akm-cli 0.9.0-beta.52 → 0.9.0-beta.54

package/dist/assets/hints/cli-hints-full.md

@@ -58,7 +58,7 @@ akm show knowledge:my-doc                    # Show content (local or remote)
 | knowledge | `content` (with view modes: `full`, `toc`, `frontmatter`, `section`, `lines`) |
 | workflow | `workflowTitle`, `workflowParameters`, `steps` |
 | memory | `content` (recalled context) |
-| env | `keys`, `comments` (key names + comments only — values never returned) |
+| env | `keys` (key names only — values and comment text never returned) |
 | secret | `name` only (the whole file is the value — never returned) |
 | wiki | `content` (same view modes as knowledge). For any wiki task, run `akm wiki list`. To ingest sources, `akm wiki ingest <name>` dispatches the configured agent (defaults.agent or `--profile`) to execute the ingest workflow. |
 
@@ -122,15 +122,16 @@ search results. No `--llm` anywhere — akm never reasons about page content.
 ## Env files
 
 A group of related CONFIGURATION for an app/service in one `.env` file at
-`<stashDir>/env/<name>.env`, sourced/injected wholesale. Key names + comments
-are discoverable; values stay on disk and never reach stdout or the index. akm
-does not edit entries — you edit the file with your own editor and akm loads it.
+`<stashDir>/env/<name>.env`, sourced/injected wholesale. Key names are
+discoverable; values and comment text stay on disk and never reach stdout or
+the index (comments can contain commented-out credentials). akm does not edit
+entries — you edit the file with your own editor and akm loads it.
 
 ```sh
 akm env create prod                           # Create an empty env file
 akm env create prod --from-file ./.env        # Ingest an existing .env
 akm env list                                  # List all env files across stashes with key names
-akm show env:prod                             # Inspect key names + comments (never values)
+akm show env:prod                             # Inspect key names (never values or comments)
 akm env run env:prod -- ./deploy.sh           # Run a command with the whole .env injected (the safe path)
 akm env run env:prod -- $SHELL                # Open an interactive shell with values injected
 akm env export env:prod --out ./env.sh        # Write a sourceable script to a file (mode 0600)

package/dist/cli/clack.js

@@ -0,0 +1,56 @@
+// 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 { cancel as realCancel, confirm as realConfirm, intro as realIntro, isCancel as realIsCancel, log as realLog, multiselect as realMultiselect, note as realNote, outro as realOutro, select as realSelect, spinner as realSpinner, text as realText, } from "@clack/prompts";
+// ── Test seam ────────────────────────────────────────────────────────────────
+// Swap-and-restore override. Inert in production; only tests call the setter
+// (via tests/_helpers/seams.ts `overrideSeam`, never directly).
+let clackFake;
+/** TEST-ONLY. Swap the clack prompt surface; pass undefined to restore. */
+export function _setClackForTests(fake) {
+    clackFake = fake;
+}
+const realFns = {
+    intro: realIntro,
+    outro: realOutro,
+    cancel: realCancel,
+    confirm: realConfirm,
+    select: realSelect,
+    multiselect: realMultiselect,
+    text: realText,
+    spinner: realSpinner,
+    note: realNote,
+    isCancel: realIsCancel,
+};
+/** Delegator with the real export's exact type; reads the fake at call time. */
+function bind(name) {
+    return ((...args) => {
+        const impl = (clackFake?.[name] ?? realFns[name]);
+        return impl(...args);
+    });
+}
+function bindLog(name) {
+    return ((...args) => {
+        const impl = (clackFake?.log?.[name] ?? realLog[name]);
+        return impl(...args);
+    });
+}
+export const intro = bind("intro");
+export const outro = bind("outro");
+export const cancel = bind("cancel");
+export const confirm = bind("confirm");
+export const select = bind("select");
+export const multiselect = bind("multiselect");
+export const text = bind("text");
+export const spinner = bind("spinner");
+export const note = bind("note");
+export const isCancel = bind("isCancel");
+export const log = {
+    message: bindLog("message"),
+    info: bindLog("info"),
+    success: bindLog("success"),
+    step: bindLog("step"),
+    warn: bindLog("warn"),
+    warning: bindLog("warning"),
+    error: bindLog("error"),
+};

package/dist/cli/confirm.js

@@ -35,8 +35,8 @@
  * `--quiet` NEVER suppresses the confirmation prompt — it is safety-critical
  * output. The auto-migration banner is similarly exempt from `--quiet`.
  */
-import * as p from "@clack/prompts";
 import { UsageError } from "../core/errors.js";
+import * as p from "./clack.js";
 /**
  * Prompt the user to confirm a destructive action.
  *

package/dist/cli.js

@@ -544,13 +544,6 @@ 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/env/env-cli.js

@@ -10,8 +10,9 @@
  * copy.
  *
  * `akm env` manages whole `.env` files under each stash's env/ directory.
- * Values are NEVER written to stdout or structured output — only key NAMES and
- * start-of-line comments are surfaced. akm does not manage individual entries;
+ * Values and comment text are NEVER written to stdout or structured output —
+ * only key NAMES are surfaced (comments routinely contain commented-out
+ * credentials). akm does not manage individual entries;
  * you edit the `.env` file yourself and akm loads it. Replaced the deprecated
  * `vault` type (removed in 0.9.0).
  */

package/dist/commands/env/env.js

@@ -18,10 +18,13 @@
  * round-trip through `dotenv`; the shell-load safety guarantee still lives on
  * the READ path (see `buildShellExportScript` + `akm env export`).
  *
- * Invariant: env values must never be written to stdout, returned through the
- * indexer, the `akm show` renderer, or any structured output channel. Key
- * NAMES and start-of-line comments ARE surfaced by design (discoverability) —
- * only values are secret. The supported value-load paths are:
+ * Invariant: nothing from an env file except key NAMES may be written to
+ * stdout, returned through the indexer, the `akm show` renderer, or any
+ * structured output channel. Key NAMES are surfaced for discoverability;
+ * comment text is NOT — real .env files routinely carry commented-out
+ * `KEY=value` lines and free-text notes containing live credentials, so
+ * comments are treated exactly like values. The supported value-load paths
+ * are:
  *
  *   - `akm env run <ref> -- <command>` — values injected into the child
  *     process env (never via a shell), see `injectIntoEnv` / `loadEnv`. This is
@@ -71,75 +74,19 @@ function scanKeys(text) {
     return keys;
 }
 /**
- * Scan lines and return start-of-line `#` comments (with the leading `#` and
- * any leading whitespace stripped). Inline/trailing `#` after an assignment is
- * never extracted.
- */
-function scanComments(text) {
-    const comments = [];
-    for (const line of text.split(/\r?\n/)) {
-        const trimmed = line.trimStart();
-        if (trimmed.startsWith("#")) {
-            comments.push(trimmed.slice(1).trimStart());
-        }
-    }
-    return comments;
-}
-/**
- * Read and return ONLY non-secret metadata (keys + start-of-line comments).
+ * Read and return ONLY non-secret metadata: key names.
  *
  * The function reads the whole file into memory (same as any dotenv parser)
- * but deliberately does not parse values — the LHS-only regex scanners above
- * ensure no value content is retained or returned. The guarantee is that
- * values never leave this function.
+ * but deliberately does not parse values — the LHS-only regex scanner above
+ * ensures no value content is retained or returned. Comment text is never
+ * returned either: comments routinely contain commented-out `KEY=value`
+ * credentials and free-text secrets, so they never leave this function.
  */
 export function listKeys(envPath) {
     if (!fs.existsSync(envPath))
-        return { keys: [], comments: [] };
-    const text = fs.readFileSync(envPath, "utf8");
-    return { keys: scanKeys(text), comments: scanComments(text) };
-}
-/**
- * Return structured `entries` pairing each key with the nearest preceding
- * comment line (if any). This is an easier-to-consume shape than the parallel
- * `keys[]` + `comments[]` of `listKeys` (QA #35).
- *
- * Values are never included — the same privacy guarantee as `listKeys`.
- */
-export function listEntries(envPath) {
-    if (!fs.existsSync(envPath))
-        return [];
+        return { keys: [] };
     const text = fs.readFileSync(envPath, "utf8");
-    const lines = text.split(/\r?\n/);
-    const seen = new Set();
-    const entries = [];
-    let pendingComment;
-    for (const line of lines) {
-        const trimmed = line.trimStart();
-        if (trimmed.startsWith("#")) {
-            // Capture the most recent comment before a key
-            pendingComment = trimmed.slice(1).trimStart() || undefined;
-            continue;
-        }
-        const m = line.match(ASSIGN_RE);
-        if (m) {
-            const key = m[1];
-            if (!seen.has(key)) {
-                seen.add(key);
-                const entry = { key };
-                if (pendingComment)
-                    entry.comment = pendingComment;
-                entries.push(entry);
-            }
-            pendingComment = undefined;
-        }
-        else {
-            // Any non-comment, non-assignment line (including blank lines)
-            // breaks "nearest preceding comment line" association.
-            pendingComment = undefined;
-        }
-    }
-    return entries;
+    return { keys: scanKeys(text) };
 }
 /**
  * Read all KEY=value pairs from an env file. Intended for programmatic callers

package/dist/commands/health/checks.js

@@ -191,21 +191,34 @@ export const HEALTH_CHECKS = [
     {
         name: "semantic-search-runtime",
         channel: "advisory",
-        run: (ctx) => ({
-            name: "semantic-search-runtime",
-            kind: "deterministic",
-            status: !ctx.semanticStatus ||
-                ctx.semanticStatus.status === "pending" ||
-                ctx.semanticStatus.status === "ready-js" ||
-                ctx.semanticStatus.status === "ready-vec"
-                ? "pass"
-                : "warn",
-            confidence: "medium",
-            message: ctx.semanticStatus
-                ? `Semantic search status: ${ctx.semanticStatus.status}`
-                : "No semantic-search runtime status recorded yet.",
-            evidence: ctx.semanticStatus ? { ...ctx.semanticStatus } : undefined,
-        }),
+        run: (ctx) => {
+            const blocked = ctx.semanticStatus?.status === "blocked";
+            // The generic "status: blocked" line is not actionable when the real
+            // problem is a configured remote embedding endpoint that is down while
+            // semanticSearchMode leaves semantic search enabled — every index run
+            // burns time failing against it and searches silently degrade to
+            // keyword-only. Name the endpoint and the two ways out.
+            const remoteReason = ctx.semanticStatus?.reason?.startsWith("remote-") === true;
+            const endpointAdvisory = blocked && remoteReason && ctx.embeddingEndpoint
+                ? `Configured embedding endpoint ${ctx.embeddingEndpoint} is failing ` +
+                    `(${ctx.semanticStatus?.reason}${ctx.semanticStatus?.message ? `: ${ctx.semanticStatus.message}` : ""}) ` +
+                    `while semanticSearchMode is "${ctx.semanticSearchMode ?? "auto"}". Searches fall back to keyword-only. ` +
+                    `Restore the endpoint, or set semanticSearchMode to "off" (or remove embedding.endpoint to use the local model).`
+                : undefined;
+            return {
+                name: "semantic-search-runtime",
+                kind: "deterministic",
+                status: !ctx.semanticStatus || !blocked ? "pass" : "warn",
+                confidence: "medium",
+                message: endpointAdvisory ??
+                    (ctx.semanticStatus
+                        ? `Semantic search status: ${ctx.semanticStatus.status}`
+                        : "No semantic-search runtime status recorded yet."),
+                evidence: ctx.semanticStatus
+                    ? { ...ctx.semanticStatus, ...(ctx.embeddingEndpoint ? { embeddingEndpoint: ctx.embeddingEndpoint } : {}) }
+                    : undefined,
+            };
+        },
     },
     {
         // session-log-failures: demoted to informational — the ERROR_PATTERNS regex

package/dist/commands/health/html-report.js

@@ -282,6 +282,7 @@ export function buildHealthHtmlReplacements(result, opts) {
     };
     const coverage = improve.coverage;
     const degradation = improve.degradation;
+    const minting = improve.enrichmentMinting;
     // #576: real per-stage LLM token/time accounting (replaces the GPU-time
     // proxy). Optional-guarded so reports built from older health JSON without
     // the aggregate still render.
@@ -557,7 +558,7 @@ export function buildHealthHtmlReplacements(result, opts) {
             "Coverage rate",
             pct(coverage.rate, 1),
             "flat",
-            "Accepted proposals / total stash assets (denominator-fixed). Shows what fraction of the corpus has been touched.",
+            "Distinct accepted refs / total stash assets (denominator-fixed). Shows what fraction of the corpus has been touched.",
         ], [
             "Eligible fraction",
             pct(coverage.eligibleFraction, 1),
@@ -566,8 +567,22 @@ export function buildHealthHtmlReplacements(result, opts) {
         ], [
             "Coverage accepted",
             num(coverage.acceptedProposals),
-            "up",
-            "Total accepted proposals used for the denominator-fixed coverage rate.",
+            "flat",
+            "Total accepted proposals in the window (raw volume — includes repeated rewrites of the same asset).",
+        ], [
+            "Churn ratio",
+            Number.isFinite(coverage.churnRatio) ? num(coverage.churnRatio) : "—",
+            Number.isFinite(coverage.churnRatio) && coverage.churnRatio > 1.5 ? "down" : "flat",
+            "Accepted proposals / distinct refs touched. >1.5 = the loop is repeatedly rewriting the same assets (churn, not coverage).",
+        ]);
+    }
+    // Enrichment-vs-minting policy rollup (reporting-only).
+    if (minting && Number.isFinite(minting.share)) {
+        summaryRows.push([
+            "Enrichment-lane minted share",
+            pct(minting.share, 1),
+            minting.share > 0.05 ? "down" : "flat",
+            `New assets minted by enrichment lanes / their accepted total (${minting.minted} minted vs ${minting.updated} updated). Enrichment lanes are ratified to edit existing assets only; WARN >5%, FAIL >15%.`,
         ]);
     }
     // WS-5: perf telemetry rows (only when at least one run reported telemetry).
@@ -606,18 +621,13 @@ export function buildHealthHtmlReplacements(result, opts) {
         summaryRows.push([
             "Corpus diversity (Gini)",
             num(degradation.corpusCentroidDistance),
-            degradation.entrenchmentFlagged ? "down" : "flat",
-            "Gini coefficient of retrieval_salience for top-100 ranked assets. High Gini (>0.35) = entrenchment risk.",
+            degradation.entrenchmentFlagged || degradation.salienceUniformityFlagged ? "down" : "flat",
+            "Gini coefficient of retrieval_salience for top-100 ranked assets. Two-tailed: >0.35 = entrenchment risk; <0.08 = collapsed toward uniform (ranking no longer discriminates).",
         ], [
             "Merge fidelity contradiction rate",
             pct(degradation.mergeFidelityContradictionRate, 1),
             "flat",
             "Fraction of consolidated proposals that involved a contradiction, from consolidation result envelopes.",
-        ], [
-            "High-generation fraction",
-            pct(degradation.highGenerationFraction, 1),
-            "flat",
-            "Fraction of assets with consecutive_no_ops >= 2 (proxy for high-generation assets in the salience table).",
         ]);
     }
     const summaryRowsHtml = summaryRows
@@ -726,6 +736,19 @@ export function buildHealthHtmlReplacements(result, opts) {
             remedy: "akm health --format json | jq '.improve.degradation'",
         });
     }
+    // Low-tail companion: salience distribution collapsed toward uniform.
+    if (degradation?.salienceUniformityFlagged) {
+        pushItem({
+            key: "salience-uniformity-collapse",
+            prio: "P2",
+            cls: "warn",
+            title: "Salience distribution collapsed: retrieval_salience Gini < 0.08",
+            descHtml: "The top-100 salience scores are near-uniform (uniform baseline ≈ 0.1) — " +
+                "ranking currently carries little to no discrimination between assets. " +
+                `Corpus diversity proxy: ${esc(String(degradation.corpusCentroidDistance))}.`,
+            remedy: "akm health --format json | jq '.improve.degradation'",
+        });
+    }
     // WS-5: over-budget consolidation advisory.
     if (perf.overBudgetRuns > 0) {
         pushItem({