akm-cli 0.5.0 → 0.6.0-rc2

package/dist/{stash-add.js → commands/source-add.js}

@@ -1,21 +1,23 @@
 import fs from "node:fs";
 import path from "node:path";
-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";
-import { warn } from "./warn";
-import { ensureWikiNameAvailable, validateWikiName } from "./wiki";
+import { isHttpUrl, resolveStashDir } from "../core/common";
+import { loadConfig, loadUserConfig, saveConfig } from "../core/config";
+import { UsageError } from "../core/errors";
+import { warn } from "../core/warn";
+import { akmIndex } from "../indexer/indexer";
+import { upsertLockEntry } from "../integrations/lockfile";
+import { parseRegistryRef } from "../registry/resolve";
+import { detectStashRoot } from "../sources/providers/provider-utils";
+import { syncFromRef } from "../sources/providers/sync-from-ref";
+import { ensureWebsiteMirror, validateWebsiteInputUrl } from "../sources/providers/website";
+import { ensureWikiNameAvailable, validateWikiName } from "../wiki/wiki";
+import { auditInstallCandidate, deriveRegistryLabels, enforceRegistryInstallPolicy, formatInstallAuditFailure, } from "./install-audit";
 const VALID_OVERRIDE_TYPES = new Set(["wiki"]);
 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) {
@@ -30,7 +32,7 @@ export async function akmAdd(input) {
     }
     const stashDir = resolveStashDir();
     if (shouldAddAsWebsiteUrl(ref)) {
-        return addWebsiteStashSource(ref, stashDir, input.name ?? wikiName, input.options, wikiName);
+        return addWebsiteSource(ref, stashDir, input.name ?? wikiName, input.options, wikiName);
     }
     // Detect local directory refs and route them to stashes[] instead of installed[]
     try {
@@ -39,13 +41,13 @@ export async function akmAdd(input) {
             if (input.trustThisInstall) {
                 warn("--trust has no effect on local directory sources; the install audit is not run for local paths.");
             }
-            return addLocalStashSource(ref, parsed.sourcePath, stashDir, wikiName);
+            return addLocalSource(ref, parsed.sourcePath, stashDir, wikiName, input.name);
         }
     }
     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();
@@ -65,29 +67,39 @@ export async function registerWikiSource(input) {
  * Add a local directory as a filesystem stash source.
  * Creates a stashes[] entry instead of an installed[] entry.
  */
-async function addLocalStashSource(ref, sourcePath, stashDir, wikiName) {
+async function addLocalSource(ref, sourcePath, stashDir, wikiName, explicitName) {
     const stashRoot = detectStashRoot(sourcePath);
     const resolvedPath = path.resolve(stashRoot);
     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);
+    // Derive the canonical name: explicit --name wins, then wiki name, then readable path.
+    const derivedName = explicitName ?? wikiName ?? toReadableId(resolvedPath);
+    // Check for duplicates in sources[]
+    const sources = [...(config.sources ?? config.stashes ?? [])];
+    const existing = sources.find((s) => s.type === "filesystem" && s.path && path.resolve(s.path) === resolvedPath);
     let persistedEntry;
     if (!existing) {
         persistedEntry = {
             type: "filesystem",
             path: resolvedPath,
-            name: wikiName ?? toReadableId(resolvedPath),
+            name: derivedName,
             ...(wikiName ? { wikiName } : {}),
         };
-        stashes.push(persistedEntry);
-        saveConfig({ ...config, stashes });
+        sources.push(persistedEntry);
+        saveConfig({ ...config, sources, stashes: undefined });
     }
     else {
+        let changed = false;
+        // If --name was explicitly supplied, update the persisted name.
+        if (explicitName && existing.name !== explicitName) {
+            existing.name = explicitName;
+            changed = true;
+        }
         if (wikiName && existing.wikiName !== wikiName) {
             existing.wikiName = wikiName;
-            saveConfig({ ...config, stashes });
+            changed = true;
         }
+        if (changed)
+            saveConfig({ ...config, sources, stashes: undefined });
         persistedEntry = existing;
     }
     const index = await akmIndex({ stashDir });
@@ -96,7 +108,7 @@ async function addLocalStashSource(ref, sourcePath, stashDir, wikiName) {
         schemaVersion: 1,
         stashDir,
         ref: wikiName ?? ref,
-        stashSource: {
+        sourceAdded: {
             type: "filesystem",
             path: resolvedPath,
             name: persistedEntry.name ?? toReadableId(resolvedPath),
@@ -104,7 +116,7 @@ async function addLocalStashSource(ref, sourcePath, stashDir, wikiName) {
             ...(persistedEntry.wikiName ? { wiki: persistedEntry.wikiName } : {}),
         },
         config: {
-            stashCount: updatedConfig.stashes?.length ?? 0,
+            sourceCount: (updatedConfig.sources ?? updatedConfig.stashes ?? []).length,
             installedKitCount: updatedConfig.installed?.length ?? 0,
         },
         index: {
@@ -116,11 +128,11 @@ async function addLocalStashSource(ref, sourcePath, stashDir, wikiName) {
         },
     };
 }
-async function addWebsiteStashSource(ref, stashDir, name, options, wikiName) {
+async function addWebsiteSource(ref, stashDir, name, options, wikiName) {
     const normalizedUrl = validateWebsiteInputUrl(ref);
     const config = loadUserConfig();
-    const stashes = [...(config.stashes ?? [])];
-    let entry = stashes.find((stash) => stash.type === "website" && stash.url === normalizedUrl);
+    const sources = [...(config.sources ?? config.stashes ?? [])];
+    let entry = sources.find((stash) => stash.type === "website" && stash.url === normalizedUrl);
     if (!entry) {
         entry = {
             type: "website",
@@ -129,8 +141,8 @@ async function addWebsiteStashSource(ref, stashDir, name, options, wikiName) {
             ...(options && Object.keys(options).length > 0 ? { options } : {}),
             ...(wikiName ? { wikiName } : {}),
         };
-        stashes.push(entry);
-        saveConfig({ ...config, stashes });
+        sources.push(entry);
+        saveConfig({ ...config, sources, stashes: undefined });
     }
     else {
         let changed = false;
@@ -143,7 +155,7 @@ async function addWebsiteStashSource(ref, stashDir, name, options, wikiName) {
             changed = true;
         }
         if (changed)
-            saveConfig({ ...config, stashes });
+            saveConfig({ ...config, sources, stashes: undefined });
     }
     const cachePaths = await ensureWebsiteMirror(entry, { requireStashDir: true });
     const index = await akmIndex({ stashDir });
@@ -152,7 +164,7 @@ async function addWebsiteStashSource(ref, stashDir, name, options, wikiName) {
         schemaVersion: 1,
         stashDir,
         ref: wikiName ?? ref,
-        stashSource: {
+        sourceAdded: {
             type: "website",
             url: normalizedUrl,
             name: entry.name,
@@ -160,7 +172,7 @@ async function addWebsiteStashSource(ref, stashDir, name, options, wikiName) {
             ...(entry.wikiName ? { wiki: entry.wikiName } : {}),
         },
         config: {
-            stashCount: updatedConfig.stashes?.length ?? 0,
+            sourceCount: (updatedConfig.sources ?? updatedConfig.stashes ?? []).length,
             installedKitCount: updatedConfig.installed?.length ?? 0,
         },
         index: {
@@ -173,34 +185,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 +251,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,
+            sourceCount: (updatedConfig.sources ?? updatedConfig.stashes ?? []).length,
+            installedKitCount: updatedConfig.installed?.length ?? 0,
         },
         index: {
             mode: index.mode,
@@ -239,6 +276,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 → commands/source-clone.js}

@@ -1,18 +1,18 @@
 import fs from "node:fs";
 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 { makeAssetRef, parseAssetRef } from "./stash-ref";
-import { resolveAssetPath } from "./stash-resolve";
+import { makeAssetRef, parseAssetRef } from "../core/asset-ref";
+import { TYPE_DIRS } from "../core/asset-spec";
+import { NotFoundError, UsageError } from "../core/errors";
+import { findSourceForPath, getPrimarySource, resolveSourceEntries } from "../indexer/search-source";
+import { isRemoteOrigin, resolveSourcesForOrigin } from "../registry/origin-resolve";
+import { syncFromRef } from "../sources/providers/sync-from-ref";
+import { resolveAssetPath } from "../sources/resolve";
 export async function akmClone(options) {
     const parsed = parseAssetRef(options.sourceRef);
     // When --dest is provided, the working stash is optional
     let allSources;
     try {
-        allSources = resolveStashSources();
+        allSources = resolveSourceEntries();
     }
     catch (err) {
         if (options.dest) {
@@ -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,
         };
     }
@@ -56,8 +56,10 @@ export async function akmClone(options) {
         }
     }
     if (!sourcePath) {
-        const context = remoteFetched ? ` (remote package fetched but asset not found inside it)` : "";
-        throw lastError ?? new Error(`Source asset not found for ref: ${options.sourceRef}${context}`);
+        if (remoteFetched) {
+            throw new NotFoundError(`Source asset not found for ref: ${options.sourceRef} (remote package fetched but asset not found inside it)`, "ASSET_NOT_FOUND", "The remote package was fetched but doesn't contain the requested asset. Check the asset name and type.");
+        }
+        throw lastError ?? new NotFoundError(`Source asset not found for ref: ${options.sourceRef}`, "ASSET_NOT_FOUND");
     }
     const sourceSource = findSourceForPath(sourcePath, allSources);
     const destName = options.newName ?? parsed.name;

package/dist/{stash-source-manage.js → commands/source-manage.js}

@@ -1,19 +1,19 @@
 import path from "node:path";
-import { loadConfig, loadUserConfig, saveConfig } from "./config";
-import { UsageError } from "./errors";
-import { resolveStashSources } from "./search-source";
+import { loadConfig, loadUserConfig, saveConfig } from "../core/config";
+import { UsageError } from "../core/errors";
+import { resolveSourceEntries } from "../indexer/search-source";
 // ── Operations ──────────────────────────────────────────────────────────────
 /**
  * Add a stash source (filesystem path or remote provider URL) to config.
  *
  * Filesystem paths are auto-detected when `target` does not start with
  * `http://` or `https://`. URL sources require a `providerType` option
- * (e.g. "openviking").
+ * (e.g. "website", "git").
  */
 export function addStash(opts) {
     const { target, name, providerType, options: providerOptions, writable } = opts;
     const config = loadUserConfig();
-    const stashes = [...(config.stashes ?? [])];
+    const sources = [...(config.sources ?? config.stashes ?? [])];
     const isRemoteUrl = target.startsWith("http://") ||
         target.startsWith("https://") ||
         target.startsWith("git@") ||
@@ -22,11 +22,11 @@ export function addStash(opts) {
     let entry;
     if (isRemoteUrl) {
         if (!providerType) {
-            throw new UsageError("--provider is required for URL sources (e.g. --provider openviking)");
+            throw new UsageError("--provider is required for URL sources (e.g. --provider git --provider website)");
         }
         // Deduplicate by URL
-        if (stashes.some((s) => s.url === target)) {
-            return { stashes, added: false, message: "Source URL already configured" };
+        if (sources.some((s) => s.url === target)) {
+            return { sources, added: false, message: "Source URL already configured" };
         }
         entry = { type: providerType, url: target };
         if (name)
@@ -39,16 +39,16 @@ export function addStash(opts) {
     else {
         // Filesystem path
         const resolvedPath = path.resolve(target);
-        if (stashes.some((s) => s.path && path.resolve(s.path) === resolvedPath)) {
-            return { stashes, added: false, message: "Source path already configured" };
+        if (sources.some((s) => s.path && path.resolve(s.path) === resolvedPath)) {
+            return { sources, added: false, message: "Source path already configured" };
         }
         entry = { type: "filesystem", path: resolvedPath };
         if (name)
             entry.name = name;
     }
-    stashes.push(entry);
-    saveConfig({ ...config, stashes });
-    return { stashes, added: true, entry };
+    sources.push(entry);
+    saveConfig({ ...config, sources, stashes: undefined });
+    return { sources, added: true, entry };
 }
 /**
  * Remove a stash source by URL, path, or name.
@@ -56,7 +56,7 @@ export function addStash(opts) {
  */
 export function removeStash(target) {
     const config = loadUserConfig();
-    const stashes = [...(config.stashes ?? [])];
+    const sources = [...(config.sources ?? config.stashes ?? [])];
     const isUrl = target.startsWith("http://") ||
         target.startsWith("https://") ||
         target.startsWith("git@") ||
@@ -66,27 +66,27 @@ export function removeStash(target) {
     // Try URL match first, then path, then name (most specific → least specific)
     let idx = -1;
     if (isUrl) {
-        idx = stashes.findIndex((s) => s.url === target);
+        idx = sources.findIndex((s) => s.url === target);
     }
     if (idx === -1 && resolvedPath) {
-        idx = stashes.findIndex((s) => s.path && path.resolve(s.path) === resolvedPath);
+        idx = sources.findIndex((s) => s.path && path.resolve(s.path) === resolvedPath);
     }
     if (idx === -1) {
-        idx = stashes.findIndex((s) => s.name === target);
+        idx = sources.findIndex((s) => s.name === target);
     }
     if (idx === -1) {
-        return { stashes, removed: false, message: "No matching source found" };
+        return { sources, removed: false, message: "No matching source found" };
     }
-    const removed = stashes.splice(idx, 1)[0];
-    saveConfig({ ...config, stashes });
-    return { stashes, removed: true, entry: removed };
+    const removed = sources.splice(idx, 1)[0];
+    saveConfig({ ...config, sources, stashes: undefined });
+    return { sources, removed: true, entry: removed };
 }
 /**
  * List all stash sources (local filesystem + configured stashes).
  */
 export function listStashes() {
     const config = loadConfig();
-    const localSources = resolveStashSources();
-    const stashes = config.stashes ?? [];
-    return { localSources, stashes };
+    const localSources = resolveSourceEntries();
+    const sources = config.sources ?? config.stashes ?? [];
+    return { localSources, sources };
 }

package/dist/{vault.js → commands/vault.js}

@@ -66,6 +66,49 @@ export function listKeys(vaultPath) {
     const text = fs.readFileSync(vaultPath, "utf8");
     return { keys: scanKeys(text), comments: scanComments(text) };
 }
+/**
+ * Return structured `entries` pairing each key with the nearest preceding
+ * comment line (if any). This replaces the parallel `keys[]` + `comments[]`
+ * shape used internally by `listKeys` with a single merged array, which is
+ * easier for callers to consume (QA #35).
+ *
+ * Values are never included — the same privacy guarantee as `listKeys`.
+ */
+export function listEntries(vaultPath) {
+    if (!fs.existsSync(vaultPath))
+        return [];
+    const text = fs.readFileSync(vaultPath, "utf8");
+    const lines = text.split(/\r?\n/);
+    const seen = new Set();
+    const entries = [];
+    let pendingComment;
+    for (const line of lines) {
+        const trimmed = line.trimStart();
+        if (trimmed.startsWith("#")) {
+            // Capture the most recent comment before a key
+            pendingComment = trimmed.slice(1).trimStart() || undefined;
+            continue;
+        }
+        const m = line.match(ASSIGN_RE);
+        if (m) {
+            const key = m[1];
+            if (!seen.has(key)) {
+                seen.add(key);
+                const entry = { key };
+                if (pendingComment)
+                    entry.comment = pendingComment;
+                entries.push(entry);
+            }
+            pendingComment = undefined;
+        }
+        else {
+            // Any non-comment, non-assignment line (including blank lines)
+            // breaks "nearest preceding comment line" association.
+            pendingComment = undefined;
+        }
+    }
+    return entries;
+}
 /**
  * Read all KEY=value pairs from a vault file. Intended for programmatic
  * callers that need to inject values into a process environment. Callers

package/dist/{stash-ref.js → core/asset-ref.js}

@@ -30,7 +30,7 @@ export function makeAssetRef(type, name, origin) {
 export function parseAssetRef(ref) {
     const trimmed = ref.trim();
     if (!trimmed)
-        throw new UsageError("Empty ref.");
+        throw new UsageError("Empty ref.", "MISSING_REQUIRED_ARGUMENT");
     let origin;
     let body = trimmed;
     const boundary = trimmed.indexOf("//");
@@ -38,16 +38,16 @@ export function parseAssetRef(ref) {
         origin = trimmed.slice(0, boundary);
         body = trimmed.slice(boundary + 2);
         if (!origin)
-            throw new UsageError("Empty origin in ref.");
+            throw new UsageError("Empty origin in ref.", "MISSING_REQUIRED_ARGUMENT");
     }
     const colon = body.indexOf(":");
     if (colon <= 0) {
-        throw new UsageError(`Invalid ref "${trimmed}". Expected [origin//]type:name`);
+        throw new UsageError(`Invalid ref "${trimmed}". Expected [origin//]type:name, e.g. skill:deploy or knowledge:guide.md`, "MISSING_REQUIRED_ARGUMENT");
     }
     const rawType = body.slice(0, colon);
     const rawName = body.slice(colon + 1);
     if (!isAssetType(rawType)) {
-        throw new UsageError(`Invalid asset type: "${rawType}".`);
+        throw new UsageError(`Invalid asset type: "${rawType}".`, "MISSING_REQUIRED_ARGUMENT");
     }
     validateName(rawName);
     const name = normalizeName(rawName);

package/dist/{asset-registry.js → core/asset-registry.js}

@@ -1,16 +1,16 @@
 /**
  * Central registry for asset type renderer and action builder maps.
  *
- * Previously these maps lived in `local-search.ts` and were wired into
- * `asset-spec.ts` via a fragile `_setAssetTypeHooks` deferred callback
- * pattern. If `local-search.ts` was imported after `registerAssetType()`
- * calls, hooks would be silently dropped.
+ * Previously these maps lived in `db-search.ts` (then `local-search.ts`) and
+ * were wired into `asset-spec.ts` via a fragile `_setAssetTypeHooks` deferred
+ * callback pattern. If the search module was imported after
+ * `registerAssetType()` calls, hooks would be silently dropped.
  *
  * This module is a simple singleton that both `asset-spec.ts` and
- * `local-search.ts` import from, eliminating the import-order dependency
+ * `db-search.ts` import from, eliminating the import-order dependency
  * entirely.
  */
-import { buildWorkflowAction } from "./renderers";
+import { buildWorkflowAction } from "../output/renderers";
 /** Map asset types to their primary renderer names. */
 export const TYPE_TO_RENDERER = {
     script: "script-source",
@@ -53,3 +53,27 @@ export function registerTypeRenderer(type, rendererName) {
 export function registerActionBuilder(type, builder) {
     ACTION_BUILDERS[type] = builder;
 }
+export const defaultRendererRegistry = {
+    rendererNameFor(type) {
+        return TYPE_TO_RENDERER[type];
+    },
+    actionBuilderFor(type) {
+        return ACTION_BUILDERS[type];
+    },
+};
+/**
+ * Build a registry from explicit maps. Useful for tests that need to assert
+ * rendering behavior without touching the global singletons.
+ */
+export function createRendererRegistry(maps) {
+    const renderers = maps.renderers ?? {};
+    const actionBuilders = maps.actionBuilders ?? {};
+    return {
+        rendererNameFor(type) {
+            return renderers[type];
+        },
+        actionBuilderFor(type) {
+            return actionBuilders[type];
+        },
+    };
+}