codecartographer-pi 0.19.6 → 0.21.0

package/dist/core/completion.js

@@ -1,7 +1,7 @@
 import { appendFile, copyFile, mkdir, readFile, readdir, writeFile } from "node:fs/promises";
 import { join } from "node:path";
-import { getNextEligiblePhase, resolvePhase, validatePhaseOutput } from "./pipeline.js";
-import { applyHandoff, autoAssignIds, buildTerminalNextActions, loadHandoffFile, normalizeStatus } from "./status.js";
+import { recomputeCursor, resolvePhase, validatePhaseOutput } from "./pipeline.js";
+import { applyHandoff, autoAssignIds, loadHandoffFile, normalizeStatus } from "./status.js";
 import { compareDottedVersions, dateOnly, newlineIfUnterminated, pathExists, uniqueStrings } from "./utils.js";
 import { getWorkspaceState, updateStatusAtomically } from "./workspace.js";
 /**
@@ -110,7 +110,13 @@ async function appendDecisionLog(workspaceDir, phaseId, closeoutFile, decisions)
         const number = String(nextNumber + index).padStart(3, "0");
         return `D${number} | ${decision.trim()} | ${source} | closeouts/${closeoutFile} §Decisions Beyond Prompt (${phaseId})`;
     });
-    content += `${content.endsWith("\n") ? "" : "\n"}${rows.join("\n")}\n`;
+    // A row appended straight after the section's explanatory paragraph is
+    // rendered as part of that paragraph by most Markdown renderers; a blank
+    // line makes the rows their own block (self-audit F4). Rows already
+    // present stay contiguous with the new ones.
+    const trailing = content.replace(/\n+$/, "").split("\n").pop() ?? "";
+    const separator = /^D\d+\s*\|/.test(trailing) || trailing.trim() === "" ? "" : "\n";
+    content += `${content.endsWith("\n") ? "" : "\n"}${separator}${rows.join("\n")}\n`;
     await writeFile(join(workspaceDir, "DECISIONS.md"), content, "utf8");
     return fresh.length;
 }
@@ -253,6 +259,80 @@ export function closureEvidenceGateActive(scaffoldVersion) {
     const comparison = compareDottedVersions(scaffoldVersion, CLOSURE_EVIDENCE_GATE_SCAFFOLD_VERSION);
     return comparison !== null && comparison >= 0;
 }
+/**
+ * Whether `text` names one of `ids` as a whole token: the id must not run
+ * straight into another id character on either side, so `arch-CF2` matches
+ * "routed as `arch-CF2`" and not "arch-CF20".
+ */
+function mentionsAnyId(text, ids) {
+    for (const id of ids) {
+        let from = 0;
+        while (true) {
+            const at = text.indexOf(id, from);
+            if (at === -1)
+                break;
+            const before = at === 0 ? "" : text[at - 1];
+            const after = text[at + id.length] ?? "";
+            if (!/[A-Za-z0-9_-]/.test(before) && !/[A-Za-z0-9_-]/.test(after))
+                return true;
+            from = at + 1;
+        }
+    }
+    return false;
+}
+/**
+ * Turn each PARTIAL validation row into a `needs-maintainer-decision`
+ * question on the phase, unless the row's criterion or evidence cell names an
+ * entry the workspace already tracks: an open question, carry-forward, or
+ * post-pipeline item, from this handoff or an earlier phase. VALIDATE.md asks
+ * the phase to name the tracking entry in the evidence cell; honouring it is
+ * what stops a routed gap from also becoming a duplicate question that every
+ * later phase re-triages and someone must close (#239).
+ *
+ * Runs after the handoff has been applied. That is also what keeps the auto
+ * ids distinct from the handoff's: both `autoAssignIds` from `oq-<phase>-1`,
+ * and assigning the gaps first let a later id-less handoff question replace a
+ * gap under the same id.
+ */
+function addPartialRowQuestions(status, phaseId, rows) {
+    const phase = status.phases[phaseId];
+    if (!phase)
+        return;
+    const trackedIds = new Set();
+    for (const phaseState of Object.values(status.phases)) {
+        for (const entry of [...(phaseState.open_questions ?? []), ...(phaseState.carry_forward ?? [])]) {
+            if (entry.id)
+                trackedIds.add(entry.id);
+        }
+    }
+    for (const entry of status.post_pipeline) {
+        if (entry.id)
+            trackedIds.add(entry.id);
+    }
+    const gapEntries = [];
+    for (const row of rows) {
+        if (!row.result.toUpperCase().includes("PARTIAL"))
+            continue;
+        if (mentionsAnyId(`${row.criterion} ${row.evidence}`, trackedIds))
+            continue;
+        const candidate = {
+            kind: "needs-maintainer-decision",
+            description: row.criterion || "Partial validation gap",
+            deferred_reason: row.evidence || "Marked PARTIAL by validation",
+        };
+        // Idempotent across re-runs of completion: the same gap is one question.
+        if (phase.open_questions.some((entry) => entry.description === candidate.description && entry.deferred_reason === candidate.deferred_reason))
+            continue;
+        gapEntries.push(candidate);
+    }
+    if (gapEntries.length === 0)
+        return;
+    // Reserve every id already on the phase so the new ones skip them; the
+    // placeholders keep autoAssignIds from touching the existing entries.
+    const reserved = phase.open_questions.filter((entry) => entry.id).map((entry) => ({ id: entry.id }));
+    autoAssignIds([...reserved, ...gapEntries], "oq", phaseId);
+    phase.open_questions.push(...gapEntries);
+}
 export async function completeValidatedPhase(cwd, validation, sourceLabel) {
     const initialState = await getWorkspaceState(cwd);
     if (!initialState)
@@ -391,20 +471,6 @@ export async function completeValidatedPhase(cwd, validation, sourceLabel) {
             open_questions: [],
             carry_forward: [],
         };
-        const gapEntries = lockedValidation.rows
-            .filter((row) => row.result.toUpperCase().includes("PARTIAL"))
-            .map((row) => ({
-            kind: "needs-maintainer-decision",
-            description: row.criterion || "Partial validation gap",
-            deferred_reason: row.evidence || "Marked PARTIAL by validation",
-        }));
-        autoAssignIds(gapEntries, "oq", validation.phaseId);
-        const mergedOpenQuestions = [...existingPhase.open_questions];
-        for (const candidate of gapEntries) {
-            if (!mergedOpenQuestions.some((entry) => entry.description === candidate.description && entry.deferred_reason === candidate.deferred_reason)) {
-                mergedOpenQuestions.push(candidate);
-            }
-        }
         nextStatus.phases[validation.phaseId] = {
             status: "complete",
             owner_notes: uniqueStrings([
@@ -414,18 +480,17 @@ export async function completeValidatedPhase(cwd, validation, sourceLabel) {
                 `Validation: ${lockedValidation.overall}`,
             ]),
             outputs_present: uniqueStrings([...existingPhase.outputs_present, validation.primaryOutput]),
-            open_questions: mergedOpenQuestions,
+            open_questions: [...existingPhase.open_questions],
             carry_forward: existingPhase.carry_forward ?? [],
         };
         if (handoff)
             applyHandoff(nextStatus, handoff);
+        // After the handoff, so a gap the handoff routed is recognised as
+        // tracked and the ids the handoff introduced are known (#239).
+        addPartialRowQuestions(nextStatus, validation.phaseId, lockedValidation.rows);
         nextStatus.last_updated = completionTimestamp;
         const nextWorkspace = { ...lockedState, status: nextStatus };
-        const nextEligible = getNextEligiblePhase(nextWorkspace);
-        nextStatus.current_phase = nextEligible?.id ?? "complete";
-        nextStatus.next_actions = nextEligible
-            ? [`Begin ${nextEligible.id} phase by producing ${nextEligible.primary_output ?? `findings/${nextEligible.id}/`}`]
-            : buildTerminalNextActions(nextStatus);
+        recomputeCursor(nextWorkspace);
         return {
             state: { ...nextWorkspace, status: nextStatus },
             // The closeout, THREAD_LOG line, decision rows, and staged proposals

package/dist/core/dashboard-writer.d.ts

@@ -0,0 +1,8 @@
+/**
+ * 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/core/dashboard-writer.js

@@ -0,0 +1,159 @@
+// I/O wrapper that gathers all dashboard inputs and writes the rendered
+// HTML to `.codecarto/dashboard.html`. Best-effort — failures are swallowed
+// and never escalate to a phase error the user sees, mirroring the
+// recordUsage discipline at extensions/codecarto/index.ts.
+//
+// Lived in the Pi extension until #254, with the MCP server reaching across
+// to import it; both surfaces refresh the dashboard at the same lifecycle
+// points (init, completion, amendment, pipeline switch, on demand), so it is
+// a core primitive like everything else they share.
+import { readdir, readFile } from "node:fs/promises";
+import { join } from "node:path";
+import { atomicWriteFile, DASHBOARD_RELATIVE_PATH, getWorkspaceState, loadUsage, NARRATION_CACHE_RELATIVE_PATH, parseSimpleYaml, pathExists, renderDashboard, } from "./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 false;
+        const workspaceDir = state.workspaceDir;
+        const [usage, closeouts, outputsPresent, narration] = await Promise.all([
+            loadUsage(workspaceDir),
+            listCloseouts(workspaceDir),
+            buildOutputsPresent(state.workspaceDir, state.pipeline),
+            loadNarration(workspaceDir),
+        ]);
+        const inputs = {
+            status: state.status,
+            pipeline: state.pipeline,
+            usage,
+            closeouts,
+            outputsPresent,
+            packageVersion,
+            generatedAt: new Date().toISOString(),
+            narration,
+        };
+        const html = renderDashboard(inputs);
+        await atomicWriteFile(join(workspaceDir, DASHBOARD_RELATIVE_PATH), html);
+        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) {
+    const dir = join(workspaceDir, "closeouts");
+    if (!(await pathExists(dir)))
+        return [];
+    let entries;
+    try {
+        entries = await readdir(dir);
+    }
+    catch {
+        return [];
+    }
+    const out = [];
+    for (const name of entries) {
+        const m = CLOSEOUT_FILENAME_RE.exec(name);
+        if (!m)
+            continue;
+        out.push({ date: m[1], phaseOrModule: m[2], fileName: name, summary: await readCloseoutSummary(join(dir, name)) });
+    }
+    return out;
+}
+async function readCloseoutSummary(path) {
+    try {
+        const raw = await readFile(path, "utf8");
+        const lines = raw.split(/\r?\n/);
+        const summaryStart = lines.findIndex((line) => /^##\s+Summary\s*$/i.test(line.trim()));
+        if (summaryStart === -1)
+            return undefined;
+        const body = [];
+        for (const line of lines.slice(summaryStart + 1)) {
+            if (/^##\s+/.test(line.trim()))
+                break;
+            const trimmed = line.trim();
+            if (!trimmed || trimmed === "-")
+                continue;
+            body.push(trimmed.replace(/^[-*]\s+/, ""));
+            if (body.join(" ").length > 280)
+                break;
+        }
+        const summary = body.join(" ").trim();
+        return summary ? `${summary.slice(0, 280)}${summary.length > 280 ? "…" : ""}` : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+async function buildOutputsPresent(workspaceDir, pipeline) {
+    const out = new Map();
+    for (const phaseId of pipeline.phase_order) {
+        const phaseDef = pipeline.phases.find((p) => p.id === phaseId);
+        if (!phaseDef)
+            continue;
+        const entry = { secondary: [] };
+        if (phaseDef.primary_output) {
+            entry.primary = {
+                path: phaseDef.primary_output,
+                exists: await pathExists(join(workspaceDir, phaseDef.primary_output)),
+            };
+        }
+        for (const sec of phaseDef.secondary_outputs ?? []) {
+            entry.secondary.push({
+                path: sec.path,
+                exists: await pathExists(join(workspaceDir, sec.path)),
+            });
+        }
+        out.set(phaseId, entry);
+    }
+    return out;
+}
+async function loadNarration(workspaceDir) {
+    const path = join(workspaceDir, NARRATION_CACHE_RELATIVE_PATH);
+    if (!(await pathExists(path)))
+        return undefined;
+    try {
+        const raw = await readFile(path, "utf8");
+        const { frontmatter, body } = splitFrontmatter(raw);
+        if (!frontmatter)
+            return undefined;
+        const generatedAt = typeof frontmatter.generatedAt === "string" ? frontmatter.generatedAt : "";
+        const phaseCountAtGeneration = typeof frontmatter.phaseCountAtGeneration === "number" ? frontmatter.phaseCountAtGeneration : 0;
+        if (!generatedAt)
+            return undefined;
+        return { content: body.trim(), generatedAt, phaseCountAtGeneration };
+    }
+    catch {
+        return undefined;
+    }
+}
+function splitFrontmatter(raw) {
+    if (!raw.startsWith("---\n"))
+        return { frontmatter: null, body: raw };
+    const end = raw.indexOf("\n---\n", 4);
+    if (end === -1)
+        return { frontmatter: null, body: raw };
+    const yamlText = raw.slice(4, end);
+    const body = raw.slice(end + 5);
+    try {
+        const parsed = parseSimpleYaml(yamlText);
+        if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) {
+            return { frontmatter: parsed, body };
+        }
+    }
+    catch {
+        // fall through
+    }
+    return { frontmatter: null, body };
+}

package/dist/core/index.d.ts

@@ -16,3 +16,5 @@ export * from "./dashboard.ts";
 export * from "./library.ts";
 export * from "./synthesis.ts";
 export * from "./broadside.ts";
+export * from "./secrets.ts";
+export * from "./dashboard-writer.ts";

package/dist/core/index.js

@@ -19,3 +19,5 @@ export * from "./dashboard.js";
 export * from "./library.js";
 export * from "./synthesis.js";
 export * from "./broadside.js";
+export * from "./secrets.js";
+export * from "./dashboard-writer.js";

package/dist/core/library.js

@@ -33,7 +33,7 @@ import { spawn } from "node:child_process";
 import { mkdir, readFile, readdir, rename, rm, writeFile } from "node:fs/promises";
 import { basename, join, resolve } from "node:path";
 import { acquireLock } from "./status.js";
-import { atomicWriteFile, canonicalPath, isPlainObject, normalizeForComparison, pathExists, uniqueTempSuffix } from "./utils.js";
+import { atomicWriteFile, canonicalPath, GIT_TIMEOUT_MS, isPlainObject, normalizeForComparison, pathExists, uniqueTempSuffix } from "./utils.js";
 import { parseSimpleYaml, stringifySimpleYaml } from "./yaml.js";
 // ─── Constants ──────────────────────────────────────────────────────────────
 export const LIBRARY_MARKER_FILE = ".codecarto-library";
@@ -676,7 +676,10 @@ export async function listEntries(libraryRoot, filter = {}) {
             return false;
         if (filter.slug !== undefined && e.slug !== filter.slug)
             return false;
-        if (filter.source_repo !== undefined && e.source_repo !== filter.source_repo)
+        // Same equivalence the publish guard applies: `.git`, scheme, userinfo,
+        // default port, and forge-host case do not make two references two
+        // repositories, so they must not make a filter miss one either (#257).
+        if (filter.source_repo !== undefined && !sameSourceRepo(e.source_repo, filter.source_repo))
             return false;
         if (filter.tag !== undefined && !e.tags.includes(filter.tag))
             return false;
@@ -827,7 +830,7 @@ async function writeIndexMarkdown(libraryRoot, index, marker) {
     const lines = [];
     lines.push(`# ${escapeMd(marker.name)} — Library Index`);
     lines.push("");
-    lines.push(`_Generated ${index.generated_at}. Do not edit by hand — regenerate with \`codecarto library-reindex\`._`);
+    lines.push(`_Generated ${index.generated_at}. Do not edit by hand — regenerate with the \`codecarto_library_reindex\` MCP tool._`);
     lines.push("");
     // A single-tenant library has no namespaces but is still one namespace's
     // worth of entries; count once so the noun agrees with the number shown.
@@ -1038,7 +1041,9 @@ export async function commitPublish(libraryRoot, message, opts = {}) {
 }
 function runGit(cwd, args) {
     return new Promise((resolvePromise) => {
-        const child = spawn("git", args, { cwd, stdio: ["ignore", "pipe", "pipe"] });
+        // Bounded like every fetch: a credential helper waiting on a prompt
+        // used to hang publish or source-repo resolution for good (sem 3.12).
+        const child = spawn("git", args, { cwd, stdio: ["ignore", "pipe", "pipe"], timeout: GIT_TIMEOUT_MS });
         let stdout = "";
         let stderr = "";
         child.stdout.on("data", (b) => {

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

@@ -24,9 +24,24 @@ export interface LibraryConfig {
      *  to hosts that actually configured the key. */
     publish_confirm_configured: boolean;
 }
+/** One thing a config file said that the loader could not use. */
+export interface ConfigProblem {
+    /** The config file the problem was found in. */
+    path: string;
+    /** What was wrong and what the loader did about it. */
+    message: string;
+}
 export interface CodecartoConfig {
     orchestrator: OrchestratorConfig;
     library: LibraryConfig;
+    /**
+     * Faults in the config files that were read, in layer order (user-global
+     * first). Empty when every file that exists was used in full. The loader
+     * never throws on a bad file — a phase run should not be blocked by a
+     * typo in a toggle — but publish refuses while this is non-empty, since
+     * the library path and the confirm gate come from here.
+     */
+    problems: ConfigProblem[];
 }
 export declare const CONFIG_RELATIVE_PATH = "workflow/config.yaml";
 export declare const USER_CONFIG_DIR: string;
@@ -56,15 +71,25 @@ export declare function loadCodecartoConfig(workspaceDir: PathLike): Promise<Cod
  */
 export declare function loadUserConfig(): Promise<CodecartoConfig>;
 /**
- * Apply one raw config layer over an existing config. Public so tests can
+ * Apply one raw config layer over the defaults. 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").
+ * a layer in memory (e.g. "what if library_path were X"). `sourcePath`
+ * names the layer in any problem it produces.
+ */
+export declare function mergeConfig(raw: RawConfig | null | undefined, sourcePath?: string): CodecartoConfig;
+/**
+ * The lines both surfaces print for a config with problems: one header,
+ * then one line per fault naming its file. Empty when there are none.
  */
-export declare function mergeConfig(raw: RawConfig | null | undefined): CodecartoConfig;
+export declare function describeConfigProblems(config: CodecartoConfig): string[];
 /**
- * Write a `library:` block into a config file (user-global or workspace).
- * Creates the file and parent directories if needed. Preserves any existing
- * `orchestrator:` block. Overwrites the `library:` block if present.
+ * Record a library in a config file (user-global or workspace): set
+ * `library.path`, and `library.namespace` when one is given. Every other key
+ * in the file, `library.publish_confirm` included, is left exactly as it was
+ * — library-init writes only what it was asked for, so it cannot switch the
+ * MCP confirm gate on behind the user's back (#244). Creates the file and
+ * parent directories if needed. A file that exists but does not parse is
+ * never overwritten: the caller is told to fix it first.
  */
-export declare function writeLibraryConfig(configPath: string, libraryPath: string, namespace?: string | null, publishConfirm?: boolean): Promise<void>;
+export declare function writeLibraryConfig(configPath: string, libraryPath: string, namespace?: string | null): Promise<void>;
 export {};