edsger 0.75.1 → 0.77.0

package/dist/commands/api-docs/index.d.ts

@@ -0,0 +1,18 @@
+/**
+ * CLI command: edsger api-docs <productId> --run-id <id>
+ *               edsger api-docs --repo-id <id> --run-id <id>
+ *
+ * Clones the repository, asks Claude to determine its API surface, and persists
+ * a generated API reference (Markdown + optional OpenAPI document) onto the
+ * pending api_doc_runs row. The desktop UI creates the pending row first then
+ * invokes the CLI with --run-id; the CLI flips status running →
+ * success/failed and writes the artifact via the api-docs MCP toolkit.
+ */
+export interface ApiDocsCliOptions {
+    runId: string;
+    /** Repo-only mode: generate for a single repositories row, no product. */
+    repoId?: string;
+    guidance?: string;
+    verbose?: boolean;
+}
+export declare function runApiDocs(productId: string | undefined, options: ApiDocsCliOptions): Promise<void>;

package/dist/commands/api-docs/index.js

@@ -0,0 +1,41 @@
+/**
+ * CLI command: edsger api-docs <productId> --run-id <id>
+ *               edsger api-docs --repo-id <id> --run-id <id>
+ *
+ * Clones the repository, asks Claude to determine its API surface, and persists
+ * a generated API reference (Markdown + optional OpenAPI document) onto the
+ * pending api_doc_runs row. The desktop UI creates the pending row first then
+ * invokes the CLI with --run-id; the CLI flips status running →
+ * success/failed and writes the artifact via the api-docs MCP toolkit.
+ */
+import { runApiDocsPhase } from '../../phases/api-docs/index.js';
+import { logError, logInfo, logSuccess } from '../../utils/logger.js';
+export async function runApiDocs(productId, options) {
+    const { runId, repoId, guidance, verbose } = options;
+    if (!productId && !repoId) {
+        throw new Error('Either a product ID or --repo-id is required for api-docs');
+    }
+    if (!runId) {
+        throw new Error('--run-id is required (the pending api_doc_runs row id)');
+    }
+    if (productId) {
+        logInfo(`Starting API docs generation for product ${productId}`);
+    }
+    else {
+        logInfo(`Starting API docs generation for repository ${repoId}`);
+    }
+    const result = await runApiDocsPhase({
+        productId,
+        repoId,
+        runId,
+        guidance,
+        verbose,
+    });
+    if (result.status === 'success') {
+        logSuccess(result.message);
+    }
+    else {
+        logError(result.message);
+        process.exit(1);
+    }
+}

package/dist/commands/find-architecture/index.d.ts

@@ -5,9 +5,11 @@
  * and files each new finding as an issue.
  */
 export interface FindArchitectureCliOptions {
+    /** Repo-only mode: scan a single `repositories` row with no product. */
+    repoId?: string;
     full?: boolean;
     branch?: string;
     maxFiles?: number;
     verbose?: boolean;
 }
-export declare function runFindArchitecture(productId: string, options: FindArchitectureCliOptions): Promise<void>;
+export declare function runFindArchitecture(productId: string | undefined, options: FindArchitectureCliOptions): Promise<void>;

package/dist/commands/find-architecture/index.js

@@ -4,22 +4,31 @@
  * coupling, cycles, missing/duplicated abstractions, responsibility creep)
  * and files each new finding as an issue.
  */
-import { getGitHubConfigByProduct } from '../../api/github.js';
+import { getGitHubConfigByProduct, getGitHubConfigByRepository, } from '../../api/github.js';
 import { scanForArchitecture } from '../../phases/find-architecture/index.js';
 import { logError, logInfo, logSuccess } from '../../utils/logger.js';
 export async function runFindArchitecture(productId, options) {
-    const { full, branch, maxFiles, verbose } = options;
-    logInfo(`Starting architecture scan for product ${productId}`);
-    const githubConfig = await getGitHubConfigByProduct(productId, verbose);
+    const { repoId, full, branch, maxFiles, verbose } = options;
+    if (!productId && !repoId) {
+        throw new Error('Provide a productId or --repo-id for find-architecture');
+    }
+    const scopeLabel = productId
+        ? `product ${productId}`
+        : `repository ${repoId}`;
+    logInfo(`Starting architecture scan for ${scopeLabel}`);
+    const githubConfig = productId
+        ? await getGitHubConfigByProduct(productId, verbose)
+        : await getGitHubConfigByRepository(repoId, verbose);
     if (!githubConfig.configured ||
         !githubConfig.token ||
         !githubConfig.owner ||
         !githubConfig.repo) {
-        logError(`GitHub not configured for product ${productId}: ${githubConfig.message || 'No installation found'}`);
+        logError(`GitHub not configured for ${scopeLabel}: ${githubConfig.message || 'No installation found'}`);
         process.exit(1);
     }
     const result = await scanForArchitecture({
         productId,
+        repoId,
         githubToken: githubConfig.token,
         owner: githubConfig.owner,
         repo: githubConfig.repo,

package/dist/commands/find-bugs/index.d.ts

@@ -3,9 +3,11 @@
  * Audits the product's repository for bugs and files each new finding as an issue.
  */
 export interface FindBugsCliOptions {
+    /** Repo-only mode: scan a single `repositories` row with no product. */
+    repoId?: string;
     full?: boolean;
     branch?: string;
     maxFiles?: number;
     verbose?: boolean;
 }
-export declare function runFindBugs(productId: string, options: FindBugsCliOptions): Promise<void>;
+export declare function runFindBugs(productId: string | undefined, options: FindBugsCliOptions): Promise<void>;

package/dist/commands/find-bugs/index.js

@@ -2,22 +2,31 @@
  * CLI command: edsger find-bugs <productId>
  * Audits the product's repository for bugs and files each new finding as an issue.
  */
-import { getGitHubConfigByProduct } from '../../api/github.js';
+import { getGitHubConfigByProduct, getGitHubConfigByRepository, } from '../../api/github.js';
 import { scanForBugs } from '../../phases/find-bugs/index.js';
 import { logError, logInfo, logSuccess } from '../../utils/logger.js';
 export async function runFindBugs(productId, options) {
-    const { full, branch, maxFiles, verbose } = options;
-    logInfo(`Starting bug scan for product ${productId}`);
-    const githubConfig = await getGitHubConfigByProduct(productId, verbose);
+    const { repoId, full, branch, maxFiles, verbose } = options;
+    if (!productId && !repoId) {
+        throw new Error('Provide a productId or --repo-id for find-bugs');
+    }
+    const scopeLabel = productId
+        ? `product ${productId}`
+        : `repository ${repoId}`;
+    logInfo(`Starting bug scan for ${scopeLabel}`);
+    const githubConfig = productId
+        ? await getGitHubConfigByProduct(productId, verbose)
+        : await getGitHubConfigByRepository(repoId, verbose);
     if (!githubConfig.configured ||
         !githubConfig.token ||
         !githubConfig.owner ||
         !githubConfig.repo) {
-        logError(`GitHub not configured for product ${productId}: ${githubConfig.message || 'No installation found'}`);
+        logError(`GitHub not configured for ${scopeLabel}: ${githubConfig.message || 'No installation found'}`);
         process.exit(1);
     }
     const result = await scanForBugs({
         productId,
+        repoId,
         githubToken: githubConfig.token,
         owner: githubConfig.owner,
         repo: githubConfig.repo,

package/dist/commands/find-smells/index.d.ts

@@ -5,6 +5,8 @@
  */
 import { type SmellCategory } from '../../phases/find-smells/types.js';
 export interface FindSmellsCliOptions {
+    /** Repo-only mode: scan a single `repositories` row with no product. */
+    repoId?: string;
     full?: boolean;
     branch?: string;
     maxFiles?: number;
@@ -18,4 +20,4 @@ export interface FindSmellsCliOptions {
  * matches user intuition for `--categories=`.
  */
 export declare function parseCategoriesOption(raw: string): SmellCategory[] | undefined;
-export declare function runFindSmells(productId: string, options: FindSmellsCliOptions): Promise<void>;
+export declare function runFindSmells(productId: string | undefined, options: FindSmellsCliOptions): Promise<void>;

package/dist/commands/find-smells/index.js

@@ -3,7 +3,7 @@
  * Audits the product's repository for code smells (refactor candidates, perf
  * cliffs, dead code, etc.) and files each new finding as an issue.
  */
-import { getGitHubConfigByProduct } from '../../api/github.js';
+import { getGitHubConfigByProduct, getGitHubConfigByRepository, } from '../../api/github.js';
 import { scanForSmells } from '../../phases/find-smells/index.js';
 import { isSmellCategory, SMELL_CATEGORIES, } from '../../phases/find-smells/types.js';
 import { logError, logInfo, logSuccess } from '../../utils/logger.js';
@@ -31,18 +31,27 @@ export function parseCategoriesOption(raw) {
     return Array.from(new Set(tokens));
 }
 export async function runFindSmells(productId, options) {
-    const { full, branch, maxFiles, categories, verbose } = options;
-    logInfo(`Starting smell scan for product ${productId}`);
-    const githubConfig = await getGitHubConfigByProduct(productId, verbose);
+    const { repoId, full, branch, maxFiles, categories, verbose } = options;
+    if (!productId && !repoId) {
+        throw new Error('Provide a productId or --repo-id for find-smells');
+    }
+    const scopeLabel = productId
+        ? `product ${productId}`
+        : `repository ${repoId}`;
+    logInfo(`Starting smell scan for ${scopeLabel}`);
+    const githubConfig = productId
+        ? await getGitHubConfigByProduct(productId, verbose)
+        : await getGitHubConfigByRepository(repoId, verbose);
     if (!githubConfig.configured ||
         !githubConfig.token ||
         !githubConfig.owner ||
         !githubConfig.repo) {
-        logError(`GitHub not configured for product ${productId}: ${githubConfig.message || 'No installation found'}`);
+        logError(`GitHub not configured for ${scopeLabel}: ${githubConfig.message || 'No installation found'}`);
         process.exit(1);
     }
     const result = await scanForSmells({
         productId,
+        repoId,
         githubToken: githubConfig.token,
         owner: githubConfig.owner,
         repo: githubConfig.repo,

package/dist/commands/quality-benchmark/index.d.ts

@@ -36,5 +36,10 @@ export interface QualityBenchmarkCliOptions {
     save?: boolean;
     /** Overwrite any existing report row for this (product, commit, rubric). */
     force?: boolean;
+    /**
+     * Evaluate the scope's quality gate against the report and exit non-zero if
+     * it fails — for use in CI ("fail the build"). No-op when no gate is set.
+     */
+    gate?: boolean;
 }
 export declare function runQualityBenchmarkCli(productId: string, options: QualityBenchmarkCliOptions): Promise<void>;

package/dist/commands/quality-benchmark/index.js

@@ -26,6 +26,7 @@ import { mkdirSync, writeFileSync } from 'node:fs';
 import { dirname, resolve } from 'node:path';
 import { getGitHubConfigByProduct, getGitHubConfigByRepository, getRepositoryBasics, } from '../../api/github.js';
 import { fetchProductBasics } from '../../phases/find-shared/mcp.js';
+import { evaluateGate, getQualityGate, } from '../../phases/quality-benchmark/gate.js';
 import { runQualityBenchmark, } from '../../phases/quality-benchmark/index.js';
 import { prepareQualityWorkspace } from '../../phases/quality-benchmark/workspace.js';
 import { saveQualityReport } from '../../services/quality-reports.js';
@@ -207,6 +208,33 @@ export async function runQualityBenchmarkCli(productId, options) {
     if (outcome.report.executive_summary) {
         logInfo(outcome.report.executive_summary);
     }
+    // Quality gate (CI enforcement). Evaluated against the report we just
+    // produced; a failing gate exits non-zero so a pipeline step can block.
+    if (options.gate) {
+        const scope = repoOnly
+            ? { repoId: options.repoId }
+            : { productId };
+        const gate = await getQualityGate(scope);
+        if (!gate) {
+            logInfo('Quality gate: none configured for this scope — skipping.');
+        }
+        else if (!gate.enabled) {
+            logInfo('Quality gate: disabled for this scope — skipping.');
+        }
+        else {
+            const result = evaluateGate(outcome.report, gate);
+            if (result.passed) {
+                logSuccess('Quality gate: PASS');
+            }
+            else {
+                logError('Quality gate: FAIL');
+                for (const v of result.violations) {
+                    logError(`  • ${v.label}: required ${v.required}, got ${v.actual}`);
+                }
+                process.exit(1);
+            }
+        }
+    }
 }
 /** Resolve a repository id to its "owner/repo" full name (RLS-scoped). */
 async function resolveRepositoryFullName(repositoryId) {

package/dist/index.js

@@ -9,6 +9,7 @@ import { runLogin, runLogout, runStatus } from './auth/login.js';
 import { runAdr } from './commands/adr/index.js';
 import { runAgentWorkflow } from './commands/agent-workflow/index.js';
 import { runAnalyzeLogs } from './commands/analyze-logs/index.js';
+import { runApiDocs } from './commands/api-docs/index.js';
 import { runAppStoreGeneration } from './commands/app-store/index.js';
 import { runArchitectureDiagram } from './commands/architecture-diagram/index.js';
 import { runBuild } from './commands/build/index.js';
@@ -802,8 +803,9 @@ program
 // Subcommand: edsger find-bugs <productId>
 // ============================================================
 program
-    .command('find-bugs <productId>')
-    .description("AI-audit a product's repository for bugs and file each new finding as an issue")
+    .command('find-bugs [productId]')
+    .description("AI-audit a product's (or a standalone repository's) repo for bugs and file each new finding as an issue")
+    .option('--repo-id <id>', 'Run in repo-only mode against a single repositories row (no product context)')
     .option('--full', 'Force a full scan even if previous-scan state exists')
     .option('--branch <name>', 'Branch to scan (defaults to repo default branch)')
     .option('--max-files <n>', 'Upper bound on files the auditor may Read (default 200)', (value) => {
@@ -836,6 +838,7 @@ program
     .option('--output <path>', 'Where to write the JSON report (default: ./quality-report-<commit>.json)')
     .option('--no-save', 'Skip the quality_reports/save MCP call (local-only run)')
     .option('--force', 'Overwrite any existing report row for this (product, commit, rubric)')
+    .option('--gate', "Evaluate the scope's quality gate against the report and exit non-zero if it fails (for CI). No-op when no gate is configured")
     .option('-v, --verbose', 'Print every progress event')
     .action(async (productId, opts) => {
     try {
@@ -1030,8 +1033,9 @@ program
 // Subcommand: edsger find-smells <productId>
 // ============================================================
 program
-    .command('find-smells <productId>')
-    .description("AI-audit a product's repository for code smells (refactor candidates, perf cliffs, dead code, type-safety gaps) and file each new finding as an issue")
+    .command('find-smells [productId]')
+    .description("AI-audit a product's (or a standalone repository's) repo for code smells (refactor candidates, perf cliffs, dead code, type-safety gaps) and file each new finding as an issue")
+    .option('--repo-id <id>', 'Run in repo-only mode against a single repositories row (no product context)')
     .option('--full', 'Force a full scan even if previous-scan state exists')
     .option('--branch <name>', 'Branch to scan (defaults to repo default branch)')
     .option('--max-files <n>', `Upper bound on files the auditor may Read (default ${FIND_SMELLS_DEFAULT_MAX_FILES})`, (value) => {
@@ -1055,8 +1059,9 @@ program
 // Subcommand: edsger find-architecture <productId>
 // ============================================================
 program
-    .command('find-architecture <productId>')
-    .description("AI-audit a product's repository for architectural concerns (layering, coupling, cycles, missing/duplicated abstractions, responsibility creep) and file each new finding as an issue")
+    .command('find-architecture [productId]')
+    .description("AI-audit a product's (or a standalone repository's) repo for architectural concerns (layering, coupling, cycles, missing/duplicated abstractions, responsibility creep) and file each new finding as an issue")
+    .option('--repo-id <id>', 'Run in repo-only mode against a single repositories row (no product context)')
     .option('--full', 'Force a full scan even if previous-scan state exists')
     .option('--branch <name>', 'Branch to scan (defaults to repo default branch)')
     .option('--max-files <n>', `Upper bound on files the auditor may Read (default ${FIND_ARCHITECTURE_DEFAULT_MAX_FILES})`, (value) => {
@@ -1139,6 +1144,33 @@ program
     }
 });
 // ============================================================
+// Subcommand: edsger api-docs <productId>
+// ============================================================
+program
+    .command('api-docs [productId]')
+    .description("Generate an API reference (Markdown + an optional OpenAPI 3.x document) for a product's (or standalone repository's) codebase by determining the API surface it exposes from its source. Writes against the pending api_doc_runs row identified by --run-id.")
+    .requiredOption('--run-id <id>', 'Pending api_doc_runs row id to drive (created by the desktop UI before invocation)')
+    .option('--repo-id <id>', 'Run in repo-only mode against a single repositories row (no product context)')
+    .option('-g, --guidance <text>', 'Human direction for the AI (focus areas, exclusions)')
+    .option('-v, --verbose', 'Verbose output')
+    .action(async (productId, opts) => {
+    try {
+        if (!productId && !opts.repoId) {
+            throw new Error('Provide a productId or --repo-id (repo-only mode) for api-docs');
+        }
+        await runApiDocs(productId, {
+            runId: opts.runId,
+            repoId: opts.repoId,
+            guidance: opts.guidance,
+            verbose: opts.verbose,
+        });
+    }
+    catch (error) {
+        logError(error instanceof Error ? error.message : String(error));
+        process.exit(1);
+    }
+});
+// ============================================================
 // Subcommand: edsger pr-resolve <productId>
 // ============================================================
 program

package/dist/phases/api-docs/index.d.ts

@@ -0,0 +1,47 @@
+/**
+ * API docs phase: clone the repository, ask Claude to work out the API surface
+ * it exposes, and persist a generated API reference (Markdown + an optional
+ * OpenAPI document) onto the pending api_doc_runs row.
+ *
+ * Production-grade behaviours (mirrors the recipes phase):
+ *
+ *   - Heartbeat: `last_heartbeat_at` on the api_doc_runs row is refreshed on
+ *     every assistant message so the reader can detect stalled / crashed runs
+ *     (see desktop-app/.../services/db/api-doc-runs.ts for the lazy reaper).
+ *   - Cancellation-safe writes: markRunning / persistAndSucceed / markFailed
+ *     only touch rows whose status is in {pending, running}. If the user
+ *     clicked Stop and the row is now 'cancelled', the final write no-ops.
+ *   - Capture-then-persist: the agent submits the reference via a single
+ *     `submit_api_docs` MCP tool; the artifact is written in one atomic update
+ *     alongside the success flip, so a run never leaves a half-written doc.
+ */
+import type { SupabaseClient } from '@supabase/supabase-js';
+import type { ApiDocsArtifact } from './types.js';
+export interface ApiDocsPhaseOptions {
+    /** Product-scoped run. Mutually exclusive with `repoId`. */
+    productId?: string;
+    /** Repo-only run: a single repositories row, no product context. */
+    repoId?: string;
+    runId: string;
+    guidance?: string;
+    verbose?: boolean;
+}
+export interface ApiDocsPhaseResult {
+    status: 'success' | 'error' | 'cancelled';
+    message: string;
+}
+export declare function runApiDocsPhase(options: ApiDocsPhaseOptions): Promise<ApiDocsPhaseResult>;
+/**
+ * Claim the row by flipping `pending` → `running`. Returns true on success and
+ * false when the row has already moved on (e.g. user cancelled before the CLI
+ * started). Bounded by the status filter so we can't resurrect a 'cancelled'
+ * row.
+ */
+export declare function markRunning(supabase: SupabaseClient, runId: string): Promise<boolean>;
+export declare function heartbeat(supabase: SupabaseClient, runId: string): Promise<void>;
+export declare function markFailed(supabase: SupabaseClient, runId: string, errorMessage: string): Promise<boolean>;
+/**
+ * Write the captured artifact AND flip the row to success in one update,
+ * bounded by the {pending, running} status filter so a cancelled run no-ops.
+ */
+export declare function persistAndSucceed(supabase: SupabaseClient, runId: string, artifact: ApiDocsArtifact): Promise<boolean>;

package/dist/phases/api-docs/index.js

@@ -0,0 +1,254 @@
+/**
+ * API docs phase: clone the repository, ask Claude to work out the API surface
+ * it exposes, and persist a generated API reference (Markdown + an optional
+ * OpenAPI document) onto the pending api_doc_runs row.
+ *
+ * Production-grade behaviours (mirrors the recipes phase):
+ *
+ *   - Heartbeat: `last_heartbeat_at` on the api_doc_runs row is refreshed on
+ *     every assistant message so the reader can detect stalled / crashed runs
+ *     (see desktop-app/.../services/db/api-doc-runs.ts for the lazy reaper).
+ *   - Cancellation-safe writes: markRunning / persistAndSucceed / markFailed
+ *     only touch rows whose status is in {pending, running}. If the user
+ *     clicked Stop and the row is now 'cancelled', the final write no-ops.
+ *   - Capture-then-persist: the agent submits the reference via a single
+ *     `submit_api_docs` MCP tool; the artifact is written in one atomic update
+ *     alongside the success flip, so a run never leaves a half-written doc.
+ */
+import { query } from '@anthropic-ai/claude-agent-sdk';
+import { getGitHubConfigByProduct, getGitHubConfigByRepository, getRepositoryBasics, } from '../../api/github.js';
+import { DEFAULT_MODEL } from '../../constants.js';
+import { getSupabase } from '../../supabase/client.js';
+import { logError, logInfo, logSuccess, logWarning, } from '../../utils/logger.js';
+import { cleanupIssueRepo, cloneIssueRepo, ensureWorkspaceDir, } from '../../workspace/workspace-manager.js';
+import { fetchProductBasics } from '../find-shared/mcp.js';
+import { createPromptGenerator, extractTextFromContent, } from '../pr-shared/agent-utils.js';
+import { createApiDocsCaptureState, createApiDocsMcpServer, } from './mcp-server.js';
+import { createApiDocsSystemPrompt, createApiDocsUserPrompt, } from './prompts.js';
+const WORKSPACE_KEY = 'api-docs';
+const MAX_TURNS = 200;
+// Heartbeat cadence: at most one DB write per HEARTBEAT_MIN_INTERVAL_MS.
+const HEARTBEAT_MIN_INTERVAL_MS = 15_000;
+export async function runApiDocsPhase(options) {
+    const { productId, repoId, runId, guidance, verbose } = options;
+    const repoOnly = !productId && Boolean(repoId);
+    if (productId) {
+        logInfo(`Starting API docs generation for product ${productId}`);
+    }
+    else {
+        logInfo(`Starting API docs generation for repository ${repoId}`);
+    }
+    const supabase = getSupabase();
+    const claimed = await markRunning(supabase, runId);
+    if (!claimed) {
+        return {
+            status: 'cancelled',
+            message: 'API docs run row is no longer in a runnable state (likely cancelled before the CLI started)',
+        };
+    }
+    // Resolve repo basics (name/description) for the prompt.
+    let repoBasics = {
+        fullName: null,
+        description: null,
+    };
+    if (repoOnly) {
+        const basics = await getRepositoryBasics(repoId);
+        repoBasics = { fullName: basics.fullName, description: basics.description };
+    }
+    const githubConfig = repoOnly
+        ? await getGitHubConfigByRepository(repoId, verbose)
+        : await getGitHubConfigByProduct(productId, verbose);
+    if (!githubConfig.configured ||
+        !githubConfig.token ||
+        !githubConfig.owner ||
+        !githubConfig.repo) {
+        const msg = githubConfig.message ||
+            (repoOnly
+                ? 'GitHub repository not configured. Connect the repo first.'
+                : 'GitHub repository not configured for this product. Connect a repo first.');
+        await markFailed(supabase, runId, msg);
+        return { status: 'error', message: msg };
+    }
+    let repoPath;
+    let succeeded = false;
+    try {
+        const workspaceRoot = ensureWorkspaceDir();
+        const repoKey = repoOnly
+            ? `${WORKSPACE_KEY}-repo-${repoId}`
+            : `${WORKSPACE_KEY}-${productId}`;
+        ({ repoPath } = cloneIssueRepo(workspaceRoot, repoKey, githubConfig.owner, githubConfig.repo, githubConfig.token));
+        const basics = repoOnly
+            ? {
+                name: repoBasics.fullName ?? `${githubConfig.owner}/${githubConfig.repo}`,
+                description: repoBasics.description ?? undefined,
+            }
+            : await fetchProductBasics(productId);
+        const systemPrompt = createApiDocsSystemPrompt();
+        const userPrompt = createApiDocsUserPrompt({
+            repoName: basics.name,
+            repoDescription: basics.description,
+            guidance,
+        });
+        const capture = createApiDocsCaptureState();
+        const mcpServer = createApiDocsMcpServer(capture);
+        logInfo('Running Claude agent to generate API docs...');
+        let lastHeartbeatAt = 0;
+        for await (const message of query({
+            prompt: createPromptGenerator(userPrompt),
+            options: {
+                systemPrompt: {
+                    type: 'preset',
+                    preset: 'claude_code',
+                    append: systemPrompt,
+                },
+                model: DEFAULT_MODEL,
+                maxTurns: MAX_TURNS,
+                permissionMode: 'bypassPermissions',
+                cwd: repoPath,
+                mcpServers: {
+                    'api-docs': mcpServer,
+                },
+            },
+        })) {
+            if (message.type === 'assistant') {
+                extractTextFromContent(message.message?.content ?? [], verbose);
+                const now = Date.now();
+                if (now - lastHeartbeatAt >= HEARTBEAT_MIN_INTERVAL_MS) {
+                    lastHeartbeatAt = now;
+                    await heartbeat(supabase, runId);
+                }
+                continue;
+            }
+            if (message.type !== 'result') {
+                continue;
+            }
+            if (message.subtype !== 'success') {
+                const msg = `API docs generation failed: agent ${message.subtype}`;
+                const written = await markFailed(supabase, runId, msg);
+                return {
+                    status: written ? 'error' : 'cancelled',
+                    message: written
+                        ? msg
+                        : 'Run was cancelled while the agent was running',
+                };
+            }
+            if (!capture.captured) {
+                const msg = 'Agent finished without calling submit_api_docs — no reference was produced.';
+                const written = await markFailed(supabase, runId, msg);
+                return {
+                    status: written ? 'error' : 'cancelled',
+                    message: written ? msg : 'Run was cancelled before completion',
+                };
+            }
+            const written = await persistAndSucceed(supabase, runId, capture.captured);
+            if (!written) {
+                return {
+                    status: 'cancelled',
+                    message: 'Run was cancelled before the result could be written',
+                };
+            }
+            succeeded = true;
+            const ep = capture.captured.endpointCount;
+            logSuccess(`API docs generated (${ep} endpoint${ep === 1 ? '' : 's'}${capture.captured.openapi ? ', with OpenAPI spec' : ''}).`);
+            return {
+                status: 'success',
+                message: `API docs generated (${ep} endpoint${ep === 1 ? '' : 's'}).`,
+            };
+        }
+        const msg = 'API docs generation ended without a result message';
+        await markFailed(supabase, runId, msg);
+        return { status: 'error', message: msg };
+    }
+    catch (error) {
+        const errorMessage = error instanceof Error ? error.message : String(error);
+        logError(`API docs generation failed: ${errorMessage}`);
+        await markFailed(supabase, runId, errorMessage);
+        return { status: 'error', message: errorMessage };
+    }
+    finally {
+        if (succeeded) {
+            cleanupIssueRepo(repoPath);
+        }
+    }
+}
+// ============================================================================
+// DB helpers — exported for unit tests
+// ============================================================================
+/**
+ * Claim the row by flipping `pending` → `running`. Returns true on success and
+ * false when the row has already moved on (e.g. user cancelled before the CLI
+ * started). Bounded by the status filter so we can't resurrect a 'cancelled'
+ * row.
+ */
+export async function markRunning(supabase, runId) {
+    const { data, error } = await supabase
+        .from('api_doc_runs')
+        .update({
+        status: 'running',
+        error: null,
+        last_heartbeat_at: new Date().toISOString(),
+    })
+        .eq('id', runId)
+        .in('status', ['pending', 'running'])
+        .select('id')
+        .maybeSingle();
+    if (error) {
+        logWarning(`Could not mark run as running: ${error.message}`);
+        return false;
+    }
+    return data !== null;
+}
+export async function heartbeat(supabase, runId) {
+    const { error } = await supabase
+        .from('api_doc_runs')
+        .update({ last_heartbeat_at: new Date().toISOString() })
+        .eq('id', runId)
+        .eq('status', 'running');
+    if (error) {
+        logWarning(`Heartbeat failed: ${error.message}`);
+    }
+}
+export async function markFailed(supabase, runId, errorMessage) {
+    const { data, error } = await supabase
+        .from('api_doc_runs')
+        .update({
+        status: 'failed',
+        error: errorMessage,
+        completed_at: new Date().toISOString(),
+    })
+        .eq('id', runId)
+        .in('status', ['pending', 'running'])
+        .select('id')
+        .maybeSingle();
+    if (error) {
+        logWarning(`Could not mark run as failed: ${error.message}`);
+        return false;
+    }
+    return data !== null;
+}
+/**
+ * Write the captured artifact AND flip the row to success in one update,
+ * bounded by the {pending, running} status filter so a cancelled run no-ops.
+ */
+export async function persistAndSucceed(supabase, runId, artifact) {
+    const { data, error } = await supabase
+        .from('api_doc_runs')
+        .update({
+        status: 'success',
+        error: null,
+        openapi: artifact.openapi,
+        markdown: artifact.markdown,
+        summary: artifact.summary,
+        endpoint_count: artifact.endpointCount,
+        completed_at: new Date().toISOString(),
+    })
+        .eq('id', runId)
+        .in('status', ['pending', 'running'])
+        .select('id')
+        .maybeSingle();
+    if (error) {
+        logWarning(`Could not persist API docs: ${error.message}`);
+        return false;
+    }
+    return data !== null;
+}