agentikit 0.0.14 → 0.0.15

package/dist/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, warnIfVecMissing, DB_VERSION, } from "./db";
+import { warn } from "./warn";
 // ── Indexer ──────────────────────────────────────────────────────────────────
 export async function agentikitIndex(options) {
     const stashDir = options?.stashDir || resolveStashDir();
@@ -30,12 +32,16 @@ export async function agentikitIndex(options) {
             try {
                 db.exec("DELETE FROM embeddings");
             }
-            catch { /* ignore */ }
+            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");
@@ -126,9 +132,7 @@ function indexEntries(db, allStashDirs, stashDir, isIncremental, builtAtMs) {
                         }
                         // 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 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);
@@ -149,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);
@@ -202,7 +204,7 @@ async function generateEmbeddingsForDb(db, config) {
         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;
     }
 }
@@ -217,9 +219,7 @@ function getAllEntriesForEmbedding(db) {
 }
 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;
@@ -240,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;
 }
@@ -277,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

@@ -6,10 +6,10 @@
  */
 import fs from "node:fs";
 import path from "node:path";
-import { TYPE_DIRS } from "./common";
+import { TYPE_DIRS } from "./asset-spec";
+import { getConfigPath, loadConfig, saveConfig } from "./config";
+import { getBinDir, getDefaultStashDir } from "./paths";
 import { ensureRg } from "./ripgrep-install";
-import { loadConfig, saveConfig, getConfigPath } from "./config";
-import { getDefaultStashDir, getBinDir } from "./paths";
 export async function agentikitInit(options) {
     const stashDir = options?.dir ? path.resolve(options.dir) : getDefaultStashDir();
     let created = false;

package/dist/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

@@ -31,7 +31,9 @@ export function writeLockfile(entries) {
         try {
             fs.unlinkSync(tmpPath);
         }
-        catch { /* ignore cleanup failure */ }
+        catch {
+            /* ignore cleanup failure */
+        }
         throw err;
     }
 }
@@ -49,7 +51,10 @@ 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 !== "");
+    return (typeof obj.id === "string" &&
+        obj.id !== "" &&
+        typeof obj.source === "string" &&
+        ["npm", "github", "git", "local"].includes(obj.source) &&
+        typeof obj.ref === "string" &&
+        obj.ref !== "");
 }

package/dist/matchers.js

@@ -150,8 +150,14 @@ export function smartMdMatcher(ctx) {
     return { type: "knowledge", specificity: 5, renderer: "knowledge-md" };
 }
 // ── Registration ────────────────────────────────────────────────────────────
-// Order matters: later registrations win ties at the same specificity.
-registerMatcher(extensionMatcher);
-registerMatcher(directoryMatcher);
-registerMatcher(parentDirHintMatcher);
-registerMatcher(smartMdMatcher);
+/** All built-in matchers in registration order (later wins ties). */
+const builtinMatchers = [extensionMatcher, directoryMatcher, parentDirHintMatcher, smartMdMatcher];
+/**
+ * Register all built-in matchers with the file-context registry.
+ * Called once from the CLI entry point (or ensureBuiltinsRegistered).
+ */
+export function registerBuiltinMatchers() {
+    for (const matcher of builtinMatchers) {
+        registerMatcher(matcher);
+    }
+}

package/dist/metadata.js

@@ -1,9 +1,10 @@
 import fs from "node:fs";
 import path from "node:path";
+import { deriveCanonicalAssetName, isRelevantAssetFile } from "./asset-spec";
+import { tryGetHandler } from "./asset-type-handler";
 import { isAssetType } from "./common";
-import { isRelevantAssetFile, deriveCanonicalAssetName } from "./asset-spec";
 import { parseFrontmatter, toStringOrUndefined } from "./frontmatter";
-import { tryGetHandler } from "./asset-type-handler";
+import { warn } from "./warn";
 // ── Load / Write ────────────────────────────────────────────────────────────
 const STASH_FILENAME = ".stash.json";
 export function stashFilePath(dirPath) {
@@ -20,8 +21,15 @@ export function loadStashFile(dirPath) {
         const entries = [];
         for (const e of raw.entries) {
             const validated = validateStashEntry(e);
-            if (validated)
+            if (validated) {
                 entries.push(validated);
+            }
+            else {
+                const name = typeof e === "object" && e !== null && typeof e.name === "string"
+                    ? e.name
+                    : "(unknown)";
+                warn(`Warning: Skipping invalid entry "${name}" in ${filePath}`);
+            }
         }
         return entries.length > 0 ? { entries } : null;
     }
@@ -40,7 +48,9 @@ export function writeStashFile(dirPath, stash) {
         try {
             fs.unlinkSync(tmpPath);
         }
-        catch { /* ignore cleanup failure */ }
+        catch {
+            /* ignore cleanup failure */
+        }
         throw err;
     }
 }
@@ -85,7 +95,8 @@ export function validateStashEntry(entry) {
         result.quality = e.quality;
     if (typeof e.confidence === "number" && Number.isFinite(e.confidence))
         result.confidence = Math.max(0, Math.min(1, e.confidence));
-    if (typeof e.source === "string" && ["package", "frontmatter", "comments", "filename", "manual", "llm"].includes(e.source)) {
+    if (typeof e.source === "string" &&
+        ["package", "frontmatter", "comments", "filename", "manual", "llm"].includes(e.source)) {
         result.source = e.source;
     }
     if (Array.isArray(e.aliases)) {
@@ -98,9 +109,7 @@ export function validateStashEntry(entry) {
             if (typeof h !== "object" || h === null)
                 return false;
             const rec = h;
-            return typeof rec.level === "number"
-                && typeof rec.text === "string"
-                && typeof rec.line === "number";
+            return typeof rec.level === "number" && typeof rec.text === "string" && typeof rec.line === "number";
         });
         if (validated.length > 0)
             result.toc = validated;
@@ -134,9 +143,7 @@ export function generateMetadata(dirPath, assetType, files, typeRoot = dirPath)
         // Skip non-relevant files
         if (!isRelevantAssetFile(assetType, fileName))
             continue;
-        const canonicalName = assetType === "skill"
-            ? deriveCanonicalAssetName(assetType, typeRoot, file) ?? baseName
-            : baseName;
+        const canonicalName = assetType === "skill" ? (deriveCanonicalAssetName(assetType, typeRoot, file) ?? baseName) : baseName;
         const entry = {
             name: canonicalName,
             type: assetType,
@@ -145,7 +152,7 @@ export function generateMetadata(dirPath, assetType, files, typeRoot = dirPath)
             confidence: 0.55,
             source: "filename",
         };
-        // Priority 1: package.json metadata
+        // Priority 1: Package.json metadata
         if (pkgMeta) {
             if (pkgMeta.description && !entry.description) {
                 entry.description = pkgMeta.description;
@@ -155,7 +162,7 @@ export function generateMetadata(dirPath, assetType, files, typeRoot = dirPath)
             if (pkgMeta.keywords && pkgMeta.keywords.length > 0)
                 entry.tags = normalizeTerms(pkgMeta.keywords);
         }
-        // Priority 2: Frontmatter (for .md files — overrides package.json description)
+        // Priority 2: Frontmatter (for .md files -- overrides package.json description)
         if (ext === ".md") {
             const fm = extractFrontmatterDescription(file);
             if (fm) {
@@ -164,7 +171,7 @@ export function generateMetadata(dirPath, assetType, files, typeRoot = dirPath)
                 entry.confidence = 0.9;
             }
         }
-        // Type-specific metadata extraction (e.g. TOC for knowledge, comments for tools/scripts)
+        // Priority 3: Type-specific metadata extraction (e.g. TOC for knowledge, comments for tools/scripts)
         const handler = tryGetHandler(assetType);
         if (handler?.extractTypeMetadata) {
             handler.extractTypeMetadata(entry, file, ext);
@@ -226,7 +233,10 @@ export function extractDescriptionFromComments(filePath) {
             const line = lines[i];
             if (i > blockStart && /\*\//.test(line))
                 break;
-            const cleaned = line.replace(/^\s*\/?\*\*?\s?/, "").replace(/\*\/\s*$/, "").trim();
+            const cleaned = line
+                .replace(/^\s*\/?\*\*?\s?/, "")
+                .replace(/\*\/\s*$/, "")
+                .trim();
             if (cleaned)
                 desc.push(cleaned);
         }
@@ -244,7 +254,6 @@ export function extractDescriptionFromComments(filePath) {
             hashLines.push(line.replace(/^#+\s*/, "").trim());
         }
         else if (line === "") {
-            continue;
         }
         else {
             break;

package/dist/paths.js

@@ -6,6 +6,7 @@
  * on Windows.
  */
 import path from "node:path";
+import { ConfigError } from "./errors";
 const IS_WINDOWS = process.platform === "win32";
 // ── Config directory ─────────────────────────────────────────────────────────
 export function getConfigDir(env = process.env, platform = process.platform) {
@@ -15,7 +16,7 @@ export function getConfigDir(env = process.env, platform = process.platform) {
             return path.join(appData, "agentikit");
         const userProfile = env.USERPROFILE?.trim();
         if (!userProfile) {
-            throw new Error("Unable to determine config directory. Set APPDATA or USERPROFILE.");
+            throw new ConfigError("Unable to determine config directory. Set APPDATA or USERPROFILE.");
         }
         return path.join(userProfile, "AppData", "Roaming", "agentikit");
     }
@@ -24,7 +25,7 @@ export function getConfigDir(env = process.env, platform = process.platform) {
         return path.join(xdgConfigHome, "agentikit");
     const home = env.HOME?.trim();
     if (!home) {
-        throw new Error("Unable to determine config directory. Set XDG_CONFIG_HOME or HOME.");
+        throw new ConfigError("Unable to determine config directory. Set XDG_CONFIG_HOME or HOME.");
     }
     return path.join(home, ".config", "agentikit");
 }
@@ -42,7 +43,7 @@ export function getCacheDir() {
             return path.join(userProfile, "AppData", "Local", "agentikit");
         const appData = process.env.APPDATA?.trim();
         if (!appData) {
-            throw new Error("Unable to determine cache directory. Set LOCALAPPDATA, USERPROFILE, or APPDATA.");
+            throw new ConfigError("Unable to determine cache directory. Set LOCALAPPDATA, USERPROFILE, or APPDATA.");
         }
         return path.join(appData, "..", "Local", "agentikit");
     }
@@ -76,7 +77,7 @@ export function getDefaultStashDir() {
     }
     const home = process.env.HOME?.trim();
     if (!home) {
-        throw new Error("Unable to determine default stash directory. Set HOME.");
+        throw new ConfigError("Unable to determine default stash directory. Set HOME.");
     }
     return path.join(home, "agentikit");
 }

package/dist/registry-install.js

@@ -1,11 +1,12 @@
-import { createHash } from "node:crypto";
 import { spawnSync } from "node:child_process";
+import { createHash } from "node:crypto";
 import fs from "node:fs";
 import path from "node:path";
-import { fetchWithRetry, isWithin, TYPE_DIRS } from "./common";
+import { TYPE_DIRS } from "./asset-spec";
+import { fetchWithRetry, isWithin } from "./common";
 import { loadConfig, saveConfig } from "./config";
-import { parseRegistryRef, resolveRegistryArtifact } from "./registry-resolve";
 import { getRegistryCacheDir as _getRegistryCacheDir } from "./paths";
+import { parseRegistryRef, resolveRegistryArtifact } from "./registry-resolve";
 const REGISTRY_STASH_DIR_NAMES = new Set(Object.values(TYPE_DIRS));
 export async function installRegistryRef(ref, options) {
     const parsed = parseRegistryRef(ref);
@@ -231,7 +232,8 @@ async function downloadArchive(url, destination) {
     }
     // Stream response to disk instead of buffering the entire archive in memory.
     // Uses Bun.write which handles Response streaming natively.
-    const BunRuntime = globalThis.Bun;
+    const BunRuntime = globalThis
+        .Bun;
     if (BunRuntime?.write) {
         await BunRuntime.write(destination, response);
     }
@@ -308,7 +310,9 @@ function validateTarEntries(listOutput) {
         if (!stripped)
             continue;
         const normalizedStripped = path.posix.normalize(stripped);
-        if (normalizedStripped === ".." || normalizedStripped.startsWith("../") || path.posix.isAbsolute(normalizedStripped)) {
+        if (normalizedStripped === ".." ||
+            normalizedStripped.startsWith("../") ||
+            path.posix.isAbsolute(normalizedStripped)) {
             throw new Error(`Archive contains an unsafe entry after strip-components: ${entry}`);
         }
     }

package/dist/registry-resolve.js

@@ -3,7 +3,7 @@ import fs from "node:fs";
 import path from "node:path";
 import { pathToFileURL } from "node:url";
 import { fetchWithRetry } from "./common";
-import { GITHUB_API_BASE, githubHeaders, asRecord, asString } from "./github";
+import { asRecord, asString, GITHUB_API_BASE, githubHeaders } from "./github";
 export function parseRegistryRef(rawRef) {
     const ref = rawRef.trim();
     if (!ref)
@@ -177,7 +177,7 @@ async function resolveNpmArtifact(parsed) {
         }
     }
     if (!resolvedVersion || !(resolvedVersion in versions)) {
-        throw new Error(`Unable to resolve npm ref \"${parsed.ref}\".`);
+        throw new Error(`Unable to resolve npm ref "${parsed.ref}".`);
     }
     const versionMeta = asRecord(versions[resolvedVersion]);
     const dist = asRecord(versionMeta.dist);
@@ -287,16 +287,20 @@ function splitNpmNameAndVersion(input) {
 }
 function validateNpmPackageName(name) {
     if (!name)
-        throw new Error('Invalid npm package name: name is required.');
+        throw new Error("Invalid npm package name: name is required.");
     if (name.length > 214)
         throw new Error(`Invalid npm package name: "${name}" exceeds 214 characters.`);
-    if (name !== name.toLowerCase() && !name.startsWith('@')) {
+    if (name !== name.toLowerCase() && !name.startsWith("@")) {
         throw new Error(`Invalid npm package name: "${name}" must be lowercase.`);
     }
-    if (name.startsWith('.') || name.startsWith('_')) {
+    if (name.startsWith(".") || name.startsWith("_")) {
         throw new Error(`Invalid npm package name: "${name}" cannot start with . or _.`);
     }
-    if (/[~'!()*]/.test(name) || name.includes(' ') || encodeURIComponent(name).replace(/%40/g, '@').replace(/%2[Ff]/g, '/') !== name) {
+    if (/[~'!()*]/.test(name) ||
+        name.includes(" ") ||
+        encodeURIComponent(name)
+            .replace(/%40/g, "@")
+            .replace(/%2[Ff]/g, "/") !== name) {
         throw new Error(`Invalid npm package name: "${name}" contains invalid characters.`);
     }
 }
@@ -449,11 +453,11 @@ async function fetchJson(url, headers) {
     if (!response.ok) {
         throw new Error(`Request failed (${response.status}) for ${url}`);
     }
-    return await response.json();
+    return (await response.json());
 }
 async function tryFetchJson(url, headers) {
     const response = await fetchWithRetry(url, { headers });
     if (!response.ok)
         return null;
-    return await response.json();
+    return (await response.json());
 }

package/dist/registry-search.js

@@ -149,10 +149,7 @@ function parseKitEntry(raw) {
 }
 // ── Scoring ─────────────────────────────────────────────────────────────────
 function scoreKits(kits, query, limit) {
-    const tokens = query
-        .toLowerCase()
-        .split(/\s+/)
-        .filter(Boolean);
+    const tokens = query.toLowerCase().split(/\s+/).filter(Boolean);
     const scored = [];
     for (const kit of kits) {
         const score = scoreKit(kit, tokens);
@@ -226,7 +223,10 @@ function resolveRegistryUrls(override) {
     // Allow env var override (comma-separated)
     const envUrls = process.env.AKM_REGISTRY_URL?.trim();
     if (envUrls) {
-        return envUrls.split(",").map((u) => u.trim()).filter(Boolean);
+        return envUrls
+            .split(",")
+            .map((u) => u.trim())
+            .filter(Boolean);
     }
     return [DEFAULT_REGISTRY_URL];
 }

package/dist/renderers.js

@@ -6,15 +6,14 @@
  * from ./file-context. Renderers are registered at module-load time so that
  * importing this module is sufficient to make them available.
  */
-import fs from "node:fs";
 import path from "node:path";
-import { registerRenderer } from "./file-context";
-import { parseFrontmatter, toStringOrUndefined } from "./frontmatter";
 import { SCRIPT_EXTENSIONS } from "./asset-spec";
-import { buildToolInfo } from "./tool-runner";
 import { hasErrnoCode } from "./common";
+import { registerRenderer } from "./file-context";
+import { parseFrontmatter, toStringOrUndefined } from "./frontmatter";
+import { extractFrontmatterOnly, extractLineRange, extractSection, formatToc, parseMarkdownToc } from "./markdown";
 import { extractDescriptionFromComments } from "./metadata";
-import { parseMarkdownToc, extractSection, extractLineRange, extractFrontmatterOnly, formatToc, } from "./markdown";
+import { buildToolInfo } from "./tool-runner";
 // ── Helpers ──────────────────────────────────────────────────────────────────
 /**
  * Derive a display name from the RenderContext.
@@ -35,7 +34,7 @@ function deriveName(ctx) {
  * entry in the array when no prefix match is found.
  */
 function findContainingStashDir(stashDirs, filePath) {
-    return (stashDirs.find((d) => path.resolve(filePath).startsWith(path.resolve(d) + path.sep)) ?? stashDirs[0]);
+    return stashDirs.find((d) => path.resolve(filePath).startsWith(path.resolve(d) + path.sep)) ?? stashDirs[0];
 }
 // ── 1. tool-script ───────────────────────────────────────────────────────────
 const toolScriptRenderer = {
@@ -186,8 +185,7 @@ const knowledgeMdRenderer = {
     },
     extractMetadata(entry, ctx) {
         try {
-            const mdContent = fs.readFileSync(ctx.absPath, "utf8");
-            const toc = parseMarkdownToc(mdContent);
+            const toc = parseMarkdownToc(ctx.content());
             if (toc.headings.length > 0)
                 entry.toc = toc.headings;
         }
@@ -266,11 +264,23 @@ const scriptSourceRenderer = {
     ],
 };
 // ── Registration ─────────────────────────────────────────────────────────────
-registerRenderer(toolScriptRenderer);
-registerRenderer(skillMdRenderer);
-registerRenderer(commandMdRenderer);
-registerRenderer(agentMdRenderer);
-registerRenderer(knowledgeMdRenderer);
-registerRenderer(scriptSourceRenderer);
+/** All built-in renderers. */
+const builtinRenderers = [
+    toolScriptRenderer,
+    skillMdRenderer,
+    commandMdRenderer,
+    agentMdRenderer,
+    knowledgeMdRenderer,
+    scriptSourceRenderer,
+];
+/**
+ * Register all built-in renderers with the file-context registry.
+ * Called once from the CLI entry point (or ensureBuiltinsRegistered).
+ */
+export function registerBuiltinRenderers() {
+    for (const renderer of builtinRenderers) {
+        registerRenderer(renderer);
+    }
+}
 // ── Named exports for testing ────────────────────────────────────────────────
 export { toolScriptRenderer, skillMdRenderer, commandMdRenderer, agentMdRenderer, knowledgeMdRenderer, scriptSourceRenderer, };

package/dist/ripgrep-install.js

@@ -78,14 +78,7 @@ function downloadAndExtractTarGz(url, archiveName, destBinary) {
             throw new Error(`Failed to download ripgrep from ${url}: ${err}`);
         }
         // Extract the specific binary from the archive into destDir
-        const tarResult = spawnSync("tar", [
-            "xzf",
-            tmpTarGz,
-            "--strip-components=1",
-            "-C",
-            destDir,
-            `${archiveName}/rg`,
-        ], {
+        const tarResult = spawnSync("tar", ["xzf", tmpTarGz, "--strip-components=1", "-C", destDir, `${archiveName}/rg`], {
             encoding: "utf8",
             timeout: 60_000,
         });
@@ -124,13 +117,7 @@ function downloadAndExtractZip(url, archiveName, destBinary) {
         }
         // Extract the zip archive using separate spawnSync calls with argument arrays
         // to avoid shell injection via path interpolation in PowerShell -Command strings
-        const expandResult = spawnSync("powershell", [
-            "-Command",
-            "Expand-Archive",
-            "-Path", tmpZip,
-            "-DestinationPath", destDir,
-            "-Force",
-        ], {
+        const expandResult = spawnSync("powershell", ["-Command", "Expand-Archive", "-Path", tmpZip, "-DestinationPath", destDir, "-Force"], {
             encoding: "utf8",
             timeout: 60_000,
         });
@@ -138,13 +125,7 @@ function downloadAndExtractZip(url, archiveName, destBinary) {
             throw new Error(expandResult.stderr?.trim() || "extraction failed");
         }
         const srcRgExe = path.join(destDir, archiveName, "rg.exe");
-        const moveResult = spawnSync("powershell", [
-            "-Command",
-            "Move-Item",
-            "-Force",
-            "-Path", srcRgExe,
-            "-Destination", destBinary,
-        ], {
+        const moveResult = spawnSync("powershell", ["-Command", "Move-Item", "-Force", "-Path", srcRgExe, "-Destination", destBinary], {
             encoding: "utf8",
             timeout: 60_000,
         });

package/dist/ripgrep.js

@@ -1,2 +1,2 @@
-export { resolveRg, isRgAvailable } from "./ripgrep-resolve";
 export { ensureRg } from "./ripgrep-install";
+export { isRgAvailable, resolveRg } from "./ripgrep-resolve";