codecartographer-pi 0.19.5 → 0.20.0

package/dist/mcp-server/server.js

@@ -17,12 +17,11 @@ 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, canonicalPath, copyPackagedWorkspace, collectResultText, completeValidatedPhase, computePerPhaseTotals, computeTotals, createEmptyStatus, DEFAULT_PIPELINE_PATH, deriveSlug, discoverLibrary, describeScaffoldStaleness, detectProvenanceConflicts, estimateSubmitText, getLens, getNextEligiblePhase, getPipelineLabel, getWorkspaceState, isValidSlug, isWithinPathResolved, listBatchModels, listEntries, listGuideTopics, loadBroadsideConfig, modelsText, readGuide, listSkillNames, 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, } from "../core/index.js";
+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 { 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";
+import { describeConfigProblems, loadUserConfig, resolveUserConfigPath } from "../core/orchestrator-config.js";
 // ---------- input helpers ----------
 /**
  * Normalize an optional `phase` argument. A client can send any JSON, and
@@ -50,6 +49,25 @@ async function validateCwd(cwd) {
     }
     return cwd;
 }
+/**
+ * The library tools take `cwd` optionally: absent means "no workspace, use
+ * the user-global config alone". When it is given it becomes a containment
+ * root for spec_path and the source of the workspace config that gates the
+ * write, so it is validated exactly as a required cwd is — absolute and
+ * existing — before anything reads through it (#241). A relative path would
+ * resolve against the MCP server process's working directory, not the
+ * caller's, and widen the root to whatever `.codecarto/` sits there.
+ */
+async function optionalCwd(cwd) {
+    if (cwd === undefined || cwd === null)
+        return null;
+    if (typeof cwd !== "string") {
+        throw new McpError(ErrorCode.InvalidParams, "cwd must be a string when given");
+    }
+    if (cwd.trim() === "")
+        return null;
+    return validateCwd(cwd.trim());
+}
 async function requireWorkspace(cwd) {
     const state = await getWorkspaceState(cwd).catch((error) => {
         throw new McpError(ErrorCode.InternalError, error instanceof Error ? error.message : String(error));
@@ -109,12 +127,21 @@ export async function handleInit(args) {
         const entries = (await readdir(targetWorkspaceDir)).filter((entry) => entry !== BROADSIDE_DIR);
         broadsideOnly = entries.length === 0 && (await pathExists(join(targetWorkspaceDir, BROADSIDE_DIR)));
     }
-    if (targetExists && !sameWorkspace && !broadsideOnly) {
+    if (targetExists && !broadsideOnly) {
         if (!args.force) {
-            throw new McpError(ErrorCode.InvalidRequest, `A .codecarto/ directory already exists at ${targetWorkspaceDir}. Pass force: true to back it up and reinitialize. Warning: this moves all existing findings, handoffs, usage data, closeouts, and phase progress to a .codecarto-backup-TIMESTAMP/ directory.`);
+            throw new McpError(ErrorCode.InvalidRequest, sameWorkspace
+                ? `The .codecarto/ at ${targetWorkspaceDir} is CodeCartographer's own packaged template (a checkout install), and it holds workspace state. Pass force: true to move that state — status, findings, handoffs, usage data, closeouts, dashboard — to a .codecarto-backup-TIMESTAMP/ directory and reinitialize; the framework files stay in place. Consider codecarto_open to reattach without resetting.`
+                : `A .codecarto/ directory already exists at ${targetWorkspaceDir}. Pass force: true to back it up and reinitialize. Warning: this moves all existing findings, handoffs, usage data, closeouts, and phase progress to a .codecarto-backup-TIMESTAMP/ directory.`);
         }
         const backupDir = join(cwd, `.codecarto-backup-${new Date().toISOString().replace(/[:.]/g, "-")}`);
-        await rename(targetWorkspaceDir, backupDir);
+        if (sameWorkspace) {
+            // The template cannot be renamed away — it is what init copies from —
+            // so its session state is moved out file by file instead (#245).
+            await backupWorkspaceState(targetWorkspaceDir, backupDir);
+        }
+        else {
+            await rename(targetWorkspaceDir, backupDir);
+        }
     }
     if (!(await pathExists(targetWorkspaceDir))) {
         await mkdir(cwd, { recursive: true });
@@ -125,8 +152,11 @@ export async function handleInit(args) {
         // broadside state and results already on disk.
         await copyPackagedWorkspace(targetWorkspaceDir);
     }
+    // The template no longer carries a status.yaml (it is this repository's
+    // own project state); one is only present when init is re-run over an
+    // existing workspace, where its pipeline stays the default.
     const statusPath = join(targetWorkspaceDir, "workflow", "status.yaml");
-    const rawStatus = (await loadYamlFile(statusPath)) ?? {};
+    const rawStatus = (await pathExists(statusPath)) ? ((await loadYamlFile(statusPath)) ?? {}) : {};
     const selectedPipelinePath = pipelineChoice ?? rawStatus.pipeline?.trim() ?? DEFAULT_PIPELINE_PATH;
     const resolvedPipelinePath = join(targetWorkspaceDir, selectedPipelinePath);
     if (!(await pathExists(resolvedPipelinePath))) {
@@ -166,6 +196,7 @@ export async function handleStatus(args) {
     const terminalOpenQuestions = Object.values(state.status.phases).reduce((sum, phase) => sum + (phase.open_questions?.length ?? 0), 0);
     const postPipelinePending = state.status.post_pipeline.filter((entry) => entry.status !== "resolved").length;
     const scaffoldNotice = describeScaffoldStaleness(state);
+    const missingOutputs = await listMissingCompletedOutputs(state);
     const summaryLines = [
         `Phase: ${currentPhase}`,
         `Pipeline state: ${currentPhase === "complete" ? "complete" : "in progress"}`,
@@ -183,9 +214,11 @@ export async function handleStatus(args) {
     ];
     if (scaffoldNotice)
         summaryLines.push(`Scaffold: ${scaffoldNotice}`);
+    summaryLines.push(...describeMissingCompletedOutputs(missingOutputs));
     const summary = summaryLines.join("\n");
     return textResult(summary, {
         ...(scaffoldNotice ? { scaffoldNotice } : {}),
+        ...(missingOutputs.length > 0 ? { missingOutputs } : {}),
         currentPhase,
         pipeline: state.status.pipeline,
         pipelineLabel: getPipelineLabel(state.status.pipeline),
@@ -209,6 +242,11 @@ export async function handleSwitchPipeline(args) {
         return textResult(`Already on pipeline: ${getPipelineLabel(pipelineChoice)}`, { pipeline: getPipelineLabel(pipelineChoice) });
     }
     const result = await switchPipeline(cwd, pipelineChoice);
+    // The dashboard is rendered from the pipeline the switch just replaced;
+    // Pi re-rendered here and MCP did not, so the file showed the old phase
+    // list until the next completion (#254). Same best-effort call as
+    // completion and amendment make.
+    const dashboardPath = (await writeDashboard(cwd, PACKAGE_VERSION)) ? ".codecarto/dashboard.html" : undefined;
     const lines = [`Switched pipeline: ${getPipelineLabel(pipelineChoice)}`];
     if (result.carried.length > 0)
         lines.push(`Phases preserved (completed): ${result.carried.join(", ")}`);
@@ -216,11 +254,18 @@ export async function handleSwitchPipeline(args) {
         lines.push(`New phases: ${result.newPhases.join(", ")}`);
     if (result.dropped.length > 0)
         lines.push(`Phases not in new pipeline: ${result.dropped.join(", ")} (findings remain on disk)`);
+    lines.push(...describeDanglingCarryForward(result.dangling));
+    lines.push(`Current phase: ${result.state.status.current_phase}`);
+    if (dashboardPath)
+        lines.push(`Dashboard refreshed: ${dashboardPath}`);
     return textResult(lines.join("\n"), {
         pipeline: getPipelineLabel(pipelineChoice),
+        currentPhase: result.state.status.current_phase,
         carried: result.carried,
         newPhases: result.newPhases,
         dropped: result.dropped,
+        dangling: result.dangling,
+        dashboardPath,
     });
 }
 export async function handleNext(args) {
@@ -350,17 +395,20 @@ export async function handleSkill(args) {
     if (nextPhase) {
         throw new McpError(ErrorCode.InvalidRequest, `Cannot run skill: pipeline is not complete (next phase: ${nextPhase.id}). Finish the pipeline first.`);
     }
-    const skillFile = join(state.workspaceDir, "skills", args.name, "SKILL.md");
-    if (!(await pathExists(skillFile))) {
+    // Resolve against the installed list only: the name is never joined onto a
+    // path, so a traversal like `../findings/architecture` cannot splice a
+    // phase SKILL.md (or anything else) into the post-pipeline prompt.
+    const skillName = await resolveSkillName(state.workspaceDir, args.name);
+    if (!skillName) {
         const available = await listSkillNames(state.workspaceDir);
         const hint = available.length > 0 ? ` Available: ${available.join(", ")}.` : " No skills installed.";
-        throw new McpError(ErrorCode.InvalidParams, `Unknown skill: ${args.name}.${hint} The Broad-Side reading guide is served as \`${BROADSIDE_SKILL_NAME}\` and is not pipeline-gated.`);
+        throw new McpError(ErrorCode.InvalidParams, `Unknown skill: ${args.name.trim()}.${hint} The Broad-Side reading guide is served as \`${BROADSIDE_SKILL_NAME}\` and is not pipeline-gated.`);
     }
-    const prompt = await buildSkillPrompt(state, args.name);
-    return textResult(prompt, { skill: args.name });
+    const prompt = await buildSkillPrompt(state, skillName);
+    return textResult(prompt, { skill: skillName });
 }
 // ---------- library helpers ----------
-async function resolveLibraryPath(args) {
+function resolveLibraryPath(args, config) {
     const explicit = typeof args.library_path === "string" && args.library_path.trim() !== ""
         ? args.library_path.trim()
         : null;
@@ -370,18 +418,8 @@ async function resolveLibraryPath(args) {
         }
         return explicit;
     }
-    if (typeof args.cwd === "string" && args.cwd.trim() !== "") {
-        const cwd = args.cwd.trim();
-        if (!isAbsolute(cwd)) {
-            throw new McpError(ErrorCode.InvalidParams, `cwd must be absolute, got: ${cwd}`);
-        }
-        // loadCodecartoConfig merges user-global under per-workspace and tolerates
-        // a missing workspace file, so a single call covers both cases.
-        const workspaceDir = join(cwd, ".codecarto");
-        const config = await loadCodecartoConfig(workspaceDir);
-        if (config.library.path)
-            return config.library.path;
-    }
+    if (config.library.path)
+        return config.library.path;
     throw new McpError(ErrorCode.InvalidParams, "library_path is required (pass it explicitly, or pass cwd and configure library.path in ~/.codecarto/config.yaml or .codecarto/workflow/config.yaml).");
 }
 /**
@@ -391,17 +429,22 @@ async function resolveLibraryPath(args) {
  * the publish tool enforces.
  */
 async function loadEffectiveConfig(cwd) {
-    if (typeof cwd !== "string" || cwd.trim() === "")
+    // This config decides whether publish_confirm gates the write, so the cwd
+    // it is read through is the one optionalCwd validated, never a raw argument.
+    if (!cwd)
         return loadUserConfig();
-    // A relative path here resolves against the server process's working
-    // directory, not the caller's, so it would quietly read some other
-    // workspace's config — and this config decides whether publish_confirm
-    // gates the write. Refuse rather than answer from the wrong file.
-    const trimmed = cwd.trim();
-    if (!isAbsolute(trimmed)) {
-        throw new McpError(ErrorCode.InvalidParams, `cwd must be an absolute path, got: ${trimmed}`);
-    }
-    return loadCodecartoConfig(join(trimmed, ".codecarto"));
+    return loadCodecartoConfig(join(cwd, ".codecarto"));
+}
+/**
+ * The library tools answer from the config — its path, its namespace, its
+ * confirm gate — so a config file that could not be used in full is a
+ * refusal, not a silent fallback to whatever the other layer says (#242).
+ * The message names each file and key; codecarto_config shows the same list.
+ */
+function refuseOnConfigProblems(config, tool) {
+    if (config.problems.length === 0)
+        return;
+    throw new McpError(ErrorCode.InvalidRequest, [`${tool} refused: the configuration has problems. Fix or remove the offending file, then retry.`, ...describeConfigProblems(config)].join("\n"));
 }
 function asStringArray(value, fieldName) {
     if (!Array.isArray(value)) {
@@ -488,12 +531,12 @@ async function resolveDefaultsFromWorkspace(cwd, overrides) {
     let namespace = typeof overrides.namespace === "string" && overrides.namespace.trim() !== ""
         ? overrides.namespace.trim()
         : null;
-    if (typeof cwd === "string" && cwd.trim() !== "" && isAbsolute(cwd)) {
-        const workspaceDir = join(cwd.trim(), ".codecarto");
+    if (cwd) {
+        const workspaceDir = join(cwd, ".codecarto");
         if (await pathExists(workspaceDir)) {
             if (pipeline === "unknown") {
                 try {
-                    const state = await getWorkspaceState(cwd.trim());
+                    const state = await getWorkspaceState(cwd);
                     if (state?.status.pipeline)
                         pipeline = state.status.pipeline;
                 }
@@ -539,16 +582,20 @@ function provenanceConflictLines(conflicts) {
 }
 // ---------- library handlers ----------
 export async function handlePublish(args) {
-    const libraryPath = await resolveLibraryPath(args);
+    // First, before anything is read through it: cwd is a containment root
+    // for spec_path below and the source of the config that gates the write.
+    const cwd = await optionalCwd(args.cwd);
+    const config = await loadEffectiveConfig(cwd);
+    refuseOnConfigProblems(config, "codecarto_publish");
+    const libraryPath = resolveLibraryPath(args, config);
     const marker = await discoverLibrary(libraryPath);
     if (!marker) {
         throw new McpError(ErrorCode.InvalidParams, `No CodeCartographer library at ${libraryPath} (missing .codecarto-library marker). Create one before publishing.`);
     }
     // Build allowed roots for spec_path containment: workspace .codecarto/ and library path
     const allowedRoots = [libraryPath];
-    if (typeof args.cwd === "string" && args.cwd.trim() !== "") {
-        allowedRoots.push(join(args.cwd.trim(), ".codecarto"));
-    }
+    if (cwd)
+        allowedRoots.push(join(cwd, ".codecarto"));
     const spec = await readSpecArg(args, allowedRoots);
     if (typeof args.source_repo !== "string" || args.source_repo.trim() === "") {
         throw new McpError(ErrorCode.InvalidParams, "source_repo is required");
@@ -564,7 +611,7 @@ export async function handlePublish(args) {
     if (!isValidSlug(slug)) {
         throw new McpError(ErrorCode.InvalidParams, `Resolved slug "${slug}" is invalid. Provide an explicit slug (lowercase ASCII, starts with a letter, max 64 chars).`);
     }
-    const defaults = await resolveDefaultsFromWorkspace(args.cwd, {
+    const defaults = await resolveDefaultsFromWorkspace(cwd, {
         pipeline: args.pipeline,
         namespace: args.namespace,
     });
@@ -593,7 +640,6 @@ export async function handlePublish(args) {
     // opt-out, and a host that never configured the key keeps the behavior it
     // had. Runs after every argument check so the preview names the resolved
     // slug and namespace, and before publishEntry so nothing is written.
-    const config = await loadEffectiveConfig(args.cwd);
     if (config.library.publish_confirm && config.library.publish_confirm_configured && args.confirm !== true) {
         const preview = await previewPublishVersion(libraryPath, spec, { slug, namespace }, { forceNewVersion });
         const label = `${namespace ? `${namespace}/` : ""}${slug}`;
@@ -662,7 +708,9 @@ export async function handlePublish(args) {
     });
 }
 export async function handleLibraryList(args) {
-    const libraryPath = await resolveLibraryPath(args);
+    const config = await loadEffectiveConfig(await optionalCwd(args.cwd));
+    refuseOnConfigProblems(config, "codecarto_library_list");
+    const libraryPath = resolveLibraryPath(args, config);
     const marker = await discoverLibrary(libraryPath);
     if (!marker) {
         throw new McpError(ErrorCode.InvalidParams, `No CodeCartographer library at ${libraryPath} (missing .codecarto-library marker).`);
@@ -703,7 +751,9 @@ export async function handleLibraryList(args) {
     });
 }
 export async function handleLibraryReindex(args) {
-    const libraryPath = await resolveLibraryPath(args);
+    const config = await loadEffectiveConfig(await optionalCwd(args.cwd));
+    refuseOnConfigProblems(config, "codecarto_library_reindex");
+    const libraryPath = resolveLibraryPath(args, config);
     const marker = await discoverLibrary(libraryPath);
     if (!marker) {
         throw new McpError(ErrorCode.InvalidParams, `No CodeCartographer library at ${libraryPath} (missing .codecarto-library marker).`);
@@ -739,10 +789,17 @@ export async function handleLibraryInit(args) {
     });
     // Write config to user-global location
     const configPath = resolveUserConfigPath();
-    await writeLibraryConfig(configPath, libraryPath, args.namespace ?? null);
+    // Writes library.path (and library.namespace when given) and nothing else:
+    // in particular it does not set publish_confirm, so initializing a library
+    // does not switch the codecarto_publish confirm gate on (#244). A config
+    // file that cannot be parsed is left alone and reported.
+    await writeLibraryConfig(configPath, libraryPath, args.namespace ?? null).catch((error) => {
+        throw new McpError(ErrorCode.InvalidRequest, error instanceof Error ? error.message : String(error));
+    });
+    const written = args.namespace ? "library.path and library.namespace" : "library.path";
     const msg = result.alreadyExisted
-        ? `Library already exists at ${libraryPath} (marker preserved). Config written to ${configPath}.`
-        : `Created library at ${libraryPath} with marker "${result.marker.name}". Config written to ${configPath}.`;
+        ? `Library already exists at ${libraryPath} (marker preserved). Wrote ${written} to ${configPath}; other keys untouched.`
+        : `Created library at ${libraryPath} with marker "${result.marker.name}". Wrote ${written} to ${configPath}; other keys untouched.`;
     return textResult(msg, {
         libraryPath,
         markerName: result.marker.name,
@@ -805,6 +862,9 @@ export async function handleConfig(args) {
         `  Library marker: ${markerStatus}`,
         `  User-global config: ${userConfigPath}`,
         `  Workspace config: ${workspaceConfigPath ?? "(no cwd provided)"}`,
+        // A file that could not be used is the one thing this tool exists
+        // to surface; the library tools refuse while any is listed (#242).
+        ...describeConfigProblems(config),
     ].join("\n"), {
         libraryPath: config.library.path,
         libraryNamespace: config.library.namespace,
@@ -812,6 +872,7 @@ export async function handleConfig(args) {
         llmSteerNextPhase: config.orchestrator.llm_steer_next_phase,
         userConfigPath,
         workspaceConfigPath,
+        problems: config.problems,
     });
 }
 // ---------- MCP parity handlers: open, usage, dashboard, list_skills ----------
@@ -1113,7 +1174,7 @@ const TOOLS = [
     },
     {
         name: "codecarto_validate",
-        description: "Validate a phase's primary output against the validation block in the produced markdown. Returns overall PASS/PASS WITH GAPS/FAIL/MISSING plus the parsed criteria rows. If phase is omitted, validates the next eligible phase.",
+        description: "Read the ## Validation table a phase wrote at the end of its primary output — the phase's own PASS/PARTIAL/FAIL per completion criterion — apply two cross-checks (findings evidence/action pairing; declared secondary outputs present), and return PASS/PASS WITH GAPS/FAIL/MISSING plus the parsed rows. It does not judge the criteria itself. If phase is omitted, validates the next eligible phase.",
         inputSchema: {
             type: "object",
             properties: {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "codecartographer-pi",
-  "version": "0.19.5",
+  "version": "0.20.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",
@@ -76,6 +76,7 @@
     "typescript": "^5.9.3"
   },
   "overrides": {
-    "undici": "^8.10.0"
+    "undici": "^8.10.0",
+    "hono": "^4.13.5"
   }
 }