edsger 0.76.0 → 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/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';
@@ -837,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 {
@@ -1142,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;
+}

package/dist/phases/api-docs/mcp-server.d.ts

@@ -0,0 +1,25 @@
+/**
+ * In-process MCP server exposing a single api-docs tool:
+ *
+ *   - submit_api_docs  capture the generated API reference (Markdown + an
+ *                      optional OpenAPI document + summary + endpoint count)
+ *
+ * Unlike the recipes toolkit (which commits each mutation as it goes) the
+ * api-docs artifact is a single document, so the tool just captures into an
+ * in-memory buffer. The orchestrator persists the captured artifact and flips
+ * the run row to success once the agent's turn ends — a clean all-or-nothing
+ * write that can't leave a half-written reference behind.
+ */
+import { z } from 'zod';
+import { type ApiDocsArtifact } from './types.js';
+export interface ApiDocsCaptureState {
+    captured: ApiDocsArtifact | null;
+}
+export declare function createApiDocsCaptureState(): ApiDocsCaptureState;
+export declare function createSubmitApiDocsTool(capture: ApiDocsCaptureState): import("@anthropic-ai/claude-agent-sdk").SdkMcpToolDefinition<{
+    markdown: z.ZodString;
+    summary: z.ZodString;
+    endpoint_count: z.ZodNumber;
+    openapi_json: z.ZodOptional<z.ZodString>;
+}>;
+export declare function createApiDocsMcpServer(capture: ApiDocsCaptureState): import("@anthropic-ai/claude-agent-sdk").McpSdkServerConfigWithInstance;

package/dist/phases/api-docs/mcp-server.js

@@ -0,0 +1,82 @@
+/**
+ * In-process MCP server exposing a single api-docs tool:
+ *
+ *   - submit_api_docs  capture the generated API reference (Markdown + an
+ *                      optional OpenAPI document + summary + endpoint count)
+ *
+ * Unlike the recipes toolkit (which commits each mutation as it goes) the
+ * api-docs artifact is a single document, so the tool just captures into an
+ * in-memory buffer. The orchestrator persists the captured artifact and flips
+ * the run row to success once the agent's turn ends — a clean all-or-nothing
+ * write that can't leave a half-written reference behind.
+ */
+import { createSdkMcpServer, tool } from '@anthropic-ai/claude-agent-sdk';
+import { z } from 'zod';
+import { API_DOCS_MARKDOWN_MAX, API_DOCS_SUMMARY_MAX, } from './types.js';
+export function createApiDocsCaptureState() {
+    return { captured: null };
+}
+function textError(message) {
+    return {
+        content: [{ type: 'text', text: message }],
+        isError: true,
+    };
+}
+function textOk(message) {
+    return {
+        content: [{ type: 'text', text: message }],
+    };
+}
+export function createSubmitApiDocsTool(capture) {
+    return tool('submit_api_docs', 'Submit the final API reference for this repository. Call this exactly once, at the end, after you have explored the codebase. Provide a Markdown reference (always) and, when the repo exposes an HTTP API, a complete OpenAPI 3.x document as a JSON string.', {
+        markdown: z
+            .string()
+            .min(1)
+            .max(API_DOCS_MARKDOWN_MAX)
+            .describe('The human-readable API reference in Markdown. Document each endpoint / exported interface: method + path (or signature), purpose, parameters, request/response shapes, auth, and an example where useful.'),
+        summary: z
+            .string()
+            .min(1)
+            .max(API_DOCS_SUMMARY_MAX)
+            .describe('One-paragraph overview of the API surface (what it exposes and how it is consumed).'),
+        endpoint_count: z
+            .number()
+            .int()
+            .min(0)
+            .describe('How many distinct endpoints / operations the reference documents (0 if the repo exposes no callable API surface).'),
+        openapi_json: z
+            .string()
+            .optional()
+            .describe('A complete OpenAPI 3.x document serialized as a JSON string. Omit when the repository exposes no HTTP API (e.g. a library or CLI).'),
+    }, async (args) => {
+        let openapi = null;
+        if (args.openapi_json && args.openapi_json.trim()) {
+            try {
+                const parsed = JSON.parse(args.openapi_json);
+                if (typeof parsed !== 'object' ||
+                    parsed === null ||
+                    Array.isArray(parsed)) {
+                    return textError('openapi_json must be a JSON object (an OpenAPI document), not an array or scalar.');
+                }
+                openapi = parsed;
+            }
+            catch (error) {
+                return textError(`openapi_json is not valid JSON: ${error instanceof Error ? error.message : String(error)}`);
+            }
+        }
+        capture.captured = {
+            openapi,
+            markdown: args.markdown,
+            summary: args.summary.trim(),
+            endpointCount: args.endpoint_count,
+        };
+        return textOk(`API docs captured (${args.endpoint_count} endpoint${args.endpoint_count === 1 ? '' : 's'}${openapi ? ', with OpenAPI spec' : ''}). You can end your turn now.`);
+    });
+}
+export function createApiDocsMcpServer(capture) {
+    return createSdkMcpServer({
+        name: 'api-docs',
+        version: '1.0.0',
+        tools: [createSubmitApiDocsTool(capture)],
+    });
+}

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

@@ -0,0 +1,16 @@
+/**
+ * Prompts for the api-docs phase.
+ *
+ * Agent's job: explore the cloned repository, work out what API surface it
+ * exposes (HTTP/REST routes, RPC handlers, edge functions, exported SDK
+ * functions, CLI commands — whatever the repo actually offers), and produce
+ * an API reference. Output is submitted via the single `submit_api_docs` MCP
+ * tool — no fenced JSON, no chat summary.
+ */
+export interface ApiDocsPromptContext {
+    repoName: string;
+    repoDescription?: string;
+    guidance?: string;
+}
+export declare function createApiDocsSystemPrompt(): string;
+export declare function createApiDocsUserPrompt(ctx: ApiDocsPromptContext): string;

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

@@ -0,0 +1,65 @@
+/**
+ * Prompts for the api-docs phase.
+ *
+ * Agent's job: explore the cloned repository, work out what API surface it
+ * exposes (HTTP/REST routes, RPC handlers, edge functions, exported SDK
+ * functions, CLI commands — whatever the repo actually offers), and produce
+ * an API reference. Output is submitted via the single `submit_api_docs` MCP
+ * tool — no fenced JSON, no chat summary.
+ */
+export function createApiDocsSystemPrompt() {
+    return `You are a senior engineer writing the API reference for a codebase.
+
+The current working directory is a fresh clone of the repository. Use Glob/Grep/Read (and Bash for git/log when helpful) to explore it before writing anything.
+
+## Step 1 — Determine the API surface
+
+Repositories expose their API in different ways. Figure out which apply here (a repo may have more than one):
+- **HTTP / REST** — route definitions, controllers, request handlers (Express/Fastify/Next.js route handlers, Flask/FastAPI/Django, Spring, Go net/http, etc.).
+- **Action-routed / RPC functions** — e.g. serverless / edge functions dispatched by an \`action\` field on the body, gRPC services, tRPC routers.
+- **Library / SDK** — the public, exported functions/classes other code imports. Document the exported surface, not internal helpers.
+- **CLI** — the commands and flags the tool exposes.
+
+Do NOT assume it is REST. Read the code and document what is actually there.
+
+## Step 2 — Produce two artifacts
+
+1. **Markdown reference (always).** A clear, navigable reference. For each endpoint / operation / exported function document: its identifier (method + path, or signature), purpose, parameters (name, type, required, description), request body and response shapes, auth/permissions, and a short example where it helps. Group by resource/module. Note relative file paths so readers can jump to the source.
+
+2. **OpenAPI 3.x document (only when the repo exposes an HTTP API).** A complete, spec-valid OpenAPI document covering the HTTP endpoints — paths, methods, parameters, requestBody/response schemas under \`components.schemas\`, and security schemes. Omit this entirely for pure libraries or CLIs (there is nothing meaningful to put in an OpenAPI \`paths\` object).
+
+## Output protocol
+
+Submit your result with the \`submit_api_docs\` MCP tool — call it EXACTLY ONCE at the end:
+
+- \`markdown\` — the full Markdown reference.
+- \`summary\` — one paragraph describing the API surface.
+- \`endpoint_count\` — the number of distinct endpoints/operations you documented (0 for a non-callable surface).
+- \`openapi_json\` — the OpenAPI document as a JSON string, or omit it when there is no HTTP API.
+
+Do NOT paste the reference into chat. Do NOT wrap it in fenced code blocks in a message. Explore, then call the tool, then end your turn.
+
+## Rules
+
+- Ground everything in the actual source. Don't invent endpoints, parameters, or response fields. If something is ambiguous, describe what the code does and say so.
+- Keep the Markdown focused on the externally-callable surface. Don't document private/internal helpers as if they were API.
+- Prefer accuracy over completeness padding: a small repo gets a short, correct reference.`;
+}
+export function createApiDocsUserPrompt(ctx) {
+    const lines = [];
+    lines.push(`# Repository: ${ctx.repoName}`);
+    if (ctx.repoDescription) {
+        lines.push('');
+        lines.push('## Description');
+        lines.push(ctx.repoDescription);
+    }
+    if (ctx.guidance && ctx.guidance.trim()) {
+        lines.push('');
+        lines.push('## Reviewer guidance (focus or exclusions)');
+        lines.push(ctx.guidance.trim());
+    }
+    lines.push('');
+    lines.push('## Task');
+    lines.push('Explore the cloned repository, determine what API surface it exposes, and write its API reference. Then call `submit_api_docs` exactly once with the Markdown reference, a one-paragraph summary, the endpoint count, and (only if the repo exposes an HTTP API) the OpenAPI document as a JSON string. End your turn after submitting.');
+    return lines.join('\n');
+}