@cairn-tool/cairn 2.0.0

package/dist/agent/overlays.d.ts

@@ -0,0 +1,38 @@
+import type { AgentDiagnostic, AgentProfile, AgentTarget, Artifact, NativeOverlay } from "./types.js";
+import type { NativeOverlayDeclaration } from "./manifest.js";
+/** File name of the optional plugin-manifest fragment inside an overlay root. */
+export declare const OVERLAY_MANIFEST = "manifest.json";
+/**
+ * Rejects an overlay path that would escape its target output root.
+ *
+ * `allFiles` already refuses symlinks that leave the directory it walks, so
+ * this is a second, purely lexical check. The invariant is promised at the
+ * output boundary, so it is enforced there rather than inferred from the
+ * filesystem walk.
+ */
+export declare function safeOverlayOutputPath(relative: string): string | null;
+/**
+ * Loads the declared native overlays for a bundle.
+ *
+ * Overlay content is deliberately **not** run through `processTargetBlocks` or
+ * `rewritePlaceholders`. It is already native and target-specific; rewriting it
+ * would be the exact "pretend it is portable" failure the overlay layer exists
+ * to avoid.
+ */
+export declare function loadOverlays(root: string, declarations: NativeOverlayDeclaration[], manifestPath: string, diagnostics: AgentDiagnostic[]): NativeOverlay[];
+/** The overlay artifacts for one target and output profile, in path order. */
+export declare function overlayArtifacts(overlay: NativeOverlay | undefined, profile: AgentProfile): Artifact[];
+/**
+ * Merges overlay artifacts into the portable set for one target and profile.
+ *
+ * Returns `portable` untouched when there is no overlay, so a bundle without
+ * one cannot be affected by this code path at all.
+ */
+export declare function mergeOverlay(portable: Artifact[], overlay: Artifact[], onCollision: NativeOverlay["onCollision"], target: AgentTarget, profile: AgentProfile, diagnostics: AgentDiagnostic[]): Artifact[];
+/**
+ * Merges an overlay manifest fragment over the generated plugin manifest.
+ *
+ * Applied to the object before the manifest artifact is built, so there is
+ * exactly one manifest artifact and no path collision to resolve.
+ */
+export declare function applyOverlayManifest(generated: Record<string, unknown>, fragment: Record<string, unknown> | undefined, target: AgentTarget, diagnostics: AgentDiagnostic[]): Record<string, unknown>;

package/dist/agent/overlays.js

@@ -0,0 +1,223 @@
+import fs from "node:fs";
+import path from "node:path";
+import { diagnostic } from "./types.js";
+import { profileFor } from "./targets/index.js";
+const PROFILES = ["plugin", "project"];
+/** File name of the optional plugin-manifest fragment inside an overlay root. */
+export const OVERLAY_MANIFEST = "manifest.json";
+/** Root-level files that document the overlay rather than contributing output. */
+const IGNORED_AT_ROOT = new Set(["README.md", "readme.md"]);
+function error(diagnostics, code, message, extra) {
+    diagnostics.push({
+        ...diagnostic(code, message, "unsupported", extra),
+        severity: "error",
+    });
+}
+/**
+ * Rejects an overlay path that would escape its target output root.
+ *
+ * `allFiles` already refuses symlinks that leave the directory it walks, so
+ * this is a second, purely lexical check. The invariant is promised at the
+ * output boundary, so it is enforced there rather than inferred from the
+ * filesystem walk.
+ */
+export function safeOverlayOutputPath(relative) {
+    const normalized = relative.split(path.sep).join("/");
+    if (!normalized || normalized.startsWith("/") || /^[A-Za-z]:/.test(normalized))
+        return null;
+    if (normalized.includes("\\"))
+        return null;
+    if (normalized.split("/").some((segment) => segment === ".." || segment === "."))
+        return null;
+    return normalized;
+}
+function readOverlayFiles(directory) {
+    const files = [];
+    const visit = (current) => {
+        for (const entry of fs
+            .readdirSync(current, { withFileTypes: true })
+            .sort((a, b) => (a.name < b.name ? -1 : 1))) {
+            const full = path.join(current, entry.name);
+            // Refuse a symlink that leaves the overlay root before reading it.
+            if (entry.isSymbolicLink()) {
+                const real = fs.realpathSync(full);
+                const relative = path.relative(fs.realpathSync(directory), real);
+                if (relative.startsWith("..") || path.isAbsolute(relative))
+                    throw new Error(`Overlay symlink escapes its root: ${full}`);
+            }
+            if (entry.isDirectory() || (entry.isSymbolicLink() && fs.statSync(full).isDirectory()))
+                visit(full);
+            else
+                files.push({
+                    path: path.relative(directory, full),
+                    content: fs.readFileSync(full),
+                    mode: fs.statSync(full).mode & 0o777,
+                });
+        }
+    };
+    visit(directory);
+    return files;
+}
+/**
+ * Loads the declared native overlays for a bundle.
+ *
+ * Overlay content is deliberately **not** run through `processTargetBlocks` or
+ * `rewritePlaceholders`. It is already native and target-specific; rewriting it
+ * would be the exact "pretend it is portable" failure the overlay layer exists
+ * to avoid.
+ */
+export function loadOverlays(root, declarations, manifestPath, diagnostics) {
+    const overlays = [];
+    for (const declaration of declarations) {
+        const target = declaration.target;
+        const overlayRoot = path.resolve(root, declaration.root);
+        const relative = path.relative(root, overlayRoot);
+        if (relative.startsWith("..") || path.isAbsolute(relative)) {
+            error(diagnostics, "AB183", `Native overlay root escapes the bundle: ${declaration.root}`, {
+                target,
+                path: manifestPath,
+                remediation: "Keep the overlay root inside the bundle.",
+            });
+            continue;
+        }
+        if (!fs.existsSync(overlayRoot) || !fs.statSync(overlayRoot).isDirectory())
+            continue;
+        const supported = profileFor(target).profiles;
+        const files = { plugin: [], project: [] };
+        let manifest;
+        for (const entry of fs
+            .readdirSync(overlayRoot, { withFileTypes: true })
+            .sort((a, b) => (a.name < b.name ? -1 : 1))) {
+            if (entry.isFile() && entry.name === OVERLAY_MANIFEST) {
+                try {
+                    const parsed = JSON.parse(fs.readFileSync(path.join(overlayRoot, entry.name), "utf8"));
+                    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed))
+                        throw new Error("must be a JSON object");
+                    manifest = parsed;
+                }
+                catch (cause) {
+                    error(diagnostics, "AB182", `Native overlay manifest fragment is invalid: ${cause.message}`, { target, path: path.join(overlayRoot, entry.name) });
+                }
+                continue;
+            }
+            if (!entry.isDirectory()) {
+                // Documentation and VCS scaffolding at the overlay root are ignored
+                // rather than rejected — an overlay is a directory people maintain by
+                // hand, and `agent init` writes a README explaining the contract.
+                if (IGNORED_AT_ROOT.has(entry.name) || entry.name.startsWith("."))
+                    continue;
+                // Anything else has no output profile to belong to. Reporting it beats
+                // silently dropping a file the author expected to be emitted.
+                error(diagnostics, "AB186", `Native overlay entry '${entry.name}' is not an output profile directory`, {
+                    target,
+                    path: path.join(overlayRoot, entry.name),
+                    remediation: `Place it under ${PROFILES.join("/ or ")}/.`,
+                });
+                continue;
+            }
+            if (!PROFILES.includes(entry.name)) {
+                error(diagnostics, "AB186", `Native overlay directory '${entry.name}' is not an output profile`, {
+                    target,
+                    path: path.join(overlayRoot, entry.name),
+                    remediation: `Use ${PROFILES.join(" or ")}.`,
+                });
+                continue;
+            }
+            const profile = entry.name;
+            if (!supported.includes(profile)) {
+                diagnostics.push(diagnostic("AB187", `Native overlay declares the '${profile}' profile, which ${target} does not support`, "unsupported", { target, profile, path: path.join(overlayRoot, entry.name) }));
+                continue;
+            }
+            for (const file of readOverlayFiles(path.join(overlayRoot, profile))) {
+                const output = safeOverlayOutputPath(file.path);
+                if (output === null) {
+                    error(diagnostics, "AB183", `Native overlay path escapes the target root: ${file.path}`, {
+                        target,
+                        profile,
+                        path: path.join(overlayRoot, profile, file.path),
+                    });
+                    continue;
+                }
+                files[profile].push({ ...file, path: output });
+            }
+        }
+        if (!files.plugin.length && !files.project.length && !manifest)
+            continue;
+        overlays.push({ target, root: overlayRoot, files, manifest, onCollision: "overlay-wins" });
+    }
+    return overlays;
+}
+/** The overlay artifacts for one target and output profile, in path order. */
+export function overlayArtifacts(overlay, profile) {
+    if (!overlay)
+        return [];
+    return overlay.files[profile]
+        .map((file) => ({
+        path: file.path,
+        content: file.content,
+        mode: file.mode,
+        origin: "native",
+    }))
+        .sort((a, b) => (a.path < b.path ? -1 : 1));
+}
+/**
+ * Merges overlay artifacts into the portable set for one target and profile.
+ *
+ * Returns `portable` untouched when there is no overlay, so a bundle without
+ * one cannot be affected by this code path at all.
+ */
+export function mergeOverlay(portable, overlay, onCollision, target, profile, diagnostics) {
+    if (!overlay.length)
+        return portable;
+    // Keyed by path rather than positional, so the result cannot depend on the
+    // order the two lists happen to arrive in.
+    const merged = new Map(portable.map((artifact) => [artifact.path, artifact]));
+    for (const artifact of overlay) {
+        if (!merged.has(artifact.path)) {
+            merged.set(artifact.path, artifact);
+            continue;
+        }
+        if (onCollision === "error") {
+            error(diagnostics, "AB181", `Native overlay collides with the portable artifact at '${artifact.path}'`, {
+                target,
+                profile,
+                path: artifact.path,
+                remediation: "Rename the overlay file, remove the portable component, or set onCollision: overlay-wins.",
+            });
+            continue;
+        }
+        diagnostics.push(diagnostic("AB181", `Native overlay replaces the portable artifact at '${artifact.path}'`, "approximate", {
+            target,
+            profile,
+            path: artifact.path,
+            remediation: "Remove the portable component if the override is permanent.",
+        }));
+        merged.set(artifact.path, artifact);
+    }
+    return [...merged.values()];
+}
+/**
+ * Merges an overlay manifest fragment over the generated plugin manifest.
+ *
+ * Applied to the object before the manifest artifact is built, so there is
+ * exactly one manifest artifact and no path collision to resolve.
+ */
+export function applyOverlayManifest(generated, fragment, target, diagnostics) {
+    if (!fragment)
+        return generated;
+    if (profileFor(target).manifest.directory === null) {
+        error(diagnostics, "AB182", `${target} has no plugin manifest to merge an overlay into`, {
+            target,
+            profile: "plugin",
+        });
+        return generated;
+    }
+    const merged = { ...generated };
+    for (const [key, value] of Object.entries(fragment)) {
+        if (key in generated)
+            diagnostics.push(diagnostic("AB182", `Native overlay manifest overrides the generated '${key}' field`, "approximate", { target, profile: "plugin", remediation: "Remove the key to keep the generated value." }));
+        merged[key] = value;
+    }
+    return merged;
+}
+//# sourceMappingURL=overlays.js.map

package/dist/agent/overlays.js.map

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

package/dist/agent/package/index.d.ts

@@ -0,0 +1,105 @@
+import type { AgentBundle, AgentDiagnostic, AgentProfile, AgentTarget, Artifact } from "../types.js";
+export declare const PACKAGE_REPORT = "package-report.json";
+export declare const CHECKSUMS = "checksums.sha256";
+export declare const SBOM = "sbom.json";
+export type MarketplaceMode = "repo" | "local" | "none";
+export interface PackageArchive {
+    target: AgentTarget;
+    profile: AgentProfile;
+    path: string;
+    sha256: string;
+    bytes: number;
+}
+export interface PackageReport {
+    catalogs: Array<{
+        target: AgentTarget;
+        profile: AgentProfile;
+        path: string;
+    }>;
+    archives: PackageArchive[];
+    checksums: string;
+    sbom: string;
+    checks: {
+        passed: number;
+        failed: number;
+    };
+}
+/**
+ * Reads image dimensions from a PNG or JPEG header.
+ *
+ * Header parsing only — pulling in an image library to answer "is this a PNG"
+ * would be a dependency for a validation nicety.
+ */
+export declare function imageKind(content: Buffer): "png" | "jpeg" | "svg" | null;
+export interface CatalogResult {
+    artifacts: Artifact[];
+    entries: PackageReport["catalogs"];
+    diagnostics: AgentDiagnostic[];
+}
+/**
+ * How a catalog covering more than one bundle differs from the single-bundle
+ * default. Every option is optional, so `agent package` passes none and gets
+ * byte-identical output to before this generalization.
+ */
+export interface CatalogOptions {
+    /**
+     * Replaces the resolved document-level fields — a collection's `name`,
+     * `description`, and `owner` belong to the collection, not to whichever of
+     * its bundles happened to sort first. Entry fields are unaffected, so each
+     * bundle still supplies its own `author` from `marketplace.publisher`.
+     */
+    document?: Record<string, unknown>;
+    /** Entry `source` per bundle. Defaults to the package-relative `./<target>/<profile>`. */
+    sourceFor?: (bundle: AgentBundle, target: AgentTarget, profile: AgentProfile) => string;
+    /** Where the catalog document is written. Defaults to inside the payload, beside the manifest. */
+    catalogPathFor?: (target: AgentTarget, profile: AgentProfile, location: CatalogLocation) => string;
+    /**
+     * Name the offending bundle on `AB500` and `AB501`. A collection needs it to
+     * say which of its bundles is at fault; `agent package` leaves it off, as it
+     * always has, so its diagnostic bytes do not move.
+     */
+    attributeToBundle?: boolean;
+}
+type CatalogLocation = {
+    directory: string;
+    file: string;
+};
+/**
+ * Builds a marketplace catalog per selected target, covering every bundle given.
+ *
+ * Field names and requirements come from the target profile, so the packager
+ * itself contains no per-target branching and a catalog change is a data edit.
+ * `AB500` and `AB501` fire from here for every caller — `agent package` with one
+ * bundle, `agent marketplace` with a collection — so a consumer's suppression
+ * list means the same thing whichever command produced the catalog.
+ */
+export declare function buildCatalogs(bundles: AgentBundle | AgentBundle[], targets: AgentTarget[], profiles: AgentProfile[], mode: MarketplaceMode, options?: CatalogOptions): CatalogResult;
+/** Validates declared marketplace assets against the target's asset rules. */
+export declare function checkAssets(bundle: AgentBundle, targets: AgentTarget[], payload: Artifact[]): AgentDiagnostic[];
+/** Flags executable files outside the directories where a script belongs. */
+export declare function checkExecutables(payload: Artifact[]): AgentDiagnostic[];
+/** Flags paths that collide when the filesystem is case-insensitive. */
+export declare function checkCaseCollisions(payload: Artifact[]): AgentDiagnostic[];
+/** Notes MCP servers invoked through an unpinned package specifier. */
+export declare function checkPinning(bundle: AgentBundle): AgentDiagnostic[];
+/** `sha256sum -c` compatible, sorted by byte order for reproducibility. */
+export declare function buildChecksums(payload: Artifact[]): Artifact;
+/**
+ * Content-derived file type, as recorded in `sbom.json`. Exported because
+ * `agent audit --baseline` reads that `type` field back and must classify the
+ * current side by the same rule.
+ */
+export declare function classify(artifact: Artifact): string;
+/**
+ * A file inventory, deliberately not a CycloneDX claim.
+ *
+ * `bomFormat` and `specVersion` identify it as this tool's own format so a
+ * later `--sbom cyclonedx` can be added without changing what this one means.
+ */
+export declare function buildSbom(bundle: AgentBundle, payload: Artifact[]): Artifact;
+/** One deterministic archive per target and profile. */
+export declare function buildArchives(bundle: AgentBundle, payload: Artifact[], targets: AgentTarget[], profiles: AgentProfile[]): {
+    artifacts: Artifact[];
+    archives: PackageArchive[];
+};
+export {};