akm-cli 0.0.17 → 0.0.19

package/README.md

@@ -1,4 +1,6 @@
-# akm -- the Agent-i-Kit Manager
+# Agent Kit Manager
+
+> Agent-i-Kit
 
 [![npm version](https://img.shields.io/npm/v/akm-cli)](https://www.npmjs.com/package/akm-cli)
 [![CI](https://github.com/itlackey/agentikit/actions/workflows/ci.yml/badge.svg)](https://github.com/itlackey/agentikit/actions/workflows/ci.yml)
@@ -43,7 +45,7 @@ akm search "deploy"
 akm show script:deploy.sh
 ```
 
-## Using With Any AI Agent
+## Works Any AI Agent
 
 `akm` is platform agnostic. Any model that can execute shell commands can search
 your stash and use what it finds. The workflow is three commands:

package/dist/cli.js

@@ -699,6 +699,7 @@ const registryCommand = defineCommand({
             args: {
                 url: { type: "positional", description: "Registry index URL", required: true },
                 name: { type: "string", description: "Human-friendly name for the registry" },
+                provider: { type: "string", description: "Provider type (e.g. static-index, skills-sh)" },
             },
             run({ args }) {
                 return runWithJsonErrors(() => {
@@ -715,6 +716,8 @@ const registryCommand = defineCommand({
                     const entry = { url: args.url };
                     if (args.name)
                         entry.name = args.name;
+                    if (args.provider)
+                        entry.provider = args.provider;
                     registries.push(entry);
                     saveConfig({ ...config, registries });
                     output("registry-add", { registries, added: true });
@@ -769,6 +772,19 @@ const sourcesCommand = defineCommand({
         });
     },
 });
+const hintsCommand = defineCommand({
+    meta: {
+        name: "hints",
+        description: "Print agent instructions on how to use akm, use --detail full for a complete guide",
+    },
+    args: {
+        detail: { type: "string", description: "Detail level (normal|full)", default: "normal" },
+    },
+    run({ args }) {
+        const detail = args.detail === "full" ? "full" : "normal";
+        process.stdout.write(loadHints(detail));
+    },
+});
 const main = defineCommand({
     meta: {
         name: "akm",
@@ -794,6 +810,7 @@ const main = defineCommand({
         sources: sourcesCommand,
         registry: registryCommand,
         config: configCommand,
+        hints: hintsCommand,
     },
 });
 const SEARCH_SOURCES = ["local", "registry", "both"];
@@ -932,3 +949,167 @@ function normalizeShowArgv(argv) {
     result.push(...globalFlags);
     return result;
 }
+// ── Hints (embedded AGENTS.md) ──────────────────────────────────────────────
+function loadHints(detail = "normal") {
+    const filename = detail === "full" ? "AGENTS.full.md" : "AGENTS.md";
+    const fallback = detail === "full" ? EMBEDDED_HINTS_FULL : EMBEDDED_HINTS;
+    // Try reading from the docs/ directory (works in dev and when installed via npm)
+    try {
+        const docsPath = path.resolve(import.meta.dir ?? __dirname, `../docs/${filename}`);
+        if (fs.existsSync(docsPath)) {
+            return fs.readFileSync(docsPath, "utf8");
+        }
+    }
+    catch {
+        // fall through
+    }
+    // Fallback for compiled binary — inline content
+    return fallback;
+}
+const EMBEDDED_HINTS = `# akm CLI
+
+You have access to a searchable library of scripts, skills, commands, agents, and knowledge documents via \`akm\`. Search the stash first before writing something from scratch.
+
+## Quick Reference
+
+\`\`\`sh
+akm search "<query>"                          # Search for assets
+akm search "<query>" --type skill             # Filter by type
+akm search "<query>" --source both            # Search registries and local stashes for assets
+akm show <ref>                                # View asset details
+akm add <ref>                                 # Install a kit (npm, GitHub, git, local)
+akm clone <ref>                               # Copy an asset to the working stash (optional --dest arg to clone to specific location)
+akm registry search "<query>"                 # Search all registries
+\`\`\`
+
+## Primary Asset Types
+
+| Type | What \`akm show\` returns |
+| --- | --- |
+| script | A \`run\` command you can execute directly |
+| skill | Instructions to follow (read the full content) |
+| command | A prompt template with placeholders to fill in |
+| agent | A system prompt with model and tool hints |
+| knowledge | A reference doc (use \`toc\` or \`section "..."\` to navigate) |
+
+Run \`akm -h\` for the full command reference.
+`;
+const EMBEDDED_HINTS_FULL = `# akm CLI — Full Reference
+
+You have access to a searchable library of scripts, skills, commands, agents, and knowledge documents via \`akm\`. Search the stash first before writing something from scratch.
+
+## Search
+
+\`\`\`sh
+akm search "<query>"                          # Search local stash
+akm search "<query>" --type skill             # Filter by asset type
+akm search "<query>" --source both            # Search local stash and registries
+akm search "<query>" --source registry        # Search registries only
+akm search "<query>" --limit 10               # Limit results
+akm search "<query>" --detail full            # Include scores, paths, timing
+\`\`\`
+
+| Flag | Values | Default |
+| --- | --- | --- |
+| \`--type\` | \`skill\`, \`command\`, \`agent\`, \`knowledge\`, \`script\`, \`any\` | \`any\` |
+| \`--source\` | \`local\`, \`registry\`, \`both\` | \`local\` |
+| \`--limit\` | number | \`20\` |
+| \`--format\` | \`json\`, \`text\`, \`yaml\` | \`json\` |
+| \`--detail\` | \`brief\`, \`normal\`, \`full\` | \`brief\` |
+
+## Show
+
+Display an asset by ref. Knowledge assets support view modes as positional arguments.
+
+\`\`\`sh
+akm show script:deploy.sh                     # Show script (returns run command)
+akm show skill:code-review                    # Show skill (returns full content)
+akm show command:release                      # Show command (returns template)
+akm show agent:architect                      # Show agent (returns system prompt)
+akm show knowledge:guide toc                  # Table of contents
+akm show knowledge:guide section "Auth"       # Specific section
+akm show knowledge:guide lines 10 30          # Line range
+\`\`\`
+
+| Type | Key fields returned |
+| --- | --- |
+| script | \`run\`, \`setup\`, \`cwd\` |
+| skill | \`content\` (full SKILL.md) |
+| command | \`template\`, \`description\`, \`parameters\` |
+| agent | \`prompt\`, \`description\`, \`modelHint\`, \`toolPolicy\` |
+| knowledge | \`content\` (with view modes: \`full\`, \`toc\`, \`frontmatter\`, \`section\`, \`lines\`) |
+
+## Install & Manage Kits
+
+\`\`\`sh
+akm add <ref>                                 # Install a kit
+akm add @scope/kit                            # From npm
+akm add owner/repo                            # From GitHub
+akm add ./path/to/local/kit                   # From local directory
+akm list                                      # List installed kits
+akm remove <target>                           # Remove by id or ref
+akm update --all                              # Update all installed kits
+akm update <target> --force                   # Force re-download
+\`\`\`
+
+## Clone
+
+Copy an asset to the working stash or a custom destination for editing.
+
+\`\`\`sh
+akm clone <ref>                               # Clone to working stash
+akm clone <ref> --name new-name               # Rename on clone
+akm clone <ref> --dest ./project/.claude       # Clone to custom location
+akm clone <ref> --force                       # Overwrite existing
+akm clone "npm:@scope/pkg//script:deploy.sh"  # Clone from remote package
+\`\`\`
+
+When \`--dest\` is provided, \`akm init\` is not required first.
+
+## Registries
+
+\`\`\`sh
+akm registry list                             # List configured registries
+akm registry add <url>                        # Add a registry
+akm registry add <url> --name my-team         # Add with label
+akm registry add <url> --provider skills-sh   # Specify provider type
+akm registry remove <url-or-name>             # Remove a registry
+akm registry search "<query>"                 # Search all registries
+akm registry search "<query>" --assets        # Include asset-level results
+\`\`\`
+
+## Configuration
+
+\`\`\`sh
+akm config list                               # Show current config
+akm config get <key>                          # Read a value
+akm config set <key> <value>                  # Set a value
+akm config unset <key>                        # Remove a key
+akm config path --all                         # Show all config paths
+\`\`\`
+
+## Other Commands
+
+\`\`\`sh
+akm init                                      # Initialize stash directory
+akm index                                     # Rebuild search index
+akm index --full                              # Full reindex
+akm sources                                   # List stash search paths
+akm upgrade                                   # Upgrade akm binary
+akm upgrade --check                           # Check for updates
+akm hints                                     # Print this reference
+\`\`\`
+
+## Output Control
+
+All commands accept \`--format\` and \`--detail\` flags:
+
+- \`--format json\` (default) — structured JSON
+- \`--format text\` — human-readable plain text
+- \`--format yaml\` — YAML output
+- \`--detail brief\` (default) — compact output
+- \`--detail normal\` — adds tags, refs, origins
+- \`--detail full\` — includes scores, paths, timing, debug info
+
+Run \`akm -h\` or \`akm <command> -h\` for per-command help.
+`;

package/dist/common.js

@@ -147,6 +147,12 @@ export async function fetchWithTimeout(url, opts, timeoutMs = 30_000) {
     try {
         return await fetch(url, { ...opts, signal: controller.signal });
     }
+    catch (err) {
+        if (err instanceof DOMException && err.name === "AbortError") {
+            throw new Error(`Request timed out after ${timeoutMs}ms: ${url}`);
+        }
+        throw err;
+    }
     finally {
         clearTimeout(timer);
     }

package/dist/config-cli.js

@@ -131,7 +131,7 @@ function parseRegistriesValue(value) {
         parsed = JSON.parse(value);
     }
     catch {
-        throw new UsageError(`Invalid value for registries: expected JSON array of {url, name?, enabled?} objects` +
+        throw new UsageError(`Invalid value for registries: expected JSON array of {url, name?, enabled?, provider?, options?} objects` +
             ` (e.g. '[{"url":"https://example.com/index.json","name":"my-registry"}]')`);
     }
     if (!Array.isArray(parsed)) {
@@ -150,6 +150,11 @@ function parseRegistriesValue(value) {
             result.name = obj.name;
         if (typeof obj.enabled === "boolean")
             result.enabled = obj.enabled;
+        if (typeof obj.provider === "string" && obj.provider)
+            result.provider = obj.provider;
+        if (typeof obj.options === "object" && obj.options !== null && !Array.isArray(obj.options)) {
+            result.options = obj.options;
+        }
         return result;
     });
 }

package/dist/config.js

@@ -334,5 +334,11 @@ function parseRegistryConfigEntry(value) {
         entry.name = name;
     if (typeof obj.enabled === "boolean")
         entry.enabled = obj.enabled;
+    const provider = asNonEmptyString(obj.provider);
+    if (provider)
+        entry.provider = provider;
+    if (typeof obj.options === "object" && obj.options !== null && !Array.isArray(obj.options)) {
+        entry.options = obj.options;
+    }
     return entry;
 }

package/dist/db.js

@@ -180,6 +180,15 @@ export function upsertEntry(db, entryKey, dirPath, filePath, stashDir, entry, se
 }
 export function deleteEntriesByDir(db, dirPath) {
     const ids = db.prepare("SELECT id FROM entries WHERE dir_path = ?").all(dirPath);
+    deleteRelatedRows(db, ids);
+    db.prepare("DELETE FROM entries WHERE dir_path = ?").run(dirPath);
+}
+export function deleteEntriesByStashDir(db, stashDir) {
+    const ids = db.prepare("SELECT id FROM entries WHERE stash_dir = ?").all(stashDir);
+    deleteRelatedRows(db, ids);
+    db.prepare("DELETE FROM entries WHERE stash_dir = ?").run(stashDir);
+}
+function deleteRelatedRows(db, ids) {
     for (const { id } of ids) {
         try {
             db.prepare("DELETE FROM embeddings WHERE id = ?").run(id);
@@ -196,7 +205,6 @@ export function deleteEntriesByDir(db, dirPath) {
             }
         }
     }
-    db.prepare("DELETE FROM entries WHERE dir_path = ?").run(dirPath);
 }
 export function rebuildFts(db) {
     db.exec("DELETE FROM entries_fts");

package/dist/indexer.js

@@ -1,7 +1,7 @@
 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 { closeDatabase, DB_VERSION, deleteEntriesByDir, deleteEntriesByStashDir, 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";
@@ -45,6 +45,20 @@ export async function agentikitIndex(options) {
             db.exec("DELETE FROM entries_fts");
             db.exec("DELETE FROM entries");
         }
+        else {
+            // Incremental: purge entries from stash dirs that have been removed
+            // (e.g. after `akm remove`) so orphaned entries don't linger.
+            const prevStashDirsJson = getMeta(db, "stashDirs");
+            if (prevStashDirsJson) {
+                const prevStashDirs = JSON.parse(prevStashDirsJson);
+                const currentSet = new Set(allStashDirs);
+                for (const dir of prevStashDirs) {
+                    if (!currentSet.has(dir)) {
+                        deleteEntriesByStashDir(db, dir);
+                    }
+                }
+            }
+        }
         const tWalkStart = Date.now();
         // Walk stash dirs and index entries
         const { scannedDirs, skippedDirs, generatedCount, dirsNeedingLlm } = indexEntries(db, allStashDirs, stashDir, isIncremental, builtAtMs);

package/dist/provider-registry.js

@@ -0,0 +1,8 @@
+// ── Factory map ─────────────────────────────────────────────────────────────
+const providers = new Map();
+export function registerProvider(type, factory) {
+    providers.set(type, factory);
+}
+export function resolveProviderFactory(type) {
+    return providers.get(type) ?? null;
+}

package/dist/providers/skills-sh.js

@@ -0,0 +1,166 @@
+import fs from "node:fs";
+import path from "node:path";
+import { fetchWithRetry } from "../common";
+import { getRegistryIndexCacheDir } from "../paths";
+import { registerProvider } from "../provider-registry";
+// ── Constants ───────────────────────────────────────────────────────────────
+/** Per-query cache TTL in milliseconds (15 minutes). */
+const QUERY_CACHE_TTL_MS = 15 * 60 * 1000;
+/** Maximum age before query cache is considered stale but still usable (1 day). */
+const QUERY_CACHE_STALE_MS = 24 * 60 * 60 * 1000;
+// ── Provider class ──────────────────────────────────────────────────────────
+class SkillsShProvider {
+    type = "skills-sh";
+    config;
+    constructor(config) {
+        this.config = config;
+    }
+    async search(options) {
+        try {
+            const entries = await this.fetchSkills(options.query, options.limit);
+            const limited = entries.slice(0, options.limit);
+            const hits = this.mapToHits(limited);
+            let assetHits;
+            if (options.includeAssets) {
+                assetHits = this.mapToAssetHits(limited);
+            }
+            return { hits, assetHits };
+        }
+        catch (err) {
+            const label = this.config.name ?? "skills.sh";
+            const message = err instanceof Error ? err.message : String(err);
+            return { hits: [], warnings: [`Registry ${label}: ${message}`] };
+        }
+    }
+    async fetchSkills(query, limit) {
+        // Check per-query cache first
+        const cachePath = this.queryCachePath(query, limit);
+        const cached = this.readQueryCache(cachePath);
+        if (cached && !isExpired(cached.mtime, QUERY_CACHE_TTL_MS)) {
+            return cached.entries;
+        }
+        // Fetch from API
+        const baseUrl = this.config.url.replace(/\/+$/, "");
+        const url = `${baseUrl}/api/search?q=${encodeURIComponent(query)}&limit=${limit}`;
+        try {
+            const response = await fetchWithRetry(url, undefined, { timeout: 10_000, retries: 1 });
+            if (!response.ok) {
+                throw new Error(`HTTP ${response.status}`);
+            }
+            const data = (await response.json());
+            const entries = parseSkillsResponse(data);
+            this.writeQueryCache(cachePath, entries);
+            return entries;
+        }
+        catch (err) {
+            // Fall back to stale cache if available
+            if (cached && !isExpired(cached.mtime, QUERY_CACHE_STALE_MS)) {
+                return cached.entries;
+            }
+            throw err;
+        }
+    }
+    mapToHits(entries) {
+        if (entries.length === 0)
+            return [];
+        // Assign decreasing synthetic scores for merge compatibility
+        const maxInstalls = Math.max(...entries.map((e) => e.installs), 1);
+        const registryName = this.config.name ?? "skills.sh";
+        const baseUrl = this.config.url.replace(/\/+$/, "");
+        return entries.map((entry) => {
+            const owner = entry.source.split("/")[0] ?? "";
+            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}`,
+                homepage: `${baseUrl}/${entry.id}`,
+                score,
+                metadata: {
+                    installs: String(entry.installs),
+                    ...(owner ? { author: owner } : {}),
+                },
+                registryName,
+            };
+        });
+    }
+    mapToAssetHits(entries) {
+        if (entries.length === 0)
+            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,
+        }));
+        return hits.length > 0 ? hits : undefined;
+    }
+    // ── Per-query cache ─────────────────────────────────────────────────────
+    queryCachePath(query, limit) {
+        const cacheDir = getRegistryIndexCacheDir();
+        const hasher = new Bun.CryptoHasher("md5");
+        hasher.update(this.config.url);
+        hasher.update("\0");
+        hasher.update(query.trim().toLowerCase());
+        hasher.update("\0");
+        hasher.update(String(limit));
+        const hash = hasher.digest("hex");
+        return path.join(cacheDir, `skills-sh-search-${hash}.json`);
+    }
+    readQueryCache(cachePath) {
+        try {
+            const stat = fs.statSync(cachePath);
+            const raw = JSON.parse(fs.readFileSync(cachePath, "utf8"));
+            if (!Array.isArray(raw))
+                return null;
+            const entries = raw.filter(isValidSkillsEntry);
+            return { entries, mtime: stat.mtimeMs };
+        }
+        catch {
+            return null;
+        }
+    }
+    writeQueryCache(cachePath, entries) {
+        try {
+            const dir = path.dirname(cachePath);
+            fs.mkdirSync(dir, { recursive: true });
+            const tmpPath = `${cachePath}.tmp.${process.pid}`;
+            fs.writeFileSync(tmpPath, JSON.stringify(entries), "utf8");
+            fs.renameSync(tmpPath, cachePath);
+        }
+        catch {
+            // Best-effort caching
+        }
+    }
+}
+// ── Self-register ───────────────────────────────────────────────────────────
+registerProvider("skills-sh", (config) => new SkillsShProvider(config));
+// ── Response parsing ────────────────────────────────────────────────────────
+function parseSkillsResponse(data) {
+    if (typeof data !== "object" || data === null || Array.isArray(data))
+        return [];
+    const obj = data;
+    if (!Array.isArray(obj.skills))
+        return [];
+    return obj.skills.filter(isValidSkillsEntry);
+}
+function isValidSkillsEntry(entry) {
+    if (typeof entry !== "object" || entry === null || Array.isArray(entry))
+        return false;
+    const obj = entry;
+    return (typeof obj.id === "string" &&
+        typeof obj.name === "string" &&
+        typeof obj.installs === "number" &&
+        typeof obj.source === "string");
+}
+// ── Utilities ───────────────────────────────────────────────────────────────
+function isExpired(mtimeMs, ttlMs) {
+    return Date.now() - mtimeMs > ttlMs;
+}

package/dist/providers/static-index.js

@@ -0,0 +1,347 @@
+import fs from "node:fs";
+import path from "node:path";
+import { fetchWithRetry } from "../common";
+import { getRegistryIndexCacheDir } from "../paths";
+import { registerProvider } from "../provider-registry";
+// ── Constants ───────────────────────────────────────────────────────────────
+/** Cache TTL in milliseconds (1 hour). */
+const CACHE_TTL_MS = 60 * 60 * 1000;
+/** Maximum age before cache is considered stale but still usable as fallback (7 days). */
+const CACHE_STALE_MS = 7 * 24 * 60 * 60 * 1000;
+// ── Provider class ──────────────────────────────────────────────────────────
+class StaticIndexProvider {
+    type = "static-index";
+    config;
+    constructor(config) {
+        this.config = config;
+    }
+    async search(options) {
+        const warnings = [];
+        const allKits = [];
+        try {
+            const index = await loadIndex(this.config);
+            if (index) {
+                const regName = this.config.name;
+                for (const kit of index.kits) {
+                    allKits.push({ kit, registryName: regName });
+                }
+            }
+        }
+        catch (err) {
+            const label = this.config.name ? `${this.config.name} (${this.config.url})` : this.config.url;
+            warnings.push(`Registry ${label}: ${toErrorMessage(err)}`);
+        }
+        const hits = scoreKits(allKits, options.query, options.limit);
+        let assetHits;
+        if (options.includeAssets) {
+            const scored = scoreAssets(allKits, options.query, options.limit);
+            if (scored.length > 0)
+                assetHits = scored;
+        }
+        return { hits, assetHits, warnings: warnings.length > 0 ? warnings : undefined };
+    }
+}
+// ── Self-register ───────────────────────────────────────────────────────────
+registerProvider("static-index", (config) => new StaticIndexProvider(config));
+// ── Index loading with cache ────────────────────────────────────────────────
+async function loadIndex(entry) {
+    const cachePath = indexCachePath(entry.url);
+    const cached = readCachedIndex(cachePath);
+    // Fresh cache: return immediately
+    if (cached && !isCacheExpired(cached.mtime)) {
+        return cached.index;
+    }
+    // Try to fetch fresh index
+    try {
+        const response = await fetchWithRetry(entry.url, undefined, { timeout: 10_000 });
+        if (!response.ok) {
+            throw new Error(`HTTP ${response.status}`);
+        }
+        const data = (await response.json());
+        const index = parseRegistryIndex(data);
+        if (index) {
+            writeCachedIndex(cachePath, index);
+            return index;
+        }
+        throw new Error("Invalid registry index format");
+    }
+    catch (err) {
+        // Fetch failed — use stale cache if available
+        if (cached && !isCacheStale(cached.mtime)) {
+            return cached.index;
+        }
+        throw err;
+    }
+}
+// ── Cache helpers (exported for reuse by other providers) ───────────────────
+export function indexCachePath(url) {
+    const indexDir = getRegistryIndexCacheDir();
+    // Deterministic filename from URL
+    const slug = url
+        .replace(/[^a-zA-Z0-9]+/g, "-")
+        .replace(/^-+|-+$/g, "")
+        .slice(0, 120);
+    return path.join(indexDir, `${slug}.json`);
+}
+export function readCachedIndex(cachePath) {
+    try {
+        const stat = fs.statSync(cachePath);
+        const raw = JSON.parse(fs.readFileSync(cachePath, "utf8"));
+        const index = parseRegistryIndex(raw);
+        if (!index)
+            return null;
+        return { index, mtime: stat.mtimeMs };
+    }
+    catch {
+        return null;
+    }
+}
+export function writeCachedIndex(cachePath, index) {
+    try {
+        const dir = path.dirname(cachePath);
+        fs.mkdirSync(dir, { recursive: true });
+        const tmpPath = `${cachePath}.tmp.${process.pid}`;
+        fs.writeFileSync(tmpPath, JSON.stringify(index), "utf8");
+        fs.renameSync(tmpPath, cachePath);
+    }
+    catch {
+        // Best-effort caching — don't fail the search if we can't write
+    }
+}
+export function isCacheExpired(mtimeMs) {
+    return Date.now() - mtimeMs > CACHE_TTL_MS;
+}
+export function isCacheStale(mtimeMs) {
+    return Date.now() - mtimeMs > CACHE_STALE_MS;
+}
+// ── Index parsing (exported for reuse) ──────────────────────────────────────
+export function parseRegistryIndex(data) {
+    if (typeof data !== "object" || data === null || Array.isArray(data))
+        return null;
+    const obj = data;
+    if (typeof obj.version !== "number" || (obj.version !== 1 && obj.version !== 2))
+        return null;
+    if (typeof obj.updatedAt !== "string")
+        return null;
+    if (!Array.isArray(obj.kits))
+        return null;
+    const kits = obj.kits.flatMap((raw) => {
+        const kit = parseKitEntry(raw);
+        return kit ? [kit] : [];
+    });
+    return { version: obj.version, updatedAt: obj.updatedAt, kits };
+}
+// ── Kit entry parsing ───────────────────────────────────────────────────────
+function parseKitEntry(raw) {
+    if (typeof raw !== "object" || raw === null || Array.isArray(raw))
+        return null;
+    const obj = raw;
+    const id = asString(obj.id);
+    const name = asString(obj.name);
+    const ref = asString(obj.ref);
+    const source = asSource(obj.source);
+    if (!id || !name || !ref || !source)
+        return null;
+    return {
+        id,
+        name,
+        ref,
+        source,
+        description: asString(obj.description),
+        homepage: asString(obj.homepage),
+        tags: asStringArray(obj.tags),
+        assetTypes: asStringArray(obj.assetTypes),
+        assets: parseAssets(obj.assets),
+        author: asString(obj.author),
+        license: asString(obj.license),
+        latestVersion: asString(obj.latestVersion),
+        curated: obj.curated === true ? true : undefined,
+    };
+}
+// ── Scoring ─────────────────────────────────────────────────────────────────
+function scoreKits(kits, query, limit) {
+    const tokens = query.toLowerCase().split(/\s+/).filter(Boolean);
+    const scored = [];
+    for (const { kit, registryName } of kits) {
+        const score = scoreKit(kit, tokens);
+        if (score > 0) {
+            scored.push({ kit, registryName, score });
+        }
+    }
+    scored.sort((a, b) => b.score - a.score);
+    return scored.slice(0, limit).map(({ kit, registryName, score }) => toSearchHit(kit, score, registryName));
+}
+function scoreKit(kit, tokens) {
+    let score = 0;
+    const nameLower = kit.name.toLowerCase();
+    const descLower = (kit.description ?? "").toLowerCase();
+    const tagsLower = (kit.tags ?? []).map((t) => t.toLowerCase());
+    for (const token of tokens) {
+        // Exact name match is strongest signal
+        if (nameLower === token) {
+            score += 1.0;
+        }
+        else if (nameLower.includes(token)) {
+            score += 0.6;
+        }
+        // Tag matches are high-signal (curated keywords)
+        if (tagsLower.some((tag) => tag === token)) {
+            score += 0.5;
+        }
+        else if (tagsLower.some((tag) => tag.includes(token))) {
+            score += 0.25;
+        }
+        // Description substring
+        if (descLower.includes(token)) {
+            score += 0.2;
+        }
+        // Author match
+        if (kit.author?.toLowerCase().includes(token)) {
+            score += 0.15;
+        }
+    }
+    // Normalize by token count so multi-word queries don't inflate scores
+    return tokens.length > 0 ? score / tokens.length : 0;
+}
+function toSearchHit(kit, score, registryName) {
+    const metadata = {};
+    if (kit.latestVersion)
+        metadata.version = kit.latestVersion;
+    if (kit.author)
+        metadata.author = kit.author;
+    if (kit.license)
+        metadata.license = kit.license;
+    if (kit.assetTypes?.length)
+        metadata.assetTypes = kit.assetTypes.join(", ");
+    return {
+        source: kit.source,
+        id: kit.id,
+        title: kit.name,
+        description: kit.description,
+        ref: kit.ref,
+        installRef: buildInstallRef(kit.source, kit.ref),
+        homepage: kit.homepage,
+        score: Math.round(score * 1000) / 1000,
+        metadata,
+        curated: kit.curated,
+        registryName,
+    };
+}
+// ── Asset parsing ───────────────────────────────────────────────────────────
+function parseAssets(raw) {
+    if (!Array.isArray(raw))
+        return undefined;
+    const parsed = raw.flatMap((item) => {
+        const entry = parseAssetEntry(item);
+        return entry ? [entry] : [];
+    });
+    return parsed.length > 0 ? parsed : undefined;
+}
+function parseAssetEntry(raw) {
+    if (typeof raw !== "object" || raw === null || Array.isArray(raw))
+        return null;
+    const obj = raw;
+    const type = asString(obj.type);
+    const name = asString(obj.name);
+    if (!type || !name)
+        return null;
+    return {
+        type,
+        name,
+        description: asString(obj.description),
+        tags: asStringArray(obj.tags),
+    };
+}
+// ── Asset-level scoring ─────────────────────────────────────────────────────
+function scoreAssets(kits, query, limit) {
+    const tokens = query.toLowerCase().split(/\s+/).filter(Boolean);
+    if (tokens.length === 0)
+        return [];
+    const scored = [];
+    for (const { kit, registryName } of kits) {
+        if (!kit.assets || kit.assets.length === 0)
+            continue;
+        const installRef = buildInstallRef(kit.source, kit.ref);
+        for (const asset of kit.assets) {
+            const score = scoreAsset(asset, tokens);
+            if (score > 0) {
+                scored.push({
+                    hit: {
+                        type: "registry-asset",
+                        assetType: asset.type,
+                        assetName: asset.name,
+                        description: asset.description,
+                        kit: { id: kit.id, name: kit.name },
+                        registryName,
+                        action: `akm add ${installRef}`,
+                        score: Math.round(score * 1000) / 1000,
+                    },
+                    score,
+                });
+            }
+        }
+    }
+    scored.sort((a, b) => b.score - a.score);
+    return scored.slice(0, limit).map(({ hit }) => hit);
+}
+function scoreAsset(asset, tokens) {
+    let score = 0;
+    const nameLower = asset.name.toLowerCase();
+    const descLower = (asset.description ?? "").toLowerCase();
+    const tagsLower = (asset.tags ?? []).map((t) => t.toLowerCase());
+    const typeLower = asset.type.toLowerCase();
+    for (const token of tokens) {
+        if (nameLower === token) {
+            score += 1.0;
+        }
+        else if (nameLower.includes(token)) {
+            score += 0.6;
+        }
+        if (typeLower === token) {
+            score += 0.4;
+        }
+        else if (typeLower.includes(token)) {
+            score += 0.2;
+        }
+        if (tagsLower.some((tag) => tag === token)) {
+            score += 0.5;
+        }
+        else if (tagsLower.some((tag) => tag.includes(token))) {
+            score += 0.25;
+        }
+        if (descLower.includes(token)) {
+            score += 0.2;
+        }
+    }
+    return tokens.length > 0 ? score / tokens.length : 0;
+}
+// ── Utilities ───────────────────────────────────────────────────────────────
+function asString(value) {
+    return typeof value === "string" && value ? value : undefined;
+}
+function asSource(value) {
+    if (value === "npm" || value === "github" || value === "git" || value === "local")
+        return value;
+    return undefined;
+}
+function asStringArray(value) {
+    if (!Array.isArray(value))
+        return undefined;
+    const filtered = value.filter((v) => typeof v === "string");
+    return filtered.length > 0 ? filtered : undefined;
+}
+function buildInstallRef(source, ref) {
+    switch (source) {
+        case "npm":
+            return `npm:${ref}`;
+        case "git":
+            return `git+${ref}`;
+        case "local":
+            return ref;
+        default:
+            return `github:${ref}`;
+    }
+}
+function toErrorMessage(error) {
+    return error instanceof Error ? error.message : String(error);
+}

package/dist/registry-provider.js

@@ -0,0 +1 @@
+export {};

package/dist/registry-resolve.js

@@ -9,6 +9,12 @@ export function parseRegistryRef(rawRef) {
     const ref = rawRef.trim();
     if (!ref)
         throw new Error("Registry ref is required.");
+    // Detect registry search result IDs (e.g. "skills-sh:org/skills/name")
+    // that are not installable refs. Known installable prefixes are handled below.
+    const registryIdHint = detectRegistrySearchId(ref);
+    if (registryIdHint) {
+        throw new Error(registryIdHint);
+    }
     if (ref.startsWith("npm:")) {
         return parseNpmRef(ref.slice(4), ref);
     }
@@ -33,6 +39,37 @@ export function parseRegistryRef(rawRef) {
     }
     return parseGithubShorthand(ref, ref);
 }
+/**
+ * Known prefixes that `parseRegistryRef` handles as installable sources.
+ * Anything with a colon that doesn't start with one of these is likely a
+ * registry search result ID (e.g. `skills-sh:org/skills/name`).
+ */
+const KNOWN_PREFIXES = ["npm:", "github:", "git+", "file:", "http://", "https://"];
+function detectRegistrySearchId(ref) {
+    const colonIdx = ref.indexOf(":");
+    if (colonIdx < 1)
+        return undefined;
+    // Skip known installable prefixes
+    for (const prefix of KNOWN_PREFIXES) {
+        if (ref.startsWith(prefix))
+            return undefined;
+    }
+    const prefix = ref.slice(0, colonIdx);
+    // Registry IDs use lowercase-with-hyphens prefixes (e.g. skills-sh, static-index)
+    if (!/^[a-z][a-z0-9-]*$/.test(prefix))
+        return undefined;
+    const rest = ref.slice(colonIdx + 1);
+    return [
+        `"${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");
+}
 export async function resolveRegistryArtifact(parsed) {
     if (parsed.source === "npm") {
         return resolveNpmArtifact(parsed);

package/dist/registry-search.js

@@ -1,13 +1,8 @@
-import fs from "node:fs";
-import path from "node:path";
-import { fetchWithRetry } from "./common";
 import { DEFAULT_CONFIG, loadConfig } from "./config";
-import { getRegistryIndexCacheDir } from "./paths";
-// ── Constants ───────────────────────────────────────────────────────────────
-/** Cache TTL in milliseconds (1 hour). */
-const CACHE_TTL_MS = 60 * 60 * 1000;
-/** Maximum age before cache is considered stale but still usable as fallback (7 days). */
-const CACHE_STALE_MS = 7 * 24 * 60 * 60 * 1000;
+import { resolveProviderFactory } from "./provider-registry";
+// ── Eagerly import providers to trigger self-registration ───────────────────
+import "./providers/static-index";
+import "./providers/skills-sh";
 // ── Public API ──────────────────────────────────────────────────────────────
 export async function searchRegistry(query, options) {
     const trimmed = query.trim();
@@ -15,33 +10,45 @@ export async function searchRegistry(query, options) {
         return { query: "", hits: [], warnings: [] };
     }
     const limit = clampLimit(options?.limit);
-    const entries = (options?.registries ?? resolveRegistries()).filter((r) => r.enabled !== false);
+    // resolveRegistries() already filters by enabled; explicit registries are filtered here
+    const raw = options?.registries ?? resolveRegistries();
+    const entries = options?.registries ? raw.filter((r) => r.enabled !== false) : raw;
     const warnings = [];
-    // Load index from all configured registries, merge kits
-    const allKits = [];
-    for (const entry of entries) {
-        try {
-            const index = await loadIndex(entry);
-            if (index) {
-                const regName = entry.name;
-                for (const kit of index.kits) {
-                    allKits.push({ kit, registryName: regName });
-                }
-            }
-        }
-        catch (err) {
-            const label = entry.name ? `${entry.name} (${entry.url})` : entry.url;
-            warnings.push(`Registry ${label}: ${toErrorMessage(err)}`);
+    // Resolve and search all providers concurrently
+    const results = await Promise.allSettled(entries.map((entry) => {
+        const provider = createProvider(entry, warnings);
+        if (!provider)
+            return Promise.resolve(null);
+        return provider.search({ query: trimmed, limit, includeAssets: options?.includeAssets });
+    }));
+    // Merge results grouped by provider
+    const allHits = [];
+    const allAssetHits = [];
+    for (const result of results) {
+        if (result.status === "rejected") {
+            warnings.push(toErrorMessage(result.reason));
+            continue;
         }
+        const value = result.value;
+        if (!value)
+            continue;
+        allHits.push(...value.hits);
+        if (value.assetHits)
+            allAssetHits.push(...value.assetHits);
+        if (value.warnings)
+            warnings.push(...value.warnings);
     }
-    // Score and rank
-    const hits = scoreKits(allKits, trimmed, limit);
-    // When includeAssets is enabled, also search asset-level metadata
-    let assetHits = [];
-    if (options?.includeAssets) {
-        assetHits = scoreAssets(allKits, trimmed, limit);
-    }
-    return { query: trimmed, hits, warnings, assetHits: assetHits.length > 0 ? assetHits : undefined };
+    // Sort merged hits by score descending, apply limit
+    allHits.sort((a, b) => (b.score ?? 0) - (a.score ?? 0));
+    const limitedHits = allHits.slice(0, limit);
+    allAssetHits.sort((a, b) => (b.score ?? 0) - (a.score ?? 0));
+    const limitedAssetHits = allAssetHits.slice(0, limit);
+    return {
+        query: trimmed,
+        hits: limitedHits,
+        warnings,
+        assetHits: limitedAssetHits.length > 0 ? limitedAssetHits : undefined,
+    };
 }
 // ── Registry resolution ─────────────────────────────────────────────────────
 /**
@@ -65,280 +72,16 @@ export function resolveRegistries(configRegistries) {
     const registries = configRegistries ?? loadConfig().registries ?? DEFAULT_CONFIG.registries ?? [];
     return registries.filter((r) => r.enabled !== false);
 }
-// ── Index loading with cache ────────────────────────────────────────────────
-async function loadIndex(entry) {
-    const cachePath = indexCachePath(entry.url);
-    const cached = readCachedIndex(cachePath);
-    // Fresh cache: return immediately
-    if (cached && !isCacheExpired(cached.mtime)) {
-        return cached.index;
-    }
-    // Try to fetch fresh index
-    try {
-        const response = await fetchWithRetry(entry.url, undefined, { timeout: 10_000 });
-        if (!response.ok) {
-            throw new Error(`HTTP ${response.status}`);
-        }
-        const data = (await response.json());
-        const index = parseRegistryIndex(data);
-        if (index) {
-            writeCachedIndex(cachePath, index);
-            return index;
-        }
-        throw new Error("Invalid registry index format");
-    }
-    catch (err) {
-        // Fetch failed — use stale cache if available
-        if (cached && !isCacheStale(cached.mtime)) {
-            return cached.index;
-        }
-        throw err;
-    }
-}
-function readCachedIndex(cachePath) {
-    try {
-        const stat = fs.statSync(cachePath);
-        const raw = JSON.parse(fs.readFileSync(cachePath, "utf8"));
-        const index = parseRegistryIndex(raw);
-        if (!index)
-            return null;
-        return { index, mtime: stat.mtimeMs };
-    }
-    catch {
-        return null;
-    }
-}
-function writeCachedIndex(cachePath, index) {
-    try {
-        const dir = path.dirname(cachePath);
-        fs.mkdirSync(dir, { recursive: true });
-        const tmpPath = `${cachePath}.tmp.${process.pid}`;
-        fs.writeFileSync(tmpPath, JSON.stringify(index), "utf8");
-        fs.renameSync(tmpPath, cachePath);
-    }
-    catch {
-        // Best-effort caching — don't fail the search if we can't write
-    }
-}
-function indexCachePath(url) {
-    const indexDir = getRegistryIndexCacheDir();
-    // Deterministic filename from URL
-    const slug = url
-        .replace(/[^a-zA-Z0-9]+/g, "-")
-        .replace(/^-+|-+$/g, "")
-        .slice(0, 120);
-    return path.join(indexDir, `${slug}.json`);
-}
-function isCacheExpired(mtimeMs) {
-    return Date.now() - mtimeMs > CACHE_TTL_MS;
-}
-function isCacheStale(mtimeMs) {
-    return Date.now() - mtimeMs > CACHE_STALE_MS;
-}
-// ── Index parsing ───────────────────────────────────────────────────────────
-function parseRegistryIndex(data) {
-    if (typeof data !== "object" || data === null || Array.isArray(data))
-        return null;
-    const obj = data;
-    if (typeof obj.version !== "number" || (obj.version !== 1 && obj.version !== 2))
-        return null;
-    if (typeof obj.updatedAt !== "string")
-        return null;
-    if (!Array.isArray(obj.kits))
-        return null;
-    const kits = obj.kits.flatMap((raw) => {
-        const kit = parseKitEntry(raw);
-        return kit ? [kit] : [];
-    });
-    return { version: obj.version, updatedAt: obj.updatedAt, kits };
-}
-function parseKitEntry(raw) {
-    if (typeof raw !== "object" || raw === null || Array.isArray(raw))
-        return null;
-    const obj = raw;
-    const id = asString(obj.id);
-    const name = asString(obj.name);
-    const ref = asString(obj.ref);
-    const source = asSource(obj.source);
-    if (!id || !name || !ref || !source)
-        return null;
-    return {
-        id,
-        name,
-        ref,
-        source,
-        description: asString(obj.description),
-        homepage: asString(obj.homepage),
-        tags: asStringArray(obj.tags),
-        assetTypes: asStringArray(obj.assetTypes),
-        assets: parseAssets(obj.assets),
-        author: asString(obj.author),
-        license: asString(obj.license),
-        latestVersion: asString(obj.latestVersion),
-        curated: obj.curated === true ? true : undefined,
-    };
-}
-// ── Scoring ─────────────────────────────────────────────────────────────────
-function scoreKits(kits, query, limit) {
-    const tokens = query.toLowerCase().split(/\s+/).filter(Boolean);
-    const scored = [];
-    for (const { kit, registryName } of kits) {
-        const score = scoreKit(kit, tokens);
-        if (score > 0) {
-            scored.push({ kit, registryName, score });
-        }
-    }
-    scored.sort((a, b) => b.score - a.score);
-    return scored.slice(0, limit).map(({ kit, registryName, score }) => toSearchHit(kit, score, registryName));
-}
-function scoreKit(kit, tokens) {
-    let score = 0;
-    const nameLower = kit.name.toLowerCase();
-    const descLower = (kit.description ?? "").toLowerCase();
-    const tagsLower = (kit.tags ?? []).map((t) => t.toLowerCase());
-    for (const token of tokens) {
-        // Exact name match is strongest signal
-        if (nameLower === token) {
-            score += 1.0;
-        }
-        else if (nameLower.includes(token)) {
-            score += 0.6;
-        }
-        // Tag matches are high-signal (curated keywords)
-        if (tagsLower.some((tag) => tag === token)) {
-            score += 0.5;
-        }
-        else if (tagsLower.some((tag) => tag.includes(token))) {
-            score += 0.25;
-        }
-        // Description substring
-        if (descLower.includes(token)) {
-            score += 0.2;
-        }
-        // Author match
-        if (kit.author?.toLowerCase().includes(token)) {
-            score += 0.15;
-        }
-    }
-    // Normalize by token count so multi-word queries don't inflate scores
-    return tokens.length > 0 ? score / tokens.length : 0;
-}
-function toSearchHit(kit, score, registryName) {
-    const metadata = {};
-    if (kit.latestVersion)
-        metadata.version = kit.latestVersion;
-    if (kit.author)
-        metadata.author = kit.author;
-    if (kit.license)
-        metadata.license = kit.license;
-    if (kit.assetTypes?.length)
-        metadata.assetTypes = kit.assetTypes.join(", ");
-    return {
-        source: kit.source,
-        id: kit.id,
-        title: kit.name,
-        description: kit.description,
-        ref: kit.ref,
-        homepage: kit.homepage,
-        score: Math.round(score * 1000) / 1000,
-        metadata,
-        curated: kit.curated,
-        registryName,
-    };
-}
-// ── Asset parsing ────────────────────────────────────────────────────────────
-function parseAssets(raw) {
-    if (!Array.isArray(raw))
-        return undefined;
-    const parsed = raw.flatMap((item) => {
-        const entry = parseAssetEntry(item);
-        return entry ? [entry] : [];
-    });
-    return parsed.length > 0 ? parsed : undefined;
-}
-function parseAssetEntry(raw) {
-    if (typeof raw !== "object" || raw === null || Array.isArray(raw))
+// ── Provider resolution ─────────────────────────────────────────────────────
+function createProvider(entry, warnings) {
+    const providerType = entry.provider ?? "static-index";
+    const factory = resolveProviderFactory(providerType);
+    if (!factory) {
+        const label = entry.name ? `${entry.name} (${entry.url})` : entry.url;
+        warnings.push(`Registry ${label}: unknown provider type "${providerType}"`);
         return null;
-    const obj = raw;
-    const type = asString(obj.type);
-    const name = asString(obj.name);
-    if (!type || !name)
-        return null;
-    return {
-        type,
-        name,
-        description: asString(obj.description),
-        tags: asStringArray(obj.tags),
-    };
-}
-// ── Asset-level scoring ──────────────────────────────────────────────────────
-function scoreAssets(kits, query, limit) {
-    const tokens = query.toLowerCase().split(/\s+/).filter(Boolean);
-    if (tokens.length === 0)
-        return [];
-    const scored = [];
-    for (const { kit, registryName } of kits) {
-        if (!kit.assets || kit.assets.length === 0)
-            continue;
-        const installRef = kit.source === "npm"
-            ? `npm:${kit.ref}`
-            : kit.source === "git"
-                ? `git+${kit.ref}`
-                : kit.source === "local"
-                    ? kit.ref
-                    : `github:${kit.ref}`;
-        for (const asset of kit.assets) {
-            const score = scoreAsset(asset, tokens);
-            if (score > 0) {
-                scored.push({
-                    hit: {
-                        type: "registry-asset",
-                        assetType: asset.type,
-                        assetName: asset.name,
-                        description: asset.description,
-                        kit: { id: kit.id, name: kit.name },
-                        registryName,
-                        action: `akm add ${installRef}`,
-                        score: Math.round(score * 1000) / 1000,
-                    },
-                    score,
-                });
-            }
-        }
-    }
-    scored.sort((a, b) => b.score - a.score);
-    return scored.slice(0, limit).map(({ hit }) => hit);
-}
-function scoreAsset(asset, tokens) {
-    let score = 0;
-    const nameLower = asset.name.toLowerCase();
-    const descLower = (asset.description ?? "").toLowerCase();
-    const tagsLower = (asset.tags ?? []).map((t) => t.toLowerCase());
-    const typeLower = asset.type.toLowerCase();
-    for (const token of tokens) {
-        if (nameLower === token) {
-            score += 1.0;
-        }
-        else if (nameLower.includes(token)) {
-            score += 0.6;
-        }
-        if (typeLower === token) {
-            score += 0.4;
-        }
-        else if (typeLower.includes(token)) {
-            score += 0.2;
-        }
-        if (tagsLower.some((tag) => tag === token)) {
-            score += 0.5;
-        }
-        else if (tagsLower.some((tag) => tag.includes(token))) {
-            score += 0.25;
-        }
-        if (descLower.includes(token)) {
-            score += 0.2;
-        }
     }
-    return tokens.length > 0 ? score / tokens.length : 0;
+    return factory(entry);
 }
 // ── Utilities ───────────────────────────────────────────────────────────────
 function clampLimit(limit) {
@@ -346,20 +89,6 @@ function clampLimit(limit) {
         return 20;
     return Math.min(100, Math.max(1, Math.trunc(limit)));
 }
-function asString(value) {
-    return typeof value === "string" && value ? value : undefined;
-}
-function asSource(value) {
-    if (value === "npm" || value === "github" || value === "git" || value === "local")
-        return value;
-    return undefined;
-}
-function asStringArray(value) {
-    if (!Array.isArray(value))
-        return undefined;
-    const filtered = value.filter((v) => typeof v === "string");
-    return filtered.length > 0 ? filtered : undefined;
-}
 function toErrorMessage(error) {
     return error instanceof Error ? error.message : String(error);
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "akm-cli",
-  "version": "0.0.17",
+  "version": "0.0.19",
   "type": "module",
   "description": "CLI tool to search, open, and run extension assets from an akm stash directory.",
   "keywords": [