@iseoane/agent-depot 0.4.1 → 0.5.0

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

@@ -0,0 +1,240 @@
+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`; commits compare by equality.
+ * A mixed pair, missing evidence, or an opaque version is `unknown`, never `current`.
+ */
+export function classifyUpdate(installed, available) {
+    if (installed.kind !== "installed" || available === undefined) {
+        return "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";
+    }
+    if (installed.commit !== undefined && available.kind === "git-commit") {
+        return normalizeCommit(installed.commit) === normalizeCommit(available.commit)
+            ? "current"
+            : "update available";
+    }
+    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);
+}

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

@@ -0,0 +1,349 @@
+import { readFile } from "node:fs/promises";
+import { homedir } from "node:os";
+import path from "node:path";
+/**
+ * Reads the `packages` setting, or a bare `packages` array, into records.
+ * Nothing here throws: an unknown entry shape becomes a drifted record so the
+ * lookup it could affect reports `unknown` instead of a guess.
+ */
+export function parsePiPackagesSetting(value) {
+    const entries = Array.isArray(value)
+        ? value
+        : isRecord(value) && Array.isArray(value.packages)
+            ? value.packages
+            : undefined;
+    if (entries === undefined) {
+        return Object.freeze([]);
+    }
+    return Object.freeze(entries.map(parsePiInstallEntry));
+}
+/** Reads `installed_plugins.json` in its v2 (array per plugin) and v1 (one object) shapes. */
+export function parseClaudePluginState(value) {
+    if (!isRecord(value) || !isRecord(value.plugins)) {
+        return Object.freeze([]);
+    }
+    const records = [];
+    for (const [installId, raw] of Object.entries(value.plugins)) {
+        for (const entry of Array.isArray(raw) ? raw : [raw]) {
+            records.push(parseClaudeInstallEntry(installId, entry));
+        }
+    }
+    return Object.freeze(records);
+}
+/** Reads `known_marketplaces.json`, whose keys are the marketplace names. */
+export function parseClaudeMarketplaceState(value) {
+    if (!isRecord(value)) {
+        return Object.freeze([]);
+    }
+    const records = Object.entries(value).map(([name, raw]) => parseClaudeMarketplaceEntry(name, raw));
+    return Object.freeze(records);
+}
+/**
+ * Reads the three host state files. A missing file is an empty section; a
+ * drifted or unreadable file degrades to an `issue`, and this never throws.
+ */
+export async function readHostInstallView(env = {}) {
+    const home = env.homeDirectory ?? homedir();
+    const reader = env.readHostStateFile ?? ((filePath) => readFile(filePath, "utf8"));
+    const [pi, claudePlugins, claudeMarketplaces] = await Promise.all([
+        readSection("pi-settings", path.join(home, ".pi", "agent", "settings.json"), reader, parsePiSettingsFile),
+        readSection("claude-installed-plugins", path.join(home, ".claude", "plugins", "installed_plugins.json"), reader, parseClaudePluginsFile),
+        readSection("claude-known-marketplaces", path.join(home, ".claude", "plugins", "known_marketplaces.json"), reader, parseClaudeMarketplacesFile),
+    ]);
+    return Object.freeze({ pi, claudePlugins, claudeMarketplaces });
+}
+/**
+ * What the host says about one bundle. Pi identity is the repository URL without
+ * the ref; npm-shaped records never match a git bundle. Claude identity is
+ * `<plugin>@<marketplace>`, and a record is attributed only when its marketplace
+ * is the one bound to the selection's Source.
+ */
+export function findInstalledBundle(view, descriptor, selection) {
+    if (descriptor.host !== selection.host) {
+        return unknownEvidence("the bundle descriptor and the selection disagree on the host");
+    }
+    return selection.host === "pi"
+        ? findPiInstalled(view.pi, selection)
+        : findClaudeInstalled(view, descriptor, selection);
+}
+/**
+ * The Pi install identity of a registered Source: `git:` plus the scheme-stripped
+ * repository URL, without any ref. Built-in and local path Sources have none.
+ */
+export function piSourceIdentity(source) {
+    if (source.kind === "builtin" || "path" in source) {
+        return undefined;
+    }
+    return `git:${normalizeRepository(source.url)}`;
+}
+/**
+ * The marketplace names the host has registered for a Source, resolved by
+ * matching each record's own source against the Source URL.
+ */
+export function claudeMarketplaceNamesForSource(section, source) {
+    const target = hostSourceReference(source);
+    if (target === undefined) {
+        return Object.freeze([]);
+    }
+    const names = section.records
+        .filter((record) => marketplaceSourceMatches(record.source, target))
+        .map((record) => record.name);
+    return Object.freeze([...new Set(names)]);
+}
+function hostSourceReference(source) {
+    if (source.kind === "builtin") {
+        return undefined;
+    }
+    if ("path" in source) {
+        return { kind: "path", reference: path.normalize(source.path) };
+    }
+    return { kind: "repository", reference: normalizeRepository(source.url) };
+}
+function marketplaceSourceMatches(source, target) {
+    if (target.kind === "repository") {
+        if (source.kind === "url" || source.kind === "git") {
+            return normalizeRepository(source.url) === target.reference;
+        }
+        if (source.kind === "github") {
+            const repository = source.repo.includes("://") ? source.repo : `github.com/${source.repo}`;
+            return normalizeRepository(repository) === target.reference;
+        }
+        return false;
+    }
+    if (source.kind === "directory" || source.kind === "file") {
+        return path.normalize(source.path) === target.reference;
+    }
+    return false;
+}
+function findPiInstalled(section, selection) {
+    if (section.issue !== undefined) {
+        return unknownEvidence(section.issue);
+    }
+    const identity = piSourceIdentity(selection.source);
+    if (identity === undefined) {
+        return unknownEvidence("the selection's Source has no Pi install identity");
+    }
+    const wanted = normalizeRepository(identity);
+    const match = section.records.find((record) => !record.drifted && normalizeRepository(record.identity) === wanted);
+    if (match !== undefined) {
+        return installedEvidence(undefined, match.commit);
+    }
+    if (section.records.some((record) => record.drifted)) {
+        return unknownEvidence(`${section.path} holds an entry whose shape could not be read, so the install cannot be verified`);
+    }
+    return Object.freeze({ kind: "absent" });
+}
+function findClaudeInstalled(view, descriptor, selection) {
+    const section = view.claudePlugins;
+    if (section.issue !== undefined) {
+        return unknownEvidence(section.issue);
+    }
+    const pluginName = selection.host === "claude" ? selection.pluginName : descriptor.name;
+    const records = section.records.filter((record) => record.pluginName === pluginName);
+    const names = claudeMarketplaceNamesForSource(view.claudeMarketplaces, selection.source);
+    if (names.length > 0) {
+        // V1 delegates user-global installs only, so a project or local record does not satisfy the selection.
+        const match = records.find((record) => record.scope === "user" && names.includes(record.marketplace));
+        return match === undefined
+            ? Object.freeze({ kind: "absent" })
+            : installedEvidence(match.version, match.commit);
+    }
+    if (records.some((record) => record.drifted)) {
+        return unknownEvidence(`${section.path} holds an entry whose shape could not be read, so the install cannot be verified`);
+    }
+    if (records.length > 0) {
+        const reason = view.claudeMarketplaces.issue
+            ?? `no marketplace recorded in ${view.claudeMarketplaces.path} is bound to the selection's Source`;
+        return unknownEvidence(reason);
+    }
+    return Object.freeze({ kind: "absent" });
+}
+function installedEvidence(version, commit) {
+    return Object.freeze({
+        kind: "installed",
+        ...(version === undefined || version === "" ? {} : { version }),
+        ...(commit === undefined || commit === "" ? {} : { commit }),
+    });
+}
+function unknownEvidence(reason) {
+    return Object.freeze({ kind: "unknown", reason });
+}
+async function readSection(id, filePath, reader, parse) {
+    let raw;
+    try {
+        raw = await reader(filePath);
+    }
+    catch (error) {
+        if (isNotFound(error)) {
+            return Object.freeze({ id, path: filePath, present: false, records: Object.freeze([]) });
+        }
+        return Object.freeze({
+            id,
+            path: filePath,
+            present: true,
+            records: Object.freeze([]),
+            issue: `${filePath} could not be read (${errorReason(error)})`,
+        });
+    }
+    let value;
+    try {
+        value = JSON.parse(raw);
+    }
+    catch (error) {
+        return Object.freeze({
+            id,
+            path: filePath,
+            present: true,
+            records: Object.freeze([]),
+            issue: `${filePath} is not valid JSON (${errorReason(error)})`,
+        });
+    }
+    const parsed = parse(value);
+    if (parsed.issue !== undefined) {
+        return Object.freeze({ id, path: filePath, present: true, records: Object.freeze([]), issue: parsed.issue });
+    }
+    return Object.freeze({ id, path: filePath, present: true, records: parsed.records ?? Object.freeze([]) });
+}
+function parsePiSettingsFile(value) {
+    if (!isRecord(value)) {
+        return { issue: "the settings file is not a JSON object" };
+    }
+    if (value.packages === undefined) {
+        return { records: Object.freeze([]) };
+    }
+    if (!Array.isArray(value.packages)) {
+        return { issue: "the packages setting is not an array" };
+    }
+    return { records: parsePiPackagesSetting(value.packages) };
+}
+function parseClaudePluginsFile(value) {
+    if (!isRecord(value)) {
+        return { issue: "the installed plugins file is not a JSON object" };
+    }
+    if (value.plugins === undefined) {
+        return { records: Object.freeze([]) };
+    }
+    if (!isRecord(value.plugins)) {
+        return { issue: "the plugins record is not a JSON object" };
+    }
+    return { records: parseClaudePluginState(value) };
+}
+function parseClaudeMarketplacesFile(value) {
+    if (!isRecord(value)) {
+        return { issue: "the known marketplaces file is not a JSON object" };
+    }
+    return { records: parseClaudeMarketplaceState(value) };
+}
+function parsePiInstallEntry(entry) {
+    const source = typeof entry === "string"
+        ? entry.trim()
+        : isRecord(entry) && typeof entry.source === "string"
+            ? entry.source.trim()
+            : "";
+    if (source === "") {
+        return Object.freeze({ source: "", identity: "", objectForm: isRecord(entry), drifted: true });
+    }
+    const pinIndex = trailingPinIndex(source);
+    const pin = pinIndex === undefined ? undefined : source.slice(pinIndex + 1);
+    const identity = pinIndex === undefined ? source : source.slice(0, pinIndex);
+    const commit = pin !== undefined && /^[0-9a-f]{7,64}$/iu.test(pin) ? pin.toLowerCase() : undefined;
+    return Object.freeze({
+        source,
+        identity,
+        ...(pin === undefined ? {} : { pin }),
+        ...(commit === undefined ? {} : { commit }),
+        objectForm: isRecord(entry),
+        drifted: false,
+    });
+}
+function parseClaudeInstallEntry(installId, entry) {
+    const id = parseClaudeInstallId(installId);
+    if (id === undefined || !isRecord(entry) || typeof entry.scope !== "string" || typeof entry.installPath !== "string") {
+        return Object.freeze({
+            installId,
+            pluginName: id?.pluginName ?? "",
+            marketplace: id?.marketplace ?? "",
+            scope: "",
+            installPath: "",
+            drifted: true,
+        });
+    }
+    return Object.freeze({
+        installId,
+        pluginName: id.pluginName,
+        marketplace: id.marketplace,
+        scope: entry.scope,
+        installPath: entry.installPath,
+        ...(typeof entry.version === "string" ? { version: entry.version } : {}),
+        ...(typeof entry.gitCommitSha === "string" ? { commit: entry.gitCommitSha } : {}),
+        drifted: false,
+    });
+}
+function parseClaudeMarketplaceEntry(name, raw) {
+    const record = isRecord(raw) ? raw : undefined;
+    return Object.freeze({
+        name,
+        source: parseClaudeMarketplaceSource(record?.source),
+        installLocation: record !== undefined && typeof record.installLocation === "string" ? record.installLocation : "",
+        ...(record !== undefined && typeof record.lastUpdated === "string" ? { lastUpdated: record.lastUpdated } : {}),
+        ...(record !== undefined && typeof record.autoUpdate === "boolean" ? { autoUpdate: record.autoUpdate } : {}),
+    });
+}
+function parseClaudeMarketplaceSource(value) {
+    if (!isRecord(value) || typeof value.source !== "string") {
+        return { kind: "unknown", raw: JSON.stringify(value ?? null) };
+    }
+    const ref = typeof value.ref === "string" && value.ref !== "" ? value.ref : undefined;
+    switch (value.source) {
+        case "github":
+            return typeof value.repo === "string" && value.repo !== ""
+                ? Object.freeze({ kind: "github", repo: value.repo, ...(ref === undefined ? {} : { ref }) })
+                : { kind: "unknown", raw: JSON.stringify(value) };
+        case "url":
+            return typeof value.url === "string" && value.url !== ""
+                ? Object.freeze({ kind: "url", url: value.url, ...(ref === undefined ? {} : { ref }) })
+                : { kind: "unknown", raw: JSON.stringify(value) };
+        case "git":
+            return typeof value.url === "string" && value.url !== ""
+                ? Object.freeze({ kind: "git", url: value.url, ...(ref === undefined ? {} : { ref }) })
+                : { kind: "unknown", raw: JSON.stringify(value) };
+        case "directory":
+            return typeof value.path === "string" && value.path !== ""
+                ? Object.freeze({ kind: "directory", path: value.path })
+                : { kind: "unknown", raw: JSON.stringify(value) };
+        case "file":
+            return typeof value.path === "string" && value.path !== ""
+                ? Object.freeze({ kind: "file", path: value.path })
+                : { kind: "unknown", raw: JSON.stringify(value) };
+        default:
+            return { kind: "unknown", raw: JSON.stringify(value) };
+    }
+}
+function parseClaudeInstallId(installId) {
+    const at = installId.lastIndexOf("@");
+    if (at <= 0 || at === installId.length - 1) {
+        return undefined;
+    }
+    return { pluginName: installId.slice(0, at), marketplace: installId.slice(at + 1) };
+}
+/** The `@<pin>` of a Pi source string, only when it follows the last path segment. */
+function trailingPinIndex(source) {
+    const at = source.lastIndexOf("@");
+    return at > 0 && at > source.lastIndexOf("/") ? at : undefined;
+}
+function normalizeRepository(value) {
+    const scheme = value.indexOf("://");
+    return (scheme >= 0 ? value.slice(scheme + 3) : value)
+        .replace(/^git:/u, "")
+        .replace(/\.git$/u, "")
+        .replace(/\/+$/u, "");
+}
+function isNotFound(error) {
+    return error instanceof Error && "code" in error && error.code === "ENOENT";
+}
+function errorReason(error) {
+    return error instanceof Error ? error.message : "the host file could not be read";
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}

package/dist/src/package-model.js

@@ -0,0 +1,33 @@
+/** V1 bundle hosts. Codex and OpenCode packaging stays recognized but deferred. */
+export const PACKAGE_HOSTS = Object.freeze(["pi", "claude"]);
+/** The single list of categories Agent Depot reports but never manages. */
+export const DEFERRED_COMPONENT_KINDS = Object.freeze(["agents", "mcp-servers"]);
+/** The portable selection a discovered bundle stands for: its coordinates, `latest`, and the Source it came from. */
+export function packageSelectionFor(descriptor, source) {
+    const coordinates = descriptor.coordinates;
+    return coordinates.host === "pi"
+        ? { host: "pi", root: coordinates.root, source, version: { policy: "latest" } }
+        : { host: "claude", marketplaceRoot: coordinates.marketplaceRoot, pluginName: coordinates.pluginName, source, version: { policy: "latest" } };
+}
+/** The POSIX directory identifying where a bundle lives within its Source. */
+export function bundleRoot(coordinates) {
+    return coordinates.host === "pi" ? coordinates.root : coordinates.marketplaceRoot;
+}
+/** A human-readable one-line label for a bundle's coordinates. */
+export function describeCoordinates(coordinates) {
+    const at = (pathValue) => (pathValue === "" ? "." : pathValue);
+    return coordinates.host === "pi"
+        ? `pi ${at(coordinates.root)}`
+        : `claude ${coordinates.pluginName}@${at(coordinates.marketplaceRoot)}`;
+}
+/**
+ * The stable selection identity. Derived from the Source and the coordinates
+ * only, so a bundle rename (its manifest name or version) does not move the
+ * key, while a Source or coordinate change does.
+ */
+export function selectionKey(selection) {
+    const coordinates = selection.host === "pi"
+        ? { host: selection.host, root: selection.root }
+        : { host: selection.host, marketplaceRoot: selection.marketplaceRoot, pluginName: selection.pluginName };
+    return JSON.stringify([selection.source, coordinates]);
+}