akm-cli 0.8.2 → 0.9.0-beta.0

package/dist/commands/lint/memory-linter.js

@@ -2,7 +2,7 @@
 // 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 { BaseLinter } from "./base-linter";
+import { BaseLinter } from "./base-linter.js";
 /**
  * Linter for `memories/` assets.
  *

package/dist/commands/lint/registry.js

@@ -1,14 +1,14 @@
 // 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 { AgentLinter } from "./agent-linter";
-import { CommandLinter } from "./command-linter";
-import { DefaultLinter } from "./default-linter";
-import { KnowledgeLinter } from "./knowledge-linter";
-import { MemoryLinter } from "./memory-linter";
-import { SkillLinter } from "./skill-linter";
-import { TaskLinter } from "./task-linter";
-import { WorkflowLinter } from "./workflow-linter";
+import { AgentLinter } from "./agent-linter.js";
+import { CommandLinter } from "./command-linter.js";
+import { DefaultLinter } from "./default-linter.js";
+import { KnowledgeLinter } from "./knowledge-linter.js";
+import { MemoryLinter } from "./memory-linter.js";
+import { SkillLinter } from "./skill-linter.js";
+import { TaskLinter } from "./task-linter.js";
+import { WorkflowLinter } from "./workflow-linter.js";
 // Singleton instances — one per type, shared across all lint runs.
 const LINTERS = [
     new AgentLinter(),

package/dist/commands/lint/skill-linter.js

@@ -3,7 +3,7 @@
 // file, You can obtain one at https://mozilla.org/MPL/2.0/.
 import fs from "node:fs";
 import path from "node:path";
-import { BaseLinter } from "./base-linter";
+import { BaseLinter } from "./base-linter.js";
 /**
  * Linter for `skills/` assets.
  *

package/dist/commands/lint/task-linter.js

@@ -1,7 +1,7 @@
 // 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 { BaseLinter } from "./base-linter";
+import { BaseLinter } from "./base-linter.js";
 /**
  * Linter for `tasks/` assets.
  *

package/dist/commands/lint/workflow-linter.js

@@ -2,7 +2,7 @@
 // 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 { BaseLinter } from "./base-linter";
+import { BaseLinter } from "./base-linter.js";
 const PLACEHOLDER_STRINGS = ["Describe what this workflow accomplishes", "Example Workflow"];
 /**
  * Linter for `workflows/` assets.

package/dist/commands/lint.js

@@ -1,4 +1,4 @@
 // 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/.
-export { akmLint } from "./lint/index";
+export { akmLint } from "./lint/index.js";

package/dist/commands/observability-cli.js

@@ -0,0 +1,244 @@
+// 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/.
+/**
+ * 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.
+ *
+ * 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.
+ *
+ * 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.
+ */
+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 { getHyphenatedArg, getOutputMode, parseDetailLevel } from "../output/context.js";
+import { formatEventLine } from "../output/text.js";
+import { getDirname } from "../runtime.js";
+import { akmEventsList, akmEventsTail } from "./events.js";
+// ── `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" },
+    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)" },
+        "exclude-tags": {
+            type: "string",
+            description: "Exclude events matching these tags (repeatable)",
+        },
+        "include-tags": {
+            type: "string",
+            description: "Only include events with ALL these tags (repeatable)",
+        },
+    },
+    run({ args }) {
+        const excludeTags = parseAllFlagValues("--exclude-tags");
+        const includeTags = parseAllFlagValues("--include-tags");
+        const result = akmEventsList({
+            since: args.since,
+            type: args.type,
+            ref: args.ref,
+            ...(excludeTags.length > 0 ? { excludeTags } : {}),
+            ...(includeTags.length > 0 ? { includeTags } : {}),
+        });
+        output("events-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(getHyphenatedArg(args, "interval-ms"), "--interval-ms");
+            const maxDurationMs = parsePositiveIntFlag(getHyphenatedArg(args, "max-duration-ms"), "--max-duration-ms");
+            const maxEvents = parsePositiveIntFlag(getHyphenatedArg(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/drain-policies.js

@@ -16,10 +16,10 @@
  */
 import fs from "node:fs";
 import { z } from "zod";
-import { UsageError } from "../../core/errors";
-import { PROPOSAL_SOURCES } from "../../core/proposals";
+import { UsageError } from "../../core/errors.js";
+import { PROPOSAL_SOURCES } from "./validators/proposals.js";
 // Valid `generator` values for a drain rule are exactly the canonical proposal
-// `source` values (see {@link PROPOSAL_SOURCES} in src/core/proposals.ts). The
+// `source` values (see {@link PROPOSAL_SOURCES} in src/commands/proposal/validators/proposals.ts). The
 // engine matches rules via `policy.accept.find(r => r.generator === proposal.source)`,
 // so a generator that is not a real source can never match — it would be a
 // silent permanent no-op. Validate against the closed set to surface typos.

package/dist/commands/proposal/drain.js

@@ -36,16 +36,17 @@
  */
 import fs from "node:fs";
 import path from "node:path";
-import { parseAssetRef } from "../../core/asset-ref";
-import { resolveAssetPathFromName, TYPE_DIRS } from "../../core/asset-spec";
-import { appendEvent } from "../../core/events";
-import { parseFrontmatter } from "../../core/frontmatter";
-import { listProposals } from "../../core/proposals";
-import { info, warn } from "../../core/warn";
-import { runAgent } from "../../integrations/agent";
-import { runOpencodeSdk } from "../../integrations/agent/sdk-runner";
-import { chatCompletion, stripJsonFences } from "../../llm/client";
-import { akmProposalAccept, akmProposalReject } from "../proposal";
+import { assertNever } from "../../core/assert.js";
+import { parseAssetRef } from "../../core/asset/asset-ref.js";
+import { resolveAssetPathFromName, TYPE_DIRS } from "../../core/asset/asset-spec.js";
+import { parseFrontmatter } from "../../core/asset/frontmatter.js";
+import { appendEvent } from "../../core/events.js";
+import { info, warn } from "../../core/warn.js";
+import { runAgent } from "../../integrations/agent/index.js";
+import { runOpencodeSdk } from "../../integrations/harnesses/opencode-sdk/index.js";
+import { chatCompletion, stripJsonFences } from "../../llm/client.js";
+import { akmProposalAccept, akmProposalReject } from "./proposal.js";
+import { listProposals } from "./validators/proposals.js";
 // ---------------------------------------------------------------------------
 // Content helpers
 // ---------------------------------------------------------------------------
@@ -220,6 +221,10 @@ async function dispatchJudgment(runner, prompt, seams) {
             raw = stdout;
             break;
         }
+        default:
+            // Exhaustiveness arm (H1): a 4th RunnerSpec kind becomes a compile error
+            // here instead of leaving `raw` undefined at runtime.
+            return assertNever(runner);
     }
     return parseJudgmentVerdict(raw);
 }