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

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

@@ -0,0 +1,913 @@
+/**
+ * Wire shape for a single registry row returned by
+ * `GET /api/v1/organizations/:orgId/npm-registry`. Mirrors the server's
+ * `OrgNpmRegistryDto` (see
+ * `packages/server/src/controllers/v1/orgNpmRegistry/handlers.ts`).
+ *
+ * `scope === null` is the default (unscoped) registry; otherwise it is a
+ * single npm scope like `"@mycompany"`.
+ *
+ * `registryUrl` is the Superblocks npm proxy URL (the server rewrites each
+ * row to it). There is no token here: the auth token is the machine's own
+ * Superblocks login, stamped in by `registriesToConfig`, not a per-registry
+ * secret.
+ */
+export interface NpmRegistryEntry {
+    id: string;
+    scope: string | null;
+    registryUrl: string;
+}
+/**
+ * Renderable npm registry configuration. This is the shape `writeNpmrc`
+ * consumes — it is independent of where it came from (server fetch in
+ * production; constructed in tests). For a configured org, `default` is
+ * populated; for an org with no registries, both fields are empty and
+ * `configured` is false.
+ */
+export interface NpmRegistryConfig {
+    /** True if at least one registry is configured for the org. */
+    configured: boolean;
+    /** Default (unscoped) registry URL + optional token. */
+    default?: {
+        url: string;
+        token?: string;
+    };
+    /**
+     * Scoped registries keyed by scope (e.g. `"@mycompany"`).
+     * Tokens are kept alongside so `writeNpmrc` can emit per-scope
+     * `_authToken=` lines.
+     */
+    scopes?: Record<string, {
+        url: string;
+        token?: string;
+    }>;
+    /**
+     * Org-level npm policy: `false` means AppShell appends `--ignore-scripts`
+     * to every npm/pnpm invocation; `true` or `undefined` keeps the default
+     * behaviour. Independent of `configured` — an org can set the policy
+     * without configuring any registry rows (in which case `configured` is
+     * false but the policy still flows through). Originates from the
+     * `superblocks.npm-registry.enabled` LD-flag-gated field on the server
+     * (APPS-4250); undefined when the flag is off or the server omits it.
+     */
+    allowInstallScripts?: boolean;
+}
+/**
+ * Logical outcome of `NpmRegistryClient.getConfig()`. The discriminator lets
+ * callers branch cleanly on the four cases without inspecting the cache
+ * itself.
+ *
+ *   - `configured`: at least one registry row exists for the org; render
+ *     `.npmrc` lines from `config`.
+ *   - `not-configured`: a successful server observation said the org has
+ *     no registry rows (flag off, 404, or empty `registries: []`). Caller
+ *     can act on this as deliberate steady-state — e.g. cleanup of a
+ *     previously-written `.npmrc`. Downstream `require` enforcement (when
+ *     wired) decides whether to refuse npm.
+ *   - `stale`: server unreachable, returning last-known-good non-empty
+ *     entries. Same render path as `configured`, but the source field
+ *     distinguishes it for observability and tests.
+ *   - `unreachable`: server unreachable AND we have no usable cache (cold
+ *     start or only an empty observation). `config.configured` is false so
+ *     write-side consumers (`maybeWriteNpmrcForDir`, `prepareForPrivateRegistry`)
+ *     no-op safely. Distinct from `not-configured` so consumers with
+ *     destructive cleanup paths (e.g. `syncHomeNpmrc`) can refuse to act
+ *     on what is really "we don't know" rather than "deliberately unset".
+ */
+export type NpmRegistryFetchResult = {
+    source: "configured";
+    config: NpmRegistryConfig;
+} | {
+    source: "stale";
+    config: NpmRegistryConfig;
+} | {
+    source: "not-configured";
+    config: NpmRegistryConfig;
+} | {
+    source: "unreachable";
+    config: NpmRegistryConfig;
+    /**
+     * APPS-4370. True if a `LastKnownRegistryPolicyStore` was wired into
+     * the `NpmRegistryClient` and reported that this org had at some prior
+     * point successfully resolved a configured registry (i.e. a marker file
+     * exists on disk). Used by AppShell install paths to fail closed with
+     * `NpmInstallBlocked(registry_unreachable)` rather than silently
+     * resolving through public npm during a server outage.
+     *
+     *   - `true`      — store reports a prior successful fetch; the install
+     *                   path MUST refuse to spawn npm.
+     *   - `false`     — store has no marker (first-install / greenfield);
+     *                   the install path proceeds as before so cold-boot
+     *                   first-time users are not blocked.
+     *   - `undefined` — no store was wired in at all (test fixtures, older
+     *                   call sites). Install path falls back to current
+     *                   behaviour (proceed).
+     */
+    everConfigured?: boolean;
+};
+/**
+ * APPS-4370. Disk-backed per-org "this org has at some point been configured
+ * with a private npm registry" marker. The CLI's `NpmRegistryClient` writes
+ * the marker on every `configured` / `stale` resolution and reads it on
+ * `unreachable` so AppShell's install paths can fail closed with
+ * `NpmInstallBlocked(registry_unreachable)` on a server outage — rather than
+ * silently resolving through public npm with a possibly-stale managed
+ * `.npmrc`.
+ *
+ * Implementations MUST be best-effort: a write failure (disk full,
+ * permission denied) MUST NOT throw, and a read failure MUST resolve to
+ * `false` rather than rejecting. Either is a strict superset of today's
+ * behaviour (no marker → proceed), so a broken store keeps the install
+ * path healthy.
+ */
+export interface LastKnownRegistryPolicyStore {
+    /** Persist the per-org marker. Best-effort; never throws. */
+    markConfigured(): Promise<void>;
+    /** Remove the per-org marker. Best-effort; never throws. */
+    clearConfigured(): Promise<void>;
+    /** True if the marker is present. Best-effort; resolves to false on error. */
+    hasEverBeenConfigured(): Promise<boolean>;
+}
+/**
+ * Resolves the org `allow_install_scripts` policy from a `prepareForPrivateRegistry`
+ * (or `maybeWriteNpmrcForDir`) result. `false` means "the org has explicitly
+ * disabled npm install scripts" — install entrypoints append `--ignore-scripts`.
+ * `true` or `undefined` (server omitted the field, LD flag off, no client wired
+ * up) keeps today's behaviour.
+ *
+ * Shared by AppShell install entrypoints (shell.ts) and the dev-server startup
+ * install (sdk/cli-replacement/dev.mts) so both paths interpret the policy
+ * identically.
+ */
+export declare function shouldIgnoreInstallScripts(result: NpmRegistryFetchResult | undefined): boolean;
+/**
+ * True only when `registryUrl` is genuinely the Superblocks npm proxy for THIS
+ * org on THIS server (matching origin AND the org-scoped `/npm-proxy` path).
+ *
+ * The client stamps the machine's own Superblocks login token onto every row
+ * `/config` returns. That is only safe if every row really is our proxy: a
+ * version-skewed or misconfigured server could return a customer's upstream
+ * registry URL (or a broken one built from an empty external-server URL), and
+ * blindly stamping the login token onto that would leak a Superblocks
+ * credential to a third-party host. So the client proves the proxy invariant
+ * before stamping and fails closed when it does not hold.
+ *
+ * Compares parsed origin + pathname (not a raw string prefix) so trailing
+ * slashes and default ports can't cause a false negative, and requires a path
+ * boundary so a lookalike like `…/npm-proxyEVIL` can't slip through. Also
+ * rejects anything the canonical proxy URL never carries — embedded
+ * userinfo (`https://user:pass@host/…` shares the host's `origin` but is not
+ * our proxy URL) and any query/fragment — so a crafted URL can't satisfy the
+ * origin check while smuggling something else into `.npmrc`.
+ */
+export declare function isSuperblocksNpmProxyUrl(registryUrl: string, baseUrl: string, organizationId: string): boolean;
+/**
+ * True when on-disk `.npmrc` / `.npmrc.default` content routes installs
+ * through this org's Superblocks npm proxy.
+ *
+ * Origin is intentionally NOT required: live-edit pods write
+ * cluster-local hosts (`server.superblocks.svc.cluster.local`) while the
+ * client `baseUrl` is often the public URL. Path + org id is the durable
+ * ownership signal for both rewrite and delete. Path boundary required so
+ * a lookalike like `…/npm-proxyEVIL` cannot match.
+ *
+ * Scans every occurrence (a first lookalike must not hide a later genuine
+ * line). Requires the hit to sit on a non-comment `registry=` /
+ * `@scope:registry=` / `:_authToken=` line so a comment mentioning the
+ * path does not classify a customer file as ours.
+ *
+ * Used by `maybeWriteNpmrcForDir` to decide whether a project-dir file is
+ * safe to reconcile (stale PVC `.npmrc` after registry delete or expired
+ * JWT).
+ */
+export declare function isSuperblocksAuthoredNpmrcContent(content: string, organizationId: string): boolean;
+export declare function registriesToConfig(entries: NpmRegistryEntry[], allowInstallScripts?: boolean, authToken?: string): NpmRegistryConfig;
+/**
+ * Dependencies the `NpmRegistryClient` needs to fetch from the server.
+ * Injected so the client itself stays free of `fs`, `~/.superblocks/auth.json`
+ * parsing, and LaunchDarkly client wiring — those live at the dev-server
+ * entrypoint / CLI bootstrap layer and are exercised by their own tests.
+ */
+export interface NpmRegistryClientDeps {
+    /**
+     * Returns true if the `superblocks.npm-registry.enabled` LaunchDarkly
+     * flag is on for the active org. Called on every `getConfig()` because LD
+     * flag flips must propagate within the LD poll interval without a process
+     * restart (see APPS-4228 acceptance).
+     *
+     * Synchronous on purpose: the caller has already evaluated the flag
+     * against the org context; the client just reads the current value.
+     */
+    isFlagEnabled: () => boolean;
+    /**
+     * Returns the current user JWT for the active dev-server session.
+     * Called once per fetch attempt; on 401 the client first awaits
+     * `refreshJwt` (if provided) and then re-invokes this for the retry.
+     */
+    getJwt: () => Promise<string>;
+    /**
+     * Optional hook the client awaits between a 401 and its retry. The
+     * intended implementation subscribes once to a push-based token
+     * refresh signal (e.g. `tokenManager`'s `tokenUpdated` event) with a
+     * short timeout, so the retry has a fair chance of picking up a
+     * freshly-rotated JWT.
+     *
+     * If omitted, the client retries immediately with the next `getJwt()`
+     * read — useful for tests and for environments where no push-based
+     * refresh exists. The retry still benefits from any external refresh
+     * that happens to have landed by the time `getJwt()` is re-read; it
+     * just isn't given the chance to wait.
+     *
+     * Errors thrown by `refreshJwt` are treated as transient: the client
+     * routes through `serveStaleOrUnconfigured` rather than crashing the
+     * install path on a refresh-channel hiccup.
+     */
+    refreshJwt?: () => Promise<void>;
+    /** Active organization id. */
+    organizationId: string;
+    /**
+     * Base URL of the Superblocks server (e.g. `https://app.superblocks.com`,
+     * `http://localhost:3000`). The client appends
+     * `/api/v1/organizations/:orgId/npm-registry`.
+     */
+    baseUrl: string;
+    /**
+     * Optional `fetch` override for testing. Defaults to the global `fetch`
+     * available in Node 18+.
+     */
+    fetch?: typeof globalThis.fetch;
+    /**
+     * TTL for the in-memory cache, in milliseconds. Defaults to 5 minutes,
+     * matching the ticket's tunable.
+     */
+    ttlMs?: number;
+    /**
+     * Clock function returning the current time in ms. Defaults to
+     * `Date.now`. Overridable so tests can advance the cache deterministically
+     * without `vi.useFakeTimers()`.
+     */
+    now?: () => number;
+    /**
+     * APPS-4370. Optional disk-backed store the client uses to record that
+     * an org has at some point successfully resolved a configured registry,
+     * and to consult on `unreachable` resolutions so the result can carry
+     * `everConfigured` for the AppShell install fail-closed decision.
+     *
+     * When omitted, the client behaves exactly as before: marker writes are
+     * silently skipped and `unreachable` results carry no `everConfigured`
+     * field. Install paths that key off the field default to "proceed".
+     *
+     * Writes are fire-and-forget: a `markConfigured()` rejection is logged
+     * but never bubbles up to the install path.
+     */
+    lastKnownPolicyStore?: LastKnownRegistryPolicyStore;
+}
+/**
+ * Per-call options for `NpmRegistryClient.getConfig`.
+ */
+interface GetConfigOptions {
+    /**
+     * Skip the in-memory TTL cache and re-fetch from the server. Used by the
+     * just-in-time call sites (`.npmrc` synthesis before an install, package
+     * lookups, home-npmrc sync) so an admin clearing or changing the org's
+     * registry takes effect immediately rather than after the TTL expires.
+     * The last-known-good fallback on a server outage is unaffected — only
+     * the cache-hit read is bypassed.
+     */
+    forceRefresh?: boolean;
+    /**
+     * Freshness floor (ms) for a forced read: serve the cache if it is younger
+     * than this, otherwise re-fetch. Defaults to 0, which means a forced read
+     * always re-fetches (full bypass). Only meaningful when `forceRefresh` is
+     * set. The hot lookup path passes a small floor so a tight sequential batch
+     * of per-package lookups collapses onto one config fetch instead of one per
+     * package; the install/home `.npmrc` boundaries leave it at 0 so they always
+     * observe an admin change immediately.
+     */
+    forceRefreshMaxAgeMs?: number;
+}
+/**
+ * Fetches per-org npm registry configuration from the server, caching the
+ * result in-memory with a short TTL. Designed so callers do not have to
+ * think about the LaunchDarkly flag, JWT lifecycle, or transient server
+ * outages — they just `await client.getConfig()` and get back a renderable
+ * shape (or "not configured").
+ *
+ * Lifecycle invariants (see APPS-4230 scope):
+ *
+ *   1. **Flag off → short-circuit**: returns `{ configured: false }` with
+ *      no network I/O. Lets us dark-ship LinkedIn first without hammering
+ *      the API for the rest of the fleet.
+ *   2. **Cache hit within TTL → no fetch**: avoids per-install round-trips
+ *      against the server.
+ *   3. **401 → await `refreshJwt` then retry once with a fresh
+ *      `getJwt()` read**: any push-based JWT refresh (auth-hot-reload)
+ *      that landed between the original request and the retry is picked
+ *      up. The cache is preserved across the retry so a failed retry
+ *      can still fall back to last-known-good. Two disjoint failure
+ *      modes:
+ *        - The retry itself returns 401 → hard throw. We deliberately do
+ *          not keep retrying because the only way a freshly-read JWT also
+ *          401s is a true re-auth failure.
+ *        - `refreshJwt` itself throws or times out (e.g. the push channel
+ *          hung) → route through `serveStaleOrUnconfigured` (same as a 5xx
+ *          / network outage). A flaky refresh channel must not crash the
+ *          install path, and we never reach the second `attempt()`.
+ *   4. **Other 4xx (403/400/…) → clear the cache and throw**: these are
+ *      deliberate denials (RBAC revocation, malformed request), not
+ *      transient outages. Serving stale would extend the revocation
+ *      window beyond the cache TTL. The error propagates to the caller
+ *      (typically `AppShell` / `TemplateRenderer`), which decides
+ *      whether to fail the install or fall back to public npm.
+ *   5. **5xx or network unreachable + cached value → return cache +
+ *      `logger.warn`**: install workflows continue against the
+ *      last-known-good registry while we surface the outage; strictly
+ *      better than falling back to `registry.npmjs.org` mid-deploy.
+ *   6. **5xx or network unreachable + no usable cache → return
+ *      `source: "unreachable"` with `{ configured: false }`**: cold start
+ *      or only an empty-list cache. `config.configured: false` so
+ *      write-side consumers continue to no-op, but the distinct source
+ *      keeps destructive cleanup paths (home-npmrc unlink) from acting on
+ *      a transient outage.
+ *
+ * The class is intentionally a thin wrapper around a single Map cell — the
+ * cache key is `(organizationId)` since one client serves one org. Sharing
+ * one client across orgs would require per-org cache keys; we don't do
+ * that today because the dev-server pod is single-tenant.
+ */
+export declare class NpmRegistryClient {
+    private readonly deps;
+    /**
+     * Last successful fetch + when it landed. Source of both the TTL check
+     * and the last-known-good fallback. We deliberately store the entries as
+     * received (not the rendered `NpmRegistryConfig`) so future readers can
+     * apply different render policies without a re-fetch.
+     *
+     * `npmAllowInstallScripts` rides alongside because the server returns it
+     * on the same envelope and AppShell wants the same TTL/fallback semantics
+     * for both. `undefined` here means the server omitted the field (LD flag
+     * off on the server side, or older server); we propagate that as
+     * `allowInstallScripts: undefined` rather than defaulting to `true` so
+     * the consumer can distinguish "policy known, scripts allowed" from
+     * "policy unknown".
+     */
+    private cache;
+    /**
+     * Inflight `fetchWithRefresh()` promise, if any. Used to deduplicate
+     * concurrent `getConfig()` callers during a cache miss (or stale-after-
+     * TTL re-fetch): rather than firing N network requests for N callers
+     * we share the single in-flight request. Cleared in a `.finally()` so a
+     * resolved or rejected fetch never sticks around.
+     *
+     * Without this, a burst of installs that all hit cold cache would race
+     * to the server, the first one's 401 would clear the cache for itself
+     * before the others observe their own 401s — and the others would
+     * then have no last-known-good to fall back to.
+     */
+    private inflight;
+    /**
+     * Last `npmAllowInstallScripts` value observed from a successful server
+     * response, retained across hard-fail cache invalidations (refreshJwt
+     * rejection, double-401, other 4xx). Registry credentials and the
+     * security policy live on the same envelope but have different
+     * security semantics: serving stale credentials to a revoked caller
+     * extends a deliberate denial, but dropping a known `false` policy
+     * silently weakens `--ignore-scripts` enforcement — strictly the
+     * wrong direction. So `this.cache` is cleared on hard-fail (revoke
+     * stale credentials), but this field survives so the next call's
+     * fall-through `serveStaleOrUnconfigured` still propagates the
+     * org's policy to AppShell.
+     */
+    private lastKnownPolicy;
+    constructor(deps: NpmRegistryClientDeps);
+    /**
+     * Organization id this client serves. Read-only; surfaced so the
+     * `npm_registry.prepare_for_private_registry` span (APPS-4378) can carry
+     * `org_id` without the standalone `prepareForPrivateRegistry` helper having
+     * to thread it through its signature.
+     */
+    get organizationId(): string;
+    /**
+     * Clears the in-memory cache so the next `getConfig()` re-fetches from
+     * the server. Called by AppShell install retry when
+     * `registry_auth_failed` indicates a stale Artifactory token.
+     *
+     * `lastKnownPolicy` survives invalidation (same as the auth-failure
+     * branches in `fetchWithRefresh`) so `--ignore-scripts` enforcement
+     * is not weakened during the re-fetch.
+     */
+    invalidateCache(): void;
+    /**
+     * Persist the "ever configured" marker, AWAITED so the write is durable
+     * before the caller hands back a `configured` / `stale` resolution. Used
+     * on every such resolution so a subsequent server outage can fail closed
+     * instead of silently resolving through public npm.
+     *
+     * Awaited (not fire-and-forget) because the marker must be on disk before
+     * `getConfig()` returns: a crash in the gap between returning `configured`
+     * and an un-awaited write landing would lose the marker and silently break
+     * the "once configured, always fail-closed on unreachable" invariant. The
+     * write stays async (`fs/promises`, per the ai-service no-sync-fs rule);
+     * the disk store guards itself so the write happens at most once per
+     * process (see `createDiskRegistryPolicyStore`), keeping the awaited write
+     * off the hot path after the first configured resolution.
+     *
+     * Logs a warning on write failure but never propagates the error: a broken
+     * store is a strict superset of today's no-marker behaviour, and the
+     * install path must stay healthy when disk is full or the marker directory
+     * is unwritable.
+     */
+    private markPolicyConfigured;
+    /**
+     * Drop the marker when a fresh fetch proves the org has no registry rows.
+     * Mirrors `markPolicyConfigured`: best-effort, warns on failure, never
+     * propagates. A store that cannot clear leaves today's fail-closed
+     * behaviour in place.
+     */
+    private clearPolicyConfigured;
+    /**
+     * Read the disk-backed marker that AppShell uses to decide whether to
+     * fail closed on `unreachable`. Treats a read failure as `false` so a
+     * transient store IO error preserves current behaviour (proceed) rather
+     * than degrading to a fail-closed install.
+     */
+    private readEverConfigured;
+    /**
+     * Resolve the current npm registry configuration for the active org. See
+     * the class docstring for the full state machine.
+     *
+     * `forceRefresh` bypasses the TTL cache-hit return below so a just-in-time
+     * caller (the `.npmrc` writer before an install, a package lookup, the
+     * home-npmrc sync) observes an admin clearing or changing the registry
+     * immediately instead of waiting out the TTL. `forceRefreshMaxAgeMs` lets a
+     * high-frequency caller (the package lookup) keep a small freshness floor so
+     * a tight sequential batch collapses onto one fetch; left at 0 (install /
+     * home sync) a forced read always re-fetches. It does NOT touch the cache
+     * before fetching: `serveStaleOrUnconfigured` still needs the last-known-good
+     * entries to fall back to during a 5xx/network outage. The flag-off
+     * short-circuit, inflight dedup, and all hard-fail branches behave
+     * identically.
+     */
+    getConfig(options?: GetConfigOptions): Promise<NpmRegistryFetchResult>;
+    private fetchWithRefresh;
+    /**
+     * One full fetch attempt with the current JWT. Throws on getJwt failure
+     * OR network failure so the caller's single try/catch handles both.
+     */
+    private attempt;
+    /**
+     * Signal when `lastKnownPolicy` supplied the install-scripts policy that the
+     * in-memory cache could not (`cachePolicy == null && lastKnownPolicy !=
+     * null`). That combination means an earlier auth-failure or 4xx branch wiped
+     * the cache and we fell back to the surviving policy, which is a sign
+     * something went wrong. Emit a WARN (with `orgId` and which branch ran) plus
+     * a low-cardinality counter so it can be alerted on from a dashboard without
+     * digging through logs or traces. `cachePolicy` is passed in (not re-read)
+     * because the 404 branch overwrites `this.cache` before this runs.
+     */
+    private signalPolicyFallback;
+    /**
+     * Render cached/fetched entries into a config, stamping the machine's current
+     * Superblocks login token onto every proxied registry (`registryUrl` is the
+     * proxy URL the server rewrote each row to). Read fresh each call so the
+     * `.npmrc` the caller writes right after carries a current token. `getJwt()`
+     * resolves immediately when a token is already primed, so this stays cheap on
+     * the cache-hit fast path; it throws only when no token is available, in
+     * which case there is no way to build a working proxy `.npmrc`.
+     */
+    private renderConfig;
+    /**
+     * Build a `configured` result, but route a JWT-read failure through the same
+     * fail-closed path as `serveStaleOrUnconfigured`. `renderConfig` reads the
+     * login token via `getJwt()`, which can reject (no token primed). A missing
+     * token is the same "we can't build a working proxy `.npmrc`" condition the
+     * stale path already treats as `unreachable`, so both the cache-hit and the
+     * fresh-fetch success paths must resolve it the same way rather than throwing
+     * out of `getConfig()`. With a warm cache this serves last-known-good; with
+     * no usable cache it reports `unreachable`.
+     */
+    private renderConfigured;
+    private serveStaleOrUnconfigured;
+}
+interface WriteNpmrcOptions {
+    /**
+     * POSIX file mode for the written `.npmrc`. Defaults to `0o600` (owner
+     * read/write) because the per-install-site writers rewrite the file on
+     * every install; the immutability angle doesn't apply there. Callers that
+     * own a persistent file users should not clobber (e.g. the home-level
+     * writer at APPS-4231) pass `0o400` to drop the owner write bit. Atomic
+     * rename in this writer is governed by parent-dir perms, not the target
+     * file mode, so a stricter mode does not interfere with subsequent
+     * re-writes from the same caller.
+     */
+    mode?: number;
+    /**
+     * Optional plain-text header written as the first line of the file,
+     * prefixed with `; ` so npm and `ini.parse` treat it as a comment. Used as
+     * an in-band ownership marker so a delete-on-unset path can tell a file
+     * this writer created apart from one the operator hand-maintains. Must
+     * not contain `\r` or `\n`.
+     */
+    header?: string;
+}
+/**
+ * Renders the npm registry config to an `.npmrc` file at `targetPath`.
+ *
+ * Uses `ini.stringify` (the same library `@npmcli/config` uses to read and
+ * write `.npmrc`) so the file is guaranteed to round-trip through
+ * `ini.parse`. This handles value-quoting for `=`, `\r`, `\n`, leading `[`,
+ * leading/trailing whitespace, and escapes `;` / `#` so they're not treated
+ * as comments.
+ *
+ * Validation NOT covered by `ini`:
+ *   - `noControlChars` Zod refinement: `ini.safe` JSON-quotes `\r`/`\n`
+ *     rather than rejecting them, and accepts other C0 control bytes
+ *     (`\x00..\x1f`) unchanged — so we reject the entire C0 range at the
+ *     wire-schema layer instead.
+ *   - Scope grammar (`@scope` must match npm's regex): `@npmcli/config`
+ *     does not validate scope names.
+ *   - https-only registry URLs: npm itself accepts http.
+ *
+ * Idempotent: rewrites the file in full each call. Writes are atomic (tmp +
+ * rename) and the file mode is restricted to 0600 because the file may carry
+ * an auth token.
+ *
+ * Requires `config.configured === true` OR `config.allowInstallScripts === false`
+ * (so the writer can emit a policy-only `.npmrc` with just `ignore-scripts=true`
+ * even when no registry rows are configured). A scoped-only config (no `default`
+ * entry) is valid — only scope `:registry=` lines are emitted, and unscoped
+ * packages fall through to public npm. This matches the server contract
+ * (the `(org, scope)` unique constraint allows scoped-only rows) and is
+ * the right shape for customers who only want to override one `@scope`
+ * without redirecting the rest of npm.
+ */
+export declare function writeNpmrc(targetPath: string, config: NpmRegistryConfig, options?: WriteNpmrcOptions): Promise<void>;
+/**
+ * Filename of the on-disk backup of the baked-in `.npmrc` that ships with the
+ * dev-server image. Captured once per pod boot by `maybeWriteNpmrcForDir`
+ * before the first `writeNpmrc` rewrite, then used as the restore source when
+ * the org transitions back to `not-configured` (e.g. the last
+ * `org_npm_registry` row was deleted). Lives sibling to `.npmrc` in the same
+ * directory writes target.
+ */
+export declare const NPMRC_DEFAULT_FILENAME = ".npmrc.default";
+/**
+ * Outcome of a `snapshotInitialNpmrc` attempt. Lets a caller decide
+ * whether a usable backup now exists before it acts on the symmetric
+ * restore path — in particular, whether it is safe to ask
+ * `restoreInitialNpmrc` to UNLINK a Superblocks-owned target when the
+ * backup turns up missing.
+ *
+ *   - `created`   — this call wrote the hardlink; the backup is now present
+ *                   and holds the baked-in baseline.
+ *   - `exists`    — the backup was already present (prior boot, or a
+ *                   concurrent caller won the race). A usable backup exists.
+ *   - `no-source` — `targetPath` had no baked-in file to snapshot (ENOENT).
+ *                   The natural restore baseline is "no file"; there is
+ *                   nothing to back up and nothing to restore to.
+ *   - `failed`    — the snapshot was attempted against a real target but
+ *                   `link(2)` failed for a reason other than EEXIST/ENOENT
+ *                   (e.g. EXDEV when target and backup straddle filesystems).
+ *                   A baked-in file existed but NO backup was produced — the
+ *                   restore path must NOT treat a missing backup as "nothing
+ *                   to preserve" and unlink the target.
+ */
+export type SnapshotInitialNpmrcOutcome = "created" | "exists" | "no-source" | "failed";
+/**
+ * Snapshot `targetPath` to `backupPath` exactly once if the backup does
+ * not already exist. Lets a subsequent `writeNpmrc`-style rewrite of
+ * `targetPath` happen non-destructively: a restore path has a baked-in
+ * source to copy back when the org transitions to `not-configured`.
+ *
+ * Uses `link(2)` rather than read + write so the snapshot is concurrency-
+ * safe. Two properties matter:
+ *
+ *   - The kernel serializes hardlink creation: only one of N concurrent
+ *     callers wins; the rest see EEXIST. No read-then-write window where
+ *     a slow caller could observe a `writeNpmrc`-rewritten target and
+ *     poison the backup with the private registry content.
+ *   - `writeNpmrc` rewrites the target via tmp + rename, which gives it
+ *     a fresh inode. The hardlink at `backupPath` keeps the original
+ *     inode (with the baked-in content) alive — that's the whole point.
+ *
+ * Silently no-ops in two cases:
+ *   - `backupPath` is already present (subsequent boots, or a second
+ *     call in the same boot after the first capture landed). Important so
+ *     a later `writeNpmrc`-rewritten target is never mistaken for the
+ *     baked-in baseline.
+ *   - `targetPath` does not exist (image without a baked-in `.npmrc`,
+ *     or a brownfield app dir that never had one). The natural "restore"
+ *     state is "no file", which the restore path handles by treating an
+ *     absent backup as "no file" too — for that case `restoreInitialNpmrc`
+ *     unlinks the target if asked, otherwise leaves it alone.
+ *
+ * Other errors degrade to a warning + no-op rather than throwing — the
+ * capture is a best-effort safety net for the restore path, not a
+ * precondition for the install path itself.
+ *
+ * Returns a `SnapshotInitialNpmrcOutcome` so a caller can tell whether a
+ * usable backup now exists. This matters for the destructive restore path:
+ * a silent `failed` (e.g. EXDEV) leaves no backup behind, so a later
+ * `not-configured` transition must NOT mistake the absent backup for
+ * "nothing to preserve" and unlink a real baked-in userconfig (APPS-4428).
+ * Still never throws — the outcome is advisory, not an error channel.
+ *
+ * Shared with the home-npmrc writer (CLI startup, target =
+ * `~/.superblocks/npmrc`) so both project-dir and home flows agree on the
+ * snapshot/restore semantics.
+ */
+export declare function snapshotInitialNpmrc(targetPath: string, backupPath: string): Promise<SnapshotInitialNpmrcOutcome>;
+interface RestoreInitialNpmrcOptions {
+    /**
+     * When `true`, missing backup AND a present target file means "remove
+     * the target": the caller owns the target file and has no image-baked
+     * baseline to fall back to, so leaving a stale rewrite in place would
+     * be wrong. The home-npmrc writer (`~/.superblocks/npmrc`) passes this
+     * because the file is Superblocks-owned — nothing else should be
+     * reading from it, and leaving a stale configured-org registry/auth
+     * after a transition to `not-configured` is the exact case
+     * `gpoulios-sb` flagged on APPS-4328.
+     *
+     * When `false` (the default), missing backup means "leave the target
+     * alone": the caller (project `.npmrc`) shares the file with template
+     * tooling and lockfile-aware installs; an empty or absent file would
+     * break unrelated callers. This is the original APPS-4320 semantics.
+     */
+    unlinkTargetWhenBackupMissing?: boolean;
+}
+/**
+ * Restore `targetPath` from `backupPath` when the org has transitioned
+ * back to `not-configured` (e.g. last `org_npm_registry` row deleted).
+ * Without this, a file previously rewritten by `writeNpmrc` stays in
+ * place pointing at a registry the customer just removed — the exact
+ * case APPS-4320 closes for project `.npmrc`, and APPS-4328 closes for
+ * the home-level userconfig.
+ *
+ * Best-effort, never throws. The project-dir caller
+ * (`maybeWriteNpmrcForDir` → `prepareForPrivateRegistry`) needs to fall
+ * through to `stripResolvedFromLockfile` even when the restore can't
+ * run; the home-level caller (`syncHomeNpmrc`) needs to finish dev-server
+ * startup. Any error here degrades to a warn + no-op so the surrounding
+ * install path stays alive.
+ *
+ * Skips the rewrite (without a warning) in three harmless cases:
+ *   - `targetPath` does not exist. The baked-in baseline for this dir is
+ *     "no file"; there is nothing to restore to.
+ *   - `backupPath` is missing AND `options.unlinkTargetWhenBackupMissing`
+ *     is not set. Expected on pods that never had `org_npm_registry`
+ *     configured (snapshot is gated on the configured branch), AND on
+ *     older pods whose target was rewritten before this commit landed.
+ *     In both cases the running file is what the pod has lived with —
+ *     leave it alone.
+ *   - `targetPath` already byte-matches `backupPath`. Avoids a no-op
+ *     rewrite that would bump mtime for downstream watchers (e.g. Tilt /
+ *     Vite file-sync).
+ *
+ * When `options.unlinkTargetWhenBackupMissing` is true and the backup is
+ * absent but the target exists, the target is unlinked — see the option
+ * comment.
+ */
+export declare function restoreInitialNpmrc(targetPath: string, backupPath: string, options?: RestoreInitialNpmrcOptions): Promise<void>;
+/**
+ * Outcome of `ensureNpmrcGitignored`. The caller's fail-closed decision is
+ * `!ignored`: any state in which we cannot positively guarantee that
+ * `.npmrc` is ignored from `<dir>` — whether `.git` exists today or not —
+ * blocks the credential write. `hasGit` is retained for logging /
+ * diagnostics so warnings can distinguish the "native git can stage on the
+ * next commit" case from the "no native git today, but a future `git init`
+ * would stage" case.
+ */
+interface EnsureNpmrcGitignoredResult {
+    /**
+     * True iff `.npmrc` is now positively known to be ignored from `<dir>`.
+     * The bar depends on whether a `.git` is present:
+     *
+     *   - Native git (`<dir>/.git` exists): an ignore entry was written
+     *     (`<dir>/.gitignore` or the per-clone `<dir>/.git/info/exclude`) AND
+     *     `git check-ignore .npmrc` confirms the file is effectively ignored
+     *     (catches later `!.npmrc` negations) AND `git ls-files .npmrc` shows
+     *     the file is not already tracked (an ignore line does not protect a
+     *     file already in the index).
+     *
+     *   - Non-native (no `<dir>/.git`): `<dir>/.gitignore` was appended to
+     *     OR created with the `.npmrc` line. We create `.gitignore` even
+     *     when none exists so a subsequent `git init` in the same dir is
+     *     future-safe: a customer who later turns on native git for an app
+     *     where a credential-bearing `.npmrc` already sits on disk would
+     *     otherwise stage the token on their first `git add .` before any
+     *     install path re-runs this helper. Returns `false` only when the
+     *     `.gitignore` write itself fails (rare — disk full, permission
+     *     denied, `.gitignore` is a directory); in that case the caller MUST
+     *     refuse to write the credential-bearing `.npmrc`, because the
+     *     future-git leak path the reviewer flagged is still open (a later
+     *     `git init` finds the token on disk with no ignore rule).
+     */
+    ignored: boolean;
+    /** True iff `<dir>` is inside any git working tree — either because
+     * `<dir>/.git` exists OR because a parent directory has `.git` (nested-repo
+     * layout). Diagnostic only — the fail-closed decision in
+     * `maybeWriteNpmrcForDir` is `!ignored`, regardless of `hasGit`. The
+     * nested-repo case matters because a parent's `git add .` will stage
+     * `<dir>/.npmrc` unless an ignore rule excludes it; see PR #19642 review
+     * from cursor[bot]. */
+    hasGit: boolean;
+}
+/**
+ * Ensure `.npmrc` is git-ignored from `<dir>` before any credential-bearing
+ * `.npmrc` is written.
+ *
+ * Why this matters: `maybeWriteNpmrcForDir` writes a `.npmrc` containing
+ * `//host/:_authToken=<the machine's Superblocks login token>` at the app
+ * root. That token authenticates to the Superblocks npm proxy; the
+ * customer's upstream registry password is held server-side and never
+ * reaches disk. It is still a Superblocks credential, so it must not be
+ * committed. The DBFS sync already excludes `.npmrc` from upload
+ * (`codeModeExcludedFiles` in `file-system-helpers.ts`), but the native-git
+ * path calls `git.add(".")` (socket-manager `gitCommitLocal`/`gitPull`,
+ * agent `git`/`git_raw` tools) which stages everything not listed in the
+ * app's on-disk ignore. Without this enforcement, a customer with a
+ * configured private registry pushes that login `_authToken` to their
+ * external git remote on the next commit. The
+ * template `.gitignore` covers new apps; this helper covers the existing
+ * fleet whose `.gitignore` predates the registry feature.
+ *
+ * Behaviour, in three layers:
+ *
+ *   1. Non-native-git (`<dir>/.git` does not exist):
+ *      - Append `.npmrc` to `<dir>/.gitignore`, or create the file if
+ *        it doesn't exist. We create `.gitignore` here (not just when
+ *        `.git` already exists) so a subsequent `git init` in the same
+ *        directory is future-safe: a customer who later turns on native
+ *        git for an app where a credential-bearing `.npmrc` already
+ *        sits on disk would otherwise stage the token on their first
+ *        `git add .` before any install path re-runs this helper.
+ *      - On success return `{ ignored: true, hasGit: false }`. On a
+ *        read or write failure (`.gitignore` is a directory, disk full,
+ *        permission denied) return `{ ignored: false, hasGit: false }`.
+ *        The caller MUST refuse to write the credential-bearing
+ *        `.npmrc` in that case: even though no native git checkout
+ *        exists today, a later `git init` (or wiring this dir into an
+ *        existing repo) would find the on-disk token and stage it on
+ *        the first `git add .` — exactly the future-git leak path
+ *        gpoulios-sb flagged in code review.
+ *
+ *   2. Native-git (`<dir>/.git` exists), `.gitignore` path:
+ *      - Read or create `.gitignore`, append `.npmrc` if missing. After
+ *        the append, verify with git itself (`verifyNpmrcIgnoredByGit`)
+ *        that the file is effectively ignored AND not already tracked.
+ *        Only then return `ignored: true`.
+ *
+ *   3. Native-git, `.git/info/exclude` fallback:
+ *      - Only attempted when the `.gitignore` write failed AND `.git` is a
+ *        directory (regular repo). `.git/info/exclude` is the per-clone
+ *        ignore file: not synced to remotes, but exactly as effective as
+ *        `.gitignore` at preventing `git add` from staging the file. The
+ *        fallback lets us still fail-closed when the working tree is
+ *        read-only but the local clone metadata is writable. After the
+ *        exclude append, the same `verifyNpmrcIgnoredByGit` check runs.
+ *
+ * Why git verification, not just text: a `.gitignore` containing `.npmrc`
+ * is necessary but not sufficient. Two real leak paths bypass a naive
+ * "any line matches" textual check:
+ *   - A later `!.npmrc` re-includes the file (gitignore is order-sensitive).
+ *     `textIgnoresNpmrc` is already negation-aware (returns true only when
+ *     the LAST matching rule is positive), so for this case the textual
+ *     check correctly reports "not ignored" and `appendNpmrcIgnore` writes
+ *     a fresh positive `.npmrc` line that becomes the new last-match.
+ *     This is the gpoulios-sb PR #19642 re-review "always append" remedy,
+ *     applied uniformly to both branches (non-native-git relies on it as
+ *     the authoritative check; native-git double-checks with git below).
+ *   - An already-tracked `.npmrc` stages on every commit regardless of
+ *     ignore rules. No textual check sees the index, so for native-git
+ *     `git ls-files --error-unmatch` is the only catch.
+ *
+ * Returns `{ ignored, hasGit }`. The caller's fail-closed signal is
+ * `ignored === false` regardless of `hasGit`: any state in which we cannot
+ * guarantee `.npmrc` is ignored from `<dir>` blocks the credential write,
+ * because either the current native git checkout would stage the token on
+ * the next `git add .`, or a future `git init` in the same dir would find
+ * the token on disk and stage it on the first `git add .`. `hasGit` is
+ * retained for logging only — it lets the warning distinguish the
+ * "tomorrow's risk" case from the "today's risk" case.
+ */
+export declare function ensureNpmrcGitignored(dir: string): Promise<EnsureNpmrcGitignoredResult>;
+/**
+ * Convenience: invoke `writeNpmrc` against `<dir>/.npmrc` when the client
+ * resolves to a configured (or stale) registry config. No-op when:
+ *
+ *   - `client` is undefined (test-only opt-out — production code paths
+ *     always pass a client constructed by AiService); or
+ *   - the resolved config is `source: "unreachable"` (transient cold-cache
+ *     outage — we leave `.npmrc` whatever it currently is and reconcile on
+ *     the next successful fetch, rather than clobbering a last-known-good
+ *     private-registry `.npmrc` back to baseline during the outage window);
+ *     or
+ *   - the resolved config is `source: "not-configured"` (deliberate unset
+ *     observation). If a previously-written `.npmrc` exists that no longer
+ *     matches the baked-in `.npmrc.default`, restore it — see APPS-4320.
+ *
+ * On the first call per pod boot for `<dir>`, captures `<dir>/.npmrc` to
+ * `<dir>/.npmrc.default` before any rewrite so the restore path above has
+ * a source to copy back from.
+ *
+ * Returns the resolved fetch result so callers can branch on `source` for
+ * observability, or `undefined` when no client was provided.
+ */
+export declare function maybeWriteNpmrcForDir(dir: string, client?: NpmRegistryClient): Promise<NpmRegistryFetchResult | undefined>;
+/**
+ * Materializes the private-registry `.npmrc` AND unconditionally strips
+ * `resolved` URLs from any lockfile present in `dir`, so a subsequent
+ * `npm install` is guaranteed to re-resolve through the active registry.
+ * The `.npmrc` write is gated on whether the client resolves to a configured
+ * registry; the lockfile strip runs regardless.
+ *
+ * Why the strip is unconditional (decoupled from the `.npmrc` write):
+ *   - SaaS dev-server pods (staging/prod) often run without a configured
+ *     org npm registry, but their lockfiles can still be poisoned with
+ *     cross-registry `resolved` URLs via DBFS state (APPS-4300). Gating
+ *     the strip on the client's configured-ness meant the only safety net
+ *     never fired in the exact environment where it mattered. Always
+ *     stripping closes that read path.
+ *   - The mutation is transient: `npm install` rewrites `resolved` with
+ *     URLs from the active `.npmrc` registry on the very next line, so a
+ *     local dev whose lockfile pointed at npmjs.org sees the same URLs
+ *     restored after install.
+ *   - `integrity` is preserved (see `stripResolvedFromLockfile`), so any
+ *     cross-registry tarball drift surfaces as a clean `EINTEGRITY` failure
+ *     rather than silent corruption.
+ *
+ * The strip is per-boot, not persisted: a stripped lockfile only reaches DBFS
+ * if the surrounding flow runs an upload. Pods that boot, strip, and exit
+ * without uploading still find the same poisoned lockfile in DBFS on the
+ * next boot. The CI fix in `build-db-migrations.yaml` and `build-dev-server.yaml`
+ * (only configure GHPR scope for ephemeral builds) is the actual durable
+ * fix; this strip is the runtime safety net for already-poisoned DBFS state.
+ *
+ * Returns the resolved fetch result when a client is provided (so callers
+ * can branch on `source` for observability), or `undefined` when no client
+ * was provided. The lockfile strip happens in both cases.
+ */
+export declare function prepareForPrivateRegistry(dir: string, client?: NpmRegistryClient): Promise<NpmRegistryFetchResult | undefined>;
+/**
+ * Removes the `resolved` field from every entry in `.packages` of an npm v2+
+ * lockfile. TS-side counterpart to `scripts/strip-lockfile-resolved.sh`.
+ *
+ * Same goal: npm honors `resolved` URLs verbatim, so a lockfile whose entries
+ * point at registry.npmjs.org keeps fetching from npmjs even after we've
+ * written a private `registry=` line to `.npmrc`. Stripping forces npm to
+ * re-resolve through the active registry.
+ *
+ * Use at runtime for *brownfield* apps — apps imported into Superblocks with
+ * a lockfile baked at customer-side npm install time (typically against
+ * npmjs.org). Greenfield template lockfiles are stripped at image-build time
+ * by the bash script; this function handles the rest.
+ *
+ * Behavior:
+ *   - Strips both `<dir>/package-lock.json` and the hidden
+ *     `<dir>/node_modules/.package-lock.json` if present.
+ *   - No-op when neither file exists (brownfield apps may not have a
+ *     lockfile yet).
+ *   - Idempotent: a second call against an already-stripped file is a no-op.
+ *   - Malformed JSON or wrong shape -> logged warning, file left untouched.
+ *     We don't throw because the consuming `npm install` will surface a
+ *     clearer error on the same lockfile, and an unrelated parse bug here
+ *     should not block the user's install.
+ *   - Atomic: writes via tmp + rename to avoid leaving a partial lockfile on
+ *     crash mid-write.
+ */
+export declare function stripResolvedFromLockfile(dir: string): Promise<void>;
+export declare function stripResolvedFromLockfilePath(lockfilePath: string): Promise<void>;
+/**
+ * APPS-4370. Build a disk-backed `LastKnownRegistryPolicyStore` rooted at
+ * `<rootDir>/.superblocks/orgs/<orgId>/.registry-was-configured`.
+ *
+ * The marker's PRESENCE is the semantic signal; its content is informal
+ * (an ISO timestamp for forensics — "when was this org first seen with a
+ * configured registry"). Writes are best-effort: a write failure (EACCES
+ * on a 0o500 parent, ENOSPC) is logged and swallowed. Reads return false
+ * on any error so a transient IO problem doesn't degrade today's
+ * "proceed" behaviour into a fail-closed install.
+ *
+ * APPS-4427: `markConfigured` is AWAITED by its caller
+ * (`NpmRegistryClient.markPolicyConfigured`) before a `configured` / `stale`
+ * resolution is handed back, so the marker is durably on disk before that
+ * result is used — closing the crash window an un-awaited write would leave
+ * open. The write stays async (`fs/promises`, per the ai-service no-sync-fs
+ * rule) and is guarded to run at most once per process, so awaiting it stays
+ * off the install hot path after the first configured resolution.
+ *
+ * The `rootDir` is injected (rather than hard-coded to `os.homedir()`)
+ * so tests can isolate to a tmp directory and so the dev-server can
+ * point the store at the same disk it already manages
+ * (`~/.superblocks/...`). The per-org path keeps multiple orgs running
+ * against the same machine from contaminating each other's marker state.
+ */
+export declare function createDiskRegistryPolicyStore(opts: {
+    organizationId: string;
+    rootDir: string;
+}): LastKnownRegistryPolicyStore;
+export { parseNpmJsonError, parseNpmJsonDiagnostic, classifyNpmExecStderr, } from "./npm-error-parser.js";
+export type { ParseContext } from "./npm-error-parser.js";
+export { NpmInstallBlocked, NpmInstallError, scrubSecrets } from "../types.js";
+export type { NpmInstallBlockedDetails, NpmInstallBlockedReason, } from "../types.js";
+//# sourceMappingURL=npm-registry.d.ts.map