specrails-desktop 2.0.0

package/docs/getting-started.md

@@ -0,0 +1,140 @@
+# Getting started
+
+This guide walks you from "I just heard about specrails-desktop" to "I just shipped my first AI-driven change" in about ten minutes. No prior knowledge of specrails-core required — the app installs it for you.
+
+## What you'll need
+
+- **An AI CLI signed in** — either [Claude Code](https://claude.com/claude-code) (via Claude subscription login or an `ANTHROPIC_API_KEY`) or the Codex CLI. You can use one or both — see [Codex](codex.md).
+- A project you want to work on (any Git repository works)
+
+If you install with **npm** (Option 2 below) you'll also need **Node.js 20+** and **`git`** on your PATH. The **desktop app** bundles its own Node and Git runtimes, so you don't need those installed separately.
+
+That's it. specrails-desktop will install specrails-core in your project on first run if it isn't there yet.
+
+## Install
+
+Two options:
+
+### Option 1 — Desktop app (recommended)
+
+Download a signed build for your OS from `https://specrails.dev/downloads/specrails-desktop/latest/`:
+
+- **macOS** — `specrails-desktop-<version>-aarch64.dmg` (Apple Silicon, notarised)
+- **Windows** — `specrails-desktop-<version>-x64-setup.exe` (NSIS) or `.msi`
+
+Open the installer, drag to Applications (macOS) or click through the wizard (Windows). The app bundles the server, so you don't need a separate process. macOS handles all the Homebrew/Volta/nvm PATH gymnastics for you — see [platforms/macos.md](platforms/macos.md) if anything looks off.
+
+> First Windows launch shows a SmartScreen warning until the installer is code-signed. Click **More info → Run anyway**. Details and hash-verification steps in [platforms/windows.md](platforms/windows.md).
+
+### Option 2 — npm
+
+```bash
+npm install -g specrails-desktop
+specrails-desktop start
+```
+
+By default the app binds to `http://127.0.0.1:4200`. Open it in your browser.
+
+## Add a project
+
+There are two ways. Pick whichever feels natural.
+
+**From the dashboard:**
+
+1. Click **+** in the left sidebar.
+2. Enter the absolute path to your project (e.g. `/Users/you/repos/my-app`).
+3. Pick your **AI providers**. Check **Claude**, **Codex**, or both — when you select both, the first one becomes the project default. The provider set is fixed once the project is created.
+4. The prerequisites panel verifies `node`, `npm`, `npx`, `git`. If anything's missing, the panel surfaces OS-aware install commands you can copy.
+5. Click **Add**.
+
+**From the CLI:**
+
+```bash
+specrails-desktop add /path/to/your/project
+specrails-desktop list   # verify
+```
+
+### If the project doesn't have specrails-core yet
+
+The setup wizard runs automatically. Three steps:
+
+1. **Configure** — choose which agents to install (the baseline trio `sr-architect`, `sr-developer`, `sr-reviewer` is always selected; optional agents like Test Writer or Security Reviewer are opt-in). Pick a model preset (Balanced / Budget / Max) and optionally override the model per agent.
+2. **Install** — the app runs the installer (`npx specrails-core@latest init --yes --from-config <config>`) non-interactively and streams the output live.
+3. **Done** — a summary tells you how many agents and commands landed. Click **Continue to project**.
+
+That's the whole onboarding. No tier picker, no second wizard. You can manage agents and their per-agent models later from the **Agents** page (Profiles tab).
+
+## Your first spec
+
+A "spec" is a description of work you want done. specrails-desktop gives you two ways to author them.
+
+### Quick mode — one-shot generation
+
+When you already know what you want:
+
+1. On the Dashboard, click **+ Add Spec → Quick**.
+2. Type a one-line title (e.g. *"Add a webhook retry with exponential backoff"*).
+3. (Optional) toggle **Enrich with Contract Layer** to get a structured block of names, data shapes, invariants, and a file touch list appended to the description.
+4. Hit Enter.
+
+Your AI CLI generates the full spec in one turn. A small toast at the bottom right shows the project, the spec title, and live elapsed time ("Generating… 0:12") — it turns into a success or failure toast (with a **View** action) when generation finishes.
+
+### Explore mode — converse with the AI
+
+When the spec needs shaping:
+
+1. Click **+ Add Spec → Explore**.
+2. (Optional) pick a context preset from the slider — `Minimal` (just your message) up to `Desktop` (the full codebase + Contract Layer enrichment + project and user-approved MCPs).
+3. Type a starting message. The AI responds with a live draft below.
+4. Iterate. Each turn updates the draft.
+5. Click **Save as Draft** to come back later, or **Create Spec** when the draft looks right.
+
+The committed spec lands on your board with status `todo`.
+
+## Run your first pipeline
+
+The right pane of the Dashboard is your **Rails** — execution lanes:
+
+1. Drag a spec card from the left pane onto a Rail.
+2. (Optional) pick an **agent profile** from the rail header. This picker only appears once the project has profiles (create them on the **Agents** page); otherwise the rail runs in legacy mode (single orchestrator, no per-agent overrides).
+3. Press **▶ Play** on the rail.
+
+The rail flips to running. The Jobs page (right sidebar) streams the AI's output live. When the slash command defines them, you'll see the pipeline phases progress: Architect → Developer → Reviewer → Ship.
+
+Token usage, duration, and cost are tracked per turn and surface in:
+
+- **Jobs page** — each job has a status panel with live counters and a `JobTicketHeader` chip for every ticket the job touched (click to open).
+- **Analytics page** — burn rate, top tickets, daily timeline (see [Tracking cost](tracking-cost.md)).
+- **The spec's detail modal** — a one-line spending summary linking back to Analytics filtered by that ticket.
+
+## What's next?
+
+- **[Creating specs](creating-specs.md)** — drafts, SMASH (decompose epics), Continue Editing (refine specs in place), Compare (side-by-side review).
+- **[Running pipelines](running-pipelines.md)** — agent profiles, plugins (Serena), telemetry export.
+- **[Tracking cost](tracking-cost.md)** — analytics deep dive and CSV exports.
+- **[Codex](codex.md)** — using the Codex CLI as a provider, alongside or instead of Claude.
+- **[Terminal panel](terminal.md)** — the built-in per-project terminal (toggle with `Cmd/Ctrl+J`).
+- **[Customising the app](customizing.md)** — themes, terminal settings, kill switches.
+- **[CLI reference](cli.md)** — drive specrails-desktop from the terminal.
+
+## Troubleshooting
+
+**"Port 4200 already in use" on start**
+
+```bash
+specrails-desktop stop                # stops the running server cleanly
+# or kill the process holding the port
+lsof -i :4200    # macOS / Linux
+```
+
+**The `claude` command isn't found inside the app**
+
+On macOS, this usually means the app was launched from Finder/Dock and didn't pick up Homebrew/Volta paths. The app fixes this at startup automatically, but if it still fails, see [platforms/macos.md](platforms/macos.md).
+
+**The setup wizard fails on `npx specrails-core@latest init`**
+
+Most likely Node is missing from the shell environment that launched the app, or your AI CLI isn't authenticated (sign in to the `claude` CLI or set `ANTHROPIC_API_KEY`; for Codex, sign in to the `codex` CLI). Click **Copy diagnostics** in the install-instructions modal — that prints the resolved PATH, where the app found each tool, and login-shell status. Paste it into a bug report if you can't figure it out.
+
+**More**
+
+Operational issues (port conflicts, stale PID files, database corruption) are covered in the [Operations runbook](internals/operations-runbook.md).

package/docs/internals/README.md

@@ -0,0 +1,25 @@
+# Internals
+
+These docs are primarily for contributors and people building on the app's API. They mostly describe how the app works under the hood — though a couple (like the profiles quick start) double as practical how-tos.
+
+If you're a user looking for **how do I do X?** docs, head back to the [user guides](../README.md).
+
+## Contents
+
+| Doc | What it covers |
+|-----|----------------|
+| [architecture.md](architecture.md) | Server modules, client layout, WebSocket protocol, process spawning, security model |
+| [api-reference.md](api-reference.md) | REST endpoint catalogue under `/api/*` and `/api/projects/:projectId/*` |
+| [configuration.md](configuration.md) | Settings, env vars, kill switches, advanced flags |
+| [operations-runbook.md](operations-runbook.md) | Start/stop, port conflicts, recovery procedures, backups |
+| [openspec-workflow.md](openspec-workflow.md) | `opsx:*` change lifecycle — used by the app itself for structured change management |
+| [adding-a-provider.md](adding-a-provider.md) | How to add a new AI CLI: one adapter file plus one entry in the registry |
+| [profiles.md](profiles.md) | Agent profiles quick start: open the Agents section, pick a profile per rail at launch, author custom agents in Agent Studio. For the true file-format and snapshotting internals, read `server/profile-manager.ts` and the profile-manager section of `CLAUDE.md` |
+
+**See also:** [`../codex.md`](../codex.md) for the multi-provider model (Claude Code + Codex CLI as first-class engines).
+
+## Contributing
+
+For coding conventions, file naming, the coverage policy, and how WebSocket handlers are expected to be wired, see [`CLAUDE.md`](../../CLAUDE.md) at the repo root. That file is the authoritative source for project-wide rules.
+
+When adding a feature, follow the OpenSpec workflow: `/opsx:new → /opsx:ff → /opsx:apply → /opsx:verify → /opsx:archive`. The `/opsx:*` invocations resolve to command files under `.claude/commands/opsx/*.md` (the related skills under `.claude/skills/` are named `openspec-*`).

package/docs/internals/adding-a-provider.md

@@ -0,0 +1,238 @@
+# Adding a new AI provider to Specrails
+
+The app is provider-agnostic by design. Every manager that spawns an AI
+CLI consumes a `ProviderAdapter` rather than branching on a hardcoded
+`if (provider === 'claude')`. Adding a new provider is mostly one adapter
+file plus one entry in the registry — but the codebase still carries a
+handful of `'claude' | 'codex'` type unions and two hardcoded provider
+lists that you must widen by hand today. Those are tracked in the
+**Type-union widening** and **Manual wiring still required** sections
+below.
+
+If you find yourself wanting to write `if (this._provider === 'X')` in
+a manager, **the design has drifted** — find the capability you're
+gating on, add a flag to `ProviderCapabilities`, and branch on the
+flag instead.
+
+## The recipe
+
+### 1. Implement the adapter
+
+Create `server/providers/<id>-adapter.ts` exporting a `const` of type
+`ProviderAdapter`:
+
+```ts
+import type { ProviderAdapter, SpawnAction, SpawnOptions, AdapterEvent, NormalisedResult, DetectionResult } from './types'
+
+const MODELS = [
+  { value: 'flagship', label: 'Provider X Flagship', default: true as const },
+  { value: 'fast',     label: 'Provider X Fast' },
+] as const
+
+export const exampleAdapter: ProviderAdapter = {
+  id: 'example',
+  displayName: 'Example CLI',
+  binary: 'example',
+  minCliVersion: '1.0.0',
+  projectDirName: '.example',
+  instructionsFilename: 'EXAMPLE.md',
+  mcpRegistration: 'cli-add', // or 'project-json'
+  capabilities: {
+    nativeResume: true,
+    nativeStreamJson: true,
+    nativeCostUsd: false,    // if false, add the provider:model entries to server/pricing.ts
+    nativeOtelEnv: false,    // if false, the app will synthesise OTEL via the bridge
+    profileEnvSupport: true,
+    systemPromptArg: false,
+  },
+  modelCatalog: () => MODELS,
+  defaultModel: () => 'flagship',
+  buildArgs: (action: SpawnAction, opts: SpawnOptions): string[] => { /* per-action argv */ },
+  parseStreamLine: (line: string): AdapterEvent | null => { /* line → canonical event */ },
+  extractResult: (events): NormalisedResult => { /* events → tokens/cost/session */ },
+  baselineAgents: () => ['sr-architect', 'sr-developer', 'sr-reviewer'],
+  detectInstalled: async (): Promise<DetectionResult> => { /* `which` + `--version` */ },
+}
+```
+
+The `ProviderAdapter` interface is documented in
+`server/providers/types.ts`. Read the existing
+`server/providers/{claude,codex}-adapter.ts` for the patterns —
+`SpawnAction` shapes per provider, `text-delta` event normalisation
+across native JSONL formats, etc. Note the shipped baseline is the
+three-agent trio `['sr-architect', 'sr-developer', 'sr-reviewer']`;
+`ProfileManager` validation requires exactly your `baselineAgents()` to
+be present in every profile chain, so don't add agents your scaffold
+won't actually create.
+
+`parseStreamLine` returns `null` for empty input lines **and** for lines
+that fail `JSON.parse` (see `server/providers/codex-adapter.ts`); unknown
+JSON event types resolve to `{ kind: 'other' }`. Write your tests
+accordingly — don't assume null-only-on-empty.
+
+### 2. Register it
+
+Append the import to `server/providers/index.ts`:
+
+```ts
+import { register } from './registry'
+import { claudeAdapter } from './claude-adapter'
+import { codexAdapter } from './codex-adapter'
+import { exampleAdapter } from './example-adapter' // ← add this
+
+register(claudeAdapter)
+register(codexAdapter)
+register(exampleAdapter) // ← and this
+```
+
+**Truly automatic** (these walk the registry, so they pick up the new
+provider with zero edits):
+
+- `getAdapter` / `listAdapters` / `hasAdapter` (`server/providers/registry.ts`).
+- `detectAvailableCLIs` (`server/core-compat.ts`).
+- `POST /api/projects` provider validation (`server/desktop-router.ts`,
+  via `hasAdapter` / `listAdapters`).
+- `setup-prerequisites` provider rows (`server/setup-prerequisites.ts`,
+  iterates `listAdapters()`).
+- Analytics `byProvider` (`server/spending.ts`) and the
+  `ProviderBreakdownCard` (`client/src/components/analytics/ProviderBreakdownCard.tsx`).
+
+**Manual wiring still required** (these hardcode `claude` / `codex`
+today and will NOT surface a 4th provider until edited):
+
+- `GET /api/available-providers` (`server/desktop-router.ts`) returns a
+  literal `{ claude, codex }` shape — add your key.
+- `AddProjectDialog` (`client/src/components/AddProjectDialog.tsx`)
+  hardcodes `PROVIDER_ORDER = ['claude', 'codex']` and reads
+  `data.claude` / `data.codex` explicitly. Without editing it the
+  provider won't appear in the Add Project UI.
+- `providerInstallUrl` / `providerInstallHint`
+  (`server/setup-prerequisites.ts`) have generic `default:` fallbacks so
+  nothing crashes, but a good install hint needs a `case` for your id.
+
+### Type-union widening
+
+A 4th provider is a **compile-time blocker** until you widen the
+`'claude' | 'codex'` unions still scattered across the server. The build
+fails until they're widened (or migrated to a shared `ProviderId`):
+
+- `CliProvider` (`server/desktop-db.ts`) — the canonical project-row provider type.
+- `SpecProvider` (`server/spec-models.ts`).
+- The inline `'claude' | 'codex'` unions in `server/queue-manager.ts`
+  (`EnqueueOptions.provider`, `_jobProviderSelection`),
+  `server/chat-manager.ts`, `server/agent-refine-manager.ts`, and
+  `server/project-registry.ts`.
+
+Expect to widen roughly eight unions. The long-term goal is to delete
+them in favour of a single `ProviderId` derived from the registry — if
+you add a new hardcoded site instead of widening the existing ones, file
+an OpenSpec change first (see the closing section).
+
+### 3. (If `nativeCostUsd === false`) add pricing entries
+
+For providers that don't report `total_cost_usd` in their terminal
+event, append the rate card to `server/pricing.ts`:
+
+```ts
+'example:flagship': { inputPer1M: 5.00, outputPer1M: 15.00, cacheReadPer1M: 0.50, lastReviewedAt: '2026-05-18' },
+'example:fast':     { inputPer1M: 0.50, outputPer1M:  1.50, cacheReadPer1M: 0.05, lastReviewedAt: '2026-05-18' },
+```
+
+The `finaliseInvocationResult` flow in `server/result-event.ts` falls
+back to this table automatically and returns an `estimated` flag that
+`recordInvocation` (`server/ai-invocations.ts`) persists as
+`total_cost_usd_estimated = 1` on the `ai_invocations` row, which in
+turn lights up the `~` tilde + Hero footnote on the AnalyticsPage.
+
+### 4. (If `nativeOtelEnv === false`) confirm the OTEL bridge works
+
+The synthetic OTEL bridge at `server/codex-otel-bridge.ts` is
+provider-neutral despite its name — it consumes the canonical
+`AdapterEvent` stream. As long as your adapter's `parseStreamLine`
+emits `text-delta`, `tool-use`, `session-started`, and `result` events,
+the bridge will synthesise traces / metrics / logs for free. The
+exported factory is still named `createCodexOtelBridge`; if that bugs
+you, renaming it to `createSyntheticOtelBridge` (and updating callers)
+is safe — same logic.
+
+### 5. (If `mcpRegistration === 'cli-add'`) wire the plugin install path
+
+The codex MCP integration lives at `server/plugins/codex-mcp.ts`.
+Mirror that file for a new `<provider>-mcp.ts` if your provider has a
+similar `<binary> mcp add/remove/list` subcommand. Then update
+`server/plugins/serena/install.ts`, which routes to the CLI-add helper
+whenever `getAdapter(providerId).mcpRegistration === 'cli-add'`. The
+app-level `PluginManager` already threads `providerId` through every
+relevant method.
+
+For `mcpRegistration === 'project-json'` providers, the existing
+`.mcp.json` surgical-merge path applies — nothing to add.
+
+## Known gotchas
+
+- **Legacy result path.** `normaliseResultEvent(event, provider)`
+  (`server/result-event.ts`) is still live for any callsite not yet
+  migrated to `finaliseInvocationResult`. It only special-cases
+  `provider === 'claude'`; everything else falls into the non-claude
+  (codex-shaped) branch. A 4th provider hitting that path would be
+  silently parsed as codex — migrate the callsite or extend the branch.
+- **Rail slash-command translation is provider-specific.** In
+  `server/queue-manager.ts` the rail prompt builder rewrites
+  `/specrails:<name>` → `$<name>` for codex (so codex picks up the
+  matching `.codex/skills/<name>/SKILL.md`), while claude passes the
+  command verbatim. A new adapter falls through to the claude branch
+  (verbatim). If your CLI needs a different invocation syntax, add a
+  branch keyed on a capability, not on the provider id.
+
+## Drop a fixture set
+
+Add a JSONL capture of a real `<binary> exec --json` (or whatever your
+CLI's JSONL flag is) under
+`server/providers/__fixtures__/<id>/<minCliVersion>/`. The adapter's
+test suite consumes these so future CLI-version bumps surface schema
+drift loudly instead of silently.
+
+## Write the tests
+
+Mirror the test layout under `server/providers/<id>-adapter.test.ts`.
+Required coverage:
+
+- Identity: id / binary / projectDirName / instructionsFilename /
+  mcpRegistration / capability flags / model catalog.
+- `buildArgs` for every `SpawnAction` the manager flow uses (today:
+  `chat-turn`, `chat-resume`, `rail-job`, `spec-gen`, `agent-refine`,
+  `setup-enrich`, `setup-enrich-resume`, `auto-title`).
+- `parseStreamLine` per event type, including an "unknown type maps
+  to kind: 'other'" defensive test and a "returns null on empty input
+  and on unparseable JSON" test.
+- `extractResult` from a fixture-derived event sequence.
+- `detectInstalled` happy / missing / non-zero-exit paths.
+
+## Verify
+
+```bash
+npm run typecheck
+npx vitest run server/providers server/pricing server/result-event server/plugin-manager
+```
+
+`npm run typecheck` runs `tsc --noEmit` for both the server and the
+client — important here, because the type-union widening above touches
+types both halves import, and a missed union surfaces only on the side
+you didn't check.
+
+Then a manual smoke test: register a project via the UI with the new
+provider, run a chat turn, run a rail, confirm tokens + cost land on
+the AnalyticsPage.
+
+## Don't break the principle
+
+The drift inventory above — the two hardcoded provider lists, the ~8
+`'claude' | 'codex'` unions, the legacy `normaliseResultEvent` branch,
+and the provider-specific rail rewrite — is the current debt. The
+long-term goal is to delete every one of those sites in favour of a
+registry-derived `ProviderId` so that adding a fifth provider really is
+just the adapter file plus the registry entry. If you find a NEW
+hardcoded `if (provider === 'X')` site that this guide doesn't list,
+**the architecture has drifted further** — file an OpenSpec change at
+`openspec/changes/<your-change-name>/` and capture the drift before
+papering over it with another manager-level branch.