@solaqua/skul 0.1.0

package/dist/bundle-fetch.d.ts

@@ -0,0 +1,67 @@
+export interface FetchRemoteSourceOptions {
+    /** Normalized source identifier, e.g. "github.com/owner/repo" */
+    source: string;
+    libraryDir: string;
+    /** Transport protocol to use when cloning. Defaults to "https". */
+    protocol?: "https" | "ssh";
+}
+export interface FetchRemoteSourceResult {
+    /** true if a fresh clone was performed; false if the cache already existed */
+    cloned: boolean;
+    targetDir: string;
+}
+export interface CachedSourceRevision {
+    cached: boolean;
+    targetDir: string;
+    currentCommit?: string;
+    currentRef?: string;
+    remoteUrl?: string;
+}
+export interface RemoteSourceStatus extends CachedSourceRevision {
+    remoteCommit: string;
+    refKind: "branch" | "tag" | "commit";
+    resolvedRef?: string;
+}
+export interface UpdateCachedRemoteSourceResult extends RemoteSourceStatus {
+    previousCommit?: string;
+    updated: boolean;
+}
+/**
+ * Ensures a remote git source is present in the local library cache.
+ * If the target directory already exists the operation is a no-op (returns cloned: false).
+ * Otherwise the repo is shallow-cloned into libraryDir/host/owner/repo using
+ * HTTPS (default) or SSH when protocol is "ssh".
+ */
+export declare function fetchRemoteSource(options: FetchRemoteSourceOptions): FetchRemoteSourceResult;
+/** Reads the currently cached commit, ref, and remote URL for one source. */
+export declare function readCachedSourceRevision(options: FetchRemoteSourceOptions): CachedSourceRevision;
+/** Resolves the remote state for one source and optional ref selector without mutating the cache. */
+export declare function inspectRemoteSource(options: FetchRemoteSourceOptions & {
+    ref?: string;
+}): RemoteSourceStatus;
+/** Updates a cached remote source to the latest commit for its selected ref. */
+export declare function updateCachedRemoteSource(options: FetchRemoteSourceOptions & {
+    ref?: string;
+}): UpdateCachedRemoteSourceResult;
+/** Moves a cached source checkout back to a previously recorded revision. */
+export declare function restoreCachedRemoteSourceRevision(options: FetchRemoteSourceOptions & {
+    ref?: string;
+    commit: string;
+    refName?: string;
+}): void;
+/** Deletes one cached source checkout without reporting whether it existed. */
+export declare function removeCachedRemoteSource(options: FetchRemoteSourceOptions): void;
+/**
+ * Clears the cached clone for a source and re-clones it fresh at HEAD.
+ *
+ * Clones into a sibling `.tmp` directory first so the existing cache survives
+ * any network or authentication failure — the working copy is only replaced
+ * after the clone succeeds.
+ *
+ * Respects protocol switching: if the stored origin URL uses a different
+ * transport than `options.protocol` (e.g. the cache was SSH but the caller
+ * requests HTTPS), a fresh URL is constructed from the source identifier so the
+ * new protocol takes effect. Local-path remotes used in tests are left as-is
+ * because they don't start with `git@` and therefore match `"https"` by default.
+ */
+export declare function clearAndRefetchCachedRemoteSource(options: FetchRemoteSourceOptions): void;

package/dist/bundle-fetch.js

@@ -0,0 +1,378 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.fetchRemoteSource = fetchRemoteSource;
+exports.readCachedSourceRevision = readCachedSourceRevision;
+exports.inspectRemoteSource = inspectRemoteSource;
+exports.updateCachedRemoteSource = updateCachedRemoteSource;
+exports.restoreCachedRemoteSourceRevision = restoreCachedRemoteSourceRevision;
+exports.removeCachedRemoteSource = removeCachedRemoteSource;
+exports.clearAndRefetchCachedRemoteSource = clearAndRefetchCachedRemoteSource;
+const node_child_process_1 = require("node:child_process");
+const node_fs_1 = __importDefault(require("node:fs"));
+const node_path_1 = __importDefault(require("node:path"));
+const fs_utils_1 = require("./fs-utils");
+const SAFE_SOURCE_RE = /^[a-zA-Z0-9._-]+\/[a-zA-Z0-9._-]+\/[a-zA-Z0-9._-]+$/;
+const SSH_AUTH_FAILURE_RE = /permission denied|could not read from remote repository|host key verification failed/i;
+/**
+ * Ensures a remote git source is present in the local library cache.
+ * If the target directory already exists the operation is a no-op (returns cloned: false).
+ * Otherwise the repo is shallow-cloned into libraryDir/host/owner/repo using
+ * HTTPS (default) or SSH when protocol is "ssh".
+ */
+function fetchRemoteSource(options) {
+    const targetDir = getTargetDir(options);
+    if (node_fs_1.default.existsSync(targetDir)) {
+        return { cloned: false, targetDir };
+    }
+    const cloneUrl = getCloneUrl(options.source, options.protocol);
+    node_fs_1.default.mkdirSync(node_path_1.default.dirname(targetDir), { recursive: true });
+    try {
+        runGit(["clone", "--depth=1", cloneUrl, targetDir]);
+    }
+    catch (error) {
+        node_fs_1.default.rmSync(targetDir, { recursive: true, force: true });
+        throw normalizeGitError(error, `Failed to clone ${cloneUrl}`, {
+            source: options.source,
+            protocol: options.protocol,
+        });
+    }
+    return { cloned: true, targetDir };
+}
+/** Reads the currently cached commit, ref, and remote URL for one source. */
+function readCachedSourceRevision(options) {
+    const targetDir = getTargetDir(options);
+    if (!node_fs_1.default.existsSync(targetDir)) {
+        return { cached: false, targetDir };
+    }
+    return {
+        cached: true,
+        targetDir,
+        currentCommit: tryRunGit(["-C", targetDir, "rev-parse", "HEAD"]),
+        currentRef: normalizeCurrentRef(tryRunGit([
+            "-C",
+            targetDir,
+            "symbolic-ref",
+            "--quiet",
+            "--short",
+            "HEAD",
+        ])),
+        remoteUrl: tryRunGit(["-C", targetDir, "remote", "get-url", "origin"]),
+    };
+}
+/** Resolves the remote state for one source and optional ref selector without mutating the cache. */
+function inspectRemoteSource(options) {
+    const cached = readCachedSourceRevision(options);
+    const remoteUrl = cached.remoteUrl ?? getCloneUrl(options.source, options.protocol);
+    let resolvedRemote;
+    try {
+        resolvedRemote = resolveRemoteRef(remoteUrl, options.ref);
+    }
+    catch (error) {
+        throw normalizeGitError(error, `Failed to inspect ${options.source}`, {
+            source: options.source,
+            protocol: options.protocol,
+        });
+    }
+    return {
+        ...cached,
+        remoteCommit: resolvedRemote.commit,
+        refKind: resolvedRemote.kind,
+        ...(resolvedRemote.resolvedRef !== undefined
+            ? { resolvedRef: resolvedRemote.resolvedRef }
+            : {}),
+    };
+}
+/** Updates a cached remote source to the latest commit for its selected ref. */
+function updateCachedRemoteSource(options) {
+    const initialRevision = readCachedSourceRevision(options);
+    if (!initialRevision.cached) {
+        fetchRemoteSource(options);
+    }
+    const targetDir = getTargetDir(options);
+    let status;
+    try {
+        status = inspectRemoteSource(options);
+    }
+    catch (error) {
+        throw rewriteInspectFailureForUpdate(error, options.source);
+    }
+    const requiresCheckoutRealignment = status.refKind === "branch"
+        ? status.currentRef !== status.resolvedRef
+        : status.currentRef !== undefined;
+    if (status.currentCommit === status.remoteCommit &&
+        !requiresCheckoutRealignment) {
+        return {
+            ...status,
+            previousCommit: status.currentCommit,
+            updated: false,
+            currentCommit: status.remoteCommit,
+        };
+    }
+    try {
+        if (status.refKind === "branch") {
+            runGit([
+                "-C",
+                targetDir,
+                "fetch",
+                "--depth=1",
+                "origin",
+                `refs/heads/${status.resolvedRef}`,
+            ]);
+            runGit([
+                "-C",
+                targetDir,
+                "checkout",
+                "-B",
+                status.resolvedRef,
+                "FETCH_HEAD",
+            ]);
+        }
+        else if (status.refKind === "tag") {
+            runGit([
+                "-C",
+                targetDir,
+                "fetch",
+                "--depth=1",
+                "origin",
+                `refs/tags/${status.resolvedRef}`,
+            ]);
+            runGit(["-C", targetDir, "checkout", "--detach", "FETCH_HEAD"]);
+        }
+        else {
+            runGit([
+                "-C",
+                targetDir,
+                "fetch",
+                "--depth=1",
+                "origin",
+                status.remoteCommit,
+            ]);
+            runGit(["-C", targetDir, "checkout", "--detach", "FETCH_HEAD"]);
+        }
+    }
+    catch (error) {
+        throw normalizeGitError(error, `Failed to update ${options.source}`, {
+            source: options.source,
+            protocol: options.protocol,
+        });
+    }
+    const refreshed = readCachedSourceRevision(options);
+    return {
+        ...status,
+        currentCommit: refreshed.currentCommit ?? status.remoteCommit,
+        currentRef: refreshed.currentRef,
+        remoteUrl: refreshed.remoteUrl ?? status.remoteUrl,
+        previousCommit: initialRevision.currentCommit,
+        updated: status.currentCommit !== status.remoteCommit ||
+            requiresCheckoutRealignment,
+    };
+}
+function rewriteInspectFailureForUpdate(error, source) {
+    if (error instanceof Error &&
+        error.message.startsWith(`Failed to inspect ${source}`)) {
+        return new Error(error.message.replace(`Failed to inspect ${source}`, `Failed to update ${source}`));
+    }
+    return error instanceof Error ? error : new Error(String(error));
+}
+/** Moves a cached source checkout back to a previously recorded revision. */
+function restoreCachedRemoteSourceRevision(options) {
+    const targetDir = getTargetDir(options);
+    if (options.refName) {
+        runGit([
+            "-C",
+            targetDir,
+            "checkout",
+            "-B",
+            options.refName,
+            options.commit,
+        ]);
+        return;
+    }
+    runGit(["-C", targetDir, "checkout", "--detach", options.commit]);
+}
+/** Deletes one cached source checkout without reporting whether it existed. */
+function removeCachedRemoteSource(options) {
+    node_fs_1.default.rmSync(getTargetDir(options), { recursive: true, force: true });
+}
+/**
+ * Clears the cached clone for a source and re-clones it fresh at HEAD.
+ *
+ * Clones into a sibling `.tmp` directory first so the existing cache survives
+ * any network or authentication failure — the working copy is only replaced
+ * after the clone succeeds.
+ *
+ * Respects protocol switching: if the stored origin URL uses a different
+ * transport than `options.protocol` (e.g. the cache was SSH but the caller
+ * requests HTTPS), a fresh URL is constructed from the source identifier so the
+ * new protocol takes effect. Local-path remotes used in tests are left as-is
+ * because they don't start with `git@` and therefore match `"https"` by default.
+ */
+function clearAndRefetchCachedRemoteSource(options) {
+    const targetDir = getTargetDir(options);
+    const revision = readCachedSourceRevision(options);
+    const isStoredSsh = revision.remoteUrl?.startsWith("git@") ?? false;
+    const cloneUrl = revision.remoteUrl && isStoredSsh === (options.protocol === "ssh")
+        ? revision.remoteUrl
+        : getCloneUrl(options.source, options.protocol);
+    const tempDir = `${targetDir}.tmp`;
+    node_fs_1.default.rmSync(tempDir, { recursive: true, force: true });
+    node_fs_1.default.mkdirSync(node_path_1.default.dirname(targetDir), { recursive: true });
+    try {
+        runGit(["clone", "--depth=1", cloneUrl, tempDir]);
+        node_fs_1.default.rmSync(targetDir, { recursive: true, force: true });
+        node_fs_1.default.renameSync(tempDir, targetDir);
+    }
+    catch (error) {
+        node_fs_1.default.rmSync(tempDir, { recursive: true, force: true });
+        throw normalizeGitError(error, `Failed to clone ${cloneUrl}`, {
+            source: options.source,
+            protocol: options.protocol,
+        });
+    }
+}
+function getTargetDir(options) {
+    assertSafeSource(options.source);
+    return node_path_1.default.join(options.libraryDir, ...options.source.split("/"));
+}
+function getCloneUrl(source, protocol = "https") {
+    assertSafeSource(source);
+    const [host, owner, repo] = source.split("/");
+    return protocol === "ssh"
+        ? `git@${host}:${owner}/${repo}.git`
+        : `https://${source}`;
+}
+function resolveRemoteRef(remoteUrl, requestedRef) {
+    if (requestedRef && isCommitSha(requestedRef)) {
+        return { kind: "commit", commit: requestedRef };
+    }
+    if (requestedRef) {
+        const branchCommit = parseFirstSha(runGit(["ls-remote", remoteUrl, `refs/heads/${requestedRef}`]));
+        if (branchCommit) {
+            return {
+                kind: "branch",
+                resolvedRef: requestedRef,
+                commit: branchCommit,
+            };
+        }
+        const tagOutput = runGit([
+            "ls-remote",
+            remoteUrl,
+            `refs/tags/${requestedRef}`,
+            `refs/tags/${requestedRef}^{}`,
+        ]);
+        const tagCommit = parsePreferredTagSha(tagOutput, requestedRef);
+        if (tagCommit) {
+            return { kind: "tag", resolvedRef: requestedRef, commit: tagCommit };
+        }
+        throw new Error(`Remote ref not found: ${requestedRef}`);
+    }
+    const headOutput = runGit(["ls-remote", "--symref", remoteUrl, "HEAD"]);
+    const headRef = parseHeadRef(headOutput);
+    const headCommit = parseHeadCommit(headOutput);
+    if (!headRef || !headCommit) {
+        throw new Error(`Failed to resolve remote HEAD for ${remoteUrl}`);
+    }
+    return { kind: "branch", resolvedRef: headRef, commit: headCommit };
+}
+function parseHeadRef(output) {
+    for (const line of output.split("\n")) {
+        const match = line.match(/^ref:\s+refs\/heads\/(.+)\s+HEAD$/);
+        if (match) {
+            return match[1];
+        }
+    }
+    return undefined;
+}
+function parseHeadCommit(output) {
+    for (const line of output.split("\n")) {
+        const match = line.match(/^([0-9a-f]{7,40})\s+HEAD$/i);
+        if (match) {
+            return match[1];
+        }
+    }
+    return undefined;
+}
+function parsePreferredTagSha(output, tagName) {
+    const peeledPattern = new RegExp(`^([0-9a-f]{7,40})\\s+refs/tags/${(0, fs_utils_1.escapeRegExp)(tagName)}\\^{}$`, "i");
+    const directPattern = new RegExp(`^([0-9a-f]{7,40})\\s+refs/tags/${(0, fs_utils_1.escapeRegExp)(tagName)}$`, "i");
+    let directCommit;
+    for (const line of output.split("\n")) {
+        const peeledMatch = line.match(peeledPattern);
+        if (peeledMatch) {
+            return peeledMatch[1];
+        }
+        const directMatch = line.match(directPattern);
+        if (directMatch) {
+            directCommit = directMatch[1];
+        }
+    }
+    return directCommit;
+}
+function parseFirstSha(output) {
+    for (const line of output.split("\n")) {
+        const match = line.match(/^([0-9a-f]{7,40})\s+/i);
+        if (match) {
+            return match[1];
+        }
+    }
+    return undefined;
+}
+function normalizeCurrentRef(value) {
+    if (!value) {
+        return undefined;
+    }
+    return value.replace(/^heads\//, "");
+}
+function runGit(args) {
+    try {
+        return String((0, node_child_process_1.execFileSync)("git", args, {
+            encoding: "utf8",
+            stdio: ["ignore", "pipe", "pipe"],
+        })).trim();
+    }
+    catch (error) {
+        if (error instanceof Error &&
+            "code" in error &&
+            error.code === "ENOENT") {
+            throw new Error("git is not installed or not on PATH. Install git to fetch remote bundles.");
+        }
+        throw error;
+    }
+}
+function tryRunGit(args) {
+    try {
+        const result = runGit(args);
+        return result === "" ? undefined : result;
+    }
+    catch {
+        return undefined;
+    }
+}
+function normalizeGitError(error, prefix, context) {
+    if (error instanceof Error &&
+        "code" in error &&
+        error.code === "ENOENT") {
+        return new Error("git is not installed or not on PATH. Install git to fetch remote bundles.");
+    }
+    const stderr = error instanceof Error && "stderr" in error
+        ? String(error.stderr).trim()
+        : String(error);
+    let message = `${prefix}${stderr ? `:\n${stderr}` : ""}`;
+    if ((context.protocol ?? "https") === "ssh" &&
+        SSH_AUTH_FAILURE_RE.test(stderr)) {
+        message += `\nHint: SSH authentication failed. To clone via HTTPS instead, omit --ssh:\n  skul add ${context.source}`;
+    }
+    return new Error(message);
+}
+function assertSafeSource(source) {
+    if (!SAFE_SOURCE_RE.test(source)) {
+        throw new Error(`Invalid bundle source: ${source}`);
+    }
+}
+function isCommitSha(value) {
+    return /^[0-9a-f]{7,40}$/i.test(value);
+}
+//# sourceMappingURL=bundle-fetch.js.map

package/dist/bundle-fetch.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"bundle-fetch.js","sourceRoot":"","sources":["../src/bundle-fetch.ts"],"names":[],"mappings":"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"}

package/dist/bundle-items.d.ts

@@ -0,0 +1,34 @@
+import type { BundleManifest } from "./bundle-manifest";
+import { type ToolName, type ToolTargetName } from "./tool-mapping";
+export type BundleItemSelector = string;
+/** Normalizes one user-facing bundle item selector. */
+export declare function normalizeBundleItemSelector(selector: string): BundleItemSelector;
+/** Normalizes and deduplicates bundle item selectors while preserving order. */
+export declare function normalizeBundleItemSelectors(selectors: string[]): BundleItemSelector[];
+/** Returns true when a root-instruction target should be materialized. */
+export declare function isRootInstructionItemSelected(selectors: BundleItemSelector[] | undefined): boolean;
+/** Returns true when a directory target item should be materialized. */
+export declare function isDirectoryItemSelected(options: {
+    selectors: BundleItemSelector[] | undefined;
+    targetName: ToolTargetName;
+    entryName: string;
+}): boolean;
+/** Lists installable item selectors available from a cached bundle. */
+export declare function listSelectableBundleItems(options: {
+    bundleDir: string;
+    manifest: BundleManifest;
+    tools?: ToolName[];
+}): BundleItemSelector[];
+/** Throws when requested item selectors are not present in the selected bundle scope. */
+export declare function assertBundleSupportsRequestedItems(options: {
+    requestedItems: BundleItemSelector[];
+    availableItems: BundleItemSelector[];
+}): void;
+/** Merges item selections, returning undefined when the whole bundle is selected. */
+export declare function mergeDesiredBundleItems(options: {
+    existingItems?: BundleItemSelector[];
+    requestedItems?: BundleItemSelector[];
+    replace?: boolean;
+}): BundleItemSelector[] | undefined;
+/** Returns true when two optional selector lists describe the same bundle item set. */
+export declare function bundleItemSelectionsEqual(left?: BundleItemSelector[], right?: BundleItemSelector[]): boolean;

package/dist/bundle-items.js

@@ -0,0 +1,149 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.normalizeBundleItemSelector = normalizeBundleItemSelector;
+exports.normalizeBundleItemSelectors = normalizeBundleItemSelectors;
+exports.isRootInstructionItemSelected = isRootInstructionItemSelected;
+exports.isDirectoryItemSelected = isDirectoryItemSelected;
+exports.listSelectableBundleItems = listSelectableBundleItems;
+exports.assertBundleSupportsRequestedItems = assertBundleSupportsRequestedItems;
+exports.mergeDesiredBundleItems = mergeDesiredBundleItems;
+exports.bundleItemSelectionsEqual = bundleItemSelectionsEqual;
+const node_fs_1 = __importDefault(require("node:fs"));
+const node_path_1 = __importDefault(require("node:path"));
+const tool_mapping_1 = require("./tool-mapping");
+const ROOT_INSTRUCTION_SELECTOR = "root-instruction";
+const DIRECTORY_TARGET_NAMES = new Set([
+    "skills",
+    "commands",
+    "agents",
+]);
+/** Normalizes one user-facing bundle item selector. */
+function normalizeBundleItemSelector(selector) {
+    const value = selector.trim().replaceAll("\\", "/");
+    if (value === ROOT_INSTRUCTION_SELECTOR ||
+        value === "AGENTS.md" ||
+        value === "CLAUDE.md" ||
+        value === "GEMINI.md" ||
+        value === ".github/copilot-instructions.md") {
+        return ROOT_INSTRUCTION_SELECTOR;
+    }
+    const [targetName, itemName, ...rest] = value.split("/");
+    if (rest.length > 0) {
+        throw new Error(`Bundle item selector must target one top-level item: ${selector}`);
+    }
+    if (!isDirectoryTargetName(targetName)) {
+        throw new Error(`Bundle item selector must start with skills/, commands/, agents/, or be root-instruction: ${selector}`);
+    }
+    return `${targetName}/${normalizeBundleItemName(itemName, selector)}`;
+}
+function isDirectoryTargetName(value) {
+    return (value !== undefined && DIRECTORY_TARGET_NAMES.has(value));
+}
+function normalizeBundleItemName(value, originalSelector) {
+    if (!value || value === "." || value === "..") {
+        throw new Error(`Bundle item selector is missing an item name: ${originalSelector}`);
+    }
+    return stripKnownItemExtension(value);
+}
+function stripKnownItemExtension(value) {
+    if (value.endsWith(".agent.md")) {
+        return value.slice(0, -".agent.md".length);
+    }
+    return value.replace(/\.(md|toml|yaml|yml|json)$/i, "");
+}
+/** Normalizes and deduplicates bundle item selectors while preserving order. */
+function normalizeBundleItemSelectors(selectors) {
+    const normalized = selectors.map(normalizeBundleItemSelector);
+    return Array.from(new Set(normalized));
+}
+/** Returns true when a root-instruction target should be materialized. */
+function isRootInstructionItemSelected(selectors) {
+    return !selectors || selectors.includes(ROOT_INSTRUCTION_SELECTOR);
+}
+/** Returns true when a directory target item should be materialized. */
+function isDirectoryItemSelected(options) {
+    if (!options.selectors) {
+        return true;
+    }
+    return options.selectors.includes(`${options.targetName}/${stripKnownItemExtension(options.entryName)}`);
+}
+/** Lists installable item selectors available from a cached bundle. */
+function listSelectableBundleItems(options) {
+    const selectors = new Set();
+    const toolEntries = selectManifestToolEntries(options.manifest, options.tools);
+    for (const [toolName, targets] of toolEntries) {
+        for (const [targetName, target] of Object.entries(targets)) {
+            if (targetName === "root_instruction") {
+                selectors.add(ROOT_INSTRUCTION_SELECTOR);
+                continue;
+            }
+            if (!isDirectoryTargetName(targetName)) {
+                continue;
+            }
+            const targetDefinition = (0, tool_mapping_1.getToolDefinition)(toolName)?.targets[targetName];
+            if (targetDefinition?.kind !== "directory") {
+                continue;
+            }
+            for (const itemName of listTargetItemNames({
+                sourceDir: node_path_1.default.join(options.bundleDir, target.path),
+                targetName,
+            })) {
+                selectors.add(`${targetName}/${itemName}`);
+            }
+        }
+    }
+    return Array.from(selectors).sort((left, right) => left.localeCompare(right));
+}
+function selectManifestToolEntries(manifest, tools) {
+    return (tools && tools.length > 0
+        ? Object.entries(manifest.tools).filter(([toolName]) => tools.includes(toolName))
+        : Object.entries(manifest.tools));
+}
+function listTargetItemNames(options) {
+    if (!node_fs_1.default.existsSync(options.sourceDir)) {
+        return [];
+    }
+    return node_fs_1.default
+        .readdirSync(options.sourceDir, { withFileTypes: true })
+        .filter((entry) => isSelectableTargetEntry(entry, options.targetName))
+        .map((entry) => stripKnownItemExtension(entry.name));
+}
+function isSelectableTargetEntry(entry, targetName) {
+    if (targetName === "skills") {
+        return entry.isDirectory();
+    }
+    return entry.isFile();
+}
+/** Throws when requested item selectors are not present in the selected bundle scope. */
+function assertBundleSupportsRequestedItems(options) {
+    const unsupportedItems = options.requestedItems.filter((item) => !options.availableItems.includes(item));
+    if (unsupportedItems.length === 0) {
+        return;
+    }
+    throw new Error(`Bundle does not include item(s): ${unsupportedItems.join(", ")}\nAvailable items: ${options.availableItems.join(", ")}`);
+}
+/** Merges item selections, returning undefined when the whole bundle is selected. */
+function mergeDesiredBundleItems(options) {
+    if (options.requestedItems === undefined) {
+        return undefined;
+    }
+    if (options.replace) {
+        return [...options.requestedItems];
+    }
+    return Array.from(new Set([...(options.existingItems ?? []), ...options.requestedItems]));
+}
+/** Returns true when two optional selector lists describe the same bundle item set. */
+function bundleItemSelectionsEqual(left, right) {
+    if (!left && !right) {
+        return true;
+    }
+    if (!left || !right || left.length !== right.length) {
+        return false;
+    }
+    const rightSet = new Set(right);
+    return left.every((item) => rightSet.has(item));
+}
+//# sourceMappingURL=bundle-items.js.map

package/dist/bundle-items.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"bundle-items.js","sourceRoot":"","sources":["../src/bundle-items.ts"],"names":[],"mappings":"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"}