@uniformdev/next-app-router-upgrade 0.0.0-stage → 0.1.0

package/src/edge/vercel.js

@@ -0,0 +1,360 @@
+// Phase 2 on Vercel: turn on edge mode with vercelUniformEdgeMiddleware.
+// The steps follow "Set up edge mode on Vercel" in the docs.
+
+import fs from "node:fs";
+import path from "node:path";
+import ts from "typescript";
+
+import { addToBlock } from "../json-text.js";
+import { applyEdits } from "../migrate.js";
+import { listSourceFiles, scriptKind } from "../scan.js";
+
+const SDK = "@uniformdev/next-app-router";
+const VERCEL = `${SDK}/vercel`;
+const EDGE_HEADER = "x-uniform-edge-origin";
+const VERCEL_FUNCTIONS_RANGE = "^3.7.2";
+const DEFAULT_SOURCE = "/((?!api|_next/static|_next/image|favicon.ico|sitemap.xml|robots.txt).*)";
+const MISSING_RULE = `[{ type: "header", key: "${EDGE_HEADER}" }]`;
+const LITE = new Set(["uniformMiddleware"]);
+
+/**
+ * Returns { changes, contents, manual, reminders } for phase 2 on Vercel. Reminders are not code changes.
+ * `base` maps absolute paths to the text after phase 1, so that the two phases make one plan.
+ */
+export function planVercelEdge(root, { base = new Map() } = {}) {
+  const read = (file) => base.get(file) ?? fs.readFileSync(file, "utf8");
+  const changes = [];
+  const contents = new Map();
+  const manual = [];
+  const save = (file, text, fileChanges) => {
+    if (text !== read(file)) contents.set(file, text);
+    changes.push(...fileChanges);
+  };
+
+  // Step 1: @vercel/functions.
+  const pkgFile = path.join(root, "package.json");
+  const pkgText = read(pkgFile);
+  const pkg = JSON.parse(pkgText);
+  if (!pkg.dependencies?.["@vercel/functions"] && !pkg.devDependencies?.["@vercel/functions"]) {
+    save(pkgFile, addToBlock(pkgText, "dependencies", "@vercel/functions", VERCEL_FUNCTIONS_RANGE), [
+      { file: "package.json", rule: "edge-vercel-functions", description: `Add @vercel/functions ${VERCEL_FUNCTIONS_RANGE}. vercelUniformEdgeMiddleware needs it.` },
+    ]);
+  }
+
+  // Step 2: the middleware.
+  const middleware = findMiddlewareFile(root);
+  if (!middleware) {
+    manual.push("No middleware.ts was found. Add middleware.ts with vercelUniformEdgeMiddleware, as in the docs.");
+  } else if (/^proxy\./.test(path.basename(middleware))) {
+    manual.push(
+      `${path.relative(root, middleware)}: edge mode needs middleware.ts with runtime "experimental-edge" (vercel/next.js#82344). Rename the file to middleware.ts, and then run the migration again.`
+    );
+  } else {
+    const result = migrateMiddleware(root, middleware, read(middleware));
+    save(middleware, result.text, result.changes);
+    manual.push(...result.manual);
+  }
+
+  // Steps 3 and 4: static params and the preview route, in all source files.
+  for (const file of listSourceFiles(root)) {
+    if (file === middleware) continue;
+    const text = read(file);
+    if (!text.includes(SDK)) continue;
+    const result = migrateRouteFile(root, file, text);
+    if (result.changes.length || result.manual.length) {
+      save(file, result.text, result.changes);
+      manual.push(...result.manual);
+    }
+  }
+
+  const reminders = [
+    "In Uniform, make sure that a webhook sends manifest.published, composition.*, entry.*, projectmap.node.* and redirect.* to /api/preview. The migration cannot check this.",
+  ];
+  return { changes, contents, manual, reminders };
+}
+
+function findMiddlewareFile(root) {
+  for (const dir of ["", "src"]) {
+    for (const name of ["middleware", "proxy"]) {
+      for (const ext of [".ts", ".js", ".mts", ".mjs", ".tsx", ".jsx"]) {
+        const file = path.join(root, dir, name + ext);
+        if (fs.existsSync(file)) return file;
+      }
+    }
+  }
+  return undefined;
+}
+
+function parse(file, text) {
+  return ts.createSourceFile(file, text, ts.ScriptTarget.Latest, true, scriptKind(file));
+}
+
+function sdkImports(sf) {
+  const locals = new Map();
+  for (const statement of sf.statements) {
+    if (!ts.isImportDeclaration(statement) || !ts.isStringLiteral(statement.moduleSpecifier)) continue;
+    const module = statement.moduleSpecifier.text;
+    if (!module.startsWith(SDK)) continue;
+    const bindings = statement.importClause?.namedBindings;
+    if (bindings && ts.isNamedImports(bindings)) {
+      for (const element of bindings.elements) {
+        locals.set(element.name.text, { module, imported: (element.propertyName ?? element.name).text, element, statement });
+      }
+    }
+  }
+  return locals;
+}
+
+// The middleware file
+
+export function migrateMiddleware(root, file, text) {
+  const sf = parse(file, text);
+  const rel = path.relative(root, file);
+  const lineOf = (node) => sf.getLineAndCharacterOfPosition(node.getStart(sf)).line + 1;
+  const edits = [];
+  const changes = [];
+  const manual = [];
+  const record = (node, description) => changes.push({ file: rel, line: node ? lineOf(node) : undefined, rule: "edge-middleware", description });
+
+  const locals = sdkImports(sf);
+  const usesEdge = [...locals.values()].some((info) => info.module === VERCEL && info.imported === "vercelUniformEdgeMiddleware");
+  const lite = [...locals.entries()].find(([, info]) => info.module === `${SDK}/middleware` && LITE.has(info.imported));
+  const handle = [...locals.entries()].find(([, info]) => info.module === `${SDK}/middleware` && info.imported === "handleUniformRoute");
+
+  if (!usesEdge && lite) {
+    const [local, info] = lite;
+    // Swap the factory only when each reference is a call: uniformMiddleware({ ... }).
+    const references = [];
+    let other = false;
+    const visit = (node) => {
+      if (ts.isIdentifier(node) && node.text === local && node !== info.element.name && !ts.isImportSpecifier(node.parent)) {
+        if (ts.isCallExpression(node.parent) && node.parent.expression === node) references.push(node);
+        else other = true;
+      }
+      ts.forEachChild(node, visit);
+    };
+    visit(sf);
+
+    if (other || !references.length) {
+      manual.push(`${rel}: ${local} is used in a way that the migration cannot change. Replace it with vercelUniformEdgeMiddleware from ${VERCEL}.`);
+    } else {
+      for (const reference of references) {
+        edits.push({ start: reference.getStart(sf), end: reference.end, text: "vercelUniformEdgeMiddleware" });
+        record(reference, `Replace ${local}(...) with vercelUniformEdgeMiddleware(...). It accepts the same options.`);
+      }
+      edits.push(...replaceImport(sf, info, "vercelUniformEdgeMiddleware", VERCEL));
+    }
+  } else if (!usesEdge && handle) {
+    manual.push(
+      `${rel}: the middleware calls handleUniformRoute in a custom function. Replace it with vercelUniformEdgeMiddleware(options)(request, event), or with handleUniformEdgeRoute. The migration does not change custom middleware.`
+    );
+  } else if (!usesEdge) {
+    manual.push(`${rel}: the middleware does not use uniformMiddleware. Add vercelUniformEdgeMiddleware, as in the docs.`);
+  }
+
+  // export const config = { matcher, runtime }
+  const config = findExportedConst(sf, "config");
+  if (!config) {
+    const block = `\nexport const config = {\n  matcher: [\n    {\n      source: "${DEFAULT_SOURCE}",\n      missing: ${MISSING_RULE},\n    },\n  ],\n  runtime: "experimental-edge",\n};\n`;
+    edits.push({ start: text.length, end: text.length, text: (text.endsWith("\n") ? "" : "\n") + block });
+    record(undefined, "Add the middleware config: the default matcher of the docs with the missing header rule, and runtime \"experimental-edge\". Before, the middleware ran on all paths.");
+  } else if (!ts.isObjectLiteralExpression(config)) {
+    manual.push(`${rel}: the middleware config is not an object literal. Add missing: ${MISSING_RULE} to each matcher, and runtime: "experimental-edge".`);
+  } else {
+    const matcher = findProperty(config, "matcher");
+    if (!matcher) {
+      edits.push(insertProperty(sf, config, `matcher: [{ source: "${DEFAULT_SOURCE}", missing: ${MISSING_RULE} }]`));
+      record(config, "Add a matcher with the missing header rule.");
+    } else if (ts.isPropertyAssignment(matcher)) {
+      const value = matcher.initializer;
+      if (ts.isStringLiteral(value) || ts.isNoSubstitutionTemplateLiteral(value)) {
+        edits.push({ start: value.getStart(sf), end: value.end, text: `[{ source: ${value.getText(sf)}, missing: ${MISSING_RULE} }]` });
+        record(matcher, "Change the matcher to an object with the missing header rule.");
+      } else if (ts.isArrayLiteralExpression(value)) {
+        for (const element of value.elements) {
+          if (ts.isStringLiteral(element) || ts.isNoSubstitutionTemplateLiteral(element)) {
+            edits.push({ start: element.getStart(sf), end: element.end, text: `{ source: ${element.getText(sf)}, missing: ${MISSING_RULE} }` });
+            record(element, "Add the missing header rule to the matcher.");
+          } else if (ts.isObjectLiteralExpression(element)) {
+            const missing = findProperty(element, "missing");
+            if (!missing) {
+              edits.push(insertProperty(sf, element, `missing: ${MISSING_RULE}`));
+              record(element, "Add the missing header rule to the matcher.");
+            } else if (!missing.getText(sf).includes(EDGE_HEADER)) {
+              if (ts.isPropertyAssignment(missing) && ts.isArrayLiteralExpression(missing.initializer)) {
+                edits.push(insertArrayElement(sf, missing.initializer, `{ type: "header", key: "${EDGE_HEADER}" }`));
+                record(missing, "Add the edge origin header to the missing rules of the matcher.");
+              } else {
+                manual.push(`${rel}:${lineOf(missing)}: add { type: "header", key: "${EDGE_HEADER}" } to the missing rules.`);
+              }
+            }
+          } else {
+            manual.push(`${rel}:${lineOf(element)}: add missing: ${MISSING_RULE} to this matcher.`);
+          }
+        }
+      } else {
+        manual.push(`${rel}:${lineOf(matcher)}: the matcher is not a literal. Add missing: ${MISSING_RULE} to each matcher.`);
+      }
+    }
+
+    const runtime = findProperty(config, "runtime");
+    if (!runtime) {
+      edits.push(insertProperty(sf, config, 'runtime: "experimental-edge"'));
+      record(config, 'Add runtime: "experimental-edge". The edge middleware needs the edge runtime.');
+    } else if (!/["'`](experimental-)?edge["'`]/.test(runtime.getText(sf))) {
+      manual.push(`${rel}:${lineOf(runtime)}: set runtime to "experimental-edge". The edge middleware needs the edge runtime (vercel/next.js#82344).`);
+    }
+  }
+
+  return { text: applyEdits(text, mergeInsertions(edits)), changes, manual };
+}
+
+function findExportedConst(sf, name) {
+  for (const statement of sf.statements) {
+    if (!ts.isVariableStatement(statement)) continue;
+    if (!statement.modifiers?.some((m) => m.kind === ts.SyntaxKind.ExportKeyword)) continue;
+    for (const declaration of statement.declarationList.declarations) {
+      if (ts.isIdentifier(declaration.name) && declaration.name.text === name) {
+        let value = declaration.initializer;
+        while (value && (ts.isSatisfiesExpression?.(value) || ts.isAsExpression(value) || ts.isParenthesizedExpression(value))) value = value.expression;
+        return value;
+      }
+    }
+  }
+  return undefined;
+}
+
+function findProperty(object, name) {
+  return object.properties.find((p) => p.name && (ts.isIdentifier(p.name) || ts.isStringLiteral(p.name)) && p.name.text === name);
+}
+
+// Route files: createUniformStaticParams and createPreviewPOSTRouteHandler
+
+export function migrateRouteFile(root, file, text) {
+  const sf = parse(file, text);
+  const rel = path.relative(root, file);
+  const lineOf = (node) => sf.getLineAndCharacterOfPosition(node.getStart(sf)).line + 1;
+  const edits = [];
+  const changes = [];
+  const manual = [];
+  const locals = sdkImports(sf);
+  const isCall = (node, imported) =>
+    ts.isCallExpression(node) && ts.isIdentifier(node.expression) && locals.get(node.expression.text)?.imported === imported;
+  let needsExpireImport = false;
+  const hasExpireImport = [...locals.values()].some((info) => info.imported === "expireVercelRuntimeCacheTags");
+
+  const visit = (node) => {
+    if (isCall(node, "createUniformStaticParams")) {
+      const options = node.arguments[0];
+      if (options && ts.isObjectLiteralExpression(options)) {
+        const edgeMode = findProperty(options, "edgeMode");
+        if (!edgeMode) {
+          edits.push(insertProperty(sf, options, "edgeMode: [true, false]"));
+          changes.push({ file: rel, line: lineOf(node), rule: "edge-static-params", description: "Add edgeMode: [true, false], so that the build prebuilds both edge mode values." });
+        } else if (!/\btrue\b/.test(edgeMode.getText(sf))) {
+          manual.push(`${rel}:${lineOf(edgeMode)}: add true to the edgeMode option of createUniformStaticParams.`);
+        }
+      } else {
+        manual.push(`${rel}:${lineOf(node)}: add edgeMode: [true, false] to the options of createUniformStaticParams.`);
+      }
+    }
+
+    if (isCall(node, "createPreviewPOSTRouteHandler")) {
+      const options = node.arguments[0];
+      if (!options) {
+        const open = sf.getFullText().indexOf("(", node.expression.end);
+        edits.push({ start: open + 1, end: node.arguments.end, text: "{ onRevalidateTags: expireVercelRuntimeCacheTags }" });
+        changes.push({ file: rel, line: lineOf(node), rule: "edge-preview-route", description: "Expire the Vercel runtime cache when content is published: onRevalidateTags: expireVercelRuntimeCacheTags." });
+        needsExpireImport = true;
+      } else if (ts.isObjectLiteralExpression(options)) {
+        const existing = findProperty(options, "onRevalidateTags");
+        if (!existing) {
+          edits.push(insertProperty(sf, options, "onRevalidateTags: expireVercelRuntimeCacheTags"));
+          changes.push({ file: rel, line: lineOf(node), rule: "edge-preview-route", description: "Expire the Vercel runtime cache when content is published: onRevalidateTags: expireVercelRuntimeCacheTags." });
+          needsExpireImport = true;
+        } else if (!existing.getText(sf).includes("expireVercelRuntimeCacheTags")) {
+          manual.push(`${rel}:${lineOf(existing)}: you have your own onRevalidateTags. Also call expireVercelRuntimeCacheTags(tags) from ${VERCEL} in it.`);
+        }
+      } else {
+        manual.push(`${rel}:${lineOf(node)}: add onRevalidateTags: expireVercelRuntimeCacheTags to the options of createPreviewPOSTRouteHandler.`);
+      }
+    }
+    ts.forEachChild(node, visit);
+  };
+  visit(sf);
+
+  if (needsExpireImport && !hasExpireImport) edits.push(...addNamedImport(sf, "expireVercelRuntimeCacheTags", VERCEL));
+  return { text: applyEdits(text, mergeInsertions(edits)), changes, manual };
+}
+
+// Text edits
+
+/** Inserts `property` as the last property of `object`, in the style of the object. */
+function insertProperty(sf, object, property) {
+  const text = sf.getFullText();
+  const props = object.properties;
+  if (!props.length) {
+    return { start: object.getStart(sf) + 1, end: object.end - 1, text: ` ${property} ` };
+  }
+  const last = props[props.length - 1];
+  let at = last.end;
+  const comma = /^\s*,/.exec(text.slice(at));
+  const trailingComma = Boolean(comma);
+  if (comma) at += comma[0].length;
+  const multiline = text.slice(object.getStart(sf), object.end).includes("\n");
+  if (!multiline) return { start: at, end: at, text: `${trailingComma ? "" : ","} ${property}${trailingComma ? "," : ""}` };
+  const indent = /([ \t]*)$/.exec(text.slice(0, last.getStart(sf)))[1];
+  return { start: at, end: at, text: `${trailingComma ? "" : ","}\n${indent}${property}${trailingComma ? "," : ""}` };
+}
+
+function insertArrayElement(sf, array, element) {
+  const fake = { properties: array.elements, getStart: (s) => array.getStart(s), end: array.end };
+  return insertProperty(sf, fake, element);
+}
+
+/** Replaces the import of `info` with `name` from `module`. */
+function replaceImport(sf, info, name, module) {
+  const statement = info.statement;
+  const named = statement.importClause.namedBindings;
+  const quote = statement.moduleSpecifier.getText(sf)[0];
+  const line = `import { ${name} } from ${quote}${module}${quote};`;
+  if (named.elements.length === 1 && !statement.importClause.name) {
+    return [{ start: statement.getStart(sf), end: statement.end, text: line }];
+  }
+  // Remove the specifier, and add the new import after the statement.
+  const elements = [...named.elements];
+  const i = elements.indexOf(info.element);
+  const removal =
+    i < elements.length - 1
+      ? { start: info.element.getStart(sf), end: elements[i + 1].getStart(sf), text: "" }
+      : { start: elements[i - 1].end, end: info.element.end, text: "" };
+  return [removal, { start: statement.end, end: statement.end, text: `\n${line}` }];
+}
+
+/** Adds `import { name } from module`, or adds `name` to an existing import from the module. */
+function addNamedImport(sf, name, module) {
+  const imports = sf.statements.filter(ts.isImportDeclaration);
+  const existing = imports.find((s) => ts.isStringLiteral(s.moduleSpecifier) && s.moduleSpecifier.text === module && s.importClause?.namedBindings && ts.isNamedImports(s.importClause.namedBindings));
+  if (existing) {
+    const elements = existing.importClause.namedBindings.elements;
+    const last = elements[elements.length - 1];
+    return [{ start: last.end, end: last.end, text: `, ${name}` }];
+  }
+  const quote = imports[0]?.moduleSpecifier.getText(sf)[0] ?? '"';
+  const line = `import { ${name} } from ${quote}${module}${quote};`;
+  const after = imports[imports.length - 1];
+  if (after) return [{ start: after.end, end: after.end, text: `\n${line}` }];
+  return [{ start: 0, end: 0, text: `${line}\n` }];
+}
+
+/** Joins insertions at the same position, so that applyEdits accepts them. */
+function mergeInsertions(edits) {
+  const out = [];
+  for (const edit of [...edits].sort((a, b) => a.start - b.start || a.end - b.end)) {
+    const previous = out[out.length - 1];
+    if (previous && previous.start === edit.start && previous.end === previous.start && edit.end === edit.start) {
+      previous.text += edit.text;
+    } else out.push({ ...edit });
+  }
+  return out;
+}

package/src/interactive.js

@@ -0,0 +1,111 @@
+// The interactive mode: a guide through the check, phase 1 (the SDK upgrade) and phase 2 (edge mode).
+
+import { spawnSync } from "node:child_process";
+import fs from "node:fs";
+import path from "node:path";
+import { createInterface } from "node:readline/promises";
+
+import { PROVIDERS } from "./edge/index.js";
+import { formatText, TARGET_VERSION, verdict } from "./report.js";
+import { colors, executeMigration, NAME, projectStatus } from "./session.js";
+
+export async function runInteractive({ root, color, uniformData }) {
+  const c = colors(color);
+  const rl = createInterface({ input: process.stdin, output: process.stdout });
+  const ask = async (question, defaultYes = false) => {
+    const answer = (await rl.question(`${c("36", "?")} ${question} ${c("2", defaultYes ? "[Y/n]" : "[y/N]")} `)).trim();
+    return answer ? /^y(es)?$/i.test(answer) : defaultYes;
+  };
+  const choose = async (question, options) => {
+    console.log(`${c("36", "?")} ${c("1", question)}`);
+    options.forEach((option, i) => {
+      const label = option.disabled ? c("2", `${option.label}  (${option.hint})`) : `${option.label}${option.hint ? c("2", `  ${option.hint}`) : ""}`;
+      console.log(`  ${c("36", String(i + 1))}) ${label}`);
+    });
+    for (;;) {
+      const answer = Number((await rl.question(`  Select 1-${options.length}: `)).trim());
+      const option = options[answer - 1];
+      if (option) {
+        console.log("");
+        return option;
+      }
+    }
+  };
+
+  try {
+    for (;;) {
+      const status = projectStatus(root, { uniformData });
+      printHeader(root, status, c);
+
+      const phase1Hint = status.phase1Pending ? `${status.phase1Pending} automatic change(s) to do` : "done";
+      const phase2Hint = status.edgeMode ? `edge mode is on (${status.edgeMode})` : "lite mode now";
+      const action = await choose("What do you want to do?", [
+        { value: "check", label: "Check compatibility", hint: "a full report, no changes" },
+        { value: "phase1", label: "Phase 1: upgrade the SDK", hint: phase1Hint },
+        { value: "phase2", label: "Phase 2: turn on edge mode", hint: phase2Hint },
+        { value: "exit", label: "Exit" },
+      ]);
+
+      if (action.value === "exit") return 0;
+
+      if (action.value === "check") {
+        console.log(formatText(status.scan, verdict(status.scan.findings), { color }));
+        console.log("");
+        await rl.question(c("2", "Press Enter to go back to the menu. "));
+        continue;
+      }
+
+      let edge;
+      if (action.value === "phase2") {
+        const host = await choose("Which host serves your app?", [
+          ...Object.entries(PROVIDERS).map(([key, provider]) => ({
+            value: key,
+            label: provider.name,
+            hint: provider.available ? provider.summary : "coming soon",
+            disabled: !provider.available,
+          })),
+          { value: "back", label: "Back" },
+        ]);
+        if (host.value === "back") continue;
+        if (host.disabled) {
+          console.log(`${PROVIDERS[host.value].name} is not in this CLI yet. To set up edge mode by hand, follow the docs:`);
+          console.log(c("36", `  ${PROVIDERS[host.value].docs}`));
+          console.log("");
+          continue;
+        }
+        edge = host.value;
+        if (status.phase1Pending) {
+          console.log(c("33", `Phase 1 is not done. The plan includes its ${status.phase1Pending} change(s) too.`));
+          console.log("");
+        }
+      }
+
+      const code = await executeMigration({ root, edge, color, uniformData, ask, interactive: true, diff: "ask" });
+      if (code !== 2 && fs.existsSync(path.join(root, "package.json"))) await offerInstall(root, ask, c);
+      await rl.question(c("2", "Press Enter to go back to the menu. "));
+    }
+  } finally {
+    rl.close();
+  }
+}
+
+function printHeader(root, status, c) {
+  const { scan } = status;
+  const result = verdict(scan.findings);
+  console.log("");
+  console.log(c("1", "Uniform Next.js App Router SDK upgrade"));
+  console.log(`  Project   ${scan.project.name ?? path.basename(root)} ${c("2", `(${root})`)}`);
+  console.log(`  SDK       ${status.sdkVersion}${status.atTarget ? c("32", "  (target version)") : c("2", `  → ${TARGET_VERSION}`)}`);
+  console.log(`  Check     ${c(result.safe ? "32" : "31", result.label)} ${c("2", `(${result.errors} error(s), ${result.warnings} warning(s))`)}`);
+  console.log(`  Mode      ${status.edgeMode ? c("32", `edge mode (${status.edgeMode})`) : "lite mode: the browser chooses the variants after hydration"}`);
+  console.log("");
+}
+
+async function offerInstall(root, ask, c) {
+  const manager = fs.existsSync(path.join(root, "pnpm-lock.yaml")) ? "pnpm" : fs.existsSync(path.join(root, "yarn.lock")) ? "yarn" : "npm";
+  if (!(await ask(`Run "${manager} install" now?`, false))) return;
+  const result = spawnSync(manager, ["install"], { cwd: root, stdio: "inherit", shell: process.platform === "win32" });
+  console.log(result.status === 0 ? c("32", "Install done.") : c("31", `${manager} install failed. Run it yourself, and read the error.`));
+  console.log(c("2", `Then run: ${NAME} check`));
+  console.log("");
+}

package/src/json-text.js

@@ -0,0 +1,95 @@
+// Small edits to JSON text that keep the formatting of all other lines.
+
+/** Returns [start, end] of the object value of a top-level key, from "{" to "}" inclusive. */
+export function findTopLevelObject(text, key) {
+  let depth = 0;
+  for (let i = 0; i < text.length; i++) {
+    const ch = text[i];
+    if (ch === '"') {
+      const end = endOfString(text, i);
+      if (depth === 1) {
+        const name = JSON.parse(text.slice(i, end + 1));
+        const rest = /^\s*:\s*/.exec(text.slice(end + 1));
+        if (name === key && rest && text[end + 1 + rest[0].length] === "{") {
+          const start = end + 1 + rest[0].length;
+          return [start, matchBrace(text, start)];
+        }
+      }
+      i = end;
+    } else if (ch === "{" || ch === "[") depth++;
+    else if (ch === "}" || ch === "]") depth--;
+  }
+  return undefined;
+}
+
+function endOfString(text, start) {
+  for (let i = start + 1; i < text.length; i++) {
+    if (text[i] === "\\") i++;
+    else if (text[i] === '"') return i;
+  }
+  throw new Error("Unterminated string in JSON");
+}
+
+function matchBrace(text, start) {
+  let depth = 0;
+  for (let i = start; i < text.length; i++) {
+    if (text[i] === '"') i = endOfString(text, i);
+    else if (text[i] === "{" || text[i] === "[") depth++;
+    else if (text[i] === "}" || text[i] === "]") {
+      depth--;
+      if (depth === 0) return i;
+    }
+  }
+  throw new Error("Unbalanced JSON");
+}
+
+const quote = (s) => JSON.stringify(s);
+const escapeRe = (s) => s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+
+/** Changes the value of `name` inside the top-level object `block`. Returns the new text, or undefined. */
+export function setValueInBlock(text, block, name, value) {
+  const range = findTopLevelObject(text, block);
+  if (!range) return undefined;
+  const inner = text.slice(range[0], range[1] + 1);
+  const re = new RegExp(`(${escapeRe(quote(name))}\\s*:\\s*)"(?:[^"\\\\]|\\\\.)*"`);
+  if (!re.test(inner)) return undefined;
+  return text.slice(0, range[0]) + inner.replace(re, `$1${quote(value)}`) + text.slice(range[1] + 1);
+}
+
+/**
+ * Adds `name: value` to the top-level object `block`, in alphabetical order when the keys are in
+ * alphabetical order. Adds the block when it does not exist.
+ */
+export function addToBlock(text, block, name, value) {
+  const eol = text.includes("\r\n") ? "\r\n" : "\n";
+  const unit = /^([ \t]+)"/m.exec(text)?.[1] ?? "  ";
+  const range = findTopLevelObject(text, block);
+
+  if (!range) {
+    // Add the block before the last "}" of the file.
+    const close = text.lastIndexOf("}");
+    const before = text.slice(0, close).replace(/\s*$/, "");
+    const entry = `${unit}${quote(block)}: {${eol}${unit}${unit}${quote(name)}: ${quote(value)}${eol}${unit}}`;
+    return `${before},${eol}${entry}${eol}${text.slice(close)}`;
+  }
+
+  const [start, end] = range;
+  const body = text.slice(start + 1, end);
+  const keys = [...body.matchAll(/"((?:[^"\\]|\\.)*)"\s*:/g)].map((m) => ({ name: JSON.parse(`"${m[1]}"`), index: start + 1 + m.index }));
+  if (!keys.length) return text.slice(0, start) + `{ ${quote(name)}: ${quote(value)} }` + text.slice(end + 1);
+
+  const indent = /([ \t]*)$/.exec(text.slice(0, keys[0].index))[1];
+  const multiline = body.includes("\n");
+  const sorted = keys.every((key, i) => i === 0 || keys[i - 1].name.localeCompare(key.name) <= 0);
+  const next = sorted ? keys.find((key) => key.name.localeCompare(name) > 0) : undefined;
+
+  if (next) {
+    const entry = multiline ? `${quote(name)}: ${quote(value)},${eol}${indent}` : `${quote(name)}: ${quote(value)}, `;
+    return text.slice(0, next.index) + entry + text.slice(next.index);
+  }
+  // Add after the last value.
+  const lastValueEnd = start + 1 + body.replace(/\s*$/, "").length;
+  const hasComma = text[lastValueEnd - 1] === ",";
+  const entry = multiline ? `${hasComma ? "" : ","}${eol}${indent}${quote(name)}: ${quote(value)}` : `${hasComma ? "" : ","} ${quote(name)}: ${quote(value)}`;
+  return text.slice(0, lastValueEnd) + entry + text.slice(lastValueEnd);
+}