akm-cli 0.7.5 → 0.8.0-rc.6

package/dist/registry/providers/skills-sh.js

@@ -1,13 +1,13 @@
-import fs from "node:fs";
-import path from "node:path";
+// This Source Code Form is subject to the terms of the Mozilla Public
+// License, v. 2.0. If a copy of the MPL was not distributed with this
+// file, You can obtain one at https://mozilla.org/MPL/2.0/.
 import { fetchWithRetry } from "../../core/common";
-import { getRegistryIndexCacheDir } from "../../core/paths";
+import { rethrowIfTestIsolationError } from "../../core/errors";
+import { closeDatabase, getRegistryIndexCache, openDatabase, upsertRegistryIndexCache } from "../../indexer/db";
 import { registerProvider } from "../factory";
 // ── 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";
@@ -89,13 +89,38 @@ class SkillsShProvider {
         return ref.source === "github";
     }
     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;
+        // Build a stable DB cache key for this query
+        const dbCacheKey = this.queryDbCacheKey(query, limit);
+        // ── Step 1: Try DB cache (index.db) ───────────────────────────────────
+        let db;
+        let dbCacheResult;
+        try {
+            db = openDatabase();
+            dbCacheResult = getRegistryIndexCache(db, dbCacheKey, QUERY_CACHE_TTL_MS);
+        }
+        catch (err) {
+            // Never mask the bun-test isolation guard as "DB unavailable" — see
+            // rethrowIfTestIsolationError in src/core/errors.ts. Without this,
+            // a leaky test silently gets a cold cache + fresh fetch instead of
+            // the loud TEST_ISOLATION_MISSING failure the guard intends.
+            rethrowIfTestIsolationError(err);
+            // index.db not available yet (pre-migration install or test env) — fall through
         }
-        // Fetch from API
+        if (dbCacheResult) {
+            try {
+                const parsed = JSON.parse(dbCacheResult.indexJson);
+                if (Array.isArray(parsed)) {
+                    const entries = parsed.filter(isValidSkillsEntry);
+                    if (db)
+                        closeDatabase(db);
+                    return entries;
+                }
+            }
+            catch {
+                /* corrupt DB entry — fall through */
+            }
+        }
+        // ── Step 2: Fetch from API ─────────────────────────────────────────────
         const baseUrl = this.config.url.replace(/\/+$/, "");
         const url = `${baseUrl}/api/search?q=${encodeURIComponent(query)}&limit=${limit}`;
         try {
@@ -105,13 +130,40 @@ class SkillsShProvider {
             }
             const data = (await response.json());
             const entries = parseSkillsResponse(data);
-            this.writeQueryCache(cachePath, entries);
+            // Write to DB cache (primary)
+            if (db) {
+                try {
+                    upsertRegistryIndexCache(db, dbCacheKey, JSON.stringify(entries));
+                }
+                catch {
+                    /* best-effort */
+                }
+                closeDatabase(db);
+            }
             return entries;
         }
         catch (err) {
-            // Fall back to stale cache if available
-            if (cached && !isExpired(cached.mtime, QUERY_CACHE_STALE_MS)) {
-                return cached.entries;
+            if (db) {
+                try {
+                    closeDatabase(db);
+                }
+                catch {
+                    /* ignore */
+                }
+            }
+            // Fetch failed — use stale DB cache if available
+            if (dbCacheResult) {
+                try {
+                    const parsed = JSON.parse(dbCacheResult.indexJson);
+                    if (Array.isArray(parsed)) {
+                        const entries = parsed.filter(isValidSkillsEntry);
+                        if (entries.length > 0)
+                            return entries;
+                    }
+                }
+                catch {
+                    /* ignore */
+                }
             }
             throw err;
         }
@@ -167,9 +219,8 @@ class SkillsShProvider {
         });
         return hits.length > 0 ? hits : undefined;
     }
-    // ── Per-query cache ─────────────────────────────────────────────────────
-    queryCachePath(query, limit) {
-        const cacheDir = getRegistryIndexCacheDir();
+    // ── DB cache key ────────────────────────────────────────────────────────
+    queryDbCacheKey(query, limit) {
         const hasher = new Bun.CryptoHasher("md5");
         hasher.update(this.config.url);
         hasher.update("\0");
@@ -177,33 +228,7 @@ class SkillsShProvider {
         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}`;
-            // 0o600: owner read/write only — cache may contain search terms tied to API keys
-            fs.writeFileSync(tmpPath, JSON.stringify(entries), { encoding: "utf8", mode: 0o600 });
-            fs.renameSync(tmpPath, cachePath);
-        }
-        catch {
-            // Best-effort caching
-        }
+        return `skills-sh:${hash}`;
     }
 }
 // ── Self-register ───────────────────────────────────────────────────────────
@@ -226,7 +251,3 @@ function isValidSkillsEntry(entry) {
         typeof obj.installs === "number" &&
         typeof obj.source === "string");
 }
-// ── Utilities ───────────────────────────────────────────────────────────────
-function isExpired(mtimeMs, ttlMs) {
-    return Date.now() - mtimeMs > ttlMs;
-}

package/dist/registry/providers/static-index.js

@@ -1,7 +1,9 @@
-import fs from "node:fs";
-import path from "node:path";
+// This Source Code Form is subject to the terms of the Mozilla Public
+// License, v. 2.0. If a copy of the MPL was not distributed with this
+// file, You can obtain one at https://mozilla.org/MPL/2.0/.
 import { fetchWithRetry, jsonWithByteCap, toErrorMessage } from "../../core/common";
-import { getRegistryIndexCacheDir } from "../../core/paths";
+import { rethrowIfTestIsolationError } from "../../core/errors";
+import { closeDatabase, getRegistryIndexCache, openDatabase, upsertRegistryIndexCache } from "../../indexer/db";
 import { asString } from "../../integrations/github";
 import { registerProvider } from "../factory";
 // ── Constants ───────────────────────────────────────────────────────────────
@@ -114,13 +116,30 @@ function assetHitToPreview(hit) {
 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;
+    // ── Step 1: Try DB cache (index.db) ─────────────────────────────────────
+    let db;
+    let dbCacheResult;
+    try {
+        db = openDatabase();
+        dbCacheResult = getRegistryIndexCache(db, entry.url, CACHE_TTL_MS);
+    }
+    catch (err) {
+        // Never mask the bun-test isolation guard as "DB unavailable" — see
+        // rethrowIfTestIsolationError in src/core/errors.ts. Without this, a
+        // leaky test silently gets a cold cache instead of the loud
+        // TEST_ISOLATION_MISSING failure the guard intends.
+        rethrowIfTestIsolationError(err);
+        // index.db not available yet (pre-migration install or test env) — fall through
+    }
+    if (dbCacheResult) {
+        const index = parseRegistryIndex(JSON.parse(dbCacheResult.indexJson));
+        if (index) {
+            if (db)
+                closeDatabase(db);
+            return index;
+        }
     }
-    // Try to fetch fresh index
+    // ── Step 2: Fetch fresh index from remote ────────────────────────────────
     try {
         const response = await fetchWithRetry(entry.url, undefined, { timeout: 10_000 });
         if (!response.ok) {
@@ -131,54 +150,40 @@ async function loadIndex(entry) {
         const data = await jsonWithByteCap(response, 50 * 1024 * 1024);
         const index = parseRegistryIndex(data);
         if (index) {
-            writeCachedIndex(cachePath, index);
+            // Write to DB cache (primary)
+            if (db) {
+                try {
+                    const etag = response.headers.get("etag") ?? undefined;
+                    const lastModified = response.headers.get("last-modified") ?? undefined;
+                    upsertRegistryIndexCache(db, entry.url, JSON.stringify(index), { etag, lastModified });
+                }
+                catch {
+                    /* best-effort */
+                }
+                closeDatabase(db);
+            }
             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;
+        if (db) {
+            try {
+                closeDatabase(db);
+            }
+            catch {
+                /* ignore */
+            }
+        }
+        // Fetch failed — use stale DB cache if available
+        if (dbCacheResult) {
+            const index = parseRegistryIndex(JSON.parse(dbCacheResult.indexJson));
+            if (index)
+                return 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}.${Math.random().toString(36).slice(2)}`;
-        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;
 }

package/dist/registry/providers/types.js

@@ -1,25 +1,4 @@
-/**
- * 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.
- */
+// This Source Code Form is subject to the terms of the Mozilla Public
+// License, v. 2.0. If a copy of the MPL was not distributed with this
+// file, You can obtain one at https://mozilla.org/MPL/2.0/.
 export {};

package/dist/registry/resolve.js

@@ -1,3 +1,6 @@
+// This Source Code Form is subject to the terms of the Mozilla Public
+// License, v. 2.0. If a copy of the MPL was not distributed with this
+// file, You can obtain one at https://mozilla.org/MPL/2.0/.
 import { spawnSync } from "node:child_process";
 import fs from "node:fs";
 import os from "node:os";
@@ -340,6 +343,7 @@ async function resolveNpmArtifact(parsed) {
 }
 async function resolveGithubArtifact(parsed) {
     const gitUrl = `https://github.com/${encodeURIComponent(parsed.owner)}/${encodeURIComponent(parsed.repo)}.git`;
+    const repoBase = `${GITHUB_API_BASE}/repos/${encodeURIComponent(parsed.owner)}/${encodeURIComponent(parsed.repo)}`;
     // Prefer git-backed installs so private GitHub repos work with the user's
     // normal git credential helper rather than requiring API-specific auth.
     const gitResolvedRevision = resolveGitRevisionFromRemote(gitUrl, parsed.requestedRef);
@@ -355,18 +359,18 @@ async function resolveGithubArtifact(parsed) {
     }
     const headers = githubHeaders();
     if (parsed.requestedRef) {
-        const commit = await tryFetchJson(`${GITHUB_API_BASE}/repos/${encodeURIComponent(parsed.owner)}/${encodeURIComponent(parsed.repo)}/commits/${encodeURIComponent(parsed.requestedRef)}`, headers);
+        const commit = await tryFetchJson(`${repoBase}/commits/${encodeURIComponent(parsed.requestedRef)}`, headers);
         const resolvedRevision = asString(commit?.sha) ?? parsed.requestedRef;
         return {
             id: parsed.id,
             source: parsed.source,
             ref: parsed.ref,
-            artifactUrl: `${GITHUB_API_BASE}/repos/${encodeURIComponent(parsed.owner)}/${encodeURIComponent(parsed.repo)}/tarball/${encodeURIComponent(parsed.requestedRef)}`,
+            artifactUrl: `${repoBase}/tarball/${encodeURIComponent(parsed.requestedRef)}`,
             resolvedRevision,
             resolvedVersion: parsed.requestedRef,
         };
     }
-    const latestRelease = await tryFetchJson(`${GITHUB_API_BASE}/repos/${encodeURIComponent(parsed.owner)}/${encodeURIComponent(parsed.repo)}/releases/latest`, headers);
+    const latestRelease = await tryFetchJson(`${repoBase}/releases/latest`, headers);
     if (latestRelease) {
         const tarballUrl = asString(latestRelease.tarball_url);
         if (tarballUrl) {
@@ -380,17 +384,17 @@ async function resolveGithubArtifact(parsed) {
             };
         }
     }
-    const repoMeta = await fetchJson(`${GITHUB_API_BASE}/repos/${encodeURIComponent(parsed.owner)}/${encodeURIComponent(parsed.repo)}`, headers);
+    const repoMeta = await fetchJson(repoBase, headers);
     const defaultBranch = asString(repoMeta.default_branch);
     if (!defaultBranch) {
         throw new Error(`Unable to resolve default branch for ${parsed.owner}/${parsed.repo}.`);
     }
-    const commit = await tryFetchJson(`${GITHUB_API_BASE}/repos/${encodeURIComponent(parsed.owner)}/${encodeURIComponent(parsed.repo)}/commits/${encodeURIComponent(defaultBranch)}`, headers);
+    const commit = await tryFetchJson(`${repoBase}/commits/${encodeURIComponent(defaultBranch)}`, headers);
     return {
         id: parsed.id,
         source: parsed.source,
         ref: parsed.ref,
-        artifactUrl: `${GITHUB_API_BASE}/repos/${encodeURIComponent(parsed.owner)}/${encodeURIComponent(parsed.repo)}/tarball/${encodeURIComponent(defaultBranch)}`,
+        artifactUrl: `${repoBase}/tarball/${encodeURIComponent(defaultBranch)}`,
         resolvedVersion: defaultBranch,
         resolvedRevision: asString(commit?.sha) ?? defaultBranch,
     };
@@ -407,16 +411,7 @@ function resolveGitRevisionFromRemote(url, requestedRef) {
     return firstLine?.split(/\s/)[0] || undefined;
 }
 async function resolveGitArtifact(parsed) {
-    validateGitUrl(parsed.url);
-    const ref = parsed.requestedRef ?? "HEAD";
-    if (parsed.requestedRef)
-        validateGitRef(parsed.requestedRef);
-    const result = spawnSync("git", ["ls-remote", parsed.url, ref], { encoding: "utf8", timeout: 30_000 });
-    let resolvedRevision;
-    if (result.status === 0) {
-        const firstLine = result.stdout.trim().split(/\r?\n/)[0];
-        resolvedRevision = firstLine?.split(/\s/)[0] || undefined;
-    }
+    const resolvedRevision = resolveGitRevisionFromRemote(parsed.url, parsed.requestedRef);
     return {
         id: parsed.id,
         source: parsed.source,

package/dist/registry/types.js

@@ -1 +1,4 @@
+// This Source Code Form is subject to the terms of the Mozilla Public
+// License, v. 2.0. If a copy of the MPL was not distributed with this
+// file, You can obtain one at https://mozilla.org/MPL/2.0/.
 export {};