akm-cli 0.5.0 → 0.6.0-rc1

package/dist/stash-add.js

@@ -4,9 +4,11 @@ import { isHttpUrl, resolveStashDir } from "./common";
 import { loadConfig, loadUserConfig, saveConfig } from "./config";
 import { UsageError } from "./errors";
 import { akmIndex } from "./indexer";
+import { auditInstallCandidate, deriveRegistryLabels, enforceRegistryInstallPolicy, formatInstallAuditFailure, } from "./install-audit";
 import { upsertLockEntry } from "./lockfile";
-import { detectStashRoot, installRegistryRef, upsertInstalledRegistryEntry } from "./registry-install";
 import { parseRegistryRef } from "./registry-resolve";
+import { detectStashRoot } from "./stash-providers/provider-utils";
+import { syncFromRef } from "./stash-providers/sync-from-ref";
 import { ensureWebsiteMirror, validateWebsiteInputUrl } from "./stash-providers/website";
 import { warn } from "./warn";
 import { ensureWikiNameAvailable, validateWikiName } from "./wiki";
@@ -15,7 +17,7 @@ export async function akmAdd(input) {
     const ref = input.ref.trim();
     if (!ref)
         throw new UsageError("Install ref or local directory is required. " +
-            "Examples: `akm add @scope/kit`, `akm add github:owner/repo`, `akm add ./local/path`");
+            "Examples: `akm add @scope/stash`, `akm add github:owner/repo`, `akm add ./local/path`");
     // Validate and resolve wiki name when --type wiki is used
     let wikiName;
     if (input.overrideType) {
@@ -45,7 +47,7 @@ export async function akmAdd(input) {
     catch {
         // Not a local ref — fall through to registry install
     }
-    return addRegistryKit(ref, stashDir, input.trustThisInstall, input.writable, wikiName);
+    return addRegistryStash(ref, stashDir, input.trustThisInstall, input.writable, wikiName);
 }
 export async function registerWikiSource(input) {
     const stashDir = resolveStashDir();
@@ -173,34 +175,59 @@ async function addWebsiteStashSource(ref, stashDir, name, options, wikiName) {
     };
 }
 /**
- * Install a kit from a registry (npm, github, git).
+ * Install a stash from a registry (npm, github, git) by dispatching to the
+ * matching syncable provider, then running the post-sync install audit and
+ * persisting the lock entry.
  */
-async function addRegistryKit(ref, stashDir, trustThisInstall, writable, wikiName) {
-    const installed = await installRegistryRef(ref, { trustThisInstall, writable });
-    const replaced = (loadConfig().installed ?? []).find((entry) => entry.id === installed.id);
-    const config = upsertInstalledRegistryEntry({
-        id: installed.id,
-        source: installed.source,
-        ref: installed.ref,
-        artifactUrl: installed.artifactUrl,
-        resolvedVersion: installed.resolvedVersion,
-        resolvedRevision: installed.resolvedRevision,
-        stashRoot: installed.stashRoot,
-        cacheDir: installed.cacheDir,
-        installedAt: installed.installedAt,
-        writable: installed.writable,
+async function addRegistryStash(ref, stashDir, trustThisInstall, writable, wikiName) {
+    // Pre-sync registry-policy enforcement uses just the parsed ref (no fetch needed),
+    // so we keep parity with the historical behavior where `enforceRegistryInstallPolicy`
+    // ran before `extractTarGzSecure` etc.
+    const config = loadConfig();
+    const synced = await syncFromRef(ref, { trustThisInstall, writable });
+    const registryLabels = deriveRegistryLabels({
+        source: synced.source,
+        ref: synced.ref,
+        artifactUrl: synced.artifactUrl,
+    });
+    enforceRegistryInstallPolicy(registryLabels, config, ref);
+    // Post-sync hook: install audit. Throws when blocked unless `--trust` is set
+    // (in which case the audit report still surfaces in the response).
+    const audit = auditInstallCandidate({
+        rootDir: synced.extractedDir,
+        source: synced.source,
+        ref: synced.ref,
+        registryLabels,
+        config,
+        trustThisInstall,
+    });
+    if (audit.blocked) {
+        throw new Error(formatInstallAuditFailure(synced.ref, audit));
+    }
+    const replaced = (loadConfig().installed ?? []).find((entry) => entry.id === synced.id);
+    const updatedConfig = upsertInstalledRegistryEntry({
+        id: synced.id,
+        source: synced.source,
+        ref: synced.ref,
+        artifactUrl: synced.artifactUrl,
+        resolvedVersion: synced.resolvedVersion,
+        resolvedRevision: synced.resolvedRevision,
+        stashRoot: synced.contentDir,
+        cacheDir: synced.cacheDir,
+        installedAt: synced.syncedAt,
+        writable: synced.writable,
         ...(wikiName ? { wikiName } : {}),
     });
     await upsertLockEntry({
-        id: installed.id,
-        source: installed.source,
-        ref: installed.ref,
-        resolvedVersion: installed.resolvedVersion,
-        resolvedRevision: installed.resolvedRevision,
-        integrity: installed.integrity,
+        id: synced.id,
+        source: synced.source,
+        ref: synced.ref,
+        resolvedVersion: synced.resolvedVersion,
+        resolvedRevision: synced.resolvedRevision,
+        integrity: synced.integrity,
     });
     // Clean up old cache directory on re-install
-    if (replaced && replaced.cacheDir !== installed.cacheDir) {
+    if (replaced && replaced.cacheDir !== synced.cacheDir) {
         try {
             fs.rmSync(replaced.cacheDir, { recursive: true, force: true });
         }
@@ -214,21 +241,21 @@ async function addRegistryKit(ref, stashDir, trustThisInstall, writable, wikiNam
         stashDir,
         ref,
         installed: {
-            id: installed.id,
-            source: installed.source,
-            ref: installed.ref,
-            artifactUrl: installed.artifactUrl,
-            resolvedVersion: installed.resolvedVersion,
-            resolvedRevision: installed.resolvedRevision,
-            stashRoot: installed.stashRoot,
-            cacheDir: installed.cacheDir,
-            extractedDir: installed.extractedDir,
-            installedAt: installed.installedAt,
-            audit: installed.audit,
+            id: synced.id,
+            source: synced.source,
+            ref: synced.ref,
+            artifactUrl: synced.artifactUrl,
+            resolvedVersion: synced.resolvedVersion,
+            resolvedRevision: synced.resolvedRevision,
+            stashRoot: synced.contentDir,
+            cacheDir: synced.cacheDir,
+            extractedDir: synced.extractedDir,
+            installedAt: synced.syncedAt,
+            audit,
         },
         config: {
-            stashCount: config.stashes?.length ?? 0,
-            installedKitCount: config.installed?.length ?? 0,
+            stashCount: updatedConfig.stashes?.length ?? 0,
+            installedKitCount: updatedConfig.installed?.length ?? 0,
         },
         index: {
             mode: index.mode,
@@ -239,6 +266,35 @@ async function addRegistryKit(ref, stashDir, trustThisInstall, writable, wikiNam
         },
     };
 }
+/** Persist or replace an installed stash entry in the user config. */
+export function upsertInstalledRegistryEntry(entry) {
+    const current = loadUserConfig();
+    const currentInstalled = current.installed ?? [];
+    const withoutExisting = currentInstalled.filter((item) => item.id !== entry.id);
+    const nextInstalled = [...withoutExisting, normalizeInstalledEntry(entry)];
+    const nextConfig = { ...current, installed: nextInstalled };
+    saveConfig(nextConfig);
+    return nextConfig;
+}
+/** Remove an installed stash entry from the user config. */
+export function removeInstalledRegistryEntry(id) {
+    const current = loadUserConfig();
+    const currentInstalled = current.installed ?? [];
+    const nextInstalled = currentInstalled.filter((item) => item.id !== id);
+    const nextConfig = {
+        ...current,
+        installed: nextInstalled.length > 0 ? nextInstalled : undefined,
+    };
+    saveConfig(nextConfig);
+    return nextConfig;
+}
+function normalizeInstalledEntry(entry) {
+    return {
+        ...entry,
+        stashRoot: path.resolve(entry.stashRoot),
+        cacheDir: path.resolve(entry.cacheDir),
+    };
+}
 function toReadableId(resolvedPath) {
     const home = process.env.HOME ?? process.env.USERPROFILE ?? "";
     if (home && resolvedPath.startsWith(home + path.sep)) {

package/dist/stash-clone.js

@@ -3,8 +3,8 @@ import path from "node:path";
 import { TYPE_DIRS } from "./asset-spec";
 import { UsageError } from "./errors";
 import { isRemoteOrigin, resolveSourcesForOrigin } from "./origin-resolve";
-import { installRegistryRef } from "./registry-install";
 import { findSourceForPath, getPrimarySource, resolveStashSources } from "./search-source";
+import { syncFromRef } from "./stash-providers/sync-from-ref";
 import { makeAssetRef, parseAssetRef } from "./stash-ref";
 import { resolveAssetPath } from "./stash-resolve";
 export async function akmClone(options) {
@@ -31,16 +31,16 @@ export async function akmClone(options) {
     // Remote fetch fallback: if no local source matched and origin looks remote, fetch it
     let remoteFetched;
     if (searchSources.length === 0 && parsed.origin && isRemoteOrigin(parsed.origin, allSources)) {
-        const installResult = await installRegistryRef(parsed.origin);
+        const installResult = await syncFromRef(parsed.origin);
         const syntheticSource = {
-            path: installResult.stashRoot,
+            path: installResult.contentDir,
             registryId: installResult.id,
         };
         searchSources = [syntheticSource];
         allSources = [...allSources, syntheticSource];
         remoteFetched = {
             origin: parsed.origin,
-            stashRoot: installResult.stashRoot,
+            stashRoot: installResult.contentDir,
             cacheDir: installResult.cacheDir,
         };
     }

package/dist/stash-provider-factory.js

@@ -5,8 +5,8 @@
  * factory functions that create StashProvider instances from a StashConfigEntry.
  *
  * "Stash providers" are runtime data sources for the search and show commands —
- * distinct from the kit-discovery registries (registry-factory.ts) and the
- * installed-kit operations (installed-kits.ts).
+ * distinct from the stash-discovery registries (registry-factory.ts) and the
+ * installed-stash operations (installed-stashes.ts).
  */
 import { createProviderRegistry } from "./create-provider-registry";
 // ── Factory map ─────────────────────────────────────────────────────────────

package/dist/stash-provider.js

@@ -1 +1,3 @@
-export {};
+export function isSyncable(p) {
+    return p.kind === "syncable";
+}

package/dist/stash-providers/filesystem.js

@@ -1,11 +1,14 @@
 import { resolveStashDir } from "../common";
 import { loadConfig } from "../config";
-import { searchLocal } from "../local-search";
+import { searchLocal } from "../db-search";
+import { ConfigError } from "../errors";
 import { resolveStashSources } from "../search-source";
 import { registerStashProvider } from "../stash-provider-factory";
 import { showLocal } from "../stash-show";
+import { detectStashRoot } from "./provider-utils";
 class FilesystemStashProvider {
     type = "filesystem";
+    kind = "syncable";
     name;
     stashDir;
     constructor(entry) {
@@ -36,6 +39,33 @@ class FilesystemStashProvider {
     canShow(ref) {
         return !ref.includes("://");
     }
+    /** No-op: a filesystem stash already lives on disk. */
+    async sync(config, options) {
+        if (!config.path) {
+            throw new ConfigError("filesystem stash entry must include a `path`");
+        }
+        const stashRoot = detectStashRoot(config.path);
+        const syncedAt = (options?.now ?? new Date()).toISOString();
+        return {
+            id: stashRoot,
+            source: "local",
+            ref: stashRoot,
+            artifactUrl: stashRoot,
+            contentDir: stashRoot,
+            cacheDir: stashRoot,
+            extractedDir: stashRoot,
+            syncedAt,
+        };
+    }
+    getContentDir(config) {
+        if (!config.path) {
+            throw new ConfigError("filesystem stash entry must include a `path`");
+        }
+        return config.path;
+    }
+    async remove(_config) {
+        // Filesystem stashes are user-managed; never delete the source on `akm remove`.
+    }
 }
 // ── Self-register ───────────────────────────────────────────────────────────
 registerStashProvider("filesystem", (config) => new FilesystemStashProvider(config));

package/dist/stash-providers/git.js

@@ -5,19 +5,27 @@ import path from "node:path";
 import { resolveStashDir } from "../common";
 import { loadConfig } from "../config";
 import { ConfigError, UsageError } from "../errors";
-import { getRegistryIndexCacheDir } from "../paths";
-import { validateGitUrl } from "../registry-resolve";
+import { getRegistryCacheDir, getRegistryIndexCacheDir } from "../paths";
+import { parseRegistryRef, resolveRegistryArtifact, validateGitRef, validateGitUrl } from "../registry-resolve";
 import { registerStashProvider } from "../stash-provider-factory";
-import { isExpired, sanitizeString } from "./provider-utils";
+import { applyAkmIncludeConfig, buildInstallCacheDir, copyDirectoryContents, detectStashRoot, isDirectory, isExpired, sanitizeString, } from "./provider-utils";
 /** Cache TTL before refreshing the mirrored repo (12 hours). */
 const CACHE_TTL_MS = 12 * 60 * 60 * 1000;
 /** Maximum stale age allowed when refresh fails (7 days). */
 const CACHE_STALE_MS = 7 * 24 * 60 * 60 * 1000;
-const GIT_STASH_TYPES = new Set(["git", "context-hub", "github"]);
+const GIT_STASH_TYPES = new Set(["git"]);
+/**
+ * Git stash provider. Implements {@link SyncableStashProvider} (which extends
+ * the LiveStashProvider surface) — the indexer walks the cloned repo, and
+ * `sync()` clones/pulls into a local mirror.
+ */
 class GitStashProvider {
     type = "git";
+    kind = "syncable";
     name;
+    config;
     constructor(config) {
+        this.config = config;
         this.name = config.name ?? "git";
     }
     /** Content is indexed through the standard FTS5 pipeline. */
@@ -32,15 +40,68 @@ class GitStashProvider {
     canShow(_ref) {
         return false;
     }
+    async sync(config, options) {
+        // Two execution modes:
+        //   1. Long-lived configured stash (config.url) — mirror into the
+        //      registry-index cache and serve as a read-only working tree.
+        //   2. One-shot install ref (config.options.ref like "git:..." / "github:...") —
+        //      run the historical clone-into-cache flow used by `akm add`.
+        if (typeof config.options?.ref === "string" && config.options.ref) {
+            return syncRegistryGitRef(String(config.options.ref), options);
+        }
+        return syncMirroredRepo(config, options);
+    }
+    getContentDir(config) {
+        if (config.path)
+            return config.path;
+        if (config.url) {
+            const repo = parseGitRepoUrl(config.url);
+            return getCachePaths(repo.canonicalUrl).repoDir;
+        }
+        throw new ConfigError("git stash entry must have either `path` or `url`");
+    }
+    async remove(config) {
+        if (config.path && isDirectory(config.path)) {
+            try {
+                fs.rmSync(path.dirname(config.path), { recursive: true, force: true });
+            }
+            catch {
+                /* best-effort */
+            }
+        }
+        else if (config.url) {
+            const repo = parseGitRepoUrl(config.url);
+            const paths = getCachePaths(repo.canonicalUrl);
+            try {
+                fs.rmSync(paths.rootDir, { recursive: true, force: true });
+            }
+            catch {
+                /* best-effort */
+            }
+        }
+    }
 }
 // ── Self-register ───────────────────────────────────────────────────────────
 registerStashProvider("git", (config) => new GitStashProvider(config));
-registerStashProvider("context-hub", (config) => new GitStashProvider(config));
-registerStashProvider("github", (config) => new GitStashProvider(config));
 // ── Cache management ────────────────────────────────────────────────────────
 function getCachePaths(repoUrl) {
     const key = createHash("sha256").update(repoUrl).digest("hex").slice(0, 16);
-    const rootDir = path.join(getRegistryIndexCacheDir(), `context-hub-${key}`);
+    const cacheRoot = getRegistryIndexCacheDir();
+    const rootDir = path.join(cacheRoot, `git-${key}`);
+    // One-time silent migration: legacy `context-hub-${key}` directories were
+    // created for ALL git stashes (not just the andrewyng/context-hub repo). If
+    // the new path doesn't yet exist but the legacy one does, rename it in place
+    // so existing clones aren't silently invalidated. Failures are non-fatal —
+    // worst case the repo is re-cloned on the next refresh.
+    try {
+        const legacyRootDir = path.join(cacheRoot, `context-hub-${key}`);
+        if (!fs.existsSync(rootDir) && fs.existsSync(legacyRootDir)) {
+            fs.renameSync(legacyRootDir, rootDir);
+        }
+    }
+    catch {
+        /* migration is best-effort */
+    }
     return {
         rootDir,
         repoDir: path.join(rootDir, "repo"),
@@ -50,6 +111,7 @@ function getCachePaths(repoUrl) {
 async function ensureGitMirror(repo, cachePaths, options) {
     const requireRepoDir = options?.requireRepoDir === true;
     const writable = options?.writable === true;
+    const force = options?.force === true;
     // Check if cache is fresh
     let mtime = 0;
     try {
@@ -58,7 +120,7 @@ async function ensureGitMirror(repo, cachePaths, options) {
     catch {
         /* no cached index */
     }
-    if (mtime && !isExpired(mtime, CACHE_TTL_MS) && (!requireRepoDir || hasExtractedRepo(cachePaths.repoDir))) {
+    if (!force && mtime && !isExpired(mtime, CACHE_TTL_MS) && (!requireRepoDir || hasExtractedRepo(cachePaths.repoDir))) {
         return;
     }
     try {
@@ -80,6 +142,145 @@ async function ensureGitMirror(repo, cachePaths, options) {
         throw err;
     }
 }
+/**
+ * Sync mode for a long-lived configured git stash. Mirrors the repo into the
+ * shared registry-index cache (12h TTL) and exposes the working tree as the
+ * stash content directory.
+ */
+async function syncMirroredRepo(config, options) {
+    if (!config.url) {
+        throw new ConfigError("git stash entry requires a URL when no install ref is supplied");
+    }
+    const repo = parseGitRepoUrl(config.url);
+    const cachePaths = getCachePaths(repo.canonicalUrl);
+    await ensureGitMirror(repo, cachePaths, {
+        requireRepoDir: true,
+        writable: options?.writable ?? config.writable === true,
+        force: options?.force,
+    });
+    const syncedAt = (options?.now ?? new Date()).toISOString();
+    const contentDir = cachePaths.repoDir;
+    return {
+        id: repo.canonicalUrl,
+        source: "git",
+        ref: repo.canonicalUrl,
+        artifactUrl: repo.canonicalUrl,
+        contentDir,
+        cacheDir: cachePaths.rootDir,
+        extractedDir: contentDir,
+        writable: options?.writable ?? config.writable === true,
+        syncedAt,
+    };
+}
+/**
+ * Sync mode for a one-shot install ref (`akm add github:owner/repo` or
+ * `akm add git:url`). Runs the clone → strip → include-filter pipeline that
+ * historically lived in `installRegistryRef()`.
+ */
+export async function syncRegistryGitRef(ref, options) {
+    const parsed = parseRegistryRef(ref);
+    if (parsed.source === "github") {
+        const githubRef = {
+            source: "git",
+            ref: parsed.ref,
+            id: parsed.id,
+            url: `https://github.com/${parsed.owner}/${parsed.repo}.git`,
+            requestedRef: parsed.requestedRef,
+        };
+        const result = await doSyncGit(githubRef, options);
+        return { ...result, source: "github" };
+    }
+    if (parsed.source !== "git") {
+        throw new UsageError(`syncRegistryGitRef requires a git: or github: ref, got "${ref}"`);
+    }
+    return doSyncGit(parsed, options);
+}
+async function doSyncGit(parsed, options) {
+    const resolved = await resolveRegistryArtifact(parsed);
+    const syncedAt = (options?.now ?? new Date()).toISOString();
+    const cacheRootDir = options?.cacheRootDir ?? getRegistryCacheDir();
+    const cacheDir = buildInstallCacheDir(cacheRootDir, parsed.source, parsed.id, resolved.resolvedRevision);
+    const cloneDir = path.join(cacheDir, "clone");
+    const extractedDir = path.join(cacheDir, "extracted");
+    // Cache hit
+    if (!options?.force && isDirectory(extractedDir)) {
+        try {
+            const provisionalKitRoot = detectStashRoot(extractedDir);
+            const installRoot = applyAkmIncludeConfig(provisionalKitRoot, cacheDir, extractedDir) ?? provisionalKitRoot;
+            const stashRoot = detectStashRoot(installRoot);
+            if (stashRoot) {
+                return {
+                    id: resolved.id,
+                    source: resolved.source,
+                    ref: resolved.ref,
+                    artifactUrl: resolved.artifactUrl,
+                    resolvedVersion: resolved.resolvedVersion,
+                    resolvedRevision: resolved.resolvedRevision,
+                    contentDir: stashRoot,
+                    cacheDir,
+                    extractedDir,
+                    writable: options?.writable,
+                    syncedAt,
+                };
+            }
+        }
+        catch {
+            // Cache invalid, re-clone
+        }
+    }
+    fs.mkdirSync(cacheDir, { recursive: true });
+    // Validate URL and ref before passing to git to prevent command injection
+    validateGitUrl(parsed.url);
+    if (parsed.requestedRef)
+        validateGitRef(parsed.requestedRef);
+    let provisionalKitRoot;
+    let installRoot;
+    let stashRoot;
+    try {
+        const cloneArgs = ["clone", "--depth", "1"];
+        if (parsed.requestedRef) {
+            cloneArgs.push("--branch", parsed.requestedRef);
+        }
+        cloneArgs.push(parsed.url, cloneDir);
+        const cloneResult = spawnSync("git", cloneArgs, { encoding: "utf8", timeout: 120_000 });
+        if (cloneResult.status !== 0) {
+            const err = cloneResult.stderr?.trim() || cloneResult.error?.message || "unknown error";
+            throw new Error(`Failed to clone ${parsed.url}: ${err}`);
+        }
+        // Copy contents to extracted dir without .git
+        fs.mkdirSync(extractedDir, { recursive: true });
+        copyDirectoryContents(cloneDir, extractedDir);
+        // Clean up the clone dir
+        fs.rmSync(cloneDir, { recursive: true, force: true });
+        provisionalKitRoot = detectStashRoot(extractedDir);
+        installRoot = applyAkmIncludeConfig(provisionalKitRoot, cacheDir, extractedDir) ?? provisionalKitRoot;
+        stashRoot = detectStashRoot(installRoot);
+    }
+    catch (err) {
+        // Clean up the cache directory so stale or partially-cloned artifacts
+        // don't cause false cache hits on the next install attempt.
+        try {
+            fs.rmSync(cacheDir, { recursive: true, force: true });
+        }
+        catch {
+            /* best-effort */
+        }
+        throw err;
+    }
+    return {
+        id: resolved.id,
+        source: resolved.source,
+        ref: resolved.ref,
+        artifactUrl: resolved.artifactUrl,
+        resolvedVersion: resolved.resolvedVersion,
+        resolvedRevision: resolved.resolvedRevision,
+        contentDir: stashRoot,
+        cacheDir,
+        extractedDir,
+        writable: options?.writable,
+        syncedAt,
+    };
+}
 export function cloneRepo(cloneUrl, ref, destDir, writable = false) {
     // Stage the clone into a sibling temp dir so that a failed clone never
     // destroys a previously-valid destDir (e.g. when the remote is temporarily

package/dist/stash-providers/index.js

@@ -7,5 +7,6 @@
  */
 import "./filesystem";
 import "./git";
+import "./npm";
 import "./openviking";
 import "./website";