@superblocksteam/vite-plugin-file-sync 2.0.170 → 2.0.171-next.0

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

@@ -44,7 +44,8 @@ import JSON5 from "json5";
 import { detect, resolveCommand } from "package-manager-detector";
 import semver from "semver";
 import { normalizePath } from "vite";
-import { isProtectedCorePackage, isValidNpmPackageName, isValidNpmVersionSpec, } from "@superblocksteam/library-shared/types";
+import { isMap, parseDocument } from "yaml";
+import { isCaretRelease, isProtectedCorePackage, isValidNpmPackageName, isValidNpmVersionSpec, parseOverrideSelector, } from "@superblocksteam/library-shared/types";
 import { bucketNpmRegistryHost, recordNpmInstall, } from "@superblocksteam/telemetry";
 import { applyPackageJsonSubstitutions, readDeclaredDependencies, } from "../../npm/apply-package-json-substitutions.js";
 import { preparePackageJsonForCloudNpm } from "../../npm/prepare-package-json-for-cloud-npm.js";
@@ -53,7 +54,7 @@ import { getErrorMeta, getLogger } from "../../util/logger.js";
 import { ToolExecutionError } from "../agent/tools2/types.js";
 import llmobs from "../llmobs/index.js";
 import { fixLucideDynamicTypeImports, isFixableLucidePath, } from "../transform/lucide-dynamic-type-imports/transformer.js";
-import { NpmInstallBlocked, NpmInstallError, scrubSecrets, } from "../types.js";
+import { NpmInstallBlocked, NpmInstallError, scrubSecrets, stripUnsafeChars, } from "../types.js";
 import { detectAppPackageManager, isPnpmEnabled, podPnpmEnv, } from "./app-package-manager.js";
 import { execCancellable } from "./cancellable-exec.js";
 import { CLARK_APP_BLACKLIST_PATTERNS, APPLICATION_FILE_PATTERNS, STANDARD_IGNORE_PATTERNS, } from "./constants.js";
@@ -61,7 +62,7 @@ import { DraftManager, validateFileOperation, } from "./filesystem/index.js";
 import { Linter } from "./linter.js";
 import { classifyNpmExecStderr, parseNpmJsonDiagnostic, parseNpmJsonError, parseNpmJsonSuccess, } from "./npm-error-parser.js";
 import { prepareForPrivateRegistry, shouldIgnoreInstallScripts, } from "./npm-registry.js";
-import { readPnpmLockfile } from "./pnpm-lockfile.js";
+import { parsePnpmPackageKey, readPnpmLockfile } from "./pnpm-lockfile.js";
 import { parseTypecheckOutputByPath } from "./typecheck-output-parser.js";
 import { applyPackageSubstitutions, runVulnerabilityGate, } from "./vulnerability-gate.js";
 const execPromise = promisify(exec);
@@ -84,6 +85,51 @@ function ignoreScriptsFlags(packageManager) {
         ? ["--ignore-scripts", "--ignore-pnpmfile"]
         : ["--ignore-scripts"];
 }
+/** 7 days. Same window as the quarantine holdback. pnpm counts minutes. */
+const QUARANTINE_WINDOW_DAYS = 7;
+function updateAgeArgs(packageManager) {
+    if (packageManager === "pnpm") {
+        return [`--config.minimum-release-age=${QUARANTINE_WINDOW_DAYS * 24 * 60}`];
+    }
+    return [`--min-release-age=${QUARANTINE_WINDOW_DAYS}`];
+}
+function versionsByName(packages) {
+    const byName = new Map();
+    for (const pkg of packages) {
+        const versions = byName.get(pkg.name) ?? new Set();
+        versions.add(pkg.version);
+        byName.set(pkg.name, versions);
+    }
+    return byName;
+}
+function sameVersions(left, right) {
+    if (!left || left.size !== right.size)
+        return false;
+    for (const version of right) {
+        if (!left.has(version))
+            return false;
+    }
+    return true;
+}
+/** Package-manager text from a failed probe, short enough to show the model. */
+function probeFailureText(error) {
+    if (!(error instanceof Error))
+        return "The package manager failed.";
+    const stderr = "stderr" in error && typeof error.stderr === "string"
+        ? error.stderr.trim()
+        : "";
+    const stdout = "stdout" in error && typeof error.stdout === "string"
+        ? error.stdout.trim()
+        : "";
+    return stripUnsafeChars(scrubSecrets(stderr || stdout || error.message)).slice(0, 500);
+}
+/** Package name behind `npm:prettier@2.8.8`. The alias key is not that package. */
+function npmAliasName(spec) {
+    if (!spec?.startsWith("npm:"))
+        return undefined;
+    const target = spec.slice("npm:".length);
+    return parsePnpmPackageKey(target)?.name ?? (target || undefined);
+}
 /** Lowest version a declared range admits; skips `workspace:`/`file:`/`*`/git. */
 function declaredRangeFloor(range) {
     if (range == null || semver.validRange(range) == null)
@@ -141,6 +187,25 @@ function isNpmErrorEnvelope(parsed) {
  * on some shapes; treat those as top-level so a missing field cannot hide a
  * package from the top-level CVE checks.
  */
+function throwHeldResolution(args) {
+    const { caret, substitutions } = args;
+    const findings = substitutions.map((entry) => {
+        const suggestedVersion = caret && isCaretRelease(`^${entry.toVersion}`)
+            ? `^${entry.toVersion}`
+            : entry.toVersion;
+        return {
+            advisoryId: entry.reason,
+            kind: "cve",
+            package: `${entry.name}@${entry.fromVersion}`,
+            suggestedVersion,
+        };
+    });
+    throw new NpmInstallBlocked({
+        findings,
+        packages: [...new Set(findings.map((finding) => finding.package))],
+        reason: "vulnerable_package",
+    });
+}
 function isRootNodeModulesPath(entryPath) {
     if (typeof entryPath !== "string" || entryPath.length === 0)
         return true;
@@ -211,6 +276,117 @@ const DEFAULT_COPY_DIRECTORY_EXCLUDES = new Set([
  * - Code quality tools (linting, type checking)
  * - Package management
  */
+function isJsonRecord(value) {
+    return value != null && typeof value === "object" && !Array.isArray(value);
+}
+/**
+ * npm reads overrides from package.json. pnpm 12 ignores that field.
+ * `parent>dep` is nested. `name@range` stays a flat key.
+ * A nested value stays until that key is replaced.
+ */
+function packageJsonWithFlatOverrides(args) {
+    const { changes, source } = args;
+    const parsed = JSON.parse(source);
+    if (!isJsonRecord(parsed)) {
+        throw new Error("package.json is not a JSON object");
+    }
+    const buckets = [];
+    if (isJsonRecord(parsed.overrides))
+        buckets.push(parsed.overrides);
+    for (const change of changes) {
+        const selector = parseOverrideSelector(change.name);
+        if (selector?.kind === "parent") {
+            let found = false;
+            for (const bucket of buckets) {
+                const current = bucket[selector.parent];
+                if (change.version === null) {
+                    if (!isJsonRecord(current) || !(selector.child in current))
+                        continue;
+                    delete current[selector.child];
+                    if (Object.keys(current).length === 0)
+                        delete bucket[selector.parent];
+                    found = true;
+                    continue;
+                }
+                if (current === undefined)
+                    continue;
+                if (!isJsonRecord(current)) {
+                    throw new Error(`package.json overrides for ${selector.parent} is not an object`);
+                }
+                current[selector.child] = change.version;
+                found = true;
+            }
+            if (found || change.version === null)
+                continue;
+            if (parsed.overrides === undefined)
+                parsed.overrides = {};
+            if (!isJsonRecord(parsed.overrides)) {
+                throw new Error("package.json overrides is not an object");
+            }
+            parsed.overrides[selector.parent] = {
+                [selector.child]: change.version,
+            };
+            if (!buckets.includes(parsed.overrides))
+                buckets.push(parsed.overrides);
+            continue;
+        }
+        let found = false;
+        for (const bucket of buckets) {
+            if (!(change.name in bucket))
+                continue;
+            found = true;
+            if (change.version === null)
+                delete bucket[change.name];
+            else
+                bucket[change.name] = change.version;
+        }
+        if (found || change.version === null)
+            continue;
+        if (parsed.overrides === undefined)
+            parsed.overrides = {};
+        if (!isJsonRecord(parsed.overrides)) {
+            throw new Error("package.json overrides is not an object");
+        }
+        parsed.overrides[change.name] = change.version;
+        if (!buckets.includes(parsed.overrides))
+            buckets.push(parsed.overrides);
+    }
+    if (isJsonRecord(parsed.overrides) &&
+        Object.keys(parsed.overrides).length === 0) {
+        delete parsed.overrides;
+    }
+    return `${JSON.stringify(parsed, null, 2)}\n`;
+}
+/**
+ * Override keys in pnpm-workspace.yaml. pnpm 12 reads this file and ignores
+ * overrides in package.json. A selector stays a string key.
+ */
+function workspaceYamlWithFlatOverrides(args) {
+    const { changes, source } = args;
+    const doc = parseDocument(source);
+    if (doc.errors.length > 0) {
+        throw new Error("pnpm-workspace.yaml is not valid YAML");
+    }
+    const current = doc.get("overrides");
+    if (current != null && !isMap(current)) {
+        throw new Error("pnpm-workspace.yaml overrides is not a map");
+    }
+    for (const change of changes) {
+        if (change.version === null) {
+            if (doc.has("overrides"))
+                doc.deleteIn(["overrides", change.name]);
+            continue;
+        }
+        doc.setIn(["overrides", change.name], change.version);
+    }
+    const next = doc.get("overrides");
+    if (isMap(next) && next.items.length === 0)
+        doc.delete("overrides");
+    const text = doc.toString();
+    if (text.length === 0)
+        return "";
+    return text.endsWith("\n") ? text : `${text}\n`;
+}
 let AppShell = (() => {
     let _instanceExtraInitializers = [];
     let _readFiles_decorators;
@@ -219,6 +395,8 @@ let AppShell = (() => {
     let _warmLinterCache_decorators;
     let _runNpmInstall_decorators;
     let _runPackageManagerInstall_decorators;
+    let _setPackageOverrides_decorators;
+    let _updatePackages_decorators;
     let _installSpecificPackages_decorators;
     let _uninstallPackages_decorators;
     let _saveGeneratedArtifact_decorators;
@@ -239,6 +417,8 @@ let AppShell = (() => {
             _warmLinterCache_decorators = [llmobs.decorate({ kind: "task", name: "AppShell.warmLinterCache" })];
             _runNpmInstall_decorators = [llmobs.decorate({ kind: "task", name: "AppShell.runNpmInstall" })];
             _runPackageManagerInstall_decorators = [llmobs.decorate({ kind: "task", name: "AppShell.runPackageManagerInstall" })];
+            _setPackageOverrides_decorators = [llmobs.decorate({ kind: "task", name: "AppShell.setPackageOverrides" })];
+            _updatePackages_decorators = [llmobs.decorate({ kind: "task", name: "AppShell.updatePackages" })];
             _installSpecificPackages_decorators = [llmobs.decorate({
                     kind: "task",
                     name: "AppShell.installSpecificPackages",
@@ -259,6 +439,8 @@ let AppShell = (() => {
             __esDecorate(this, null, _warmLinterCache_decorators, { kind: "method", name: "warmLinterCache", static: false, private: false, access: { has: obj => "warmLinterCache" in obj, get: obj => obj.warmLinterCache }, metadata: _metadata }, null, _instanceExtraInitializers);
             __esDecorate(this, null, _runNpmInstall_decorators, { kind: "method", name: "runNpmInstall", static: false, private: false, access: { has: obj => "runNpmInstall" in obj, get: obj => obj.runNpmInstall }, metadata: _metadata }, null, _instanceExtraInitializers);
             __esDecorate(this, null, _runPackageManagerInstall_decorators, { kind: "method", name: "runPackageManagerInstall", static: false, private: false, access: { has: obj => "runPackageManagerInstall" in obj, get: obj => obj.runPackageManagerInstall }, metadata: _metadata }, null, _instanceExtraInitializers);
+            __esDecorate(this, null, _setPackageOverrides_decorators, { kind: "method", name: "setPackageOverrides", static: false, private: false, access: { has: obj => "setPackageOverrides" in obj, get: obj => obj.setPackageOverrides }, metadata: _metadata }, null, _instanceExtraInitializers);
+            __esDecorate(this, null, _updatePackages_decorators, { kind: "method", name: "updatePackages", static: false, private: false, access: { has: obj => "updatePackages" in obj, get: obj => obj.updatePackages }, metadata: _metadata }, null, _instanceExtraInitializers);
             __esDecorate(this, null, _installSpecificPackages_decorators, { kind: "method", name: "installSpecificPackages", static: false, private: false, access: { has: obj => "installSpecificPackages" in obj, get: obj => obj.installSpecificPackages }, metadata: _metadata }, null, _instanceExtraInitializers);
             __esDecorate(this, null, _uninstallPackages_decorators, { kind: "method", name: "uninstallPackages", static: false, private: false, access: { has: obj => "uninstallPackages" in obj, get: obj => obj.uninstallPackages }, metadata: _metadata }, null, _instanceExtraInitializers);
             __esDecorate(this, null, _saveGeneratedArtifact_decorators, { kind: "method", name: "saveGeneratedArtifact", static: false, private: false, access: { has: obj => "saveGeneratedArtifact" in obj, get: obj => obj.saveGeneratedArtifact }, metadata: _metadata }, null, _instanceExtraInitializers);
@@ -300,8 +482,9 @@ let AppShell = (() => {
         reportNpmInstallBlocked;
         /**
          * Optional sink for privacy-safe install-gate USER_EVENT reports. One call
-         * per gated AppShell install (`install_all` / `install_specific`) with
-         * outcome + runner only. Prefetch and uninstall never report.
+         * per gated AppShell install (`install_all` / `install_specific` /
+         * `update`) with outcome + runner only. Prefetch and uninstall never
+         * report.
          */
         reportNpmInstallOutcome;
         /**
@@ -757,12 +940,15 @@ let AppShell = (() => {
         }
         /**
          * Report a gated install outcome for Snowflake USER_EVENTs. Only
-         * `install_all` and `install_specific` run the vulnerability gate.
-         * Fire-and-forget: a reporting failure must never break the install.
+         * `install_all`, `install_specific`, and `update` run the vulnerability
+         * gate. Fire-and-forget: a reporting failure must never break the install.
          */
         maybeReportInstallOutcome(runner, outcome) {
-            if (runner !== "install_all" && runner !== "install_specific")
+            if (runner !== "install_all" &&
+                runner !== "install_specific" &&
+                runner !== "update") {
                 return;
+            }
             if (!this.reportNpmInstallOutcome)
                 return;
             try {
@@ -1128,6 +1314,56 @@ let AppShell = (() => {
             }
             return results;
         }
+        /**
+         * Versions `npm update` / `pnpm update` would install. A failed probe does
+         * not fall back to the lockfile: that tree is the one already installed.
+         */
+        async resolveUpdateTree(args) {
+            const { abortSignal, ignoreScripts, packages, updatePackageNames } = args;
+            let resolved;
+            try {
+                resolved = await this.resolveTreeViaNpmDryRun({
+                    abortSignal,
+                    ignoreScripts,
+                    npmCommand: "update",
+                    specs: updatePackageNames,
+                });
+            }
+            catch (err) {
+                if (abortSignal?.aborted ||
+                    (err instanceof Error && err.name === "AbortError")) {
+                    throw err;
+                }
+                return { resolves: false, topLevel: [], tree: [] };
+            }
+            if (!resolved.resolves) {
+                return { resolves: false, topLevel: [], tree: [] };
+            }
+            const wanted = new Set(updatePackageNames.length > 0
+                ? updatePackageNames
+                : (packages ?? []).map((pkg) => pkg.name));
+            for (const pkg of packages ?? []) {
+                if (!wanted.has(pkg.name))
+                    continue;
+                const alias = npmAliasName(pkg.version);
+                if (alias)
+                    wanted.add(alias);
+            }
+            const topLevel = [];
+            const seen = new Set();
+            for (const pkg of resolved.topLevel) {
+                if (!wanted.has(pkg.name) || seen.has(pkg.name))
+                    continue;
+                seen.add(pkg.name);
+                topLevel.push(pkg);
+            }
+            return {
+                resolves: true,
+                topLevel,
+                tree: resolved.tree,
+                unnamed: resolved.unnamed,
+            };
+        }
         /**
          * Mode 1: npm dry-run + lockfile.
          * Mode 2: `topLevel` is always declared package.json floors (CVE remediations).
@@ -1135,7 +1371,16 @@ let AppShell = (() => {
          * rewrite). Local stays floors-only — pnpm + lingering `workspace:*` mean
          * full-tree coverage is not available there.
          */
-        async resolveInstallTree(mode, packages, abortSignal, ignoreScripts) {
+        async resolveInstallTree(args) {
+            const { abortSignal, ignoreScripts, mode, packages, updatePackageNames } = args;
+            if (mode === "all" && updatePackageNames !== undefined) {
+                return await this.resolveUpdateTree({
+                    abortSignal,
+                    ignoreScripts,
+                    packages,
+                    updatePackageNames,
+                });
+            }
             if (mode === "all") {
                 const topLevel = [];
                 for (const pkg of packages ?? []) {
@@ -1150,7 +1395,12 @@ let AppShell = (() => {
                 const fromLock = await this.readPackagesFromPackageLock();
                 let dryTree = [];
                 try {
-                    dryTree = (await this.resolveTreeViaNpmDryRun([], abortSignal, ignoreScripts)).tree;
+                    dryTree = (await this.resolveTreeViaNpmDryRun({
+                        abortSignal,
+                        ignoreScripts,
+                        npmCommand: "install",
+                        specs: [],
+                    })).tree;
                 }
                 catch (err) {
                     // Do not continue remediation after cancel.
@@ -1170,7 +1420,11 @@ let AppShell = (() => {
                 return { resolves: true, topLevel, tree: [...byKey.values()] };
             }
             const specs = (packages ?? []).map((pkg) => pkg.version ? `${pkg.name}@${pkg.version}` : pkg.name);
-            const resolved = await this.resolveTreeViaNpmDryRun(specs, abortSignal, ignoreScripts);
+            const resolved = await this.resolveTreeViaNpmDryRun({
+                abortSignal,
+                ignoreScripts,
+                specs,
+            });
             // Prefer dry-run concrete pins for top-level. Never inject the raw
             // requested range/`latest` string into the lookup tree — the index
             // keys on concrete versions, and a range would fail coverage checks.
@@ -1209,16 +1463,23 @@ let AppShell = (() => {
                 unnamed: resolved.unnamed,
             };
         }
-        async resolveTreeViaNpmDryRun(specs, abortSignal, ignoreScripts) {
+        async resolveTreeViaNpmDryRun(probe) {
+            const { abortSignal, ignoreScripts, npmCommand = "install", specs } = probe;
             if (isPnpmEnabled() && (await this.appPackageManager()) === "pnpm") {
-                return this.resolveTreeViaPnpmLockfile(specs, abortSignal, ignoreScripts);
+                return this.resolveTreeViaPnpmLockfile({
+                    abortSignal,
+                    ignoreScripts,
+                    npmCommand,
+                    specs,
+                });
             }
             const args = [
-                "install",
+                npmCommand,
                 "--dry-run",
                 "--json",
                 "--fund=false",
                 "--audit=false",
+                ...(npmCommand === "update" ? updateAgeArgs("npm") : []),
                 // `--` so a spec that looks like an option (`--registry=…`,
                 // `--userconfig=…`) is parsed as a package name instead of
                 // reconfiguring the probe: the gate scans the tree this resolves, so a
@@ -1284,7 +1545,11 @@ let AppShell = (() => {
          * more packages than get installed, never fewer. The app's locked tree is
          * scanned from its lockfile in `resolveInstallTree`.
          */
-        async resolveTreeViaPnpmLockfile(specs, abortSignal, ignoreScripts) {
+        async resolveTreeViaPnpmLockfile(probe) {
+            const { abortSignal, ignoreScripts, npmCommand = "install", specs } = probe;
+            // A member of a parent workspace has no lockfile in this copy, so the
+            // probe fails closed. It does not write the shared lockfile. Cloud edit
+            // is one app and does not hit that case.
             const dir = await mkdtemp(path.join(os.tmpdir(), "sb-pnpm-resolve-"));
             try {
                 for (const file of [
@@ -1306,17 +1571,26 @@ let AppShell = (() => {
                     "--lockfile-only",
                     ...(ignoreScripts ? ignoreScriptsFlags("pnpm") : ["--ignore-scripts"]),
                 ];
-                const onlyNewPackages = specs.length > 0 &&
+                const onlyNewPackages = npmCommand === "install" &&
+                    specs.length > 0 &&
                     (await this.lockfileIsUpToDate(dir, flags, abortSignal));
                 if (onlyNewPackages) {
                     await this.keepOnlyNewPackages(dir);
                 }
-                const args = specs.length > 0
-                    ? ["add", ...flags, "--", ...specs]
-                    : // The lockfile has to be allowed to change, as on the real
-                        // install. pnpm 12 already allows that with `--lockfile-only`
-                        // under `CI=true`; the flag says so outright. `pnpm add` rejects it.
-                        ["install", ...flags, "--no-frozen-lockfile"];
+                const ageArgs = npmCommand === "update" ? updateAgeArgs("pnpm") : [];
+                const args = npmCommand === "update"
+                    ? [
+                        "update",
+                        ...flags,
+                        ...ageArgs,
+                        ...(specs.length > 0 ? ["--", ...specs] : []),
+                    ]
+                    : specs.length > 0
+                        ? ["add", ...flags, "--", ...specs]
+                        : // The lockfile has to be allowed to change, as on the real
+                            // install. pnpm 12 already allows that with `--lockfile-only`
+                            // under `CI=true`; the flag says so outright. `pnpm add` rejects it.
+                            ["install", ...flags, "--no-frozen-lockfile"];
                 await execFilePromise("pnpm", args, {
                     cwd: dir,
                     env: this.installLogEnv(),
@@ -1324,8 +1598,14 @@ let AppShell = (() => {
                     maxBuffer: NPM_JSON_MAX_BUFFER,
                 });
                 const locked = readPnpmLockfile(await fsReadFile(path.join(dir, "pnpm-lock.yaml"), "utf8"));
-                if (!locked)
-                    return { tree: [], topLevel: [], resolves: false };
+                if (!locked) {
+                    return {
+                        failure: "pnpm wrote a lockfile that could not be read.",
+                        resolves: false,
+                        topLevel: [],
+                        tree: [],
+                    };
+                }
                 // A tarball or git package already in the app's lockfile is already
                 // installed; only the ones this install adds are new.
                 const installed = new Set((await this.readPackagesFromPackageLock())?.unnamed);
@@ -1340,12 +1620,36 @@ let AppShell = (() => {
                     (error instanceof Error && error.name === "AbortError")) {
                     throw error;
                 }
-                return { tree: [], topLevel: [], resolves: false };
+                return {
+                    failure: probeFailureText(error),
+                    resolves: false,
+                    topLevel: [],
+                    tree: [],
+                };
             }
             finally {
                 await rm(dir, { recursive: true, force: true });
             }
         }
+        /**
+         * Nearest directory that contains `pnpm-workspace.yaml`. The lockfile for a
+         * workspace member lives there, not beside the member's package.json.
+         */
+        async pnpmWorkspaceRoot() {
+            let dir = path.resolve(this.appRootDirPath);
+            for (;;) {
+                try {
+                    await access(path.join(dir, "pnpm-workspace.yaml"));
+                    return dir;
+                }
+                catch {
+                    const parent = path.dirname(dir);
+                    if (parent === dir)
+                        return null;
+                    dir = parent;
+                }
+            }
+        }
         /**
          * Whether the app's lockfile, as copied into `dir`, already accounts for its
          * manifest, overrides and pnpmfile: pnpm's frozen install, offline, so it
@@ -1390,7 +1694,6 @@ let AppShell = (() => {
             if (parsed == null || typeof parsed !== "object") {
                 return { tree: [], topLevel: [], resolves: true };
             }
-            const record = parsed;
             const tree = [];
             const root = [];
             const seen = new Set();
@@ -1407,24 +1710,25 @@ let AppShell = (() => {
                 if (isRootNodeModulesPath(entryPath))
                     root.push({ name, version });
             };
-            if (Array.isArray(record.add)) {
-                for (const entry of record.add) {
-                    if (entry == null || typeof entry !== "object")
-                        continue;
-                    const pkg = entry;
-                    push(pkg.name, pkg.version, pkg.path);
-                }
+            const list = (key) => {
+                const value = Reflect.get(parsed, key);
+                return Array.isArray(value) ? value : [];
+            };
+            const pushEntry = (entry) => {
+                push(Reflect.get(entry, "name"), Reflect.get(entry, "version"), Reflect.get(entry, "path"));
+            };
+            for (const entry of list("add")) {
+                if (entry == null || typeof entry !== "object")
+                    continue;
+                pushEntry(entry);
             }
-            if (Array.isArray(record.change)) {
-                for (const entry of record.change) {
-                    if (entry == null || typeof entry !== "object")
-                        continue;
-                    const change = entry;
-                    if (change.to == null || typeof change.to !== "object")
-                        continue;
-                    const to = change.to;
-                    push(to.name, to.version, to.path);
-                }
+            for (const entry of list("change")) {
+                if (entry == null || typeof entry !== "object")
+                    continue;
+                const to = Reflect.get(entry, "to");
+                if (to == null || typeof to !== "object")
+                    continue;
+                pushEntry(to);
             }
             const topLevelNames = new Set(specs.map((spec) => {
                 if (spec.startsWith("@")) {
@@ -1437,14 +1741,29 @@ let AppShell = (() => {
             // A dependency's nested copy shares the requested name but is a different
             // version, and vouching for it would let the requested one install
             // unchecked.
-            const topLevel = root.filter((pkg) => topLevelNames.has(pkg.name));
+            // No specs means the whole update. Root entries are the pins it would adopt.
+            const topLevel = topLevelNames.size === 0
+                ? root
+                : root.filter((pkg) => topLevelNames.has(pkg.name));
+            // npm 11 prints `added` / `changed` counts. A positive count with no
+            // package list is not an empty tree: the update would install versions
+            // this probe did not name.
+            const added = Reflect.get(parsed, "added");
+            const changed = Reflect.get(parsed, "changed");
+            const positive = (value) => typeof value === "number" && value > 0;
+            if (tree.length === 0 && (positive(added) || positive(changed))) {
+                return { resolves: false, topLevel: [], tree: [] };
+            }
             return { tree, topLevel, resolves: true };
         }
         async readPackagesFromPackageLock() {
             // A pnpm app's installed tree is in `pnpm-lock.yaml`; a `package-lock.json`
             // left over from its npm days would describe packages pnpm never installs.
             if (isPnpmEnabled() && (await this.appPackageManager()) === "pnpm") {
-                const locked = readPnpmLockfile(await fsReadFile(path.join(this.appRootDirPath, "pnpm-lock.yaml"), "utf8").catch(() => ""));
+                // A workspace member's lockfile sits next to `pnpm-workspace.yaml`,
+                // which may be a parent of the app. The app directory often has none.
+                const root = await this.pnpmWorkspaceRoot();
+                const locked = readPnpmLockfile(await fsReadFile(path.join(root ?? this.appRootDirPath, "pnpm-lock.yaml"), "utf8").catch(() => ""));
                 return locked ? { ...locked, resolves: true } : null;
             }
             const lockPath = path.join(this.appRootDirPath, "package-lock.json");
@@ -1526,9 +1845,15 @@ let AppShell = (() => {
             if (!this.packageLookup) {
                 return { substitutions: [] };
             }
-            const packages = mode === "all"
+            const declared = mode === "all"
                 ? await readDeclaredDependencies(this.appRootDirPath)
                 : args.packages;
+            // A named update may rewrite only those packages. An empty list still
+            // means every declared dependency.
+            const named = args.updatePackageNames;
+            const packages = named && named.length > 0
+                ? (declared ?? []).filter((pkg) => named.includes(pkg.name))
+                : declared;
             return await runVulnerabilityGate({
                 abortSignal,
                 capabilities: {
@@ -1538,9 +1863,24 @@ let AppShell = (() => {
                         getLogger().warn(message, getErrorMeta(error));
                     },
                     pickQuarantineHoldback: this.packageLookup.pickQuarantineHoldback,
-                    resolveInstallTree: async (resolveArgs) => await this.resolveInstallTree(resolveArgs.mode, resolveArgs.packages, resolveArgs.abortSignal, ignoreScripts),
-                    resolvePackageSpecs: async (resolveArgs) => await this.resolveTreeViaNpmDryRun(resolveArgs.specs, resolveArgs.abortSignal, ignoreScripts),
+                    resolveInstallTree: async (resolveArgs) => await this.resolveInstallTree({
+                        abortSignal: resolveArgs.abortSignal,
+                        ignoreScripts,
+                        mode: resolveArgs.mode,
+                        packages: resolveArgs.packages,
+                        ...(args.updatePackageNames !== undefined
+                            ? { updatePackageNames: args.updatePackageNames }
+                            : {}),
+                    }),
+                    resolvePackageSpecs: async (resolveArgs) => await this.resolveTreeViaNpmDryRun({
+                        abortSignal: resolveArgs.abortSignal,
+                        ignoreScripts,
+                        specs: resolveArgs.specs,
+                    }),
                 },
+                ...(args.updatePackageNames !== undefined
+                    ? { checkUpdatePins: true }
+                    : {}),
                 cveUserOverride,
                 mode,
                 packages,
@@ -1788,6 +2128,264 @@ let AppShell = (() => {
                 this.observeNpmInstall("install_all", capturedFetchResult, outcome, Date.now() - installStart, capturedPackageManager);
             }
         }
+        /**
+         * Edit one targeted override, then install. The name is `parent>dep` or
+         * `name@range`. The version is a caret release such as `^1.2.3`. pnpm 12
+         * reads the map from pnpm-workspace.yaml. npm reads it from package.json.
+         * Every concrete version the change adds goes through the specific install
+         * gate. A block or a holdback restores the file. No lockfile means every
+         * resolved package counts as new.
+         */
+        async setPackageOverrides(args) {
+            const { abortSignal, changes } = args;
+            if (changes.length === 0) {
+                throw new Error("No override changes were given.");
+            }
+            const invalidNames = changes.filter((change) => {
+                if (parseOverrideSelector(change.name))
+                    return false;
+                // A removal can still delete a flat key already in the file.
+                return change.version !== null || !isValidNpmPackageName(change.name);
+            });
+            if (invalidNames.length > 0) {
+                throw new Error(`Override name must be parent>package or name@range: ${invalidNames.map((change) => change.name).join(", ")}.`);
+            }
+            const invalidVersions = changes.filter((change) => change.version !== null && !isCaretRelease(change.version));
+            if (invalidVersions.length > 0) {
+                throw new Error(`Override version must be a caret release such as ^1.2.3: ${invalidVersions.map((change) => change.name).join(", ")}.`);
+            }
+            const protectedTargets = [
+                ...new Set(changes.flatMap((change) => {
+                    if (change.version === null)
+                        return [];
+                    const selector = parseOverrideSelector(change.name);
+                    if (!selector)
+                        return [];
+                    const target = selector.kind === "parent" ? selector.child : selector.name;
+                    return isProtectedCorePackage(target) ? [target] : [];
+                })),
+            ];
+            if (protectedTargets.length > 0) {
+                throw new Error(`Refusing to override protected core package(s): ${protectedTargets.join(", ")}. ` +
+                    "These are required by the Superblocks platform (dev server, build pipeline, or app runtime) and must keep the version the app declares.");
+            }
+            const manifestPath = path.join(this.appRootDirPath, "package.json");
+            const packageManager = await this.installingPackageManager();
+            const workspaceFile = packageManager === "pnpm"
+                ? path.join((await this.pnpmWorkspaceRoot()) ?? this.appRootDirPath, "pnpm-workspace.yaml")
+                : undefined;
+            // null means the file was not there. A string is the text to restore.
+            let yamlOriginal = null;
+            if (workspaceFile) {
+                try {
+                    yamlOriginal = await this.enqueueFsOperation("readWorkspaceOverrides", () => fsReadFile(workspaceFile, "utf8"));
+                }
+                catch (error) {
+                    const missing = typeof error === "object" &&
+                        error !== null &&
+                        "code" in error &&
+                        error.code === "ENOENT";
+                    if (!missing)
+                        throw error;
+                }
+            }
+            let installStarted = false;
+            let original = "";
+            let savedOriginal = false;
+            try {
+                return await this.withAuthFailedRetry(async (registryFetchResult) => {
+                    this.maybeShortCircuitForUnreachable(registryFetchResult, changes.map((change) => change.name));
+                    await this.maybePreparePackageJsonForCloudNpm();
+                    if (!savedOriginal) {
+                        original = await this.enqueueFsOperation("readPackageJson", () => fsReadFile(manifestPath, "utf8"));
+                        savedOriginal = true;
+                    }
+                    const next = packageJsonWithFlatOverrides({
+                        changes,
+                        source: original,
+                    });
+                    await this.enqueueFsOperation("writePackageOverrides", () => writeFile(manifestPath, next));
+                    if (workspaceFile) {
+                        const nextYaml = workspaceYamlWithFlatOverrides({
+                            changes,
+                            source: yamlOriginal ?? "",
+                        });
+                        await this.enqueueFsOperation("writeWorkspaceOverrides", async () => {
+                            if (nextYaml.length === 0) {
+                                await rm(workspaceFile, { force: true });
+                                return;
+                            }
+                            await writeFile(workspaceFile, nextYaml);
+                        });
+                    }
+                    const ignoreScripts = shouldIgnoreInstallScripts(registryFetchResult);
+                    const before = await this.readPackagesFromPackageLock();
+                    const beforeVersions = versionsByName(before?.tree ?? []);
+                    const after = await this.resolveTreeViaNpmDryRun({
+                        abortSignal,
+                        ignoreScripts,
+                        npmCommand: "install",
+                        specs: [],
+                    });
+                    if (!after.resolves) {
+                        const detail = after.failure?.trim();
+                        throw new Error(detail
+                            ? `Could not resolve packages after the override change. ${detail}`
+                            : "Could not resolve packages after the override change.");
+                    }
+                    const beforeUnnamed = new Set(before?.unnamed ?? []);
+                    const newUnnamed = (after.unnamed ?? []).filter((key) => !beforeUnnamed.has(key));
+                    if (newUnnamed.length > 0) {
+                        throw new NpmInstallBlocked({
+                            findings: newUnnamed.map((pkg) => ({
+                                advisoryId: "index_unavailable",
+                                kind: "index_unavailable",
+                                package: pkg,
+                            })),
+                            packages: newUnnamed,
+                            reason: "vulnerable_package",
+                        });
+                    }
+                    const afterVersions = versionsByName(after.tree);
+                    const seenPins = new Set();
+                    // A name whose version set changed is checked in full. Promoting a
+                    // version that already sat somewhere in the old tree still counts.
+                    const changedPins = after.tree.filter((pkg) => {
+                        const key = `${pkg.name}@${pkg.version}`;
+                        if (seenPins.has(key))
+                            return false;
+                        seenPins.add(key);
+                        const afterSet = afterVersions.get(pkg.name) ?? new Set();
+                        return !sameVersions(beforeVersions.get(pkg.name), afterSet);
+                    });
+                    if (changedPins.length > 0) {
+                        const remediation = await this.maybeRemediateVulnerabilities({
+                            abortSignal,
+                            ignoreScripts,
+                            mode: "specific",
+                            packages: changedPins.map((pkg) => ({
+                                name: pkg.name,
+                                version: pkg.version,
+                            })),
+                        });
+                        if (remediation.substitutions.length > 0) {
+                            throwHeldResolution({
+                                caret: true,
+                                substitutions: remediation.substitutions,
+                            });
+                        }
+                    }
+                    installStarted = true;
+                    return await this.runPackageManagerInstall(abortSignal);
+                });
+            }
+            catch (error) {
+                // Once the install has started, the lockfile matches the new manifest.
+                // Rolling package.json back would leave those two files apart.
+                if (savedOriginal && !installStarted) {
+                    await this.enqueueFsOperation("restorePackageOverrides", () => writeFile(manifestPath, original)).catch((restoreError) => {
+                        getLogger().error("Failed to restore package.json after an override change", getErrorMeta(restoreError));
+                    });
+                }
+                if (workspaceFile && !installStarted) {
+                    const file = workspaceFile;
+                    await this.enqueueFsOperation("restoreWorkspaceOverrides", async () => {
+                        if (yamlOriginal === null) {
+                            await rm(file, { force: true });
+                            return;
+                        }
+                        await writeFile(file, yamlOriginal);
+                    }).catch((restoreError) => {
+                        getLogger().error("Failed to restore pnpm-workspace.yaml after an override change", getErrorMeta(restoreError));
+                    });
+                }
+                if (!installStarted) {
+                    this.maybeReportBlockedInstall(error, "install_specific");
+                }
+                throw error;
+            }
+        }
+        /**
+         * `npm update` / `pnpm update`. Moves installed versions to the newest
+         * release the ranges in package.json already allow. Does not add a package
+         * and does not change those ranges. The vulnerability gate scans the tree
+         * the update would install. Protected-package removal stays on
+         * `uninstallPackages`.
+         */
+        async updatePackages(packages, abortSignal) {
+            const requested = packages ?? [];
+            const invalidRequested = requested.filter((name) => !isValidNpmPackageName(name));
+            if (invalidRequested.length > 0) {
+                throw new Error(`Invalid package name(s): ${invalidRequested.join(", ")}.`);
+            }
+            const installStart = Date.now();
+            let outcome = "success";
+            let capturedFetchResult;
+            let capturedPackageManager;
+            try {
+                return await this.withAuthFailedRetry(async (registryFetchResult) => {
+                    capturedFetchResult = registryFetchResult;
+                    this.maybeShortCircuitForUnreachable(registryFetchResult, requested);
+                    const packageManagerAgent = await this.installingPackageManager();
+                    await this.maybePreparePackageJsonForCloudNpm();
+                    capturedPackageManager = packageManagerAgent;
+                    const remediation = await this.maybeRemediateVulnerabilities({
+                        abortSignal,
+                        ignoreScripts: shouldIgnoreInstallScripts(registryFetchResult),
+                        mode: "all",
+                        updatePackageNames: requested,
+                    });
+                    if (remediation.substitutions.length > 0) {
+                        throwHeldResolution({
+                            caret: false,
+                            substitutions: remediation.substitutions,
+                        });
+                    }
+                    const ignoreScripts = shouldIgnoreInstallScripts(registryFetchResult);
+                    const isNpm = packageManagerAgent === "npm";
+                    const ageArgs = updateAgeArgs(isNpm ? "npm" : "pnpm");
+                    const baseArgs = isNpm
+                        ? [
+                            "--fund=false",
+                            "--audit=false",
+                            "--json",
+                            ...ageArgs,
+                            ...requested,
+                        ]
+                        : [...ageArgs, ...requested];
+                    const resolved = resolveCommand(packageManagerAgent, "upgrade", ignoreScripts
+                        ? [...ignoreScriptsFlags(packageManagerAgent), ...baseArgs]
+                        : baseArgs);
+                    if (!resolved) {
+                        throw new Error(`Could not determine upgrade command for ${packageManagerAgent}`);
+                    }
+                    let stdout;
+                    try {
+                        ({ stdout } = await execPromise(`${resolved.command} ${resolved.args.join(" ")}`, {
+                            cwd: this.appRootDirPath,
+                            env: this.installLogEnv(),
+                            signal: abortSignal,
+                            maxBuffer: NPM_JSON_MAX_BUFFER,
+                        }));
+                    }
+                    catch (error) {
+                        if (isNpm) {
+                            throw this.classifyNpmExecError(error, undefined, registryFetchResult);
+                        }
+                        throw this.classifyPnpmExecError(error, undefined, registryFetchResult);
+                    }
+                    return isNpm ? (parseNpmJsonSuccess(stdout) ?? stdout) : stdout;
+                });
+            }
+            catch (err) {
+                outcome = outcomeFromInstallError(err);
+                this.maybeReportBlockedInstall(err, "update");
+                throw err;
+            }
+            finally {
+                this.observeNpmInstall("update", capturedFetchResult, outcome, Date.now() - installStart, capturedPackageManager);
+            }
+        }
         async installSpecificPackages(packages, abortSignal, options) {
             if (!packages || packages.length === 0) {
                 throw new Error("No packages specified for installation");