u1s1-cli 1.14.5 → 1.15.0

package/scripts/pi-upgrade.mjs

@@ -0,0 +1,829 @@
+#!/usr/bin/env node
+/**
+ * Upgrade the embedded Pi (@earendil-works/pi-*) to a given version and regenerate both patch tracks.
+ *
+ * One command for steps 1–4 of docs/pi-patch-inventory-2026-11-13.md §3.5; step 5 (rules that no
+ * longer match) is reported, never rewritten:
+ *   1. packages/cli/package.json: every @earendil-works/pi-* to the new version, plus pi packages the
+ *      new version newly depends on; undici follows pi-coding-agent's exact pin
+ *   2. pnpm-workspace.yaml: minimumReleaseAgeExclude (pi entries) and patchedDependencies
+ *   3. patches/@earendil-works__pi-{coding-agent,tui}@<ver>.patch: regenerated from the pristine npm
+ *      tarballs + scripts/patch-pi.js (so the two tracks stay byte-identical), old files removed
+ *   4. packages/cli/package-lock.json (npm --package-lock-only in a scratch copy) and pnpm-lock.yaml
+ *      (pnpm install)
+ * and writes a report (report.json / report.md / report.public.md): per-rule status against the new
+ * pristine sources, UI strings the new version added that no rule covers, and the Breaking sections of
+ * the upstream CHANGELOGs shipped in the tarballs. report.public.md is the one meant for PR / issue
+ * bodies: everything quoted from upstream sits in code blocks (no @mentions, no cross-references) and
+ * third-party service names and price words are masked.
+ *
+ * Usage:
+ *   node packages/cli/scripts/pi-upgrade.mjs [--version <x.y.z>|latest] [--dry-run] [--force]
+ *        [--resolve-only] [--skip-install] [--work-dir <dir>] [--report-dir <dir>] [--pnpm <cmd>] [--json]
+ *
+ *   --version       target version; default "latest" = newest stable release at or below the npm
+ *                   `latest` tag that is at least minimumReleaseAge (pnpm-workspace.yaml) old
+ *   --resolve-only  print the version decision as JSON and exit; touches nothing, downloads no tarball
+ *   --dry-run       download, patch and report, but leave the working tree untouched
+ *   --force         write the upgrade even when some rule no longer matches (still exits 1)
+ *   --skip-install  do not run pnpm install (pnpm-lock.yaml is then left stale)
+ *   --pnpm          pnpm command to run (default "pnpm"; locally e.g. the npx-cached pnpm 11 binary)
+ *
+ * Network: npm registry only (npm view / npm pack / npm install --package-lock-only, pnpm install).
+ * Exit codes: 0 done (or nothing to do), 1 some rule missing / wrong count (report written), 2 error.
+ */
+
+import { spawnSync } from "node:child_process";
+import { closeSync, cpSync, existsSync, mkdirSync, mkdtempSync, openSync, readFileSync, readdirSync, rmSync, unlinkSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+
+export const PI_SCOPE = "@earendil-works/";
+export const PI_PREFIX = `${PI_SCOPE}pi-`;
+export const CODING_AGENT = `${PI_SCOPE}pi-coding-agent`;
+export const TUI = `${PI_SCOPE}pi-tui`;
+/** Packages that carry a pnpm patch (patches/@earendil-works__<name>@<ver>.patch). */
+export const PATCHED = [CODING_AGENT, TUI];
+/** Not a rule target: its descriptions are translated by u1s1's in-process extension (src/pi-ui-text.ts). */
+const SLASH_COMMANDS_FILE = "dist/core/slash-commands.js";
+
+// ---------------------------------------------------------------------------
+// versions
+// ---------------------------------------------------------------------------
+
+const STABLE = /^(\d+)\.(\d+)\.(\d+)$/;
+
+export function compareVersions(a, b) {
+  const pa = a.match(STABLE);
+  const pb = b.match(STABLE);
+  if (!pa || !pb) throw new Error(`not a stable x.y.z version: ${!pa ? a : b}`);
+  for (let i = 1; i <= 3; i++) {
+    const d = Number(pa[i]) - Number(pb[i]);
+    if (d !== 0) return Math.sign(d);
+  }
+  return 0;
+}
+
+/** minimumReleaseAge (minutes) from pnpm-workspace.yaml text; 0 when not set. */
+export function readMinimumReleaseAge(workspaceYaml) {
+  const m = workspaceYaml.match(/^minimumReleaseAge:\s*(\d+)\s*$/m);
+  return m ? Number(m[1]) : 0;
+}
+
+/**
+ * Pick the version to upgrade to.
+ * meta: { versions: string[], time: Record<version, ISO>, distTags: Record<tag, version> }
+ * requested: "latest" or an explicit x.y.z. Explicit versions are taken as asked (but flagged when young).
+ */
+export function selectVersion({ meta, current, requested = "latest", now = Date.now(), minAgeMinutes = 0 }) {
+  const ageOf = (v) => (meta.time?.[v] ? Math.floor((now - Date.parse(meta.time[v])) / 60_000) : undefined);
+  if (requested !== "latest") {
+    if (!STABLE.test(requested)) throw new Error(`--version must be x.y.z or "latest", got ${requested}`);
+    if (!meta.versions.includes(requested)) throw new Error(`${requested} is not published on npm`);
+    const ageMinutes = ageOf(requested);
+    return {
+      current,
+      version: requested,
+      publishedAt: meta.time?.[requested],
+      ageMinutes,
+      young: ageMinutes === undefined || ageMinutes < minAgeMinutes,
+      skippedYoung: [],
+      upToDate: requested === current,
+    };
+  }
+  const latest = meta.distTags?.latest;
+  if (!latest || !STABLE.test(latest)) throw new Error(`npm has no stable "latest" tag (${latest})`);
+  const stable = meta.versions.filter((v) => STABLE.test(v) && compareVersions(v, latest) <= 0);
+  const oldEnough = (v) => {
+    const age = ageOf(v);
+    return age !== undefined && age >= minAgeMinutes;
+  };
+  const eligible = stable.filter(oldEnough).sort(compareVersions);
+  const version = eligible.at(-1);
+  const skippedYoung = stable.filter((v) => !oldEnough(v) && (!version || compareVersions(v, version) > 0)).sort(compareVersions);
+  return {
+    current,
+    version,
+    publishedAt: version ? meta.time[version] : undefined,
+    ageMinutes: version ? ageOf(version) : undefined,
+    young: false,
+    skippedYoung,
+    upToDate: !version || (STABLE.test(current) && compareVersions(version, current) <= 0),
+  };
+}
+
+/**
+ * Exact versions of every pi package the upgrade needs: the pi packages already pinned plus every
+ * @earendil-works/* the new versions depend on, transitively. Ranges (1.2.0 used ^1.2.0) resolve to the
+ * target version; exact upstream pins win. fetchDeps(name, version) → dependencies object (may be async).
+ */
+export async function resolvePiClosure({ roots, target, fetchDeps }) {
+  const versions = {};
+  const queue = roots.map((name) => [name, target]);
+  while (queue.length) {
+    const [name, version] = queue.shift();
+    if (versions[name] === version) continue;
+    if (versions[name]) throw new Error(`${name} is wanted at both ${versions[name]} and ${version}`);
+    versions[name] = version;
+    const deps = (await fetchDeps(name, version)) ?? {};
+    for (const [dep, spec] of Object.entries(deps)) {
+      if (!dep.startsWith(PI_SCOPE)) continue;
+      queue.push([dep, STABLE.test(spec) ? spec : target]);
+    }
+  }
+  return Object.fromEntries(Object.entries(versions).sort(([a], [b]) => a.localeCompare(b)));
+}
+
+// ---------------------------------------------------------------------------
+// file rewrites (pure: text/object in, text/object out)
+// ---------------------------------------------------------------------------
+
+/** Current pi pins from package.json dependencies. */
+export function piPins(pkg) {
+  return Object.fromEntries(Object.entries(pkg.dependencies ?? {}).filter(([name]) => name.startsWith(PI_PREFIX)));
+}
+
+/**
+ * New package.json object: pi packages set to `closure`, new ones added, undici synced; dependencies
+ * stay sorted by name. Returns { pkg, changes: [{ name, from, to }] }.
+ */
+export function planPackageJson(pkg, closure, undici) {
+  const deps = { ...pkg.dependencies };
+  const changes = [];
+  const set = (name, to) => {
+    if (deps[name] === to) return;
+    changes.push({ name, from: deps[name] ?? null, to });
+    deps[name] = to;
+  };
+  for (const [name, version] of Object.entries(closure)) set(name, version);
+  if (undici) set("undici", undici);
+  const sorted = Object.fromEntries(Object.entries(deps).sort(([a], [b]) => a.localeCompare(b)));
+  return { pkg: { ...pkg, dependencies: sorted }, changes };
+}
+
+export const patchFileName = (name, version) => `${name.replace("/", "__")}@${version}.patch`;
+
+/**
+ * Rewrite pnpm-workspace.yaml line by line (keeps comments and every unrelated entry):
+ *  - minimumReleaseAgeExclude: drop every `@earendil-works/pi-*@x` item; add `exclude` (name@version
+ *    list, only packages still younger than minimumReleaseAge) where the first pi item used to be
+ *  - patchedDependencies: `@earendil-works/<pkg>@<old>` → `<new>` with the new patch file name; entries
+ *    whose package is in `dropPatched` (empty generated patch) are removed
+ */
+export function planWorkspaceYaml(text, { versions, exclude = [], dropPatched = [] }) {
+  const lines = text.split("\n");
+  const out = [];
+  let block = null;
+  let insertAt = -1;
+  const piExclude = /^\s+-\s+'?@earendil-works\/pi-[\w-]+@[^'\s]+'?\s*$/;
+  const patchedEntry = /^(\s+)'(@earendil-works\/pi-[\w-]+)@[^']+':\s*patches\/\S+\s*$/;
+  for (const line of lines) {
+    const top = line.match(/^([A-Za-z][\w-]*):/);
+    if (top) {
+      if (block === "minimumReleaseAgeExclude" && insertAt < 0) insertAt = out.length;
+      block = top[1];
+    }
+    if (block === "minimumReleaseAgeExclude" && piExclude.test(line)) {
+      if (insertAt < 0) insertAt = out.length;
+      continue;
+    }
+    const p = block === "patchedDependencies" ? line.match(patchedEntry) : null;
+    if (p) {
+      const [, indent, name] = p;
+      if (dropPatched.includes(name)) continue;
+      const version = versions[name];
+      if (!version) throw new Error(`patchedDependencies has ${name} but the upgrade has no version for it`);
+      out.push(`${indent}'${name}@${version}': patches/${patchFileName(name, version)}`);
+      continue;
+    }
+    out.push(line);
+  }
+  if (exclude.length) {
+    if (insertAt < 0) throw new Error("pnpm-workspace.yaml has no minimumReleaseAgeExclude list to add to");
+    // the list may have ended in blank lines before the next key; keep the new items inside the list
+    while (insertAt > 0 && out[insertAt - 1].trim() === "") insertAt--;
+    out.splice(insertAt, 0, ...[...exclude].sort().map((spec) => `  - '${spec}'`));
+  }
+  return out.join("\n");
+}
+
+// ---------------------------------------------------------------------------
+// report inputs
+// ---------------------------------------------------------------------------
+
+/**
+ * String and template literals of a JS source, skipping comments and regex literals (an apostrophe in a
+ * comment would otherwise throw a regex-only scan out of step). Template expressions become "…"; templates
+ * nested inside them are returned separately. Good enough for tsc output; not a full JS lexer.
+ */
+export function jsStringLiterals(src) {
+  const out = [];
+  let i = 0;
+  let prev = ""; // last significant char, to tell a regex literal from a division
+  const regexAfter = /[(,=:[!&|?{};+\-*%<>~^]/;
+  const readQuoted = (q) => {
+    let s = "";
+    for (i++; i < src.length && src[i] !== q && src[i] !== "\n"; i++) {
+      if (src[i] === "\\") s += src[i++];
+      s += src[i];
+    }
+    i++;
+    return s;
+  };
+  // returns the template text with expressions as "…"; i ends after the closing backtick
+  const readTemplate = () => {
+    let s = "";
+    for (i++; i < src.length && src[i] !== "`"; i++) {
+      if (src[i] === "\\") s += src[i++] + src[i];
+      else if (src[i] === "$" && src[i + 1] === "{") {
+        i += 2;
+        scanCode(true);
+        i--; // scanCode stopped just past "}"; the loop's i++ must not skip the next char
+        s += "…";
+      } else s += src[i];
+    }
+    i++;
+    return s;
+  };
+  // scans code until the matching "}" (inside ${…}) or the end; pushes literals it meets
+  const scanCode = (inExpr) => {
+    let depth = 0;
+    while (i < src.length) {
+      const c = src[i];
+      if (c === "/" && src[i + 1] === "/") {
+        while (i < src.length && src[i] !== "\n") i++;
+      } else if (c === "/" && src[i + 1] === "*") {
+        const end = src.indexOf("*/", i + 2);
+        i = end < 0 ? src.length : end + 2;
+      } else if (c === '"' || c === "'") {
+        out.push(readQuoted(c));
+        prev = "a";
+      } else if (c === "`") {
+        out.push(readTemplate());
+        prev = "a";
+      } else if (c === "/" && (prev === "" || regexAfter.test(prev))) {
+        let inClass = false;
+        for (i++; i < src.length && src[i] !== "\n"; i++) {
+          if (src[i] === "\\") i++;
+          else if (src[i] === "[") inClass = true;
+          else if (src[i] === "]") inClass = false;
+          else if (src[i] === "/" && !inClass) break;
+        }
+        i++;
+        prev = "a";
+      } else if (/[A-Za-z_$]/.test(c)) {
+        const word = src.slice(i).match(/^[\w$]+/)[0];
+        i += word.length;
+        prev = /^(?:return|typeof|case|in|of|else|void|yield|await|delete|new|throw)$/.test(word) ? "(" : "a";
+      } else {
+        if (c === "{") depth++;
+        if (c === "}") {
+          if (inExpr && depth === 0) {
+            i++;
+            return;
+          }
+          depth--;
+        }
+        if (!/\s/.test(c)) prev = /[\w$)\]]/.test(c) ? "a" : c;
+        i++;
+      }
+    }
+  };
+  scanCode(false);
+  return out;
+}
+
+/** Whether a (normalized) string literal reads like user-facing English rather than code. */
+export function looksLikeUiText(s) {
+  if (s.length < 3 || s.length > 300) return false;
+  if (!/[A-Za-z]{2}/.test(s)) return false;
+  if (/\\x1b|\\u001b|\\u\{|^\s*[-#.]|^\w+:\/\/|\.(?:js|json|ts|md|jsonl|html)\b/.test(s)) return false;
+  if (/^[\w$.:/@-]+$/.test(s)) return /^[A-Z][a-z]+[.!?…:]?$/.test(s); // one word: only "Continue", "Fork"…
+  if (/[{};=]|=>|\(\)/.test(s)) return false;
+  return /[A-Za-z]{2,}\s+\S/.test(s) || /^[A-Z][a-z]+[.!?…:]$/.test(s);
+}
+
+/** User-facing string literals of one JS source; template expressions collapse to "…". */
+export function extractUiStrings(source) {
+  const found = new Set();
+  for (const literal of jsStringLiterals(source)) {
+    const s = literal.trim();
+    if (!s.includes("\n") && looksLikeUiText(s)) found.add(s);
+  }
+  return found;
+}
+
+/**
+ * UI strings present in the new files but not in the old ones (same files, any position), minus those
+ * some rule's `from` text already quotes. files: { [relPath]: { old?: string, new?: string } }.
+ */
+export function newUiStrings(files, ruleFroms = []) {
+  const out = [];
+  for (const [file, { old: before = "", new: after = "" }] of Object.entries(files)) {
+    const oldSet = extractUiStrings(before);
+    for (const s of extractUiStrings(after)) {
+      if (oldSet.has(s)) continue;
+      const needle = s.split("…")[0];
+      if (needle.length >= 3 && ruleFroms.some((from) => from.includes(needle))) continue;
+      out.push({ file, text: s });
+    }
+  }
+  return out;
+}
+
+const unquote = (lit) => lit.slice(1, -1).replace(/\$\{[^}]*\}/g, "…").replace(/\\(.)/g, "$1");
+const QUOTED = String.raw`("(?:[^"\\]|\\.)*"|` + "`(?:[^`\\\\]|\\\\.)*`)";
+
+/** Split a source on `name: "<cmd>"` and read the named fields of each entry: [{ name, fields }]. */
+function namedEntries(source, fieldNames) {
+  const parts = source.split(/\bname:\s*"([^"]+)"/);
+  const out = [];
+  for (let i = 1; i < parts.length; i += 2) {
+    const body = parts[i + 1];
+    const fields = {};
+    for (const f of fieldNames) {
+      const m = body.match(new RegExp(`\\b${f}:\\s*${QUOTED}`));
+      if (m) fields[f] = unquote(m[1]);
+    }
+    out.push({ name: parts[i], fields });
+  }
+  return out;
+}
+
+/** BUILTIN_SLASH_COMMANDS of Pi's dist/core/slash-commands.js: [{ name, description, argumentHint? }]. */
+export function parseSlashCommands(js) {
+  const block = js.match(/BUILTIN_SLASH_COMMANDS\s*=\s*\[([\s\S]*?)\n\];/);
+  if (!block) return null;
+  return namedEntries(block[1], ["description", "argumentHint"]).map(({ name, fields }) => ({ name, ...fields }));
+}
+
+/** BUILTIN_COMMAND_TEXT of src/pi-ui-text.ts, as the same shape (upstream → description). */
+export function parseUiTextTable(ts) {
+  const block = ts.match(/BUILTIN_COMMAND_TEXT[^=]*=\s*\[([\s\S]*?)\n\];/);
+  if (!block) return null;
+  return namedEntries(block[1], ["upstream", "argumentHint"]).map(({ name, fields }) => ({
+    name,
+    description: fields.upstream,
+    ...(fields.argumentHint !== undefined && { argumentHint: fields.argumentHint }),
+  }));
+}
+
+/**
+ * Where u1s1's slash-command text table (translated by the in-process extension) no longer matches the
+ * new Pi: [{ name, kind: added|removed|changed|order, ours?, upstream? }]. Same check as
+ * test/pi-ui-text.test.ts, done before install so the report can name it.
+ */
+export function slashCommandDrift(ours, upstream) {
+  const key = (c) => `${c.description ?? ""}\u0000${c.argumentHint ?? ""}`;
+  const mine = new Map(ours.map((c) => [c.name, c]));
+  const theirs = new Map(upstream.map((c) => [c.name, c]));
+  const drift = [];
+  for (const c of upstream) {
+    const m = mine.get(c.name);
+    if (!m) drift.push({ name: c.name, kind: "added", upstream: c.description });
+    else if (key(m) !== key(c)) drift.push({ name: c.name, kind: "changed", ours: m.description, upstream: c.description });
+  }
+  for (const c of ours) if (!theirs.has(c.name)) drift.push({ name: c.name, kind: "removed", ours: c.description });
+  if (!drift.length && ours.map((c) => c.name).join() !== upstream.map((c) => c.name).join()) {
+    drift.push({ name: "*", kind: "order" });
+  }
+  return drift;
+}
+
+/**
+ * Breaking-change bullets of every CHANGELOG version in (from, to].
+ * Returns [{ version, items: string[] }] newest first, as the CHANGELOG lists them.
+ */
+export function extractBreaking(changelog, from, to) {
+  const out = [];
+  let version = null;
+  let inBreaking = false;
+  let items = null;
+  for (const line of changelog.split("\n")) {
+    const v = line.match(/^##\s+\[?(\d+\.\d+\.\d+)\]?/);
+    if (v) {
+      version = v[1];
+      inBreaking = false;
+      continue;
+    }
+    if (/^###\s/.test(line)) {
+      inBreaking = /breaking/i.test(line);
+      if (inBreaking && version && compareVersions(version, from) > 0 && compareVersions(version, to) <= 0) {
+        items = out.find((e) => e.version === version)?.items;
+        if (!items) {
+          items = [];
+          out.push({ version, items });
+        }
+      } else inBreaking = false;
+      continue;
+    }
+    if (!inBreaking || !items) continue;
+    if (/^\s*[-*]\s+/.test(line)) items.push(line.replace(/^\s*[-*]\s+/, "").trim());
+    else if (line.trim() && items.length) items[items.length - 1] += ` ${line.trim()}`;
+  }
+  return out.filter((e) => e.items.length);
+}
+
+// ---------------------------------------------------------------------------
+// report
+// ---------------------------------------------------------------------------
+
+const STATUS_LABEL = { hit: "命中", applied: "已含(上游已是目标文本)", count: "命中次数不对", missing: "失配" };
+
+/** pi-patch-report status → hit | applied | count | missing */
+export function ruleState(status) {
+  if (status === "clean") return "hit";
+  if (status.startsWith("applied")) return "applied";
+  if (status === "count") return "count";
+  return "missing";
+}
+
+/**
+ * Third-party service names and price words never go into PR / issue text (they are public). This is a
+ * mask, not a parser: anything matching is replaced, the rest of the line is kept.
+ */
+const THIRD_PARTY =
+  /\b(?:deepseek|wokey|open\s?ai|anthropic|claude(?:\s+code)?|chat\s?gpt|codex|gpt-?[\w.]*|gemini|google|vertex(?:\s+ai)?|bedrock|azure|aws|amazon|openrouter|litellm|vllm|ollama|mistral|groq|xai|grok|kimi|moonshot|qwen|zhipu|glm-?[\w.]*|minimax|copilot|microsoft|radius|passin|blockwallets|cloudflare|fireworks|together\s?ai|deepinfra|cerebras|perplexity|cohere|huggingface|nvidia)\b/gi;
+const PRICE = /\b(?:price[sd]?|pricing|costs?|billing|billed|markup|discounts?|cheap(?:er|est)?)\b|[$¥￥€]\s?\d+(?:[.,]\d+)*|加价|成本|定价|价格|售价|折扣|渠道|供应商/gi;
+export function maskPublic(text) {
+  return text.replace(THIRD_PARTY, "[第三方]").replace(PRICE, "[略]");
+}
+
+/** Text inside a fenced block: no mentions, no #refs, no autolinks; also strip markdown links to their text. */
+function fenced(lines) {
+  const body = lines.join("\n").replace(/\[([^\]]*)\]\([^)]*\)/g, "$1").replace(/```/g, "'''");
+  return ["```text", body, "```"];
+}
+
+export function buildReport({ current, target, packages, undici, rules, slashCommands = [], uiStrings, breaking, patches }) {
+  const tally = { hit: 0, applied: 0, count: 0, missing: 0 };
+  const items = rules.map((r) => {
+    const state = ruleState(r.status);
+    tally[state]++;
+    return { id: `${r.table}[${r.index}]`, file: r.file, status: r.status, state, from: r.from };
+  });
+  const problems = items.filter((r) => r.state === "count" || r.state === "missing");
+  return {
+    current,
+    target,
+    ok: problems.length === 0 && slashCommands.length === 0,
+    packages,
+    undici,
+    patches,
+    rules: { total: items.length, ...tally, problems, items },
+    slashCommands,
+    uiStrings,
+    breaking,
+  };
+}
+
+const DRIFT_LABEL = { added: "上游新增", removed: "上游已删", changed: "上游原文变了", order: "顺序变了" };
+
+const MAX_LIST = 150;
+
+/** Markdown report. publicSafe: mask third-party/price words and keep every quote inside code blocks. */
+export function renderMarkdown(report, { publicSafe = false } = {}) {
+  const q = publicSafe ? maskPublic : (s) => s;
+  const r = report.rules;
+  const lines = [];
+  lines.push(`<!-- pi-upgrade version=${report.target} ok=${report.ok} -->`);
+  lines.push(`## Pi ${report.current} → ${report.target}`, "");
+  if (report.ok) lines.push("补丁规则全部命中,斜杠命令文案表与新版一致。", "");
+  if (r.problems.length) lines.push(`**有 ${r.problems.length} 条补丁规则对不上新版本,需要人工改 \`packages/cli/scripts/patch-pi.js\`。**`, "");
+  if (report.slashCommands.length) {
+    lines.push(`**有 ${report.slashCommands.length} 个内置斜杠命令和 \`packages/cli/src/pi-ui-text.ts\` 的文案表对不上,需要人工补表。**`, "");
+  }
+  lines.push("### 依赖版本", "", "| 包 | 旧 | 新 |", "|---|---|---|");
+  for (const c of report.packages) lines.push(`| \`${c.name}\` | ${c.from ?? "(新增)"} | ${c.to} |`);
+  lines.push("");
+  if (report.patches?.length) {
+    lines.push("### 重新生成的 pnpm 补丁", "");
+    for (const p of report.patches) lines.push(`- \`patches/${p.file}\`:${p.empty ? "无改动(不再需要这份补丁)" : `${p.hunks} 个 hunk`}`);
+    lines.push("");
+  }
+  lines.push("### 补丁规则(`patch-pi.js`,对照新版原始文件)", "");
+  lines.push(`共 ${r.total} 条:命中 ${r.hit},已含 ${r.applied},命中次数不对 ${r.count},失配 ${r.missing}。`, "");
+  if (r.problems.length) {
+    lines.push(...fenced(r.problems.map((p) => `${STATUS_LABEL[p.state]}  ${p.id}  ${p.file}  ${q(p.from)}`)), "");
+  }
+  lines.push("### 斜杠命令文案表(`src/pi-ui-text.ts`,由 u1s1 扩展翻译)", "");
+  if (report.slashCommands.length) {
+    const out = report.slashCommands.map((d) =>
+      [`${DRIFT_LABEL[d.kind]}  /${d.name}`, d.ours !== undefined && `    表里:${q(d.ours)}`, d.upstream !== undefined && `    新版:${q(d.upstream)}`]
+        .filter(Boolean)
+        .join("\n"),
+    );
+    lines.push(...fenced(out), "");
+  } else lines.push("一致。", "");
+  lines.push(`### 新版新增、补丁和扩展都没覆盖的界面文字(${report.uiStrings.length} 条)`, "");
+  if (report.uiStrings.length) {
+    lines.push("从补丁目标文件里新出现的英文字面量自动提取,可能有少量误报;中国站会看到这些英文。", "");
+    const shown = report.uiStrings.slice(0, MAX_LIST).map((u) => `${u.file}: ${q(u.text)}`);
+    if (report.uiStrings.length > MAX_LIST) shown.push(`…另有 ${report.uiStrings.length - MAX_LIST} 条,见完整报告`);
+    lines.push(...fenced(shown), "");
+  } else lines.push("无。", "");
+  lines.push("### 上游 CHANGELOG 的 Breaking Changes", "");
+  if (report.breaking.length) {
+    const out = [];
+    for (const b of report.breaking) {
+      out.push(`[${b.package} ${b.version}]`);
+      for (const item of b.items) out.push(`- ${q(item)}`);
+      out.push("");
+    }
+    lines.push(...fenced(out.slice(0, -1)), "");
+  } else lines.push("无。", "");
+  if (!publicSafe && r.items.length) {
+    lines.push("<details><summary>全部规则状态</summary>", "");
+    lines.push(...fenced(r.items.map((i) => `${i.status.padEnd(16)} ${i.id}  ${i.file}`)), "", "</details>", "");
+  }
+  return lines.join("\n");
+}
+
+// ---------------------------------------------------------------------------
+// side effects (npm, git, filesystem)
+// ---------------------------------------------------------------------------
+
+function run(cmd, args, { cwd, env, allowFail = false, input } = {}) {
+  const res = spawnSync(cmd, args, { cwd, env: env ?? process.env, encoding: "utf8", input, maxBuffer: 256 * 1024 * 1024 });
+  if (res.error) throw new Error(`${cmd} ${args.join(" ")}: ${res.error.message}`);
+  if (res.status !== 0 && !allowFail) {
+    throw new Error(`${cmd} ${args.join(" ")} exited ${res.status}\n${(res.stderr || res.stdout || "").trim().slice(-2000)}`);
+  }
+  return res;
+}
+
+const npmJson = (args, opts) => {
+  const out = run("npm", [...args, "--json"], opts).stdout.trim();
+  return out ? JSON.parse(out) : undefined;
+};
+
+function npmMeta(name) {
+  const m = npmJson(["view", name, "versions", "time", "dist-tags"]);
+  return { versions: m.versions, time: m.time, distTags: m["dist-tags"] };
+}
+
+function npmPack(spec, dest) {
+  mkdirSync(dest, { recursive: true });
+  const [info] = npmJson(["pack", spec, "--pack-destination", dest, "--ignore-scripts"], { cwd: dest });
+  return join(dest, info.filename);
+}
+
+/** Unpack an npm tarball's package/ into `into` (which must not exist yet). */
+function unpack(tgz, into) {
+  const tmp = `${into}.unpack`;
+  mkdirSync(tmp, { recursive: true });
+  run("tar", ["-xzf", tgz, "-C", tmp]);
+  cpSync(join(tmp, "package"), into, { recursive: true });
+  rmSync(tmp, { recursive: true, force: true });
+}
+
+/** git diff of two package trees in the format of the committed patches (a/dist/… b/dist/…, 7-digit index). */
+function diffTrees(work, before, after) {
+  const dir = mkdtempSync(join(work, "diff-"));
+  cpSync(before, join(dir, "a"), { recursive: true });
+  cpSync(after, join(dir, "b"), { recursive: true });
+  const emptyConfig = join(dir, "empty.gitconfig");
+  writeFileSync(emptyConfig, "");
+  const env = { ...process.env, GIT_CONFIG_NOSYSTEM: "1", GIT_CONFIG_GLOBAL: emptyConfig, LC_ALL: "C" };
+  const res = run(
+    "git",
+    ["-c", "core.abbrev=7", "diff", "--no-index", "--no-color", "--no-ext-diff", "--no-textconv", "--no-renames", "--no-prefix", "a", "b"],
+    { cwd: dir, env, allowFail: true },
+  );
+  if (res.status !== 0 && res.status !== 1) throw new Error(`git diff failed: ${res.stderr}`);
+  rmSync(dir, { recursive: true, force: true });
+  return res.stdout;
+}
+
+function parseArgs(argv) {
+  const opts = { version: "latest", pnpm: "pnpm" };
+  const value = (i) => {
+    if (argv[i + 1] === undefined || argv[i + 1].startsWith("--")) throw new Error(`${argv[i]} needs a value`);
+    return argv[i + 1];
+  };
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === "--dry-run") opts.dryRun = true;
+    else if (a === "--force") opts.force = true;
+    else if (a === "--resolve-only") opts.resolveOnly = true;
+    else if (a === "--skip-install") opts.skipInstall = true;
+    else if (a === "--json") opts.json = true;
+    else if (a === "--version") opts.version = value(i++);
+    else if (a === "--work-dir") opts.workDir = resolve(value(i++));
+    else if (a === "--report-dir") opts.reportDir = resolve(value(i++));
+    else if (a === "--pnpm") opts.pnpm = value(i++);
+    else if (a === "-h" || a === "--help") opts.help = true;
+    else throw new Error(`unknown argument ${a}`);
+  }
+  return opts;
+}
+
+async function main(argv) {
+  const opts = parseArgs(argv);
+  if (opts.help) {
+    console.log(readFileSync(fileURLToPath(import.meta.url), "utf8").match(/\/\*\*([\s\S]*?)\*\//)[1].replace(/^ \* ?/gm, ""));
+    return 0;
+  }
+  const here = dirname(fileURLToPath(import.meta.url));
+  const cliRoot = join(here, "..");
+  const repoRoot = join(cliRoot, "..", "..");
+  const pkgPath = join(cliRoot, "package.json");
+  const wsPath = join(repoRoot, "pnpm-workspace.yaml");
+  const pkg = JSON.parse(readFileSync(pkgPath, "utf8"));
+  const wsText = readFileSync(wsPath, "utf8");
+  const pins = piPins(pkg);
+  const current = pins[CODING_AGENT];
+  const minAgeMinutes = readMinimumReleaseAge(wsText);
+
+  const decision = selectVersion({ meta: npmMeta(CODING_AGENT), current, requested: opts.version, minAgeMinutes });
+  if (opts.resolveOnly) {
+    console.log(JSON.stringify({ ...decision, minAgeMinutes }));
+    return 0;
+  }
+  if (!decision.version) {
+    console.log(`没有发布满 ${minAgeMinutes} 分钟的版本可升(跳过:${decision.skippedYoung.join(", ") || "无"})`);
+    return 0;
+  }
+  if (opts.version === "latest" && decision.upToDate) {
+    console.log(`已是最新:${current}(可升的最新版 ${decision.version}${decision.skippedYoung.length ? `;未满 ${minAgeMinutes} 分钟、已跳过 ${decision.skippedYoung.join(", ")}` : ""})`);
+    return 0;
+  }
+  const target = decision.version;
+  const log = (s) => console.error(`[pi-upgrade] ${s}`);
+  log(`${current} → ${target}${decision.young ? `(发布不满 ${minAgeMinutes} 分钟)` : ""}`);
+
+  const work = opts.workDir ?? mkdtempSync(join(tmpdir(), "pi-upgrade-"));
+  mkdirSync(work, { recursive: true });
+  const reportDir = opts.reportDir ?? join(work, "report");
+  log(`工作目录 ${work}`);
+
+  // 1. versions of every pi package + undici
+  const manifests = {};
+  const fetchDeps = (name, version) => {
+    const m = npmJson(["view", `${name}@${version}`, "version", "dependencies"]);
+    if (!m || (m.version ?? m) !== version) throw new Error(`${name}@${version} is not published on npm`);
+    manifests[name] = m;
+    return m.dependencies;
+  };
+  const closure = await resolvePiClosure({ roots: Object.keys(pins).sort(), target, fetchDeps });
+  const undiciSpec = manifests[CODING_AGENT]?.dependencies?.undici;
+  const undici = undiciSpec && STABLE.test(undiciSpec) ? undiciSpec : undefined;
+  if (undiciSpec && !undici) log(`pi-coding-agent 的 undici 是范围 ${undiciSpec},不同步`);
+  const { pkg: nextPkg, changes } = planPackageJson(pkg, closure, undici);
+
+  // 2. pristine tarballs: new (all pi packages, for CHANGELOGs), old pi-coding-agent (for the UI diff)
+  const tgz = {};
+  for (const [name, version] of Object.entries(closure)) tgz[name] = npmPack(`${name}@${version}`, join(work, "tgz"));
+  const oldTgz = current && current !== target ? npmPack(`${CODING_AGENT}@${current}`, join(work, "tgz-old")) : undefined;
+
+  const orig = join(work, "orig");
+  const fixture = join(work, "fixture");
+  rmSync(orig, { recursive: true, force: true });
+  rmSync(fixture, { recursive: true, force: true });
+  for (const name of PATCHED) {
+    unpack(tgz[name], join(orig, name));
+    unpack(tgz[name], join(fixture, "node_modules", name));
+  }
+  const oldCa = join(work, "old", CODING_AGENT);
+  rmSync(join(work, "old"), { recursive: true, force: true });
+  if (oldTgz) unpack(oldTgz, oldCa);
+
+  // 3. patch-pi.js on the fixture (exactly what npm's postinstall does), then diff = the pnpm patches
+  mkdirSync(join(fixture, "scripts"), { recursive: true });
+  writeFileSync(join(fixture, "package.json"), '{"type":"module"}\n');
+  cpSync(join(here, "patch-pi.js"), join(fixture, "scripts", "patch-pi.js"));
+  const patchLog = run(process.execPath, [join(fixture, "scripts", "patch-pi.js")], {
+    cwd: fixture,
+    env: { ...process.env, U1S1_PATCH_PI_SCAN_ROOT: fixture },
+  }).stdout.trim();
+  if (patchLog) log(`patch-pi.js: ${patchLog.replace(/\n/g, " | ")}`);
+
+  const patches = PATCHED.map((name) => {
+    const text = diffTrees(work, join(orig, name), join(fixture, "node_modules", name));
+    const file = patchFileName(name, closure[name]);
+    const path = join(work, "patches", file);
+    mkdirSync(dirname(path), { recursive: true });
+    writeFileSync(path, text);
+    return { name, file, path, text, empty: text === "", hunks: (text.match(/^@@ /gm) ?? []).length };
+  });
+
+  // 4. rule status against the pristine new sources (pi-patch-report does the classification)
+  const reportArgs = [join(here, "pi-patch-report.mjs"), "--json", "--pi", join(orig, CODING_AGENT), "--tui", join(orig, TUI), "--patch-pi", join(here, "patch-pi.js")];
+  for (const p of patches) reportArgs.push("--patch", p.path);
+  // pi-patch-report calls process.exit right after printing; a pipe would cut the JSON off at 64 KB, a file does not
+  const rrOut = join(work, "pi-patch-report.json");
+  const fd = openSync(rrOut, "w");
+  const rr = spawnSync(process.execPath, reportArgs, { stdio: ["ignore", fd, "pipe"], encoding: "utf8" });
+  closeSync(fd);
+  if (rr.status !== 0 && rr.status !== 1) throw new Error(`pi-patch-report failed: ${rr.stderr || rr.error?.message}`);
+  const ruleResults = JSON.parse(readFileSync(rrOut, "utf8")).rules;
+
+  // 5. slash-command descriptions: u1s1's extension table vs the new BUILTIN_SLASH_COMMANDS
+  const readOr = (p) => (existsSync(p) ? readFileSync(p, "utf8") : "");
+  const ours = parseUiTextTable(readOr(join(cliRoot, "src", "pi-ui-text.ts")));
+  const builtin = parseSlashCommands(readOr(join(orig, CODING_AGENT, SLASH_COMMANDS_FILE)));
+  if (!ours || !builtin) throw new Error(`cannot read ${!ours ? "BUILTIN_COMMAND_TEXT in src/pi-ui-text.ts" : `BUILTIN_SLASH_COMMANDS in ${SLASH_COMMANDS_FILE}`}`);
+  const slashCommands = slashCommandDrift(ours, builtin);
+
+  // 6. new UI strings in the rule target files, old vs new pi-coding-agent
+  const uiFiles = {};
+  for (const file of new Set(ruleResults.map((r) => r.file).filter((f) => f.startsWith("dist/")))) {
+    uiFiles[file] = { old: readOr(join(oldTgz ? oldCa : join(orig, CODING_AGENT), file)), new: readOr(join(orig, CODING_AGENT, file)) };
+  }
+  const ruleFroms = jsStringLiterals(readFileSync(join(here, "patch-pi.js"), "utf8"));
+  const uiStrings = newUiStrings(uiFiles, ruleFroms);
+
+  // 7. Breaking sections of every CHANGELOG shipped in the new tarballs
+  const breaking = [];
+  const seen = new Set();
+  for (const [name, file] of Object.entries(tgz)) {
+    const dir = join(work, "changelog", name);
+    rmSync(dir, { recursive: true, force: true });
+    unpack(file, dir);
+    const changelog = join(dir, "CHANGELOG.md");
+    if (!existsSync(changelog) || !current) continue;
+    for (const entry of extractBreaking(readFileSync(changelog, "utf8"), current, closure[name])) {
+      const items = entry.items.filter((i) => !seen.has(i));
+      items.forEach((i) => seen.add(i));
+      if (items.length) breaking.push({ package: name.slice(PI_SCOPE.length), version: entry.version, items });
+    }
+  }
+
+  const report = buildReport({
+    current,
+    target,
+    packages: changes,
+    undici,
+    rules: ruleResults,
+    slashCommands,
+    uiStrings,
+    breaking,
+    patches: patches.map(({ file, empty, hunks }) => ({ file, empty, hunks })),
+  });
+  mkdirSync(reportDir, { recursive: true });
+  writeFileSync(join(reportDir, "report.json"), `${JSON.stringify(report, null, 2)}\n`);
+  writeFileSync(join(reportDir, "report.md"), renderMarkdown(report));
+  writeFileSync(join(reportDir, "report.public.md"), renderMarkdown(report, { publicSafe: true }));
+
+  if (opts.json) console.log(JSON.stringify(report, null, 2));
+  else console.log(renderMarkdown(report));
+  log(`报告:${reportDir}/report.{json,md,public.md}`);
+
+  const exitCode = report.ok ? 0 : 1;
+  if (!report.ok && !opts.force) {
+    log(`补丁规则 ${report.rules.problems.length} 条、斜杠命令文案表 ${report.slashCommands.length} 处对不上,不改工作区(--force 可照写)`);
+    return exitCode;
+  }
+  if (opts.dryRun) {
+    log("--dry-run:不改工作区");
+    return exitCode;
+  }
+
+  // 8. write the working tree
+  writeFileSync(pkgPath, `${JSON.stringify(nextPkg, null, 2)}\n`);
+  const young = Object.entries(closure)
+    .filter(([name, version]) => {
+      const age = npmMeta(name).time?.[version];
+      return !age || Date.now() - Date.parse(age) < minAgeMinutes * 60_000;
+    })
+    .map(([name, version]) => `${name}@${version}`);
+  writeFileSync(wsPath, planWorkspaceYaml(wsText, { versions: closure, exclude: young, dropPatched: patches.filter((p) => p.empty).map((p) => p.name) }));
+  const patchesDir = join(repoRoot, "patches");
+  for (const name of PATCHED) {
+    const prefix = `${name.replace("/", "__")}@`;
+    for (const f of readdirSync(patchesDir)) if (f.startsWith(prefix) && f.endsWith(".patch")) unlinkSync(join(patchesDir, f));
+  }
+  for (const p of patches) if (!p.empty) writeFileSync(join(patchesDir, p.file), p.text);
+  log("已改 package.json、pnpm-workspace.yaml、patches/");
+
+  const npmDir = join(work, "npm-lock");
+  rmSync(npmDir, { recursive: true, force: true });
+  mkdirSync(npmDir, { recursive: true });
+  cpSync(pkgPath, join(npmDir, "package.json"));
+  cpSync(join(cliRoot, "package-lock.json"), join(npmDir, "package-lock.json"));
+  run("npm", ["install", "--package-lock-only", "--ignore-scripts", "--no-audit", "--no-fund"], { cwd: npmDir });
+  cpSync(join(npmDir, "package-lock.json"), join(cliRoot, "package-lock.json"));
+  log("已更新 packages/cli/package-lock.json");
+
+  if (!opts.skipInstall) {
+    const pn = opts.pnpm.split(" ");
+    const res = spawnSync(pn[0], [...pn.slice(1), "install", "--no-frozen-lockfile"], { cwd: repoRoot, stdio: ["ignore", process.stderr, process.stderr] });
+    if (res.status !== 0) throw new Error(`pnpm install exited ${res.status ?? res.error?.message}`);
+    log("已更新 pnpm-lock.yaml(pnpm install)");
+  }
+  return exitCode;
+}
+
+if (process.argv[1] && import.meta.url === pathToFileURL(resolve(process.argv[1])).href) {
+  // exitCode, not exit(): a large report written to a pipe would be cut off by an immediate exit
+  main(process.argv.slice(2)).then(
+    (code) => {
+      process.exitCode = code;
+    },
+    (err) => {
+      console.error(`[pi-upgrade] 失败:${err?.stack ?? err}`);
+      process.exitCode = 2;
+    },
+  );
+}