triggershell/docs/ARCHITECTURE.md

Architecture

 triggershell (Python CLI)                     app/ (Next.js, all server logic)
 ───────────────────────                       ──────────────────────────────
 triggershell dev|start                         server.ts (custom Node server)
   1. resolve + pre-flight the config              ├─ Next.js request handler (pages, API routes)
   2. check node/pnpm, `pnpm install` if stale      ├─ ws.WebSocketServer on /ws/runs
   3. set TRIGGERSHELL_CONFIG_PATH/PORT/HOST env    └─ boot: migrate DB, sync auth, reconcile runs
   4. spawn `pnpm run dev|start`, forward signals
   5. poll /api/healthz, open browser                        │
                                                    ┌──────────┴──────────┐
                                              REST API                 WebSocket
                                          (src/app/api/**)          (src/lib/ws/server.ts)
                                                    │                       │
                                                    └───────────┬───────────┘
                                                                │
                                                    src/lib/runner/engine.ts
                                                       execa(argv, env) — never a shell string
                                                                │
                                                    child process (the configured script)

Why a custom Node server

Next.js Route Handlers can't host a persistent WebSocket server, so app/server.ts wraps Next's request handler in a plain http.createServer and attaches a ws.WebSocketServer via the upgrade event, scoped to /ws/runs with its own auth check (Route Handlers get auth via next/headers's cookies(), which isn't available on a raw http.IncomingMessage).

Why the Python CLI is thin

Everything Node/pnpm/Next.js needs to do (serve pages, run scripts, stream output, enforce auth) is naturally a Node problem — execa for argv-safe spawning, ws for streaming, Next for the UI. Python's job is just: get Node/pnpm ready, validate the config fast, and manage the child process's lifecycle (signals, readiness, browser launch) — a CLI concern, not a web-server concern.

Cross-module-graph state

Next compiles Route Handlers and Server Components through its own build/module graph, which is a separate module instantiation from whatever server.ts imports directly via tsx at startup — even though both run in the same OS process. A plain module-level singleton (e.g. new Map() at the top of a file) ends up duplicated, one copy per graph, which silently breaks anything that needs to be shared across that boundary (the WebSocket subscriber registry, the live-run-handle registry used for cancellation, the config/DB singletons). These are anchored on globalThis instead, which is the one truly process-wide object regardless of which graph loaded the file — see the comment in src/lib/runner/events.ts for the canonical explanation.

Run lifecycle

queued → running → succeeded | failed | cancelled | timed_out
                  ↘ interrupted   (set at boot for any row still queued/running - see below)

• src/lib/runner/build-args.ts turns validated variable values into {argv, env, stdin} per each variable's passAs — this is the only place variable values become process arguments, and it never builds a shell string.
• src/lib/runner/engine.ts spawns via execa, streams stdout/stderr chunks to both the run's log file (logs.dir/<runId>.log) and runEvents (for WS broadcast), and updates the runs row's status as the child process progresses.
• src/lib/runner/registry.ts holds an in-memory Map<runId, {controller: AbortController}> for live runs, used to route a cancel request (REST or WS) to the right process. This can't survive a restart, so reconcileOrphanedRuns() marks any DB row still queued/running at boot as interrupted — its output can't be re-attached, only its final state corrected.

Auth

• Session: iron-session — a stateless, encrypted+signed cookie (no session-store table).
• Config is the source of truth for who is allowed in; src/lib/auth/sync.ts upserts config users/tokens into SQLite on boot, giving a single DB-backed check path plus lastLoginAt tracking.
• src/proxy.ts (Next's Proxy, formerly "Middleware") does a fast, cookie-only redirect for unauthenticated page/API requests — explicitly not the real security boundary. Every Route Handler also calls requireAuth() itself; this is the actual auth check.
• The WS upgrade handler is outside Next's request pipeline entirely, so it authenticates by hand (parsing the cookie header, or a ?token= query param) via authenticateUpgrade().

Build-time vs. runtime config

Every server file that reads the config/DB at request time (getConfig(), getDb(), requireAuth()) sets export const dynamic = "force-dynamic". Without it, next build tries to statically prerender pages like / at build time, which fails because there's no config file to read yet (the config only exists at triggershell start runtime, in the user's own project directory, not app/'s).