akm-cli 0.9.0-beta.54 → 0.9.0-beta.56

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

@@ -3,13 +3,11 @@
 // file, You can obtain one at https://mozilla.org/MPL/2.0/.
 import fs from "node:fs";
 import path from "node:path";
-import { defineCommand } from "citty";
 import * as p from "../../cli/clack.js";
-import { output, runWithJsonErrors } from "../../cli/shared.js";
+import { defineJsonCommand, output } from "../../cli/shared.js";
 import { UsageError } from "../../core/errors.js";
 import { appendEvent } from "../../core/events.js";
 import { warn } from "../../core/warn.js";
-import { getHyphenatedBoolean } from "../../output/context.js";
 import { akmRemove } from "./installed-stashes.js";
 import { akmAdd } from "./source-add.js";
 import { addStash } from "./source-manage.js";
@@ -149,7 +147,7 @@ export async function auditInstalledStashForDangerousKeys(opts) {
     return { blocked: true, exitCode: 1 };
 }
 // ── Command definition ────────────────────────────────────────────────────────
-export const addCommand = defineCommand({
+export const addCommand = defineJsonCommand({
     meta: {
         name: "add",
         description: "Add a source (local directory, website, npm package, GitHub repo, git URL, or remote provider)",
@@ -181,48 +179,11 @@ export const addCommand = defineCommand({
         },
     },
     async run({ args }) {
-        await runWithJsonErrors(async () => {
-            const ref = args.ref.trim();
-            const allowInsecure = getHyphenatedBoolean(args, "allow-insecure");
-            const allowDangerousKeys = allowInsecure;
-            // URL with --provider → stash source (remote or git provider)
-            if (args.provider) {
-                if (shouldWarnOnPlainHttp(ref)) {
-                    if (!allowInsecure) {
-                        throw new UsageError("Source URL uses plain HTTP (not HTTPS). An on-path attacker could substitute a malicious payload. " +
-                            "Use https:// or pass --allow-insecure if you have explicitly accepted the risk.", "INVALID_FLAG_VALUE", "Re-run with `--allow-insecure` only after confirming the URL is trusted.");
-                    }
-                    warn("Warning: source URL uses plain HTTP (not HTTPS). --allow-insecure was set; an on-path attacker could substitute a malicious payload.");
-                }
-                let parsedOptions;
-                if (args.options) {
-                    try {
-                        const parsed = JSON.parse(args.options);
-                        if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
-                            throw new UsageError("--options must be a JSON object");
-                        }
-                        parsedOptions = parsed;
-                    }
-                    catch (err) {
-                        if (err instanceof UsageError)
-                            throw err;
-                        throw new UsageError("--options must be valid JSON");
-                    }
-                }
-                const result = addStash({
-                    target: ref,
-                    name: args.name,
-                    providerType: args.provider,
-                    options: parsedOptions,
-                    writable: args.writable,
-                });
-                appendEvent({
-                    eventType: "add",
-                    metadata: { target: ref, provider: args.provider, name: args.name ?? null, writable: args.writable === true },
-                });
-                output("add", result);
-                return;
-            }
+        const ref = args.ref.trim();
+        const allowInsecure = args["allow-insecure"];
+        const allowDangerousKeys = allowInsecure;
+        // URL with --provider → stash source (remote or git provider)
+        if (args.provider) {
             if (shouldWarnOnPlainHttp(ref)) {
                 if (!allowInsecure) {
                     throw new UsageError("Source URL uses plain HTTP (not HTTPS). An on-path attacker could substitute a malicious payload. " +
@@ -230,64 +191,99 @@ export const addCommand = defineCommand({
                 }
                 warn("Warning: source URL uses plain HTTP (not HTTPS). --allow-insecure was set; an on-path attacker could substitute a malicious payload.");
             }
-            const websiteOptions = buildWebsiteOptions(args);
-            if (args.type === "wiki") {
-                const { registerWikiSource } = await import("./source-add.js");
-                const result = await registerWikiSource({
-                    ref,
-                    name: args.name,
-                    options: Object.keys(websiteOptions).length > 0 ? websiteOptions : undefined,
-                    writable: args.writable,
-                });
-                appendEvent({
-                    eventType: "add",
-                    metadata: { target: ref, type: "wiki", name: args.name ?? null, writable: args.writable === true },
-                });
-                output("add", result);
-                return;
+            let parsedOptions;
+            if (args.options) {
+                try {
+                    const parsed = JSON.parse(args.options);
+                    if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+                        throw new UsageError("--options must be a JSON object");
+                    }
+                    parsedOptions = parsed;
+                }
+                catch (err) {
+                    if (err instanceof UsageError)
+                        throw err;
+                    throw new UsageError("--options must be valid JSON");
+                }
             }
-            const result = await akmAdd({
+            const result = addStash({
+                target: ref,
+                name: args.name,
+                providerType: args.provider,
+                options: parsedOptions,
+                writable: args.writable,
+            });
+            appendEvent({
+                eventType: "add",
+                metadata: { target: ref, provider: args.provider, name: args.name ?? null, writable: args.writable === true },
+            });
+            output("add", result);
+            return;
+        }
+        if (shouldWarnOnPlainHttp(ref)) {
+            if (!allowInsecure) {
+                throw new UsageError("Source URL uses plain HTTP (not HTTPS). An on-path attacker could substitute a malicious payload. " +
+                    "Use https:// or pass --allow-insecure if you have explicitly accepted the risk.", "INVALID_FLAG_VALUE", "Re-run with `--allow-insecure` only after confirming the URL is trusted.");
+            }
+            warn("Warning: source URL uses plain HTTP (not HTTPS). --allow-insecure was set; an on-path attacker could substitute a malicious payload.");
+        }
+        const websiteOptions = buildWebsiteOptions(args);
+        if (args.type === "wiki") {
+            const { registerWikiSource } = await import("./source-add.js");
+            const result = await registerWikiSource({
                 ref,
                 name: args.name,
-                overrideType: args.type,
                 options: Object.keys(websiteOptions).length > 0 ? websiteOptions : undefined,
                 writable: args.writable,
             });
             appendEvent({
                 eventType: "add",
-                metadata: {
-                    target: ref,
-                    name: args.name ?? null,
-                    overrideType: args.type ?? null,
-                    writable: args.writable === true,
-                },
+                metadata: { target: ref, type: "wiki", name: args.name ?? null, writable: args.writable === true },
             });
-            // ── Post-install env key audit ──────────────────────────────────────────
-            // Resolve the stash root from the install result and scan any env files
-            // for dangerous env var keys.  When findings are present the install is
-            // gated: TTY → interactive confirmation prompt; non-TTY without
-            // --allow-insecure → hard failure (exit 1).  Pass
-            // --allow-insecure to skip the prompt non-interactively.
-            const installedStashRoot = result.installed?.stashRoot ??
-                (result.sourceAdded && "stashRoot" in result.sourceAdded ? result.sourceAdded.stashRoot : undefined);
-            if (installedStashRoot) {
-                // Use the canonical installed id (most reliably resolved by akmRemove) rather
-                // than the raw user-supplied ref which may not match after URL normalisation.
-                const rollbackTarget = result.installed?.id ?? result.sourceAdded?.stashRoot ?? ref;
-                // The audit RETURNS its decision; we decide `process.exit` here, OUTSIDE
-                // any catch, so the abort cannot be lost to a swallowed exception (C3).
-                const decision = await auditInstalledStashForDangerousKeys({
-                    installedStashRoot,
-                    ref,
-                    allowDangerousKeys,
-                    rollbackTarget,
-                    isTTY: process.stdin.isTTY === true,
-                });
-                if (decision.blocked) {
-                    process.exit(decision.exitCode);
-                }
-            }
             output("add", result);
+            return;
+        }
+        const result = await akmAdd({
+            ref,
+            name: args.name,
+            overrideType: args.type,
+            options: Object.keys(websiteOptions).length > 0 ? websiteOptions : undefined,
+            writable: args.writable,
+        });
+        appendEvent({
+            eventType: "add",
+            metadata: {
+                target: ref,
+                name: args.name ?? null,
+                overrideType: args.type ?? null,
+                writable: args.writable === true,
+            },
         });
+        // ── Post-install env key audit ──────────────────────────────────────────
+        // Resolve the stash root from the install result and scan any env files
+        // for dangerous env var keys.  When findings are present the install is
+        // gated: TTY → interactive confirmation prompt; non-TTY without
+        // --allow-insecure → hard failure (exit 1).  Pass
+        // --allow-insecure to skip the prompt non-interactively.
+        const installedStashRoot = result.installed?.stashRoot ??
+            (result.sourceAdded && "stashRoot" in result.sourceAdded ? result.sourceAdded.stashRoot : undefined);
+        if (installedStashRoot) {
+            // Use the canonical installed id (most reliably resolved by akmRemove) rather
+            // than the raw user-supplied ref which may not match after URL normalisation.
+            const rollbackTarget = result.installed?.id ?? result.sourceAdded?.stashRoot ?? ref;
+            // The audit RETURNS its decision; we decide `process.exit` here, OUTSIDE
+            // any catch, so the abort cannot be lost to a swallowed exception (C3).
+            const decision = await auditInstalledStashForDangerousKeys({
+                installedStashRoot,
+                ref,
+                allowDangerousKeys,
+                rollbackTarget,
+                isTTY: process.stdin.isTTY === true,
+            });
+            if (decision.blocked) {
+                process.exit(decision.exitCode);
+            }
+        }
+        output("add", result);
     },
 });

package/dist/commands/sources/history.js

@@ -22,7 +22,7 @@ import { readEvents } from "../../core/events.js";
 import { isoToSqlite, parseSinceToIso } from "../../core/time.js";
 import { closeDatabase, openExistingDatabase } from "../../indexer/db/db.js";
 import { getUsageEvents } from "../../indexer/usage/usage-events.js";
-import { listProposals } from "../proposal/validators/proposals.js";
+import { listProposals } from "../proposal/repository.js";
 // Proposal lifecycle event types emitted by the proposal substrate (#225).
 const PROPOSAL_EVENT_TYPES = new Set(["promoted", "rejected"]);
 // ── Helpers ──────────────────────────────────────────────────────────────────

package/dist/commands/sources/schema-repair.js

@@ -23,7 +23,7 @@ import { resolveStandardsContext } from "../../core/standards/resolve-standards-
 import { info } from "../../core/warn.js";
 import { resolveAssetPath } from "../../indexer/walk/path-resolver.js";
 import { chatCompletion, parseEmbeddedJsonResponse } from "../../llm/client.js";
-import { createProposal, isProposalSkipped } from "../proposal/validators/proposals.js";
+import { createProposal, isProposalSkipped } from "../proposal/repository.js";
 // ── Constants ────────────────────────────────────────────────────────────────
 /** Minimum gap between schema-repair attempts on the same asset. */
 const SCHEMA_REPAIR_COOLDOWN_MS = 7 * 24 * 60 * 60 * 1000; // 7 days

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

@@ -23,7 +23,7 @@ import { loadConfig } from "../../core/config/config.js";
 import { UsageError } from "../../core/errors.js";
 import { appendEvent } from "../../core/events.js";
 import { resolveSourceEntries } from "../../indexer/search/search-source.js";
-import { getHyphenatedBoolean, parseFlagValue } from "../../output/context.js";
+import { parseFlagValue } from "../../output/context.js";
 import { resolveWritableOverride, saveGitStash } from "../../sources/providers/git.js";
 import { pkgVersion } from "../../version.js";
 import { akmHistory } from "./history.js";
@@ -125,8 +125,8 @@ export const upgradeCommand = defineJsonCommand({
             output("upgrade", check);
             return;
         }
-        const skipChecksum = getHyphenatedBoolean(args, "skip-checksum");
-        const skipPostUpgrade = getHyphenatedBoolean(args, "skip-post-upgrade");
+        const skipChecksum = args["skip-checksum"];
+        const skipPostUpgrade = args["skip-post-upgrade"];
         const result = await performUpgrade(check, { force: args.force, skipChecksum, skipPostUpgrade });
         output("upgrade", result);
     },

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

@@ -60,7 +60,7 @@ export const initCommand = defineJsonCommand({
         const legacyDir = parseFlagValue(process.argv, "--stashDir") ?? parseFlagValue(process.argv, "--stash-dir");
         const result = await akmInit({
             dir: args.dir ?? legacyDir,
-            setDefault: getHyphenatedBoolean(args, "set-default"),
+            setDefault: args["set-default"],
         });
         output("init", result);
     },

package/dist/commands/tasks/tasks-cli.js

@@ -15,7 +15,6 @@
 import { defineCommand } from "citty";
 import { parsePositiveIntFlag } from "../../cli/parse-args.js";
 import { defineGroupCommand, defineJsonCommand, output, runWithJsonErrors } from "../../cli/shared.js";
-import { getHyphenatedArg } from "../../output/context.js";
 import { detectServerDefault, registerDefaultTasks } from "./default-tasks.js";
 import { akmTasksAdd, akmTasksDoctor, akmTasksHistory, akmTasksList, akmTasksRemove, akmTasksRun, akmTasksSetEnabled, akmTasksShow, akmTasksSync, parseTaskRef, } from "./tasks.js";
 const tasksAddCommand = defineJsonCommand({
@@ -51,7 +50,7 @@ const tasksAddCommand = defineJsonCommand({
             profile: args.profile,
             params: args.params,
             name: args.name,
-            when_to_use: getHyphenatedArg(args, "when-to-use"),
+            when_to_use: args["when-to-use"],
             description: args.description,
             tags: args.tags
                 ? args.tags

package/dist/commands/wiki-cli.js

@@ -16,7 +16,6 @@ import { defineGroupCommand, defineJsonCommand, output, runWithJsonErrors } from
 import { resolveStashDir } from "../core/common.js";
 import { loadConfig, resolveConfiguredSources } from "../core/config/config.js";
 import { ConfigError, UsageError } from "../core/errors.js";
-import { getHyphenatedArg, getHyphenatedBoolean } from "../output/context.js";
 import { akmAgentDispatch } from "./agent/agent-dispatch.js";
 import { readKnowledgeInput } from "./read/knowledge.js";
 import { buildWebsiteOptions } from "./sources/add-cli.js";
@@ -108,7 +107,7 @@ const wikiRemoveCommand = defineJsonCommand({
             process.stderr.write("Aborted.\n");
             return;
         }
-        const withSources = getHyphenatedBoolean(args, "with-sources");
+        const withSources = args["with-sources"];
         const { removeWiki } = await import("../wiki/wiki.js");
         const { akmIndex } = await import("../indexer/indexer.js");
         const stashDir = resolveStashDir();
@@ -244,7 +243,7 @@ const wikiIngestCommand = defineJsonCommand({
         if (!profileName) {
             throw new UsageError("akm wiki ingest requires an agent profile. Pass --profile <name> or set defaults.agent in config.", "MISSING_REQUIRED_ARGUMENT", "Available profiles are listed under profiles.agent in your config. Run `akm config get profiles.agent` to inspect.");
         }
-        const timeoutMs = parsePositiveIntFlag(getHyphenatedArg(args, "timeout-ms"), "--timeout-ms");
+        const timeoutMs = parsePositiveIntFlag(args["timeout-ms"], "--timeout-ms");
         const model = getStringArg(args, "model");
         const { getDefaultLlmConfig } = await import("../core/config/config.js");
         const dispatchResult = await akmAgentDispatch({

package/dist/core/common.js

@@ -132,9 +132,9 @@ export function writeFileAtomic(target, content, mode) {
  *
  * Throws if no valid stash directory is found.
  */
-export function resolveStashDir(_options) {
+export function resolveStashDir(_options, env = process.env) {
     // 1. Env var override (for CI, scripts, testing)
-    const envDir = process.env.AKM_STASH_DIR?.trim();
+    const envDir = env.AKM_STASH_DIR?.trim();
     if (envDir) {
         return validateStashDir(envDir);
     }
@@ -143,7 +143,7 @@ export function resolveStashDir(_options) {
     if (configStashDir)
         return validateStashDir(configStashDir);
     // 3. Platform default — use it if it exists
-    const defaultDir = getDefaultStashDir();
+    const defaultDir = getDefaultStashDir(env);
     if (isValidDirectory(defaultDir)) {
         return defaultDir;
     }

package/dist/core/config/config-schema.js

@@ -846,6 +846,12 @@ export const AkmConfigShape = {
     semanticSearchMode: z.enum(["off", "auto"]).default("auto"),
     embedding: EmbeddingConnectionConfigSchema.optional(),
     index: IndexConfigSchema.optional(),
+    // The `installed[]` shape is OWNED by the registry (`InstalledStashEntry`):
+    // its `source` is the 4-value `InstallKind` produced by the registry ref
+    // parser, and installed entries never carry the extra passthrough keys. The
+    // schema still validates entries at runtime, but its OUTPUT type is pinned to
+    // the domain type so config consumers get the registry `InstalledStashEntry`
+    // (not a looser schema-local mirror) — the single-source-of-truth boundary.
     installed: z.array(InstalledStashEntrySchema).optional(),
     registries: z.array(RegistryConfigEntrySchema).optional(),
     sources: z.array(SourceConfigEntrySchema).optional(),

package/dist/core/deep-merge.js

@@ -0,0 +1,38 @@
+// 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/.
+/**
+ * Generic recursive object merge, extracted from the setup wizard (it is not
+ * setup-specific). Plain objects merge key-by-key; arrays and scalars replace
+ * wholesale. Used to apply a partial `--file` config over the existing config
+ * without dropping sibling subkeys.
+ */
+/** True for non-null, non-array plain objects. */
+export function isPlainObject(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+/**
+ * Recursively merge `incoming` into `base`: plain objects merge key-by-key,
+ * while arrays and scalars replace wholesale. A partial input therefore only
+ * updates the keys it carries and never drops sibling subkeys (e.g. a file
+ * containing `{ output: { format: "text" } }` leaves `output.detail` intact).
+ *
+ * `base` is treated as immutable — a fresh object graph is returned.
+ */
+export function deepMergeConfig(base, incoming) {
+    if (!isPlainObject(incoming))
+        return incoming;
+    const baseObj = isPlainObject(base) ? base : {};
+    const out = { ...baseObj };
+    for (const [key, value] of Object.entries(incoming)) {
+        if (value === undefined)
+            continue;
+        if (isPlainObject(value) && isPlainObject(baseObj[key])) {
+            out[key] = deepMergeConfig(baseObj[key], value);
+        }
+        else {
+            out[key] = value;
+        }
+    }
+    return out;
+}

package/dist/core/events.js

@@ -25,9 +25,10 @@
  * - `ts` is ISO-8601 (UTC, millisecond precision).
  */
 import path from "node:path";
+import { insertEvent, readStateEvents } from "../storage/repositories/events-repository.js";
 import { rethrowIfTestIsolationError } from "./errors.js";
 import { getDataDir } from "./paths.js";
-import { insertEvent, openStateDatabase, readStateEvents, withStateDb } from "./state-db.js";
+import { openStateDatabase, withStateDb } from "./state-db.js";
 import { error } from "./warn.js";
 /**
  * Legacy events.jsonl path — used only by the migration script

package/dist/core/logs-db.js

@@ -37,11 +37,9 @@
  *
  * @module logs-db
  */
-import fs from "node:fs";
 import path from "node:path";
-import { openDatabase } from "../storage/database.js";
 import { runMigrations as runSqliteMigrations } from "../storage/engines/sqlite-migrations.js";
-import { applyStandardPragmas } from "../storage/sqlite-pragmas.js";
+import { openManagedDatabase } from "../storage/managed-db.js";
 import { getDataDir } from "./paths.js";
 // ── Path helper ──────────────────────────────────────────────────────────────
 /**
@@ -72,16 +70,13 @@ export function getLogsDbPath() {
  */
 export function openLogsDatabase(dbPath) {
     const resolvedPath = dbPath ?? getLogsDbPath();
-    const dir = path.dirname(resolvedPath);
-    if (!fs.existsSync(dir)) {
-        fs.mkdirSync(dir, { recursive: true });
-    }
-    const db = openDatabase(resolvedPath);
-    // PRAGMAs must run before any DDL or DML. foreignKeys:false preserves this
-    // opener's historical behaviour — logs.db has never enforced foreign keys.
-    applyStandardPragmas(db, { dataDir: dir, foreignKeys: false });
-    runMigrations(db);
-    return db;
+    // foreignKeys:false preserves this opener's historical behaviour — logs.db
+    // has never enforced foreign keys.
+    return openManagedDatabase({
+        path: resolvedPath,
+        pragmas: { dataDir: path.dirname(resolvedPath), foreignKeys: false },
+        init: runMigrations,
+    });
 }
 // ── Migrations ───────────────────────────────────────────────────────────────
 /**

package/dist/core/paths.js

@@ -115,8 +115,8 @@ export function getConfigPath() {
     return path.join(getConfigDir(), "config.json");
 }
 // ── Cache directory ──────────────────────────────────────────────────────────
-export function getCacheDir() {
-    const override = process.env.AKM_CACHE_DIR?.trim();
+export function getCacheDir(env = process.env) {
+    const override = env.AKM_CACHE_DIR?.trim();
     if (override)
         return override;
     // Explicit XDG/platform overrides win before the transient-stash isolation
@@ -125,13 +125,13 @@ export function getCacheDir() {
     // as set, so the AKM_STASH_DIR transient rule does not silently move cache
     // writes away from where they pointed them.
     if (IS_WINDOWS) {
-        const localAppData = process.env.LOCALAPPDATA?.trim();
+        const localAppData = env.LOCALAPPDATA?.trim();
         if (localAppData)
             return path.join(localAppData, "akm");
-        const userProfile = process.env.USERPROFILE?.trim();
+        const userProfile = env.USERPROFILE?.trim();
         if (userProfile)
             return path.join(userProfile, "AppData", "Local", "akm");
-        const appData = process.env.APPDATA?.trim();
+        const appData = env.APPDATA?.trim();
         if (appData) {
             // Heuristic fallback: APPDATA points to %APPDATA% (Roaming), so
             // navigate to the sibling "Local" directory. This is typically
@@ -141,7 +141,7 @@ export function getCacheDir() {
         }
     }
     else {
-        const xdgCacheHome = process.env.XDG_CACHE_HOME?.trim();
+        const xdgCacheHome = env.XDG_CACHE_HOME?.trim();
         if (xdgCacheHome)
             return path.join(xdgCacheHome, "akm");
     }
@@ -150,7 +150,7 @@ export function getCacheDir() {
     // into `${AKM_STASH_DIR}/.akm/cache` so that config backups, registry-index
     // cache, and other regenerable artifacts do not pollute the user's host
     // ~/.cache/akm directory.
-    const stashOverride = process.env.AKM_STASH_DIR?.trim();
+    const stashOverride = env.AKM_STASH_DIR?.trim();
     if (stashOverride && isTransientStashPath(stashOverride)) {
         return path.join(stashOverride, ".akm", "cache");
     }
@@ -158,7 +158,7 @@ export function getCacheDir() {
         // None of LOCALAPPDATA / USERPROFILE / APPDATA were set above.
         throw new ConfigError("Unable to determine cache directory. Set LOCALAPPDATA, USERPROFILE, or APPDATA.", "CONFIG_DIR_UNRESOLVABLE");
     }
-    const home = process.env.HOME?.trim();
+    const home = env.HOME?.trim();
     if (!home)
         return path.join("/tmp", "akm-cache");
     return path.join(home, ".cache", "akm");
@@ -257,17 +257,17 @@ export function getTaskHistoryDir() {
     return path.join(getCacheDir(), "tasks", "history");
 }
 // ── Default stash directory ──────────────────────────────────────────────────
-export function getDefaultStashDir() {
-    const override = process.env.AKM_STASH_DIR?.trim();
+export function getDefaultStashDir(env = process.env) {
+    const override = env.AKM_STASH_DIR?.trim();
     if (override)
         return override;
     if (IS_WINDOWS) {
-        const userProfile = process.env.USERPROFILE?.trim();
+        const userProfile = env.USERPROFILE?.trim();
         if (userProfile)
             return path.join(userProfile, "Documents", "akm");
         return path.join("C:\\", "akm");
     }
-    const home = process.env.HOME?.trim();
+    const home = env.HOME?.trim();
     if (!home) {
         throw new ConfigError("Unable to determine default stash directory. Set HOME.", "STASH_DIR_NOT_FOUND");
     }
@@ -294,7 +294,7 @@ export function getDefaultStashDir() {
  * is fine even though `~/.local` is refused). This catches fat-finger
  * `--dir /` or `--dir ~` without preventing legitimate nested use.
  */
-export function assertSafeStashDir(stashDir) {
+export function assertSafeStashDir(stashDir, env = process.env) {
     const resolved = path.resolve(stashDir);
     // Filesystem root — POSIX and Windows drive roots.
     if (resolved === "/" || /^[A-Za-z]:[\\/]?$/.test(resolved)) {
@@ -334,7 +334,7 @@ export function assertSafeStashDir(stashDir) {
     // under bun test (which isolates HOME to a tempdir while os.homedir()
     // still returns the real user's home).
     const candidateHomes = new Set();
-    const envHome = (process.env.HOME ?? process.env.USERPROFILE)?.trim();
+    const envHome = (env.HOME ?? env.USERPROFILE)?.trim();
     if (envHome)
         candidateHomes.add(path.resolve(envHome));
     try {