akm-cli 0.6.0-rc1 → 0.6.0

package/dist/core/write-source.js

@@ -0,0 +1,280 @@
+/**
+ * write-source — the only place in the codebase that branches on `source.kind`.
+ *
+ * v1 architecture spec §2.6 / §2.7 / §10 step 5: writing to a source is *not*
+ * a SourceProvider interface concern. It's a small command-layer helper that
+ * does a plain filesystem write, plus a git-specific commit (and optional
+ * push) when the source is backed by a git working tree.
+ *
+ * If a third kind ever needs special write handling, it gets added here. For
+ * v1 there are exactly two cases. Adding more parallel scoring systems for
+ * different provider kinds is explicitly disallowed by CLAUDE.md.
+ *
+ * This module is the **single dispatch point** for `kind`-branching write
+ * logic. Callers (remember, import, source-add, etc.) MUST go through
+ * `writeAssetToSource` / `deleteAssetFromSource` rather than re-inlining the
+ * filesystem-write + git-commit dance.
+ */
+import { spawnSync } from "node:child_process";
+import fs from "node:fs";
+import path from "node:path";
+import { getCachePaths, parseGitRepoUrl } from "../sources/providers/git";
+import { makeAssetRef } from "./asset-ref";
+import { resolveAssetPathFromName, TYPE_DIRS } from "./asset-spec";
+import { isWithin, resolveStashDir } from "./common";
+import { resolveConfiguredSources } from "./config";
+import { ConfigError, UsageError } from "./errors";
+/**
+ * Source kinds that the loader is allowed to mark `writable: true`. Anything
+ * else is rejected at config load (per locked decision 4) — see
+ * {@link assertWritableAllowedForKind}.
+ */
+const REJECTED_WRITABLE_KINDS = new Set(["website", "npm"]);
+// ── Public helpers ──────────────────────────────────────────────────────────
+/**
+ * Resolve the effective `writable` flag for a source config entry, applying
+ * the v1 default policy from spec §5.4:
+ *
+ *  - `filesystem` → `true` by default
+ *  - everything else → `false` by default
+ *
+ * Users can opt out for `filesystem` via `writable: false`. They cannot opt
+ * **in** for `website` / `npm` — that combination is rejected at config load
+ * (see {@link assertWritableAllowedForKind}).
+ */
+export function resolveWritable(entry) {
+    if (typeof entry.writable === "boolean")
+        return entry.writable;
+    return entry.type === "filesystem";
+}
+/**
+ * Reject `writable: true` on `website` / `npm` sources at config-load time.
+ * Per locked decision 4 (§6 of the v1 implementation plan): `sync()` would
+ * clobber writes on the next refresh, so allowing writes here is a footgun.
+ *
+ * Throws {@link ConfigError} when the combination is rejected.
+ */
+export function assertWritableAllowedForKind(entry) {
+    if (entry.writable !== true)
+        return;
+    if (REJECTED_WRITABLE_KINDS.has(entry.type)) {
+        const label = entry.name ? ` "${entry.name}"` : "";
+        throw new ConfigError(`writable: true is only supported on filesystem and git sources (got "${entry.type}" on source${label}).`, "INVALID_CONFIG_FILE", "To author into a checked-out package, add the same path as a separate filesystem source.");
+    }
+}
+/**
+ * Write a textual asset (`content`) into `source` at the path implied by
+ * `ref`. Always:
+ *
+ *   1. Refuses if `config.writable` is not truthy (per §5.4).
+ *   2. Performs a plain filesystem write to `path.join(source.path, …)`.
+ *
+ * For sources of `kind === "git"`, additionally:
+ *
+ *   3. `git -C <path> add <file>`
+ *   4. `git -C <path> commit -m "Update <ref>"`
+ *   5. `git -C <path> push` when `config.options.pushOnCommit` is truthy.
+ *
+ * Any other `kind` reaching this helper is a configuration bug — the loader
+ * rejects unsupported writable kinds — so we throw {@link ConfigError}.
+ */
+export async function writeAssetToSource(source, config, ref, content) {
+    ensureWritable(source, config);
+    const filePath = resolveAssetFilePath(source, ref);
+    fs.mkdirSync(path.dirname(filePath), { recursive: true });
+    const normalized = content.endsWith("\n") ? content : `${content}\n`;
+    fs.writeFileSync(filePath, normalized, "utf8");
+    await runKindSpecificCommit(source, config, filePath, `Update ${formatRefForMessage(ref)}`);
+    return { path: filePath, ref: makeAssetRef(ref.type, ref.name, ref.origin) };
+}
+/**
+ * Delete the asset at `ref` from `source`. Symmetric to
+ * {@link writeAssetToSource}: same writable check, same git-commit-and-push
+ * convenience for `kind === "git"`.
+ */
+export async function deleteAssetFromSource(source, config, ref) {
+    ensureWritable(source, config);
+    const filePath = resolveAssetFilePath(source, ref);
+    if (!fs.existsSync(filePath)) {
+        throw new UsageError(`Asset "${formatRefForMessage(ref)}" not found in source "${source.name}" (expected at ${filePath}).`, "MISSING_REQUIRED_ARGUMENT");
+    }
+    fs.unlinkSync(filePath);
+    await runKindSpecificCommit(source, config, filePath, `Remove ${formatRefForMessage(ref)}`);
+    return { path: filePath, ref: makeAssetRef(ref.type, ref.name, ref.origin) };
+}
+/**
+ * Resolve the destination for a write per locked decision 3:
+ *
+ *   1. Explicit `--target <name>` (when supplied)
+ *   2. `config.defaultWriteTarget`
+ *   3. `config.stashDir` (the working stash created by `akm init`)
+ *   4. `ConfigError("no writable source configured; run `akm init`")`
+ *
+ * The legacy `first-writable-in-source-array-order` fallback is *not* used —
+ * see plan §6 decision 3 for the rationale.
+ */
+export function resolveWriteTarget(akmConfig, explicitTarget) {
+    const configuredSources = resolveConfiguredSources(akmConfig);
+    // 1. Explicit --target wins.
+    if (explicitTarget) {
+        const match = configuredSources.find((s) => s.name === explicitTarget);
+        if (!match) {
+            throw new UsageError(`--target must reference a source name from your config. No source named "${explicitTarget}" is configured. Run \`akm list\` to see available sources.`, "INVALID_FLAG_VALUE");
+        }
+        // Up-front writable check so an explicit --target fails fast with a
+        // ConfigError (rather than the generic UsageError ensureWritable would
+        // raise after we've already started building paths). Resolve the
+        // effective writable flag (filesystem defaults to true; everything else
+        // defaults to false) so unset values are interpreted correctly.
+        const effectiveWritable = resolveWritable({ type: match.type, writable: match.writable });
+        if (!effectiveWritable) {
+            throw new ConfigError(`source ${explicitTarget} is not writable`, "INVALID_CONFIG_FILE", `Set \`writable: true\` on the "${explicitTarget}" source in your config, or pass --target to a different source.`);
+        }
+        return adaptConfiguredSource(match);
+    }
+    // 2. config.defaultWriteTarget.
+    if (akmConfig.defaultWriteTarget) {
+        const match = configuredSources.find((s) => s.name === akmConfig.defaultWriteTarget);
+        if (match)
+            return adaptConfiguredSource(match);
+        // Fall through if the named target no longer exists — surface a clear error.
+        throw new ConfigError(`defaultWriteTarget "${akmConfig.defaultWriteTarget}" does not match any configured source.`, "INVALID_CONFIG_FILE", "Update `defaultWriteTarget` in your config (run `akm config get defaultWriteTarget`) or run `akm list` to see configured sources.");
+    }
+    // 3. Working stash (config.stashDir / resolveStashDir()).
+    try {
+        const stashDir = resolveStashDir({ readOnly: true });
+        return {
+            source: { kind: "filesystem", name: "stash", path: stashDir },
+            config: { type: "filesystem", path: stashDir, name: "stash", writable: true },
+        };
+    }
+    catch {
+        // Fall through to the final ConfigError below.
+    }
+    // 4. Nothing usable.
+    throw new ConfigError("no writable source configured; run `akm init`", "STASH_DIR_NOT_FOUND", "Run `akm init` to create a working stash, or set `defaultWriteTarget` in your config.");
+}
+// ── Internals ───────────────────────────────────────────────────────────────
+function ensureWritable(source, config) {
+    // Apply the same default-resolution rule as resolveWritable so callers can
+    // pass through a SourceConfigEntry with an absent `writable` field.
+    const writable = resolveWritable(config);
+    if (!writable) {
+        throw new UsageError(`Source "${source.name}" is not writable. Set \`writable: true\` on the source config entry to enable writes.`, "INVALID_FLAG_VALUE");
+    }
+}
+function resolveAssetFilePath(source, ref) {
+    const typeDir = TYPE_DIRS[ref.type];
+    if (!typeDir) {
+        throw new UsageError(`Unknown asset type "${ref.type}". Cannot resolve a write path.`, "INVALID_FLAG_VALUE");
+    }
+    const typeRoot = path.join(source.path, typeDir);
+    const assetPath = resolveAssetPathFromName(ref.type, typeRoot, ref.name);
+    if (!isWithin(assetPath, typeRoot)) {
+        throw new UsageError(`Resolved asset path escapes its source: "${ref.name}" in source "${source.name}".`, "PATH_ESCAPE_VIOLATION");
+    }
+    return assetPath;
+}
+async function runKindSpecificCommit(source, config, filePath, message) {
+    if (source.kind === "filesystem") {
+        return; // No commit step.
+    }
+    if (source.kind === "git") {
+        runGitCommit(source.path, filePath, message);
+        if (config.options?.pushOnCommit) {
+            runGitPush(source.path);
+        }
+        return;
+    }
+    // Reject any other kind reaching the helper. The config loader is the
+    // first line of defence (assertWritableAllowedForKind), but we throw here
+    // so external callers that bypass the loader still get a clear error.
+    throw new ConfigError(`write-source: unsupported kind "${source.kind}" for source "${source.name}". ` +
+        "Writes are only defined for `filesystem` and `git` sources.", "INVALID_CONFIG_FILE", 'Set `kind: "filesystem"` (or `kind: "git"`) on the source, or add a parallel filesystem entry.');
+}
+function runGitCommit(repoDir, filePath, message) {
+    // Stage the specific file rather than `add -A` so unrelated working-tree
+    // changes don't get folded into the asset commit.
+    const relPath = path.relative(repoDir, filePath) || filePath;
+    const addResult = spawnSync("git", ["-C", repoDir, "add", "--", relPath], { encoding: "utf8" });
+    if (addResult.status !== 0) {
+        throw new Error(`git add failed: ${addResult.stderr?.trim() || "unknown error"}`);
+    }
+    // Provide a fallback identity so fresh CI/test environments without
+    // user.name/user.email configured can always commit.
+    const commitResult = spawnSync("git", ["-C", repoDir, "-c", "user.name=akm", "-c", "user.email=akm@local", "commit", "-m", message], { encoding: "utf8" });
+    if (commitResult.status !== 0) {
+        // `nothing to commit` is a no-op success — the file may have matched the
+        // existing tree exactly. Surface other errors verbatim.
+        const stderr = commitResult.stderr ?? "";
+        if (/nothing to commit|no changes added/i.test(stderr) ||
+            /nothing to commit|no changes added/i.test(commitResult.stdout ?? "")) {
+            return;
+        }
+        throw new Error(`git commit failed: ${stderr.trim() || "unknown error"}`);
+    }
+}
+function runGitPush(repoDir) {
+    const pushResult = spawnSync("git", ["-C", repoDir, "push"], { encoding: "utf8", timeout: 120_000 });
+    if (pushResult.status !== 0) {
+        throw new Error(`git push failed: ${pushResult.stderr?.trim() || "unknown error"}`);
+    }
+}
+function formatRefForMessage(ref) {
+    return ref.origin ? `${ref.origin}//${ref.type}:${ref.name}` : `${ref.type}:${ref.name}`;
+}
+/**
+ * Derive a {@link WriteTargetSource} + persisted {@link SourceConfigEntry}
+ * from the runtime {@link ConfiguredSource} representation used elsewhere in
+ * the codebase. The mapping is:
+ *
+ *   ConfiguredSource.type     → WriteTargetSource.kind
+ *   ConfiguredSource.name     → WriteTargetSource.name
+ *   ConfiguredSource.source.* → WriteTargetSource.path  (via parseSourceSpec)
+ *
+ * Legacy aliases (`context-hub`, `github`) have already been normalised to
+ * `git` by the config loader, so this mapping is straightforward.
+ */
+function adaptConfiguredSource(runtime) {
+    const writePath = pathFromConfiguredSource(runtime);
+    if (!writePath) {
+        throw new ConfigError(`Source "${runtime.name}" has no resolvable on-disk path; writes are unsupported for this entry.`, "INVALID_CONFIG_FILE");
+    }
+    // Map the runtime kind to the write helper's `kind` discriminator. Only
+    // filesystem and git produce writable sources at v1.
+    const kind = runtime.type === "filesystem" || runtime.type === "git" ? runtime.type : runtime.type;
+    const config = {
+        type: runtime.type,
+        name: runtime.name,
+        ...(writePath !== undefined ? { path: writePath } : {}),
+        ...(runtime.writable !== undefined ? { writable: runtime.writable } : {}),
+        ...(runtime.options ? { options: runtime.options } : {}),
+    };
+    return {
+        source: { kind, name: runtime.name, path: writePath },
+        config,
+    };
+}
+function pathFromConfiguredSource(runtime) {
+    // ConfiguredSource.source is the parsed SourceSpec (filesystem|git|website|npm).
+    // For writable kinds we only ever care about a local on-disk path: filesystem
+    // sources expose it directly; git sources resolve through the cache mirror
+    // (handled by the existing source provider). For v1 the helper trusts
+    // callers to materialise the cache path beforehand and does not re-clone.
+    const spec = runtime.source;
+    if (spec.type === "filesystem")
+        return spec.path;
+    // For git sources we fall back to the cached repo directory the provider
+    // already materialised. The lookup is intentionally lazy — we only import
+    // it when needed to keep the helper's import graph small.
+    if (spec.type === "git") {
+        try {
+            const repo = parseGitRepoUrl(spec.url);
+            return getCachePaths(repo.canonicalUrl).repoDir;
+        }
+        catch {
+            return undefined;
+        }
+    }
+    return undefined;
+}

package/dist/{db-search.js → indexer/db-search.js}

@@ -1,29 +1,29 @@
 /**
- * Database-backed (SQLite + FTS5/vector) stash search implementation.
+ * Database-backed (SQLite + FTS5/vector) source search implementation.
  *
- * Extracted from stash-search.ts to break the circular import:
- *   stash-search.ts → stash-providers/filesystem.ts → db-search.ts (no cycle)
+ * Extracted from source-search.ts to break the circular import:
+ *   source-search.ts → sources/providers/filesystem.ts → db-search.ts (no cycle)
  *
- * stash-search.ts imports this module for the `searchLocal` export.
- * stash-providers/filesystem.ts also imports `searchLocal` from here.
+ * source-search.ts imports this module for the `searchLocal` export.
+ * sources/providers/filesystem.ts also imports `searchLocal` from here.
  *
  * Renamed from `local-search.ts` to signal that this is the DB-layer search
  * implementation, not a "local vs. remote" distinction.
  */
 import fs from "node:fs";
 import path from "node:path";
-import { defaultRendererRegistry } from "./asset-registry";
-import { deriveCanonicalAssetNameFromStashRoot } from "./asset-spec";
+import { makeAssetRef } from "../core/asset-ref";
+import { defaultRendererRegistry } from "../core/asset-registry";
+import { deriveCanonicalAssetNameFromStashRoot } from "../core/asset-spec";
+import { getDbPath } from "../core/paths";
+import { warn } from "../core/warn";
 import { closeDatabase, getAllEntries, getEntryById, getEntryCount, getMeta, getUtilityScoresByIds, openDatabase, searchFts, searchVec, } from "./db";
 import { getRenderer } from "./file-context";
 import { generateMetadataFlat, loadStashFile, shouldIndexStashFile } from "./metadata";
-import { getDbPath } from "./paths";
 import { buildSearchText } from "./search-fields";
 import { buildEditHint, findSourceForPath, isEditable } from "./search-source";
 import { deriveSemanticProviderFingerprint, getEffectiveSemanticStatus, isSemanticRuntimeReady, readSemanticStatus, } from "./semantic-status";
-import { makeAssetRef } from "./stash-ref";
 import { walkStashFlat } from "./walker";
-import { warn } from "./warn";
 export async function rendererForType(type, registry = defaultRendererRegistry) {
     const name = registry.rendererNameFor(type);
     return name ? getRenderer(name) : undefined;
@@ -45,7 +45,7 @@ function resolveSearchHitOrigin(source) {
 export async function searchLocal(input) {
     const { query, searchType, limit, stashDir, sources, config } = input;
     const rendererRegistry = input.rendererRegistry ?? defaultRendererRegistry;
-    const allStashDirs = sources.map((s) => s.path);
+    const allSourceDirs = sources.map((s) => s.path);
     const rawStatus = readSemanticStatus();
     const semanticStatus = getEffectiveSemanticStatus(config, rawStatus);
     const warnings = [];
@@ -85,7 +85,7 @@ export async function searchLocal(input) {
                     }
                 }
                 if (entryCount > 0 && stashDirMatch) {
-                    const { hits, embedMs, rankMs } = await searchDatabase(db, query, searchType, limit, stashDir, allStashDirs, config, sources, rendererRegistry);
+                    const { hits, embedMs, rankMs } = await searchDatabase(db, query, searchType, limit, stashDir, allSourceDirs, config, sources, rendererRegistry);
                     return {
                         hits,
                         tip: hits.length === 0
@@ -105,7 +105,7 @@ export async function searchLocal(input) {
     catch (error) {
         warn("Search index unavailable, falling back to substring search:", error instanceof Error ? error.message : String(error));
     }
-    const hitArrays = await Promise.all(allStashDirs.map((dir) => substringSearch(query, searchType, limit, dir, sources, config, rendererRegistry)));
+    const hitArrays = await Promise.all(allSourceDirs.map((dir) => substringSearch(query, searchType, limit, dir, sources, config, rendererRegistry)));
     const hits = hitArrays.flat().slice(0, limit);
     return {
         hits,
@@ -114,7 +114,7 @@ export async function searchLocal(input) {
     };
 }
 // ── Database search ─────────────────────────────────────────────────────────
-async function searchDatabase(db, query, searchType, limit, stashDir, allStashDirs, config, sources, rendererRegistry = defaultRendererRegistry) {
+async function searchDatabase(db, query, searchType, limit, stashDir, allSourceDirs, config, sources, rendererRegistry = defaultRendererRegistry) {
     // Empty query: return all entries
     if (!query) {
         const typeFilter = searchType === "any" ? undefined : searchType;
@@ -135,7 +135,7 @@ async function searchDatabase(db, query, searchType, limit, stashDir, allStashDi
             query,
             rankingMode: "fts",
             defaultStashDir: stashDir,
-            allStashDirs,
+            allSourceDirs,
             sources,
             config,
             rendererRegistry,
@@ -355,13 +355,19 @@ async function searchDatabase(db, query, searchType, limit, stashDir, allStashDi
             item.utilityBoosted = true;
         }
     }
+    // ── minScore floor ──────────────────────────────────────────────────────
+    // Drop semantic-only hits (cosine-only, no FTS match) whose score falls
+    // below the configured floor. FTS hits and hybrid hits are always kept.
+    // Default floor: 0.2. Set search.minScore = 0 in config to disable.
+    const minScore = config.search?.minScore ?? 0.2;
+    const preFilter = minScore > 0 ? scored.filter((item) => item.rankingMode !== "semantic" || item.score >= minScore) : scored;
     // Deterministic tiebreaker on equal scores
-    scored.sort((a, b) => b.score - a.score || a.entry.name.localeCompare(b.entry.name));
+    preFilter.sort((a, b) => b.score - a.score || a.entry.name.localeCompare(b.entry.name));
     // Deduplicate by file path — keep only the highest-scored entry per file.
     // Multiple .stash.json entries can map to the same file (e.g. entries without
     // a filename field all collapse to files[0]). Showing the same path/ref
     // multiple times clutters results.
-    const deduped = deduplicateByPath(scored);
+    const deduped = deduplicateByPath(preFilter);
     const rankMs = Date.now() - tRank0;
     const selected = deduped.slice(0, limit);
     const hits = await Promise.all(selected.map(({ entry, filePath, score, rankingMode, utilityBoosted }) => buildDbHit({
@@ -372,7 +378,7 @@ async function searchDatabase(db, query, searchType, limit, stashDir, allStashDi
         query,
         rankingMode,
         defaultStashDir: stashDir,
-        allStashDirs,
+        allSourceDirs,
         sources,
         config,
         utilityBoosted,
@@ -389,7 +395,7 @@ async function tryVecScores(db, query, k, config) {
     if (hasEmbeddings !== "1")
         return null;
     try {
-        const { embed } = await import("./embedder.js");
+        const { embed } = await import("../llm/embedder.js");
         const queryEmbedding = await embed(query, config.embedding);
         const vecResults = searchVec(db, queryEmbedding, k);
         const scores = new Map();

package/dist/{db.js → indexer/db.js}

@@ -2,13 +2,14 @@ import { Database } from "bun:sqlite";
 import fs from "node:fs";
 import { createRequire } from "node:module";
 import path from "node:path";
-import { cosineSimilarity } from "./embedders/types";
-import { getDbPath } from "./paths";
+import { parseAssetRef } from "../core/asset-ref";
+import { getDbPath } from "../core/paths";
+import { warn } from "../core/warn";
+import { cosineSimilarity } from "../llm/embedders/types";
 import { buildSearchFields } from "./search-fields";
 import { ensureUsageEventsSchema } from "./usage-events";
-import { warn } from "./warn";
 // ── Constants ───────────────────────────────────────────────────────────────
-export const DB_VERSION = 8;
+export const DB_VERSION = 9;
 export const EMBEDDING_DIM = 384;
 // ── Database lifecycle ──────────────────────────────────────────────────────
 export function openDatabase(dbPath, options) {
@@ -19,6 +20,7 @@ export function openDatabase(dbPath, options) {
     }
     const db = new Database(resolvedPath);
     db.exec("PRAGMA journal_mode = WAL");
+    db.exec("PRAGMA busy_timeout = 5000");
     db.exec("PRAGMA foreign_keys = ON");
     // Try to load sqlite-vec extension
     loadVecExtension(db);
@@ -102,6 +104,22 @@ function ensureSchema(db, embeddingDim) {
 
     CREATE INDEX IF NOT EXISTS idx_entries_dir ON entries(dir_path);
     CREATE INDEX IF NOT EXISTS idx_entries_type ON entries(entry_type);
+  `);
+    // Validated WorkflowDocument JSON, one row per indexed workflow entry.
+    // Pure index data — fully rebuilt on each `akm index`. ON DELETE CASCADE
+    // means clearing entries (full rebuild or per-dir delete) drops these too.
+    db.exec(`
+    CREATE TABLE IF NOT EXISTS workflow_documents (
+      entry_id        INTEGER PRIMARY KEY REFERENCES entries(id) ON DELETE CASCADE,
+      schema_version  INTEGER NOT NULL,
+      document_json   TEXT NOT NULL,
+      source_path     TEXT NOT NULL,
+      source_hash     TEXT NOT NULL,
+      updated_at      TEXT NOT NULL
+    );
+
+    CREATE INDEX IF NOT EXISTS idx_workflow_documents_source_path
+      ON workflow_documents(source_path);
   `);
     // Set version immediately after table creation so a crash before the end of
     // ensureSchema() does not leave the database in a versionless state on next open.
@@ -145,6 +163,15 @@ function ensureSchema(db, embeddingDim) {
       updated_at   TEXT NOT NULL DEFAULT (datetime('now')),
       FOREIGN KEY (entry_id) REFERENCES entries(id) ON DELETE CASCADE
     );
+  `);
+    // FTS-dirty queue. Created here (not lazily on first upsert) so the
+    // per-entry write path doesn't issue a CREATE TABLE IF NOT EXISTS on
+    // every call — that DDL would fire thousands of times during a full
+    // index. See `markFtsDirty` and `rebuildFts({ incremental: true })`.
+    db.exec(`
+    CREATE TABLE IF NOT EXISTS entries_fts_dirty (
+      entry_id INTEGER PRIMARY KEY
+    );
   `);
     // sqlite-vec table
     if (isVecAvailable(db)) {
@@ -280,45 +307,45 @@ export function setMeta(db, key, value) {
  * reflect the changes.
  */
 export function upsertEntry(db, entryKey, dirPath, filePath, stashDir, entry, searchText) {
-    const stmt = db.prepare(`
-    INSERT INTO entries (entry_key, dir_path, file_path, stash_dir, entry_json, search_text, entry_type)
-    VALUES (?, ?, ?, ?, ?, ?, ?)
-    ON CONFLICT(entry_key) DO UPDATE SET
-      dir_path = excluded.dir_path,
-      file_path = excluded.file_path,
-      stash_dir = excluded.stash_dir,
-      entry_json = excluded.entry_json,
-      search_text = excluded.search_text,
-      entry_type = excluded.entry_type
-  `);
-    stmt.run(entryKey, dirPath, filePath, stashDir, JSON.stringify(entry), searchText, entry.type);
-    // Fetch the row id explicitly since last_insert_rowid() is unreliable for ON CONFLICT DO UPDATE
-    const row = db.prepare("SELECT id FROM entries WHERE entry_key = ?").get(entryKey);
-    if (!row)
+    // Hot path during indexing — cache the two prepared statements per
+    // database connection so we don't pay the SQL parse/compile cost on
+    // every call. The dirty-mark INSERT and the upsert-with-RETURNING
+    // share the same WeakMap so they live and die with the connection.
+    const stmts = getUpsertStmts(db);
+    const result = stmts.upsert.get(entryKey, dirPath, filePath, stashDir, JSON.stringify(entry), searchText, entry.type);
+    if (!result)
         throw new Error("upsertEntry: entry_key not found after upsert");
-    // Mark this entry as FTS-dirty so an incremental rebuild only revisits the
-    // entries that actually changed. Without this, every `akm index` run had to
-    // re-scan and re-insert every FTS row, even if only one entry was touched.
-    markFtsDirty(db, row.id);
-    return row.id;
-}
-/**
- * Mark an entry as needing FTS re-indexing on the next `rebuildFts` call.
- *
- * The list lives in a small `entries_fts_dirty` table — a per-entry-id queue
- * of work items. `rebuildFts({ incremental: true })` drains this list rather
- * than scanning the entire `entries` table.
- */
-function markFtsDirty(db, entryId) {
-    ensureFtsDirtyTable(db);
-    db.prepare("INSERT OR IGNORE INTO entries_fts_dirty (entry_id) VALUES (?)").run(entryId);
-}
-function ensureFtsDirtyTable(db) {
-    db.exec(`
-    CREATE TABLE IF NOT EXISTS entries_fts_dirty (
-      entry_id INTEGER PRIMARY KEY
-    );
-  `);
+    // Mark this entry as FTS-dirty so `rebuildFts({ incremental: true })`
+    // only revisits entries that actually changed. INSERT OR IGNORE is
+    // idempotent across multiple upserts of the same row.
+    stmts.markDirty.run(result.id);
+    return result.id;
+}
+const upsertStmtsByDb = new WeakMap();
+function getUpsertStmts(db) {
+    const existing = upsertStmtsByDb.get(db);
+    if (existing)
+        return existing;
+    const stmts = {
+        // RETURNING id handles ON CONFLICT DO UPDATE correctly — no second
+        // SELECT round-trip needed (last_insert_rowid() is unreliable for
+        // ON CONFLICT). Use `.get()` so a single row comes back.
+        upsert: db.prepare(`
+      INSERT INTO entries (entry_key, dir_path, file_path, stash_dir, entry_json, search_text, entry_type)
+      VALUES (?, ?, ?, ?, ?, ?, ?)
+      ON CONFLICT(entry_key) DO UPDATE SET
+        dir_path = excluded.dir_path,
+        file_path = excluded.file_path,
+        stash_dir = excluded.stash_dir,
+        entry_json = excluded.entry_json,
+        search_text = excluded.search_text,
+        entry_type = excluded.entry_type
+      RETURNING id
+    `),
+        markDirty: db.prepare("INSERT OR IGNORE INTO entries_fts_dirty (entry_id) VALUES (?)"),
+    };
+    upsertStmtsByDb.set(db, stmts);
+    return stmts;
 }
 export function deleteEntriesByDir(db, dirPath) {
     db.transaction(() => {
@@ -419,7 +446,6 @@ export function rebuildFts(db, options) {
     db.transaction(() => {
         let rows;
         if (incremental) {
-            ensureFtsDirtyTable(db);
             // Read the dirty queue and join against entries to get the JSON.
             // Then drop the matching rows from entries_fts so the INSERT below
             // doesn't double-up. The dirty list is drained at the end.
@@ -469,10 +495,8 @@ export function rebuildFts(db, options) {
             db.exec("DELETE FROM entries_fts_dirty");
         }
         else {
-            // Full path: only drop the dirty table if it exists. Use
-            // `CREATE IF NOT EXISTS` then DELETE so we don't error on databases
-            // that haven't run any upserts yet (e.g. fresh schema).
-            ensureFtsDirtyTable(db);
+            // Full path: drain the dirty queue too. The table is created by
+            // ensureSchema(), so it always exists at this point.
             db.exec("DELETE FROM entries_fts_dirty");
         }
     })();
@@ -694,6 +718,14 @@ export function getAllEntries(db, entryType) {
     }
     return entries;
 }
+export function findEntryIdByRef(db, ref) {
+    const parsed = parseAssetRef(ref);
+    const suffix = `${parsed.type}:${parsed.name}`;
+    const row = db
+        .prepare("SELECT id FROM entries WHERE entry_type = ? AND substr(entry_key, length(entry_key) - length(?) + 1) = ? LIMIT 1")
+        .get(parsed.type, suffix, suffix);
+    return row?.id;
+}
 export function getEntryCount(db) {
     const row = db.prepare("SELECT COUNT(*) AS cnt FROM entries").get();
     return row.cnt;

package/dist/{file-context.js → indexer/file-context.js}

@@ -6,8 +6,8 @@
  */
 import fs from "node:fs";
 import path from "node:path";
-import { toPosix } from "./common";
-import { parseFrontmatter } from "./frontmatter";
+import { toPosix } from "../core/common";
+import { parseFrontmatter } from "../core/frontmatter";
 /**
  * Build a FileContext from a stash root and an absolute file path.
  *
@@ -81,7 +81,7 @@ async function ensureBuiltinsRegistered() {
     if (!builtinsPromise) {
         builtinsPromise = (async () => {
             const { registerBuiltinMatchers } = await import("./matchers.js");
-            const { registerBuiltinRenderers } = await import("./renderers.js");
+            const { registerBuiltinRenderers } = await import("../output/renderers.js");
             registerBuiltinMatchers();
             registerBuiltinRenderers();
         })();