# .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