akm-cli 0.7.4 → 0.8.0-rc.10

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,47 +1,28 @@
-/**
- * Append-only events stream — `events.jsonl` (#204).
- *
- * Every mutating CLI verb funnels through `appendEvent` so external
- * observers (sync, replication, audit, dashboards) can react to stash
- * changes by tailing a single file. The file is plain newline-delimited
- * JSON; each line is a self-contained event envelope.
- *
- * The helper is the only thing in akm that writes to events.jsonl. It
- * accepts injectable `now()` and `path` so tests can pin time and use a
- * tmpdir without any global mutation.
- *
- * Format (each line):
- *   { "schemaVersion": 1, "id": <number>, "ts": "<ISO>",
- *     "eventType": "<verb>", "ref"?: "<asset-ref>", ... }
- *
- * - `id` is a monotonic integer per file. We use the file's pre-write
- *   byte length as a durable cursor for `--since` (stable across processes
- *   because every appender holds an O_APPEND write). Callers can also pass
- *   a string ISO timestamp to `--since` and we filter by `ts >= since`.
- * - `ts` is ISO-8601 (UTC, millisecond precision).
- *
- * The event `id` is derived at read time (line index) — the file itself
- * is the source of truth, so the writer never has to coordinate with a
- * counter. Tail consumers can persist a byte offset (durable cursor).
- */
-import fs from "node:fs";
+// 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 { getCacheDir } from "./paths";
+import { rethrowIfTestIsolationError } from "./errors";
+import { getDataDir } from "./paths";
+import { insertEvent, openStateDatabase, readStateEvents } from "./state-db";
+import { error } from "./warn";
 /**
- * Default events.jsonl location: `<cacheDir>/events.jsonl`.
- *
- * Env-isolation caveat: `getCacheDir()` reads `XDG_CACHE_HOME` at the time of
- * each call. Two cooperating processes (e.g. one writing events, one tailing)
- * MUST inherit the same `XDG_CACHE_HOME` or they will read/write different
- * `events.jsonl` files. This is the same env-isolation behaviour as the rest
- * of akm — config, indexes, and caches all key off XDG paths — so set
- * `XDG_CACHE_HOME` consistently across processes that share the events bus.
+ * Legacy events.jsonl path — used only by the migration script
+ * (`scripts/migrate-storage.ts`) to import existing event history into
+ * state.db. No events are written here by akm v0.9+.
  */
 export function getEventsPath() {
-    return path.join(getCacheDir(), "events.jsonl");
+    return path.join(getDataDir(), "events.jsonl");
 }
-function resolvePath(ctx) {
-    return ctx?.filePath ?? getEventsPath();
+/**
+ * Resolve the state.db path from context:
+ *   1. `ctx.dbPath` — explicit override (test seam)
+ *   2. default      — `<dataDir>/state.db`
+ */
+function resolveDbPath(ctx) {
+    if (ctx?.dbPath)
+        return ctx.dbPath;
+    return path.join(getDataDir(), "state.db");
 }
 function resolveNow(ctx) {
     return ctx?.now ?? Date.now;
@@ -50,124 +31,101 @@ function resolveNow(ctx) {
  * Append a single event. Best-effort: a write failure is logged once to
  * stderr but never propagates — observability must not break mutation.
  *
- * The id field is intentionally omitted on write (the line index is the
- * id; the reader assigns it). Keeping it off the wire avoids a coordination
- * step between concurrent appenders.
+ * 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 filePath = resolvePath(ctx);
     const now = resolveNow(ctx);
     const ts = new Date(now()).toISOString();
-    const envelope = {
-        schemaVersion: 1,
-        ts,
-        eventType: input.eventType,
-        ...(input.ref !== undefined ? { ref: input.ref } : {}),
-        ...(input.metadata !== undefined ? { metadata: input.metadata } : {}),
-    };
-    const line = `${JSON.stringify(envelope)}\n`;
+    // 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 {
-        fs.mkdirSync(path.dirname(filePath), { recursive: true });
-        // O_APPEND guarantees atomic appends ≤ PIPE_BUF (4 KiB on Linux); our
-        // events are well under that ceiling, so concurrent processes can write
-        // safely without locking. `appendFileSync` opens with `'a'` which sets
-        // O_APPEND.
-        fs.appendFileSync(filePath, line, { encoding: "utf8" });
+        const db = openStateDatabase(dbPath);
+        try {
+            insertEvent(db, {
+                eventType: input.eventType,
+                ts,
+                ref: input.ref,
+                metadata: input.metadata,
+            });
+        }
+        finally {
+            db.close();
+        }
     }
     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.
-        const message = err instanceof Error ? err.message : String(err);
-        process.stderr.write(`akm: events.jsonl append failed (${message})\n`);
+        error(`akm: appendEvent failed: ${String(err)}`);
     }
 }
 /**
  * Read all events matching the filter. Returns a `nextOffset` that callers
- * can persist between processes for monotonic resumption — `sinceOffset`
- * is the durable cursor referenced in the acceptance criteria.
+ * can persist between processes for monotonic resumption.
  */
 export function readEvents(options = {}, ctx) {
-    const filePath = resolvePath(ctx);
-    if (!fs.existsSync(filePath)) {
-        return { events: [], nextOffset: 0 };
+    const dbPath = resolveDbPath(ctx);
+    let db;
+    try {
+        db = openStateDatabase(dbPath);
     }
-    const stat = fs.statSync(filePath);
-    const startOffset = options.sinceOffset && options.sinceOffset > 0 ? options.sinceOffset : 0;
-    if (startOffset >= stat.size) {
-        return { events: [], nextOffset: stat.size };
+    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 };
     }
-    const fd = fs.openSync(filePath, "r");
     try {
-        const length = stat.size - startOffset;
-        const buf = Buffer.alloc(length);
-        fs.readSync(fd, buf, 0, length, startOffset);
-        const text = buf.toString("utf8");
-        const events = parseEventLines(text, options, startOffset);
-        return { events, nextOffset: stat.size };
+        const { events: rawEvents, nextId } = readStateEvents(db, {
+            sinceId: options.sinceOffset,
+            since: options.since,
+            type: options.type,
+            ref: options.ref,
+        });
+        // Apply tag filters in application code (same as the old JSONL implementation).
+        const events = rawEvents.filter((envelope) => {
+            const tags = envelope.metadata?.tags ?? [];
+            if (options.excludeTags?.some((t) => tags.includes(t)))
+                return false;
+            if (options.includeTags && !options.includeTags.every((t) => tags.includes(t)))
+                return false;
+            return true;
+        });
+        return { events, nextOffset: nextId };
     }
     finally {
-        fs.closeSync(fd);
+        db.close();
     }
 }
-function parseEventLines(text, options, startOffset) {
-    // Each line that ends with \n is a complete event. A trailing partial
-    // line (no terminating \n) is ignored — the next read will pick it up
-    // once it is fully written.
-    const out = [];
-    let lineStart = 0;
-    // The envelope id is the 1-based line index across the whole file. We
-    // approximate that here as the line index from the start of the read
-    // window plus a synthetic offset — for callers using `--since`, the
-    // absolute id is less useful than the byte cursor anyway. To keep ids
-    // monotonic across reads we use absolute byte position as a stable
-    // surrogate identifier.
-    for (let i = 0; i < text.length; i += 1) {
-        if (text.charCodeAt(i) !== 10 /* \n */)
-            continue;
-        const line = text.slice(lineStart, i);
-        const absStart = startOffset + lineStart;
-        lineStart = i + 1;
-        if (!line.trim())
-            continue;
-        let parsed;
-        try {
-            parsed = JSON.parse(line);
-        }
-        catch {
-            // Skip malformed lines — better than crashing the read pipeline.
-            continue;
-        }
-        const envelope = {
-            schemaVersion: 1,
-            id: absStart,
-            ts: typeof parsed.ts === "string" ? parsed.ts : "",
-            eventType: typeof parsed.eventType === "string" ? parsed.eventType : "unknown",
-            ...(typeof parsed.ref === "string" ? { ref: parsed.ref } : {}),
-            ...(parsed.metadata !== undefined ? { metadata: parsed.metadata } : {}),
-        };
-        if (!matchesFilter(envelope, options))
-            continue;
-        out.push(envelope);
-    }
-    return out;
-}
-function matchesFilter(envelope, options) {
-    if (options.type && envelope.eventType !== options.type)
-        return false;
-    if (options.ref && envelope.ref !== options.ref)
-        return false;
-    if (options.since && envelope.ts && envelope.ts < options.since)
-        return false;
-    return true;
-}
 /**
- * Follow events.jsonl. Polls at `intervalMs` (default 75ms) and emits
- * every new event to `onEvent`. Resolves when `signal` aborts, when
+ * Follow the events table in state.db. Polls at `intervalMs` (default 75ms)
+ * and emits every new event to `onEvent`. Resolves when `signal` aborts, when
  * `maxEvents` events have been observed, or when `maxDurationMs` elapses.
  *
- * The polling cursor is byte-offset based, so concurrent writers cannot
- * cause skips: between two reads we always pick up everything appended
- * since the last `nextOffset`.
+ * The polling cursor is a monotonic SQLite rowid so concurrent writers cannot
+ * cause skips: between two reads we always pick up everything inserted since
+ * the last `nextOffset`.
  */
 export async function tailEvents(options = {}, ctx) {
     const intervalMs = options.intervalMs ?? 75;
@@ -178,7 +136,13 @@ export async function tailEvents(options = {}, ctx) {
     // we start polling. This matches the documented behaviour of `tail
     // --since`: emit existing events that match, then follow.
     if (options.sinceOffset === undefined) {
-        const initial = readEvents({ since: options.since, type: options.type, ref: options.ref }, ctx);
+        const initial = readEvents({
+            since: options.since,
+            type: options.type,
+            ref: options.ref,
+            excludeTags: options.excludeTags,
+            includeTags: options.includeTags,
+        }, ctx);
         for (const event of initial.events) {
             collected.push(event);
             options.onEvent?.(event);
@@ -202,11 +166,17 @@ export async function tailEvents(options = {}, ctx) {
         }
         function tick() {
             try {
-                const result = readEvents({ sinceOffset: cursor, type: options.type, ref: options.ref }, ctx);
+                const result = readEvents({
+                    sinceOffset: cursor,
+                    type: options.type,
+                    ref: options.ref,
+                    excludeTags: options.excludeTags,
+                    includeTags: options.includeTags,
+                }, ctx);
                 cursor = result.nextOffset;
                 for (const event of result.events) {
                     // Apply --since filter inside the polling loop too — the cursor is
-                    // byte-offset so it can hand us events the user filtered out.
+                    // rowid-based so it can hand us events the user filtered out.
                     if (options.since && event.ts && event.ts < options.since)
                         continue;
                     collected.push(event);

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,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/.
 /**
  * Shared frontmatter parsing utilities.
  *
@@ -18,6 +21,9 @@
  *   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);
@@ -26,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.
@@ -37,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})?- (.*)$/);
@@ -51,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")) {
@@ -72,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;
@@ -83,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;
         }
@@ -93,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 {
@@ -150,9 +223,3 @@ export function parseYamlScalar(value) {
     }
     return value;
 }
-/**
- * Coerce an unknown value to a trimmed string, or return undefined if empty/non-string.
- */
-export function toStringOrUndefined(value) {
-    return typeof value === "string" && value.trim() ? value : undefined;
-}

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) {
@@ -75,3 +78,20 @@ export function formatToc(toc) {
     parts.push(`\n${toc.totalLines} lines total`);
     return parts.join("\n");
 }
+// ── Fence stripping ──────────────────────────────────────────────────────────
+/**
+ * Best-effort fence stripping. Strips `<think>` reasoning blocks emitted by
+ * local LLMs (e.g. Qwen3) before the content, which otherwise breaks YAML
+ * frontmatter detection. Only strips outer triple-fence pairs — leaves inner
+ * code blocks intact.
+ */
+export function stripMarkdownFences(raw) {
+    const stripped = raw
+        .trim()
+        .replace(/<think>[\s\S]*?<\/think>/gi, "")
+        .trim();
+    const fence = stripped.match(/^```(?:markdown|md)?\s*\n([\s\S]*?)\n```\s*$/i);
+    if (fence)
+        return fence[1].trim();
+    return stripped;
+}