akm-cli 0.9.0-rc.1 → 0.9.0-rc.13

package/dist/commands/sources/bundle-cli.js

@@ -0,0 +1,166 @@
+// This Source Code Form is subject to the terms of the Mozilla Public
+// License, v. 2.0. If a copy of the MPL was not distributed with this
+// file, You can obtain one at https://mozilla.org/MPL/2.0/.
+/**
+ * `akm bundle` command group — 0.9 CLI overhaul (S7).
+ *
+ * Consolidates the five former top-level bundle-lifecycle commands under one
+ * group, hard break, no alias kept at the top level:
+ *   - `create` (= old top-level `init`, src/commands/sources/init.ts)
+ *   - `add`    (= old top-level `add`, src/commands/sources/add-cli.ts — the
+ *     command definition moved here; `add-cli.ts` keeps its exported helpers,
+ *     including `auditInstalledStashForDangerousKeys`, which a test imports
+ *     directly)
+ *   - `list`   (= old top-level `list`)
+ *   - `remove` (= old top-level `remove`)
+ *   - `update` (= old top-level `update`)
+ *   - `show <name>` — NEW: a single-bundle detail view of the `list` payload.
+ *
+ * `add`/`list`/`remove`/`update` are pure relocations (payload and output
+ * shape unchanged: `SourceEntry`/`RemoveResponse`/`UpdateResponse` keep their
+ * bare `add`/`list`/`remove`/`update` output shape). `create` is a genuine
+ * verb rename (was `init`), so its output shape is renamed to `bundle-create`
+ * to match (the same convention S8 used for `propose` -> `proposal new`'s
+ * `proposal-new` shape). `show` is a new shape, `bundle-show`.
+ */
+import { defineGroupCommand, defineJsonCommand, output } from "../../cli/shared.js";
+import { NotFoundError, UsageError } from "../../core/errors.js";
+import { appendEvent } from "../../core/events.js";
+import { addCommand } from "./add-cli.js";
+import { akmInit } from "./init.js";
+import { akmListSources, akmRemove, akmUpdate } from "./installed-stashes.js";
+const VALID_SOURCE_KINDS = new Set(["filesystem", "git", "npm", "website"]);
+function parseKindFilter(raw) {
+    if (!raw)
+        return undefined;
+    const kinds = raw.split(",").map((s) => s.trim());
+    for (const k of kinds) {
+        if (!VALID_SOURCE_KINDS.has(k)) {
+            throw new UsageError(`Invalid --kind value: "${k}". Expected one of: filesystem, git, npm, website`);
+        }
+    }
+    return kinds;
+}
+const createCommand = defineJsonCommand({
+    meta: {
+        name: "create",
+        description: "Initialize akm's working bundle directory and persist it in config",
+    },
+    args: {
+        dir: { type: "string", description: "Custom bundle directory path (default: ~/akm)" },
+        "set-default": {
+            type: "boolean",
+            description: "Make --dir the default bundle. Without this, `akm bundle create --dir X` scaffolds X but leaves your existing default bundle unchanged.",
+            default: false,
+        },
+    },
+    async run({ args }) {
+        const result = await akmInit({
+            dir: args.dir,
+            setDefault: args["set-default"],
+        });
+        output("bundle-create", result);
+    },
+});
+const listCommand = defineJsonCommand({
+    meta: { name: "list", description: "List configured bundles and their resolved source state" },
+    args: {
+        kind: {
+            type: "string",
+            description: "Filter by source provider (filesystem, git, npm, website). Comma-separated.",
+        },
+    },
+    async run({ args }) {
+        const kind = parseKindFilter(args.kind);
+        const result = await akmListSources({ kind });
+        output("list", result);
+    },
+});
+const showCommand = defineJsonCommand({
+    meta: { name: "show", description: "Show detail for a single configured bundle" },
+    args: {
+        name: { type: "positional", description: "Bundle name (as reported by `akm bundle list`)", required: true },
+    },
+    async run({ args }) {
+        const { sources } = await akmListSources();
+        const entry = sources.find((s) => s.name === args.name);
+        if (!entry) {
+            throw new NotFoundError(`No configured bundle named "${args.name}"`, "SOURCE_NOT_FOUND");
+        }
+        output("bundle-show", entry);
+    },
+});
+const removeCommand = defineJsonCommand({
+    meta: { name: "remove", description: "Remove a bundle by id, ref, path, URL, or name" },
+    args: {
+        target: { type: "positional", description: "Bundle to remove (id, ref, path, URL, or name)", required: true },
+        yes: { type: "boolean", alias: "y", description: "Skip confirmation prompt", default: false },
+    },
+    async run({ args }) {
+        const { confirmDestructive } = await import("../../cli/confirm.js");
+        const confirmed = await confirmDestructive(`Remove bundle "${args.target}"? This cannot be undone.`, {
+            yes: args.yes === true,
+        });
+        if (!confirmed) {
+            process.stderr.write("Aborted.\n");
+            return;
+        }
+        const result = await akmRemove({ target: args.target });
+        appendEvent({
+            eventType: "remove",
+            metadata: {
+                target: args.target,
+                ref: typeof result.removed?.ref === "string" ? result.removed.ref : null,
+                id: typeof result.removed?.id === "string" ? result.removed.id : null,
+            },
+        });
+        output("remove", result);
+    },
+});
+const updateCommand = defineJsonCommand({
+    meta: { name: "update", description: "Update one or all managed bundles" },
+    args: {
+        target: { type: "positional", description: "Bundle to update (id or ref)", required: false },
+        all: { type: "boolean", description: "Update all installed entries", default: false },
+        force: { type: "boolean", description: "Force fresh download even if version is unchanged", default: false },
+        // F1/R-058: gates ONLY the rare branch where the resolved content
+        // directory moves and the previous `localRoot` is deleted — a normal
+        // refresh (the overwhelming majority of updates) deletes nothing and
+        // never consults this flag. Mirrors `remove`'s `-y/--yes`.
+        yes: {
+            type: "boolean",
+            alias: "y",
+            description: "Skip the confirmation prompt when an update needs to delete a previous install directory (because the resolved content location moved). No effect on a normal refresh, which deletes nothing.",
+            default: false,
+        },
+    },
+    async run({ args }) {
+        const result = await akmUpdate({ target: args.target, all: args.all, force: args.force, yes: args.yes });
+        appendEvent({
+            eventType: "update",
+            metadata: {
+                target: args.target ?? null,
+                all: args.all === true,
+                force: args.force === true,
+                processed: Array.isArray(result.processed)
+                    ? result.processed.length
+                    : 0,
+            },
+        });
+        output("update", result);
+    },
+});
+export const bundleCommand = defineGroupCommand({
+    meta: {
+        name: "bundle",
+        description: "Create, add to, inspect, and manage your bundles (working bundle + configured sources)",
+    },
+    subCommands: {
+        create: createCommand,
+        add: addCommand,
+        list: listCommand,
+        show: showCommand,
+        remove: removeCommand,
+        update: updateCommand,
+    },
+});

package/dist/commands/sources/bundle-config-ops.js

@@ -0,0 +1,63 @@
+// This Source Code Form is subject to the terms of the Mozilla Public
+// License, v. 2.0. If a copy of the MPL was not distributed with this
+// file, You can obtain one at https://mozilla.org/MPL/2.0/.
+/**
+ * Bundle-map config write helpers (0.9.0 config-shape cutover, spec §10.1).
+ *
+ * The `stashDir`/`sources[]`/`installed[]` trio is retired: every source is now
+ * a `bundles.<slug>` entry, and the primary working stash is the `defaultBundle`.
+ * These helpers give the source writers (`akm bundle create`, `akm setup`, `akm bundle add`,
+ * `akm sources add/remove`) one place to derive slug-legal bundle keys (via the
+ * shared {@link deriveBundleId} — D-R5), locate an existing bundle by its source
+ * descriptor, and set/repoint the primary bundle — without duplicating the
+ * keying rules across call sites.
+ */
+import path from "node:path";
+import { primaryBundlePath } from "../../core/config/config.js";
+import { deriveBundleId } from "../../indexer/installations.js";
+export { primaryBundlePath };
+/**
+ * Upsert the primary filesystem bundle (`{ path, writable: true }`) and point
+ * `defaultBundle` at it. Reuses the current default key when it already names a
+ * filesystem bundle (so re-pointing the primary keeps a stable id); otherwise
+ * derives a fresh slug-legal key from the path.
+ */
+export function withPrimaryBundle(config, stashDir) {
+    const bundles = { ...(config.bundles ?? {}) };
+    let key = config.defaultBundle;
+    if (!key || !(key in bundles) || typeof bundles[key]?.path !== "string") {
+        key = deriveBundleId(undefined, stashDir, new Set(Object.keys(bundles)));
+    }
+    bundles[key] = {
+        ...bundles[key],
+        path: stashDir,
+        writable: true,
+        components: { main: { root: ".", adapter: "akm", writable: true } },
+    };
+    return { ...config, bundles, defaultBundle: key };
+}
+/** Existing bundle key whose filesystem descriptor resolves to `resolvedPath`, or `undefined`. */
+export function bundleKeyForPath(config, resolvedPath) {
+    for (const [key, bundle] of Object.entries(config.bundles ?? {})) {
+        if (typeof bundle.path === "string" && path.resolve(bundle.path) === resolvedPath)
+            return key;
+    }
+    return undefined;
+}
+/** Existing bundle key whose git/website/npm descriptor matches `url`, or `undefined`. */
+export function bundleKeyForUrl(config, url) {
+    for (const [key, bundle] of Object.entries(config.bundles ?? {})) {
+        if (bundle.git === url || bundle.website?.url === url || bundle.npm === url)
+            return key;
+    }
+    return undefined;
+}
+/**
+ * Derive a slug-legal, batch-unique bundle key for a new source: prefer the
+ * caller's `preferredName` when it is a legal slug, else slug the seed locator
+ * (path/url) — the shared {@link deriveBundleId} rule (D-R5), made unique against
+ * the currently-configured bundle keys.
+ */
+export function nextBundleKey(bundles, preferredName, seedLocator) {
+    return deriveBundleId(preferredName, seedLocator, new Set(Object.keys(bundles)));
+}

package/dist/commands/sources/info.js

@@ -2,11 +2,16 @@
 // License, v. 2.0. If a copy of the MPL was not distributed with this
 // file, You can obtain one at https://mozilla.org/MPL/2.0/.
 import fs from "node:fs";
-import { getAssetTypes } from "../../core/asset/asset-spec.js";
+import { placementTypes } from "../../core/asset/asset-placement.js";
+import { resolveStashDir } from "../../core/common.js";
 import { getSources, loadConfig } from "../../core/config/config.js";
 import { getDbPath } from "../../core/paths.js";
-import { closeDatabase, getEntryCount, getMeta, isVecAvailable, openExistingDatabase } from "../../indexer/db/db.js";
+import { error } from "../../core/warn.js";
 import { getEffectiveSemanticStatus, readSemanticStatus } from "../../indexer/search/semantic-status.js";
+import { closeDatabase, openExistingDatabase } from "../../storage/repositories/index-connection.js";
+import { getEntryCount, getEntryCountByType } from "../../storage/repositories/index-entries-repository.js";
+import { getMeta } from "../../storage/repositories/index-meta-repository.js";
+import { isVecAvailable } from "../../storage/repositories/index-vec-repository.js";
 import { pkgVersion } from "../../version.js";
 /**
  * Assemble system info describing the current capabilities, configuration,
@@ -16,8 +21,13 @@ import { pkgVersion } from "../../version.js";
  */
 export function assembleInfo(options) {
     const config = loadConfig();
-    // Asset types (copy into a mutable array — `getAssetTypes()` returns readonly)
-    const assetTypes = [...getAssetTypes()];
+    // Primary stash directory + default bundle name — same resolution
+    // `akm sources list` uses (R-057), so `akm info` and `akm sources list`
+    // agree on which stash is primary.
+    const stashDir = resolveStashDir();
+    const defaultBundle = config.defaultBundle ?? null;
+    // Asset types (copy into a mutable array — `placementTypes()` returns readonly)
+    const assetTypes = [...placementTypes()];
     const semanticRuntime = readSemanticStatus();
     const semanticStatus = getEffectiveSemanticStatus(config, semanticRuntime);
     // Search modes
@@ -32,28 +42,26 @@ export function assembleInfo(options) {
         ...(r.provider ? { provider: r.provider } : {}),
         ...(r.enabled !== undefined ? { enabled: r.enabled } : {}),
     }));
-    // Stash providers — prefer `sources[]`; fall back to `stashDir` when the
-    // user has not yet migrated to the sources[] config shape so that info
-    // always reflects at least one provider when a stash is configured.
+    // Stash providers — the unified `bundles` source list (spec §10.1), which
+    // already includes the primary (`defaultBundle`) stash first.
     const configuredSources = getSources(config);
-    const stashesList = configuredSources.length === 0 && config.stashDir
-        ? [{ type: "filesystem", path: config.stashDir, name: "primary" }]
-        : configuredSources;
-    const sourceProviders = stashesList.map((s) => ({
+    const sourceProviders = configuredSources.map((s) => ({
         type: s.type,
         ...(s.name ? { name: s.name } : {}),
         ...(s.path ? { path: s.path } : {}),
         ...(s.url ? { url: s.url } : {}),
         ...(s.enabled !== undefined ? { enabled: s.enabled } : {}),
     }));
-    // Index stats — resolve the DB path from config so info reads the same
-    // database that health and search use, rather than a bare getDbPath() call
-    // that ignores XDG_DATA_HOME or per-config overrides.
+    // Index stats — `options.dbPath` is a test-only override (see the param
+    // doc above); real callers fall through to the same `getDbPath()` that
+    // health and search use, so info reads the same database they do.
     const resolvedDbPath = options?.dbPath ?? getDbPath();
     const indexStats = readIndexStats(resolvedDbPath);
     return {
         schemaVersion: 1,
         version: pkgVersion,
+        bundleDir: stashDir,
+        defaultBundle,
         assetTypes,
         searchModes,
         semanticSearch: {
@@ -70,6 +78,7 @@ export function assembleInfo(options) {
 function readIndexStats(resolvedPath) {
     const EMPTY = {
         entryCount: 0,
+        byType: {},
         lastBuiltAt: null,
         hasEmbeddings: false,
         vecAvailable: false,
@@ -81,6 +90,7 @@ function readIndexStats(resolvedPath) {
         db = openExistingDatabase(resolvedPath);
         return {
             entryCount: getEntryCount(db),
+            byType: getEntryCountByType(db),
             lastBuiltAt: getMeta(db, "builtAt") ?? null,
             hasEmbeddings: getMeta(db, "hasEmbeddings") === "1",
             vecAvailable: isVecAvailable(db),
@@ -89,7 +99,9 @@ function readIndexStats(resolvedPath) {
     catch (err) {
         // Surface the error so operators can diagnose mismatches between
         // `akm info` and `akm health` rather than silently returning zeros.
-        process.stderr.write(`[akm info] failed to read index stats from ${resolvedPath}: ${String(err)}\n`);
+        // Routed through core/warn's `error()` (not a raw process.stderr.write)
+        // so `--quiet`/`setQuiet()` actually gate this line (R-057).
+        error(`[akm info] failed to read index stats from ${resolvedPath}: ${String(err)}`);
         return EMPTY;
     }
     finally {

package/dist/commands/sources/init.js

@@ -10,18 +10,18 @@
 import { spawnSync } from "node:child_process";
 import fs from "node:fs";
 import path from "node:path";
-import { TYPE_DIRS } from "../../core/asset/asset-spec.js";
-import { loadUserConfig, saveConfig } from "../../core/config/config.js";
+import { stashDirNames } from "../../core/asset/asset-placement.js";
+import { mutateConfig } from "../../core/config/config.js";
 import { ConfigError } from "../../core/errors.js";
-import { assertSafeStashDir, getBinDir, getConfigPath, getDefaultStashDir } from "../../core/paths.js";
-import { ensureRg } from "../../core/ripgrep/install.js";
+import { assertSafeStashDir, getConfigPath, getDefaultStashDir } from "../../core/paths.js";
+import { primaryBundlePath, withPrimaryBundle } from "./bundle-config-ops.js";
 import { copyStashSkeleton, ensureStashGitignore, scaffoldStashMeta } from "./stash-skeleton.js";
 /**
  * Refuse to persist a temporary-directory stashDir to the user's config when
  * running under a test runner AND `--dir <tempdir>` was passed explicitly.
  * This guard targets the exact agent-overreach pattern documented in
- * `memory:akm-init-persists-stashdir-warning`: an agent ran
- * `akm init --dir $(mktemp -d)` for an E2E test and silently rewrote the
+ * `memories/akm-init-persists-stashdir-warning`: an agent ran
+ * `akm bundle create --dir $(mktemp -d)` for an E2E test and silently rewrote the
  * developer's real config to point at a now-deleted temp dir.
  *
  * Tests that legitimately resolve a tempdir via HOME (default-path init) are
@@ -31,7 +31,7 @@ import { copyStashSkeleton, ensureStashGitignore, scaffoldStashMeta } from "./st
  *   - `BUN_TEST=1`     — explicit opt-in
  *   - `NODE_ENV=test`  — what `bun test` sets today
  *
- * Tests that genuinely need to exercise `akm init --dir /tmp/...` should set
+ * Tests that genuinely need to exercise `akm bundle create --dir /tmp/...` should set
  * `AKM_FORCE_INIT_TMP_STASH=1`.
  */
 function assertInitSandbox(stashDir, dirExplicitlyProvided) {
@@ -72,8 +72,8 @@ async function akmInitReal(options) {
     const setDefault = options?.setDefault === true;
     const stashDir = options?.dir ? path.resolve(options.dir) : getDefaultStashDir();
     // Safety check (#473): refuse stashDir at /, $HOME, /etc, ~/.config, etc.
-    // Runs BEFORE any disk write — a fat-fingered `akm init --dir /` or
-    // `akm init --dir ~` would otherwise mkdir + git-init the user's system
+    // Runs BEFORE any disk write — a fat-fingered `akm bundle create --dir /` or
+    // `akm bundle create --dir ~` would otherwise mkdir + git-init the user's system
     // root or home directory. Catastrophic-on-misuse vs. trivial-to-recover-from.
     assertSafeStashDir(stashDir);
     // Defense-in-depth: refuse to persist an explicit --dir /tmp/... stashDir
@@ -84,7 +84,7 @@ async function akmInitReal(options) {
         fs.mkdirSync(stashDir, { recursive: true });
         created = true;
     }
-    for (const sub of Object.values(TYPE_DIRS)) {
+    for (const sub of stashDirNames()) {
         const subDir = path.join(stashDir, sub);
         if (!fs.existsSync(subDir)) {
             fs.mkdirSync(subDir, { recursive: true });
@@ -97,16 +97,16 @@ async function akmInitReal(options) {
     // opts into versioning by un-ignoring a path.
     ensureStashGitignore(stashDir);
     // Run seeding UNCONDITIONALLY (not just when the stash was newly created) so
-    // re-running `akm init` on an existing stash backfills any missing skeleton
+    // re-running `akm bundle create` on an existing stash backfills any missing skeleton
     // files — the README, the per-type SOFT convention templates under
     // facts/conventions/assets/, and the `.meta/index.md` orientation doc. Both
     // helpers are absent-only: they never overwrite a file a user has edited.
     copyStashSkeleton(stashDir);
     scaffoldStashMeta(stashDir);
     // Persist stashDir in config.json — but ONLY when the user is actually
-    // setting up / opting into a default. A bare `akm init --dir <secondary>`
+    // setting up / opting into a default. A bare `akm bundle create --dir <secondary>`
     // must NOT silently repoint the user's real default stash (the footgun
-    // documented in memory:akm-init-persists-stashdir-warning).
+    // documented in memories/akm-init-persists-stashdir-warning).
     //
     // Decision matrix — persist when ANY of:
     //   (a) no --dir provided           → default HOME-resolved setup flow
@@ -115,35 +115,25 @@ async function akmInitReal(options) {
     // Otherwise (--dir + existing default + no --set-default) leave the default
     // pointer alone; the target dir is still scaffolded above.
     const configPath = getConfigPath();
-    const existing = loadUserConfig();
-    const existingStashDir = existing.stashDir;
-    const shouldPersist = !dirExplicitlyProvided || !existingStashDir || setDefault;
-    let defaultStashUpdated = false;
+    let defaultBundleUpdated = false;
     let previousStashDir;
-    if (shouldPersist) {
-        if (!existingStashDir || existingStashDir !== stashDir) {
-            saveConfig({ ...existing, stashDir });
-            defaultStashUpdated = true;
-        }
-        // else: already pointed here — no-op, no spurious rewrite.
-    }
-    else {
-        // Default left untouched; surface it so the CLI can inform the user.
-        previousStashDir = existingStashDir;
-    }
-    // Ensure ripgrep is available (install to cache/bin if needed)
-    let ripgrep;
-    if (!isUnderTestRunner()) {
-        try {
-            const binDir = getBinDir();
-            const rgResult = ensureRg(binDir);
-            ripgrep = rgResult;
-        }
-        catch {
-            // Non-fatal: ripgrep is optional, search works without it
-        }
+    if (options?.persistConfig !== false) {
+        const result = mutateConfig((latest) => {
+            // 0.9.0 (spec §10.1): the primary stash is the `defaultBundle`'s filesystem
+            // `path`, not the retired top-level `stashDir`.
+            const currentPrimary = primaryBundlePath(latest);
+            const shouldPersist = !dirExplicitlyProvided || !currentPrimary || setDefault;
+            if (!shouldPersist) {
+                previousStashDir = currentPrimary;
+                return latest;
+            }
+            if (currentPrimary === stashDir)
+                return latest;
+            return withPrimaryBundle(latest, stashDir);
+        });
+        defaultBundleUpdated = result.written;
     }
-    return { stashDir, created, configPath, defaultStashUpdated, previousStashDir, ripgrep };
+    return { bundleDir: stashDir, created, configPath, defaultBundleUpdated, previousBundleDir: previousStashDir };
 }
 /** Initialise `dir` as a git repository if it is not already one. */
 function ensureGitRepo(dir) {