codecartographer-pi 0.1.0 → 0.1.2

package/dist/extensions/codecarto/index.js

@@ -0,0 +1,372 @@
+import { cp, mkdir, rm, writeFile } from "node:fs/promises";
+import { basename, join, resolve } from "node:path";
+import { buildPhasePrompt, buildSkillPrompt, buildThreadLogEntry, buildValidationSummary, canonicalPath, closeoutFileName, createEmptyStatus, dateOnly, DEFAULT_PIPELINE_PATH, ensureCloseoutStub, getNextEligiblePhase, getPipelineLabel, getWorkspaceState, isWithinPath, listSkillNames, loadYamlFile, normalizeForComparison, normalizeStatus, packagedWorkspaceDir, pathExists, PIPELINE_ALIASES, resolvePhase, resolvePipelineChoice, stringifySimpleYaml, uniqueStrings, updateStatusAtomically, validatePhaseOutput, } from "../../core/index.js";
+const STATUS_WIDGET_ID = "codecarto-widget";
+const STATUS_LINE_ID = "codecarto-status";
+const SAFE_TOOL_NAMES = ["read", "grep", "find", "ls", "edit", "write"];
+function buildStatusLines(state, extraLines = []) {
+    const nextPhase = getNextEligiblePhase(state);
+    const currentPhase = nextPhase?.id ?? state.status.current_phase ?? "complete";
+    const pipelineLabel = getPipelineLabel(state.status.pipeline);
+    const completedCount = state.pipeline.phase_order.filter((phaseId) => state.status.phases[phaseId]?.status === "complete").length;
+    const currentOpenQuestions = currentPhase === "complete" ? 0 : state.status.phases[currentPhase]?.open_questions.length ?? 0;
+    const totalCarryForward = Object.values(state.status.phases).reduce((sum, phase) => sum + (phase.carry_forward?.length ?? 0), 0);
+    const nextAction = state.status.next_actions[0] ?? (nextPhase ? `Next: ${nextPhase.id}` : "All phases complete.");
+    const lines = [
+        "CodeCartographer",
+        `Phase: ${currentPhase}`,
+        `Pipeline: ${pipelineLabel}`,
+        `Progress: ${completedCount}/${state.pipeline.phase_order.length} complete`,
+        `Open questions: ${currentOpenQuestions}`,
+        `Carry-forward: ${totalCarryForward}`,
+        `Next: ${nextAction}`,
+    ];
+    if (extraLines.length > 0) {
+        lines.push("", ...extraLines);
+    }
+    return lines;
+}
+function setUiState(ctx, state, extraLines = []) {
+    if (!ctx.hasUI)
+        return;
+    if (!state) {
+        ctx.ui.setStatus(STATUS_LINE_ID, undefined);
+        ctx.ui.setWidget(STATUS_WIDGET_ID, undefined);
+        return;
+    }
+    const theme = ctx.ui.theme;
+    const currentPhase = getNextEligiblePhase(state)?.id ?? state.status.current_phase ?? "complete";
+    ctx.ui.setStatus(STATUS_LINE_ID, `${theme.fg("accent", "CC")} ${theme.fg("dim", currentPhase)}`);
+    ctx.ui.setWidget(STATUS_WIDGET_ID, buildStatusLines(state, extraLines));
+}
+export default function codeCartographerExtension(pi) {
+    let lastFeedbackLines = [];
+    const readWorkspaceState = async (ctx, notifyOnError = true) => {
+        try {
+            return await getWorkspaceState(ctx.cwd);
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            lastFeedbackLines = [message];
+            setUiState(ctx, null);
+            if (notifyOnError && ctx.hasUI)
+                ctx.ui.notify(message, "error");
+            return null;
+        }
+    };
+    const refreshWorkspaceUi = async (ctx, extraLines) => {
+        const state = await readWorkspaceState(ctx, false);
+        setUiState(ctx, state, extraLines ?? lastFeedbackLines);
+        if (state) {
+            const phaseId = getNextEligiblePhase(state)?.id ?? state.status.current_phase;
+            if (phaseId)
+                pi.setSessionName(`CodeCartographer: ${phaseId}`);
+        }
+        return state;
+    };
+    const ensureWorkspaceState = async (ctx) => {
+        const state = await readWorkspaceState(ctx);
+        if (state)
+            return state;
+        const hasWorkspace = await pathExists(join(ctx.cwd, ".codecarto", "workflow", "status.yaml"));
+        if (!hasWorkspace)
+            ctx.ui.notify("No .codecarto/ workspace found. Run /codecarto-init first.", "warning");
+        return null;
+    };
+    pi.on("session_start", async (_event, ctx) => {
+        const state = await refreshWorkspaceUi(ctx);
+        if (!state)
+            return;
+        pi.setActiveTools(SAFE_TOOL_NAMES);
+    });
+    pi.on("agent_end", async (_event, ctx) => {
+        await refreshWorkspaceUi(ctx);
+    });
+    pi.on("tool_call", async (event, ctx) => {
+        const workspaceDir = join(ctx.cwd, ".codecarto");
+        if (!(await pathExists(workspaceDir)))
+            return undefined;
+        if (event.toolName === "bash") {
+            if (ctx.hasUI)
+                ctx.ui.notify("Blocked bash in CodeCartographer mode", "warning");
+            return { block: true, reason: "CodeCartographer mode disables bash to keep source analysis read-only." };
+        }
+        if (event.toolName === "edit" || event.toolName === "write") {
+            const inputPath = typeof event.input.path === "string" ? event.input.path : "";
+            const strippedPath = inputPath.startsWith("@") ? inputPath.slice(1) : inputPath;
+            const targetPath = await canonicalPath(resolve(ctx.cwd, strippedPath));
+            const allowedRoot = await canonicalPath(workspaceDir);
+            if (!isWithinPath(targetPath, allowedRoot)) {
+                if (ctx.hasUI) {
+                    ctx.ui.notify(`Blocked ${event.toolName} outside .codecarto/: ${inputPath}`, "warning");
+                }
+                return { block: true, reason: `CodeCartographer mode only allows ${event.toolName} within .codecarto/` };
+            }
+        }
+        return undefined;
+    });
+    pi.registerCommand("codecarto-init", {
+        description: "Initialize .codecarto/ in the current repository",
+        getArgumentCompletions: (prefix) => {
+            const items = Object.keys(PIPELINE_ALIASES)
+                .filter((value) => value.startsWith(prefix))
+                .map((value) => ({ value, label: value }));
+            return items.length > 0 ? items : null;
+        },
+        handler: async (args, ctx) => {
+            const trimmedArgs = args.trim();
+            const pipelineChoice = resolvePipelineChoice(trimmedArgs);
+            if (trimmedArgs && !pipelineChoice) {
+                ctx.ui.notify(`Unknown pipeline: ${trimmedArgs}`, "error");
+                return;
+            }
+            const targetWorkspaceDir = join(ctx.cwd, ".codecarto");
+            const sourceWorkspaceDir = packagedWorkspaceDir;
+            if (!(await pathExists(sourceWorkspaceDir))) {
+                ctx.ui.notify("Packaged .codecarto assets are missing.", "error");
+                return;
+            }
+            const targetExists = await pathExists(targetWorkspaceDir);
+            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?");
+                    if (!overwrite)
+                        return;
+                    await rm(targetWorkspaceDir, { recursive: true, force: true });
+                }
+            }
+            if (!(await pathExists(targetWorkspaceDir))) {
+                await mkdir(ctx.cwd, { recursive: true });
+                await cp(sourceWorkspaceDir, targetWorkspaceDir, { recursive: true });
+            }
+            const rawStatusPath = join(targetWorkspaceDir, "workflow", "status.yaml");
+            const rawStatus = (await loadYamlFile(rawStatusPath)) ?? {};
+            const selectedPipelinePath = pipelineChoice ?? rawStatus.pipeline?.trim() ?? DEFAULT_PIPELINE_PATH;
+            const resolvedPipelinePath = join(targetWorkspaceDir, selectedPipelinePath);
+            if (!(await pathExists(resolvedPipelinePath))) {
+                ctx.ui.notify(`Pipeline not found: ${selectedPipelinePath}`, "error");
+                return;
+            }
+            const pipeline = await loadYamlFile(resolvedPipelinePath);
+            const normalizedStatus = createEmptyStatus(basename(ctx.cwd), selectedPipelinePath, pipeline);
+            normalizedStatus.last_updated = new Date().toISOString();
+            await writeFile(rawStatusPath, `${stringifySimpleYaml(normalizedStatus)}\n`, "utf8");
+            lastFeedbackLines = [`Initialized workspace with pipeline: ${getPipelineLabel(selectedPipelinePath)}`];
+            ctx.ui.notify(`Initialized CodeCartographer (${getPipelineLabel(selectedPipelinePath)})`, "info");
+            await ctx.reload();
+            return;
+        },
+    });
+    pi.registerCommand("codecarto-status", {
+        description: "Show the current CodeCartographer phase and progress",
+        handler: async (_args, ctx) => {
+            const state = await ensureWorkspaceState(ctx);
+            if (!state)
+                return;
+            const nextPhase = getNextEligiblePhase(state)?.id ?? "complete";
+            lastFeedbackLines = [`Current phase: ${nextPhase}`, `Pipeline: ${getPipelineLabel(state.status.pipeline)}`];
+            setUiState(ctx, state, lastFeedbackLines);
+            ctx.ui.notify(`CodeCartographer phase: ${nextPhase}`, "info");
+        },
+    });
+    pi.registerCommand("codecarto-next", {
+        description: "Queue the next eligible CodeCartographer phase prompt",
+        handler: async (_args, ctx) => {
+            const state = await ensureWorkspaceState(ctx);
+            if (!state)
+                return;
+            const phase = getNextEligiblePhase(state);
+            if (!phase) {
+                lastFeedbackLines = ["All phases complete."];
+                setUiState(ctx, state, lastFeedbackLines);
+                ctx.ui.notify("All CodeCartographer phases are complete.", "info");
+                return;
+            }
+            const prompt = await buildPhasePrompt(state, phase, false);
+            if (ctx.isIdle()) {
+                pi.sendUserMessage(prompt);
+            }
+            else {
+                pi.sendUserMessage(prompt, { deliverAs: "followUp" });
+            }
+            lastFeedbackLines = [`Queued phase prompt for ${phase.id}`];
+            setUiState(ctx, state, lastFeedbackLines);
+            ctx.ui.notify(`Queued CodeCartographer phase: ${phase.id}`, "info");
+        },
+    });
+    pi.registerCommand("codecarto-phase", {
+        description: "Queue a specific CodeCartographer phase prompt: /codecarto-phase <phase>",
+        handler: async (args, ctx) => {
+            const phaseId = args.trim();
+            if (!phaseId) {
+                ctx.ui.notify("Usage: /codecarto-phase <phase>", "warning");
+                return;
+            }
+            const state = await ensureWorkspaceState(ctx);
+            if (!state)
+                return;
+            const phase = resolvePhase(state, phaseId);
+            if (!phase) {
+                ctx.ui.notify(`Unknown phase: ${phaseId}`, "error");
+                return;
+            }
+            const prompt = await buildPhasePrompt(state, phase, true);
+            if (ctx.isIdle()) {
+                pi.sendUserMessage(prompt);
+            }
+            else {
+                pi.sendUserMessage(prompt, { deliverAs: "followUp" });
+            }
+            lastFeedbackLines = [`Queued explicit phase prompt for ${phase.id}`];
+            setUiState(ctx, state, lastFeedbackLines);
+            ctx.ui.notify(`Queued CodeCartographer phase: ${phase.id}`, "info");
+        },
+    });
+    pi.registerCommand("codecarto-validate", {
+        description: "Validate a phase output: /codecarto-validate [phase]",
+        handler: async (args, ctx) => {
+            const state = await ensureWorkspaceState(ctx);
+            if (!state)
+                return;
+            const validation = await validatePhaseOutput(state, args.trim() || undefined);
+            lastFeedbackLines = buildValidationSummary(validation);
+            setUiState(ctx, state, lastFeedbackLines);
+            const level = validation.overall === "FAIL" || validation.overall === "MISSING" ? "error" : validation.overall === "PASS WITH GAPS" ? "warning" : "info";
+            ctx.ui.notify(`Validation ${validation.phaseId}: ${validation.overall}`, level);
+        },
+    });
+    pi.registerCommand("codecarto-complete", {
+        description: "Mark a phase complete after validation passes: /codecarto-complete [phase]",
+        handler: async (args, ctx) => {
+            const currentState = await ensureWorkspaceState(ctx);
+            if (!currentState)
+                return;
+            const validation = await validatePhaseOutput(currentState, args.trim() || undefined);
+            if (validation.overall === "FAIL" || validation.overall === "MISSING") {
+                lastFeedbackLines = buildValidationSummary(validation);
+                setUiState(ctx, currentState, lastFeedbackLines);
+                ctx.ui.notify(`Cannot complete ${validation.phaseId}: ${validation.overall}`, "error");
+                return;
+            }
+            const completionTimestamp = new Date().toISOString();
+            const updatedState = await updateStatusAtomically(ctx.cwd, (lockedState) => {
+                const phase = resolvePhase(lockedState, validation.phaseId);
+                if (!phase?.primary_output) {
+                    throw new Error(`Phase ${validation.phaseId} is missing primary_output.`);
+                }
+                const nextStatus = normalizeStatus(lockedState.status, lockedState.pipeline, lockedState.status.pipeline, lockedState.cwd);
+                const existingPhase = nextStatus.phases[validation.phaseId] ?? {
+                    status: "pending",
+                    owner_notes: [],
+                    outputs_present: [],
+                    open_questions: [],
+                    carry_forward: [],
+                };
+                const gapEntries = validation.rows
+                    .filter((row) => row.result.toUpperCase().includes("PARTIAL"))
+                    .map((row) => ({
+                    kind: "needs-maintainer-decision",
+                    description: row.criterion || "Partial validation gap",
+                    deferred_reason: row.evidence || "Marked PARTIAL by validation",
+                }));
+                const mergedOpenQuestions = [...existingPhase.open_questions];
+                for (const candidate of gapEntries) {
+                    const dupe = mergedOpenQuestions.some((entry) => entry.description === candidate.description && entry.deferred_reason === candidate.deferred_reason);
+                    if (!dupe)
+                        mergedOpenQuestions.push(candidate);
+                }
+                nextStatus.phases[validation.phaseId] = {
+                    status: "complete",
+                    owner_notes: uniqueStrings([
+                        ...existingPhase.owner_notes,
+                        `Completed via /codecarto-complete on ${completionTimestamp}.`,
+                        `Primary output: .codecarto/${validation.primaryOutput}`,
+                        `Validation: ${validation.overall}`,
+                    ]).slice(-3),
+                    outputs_present: uniqueStrings([...existingPhase.outputs_present, validation.primaryOutput]),
+                    open_questions: mergedOpenQuestions,
+                    carry_forward: existingPhase.carry_forward ?? [],
+                };
+                nextStatus.last_updated = completionTimestamp;
+                const updatedWorkspaceState = {
+                    ...lockedState,
+                    status: nextStatus,
+                };
+                const nextEligible = getNextEligiblePhase(updatedWorkspaceState);
+                nextStatus.current_phase = nextEligible?.id ?? "complete";
+                nextStatus.next_actions = nextEligible
+                    ? [
+                        `Begin ${nextEligible.id} phase by producing ${nextEligible.primary_output ?? `findings/${nextEligible.id}/`}`,
+                    ]
+                    : ["All phases complete. Review findings, open questions, and downstream implementation notes."];
+                return {
+                    state: {
+                        ...updatedWorkspaceState,
+                        status: nextStatus,
+                    },
+                    threadLogEntry: buildThreadLogEntry(validation.phaseId, validation, completionTimestamp),
+                };
+            });
+            let closeoutNotice;
+            try {
+                const created = await ensureCloseoutStub(updatedState.workspaceDir, validation.phaseId, completionTimestamp);
+                if (created) {
+                    closeoutNotice = `Closeout stub: .codecarto/closeouts/${closeoutFileName(dateOnly(completionTimestamp), validation.phaseId)} (fill it in)`;
+                }
+            }
+            catch (error) {
+                const message = error instanceof Error ? error.message : String(error);
+                closeoutNotice = `Closeout stub not created: ${message}`;
+            }
+            lastFeedbackLines = [
+                `Completed phase: ${validation.phaseId}`,
+                `Validation: ${validation.overall}`,
+                `Next phase: ${updatedState.status.current_phase}`,
+            ];
+            if (closeoutNotice)
+                lastFeedbackLines.push(closeoutNotice);
+            setUiState(ctx, updatedState, lastFeedbackLines);
+            ctx.ui.notify(`Marked ${validation.phaseId} complete`, validation.overall === "PASS WITH GAPS" ? "warning" : "info");
+            if (closeoutNotice)
+                ctx.ui.notify(closeoutNotice, "info");
+        },
+    });
+    pi.registerCommand("codecarto-skill", {
+        description: "Run a post-pipeline skill (after all phases are complete): /codecarto-skill <name>",
+        handler: async (args, ctx) => {
+            const skillName = args.trim();
+            if (!skillName) {
+                const available = await listSkillNames(join(ctx.cwd, ".codecarto"));
+                const hint = available.length > 0 ? ` (available: ${available.join(", ")})` : "";
+                ctx.ui.notify(`Usage: /codecarto-skill <name>${hint}`, "warning");
+                return;
+            }
+            const state = await ensureWorkspaceState(ctx);
+            if (!state)
+                return;
+            const nextPhase = getNextEligiblePhase(state);
+            if (nextPhase) {
+                ctx.ui.notify(`Cannot run skill: pipeline is not complete (next phase: ${nextPhase.id}). Finish the pipeline before running post-pipeline skills.`, "error");
+                return;
+            }
+            const skillFile = join(state.workspaceDir, "skills", skillName, "SKILL.md");
+            if (!(await pathExists(skillFile))) {
+                const available = await listSkillNames(state.workspaceDir);
+                const hint = available.length > 0 ? ` (available: ${available.join(", ")})` : " (no skills installed)";
+                ctx.ui.notify(`Unknown skill: ${skillName}${hint}`, "error");
+                return;
+            }
+            const prompt = await buildSkillPrompt(state, skillName);
+            if (ctx.isIdle()) {
+                pi.sendUserMessage(prompt);
+            }
+            else {
+                pi.sendUserMessage(prompt, { deliverAs: "followUp" });
+            }
+            lastFeedbackLines = [`Queued post-pipeline skill: ${skillName}`];
+            setUiState(ctx, state, lastFeedbackLines);
+            ctx.ui.notify(`Queued CodeCartographer skill: ${skillName}`, "info");
+        },
+    });
+}

package/dist/mcp-server/bin.d.mts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/mcp-server/bin.mjs

@@ -0,0 +1,9 @@
+#!/usr/bin/env node
+// This file is shipped from dist/. It imports the compiled server.js next to
+// it. Running it directly from the source tree will fail (server.js does not
+// exist in source); run `npm run build` first, or use the published package.
+import { startStdioServer } from "./server.js";
+startStdioServer().catch((error) => {
+    console.error("[codecarto-mcp] failed to start:", error);
+    process.exit(1);
+});

package/dist/mcp-server/server.d.ts

@@ -0,0 +1,105 @@
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+export declare function handleInit(args: {
+    cwd: string;
+    pipeline?: string;
+    force?: boolean;
+}): Promise<{
+    content: Array<{
+        type: "text";
+        text: string;
+    }>;
+    structuredContent?: Record<string, unknown>;
+}>;
+export declare function handleStatus(args: {
+    cwd: string;
+}): Promise<{
+    content: Array<{
+        type: "text";
+        text: string;
+    }>;
+    structuredContent?: Record<string, unknown>;
+}>;
+export declare function handleNext(args: {
+    cwd: string;
+}): Promise<{
+    content: Array<{
+        type: "text";
+        text: string;
+    }>;
+    structuredContent?: Record<string, unknown>;
+}>;
+export declare function handlePhase(args: {
+    cwd: string;
+    phase: string;
+}): Promise<{
+    content: Array<{
+        type: "text";
+        text: string;
+    }>;
+    structuredContent?: Record<string, unknown>;
+}>;
+export declare function handleValidate(args: {
+    cwd: string;
+    phase?: string;
+}): Promise<{
+    content: Array<{
+        type: "text";
+        text: string;
+    }>;
+    structuredContent?: Record<string, unknown>;
+}>;
+export declare function handleComplete(args: {
+    cwd: string;
+    phase?: string;
+}): Promise<{
+    content: Array<{
+        type: "text";
+        text: string;
+    }>;
+    structuredContent?: Record<string, unknown>;
+}>;
+export declare function handleSkill(args: {
+    cwd: string;
+    name: string;
+}): Promise<{
+    content: Array<{
+        type: "text";
+        text: string;
+    }>;
+    structuredContent?: Record<string, unknown>;
+}>;
+export declare function buildServer(): Server<{
+    method: string;
+    params?: {
+        [x: string]: unknown;
+        _meta?: {
+            [x: string]: unknown;
+            progressToken?: string | number;
+            "io.modelcontextprotocol/related-task"?: {
+                taskId: string;
+            };
+        };
+    };
+}, {
+    method: string;
+    params?: {
+        [x: string]: unknown;
+        _meta?: {
+            [x: string]: unknown;
+            progressToken?: string | number;
+            "io.modelcontextprotocol/related-task"?: {
+                taskId: string;
+            };
+        };
+    };
+}, {
+    [x: string]: unknown;
+    _meta?: {
+        [x: string]: unknown;
+        progressToken?: string | number;
+        "io.modelcontextprotocol/related-task"?: {
+            taskId: string;
+        };
+    };
+}>;
+export declare function startStdioServer(): Promise<void>;