akm-cli 0.9.0-beta.45 → 0.9.0-beta.46

package/dist/sources/providers/npm.js

@@ -36,18 +36,14 @@ class NpmSourceProvider {
         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() {
+    async sync(options) {
         const ref = npmRefFromConfig(this.#config);
-        await syncNpmRef(ref);
+        await syncNpmRef(ref, { force: options?.force });
     }
 }
 registerSourceProvider("npm", (config) => new NpmSourceProvider(config));

package/dist/sources/providers/sync-from-ref.js

@@ -1,6 +1,13 @@
 // This Source Code Form is subject to the terms of the Mozilla Public
 // License, v. 2.0. If a copy of the MPL was not distributed with this
 // file, You can obtain one at https://mozilla.org/MPL/2.0/.
+/**
+ * Unified install-ref dispatcher.
+ *
+ * Replaces the historical `installRegistryRef()` entry point. Given an
+ * unparsed install ref, this resolves the right syncable provider and
+ * invokes its `sync()` method.
+ */
 import { UsageError } from "../../core/errors.js";
 import { parseRegistryRef } from "../../registry/resolve.js";
 import { detectStashRoot } from "./provider-utils.js";
@@ -18,7 +25,8 @@ export async function syncFromRef(ref, options) {
         return syncRegistryGitRef(ref, options);
     }
     // Exhaustiveness — `parseRegistryRef` only emits the four sources above.
-    throw new UsageError(`No syncable provider for ref: ${ref} (source=${parsed.source})`);
+    const _exhaustive = parsed;
+    throw new UsageError(`No syncable provider for ref: ${ref}`);
 }
 function syncLocalRef(parsed, options) {
     const stashRoot = detectStashRoot(parsed.sourcePath);

package/dist/sources/providers/website.js

@@ -12,12 +12,11 @@ registerSourceProvider("website", (config) => {
     return {
         kind: "website",
         name,
-        async init(_ctx) { },
         path() {
             return getWebsiteCachePaths(url).stashDir;
         },
-        async sync() {
-            await ensureWebsiteMirror(config, { requireStashDir: true });
+        async sync(options) {
+            await ensureWebsiteMirror(config, { requireStashDir: true, force: options?.force });
         },
     };
 });

package/dist/sources/website-ingest.js

@@ -4,11 +4,12 @@
 import { createHash } from "node:crypto";
 import fs from "node:fs";
 import path from "node:path";
-import { fetchWithRetry, ResponseTooLargeError, readBodyWithByteCap } from "../core/common.js";
+import { fetchWithRetry, ResponseTooLargeError, readBodyWithByteCap, resolveStashDir } from "../core/common.js";
 import { ConfigError, UsageError } from "../core/errors.js";
 import { getRegistryIndexCacheDir } from "../core/paths.js";
 import { warn } from "../core/warn.js";
 import { isExpired, sanitizeString } from "./providers/provider-utils.js";
+import { loadWikiSnapshotFetchers } from "./wiki-fetchers/registry.js";
 /** Refresh website snapshots every 12 hours to balance freshness with scraping load. */
 const CACHE_REFRESH_INTERVAL_MS = 12 * 60 * 60 * 1000;
 /** Allow up to 7 days of stale snapshots when refresh fails so search remains available during outages. */
@@ -30,6 +31,16 @@ const WEBSITE_PAGE_BYTE_CAP = 5 * 1024 * 1024;
  * whole crawl and return what we have when time runs out.
  */
 const WEBSITE_CRAWL_WALL_CLOCK_MS = 10 * 60 * 1000;
+function resolveFetcherStashDir(explicitStashDir) {
+    if (explicitStashDir)
+        return explicitStashDir;
+    try {
+        return resolveStashDir({ readOnly: true });
+    }
+    catch {
+        return null;
+    }
+}
 export function getWebsiteCachePaths(siteUrl) {
     const key = createHash("sha256").update(normalizeSiteUrl(siteUrl)).digest("hex").slice(0, 16);
     const rootDir = path.join(getRegistryIndexCacheDir(), `website-${key}`);
@@ -114,20 +125,51 @@ async function scrapeWebsiteToStash(startUrl, stashDir, options) {
         fs.writeFileSync(filePath, buildMarkdownSnapshot(page, slug), "utf8");
     }
 }
-export async function fetchWebsiteMarkdownSnapshot(rawUrl) {
+export async function fetchWebsiteMarkdownSnapshot(rawUrl, options) {
     const normalizedUrl = validateWebsiteInputUrl(rawUrl);
+    const parsedUrl = new URL(normalizedUrl);
+    const stashDir = resolveFetcherStashDir(options?.stashDir);
+    const context = {
+        stashDir: stashDir ?? "",
+        timeoutMs: options?.timeoutMs ?? 15_000,
+        signal: options?.signal,
+    };
+    for (const fetcher of await loadWikiSnapshotFetchers(stashDir)) {
+        try {
+            if (!fetcher.matches(parsedUrl, context))
+                continue;
+            const snapshot = await fetcher.fetch(parsedUrl, context);
+            if (!snapshot)
+                continue;
+            return websiteMarkdownSnapshotFromResult(snapshot);
+        }
+        catch (error) {
+            warn("[akm] wiki-fetcher %s threw on %s: %s", fetcher.name, normalizedUrl, error instanceof Error ? error.message : String(error));
+        }
+    }
     const fetched = await fetchWebsitePage(normalizedUrl);
     if (!fetched) {
         throw new UsageError(`No content could be fetched from ${normalizedUrl}`);
     }
-    const preferredName = deriveImportPath(fetched.page.url);
-    const slug = preferredName.split("/").pop() ?? preferredName;
-    return {
+    return websiteMarkdownSnapshotFromResult({
         url: fetched.page.url,
         title: fetched.page.title,
         markdown: fetched.page.markdown,
+    });
+}
+function websiteMarkdownSnapshotFromResult(snapshot) {
+    const preferredName = snapshot.preferredName ?? deriveImportPath(snapshot.url);
+    const slug = preferredName.split("/").pop() ?? preferredName;
+    return {
+        url: snapshot.url,
+        title: snapshot.title,
+        markdown: snapshot.markdown,
         preferredName,
-        content: buildMarkdownSnapshot(fetched.page, slug || "website"),
+        content: buildMarkdownSnapshot({
+            url: snapshot.url,
+            title: snapshot.title,
+            markdown: snapshot.markdown,
+        }, slug || "website", snapshot.tags),
     };
 }
 async function crawlWebsite(startUrl, options) {
@@ -216,11 +258,12 @@ async function fetchWebsitePage(pageUrl) {
         links: [],
     };
 }
-function buildMarkdownSnapshot(page, slug) {
+function buildMarkdownSnapshot(page, slug, tags) {
     const title = sanitizeString(page.title, 200) || slug;
     const description = sanitizeString(`Snapshot of ${page.url}`, 500);
     const host = sanitizeString(new URL(page.url).hostname, 120);
     const content = page.markdown.trim() || `Source: ${page.url}`;
+    const normalizedTags = Array.from(new Set(["website", host, ...(tags ?? [])]));
     return [
         "---",
         `name: ${JSON.stringify(slug)}`,
@@ -228,8 +271,7 @@ function buildMarkdownSnapshot(page, slug) {
         `sourceUrl: ${JSON.stringify(page.url)}`,
         `title: ${JSON.stringify(title)}`,
         "tags:",
-        `  - ${JSON.stringify("website")}`,
-        `  - ${JSON.stringify(host)}`,
+        ...normalizedTags.map((tag) => `  - ${JSON.stringify(tag)}`),
         "---",
         "",
         `# ${title}`,

package/dist/sources/wiki-fetchers/registry.js

@@ -0,0 +1,53 @@
+// This Source Code Form is subject to the terms of the Mozilla Public
+// License, v. 2.0. If a copy of the MPL was not distributed with this
+// file, You can obtain one at https://mozilla.org/MPL/2.0/.
+import fs from "node:fs";
+import path from "node:path";
+import { pathToFileURL } from "node:url";
+import { warn } from "../../core/warn.js";
+import youtubeFetcher from "./youtube.js";
+const FETCHER_DIR = path.join("scripts", "wiki-fetchers");
+const FETCHER_FILE_PATTERN = /\.(?:ts|js|mjs)$/i;
+const BUILTIN_FETCHERS = [youtubeFetcher];
+function isWikiSnapshotFetcher(value) {
+    if (!value || typeof value !== "object")
+        return false;
+    const candidate = value;
+    return (typeof candidate.name === "string" &&
+        typeof candidate.matches === "function" &&
+        typeof candidate.fetch === "function");
+}
+export async function loadWikiSnapshotFetchers(stashDir) {
+    const fetchers = [];
+    if (stashDir) {
+        const fetcherDir = path.join(stashDir, FETCHER_DIR);
+        try {
+            const entries = fs.readdirSync(fetcherDir).sort();
+            for (const entry of entries) {
+                if (!FETCHER_FILE_PATTERN.test(entry))
+                    continue;
+                try {
+                    const fileUrl = pathToFileURL(path.join(fetcherDir, entry)).toString();
+                    const mod = await import(fileUrl);
+                    if (isWikiSnapshotFetcher(mod.default)) {
+                        fetchers.push(mod.default);
+                    }
+                    else {
+                        warn("[akm] wiki-fetcher %s skipped: missing { name, matches, fetch }", entry);
+                    }
+                }
+                catch (error) {
+                    warn("[akm] wiki-fetcher %s failed to load: %s", entry, error instanceof Error ? error.message : String(error));
+                }
+            }
+        }
+        catch (error) {
+            const code = typeof error === "object" && error && "code" in error ? error.code : undefined;
+            if (code !== "ENOENT") {
+                warn("[akm] wiki-fetcher directory %s could not be read: %s", fetcherDir, error instanceof Error ? error.message : String(error));
+            }
+            // Missing directory means no custom fetchers.
+        }
+    }
+    return [...fetchers, ...BUILTIN_FETCHERS];
+}

package/dist/sources/wiki-fetchers/youtube.js

@@ -0,0 +1,181 @@
+// This Source Code Form is subject to the terms of the Mozilla Public
+// License, v. 2.0. If a copy of the MPL was not distributed with this
+// file, You can obtain one at https://mozilla.org/MPL/2.0/.
+import { fetchWithRetry } from "../../core/common.js";
+const YOUTUBE_HOSTS = new Set(["www.youtube.com", "youtube.com", "m.youtube.com", "youtu.be"]);
+const WATCH_HOST = "https://www.youtube.com/watch?v=";
+function extractVideoId(url) {
+    if (!YOUTUBE_HOSTS.has(url.hostname))
+        return null;
+    if (url.hostname === "youtu.be") {
+        const id = url.pathname.replace(/^\/+/, "").split("/")[0]?.trim();
+        return id || null;
+    }
+    if (url.pathname === "/watch") {
+        const id = url.searchParams.get("v")?.trim();
+        return id || null;
+    }
+    if (url.pathname.startsWith("/shorts/")) {
+        const id = url.pathname.slice("/shorts/".length).split("/")[0]?.trim();
+        return id || null;
+    }
+    return null;
+}
+function canonicalWatchUrl(videoId) {
+    return `${WATCH_HOST}${encodeURIComponent(videoId)}`;
+}
+function decodeEntities(value) {
+    const safeFromCodePoint = (codePoint, fallback) => {
+        if (!Number.isFinite(codePoint) || codePoint < 0 || codePoint > 0x10ffff)
+            return fallback;
+        try {
+            return String.fromCodePoint(codePoint);
+        }
+        catch {
+            return fallback;
+        }
+    };
+    return value
+        .replace(/&#x([0-9a-f]+);/gi, (m, hex) => safeFromCodePoint(Number.parseInt(hex, 16), m))
+        .replace(/&#([0-9]+);/g, (m, dec) => safeFromCodePoint(Number.parseInt(dec, 10), m))
+        .replace(/&quot;/g, '"')
+        .replace(/&#39;|&apos;/g, "'")
+        .replace(/&lt;/g, "<")
+        .replace(/&gt;/g, ">")
+        .replace(/&amp;/g, "&");
+}
+function stripTags(value) {
+    return value.replace(/<[^>]+>/g, "");
+}
+function extractJsonObjectAfter(marker, source) {
+    const markerIndex = source.indexOf(marker);
+    if (markerIndex === -1)
+        return null;
+    const start = source.indexOf("{", markerIndex + marker.length);
+    if (start === -1)
+        return null;
+    let depth = 0;
+    let inString = false;
+    let escaped = false;
+    for (let i = start; i < source.length; i += 1) {
+        const char = source[i];
+        if (inString) {
+            if (escaped) {
+                escaped = false;
+            }
+            else if (char === "\\") {
+                escaped = true;
+            }
+            else if (char === '"') {
+                inString = false;
+            }
+            continue;
+        }
+        if (char === '"') {
+            inString = true;
+            continue;
+        }
+        if (char === "{")
+            depth += 1;
+        if (char === "}") {
+            depth -= 1;
+            if (depth === 0)
+                return source.slice(start, i + 1);
+        }
+    }
+    return null;
+}
+function parsePlayerResponse(html) {
+    const jsonText = extractJsonObjectAfter("ytInitialPlayerResponse =", html);
+    if (!jsonText)
+        return null;
+    try {
+        return JSON.parse(jsonText);
+    }
+    catch {
+        return null;
+    }
+}
+function chooseCaptionTrack(tracks) {
+    const normalized = tracks
+        .map((track) => ({
+        baseUrl: typeof track.baseUrl === "string" ? track.baseUrl : "",
+        languageCode: typeof track.languageCode === "string" ? track.languageCode : "",
+        kind: typeof track.kind === "string" ? track.kind : "",
+    }))
+        .filter((track) => track.baseUrl);
+    if (normalized.length === 0)
+        return null;
+    const preferred = normalized.find((track) => track.languageCode === "en" && track.kind !== "asr") ??
+        normalized.find((track) => track.languageCode.startsWith("en") && track.kind !== "asr") ??
+        normalized.find((track) => track.languageCode.startsWith("en")) ??
+        normalized[0];
+    return preferred.baseUrl;
+}
+async function fetchText(url, timeoutMs, signal) {
+    const response = await fetchWithRetry(url, {
+        headers: {
+            Accept: "text/html,application/json,application/xml,text/xml,text/plain;q=0.9,*/*;q=0.1",
+            "User-Agent": "akm-cli youtube fetcher",
+        },
+        signal,
+    }, { timeout: timeoutMs, retries: 1 });
+    if (!response.ok)
+        return null;
+    return response.text();
+}
+function parseTranscript(xml) {
+    const texts = [...xml.matchAll(/<text\b[^>]*>([\s\S]*?)<\/text>/g)]
+        .map((match) => decodeEntities(stripTags(match[1] ?? "")).trim())
+        .filter(Boolean);
+    if (texts.length === 0)
+        return null;
+    return texts.join("\n");
+}
+const youtubeFetcher = {
+    name: "youtube-transcript",
+    matches(url) {
+        return extractVideoId(url) !== null;
+    },
+    async fetch(url, context) {
+        const videoId = extractVideoId(url);
+        if (!videoId)
+            return null;
+        const watchUrl = canonicalWatchUrl(videoId);
+        const watchHtml = await fetchText(watchUrl, context.timeoutMs, context.signal);
+        if (!watchHtml)
+            return null;
+        const playerResponse = parsePlayerResponse(watchHtml);
+        if (!playerResponse)
+            return null;
+        const title = typeof playerResponse.videoDetails?.title === "string" ? playerResponse.videoDetails.title.trim() : "";
+        const description = typeof playerResponse.videoDetails?.shortDescription === "string"
+            ? playerResponse.videoDetails.shortDescription.trim()
+            : "";
+        const sections = [];
+        let hasTranscript = false;
+        if (description) {
+            sections.push("## Description", "", description);
+        }
+        const tracks = playerResponse.captions?.playerCaptionsTracklistRenderer?.captionTracks ?? [];
+        const captionUrl = chooseCaptionTrack(tracks);
+        if (captionUrl) {
+            const transcriptXml = await fetchText(captionUrl, context.timeoutMs, context.signal);
+            const transcript = transcriptXml ? parseTranscript(transcriptXml) : null;
+            if (transcript) {
+                hasTranscript = true;
+                sections.push("## Transcript", "", transcript);
+            }
+        }
+        if (sections.length === 0)
+            return null;
+        return {
+            url: watchUrl,
+            title: title || `YouTube ${videoId}`,
+            markdown: sections.join("\n"),
+            preferredName: `youtube/${videoId}`,
+            tags: hasTranscript ? ["youtube", "video", "transcript"] : ["youtube", "video"],
+        };
+    },
+};
+export default youtubeFetcher;

package/dist/storage/database.js

@@ -35,18 +35,39 @@ const isBun = !!process.versions?.bun;
 // Bun built-in, unresolvable on Node) nor `better-sqlite3` (an optional native
 // dep, possibly absent under Bun) is statically imported.
 const nodeRequire = createRequire(import.meta.url);
+// bun:sqlite — Bun built-in, no native build. Cannot run on Node.
+const bunSqliteProvider = {
+    name: "bun:sqlite",
+    supported: () => isBun,
+    open: openBunDatabase,
+};
+// better-sqlite3 — native Node driver. Cannot run on Bun (oven-sh/bun#4290).
+const nodeSqliteProvider = {
+    name: "better-sqlite3",
+    supported: () => !isBun,
+    open: openNodeDatabase,
+};
 /**
- * Open a SQLite database handle at `path`, selecting the driver for the current
- * runtime. Returns a handle conforming to the structural {@link Database} type.
- *
- * The Node driver (`better-sqlite3`) is required lazily and ONLY when not on
- * Bun, so importing this module under Bun never touches `better-sqlite3`.
+ * Ordered provider registry. The factory selects the first supported provider.
+ * A future Postgres provider is appended here — and only here. Both SQLite
+ * engines are kept as distinct providers (not collapsed) because no single
+ * SQLite driver runs on both Bun and Node today.
  */
-export function openDatabase(path, opts) {
-    if (isBun) {
-        return openBunDatabase(path, opts);
+const PROVIDERS = [bunSqliteProvider, nodeSqliteProvider];
+/** Select the provider for the current runtime. */
+function selectProvider() {
+    const provider = PROVIDERS.find((p) => p.supported());
+    if (!provider) {
+        throw new Error(`No storage provider supports the current runtime (${isBun ? "Bun" : "Node"}).`);
     }
-    return openNodeDatabase(path, opts);
+    return provider;
+}
+/**
+ * Open a SQLite database handle at `path` via the active {@link StorageProvider}.
+ * Returns a handle conforming to the structural {@link Database} type.
+ */
+export function openDatabase(path, opts) {
+    return selectProvider().open(path, opts);
 }
 function openBunDatabase(path, opts) {
     const { Database: BunDatabase } = loadBunSqlite();
@@ -81,7 +102,21 @@ function loadBetterSqlite3() {
     if (!betterSqlite3Ctor) {
         // Runtime-gated dynamic require: only reached when NOT on Bun, so Bun never
         // resolves or loads the optional `better-sqlite3` native dependency.
-        const mod = nodeRequire("better-sqlite3");
+        // `better-sqlite3` is an optionalDependency, so `npm i` can succeed without
+        // it (or with a native build that failed). Convert the raw MODULE_NOT_FOUND
+        // into an actionable message instead of a cryptic onboarding crash.
+        let mod;
+        try {
+            mod = nodeRequire("better-sqlite3");
+        }
+        catch (err) {
+            throw new Error("akm could not load 'better-sqlite3', the SQLite driver it needs on Node.js.\n" +
+                "  • Reinstall akm with a working C/C++ build toolchain so its optional\n" +
+                "    'better-sqlite3' native binding rebuilds (a global `npm i -g better-sqlite3`\n" +
+                "    will NOT be resolved — Node loads it from akm's own node_modules).\n" +
+                "  • Or run akm under Bun, which has a built-in SQLite driver and needs no native build.\n" +
+                `  Underlying load error: ${err instanceof Error ? err.message : String(err)}`);
+        }
         betterSqlite3Ctor = mod.default ?? mod;
     }
     return betterSqlite3Ctor;

package/dist/storage/managed-db.js

@@ -0,0 +1,82 @@
+// This Source Code Form is subject to the terms of the Mozilla Public
+// License, v. 2.0. If a copy of the MPL was not distributed with this
+// file, You can obtain one at https://mozilla.org/MPL/2.0/.
+/**
+ * Managed-database seam — the single home for the SQLite open/lifecycle recipe.
+ *
+ * Before this module, two idioms were copy-pasted across state.db / logs.db /
+ * workflow.db / index.db and their consumers:
+ *
+ *   1. The open recipe: `mkdir(dir) → openDatabase(path) → applyStandardPragmas
+ *      → migrate`.
+ *   2. The borrow-or-own lifecycle: `const db = ctx?.db ?? open(); const owns =
+ *      !ctx?.db; try { … } finally { if (owns) db.close(); }`.
+ *
+ * {@link openManagedDatabase} owns (1); {@link withManagedDb} owns (2). Each DB
+ * module supplies only a path + initializer and gets a `withXDb` loan helper
+ * (see `withIndexDb`, `withStateDb`, etc.) so callers never hand-roll the
+ * ownership flag or the finally/close again. This is also the one place to add
+ * busy-timeout tuning, integrity checks, or test-isolation injection.
+ */
+import fs from "node:fs";
+import path from "node:path";
+import { openDatabase } from "./database.js";
+import { applyStandardPragmas } from "./sqlite-pragmas.js";
+/**
+ * Open a managed SQLite database: ensure the parent dir exists, open the handle,
+ * apply standard pragmas, then run the schema initializer. The single home for
+ * the open→pragmas→migrate recipe.
+ */
+export function openManagedDatabase(spec) {
+    const dir = path.dirname(spec.path);
+    if (!fs.existsSync(dir)) {
+        fs.mkdirSync(dir, { recursive: true });
+    }
+    const db = openDatabase(spec.path);
+    applyStandardPragmas(db, spec.pragmas ?? { dataDir: dir });
+    spec.init?.(db);
+    return db;
+}
+/**
+ * Run `fn` against a managed database, owning its lifecycle.
+ *
+ * When `opts.borrowed` is supplied the caller already owns an open handle: it is
+ * passed straight through and NOT closed (borrow). Otherwise a fresh handle is
+ * opened via `open` and closed in a `finally` (own). This replaces the
+ * hand-rolled `ctx?.db ?? open()` + `ownsDb` flag + `finally`/close idiom — the
+ * ownership decision and the close live here, once.
+ *
+ * Synchronous by design: the DB consumers (telemetry writers, planners) finish
+ * all work within the tick, matching the inline blocks this replaces.
+ */
+export function withManagedDb(open, fn, opts) {
+    if (opts?.borrowed) {
+        return fn(opts.borrowed);
+    }
+    const db = open();
+    try {
+        return fn(db);
+    }
+    finally {
+        db.close();
+    }
+}
+/**
+ * Async sibling of {@link withManagedDb}. Use this — NOT `withManagedDb` — when
+ * `fn` holds the handle across an `await`: the sync version closes in its
+ * `finally` before the awaited work resolves (use-after-close). Here the handle
+ * is closed only after `fn`'s promise settles. Borrowed handles pass straight
+ * through and are not closed, as in the sync version.
+ */
+export async function withManagedDbAsync(open, fn, opts) {
+    if (opts?.borrowed) {
+        return fn(opts.borrowed);
+    }
+    const db = open();
+    try {
+        return await fn(db);
+    }
+    finally {
+        db.close();
+    }
+}

package/dist/storage/repositories/registry-cache.js

@@ -0,0 +1,92 @@
+// This Source Code Form is subject to the terms of the Mozilla Public
+// License, v. 2.0. If a copy of the MPL was not distributed with this
+// file, You can obtain one at https://mozilla.org/MPL/2.0/.
+import { rethrowIfTestIsolationError } from "../../core/errors.js";
+import { closeDatabase, getRegistryIndexCache, openIndexDatabase, upsertRegistryIndexCache } from "../../indexer/db/db.js";
+/**
+ * RAII-style lifecycle helper for the registry cache DB. Opens the DB (treating
+ * a failed open exactly like the legacy fall-through: the bun-test isolation
+ * guard is re-thrown, any other failure yields `db = undefined`), runs `fn`,
+ * and guarantees the DB is closed in a `finally` after `fn` has fully settled
+ * (the await is required: the callbacks are async, and closing before they
+ * settle would tear the DB down mid-write).
+ */
+export async function withRegistryCacheDb(fn) {
+    let db;
+    try {
+        db = openIndexDatabase();
+    }
+    catch (err) {
+        // Never mask the bun-test isolation guard as "DB unavailable".
+        rethrowIfTestIsolationError(err);
+        db = undefined;
+    }
+    try {
+        return await fn(db);
+    }
+    finally {
+        if (db) {
+            try {
+                closeDatabase(db);
+            }
+            catch {
+                /* ignore */
+            }
+        }
+    }
+}
+/**
+ * Shared registry index-cache fetch template. Opens the cache DB, returns a
+ * fresh cache hit when present, otherwise fetches live (writing the result back
+ * to the cache best-effort), and falls back to a stale cache row when the fetch
+ * fails. Behaviour-preserving extraction of the logic previously duplicated in
+ * `skills-sh.ts` (`fetchSkills`) and `static-index.ts` (`loadIndex`).
+ */
+export async function fetchCachedJson(opts) {
+    const { cacheKey, ttlMs, parseCache, fetchFresh } = opts;
+    return withRegistryCacheDb(async (db) => {
+        // ── Step 1: Try DB cache (index.db) ─────────────────────────────────────
+        let dbCacheResult;
+        try {
+            if (db) {
+                dbCacheResult = getRegistryIndexCache(db, cacheKey, ttlMs);
+            }
+        }
+        catch (err) {
+            // Never mask the bun-test isolation guard as "DB unavailable" — see
+            // rethrowIfTestIsolationError in src/core/errors.ts. Without this, a
+            // leaky test silently gets a cold cache instead of the loud
+            // TEST_ISOLATION_MISSING failure the guard intends.
+            rethrowIfTestIsolationError(err);
+            // index.db read failed (pre-migration install or test env) — fall through
+        }
+        if (dbCacheResult) {
+            const cached = parseCache(dbCacheResult.indexJson, { stale: false });
+            if (cached !== undefined) {
+                return cached;
+            }
+        }
+        // ── Step 2: Fetch fresh ──────────────────────────────────────────────────
+        try {
+            const { value, cacheJson, cacheOpts } = await fetchFresh(db);
+            if (db) {
+                try {
+                    upsertRegistryIndexCache(db, cacheKey, cacheJson, cacheOpts);
+                }
+                catch {
+                    /* best-effort */
+                }
+            }
+            return value;
+        }
+        catch (err) {
+            // Fetch failed — use stale DB cache if available.
+            if (dbCacheResult) {
+                const stale = parseCache(dbCacheResult.indexJson, { stale: true });
+                if (stale !== undefined)
+                    return stale;
+            }
+            throw err;
+        }
+    });
+}