kibi-cli 1.0.1 → 2.0.0

package/dist/commands/prove.js

@@ -0,0 +1,470 @@
+import { spawn } from "node:child_process";
+import { mkdir, readFile, rm, writeFile } from "node:fs/promises";
+import path from "node:path";
+import { executeIngestProof } from "../operations/proof/ingest-proof.js";
+import { PROOF_RUNS_DIR, loadProofIntegrations, resolveIntegration, } from "../proof/integrations.js";
+import { convertJUnitXml } from "../proof/producers/junit-adapter.js";
+import { convertTap } from "../proof/producers/tap-adapter.js";
+import { loadEntities } from "../public/operations/discovery-entities.js";
+import { ingestProofSpec } from "../public/operations/specs/proof.js";
+import { readWorkspaceSnapshot } from "../public/operations/workspace-snapshot.js";
+import { PROOF_RUN_VERSION, proofBindingsErrors, proofRunArtifactErrors, } from "../public/proof-protocol.js";
+import { createCliRuntime } from "../runtime/cli-runtime.js";
+/**
+ * Describe which paths moved when a proof snapshot refusal fires, so
+ * consumers can see what kibi thinks changed instead of diffing by hand.
+ * Snapshot-relevant changes come first (receipt-only and ignored edits do
+ * not affect the hash), and the list is capped to keep the error readable.
+ */
+// implements REQ-kibi-proof-evidence-protocol
+export function describeWorkspaceDrift(snapshot) {
+    if (!snapshot.available)
+        return " (workspace snapshot unavailable)";
+    const changes = snapshot.snapshot.changes ?? [];
+    const relevant = changes.filter((change) => change.snapshotRelevant);
+    const pool = relevant.length > 0
+        ? relevant
+        : changes.filter((change) => !change.snapshotRelevant);
+    if (pool.length === 0) {
+        return " (git reported no workspace changes; the hash drift may come from file content that git treats as unchanged)";
+    }
+    const maxPaths = 10;
+    const listed = pool
+        .slice(0, maxPaths)
+        .map((change) => `${change.status.trim() || "M"} ${change.path}`);
+    const more = pool.length - listed.length;
+    return `; changed: ${listed.join(", ")}${more > 0 ? ` (+${more} more)` : ""}`;
+}
+/**
+ * Parse a comma-separated integration selector ("a", "a,b,c") into a set of
+ * trimmed, non-empty ids. Empty selectors yield an empty set; blank items
+ * fail fast instead of silently narrowing the selection.
+ */
+// implements REQ-kibi-proof-evidence-protocol
+export function parseIntegrationSelector(value, flagName) {
+    if (value === undefined || value.trim() === "")
+        return new Set();
+    const ids = new Set();
+    for (const raw of value.split(",")) {
+        const id = raw.trim();
+        if (id === "")
+            throw new Error(`prove: ${flagName} contains an empty integration id`);
+        ids.add(id);
+    }
+    return ids;
+}
+function withId(entity) {
+    if (typeof entity.id !== "string" || entity.id === "")
+        throw new Error("prove: loaded test entity is missing an id");
+    return entity;
+}
+export function testId(test) {
+    return String(test.id);
+}
+function parseContract(test) {
+    const contract = test.proof_contract;
+    if (contract === null ||
+        typeof contract !== "object" ||
+        Array.isArray(contract))
+        return null;
+    return contract;
+}
+async function runChild(commandArgv, cwd, env) {
+    const [command, ...args] = commandArgv;
+    if (!command)
+        throw new Error("prove: integration command argv must be non-empty");
+    return await new Promise((resolve, reject) => {
+        const child = spawn(command, args, {
+            cwd,
+            env,
+            shell: false,
+            stdio: "inherit",
+        });
+        child.once("error", reject);
+        child.once("close", (code) => resolve(code ?? 1));
+    });
+}
+// implements REQ-kibi-proof-evidence-protocol
+export function commandEnvironment(integration, commandArgv, snapshot, workspaceRoot, testIds, outputPath) {
+    return {
+        ...process.env,
+        KIBI_PROOF_RUN: "1",
+        KIBI_PROOF_OUTPUT: outputPath,
+        KIBI_PROOF_SNAPSHOT: snapshot,
+        KIBI_PROOF_COMMAND_ARGV: JSON.stringify(commandArgv),
+        KIBI_PROOF_INTEGRATION: integration.id,
+        KIBI_PROOF_WORKSPACE: workspaceRoot,
+        KIBI_PROOF_TEST_IDS: JSON.stringify(testIds),
+    };
+}
+function collectBindings(tests) {
+    const bindings = [];
+    for (const test of tests) {
+        const raw = test.proof_bindings;
+        if (raw === undefined || raw === null)
+            continue;
+        if (!Array.isArray(raw))
+            continue;
+        const errors = proofBindingsErrors(raw);
+        if (errors.length > 0)
+            throw new Error(`prove: test ${test.id} has invalid proof_bindings: ${errors.join("; ")}`);
+        for (const entry of raw) {
+            const row = entry;
+            bindings.push({
+                symbol_id: String(row.symbol_id),
+                target: String(row.target),
+                ...(row.native_id !== undefined
+                    ? { native_id: String(row.native_id) }
+                    : {}),
+                ...(row.aliases !== undefined
+                    ? { aliases: row.aliases.map(String) }
+                    : {}),
+            });
+        }
+    }
+    return bindings;
+}
+function dedupeObligations(tests) {
+    const seen = new Set();
+    const results = [];
+    for (const test of tests) {
+        const contract = parseContract(test);
+        if (!contract)
+            continue;
+        for (const obligation of contract.required_proofs) {
+            const key = `${obligation.target}\0${obligation.symbol_id}`;
+            if (seen.has(key))
+                continue;
+            seen.add(key);
+            results.push({
+                symbol_id: obligation.symbol_id,
+                target: obligation.target,
+                outcome: "passed",
+                binding: "aggregate_run",
+                attempts: { status: "unavailable" },
+            });
+        }
+    }
+    return results;
+}
+function markAggregateFailure(results) {
+    return results.map((result) => ({ ...result, outcome: "failed" }));
+}
+async function selectTests(context, options) {
+    // Paginated: loading every test entity with full props in one query can
+    // exceed the Prolog output buffer once receipt histories grow.
+    const loadAll = async () => {
+        const pageSize = 25;
+        const all = [];
+        for (let offset = 0;; offset += pageSize) {
+            const page = await loadEntities(context.prolog, {
+                type: "test",
+                limit: pageSize,
+                offset,
+            });
+            all.push(...page);
+            if (page.length < pageSize)
+                return all;
+        }
+    };
+    let candidates = [];
+    if (options.testId) {
+        const found = await loadEntities(context.prolog, {
+            id: options.testId,
+            type: "test",
+        });
+        candidates = found.map(withId);
+    }
+    else if (options.requirement) {
+        const requirementId = options.requirement;
+        const scenarioResult = await context.prolog?.query(`findall([S,T], (kb_relationship(specified_by, '${requirementId}', S), (kb_relationship(verified_by, S, T) ; kb_relationship(validates, T, S)), kb_entity(T, test, _)), Rows)`);
+        const rowsRaw = scenarioResult?.success
+            ? scenarioResult.bindings.Rows
+            : undefined;
+        const ids = new Set();
+        if (typeof rowsRaw === "string") {
+            for (const match of rowsRaw.matchAll(/\[['"]?([^,\]]+)['"]?,['"]?([^,\]]+)['"]?\]/g)) {
+                const test = match[2];
+                if (test)
+                    ids.add(test.trim());
+            }
+        }
+        const directResult = await context.prolog?.query(`findall(T, (kb_relationship(validates, T, '${requirementId}'), kb_entity(T, test, _)), Rows)`);
+        const directRaw = directResult?.success
+            ? directResult.bindings.Rows
+            : undefined;
+        if (typeof directRaw === "string") {
+            for (const match of directRaw.matchAll(/\[?['"]?([A-Za-z0-9_-]+)['"]?\]?/g)) {
+                const candidate = match[1];
+                if (candidate?.startsWith("TEST-"))
+                    ids.add(candidate);
+            }
+        }
+        const all = await loadAll();
+        candidates = all.filter((entity) => ids.has(String(entity.id))).map(withId);
+    }
+    else {
+        candidates = (await loadAll()).map(withId);
+    }
+    const selected = candidates.filter((entity) => parseContract(entity) !== null);
+    const includeIds = parseIntegrationSelector(options.integration, "--integration");
+    const excludeIds = parseIntegrationSelector(options.integrationExcept, "--integration-except");
+    if (includeIds.size === 0 && excludeIds.size === 0)
+        return selected;
+    const filtered = selected.filter((entity) => {
+        const contract = parseContract(entity);
+        if (!contract)
+            return false;
+        if (includeIds.size > 0 && !includeIds.has(contract.integration))
+            return false;
+        if (excludeIds.size > 0 && excludeIds.has(contract.integration))
+            return false;
+        return true;
+    });
+    if (filtered.length === 0 && includeIds.size + excludeIds.size > 0) {
+        const requested = [
+            ...(includeIds.size > 0
+                ? [`integrations: ${[...includeIds].sort().join(", ")}`]
+                : []),
+            ...(excludeIds.size > 0
+                ? [`excluding: ${[...excludeIds].sort().join(", ")}`]
+                : []),
+        ].join("; ");
+        throw new Error(`prove: no proof-bearing tests match the integration selector (${requested})`);
+    }
+    return filtered;
+}
+function summarize(result) {
+    const parts = [`passed ${result.passed}`, `failed ${result.failed}`];
+    if (result.unchanged > 0)
+        parts.push(`unchanged ${result.unchanged}`);
+    return parts.join(", ");
+}
+// implements REQ-kibi-proof-evidence-protocol
+export async function proveCommand(options, deps = {}) {
+    const workspaceRoot = options.workspaceRoot ?? process.cwd();
+    const ingestProof = deps.ingestProof ?? executeIngestProof;
+    const runtime = deps.runtime ??
+        createCliRuntime(options.workspaceRoot === undefined ? {} : { workspaceRoot });
+    const context = await runtime.open(ingestProofSpec, {
+        ...(options.workspaceRoot === undefined ? {} : { workspaceRoot }),
+    });
+    let completed = false;
+    try {
+        const integrations = loadProofIntegrations(context.workspaceRoot);
+        if (!integrations.available)
+            throw new Error(`prove: ${integrations.error}`);
+        const selected = await selectTests(context, options);
+        if (selected.length === 0) {
+            process.stdout.write(`${JSON.stringify({ proved: 0, failed: 0, message: "no proof-bearing tests selected" })}\n`);
+            completed = true;
+            return { exitCode: 0 };
+        }
+        const before = await readWorkspaceSnapshot(context);
+        if (!before.available)
+            throw new Error(`prove: ${before.error}`);
+        const snapshot = before.snapshot.hash;
+        // Packed contracts run in separate processes; one shared packed-tarball
+        // cache area per campaign snapshot replaces dozens of repeated packs and
+        // installs with a single population. The snapshot hash is the provenance
+        // key: different workspace state never sees another campaign's artifacts.
+        process.env.KIBI_E2E_PACK_CACHE_KEY ??= snapshot;
+        const groups = new Map();
+        for (const test of selected) {
+            const contract = parseContract(test);
+            if (!contract)
+                continue;
+            const list = groups.get(contract.integration) ?? [];
+            list.push(test);
+            groups.set(contract.integration, list);
+        }
+        const runsDir = path.join(context.workspaceRoot, PROOF_RUNS_DIR);
+        await mkdir(runsDir, { recursive: true });
+        const ingestResults = [];
+        const failures = [];
+        for (const [integrationId, tests] of groups) {
+            const integration = resolveIntegration(integrations.integrations, integrationId);
+            if (!integration) {
+                failures.push(`integration '${integrationId}' (required by ${tests.map((t) => t.id).join(", ")}) is not configured in .kb/proof/integrations.json`);
+                continue;
+            }
+            const commandArgv = [...integration.command];
+            const artifactPath = path.resolve(context.workspaceRoot, integration.artifact ??
+                path.join(PROOF_RUNS_DIR, `${integrationId}.json`));
+            await mkdir(path.dirname(artifactPath), { recursive: true });
+            await rm(artifactPath, { force: true });
+            const env = commandEnvironment(integration, commandArgv, snapshot, context.workspaceRoot, tests.map((test) => String(test.id)), artifactPath);
+            const startedAt = new Date().toISOString();
+            let exitCode;
+            try {
+                exitCode = await runChild(commandArgv, context.workspaceRoot, env);
+            }
+            catch (error) {
+                failures.push(`integration '${integrationId}' failed to start: ${error instanceof Error ? error.message : String(error)}`);
+                continue;
+            }
+            const finishedAt = new Date().toISOString();
+            let artifact;
+            try {
+                artifact = await buildArtifact({
+                    integration,
+                    commandArgv,
+                    exitCode,
+                    startedAt,
+                    finishedAt,
+                    artifactPath,
+                    snapshot,
+                    tests,
+                });
+            }
+            catch (error) {
+                failures.push(`integration '${integrationId}': ${error instanceof Error ? error.message : String(error)}`);
+                continue;
+            }
+            const artifactErrors = proofRunArtifactErrors(artifact);
+            if (artifactErrors.length > 0) {
+                failures.push(`integration '${integrationId}' produced an invalid kibi.proof-run.v1 artifact: ${artifactErrors.join("; ")}`);
+                continue;
+            }
+            await mkdir(path.dirname(artifactPath), { recursive: true });
+            await writeFile(artifactPath, `${JSON.stringify(artifact, null, 2)}\n`, "utf8");
+            const afterRun = await readWorkspaceSnapshot(context);
+            if (!afterRun.available || afterRun.snapshot.hash !== snapshot) {
+                failures.push(`integration '${integrationId}' changed the tracked workspace during proof execution; proof is bound to snapshot ${snapshot}${describeWorkspaceDrift(afterRun)}`);
+                continue;
+            }
+            const ingested = await ingestProof({
+                snapshot,
+                artifact: artifact,
+                testIds: tests.map((test) => String(test.id)),
+            }, context);
+            ingestResults.push(ingested.structuredContent);
+            const afterIngest = await readWorkspaceSnapshot(context);
+            if (!afterIngest.available || afterIngest.snapshot.hash !== snapshot) {
+                failures.push(`the tracked workspace changed while receipts were applied; re-run kibi prove${describeWorkspaceDrift(afterIngest)}`);
+            }
+        }
+        const passed = ingestResults.reduce((sum, result) => sum + result.passed, 0);
+        const failed = ingestResults.reduce((sum, result) => sum + result.failed, 0);
+        const unchanged = ingestResults.reduce((sum, result) => sum + result.unchanged, 0);
+        const summary = {
+            proved: passed,
+            failed,
+            unchanged,
+            runs: ingestResults.map((result) => ({
+                integration: result.integration,
+                summary: summarize(result),
+                results: result.results,
+            })),
+            ...(failures.length > 0 ? { failures } : {}),
+        };
+        process.stdout.write(`${JSON.stringify(summary)}\n`);
+        completed = true;
+        await runtime.afterSuccess(ingestProofSpec, context);
+        return { exitCode: failures.length > 0 || failed > 0 ? 1 : 0 };
+    }
+    finally {
+        await runtime.close(context, completed
+            ? { status: "success", result: 0 }
+            : { status: "error", error: 1 });
+    }
+}
+async function buildArtifact(input) {
+    const { integration, commandArgv, exitCode, startedAt, finishedAt, artifactPath, snapshot, tests, } = input;
+    const run = (outcome) => ({
+        outcome,
+        exit_code: exitCode,
+        started_at: startedAt,
+        finished_at: finishedAt,
+    });
+    if (integration.producer === "command") {
+        const results = dedupeObligations(tests);
+        return {
+            version: PROOF_RUN_VERSION,
+            producer: {
+                name: "kibi-command-producer",
+                ...(integration.producer_version !== undefined
+                    ? { version: integration.producer_version }
+                    : {}),
+            },
+            integration: integration.id,
+            command_argv: [...commandArgv],
+            code_snapshot: snapshot,
+            environment: {
+                os: process.platform,
+                arch: process.arch,
+                runtime: { name: "node", version: process.version },
+            },
+            run: run(exitCode === 0 ? "passed" : "failed"),
+            proof_results: exitCode === 0 ? results : markAggregateFailure(results),
+        };
+    }
+    if (integration.producer === "junit" || integration.producer === "tap") {
+        const nativePath = integration.artifact;
+        if (!nativePath)
+            throw new Error(`producer '${integration.producer}' requires an artifact path in .kb/proof/integrations.json`);
+        let native;
+        try {
+            native = await readFile(path.resolve(context_path(nativePath)), "utf8");
+        }
+        catch {
+            throw new Error(`producer '${integration.producer}' did not produce its native report at ${nativePath}`);
+        }
+        const bindings = collectBindings(tests);
+        const conversion = integration.producer === "junit"
+            ? convertJUnitXml(native, bindings)
+            : convertTap(native, bindings);
+        if (conversion.fatal) {
+            throw new Error(`producer '${integration.producer}' rejected its native report${conversion.diagnostics.length > 0 ? `: ${conversion.diagnostics.join("; ")}` : ""}`);
+        }
+        if (conversion.results.length === 0)
+            throw new Error(`producer '${integration.producer}' produced no bound proof results${conversion.diagnostics.length > 0 ? `: ${conversion.diagnostics.join("; ")}` : ""}`);
+        return {
+            version: PROOF_RUN_VERSION,
+            producer: {
+                name: `kibi-${integration.producer}-adapter`,
+                ...(integration.producer_version !== undefined
+                    ? { version: integration.producer_version }
+                    : {}),
+            },
+            integration: integration.id,
+            command_argv: [...commandArgv],
+            code_snapshot: snapshot,
+            environment: {
+                os: process.platform,
+                arch: process.arch,
+                runtime: { name: "node", version: process.version },
+            },
+            run: run(conversion.results.every((result) => result.outcome === "passed")
+                ? "passed"
+                : "failed"),
+            proof_results: conversion.results,
+            ...(conversion.diagnostics.length > 0
+                ? { diagnostics: conversion.diagnostics }
+                : {}),
+        };
+    }
+    // Self-emitting producers (playwright and custom): read the emitted
+    // kibi.proof-run.v1 artifact and enforce the process outcome.
+    let parsed;
+    try {
+        parsed = JSON.parse(await readFile(artifactPath, "utf8"));
+    }
+    catch {
+        throw new Error(`producer '${integration.producer}' did not emit a readable kibi.proof-run.v1 artifact at ${artifactPath}`);
+    }
+    const artifact = parsed;
+    const runRecord = parsed.run;
+    const reportedOutcome = runRecord?.outcome;
+    if (exitCode !== 0) {
+        if (reportedOutcome === "passed") {
+            throw new Error(`producer '${integration.producer}' reported run.outcome 'passed' but the process exited with code ${exitCode}`);
+        }
+    }
+    return artifact;
+}
+function context_path(nativePath) {
+    return path.isAbsolute(nativePath)
+        ? nativePath
+        : path.join(process.cwd(), nativePath);
+}

package/dist/commands/report.js

@@ -163,7 +163,7 @@ export async function reportCommand(options, deps = {}) {
     const hasContradiction = coverage.requirements.rows.some((row) => Array.isArray(row.proofGaps) &&
         row.proofGaps.includes("blocking_contradiction"));
     const snapshotStale = coverage.requirements.meta?.dirty === true ||
-        coverage.requirements.meta?.verificationSnapshotDirty === true;
+        coverage.requirements.meta?.proofSnapshotDirty === true;
     const badgeMessage = currentRequirements === 0 ? "no requirements" : `${proofPercent}% proven`;
     const badgeColor = currentRequirements === 0
         ? KIBI_BRAND.rail

package/dist/commands/sync/discovery.d.ts

@@ -18,6 +18,9 @@ export type PendingSourceReceiptSnapshot = Readonly<{
     afterHash: string;
     rawHash: string;
 }>;
+export declare function isFsEnoent(error: unknown): boolean;
+export declare function readTextOrEnoent(absolute: string): string | null;
+export declare function unlinkOrEnoent(absolute: string): boolean;
 export declare function clearRecoveredPendingSourceReceipts(cwd: string, receipts: readonly PendingSourceReceiptSnapshot[]): void;
 export declare function normalizeMarkdownPath(pattern: string | undefined): string | null;
 export declare function discoverSourceFiles(cwd: string, options?: DiscoveryOptions): Promise<{

package/dist/commands/sync/discovery.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"discovery.d.ts","sourceRoot":"","sources":["../../../src/commands/sync/discovery.ts"],"names":[],"mappings":"AAiCA,MAAM,MAAM,gBAAgB,GAAG,QAAQ,CAAC;IACtC,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,4BAA4B,CAAC,EAAE,OAAO,CAAC;IACvC,+EAA+E;IAC/E,6BAA6B,CAAC,EAAE,OAAO,CAAC;CACzC,CAAC,CAAC;AAEH;;;;;;;GAOG;AACH,MAAM,MAAM,4BAA4B,GAAG,QAAQ,CAAC;IAClD,WAAW,EAAE,MAAM,CAAC;IACpB,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,MAAM,CAAC;CACjB,CAAC,CAAC;AAyFH,wBAAgB,mCAAmC,CACjD,GAAG,EAAE,MAAM,EACX,QAAQ,EAAE,SAAS,4BAA4B,EAAE,GAChD,IAAI,CA2EN;AAsBD,wBAAgB,qBAAqB,CACnC,OAAO,EAAE,MAAM,GAAG,SAAS,GAC1B,MAAM,GAAG,IAAI,CAIf;AAED,wBAAsB,mBAAmB,CACvC,GAAG,EAAE,MAAM,EACX,OAAO,GAAE,gBAAqB,GAC7B,OAAO,CAAC;IACT,aAAa,EAAE,MAAM,EAAE,CAAC;IACxB,aAAa,EAAE,MAAM,EAAE,CAAC;IACxB,gBAAgB,EAAE,MAAM,CAAC;IACzB,4BAA4B,EAAE,4BAA4B,EAAE,CAAC;CAC9D,CAAC,CA4FD"}
+{"version":3,"file":"discovery.d.ts","sourceRoot":"","sources":["../../../src/commands/sync/discovery.ts"],"names":[],"mappings":"AAkCA,MAAM,MAAM,gBAAgB,GAAG,QAAQ,CAAC;IACtC,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,4BAA4B,CAAC,EAAE,OAAO,CAAC;IACvC,+EAA+E;IAC/E,6BAA6B,CAAC,EAAE,OAAO,CAAC;CACzC,CAAC,CAAC;AAEH;;;;;;;GAOG;AACH,MAAM,MAAM,4BAA4B,GAAG,QAAQ,CAAC;IAClD,WAAW,EAAE,MAAM,CAAC;IACpB,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,MAAM,CAAC;CACjB,CAAC,CAAC;AAyFH,wBAAgB,UAAU,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAOlD;AAED,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAShE;AAED,wBAAgB,cAAc,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAUxD;AAED,wBAAgB,mCAAmC,CACjD,GAAG,EAAE,MAAM,EACX,QAAQ,EAAE,SAAS,4BAA4B,EAAE,GAChD,IAAI,CA6CN;AAsBD,wBAAgB,qBAAqB,CACnC,OAAO,EAAE,MAAM,GAAG,SAAS,GAC1B,MAAM,GAAG,IAAI,CAIf;AAED,wBAAsB,mBAAmB,CACvC,GAAG,EAAE,MAAM,EACX,OAAO,GAAE,gBAAqB,GAC7B,OAAO,CAAC;IACT,aAAa,EAAE,MAAM,EAAE,CAAC;IACxB,aAAa,EAAE,MAAM,EAAE,CAAC;IACxB,gBAAgB,EAAE,MAAM,CAAC;IACzB,4BAA4B,EAAE,4BAA4B,EAAE,CAAC;CAC9D,CAAC,CA+FD"}

package/dist/commands/sync/discovery.js

@@ -17,6 +17,7 @@
  */
 import { execFile } from "node:child_process";
 import { createHash } from "node:crypto";
+import * as fs from "node:fs";
 import { existsSync, readFileSync, readdirSync, unlinkSync } from "node:fs";
 import * as path from "node:path";
 import { promisify } from "node:util";
@@ -89,6 +90,33 @@ function pendingSourcePaths(cwd, recoverMissing) {
     }
     return { paths, recoveredReceipts };
 }
+export function isFsEnoent(error) {
+    return (error !== null &&
+        typeof error === "object" &&
+        "code" in error &&
+        error.code === "ENOENT");
+}
+export function readTextOrEnoent(absolute) {
+    try {
+        return fs.readFileSync(absolute, "utf8");
+    }
+    catch (error) {
+        if (isFsEnoent(error))
+            return null;
+        throw new Error(`Failed to inspect pending source receipt for ${absolute}: ${error instanceof Error ? error.message : String(error)}`);
+    }
+}
+export function unlinkOrEnoent(absolute) {
+    try {
+        fs.unlinkSync(absolute);
+        return true;
+    }
+    catch (error) {
+        if (isFsEnoent(error))
+            return false;
+        throw new Error(`Failed to retire pending source receipt for ${absolute}: ${error instanceof Error ? error.message : String(error)}`);
+    }
+}
 export function clearRecoveredPendingSourceReceipts(cwd, receipts) {
     const root = path.resolve(cwd, ".kb", "recovery", "pending-sources");
     for (const receipt of receipts) {
@@ -103,19 +131,9 @@ export function clearRecoveredPendingSourceReceipts(cwd, receipts) {
         // because it has the same receipt filename.  Failing closed here is
         // important: publication may have completed, but recovery must not claim
         // that pending intent was retired when a newer intent remains.
-        let raw;
-        try {
-            raw = readFileSync(absolute, "utf8");
-        }
-        catch (error) {
-            if (error !== null &&
-                typeof error === "object" &&
-                "code" in error &&
-                error.code === "ENOENT") {
-                continue;
-            }
-            throw new Error(`Failed to inspect pending source receipt for ${receipt.path}: ${error instanceof Error ? error.message : String(error)}`);
-        }
+        const raw = readTextOrEnoent(absolute);
+        if (raw === null)
+            continue;
         const rawHash = createHash("sha256").update(raw).digest("hex");
         if (rawHash !== receipt.rawHash) {
             throw new Error(`Pending source receipt changed during recovery for ${receipt.path}; refusing to retire newer receipt`);
@@ -131,20 +149,7 @@ export function clearRecoveredPendingSourceReceipts(cwd, receipts) {
             current.afterHash !== receipt.afterHash) {
             throw new Error(`Pending source receipt changed during recovery for ${receipt.path}; refusing to retire newer receipt`);
         }
-        try {
-            unlinkSync(absolute);
-        }
-        catch (error) {
-            if (error !== null &&
-                typeof error === "object" &&
-                "code" in error &&
-                error.code === "ENOENT") {
-                // Another recovery or source publication may have consumed it
-                // already; cleanup is idempotent for that case.
-                continue;
-            }
-            throw new Error(`Failed to retire pending source receipt for ${receipt.path}: ${error instanceof Error ? error.message : String(error)}`);
-        }
+        unlinkOrEnoent(absolute);
     }
 }
 function filterTracked(cwd, files, tracked, pending) {
@@ -183,11 +188,14 @@ export async function discoverSourceFiles(cwd, options = {}) {
         absolute: true,
         ignore: [...MARKDOWN_DISCOVERY_IGNORE],
     });
-    let entityMarkdownFiles = markdownFiles.filter((file) => !file.endsWith("/README.md"));
+    let entityMarkdownFiles = (Array.isArray(markdownFiles) ? markdownFiles : []).filter((file) => !file.endsWith("/README.md"));
     let manifestFiles = await fg(CANONICAL_ENTITY_PATHS.symbols, {
         cwd,
         absolute: true,
     });
+    if (!Array.isArray(manifestFiles)) {
+        manifestFiles = [];
+    }
     const recoveredPendingReceiptPaths = [];
     if (options.trackedOnly) {
         const tracked = await gitTrackedPaths(cwd);

package/dist/commands/sync/manifest.d.ts

@@ -16,7 +16,7 @@ interface ManifestDeps {
     writeCoordinateArtifact: typeof writeCoordinateArtifact;
     resolveSymbolsManifestPaths: typeof resolveSymbolsManifestPaths;
 }
-export declare const SYMBOLS_MANIFEST_COMMENT_BLOCK = "# symbols.yaml\n# AUTHORED fields (edit freely):\n#   id, title, sourceFile, links, status, tags, owner, priority\n# Generated coordinates are stored separately in symbol-coordinates.yaml.\n# Run `kibi sync --refresh-symbol-coordinates` to refresh them.\n";
+export declare const SYMBOLS_MANIFEST_COMMENT_BLOCK: string;
 /**
  * Coarse symbol anchors for which AST per-declaration coordinates are not
  * expected.

package/dist/commands/sync/manifest.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"manifest.d.ts","sourceRoot":"","sources":["../../../src/commands/sync/manifest.ts"],"names":[],"mappings":"AAkBA,OAAO,EACL,UAAU,EACV,YAAY,EACZ,UAAU,EACV,UAAU,EACV,aAAa,EACd,MAAM,SAAS,CAAC;AAEjB,OAAO,EAAE,IAAI,IAAI,QAAQ,EAAE,IAAI,IAAI,SAAS,EAAE,MAAM,SAAS,CAAC;AAC9D,OAAO,EAML,uBAAuB,EACxB,MAAM,wCAAwC,CAAC;AAChD,OAAO,EACL,KAAK,mBAAmB,EACxB,uBAAuB,EACxB,MAAM,yCAAyC,CAAC;AACjD,OAAO,EACL,0BAA0B,EAE3B,MAAM,oCAAoC,CAAC;AAC5C,OAAO,EAAE,2BAA2B,EAAE,MAAM,+BAA+B,CAAC;AAE5E,UAAU,YAAY;IACpB,QAAQ,EAAE,OAAO,QAAQ,CAAC;IAC1B,uBAAuB,EAAE,OAAO,uBAAuB,CAAC;IACxD,UAAU,EAAE,OAAO,UAAU,CAAC;IAC9B,SAAS,EAAE,OAAO,SAAS,CAAC;IAC5B,YAAY,EAAE,OAAO,YAAY,CAAC;IAClC,UAAU,EAAE,OAAO,UAAU,CAAC;IAC9B,UAAU,EAAE,OAAO,UAAU,CAAC;IAC9B,aAAa,EAAE,OAAO,aAAa,CAAC;IACpC,uBAAuB,EAAE,OAAO,uBAAuB,CAAC;IACxD,2BAA2B,EAAE,OAAO,2BAA2B,CAAC;CACjE;AAkBD,eAAO,MAAM,8BAA8B,oQAK1C,CAAC;AAwBF;;;;;;;;;GASG;AACH,OAAO,EAAE,0BAA0B,EAAE,CAAC;AAEtC,wBAAgB,yBAAyB,CAAC,KAAK,EAAE,mBAAmB,GAAG,OAAO,CAG7E;AAsGD,wBAAsB,0BAA0B,CAE9C,YAAY,EAAE,MAAM,EACpB,aAAa,EAAE,MAAM,EACrB,IAAI,CAAC,EAAE,OAAO,CAAC,YAAY,CAAC,GAAG;IAAE,wBAAwB,CAAC,EAAE,OAAO,CAAA;CAAE,GACpE,OAAO,CAAC,IAAI,CAAC,CA0Kf;AAED,wBAAgB,0BAA0B,CAExC,KAAK,EAAE,mBAAmB,GACzB,OAAO,CAOT;AAED,wBAAgB,8BAA8B,CAE5C,UAAU,EAAE,MAAM,GAAG,SAAS,EAC9B,aAAa,EAAE,MAAM,EACrB,IAAI,CAAC,EAAE,OAAO,CAAC,YAAY,CAAC,GAC3B,OAAO,CAUT"}
+{"version":3,"file":"manifest.d.ts","sourceRoot":"","sources":["../../../src/commands/sync/manifest.ts"],"names":[],"mappings":"AAkBA,OAAO,EACL,UAAU,EACV,YAAY,EACZ,UAAU,EACV,UAAU,EACV,aAAa,EACd,MAAM,SAAS,CAAC;AAEjB,OAAO,EAAE,IAAI,IAAI,QAAQ,EAAE,IAAI,IAAI,SAAS,EAAE,MAAM,SAAS,CAAC;AAC9D,OAAO,EAML,uBAAuB,EACxB,MAAM,wCAAwC,CAAC;AAChD,OAAO,EACL,KAAK,mBAAmB,EACxB,uBAAuB,EACxB,MAAM,yCAAyC,CAAC;AACjD,OAAO,EACL,0BAA0B,EAG3B,MAAM,oCAAoC,CAAC;AAC5C,OAAO,EAAE,2BAA2B,EAAE,MAAM,+BAA+B,CAAC;AAE5E,UAAU,YAAY;IACpB,QAAQ,EAAE,OAAO,QAAQ,CAAC;IAC1B,uBAAuB,EAAE,OAAO,uBAAuB,CAAC;IACxD,UAAU,EAAE,OAAO,UAAU,CAAC;IAC9B,SAAS,EAAE,OAAO,SAAS,CAAC;IAC5B,YAAY,EAAE,OAAO,YAAY,CAAC;IAClC,UAAU,EAAE,OAAO,UAAU,CAAC;IAC9B,UAAU,EAAE,OAAO,UAAU,CAAC;IAC9B,aAAa,EAAE,OAAO,aAAa,CAAC;IACpC,uBAAuB,EAAE,OAAO,uBAAuB,CAAC;IACxD,2BAA2B,EAAE,OAAO,2BAA2B,CAAC;CACjE;AAkBD,eAAO,MAAM,8BAA8B,QAc1C,CAAC;AAaF;;;;;;;;;GASG;AACH,OAAO,EAAE,0BAA0B,EAAE,CAAC;AAEtC,wBAAgB,yBAAyB,CAAC,KAAK,EAAE,mBAAmB,GAAG,OAAO,CAG7E;AAoHD,wBAAsB,0BAA0B,CAE9C,YAAY,EAAE,MAAM,EACpB,aAAa,EAAE,MAAM,EACrB,IAAI,CAAC,EAAE,OAAO,CAAC,YAAY,CAAC,GAAG;IAAE,wBAAwB,CAAC,EAAE,OAAO,CAAA;CAAE,GACpE,OAAO,CAAC,IAAI,CAAC,CAqMf;AAED,wBAAgB,0BAA0B,CAExC,KAAK,EAAE,mBAAmB,GACzB,OAAO,CAOT;AAED,wBAAgB,8BAA8B,CAE5C,UAAU,EAAE,MAAM,GAAG,SAAS,EAC9B,aAAa,EAAE,MAAM,EACrB,IAAI,CAAC,EAAE,OAAO,CAAC,YAAY,CAAC,GAC3B,OAAO,CAUT"}