akm-cli 0.8.0-rc2 → 0.8.0

package/dist/core/errors.js

@@ -1,37 +1,27 @@
-/**
- * Typed error classes for structured exit code classification.
- *
- * - ConfigError  -> exit 78  (configuration / environment problems)
- * - UsageError   -> exit 2   (bad CLI arguments or invalid input)
- * - NotFoundError -> exit 1  (requested resource missing)
- *
- * Each error carries a machine-readable `code` field. Codes are stable
- * identifiers safe to consume from scripts and JSON output. Existing throw
- * sites without an explicit code receive a default code per error class so
- * older call sites continue to compile and behave unchanged.
- *
- * Each error also exposes a `hint()` method returning an actionable hint
- * string (or `undefined`). Hints can be supplied at construction time or
- * derived from the error `code` via the per-class default mapping below.
- * The CLI surfaces this via `error.hint()` rather than message-regex parsing.
- */
+// 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/.
 /**
  * Default hint for each ConfigError code. Keep these short, actionable, and
  * imperative. Returning undefined means "no canned hint".
  */
 const CONFIG_HINTS = {
-    STASH_DIR_NOT_FOUND: "Run `akm init` to create the default stash, or set stashDir in your config.",
+    STASH_DIR_NOT_FOUND: "Run `akm setup` to create and configure your stash, or set stashDir in your config.",
     STASH_DIR_NOT_A_DIRECTORY: "The configured stashDir exists but isn't a directory. Update stashDir to point at a folder.",
     STASH_DIR_UNREADABLE: "Check the path exists and your user has read permission, or update stashDir.",
     EMBEDDING_NOT_CONFIGURED: 'Run `akm config set embedding \'{"endpoint":"...","model":"..."}\'` to enable embeddings.',
-    LLM_NOT_CONFIGURED: 'Run `akm config set llm \'{"endpoint":"...","model":"..."}\'` to configure the LLM.',
+    LLM_NOT_CONFIGURED: 'Run `akm setup` or `akm config set profiles.llm.default \'{"endpoint":"...","model":"..."}\' to configure an LLM profile.',
+    TEST_ISOLATION_MISSING: "Under bun test, when AKM_STASH_DIR is set you MUST also set XDG_DATA_HOME (or AKM_DATA_DIR) and XDG_STATE_HOME (or AKM_STATE_DIR) to temp directories so the test does not touch the developer's real ~/.local/share/akm or ~/.local/state/akm.",
+    SETUP_TMP_STASH_REFUSED: "Use a persistent directory, or set AKM_FORCE_SETUP_TMP_STASH=1 to opt in to a sandboxed setup (setup also pre-sets AKM_STASH_DIR so config and cache writes auto-isolate into $stashDir/.akm/ — host config is preserved).",
+    UNSAFE_STASH_DIR: "Choose a path inside your home directory (e.g. ~/akm) or another empty workspace. The stash directory cannot be the filesystem root, your home directory itself, or a sensitive system path like /etc, /var, ~/.config, or ~/.ssh.",
 };
 /** Default hint for each UsageError code. */
 const USAGE_HINTS = {
     INVALID_FLAG_VALUE: "Run `akm <command> --help` to see accepted values.",
     INVALID_SOURCE_VALUE: "Pick one of: stash, registry, both.",
     INVALID_FORMAT_VALUE: "Pick one of: json, jsonl, text, yaml.",
-    INVALID_DETAIL_VALUE: "Pick one of: brief, normal, full, summary, agent.",
+    INVALID_DETAIL_VALUE: "Pick one of: brief, normal, full. For agent/summary projections use --shape.",
+    INVALID_SHAPE_VALUE: "Pick one of: human, agent, summary (summary is only valid on `akm show`).",
     INVALID_JSON_CONFIG_VALUE: 'Quote JSON values in your shell, for example: akm config set embedding \'{"endpoint":"http://localhost:11434/v1/embeddings","model":"nomic-embed-text"}\'.',
     MISSING_OR_AMBIGUOUS_TARGET: "Use `akm update --all` or pass a target like `akm update npm:@scope/pkg` (not both).",
     TARGET_NOT_UPDATABLE: "Run `akm list` to view your sources, then retry with one of those values.",
@@ -92,3 +82,35 @@ export class NotFoundError extends Error {
         return this._hint ?? NOT_FOUND_HINTS[this.code];
     }
 }
+/**
+ * Test-isolation guard helper.
+ *
+ * `src/core/paths.ts` throws `ConfigError("TEST_ISOLATION_MISSING")` under
+ * `bun test` when `AKM_STASH_DIR` is set without a paired data-dir or
+ * state-dir override. That throw must never be swallowed by best-effort
+ * catches around DB/data-dir operations — otherwise the guard's loud failure
+ * silently degrades into a "no result" outcome (cold cache, missing snapshot,
+ * etc.) and the underlying test leak goes undetected.
+ *
+ * Call `rethrowIfTestIsolationError(err)` from any catch block that returns
+ * a fallback value (null, [], empty result) after touching DB or data-dir
+ * paths. It re-throws when the caught error is the guard violation, otherwise
+ * does nothing so the existing benign-fallback path can proceed unchanged.
+ *
+ * Usage:
+ *   try {
+ *     const db = openDatabase();
+ *     // ...
+ *   } catch (err) {
+ *     rethrowIfTestIsolationError(err);
+ *     // existing benign-fallback handling
+ *   }
+ */
+export function isTestIsolationError(err) {
+    return err instanceof ConfigError && err.code === "TEST_ISOLATION_MISSING";
+}
+export function rethrowIfTestIsolationError(err) {
+    if (isTestIsolationError(err)) {
+        throw err;
+    }
+}

package/dist/core/events.js

@@ -1,27 +1,8 @@
-/**
- * Append-only events stream — backed by state.db (#204, Phase 3).
- *
- * Every mutating CLI verb funnels through `appendEvent` so external
- * observers (sync, replication, audit, dashboards) can react to stash
- * changes. Events are stored in the `events` table in `state.db`
- * (SQLite, WAL mode) instead of a flat `events.jsonl` file.
- *
- * The helper is the only thing in akm that writes to the events table. It
- * accepts an injectable `dbPath` (via `EventsContext`) so tests can pin a
- * tmpdir without any global mutation.
- *
- * Format (each EventEnvelope):
- *   { "schemaVersion": 1, "id": <number>, "ts": "<ISO>",
- *     "eventType": "<verb>", "ref"?: "<asset-ref>", ... }
- *
- * - `id` is a monotonic SQLite AUTOINCREMENT rowid. Callers can persist it
- *   as a durable cursor for `--since` resumption (replaces the old byte-offset
- *   cursor). The public API still surfaces this as `nextOffset` (an opaque
- *   number) for backward compatibility with callers that stored byte-offset
- *   cursors.
- * - `ts` is ISO-8601 (UTC, millisecond precision).
- */
+// 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 path from "node:path";
+import { rethrowIfTestIsolationError } from "./errors";
 import { getDataDir } from "./paths";
 import { insertEvent, openStateDatabase, readStateEvents } from "./state-db";
 import { error } from "./warn";
@@ -51,11 +32,32 @@ function resolveNow(ctx) {
  * stderr but never propagates — observability must not break mutation.
  *
  * Events are written exclusively to the `events` table in `state.db`.
+ *
+ * I1: when `ctx.db` is provided (a pre-opened long-lived connection), the
+ * function writes directly to that handle without opening or closing the DB.
+ * This eliminates per-event open/migrate/close overhead for high-frequency
+ * callers such as `akmImprove`.
  */
 export function appendEvent(input, ctx) {
-    const dbPath = resolveDbPath(ctx);
     const now = resolveNow(ctx);
     const ts = new Date(now()).toISOString();
+    // Fast path: caller provided a long-lived connection — use it directly.
+    if (ctx?.db) {
+        try {
+            insertEvent(ctx.db, {
+                eventType: input.eventType,
+                ts,
+                ref: input.ref,
+                metadata: input.metadata,
+            });
+        }
+        catch (err) {
+            error(`akm: appendEvent failed: ${String(err)}`);
+        }
+        return;
+    }
+    // Default path: open, insert, close.
+    const dbPath = resolveDbPath(ctx);
     try {
         const db = openStateDatabase(dbPath);
         try {
@@ -71,6 +73,8 @@ export function appendEvent(input, ctx) {
         }
     }
     catch (err) {
+        // Never mask the bun-test isolation guard as a silent "events failed".
+        rethrowIfTestIsolationError(err);
         // Best-effort: events stream failures must not break the mutating verb.
         // Surface once to stderr so operators can diagnose.
         error(`akm: appendEvent failed: ${String(err)}`);
@@ -86,7 +90,9 @@ export function readEvents(options = {}, ctx) {
     try {
         db = openStateDatabase(dbPath);
     }
-    catch {
+    catch (err) {
+        // Never mask the bun-test isolation guard as "no events".
+        rethrowIfTestIsolationError(err);
         // DB does not exist yet or cannot be opened — return empty result.
         return { events: [], nextOffset: 0 };
     }

package/dist/core/file-lock.js

@@ -0,0 +1,104 @@
+// 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 { isProcessAlive } from "./common";
+/**
+ * Atomically create a sentinel at `lockPath` with `payload` as the body.
+ * Returns true if we now own the lock, false if a sentinel already
+ * exists (EEXIST). Throws any other error (permissions, missing parent
+ * dir, etc.) — callers must ensure the parent directory exists.
+ *
+ * `payload` is typically `String(process.pid)` for the simple cases or
+ * a small JSON envelope for callers that want richer metadata
+ * (improve.ts records pid + startedAt so audit can correlate runs).
+ */
+export function tryAcquireLockSync(lockPath, payload) {
+    try {
+        fs.writeFileSync(lockPath, payload, { flag: "wx" });
+        return true;
+    }
+    catch (err) {
+        if (err.code === "EEXIST")
+            return false;
+        throw err;
+    }
+}
+/**
+ * Inspect an existing sentinel at `lockPath` without modifying it.
+ * Returns:
+ *   - `absent` if the file does not exist.
+ *   - `stale` if the file is present but should be reclaimed (the holding
+ *     PID is dead, the content is unparseable, or the lock has exceeded
+ *     `staleAfterMs`). Includes the failure reason so callers can log it.
+ *   - `held` if the lock has a live holder and is not yet age-expired.
+ *
+ * Does NOT remove the file. Callers decide recovery policy.
+ */
+export function probeLock(lockPath, opts) {
+    let rawContent;
+    let ageMs;
+    try {
+        rawContent = fs.readFileSync(lockPath, "utf8");
+    }
+    catch (err) {
+        if (err.code === "ENOENT")
+            return { state: "absent" };
+        return { state: "stale", reason: "unreadable" };
+    }
+    try {
+        const stat = fs.statSync(lockPath);
+        ageMs = Date.now() - stat.mtimeMs;
+    }
+    catch {
+        // Stat failed even though read succeeded — race-y removal in flight.
+        return { state: "stale", reason: "unreadable", rawContent };
+    }
+    const holderPid = extractHolderPid(rawContent);
+    if (holderPid === undefined) {
+        return { state: "stale", reason: "invalid_pid", ageMs, rawContent };
+    }
+    if (!isProcessAlive(holderPid)) {
+        return { state: "stale", reason: "pid_dead", holderPid, ageMs, rawContent };
+    }
+    if (opts?.staleAfterMs !== undefined && ageMs > opts.staleAfterMs) {
+        return { state: "stale", reason: "age_exceeded", holderPid, ageMs, rawContent };
+    }
+    return { state: "held", holderPid, ageMs, rawContent };
+}
+/**
+ * Remove a lock file. Idempotent — silently ignores ENOENT. Used both to
+ * reclaim stale locks (after probeLock returns `state: "stale"`) and to
+ * release locks we own (after a successful tryAcquireLockSync).
+ */
+export function releaseLock(lockPath) {
+    try {
+        fs.unlinkSync(lockPath);
+    }
+    catch {
+        // Sentinel already gone — fine.
+    }
+}
+/**
+ * Extract a PID from a sentinel body. Accepts the two shapes used across
+ * the codebase: a bare numeric string (config-io, vault, lockfile) and
+ * a JSON object with a `pid` field (improve). Returns undefined when the
+ * body is unparseable or yields a non-positive integer.
+ */
+function extractHolderPid(content) {
+    const trimmed = content.trim();
+    if (!trimmed)
+        return undefined;
+    if (trimmed.startsWith("{")) {
+        try {
+            const parsed = JSON.parse(trimmed);
+            const pid = typeof parsed.pid === "number" ? parsed.pid : Number.NaN;
+            return Number.isInteger(pid) && pid > 0 ? pid : undefined;
+        }
+        catch {
+            return undefined;
+        }
+    }
+    const pid = Number.parseInt(trimmed, 10);
+    return Number.isInteger(pid) && pid > 0 ? pid : undefined;
+}

package/dist/core/frontmatter.js

@@ -1,10 +1,12 @@
+// 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 frontmatter parsing utilities.
  *
  * Provides a single, canonical YAML-subset frontmatter parser used by both
  * the stash open logic and the metadata generator.
  */
-import { asNonEmptyString } from "./common";
 /**
  * Parse YAML-subset frontmatter from a Markdown (or similar) string.
  *
@@ -19,6 +21,9 @@ import { asNonEmptyString } from "./common";
  *   booleans, or numbers.
  * - **No nested objects beyond one level**: Only a single level of indented
  *   key-value pairs is supported.
+ * - **Block scalars**: `|` (literal), `|-` (strip), and `|+` (keep) block
+ *   scalars are supported for multi-line string values as emitted by the
+ *   `yaml` library's `stringify`.
  */
 export function parseFrontmatter(raw) {
     const parsedBlock = parseFrontmatterBlock(raw);
@@ -27,10 +32,18 @@ export function parseFrontmatter(raw) {
     }
     const data = {};
     let currentKey = null;
-    /** "scalar" | "list" | "object" | "pending" — "pending" means empty value, mode determined by next line */
+    /**
+     * "scalar" | "list" | "object" | "pending" | "block" —
+     * "pending" means empty value, mode determined by next line.
+     * "block" means we are accumulating lines for a `|`-block scalar.
+     */
     let mode = "scalar";
     let nested = null;
     let currentList = null;
+    /** Lines collected while in "block" mode. */
+    let blockLines = null;
+    /** Block scalar chomping: "clip" (|), "strip" (|-), "keep" (|+). */
+    let blockChomping = "clip";
     const flushPending = () => {
         // Called when we start a new top-level key and the previous key was still "pending".
         // An empty-value key followed by another top-level key means it was an empty scalar.
@@ -38,7 +51,41 @@ export function parseFrontmatter(raw) {
             data[currentKey] = "";
         }
     };
+    const flushBlock = () => {
+        // Commit the accumulated block-scalar lines to `data[currentKey]`.
+        if (mode !== "block" || currentKey === null || blockLines === null)
+            return;
+        // De-indent: strip the common 2-space prefix `yaml.stringify` emits.
+        const deindented = blockLines.map((l) => (l.startsWith("  ") ? l.slice(2) : l));
+        // Chomping: apply trailing-newline policy.
+        // "clip" (|): single trailing newline.
+        // "strip" (|-): no trailing newline.
+        // "keep" (|+): keep all trailing newlines as-is.
+        if (blockChomping === "keep") {
+            data[currentKey] = deindented.join("\n");
+        }
+        else if (blockChomping === "strip") {
+            data[currentKey] = deindented.join("\n").replace(/\n+$/, "");
+        }
+        else {
+            // "clip": exactly one trailing newline
+            data[currentKey] = `${deindented.join("\n").replace(/\n+$/, "")}\n`;
+        }
+    };
     for (const line of parsedBlock.frontmatter.split(/\r?\n/)) {
+        // If we are in block-scalar mode, collect indented lines or end the block.
+        if (mode === "block") {
+            if (line.startsWith("  ") || line === "") {
+                // Continuation of the block scalar (indented content or blank line).
+                blockLines.push(line);
+                continue;
+            }
+            // Non-indented line ends the block scalar — flush and fall through to
+            // parse the new line as a top-level key.
+            flushBlock();
+            mode = "scalar";
+            blockLines = null;
+        }
         // Block-sequence item: "- value" or "  - value" (optional 2-space indent)
         // Only match when the current key is in list or pending mode.
         const seqItem = line.match(/^(?: {2})?- (.*)$/);
@@ -52,6 +99,18 @@ export function parseFrontmatter(raw) {
             currentList.push(parseYamlScalar(seqItem[1].trim()));
             continue;
         }
+        // Plain-style multi-line scalar continuation: a 2-space-indented line that
+        // is not a sequence item or nested key. YAML plain scalars fold newlines
+        // into a single space, so we append with a space. This handles LLM-emitted
+        // descriptions like:
+        //   description: Use 4-colon outer containers when mixing
+        //     nesting depths in markdown-it-container plugins.
+        // Without this, only the first line is captured and the truncation
+        // heuristic wrongly flags it as cut off mid-sentence.
+        if (mode === "scalar" && currentKey !== null && /^ {2}\S/.test(line)) {
+            data[currentKey] = `${String(data[currentKey])} ${line.trim()}`;
+            continue;
+        }
         // Indented nested key-value (object under a key with empty value)
         const indented = line.match(/^ {2}(\w[\w-]*):\s*(.+)$/);
         if (indented && currentKey !== null && (mode === "object" || mode === "pending")) {
@@ -73,7 +132,15 @@ export function parseFrontmatter(raw) {
         flushPending();
         currentKey = top[1];
         const value = top[2].trim();
-        if (value === "") {
+        if (value === "|" || value === "|-" || value === "|+") {
+            // Block scalar header — collect subsequent indented lines.
+            mode = "block";
+            blockLines = [];
+            blockChomping = value === "|-" ? "strip" : value === "|+" ? "keep" : "clip";
+            nested = null;
+            currentList = null;
+        }
+        else if (value === "") {
             // Defer mode decision until we see the next line
             mode = "pending";
             nested = null;
@@ -84,6 +151,7 @@ export function parseFrontmatter(raw) {
             // Inline flow array: tags: [ops, networking]
             mode = "list";
             nested = null;
+            currentList = null;
             currentList = parseFlowArray(value);
             data[currentKey] = currentList;
         }
@@ -94,6 +162,10 @@ export function parseFrontmatter(raw) {
             data[currentKey] = parseYamlScalar(value);
         }
     }
+    // Flush any in-progress block scalar at end of frontmatter.
+    if (mode === "block") {
+        flushBlock();
+    }
     // Flush the last key if it was still pending (empty value, no continuation)
     flushPending();
     return {
@@ -151,10 +223,3 @@ export function parseYamlScalar(value) {
     }
     return value;
 }
-/**
- * Coerce an unknown value to a trimmed string, or return undefined if empty/non-string.
- * @deprecated Use `asNonEmptyString` from `core/common` directly.
- */
-export function toStringOrUndefined(value) {
-    return asNonEmptyString(value);
-}

package/dist/core/lesson-lint.js

@@ -1,3 +1,6 @@
+// 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/.
 /**
  * Deterministic frontmatter lint for `lesson` assets (v1 spec §13).
  *

package/dist/core/markdown.js

@@ -1,3 +1,6 @@
+// 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 { parseFrontmatter } from "./frontmatter";
 // ── Parsing ─────────────────────────────────────────────────────────────────
 export function parseMarkdownToc(content) {

package/dist/core/memory-belief.js

@@ -0,0 +1,62 @@
+// 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 memory belief-state machinery (C-3 / #382).
+ *
+ * Extracted from `memory-improve.ts` so both `akmConsolidate` and
+ * `analyzeMemoryCleanup` can emit `MemoryBeliefTransitionLogRecord` entries
+ * through a unified state-transition model.
+ *
+ * # Design
+ *
+ * The 4-state belief lifecycle (active → superseded | contradicted → archived)
+ * was previously encoded only in `memory-improve.ts`. `akmConsolidate` used a
+ * flat merge/delete/promote model with no belief states, causing the two engines
+ * to diverge. This module:
+ *
+ *   1. Re-exports the belief-state types from `memory-improve.ts` so callers
+ *      can import from one canonical location.
+ *   2. Provides `writeContradictEdge` — a shared primitive that both engines
+ *      use when an LLM (or heuristic) identifies a contradiction between two
+ *      memories. This is the bridge between `akmConsolidate`'s LLM-detected
+ *      contradictions and `resolveFamilyContradictions`' SCC resolver.
+ *
+ * # References
+ *
+ * - Zep / Graphiti (arXiv:2501.13956 §3) — unified belief-revision pipeline
+ * - MemOS (arXiv:2507.03724) — formal archive/merge/transition with shared state model
+ */
+import fs from "node:fs";
+import { assembleAsset } from "./asset-serialize";
+import { parseFrontmatter } from "./frontmatter";
+// ── Contradiction edge writer ─────────────────────────────────────────────────
+/**
+ * Write `contradictedBy` and `beliefState: contradicted` edges to a memory
+ * file's frontmatter (C-3 / #382).
+ *
+ * This is the shared primitive used by:
+ *   - `akmConsolidate` when its LLM plan includes a `contradict` op
+ *   - `memory-contradiction-detect.ts` for the M-1 automated contradiction pass
+ *   - `resolveFamilyContradictions` in `memory-improve.ts` for SCC resolution
+ *
+ * Idempotent: if the `contradictedByRef` is already in `contradictedBy`,
+ * the file is not rewritten.
+ *
+ * @param filePath          - Absolute path to the memory markdown file.
+ * @param contradictedByRef - The ref that contradicts this memory.
+ */
+export function writeContradictEdge(filePath, contradictedByRef) {
+    const raw = fs.readFileSync(filePath, "utf8");
+    const parsed = parseFrontmatter(raw);
+    const existing = Array.isArray(parsed.data.contradictedBy) ? parsed.data.contradictedBy : [];
+    if (existing.includes(contradictedByRef))
+        return; // Already written — idempotent.
+    const nextContradictedBy = [...new Set([...existing, contradictedByRef])].sort();
+    const nextFrontmatter = {
+        ...parsed.data,
+        contradictedBy: nextContradictedBy,
+        beliefState: "contradicted",
+    };
+    fs.writeFileSync(filePath, assembleAsset(nextFrontmatter, parsed.content), "utf8");
+}