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

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();
+    }
+}

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;
+        }
+    });
+}

package/dist/storage/sqlite-pragmas.js

@@ -0,0 +1,146 @@
+// 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/.
+/**
+ * Shared SQLite PRAGMA application + journal-mode resolution (#628).
+ *
+ * Every AKM SQLite opener applies the same opening PRAGMAs: a journal mode, a
+ * 30 s busy_timeout, and (for most) foreign_keys = ON. Historically each opener
+ * hard-coded `PRAGMA journal_mode = WAL`. WAL is impossible on network
+ * filesystems (NFS/SMB) because its `-shm` shared-memory wal-index cannot be
+ * mmap'd over a network mount, so AKM could not run with its data dir on a
+ * network share.
+ *
+ * This module centralises that PRAGMA block behind {@link applyStandardPragmas}
+ * and makes the journal mode configurable via the `AKM_SQLITE_JOURNAL_MODE`
+ * env var (WAL | DELETE | TRUNCATE; default WAL = unchanged behaviour). When the
+ * mode is the WAL default and the data directory is detected to live on a
+ * network filesystem, it auto-falls-back to DELETE with a one-line warning.
+ *
+ * Boundary note: this is a PLAIN module, not a runtime-boundary file. It only
+ * does pure string work plus `db.exec()` (allowed everywhere). The single
+ * runtime primitive it needs — a filesystem-type probe (statfs) — lives in
+ * src/runtime.ts and is injected here, keeping the network-FS classifier a
+ * pure, unit-testable function.
+ *
+ * @module storage/sqlite-pragmas
+ */
+import { warn } from "../core/warn.js";
+import { statfsType } from "../runtime.js";
+const VALID_MODES = new Set(["WAL", "DELETE", "TRUNCATE"]);
+// One-shot warning guards so a misconfigured env var or a network-FS fallback
+// each emit AT MOST ONCE per process rather than on every db open.
+let warnedInvalid = false;
+let warnedNetworkFallback = false;
+/**
+ * Resolve a raw `AKM_SQLITE_JOURNAL_MODE` value to a canonical {@link JournalMode}.
+ *
+ * PURE and unit-testable: the raw string is passed in (not read from
+ * `process.env` here). Trims + uppercases; an empty/undefined value yields the
+ * WAL default; a recognised value yields its canonical form; any other
+ * non-empty value warns once and falls back to WAL. Never throws.
+ */
+export function resolveJournalMode(raw) {
+    if (raw === undefined)
+        return "WAL";
+    const normalized = raw.trim().toUpperCase();
+    if (normalized === "")
+        return "WAL";
+    if (VALID_MODES.has(normalized)) {
+        return normalized;
+    }
+    warnInvalidJournalModeOnce(raw);
+    return "WAL";
+}
+/**
+ * The single env-reading seam: resolve the configured journal mode from
+ * `process.env.AKM_SQLITE_JOURNAL_MODE`. Read at call time (per open) so tests
+ * that set the env per-case see the right value and we avoid stale-env flakes.
+ */
+export function resolveConfiguredJournalMode() {
+    return resolveJournalMode(process.env.AKM_SQLITE_JOURNAL_MODE);
+}
+function warnInvalidJournalModeOnce(raw) {
+    if (warnedInvalid)
+        return;
+    warnedInvalid = true;
+    warn(`[akm] invalid AKM_SQLITE_JOURNAL_MODE=${JSON.stringify(raw)} — using WAL (valid: WAL, DELETE, TRUNCATE)`);
+}
+// Known Linux f_type magic numbers for network filesystems. node's statfs
+// normalises `type` to this numeric f_type magic on all platforms.
+const FS_MAGIC_NFS = 0x6969; // 26985    — NFS
+const FS_MAGIC_SMB = 0x517b; // 20859    — older SMB_SUPER_MAGIC
+const FS_MAGIC_CIFS = 0xff534d42; // 4283649346 — SMB/CIFS
+const FS_MAGIC_SMB2 = 0xfe534d42; // 4267272514 — SMB2
+const FS_MAGIC_FUSE = 0x65735546; // 1702057286 — FUSE (sshfs + many network FUSE mounts)
+const NETWORK_FS_MAGICS = new Set([
+    FS_MAGIC_NFS,
+    FS_MAGIC_SMB,
+    FS_MAGIC_CIFS,
+    FS_MAGIC_SMB2,
+    // FUSE is a judgment call: it backs BOTH network mounts (sshfs) and local
+    // mounts (some encrypted/overlay FS). Treating it as network falls back to
+    // DELETE — conservative-but-safe (DELETE works everywhere; the only cost is
+    // losing WAL concurrency). An operator can always force WAL via the env var.
+    FS_MAGIC_FUSE,
+]);
+/**
+ * PURE classifier: is `fsType` a known network-filesystem magic number?
+ * Returns false for `undefined` (probe failed/unsupported) and for local
+ * magics (ext4 0xEF53, btrfs, xfs, tmpfs, apfs, …). Unit-testable with
+ * injected magic numbers — no real mount required.
+ */
+export function isNetworkFilesystem(fsType) {
+    if (fsType === undefined)
+        return false;
+    return NETWORK_FS_MAGICS.has(fsType);
+}
+/**
+ * Apply AKM's standard opening PRAGMAs to `db`, in order:
+ *   1. `journal_mode` = the configured mode (with WAL→DELETE network-FS fallback)
+ *   2. `busy_timeout = 30000`
+ *   3. `foreign_keys = ON`  (unless `opts.foreignKeys === false`)
+ *   4. `synchronous = FULL` (only in a rollback-journal mode — DELETE/TRUNCATE)
+ *
+ * Returns the effective {@link JournalMode} so callers/tests can assert it.
+ *
+ * `synchronous = FULL` is set explicitly only in DELETE/TRUNCATE so durability
+ * intent is clear: rollback journals need FULL for crash-durability across
+ * power loss, whereas WAL is durable at NORMAL. SQLite's default synchronous is
+ * already FULL when unset, so this never changes WAL-default behaviour — the
+ * WAL path emits no `synchronous` pragma, exactly as before.
+ */
+export function applyStandardPragmas(db, opts = {}) {
+    let mode = resolveConfiguredJournalMode();
+    // Network-FS fallback only fires for the WAL default and only when we have a
+    // directory to probe. An explicitly-requested DELETE/TRUNCATE is never
+    // overridden, and a failed/unsupported probe (undefined) keeps WAL.
+    if (mode === "WAL" && opts.dataDir) {
+        const probe = opts.fsTypeProbe ?? statfsType;
+        if (isNetworkFilesystem(probe(opts.dataDir))) {
+            mode = "DELETE";
+            warnNetworkFallbackOnce(opts.dataDir);
+        }
+    }
+    // PRAGMAs must run before any DDL or DML. busy_timeout is applied FIRST so a
+    // journal-mode change that must reclaim a leftover `-wal` file (WAL→DELETE on
+    // reopen of an unclean WAL db, e.g. after a crash) can wait out a transient
+    // lock instead of failing immediately with SQLITE_BUSY. For the WAL default
+    // this is a no-op (WAL→WAL changes nothing), so byte-identical behaviour is
+    // preserved.
+    db.exec("PRAGMA busy_timeout = 30000");
+    db.exec(`PRAGMA journal_mode = ${mode}`);
+    if (opts.foreignKeys !== false) {
+        db.exec("PRAGMA foreign_keys = ON");
+    }
+    if (mode !== "WAL") {
+        db.exec("PRAGMA synchronous = FULL");
+    }
+    return mode;
+}
+function warnNetworkFallbackOnce(dataDir) {
+    if (warnedNetworkFallback)
+        return;
+    warnedNetworkFallback = true;
+    warn(`[akm] network filesystem detected at ${dataDir} — WAL unsupported, using DELETE journal mode`);
+}

package/dist/tasks/backends/cron.js

@@ -29,7 +29,7 @@ import fs from "node:fs";
 import path from "node:path";
 import { ConfigError } from "../../core/errors.js";
 import { getTaskLogDir } from "../../core/paths.js";
-import { resolveAkmInvocation } from "../resolveAkmBin.js";
+import { resolveAkmInvocation } from "../resolve-akm-bin.js";
 import { parseSchedule, translateToCron } from "../schedule.js";
 const BEGIN = (id) => `# akm:task ${id} BEGIN`;
 const END = (id) => `# akm:task ${id} END`;

package/dist/tasks/backends/launchd.js

@@ -27,7 +27,7 @@ import path from "node:path";
 import launchdTemplate from "../../assets/backends/launchd-template.xml" with { type: "text" };
 import { ConfigError } from "../../core/errors.js";
 import { getTaskLogDir } from "../../core/paths.js";
-import { resolveAkmInvocation } from "../resolveAkmBin.js";
+import { resolveAkmInvocation } from "../resolve-akm-bin.js";
 import { parseSchedule, translateToLaunchd } from "../schedule.js";
 import { escapeXml, nodeExec, nodeFs } from "./exec-utils.js";
 export const LAUNCHD_LABEL_PREFIX = "com.akm.task.";

package/dist/tasks/backends/schtasks.js

@@ -35,7 +35,7 @@ import path from "node:path";
 import schtasksTemplate from "../../assets/backends/schtasks-template.xml" with { type: "text" };
 import { ConfigError } from "../../core/errors.js";
 import { getTaskLogDir } from "../../core/paths.js";
-import { resolveAkmInvocation } from "../resolveAkmBin.js";
+import { resolveAkmInvocation } from "../resolve-akm-bin.js";
 import { parseSchedule, translateToSchtasks } from "../schedule.js";
 import { escapeXml, nodeExec, nodeFs } from "./exec-utils.js";
 export const DEFAULT_FOLDER_PREFIX = "\\akm\\";

package/dist/tasks/{resolveAkmBin.js → resolve-akm-bin.js}

@@ -44,8 +44,8 @@ export function resolveAkmInvocation(options = {}) {
 /**
  * From the URL of a module inside `src/tasks/` figure out the CLI entry.
  *
- *   • dev      `…/src/tasks/resolveAkmBin.ts`   → `…/src/cli.ts`
- *   • build    `…/dist/tasks/resolveAkmBin.js`  → `…/dist/cli.js`
+ *   • dev      `…/src/tasks/resolve-akm-bin.ts`   → `…/src/cli.ts`
+ *   • build    `…/dist/tasks/resolve-akm-bin.js`  → `…/dist/cli.js`
  */
 function resolveCliEntry(moduleUrl) {
     let modulePath;