akm-cli 0.9.0-beta.1 → 0.9.0-beta.11

package/dist/cli/shared.js

@@ -12,6 +12,7 @@ import { stringify as yamlStringify } from "yaml";
 import { assertNever } from "../core/assert.js";
 import { AkmError } from "../core/errors.js";
 import { getOutputMode } from "../output/context.js";
+import { DEFAULT_TEMPLATE, deliverRendered, escapeHtml, renderHtml, resolveTemplatePath } from "../output/html-render.js";
 import { shapeForCommand } from "../output/shapes.js";
 import { formatPlain, outputJsonl } from "../output/text.js";
 // ── Exit codes ───────────────────────────────────────────────────────────────
@@ -111,7 +112,10 @@ export function defineJsonCommand(def) {
     });
 }
 /**
- * Render a command result according to the active output mode (json/jsonl/yaml/text).
+ * Render a command result according to the active output mode
+ * (json/jsonl/yaml/text/md/html). When `--output <path>` is set, the rendered
+ * document is written to that file instead of stdout (jsonl excepted — it is
+ * a line-streaming protocol and always goes to stdout).
  */
 export function output(command, result) {
     const mode = getOutputMode();
@@ -122,14 +126,14 @@ export function output(command, result) {
     }
     switch (mode.format) {
         case "json":
-            console.log(JSON.stringify(shaped, null, 2));
+            deliverRendered(JSON.stringify(shaped, null, 2), mode.outputPath);
             return;
         case "yaml":
-            console.log(yamlStringify(shaped));
+            deliverRendered(yamlStringify(shaped), mode.outputPath);
             return;
         case "text": {
             const plain = formatPlain(command, shaped, mode.detail);
-            console.log(plain ?? JSON.stringify(shaped, null, 2));
+            deliverRendered(plain ?? JSON.stringify(shaped, null, 2), mode.outputPath);
             return;
         }
         case "md":
@@ -137,8 +141,20 @@ export function output(command, result) {
             // per-run / window-compare table renderings. Commands that don't
             // implement an md renderer fall back to the JSON envelope so
             // pipelines never get an empty stdout.
-            console.log(JSON.stringify(shaped, null, 2));
+            deliverRendered(JSON.stringify(shaped, null, 2), mode.outputPath);
             return;
+        case "html": {
+            // Generic fallback: render the JSON envelope inside the dark-mode
+            // default template. Commands with a bespoke HTML template (`akm health`)
+            // intercept before reaching output(), same as the `md` intercept.
+            const html = renderHtml(resolveTemplatePath(DEFAULT_TEMPLATE), {
+                "%%COMMAND%%": escapeHtml(command),
+                "%%CONTENT_JSON%%": escapeHtml(JSON.stringify(shaped, null, 2)),
+                "%%GENERATED_AT%%": new Date().toISOString(),
+            });
+            deliverRendered(html, mode.outputPath);
+            return;
+        }
     }
 }
 /**

package/dist/cli.js

@@ -88,6 +88,7 @@ import { getCacheDir, getConfigPath, getDbPath } from "./core/paths.js";
 import { plainize } from "./core/tty.js";
 import { info, isQuiet, setQuiet, setVerbose, warn } from "./core/warn.js";
 import { getHyphenatedBoolean, getOutputMode, initOutputMode, parseFlagValue } from "./output/context.js";
+import { deliverRendered, renderHtml, resolveTemplatePath } from "./output/html-render.js";
 import { pkgVersion } from "./version.js";
 function applyEarlyStderrFlags(argv) {
     if (argv.includes("--quiet") || argv.includes("-q")) {
@@ -297,16 +298,47 @@ const healthCommand = defineCommand({
             type: "string",
             description: "Explicit comparison window 'name=...,since=ISO,until=ISO' (repeatable, up to 4; mutually exclusive with --window-compare)",
         },
+        compare: {
+            type: "string",
+            description: "Comparison window for the --format html report's trend deltas (default: 24h)",
+        },
     },
     async run({ args }) {
         let resultStatus;
-        await runWithJsonErrors(() => {
+        await runWithJsonErrors(async () => {
             // citty only surfaces the last value of a repeated flag, so read --windows
             // directly from argv to support multi-window comparison.
             const rawWindows = parseAllFlagValues("--windows");
             const windows = rawWindows.length > 0 ? rawWindows.map((raw) => parseWindowSpec(raw)) : undefined;
             const groupBy = args["group-by"];
             const windowCompareRaw = args["window-compare"];
+            const mode = getOutputMode();
+            // `--format html` is health-specific: render the full HTML health
+            // report (charts, KPI cards, advisories) from the bespoke template.
+            // Mirrors the `md` intercept below. Two reads, exactly like the
+            // retired akm-health-report skill: the canonical per-run window plus a
+            // window-compare read for the trend deltas (defaults to 24h,
+            // overridable via --compare).
+            if (mode.format === "html") {
+                // Default the compare window to the report's own `--since` window so the
+                // trend deltas are like-for-like (e.g. last 7d vs the prior 7d). A fixed
+                // 24h default made a `--since 7d` report compare its 7-day totals against
+                // a 24-hour prior window, producing meaningless deltas.
+                const compare = args.compare ?? windowCompareRaw ?? args.since ?? "24h";
+                const result = akmHealth({ since: args.since, groupBy: "run" });
+                resultStatus = result.status;
+                const deltas = akmHealth({ since: args.since, windowCompare: compare }).deltas;
+                const { buildHealthHtmlReplacements } = await import("./commands/health/html-report.js");
+                const { listPendingProposals } = await import("./commands/proposal/proposal.js");
+                const replacements = buildHealthHtmlReplacements(result, {
+                    window: args.since ?? "24h",
+                    compare,
+                    proposals: listPendingProposals(),
+                    deltas,
+                });
+                deliverRendered(renderHtml(resolveTemplatePath("health"), replacements), mode.outputPath);
+                return;
+            }
             const result = akmHealth({
                 since: args.since,
                 groupBy: groupBy,
@@ -317,13 +349,12 @@ const healthCommand = defineCommand({
             // `--format md` is health-specific: render a TSV-shaped per-run or
             // window-compare table to stdout instead of going through the JSON
             // envelope. Other modes fall through to the standard output() path.
-            const mode = getOutputMode();
             if (mode.format === "md") {
                 if (result.windows && result.windows.length > 0) {
-                    console.log(renderWindowCompareMd(result.windows, result.deltas));
+                    deliverRendered(renderWindowCompareMd(result.windows, result.deltas), mode.outputPath);
                 }
                 else if (result.runs) {
-                    console.log(renderRunsDetailMd(result.runs));
+                    deliverRendered(renderRunsDetailMd(result.runs), mode.outputPath);
                 }
                 else {
                     output("health", result);
@@ -419,7 +450,11 @@ export const main = defineCommand({
             "  78  config error",
     },
     args: {
-        format: { type: "string", description: "Output format (json|jsonl|text|yaml)", default: "json" },
+        format: { type: "string", description: "Output format (json|jsonl|text|yaml|md|html)", default: "json" },
+        output: {
+            type: "string",
+            description: "Write rendered output to a file instead of stdout (all formats except jsonl)",
+        },
         detail: {
             type: "string",
             description: "Detail level (verbosity): brief|normal|full. Default: brief.",
@@ -505,6 +540,13 @@ const EXIT_HEALTH_WARN = EXIT_CODES.HEALTH_WARN;
 // The wrapper sets `AKM_NODE_ENTRY=1` to opt into the startup block. The test
 // harness never sets it, so importing cli.ts under Bun stays inert as before.
 if (import.meta.main || process.env.AKM_NODE_ENTRY === "1") {
+    // Mark that this process is the real akm CLI: its `process.argv[1]` is the
+    // akm entrypoint, so the background auto-reindex may safely re-invoke it as a
+    // detached child. Hosts that merely import this module (the in-process test
+    // harness, library embeddings) never reach this block, so they fall back to
+    // an inline reindex instead of spawning the wrong program. See
+    // `ensureIndex` in src/indexer/ensure-index.ts.
+    process.env.AKM_CLI_ENTRY = "1";
     // citty reads process.argv directly and does not accept a custom argv array,
     // so we must replace process.argv with the normalized version before runMain.
     process.argv = normalizeShowArgv(process.argv);

package/dist/commands/config-cli.js

@@ -320,16 +320,6 @@ export const configCommand = defineJsonCommand({
                 }
             },
         }),
-        edit: defineJsonCommand({
-            meta: {
-                name: "edit",
-                description: "Interactively edit configuration via a schema-driven menu (TTY only).",
-            },
-            async run() {
-                const { runConfigEdit } = await import("./config-edit.js");
-                await runConfigEdit();
-            },
-        }),
         validate: defineJsonCommand({
             meta: {
                 name: "validate",

package/dist/commands/feedback-cli.js

@@ -14,6 +14,7 @@ import { appendEvent } from "../core/events.js";
 import { warn } from "../core/warn.js";
 import { applyFeedbackToUtilityScore, closeDatabase, findEntryIdByRef, getEntryFilePathById, openExistingDatabase, } from "../indexer/db/db.js";
 import { ensureIndex } from "../indexer/ensure-index.js";
+import { withIndexWriterLease } from "../indexer/index-writer-lock.js";
 import { resolveSourceEntries } from "../indexer/search/search-source.js";
 import { countFeedbackSignals, insertUsageEvent } from "../indexer/usage/usage-events.js";
 // ── Tag validation ────────────────────────────────────────────────────────────
@@ -203,47 +204,51 @@ export const feedbackCommand = defineCommand({
                 ...(validatedTags.length > 0 ? { tags: validatedTags } : {}),
             };
             const metadataStr = Object.keys(metadataObj).length > 1 ? JSON.stringify(metadataObj) : undefined;
-            // Auto-index when stale so the index is current before recording feedback.
-            const sources = resolveSourceEntries();
-            if (sources.length > 0) {
-                await ensureIndex(sources[0].path);
-            }
-            let utilityResult;
-            const db = openExistingDatabase();
-            try {
-                const entryId = findEntryIdByRef(db, ref);
-                if (entryId === undefined) {
-                    throw new UsageError(`Ref "${ref}" is not in the index. ` +
-                        "Run 'akm search' to verify the asset exists, then 'akm index' if it was recently added.");
+            const utilityResult = await withIndexWriterLease({ purpose: "feedback-write" }, async () => {
+                // Feedback is itself an index.db writer, so it must not spawn a detached
+                // reindex and then compete with it for the same database file.
+                const sources = resolveSourceEntries();
+                if (sources.length > 0) {
+                    await ensureIndex(sources[0].path, { mode: "blocking" });
                 }
-                // Persist the feedback signal into usage_events. For positive signals,
-                // the EMA utility score is updated immediately on the next read path.
-                // For negative signals, the score is adjusted the next time `akm index`
-                // runs — the signal is durable in the DB but does NOT suppress ranking
-                // in search results until after reindexing.
-                insertUsageEvent(db, {
-                    event_type: "feedback",
-                    entry_ref: ref,
-                    entry_id: entryId,
-                    signal,
-                    metadata: metadataStr,
-                });
-                // Apply feedback-derived utility score adjustment immediately so that
-                // positive/negative signals influence search ranking without requiring
-                // a full reindex. We query the total accumulated feedback counts from
-                // usage_events so the delta reflects the entire signal history.
-                // Uses MemRL bounded-step EMA (F-5 / #386, arXiv:2601.03192).
+                let scopedUtilityResult;
+                const db = openExistingDatabase();
                 try {
-                    const { pos, neg } = countFeedbackSignals(db, entryId);
-                    utilityResult = applyFeedbackToUtilityScore(db, entryId, pos, neg);
+                    const entryId = findEntryIdByRef(db, ref);
+                    if (entryId === undefined) {
+                        throw new UsageError(`Ref "${ref}" is not in the index. ` +
+                            "Run 'akm search' to verify the asset exists, then 'akm index' if it was recently added.");
+                    }
+                    // Persist the feedback signal into usage_events. For positive signals,
+                    // the EMA utility score is updated immediately on the next read path.
+                    // For negative signals, the score is adjusted the next time `akm index`
+                    // runs — the signal is durable in the DB but does NOT suppress ranking
+                    // in search results until after reindexing.
+                    insertUsageEvent(db, {
+                        event_type: "feedback",
+                        entry_ref: ref,
+                        entry_id: entryId,
+                        signal,
+                        metadata: metadataStr,
+                    });
+                    // Apply feedback-derived utility score adjustment immediately so that
+                    // positive/negative signals influence search ranking without requiring
+                    // a full reindex. We query the total accumulated feedback counts from
+                    // usage_events so the delta reflects the entire signal history.
+                    // Uses MemRL bounded-step EMA (F-5 / #386, arXiv:2601.03192).
+                    try {
+                        const { pos, neg } = countFeedbackSignals(db, entryId);
+                        scopedUtilityResult = applyFeedbackToUtilityScore(db, entryId, pos, neg);
+                    }
+                    catch {
+                        // best-effort — feedback recording succeeds even if utility update fails
+                    }
                 }
-                catch {
-                    // best-effort — feedback recording succeeds even if utility update fails
+                finally {
+                    closeDatabase(db);
                 }
-            }
-            finally {
-                closeDatabase(db);
-            }
+                return scopedUtilityResult;
+            });
             appendEvent({
                 eventType: "feedback",
                 ref,

package/dist/commands/graph/graph.js

@@ -12,6 +12,7 @@ import { closeDatabase, findEntryIdByRef, getEntryById, getEntryRefRowsForStashR
 import { loadStoredGraphSnapshot } from "../../indexer/db/graph-db.js";
 import { listRelatedPathsForFile } from "../../indexer/graph/graph-boost.js";
 import { runGraphExtractionPass } from "../../indexer/graph/graph-extraction.js";
+import { withIndexWriterLease } from "../../indexer/index-writer-lock.js";
 import { lookup } from "../../indexer/indexer.js";
 import { findSourceForPath, resolveSourceEntries } from "../../indexer/search/search-source.js";
 import { resolveAssetPath } from "../../indexer/walk/path-resolver.js";
@@ -375,85 +376,88 @@ export async function akmGraphUpdate(options) {
         }
     }
     const scoped = Array.isArray(options.refs) && options.refs.length > 0;
-    let candidatePaths;
-    if (scoped && options.refs) {
-        // Resolve each ref to an absolute file path via the index DB.
-        const dbPath = getDbPath();
-        let db;
-        const resolvedPaths = new Set();
-        try {
-            db = openDatabase(dbPath);
-            for (const ref of options.refs) {
-                const trimmed = ref.trim();
-                if (!trimmed)
-                    continue;
-                const entryId = findEntryIdByRef(db, trimmed);
-                if (entryId === undefined) {
-                    warn(`[graph] ref not found in index, skipping: ${trimmed}`);
-                    continue;
+    return withIndexWriterLease({ purpose: "graph-update" }, async () => {
+        let candidatePaths;
+        if (scoped && options.refs) {
+            // Resolve each ref to an absolute file path while the writer lease is held
+            // so the scoped graph write sees the same index snapshot it resolved from.
+            const dbPath = getDbPath();
+            let db;
+            const resolvedPaths = new Set();
+            try {
+                db = openDatabase(dbPath);
+                for (const ref of options.refs) {
+                    const trimmed = ref.trim();
+                    if (!trimmed)
+                        continue;
+                    const entryId = findEntryIdByRef(db, trimmed);
+                    if (entryId === undefined) {
+                        warn(`[graph] ref not found in index, skipping: ${trimmed}`);
+                        continue;
+                    }
+                    const row = getEntryById(db, entryId);
+                    if (!row?.filePath) {
+                        warn(`[graph] could not resolve path for ref, skipping: ${trimmed}`);
+                        continue;
+                    }
+                    resolvedPaths.add(row.filePath);
                 }
-                const row = getEntryById(db, entryId);
-                if (!row?.filePath) {
-                    warn(`[graph] could not resolve path for ref, skipping: ${trimmed}`);
-                    continue;
-                }
-                resolvedPaths.add(row.filePath);
             }
+            finally {
+                if (db)
+                    closeDatabase(db);
+            }
+            if (resolvedPaths.size === 0) {
+                warn("[graph] none of the provided refs resolved to indexed paths — no extraction performed.");
+                return {
+                    shape: "graph-update",
+                    ok: true,
+                    filesExtracted: 0,
+                    entitiesUpserted: 0,
+                    relationsUpserted: 0,
+                    durationMs: 0,
+                    scoped: true,
+                };
+            }
+            candidatePaths = resolvedPaths;
         }
-        finally {
-            if (db)
-                closeDatabase(db);
-        }
-        if (resolvedPaths.size === 0) {
-            warn("[graph] none of the provided refs resolved to indexed paths — no extraction performed.");
+        const extractionFn = options.graphExtractionFn ?? runGraphExtractionPass;
+        const passOptions = candidatePaths ? { candidatePaths } : {};
+        let db;
+        const startMs = Date.now();
+        try {
+            db = openDatabase(getDbPath());
+            const onProgress = (event) => {
+                if (!event.currentPath)
+                    return;
+                const file = path.basename(event.currentPath);
+                warn(`[graph] extracting ${event.processed}/${event.total} ${file}`);
+            };
+            const result = await extractionFn({
+                config,
+                sources,
+                signal: undefined,
+                db,
+                reEnrich: false,
+                onProgress,
+                options: passOptions,
+            });
+            const durationMs = Date.now() - startMs;
             return {
                 shape: "graph-update",
                 ok: true,
-                filesExtracted: 0,
-                entitiesUpserted: 0,
-                relationsUpserted: 0,
-                durationMs: 0,
-                scoped: true,
+                filesExtracted: result.quality.extractedFiles,
+                entitiesUpserted: result.quality.entityCount,
+                relationsUpserted: result.quality.relationCount,
+                durationMs,
+                scoped,
             };
         }
-        candidatePaths = resolvedPaths;
-    }
-    const extractionFn = options.graphExtractionFn ?? runGraphExtractionPass;
-    const passOptions = candidatePaths ? { candidatePaths } : {};
-    let db;
-    const startMs = Date.now();
-    try {
-        db = openDatabase(getDbPath());
-        const onProgress = (event) => {
-            if (!event.currentPath)
-                return;
-            const file = path.basename(event.currentPath);
-            warn(`[graph] extracting ${event.processed}/${event.total} ${file}`);
-        };
-        const result = await extractionFn({
-            config,
-            sources,
-            signal: undefined,
-            db,
-            reEnrich: false,
-            onProgress,
-            options: passOptions,
-        });
-        const durationMs = Date.now() - startMs;
-        return {
-            shape: "graph-update",
-            ok: true,
-            filesExtracted: result.quality.extractedFiles,
-            entitiesUpserted: result.quality.entityCount,
-            relationsUpserted: result.quality.relationCount,
-            durationMs,
-            scoped,
-        };
-    }
-    finally {
-        if (db)
-            closeDatabase(db);
-    }
+        finally {
+            if (db)
+                closeDatabase(db);
+        }
+    });
 }
 async function resolveGraphTarget(ref, source) {
     const parsedRef = parseAssetRef(ref);

package/dist/commands/health/checks.js

@@ -257,6 +257,54 @@ export const HEALTH_CHECKS = [
             };
         },
     },
+    {
+        // #603: pool-saturation advisory. The raw `sessionsScanned` count fired on
+        // normal cadence changes (the Jun 12 false alarm). Instead track the ratio
+        // of NEW (unseen) sessions to the total session pool extract evaluated in
+        // the window: a low ratio is the *expected* steady state, only a near-zero
+        // ratio signals a possible discovery/dedup bug.
+        //
+        // unseen ≈ `sessionsScanned` (extract only processes new sessions; already-
+        // seen ones are deduped into `sessionsSkipped`). total = scanned + skipped.
+        // This is a heuristic approximation — `sessionsSkipped` also folds in
+        // too-short skips — so the check is informational and never gates status.
+        name: "pool-saturation",
+        channel: "advisory",
+        run: (ctx) => {
+            const sx = ctx.sessionExtraction;
+            const total = sx.sessionsScanned + sx.sessionsSkipped;
+            const unseen = sx.sessionsScanned;
+            const ratio = total > 0 ? unseen / total : null;
+            const pct = ratio === null ? null : Math.round(ratio * 1000) / 10;
+            let status = "pass";
+            let confidence = "low";
+            let message;
+            if (!sx.ran || ratio === null) {
+                message = "Pool saturation: no extract activity in the window — no signal.";
+            }
+            else if (ratio < 0.02) {
+                status = "warn";
+                confidence = "medium";
+                message = `Session pool near-exhausted: only ${pct}% of the ${total}-session pool was new (<2%). Possible discovery/dedup bug — verify extract is still finding new sessions.`;
+            }
+            else if (ratio < 0.1) {
+                confidence = "medium";
+                message = `Session pool saturation: ${pct}% of ${total} sessions were new (<10%, steady-state expected — informational).`;
+            }
+            else {
+                confidence = "medium";
+                message = `Session pool healthy: ${pct}% of ${total} sessions were new.`;
+            }
+            return {
+                name: "pool-saturation",
+                kind: "heuristic",
+                status,
+                confidence,
+                message,
+                evidence: { totalSessions: total, unseenSessions: unseen, saturationRatio: ratio },
+            };
+        },
+    },
     {
         name: "auto-accept-validation",
         channel: "advisory",