akm-cli 0.5.0 → 0.6.0-rc2

package/dist/{asset-spec.js → core/asset-spec.js}

@@ -1,7 +1,7 @@
 import path from "node:path";
+import { buildWorkflowAction } from "../output/renderers";
 import { registerActionBuilder, registerTypeRenderer } from "./asset-registry";
 import { toPosix } from "./common";
-import { buildWorkflowAction } from "./renderers";
 const markdownSpec = {
     isRelevantFile: (fileName) => path.extname(fileName).toLowerCase() === ".md",
     toCanonicalName: (typeRoot, filePath) => {
@@ -129,8 +129,6 @@ export const ASSET_SPECS = ASSET_SPECS_INTERNAL;
 export function registerAssetType(type, spec) {
     ASSET_SPECS_INTERNAL[type] = spec;
     TYPE_DIRS[type] = spec.stashDir;
-    ASSET_TYPES.length = 0;
-    ASSET_TYPES.push(...getAssetTypes());
     // Auto-register renderer and action builder if provided in spec
     if (spec.rendererName) {
         registerTypeRenderer(type, spec.rendererName);
@@ -139,11 +137,20 @@ export function registerAssetType(type, spec) {
         registerActionBuilder(type, spec.actionBuilder);
     }
 }
+/**
+ * Remove a previously-registered asset type.
+ *
+ * Primarily used by tests for cleanup after `registerAssetType` calls so
+ * subsequent tests see a pristine type registry. Built-in types should not
+ * normally be deregistered at runtime.
+ */
+export function deregisterAssetType(type) {
+    delete ASSET_SPECS_INTERNAL[type];
+    delete TYPE_DIRS[type];
+}
 export function getAssetTypes() {
     return Object.keys(ASSET_SPECS_INTERNAL);
 }
-/** Warning: mutable array — stale if captured before `registerAssetType()` calls. Prefer `getAssetTypes()`. */
-export const ASSET_TYPES = getAssetTypes();
 export const TYPE_DIRS = Object.fromEntries(Object.entries(ASSET_SPECS_INTERNAL).map(([type, spec]) => [type, spec.stashDir]));
 export function isRelevantAssetFile(assetType, fileName) {
     return ASSET_SPECS[assetType]?.isRelevantFile(fileName) ?? false;
@@ -158,7 +165,7 @@ export function deriveCanonicalAssetNameFromStashRoot(assetType, stashRoot, file
     // When the first segment matches the canonical type dir (e.g. "agents"),
     // use it as the type root so canonical names are relative to it.
     // Otherwise fall back to stashRoot — this preserves the full relative path
-    // as the canonical name, which is correct for installed kits that live
+    // as the canonical name, which is correct for installed stashes that live
     // under custom directories (e.g. "tools/agents/svelte-file-editor").
     const typeRoot = firstSegment === TYPE_DIRS[assetType] ? path.join(stashRoot, firstSegment) : stashRoot;
     return deriveCanonicalAssetName(assetType, typeRoot, filePath);

package/dist/{common.js → core/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)