codecartographer-pi 0.16.0 → 0.17.0

package/dist/core/completion.js

@@ -1,6 +1,6 @@
 import { appendFile, copyFile, mkdir, readFile, readdir, writeFile } from "node:fs/promises";
 import { join } from "node:path";
-import { getNextEligiblePhase, resolvePhase } from "./pipeline.js";
+import { getNextEligiblePhase, resolvePhase, validatePhaseOutput } from "./pipeline.js";
 import { applyHandoff, autoAssignIds, buildTerminalNextActions, loadHandoffFile, normalizeStatus } from "./status.js";
 import { dateOnly, pathExists, uniqueStrings } from "./utils.js";
 import { getWorkspaceState, updateStatusAtomically } from "./workspace.js";
@@ -275,6 +275,22 @@ export async function completeValidatedPhase(cwd, validation, sourceLabel) {
         const phase = resolvePhase(lockedState, validation.phaseId);
         if (!phase?.primary_output)
             throw new Error(`Phase ${validation.phaseId} is missing primary_output.`);
+        // Re-validate the output under the lock (#132). The caller's
+        // validation snapshot can predate a concurrent edit or another
+        // session's completion; a stale PASS must not complete a phase whose
+        // output no longer validates. The locked recheck is the authoritative
+        // one and is what every artifact below is written from.
+        // A validation that never touched a file on disk (no outputPath)
+        // has nothing to race against, so the caller's result stands — the
+        // real surfaces (MCP, Pi) always validate real files.
+        const authoritative = validation.outputPath
+            ? await validatePhaseOutput(lockedState, validation.phaseId)
+            : validation;
+        if (authoritative.overall === "FAIL" || authoritative.overall === "MISSING") {
+            throw new Error(`Refusing to complete ${validation.phaseId}: the output no longer validates under the status lock ` +
+                `(now ${authoritative.overall}). It changed since the last validation — re-run validation and fix the output first.`);
+        }
+        const lockedValidation = authoritative;
         const nextStatus = normalizeStatus(lockedState.status, lockedState.pipeline, lockedState.status.pipeline, lockedState.cwd);
         const existingPhase = nextStatus.phases[validation.phaseId] ?? {
             status: "pending",
@@ -283,7 +299,7 @@ export async function completeValidatedPhase(cwd, validation, sourceLabel) {
             open_questions: [],
             carry_forward: [],
         };
-        const gapEntries = validation.rows
+        const gapEntries = lockedValidation.rows
             .filter((row) => row.result.toUpperCase().includes("PARTIAL"))
             .map((row) => ({
             kind: "needs-maintainer-decision",
@@ -303,7 +319,7 @@ export async function completeValidatedPhase(cwd, validation, sourceLabel) {
                 ...existingPhase.owner_notes,
                 `Completed via ${sourceLabel}.`,
                 `Primary output: .codecarto/${validation.primaryOutput}`,
-                `Validation: ${validation.overall}`,
+                `Validation: ${lockedValidation.overall}`,
             ]),
             outputs_present: uniqueStrings([...existingPhase.outputs_present, validation.primaryOutput]),
             open_questions: mergedOpenQuestions,
@@ -318,7 +334,7 @@ export async function completeValidatedPhase(cwd, validation, sourceLabel) {
         nextStatus.next_actions = nextEligible
             ? [`Begin ${nextEligible.id} phase by producing ${nextEligible.primary_output ?? `findings/${nextEligible.id}/`}`]
             : buildTerminalNextActions(nextStatus);
-        const artifacts = await writeCompletionArtifacts(lockedState.workspaceDir, validation.phaseId, validation, completionTimestamp, handoff);
+        const artifacts = await writeCompletionArtifacts(lockedState.workspaceDir, validation.phaseId, lockedValidation, completionTimestamp, handoff);
         closeoutPath = artifacts.closeoutPath;
         orchestratorCheckpoint = buildOrchestratorCheckpoint(artifacts.decisionsAppended, artifacts.totalPendingProposals, nextStatus);
         return { state: { ...nextWorkspace, status: nextStatus } };

package/dist/core/index.d.ts

@@ -13,3 +13,4 @@ export * from "./guide.ts";
 export * from "./dashboard.ts";
 export * from "./library.ts";
 export * from "./synthesis.ts";
+export * from "./broadside.ts";

package/dist/core/index.js

@@ -16,3 +16,4 @@ export * from "./guide.js";
 export * from "./dashboard.js";
 export * from "./library.js";
 export * from "./synthesis.js";
+export * from "./broadside.js";

package/dist/core/library.d.ts

@@ -108,6 +108,20 @@ export declare function isValidSlug(slug: string): boolean;
  * to ask the user about it.
  */
 export declare function deriveSlug(sourceRepo: string): string;
+/**
+ * Reduce a repo reference to a comparable form so that spellings of the same
+ * repository do not read as different projects. Handles scheme, `git@host:path`
+ * SCP syntax, a `www.` host prefix, a trailing `.git`, repeated and trailing
+ * slashes, backslash separators, and case.
+ *
+ * This is deliberately conservative: it only collapses spellings that are
+ * unambiguously the same target. Anything it cannot prove equivalent stays
+ * distinct, because the caller treats "different" as a hard error. Case is the
+ * one place that cuts the other way — see the note above the return.
+ */
+export declare function normalizeSourceRepo(sourceRepo: string): string;
+/** True when two repo references denote the same repository. */
+export declare function sameSourceRepo(a: string, b: string): boolean;
 export interface PublishInput {
     slug: string;
     namespace?: string;
@@ -131,6 +145,14 @@ export interface PublishOptions {
     forceNewVersion?: boolean;
     /** Skip the regen of index.yaml + INDEX.md (caller will batch). */
     skipReindex?: boolean;
+    /**
+     * Permit publishing when the target entry's recorded `source_repo` differs
+     * from the incoming one. Off by default: a mismatch usually means two
+     * different projects derived the same slug, and continuing would append
+     * one project's spec to the other's version history. Set this only when
+     * the repository genuinely moved (rename, org transfer, host change).
+     */
+    allowSourceRepoChange?: boolean;
 }
 export interface PublishResult {
     slug: string;

package/dist/core/library.js

@@ -136,6 +136,83 @@ export function deriveSlug(sourceRepo) {
     const safe = slug.length === 0 || !/^[a-z]/.test(slug) ? `entry-${slug}`.slice(0, 64) : slug;
     return RESERVED_SLUGS.has(safe) ? `${safe}-entry` : safe;
 }
+/**
+ * Reduce a repo reference to a comparable form so that spellings of the same
+ * repository do not read as different projects. Handles scheme, `git@host:path`
+ * SCP syntax, a `www.` host prefix, a trailing `.git`, repeated and trailing
+ * slashes, backslash separators, and case.
+ *
+ * This is deliberately conservative: it only collapses spellings that are
+ * unambiguously the same target. Anything it cannot prove equivalent stays
+ * distinct, because the caller treats "different" as a hard error. Case is the
+ * one place that cuts the other way — see the note above the return.
+ */
+export function normalizeSourceRepo(sourceRepo) {
+    let s = sourceRepo.trim().replace(/\\/g, "/");
+    // Order matters here. The scheme comes off first so that the SCP branch
+    // below sees only genuine `host:path` syntax, and the userinfo strip runs
+    // before either interpretation of a colon. Getting this order wrong makes
+    // `ssh://git@host/acme/tool` and `https://host/acme/tool` read as two
+    // different repositories, which would refuse a legitimate re-publish.
+    const hadScheme = /^[A-Za-z][A-Za-z0-9+.-]*:\/\//.test(s);
+    s = s.replace(/^[A-Za-z][A-Za-z0-9+.-]*:\/\//, "");
+    // git@, user:token@, oauth2:x-oauth-basic@ ...
+    s = s.replace(/^[^/@]+@/, "");
+    // SCP syntax (git@github.com:acme/tool) only ever appears without a scheme,
+    // where the colon separates host from path rather than naming a port. The
+    // dot requirement keeps a Windows drive letter (C:/repos/tool) out of this
+    // branch.
+    if (!hadScheme)
+        s = s.replace(/^([^:/]+\.[^:/]+):(.+)$/, "$1/$2");
+    // A default port for the transports in play is not a distinguishing part of
+    // the address. Any other port is left alone, since two services on one host
+    // may genuinely differ by port.
+    s = s.replace(/^([^/]+):(?:22|80|443)(?=\/|$)/, "$1");
+    s = s.replace(/^www\./i, "");
+    s = s.replace(/\.git$/i, "");
+    // Repeated separators name the same location. A leading `//` is the one
+    // exception: on Windows that is a UNC share (\\server\share), which is not
+    // the same place as /server/share.
+    s = s.startsWith("//") ? `/${s.replace(/\/{2,}/g, "/")}` : s.replace(/\/{2,}/g, "/");
+    s = s.replace(/\/+$/, "");
+    // Case folding is only safe where the target is case-insensitive. Hosts are,
+    // as are the repository paths the major forges serve over them, and so are
+    // Windows drive paths. A POSIX absolute path is not: /srv/Repos/tool and
+    // /srv/repos/tool are two directories on Linux, and folding them together
+    // would hide exactly the cross-project collision this comparison exists to
+    // catch. Pi records the analyzed directory as source_repo, so local paths
+    // are a common case here rather than a curiosity.
+    return isCaseSensitivePath(s) ? s : s.toLowerCase();
+}
+/** An absolute POSIX path (or a `~` home reference), where case is significant. */
+function isCaseSensitivePath(s) {
+    return s.startsWith("/") || s === "~" || s.startsWith("~/");
+}
+/** True when two repo references denote the same repository. */
+export function sameSourceRepo(a, b) {
+    return normalizeSourceRepo(a) === normalizeSourceRepo(b);
+}
+/**
+ * The `source_repo` recorded on an entry's newest version, or null when it
+ * cannot be determined (no metadata, unreadable, or malformed). Null means
+ * "unknown", and callers treat unknown as permission to proceed rather than
+ * as a mismatch.
+ */
+async function readRecordedSourceRepo(libraryRoot, namespace, slug, version) {
+    const metaPath = join(versionDir(libraryRoot, namespace, slug, version), METADATA_FILE);
+    if (!(await pathExists(metaPath)))
+        return null;
+    try {
+        const raw = parseSimpleYaml(await readFile(metaPath, "utf8"));
+        if (!isPlainObject(raw))
+            return null;
+        const recorded = raw.source_repo;
+        return typeof recorded === "string" && recorded.trim() !== "" ? recorded : null;
+    }
+    catch {
+        return null;
+    }
+}
 // ─── Path helpers ───────────────────────────────────────────────────────────
 function entryRoot(libraryRoot, namespace, slug) {
     return namespace ? join(libraryRoot, ENTRIES_DIR, namespace, slug) : join(libraryRoot, ENTRIES_DIR, slug);
@@ -198,6 +275,26 @@ export async function publishEntry(libraryRoot, spec, input, opts = {}) {
     const existingVersions = await listVersionDirs(entryDir);
     const latestVersion = existingVersions.length === 0 ? 0 : existingVersions[existingVersions.length - 1];
     const newSpecHash = sha256(spec);
+    // Collision guard. Slugs derive from the trailing path segment of the source
+    // repo, so two unrelated projects (acme/whisper and openai/whisper) collapse
+    // onto one slug. Without this check the second publish would append its spec
+    // to the first project's version history, and the index would then report the
+    // newcomer's source_repo as though it owned every prior version. Checked
+    // before the idempotence branch below, because a metadata-only update would
+    // overwrite the wrong entry just as silently.
+    if (latestVersion > 0 && !opts.allowSourceRepoChange) {
+        const recorded = await readRecordedSourceRepo(libraryRoot, namespace, input.slug, latestVersion);
+        if (recorded !== null && !sameSourceRepo(recorded, input.source_repo)) {
+            const label = namespace ? `${namespace}/${input.slug}` : input.slug;
+            throw new Error(`Refusing to publish: entry "${label}" v${latestVersion} records source_repo ` +
+                `"${recorded}", but this publish carries "${input.source_repo}". Publishing would ` +
+                `append this spec to a different project's version history. Publish this project ` +
+                `under a distinct slug to shelve it separately, or — if the repository itself ` +
+                `moved (rename, org transfer, host change) — re-publish with the source-repo ` +
+                `change allowed: allow_source_repo_change on codecarto_publish, ` +
+                `allowSourceRepoChange in PublishOptions.`);
+        }
+    }
     // Content-hash idempotence: if the latest version's spec matches bytes-for-bytes,
     // update metadata in place and return without bumping the version.
     if (latestVersion > 0 && !opts.forceNewVersion) {
@@ -635,7 +732,10 @@ function formatIndexRow(e, namespaced) {
     return `| ${slugLink} | v${e.latest_version} | ${headline} | ${tags} |`;
 }
 function escapeMd(value) {
-    return value.replace(/\|/g, "\\|").replace(/\r?\n/g, " ");
+    // Backslashes first: escaping only the pipe lets an input ending in `\`
+    // turn the emitted `\|` into a literal-backslash-plus-cell-delimiter and
+    // break out of the table cell (code scanning alert #3).
+    return value.replace(/\\/g, "\\\\").replace(/\|/g, "\\|").replace(/\r?\n/g, " ");
 }
 // ─── Atomic YAML write ──────────────────────────────────────────────────────
 async function atomicWriteYaml(path, value) {

package/dist/core/orchestrator-config.js

@@ -14,7 +14,7 @@
 // `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 { dirname, join, resolve } from "node:path";
 import { mkdir, readFile, writeFile } from "node:fs/promises";
 import { expandTilde, pathExists } from "./utils.js";
 import { loadYamlFile, parseSimpleYaml, stringifySimpleYaml } from "./yaml.js";
@@ -131,7 +131,10 @@ export async function writeLibraryConfig(configPath, libraryPath, namespace = nu
     if (namespace)
         library.namespace = namespace;
     const updated = { ...existing, library };
-    const dir = configPath.includes("/") ? configPath.slice(0, configPath.lastIndexOf("/")) : ".";
+    // dirname() honors the platform separator; the previous hand-rolled
+    // `includes("/")` check treated every Windows path as a bare filename
+    // and left mkdir a no-op before the writeFile ENOENT'd (#128).
+    const dir = dirname(configPath);
     await mkdir(dir, { recursive: true });
     await writeFile(configPath, `${stringifySimpleYaml(updated)}\n`, "utf8");
 }

package/dist/core/pipeline.js

@@ -5,6 +5,7 @@ import { pathExists } from "./utils.js";
 export const PIPELINE_ALIASES = {
     "full-with-audit": "workflow/pipeline-full-with-audit.yaml",
     "full-with-deep-audit": "workflow/pipeline-full-with-deep-audit.yaml",
+    "scout-first": "workflow/pipeline-scout-first.yaml",
     full: "workflow/pipeline.yaml",
     "defect-scan": "workflow/pipeline-defect-scan.yaml",
     lite: "workflow/pipeline-lite.yaml",

package/dist/core/status.js

@@ -345,7 +345,15 @@ export async function acquireLock(lockPath) {
     while (true) {
         try {
             const handle = await open(lockPath, "wx");
-            await handle.writeFile(`${process.pid}\n${new Date().toISOString()}\n`, "utf8");
+            try {
+                await handle.writeFile(`${process.pid}\n${new Date().toISOString()}\n`, "utf8");
+            }
+            catch (error) {
+                // A non-EEXIST write failure must not leak the descriptor the
+                // open just created (#131); close best-effort, then rethrow.
+                await handle.close().catch(() => undefined);
+                throw error;
+            }
             await handle.close();
             return {
                 release: async () => {

package/dist/core/utils.js

@@ -34,7 +34,13 @@ export function isWithinPath(path, root) {
     const normalizedRoot = normalizeForComparison(resolve(root));
     if (normalizedPath === normalizedRoot)
         return true;
-    return normalizedPath.startsWith(`${normalizedRoot}${process.platform === "win32" ? "\\" : "/"}`);
+    // A filesystem root (e.g. "/" or "C:\") already ends in a separator;
+    // appending another one produced a prefix ("//" / "C:\\") that no real
+    // path starts with, falsely rejecting every legitimate subpath (#130).
+    const prefix = normalizedRoot.endsWith("/") || normalizedRoot.endsWith("\\")
+        ? normalizedRoot
+        : `${normalizedRoot}${process.platform === "win32" ? "\\" : "/"}`;
+    return normalizedPath.startsWith(prefix);
 }
 /**
  * Symlink-aware version of isWithinPath. Resolves symlinks on both the path

package/dist/core/workspace.d.ts

@@ -11,7 +11,24 @@ export declare const ORCHESTRATOR_FILES: readonly [{
 }, {
     readonly file: "DECISIONS.md";
     readonly template: "decisions-template.md";
+}, {
+    readonly file: "BACKLOG.md";
+    readonly template: "backlog-project.md";
+}, {
+    readonly file: "THREAD_LOG.md";
+    readonly template: "thread-log.md";
 }];
+/**
+ * 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 declare function copyPackagedWorkspace(targetWorkspaceDir: string, sourceWorkspaceDir?: string): Promise<void>;
 /**
  * Seed the orchestrator-maintained files from the workspace's templates
  * (issue #98): orchestration is on by default, so a fresh workspace starts

package/dist/core/workspace.js

@@ -3,7 +3,7 @@
 // + 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";
@@ -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 });

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/broadside-flags.d.ts

@@ -0,0 +1,21 @@
+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[];
+    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", "--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,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;
+}