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

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

@@ -9,84 +9,737 @@
  */
 export declare const PRESERVE_NPMRC_SCOPES: string[];
 /**
- * Configuration for an npm registry sourced from environment variables.
+ * 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`).
  *
- * The "single-host MVP" surface is `url` + `token`; `scopes` is plumbed for
- * forward-compatibility (two-host setups like @superblocksteam on GitHub
- * Packages plus third-party deps on Artifactory) but admin UX is deferred.
+ * `scope === null` is the default (unscoped) registry; otherwise it is a
+ * single npm scope like `"@mycompany"`.
+ */
+export interface NpmRegistryEntry {
+    id: string;
+    scope: string | null;
+    registryUrl: string;
+    token: string | null;
+}
+/**
+ * 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 {
-    /** Default registry URL (e.g. https://artifactory.example.com/api/npm/npm-virtual/) */
-    url: string;
-    /** Optional auth token for the default registry host */
-    token?: string;
+    /** True if at least one registry is configured for the org. */
+    configured: boolean;
+    /** Default (unscoped) registry URL + optional token. */
+    default?: {
+        url: string;
+        token?: string;
+    };
     /**
-     * Optional per-scope registry mappings. e.g.
-     *   { "@superblocksteam": "https://npm.pkg.github.com/" }
+     * Scoped registries keyed by scope (e.g. `"@mycompany"`).
+     * Tokens are kept alongside so `writeNpmrc` can emit per-scope
+     * `_authToken=` lines.
      */
-    scopes?: Record<string, string>;
+    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;
     /**
-     * When true, AppShell refuses to run npm if the registry env is unset.
-     * Plumbed for the upcoming `SUPERBLOCKS_REQUIRE_PRIVATE_REGISTRY` enforcement
-     * branch; not yet read by any consumer in this PR.
+     * 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).
      */
-    require?: boolean;
+    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>;
+    /** True if the marker is present. Best-effort; resolves to false on error. */
+    hasEverBeenConfigured(): Promise<boolean>;
 }
 /**
- * Reads the npm registry env contract and returns a typed config, or undefined
- * when `SUPERBLOCKS_NPM_REGISTRY` is unset or invalid (preserves SaaS / local
- * behavior). Invalid values are logged as warnings and treated as unset rather
- * than half-broken (avoids landing a `.npmrc` with a malformed `registry=`
- * line and no `_authToken=`).
+ * 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.
  *
- * Env contract:
- * - SUPERBLOCKS_NPM_REGISTRY: full registry URL
- * - SUPERBLOCKS_NPM_REGISTRY_TOKEN: optional auth token
- * - SUPERBLOCKS_NPM_REGISTRY_SCOPES_JSON: optional JSON map of scope -> URL
- * - SUPERBLOCKS_REQUIRE_PRIVATE_REGISTRY: opt-in strict mode (default off)
+ * 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 getNpmRegistryConfig(env?: NodeJS.ProcessEnv): NpmRegistryConfig | undefined;
+export declare function shouldIgnoreInstallScripts(result: NpmRegistryFetchResult | undefined): boolean;
+/**
+ * Translates a list of server-shaped registry entries into the renderable
+ * `NpmRegistryConfig`. Centralised so `writeNpmrc`, tests, and any future
+ * consumer all interpret the wire shape the same way.
+ *
+ * Multiple `scope === null` entries should never happen — the server's
+ * UNIQUE (organization_id, scope) constraint forbids it — but we are
+ * defensive: the FIRST default wins, subsequent ones are logged and
+ * discarded so a server-side bug never silently rotates the default URL
+ * mid-fetch.
+ *
+ * Duplicate scoped entries (same `scope` string) follow the same rule:
+ * first wins.
+ */
+export declare function registriesToConfig(entries: NpmRegistryEntry[], allowInstallScripts?: boolean): 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;
+}
+/**
+ * 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);
+    /**
+     * 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;
+    /**
+     * 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.
+     */
+    getConfig(): 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;
+    private serveStaleOrUnconfigured;
+}
 export interface WriteNpmrcOptions {
     /**
      * Scope prefixes (e.g. `@superblocksteam`) whose existing
-     * `<scope>:registry=` lines must survive. Used to preserve scope mappings
-     * baked into a template `.npmrc` by setup-template.sh in EE builds.
+     * `<scope>:registry=` lines must survive — together with every
+     * auth-family key (`_authToken`, `_password`, `username`, `email`,
+     * `_auth`) keyed on the same `//<origin>/` prefix as
+     * the preserved registry URL. Used to keep scope mappings baked into a
+     * template `.npmrc` by setup-template.sh in EE builds, including the
+     * GHPR token that authenticates `@superblocksteam/*` installs
+     * (APPS-4300). When the same scope is also overridden in
+     * `config.scopes`, both the registry line and its auth-family lines
+     * are dropped in favour of the override.
      */
     preserveScopeLines?: string[];
+    /**
+     * 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.
+ *
  * When `preserveScopeLines` is provided, any existing `<scope>:registry=`
- * lines for those scopes are preserved verbatim (so EE-baked
+ * keys for those scopes are preserved (so EE-baked
  * `@superblocksteam:registry=https://npm.pkg.github.com/` survives) UNLESS
- * the same scope is explicitly overridden in `config.scopes`.
+ * the same scope is explicitly overridden in `config.scopes`. The
+ * preserved value is read via `ini.parse` from the existing file, so
+ * `ini`'s own quoting rules apply (rather than our older line-grep that
+ * could mis-handle quoted values).
  *
  * 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>;
 /**
- * Convenience: invoke `writeNpmrc` against `<dir>/.npmrc` if registry config is
- * present in the env. No-op when unset (preserves today's behavior for SaaS /
- * local dev).
+ * 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.
  *
- * Returns the loaded config when an `.npmrc` was written, otherwise `undefined`.
+ *   - `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 declare function maybeWriteNpmrcForDir(dir: string, options?: WriteNpmrcOptions, env?: NodeJS.ProcessEnv): Promise<NpmRegistryConfig | undefined>;
+export type SnapshotInitialNpmrcOutcome = "created" | "exists" | "no-source" | "failed";
 /**
- * Materializes the private-registry `.npmrc` (when the env contract is set)
- * 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.
+ * 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>;
+export 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.
+ */
+export 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=<customer token>` at the app root. 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
+ * their `_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, options?: WriteNpmrcOptions, 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) run without `SUPERBLOCKS_NPM_REGISTRY`
- *     set, but their lockfiles can still be poisoned with cross-registry
- *     `resolved` URLs via DBFS state (APPS-4300). Gating the strip on the
- *     env meant the only safety net never fired in the exact environment
- *     where it mattered. Always stripping closes that read path.
+ *   - 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
@@ -102,10 +755,11 @@ export declare function maybeWriteNpmrcForDir(dir: string, options?: WriteNpmrcO
  * (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 loaded config when an `.npmrc` was written, otherwise
- * `undefined`. The lockfile strip happens in both cases.
+ * 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, options?: WriteNpmrcOptions, env?: NodeJS.ProcessEnv): Promise<NpmRegistryConfig | undefined>;
+export declare function prepareForPrivateRegistry(dir: string, options?: WriteNpmrcOptions, 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`.
@@ -134,4 +788,38 @@ export declare function prepareForPrivateRegistry(dir: string, options?: WriteNp
  *     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 { NpmInstallBlockedReason, NpmInstallBlockedSubreason, NpmInstallBlockedDetails, } from "../types.js";
 //# sourceMappingURL=npm-registry.d.ts.map