akm-cli 0.6.0-rc1 → 0.6.0-rc2

package/dist/{providers → registry/providers}/skills-sh.js

@@ -1,8 +1,8 @@
 import fs from "node:fs";
 import path from "node:path";
-import { fetchWithRetry } from "../common";
-import { getRegistryIndexCacheDir } from "../paths";
-import { registerProvider } from "../registry-factory";
+import { fetchWithRetry } from "../../core/common";
+import { getRegistryIndexCacheDir } from "../../core/paths";
+import { registerProvider } from "../factory";
 // ── Constants ───────────────────────────────────────────────────────────────
 /** Per-query cache TTL in milliseconds (15 minutes). */
 const QUERY_CACHE_TTL_MS = 15 * 60 * 1000;
@@ -32,6 +32,62 @@ class SkillsShProvider {
             return { hits: [], warnings: [`Registry ${label}: ${message}`] };
         }
     }
+    // ── v1-spec §3.1 surface ────────────────────────────────────────────────
+    async searchKits(q) {
+        const result = await this.search({
+            query: q.text,
+            limit: q.limit ?? 20,
+            includeAssets: false,
+        });
+        return result.hits.map((hit) => ({
+            id: hit.id,
+            title: hit.title,
+            summary: hit.description,
+            installRef: hit.installRef,
+            score: hit.score,
+        }));
+    }
+    async searchAssets(q) {
+        const result = await this.search({
+            query: q.text,
+            limit: q.limit ?? 20,
+            includeAssets: true,
+        });
+        return (result.assetHits ?? []).map((hit) => ({
+            kitId: hit.stash.id,
+            type: hit.assetType,
+            name: hit.assetName,
+            summary: hit.description,
+            cloneRef: hit.action.replace(/^akm add\s+/, ""),
+        }));
+    }
+    /**
+     * skills.sh has no `getKit` API — every entry corresponds to a GitHub
+     * repository whose metadata we already include in the search result. We
+     * synthesize a manifest from the search hit when the caller knows the kit
+     * id; if not present in the most recent results, return null.
+     */
+    async getKit(id) {
+        if (!id.startsWith("skills-sh:"))
+            return null;
+        const slug = id.slice("skills-sh:".length);
+        // Best-effort: the API gives us search-by-name; extract the leaf segment.
+        const segments = slug.split("/").filter(Boolean);
+        const leaf = segments[segments.length - 1] ?? slug;
+        const result = await this.search({ query: leaf, limit: 50, includeAssets: false });
+        const match = result.hits.find((hit) => hit.id === id);
+        if (!match)
+            return null;
+        return { id: match.id, installRef: match.installRef };
+    }
+    /**
+     * skills.sh entries are always GitHub repositories. Claim only refs whose
+     * parsed source is `github`; defer everything else (npm tarballs, local
+     * paths, raw git URLs) to other registries.
+     */
+    canHandle(ref) {
+        return ref.source === "github";
+    }
     async fetchSkills(query, limit) {
         // Check per-query cache first
         const cachePath = this.queryCachePath(query, limit);

package/dist/{providers → registry/providers}/static-index.js

@@ -1,9 +1,9 @@
 import fs from "node:fs";
 import path from "node:path";
-import { fetchWithRetry, jsonWithByteCap, toErrorMessage } from "../common";
-import { asString } from "../github";
-import { getRegistryIndexCacheDir } from "../paths";
-import { registerProvider } from "../registry-factory";
+import { fetchWithRetry, jsonWithByteCap, toErrorMessage } from "../../core/common";
+import { getRegistryIndexCacheDir } from "../../core/paths";
+import { asString } from "../../integrations/github";
+import { registerProvider } from "../factory";
 // ── Constants ───────────────────────────────────────────────────────────────
 /** Cache TTL in milliseconds (1 hour). */
 const CACHE_TTL_MS = 60 * 60 * 1000;
@@ -18,6 +18,63 @@ class StaticIndexProvider {
     }
     async search(options) {
         const warnings = [];
+        const allKits = await this.loadAllKits(warnings);
+        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 };
+    }
+    // ── v1-spec §3.1 surface ────────────────────────────────────────────────
+    async searchKits(q) {
+        const result = await this.search({
+            query: q.text,
+            limit: q.limit ?? 20,
+            includeAssets: false,
+        });
+        return result.hits.map(hitToKitResult);
+    }
+    async searchAssets(q) {
+        const result = await this.search({
+            query: q.text,
+            limit: q.limit ?? 20,
+            includeAssets: true,
+        });
+        return (result.assetHits ?? []).map(assetHitToPreview);
+    }
+    async getKit(id) {
+        const allKits = await this.loadAllKits([]);
+        const found = allKits.find(({ stash }) => stash.id === id);
+        if (!found)
+            return null;
+        const installRef = buildInstallRef(found.stash.source, found.stash.ref);
+        return {
+            id: found.stash.id,
+            installRef,
+            assets: found.stash.assets?.map((asset) => ({
+                kitId: found.stash.id,
+                type: asset.type,
+                name: asset.name,
+                summary: asset.description,
+                cloneRef: installRef,
+            })),
+        };
+    }
+    /**
+     * Static-index doesn't own a URL prefix — any `ParsedRegistryRef` could
+     * theoretically be backed by an entry in some static-index registry. We
+     * therefore claim every ref. The orchestrator picks the first matching
+     * provider, and `static-index` is registered first by `index.ts`, so this
+     * is effectively the default catch-all.
+     */
+    canHandle(_ref) {
+        return true;
+    }
+    // ── Internals ───────────────────────────────────────────────────────────
+    async loadAllKits(warnings) {
         const allKits = [];
         try {
             const index = await loadIndex(this.config);
@@ -32,16 +89,27 @@ class StaticIndexProvider {
             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 };
+        return allKits;
     }
 }
+function hitToKitResult(hit) {
+    return {
+        id: hit.id,
+        title: hit.title,
+        summary: hit.description,
+        installRef: hit.installRef,
+        score: hit.score,
+    };
+}
+function assetHitToPreview(hit) {
+    return {
+        kitId: hit.stash.id,
+        type: hit.assetType,
+        name: hit.assetName,
+        summary: hit.description,
+        cloneRef: hit.action.replace(/^akm add\s+/, ""),
+    };
+}
 // ── Self-register ───────────────────────────────────────────────────────────
 registerProvider("static-index", (config) => new StaticIndexProvider(config));
 // ── Index loading with cache ────────────────────────────────────────────────

package/dist/registry/providers/types.js

@@ -0,0 +1,25 @@
+/**
+ * Registry provider interface (v1 architecture spec §3.1).
+ *
+ * A `RegistryProvider` is a read-only catalog that lists installable kits and
+ * (optionally) previews assets within them. It is *not* a `SourceProvider`:
+ * registry providers do not materialise files to disk — they only answer
+ * discovery queries.
+ *
+ * The two built-in registry providers at v1 are:
+ *
+ * - `static-index` — reads the v2 JSON index schema (the official akm registry
+ *   and any static-hosted team registry). The v2 schema is owned by this
+ *   provider, not by core akm.
+ * - `skills-sh` — wraps the skills.sh REST API.
+ *
+ * Context Hub is **not** a registry provider — it is an ordinary git repository
+ * recommended via the official static-index registry (see CLAUDE.md).
+ *
+ * Note: the simple `search()` method is the v0.6 surface and remains the
+ * primary entry point used by the orchestrator. The `searchKits` /
+ * `searchAssets` / `getKit` / `canHandle` methods are the v1-spec contract
+ * (§3.1) which built-in providers also implement so the orchestrator can be
+ * iterated cleanly post-Phase 6 without reaching into provider-specific shapes.
+ */
+export {};

package/dist/{registry-resolve.js → registry/resolve.js}

@@ -3,9 +3,9 @@ import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
 import { fileURLToPath, pathToFileURL } from "node:url";
-import { fetchWithRetry, jsonWithByteCap } from "./common";
-import { UsageError } from "./errors";
-import { asRecord, asString, GITHUB_API_BASE, githubHeaders } from "./github";
+import { fetchWithRetry, jsonWithByteCap } from "../core/common";
+import { UsageError } from "../core/errors";
+import { asRecord, asString, GITHUB_API_BASE, githubHeaders } from "../integrations/github";
 /**
  * Validate that a URL is safe to pass to git.
  * Allowlists https:, http:, ssh:, git: schemes and git@ SSH shorthand.

package/dist/{detect.js → setup/detect.js}

@@ -91,30 +91,3 @@ export function detectAgentPlatforms() {
         path: path.join(home, p.relPath),
     }));
 }
-// ── OpenViking Detection ────────────────────────────────────────────────────
-/**
- * Check if an OpenViking server is reachable at the given URL.
- * Uses the lightweight /api/v1/fs/stat endpoint (GET) rather than
- * the search endpoint which requires a running search index.
- */
-export async function detectOpenViking(url) {
-    const normalized = url.replace(/\/+$/, "");
-    try {
-        // Any HTTP response (even non-2xx) from the API endpoint means the server is reachable.
-        // Only network errors / timeouts indicate the server is truly unavailable.
-        await fetch(`${normalized}/api/v1/fs/stat?uri=${encodeURIComponent("viking://")}`, {
-            signal: AbortSignal.timeout(5000),
-        });
-        return { available: true, url: normalized };
-    }
-    catch {
-        // stat endpoint unreachable — try root URL as fallback
-        try {
-            await fetch(normalized, { signal: AbortSignal.timeout(5000) });
-            return { available: true, url: normalized };
-        }
-        catch {
-            return { available: false, url: normalized };
-        }
-    }
-}

package/dist/{ripgrep-install.js → setup/ripgrep-install.js}

@@ -1,7 +1,7 @@
 import { spawnSync } from "node:child_process";
 import fs from "node:fs";
 import path from "node:path";
-import { IS_WINDOWS } from "./common";
+import { IS_WINDOWS } from "../core/common";
 import { RG_BINARY, resolveRg } from "./ripgrep-resolve";
 /**
  * Platform and architecture detection for ripgrep binary downloads.

package/dist/{ripgrep-resolve.js → setup/ripgrep-resolve.js}

@@ -1,7 +1,7 @@
 import fs from "node:fs";
 import path from "node:path";
-import { IS_WINDOWS } from "./common";
-import { getBinDir } from "./paths";
+import { IS_WINDOWS } from "../core/common";
+import { getBinDir } from "../core/paths";
 export const RG_BINARY = IS_WINDOWS ? "rg.exe" : "rg";
 function canExecute(filePath) {
     if (!fs.existsSync(filePath))

package/dist/{setup.js → setup/setup.js}

@@ -7,17 +7,17 @@
  */
 import path from "node:path";
 import * as p from "@clack/prompts";
-import { isHttpUrl } from "./common";
-import { DEFAULT_CONFIG, getConfigPath, loadUserConfig, saveConfig } from "./config";
-import { closeDatabase, isVecAvailable, openDatabase } from "./db";
-import { detectAgentPlatforms, detectOllama, detectOpenViking } from "./detect";
-import { checkEmbeddingAvailability, DEFAULT_LOCAL_MODEL, isTransformersAvailable } from "./embedder";
-import { akmIndex } from "./indexer";
-import { akmInit } from "./init";
-import { probeLlmCapabilities } from "./llm";
-import { getDefaultStashDir } from "./paths";
-import { clearSemanticStatus, deriveSemanticProviderFingerprint, writeSemanticStatus } from "./semantic-status";
-import { createSetupContext, runSetupSteps } from "./setup-steps";
+import { akmInit } from "../commands/init";
+import { isHttpUrl } from "../core/common";
+import { DEFAULT_CONFIG, getConfigPath, loadUserConfig, saveConfig } from "../core/config";
+import { getDefaultStashDir } from "../core/paths";
+import { closeDatabase, isVecAvailable, openDatabase } from "../indexer/db";
+import { akmIndex } from "../indexer/indexer";
+import { clearSemanticStatus, deriveSemanticProviderFingerprint, writeSemanticStatus, } from "../indexer/semantic-status";
+import { probeLlmCapabilities } from "../llm/client";
+import { checkEmbeddingAvailability, DEFAULT_LOCAL_MODEL, isTransformersAvailable } from "../llm/embedder";
+import { detectAgentPlatforms, detectOllama } from "./detect";
+import { createSetupContext, runSetupSteps } from "./steps";
 // ── Constants ───────────────────────────────────────────────────────────────
 /**
  * Recommended GitHub repositories shown during setup.
@@ -141,7 +141,7 @@ async function prepareSemanticSearchAssets(config) {
             const spin = p.spinner();
             spin.start("Installing @huggingface/transformers...");
             try {
-                const pkgRoot = path.resolve(import.meta.dir, "..");
+                const pkgRoot = path.resolve(import.meta.dir, "../..");
                 const proc = Bun.spawn(["bun", "add", "@huggingface/transformers"], {
                     cwd: pkgRoot,
                     stdout: "pipe",
@@ -500,8 +500,8 @@ async function stepRegistries(current) {
 /**
  * @internal Exported for testing only.
  */
-export async function stepStashSources(current) {
-    const stashes = [...(current.stashes ?? [])];
+export async function stepAddSources(current) {
+    const stashes = [...(current.sources ?? current.stashes ?? [])];
     if (stashes.length > 0) {
         p.log.info(`You have ${stashes.length} existing stash source(s).`);
     }
@@ -547,7 +547,6 @@ export async function stepStashSources(current) {
         const action = await prompt(() => p.select({
             message: "Add another stash source?",
             options: [
-                { value: "openviking", label: "OpenViking server", hint: "remote stash" },
                 { value: "github-repo", label: "GitHub repository", hint: "custom URL" },
                 { value: "filesystem", label: "Filesystem path", hint: "local directory" },
                 { value: "done", label: "Done — no more sources" },
@@ -557,45 +556,6 @@ export async function stepStashSources(current) {
             addMore = false;
             break;
         }
-        if (action === "openviking") {
-            const url = await promptOrBack(() => p.text({
-                message: "Enter the OpenViking server URL:",
-                placeholder: "https://your-openviking-server.example.com",
-                validate: (v) => {
-                    if (!v?.trim())
-                        return "URL cannot be empty";
-                    if (!v.startsWith("http://") && !v.startsWith("https://"))
-                        return "URL must start with http:// or https://";
-                },
-            }));
-            if (url === null)
-                continue;
-            const spin = p.spinner();
-            spin.start("Checking OpenViking server...");
-            const result = await detectOpenViking(url.trim());
-            if (result.available) {
-                spin.stop("Server is reachable");
-            }
-            else {
-                spin.stop("Server not reachable — adding anyway (it may be temporarily down)");
-            }
-            const name = await promptOrBack(() => p.text({
-                message: "Give this stash a name (optional):",
-                placeholder: "my-openviking",
-            }));
-            if (name === null)
-                continue;
-            // Use the normalized URL from detection (trailing slashes stripped)
-            const entry = { type: "openviking", url: result.url };
-            if (name.trim())
-                entry.name = name.trim();
-            if (!stashes.some((s) => s.url === entry.url)) {
-                stashes.push(entry);
-            }
-            else {
-                p.log.warn("This URL is already configured.");
-            }
-        }
         if (action === "github-repo") {
             const url = await promptOrBack(() => p.text({
                 message: "Enter the GitHub repository URL:",
@@ -761,14 +721,14 @@ export function buildSetupSteps(options) {
             id: "stash-sources",
             label: "Stash Sources",
             async run(ctx) {
-                const stashes = await stepStashSources(ctx.config);
+                const stashes = await stepAddSources(ctx.config);
                 const platforms = await stepAgentPlatforms(ctx.config);
                 const merged = [...stashes];
                 for (const ps of platforms) {
                     if (!merged.some((s) => s.path === ps.path))
                         merged.push(ps);
                 }
-                ctx.apply({ stashes: merged.length > 0 ? merged : undefined });
+                ctx.apply({ sources: merged.length > 0 ? merged : undefined });
             },
         },
     ];

package/dist/{stash-include.js → sources/include.js}

@@ -1,6 +1,6 @@
 import fs from "node:fs";
 import path from "node:path";
-import { isWithin } from "./common";
+import { isWithin } from "../core/common";
 // ── Helpers ─────────────────────────────────────────────────────────────────
 /** Key to check in package.json for akm include configuration. */
 const INCLUDE_CONFIG_KEYS = ["akm"];

package/dist/sources/provider-factory.js

@@ -0,0 +1,36 @@
+/**
+ * Source provider factory map.
+ *
+ * Maps source kind identifiers (e.g. "filesystem", "git", "website", "npm")
+ * to factory functions that build {@link SourceProvider} instances from a
+ * {@link SourceConfigEntry}.
+ *
+ * Distinct from the registry-discovery factory (`registry/factory.ts`).
+ * Both share `create-provider-registry.ts` for the underlying string→factory
+ * map.
+ */
+import { createProviderRegistry } from "../registry/create-provider-registry";
+// ── Factory map ─────────────────────────────────────────────────────────────
+const registry = createProviderRegistry();
+export function registerSourceProvider(type, factory) {
+    registry.register(type, factory);
+}
+export function resolveSourceProviderFactory(type) {
+    return registry.resolve(type);
+}
+/**
+ * Build a {@link SourceProvider} for every enabled source in the config that
+ * has a registered factory.
+ */
+export function resolveSourceProviders(config) {
+    const providers = [];
+    for (const entry of config.sources ?? config.stashes ?? []) {
+        if (entry.enabled === false)
+            continue;
+        const factory = registry.resolve(entry.type);
+        if (factory) {
+            providers.push(factory(entry));
+        }
+    }
+    return providers;
+}

package/dist/sources/provider.js

@@ -0,0 +1,21 @@
+/**
+ * SourceProvider — minimal v1 interface (spec §2.1).
+ *
+ * A SourceProvider gets files into a directory. The indexer walks `path()`
+ * and reads files from disk. Search and show go through the indexer, not
+ * through provider methods.
+ *
+ * Three required members + one optional:
+ *   - name      configured source name
+ *   - kind      "filesystem" | "git" | "website" | "npm"
+ *   - init(ctx) called once after construction
+ *   - path()    the directory the indexer walks (stable for instance lifetime)
+ *   - sync?()   refresh the directory from upstream (no-op for filesystem)
+ *
+ * All other writing/reading concerns live outside this interface:
+ *   - Writes:    src/core/write-source.ts (Phase 5)
+ *   - Reads:     src/indexer.ts (Phase 4)
+ *   - Install:   src/sources/providers/sync-from-ref.ts (install-time helpers,
+ *                separate from configured-source plumbing)
+ */
+export {};

package/dist/sources/providers/filesystem.js

@@ -0,0 +1,35 @@
+import { resolveStashDir } from "../../core/common";
+import { ConfigError } from "../../core/errors";
+import { registerSourceProvider } from "../provider-factory";
+/**
+ * Filesystem source — points at a directory the user already manages.
+ *
+ * Implements the v1 {@link SourceProvider} interface (spec §2.1, §2.4):
+ * just `{ name, kind, init, path }`. No `sync()` — content is the user's
+ * own directory, never refreshed by akm.
+ */
+class FilesystemSourceProvider {
+    kind = "filesystem";
+    name;
+    #stashDir;
+    constructor(entry) {
+        if (entry.type !== "filesystem") {
+            throw new ConfigError(`FilesystemSourceProvider invoked with type="${entry.type}"`);
+        }
+        this.#stashDir = entry.path ?? resolveStashDir();
+        if (!this.#stashDir) {
+            throw new ConfigError("filesystem source requires a `path`");
+        }
+        this.name = entry.name ?? this.#stashDir;
+    }
+    async init(_ctx) {
+        // Filesystem sources resolve their path eagerly in the constructor;
+        // init has nothing to do beyond letting the registry know we're ready.
+    }
+    path() {
+        return this.#stashDir;
+    }
+}
+// ── Self-register ───────────────────────────────────────────────────────────
+registerSourceProvider("filesystem", (config) => new FilesystemSourceProvider(config));
+export { FilesystemSourceProvider };