akm-cli 0.6.0-rc1 → 0.6.0-rc2

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

@@ -1,17 +1,17 @@
 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 { 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";
-import { upsertLockEntry } from "./lockfile";
-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";
 const VALID_OVERRIDE_TYPES = new Set(["wiki"]);
 export async function akmAdd(input) {
     const ref = input.ref.trim();
@@ -32,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 {
@@ -41,7 +41,7 @@ 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 {
@@ -67,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 });
@@ -98,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),
@@ -106,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: {
@@ -118,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",
@@ -131,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;
@@ -145,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 });
@@ -154,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,
@@ -162,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: {
@@ -254,7 +264,7 @@ async function addRegistryStash(ref, stashDir, trustThisInstall, writable, wikiN
             audit,
         },
         config: {
-            stashCount: updatedConfig.stashes?.length ?? 0,
+            sourceCount: (updatedConfig.sources ?? updatedConfig.stashes ?? []).length,
             installedKitCount: updatedConfig.installed?.length ?? 0,
         },
         index: {

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 { 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";
+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) {
@@ -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}

@@ -10,7 +10,7 @@
  * `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",

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

@@ -1,7 +1,7 @@
 import path from "node:path";
+import { buildWorkflowAction } from "../output/renderers";
 import { registerActionBuilder, registerTypeRenderer } from "./asset-registry";
 import { toPosix } from "./common";
-import { buildWorkflowAction } from "./renderers";
 const markdownSpec = {
     isRelevantFile: (fileName) => path.extname(fileName).toLowerCase() === ".md",
     toCanonicalName: (typeRoot, filePath) => {