akm-cli 0.9.0-beta.3 → 0.9.0-beta.31

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/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/workflows/db.js

@@ -6,6 +6,7 @@ import path from "node:path";
 import { getWorkflowDbPath } from "../core/paths.js";
 import { openDatabase } from "../storage/database.js";
 import { runMigrations as runSqliteMigrations } from "../storage/engines/sqlite-migrations.js";
+import { applyStandardPragmas } from "../storage/sqlite-pragmas.js";
 /**
  * workflow.db — Durable SQLite database for workflow run state.
  *
@@ -46,12 +47,10 @@ export function openWorkflowDatabase(dbPath = getWorkflowDbPath()) {
         fs.mkdirSync(dir, { recursive: true });
     }
     const db = openDatabase(dbPath);
-    db.exec("PRAGMA journal_mode = WAL");
     // #589: 30 s busy timeout, matching index.db / state.db. Without it the
     // default is 0 ms, so any concurrent writer fails immediately with
-    // SQLITE_BUSY.
-    db.exec("PRAGMA busy_timeout = 30000");
-    db.exec("PRAGMA foreign_keys = ON");
+    // SQLITE_BUSY. #628: journal_mode is configurable via AKM_SQLITE_JOURNAL_MODE.
+    applyStandardPragmas(db, { dataDir: dir });
     ensureBaseSchema(db);
     runMigrations(db);
     return db;

package/dist/workflows/validate-summary.js

@@ -16,14 +16,9 @@
  *
  * @module workflows/validate-summary
  */
+import validateSummaryJudgePrompt from "../assets/prompts/validate-summary-judge.md" with { type: "text" };
 import { parseJsonResponse } from "../core/parse.js";
-const JUDGE_SYSTEM = "You are a strict completion auditor for a software workflow engine. " +
-    "Given a step's completion criteria and a summary of the work an agent claims to have done, " +
-    "judge whether the summary provides concrete evidence that EVERY criterion is satisfied. " +
-    "Be skeptical: vague, hand-wavy, or unsubstantiated claims do NOT satisfy a criterion. " +
-    'Respond with ONLY a JSON object: {"complete": boolean, "missing": string[], "feedback": string}. ' +
-    '"missing" lists the exact criteria that are not yet satisfied; "feedback" is a short directive ' +
-    "telling the agent what to finish or fix. No prose, no markdown fences.";
+const JUDGE_SYSTEM = validateSummaryJudgePrompt;
 function buildUserPrompt(input) {
     const criteria = input.completionCriteria.map((c, i) => `${i + 1}. ${c}`).join("\n");
     return [

package/docs/data-and-telemetry.md

@@ -216,6 +216,7 @@ You can redirect any AKM directory to a custom path:
 |---|---|
 | `AKM_CONFIG_DIR` | Config directory (`~/.config/akm/`) |
 | `AKM_DATA_DIR` | Data directory (`~/.local/share/akm/`) |
+| `AKM_SQLITE_JOURNAL_MODE` | SQLite journal mode: `WAL` (default), `DELETE`, or `TRUNCATE`. Use `DELETE`/`TRUNCATE` on network filesystems (NFS/SMB) where WAL is impossible. When left at the `WAL` default, akm auto-detects a network FS for the data dir and falls back to `DELETE`. |
 | `AKM_STATE_DIR` | State directory (`~/.local/state/akm/`) |
 | `AKM_CACHE_DIR` | Cache directory (`~/.cache/akm/`) |
 | `AKM_STASH_DIR` | Default stash directory (`~/akm/`) |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "akm-cli",
-  "version": "0.9.0-beta.3",
+  "version": "0.9.0-beta.31",
   "type": "module",
   "description": "akm (Agent Knowledge Management) — A package manager for AI agent skills, commands, tools, and knowledge. Works with Claude Code, OpenCode, Cursor, and any AI coding assistant.",
   "keywords": [
@@ -51,15 +51,18 @@
   },
   "scripts": {
     "preinstall": "node -e \"var ua=process.env.npm_config_user_agent||'';var major=parseInt((process.versions.node||'0').split('.')[0],10);if(process.versions.bun||ua.startsWith('bun/')||process.env.BUN_INSTALL||major>=20){process.exit(0)}console.error('\\n  ERROR: akm-cli requires the Bun runtime (https://bun.sh), Node.js >= 20, or the prebuilt binary.\\n  Install options:\\n    1. Bun:    curl -fsSL https://bun.sh/install | bash  &&  bun install -g akm-cli\\n    2. Binary: curl -fsSL https://github.com/itlackey/akm/releases/latest/download/install.sh | bash\\n');process.exit(1)\"",
-    "build": "rm -rf dist && bun run tsc --project ./tsconfig.build.json && bun scripts/copy-assets.ts && bun scripts/fix-esm-extensions.ts",
+    "build": "rm -rf dist && bun scripts/gen-config-schema.ts &&bun run tsc --project ./tsconfig.build.json && bun scripts/copy-assets.ts && bun scripts/fix-esm-extensions.ts",
     "check": "bun run lint && bunx tsc --noEmit && bun run test:unit && bun run test:integration",
     "check:fast": "bun run lint && bunx tsc --noEmit && bun run test:unit",
     "check:changed": "bun test tests/output-baseline.test.ts tests/integration/e2e.test.ts tests/stash-search.test.ts && bun run lint && bunx tsc --noEmit",
-    "test": "bun test --parallel=${TEST_PARALLEL:-12} --timeout=30000 ./tests --path-ignore-patterns=tests/integration",
-    "test:unit": "bun test --parallel=${TEST_PARALLEL:-12} --timeout=30000 ./tests --path-ignore-patterns=tests/integration",
-    "test:integration": "bun test --parallel=${TEST_PARALLEL:-12} --timeout=30000 ./tests/integration ./tests/commands ./tests/workflows",
+    "sweep:tmp": "bun scripts/sweep-test-tmp.ts",
+    "test": "bun run sweep:tmp && bun test --parallel=${TEST_PARALLEL:-1} --timeout=30000 ./tests --path-ignore-patterns=tests/integration",
+    "test:unit": "bun run sweep:tmp && bun test --parallel=${TEST_PARALLEL:-1} --timeout=30000 ./tests --path-ignore-patterns=tests/integration",
+    "test:integration": "bun run sweep:tmp && bun test --parallel=${TEST_PARALLEL:-1} --timeout=30000 ./tests/integration ./tests/commands ./tests/workflows",
+    "test:unit:shard": "bun run sweep:tmp && bun test --parallel=1 --timeout=30000 ./tests --path-ignore-patterns=tests/integration --shard=${SHARD:?set SHARD=k/N}",
+    "test:integration:shard": "bun run sweep:tmp && bun test --parallel=1 --timeout=30000 ./tests/integration ./tests/commands ./tests/workflows --shard=${SHARD:?set SHARD=k/N}",
     "test:node-smoke": "bun scripts/node-smoke.ts",
-    "test:sharded": "bun test ./tests --shard=1/4 & bun test ./tests --shard=2/4 & bun test ./tests --shard=3/4 & bun test ./tests --shard=4/4 & wait",
+    "test:node-compat": "AKM_NODE_COMPAT_TESTS=1 bun test --timeout=120000 tests/integration/node-compat.test.ts",
     "test:time": "bun scripts/test-timing-report.ts",
     "lint:isolation": "bun scripts/lint-tests-isolation.ts",
     "lint:devto-posts": "bun scripts/lint-devto-posts.ts",