codecartographer-pi 0.12.3 → 0.12.4

package/dist/core/synthesis.js

@@ -78,25 +78,25 @@ export async function runPhasePreflight(state, phase) {
     if (checks.has("requires-vision-input")) {
         const visionPath = join(state.workspaceDir, SYNTHESIS_VISION_INPUT_PATH);
         if (!(await pathExists(visionPath))) {
-            throw new PhasePreflightError(phase.id, `the vision brief is missing at .codecarto/${SYNTHESIS_VISION_INPUT_PATH}. Create it before starting synthesis.`);
+            throw new PhasePreflightError(phase.id, `the vision brief is missing at .codecarto/${SYNTHESIS_VISION_INPUT_PATH}. Create that file and describe your product intent (audience, problem, desired outcome, constraints, non-goals). See .codecarto/templates/vision.md for the expected structure.`);
         }
         const rawVision = await readFile(visionPath, "utf8");
         if (!hasMeaningfulVisionContent(rawVision)) {
-            throw new PhasePreflightError(phase.id, `the vision brief at .codecarto/${SYNTHESIS_VISION_INPUT_PATH} is still empty. Describe the audience, problem, and desired outcome, then retry.`);
+            throw new PhasePreflightError(phase.id, `the vision brief at .codecarto/${SYNTHESIS_VISION_INPUT_PATH} appears to be empty or only contains comments. Write your product intent into that file — at minimum: who the product is for, what problem it solves, and what outcome you want. See .codecarto/templates/vision.md for the full structure.`);
         }
     }
     if (checks.has("requires-library")) {
         const config = await loadCodecartoConfig(state.workspaceDir);
         if (!config.library.path) {
-            throw new PhasePreflightError(phase.id, "no library.path is configured. Set it in ~/.codecarto/config.yaml or .codecarto/workflow/config.yaml.");
+            throw new PhasePreflightError(phase.id, "no library.path is configured. Create a library directory with a .codecarto-library marker file, then set library.path in ~/.codecarto/config.yaml or .codecarto/workflow/config.yaml. Example config:\n  library:\n    path: ~/codecarto-library\n    publish_confirm: true");
         }
         const marker = await discoverLibrary(config.library.path);
         if (!marker) {
-            throw new PhasePreflightError(phase.id, `no CodeCartographer library was found at ${config.library.path} (missing .codecarto-library).`);
+            throw new PhasePreflightError(phase.id, `no CodeCartographer library was found at ${config.library.path} (missing .codecarto-library). Create a .codecarto-library marker file in that directory with: {"schema_version": 1, "name": "personal-library", "visibility": "internal", "namespaced": false}`);
         }
         const entries = await listEntries(config.library.path);
         if (entries.length === 0) {
-            throw new PhasePreflightError(phase.id, `the configured library at ${config.library.path} has no entries. Publish at least one reimplementation spec first.`);
+            throw new PhasePreflightError(phase.id, `the configured library at ${config.library.path} has no entries. Run a reverse-engineering pipeline (e.g. /codecarto-init full-with-deep-audit) on a source repository, then use /codecarto-publish to publish at least one reimplementation spec into the library before starting synthesis.`);
         }
         result.libraryPath = config.library.path;
         result.libraryName = marker.name;
@@ -110,13 +110,13 @@ export async function runPhasePreflight(state, phase) {
         result.confirmedSelections = parseConfirmedProposalSelections(await readFile(proposalPath, "utf8"));
         result.confirmedEntries = result.confirmedSelections.map((selection) => selection.ref);
         if (result.confirmedSelections.length === 0) {
-            throw new PhasePreflightError(phase.id, `no library entries are confirmed in .codecarto/${SYNTHESIS_PROPOSAL_PATH}. Change at least one [ ] checkbox to [x], then retry.`);
+            throw new PhasePreflightError(phase.id, `no library entries are confirmed in .codecarto/${SYNTHESIS_PROPOSAL_PATH}. Open that file and change at least one [ ] checkbox to [x] for the entry you want to include, then retry.`);
         }
         const available = new Map(result.libraryEntries.map((entry) => [entry.ref, entry]));
         for (const selection of result.confirmedSelections) {
             const entry = available.get(selection.ref);
             if (!entry || !entry.versions.includes(selection.version)) {
-                throw new PhasePreflightError(phase.id, `confirmed selection ${selection.ref}@v${selection.version} is not present in the configured library. Re-run the proposal phase or correct the checked row.`);
+                throw new PhasePreflightError(phase.id, `confirmed selection ${selection.ref}@v${selection.version} is not present in the configured library. Edit .codecarto/${SYNTHESIS_PROPOSAL_PATH} to correct the checked row (change [x] back to [ ] or update the version), or re-run the goal-synthesis-propose phase to regenerate the proposal.`);
             }
             selection.specPath = specPathForVersion(result.libraryPath, selection.ref, selection.version);
         }

package/dist/extensions/codecarto/index.js

@@ -1,4 +1,4 @@
-import { cp, mkdir, readFile, rm, writeFile } from "node:fs/promises";
+import { cp, mkdir, readFile, rename, writeFile } from "node:fs/promises";
 import { basename, join, resolve } from "node:path";
 import { autoCompletePhase, buildAutoSummary, isPhaseRunning, runAuto, runSinglePhase } from "./auto-runner.js";
 import { disposeAgentsWidget } from "./agent-widget.js";
@@ -220,10 +220,13 @@ export default function codeCartographerExtension(pi) {
             if (targetExists) {
                 const sameWorkspace = normalizeForComparison(await canonicalPath(targetWorkspaceDir)) === normalizeForComparison(await canonicalPath(sourceWorkspaceDir));
                 if (!sameWorkspace) {
-                    const overwrite = await ctx.ui.confirm("CodeCartographer already exists", "A .codecarto/ directory already exists in this repository. Overwrite it?");
+                    const overwrite = await ctx.ui.confirm("CodeCartographer already exists — data will be lost", "A .codecarto/ directory already exists in this repository. Re-initializing will back up the existing workspace to .codecarto-backup-TIMESTAMP/ and create a fresh one. All phase findings, handoffs, usage data, closeouts, and progress will be moved to the backup. Consider /codecarto-open to reattach without resetting. Continue?");
                     if (!overwrite)
                         return;
-                    await rm(targetWorkspaceDir, { recursive: true, force: true });
+                    const backupDir = join(ctx.cwd, `.codecarto-backup-${new Date().toISOString().replace(/[:.]/g, "-")}`);
+                    await rename(targetWorkspaceDir, backupDir);
+                    if (ctx.hasUI)
+                        ctx.ui.notify(`Backed up existing workspace to ${basename(backupDir)}/`, "info");
                 }
             }
             if (!(await pathExists(targetWorkspaceDir))) {
@@ -538,12 +541,12 @@ export default function codeCartographerExtension(pi) {
                 return;
             const config = await loadCodecartoConfig(state.workspaceDir);
             if (!config.library.path) {
-                ctx.ui.notify("No library.path is configured. Set it in ~/.codecarto/config.yaml or .codecarto/workflow/config.yaml.", "error");
+                ctx.ui.notify("No library.path is configured. Create a library directory with a .codecarto-library marker, then set library.path in ~/.codecarto/config.yaml or .codecarto/workflow/config.yaml.", "error");
                 return;
             }
             const marker = await discoverLibrary(config.library.path);
             if (!marker) {
-                ctx.ui.notify(`No CodeCartographer library at ${config.library.path} (missing .codecarto-library).`, "error");
+                ctx.ui.notify(`No CodeCartographer library at ${config.library.path} (missing .codecarto-library). Create a .codecarto-library marker file in that directory.`, "error");
                 return;
             }
             const phase = resolvePhase(state, "reimplementation-spec");

package/dist/mcp-server/server.js

@@ -13,7 +13,7 @@
 import { Server } from "@modelcontextprotocol/sdk/server/index.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { CallToolRequestSchema, ErrorCode, ListToolsRequestSchema, McpError, } from "@modelcontextprotocol/sdk/types.js";
-import { cp, mkdir, readFile, rm, writeFile } from "node:fs/promises";
+import { cp, mkdir, readFile, rename, writeFile } from "node:fs/promises";
 import { basename, isAbsolute, join } from "node:path";
 import { buildPhasePrompt, buildSkillPrompt, buildValidationSummary, canonicalPath, completeValidatedPhase, createEmptyStatus, DEFAULT_PIPELINE_PATH, deriveSlug, discoverLibrary, getNextEligiblePhase, getPipelineLabel, getWorkspaceState, isValidSlug, listEntries, listSkillNames, loadCodecartoConfig, loadYamlFile, normalizeForComparison, PACKAGE_VERSION, packagedWorkspaceDir, pathExists, PhasePreflightError, publishEntry, reindex as libraryReindex, resolvePhase, resolvePipelineChoice, stringifySimpleYaml, validatePhaseOutput, } from "../core/index.js";
 // ---------- input helpers ----------
@@ -77,9 +77,10 @@ export async function handleInit(args) {
     }
     if (targetExists && !sameWorkspace) {
         if (!args.force) {
-            throw new McpError(ErrorCode.InvalidRequest, `A .codecarto/ directory already exists at ${targetWorkspaceDir}. Pass force: true to overwrite it.`);
+            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.`);
         }
-        await rm(targetWorkspaceDir, { recursive: true, force: true });
+        const backupDir = join(cwd, `.codecarto-backup-${new Date().toISOString().replace(/[:.]/g, "-")}`);
+        await rename(targetWorkspaceDir, backupDir);
     }
     if (!(await pathExists(targetWorkspaceDir))) {
         await mkdir(cwd, { recursive: true });
@@ -463,7 +464,7 @@ export async function handleLibraryReindex(args) {
 const TOOLS = [
     {
         name: "codecarto_init",
-        description: "Initialize a CodeCartographer workspace (.codecarto/) in a target repository. Copies the packaged framework template and writes a fresh status.yaml for the chosen pipeline. Errors if .codecarto/ already exists unless force is true.",
+        description: "Initialize a CodeCartographer workspace (.codecarto/) in a target repository. Copies the packaged framework template and writes a fresh status.yaml for the chosen pipeline. If .codecarto/ already exists, pass force: true to back up the existing workspace to .codecarto-backup-TIMESTAMP/ and create a fresh one. Warning: backing up moves all existing findings, handoffs, usage data, closeouts, and phase progress to the backup directory.",
         inputSchema: {
             type: "object",
             properties: {
@@ -474,7 +475,7 @@ const TOOLS = [
                 },
                 force: {
                     type: "boolean",
-                    description: "Overwrite an existing .codecarto/ directory if present (default false).",
+                    description: "Back up and overwrite an existing .codecarto/ directory if present (default false).",
                 },
             },
             required: ["cwd"],
@@ -625,7 +626,7 @@ const HANDLERS = {
 };
 // ---------- server bootstrap ----------
 export function buildServer() {
-    const server = new Server({ name: "codecartographer", version: "0.2.0" }, { capabilities: { tools: {} } });
+    const server = new Server({ name: "codecartographer", version: PACKAGE_VERSION }, { capabilities: { tools: {} } });
     server.setRequestHandler(ListToolsRequestSchema, async () => ({ tools: TOOLS }));
     server.setRequestHandler(CallToolRequestSchema, async (request) => {
         const handler = HANDLERS[request.params.name];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "codecartographer-pi",
-  "version": "0.12.3",
+  "version": "0.12.4",
   "mcpName": "io.github.HuginnIndustries/codecartographer",
   "description": "Evidence-backed reverse engineering and human-gated software planning for Pi and MCP coding agents.",
   "type": "module",