@iseoane/agent-depot 0.4.1 → 0.5.1

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

@@ -0,0 +1,473 @@
+import { lstat, readFile } from "node:fs/promises";
+import { homedir } from "node:os";
+import path from "node:path";
+import { canonicalizeGitSourceUrl } from "./git-source.js";
+import { assertNoSymlinkPath } from "./path-safety.js";
+import { runProcess } from "./process-runner.js";
+/**
+ * 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 piAgentDirectory = path.resolve(env.piAgentDirectory ?? process.env.PI_CODING_AGENT_DIR ?? path.join(home, ".pi", "agent"));
+    const reader = env.readHostStateFile ?? ((filePath) => readFile(filePath, "utf8"));
+    const [pi, claudePlugins, claudeMarketplaces] = await Promise.all([
+        readSection("pi-settings", path.join(piAgentDirectory, "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),
+    ]);
+    const verifiedPi = await attachPiCheckoutEvidence(pi, piAgentDirectory, env.readPiCheckout ?? readPiCheckoutEvidence);
+    return Object.freeze({ pi: verifiedPi, 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");
+    }
+    if (selection.host === "pi" && (descriptor.coordinates.host !== "pi" || descriptor.coordinates.root !== selection.root)) {
+        return unknownEvidence("the Pi bundle root and the selection disagree");
+    }
+    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) {
+        if (selection.root !== "") {
+            return unknownEvidence("Pi project-scoped and subdirectory package checkouts are not supported for version evidence");
+        }
+        if (match.checkoutIssue !== undefined) {
+            return installedEvidence(undefined, undefined, match.checkoutIssue);
+        }
+        if (match.checkoutCommit === undefined) {
+            return installedEvidence(undefined, undefined, `Pi reports this Package installed, but its checkout could not be verified. Version and update assessment are unavailable; inspect the configured checkout before updating.`);
+        }
+        return installedEvidence(match.checkoutVersion, match.checkoutCommit);
+    }
+    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, reason) {
+    return Object.freeze({
+        kind: "installed",
+        ...(version === undefined || version === "" ? {} : { version }),
+        ...(commit === undefined || commit === "" ? {} : { commit }),
+        ...(reason === undefined ? {} : { reason }),
+    });
+}
+async function attachPiCheckoutEvidence(section, agentDirectory, reader) {
+    const records = await Promise.all(section.records.map(async (record) => {
+        if (record.drifted || !record.identity.startsWith("git:"))
+            return record;
+        try {
+            const checkoutPath = piGitInstallPath(agentDirectory, record.identity);
+            const evidence = await reader(checkoutPath, record.identity);
+            return Object.freeze({
+                ...record,
+                ...(evidence.commit === undefined ? {} : { checkoutCommit: evidence.commit }),
+                ...(evidence.version === undefined ? {} : { checkoutVersion: evidence.version }),
+                ...(evidence.issue === undefined ? {} : { checkoutIssue: evidence.issue }),
+            });
+        }
+        catch (error) {
+            return Object.freeze({
+                ...record,
+                checkoutIssue: error instanceof Error ? error.message : "Pi Git checkout could not be verified",
+            });
+        }
+    }));
+    return Object.freeze({ ...section, records: Object.freeze(records) });
+}
+function piGitInstallPath(agentDirectory, identity) {
+    const source = identity.slice("git:".length);
+    let parsed;
+    try {
+        parsed = new URL(`https://${source}`);
+    }
+    catch {
+        throw new Error("the configured Pi Git source has no safe checkout path");
+    }
+    const segments = parsed.pathname.split("/").filter(Boolean).map((segment) => decodeURIComponent(segment));
+    const lastSegment = segments.at(-1);
+    if (lastSegment?.endsWith(".git"))
+        segments[segments.length - 1] = lastSegment.slice(0, -4);
+    if (segments.length < 2 || segments.some((segment) => segment === "." || segment === ".." || segment.includes("/") || segment.includes("\\"))) {
+        throw new Error("the configured Pi Git source has no safe checkout path");
+    }
+    return path.resolve(agentDirectory, "git", parsed.hostname, ...segments);
+}
+async function readPiCheckoutEvidence(checkoutPath, sourceIdentity) {
+    const unavailable = (reason) => ({
+        issue: `Pi reports this Package installed, but ${reason}. Version and update assessment are unavailable; inspect the checkout before updating.`,
+    });
+    try {
+        await assertNoSymlinkPath(checkoutPath, "Pi package checkout path");
+        const root = await lstat(checkoutPath).catch((error) => {
+            if (isNotFound(error))
+                return undefined;
+            throw error;
+        });
+        if (root === undefined)
+            return unavailable("its configured Git checkout is missing");
+        if (!root.isDirectory())
+            return unavailable("its configured Git checkout is not a directory");
+        const [topLevel, origin, commit, status, manifest] = await Promise.all([
+            runPiGit(checkoutPath, ["rev-parse", "--show-toplevel"]),
+            runPiGit(checkoutPath, ["config", "--get", "remote.origin.url"]),
+            runPiGit(checkoutPath, ["rev-parse", "--verify", "HEAD^{commit}"]),
+            runPiGit(checkoutPath, ["status", "--porcelain", "--untracked-files=all"]),
+            runPiGit(checkoutPath, ["show", "HEAD:package.json"]),
+        ]);
+        const expectedRoot = path.resolve(checkoutPath);
+        if (path.resolve(topLevel) !== expectedRoot)
+            return unavailable("the package path is not the root of its Git checkout");
+        if (normalizeRepository(piSourceIdentityFromUrl(origin)) !== normalizeRepository(sourceIdentity)) {
+            return unavailable("the Git checkout origin does not match the selected Pi package Source");
+        }
+        if (!/^(?:[0-9a-f]{40}|[0-9a-f]{64})$/iu.test(commit))
+            return unavailable("the Pi checkout HEAD is not a full Git commit");
+        if (status !== "")
+            return unavailable("the Pi Git checkout has local modifications");
+        const packageJson = JSON.parse(manifest);
+        if (!isRecord(packageJson) || typeof packageJson.version !== "string" || packageJson.version.trim() === "") {
+            return { commit: commit.toLowerCase() };
+        }
+        return { commit: commit.toLowerCase(), version: packageJson.version };
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : "";
+        const reason = message.includes("timed out")
+            ? "Git checkout verification timed out"
+            : message.includes("symbolic link")
+                ? "the configured checkout path contains a symbolic link"
+                : "the Pi Git checkout could not be read safely";
+        return unavailable(reason);
+    }
+}
+async function runPiGit(checkoutPath, args) {
+    const result = await runProcess("git", ["-C", checkoutPath, ...args], {
+        captureStdout: true,
+        maxOutputBytes: 1024 * 1024,
+        maxStderrBytes: 8192,
+        timeoutMs: 3000,
+    });
+    if (result.timedOut)
+        throw new Error("Pi checkout verification timed out");
+    if (result.outputTooLarge || result.code !== 0 || result.signal !== null)
+        throw new Error("Pi checkout verification command failed");
+    return result.stdout.toString("utf8").trim();
+}
+function piSourceIdentityFromUrl(origin) {
+    const canonical = canonicalizeGitSourceUrl(origin);
+    return `git:${canonical.replace(/^[a-z][a-z0-9+.-]*:\/\//iu, "")}`;
+}
+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]);
+}

package/dist/src/package-owned-skills.js

@@ -0,0 +1,124 @@
+import { homedir } from "node:os";
+import { bundleOwnedSkillMatcher, bundleOwnedSkillNameMatcher, discoverBundlesInSnapshot, } from "./package-bundles.js";
+import { findInstalledBundle, readHostInstallView } from "./package-host-state.js";
+import { packageSelectionFor, selectionKey, } from "./package-model.js";
+import { sourceBundleScope } from "./package-content.js";
+import { defaultPackageStateDirectory, PackageStateStore } from "./package-state.js";
+import { createSourceContentAccess } from "./skill-discovery.js";
+import { createSourceOperations, projectSourceOf } from "./sources.js";
+/**
+ * The bundles that own their Skills. A bundle owns them only when it is active:
+ * a recorded selection names the user's choice, or a host state file proves the
+ * bundle installed. Source, host, and coordinates must all agree, and a bundle
+ * that is not installable never owns. An unreadable host state is `unknown`, not
+ * `installed`, so it never claims; the user's own selection still does.
+ */
+export function activeBundles(bundles, selections, hostView) {
+    const selectedKeys = new Set(selections.map(selectionKey));
+    const active = [];
+    for (const { source, descriptor } of bundles) {
+        if (!descriptor.installable) {
+            continue;
+        }
+        const selection = packageSelectionFor(descriptor, source);
+        const selected = selectedKeys.has(selectionKey(selection));
+        const installed = findInstalledBundle(hostView, descriptor, selection).kind === "installed";
+        if (selected || installed) {
+            active.push({
+                descriptor,
+                selection,
+                reason: selected ? (installed ? "selected-and-installed" : "selected") : "installed",
+            });
+        }
+    }
+    return Object.freeze(active);
+}
+/**
+ * Composes ownership for descriptors a caller already derived from the snapshot
+ * pass that fed skill discovery, so no second walk or hand-synced list is
+ * needed. A Skill path matches a `skill-category` component; a bare directory
+ * name matches a Skill name that component declares.
+ */
+export function packageOwnedSkillMatcher(descriptors) {
+    const byPath = bundleOwnedSkillMatcher(descriptors);
+    const byName = bundleOwnedSkillNameMatcher(descriptors);
+    return (skillPath) => byPath(skillPath) ?? (skillPath.includes("/") ? undefined : byName(skillPath));
+}
+/**
+ * Reads one snapshot per Source and derives bundle ownership from the same
+ * pass discovery uses, then keeps only the bundles the user selected or a host
+ * proves installed. A Source or Package state that cannot be read warns and
+ * contributes no exclusions, so an unresolvable input never hides a Skill and a
+ * missing record never falsely claims one.
+ */
+export async function loadPackageOwnedSkillFilter(options = {}) {
+    const warn = options.reportWarning ?? (warning => process.emitWarning(warning));
+    let sources;
+    try {
+        sources = options.sources ?? await createSourceOperations({
+            ...(options.homeDirectory === undefined ? {} : { homeDirectory: options.homeDirectory }),
+        }).listSources();
+    }
+    catch (error) {
+        warn(`WARNING: Package-owned Skill exclusions unavailable; no exclusions applied: ${errorMessage(error)}`);
+        return () => undefined;
+    }
+    const contentAccess = options.sourceContentAccess ?? createSourceContentAccess();
+    const bundles = [];
+    for (const source of sources) {
+        try {
+            const projectSource = projectSourceOf(source);
+            for (const descriptor of discoverBundlesInSnapshot(await contentAccess.readSnapshot(source), sourceBundleScope(source))) {
+                bundles.push({ source: projectSource, descriptor });
+            }
+        }
+        catch (error) {
+            warn(`WARNING: Skipping Package-owned Skill exclusions for Source ${source.id}: ${errorMessage(error)}`);
+        }
+    }
+    return packageOwnedSkillMatcher(activeBundles(bundles, await loadSelections(options, warn), await loadHostView(options)).map(bundle => bundle.descriptor));
+}
+async function loadSelections(options, warn) {
+    if (options.selections !== undefined) {
+        return options.selections;
+    }
+    try {
+        const records = await new PackageStateStore(options.stateDirectory ?? defaultPackageStateDirectory(process.env, process.platform, options.homeDirectory ?? homedir())).list();
+        return records.map(record => record.selection);
+    }
+    catch (error) {
+        warn(`WARNING: Package selection state unavailable; no Package-owned Skill exclusions applied: ${errorMessage(error)}`);
+        return [];
+    }
+}
+async function loadHostView(options) {
+    return options.hostView ?? await readHostInstallView({
+        ...(options.homeDirectory === undefined ? {} : { homeDirectory: options.homeDirectory }),
+    });
+}
+/**
+ * The recorded portable user-global installations a bundle's own
+ * `skill-category` components would duplicate, matched by Source and by
+ * Source-relative Skill path or bare Skill name. Empty when nothing overlaps.
+ * A caller refuses the Package lifecycle on any conflict instead of silently
+ * replacing or removing the portable copy.
+ */
+export function portableSkillConflicts(descriptor, source, installations) {
+    const owned = packageOwnedSkillMatcher([descriptor]);
+    return Object.freeze(installations.filter((installation) => sameSource(installation.source, source) && owned(installation.path) !== undefined));
+}
+function sameSource(left, right) {
+    return JSON.stringify(left) === JSON.stringify(right);
+}
+/** Refuses a bundle-owned Skill path or name, naming the Package and its Host. */
+export function assertSkillNotPackageOwned(skillPath, owned) {
+    const owner = owned(skillPath);
+    if (owner === undefined) {
+        return;
+    }
+    throw new Error(`Package-owned Skill ${JSON.stringify(skillPath)} is provided by the ${owner.host} Package ${JSON.stringify(owner.name)}; ` +
+        "it cannot be installed, adopted, or removed as a loose Skill, and no path was changed");
+}
+function errorMessage(error) {
+    return error instanceof Error ? error.message : String(error);
+}