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

package/dist/ai-service/app-interface/shell.js

@@ -39,14 +39,52 @@ import { promisify } from "node:util";
 import { glob } from "glob";
 import { detect, resolveCommand } from "package-manager-detector";
 import { normalizePath } from "vite";
+import { bucketNpmRegistryHost, recordNpmInstall, } from "@superblocksteam/telemetry";
 import { getErrorMeta, getLogger } from "../../util/logger.js";
 import llmobs from "../llmobs/index.js";
-import { NpmInstallError } from "../types.js";
+import { NpmInstallBlocked, NpmInstallError, scrubSecrets, } from "../types.js";
 import { CLARK_APP_BLACKLIST_PATTERNS, APPLICATION_FILE_PATTERNS, STANDARD_IGNORE_PATTERNS, } from "./constants.js";
 import { DraftManager, validateFileOperation, } from "./filesystem/index.js";
 import { Linter } from "./linter.js";
-import { maybeWriteNpmrcForDir, prepareForPrivateRegistry, PRESERVE_NPMRC_SCOPES, } from "./npm-registry.js";
+import { parseNpmJsonDiagnostic, parseNpmJsonError, parseNpmJsonSuccess, } from "./npm-error-parser.js";
+import { prepareForPrivateRegistry, PRESERVE_NPMRC_SCOPES, shouldIgnoreInstallScripts, } from "./npm-registry.js";
 const execPromise = promisify(exec);
+// `npm install --json` emits the full install summary on stdout. The default
+// 1 MiB exec buffer can be exceeded for fat dependency trees, which would
+// fail a successful install with ERR_CHILD_PROCESS_STDIO_MAXBUFFER and reach
+// `classifyNpmExecError` with truncated stdout — defeating the `--json`
+// error-envelope contract these entry points depend on. 4 MiB comfortably
+// covers real-world npm summaries (per-package entries are tiny) while
+// keeping the worst-case buffer + parsed-object peak bounded.
+const NPM_JSON_MAX_BUFFER = 4 * 1024 * 1024;
+/**
+ * Map an install failure to a value in the closed `npm.outcome` enum
+ * (APPS-4189). `NpmInstallBlocked` carries the structured reason from
+ * P1.2; anything else is bucketed as `other` at the metric boundary.
+ * `normalizeNpmOutcome` enforces the allowlist a second time downstream
+ * so a stray reason value cannot leak past the emit boundary.
+ */
+function outcomeFromInstallError(err) {
+    if (err instanceof NpmInstallBlocked)
+        return err.reason;
+    return "other";
+}
+/**
+ * Pick the registry URL the install actually targeted from the most-recent
+ * `prepareForPrivateRegistry` / `maybeWriteNpmrcForDir` result. Returns
+ * `undefined` (→ `registry_host=unknown`) when no configured row was in
+ * effect, including the `unreachable` and `not-configured` cases — those
+ * are deliberately reported as `unknown` rather than guessed at public
+ * npm, so the dashboard signal "did private-registry routing actually
+ * fire?" stays honest.
+ */
+function registryUrlFromFetchResult(result) {
+    if (!result)
+        return undefined;
+    if (!result.config.configured)
+        return undefined;
+    return result.config.default?.url;
+}
 const DEFAULT_COPY_DIRECTORY_EXCLUDES = new Set([
     ".git",
     ".next",
@@ -135,12 +173,22 @@ let AppShell = (() => {
         virtualFs;
         pathValidator;
         enableDeletingLockfiles;
+        /**
+         * Resolves the per-org npm registry config at install time. The AiService
+         * always constructs one in production (SaaS, local dev, and ephemeral
+         * pods); the LD flag (`superblocks.npm-registry.enabled`) inside the
+         * client decides whether to short-circuit to "not-configured" without a
+         * server call. `undefined` here is the test-only path (or callers that
+         * deliberately opt out): every `.npmrc` helper becomes a no-op and the
+         * install runs against npm's default resolution.
+         */
+        npmRegistryClient;
         /**
          * Tracks files that must be read before they can be written.
          * Used to enforce read-before-write pattern for AI safety.
          */
         requiredReads = new Set();
-        constructor({ appRootDirPath, fsOperationQueue, messageSender, draftInterface, templateRenderer, virtualFileSystem, pathValidator, enableDeletingLockfiles, }) {
+        constructor({ appRootDirPath, fsOperationQueue, messageSender, draftInterface, templateRenderer, virtualFileSystem, pathValidator, enableDeletingLockfiles, npmRegistryClient, }) {
             // Normalize path to handle Windows drive letter case
             this.appRootDirPath = normalizePath(appRootDirPath);
             this.fsOperationQueue = fsOperationQueue;
@@ -153,6 +201,7 @@ let AppShell = (() => {
             this.virtualFs = virtualFileSystem;
             this.pathValidator = pathValidator;
             this.enableDeletingLockfiles = enableDeletingLockfiles ?? false;
+            this.npmRegistryClient = npmRegistryClient;
         }
         /**
          * Toggle the API virtual-file projection. When disabled, reads to `apis/*`
@@ -276,182 +325,555 @@ let AppShell = (() => {
         warmLinterCache() {
             void this.linter.warmCache(["**/*.{tsx}"]);
         }
+        /**
+         * Emit one `superblocks.npm.install.*` observation (APPS-4189 / P6.2) and
+         * annotate the active llmobs span with the same dimensions. Shared by
+         * every `AppShell.*install*` method so metric and span streams join on
+         * (runner, registry_host, outcome) without drift. Every value flows
+         * through the P6.1 sanitization helpers inside `recordNpmInstall`, so a
+         * raw registry hostname or token cannot reach an exported attribute even
+         * if an upstream caller forgot to scrub.
+         */
+        observeNpmInstall(runner, registryFetchResult, outcome, durationMs) {
+            const tags = recordNpmInstall({
+                runner,
+                registryHost: registryUrlFromFetchResult(registryFetchResult),
+                outcome,
+                durationMs,
+            });
+            llmobs.annotate({ tags });
+        }
+        /**
+         * Env overlay for AppShell-spawned npm/pnpm installs in the live-edit
+         * pod. Routes npm's per-run debug log into `<app>/.superblocks/logs` via
+         * `NPM_CONFIG_LOGS_DIR` so a failed agent install leaves a collectable log
+         * in a predictable place — the same convention the CLI dev-server install
+         * uses (`buildInstallEnv` in the SDK). These execs otherwise inherit
+         * `process.env` implicitly, so we spread it before adding the override.
+         * pnpm has no equivalent logs-dir config and ignores the var (npm-only).
+         */
+        installLogEnv() {
+            return {
+                ...process.env,
+                NPM_CONFIG_LOGS_DIR: path.join(this.appRootDirPath, ".superblocks", "logs"),
+            };
+        }
         async runNpmInstall(abortSignal) {
-            // Materialize `.npmrc` from the SUPERBLOCKS_NPM_REGISTRY env contract AND
-            // strip `resolved` URLs from any baked-in lockfile so npm re-resolves
-            // through the active private registry (brownfield cutover). Serialized
-            // with other queued FS ops so two concurrent installs can't interleave
-            // the preserve-scope read-modify-write or rewrite the lockfile mid-read.
-            await this.enqueueFsOperation("maybeWriteNpmrc", () => prepareForPrivateRegistry(this.appRootDirPath, {
-                preserveScopeLines: PRESERVE_NPMRC_SCOPES,
-            }));
-            return await new Promise((resolve, reject) => {
-                const command = 
-                // if we're running in csb mock server, we need to avoid conflicts with the workspace
-                process.env.SUPERBLOCKS_SERVER_ENV === "local"
-                    ? "pnpm install --config.confirmModulesPurge=false"
-                    : "npm install";
-                exec(command, {
-                    cwd: this.appRootDirPath,
-                    timeout: 30_000,
-                    signal: abortSignal,
-                }, (error, _stdout, stderr) => {
-                    if (error) {
-                        return reject(new NpmInstallError(stderr));
-                    }
-                    return resolve();
+            const installStart = Date.now();
+            let outcome = "success";
+            let capturedFetchResult;
+            try {
+                // `withAuthFailedRetry` owns the `.npmrc` materialization (via
+                // `prepareForPrivateRegistry`) and the one-shot auth_failed retry —
+                // see its docstring. Telemetry is captured around it so a retry-then-
+                // succeed flow still records the right outcome.
+                await this.withAuthFailedRetry(async (registryFetchResult) => {
+                    capturedFetchResult = registryFetchResult;
+                    // APPS-4370: refuse to spawn npm when the registry server is
+                    // unreachable AND we have prior evidence (disk marker) that this org
+                    // was at some point configured with a private registry. See
+                    // `maybeShortCircuitForUnreachable` for the full rationale.
+                    this.maybeShortCircuitForUnreachable(registryFetchResult, []);
+                    const ignoreScripts = shouldIgnoreInstallScripts(registryFetchResult);
+                    // In csb mock server (local dev) we use pnpm to avoid lockfile / store
+                    // conflicts with the surrounding workspace; everywhere else we force npm
+                    // so the `--json` error contract — and therefore the registry-blocked
+                    // advice matrix — applies on this post-processing path too. When the
+                    // org has opted out via `allow_install_scripts=false`, append
+                    // `--ignore-scripts` (the flag is honored by both npm and pnpm).
+                    const isNpm = process.env.SUPERBLOCKS_SERVER_ENV !== "local";
+                    const baseCommand = isNpm
+                        ? "npm install --fund=false --audit=false --json"
+                        : "pnpm install --config.confirmModulesPurge=false";
+                    const command = ignoreScripts
+                        ? `${baseCommand} --ignore-scripts`
+                        : baseCommand;
+                    return await new Promise((resolve, reject) => {
+                        exec(command, {
+                            cwd: this.appRootDirPath,
+                            env: this.installLogEnv(),
+                            timeout: 30_000,
+                            signal: abortSignal,
+                            // See `NPM_JSON_MAX_BUFFER` — `--json` summary can outgrow the
+                            // default 1 MiB exec buffer on fat dep trees.
+                            maxBuffer: NPM_JSON_MAX_BUFFER,
+                        }, (error, stdout, stderr) => {
+                            if (error) {
+                                // Route the npm path through the same classifier as the agent-tool
+                                // install entry points so E404 / E401 / ENOTFOUND surface as a
+                                // `NpmInstallBlocked` (with row-aware advice) instead of a raw
+                                // `NpmInstallError(stderr)`. The pnpm path doesn't emit the
+                                // `--json` envelope, so the classifier falls through to the
+                                // legacy error for it — registry-blocked scenarios only matter
+                                // in cloud-edit (which is the npm branch).
+                                if (isNpm) {
+                                    return reject(this.classifyNpmExecError({ stdout, stderr, message: error.message }, undefined, registryFetchResult));
+                                }
+                                return reject(new NpmInstallError(stderr));
+                            }
+                            return resolve();
+                        });
+                    });
                 });
+            }
+            catch (err) {
+                outcome = outcomeFromInstallError(err);
+                throw err;
+            }
+            finally {
+                this.observeNpmInstall("install_all", capturedFetchResult, outcome, Date.now() - installStart);
+            }
+        }
+        /**
+         * APPS-4370. If the `prepareForPrivateRegistry` result tells us the
+         * server is unreachable AND the per-org disk marker says this org has
+         * at some prior point successfully resolved a configured registry,
+         * throw `NpmInstallBlocked(registry_unreachable)` BEFORE spawning npm.
+         *
+         * Without this short-circuit the install spawns anyway and hits one of
+         * two failure modes:
+         *   1. A previous install left a managed `.npmrc` with rotated credentials
+         *      → npm 401s mid-deploy and `classifyNpmExecError` tags it
+         *      `registry_auth_failed`, pointing the user at the wrong remediation.
+         *   2. No managed `.npmrc` exists → install silently resolves through
+         *      public npm, defeating the privacy posture during the outage.
+         *
+         * Bypassed when:
+         *   - The fetch result is anything other than `unreachable` (the
+         *     existing code paths handle `configured` / `stale` / `not-configured`).
+         *   - `everConfigured` is `undefined` (no store wired in — older call
+         *     sites, test fixtures) or `false` (greenfield org / first install).
+         *
+         * `packages` flows onto the structured error so the agent loop can
+         * surface "we tried to install <these> and the registry was unreachable".
+         */
+        maybeShortCircuitForUnreachable(registryFetchResult, packages) {
+            if (!registryFetchResult || registryFetchResult.source !== "unreachable") {
+                return;
+            }
+            if (registryFetchResult.everConfigured !== true) {
+                return;
+            }
+            throw new NpmInstallBlocked({
+                reason: "registry_unreachable",
+                packages,
+                hasAnyRegistryConfigured: true,
             });
         }
-        async runPackageManagerInstall(abortSignal) {
-            // See `runNpmInstall` for serialization + brownfield-lockfile rationale.
-            await this.enqueueFsOperation("maybeWriteNpmrc", () => prepareForPrivateRegistry(this.appRootDirPath, {
-                preserveScopeLines: PRESERVE_NPMRC_SCOPES,
-            }));
-            // In cloud edit mode, always use npm because pnpm is not available in the container.
-            // The user's project may have pnpm signals (pnpm-lock.yaml, packageManager field)
-            // from local editing, but we must use npm in cloud mode.
-            const isCloudMode = process.env.SUPERBLOCKS_SERVER_ENV !== "local";
-            let packageManagerAgent;
-            if (isCloudMode) {
-                // Force npm in cloud mode
-                packageManagerAgent = "npm";
+        /**
+         * Derive the `hasAnyRegistryConfigured` tri-state from the
+         * `NpmRegistryFetchResult` that the immediately-preceding
+         * `prepareForPrivateRegistry` call returned.
+         *
+         *   - `true`      — `configured` or `stale`. At least one row is known
+         *                   to exist (fresh fetch or last-known-good cache).
+         *   - `false`     — `not-configured`. The kill switch is off OR the
+         *                   server returned an empty list. A deliberate "no rows"
+         *                   observation.
+         *   - `undefined` — `prepareForPrivateRegistry` returned `undefined` (no
+         *                   client wired in) OR the client resolved to `unreachable`
+         *                   (server down with no usable cache). Both mean "we don't
+         *                   know"; `buildBlockedMessage` falls back to the default
+         *                   variant rather than asserting a row count.
+         *
+         * Kept narrow + private so the signal stays a single derivation site rather
+         * than something every catch handler reimplements.
+         */
+        static deriveHasAnyRegistryConfigured(result) {
+            if (!result)
+                return undefined;
+            switch (result.source) {
+                case "configured":
+                case "stale":
+                    return true;
+                case "not-configured":
+                    return false;
+                case "unreachable":
+                    return undefined;
             }
-            else {
-                // NOTE: this largely duplicates the logic in the CLI
-                const packageManager = await detect({
-                    strategies: [
-                        "packageManager-field",
-                        "lockfile",
-                        "install-metadata",
-                        "devEngines-field",
-                    ],
-                    cwd: this.appRootDirPath,
+        }
+        /**
+         * Convert an exec failure from `npm --json` into a structured error.
+         *
+         * - When the stdout JSON matches a known registry-blocked condition (E404,
+         *   ENOTFOUND, E401, ...) we throw `NpmInstallBlocked` so the tool layer
+         *   can surface it to the agent as a structured result.
+         * - Otherwise we fall back to the legacy `NpmInstallError(stderr)` so any
+         *   pre-existing handler (e.g. agent-planning's POST_PROCESSING_ERRORED
+         *   branch) behaves exactly as it did before.
+         *
+         * Only used on the npm code path; pnpm continues to throw `NpmInstallError`
+         * directly because pnpm's `--json` error contract differs and the
+         * registry-blocked scenarios only matter in cloud-edit (which forces npm).
+         *
+         * `registryFetchResult` carries the most recent
+         * `prepareForPrivateRegistry` result so the structured error can encode
+         * whether the org had any configured registry rows at the moment of
+         * failure (used by `buildBlockedMessage` to choose between default and
+         * row-aware advice variants). The active llmobs span is annotated with the
+         * same data points so a downstream `npm.install_blocked.*` facet can
+         * correlate reason, host, and row presence.
+         */
+        classifyNpmExecError(error, requestedPackages, registryFetchResult) {
+            const stdout = error.stdout ?? "";
+            const hasAnyRegistryConfigured = AppShell.deriveHasAnyRegistryConfigured(registryFetchResult);
+            const blocked = parseNpmJsonError(stdout, {
+                requestedPackages,
+                hasAnyRegistryConfigured,
+            });
+            if (blocked) {
+                // Span tags for `superblocks.npm.install_blocked.*` faceting. Stringified
+                // because llmobs tag values are strings; `unknown` is used in lieu of
+                // `null`/`undefined` so the tag's cardinality stays bounded and a
+                // "field absent" datapoint is still queryable.
+                //
+                // `npm.install_blocked.registry_host` is routed through the P6.1
+                // `bucketNpmRegistryHost` sanitizer (same helper used by
+                // `recordNpmInstall`) so the tag value is a bounded enum
+                // (`public_npm` / `private` / `unknown`). `NpmInstallBlocked` only
+                // scrubs credentials and control characters — without the bucketer the
+                // raw customer registry hostname would land in llmobs tags, leaking
+                // customer-internal hosts and giving the tag unbounded cardinality.
+                llmobs.annotate({
+                    tags: {
+                        "npm.install_blocked.reason": blocked.reason,
+                        "npm.install_blocked.registry_host": bucketNpmRegistryHost(blocked.registryHost),
+                        "npm.install_blocked.npm_error_code": blocked.npmErrorCode ?? "unknown",
+                        "npm.install_blocked.has_any_registry_configured": hasAnyRegistryConfigured === undefined
+                            ? "unknown"
+                            : String(hasAnyRegistryConfigured),
+                    },
                 });
-                if (!packageManager) {
-                    throw new Error("Could not detect package manager");
-                }
-                packageManagerAgent = packageManager.agent;
+                return blocked;
             }
-            const installCommand = resolveCommand(packageManagerAgent, "install", packageManagerAgent === "npm" ? ["--fund=false", "--audit=false"] : []);
-            if (!installCommand) {
-                throw new Error(`Could not determine install command for ${packageManagerAgent}, skipping package installation`);
+            // Non-registry-blocked failure (ERESOLVE, EPEERINVALID, ETARGET, …).
+            // Prefer the JSON diagnostic from stdout because under `--json` stderr
+            // is sparse — preserving the diagnostic keeps agent-planning's
+            // POST_PROCESSING_ERRORED debug message useful instead of collapsing
+            // it to a generic exec-failure string.
+            const diagnostic = parseNpmJsonDiagnostic(stdout);
+            if (stdout && !diagnostic) {
+                // npm was invoked with `--json` but neither parser could extract
+                // anything from stdout. This silently bypasses the row-aware advice
+                // matrix, the structured warn log, and the llmobs span tags above —
+                // converting the silent fallback into a queryable signal so operators
+                // can find these (npm crash mid-output, stdout truncation, schema
+                // drift across npm versions, an interactive prompt sneaking past
+                // `--json`). Single line, debug-grade payload (truncated preview
+                // only) to keep log volume bounded.
+                //
+                // Scrub BEFORE slicing: raw npm `--json` stdout can contain registry
+                // URLs with userinfo or `_authToken=` lines from a leaked `.npmrc`,
+                // and slicing first could split a credential across the 200-char
+                // boundary so the regex no longer matches.
+                getLogger().warn("[npm] failed to extract structured error from `npm --json` stdout; falling back to legacy NpmInstallError", { stdoutPreview: scrubSecrets(stdout).slice(0, 200) });
             }
-            const { command, args } = installCommand;
+            return new NpmInstallError(diagnostic || error.stderr || error.message || "");
+        }
+        /**
+         * Wraps an install attempt so that a `registry_auth_failed` failure
+         * triggers one cache-invalidation + re-fetch + retry cycle before
+         * throwing. The helper owns the `.npmrc` materialisation so the retry
+         * picks up a freshly-fetched token without duplicating the prep call
+         * in every install method.
+         *
+         * Guard: only one retry per call — a second `registry_auth_failed`
+         * propagates unchanged.
+         */
+        async withAuthFailedRetry(attempt) {
+            const registryFetchResult = await this.enqueueFsOperation("maybeWriteNpmrc", () => prepareForPrivateRegistry(this.appRootDirPath, { preserveScopeLines: PRESERVE_NPMRC_SCOPES }, this.npmRegistryClient));
             try {
-                const { stdout } = await execPromise(`${command} ${args.join(" ")}`, {
-                    cwd: this.appRootDirPath,
-                    signal: abortSignal,
-                });
-                return stdout;
+                return await attempt(registryFetchResult);
             }
             catch (error) {
-                throw new NpmInstallError(error.stderr || error.message);
+                if (error instanceof NpmInstallBlocked &&
+                    error.reason === "registry_auth_failed" &&
+                    this.npmRegistryClient) {
+                    this.npmRegistryClient.invalidateCache();
+                    getLogger().info("[npm-registry] invalidated cache after registry_auth_failed; retrying install once");
+                    llmobs.annotate({
+                        tags: {
+                            "npm.registry.cache_invalidated_on_auth_failed": "true",
+                        },
+                    });
+                    const retryFetchResult = await this.enqueueFsOperation("maybeWriteNpmrc", () => prepareForPrivateRegistry(this.appRootDirPath, { preserveScopeLines: PRESERVE_NPMRC_SCOPES }, this.npmRegistryClient));
+                    return await attempt(retryFetchResult);
+                }
+                throw error;
+            }
+        }
+        async runPackageManagerInstall(abortSignal) {
+            const installStart = Date.now();
+            let outcome = "success";
+            let capturedFetchResult;
+            try {
+                return await this.withAuthFailedRetry(async (registryFetchResult) => {
+                    capturedFetchResult = registryFetchResult;
+                    // APPS-4370: short-circuit before any exec when server is unreachable
+                    // AND this org's marker says it was previously configured.
+                    this.maybeShortCircuitForUnreachable(registryFetchResult, []);
+                    const ignoreScripts = shouldIgnoreInstallScripts(registryFetchResult);
+                    // In cloud edit mode, always use npm because pnpm is not available in the container.
+                    // The user's project may have pnpm signals (pnpm-lock.yaml, packageManager field)
+                    // from local editing, but we must use npm in cloud mode.
+                    const isCloudMode = process.env.SUPERBLOCKS_SERVER_ENV !== "local";
+                    let packageManagerAgent;
+                    if (isCloudMode) {
+                        // Force npm in cloud mode
+                        packageManagerAgent = "npm";
+                    }
+                    else {
+                        // NOTE: this largely duplicates the logic in the CLI
+                        const packageManager = await detect({
+                            strategies: [
+                                "packageManager-field",
+                                "lockfile",
+                                "install-metadata",
+                                "devEngines-field",
+                            ],
+                            cwd: this.appRootDirPath,
+                        });
+                        if (!packageManager) {
+                            throw new Error("Could not detect package manager");
+                        }
+                        packageManagerAgent = packageManager.agent;
+                    }
+                    const isNpm = packageManagerAgent === "npm";
+                    const baseInstallArgs = isNpm
+                        ? ["--fund=false", "--audit=false", "--json"]
+                        : [];
+                    const installArgs = ignoreScripts
+                        ? [...baseInstallArgs, "--ignore-scripts"]
+                        : baseInstallArgs;
+                    const installCommand = resolveCommand(packageManagerAgent, "install", installArgs);
+                    if (!installCommand) {
+                        throw new Error(`Could not determine install command for ${packageManagerAgent}, skipping package installation`);
+                    }
+                    const { command, args } = installCommand;
+                    try {
+                        const { stdout } = await execPromise(`${command} ${args.join(" ")}`, {
+                            cwd: this.appRootDirPath,
+                            env: this.installLogEnv(),
+                            signal: abortSignal,
+                            // See `NPM_JSON_MAX_BUFFER` — `--json` summary can outgrow the
+                            // default 1 MiB exec buffer on fat dep trees.
+                            maxBuffer: NPM_JSON_MAX_BUFFER,
+                        });
+                        // On the npm path stdout is a JSON blob; translate to a compact
+                        // human-readable summary for the agent, falling back to raw stdout
+                        // when the JSON shape drifts.
+                        if (isNpm) {
+                            return parseNpmJsonSuccess(stdout) ?? stdout;
+                        }
+                        return stdout;
+                    }
+                    catch (error) {
+                        if (isNpm)
+                            throw this.classifyNpmExecError(error, undefined, registryFetchResult);
+                        throw new NpmInstallError(error.stderr || error.message);
+                    }
+                });
+            }
+            catch (err) {
+                outcome = outcomeFromInstallError(err);
+                throw err;
+            }
+            finally {
+                this.observeNpmInstall("install_all", capturedFetchResult, outcome, Date.now() - installStart);
             }
         }
         async installSpecificPackages(packages, abortSignal) {
             if (!packages || packages.length === 0) {
                 throw new Error("No packages specified for installation");
             }
-            // See `runNpmInstall` for serialization + brownfield-lockfile rationale.
-            await this.enqueueFsOperation("maybeWriteNpmrc", () => prepareForPrivateRegistry(this.appRootDirPath, {
-                preserveScopeLines: PRESERVE_NPMRC_SCOPES,
-            }));
-            // In cloud edit mode, always use npm because pnpm is not available in the container.
-            // The user's project may have pnpm signals (pnpm-lock.yaml, packageManager field)
-            // from local editing, but we must use npm in cloud mode.
-            const isCloudMode = process.env.SUPERBLOCKS_SERVER_ENV !== "local";
-            let packageManagerAgent;
-            if (isCloudMode) {
-                // Force npm in cloud mode
-                packageManagerAgent = "npm";
-            }
-            else {
-                const packageManager = await detect({
-                    strategies: [
-                        "packageManager-field",
-                        "lockfile",
-                        "install-metadata",
-                        "devEngines-field",
-                    ],
-                    cwd: this.appRootDirPath,
+            const installStart = Date.now();
+            let outcome = "success";
+            let capturedFetchResult;
+            try {
+                return await this.withAuthFailedRetry(async (registryFetchResult) => {
+                    capturedFetchResult = registryFetchResult;
+                    // APPS-4370: short-circuit before exec when unreachable + everConfigured.
+                    // Pass through the requested package specs so the structured error
+                    // surfaces them to the agent ("we tried to install lodash and the
+                    // private registry was unreachable").
+                    this.maybeShortCircuitForUnreachable(registryFetchResult, packages.map((pkg) => pkg.version ? `${pkg.name}@${pkg.version}` : pkg.name));
+                    const ignoreScripts = shouldIgnoreInstallScripts(registryFetchResult);
+                    // In cloud edit mode, always use npm because pnpm is not available in the container.
+                    // The user's project may have pnpm signals (pnpm-lock.yaml, packageManager field)
+                    // from local editing, but we must use npm in cloud mode.
+                    const isCloudMode = process.env.SUPERBLOCKS_SERVER_ENV !== "local";
+                    let packageManagerAgent;
+                    if (isCloudMode) {
+                        // Force npm in cloud mode
+                        packageManagerAgent = "npm";
+                    }
+                    else {
+                        const packageManager = await detect({
+                            strategies: [
+                                "packageManager-field",
+                                "lockfile",
+                                "install-metadata",
+                                "devEngines-field",
+                            ],
+                            cwd: this.appRootDirPath,
+                        });
+                        if (!packageManager) {
+                            throw new Error("Could not detect package manager");
+                        }
+                        packageManagerAgent = packageManager.agent;
+                    }
+                    const isNpm = packageManagerAgent === "npm";
+                    // Separate regular and dev dependencies
+                    const regularPackages = packages.filter((pkg) => !pkg.dev);
+                    const devPackages = packages.filter((pkg) => pkg.dev);
+                    const outputs = [];
+                    // Install regular dependencies
+                    if (regularPackages.length > 0) {
+                        const packageSpecs = regularPackages.map((pkg) => pkg.version ? `${pkg.name}@${pkg.version}` : pkg.name);
+                        const baseArgs = isNpm
+                            ? ["--fund=false", "--audit=false", "--json", ...packageSpecs]
+                            : packageSpecs;
+                        const addCommand = resolveCommand(packageManagerAgent, "add", ignoreScripts ? ["--ignore-scripts", ...baseArgs] : baseArgs);
+                        if (!addCommand) {
+                            throw new Error(`Could not determine add command for ${packageManagerAgent}`);
+                        }
+                        const { command, args } = addCommand;
+                        try {
+                            const { stdout } = await execPromise(`${command} ${args.join(" ")}`, {
+                                cwd: this.appRootDirPath,
+                                env: this.installLogEnv(),
+                                signal: abortSignal,
+                                // See `NPM_JSON_MAX_BUFFER` — `--json` summary can outgrow the
+                                // default 1 MiB exec buffer on fat dep trees.
+                                maxBuffer: NPM_JSON_MAX_BUFFER,
+                            });
+                            outputs.push(isNpm ? (parseNpmJsonSuccess(stdout) ?? stdout) : stdout);
+                        }
+                        catch (error) {
+                            if (isNpm)
+                                throw this.classifyNpmExecError(error, regularPackages, registryFetchResult);
+                            throw new NpmInstallError(error.stderr || error.message);
+                        }
+                    }
+                    // Install dev dependencies
+                    if (devPackages.length > 0) {
+                        const packageSpecs = devPackages.map((pkg) => pkg.version ? `${pkg.name}@${pkg.version}` : pkg.name);
+                        const baseArgs = isNpm
+                            ? [
+                                "--save-dev",
+                                "--fund=false",
+                                "--audit=false",
+                                "--json",
+                                ...packageSpecs,
+                            ]
+                            : ["-D", ...packageSpecs];
+                        const addCommand = resolveCommand(packageManagerAgent, "add", ignoreScripts ? ["--ignore-scripts", ...baseArgs] : baseArgs);
+                        if (!addCommand) {
+                            throw new Error(`Could not determine add command for ${packageManagerAgent}`);
+                        }
+                        const { command, args } = addCommand;
+                        try {
+                            const { stdout } = await execPromise(`${command} ${args.join(" ")}`, {
+                                cwd: this.appRootDirPath,
+                                env: this.installLogEnv(),
+                                signal: abortSignal,
+                                // See `NPM_JSON_MAX_BUFFER` — `--json` summary can outgrow the
+                                // default 1 MiB exec buffer on fat dep trees.
+                                maxBuffer: NPM_JSON_MAX_BUFFER,
+                            });
+                            outputs.push(isNpm ? (parseNpmJsonSuccess(stdout) ?? stdout) : stdout);
+                        }
+                        catch (error) {
+                            if (isNpm)
+                                throw this.classifyNpmExecError(error, devPackages, registryFetchResult);
+                            throw new NpmInstallError(error.stderr || error.message);
+                        }
+                    }
+                    return outputs.join("\n");
                 });
-                if (!packageManager) {
-                    throw new Error("Could not detect package manager");
-                }
-                packageManagerAgent = packageManager.agent;
-            }
-            // Separate regular and dev dependencies
-            const regularPackages = packages.filter((pkg) => !pkg.dev);
-            const devPackages = packages.filter((pkg) => pkg.dev);
-            const outputs = [];
-            // Install regular dependencies
-            if (regularPackages.length > 0) {
-                const packageSpecs = regularPackages.map((pkg) => pkg.version ? `${pkg.name}@${pkg.version}` : pkg.name);
-                const addCommand = resolveCommand(packageManagerAgent, "add", packageManagerAgent === "npm"
-                    ? ["--fund=false", "--audit=false", ...packageSpecs]
-                    : packageSpecs);
-                if (!addCommand) {
-                    throw new Error(`Could not determine add command for ${packageManagerAgent}`);
-                }
-                const { command, args } = addCommand;
-                try {
-                    const { stdout } = await execPromise(`${command} ${args.join(" ")}`, {
-                        cwd: this.appRootDirPath,
-                        signal: abortSignal,
-                    });
-                    outputs.push(stdout);
-                }
-                catch (error) {
-                    throw new NpmInstallError(error.stderr || error.message);
-                }
             }
-            // Install dev dependencies
-            if (devPackages.length > 0) {
-                const packageSpecs = devPackages.map((pkg) => pkg.version ? `${pkg.name}@${pkg.version}` : pkg.name);
-                const addCommand = resolveCommand(packageManagerAgent, "add", packageManagerAgent === "npm"
-                    ? ["--save-dev", "--fund=false", "--audit=false", ...packageSpecs]
-                    : ["-D", ...packageSpecs]);
-                if (!addCommand) {
-                    throw new Error(`Could not determine add command for ${packageManagerAgent}`);
-                }
-                const { command, args } = addCommand;
-                try {
-                    const { stdout } = await execPromise(`${command} ${args.join(" ")}`, {
-                        cwd: this.appRootDirPath,
-                        signal: abortSignal,
-                    });
-                    outputs.push(stdout);
-                }
-                catch (error) {
-                    throw new NpmInstallError(error.stderr || error.message);
-                }
+            catch (err) {
+                outcome = outcomeFromInstallError(err);
+                throw err;
+            }
+            finally {
+                this.observeNpmInstall("install_specific", capturedFetchResult, outcome, Date.now() - installStart);
             }
-            return outputs.join("\n");
         }
         async uninstallPackages(packages, options) {
-            // Uninstalls hit the same registry resolution rules as installs (e.g.
-            // dependency tree solver may re-fetch metadata), so refresh `.npmrc`
-            // first. Without this, an uninstall against a deployment whose
-            // private-registry token has been rotated would 401 against the stale
-            // `_authToken=` line. Same serialization rationale as `runNpmInstall`.
-            await this.enqueueFsOperation("maybeWriteNpmrc", () => maybeWriteNpmrcForDir(this.appRootDirPath, {
-                preserveScopeLines: PRESERVE_NPMRC_SCOPES,
-            }));
-            return await new Promise((resolve, reject) => {
-                // Use pnpm for local env, npm otherwise (same pattern as runNpmInstall)
-                const packageManager = process.env.SUPERBLOCKS_SERVER_ENV === "local" ? "pnpm" : "npm";
-                const uninstallCmd = packageManager === "pnpm" ? "remove" : "uninstall";
-                const command = `${packageManager} ${uninstallCmd} ${packages.join(" ")}`;
-                exec(command, {
-                    cwd: this.appRootDirPath,
-                    timeout: 30_000,
-                    signal: options?.abortSignal,
-                }, (error, stdout, stderr) => {
-                    if (error) {
-                        return reject(new NpmInstallError(stderr || error.message));
-                    }
-                    return resolve({ stdout, stderr });
+            // Uninstalls hit the same registry resolution rules as installs (the
+            // dependency-tree solver re-reifies the remaining tree and can re-fetch
+            // metadata), so they run through the SAME safety wrapper as every
+            // install path rather than a bespoke one-shot exec:
+            //
+            //   - `withAuthFailedRetry` owns the `.npmrc` materialization (via
+            //     `prepareForPrivateRegistry`, same serialization as `runNpmInstall`)
+            //     AND retries once on `registry_auth_failed` after invalidating the
+            //     registry cache, so an uninstall against a deployment whose
+            //     private-registry token was rotated mid-session recovers instead of
+            //     hard-failing on the stale `_authToken=` line.
+            //   - `maybeShortCircuitForUnreachable` (APPS-4370) refuses to spawn when
+            //     the config server is unreachable AND this org was previously
+            //     configured. Without it the uninstall escaped the fail-closed gate,
+            //     401'd against the stale token, and surfaced `registry_auth_failed`
+            //     (rotate-credentials advice) instead of `registry_unreachable`
+            //     (registry-down advice) — the wrong remediation.
+            //   - The npm path runs with `--json` and routes failures through
+            //     `classifyNpmExecError`, identical to `installSpecificPackages`, so
+            //     E404 / E401 / ENOTFOUND surface as a structured `NpmInstallBlocked`
+            //     (and the auth-failed case feeds the retry above).
+            //
+            // `shouldIgnoreInstallScripts` honours the org's `allowInstallScripts`
+            // policy on uninstall too — `preuninstall` / `postuninstall` lifecycle
+            // scripts are just as dangerous as install-time ones.
+            return await this.withAuthFailedRetry(async (registryFetchResult) => {
+                this.maybeShortCircuitForUnreachable(registryFetchResult, packages);
+                const ignoreScripts = shouldIgnoreInstallScripts(registryFetchResult);
+                // pnpm in local dev (avoids store/lockfile conflicts with the
+                // surrounding workspace); npm everywhere else so the `--json` error
+                // contract — and therefore the registry-blocked advice matrix —
+                // applies. Mirrors `runNpmInstall` / `installSpecificPackages`.
+                const isNpm = process.env.SUPERBLOCKS_SERVER_ENV !== "local";
+                const packageManager = isNpm ? "npm" : "pnpm";
+                const uninstallCmd = isNpm ? "uninstall" : "remove";
+                const jsonFlag = isNpm ? " --json" : "";
+                const baseCommand = `${packageManager} ${uninstallCmd} ${packages.join(" ")}${jsonFlag}`;
+                const command = ignoreScripts
+                    ? `${baseCommand} --ignore-scripts`
+                    : baseCommand;
+                return await new Promise((resolve, reject) => {
+                    exec(command, {
+                        cwd: this.appRootDirPath,
+                        env: this.installLogEnv(),
+                        timeout: 30_000,
+                        signal: options?.abortSignal,
+                        // `--json` summary can outgrow the default 1 MiB exec buffer.
+                        maxBuffer: NPM_JSON_MAX_BUFFER,
+                    }, (error, stdout, stderr) => {
+                        if (error) {
+                            // Same classifier as the install paths: a registry block
+                            // (E404 / E401 / ENOTFOUND, ...) becomes a structured
+                            // `NpmInstallBlocked` (with row-aware advice + the
+                            // auth-failed retry signal consumed by `withAuthFailedRetry`);
+                            // anything else falls back to the legacy `NpmInstallError`.
+                            // pnpm doesn't emit the `--json` envelope, so it keeps the
+                            // raw-stderr error.
+                            if (isNpm) {
+                                return reject(this.classifyNpmExecError({ stdout, stderr, message: error.message }, undefined, registryFetchResult));
+                            }
+                            return reject(new NpmInstallError(stderr || error.message));
+                        }
+                        // On the npm path stdout is a `--json` blob; collapse it to a
+                        // compact human-readable summary (same as
+                        // `installSpecificPackages`), falling back to raw stdout on
+                        // shape drift.
+                        return resolve({
+                            stdout: isNpm
+                                ? (parseNpmJsonSuccess(stdout) ?? stdout)
+                                : stdout,
+                            stderr,
+                        });
+                    });
                 });
             });
         }