akm-cli 0.5.0 → 0.6.0-rc2

package/dist/{stash-providers → sources/providers}/git.js

@@ -2,45 +2,95 @@ import { spawnSync } from "node:child_process";
 import { createHash, randomBytes } from "node:crypto";
 import fs from "node:fs";
 import path from "node:path";
-import { resolveStashDir } from "../common";
-import { loadConfig } from "../config";
-import { ConfigError, UsageError } from "../errors";
-import { getRegistryIndexCacheDir } from "../paths";
-import { validateGitUrl } from "../registry-resolve";
-import { registerStashProvider } from "../stash-provider-factory";
-import { isExpired, sanitizeString } from "./provider-utils";
+import { resolveStashDir } from "../../core/common";
+import { loadConfig } from "../../core/config";
+import { ConfigError, UsageError } from "../../core/errors";
+import { getRegistryCacheDir, getRegistryIndexCacheDir } from "../../core/paths";
+import { parseRegistryRef, resolveRegistryArtifact, validateGitRef, validateGitUrl } from "../../registry/resolve";
+import { registerSourceProvider } from "../provider-factory";
+import { applyAkmIncludeConfig, buildInstallCacheDir, copyDirectoryContents, detectStashRoot, isDirectory, isExpired, sanitizeString, } from "./provider-utils";
 /** Cache TTL before refreshing the mirrored repo (12 hours). */
 const CACHE_TTL_MS = 12 * 60 * 60 * 1000;
 /** Maximum stale age allowed when refresh fails (7 days). */
 const CACHE_STALE_MS = 7 * 24 * 60 * 60 * 1000;
-const GIT_STASH_TYPES = new Set(["git", "context-hub", "github"]);
-class GitStashProvider {
-    type = "git";
+const GIT_STASH_TYPES = new Set(["git"]);
+/**
+ * Git source provider — clones (and re-pulls) a remote repo into a local
+ * cache directory. Implements the v1 {@link SourceProvider} interface (spec
+ * §2.1, §2.5): `{ name, kind, init, path, sync }`.
+ *
+ * Reading is the indexer's job — this class doesn't implement `search` or
+ * `show`. The install-time helpers `syncRegistryGitRef` / `syncMirroredRepo`
+ * live below as standalone functions used by `akm add` / `akm update`.
+ */
+class GitSourceProvider {
+    kind = "git";
     name;
+    #config;
+    #path = null;
     constructor(config) {
+        this.#config = config;
         this.name = config.name ?? "git";
     }
-    /** Content is indexed through the standard FTS5 pipeline. */
-    async search(_options) {
-        return { hits: [] };
-    }
-    /** Content is local files, shown via showLocal. */
-    async show(_ref, _view) {
-        throw new Error("Git provider content is shown via local index");
-    }
-    /** Content is local; no remote show needed. */
-    canShow(_ref) {
-        return false;
+    async init(_ctx) {
+        // Resolve the on-disk content directory once. For configured git sources
+        // this is the cached working tree; for one-shot install refs it's the
+        // path the install pipeline materialised.
+        this.#path = resolveGitContentDir(this.#config);
+    }
+    path() {
+        if (this.#path == null) {
+            // Lazy resolution: providers are sometimes constructed without an
+            // explicit init() call (e.g. by legacy callers that just want the
+            // path). Resolve on demand and cache.
+            this.#path = resolveGitContentDir(this.#config);
+        }
+        return this.#path;
+    }
+    async sync() {
+        // Two execution modes:
+        //   1. Long-lived configured source (config.url) — mirror into the
+        //      registry-index cache and serve as a read-only working tree.
+        //   2. One-shot install ref (options.ref like "git:..." / "github:...") —
+        //      delegate to the install-time pipeline.
+        if (typeof this.#config.options?.ref === "string" && this.#config.options.ref) {
+            await syncRegistryGitRef(String(this.#config.options.ref));
+            return;
+        }
+        await syncMirroredRepo(this.#config);
     }
 }
+/** Resolve the on-disk content directory for a configured git source. */
+function resolveGitContentDir(config) {
+    if (config.path)
+        return config.path;
+    if (config.url) {
+        const repo = parseGitRepoUrl(config.url);
+        return getCachePaths(repo.canonicalUrl).repoDir;
+    }
+    throw new ConfigError("git source entry must have either `path` or `url`");
+}
 // ── Self-register ───────────────────────────────────────────────────────────
-registerStashProvider("git", (config) => new GitStashProvider(config));
-registerStashProvider("context-hub", (config) => new GitStashProvider(config));
-registerStashProvider("github", (config) => new GitStashProvider(config));
+registerSourceProvider("git", (config) => new GitSourceProvider(config));
 // ── Cache management ────────────────────────────────────────────────────────
 function getCachePaths(repoUrl) {
     const key = createHash("sha256").update(repoUrl).digest("hex").slice(0, 16);
-    const rootDir = path.join(getRegistryIndexCacheDir(), `context-hub-${key}`);
+    const cacheRoot = getRegistryIndexCacheDir();
+    const rootDir = path.join(cacheRoot, `git-${key}`);
+    // One-time silent migration: legacy `context-hub-${key}` directories were
+    // created for ALL git stashes (not just the andrewyng/context-hub repo). If
+    // the new path doesn't yet exist but the legacy one does, rename it in place
+    // so existing clones aren't silently invalidated. Failures are non-fatal —
+    // worst case the repo is re-cloned on the next refresh.
+    try {
+        const legacyRootDir = path.join(cacheRoot, `context-hub-${key}`);
+        if (!fs.existsSync(rootDir) && fs.existsSync(legacyRootDir)) {
+            fs.renameSync(legacyRootDir, rootDir);
+        }
+    }
+    catch {
+        /* migration is best-effort */
+    }
     return {
         rootDir,
         repoDir: path.join(rootDir, "repo"),
@@ -50,6 +100,7 @@ function getCachePaths(repoUrl) {
 async function ensureGitMirror(repo, cachePaths, options) {
     const requireRepoDir = options?.requireRepoDir === true;
     const writable = options?.writable === true;
+    const force = options?.force === true;
     // Check if cache is fresh
     let mtime = 0;
     try {
@@ -58,7 +109,7 @@ async function ensureGitMirror(repo, cachePaths, options) {
     catch {
         /* no cached index */
     }
-    if (mtime && !isExpired(mtime, CACHE_TTL_MS) && (!requireRepoDir || hasExtractedRepo(cachePaths.repoDir))) {
+    if (!force && mtime && !isExpired(mtime, CACHE_TTL_MS) && (!requireRepoDir || hasExtractedRepo(cachePaths.repoDir))) {
         return;
     }
     try {
@@ -80,6 +131,145 @@ async function ensureGitMirror(repo, cachePaths, options) {
         throw err;
     }
 }
+/**
+ * Sync mode for a long-lived configured git stash. Mirrors the repo into the
+ * shared registry-index cache (12h TTL) and exposes the working tree as the
+ * stash content directory.
+ */
+async function syncMirroredRepo(config, options) {
+    if (!config.url) {
+        throw new ConfigError("git stash entry requires a URL when no install ref is supplied");
+    }
+    const repo = parseGitRepoUrl(config.url);
+    const cachePaths = getCachePaths(repo.canonicalUrl);
+    await ensureGitMirror(repo, cachePaths, {
+        requireRepoDir: true,
+        writable: options?.writable ?? config.writable === true,
+        force: options?.force,
+    });
+    const syncedAt = (options?.now ?? new Date()).toISOString();
+    const contentDir = cachePaths.repoDir;
+    return {
+        id: repo.canonicalUrl,
+        source: "git",
+        ref: repo.canonicalUrl,
+        artifactUrl: repo.canonicalUrl,
+        contentDir,
+        cacheDir: cachePaths.rootDir,
+        extractedDir: contentDir,
+        writable: options?.writable ?? config.writable === true,
+        syncedAt,
+    };
+}
+/**
+ * Sync mode for a one-shot install ref (`akm add github:owner/repo` or
+ * `akm add git:url`). Runs the clone → strip → include-filter pipeline that
+ * historically lived in `installRegistryRef()`.
+ */
+export async function syncRegistryGitRef(ref, options) {
+    const parsed = parseRegistryRef(ref);
+    if (parsed.source === "github") {
+        const githubRef = {
+            source: "git",
+            ref: parsed.ref,
+            id: parsed.id,
+            url: `https://github.com/${parsed.owner}/${parsed.repo}.git`,
+            requestedRef: parsed.requestedRef,
+        };
+        const result = await doSyncGit(githubRef, options);
+        return { ...result, source: "github" };
+    }
+    if (parsed.source !== "git") {
+        throw new UsageError(`syncRegistryGitRef requires a git: or github: ref, got "${ref}"`);
+    }
+    return doSyncGit(parsed, options);
+}
+async function doSyncGit(parsed, options) {
+    const resolved = await resolveRegistryArtifact(parsed);
+    const syncedAt = (options?.now ?? new Date()).toISOString();
+    const cacheRootDir = options?.cacheRootDir ?? getRegistryCacheDir();
+    const cacheDir = buildInstallCacheDir(cacheRootDir, parsed.source, parsed.id, resolved.resolvedRevision);
+    const cloneDir = path.join(cacheDir, "clone");
+    const extractedDir = path.join(cacheDir, "extracted");
+    // Cache hit
+    if (!options?.force && isDirectory(extractedDir)) {
+        try {
+            const provisionalKitRoot = detectStashRoot(extractedDir);
+            const installRoot = applyAkmIncludeConfig(provisionalKitRoot, cacheDir, extractedDir) ?? provisionalKitRoot;
+            const stashRoot = detectStashRoot(installRoot);
+            if (stashRoot) {
+                return {
+                    id: resolved.id,
+                    source: resolved.source,
+                    ref: resolved.ref,
+                    artifactUrl: resolved.artifactUrl,
+                    resolvedVersion: resolved.resolvedVersion,
+                    resolvedRevision: resolved.resolvedRevision,
+                    contentDir: stashRoot,
+                    cacheDir,
+                    extractedDir,
+                    writable: options?.writable,
+                    syncedAt,
+                };
+            }
+        }
+        catch {
+            // Cache invalid, re-clone
+        }
+    }
+    fs.mkdirSync(cacheDir, { recursive: true });
+    // Validate URL and ref before passing to git to prevent command injection
+    validateGitUrl(parsed.url);
+    if (parsed.requestedRef)
+        validateGitRef(parsed.requestedRef);
+    let provisionalKitRoot;
+    let installRoot;
+    let stashRoot;
+    try {
+        const cloneArgs = ["clone", "--depth", "1"];
+        if (parsed.requestedRef) {
+            cloneArgs.push("--branch", parsed.requestedRef);
+        }
+        cloneArgs.push(parsed.url, cloneDir);
+        const cloneResult = spawnSync("git", cloneArgs, { encoding: "utf8", timeout: 120_000 });
+        if (cloneResult.status !== 0) {
+            const err = cloneResult.stderr?.trim() || cloneResult.error?.message || "unknown error";
+            throw new Error(`Failed to clone ${parsed.url}: ${err}`);
+        }
+        // Copy contents to extracted dir without .git
+        fs.mkdirSync(extractedDir, { recursive: true });
+        copyDirectoryContents(cloneDir, extractedDir);
+        // Clean up the clone dir
+        fs.rmSync(cloneDir, { recursive: true, force: true });
+        provisionalKitRoot = detectStashRoot(extractedDir);
+        installRoot = applyAkmIncludeConfig(provisionalKitRoot, cacheDir, extractedDir) ?? provisionalKitRoot;
+        stashRoot = detectStashRoot(installRoot);
+    }
+    catch (err) {
+        // Clean up the cache directory so stale or partially-cloned artifacts
+        // don't cause false cache hits on the next install attempt.
+        try {
+            fs.rmSync(cacheDir, { recursive: true, force: true });
+        }
+        catch {
+            /* best-effort */
+        }
+        throw err;
+    }
+    return {
+        id: resolved.id,
+        source: resolved.source,
+        ref: resolved.ref,
+        artifactUrl: resolved.artifactUrl,
+        resolvedVersion: resolved.resolvedVersion,
+        resolvedRevision: resolved.resolvedRevision,
+        contentDir: stashRoot,
+        cacheDir,
+        extractedDir,
+        writable: options?.writable,
+        syncedAt,
+    };
+}
 export function cloneRepo(cloneUrl, ref, destDir, writable = false) {
     // Stage the clone into a sibling temp dir so that a failed clone never
     // destroys a previously-valid destDir (e.g. when the remote is temporarily
@@ -213,7 +403,7 @@ export function saveGitStash(name, message, writableOverride) {
     let writable = false;
     if (name) {
         const config = loadConfig();
-        const stash = config.stashes?.find((s) => s.name === name || s.url === name);
+        const stash = (config.sources ?? config.stashes ?? []).find((s) => s.name === name || s.url === name);
         if (!stash)
             throw new UsageError(`No git stash found with name "${name}"`);
         if (!GIT_STASH_TYPES.has(stash.type)) {
@@ -275,4 +465,4 @@ export function saveGitStash(name, message, writableOverride) {
     };
 }
 // ── Exports ─────────────────────────────────────────────────────────────────
-export { ensureGitMirror, GitStashProvider, getCachePaths, parseGitRepoUrl };
+export { ensureGitMirror, GitSourceProvider, getCachePaths, parseGitRepoUrl };

package/dist/{stash-providers → sources/providers}/index.js

@@ -1,11 +1,11 @@
 /**
- * Centralized stash provider registration.
+ * Centralized source provider registration.
  *
- * Import this module (side-effect import) to register all built-in stash
+ * Import this module (side-effect import) to register all built-in source
  * providers with the provider registry. This replaces the individual
- * side-effect imports that were duplicated in stash-search.ts and stash-show.ts.
+ * side-effect imports that were duplicated in source-search.ts and source-show.ts.
  */
 import "./filesystem";
 import "./git";
-import "./openviking";
+import "./npm";
 import "./website";

package/dist/sources/providers/install-types.js

@@ -0,0 +1,14 @@
+/**
+ * Install-time types used by `syncFromRef` and the legacy install pipeline.
+ *
+ * Distinct from the v1 {@link SourceProvider} interface (which only deals
+ * with "configured sources" — entries already resolved into a directory).
+ * These types describe the resolution+lockfile step that runs when
+ * `akm add <install-ref>` materialises an upstream artifact into a local
+ * cache directory.
+ *
+ * They live here, outside `provider.ts`, so the v1 SourceProvider
+ * interface stays minimal (`{ name, kind, init, path, sync? }`) per the
+ * architecture spec §2.1.
+ */
+export {};

package/dist/sources/providers/npm.js

@@ -0,0 +1,160 @@
+/**
+ * Npm-source stash provider.
+ *
+ * `sync()` resolves the npm package tarball, downloads it, verifies its
+ * integrity, extracts it securely (via `extractTarGzSecure`), detects the
+ * stash root inside the package, and applies any nested `.akm-include`
+ * configuration. Cache hits short-circuit the fetch.
+ *
+ * Audit is intentionally NOT performed here — `akmAdd` calls
+ * `auditInstallCandidate` after `sync()` so the policy decision lives at
+ * the orchestrator layer where the `--trust` flag is known.
+ */
+import fs from "node:fs";
+import path from "node:path";
+import { ConfigError, UsageError } from "../../core/errors";
+import { getRegistryCacheDir } from "../../core/paths";
+import { parseRegistryRef, resolveRegistryArtifact } from "../../registry/resolve";
+import { registerSourceProvider } from "../provider-factory";
+import { applyAkmIncludeConfig, buildInstallCacheDir, computeFileHash, detectStashRoot, downloadArchive, isDirectory, } from "./provider-utils";
+import { extractTarGzSecure, verifyArchiveIntegrity } from "./tar-utils";
+/**
+ * NPM source provider — fetches a tarball from the npm registry and extracts
+ * it into a local cache. Implements the v1 {@link SourceProvider} interface
+ * (spec §2.1): `{ name, kind, init, path, sync }`.
+ *
+ * The install-time pipeline (`syncNpmRef`) lives below as a standalone
+ * function used by `akm add` / `akm update` — that path produces a
+ * {@link SourceLockData} record for lockfile bookkeeping. The provider's own
+ * `sync()` is a void refresh (delegates to the install pipeline but discards
+ * the lock data, which is owned by `lockfile.ts`).
+ */
+class NpmSourceProvider {
+    kind = "npm";
+    name;
+    #config;
+    constructor(config) {
+        this.#config = config;
+        this.name = config.name ?? config.url ?? "npm";
+    }
+    async init(_ctx) {
+        // Resolution happens lazily in path(): until `sync()` runs there's no
+        // reliable on-disk path. Init is the registration handshake.
+    }
+    path() {
+        if (this.#config.path)
+            return this.#config.path;
+        throw new ConfigError(`npm source "${this.name}" has no resolved content path — run \`akm update\` to sync it before indexing.`);
+    }
+    async sync() {
+        const ref = npmRefFromConfig(this.#config);
+        await syncNpmRef(ref);
+    }
+}
+registerSourceProvider("npm", (config) => new NpmSourceProvider(config));
+function npmRefFromConfig(config) {
+    // Prefer an explicit ref-bearing field (set by akmAdd when persisting), else fall back
+    // to options or url so the provider stays usable from a hand-rolled config.
+    const candidate = config.options?.ref ?? config.url ?? config.options?.package ?? config.name;
+    if (typeof candidate !== "string" || !candidate) {
+        throw new UsageError('npm stash entry must include an `options.ref` (e.g. "npm:my-pkg@1.2.3")');
+    }
+    return candidate.startsWith("npm:") ? candidate : `npm:${candidate}`;
+}
+/**
+ * Fetch and extract an npm tarball, returning a populated `SourceLockData`.
+ *
+ * Mirrors the historical `installRegistryRef()` path for npm sources:
+ *   - resolve artifact URL + integrity from the npm registry
+ *   - reuse cached extraction when present
+ *   - download, verify, extract securely, then detect the stash root
+ *   - honour `.akm-include` filters
+ */
+export async function syncNpmRef(ref, options) {
+    const parsed = parseRegistryRef(ref);
+    if (parsed.source !== "npm") {
+        throw new UsageError(`syncNpmRef requires an npm: ref, got "${ref}"`);
+    }
+    return doSyncNpm(parsed, options);
+}
+async function doSyncNpm(parsed, options) {
+    const resolved = await resolveRegistryArtifact(parsed);
+    const syncedAt = (options?.now ?? new Date()).toISOString();
+    const cacheRootDir = options?.cacheRootDir ?? getRegistryCacheDir();
+    const cacheDir = buildInstallCacheDir(cacheRootDir, resolved.source, resolved.id, resolved.resolvedVersion ?? resolved.resolvedRevision);
+    const archivePath = path.join(cacheDir, "artifact.tar.gz");
+    const extractedDir = path.join(cacheDir, "extracted");
+    // Cache hit: extracted dir already valid → reuse it
+    if (!options?.force && isDirectory(extractedDir)) {
+        try {
+            const cachedStashRoot = detectStashRoot(extractedDir);
+            if (cachedStashRoot) {
+                const integrity = fs.existsSync(archivePath) ? await computeFileHash(archivePath) : undefined;
+                return {
+                    id: resolved.id,
+                    source: resolved.source,
+                    ref: resolved.ref,
+                    artifactUrl: resolved.artifactUrl,
+                    resolvedVersion: resolved.resolvedVersion,
+                    resolvedRevision: resolved.resolvedRevision,
+                    contentDir: cachedStashRoot,
+                    cacheDir,
+                    extractedDir,
+                    integrity,
+                    writable: options?.writable,
+                    syncedAt,
+                };
+            }
+        }
+        catch {
+            // Cache invalid, re-download
+        }
+    }
+    fs.mkdirSync(cacheDir, { recursive: true });
+    let integrity;
+    let provisionalKitRoot;
+    let installRoot;
+    let stashRoot;
+    try {
+        await downloadArchive(resolved.artifactUrl, archivePath);
+        verifyArchiveIntegrity(archivePath, resolved.resolvedRevision, resolved.source);
+        integrity = await computeFileHash(archivePath);
+        extractTarGzSecure(archivePath, extractedDir);
+        const detectedProvisionalKitRoot = detectStashRoot(extractedDir);
+        if (!detectedProvisionalKitRoot) {
+            throw new UsageError(`Unable to detect a stash root in extracted npm package: ${resolved.ref}`);
+        }
+        provisionalKitRoot = detectedProvisionalKitRoot;
+        installRoot = applyAkmIncludeConfig(provisionalKitRoot, cacheDir, extractedDir) ?? provisionalKitRoot;
+        const detectedStashRoot = detectStashRoot(installRoot);
+        if (!detectedStashRoot) {
+            throw new UsageError(`Unable to detect a stash root after applying .akm-include configuration for npm package: ${resolved.ref}`);
+        }
+        stashRoot = detectedStashRoot;
+    }
+    catch (err) {
+        // Clean up so stale or partial extractions don't cause false cache hits.
+        try {
+            fs.rmSync(cacheDir, { recursive: true, force: true });
+        }
+        catch {
+            /* best-effort */
+        }
+        throw err;
+    }
+    return {
+        id: resolved.id,
+        source: resolved.source,
+        ref: resolved.ref,
+        artifactUrl: resolved.artifactUrl,
+        resolvedVersion: resolved.resolvedVersion,
+        resolvedRevision: resolved.resolvedRevision,
+        contentDir: stashRoot,
+        cacheDir,
+        extractedDir,
+        integrity,
+        writable: options?.writable,
+        syncedAt,
+    };
+}
+export { NpmSourceProvider };

package/dist/sources/providers/provider-utils.js

@@ -0,0 +1,173 @@
+import { createHash } from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+import { TYPE_DIRS } from "../../core/asset-spec";
+import { fetchWithRetry } from "../../core/common";
+import { copyIncludedPaths, findNearestIncludeConfig } from "../include";
+const REGISTRY_STASH_DIR_NAMES = new Set(Object.values(TYPE_DIRS));
+/** Strip terminal control characters from untrusted strings. */
+export function sanitizeString(value, maxLength = 255) {
+    if (typeof value !== "string")
+        return "";
+    // biome-ignore lint/suspicious/noControlCharactersInRegex: intentional — strip control chars from untrusted remote data
+    return value.replace(/[\u0000-\u001f\u007f]/g, "").slice(0, maxLength);
+}
+/** Check whether a cached timestamp has exceeded its TTL. */
+export function isExpired(mtimeMs, ttlMs) {
+    return Date.now() - mtimeMs > ttlMs;
+}
+/**
+ * Find the directory inside `extractedDir` that should be treated as the
+ * stash root. Looks for a `.stash` marker, then well-known type dirs, then
+ * BFS for the shallowest such candidate.
+ */
+export function detectStashRoot(extractedDir) {
+    const root = path.resolve(extractedDir);
+    const rootDotStash = path.join(root, ".stash");
+    if (isDirectory(rootDotStash)) {
+        return root;
+    }
+    if (hasStashDirs(root)) {
+        return root;
+    }
+    const shallowest = findShallowestStashRoot(root);
+    if (shallowest)
+        return shallowest;
+    return root;
+}
+/**
+ * Build a per-source cache directory under `cacheRootDir`.
+ *
+ * Versioned sources get `${source}-${id}/${version}` for cache reuse;
+ * `local` sources get a unique timestamped slug so each install is isolated.
+ */
+export function buildInstallCacheDir(cacheRootDir, source, id, version) {
+    const slug = `${source}-${id.replace(/[^a-zA-Z0-9_.-]+/g, "-").replace(/^-+|-+$/g, "")}`;
+    const versionSlug = source === "local"
+        ? `${Date.now()}-${Math.random().toString(36).slice(2, 10)}`
+        : (version?.replace(/[^a-zA-Z0-9_.-]+/g, "-") ?? `${Date.now()}-${Math.random().toString(36).slice(2, 10)}`);
+    return path.join(cacheRootDir, slug || source, versionSlug);
+}
+/**
+ * Apply an `.akm-include` config (if any) by copying the selected paths
+ * into a sibling `selected/` directory and returning that path. Returns
+ * undefined when no include config is found.
+ */
+export function applyAkmIncludeConfig(sourceRoot, cacheDir, searchRoot = sourceRoot) {
+    const includeConfig = findNearestIncludeConfig(sourceRoot, searchRoot);
+    if (!includeConfig)
+        return undefined;
+    const selectedDir = path.join(cacheDir, "selected");
+    fs.rmSync(selectedDir, { recursive: true, force: true });
+    fs.mkdirSync(selectedDir, { recursive: true });
+    copyIncludedPaths(includeConfig.include, includeConfig.baseDir, selectedDir);
+    return selectedDir;
+}
+/** Stream a remote archive to disk using Bun.write when available. */
+export async function downloadArchive(url, destination) {
+    const response = await fetchWithRetry(url, undefined, { timeout: 120_000 });
+    if (!response.ok) {
+        throw new Error(`Failed to download archive (${response.status}) from ${url}`);
+    }
+    // Stream response to disk instead of buffering the entire archive in memory.
+    // Uses Bun.write which handles Response streaming natively.
+    const BunRuntime = globalThis
+        .Bun;
+    if (BunRuntime?.write) {
+        await BunRuntime.write(destination, response);
+    }
+    else {
+        // Fallback for non-Bun environments (e.g., tests)
+        const arrayBuffer = await response.arrayBuffer();
+        fs.writeFileSync(destination, Buffer.from(arrayBuffer));
+    }
+}
+/** SHA-256 of a file, returned as `sha256:<hex>`. */
+export async function computeFileHash(filePath) {
+    const data = fs.readFileSync(filePath);
+    const hash = createHash("sha256").update(data).digest("hex");
+    return `sha256:${hash}`;
+}
+/** Recursively copy directory contents, excluding `.git`. */
+export function copyDirectoryContents(sourceDir, destinationDir) {
+    for (const entry of fs.readdirSync(sourceDir, { withFileTypes: true })) {
+        if (entry.name === ".git")
+            continue;
+        const src = path.join(sourceDir, entry.name);
+        const dest = path.join(destinationDir, entry.name);
+        fs.mkdirSync(path.dirname(dest), { recursive: true });
+        if (entry.isDirectory()) {
+            fs.cpSync(src, dest, { recursive: true, force: true });
+        }
+        else {
+            fs.copyFileSync(src, dest);
+        }
+    }
+}
+export function isDirectory(target) {
+    try {
+        return fs.statSync(target).isDirectory();
+    }
+    catch {
+        return false;
+    }
+}
+function hasStashDirs(dirPath) {
+    if (!isDirectory(dirPath))
+        return false;
+    const entries = fs.readdirSync(dirPath, { withFileTypes: true });
+    return entries.some((entry) => entry.isDirectory() && REGISTRY_STASH_DIR_NAMES.has(entry.name));
+}
+function countStashDirs(dirPath) {
+    if (!isDirectory(dirPath))
+        return 0;
+    const entries = fs.readdirSync(dirPath, { withFileTypes: true });
+    return entries.filter((entry) => entry.isDirectory() && REGISTRY_STASH_DIR_NAMES.has(entry.name)).length;
+}
+/**
+ * BFS to find the shallowest directory that looks like a stash root.
+ * Checks for both `.stash` directories and well-known type directories
+ * (scripts/, skills/, etc.), so nested layouts like `project/my-stash/scripts/`
+ * are discovered even without a `.stash` marker.
+ *
+ * Skips `root` itself since the caller already checked it via `hasStashDirs`.
+ */
+const BFS_MAX_DEPTH = 5;
+function findShallowestStashRoot(root) {
+    const queue = [{ dir: root, depth: 0 }];
+    while (queue.length > 0) {
+        const item = queue.shift();
+        if (!item) {
+            continue;
+        }
+        const { dir: current, depth } = item;
+        if (current !== root) {
+            // .stash directory is a strong stash marker
+            if (isDirectory(path.join(current, ".stash"))) {
+                return current;
+            }
+            // Require 2+ type dirs for BFS candidates to avoid false positives.
+            // A single "scripts/" is too common (skill dirs, npm packages, etc.).
+            if (countStashDirs(current) >= 2) {
+                return current;
+            }
+        }
+        if (depth >= BFS_MAX_DEPTH)
+            continue;
+        let children;
+        try {
+            children = fs.readdirSync(current, { withFileTypes: true });
+        }
+        catch {
+            continue;
+        }
+        for (const child of children) {
+            if (!child.isDirectory())
+                continue;
+            if (child.name === ".git" || child.name === "node_modules")
+                continue;
+            queue.push({ dir: path.join(current, child.name), depth: depth + 1 });
+        }
+    }
+    return undefined;
+}