akm-cli 0.1.3 → 0.2.1

package/dist/metadata.js

@@ -133,6 +133,30 @@ export function validateStashEntry(entry) {
         result.cwd = e.cwd.trim();
     if (typeof e.fileSize === "number" && Number.isFinite(e.fileSize) && e.fileSize >= 0)
         result.fileSize = e.fileSize;
+    if (Array.isArray(e.parameters)) {
+        const validated = e.parameters
+            .filter((p) => {
+            if (typeof p !== "object" || p === null)
+                return false;
+            const rec = p;
+            return typeof rec.name === "string" && rec.name.trim().length > 0;
+        })
+            .map((p) => {
+            const rec = p;
+            const param = { name: rec.name.trim() };
+            if (typeof rec.type === "string" && rec.type.trim())
+                param.type = rec.type.trim();
+            if (typeof rec.description === "string" && rec.description.trim())
+                param.description = rec.description.trim();
+            if (typeof rec.required === "boolean")
+                param.required = rec.required;
+            if (typeof rec.default === "string" && rec.default.trim().length > 0)
+                param.default = rec.default;
+            return param;
+        });
+        if (validated.length > 0)
+            result.parameters = validated;
+    }
     return result;
 }
 function normalizeNonEmptyStringList(value) {
@@ -148,6 +172,107 @@ function normalizeNonEmptyStringList(value) {
         .filter((item) => item.length > 0);
     return filtered.length > 0 ? filtered : undefined;
 }
+// ── Parameter Extraction ─────────────────────────────────────────────────────
+/**
+ * Extract structured parameters from a command template containing
+ * `$ARGUMENTS`, `$1`-`$9`, or `{{named}}` placeholders.
+ */
+export function extractCommandParameters(template) {
+    const params = [];
+    if (/\$ARGUMENTS\b/.test(template)) {
+        params.push({ name: "ARGUMENTS" });
+    }
+    for (const match of template.matchAll(/\$([1-9])(?!\d)/g)) {
+        const name = `$${match[1]}`;
+        if (!params.some((p) => p.name === name)) {
+            params.push({ name });
+        }
+    }
+    for (const match of template.matchAll(/\{\{([a-zA-Z_][a-zA-Z0-9_]*)\}\}/g)) {
+        const name = match[1];
+        if (!params.some((p) => p.name === name)) {
+            params.push({ name });
+        }
+    }
+    return params.length > 0 ? params : undefined;
+}
+/**
+ * Extract `@param` JSDoc tags from a script file's leading comment block.
+ *
+ * Supports both JSDoc-style (`/** ... * /`) and hash-style (`# @param ...`)
+ * comments. Optionally captures `{type}` annotations.
+ */
+export function extractScriptParameters(filePath, content) {
+    if (content === undefined) {
+        try {
+            content = fs.readFileSync(filePath, "utf8");
+        }
+        catch {
+            return undefined;
+        }
+    }
+    const lines = content.split(/\r?\n/).slice(0, 50);
+    const params = [];
+    // Match @param lines in any comment style:
+    // JSDoc:  * @param {string} name - description
+    // JSDoc:  * @param name - description
+    // Hash:   # @param name - description
+    const paramRegex = /^[\s/*#;-]*@param\s+(?:\{([^}]+)\}\s+)?(\w+)(?:\s+-\s+(.+))?/;
+    for (const line of lines) {
+        const match = line.match(paramRegex);
+        if (match) {
+            const param = { name: match[2] };
+            if (match[1])
+                param.type = match[1].trim();
+            if (match[3])
+                param.description = match[3].trim();
+            params.push(param);
+        }
+    }
+    return params.length > 0 ? params : undefined;
+}
+/**
+ * Extract parameters from frontmatter `params:` key.
+ *
+ * The frontmatter parser produces a nested object for `params:` like:
+ * ```
+ * { region: "AWS region to deploy to", instance_type: "EC2 instance type" }
+ * ```
+ */
+export function extractFrontmatterParameters(fmData) {
+    const paramsRaw = fmData.params;
+    if (typeof paramsRaw !== "object" || paramsRaw === null || Array.isArray(paramsRaw))
+        return undefined;
+    const paramsObj = paramsRaw;
+    const params = [];
+    for (const [key, value] of Object.entries(paramsObj)) {
+        const param = { name: key };
+        if (typeof value === "string" && value.trim()) {
+            param.description = value.trim();
+        }
+        params.push(param);
+    }
+    return params.length > 0 ? params : undefined;
+}
+/**
+ * Merge two parameter lists, deduplicating by name.
+ * Parameters from `additional` are appended only if their name is not already present.
+ */
+function mergeParameters(existing, additional) {
+    if (!additional || additional.length === 0)
+        return existing;
+    if (!existing || existing.length === 0)
+        return additional;
+    const names = new Set(existing.map((p) => p.name));
+    const merged = [...existing];
+    for (const param of additional) {
+        if (!names.has(param.name)) {
+            merged.push(param);
+            names.add(param.name);
+        }
+    }
+    return merged;
+}
 // ── Metadata Generation ─────────────────────────────────────────────────────
 export async function generateMetadata(dirPath, assetType, files, typeRoot = dirPath) {
     const entries = [];
@@ -179,12 +304,31 @@ export async function generateMetadata(dirPath, assetType, files, typeRoot = dir
         }
         // Priority 2: Frontmatter (for .md files -- overrides package.json description)
         if (ext === ".md") {
-            const fm = extractFrontmatterDescription(file);
+            const content = fs.readFileSync(file, "utf8");
+            const parsed = parseFrontmatter(content);
+            const fm = toStringOrUndefined(parsed.data.description);
             if (fm) {
                 entry.description = fm;
                 entry.source = "frontmatter";
                 entry.confidence = 0.9;
             }
+            // Extract parameters from frontmatter params: key
+            const fmParams = extractFrontmatterParameters(parsed.data);
+            if (fmParams)
+                entry.parameters = fmParams;
+            // Extract parameters from template placeholders ($1, $ARGUMENTS, {{named}})
+            if (entry.type === "command") {
+                const cmdParams = extractCommandParameters(parsed.content);
+                if (cmdParams) {
+                    entry.parameters = mergeParameters(entry.parameters, cmdParams);
+                }
+            }
+        }
+        // Extract @param from script files
+        if (ext !== ".md") {
+            const scriptParams = extractScriptParameters(file);
+            if (scriptParams)
+                entry.parameters = scriptParams;
         }
         // Priority 3: Type-specific metadata extraction (e.g. TOC for knowledge, comments for scripts)
         const fileCtx = buildFileContext(typeRoot, file);
@@ -262,12 +406,31 @@ export async function generateMetadataFlat(stashRoot, files) {
         }
         // Frontmatter
         if (ext === ".md") {
-            const fm = extractFrontmatterDescription(file);
+            const content = ctx.content();
+            const parsed = parseFrontmatter(content);
+            const fm = toStringOrUndefined(parsed.data.description);
             if (fm) {
                 entry.description = fm;
                 entry.source = "frontmatter";
                 entry.confidence = 0.9;
             }
+            // Extract parameters from frontmatter params: key
+            const fmParams = extractFrontmatterParameters(parsed.data);
+            if (fmParams)
+                entry.parameters = fmParams;
+            // Extract parameters from template placeholders ($1, $ARGUMENTS, {{named}})
+            if (entry.type === "command") {
+                const cmdParams = extractCommandParameters(parsed.content);
+                if (cmdParams) {
+                    entry.parameters = mergeParameters(entry.parameters, cmdParams);
+                }
+            }
+        }
+        // Extract @param from script files
+        if (ext !== ".md") {
+            const scriptParams = extractScriptParameters(file, ctx.content());
+            if (scriptParams)
+                entry.parameters = scriptParams;
         }
         // Renderer metadata extraction
         const renderer = await getRenderer(match.renderer);

package/dist/providers/skills-sh.js

@@ -68,14 +68,17 @@ class SkillsShProvider {
         const registryName = this.config.name ?? "skills.sh";
         const baseUrl = this.config.url.replace(/\/+$/, "");
         return entries.map((entry) => {
-            const owner = entry.source.split("/")[0] ?? "";
+            const segments = entry.source.split("/");
+            const owner = segments[0] ?? "";
+            const repo = segments[1] ?? "";
+            const ownerRepo = owner && repo ? `${owner}/${repo}` : entry.source;
             const score = Math.round((entry.installs / maxInstalls) * 1000) / 1000;
             return {
                 source: "github",
                 id: `skills-sh:${entry.id}`,
                 title: entry.name,
-                ref: entry.source,
-                installRef: `github:${entry.source}`,
+                ref: ownerRepo,
+                installRef: `github:${ownerRepo}`,
                 homepage: `${baseUrl}/${entry.id}`,
                 score,
                 metadata: {
@@ -91,15 +94,21 @@ class SkillsShProvider {
             return undefined;
         const registryName = this.config.name ?? "skills.sh";
         const maxInstalls = Math.max(...entries.map((e) => e.installs), 1);
-        const hits = entries.map((entry) => ({
-            type: "registry-asset",
-            assetType: "skill",
-            assetName: entry.name,
-            kit: { id: `skills-sh:${entry.id}`, name: entry.name },
-            registryName,
-            action: `akm add ${entry.source}`,
-            score: Math.round((entry.installs / maxInstalls) * 1000) / 1000,
-        }));
+        const hits = entries.map((entry) => {
+            const segments = entry.source.split("/");
+            const owner = segments[0] ?? "";
+            const repo = segments[1] ?? "";
+            const ownerRepo = owner && repo ? `${owner}/${repo}` : entry.source;
+            return {
+                type: "registry-asset",
+                assetType: "skill",
+                assetName: entry.name,
+                kit: { id: `skills-sh:${entry.id}`, name: entry.name },
+                registryName,
+                action: `akm add github:${ownerRepo}`,
+                score: Math.round((entry.installs / maxInstalls) * 1000) / 1000,
+            };
+        });
         return hits.length > 0 ? hits : undefined;
     }
     // ── Per-query cache ─────────────────────────────────────────────────────

package/dist/providers/static-index.js

@@ -251,6 +251,7 @@ function parseAssetEntry(raw) {
         name,
         description: asString(obj.description),
         tags: asStringArray(obj.tags),
+        estimatedTokens: typeof obj.estimatedTokens === "number" ? obj.estimatedTokens : undefined,
     };
 }
 // ── Asset-level scoring ─────────────────────────────────────────────────────
@@ -272,6 +273,7 @@ function scoreAssets(kits, query, limit) {
                         assetType: asset.type,
                         assetName: asset.name,
                         description: asset.description,
+                        estimatedTokens: asset.estimatedTokens,
                         kit: { id: kit.id, name: kit.name },
                         registryName,
                         action: `akm add ${installRef}`,
@@ -335,7 +337,7 @@ function buildInstallRef(source, ref) {
         case "git":
             return `git+${ref}`;
         case "local":
-            return ref;
+            return `file:${ref}`;
         default:
             return `github:${ref}`;
     }

package/dist/registry-build-index.js

@@ -184,6 +184,7 @@ async function inspectArchive(url, headers) {
             name: entry.name,
             ...(entry.description ? { description: entry.description } : {}),
             ...(entry.tags && entry.tags.length > 0 ? { tags: entry.tags } : {}),
+            ...(typeof entry.fileSize === "number" ? { estimatedTokens: Math.round(entry.fileSize / 4) } : {}),
         }));
         return {
             description: asString(packageMetadata.description),
@@ -241,10 +242,20 @@ async function enumerateAssets(stashRoot) {
                 continue;
             stash = generated;
         }
-        entries.push(...stash.entries);
+        entries.push(...stash.entries.map((entry) => attachFileSize(dirPath, entry)));
     }
     return entries.sort((a, b) => `${a.type}:${a.name}`.localeCompare(`${b.type}:${b.name}`));
 }
+function attachFileSize(dirPath, entry) {
+    if (typeof entry.fileSize === "number" || !entry.filename)
+        return entry;
+    try {
+        return { ...entry, fileSize: fs.statSync(path.join(dirPath, entry.filename)).size };
+    }
+    catch {
+        return entry;
+    }
+}
 function applyIncludeConfigForInspection(stashRoot, tempDir, searchRoot) {
     const includeConfig = findNearestIncludeConfig(stashRoot, searchRoot);
     if (!includeConfig)

package/dist/registry-resolve.js

@@ -87,16 +87,19 @@ function detectRegistrySearchId(ref) {
     if (!/^[a-z][a-z0-9-]*$/.test(prefix))
         return undefined;
     const rest = ref.slice(colonIdx + 1);
-    return [
+    // Try to extract a plausible owner/repo from the rest (e.g. "org/repo/skill" → "org/repo")
+    const segments = rest.split("/").filter(Boolean);
+    const suggestedRef = segments.length >= 2 ? `github:${segments[0]}/${segments[1]}` : undefined;
+    const lines = [
         `"${ref}" looks like a registry search result ID, not an installable ref.`,
         `The "${prefix}:" prefix is a registry identifier and cannot be passed to \`akm add\`.`,
         "",
-        "Use the installRef or ref field from the search result instead. For example:",
-        `  akm registry search "${rest}" --format json`,
-        "Then install using the installRef value from the result:",
-        "  akm add github:owner/repo",
-        "  akm add npm:package-name",
-    ].join("\n");
+    ];
+    if (suggestedRef) {
+        lines.push(`Try installing the source repository directly:`, `  akm add ${suggestedRef}`, "");
+    }
+    lines.push("Or search for the installable ref:", `  akm search "${segments.length > 2 ? segments[segments.length - 1] : rest}" --source registry`, "Then install using the installRef value from the result:", "  akm add github:owner/repo", "  akm add npm:package-name");
+    return lines.join("\n");
 }
 export async function resolveRegistryArtifact(parsed) {
     if (parsed.source === "npm") {

package/dist/renderers.js

@@ -399,4 +399,4 @@ export function registerBuiltinRenderers() {
     }
 }
 // ── Named exports for testing ────────────────────────────────────────────────
-export { skillMdRenderer, commandMdRenderer, agentMdRenderer, knowledgeMdRenderer, memoryMdRenderer, scriptSourceRenderer, INTERPRETER_MAP, SETUP_SIGNALS, };
+export { agentMdRenderer, commandMdRenderer, INTERPRETER_MAP, knowledgeMdRenderer, memoryMdRenderer, SETUP_SIGNALS, scriptSourceRenderer, skillMdRenderer, };

package/dist/search-fields.js

@@ -0,0 +1,69 @@
+/**
+ * Per-field search text extraction for FTS5 indexing.
+ *
+ * Extracted from indexer.ts to break the circular dependency:
+ *   db.ts -> indexer.ts -> db.ts
+ *
+ * This module imports only from metadata.ts (for the StashEntry type),
+ * so it can be safely imported by both db.ts and indexer.ts.
+ */
+/**
+ * Return per-field search text for multi-column FTS5 indexing.
+ *
+ * Fields:
+ *  - name: entry name with hyphens/underscores replaced by spaces
+ *  - description: entry description
+ *  - tags: tags + aliases joined
+ *  - hints: searchHints + examples + usage + intent fields
+ *  - content: TOC headings (lowest-weight catch-all)
+ */
+export function buildSearchFields(entry) {
+    const name = entry.name.replace(/[-_]/g, " ").toLowerCase();
+    const description = (entry.description ?? "").toLowerCase();
+    const tagParts = [];
+    if (entry.tags)
+        tagParts.push(entry.tags.join(" "));
+    if (entry.aliases)
+        tagParts.push(entry.aliases.join(" "));
+    const tags = tagParts.join(" ").toLowerCase();
+    const hintParts = [];
+    if (entry.searchHints)
+        hintParts.push(entry.searchHints.join(" "));
+    if (entry.examples)
+        hintParts.push(entry.examples.join(" "));
+    if (entry.usage)
+        hintParts.push(entry.usage.join(" "));
+    if (entry.intent) {
+        if (entry.intent.when)
+            hintParts.push(entry.intent.when);
+        if (entry.intent.input)
+            hintParts.push(entry.intent.input);
+        if (entry.intent.output)
+            hintParts.push(entry.intent.output);
+    }
+    const hints = hintParts.join(" ").toLowerCase();
+    const contentParts = [];
+    if (entry.toc) {
+        contentParts.push(entry.toc.map((h) => h.text).join(" "));
+    }
+    if (entry.parameters) {
+        for (const param of entry.parameters) {
+            contentParts.push(param.name);
+            if (param.description)
+                contentParts.push(param.description);
+        }
+    }
+    const content = contentParts.join(" ").toLowerCase();
+    return { name, description, tags, hints, content };
+}
+/**
+ * Build a single concatenated search text string for an entry.
+ * Used for the `search_text` column in the entries table (backward compat)
+ * and for generating embedding text.
+ */
+export function buildSearchText(entry) {
+    const fields = buildSearchFields(entry);
+    return [fields.name, fields.description, fields.tags, fields.hints, fields.content]
+        .filter((s) => s.length > 0)
+        .join(" ");
+}

package/dist/search-source.js

@@ -2,6 +2,7 @@ import fs from "node:fs";
 import path from "node:path";
 import { resolveStashDir } from "./common";
 import { loadConfig } from "./config";
+import { ensureGitMirror, getCachePaths, parseGitRepoUrl } from "./stash-providers/git";
 import { warn } from "./warn";
 // ── Resolution ──────────────────────────────────────────────────────────────
 /**
@@ -36,6 +37,23 @@ export function resolveStashSources(overrideStashDir, existingConfig) {
             addSource(entry.path, entry.name);
         }
     }
+    // Git stash entries: resolve cache directory so the indexer can walk it.
+    // "context-hub", "github", and "git" provider types are handled.
+    for (const entry of config.stashes ?? []) {
+        if (GIT_STASH_TYPES.has(entry.type) && entry.url && entry.enabled !== false) {
+            try {
+                const repo = parseGitRepoUrl(entry.url);
+                const cachePaths = getCachePaths(repo.canonicalUrl);
+                // The content/ subdirectory inside the extracted repo is the actual
+                // stash root containing DOC.md / SKILL.md files that the walker indexes.
+                const contentDir = path.join(cachePaths.repoDir, "content");
+                addSource(contentDir, entry.name);
+            }
+            catch (err) {
+                warn(`Warning: failed to resolve git stash cache for "${entry.url}": ${err instanceof Error ? err.message : String(err)}`);
+            }
+        }
+    }
     // Installed kits (registry and local)
     for (const entry of config.installed ?? []) {
         addSource(entry.stashRoot, entry.id);
@@ -132,3 +150,27 @@ function isValidDirectory(dir) {
         return false;
     }
 }
+// ── Git stash cache integration ──────────────────────────────────────────────
+const GIT_STASH_TYPES = new Set(["context-hub", "github", "git"]);
+/**
+ * Ensure all git stash mirrors are refreshed so their cache directories
+ * exist on disk. Must be called (async) before `resolveStashSources()` so
+ * the content directories pass the `isValidDirectory()` check.
+ */
+export async function ensureGitCaches(config) {
+    const cfg = config ?? loadConfig();
+    for (const entry of cfg.stashes ?? []) {
+        if (!GIT_STASH_TYPES.has(entry.type) || !entry.url || entry.enabled === false)
+            continue;
+        try {
+            const repo = parseGitRepoUrl(entry.url);
+            const cachePaths = getCachePaths(repo.canonicalUrl);
+            await ensureGitMirror(repo, cachePaths, { requireRepoDir: true });
+        }
+        catch (err) {
+            warn(`Warning: failed to refresh git mirror for "${entry.url}": ${err instanceof Error ? err.message : String(err)}`);
+        }
+    }
+}
+/** @deprecated Use ensureGitCaches instead. */
+export const ensureContextHubCaches = ensureGitCaches;