akm-cli 0.6.0-rc1 → 0.6.0

package/dist/{stash-show.js → commands/show.js}

@@ -1,31 +1,47 @@
+/**
+ * `akm show` — entry point.
+ *
+ * Spec §6.2:
+ *
+ *   show(ref) → indexer.lookup(ref) → readFile(entry.filePath)
+ *
+ * The richer presentation logic (matchers, renderers, wiki-root handling,
+ * edit-hints, summary-detail truncation) lives below in this file. The flow:
+ *
+ *   1. Special-case wiki-root refs (`wiki:<name>` with no page path).
+ *   2. Ask `indexer.lookup(ref)` for the row in the FTS index.
+ *   3. Fall back to the on-disk type-dir resolver only when the index has
+ *      no matching row — covers the "indexed yet?" gap when the user has
+ *      just added a file and not run `akm index`.
+ *   4. Render the file via the matcher/renderer pipeline.
+ *
+ * Step (2) is the v1 spec change: reading is the indexer's job. Step (3) is a
+ * pragmatic safety net (NOT remote provider fallback, which the spec
+ * forbids — "Show: Local FTS5 index only. No remote provider fallback.").
+ */
 import fs from "node:fs";
 import path from "node:path";
-import { loadConfig } from "./config";
-import { closeDatabase, openDatabase } from "./db";
-import { NotFoundError, UsageError } from "./errors";
-import { buildFileContext, buildRenderContext, getRenderer, runMatchers } from "./file-context";
-import { parseFrontmatter, toStringOrUndefined } from "./frontmatter";
-import { loadStashFile } from "./metadata";
-import { resolveSourcesForOrigin } from "./origin-resolve";
-import { buildEditHint, findSourceForPath, isEditable, resolveStashSources } from "./search-source";
-import { resolveStashProviders } from "./stash-provider-factory";
-import { parseAssetRef } from "./stash-ref";
-import { resolveAssetPath } from "./stash-resolve";
-import { insertUsageEvent } from "./usage-events";
-// Eagerly import stash providers to trigger self-registration
-import "./stash-providers/index";
+import { parseAssetRef } from "../core/asset-ref";
+import { loadConfig } from "../core/config";
+import { NotFoundError, UsageError } from "../core/errors";
+import { parseFrontmatter, toStringOrUndefined } from "../core/frontmatter";
+import { closeDatabase, findEntryIdByRef, openDatabase } from "../indexer/db";
+import { buildFileContext, buildRenderContext, getRenderer, runMatchers } from "../indexer/file-context";
+import { lookup } from "../indexer/indexer";
+import { loadStashFile } from "../indexer/metadata";
+import { buildEditHint, findSourceForPath, isEditable, resolveSourceEntries } from "../indexer/search-source";
+import { insertUsageEvent } from "../indexer/usage-events";
+import { resolveSourcesForOrigin } from "../registry/origin-resolve";
+// Eagerly import source providers to trigger self-registration.
+import "../sources/providers/index";
+import { resolveAssetPath } from "../sources/resolve";
 /**
  * Show a wiki root (no page path) — returns the same payload as
  * `akm wiki show <name>`.
- *
- * Called when `parseAssetRef` yields `type === "wiki"` and the name has no
- * `/`, e.g. `wiki:research`.
  */
 async function showWikiRoot(stashDir, wikiName) {
-    const { showWiki } = await import("./wiki.js");
+    const { showWiki } = await import("../wiki/wiki.js");
     const result = showWiki(stashDir, wikiName);
-    // Shape the WikiShowResult into a ShowResponse-compatible object.
-    // The payload mirrors what `akm wiki show <name>` returns.
     return {
         type: "wiki",
         name: result.ref,
@@ -40,7 +56,7 @@ async function showWikiRoot(stashDir, wikiName) {
     };
 }
 async function showWikiRootForSource(stashDir, source, wikiName) {
-    const { showWikiAtPath } = await import("./wiki.js");
+    const { showWikiAtPath } = await import("../wiki/wiki.js");
     if (source.wikiName === wikiName) {
         const result = showWikiAtPath(wikiName, source.path);
         return {
@@ -78,7 +94,9 @@ function resolveRegisteredWikiAssetPath(wikiRoot, wikiName, assetName) {
     return realTarget;
 }
 /**
- * Unified show: tries local FTS5 index first, then remote providers.
+ * Unified show: queries the local FTS5 index, then falls back to on-disk
+ * type-dir resolution if the index has no row. Spec §6.2; no remote provider
+ * fallback.
  *
  * When `detail` is `"summary"`, the response omits content/template/prompt and
  * returns only compact metadata (name, type, description, tags, parameters).
@@ -92,7 +110,7 @@ export async function akmShowUnified(input) {
     {
         const parsed = parseAssetRef(ref);
         if (parsed.type === "wiki" && !parsed.name.includes("/")) {
-            const allSources = resolveStashSources();
+            const allSources = resolveSourceEntries();
             const searchSources = resolveSourcesForOrigin(parsed.origin, allSources);
             let lastError;
             for (const source of searchSources) {
@@ -109,56 +127,19 @@ export async function akmShowUnified(input) {
                 new NotFoundError(`Wiki not found: ${parsed.name}. Run \`akm wiki create ${parsed.name}\` to create it.`));
         }
     }
-    // 1. Try local filesystem first (FTS5 index lookup)
-    let localError;
-    try {
-        const result = await showLocal(input);
-        logShowEvent(ref);
-        return result;
-    }
-    catch (err) {
-        // Only fall through to remote providers on NotFoundError
-        if (!(err instanceof NotFoundError))
-            throw err;
-        localError = err;
-    }
-    // 2. Try remote providers (e.g. OpenViking)
-    const config = loadConfig();
-    const providers = resolveStashProviders(config).filter((p) => p.type !== "filesystem" && p.canShow(ref));
-    for (const provider of providers) {
-        try {
-            const response = await provider.show(ref, input.view);
-            logShowEvent(ref);
-            if (input.detail === "summary") {
-                return buildSummaryResponse(response);
-            }
-            return response;
-        }
-        catch (err) {
-            if (!(err instanceof NotFoundError))
-                throw err;
-        }
-    }
-    // Nothing found anywhere — rethrow the original local error with its specific message
-    throw localError;
+    // Try local filesystem (FTS5 index lookup, then on-disk fallback)
+    const result = await showLocal(input);
+    logShowEvent(ref);
+    return result;
 }
-/**
- * Fire-and-forget: log a show event to the usage_events table.
- * Never blocks the caller; errors are silently ignored.
- */
 function logShowEvent(ref, existingDb) {
     try {
         const db = existingDb ?? openDatabase();
         try {
-            const parsed = parseAssetRef(ref);
-            const safeName = parsed.name.replace(/%/g, "\\%").replace(/_/g, "\\_");
-            const row = db
-                .prepare("SELECT id FROM entries WHERE entry_key LIKE ? ESCAPE '\\' AND entry_type = ? LIMIT 1")
-                .get(`%:${parsed.type}:${safeName}`, parsed.type);
             insertUsageEvent(db, {
                 event_type: "show",
                 entry_ref: ref,
-                entry_id: row?.id,
+                entry_id: findEntryIdByRef(db, ref),
             });
         }
         finally {
@@ -170,14 +151,48 @@ function logShowEvent(ref, existingDb) {
         /* fire-and-forget */
     }
 }
+/**
+ * Resolve an asset path to a file via:
+ *   1. `indexer.lookup(ref)` — the spec's primary path (§6.2).
+ *   2. On-disk type-dir traversal — fallback for files not yet indexed.
+ *
+ * Returns `undefined` if neither path finds a match.
+ */
+async function resolvePathViaIndexThenDisk(parsed, searchSourceDirs) {
+    // Step 1: indexer
+    try {
+        const entry = await lookup(parsed);
+        if (entry) {
+            return { assetPath: entry.filePath };
+        }
+    }
+    catch (err) {
+        // Index unavailable (e.g. DB doesn't exist yet) — fall back to disk walk.
+        if (!(err instanceof NotFoundError)) {
+            // continue to disk fallback
+        }
+    }
+    // Step 2: on-disk type-dir traversal
+    let lastError;
+    for (const dir of searchSourceDirs) {
+        try {
+            const assetPath = await resolveAssetPath(dir, parsed.type, parsed.name);
+            return { assetPath, lastError };
+        }
+        catch (err) {
+            lastError = err instanceof Error ? err : new Error(String(err));
+        }
+    }
+    return lastError ? { assetPath: "", lastError } : undefined;
+}
 /** @internal Use akmShowUnified() for all external callers. */
 export async function showLocal(input) {
     const parsed = parseAssetRef(input.ref);
     const displayType = parsed.type;
     const config = loadConfig();
-    const allSources = resolveStashSources(input.stashDir);
+    const allSources = resolveSourceEntries(input.stashDir);
     const searchSources = resolveSourcesForOrigin(parsed.origin, allSources);
-    const allStashDirs = searchSources.map((s) => s.path);
+    const allSourceDirs = searchSources.map((s) => s.path);
     let assetPath;
     const matchedSource = parsed.type === "wiki" ? searchSources.find((source) => parsed.name.startsWith(`${source.wikiName}/`)) : undefined;
     let lastError;
@@ -189,15 +204,13 @@ export async function showLocal(input) {
             lastError = err instanceof Error ? err : new Error(String(err));
         }
     }
-    for (const dir of allStashDirs) {
-        if (assetPath)
-            break;
-        try {
-            assetPath = await resolveAssetPath(dir, parsed.type, parsed.name);
-            break;
+    if (!assetPath) {
+        const resolved = await resolvePathViaIndexThenDisk(parsed, allSourceDirs);
+        if (resolved?.assetPath) {
+            assetPath = resolved.assetPath;
         }
-        catch (err) {
-            lastError = err instanceof Error ? err : new Error(String(err));
+        else if (resolved?.lastError) {
+            lastError = resolved.lastError;
         }
     }
     if (!assetPath && parsed.origin && searchSources.length === 0) {
@@ -211,7 +224,7 @@ export async function showLocal(input) {
                 "Check the name with `akm search` or verify the asset exists in your stash."));
     }
     const source = matchedSource ?? findSourceForPath(assetPath, allSources);
-    const sourceStashDir = source?.path ?? allStashDirs[0];
+    const sourceStashDir = source?.path ?? allSourceDirs[0];
     if (!sourceStashDir) {
         throw new UsageError(`Could not determine stash root for asset: ${displayType}:${parsed.name}. ` +
             "Run `akm init` to create the stash directory, or check `akm stash list` for configured paths.");
@@ -229,7 +242,7 @@ export async function showLocal(input) {
     if (!renderer) {
         throw new UsageError(`Renderer "${match.renderer}" not found for asset: ${displayType}:${parsed.name}`);
     }
-    const renderCtx = buildRenderContext(fileCtx, match, allStashDirs, source?.registryId);
+    const renderCtx = buildRenderContext(fileCtx, match, allSourceDirs, source?.registryId);
     const response = renderer.buildShowResponse(renderCtx);
     const editable = isEditable(assetPath, config);
     const fullResponse = {
@@ -243,6 +256,20 @@ export async function showLocal(input) {
     }
     return fullResponse;
 }
+/**
+ * Minimal `show`: ref → indexer lookup → file contents. Used by callers that
+ * just need the raw file (e.g. clone, write-source) and don't want the full
+ * renderer graph. Spec §6.2's literal flow.
+ */
+export async function showByRef(ref) {
+    const parsed = parseAssetRef(ref);
+    const entry = await lookup(parsed);
+    if (!entry) {
+        throw new NotFoundError(`Asset not found for ref: ${parsed.type}:${parsed.name}`);
+    }
+    const body = await fs.promises.readFile(entry.filePath, "utf8");
+    return { filePath: entry.filePath, body };
+}
 /**
  * Build a compact summary response from a full ShowResponse.
  *
@@ -250,24 +277,17 @@ export async function showLocal(input) {
  * type, name, path, description, tags, parameters, action.
  * Enriches description and tags from frontmatter or .stash.json when available.
  *
- * Enrichment via frontmatter and .stash.json is only performed when `assetPath`
- * is supplied (local assets). Remote provider responses (e.g. OpenViking) rely
- * on the provider having already populated description and tags.
- *
  * The resulting JSON should be under 200 tokens.
  */
 function buildSummaryResponse(full, assetPath) {
-    // Try to enrich metadata from .stash.json if description or tags are missing
     let description = full.description;
     let tags = full.tags;
     if (assetPath) {
-        // Try frontmatter extraction from content fields
         const textContent = full.content ?? full.template ?? full.prompt;
         if (textContent && !description) {
             const parsed = parseFrontmatter(textContent);
             description = toStringOrUndefined(parsed.data.description);
         }
-        // Try .stash.json for richer metadata (tags especially)
         const dir = path.dirname(assetPath);
         const stashFile = loadStashFile(dir);
         if (stashFile) {

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