akm-cli 0.1.3 → 0.2.0

package/dist/metadata.js

@@ -133,6 +133,30 @@ export function validateStashEntry(entry) {
         result.cwd = e.cwd.trim();
     if (typeof e.fileSize === "number" && Number.isFinite(e.fileSize) && e.fileSize >= 0)
         result.fileSize = e.fileSize;
+    if (Array.isArray(e.parameters)) {
+        const validated = e.parameters
+            .filter((p) => {
+            if (typeof p !== "object" || p === null)
+                return false;
+            const rec = p;
+            return typeof rec.name === "string" && rec.name.trim().length > 0;
+        })
+            .map((p) => {
+            const rec = p;
+            const param = { name: rec.name.trim() };
+            if (typeof rec.type === "string" && rec.type.trim())
+                param.type = rec.type.trim();
+            if (typeof rec.description === "string" && rec.description.trim())
+                param.description = rec.description.trim();
+            if (typeof rec.required === "boolean")
+                param.required = rec.required;
+            if (typeof rec.default === "string" && rec.default.trim().length > 0)
+                param.default = rec.default;
+            return param;
+        });
+        if (validated.length > 0)
+            result.parameters = validated;
+    }
     return result;
 }
 function normalizeNonEmptyStringList(value) {
@@ -148,6 +172,107 @@ function normalizeNonEmptyStringList(value) {
         .filter((item) => item.length > 0);
     return filtered.length > 0 ? filtered : undefined;
 }
+// ── Parameter Extraction ─────────────────────────────────────────────────────
+/**
+ * Extract structured parameters from a command template containing
+ * `$ARGUMENTS`, `$1`-`$9`, or `{{named}}` placeholders.
+ */
+export function extractCommandParameters(template) {
+    const params = [];
+    if (/\$ARGUMENTS\b/.test(template)) {
+        params.push({ name: "ARGUMENTS" });
+    }
+    for (const match of template.matchAll(/\$([1-9])(?!\d)/g)) {
+        const name = `$${match[1]}`;
+        if (!params.some((p) => p.name === name)) {
+            params.push({ name });
+        }
+    }
+    for (const match of template.matchAll(/\{\{([a-zA-Z_][a-zA-Z0-9_]*)\}\}/g)) {
+        const name = match[1];
+        if (!params.some((p) => p.name === name)) {
+            params.push({ name });
+        }
+    }
+    return params.length > 0 ? params : undefined;
+}
+/**
+ * Extract `@param` JSDoc tags from a script file's leading comment block.
+ *
+ * Supports both JSDoc-style (`/** ... * /`) and hash-style (`# @param ...`)
+ * comments. Optionally captures `{type}` annotations.
+ */
+export function extractScriptParameters(filePath, content) {
+    if (content === undefined) {
+        try {
+            content = fs.readFileSync(filePath, "utf8");
+        }
+        catch {
+            return undefined;
+        }
+    }
+    const lines = content.split(/\r?\n/).slice(0, 50);
+    const params = [];
+    // Match @param lines in any comment style:
+    // JSDoc:  * @param {string} name - description
+    // JSDoc:  * @param name - description
+    // Hash:   # @param name - description
+    const paramRegex = /^[\s/*#;-]*@param\s+(?:\{([^}]+)\}\s+)?(\w+)(?:\s+-\s+(.+))?/;
+    for (const line of lines) {
+        const match = line.match(paramRegex);
+        if (match) {
+            const param = { name: match[2] };
+            if (match[1])
+                param.type = match[1].trim();
+            if (match[3])
+                param.description = match[3].trim();
+            params.push(param);
+        }
+    }
+    return params.length > 0 ? params : undefined;
+}
+/**
+ * Extract parameters from frontmatter `params:` key.
+ *
+ * The frontmatter parser produces a nested object for `params:` like:
+ * ```
+ * { region: "AWS region to deploy to", instance_type: "EC2 instance type" }
+ * ```
+ */
+export function extractFrontmatterParameters(fmData) {
+    const paramsRaw = fmData.params;
+    if (typeof paramsRaw !== "object" || paramsRaw === null || Array.isArray(paramsRaw))
+        return undefined;
+    const paramsObj = paramsRaw;
+    const params = [];
+    for (const [key, value] of Object.entries(paramsObj)) {
+        const param = { name: key };
+        if (typeof value === "string" && value.trim()) {
+            param.description = value.trim();
+        }
+        params.push(param);
+    }
+    return params.length > 0 ? params : undefined;
+}
+/**
+ * Merge two parameter lists, deduplicating by name.
+ * Parameters from `additional` are appended only if their name is not already present.
+ */
+function mergeParameters(existing, additional) {
+    if (!additional || additional.length === 0)
+        return existing;
+    if (!existing || existing.length === 0)
+        return additional;
+    const names = new Set(existing.map((p) => p.name));
+    const merged = [...existing];
+    for (const param of additional) {
+        if (!names.has(param.name)) {
+            merged.push(param);
+            names.add(param.name);
+        }
+    }
+    return merged;
+}
 // ── Metadata Generation ─────────────────────────────────────────────────────
 export async function generateMetadata(dirPath, assetType, files, typeRoot = dirPath) {
     const entries = [];
@@ -179,12 +304,31 @@ export async function generateMetadata(dirPath, assetType, files, typeRoot = dir
         }
         // Priority 2: Frontmatter (for .md files -- overrides package.json description)
         if (ext === ".md") {
-            const fm = extractFrontmatterDescription(file);
+            const content = fs.readFileSync(file, "utf8");
+            const parsed = parseFrontmatter(content);
+            const fm = toStringOrUndefined(parsed.data.description);
             if (fm) {
                 entry.description = fm;
                 entry.source = "frontmatter";
                 entry.confidence = 0.9;
             }
+            // Extract parameters from frontmatter params: key
+            const fmParams = extractFrontmatterParameters(parsed.data);
+            if (fmParams)
+                entry.parameters = fmParams;
+            // Extract parameters from template placeholders ($1, $ARGUMENTS, {{named}})
+            if (entry.type === "command") {
+                const cmdParams = extractCommandParameters(parsed.content);
+                if (cmdParams) {
+                    entry.parameters = mergeParameters(entry.parameters, cmdParams);
+                }
+            }
+        }
+        // Extract @param from script files
+        if (ext !== ".md") {
+            const scriptParams = extractScriptParameters(file);
+            if (scriptParams)
+                entry.parameters = scriptParams;
         }
         // Priority 3: Type-specific metadata extraction (e.g. TOC for knowledge, comments for scripts)
         const fileCtx = buildFileContext(typeRoot, file);
@@ -262,12 +406,31 @@ export async function generateMetadataFlat(stashRoot, files) {
         }
         // Frontmatter
         if (ext === ".md") {
-            const fm = extractFrontmatterDescription(file);
+            const content = ctx.content();
+            const parsed = parseFrontmatter(content);
+            const fm = toStringOrUndefined(parsed.data.description);
             if (fm) {
                 entry.description = fm;
                 entry.source = "frontmatter";
                 entry.confidence = 0.9;
             }
+            // Extract parameters from frontmatter params: key
+            const fmParams = extractFrontmatterParameters(parsed.data);
+            if (fmParams)
+                entry.parameters = fmParams;
+            // Extract parameters from template placeholders ($1, $ARGUMENTS, {{named}})
+            if (entry.type === "command") {
+                const cmdParams = extractCommandParameters(parsed.content);
+                if (cmdParams) {
+                    entry.parameters = mergeParameters(entry.parameters, cmdParams);
+                }
+            }
+        }
+        // Extract @param from script files
+        if (ext !== ".md") {
+            const scriptParams = extractScriptParameters(file, ctx.content());
+            if (scriptParams)
+                entry.parameters = scriptParams;
         }
         // Renderer metadata extraction
         const renderer = await getRenderer(match.renderer);

package/dist/providers/skills-sh.js

@@ -68,14 +68,17 @@ class SkillsShProvider {
         const registryName = this.config.name ?? "skills.sh";
         const baseUrl = this.config.url.replace(/\/+$/, "");
         return entries.map((entry) => {
-            const owner = entry.source.split("/")[0] ?? "";
+            const segments = entry.source.split("/");
+            const owner = segments[0] ?? "";
+            const repo = segments[1] ?? "";
+            const ownerRepo = owner && repo ? `${owner}/${repo}` : entry.source;
             const score = Math.round((entry.installs / maxInstalls) * 1000) / 1000;
             return {
                 source: "github",
                 id: `skills-sh:${entry.id}`,
                 title: entry.name,
-                ref: entry.source,
-                installRef: `github:${entry.source}`,
+                ref: ownerRepo,
+                installRef: `github:${ownerRepo}`,
                 homepage: `${baseUrl}/${entry.id}`,
                 score,
                 metadata: {
@@ -91,15 +94,21 @@ class SkillsShProvider {
             return undefined;
         const registryName = this.config.name ?? "skills.sh";
         const maxInstalls = Math.max(...entries.map((e) => e.installs), 1);
-        const hits = entries.map((entry) => ({
-            type: "registry-asset",
-            assetType: "skill",
-            assetName: entry.name,
-            kit: { id: `skills-sh:${entry.id}`, name: entry.name },
-            registryName,
-            action: `akm add ${entry.source}`,
-            score: Math.round((entry.installs / maxInstalls) * 1000) / 1000,
-        }));
+        const hits = entries.map((entry) => {
+            const segments = entry.source.split("/");
+            const owner = segments[0] ?? "";
+            const repo = segments[1] ?? "";
+            const ownerRepo = owner && repo ? `${owner}/${repo}` : entry.source;
+            return {
+                type: "registry-asset",
+                assetType: "skill",
+                assetName: entry.name,
+                kit: { id: `skills-sh:${entry.id}`, name: entry.name },
+                registryName,
+                action: `akm add github:${ownerRepo}`,
+                score: Math.round((entry.installs / maxInstalls) * 1000) / 1000,
+            };
+        });
         return hits.length > 0 ? hits : undefined;
     }
     // ── Per-query cache ─────────────────────────────────────────────────────

package/dist/providers/static-index.js

@@ -251,6 +251,7 @@ function parseAssetEntry(raw) {
         name,
         description: asString(obj.description),
         tags: asStringArray(obj.tags),
+        estimatedTokens: typeof obj.estimatedTokens === "number" ? obj.estimatedTokens : undefined,
     };
 }
 // ── Asset-level scoring ─────────────────────────────────────────────────────
@@ -272,6 +273,7 @@ function scoreAssets(kits, query, limit) {
                         assetType: asset.type,
                         assetName: asset.name,
                         description: asset.description,
+                        estimatedTokens: asset.estimatedTokens,
                         kit: { id: kit.id, name: kit.name },
                         registryName,
                         action: `akm add ${installRef}`,
@@ -335,7 +337,7 @@ function buildInstallRef(source, ref) {
         case "git":
             return `git+${ref}`;
         case "local":
-            return ref;
+            return `file:${ref}`;
         default:
             return `github:${ref}`;
     }

package/dist/registry-build-index.js

@@ -184,6 +184,7 @@ async function inspectArchive(url, headers) {
             name: entry.name,
             ...(entry.description ? { description: entry.description } : {}),
             ...(entry.tags && entry.tags.length > 0 ? { tags: entry.tags } : {}),
+            ...(typeof entry.fileSize === "number" ? { estimatedTokens: Math.round(entry.fileSize / 4) } : {}),
         }));
         return {
             description: asString(packageMetadata.description),
@@ -241,10 +242,20 @@ async function enumerateAssets(stashRoot) {
                 continue;
             stash = generated;
         }
-        entries.push(...stash.entries);
+        entries.push(...stash.entries.map((entry) => attachFileSize(dirPath, entry)));
     }
     return entries.sort((a, b) => `${a.type}:${a.name}`.localeCompare(`${b.type}:${b.name}`));
 }
+function attachFileSize(dirPath, entry) {
+    if (typeof entry.fileSize === "number" || !entry.filename)
+        return entry;
+    try {
+        return { ...entry, fileSize: fs.statSync(path.join(dirPath, entry.filename)).size };
+    }
+    catch {
+        return entry;
+    }
+}
 function applyIncludeConfigForInspection(stashRoot, tempDir, searchRoot) {
     const includeConfig = findNearestIncludeConfig(stashRoot, searchRoot);
     if (!includeConfig)

package/dist/registry-resolve.js

@@ -87,16 +87,19 @@ function detectRegistrySearchId(ref) {
     if (!/^[a-z][a-z0-9-]*$/.test(prefix))
         return undefined;
     const rest = ref.slice(colonIdx + 1);
-    return [
+    // Try to extract a plausible owner/repo from the rest (e.g. "org/repo/skill" → "org/repo")
+    const segments = rest.split("/").filter(Boolean);
+    const suggestedRef = segments.length >= 2 ? `github:${segments[0]}/${segments[1]}` : undefined;
+    const lines = [
         `"${ref}" looks like a registry search result ID, not an installable ref.`,
         `The "${prefix}:" prefix is a registry identifier and cannot be passed to \`akm add\`.`,
         "",
-        "Use the installRef or ref field from the search result instead. For example:",
-        `  akm registry search "${rest}" --format json`,
-        "Then install using the installRef value from the result:",
-        "  akm add github:owner/repo",
-        "  akm add npm:package-name",
-    ].join("\n");
+    ];
+    if (suggestedRef) {
+        lines.push(`Try installing the source repository directly:`, `  akm add ${suggestedRef}`, "");
+    }
+    lines.push("Or search for the installable ref:", `  akm search "${segments.length > 2 ? segments[segments.length - 1] : rest}" --source registry`, "Then install using the installRef value from the result:", "  akm add github:owner/repo", "  akm add npm:package-name");
+    return lines.join("\n");
 }
 export async function resolveRegistryArtifact(parsed) {
     if (parsed.source === "npm") {

package/dist/search-fields.js

@@ -0,0 +1,69 @@
+/**
+ * Per-field search text extraction for FTS5 indexing.
+ *
+ * Extracted from indexer.ts to break the circular dependency:
+ *   db.ts -> indexer.ts -> db.ts
+ *
+ * This module imports only from metadata.ts (for the StashEntry type),
+ * so it can be safely imported by both db.ts and indexer.ts.
+ */
+/**
+ * Return per-field search text for multi-column FTS5 indexing.
+ *
+ * Fields:
+ *  - name: entry name with hyphens/underscores replaced by spaces
+ *  - description: entry description
+ *  - tags: tags + aliases joined
+ *  - hints: searchHints + examples + usage + intent fields
+ *  - content: TOC headings (lowest-weight catch-all)
+ */
+export function buildSearchFields(entry) {
+    const name = entry.name.replace(/[-_]/g, " ").toLowerCase();
+    const description = (entry.description ?? "").toLowerCase();
+    const tagParts = [];
+    if (entry.tags)
+        tagParts.push(entry.tags.join(" "));
+    if (entry.aliases)
+        tagParts.push(entry.aliases.join(" "));
+    const tags = tagParts.join(" ").toLowerCase();
+    const hintParts = [];
+    if (entry.searchHints)
+        hintParts.push(entry.searchHints.join(" "));
+    if (entry.examples)
+        hintParts.push(entry.examples.join(" "));
+    if (entry.usage)
+        hintParts.push(entry.usage.join(" "));
+    if (entry.intent) {
+        if (entry.intent.when)
+            hintParts.push(entry.intent.when);
+        if (entry.intent.input)
+            hintParts.push(entry.intent.input);
+        if (entry.intent.output)
+            hintParts.push(entry.intent.output);
+    }
+    const hints = hintParts.join(" ").toLowerCase();
+    const contentParts = [];
+    if (entry.toc) {
+        contentParts.push(entry.toc.map((h) => h.text).join(" "));
+    }
+    if (entry.parameters) {
+        for (const param of entry.parameters) {
+            contentParts.push(param.name);
+            if (param.description)
+                contentParts.push(param.description);
+        }
+    }
+    const content = contentParts.join(" ").toLowerCase();
+    return { name, description, tags, hints, content };
+}
+/**
+ * Build a single concatenated search text string for an entry.
+ * Used for the `search_text` column in the entries table (backward compat)
+ * and for generating embedding text.
+ */
+export function buildSearchText(entry) {
+    const fields = buildSearchFields(entry);
+    return [fields.name, fields.description, fields.tags, fields.hints, fields.content]
+        .filter((s) => s.length > 0)
+        .join(" ");
+}

package/dist/search-source.js

@@ -2,6 +2,7 @@ import fs from "node:fs";
 import path from "node:path";
 import { resolveStashDir } from "./common";
 import { loadConfig } from "./config";
+import { ensureGitMirror, getCachePaths, parseGitRepoUrl } from "./stash-providers/git";
 import { warn } from "./warn";
 // ── Resolution ──────────────────────────────────────────────────────────────
 /**
@@ -36,6 +37,23 @@ export function resolveStashSources(overrideStashDir, existingConfig) {
             addSource(entry.path, entry.name);
         }
     }
+    // Git stash entries: resolve cache directory so the indexer can walk it.
+    // "context-hub", "github", and "git" provider types are handled.
+    for (const entry of config.stashes ?? []) {
+        if (GIT_STASH_TYPES.has(entry.type) && entry.url && entry.enabled !== false) {
+            try {
+                const repo = parseGitRepoUrl(entry.url);
+                const cachePaths = getCachePaths(repo.canonicalUrl);
+                // The content/ subdirectory inside the extracted repo is the actual
+                // stash root containing DOC.md / SKILL.md files that the walker indexes.
+                const contentDir = path.join(cachePaths.repoDir, "content");
+                addSource(contentDir, entry.name);
+            }
+            catch (err) {
+                warn(`Warning: failed to resolve git stash cache for "${entry.url}": ${err instanceof Error ? err.message : String(err)}`);
+            }
+        }
+    }
     // Installed kits (registry and local)
     for (const entry of config.installed ?? []) {
         addSource(entry.stashRoot, entry.id);
@@ -132,3 +150,27 @@ function isValidDirectory(dir) {
         return false;
     }
 }
+// ── Git stash cache integration ──────────────────────────────────────────────
+const GIT_STASH_TYPES = new Set(["context-hub", "github", "git"]);
+/**
+ * Ensure all git stash mirrors are refreshed so their cache directories
+ * exist on disk. Must be called (async) before `resolveStashSources()` so
+ * the content directories pass the `isValidDirectory()` check.
+ */
+export async function ensureGitCaches(config) {
+    const cfg = config ?? loadConfig();
+    for (const entry of cfg.stashes ?? []) {
+        if (!GIT_STASH_TYPES.has(entry.type) || !entry.url || entry.enabled === false)
+            continue;
+        try {
+            const repo = parseGitRepoUrl(entry.url);
+            const cachePaths = getCachePaths(repo.canonicalUrl);
+            await ensureGitMirror(repo, cachePaths, { requireRepoDir: true });
+        }
+        catch (err) {
+            warn(`Warning: failed to refresh git mirror for "${entry.url}": ${err instanceof Error ? err.message : String(err)}`);
+        }
+    }
+}
+/** @deprecated Use ensureGitCaches instead. */
+export const ensureContextHubCaches = ensureGitCaches;

package/dist/stash-clone.js

@@ -98,7 +98,9 @@ export async function akmClone(options) {
     }
     else {
         const resolvedSource = path.resolve(sourcePath);
-        const resolvedDest = path.resolve(path.join(destRoot, typeDir, destName));
+        const sourceExt = path.extname(sourcePath);
+        const effectiveDestName = !path.extname(destName) && sourceExt ? destName + sourceExt : destName;
+        const resolvedDest = path.resolve(path.join(destRoot, typeDir, effectiveDestName));
         if (resolvedSource === resolvedDest) {
             throw new Error(`Source and destination are the same path. Use --name to provide a new name for the clone.`);
         }

package/dist/stash-provider-factory.js

@@ -26,8 +26,6 @@ export function resolveStashProviders(config) {
     for (const entry of config.stashes ?? []) {
         if (entry.enabled === false)
             continue;
-        if (entry.type === "filesystem")
-            continue;
         const factory = registry.resolve(entry.type);
         if (factory) {
             providers.push(factory(entry));

package/dist/stash-providers/filesystem.js

@@ -8,21 +8,20 @@ class FilesystemStashProvider {
     type = "filesystem";
     name;
     stashDir;
-    config;
     constructor(entry) {
-        this.config = loadConfig();
         this.stashDir = entry.path ?? resolveStashDir();
         this.name = entry.name ?? this.stashDir;
     }
     async search(options) {
-        const sources = resolveStashSources(this.stashDir, this.config);
+        const config = loadConfig();
+        const sources = resolveStashSources(this.stashDir, config);
         const result = await searchLocal({
             query: options.query.toLowerCase(),
             searchType: options.type ?? "any",
             limit: options.limit,
             stashDir: this.stashDir,
             sources,
-            config: this.config,
+            config,
         });
         return {
             hits: result.hits,
@@ -35,7 +34,7 @@ class FilesystemStashProvider {
         return showLocal({ ref, view });
     }
     canShow(ref) {
-        return !ref.trim().startsWith("viking://");
+        return !ref.includes("://");
     }
 }
 // ── Self-register ───────────────────────────────────────────────────────────

package/dist/stash-providers/git.js

@@ -0,0 +1,140 @@
+import { createHash } from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+import { fetchWithRetry } from "../common";
+import { ConfigError } from "../errors";
+import { getRegistryIndexCacheDir } from "../paths";
+import { extractTarGzSecure } from "../registry-install";
+import { registerStashProvider } from "../stash-provider-factory";
+import { 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;
+class GitStashProvider {
+    type = "git";
+    name;
+    constructor(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;
+    }
+}
+// ── Self-register ───────────────────────────────────────────────────────────
+registerStashProvider("git", (config) => new GitStashProvider(config));
+registerStashProvider("context-hub", (config) => new GitStashProvider(config));
+registerStashProvider("github", (config) => new GitStashProvider(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}`);
+    return {
+        rootDir,
+        archivePath: path.join(rootDir, "repo.tar.gz"),
+        repoDir: path.join(rootDir, "repo"),
+        indexPath: path.join(rootDir, "index.json"),
+    };
+}
+async function ensureGitMirror(repo, cachePaths, options) {
+    const requireRepoDir = options?.requireRepoDir === true;
+    // Check if cache is fresh
+    let mtime = 0;
+    try {
+        mtime = fs.statSync(cachePaths.indexPath).mtimeMs;
+    }
+    catch {
+        /* no cached index */
+    }
+    if (mtime && !isExpired(mtime, CACHE_TTL_MS) && (!requireRepoDir || hasExtractedRepo(cachePaths.repoDir))) {
+        return;
+    }
+    try {
+        fs.mkdirSync(cachePaths.rootDir, { recursive: true });
+        await downloadArchive(buildTarballUrl(repo), cachePaths.archivePath);
+        extractTarGzSecure(cachePaths.archivePath, cachePaths.repoDir);
+        // Touch index file to track freshness
+        fs.writeFileSync(cachePaths.indexPath, "[]", { encoding: "utf8", mode: 0o600 });
+    }
+    catch (err) {
+        if (mtime && !isExpired(mtime, CACHE_STALE_MS) && (!requireRepoDir || hasExtractedRepo(cachePaths.repoDir))) {
+            return;
+        }
+        throw err;
+    }
+}
+function hasExtractedRepo(repoDir) {
+    try {
+        return fs.statSync(repoDir).isDirectory() && fs.statSync(path.join(repoDir, "content")).isDirectory();
+    }
+    catch {
+        return false;
+    }
+}
+async function downloadArchive(url, destination) {
+    const response = await fetchWithRetry(url, undefined, { timeout: 120_000, retries: 1 });
+    if (!response.ok) {
+        throw new Error(`Failed to download archive (${response.status}) from ${url}`);
+    }
+    const BunRuntime = globalThis.Bun;
+    if (BunRuntime?.write) {
+        await BunRuntime.write(destination, response);
+        return;
+    }
+    const arrayBuffer = await response.arrayBuffer();
+    fs.writeFileSync(destination, Buffer.from(arrayBuffer));
+}
+function buildTarballUrl(repo) {
+    return `https://github.com/${repo.owner}/${repo.repo}/archive/refs/heads/${repo.ref}.tar.gz`;
+}
+function parseGitRepoUrl(rawUrl) {
+    if (!rawUrl) {
+        throw new ConfigError("Git provider requires a GitHub repository URL");
+    }
+    let parsed;
+    try {
+        parsed = new URL(rawUrl);
+    }
+    catch {
+        throw new ConfigError(`Git provider URL is not valid: "${rawUrl}"`);
+    }
+    if (parsed.protocol !== "https:") {
+        throw new ConfigError(`Git provider URL must use https://, got "${parsed.protocol}"`);
+    }
+    if (parsed.hostname !== "github.com") {
+        throw new ConfigError(`Git provider only supports github.com URLs, got "${parsed.hostname}"`);
+    }
+    const segments = parsed.pathname.split("/").filter(Boolean);
+    if (segments.length < 2) {
+        throw new ConfigError(`Git provider URL must point to a GitHub repository, got "${rawUrl}"`);
+    }
+    const owner = sanitizeString(segments[0]);
+    const repo = sanitizeString(segments[1].replace(/\.git$/i, ""));
+    let ref = "main";
+    if (segments[2] === "tree" && segments.length >= 4) {
+        ref = sanitizeString(segments.slice(3).join("/"), 255) || "main";
+    }
+    if (!owner || !repo || !/^[A-Za-z0-9_.-]+$/.test(owner) || !/^[A-Za-z0-9_.-]+$/.test(repo)) {
+        throw new ConfigError(`Unsupported repository URL: "${rawUrl}"`);
+    }
+    if (!ref || ref.includes("..") || !/^[A-Za-z0-9._/-]+$/.test(ref)) {
+        throw new ConfigError(`Unsupported branch/ref in URL: "${rawUrl}"`);
+    }
+    return {
+        owner,
+        repo,
+        ref,
+        canonicalUrl: `https://github.com/${owner}/${repo}/tree/${ref}`,
+    };
+}
+// ── Exports ─────────────────────────────────────────────────────────────────
+export { GitStashProvider, ensureGitMirror, getCachePaths, parseGitRepoUrl };