akm-cli 0.10.261019 → 0.10.261021

package/dist/commands/health/type-directory-check.js

@@ -22,28 +22,21 @@
 import fs from "node:fs";
 import path from "node:path";
 import { parseFrontmatter } from "../../core/asset/frontmatter.js";
+import { buildFileContext } from "../../indexer/walk/file-context.js";
+import { declaredTypeForPath } from "../../indexer/walk/matchers.js";
 /**
- * Directory → declared-type map, mirroring `DIR_TYPE_MAP` in
- * `src/indexer/walk/matchers.ts` minus its per-directory extension test —
- * this check only needs "which type does this directory declare", not which
- * extensions it accepts. Keep in sync if `DIR_TYPE_MAP` gains, renames, or
- * removes a directory.
+ * The type the entry's location declares under the `akm` stash rules, derived
+ * with the indexer's own directory predicates (see `declaredTypeForPath`).
+ * Other adapters, and paths outside the component root, declare nothing.
  */
-const DECLARED_DIR_TYPES = {
-    memories: "memory",
-    knowledge: "knowledge",
-    commands: "command",
-    agents: "agent",
-    workflows: "workflow",
-    facts: "fact",
-    lessons: "lesson",
-    sessions: "session",
-    instructions: "instruction",
-    scripts: "script",
-    env: "env",
-    secrets: "secret",
-    tasks: "task",
-};
+function declaredTypeFor(entry) {
+    if (entry.adapterId !== "akm" || !entry.root)
+        return undefined;
+    const rel = path.relative(entry.root, entry.filePath);
+    if (rel === "" || rel.startsWith("..") || path.isAbsolute(rel))
+        return undefined;
+    return declaredTypeForPath(buildFileContext(entry.root, entry.filePath));
+}
 const realReadFile = (absPath) => {
     try {
         return fs.readFileSync(absPath, "utf8");
@@ -52,31 +45,6 @@ const realReadFile = (absPath) => {
         return undefined;
     }
 };
-/**
- * The type a file's directory declares, mirroring the `classifyByDirectory` /
- * `classifyByParentDirHint` precedence in matchers.ts: the immediate parent
- * directory wins when it is itself typed (parentDirHint, specificity 15);
- * otherwise the outermost typed ancestor wins (directoryMatcher, specificity
- * 10, which walks root-to-leaf and returns on the first hit).
- */
-function declaredTypeForPath(absPath) {
-    const segments = path
-        .dirname(absPath)
-        .split(path.sep)
-        .filter((seg) => seg.length > 0);
-    const immediateParent = segments.at(-1);
-    if (immediateParent) {
-        const parentType = DECLARED_DIR_TYPES[immediateParent];
-        if (parentType)
-            return { dir: immediateParent, type: parentType };
-    }
-    for (const seg of segments) {
-        const type = DECLARED_DIR_TYPES[seg];
-        if (type)
-            return { dir: seg, type };
-    }
-    return undefined;
-}
 /**
  * Best-effort explanation for why `classifyBySmartMd` (matchers.ts) would
  * have produced `resolvedType` for this content, in the SAME precedence
@@ -110,7 +78,7 @@ function explainOverride(resolvedType, content) {
 }
 /**
  * Compare every indexed entry's resolved type against the type its
- * directory declares (see {@link DECLARED_DIR_TYPES}), and return one
+ * directory declares (see {@link declaredTypeFor}), and return one
  * {@link TypeDirectoryDisagreement} per mismatch, sorted by path. Entries
  * outside any declared-type directory are not checked — this is only the
  * "directory declares type" invariant.
@@ -118,15 +86,15 @@ function explainOverride(resolvedType, content) {
 export function collectTypeDirectoryDisagreements(entries, readFile = realReadFile) {
     const disagreements = [];
     for (const entry of entries) {
-        const declared = declaredTypeForPath(entry.filePath);
-        if (!declared || declared.type === entry.type)
+        const declared = declaredTypeFor(entry);
+        if (!declared || declared === entry.type)
             continue;
         const content = readFile(entry.filePath);
         const explanation = content === undefined ? undefined : explainOverride(entry.type, content);
         disagreements.push({
             path: entry.filePath,
             resolved: entry.type,
-            expected: declared.type,
+            expected: declared,
             winner: explanation?.winner ?? "unknown",
             knownGoodOverride: explanation?.knownGoodOverride ?? false,
         });

package/dist/commands/health.js

@@ -10,6 +10,7 @@ import { classifyPathAccess, describeInaccessiblePath } from "../core/path-acces
 import { getConfigPath, getDataDir, getDbPath, getStateDbPathInDataDir } from "../core/paths.js";
 import { listExistingTableNames, listPendingStateMigrations, openStateDatabaseWithReport, withStateDb, } from "../core/state-db.js";
 import { DURATION_UNITS, parseDuration, parseSinceToIso } from "../core/time.js";
+import { resolveSourceEntries } from "../indexer/search/search-source.js";
 import { probeLlmEndpoint } from "../llm/client.js";
 import { openDatabase } from "../storage/database.js";
 import { insertEvent } from "../storage/repositories/events-repository.js";
@@ -251,24 +252,36 @@ function gatherAncillaryAdvisories(db, options, egressConfigView) {
     const indexStateMismatch = detectIndexStateGenerationMismatch(db);
     if (indexStateMismatch)
         advisories.push(indexStateMismatch);
-    // Surface a `stash-git-exposure` advisory when env/secret assets are
-    // git-tracked AND a remote is configured (the leak moment). Best-effort.
-    // Cheap guard: only shell out to git when the stash has its OWN `.git` (or a
-    // test injected a fake seam), so the hot path never spawns for a non-git
-    // stash — the common unit-test case. Trade-off: a stash manually pointed at a
-    // bare subdirectory of a parent git repo (no `.git` of its own) is not
-    // checked. akm-init always creates `.git` at the stash root, so any
-    // akm-initialised stash is covered; this only skips hand-pointed nested ones.
+    // Surface a `stash-git-exposure` advisory for each bundle whose env/secret
+    // assets are git-tracked AND that has a remote (the leak moment). Every
+    // configured bundle is checked, not just the working stash; each honours the
+    // intentional-tracking marker in its own `.gitignore`. Best-effort.
+    // Cheap guard: only shell out to git for a bundle root with its OWN `.git`
+    // (or when a test injected a fake seam), so the hot path never spawns for
+    // non-git bundles. Trade-off: a bundle pointed at a bare subdirectory of a
+    // parent git repo (no `.git` of its own) is not checked; akm-init and
+    // writable git installs put `.git` at the bundle root.
+    let exposureRoots = [];
     try {
         const exposureStashDir = options.stashDir ?? resolveStashDir();
-        if (options.stashExposureGit || fs.existsSync(path.join(exposureStashDir, ".git"))) {
-            const stashExposure = collectStashExposureAdvisory(exposureStashDir, options.stashExposureGit);
-            if (stashExposure)
-                advisories.push(stashExposure);
-        }
+        exposureRoots = [exposureStashDir];
+        exposureRoots = resolveSourceEntries(exposureStashDir).map((source) => source.path);
     }
     catch {
-        // Non-fatal — a git/probe failure must not abort the health report.
+        // An unreadable working stash skips the advisory; an unreadable bundle
+        // config still checks the working stash. Neither aborts the report.
+    }
+    for (const root of new Set(exposureRoots.map((dir) => path.resolve(dir)))) {
+        try {
+            if (options.stashExposureGit || fs.existsSync(path.join(root, ".git"))) {
+                const stashExposure = collectStashExposureAdvisory(root, options.stashExposureGit);
+                if (stashExposure)
+                    advisories.push(stashExposure);
+            }
+        }
+        catch {
+            // Non-fatal — a git/probe failure must not abort the health report.
+        }
     }
     // 08 surfaces: the remaining read-only advisory group (binary-config-skew,
     // egress-endpoints). Best-effort — a filesystem probe failure must not abort
@@ -346,7 +359,24 @@ function detectTypeDirectoryDisagreements(stashRoot) {
         indexDb = openReadonlyExistingDatabase(getDbPath());
         if (!indexDb)
             return undefined;
-        const entries = getAllEntries(indexDb).map((entry) => ({ filePath: entry.filePath, type: entry.type }));
+        // Directory intent is read only from inside the component root that owns the entry.
+        // Both spellings of each root: indexed paths may be realpaths (a symlinked
+        // stash, macOS /var -> /private/var) while config holds the configured path.
+        const roots = resolveSourceEntries(stashRoot).flatMap((source) => {
+            const resolved = path.resolve(source.path);
+            try {
+                return [resolved, fs.realpathSync.native(resolved)];
+            }
+            catch {
+                return [resolved];
+            }
+        });
+        const entries = getAllEntries(indexDb).map((entry) => ({
+            filePath: entry.filePath,
+            type: entry.type,
+            adapterId: entry.adapterId,
+            root: roots.filter((root) => entry.filePath.startsWith(root + path.sep)).sort((a, b) => b.length - a.length)[0] ?? "",
+        }));
         return buildTypeDirectoryAdvisory(entries, undefined, (absPath) => absPath.startsWith(stashRoot) ? path.relative(stashRoot, absPath) : absPath);
     }
     catch {

package/dist/commands/metrics/collect.js

@@ -4,6 +4,7 @@
 import { decodeLlmUsageRecord } from "../../llm/usage-telemetry.js";
 import { decodeTaskHistoryMetadata } from "../../storage/repositories/task-history-repository.js";
 import { computeWallTimeStats } from "../health/improve-metrics.js";
+import { hasTokenUsage } from "../health/llm-usage.js";
 import { computeValenceScore } from "../improve/feedback-valence.js";
 const DAY_MS = 86_400_000;
 /** Utility is a score in [0, 1], reported in ten equal buckets. */
@@ -111,6 +112,8 @@ export function llmRowsFromEvents(events) {
                 completionTokens: 0,
                 totalTokens: 0,
                 reasoningTokens: 0,
+                usageCalls: 0,
+                reasoningCalls: 0,
             };
             rows.set(key, row);
         }
@@ -121,6 +124,10 @@ export function llmRowsFromEvents(events) {
         // A call without a total counts as prompt + completion, as the dashboard did per call.
         row.totalTokens += record.totalTokens ?? (record.promptTokens ?? 0) + (record.completionTokens ?? 0);
         row.reasoningTokens += record.reasoningTokens ?? 0;
+        if (hasTokenUsage(record))
+            row.usageCalls += 1;
+        if (record.reasoningTokens !== undefined)
+            row.reasoningCalls += 1;
     }
     return [...rows.values()];
 }
@@ -260,10 +267,11 @@ function buildUsage(input, rows) {
             curates,
             selects: input.selects.length,
             zeroResultSearches,
+            searchesWithHits,
             distinctAssets: assets.size,
             distinctQueries: queries.size,
         },
-        selectRate: searchesWithHits > 0 ? input.selects.length / searchesWithHits : null,
+        selectsPerSearch: searchesWithHits > 0 ? input.selects.length / searchesWithHits : null,
         searchMedianMs: median(searchMs),
         daily: [...days.values()].sort((a, b) => a.day.localeCompare(b.day)),
         topAssets: [...assets.values()]

package/dist/commands/metrics/metrics-cli.js

@@ -131,7 +131,7 @@ export async function akmMetrics(options = {}) {
     if (index.note)
         notes.push(index.note);
     const filter = { sinceIso, untilIso, source: SOURCE };
-    notes.push("Selects come from the events stream, which records no source, so they are counted for every source.");
+    notes.push("Selects come from the events stream, which records no source or search id, so they are counted for every source and selects per search is a ratio, not a conversion rate.");
     const input = {
         window: { since: sinceIso, until: untilIso },
         source: SOURCE,

package/dist/commands/metrics/report-view.js

@@ -20,18 +20,27 @@ function sourceFacts(counts) {
     const entries = Object.entries(counts);
     return entries.length === 0 ? "-" : entries.map(([k, v]) => `${k}=${v}`).join(" ");
 }
+/** A token sum, or `unknown` when calls were made and none reported usage (never a measured zero). */
+function tokens(n, a) {
+    return a.calls > 0 && a.usageCalls === 0 ? "unknown" : int(n);
+}
+/** `reported/calls`; `-` for an aggregate that carries no coverage. */
+function usageCoverage(a) {
+    return a.usageCalls === undefined ? "-" : `${a.usageCalls}/${a.calls}`;
+}
 function llmRows(group) {
     return Object.entries(group).map(([name, a]) => [
         name,
         int(a.calls),
         int(a.failures),
-        int(a.promptTokens),
-        int(a.completionTokens),
-        int(a.totalTokens),
+        tokens(a.promptTokens, a),
+        tokens(a.completionTokens, a),
+        tokens(a.totalTokens, a),
+        usageCoverage(a),
         ms(a.totalDurationMs),
     ]);
 }
-const LLM_HEADERS = ["name", "calls", "failed", "prompt", "completion", "total", "time"];
+const LLM_HEADERS = ["name", "calls", "failed", "prompt", "completion", "total", "calls with usage", "time"];
 export function buildMetricsView(r, detail) {
     const brief = detail === "brief";
     const cut = (items) => (brief ? items.slice(0, BRIEF_LIST_LIMIT) : items);
@@ -45,7 +54,8 @@ export function buildMetricsView(r, detail) {
                 ["shows", int(usage.totals.shows)],
                 ["curates", int(usage.totals.curates)],
                 ["selects", int(usage.totals.selects)],
-                ["select rate", pct(usage.selectRate)],
+                ["searches with hits", int(usage.totals.searchesWithHits)],
+                ["selects per search with hits", fixed(usage.selectsPerSearch, 2)],
                 [
                     "zero-result searches",
                     `${usage.totals.zeroResultSearches} (${pct(searches === 0 ? null : usage.totals.zeroResultSearches / searches)})`,
@@ -154,10 +164,11 @@ export function buildMetricsView(r, detail) {
             facts: [
                 ["calls", int(llm.calls)],
                 ["failed", int(llm.failures)],
-                ["prompt tokens", int(llm.promptTokens)],
-                ["completion tokens", int(llm.completionTokens)],
-                ["reasoning tokens", int(llm.reasoningTokens)],
-                ["total tokens", int(llm.totalTokens)],
+                ["calls with token usage", usageCoverage(llm)],
+                ["prompt tokens", tokens(llm.promptTokens, llm)],
+                ["completion tokens", tokens(llm.completionTokens, llm)],
+                ["reasoning tokens", llm.calls > 0 && llm.reasoningCalls === 0 ? "unknown" : tokens(llm.reasoningTokens, llm)],
+                ["total tokens", tokens(llm.totalTokens, llm)],
                 ["time", ms(llm.totalDurationMs)],
             ],
             tables: [

package/dist/commands/sources/plugin-channels.js

@@ -0,0 +1,147 @@
+// 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 fs from "node:fs";
+import path from "node:path";
+import { isDeepStrictEqual } from "node:util";
+import { applyEdits, modify } from "jsonc-parser";
+import { parse as parseToml } from "smol-toml";
+import { existingFileMode, parseJsonc, timestampForFilename, writeFileAtomic } from "../../core/common.js";
+/** Preserve unrelated settings and comments; only the named native key changes. */
+export function editChannelJson(file, keys, value, content) {
+    const before = content ?? fs.readFileSync(file, "utf8");
+    parseJsonc(before);
+    const after = applyEdits(before, modify(before, keys, value, { formattingOptions: { insertSpaces: true, tabSize: 2 } }));
+    parseJsonc(after);
+    return { file, content: after };
+}
+export function backupChannelFile(file) {
+    const backup = `${file}.akm-channel-${timestampForFilename()}-${process.pid}.bak`;
+    fs.copyFileSync(file, backup, fs.constants.COPYFILE_EXCL);
+    fs.chmodSync(backup, existingFileMode(file) ?? 0o600);
+    return backup;
+}
+export class ChannelWriteError extends Error {
+    backups;
+    writtenFiles;
+    constructor(cause, backups, writtenFiles) {
+        super(`Channel settings could not all be written: ${String(cause)}. Backups: ${backups.join(", ") || "none"}`);
+        this.backups = backups;
+        this.writtenFiles = writtenFiles;
+    }
+}
+export function writeChannelEdits(edits) {
+    const backups = [];
+    const writtenFiles = [];
+    try {
+        const changed = edits.filter(({ file, content }) => fs.readFileSync(file, "utf8") !== content);
+        for (const { file } of changed)
+            backups.push(backupChannelFile(file));
+        for (const { file, content } of changed) {
+            writeFileAtomic(file, content, existingFileMode(file));
+            writtenFiles.push(file);
+        }
+        return backups;
+    }
+    catch (error) {
+        throw new ChannelWriteError(error, backups, writtenFiles);
+    }
+}
+/** Claude has no command to change a registered marketplace's ref in place. Never remove the marketplace. */
+export function claudeChannelEdits(configDir, pluginsRoot, channel, projectPaths = []) {
+    const ref = channel === "next" ? "next" : undefined;
+    const knownFile = path.join(pluginsRoot, "known_marketplaces.json");
+    const known = parseJsonc(fs.readFileSync(knownFile, "utf8"));
+    const source = known["akm-plugins"]?.source;
+    if (!source || !["github", "git"].includes(source.source ?? "")) {
+        throw new Error("the akm-plugins marketplace has no Git source whose channel can be switched");
+    }
+    const edits = [editChannelJson(knownFile, ["akm-plugins", "source", "ref"], ref)];
+    const settingsFiles = [
+        path.join(configDir, "settings.json"),
+        ...[process.cwd(), ...projectPaths].flatMap((project) => [
+            path.join(project, ".claude", "settings.json"),
+            path.join(project, ".claude", "settings.local.json"),
+        ]),
+    ];
+    for (const file of new Set(settingsFiles)) {
+        if (!fs.existsSync(file))
+            continue;
+        const settings = parseJsonc(fs.readFileSync(file, "utf8"));
+        if (!settings.extraKnownMarketplaces?.["akm-plugins"])
+            continue;
+        edits.push(editChannelJson(file, ["extraKnownMarketplaces", "akm-plugins", "source", "ref"], ref));
+    }
+    return edits;
+}
+/** Read native TOML, including quoted keys and inline tables. */
+export function codexMarketplace(file) {
+    const config = parseToml(fs.readFileSync(file, "utf8"));
+    const marketplaces = config.marketplaces;
+    const marketplace = marketplaces?.["akm-plugins"];
+    return marketplace && typeof marketplace === "object" ? marketplace : undefined;
+}
+/** Codex's add refuses a changed ref on an existing source; preserve the installed plugin and edit only its ref. */
+export function codexChannelEdit(file, channel) {
+    const before = fs.readFileSync(file, "utf8");
+    const expected = parseToml(before);
+    const entry = expected.marketplaces?.["akm-plugins"];
+    if (!entry || entry.source_type !== "git")
+        throw new Error("the akm-plugins marketplace has no Git source whose channel can be switched");
+    if (channel === "next")
+        entry.ref = "next";
+    else
+        delete entry.ref;
+    const headers = [...before.matchAll(/^[ \t]*\[(?!\[)([^\]\r\n]+)\][ \t]*(?:#[^\r\n]*)?\r?$/gm)];
+    let after = before;
+    let edited = false;
+    for (const [index, header] of headers.entries()) {
+        let parsed;
+        try {
+            parsed = parseToml(`[${header[1]}]`);
+        }
+        catch {
+            continue;
+        }
+        const target = parsed.marketplaces?.["akm-plugins"];
+        if (!target || Object.keys(target).length !== 0)
+            continue;
+        const start = header.index + header[0].length;
+        const end = headers[index + 1]?.index ?? before.length;
+        const section = before.slice(start, end);
+        const refLine = /^[ \t]*(?:ref|"ref"|'ref')[ \t]*=[ \t]*(?:"(?:\\.|[^"\\])*"|'[^']*')([ \t]*(?:#[^\r\n]*)?)(\r?\n|$)/m;
+        const newline = before.includes("\r\n") ? "\r\n" : "\n";
+        const nextSection = refLine.test(section)
+            ? section.replace(refLine, (_line, comment, end) => channel === "next" ? `ref = "next"${comment}${end}` : comment.trim() ? `${comment.trimStart()}${end}` : "")
+            : channel === "next"
+                ? `${newline}ref = "next"${section}`
+                : section;
+        after = before.slice(0, start) + nextSection + before.slice(end);
+        edited = true;
+        break;
+    }
+    if (!edited) {
+        // Inline tables have no section to insert into. Change just this table's ref and retain every other byte.
+        const inline = /((?:"akm-plugins"|'akm-plugins'|akm-plugins)\s*=\s*\{)([^\n]*?)(\})/g;
+        for (const match of before.matchAll(inline)) {
+            const [, open, body, close] = match;
+            const ref = /(?:^|,)\s*(?:ref|"ref"|'ref')\s*=\s*(?:"(?:\\.|[^"\\])*"|'[^']*')\s*/;
+            const stripped = body.replace(ref, "").replace(/^\s*,/, "");
+            const next = channel === "next" ? `${stripped.trimEnd()}${stripped.trim() ? ", " : ""}ref = "next" ` : stripped;
+            const candidate = before.slice(0, match.index) + `${open}${next}${close}` + before.slice(match.index + match[0].length);
+            try {
+                if (isDeepStrictEqual(parseToml(candidate), expected)) {
+                    after = candidate;
+                    break;
+                }
+            }
+            catch {
+                /* Try the next table with this name. */
+            }
+        }
+    }
+    // Validate the whole semantic document: an unusual layout is never partially rewritten.
+    if (!isDeepStrictEqual(parseToml(after), expected))
+        throw new Error("could not locate only the akm-plugins ref in Codex config.toml; no settings were changed");
+    return { file, content: after };
+}