akm-cli 0.5.0 → 0.6.0-rc1

package/dist/common.js

@@ -24,21 +24,17 @@ export function isAssetType(type) {
  *   2. stashDir field in config.json
  *   3. Platform default (~/akm or ~/Documents/akm on Windows)
  *
- * WARNING: May write to config file as a side effect when AKM_STASH_DIR is set.
- * Specifically, when AKM_STASH_DIR is set and `options.readOnly` is not true,
- * this function calls `persistStashDirToConfig()` which writes the resolved
- * path into config.json on disk.
+ * Pure read: never writes to disk. The legacy `readOnly` option is accepted
+ * (and ignored) for one release cycle so older callers continue to compile;
+ * it can be removed in the next minor bump.
  *
  * Throws if no valid stash directory is found.
  */
-export function resolveStashDir(options) {
+export function resolveStashDir(_options) {
     // 1. Env var override (for CI, scripts, testing)
     const envDir = process.env.AKM_STASH_DIR?.trim();
     if (envDir) {
-        const resolved = validateStashDir(envDir);
-        if (!options?.readOnly)
-            persistStashDirToConfig(resolved);
-        return resolved;
+        return validateStashDir(envDir);
     }
     // 2. Config file stashDir field
     const configStashDir = readStashDirFromConfig();
@@ -50,7 +46,7 @@ export function resolveStashDir(options) {
         return defaultDir;
     }
     throw new ConfigError(`No stash directory found. Run "akm init" to create one at ${defaultDir}, ` +
-        `or set stashDir in ${getConfigPath()}.`);
+        `or set stashDir in ${getConfigPath()}.`, "STASH_DIR_NOT_FOUND");
 }
 function validateStashDir(raw) {
     const stashDir = path.resolve(raw);
@@ -59,10 +55,10 @@ function validateStashDir(raw) {
         stat = fs.statSync(stashDir);
     }
     catch {
-        throw new ConfigError(`Unable to read stash directory at "${stashDir}".`);
+        throw new ConfigError(`Unable to read stash directory at "${stashDir}".`, "STASH_DIR_UNREADABLE");
     }
     if (!stat.isDirectory()) {
-        throw new ConfigError(`Stash path must point to a directory: "${stashDir}".`);
+        throw new ConfigError(`Stash path must point to a directory: "${stashDir}".`, "STASH_DIR_NOT_A_DIRECTORY");
     }
     return stashDir;
 }
@@ -92,42 +88,6 @@ function readStashDirFromConfig() {
     }
     return undefined;
 }
-/**
- * Persist stashDir to config.json if not already set, so users can
- * transition away from relying on the AKM_STASH_DIR env var.
- *
- * WARNING: This function writes to disk (config.json). It is called as a side
- * effect of `resolveStashDir()` when AKM_STASH_DIR is set and `readOnly` is
- * not true. Callers that must not touch the filesystem should pass
- * `{ readOnly: true }` to `resolveStashDir()`.
- */
-function persistStashDirToConfig(stashDir) {
-    try {
-        const configPath = getConfigPath();
-        let raw = {};
-        try {
-            const text = fs.readFileSync(configPath, "utf8");
-            const parsed = JSON.parse(text);
-            if (typeof parsed === "object" && parsed !== null && !Array.isArray(parsed)) {
-                raw = parsed;
-            }
-        }
-        catch {
-            // No existing config or invalid — start fresh
-        }
-        if (!raw.stashDir) {
-            raw.stashDir = stashDir;
-            const dir = path.dirname(configPath);
-            fs.mkdirSync(dir, { recursive: true });
-            const tmpPath = `${configPath}.tmp.${process.pid}.${Math.random().toString(36).slice(2)}`;
-            fs.writeFileSync(tmpPath, `${JSON.stringify(raw, null, 2)}\n`, "utf8");
-            fs.renameSync(tmpPath, configPath);
-        }
-    }
-    catch {
-        // Non-fatal: best-effort persistence
-    }
-}
 export function toPosix(input) {
     return input.replace(/\\/g, "/");
 }
@@ -144,12 +104,39 @@ export function isWithin(candidate, root) {
     const rel = path.relative(normalizedRoot, normalizedCandidate);
     return rel === "" || (!rel.startsWith("..") && !path.isAbsolute(rel));
 }
+/**
+ * Resolve symlinks on `p`, walking up to the closest existing ancestor when
+ * `p` itself does not exist.  This ensures that comparisons between an
+ * existing directory and a not-yet-created child path inside it are
+ * consistent even when the directory hierarchy contains symlinks (e.g.
+ * macOS /tmp → /private/tmp, or a HOME that is itself a symlink).
+ */
 function safeRealpath(p) {
+    const resolved = path.resolve(p);
     try {
-        return fs.realpathSync(path.resolve(p));
+        return fs.realpathSync(resolved);
     }
     catch {
-        return path.resolve(p);
+        // Path doesn't exist — resolve symlinks on the nearest existing ancestor
+        // and reconstruct the full path from there.
+        const suffix = [];
+        let current = resolved;
+        for (;;) {
+            const parent = path.dirname(current);
+            if (parent === current) {
+                // Reached filesystem root without finding an existing entry.
+                return resolved;
+            }
+            suffix.unshift(path.basename(current));
+            current = parent;
+            try {
+                const realParent = fs.realpathSync(current);
+                return path.join(realParent, ...suffix);
+            }
+            catch {
+                // parent also doesn't exist; keep walking up
+            }
+        }
     }
 }
 function normalizeFsPathForComparison(value) {
@@ -207,6 +194,116 @@ export async function fetchWithRetry(url, init, options) {
 function shouldRetry(status) {
     return status === 429 || status >= 500;
 }
+/**
+ * Read stdin as UTF-8 text if something is piped in. Returns `undefined`
+ * when stdin is a TTY (no pipe) or when the piped content is empty.
+ */
+export function tryReadStdinText() {
+    if (process.stdin.isTTY)
+        return undefined;
+    const input = fs.readFileSync(0, "utf8");
+    return input.length > 0 ? input : undefined;
+}
+/**
+ * Default byte cap for untrusted network responses (10 MB).
+ *
+ * Applies to website scraping, registry index fetches, and any other
+ * response that is read into memory from a source the CLI does not fully
+ * control. A compromised or malicious endpoint that streams an unbounded
+ * response would otherwise exhaust RAM — this cap ensures the process
+ * aborts with a clean error instead of crashing.
+ */
+export const DEFAULT_RESPONSE_BYTE_CAP = 10 * 1024 * 1024;
+/**
+ * Thrown by {@link readBodyWithByteCap} and its helpers when a response
+ * body exceeds the caller's byte cap. Callers can catch this specifically
+ * to surface a targeted error to the user.
+ */
+export class ResponseTooLargeError extends Error {
+    url;
+    maxBytes;
+    observedBytes;
+    constructor(url, maxBytes, observedBytes) {
+        const observed = observedBytes === null ? "unknown" : `${observedBytes} bytes`;
+        super(`Response body exceeded ${maxBytes} bytes (observed: ${observed}): ${url}`);
+        this.name = "ResponseTooLargeError";
+        this.url = url;
+        this.maxBytes = maxBytes;
+        this.observedBytes = observedBytes;
+    }
+}
+/**
+ * Read a Response body as a UTF-8 string with a byte-count cap.
+ *
+ * Streams the body so we abort as soon as the cap is exceeded, without
+ * buffering the full response first. If the server sent a
+ * `Content-Length` larger than the cap, we refuse before reading any
+ * bytes. `response.body` is consumed and cancelled on cap breach.
+ *
+ * `maxBytes` defaults to {@link DEFAULT_RESPONSE_BYTE_CAP} (10 MB).
+ */
+export async function readBodyWithByteCap(response, maxBytes = DEFAULT_RESPONSE_BYTE_CAP) {
+    const url = response.url || "(unknown URL)";
+    const contentLengthHeader = response.headers.get("content-length");
+    if (contentLengthHeader) {
+        const declared = Number(contentLengthHeader);
+        if (Number.isFinite(declared) && declared > maxBytes) {
+            // Don't even start reading.
+            await response.body?.cancel?.().catch(() => undefined);
+            throw new ResponseTooLargeError(url, maxBytes, declared);
+        }
+    }
+    const body = response.body;
+    if (!body) {
+        // No streaming body available (e.g., some mock environments). Fall
+        // back to text() but still enforce the cap post-hoc.
+        const text = await response.text();
+        if (text.length > maxBytes)
+            throw new ResponseTooLargeError(url, maxBytes, text.length);
+        return text;
+    }
+    const reader = body.getReader();
+    const chunks = [];
+    let total = 0;
+    try {
+        while (true) {
+            const { done, value } = await reader.read();
+            if (done)
+                break;
+            if (!value)
+                continue;
+            total += value.byteLength;
+            if (total > maxBytes) {
+                await reader.cancel().catch(() => undefined);
+                throw new ResponseTooLargeError(url, maxBytes, total);
+            }
+            chunks.push(value);
+        }
+    }
+    finally {
+        reader.releaseLock?.();
+    }
+    if (chunks.length === 0)
+        return "";
+    if (chunks.length === 1)
+        return new TextDecoder().decode(chunks[0]);
+    const combined = new Uint8Array(total);
+    let offset = 0;
+    for (const chunk of chunks) {
+        combined.set(chunk, offset);
+        offset += chunk.byteLength;
+    }
+    return new TextDecoder().decode(combined);
+}
+/**
+ * Parse a Response body as JSON with a byte-count cap. A cheap wrapper
+ * around {@link readBodyWithByteCap}; prefer this for registry index
+ * fetches, GitHub API responses, and any other untrusted JSON source.
+ */
+export async function jsonWithByteCap(response, maxBytes = DEFAULT_RESPONSE_BYTE_CAP) {
+    const text = await readBodyWithByteCap(response, maxBytes);
+    return JSON.parse(text);
+}
 function parseRetryAfter(response) {
     const header = response.headers.get("retry-after");
     if (!header)

package/dist/config.js

@@ -1,3 +1,4 @@
+import { createHash } from "node:crypto";
 import fs from "node:fs";
 import path from "node:path";
 import { filterNonEmptyStrings } from "./common";
@@ -29,22 +30,56 @@ export function resetConfigCache() {
     cachedConfig = undefined;
     cachedUserConfig = undefined;
 }
+function hashString(text) {
+    // Simple, fast non-cryptographic hash (FNV-1a 32-bit) — sufficient to detect
+    // content changes between config writes when filesystem mtime resolution is
+    // too coarse to reflect rapid back-to-back writes (common in tests).
+    let hash = 0x811c9dc5;
+    for (let i = 0; i < text.length; i++) {
+        hash ^= text.charCodeAt(i);
+        hash = Math.imul(hash, 0x01000193);
+    }
+    return (hash >>> 0).toString(16);
+}
 export function loadUserConfig() {
     const configPath = getConfigPath();
     let stat;
     try {
         stat = fs.statSync(configPath);
-        if (cachedUserConfig && cachedUserConfig.path === configPath && cachedUserConfig.mtime === stat.mtimeMs) {
-            return cachedUserConfig.config;
-        }
     }
     catch {
         cachedUserConfig = undefined;
         return applyRuntimeEnvApiKeys({ ...DEFAULT_CONFIG });
     }
-    const config = mergeLoadedConfig(DEFAULT_CONFIG, readNormalizedConfig(configPath));
+    // Cache key combines mtimeMs + size + content hash. mtimeMs alone is unreliable
+    // when tests write multiple times within the filesystem mtime resolution
+    // window (often 1ms+). Reading + hashing on cache miss is cheap and ensures
+    // we never serve stale config.
+    let text;
+    try {
+        text = fs.readFileSync(configPath, "utf8");
+    }
+    catch {
+        cachedUserConfig = undefined;
+        return applyRuntimeEnvApiKeys({ ...DEFAULT_CONFIG });
+    }
+    const contentHash = hashString(text);
+    if (cachedUserConfig &&
+        cachedUserConfig.path === configPath &&
+        cachedUserConfig.mtime === stat.mtimeMs &&
+        cachedUserConfig.size === stat.size &&
+        cachedUserConfig.contentHash === contentHash) {
+        return cachedUserConfig.config;
+    }
+    const config = mergeLoadedConfig(DEFAULT_CONFIG, readNormalizedConfigFromText(configPath, text));
     const finalConfig = applyRuntimeEnvApiKeys(config);
-    cachedUserConfig = { config: finalConfig, path: configPath, mtime: stat.mtimeMs };
+    cachedUserConfig = {
+        config: finalConfig,
+        path: configPath,
+        mtime: stat.mtimeMs,
+        size: stat.size,
+        contentHash,
+    };
     return finalConfig;
 }
 export function loadConfig() {
@@ -66,6 +101,7 @@ export function loadConfig() {
 }
 export function saveConfig(config) {
     cachedConfig = undefined;
+    cachedUserConfig = undefined;
     const configPath = getConfigPath();
     const dir = path.dirname(configPath);
     fs.mkdirSync(dir, { recursive: true });
@@ -175,7 +211,13 @@ function pickKnownKeys(raw) {
     const registries = parseRegistriesConfig(raw.registries);
     if (registries)
         config.registries = registries;
-    if (typeof raw.disableGlobalStashes === "boolean") {
+    // Prefer the new `stashInheritance` field; fall back to the legacy boolean
+    // `disableGlobalStashes` so existing config files keep working unchanged.
+    if (raw.stashInheritance === "replace" || raw.stashInheritance === "merge") {
+        config.stashInheritance = raw.stashInheritance;
+    }
+    else if (typeof raw.disableGlobalStashes === "boolean") {
+        config.stashInheritance = raw.disableGlobalStashes ? "replace" : "merge";
         config.disableGlobalStashes = raw.disableGlobalStashes;
     }
     const stashes = parseStashesConfig(raw.stashes);
@@ -197,6 +239,19 @@ function readNormalizedConfig(configPath) {
     const expanded = raw ? expandEnvVars(raw) : undefined;
     return expanded ? pickKnownKeys(expanded) : undefined;
 }
+function readNormalizedConfigFromText(_configPath, text) {
+    let raw;
+    try {
+        raw = JSON.parse(stripJsonComments(text));
+    }
+    catch {
+        return undefined;
+    }
+    if (typeof raw !== "object" || raw === null || Array.isArray(raw))
+        return undefined;
+    const expanded = expandEnvVars(raw);
+    return pickKnownKeys(expanded);
+}
 function parseOutputConfig(value) {
     if (typeof value !== "object" || value === null || Array.isArray(value))
         return undefined;
@@ -428,11 +483,11 @@ function parseInstalledEntries(value) {
     if (!Array.isArray(value))
         return undefined;
     const entries = value
-        .map((entry) => parseInstalledKitEntry(entry))
+        .map((entry) => parseInstalledStashEntry(entry))
         .filter((entry) => entry !== undefined);
     return entries.length > 0 ? entries : undefined;
 }
-function parseInstalledKitEntry(value) {
+function parseInstalledStashEntry(value) {
     if (typeof value !== "object" || value === null || Array.isArray(value))
         return undefined;
     const obj = value;
@@ -470,6 +525,14 @@ function parseInstalledKitEntry(value) {
 function asNonEmptyString(value) {
     return typeof value === "string" && value ? value : undefined;
 }
+/**
+ * Validate a legacy lockfile/installed-entry source string.
+ *
+ * Restricted to the four kinds that the install pipeline produces
+ * (`"npm" | "github" | "git" | "local"`). The full {@link KitSource} union is
+ * wider, but persisted `installed[]` entries should never carry the runtime
+ * provider kinds (`"filesystem" | "website" | "openviking"`).
+ */
 function asKitSource(value) {
     if (value === "npm" || value === "github" || value === "git" || value === "local")
         return value;
@@ -550,13 +613,24 @@ function parseInstallAuditAllowedFinding(value) {
         finding.reason = reason;
     return finding;
 }
+/**
+ * Legacy stash type aliases that are normalized to canonical types at
+ * config-load time. Both "context-hub" and "github" were never distinct
+ * provider types — they were always git stashes — so we normalize them in
+ * memory to "git" without rewriting `config.json` on disk.
+ */
+const STASH_TYPE_ALIASES = {
+    "context-hub": "git",
+    github: "git",
+};
 function parseStashConfigEntry(value) {
     if (typeof value !== "object" || value === null || Array.isArray(value))
         return undefined;
     const obj = value;
-    const type = asNonEmptyString(obj.type);
-    if (!type)
+    const rawType = asNonEmptyString(obj.type);
+    if (!rawType)
         return undefined;
+    const type = STASH_TYPE_ALIASES[rawType] ?? rawType;
     const entry = { type };
     const entryPath = asNonEmptyString(obj.path);
     if (entryPath)
@@ -571,6 +645,8 @@ function parseStashConfigEntry(value) {
         entry.enabled = obj.enabled;
     if (typeof obj.writable === "boolean")
         entry.writable = obj.writable;
+    if (typeof obj.primary === "boolean")
+        entry.primary = obj.primary;
     if (typeof obj.options === "object" && obj.options !== null && !Array.isArray(obj.options)) {
         entry.options = obj.options;
     }
@@ -579,6 +655,124 @@ function parseStashConfigEntry(value) {
         entry.wikiName = wikiName;
     return entry;
 }
+// ── StashEntry runtime construction ─────────────────────────────────────────
+/**
+ * Synthesize a stable identifier when a {@link StashConfigEntry} omits its
+ * `name`. Uses a short hash of the discriminating fields so two equivalent
+ * entries collapse to the same generated name.
+ */
+function deriveStashEntryName(entry) {
+    if (entry.name)
+        return entry.name;
+    const seed = JSON.stringify({
+        type: entry.type,
+        path: entry.path ?? null,
+        url: entry.url ?? null,
+    });
+    const hash = createHash("sha256").update(seed).digest("hex").slice(0, 8);
+    return `${entry.type}-${hash}`;
+}
+/**
+ * Convert a persisted {@link StashConfigEntry} into the runtime
+ * {@link StashSource} discriminated union. Returns `undefined` when the
+ * entry is missing the fields its provider type requires (e.g. a
+ * `filesystem` entry with no `path`); callers should drop or warn for those.
+ *
+ * Unknown provider types fall back to `{ type: "filesystem", path: ... }` so
+ * legacy aliases (`"context-hub"`, `"github"` for git) still produce a usable
+ * runtime value when a path/url is supplied.
+ */
+export function parseStashEntrySource(entry) {
+    switch (entry.type) {
+        case "filesystem":
+            return entry.path ? { type: "filesystem", path: entry.path } : undefined;
+        case "git":
+        case "context-hub":
+        case "github":
+            // Note: a configured `github` provider entry historically meant "git
+            // repo over the GitHub web URL", not the registry-install `github:` ref.
+            return entry.url ? { type: "git", url: entry.url } : undefined;
+        case "website":
+            return entry.url
+                ? {
+                    type: "website",
+                    url: entry.url,
+                    ...(typeof entry.options?.maxPages === "number" ? { maxPages: entry.options.maxPages } : {}),
+                }
+                : undefined;
+        case "openviking":
+            return entry.url ? { type: "openviking", url: entry.url } : undefined;
+        case "npm":
+            // Persisted `npm` stash entries are unusual but supported for symmetry.
+            return entry.path ? { type: "npm", package: entry.path } : undefined;
+        default:
+            // Unknown provider — best-effort fallback so callers still get something.
+            return entry.path ? { type: "filesystem", path: entry.path } : undefined;
+    }
+}
+/**
+ * Build the full ordered list of runtime {@link StashEntry} values from a
+ * loaded {@link AkmConfig}. Order is the canonical iteration order:
+ *
+ *   1. The entry marked `primary: true` (or, as a backwards-compat shim,
+ *      a synthetic filesystem entry built from the top-level `stashDir`).
+ *   2. Remaining `stashes[]` entries in declared order.
+ *   3. Legacy `installed[]` entries, mapped into runtime entries.
+ *
+ * Entries with `enabled: false` are still emitted — callers decide whether
+ * to honour the flag (mirrors how `installed[]` entries have always been
+ * unconditional). Entries that fail {@link parseStashEntrySource} are
+ * dropped silently.
+ */
+export function resolveStashEntries(config) {
+    const entries = [];
+    const stashes = config.stashes ?? [];
+    // (1) Primary entry: explicit `primary: true` wins; fall back to top-level stashDir.
+    let primary = stashes.find((entry) => entry.primary === true);
+    if (!primary && config.stashDir) {
+        primary = { type: "filesystem", path: config.stashDir, primary: true };
+    }
+    if (primary) {
+        const runtime = toStashEntry(primary, true);
+        if (runtime)
+            entries.push(runtime);
+    }
+    // (2) Declared stashes (skip the primary entry — already added).
+    for (const entry of stashes) {
+        if (entry === primary)
+            continue;
+        const runtime = toStashEntry(entry, false);
+        if (runtime)
+            entries.push(runtime);
+    }
+    // (3) Legacy installed[] entries.
+    for (const installed of config.installed ?? []) {
+        entries.push({
+            name: installed.id,
+            type: "filesystem",
+            source: { type: "filesystem", path: installed.stashRoot },
+            enabled: true,
+            writable: installed.writable,
+            ...(installed.wikiName ? { wikiName: installed.wikiName } : {}),
+        });
+    }
+    return entries;
+}
+function toStashEntry(persisted, isPrimary) {
+    const source = parseStashEntrySource(persisted);
+    if (!source)
+        return undefined;
+    return {
+        name: deriveStashEntryName(persisted),
+        type: persisted.type,
+        source,
+        ...(persisted.enabled !== undefined ? { enabled: persisted.enabled } : {}),
+        ...(persisted.writable !== undefined ? { writable: persisted.writable } : {}),
+        ...(isPrimary || persisted.primary ? { primary: true } : {}),
+        ...(persisted.options ? { options: persisted.options } : {}),
+        ...(persisted.wikiName ? { wikiName: persisted.wikiName } : {}),
+    };
+}
 function parseRegistryConfigEntry(value) {
     if (typeof value !== "object" || value === null || Array.isArray(value))
         return undefined;
@@ -621,7 +815,8 @@ function mergeInstallAuditConfig(base, override) {
  * Scalar fields follow normal override semantics. Known nested objects are
  * deep-merged so project config files can override individual fields without
  * clobbering sibling settings. `stashes` are additive by default, but a later
- * layer can set `disableGlobalStashes: true` to drop inherited stashes first.
+ * layer can set `stashInheritance: "replace"` (or the legacy
+ * `disableGlobalStashes: true`) to drop inherited stashes first.
  */
 function mergeLoadedConfig(base, override) {
     if (!override)
@@ -642,7 +837,11 @@ function mergeLoadedConfig(base, override) {
     if (base.security && override.security) {
         merged.security = mergeSecurityConfig(base.security, override.security);
     }
-    if (override.disableGlobalStashes) {
+    // The new `stashInheritance` field wins; fall back to the legacy
+    // `disableGlobalStashes` boolean so old config files behave identically.
+    const replaceStashes = override.stashInheritance === "replace" ||
+        (override.stashInheritance === undefined && override.disableGlobalStashes === true);
+    if (replaceStashes) {
         merged.stashes = [...(override.stashes ?? [])];
     }
     else if (override.stashes) {
@@ -713,7 +912,19 @@ function isFile(filePath) {
 }
 function getFileSignatureToken(filePath) {
     try {
-        return String(fs.statSync(filePath).mtimeMs);
+        const stat = fs.statSync(filePath);
+        // mtimeMs alone is unreliable on filesystems with low-resolution mtime
+        // (HFS+, some network FS, or very fast back-to-back writes in tests).
+        // Combine mtime + size + content hash so the signature actually changes
+        // when content does.
+        let contentHash = "";
+        try {
+            contentHash = hashString(fs.readFileSync(filePath, "utf8"));
+        }
+        catch {
+            // ignore — fall back to stat-only signature
+        }
+        return `${stat.mtimeMs}:${stat.size}:${contentHash}`;
     }
     catch {
         return "missing";

package/dist/create-provider-registry.js

@@ -2,7 +2,7 @@
  * Generic factory-map utility.
  *
  * Creates a lightweight registry that maps string keys to factory functions.
- * Both registry-factory.ts (kit discovery) and stash-provider-factory.ts
+ * Both registry-factory.ts (stash discovery) and stash-provider-factory.ts
  * (stash source providers) are built on this utility.
  */
 export function createProviderRegistry() {