akm-cli 0.9.16 → 0.9.17-alpha.10

package/dist/registry/factory.js

@@ -1,30 +1,15 @@
 // 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 provider factory map.
- *
- * Maps registry provider type identifiers (e.g. "static-index", "skills-sh")
- * to factory functions that create RegistryProvider instances.
- *
- * "Registry" here refers to the stash discovery registries (static index files,
- * skills.sh API) — not to be confused with the source provider factory map in
- * `sources/provider-factory.ts` or the installed-source operations in
- * `installed-stashes.ts`.
- *
- * Factories use the `RegistryProviderFactory` type owned by
- * `src/registry/providers/types.ts`.
- */
-import { createProviderRegistry } from "./create-provider-registry.js";
 // ── Factory map ─────────────────────────────────────────────────────────────
-const registry = createProviderRegistry();
+const factories = new Map();
 export function registerRegistryProvider(type, factory) {
-    registry.register(type, factory);
+    factories.set(type, factory);
 }
 export function resolveRegistryProviderFactory(type) {
-    return registry.resolve(type);
+    return factories.get(type) ?? null;
 }
 /** Test-only seam: removes a registration made with {@link registerRegistryProvider}. */
 export function unregisterRegistryProvider(type) {
-    registry.unregister(type);
+    factories.delete(type);
 }

package/dist/registry/network.js

@@ -1,247 +1,93 @@
 // 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/.
-import { isIP } from "node:net";
-import { backoffDelay, computeRetryDelay, abortableDelay as sharedAbortableDelay, shouldRetry } from "../core/common.js";
-import { bareHostname, classifyNetworkAddress, classifyNetworkHostname, resolveHostnameAddresses, } from "../core/network-policy.js";
-import { assertRegistryPinnedTransportAvailable, requestRegistryAddressPinned, } from "./pinned-transport.js";
-export { requestRegistryAddressPinned } from "./pinned-transport.js";
-export class RegistryNetworkError extends Error {
-    code = "REGISTRY_NETWORK_POLICY";
-    constructor(message) {
-        super(message);
-        this.name = "RegistryNetworkError";
-    }
-}
-const GITHUB_API_ORIGIN = "https://api.github.com";
-const MAX_REGISTRY_REDIRECTS = 8;
-const MAX_REGISTRY_RETRY_DELAY_MS = 30_000;
-let allowRegistryFixturesForTests = false;
-let registryHostnameResolverForTests;
-let registryPinnedRequestForTests;
-/**
- * Single outbound HTTP boundary for registry metadata requests.
- *
- * Every retry and redirect returns through this function's resolve, validate,
- * and pinned-connect sequence before another request can start.
- */
-export async function fetchRegistryResponse(rawUrl, init, options, redirectCount = 0) {
+import { abortableDelay, backoffDelay, computeRetryDelay, jsonWithByteCap, ResponseTooLargeError, shouldRetry, toErrorMessage, } from "../core/common.js";
+import { ConfigError, NotFoundError, TransientError } from "../core/errors.js";
+import { formatRegistryUrl } from "../core/registry-url.js";
+const DEFAULT_TIMEOUT_MS = 30_000;
+const DEFAULT_RETRIES = 2;
+const DEFAULT_JSON_BYTE_CAP = 10 * 1024 * 1024;
+const MAX_RETRY_DELAY_MS = 30_000;
+/** Fetch a registry URL. Resolves only to a 2xx response; every other outcome throws an `AkmError`. */
+export async function fetchRegistry(rawUrl, options = {}) {
     const url = parseRegistryUrl(rawUrl);
-    const response = await requestRegistryHop(url, init, options);
-    if (!isRedirect(response.status))
-        return response;
-    if (options.policy.kind === "github-api") {
-        await cancelRegistryResponse(response);
-        throw new RegistryNetworkError("GitHub API registry metadata policy does not permit redirects");
-    }
-    if (redirectCount >= MAX_REGISTRY_REDIRECTS) {
-        await cancelRegistryResponse(response);
-        throw new RegistryNetworkError(`Too many redirects while fetching registry metadata from ${url.origin}`);
-    }
-    const location = response.headers.get("location");
-    if (!location) {
-        await cancelRegistryResponse(response);
-        throw new RegistryNetworkError(`Redirect from registry host ${url.hostname} did not include Location`);
-    }
-    await cancelRegistryResponse(response);
-    let nextUrl;
-    try {
-        nextUrl = new URL(location, url);
-    }
-    catch {
-        throw new RegistryNetworkError(`Redirect from registry host ${url.hostname} included an invalid Location`);
-    }
-    const nextInit = redirectInit(init, url, nextUrl, response.status);
-    return fetchRegistryResponse(nextUrl.toString(), nextInit, options, redirectCount + 1);
-}
-async function requestRegistryHop(url, init, options) {
-    const maxRetries = options.retries ?? 3;
-    const injectedTransport = options.requestPinnedForTesting ?? registryPinnedRequestForTests;
-    if (!injectedTransport)
-        assertRegistryPinnedTransportAvailable();
-    const transport = injectedTransport ?? requestRegistryAddressPinned;
-    for (let attempt = 0; attempt <= maxRetries; attempt += 1) {
-        const attemptDeadline = Date.now() + options.timeoutMs;
-        const allowPrivate = privateNetworkAllowed(url, options);
-        const addresses = await validatedRegistryAddresses(url, options, allowPrivate, options.timeoutMs, init?.signal);
-        if (Date.now() >= attemptDeadline) {
-            throw new RegistryNetworkError(`Registry request to ${url.hostname} attempt deadline expired before transport could start`);
-        }
-        const address = addresses[attempt % addresses.length];
-        if (!address) {
-            throw new RegistryNetworkError(`Refusing registry request to ${url.hostname}: no validated address available`);
-        }
+    const timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+    const retries = options.retries ?? DEFAULT_RETRIES;
+    for (let attempt = 0;; attempt += 1) {
+        // AbortSignal.timeout() does not keep the event loop alive, and it keeps
+        // covering the body after this function returns.
+        const timeout = AbortSignal.timeout(timeoutMs);
+        const signal = options.signal ? AbortSignal.any([options.signal, timeout]) : timeout;
+        let response;
         try {
-            const remainingMs = attemptDeadline - Date.now();
-            if (remainingMs <= 0) {
-                throw new RegistryNetworkError(`Registry request to ${url.hostname} attempt deadline expired before transport could start`);
-            }
-            const response = await transport(url, address, init, remainingMs);
-            if (attempt < maxRetries && shouldRetry(response.status)) {
-                const delay = computeRetryDelay(response, attempt, { maxDelayMs: MAX_REGISTRY_RETRY_DELAY_MS });
-                await cancelRegistryResponse(response);
-                await abortableDelay(delay, init?.signal);
-                continue;
-            }
-            return response;
+            response = await fetch(rawUrl, { headers: options.headers, signal, redirect: "follow" });
         }
         catch (error) {
-            if (attempt >= maxRetries || init?.signal?.aborted)
+            if (options.signal?.aborted)
                 throw error;
-            await abortableDelay(backoffDelay(attempt, undefined, MAX_REGISTRY_RETRY_DELAY_MS), init?.signal);
+            if (attempt < retries) {
+                await abortableDelay(backoffDelay(attempt, undefined, MAX_RETRY_DELAY_MS), options.signal);
+                continue;
+            }
+            const reason = timeout.aborted ? `timed out after ${timeoutMs}ms` : `failed: ${toErrorMessage(error)}`;
+            throw new TransientError(`Registry request to ${url.host} ${reason} (${rawUrl})`, "REGISTRY_UNREACHABLE");
         }
+        if (attempt < retries && shouldRetry(response.status)) {
+            await cancelBody(response);
+            await abortableDelay(computeRetryDelay(response, attempt, { maxDelayMs: MAX_RETRY_DELAY_MS }), options.signal);
+            continue;
+        }
+        if (response.ok)
+            return response;
+        await cancelBody(response);
+        throw statusError(response.status, rawUrl);
     }
-    throw new Error("Registry retry loop is unreachable");
-}
-function parseRegistryUrl(rawUrl) {
-    let url;
-    try {
-        url = new URL(rawUrl);
-    }
-    catch {
-        throw new RegistryNetworkError("Registry request URL is invalid");
-    }
-    if (url.protocol !== "http:" && url.protocol !== "https:") {
-        throw new RegistryNetworkError(`Registry requests require HTTP(S), not ${url.protocol || "an empty scheme"}`);
-    }
-    if (url.username || url.password) {
-        throw new RegistryNetworkError(`Registry request URL must not contain embedded credentials: ${url.hostname}`);
-    }
-    return url;
 }
-function privateNetworkAllowed(url, options) {
-    if (options.allowPrivateHostsForTesting === true)
-        return true;
-    if (options.policy.kind !== "npm-api" || !options.policy.allowPrivateRegistryOrigin)
-        return false;
-    const expectedOrigin = normalizedOrigin(options.policy.registryOrigin, "npm registry");
-    return url.origin === expectedOrigin;
-}
-async function validatedRegistryAddresses(url, options, allowPrivate, timeoutMs, signal) {
-    assertPolicyOrigin(url, options.policy);
-    const hostname = bareHostname(url.hostname);
-    const literal = isIP(hostname) !== 0;
-    const hostClass = classifyNetworkHostname(hostname);
-    assertAllowedClass(hostClass, hostname, allowPrivate);
-    if (literal)
-        return [hostname];
-    let addresses;
+/** `fetchRegistry` plus a JSON body read under a byte cap. */
+export async function fetchRegistryJson(rawUrl, options = {}) {
+    const response = await fetchRegistry(rawUrl, options);
     try {
-        addresses = await resolveAddressesWithDeadline(hostname, options.resolveHostname ?? registryHostnameResolverForTests, timeoutMs, signal);
+        return await jsonWithByteCap(response, options.maxBytes ?? DEFAULT_JSON_BYTE_CAP, {
+            bodyTimeoutMs: options.timeoutMs ?? DEFAULT_TIMEOUT_MS,
+            signal: options.signal,
+        });
     }
     catch (error) {
-        if (error instanceof RegistryNetworkError || signal?.aborted)
+        if (options.signal?.aborted)
             throw error;
-        throw new RegistryNetworkError(`Refusing registry request to ${hostname}: DNS resolution failed`);
-    }
-    if (addresses.length === 0) {
-        throw new RegistryNetworkError(`Refusing registry request to ${hostname}: hostname resolved to no addresses`);
-    }
-    for (const address of addresses) {
-        const addressClass = classifyNetworkAddress(address);
-        assertAllowedClass(addressClass, `${hostname} (${address})`, allowPrivate, true);
-    }
-    return addresses;
-}
-async function resolveAddressesWithDeadline(hostname, resolver, timeoutMs, signal) {
-    if (signal?.aborted)
-        throw signal.reason ?? new Error("Registry request aborted");
-    return new Promise((resolve, reject) => {
-        let settled = false;
-        const cleanup = () => {
-            clearTimeout(timer);
-            signal?.removeEventListener("abort", onAbort);
-        };
-        const finish = (action) => {
-            if (settled)
-                return;
-            settled = true;
-            cleanup();
-            action();
-        };
-        const onAbort = () => finish(() => reject(signal?.reason ?? new Error("Registry request aborted")));
-        const timer = setTimeout(() => finish(() => reject(new RegistryNetworkError(`Refusing registry request to ${hostname}: DNS resolution timed out after ${timeoutMs}ms`))), Math.max(1, timeoutMs));
-        signal?.addEventListener("abort", onAbort, { once: true });
-        void resolveHostnameAddresses(hostname, resolver).then((addresses) => finish(() => resolve(addresses)), (error) => finish(() => reject(error)));
-    });
-}
-function assertPolicyOrigin(url, policy) {
-    if (policy.kind === "github-api" && url.origin !== GITHUB_API_ORIGIN) {
-        throw new RegistryNetworkError(`GitHub API origin policy rejected registry request to ${url.origin}`);
-    }
-    if (policy.kind === "npm-api") {
-        const expected = normalizedOrigin(policy.registryOrigin, "npm registry");
-        if (url.origin !== expected && classifyNetworkHostname(url.hostname) !== "public") {
-            throw new RegistryNetworkError(`npm registry redirect policy rejected non-public origin ${url.origin}`);
+        if (error instanceof ResponseTooLargeError || error instanceof SyntaxError) {
+            throw new NotFoundError(`Registry response from ${rawUrl} is not usable: ${toErrorMessage(error)}`, "REGISTRY_RESPONSE_INVALID");
         }
+        throw new TransientError(`Registry response from ${rawUrl} could not be read: ${toErrorMessage(error)}`, "REGISTRY_UNREACHABLE");
     }
 }
-function normalizedOrigin(rawUrl, label) {
+function parseRegistryUrl(rawUrl) {
+    let url;
     try {
-        return new URL(rawUrl).origin;
+        url = new URL(rawUrl);
     }
     catch {
-        throw new RegistryNetworkError(`Configured ${label} origin is invalid`);
+        throw new ConfigError(`Registry URL is not a valid URL: ${formatRegistryUrl(rawUrl)}`, "REGISTRY_URL_INVALID");
     }
-}
-function assertAllowedClass(addressClass, destination, allowPrivate, resolved = false) {
-    if (addressClass === "public")
-        return;
-    if (allowPrivate && (addressClass === "private" || addressClass === "loopback"))
-        return;
-    const qualifier = resolved ? "resolves to " : "is ";
-    throw new RegistryNetworkError(`Refusing registry request: ${destination} ${qualifier}non-public ${addressClass} destination`);
-}
-function redirectInit(init, currentUrl, nextUrl, status) {
-    if (!init)
-        return init;
-    const headers = new Headers(init.headers);
-    if (currentUrl.origin !== nextUrl.origin) {
-        headers.delete("authorization");
-        headers.delete("cookie");
-        headers.delete("proxy-authorization");
+    if (url.protocol !== "http:" && url.protocol !== "https:") {
+        throw new ConfigError(`Registry URL must use http(s), not ${url.protocol || "an empty scheme"}: ${formatRegistryUrl(rawUrl)}`, "REGISTRY_URL_INVALID");
     }
-    const method = (init.method ?? "GET").toUpperCase();
-    const switchToGet = ((status === 301 || status === 302) && method === "POST") ||
-        (status === 303 && method !== "GET" && method !== "HEAD");
-    if (!switchToGet)
-        return { ...init, headers };
-    for (const name of ["content-encoding", "content-language", "content-length", "content-location", "content-type"]) {
-        headers.delete(name);
+    if (url.username || url.password) {
+        throw new ConfigError(`Registry URL must not embed credentials: ${url.origin}`, "REGISTRY_URL_INVALID");
     }
-    return { ...init, method: "GET", body: undefined, headers };
-}
-function isRedirect(status) {
-    return status === 301 || status === 302 || status === 303 || status === 307 || status === 308;
+    return url;
 }
-/** Release a terminal response body so pinned helper/socket resources cannot linger. */
-export async function cancelRegistryResponse(response) {
+function statusError(status, rawUrl) {
+    const message = `Registry request failed (HTTP ${status}) for ${rawUrl}`;
+    if (shouldRetry(status))
+        return new TransientError(message, "REGISTRY_UNREACHABLE");
+    if (status === 404 || status === 410)
+        return new NotFoundError(message, "REGISTRY_NOT_FOUND");
+    const hint = status === 401 || status === 403
+        ? "The registry refused the request. For GitHub, set GITHUB_TOKEN or sign in with `gh auth login`; akm's registry providers send no other credentials."
+        : undefined;
+    return new NotFoundError(message, "REGISTRY_RESPONSE_INVALID", hint);
+}
+async function cancelBody(response) {
     await response.body?.cancel().catch(() => undefined);
 }
-/** Test-only visibility for the server-controlled Retry-After clamp. */
-export function _registryRetryDelayForTests(response, attempt) {
-    return computeRetryDelay(response, attempt, { maxDelayMs: MAX_REGISTRY_RETRY_DELAY_MS });
-}
-function abortableDelay(ms, signal) {
-    return sharedAbortableDelay(ms, signal, "Registry request aborted");
-}
-/** Existing local HTTP fixtures remain available only inside the test process. */
-export function allowPrivateRegistryFixtureForTests(rawUrl) {
-    if (!allowRegistryFixturesForTests)
-        return false;
-    try {
-        const url = new URL(rawUrl);
-        const hostClass = classifyNetworkHostname(url.hostname);
-        const port = Number.parseInt(url.port, 10);
-        return hostClass === "loopback" && Number.isInteger(port) && port >= 1024 && port <= 65_535;
-    }
-    catch {
-        return false;
-    }
-}
-/** Test-harness seam; production composition never enables these overrides. */
-export function _setRegistryNetworkOverridesForTests(overrides) {
-    allowRegistryFixturesForTests = overrides?.allowLoopbackFixtures === true;
-    registryHostnameResolverForTests = overrides?.resolveHostname;
-    registryPinnedRequestForTests = overrides?.requestPinned;
-}

package/dist/registry/providers/index.js

@@ -7,8 +7,6 @@
  * Import this module (side-effect import) to register all built-in registry
  * providers with the provider registry. This replaces the individual
  * side-effect imports that were duplicated in registry-search.ts.
- *
- * Mirrors the pattern used by `sources/providers/index.ts`.
  */
 import "./static-index.js";
 import "./skills-sh.js";

package/dist/registry/providers/skills-sh.js

@@ -1,12 +1,11 @@
 // 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/.
-import { jsonWithByteCap } from "../../core/common.js";
 import { formatRegistryCredentialWarning, formatRegistryError, formatRegistryLabel, hasRegistryUrlCredentials, } from "../../core/registry-url.js";
 import { md5Hex } from "../../runtime.js";
-import { fetchCachedJson } from "../../storage/repositories/registry-cache.js";
+import { fetchCachedJson } from "../../storage/repositories/registry-index-cache-repository.js";
 import { registerRegistryProvider } from "../factory.js";
-import { allowPrivateRegistryFixtureForTests, cancelRegistryResponse, fetchRegistryResponse } from "../network.js";
+import { fetchRegistryJson } from "../network.js";
 // ── Constants ───────────────────────────────────────────────────────────────
 /** Per-query cache TTL in milliseconds (15 minutes). */
 const QUERY_CACHE_TTL_MS = 15 * 60 * 1000;
@@ -63,17 +62,7 @@ class SkillsShProvider {
                 }
             },
             fetchFresh: async () => {
-                const response = await fetchRegistryResponse(url, undefined, {
-                    policy: { kind: "public-registry" },
-                    timeoutMs: 10_000,
-                    retries: 1,
-                    allowPrivateHostsForTesting: allowPrivateRegistryFixtureForTests(url),
-                });
-                if (!response.ok) {
-                    await cancelRegistryResponse(response);
-                    throw new Error(`HTTP ${response.status}`);
-                }
-                const data = await jsonWithByteCap(response, 10 * 1024 * 1024, { bodyTimeoutMs: 10_000 });
+                const data = await fetchRegistryJson(url, { timeoutMs: 10_000, retries: 1 });
                 const entries = parseSkillsResponse(data);
                 return { value: entries, cacheJson: JSON.stringify(entries) };
             },

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

@@ -1,16 +1,19 @@
 // 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/.
-import { jsonWithByteCap } from "../../core/common.js";
+import { NotFoundError } from "../../core/errors.js";
 import { formatRegistryCredentialWarning, formatRegistryError, formatRegistryLabel, hasRegistryUrlCredentials, } from "../../core/registry-url.js";
+import { warnOnce } from "../../core/warn.js";
 import { asString } from "../../integrations/github.js";
-import { fetchCachedJson } from "../../storage/repositories/registry-cache.js";
+import { fetchCachedJson } from "../../storage/repositories/registry-index-cache-repository.js";
 import { registerRegistryProvider } from "../factory.js";
-import { allowPrivateRegistryFixtureForTests, cancelRegistryResponse, fetchRegistryResponse } from "../network.js";
+import { fetchRegistryJson } from "../network.js";
 import { buildInstallRef } from "../resolve.js";
 // ── Constants ───────────────────────────────────────────────────────────────
 /** Cache TTL in milliseconds (1 hour). */
 const CACHE_TTL_MS = 60 * 60 * 1000;
+/** Index format versions this reader was written against; both use the same `stashes[]` wire format. */
+const KNOWN_INDEX_VERSIONS = new Set([2, 3]);
 // ── Provider class ──────────────────────────────────────────────────────────
 class StaticIndexProvider {
     type = "static-index";
@@ -39,6 +42,9 @@ class StaticIndexProvider {
         try {
             const index = await loadIndex(this.config);
             if (index) {
+                if (!KNOWN_INDEX_VERSIONS.has(index.version ?? Number.NaN)) {
+                    warnOnce(`registry-index-version:${this.config.url}`, `Registry ${formatRegistryLabel(this.config)}: index version ${index.version ?? "(missing)"} is not one this akm was written against (2 or 3); reading the entries it can.`);
+                }
                 const regName = this.config.name;
                 for (const stash of index.stashes) {
                     if (stash.source === "git") {
@@ -66,46 +72,38 @@ async function loadIndex(entry) {
         // cache row lets JSON.parse throw out of the load.
         parseCache: (json) => parseRegistryIndex(JSON.parse(json)) ?? undefined,
         fetchFresh: async () => {
-            const response = await fetchRegistryResponse(entry.url, undefined, {
-                policy: { kind: "public-registry" },
-                timeoutMs: 10_000,
-                allowPrivateHostsForTesting: allowPrivateRegistryFixtureForTests(entry.url),
-            });
-            if (!response.ok) {
-                await cancelRegistryResponse(response);
-                throw new Error(`HTTP ${response.status}`);
-            }
-            // Cap at 50 MB — registry indexes can grow large but unbounded
-            // responses from a compromised server would OOM us.
-            const data = await jsonWithByteCap(response, 50 * 1024 * 1024, { bodyTimeoutMs: 10_000 });
+            // Registry indexes can grow large; 50 MB is the cap on what one is
+            // allowed to send.
+            const data = await fetchRegistryJson(entry.url, { timeoutMs: 10_000, maxBytes: 50 * 1024 * 1024 });
             const index = parseRegistryIndex(data);
             if (!index) {
-                throw new Error("Invalid registry index format");
+                throw new NotFoundError(`Registry index at ${formatRegistryLabel(entry)} has no stashes array`, "REGISTRY_RESPONSE_INVALID");
             }
-            const etag = response.headers.get("etag") ?? undefined;
-            const lastModified = response.headers.get("last-modified") ?? undefined;
-            return { value: index, cacheJson: JSON.stringify(index), cacheOpts: { etag, lastModified } };
+            return { value: index, cacheJson: JSON.stringify(index) };
         },
     });
 }
 // ── Index parsing (exported for reuse) ──────────────────────────────────────
+/**
+ * Read whatever the index carries: the only requirement is a `stashes` array.
+ * Entries that lack an id, name, ref or known source are skipped; `version`
+ * and `updatedAt` are carried through as published.
+ */
 export function parseRegistryIndex(data) {
     if (typeof data !== "object" || data === null || Array.isArray(data))
         return null;
     const obj = data;
-    // Accept version 2 and 3 — both use the same stashes[] wire format.
-    // The live official registry currently publishes version 2.
-    if (typeof obj.version !== "number" || (obj.version !== 2 && obj.version !== 3))
-        return null;
-    if (typeof obj.updatedAt !== "string")
-        return null;
     if (!Array.isArray(obj.stashes))
         return null;
     const stashes = obj.stashes.flatMap((raw) => {
         const stash = parseBundleEntry(raw);
         return stash ? [stash] : [];
     });
-    return { version: obj.version, updatedAt: obj.updatedAt, stashes };
+    return {
+        version: typeof obj.version === "number" ? obj.version : undefined,
+        updatedAt: asString(obj.updatedAt),
+        stashes,
+    };
 }
 // ── Stash entry parsing ───────────────────────────────────────────────────────
 function parseBundleEntry(raw) {