codecartographer-pi 0.14.0 → 0.15.0

package/dist/mcp-server/server.js

@@ -15,7 +15,9 @@ import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js"
 import { CallToolRequestSchema, ErrorCode, ListToolsRequestSchema, McpError, } from "@modelcontextprotocol/sdk/types.js";
 import { cp, mkdir, readFile, rename, writeFile } from "node:fs/promises";
 import { basename, isAbsolute, join } from "node:path";
-import { buildPhasePrompt, buildSkillPrompt, buildValidationSummary, canonicalPath, completeValidatedPhase, computePerPhaseTotals, computeTotals, createEmptyStatus, DEFAULT_PIPELINE_PATH, deriveSlug, discoverLibrary, describeScaffoldStaleness, getNextEligiblePhase, getPipelineLabel, getWorkspaceState, isValidSlug, isWithinPathResolved, listEntries, listGuideTopics, readGuide, listSkillNames, loadCodecartoConfig, loadUsage, loadYamlFile, normalizeForComparison, PACKAGE_VERSION, packagedWorkspaceDir, pathExists, PhasePreflightError, publishEntry, reindex as libraryReindex, resolvePhase, resolvePipelineChoice, stringifySimpleYaml, switchPipeline, validatePhaseOutput, writeLibraryConfig, } from "../core/index.js";
+import { buildPhasePrompt, buildSkillPrompt, buildValidationSummary, canonicalPath, completeValidatedPhase, computePerPhaseTotals, computeTotals, createEmptyStatus, DEFAULT_PIPELINE_PATH, deriveSlug, discoverLibrary, describeScaffoldStaleness, getNextEligiblePhase, getPipelineLabel, getWorkspaceState, isValidSlug, isWithinPathResolved, listEntries, listGuideTopics, readGuide, listSkillNames, loadCodecartoConfig, loadUsage, loadYamlFile, normalizeForComparison, PACKAGE_VERSION, packagedWorkspaceDir, pathExists, PhasePreflightError, publishEntry, reindex as libraryReindex, refreshScaffold, resolvePhase, resolvePipelineChoice, seedOrchestratorFiles, stringifySimpleYaml, switchPipeline, validatePhaseOutput, writeLibraryConfig, } from "../core/index.js";
+import { applyAmendment } from "../core/amendment.js";
+import { appendUsageRun } from "../core/usage.js";
 import { initLibrary } from "../core/library.js";
 import { loadUserConfig, resolveUserConfigPath } from "../core/orchestrator-config.js";
 import { writeDashboard } from "../extensions/codecarto/dashboard-writer.js";
@@ -41,13 +43,17 @@ async function requireWorkspace(cwd) {
     }
     return state;
 }
+// MCP clients may read structuredContent in preference to content when both are
+// present. The tools whose payload IS prose — the phase prompts, the guide —
+// therefore have to expose it structurally too, or such a client receives labels
+// and no payload: codecarto_next returned no phase prompt at all (issue #94).
+// Carrying the rendered text under a stable key keeps both client styles whole,
+// and no tool declares an outputSchema that this could violate.
 function textResult(text, structured) {
-    const result = {
+    return {
         content: [{ type: "text", text }],
+        structuredContent: { ...structured, text },
     };
-    if (structured)
-        result.structuredContent = structured;
-    return result;
 }
 async function buildMcpPhasePrompt(state, phase, forced) {
     try {
@@ -100,12 +106,23 @@ export async function handleInit(args) {
     const normalizedStatus = createEmptyStatus(basename(cwd), selectedPipelinePath, pipeline);
     normalizedStatus.last_updated = new Date().toISOString();
     await writeFile(statusPath, `${stringifySimpleYaml(normalizedStatus)}\n`, "utf8");
+    // Orchestration is on by default (issue #97/#98): the driving chat holds the
+    // duties, so the files those duties maintain exist from the first phase.
+    const seeded = await seedOrchestratorFiles(targetWorkspaceDir);
     const label = getPipelineLabel(selectedPipelinePath);
-    return textResult(`Initialized CodeCartographer workspace at ${targetWorkspaceDir}.\nPipeline: ${label} (${selectedPipelinePath})\nFirst phase: ${normalizedStatus.current_phase}`, {
+    const initLines = [
+        `Initialized CodeCartographer workspace at ${targetWorkspaceDir}.`,
+        `Pipeline: ${label} (${selectedPipelinePath})`,
+        `First phase: ${normalizedStatus.current_phase}`,
+    ];
+    if (seeded.length > 0)
+        initLines.push(`Seeded orchestrator files: ${seeded.join(", ")} (the driving chat holds the orchestrator duties — see GUIDE.md §Roles).`);
+    return textResult(initLines.join("\n"), {
         workspaceDir: targetWorkspaceDir,
         pipeline: selectedPipelinePath,
         pipelineLabel: label,
         firstPhase: normalizedStatus.current_phase,
+        seededOrchestratorFiles: seeded,
     });
 }
 export async function handleStatus(args) {
@@ -212,6 +229,7 @@ export async function handleValidate(args) {
         rows: validation.rows,
         gaps: validation.gaps,
         errors: validation.errors,
+        secondaryOutputs: validation.secondaryOutputs ?? [],
     });
 }
 export async function handleComplete(args) {
@@ -223,20 +241,46 @@ export async function handleComplete(args) {
     if (validation.overall === "FAIL" || validation.overall === "MISSING") {
         throw new McpError(ErrorCode.InvalidRequest, `Cannot complete ${validation.phaseId}: validation is ${validation.overall}.\n${buildValidationSummary(validation).join("\n")}`);
     }
-    const { updatedState, closeoutNotice } = await completeValidatedPhase(cwd, validation, "codecarto_complete").catch((error) => {
+    const { updatedState, closeoutNotice, orchestratorCheckpoint } = await completeValidatedPhase(cwd, validation, "codecarto_complete").catch((error) => {
         throw new McpError(ErrorCode.InvalidParams, error instanceof Error ? error.message : String(error));
     });
+    // Record the run in the usage log (issue #100). MCP hosts execute phases in
+    // their own context, so tokens and activity are unknowable here — this is a
+    // completion receipt, marked recorded_by so totals can tell it apart from
+    // the Pi runner's token-bearing entries. Recording lives in this handler,
+    // not core completion, because Pi-driven runs already record with real
+    // telemetry and must not double-count.
+    try {
+        await appendUsageRun(updatedState.workspaceDir, {
+            timestamp: new Date().toISOString(),
+            phase: validation.phaseId,
+            status: "completed",
+            turn_count: 0,
+            tool_uses: 0,
+            duration_ms: 0,
+            tokens: { input: 0, output: 0, cache_write: 0 },
+            recorded_by: "mcp-complete",
+        });
+    }
+    catch {
+        // Usage is best-effort telemetry: the phase completed and canonical
+        // state is already written, so a usage-log write failure must not fail
+        // the completion result. Nothing else can act on the error here.
+    }
     const lines = [
         `Marked ${validation.phaseId} complete (validation: ${validation.overall}).`,
         `Next phase: ${updatedState.status.current_phase}`,
     ];
     if (closeoutNotice)
         lines.push(closeoutNotice);
+    if (orchestratorCheckpoint)
+        lines.push(orchestratorCheckpoint);
     return textResult(lines.join("\n"), {
         completedPhase: validation.phaseId,
         validation: validation.overall,
         nextPhase: updatedState.status.current_phase,
         closeoutNotice,
+        orchestratorCheckpoint,
     });
 }
 export async function handleSkill(args) {
@@ -615,18 +659,22 @@ export async function handleUsage(args) {
     }
     const totals = computeTotals(usage);
     const perPhase = computePerPhaseTotals(usage);
+    const receiptRuns = usage.runs.filter((run) => run.recorded_by === "mcp-complete").length;
     const lines = [
         `Total runs: ${totals.runs}`,
         `Total tokens: ${totals.tokens.input} in / ${totals.tokens.output} out / ${totals.tokens.cache_write} cache-write`,
         `Total duration: ${totals.duration_ms}ms / ${totals.tool_uses} tool uses`,
-        "",
-        "Per-phase totals:",
     ];
+    if (receiptRuns > 0) {
+        lines.push(`Note: ${receiptRuns} run(s) recorded via codecarto_complete carry no token or activity data (MCP hosts execute phases in their own context) — zeros above are unknowns, not free runs.`);
+    }
+    lines.push("", "Per-phase totals:");
     for (const [phaseId, t] of perPhase) {
         lines.push(`  ${phaseId}: ${t.runs} run(s), ${t.tokens.input + t.tokens.output} tokens, ${t.tool_uses} tool uses, ${t.duration_ms}ms`);
     }
     return textResult(lines.join("\n"), {
         runs: totals.runs,
+        receiptRuns,
         tokens: totals.tokens,
         toolUses: totals.tool_uses,
         durationMs: totals.duration_ms,
@@ -648,6 +696,50 @@ export async function handleListSkills(args) {
         : ["No skills installed."];
     return textResult(lines.join("\n"), { skills });
 }
+export async function handleRefreshScaffold(args) {
+    const cwd = await validateCwd(args.cwd);
+    await requireWorkspace(cwd);
+    const result = await refreshScaffold(cwd).catch((error) => {
+        throw new McpError(ErrorCode.InvalidRequest, error instanceof Error ? error.message : String(error));
+    });
+    const shown = result.written.slice(0, 20);
+    const lines = [
+        `Refreshed ${result.written.length} framework-owned file(s) from the packaged template (${result.scaffoldVersionBefore ?? "unversioned"} → ${result.scaffoldVersionAfter}).`,
+        "Project state, user config, findings outputs, scratch, closeouts, and orchestrator files were not touched.",
+        ...shown.map((path) => `  - .codecarto/${path}`),
+    ];
+    if (result.written.length > shown.length)
+        lines.push(`  … +${result.written.length - shown.length} more`);
+    return textResult(lines.join("\n"), {
+        written: result.written,
+        scaffoldVersionBefore: result.scaffoldVersionBefore,
+        scaffoldVersionAfter: result.scaffoldVersionAfter,
+    });
+}
+export async function handleAmend(args) {
+    if (typeof args.name !== "string" || !args.name.trim()) {
+        throw new McpError(ErrorCode.InvalidParams, "name is required (the amendment file's slug under .codecarto/scratch/amendments/)");
+    }
+    const cwd = await validateCwd(args.cwd);
+    await requireWorkspace(cwd);
+    const { applied, closeoutNotice } = await applyAmendment(cwd, args.name).catch((error) => {
+        throw new McpError(ErrorCode.InvalidRequest, error instanceof Error ? error.message : String(error));
+    });
+    const lines = [
+        `Amendment applied.`,
+        `Open questions closed: ${applied.openQuestionsClosed.length > 0 ? applied.openQuestionsClosed.join(", ") : "none"}`,
+        `Post-pipeline items closed: ${applied.postPipelineClosed.length > 0 ? applied.postPipelineClosed.join(", ") : "none"}`,
+    ];
+    if (applied.unknownIds.length > 0)
+        lines.push(`Ids that matched nothing (already closed or unknown): ${applied.unknownIds.join(", ")}`);
+    lines.push(closeoutNotice);
+    return textResult(lines.join("\n"), {
+        openQuestionsClosed: applied.openQuestionsClosed,
+        postPipelineClosed: applied.postPipelineClosed,
+        unknownIds: applied.unknownIds,
+        closeoutNotice,
+    });
+}
 // ---------- tool registry ----------
 const TOOLS = [
     {
@@ -898,9 +990,32 @@ const TOOLS = [
             required: ["cwd"],
         },
     },
+    {
+        name: "codecarto_amend",
+        description: "Apply a post-pipeline amendment from .codecarto/scratch/amendments/<name>.yaml to workflow/status.yaml: close open questions resolved on evidence after the pipeline completed and retire finished post-pipeline backlog items, under the same lock completion uses. Writes an amendment closeout and THREAD_LOG entry. Refused while the pipeline is incomplete — mid-pipeline resolutions belong in the phase handoff. Idempotent: ids that no longer match are reported, not fatal.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                cwd: { type: "string", description: "Absolute path to the target repository." },
+                name: { type: "string", description: "Amendment file slug under .codecarto/scratch/amendments/ (with or without .yaml)." },
+            },
+            required: ["cwd", "name"],
+        },
+    },
+    {
+        name: "codecarto_refresh_scaffold",
+        description: "Refresh a workspace's framework-owned files (GUIDE.md, templates/, workflow pipelines and VALIDATE.md, skills/, findings SKILL and README stubs) from the packaged template — the action every scaffold-staleness warning instructs. Never touches project state (status.yaml), user config (workflow/config.yaml, usage log), findings outputs, scratch/, closeouts/, or the orchestrator files (CONVENTIONS.md, DECISIONS.md, BACKLOG.md, THREAD_LOG.md). Appends one THREAD_LOG entry naming the version transition. Unlike codecarto_init force:true, nothing is backed up or lost.",
+        inputSchema: {
+            type: "object",
+            properties: { cwd: { type: "string", description: "Absolute path to the target repository." } },
+            required: ["cwd"],
+        },
+    },
 ];
 const HANDLERS = {
+    codecarto_amend: handleAmend,
     codecarto_init: handleInit,
+    codecarto_refresh_scaffold: handleRefreshScaffold,
     codecarto_status: handleStatus,
     codecarto_switch_pipeline: handleSwitchPipeline,
     codecarto_next: handleNext,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "codecartographer-pi",
-  "version": "0.14.0",
+  "version": "0.15.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",