codecartographer-pi 0.16.0 → 0.17.1

package/dist/core/workspace.js

@@ -3,11 +3,11 @@
 // + normalizes the per-project workspace state from disk, and provides the
 // atomic status-update primitive used by /codecarto-complete.
 import { existsSync, readFileSync } from "node:fs";
-import { appendFile, copyFile, mkdir, readFile, readdir, rename, writeFile } from "node:fs/promises";
+import { appendFile, copyFile, cp, mkdir, readFile, readdir, rename, writeFile } from "node:fs/promises";
 import { basename, dirname, join, relative } from "node:path";
 import { fileURLToPath } from "node:url";
 import { acquireLock, applyHandoff, createEmptyStatus, normalizeStatus, parseHandoff } from "./status.js";
-import { pathExists } from "./utils.js";
+import { compareDottedVersions, newlineIfUnterminated, pathExists } from "./utils.js";
 import { loadYamlFile, stringifySimpleYaml } from "./yaml.js";
 // Walk up from the current file to find the package root. Needed because the
 // source lives at <root>/core/workspace.ts (one level below the package root)
@@ -102,7 +102,71 @@ export async function getWorkspaceState(cwd) {
 export const ORCHESTRATOR_FILES = [
     { file: "CONVENTIONS.md", template: "conventions-template.md" },
     { file: "DECISIONS.md", template: "decisions-template.md" },
+    { file: "BACKLOG.md", template: "backlog-project.md" },
+    { file: "THREAD_LOG.md", template: "thread-log.md" },
 ];
+/**
+ * Project state that must never travel from the packaged template into a new
+ * workspace.
+ *
+ * This repository's `.codecarto/` is two things at once: the template that gets
+ * copied into a user's repo, and CodeCartographer's own live workspace. The
+ * second role writes real project state into it — a backlog of framework
+ * deferrals, a thread log, closeouts of sessions where CodeCartographer
+ * analyzed itself. Copying the tree wholesale handed every new workspace ~40 KB
+ * of another project's history as its own, and the damage was not only clutter:
+ * GUIDE.md keys first-time-project setup on `closeouts/` being empty, so a
+ * shipped closeout told every new session it was not the first to touch the
+ * project, suppressing the orchestrator role that issues #97/#98 made the
+ * default.
+ *
+ * The four top-level files are seeded fresh from templates instead
+ * ({@link ORCHESTRATOR_FILES}); `closeouts/` is created empty.
+ */
+const INIT_EXCLUDED_TOP_LEVEL = new Set(["BACKLOG.md", "THREAD_LOG.md", "CONVENTIONS.md", "DECISIONS.md"]);
+const INIT_EXCLUDED_DIR_CONTENTS = new Set(["closeouts"]);
+// broadside/ is machine-local scan state (state.json, timestamped run dirs)
+// except for its two template files — the same carve-out .codecarto/.gitignore
+// makes for this repository itself. Without this, init from a local checkout
+// with live scan state handed every new workspace another project's runs.
+// Literal rather than an import from broadside.ts, which imports this module.
+const BROADSIDE_DIR_NAME = "broadside";
+const INIT_BROADSIDE_TEMPLATE_FILES = new Set(["SKILL.md", "config.yaml"]);
+/**
+ * Copy the packaged template into a target workspace, skipping this
+ * repository's own project state. Directories are still created, so a fresh
+ * workspace has an empty `closeouts/` rather than no `closeouts/`.
+ *
+ * @param targetWorkspaceDir - Absolute path to the `.codecarto/` to create or merge into.
+ * @param sourceWorkspaceDir - The template to copy from. Defaults to the packaged
+ *   template; tests pass a synthetic directory so they can prove the state filter
+ *   without mutating the repository's own live workspace mid-suite.
+ */
+export async function copyPackagedWorkspace(targetWorkspaceDir, sourceWorkspaceDir = packagedWorkspaceDir) {
+    await cp(sourceWorkspaceDir, targetWorkspaceDir, {
+        recursive: true,
+        filter: (source) => {
+            const relativePath = relative(sourceWorkspaceDir, source);
+            if (!relativePath)
+                return true; // the workspace root itself
+            const segments = relativePath.split(/[\\/]/);
+            if (segments.length === 1)
+                return !INIT_EXCLUDED_TOP_LEVEL.has(segments[0]);
+            if (segments[0] === BROADSIDE_DIR_NAME) {
+                return segments.length === 2 && INIT_BROADSIDE_TEMPLATE_FILES.has(segments[1]);
+            }
+            // Keep the directory, drop what this repository wrote inside it.
+            return !INIT_EXCLUDED_DIR_CONTENTS.has(segments[0]);
+        },
+    });
+    // The published tarball carries no empty directories, so an excluded-contents
+    // directory may not exist to be copied at all. Create them either way: a
+    // workspace whose closeouts/ is missing rather than empty reads differently
+    // to anything that lists it.
+    for (const name of INIT_EXCLUDED_DIR_CONTENTS) {
+        await mkdir(join(targetWorkspaceDir, name), { recursive: true });
+    }
+}
 /**
  * Seed the orchestrator-maintained files from the workspace's templates
  * (issue #98): orchestration is on by default, so a fresh workspace starts
@@ -131,7 +195,9 @@ export async function seedOrchestratorFiles(workspaceDir) {
  * Everything else present in the packaged template is framework-owned.
  */
 const REFRESH_EXCLUDED_TOP_LEVEL = new Set(["BACKLOG.md", "THREAD_LOG.md", "CONVENTIONS.md", "DECISIONS.md"]);
-const REFRESH_EXCLUDED_DIRS = new Set(["scratch", "inputs", "closeouts"]);
+// broadside/ holds machine-local scout state (batch ids, API key config,
+// generated results) — refresh must never overwrite it.
+const REFRESH_EXCLUDED_DIRS = new Set(["scratch", "inputs", "closeouts", "broadside"]);
 const REFRESH_EXCLUDED_WORKFLOW_FILES = new Set(["status.yaml", "config.yaml", ".usage.local.yaml"]);
 async function listTemplateFiles(dir, relativeDir = "") {
     const entries = await readdir(dir, { withFileTypes: true });
@@ -179,7 +245,15 @@ export async function refreshScaffold(cwd) {
         await copyFile(join(packagedWorkspaceDir, relativePath), target);
     }
     const entry = `- ${new Date().toISOString().slice(0, 10)} — scaffold-refresh — Refreshed ${files.length} framework-owned file(s) from the packaged template (${scaffoldVersionBefore ?? "unversioned"} → ${PACKAGE_VERSION}); project state, user config, and session outputs untouched.`;
-    await appendFile(join(state.workspaceDir, "THREAD_LOG.md"), `${entry}\n`, "utf8");
+    const threadLogPath = join(state.workspaceDir, "THREAD_LOG.md");
+    let currentLog = "";
+    try {
+        currentLog = await readFile(threadLogPath, "utf8");
+    }
+    catch {
+        // Created by the append when absent (pre-template scaffolds).
+    }
+    await appendFile(threadLogPath, `${newlineIfUnterminated(currentLog)}${entry}\n`, "utf8");
     return {
         written: files,
         ...(scaffoldVersionBefore !== undefined && { scaffoldVersionBefore }),
@@ -187,21 +261,6 @@ export async function refreshScaffold(cwd) {
     };
 }
 // Numeric x.y.z comparison; null when either side is not a plain dotted triple.
-function compareDottedVersions(a, b) {
-    const parse = (version) => {
-        const match = /^(\d+)\.(\d+)\.(\d+)$/.exec(version.trim());
-        return match ? [Number(match[1]), Number(match[2]), Number(match[3])] : null;
-    };
-    const left = parse(a);
-    const right = parse(b);
-    if (!left || !right)
-        return null;
-    for (let i = 0; i < 3; i++) {
-        if (left[i] !== right[i])
-            return left[i] < right[i] ? -1 : 1;
-    }
-    return 0;
-}
 /**
  * Human-readable staleness notice for the workspace's .codecarto/ scaffold,
  * or null when the scaffold matches the running framework. A missing marker
@@ -263,7 +322,7 @@ export async function updateStatusAtomically(cwd, updater) {
             const normalizedEntry = result.threadLogEntry.trim();
             const isDuplicate = logEntries.some((line) => line.trim() === normalizedEntry);
             if (!isDuplicate) {
-                await appendFile(threadLogPath, result.threadLogEntry, "utf8");
+                await appendFile(threadLogPath, `${newlineIfUnterminated(currentLog)}${normalizedEntry}\n`, "utf8");
             }
         }
         return nextState;

package/dist/core/yaml.js

@@ -3,6 +3,18 @@
 // Round-trips structured carry_forward/open_questions entries.
 import { readFile } from "node:fs/promises";
 import { isPlainObject } from "./utils.js";
+/**
+ * True when the double quote at `index` is escaped, i.e. preceded by an odd
+ * run of backslashes. Checking only the single previous character read `\\"`
+ * (an escaped backslash, then the closing quote) as an escaped quote, so the
+ * scalar never closed and a trailing ` # comment` leaked into the value (#134).
+ */
+function isEscapedQuote(text, index) {
+    let backslashes = 0;
+    for (let i = index - 1; i >= 0 && text[i] === "\\"; i--)
+        backslashes++;
+    return backslashes % 2 === 1;
+}
 export function stripYamlComment(value) {
     let inSingle = false;
     let inDouble = false;
@@ -12,7 +24,7 @@ export function stripYamlComment(value) {
             inSingle = !inSingle;
             continue;
         }
-        if (char === '"' && !inSingle && value[i - 1] !== "\\") {
+        if (char === '"' && !inSingle && !isEscapedQuote(value, i)) {
             inDouble = !inDouble;
             continue;
         }
@@ -49,7 +61,7 @@ function findKeySeparator(text) {
             inSingle = !inSingle;
             continue;
         }
-        if (char === '"' && !inSingle && text[i - 1] !== "\\") {
+        if (char === '"' && !inSingle && !isEscapedQuote(text, i)) {
             inDouble = !inDouble;
             continue;
         }
@@ -77,7 +89,10 @@ export function parseYamlScalar(rawValue) {
         return Number.parseInt(trimmed, 10);
     if (/^-?\d+\.\d+$/.test(trimmed))
         return Number.parseFloat(trimmed);
-    if (trimmed.startsWith('"') && trimmed.endsWith('"')) {
+    // A quoted scalar needs at least its two quotes: a lone quote character
+    // satisfied startsWith and endsWith at once and was sliced to "" (#134).
+    const canBeQuoted = trimmed.length >= 2;
+    if (canBeQuoted && trimmed.startsWith('"') && trimmed.endsWith('"')) {
         try {
             return JSON.parse(trimmed);
         }
@@ -85,7 +100,7 @@ export function parseYamlScalar(rawValue) {
             return trimmed.slice(1, -1);
         }
     }
-    if (trimmed.startsWith("'") && trimmed.endsWith("'")) {
+    if (canBeQuoted && trimmed.startsWith("'") && trimmed.endsWith("'")) {
         return trimmed.slice(1, -1).replace(/''/g, "'");
     }
     return trimmed;

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

@@ -183,6 +183,12 @@ export async function runPhase(ctx, prompt, callbacks = {}, options = {}, signal
     }
     try {
         await session.prompt(prompt);
+        // If no compaction fired during the run, the promise above would
+        // otherwise strand the continuation path for the full settle timeout
+        // (#129). Settle it with what actually happened — resolve() is
+        // idempotent, so a real compaction_end event earlier in the run
+        // keeps its `true`.
+        resolveCompaction?.(false);
         let primaryOutputPresent = true;
         if (options.primaryOutput) {
             primaryOutputPresent = await primaryOutputExists(cwd, options.primaryOutput);

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

@@ -41,6 +41,8 @@ export declare function isPhaseRunning(phaseId: string): boolean;
 export interface AutoCompleteResult {
     updatedState: WorkspaceState;
     closeoutNotice?: string;
+    /** Non-gating closure-integrity notes from completion (#122). */
+    warnings: string[];
 }
 export declare function autoCompletePhase(ctx: ExtensionContext, validation: ValidationResult): Promise<AutoCompleteResult>;
 export type AutoOutcome = "complete" | "stopped" | "aborted";

package/dist/extensions/codecarto/broadside-flags.d.ts

@@ -0,0 +1,26 @@
+import { type BroadsideLensId } from "../../core/index.ts";
+export type BroadsideAction = "submit" | "collect" | "status" | "models";
+export interface BroadsideFlags {
+    action: BroadsideAction;
+    /** Empty means "the repository's default lens set". */
+    lenses: BroadsideLensId[];
+    /**
+     * Undefined means "use the repository's config default". --incremental sets
+     * true and --no-incremental sets false, so a config-set `incremental: true`
+     * can be overridden back to a full scan for one run (#163).
+     */
+    incremental?: boolean;
+    includeSynthesis?: boolean;
+    includeTriage?: boolean;
+    retryTruncated?: boolean;
+    /** Undefined means "use the repository's config default". */
+    maxCost?: number;
+    waitSeconds?: number;
+    benchmarks: boolean;
+    unknown: string[];
+    /** Set on an invalid combination. The caller surfaces it as an error. */
+    error?: string;
+}
+/** Every token the completer offers, in the order it offers them. */
+export declare const KNOWN_BROADSIDE_TOKENS: readonly ["submit", "collect", "status", "models", "architecture", "api", "security", "defect", "conventions", "porting", "--incremental", "--no-incremental", "--max-cost=", "--wait=", "--no-synthesis", "--no-triage", "--no-retry-truncated", "--benchmarks"];
+export declare function parseBroadsideFlags(args: string): BroadsideFlags;

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

@@ -0,0 +1,129 @@
+// 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
+//   --no-incremental       --no-triage
+//   --max-cost=N           --no-retry-truncated
+//   --wait=SECONDS         --benchmarks (models only)
+//
+// --incremental has a spelled-out negative because the value is tri-state:
+// absent defers to config.yaml, so a repository that set `incremental: true`
+// can still ask for a one-off full scan (#163), exactly as an MCP caller can
+// with `incremental: false`.
+//
+// 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",
+    "--no-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: [],
+        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" || token === "--no-incremental") {
+            const value = token === "--incremental";
+            // Last-one-wins would be a silent tiebreak on a command that spends
+            // money; a contradiction is an error.
+            if (result.incremental !== undefined && result.incremental !== value) {
+                result.error ??= "--incremental and --no-incremental contradict each other; pass one or neither.";
+            }
+            result.incremental = value;
+            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 (and --no-incremental
+    // would read as a full re-collect, which is not one either).
+    if (result.lenses.length > 0 && result.action !== "submit") {
+        result.error ??= `Lens names are only meaningful for submit (got action "${result.action}").`;
+    }
+    if (result.incremental !== undefined && result.action !== "submit") {
+        const flag = result.incremental ? "--incremental" : "--no-incremental";
+        result.error ??= `${flag} 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-narrator.js

@@ -66,7 +66,7 @@ async function readRecentCloseouts(workspaceDir) {
         return m ? { date: m[1], phaseOrModule: m[2], fileName: name } : null;
     })
         .filter((x) => x !== null)
-        .sort((a, b) => (a.date < b.date ? 1 : -1))
+        .sort((a, b) => (a.date < b.date ? 1 : a.date > b.date ? -1 : 0))
         .slice(0, MAX_CLOSEOUTS);
     const out = [];
     for (const entry of matched) {