akm-cli 0.6.1 → 0.7.0

package/dist/src/core/events.js

@@ -0,0 +1,239 @@
+/**
+ * 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";
+import path from "node:path";
+import { getCacheDir } from "./paths";
+/**
+ * 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.
+ */
+export function getEventsPath() {
+    return path.join(getCacheDir(), "events.jsonl");
+}
+function resolvePath(ctx) {
+    return ctx?.filePath ?? getEventsPath();
+}
+function resolveNow(ctx) {
+    return ctx?.now ?? Date.now;
+}
+/**
+ * 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.
+ */
+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`;
+    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" });
+    }
+    catch (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`);
+    }
+}
+/**
+ * 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.
+ */
+export function readEvents(options = {}, ctx) {
+    const filePath = resolvePath(ctx);
+    if (!fs.existsSync(filePath)) {
+        return { events: [], nextOffset: 0 };
+    }
+    const stat = fs.statSync(filePath);
+    const startOffset = options.sinceOffset && options.sinceOffset > 0 ? options.sinceOffset : 0;
+    if (startOffset >= stat.size) {
+        return { events: [], nextOffset: stat.size };
+    }
+    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 };
+    }
+    finally {
+        fs.closeSync(fd);
+    }
+}
+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
+ * `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`.
+ */
+export async function tailEvents(options = {}, ctx) {
+    const intervalMs = options.intervalMs ?? 75;
+    const collected = [];
+    let cursor = options.sinceOffset ?? 0;
+    // Seed the cursor: if the caller passed --since (timestamp) but no
+    // sinceOffset, do an initial filtered read so they see history before
+    // 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);
+        for (const event of initial.events) {
+            collected.push(event);
+            options.onEvent?.(event);
+            if (options.maxEvents !== undefined && collected.length >= options.maxEvents) {
+                return { events: collected, nextOffset: initial.nextOffset, reason: "maxEvents" };
+            }
+        }
+        cursor = initial.nextOffset;
+    }
+    const startedAt = Date.now();
+    return new Promise((resolve) => {
+        let resolved = false;
+        let timer;
+        function finish(reason) {
+            if (resolved)
+                return;
+            resolved = true;
+            if (timer)
+                clearInterval(timer);
+            resolve({ events: collected, nextOffset: cursor, reason });
+        }
+        function tick() {
+            try {
+                const result = readEvents({ sinceOffset: cursor, type: options.type, ref: options.ref }, 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.
+                    if (options.since && event.ts && event.ts < options.since)
+                        continue;
+                    collected.push(event);
+                    options.onEvent?.(event);
+                    if (options.maxEvents !== undefined && collected.length >= options.maxEvents) {
+                        finish("maxEvents");
+                        return;
+                    }
+                }
+            }
+            catch {
+                // Non-fatal: stay in the loop.
+            }
+            if (options.maxDurationMs !== undefined && Date.now() - startedAt >= options.maxDurationMs) {
+                finish("maxDuration");
+            }
+        }
+        if (options.signal) {
+            if (options.signal.aborted) {
+                finish("signal");
+                return;
+            }
+            options.signal.addEventListener("abort", () => finish("signal"), { once: true });
+        }
+        timer = setInterval(tick, intervalMs);
+        // Run one tick immediately so callers don't have to wait an interval
+        // for events written in the same tick as the tail starts.
+        tick();
+    });
+}

package/dist/src/core/lesson-lint.js

@@ -0,0 +1,86 @@
+/**
+ * Deterministic frontmatter lint for `lesson` assets (v1 spec §13).
+ *
+ * The contract is fixed:
+ *
+ *   - Required: `description` — a non-empty single-line string describing
+ *     what the lesson teaches.
+ *   - Required: `when_to_use` — a non-empty single-line string describing
+ *     the trigger that should make a caller apply the lesson.
+ *
+ * Lint produces structured findings rather than throwing so callers can
+ * batch-validate (e.g. `akm proposal accept` over a queue) and surface every
+ * violation in a single pass. A strict wrapper (`assertLessonValid`) throws
+ * a `UsageError` for call sites that want a fail-fast contract — most
+ * notably the proposal-accept path described in v1 spec §13.1.
+ *
+ * The lint is intentionally side-effect free and does not import the indexer
+ * or filesystem walker; it operates on a single file path + raw string. This
+ * lets it run from any code path (CLI, proposal-accept, asset-spec tests)
+ * without dragging in the rest of the runtime.
+ */
+import fs from "node:fs";
+import { UsageError } from "./errors";
+import { parseFrontmatter } from "./frontmatter";
+function isNonEmptyString(value) {
+    return typeof value === "string" && value.trim().length > 0;
+}
+/**
+ * Lint a lesson given its raw markdown source.
+ *
+ * `pathForMessages` is woven into every finding's message so callers can
+ * surface the offending file in CLI/proposal flows without having to map
+ * findings back to paths separately.
+ */
+export function lintLessonContent(raw, pathForMessages) {
+    const findings = [];
+    const parsed = parseFrontmatter(raw);
+    const fm = parsed.data;
+    if (!("description" in fm)) {
+        findings.push({
+            kind: "missing-description",
+            field: "description",
+            message: `Lesson at ${pathForMessages} is missing required frontmatter field \`description\`.`,
+        });
+    }
+    else if (!isNonEmptyString(fm.description)) {
+        findings.push({
+            kind: "empty-description",
+            field: "description",
+            message: `Lesson at ${pathForMessages} has an empty \`description\` frontmatter field; it must be a non-empty single-line string.`,
+        });
+    }
+    if (!("when_to_use" in fm)) {
+        findings.push({
+            kind: "missing-when_to_use",
+            field: "when_to_use",
+            message: `Lesson at ${pathForMessages} is missing required frontmatter field \`when_to_use\`.`,
+        });
+    }
+    else if (!isNonEmptyString(fm.when_to_use)) {
+        findings.push({
+            kind: "empty-when_to_use",
+            field: "when_to_use",
+            message: `Lesson at ${pathForMessages} has an empty \`when_to_use\` frontmatter field; it must be a non-empty single-line string.`,
+        });
+    }
+    return { path: pathForMessages, findings };
+}
+/** Lint a lesson file on disk. Throws if the file cannot be read. */
+export function lintLessonFile(filePath) {
+    const raw = fs.readFileSync(filePath, "utf8");
+    return lintLessonContent(raw, filePath);
+}
+/**
+ * Strict variant: throws a `UsageError` if any finding is present. The thrown
+ * error carries the full set of findings on its message and a hint pointing
+ * at v1 spec §13. The first finding's `field` becomes the error's primary
+ * field for callers that want to highlight the first violation.
+ */
+export function assertLessonValid(filePath) {
+    const report = lintLessonFile(filePath);
+    if (report.findings.length === 0)
+        return;
+    const message = report.findings.map((f) => f.message).join("\n");
+    throw new UsageError(message, "MISSING_REQUIRED_ARGUMENT", "Lessons require non-empty `description` and `when_to_use` frontmatter fields. See v1 spec §13.");
+}