agentikit 0.0.7 → 0.0.9

package/dist/src/frontmatter.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Shared frontmatter parsing utilities.
+ *
+ * Provides a single, canonical YAML-subset frontmatter parser used by both
+ * the stash open logic and the metadata generator.
+ */
+/**
+ * Parse YAML-subset frontmatter from a Markdown (or similar) string.
+ *
+ * Returns the parsed key-value data and the remaining body content.
+ */
+export declare function parseFrontmatter(raw: string): {
+    data: Record<string, unknown>;
+    content: string;
+    frontmatter: string | null;
+    bodyStartLine: number;
+};
+export declare function parseFrontmatterBlock(raw: string): {
+    frontmatter: string;
+    content: string;
+    bodyStartLine: number;
+} | null;
+/**
+ * Parse a simple YAML scalar value (string, boolean, or number).
+ */
+export declare function parseYamlScalar(value: string): unknown;
+/**
+ * Coerce an unknown value to a trimmed string, or return undefined if empty/non-string.
+ */
+export declare function toStringOrUndefined(value: unknown): string | undefined;

package/dist/src/frontmatter.js

@@ -0,0 +1,86 @@
+/**
+ * Shared frontmatter parsing utilities.
+ *
+ * Provides a single, canonical YAML-subset frontmatter parser used by both
+ * the stash open logic and the metadata generator.
+ */
+/**
+ * Parse YAML-subset frontmatter from a Markdown (or similar) string.
+ *
+ * Returns the parsed key-value data and the remaining body content.
+ */
+export function parseFrontmatter(raw) {
+    const parsedBlock = parseFrontmatterBlock(raw);
+    if (!parsedBlock) {
+        return { data: {}, content: raw, frontmatter: null, bodyStartLine: 1 };
+    }
+    const data = {};
+    let currentKey = null;
+    let nested = null;
+    for (const line of parsedBlock.frontmatter.split(/\r?\n/)) {
+        const indented = line.match(/^  (\w[\w-]*):\s*(.+)$/);
+        if (indented && currentKey && nested) {
+            nested[indented[1]] = parseYamlScalar(indented[2].trim());
+            continue;
+        }
+        const top = line.match(/^(\w[\w-]*):\s*(.*)$/);
+        if (!top) {
+            continue;
+        }
+        currentKey = top[1];
+        const value = top[2].trim();
+        if (value === "") {
+            nested = {};
+            data[currentKey] = nested;
+        }
+        else {
+            nested = null;
+            data[currentKey] = parseYamlScalar(value);
+        }
+    }
+    return {
+        data,
+        content: parsedBlock.content,
+        frontmatter: parsedBlock.frontmatter,
+        bodyStartLine: parsedBlock.bodyStartLine,
+    };
+}
+export function parseFrontmatterBlock(raw) {
+    const match = raw.match(/^---\r?\n([\s\S]*?)\r?\n---\r?\n?([\s\S]*)$/);
+    if (!match)
+        return null;
+    return {
+        frontmatter: match[1],
+        content: match[2],
+        bodyStartLine: countLines(raw.slice(0, match[0].length - match[2].length)) + 1,
+    };
+}
+function countLines(text) {
+    if (text.length === 0)
+        return 0;
+    return text.split(/\r?\n/).length - 1;
+}
+/**
+ * Parse a simple YAML scalar value (string, boolean, or number).
+ */
+export function parseYamlScalar(value) {
+    if (value === "")
+        return "";
+    if (value === "true")
+        return true;
+    if (value === "false")
+        return false;
+    const asNumber = Number(value);
+    if (!Number.isNaN(asNumber))
+        return asNumber;
+    if ((value.startsWith('"') && value.endsWith('"')) || (value.startsWith("'") && value.endsWith("'"))) {
+        return value.slice(1, -1);
+    }
+    return value;
+}
+/**
+ * Coerce an unknown value to a trimmed string, or return undefined if empty/non-string.
+ */
+export function toStringOrUndefined(value) {
+    return typeof value === "string" && value.trim() ? value : undefined;
+}

package/dist/src/indexer.d.ts

@@ -1,26 +1,44 @@
 import { type StashEntry } from "./metadata";
+import { type SerializedTfIdf } from "./similarity";
+import type { EmbeddingVector } from "./embedder";
 export interface IndexedEntry {
     entry: StashEntry;
     path: string;
     dirPath: string;
+    embedding?: EmbeddingVector;
 }
 export interface SearchIndex {
     version: number;
     builtAt: string;
     stashDir: string;
+    /** All stash directories that were indexed (primary + additional) */
+    stashDirs?: string[];
     entries: IndexedEntry[];
     /** Serialized TF-IDF state (term frequencies, idf values) */
-    tfidf?: unknown;
+    tfidf?: SerializedTfIdf;
+    /** Whether embeddings are included in entries */
+    hasEmbeddings?: boolean;
 }
 export interface IndexResponse {
     stashDir: string;
     totalEntries: number;
     generatedMetadata: number;
     indexPath: string;
+    mode: "full" | "incremental";
+    directoriesScanned: number;
+    directoriesSkipped: number;
+    /** Timing counters in milliseconds */
+    timing?: {
+        totalMs: number;
+        walkMs: number;
+        embedMs: number;
+        tfidfMs: number;
+    };
 }
 export declare function getIndexPath(): string;
 export declare function loadSearchIndex(): SearchIndex | null;
 export declare function agentikitIndex(options?: {
     stashDir?: string;
-}): IndexResponse;
+    full?: boolean;
+}): Promise<IndexResponse>;
 export declare function buildSearchText(entry: StashEntry): string;

package/dist/src/indexer.js

@@ -1,16 +1,12 @@
 import fs from "node:fs";
 import path from "node:path";
+import { resolveStashDir } from "./common";
+import { ASSET_TYPES, TYPE_DIRS, deriveCanonicalAssetName } from "./asset-spec";
 import { loadStashFile, writeStashFile, generateMetadata, } from "./metadata";
 import { TfIdfAdapter } from "./similarity";
+import { walkStash } from "./walker";
 // ── Constants ───────────────────────────────────────────────────────────────
-const INDEX_VERSION = 1;
-const SCRIPT_EXTENSIONS = new Set([".sh", ".ts", ".js", ".ps1", ".cmd", ".bat"]);
-const TYPE_DIRS = {
-    tool: "tools",
-    skill: "skills",
-    command: "commands",
-    agent: "agents",
-};
+const INDEX_VERSION = 4;
 // ── Index Path ──────────────────────────────────────────────────────────────
 export function getIndexPath() {
     const cacheDir = process.env.XDG_CACHE_HOME
@@ -32,37 +28,98 @@ export function loadSearchIndex() {
     }
 }
 // ── Indexer ──────────────────────────────────────────────────────────────────
-export function agentikitIndex(options) {
-    const stashDir = options?.stashDir || resolveStashDirForIndex();
+export async function agentikitIndex(options) {
+    const stashDir = options?.stashDir || resolveStashDir();
+    // Load config to get additional stash dirs and semantic search setting
+    const { loadConfig } = await import("./config.js");
+    const config = loadConfig(stashDir);
+    const allStashDirs = [stashDir];
+    for (const d of config.additionalStashDirs) {
+        try {
+            if (fs.statSync(d).isDirectory() && !allStashDirs.includes(path.resolve(d))) {
+                allStashDirs.push(path.resolve(d));
+            }
+        }
+        catch { /* skip nonexistent dirs */ }
+    }
+    const t0 = Date.now();
     const allEntries = [];
     let generatedCount = 0;
-    for (const assetType of Object.keys(TYPE_DIRS)) {
-        const typeRoot = path.join(stashDir, TYPE_DIRS[assetType]);
-        if (!fs.existsSync(typeRoot) || !fs.statSync(typeRoot).isDirectory())
-            continue;
-        // Group files by their immediate parent directory
-        const dirGroups = collectDirectoryGroups(typeRoot, assetType);
-        for (const [dirPath, files] of dirGroups) {
-            // Try loading existing .stash.json
-            let stash = loadStashFile(dirPath);
-            if (!stash) {
-                // Generate metadata
-                stash = generateMetadata(dirPath, assetType, files);
-                if (stash.entries.length > 0) {
-                    writeStashFile(dirPath, stash);
-                    generatedCount += stash.entries.length;
-                }
+    let scannedDirs = 0;
+    let skippedDirs = 0;
+    // Load previous index for incremental mode
+    const previousIndex = !options?.full ? loadSearchIndex() : null;
+    const isIncremental = previousIndex !== null && previousIndex.stashDir === stashDir;
+    const builtAtMs = isIncremental ? new Date(previousIndex.builtAt).getTime() : 0;
+    // Build lookup of previous entries by dirPath
+    const previousEntriesByDir = new Map();
+    if (isIncremental) {
+        for (const ie of previousIndex.entries) {
+            const list = previousEntriesByDir.get(ie.dirPath) || [];
+            list.push(ie);
+            previousEntriesByDir.set(ie.dirPath, list);
+        }
+    }
+    const seenPaths = new Set();
+    const tWalkStart = Date.now();
+    for (const currentStashDir of allStashDirs) {
+        for (const assetType of ASSET_TYPES) {
+            const typeRoot = path.join(currentStashDir, TYPE_DIRS[assetType]);
+            try {
+                if (!fs.statSync(typeRoot).isDirectory())
+                    continue;
+            }
+            catch {
+                continue;
             }
-            if (stash) {
-                for (const entry of stash.entries) {
-                    const entryPath = entry.entry
-                        ? path.join(dirPath, entry.entry)
-                        : files[0] || dirPath;
-                    allEntries.push({ entry, path: entryPath, dirPath });
+            // Group files by their immediate parent directory
+            const dirGroups = walkStash(typeRoot, assetType);
+            for (const { dirPath, files } of dirGroups) {
+                // Deduplicate by dirPath across stash dirs
+                if (seenPaths.has(path.resolve(dirPath)))
+                    continue;
+                seenPaths.add(path.resolve(dirPath));
+                // Incremental: skip directories that haven't changed
+                const prevEntries = previousEntriesByDir.get(dirPath);
+                if (isIncremental && prevEntries && !isDirStale(dirPath, files, prevEntries, builtAtMs)) {
+                    allEntries.push(...prevEntries);
+                    skippedDirs++;
+                    continue;
+                }
+                scannedDirs++;
+                // Try loading existing .stash.json
+                let stash = loadStashFile(dirPath);
+                if (stash) {
+                    const migration = migrateGeneratedSkillMetadata(stash, files, typeRoot);
+                    if (migration.changed) {
+                        stash = migration.stash;
+                        writeStashFile(dirPath, stash);
+                    }
+                }
+                if (!stash) {
+                    // Generate metadata
+                    stash = generateMetadata(dirPath, assetType, files, typeRoot);
+                    // Enhance with LLM if configured
+                    if (config.llm && stash.entries.length > 0) {
+                        stash = await enhanceStashWithLlm(config.llm, stash, dirPath, files);
+                    }
+                    if (stash.entries.length > 0) {
+                        writeStashFile(dirPath, stash);
+                        generatedCount += stash.entries.length;
+                    }
+                }
+                if (stash) {
+                    for (const entry of stash.entries) {
+                        const entryPath = entry.entry
+                            ? path.join(dirPath, entry.entry)
+                            : files[0] || dirPath;
+                        allEntries.push({ entry, path: entryPath, dirPath });
+                    }
                 }
             }
         }
     }
+    const tWalkEnd = Date.now();
     // Build TF-IDF index
     const adapter = new TfIdfAdapter();
     const scoredEntries = allEntries.map((ie) => ({
@@ -72,6 +129,25 @@ export function agentikitIndex(options) {
         path: ie.path,
     }));
     adapter.buildIndex(scoredEntries);
+    const tTfidfEnd = Date.now();
+    // Generate embeddings if semantic search is enabled
+    let hasEmbeddings = false;
+    if (config.semanticSearch) {
+        try {
+            const { embed } = await import("./embedder.js");
+            for (const ie of allEntries) {
+                if (!ie.embedding) {
+                    const text = buildSearchText(ie.entry);
+                    ie.embedding = await embed(text, config.embedding);
+                }
+            }
+            hasEmbeddings = true;
+        }
+        catch {
+            // Embedding provider not available, continue without embeddings
+        }
+    }
+    const tEmbedEnd = Date.now();
     // Persist index
     const indexPath = getIndexPath();
     const indexDir = path.dirname(indexPath);
@@ -82,59 +158,119 @@ export function agentikitIndex(options) {
         version: INDEX_VERSION,
         builtAt: new Date().toISOString(),
         stashDir,
+        stashDirs: allStashDirs,
         entries: allEntries,
         tfidf: adapter.serialize(),
+        hasEmbeddings,
     };
     fs.writeFileSync(indexPath, JSON.stringify(index) + "\n", "utf8");
+    const tEnd = Date.now();
     return {
         stashDir,
         totalEntries: allEntries.length,
         generatedMetadata: generatedCount,
         indexPath,
+        mode: isIncremental ? "incremental" : "full",
+        directoriesScanned: scannedDirs,
+        directoriesSkipped: skippedDirs,
+        timing: {
+            totalMs: tEnd - t0,
+            walkMs: tWalkEnd - tWalkStart, // includes metadata generation (interleaved)
+            embedMs: tEmbedEnd - tTfidfEnd,
+            tfidfMs: tTfidfEnd - tWalkEnd,
+        },
     };
 }
 // ── Helpers ─────────────────────────────────────────────────────────────────
-function collectDirectoryGroups(typeRoot, assetType) {
-    const groups = new Map();
-    const walk = (dir) => {
-        if (!fs.existsSync(dir))
-            return;
-        const entries = fs.readdirSync(dir, { withFileTypes: true });
-        for (const entry of entries) {
-            if (entry.name === ".stash.json")
-                continue;
-            const fullPath = path.join(dir, entry.name);
-            if (entry.isDirectory()) {
-                walk(fullPath);
-            }
-            else if (entry.isFile() && isRelevantFile(entry.name, assetType)) {
-                const parentDir = path.dirname(fullPath);
-                const existing = groups.get(parentDir);
-                if (existing) {
-                    existing.push(fullPath);
-                }
-                else {
-                    groups.set(parentDir, [fullPath]);
-                }
-            }
+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 currFileNames = new Set(currentFiles.map((f) => path.basename(f)));
+    if (prevFileNames.size !== currFileNames.size)
+        return true;
+    for (const name of currFileNames) {
+        if (!prevFileNames.has(name))
+            return true;
+    }
+    // Check modification times of current files
+    for (const file of currentFiles) {
+        try {
+            if (fs.statSync(file).mtimeMs > builtAtMs)
+                return true;
+        }
+        catch {
+            return true;
         }
+    }
+    // Check .stash.json modification time
+    const stashPath = path.join(dirPath, ".stash.json");
+    try {
+        if (fs.existsSync(stashPath) && fs.statSync(stashPath).mtimeMs > builtAtMs)
+            return true;
+    }
+    catch {
+        // ignore
+    }
+    return false;
+}
+function migrateGeneratedSkillMetadata(stash, files, typeRoot) {
+    const fileByBaseName = new Map(files.map((filePath) => [path.basename(filePath), filePath]));
+    let changed = false;
+    const entries = stash.entries.map((entry) => {
+        if (entry.type !== "skill" || entry.generated !== true)
+            return entry;
+        const hintedFilePath = entry.entry ? fileByBaseName.get(path.basename(entry.entry)) : undefined;
+        const skillFilePath = hintedFilePath ?? fileByBaseName.get("SKILL.md");
+        if (!skillFilePath)
+            return entry;
+        const canonicalName = deriveCanonicalAssetName("skill", typeRoot, skillFilePath);
+        if (!canonicalName || canonicalName === entry.name)
+            return entry;
+        changed = true;
+        return { ...entry, name: canonicalName };
+    });
+    if (!changed) {
+        return { stash, changed: false };
+    }
+    return {
+        stash: { entries },
+        changed: true,
     };
-    walk(typeRoot);
-    return groups;
 }
-function isRelevantFile(fileName, assetType) {
-    const ext = path.extname(fileName).toLowerCase();
-    switch (assetType) {
-        case "tool":
-            return SCRIPT_EXTENSIONS.has(ext);
-        case "skill":
-            return fileName === "SKILL.md";
-        case "command":
-        case "agent":
-            return ext === ".md";
-        default:
-            return false;
+async function enhanceStashWithLlm(llmConfig, stash, dirPath, files) {
+    const { enhanceMetadata } = await import("./llm.js");
+    const enhanced = [];
+    for (const entry of stash.entries) {
+        try {
+            // Find the file matching this entry for content context
+            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 */ }
+            }
+            const improvements = await enhanceMetadata(llmConfig, entry, fileContent);
+            const updated = { ...entry };
+            if (improvements.description)
+                updated.description = improvements.description;
+            if (improvements.intents?.length)
+                updated.intents = improvements.intents;
+            if (improvements.tags?.length)
+                updated.tags = improvements.tags;
+            enhanced.push(updated);
+        }
+        catch {
+            // LLM enhancement failed for this entry, keep original
+            enhanced.push(entry);
+        }
     }
+    return { entries: enhanced };
 }
 export function buildSearchText(entry) {
     const parts = [entry.name.replace(/[-_]/g, " ")];
@@ -144,6 +280,10 @@ export function buildSearchText(entry) {
         parts.push(entry.tags.join(" "));
     if (entry.examples)
         parts.push(entry.examples.join(" "));
+    if (entry.aliases)
+        parts.push(entry.aliases.join(" "));
+    if (entry.intents)
+        parts.push(entry.intents.join(" "));
     if (entry.intent) {
         if (entry.intent.when)
             parts.push(entry.intent.when);
@@ -152,16 +292,8 @@ export function buildSearchText(entry) {
         if (entry.intent.output)
             parts.push(entry.intent.output);
     }
-    return parts.join(" ").toLowerCase();
-}
-function resolveStashDirForIndex() {
-    const raw = process.env.AGENTIKIT_STASH_DIR?.trim();
-    if (!raw) {
-        throw new Error("AGENTIKIT_STASH_DIR is not set. Run 'agentikit init' first.");
+    if (entry.toc) {
+        parts.push(entry.toc.map((h) => h.text).join(" "));
     }
-    const stashDir = path.resolve(raw);
-    if (!fs.existsSync(stashDir) || !fs.statSync(stashDir).isDirectory()) {
-        throw new Error(`AGENTIKIT_STASH_DIR does not exist or is not a directory: "${stashDir}"`);
-    }
-    return stashDir;
+    return parts.join(" ").toLowerCase();
 }

package/dist/src/init.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Agentikit initialization logic.
+ *
+ * Creates the stash directory structure, sets the AGENTIKIT_STASH_DIR
+ * environment variable, and ensures ripgrep is available.
+ */
+export interface InitResponse {
+    stashDir: string;
+    created: boolean;
+    envSet: boolean;
+    profileUpdated?: string;
+    configPath: string;
+    ripgrep?: {
+        rgPath: string;
+        installed: boolean;
+        version: string;
+    };
+}
+export declare function agentikitInit(): InitResponse;

package/dist/src/init.js

@@ -0,0 +1,87 @@
+/**
+ * Agentikit initialization logic.
+ *
+ * Creates the stash directory structure, sets the AGENTIKIT_STASH_DIR
+ * environment variable, and ensures ripgrep is available.
+ */
+import { spawnSync } from "node:child_process";
+import fs from "node:fs";
+import path from "node:path";
+import { IS_WINDOWS, TYPE_DIRS } from "./common";
+import { ensureRg } from "./ripgrep-install";
+import { getConfigPath, saveConfig, DEFAULT_CONFIG } from "./config";
+export function agentikitInit() {
+    let stashDir;
+    if (IS_WINDOWS) {
+        const userProfile = process.env.USERPROFILE?.trim();
+        if (!userProfile) {
+            throw new Error("Unable to determine Documents folder. Ensure USERPROFILE is set.");
+        }
+        const docs = path.join(userProfile, "Documents");
+        stashDir = path.join(docs, "agentikit");
+    }
+    else {
+        const home = process.env.HOME?.trim();
+        if (!home) {
+            throw new Error("Unable to determine home directory. Set HOME.");
+        }
+        stashDir = path.join(home, "agentikit");
+    }
+    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 });
+        }
+    }
+    let envSet = false;
+    let profileUpdated;
+    if (IS_WINDOWS) {
+        const result = spawnSync("setx", ["AGENTIKIT_STASH_DIR", stashDir], {
+            encoding: "utf8",
+            timeout: 10_000,
+        });
+        envSet = result.status === 0;
+    }
+    else {
+        const shell = process.env.SHELL || "";
+        const homeDir = process.env.HOME; // already validated non-empty above
+        let profile;
+        if (shell.endsWith("/zsh")) {
+            profile = path.join(homeDir, ".zshrc");
+        }
+        else if (shell.endsWith("/bash")) {
+            profile = path.join(homeDir, ".bashrc");
+        }
+        else {
+            profile = path.join(homeDir, ".profile");
+        }
+        const exportLine = `export AGENTIKIT_STASH_DIR="${stashDir}"`;
+        const existing = fs.existsSync(profile) ? fs.readFileSync(profile, "utf8") : "";
+        if (!existing.includes("AGENTIKIT_STASH_DIR")) {
+            fs.appendFileSync(profile, `\n# Agentikit stash directory\n${exportLine}\n`);
+            envSet = true;
+            profileUpdated = profile;
+        }
+    }
+    // Create default config.json if it doesn't exist
+    const configPath = getConfigPath(stashDir);
+    if (!fs.existsSync(configPath)) {
+        saveConfig(DEFAULT_CONFIG, stashDir);
+    }
+    process.env.AGENTIKIT_STASH_DIR = stashDir;
+    // Ensure ripgrep is available (install to stash/bin if needed)
+    let ripgrep;
+    try {
+        const rgResult = ensureRg(stashDir);
+        ripgrep = rgResult;
+    }
+    catch {
+        // Non-fatal: ripgrep is optional, search works without it
+    }
+    return { stashDir, created, envSet, profileUpdated, configPath, ripgrep };
+}

package/dist/src/llm.d.ts

@@ -0,0 +1,15 @@
+import type { LlmConnectionConfig } from "./config";
+import type { StashEntry } from "./metadata";
+/**
+ * Use an LLM to enhance a stash entry's metadata: improve description,
+ * generate intents, and suggest tags.
+ */
+export declare function enhanceMetadata(config: LlmConnectionConfig, entry: StashEntry, fileContent?: string): Promise<{
+    description?: string;
+    intents?: string[];
+    tags?: string[];
+}>;
+/**
+ * Check if the LLM endpoint is reachable.
+ */
+export declare function isLlmAvailable(config: LlmConnectionConfig): Promise<boolean>;