akm-cli 0.7.4 → 0.8.0-rc.3

package/dist/indexer/ranking-contributors.js

@@ -0,0 +1,204 @@
+import { computeGraphBoost } from "./graph-boost";
+const TYPE_BOOST = {
+    skill: 0.4,
+    command: 0.35,
+    workflow: 0.35,
+    agent: 0.3,
+    script: 0.2,
+    knowledge: 0.22,
+    memory: -0.02,
+};
+const MAX_BOOST_SUM = 3.0;
+const UTILITY_WEIGHT = 0.5;
+const UTILITY_MAX_BOOST = 1.5;
+const RECENCY_DECAY_DAYS = 30;
+function beliefStateBoost(item) {
+    const entry = item.entry;
+    if (entry.type !== "memory")
+        return 0;
+    if (entry.beliefState === "contradicted")
+        return -0.45;
+    if (entry.beliefState === "superseded")
+        return -0.25;
+    if (entry.beliefState === "archived")
+        return -0.6;
+    if (entry.beliefState === "active")
+        return 0.06;
+    return 0;
+}
+const exactNameRankingContributor = {
+    name: "exact-name-ranking",
+    appliesTo: () => true,
+    adjust(item, ctx) {
+        const entry = item.entry;
+        const nameLower = entry.name.toLowerCase();
+        const rawNameBase = nameLower.split("/").pop() ?? nameLower;
+        const nameBase = entry.type === "memory" && rawNameBase.endsWith(".derived")
+            ? rawNameBase.slice(0, -".derived".length)
+            : rawNameBase;
+        if (nameBase === ctx.queryLower || nameLower === ctx.queryLower) {
+            return 2.0;
+        }
+        if (nameBase.includes(ctx.queryLower) || ctx.queryLower.includes(nameBase)) {
+            return 1.0;
+        }
+        const nameTokens = nameBase.split(/[-_\s]+/).filter(Boolean);
+        const matchCount = ctx.queryTokens.filter((qt) => nameTokens.some((nt) => nt === qt || nt.includes(qt))).length;
+        return matchCount > 0 ? Math.min(0.9, matchCount * 0.3) : 0;
+    },
+};
+const typeRankingContributor = {
+    name: "type-ranking",
+    appliesTo: () => true,
+    adjust(item) {
+        return TYPE_BOOST[item.entry.type] ?? 0;
+    },
+};
+const memoryRankingContributor = {
+    name: "memory-ranking",
+    appliesTo(item) {
+        return item.entry.type === "memory";
+    },
+    adjust(item) {
+        const derivedBoost = item.entry.name.toLowerCase().endsWith(".derived") ? 0.12 : -0.08;
+        return derivedBoost + beliefStateBoost(item);
+    },
+};
+const tagRankingContributor = {
+    name: "tag-ranking",
+    appliesTo(item) {
+        return Array.isArray(item.entry.tags) && item.entry.tags.length > 0;
+    },
+    adjust(item, ctx) {
+        let tagBoost = 0;
+        for (const tag of item.entry.tags ?? []) {
+            if (ctx.queryTokens.some((token) => tag.toLowerCase() === token))
+                tagBoost += 0.15;
+        }
+        return Math.min(0.3, tagBoost);
+    },
+};
+const searchHintRankingContributor = {
+    name: "search-hint-ranking",
+    appliesTo(item) {
+        return Array.isArray(item.entry.searchHints) && item.entry.searchHints.length > 0;
+    },
+    adjust(item, ctx) {
+        let hintBoost = 0;
+        for (const hint of item.entry.searchHints ?? []) {
+            const hintLower = hint.toLowerCase();
+            for (const token of ctx.queryTokens) {
+                if (hintLower.includes(token)) {
+                    hintBoost += 0.12;
+                    break;
+                }
+            }
+        }
+        return Math.min(0.24, hintBoost);
+    },
+};
+const aliasRankingContributor = {
+    name: "alias-ranking",
+    appliesTo(item) {
+        return Array.isArray(item.entry.aliases) && item.entry.aliases.length > 0;
+    },
+    adjust(item, ctx) {
+        let boost = 0;
+        for (const alias of item.entry.aliases ?? []) {
+            const aliasLower = alias.toLowerCase();
+            if (aliasLower === ctx.queryLower) {
+                boost += 1.5;
+                break;
+            }
+            if (ctx.queryTokens.some((token) => aliasLower.includes(token)))
+                boost += 0.3;
+        }
+        return boost;
+    },
+};
+const descriptionRankingContributor = {
+    name: "description-ranking",
+    appliesTo(item) {
+        return typeof item.entry.description === "string" && item.entry.description.length > 0;
+    },
+    adjust(item, ctx) {
+        const descLower = item.entry.description?.toLowerCase() ?? "";
+        const descMatchCount = ctx.queryTokens.filter((token) => descLower.includes(token)).length;
+        if (descMatchCount === ctx.queryTokens.length && ctx.queryTokens.length > 1)
+            return 0.25;
+        if (descMatchCount > 0)
+            return 0.1;
+        return 0;
+    },
+};
+const metadataRankingContributor = {
+    name: "metadata-ranking",
+    appliesTo: () => true,
+    adjust(item) {
+        let boost = item.entry.quality === "curated" ? 0.05 : 0;
+        if (typeof item.entry.confidence === "number") {
+            boost += Math.min(0.05, Math.max(0, item.entry.confidence) * 0.05);
+        }
+        return boost;
+    },
+};
+const graphRankingContributor = {
+    name: "graph-ranking",
+    appliesTo(_item, ctx) {
+        return ctx.graphContext !== null;
+    },
+    adjust(item, ctx) {
+        return ctx.graphContext ? computeGraphBoost(ctx.graphContext, item.filePath) : 0;
+    },
+};
+const utilityRankingContributor = {
+    name: "utility-ranking",
+    appliesTo(item, ctx) {
+        const utilScore = ctx.utilityScores.get(item.id);
+        return Boolean(utilScore && utilScore.utility > 0);
+    },
+    apply(item, ctx) {
+        const utilScore = ctx.utilityScores.get(item.id);
+        if (!utilScore || utilScore.utility <= 0)
+            return;
+        let recencyFactor = 1;
+        if (utilScore.lastUsedAt) {
+            const lastUsedMs = new Date(utilScore.lastUsedAt).getTime();
+            const daysSinceLastUse = Number.isNaN(lastUsedMs)
+                ? Infinity
+                : Math.max(0, (Date.now() - lastUsedMs) / (1000 * 60 * 60 * 24));
+            recencyFactor = Math.exp(-daysSinceLastUse / RECENCY_DECAY_DAYS);
+        }
+        const rawBoost = 1 + utilScore.utility * recencyFactor * UTILITY_WEIGHT;
+        item.score *= Math.min(rawBoost, UTILITY_MAX_BOOST);
+        item.utilityBoosted = true;
+    },
+};
+export const defaultRankingContributors = [
+    exactNameRankingContributor,
+    typeRankingContributor,
+    memoryRankingContributor,
+    tagRankingContributor,
+    searchHintRankingContributor,
+    aliasRankingContributor,
+    descriptionRankingContributor,
+    metadataRankingContributor,
+    graphRankingContributor,
+];
+export const defaultUtilityRankingContributors = [utilityRankingContributor];
+export function applyScoreContributors(item, ctx, contributors = defaultRankingContributors) {
+    let boostSum = 0;
+    for (const contributor of contributors) {
+        if (!contributor.appliesTo(item, ctx))
+            continue;
+        boostSum += contributor.adjust(item, ctx);
+    }
+    item.score *= 1 + Math.min(boostSum, MAX_BOOST_SUM);
+}
+export function applyUtilityContributors(item, ctx, contributors = defaultUtilityRankingContributors) {
+    for (const contributor of contributors) {
+        if (!contributor.appliesTo(item, ctx))
+            continue;
+        contributor.apply(item, ctx);
+    }
+}

package/dist/indexer/ranking.js

@@ -0,0 +1,74 @@
+import { getUtilityScoresByIds } from "./db";
+import { applyScoreContributors, applyUtilityContributors } from "./ranking-contributors";
+export function normalizeFtsScores(results) {
+    const ftsScoreMap = new Map();
+    if (results.length === 0)
+        return ftsScoreMap;
+    const bestBm25 = results[0].bm25Score;
+    const worstBm25 = results[results.length - 1].bm25Score;
+    const range = bestBm25 - worstBm25;
+    for (const result of results) {
+        const normalized = range !== 0 ? (result.bm25Score - worstBm25) / range : 1.0;
+        const ftsScore = 0.3 + normalized * 0.7;
+        ftsScoreMap.set(result.id, { score: ftsScore, result });
+    }
+    return ftsScoreMap;
+}
+export function combineSearchScores(options) {
+    const FTS_WEIGHT = 0.7;
+    const VEC_WEIGHT = 0.3;
+    const scored = [];
+    const seenIds = new Set();
+    for (const [id, { score: ftsScore, result }] of options.ftsScoreMap) {
+        seenIds.add(id);
+        const embedScore = options.embedScoreMap.get(id);
+        const combinedScore = embedScore !== undefined ? ftsScore * FTS_WEIGHT + embedScore * VEC_WEIGHT : ftsScore;
+        scored.push({
+            id,
+            entry: result.entry,
+            filePath: result.filePath,
+            score: combinedScore,
+            rankingMode: embedScore !== undefined ? "hybrid" : "fts",
+        });
+    }
+    for (const [id, cosine] of options.embedScoreMap) {
+        if (seenIds.has(id))
+            continue;
+        const found = options.getEntryById(id);
+        if (!found)
+            continue;
+        if (options.typeFilter && found.entry.type !== options.typeFilter)
+            continue;
+        scored.push({
+            id,
+            entry: found.entry,
+            filePath: found.filePath,
+            score: cosine * VEC_WEIGHT,
+            rankingMode: "semantic",
+        });
+    }
+    return scored;
+}
+export function applyRankingRules(options) {
+    const queryTokens = options.query.toLowerCase().split(/\s+/).filter(Boolean);
+    const queryLower = options.query.toLowerCase().trim();
+    const rankingContext = {
+        db: options.db,
+        query: options.query,
+        queryLower,
+        queryTokens,
+        graphContext: options.graphContext,
+    };
+    for (const item of options.items) {
+        applyScoreContributors(item, rankingContext);
+    }
+    const utilScoresMap = getUtilityScoresByIds(options.db, options.items.map((item) => item.id));
+    const utilityContext = {
+        ...rankingContext,
+        utilityScores: utilScoresMap,
+    };
+    for (const item of options.items) {
+        applyUtilityContributors(item, utilityContext);
+    }
+    return options.items;
+}

package/dist/indexer/search-hit-enrichers.js

@@ -0,0 +1,22 @@
+import { getRenderer } from "./file-context";
+const rendererSearchHitEnricher = {
+    name: "renderer-search-hit-enricher",
+    appliesTo(ctx) {
+        return ctx.rendererRegistry.rendererNameFor(ctx.type) !== undefined;
+    },
+    async enrich(hit, ctx) {
+        const rendererName = ctx.rendererRegistry.rendererNameFor(ctx.type);
+        if (!rendererName)
+            return;
+        const renderer = await getRenderer(rendererName);
+        renderer?.enrichSearchHit?.(hit, ctx.stashDir);
+    },
+};
+export const defaultSearchHitEnrichers = [rendererSearchHitEnricher];
+export async function enrichSearchHit(hit, ctx, enrichers = defaultSearchHitEnrichers) {
+    for (const enricher of enrichers) {
+        if (!enricher.appliesTo(ctx))
+            continue;
+        await enricher.enrich(hit, ctx);
+    }
+}

package/dist/indexer/search-source.js

@@ -1,7 +1,7 @@
 import fs from "node:fs";
 import path from "node:path";
 import { resolveStashDir } from "../core/common";
-import { loadConfig } from "../core/config";
+import { getSources, loadConfig } from "../core/config";
 import { resolveSourceProviderFactory } from "../sources/provider-factory";
 // Eager side-effect imports so all built-in source providers self-register
 // before resolveEntryContentDir() runs.
@@ -21,7 +21,7 @@ const GIT_STASH_TYPES = new Set(["git"]);
  *   1. The primary stash directory (the entry marked `primary: true`, or the
  *      legacy top-level `stashDir`). Always emitted, even when the directory
  *      does not yet exist on disk, so callers can use it as the clone target.
- *   2. Each entry in `config.sources ?? config.stashes[]` (in declared order), excluding the
+ *   2. Each entry in `config.sources[]` (in declared order), excluding the
  *      one already emitted as the primary.
  *   3. Each entry in `config.installed[]` (registry-managed stashes).
  *
@@ -32,9 +32,10 @@ const GIT_STASH_TYPES = new Set(["git"]);
 export function resolveSourceEntries(overrideStashDir, existingConfig) {
     const stashDir = overrideStashDir ?? resolveStashDir();
     const config = existingConfig ?? loadConfig();
-    const sources = [{ path: stashDir }];
+    // Primary stash is always writable.
+    const sources = [{ path: stashDir, writable: true }];
     const seen = new Set([path.resolve(stashDir)]);
-    const addSource = (dir, registryId, wikiName) => {
+    const addSource = (dir, registryId, wikiName, writable) => {
         const resolved = path.resolve(dir);
         if (seen.has(resolved))
             return;
@@ -47,13 +48,14 @@ export function resolveSourceEntries(overrideStashDir, existingConfig) {
                 path: resolved,
                 ...(registryId ? { registryId } : {}),
                 ...(wikiName ? { wikiName } : {}),
+                ...(writable ? { writable: true } : {}),
             });
         }
     };
     // (1) + (2) Single pass over declared stashes — primary first if present,
     // then the rest in declared order. The primary's directory is already
     // injected as `sources[0]` above, so we only need to dedupe the source set.
-    const stashes = config.sources ?? config.stashes ?? [];
+    const stashes = getSources(config);
     const primaryIdx = stashes.findIndex((entry) => entry.primary === true);
     const ordered = [];
     if (primaryIdx >= 0) {
@@ -72,11 +74,12 @@ export function resolveSourceEntries(overrideStashDir, existingConfig) {
         const dir = resolveEntryContentDir(entry);
         if (dir == null)
             continue;
-        addSource(dir, entry.name, entry.wikiName);
+        addSource(dir, entry.name, entry.wikiName, entry.writable === true);
     }
     // (3) Installed stashes (registry-managed). Always last.
+    // Only installed entries explicitly marked writable: true are considered writable.
     for (const entry of config.installed ?? []) {
-        addSource(entry.stashRoot, entry.id, entry.wikiName);
+        addSource(entry.stashRoot, entry.id, entry.wikiName, entry.writable === true);
     }
     return sources;
 }
@@ -132,6 +135,19 @@ function resolveEntryContentDir(entry) {
 export function resolveAllStashDirs(overrideStashDir) {
     return resolveSourceEntries(overrideStashDir).map((s) => s.path);
 }
+/**
+ * Return the resolved absolute paths of all writable stash sources.
+ *
+ * The primary stash is always writable. Filesystem/git sources that have
+ * `writable: true` in config are also included. Registry-cached sources
+ * (installed without `writable: true`) are excluded because they are
+ * overwritten on `akm update` and must never be mutated.
+ */
+export function getWritableStashDirs(overrideStashDir, existingConfig) {
+    return resolveSourceEntries(overrideStashDir, existingConfig)
+        .filter((s) => s.writable === true)
+        .map((s) => s.path);
+}
 /**
  * Find which source a file path belongs to.
  */
@@ -226,8 +242,7 @@ function isValidDirectory(dir) {
 export async function ensureSourceCaches(config, options) {
     const cfg = config ?? loadConfig();
     const force = options?.force === true;
-    // Use sources[] (current key) with fallback to stashes[] (deprecated, one-release compat).
-    const entries = cfg.sources ?? cfg.stashes ?? [];
+    const entries = getSources(cfg);
     for (const entry of entries) {
         if (!GIT_STASH_TYPES.has(entry.type) || !entry.url || entry.enabled === false)
             continue;

package/dist/indexer/semantic-status.js

@@ -1,5 +1,5 @@
 import fs from "node:fs";
-import path from "node:path";
+import { writeFileAtomic } from "../core/common";
 import { getCacheDir, getSemanticStatusPath } from "../core/paths";
 import { DEFAULT_LOCAL_MODEL } from "../llm/embedder";
 export function deriveSemanticProviderFingerprint(embedding) {
@@ -41,21 +41,7 @@ export function readSemanticStatus() {
 export function writeSemanticStatus(status) {
     const dir = getCacheDir();
     fs.mkdirSync(dir, { recursive: true });
-    const filePath = getSemanticStatusPath();
-    const tmpPath = path.join(dir, `semantic-status.json.tmp.${process.pid}.${Math.random().toString(36).slice(2)}`);
-    fs.writeFileSync(tmpPath, `${JSON.stringify(status, null, 2)}\n`, "utf8");
-    try {
-        fs.renameSync(tmpPath, filePath);
-    }
-    catch (err) {
-        try {
-            fs.unlinkSync(tmpPath);
-        }
-        catch {
-            /* ignore cleanup failure */
-        }
-        throw err;
-    }
+    writeFileAtomic(getSemanticStatusPath(), `${JSON.stringify(status, null, 2)}\n`);
 }
 export function clearSemanticStatus() {
     try {

package/dist/indexer/walker.js

@@ -136,6 +136,31 @@ function isInsideGitRepo(dir) {
     }
     return false;
 }
+/**
+ * Recursively yield every `.md` file under `root`.
+ *
+ * Shared by graph-extraction and memory-inference so the generator logic
+ * lives in exactly one place. Silently skips directories that cannot be
+ * read (e.g. permission errors).
+ */
+export function* walkMarkdownFiles(root) {
+    let entries;
+    try {
+        entries = fs.readdirSync(root, { withFileTypes: true });
+    }
+    catch {
+        return;
+    }
+    for (const entry of entries) {
+        const full = path.join(root, entry.name);
+        if (entry.isDirectory()) {
+            yield* walkMarkdownFiles(full);
+        }
+        else if (entry.isFile() && entry.name.toLowerCase().endsWith(".md")) {
+            yield full;
+        }
+    }
+}
 /** Manual walk for non-git directories. */
 function walkStashManual(stashRoot) {
     const results = [];

package/dist/integrations/agent/builders.js

@@ -0,0 +1,109 @@
+/**
+ * Agent command builder strategy (v1 spec §12.2).
+ *
+ * Each supported agent CLI platform has its own `AgentCommandBuilder` that
+ * translates a platform-agnostic `AgentDispatchRequest` into the exact argv
+ * the CLI expects. This keeps all per-platform arg differences out of the
+ * spawn wrapper and profiles.
+ *
+ * Adding a new platform: implement `AgentCommandBuilder`, add to
+ * `BUILTIN_BUILDERS`. Nothing else changes.
+ */
+import { resolveModel } from "./model-aliases";
+// ── Tool normalization ────────────────────────────────────────────────────────
+/**
+ * Normalize a toolPolicy value to a comma-separated string suitable for a
+ * CLI flag. Structured policy objects are JSON-serialized.
+ */
+function normalizeTools(tools) {
+    if (typeof tools === "string")
+        return tools;
+    if (Array.isArray(tools))
+        return tools.join(",");
+    return JSON.stringify(tools);
+}
+// ── Platform builders ─────────────────────────────────────────────────────────
+/**
+ * OpenCode builder.
+ * Command shape: opencode run [--system-prompt "..."] [--model <m>] "<prompt>"
+ *
+ * Tool policy is omitted — opencode manages tool access through its own agent
+ * config files, not via CLI flags.
+ */
+const opencodeBuilder = {
+    platform: "opencode",
+    build(profile, req) {
+        const args = [...profile.args]; // starts with ["run"]
+        if (req.systemPrompt) {
+            args.push("--system-prompt", req.systemPrompt);
+        }
+        if (req.model) {
+            const resolved = resolveModel(req.model, "opencode", profile.modelAliases);
+            args.push("--model", resolved);
+        }
+        args.push(req.prompt);
+        return { argv: [profile.bin, ...args] };
+    },
+};
+/**
+ * Claude Code builder.
+ * Command shape: claude [--system-prompt "..."] [--model <m>] [--allowedTools <t>] --print "<prompt>"
+ *
+ * --print switches Claude Code to non-interactive captured output mode.
+ */
+const claudeBuilder = {
+    platform: "claude",
+    build(profile, req) {
+        const args = [...profile.args];
+        if (req.systemPrompt) {
+            args.push("--system-prompt", req.systemPrompt);
+        }
+        if (req.model) {
+            const resolved = resolveModel(req.model, "claude", profile.modelAliases);
+            args.push("--model", resolved);
+        }
+        if (req.tools) {
+            args.push("--allowedTools", normalizeTools(req.tools));
+        }
+        // --print = non-interactive, outputs to stdout — required for captured mode
+        args.push("--print");
+        args.push(req.prompt);
+        return { argv: [profile.bin, ...args] };
+    },
+};
+/**
+ * Default builder — used for custom profiles and any platform without a
+ * dedicated builder. Passes systemPrompt and model via the same flags as
+ * the builtin builders so custom profiles benefit from agent asset metadata.
+ * Tools are omitted — no standard cross-platform flag exists.
+ */
+const defaultBuilder = {
+    platform: "default",
+    build(profile, req) {
+        const args = [...profile.args];
+        if (req.systemPrompt) {
+            args.push("--system-prompt", req.systemPrompt);
+        }
+        if (req.model) {
+            const resolved = resolveModel(req.model, profile.name, profile.modelAliases);
+            args.push("--model", resolved);
+        }
+        args.push(req.prompt);
+        return { argv: [profile.bin, ...args] };
+    },
+};
+// ── Registry ──────────────────────────────────────────────────────────────────
+const BUILTIN_BUILDERS = {
+    opencode: opencodeBuilder,
+    "opencode-headless": opencodeBuilder,
+    claude: claudeBuilder,
+    "claude-headless": claudeBuilder,
+};
+/**
+ * Return the builder for the given platform name, falling back to the default
+ * builder for unknown platforms. Custom builders injected via tests can be
+ * passed as `registry`.
+ */
+export function getCommandBuilder(platform, registry = BUILTIN_BUILDERS) {
+    return registry[platform] ?? defaultBuilder;
+}