Hoist artifacts to top level software factory workspace and incorporate tests

.github/workflows/ci.yaml

@@ -29,6 +29,7 @@ jobs:
       boxel-ui: ${{ steps.filter.outputs.boxel-ui }}
       matrix: ${{ steps.filter.outputs.matrix }}
       realm-server: ${{ steps.filter.outputs.realm-server }}
+      software-factory: ${{ steps.filter.outputs.software-factory }}
       vscode-boxel-tools: ${{ steps.filter.outputs.vscode-boxel-tools }}
       workspace-sync-cli: ${{ steps.filter.outputs.workspace-sync-cli }}
       # Force all tests to run when on ci-bisect* branches
@@ -96,6 +97,15 @@ jobs:
               - 'packages/eslint-plugin-boxel/**'
               - 'packages/postgres/**'
               - 'packages/realm-server/**'
+            software-factory:
+              - *shared
+              - 'packages/base/**'
+              - 'packages/boxel-icons/**'
+              - 'packages/host/**'
+              - 'packages/matrix/**'
+              - 'packages/postgres/**'
+              - 'packages/realm-server/**'
+              - 'packages/software-factory/**'
             vscode-boxel-tools:
               - *shared
               - 'packages/vscode-boxel-tools/**'
@@ -111,7 +121,7 @@ jobs:
   test-web-assets:
     name: Build test web assets
     needs: change-check
-    if: needs.change-check.outputs.boxel == 'true' || needs.change-check.outputs.boxel-ui == 'true' || needs.change-check.outputs.matrix == 'true' || needs.change-check.outputs.realm-server == 'true' || needs.change-check.outputs.vscode-boxel-tools == 'true' || needs.change-check.outputs.workspace-sync-cli == 'true' || github.ref == 'refs/heads/main' || needs.change-check.outputs.run_all == 'true'
+    if: needs.change-check.outputs.boxel == 'true' || needs.change-check.outputs.boxel-ui == 'true' || needs.change-check.outputs.matrix == 'true' || needs.change-check.outputs.realm-server == 'true' || needs.change-check.outputs.software-factory == 'true' || needs.change-check.outputs.vscode-boxel-tools == 'true' || needs.change-check.outputs.workspace-sync-cli == 'true' || github.ref == 'refs/heads/main' || needs.change-check.outputs.run_all == 'true'
     uses: ./.github/workflows/test-web-assets.yaml
 
   ai-bot-test:
@@ -633,6 +643,56 @@ jobs:
           path: /tmp/test-realms.log
           retention-days: 30
 
+  software-factory-test:
+    name: Software Factory Tests
+    needs: [change-check, test-web-assets]
+    if: needs.change-check.outputs.software-factory == 'true' || github.ref == 'refs/heads/main' || needs.change-check.outputs.run_all == 'true'
+    runs-on: ubuntu-latest
+    concurrency:
+      group: software-factory-test-${{ github.head_ref || github.run_id }}
+      cancel-in-progress: true
+    steps:
+      - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # 4.2.2
+      - uses: ./.github/actions/init
+      - name: Download test web assets
+        uses: actions/download-artifact@b14cf4c92620c250e1c074ab0a5800e37df86765 # 4.2.0
+        with:
+          name: ${{ needs.test-web-assets.outputs.artifact_name }}
+          path: .test-web-assets-artifact
+      - name: Restore test web assets into workspace
+        shell: bash
+        run: |
+          shopt -s dotglob
+          cp -a .test-web-assets-artifact/. ./
+      - name: Install Playwright Browsers
+        run: pnpm exec playwright install
+        working-directory: packages/software-factory
+      - name: Serve host dist (test assets)
+        uses: JarvusInnovations/background-action@2428e7b970a846423095c79d43f759abf979a635 # 1.0.7
+        with:
+          run: pnpm serve:dist &
+          working-directory: packages/host
+          wait-for: 3m
+          wait-on: http-get://localhost:4200
+      - name: Serve boxel-icons
+        uses: JarvusInnovations/background-action@2428e7b970a846423095c79d43f759abf979a635 # 1.0.7
+        with:
+          run: pnpm serve &
+          working-directory: packages/boxel-icons
+          wait-for: 3m
+          wait-on: http-get://localhost:4206/@cardstack/boxel-icons/v1/icons/code.js
+      - name: Run Playwright tests
+        run: pnpm test:playwright
+        working-directory: packages/software-factory
+      - name: Upload Playwright traces
+        if: ${{ !cancelled() }}
+        uses: actions/upload-artifact@4cec3d8aa04e39d1a68397de0c4cd6fb9dce8ec1 # 4.6.1
+        with:
+          name: software-factory-playwright-traces
+          path: packages/software-factory/test-results/**/trace.zip
+          retention-days: 30
+          if-no-files-found: ignore
+
   vscode-boxel-tools-package:
     name: Boxel Tools VS Code Extension package
     needs: [change-check, test-web-assets]

packages/matrix/docker/index.ts

@@ -2,11 +2,7 @@ import * as os from 'os';
 import * as childProcess from 'child_process';
 import * as fse from 'fs-extra';
 
-function dockerPull(
-  image: string,
-  retries = 3,
-  delayMs = 5000,
-): Promise<void> {
+function dockerPull(image: string, retries = 3, delayMs = 5000): Promise<void> {
   return new Promise<void>((resolve, reject) => {
     let attempt = 0;
     function tryPull() {
@@ -151,8 +147,8 @@ export async function dockerLogs(args: {
       .once('close', resolve);
   });
 
-  if (args.stdoutFile) await fse.close(<number>stdoutFile);
-  if (args.stderrFile) await fse.close(<number>stderrFile);
+  if (args.stdoutFile) await fse.close(stdoutFile as number);
+  if (args.stderrFile) await fse.close(stderrFile as number);
 }
 
 export function dockerStop(args: { containerId: string }): Promise<void> {

packages/matrix/docker/synapse/index.ts

@@ -129,7 +129,11 @@ export async function synapseStart(
     opts?.template ?? 'test',
     opts?.dataDir,
   );
-  let containerName = opts?.containerName || (isEnvironmentMode() ? getSynapseContainerName() : path.basename(synCfg.configDir));
+  let containerName =
+    opts?.containerName ||
+    (isEnvironmentMode()
+      ? getSynapseContainerName()
+      : path.basename(synCfg.configDir));
   console.log(
     `Starting synapse with config dir ${synCfg.configDir} in container ${containerName}...`,
   );
@@ -381,7 +385,13 @@ export interface UpdateUserOptions {
 export async function updateUser(
   adminAccessToken: string,
   userId: string,
-  { password, displayname, avatar_url, emailAddresses, matrixURL }: UpdateUserOptions,
+  {
+    password,
+    displayname,
+    avatar_url,
+    emailAddresses,
+    matrixURL,
+  }: UpdateUserOptions,
 ) {
   let url = matrixURL
     ? `${matrixURL}/_synapse/admin/v2/users/${userId}`
@@ -506,14 +516,11 @@ export async function getRoomMembers(roomId: string, accessToken: string) {
 }
 
 export async function sync(accessToken: string) {
-  let response = await fetch(
-    `${getSynapseURL()}/_matrix/client/v3/sync`,
-    {
-      headers: {
-        Authorization: `Bearer ${accessToken}`,
-      },
+  let response = await fetch(`${getSynapseURL()}/_matrix/client/v3/sync`, {
+    headers: {
+      Authorization: `Bearer ${accessToken}`,
     },
-  );
+  });
   return await response.json();
 }
 

packages/matrix/helpers/isolated-realm-server.ts

@@ -138,18 +138,23 @@ export async function startPrerenderServer(
 ): Promise<RunningPrerenderServer> {
   let port = await findAvailablePort(options?.port ?? DEFAULT_PRERENDER_PORT);
   let url = `http://localhost:${port}`;
+  let silent = process.env.SOFTWARE_FACTORY_PRERENDER_SILENT !== '0';
   let env = {
     ...process.env,
     NODE_ENV: process.env.NODE_ENV ?? 'development',
     NODE_NO_WARNINGS: '1',
     BOXEL_HOST_URL: process.env.HOST_URL ?? 'http://localhost:4200',
+    LOG_LEVELS:
+      process.env.SOFTWARE_FACTORY_PRERENDER_LOG_LEVELS ?? process.env.LOG_LEVELS,
   };
   let prerenderArgs = [
     '--transpileOnly',
     'prerender/prerender-server',
     `--port=${port}`,
-    '--silent',
   ];
+  if (silent) {
+    prerenderArgs.push('--silent');
+  }
 
   let child = spawn('ts-node', prerenderArgs, {
     cwd: realmServerDir,

packages/realm-server/main.ts

@@ -89,6 +89,8 @@ if (process.env.DISABLE_MODULE_CACHING === 'true') {
 }
 
 const ENABLE_FILE_WATCHER = process.env.ENABLE_FILE_WATCHER === 'true';
+const FULL_INDEX_ON_STARTUP =
+  process.env.REALM_SERVER_FULL_INDEX_ON_STARTUP !== 'false';
 
 let {
   port,
@@ -240,7 +242,7 @@ let autoMigrate = migrateDB || undefined;
 log.info(
   `Realm server boot config: port=${port} serverURL=${serverURL} distURL=${distURL} matrixURL=${matrixURL} realmsRootPath=${realmsRootPath} migrateDB=${Boolean(
     migrateDB,
-  )} workerManagerPort=${workerManagerPort ?? 'none'} prerendererUrl=${prerendererUrl} enableFileWatcher=${ENABLE_FILE_WATCHER}`,
+  )} workerManagerPort=${workerManagerPort ?? 'none'} prerendererUrl=${prerendererUrl} enableFileWatcher=${ENABLE_FILE_WATCHER} fullIndexOnStartup=${FULL_INDEX_ON_STARTUP}`,
 );
 log.info(`Realm paths: ${paths.map(String).join(', ')}`);
 
@@ -323,7 +325,7 @@ const getIndexHTML = async () => {
         ),
       },
       {
-        fullIndexOnStartup: true,
+        ...(FULL_INDEX_ON_STARTUP ? { fullIndexOnStartup: true as const } : {}),
         ...(process.env.DISABLE_MODULE_CACHING === 'true'
           ? { disableModuleCaching: true }
           : {}),
@@ -388,24 +390,27 @@ const getIndexHTML = async () => {
       registerService(httpServer, serviceName, { wildcardSubdomains: true });
     }
   });
+  let stopRealmServer = (notifyParent = false) => {
+    let stopPort =
+      (httpServer.address() as import('net').AddressInfo | null)?.port ?? port;
+    console.log(`stopping realm server on port ${stopPort}...`);
+    if (isEnvironmentMode()) {
+      deregisterEnvironment();
+    }
+    httpServer.closeAllConnections();
+    httpServer.close(() => {
+      queue.destroy(); // warning this is async
+      dbAdapter.close(); // warning this is async
+      console.log(`realm server on port ${stopPort} has stopped`);
+      if (notifyParent && process.send) {
+        process.send('stopped');
+      }
+      process.exit(0);
+    });
+  };
   process.on('message', (message) => {
     if (message === 'stop') {
-      let stopPort =
-        (httpServer.address() as import('net').AddressInfo | null)?.port ??
-        port;
-      console.log(`stopping realm server on port ${stopPort}...`);
-      if (isEnvironmentMode()) {
-        deregisterEnvironment();
-      }
-      httpServer.closeAllConnections();
-      httpServer.close(() => {
-        queue.destroy(); // warning this is async
-        dbAdapter.close(); // warning this is async
-        console.log(`realm server on port ${stopPort} has stopped`);
-        if (process.send) {
-          process.send('stopped');
-        }
-      });
+      stopRealmServer(true);
     } else if (message === 'kill') {
       console.log(`Ending server process...`);
       process.exit(0);
@@ -437,6 +442,10 @@ const getIndexHTML = async () => {
         });
     }
   });
+  process.on('disconnect', () => {
+    console.log(`realm server IPC disconnected, shutting down...`);
+    stopRealmServer(false);
+  });
 
   await server.start();
 

packages/realm-server/tests/helpers/index.ts

@@ -208,8 +208,22 @@ export const realmServerTestMatrix: MatrixConfig = {
 export const realmServerSecretSeed = "mum's the word";
 export const realmSecretSeed = `shhh! it's a secret`;
 export const grafanaSecret = `shhh! it's a secret`;
-export const matrixRegistrationSecret: string =
-  getSynapseConfig()!.registration_shared_secret; // as long as synapse has been started at least once, this will always exist
+
+function getMatrixRegistrationSecret(): string {
+  let secret =
+    getSynapseConfig()?.registration_shared_secret ??
+    process.env.MATRIX_REGISTRATION_SHARED_SECRET;
+
+  if (!secret) {
+    throw new Error(
+      'Missing Matrix registration shared secret. Start Synapse first or set MATRIX_REGISTRATION_SHARED_SECRET.',
+    );
+  }
+
+  return secret;
+}
+
+export const matrixRegistrationSecret = getMatrixRegistrationSecret();
 export const testCreatePrerenderAuth =
   buildCreatePrerenderAuth(realmSecretSeed);
 

packages/realm-server/worker-manager.ts

@@ -271,6 +271,10 @@ const shutdown = (onShutdown?: () => void) => {
 
 process.on('SIGINT', () => shutdown());
 process.on('SIGTERM', () => shutdown());
+process.on('disconnect', () => {
+  log.info(`Parent IPC disconnected, shutting down worker manager...`);
+  shutdown();
+});
 process.on('uncaughtException', (err) => {
   log.error(`Uncaught exception in worker manager:`, err);
   shutdown();

packages/realm-server/worker.ts

@@ -166,6 +166,7 @@ let autoMigrate = migrateDB || undefined;
   };
   process.on('SIGINT', shutdown);
   process.on('SIGTERM', shutdown);
+  process.on('disconnect', shutdown);
   process.on('message', (message) => {
     if (message === 'stop') {
       shutdown(); // warning this is async

packages/software-factory/.agents/skills/boxel-development/SKILL.md

@@ -0,0 +1,66 @@
+---
+name: boxel-development
+description: Use when working on Boxel card development, especially creating or editing `.gts` card definitions, `.json` card instances, Boxel commands, themes, queries, templates, or related Boxel patterns in a synced workspace. Read the targeted files in `references/` instead of loading broad guidance by default.
+---
+
+# Boxel Development
+
+Use this skill for Boxel card and app development. Keep the top-level guidance lean and load only the references needed for the task.
+
+## Core Workflow
+
+1. Confirm whether the task is about a card definition, card instance, query, command, theme, file asset, or styling.
+2. Read only the specific reference files that match the task.
+3. For file placement, naming, or `adoptsFrom.module` paths, also read `../boxel-file-structure/SKILL.md`.
+4. Apply the rules from the relevant references exactly when they are marked critical.
+5. Ignore Boxel in-app editor instructions unless you are explicitly operating inside that environment. In this repo, prefer normal filesystem edits and CLI workflows.
+
+## Always Load First
+
+- `references/dev-core-concept.md`
+- `references/dev-technical-rules.md`
+- `references/dev-quick-reference.md`
+
+These three files establish the data model, the `contains` vs `linksTo` rule, required formats, inherited fields, and common import patterns.
+
+## Load By Task
+
+- Card structure and safe patterns:
+  `references/dev-core-patterns.md`
+- Templates, delegated rendering, and field access:
+  `references/dev-template-patterns.md`
+  `references/dev-delegated-rendering.md`
+- Styling and themes:
+  `references/dev-theme-design-system.md`
+  `references/dev-styling-design.md`
+  `references/dev-fitted-formats.md`
+- Queries and data linking:
+  `references/dev-query-systems.md`
+  `references/dev-data-management.md`
+- File-backed content and file asset cards:
+  `references/dev-file-def.md`
+- Enum fields:
+  `references/dev-enumerations.md`
+- Defensive component logic:
+  `references/dev-defensive-programming.md`
+- Third-party libraries:
+  `references/dev-external-libraries.md`
+- Command implementation:
+  `references/dev-command-development.md`
+- Spec usage:
+  `references/dev-spec-usage.md`
+- Replicate integration:
+  `references/dev-replicate-ai.md`
+
+## Usually Ignore Unless Explicitly Relevant
+
+- `references/dev-file-editing.md`
+  This is primarily for Boxel's in-app AI editing flow, not normal terminal-based editing.
+
+## Key Reminders
+
+- `CardDef` and `FileDef` references use `linksTo` / `linksToMany`.
+- `FieldDef` values use `contains` / `containsMany`.
+- Modern cards should implement `isolated`, `embedded`, and `fitted`.
+- Be precise with relative JSON module paths.
+- Prefer loading one or two reference files over reading the whole reference set.