codecartographer-pi 0.8.0 → 0.9.0

package/dist/core/orchestrator-config.d.ts

@@ -6,15 +6,53 @@ export interface OrchestratorConfig {
      *  tokens, opt-in. */
     llm_steer_next_phase: boolean;
 }
+export interface LibraryConfig {
+    /** Absolute, tilde-expanded path to the CodeCartographer library
+     *  this workspace publishes to and reads from. Null if unconfigured —
+     *  callers should prompt the user on first use. */
+    path: string | null;
+    /** Default namespace for entries published by this workspace.
+     *  Null if unconfigured (single-tenant libraries should use null). */
+    namespace: string | null;
+    /** Whether `codecarto publish` should display a confirmation prompt
+     *  with slug + source + library path before writing. Default true. */
+    publish_confirm: boolean;
+}
 export interface CodecartoConfig {
     orchestrator: OrchestratorConfig;
+    library: LibraryConfig;
 }
 export declare const CONFIG_RELATIVE_PATH = "workflow/config.yaml";
+export declare const USER_CONFIG_DIR: string;
+export declare const USER_CONFIG_PATH: string;
+/**
+ * Tests and tooling can override the user-global config path by setting
+ * `CODECARTO_USER_CONFIG_PATH`. The exported constant above is the default
+ * for documentation and onboarding flows. Internal load functions go
+ * through `resolveUserConfigPath()` so the override takes effect.
+ */
+export declare function resolveUserConfigPath(): string;
 type RawConfig = {
     orchestrator?: Partial<{
         llm_steer_next_phase: unknown;
     }>;
+    library?: Partial<{
+        path: unknown;
+        namespace: unknown;
+        publish_confirm: unknown;
+    }>;
 };
 export declare function loadCodecartoConfig(workspaceDir: PathLike): Promise<CodecartoConfig>;
+/**
+ * Read the user-global config directly. Exposed so wrappers can show
+ * "your library is at <path>" in onboarding flows without having to
+ * load a workspace first.
+ */
+export declare function loadUserConfig(): Promise<CodecartoConfig>;
+/**
+ * Apply one raw config layer over an existing config. Public so tests can
+ * exercise layering without filesystem fixtures, and so wrappers can mock
+ * a layer in memory (e.g. "what if library_path were X").
+ */
 export declare function mergeConfig(raw: RawConfig | null | undefined): CodecartoConfig;
 export {};

package/dist/core/orchestrator-config.js

@@ -1,45 +1,112 @@
-// Workspace-level orchestrator configuration. Lives at
-// `.codecarto/workflow/config.yaml`. Missing file or missing keys fall back
-// to defaults, so existing workspaces created before this file existed
-// keep working unchanged. Schema is intentionally narrow — one surface
-// per feature, easy to grow.
-import { join } from "node:path";
-import { pathExists } from "./utils.js";
+// Workspace-level orchestrator configuration. Two layers:
+//
+//   1. User-global  — `~/.codecarto/config.yaml`. Default location for
+//      `library.path`, `library.namespace`, `library.publish_confirm`, and
+//      the orchestrator toggles. Shared across all workspaces on this
+//      machine.
+//   2. Per-workspace — `.codecarto/workflow/config.yaml` inside the
+//      workspace. Overrides individual keys from the user-global layer.
+//
+// Resolution order (top wins): per-workspace > user-global > defaults.
+// Missing files at either layer fall back to defaults; malformed YAML
+// at either layer is non-fatal (drops the layer, logs nothing).
+//
+// `library.path` is returned tilde-expanded and absolute so consumers
+// don't have to expand themselves.
+import { homedir } from "node:os";
+import { join, resolve } from "node:path";
+import { expandTilde, pathExists } from "./utils.js";
 import { loadYamlFile } from "./yaml.js";
 export const CONFIG_RELATIVE_PATH = "workflow/config.yaml";
+export const USER_CONFIG_DIR = join(homedir(), ".codecarto");
+export const USER_CONFIG_PATH = join(USER_CONFIG_DIR, "config.yaml");
+/**
+ * Tests and tooling can override the user-global config path by setting
+ * `CODECARTO_USER_CONFIG_PATH`. The exported constant above is the default
+ * for documentation and onboarding flows. Internal load functions go
+ * through `resolveUserConfigPath()` so the override takes effect.
+ */
+export function resolveUserConfigPath() {
+    return process.env.CODECARTO_USER_CONFIG_PATH ?? USER_CONFIG_PATH;
+}
 const DEFAULT_CONFIG = {
     orchestrator: {
         llm_steer_next_phase: false,
     },
+    library: {
+        path: null,
+        namespace: null,
+        publish_confirm: true,
+    },
 };
 export async function loadCodecartoConfig(workspaceDir) {
-    const configPath = join(workspaceDir, CONFIG_RELATIVE_PATH);
-    if (!(await pathExists(configPath)))
-        return cloneDefault();
+    const userRaw = await loadRawIfExists(resolveUserConfigPath());
+    const workspaceRaw = await loadRawIfExists(join(workspaceDir, CONFIG_RELATIVE_PATH));
+    return mergeLayered([userRaw, workspaceRaw]);
+}
+/**
+ * Read the user-global config directly. Exposed so wrappers can show
+ * "your library is at <path>" in onboarding flows without having to
+ * load a workspace first.
+ */
+export async function loadUserConfig() {
+    const userRaw = await loadRawIfExists(resolveUserConfigPath());
+    return mergeLayered([userRaw]);
+}
+async function loadRawIfExists(path) {
+    if (!(await pathExists(path)))
+        return null;
     try {
-        const raw = await loadYamlFile(configPath);
-        return mergeConfig(raw);
+        return await loadYamlFile(path);
     }
     catch {
-        // Malformed YAML: fall back to defaults rather than failing the
-        // command. The user can fix it; a broken config shouldn't block work.
-        return cloneDefault();
+        return null;
     }
 }
+function mergeLayered(layers) {
+    let merged = cloneDefault();
+    for (const layer of layers)
+        merged = applyRaw(merged, layer);
+    return merged;
+}
+/**
+ * Apply one raw config layer over an existing config. Public so tests can
+ * exercise layering without filesystem fixtures, and so wrappers can mock
+ * a layer in memory (e.g. "what if library_path were X").
+ */
 export function mergeConfig(raw) {
-    const merged = cloneDefault();
+    return applyRaw(cloneDefault(), raw);
+}
+function applyRaw(base, raw) {
     if (!raw || typeof raw !== "object")
-        return merged;
+        return base;
+    const out = {
+        orchestrator: { ...base.orchestrator },
+        library: { ...base.library },
+    };
     const o = raw.orchestrator;
     if (o && typeof o === "object") {
         if (typeof o.llm_steer_next_phase === "boolean") {
-            merged.orchestrator.llm_steer_next_phase = o.llm_steer_next_phase;
+            out.orchestrator.llm_steer_next_phase = o.llm_steer_next_phase;
         }
     }
-    return merged;
+    const l = raw.library;
+    if (l && typeof l === "object") {
+        if (typeof l.path === "string" && l.path.trim() !== "") {
+            out.library.path = resolve(expandTilde(l.path.trim()));
+        }
+        if (typeof l.namespace === "string" && l.namespace.trim() !== "") {
+            out.library.namespace = l.namespace.trim();
+        }
+        if (typeof l.publish_confirm === "boolean") {
+            out.library.publish_confirm = l.publish_confirm;
+        }
+    }
+    return out;
 }
 function cloneDefault() {
     return {
         orchestrator: { ...DEFAULT_CONFIG.orchestrator },
+        library: { ...DEFAULT_CONFIG.library },
     };
 }

package/dist/core/pipeline.js

@@ -38,10 +38,22 @@ export function getNextEligiblePhase(state) {
 }
 export function resolvePhase(state, phaseId) {
     const trimmed = phaseId?.trim();
-    if (trimmed) {
-        return getPhaseMap(state.pipeline).get(trimmed) ?? null;
+    if (!trimmed)
+        return getNextEligiblePhase(state);
+    const exact = getPhaseMap(state.pipeline).get(trimmed);
+    if (exact)
+        return exact;
+    // Fall back to matching the primary_output filename. Validation errors
+    // surface that path (e.g. "Missing primary output: .codecarto/findings/
+    // protocols/protocols-and-state.md"), so users naturally paste it back as
+    // the phase argument. Accept the basename with or without the .md suffix.
+    const wanted = basename(trimmed, ".md");
+    for (const phase of state.pipeline.phases) {
+        if (phase.primary_output && basename(phase.primary_output, ".md") === wanted) {
+            return phase;
+        }
     }
-    return getNextEligiblePhase(state);
+    return null;
 }
 export function resolvePipelineChoice(input) {
     const trimmed = input.trim();

package/dist/core/prompts.d.ts

@@ -1,7 +1,18 @@
 import type { CarryForwardEntry, OpenQuestionEntry, PipelinePhase, ValidationResult, WorkspaceState } from "./types.ts";
 export declare function describeEntry(entry: OpenQuestionEntry | CarryForwardEntry): string;
 export declare function collectRoutedCarryForward(state: WorkspaceState, targetPhaseId: string): CarryForwardEntry[];
-export declare function buildPhasePrompt(state: WorkspaceState, phase: PipelinePhase, forced: boolean): Promise<string>;
+export interface BuildPhasePromptOptions {
+    /**
+     * Set when the phase is being run inside `/codecarto-next --auto` (or any
+     * other non-interactive driver). Suppresses interactive hooks that would
+     * otherwise pause the sub-agent to ask the user a question — those hooks
+     * are the dominant cause of the auto loop wedging at `reimplementation-spec`
+     * with a `MISSING` primary output. Each suppressed hook documents the
+     * default it falls back to.
+     */
+    auto?: boolean;
+}
+export declare function buildPhasePrompt(state: WorkspaceState, phase: PipelinePhase, forced: boolean, options?: BuildPhasePromptOptions): Promise<string>;
 export declare function closeoutFileName(date: string, phaseOrModule: string): string;
 export declare function buildThreadLogEntry(phaseOrModule: string, validation: ValidationResult, timestamp: string): string;
 export declare function ensureCloseoutStub(workspaceDir: string, phaseOrModule: string, timestamp: string): Promise<string | null>;

package/dist/core/prompts.js

@@ -26,7 +26,7 @@ export function collectRoutedCarryForward(state, targetPhaseId) {
     }
     return routed;
 }
-export async function buildPhasePrompt(state, phase, forced) {
+export async function buildPhasePrompt(state, phase, forced, options = {}) {
     const lines = [
         `Read .codecarto/GUIDE.md and continue the CodeCartographer workflow for the phase \`${phase.id}\`.`,
         `Work on this phase only. The analyzed source code is the repository outside .codecarto/.`,
@@ -66,11 +66,20 @@ export async function buildPhasePrompt(state, phase, forced) {
     }
     if (phase.id === "reimplementation-spec") {
         lines.push("");
-        lines.push("Strategic Alignment Hook (run BEFORE producing the spec):");
-        lines.push("- Confirm with the user whether this spec should be language-agnostic or opinionated:");
-        lines.push("    - language-agnostic → use templates/reimplementation-spec.md (default).");
-        lines.push("    - opinionated (target stack locked) → use templates/reimplementation-spec-opinionated.md.");
-        lines.push("- Record the chosen variant in the spec front-matter and in your validation block.");
+        if (options.auto) {
+            lines.push("Strategic Alignment Hook (auto run — DO NOT ask the user):");
+            lines.push("- This phase is running inside `/codecarto-next --auto`. The user is not in the loop.");
+            lines.push("- Default the spec to LANGUAGE-AGNOSTIC: use templates/reimplementation-spec.md.");
+            lines.push("- Record `variant: language-agnostic` and `selection: auto-default` in the spec front-matter and in your validation block, so a later opinionated re-run is traceable.");
+            lines.push("- Do NOT block on the user. If you would otherwise pause to ask about target stack, project name, or scope cuts, instead produce the language-agnostic spec and capture each unresolved choice as an `open_questions` entry (`kind: needs-maintainer-decision`) for follow-up.");
+        }
+        else {
+            lines.push("Strategic Alignment Hook (run BEFORE producing the spec):");
+            lines.push("- Confirm with the user whether this spec should be language-agnostic or opinionated:");
+            lines.push("    - language-agnostic → use templates/reimplementation-spec.md (default).");
+            lines.push("    - opinionated (target stack locked) → use templates/reimplementation-spec-opinionated.md.");
+            lines.push("- Record the chosen variant in the spec front-matter and in your validation block.");
+        }
     }
     lines.push("", "Rules:");
     lines.push("- Do not modify source files outside .codecarto/.");

package/dist/core/usage.js

@@ -90,5 +90,19 @@ function isUsageRun(x) {
     const r = x;
     return (typeof r.timestamp === "string" &&
         typeof r.phase === "string" &&
-        typeof r.status === "string");
+        (r.status === "completed" || r.status === "aborted" || r.status === "error") &&
+        isFiniteNumber(r.turn_count) &&
+        isFiniteNumber(r.tool_uses) &&
+        isFiniteNumber(r.duration_ms) &&
+        isUsageTokens(r.tokens) &&
+        (r.session_file === undefined || typeof r.session_file === "string"));
+}
+function isUsageTokens(x) {
+    if (!x || typeof x !== "object")
+        return false;
+    const t = x;
+    return isFiniteNumber(t.input) && isFiniteNumber(t.output) && isFiniteNumber(t.cache_write);
+}
+function isFiniteNumber(x) {
+    return typeof x === "number" && Number.isFinite(x);
 }

package/dist/core/utils.d.ts

@@ -6,6 +6,14 @@ export declare function isWithinPath(path: string, root: string): boolean;
 export declare function isPlainObject(value: unknown): value is Record<string, unknown>;
 export declare function uniqueStrings(items: string[]): string[];
 export declare function dateOnly(timestamp: string): string;
+/**
+ * Expand a leading `~` or `~/` to the user's home directory. Node's `path`
+ * module deliberately doesn't do this (it's a shell convention, not a path
+ * primitive), so callers that accept user-typed paths (config files,
+ * `library.path`) need to expand explicitly before passing to `resolve`.
+ * Paths without a leading tilde are returned unchanged.
+ */
+export declare function expandTilde(path: string): string;
 /**
  * Format an integer as `2.50M` / `2.3k` / `500`. Used by the HTML dashboard
  * for compact numeric cells. The widget and notify paths have their own

package/dist/core/utils.js

@@ -2,7 +2,8 @@
 // path-boundary enforcement (Pi tool interception, MCP cwd validation).
 import { access } from "node:fs/promises";
 import { constants } from "node:fs";
-import { normalize, resolve } from "node:path";
+import { homedir } from "node:os";
+import { join, normalize, resolve } from "node:path";
 import { realpath } from "node:fs/promises";
 export function sleep(ms) {
     return new Promise((resolvePromise) => setTimeout(resolvePromise, ms));
@@ -44,6 +45,21 @@ export function uniqueStrings(items) {
 export function dateOnly(timestamp) {
     return timestamp.slice(0, 10);
 }
+/**
+ * Expand a leading `~` or `~/` to the user's home directory. Node's `path`
+ * module deliberately doesn't do this (it's a shell convention, not a path
+ * primitive), so callers that accept user-typed paths (config files,
+ * `library.path`) need to expand explicitly before passing to `resolve`.
+ * Paths without a leading tilde are returned unchanged.
+ */
+export function expandTilde(path) {
+    if (path === "~")
+        return homedir();
+    if (path.startsWith("~/") || path.startsWith("~\\")) {
+        return join(homedir(), path.slice(2));
+    }
+    return path;
+}
 /**
  * Format an integer as `2.50M` / `2.3k` / `500`. Used by the HTML dashboard
  * for compact numeric cells. The widget and notify paths have their own

package/dist/extensions/codecarto/auto-runner.d.ts

@@ -4,6 +4,14 @@ import { type PipelinePhase, type ValidationOverall, type ValidationResult, type
 export interface RunSinglePhaseOptions {
     llmSteerEnabled: boolean;
     signal?: AbortSignal;
+    /**
+     * True when this phase is being driven by `/codecarto-next --auto`. The flag
+     * propagates into `buildPhasePrompt` so interactive hooks (notably the
+     * `reimplementation-spec` Strategic Alignment Hook) suppress their user-
+     * facing question and fall back to a documented default. The one-shot
+     * `/codecarto-next` path leaves this unset and the prompt is unchanged.
+     */
+    auto?: boolean;
 }
 export interface SinglePhaseResult {
     status: "completed" | "aborted" | "error";
@@ -38,6 +46,14 @@ export interface AutoRunOptions {
     strict: boolean;
     llmSteerOverride?: boolean;
     signal?: AbortSignal;
+    /**
+     * Fired after each phase is auto-completed and `state` has advanced to the
+     * next eligible phase. Lets the caller refresh UI that reflects pipeline
+     * progress (the status widget, session name) mid-run instead of only after
+     * the whole loop returns — otherwise the readout stays frozen at the
+     * initial phase/progress until the auto run finishes.
+     */
+    onPhaseAdvanced?: (state: WorkspaceState) => void;
 }
 export interface AutoRunResult {
     outcome: AutoOutcome;

package/dist/extensions/codecarto/auto-runner.js

@@ -29,7 +29,7 @@ import { appendUsageRun, buildPhasePrompt, buildThreadLogEntry, buildValidationS
  * getPhaseActivity) and attached the agents widget if it wanted live progress.
  */
 export async function runSinglePhase(ctx, pi, state, phase, options) {
-    let prompt = await buildPhasePrompt(state, phase, false);
+    let prompt = await buildPhasePrompt(state, phase, false, { auto: options.auto === true });
     if (options.llmSteerEnabled) {
         if (ctx.hasUI)
             ctx.ui.notify(`Customizing ${phase.id} prompt via LLM rewriter…`, "info");
@@ -87,10 +87,11 @@ export async function runSinglePhase(ctx, pi, state, phase, options) {
                 tokens: activity.lifetimeUsage,
                 durationMs: (activity.completedAt ?? Date.now()) - activity.startedAt,
                 responseText: result.responseText,
+                sessionFile: result.sessionFile,
             }),
             display: true,
         });
-        void recordUsage(state.workspaceDir, phase.id, status, activity);
+        void recordUsage(state.workspaceDir, phase.id, status, activity, result.sessionFile);
         void writeDashboard(ctx.cwd, PACKAGE_VERSION);
         return {
             status: result.aborted ? "aborted" : "completed",
@@ -264,6 +265,7 @@ export async function runAuto(ctx, pi, initialState, options) {
         const phaseResult = await runSinglePhase(ctx, pi, state, phase, {
             llmSteerEnabled,
             signal: options.signal,
+            auto: true,
         });
         // Accumulate tokens whether the phase succeeded, was aborted, or errored.
         totalTokens.input += phaseResult.activity.lifetimeUsage.input;
@@ -300,6 +302,7 @@ export async function runAuto(ctx, pi, initialState, options) {
             const { updatedState } = await autoCompletePhase(ctx, validation);
             state = updatedState;
             phasesRun.push(phase.id);
+            options.onPhaseAdvanced?.(state);
         }
         catch (err) {
             const message = err instanceof Error ? err.message : String(err);
@@ -377,7 +380,7 @@ function recoveryHint(result) {
 // ----------------------------------------------------------------------------
 // Helpers
 // ----------------------------------------------------------------------------
-async function recordUsage(workspaceDir, phaseId, status, activity) {
+async function recordUsage(workspaceDir, phaseId, status, activity, sessionFile) {
     try {
         await appendUsageRun(workspaceDir, {
             timestamp: new Date().toISOString(),
@@ -391,6 +394,7 @@ async function recordUsage(workspaceDir, phaseId, status, activity) {
                 output: activity.lifetimeUsage.output,
                 cache_write: activity.lifetimeUsage.cacheWrite,
             },
+            ...(sessionFile ? { session_file: sessionFile } : {}),
         });
     }
     catch {

package/dist/extensions/codecarto/dashboard-writer.js

@@ -56,10 +56,35 @@ async function listCloseouts(workspaceDir) {
         const m = CLOSEOUT_FILENAME_RE.exec(name);
         if (!m)
             continue;
-        out.push({ date: m[1], phaseOrModule: m[2], fileName: name });
+        out.push({ date: m[1], phaseOrModule: m[2], fileName: name, summary: await readCloseoutSummary(join(dir, name)) });
     }
     return out;
 }
+async function readCloseoutSummary(path) {
+    try {
+        const raw = await readFile(path, "utf8");
+        const lines = raw.split(/\r?\n/);
+        const summaryStart = lines.findIndex((line) => /^##\s+Summary\s*$/i.test(line.trim()));
+        if (summaryStart === -1)
+            return undefined;
+        const body = [];
+        for (const line of lines.slice(summaryStart + 1)) {
+            if (/^##\s+/.test(line.trim()))
+                break;
+            const trimmed = line.trim();
+            if (!trimmed || trimmed === "-")
+                continue;
+            body.push(trimmed.replace(/^[-*]\s+/, ""));
+            if (body.join(" ").length > 280)
+                break;
+        }
+        const summary = body.join(" ").trim();
+        return summary ? `${summary.slice(0, 280)}${summary.length > 280 ? "…" : ""}` : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
 async function buildOutputsPresent(workspaceDir, pipeline) {
     const out = new Map();
     for (const phaseId of pipeline.phase_order) {

package/dist/extensions/codecarto/index.js

@@ -227,6 +227,15 @@ export default function codeCartographerExtension(pi) {
                     strict: flags.strict,
                     llmSteerOverride: flags.llmSteerOverride,
                     signal: ctx.signal,
+                    onPhaseAdvanced: (advancedState) => {
+                        // Refresh the status widget + session name between phases so
+                        // the readout tracks progress live instead of staying frozen
+                        // at the initial phase until the whole auto run finishes.
+                        setUiState(ctx, advancedState, [`Auto pipeline${flags.strict ? " (strict)" : ""} running…`]);
+                        const phaseId = getNextEligiblePhase(advancedState)?.id ?? advancedState.status.current_phase;
+                        if (phaseId)
+                            pi.setSessionName(`CodeCartographer: ${phaseId}`);
+                    },
                 });
                 const availableSkills = await listSkillNames(state.workspaceDir).catch(() => []);
                 pi.sendMessage({
@@ -302,7 +311,13 @@ export default function codeCartographerExtension(pi) {
             const state = await ensureWorkspaceState(ctx);
             if (!state)
                 return;
-            const validation = await validatePhaseOutput(state, args.trim() || undefined);
+            const validation = await validatePhaseOutput(state, args.trim() || undefined).catch((error) => error instanceof Error ? error : new Error(String(error)));
+            if (validation instanceof Error) {
+                lastFeedbackLines = [validation.message];
+                setUiState(ctx, state, lastFeedbackLines);
+                ctx.ui.notify(validation.message, "error");
+                return;
+            }
             lastFeedbackLines = buildValidationSummary(validation);
             setUiState(ctx, state, lastFeedbackLines);
             const level = validation.overall === "FAIL" || validation.overall === "MISSING" ? "error" : validation.overall === "PASS WITH GAPS" ? "warning" : "info";
@@ -315,7 +330,13 @@ export default function codeCartographerExtension(pi) {
             const currentState = await ensureWorkspaceState(ctx);
             if (!currentState)
                 return;
-            const validation = await validatePhaseOutput(currentState, args.trim() || undefined);
+            const validation = await validatePhaseOutput(currentState, args.trim() || undefined).catch((error) => error instanceof Error ? error : new Error(String(error)));
+            if (validation instanceof Error) {
+                lastFeedbackLines = [validation.message];
+                setUiState(ctx, currentState, lastFeedbackLines);
+                ctx.ui.notify(validation.message, "error");
+                return;
+            }
             if (validation.overall === "FAIL" || validation.overall === "MISSING") {
                 lastFeedbackLines = buildValidationSummary(validation);
                 setUiState(ctx, currentState, lastFeedbackLines);

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

@@ -68,6 +68,27 @@ export declare function handleSkill(args: {
     }>;
     structuredContent?: Record<string, unknown>;
 }>;
+export declare function handlePublish(args: Record<string, unknown>): Promise<{
+    content: Array<{
+        type: "text";
+        text: string;
+    }>;
+    structuredContent?: Record<string, unknown>;
+}>;
+export declare function handleLibraryList(args: Record<string, unknown>): Promise<{
+    content: Array<{
+        type: "text";
+        text: string;
+    }>;
+    structuredContent?: Record<string, unknown>;
+}>;
+export declare function handleLibraryReindex(args: Record<string, unknown>): Promise<{
+    content: Array<{
+        type: "text";
+        text: string;
+    }>;
+    structuredContent?: Record<string, unknown>;
+}>;
 export declare function buildServer(): Server<{
     method: string;
     params?: {