Merge branch 'main' into virtual-network

Author: jurgenwerk

.github/workflows/ci.yaml

@@ -29,15 +29,16 @@ jobs:
         # This addition to each step causes the job to proceed even if one lint job fails so we can see all errors
         if: always()
         run: pnpm run lint
-        working-directory: packages/boxel-motion
-      - name: Lint Boxel Motion Test App
+        working-directory: packages/boxel-motion/addon
+      - name: Build Boxel Motion
+        # To faciliate linting of projects that depend on Boxel Motion
         if: always()
-        run: pnpm run lint
-        working-directory: packages/boxel-motion-test-app
-      - name: Lint Boxel Motion Demo App
+        run: pnpm run build
+        working-directory: packages/boxel-motion/addon
+      - name: Lint Boxel Motion Test App
         if: always()
         run: pnpm run lint
-        working-directory: packages/boxel-motion-demo-app
+        working-directory: packages/boxel-motion/test-app
       - name: Lint Boxel UI
         if: always()
         run: pnpm run lint
@@ -86,9 +87,12 @@ jobs:
     steps:
       - uses: actions/checkout@v3
       - uses: ./.github/actions/init
-      - name: Run Tests
-        run: pnpm run test:ember
-        working-directory: packages/boxel-motion-test-app
+      - name: Build boxel-motion
+        run: pnpm build
+        working-directory: packages/boxel-motion/addon
+      - name: Run test suite
+        run: pnpm test
+        working-directory: packages/boxel-motion/test-app
 
   boxel-ui-test:
     name: Boxel UI Tests

.vscode/settings.json

@@ -9,5 +9,6 @@
     "editor.defaultFormatter": "esbenp.prettier-vscode",
     "editor.formatOnSave": true
   },
-  "prettier.documentSelectors": ["**/*.gjs", "**/*.gts"]
+  "prettier.documentSelectors": ["**/*.gjs", "**/*.gts"],
+  "search.followSymlinks": false
 }

QUICKSTART.md

@@ -0,0 +1,103 @@
+# Building the Repository
+
+To build the entire repository and run the application, follow these steps:
+
+1. The 2 main system dependencies to install are:
+
+   - [volta](https://docs.volta.sh/guide/getting-started)
+   - [docker](https://docs.docker.com/get-docker/)
+   - [pnpm](https://docs.volta.sh/advanced/pnpm) Note: If you don't have pnpm already on your system, **DON'T** install pnpm manually (volta will install it for you when you call `pnpm install`).
+
+2. Clone the repo:
+
+   ```zsh
+   git clone https://github.com/cardstack/boxel.git
+   ```
+
+3. Install the package dependencies:
+
+   ```zsh
+   echo 'export VOLTA_FEATURE_PNPM=1"' >> ~/.profile && source ~/.profile
+   pnpm install
+   ```
+
+4. Build the boxel-ui:
+
+   ```zsh
+   cd ./packages/boxel-ui/addon
+   pnpm rebuild:icons
+   pnpm build
+   ```
+
+5. Build the host:
+
+   ```zsh
+   cd ./packages/host
+   pnpm start
+   ```
+
+6. Run the realm server:
+
+   ```zsh
+   cd ./packages/realm-server
+   pnpm start:all
+   ```
+
+   Note: Ensure that the realm-server is completely started by looking out for tor the test-realm indexing output.
+
+   ```zsh
+   Realm http://localhost:4202/test/ has started ({
+   "instancesIndexed": 8,
+   "instanceErrors": 0,
+   "moduleErrors": 0
+   })
+   ```
+
+7. Register ALL:
+
+   ```zsh
+   cd ./packages/matrix
+   pnpm register-all
+   ```
+
+8. Verify registration:
+
+   ```zsh
+   cd ./packages/matrix
+   pnpm start:admin
+   ```
+
+   Visit http://localhost:8080. Type in Username = "admin", Password: "password" Homeserver URL: http://localhost:8008
+
+9. Host App
+	- Visit http://localhost:4201/
+	-  Enter the registration flow and create a Boxel Account
+	- When prompted for an authentication token, type in "dev-token"
+
+10. Validate email for login
+	- Visit SMTP UI at http://localhost:5001/
+	- Validate email
+	- Go back to Host and login
+
+11. Validate email for login
+	- Visit SMTP UI at http://localhost:5001/
+	- Validate email
+	- Go back to Host and login
+
+13. Run ai bot (Optional):
+
+    ```zsh
+    cd ./packages/ai-bot
+    OPENAI_API_KEY=*** pnpm start
+    ```
+
+## Cleanup command
+
+If you experience issues, you can start from scratch by running this command
+
+```
+pnpm clear-caches
+rm -rf ./packages/matrix/synapse-data
+docker ps -a --format '{{.Names}}' | grep -E 'boxel-smtp|boxel-synapse|synapse-admin' | xargs -r docker stop
+docker ps -a --format '{{.Names}}' | grep -E 'boxel-smtp|boxel-synapse|synapse-admin' | xargs -r docker rm -v
+```

README.md

@@ -1,5 +1,7 @@
 # Boxel Runtime
 
+For a quickstart, see [here](./QUICKSTART.md)
+
 ## Setup
 
 - you will want the [Glint](https://marketplace.visualstudio.com/items?itemName=typed-ember.glint-vscode) vscode extension
@@ -23,12 +25,14 @@
 
 `packages/boxel-motion-test-app` is the test suite for boxel-motion
 
-`packages/boxel-motion-demo-app` is the demo app for boxel-motion
+`packages/boxel-motion/test-app` is the demo app for boxel-motion
 
 `packages/matrix` is the docker container for running the matrix server: synapse, as well as tests that involve running a matrix client.
 
 `packages/ai-bot` is a node app that runs a matrix client session and an OpenAI session. Matrix message queries sent to the AI bot are packaged with an OpenAI system prompt and operator mode context and sent to OpenAI. The ai bot enriches the OpenAI response and posts the response back into the matrix room.
 
+To learn more about Boxel and Cards, see our [documentation](./docs/README.md)
+
 ## Running the Host App
 
 There exists a "dev" mode in which we can use ember-cli to host the card runtime host application which includes live reloads. Additionally, you can also use the realm server to host the app, which is how it will be served in production.
@@ -81,7 +85,6 @@ Instead of running `pnpm start:base`, you can alternatively use `pnpm start:all`
 | :5001 | Mail user interface for viewing emails sent to local SMTP | ✅                  | 🚫                   |
 | :8008 | Matrix synapse server                                     | ✅                  | 🚫                   |
 
-
 #### Using `start:development`
 
 You can also use `start:development` if you want the functionality of `start:all`, but without running the test realms. `start:development` will enable you to open http://localhost:4201 and allow to select between the cards in the /base and /drafts realm.
@@ -136,12 +139,8 @@ First you must create an administrative user:
    docker exec -it boxel-synapse register_new_matrix_user http://localhost:8008 -c /data/homeserver.yaml -u admin -p your_admin_password --admin
    ```
    Alternatively, you can execute `pnpm register-test-admin` and utilize the following credentials: `user: admin` and `password: password`.
-3. Run the docker container:
-   ```
-   docker run --name synapse-admin -p 8080:80 -d awesometechnologies/synapse-admin
-   ```
 
-After you have created an administrative user and have created the docker container you can start the admin console by executing the following in the packages/matrix workspace:
+After you have created an administrative user and can start the admin console by executing the following in the packages/matrix workspace:
 
 ```
 pnpm start:admin
@@ -173,7 +172,7 @@ There is a ember-freestyle component explorer available to assist with developme
 
 In order to run the boxel-motion demo app:
 
-1. `cd packages/boxel-motion-demo-app`
+1. `cd packages/boxel-motion/test-app`
 2. `pnpm start`
 3. Visit http://localhost:4200 in your browser
 

docs/README.md

@@ -1,3 +1,21 @@
+
+# Documentation about Boxel
+
+## Prerequisites
+
 The following VS Code addon helps to visualize a .mermaid file: https://marketplace.visualstudio.com/items?itemName=tomoyukim.vscode-mermaid-editor
 
 It also has a feature to save an .svg image, which be opened in Chrome for a decent pan and zoom experience.
+
+## Concepts
+
+The following are important concepts: 
+
+- [Card and Field Definition Relationships](card-def-field-def-relationships.md): There is a subtle distinction between card and fields to consider when creating cards. 
+- [Inheritance](card-inheritance.md): Cards can be extended based upon user's custom needs -- no reinventing the wheel.  
+- [Rendering](card-rendering.md): Cards can be rendered easily in the browser. Each card renders differently based upon how it is related and what context it exists in.  
+- [Serialization and Deserialization](card-serialization-deserialization.md): Cards have to be adapted to a consistent JSON format before being sent over-the-wire to other consumers.
+- [Computed Fields](computed-fields.md): Computed fields work too! We can compute on the data that is already contained in a card to build more complex logic.   
+- [Indexing](indexing.md): Indexing powers the re-rendering of cards when it's dependencies get updated. 
+- [Realm](realm.md): Realms are storage for cards that have their own underlying permissions and indexer.
+- [Search](search.md): Every Card is searchable within and across realms.

docs/card-serialization-deserialization.md

@@ -8,9 +8,9 @@ flowchart TB
     E[LooseCardResource] -->|createFromSerialized| A
     C[JSON Storage on Realm Server] --> E
 
-    style A fill:#58D68D
+    style A fill:#63a45b
     style B fill:#3498DB
-    style C fill:#F5B041
+    style C fill:#cc3e33
     style E fill:#3498DB
 ```
 

package.json

@@ -58,7 +58,7 @@
     "hcl2-parser": "^1.0.3",
     "prettier": "^2.7.1",
     "prettier-plugin-ember-template-tag": "^1.1.0",
-    "typescript": "^5.1.6"
+    "typescript": "~5.1.6"
   },
   "engines": {
     "pnpm": "^8"

packages/ai-bot/package.json

@@ -12,7 +12,7 @@
     "stream-chain": "^2.2.5",
     "stream-json": "^1.8.0",
     "ts-node": "^10.9.1",
-    "typescript": "^5.1.6"
+    "typescript": "~5.1.6"
   },
   "devDependencies": {
     "qunit": "^2.18.0"