codecartographer-pi 0.6.1 → 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,3 +6,24 @@ 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
+ * formatters that include " tokens" / unit suffixes inline; this helper is
+ * deliberately suffix-free so callers attach units in surrounding markup.
+ */
+export declare function formatTokenCount(count: number): string;
+/**
+ * Format a millisecond duration as `2m30s` / `1.5s` / `500ms`. Matches the
+ * extension widget's `formatDuration` shape; promoted to `core/` so the
+ * dashboard renderer can reuse without crossing the core/extensions boundary.
+ */
+export declare function formatMillis(ms: number): string;

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,3 +45,45 @@ 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
+ * formatters that include " tokens" / unit suffixes inline; this helper is
+ * deliberately suffix-free so callers attach units in surrounding markup.
+ */
+export function formatTokenCount(count) {
+    if (count >= 1_000_000)
+        return `${(count / 1_000_000).toFixed(2)}M`;
+    if (count >= 1_000)
+        return `${(count / 1_000).toFixed(1)}k`;
+    return `${count}`;
+}
+/**
+ * Format a millisecond duration as `2m30s` / `1.5s` / `500ms`. Matches the
+ * extension widget's `formatDuration` shape; promoted to `core/` so the
+ * dashboard renderer can reuse without crossing the core/extensions boundary.
+ */
+export function formatMillis(ms) {
+    if (ms < 1000)
+        return `${ms}ms`;
+    if (ms < 60_000)
+        return `${(ms / 1000).toFixed(1)}s`;
+    const minutes = Math.floor(ms / 60_000);
+    const seconds = Math.floor((ms % 60_000) / 1000);
+    return `${minutes}m${seconds.toString().padStart(2, "0")}s`;
+}

package/dist/core/workspace.d.ts

@@ -1,5 +1,6 @@
 import type { WorkspaceState } from "./types.ts";
 export declare const packagedWorkspaceDir: string;
+export declare const PACKAGE_VERSION: string;
 export declare function getWorkspaceState(cwd: string): Promise<WorkspaceState | null>;
 export declare function updateStatusAtomically(cwd: string, updater: (state: WorkspaceState) => Promise<{
     state: WorkspaceState;

package/dist/core/workspace.js

@@ -2,7 +2,7 @@
 // (so the MCP server and Pi can both copy from it on /codecarto-init), loads
 // + normalizes the per-project workspace state from disk, and provides the
 // atomic status-update primitive used by /codecarto-complete.
-import { existsSync } from "node:fs";
+import { existsSync, readFileSync } from "node:fs";
 import { appendFile, rename, writeFile } from "node:fs/promises";
 import { dirname, join, relative } from "node:path";
 import { fileURLToPath } from "node:url";
@@ -30,6 +30,18 @@ const packageRoot = findPackageRoot(coreDir);
 // Path to the packaged framework template directory. Wrappers copy this on
 // /codecarto-init.
 export const packagedWorkspaceDir = join(packageRoot, ".codecarto");
+// Resolved at module-load time from the same package.json that findPackageRoot
+// located. Used by the HTML dashboard renderer for the footer; cheap to read
+// once since startup is already paying for findPackageRoot.
+export const PACKAGE_VERSION = (() => {
+    try {
+        const pkg = JSON.parse(readFileSync(join(packageRoot, "package.json"), "utf8"));
+        return typeof pkg.version === "string" ? pkg.version : "0.0.0";
+    }
+    catch {
+        return "0.0.0";
+    }
+})();
 export async function getWorkspaceState(cwd) {
     const workspaceDir = join(cwd, ".codecarto");
     const statusPath = join(workspaceDir, "workflow", "status.yaml");

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

@@ -0,0 +1,96 @@
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { type PhaseActivity } from "./agent-state.ts";
+import { type PipelinePhase, type ValidationOverall, type ValidationResult, type WorkspaceState } from "../../core/index.ts";
+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";
+    activity: PhaseActivity;
+    error?: string;
+    responseText?: string;
+}
+/**
+ * Run one phase end to end: optional LLM-steered rewrite, spawn the sub-agent,
+ * wait for it, then emit the side effects the historical /codecarto-next chain
+ * fired (notify, phase-summary sendMessage, recordUsage, writeDashboard). The
+ * .finally linger-timeout for clearPhase fires here so both callers (one-shot
+ * + auto loop) get the same lifecycle.
+ *
+ * Pre-conditions: caller verified the phase isn't already running (via
+ * getPhaseActivity) and attached the agents widget if it wanted live progress.
+ */
+export declare function runSinglePhase(ctx: ExtensionContext, pi: ExtensionAPI, state: WorkspaceState, phase: PipelinePhase, options: RunSinglePhaseOptions): Promise<SinglePhaseResult>;
+/**
+ * Re-entry guard: returns true if the phase is already running from a prior
+ * spawn (manual or auto). Callers (both /codecarto-next paths) should reject
+ * before invoking runSinglePhase.
+ */
+export declare function isPhaseRunning(phaseId: string): boolean;
+export interface AutoCompleteResult {
+    updatedState: WorkspaceState;
+    closeoutNotice?: string;
+}
+export declare function autoCompletePhase(ctx: ExtensionContext, validation: ValidationResult): Promise<AutoCompleteResult>;
+export type AutoOutcome = "complete" | "stopped" | "aborted";
+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;
+    reason: string;
+    phasesRun: string[];
+    totalPhases: number;
+    startedAt: number;
+    endedAt: number;
+    totalTokens: {
+        input: number;
+        output: number;
+        cacheWrite: number;
+    };
+    stoppedAt?: {
+        phaseId: string;
+        validation?: ValidationOverall;
+        error?: string;
+    };
+    validationSummary?: string[];
+}
+/**
+ * Per-iteration decision: given the outcome of a sub-agent run and (if it
+ * completed) its validation result, what should the auto loop do next?
+ * Pure function — no I/O, no module state — so the decision matrix is
+ * unit-testable without mocking the SDK.
+ */
+export type AutoDecision = {
+    action: "continue";
+} | {
+    action: "stop";
+    reason: string;
+    validation?: ValidationOverall;
+    error?: string;
+    validationSummary?: string[];
+} | {
+    action: "aborted";
+};
+export declare function decideAfterPhase(phaseStatus: SinglePhaseResult["status"], phaseError: string | undefined, validation: ValidationResult | null, strict: boolean): AutoDecision;
+export declare function runAuto(ctx: ExtensionContext, pi: ExtensionAPI, initialState: WorkspaceState, options: AutoRunOptions): Promise<AutoRunResult>;
+export declare function buildAutoSummary(result: AutoRunResult, availableSkills?: string[]): string;