@iseoane/agent-depot 0.4.1 → 0.5.1

package/dist/src/package-host-plans.js

@@ -0,0 +1,243 @@
+import { createHash } from "node:crypto";
+import { compareAppVersions, sameAppVersion } from "./app-version.js";
+import { claudeMarketplaceNamesForSource, piSourceIdentity, } from "./package-host-state.js";
+import { parsePortableInstallationMethod } from "./project-manifest.js";
+/** A plan that cannot be derived safely fails closed with its reason. */
+export class PackagePlanError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "PackagePlanError";
+    }
+}
+const NO_STEPS = Object.freeze([]);
+/**
+ * The one place that knows each host CLI's grammar, verified against the
+ * installed CLIs in `.scratch/packages/arena/host-cli-verbs.md`. V1 uses the
+ * scoped verb for every action. Select and forget run nothing.
+ */
+export const HOST_STEP_TEMPLATES = Object.freeze({
+    pi: Object.freeze({
+        install: (input) => Object.freeze([
+            Object.freeze(["pi", "install", input.installSpec]),
+        ]),
+        update: (input) => Object.freeze([
+            Object.freeze(["pi", "update", input.source]),
+        ]),
+        uninstall: (input) => Object.freeze([
+            Object.freeze(["pi", "remove", input.source]),
+        ]),
+        select: () => NO_STEPS,
+        forget: () => NO_STEPS,
+    }),
+    claude: Object.freeze({
+        install: (input) => Object.freeze([
+            ...(input.marketplaceKnown
+                ? []
+                : [Object.freeze(["claude", "plugin", "marketplace", "add", input.source])]),
+            Object.freeze(["claude", "plugin", "install", claudeInstallId(input)]),
+        ]),
+        update: (input) => Object.freeze([
+            Object.freeze(["claude", "plugin", "marketplace", "update", claudeMarketplaceName(input)]),
+            Object.freeze(["claude", "plugin", "update", claudeInstallId(input)]),
+        ]),
+        uninstall: (input) => Object.freeze([
+            Object.freeze(["claude", "plugin", "uninstall", claudeInstallId(input)]),
+        ]),
+        select: () => NO_STEPS,
+        forget: () => NO_STEPS,
+    }),
+});
+/**
+ * The exact host argv for one action. Pure. Every produced argv is re-validated
+ * through `parsePortableInstallationMethod`, so the recipe safety rules apply to
+ * host commands too.
+ *
+ * The synthesized design's four arguments cannot carry the Claude marketplace
+ * name, which lives in the Source snapshot's `marketplace.json` and never in the
+ * host state before the first `marketplace add`. `resolution` supplies it; a
+ * Claude plan that must name the marketplace and has no resolution fails closed.
+ */
+export function planHostSteps(action, descriptor, selection, state, resolution = {}) {
+    assertHostCommand(action, descriptor, selection);
+    const input = stepTemplateInput(descriptor, selection, state, resolution);
+    const steps = HOST_STEP_TEMPLATES[descriptor.host][action](input);
+    return Object.freeze(steps.map((argv, index) => assertValidHostArgv(argv, `${descriptor.host} ${action} step ${index + 1}`)));
+}
+/**
+ * The host's own identity for one selection: `<plugin>@<marketplace>` for Claude
+ * and the Pi Source identity for Pi. The same value the argv templates carry, so
+ * a record can never name an identity the host was not given.
+ */
+export function hostInstallId(descriptor, selection, state, resolution = {}) {
+    const input = stepTemplateInput(descriptor, selection, state, resolution);
+    return descriptor.host === "claude" ? claudeInstallId(input) : input.source;
+}
+function assertHostCommand(action, descriptor, selection) {
+    if (descriptor.host !== selection.host) {
+        throw new PackagePlanError(`The bundle descriptor host ${JSON.stringify(descriptor.host)} does not match the selection host ${JSON.stringify(selection.host)}`);
+    }
+    if (!runsHostCommand(action)) {
+        return;
+    }
+    if (!isInstallable(descriptor)) {
+        throw new PackagePlanError(`The bundle ${JSON.stringify(descriptor.name)} is not installable (${descriptor.warnings.join("; ")})`);
+    }
+    if (descriptor.host === "claude" && action !== "uninstall" && selection.version.policy === "fixed") {
+        throw new PackagePlanError(`A fixed-version Claude selection cannot be delegated: claude plugin install takes <plugin>@<marketplace> and cannot carry the pin ${JSON.stringify(selection.version.version)}`);
+    }
+}
+function stepTemplateInput(descriptor, selection, state, resolution) {
+    const source = hostSource(selection);
+    const marketplace = descriptor.host === "claude" ? resolveClaudeMarketplace(state, selection) : undefined;
+    const marketplaceName = resolution.marketplaceName ?? marketplace?.name;
+    return Object.freeze({
+        descriptor,
+        selection,
+        source,
+        installSpec: installSpec(source, selection),
+        ...(marketplaceName === undefined ? {} : { marketplaceName }),
+        marketplaceKnown: marketplace?.known === true,
+    });
+}
+/**
+ * Every recorded coordinate an action may change. V1 uses the scoped verb for
+ * every action, verified in `.scratch/packages/arena/host-cli-verbs.md`, so that
+ * is the selection's own coordinates. Flip `HOST_WIDE_UPDATE` for a host when a
+ * host-wide verb like `pi update --extensions` is chosen; this function then
+ * returns every recorded coordinate of that host.
+ */
+export function affectedBy(action, selection, recorded) {
+    if (action === "update" && HOST_WIDE_UPDATE[selection.host]) {
+        return Object.freeze(recorded
+            .filter((candidate) => candidate.host === selection.host)
+            .map((candidate) => coordinatesOf(candidate)));
+    }
+    return Object.freeze([coordinatesOf(selection)]);
+}
+const HOST_WIDE_UPDATE = Object.freeze({
+    pi: false,
+    claude: false,
+});
+/** sha256 over the canonical serialization of the declaration. Exact argv order included. */
+export function packageApprovalDigest(declaration) {
+    return createHash("sha256").update(canonicalJson(declaration), "utf8").digest("hex");
+}
+/**
+ * Compares installed evidence with available evidence. Manifest versions compare
+ * through `sameAppVersion` and `compareAppVersions`; differing commits compare only
+ * when cached Source history proves the installed commit is an ancestor.
+ */
+export function classifyUpdate(installed, available, availableCommit, installedCommitIsAncestor) {
+    if (installed.kind !== "installed" || installed.reason !== undefined || available === undefined) {
+        return "unknown";
+    }
+    if (installed.commit !== undefined) {
+        const sourceCommit = availableCommit ?? (available.kind === "git-commit" ? available.commit : undefined);
+        if (sourceCommit === undefined)
+            return "unknown";
+        if (normalizeCommit(installed.commit) === normalizeCommit(sourceCommit))
+            return "current";
+        return installedCommitIsAncestor === true ? "update available" : "unknown";
+    }
+    if (installed.version !== undefined && available.kind === "manifest-version") {
+        if (sameAppVersion(installed.version, available.version)) {
+            return "current";
+        }
+        const order = compareAppVersions(installed.version, available.version);
+        if (order === undefined) {
+            return "unknown";
+        }
+        return order < 0 ? "update available" : "current";
+    }
+    return "unknown";
+}
+/** Validates one host argv with the shared portable-command rules. */
+export function assertValidHostArgv(argv, label) {
+    try {
+        return parsePortableInstallationMethod({ kind: "command", argv }, { label }).argv;
+    }
+    catch (error) {
+        const reason = error instanceof Error ? error.message : "the argv is not a portable no-shell command";
+        throw new PackagePlanError(`Refused host command (${label}): ${reason}`);
+    }
+}
+function claudeInstallId(input) {
+    return `${claudePluginName(input)}@${claudeMarketplaceName(input)}`;
+}
+function claudePluginName(input) {
+    return input.selection.host === "claude" ? input.selection.pluginName : input.descriptor.name;
+}
+function claudeMarketplaceName(input) {
+    if (input.marketplaceName === undefined || input.marketplaceName === "") {
+        throw new PackagePlanError(`Naming the marketplace for ${JSON.stringify(claudePluginName(input))} requires the name declared in the Source's .claude-plugin/marketplace.json`);
+    }
+    return input.marketplaceName;
+}
+function resolveClaudeMarketplace(state, selection) {
+    if (selection.host !== "claude") {
+        return undefined;
+    }
+    const known = claudeMarketplaceNamesForSource(state.claudeMarketplaces, selection.source)[0];
+    if (known !== undefined) {
+        return { name: known, known: true };
+    }
+    const installed = state.claudePlugins.records.find((record) => !record.drifted && record.scope === "user" && record.pluginName === selection.pluginName && record.marketplace !== "");
+    return installed === undefined ? undefined : { name: installed.marketplace, known: false };
+}
+function isInstallable(descriptor) {
+    return descriptor.installable;
+}
+function runsHostCommand(action) {
+    return action === "install" || action === "update" || action === "uninstall";
+}
+function hostSource(selection) {
+    if (selection.host === "pi") {
+        const identity = piSourceIdentity(selection.source);
+        if (identity === undefined) {
+            throw new PackagePlanError("Pi cannot install a built-in or local path Source");
+        }
+        return identity;
+    }
+    if (selection.source.kind === "builtin" || "path" in selection.source) {
+        throw new PackagePlanError("Claude Code cannot install a built-in or local path Source");
+    }
+    return selection.source.url;
+}
+function installSpec(source, selection) {
+    return selection.version.policy === "fixed" && selection.version.version !== ""
+        ? `${source}@${selection.version.version}`
+        : source;
+}
+function normalizeCommit(commit) {
+    return commit.trim().toLowerCase();
+}
+function coordinatesOf(selection) {
+    return selection.host === "pi"
+        ? Object.freeze({ host: selection.host, root: selection.root })
+        : Object.freeze({ host: selection.host, marketplaceRoot: selection.marketplaceRoot, pluginName: selection.pluginName });
+}
+function canonicalJson(value) {
+    if (value === null) {
+        return "null";
+    }
+    if (typeof value === "string") {
+        return JSON.stringify(value);
+    }
+    if (typeof value === "boolean") {
+        return value ? "true" : "false";
+    }
+    if (typeof value === "number") {
+        return Number.isFinite(value) ? String(value) : "null";
+    }
+    if (Array.isArray(value)) {
+        return `[${value.map((entry) => canonicalJson(entry)).join(",")}]`;
+    }
+    if (isRecord(value)) {
+        const keys = Object.keys(value).filter((key) => value[key] !== undefined).sort();
+        return `{${keys.map((key) => `${JSON.stringify(key)}:${canonicalJson(value[key])}`).join(",")}}`;
+    }
+    throw new PackagePlanError("The package declaration contains a value that cannot be canonicalized");
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}