agentikit 0.0.13 → 0.0.15

package/dist/handlers/handler-bridge.js

@@ -0,0 +1,51 @@
+/**
+ * Bridge utility that converts legacy ShowInput into a RenderContext,
+ * allowing handlers to delegate their buildShowResponse to renderers.
+ */
+import path from "node:path";
+import { toPosix } from "../common";
+/**
+ * Convert a legacy ShowInput into a RenderContext suitable for passing
+ * to an AssetRenderer's buildShowResponse method.
+ *
+ * This avoids hitting the filesystem since ShowInput already carries
+ * the file content.
+ */
+export function showInputToRenderContext(input, rendererName) {
+    const absPath = path.resolve(input.path);
+    const stashDirs = input.stashDirs ?? [];
+    // Derive a stash root from stashDirs if possible
+    const stashRoot = stashDirs.find((d) => absPath.startsWith(path.resolve(d) + path.sep)) ?? stashDirs[0] ?? path.dirname(absPath);
+    const relPath = toPosix(path.relative(stashRoot, absPath));
+    const ext = path.extname(absPath).toLowerCase();
+    const fileName = path.basename(absPath);
+    const parentDirAbs = path.dirname(absPath);
+    const parentDir = path.basename(parentDirAbs);
+    const relDir = toPosix(path.dirname(relPath));
+    const ancestorDirs = relDir === "." ? [] : relDir.split("/").filter((seg) => seg.length > 0);
+    // Cache the content from input (no filesystem read needed)
+    const cachedContent = input.content;
+    const matchResult = {
+        type: rendererName.split("-")[0], // e.g. "tool" from "tool-script"
+        specificity: 10,
+        renderer: rendererName,
+        meta: { name: input.name, view: input.view },
+    };
+    return {
+        absPath,
+        relPath,
+        ext,
+        fileName,
+        parentDir,
+        parentDirAbs,
+        ancestorDirs,
+        stashRoot,
+        content: () => cachedContent,
+        frontmatter: () => null, // Renderers parse frontmatter from content() themselves
+        stat() {
+            throw new Error("stat() not available in handler bridge context");
+        },
+        matchResult,
+        stashDirs,
+    };
+}

package/dist/handlers/index.js

@@ -0,0 +1,19 @@
+import { registerAssetType } from "../asset-type-handler";
+import { agentHandler } from "./agent-handler";
+import { commandHandler } from "./command-handler";
+import { knowledgeHandler } from "./knowledge-handler";
+import { scriptHandler } from "./script-handler";
+import { skillHandler } from "./skill-handler";
+import { toolHandler } from "./tool-handler";
+/**
+ * Register all built-in asset type handlers.
+ * Called once from ensureHandlersRegistered in asset-type-handler.ts.
+ */
+export function registerBuiltinHandlers() {
+    registerAssetType(toolHandler);
+    registerAssetType(skillHandler);
+    registerAssetType(commandHandler);
+    registerAssetType(agentHandler);
+    registerAssetType(knowledgeHandler);
+    registerAssetType(scriptHandler);
+}

package/dist/handlers/knowledge-handler.js

@@ -0,0 +1,32 @@
+import fs from "node:fs";
+import { getRenderer } from "../file-context";
+import { parseMarkdownToc } from "../markdown";
+import { showInputToRenderContext } from "./handler-bridge";
+import { isMarkdownFile, markdownAssetPath, markdownCanonicalName } from "./markdown-helpers";
+export const knowledgeHandler = {
+    typeName: "knowledge",
+    stashDir: "knowledge",
+    isRelevantFile: isMarkdownFile,
+    toCanonicalName: markdownCanonicalName,
+    toAssetPath: markdownAssetPath,
+    buildShowResponse(input) {
+        const renderer = getRenderer("knowledge-md");
+        const ctx = showInputToRenderContext(input, "knowledge-md");
+        return renderer.buildShowResponse(ctx);
+    },
+    defaultUsageGuide: [
+        "Use `akm show <openRef>` to read the document; start with `--view toc` for large files.",
+        "Use `--view section` or `--view lines` to load only the part you need.",
+    ],
+    extractTypeMetadata(entry, file) {
+        try {
+            const mdContent = fs.readFileSync(file, "utf8");
+            const toc = parseMarkdownToc(mdContent);
+            if (toc.headings.length > 0)
+                entry.toc = toc.headings;
+        }
+        catch {
+            // Non-fatal: skip TOC if file can't be read
+        }
+    },
+};

package/dist/handlers/script-handler.js

@@ -0,0 +1,42 @@
+import path from "node:path";
+import { SCRIPT_EXTENSIONS_BROAD } from "../asset-spec";
+import { toPosix } from "../common";
+import { getRenderer } from "../file-context";
+import { extractDescriptionFromComments } from "../metadata";
+import { showInputToRenderContext } from "./handler-bridge";
+export const scriptHandler = {
+    typeName: "script",
+    stashDir: "scripts",
+    isRelevantFile(fileName) {
+        return SCRIPT_EXTENSIONS_BROAD.has(path.extname(fileName).toLowerCase());
+    },
+    toCanonicalName(typeRoot, filePath) {
+        return toPosix(path.relative(typeRoot, filePath));
+    },
+    toAssetPath(typeRoot, name) {
+        return path.join(typeRoot, name);
+    },
+    buildShowResponse(input) {
+        const renderer = getRenderer("script-source");
+        const ctx = showInputToRenderContext(input, "script-source");
+        return renderer.buildShowResponse(ctx);
+    },
+    enrichSearchHit(hit, stashDir) {
+        const renderer = getRenderer("script-source");
+        renderer.enrichSearchHit(hit, stashDir);
+    },
+    defaultUsageGuide: [
+        "Use the hit's runCmd for execution when available, or run the script directly with the appropriate interpreter.",
+        "Use `akm show <openRef>` to inspect the script before running it.",
+    ],
+    extractTypeMetadata(entry, file, ext) {
+        if (ext !== ".md") {
+            const commentDesc = extractDescriptionFromComments(file);
+            if (commentDesc && !entry.description) {
+                entry.description = commentDesc;
+                entry.source = "comments";
+                entry.confidence = 0.7;
+            }
+        }
+    },
+};

package/dist/{src/handlers → handlers}/skill-handler.js

@@ -1,5 +1,7 @@
 import path from "node:path";
 import { toPosix } from "../common";
+import { getRenderer } from "../file-context";
+import { showInputToRenderContext } from "./handler-bridge";
 export const skillHandler = {
     typeName: "skill",
     stashDir: "skills",
@@ -16,12 +18,9 @@ export const skillHandler = {
         return path.join(typeRoot, name, "SKILL.md");
     },
     buildShowResponse(input) {
-        return {
-            type: "skill",
-            name: input.name,
-            path: input.path,
-            content: input.content,
-        };
+        const renderer = getRenderer("skill-md");
+        const ctx = showInputToRenderContext(input, "skill-md");
+        return renderer.buildShowResponse(ctx);
     },
     defaultUsageGuide: [
         "Read and apply the skill instructions as written, then adapt examples to your current repo state and task.",

package/dist/{src/handlers → handlers}/tool-handler.js

@@ -1,8 +1,9 @@
 import path from "node:path";
 import { SCRIPT_EXTENSIONS } from "../asset-spec";
-import { hasErrnoCode, toPosix } from "../common";
-import { buildToolInfo } from "../tool-runner";
+import { toPosix } from "../common";
+import { getRenderer } from "../file-context";
 import { extractDescriptionFromComments } from "../metadata";
+import { showInputToRenderContext } from "./handler-bridge";
 export const toolHandler = {
     typeName: "tool",
     stashDir: "tools",
@@ -16,30 +17,13 @@ export const toolHandler = {
         return path.join(typeRoot, name);
     },
     buildShowResponse(input) {
-        const stashDirs = input.stashDirs ?? [];
-        const assetStashDir = stashDirs.find((d) => path.resolve(input.path).startsWith(path.resolve(d) + path.sep)) ?? stashDirs[0];
-        if (!assetStashDir) {
-            return { type: "tool", name: input.name, path: input.path, content: input.content };
-        }
-        const toolInfo = buildToolInfo(assetStashDir, input.path);
-        return {
-            type: "tool",
-            name: input.name,
-            path: input.path,
-            runCmd: toolInfo.runCmd,
-            kind: toolInfo.kind,
-        };
+        const renderer = getRenderer("tool-script");
+        const ctx = showInputToRenderContext(input, "tool-script");
+        return renderer.buildShowResponse(ctx);
     },
     enrichSearchHit(hit, stashDir) {
-        try {
-            const toolInfo = buildToolInfo(stashDir, hit.path);
-            hit.runCmd = toolInfo.runCmd;
-            hit.kind = toolInfo.kind;
-        }
-        catch (error) {
-            if (!hasErrnoCode(error, "ENOENT"))
-                throw error;
-        }
+        const renderer = getRenderer("tool-script");
+        renderer.enrichSearchHit(hit, stashDir);
     },
     defaultUsageGuide: [
         "Use the hit's runCmd for execution so runtime and working directory stay correct.",

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

@@ -1,10 +1,12 @@
 import fs from "node:fs";
 import path from "node:path";
+import { ASSET_TYPES, deriveCanonicalAssetName, TYPE_DIRS } from "./asset-spec";
 import { resolveStashDir } from "./common";
-import { ASSET_TYPES, TYPE_DIRS, deriveCanonicalAssetName } from "./asset-spec";
-import { loadStashFile, writeStashFile, generateMetadata, } from "./metadata";
+import { closeDatabase, DB_VERSION, deleteEntriesByDir, getEntriesByDir, getEntryCount, getMeta, isVecAvailable, openDatabase, rebuildFts, setMeta, upsertEmbedding, upsertEntry, warnIfVecMissing, } from "./db";
+import { generateMetadata, loadStashFile, writeStashFile } from "./metadata";
+import { getDbPath } from "./paths";
 import { walkStash } from "./walker";
-import { openDatabase, closeDatabase, getDbPath, getMeta, setMeta, upsertEntry, deleteEntriesByDir, rebuildFts, upsertEmbedding, getEntriesByDir, getEntryCount, isVecAvailable, DB_VERSION, } from "./db";
+import { warn } from "./warn";
 // ── Indexer ──────────────────────────────────────────────────────────────────
 export async function agentikitIndex(options) {
     const stashDir = options?.stashDir || resolveStashDir();
@@ -26,14 +28,23 @@ export async function agentikitIndex(options) {
         const builtAtMs = isIncremental ? new Date(prevBuiltAt).getTime() : 0;
         if (options?.full || !isIncremental) {
             // Wipe all entries for full rebuild or stashDir change
-            db.exec("DELETE FROM entries");
-            db.exec("DELETE FROM entries_fts");
-            if (isVecAvailable()) {
+            // 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 */ }
+                catch {
+                    /* ignore */
+                }
             }
+            db.exec("DELETE FROM entries_fts");
+            db.exec("DELETE FROM entries");
         }
         const tWalkStart = Date.now();
         // Walk stash dirs and index entries
@@ -54,6 +65,8 @@ export async function agentikitIndex(options) {
         setMeta(db, "stashDirs", JSON.stringify(allStashDirs));
         setMeta(db, "hasEmbeddings", hasEmbeddings ? "1" : "0");
         const totalEntries = getEntryCount(db);
+        // Warn on every index run if using JS fallback with many entries
+        warnIfVecMissing(db);
         const tEnd = Date.now();
         return {
             stashDir,
@@ -117,6 +130,18 @@ function indexEntries(db, allStashDirs, stashDir, isIncremental, builtAtMs) {
                             stash = migration.stash;
                             writeStashFile(dirPath, stash);
                         }
+                        // Check for files on disk that aren't covered by existing .stash.json entries.
+                        // This handles the case where new files are added after the initial index.
+                        const coveredFiles = new Set(stash.entries.map((e) => e.entry).filter((e) => !!e));
+                        const uncoveredFiles = files.filter((f) => !coveredFiles.has(path.basename(f)));
+                        if (uncoveredFiles.length > 0) {
+                            const generated = generateMetadata(dirPath, assetType, uncoveredFiles, typeRoot);
+                            if (generated.entries.length > 0) {
+                                stash = { entries: [...stash.entries, ...generated.entries] };
+                                writeStashFile(dirPath, stash);
+                                generatedCount += generated.entries.length;
+                            }
+                        }
                     }
                     if (!stash) {
                         // Generate metadata heuristically
@@ -128,9 +153,7 @@ function indexEntries(db, allStashDirs, stashDir, isIncremental, builtAtMs) {
                     }
                     if (stash) {
                         for (const entry of stash.entries) {
-                            const entryPath = entry.entry
-                                ? path.join(dirPath, entry.entry)
-                                : files[0] || dirPath;
+                            const entryPath = entry.entry ? path.join(dirPath, entry.entry) : files[0] || dirPath;
                             const entryKey = `${currentStashDir}:${entry.type}:${entry.name}`;
                             const searchText = buildSearchText(entry);
                             upsertEntry(db, entryKey, dirPath, entryPath, currentStashDir, entry, searchText);
@@ -166,19 +189,22 @@ async function enhanceDirsWithLlm(db, config, dirsNeedingLlm) {
     }
 }
 async function generateEmbeddingsForDb(db, config) {
-    if (!config.semanticSearch || !isVecAvailable())
+    if (!config.semanticSearch)
         return false;
     try {
-        const { embed } = await import("./embedder.js");
+        const { embedBatch } = await import("./embedder.js");
         const allEntries = getAllEntriesForEmbedding(db);
-        for (const { id, searchText } of allEntries) {
-            const embedding = await embed(searchText, config.embedding);
-            upsertEmbedding(db, id, embedding);
+        if (allEntries.length === 0)
+            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]);
         }
         return true;
     }
     catch (error) {
-        console.warn("Embedding generation failed, continuing without:", error instanceof Error ? error.message : String(error));
+        warn("Embedding generation failed, continuing without:", error instanceof Error ? error.message : String(error));
         return false;
     }
 }
@@ -187,15 +213,13 @@ function getAllEntriesForEmbedding(db) {
     return db
         .prepare(`
       SELECT e.id, e.search_text AS searchText FROM entries e
-      WHERE NOT EXISTS (SELECT 1 FROM entries_vec v WHERE v.id = e.id)
+      WHERE NOT EXISTS (SELECT 1 FROM embeddings b WHERE b.id = e.id)
     `)
         .all();
 }
 function isDirStale(dirPath, currentFiles, previousEntries, builtAtMs) {
     // Check if file set changed (additions or deletions)
-    const prevFileNames = new Set(previousEntries
-        .map((ie) => ie.entry.entry)
-        .filter((e) => !!e));
+    const prevFileNames = new Set(previousEntries.map((ie) => ie.entry.entry).filter((e) => !!e));
     const currFileNames = new Set(currentFiles.map((f) => path.basename(f)));
     if (prevFileNames.size !== currFileNames.size)
         return true;
@@ -216,11 +240,11 @@ function isDirStale(dirPath, currentFiles, previousEntries, builtAtMs) {
     // Check .stash.json modification time
     const stashPath = path.join(dirPath, ".stash.json");
     try {
-        if (fs.existsSync(stashPath) && fs.statSync(stashPath).mtimeMs > builtAtMs)
+        if (fs.statSync(stashPath).mtimeMs > builtAtMs)
             return true;
     }
     catch {
-        // ignore
+        // file doesn't exist, not stale
     }
     return false;
 }
@@ -253,15 +277,15 @@ async function enhanceStashWithLlm(llmConfig, stash, dirPath, files) {
     const enhanced = [];
     for (const entry of stash.entries) {
         try {
-            const entryFile = entry.entry
-                ? files.find((f) => path.basename(f) === entry.entry) ?? files[0]
-                : files[0];
+            const entryFile = entry.entry ? (files.find((f) => path.basename(f) === entry.entry) ?? files[0]) : files[0];
             let fileContent;
             if (entryFile) {
                 try {
                     fileContent = fs.readFileSync(entryFile, "utf8");
                 }
-                catch { /* ignore unreadable files */ }
+                catch {
+                    /* ignore unreadable files */
+                }
             }
             const improvements = await enhanceMetadata(llmConfig, entry, fileContent);
             const updated = { ...entry };

package/dist/init.js

@@ -0,0 +1,43 @@
+/**
+ * Agentikit initialization logic.
+ *
+ * Creates the working stash directory structure, persists the stashDir
+ * in config.json, and ensures ripgrep is available.
+ */
+import fs from "node:fs";
+import path from "node:path";
+import { TYPE_DIRS } from "./asset-spec";
+import { getConfigPath, loadConfig, saveConfig } from "./config";
+import { getBinDir, getDefaultStashDir } from "./paths";
+import { ensureRg } from "./ripgrep-install";
+export async function agentikitInit(options) {
+    const stashDir = options?.dir ? path.resolve(options.dir) : getDefaultStashDir();
+    let created = false;
+    if (!fs.existsSync(stashDir)) {
+        fs.mkdirSync(stashDir, { recursive: true });
+        created = true;
+    }
+    for (const sub of Object.values(TYPE_DIRS)) {
+        const subDir = path.join(stashDir, sub);
+        if (!fs.existsSync(subDir)) {
+            fs.mkdirSync(subDir, { recursive: true });
+        }
+    }
+    // Persist stashDir in config.json
+    const configPath = getConfigPath();
+    const existing = loadConfig();
+    if (!existing.stashDir || existing.stashDir !== stashDir) {
+        saveConfig({ ...existing, stashDir });
+    }
+    // Ensure ripgrep is available (install to cache/bin if needed)
+    let ripgrep;
+    try {
+        const binDir = getBinDir();
+        const rgResult = ensureRg(binDir);
+        ripgrep = rgResult;
+    }
+    catch {
+        // Non-fatal: ripgrep is optional, search works without it
+    }
+    return { stashDir, created, configPath, ripgrep };
+}

package/dist/{src/llm.js → llm.js}

@@ -28,19 +28,14 @@ const SYSTEM_PROMPT = `You are a metadata generator for a developer tool registr
  * generate intents, and suggest tags.
  */
 export async function enhanceMetadata(config, entry, fileContent) {
-    const contextParts = [
-        `Name: ${entry.name}`,
-        `Type: ${entry.type}`,
-    ];
+    const contextParts = [`Name: ${entry.name}`, `Type: ${entry.type}`];
     if (entry.description)
         contextParts.push(`Current description: ${entry.description}`);
     if (entry.tags?.length)
         contextParts.push(`Current tags: ${entry.tags.join(", ")}`);
     if (fileContent) {
         // Limit content to first 2000 chars to stay within token limits
-        const truncated = fileContent.length > 2000
-            ? fileContent.slice(0, 2000) + "\n... (truncated)"
-            : fileContent;
+        const truncated = fileContent.length > 2000 ? fileContent.slice(0, 2000) + "\n... (truncated)" : fileContent;
         contextParts.push(`File content:\n${truncated}`);
     }
     const userPrompt = `${contextParts.join("\n")}
@@ -64,7 +59,9 @@ Return ONLY the JSON object, no explanation.`;
             result.description = parsed.description;
         }
         if (Array.isArray(parsed.intents)) {
-            result.intents = parsed.intents.filter((s) => typeof s === "string" && s.trim().length > 0).slice(0, 8);
+            result.intents = parsed.intents
+                .filter((s) => typeof s === "string" && s.trim().length > 0)
+                .slice(0, 8);
         }
         if (Array.isArray(parsed.tags)) {
             result.tags = parsed.tags.filter((s) => typeof s === "string" && s.trim().length > 0).slice(0, 10);
@@ -81,9 +78,7 @@ Return ONLY the JSON object, no explanation.`;
  */
 export async function isLlmAvailable(config) {
     try {
-        const result = await chatCompletion(config, [
-            { role: "user", content: "Respond with just the word: ok" },
-        ]);
+        const result = await chatCompletion(config, [{ role: "user", content: "Respond with just the word: ok" }]);
         return result.length > 0;
     }
     catch {

package/dist/lockfile.js

@@ -0,0 +1,60 @@
+import fs from "node:fs";
+import path from "node:path";
+import { getConfigDir } from "./config";
+// ── Paths ───────────────────────────────────────────────────────────────────
+function getLockfilePath() {
+    return path.join(getConfigDir(), "stash.lock");
+}
+// ── Read / Write ────────────────────────────────────────────────────────────
+export function readLockfile() {
+    const lockfilePath = getLockfilePath();
+    try {
+        const raw = JSON.parse(fs.readFileSync(lockfilePath, "utf8"));
+        if (!Array.isArray(raw))
+            return [];
+        return raw.filter(isValidLockfileEntry);
+    }
+    catch {
+        return [];
+    }
+}
+export function writeLockfile(entries) {
+    const lockfilePath = getLockfilePath();
+    const dir = path.dirname(lockfilePath);
+    fs.mkdirSync(dir, { recursive: true });
+    const tmpPath = lockfilePath + `.tmp.${process.pid}`;
+    try {
+        fs.writeFileSync(tmpPath, JSON.stringify(entries, null, 2) + "\n", "utf8");
+        fs.renameSync(tmpPath, lockfilePath);
+    }
+    catch (err) {
+        try {
+            fs.unlinkSync(tmpPath);
+        }
+        catch {
+            /* ignore cleanup failure */
+        }
+        throw err;
+    }
+}
+export function upsertLockEntry(entry) {
+    const entries = readLockfile();
+    const withoutExisting = entries.filter((e) => e.id !== entry.id);
+    writeLockfile([...withoutExisting, entry]);
+}
+export function removeLockEntry(id) {
+    const entries = readLockfile();
+    writeLockfile(entries.filter((e) => e.id !== id));
+}
+// ── Helpers ─────────────────────────────────────────────────────────────────
+function isValidLockfileEntry(value) {
+    if (typeof value !== "object" || value === null || Array.isArray(value))
+        return false;
+    const obj = value;
+    return (typeof obj.id === "string" &&
+        obj.id !== "" &&
+        typeof obj.source === "string" &&
+        ["npm", "github", "git", "local"].includes(obj.source) &&
+        typeof obj.ref === "string" &&
+        obj.ref !== "");
+}