akm-cli 0.9.0-rc.0 → 0.9.0-rc.13

package/dist/commands/observability-cli.js

@@ -2,49 +2,78 @@
 // 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/.
 /**
- * Observability command cluster — `akm log` (events list/tail), `akm lessons`
- * (coverage), and `akm hints`. Extracted verbatim from src/cli.ts (WS6) so the
- * God Module shrinks; the `main.subCommands.{log,lessons,hints}` keys and every
- * subcommand's args/output shape are byte-identical.
+ * Observability command cluster — `akm log` (append-only events stream).
+ * Extracted verbatim from src/cli.ts (WS6) so the God Module shrinks; the
+ * `main.subCommands.log` key and its args/output shape are byte-identical.
  *
- * These three surfaces are cohesive read-only "tell me what happened / what to
- * do" commands: `log` reads the append-only state.db events stream, `lessons
- * coverage` reports tag-coverage gaps from the index, and `hints` prints the
- * embedded AGENTS.md guidance. They share no helpers with any command still
- * inline in cli.ts, so the `loadHints` private helper and the
- * `formatEventLine` / `EMBEDDED_HINTS*` / db-tag-set imports move with them.
+ * `log` reads the append-only state.db events stream. It shares no helpers
+ * with any command still inline in cli.ts.
  *
- * The leaf handlers whose body is a plain `runWithJsonErrors(...) + output(...)`
- * (`events list`, `lessons coverage`) are migrated onto `defineJsonCommand`,
- * which emits the same JSON envelope (stdout/stderr/exit-code) as the inline
- * form. `events tail` (manual streaming console/stderr writes) and `hints`
- * (direct `process.stdout.write`) keep a plain `defineCommand` wrapping
- * `runWithJsonErrors` so their byte-for-byte output stays untouched.
+ * 0.9.0 CLI overhaul (S3): `log` was a group with `list`/`tail` subcommands;
+ * `tail` (a foreground polling daemon) is dropped and `log` becomes a LEAF
+ * command that is today's `list` surface, unchanged (including the
+ * `--since @offset:<id>` durable cursor and --ref/--type filters). The
+ * `lessons`/`lesson` group (`coverage`, `strength`) is dropped entirely —
+ * ranking's `lessonStrength` contributor is untouched, only the CLI read
+ * surface for it goes away.
+ *
+ * The embedded agent-guide surfaces (`akm hints` and `akm help agents`) live
+ * in src/cli.ts, so their loading code is intentionally outside this module.
+ *
+ * The leaf handler's body is a plain `runWithJsonErrors(...) + output(...)`,
+ * migrated onto `defineJsonCommand`, which emits the same JSON envelope
+ * (stdout/stderr/exit-code) as the inline form.
  */
-import fs from "node:fs";
-import path from "node:path";
-import { defineCommand } from "citty";
 import { parsePositiveIntFlag } from "../cli/parse-args.js";
-import { defineJsonCommand, output, parseAllFlagValues, runWithJsonErrors } from "../cli/shared.js";
-import { closeDatabase, collectTagSetFromEntries, openExistingDatabase } from "../indexer/db/db.js";
-import { EMBEDDED_HINTS, EMBEDDED_HINTS_FULL } from "../output/cli-hints.js";
-import { getOutputMode, parseDetailLevel } from "../output/context.js";
-import { formatEventLine } from "../output/text.js";
-import { getDirname } from "../runtime.js";
-import { akmEventsList, akmEventsTail } from "./events.js";
+import { retiredCommandHint } from "../cli/retired-commands.js";
+import { defineJsonCommand, output, parseAllFlagValues } from "../cli/shared.js";
+import { UsageError } from "../core/errors.js";
+import { akmEventsList } from "./log.js";
+/**
+ * `log` flattened from a group (`log list`/`log tail`) to a leaf in 0.9 (S3).
+ * `log` declares no positional args, so citty leaves any leftover positional
+ * token in `args._` uninterpreted rather than rejecting it — meaning
+ * `akm log tail` and `akm log list` silently ran today's `log` surface
+ * instead of failing like the other removed spellings (`log tail` is the
+ * dangerous one: it used to stream/follow, so an unmigrated caller got a
+ * silent one-shot snapshot instead of an error).
+ */
+function rejectExtraLogPositionals(positionals) {
+    const extra = Array.isArray(positionals) ? positionals.map(String) : [];
+    if (extra.length === 0)
+        return;
+    // A retired subcommand spelling gets its replacement hint (same table the
+    // unknown-command path uses), so `akm log tail` teaches the durable-cursor
+    // polling pattern instead of a bare "takes no positional arguments".
+    const retired = extra[0] === undefined ? undefined : retiredCommandHint(["log"], extra[0]);
+    throw new UsageError(`akm log takes no positional arguments, but got ${extra.map((token) => `"${token}"`).join(" ")}. ` +
+        '"log list"/"log tail" were removed in 0.9.0 — `akm log` alone is today\'s `log list` surface.', "INVALID_FLAG_VALUE", retired);
+}
 // ── `akm log` ────────────────────────────────────────────────────────────────
-// Append-only events stream surface (#204). `list` reads state.db events
-// with optional --since/--type/--ref filters; `tail` follows the table via
-// a polling loop and prints each event as a single JSONL line.
-const eventsListCommand = defineJsonCommand({
-    meta: { name: "list", description: "List events from the append-only state.db events stream" },
+// Append-only events stream surface (#204). Reads state.db events with
+// optional --since/--type/--ref filters.
+//
+// R-060: the internal output()/shape-registry command name is `log-list`
+// (renamed from the pre-rename `events-list`, back when the command group was
+// still called `akm events`). This string never reaches the wire —
+// `shapeEventsOutput` (src/output/shapes/helpers.ts) builds its own envelope
+// and never stamps a `shape` field — so the rename is a coherence-only
+// change, not a schemaVersion bump. Kept as `log-list` (not renamed to `log`)
+// even though the group flattened to a leaf, to avoid unrelated churn on the
+// internal registry key.
+export const logCommand = defineJsonCommand({
+    meta: { name: "log", description: "List events from the append-only state.db events stream" },
     args: {
         since: {
             type: "string",
             description: "ISO timestamp / epoch ms, OR `@offset:<id>` for a durable row-id cursor (resume across processes)",
         },
         type: { type: "string", description: "Filter by event type (add, remove, remember, feedback, ...)" },
-        ref: { type: "string", description: "Filter by asset ref (type:name)" },
+        ref: { type: "string", description: "Filter by asset ref ([bundle//]conceptId)" },
+        run: {
+            type: "string",
+            description: "Filter to a workflow run's events (metadata.runId), e.g. the id from `akm workflow start`",
+        },
         "exclude-tags": {
             type: "string",
             description: "Exclude events matching these tags (repeatable)",
@@ -53,192 +82,25 @@ const eventsListCommand = defineJsonCommand({
             type: "string",
             description: "Only include events with ALL these tags (repeatable)",
         },
+        limit: {
+            type: "string",
+            description: "Return only the most recent N events matching every other filter (default: unlimited)",
+        },
     },
     run({ args }) {
+        rejectExtraLogPositionals(args._);
         const excludeTags = parseAllFlagValues("--exclude-tags");
         const includeTags = parseAllFlagValues("--include-tags");
+        const limit = parsePositiveIntFlag(args.limit);
         const result = akmEventsList({
             since: args.since,
             type: args.type,
             ref: args.ref,
+            run: args.run,
             ...(excludeTags.length > 0 ? { excludeTags } : {}),
             ...(includeTags.length > 0 ? { includeTags } : {}),
+            ...(limit !== undefined ? { limit } : {}),
         });
-        output("events-list", result);
+        output("log-list", result);
     },
 });
-const eventsTailCommand = defineCommand({
-    meta: { name: "tail", description: "Follow the append-only state.db events stream (polling)" },
-    args: {
-        since: {
-            type: "string",
-            description: "ISO timestamp / epoch ms, OR `@offset:<id>` for a durable row-id cursor (resume across processes)",
-        },
-        type: { type: "string", description: "Filter by event type" },
-        ref: { type: "string", description: "Filter by asset ref (type:name)" },
-        "interval-ms": { type: "string", description: "Polling interval in ms (default: 75)" },
-        "max-duration-ms": { type: "string", description: "Stop after this many ms (default: never)" },
-        "max-events": { type: "string", description: "Stop after observing this many events" },
-        "exclude-tags": {
-            type: "string",
-            description: "Exclude events matching these tags (repeatable)",
-        },
-        "include-tags": {
-            type: "string",
-            description: "Only include events with ALL these tags (repeatable)",
-        },
-    },
-    async run({ args }) {
-        await runWithJsonErrors(async () => {
-            const intervalMs = parsePositiveIntFlag(args["interval-ms"], "--interval-ms");
-            const maxDurationMs = parsePositiveIntFlag(args["max-duration-ms"], "--max-duration-ms");
-            const maxEvents = parsePositiveIntFlag(args["max-events"], "--max-events");
-            const mode = getOutputMode();
-            // In streaming text mode we want each event to print as soon as it
-            // arrives. The polling loop emits via `onEvent`; the final result is
-            // also rendered through the standard output() pipeline so JSON
-            // consumers always get the canonical envelope.
-            const stream = mode.format === "text" || mode.format === "jsonl";
-            const excludeTags = parseAllFlagValues("--exclude-tags");
-            const includeTags = parseAllFlagValues("--include-tags");
-            const result = await akmEventsTail({
-                since: args.since,
-                type: args.type,
-                ref: args.ref,
-                intervalMs,
-                maxDurationMs,
-                maxEvents,
-                ...(excludeTags.length > 0 ? { excludeTags } : {}),
-                ...(includeTags.length > 0 ? { includeTags } : {}),
-                onEvent: stream
-                    ? (event) => {
-                        if (mode.format === "jsonl") {
-                            console.log(JSON.stringify(event));
-                        }
-                        else {
-                            console.log(formatEventLine(event));
-                        }
-                    }
-                    : undefined,
-            });
-            // Emit the canonical envelope last (JSON/YAML modes rely on this;
-            // streaming modes already printed each event but we still emit a
-            // trailer so callers can persist the resumable cursor).
-            if (!stream) {
-                output("events-tail", result);
-            }
-            else if (mode.format === "jsonl") {
-                // Final discriminated trailer row so jsonl consumers can resume.
-                const trailer = {
-                    _kind: "trailer",
-                    schemaVersion: 1,
-                    nextOffset: result.nextOffset,
-                    totalCount: result.totalCount,
-                    reason: result.reason,
-                };
-                console.log(JSON.stringify(trailer));
-            }
-            else {
-                // text mode: keep stdout pristine for line-oriented parsers and
-                // emit the trailer on stderr.
-                process.stderr.write(`[events-tail] reason=${result.reason} nextOffset=${result.nextOffset} total=${result.totalCount}\n`);
-            }
-        });
-    },
-});
-export const logCommand = defineCommand({
-    meta: {
-        name: "log",
-        description: "Read or follow the append-only state.db events stream (mutations, feedback, indexing)",
-    },
-    subCommands: {
-        list: eventsListCommand,
-        tail: eventsTailCommand,
-    },
-});
-// ── lessons subcommands (Phase 7A / Advantage D4c) ──────────────────────────
-const lessonsCoverageCommand = defineJsonCommand({
-    meta: {
-        name: "coverage",
-        description: "Report tags that exist on indexed assets but are NOT yet covered by any lesson.\n\n" +
-            "Useful for spotting topics where the stash has skills/commands/scripts but no\n" +
-            "crystallized lesson — a signal that the team has tacit knowledge worth distilling.\n\n" +
-            "Default output is JSON: { uncoveredTags: string[], lessonTagCount: number, totalTagCount: number }.\n" +
-            "Pass --format text for a plain-text bulleted list.",
-    },
-    args: {},
-    run() {
-        const db = openExistingDatabase();
-        try {
-            const allTagSet = collectTagSetFromEntries(db, undefined);
-            const lessonTagSet = collectTagSetFromEntries(db, "lesson");
-            const uncovered = [];
-            for (const tag of allTagSet) {
-                if (!lessonTagSet.has(tag))
-                    uncovered.push(tag);
-            }
-            uncovered.sort((a, b) => a.localeCompare(b));
-            output("lessons-coverage", {
-                ok: true,
-                uncoveredTags: uncovered,
-                lessonTagCount: lessonTagSet.size,
-                totalTagCount: allTagSet.size,
-            });
-        }
-        finally {
-            closeDatabase(db);
-        }
-    },
-});
-export const lessonsCommand = defineCommand({
-    meta: {
-        name: "lessons",
-        alias: "lesson",
-        description: "Lesson-asset tooling: tag-coverage gaps, strength queries.",
-    },
-    subCommands: {
-        coverage: lessonsCoverageCommand,
-    },
-});
-// ── `akm hints` ──────────────────────────────────────────────────────────────
-export const hintsCommand = defineCommand({
-    meta: {
-        name: "hints",
-        description: "Print agent instructions on how to use akm, use --detail full for a complete guide",
-    },
-    args: {
-        detail: {
-            type: "string",
-            description: "Hints detail level (brief|normal|full). `brief` prints the short guide; `normal`/`full` print the complete guide.",
-            default: "normal",
-        },
-    },
-    run({ args }) {
-        return runWithJsonErrors(() => {
-            // Let the global parser validate the value so an invalid `--detail`
-            // returns the standard JSON error envelope (exit 2) rather than a raw
-            // stack trace + exit 1. `brief` → short doc; `normal`/`full` → full doc.
-            const detail = parseDetailLevel(args.detail) ?? "normal";
-            process.stdout.write(loadHints(detail === "brief" ? "brief" : "full"));
-        });
-    },
-});
-// ── Hints (embedded AGENTS.md) ──────────────────────────────────────────────
-function loadHints(detail = "normal") {
-    // `brief` → the short AGENTS.md guide; `normal`/`full` → the complete guide.
-    const wantFull = detail !== "brief";
-    const filename = wantFull ? "AGENTS.full.md" : "AGENTS.md";
-    const fallback = wantFull ? EMBEDDED_HINTS_FULL : EMBEDDED_HINTS;
-    // Try reading from the docs/ directory (works in dev and when installed via npm)
-    try {
-        const docsPath = path.resolve(getDirname(import.meta.url), `../../docs/agents/${filename}`);
-        if (fs.existsSync(docsPath)) {
-            return fs.readFileSync(docsPath, "utf8");
-        }
-    }
-    catch {
-        // fall through
-    }
-    // Fallback for compiled binary — inline content
-    return fallback;
-}

package/dist/commands/proposal/diff-format.js

@@ -0,0 +1,50 @@
+// 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/.
+/**
+ * Proposal diff renderers — extracted verbatim from `repository.ts`
+ * (Chunk 6 WI-6.6 decompose). Pure string functions with no repository
+ * dependency; `diffProposal` (repository.ts) is the only production caller.
+ */
+/**
+ * Minimal unified-diff renderer. We deliberately avoid pulling a runtime
+ * dependency just for this — proposals diffs are usually small (a single
+ * lesson / skill file), so the LCS-free greedy renderer below is plenty for
+ * humans to review. The output mirrors `git diff --no-index` for the first
+ * `@@ … @@` hunk: enough to be familiar, not so detailed that we re-implement
+ * a full LCS table.
+ */
+export function formatUnifiedDiff(left, right, label) {
+    if (left === right)
+        return "";
+    const leftLines = left.split("\n");
+    const rightLines = right.split("\n");
+    const lines = [`--- ${label} (existing)`, `+++ ${label} (proposed)`];
+    // Pad to the longer side so alignment is one-to-one. Real diff tools use
+    // LCS to align matching runs; we don't need that fidelity for a review
+    // surface — both halves are visible regardless.
+    const max = Math.max(leftLines.length, rightLines.length);
+    lines.push(`@@ 1,${leftLines.length} 1,${rightLines.length} @@`);
+    for (let i = 0; i < max; i += 1) {
+        const l = leftLines[i];
+        const r = rightLines[i];
+        if (l === r && l !== undefined) {
+            lines.push(` ${l}`);
+            continue;
+        }
+        if (l !== undefined)
+            lines.push(`-${l}`);
+        if (r !== undefined)
+            lines.push(`+${r}`);
+    }
+    return lines.join("\n");
+}
+/** Render the all-additions diff for a proposal targeting a new asset. */
+export function formatNewAssetDiff(ref, content) {
+    const lines = [`--- /dev/null`, `+++ ${ref} (proposed, new asset)`];
+    lines.push(`@@ 0,0 1,${content.split("\n").length} @@`);
+    for (const line of content.split("\n")) {
+        lines.push(`+${line}`);
+    }
+    return lines.join("\n");
+}

package/dist/commands/proposal/drain-policies.js

@@ -47,12 +47,6 @@ export const PERSONAL_STASH = {
         { generator: "reflect", maxDiffLines: 80 },
         // Consolidate within the diff band; mid-band lands in `defer` below.
         { generator: "consolidate", maxDiffLines: 200 },
-        // Recombine: accept only confirmed type:lesson proposals (promoted by the
-        // recombine confidence gate) within the diff band. type:hypothesis proposals
-        // have no matching rule here and stay pending on the audited-autonomous
-        // queue until recombine supersedes them or the 90-day TTL sweeps them —
-        // there is no manual-review rung (06-M3).
-        { generator: "recombine", requireType: "lesson", maxDiffLines: 200 },
     ],
     rejectEmpty: true,
     // Mid-band consolidate, distill duplicates, and contradiction escalations are