@cairn-tool/cairn 4.0.0 → 4.1.0

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

@@ -36,7 +36,9 @@ export interface InstallInventoryEntry {
     mode: string;
     sha256: string;
 }
-export interface InstallRegistration {
+export interface ClaudeInstallRegistration {
+    /** Absent in manifests written before activation drivers were versioned. */
+    form?: "claude-enabled-plugins";
     file: string;
     marketplaceKey: string;
     /** The single plugin key a bundle install enables. */
@@ -47,6 +49,14 @@ export interface InstallRegistration {
      */
     pluginKeys?: string[];
 }
+export interface CodexInstallRegistration {
+    form: "codex-plugin-cli";
+    command: string;
+    marketplaceKey: string;
+    pluginKey?: string;
+    pluginKeys?: string[];
+}
+export type InstallRegistration = ClaudeInstallRegistration | CodexInstallRegistration;
 /**
  * The plugin keys a registration activates, whichever spelling recorded them.
  * A manifest written before collections carries only `pluginKey`.
@@ -134,6 +144,7 @@ export declare function installKey(record: {
 export interface InstallContext {
     home?: string;
     cwd?: string;
+    env?: NodeJS.ProcessEnv;
 }
 export interface ResolvedInstall {
     location: InstallLocation;
@@ -181,6 +192,8 @@ export declare function resolveScope(value: string | undefined, fallback?: Insta
  * anything else is resolved against `cwd`.
  */
 export declare function expandInstallRoot(root: string, context?: InstallContext): string;
+/** Resolves an install location, honoring a host-specific home override first. */
+export declare function expandInstallLocationRoot(location: InstallLocation, context?: InstallContext): string;
 export declare function locationFor(target: AgentTarget, scope: InstallScope): InstallLocation | null;
 /**
  * True when `relative` would land outside `root`. Lexical: a `..` segment or an
@@ -193,6 +206,13 @@ export declare function readInstallRecord(destination: string, key: string): Ins
 export declare function resolveInstallDestination(target: AgentTarget, scope: InstallScope, name: string, options?: {
     into?: string;
 } & InstallContext): ResolvedInstall | AgentDiagnostic;
+/**
+ * Checks host-side conflicts before a batch writes any files.
+ *
+ * In particular, `--force` never takes over a same-named Codex marketplace
+ * that points somewhere else: it is external state Cairn does not own.
+ */
+export declare function preflightInstallRegistrations(plans: InstallPlan[]): void;
 export declare function installIsCurrent(plan: InstallPlan): boolean;
 /** Options shared by every install plan in one run. */
 export interface PlanInstallOptions extends InstallContext {

package/dist/agent/install/index.js

@@ -1,4 +1,5 @@
 import crypto from "node:crypto";
+import { spawnSync } from "node:child_process";
 import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
@@ -122,6 +123,14 @@ export function expandInstallRoot(root, context = {}) {
         return path.resolve(cwd);
     return path.resolve(cwd, root);
 }
+/** Resolves an install location, honoring a host-specific home override first. */
+export function expandInstallLocationRoot(location, context = {}) {
+    const configured = location.environmentRoot;
+    const value = configured ? (context.env ?? process.env)[configured.variable] : undefined;
+    if (configured && value)
+        return path.resolve(value, configured.suffix);
+    return expandInstallRoot(location.root, context);
+}
 export function locationFor(target, scope) {
     return profileFor(target).install?.[scope] ?? null;
 }
@@ -241,19 +250,33 @@ function parseRecord(value) {
     const keys = Array.isArray(registration?.pluginKeys)
         ? registration.pluginKeys.filter((key) => typeof key === "string")
         : undefined;
-    const parsedRegistration = registration &&
+    const hasRegistrationKey = typeof registration?.pluginKey === "string" || keys !== undefined;
+    let parsedRegistration;
+    if (registration?.form === "codex-plugin-cli" &&
+        typeof registration.command === "string" &&
+        typeof registration.marketplaceKey === "string" &&
+        hasRegistrationKey)
+        parsedRegistration = {
+            form: "codex-plugin-cli",
+            command: registration.command,
+            marketplaceKey: registration.marketplaceKey,
+            ...(typeof registration.pluginKey === "string" ? { pluginKey: registration.pluginKey } : {}),
+            ...(keys ? { pluginKeys: keys } : {}),
+        };
+    else if (registration &&
+        (registration.form === undefined || registration.form === "claude-enabled-plugins") &&
         typeof registration.file === "string" &&
         typeof registration.marketplaceKey === "string" &&
-        (typeof registration.pluginKey === "string" || keys !== undefined)
-        ? {
+        hasRegistrationKey)
+        parsedRegistration = {
+            ...(registration.form === "claude-enabled-plugins"
+                ? { form: "claude-enabled-plugins" }
+                : {}),
             file: registration.file,
             marketplaceKey: registration.marketplaceKey,
-            ...(typeof registration.pluginKey === "string"
-                ? { pluginKey: registration.pluginKey }
-                : {}),
+            ...(typeof registration.pluginKey === "string" ? { pluginKey: registration.pluginKey } : {}),
             ...(keys ? { pluginKeys: keys } : {}),
-        }
-        : undefined;
+        };
     const collection = doc.collection;
     const plugins = collection && Array.isArray(collection.plugins)
         ? collection.plugins.flatMap((entry) => {
@@ -362,13 +385,11 @@ export function resolveInstallDestination(target, scope, name, options = {}) {
     if (!location)
         return error("AB800", `No recorded install location for ${target} ${scope} scope`, {
             target,
-            remediation: scope === "user" && target === "codex"
-                ? "Codex has no user-scope install; use --scope project, or pick another target."
-                : "Use a target and scope the profile declares, or pass --into only after one exists.",
+            remediation: "Use a target and scope the profile declares, or pass --into only after one exists.",
         });
     const locationRoot = options.into
         ? path.resolve(options.into)
-        : expandInstallRoot(location.root, options);
+        : expandInstallLocationRoot(location, options);
     const destination = location.layout === "merge" ? locationRoot : path.join(locationRoot, name);
     return { location, locationRoot, destination };
 }
@@ -430,7 +451,102 @@ function readJsonObject(file) {
         throw new Error(`Activation file is not a JSON object: ${file}`);
     return parsed;
 }
-function applyRegistration(settings, destination) {
+function isCodexRegistration(registration) {
+    return registration.form === "codex-plugin-cli";
+}
+function commandJson(command, args) {
+    const result = spawnSync(command, args, {
+        encoding: "utf8",
+        env: process.env,
+        maxBuffer: 1024 * 1024,
+    });
+    const invocation = [command, ...args].join(" ");
+    if (result.error)
+        throw new Error(`Failed to run '${invocation}': ${result.error.message}`);
+    if (result.status !== 0) {
+        const detail = (result.stderr || result.stdout).trim();
+        throw new Error(`Host command '${invocation}' exited ${result.status ?? "without a status"}${detail ? `: ${detail}` : ""}`);
+    }
+    try {
+        const parsed = JSON.parse(result.stdout);
+        if (!parsed || typeof parsed !== "object" || Array.isArray(parsed))
+            throw new Error("output is not an object");
+        return parsed;
+    }
+    catch (cause) {
+        throw new Error(`Host command '${invocation}' returned invalid JSON`, { cause });
+    }
+}
+function codexMarketplaces(registration) {
+    const value = commandJson(registration.command, [
+        "plugin",
+        "marketplace",
+        "list",
+        "--json",
+    ]).marketplaces;
+    if (!Array.isArray(value))
+        throw new Error("Codex marketplace list returned no marketplaces");
+    return value.flatMap((entry) => {
+        const row = entry;
+        return row && typeof row.name === "string" && typeof row.root === "string"
+            ? [{ name: row.name, root: row.root }]
+            : [];
+    });
+}
+function codexPlugins(registration) {
+    const value = commandJson(registration.command, ["plugin", "list", "--json"]).installed;
+    if (!Array.isArray(value))
+        throw new Error("Codex plugin list returned no installed plugins");
+    return value.flatMap((entry) => {
+        const row = entry;
+        return row && typeof row.pluginId === "string"
+            ? [
+                {
+                    pluginId: row.pluginId,
+                    ...(typeof row.version === "string" ? { version: row.version } : {}),
+                    installed: row.installed === true,
+                    enabled: row.enabled === true,
+                },
+            ]
+            : [];
+    });
+}
+function canonicalPath(file) {
+    try {
+        return fs.realpathSync(file);
+    }
+    catch {
+        return path.resolve(file);
+    }
+}
+function samePath(left, right) {
+    return canonicalPath(left) === canonicalPath(right);
+}
+function codexMarketplace(registration) {
+    return codexMarketplaces(registration).find((marketplace) => marketplace.name === registration.marketplaceKey);
+}
+/**
+ * Checks host-side conflicts before a batch writes any files.
+ *
+ * In particular, `--force` never takes over a same-named Codex marketplace
+ * that points somewhere else: it is external state Cairn does not own.
+ */
+export function preflightInstallRegistrations(plans) {
+    const checked = new Set();
+    for (const plan of plans) {
+        const registration = plan.settings;
+        if (!plan.register || !registration || !isCodexRegistration(registration))
+            continue;
+        const key = `${registration.command}\0${registration.marketplaceKey}\0${plan.destination}`;
+        if (checked.has(key))
+            continue;
+        checked.add(key);
+        const current = codexMarketplace(registration);
+        if (current && !samePath(current.root, plan.destination))
+            throw new Error(`Codex marketplace '${registration.marketplaceKey}' already points to ${current.root}; refusing to replace it with ${plan.destination}`);
+    }
+}
+function applyClaudeRegistration(settings, destination) {
     const current = readJsonObject(settings.file);
     const extra = {
         ...(current.extraKnownMarketplaces ?? {}),
@@ -449,7 +565,55 @@ function applyRegistration(settings, destination) {
         enabledPlugins: enabled,
     });
 }
-function revertRegistration(registration, destination) {
+function applyCodexRegistration(registration, destination) {
+    const marketplace = codexMarketplace(registration);
+    if (marketplace && !samePath(marketplace.root, destination))
+        throw new Error(`Codex marketplace '${registration.marketplaceKey}' already points to ${marketplace.root}; refusing to replace it with ${destination}`);
+    const installedBefore = new Set(codexPlugins(registration)
+        .filter((plugin) => plugin.installed)
+        .map((plugin) => plugin.pluginId));
+    const added = [];
+    try {
+        commandJson(registration.command, ["plugin", "marketplace", "add", destination, "--json"]);
+        for (const key of registeredPluginKeys(registration)) {
+            commandJson(registration.command, ["plugin", "add", key, "--json"]);
+            if (!installedBefore.has(key))
+                added.push(key);
+        }
+    }
+    catch (cause) {
+        for (const key of added.reverse()) {
+            try {
+                commandJson(registration.command, ["plugin", "remove", key, "--json"]);
+            }
+            catch {
+                // Best effort: preserve the original host failure.
+            }
+        }
+        if (!marketplace) {
+            try {
+                commandJson(registration.command, [
+                    "plugin",
+                    "marketplace",
+                    "remove",
+                    registration.marketplaceKey,
+                    "--json",
+                ]);
+            }
+            catch {
+                // Best effort: preserve the original host failure.
+            }
+        }
+        throw cause;
+    }
+}
+function applyRegistration(registration, destination) {
+    if (isCodexRegistration(registration))
+        applyCodexRegistration(registration, destination);
+    else
+        applyClaudeRegistration(registration, destination);
+}
+function revertClaudeRegistration(registration, destination) {
     if (!existsAt(registration.file))
         return;
     const current = readJsonObject(registration.file);
@@ -470,7 +634,54 @@ function revertRegistration(registration, destination) {
         enabledPlugins: enabled,
     });
 }
-function registrationCurrent(settings, destination) {
+function revertCodexRegistration(registration, destination) {
+    const marketplace = codexMarketplace(registration);
+    // The name now belongs to a different root. Removing either its plugins or
+    // the marketplace would mutate state Cairn did not install.
+    if (marketplace && !samePath(marketplace.root, destination))
+        return;
+    const installed = new Set(codexPlugins(registration)
+        .filter((plugin) => plugin.installed)
+        .map((plugin) => plugin.pluginId));
+    for (const key of registeredPluginKeys(registration))
+        if (installed.has(key))
+            commandJson(registration.command, ["plugin", "remove", key, "--json"]);
+    if (marketplace)
+        commandJson(registration.command, [
+            "plugin",
+            "marketplace",
+            "remove",
+            registration.marketplaceKey,
+            "--json",
+        ]);
+}
+function revertRegistration(registration, destination) {
+    if (isCodexRegistration(registration))
+        revertCodexRegistration(registration, destination);
+    else
+        revertClaudeRegistration(registration, destination);
+}
+function expectedPluginVersions(registration, record) {
+    if (record.kind === "collection" && record.collection)
+        return new Map(record.collection.plugins.map((plugin) => [
+            `${plugin.name}@${registration.marketplaceKey}`,
+            plugin.version,
+        ]));
+    return new Map(registeredPluginKeys(registration).map((key) => [key, record.bundle.version]));
+}
+function codexRegistrationCurrent(registration, destination, record) {
+    const marketplace = codexMarketplace(registration);
+    if (!marketplace || !samePath(marketplace.root, destination))
+        return false;
+    const installed = new Map(codexPlugins(registration).map((plugin) => [plugin.pluginId, plugin]));
+    for (const [key, version] of expectedPluginVersions(registration, record)) {
+        const plugin = installed.get(key);
+        if (!plugin?.installed || !plugin.enabled || plugin.version !== version)
+            return false;
+    }
+    return true;
+}
+function claudeRegistrationCurrent(settings, destination) {
     if (!existsAt(settings.file))
         return false;
     try {
@@ -484,6 +695,11 @@ function registrationCurrent(settings, destination) {
         return false;
     }
 }
+function registrationCurrent(settings, destination, record) {
+    return isCodexRegistration(settings)
+        ? codexRegistrationCurrent(settings, destination, record)
+        : claudeRegistrationCurrent(settings, destination);
+}
 function pruneEmptyAncestors(root, relative) {
     let current = path.dirname(path.join(root, relative));
     const stop = path.resolve(root);
@@ -518,7 +734,9 @@ export function installIsCurrent(plan) {
     // would leave --check reporting "current" while uninstall reports not-found.
     if (readInstallRecord(plan.destination, installKey(plan.record)) === "missing")
         return false;
-    if (plan.register && plan.settings && !registrationCurrent(plan.settings, plan.destination))
+    if (plan.register &&
+        plan.settings &&
+        !registrationCurrent(plan.settings, plan.destination, plan.record))
         return false;
     return true;
 }
@@ -581,6 +799,42 @@ function unresolvedPlan(bundle, target, scope, mode, resolved) {
         register: false,
     };
 }
+function registrationFor(location, marketplaceKey, pluginKeys, context, single) {
+    if (location.layout !== "marketplace" || !location.activation)
+        return undefined;
+    const keys = single ? { pluginKey: pluginKeys[0] } : { pluginKeys };
+    if (location.activation.form === "codex-plugin-cli")
+        return {
+            form: "codex-plugin-cli",
+            command: location.activation.command,
+            marketplaceKey,
+            ...keys,
+        };
+    return {
+        file: expandInstallRoot(location.activation.file, context),
+        marketplaceKey,
+        ...keys,
+    };
+}
+function activationDiagnostic(registration, destination, target) {
+    const keys = registeredPluginKeys(registration);
+    if (isCodexRegistration(registration)) {
+        const commands = [
+            `${registration.command} plugin marketplace add ${destination} --json`,
+            ...keys.map((key) => `${registration.command} plugin add ${key} --json`),
+        ];
+        return diagnostic("AB805", `Host activation required but --register was not given. Run: ${commands.join("; ")}.`, "unsupported", {
+            target,
+            path: destination,
+            remediation: "Re-run with --register, or run the reported Codex commands yourself.",
+        });
+    }
+    return diagnostic("AB805", `Host activation edit required but --register was not given. Add extraKnownMarketplaces.${registration.marketplaceKey} (directory ${destination}) and enabledPlugins for ${keys.join(", ")} to ${registration.file}.`, "unsupported", {
+        target,
+        path: registration.file,
+        remediation: "Re-run with --register, or apply the edit yourself.",
+    });
+}
 function draftInstall(bundle, target, options) {
     const scope = resolveScope(options.scope, "user");
     const resolved = resolveInstallDestination(target, scope, bundle.name, options);
@@ -602,23 +856,10 @@ function draftInstall(bundle, target, options) {
                 target,
                 profile: location.profile,
             }));
-    const settingsFile = location.activation
-        ? expandInstallRoot(location.activation.file, options)
-        : undefined;
-    const settings = location.layout === "marketplace" && settingsFile
-        ? {
-            file: settingsFile,
-            marketplaceKey: bundle.name,
-            pluginKey: `${bundle.name}@${bundle.name}`,
-        }
-        : undefined;
+    const settings = registrationFor(location, bundle.name, [`${bundle.name}@${bundle.name}`], options, true);
     const register = Boolean(options.register) && Boolean(settings);
     if (settings && !options.register)
-        diagnostics.push(diagnostic("AB805", `Host activation edit required but --register was not given. Add extraKnownMarketplaces.${bundle.name} (directory ${destination}) and enabledPlugins["${bundle.name}@${bundle.name}"] to ${settingsFile}.`, "unsupported", {
-            target,
-            path: settingsFile,
-            remediation: "Re-run with --register, or apply the edit yourself.",
-        }));
+        diagnostics.push(activationDiagnostic(settings, destination, target));
     if (mode === "link")
         diagnostics.push(diagnostic("AB807", "--link is in use; edits to the materialized tree are live and the host may not follow symlinks", "exact", { target, profile: location.profile, path: destination }));
     const materialized = mode === "link" ? path.join(bundle.root, INSTALL_CACHE, target, location.profile) : undefined;
@@ -840,20 +1081,11 @@ export function planCollectionInstall(collection, options = {}) {
                 target: collection.target,
                 profile: "plugin",
             }));
-    const settingsFile = location.activation
-        ? expandInstallRoot(location.activation.file, options)
-        : undefined;
     const pluginKeys = collection.plugins.map((plugin) => `${plugin.name}@${collection.name}`);
-    const settings = location.layout === "marketplace" && settingsFile
-        ? { file: settingsFile, marketplaceKey: collection.name, pluginKeys }
-        : undefined;
+    const settings = registrationFor(location, collection.name, pluginKeys, options, false);
     const register = Boolean(options.register) && Boolean(settings);
     if (settings && !options.register)
-        diagnostics.push(diagnostic("AB805", `Host activation edit required but --register was not given. Add extraKnownMarketplaces.${collection.name} (directory ${destination}) and enabledPlugins for ${pluginKeys.join(", ")} to ${settingsFile}.`, "unsupported", {
-            target: collection.target,
-            path: settingsFile,
-            remediation: "Re-run with --register, or apply the edit yourself.",
-        }));
+        diagnostics.push(activationDiagnostic(settings, destination, collection.target));
     if (mode === "link")
         diagnostics.push(diagnostic("AB807", "--link is in use; edits to the materialized tree are live and the host may not follow symlinks", "exact", { target: collection.target, profile: "plugin", path: destination }));
     const materialized = mode === "link" ? options.materializeInto : undefined;
@@ -971,6 +1203,19 @@ function retirePrior(plan) {
     if (previous.registration && !plan.record.registration)
         revertRegistration(previous.registration, plan.destination);
 }
+function restoreRegistrationRecordAfterFailure(plan) {
+    const key = installKey(plan.record);
+    const previous = plan.prior === "missing" || plan.prior === "malformed"
+        ? undefined
+        : plan.prior.installs.find((record) => installKey(record) === key)?.registration;
+    const installs = plan.document.installs.map((record) => {
+        if (installKey(record) !== key)
+            return record;
+        const { registration: _failed, ...without } = record;
+        return previous ? { ...without, registration: previous } : without;
+    });
+    writeJsonAtomically(path.join(plan.destination, INSTALL_MANIFEST), serializeDocument({ generator: currentGenerator(), installs: sortRecords(installs) }));
+}
 /** Writes a planned install. Caller must have already decided the run is not blocked. */
 export function commitInstall(plan) {
     retirePrior(plan);
@@ -979,7 +1224,15 @@ export function commitInstall(plan) {
     else
         writeCopy(plan);
     if (plan.register && plan.settings)
-        applyRegistration(plan.settings, plan.destination);
+        try {
+            applyRegistration(plan.settings, plan.destination);
+        }
+        catch (cause) {
+            // The filesystem install remains useful, but its manifest must not claim
+            // host activation that the driver just rolled back.
+            restoreRegistrationRecordAfterFailure(plan);
+            throw cause;
+        }
 }
 export function planToEntry(plan) {
     return toEntry(plan.record);
@@ -1086,6 +1339,10 @@ export function commitUninstall(plan) {
     if (!record)
         return;
     const destination = plan.destination;
+    // Host state is the harder-to-recover half. If its driver fails, leave the
+    // marketplace tree and manifest intact so a retry can still identify it.
+    if (record.registration)
+        revertRegistration(record.registration, destination);
     const document = readInstallDocument(destination);
     const key = installKey(record);
     const remaining = document === "missing" || document === "malformed"
@@ -1123,8 +1380,6 @@ export function commitUninstall(plan) {
     }
     if (record.materialized)
         removePath(record.materialized);
-    if (record.registration)
-        revertRegistration(record.registration, destination);
 }
 function scanRoot(target, scope, location, locationRoot) {
     const entries = [];
@@ -1164,7 +1419,7 @@ export function listInstalled(targets, options = {}) {
                 continue;
             const locationRoot = options.into
                 ? path.resolve(options.into)
-                : expandInstallRoot(location.root, options);
+                : expandInstallLocationRoot(location, options);
             entries.push(...scanRoot(target, scope, location, locationRoot));
         }
     }