@superblocksteam/vite-plugin-file-sync 1.99.99-next.3 → 2.0.0-SNAPSHOT.2143e2e95d0107ab

package/dist/ai-service/app-interface/npm-package-lookup.js

@@ -0,0 +1,1043 @@
+import { metrics, trace, } from "@opentelemetry/api";
+import semver from "semver";
+import z from "zod";
+import { bucketNpmPackageName, bucketNpmRegistryHost, NPM_REGISTRY_SPAN, NPM_REGISTRY_SPAN_ATTR, npmPackageUnpackedSizeBytes, npmRegistryEmitter, withNpmRegistrySpan, } from "@superblocksteam/telemetry";
+import { getLogger } from "../../util/logger.js";
+/**
+ * Meter name for the npm-package-lookup gauge. Picked to match the
+ * `superblocks.npm.*` instrument family established by APPS-4189
+ * (`superblocks.npm.install.*` counter + histogram); the meter is the
+ * "instrumentation scope" the OTel collector tags every emitted metric
+ * with, so keeping the npm tools under one scope name makes the family
+ * easy to filter on in Grafana.
+ */
+const METER_NAME = "superblocks.npm";
+/**
+ * Resolve the cache-size gauge against the *currently registered* global
+ * meter provider. Resolved per-instance (in the constructor) rather than
+ * memoized at module load because:
+ *
+ *   1. The global meter provider can be installed after this module is
+ *      imported — telemetry init is async and runs alongside the rest of
+ *      the dev-server bootstrap. A memoized lookup taken at import time
+ *      would bind to the no-op meter and never emit.
+ *   2. Tests swap the global meter provider per case (so each case has its
+ *      own in-memory exporter). A memoized gauge would observe through a
+ *      provider that's been disabled, missing the assertion.
+ *
+ * The OpenTelemetry SDK already de-duplicates same-name instruments inside
+ * the same meter (returns the existing one and logs a warning the first
+ * time a mismatched description is seen), so resolving per-instance is
+ * cheap; we're not creating multiple physical instruments.
+ */
+function resolveCacheSizeGauge() {
+    return metrics
+        .getMeter(METER_NAME)
+        .createObservableGauge("superblocks.npm.lookup.cache_size", {
+        description: "Current number of entries in the NpmPackageLookup in-memory cache (successful lookups and 'not_in_registry' misses; transient failures are not cached).",
+        unit: "{entry}",
+    });
+}
+/**
+ * Resolve the eviction counter against the *currently registered* global
+ * meter provider. Mirrors `resolveCacheSizeGauge` (same per-instance
+ * resolution rationale, same `superblocks.npm.*` instrument family) — the
+ * gauge reports the live footprint, this counter reports the cumulative
+ * number of entries the size cap has forced out so the two can be read
+ * together (sustained eviction at a flat `cache_size` = the cap is the
+ * bottleneck, not just churn).
+ */
+function resolveCacheEvictionCounter() {
+    return metrics
+        .getMeter(METER_NAME)
+        .createCounter("superblocks.npm.lookup.cache_evictions", {
+        description: "Cumulative number of entries evicted from the NpmPackageLookup in-memory cache to stay under the size cap (expired entries first, then oldest-expiring).",
+        unit: "{entry}",
+    });
+}
+const DEFAULT_TTL_MS = 60_000;
+const DEFAULT_FETCH_TIMEOUT_MS = 5_000;
+/**
+ * Freshness floor (ms) for the per-lookup forced config refresh. A lookup must
+ * see an admin clearing or changing the registry quickly, but Clark issues
+ * package lookups one at a time, so a literal per-call refresh would turn a
+ * sequential batch of N packages into N config fetches. Passing this floor to
+ * `getConfig({ forceRefresh, forceRefreshMaxAgeMs })` lets a tight batch reuse
+ * a config no older than a few seconds, collapsing it onto ~one fetch while
+ * keeping admin-change visibility well under the client's 5-minute TTL.
+ */
+const CONFIG_FRESHNESS_FLOOR_MS = 5_000;
+/**
+ * Hard cap on the in-memory cache size. The lookup instance lives for the
+ * whole dev-server process, and TTL is only checked reactively on read, so
+ * without a cap a long session full of unique lookups (one per package the
+ * agent ever considers) would grow the heap unbounded — expired entries
+ * linger until they're re-accessed, which a never-repeated name never is.
+ * On insert at/over the cap we evict expired entries first, then the
+ * oldest-expiring entries until under the cap (see `evictToCapacity`).
+ * Sized well above the sibling caches (`scoped-token-utils` = 100,
+ * `secret-scanner` = 200) because a npm name is a far smaller value than a
+ * token or a scan result and a single Clark session can legitimately touch
+ * thousands of distinct packages; 10k entries is a few MB at most.
+ */
+const MAX_CACHE_SIZE = 10_000;
+/**
+ * How many entries to include in `recent_versions`. Sized so the agent gets
+ * enough recent history to pick across major lines without bloating its
+ * context window — most popular packages publish dozens of patch versions
+ * per major, and 30 covers ~the last 2-3 majors for a typical library.
+ */
+const RECENT_VERSIONS_CAP = 30;
+/**
+ * Pseudo-keys in npm's `time` map that are not real package versions.
+ */
+const NPM_TIME_PSEUDO_KEYS = new Set(["created", "modified", "unpublished"]);
+/** 7-day new-release hold-back window (pnpm minimumReleaseAge / Renovate precedent). */
+export const QUARANTINE_WINDOW_MS = 7 * 24 * 60 * 60 * 1000;
+/**
+ * If `version` was published within `windowMs` of `nowMs`, return the newest
+ * version whose publish time is at or before `nowMs - windowMs`. Returns
+ * `undefined` when age is unknown, the version is already old enough, or no
+ * older candidate exists — callers treat that as "no holdback" (fail-open).
+ */
+export function selectQuarantineHoldback(args) {
+    const { nowMs, publishTimes, version, windowMs = QUARANTINE_WINDOW_MS, } = args;
+    if (semver.valid(version) === null) {
+        return undefined;
+    }
+    const raw = publishTimes[version];
+    if (typeof raw !== "string" && typeof raw !== "number") {
+        return undefined;
+    }
+    const publishedMs = typeof raw === "number" ? raw : Date.parse(raw);
+    if (!Number.isFinite(publishedMs)) {
+        return undefined;
+    }
+    const cutoffMs = nowMs - windowMs;
+    if (publishedMs <= cutoffMs) {
+        return undefined;
+    }
+    let best;
+    for (const [candidate, candidateRaw] of Object.entries(publishTimes)) {
+        if (NPM_TIME_PSEUDO_KEYS.has(candidate))
+            continue;
+        if (semver.valid(candidate) === null)
+            continue;
+        if (typeof candidateRaw !== "string" && typeof candidateRaw !== "number") {
+            continue;
+        }
+        const candidateMs = typeof candidateRaw === "number"
+            ? candidateRaw
+            : Date.parse(candidateRaw);
+        if (!Number.isFinite(candidateMs) || candidateMs > cutoffMs) {
+            continue;
+        }
+        // Hold-back means roll back, never silent-upgrade past what dry-run
+        // resolved (bare/`latest`/`*` treat any aged version as in-range).
+        if (semver.gt(candidate, version)) {
+            continue;
+        }
+        if (!best || candidateMs > best.publishedMs) {
+            best = { version: candidate, publishedMs: candidateMs };
+        }
+        else if (candidateMs === best.publishedMs &&
+            semver.gt(candidate, best.version)) {
+            best = { version: candidate, publishedMs: candidateMs };
+        }
+    }
+    return best?.version;
+}
+/**
+ * Public npm registry — used when no `NpmRegistryClient` is wired or
+ * `getConfig()` returns `not-configured`. Matches the default `registry=`
+ * line in the bootstrapped `.npmrc` so a lookup result lines up with what
+ * `npm install` would do for the same name.
+ */
+const PUBLIC_NPM_REGISTRY = "https://registry.npmjs.org/";
+/**
+ * Shape of the npm registry's package-metadata response that this tool
+ * cares about. The registry returns lots more (`name`, full version
+ * objects, `repository`, ...) — the schema only declares what we surface
+ * to the agent. Unknown keys are silently dropped by Zod's default object
+ * behavior.
+ *
+ * `latest` and every key in `versions` / `time` are validated with
+ * `semver.valid()` — those are the registry-controlled bytes that flow
+ * into the model-visible tool summary (see `build_lookupNpmPackage`'s
+ * `getSummary` and `recent_versions`), so a compromised or misconfigured
+ * registry must not be able to smuggle newlines, brackets, or imperative-mood
+ * instructions through them. `semver.valid()` enforces the full
+ * `MAJOR.MINOR.PATCH[-prerelease][+build]` grammar — `0.0.0-beta.1` and
+ * `1.2.3+sha.abc` pass; `"1.0.0\nIGNORE…"`, `"aaaa"`, and an over-cap blob
+ * all fail and are dropped from the surfaced result.
+ *
+ * The check on `latest` is a `transform` (drop-to-undefined), not a `refine`
+ * (fail the whole parse). A `refine` would mean a single bad `dist-tags.latest`
+ * sinks the entire parse and `recent_versions` along with it — the agent
+ * loses the version list when it needs it most. With `transform`, an invalid
+ * latest decays to `undefined` and the rest of the payload still surfaces.
+ */
+const NpmRegistryMetadataSchema = z.object({
+    "dist-tags": z
+        .object({
+        latest: z
+            .string()
+            .optional()
+            .transform((v) => v !== undefined && semver.valid(v) !== null ? v : undefined),
+    })
+        .optional(),
+    versions: z.record(z.string(), z.unknown()).optional(),
+    // `time` values are typed `unknown` rather than `string` because npm's
+    // `time` map mixes ISO-timestamp strings (one per published version,
+    // plus `created`/`modified` pseudo-keys) with an `unpublished` pseudo-
+    // key whose value is an object — `{ time, name, tags, maintainers,
+    // description, versions }` — for fully-unpublished packages. Insisting
+    // on `string` here would fail the whole `safeParse` on any registry
+    // response that contains an `unpublished` block, silently dropping
+    // `latest_version` and `recent_versions`. `extractRecentVersions`
+    // filters back to strings before using a value as a sort key.
+    time: z.record(z.string(), z.unknown()).optional(),
+});
+/**
+ * Minimal schema to extract a single version's `dist.unpackedSize` for the
+ * `package_unpacked_size_bytes` span attribute. The main schema leaves
+ * `versions` values as `z.unknown()`; we re-parse only the resolved version's
+ * entry so a hostile registry can't smuggle a non-numeric byte count
+ * (validated again at the emit boundary by `npmPackageUnpackedSizeBytes`).
+ */
+const VersionUnpackedSizeSchema = z.object({
+    dist: z.object({ unpackedSize: z.number().optional() }).optional(),
+});
+/**
+ * Best-effort `dist.unpackedSize` (bytes) of the resolved/latest version, or
+ * `undefined` when absent / non-numeric / negative. Span-attribute only —
+ * never a metric label (raw byte counts are unbounded cardinality).
+ */
+function unpackedSizeForVersion(versions, latest) {
+    if (latest === undefined)
+        return undefined;
+    const entry = VersionUnpackedSizeSchema.safeParse(versions?.[latest]);
+    return entry.success
+        ? npmPackageUnpackedSizeBytes(entry.data.dist?.unpackedSize)
+        : undefined;
+}
+/**
+ * Map a lookup result to the closed `lookup_tool` outcome enum: `available` →
+ * `in_registry`; an explicit `not_in_registry` → `not_in_registry`; every
+ * other failure (auth, unreachable, fail-closed) and a thrown lookup →
+ * `error`. The emitter re-normalizes, so an unexpected value can't escape.
+ */
+function lookupToolOutcome(result) {
+    if (!result)
+        return "error";
+    if (result.available)
+        return "in_registry";
+    if (result.reason === "not_in_registry")
+        return "not_in_registry";
+    return "error";
+}
+/**
+ * Normalize a registry URL into a stable cache-key prefix. Lowercases the
+ * scheme+host (RFC 3986 §3) and drops a single trailing slash so
+ * `https://artifactory.example.com/api/npm/repo-a/` and
+ * `HTTPS://Artifactory.Example.com/api/npm/repo-a` hash to the same entry —
+ * but `…/repo-a/` and `…/repo-b/` stay distinct, which is the property
+ * Artifactory-style virtual repos depend on. The path is preserved
+ * case-sensitively because registry sub-paths are usually case-sensitive
+ * (Artifactory treats `/repo-a` and `/Repo-A` as different repos).
+ */
+function normalizeRegistryUrl(raw) {
+    try {
+        const u = new URL(raw);
+        const origin = `${u.protocol.toLowerCase()}//${u.host.toLowerCase()}`;
+        const path = u.pathname.replace(/\/$/, "");
+        return `${origin}${path}`;
+    }
+    catch {
+        // Malformed URL — fall back to the raw string trimmed of trailing
+        // slashes. This shouldn't happen in practice because `resolveRegistry`
+        // only ever returns URLs that the `new URL(registry.url)` call above
+        // it accepted, but the cache-key path must not throw.
+        return raw.replace(/\/$/, "");
+    }
+}
+/**
+ * Encode an npm package name into the URL-path segment npm registries expect.
+ *
+ * For scoped packages (`@scope/name`) the `/` is percent-encoded to `%2F` so
+ * the path collapses to a single registry segment — npm, Artifactory, and
+ * Verdaccio all accept that form, and it sidesteps the ambiguity where a
+ * literal `/` could be confused with a registry sub-path on some proxies.
+ * The leading `@` is left as-is to match npm CLI URL shape, but the rest of
+ * the scope name is percent-encoded along with the sub-name so a hostile or
+ * malformed input (`@evil?probe=1/pkg`) cannot smuggle query-/path-segment
+ * characters into the authenticated request.
+ */
+function encodePackagePath(name) {
+    if (name.startsWith("@")) {
+        const slash = name.indexOf("/");
+        if (slash > 0) {
+            const scope = name.slice(1, slash);
+            const sub = name.slice(slash + 1);
+            return `@${encodeURIComponent(scope)}%2F${encodeURIComponent(sub)}`;
+        }
+    }
+    return encodeURIComponent(name);
+}
+/**
+ * Pick the registry that `npm install` would route a given package name to,
+ * given the current `NpmRegistryConfig`. Mirrors npm's scope-mapping rule:
+ * `@scope/foo` matches `config.scopes["@scope"]` if present, otherwise the
+ * default registry. Unscoped names always use the default.
+ *
+ * Returns `undefined` only when the config has scope mappings but no default
+ * AND the requested name doesn't match any scope — in that case we have no
+ * URL to hit. The caller falls back to public npm; `npm install` would do
+ * the same thing.
+ */
+function selectRegistry(config, name) {
+    if (name.startsWith("@")) {
+        const slash = name.indexOf("/");
+        if (slash > 0) {
+            const scope = name.slice(0, slash);
+            const scoped = config.scopes?.[scope];
+            if (scoped) {
+                return scoped;
+            }
+        }
+    }
+    return config.default;
+}
+/**
+ * Pre-flight check for npm package availability against the registry
+ * Clark's install path would actually use. Designed so the agent can call
+ * this BEFORE attempting `npm install` and either skip a doomed install
+ * (the registry doesn't carry the package), pick a different package up
+ * front, or pick a recent version from `recent_versions` — rather than
+ * burning ~30s on a build pod recovering from `NpmInstallBlocked` after
+ * the fact.
+ *
+ * Registry resolution per call (mirrors `npm install`'s scope-mapping):
+ *
+ *   1. `await client.getConfig()` if a client is wired.
+ *      - `source: configured | stale` → use `config.scopes[@scope]` for a
+ *        scoped name; else `config.default`. Both yield `mode: "private"`.
+ *        If neither matches (scoped-only mappings, no default, no scope
+ *        match) the result is public npm (`mode: "public-npm"`): a
+ *        scoped-only config is valid and unscoped names fall through to
+ *        npmjs.org, matching the synthesized `.npmrc` — see `resolveRegistry`.
+ *      - `source: not-configured` → public npm (`mode: "public-npm"`).
+ *      - `source: unreachable`, or `getConfig()` threw → `mode: "fail-closed"`.
+ *   2. No client wired → public npm (`mode: "public-npm"`).
+ *      Matches the default `registry=` line we bootstrap into every app's
+ *      `.npmrc`.
+ *
+ * Behaviour matrix (post-resolve):
+ *
+ *   | HTTP 200                                   | `available: true`, `latest_version`, `recent_versions` |
+ *   | HTTP 404                                   | `available: false, reason: not_in_registry` |
+ *   | HTTP 401 / 403                             | `available: false, reason: registry_auth_failed` |
+ *   | HTTP 5xx / DNS / TCP / TLS / fetch throw   | `available: false, reason: registry_unreachable` |
+ *
+ * `mode: "public-npm"` + `reason: "registry_unreachable"` is the strong
+ * signal that the operator's network blocks egress to npmjs.org without
+ * a configured private registry; the agent can surface this as a
+ * connectivity / configuration issue rather than a missing package.
+ * `mode: "fail-closed"` + `reason: "registry_unreachable"` covers the
+ * cases where the private-registry config itself is in a bad state
+ * (auth, or transient unreachable for a previously-configured org). A
+ * scoped-only config with no default and no scope match is NOT fail-closed:
+ * it resolves to public npm, because that's where a real `npm install` of an
+ * unscoped name would go under the synthesized `.npmrc`.
+ *
+ * Token hygiene: the token comes back from `client.getConfig()` per call
+ * and lives only in a local inside `lookup()`. Nothing token-bearing is
+ * stored on the instance, so `JSON.stringify(this)` cannot surface it.
+ * Bodies of 4xx/5xx responses are drained without inspection — a hostile
+ * registry could echo the submitted token back in a 401 body, and the only
+ * way to guarantee the token never reaches the tool output / log / span is
+ * to never read those bytes at all.
+ *
+ * Caching: per-instance, in-memory, keyed on
+ * `<normalized-registry-base-url>:<name>` with a 60s TTL. The full base
+ * URL (not just the host) is required because Artifactory-style proxies
+ * host multiple npm repos under one host (`…/api/npm/repo-a/` vs
+ * `…/api/npm/repo-b/`) — keying on host alone would let a 200 or 404
+ * from one virtual repo bleed into the other. Per-process (the dev-server
+ * runs a single AppShell), no cross-pod sharing — same as
+ * `NpmRegistryClient`. Only stable outcomes (`available: true` and
+ * `not_in_registry`) are cached; `registry_auth_failed` and
+ * `registry_unreachable` are transient and must recover on the next call
+ * (otherwise a token rotation or a short network blip would pin the
+ * failure for a full minute). The URL-keyed prefix also means a swap
+ * between a private registry and the public-npm fallback can't accidentally
+ * serve a result from the wrong source. The cache is bounded at
+ * `MAX_CACHE_SIZE` entries (APPS-4429): TTL is checked only reactively on
+ * read, so without a cap a long session of unique lookups would grow the
+ * heap unbounded. On insert at/over the cap, `evictToCapacity` drops expired
+ * entries first, then the oldest-expiring live entries, emitting the count
+ * on the `cache_evictions` counter.
+ *
+ * In-flight dedup: concurrent `lookup(name)` calls that miss the cache and
+ * resolve to the same cache key share a single fetch — the first caller
+ * stores the pending promise in an inflight map; subsequent callers await
+ * it instead of firing a second HTTP request. Clark batch-installs (one
+ * lookup per package) hit this path regularly. The slot is cleared in
+ * `.finally()` so a transient-failure resolution doesn't pin every future
+ * caller to the same rejected promise. See `inFlight` for the keying
+ * contract (same string as the cache, so two scopes never share a result).
+ */
+export class NpmPackageLookup {
+    client;
+    orgId;
+    fetchImpl;
+    nowFn;
+    ttlMs;
+    fetchTimeoutMs;
+    cache = new Map();
+    /**
+     * In-flight fetches keyed by the same `<normalized-registry-base-url>:<name>`
+     * string the cache uses. The first caller for a given key kicks off the
+     * fetch and stores the pending promise here; subsequent concurrent callers
+     * (Clark batch-installs hit this regularly) await the same promise instead
+     * of firing a second HTTP request against the registry. The slot is cleared
+     * in `.finally()` regardless of fetch outcome — including the transient
+     * failure paths (`registry_auth_failed`, `registry_unreachable`) that the
+     * cache deliberately skips — so a single failed fetch can't pin every
+     * future caller to the same rejected promise.
+     *
+     * Keying on the same string as `cache` (not on `name` alone) means
+     * concurrent lookups for the same package name routed to different
+     * registries (scoped vs. default, or a swap between private and public)
+     * each get their own inflight slot and never share a result across trust
+     * boundaries.
+     */
+    inFlight = new Map();
+    /**
+     * Resolved gauge and bound callback held so `removeCallback` can detach.
+     * The gauge handle is captured at construction so `dispose()` always
+     * detaches from the same instrument it attached to, even if the global
+     * meter provider has been replaced in the meantime.
+     */
+    gauge;
+    gaugeCallback;
+    /**
+     * Counter for entries the size cap forces out (see `evictToCapacity`).
+     * Cumulative, no labels — same partitioning rationale as the gauge. Held
+     * `undefined` when `skipMetrics` is set so tests don't leak instruments
+     * against the process-global meter.
+     */
+    evictionCounter;
+    constructor(deps = {}) {
+        this.client = deps.client;
+        this.orgId = deps.orgId;
+        this.fetchImpl = deps.fetch ?? globalThis.fetch;
+        this.nowFn = deps.now ?? Date.now;
+        this.ttlMs = deps.ttlMs ?? DEFAULT_TTL_MS;
+        this.fetchTimeoutMs = deps.fetchTimeoutMs ?? DEFAULT_FETCH_TIMEOUT_MS;
+        if (!deps.skipMetrics) {
+            // The callback observes `cache.size` directly. No labels — the meter's
+            // resource attributes (`service.name`, `deployment.environment.name`)
+            // already partition by process; further per-instance attributes would
+            // double-count when more than one `NpmPackageLookup` lives in the same
+            // process (e.g. if a future Clark code path constructs a second one).
+            // OTel resolves duplicate observations for the same gauge+attributes by
+            // taking the last value within a collection cycle, so even then we'd
+            // surface only one of them; emitting them under separate attribute sets
+            // would inflate the series count without adding signal.
+            this.gauge = resolveCacheSizeGauge();
+            this.gaugeCallback = (result) => {
+                result.observe(this.cache.size);
+            };
+            this.gauge.addCallback(this.gaugeCallback);
+            this.evictionCounter = resolveCacheEvictionCounter();
+        }
+    }
+    /**
+     * Detach the cache-size gauge callback. Call when retiring a long-lived
+     * instance (e.g. tearing down a Clark session that owned its own lookup).
+     * The OTel API keeps a strong reference to every registered callback, so
+     * letting the instance go out of scope without calling this leaves the
+     * callback (and the cache it closes over) alive for the lifetime of the
+     * process meter. Production code paths that hold the lookup for the
+     * lifetime of the process never need to call this; it exists so tests and
+     * future cleanup paths can detach cleanly.
+     */
+    dispose() {
+        if (this.gauge && this.gaugeCallback) {
+            this.gauge.removeCallback(this.gaugeCallback);
+        }
+    }
+    /**
+     * Look up a package, wrapped in the `npm_registry.lookup_package` span and
+     * the `superblocks.npm.lookup.*` metric (APPS-4378). Every tool call — cache
+     * hit or live fetch — is observed; `org_id` rides on the span only. The span
+     * uses the global tracer so it nests under an active Clark/LLMObs task span.
+     */
+    async lookup(name) {
+        const start = this.nowFn();
+        return withNpmRegistrySpan(NPM_REGISTRY_SPAN.LOOKUP_PACKAGE, this.orgId ? { [NPM_REGISTRY_SPAN_ATTR.ORG_ID]: this.orgId } : {}, async (span) => {
+            let result;
+            try {
+                result = await this.lookupImpl(name);
+                return result;
+            }
+            finally {
+                this.observeLookupTool(span, name, result, this.nowFn() - start);
+            }
+        });
+    }
+    /**
+     * Non-tool quarantine API for the install gate. If `version` is younger
+     * than the 7-day window, returns the newest older-than-window pin.
+     * Applies to every resolved registry, including org default and scoped
+     * private registries. Returns `undefined` (no holdback / fail-open) when:
+     * fail-closed, age unknown, version already old enough, no older
+     * candidate, or the registry fetch fails.
+     */
+    async pickQuarantineHoldback(name, version) {
+        try {
+            const resolved = await this.resolveRegistry(name);
+            if (resolved === "fail-closed") {
+                return undefined;
+            }
+            const registryBase = resolved.registry.url.replace(/\/$/, "");
+            const url = `${registryBase}/${encodePackagePath(name)}`;
+            const headers = { accept: "application/json" };
+            if (resolved.registry.token) {
+                headers.authorization = `Bearer ${resolved.registry.token}`;
+            }
+            const registryHost = new URL(resolved.registry.url).host;
+            const response = await this.fetchImpl(url, {
+                method: "GET",
+                headers,
+                signal: AbortSignal.timeout(this.fetchTimeoutMs),
+            });
+            if (response.status !== 200) {
+                await drainSilently(response);
+                getLogger().warn("[pkg-security] quarantine unevaluable", {
+                    reason: "registry_status",
+                    registryHost,
+                    status: response.status,
+                });
+                return undefined;
+            }
+            const parsed = NpmRegistryMetadataSchema.safeParse(await response.json());
+            if (!parsed.success || !parsed.data.time) {
+                getLogger().warn("[pkg-security] quarantine unevaluable", {
+                    reason: "no_time_metadata",
+                    registryHost,
+                });
+                return undefined;
+            }
+            const publishTimes = {};
+            for (const [key, value] of Object.entries(parsed.data.time)) {
+                if (typeof value === "string" || typeof value === "number") {
+                    publishTimes[key] = value;
+                }
+            }
+            return selectQuarantineHoldback({
+                nowMs: this.nowFn(),
+                publishTimes,
+                version,
+            });
+        }
+        catch (err) {
+            getLogger().warn("[pkg-security] quarantine unevaluable", {
+                error: err instanceof Error ? err.message : String(err),
+                reason: "fetch_failed",
+            });
+            return undefined;
+        }
+    }
+    /**
+     * Emit the `superblocks.npm.lookup.*` metric and set the span's outcome
+     * attributes. `package_unpacked_size_bytes` is set separately inside
+     * `fetchAndMap` (it's only known after parsing the 200 body, and is
+     * best-effort on the in-flight-deduped path).
+     */
+    observeLookupTool(span, name, result, durationMs) {
+        // fail-closed yields registry_host "" → undefined → bucket "unknown".
+        const registryHost = result?.registry_host || undefined;
+        const registryBucket = bucketNpmRegistryHost(registryHost);
+        const outcome = lookupToolOutcome(result);
+        span.setAttributes({
+            [NPM_REGISTRY_SPAN_ATTR.REGISTRY_HOST]: registryBucket,
+            [NPM_REGISTRY_SPAN_ATTR.PACKAGE_NAME_BUCKET]: bucketNpmPackageName(name, registryBucket),
+            [NPM_REGISTRY_SPAN_ATTR.OUTCOME]: outcome,
+            [NPM_REGISTRY_SPAN_ATTR.DURATION_MS]: durationMs,
+        });
+        npmRegistryEmitter.recordLookupTool({ registryHost, outcome, durationMs });
+    }
+    async lookupImpl(name) {
+        const resolved = await this.resolveRegistry(name);
+        if (resolved === "fail-closed") {
+            // We have evidence of a private-registry org but no safe destination
+            // for this name (hard-fail auth, or a transient `source: unreachable`).
+            // Returning `registry_unreachable` with `mode: "fail-closed"` tells the
+            // agent "the lookup didn't run" without leaking a potentially-private
+            // package name to npmjs.org.
+            return {
+                available: false,
+                mode: "fail-closed",
+                reason: "registry_unreachable",
+                registry_host: "",
+            };
+        }
+        const { registry, mode } = resolved;
+        const registryBase = registry.url.replace(/\/$/, "");
+        const registryHost = new URL(registry.url).host;
+        // Key on the normalized registry base URL — host alone collides on
+        // Artifactory-style proxies that host multiple npm repos under one
+        // host (e.g. `…/api/npm/repo-a/` vs `…/api/npm/repo-b/`). Lowercasing
+        // the scheme+host (per RFC 3986 §3) and dropping the trailing slash
+        // gives a stable identity for the same registry across capitalisation
+        // and slash-trailing variants in the config. `registry_host` in the
+        // result keeps the bare host — the cache-key shape is an internal
+        // detail callers don't need.
+        const cacheKey = `${normalizeRegistryUrl(registry.url)}:${name}`;
+        const now = this.nowFn();
+        const cached = this.cache.get(cacheKey);
+        if (cached && cached.expiresAt > now) {
+            return cached.result;
+        }
+        // Share a single in-flight fetch across concurrent callers for the same
+        // key (Clark batch-installs are the hot path). `inFlight.set` happens
+        // synchronously before the first `await`, so a second call that enters
+        // `lookup()` while the first is still pending always sees the existing
+        // promise here and skips the duplicate fetch.
+        const inFlight = this.inFlight.get(cacheKey);
+        if (inFlight) {
+            return inFlight;
+        }
+        const url = `${registryBase}/${encodePackagePath(name)}`;
+        const headers = { accept: "application/json" };
+        if (registry.token) {
+            headers.authorization = `Bearer ${registry.token}`;
+        }
+        const promise = this.fetchAndMap(url, headers, registryHost, mode)
+            .then((result) => {
+            // Cache only stable outcomes. Transient failures must retry on the
+            // next call so a token rotation or a short network blip can't pin
+            // the failure for a full TTL window.
+            if (result.available || result.reason === "not_in_registry") {
+                // Bound the cache before inserting a *new* key. Re-inserting an
+                // existing key (the common refetch-after-TTL path) is a Map
+                // overwrite, not growth, so it never needs eviction — gating on
+                // `!has(cacheKey)` keeps the steady-state hot path free of the
+                // eviction scan.
+                if (!this.cache.has(cacheKey)) {
+                    this.evictToCapacity(now);
+                }
+                this.cache.set(cacheKey, { result, expiresAt: now + this.ttlMs });
+            }
+            return result;
+        })
+            .finally(() => {
+            // Always clear the inflight slot, including on the transient-failure
+            // paths the cache skips. Otherwise a single failed fetch would pin
+            // every future caller to the same rejected promise.
+            this.inFlight.delete(cacheKey);
+        });
+        this.inFlight.set(cacheKey, promise);
+        return promise;
+    }
+    /**
+     * Number of cached entries (successful lookups and `not_in_registry`
+     * misses; transient failures aren't cached). Exposed as a gauge for
+     * monitoring — keeps the cache footprint visible without poking at
+     * private state from outside the class.
+     */
+    size() {
+        return this.cache.size;
+    }
+    /**
+     * Make room for one new entry when the cache is at/over `MAX_CACHE_SIZE`.
+     * Called from the insert path before adding a key that isn't already
+     * present.
+     *
+     * Eviction order, keyed on `expiresAt`:
+     *
+     *   1. Expired entries first (`expiresAt <= now`). TTL is only checked
+     *      reactively on read, so a never-re-accessed name's entry would
+     *      otherwise linger forever; dropping the already-dead ones reclaims
+     *      space without evicting anything a future read could have used.
+     *   2. If that didn't get us under the cap, the oldest-expiring live
+     *      entries (smallest `expiresAt`) — those are closest to expiry anyway,
+     *      so they're the cheapest live entries to lose.
+     *
+     * Sorting the whole keyset is O(n log n), but it only runs once the cache
+     * is full (n = `MAX_CACHE_SIZE`) and only on inserts of genuinely-new keys,
+     * so it's off the steady-state hot path. Emits the number evicted on the
+     * eviction counter so a sustained-eviction-at-flat-size signal is visible
+     * in Grafana alongside the existing `cache_size` gauge.
+     */
+    evictToCapacity(now) {
+        if (this.cache.size < MAX_CACHE_SIZE) {
+            return;
+        }
+        // Target one slot below the cap so the imminent `set` lands at the cap,
+        // not over it.
+        const target = MAX_CACHE_SIZE - 1;
+        let evicted = 0;
+        // Pass 1: expired entries.
+        for (const [key, entry] of this.cache) {
+            if (this.cache.size <= target) {
+                break;
+            }
+            if (entry.expiresAt <= now) {
+                this.cache.delete(key);
+                evicted += 1;
+            }
+        }
+        // Pass 2: oldest-expiring live entries, if still over the cap.
+        if (this.cache.size > target) {
+            const byExpiry = Array.from(this.cache.entries()).sort((a, b) => a[1].expiresAt - b[1].expiresAt);
+            for (const [key] of byExpiry) {
+                if (this.cache.size <= target) {
+                    break;
+                }
+                this.cache.delete(key);
+                evicted += 1;
+            }
+        }
+        if (evicted > 0) {
+            this.evictionCounter?.add(evicted);
+        }
+    }
+    /**
+     * Resolve the registry this lookup will hit:
+     *
+     *   - No client wired (SaaS mode): public npm.
+     *   - `source: not-configured` (operator never opted in): public npm.
+     *   - `source: configured | stale`, name matches `config.scopes[@scope]`:
+     *     scoped private registry.
+     *   - `source: configured | stale`, no scope match, `config.default`
+     *     present: default private registry.
+     *   - `source: configured | stale`, no scope match, no `config.default`
+     *     (scoped-only config): public npm. A scoped-only config is valid —
+     *     npm applies `@scope:registry=…` for matching names and falls through
+     *     to npmjs.org for the rest, exactly what the synthesized `.npmrc`
+     *     does — so an unscoped name resolves to public npm to match install
+     *     reality, not fail-closed.
+     *
+     * Fail-closed (returns `"fail-closed"`; caller surfaces
+     * `registry_unreachable` and never touches the network):
+     *
+     *   - `getConfig()` threw on hard-fail auth (revoked JWT, double 401
+     *     against the Superblocks server). In that state we'd silently
+     *     downgrade from "checking the private registry" to "checking
+     *     public npm" — different trust boundary, different answer. The
+     *     agent's reasoning about install feasibility depends on which
+     *     registry actually answered; failing closed surfaces the auth
+     *     problem instead of hiding it behind a misleading public-npm
+     *     result.
+     *   - `source: unreachable` AND `everConfigured === true` (transient
+     *     cold-cache outage against the Superblocks server for an org that
+     *     has at some prior point successfully resolved a configured
+     *     registry). Same trust gap as the throw branch: we don't know the
+     *     org's current registry state, but the on-disk marker says it has
+     *     a private registry, so leaking the name to npmjs would be a silent
+     *     supply-chain leak during the outage window. Symmetric with
+     *     `syncHomeNpmrc` and `maybeWriteNpmrcForDir`, both of which refuse
+     *     to act on `unreachable` for the same reason.
+     *
+     *     When `everConfigured` is `false` (greenfield org / no disk marker)
+     *     or `undefined` (no store wired in — older call sites, test
+     *     fixtures), we do NOT fail closed. The `unreachable` config is
+     *     `{ configured: false }`, so we proceed exactly as the install path
+     *     does (`AppShell.maybeShortCircuitForUnreachable` only blocks when
+     *     `everConfigured === true`): fall through to public npm. A
+     *     greenfield org has no private registry, so a metadata lookup
+     *     against public npm during a config-server outage leaks nothing
+     *     sensitive — and keeping the lookup aligned with the install gate
+     *     removes the lookup-vs-install divergence where the lookup reported
+     *     `fail-closed` while a direct install of the same package would
+     *     have proceeded (APPS-4425).
+     */
+    async resolveRegistry(name) {
+        if (!this.client) {
+            return {
+                registry: { url: PUBLIC_NPM_REGISTRY },
+                mode: "public-npm",
+            };
+        }
+        let fetchResult;
+        try {
+            // Force-refresh so a lookup observes an admin clearing or changing the
+            // registry quickly instead of answering from the wrong trust boundary
+            // until the config TTL expires. The freshness floor bounds the fetch
+            // amplification: Clark issues lookups one at a time, so without it a
+            // sequential batch of N packages would trigger N config fetches. With
+            // it, a tight batch reuses a config no older than the floor, collapsing
+            // onto ~one fetch; the package-result cache below (keyed by registry
+            // URL) keeps repeat lookups of the same name cheap.
+            fetchResult = await this.client.getConfig({
+                forceRefresh: true,
+                forceRefreshMaxAgeMs: CONFIG_FRESHNESS_FLOOR_MS,
+            });
+        }
+        catch (err) {
+            getLogger().warn("[npm-package-lookup] registry client getConfig threw; failing closed rather than silently downgrading to public npm", { error: err instanceof Error ? err.message : String(err) });
+            return "fail-closed";
+        }
+        if (fetchResult.source === "unreachable") {
+            // Transient cold-cache outage against the Superblocks server. Gate
+            // the fail-closed decision on `everConfigured` so the lookup matches
+            // the install gate (`AppShell.maybeShortCircuitForUnreachable`), which
+            // blocks only when `everConfigured === true` (APPS-4425).
+            if (fetchResult.everConfigured === true) {
+                // The on-disk marker says this org has at some prior point resolved
+                // a configured private registry. We don't know its current state
+                // during the outage, so the same trust-gap argument as the
+                // `getConfig threw` branch applies: falling through to public npm
+                // would leak the requested name — which the agent picked precisely
+                // because it's targeting the (possibly-private) registry — to
+                // npmjs.org. Fail-closed; caller surfaces `registry_unreachable`.
+                // Symmetric with `syncHomeNpmrc` and `maybeWriteNpmrcForDir`, both
+                // of which refuse to act on `source: "unreachable"`.
+                getLogger().warn("[npm-package-lookup] registry config unreachable for a previously-configured org; failing closed rather than silently downgrading to public npm");
+                return "fail-closed";
+            }
+            // `everConfigured` is `false` (greenfield org / no disk marker) or
+            // `undefined` (no store wired in). A greenfield org has no private
+            // registry, so a metadata lookup against public npm during the
+            // config-server outage leaks nothing sensitive — and a direct
+            // install of the same name would proceed through public npm anyway,
+            // since the install path only short-circuits when `everConfigured ===
+            // true`. Proceed to public npm so the lookup doesn't diverge from
+            // install reality. The `unreachable` config is `{ configured: false }`,
+            // so this is the same destination `not-configured` resolves to.
+            return {
+                registry: { url: PUBLIC_NPM_REGISTRY },
+                mode: "public-npm",
+            };
+        }
+        if (fetchResult.source === "not-configured") {
+            return {
+                registry: { url: PUBLIC_NPM_REGISTRY },
+                mode: "public-npm",
+            };
+        }
+        const selected = selectRegistry(fetchResult.config, name);
+        if (selected) {
+            return { registry: selected, mode: "private" };
+        }
+        // Configured org with scoped-only mappings and no default registry, and
+        // the requested name matches no scope. A scoped-only config is valid: npm
+        // reads `@scope:registry=…` lines for matching names and falls through to
+        // public npm for everything else. The synthesized `.npmrc` we write does
+        // exactly that (`npm-registry.ts` emits only scope lines, no default), and
+        // a real `npm install react` here resolves against npmjs.org. The install
+        // gate agrees — `AppShell.maybeShortCircuitForUnreachable` blocks only a
+        // true `source: "unreachable"`, not a scoped-only config. Resolve the
+        // lookup against public npm so the tool's answer matches install reality
+        // instead of mislabeling a working config as a registry outage. Same
+        // destination the `not-configured` branch returns.
+        return {
+            registry: { url: PUBLIC_NPM_REGISTRY },
+            mode: "public-npm",
+        };
+    }
+    async fetchAndMap(url, headers, registryHost, mode) {
+        let response;
+        try {
+            response = await this.fetchImpl(url, {
+                method: "GET",
+                headers,
+                signal: AbortSignal.timeout(this.fetchTimeoutMs),
+            });
+        }
+        catch (err) {
+            getLogger().warn("[npm-package-lookup] registry unreachable", {
+                registryHost,
+                error: err instanceof Error ? err.message : String(err),
+            });
+            return {
+                available: false,
+                mode,
+                reason: "registry_unreachable",
+                registry_host: registryHost,
+            };
+        }
+        if (response.status === 200) {
+            let latest;
+            let recent;
+            try {
+                const parsed = NpmRegistryMetadataSchema.safeParse(await response.json());
+                if (parsed.success) {
+                    latest = parsed.data["dist-tags"]?.latest;
+                    recent = extractRecentVersions(parsed.data, latest);
+                    // Span-attribute only (set on the active lookup_package span); the
+                    // result returned to the LLM tool is intentionally unchanged.
+                    const unpackedSize = unpackedSizeForVersion(parsed.data.versions, latest);
+                    if (unpackedSize !== undefined) {
+                        trace
+                            .getActiveSpan()
+                            ?.setAttribute(NPM_REGISTRY_SPAN_ATTR.PACKAGE_UNPACKED_SIZE_BYTES, unpackedSize);
+                    }
+                }
+            }
+            catch {
+                // 200 with non-JSON body: package still exists; just no latest
+                // and no version list.
+            }
+            return {
+                available: true,
+                mode,
+                registry_host: registryHost,
+                ...(latest ? { latest_version: latest } : {}),
+                ...(recent && recent.length > 0 ? { recent_versions: recent } : {}),
+            };
+        }
+        if (response.status === 404) {
+            await drainSilently(response);
+            return {
+                available: false,
+                mode,
+                reason: "not_in_registry",
+                registry_host: registryHost,
+            };
+        }
+        if (response.status === 401 || response.status === 403) {
+            getLogger().warn("[npm-package-lookup] registry auth failed", {
+                registryHost,
+                status: response.status,
+            });
+            await drainSilently(response);
+            return {
+                available: false,
+                mode,
+                reason: "registry_auth_failed",
+                registry_host: registryHost,
+            };
+        }
+        // 5xx, unexpected 4xx, etc. → treat as a transient infra problem rather
+        // than `not_in_registry`. Mapping them to `not_in_registry` would let a
+        // flaky proxy silently convince Clark the package is missing.
+        getLogger().warn("[npm-package-lookup] registry returned unexpected status", {
+            registryHost,
+            status: response.status,
+        });
+        await drainSilently(response);
+        return {
+            available: false,
+            mode,
+            reason: "registry_unreachable",
+            registry_host: registryHost,
+        };
+    }
+}
+/**
+ * Pull recent published versions out of a parsed npm metadata response,
+ * capped at `RECENT_VERSIONS_CAP`. Only `semver.valid()` strings are kept
+ * so a hostile or misconfigured registry can't smuggle non-version bytes
+ * into the model-visible output.
+ *
+ * Ordering:
+ *   - If the `time` map is present (npmjs, Verdaccio, and most proxies
+ *     include it), sort versions that have a string timestamp by
+ *     published-at descending. This gives the agent the most-recently-
+ *     released versions first, which matches the "use a recent version"
+ *     instruction in the base prompt.
+ *   - Versions present in `versions` but missing a string timestamp in
+ *     `time` (some private proxies drop per-version entries while keeping
+ *     others, or npm's object-valued `unpublished` pseudo-key takes the
+ *     slot a real timestamp would have occupied) sort by semver descending
+ *     and are appended AFTER the timestamped block. Bucketing this way
+ *     keeps the comparator transitive — a single mixed comparator that
+ *     falls back to semver per-pair-when-either-side-is-missing is
+ *     non-transitive (time-order and semver-order can disagree, producing
+ *     cycles), which makes JS `Array.prototype.sort` undefined behaviour.
+ *   - If `time` is absent entirely, sort by semver descending. Some
+ *     private registries strip `time` from their proxy responses; fall
+ *     back to a deterministic ordering rather than returning nothing.
+ *
+ * Pseudo-keys in the `time` map (`created`, `modified`, `unpublished`) are
+ * dropped — they aren't real versions, so `semver.valid()` rejects them.
+ */
+function extractRecentVersions(parsed, latest) {
+    const candidateSet = new Set();
+    if (parsed.versions) {
+        for (const key of Object.keys(parsed.versions)) {
+            if (semver.valid(key) !== null) {
+                candidateSet.add(key);
+            }
+        }
+    }
+    if (parsed.time) {
+        for (const key of Object.keys(parsed.time)) {
+            if (semver.valid(key) !== null) {
+                candidateSet.add(key);
+            }
+        }
+    }
+    if (candidateSet.size === 0) {
+        return undefined;
+    }
+    const candidates = Array.from(candidateSet);
+    if (parsed.time) {
+        const time = parsed.time;
+        const withTimestamp = [];
+        const withoutTimestamp = [];
+        for (const version of candidates) {
+            const t = time[version];
+            if (typeof t === "string") {
+                withTimestamp.push({ version, timestamp: t });
+            }
+            else {
+                withoutTimestamp.push(version);
+            }
+        }
+        withTimestamp.sort((a, b) => b.timestamp.localeCompare(a.timestamp));
+        withoutTimestamp.sort((a, b) => semver.rcompare(a, b));
+        return capRecentVersions([...withTimestamp.map((entry) => entry.version), ...withoutTimestamp], latest);
+    }
+    candidates.sort((a, b) => semver.rcompare(a, b));
+    return capRecentVersions(candidates, latest);
+}
+function capRecentVersions(candidates, latest) {
+    const capped = candidates.slice(0, RECENT_VERSIONS_CAP);
+    // Only surface `latest` when it is a real, semver-valid version — a hostile
+    // or misconfigured registry must not smuggle a non-version dist-tag into the
+    // model-visible list. If it already survived the recency cap, leave it in
+    // its published-time position.
+    if (latest === undefined ||
+        semver.valid(latest) === null ||
+        capped.includes(latest)) {
+        return capped;
+    }
+    // `latest` fell outside the recency window (or the registry omitted it from
+    // `versions`/`time` entirely). Surface it FIRST — it is the dist-tag the
+    // agent would install by default, so it leads the list rather than being
+    // buried at the recency-sorted tail — and keep the list capped.
+    return [latest, ...candidates.filter((version) => version !== latest)].slice(0, RECENT_VERSIONS_CAP);
+}
+/**
+ * Consume the response body and discard it. Called on every non-200 path
+ * for two reasons that happen to be solved by the same operation:
+ *
+ *   1. Connection-pool hygiene. Node's undici-backed `fetch` keeps the
+ *      underlying TCP connection pinned to a response until its body is
+ *      consumed. Skipping the read leaves the connection unavailable to the
+ *      next call until GC reclaims it, which over a long Clark session
+ *      against the same registry host adds up.
+ *   2. Token-echo defense for 401/403 specifically. A hostile or
+ *      misconfigured registry can include the submitted bearer token in the
+ *      error body (Artifactory does this in some configs). The only way to
+ *      guarantee those bytes never reach the tool's output, a log line, or
+ *      a tracing span is to never read them.
+ *
+ * The catch is intentionally broad: if the stream errored or was already
+ * consumed, there is nothing useful to do, and surfacing that failure would
+ * shadow the real status code the caller branches on.
+ */
+async function drainSilently(response) {
+    try {
+        await response.text();
+    }
+    catch {
+        // Body already consumed or stream errored — nothing more to do.
+    }
+}
+//# sourceMappingURL=npm-package-lookup.js.map