@delegance/claude-autopilot 5.2.2 → 6.2.2

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

@@ -0,0 +1,221 @@
+/**
+ * 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 })`.
+ *
+ * `fail_rolled_back` and `fail_rollback_failed` (Phase 4 of v5.6) describe
+ * the bounded auto-rollback outcomes. They both mean "the deploy itself
+ * succeeded but the post-deploy health check failed"; the suffix indicates
+ * whether the subsequent rollback attempt succeeded (`_rolled_back`) or
+ * failed (`_rollback_failed`). Adapters never set these directly — they are
+ * stamped onto the `DeployResult` by the CLI orchestration in
+ * `src/cli/deploy.ts` after `rollback()` returns. Plain `fail` continues to
+ * cover deploy-itself failures and the "no rollback configured / not
+ * supported" branches so existing consumers keep working.
+ */
+export interface DeployResult {
+    status: 'pass' | 'fail' | 'in-progress' | 'fail_rolled_back' | 'fail_rollback_failed';
+    /** 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;
+}
+/**
+ * Self-described capability surface for an adapter.
+ *
+ * Codex review of v5.6 (#4) flagged that Render's REST polling and Fly's
+ * WebSocket streaming offer materially different log-streaming experiences,
+ * and pretending they're equivalent degrades user trust. CLI surfaces (and
+ * downstream consumers) inspect this struct to print a one-line notice when
+ * `--watch` is invoked against a `polling`-mode adapter, and to choose between
+ * native vs simulated rollback messaging in the PR comment.
+ *
+ * The field is optional — adapters that don't declare capabilities are
+ * treated as `streamMode: 'none'`, `nativeRollback: false` for safety.
+ */
+export interface DeployAdapterCapabilities {
+    /**
+     * How `streamLogs()` (when implemented) delivers lines:
+     * - `websocket` — real-time, push-based, near-zero gap between line emit and consumer receive
+     * - `polling` — REST-paginated polling cursor, lines may arrive in batches with short gaps
+     * - `none` — no log-streaming surface at all
+     */
+    streamMode?: 'websocket' | 'polling' | 'none';
+    /**
+     * `true` when the platform exposes a single "promote prior release" verb
+     * (Vercel's `/promote`, Fly's `/rollback`); `false` when rollback must be
+     * simulated by re-deploying a previous successful image/commit (Render).
+     */
+    nativeRollback?: boolean;
+}
+/**
+ * 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;
+    /**
+     * Optional self-description of the adapter's streaming + rollback shape.
+     * See {@link DeployAdapterCapabilities} for semantics. CLI consumers use
+     * this to decide whether to print the polling-mode notice on `--watch`.
+     */
+    readonly capabilities?: DeployAdapterCapabilities;
+    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. v5.4 shipped `vercel` + `generic`; v5.6 Phase 1
+     * adds `fly`; v5.6 Phase 2 adds `render`.
+     */
+    adapter: 'vercel' | 'fly' | 'render' | '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';
+    /** Fly app slug. Required when `adapter === 'fly'`. */
+    app?: string;
+    /**
+     * Pre-pushed image reference, e.g. `registry.fly.io/my-app:deployment-01`.
+     * Required when `adapter === 'fly'` — the Fly adapter does not build the
+     * image; pushing is the user's responsibility (`fly deploy --build-only --push`).
+     */
+    image?: string;
+    /** Optional Fly region pin (e.g. `ord`). Falls back to the app's default region. */
+    region?: string;
+    /** Render service ID (e.g. `srv-abc123`). Required when `adapter === 'render'`. */
+    serviceId?: string;
+    /**
+     * Whether Render should clear the build cache before deploying. Optional,
+     * default `'do_not_clear'`. Maps directly to the Render API body field.
+     */
+    clearCache?: 'do_not_clear' | 'clear';
+    /** 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

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

@@ -0,0 +1,143 @@
+import type { DeployAdapter, DeployInput, DeployLogLine, DeployResult, DeployRollbackInput, DeployStatusInput, DeployStatusResult, DeployStreamLogsInput } from './types.ts';
+/** Vercel deployment states. The first three are terminal; the rest are interim. */
+type VercelState = 'READY' | 'ERROR' | 'CANCELED' | 'BUILDING' | 'INITIALIZING' | 'QUEUED' | 'DEPLOYING' | 'ANALYZING';
+/**
+ * Single entry from `GET /v6/deployments`. Vercel's list response wraps
+ * these under `{ deployments: [...] }`. We only surface the fields the
+ * rollback + status flows need; callers MUST treat all fields beyond `id`
+ * as best-effort (older deployments occasionally omit `createdAt` and
+ * `state` is not always populated for super-recent in-flight builds).
+ */
+export interface VercelDeployListItem {
+    id: string;
+    url?: string;
+    state?: VercelState;
+    /** Milliseconds since epoch — Vercel returns this as a number. */
+    createdAt?: number;
+}
+export interface VercelDeployAdapterOptions {
+    /** Personal access token. Falls back to `process.env.VERCEL_TOKEN`. */
+    token?: string;
+    /** Vercel project ID or slug. Required. */
+    project: string;
+    /** Vercel team ID. Optional — required only for team accounts. */
+    team?: string;
+    /** Deploy target. Default: `production`. */
+    target?: 'production' | 'preview';
+    /** Polling interval (ms) when waiting for the build to reach a terminal state. Default: 2000. */
+    pollIntervalMs?: number;
+    /** Maximum total time to poll before returning `in-progress`. Default: 15 minutes. */
+    maxPollMs?: number;
+    /** Injected fetch implementation — defaults to `globalThis.fetch`. Tests pass a mock. */
+    fetchImpl?: typeof fetch;
+    /** Injected sleep implementation — tests pass a no-op so they don't actually wait. */
+    sleepImpl?: (ms: number) => Promise<void>;
+    /** Wall-clock source — tests pass a controllable counter. */
+    nowImpl?: () => number;
+    /**
+     * Optional caller-supplied redaction patterns (in addition to the
+     * built-in default set in `core/logging/redaction.ts`). Typically wired
+     * from `config.persistence.redactionPatterns` by the CLI; tests omit it.
+     *
+     * Phase 5 of v5.6 brought Vercel into parity with Fly/Render — the v5.4
+     * adapter previously emitted `output` lines verbatim, which was a real
+     * leak hazard for any build that echoed an env var into stdout.
+     */
+    redactionPatterns?: readonly string[];
+}
+/**
+ * Vercel deploy adapter.
+ *
+ * Construct once per pipeline run. The adapter is stateless across calls — all
+ * configuration (token, project, team) is captured at construction time.
+ */
+export declare class VercelDeployAdapter implements DeployAdapter {
+    readonly name = "vercel";
+    private readonly token;
+    private readonly project;
+    private readonly team;
+    private readonly target;
+    private readonly pollIntervalMs;
+    private readonly maxPollMs;
+    private readonly fetchImpl;
+    private readonly sleep;
+    private readonly now;
+    private readonly redactionPatterns;
+    constructor(opts: VercelDeployAdapterOptions);
+    deploy(input: DeployInput): Promise<DeployResult>;
+    status(input: DeployStatusInput): Promise<DeployStatusResult>;
+    /**
+     * Phase 2 — subscribe to real-time build logs for a deployment.
+     *
+     * Streams `GET /v2/deployments/<id>/events?builds=1&follow=1` and yields a
+     * `DeployLogLine` for each `stdout` / `stderr` event. Lifecycle events
+     * (`state`, `complete`) are filtered out — the polling loop in `deploy()`
+     * already handles them. Malformed JSON lines are skipped silently rather
+     * than crashing a long-running stream.
+     *
+     * Cancellation: pass `input.signal`. Once aborted, the underlying fetch
+     * is torn down and the iterator returns.
+     */
+    streamLogs(input: DeployStreamLogsInput): AsyncGenerator<DeployLogLine>;
+    /**
+     * Phase 3 — promote a previously-built deployment to production.
+     *
+     * Two modes:
+     * - `input.to` set → promote that deploy ID directly. Cheapest path.
+     * - `input.to` omitted → look up the previous prod deploy via
+     *   `listDeployments(5)` and promote it. Throws `no_previous_deploy`
+     *   when there's nothing to roll back to (project with one deploy,
+     *   or every prior deploy is in ERROR/CANCELED state).
+     *
+     * Always-query is intentional: we never cache deploy IDs locally, so a
+     * promote performed from the Vercel dashboard between our deploy and
+     * our rollback is still observable.
+     */
+    rollback(input: DeployRollbackInput): Promise<DeployResult>;
+    /**
+     * Phase 3 — list recent production deployments for the configured
+     * project. Used by the `deploy status` CLI subcommand and by the
+     * `findPreviousProdDeployment()` helper backing `rollback()`.
+     *
+     * The list endpoint is `/v6/deployments` (v13 is for individual
+     * deployments). `target=production` filters out preview builds; `limit`
+     * caps the result set — Vercel returns newest-first so a small limit
+     * is sufficient for both rollback target detection and the CLI status
+     * display (defaults to 5).
+     */
+    listDeployments(limit?: number, signal?: AbortSignal): Promise<VercelDeployListItem[]>;
+    /**
+     * Apply the adapter's redaction patterns to a streamed log line's `text`.
+     * Mirrors the Fly/Render redactLine helpers introduced in v5.6 so secrets
+     * never escape the adapter via streamed log entries.
+     */
+    private redactLine;
+    /**
+     * Returns the deployment immediately preceding the current production
+     * deployment, or `null` if no rollback target exists.
+     *
+     * "Preceding" means: among deployments with `state === 'READY'` (so we
+     * never roll back to a known-broken build), sorted newest-first by
+     * `createdAt`, the second entry. The first entry is the current prod
+     * deploy and we drop it.
+     */
+    private findPreviousProdDeployment;
+    private pollUntilTerminal;
+    private shapeResult;
+    private headers;
+    private urlWithTeam;
+    private buildLogsUrl;
+    private assertOkOrThrow;
+    /**
+     * Like `fetchWithRetry` but tuned for the events endpoint:
+     * - 404 right after a deploy POST is a known race (the deploy hasn't yet
+     *   propagated to the events service). Retry up to N times with backoff.
+     * - 5xx behaves the same as `fetchWithRetry`.
+     * - Cancels cleanly on AbortError.
+     * - Returns the last `Response` so the caller can `assertOkOrThrow` on a
+     *   final non-OK status (e.g. 401 still bubbles immediately on attempt 1).
+     */
+    private fetchEventsWithRetry;
+}
+export {};
+//# sourceMappingURL=vercel.d.ts.map