@superblocksteam/vite-plugin-file-sync 2.0.123-next.0 → 2.0.124-next.0

package/dist/ai-service/app-interface/npm-package-lookup.d.ts

@@ -0,0 +1,286 @@
+import type { NpmInstallBlockedReason } from "../types.js";
+import type { NpmRegistryClient } from "./npm-registry.js";
+/**
+ * Which registry actually answered (or was going to be hit) for this lookup:
+ *
+ *   - "private": a configured per-org registry (the operator opted in via
+ *     `superblocks.npm-registry.enabled` and configured a default and/or
+ *     scoped registries). Includes `stale` cache reads from
+ *     `NpmRegistryClient`.
+ *   - "public-npm": npmjs.org — either because no client is wired (SaaS),
+ *     or `getConfig()` reported `not-configured`. Matches the default
+ *     `registry=` line in the bootstrapped `.npmrc`.
+ *   - "fail-closed": we have evidence of a private-registry org but no safe
+ *     destination for this name right now (hard-fail auth from `getConfig`,
+ *     transient cold-cache `source: unreachable`, or a configured-but-
+ *     scoped-only org whose mappings don't cover the requested name and
+ *     supplies no default). We deliberately do NOT downgrade to public npm
+ *     in any of these — `available` will be `false` with
+ *     `reason: "registry_unreachable"` and `registry_host` will be empty.
+ *
+ * Note for callers (agent/tool): `mode: "public-npm"` + `reason:
+ * "registry_unreachable"` is the strong signal that the operator's network
+ * blocks egress to npmjs.org without having configured a private registry.
+ * `mode: "private"` + `reason: "registry_unreachable"` is the analogous
+ * signal for an unreachable per-org registry.
+ */
+export type NpmPackageLookupMode = "private" | "public-npm" | "fail-closed";
+/**
+ * Normalized result returned by `NpmPackageLookup.lookup`.
+ *
+ * The `reason` enum reuses `NpmInstallBlockedReason` (APPS-4179) verbatim so
+ * downstream prompt logic and evals can treat both tools' failure modes as
+ * one taxonomy. `registry_host` names whichever registry actually answered —
+ * the per-org default, a scope-mapped private registry, or `registry.npmjs.org`
+ * when we intentionally fell through to public npm. The empty string is
+ * reserved for `mode: "fail-closed"` where no registry was contacted at all.
+ *
+ * `recent_versions` is the most-recently-published versions from the
+ * registry's `time` map (or, when `time` is absent, semver-descending from
+ * `versions`), capped at `RECENT_VERSIONS_CAP`. Lets the agent pick a
+ * specific version without burning a second tool call.
+ */
+export interface NpmPackageLookupResult {
+    available: boolean;
+    mode: NpmPackageLookupMode;
+    reason?: NpmInstallBlockedReason;
+    registry_host: string;
+    latest_version?: string;
+    recent_versions?: string[];
+}
+export interface NpmPackageLookupDeps {
+    /**
+     * Per-org npm registry client (APPS-4230). When omitted, lookups fall back
+     * to the public npm registry, matching the `.npmrc` we bootstrap into a
+     * fresh app (which lists `https://registry.npmjs.org/` as its default).
+     */
+    client?: NpmRegistryClient;
+    /** Inject `fetch` for tests; defaults to `globalThis.fetch`. */
+    fetch?: typeof globalThis.fetch;
+    /** Clock for deterministic cache-TTL tests; defaults to `Date.now`. */
+    now?: () => number;
+    /** Cache TTL in ms; defaults to 60s per APPS-4183 spec. */
+    ttlMs?: number;
+    /** Per-request fetch timeout in ms; defaults to 5s. */
+    fetchTimeoutMs?: number;
+    /**
+     * Skip OTel `ObservableGauge` registration. Tests construct many instances
+     * per file; registering a callback on each one would leak callbacks against
+     * the process-global meter even after the instance is gone. Production code
+     * paths (`build-lookup-npm-package`) leave this unset so the gauge wires up
+     * normally.
+     */
+    skipMetrics?: boolean;
+}
+/**
+ * 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 `mode: "fail-closed"` with
+ *        `reason: "registry_unreachable"` — 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, transient unreachable) or doesn't cover the requested name
+ * (scoped-only mappings, no default, no scope match).
+ *
+ * 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 declare class NpmPackageLookup {
+    private readonly client;
+    private readonly fetchImpl;
+    private readonly nowFn;
+    private readonly ttlMs;
+    private readonly fetchTimeoutMs;
+    private readonly cache;
+    /**
+     * 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.
+     */
+    private readonly inFlight;
+    /**
+     * 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.
+     */
+    private readonly gauge?;
+    private readonly 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.
+     */
+    private readonly evictionCounter?;
+    constructor(deps?: NpmPackageLookupDeps);
+    /**
+     * 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(): void;
+    lookup(name: string): Promise<NpmPackageLookupResult>;
+    /**
+     * 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(): number;
+    /**
+     * 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.
+     */
+    private evictToCapacity;
+    /**
+     * 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.
+     *
+     * 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).
+     *   - `source: configured | stale`, no scope match, no `config.default`.
+     *     The operator wired scoped-only mappings and the requested name
+     *     doesn't match any of them — there's no in-policy destination, so
+     *     answering from npmjs.org would report availability from the wrong
+     *     trust boundary. Same shape as the other two: surface the gap to
+     *     the agent rather than silently downgrading.
+     */
+    private resolveRegistry;
+    private fetchAndMap;
+}
+//# sourceMappingURL=npm-package-lookup.d.ts.map

package/dist/ai-service/app-interface/npm-package-lookup.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"npm-package-lookup.d.ts","sourceRoot":"","sources":["../../../src/ai-service/app-interface/npm-package-lookup.ts"],"names":[],"mappings":"AASA,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,aAAa,CAAC;AAC3D,OAAO,KAAK,EAAE,iBAAiB,EAAqB,MAAM,mBAAmB,CAAC;AAE9E;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,MAAM,MAAM,oBAAoB,GAAG,SAAS,GAAG,YAAY,GAAG,aAAa,CAAC;AAE5E;;;;;;;;;;;;;;GAcG;AACH,MAAM,WAAW,sBAAsB;IACrC,SAAS,EAAE,OAAO,CAAC;IACnB,IAAI,EAAE,oBAAoB,CAAC;IAC3B,MAAM,CAAC,EAAE,uBAAuB,CAAC;IACjC,aAAa,EAAE,MAAM,CAAC;IACtB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,eAAe,CAAC,EAAE,MAAM,EAAE,CAAC;CAC5B;AAED,MAAM,WAAW,oBAAoB;IACnC;;;;OAIG;IACH,MAAM,CAAC,EAAE,iBAAiB,CAAC;IAC3B,gEAAgE;IAChE,KAAK,CAAC,EAAE,OAAO,UAAU,CAAC,KAAK,CAAC;IAChC,uEAAuE;IACvE,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;IACnB,2DAA2D;IAC3D,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,uDAAuD;IACvD,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB;;;;;;OAMG;IACH,WAAW,CAAC,EAAE,OAAO,CAAC;CACvB;AAmOD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2EG;AACH,qBAAa,gBAAgB;IAC3B,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAgC;IACvD,OAAO,CAAC,QAAQ,CAAC,SAAS,CAA0B;IACpD,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAe;IACrC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAS;IAC/B,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAS;IACxC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAGlB;IACJ;;;;;;;;;;;;;;;;OAgBG;IACH,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAGrB;IACJ;;;;;OAKG;IACH,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAkB;IACzC,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAC,CAEpB;IACX;;;;;OAKG;IACH,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAC,CAAU;gBAE/B,IAAI,GAAE,oBAAyB;IA0B3C;;;;;;;;;OASG;IACH,OAAO,IAAI,IAAI;IAMT,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,sBAAsB,CAAC;IA+E3D;;;;;OAKG;IACH,IAAI,IAAI,MAAM;IAId;;;;;;;;;;;;;;;;;;;;OAoBG;IACH,OAAO,CAAC,eAAe;IAwCvB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAiDG;YACW,eAAe;YAgFf,WAAW;CA4F1B"}