@delegance/claude-autopilot 5.2.1 → 5.5.2

package/CHANGELOG.md

@@ -1,5 +1,102 @@
 # Changelog
 
+## v5.3.0 — Deploy phase (in flight, not yet shipped)
+
+### Added
+
+- **`deploy` phase** — adapter-agnostic deploy step that runs your existing deploy command, extracts the URL from stdout, optionally polls a `healthCheckUrl`, and (optionally) posts result to a PR. Closes the loop from "PR merged" to "PR merged + deployed + smoke-tested + URL on the PR".
+- **`deployCommand` + `healthCheckUrl` config keys** — anything that works in your terminal works as `deployCommand` (`vercel --prod`, `flyctl deploy`, `kubectl apply`, `gh workflow run`, `make deploy`).
+- **`claude-autopilot deploy [--dry-run|--command|--health-url|--pr <n>]`** — CLI surface. PR comment integration via `gh pr comment`.
+
+First-class provider adapters (Vercel/Fly/Render with API-level deploy IDs + rollback hooks) are queued for v5.4.
+
+## v5.2.2 — Demo polish
+
+### Fixed
+
+- **Cost log skips zero-token entries.** Setup-flow scans, dry-runs, and no-findings paths were polluting the log with empty rows that drowned real review entries in `claude-autopilot costs` output.
+- **`costs` shows scope.** Output now explicitly notes "per-project — scoped to `<cwd>/.guardrail-cache/costs.jsonl`" so users understand it's not a global aggregate.
+- **`pr` no longer hard-fails on missing config.** First-run on a fresh repo now auto-detects + prints a remediation line pointing at `setup`.
+
+### Added
+
+- **DEMO.md committed at repo root.** Real end-to-end pipeline run on randai-johnson (multi-file Python integration, 12 min wall clock, $2.20 spend, 5 new tests, zero manual intervention). Linkable from external docs / pitch material.
+
+## v5.2.1 — Stress-test polish
+
+### Fixed
+
+- **venv detection in tests phase.** `pytest -q` now resolves to `<project>/.venv/bin/pytest` (or `venv/`, `env/`) when present, so `claude-autopilot pr` no longer reports "tests failed" on Python repos with venv-installed pytest.
+- **`autoregress` 100% broken on global install** — the bridge resolved `SCRIPT` to `dist/scripts/autoregress.ts` under the compiled layout, but `scripts/` ships at the package root. Every invocation threw `ERR_MODULE_NOT_FOUND`. Now uses `findPackageRoot` + existence check.
+- **Council in python preset.** Python preset now ships a commented `council:` template (mirrors the generic preset). Out-of-the-box `init --preset python` no longer requires manual schema discovery.
+- **Regression-lane fixture top-level await.** CI workflow's `npx tsx -e "..."` blocks wrapped in `async () => {...}` so esbuild's CJS output accepts them. Plus expected-ledger.json updated to match v5.2.0's new version format.
+
+## v5.0.8 — Line extraction + fix gate
+
+### Fixed
+
+- **Parser extracts "line N" / "on line N" / "at line N" from prose** when not adjacent to a file ref. Previously findings shipped with file but no line, so `fix --dry-run` reported "no fixable findings" on a non-empty findings list.
+- **`fix` distinguishes actionable (file present) from fixable (file + line).** Dry-run surfaces actionable findings even when line-less, with a clear message about why the LLM-fix loop can't act on them.
+
+## v5.0.7 — File backfill + cost ledger consolidation
+
+### Fixed
+
+- **Single-file scan unconditionally backfills the file path.** The 5.0.6 fallback only triggered on `<unspecified>`, so prose-noise like `"n.r"` slipped through and broke `fix`.
+- **`pr-desc` and `council` now persist to the cost ledger.** Previously only `scan` and `run` were tracked, so `claude-autopilot costs` showed misleadingly low totals after multi-call sessions.
+- **Single-letter code extensions removed from bare-reference parser** (c/d/h/m/r/s) — they still match when backtick-wrapped, but bare matches like "n.r" no longer slip through.
+- **`appendCostLog` swallows write errors centrally.** Cost log is observability, not a contract — a read-only FS or full disk no longer crashes commands that already succeeded.
+
+## v5.0.6 — Setup YAML + branch fallback
+
+### Fixed
+
+- **`setup` no longer writes duplicate `testCommand` keys.** Several presets (go, python, python-fastapi, rails-postgres) ship with their own `testCommand:` line; `cli/setup.ts` was unconditionally appending another, producing invalid YAML that hard-failed every command after `setup` on those stacks.
+- **Single-file scan backfills file path** (initial fix; superseded by v5.0.7's unconditional version).
+- **Branch-derived PR titles default to `chore:` for unknown prefixes.** `autopilot-test/validate-weights` → `chore: validate weights` instead of `autopilot test validate weights` (which fails commitlint).
+
+## v5.0.5 — Python detect + parser hardening
+
+### Added
+
+- **`presets/python/`** — general Python config (pytest, ruff, hardcoded-secrets, common protected paths). Detector now picks it for any `pyproject.toml` or `requirements.txt` without FastAPI signals (was falling through to the JS/Generic preset).
+
+### Fixed
+
+- **Parser rejects "e.g" / "i.e" / "etc" prose as file refs.** The prior regex `\.[a-z]{1,6}` accepted any 1-6 letter suffix, so prose like "(e.g. dict, list)" was matched. Bare references now require a known code-file extension.
+- **`pr-desc` real titles.** Prompt now explicitly asks for a Title line; parser falls through to a branch-derived conventional-commit title (`fix/cost-tracker` → `fix: cost tracker`), then first summary bullet, then `chore: update` only as a last resort.
+- **`runReviewOnTestFail` default flipped to `true`.** Failed/missing test commands no longer silently kill the LLM review phase. Strict gating still available via explicit `false`.
+
+## v5.0.4 — Council Responses API
+
+### Fixed
+
+- **Council 404s on `gpt-5.3-codex` resolved.** Codex variants and o-series reasoning models are Responses-API-only — the council adapter only used `client.chat.completions`. Now branches by model name (`/codex|^o[1-9]|^gpt-5\.3-/`) to use `client.responses.create()` for those models. Fixes the multi-model differentiator for any user with only `OPENAI_API_KEY`.
+- **Generic preset ships a working council template.**
+
+## v5.0.3 — Cost tracker
+
+### Fixed
+
+- **Codex adapter computes `costUSD`** (was returning `usage` without a cost field, so every codex run logged $0).
+- **`scan` now persists to cost log** (was only `run` writing entries).
+
+## v5.0.2 — Post-install friction
+
+### Fixed
+
+- **preflight `tsx` false-positive eliminated.** Every fresh global install reported `✗ tsx available` blocker because the bundled tsx wasn't checked. Now uses `findPackageRoot(import.meta.url)`.
+- **Top-level `unhandledRejection` + `uncaughtException` handlers** format `GuardrailError` as a single-line red message instead of a Node stack trace. `CLAUDE_AUTOPILOT_DEBUG=1` re-enables stack.
+- **Tarball trimmed:** dropped `src/` + `*.map` from `files` array → 319 files / 182 kB packed (was 726 / 382 kB), -56% / -52%.
+- **Stale strings:** `@alpha` install hint → `@latest`; `npx guardrail run` blocker text → `claude-autopilot run`; init deprecation banner removed (both verbs work).
+
+## v5.0.1 — Types + tombstone
+
+### Fixed
+
+- **Ships `dist/src/index.d.ts`** for TypeScript consumers.
+- **Tombstone `@delegance/guardrail` package** publishes a forwarder pointing at the renamed package; pre-rename versions deprecated with migration message.
+
 ## v5.2.0 — Migrate skill generalization
 
 ### Added

package/README.md

@@ -1,7 +1,11 @@
 # @delegance/claude-autopilot
 
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE) [![GitHub](https://img.shields.io/badge/GitHub-axledbetter%2Fclaude--autopilot-181717?logo=github)](https://github.com/axledbetter/claude-autopilot) [![npm](https://img.shields.io/npm/v/@delegance/claude-autopilot.svg)](https://www.npmjs.com/package/@delegance/claude-autopilot)
+
 **Autonomous development pipeline for Claude Code. Brainstorm → spec → plan → implement → migrate → validate → PR → review → merge — all from your terminal, on your codebase, with your test suite.**
 
+**Open source, MIT-licensed, runs on your machine with your API keys.** No hosted agent, no per-seat subscription — `npm install -g @delegance/claude-autopilot` and you're done.
+
 ```bash
 claude-autopilot brainstorm "add SSO with SAML for enterprise tenants"
 # → writes spec (reviewed by Codex) → writes plan (reviewed by Codex) →
@@ -13,6 +17,8 @@ claude-autopilot brainstorm "add SSO with SAML for enterprise tenants"
 
 *No hosted agent. No per-seat subscription. Runs locally on your machine, against your real repo, using your API keys. Every phase is a Claude Code skill you can intervene in, rewire, or run by itself.*
 
+**See it work end-to-end:** [DEMO.md](DEMO.md) — one real autonomous run on a Python codebase. 12 minutes wall clock, $2.20 spend, 5 new tests, multi-file integration, zero manual intervention. Honest about what's bounded today.
+
 ---
 
 ## Benchmark
@@ -29,24 +35,31 @@ Every finding came with a concrete remediation (often a code patch or named libr
 
 ## Why this vs the alternatives
 
-AI coding tools fall into three buckets. Here's where claude-autopilot sits.
-
-| Tool | Shape | Hosted? | Model lock-in | Pipeline structure | You can intervene mid-flow? |
+| Tool | Where code lives | Pricing model | Models | Pipeline | Intervenable? |
 |---|---|---|---|---|---|
-| **Devin** (Cognition) | Autonomous agent | Yes (SaaS, $500/mo) | Cognition's stack | Opaque | No — watch a dashboard |
-| **GitHub Copilot Workspace** | Spec → plan → PR | Yes | Copilot only | Fixed, non-extensible | Edit the plan, that's it |
-| **Factory Droids** | Multi-agent workflow | Yes (per-seat) | Factory's stack | Fixed | Limited |
-| **Cursor BugBot / Copilot Review / CodeRabbit** | Async PR reviewer | Yes | Vendor's model | Single phase (review only) | N/A — post-hoc only |
-| **Aider / Cline / Cursor agent mode** | Interactive pair programming | Local | User's choice | None — single-shot prompts | Continuous |
-| **OpenHands / SWE-agent** | Open-ended agent framework | Local | User's choice | None — agent decides | Rare, research-grade |
-| **claude-autopilot** | **Opinionated local pipeline** | **Local** | **Any LLM (Claude / GPT / Gemini / Groq / Ollama)** | **Fixed but rewireable, skill-per-phase** | **Every phase. All state on disk.** |
+| **Devin** (Cognition) | Hosted sandbox | Per-ACU (cloud markup) | Cognition's stack | Opaque | No — dashboard only |
+| **Factory Droids** | Hosted | Per-task + seat | Factory's stack | Fixed | Limited |
+| **GitHub Copilot Workspace** | GitHub-hosted | Per-seat ($) | Copilot only | Fixed, non-extensible | Edit the plan |
+| **Cursor / Copilot agent mode** | Local IDE | Per-seat ($) | Vendor's model | None — single-shot | Continuous |
+| **Cursor BugBot / CodeRabbit** | Hosted | Per-PR or seat | Vendor's model | Review only | Post-hoc |
+| **Aider / Cline** | Local CLI | Free + your API key | User's choice | None | Continuous |
+| **OpenHands / SWE-agent** | Local research | Free | User's choice | Agent decides | Rare |
+| **claude-autopilot** | **Local CLI, your repo** | **Free + your existing Claude subscription** | **Multi-model per role (Claude + Codex + Gemini)** | **Skill-per-phase, rewireable** | **Every phase, all state on disk** |
+
+Three things only this product gives you:
+
+1. **Multi-model council.** Same design question goes to Claude + Codex + Gemini in parallel; a fourth model synthesizes the consensus. Different blind spots, different recommendations, one merged answer. **No other tool dispatches multi-model on a per-decision basis.**
+2. **Your code never leaves your machine.** No cloud sandbox. No SaaS markup. The `git push` that happens at the end is from your laptop. For private repos, regulated industries, or anyone who doesn't want their unfinished code on someone else's servers — this is the only autonomous-agent shape that fits.
+3. **Ships as a Claude Code skill, not a competing IDE.** `/brainstorm`, `/autopilot`, `/migrate`, `/validate` are first-class Claude Code commands. As Claude Code grows, autopilot rides that adoption. You don't switch tools to use it; it's already there.
+
+Plus the four practical differences:
 
-The architectural differences that matter most in practice:
+- **Multi-model by role.** Claude writes code, Codex reviews the plan, bugbot triages PR findings. Swap any of them.
+- **Your stack, not a sandbox.** Runs your `npm test`, your `prisma migrate`, your `gh pr create`. If it works in your terminal, it works in the pipeline.
+- **Phase artifacts on disk, editable.** Every phase writes to a file you can open — `docs/specs/*.md`, `docs/plans/*.md`, a branch, a PR. Stop, edit by hand, resume, or re-run any phase in isolation.
+- **Test-gated auto-revert.** `claude-autopilot fix --verify` patches a file, runs your tests, reverts on failure. Built into the CLI, not a wrapper.
 
-1. **Multi-model by design.** Claude writes code, Codex reviews the plan, bugbot triages PR findings. Different model for each role, swap any of them. The pipeline's phases are explicit contracts, not one opaque API call.
-2. **Your stack, not a sandbox.** It runs your `npm test`, your `prisma migrate`, your `gh pr create`, your `ruff check`. If it works in your terminal, it works in the pipeline.
-3. **Phase artifacts on disk, editable.** Every phase writes to a file you can open — `docs/specs/*.md`, `docs/plans/*.md`, a branch, a PR. Stop, edit by hand, resume, or re-run any phase in isolation.
-4. **Test-gated auto-revert as a first-class command.** `claude-autopilot fix --verify` patches a file, runs your full test suite, and reverts on failure. Built into the CLI, not a wrapper you write yourself.
+**Real numbers from a real run:** [DEMO.md](DEMO.md) — autonomous multi-file change on a Python codebase, **12 minutes, $2.20, zero manual intervention.**
 
 ## 30-second quickstart
 
@@ -86,7 +99,22 @@ Each phase is a Claude Code skill (`.claude/skills/<name>/SKILL.md`). You can in
 
 ### Migrate phase
 
-Configure your migration tool in `.autopilot/stack.md`. The pipeline reads stack.md, dispatches to the configured skill (`migrate@1` for generic; `migrate.supabase@1` for rich Supabase ledger; `none@1` to skip), and runs your tool with full safety: structured argv (no shell injection), 4-flag CI prod gate, hash-chained audit log. Run `claude-autopilot init` to auto-detect your stack. See [docs/skills/rich-migrate-contract.md](docs/skills/rich-migrate-contract.md) for the skill contract and [docs/skills/version-compatibility.md](docs/skills/version-compatibility.md) for the version model.
+Configure your migration tool in `.autopilot/stack.md`. The pipeline reads stack.md, dispatches to the configured skill (`migrate@1` for generic; `migrate.supabase@1` for rich Supabase ledger; `none@1` to skip), and runs your tool with full safety: structured argv (no shell injection), 4-flag CI prod gate, hash-chained audit log. Run `claude-autopilot init` to auto-detect your stack — the detector recognizes Rails, Alembic, Django, Prisma, Drizzle, golang-migrate, dbmate, flyway, supabase-cli, ecto, typeorm, and falls back to a "configure manually" path. See [docs/skills/rich-migrate-contract.md](docs/skills/rich-migrate-contract.md) for the skill contract and [docs/skills/version-compatibility.md](docs/skills/version-compatibility.md) for the version model.
+
+Generic example (Rails):
+
+```yaml
+migrate:
+  skill: "migrate@1"
+  envs:
+    dev:
+      command: { exec: "rails", args: ["db:migrate"] }
+      env_file: ".env.development"
+    prod:
+      command: { exec: "rails", args: ["db:migrate", "RAILS_ENV=production"] }
+```
+
+See `skills/migrate/SKILL.md` for examples covering Alembic, Django, Prisma, Drizzle, golang-migrate, dbmate, flyway, and custom scripts.
 
 ## What's distinctive
 
@@ -315,6 +343,10 @@ ANTHROPIC_API_KEY=sk-ant-... claude-autopilot scan --all
 
 We do not claim 13/13 reflects every real-world repo — it's a reproducible upper bound on a fixture that exercises the categories we explicitly target.
 
+## Contributing
+
+Issues and PRs welcome — https://github.com/axledbetter/claude-autopilot/issues. The pipeline literally builds itself; many features in this repo were implemented by autopilot running against autopilot ([DEMO.md](DEMO.md) walks through six self-eat PRs with cost trajectory $10 → ~$2.50). Read [CONTRIBUTING.md](CONTRIBUTING.md) if it exists, otherwise: clone, `npm install`, `npm test`, open a PR.
+
 ## License
 
-MIT
+MIT — see [LICENSE](LICENSE).

package/dist/src/adapters/council/claude.js

@@ -1,6 +1,6 @@
-import Anthropic from '@anthropic-ai/sdk';
 import { GuardrailError } from "../../core/errors.js";
 import { classifyError } from "../review-engine/prompt-builder.js";
+import { loadAnthropic } from "../sdk-loader.js";
 const SYSTEM_PROMPT = `You are a technical advisor reviewing a software design decision. Evaluate the provided context and question critically. Be direct and specific. Surface tradeoffs, risks, and your recommendation.`;
 const MAX_OUTPUT_TOKENS = 2048;
 // Default Opus 4.7 rates — env override for other models.
@@ -14,6 +14,7 @@ export function makeClaudeCouncilAdapter(model, label) {
             if (!apiKey) {
                 throw new GuardrailError('ANTHROPIC_API_KEY not set', { code: 'auth', provider: 'claude' });
             }
+            const Anthropic = await loadAnthropic();
             const client = new Anthropic({ apiKey });
             let response;
             try {

package/dist/src/adapters/council/openai.js

@@ -1,6 +1,6 @@
-import OpenAI from 'openai';
 import { GuardrailError } from "../../core/errors.js";
 import { classifyError } from "../review-engine/prompt-builder.js";
+import { loadOpenAI } from "../sdk-loader.js";
 const SYSTEM_PROMPT = `You are a technical advisor reviewing a software design decision. Evaluate the provided context and question critically. Be direct and specific. Surface tradeoffs, risks, and your recommendation.`;
 const MAX_OUTPUT_TOKENS = 2048;
 // Models that ONLY work via the Responses API (not chat.completions).
@@ -25,6 +25,7 @@ export function makeOpenAICouncilAdapter(model, label) {
             if (!apiKey) {
                 throw new GuardrailError('OPENAI_API_KEY not set', { code: 'auth', provider: 'openai' });
             }
+            const OpenAI = await loadOpenAI();
             const client = new OpenAI({ apiKey });
             const userInput = `## Context\n\n${context}\n\n## Question\n\n${prompt}`;
             try {

package/dist/src/adapters/deploy/generic.d.ts

@@ -0,0 +1,39 @@
+import type { ChildProcessByStdio } from 'node:child_process';
+import type { Readable, Writable } from 'node:stream';
+import type { DeployAdapter, DeployInput, DeployResult } from './types.ts';
+/**
+ * Function signature for the spawn dependency. Tests inject a fake spawn that
+ * emits canned stdout/exit events without touching the real OS process API.
+ */
+export type SpawnFn = (command: string, args: ReadonlyArray<string>, options: {
+    shell: boolean | string;
+    signal?: AbortSignal;
+}) => ChildProcessByStdio<Writable | null, Readable | null, Readable | null>;
+export interface GenericDeployAdapterOptions {
+    /** Free-form shell command (e.g. `vercel --prod`). Required. */
+    deployCommand: string;
+    /** Optional health-check URL — accepted for forward-compat with Phase 4; unused in Phase 1. */
+    healthCheckUrl?: string;
+    /** Injected spawn implementation (defaults to `node:child_process` spawn). */
+    spawnImpl?: SpawnFn;
+    /** When true, suppress teeing child stdout/stderr to the parent's process streams. Tests pass true. */
+    quiet?: boolean;
+    /** Wall-clock source. Tests pass a controllable counter. */
+    nowImpl?: () => number;
+}
+/**
+ * Generic shell-command deploy adapter.
+ *
+ * Captures stdout, looks for the first http(s) URL, returns it as `deployUrl`.
+ * Exit code 0 → `pass`; non-zero → `fail`.
+ */
+export declare class GenericDeployAdapter implements DeployAdapter {
+    readonly name = "generic";
+    private readonly deployCommand;
+    private readonly spawnImpl;
+    private readonly quiet;
+    private readonly now;
+    constructor(opts: GenericDeployAdapterOptions);
+    deploy(input: DeployInput): Promise<DeployResult>;
+}
+//# sourceMappingURL=generic.d.ts.map

package/dist/src/adapters/deploy/generic.js

@@ -0,0 +1,98 @@
+// src/adapters/deploy/generic.ts
+//
+// Generic deploy adapter — runs an arbitrary shell command and reports back.
+//
+// Wraps the v5.3 "deployCommand" approach as a DeployAdapter so the same
+// CLI surface (`claude-autopilot deploy`) works whether you have a Vercel
+// project, a Fly app with `flyctl deploy`, a custom `make deploy`, or anything
+// else that prints a URL to stdout.
+//
+// `status()` and `rollback()` are deliberately omitted — without platform-API
+// state we have no way to answer "is the build still going" or "promote the
+// previous deploy". Callers that need those can switch to a platform adapter.
+import { spawn as defaultSpawn } from 'node:child_process';
+import { GuardrailError } from "../../core/errors.js";
+const URL_RE = /https?:\/\/[^\s)>"']+/i;
+/**
+ * Generic shell-command deploy adapter.
+ *
+ * Captures stdout, looks for the first http(s) URL, returns it as `deployUrl`.
+ * Exit code 0 → `pass`; non-zero → `fail`.
+ */
+export class GenericDeployAdapter {
+    name = 'generic';
+    deployCommand;
+    spawnImpl;
+    quiet;
+    now;
+    constructor(opts) {
+        if (!opts.deployCommand || opts.deployCommand.trim() === '') {
+            throw new GuardrailError('Generic deploy adapter requires `deployCommand`', { code: 'invalid_config', provider: 'generic' });
+        }
+        this.deployCommand = opts.deployCommand;
+        this.spawnImpl = opts.spawnImpl ?? defaultSpawn;
+        this.quiet = opts.quiet ?? process.env.AUTOPILOT_DEPLOY_QUIET === '1';
+        this.now = opts.nowImpl ?? Date.now;
+    }
+    async deploy(input) {
+        const start = this.now();
+        return new Promise((resolve, reject) => {
+            let stdoutBuf = '';
+            let stderrBuf = '';
+            const child = this.spawnImpl(this.deployCommand, [], {
+                shell: true,
+                signal: input.signal,
+            });
+            child.stdout?.on('data', (chunk) => {
+                const s = typeof chunk === 'string' ? chunk : chunk.toString('utf8');
+                stdoutBuf += s;
+                if (!this.quiet)
+                    process.stdout.write(s);
+            });
+            child.stderr?.on('data', (chunk) => {
+                const s = typeof chunk === 'string' ? chunk : chunk.toString('utf8');
+                stderrBuf += s;
+                if (!this.quiet)
+                    process.stderr.write(s);
+            });
+            child.on('error', (err) => {
+                // AbortError from a passed signal — surface as an aborted in-progress
+                // result rather than a hard reject.
+                if (err.name === 'AbortError') {
+                    resolve({
+                        status: 'in-progress',
+                        durationMs: this.now() - start,
+                        output: 'Deploy aborted by caller.',
+                    });
+                    return;
+                }
+                reject(new GuardrailError(`Generic deploy adapter failed to spawn: ${err.message}`, { code: 'adapter_bug', provider: 'generic', details: { errno: err.code } }));
+            });
+            child.on('close', (code) => {
+                const durationMs = this.now() - start;
+                const tail = lastNLines(stdoutBuf + stderrBuf, 20);
+                if (code === 0) {
+                    const match = stdoutBuf.match(URL_RE);
+                    resolve({
+                        status: 'pass',
+                        deployUrl: match?.[0],
+                        durationMs,
+                        output: tail,
+                    });
+                }
+                else {
+                    resolve({
+                        status: 'fail',
+                        durationMs,
+                        output: tail,
+                    });
+                }
+            });
+        });
+    }
+}
+function lastNLines(s, n) {
+    const lines = s.split(/\r?\n/);
+    return lines.slice(Math.max(0, lines.length - n)).join('\n');
+}
+//# sourceMappingURL=generic.js.map

package/dist/src/adapters/deploy/index.d.ts

@@ -0,0 +1,13 @@
+import type { DeployAdapter, DeployConfig } from './types.ts';
+export * from './types.ts';
+export { VercelDeployAdapter } from './vercel.ts';
+export { GenericDeployAdapter } from './generic.ts';
+/**
+ * Construct the right deploy adapter for the supplied config.
+ *
+ * Throws `GuardrailError` (code: invalid_config) when required adapter-specific
+ * fields are missing — failing fast at construction beats silently dropping
+ * the deploy step.
+ */
+export declare function createDeployAdapter(config: DeployConfig): DeployAdapter;
+//# sourceMappingURL=index.d.ts.map

package/dist/src/adapters/deploy/index.js

@@ -0,0 +1,45 @@
+// src/adapters/deploy/index.ts
+//
+// Public surface for the deploy-adapter package + factory.
+import { GuardrailError } from "../../core/errors.js";
+import { GenericDeployAdapter } from "./generic.js";
+import { VercelDeployAdapter } from "./vercel.js";
+export * from "./types.js";
+export { VercelDeployAdapter } from "./vercel.js";
+export { GenericDeployAdapter } from "./generic.js";
+/**
+ * Construct the right deploy adapter for the supplied config.
+ *
+ * Throws `GuardrailError` (code: invalid_config) when required adapter-specific
+ * fields are missing — failing fast at construction beats silently dropping
+ * the deploy step.
+ */
+export function createDeployAdapter(config) {
+    switch (config.adapter) {
+        case 'vercel': {
+            if (!config.project) {
+                throw new GuardrailError('deploy.adapter=vercel requires deploy.project (Vercel project ID or slug)', { code: 'invalid_config', provider: 'vercel' });
+            }
+            return new VercelDeployAdapter({
+                project: config.project,
+                team: config.team,
+                target: config.target,
+            });
+        }
+        case 'generic': {
+            if (!config.deployCommand) {
+                throw new GuardrailError('deploy.adapter=generic requires deploy.deployCommand (shell command)', { code: 'invalid_config', provider: 'generic' });
+            }
+            return new GenericDeployAdapter({
+                deployCommand: config.deployCommand,
+                healthCheckUrl: config.healthCheckUrl,
+            });
+        }
+        default: {
+            // exhaustiveness guard — TS narrows config.adapter to never here
+            const exhaustive = config.adapter;
+            throw new GuardrailError(`Unknown deploy adapter: ${String(exhaustive)}`, { code: 'invalid_config' });
+        }
+    }
+}
+//# sourceMappingURL=index.js.map

package/dist/src/adapters/deploy/types.d.ts

@@ -0,0 +1,157 @@
+/**
+ * Common input to a deploy operation.
+ *
+ * Adapters are free to ignore fields they don't need. The Vercel adapter uses
+ * `commitSha` (and the env-derived git source) to choose what to build; the
+ * generic adapter uses neither — it just runs the configured deploy command.
+ */
+export interface DeployInput {
+    /** Symbolic git ref (branch / tag). Optional — adapters fall back to the configured target. */
+    ref?: string;
+    /** Specific commit SHA to deploy. Takes precedence over `ref` when both are set. */
+    commitSha?: string;
+    /** Free-form metadata propagated to the platform when supported (Vercel attaches as deployment meta). */
+    meta?: Record<string, string>;
+    /** Abort signal — adapters MUST honor this for any in-flight HTTP / spawn work. */
+    signal?: AbortSignal;
+    /**
+     * Fired exactly once with the platform-native deploy ID as soon as it's
+     * known. Adapters that obtain the ID synchronously (Vercel returns it from
+     * the create-deployment POST) MUST call this immediately after the POST
+     * resolves but before polling begins. Adapters with no discrete ID (the
+     * generic shell adapter) do NOT call it.
+     *
+     * Consumers use this to start side-channel work in parallel with the
+     * deploy — most notably log streaming via `--watch`.
+     */
+    onDeployStart?: (deployId: string) => void;
+}
+/**
+ * Outcome of a deploy operation.
+ *
+ * `status: 'in-progress'` is reserved for the case where polling timed out
+ * before the platform reached a terminal state — the deploy may still finish
+ * later. The adapter does NOT auto-resume in Phase 1; the caller can re-poll
+ * via `status({ deployId })`.
+ */
+export interface DeployResult {
+    status: 'pass' | 'fail' | 'in-progress';
+    /** Adapter-native deploy ID. Vercel uses `dpl_xxx`. Empty for generic when stdout has no extractable URL. */
+    deployId?: string;
+    /** Public URL of the deploy (e.g. `https://my-app-abc.vercel.app`). */
+    deployUrl?: string;
+    /** URL to the build logs / dashboard for human follow-up. */
+    buildLogsUrl?: string;
+    /** Wall-clock duration of the adapter call, in milliseconds. */
+    durationMs: number;
+    /** Human-readable summary suitable for the PR comment (last 50 log lines, status line, etc.). */
+    output?: string;
+    /** Populated when the adapter auto-rolled back to a previous deploy. Phase 3+. */
+    rolledBackTo?: string;
+}
+/**
+ * Input to a one-shot status query (no polling). Used by the future
+ * `claude-autopilot deploy status <id>` CLI subcommand and by the polling
+ * loop inside `deploy()`.
+ */
+export interface DeployStatusInput {
+    deployId: string;
+    signal?: AbortSignal;
+}
+/**
+ * Result of a one-shot status query. Same shape as DeployResult with the
+ * deployId required for traceability. Adapters that don't support status
+ * (e.g. generic) leave the `status` method unimplemented.
+ */
+export interface DeployStatusResult extends Omit<DeployResult, 'deployId'> {
+    deployId: string;
+}
+/**
+ * Input to a rollback operation. Reserved for Phase 3.
+ *
+ * `to` is optional: when omitted the adapter rolls back to the previous
+ * production deploy (looked up via the platform API).
+ */
+export interface DeployRollbackInput {
+    /** Specific deploy ID to roll back to. When omitted, the previous prod deploy is used. */
+    to?: string;
+    signal?: AbortSignal;
+}
+/**
+ * Input to a one-shot log-streaming subscription.
+ *
+ * Returned `AsyncIterable` yields `DeployLogLine`s as the platform emits
+ * them. Consumers iterate with `for await ... of`. Cancellation is via the
+ * `signal` — once aborted, the underlying transport is torn down and the
+ * iterator finishes (or throws `AbortError`, depending on adapter).
+ */
+export interface DeployStreamLogsInput {
+    deployId: string;
+    signal?: AbortSignal;
+}
+/**
+ * A single log line surfaced from the platform.
+ *
+ * Fields beyond `timestamp` and `text` are best-effort — adapters populate
+ * what they have. Consumers MUST NOT rely on `level` or `source` being set.
+ */
+export interface DeployLogLine {
+    /** Milliseconds since epoch — from the platform if provided, else when received locally. */
+    timestamp: number;
+    /** Build phase or component (e.g. 'build', 'deploy'). Optional. */
+    source?: string;
+    /** 'info' | 'warn' | 'error' | 'stdout' | 'stderr' — adapter-defined. Optional. */
+    level?: string;
+    /** Log text, no trailing newline. */
+    text: string;
+}
+/**
+ * The DeployAdapter contract.
+ *
+ * `deploy` is required. `status` and `rollback` are optional so adapters that
+ * don't expose them (the generic shell adapter being the canonical example)
+ * can omit the methods rather than throwing at runtime.
+ */
+export interface DeployAdapter {
+    /** Stable identifier — surfaced in CLI output and logs. */
+    readonly name: string;
+    deploy(input: DeployInput): Promise<DeployResult>;
+    status?(input: DeployStatusInput): Promise<DeployStatusResult>;
+    rollback?(input: DeployRollbackInput): Promise<DeployResult>;
+    /**
+     * Subscribe to real-time build logs. Optional — adapters without a
+     * platform API for log streaming (e.g. the generic shell adapter) omit
+     * this method, and the `undefined` is the canonical "not supported"
+     * signal for callers.
+     */
+    streamLogs?(input: DeployStreamLogsInput): AsyncIterable<DeployLogLine>;
+}
+/**
+ * Configuration block for the `deploy` phase. Lives under `deploy:` in
+ * `guardrail.config.yaml`.
+ *
+ * Fields are conditionally required based on `adapter`:
+ * - `vercel` requires `project`
+ * - `generic` requires `deployCommand`
+ *
+ * The factory in `./index.ts` enforces these rules at construction time.
+ */
+export interface DeployConfig {
+    /** Which adapter to use. Phase 1 ships `vercel` + `generic`. */
+    adapter: 'vercel' | 'generic';
+    /** Vercel project ID or slug. Required when `adapter === 'vercel'`. */
+    project?: string;
+    /** Vercel team ID for team accounts. Optional. */
+    team?: string;
+    /** Deploy target. Default: `production`. */
+    target?: 'production' | 'preview';
+    /** Shell command to run for the deploy (e.g. `vercel --prod`). Required when `adapter === 'generic'`. */
+    deployCommand?: string;
+    /** Stream build logs to stderr in real time. Phase 2. */
+    watchBuildLogs?: boolean;
+    /** Auto-rollback triggers. Phase 3 / 4. */
+    rollbackOn?: Array<'healthCheckFailure' | 'smokeTestFailure'>;
+    /** URL polled after deploy succeeds to confirm app health. Used by both adapters once Phase 4 lands. */
+    healthCheckUrl?: string;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/src/adapters/deploy/types.js

@@ -0,0 +1,15 @@
+// src/adapters/deploy/types.ts
+//
+// DeployAdapter contract — Phase 1 of the v5.4 Vercel adapter spec.
+//
+// A DeployAdapter abstracts over the "deploy this code somewhere" step of the
+// pipeline. Adapters can be platform-specific (vercel, fly, render) or generic
+// (a free-form shell command à la `vercel --prod` from v5.3).
+//
+// Phase 1 implements `deploy()` and `status()`. `rollback()` is reserved for
+// Phase 3 and intentionally optional on the interface so generic adapters that
+// don't support it can omit the method entirely.
+//
+// Spec: docs/specs/v5.4-vercel-adapter.md
+export {};
+//# sourceMappingURL=types.js.map