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

package/dist/registry/providers/static-index.js

@@ -4,13 +4,11 @@
 import { fetchWithRetry, jsonWithByteCap, toErrorMessage } from "../../core/common.js";
 import { asString } from "../../integrations/github.js";
 import { fetchCachedJson } from "../../storage/repositories/registry-cache.js";
-import { registerProvider } from "../factory.js";
+import { registerRegistryProvider } from "../factory.js";
 import { buildInstallRef } from "../resolve.js";
 // ── Constants ───────────────────────────────────────────────────────────────
 /** Cache TTL in milliseconds (1 hour). */
 const CACHE_TTL_MS = 60 * 60 * 1000;
-/** Maximum age before cache is considered stale but still usable as fallback (7 days). */
-const CACHE_STALE_MS = 7 * 24 * 60 * 60 * 1000;
 // ── Provider class ──────────────────────────────────────────────────────────
 class StaticIndexProvider {
     type = "static-index";
@@ -20,25 +18,25 @@ class StaticIndexProvider {
     }
     async search(options) {
         const warnings = [];
-        const allKits = await this.loadAllKits(warnings);
-        const hits = scoreKits(allKits, options.query, options.limit);
+        const bundles = await this.loadBundles(warnings);
+        const hits = scoreBundles(bundles, options.query, options.limit);
         let assetHits;
         if (options.includeAssets) {
-            const scored = scoreAssets(allKits, options.query, options.limit);
+            const scored = scoreAssets(bundles, options.query, options.limit);
             if (scored.length > 0)
                 assetHits = scored;
         }
         return { hits, assetHits, warnings: warnings.length > 0 ? warnings : undefined };
     }
     // ── Internals ───────────────────────────────────────────────────────────
-    async loadAllKits(warnings) {
-        const allKits = [];
+    async loadBundles(warnings) {
+        const bundles = [];
         try {
             const index = await loadIndex(this.config);
             if (index) {
                 const regName = this.config.name;
                 for (const stash of index.stashes) {
-                    allKits.push({ stash, registryName: regName });
+                    bundles.push({ stash, registryName: regName });
                 }
             }
         }
@@ -46,18 +44,18 @@ class StaticIndexProvider {
             const label = this.config.name ? `${this.config.name} (${this.config.url})` : this.config.url;
             warnings.push(`Registry ${label}: ${toErrorMessage(err)}`);
         }
-        return allKits;
+        return bundles;
     }
 }
 // ── Self-register ───────────────────────────────────────────────────────────
-registerProvider("static-index", (config) => new StaticIndexProvider(config));
+registerRegistryProvider("static-index", (config) => new StaticIndexProvider(config));
 // ── Index loading with cache ────────────────────────────────────────────────
 async function loadIndex(entry) {
     return fetchCachedJson({
         cacheKey: entry.url,
         ttlMs: CACHE_TTL_MS,
         // Both the fresh hit and the stale fallback parse identically; a corrupt
-        // cache row lets JSON.parse throw out of the load (legacy behaviour).
+        // cache row lets JSON.parse throw out of the load.
         parseCache: (json) => parseRegistryIndex(JSON.parse(json)) ?? undefined,
         fetchFresh: async () => {
             const response = await fetchWithRetry(entry.url, undefined, { timeout: 10_000 });
@@ -77,12 +75,6 @@ async function loadIndex(entry) {
         },
     });
 }
-export function isCacheExpired(mtimeMs) {
-    return Date.now() - mtimeMs > CACHE_TTL_MS;
-}
-export function isCacheStale(mtimeMs) {
-    return Date.now() - mtimeMs > CACHE_STALE_MS;
-}
 // ── Index parsing (exported for reuse) ──────────────────────────────────────
 export function parseRegistryIndex(data) {
     if (typeof data !== "object" || data === null || Array.isArray(data))
@@ -97,13 +89,13 @@ export function parseRegistryIndex(data) {
     if (!Array.isArray(obj.stashes))
         return null;
     const stashes = obj.stashes.flatMap((raw) => {
-        const stash = parseStashEntry(raw);
+        const stash = parseBundleEntry(raw);
         return stash ? [stash] : [];
     });
     return { version: obj.version, updatedAt: obj.updatedAt, stashes };
 }
 // ── Stash entry parsing ───────────────────────────────────────────────────────
-function parseStashEntry(raw) {
+function parseBundleEntry(raw) {
     if (typeof raw !== "object" || raw === null || Array.isArray(raw))
         return null;
     const obj = raw;
@@ -113,9 +105,7 @@ function parseStashEntry(raw) {
     const source = asSource(obj.source);
     if (!id || !name || !ref || !source)
         return null;
-    // The legacy registry boolean `curated` is removed in v1. Legacy index JSON
-    // containing a `curated` key parses normally; the key is silently ignored
-    // (v1 spec §4.2, docs/migration/v1.md).
+    // Some published indexes include `curated`; it is intentionally ignored.
     return {
         id,
         name,
@@ -132,7 +122,7 @@ function parseStashEntry(raw) {
     };
 }
 // ── Scoring ─────────────────────────────────────────────────────────────────
-function scoreKits(stashes, query, limit) {
+function scoreBundles(stashes, query, limit) {
     const tokens = query.toLowerCase().split(/\s+/).filter(Boolean);
     const scored = [];
     for (const { stash, registryName } of stashes) {
@@ -247,7 +237,7 @@ function scoreAssets(stashes, query, limit) {
                         estimatedTokens: asset.estimatedTokens,
                         stash: { id: stash.id, name: stash.name },
                         registryName,
-                        action: `akm add ${installRef}`,
+                        action: `akm bundle add ${installRef}`,
                         score: Math.round(score * 1000) / 1000,
                     },
                     score,

package/dist/registry/resolve.js

@@ -9,6 +9,7 @@ import { fileURLToPath, pathToFileURL } from "node:url";
 import { fetchWithRetry, jsonWithByteCap } from "../core/common.js";
 import { NotFoundError, UsageError } from "../core/errors.js";
 import { asRecord, asString, GITHUB_API_BASE, githubHeaders } from "../integrations/github.js";
+import { isExactSemver, isSemverRange, maxSatisfying } from "./semver.js";
 /**
  * Validate that a URL is safe to pass to git.
  * Allowlists https:, http:, ssh:, git: schemes and git@ SSH shorthand.
@@ -108,13 +109,13 @@ function detectRegistrySearchId(ref) {
     const suggestedRef = segments.length >= 2 ? `github:${segments[0]}/${segments[1]}` : undefined;
     const lines = [
         `"${ref}" looks like a registry search result ID, not an installable ref.`,
-        `The "${prefix}:" prefix is a registry identifier and cannot be passed to \`akm add\`.`,
+        `The "${prefix}:" prefix is a registry identifier and cannot be passed to \`akm bundle add\`.`,
         "",
     ];
     if (suggestedRef) {
-        lines.push(`Try installing the source repository directly:`, `  akm add ${suggestedRef}`, "");
+        lines.push(`Try installing the source repository directly:`, `  akm bundle add ${suggestedRef}`, "");
     }
-    lines.push("Or search for the installable ref:", `  akm search "${segments.length > 2 ? segments[segments.length - 1] : rest}" --source registry`, "Then install using the installRef value from the result:", "  akm add github:owner/repo", "  akm add npm:package-name");
+    lines.push("Or search for the installable ref:", `  akm search "${segments.length > 2 ? segments[segments.length - 1] : rest}" --from registry`, "Then install using the installRef value from the result:", "  akm bundle add github:owner/repo", "  akm bundle add npm:package-name");
     return lines.join("\n");
 }
 export async function resolveRegistryArtifact(parsed) {
@@ -250,6 +251,16 @@ function isPathLikeRef(ref) {
     if (ref.startsWith("./") || ref.startsWith("../") || ref.startsWith(".\\") || ref.startsWith("..\\")) {
         return true;
     }
+    // R-007: a bare `owner/repo` (or `owner/repo#ref`) shorthand is ambiguous
+    // with a relative directory of the same shape, and is never an EXPLICIT
+    // local path the way `./owner/repo` is. Treating it as non-path here means
+    // `tryParseLocalRef` silently returns `undefined` (rather than throwing
+    // NotFoundError) when no such directory exists on disk, letting
+    // `parseRegistryRef`'s GitHub-shorthand fallback run instead. A directory
+    // that DOES exist with this shape is unaffected — `tryParseLocalRef`
+    // resolves it before the missing-path distinction ever matters.
+    if (looksLikeGithubOwnerRepo(ref))
+        return false;
     return ref.includes("/") || ref.includes("\\");
 }
 /** Default public npm registry host. */
@@ -317,9 +328,37 @@ export function validateNpmTarballUrl(tarballUrl, packageRef) {
         throw new UntrustedNpmTarballError(`npm package ${packageRef} returned a tarball URL on untrusted host "${host}" (allowed: ${allowed}).`);
     }
 }
+/**
+ * Resolve the npm registry base URL used to fetch package METADATA.
+ *
+ * R-035: `AKM_NPM_REGISTRY` previously only widened the trusted-tarball-host
+ * allowlist (see {@link trustedNpmTarballHosts}) while the metadata endpoint
+ * stayed hardcoded to the public registry — so an operator-configured mirror
+ * was never actually consulted, making the `UntrustedNpmTarballError.hint()`
+ * text below false. Honoring the override here for metadata too makes the
+ * hint true: installs really do resolve entirely against the configured
+ * mirror when it is set, mirroring how a private npm registry replaces the
+ * default wholesale (like npm's own `--registry` flag) rather than being
+ * merged with it.
+ */
+function npmMetadataRegistryBase() {
+    const override = process.env.AKM_NPM_REGISTRY?.trim();
+    if (override) {
+        try {
+            const url = new URL(override);
+            const base = `${url.origin}${url.pathname === "/" ? "" : url.pathname}`;
+            return base.replace(/\/+$/, "");
+        }
+        catch {
+            // Ignore unparseable overrides; fall back to the public registry.
+        }
+    }
+    return `https://${DEFAULT_NPM_REGISTRY_HOST}`;
+}
 async function resolveNpmArtifact(parsed) {
     const encodedName = encodeURIComponent(parsed.packageName);
-    const metadata = await fetchJson(`https://registry.npmjs.org/${encodedName}`);
+    const registryBase = npmMetadataRegistryBase();
+    const metadata = await fetchJson(`${registryBase}/${encodedName}`);
     const versions = asRecord(metadata.versions);
     const distTags = asRecord(metadata["dist-tags"]);
     const requested = parsed.requestedVersionOrTag;
@@ -560,96 +599,6 @@ function readGitValue(repoRoot, ...args) {
     const value = result.stdout.trim();
     return value || undefined;
 }
-function parseSemver(version) {
-    const match = version.match(/^(\d+)\.(\d+)\.(\d+)(?:-(.+))?$/);
-    if (!match)
-        return undefined;
-    return {
-        major: parseInt(match[1], 10),
-        minor: parseInt(match[2], 10),
-        patch: parseInt(match[3], 10),
-        prerelease: match[4],
-    };
-}
-function isExactSemver(version) {
-    return /^\d+\.\d+\.\d+(?:-[a-zA-Z0-9.+-]+)?$/.test(version);
-}
-function isSemverRange(input) {
-    return /^[~^>=<*]/.test(input) || /^\d+\.(\d+|\*)/.test(input);
-}
-function compareSemver(a, b) {
-    if (a.major !== b.major)
-        return a.major - b.major;
-    if (a.minor !== b.minor)
-        return a.minor - b.minor;
-    if (a.patch !== b.patch)
-        return a.patch - b.patch;
-    // Versions with prerelease are lower than release
-    if (a.prerelease && !b.prerelease)
-        return -1;
-    if (!a.prerelease && b.prerelease)
-        return 1;
-    return 0;
-}
-function semverGte(a, b) {
-    return compareSemver(a, b) >= 0;
-}
-function satisfiesRange(version, range) {
-    // Skip pre-release versions unless range specifically mentions one
-    if (version.prerelease && !range.includes("-"))
-        return false;
-    // ^1.2.3 — compatible with version: same major, >= minor.patch
-    const caretMatch = range.match(/^\^(\d+)\.(\d+)\.(\d+)(?:-(.+))?$/);
-    if (caretMatch) {
-        const rMajor = parseInt(caretMatch[1], 10);
-        const rMinor = parseInt(caretMatch[2], 10);
-        const rPatch = parseInt(caretMatch[3], 10);
-        if (version.major !== rMajor)
-            return false;
-        // ^0.x has special behavior: ^0.2.3 means >=0.2.3 <0.3.0
-        if (rMajor === 0) {
-            if (version.minor !== rMinor)
-                return false;
-            return version.patch >= rPatch;
-        }
-        return semverGte(version, { major: rMajor, minor: rMinor, patch: rPatch });
-    }
-    // ~1.2.3 — same major.minor, patch >= specified
-    const tildeMatch = range.match(/^~(\d+)\.(\d+)\.(\d+)(?:-(.+))?$/);
-    if (tildeMatch) {
-        const rMajor = parseInt(tildeMatch[1], 10);
-        const rMinor = parseInt(tildeMatch[2], 10);
-        const rPatch = parseInt(tildeMatch[3], 10);
-        return version.major === rMajor && version.minor === rMinor && version.patch >= rPatch;
-    }
-    // >=1.2.3
-    const gteMatch = range.match(/^>=(\d+)\.(\d+)\.(\d+)(?:-(.+))?$/);
-    if (gteMatch) {
-        const rMajor = parseInt(gteMatch[1], 10);
-        const rMinor = parseInt(gteMatch[2], 10);
-        const rPatch = parseInt(gteMatch[3], 10);
-        return semverGte(version, { major: rMajor, minor: rMinor, patch: rPatch });
-    }
-    // * or latest
-    if (range === "*" || range === "latest")
-        return true;
-    return false;
-}
-export function maxSatisfying(versions, range) {
-    const candidates = [];
-    for (const v of versions) {
-        const parsed = parseSemver(v);
-        if (!parsed)
-            continue;
-        if (satisfiesRange(parsed, range)) {
-            candidates.push({ version: v, parsed });
-        }
-    }
-    if (candidates.length === 0)
-        return undefined;
-    candidates.sort((a, b) => compareSemver(b.parsed, a.parsed));
-    return candidates[0].version;
-}
 // Cap JSON responses at 10 MB — npm package manifests and GitHub API
 // responses are typically a few KB; a compromised registry streaming
 // tens of MB of JSON is a DoS surface, not a feature.

package/dist/registry/semver.js

@@ -0,0 +1,43 @@
+// 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/.
+/**
+ * Registry semver engine (§4.6 dedup, WI-9.3).
+ *
+ * R-068 #3: this used to be a hand-rolled parse/compare/range implementation
+ * (a verbatim move from `./resolve.ts`) that only understood exact versions,
+ * `^x.y.z`, `~x.y.z`, `>=x.y.z`, and `*`/`latest`. Every OTHER valid npm range
+ * form was silently REJECTED by `satisfiesRange` even though the looser
+ * `isSemverRange` classifier correctly recognized it as a range: `1.2.x`,
+ * `>1.0.0`, `<2.0.0`, compound ranges (`>=1.0.0 <2.0.0`), partial carets
+ * (`^1.2`), OR-ranges (`a || b`), hyphen ranges (`1.2.3 - 2.3.4`), and plain
+ * exact versions used as a range. A silently-empty `maxSatisfying` result for
+ * a genuinely satisfiable range meant `akm bundle add pkg@<range>` could fail to
+ * resolve a real, installable version.
+ *
+ * `semver` (the npm package) is already a runtime dependency
+ * (`package.json`) — it was simply never imported from `src/`. This module
+ * now delegates to it directly instead of re-deriving a subset of its
+ * behavior, so every range form `semver` itself understands is supported.
+ *
+ * NOTE: `src/runtime.ts` has its own `semverOrder` with a DIFFERENT
+ * contract (engine-version ordering, not range satisfaction) — the two are
+ * intentionally not unified.
+ */
+import semver from "semver";
+/** True when `version` is an exact, fully-specified semver (not a range, wildcard, or partial version). */
+export function isExactSemver(version) {
+    return semver.valid(version) !== null;
+}
+/**
+ * True when `input` is a semver RANGE expression `maxSatisfying` can
+ * evaluate. Deliberately false for npm dist-tag conventions like `"latest"`
+ * — those are resolved via `dist-tags` lookup, not range satisfaction.
+ */
+export function isSemverRange(input) {
+    return semver.validRange(input) !== null;
+}
+/** Highest version in `versions` that satisfies `range`, or `undefined` if none match. */
+export function maxSatisfying(versions, range) {
+    return semver.maxSatisfying(versions, range) ?? undefined;
+}

package/dist/runtime.js

@@ -28,6 +28,7 @@ import path from "node:path";
 import { Readable } from "node:stream";
 import { pipeline } from "node:stream/promises";
 import { fileURLToPath } from "node:url";
+import { ResponseTooLargeError, readChunkWithDeadline } from "./core/common.js";
 /** True when running under the Bun runtime. Computed once at module load. */
 const isBun = !!process.versions?.bun;
 /** A CommonJS-style require usable from this ESM module on both runtimes. */
@@ -136,22 +137,77 @@ function stdinIterator() {
 }
 // ── File write ──────────────────────────────────────────────────────────────
 /**
- * Stream a `Response` (or its body) to `filePath`. On Bun uses `Bun.write`,
- * which natively streams a `Response` to disk; on Node pipes the response body
- * through `stream/promises.pipeline` so the archive is never fully buffered.
+ * Defensive ceiling on a streamed-to-disk download (1 GiB).
  */
-export async function writeResponseToFile(filePath, res) {
-    if (isBun) {
-        await bunGlobal().write(filePath, res);
-        return;
+export const MAX_STREAMED_DOWNLOAD_BYTES = 1024 * 1024 * 1024;
+/** Default overall wall-clock budget for streaming a download body (5 min). */
+export const STREAMED_DOWNLOAD_BODY_TIMEOUT_MS = 5 * 60_000;
+function writeStreamChunk(out, chunk) {
+    return new Promise((resolve, reject) => {
+        out.write(chunk, (err) => (err ? reject(err) : resolve()));
+    });
+}
+function endWriteStream(out) {
+    return new Promise((resolve, reject) => {
+        out.once("error", reject);
+        out.end(() => resolve());
+    });
+}
+/**
+ * Stream a `Response` body to `filePath` enforcing an explicit max-bytes cap
+ * and an overall body-read deadline.
+ *
+ * Refuses before reading when `Content-Length` exceeds the cap; otherwise
+ * streams chunk-by-chunk, aborting with {@link ResponseTooLargeError} the
+ * instant BYTES WRITTEN exceed the cap, or {@link BodyReadTimeoutError} when the
+ * body-read deadline passes. Uses the same runtime-agnostic reader loop on Bun
+ * and Node (correctness over the native `Bun.write` fast path, which offers no
+ * per-byte hook). On any failure the partial file is discarded and the stream
+ * cancelled.
+ */
+export async function writeResponseToFileCapped(filePath, res, options) {
+    const maxBytes = options?.maxBytes ?? MAX_STREAMED_DOWNLOAD_BYTES;
+    const bodyTimeoutMs = options?.bodyTimeoutMs ?? STREAMED_DOWNLOAD_BODY_TIMEOUT_MS;
+    const url = res.url || filePath;
+    const declared = Number(res.headers.get("content-length"));
+    if (Number.isFinite(declared) && declared > maxBytes) {
+        await res.body?.cancel?.().catch(() => undefined);
+        throw new ResponseTooLargeError(url, maxBytes, declared);
     }
-    if (res.body) {
-        const readable = Readable.fromWeb(res.body);
-        await pipeline(readable, createWriteStream(filePath));
+    const body = res.body;
+    if (!body) {
+        const buf = Buffer.from(await res.arrayBuffer());
+        if (buf.byteLength > maxBytes)
+            throw new ResponseTooLargeError(url, maxBytes, buf.byteLength);
+        await pipeline(Readable.from(buf), createWriteStream(filePath));
         return;
     }
-    const buf = Buffer.from(await res.arrayBuffer());
-    await pipeline(Readable.from(buf), createWriteStream(filePath));
+    const reader = body.getReader();
+    const out = createWriteStream(filePath);
+    const deadlineAt = Date.now() + bodyTimeoutMs;
+    let total = 0;
+    try {
+        while (true) {
+            const { done, value } = await readChunkWithDeadline(reader, deadlineAt, options?.signal, url, bodyTimeoutMs);
+            if (done)
+                break;
+            if (!value)
+                continue;
+            total += value.byteLength;
+            if (total > maxBytes)
+                throw new ResponseTooLargeError(url, maxBytes, total);
+            await writeStreamChunk(out, value);
+        }
+        await endWriteStream(out);
+    }
+    catch (err) {
+        out.destroy();
+        await reader.cancel().catch(() => undefined);
+        throw err;
+    }
+    finally {
+        reader.releaseLock?.();
+    }
 }
 // ── Hashing ─────────────────────────────────────────────────────────────────
 /**
@@ -237,6 +293,19 @@ export function sleepSync(ms) {
     }
     Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
 }
+/**
+ * Request a synchronous garbage collection. On Bun runs `Bun.gc(true)`; on
+ * Node a no-op (no portable forced-GC without --expose-gc). Used by the
+ * migrate-apply WAL conversion to finalize any zombie-closed bun:sqlite
+ * connection (statements not finalized before close keep the connection and
+ * its WAL shared memory alive until GC — issue #720) before concluding that
+ * ANOTHER process holds the database.
+ */
+export function requestGc() {
+    if (isBun) {
+        bunGlobal().gc(true);
+    }
+}
 /** Async sleep for `ms`. On Bun uses `Bun.sleep`; on Node a `setTimeout` promise. */
 export function sleep(ms) {
     if (isBun) {