akm-cli 0.7.5 → 0.8.0-rc.6

package/dist/core/parse.js

@@ -0,0 +1,158 @@
+// 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/.
+/**
+ * Shared JSON parsing utilities for LLM and agent output.
+ *
+ * Lives in `src/core/` so that both `src/llm/` and `src/integrations/agent/`
+ * can import without crossing the one-way boundary defined by v1 spec §9.7
+ * (agent/ must not import from llm/).
+ *
+ * The canonical implementation is ported from `src/llm/client.ts` (most
+ * complete version):
+ *   - Strips `<think>…</think>` reasoning blocks.
+ *   - Strips markdown code fences (``` or ~~~, optional language tag, with
+ *     trailing spaces on the fence line).
+ *   - Escapes unescaped control characters (actual \n, \r, \t bytes) inside
+ *     JSON string values so `JSON.parse` succeeds on outputs from local LLMs.
+ *   - Balanced-brace scanner handles both `{…}` and `[…]` top-level
+ *     structures (spawn.ts v0 only handled `{…}` — that was a bug).
+ */
+/**
+ * Strips `<think>…</think>` blocks from LLM output (for reasoning-capable
+ * models). Also strips leading/trailing whitespace.
+ */
+export function stripThinkBlocks(raw) {
+    return raw.replace(/<think>[\s\S]*?<\/think>/gi, "").trim();
+}
+/**
+ * Strips markdown code fences (``` or ~~~, with optional language tag).
+ * Handles fences with trailing spaces. Returns trimmed content.
+ */
+export function stripCodeFences(raw) {
+    return raw
+        .trim()
+        .replace(/^```(?:json)?\s*\n?/i, "")
+        .replace(/\n?```\s*$/i, "")
+        .trim();
+}
+/**
+ * Escapes unescaped control characters (actual \n, \r, \t bytes) inside JSON
+ * string values. Prevents `JSON.parse` failures from embedded newlines in
+ * local-LLM output.
+ */
+export function escapeJsonStringControls(raw) {
+    let out = "";
+    let inString = false;
+    let escaped = false;
+    for (let i = 0; i < raw.length; i++) {
+        const ch = raw[i];
+        if (escaped) {
+            out += ch;
+            escaped = false;
+            continue;
+        }
+        if (ch === "\\" && inString) {
+            out += ch;
+            escaped = true;
+            continue;
+        }
+        if (ch === '"') {
+            inString = !inString;
+            out += ch;
+            continue;
+        }
+        if (inString) {
+            if (ch === "\n") {
+                out += "\\n";
+                continue;
+            }
+            if (ch === "\r") {
+                out += "\\r";
+                continue;
+            }
+            if (ch === "\t") {
+                out += "\\t";
+                continue;
+            }
+        }
+        out += ch;
+    }
+    return out;
+}
+/**
+ * Full pipeline: stripThinkBlocks → stripCodeFences → escapeJsonStringControls
+ * → JSON.parse. Returns `undefined` on parse failure.
+ */
+export function parseJsonResponse(raw) {
+    try {
+        const cleaned = escapeJsonStringControls(stripCodeFences(stripThinkBlocks(raw)));
+        return JSON.parse(cleaned);
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Attempts `parseJsonResponse` first. On failure, scans for the first
+ * balanced `{ }` or `[ ]` structure in the text and attempts to parse that
+ * substring. Returns `undefined` if no valid JSON structure is found.
+ *
+ * Non-array results are preferred: if a `{…}` object is found first, it is
+ * returned immediately. Arrays (`[…]`) are captured as a fallback and
+ * returned only when no object was found.
+ */
+export function parseEmbeddedJsonResponse(raw) {
+    const direct = parseJsonResponse(raw);
+    if (direct !== undefined)
+        return direct;
+    const text = escapeJsonStringControls(stripCodeFences(stripThinkBlocks(raw)));
+    let arrayFallback;
+    for (let start = 0; start < text.length; start++) {
+        const opener = text[start];
+        if (opener !== "{" && opener !== "[")
+            continue;
+        const closer = opener === "{" ? "}" : "]";
+        let depth = 0;
+        let inString = false;
+        let escaped = false;
+        for (let i = start; i < text.length; i++) {
+            const ch = text[i];
+            if (inString) {
+                if (escaped) {
+                    escaped = false;
+                }
+                else if (ch === "\\") {
+                    escaped = true;
+                }
+                else if (ch === '"') {
+                    inString = false;
+                }
+                continue;
+            }
+            if (ch === '"') {
+                inString = true;
+                continue;
+            }
+            if (ch === opener)
+                depth += 1;
+            if (ch === closer) {
+                depth -= 1;
+                if (depth === 0) {
+                    try {
+                        const parsed = JSON.parse(text.slice(start, i + 1));
+                        if (!Array.isArray(parsed)) {
+                            return parsed;
+                        }
+                        arrayFallback ??= parsed;
+                        break;
+                    }
+                    catch {
+                        break;
+                    }
+                }
+            }
+        }
+    }
+    return arrayFallback;
+}

package/dist/core/paths.js

@@ -1,3 +1,6 @@
+// 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/.
 /**
  * Centralized path resolution for all akm directories.
  *
@@ -5,14 +8,93 @@
  * following XDG Base Directory conventions on Unix and standard locations
  * on Windows.
  */
+import os from "node:os";
 import path from "node:path";
+import { IS_WINDOWS } from "./common";
 import { ConfigError } from "./errors";
-const IS_WINDOWS = process.platform === "win32";
+/**
+ * Returns true when the current process appears to be running under
+ * `bun test` (either via the BUN_TEST sentinel Bun sets on the test
+ * worker, or via the conventional NODE_ENV=test).
+ *
+ * Used by getDataDir/getStateDir to enforce that every test which
+ * resolves a data/state directory ALSO sets XDG_DATA_HOME / XDG_STATE_HOME
+ * (or the AKM_*_DIR overrides) to temp directories. Without that
+ * pairing, tests silently write SQLite databases, lockfiles, and task
+ * history into the developer's real `~/.local/share/akm` /
+ * `~/.local/state/akm`.
+ */
+function isUnderBunTest(env) {
+    return env.BUN_TEST === "1" || env.NODE_ENV === "test";
+}
+/**
+ * Returns true when the given path is in a directory family the OS may
+ * reap (or that the user has clearly designated as a sandbox by virtue
+ * of placing it under `/tmp` or a macOS per-user temp dir). Used to
+ * decide whether `AKM_STASH_DIR=$tmpdir` should also isolate config +
+ * cache writes (so a test harness's `akm setup --yes --dir .` cannot
+ * silently clobber the user's `~/.config/akm/config.json`). See
+ * `docs/technical/incidents/2026-05-23-setup-clobbers-user-config.md`
+ * for the incident that motivated this.
+ *
+ * Both `/var/folders/*` and `/private/var/folders/*` are matched because
+ * `os.tmpdir()` on macOS may return either form depending on whether the
+ * caller has canonicalised the path (the realpath of `/var/folders` is
+ * `/private/var/folders`, but `path.resolve()` does not follow symlinks).
+ */
+export function isTransientStashPath(p) {
+    return (p.startsWith("/tmp/") ||
+        p === "/tmp" ||
+        p.startsWith("/var/tmp/") ||
+        p === "/var/tmp" ||
+        p.startsWith("/private/tmp/") ||
+        p.startsWith("/private/var/folders/") ||
+        p.startsWith("/var/folders/"));
+}
+/**
+ * Build a TEST_ISOLATION_MISSING ConfigError describing which env var(s)
+ * must be set so the data/state path resolves into a temp dir instead of
+ * the user's real XDG home.
+ */
+function testIsolationError(directoryKind) {
+    const xdgVar = directoryKind === "data" ? "XDG_DATA_HOME" : "XDG_STATE_HOME";
+    const akmVar = directoryKind === "data" ? "AKM_DATA_DIR" : "AKM_STATE_DIR";
+    return new ConfigError(`Refusing to resolve ${directoryKind} directory under bun test: neither ${xdgVar} nor ${akmVar} is set. ` +
+        "This guards against tests writing into the developer's real ~/.local/share/akm or ~/.local/state/akm. " +
+        `Set ${xdgVar} (or ${akmVar}) to a mktemp-d directory in this test's env block.`, "TEST_ISOLATION_MISSING");
+}
 // ── Config directory ─────────────────────────────────────────────────────────
 export function getConfigDir(env = process.env, platform = process.platform) {
     const override = env.AKM_CONFIG_DIR?.trim();
     if (override)
         return override;
+    // Explicit XDG override wins next — tests and operators that pre-arrange
+    // an isolated config dir via XDG_CONFIG_HOME (or %APPDATA% on Windows)
+    // must be honored as set, so the AKM_STASH_DIR transient-isolation rule
+    // below does not silently move config away from where they pointed it.
+    if (platform === "win32") {
+        const appData = env.APPDATA?.trim();
+        if (appData)
+            return path.join(appData, "akm");
+    }
+    else {
+        const xdgConfigHome = env.XDG_CONFIG_HOME?.trim();
+        if (xdgConfigHome)
+            return path.join(xdgConfigHome, "akm");
+    }
+    // Isolation safety: when AKM_STASH_DIR points at a transient/sandbox path
+    // (/tmp, /var/tmp, /private/var/folders) AND no explicit config dir
+    // override is set, route config writes into `${AKM_STASH_DIR}/.akm`
+    // instead of the user's host ~/.config/akm. This prevents the documented
+    // isolation pattern
+    //   AKM_DATA_DIR=/tmp/x AKM_STASH_DIR=/tmp/x akm setup --yes --dir .
+    // from silently clobbering the host config. See
+    // docs/technical/incidents/2026-05-23-setup-clobbers-user-config.md for the incident.
+    // Daily users with a persistent AKM_STASH_DIR=~/my-stash are unaffected.
+    const stashOverride = env.AKM_STASH_DIR?.trim();
+    if (stashOverride && isTransientStashPath(stashOverride)) {
+        return path.join(stashOverride, ".akm");
+    }
     if (platform === "win32") {
         const appData = env.APPDATA?.trim();
         if (appData)
@@ -40,6 +122,11 @@ export function getCacheDir() {
     const override = process.env.AKM_CACHE_DIR?.trim();
     if (override)
         return override;
+    // Explicit XDG/platform overrides win before the transient-stash isolation
+    // rule below — tests and operators that pre-arrange XDG_CACHE_HOME (or
+    // %LOCALAPPDATA% / %USERPROFILE% / %APPDATA% on Windows) must be honored
+    // 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();
         if (localAppData)
@@ -48,28 +135,150 @@ export function getCacheDir() {
         if (userProfile)
             return path.join(userProfile, "AppData", "Local", "akm");
         const appData = process.env.APPDATA?.trim();
-        if (!appData) {
-            throw new ConfigError("Unable to determine cache directory. Set LOCALAPPDATA, USERPROFILE, or APPDATA.", "CONFIG_DIR_UNRESOLVABLE");
+        if (appData) {
+            // Heuristic fallback: APPDATA points to %APPDATA% (Roaming), so
+            // navigate to the sibling "Local" directory. This is typically
+            // C:\Users\<name>\AppData\Roaming → C:\Users\<name>\AppData\Local\akm.
+            // Preferred: set LOCALAPPDATA to avoid this navigation.
+            return path.join(appData, "..", "Local", "akm");
         }
-        // Heuristic fallback: APPDATA points to %APPDATA% (Roaming), so navigate
-        // to the sibling "Local" directory. This is typically
-        // C:\Users\<name>\AppData\Roaming → C:\Users\<name>\AppData\Local\akm.
-        // Preferred: set LOCALAPPDATA to avoid this navigation.
-        return path.join(appData, "..", "Local", "akm");
-    }
-    const xdgCacheHome = process.env.XDG_CACHE_HOME?.trim();
-    if (xdgCacheHome)
-        return path.join(xdgCacheHome, "akm");
+    }
+    else {
+        const xdgCacheHome = process.env.XDG_CACHE_HOME?.trim();
+        if (xdgCacheHome)
+            return path.join(xdgCacheHome, "akm");
+    }
+    // Isolation safety (mirrors getConfigDir): when AKM_STASH_DIR points at a
+    // transient path AND no explicit cache override is set, route cache writes
+    // 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();
+    if (stashOverride && isTransientStashPath(stashOverride)) {
+        return path.join(stashOverride, ".akm", "cache");
+    }
+    if (IS_WINDOWS) {
+        // 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();
     if (!home)
         return path.join("/tmp", "akm-cache");
     return path.join(home, ".cache", "akm");
 }
+// ── Data directory ───────────────────────────────────────────────────────────
+/**
+ * Returns the XDG data directory for akm (`~/.local/share/akm` on Linux/macOS,
+ * `%LOCALAPPDATA%\akm\data` on Windows).
+ *
+ * Holds durable, non-regenerable application data: SQLite databases
+ * (index.db, workflow.db, state.db), akm.lock, and config-backups.
+ * Losing this directory loses history and installed state.
+ *
+ * Env overrides (in priority order):
+ *   AKM_DATA_DIR   — point to any directory
+ *   XDG_DATA_HOME  — (Linux/macOS) override the XDG base; akm subdir is appended
+ */
+export function getDataDir(env = process.env, platform = process.platform) {
+    const override = env.AKM_DATA_DIR?.trim();
+    if (override)
+        return override;
+    // Defense-in-depth: under `bun test`, refuse to fall through to the
+    // user's real $XDG_DATA_HOME / ~/.local/share/akm under any condition.
+    // Any test that needs a data dir must point it at a mktemp-d directory
+    // via XDG_DATA_HOME (or AKM_DATA_DIR). The previous carve-out that only
+    // fired when AKM_STASH_DIR was set was a loophole: tests calling
+    // openDatabase() or getDbPath() without overriding any env var silently
+    // wrote into ~/.local/share/akm/index.db (observed: 4,183-row
+    // registry-cache pollution). Item 5 of the 0.8.x critical-review plan.
+    if (isUnderBunTest(env) && !env.XDG_DATA_HOME?.trim()) {
+        throw testIsolationError("data");
+    }
+    if (platform === "win32") {
+        const localAppData = env.LOCALAPPDATA?.trim();
+        if (localAppData)
+            return path.join(localAppData, "akm", "data");
+        const userProfile = env.USERPROFILE?.trim();
+        if (userProfile)
+            return path.join(userProfile, "AppData", "Local", "akm", "data");
+        const appData = env.APPDATA?.trim();
+        if (!appData) {
+            throw new ConfigError("Unable to determine data directory. Set LOCALAPPDATA, USERPROFILE, or APPDATA.", "CONFIG_DIR_UNRESOLVABLE");
+        }
+        return path.join(appData, "..", "Local", "akm", "data");
+    }
+    const xdgDataHome = env.XDG_DATA_HOME?.trim();
+    if (xdgDataHome)
+        return path.join(xdgDataHome, "akm");
+    const home = env.HOME?.trim();
+    if (!home)
+        return path.join("/tmp", "akm-data");
+    return path.join(home, ".local", "share", "akm");
+}
+// ── State directory ──────────────────────────────────────────────────────────
+/**
+ * Returns the XDG state directory for akm (`~/.local/state/akm` on Linux/macOS,
+ * `%LOCALAPPDATA%\akm\state` on Windows).
+ *
+ * Holds runtime state and log-like files that persist across reboots but are
+ * less precious than $DATA: task history JSONL files, akm.lock.lck sentinel.
+ *
+ * Env overrides (in priority order):
+ *   AKM_STATE_DIR   — point to any directory
+ *   XDG_STATE_HOME  — (Linux/macOS) override the XDG base; akm subdir is appended
+ */
+export function getStateDir(env = process.env, platform = process.platform) {
+    const override = env.AKM_STATE_DIR?.trim();
+    if (override)
+        return override;
+    // Defense-in-depth: under `bun test`, refuse to fall through to the
+    // user's real $XDG_STATE_HOME / ~/.local/state/akm under any condition.
+    // See getDataDir above for rationale.
+    if (isUnderBunTest(env) && !env.XDG_STATE_HOME?.trim()) {
+        throw testIsolationError("state");
+    }
+    if (platform === "win32") {
+        const localAppData = env.LOCALAPPDATA?.trim();
+        if (localAppData)
+            return path.join(localAppData, "akm", "state");
+        const userProfile = env.USERPROFILE?.trim();
+        if (userProfile)
+            return path.join(userProfile, "AppData", "Local", "akm", "state");
+        const appData = env.APPDATA?.trim();
+        if (!appData) {
+            throw new ConfigError("Unable to determine state directory. Set LOCALAPPDATA, USERPROFILE, or APPDATA.", "CONFIG_DIR_UNRESOLVABLE");
+        }
+        return path.join(appData, "..", "Local", "akm", "state");
+    }
+    const xdgStateHome = env.XDG_STATE_HOME?.trim();
+    if (xdgStateHome)
+        return path.join(xdgStateHome, "akm");
+    const home = env.HOME?.trim();
+    if (!home)
+        return path.join("/tmp", "akm-state");
+    return path.join(home, ".local", "state", "akm");
+}
 export function getDbPath() {
-    return path.join(getCacheDir(), "index.db");
+    return path.join(getDataDir(), "index.db");
 }
 export function getWorkflowDbPath() {
-    return path.join(getCacheDir(), "workflow.db");
+    return path.join(getDataDir(), "workflow.db");
+}
+/** Path to the state.db file in $DATA. */
+export function getStateDbPathInDataDir() {
+    return path.join(getDataDir(), "state.db");
+}
+/** Path for the task history directory in $STATE (v2 location). */
+export function getTaskHistoryStateDir() {
+    return path.join(getStateDir(), "tasks", "history");
+}
+/** Path to the akm.lock file in $DATA. */
+export function getLockfilePath() {
+    return path.join(getDataDir(), "akm.lock");
+}
+/** Path to the akm.lock.lck write-sentinel in $DATA. */
+export function getLockfileLockPath() {
+    return path.join(getDataDir(), "akm.lock.lck");
 }
 export function getSemanticStatusPath() {
     return path.join(getCacheDir(), "semantic-status.json");
@@ -83,6 +292,13 @@ export function getRegistryIndexCacheDir() {
 export function getBinDir() {
     return path.join(getCacheDir(), "bin");
 }
+// ── Scheduled-task runtime directories (logs + history) ──────────────────────
+export function getTaskLogDir() {
+    return path.join(getCacheDir(), "tasks", "logs");
+}
+export function getTaskHistoryDir() {
+    return path.join(getCacheDir(), "tasks", "history");
+}
 // ── Default stash directory ──────────────────────────────────────────────────
 export function getDefaultStashDir() {
     const override = process.env.AKM_STASH_DIR?.trim();
@@ -100,3 +316,99 @@ export function getDefaultStashDir() {
     }
     return path.join(home, "akm");
 }
+// ── Stash directory safety check (#473) ──────────────────────────────────────
+/**
+ * Refuse stashDir values that would clobber a sensitive system path or the
+ * user's home directory itself. Called from `akm init`, `akm setup`, and the
+ * setup-wizard validator before any disk write.
+ *
+ * Refuses:
+ *   - The filesystem root (`/` or Windows drive root `C:\`)
+ *   - Common system roots (`/etc`, `/var`, `/usr`, `/usr/local`, `/opt`,
+ *     `/sys`, `/proc`, `/boot`, `/bin`, `/sbin`, `/lib`, `/lib64`, `/dev`,
+ *     `/run`, `/home`, `/root`, `/mnt`, `/media`,
+ *     `/Library`, `/System`, `/Applications`)
+ *   - The user's home directory itself (exact match — subdirs are fine)
+ *   - User-data dotfile parents: `~/.config`, `~/.local`, `~/.cache`,
+ *     `~/.ssh`, `~/.gnupg`, `~/.aws`, `~/.kube`, `~/.docker`,
+ *     and the macOS/Windows `~/Documents` and `~/Downloads` parents
+ *
+ * Subdirectories of any refused path are allowed (so `~/.local/share/akm-test`
+ * is fine even though `~/.local` is refused). This catches fat-finger
+ * `--dir /` or `--dir ~` without preventing legitimate nested use.
+ */
+export function assertSafeStashDir(stashDir) {
+    const resolved = path.resolve(stashDir);
+    // Filesystem root — POSIX and Windows drive roots.
+    if (resolved === "/" || /^[A-Za-z]:[\\/]?$/.test(resolved)) {
+        throw new ConfigError(`Refusing stashDir at filesystem root (${resolved}). Pick a subdirectory like ~/akm.`, "UNSAFE_STASH_DIR");
+    }
+    // System directories — exact match only.
+    const SYSTEM_ROOTS = new Set([
+        "/etc",
+        "/var",
+        "/var/tmp",
+        "/usr",
+        "/usr/local",
+        "/opt",
+        "/sys",
+        "/proc",
+        "/boot",
+        "/bin",
+        "/sbin",
+        "/lib",
+        "/lib64",
+        "/dev",
+        "/run",
+        "/home",
+        "/root",
+        "/mnt",
+        "/media",
+        "/Library",
+        "/System",
+        "/Applications",
+    ]);
+    if (SYSTEM_ROOTS.has(resolved)) {
+        throw new ConfigError(`Refusing stashDir at system path (${resolved}). Pick a path inside your home directory.`, "UNSAFE_STASH_DIR");
+    }
+    // User home — exact match only. Subdirs (~/akm, ~/work/stash) are fine.
+    // Check BOTH the env-controlled home and the OS-reported home, so the
+    // refusal can't be bypassed by unsetting HOME, and so it still fires
+    // 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();
+    if (envHome)
+        candidateHomes.add(path.resolve(envHome));
+    try {
+        const osHome = os.homedir();
+        if (osHome)
+            candidateHomes.add(path.resolve(osHome));
+    }
+    catch {
+        // os.homedir() can throw on misconfigured systems; ignore.
+    }
+    const HIDDEN_USER_PARENTS = [
+        ".config",
+        ".local",
+        ".cache",
+        ".ssh",
+        ".gnupg",
+        ".aws",
+        ".kube",
+        ".docker",
+        "Documents",
+        "Downloads",
+        "AppData",
+    ];
+    for (const home of candidateHomes) {
+        if (resolved === home) {
+            throw new ConfigError(`Refusing stashDir at your home directory (${resolved}). Pick a subdirectory like ~/akm.`, "UNSAFE_STASH_DIR");
+        }
+        for (const sub of HIDDEN_USER_PARENTS) {
+            if (resolved === path.join(home, sub)) {
+                throw new ConfigError(`Refusing stashDir at sensitive user directory (${resolved}). Pick a subdirectory or a dedicated workspace.`, "UNSAFE_STASH_DIR");
+            }
+        }
+    }
+}