codecartographer-pi 0.20.0 → 0.21.0

package/dist/mcp-server/server.js

@@ -17,7 +17,7 @@ import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js"
 import { CallToolRequestSchema, ErrorCode, ListToolsRequestSchema, McpError, } from "@modelcontextprotocol/sdk/types.js";
 import { mkdir, readFile, readdir, rename, writeFile } from "node:fs/promises";
 import { basename, isAbsolute, join } from "node:path";
-import { buildPhasePrompt, buildSkillPrompt, buildValidationSummary, BROADSIDE_DIR, broadsideDirFor, BROADSIDE_LENS_IDS, BROADSIDE_SKILL_NAME, backupWorkspaceState, canonicalPath, copyPackagedWorkspace, collectResultText, completeValidatedPhase, computePerPhaseTotals, computeTotals, createEmptyStatus, DEFAULT_PIPELINE_PATH, deriveSlug, discoverLibrary, describeScaffoldStaleness, detectProvenanceConflicts, estimateSubmitText, getLens, describeDanglingCarryForward, describeMissingCompletedOutputs, getNextEligiblePhase, getPipelineLabel, getWorkspaceState, isValidSlug, isWithinPathResolved, listBatchModels, listEntries, listGuideTopics, loadBroadsideConfig, modelsText, readGuide, listMissingCompletedOutputs, listSkillNames, resolveSkillName, loadCodecartoConfig, loadUsage, loadYamlFile, normalizeForComparison, PACKAGE_VERSION, packagedWorkspaceDir, pathExists, PhasePreflightError, previewPublishVersion, publishEntry, reindex as libraryReindex, refreshScaffold, resolvePhase, resolvePipelineChoice, readBroadsideSkill, runBroadsideCollect, runBroadsideStatus, runBroadsideSubmit, seedOrchestratorFiles, statusText, stringifySimpleYaml, switchPipeline, validatePhaseOutput, writeLibraryConfig, writeDashboard, } from "../core/index.js";
+import { buildPhasePrompt, buildSkillPrompt, buildValidationSummary, BROADSIDE_DIR, broadsideDirFor, BROADSIDE_LENS_IDS, BROADSIDE_SKILL_NAME, BroadsideConfigError, defaultBroadsideConfig, backupWorkspaceState, canonicalPath, copyPackagedWorkspace, collectResultText, completeValidatedPhase, computePerPhaseTotals, computeTotals, createEmptyStatus, DEFAULT_PIPELINE_PATH, deriveSlug, discoverLibrary, describeScaffoldStaleness, detectProvenanceConflicts, estimateSubmitText, getLens, describeDanglingCarryForward, describeMissingCompletedOutputs, describeStuckPipeline, getPipelineLabel, getWorkspaceState, isValidSlug, isWithinPathResolved, listBatchModels, listEntries, listGuideTopics, loadBroadsideConfig, modelsText, readGuide, listMissingCompletedOutputs, listSkillNames, resolvePipelineOutcome, resolveSkillName, loadCodecartoConfig, loadUsage, loadYamlFile, normalizeForComparison, PACKAGE_VERSION, packagedWorkspaceDir, pathExists, PhasePreflightError, previewPublishVersion, publishEntry, reindex as libraryReindex, refreshScaffold, resolvePhase, resolvePipelineChoice, readBroadsideSkill, runBroadsideCollect, runBroadsideStatus, runBroadsideSubmit, seedOrchestratorFiles, statusText, stringifySimpleYaml, switchPipeline, validatePhaseOutput, writeLibraryConfig, writeDashboard, } from "../core/index.js";
 import { applyAmendment } from "../core/amendment.js";
 import { appendUsageRun } from "../core/usage.js";
 import { initLibrary } from "../core/library.js";
@@ -69,8 +69,12 @@ async function optionalCwd(cwd) {
     return validateCwd(cwd.trim());
 }
 async function requireWorkspace(cwd) {
+    // What getWorkspaceState throws is the user's to fix — a status.yaml that
+    // does not parse, a missing `pipeline:`, a pipeline file that is not there
+    // — so it is InvalidRequest, not the InternalError a host would retry or
+    // report as a server bug (self-audit mech 2.8).
     const state = await getWorkspaceState(cwd).catch((error) => {
-        throw new McpError(ErrorCode.InternalError, error instanceof Error ? error.message : String(error));
+        throw new McpError(ErrorCode.InvalidRequest, error instanceof Error ? error.message : String(error));
     });
     if (!state) {
         throw new McpError(ErrorCode.InvalidRequest, `No CodeCartographer workspace at ${cwd}. Call codecarto_init first.`);
@@ -89,9 +93,9 @@ function textResult(text, structured) {
         structuredContent: { ...structured, text },
     };
 }
-async function buildMcpPhasePrompt(state, phase, forced) {
+async function buildMcpPhasePrompt(state, phase, forced, auto = false) {
     try {
-        return await buildPhasePrompt(state, phase, forced);
+        return await buildPhasePrompt(state, phase, forced, { auto });
     }
     catch (error) {
         if (error instanceof PhasePreflightError) {
@@ -188,8 +192,11 @@ export async function handleInit(args) {
 export async function handleStatus(args) {
     const cwd = await validateCwd(args.cwd);
     const state = await requireWorkspace(cwd);
-    const nextPhase = getNextEligiblePhase(state);
-    const currentPhase = nextPhase?.id ?? state.status.current_phase ?? "complete";
+    const outcome = resolvePipelineOutcome(state);
+    const nextPhase = outcome.kind === "eligible" ? outcome.phase : null;
+    // "complete" is the terminal marker; a stuck pipeline sits on its first
+    // blocked phase and says so below (#228).
+    const currentPhase = outcome.kind === "eligible" ? outcome.phase.id : outcome.kind === "stuck" ? outcome.blocked[0].phaseId : "complete";
     const completed = state.pipeline.phase_order.filter((id) => state.status.phases[id]?.status === "complete").length;
     const totalCarryForward = Object.values(state.status.phases).reduce((sum, phase) => sum + (phase.carry_forward?.length ?? 0), 0);
     const currentOpenQuestions = currentPhase === "complete" ? 0 : state.status.phases[currentPhase]?.open_questions?.length ?? 0;
@@ -199,7 +206,7 @@ export async function handleStatus(args) {
     const missingOutputs = await listMissingCompletedOutputs(state);
     const summaryLines = [
         `Phase: ${currentPhase}`,
-        `Pipeline state: ${currentPhase === "complete" ? "complete" : "in progress"}`,
+        `Pipeline state: ${outcome.kind === "eligible" ? "in progress" : outcome.kind}`,
         `Pipeline: ${getPipelineLabel(state.status.pipeline)} (${state.status.pipeline})`,
         `Progress: ${completed}/${state.pipeline.phase_order.length} complete`,
         `Open questions (terminal unresolved): ${terminalOpenQuestions}`,
@@ -212,6 +219,8 @@ export async function handleStatus(args) {
             ? state.status.next_actions.map((action, index) => `${index === 0 ? "Next: " : "      "}${action}`)
             : [`Next: ${nextPhase ? `Begin ${nextPhase.id}` : "All phases complete."}`]),
     ];
+    if (outcome.kind === "stuck")
+        summaryLines.push(describeStuckPipeline(outcome.blocked));
     if (scaffoldNotice)
         summaryLines.push(`Scaffold: ${scaffoldNotice}`);
     summaryLines.push(...describeMissingCompletedOutputs(missingOutputs));
@@ -219,6 +228,8 @@ export async function handleStatus(args) {
     return textResult(summary, {
         ...(scaffoldNotice ? { scaffoldNotice } : {}),
         ...(missingOutputs.length > 0 ? { missingOutputs } : {}),
+        ...(outcome.kind === "stuck" ? { stuck: outcome.blocked } : {}),
+        pipelineState: outcome.kind === "eligible" ? "in progress" : outcome.kind,
         currentPhase,
         pipeline: state.status.pipeline,
         pipelineLabel: getPipelineLabel(state.status.pipeline),
@@ -271,14 +282,24 @@ export async function handleSwitchPipeline(args) {
 export async function handleNext(args) {
     const cwd = await validateCwd(args.cwd);
     const state = await requireWorkspace(cwd);
-    const phase = getNextEligiblePhase(state);
-    if (!phase) {
+    const outcome = resolvePipelineOutcome(state);
+    if (outcome.kind === "stuck") {
+        // Not a result: a host looping on codecarto_next would read a text
+        // answer as "done" (#228). There is no prompt to hand out until the
+        // pipeline file is fixed.
+        throw new McpError(ErrorCode.InvalidRequest, describeStuckPipeline(outcome.blocked));
+    }
+    if (outcome.kind === "complete") {
         return textResult("All CodeCartographer phases are complete. Run codecarto_skill for post-pipeline work.", {
             complete: true,
         });
     }
-    const prompt = await buildMcpPhasePrompt(state, phase, false);
-    return textResult(prompt, { phase: phase.id, forced: false });
+    // `unattended` is the MCP spelling of Pi's --auto: nobody is there to
+    // answer the reimplementation-spec phase's Strategic Alignment Hook, so
+    // the prompt carries the auto-default instruction instead (#270).
+    const unattended = args.unattended === true;
+    const prompt = await buildMcpPhasePrompt(state, outcome.phase, false, unattended);
+    return textResult(prompt, { phase: outcome.phase.id, forced: false, unattended });
 }
 export async function handlePhase(args) {
     if (typeof args.phase !== "string" || !args.phase.trim()) {
@@ -290,8 +311,9 @@ export async function handlePhase(args) {
     if (!phase) {
         throw new McpError(ErrorCode.InvalidParams, `Unknown phase: ${args.phase}`);
     }
-    const prompt = await buildMcpPhasePrompt(state, phase, true);
-    return textResult(prompt, { phase: phase.id, forced: true });
+    const unattended = args.unattended === true;
+    const prompt = await buildMcpPhasePrompt(state, phase, true, unattended);
+    return textResult(prompt, { phase: phase.id, forced: true, unattended });
 }
 export async function handleValidate(args) {
     const cwd = await validateCwd(args.cwd);
@@ -391,9 +413,12 @@ export async function handleSkill(args) {
         return textResult(skill.content, { skill: BROADSIDE_SKILL_NAME, path: skill.path, postPipeline: false });
     }
     const state = await requireWorkspace(cwd);
-    const nextPhase = getNextEligiblePhase(state);
-    if (nextPhase) {
-        throw new McpError(ErrorCode.InvalidRequest, `Cannot run skill: pipeline is not complete (next phase: ${nextPhase.id}). Finish the pipeline first.`);
+    const outcome = resolvePipelineOutcome(state);
+    if (outcome.kind === "eligible") {
+        throw new McpError(ErrorCode.InvalidRequest, `Cannot run skill: pipeline is not complete (next phase: ${outcome.phase.id}). Finish the pipeline first.`);
+    }
+    if (outcome.kind === "stuck") {
+        throw new McpError(ErrorCode.InvalidRequest, `Cannot run skill: the pipeline is not complete. ${describeStuckPipeline(outcome.blocked)}`);
     }
     // Resolve against the installed list only: the name is never joined onto a
     // path, so a traversal like `../findings/architecture` cannot splice a
@@ -883,8 +908,16 @@ export async function handleOpen(args) {
         throw new McpError(ErrorCode.InvalidRequest, "No existing CodeCartographer workspace found. Run codecarto_init first.");
     }
     const state = await requireWorkspace(cwd);
-    const nextPhase = getNextEligiblePhase(state)?.id ?? "complete";
-    return textResult(`Opened existing CodeCartographer workspace: ${getPipelineLabel(state.status.pipeline)}. Current phase: ${nextPhase}.`, { pipeline: getPipelineLabel(state.status.pipeline), currentPhase: nextPhase });
+    const outcome = resolvePipelineOutcome(state);
+    const nextPhase = outcome.kind === "eligible" ? outcome.phase.id : outcome.kind === "stuck" ? `${outcome.blocked[0].phaseId} (stuck)` : "complete";
+    const lines = [`Opened existing CodeCartographer workspace: ${getPipelineLabel(state.status.pipeline)}. Current phase: ${nextPhase}.`];
+    if (outcome.kind === "stuck")
+        lines.push(describeStuckPipeline(outcome.blocked));
+    return textResult(lines.join("\n"), {
+        pipeline: getPipelineLabel(state.status.pipeline),
+        currentPhase: nextPhase,
+        ...(outcome.kind === "stuck" ? { stuck: outcome.blocked } : {}),
+    });
 }
 export async function handleUsage(args) {
     const cwd = await validateCwd(args.cwd);
@@ -1007,18 +1040,40 @@ export async function handleBroadside(args) {
     if (!["submit", "collect", "status", "models"].includes(action)) {
         throw new McpError(ErrorCode.InvalidParams, `Unknown action: ${action}. Valid actions: submit, collect, status, models.`);
     }
-    const config = await loadBroadsideConfig(broadsideDirFor(cwd));
+    // A config.yaml that exists but cannot be read refuses every action that
+    // would act on it (#232); status only reads recorded runs, so it answers
+    // and says the file is unreadable. A corrupt state.json refuses even that:
+    // there is nothing trustworthy to report and nothing may write over it (#233).
+    let config;
+    let configWarning = null;
+    try {
+        config = await loadBroadsideConfig(broadsideDirFor(cwd));
+    }
+    catch (error) {
+        if (!(error instanceof BroadsideConfigError) || action !== "status") {
+            throw new McpError(ErrorCode.InvalidRequest, error instanceof Error ? error.message : String(error));
+        }
+        config = defaultBroadsideConfig();
+        configWarning = error.message;
+    }
     if (action === "status") {
-        const { state } = await runBroadsideStatus(cwd);
-        return textResult(statusText(state), { state });
+        const { state } = await runBroadsideStatus(cwd).catch((error) => {
+            throw new McpError(ErrorCode.InvalidRequest, error instanceof Error ? error.message : String(error));
+        });
+        const lines = [statusText(state)];
+        if (configWarning)
+            lines.push(`Warning: ${configWarning}`);
+        return textResult(lines.join("\n"), { state, ...(configWarning ? { configWarning } : {}) });
     }
     const apiKey = resolveBroadsideApiKey(args.api_key, config);
     // Every run knob resolves the same way: explicit parameter, else the repo's
     // config.yaml default, else the shipped default baked into loadBroadsideConfig.
-    const waitSeconds = typeof args.wait_seconds === "number" && args.wait_seconds > 0
+    // An explicit 0 means "poll once and return": it used to fall through to
+    // the config default and, as undefined, to the 25-minute budget (#230).
+    const waitSeconds = typeof args.wait_seconds === "number" && args.wait_seconds >= 0
         ? args.wait_seconds
         : config.waitSeconds;
-    const waitMs = waitSeconds > 0 ? waitSeconds * 1000 : undefined;
+    const waitMs = waitSeconds * 1000;
     const includeSynthesis = args.include_synthesis ?? config.includeSynthesis;
     const includeTriage = args.include_triage ?? config.includeTriage;
     const retryTruncated = args.retry_truncated ?? config.retryTruncated;
@@ -1047,7 +1102,9 @@ export async function handleBroadside(args) {
         else {
             lenses = config.defaultLenses;
         }
-        const maxCost = typeof args.max_cost === "number" && args.max_cost > 0 ? args.max_cost : config.maxCost;
+        // An explicit 0 is "no limit" (#231); absent falls back to config.yaml,
+        // whose own default is BROADSIDE_DEFAULT_MAX_COST.
+        const maxCost = typeof args.max_cost === "number" && args.max_cost >= 0 ? args.max_cost : config.maxCost;
         const result = await runBroadsideSubmit(cwd, apiKey, {
             lenses,
             model: config.model,
@@ -1084,11 +1141,13 @@ export async function handleBroadside(args) {
         });
     }
     // action === "collect"
+    const runId = typeof args.run_id === "string" && args.run_id.trim() ? args.run_id.trim() : undefined;
     const collect = await runBroadsideCollect(cwd, apiKey, {
         waitMs,
         includeSynthesis,
         includeTriage,
         retryTruncated,
+        ...(runId && { runId }),
     }).catch((error) => {
         throw new McpError(ErrorCode.InvalidRequest, error instanceof Error ? error.message : String(error));
     });
@@ -1156,7 +1215,13 @@ const TOOLS = [
         description: "Return the prompt text for the next eligible CodeCartographer phase. The host should feed this prompt back to the agent or display it to the user.",
         inputSchema: {
             type: "object",
-            properties: { cwd: { type: "string", description: "Absolute path to the target repository." } },
+            properties: {
+                cwd: { type: "string", description: "Absolute path to the target repository." },
+                unattended: {
+                    type: "boolean",
+                    description: "Set when no user is in the loop to answer the prompt's questions (an autonomous run). The reimplementation-spec prompt then defaults to the language-agnostic variant and records selection: auto-default instead of asking which variant to build, and every interactive hook is suppressed. Same as Pi's /codecarto-next --auto.",
+                },
+            },
             required: ["cwd"],
         },
     },
@@ -1168,6 +1233,7 @@ const TOOLS = [
             properties: {
                 cwd: { type: "string", description: "Absolute path to the target repository." },
                 phase: { type: "string", description: "Phase id from the active pipeline." },
+                unattended: { type: "boolean", description: "As for codecarto_next: no user is in the loop, so interactive hooks default and record their choice instead of asking." },
             },
             required: ["cwd", "phase"],
         },
@@ -1186,7 +1252,7 @@ const TOOLS = [
     },
     {
         name: "codecarto_complete",
-        description: "Mark a phase complete. Requires the phase output's validation to be PASS or PASS WITH GAPS. Atomically updates status.yaml under a file lock, appends to THREAD_LOG.md, and creates a closeout stub from the template if one does not yet exist. If phase is omitted, completes the next eligible phase.",
+        description: "Mark a phase complete. Requires the phase output's validation to be PASS or PASS WITH GAPS and applies the phase handoff at scratch/handoffs/<phase>.yaml. Atomically updates status.yaml under a file lock, appends one THREAD_LOG.md entry, and writes the phase's closeout: the handoff's closeout_content (plus its decisions) overwrites the canonical <date>-<phase>.md when supplied; otherwise a stub is copied from the template only if no closeout exists yet. If phase is omitted, completes the next eligible phase.",
         inputSchema: {
             type: "object",
             properties: {
@@ -1412,11 +1478,15 @@ const TOOLS = [
                 },
                 api_key: {
                     type: "string",
-                    description: "OpenRouter API key. Prefer the OPENROUTER_API_KEY environment variable or .codecarto/broadside/config.yaml.",
+                    description: "OpenRouter API key. A value passed here is recorded wherever the host logs tool calls; prefer the OPENROUTER_API_KEY environment variable of the server process. (api_key in .codecarto/broadside/config.yaml also works, but that file is tracked, so a key there is committed with it.)",
+                },
+                run_id: {
+                    type: "string",
+                    description: "For collect: the run to collect, as listed by the status action. Defaults to the most recent run; pass this to collect an older run that is still in flight after a newer submit.",
                 },
                 wait_seconds: {
                     type: "number",
-                    description: "For submit: after submitting, poll up to this many seconds before returning. For collect: poll up to this many seconds before returning with partial state. Falls back to wait_seconds in .codecarto/broadside/config.yaml.",
+                    description: "For submit: after submitting, poll up to this many seconds before returning. For collect: poll up to this many seconds before returning with partial state. 0 polls each in-flight batch once and returns without waiting. Falls back to wait_seconds in .codecarto/broadside/config.yaml (default 0).",
                 },
                 include_synthesis: {
                     type: "boolean",
@@ -1432,7 +1502,7 @@ const TOOLS = [
                 },
                 max_cost: {
                     type: "number",
-                    description: "Approximate run expense limit in USD. The submit action estimates the run cost from slice sizes and the configured model's per-token pricing (live OpenRouter lookup, cached 24h) and refuses to submit when the estimate exceeds the limit unless force is true. Falls back to max_cost in .codecarto/broadside/config.yaml.",
+                    description: "Approximate run expense limit in USD. The submit action estimates the run cost from slice sizes and the configured model's per-token pricing (live OpenRouter lookup, cached 24h) and refuses to submit when the estimate exceeds the limit unless force is true. Falls back to max_cost in .codecarto/broadside/config.yaml, whose default is $1.00; pass 0 for no limit.",
                 },
                 force: {
                     type: "boolean",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "codecartographer-pi",
-  "version": "0.20.0",
+  "version": "0.21.0",
   "mcpName": "io.github.HuginnIndustries/codecartographer",
   "description": "Turn an unfamiliar codebase into a validated reimplementation spec, then synthesize confirmed specs and a product vision into a traceable plan.",
   "type": "module",