Inital template

.eventsourced/session.yaml

@@ -0,0 +1,73 @@
+# .eventsourced/session.yaml for Circuit's frontend template (React + Vite +
+# Tailwind, with a mock API that vite.config.ts starts). Commit it at the
+# ROOT of the template project; every initiative created from the template
+# then has a ready dev server and a published preview when its session
+# starts, instead of waiting for the agent (or the preview tab) to start one.
+# See docs/circuit-session-startup.md for the design and how to verify it.
+#
+# It runs only where the deployment sets SESSION_STARTUP=true (Circuit's does),
+# and a session can opt out with the per-session `session_startup: false`.
+# Port exposure also needs the session to be allowed network.expose, which
+# every Circuit mode allows (TestNoCircuitModeDeniesNetworkExpose).
+#
+# Why each step is written the way it is:
+#
+#  * Install only when node_modules is missing (a worker that kept its
+#    workspace volume does not reinstall), with `npm ci` when there is a
+#    lockfile and `npm install` when there is not.
+#
+#  * The dev server binds 0.0.0.0 and uses --strictPort on 5173, the port the
+#    template serves on (its README says so and vite.config.ts does not set
+#    another). Circuit's own preview start takes whatever port is published
+#    first, so the port declared here is the one the preview uses.
+#
+#  * Vite refuses requests whose Host header it does not know ("Blocked
+#    request. This host is not allowed"). The published host is
+#    <label>.<PREVIEW_DOMAIN> and does not exist yet when the server starts
+#    (the port is published after it). Circuit's own preview start tells Vite
+#    the host through __VITE_ADDITIONAL_SERVER_ALLOWED_HOSTS; here the whole
+#    suffix is allowed from PREVIEW_DOMAIN, which the orchestrator's
+#    controller passes into every worker pod. A pod without the variable (one
+#    that predates it) gets an empty value and Vite keeps its default; then
+#    restart the workspace, or set server.allowedHosts in vite.config.ts.
+#
+#  * A change conversation works in its own worktree under
+#    .circuit/worktrees/<id>, on the same worker, and Circuit swaps the
+#    running preview between the main checkout and a change when one is
+#    opened. Starting a second server on the same port (--strictPort would
+#    fail) or installing a second node_modules there would only produce a
+#    failed startup in the change's prompt, so both run steps do nothing in a
+#    worktree.
+#
+#  * disable_in_subagent on every step: a spawned subagent shares its
+#    parent's checkout and must not install or serve again.
+#
+# `exec` makes the named background process the dev server itself, so the
+# agent's process tool (list / read / write / kill / spawn) acts on it
+# directly.
+
+notes: |
+  The app's Vite dev server is already running as the background process
+  "dev" on port 5173, and that port is published: the live preview works
+  without you starting anything. Do not start a second dev server on that
+  port.
+  - Vite reloads on every file write and restarts itself when vite.config.ts
+    changes; the mock API (mock/server.mjs) is started by vite.config.ts in
+    the same process, so there is no separate step for it.
+  - After you add or remove a dependency, run `npm install`, then restart
+    "dev": kill "dev" with the process tool, then spawn "dev" again with
+    exactly this command:
+      __VITE_ADDITIONAL_SERVER_ALLOWED_HOSTS=${PREVIEW_DOMAIN:+.$PREVIEW_DOMAIN} npm run dev -- --host 0.0.0.0 --port 5173 --strictPort
+  - A change conversation works in its own worktree. Circuit starts the
+    preview there when it is asked for, so none of these steps run in a
+    worktree.
+startup:
+  - run: 'case "$(pwd -P)" in */.circuit/worktrees/*) echo "change worktree: Circuit starts its own preview"; exit 0;; esac; test -d node_modules || { if [ -f package-lock.json ]; then npm ci --no-audit --no-fund; else npm install --no-audit --no-fund; fi; }'
+    timeout_seconds: 900
+    disable_in_subagent: true
+  - run: 'case "$(pwd -P)" in */.circuit/worktrees/*) exit 0;; esac; __VITE_ADDITIONAL_SERVER_ALLOWED_HOSTS=${PREVIEW_DOMAIN:+.$PREVIEW_DOMAIN} exec npm run dev -- --host 0.0.0.0 --port 5173 --strictPort'
+    background: dev
+    disable_in_subagent: true
+  - expose: 5173
+    name: preview
+    disable_in_subagent: true