codecartographer-pi 0.17.0 → 0.18.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, canonicalPath, copyPackagedWorkspace, collectResultText, completeValidatedPhase, computePerPhaseTotals, computeTotals, createEmptyStatus, DEFAULT_PIPELINE_PATH, deriveSlug, discoverLibrary, describeScaffoldStaleness, estimateSubmitText, getLens, getNextEligiblePhase, getPipelineLabel, getWorkspaceState, isValidSlug, isWithinPathResolved, listBatchModels, listEntries, listGuideTopics, loadBroadsideConfig, modelsText, readGuide, listSkillNames, loadCodecartoConfig, loadUsage, loadYamlFile, normalizeForComparison, PACKAGE_VERSION, packagedWorkspaceDir, pathExists, PhasePreflightError, 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, 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 { applyAmendment } from "../core/amendment.js";
 import { appendUsageRun } from "../core/usage.js";
 import { initLibrary } from "../core/library.js";
@@ -262,7 +262,7 @@ 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, orchestratorCheckpoint } = await completeValidatedPhase(cwd, validation, "codecarto_complete").catch((error) => {
+    const { updatedState, closeoutNotice, orchestratorCheckpoint, warnings } = 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
@@ -303,6 +303,10 @@ export async function handleComplete(args) {
         lines.push(orchestratorCheckpoint);
     if (dashboardPath)
         lines.push(`Dashboard refreshed: ${dashboardPath}`);
+    for (const warning of validation.warnings ?? [])
+        lines.push(`NOTE: ${warning} Non-gating.`);
+    for (const warning of warnings)
+        lines.push(`NOTE: ${warning} Non-gating.`);
     return textResult(lines.join("\n"), {
         completedPhase: validation.phaseId,
         validation: validation.overall,
@@ -310,6 +314,7 @@ export async function handleComplete(args) {
         closeoutNotice,
         orchestratorCheckpoint,
         dashboardPath,
+        warnings: [...(validation.warnings ?? []), ...warnings],
     });
 }
 export async function handleSkill(args) {
@@ -365,6 +370,17 @@ async function resolveLibraryPath(args) {
     }
     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).");
 }
+/**
+ * The configuration `codecarto_config` reports for the same `cwd`: workspace
+ * over user-global when a cwd is given, user-global alone otherwise. Publish
+ * reads its gate from here so the value the config tool displays is the value
+ * the publish tool enforces.
+ */
+async function loadEffectiveConfig(cwd) {
+    return typeof cwd === "string" && cwd.trim() !== ""
+        ? loadCodecartoConfig(join(cwd.trim(), ".codecarto"))
+        : loadUserConfig();
+}
 function asStringArray(value, fieldName) {
     if (!Array.isArray(value)) {
         throw new McpError(ErrorCode.InvalidParams, `${fieldName} must be an array of strings`);
@@ -472,6 +488,33 @@ async function resolveDefaultsFromWorkspace(cwd, overrides) {
     }
     return { pipeline, namespace };
 }
+// ---------- library provenance reporting ----------
+function conflictEntryLabel(conflict) {
+    return conflict.namespace ? `${conflict.namespace}/${conflict.slug}` : conflict.slug;
+}
+/**
+ * The report block appended to the list and reindex text results when an
+ * entry's versions disagree about source_repo (#148). Empty when there is
+ * nothing to report, so a healthy library's output does not change. Repair
+ * is manual by design: the framework does not rename or renumber versions,
+ * because entry paths are ABI.
+ */
+function provenanceConflictLines(conflicts) {
+    if (conflicts.length === 0)
+        return [];
+    const lines = [
+        "",
+        `Provenance conflicts — ${conflicts.length} ${conflicts.length === 1 ? "entry" : "entries"} whose versions disagree about source_repo:`,
+    ];
+    for (const conflict of conflicts) {
+        const others = conflict.disagreeing_versions
+            .map((v) => `v${v.version} records ${v.source_repo}`)
+            .join("; ");
+        lines.push(`  ${conflictEntryLabel(conflict)}: the index advertises ${conflict.source_repo} (v${conflict.latest_version}), but ${others}.`);
+    }
+    lines.push("These entries were merged by a slug collision before publish refused cross-project appends, so each version history spans more than one codebase (a repository that genuinely moved and was re-published with allow_source_repo_change leaves the same shape).", "Repair is manual: split the entry by hand — the framework does not rename or renumber versions, because entry paths are ABI.");
+    return lines;
+}
 // ---------- library handlers ----------
 export async function handlePublish(args) {
     const libraryPath = await resolveLibraryPath(args);
@@ -518,6 +561,50 @@ export async function handlePublish(args) {
     const analyzedAt = typeof args.analyzed_at === "string" && args.analyzed_at !== ""
         ? args.analyzed_at
         : new Date().toISOString();
+    const headline = args.headline.trim();
+    const forceNewVersion = args.force_new_version === true;
+    // publish_confirm gate (#162). Pi shows a preview and asks before writing.
+    // An MCP server has no one to ask, so — as codecarto_broadside does for its
+    // spend limit — it refuses with the preview and lets the caller re-invoke
+    // with confirm: true. The gate applies only when a config layer actually
+    // set the key: the loader's default (true) exists to make Pi's dialog
+    // 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}`;
+        const versionLine = preview.latestVersion === 0
+            ? "v1 (first version of a new entry)"
+            : preview.isNewVersion
+                ? `v${preview.version} (new content version; the newest is v${preview.latestVersion})`
+                : `v${preview.version} (metadata-only update; the content hash matches the newest version)`;
+        const specSource = typeof args.spec_path === "string" && args.spec_path.trim() !== ""
+            ? args.spec_path.trim()
+            : `inline (${spec.length} characters)`;
+        throw new McpError(ErrorCode.InvalidRequest, [
+            "Publish not performed: library.publish_confirm is set and this call did not carry confirm: true. Nothing was written.",
+            `Would publish ${label} to ${libraryPath}`,
+            `  Version: ${versionLine}`,
+            `  Source repo: ${sourceRepo}`,
+            `  Headline: ${headline}`,
+            `  Confidentiality: ${confidentiality ?? "internal (the default; none declared)"}`,
+            `  Spec: ${specSource}`,
+            "Re-invoke codecarto_publish with the same arguments plus confirm: true to publish, or set library.publish_confirm: false in config to drop this gate.",
+        ].join("\n"), {
+            refused: "publish_confirm",
+            libraryPath,
+            namespace: namespace ?? null,
+            slug,
+            version: preview.version,
+            isNewVersion: preview.isNewVersion,
+            latestVersion: preview.latestVersion,
+            source_repo: sourceRepo,
+            headline,
+            confidentiality: confidentiality ?? null,
+        });
+    }
     const result = await publishEntry(libraryPath, spec, {
         slug,
         namespace: namespace ?? undefined,
@@ -528,14 +615,15 @@ export async function handlePublish(args) {
         analyzed_at: analyzedAt,
         pipeline: defaults.pipeline,
         codecarto_version: PACKAGE_VERSION,
-        headline: args.headline.trim(),
+        headline,
         tags,
         capabilities,
         confidentiality,
         generation,
     }, {
-        forceNewVersion: args.force_new_version === true,
+        forceNewVersion,
         allowSourceRepoChange: args.allow_source_repo_change === true,
+        allowConfidentialityMismatch: args.allow_confidentiality_mismatch === true,
     });
     const lines = [
         `Published ${result.namespace ? `${result.namespace}/` : ""}${result.slug} v${result.version} to ${libraryPath}`,
@@ -567,6 +655,10 @@ export async function handleLibraryList(args) {
     if (typeof args.source_repo === "string" && args.source_repo !== "")
         filter.source_repo = args.source_repo;
     const entries = await listEntries(libraryPath, filter);
+    // Computed over the listed entries only, read-only: one readdir per entry
+    // plus one small metadata read per older version.
+    const conflicts = await detectProvenanceConflicts(libraryPath, entries);
+    const conflicted = new Set(conflicts.map((c) => `${c.namespace ?? ""}/${c.slug}`));
     const summary = entries.length === 0
         ? `No entries match the filter in ${libraryPath}.`
         : [
@@ -574,8 +666,10 @@ export async function handleLibraryList(args) {
             ...entries.map((e) => {
                 const ns = e.namespace ? `${e.namespace}/` : "";
                 const tags = e.tags.length > 0 ? ` [${e.tags.slice(0, 4).join(", ")}${e.tags.length > 4 ? ", ..." : ""}]` : "";
-                return `  ${ns}${e.slug} v${e.latest_version} — ${e.headline}${tags}`;
+                const flag = conflicted.has(`${e.namespace ?? ""}/${e.slug}`) ? " — PROVENANCE CONFLICT (see below)" : "";
+                return `  ${ns}${e.slug} v${e.latest_version} — ${e.headline}${tags}${flag}`;
             }),
+            ...provenanceConflictLines(conflicts),
         ].join("\n");
     return textResult(summary, {
         libraryPath,
@@ -583,6 +677,7 @@ export async function handleLibraryList(args) {
         namespaced: marker.namespaced,
         count: entries.length,
         entries,
+        provenance_conflicts: conflicts,
     });
 }
 export async function handleLibraryReindex(args) {
@@ -593,17 +688,27 @@ export async function handleLibraryReindex(args) {
     }
     const index = await libraryReindex(libraryPath);
     const namespaces = index.namespaces.length > 0 ? index.namespaces.join(", ") : "(none)";
-    return textResult(`Reindexed ${libraryPath}: ${index.entry_count} ${index.entry_count === 1 ? "entry" : "entries"} across namespaces [${namespaces}].`, {
+    return textResult([
+        `Reindexed ${libraryPath}: ${index.entry_count} ${index.entry_count === 1 ? "entry" : "entries"} across namespaces [${namespaces}].`,
+        ...provenanceConflictLines(index.provenance_conflicts),
+    ].join("\n"), {
         libraryPath,
         libraryName: index.library_name,
         entry_count: index.entry_count,
         namespaces: index.namespaces,
+        provenance_conflicts: index.provenance_conflicts,
     });
 }
 export async function handleLibraryInit(args) {
     if (!args.library_path || typeof args.library_path !== "string") {
         throw new McpError(ErrorCode.InvalidParams, "library_path is required.");
     }
+    // Same rule as resolveLibraryPath for the other library tools: a relative
+    // path would resolve against the MCP server process's cwd and then be
+    // persisted verbatim into the user-global config (#134).
+    if (!isAbsolute(args.library_path)) {
+        throw new McpError(ErrorCode.InvalidParams, `library_path must be absolute, got: ${args.library_path}`);
+    }
     const libraryPath = args.library_path;
     const namespaced = !!args.namespace;
     const result = await initLibrary(libraryPath, {
@@ -1010,7 +1115,7 @@ const TOOLS = [
     },
     {
         name: "codecarto_publish",
-        description: "Publish a reimplementation-spec to a CodeCartographer library. Identified by library_path (absolute) or cwd's config.yaml. Content-hash idempotent — re-publishing identical spec bytes updates metadata in place rather than bumping the version. Required: source_repo, headline, and either spec (inline) or spec_path (absolute file). Slug derives from source_repo if not provided. If the library is namespaced, namespace is required (or pass cwd to inherit from config). Generation context (agent, model, vendor, reasoning) is passed via model_metadata so the host can record provenance; omitted fields default to 'unknown'.",
+        description: "Publish a reimplementation-spec to a CodeCartographer library. Identified by library_path (absolute) or cwd's config.yaml. Content-hash idempotent — re-publishing identical spec bytes updates metadata in place rather than bumping the version. Required: source_repo, headline, and either spec (inline) or spec_path (absolute file). Slug derives from source_repo if not provided. If the library is namespaced, namespace is required (or pass cwd to inherit from config). Generation context (agent, model, vendor, reasoning) is passed via model_metadata so the host can record provenance; omitted fields default to 'unknown'. When library.publish_confirm is set in config, a call without confirm: true is refused with a preview of what would be published (nothing is written); re-invoke with confirm: true to publish.",
         inputSchema: {
             type: "object",
             properties: {
@@ -1029,7 +1134,11 @@ const TOOLS = [
                 headline: { type: "string" },
                 tags: { type: "array", items: { type: "string" } },
                 capabilities: { type: "array", items: { type: "string" } },
-                confidentiality: { type: "string", enum: ["internal", "shared", "public"] },
+                confidentiality: {
+                    type: "string",
+                    enum: ["internal", "shared", "public"],
+                    description: "Classification of the entry. Defaults to internal. Ordered internal < shared < public; publish refuses an entry more restricted than the library's visibility unless allow_confidentiality_mismatch is set.",
+                },
                 model_metadata: {
                     type: "object",
                     properties: {
@@ -1046,13 +1155,21 @@ const TOOLS = [
                     type: "boolean",
                     description: "Permit publishing when the target entry already records a different source_repo. Off by default, because a mismatch usually means two projects derived the same slug and the spec would land in the wrong version history. Set only when the repository itself moved.",
                 },
+                allow_confidentiality_mismatch: {
+                    type: "boolean",
+                    description: "Permit publishing when the entry's confidentiality is more restricted than the library's visibility (internal < shared < public: an internal entry into a shared or public library, a shared entry into a public one). Off by default, because that direction exposes the spec to everyone the library reaches. An omitted confidentiality counts as internal. Set only when the exposure is intended; the recorded confidentiality is not changed.",
+                },
+                confirm: {
+                    type: "boolean",
+                    description: "Acknowledge the publish_confirm gate. When library.publish_confirm is set in config (user-global ~/.codecarto/config.yaml, or the workspace's .codecarto/workflow/config.yaml when cwd is passed), a call without confirm: true is refused and the refusal previews what would be published — library, entry, whether a new version or a metadata-only update, source_repo, headline, confidentiality — so the caller can show it before committing to the write. Pass true to publish. No effect when publish_confirm is unset or false.",
+                },
             },
             required: ["source_repo", "headline"],
         },
     },
     {
         name: "codecarto_library_list",
-        description: "List entries in a CodeCartographer library, optionally filtered by namespace, tag, slug, or source_repo. The library is identified by library_path (absolute) or by cwd's config.yaml.",
+        description: "List entries in a CodeCartographer library, optionally filtered by namespace, tag, slug, or source_repo. The library is identified by library_path (absolute) or by cwd's config.yaml. Flags entries whose versions disagree about source_repo (merged by a slug collision before publish refused cross-project appends); repair is manual.",
         inputSchema: {
             type: "object",
             properties: {
@@ -1067,7 +1184,7 @@ const TOOLS = [
     },
     {
         name: "codecarto_library_reindex",
-        description: "Regenerate index.yaml and INDEX.md for a CodeCartographer library from filesystem state. Use after manual edits or to resolve a git merge conflict on index.yaml.",
+        description: "Regenerate index.yaml and INDEX.md for a CodeCartographer library from filesystem state. Use after manual edits or to resolve a git merge conflict on index.yaml. Also reports entries whose versions disagree about source_repo (merged by a slug collision before publish refused cross-project appends); the index files are not changed and repair is manual.",
         inputSchema: {
             type: "object",
             properties: {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "codecartographer-pi",
-  "version": "0.17.0",
+  "version": "0.18.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",
@@ -64,7 +64,7 @@
     "@modelcontextprotocol/sdk": "^1.29.0"
   },
   "peerDependencies": {
-    "@earendil-works/pi-coding-agent": "^0.80.10",
+    "@earendil-works/pi-coding-agent": ">=0.84.0",
     "@sinclair/typebox": "*"
   },
   "pi": {