akm-cli 0.0.0 → 0.0.17

package/dist/file-context.js

@@ -0,0 +1,162 @@
+/**
+ * Flexible asset resolution system.
+ *
+ * Provides a rich FileContext built once per file during walking, plus a
+ * matcher/renderer registry that decouples asset classification from rendering.
+ */
+import fs from "node:fs";
+import path from "node:path";
+import { toPosix } from "./common";
+import { parseFrontmatter } from "./frontmatter";
+/**
+ * Build a FileContext from a stash root and an absolute file path.
+ *
+ * Path-derived fields are computed eagerly. The content, frontmatter, and
+ * stat getters use lazy caching so the file is only read from disk when
+ * (and if) a matcher or renderer actually needs it.
+ */
+export function buildFileContext(stashRoot, 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);
+    // Compute ancestor directory segments from the POSIX relPath's directory portion.
+    // For "scripts/azure/deploy/run.sh" the dir portion is "scripts/azure/deploy"
+    // which splits into ["scripts", "azure", "deploy"].
+    const relDir = toPosix(path.dirname(relPath));
+    const ancestorDirs = relDir === "." ? [] : relDir.split("/").filter((seg) => seg.length > 0);
+    // Lazy caches
+    let cachedContent;
+    let cachedFrontmatter;
+    let frontmatterComputed = false;
+    let cachedStat;
+    return {
+        absPath,
+        relPath,
+        ext,
+        fileName,
+        parentDir,
+        parentDirAbs,
+        ancestorDirs,
+        stashRoot,
+        content() {
+            if (cachedContent === undefined) {
+                cachedContent = fs.readFileSync(absPath, "utf8");
+            }
+            return cachedContent;
+        },
+        frontmatter() {
+            if (!frontmatterComputed) {
+                const raw = this.content();
+                const parsed = parseFrontmatter(raw);
+                cachedFrontmatter = Object.keys(parsed.data).length > 0 ? parsed.data : null;
+                frontmatterComputed = true;
+            }
+            return cachedFrontmatter ?? null;
+        },
+        stat() {
+            if (cachedStat === undefined) {
+                cachedStat = fs.statSync(absPath);
+            }
+            return cachedStat;
+        },
+    };
+}
+// ── Registry ─────────────────────────────────────────────────────────────────
+/** Ordered list of registered matchers. Later registrations win ties. */
+const matchers = [];
+/** Renderer lookup by name. */
+const renderers = new Map();
+let builtinsInitialized = false;
+/**
+ * Ensure that built-in matchers and renderers are registered.
+ * Called lazily on first use of runMatchers/getRenderer.
+ */
+function ensureBuiltinsRegistered() {
+    if (builtinsInitialized)
+        return;
+    builtinsInitialized = true;
+    // Lazy inline require avoids a top-level static import cycle.
+    // These are only evaluated once.
+    // eslint-disable-next-line @typescript-eslint/no-require-imports
+    const { registerBuiltinMatchers } = require("./matchers");
+    // eslint-disable-next-line @typescript-eslint/no-require-imports
+    const { registerBuiltinRenderers } = require("./renderers");
+    registerBuiltinMatchers();
+    registerBuiltinRenderers();
+}
+/**
+ * Register an AssetMatcher.
+ *
+ * Matchers are evaluated in registration order. When two matchers produce
+ * the same specificity score, the one registered later wins.
+ */
+export function registerMatcher(matcher) {
+    matchers.push(matcher);
+}
+/**
+ * Register an AssetRenderer.
+ *
+ * If a renderer with the same name already exists it is silently replaced.
+ */
+export function registerRenderer(renderer) {
+    renderers.set(renderer.name, renderer);
+}
+/**
+ * Look up a renderer by name.
+ */
+export function getRenderer(name) {
+    ensureBuiltinsRegistered();
+    return renderers.get(name);
+}
+/**
+ * Return all registered renderers (snapshot, safe to iterate).
+ */
+export function getAllRenderers() {
+    ensureBuiltinsRegistered();
+    return Array.from(renderers.values());
+}
+/**
+ * Run every registered matcher against a FileContext and return the
+ * highest-specificity result.
+ *
+ * Resolution rules:
+ * 1. Every matcher is invoked; null returns are discarded.
+ * 2. Results are ranked by specificity (descending).
+ * 3. Ties are broken by registration order: the matcher registered later wins
+ *    (this lets user-registered matchers override built-in ones).
+ * 4. Returns null when no matcher claims the file.
+ */
+export function runMatchers(ctx) {
+    ensureBuiltinsRegistered();
+    // Collect (result, registrationIndex) pairs from all matchers.
+    const hits = [];
+    for (let i = 0; i < matchers.length; i++) {
+        const result = matchers[i](ctx);
+        if (result !== null) {
+            hits.push({ result, index: i });
+        }
+    }
+    if (hits.length === 0)
+        return null;
+    // Sort by specificity descending, then by registration index descending (later wins ties).
+    hits.sort((a, b) => {
+        const specDiff = b.result.specificity - a.result.specificity;
+        if (specDiff !== 0)
+            return specDiff;
+        return b.index - a.index;
+    });
+    return hits[0].result;
+}
+/**
+ * Build a RenderContext by merging a FileContext with its winning MatchResult
+ * and the list of stash search paths.
+ */
+export function buildRenderContext(ctx, match, stashDirs) {
+    return {
+        ...ctx,
+        matchResult: match,
+        stashDirs,
+    };
+}

package/dist/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(/^ {2}(\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/github.js

@@ -0,0 +1,17 @@
+export const GITHUB_API_BASE = "https://api.github.com";
+export function githubHeaders() {
+    const token = process.env.GITHUB_TOKEN?.trim();
+    const headers = {
+        Accept: "application/vnd.github+json",
+        "User-Agent": "akm-registry",
+    };
+    if (token)
+        headers.Authorization = `Bearer ${token}`;
+    return headers;
+}
+export function asRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value) ? value : {};
+}
+export function asString(value) {
+    return typeof value === "string" && value ? value : undefined;
+}

package/dist/indexer.js

@@ -0,0 +1,311 @@
+import fs from "node:fs";
+import path from "node:path";
+import { resolveStashDir } from "./common";
+import { closeDatabase, DB_VERSION, deleteEntriesByDir, getEntriesByDir, getEntryCount, getMeta, isVecAvailable, openDatabase, rebuildFts, setMeta, upsertEmbedding, upsertEntry, warnIfVecMissing, } from "./db";
+import { generateMetadataFlat, loadStashFile } from "./metadata";
+import { getDbPath } from "./paths";
+import { walkStashFlat } from "./walker";
+import { warn } from "./warn";
+// ── Indexer ──────────────────────────────────────────────────────────────────
+export async function agentikitIndex(options) {
+    const stashDir = options?.stashDir || resolveStashDir();
+    // Load config and resolve all stash sources
+    const { loadConfig } = await import("./config.js");
+    const config = loadConfig();
+    const { resolveAllStashDirs } = await import("./stash-source.js");
+    const allStashDirs = resolveAllStashDirs(stashDir);
+    const t0 = Date.now();
+    // Open database — pass embedding dimension from config if available
+    const dbPath = getDbPath();
+    const embeddingDim = config.embedding?.dimension;
+    const db = openDatabase(dbPath, embeddingDim ? { embeddingDim } : undefined);
+    try {
+        // Check if we should do incremental
+        const prevStashDir = getMeta(db, "stashDir");
+        const prevBuiltAt = getMeta(db, "builtAt");
+        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");
+        }
+        const tWalkStart = Date.now();
+        // Walk stash dirs and index entries
+        const { scannedDirs, skippedDirs, generatedCount, dirsNeedingLlm } = indexEntries(db, allStashDirs, stashDir, isIncremental, builtAtMs);
+        // Enhance entries with LLM if configured
+        await enhanceDirsWithLlm(db, config, dirsNeedingLlm);
+        const tWalkEnd = Date.now();
+        // Rebuild FTS after all inserts
+        rebuildFts(db);
+        const tFtsEnd = Date.now();
+        // Generate embeddings if semantic search is enabled
+        const hasEmbeddings = await generateEmbeddingsForDb(db, config);
+        const tEmbedEnd = Date.now();
+        // Update metadata
+        setMeta(db, "version", String(DB_VERSION));
+        setMeta(db, "builtAt", new Date().toISOString());
+        setMeta(db, "stashDir", stashDir);
+        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,
+            totalEntries,
+            generatedMetadata: generatedCount,
+            indexPath: dbPath,
+            mode: isIncremental ? "incremental" : "full",
+            directoriesScanned: scannedDirs,
+            directoriesSkipped: skippedDirs,
+            timing: {
+                totalMs: tEnd - t0,
+                walkMs: tWalkEnd - tWalkStart,
+                embedMs: tEmbedEnd - tFtsEnd,
+                ftsMs: tFtsEnd - tWalkEnd,
+            },
+        };
+    }
+    finally {
+        closeDatabase(db);
+    }
+}
+// ── Extracted helpers for indexing ────────────────────────────────────────────
+function indexEntries(db, allStashDirs, _stashDir, isIncremental, builtAtMs) {
+    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]);
+            }
+            for (const [dirPath, files] of dirGroups) {
+                if (seenPaths.has(path.resolve(dirPath)))
+                    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);
+                    if (generated.entries.length > 0) {
+                        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 });
+                    }
+                }
+            }
+        }
+    });
+    insertTransaction();
+    return { scannedDirs, skippedDirs, generatedCount, dirsNeedingLlm };
+}
+async function enhanceDirsWithLlm(db, config, dirsNeedingLlm) {
+    if (!config.llm || dirsNeedingLlm.length === 0)
+        return;
+    for (const { dirPath, files, currentStashDir, stash: originalStash } of dirsNeedingLlm) {
+        // Only enhance generated entries; user-provided overrides should not be overwritten
+        const generatedEntries = originalStash.entries.filter((e) => e.quality === "generated");
+        if (generatedEntries.length === 0)
+            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);
+        }
+    }
+}
+async function generateEmbeddingsForDb(db, config) {
+    if (!config.semanticSearch)
+        return false;
+    try {
+        const { embedBatch } = await import("./embedder.js");
+        const allEntries = getAllEntriesForEmbedding(db);
+        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) {
+        warn("Embedding generation failed, continuing without:", error instanceof Error ? error.message : String(error));
+        return false;
+    }
+}
+// ── Helpers ─────────────────────────────────────────────────────────────────
+function getAllEntriesForEmbedding(db) {
+    return db
+        .prepare(`
+      SELECT e.id, e.search_text AS searchText FROM entries e
+      WHERE NOT EXISTS (SELECT 1 FROM embeddings b WHERE b.id = e.id)
+    `)
+        .all();
+}
+function attachFileSize(entry, entryPath) {
+    try {
+        return { ...entry, fileSize: fs.statSync(entryPath).size };
+    }
+    catch {
+        return entry;
+    }
+}
+/** Set of all known type directory names */
+function isDirStale(dirPath, currentFiles, previousEntries, builtAtMs) {
+    // Check if file set changed (additions or deletions)
+    const prevFileNames = new Set(previousEntries.map((ie) => ie.entry.filename).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.statSync(stashPath).mtimeMs > builtAtMs)
+            return true;
+    }
+    catch {
+        // file doesn't exist, not stale
+    }
+    return false;
+}
+async function enhanceStashWithLlm(llmConfig, stash, _dirPath, files) {
+    const { enhanceMetadata } = await import("./llm.js");
+    const enhanced = [];
+    for (const entry of stash.entries) {
+        try {
+            const entryFile = entry.filename
+                ? (files.find((f) => path.basename(f) === entry.filename) ?? 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.searchHints?.length)
+                updated.searchHints = improvements.searchHints;
+            if (improvements.tags?.length)
+                updated.tags = improvements.tags;
+            enhanced.push(updated);
+        }
+        catch {
+            enhanced.push(entry);
+        }
+    }
+    return { entries: enhanced };
+}
+export function buildSearchText(entry) {
+    const parts = [entry.name.replace(/[-_]/g, " ")];
+    if (entry.description)
+        parts.push(entry.description);
+    if (entry.tags)
+        parts.push(entry.tags.join(" "));
+    if (entry.examples)
+        parts.push(entry.examples.join(" "));
+    if (entry.aliases)
+        parts.push(entry.aliases.join(" "));
+    if (entry.searchHints)
+        parts.push(entry.searchHints.join(" "));
+    if (entry.intent) {
+        if (entry.intent.when)
+            parts.push(entry.intent.when);
+        if (entry.intent.input)
+            parts.push(entry.intent.input);
+        if (entry.intent.output)
+            parts.push(entry.intent.output);
+    }
+    if (entry.toc) {
+        parts.push(entry.toc.map((h) => h.text).join(" "));
+    }
+    return parts.join(" ").toLowerCase();
+}

package/dist/init.js

@@ -0,0 +1,43 @@
+/**
+ * akm 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 };
+}