akm-cli 0.0.20 → 0.0.22

package/dist/indexer.js

@@ -26,31 +26,28 @@ export async function agentikitIndex(options) {
         const isIncremental = !options?.full && prevStashDir === stashDir && !!prevBuiltAt;
         const builtAtMs = isIncremental && prevBuiltAt ? new Date(prevBuiltAt).getTime() : 0;
         if (options?.full || !isIncremental) {
-            // Wipe all entries for full rebuild or stashDir change
-            // Delete from child tables first to respect foreign key constraints
-            try {
-                db.exec("DELETE FROM embeddings");
-            }
-            catch {
-                /* ignore */
-            }
-            if (isVecAvailable(db)) {
-                try {
-                    db.exec("DELETE FROM entries_vec");
-                }
-                catch {
-                    /* ignore */
-                }
-            }
-            db.exec("DELETE FROM entries_fts");
-            db.exec("DELETE FROM entries");
+            // HI-5: the delete is now merged into the insert transaction inside
+            // indexEntries() so that a reader never sees an empty database between
+            // the wipe and the re-inserts.  The doFullDelete flag signals this path.
         }
         else {
             // Incremental: purge entries from stash dirs that have been removed
             // (e.g. after `akm remove`) so orphaned entries don't linger.
             const prevStashDirsJson = getMeta(db, "stashDirs");
             if (prevStashDirsJson) {
-                const prevStashDirs = JSON.parse(prevStashDirsJson);
+                let prevStashDirs = [];
+                try {
+                    const parsed = JSON.parse(prevStashDirsJson);
+                    if (Array.isArray(parsed)) {
+                        prevStashDirs = parsed.filter((d) => typeof d === "string");
+                    }
+                    else {
+                        warn("index_meta stashDirs value is not an array — treating as empty");
+                    }
+                }
+                catch {
+                    warn("index_meta stashDirs value is corrupt JSON — treating as empty");
+                }
                 const currentSet = new Set(allStashDirs);
                 for (const dir of prevStashDirs) {
                     if (!currentSet.has(dir)) {
@@ -60,11 +57,15 @@ export async function agentikitIndex(options) {
             }
         }
         const tWalkStart = Date.now();
-        // Walk stash dirs and index entries
-        const { scannedDirs, skippedDirs, generatedCount, dirsNeedingLlm } = indexEntries(db, allStashDirs, stashDir, isIncremental, builtAtMs);
+        // Walk stash dirs and index entries.
+        // doFullDelete=true merges the wipe into the same transaction as the
+        // inserts (HI-5) so readers never see an empty database mid-rebuild.
+        const doFullDelete = options?.full || !isIncremental;
+        const { scannedDirs, skippedDirs, generatedCount, dirsNeedingLlm } = await indexEntries(db, allStashDirs, stashDir, isIncremental, builtAtMs, doFullDelete);
+        const tWalkEnd = Date.now();
         // Enhance entries with LLM if configured
         await enhanceDirsWithLlm(db, config, dirsNeedingLlm);
-        const tWalkEnd = Date.now();
+        const tLlmEnd = Date.now();
         // Rebuild FTS after all inserts
         rebuildFts(db);
         const tFtsEnd = Date.now();
@@ -92,8 +93,9 @@ export async function agentikitIndex(options) {
             timing: {
                 totalMs: tEnd - t0,
                 walkMs: tWalkEnd - tWalkStart,
+                llmMs: tLlmEnd - tWalkEnd,
                 embedMs: tEmbedEnd - tFtsEnd,
-                ftsMs: tFtsEnd - tWalkEnd,
+                ftsMs: tFtsEnd - tLlmEnd,
             },
         };
     }
@@ -102,74 +104,102 @@ export async function agentikitIndex(options) {
     }
 }
 // ── Extracted helpers for indexing ────────────────────────────────────────────
-function indexEntries(db, allStashDirs, _stashDir, isIncremental, builtAtMs) {
+async function indexEntries(db, allStashDirs, _stashDir, isIncremental, builtAtMs, doFullDelete = false) {
     let scannedDirs = 0;
     let skippedDirs = 0;
     let generatedCount = 0;
     const seenPaths = new Set();
     const dirsNeedingLlm = [];
-    const insertTransaction = db.transaction(() => {
-        for (const currentStashDir of allStashDirs) {
-            // Walk the entire stash directory — matchers classify each file
-            const fileContexts = walkStashFlat(currentStashDir);
-            // Group files by parent directory
-            const dirGroups = new Map();
-            for (const ctx of fileContexts) {
-                const dir = ctx.parentDirAbs;
-                const group = dirGroups.get(dir);
-                if (group)
-                    group.push(ctx.absPath);
-                else
-                    dirGroups.set(dir, [ctx.absPath]);
+    const dirRecords = [];
+    for (const currentStashDir of allStashDirs) {
+        const fileContexts = walkStashFlat(currentStashDir);
+        const dirGroups = new Map();
+        for (const ctx of fileContexts) {
+            const dir = ctx.parentDirAbs;
+            const group = dirGroups.get(dir);
+            if (group)
+                group.push(ctx.absPath);
+            else
+                dirGroups.set(dir, [ctx.absPath]);
+        }
+        for (const [dirPath, files] of dirGroups) {
+            if (seenPaths.has(path.resolve(dirPath))) {
+                dirRecords.push({ dirPath, currentStashDir, files, stash: null, skip: true });
+                continue;
             }
-            for (const [dirPath, files] of dirGroups) {
-                if (seenPaths.has(path.resolve(dirPath)))
+            seenPaths.add(path.resolve(dirPath));
+            // Incremental: skip directories that haven't changed
+            if (isIncremental) {
+                const prevEntries = getEntriesByDir(db, dirPath);
+                if (prevEntries.length > 0 && !isDirStale(dirPath, files, prevEntries, builtAtMs)) {
+                    skippedDirs++;
+                    dirRecords.push({ dirPath, currentStashDir, files, stash: null, skip: true });
                     continue;
-                seenPaths.add(path.resolve(dirPath));
-                // Incremental: skip directories that haven't changed
-                if (isIncremental) {
-                    const prevEntries = getEntriesByDir(db, dirPath);
-                    if (prevEntries.length > 0 && !isDirStale(dirPath, files, prevEntries, builtAtMs)) {
-                        skippedDirs++;
-                        continue;
-                    }
                 }
-                scannedDirs++;
-                // Delete old entries for this dir (will be re-inserted)
-                deleteEntriesByDir(db, dirPath);
-                // Try loading existing .stash.json (user metadata overrides)
-                let stash = loadStashFile(dirPath);
-                if (stash) {
-                    // Check for files on disk that aren't covered by existing .stash.json entries.
-                    const coveredFiles = new Set(stash.entries.map((e) => (e.filename ? path.basename(e.filename) : "")).filter((e) => !!e));
-                    const uncoveredFiles = files.filter((f) => !coveredFiles.has(path.basename(f)));
-                    if (uncoveredFiles.length > 0) {
-                        const generated = generateMetadataFlat(currentStashDir, uncoveredFiles);
-                        if (generated.entries.length > 0) {
-                            stash = { entries: [...stash.entries, ...generated.entries] };
-                            generatedCount += generated.entries.length;
-                        }
-                    }
-                }
-                if (!stash) {
-                    const generated = generateMetadataFlat(currentStashDir, files);
+            }
+            scannedDirs++;
+            // Try loading existing .stash.json (user metadata overrides)
+            let stash = loadStashFile(dirPath);
+            if (stash) {
+                const coveredFiles = new Set(stash.entries.map((e) => (e.filename ? path.basename(e.filename) : "")).filter((e) => !!e));
+                const uncoveredFiles = files.filter((f) => !coveredFiles.has(path.basename(f)));
+                if (uncoveredFiles.length > 0) {
+                    const generated = await generateMetadataFlat(currentStashDir, uncoveredFiles);
                     if (generated.entries.length > 0) {
-                        stash = { entries: generated.entries };
+                        stash = { entries: [...stash.entries, ...generated.entries] };
                         generatedCount += generated.entries.length;
                     }
                 }
-                if (stash) {
-                    for (const entry of stash.entries) {
-                        const entryPath = entry.filename ? path.join(dirPath, entry.filename) : files[0] || dirPath;
-                        const entryKey = `${currentStashDir}:${entry.type}:${entry.name}`;
-                        const searchText = buildSearchText(entry);
-                        const entryWithSize = attachFileSize(entry, entryPath);
-                        upsertEntry(db, entryKey, dirPath, entryPath, currentStashDir, entryWithSize, searchText);
-                    }
-                    // Collect dirs needing LLM enhancement during the first walk
-                    if (stash.entries.some((e) => e.quality === "generated")) {
-                        dirsNeedingLlm.push({ dirPath, files, currentStashDir, stash });
-                    }
+            }
+            if (!stash) {
+                const generated = await generateMetadataFlat(currentStashDir, files);
+                if (generated.entries.length > 0) {
+                    stash = { entries: generated.entries };
+                    generatedCount += generated.entries.length;
+                }
+            }
+            dirRecords.push({ dirPath, currentStashDir, files, stash, skip: false });
+        }
+    }
+    // Phase 2 (sync): write all pre-generated metadata inside a single transaction.
+    const insertTransaction = db.transaction(() => {
+        // HI-5: Perform the full-rebuild wipe as the FIRST step of the insert
+        // transaction so delete and re-insert are atomic — a concurrent reader
+        // never observes an empty database between the two operations.
+        if (doFullDelete) {
+            try {
+                db.exec("DELETE FROM embeddings");
+            }
+            catch {
+                /* ignore */
+            }
+            if (isVecAvailable(db)) {
+                try {
+                    db.exec("DELETE FROM entries_vec");
+                }
+                catch {
+                    /* ignore */
+                }
+            }
+            db.exec("DELETE FROM entries_fts");
+            db.exec("DELETE FROM entries");
+        }
+        for (const { dirPath, currentStashDir, files, stash, skip } of dirRecords) {
+            if (skip)
+                continue;
+            // Delete old entries for this dir (will be re-inserted)
+            deleteEntriesByDir(db, dirPath);
+            if (stash) {
+                for (const entry of stash.entries) {
+                    const entryPath = entry.filename ? path.join(dirPath, entry.filename) : files[0] || dirPath;
+                    const entryKey = `${currentStashDir}:${entry.type}:${entry.name}`;
+                    const searchText = buildSearchText(entry);
+                    const entryWithSize = attachFileSize(entry, entryPath);
+                    upsertEntry(db, entryKey, dirPath, entryPath, currentStashDir, entryWithSize, searchText);
+                }
+                // Collect dirs needing LLM enhancement during the first walk
+                if (stash.entries.some((e) => e.quality === "generated")) {
+                    dirsNeedingLlm.push({ dirPath, files, currentStashDir, stash });
                 }
             }
         }
@@ -187,13 +217,16 @@ async function enhanceDirsWithLlm(db, config, dirsNeedingLlm) {
             continue;
         const generatedStash = { entries: generatedEntries };
         const enhanced = await enhanceStashWithLlm(config.llm, generatedStash, dirPath, files);
-        // Re-upsert only the enhanced (generated) entries
-        for (const entry of enhanced.entries) {
-            const entryPath = entry.filename ? path.join(dirPath, entry.filename) : files[0] || dirPath;
-            const entryKey = `${currentStashDir}:${entry.type}:${entry.name}`;
-            const searchText = buildSearchText(entry);
-            upsertEntry(db, entryKey, dirPath, entryPath, currentStashDir, attachFileSize(entry, entryPath), searchText);
-        }
+        // HI-2: Re-upsert the enhanced entries in a single transaction so a crash
+        // cannot leave half the entries updated and the rest stale.
+        db.transaction(() => {
+            for (const entry of enhanced.entries) {
+                const entryPath = entry.filename ? path.join(dirPath, entry.filename) : files[0] || dirPath;
+                const entryKey = `${currentStashDir}:${entry.type}:${entry.name}`;
+                const searchText = buildSearchText(entry);
+                upsertEntry(db, entryKey, dirPath, entryPath, currentStashDir, attachFileSize(entry, entryPath), searchText);
+            }
+        })();
     }
 }
 async function generateEmbeddingsForDb(db, config) {
@@ -206,9 +239,13 @@ async function generateEmbeddingsForDb(db, config) {
             return true;
         const texts = allEntries.map((e) => e.searchText);
         const embeddings = await embedBatch(texts, config.embedding);
-        for (let i = 0; i < allEntries.length; i++) {
-            upsertEmbedding(db, allEntries[i].id, embeddings[i]);
-        }
+        // HI-3: Wrap all embedding upserts in a single transaction so partial
+        // state is rolled back on failure rather than leaving the table half-filled.
+        db.transaction(() => {
+            for (let i = 0; i < allEntries.length; i++) {
+                upsertEmbedding(db, allEntries[i].id, embeddings[i]);
+            }
+        })();
         return true;
     }
     catch (error) {

package/dist/{stash-registry.js → installed-kits.js}

@@ -1,3 +1,14 @@
+/**
+ * Installed-kit operations: list, remove, update.
+ *
+ * Manages the set of kits that have been added to the local stash via
+ * `akm add`. Each installed kit has a cache directory and a stash root that
+ * is added to the search path.
+ *
+ * Not to be confused with:
+ *   - registry-factory.ts   — factory map for kit-discovery registry providers
+ *   - stash-provider-factory.ts — factory map for runtime stash data sources
+ */
 import fs from "node:fs";
 import { resolveStashDir } from "./common";
 import { loadConfig } from "./config";
@@ -76,7 +87,7 @@ export async function agentikitUpdate(input) {
         }
         const installed = await installRegistryRef(entry.ref);
         upsertInstalledRegistryEntry(toInstalledEntry(installed));
-        upsertLockEntry({
+        await upsertLockEntry({
             id: installed.id,
             source: installed.source,
             ref: installed.ref,
@@ -159,31 +170,12 @@ function resolveInstalledTarget(installed, target) {
     throw new NotFoundError(`No installed kit matched target: ${target}`);
 }
 function toInstalledEntry(status) {
-    return {
-        id: status.id,
-        source: status.source,
-        ref: status.ref,
-        artifactUrl: status.artifactUrl,
-        resolvedVersion: status.resolvedVersion,
-        resolvedRevision: status.resolvedRevision,
-        stashRoot: status.stashRoot,
-        cacheDir: status.cacheDir,
-        installedAt: status.installedAt,
-    };
+    // KitInstallStatus extends InstalledKitEntry; omit the extra extractedDir field.
+    const { extractedDir: _extractedDir, ...base } = status;
+    return base;
 }
 function toInstallStatus(status) {
-    return {
-        id: status.id,
-        source: status.source,
-        ref: status.ref,
-        artifactUrl: status.artifactUrl,
-        resolvedVersion: status.resolvedVersion,
-        resolvedRevision: status.resolvedRevision,
-        stashRoot: status.stashRoot,
-        cacheDir: status.cacheDir,
-        extractedDir: status.extractedDir,
-        installedAt: status.installedAt,
-    };
+    return { ...status };
 }
 function cleanupDirectoryBestEffort(target) {
     try {

package/dist/kit-include.js

@@ -0,0 +1,108 @@
+import fs from "node:fs";
+import path from "node:path";
+import { isWithin } from "./common";
+// ── Helpers ─────────────────────────────────────────────────────────────────
+/** Keys to check in package.json for akm include configuration. */
+const INCLUDE_CONFIG_KEYS = ["akm", "agentikit"];
+function readPackageJsonAt(dirPath) {
+    try {
+        const raw = fs.readFileSync(path.join(dirPath, "package.json"), "utf8");
+        const parsed = JSON.parse(raw);
+        if (typeof parsed === "object" && parsed !== null && !Array.isArray(parsed)) {
+            return parsed;
+        }
+        return undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+function extractIncludeList(pkg) {
+    if (!pkg)
+        return undefined;
+    for (const key of INCLUDE_CONFIG_KEYS) {
+        const config = pkg[key];
+        if (typeof config !== "object" || config === null || Array.isArray(config))
+            continue;
+        const { include } = config;
+        if (!Array.isArray(include))
+            continue;
+        const list = include
+            .filter((v) => typeof v === "string")
+            .map((v) => v.trim())
+            .filter(Boolean);
+        if (list.length > 0)
+            return list;
+    }
+    return undefined;
+}
+// ── Public API ───────────────────────────────────────────────────────────────
+/**
+ * Walk up the directory tree from `startDir` to `boundary` (inclusive) looking
+ * for a package.json that declares an `akm.include` or `agentikit.include` list.
+ * Returns the first config found, or `undefined` if none is found within the
+ * boundary.
+ */
+export function findNearestIncludeConfig(startDir, boundary) {
+    let current = path.resolve(startDir);
+    const resolvedBoundary = path.resolve(boundary);
+    while (isWithin(current, resolvedBoundary)) {
+        const pkg = readPackageJsonAt(current);
+        const include = extractIncludeList(pkg);
+        if (include && include.length > 0) {
+            return { baseDir: current, include };
+        }
+        if (current === resolvedBoundary)
+            break;
+        const parent = path.dirname(current);
+        if (parent === current)
+            break;
+        current = parent;
+    }
+    return undefined;
+}
+/**
+ * Copy each glob/path in `includeGlobs` from `sourceDir` to `destDir`.
+ *
+ * Uses `isWithin()` to prevent path-traversal attacks: any entry that escapes
+ * `sourceDir` throws immediately rather than silently being skipped.
+ *
+ * @throws {Error} if an include path escapes `sourceDir` or does not exist on disk.
+ */
+export function copyIncludedPaths(includeGlobs, sourceDir, destDir) {
+    for (const entry of includeGlobs) {
+        const resolvedSource = path.resolve(sourceDir, entry);
+        if (!isWithin(resolvedSource, sourceDir)) {
+            throw new Error(`Path in akm.include escapes the package root: ${entry}`);
+        }
+        if (!fs.existsSync(resolvedSource)) {
+            throw new Error(`Path in akm.include does not exist: ${entry}`);
+        }
+        if (path.basename(resolvedSource) === ".git") {
+            continue;
+        }
+        const relativePath = path.relative(sourceDir, resolvedSource);
+        if (!relativePath || relativePath === ".") {
+            copyDirectoryContents(sourceDir, destDir);
+            continue;
+        }
+        copyPath(resolvedSource, path.join(destDir, relativePath));
+    }
+}
+// ── Private helpers ─────────────────────────────────────────────────────────
+function copyDirectoryContents(sourceDir, destinationDir) {
+    for (const entry of fs.readdirSync(sourceDir, { withFileTypes: true })) {
+        if (entry.name === ".git")
+            continue;
+        copyPath(path.join(sourceDir, entry.name), path.join(destinationDir, entry.name));
+    }
+}
+function copyPath(sourcePath, destinationPath) {
+    const stat = fs.statSync(sourcePath);
+    fs.mkdirSync(path.dirname(destinationPath), { recursive: true });
+    if (stat.isDirectory()) {
+        fs.cpSync(sourcePath, destinationPath, { recursive: true, force: true });
+        return;
+    }
+    fs.copyFileSync(sourcePath, destinationPath);
+}