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

package/dist/core/common.js

@@ -4,29 +4,15 @@
 import crypto from "node:crypto";
 import fs from "node:fs";
 import path from "node:path";
-import { getAssetTypes, TYPE_DIRS } from "./asset/asset-spec.js";
 import { ConfigError } from "./errors.js";
 import { getConfigPath, getDefaultStashDir } from "./paths.js";
-// ── Types ───────────────────────────────────────────────────────────────────
-/**
- * The canonical catalog of built-in asset types.
- *
- * SINGLE SOURCE OF TRUTH: derived from the {@link ASSET_SPECS} registry in
- * `asset-spec.ts` rather than hand-maintained here. Before #490/WS7 this was a
- * hand-written literal array that had DRIFTED from the registry (it omitted
- * `task`, which the registry has always carried). Deriving from the registry
- * kills that drift — see `tests/asset-type-union-source.test.ts` for the
- * intentional-`task`-delta guard.
- *
- * Note: `AkmAssetType` stays a static literal union of the BUILT-IN types
- * (those present at module-eval time). Dynamically `registerAssetType`-d types
- * are accepted at runtime via {@link isAssetType} but are not part of the
- * static union — identical to the pre-WS7 contract.
- */
-export const ASSET_TYPES = Object.freeze([...getAssetTypes()]);
-export const ASSET_TYPE_SET = new Set(ASSET_TYPES);
 // ── Constants ───────────────────────────────────────────────────────────────
-export const IS_WINDOWS = process.platform === "win32";
+// Moved to the platform leaf so paths.ts can use it without a common↔paths
+// cycle (chunk-8 WI-8.6, DoD 11); re-exported here for the existing surface.
+export { IS_WINDOWS } from "./platform.js";
+export const MAX_CONFIG_FILE_BYTES = 1024 * 1024;
+export const MAX_LOCAL_METADATA_BYTES = 1024 * 1024;
+export const MAX_LOCK_METADATA_BYTES = 64 * 1024;
 export function isHttpUrl(value) {
     return !!value && /^https?:\/\//.test(value);
 }
@@ -44,20 +30,36 @@ export function isRemoteUrl(value) {
         value.startsWith("ssh://") ||
         value.startsWith("git://"));
 }
-// ── Validators ──────────────────────────────────────────────────────────────
-/**
- * Returns true if `type` is a known asset type — either a built-in from
- * {@link ASSET_TYPES} or one dynamically registered via `registerAssetType`.
- *
- * The type guard narrows to `AkmAssetType` for all built-in types. Dynamic
- * types (e.g. registered by plugins) are also accepted at runtime, but the
- * type system treats them as `AkmAssetType` via assertion since they are not
- * part of the static union.
- */
-export function isAssetType(type) {
-    return Object.hasOwn(TYPE_DIRS, type);
-}
 // ── Utilities ───────────────────────────────────────────────────────────────
+export function readTextFileDescriptorWithLimit(fd, maxBytes, label = "File", displayPath = "(open file)") {
+    const stat = fs.fstatSync(fd);
+    if (!stat.isFile())
+        throw new ConfigError(`${label} is not a regular file: ${displayPath}.`, "INVALID_CONFIG_FILE");
+    if (stat.size > maxBytes) {
+        throw new ConfigError(`${label} exceeds the ${maxBytes}-byte limit: ${displayPath}.`, "INVALID_CONFIG_FILE");
+    }
+    const buffer = Buffer.allocUnsafe(maxBytes + 1);
+    let total = 0;
+    while (total <= maxBytes) {
+        const bytesRead = fs.readSync(fd, buffer, total, maxBytes + 1 - total, null);
+        if (bytesRead === 0)
+            break;
+        total += bytesRead;
+    }
+    if (total > maxBytes) {
+        throw new ConfigError(`${label} exceeds the ${maxBytes}-byte limit: ${displayPath}.`, "INVALID_CONFIG_FILE");
+    }
+    return buffer.subarray(0, total).toString("utf8");
+}
+export function readTextFileWithLimit(filePath, maxBytes, label = "File") {
+    const fd = fs.openSync(filePath, "r");
+    try {
+        return readTextFileDescriptorWithLimit(fd, maxBytes, label, filePath);
+    }
+    finally {
+        fs.closeSync(fd);
+    }
+}
 /**
  * Write content to a file atomically via a temp file + rename.
  * Prevents partial-write corruption on crash.
@@ -78,60 +80,105 @@ export function isAssetType(type) {
  *   2. fsync the parent directory after rename, so the directory entry change
  *      is durable too. Some filesystems (FAT, certain FUSE mounts) don't
  *      support directory fsync; we ignore EINVAL/ENOTSUP so atomic writes
- *      don't fail on exotic mounts.
+ *      don't fail on those mounts. Windows does not support opening a
+ *      directory for fsync, so the directory-sync step is skipped there.
  */
 export function writeFileAtomic(target, content, mode) {
     const tmp = `${target}.tmp.${process.pid}.${crypto.randomBytes(8).toString("hex")}`;
-    const fd = fs.openSync(tmp, "w", mode ?? 0o600);
+    const data = typeof content === "string" ? Buffer.from(content) : content;
+    const fileMode = mode ?? 0o600;
+    let fd;
+    let tempOwned = false;
+    let renamed = false;
+    let failed = false;
+    let failure;
     try {
-        fs.writeSync(fd, typeof content === "string" ? Buffer.from(content) : content);
-        try {
-            fs.fdatasyncSync(fd);
-        }
-        catch {
-            // Best-effort: some pseudo-filesystems lack fdatasync. Fall through
-            // to closeSync — the rename below still preserves atomicity even if
-            // the data isn't durable, and the calling code's retry will recover.
+        fd = fs.openSync(tmp, "wx", fileMode);
+        tempOwned = true;
+        if (process.platform !== "win32")
+            fs.fchmodSync(fd, fileMode);
+        let offset = 0;
+        while (offset < data.byteLength) {
+            const written = fs.writeSync(fd, data, offset, data.byteLength - offset);
+            if (written <= 0)
+                throw new Error(`Could not make progress writing atomic temp file ${tmp}.`);
+            offset += written;
         }
+        fs.fdatasyncSync(fd);
+        fs.closeSync(fd);
+        fd = undefined;
+        fs.renameSync(tmp, target);
+        renamed = true;
+    }
+    catch (error) {
+        failed = true;
+        failure = error;
     }
     finally {
-        fs.closeSync(fd);
+        if (fd !== undefined) {
+            try {
+                fs.closeSync(fd);
+            }
+            catch (error) {
+                if (!failed) {
+                    failed = true;
+                    failure = error;
+                }
+            }
+        }
+        if (tempOwned && !renamed) {
+            try {
+                fs.unlinkSync(tmp);
+            }
+            catch (error) {
+                if (!failed && !hasErrnoCode(error, "ENOENT")) {
+                    failed = true;
+                    failure = error;
+                }
+            }
+        }
     }
-    fs.renameSync(tmp, target);
-    try {
-        const dirFd = fs.openSync(path.dirname(target), "r");
+    if (failed)
+        throw failure;
+    if (process.platform !== "win32") {
+        let dirFd;
         try {
-            fs.fsyncSync(dirFd);
+            dirFd = fs.openSync(path.dirname(target), "r");
+        }
+        catch (error) {
+            if (hasErrnoCode(error, "EINVAL") || hasErrnoCode(error, "ENOTSUP"))
+                return;
+            throw error;
+        }
+        try {
+            try {
+                fs.fsyncSync(dirFd);
+            }
+            catch (error) {
+                if (!hasErrnoCode(error, "EINVAL") && !hasErrnoCode(error, "ENOTSUP"))
+                    throw error;
+            }
         }
         finally {
             fs.closeSync(dirFd);
         }
     }
-    catch {
-        // Directory fsync is unsupported on FAT, some FUSE mounts, and Windows
-        // (where directories cannot be opened for read like POSIX). Silently
-        // ignore so writeFileAtomic remains portable.
-    }
 }
 /**
  * Resolve the stash directory using a three-level fallback chain:
- *   1. AKM_STASH_DIR environment variable (override for CI/scripts)
- *   2. stashDir field in config.json
+ *   1. AKM_BUNDLE_DIR environment variable (override for CI/scripts)
+ *   2. The configured default bundle path
  *   3. Platform default (~/akm or ~/Documents/akm on Windows)
  *
- * 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, env = process.env) {
+export function resolveStashDir(env = process.env) {
     // 1. Env var override (for CI, scripts, testing)
-    const envDir = env.AKM_STASH_DIR?.trim();
+    const envDir = env.AKM_BUNDLE_DIR?.trim();
     if (envDir) {
         return validateStashDir(envDir);
     }
-    // 2. Config file stashDir field
+    // 2. Configured default bundle path
     const configStashDir = readStashDirFromConfig();
     if (configStashDir)
         return validateStashDir(configStashDir);
@@ -140,8 +187,7 @@ export function resolveStashDir(_options, env = process.env) {
     if (isValidDirectory(defaultDir)) {
         return defaultDir;
     }
-    throw new ConfigError(`No stash directory found. Run "akm init" to create one at ${defaultDir}, ` +
-        `or set stashDir in ${getConfigPath()}.`, "STASH_DIR_NOT_FOUND");
+    throw new ConfigError(`No bundle directory found. Run "akm bundle create" to create one at ${defaultDir}.`, "STASH_DIR_NOT_FOUND");
 }
 function validateStashDir(raw) {
     const stashDir = path.resolve(raw);
@@ -150,10 +196,10 @@ function validateStashDir(raw) {
         stat = fs.statSync(stashDir);
     }
     catch {
-        throw new ConfigError(`Unable to read stash directory at "${stashDir}".`, "STASH_DIR_UNREADABLE");
+        throw new ConfigError(`Unable to read bundle directory at "${stashDir}".`, "STASH_DIR_UNREADABLE");
     }
     if (!stat.isDirectory()) {
-        throw new ConfigError(`Stash path must point to a directory: "${stashDir}".`, "STASH_DIR_NOT_A_DIRECTORY");
+        throw new ConfigError(`Bundle path must point to a directory: "${stashDir}".`, "STASH_DIR_NOT_A_DIRECTORY");
     }
     return stashDir;
 }
@@ -166,20 +212,75 @@ function isValidDirectory(dir) {
     }
 }
 /**
- * Read stashDir directly from config.json without pulling in the full config
- * module, to avoid circular dependencies.
+ * Read the primary stash path directly from config.json without pulling in the
+ * full config module, to avoid circular dependencies.
+ *
+ * Reads ONLY the 0.9.0 `bundles`/`defaultBundle` shape. A config still carrying
+ * the retired `stashDir`/`sources`/`installed` keys (with no usable bundles
+ * path) is an unmigrated config: this refuses it with the same `akm-migrate
+ * apply` hint the schema hard-reject uses (config-schema.ts), rather than
+ * silently honouring the retired key — so every `resolveStashDir` caller gets
+ * the coherent migrate posture instead of split-brain success.
  */
 function readStashDirFromConfig() {
     try {
         const configPath = getConfigPath();
-        const text = fs.readFileSync(configPath, "utf8");
+        const text = readTextFileWithLimit(configPath, MAX_CONFIG_FILE_BYTES, "Config file");
         const raw = JSON.parse(text);
-        if (typeof raw === "object" && raw !== null && typeof raw.stashDir === "string" && raw.stashDir.trim()) {
-            return raw.stashDir.trim();
+        if (typeof raw !== "object" || raw === null)
+            return undefined;
+        // 0.9.0 config-shape cutover (spec §10.1): the primary stash is the
+        // `defaultBundle`'s filesystem `path`. Read it directly (no config module
+        // import) so the primary-stash location survives the stashDir → bundles
+        // migration without a runtime rewire.
+        const bundles = raw.bundles;
+        const defaultBundle = raw.defaultBundle;
+        if (bundles &&
+            typeof bundles === "object" &&
+            typeof defaultBundle === "string" &&
+            bundles[defaultBundle] &&
+            typeof bundles[defaultBundle] === "object" &&
+            typeof bundles[defaultBundle].path === "string" &&
+            bundles[defaultBundle].path.trim()) {
+            const bundle = bundles[defaultBundle];
+            const bundlePath = bundle.path.trim();
+            if (bundle.components !== undefined) {
+                if (typeof bundle.components !== "object" || bundle.components === null) {
+                    throw new ConfigError("A bundle components map must contain exactly one component.", "INVALID_CONFIG_FILE");
+                }
+                const components = Object.values(bundle.components);
+                if (components.length !== 1) {
+                    throw new ConfigError("A bundle components map must contain exactly one component.", "INVALID_CONFIG_FILE");
+                }
+                const component = components[0];
+                if (typeof component === "object" && component !== null) {
+                    const componentConfig = component;
+                    if (typeof componentConfig.root !== "string")
+                        return bundlePath;
+                    const bundleRoot = path.resolve(bundlePath);
+                    const componentRoot = path.resolve(bundleRoot, componentConfig.root);
+                    if (!isWithin(componentRoot, bundleRoot)) {
+                        throw new ConfigError(`Component root "${componentConfig.root}" escapes bundle "${defaultBundle}".`, "INVALID_CONFIG_FILE");
+                    }
+                    return componentRoot;
+                }
+            }
+            return bundlePath;
+        }
+        // Retired pre-cutover shape with no usable bundles path: refuse with the
+        // migrate hint (matches the schema's hard-reject, config-schema.ts) instead
+        // of silently resolving the old key.
+        for (const key of ["stashDir", "sources", "installed"]) {
+            if (key in raw && raw[key] !== undefined) {
+                throw new ConfigError(`${key} is the retired pre-cutover source shape; run \`akm-migrate apply\` to convert it to bundles`, "INVALID_CONFIG_FILE");
+            }
         }
     }
-    catch {
-        // Config doesn't exist or is invalid — fall through
+    catch (err) {
+        // A retired-shape refusal must reach the caller; genuine missing/invalid
+        // config (read or JSON-parse failure) falls through to the platform default.
+        if (err instanceof ConfigError)
+            throw err;
     }
     return undefined;
 }
@@ -240,14 +341,34 @@ function normalizeFsPathForComparison(value) {
 /**
  * Fetch with an AbortController timeout.
  * Defaults to 30 seconds if no timeout is specified.
+ *
+ * SCOPE — connection + response-header phase only. `timeoutMs` bounds the time
+ * until `fetch` RESOLVES (i.e. until the status line + headers arrive); the
+ * timer is cleared once the `Response` is returned. It does NOT bound the time
+ * spent streaming the response BODY: a server can dribble body bytes forever
+ * under any per-byte limit. Callers that read the body MUST bound it
+ * themselves — pass `{ bodyTimeoutMs, signal }` to {@link readBodyWithByteCap}
+ * (in-memory reads) or use a capped streaming writer for downloads. That is the
+ * sanctioned "body-deadline mechanism"; a bounded header timeout here plus a
+ * bounded body read there gives a bounded TOTAL window.
+ *
+ * External `signal`: a caller-supplied `AbortSignal` aborts the in-flight
+ * request with the caller's own `reason`. The bridged listener is removed in
+ * `finally`, so once this function returns the caller's signal no longer
+ * governs the returned `Response`'s body stream — pass the SAME `signal` to the
+ * body-read helper so cancellation continues to apply to the body phase with
+ * the caller's reason. (A timeout and an external abort can never overwrite
+ * each other: whichever fires first aborts the controller, and a second
+ * `controller.abort()` is a no-op that preserves the first reason.)
  */
 export async function fetchWithTimeout(url, opts, timeoutMs = 30_000, signal) {
     const controller = new AbortController();
-    const timer = setTimeout(() => controller.abort(), timeoutMs);
+    const timer = timeoutMs === null ? undefined : setTimeout(() => controller.abort(), timeoutMs);
     const abortExternal = () => controller.abort(signal?.reason);
     if (signal) {
         if (signal.aborted) {
-            clearTimeout(timer);
+            if (timer)
+                clearTimeout(timer);
             controller.abort(signal.reason);
         }
         else {
@@ -269,7 +390,8 @@ export async function fetchWithTimeout(url, opts, timeoutMs = 30_000, signal) {
     finally {
         if (signal)
             signal.removeEventListener("abort", abortExternal);
-        clearTimeout(timer);
+        if (timer)
+            clearTimeout(timer);
     }
 }
 /**
@@ -342,6 +464,69 @@ export class ResponseTooLargeError extends Error {
         this.observedBytes = observedBytes;
     }
 }
+/**
+ * Thrown by {@link readBodyWithByteCap} / {@link readChunkWithDeadline} (and the
+ * capped disk writer) when streaming a response body exceeds the caller's
+ * overall body-read deadline. Distinct from a connection/header timeout
+ * (`fetchWithTimeout`) — this is the body-phase bound.
+ */
+export class BodyReadTimeoutError extends Error {
+    url;
+    timeoutMs;
+    constructor(url, timeoutMs) {
+        super(`Response body read exceeded ${timeoutMs}ms: ${url}`);
+        this.name = "BodyReadTimeoutError";
+        this.url = url;
+        this.timeoutMs = timeoutMs;
+    }
+}
+function bodyAbortError(signal, url) {
+    const reason = signal?.reason;
+    return reason instanceof Error ? reason : new Error(`Response body read aborted: ${url}`);
+}
+/**
+ * Read one chunk from `reader`, rejecting if the overall body deadline passes
+ * or `signal` aborts first. `deadlineAt` is an absolute epoch-ms instant (null
+ * = no deadline). Only races the pending `read()` so a stalled body cannot
+ * block forever; the CALLER cancels the reader on rejection. Throws
+ * {@link BodyReadTimeoutError} on deadline, or the signal's reason (or an
+ * AbortError) on external abort.
+ */
+export async function readChunkWithDeadline(reader, deadlineAt, signal, url, timeoutMs) {
+    if (signal?.aborted)
+        throw bodyAbortError(signal, url);
+    const remaining = deadlineAt === null ? null : deadlineAt - Date.now();
+    if (remaining !== null && remaining <= 0)
+        throw new BodyReadTimeoutError(url, timeoutMs);
+    if (remaining === null && !signal)
+        return reader.read();
+    return new Promise((resolve, reject) => {
+        let timer;
+        const cleanup = () => {
+            if (timer)
+                clearTimeout(timer);
+            signal?.removeEventListener("abort", onAbort);
+        };
+        const onAbort = () => {
+            cleanup();
+            reject(bodyAbortError(signal, url));
+        };
+        if (remaining !== null) {
+            timer = setTimeout(() => {
+                cleanup();
+                reject(new BodyReadTimeoutError(url, timeoutMs));
+            }, remaining);
+        }
+        signal?.addEventListener("abort", onAbort, { once: true });
+        reader.read().then((result) => {
+            cleanup();
+            resolve(result);
+        }, (err) => {
+            cleanup();
+            reject(err);
+        });
+    });
+}
 /**
  * Read a Response body as a UTF-8 string with a byte-count cap.
  *
@@ -350,9 +535,12 @@ export class ResponseTooLargeError extends Error {
  * `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).
+ * `maxBytes` defaults to {@link DEFAULT_RESPONSE_BYTE_CAP} (10 MB). `limits`
+ * bounds the body PHASE (duration + caller abort) that `fetchWithTimeout` does
+ * not cover; pass the same `signal` you gave `fetchWithTimeout` so caller
+ * cancellation keeps applying while the body streams.
  */
-export async function readBodyWithByteCap(response, maxBytes = DEFAULT_RESPONSE_BYTE_CAP) {
+export async function readBodyWithByteCap(response, maxBytes = DEFAULT_RESPONSE_BYTE_CAP, limits) {
     const url = response.url || "(unknown URL)";
     const contentLengthHeader = response.headers.get("content-length");
     if (contentLengthHeader) {
@@ -368,28 +556,35 @@ export async function readBodyWithByteCap(response, maxBytes = DEFAULT_RESPONSE_
         // 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);
+        const byteLength = Buffer.byteLength(text, "utf8");
+        if (byteLength > maxBytes)
+            throw new ResponseTooLargeError(url, maxBytes, byteLength);
         return text;
     }
     const reader = body.getReader();
     const chunks = [];
     let total = 0;
+    const bodyTimeoutMs = limits?.bodyTimeoutMs;
+    const deadlineAt = bodyTimeoutMs != null ? Date.now() + bodyTimeoutMs : null;
     try {
         while (true) {
-            const { done, value } = await reader.read();
+            const { done, value } = await readChunkWithDeadline(reader, deadlineAt, limits?.signal, url, bodyTimeoutMs ?? 0);
             if (done)
                 break;
             if (!value)
                 continue;
             total += value.byteLength;
-            if (total > maxBytes) {
-                await reader.cancel().catch(() => undefined);
+            if (total > maxBytes)
                 throw new ResponseTooLargeError(url, maxBytes, total);
-            }
             chunks.push(value);
         }
     }
+    catch (err) {
+        // Cancel the underlying stream on ANY failure (cap breach, body-read
+        // timeout, or caller abort) so the socket is released, not just on cap.
+        await reader.cancel().catch(() => undefined);
+        throw err;
+    }
     finally {
         reader.releaseLock?.();
     }
@@ -410,8 +605,8 @@ export async function readBodyWithByteCap(response, maxBytes = DEFAULT_RESPONSE_
  * 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);
+export async function jsonWithByteCap(response, maxBytes = DEFAULT_RESPONSE_BYTE_CAP, limits) {
+    const text = await readBodyWithByteCap(response, maxBytes, limits);
     return JSON.parse(text);
 }
 function parseRetryAfter(response) {