codecartographer-pi 0.15.0 → 0.17.0

package/dist/extensions/codecarto/broadside-flags.js

@@ -0,0 +1,116 @@
+// Argument parser for /codecarto-broadside. The grammar is one optional
+// action followed by lens names and flags, in any order:
+//
+//   /codecarto-broadside                              → submit, default lenses
+//   /codecarto-broadside submit architecture security → submit, two lenses
+//   /codecarto-broadside collect --wait=900
+//   /codecarto-broadside status
+//   /codecarto-broadside models --benchmarks
+//
+// Flags mirror the codecarto_broadside tool parameters, with the negative
+// forms spelled out because a slash command has no place to pass `false`:
+//   --incremental          --no-synthesis
+//   --max-cost=N           --no-triage
+//   --wait=SECONDS         --no-retry-truncated
+//   --benchmarks (models only)
+//
+// The parser never throws. index.ts decides how to surface unknown tokens and
+// invalid combinations, matching parseNextFlags.
+import { BROADSIDE_LENS_IDS } from "../../core/index.js";
+const ACTIONS = new Set(["submit", "collect", "status", "models"]);
+/** Every token the completer offers, in the order it offers them. */
+export const KNOWN_BROADSIDE_TOKENS = [
+    "submit",
+    "collect",
+    "status",
+    "models",
+    ...BROADSIDE_LENS_IDS,
+    "--incremental",
+    "--max-cost=",
+    "--wait=",
+    "--no-synthesis",
+    "--no-triage",
+    "--no-retry-truncated",
+    "--benchmarks",
+];
+// A numeric flag with a missing or unparseable value is an error, not a
+// silent fallback to the config default: "--max-cost=" almost certainly means
+// the user meant to cap the spend and mistyped it.
+function parseNumeric(token, name, result) {
+    const raw = token.slice(name.length + 1);
+    const value = Number(raw);
+    if (!raw || !Number.isFinite(value) || value < 0) {
+        result.error = `${name} needs a non-negative number (got "${raw}").`;
+        return undefined;
+    }
+    return value;
+}
+export function parseBroadsideFlags(args) {
+    const tokens = args.trim().split(/\s+/).filter((token) => token.length > 0);
+    const result = {
+        action: "submit",
+        lenses: [],
+        incremental: false,
+        benchmarks: false,
+        unknown: [],
+    };
+    let actionSeen = false;
+    for (const token of tokens) {
+        if (!actionSeen && ACTIONS.has(token)) {
+            result.action = token;
+            actionSeen = true;
+            continue;
+        }
+        if (BROADSIDE_LENS_IDS.includes(token)) {
+            // A lens named twice is one lens, not two batches of it.
+            if (!result.lenses.includes(token))
+                result.lenses.push(token);
+            continue;
+        }
+        if (token === "--incremental") {
+            result.incremental = true;
+            continue;
+        }
+        if (token === "--no-synthesis") {
+            result.includeSynthesis = false;
+            continue;
+        }
+        if (token === "--no-triage") {
+            result.includeTriage = false;
+            continue;
+        }
+        if (token === "--no-retry-truncated") {
+            result.retryTruncated = false;
+            continue;
+        }
+        if (token === "--benchmarks") {
+            result.benchmarks = true;
+            continue;
+        }
+        if (token.startsWith("--max-cost=")) {
+            result.maxCost = parseNumeric(token, "--max-cost", result);
+            continue;
+        }
+        if (token.startsWith("--wait=")) {
+            result.waitSeconds = parseNumeric(token, "--wait", result);
+            continue;
+        }
+        result.unknown.push(token);
+    }
+    // Flags that only mean something for one action are refused rather than
+    // ignored: silently dropping --incremental on a collect would read as
+    // "collected incrementally", which is not a thing.
+    if (result.lenses.length > 0 && result.action !== "submit") {
+        result.error ??= `Lens names are only meaningful for submit (got action "${result.action}").`;
+    }
+    if (result.incremental && result.action !== "submit") {
+        result.error ??= `--incremental is only meaningful for submit (got action "${result.action}").`;
+    }
+    if (result.benchmarks && result.action !== "models") {
+        result.error ??= `--benchmarks is only meaningful for models (got action "${result.action}").`;
+    }
+    if (result.action === "status" && result.waitSeconds !== undefined) {
+        result.error ??= "--wait is only meaningful for submit and collect; status reads recorded state.";
+    }
+    return result;
+}

package/dist/extensions/codecarto/dashboard-writer.d.ts

@@ -1 +1,8 @@
-export declare function writeDashboard(cwd: string, packageVersion: string): Promise<void>;
+/**
+ * Render and atomically replace `.codecarto/dashboard.html`.
+ * @returns true when a fresh dashboard landed on disk; false when the
+ * workspace is missing or any gather/render/write step failed (swallowed —
+ * lifecycle callers must never fail on a dashboard problem, but they may
+ * report truthfully whether a refresh happened).
+ */
+export declare function writeDashboard(cwd: string, packageVersion: string): Promise<boolean>;

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

@@ -6,11 +6,18 @@ import { readdir, readFile, rename, writeFile } from "node:fs/promises";
 import { join } from "node:path";
 import { DASHBOARD_RELATIVE_PATH, getWorkspaceState, loadUsage, NARRATION_CACHE_RELATIVE_PATH, parseSimpleYaml, pathExists, renderDashboard, } from "../../core/index.js";
 const CLOSEOUT_FILENAME_RE = /^(\d{4}-\d{2}-\d{2})-(.+)\.md$/;
+/**
+ * Render and atomically replace `.codecarto/dashboard.html`.
+ * @returns true when a fresh dashboard landed on disk; false when the
+ * workspace is missing or any gather/render/write step failed (swallowed —
+ * lifecycle callers must never fail on a dashboard problem, but they may
+ * report truthfully whether a refresh happened).
+ */
 export async function writeDashboard(cwd, packageVersion) {
     try {
         const state = await getWorkspaceState(cwd);
         if (!state)
-            return;
+            return false;
         const workspaceDir = state.workspaceDir;
         const [usage, closeouts, outputsPresent, narration] = await Promise.all([
             loadUsage(workspaceDir),
@@ -33,11 +40,13 @@ export async function writeDashboard(cwd, packageVersion) {
         const tempPath = `${path}.${process.pid}.${Date.now()}.tmp`;
         await writeFile(tempPath, html, "utf8");
         await rename(tempPath, path);
+        return true;
     }
     catch {
         // Best-effort: a failed dashboard write must not surface as a phase
         // error. The user's pipeline state is unaffected; the next state
         // change will trigger another render attempt.
+        return false;
     }
 }
 async function listCloseouts(workspaceDir) {

package/dist/extensions/codecarto/index.js

@@ -1,4 +1,4 @@
-import { cp, mkdir, readFile, rename, writeFile } from "node:fs/promises";
+import { mkdir, readFile, rename, writeFile } from "node:fs/promises";
 import { homedir } from "node:os";
 import { basename, join, resolve } from "node:path";
 import { autoCompletePhase, buildAutoSummary, isPhaseRunning, runAuto, runSinglePhase } from "./auto-runner.js";
@@ -6,12 +6,16 @@ import { disposeAgentsWidget } from "./agent-widget.js";
 import { parseDashboardFlags } from "./dashboard-flags.js";
 import { narrateDashboard } from "./dashboard-narrator.js";
 import { writeDashboard } from "./dashboard-writer.js";
+import { parseBroadsideFlags, KNOWN_BROADSIDE_TOKENS } from "./broadside-flags.js";
 import { parseNextFlags } from "./next-flags.js";
 import { phaseCompactionExtension } from "./phase-compaction.js";
-import { buildPhasePrompt, buildSkillPrompt, buildValidationSummary, canonicalPath, computePerPhaseTotals, computeTotals, createEmptyStatus, DEFAULT_PIPELINE_PATH, describeScaffoldStaleness, deriveSlug, discoverLibrary, getNextEligiblePhase, getPipelineLabel, getWorkspaceState, isWithinPathResolved, listSkillNames, loadCodecartoConfig, loadUsage, loadYamlFile, normalizeForComparison, packagedWorkspaceDir, pathExists, PACKAGE_VERSION, PhasePreflightError, PIPELINE_ALIASES, publishEntry, resolvePhase, resolvePipelineChoice, runPhasePreflight, seedOrchestratorFiles, stringifySimpleYaml, switchPipeline, validatePhaseOutput, writeLibraryConfig, } from "../../core/index.js";
+import { buildPhasePrompt, buildSkillPrompt, buildValidationSummary, canonicalPath, copyPackagedWorkspace, computePerPhaseTotals, computeTotals, createEmptyStatus, DEFAULT_PIPELINE_PATH, describeScaffoldStaleness, deriveSlug, discoverLibrary, getNextEligiblePhase, getPipelineLabel, getWorkspaceState, isWithinPathResolved, BROADSIDE_LENS_IDS, BROADSIDE_SKILL_NAME, BroadsideCancelledError, broadsideDirFor, collectResultText, estimateSubmitText, getLens, listBatchModels, listSkillNames, loadBroadsideConfig, modelsText, runBroadsideCollect, runBroadsideStatus, runBroadsideSubmit, statusText, loadCodecartoConfig, loadUsage, loadYamlFile, normalizeForComparison, packagedWorkspaceDir, pathExists, PACKAGE_VERSION, readBroadsideSkill, PhasePreflightError, PIPELINE_ALIASES, publishEntry, resolvePhase, resolvePipelineChoice, runPhasePreflight, seedOrchestratorFiles, stringifySimpleYaml, switchPipeline, validatePhaseOutput, writeLibraryConfig, } from "../../core/index.js";
 import { initLibrary } from "../../core/library.js";
 import { resolveUserConfigPath } from "../../core/orchestrator-config.js";
 const STATUS_WIDGET_ID = "codecarto-widget";
+// Broad-Side gets its own widget id: a scout run is legal on a repository with
+// no workspace, where the phase widget has nothing to render.
+const BROADSIDE_WIDGET_ID = "codecarto-broadside";
 const STATUS_LINE_ID = "codecarto-status";
 const SAFE_TOOL_NAMES = ["read", "grep", "find", "ls", "edit", "write"];
 function derivePublishHeadline(spec, cwd) {
@@ -92,6 +96,47 @@ function setUiState(ctx, state, extraLines = []) {
     ctx.ui.setStatus(STATUS_LINE_ID, `${theme.fg("accent", "CC")} ${theme.fg("dim", currentPhase)}`);
     ctx.ui.setWidget(STATUS_WIDGET_ID, buildStatusLines(state, extraLines));
 }
+/**
+ * Resolve the OpenRouter key for a Broad-Side run. Deliberately no slash-command
+ * parameter: a key typed as a command argument lands in the session transcript.
+ */
+function resolveBroadsideKey(configuredKey) {
+    const fromEnv = process.env.OPENROUTER_API_KEY?.trim();
+    if (fromEnv)
+        return fromEnv;
+    return configuredKey.trim() || null;
+}
+/** The spend decision, rendered for a human about to approve it. */
+function describeBroadsideEstimate(estimate) {
+    const lines = [
+        `Model: ${estimate.model}${estimate.mixedModels ? " (some lenses overridden — see below)" : ""} (pricing: ${estimate.pricing.source})`,
+        `Rates: $${estimate.pricing.inputPerM.toFixed(4)}/M in · $${estimate.pricing.outputPerM.toFixed(4)}/M out`,
+        "",
+        "Per lens:",
+        ...estimate.lenses.map(({ name, slices, cost, model }) => {
+            // Naming the model only when it differs keeps the common case quiet
+            // and makes a mixed-model run impossible to approve without noticing.
+            const override = estimate.mixedModels && model !== estimate.model ? ` on ${model}` : "";
+            return `  ${name}: ${slices} slice${slices === 1 ? "" : "s"} — ~$${cost.toFixed(4)}${override}`;
+        }),
+        "",
+        `Estimated total: ~$${estimate.totalCost.toFixed(4)} ` +
+            `(~${Math.round(estimate.inputTokens / 1000)}k in, ~${Math.round(estimate.outputTokens / 1000)}k out)`,
+    ];
+    if (estimate.maxCost > 0) {
+        lines.push(estimate.exceedsLimit
+            ? `This EXCEEDS the configured max_cost of $${estimate.maxCost.toFixed(2)}. Approving here overrides it for this run.`
+            : `Within the configured max_cost of $${estimate.maxCost.toFixed(2)}.`);
+    }
+    if (estimate.baseHead) {
+        lines.push(`Incremental: only modules changed since ${estimate.baseHead.slice(0, 8)} are included.`);
+    }
+    else if (estimate.sourceDirty) {
+        lines.push("Incremental was requested but the tree is dirty — this is a full scan.");
+    }
+    lines.push("", "The estimate is a pre-flight prediction from file sizes; OpenRouter bills actual usage.");
+    return lines.join("\n");
+}
 export default function codeCartographerExtension(pi) {
     phaseCompactionExtension(pi);
     let lastFeedbackLines = [];
@@ -268,7 +313,7 @@ export default function codeCartographerExtension(pi) {
             }
             if (!(await pathExists(targetWorkspaceDir))) {
                 await mkdir(ctx.cwd, { recursive: true });
-                await cp(sourceWorkspaceDir, targetWorkspaceDir, { recursive: true });
+                await copyPackagedWorkspace(targetWorkspaceDir);
             }
             const rawStatusPath = join(targetWorkspaceDir, "workflow", "status.yaml");
             const rawStatus = (await loadYamlFile(rawStatusPath)) ?? {};
@@ -597,6 +642,30 @@ export default function codeCartographerExtension(pi) {
                 ctx.ui.notify(`Usage: /codecarto-skill <name>${hint}`, "warning");
                 return;
             }
+            // Broad-Side is a reading guide for batch reconnaissance output, not a
+            // post-pipeline skill: it is read before or during the pipeline and works
+            // on a repository with scout state and no workspace. Same exemption the
+            // MCP surface makes in handleSkill.
+            if (skillName === BROADSIDE_SKILL_NAME) {
+                const skill = await readBroadsideSkill(ctx.cwd).catch(() => null);
+                if (!skill) {
+                    ctx.ui.notify("Broad-Side reading guide not found. Reinstall codecartographer-pi.", "error");
+                    return;
+                }
+                const message = [
+                    "Read the Broad-Side reading guide below and apply it to the batch reconnaissance results in .codecarto/broadside/.",
+                    "",
+                    skill.content,
+                ].join("\n");
+                if (ctx.isIdle()) {
+                    pi.sendUserMessage(message);
+                }
+                else {
+                    pi.sendUserMessage(message, { deliverAs: "followUp" });
+                }
+                ctx.ui.notify("Queued the Broad-Side reading guide", "info");
+                return;
+            }
             const state = await ensureWorkspaceState(ctx);
             if (!state)
                 return;
@@ -609,7 +678,7 @@ export default function codeCartographerExtension(pi) {
             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");
+                ctx.ui.notify(`Unknown skill: ${skillName}${hint}. The Broad-Side reading guide is served as \`${BROADSIDE_SKILL_NAME}\` and is not pipeline-gated.`, "error");
                 return;
             }
             const prompt = await buildSkillPrompt(state, skillName);
@@ -624,6 +693,165 @@ export default function codeCartographerExtension(pi) {
             ctx.ui.notify(`Queued CodeCartographer skill: ${skillName}`, "info");
         },
     });
+    pi.registerCommand("codecarto-broadside", {
+        description: "Batch reconnaissance (Broad-Side): /codecarto-broadside [submit|collect|status|models] [lenses…] [flags]",
+        getArgumentCompletions: (prefix) => {
+            const items = KNOWN_BROADSIDE_TOKENS
+                .filter((value) => value.startsWith(prefix))
+                .map((value) => ({ value, label: value }));
+            return items.length > 0 ? items : null;
+        },
+        handler: async (args, ctx) => {
+            const flags = parseBroadsideFlags(args);
+            if (flags.unknown.length > 0) {
+                ctx.ui.notify(`Unknown /codecarto-broadside argument: ${flags.unknown.join(" ")}. ` +
+                    `Actions: submit, collect, status, models. Lenses: ${BROADSIDE_LENS_IDS.join(", ")}.`, "error");
+                return;
+            }
+            if (flags.error) {
+                ctx.ui.notify(flags.error, "error");
+                return;
+            }
+            // Broad-Side runs on any git repository, with or without a workspace —
+            // so this command never goes through ensureWorkspaceState.
+            const broadsideDir = broadsideDirFor(ctx.cwd);
+            const config = await loadBroadsideConfig(broadsideDir);
+            const finish = (lines, notice, level = "info") => {
+                lastFeedbackLines = lines;
+                if (codecartoModeActive) {
+                    // A workspace session already has a widget; fold the result into it.
+                    if (ctx.hasUI)
+                        ctx.ui.setWidget(BROADSIDE_WIDGET_ID, undefined);
+                    void refreshWorkspaceUi(ctx, lines);
+                }
+                else if (ctx.hasUI) {
+                    // Scout-only repository: the Broad-Side widget is the only place
+                    // the result can live, so it holds it instead of being cleared.
+                    ctx.ui.setWidget(BROADSIDE_WIDGET_ID, ["Broad-Side", ...lines]);
+                }
+                ctx.ui.notify(notice, level);
+            };
+            if (flags.action === "status") {
+                const { state } = await runBroadsideStatus(ctx.cwd);
+                const runs = state.runs.length;
+                finish(statusText(state).split("\n"), runs > 0 ? `Broad-Side: ${runs} recorded run${runs === 1 ? "" : "s"}` : "Broad-Side: no runs recorded yet");
+                return;
+            }
+            const apiKey = resolveBroadsideKey(config.apiKey);
+            if (!apiKey) {
+                ctx.ui.notify("No OpenRouter API key. Set OPENROUTER_API_KEY in the environment, or add api_key to " +
+                    ".codecarto/broadside/config.yaml. (A slash command takes no key: it would land in the transcript.)", "error");
+                return;
+            }
+            if (flags.action === "models") {
+                ctx.ui.notify("Fetching the OpenRouter batch-model catalog…", "info");
+                try {
+                    const { entries, benchmarks } = await listBatchModels(broadsideDir, config, apiKey, {
+                        includeBenchmarks: flags.benchmarks,
+                    });
+                    finish(modelsText(entries, { benchmarks, defaultModel: config.model }).split("\n"), `Broad-Side: ${entries.length} batch model${entries.length === 1 ? "" : "s"} listed`);
+                }
+                catch (error) {
+                    ctx.ui.notify(`Model catalog lookup failed: ${error instanceof Error ? error.message : String(error)}`, "error");
+                }
+                return;
+            }
+            // Live per-lens progress. Poll callbacks fire often, so they render
+            // into a widget rather than a notification stream.
+            const progress = new Map();
+            const renderProgress = (heading) => {
+                if (!ctx.hasUI)
+                    return;
+                ctx.ui.setWidget(BROADSIDE_WIDGET_ID, [
+                    "Broad-Side",
+                    heading,
+                    ...[...progress.entries()].map(([lensId, line]) => `  ${lensId}: ${line}`),
+                ]);
+            };
+            const onStatus = (lensId, status, counts) => {
+                progress.set(lensId, `${status} (${counts.completed ?? 0}/${counts.total ?? "?"})`);
+                renderProgress("Polling batches…");
+            };
+            const waitSeconds = flags.waitSeconds ?? config.waitSeconds;
+            const waitMs = waitSeconds > 0 ? waitSeconds * 1000 : undefined;
+            const includeSynthesis = flags.includeSynthesis ?? config.includeSynthesis;
+            const includeTriage = flags.includeTriage ?? config.includeTriage;
+            const retryTruncated = flags.retryTruncated ?? config.retryTruncated;
+            if (flags.action === "submit") {
+                const lenses = flags.lenses.length > 0 ? flags.lenses : config.defaultLenses;
+                renderProgress("Slicing the repository and pricing the run…");
+                let submit;
+                try {
+                    submit = await runBroadsideSubmit(ctx.cwd, apiKey, {
+                        lenses,
+                        model: config.model,
+                        maxCost: flags.maxCost ?? config.maxCost,
+                        incremental: flags.incremental || config.incremental,
+                        // Pi can ask, so it asks instead of refusing over max_cost the
+                        // way MCP has to. An approval here IS the force flag.
+                        confirm: (estimate) => ctx.ui.confirm(`Broad-Side will spend about $${estimate.totalCost.toFixed(4)}`, describeBroadsideEstimate(estimate)),
+                    });
+                }
+                catch (error) {
+                    if (ctx.hasUI)
+                        ctx.ui.setWidget(BROADSIDE_WIDGET_ID, undefined);
+                    if (error instanceof BroadsideCancelledError) {
+                        ctx.ui.notify("Broad-Side cancelled. Nothing was submitted.", "info");
+                        return;
+                    }
+                    ctx.ui.notify(`Broad-Side submit failed: ${error instanceof Error ? error.message : String(error)}`, "error");
+                    return;
+                }
+                const lines = estimateSubmitText(submit, lenses.map(getLens)).split("\n");
+                if (!waitMs) {
+                    lines.push("", "Batches are in flight. Run /codecarto-broadside collect when they finish.");
+                    finish(lines, `Broad-Side submitted: run ${submit.runId} (~$${submit.estimatedTotalCost.toFixed(4)})`);
+                    return;
+                }
+                ctx.ui.notify(`Broad-Side submitted run ${submit.runId}; polling for up to ${waitSeconds}s…`, "info");
+                try {
+                    const collect = await runBroadsideCollect(ctx.cwd, apiKey, {
+                        waitMs,
+                        includeSynthesis,
+                        includeTriage,
+                        retryTruncated,
+                        onStatus,
+                    });
+                    finish([...lines, "", ...collectResultText(collect).split("\n")], `Broad-Side ${collect.status}: run ${collect.runId}`);
+                }
+                catch (error) {
+                    if (ctx.hasUI)
+                        ctx.ui.setWidget(BROADSIDE_WIDGET_ID, undefined);
+                    // The batches are submitted and paid for either way — say so, so
+                    // nobody re-submits a run that is already in flight.
+                    ctx.ui.notify(`Broad-Side submitted run ${submit.runId}, but collect failed: ` +
+                        `${error instanceof Error ? error.message : String(error)}. Retry with /codecarto-broadside collect.`, "error");
+                }
+                return;
+            }
+            // action === "collect"
+            renderProgress("Polling batches…");
+            try {
+                const collect = await runBroadsideCollect(ctx.cwd, apiKey, {
+                    waitMs,
+                    includeSynthesis,
+                    includeTriage,
+                    retryTruncated,
+                    onStatus,
+                });
+                const lines = collectResultText(collect).split("\n");
+                const done = collect.status === "completed";
+                if (!done)
+                    lines.push("", "Still in flight. Run /codecarto-broadside collect again to resume.");
+                finish(lines, `Broad-Side ${collect.status}: ${collect.resultCount} result${collect.resultCount === 1 ? "" : "s"} saved`, done ? "info" : "warning");
+            }
+            catch (error) {
+                if (ctx.hasUI)
+                    ctx.ui.setWidget(BROADSIDE_WIDGET_ID, undefined);
+                ctx.ui.notify(`Broad-Side collect failed: ${error instanceof Error ? error.message : String(error)}`, "error");
+            }
+        },
+    });
     pi.registerCommand("codecarto-publish", {
         description: "Publish the completed reimplementation spec to the configured CodeCartographer library",
         handler: async (_args, ctx) => {

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

@@ -230,6 +230,28 @@ export declare function handleAmend(args: {
         text: string;
     };
 }>;
+export declare function handleBroadside(args: {
+    cwd: string;
+    action: "submit" | "collect" | "status" | "models";
+    lenses?: string[];
+    api_key?: string;
+    wait_seconds?: number;
+    include_synthesis?: boolean;
+    include_triage?: boolean;
+    retry_truncated?: boolean;
+    max_cost?: number;
+    force?: boolean;
+    include_benchmarks?: boolean;
+    incremental?: boolean;
+}): Promise<{
+    content: {
+        type: "text";
+        text: string;
+    }[];
+    structuredContent: {
+        text: string;
+    };
+}>;
 export declare function handleGuide(args: {
     topic?: string;
 }): Promise<{