@cairn-tool/cairn 2.0.1 → 3.0.0

package/dist/agent/verify/index.js

@@ -0,0 +1,331 @@
+import fs from "node:fs";
+import path from "node:path";
+import { loadBundle } from "../parser.js";
+import { renderBundle } from "../render.js";
+import { installKey, readInstallDocument, planInstall } from "../install/index.js";
+import { CONVERSION_REPORT, diffOutput } from "../output.js";
+import { PROFILE_SCHEMA_VERSION, compareSemver } from "../targets/schema.js";
+import { profileFor } from "../targets/index.js";
+import { packageName, packageVersion } from "../../version.js";
+import { diffTree, treeMatches, walkRootsFor } from "./compare.js";
+function error(code, message, extra = {}) {
+    return { code, severity: "error", message, quality: "exact", ...extra };
+}
+function notice(code, message, extra = {}) {
+    return { code, severity: "notice", message, quality: "exact", ...extra };
+}
+/**
+ * Evaluates one bound with a caller-supplied ordering.
+ *
+ * Documentation revisions are ISO dates compared lexicographically, exactly as
+ * `agent doctor` already compares them; CLI versions go through
+ * {@link compareSemver}.
+ */
+function satisfies(actual, declared, compare) {
+    if (declared.exact !== undefined)
+        return compare(actual, declared.exact) === 0;
+    if (declared.min !== undefined && compare(actual, declared.min) < 0)
+        return false;
+    if (declared.max !== undefined && compare(actual, declared.max) > 0)
+        return false;
+    return true;
+}
+function lexical(a, b) {
+    return a < b ? -1 : a > b ? 1 : 0;
+}
+function describe(bound) {
+    if (bound.exact !== undefined)
+        return `exactly ${bound.exact}`;
+    return [
+        bound.min !== undefined ? `>= ${bound.min}` : undefined,
+        bound.max !== undefined ? `<= ${bound.max}` : undefined,
+    ]
+        .filter(Boolean)
+        .join(" and ");
+}
+export function evaluatePins(config, targets) {
+    const diagnostics = [];
+    const { pins } = config;
+    const cli = {
+        declared: pins.cli ?? null,
+        actual: packageVersion,
+        status: !pins.cli
+            ? "unpinned"
+            : satisfies(packageVersion, pins.cli, compareSemver)
+                ? "satisfied"
+                : "violated",
+    };
+    if (cli.status === "violated" && pins.cli)
+        diagnostics.push(error("AB420", `Running ${packageName} ${packageVersion} does not satisfy the pinned range (${describe(pins.cli)})`, {
+            remediation: "Install a cairn matching the pin, or update the pin and regenerate the trees in the same commit.",
+        }));
+    const schema = {
+        declared: pins.profileSchemaVersion ?? null,
+        actual: PROFILE_SCHEMA_VERSION,
+        status: !pins.profileSchemaVersion
+            ? "unpinned"
+            : pins.profileSchemaVersion === PROFILE_SCHEMA_VERSION
+                ? "satisfied"
+                : "violated",
+    };
+    if (schema.status === "violated")
+        diagnostics.push(error("AB421", `Target profile schema version is ${PROFILE_SCHEMA_VERSION}, but ${pins.profileSchemaVersion} is pinned`, { remediation: "Update the pin and regenerate the trees in the same commit." }));
+    const targetReports = [];
+    for (const target of targets) {
+        const declared = pins.targets[target];
+        const actual = profileFor(target).host.documentationRevision;
+        const status = !declared
+            ? "unpinned"
+            : satisfies(actual, declared, lexical)
+                ? "satisfied"
+                : "violated";
+        targetReports.push({ target, declared: declared ?? null, actual, status });
+        if (status === "violated" && declared)
+            diagnostics.push(error("AB422", `The ${target} target profile revision is ${actual}, which does not satisfy the pinned range (${describe(declared)})`, {
+                target,
+                remediation: "Update the pin and regenerate the trees in the same commit.",
+            }));
+    }
+    return { report: { cli, profileSchemaVersion: schema, targets: targetReports }, diagnostics };
+}
+function readConversionProvenance(destination) {
+    const file = path.join(destination, CONVERSION_REPORT);
+    if (!fs.existsSync(file))
+        return undefined;
+    try {
+        const parsed = JSON.parse(fs.readFileSync(file, "utf8"));
+        return {
+            source: CONVERSION_REPORT,
+            generator: parsed.generator ?? null,
+            profileSchemaVersion: parsed.profileSchemaVersion ?? null,
+            status: "matching",
+        };
+    }
+    catch {
+        return {
+            source: CONVERSION_REPORT,
+            generator: null,
+            profileSchemaVersion: null,
+            status: "malformed",
+        };
+    }
+}
+function provenanceOf(manifest) {
+    return {
+        source: ".cairn-install.json",
+        generator: manifest.generator,
+        // An install manifest records no profile schema version. Reported as null
+        // rather than invented, so a consumer can tell "not recorded" from "2".
+        profileSchemaVersion: null,
+        status: "matching",
+    };
+}
+/**
+ * A recorded version this build cannot parse counts as older rather than
+ * throwing: provenance is corroboration, and never the verdict.
+ */
+function isNewer(recorded) {
+    try {
+        return compareSemver(recorded, packageVersion) > 0;
+    }
+    catch {
+        return false;
+    }
+}
+function gradeProvenance(provenance) {
+    if (provenance.status === "malformed" || !provenance.generator)
+        return provenance;
+    const recorded = provenance.generator.version;
+    if (recorded === packageVersion)
+        return provenance;
+    return { ...provenance, status: isNewer(recorded) ? "newer" : "older" };
+}
+function verifyEntry(entry) {
+    const diagnostics = [];
+    const base = {
+        name: entry.name,
+        bundle: entry.bundle,
+        target: entry.target,
+        profile: entry.profile,
+        scope: entry.scope,
+        layout: entry.layout,
+        destination: entry.destination,
+        mode: entry.unmanaged,
+    };
+    if (!fs.existsSync(entry.destination) || !fs.statSync(entry.destination).isDirectory()) {
+        diagnostics.push(error("AB423", `Destination does not exist or is not a directory: ${entry.destination}`, {
+            target: entry.target,
+            profile: entry.profile,
+            path: entry.destination,
+            remediation: "Generate the tree, or remove the entry from the verify configuration.",
+        }));
+        return {
+            report: {
+                ...base,
+                expected: 0,
+                missing: [],
+                changed: [],
+                orphaned: [],
+                unmanaged: [],
+                ok: false,
+            },
+            diagnostics,
+        };
+    }
+    const bundle = loadBundle(entry.bundle);
+    // A conversion root keeps the `<target>/<profile>` prefix the renderer emits,
+    // so it is the one layout `diffOutput` describes and is reused unchanged.
+    if (entry.layout === "conversion") {
+        const rendered = renderBundle(bundle, [entry.target], [entry.profile]);
+        diagnostics.push(...rendered.diagnostics);
+        const diff = diffOutput(entry.destination, rendered.artifacts, [entry.target], [entry.profile]);
+        const provenance = readConversionProvenance(entry.destination);
+        const report = {
+            ...base,
+            expected: rendered.artifacts.length,
+            missing: diff.missing,
+            changed: diff.changed,
+            orphaned: [],
+            unmanaged: entry.unmanaged === "strict" ? diff.unmanaged : [],
+            ...(provenance ? { provenance: gradeProvenance(provenance) } : {}),
+            ok: false,
+        };
+        return { report: finish(report, diagnostics, entry), diagnostics };
+    }
+    const plan = planInstall(bundle, entry.target, {
+        scope: entry.scope,
+        into: entry.destination,
+        profile: entry.profile,
+        // The destination is expected to be occupied — that is the whole point —
+        // so the occupancy check must not turn into an AB801 error here.
+        force: true,
+    });
+    diagnostics.push(...plan.diagnostics.filter((item) => item.code !== "AB802"));
+    const prior = readInstallDocument(plan.destination || entry.destination);
+    if (prior === "malformed")
+        diagnostics.push(error("AB806", `Install manifest at ${entry.destination} is malformed`, {
+            target: entry.target,
+            path: entry.destination,
+            remediation: "Remove it and reinstall, or repair it by hand.",
+        }));
+    // A destination may record several installs. The orphan source is *this*
+    // entry's record alone — a sibling's files are not this bundle's orphans —
+    // while the strict walk's allowlist is the union of every record, or a
+    // sibling's files would all report as unmanaged.
+    const records = prior === "missing" || prior === "malformed" ? [] : prior.installs;
+    const record = records.find((item) => installKey(item) ===
+        installKey({
+            bundle: { name: bundle.name },
+            target: entry.target,
+            profile: plan.profile,
+            scope: entry.scope,
+        }));
+    const inventory = record?.files.map((file) => file.path);
+    const managedPaths = records.length
+        ? [...new Set(records.flatMap((item) => item.files.map((file) => file.path)))]
+        : undefined;
+    if (!inventory && entry.unmanaged !== "off")
+        diagnostics.push(notice("AB426", `No install of '${bundle.name}' recorded at ${entry.destination}; files this bundle no longer renders cannot be detected`, {
+            target: entry.target,
+            path: entry.destination,
+            remediation: "Reinstall so the inventory is recorded.",
+        }));
+    const expectedPaths = plan.artifacts.map((artifact) => artifact.path);
+    const diff = diffTree(plan.destination || entry.destination, plan.artifacts, {
+        unmanaged: entry.unmanaged,
+        priorInventory: inventory,
+        ...(managedPaths ? { managedPaths } : {}),
+        walkRoots: entry.unmanaged === "strict"
+            ? walkRootsFor(entry.target, plan.profile, expectedPaths)
+            : undefined,
+    });
+    const provenance = prior !== "missing" && prior !== "malformed" ? gradeProvenance(provenanceOf(prior)) : undefined;
+    const report = {
+        ...base,
+        profile: plan.profile,
+        layout: entry.layout,
+        expected: plan.artifacts.length,
+        missing: diff.missing,
+        changed: diff.changed,
+        orphaned: diff.orphaned,
+        unmanaged: diff.unmanaged,
+        ...(provenance ? { provenance } : {}),
+        ok: false,
+    };
+    return { report: finish(report, diagnostics, entry), diagnostics };
+}
+/** Maps a comparison into findings and decides the entry's own verdict. */
+function finish(report, diagnostics, entry) {
+    const where = { target: entry.target, profile: report.profile };
+    for (const missing of report.missing)
+        diagnostics.push(error("AB402", `Generated output is missing '${missing}'`, {
+            ...where,
+            path: missing,
+            remediation: "Regenerate the tree from the bundle.",
+        }));
+    for (const changed of report.changed)
+        diagnostics.push(error("AB402", `Generated output differs from the bundle at '${changed}'`, {
+            ...where,
+            path: changed,
+            remediation: "Regenerate the tree; edit the bundle rather than the generated tree.",
+        }));
+    for (const orphaned of report.orphaned)
+        diagnostics.push(error("AB424", `'${orphaned}' was generated previously but is no longer rendered`, {
+            ...where,
+            path: orphaned,
+            remediation: "Delete the file, or restore the component to the bundle.",
+        }));
+    for (const unmanaged of report.unmanaged)
+        diagnostics.push({
+            code: "AB403",
+            severity: "warning",
+            quality: "exact",
+            message: `Unmanaged file in the generated tree: '${unmanaged}'`,
+            ...where,
+            path: unmanaged,
+        });
+    if (report.provenance && report.provenance.status !== "matching" && report.provenance.generator)
+        diagnostics.push(notice("AB425", `The tree records generator ${report.provenance.generator.version}, but ${packageVersion} is verifying it`, { ...where, path: report.destination }));
+    return {
+        ...report,
+        ok: !report.missing.length &&
+            !report.changed.length &&
+            !report.orphaned.length &&
+            !report.unmanaged.length,
+    };
+}
+export function runVerify(config) {
+    const diagnostics = [];
+    const targets = [...new Set(config.entries.map((entry) => entry.target))];
+    const pins = evaluatePins(config, targets);
+    diagnostics.push(...pins.diagnostics);
+    const entries = [];
+    for (const entry of config.entries) {
+        const result = verifyEntry(entry);
+        entries.push(result.report);
+        diagnostics.push(...result.diagnostics);
+    }
+    const counts = {
+        entries: entries.length,
+        ok: entries.filter((entry) => entry.ok).length,
+        missing: entries.reduce((total, entry) => total + entry.missing.length, 0),
+        changed: entries.reduce((total, entry) => total + entry.changed.length, 0),
+        orphaned: entries.reduce((total, entry) => total + entry.orphaned.length, 0),
+        unmanaged: entries.reduce((total, entry) => total + entry.unmanaged.length, 0),
+    };
+    return {
+        report: {
+            config: { path: config.file, entries: config.entries.length },
+            generator: { name: packageName, version: packageVersion },
+            profileSchemaVersion: PROFILE_SCHEMA_VERSION,
+            pins: pins.report,
+            entries,
+            counts,
+        },
+        diagnostics,
+        targets,
+        profiles: [...new Set(entries.map((entry) => entry.profile))],
+    };
+}
+export { treeMatches };
+//# sourceMappingURL=index.js.map

package/dist/agent/verify/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/agent/verify/index.ts"],"names":[],"mappings":"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"}

package/dist/agent/verify/resolve.d.ts

@@ -0,0 +1,9 @@
+import type { VerifyConfig } from "./config.js";
+export interface VerifySelection {
+    /** `--config <file>`, resolved against the working directory. */
+    explicitPath?: string;
+    /** Invocation directory; defaults to the process working directory. */
+    cwd?: string;
+}
+export declare function readAgentDocument(file: string): Record<string, unknown>;
+export declare function resolveVerifyConfig(selection?: VerifySelection): VerifyConfig;

package/dist/agent/verify/resolve.js

@@ -0,0 +1,97 @@
+import fs from "node:fs";
+import path from "node:path";
+import { parse as parseYaml } from "yaml";
+import { configIn } from "../../config.js";
+import { object } from "../../config-schema.js";
+import { parseVerifyBlock } from "./config.js";
+/**
+ * Finds the document declaring `agent.verify`.
+ *
+ * Unlike the `scripts` walk this stops at the *nearest* document that declares
+ * the block. Entries are a set describing one repository, not a name lookup, so
+ * there is nothing for a farther ancestor to contribute — and merging two
+ * repositories' entry lists would verify trees the nearer document never
+ * mentioned.
+ */
+/** A configuration file larger than this is not one anybody wrote by hand. */
+const MAX_CONFIG_BYTES = 1024 * 1024;
+/** Enough of the head to catch a binary file mistakenly named `.cairn.yml`. */
+const NUL_PROBE_BYTES = 8 * 1024;
+/**
+ * Opens for reading without ever blocking.
+ *
+ * Opening a FIFO `O_RDONLY` blocks until a writer appears, which would wedge
+ * the process with no output — so a plain `open` cannot be the first thing
+ * that touches the path. `O_NONBLOCK` makes the open return immediately for
+ * every file type, leaving `fstat` to reject what is not a regular file.
+ * Checking the type by path first would be a check-then-use race; this way
+ * every guard is made against the descriptor that is actually read.
+ *
+ * `O_NONBLOCK` is undefined on Windows, which has no FIFOs in this sense.
+ */
+function openForRead(file) {
+    const { O_RDONLY, O_NONBLOCK } = fs.constants;
+    return fs.openSync(file, O_RDONLY | (O_NONBLOCK ?? 0));
+}
+export function readAgentDocument(file) {
+    // The guards mirror `readRegistry` in `src/scripts/resolve.ts`: a
+    // regular-file check so a FIFO cannot wedge the process, a size cap, and a
+    // NUL probe. Unlike that one, all three are made against an open descriptor,
+    // so the file they describe is the file that is read.
+    const handle = openForRead(file);
+    try {
+        const stat = fs.fstatSync(handle);
+        if (!stat.isFile())
+            throw new Error(`Not a regular file: ${file}`);
+        if (stat.size > MAX_CONFIG_BYTES)
+            throw new Error(`Configuration file is larger than ${MAX_CONFIG_BYTES} bytes: ${file}`);
+        const buffer = Buffer.alloc(stat.size);
+        let read = 0;
+        while (read < stat.size) {
+            const chunk = fs.readSync(handle, buffer, read, stat.size - read, read);
+            if (chunk === 0)
+                break;
+            read += chunk;
+        }
+        const contents = buffer.subarray(0, read);
+        if (contents.subarray(0, NUL_PROBE_BYTES).includes(0))
+            throw new Error(`Not a text file: ${file}`);
+        return object(parseYaml(contents.toString("utf-8")), "configuration");
+    }
+    finally {
+        fs.closeSync(handle);
+    }
+}
+function parseAt(file) {
+    const directory = path.dirname(path.resolve(file));
+    const document = readAgentDocument(file);
+    if (document.agent === undefined)
+        return undefined;
+    return parseVerifyBlock(document.agent, { file: path.resolve(file), directory });
+}
+export function resolveVerifyConfig(selection = {}) {
+    if (selection.explicitPath) {
+        const file = path.resolve(selection.explicitPath);
+        if (!fs.existsSync(file))
+            throw new Error(`Configuration file not found: ${file}`);
+        const config = parseAt(file);
+        if (!config)
+            throw new Error(`No 'agent.verify' block in ${file}`);
+        return config;
+    }
+    let current = path.resolve(selection.cwd ?? process.cwd());
+    while (true) {
+        const candidate = configIn(current);
+        if (candidate) {
+            const config = parseAt(candidate);
+            if (config)
+                return config;
+        }
+        const parent = path.dirname(current);
+        if (parent === current)
+            break;
+        current = parent;
+    }
+    throw new Error("No 'agent.verify' block found. Declare one in .cairn.yml, or pass --config <file>.");
+}
+//# sourceMappingURL=resolve.js.map

package/dist/agent/verify/resolve.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"resolve.js","sourceRoot":"","sources":["../../../src/agent/verify/resolve.ts"],"names":[],"mappings":"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"}

package/dist/cli.js

@@ -51,6 +51,7 @@ import { agentDoctorAction } from "./commands/agent-doctor.js";
 import { agentInstallAction } from "./commands/agent-install.js";
 import { agentUninstallAction } from "./commands/agent-uninstall.js";
 import { agentInstalledAction } from "./commands/agent-installed.js";
+import { agentVerifyAction } from "./commands/agent-verify.js";
 import { describeAction } from "./commands/describe.js";
 import { schemaAction } from "./commands/schema.js";
 import { completionAction } from "./commands/completion.js";
@@ -327,10 +328,12 @@ agent
     .action((source, opts) => agentActionBoundary("test", opts, () => agentTestAction(source, opts)));
 agent
     .command("install")
-    .description("Install a bundle into a host plugin or project directory")
-    .argument("<source>", "Bundle root")
-    .requiredOption("--target <target>", `Target: ${TARGETS.join(", ")}`, collect)
-    .option("--scope <scope>", "Install scope: user or project", "user")
+    .description("Install one or more bundles into a host plugin or project directory")
+    .argument("[source]", "Bundle root; omit when using --config")
+    .option("--target <target>", `Target (repeatable, or all): ${TARGETS.join(", ")}`, collect)
+    .option("--config <file>", "Install the agent.install block declared in a config file")
+    .option("--name <name>", "With --config, install only the named bundle (repeatable)", collect)
+    .option("--scope <scope>", "Install scope: user or project")
     .option("--into <dir>", "Override the install root declared by the target profile")
     .option("--profile <profile>", "Must match the location's profile when given")
     .option("--link", "Symlink the rendered tree instead of copying")
@@ -341,7 +344,7 @@ agent
     .option("--check", "Compare against an existing install without writing")
     .option("--format <fmt>", "Output format: llm, human, json", "llm")
     .option("--envelope", "Wrap --format json output in the versioned result envelope")
-    .addHelpText("after", "\nRenders and packages in memory, so an install is always derived from the\nbundle rather than from a possibly-drifted dist tree. Destinations come from\nthe target profiles. --register is the only flag that edits host config.\n\nExit codes:\n  0  Installed, or checks passed\n  1  Invocation or I/O error\n  2  Install finding, or --check found drift")
+    .addHelpText("after", "\nRenders and packages in memory, so an install is always derived from the\nbundle rather than from a possibly-drifted dist tree. Destinations come from\nthe target profiles. --register is the only flag that edits host config.\n\n--target is repeatable, and one destination may hold several installs: they are\ntold apart by bundle, target, profile and scope. A run is planned in full before\nanything is written, so a blocked plan writes nothing at all. --target all covers\nevery target declaring a location for the scope.\n\n--config installs the agent.install block a repository declares, and --target\nthere narrows that block rather than adding to it.\n\nExit codes:\n  0  Installed, or checks passed\n  1  Invocation or I/O error\n  2  Install finding, or --check found drift")
     .action((source, opts) => agentActionBoundary("install", opts, () => agentInstallAction(source, opts)));
 agent
     .command("uninstall")
@@ -366,6 +369,16 @@ agent
     .option("--envelope", "Wrap --format json output in the versioned result envelope")
     .addHelpText("after", "\nScans the install roots declared on the target profiles and lists every\n.cairn-install.json it finds.\n\nExit codes:\n  0  Listing written to stdout\n  1  Invocation error")
     .action((opts) => agentActionBoundary("installed", opts, () => agentInstalledAction(opts)));
+agent
+    .command("verify")
+    .description("Check committed agent trees against the bundles they were generated from")
+    .option("--config <file>", "Configuration document declaring the agent.verify block")
+    .option("--name <name>", "Verify only this entry (repeatable)", collect)
+    .option("--strict", "Treat warnings as blocking findings")
+    .option("--format <fmt>", "Output format: llm, human, json", "llm")
+    .option("--envelope", "Wrap --format json output in the versioned result envelope")
+    .addHelpText("after", "\nReads what to verify from the agent.verify block of a cairn configuration\ndocument, so a CI pipeline can run it with no arguments. Each declared bundle\nis rendered in memory and compared against the committed tree, and the pinned\nCLI and target profile versions are asserted against the running build.\n\nExit codes:\n  0  Every entry matches and every pin is satisfied\n  1  Invocation, configuration, or I/O error\n  2  Drift, an orphaned file, or a violated pin")
+    .action((opts) => agentActionBoundary("verify", opts, () => agentVerifyAction(opts)));
 agent
     .command("specs")
     .description("Print the versioned target conformance profiles")