@superblocksteam/vite-plugin-file-sync 1.99.99-next.3 → 2.0.0-SNAPSHOT.84af65cd215b6ca1

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

@@ -0,0 +1,338 @@
+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`,
+ *     or a transient cold-cache `source: unreachable` for a
+ *     previously-configured org). We deliberately do NOT downgrade to public
+ *     npm in these — `available` will be `false` with
+ *     `reason: "registry_unreachable"` and `registry_host` will be empty.
+ *     A configured-but-scoped-only org whose mappings don't cover the name
+ *     is NOT fail-closed: it resolves to "public-npm", matching what
+ *     `npm install` of an unscoped name does under the synthesized `.npmrc`.
+ *
+ * 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` and keeping
+ * `latest_version` when the cap would otherwise exclude it. 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[];
+}
+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;
+    /**
+     * Organization id, surfaced ONLY on the `npm_registry.lookup_package` span
+     * (per-trace context, never a metric label). Threaded from AiService where
+     * `config.organizationId` is in scope; absent in tests / when there is no
+     * org context.
+     */
+    orgId?: string;
+}
+/** 7-day new-release hold-back window (pnpm minimumReleaseAge / Renovate precedent). */
+export declare const QUARANTINE_WINDOW_MS: number;
+/**
+ * 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 declare function selectQuarantineHoldback(args: {
+    nowMs: number;
+    publishTimes: Record<string, string | number>;
+    version: string;
+    windowMs?: number;
+}): string | undefined;
+/**
+ * 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 declare class NpmPackageLookup {
+    private readonly client;
+    private readonly orgId;
+    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;
+    /**
+     * 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.
+     */
+    lookup(name: string): Promise<NpmPackageLookupResult>;
+    /**
+     * 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.
+     */
+    pickQuarantineHoldback(name: string, version: string): Promise<string | 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).
+     */
+    private observeLookupTool;
+    private lookupImpl;
+    /**
+     * 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.
+     *   - `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).
+     */
+    private resolveRegistry;
+    private fetchAndMap;
+}
+export {};
+//# 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":"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"}