@cairn-tool/cairn 2.0.0

package/dist/commands/agent-upgrade.js

@@ -0,0 +1,105 @@
+import fs from "node:fs";
+import path from "node:path";
+import { TARGETS, diagnostic } from "../agent/types.js";
+import { loadBundle } from "../agent/parser.js";
+import { renderBundle } from "../agent/render.js";
+import { planUpgrade } from "../agent/upgrade.js";
+import { outputDecidedResult } from "./agent.js";
+const PROFILES = ["plugin", "project"];
+/** Every artifact reduced to a comparable shape, for the byte-identity guard. */
+function fingerprint(artifacts) {
+    return artifacts
+        .map((artifact) => `${artifact.path} ${artifact.mode} ${artifact.content.toString("base64")}`)
+        .sort();
+}
+/**
+ * Rewrites one file in place, atomically.
+ *
+ * A rename within a directory is atomic on POSIX, so a reader never observes a
+ * partial manifest. This is deliberately not `writeArtifactsAtomically`, which
+ * is directory-shaped and would replace roots this command does not own.
+ */
+function writeFileAtomically(destination, content, mode) {
+    const temporary = path.join(path.dirname(destination), `.${path.basename(destination)}.cairn-${process.pid}.tmp`);
+    fs.writeFileSync(temporary, content, { mode, flag: "wx" });
+    try {
+        fs.renameSync(temporary, destination);
+    }
+    catch (error) {
+        fs.rmSync(temporary, { force: true });
+        throw error;
+    }
+}
+export async function agentUpgradeAction(source, opts) {
+    if (opts.check && opts.dryRun)
+        throw new Error("--check and --dry-run cannot be used together");
+    // Required rather than defaulted: an implicit "latest" would make a CI run's
+    // result depend on which Cairn version happened to be installed.
+    if (!opts.toSchema)
+        throw new Error("--to-schema is required, for example --to-schema 2");
+    const bundle = loadBundle(source);
+    const manifestPath = path.join(bundle.root, "agent-bundle.yaml");
+    const original = fs.existsSync(manifestPath) ? fs.readFileSync(manifestPath, "utf8") : "";
+    const plan = planUpgrade(bundle, original, opts.toSchema);
+    const diagnostics = [...plan.diagnostics];
+    // The byte-identity guard. Schema 2 is a strict superset, so a migration that
+    // changes any rendered byte is a defect — proven here by rendering both
+    // manifests in memory rather than trusted to a test.
+    if (plan.content) {
+        const before = fingerprint(renderBundle(bundle, [...TARGETS], PROFILES).artifacts);
+        const after = fingerprintMigrated(bundle.root, plan.content, manifestPath, original);
+        if (before.join("\n") !== after.join("\n"))
+            diagnostics.push({
+                ...diagnostic("AB224", "The migration would change generated output, which schema 2 must never do", "unsupported", {
+                    path: manifestPath,
+                    remediation: "This is a Cairn defect; please report it.",
+                }),
+                severity: "error",
+            });
+    }
+    const blocked = diagnostics.some((item) => item.severity === "error");
+    const stale = plan.content !== null;
+    const readOnly = Boolean(opts.dryRun) || Boolean(opts.check);
+    if (!readOnly && !blocked && plan.content)
+        writeFileAtomically(manifestPath, plan.content, 0o644);
+    const result = {
+        command: "upgrade",
+        // An AB221 human-judgment notice is not a failure; only errors and a
+        // stale --check are. `hasFindings` would fail on any approximate mapping,
+        // which is why this decides its own status like `agent doctor` does.
+        ok: !blocked && !(opts.check && stale),
+        source: bundle.root,
+        targets: [],
+        artifacts: plan.content
+            ? [
+                {
+                    path: "agent-bundle.yaml",
+                    bytes: plan.content.length,
+                    mode: "0644",
+                },
+            ]
+            : [],
+        diagnostics,
+        upgrade: plan.report,
+        ...(opts.dryRun ? { dryRun: true } : {}),
+        ...(opts.check ? { check: true, stale } : {}),
+    };
+    outputDecidedResult(result, opts);
+}
+/**
+ * Renders the bundle as if the migrated manifest were already in place.
+ *
+ * The manifest is swapped, rendered, and restored, because `loadBundle` reads
+ * from disk. The original bytes are written back in a `finally`, so an
+ * interrupted run cannot leave a half-migrated manifest behind.
+ */
+function fingerprintMigrated(root, migrated, manifestPath, original) {
+    fs.writeFileSync(manifestPath, migrated);
+    try {
+        return fingerprint(renderBundle(loadBundle(root), [...TARGETS], PROFILES).artifacts);
+    }
+    finally {
+        fs.writeFileSync(manifestPath, original);
+    }
+}
+//# sourceMappingURL=agent-upgrade.js.map

package/dist/commands/agent-upgrade.js.map

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

package/dist/commands/agent.d.ts

@@ -0,0 +1,27 @@
+import type { AgentProfile, AgentResult, AgentTarget } from "../agent/types.js";
+export interface AgentOptions {
+    target?: string[];
+    output?: string;
+    profile?: string;
+    strict?: boolean;
+    force?: boolean;
+    dryRun?: boolean;
+    check?: boolean;
+    format?: string;
+    envelope?: boolean;
+    report?: string;
+}
+export declare function agentActionBoundary(command: AgentResult["command"], opts: AgentOptions, action: () => Promise<void>): Promise<void>;
+export declare function resolveTargets(values: string[] | undefined, required?: boolean): AgentTarget[];
+export declare function profiles(value: string | undefined): AgentProfile[];
+export declare function outputResult(result: AgentResult, opts: AgentOptions): void;
+/**
+ * Writes a result whose `ok` has already been decided by the caller. `doctor`
+ * needs this because {@link hasFindings} fails on any approximate mapping even
+ * without `--strict`, which would make every codex bundle a doctor failure.
+ */
+export declare function outputDecidedResult(result: AgentResult, opts: AgentOptions): void;
+export declare function agentConvertAction(source: string, opts: AgentOptions): Promise<void>;
+export declare function agentValidateAction(source: string, opts: AgentOptions): Promise<void>;
+export declare function agentInspectAction(source: string, opts: AgentOptions): Promise<void>;
+export declare function agentCompatAction(source: string | undefined, opts: AgentOptions): Promise<void>;