akm-cli 0.9.0 → 0.9.1-beta.2

package/dist/integrations/lockfile.js

@@ -7,6 +7,7 @@ import { writeFileAtomic } from "../core/common.js";
 import { ConfigError, rethrowIfTestIsolationError } from "../core/errors.js";
 import { createLockPayload, probeLock, reclaimStaleLock, releaseLock, tryAcquireLockSync } from "../core/file-lock.js";
 import { acquireMaintenanceBarrier } from "../core/maintenance-barrier.js";
+import { classifyPathAccess, describeInaccessiblePath } from "../core/path-access.js";
 import { getDataDir, getLockfileLockPath, getLockfilePath } from "../core/paths.js";
 // ── Lock sentinel ────────────────────────────────────────────────────────────
 const LOCK_MAX_RETRIES = 3;
@@ -54,6 +55,29 @@ export function readLockfile() {
         return [];
     }
 }
+/**
+ * Refuse to treat an UNREADABLE lockfile (or data dir) as an absent one (#791).
+ *
+ * Every write path here is read-modify-WRITE: it loads the current entries and
+ * writes the whole array back. An unreadable `akm.lock` that reads as `[]`
+ * therefore does not merely lose information — the very next
+ * `writeFileAtomic` replaces the operator's entire lock record with the single
+ * entry this call happened to be adding. That is the same catastrophe R-012
+ * guards against for a *corrupt* file, reached instead through a permission
+ * fault, and `fs.existsSync`/a swallowed `readFileSync` could not tell the two
+ * apart from "the file was never created".
+ *
+ * No-op when the path is genuinely absent — that case really does have nothing
+ * to preserve.
+ */
+function assertLockfilePathReadable(target) {
+    const { access, code } = classifyPathAccess(target);
+    if (access !== "inaccessible")
+        return;
+    throw new ConfigError(`Refusing to modify the lockfile: ${describeInaccessiblePath(target, code)}. akm cannot read the existing lock ` +
+        "records, and writing over them would destroy every bundle they track. Fix the ownership or mode of that " +
+        "path (or point AKM_DATA_DIR / XDG_DATA_HOME somewhere this user owns) and retry.", "DATA_DIR_UNREADABLE");
+}
 /**
  * Like {@link readLockfile}, but THROWS instead of silently degrading to `[]`
  * when the on-disk lockfile exists yet is not parseable JSON or not a JSON
@@ -82,7 +106,15 @@ function readLockfileOrThrow() {
     }
     catch (err) {
         rethrowIfTestIsolationError(err);
-        return []; // File does not exist (or is otherwise unreadable) — nothing to preserve.
+        // "Missing file" is the only failure with nothing to preserve. An
+        // UNREADABLE lockfile has everything to preserve and we cannot see it —
+        // degrading it to `[]` here is precisely the destructive overwrite this
+        // function was written to prevent, only triggered by a permission fault
+        // instead of a corrupt file (#791). Classify AFTER the failed read so the
+        // happy path costs no extra syscall and the answer describes the failure
+        // we actually got.
+        assertLockfilePathReadable(lockfilePath);
+        return [];
     }
     let parsed;
     try {
@@ -94,6 +126,16 @@ function readLockfileOrThrow() {
     if (!Array.isArray(parsed)) {
         throw new ConfigError(`Refusing to modify lockfile ${lockfilePath}: existing content is not a JSON array. Fix or remove the file by hand before retrying — every existing lock entry would otherwise be lost.`, "INVALID_CONFIG_FILE");
     }
+    // Refuse rather than filter. This is the WRITE path's read: everything it
+    // returns is what gets written back, so silently dropping entries that fail
+    // per-entry validation destroyed them on the next write — the same
+    // data-losing overwrite the two refusals above exist to prevent, just at
+    // entry granularity instead of file granularity.
+    const invalid = parsed.filter((entry) => !isValidLockfileEntry(entry));
+    if (invalid.length > 0) {
+        throw new ConfigError(`Refusing to modify lockfile ${lockfilePath}: ${invalid.length} existing entr${invalid.length === 1 ? "y is" : "ies are"} malformed. ` +
+            "Fix or remove the file by hand before retrying — those entries would otherwise be lost.", "INVALID_CONFIG_FILE");
+    }
     return parsed.filter(isValidLockfileEntry);
 }
 /**
@@ -172,6 +214,11 @@ export async function upsertLockEntry(entry) {
 function readLockEntriesForMigration() {
     let existing = [];
     const lockfilePath = getLockfilePath();
+    // `mergeLockEntriesSync` writes `existing` straight back out, so an
+    // unreadable lockfile read as absent would be overwritten with just the
+    // migrator's sparse entries (#791). This is also what
+    // `assertMigrationLockfileReadable` promises to have checked.
+    assertLockfilePathReadable(lockfilePath);
     if (fs.existsSync(lockfilePath)) {
         let raw;
         try {
@@ -211,7 +258,13 @@ export function mergeLockEntriesSync(entries) {
     writeLockfileUnlocked([...existing.filter((e) => !incomingIds.has(e.id)), ...merged]);
 }
 export async function removeLockEntry(id) {
-    if (!fs.existsSync(getDataDir()))
+    // Returning early says "there is no lock record to remove", and the uninstall
+    // that called us reports success on that basis. Only an absent data dir earns
+    // it — one we cannot read may hold the very entry we were asked to drop, and
+    // silently leaving it behind is how a bundle stays "installed" forever (#791).
+    const dataDir = getDataDir();
+    assertLockfilePathReadable(dataDir);
+    if (!fs.existsSync(dataDir))
         return;
     const release = await acquireLockSentinel();
     try {

package/dist/llm/client.js

@@ -9,34 +9,22 @@
  */
 import { fetchWithTimeout, readBodyWithByteCap } from "../core/common.js";
 import { resolveSecret } from "../core/config/config.js";
+import { ENV_REFERENCE_PATTERN } from "../core/config/schema/primitives.js";
 import { formatExtraParamsIssue, validateExtraParams } from "../core/extra-params.js";
 import { parseJsonResponse } from "../core/parse.js";
-import { redactCredentialPatterns, redactSensitiveText } from "../core/redaction.js";
+import { redactErrorBody, redactSensitiveText } from "../core/redaction.js";
 import { warnVerbose } from "../core/warn.js";
 import { DEFAULT_LLM_TIMEOUT_MS } from "../integrations/agent/config.js";
 import { emitLlmUsage, extractUsageTokens, } from "./usage-telemetry.js";
-/** Maximum length of an LLM error response body included in thrown errors. */
+/** Maximum length of an upstream response excerpt included in thrown errors. */
 const ERROR_BODY_MAX_LEN = 200;
 /** Stable OpenAI-compatible response-schema name used for every structured call. */
 const JSON_SCHEMA_RESPONSE_NAME = "akm_response";
 /**
- * Redact credential-shaped substrings from an upstream error body before
- * including it in a thrown Error. The body is also trimmed to a fixed length
- * so that a verbose provider response cannot leak large amounts of context.
- *
- * The pattern set itself lives in {@link redactCredentialPatterns}
- * (src/core/redaction.ts) so other output paths (e.g. task run logs) can
- * reuse it without this function's length cap.
+ * Re-exported from src/core/redaction.ts, where it now lives so every HTTP
+ * transport can apply the same hardening — the embeddings client needs it too.
  */
-export function redactErrorBody(input) {
-    if (!input)
-        return "";
-    let out = redactCredentialPatterns(input);
-    if (out.length > ERROR_BODY_MAX_LEN) {
-        out = `${out.slice(0, ERROR_BODY_MAX_LEN)}…`;
-    }
-    return out;
-}
+export { redactErrorBody } from "../core/redaction.js";
 /**
  * Detect a response body that is an HTML document rather than the expected
  * JSON. LM Studio (and similar local providers) can serve their web UI on
@@ -223,7 +211,14 @@ async function chatCompletionAttempt(config, messages, options, timeoutMs) {
             throw new Error(formatExtraParamsIssue("LLM extraParams", issue));
     }
     const headers = { "Content-Type": "application/json" };
-    const resolvedKey = resolveSecret(config.apiKey);
+    // Resolve ONLY a whole-string env reference. Every live caller already hands
+    // us the materialized credential (materializeLlmConnection / materializeFrozenLlm
+    // resolve `$VAR` upstream, and engine config REQUIRES the symbolic form), so
+    // re-running the substitution over a literal key mangled any credential
+    // containing `$` — `sk-live$ecret` lost everything from the `$` onward, and
+    // the request failed with an opaque 401. The narrow check keeps the symbolic
+    // form working for any direct caller that still passes one.
+    const resolvedKey = ENV_REFERENCE_PATTERN.test(config.apiKey ?? "") ? resolveSecret(config.apiKey) : config.apiKey;
     if (resolvedKey) {
         headers.Authorization = `Bearer ${resolvedKey}`;
     }

package/dist/llm/embedder.js

@@ -65,12 +65,32 @@ export async function embed(text, embeddingConfig, signal) {
     const cached = getCachedEmbedding(key);
     if (cached)
         return cached;
-    const result = embeddingConfig && hasRemoteEndpoint(embeddingConfig)
-        ? await new RemoteEmbedder(embeddingConfig).embed(text, signal)
-        : await getLocalEmbedder().embed(text, signal);
+    const result = await embedOnce(text, embeddingConfig, signal);
     setCachedEmbedding(key, result);
     return result;
 }
+/**
+ * Resolve a single embedding through the configured provider.
+ *
+ * The local branch must honour `localModel` exactly as {@link embedBatch}
+ * does. The singleton is constructed with no default model, so routing through
+ * `getLocalEmbedder().embed()` silently used DEFAULT_LOCAL_MODEL: queries were
+ * embedded with a different model than the index was built with. Nothing
+ * detected it, because the provider fingerprint keys on `localModel`, so no
+ * purge or "pending" status ever fired — a dimension mismatch made semantic
+ * ranking contribute nothing, and a same-dimension override silently produced
+ * meaningless cross-model scores.
+ */
+async function embedOnce(text, embeddingConfig, signal) {
+    if (embeddingConfig && hasRemoteEndpoint(embeddingConfig)) {
+        return new RemoteEmbedder(embeddingConfig).embed(text, signal);
+    }
+    const localModel = embeddingConfig?.localModel;
+    if (localModel) {
+        return getLocalEmbedder().embedWithModel(text, localModel);
+    }
+    return getLocalEmbedder().embed(text, signal);
+}
 /**
  * Generate embeddings for multiple texts in batch.
  * Uses the OpenAI-compatible batch API for remote endpoints (batches of 100).

package/dist/llm/embedders/remote.js

@@ -9,6 +9,7 @@
  */
 import { fetchWithTimeout, isHttpUrl, readBodyWithByteCap } from "../../core/common.js";
 import { resolveSecret } from "../../core/config/config.js";
+import { redactErrorBody, redactSensitiveText } from "../../core/redaction.js";
 const DEFAULT_REMOTE_BATCH_SIZE = 100;
 /** Cheap token estimator: 4 chars ≈ 1 token. Used in verbose logging and error messages. */
 export function estimateTokenCount(text) {
@@ -54,7 +55,7 @@ export class RemoteEmbedder {
                     throw err;
                 return "";
             });
-            throw new Error(`Embedding request failed (${response.status}): ${errBody}`);
+            throw new Error(`Embedding request failed (${response.status}): ${this.safeErrorBody(errBody)}`);
         }
         const json = JSON.parse(await readBodyWithByteCap(response, undefined, { bodyTimeoutMs: 30_000, signal }));
         if (!json.data?.[0]?.embedding) {
@@ -94,7 +95,7 @@ export class RemoteEmbedder {
                         throw err;
                     return "";
                 });
-                throw new Error(`Embedding batch request failed (${response.status}): ${respBody}`);
+                throw new Error(`Embedding batch request failed (${response.status}): ${this.safeErrorBody(respBody)}`);
             }
             const json = JSON.parse(await readBodyWithByteCap(response, undefined, { bodyTimeoutMs: 30_000, signal }));
             if (!json.data || json.data.length !== batch.length) {
@@ -119,6 +120,21 @@ export class RemoteEmbedder {
         }
         return headers;
     }
+    /**
+     * Make a provider error body safe to embed in a thrown Error, matching the
+     * hardening llm/client.ts applies on the identical path: pattern-redact
+     * credential shapes, exact-scrub this connection's own key, and clip.
+     *
+     * These messages are durable — generateEmbeddingsForDb surfaces them as
+     * `embeddingResult.message`, which is written to semantic-status.json and
+     * replayed by `akm info` (including `--json`) until the next successful
+     * index, and printed on every vector-search attempt. Raw bodies reached that
+     * far unredacted and uncapped, at readBodyWithByteCap's 10 MB default.
+     */
+    safeErrorBody(body) {
+        const resolvedKey = resolveSecret(this.config.apiKey);
+        return redactSensitiveText(redactErrorBody(body), resolvedKey ? [resolvedKey] : []);
+    }
 }
 /**
  * L2-normalize a vector to unit length.
@@ -144,6 +160,15 @@ export function normalizeEmbeddingEndpoint(endpoint) {
     if (normalizedPath.endsWith("/embeddings")) {
         return parsed.toString();
     }
+    // Ollama's NATIVE embedding route is `/api/embed` (and the older
+    // `/api/embeddings`). Appending "/embeddings" to it produced
+    // `/api/embed/embeddings`, a 404 — so pointing akm at the native endpoint,
+    // which is what its own options like ollamaOptions and contextLength are
+    // for, could never work. An explicit path that is already an embedding route
+    // is left alone.
+    if (normalizedPath.endsWith("/embed")) {
+        return parsed.toString();
+    }
     parsed.pathname = normalizedPath ? `${normalizedPath}/embeddings` : "/embeddings";
     return parsed.toString();
 }

package/dist/output/html-render.js

@@ -14,8 +14,28 @@
  */
 import fs from "node:fs";
 import path from "node:path";
+import healthTemplate from "../assets/templates/html/health.html" with { type: "text" };
 import { getDirname } from "../runtime.js";
 const TEMPLATES_DIR = path.join(getDirname(import.meta.url), "../assets/templates/html");
+/**
+ * Templates embedded at build time, keyed by command name.
+ *
+ * `bun build --compile` embeds only what is imported `with { type: "text" }`;
+ * a plain `readFileSync` from a path relative to `import.meta.url` resolves
+ * into the virtual `/$bunfs` tree and misses. `akm health --report --format
+ * html` therefore crashed with ENOENT (exit 70) on the standalone binary that
+ * the CLI's own install error and the CHANGELOG promote as the runtime-free
+ * option. The text import works on all three runtimes: natively on Bun, via
+ * scripts/node-runtime/text-import-hook.mjs on Node, and embedded in the
+ * compiled binary.
+ */
+const EMBEDDED_TEMPLATES = {
+    // bun-types declares `*.html` as an `HTMLBundle` (its HTML-bundler entrypoint
+    // feature), which is not what a `type: "text"` import yields — the value is
+    // the file's contents as a string on every runtime. The cast reconciles the
+    // ambient declaration with the actual import attribute.
+    health: healthTemplate,
+};
 /**
  * Resolve the on-disk template path for a command's bespoke `<command>.html`.
  * The command name is sanitized to a bare basename so a hostile command
@@ -37,9 +57,28 @@ const TOKEN_RE = /%%[A-Z_]+%%/g;
  * matching the skill renderer's behaviour.
  */
 export function renderHtml(templatePath, replacements) {
-    const html = fs.readFileSync(templatePath, "utf8");
+    const html = readTemplate(templatePath);
     return html.replace(TOKEN_RE, (token) => replacements[token] ?? token);
 }
+/**
+ * Read a template from disk, falling back to the embedded copy.
+ *
+ * Disk stays primary so an operator (or a test) editing
+ * `src/assets/templates/html/<name>.html` sees the change without a rebuild.
+ * The fallback covers the standalone binary, where the file does not exist on
+ * any real filesystem.
+ */
+function readTemplate(templatePath) {
+    try {
+        return fs.readFileSync(templatePath, "utf8");
+    }
+    catch (err) {
+        const embedded = EMBEDDED_TEMPLATES[path.basename(templatePath, ".html")];
+        if (embedded !== undefined)
+            return embedded;
+        throw err;
+    }
+}
 /**
  * Minimal HTML entity escaping for text interpolated into templates. Escapes
  * the single quote as well as the double quote so escaped values are safe in

package/dist/output/text/lint-format.js

@@ -16,9 +16,18 @@ function glyphFor(fixed) {
         return { glyph: "✓", severityRank: 2 };
     return { glyph: "⚠", severityRank: 1 };
 }
+/**
+ * `file:line` when the finding is line-anchored (workflow parse/compile
+ * errors), bare `file` otherwise. `LintIssue.line` is optional precisely
+ * because most lint sources are whole-file, so their headline is byte-identical
+ * to what it has always been.
+ */
+function locationOf(issue) {
+    return typeof issue.line === "number" ? `${issue.file}:${issue.line}` : issue.file;
+}
 function issueEntry(issue) {
     const { glyph, severityRank } = glyphFor(issue.fixed);
-    return { severityRank, glyph, headline: `${issue.file}  [${issue.issue}]  ${issue.detail}` };
+    return { severityRank, glyph, headline: `${locationOf(issue)}  [${issue.issue}]  ${issue.detail}` };
 }
 function renderIssueSection(title, issues) {
     if (issues.length === 0)
@@ -30,14 +39,18 @@ export function formatLintPlain(r) {
         return null;
     const fixed = Array.isArray(r.fixed) ? r.fixed : [];
     const flagged = Array.isArray(r.flagged) ? r.flagged : [];
+    const warnings = Array.isArray(r.warnings) ? r.warnings : [];
     const summary = r.summary;
     const lines = [];
     if (typeof r.ok === "boolean")
         lines.push(`ok: ${r.ok}`);
-    lines.push(`summary: fixed=${summary?.fixed ?? fixed.length} flagged=${summary?.flagged ?? flagged.length}`);
-    // Flagged (still needs attention) surfaces before fixed (already handled)
-    // so a scan of the output hits the actionable items first.
+    lines.push(`summary: fixed=${summary?.fixed ?? fixed.length} flagged=${summary?.flagged ?? flagged.length}` +
+        ` warnings=${summary?.warnings ?? warnings.length}`);
+    // Flagged (still needs attention) surfaces before warnings (advisory,
+    // non-fatal) and fixed (already handled), so a scan of the output hits the
+    // actionable items first.
     lines.push("", ...renderIssueSection("flagged", flagged));
+    lines.push("", ...renderIssueSection("warnings", warnings));
     lines.push("", ...renderIssueSection("fixed", fixed));
     return lines.join("\n").trim();
 }

package/dist/runtime.js

@@ -78,8 +78,17 @@ function nodeSpawnAdapter(cmd, options) {
         detached: options.detached,
         stdio: [stdioFor(options.stdin), stdioFor(options.stdout), stdioFor(options.stderr)],
     });
+    // Node's 'exit' fires (null, signal) when the child dies from a signal.
+    // Resolving `code ?? 0` reported that as SUCCESS, so an OOM-killed or
+    // segfaulted child came back exit 0 with partial stdout. Bun resolves
+    // 128 + signum for the same case; match it so both runtimes agree and
+    // callers that only check `exitCode !== 0` classify signal deaths correctly.
+    let signalCode = null;
     const exited = new Promise((resolve, reject) => {
-        child.once("exit", (code) => resolve(code ?? 0));
+        child.once("exit", (code, signal) => {
+            signalCode = signal;
+            resolve(code ?? (signal ? 128 + signalNumber(signal) : 0));
+        });
         child.once("error", reject);
     });
     return {
@@ -96,12 +105,25 @@ function nodeSpawnAdapter(cmd, options) {
         get exitCode() {
             return child.exitCode;
         },
+        get signalCode() {
+            return signalCode ?? child.signalCode;
+        },
         pid: child.pid,
         kill(signal) {
             child.kill(signal);
         },
     };
 }
+/**
+ * Map a signal name to its number so a signal death can be reported as the
+ * conventional 128 + signum exit status. Falls back to SIGKILL's 9 for a name
+ * this platform does not define, which still yields a non-zero status — the
+ * property that matters for classifying the run as failed.
+ */
+function signalNumber(signal) {
+    const { constants } = nodeRequire("node:os");
+    return constants.signals[signal] ?? 9;
+}
 // `node:stream`'s Writable.toWeb is available on Node >=17; referenced via the
 // class to avoid a static import that Bun's typings may not expose.
 function Writable_toWeb(w) {