agentikit 0.0.7 → 0.0.9

package/dist/src/llm.js

@@ -0,0 +1,91 @@
+async function chatCompletion(config, messages) {
+    const headers = { "Content-Type": "application/json" };
+    if (config.apiKey) {
+        headers["Authorization"] = `Bearer ${config.apiKey}`;
+    }
+    const response = await fetch(config.endpoint, {
+        method: "POST",
+        headers,
+        body: JSON.stringify({
+            model: config.model,
+            messages,
+            temperature: 0.3,
+            max_tokens: 512,
+        }),
+    });
+    if (!response.ok) {
+        const body = await response.text().catch(() => "");
+        throw new Error(`LLM request failed (${response.status}): ${body}`);
+    }
+    const json = (await response.json());
+    return json.choices?.[0]?.message?.content?.trim() ?? "";
+}
+// ── Metadata Enhancement ────────────────────────────────────────────────────
+const SYSTEM_PROMPT = `You are a metadata generator for a developer tool registry. Given a tool/skill/command/agent entry, generate improved metadata. Respond with ONLY valid JSON, no markdown fencing.`;
+/**
+ * Use an LLM to enhance a stash entry's metadata: improve description,
+ * generate intents, and suggest tags.
+ */
+export async function enhanceMetadata(config, entry, fileContent) {
+    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;
+        contextParts.push(`File content:\n${truncated}`);
+    }
+    const userPrompt = `${contextParts.join("\n")}
+
+Generate improved metadata for this ${entry.type}. Return JSON with these fields:
+- "description": a clear, concise one-sentence description of what this does
+- "intents": an array of 3-6 natural language task phrases an agent might use to find this (e.g. "deploy a docker container", "run database migrations")
+- "tags": an array of 3-8 relevant keyword tags
+
+Return ONLY the JSON object, no explanation.`;
+    const raw = await chatCompletion(config, [
+        { role: "system", content: SYSTEM_PROMPT },
+        { role: "user", content: userPrompt },
+    ]);
+    try {
+        // Strip markdown code fences if present
+        const cleaned = raw.replace(/^```(?:json)?\s*\n?/i, "").replace(/\n?```\s*$/i, "");
+        const parsed = JSON.parse(cleaned);
+        const result = {};
+        if (typeof parsed.description === "string" && parsed.description) {
+            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);
+        }
+        if (Array.isArray(parsed.tags)) {
+            result.tags = parsed.tags.filter((s) => typeof s === "string" && s.trim().length > 0).slice(0, 10);
+        }
+        return result;
+    }
+    catch {
+        // LLM returned unparseable output, return empty
+        return {};
+    }
+}
+/**
+ * Check if the LLM endpoint is reachable.
+ */
+export async function isLlmAvailable(config) {
+    try {
+        const result = await chatCompletion(config, [
+            { role: "user", content: "Respond with just the word: ok" },
+        ]);
+        return result.length > 0;
+    }
+    catch {
+        return false;
+    }
+}

package/dist/src/markdown.d.ts

@@ -0,0 +1,18 @@
+export interface TocHeading {
+    level: number;
+    text: string;
+    line: number;
+}
+export interface KnowledgeToc {
+    headings: TocHeading[];
+    totalLines: number;
+}
+export declare function parseMarkdownToc(content: string): KnowledgeToc;
+export declare function extractSection(content: string, heading: string): {
+    content: string;
+    startLine: number;
+    endLine: number;
+} | null;
+export declare function extractLineRange(content: string, start: number, end: number): string;
+export declare function extractFrontmatterOnly(content: string): string | null;
+export declare function formatToc(toc: KnowledgeToc): string;

package/dist/src/markdown.js

@@ -0,0 +1,77 @@
+import { parseFrontmatter } from "./frontmatter";
+// ── Parsing ─────────────────────────────────────────────────────────────────
+export function parseMarkdownToc(content) {
+    const lines = content.split(/\r?\n/);
+    const headings = [];
+    const parsed = parseFrontmatter(content);
+    const start = parsed.frontmatter ? parsed.bodyStartLine - 1 : 0;
+    for (let i = start; i < lines.length; i++) {
+        const match = lines[i].match(/^(#{1,6})\s+(.+)$/);
+        if (match) {
+            headings.push({
+                level: match[1].length,
+                text: match[2].replace(/\s+#+\s*$/, "").trim(),
+                line: i + 1,
+            });
+        }
+    }
+    return { headings, totalLines: lines.length };
+}
+// ── Extraction ──────────────────────────────────────────────────────────────
+export function extractSection(content, heading) {
+    const lines = content.split(/\r?\n/);
+    const target = heading.toLowerCase();
+    let startIdx = -1;
+    let startLevel = 0;
+    for (let i = 0; i < lines.length; i++) {
+        const match = lines[i].match(/^(#{1,6})\s+(.+)$/);
+        if (!match)
+            continue;
+        const text = match[2].replace(/\s+#+\s*$/, "").trim();
+        if (text.toLowerCase() === target && startIdx === -1) {
+            startIdx = i;
+            startLevel = match[1].length;
+        }
+        else if (startIdx !== -1 && match[1].length <= startLevel) {
+            return {
+                content: lines.slice(startIdx, i).join("\n"),
+                startLine: startIdx + 1,
+                endLine: i,
+            };
+        }
+    }
+    if (startIdx === -1)
+        return null;
+    return {
+        content: lines.slice(startIdx).join("\n"),
+        startLine: startIdx + 1,
+        endLine: lines.length,
+    };
+}
+export function extractLineRange(content, start, end) {
+    const lines = content.split(/\r?\n/);
+    if (end < start)
+        return "";
+    const s = Math.max(1, Math.min(start, lines.length));
+    const e = Math.min(end, lines.length);
+    return lines.slice(s - 1, e).join("\n");
+}
+export function extractFrontmatterOnly(content) {
+    const parsed = parseFrontmatter(content);
+    return parsed.frontmatter;
+}
+// ── Formatting ──────────────────────────────────────────────────────────────
+export function formatToc(toc) {
+    if (toc.headings.length === 0) {
+        return `(no headings found — ${toc.totalLines} lines total)`;
+    }
+    const lineWidth = String(toc.totalLines).length;
+    const parts = toc.headings.map((h) => {
+        const lineNum = `L${String(h.line).padStart(lineWidth)}`;
+        const indent = "  ".repeat(h.level - 1);
+        const prefix = "#".repeat(h.level);
+        return `${lineNum}  ${indent}${prefix} ${h.text}`;
+    });
+    parts.push(`\n${toc.totalLines} lines total`);
+    return parts.join("\n");
+}

package/dist/src/metadata.d.ts

@@ -1,4 +1,5 @@
-import type { AgentikitAssetType } from "./stash";
+import { type AgentikitAssetType } from "./common";
+import { type TocHeading } from "./markdown";
 export interface StashIntent {
     when?: string;
     input?: string;
@@ -10,9 +11,16 @@ export interface StashEntry {
     description?: string;
     tags?: string[];
     examples?: string[];
+    intents?: string[];
     intent?: StashIntent;
     entry?: string;
     generated?: boolean;
+    quality?: "generated" | "curated";
+    confidence?: number;
+    source?: "package" | "frontmatter" | "comments" | "filename" | "manual" | "llm";
+    aliases?: string[];
+    toc?: TocHeading[];
+    usage?: string[];
 }
 export interface StashFile {
     entries: StashEntry[];
@@ -21,7 +29,8 @@ export declare function stashFilePath(dirPath: string): string;
 export declare function loadStashFile(dirPath: string): StashFile | null;
 export declare function writeStashFile(dirPath: string, stash: StashFile): void;
 export declare function validateStashEntry(entry: unknown): StashEntry | null;
-export declare function generateMetadata(dirPath: string, assetType: AgentikitAssetType, files: string[]): StashFile;
+export declare function generateMetadata(dirPath: string, assetType: AgentikitAssetType, files: string[], typeRoot?: string): StashFile;
+export declare function generateIntents(description: string, tags: string[], name: string): string[];
 export declare function extractDescriptionFromComments(filePath: string): string | null;
 export declare function extractFrontmatterDescription(filePath: string): string | null;
 export declare function extractPackageMetadata(dirPath: string): {

package/dist/src/metadata.js

@@ -1,5 +1,9 @@
 import fs from "node:fs";
 import path from "node:path";
+import { isAssetType } from "./common";
+import { SCRIPT_EXTENSIONS, isRelevantAssetFile, deriveCanonicalAssetName } from "./asset-spec";
+import { parseFrontmatter, toStringOrUndefined } from "./frontmatter";
+import { parseMarkdownToc } from "./markdown";
 // ── Load / Write ────────────────────────────────────────────────────────────
 const STASH_FILENAME = ".stash.json";
 export function stashFilePath(dirPath) {
@@ -35,7 +39,7 @@ export function validateStashEntry(entry) {
     const e = entry;
     if (typeof e.name !== "string" || !e.name)
         return null;
-    if (typeof e.type !== "string" || !isValidType(e.type))
+    if (typeof e.type !== "string" || !isAssetType(e.type))
         return null;
     const result = {
         name: e.name,
@@ -47,6 +51,11 @@ export function validateStashEntry(entry) {
         result.tags = e.tags.filter((t) => typeof t === "string");
     if (Array.isArray(e.examples))
         result.examples = e.examples.filter((x) => typeof x === "string");
+    if (Array.isArray(e.intents)) {
+        const filtered = e.intents.filter((s) => typeof s === "string" && s.trim().length > 0);
+        if (filtered.length > 0)
+            result.intents = filtered;
+    }
     if (typeof e.intent === "object" && e.intent !== null) {
         const intent = e.intent;
         result.intent = {};
@@ -61,62 +70,192 @@ export function validateStashEntry(entry) {
         result.entry = e.entry;
     if (e.generated === true)
         result.generated = true;
+    if (e.quality === "generated" || e.quality === "curated")
+        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)) {
+        result.source = e.source;
+    }
+    if (Array.isArray(e.aliases)) {
+        const filtered = e.aliases.filter((a) => typeof a === "string" && a.trim().length > 0);
+        if (filtered.length > 0)
+            result.aliases = normalizeTerms(filtered);
+    }
+    if (Array.isArray(e.toc)) {
+        const validated = e.toc.filter((h) => {
+            if (typeof h !== "object" || h === null)
+                return false;
+            const rec = h;
+            return typeof rec.level === "number"
+                && typeof rec.text === "string"
+                && typeof rec.line === "number";
+        });
+        if (validated.length > 0)
+            result.toc = validated;
+    }
+    const usage = normalizeNonEmptyStringList(e.usage);
+    if (usage)
+        result.usage = usage;
     return result;
 }
-function isValidType(type) {
-    return type === "tool" || type === "skill" || type === "command" || type === "agent";
+function normalizeNonEmptyStringList(value) {
+    if (typeof value === "string") {
+        const trimmed = value.trim();
+        return trimmed ? [trimmed] : undefined;
+    }
+    if (!Array.isArray(value))
+        return undefined;
+    const filtered = value
+        .filter((item) => typeof item === "string")
+        .map((item) => item.trim())
+        .filter((item) => item.length > 0);
+    return filtered.length > 0 ? filtered : undefined;
 }
 // ── Metadata Generation ─────────────────────────────────────────────────────
-const SCRIPT_EXTENSIONS = new Set([".sh", ".ts", ".js", ".ps1", ".cmd", ".bat"]);
-export function generateMetadata(dirPath, assetType, files) {
+export function generateMetadata(dirPath, assetType, files, typeRoot = dirPath) {
     const entries = [];
+    const pkgMeta = extractPackageMetadata(dirPath);
     for (const file of files) {
         const ext = path.extname(file).toLowerCase();
         const baseName = path.basename(file, ext);
+        const fileName = path.basename(file);
         // Skip non-relevant files
-        if (assetType === "tool" && !SCRIPT_EXTENSIONS.has(ext))
-            continue;
-        if ((assetType === "command" || assetType === "agent") && ext !== ".md")
-            continue;
-        if (assetType === "skill" && path.basename(file) !== "SKILL.md")
+        if (!isRelevantAssetFile(assetType, fileName))
             continue;
+        const canonicalName = assetType === "skill"
+            ? deriveCanonicalAssetName(assetType, typeRoot, file) ?? baseName
+            : baseName;
         const entry = {
-            name: baseName,
+            name: canonicalName,
             type: assetType,
             generated: true,
+            quality: "generated",
+            confidence: 0.55,
+            source: "filename",
         };
-        // Priority 3: package.json metadata
-        const pkgMeta = extractPackageMetadata(dirPath);
+        // Priority 1: package.json metadata
         if (pkgMeta) {
-            if (pkgMeta.description && !entry.description)
+            if (pkgMeta.description && !entry.description) {
                 entry.description = pkgMeta.description;
+                entry.source = "package";
+                entry.confidence = 0.8;
+            }
             if (pkgMeta.keywords && pkgMeta.keywords.length > 0)
-                entry.tags = pkgMeta.keywords;
+                entry.tags = normalizeTerms(pkgMeta.keywords);
         }
-        // Priority 2: Frontmatter (for .md files)
+        // Priority 2: Frontmatter (for .md files — overrides package.json description)
         if (ext === ".md") {
             const fm = extractFrontmatterDescription(file);
-            if (fm)
+            if (fm) {
                 entry.description = fm;
+                entry.source = "frontmatter";
+                entry.confidence = 0.9;
+            }
+        }
+        // Knowledge entries: generate TOC from headings
+        if (assetType === "knowledge") {
+            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
+            }
         }
-        // Priority 4: Code comments (for script files)
+        // Priority 3: Code comments (for script files)
         if (SCRIPT_EXTENSIONS.has(ext) && ext !== ".md") {
             const commentDesc = extractDescriptionFromComments(file);
-            if (commentDesc && !entry.description)
+            if (commentDesc && !entry.description) {
                 entry.description = commentDesc;
+                entry.source = "comments";
+                entry.confidence = 0.7;
+            }
         }
-        // Priority 5: Filename heuristics (fallback)
+        // Priority 4: Filename heuristics (fallback)
         if (!entry.description) {
             entry.description = fileNameToDescription(baseName);
+            entry.source = "filename";
+            entry.confidence = Math.min(entry.confidence ?? 0.55, 0.55);
         }
         if (!entry.tags || entry.tags.length === 0) {
             entry.tags = extractTagsFromPath(file, dirPath);
         }
+        entry.tags = normalizeTerms(entry.tags ?? []);
+        entry.aliases = buildAliases(canonicalName, entry.tags);
+        // Intents are only generated when LLM is configured (via enhanceStashWithLlm)
+        // Heuristic intents are too noisy to be useful for search quality
         entry.entry = path.basename(file);
         entries.push(entry);
     }
     return { entries };
 }
+function normalizeTerms(values) {
+    const normalized = new Set();
+    for (const value of values) {
+        const cleaned = value.toLowerCase().replace(/[-_]+/g, " ").replace(/\s+/g, " ").trim();
+        if (!cleaned)
+            continue;
+        normalized.add(cleaned);
+        if (cleaned.endsWith("s") && cleaned.length > 3) {
+            normalized.add(cleaned.slice(0, -1));
+        }
+    }
+    return Array.from(normalized);
+}
+function buildAliases(name, tags) {
+    const aliases = new Set();
+    const spaced = name.replace(/[-_]+/g, " ").trim().toLowerCase();
+    if (spaced && spaced !== name.toLowerCase())
+        aliases.add(spaced);
+    if (tags.length > 1)
+        aliases.add(tags.join(" "));
+    return Array.from(aliases);
+}
+// ── Intent Generation ────────────────────────────────────────────────────────
+export function generateIntents(description, tags, name) {
+    const intents = new Set();
+    // Split name on separators to extract tokens and potential verb
+    const nameTokens = name
+        .replace(/[-_]+/g, " ")
+        .replace(/([a-z])([A-Z])/g, "$1 $2")
+        .toLowerCase()
+        .trim()
+        .split(/\s+/)
+        .filter((t) => t.length > 1);
+    // Intent from name as phrase (e.g. "summarize diff")
+    const namePhrase = nameTokens.join(" ");
+    if (namePhrase.length > 2)
+        intents.add(namePhrase);
+    // Intent from description (lowercased)
+    const desc = description.toLowerCase().trim();
+    if (desc.length > 2)
+        intents.add(desc);
+    // Combine first name token (potential verb) with tags
+    // e.g. name "summarize-diff", tags ["git"] → "summarize git diff"
+    if (nameTokens.length >= 1 && tags.length > 0) {
+        const verb = nameTokens[0];
+        const rest = nameTokens.slice(1).join(" ");
+        for (const tag of tags) {
+            const tagLower = tag.toLowerCase();
+            // verb + tag + rest (e.g. "summarize git diff")
+            const parts = [verb, tagLower, rest].filter((p) => p.length > 0);
+            const phrase = parts.join(" ");
+            if (phrase !== namePhrase && phrase.length > 2)
+                intents.add(phrase);
+        }
+    }
+    // Join tag pairs (e.g. ["git", "diff"] → "git diff")
+    if (tags.length >= 2) {
+        const tagPhrase = tags.map((t) => t.toLowerCase()).join(" ");
+        if (tagPhrase.length > 2)
+            intents.add(tagPhrase);
+    }
+    // Cap at 8 intents
+    return Array.from(intents).slice(0, 8);
+}
 export function extractDescriptionFromComments(filePath) {
     let content;
     try {
@@ -170,15 +309,8 @@ export function extractFrontmatterDescription(filePath) {
     catch {
         return null;
     }
-    const match = content.match(/^---\r?\n([\s\S]*?)\r?\n---/);
-    if (!match)
-        return null;
-    for (const line of match[1].split(/\r?\n/)) {
-        const m = line.match(/^description:\s*"?(.+?)"?\s*$/);
-        if (m)
-            return m[1];
-    }
-    return null;
+    const parsed = parseFrontmatter(content);
+    return toStringOrUndefined(parsed.data.description) ?? null;
 }
 export function extractPackageMetadata(dirPath) {
     const pkgPath = path.join(dirPath, "package.json");

package/dist/src/registry-install.d.ts

@@ -0,0 +1,11 @@
+import { type AgentikitConfig } from "./config";
+import type { RegistryInstallResult, RegistryInstalledEntry } from "./registry-types";
+export interface InstallRegistryRefOptions {
+    cacheRootDir?: string;
+    now?: Date;
+}
+export declare function installRegistryRef(ref: string, options?: InstallRegistryRefOptions): Promise<RegistryInstallResult>;
+export declare function upsertInstalledRegistryEntry(entry: RegistryInstalledEntry, stashDir?: string): AgentikitConfig;
+export declare function removeInstalledRegistryEntry(id: string, stashDir?: string): AgentikitConfig;
+export declare function getRegistryCacheRootDir(): string;
+export declare function detectStashRoot(extractedDir: string): string;