akm-cli 0.3.0 → 0.4.0

package/dist/matchers.js

@@ -7,7 +7,7 @@
  *
  * - `extensionMatcher` (3) -- classifies any file by extension alone.
  *   Ensures every known file type is discoverable regardless of directory.
- * - `directoryMatcher` (10) -- boosts specificity when the first ancestor
+ * - `directoryMatcher` (10) -- boosts specificity when an ancestor
  *   directory matches a known type name (e.g. `scripts/`, `agents/`).
  * - `parentDirHintMatcher` (15) -- boosts specificity based on the
  *   immediate parent directory name.
@@ -43,31 +43,34 @@ export function extensionMatcher(ctx) {
 }
 // ── directoryMatcher (specificity: 10) ──────────────────────────────────────
 /**
- * Directory-based matcher that boosts specificity when the first ancestor
+ * Directory-based matcher that boosts specificity when an ancestor
  * directory segment from the stash root matches a known type name.
+ *
+ * The first matching type-like ancestor wins. This preserves intuitive
+ * behavior for nested kit layouts such as `agent-stash/agents/blog/foo.md`
+ * while still honoring earlier type roots like `commands/agents/foo.md`.
  */
 export function directoryMatcher(ctx) {
-    const topDir = ctx.ancestorDirs[0];
-    if (!topDir)
-        return null;
     const ext = ctx.ext;
-    if (topDir === "scripts" && SCRIPT_EXTENSIONS.has(ext)) {
-        return { type: "script", specificity: 10, renderer: "script-source" };
-    }
-    if (topDir === "skills" && ctx.fileName === "SKILL.md") {
-        return { type: "skill", specificity: 10, renderer: "skill-md" };
-    }
-    if (topDir === "commands" && ext === ".md") {
-        return { type: "command", specificity: 10, renderer: "command-md" };
-    }
-    if (topDir === "agents" && ext === ".md") {
-        return { type: "agent", specificity: 10, renderer: "agent-md" };
-    }
-    if (topDir === "knowledge" && ext === ".md") {
-        return { type: "knowledge", specificity: 10, renderer: "knowledge-md" };
-    }
-    if (topDir === "memories" && ext === ".md") {
-        return { type: "memory", specificity: 10, renderer: "memory-md" };
+    for (const dir of ctx.ancestorDirs) {
+        if (dir === "scripts" && SCRIPT_EXTENSIONS.has(ext)) {
+            return { type: "script", specificity: 10, renderer: "script-source" };
+        }
+        if (dir === "skills" && ctx.fileName === "SKILL.md") {
+            return { type: "skill", specificity: 10, renderer: "skill-md" };
+        }
+        if (dir === "commands" && ext === ".md") {
+            return { type: "command", specificity: 10, renderer: "command-md" };
+        }
+        if (dir === "agents" && ext === ".md") {
+            return { type: "agent", specificity: 10, renderer: "agent-md" };
+        }
+        if (dir === "knowledge" && ext === ".md") {
+            return { type: "knowledge", specificity: 10, renderer: "knowledge-md" };
+        }
+        if (dir === "memories" && ext === ".md") {
+            return { type: "memory", specificity: 10, renderer: "memory-md" };
+        }
     }
     return null;
 }

package/dist/registry-install.js

@@ -4,7 +4,8 @@ import fs from "node:fs";
 import path from "node:path";
 import { TYPE_DIRS } from "./asset-spec";
 import { fetchWithRetry, isWithin } from "./common";
-import { loadConfig, saveConfig } from "./config";
+import { loadConfig, loadUserConfig, saveConfig } from "./config";
+import { auditInstallCandidate, deriveRegistryLabels, enforceRegistryInstallPolicy, formatInstallAuditFailure, } from "./install-audit";
 import { copyIncludedPaths, findNearestIncludeConfig } from "./kit-include";
 import { getRegistryCacheDir as _getRegistryCacheDir } from "./paths";
 import { parseRegistryRef, resolveRegistryArtifact, validateGitRef, validateGitUrl } from "./registry-resolve";
@@ -12,13 +13,20 @@ import { warn } from "./warn";
 const REGISTRY_STASH_DIR_NAMES = new Set(Object.values(TYPE_DIRS));
 export async function installRegistryRef(ref, options) {
     const parsed = parseRegistryRef(ref);
+    const config = loadConfig();
     if (parsed.source === "local") {
-        return installLocalRegistryRef(parsed, options);
+        return installLocalRegistryRef(parsed, config, options);
     }
     if (parsed.source === "git") {
-        return installGitRegistryRef(parsed, options);
+        return installGitRegistryRef(parsed, config, options);
     }
     const resolved = await resolveRegistryArtifact(parsed);
+    const registryLabels = deriveRegistryLabels({
+        source: resolved.source,
+        ref: resolved.ref,
+        artifactUrl: resolved.artifactUrl,
+    });
+    enforceRegistryInstallPolicy(registryLabels, config, ref);
     const installedAt = (options?.now ?? new Date()).toISOString();
     const cacheRootDir = options?.cacheRootDir ?? getRegistryCacheRootDir();
     const cacheDir = buildInstallCacheDir(cacheRootDir, resolved.source, resolved.id, resolved.resolvedVersion ?? resolved.resolvedRevision);
@@ -30,6 +38,7 @@ export async function installRegistryRef(ref, options) {
             const cachedStashRoot = detectStashRoot(extractedDir);
             if (cachedStashRoot) {
                 const integrity = fs.existsSync(archivePath) ? await computeFileHash(archivePath) : undefined;
+                const audit = runInstallAuditOrThrow(extractedDir, resolved.source, resolved.ref, registryLabels, config);
                 return {
                     id: resolved.id,
                     source: resolved.source,
@@ -42,6 +51,7 @@ export async function installRegistryRef(ref, options) {
                     extractedDir,
                     stashRoot: cachedStashRoot,
                     integrity,
+                    audit,
                 };
             }
         }
@@ -54,11 +64,13 @@ export async function installRegistryRef(ref, options) {
     let provisionalKitRoot;
     let installRoot;
     let stashRoot;
+    let audit;
     try {
         await downloadArchive(resolved.artifactUrl, archivePath);
         verifyArchiveIntegrity(archivePath, resolved.resolvedRevision, resolved.source);
         integrity = await computeFileHash(archivePath);
         extractTarGzSecure(archivePath, extractedDir);
+        audit = runInstallAuditOrThrow(extractedDir, resolved.source, resolved.ref, registryLabels, config);
         provisionalKitRoot = detectStashRoot(extractedDir);
         installRoot = applyAkmIncludeConfig(provisionalKitRoot, cacheDir, extractedDir) ?? provisionalKitRoot;
         stashRoot = detectStashRoot(installRoot);
@@ -86,11 +98,18 @@ export async function installRegistryRef(ref, options) {
         extractedDir,
         stashRoot,
         integrity,
+        audit,
     };
 }
-async function installLocalRegistryRef(parsed, options) {
+async function installLocalRegistryRef(parsed, config, options) {
     const resolved = await resolveRegistryArtifact(parsed);
     const installedAt = (options?.now ?? new Date()).toISOString();
+    const registryLabels = deriveRegistryLabels({
+        source: resolved.source,
+        ref: resolved.ref,
+        artifactUrl: resolved.artifactUrl,
+    });
+    const audit = runInstallAuditOrThrow(parsed.sourcePath, resolved.source, resolved.ref, registryLabels, config);
     // For local directories, detect the stash root within the source path.
     // If no nested stash is found, the source path itself is used.
     const stashRoot = detectStashRoot(parsed.sourcePath);
@@ -105,10 +124,18 @@ async function installLocalRegistryRef(parsed, options) {
         cacheDir: parsed.sourcePath,
         extractedDir: parsed.sourcePath,
         stashRoot,
+        audit,
     };
 }
-async function installGitRegistryRef(parsed, options) {
+async function installGitRegistryRef(parsed, config, options) {
     const resolved = await resolveRegistryArtifact(parsed);
+    const registryLabels = deriveRegistryLabels({
+        source: resolved.source,
+        ref: resolved.ref,
+        artifactUrl: resolved.artifactUrl,
+        gitUrl: parsed.url,
+    });
+    enforceRegistryInstallPolicy(registryLabels, config, parsed.ref);
     const installedAt = (options?.now ?? new Date()).toISOString();
     const cacheRootDir = options?.cacheRootDir ?? getRegistryCacheRootDir();
     const cacheDir = buildInstallCacheDir(cacheRootDir, parsed.source, parsed.id, resolved.resolvedRevision);
@@ -121,6 +148,7 @@ async function installGitRegistryRef(parsed, options) {
             const installRoot = applyAkmIncludeConfig(provisionalKitRoot, cacheDir, extractedDir) ?? provisionalKitRoot;
             const stashRoot = detectStashRoot(installRoot);
             if (stashRoot) {
+                const audit = runInstallAuditOrThrow(extractedDir, resolved.source, resolved.ref, registryLabels, config);
                 return {
                     id: resolved.id,
                     source: resolved.source,
@@ -132,6 +160,7 @@ async function installGitRegistryRef(parsed, options) {
                     cacheDir,
                     extractedDir,
                     stashRoot,
+                    audit,
                 };
             }
         }
@@ -147,6 +176,7 @@ async function installGitRegistryRef(parsed, options) {
     let provisionalKitRoot;
     let installRoot;
     let stashRoot;
+    let audit;
     try {
         const cloneArgs = ["clone", "--depth", "1"];
         if (parsed.requestedRef) {
@@ -163,6 +193,7 @@ async function installGitRegistryRef(parsed, options) {
         copyDirectoryContents(cloneDir, extractedDir);
         // Clean up the clone dir
         fs.rmSync(cloneDir, { recursive: true, force: true });
+        audit = runInstallAuditOrThrow(extractedDir, resolved.source, resolved.ref, registryLabels, config);
         provisionalKitRoot = detectStashRoot(extractedDir);
         installRoot = applyAkmIncludeConfig(provisionalKitRoot, cacheDir, extractedDir) ?? provisionalKitRoot;
         stashRoot = detectStashRoot(installRoot);
@@ -189,10 +220,11 @@ async function installGitRegistryRef(parsed, options) {
         cacheDir,
         extractedDir,
         stashRoot,
+        audit,
     };
 }
 export function upsertInstalledRegistryEntry(entry) {
-    const current = loadConfig();
+    const current = loadUserConfig();
     const currentInstalled = current.installed ?? [];
     const withoutExisting = currentInstalled.filter((item) => item.id !== entry.id);
     const nextInstalled = [...withoutExisting, normalizeInstalledEntry(entry)];
@@ -204,7 +236,7 @@ export function upsertInstalledRegistryEntry(entry) {
     return nextConfig;
 }
 export function removeInstalledRegistryEntry(id) {
-    const current = loadConfig();
+    const current = loadUserConfig();
     const currentInstalled = current.installed ?? [];
     const nextInstalled = currentInstalled.filter((item) => item.id !== id);
     const nextConfig = {
@@ -462,3 +494,10 @@ async function computeFileHash(filePath) {
     const hash = createHash("sha256").update(data).digest("hex");
     return `sha256:${hash}`;
 }
+function runInstallAuditOrThrow(rootDir, source, ref, registryLabels, config) {
+    const audit = auditInstallCandidate({ rootDir, source, ref, registryLabels, config });
+    if (audit.blocked) {
+        throw new Error(formatInstallAuditFailure(ref, audit));
+    }
+    return audit;
+}

package/dist/search-source.js

@@ -3,6 +3,7 @@ import path from "node:path";
 import { resolveStashDir } from "./common";
 import { loadConfig } from "./config";
 import { ensureGitMirror, getCachePaths, parseGitRepoUrl } from "./stash-providers/git";
+import { ensureWebsiteMirror, getCachePaths as getWebsiteCachePaths } from "./stash-providers/website";
 import { warn } from "./warn";
 // ── Resolution ──────────────────────────────────────────────────────────────
 /**
@@ -54,6 +55,19 @@ export function resolveStashSources(overrideStashDir, existingConfig) {
             }
         }
     }
+    // Website stash entries: resolve cache directory so the indexer can walk
+    // the scraped markdown snapshots.
+    for (const entry of config.stashes ?? []) {
+        if (entry.type === "website" && entry.url && entry.enabled !== false) {
+            try {
+                const cachePaths = getWebsiteCachePaths(entry.url);
+                addSource(cachePaths.stashDir, entry.name ?? entry.url);
+            }
+            catch (err) {
+                warn(`Warning: failed to resolve website stash cache for "${entry.url}": ${err instanceof Error ? err.message : String(err)}`);
+            }
+        }
+    }
     // Installed kits (registry and local)
     for (const entry of config.installed ?? []) {
         addSource(entry.stashRoot, entry.id);
@@ -153,11 +167,12 @@ function isValidDirectory(dir) {
 // ── Git stash cache integration ──────────────────────────────────────────────
 const GIT_STASH_TYPES = new Set(["context-hub", "github", "git"]);
 /**
- * Ensure all git stash mirrors are refreshed so their cache directories
- * exist on disk. Must be called (async) before `resolveStashSources()` so
- * the content directories pass the `isValidDirectory()` check.
+ * Ensure all cache-backed stash providers are refreshed so their cache
+ * directories exist on disk. Must be called (async) before
+ * `resolveStashSources()` so the content directories pass the
+ * `isValidDirectory()` check.
  */
-export async function ensureGitCaches(config) {
+export async function ensureStashCaches(config) {
     const cfg = config ?? loadConfig();
     for (const entry of cfg.stashes ?? []) {
         if (!GIT_STASH_TYPES.has(entry.type) || !entry.url || entry.enabled === false)
@@ -171,6 +186,18 @@ export async function ensureGitCaches(config) {
             warn(`Warning: failed to refresh git mirror for "${entry.url}": ${err instanceof Error ? err.message : String(err)}`);
         }
     }
+    for (const entry of cfg.stashes ?? []) {
+        if (entry.type !== "website" || !entry.url || entry.enabled === false)
+            continue;
+        try {
+            await ensureWebsiteMirror(entry, { requireStashDir: true });
+        }
+        catch (err) {
+            warn(`Warning: failed to refresh website stash for "${entry.url}": ${err instanceof Error ? err.message : String(err)}`);
+        }
+    }
 }
-/** @deprecated Use ensureGitCaches instead. */
-export const ensureContextHubCaches = ensureGitCaches;
+/** @deprecated Use ensureStashCaches instead. */
+export const ensureGitCaches = ensureStashCaches;
+/** @deprecated Use ensureStashCaches instead. */
+export const ensureContextHubCaches = ensureStashCaches;

package/dist/setup.js

@@ -8,7 +8,7 @@
 import path from "node:path";
 import * as p from "@clack/prompts";
 import { isHttpUrl } from "./common";
-import { DEFAULT_CONFIG, getConfigPath, loadConfig, saveConfig } from "./config";
+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";
@@ -568,7 +568,7 @@ async function stepAgentPlatforms(current) {
 // ── Main Wizard ─────────────────────────────────────────────────────────────
 export async function runSetupWizard() {
     p.intro("akm setup");
-    const current = loadConfig();
+    const current = loadUserConfig();
     const configPath = getConfigPath();
     // Step 1: Stash directory
     p.log.step("Step 1: Stash Directory");

package/dist/stash-add.js

@@ -1,18 +1,22 @@
 import fs from "node:fs";
 import path from "node:path";
-import { resolveStashDir } from "./common";
-import { loadConfig, saveConfig } from "./config";
+import { isHttpUrl, resolveStashDir } from "./common";
+import { loadConfig, loadUserConfig, saveConfig } from "./config";
 import { UsageError } from "./errors";
 import { akmIndex } from "./indexer";
 import { upsertLockEntry } from "./lockfile";
 import { detectStashRoot, installRegistryRef, upsertInstalledRegistryEntry } from "./registry-install";
 import { parseRegistryRef } from "./registry-resolve";
+import { ensureWebsiteMirror, validateWebsiteInputUrl } from "./stash-providers/website";
 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`");
     const stashDir = resolveStashDir();
+    if (shouldAddAsWebsiteUrl(ref)) {
+        return addWebsiteStashSource(ref, stashDir, input.name, input.options);
+    }
     // Detect local directory refs and route them to stashes[] instead of installed[]
     try {
         const parsed = parseRegistryRef(ref);
@@ -32,7 +36,7 @@ export async function akmAdd(input) {
 async function addLocalStashSource(ref, sourcePath, stashDir) {
     const stashRoot = detectStashRoot(sourcePath);
     const resolvedPath = path.resolve(stashRoot);
-    const config = loadConfig();
+    const config = loadUserConfig();
     // Check for duplicates in stashes[]
     const stashes = [...(config.stashes ?? [])];
     const existing = stashes.find((s) => s.type === "filesystem" && s.path && path.resolve(s.path) === resolvedPath);
@@ -69,6 +73,50 @@ async function addLocalStashSource(ref, sourcePath, stashDir) {
         },
     };
 }
+async function addWebsiteStashSource(ref, stashDir, name, options) {
+    const normalizedUrl = validateWebsiteInputUrl(ref);
+    const config = loadUserConfig();
+    const stashes = [...(config.stashes ?? [])];
+    let entry = stashes.find((stash) => stash.type === "website" && stash.url === normalizedUrl);
+    if (!entry) {
+        entry = {
+            type: "website",
+            url: normalizedUrl,
+            name: name ?? toWebsiteName(normalizedUrl),
+            ...(options && Object.keys(options).length > 0 ? { options } : {}),
+        };
+        stashes.push(entry);
+        saveConfig({ ...config, stashes });
+    }
+    else if (options && Object.keys(options).length > 0) {
+        entry.options = { ...entry.options, ...options };
+        saveConfig({ ...config, stashes });
+    }
+    const cachePaths = await ensureWebsiteMirror(entry, { requireStashDir: true });
+    const index = await akmIndex({ stashDir });
+    const updatedConfig = loadConfig();
+    return {
+        schemaVersion: 1,
+        stashDir,
+        ref,
+        stashSource: {
+            type: "website",
+            url: normalizedUrl,
+            name: entry.name,
+            stashRoot: cachePaths.stashDir,
+        },
+        config: {
+            stashCount: updatedConfig.stashes?.length ?? 0,
+            installedKitCount: updatedConfig.installed?.length ?? 0,
+        },
+        index: {
+            mode: index.mode,
+            totalEntries: index.totalEntries,
+            directoriesScanned: index.directoriesScanned,
+            directoriesSkipped: index.directoriesSkipped,
+        },
+    };
+}
 /**
  * Install a kit from a registry (npm, github, git).
  */
@@ -119,6 +167,7 @@ async function addRegistryKit(ref, stashDir) {
             cacheDir: installed.cacheDir,
             extractedDir: installed.extractedDir,
             installedAt: installed.installedAt,
+            audit: installed.audit,
         },
         config: {
             stashCount: config.stashes?.length ?? 0,
@@ -139,3 +188,26 @@ function toReadableId(resolvedPath) {
     }
     return resolvedPath;
 }
+// Keep this list limited to widely-used git hosts for the non-breaking
+// "repo-like URL" fast-path; everything else continues to default to website snapshots.
+const KNOWN_GIT_HOSTS = new Set(["github.com", "gitlab.com", "bitbucket.org", "codeberg.org", "git.sr.ht"]);
+export function shouldAddAsWebsiteUrl(ref) {
+    return isHttpUrl(ref) && !isLikelyGitRepositoryUrl(ref);
+}
+function isLikelyGitRepositoryUrl(ref) {
+    try {
+        const parsed = new URL(ref);
+        return KNOWN_GIT_HOSTS.has(parsed.hostname.toLowerCase()) || parsed.pathname.endsWith(".git");
+    }
+    catch {
+        return false;
+    }
+}
+function toWebsiteName(siteUrl) {
+    try {
+        return new URL(siteUrl).hostname;
+    }
+    catch {
+        return siteUrl;
+    }
+}

package/dist/stash-providers/index.js

@@ -8,3 +8,4 @@
 import "./filesystem";
 import "./git";
 import "./openviking";
+import "./website";