akm-cli 0.9.0-beta.5 → 0.9.0-beta.50

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/tar-utils.js

@@ -12,12 +12,12 @@
  * providers that fetch tarballs (currently `NpmSourceProvider` and the
  * registry index builder).
  */
-import { spawnSync } from "node:child_process";
 import { createHash } from "node:crypto";
 import fs from "node:fs";
 import path from "node:path";
 import { isWithin } from "../../core/common.js";
 import { warn } from "../../core/warn.js";
+import { spawnSync } from "../../runtime.js";
 /**
  * Verify an archive's integrity against a known hash. Throws and removes
  * the archive when verification fails.
@@ -65,17 +65,25 @@ export function verifyArchiveIntegrity(archivePath, expected, source) {
  * tree for symlinks that would escape the destination.
  */
 export function extractTarGzSecure(archivePath, destinationDir) {
-    const listResult = spawnSync("tar", ["tzf", archivePath], { encoding: "utf8" });
-    if (listResult.status !== 0) {
-        const err = listResult.stderr?.trim() || listResult.error?.message || "unknown error";
+    const listResult = spawnSync(["tar", "tzf", archivePath]);
+    if (!listResult.success) {
+        const err = listResult.stderr?.toString().trim() || "unknown error";
         throw new Error(`Failed to inspect archive ${archivePath}: ${err}`);
     }
-    validateTarEntries(listResult.stdout);
+    validateTarEntries(listResult.stdout.toString());
     fs.rmSync(destinationDir, { recursive: true, force: true });
     fs.mkdirSync(destinationDir, { recursive: true });
-    const extractResult = spawnSync("tar", ["xzf", archivePath, "--no-same-owner", "--strip-components=1", "-C", destinationDir], { encoding: "utf8" });
-    if (extractResult.status !== 0) {
-        const err = extractResult.stderr?.trim() || extractResult.error?.message || "unknown error";
+    const extractResult = spawnSync([
+        "tar",
+        "xzf",
+        archivePath,
+        "--no-same-owner",
+        "--strip-components=1",
+        "-C",
+        destinationDir,
+    ]);
+    if (!extractResult.success) {
+        const err = extractResult.stderr?.toString().trim() || "unknown error";
         throw new Error(`Failed to extract archive ${archivePath}: ${err}`);
     }
     // Post-extraction scan: verify all extracted files are within destinationDir

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,239 @@
+// 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=";
+// Captions: the WEB watch-page caption baseUrls are now Proof-of-Origin-Token
+// gated (they carry `exp=xpe` and return an empty body without a `pot` token).
+// The ANDROID InnerTube `player` client still returns UNGATED caption baseUrls
+// that serve the transcript, so captions are sourced from there. See
+// https://github.com/yt-dlp/yt-dlp/issues/13075.
+const INNERTUBE_PLAYER_URL = "https://www.youtube.com/youtubei/v1/player";
+// Long-stable public InnerTube key; only authorizes the player call (not auth).
+const DEFAULT_INNERTUBE_KEY = "AIzaSyAO_FJ2SlqU8Q4STEHLGCilw_Y9_11qcW8";
+const ANDROID_INNERTUBE_CLIENT = {
+    clientName: "ANDROID",
+    clientVersion: "20.10.38",
+    androidSdkVersion: 34,
+    hl: "en",
+    gl: "US",
+};
+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;
+    }
+    if (url.pathname.startsWith("/embed/")) {
+        const id = url.pathname.slice("/embed/".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) {
+    // Two timedtext shapes: legacy srv1 `<text>` cues, and the format-3
+    // `<timedtext format="3">` `<p>` cues that the ANDROID InnerTube caption
+    // URLs return. Strip any nested `<s>` word tags via stripTags.
+    const matches = [...xml.matchAll(/<text\b[^>]*>([\s\S]*?)<\/text>/g), ...xml.matchAll(/<p\b[^>]*>([\s\S]*?)<\/p>/g)];
+    const texts = matches.map((match) => decodeEntities(stripTags(match[1] ?? "")).trim()).filter(Boolean);
+    if (texts.length === 0)
+        return null;
+    return texts.join("\n");
+}
+/**
+ * Fetch caption tracks via the ANDROID InnerTube `player` endpoint, whose
+ * caption baseUrls are not POT-gated. Returns [] on any failure so the caller
+ * can fall back to the (usually empty) watch-page tracks and degrade to a
+ * description-only snapshot.
+ */
+async function fetchInnertubeCaptionTracks(videoId, apiKey, timeoutMs, signal) {
+    try {
+        const response = await fetchWithRetry(`${INNERTUBE_PLAYER_URL}?key=${encodeURIComponent(apiKey)}`, {
+            method: "POST",
+            headers: {
+                "Content-Type": "application/json",
+                "User-Agent": "com.google.android.youtube/20.10.38 (Linux; U; Android 14) gzip",
+            },
+            body: JSON.stringify({ context: { client: ANDROID_INNERTUBE_CLIENT }, videoId }),
+            signal,
+        }, { timeout: timeoutMs, retries: 1 });
+        if (!response.ok)
+            return [];
+        const json = (await response.json());
+        return json.captions?.playerCaptionsTracklistRenderer?.captionTracks ?? [];
+    }
+    catch {
+        return [];
+    }
+}
+/** Extract the page's InnerTube API key, falling back to the stable default. */
+function extractInnertubeKey(html) {
+    return html.match(/"INNERTUBE_API_KEY":"([^"]+)"/)?.[1] ?? DEFAULT_INNERTUBE_KEY;
+}
+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);
+        }
+        // Prefer ungated ANDROID InnerTube caption tracks; fall back to the
+        // (now usually empty) watch-page tracks so a description-only snapshot
+        // still works when InnerTube is unavailable.
+        const apiKey = extractInnertubeKey(watchHtml);
+        let tracks = await fetchInnertubeCaptionTracks(videoId, apiKey, context.timeoutMs, context.signal);
+        if (tracks.length === 0) {
+            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();
+    }
+}