@cairn-tool/cairn 2.0.0

package/dist/agent/marketplace/index.js

@@ -0,0 +1,212 @@
+import path from "node:path";
+import { diagnostic } from "../types.js";
+import { loadBundle } from "../parser.js";
+import { renderBundle } from "../render.js";
+import { profileFor } from "../targets/index.js";
+import { buildArchives, buildCatalogs, buildChecksums, buildSbom, checkAssets, checkCaseCollisions, checkExecutables, checkPinning, } from "../package/index.js";
+import { TarPathTooLongError } from "../package/tar.js";
+import { selectedForTarget } from "./spec.js";
+export const MARKETPLACE_REPORT = "marketplace-report.json";
+/**
+ * Distribution modes a collection supports.
+ *
+ * `agent package`'s third mode, `none`, is deliberately absent: a collection
+ * whose whole product is a catalog has nothing left when the catalog is
+ * suppressed.
+ */
+export const COLLECTION_MODES = ["repo", "local"];
+/**
+ * The collection's own pass/fail rule.
+ *
+ * Like package, install, and doctor, this cannot use the shared `hasFindings`:
+ * a codex bundle inherently carries approximate render diagnostics, which say
+ * nothing about whether a collection is publishable.
+ */
+export function collectionHasFindings(diagnostics, strict) {
+    return diagnostics.some((item) => item.severity === "error" || (strict && item.severity === "warning"));
+}
+function sortByPath(artifacts) {
+    // Byte comparison, never localeCompare: that is ICU- and locale-dependent and
+    // would reorder a collection on a differently configured runner.
+    return [...artifacts].sort((a, b) => (a.path < b.path ? -1 : a.path > b.path ? 1 : 0));
+}
+/**
+ * Relocates a rendered artifact out of its `<target>/<profile>/` prefix and
+ * under the plugin's own directory, so a collection reads
+ * `<target>/<plugin>/…` rather than `<target>/plugin/…` repeated N times.
+ */
+function relocate(artifact, target, plugin) {
+    const prefix = `${target}/plugin/`;
+    return {
+        ...artifact,
+        path: `${target}/${plugin}/${artifact.path.slice(prefix.length)}`,
+    };
+}
+/**
+ * Renders every bundle for every target it is selected for, and aggregates one
+ * catalog per target.
+ *
+ * Catalog identity comes from the spec rather than from any bundle: a
+ * collection's name and owner are properties of the collection. Entry fields
+ * still resolve per bundle from the target profile, so `category`'s
+ * first-of-list transform and `author`'s object shape keep working with no
+ * per-target branching here.
+ */
+export function buildCollection(spec, targets, mode, options = {}) {
+    const diagnostics = [];
+    const bundles = new Map();
+    for (const entry of spec.bundles)
+        bundles.set(entry.path, loadBundle(entry.root));
+    // Two bundles may declare distinct paths and still render the same plugin
+    // name, which a host would resolve arbitrarily.
+    const byName = new Map();
+    for (const entry of spec.bundles) {
+        const name = bundles.get(entry.path).name;
+        const previous = byName.get(name);
+        if (previous)
+            diagnostics.push({
+                ...diagnostic("AB905", `Bundles '${previous.path}' and '${entry.path}' are both '${name}'`, "unsupported", {
+                    path: spec.file,
+                }),
+                severity: "error",
+            });
+        else
+            byName.set(name, entry);
+    }
+    const artifacts = [];
+    const reportTargets = [];
+    let archives = [];
+    for (const target of targets) {
+        const selected = spec.bundles.filter((entry) => selectedForTarget(entry, target));
+        // A notice, not a warning: an exclusion is the author saying so, and a
+        // warning would block the build under --strict for working as declared.
+        for (const entry of spec.bundles)
+            if (!selectedForTarget(entry, target))
+                diagnostics.push(diagnostic("AB907", `${entry.path} is not built for ${target}`, "exact", {
+                    target,
+                    path: entry.path,
+                }));
+        if (selected.length === 0) {
+            diagnostics.push({
+                ...diagnostic("AB906", `No bundles are built for ${target}`, "unsupported", {
+                    target,
+                    path: spec.file,
+                    remediation: "Drop the target, or widen a bundle's include/exclude.",
+                }),
+                severity: "warning",
+            });
+            reportTargets.push({ target, catalog: null, plugins: [] });
+            continue;
+        }
+        const targetArtifacts = [];
+        const ordered = [];
+        const plugins = [];
+        for (const entry of selected) {
+            const bundle = bundles.get(entry.path);
+            const rendered = renderBundle(bundle, [target], ["plugin"]);
+            diagnostics.push(...rendered.diagnostics);
+            targetArtifacts.push(...rendered.artifacts.map((artifact) => relocate(artifact, target, bundle.name)));
+            ordered.push(bundle);
+            plugins.push({ name: bundle.name, version: bundle.version, source: entry.path });
+        }
+        // AB507 already means "this target produces no catalog"; a target that
+        // declares no marketplace at all is the same condition, and one condition
+        // keeps one id whichever command surfaces it. Silently emitting payloads
+        // and no catalog would be a surprise for a command whose product is one.
+        const marketplace = profileFor(target).marketplace;
+        if (!marketplace)
+            diagnostics.push(diagnostic("AB507", `${target} declares no marketplace catalog`, "unsupported", {
+                target,
+                path: spec.file,
+                remediation: `Drop ${target} from targets, or install the plugins directly.`,
+            }));
+        const location = marketplace?.catalog[mode];
+        const catalogs = buildCatalogs(ordered, [target], ["plugin"], mode, {
+            document: {
+                name: spec.name,
+                ...(spec.description !== undefined ? { description: spec.description } : {}),
+                owner: spec.owner,
+            },
+            // Relative to the catalog, which sits one level above the plugin
+            // directories — never rewritten to "./", which is only correct when a
+            // catalog shares a directory with the single plugin it describes.
+            sourceFor: (bundle) => `./${bundle.name}`,
+            catalogPathFor: (id, _profile, where) => `${id}/${where.directory}/${where.file}`,
+            attributeToBundle: true,
+        });
+        diagnostics.push(...catalogs.diagnostics);
+        targetArtifacts.push(...catalogs.artifacts);
+        // Per bundle, not once for the collection: each declares its own icon and
+        // screenshots, and checking only the first would let the rest ship an asset
+        // the catalog references but the payload does not carry.
+        for (const bundle of ordered)
+            diagnostics.push(...checkPinning(bundle), ...checkAssets(bundle, [target], targetArtifacts));
+        artifacts.push(...targetArtifacts);
+        reportTargets.push({
+            target,
+            catalog: location ? `${target}/${location.directory}/${location.file}` : null,
+            plugins,
+        });
+    }
+    const payload = sortByPath(artifacts);
+    diagnostics.push(...checkExecutables(payload), ...checkCaseCollisions(payload));
+    const extra = [];
+    if (options.archive)
+        for (const target of targets)
+            for (const entry of spec.bundles.filter((item) => selectedForTarget(item, target))) {
+                const bundle = bundles.get(entry.path);
+                // Archive each plugin from its own subtree, so the member paths inside
+                // are the plugin's own rather than the collection's.
+                const own = payload
+                    .filter((artifact) => artifact.path.startsWith(`${target}/${bundle.name}/`))
+                    .map((artifact) => ({
+                    ...artifact,
+                    path: `${target}/plugin/${artifact.path.slice(`${target}/${bundle.name}/`.length)}`,
+                }));
+                try {
+                    const built = buildArchives(bundle, own, [target], ["plugin"]);
+                    extra.push(...built.artifacts);
+                    archives = [...archives, ...built.archives];
+                }
+                catch (cause) {
+                    if (!(cause instanceof TarPathTooLongError))
+                        throw cause;
+                    diagnostics.push({
+                        ...diagnostic("AB509", cause.message, "unsupported", {
+                            path: cause.path,
+                            remediation: "Shorten the path; ustar headers cannot express it.",
+                        }),
+                        severity: "error",
+                    });
+                }
+            }
+    const withArchives = sortByPath([...payload, ...extra]);
+    const checksums = buildChecksums(withArchives);
+    // The sbom's subject is the collection, not any one bundle, so it is given a
+    // synthetic bundle carrying the spec's identity.
+    const subject = { ...bundles.values().next().value, name: spec.name, version: spec.version };
+    const sbom = buildSbom(subject, withArchives);
+    const report = {
+        name: spec.name,
+        version: spec.version,
+        targets: reportTargets,
+        archives,
+        checksums: checksums.path,
+        sbom: sbom.path,
+        checks: {
+            failed: diagnostics.filter((item) => item.severity === "error").length,
+            passed: diagnostics.filter((item) => item.severity !== "error").length,
+        },
+    };
+    return {
+        artifacts: [...withArchives, checksums, sbom],
+        report,
+        diagnostics,
+        bundles,
+    };
+}
+/** Collection-relative directories the writer owns outright, one per target. */
+export function managedRootsFor(targets) {
+    return targets.map((target) => path.join(target));
+}
+//# sourceMappingURL=index.js.map

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

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

package/dist/agent/marketplace/spec.d.ts

@@ -0,0 +1,48 @@
+import type { AgentDiagnostic, AgentTarget } from "../types.js";
+import type { MarketplacePublisher } from "../manifest.js";
+/**
+ * The `agent-marketplace.yaml` format: which bundles a collection contains, and
+ * which targets each is built for.
+ *
+ * `schemaVersion` is hand-owned and versions the source format authors write,
+ * the sixth such version in this project. It is unrelated to the package
+ * version, to `CONTRACT_VERSION`, to `PROFILE_SCHEMA_VERSION`, to the bundle
+ * `schemaVersion`, or to the test-file one. See `docs/contract.md`.
+ */
+export declare const SUPPORTED_SPEC_SCHEMAS: readonly ["1"];
+export declare const CURRENT_SPEC_SCHEMA = "1";
+export declare const SPEC_FILENAME = "agent-marketplace.yaml";
+/** One bundle in a collection, with the targets it is built for. */
+export interface SpecBundle {
+    /** Spec-relative POSIX path, as written. */
+    path: string;
+    /** Absolute, symlink-resolved bundle root. */
+    root: string;
+    include?: AgentTarget[];
+    exclude?: AgentTarget[];
+}
+export interface MarketplaceSpec {
+    schemaVersion: string;
+    name: string;
+    version: string;
+    description?: string;
+    owner: MarketplacePublisher;
+    targets: AgentTarget[];
+    bundles: SpecBundle[];
+    /** Absolute directory the spec file lives in; every bundle path resolves from it. */
+    root: string;
+    /** Absolute path to the spec file itself, for diagnostics. */
+    file: string;
+}
+export interface SpecResult {
+    spec: MarketplaceSpec;
+    diagnostics: AgentDiagnostic[];
+}
+/** True when `bundle` is built for `target` under its include/exclude declaration. */
+export declare function selectedForTarget(bundle: SpecBundle, target: AgentTarget): boolean;
+/**
+ * Reads and validates a collection spec. Never throws for a content problem —
+ * every finding is a diagnostic, so a caller reports all of them at once rather
+ * than one per run. Only an unreadable or unparseable file throws.
+ */
+export declare function loadSpec(source: string): SpecResult;

package/dist/agent/marketplace/spec.js

@@ -0,0 +1,237 @@
+import fs from "node:fs";
+import path from "node:path";
+import { diagnostic, TARGETS } from "../types.js";
+import { readStructured } from "../parser.js";
+import { isInside } from "../../config-schema.js";
+/**
+ * The `agent-marketplace.yaml` format: which bundles a collection contains, and
+ * which targets each is built for.
+ *
+ * `schemaVersion` is hand-owned and versions the source format authors write,
+ * the sixth such version in this project. It is unrelated to the package
+ * version, to `CONTRACT_VERSION`, to `PROFILE_SCHEMA_VERSION`, to the bundle
+ * `schemaVersion`, or to the test-file one. See `docs/contract.md`.
+ */
+export const SUPPORTED_SPEC_SCHEMAS = ["1"];
+export const CURRENT_SPEC_SCHEMA = "1";
+export const SPEC_FILENAME = "agent-marketplace.yaml";
+const NAME = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
+const SEMVER = /^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?$/;
+const ROOT_KEYS = new Set([
+    "schemaVersion",
+    "name",
+    "version",
+    "description",
+    "owner",
+    "targets",
+    "bundles",
+]);
+const BUNDLE_KEYS = new Set(["path", "include", "exclude"]);
+const OWNER_KEYS = new Set(["name", "url", "email"]);
+/**
+ * The `AB9xx` error factory. The same three-line idiom appears in
+ * `manifest.ts`, `package/index.ts`, and `install/index.ts`: `diagnostic()`
+ * derives severity from quality and never returns `"error"`, so an error is
+ * built by spreading and overriding.
+ */
+function error(diagnostics, code, message, file, remediation) {
+    diagnostics.push({
+        ...diagnostic(code, message, "unsupported", {
+            path: file,
+            ...(remediation ? { remediation } : {}),
+        }),
+        severity: "error",
+    });
+}
+function record(value) {
+    return value && typeof value === "object" && !Array.isArray(value)
+        ? value
+        : undefined;
+}
+/** Required non-empty string, reported as AB901 when missing and AB902 when malformed. */
+function requiredString(value, field, file, diagnostics) {
+    if (value === undefined || value === null || value === "") {
+        error(diagnostics, "AB901", `Marketplace field '${field}' is required`, file);
+        return "";
+    }
+    if (typeof value !== "string") {
+        error(diagnostics, "AB902", `Marketplace field '${field}' must be a string`, file);
+        return "";
+    }
+    return value;
+}
+function parseTargetList(value, field, file, diagnostics) {
+    if (value === undefined)
+        return undefined;
+    if (!Array.isArray(value)) {
+        error(diagnostics, "AB902", `${field} must be an array of target ids`, file);
+        return [];
+    }
+    const resolved = [];
+    for (const entry of value) {
+        const id = String(entry);
+        // `all` is the same spelling `--target all` accepts, so a spec and a flag
+        // never disagree about what "everything" means.
+        if (id === "all") {
+            resolved.push(...TARGETS);
+            continue;
+        }
+        if (!TARGETS.includes(id)) {
+            error(diagnostics, "AB902", `Unknown target '${id}' in ${field}`, file, `Use one of: ${TARGETS.join(", ")}.`);
+            continue;
+        }
+        resolved.push(id);
+    }
+    return [...new Set(resolved)];
+}
+function parseOwner(value, file, diagnostics) {
+    if (value === undefined) {
+        error(diagnostics, "AB901", "Marketplace field 'owner' is required", file, "Claude Code refuses a catalog with no owner.");
+        return { name: "" };
+    }
+    const owner = record(value);
+    if (!owner) {
+        error(diagnostics, "AB902", "Marketplace 'owner' must be a mapping", file);
+        return { name: "" };
+    }
+    for (const key of Object.keys(owner))
+        if (!OWNER_KEYS.has(key))
+            error(diagnostics, "AB902", `Unknown owner key '${key}'`, file);
+    const name = requiredString(owner.name, "owner.name", file, diagnostics);
+    const result = { name };
+    if (typeof owner.url === "string")
+        result.url = owner.url;
+    if (typeof owner.email === "string")
+        result.email = owner.email;
+    return result;
+}
+/**
+ * Bundle paths resolve from the spec file's directory and may not escape it,
+ * including after resolving symlinks — the same containment rule component
+ * paths inside a bundle follow. A path that escapes is refused rather than
+ * followed.
+ */
+function parseBundle(value, index, root, file, diagnostics) {
+    const entry = record(value);
+    if (!entry) {
+        error(diagnostics, "AB902", `bundles[${index}] must be a mapping`, file);
+        return undefined;
+    }
+    for (const key of Object.keys(entry))
+        if (!BUNDLE_KEYS.has(key))
+            error(diagnostics, "AB902", `Unknown bundles[${index}] key '${key}'`, file);
+    const declared = requiredString(entry.path, `bundles[${index}].path`, file, diagnostics);
+    if (!declared)
+        return undefined;
+    const include = parseTargetList(entry.include, `bundles[${index}].include`, file, diagnostics);
+    const exclude = parseTargetList(entry.exclude, `bundles[${index}].exclude`, file, diagnostics);
+    if (include && exclude) {
+        error(diagnostics, "AB903", `bundles[${index}] declares both include and exclude`, file, "Use one or the other; they are not combined.");
+        return undefined;
+    }
+    const resolved = path.resolve(root, declared);
+    if (!fs.existsSync(resolved)) {
+        error(diagnostics, "AB904", `Bundle path '${declared}' does not exist`, file);
+        return undefined;
+    }
+    const real = fs.realpathSync(resolved);
+    if (!isInside(fs.realpathSync(root), real)) {
+        error(diagnostics, "AB904", `Bundle path '${declared}' escapes the spec directory`, file, "A bundle must live inside the directory holding the spec file.");
+        return undefined;
+    }
+    if (!fs.statSync(real).isDirectory()) {
+        error(diagnostics, "AB904", `Bundle path '${declared}' is not a directory`, file);
+        return undefined;
+    }
+    return {
+        path: declared,
+        root: real,
+        ...(include ? { include } : {}),
+        ...(exclude ? { exclude } : {}),
+    };
+}
+/** True when `bundle` is built for `target` under its include/exclude declaration. */
+export function selectedForTarget(bundle, target) {
+    if (bundle.include)
+        return bundle.include.includes(target);
+    if (bundle.exclude)
+        return !bundle.exclude.includes(target);
+    return true;
+}
+/**
+ * Reads and validates a collection spec. Never throws for a content problem —
+ * every finding is a diagnostic, so a caller reports all of them at once rather
+ * than one per run. Only an unreadable or unparseable file throws.
+ */
+export function loadSpec(source) {
+    const file = path.resolve(source);
+    const stat = fs.existsSync(file) ? fs.statSync(file) : undefined;
+    const resolved = stat?.isDirectory() ? path.join(file, SPEC_FILENAME) : file;
+    if (!fs.existsSync(resolved))
+        throw new Error(`Marketplace spec not found: ${path.relative(process.cwd(), resolved)}`);
+    const root = path.dirname(resolved);
+    const raw = readStructured(resolved);
+    const diagnostics = [];
+    for (const key of Object.keys(raw))
+        if (!ROOT_KEYS.has(key))
+            error(diagnostics, "AB902", `Unknown marketplace key '${key}'`, resolved);
+    const schemaVersion = String(raw.schemaVersion ?? "");
+    if (!SUPPORTED_SPEC_SCHEMAS.includes(schemaVersion))
+        error(diagnostics, "AB900", `Unsupported marketplace schemaVersion '${schemaVersion}'`, resolved, `Use schemaVersion: "${CURRENT_SPEC_SCHEMA}".`);
+    const name = requiredString(raw.name, "name", resolved, diagnostics);
+    if (name && !NAME.test(name))
+        error(diagnostics, "AB902", `Invalid marketplace name '${name}'`, resolved, "Use lowercase kebab-case; this becomes the marketplace key hosts index by.");
+    const version = requiredString(raw.version, "version", resolved, diagnostics);
+    if (version && !SEMVER.test(version))
+        error(diagnostics, "AB902", `Invalid marketplace version '${version}'`, resolved, "Use a semantic version such as 1.0.0.");
+    const description = raw.description === undefined
+        ? undefined
+        : typeof raw.description === "string"
+            ? raw.description
+            : (error(diagnostics, "AB902", "Marketplace 'description' must be a string", resolved),
+                undefined);
+    const owner = parseOwner(raw.owner, resolved, diagnostics);
+    const targets = parseTargetList(raw.targets, "targets", resolved, diagnostics) ?? [];
+    if (raw.targets === undefined)
+        error(diagnostics, "AB901", "Marketplace field 'targets' is required", resolved);
+    else if (targets.length === 0 && Array.isArray(raw.targets))
+        error(diagnostics, "AB901", "Marketplace field 'targets' is empty", resolved);
+    const bundles = [];
+    if (raw.bundles === undefined)
+        error(diagnostics, "AB901", "Marketplace field 'bundles' is required", resolved);
+    else if (!Array.isArray(raw.bundles))
+        error(diagnostics, "AB902", "Marketplace 'bundles' must be an array", resolved);
+    else if (raw.bundles.length === 0)
+        error(diagnostics, "AB901", "Marketplace field 'bundles' is empty", resolved);
+    else
+        raw.bundles.forEach((entry, index) => {
+            const parsed = parseBundle(entry, index, root, resolved, diagnostics);
+            if (parsed)
+                bundles.push(parsed);
+        });
+    // Two entries pointing at the same directory would render the same plugin
+    // name twice into one catalog, which a host resolves arbitrarily.
+    const seen = new Map();
+    for (const bundle of bundles) {
+        const previous = seen.get(bundle.root);
+        if (previous !== undefined)
+            error(diagnostics, "AB905", `Bundles '${previous}' and '${bundle.path}' resolve to the same directory`, resolved);
+        else
+            seen.set(bundle.root, bundle.path);
+    }
+    return {
+        spec: {
+            schemaVersion,
+            name,
+            version,
+            ...(description !== undefined ? { description } : {}),
+            owner,
+            targets,
+            bundles,
+            root,
+            file: resolved,
+        },
+        diagnostics,
+    };
+}
+//# sourceMappingURL=spec.js.map

package/dist/agent/marketplace/spec.js.map

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

package/dist/agent/output.d.ts

@@ -0,0 +1,36 @@
+import type { AgentProfile, AgentTarget, Artifact } from "./types.js";
+/** File name of the report `agent convert` writes at the output root. */
+export declare const CONVERSION_REPORT = "conversion-report.json";
+/**
+ * Provenance recorded in the conversion report so `agent doctor` can tell a
+ * tree generated against an older target profile from a current one.
+ */
+export interface ConversionProvenance {
+    generator: {
+        name: string;
+        version: string;
+    };
+    profileSchemaVersion: string;
+    targetProfiles: Record<string, {
+        documentationRevision: string;
+    }>;
+}
+export interface OutputDiff {
+    /** Expected artifacts absent from the tree, or present but not a regular file. */
+    missing: string[];
+    /** Expected artifacts whose bytes or mode differ. */
+    changed: string[];
+    /** Files inside a rendered target/profile root that no artifact accounts for. */
+    unmanaged: string[];
+}
+/**
+ * Compares a generated tree against the artifacts that should produce it.
+ *
+ * The conversion report is compared by existence only. It embeds the generator
+ * version and target profile revisions, so byte-comparing it would report every
+ * tree as stale after any CLI upgrade — and it is derived from artifacts that
+ * are already compared byte for byte.
+ */
+export declare function diffOutput(output: string, artifacts: Artifact[], targets: AgentTarget[], profiles: AgentProfile[]): OutputDiff;
+/** True when the generated tree matches the artifacts exactly. */
+export declare function outputMatches(diff: OutputDiff): boolean;

package/dist/agent/output.js

@@ -0,0 +1,56 @@
+import fs from "node:fs";
+import path from "node:path";
+/** File name of the report `agent convert` writes at the output root. */
+export const CONVERSION_REPORT = "conversion-report.json";
+function walk(directory, onFile) {
+    for (const entry of fs.readdirSync(directory, { withFileTypes: true })) {
+        const full = path.join(directory, entry.name);
+        if (entry.isDirectory())
+            walk(full, onFile);
+        else
+            onFile(full);
+    }
+}
+/**
+ * Compares a generated tree against the artifacts that should produce it.
+ *
+ * The conversion report is compared by existence only. It embeds the generator
+ * version and target profile revisions, so byte-comparing it would report every
+ * tree as stale after any CLI upgrade — and it is derived from artifacts that
+ * are already compared byte for byte.
+ */
+export function diffOutput(output, artifacts, targets, profiles) {
+    const diff = { missing: [], changed: [], unmanaged: [] };
+    const expected = new Map(artifacts.map((artifact) => [artifact.path, artifact]));
+    for (const artifact of artifacts) {
+        const file = path.join(output, artifact.path);
+        if (!fs.existsSync(file) || !fs.statSync(file).isFile()) {
+            diff.missing.push(artifact.path);
+            continue;
+        }
+        if (artifact.path === CONVERSION_REPORT)
+            continue;
+        if (!fs.readFileSync(file).equals(artifact.content) ||
+            (fs.statSync(file).mode & 0o777) !== artifact.mode)
+            diff.changed.push(artifact.path);
+    }
+    for (const target of targets)
+        for (const profile of profiles) {
+            const root = path.join(output, target, profile);
+            if (!fs.existsSync(root)) {
+                diff.missing.push(`${target}/${profile}`);
+                continue;
+            }
+            walk(root, (file) => {
+                const relative = path.relative(output, file).split(path.sep).join("/");
+                if (!expected.has(relative))
+                    diff.unmanaged.push(relative);
+            });
+        }
+    return diff;
+}
+/** True when the generated tree matches the artifacts exactly. */
+export function outputMatches(diff) {
+    return !diff.missing.length && !diff.changed.length && !diff.unmanaged.length;
+}
+//# sourceMappingURL=output.js.map

package/dist/agent/output.js.map

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