@ai-agent-forge/agent-forge 0.85.0

package/dist/plugins/ecosystem/cli.js

@@ -0,0 +1,970 @@
+import { Buffer } from "node:buffer";
+import { buildPluginCatalogV1 } from "./catalog.js";
+import { DEFAULT_GLOBAL_PLUGIN_SCOPE_REF_V1 } from "./installer.js";
+import { isPluginAcquisitionRefTargetV1, PluginAcquisitionErrorV1, } from "./plugin-acquisition.js";
+import { createPluginSelectionV1, MAX_PLUGIN_SELECTION_IDS_V1 } from "./selection.js";
+export const PLUGIN_ECOSYSTEM_CLI_VERSION_V1 = 1;
+export const MAX_PLUGIN_ECOSYSTEM_CLI_OUTPUT_BYTES_V1 = 64 * 1024;
+export const MAX_PLUGIN_ECOSYSTEM_CLI_LIST_ENTRIES_V1 = 128;
+export const MAX_PLUGIN_ECOSYSTEM_CLI_ARGS_V1 = MAX_PLUGIN_SELECTION_IDS_V1 + 8;
+function invalidInput(message) {
+    throw new Error(message);
+}
+function validateToken(value, label) {
+    if (value.length === 0 || value.length > 256 || /[\u0000-\u001f\s]/u.test(value))
+        invalidInput(`${label} is invalid`);
+    return value;
+}
+function parseIdentity(value) {
+    const token = validateToken(value, "plugin identity");
+    const at = token.lastIndexOf("@");
+    if (at <= 0)
+        return { pluginId: token };
+    const pluginId = token.slice(0, at);
+    const pluginVersion = token.slice(at + 1);
+    if (pluginVersion.length === 0)
+        invalidInput("plugin version is invalid");
+    return {
+        pluginId: validateToken(pluginId, "plugin ID"),
+        pluginVersion: validateToken(pluginVersion, "plugin version"),
+    };
+}
+/** Parse only the ecosystem command grammar; legacy package commands are not accepted. */
+export function parsePluginEcosystemCliCommandV1(argv, defaultFormat = "text") {
+    if (!Array.isArray(argv) || argv.length === 0 || argv.length > MAX_PLUGIN_ECOSYSTEM_CLI_ARGS_V1)
+        invalidInput("ecosystem command is invalid");
+    let format = defaultFormat;
+    if (format !== "json" && format !== "text")
+        invalidInput("output format is invalid");
+    const args = [...argv];
+    let explicitFormat;
+    let scope;
+    let pluginIdsOption;
+    for (let index = args.length - 1; index >= 0; index -= 1) {
+        const token = args[index];
+        const inlineScope = token.startsWith("--scope=") ? token.slice("--scope=".length) : undefined;
+        const selectedScope = inlineScope ?? (token === "--scope" ? args[index + 1] : undefined);
+        if (selectedScope !== undefined) {
+            if (selectedScope !== "global" && selectedScope !== "project")
+                invalidInput("state scope is invalid");
+            if (scope !== undefined && scope !== selectedScope)
+                invalidInput("state scope is specified more than once");
+            scope = selectedScope;
+            args.splice(index, token === "--scope" ? 2 : 1);
+            continue;
+        }
+        const inlineFormat = token.startsWith("--format=") ? token.slice("--format=".length) : undefined;
+        const selected = token === "--json" || token === "--text"
+            ? token === "--json"
+                ? "json"
+                : "text"
+            : (inlineFormat ?? (token === "--format" ? args[index + 1] : undefined));
+        if (selected !== undefined) {
+            if (selected !== "json" && selected !== "text")
+                invalidInput("output format is invalid");
+            if (explicitFormat !== undefined && explicitFormat !== selected)
+                invalidInput("output format is specified more than once");
+            explicitFormat = selected;
+            format = explicitFormat;
+            args.splice(index, token === "--format" ? 2 : 1);
+            continue;
+        }
+        const inlinePlugins = token.startsWith("--plugins=") ? token.slice("--plugins=".length) : undefined;
+        const selectedPlugins = inlinePlugins ?? (token === "--plugins" ? args[index + 1] : undefined);
+        if (selectedPlugins !== undefined) {
+            if (pluginIdsOption !== undefined)
+                invalidInput("plugin IDs are specified more than once");
+            const ids = selectedPlugins.split(",");
+            if (ids.length > MAX_PLUGIN_SELECTION_IDS_V1)
+                invalidInput("too many plugin IDs");
+            pluginIdsOption = Object.freeze(ids.map((id) => validateToken(id, "plugin ID")));
+            args.splice(index, token === "--plugins" ? 2 : 1);
+        }
+    }
+    if (args.length === 0)
+        invalidInput("ecosystem command is invalid");
+    const [group, action, target, ...rest] = args;
+    if (group === "selection" && action === "set" && target !== undefined) {
+        if (pluginIdsOption !== undefined && rest.length > 0)
+            invalidInput("plugin IDs must use one input form");
+        const selectedPluginIds = pluginIdsOption ?? Object.freeze(rest.map((id) => validateToken(id, "plugin ID")));
+        if (selectedPluginIds.length > MAX_PLUGIN_SELECTION_IDS_V1)
+            invalidInput("too many plugin IDs");
+        return Object.freeze({
+            version: 1,
+            command: "selection-set",
+            format,
+            profileId: validateToken(target, "profile ID"),
+            selectedPluginIds,
+            ...(scope === undefined ? {} : { scope }),
+        });
+    }
+    if (rest.length > 0)
+        invalidInput("ecosystem command has unsupported arguments");
+    if (group === "catalog" && action === "list" && target === undefined)
+        return Object.freeze({
+            version: 1,
+            command: "catalog-list",
+            format,
+            ...(scope === undefined ? {} : { scope }),
+        });
+    if (group === "state" && action === "list" && target === undefined)
+        return Object.freeze({
+            version: 1,
+            command: "state-list",
+            format,
+            ...(scope === undefined ? {} : { scope }),
+        });
+    if (group === "selection" && action === "list" && target === undefined)
+        return Object.freeze({
+            version: 1,
+            command: "selection-list",
+            format,
+            ...(scope === undefined ? {} : { scope }),
+        });
+    if (group === "selection" && action === "clear" && target !== undefined)
+        return Object.freeze({
+            version: 1,
+            command: "selection-clear",
+            format,
+            profileId: validateToken(target, "profile ID"),
+            ...(scope === undefined ? {} : { scope }),
+        });
+    if (group === "state" && (action === "enable" || action === "disable" || action === "remove") && target) {
+        const identity = parseIdentity(target);
+        return Object.freeze({
+            version: 1,
+            command: action,
+            format,
+            ...(scope === undefined ? {} : { scope }),
+            ...identity,
+        });
+    }
+    // Top-level aliases keep the common install/remove workflow concise while
+    // preserving the explicit `state <action>` grammar for scripts.
+    if ((group === "enable" || group === "disable" || group === "remove") && action) {
+        const identity = parseIdentity(action);
+        return Object.freeze({
+            version: 1,
+            command: group,
+            format,
+            ...(scope === undefined ? {} : { scope }),
+            ...identity,
+        });
+    }
+    // Install/update keeps the legacy `pluginId[@version]` identity grammar and
+    // additionally preserves the raw target: refs with npm/path/URL markers
+    // (`/`, `:`, `#`, leading `@`, `@^…`/`@~…`/`@latest`) route to the
+    // acquisition boundary; bare IDs and exact-version identities keep the
+    // registry resolve path unchanged.
+    if ((group === "install" || group === "update") && action) {
+        const identity = parseIdentity(action);
+        return Object.freeze({
+            version: 1,
+            command: group,
+            format,
+            target: action,
+            ...(scope === undefined ? {} : { scope }),
+            ...identity,
+        });
+    }
+    invalidInput("ecosystem command is invalid");
+}
+function response(command, format, status, error, data) {
+    let safeData = data === undefined ? undefined : boundData(data);
+    if (safeData !== undefined && Array.isArray(safeData.entries)) {
+        let entries = [...safeData.entries];
+        const originalEntryCount = entries.length;
+        while (entries.length > 0) {
+            const candidate = {
+                ...safeData,
+                entries,
+                ...(entries.length < safeData.entries.length ? { truncated: true } : {}),
+            };
+            if (responseWithinBudget(command, format, status, error, candidate)) {
+                safeData = Object.freeze(candidate);
+                break;
+            }
+            entries = entries.slice(0, -1);
+        }
+        if (entries.length === 0 && originalEntryCount > 0)
+            safeData = Object.freeze({
+                entries: Object.freeze([]),
+                truncated: true,
+            });
+    }
+    if (!responseWithinBudget(command, format, status, error, safeData))
+        safeData = Object.freeze({ truncated: true });
+    const base = responseBase(command, format, status, error, safeData);
+    const humanText = error ? `${status}: ${error.message}` : formatText(command, status, safeData);
+    const text = format === "json" ? JSON.stringify(base) : humanText;
+    return Object.freeze({
+        ...base,
+        text: boundText(text),
+    });
+}
+function responseWithinBudget(command, format, status, error, data) {
+    const base = responseBase(command, format, status, error, data);
+    const humanText = error ? `${status}: ${error.message}` : formatText(command, status, data);
+    const text = format === "json" ? JSON.stringify(base) : humanText;
+    return responseByteLength({ ...base, text: boundText(text) }) <= MAX_PLUGIN_ECOSYSTEM_CLI_OUTPUT_BYTES_V1;
+}
+function responseBase(command, format, status, error, data) {
+    return {
+        version: PLUGIN_ECOSYSTEM_CLI_VERSION_V1,
+        command,
+        format,
+        status,
+        ...(data === undefined ? {} : { data }),
+        ...(error === undefined ? {} : { error }),
+    };
+}
+function responseByteLength(value) {
+    return Buffer.byteLength(JSON.stringify(value), "utf8");
+}
+function boundText(value) {
+    if (Buffer.byteLength(value, "utf8") <= MAX_PLUGIN_ECOSYSTEM_CLI_OUTPUT_BYTES_V1)
+        return value;
+    const suffix = "\n[output truncated]";
+    let lower = 0;
+    let upper = value.length;
+    while (lower < upper) {
+        const middle = Math.ceil((lower + upper) / 2);
+        if (Buffer.byteLength(`${value.slice(0, middle)}${suffix}`, "utf8") <= MAX_PLUGIN_ECOSYSTEM_CLI_OUTPUT_BYTES_V1)
+            lower = middle;
+        else
+            upper = middle - 1;
+    }
+    return `${value.slice(0, lower)}${suffix}`;
+}
+function boundData(data) {
+    const list = data.entries;
+    if (!Array.isArray(list) || list.length <= MAX_PLUGIN_ECOSYSTEM_CLI_LIST_ENTRIES_V1)
+        return Object.freeze({ ...data });
+    return Object.freeze({
+        ...data,
+        entries: Object.freeze(list.slice(0, MAX_PLUGIN_ECOSYSTEM_CLI_LIST_ENTRIES_V1)),
+        truncated: true,
+    });
+}
+function formatText(command, status, data) {
+    if (data === undefined)
+        return `${status}: ${command}`;
+    const entries = data.entries;
+    if (Array.isArray(entries)) {
+        const lines = entries.map((entry) => {
+            if (typeof entry !== "object" || entry === null)
+                return String(entry);
+            const item = entry;
+            const id = typeof item.profileId === "string"
+                ? `profile:${item.profileId}`
+                : typeof item.pluginId === "string"
+                    ? item.pluginId
+                    : "plugin";
+            const version = typeof item.pluginVersion === "string" ? `@${item.pluginVersion}` : "";
+            const state = typeof item.status === "string"
+                ? ` ${item.status}`
+                : typeof item.lifecycle === "string"
+                    ? ` ${item.lifecycle}`
+                    : "";
+            return `${id}${version}${state}`;
+        });
+        return [`${status}: ${command}`, ...lines, ...(data.truncated === true ? ["[output truncated]"] : [])].join("\n");
+    }
+    if (typeof data.profileId === "string") {
+        const selected = Array.isArray(data.selectedPluginIds) ? ` selected=${data.selectedPluginIds.join(",")}` : "";
+        const disabled = Array.isArray(data.disabledPluginIds) ? ` disabled=${data.disabledPluginIds.join(",")}` : "";
+        return `${status}: ${command} profile:${data.profileId}${selected}${disabled}`;
+    }
+    return `${status}: ${command}`;
+}
+function safeError(code) {
+    const messages = {
+        invalid_command: "The plugin ecosystem command is invalid",
+        unsupported_dependencies: "The plugin ecosystem operation is unavailable on this host",
+        not_found: "The requested plugin was not found",
+        not_installed: "The requested plugin is not installed",
+        registry_failed: "The plugin registry operation failed",
+        acquisition_failed: "The plugin package acquisition failed",
+        distribution_failed: "The plugin distribution operation failed",
+        incompatible: "The requested plugin is incompatible with this host",
+        already_installed: "This plugin version is already installed in the requested scope",
+        installer_failed: "The plugin installer operation failed",
+        uninstall_failed: "The host plugin uninstall operation failed",
+        state_failed: "The plugin state operation failed",
+        selection_failed: "The plugin selection operation failed",
+        cancelled: "Plugin ecosystem operation was cancelled",
+    };
+    return Object.freeze({ code, message: messages[code] });
+}
+function isCancelled(signal) {
+    return signal?.aborted === true;
+}
+function stateStoreOf(options, scope) {
+    if (scope === "project")
+        return options.projectStateStore;
+    return options.stateStore ?? options.stateHost;
+}
+function operationScope(scope) {
+    return scope ?? "global";
+}
+function scopeRefOf(options, scope) {
+    return scope === "global" ? DEFAULT_GLOBAL_PLUGIN_SCOPE_REF_V1 : options.projectScopeRef;
+}
+function installerSupportsScope(installer, scope) {
+    return installer?.supportedScopes?.includes(scope) === true;
+}
+function selectionStoreOf(options, scope) {
+    if (scope === "project")
+        return options.projectSelectionStore;
+    return options.selectionStore ?? options.selectionHost;
+}
+function stateEntry(record) {
+    return Object.freeze({
+        pluginId: record.pluginId,
+        pluginVersion: record.pluginVersion,
+        manifestDigest: record.manifestDigest,
+        scope: record.state.scope,
+        scopeRef: record.state.scopeRef,
+        enabled: record.state.enabled,
+        lifecycle: record.state.lifecycle,
+        ...(record.source === undefined ? {} : { source: record.source }),
+    });
+}
+function selectionEntry(selection) {
+    return Object.freeze({
+        profileId: selection.profileId,
+        selectedPluginIds: Object.freeze([...selection.selectedPluginIds]),
+        disabledPluginIds: Object.freeze([...selection.disabledPluginIds]),
+    });
+}
+function catalogEntry(entry) {
+    return Object.freeze({
+        pluginId: entry.pluginId,
+        pluginVersion: entry.pluginVersion,
+        manifestDigest: entry.manifestDigest,
+        status: entry.resolution.status,
+        diagnosticCodes: Object.freeze(entry.resolution.diagnostics.map((item) => item.code).slice(0, 16)),
+    });
+}
+function findStateRecord(records, pluginId, pluginVersion, scope, scopeRef) {
+    return records.find((record) => record.pluginId === pluginId &&
+        (pluginVersion === undefined || record.pluginVersion === pluginVersion) &&
+        (scope === undefined || record.state.scope === scope) &&
+        (scopeRef === undefined || record.state.scopeRef === scopeRef));
+}
+function findCurrentStateRecord(records, pluginId, scope, scopeRef) {
+    return (records.find((record) => record.pluginId === pluginId &&
+        (scope === undefined || record.state.scope === scope) &&
+        (scopeRef === undefined || record.state.scopeRef === scopeRef) &&
+        record.state.lifecycle === "active") ?? findStateRecord(records, pluginId, undefined, scope, scopeRef));
+}
+function requireDependencies(options, scope, scopeRef) {
+    const requestedScope = operationScope(scope);
+    if (!options.registry ||
+        !options.installer ||
+        scopeRef === undefined ||
+        !installerSupportsScope(options.installer, requestedScope) ||
+        !stateStoreOf(options, requestedScope) ||
+        !options.host)
+        throw new Error("unsupported dependencies");
+}
+async function listManifests(options, signal) {
+    if (options.registry?.list)
+        return await options.registry.list({ signal });
+    if (options.manifests)
+        return options.manifests;
+    throw new Error("unsupported dependencies");
+}
+function checkSignal(signal) {
+    if (isCancelled(signal))
+        throw new Error("cancelled");
+}
+export function createPluginEcosystemCliV1(options) {
+    // Host installation and state persistence are a single logical transaction.
+    // Serializing them prevents two same-version requests from both passing the
+    // preflight state read and orphaning one physical installation.
+    let installTransactionTail = Promise.resolve();
+    async function acquireInstallTransaction() {
+        let release;
+        const turn = new Promise((resolve) => {
+            release = resolve;
+        });
+        const previous = installTransactionTail;
+        installTransactionTail = previous.then(() => turn, () => turn);
+        await previous;
+        return release;
+    }
+    async function execute(input) {
+        let parsed;
+        try {
+            parsed = parsePluginEcosystemCliCommandV1(input.argv, input.format ?? "text");
+        }
+        catch {
+            return response("invalid", input.format === "json" ? "json" : "text", "failed", safeError("invalid_command"));
+        }
+        const releaseInstallTransaction = parsed.command === "install" || parsed.command === "update" ? await acquireInstallTransaction() : undefined;
+        try {
+            const signal = input.signal;
+            const requestedScope = operationScope(parsed.scope);
+            const scopeRef = scopeRefOf(options, requestedScope);
+            if (isCancelled(signal))
+                return response(parsed.command, parsed.format, "cancelled", safeError("cancelled"));
+            if (scopeRef === undefined)
+                return response(parsed.command, parsed.format, "unsupported", safeError("unsupported_dependencies"));
+            let phase = "registry";
+            try {
+                if (parsed.command === "catalog-list") {
+                    if (!options.host)
+                        return response(parsed.command, parsed.format, "unsupported", safeError("unsupported_dependencies"));
+                    const manifests = await listManifests(options, signal);
+                    checkSignal(signal);
+                    const snapshot = buildPluginCatalogV1({
+                        manifests,
+                        host: options.host,
+                        maxEntries: MAX_PLUGIN_ECOSYSTEM_CLI_LIST_ENTRIES_V1,
+                    });
+                    return response(parsed.command, parsed.format, "succeeded", undefined, {
+                        version: snapshot.version,
+                        entries: snapshot.entries.map(catalogEntry),
+                        truncated: snapshot.truncated,
+                    });
+                }
+                if (parsed.command === "selection-list") {
+                    phase = "selection";
+                    const selectionStore = selectionStoreOf(options, parsed.scope);
+                    if (!selectionStore)
+                        return response(parsed.command, parsed.format, "unsupported", safeError("unsupported_dependencies"));
+                    const result = await selectionStore.read({ signal });
+                    if (result.status === "cancelled")
+                        return response(parsed.command, parsed.format, "cancelled", safeError("cancelled"));
+                    if (result.status === "invalid")
+                        return response(parsed.command, parsed.format, "failed", safeError("selection_failed"));
+                    return response(parsed.command, parsed.format, "succeeded", undefined, {
+                        version: result.snapshot.version,
+                        scope: parsed.scope ?? "global",
+                        entries: result.snapshot.selections.map(selectionEntry),
+                        truncated: false,
+                    });
+                }
+                if (parsed.command === "selection-set") {
+                    phase = "selection";
+                    const selectionStore = selectionStoreOf(options, parsed.scope);
+                    if (!selectionStore)
+                        return response(parsed.command, parsed.format, "unsupported", safeError("unsupported_dependencies"));
+                    let selection;
+                    try {
+                        selection = createPluginSelectionV1({
+                            profileId: parsed.profileId,
+                            selectedPluginIds: parsed.selectedPluginIds ?? [],
+                            disabledPluginIds: [],
+                        });
+                    }
+                    catch {
+                        return response(parsed.command, parsed.format, "failed", safeError("selection_failed"));
+                    }
+                    const result = await selectionStore.set({ selection, signal });
+                    if (result.status === "cancelled")
+                        return response(parsed.command, parsed.format, "cancelled", safeError("cancelled"));
+                    if (result.status !== "ok")
+                        return response(parsed.command, parsed.format, "failed", safeError("selection_failed"));
+                    return response(parsed.command, parsed.format, "succeeded", undefined, {
+                        profileId: selection.profileId,
+                        scope: parsed.scope ?? "global",
+                        selectedPluginIds: selection.selectedPluginIds,
+                        disabledPluginIds: selection.disabledPluginIds,
+                        changed: result.changed,
+                    });
+                }
+                if (parsed.command === "selection-clear") {
+                    phase = "selection";
+                    const selectionStore = selectionStoreOf(options, parsed.scope);
+                    if (!selectionStore)
+                        return response(parsed.command, parsed.format, "unsupported", safeError("unsupported_dependencies"));
+                    const result = await selectionStore.clear({
+                        profileId: parsed.profileId,
+                        signal,
+                    });
+                    if (result.status === "cancelled")
+                        return response(parsed.command, parsed.format, "cancelled", safeError("cancelled"));
+                    if (result.status !== "ok")
+                        return response(parsed.command, parsed.format, "failed", safeError("selection_failed"));
+                    return response(parsed.command, parsed.format, "succeeded", undefined, {
+                        profileId: parsed.profileId,
+                        scope: parsed.scope ?? "global",
+                        changed: result.changed,
+                    });
+                }
+                if (parsed.command === "state-list") {
+                    phase = "state";
+                    const stateStore = stateStoreOf(options, requestedScope);
+                    if (!stateStore)
+                        return response(parsed.command, parsed.format, "unsupported", safeError("unsupported_dependencies"));
+                    const result = await stateStore.read({ signal });
+                    if (result.status === "cancelled")
+                        return response(parsed.command, parsed.format, "cancelled", safeError("cancelled"));
+                    if (result.status === "invalid")
+                        return response(parsed.command, parsed.format, "failed", safeError("state_failed"));
+                    const records = result.snapshot.records.filter((record) => record.state.scope === requestedScope && record.state.scopeRef === scopeRef);
+                    return response(parsed.command, parsed.format, "succeeded", undefined, {
+                        version: result.snapshot.version,
+                        entries: records.map(stateEntry),
+                        truncated: false,
+                    });
+                }
+                if (parsed.command === "enable" || parsed.command === "disable" || parsed.command === "remove") {
+                    phase = "state";
+                    if (parsed.command === "remove" &&
+                        requestedScope === "project" &&
+                        !installerSupportsScope(options.installer, requestedScope))
+                        return response(parsed.command, parsed.format, "unsupported", safeError("unsupported_dependencies"));
+                    const stateStore = stateStoreOf(options, requestedScope);
+                    if (!stateStore)
+                        return response(parsed.command, parsed.format, "unsupported", safeError("unsupported_dependencies"));
+                    const current = await stateStore.read({ signal });
+                    if (current.status === "cancelled")
+                        return response(parsed.command, parsed.format, "cancelled", safeError("cancelled"));
+                    if (current.status === "invalid")
+                        return response(parsed.command, parsed.format, "failed", safeError("state_failed"));
+                    const record = parsed.pluginVersion === undefined
+                        ? findCurrentStateRecord(current.snapshot.records, parsed.pluginId, requestedScope, scopeRef)
+                        : findStateRecord(current.snapshot.records, parsed.pluginId, parsed.pluginVersion, requestedScope, scopeRef);
+                    if (!record)
+                        return response(parsed.command, parsed.format, "failed", safeError("not_installed"));
+                    if (parsed.command === "remove") {
+                        // Global state-only removal remains available for repairing stale records.
+                        // Project removal requires a scope-capable installer and host cleanup first.
+                        if (options.installer !== undefined) {
+                            let removedFromHost;
+                            try {
+                                removedFromHost = await options.installer.remove({
+                                    installation: {
+                                        version: 1,
+                                        pluginId: record.pluginId,
+                                        pluginVersion: record.pluginVersion,
+                                        manifestDigest: record.manifestDigest,
+                                        scope: record.state.scope,
+                                        scopeRef: record.state.scopeRef,
+                                        installationRef: record.installationRef,
+                                        state: record.state.lifecycle,
+                                    },
+                                    scope: requestedScope,
+                                    scopeRef,
+                                    signal,
+                                });
+                            }
+                            catch {
+                                return response(parsed.command, parsed.format, "failed", safeError("uninstall_failed"));
+                            }
+                            if (removedFromHost.status !== "succeeded")
+                                return response(parsed.command, parsed.format, removedFromHost.status === "cancelled" ? "cancelled" : "failed", safeError(removedFromHost.status === "cancelled" ? "cancelled" : "uninstall_failed"));
+                        }
+                        const removed = await stateStore.remove({
+                            pluginId: record.pluginId,
+                            pluginVersion: record.pluginVersion,
+                            scope: requestedScope,
+                            scopeRef,
+                            signal,
+                        });
+                        if (removed.status === "cancelled")
+                            return response(parsed.command, parsed.format, "cancelled", safeError("cancelled"));
+                        if (removed.status !== "ok")
+                            return response(parsed.command, parsed.format, "failed", safeError("state_failed"));
+                        return response(parsed.command, parsed.format, "succeeded", undefined, {
+                            pluginId: record.pluginId,
+                            pluginVersion: record.pluginVersion,
+                            ...(options.installer === undefined ? {} : { hostRemoved: true }),
+                            changed: removed.changed,
+                        });
+                    }
+                    const enabled = parsed.command === "enable";
+                    const updated = await stateStore.upsert({
+                        installation: {
+                            version: 1,
+                            pluginId: record.pluginId,
+                            pluginVersion: record.pluginVersion,
+                            manifestDigest: record.manifestDigest,
+                            scope: record.state.scope,
+                            scopeRef: record.state.scopeRef,
+                            installationRef: record.installationRef,
+                            state: record.state.lifecycle,
+                        },
+                        scope: requestedScope,
+                        enabled,
+                        ...(record.source === undefined ? {} : { source: record.source }),
+                        signal,
+                    });
+                    if (updated.status === "cancelled")
+                        return response(parsed.command, parsed.format, "cancelled", safeError("cancelled"));
+                    if (updated.status !== "ok")
+                        return response(parsed.command, parsed.format, "failed", safeError("state_failed"));
+                    return response(parsed.command, parsed.format, "succeeded", undefined, {
+                        pluginId: record.pluginId,
+                        pluginVersion: record.pluginVersion,
+                        enabled,
+                        changed: updated.changed,
+                    });
+                }
+                // install/update must have every host boundary injected. They never claim success with partial services.
+                const stateStore = stateStoreOf(options, requestedScope);
+                // Const locals keep the narrowing alive inside the shared install flow closure.
+                const installer = options.installer;
+                const host = options.host;
+                const acquisitionTarget = parsed.command === "install" &&
+                    parsed.target !== undefined &&
+                    isPluginAcquisitionRefTargetV1(parsed.target)
+                    ? parsed.target
+                    : undefined;
+                if (!stateStore ||
+                    !installer ||
+                    !host ||
+                    !installerSupportsScope(installer, requestedScope) ||
+                    (acquisitionTarget === undefined && !options.registry))
+                    return response(parsed.command, parsed.format, "unsupported", safeError("unsupported_dependencies"));
+                // One shared install transaction serves both resolutions: the legacy
+                // registry resolve path and the multi-source acquisition ref path.
+                const runInstallFlow = async (resolved) => {
+                    phase = "state";
+                    const current = await stateStore.read({ signal });
+                    if (current.status === "cancelled")
+                        return response(parsed.command, parsed.format, "cancelled", safeError("cancelled"));
+                    if (current.status === "invalid")
+                        return response(parsed.command, parsed.format, "failed", safeError("state_failed"));
+                    const previous = findCurrentStateRecord(current.snapshot.records, resolved.manifest.id, requestedScope, scopeRef);
+                    const installedVersion = findStateRecord(current.snapshot.records, resolved.manifest.id, resolved.manifest.pluginVersion, requestedScope, scopeRef);
+                    if (installedVersion !== undefined)
+                        return response(parsed.command, parsed.format, "failed", safeError("already_installed"));
+                    if (parsed.command === "update" && (!previous || previous.state.lifecycle !== "active"))
+                        return response(parsed.command, parsed.format, "failed", safeError("not_installed"));
+                    phase = "installer";
+                    const verified = installer.prepare({
+                        manifest: resolved.manifest,
+                        source: resolved.source,
+                        host,
+                        ...(resolved.expectedDigest === undefined ? {} : { expectedDigest: resolved.expectedDigest }),
+                    });
+                    if (verified.status !== "verified")
+                        return response(parsed.command, parsed.format, "failed", safeError("incompatible"));
+                    let artifact = resolved.acquired?.artifact;
+                    if (resolved.distribution !== undefined) {
+                        if (options.distribution === undefined)
+                            return response(parsed.command, parsed.format, "unsupported", safeError("unsupported_dependencies"));
+                        phase = "distribution";
+                        const descriptor = options.distribution.validateDescriptor(resolved.distribution);
+                        if (descriptor.pluginId !== verified.record.pluginId ||
+                            descriptor.pluginVersion !== verified.record.pluginVersion ||
+                            descriptor.manifestDigest !== verified.record.manifestDigest)
+                            return response(parsed.command, parsed.format, "failed", safeError("incompatible"));
+                        artifact = await options.distribution.acquireArtifact({
+                            descriptor,
+                            signal,
+                        });
+                    }
+                    let artifactReleased = false;
+                    const releaseArtifact = async () => {
+                        if (artifact === undefined || artifactReleased)
+                            return true;
+                        const previousPhase = phase;
+                        phase = "distribution";
+                        try {
+                            if (resolved.acquired !== undefined) {
+                                // Acquisition artifacts are owned by the acquisition boundary.
+                                const released = await resolved.acquired.release();
+                                if (!released)
+                                    return false;
+                                artifactReleased = true;
+                                phase = previousPhase;
+                                return true;
+                            }
+                            // Cleanup must complete even after the caller has cancelled the workflow.
+                            if (options.distribution === undefined)
+                                return false;
+                            await options.distribution.releaseArtifact({ artifact });
+                            artifactReleased = true;
+                            phase = previousPhase;
+                            return true;
+                        }
+                        catch {
+                            return false;
+                        }
+                    };
+                    let transactionResponse;
+                    let transactionError;
+                    let artifactCleanupFailed = false;
+                    try {
+                        transactionResponse = await (async () => {
+                            checkSignal(signal);
+                            phase = "installer";
+                            const installed = await installer.install({
+                                record: verified.record,
+                                scope: requestedScope,
+                                scopeRef,
+                                ...(artifact === undefined ? {} : { artifact }),
+                                signal,
+                            });
+                            if (installed.status !== "succeeded") {
+                                if (!(await releaseArtifact()))
+                                    return response(parsed.command, parsed.format, isCancelled(signal) ? "cancelled" : "failed", safeError(isCancelled(signal) ? "cancelled" : "distribution_failed"));
+                                return response(parsed.command, parsed.format, installed.status === "cancelled" ? "cancelled" : "failed", safeError(installed.status === "cancelled" ? "cancelled" : "installer_failed"));
+                            }
+                            const activated = await installer.activate({
+                                installation: installed.installation,
+                                record: verified.record,
+                                scope: requestedScope,
+                                scopeRef,
+                                signal,
+                            });
+                            if (activated.status !== "succeeded") {
+                                if (previous && previous.state.lifecycle === "active") {
+                                    const rollback = await installer.rollback({
+                                        failed: installed.installation,
+                                        previous: {
+                                            version: 1,
+                                            pluginId: previous.pluginId,
+                                            pluginVersion: previous.pluginVersion,
+                                            manifestDigest: previous.manifestDigest,
+                                            scope: previous.state.scope,
+                                            scopeRef: previous.state.scopeRef,
+                                            installationRef: previous.installationRef,
+                                            state: "active",
+                                        },
+                                        scope: requestedScope,
+                                        scopeRef,
+                                        signal: undefined,
+                                    });
+                                    if (rollback.status !== "succeeded")
+                                        return response(parsed.command, parsed.format, "failed", safeError("installer_failed"));
+                                }
+                                const removed = await installer.remove({
+                                    installation: installed.installation,
+                                    scope: requestedScope,
+                                    scopeRef,
+                                });
+                                if (removed.status !== "succeeded")
+                                    return response(parsed.command, parsed.format, "failed", safeError("installer_failed"));
+                                if (!(await releaseArtifact()))
+                                    return response(parsed.command, parsed.format, isCancelled(signal) ? "cancelled" : "failed", safeError(isCancelled(signal) ? "cancelled" : "distribution_failed"));
+                                return response(parsed.command, parsed.format, activated.status === "cancelled" ? "cancelled" : "failed", safeError(activated.status === "cancelled" ? "cancelled" : "installer_failed"));
+                            }
+                            const restoreActivatedInstallation = async () => {
+                                const replacesPrevious = previous !== undefined &&
+                                    `${previous.pluginId}@${previous.pluginVersion}` !==
+                                        `${activated.installation.pluginId}@${activated.installation.pluginVersion}`;
+                                if (replacesPrevious && previous.state.lifecycle === "active") {
+                                    const rollback = await installer.rollback({
+                                        failed: activated.installation,
+                                        previous: {
+                                            version: 1,
+                                            pluginId: previous.pluginId,
+                                            pluginVersion: previous.pluginVersion,
+                                            manifestDigest: previous.manifestDigest,
+                                            scope: previous.state.scope,
+                                            scopeRef: previous.state.scopeRef,
+                                            installationRef: previous.installationRef,
+                                            state: "active",
+                                        },
+                                        scope: requestedScope,
+                                        scopeRef,
+                                    });
+                                    if (rollback.status !== "succeeded")
+                                        return false;
+                                }
+                                if (previous !== undefined && !replacesPrevious)
+                                    return true;
+                                const removed = await installer.remove({
+                                    installation: activated.installation,
+                                    scope: requestedScope,
+                                    scopeRef,
+                                });
+                                return removed.status === "succeeded";
+                            };
+                            const restoreState = async () => {
+                                const replacesPrevious = previous !== undefined &&
+                                    `${previous.pluginId}@${previous.pluginVersion}` !==
+                                        `${activated.installation.pluginId}@${activated.installation.pluginVersion}`;
+                                let restored = true;
+                                if (previous === undefined || replacesPrevious) {
+                                    const removed = await stateStore
+                                        .remove({
+                                        pluginId: activated.installation.pluginId,
+                                        pluginVersion: activated.installation.pluginVersion,
+                                        scope: requestedScope,
+                                        scopeRef,
+                                    })
+                                        .catch(() => undefined);
+                                    restored = removed?.status === "ok";
+                                }
+                                if (previous !== undefined) {
+                                    const restoredPrevious = await stateStore
+                                        .upsert({
+                                        installation: {
+                                            version: 1,
+                                            pluginId: previous.pluginId,
+                                            pluginVersion: previous.pluginVersion,
+                                            manifestDigest: previous.manifestDigest,
+                                            scope: previous.state.scope,
+                                            scopeRef: previous.state.scopeRef,
+                                            installationRef: previous.installationRef,
+                                            state: "active",
+                                        },
+                                        scope: requestedScope,
+                                        enabled: previous.state.enabled,
+                                        ...(previous.source === undefined ? {} : { source: previous.source }),
+                                    })
+                                        .catch(() => undefined);
+                                    restored = restored && restoredPrevious?.status === "ok";
+                                }
+                                return restored;
+                            };
+                            const stateFailure = async (status) => {
+                                const [hostRestored, stateRestored] = await Promise.all([
+                                    restoreActivatedInstallation().catch(() => false),
+                                    restoreState().catch(() => false),
+                                ]);
+                                return response(parsed.command, parsed.format, hostRestored && stateRestored ? status : "failed", safeError(hostRestored && stateRestored
+                                    ? status === "cancelled"
+                                        ? "cancelled"
+                                        : "state_failed"
+                                    : "installer_failed"));
+                            };
+                            if (!(await releaseArtifact())) {
+                                phase = "installer";
+                                const restored = await restoreActivatedInstallation().catch(() => false);
+                                return response(parsed.command, parsed.format, "failed", safeError(restored ? "distribution_failed" : "installer_failed"));
+                            }
+                            phase = "state";
+                            if (previous &&
+                                `${previous.pluginId}@${previous.pluginVersion}` !==
+                                    `${installed.installation.pluginId}@${installed.installation.pluginVersion}`) {
+                                const retained = await stateStore.upsert({
+                                    installation: {
+                                        version: 1,
+                                        pluginId: previous.pluginId,
+                                        pluginVersion: previous.pluginVersion,
+                                        manifestDigest: previous.manifestDigest,
+                                        scope: previous.state.scope,
+                                        scopeRef: previous.state.scopeRef,
+                                        installationRef: previous.installationRef,
+                                        state: "retained",
+                                    },
+                                    scope: requestedScope,
+                                    enabled: previous.state.enabled,
+                                    ...(previous.source === undefined ? {} : { source: previous.source }),
+                                    signal: undefined,
+                                });
+                                if (retained.status !== "ok")
+                                    return await stateFailure("failed");
+                            }
+                            const persisted = await stateStore.upsert({
+                                installation: activated.installation,
+                                scope: requestedScope,
+                                enabled: previous?.state.enabled ?? true,
+                                ...(resolved.acquired === undefined ? {} : { source: resolved.source }),
+                                signal,
+                            });
+                            if (persisted.status === "cancelled")
+                                return await stateFailure("cancelled");
+                            if (persisted.status !== "ok")
+                                return await stateFailure("failed");
+                            return response(parsed.command, parsed.format, "succeeded", undefined, {
+                                pluginId: activated.installation.pluginId,
+                                pluginVersion: activated.installation.pluginVersion,
+                                lifecycle: "active",
+                                changed: persisted.changed,
+                                ...(resolved.acquired === undefined ? {} : { source: resolved.source }),
+                            });
+                        })();
+                    }
+                    catch (error) {
+                        transactionError = error;
+                    }
+                    finally {
+                        artifactCleanupFailed = !(await releaseArtifact());
+                    }
+                    if (artifactCleanupFailed)
+                        return response(parsed.command, parsed.format, "failed", safeError("distribution_failed"));
+                    if (transactionError !== undefined)
+                        throw transactionError;
+                    if (transactionResponse === undefined)
+                        throw new Error("plugin installation transaction did not complete");
+                    return transactionResponse;
+                };
+                if (acquisitionTarget !== undefined) {
+                    // Ref installs consult the acquisition boundary instead of the
+                    // registry; the shared guard above already verified installer,
+                    // host, state store, and scope support.
+                    if (options.acquisition === undefined)
+                        return response(parsed.command, parsed.format, "unsupported", safeError("unsupported_dependencies"));
+                    phase = "distribution";
+                    let acquired;
+                    try {
+                        acquired = await options.acquisition.resolvePackage({ ref: acquisitionTarget, signal });
+                    }
+                    catch (error) {
+                        if (isCancelled(signal) || (error instanceof PluginAcquisitionErrorV1 && error.code === "cancelled"))
+                            return response(parsed.command, parsed.format, "cancelled", safeError("cancelled"));
+                        if (error instanceof PluginAcquisitionErrorV1)
+                            return response(parsed.command, parsed.format, "failed", {
+                                code: "acquisition_failed",
+                                message: error.message,
+                            });
+                        throw error;
+                    }
+                    checkSignal(signal);
+                    return await runInstallFlow({
+                        manifest: acquired.manifest,
+                        source: acquired.source,
+                        acquired,
+                    });
+                }
+                try {
+                    requireDependencies(options, requestedScope, scopeRef);
+                }
+                catch {
+                    return response(parsed.command, parsed.format, "unsupported", safeError("unsupported_dependencies"));
+                }
+                const identity = parsed.pluginId;
+                const packageValue = await options.registry.resolve({
+                    pluginId: identity,
+                    pluginVersion: parsed.pluginVersion,
+                    signal,
+                });
+                checkSignal(signal);
+                if (!packageValue)
+                    return response(parsed.command, parsed.format, "failed", safeError("not_found"));
+                if (packageValue.manifest.id !== identity ||
+                    (parsed.pluginVersion !== undefined && packageValue.manifest.pluginVersion !== parsed.pluginVersion))
+                    return response(parsed.command, parsed.format, "failed", safeError("not_found"));
+                return await runInstallFlow({
+                    manifest: packageValue.manifest,
+                    source: packageValue.source,
+                    ...(packageValue.expectedDigest === undefined ? {} : { expectedDigest: packageValue.expectedDigest }),
+                    ...(packageValue.distribution === undefined ? {} : { distribution: packageValue.distribution }),
+                });
+            }
+            catch (error) {
+                if (isCancelled(signal) || (error instanceof Error && error.message === "cancelled"))
+                    return response(parsed.command, parsed.format, "cancelled", safeError("cancelled"));
+                if (error instanceof Error && error.message === "unsupported dependencies")
+                    return response(parsed.command, parsed.format, "unsupported", safeError("unsupported_dependencies"));
+                return response(parsed.command, parsed.format, "failed", safeError(phase === "registry"
+                    ? "registry_failed"
+                    : phase === "distribution"
+                        ? "distribution_failed"
+                        : phase === "state"
+                            ? "state_failed"
+                            : phase === "selection"
+                                ? "selection_failed"
+                                : "installer_failed"));
+            }
+        }
+        finally {
+            releaseInstallTransaction?.();
+        }
+    }
+    return { execute };
+}
+export async function runPluginEcosystemCliV1(options, input) {
+    return await createPluginEcosystemCliV1(options).execute(input);
+}
+//# sourceMappingURL=cli.js.map