create-wxl 3.0.0 → 3.1.0

package/src/messages.mjs

@@ -3,16 +3,31 @@
 // (AC-18): argument/target/download checks, strict parse and entry rules 1-5 (CW-E08), pristine
 // rule failures (CW-E10), setup questions (S1-S6's prompts, reasons and summary lines, CW-E05,
 // CW-E06, CW-E12, CW-E15), git steps (CW-W01-W03), "Next steps" lines (N1-N8), and the failure
-// and signal paths (CW-E09, CW-E11, CW-E14, CW-W05).
+// and signal paths (CW-E09, CW-E11, CW-E14, CW-W05). Every UP-* text (0006's upgrade path:
+// UP-E01-E13, UP-I01, UP-A1-A15) likewise begins with its code, in both tables
+// (`upgrade-messages.test.mjs` checks the whole UP-* set).
 
-import { jsonValue, posixCommand, posixQuoteWord, formatDirectoryArg, hasControlChar } from './text.mjs'
+import { jsonValue, posixCommand, posixQuoteWord, formatDirectoryArg, hasControlChar, jsonStringifyEscaped } from './text.mjs'
 import { printedForms } from './git-steps.mjs'
 import { MINIMUM_GIT_VERSION } from './git-version.mjs'
+import { MINIMUM_BASE_VERSION_TEXT } from './base-version.mjs'
+import { VERSION_RE } from './patterns.mjs'
+import { restoreCommandLine } from './upgrade-report.mjs'
 
-/** CW-W01's minimum-version text (S-10), one source with the actual check (`isGitVersionOk`'s
- * own default), not a hardcoded "2.20" repeated in both language tables. */
+/** CW-W01's and UP-E02's minimum-version text (S-10), one source with the actual check (`isGitVersionOk`'s
+ * own default), not a hardcoded version repeated in both language tables. */
 const MINIMUM_GIT_VERSION_TEXT = MINIMUM_GIT_VERSION.join('.')
 
+/** Candidate 22 (stage 7): the fallback UP-E10 prints when `jsonStringifyEscaped` cannot (a
+ * `JSON.stringify` throw, or a `function`/`undefined` value it reflects back as `undefined`) --
+ * only `array`/`object`/`null`/`number`/`boolean` are reachable from the one call site this
+ * exists for (a non-string `version` read from parsed JSON). */
+function typeNameOf(value) {
+  if (value === null) return 'null'
+  if (Array.isArray(value)) return 'array'
+  return typeof value
+}
+
 const CONDITION_TEXT = {
   en: {
     file: 'it is not a directory',
@@ -169,7 +184,146 @@ function cwE07DetailText(lang, detail) {
   return lang === 'zh-TW' ? `下載失敗：${jsonValue(detail.message)}` : `the download failed: ${jsonValue(detail.message)}`
 }
 
+/** D18 (traceability.md revision 3.2; T-0061): the remedies for a base read from `range.json`
+ * that the upgrade refused, in this order -- `--from <version>` first (checked through upstream's
+ * tag), the recorded commit only when the teacher knows the range was made from it, then how to see
+ * who changed the setup record. `reason` says why the recorded commit is in doubt: `'not-release'`
+ * for UP-E12 (the tag names another commit), `'unchecked'` for UP-E08 and a 404 on the tag
+ * download (the commit could not be checked against its tag; the tag may only have been deleted). */
+function recordedBaseRemediesText(lang, reason) {
+  if (lang === 'zh-TW') {
+    const doubt = reason === 'not-release' ? '記錄的 commit 不是發布版' : '記錄的 commit 沒辦法經由它的 tag 驗證'
+    return (
+      '如果你知道這個靶場是從哪一版上游建立的，請用 --from <version> 重新執行（會經由上游的 tag 驗證）。' +
+      `${doubt}：只有確定這個靶場就是從它建立時，才用 --from <commit> 指定它。` +
+      'git log -p -- range.json 可以查出是誰改了這份設定紀錄。'
+    )
+  }
+  const doubt = reason === 'not-release' ? 'The recorded commit is not a release' : 'The recorded commit could not be checked against its tag'
+  return (
+    "If you know the release this range came from, run the upgrade again with --from <version> (checked through upstream's tag). " +
+    `${doubt}: name it with --from <commit> only if you know this range was made from it. ` +
+    'git log -p -- range.json shows who changed the setup record.'
+  )
+}
+
 export const en = {
+  'UP-E01': ({ path }) =>
+    `UP-E01: ${jsonValue(path)} is not the top level of a git work tree; run upgrade in the range's own root.`,
+  'UP-I01': ({ version, commit }) =>
+    `UP-I01: nothing to do; the range is already at version ${jsonValue(version)} (commit ${jsonValue(commit)}).`,
+  'UP-E02': ({ version }) =>
+    `UP-E02: git could not be run, or is older than ${MINIMUM_GIT_VERSION_TEXT}` +
+    (version !== undefined ? ` (found ${jsonValue(version)})` : '') +
+    `; install a newer git from https://git-scm.com/downloads.`,
+  'UP-E03': ({ reason }) => `UP-E03: the range is not clean (${jsonValue(reason)}); run git status to see what changed.`,
+  'UP-E04': () =>
+    `UP-E04: no range.json was found and no --from was given; pass --from <version> or --from <commit>, ` +
+    `or run this in a range made with create-wxl, which always has a range.json.`,
+  'UP-E05': ({ rangeRepository, sourceRepository }) =>
+    `UP-E05: range.json's upstream.repository ${jsonValue(rangeRepository)} does not match the upstream repository ${jsonValue(sourceRepository)}.`,
+  'UP-E06': ({ reason }) => `UP-E06: range.json is invalid (${jsonValue(reason)}).`,
+  'UP-E07': ({ baseVersion, targetVersion }) =>
+    `UP-E07: the range's base version ${jsonValue(baseVersion)} is higher than the target version ${jsonValue(targetVersion)}; downgrading is not supported.`,
+  'UP-E10': ({ version }) => {
+    if (version === undefined) {
+      return `UP-E10: the base version could not be read; a range from before ${MINIMUM_BASE_VERSION_TEXT} cannot be upgraded by this tool.`
+    }
+    if (typeof version !== 'string') {
+      const printed = jsonStringifyEscaped(version) ?? typeNameOf(version)
+      return `UP-E10: the base version ${printed} is not valid; a range from before ${MINIMUM_BASE_VERSION_TEXT} cannot be upgraded by this tool.`
+    }
+    if (!VERSION_RE.test(version)) {
+      return `UP-E10: the base version ${jsonValue(version)} is not valid; a range from before ${MINIMUM_BASE_VERSION_TEXT} cannot be upgraded by this tool.`
+    }
+    return `UP-E10: the base version ${jsonValue(version)} is lower than ${MINIMUM_BASE_VERSION_TEXT}; a range from before ${MINIMUM_BASE_VERSION_TEXT} cannot be upgraded by this tool.`
+  },
+  // D18 (T-0061): `remedies` is set for a base read from range.json.
+  'UP-E08': ({ tag, remedies }) =>
+    `UP-E08: the tag ${jsonValue(tag)}'s archive comment is not 40 lowercase hexadecimal characters; the commit the tag names could not be read.` +
+    (remedies ? ` ${recordedBaseRemediesText('en', 'unchecked')}` : ''),
+  // T-0027 increment 1 (traceability.md "Codes", attention items UP-A1-UP-A12): a fixed
+  // description per code, never per-instance (the path itself is printed by R3, next to the
+  // code, not inside this text) -- so every one of these takes no fields at all, trivially safe
+  // under `language.test.mjs`'s shared `ARGS` object: a function that never destructures anything
+  // can never throw on a missing field.
+  'UP-A1': () => `UP-A1: a conflict was written, marked with three labels (range, the base version, the target version).`,
+  'UP-A2': () => `UP-A2: a binary file changed on both sides; the range's own version was kept.`,
+  'UP-A3': () => `UP-A3: upstream deleted a file the range changed; the range's own version was kept.`,
+  'UP-A4': () => `UP-A4: upstream added a file where the range already has a different one; the range's own version was kept.`,
+  'UP-A5': () => `UP-A5: the range deleted a file upstream changed; it stays deleted.`,
+  'UP-A6': () => `UP-A6: the lockfile changed on both sides; upstream's was taken. Run pnpm install.`,
+  // T-0027 increment 4 (traceability.md "Codes", P-3): the path is or passes through a symbolic
+  // link in the range; untouched.
+  'UP-A7': () => `UP-A7: the path is or passes through a symbolic link in the range; it was left untouched.`,
+  // T-0027 increment 6 (traceability.md "Codes", P-5): the path is ignored by the range's own
+  // rules; untouched.
+  'UP-A9': () => `UP-A9: the path is ignored by the range's own rules; it was left untouched.`,
+  // T-0027 increment 13 (traceability.md "Codes", P-4): another path differs only by
+  // `path.normalize('NFC')` and `toLowerCase()` (`merge-plan.mjs`'s `hasCaseCollision`) --
+  // lowercasing, not full Unicode case folding (recorded, not changed), so the text names the
+  // Unicode form too, not only letter case; untouched.
+  'UP-A8': () =>
+    `UP-A8: another path in the range differs from this one only by letter case or Unicode form; it was left untouched.`,
+  // T-0027 increment 15 (traceability.md "Codes", P-6 and the parent check): the range has a
+  // directory or other non-file where upstream has a file, or a planned write's parent is kept as
+  // a non-directory; either way, untouched.
+  'UP-A10': () => `UP-A10: the range has a directory or other non-file where upstream has a file (or the reverse); it was left untouched.`,
+  // T-0027 increment 19 (traceability.md "Codes", M12): a clean merge of a `.json` file produced
+  // output that does not parse as JSON; the range's own version was kept instead.
+  'UP-A11': () => `UP-A11: a clean JSON merge did not parse; the range's own version was kept.`,
+  // T-0027 increment 20 (traceability.md "Fork:init-derived content", "Codes" UP-A12): any of the
+  // nine anchor files differs between base and target; this adds the single UP-A12 line, never
+  // naming the files themselves -- the one fixed text below covers both the
+  // rerun-with-original-arguments clause and the deploy-workflow clause.
+  'UP-A12': () =>
+    `UP-A12: upstream changed files pnpm fork:init writes. After resolving every attention item, rerun pnpm fork:init with the range's original arguments; for a range with a deploy workflow, this also refreshes it.`,
+  // D9 (traceability.md "Pre-checks" P-7, "Codes" UP-A13): an ignore file (at any level) that
+  // upstream changed is never written, so the restore commands and every ignored file stay
+  // safe; the teacher merges the ignore rules by hand.
+  'UP-A13': () =>
+    `UP-A13: upstream changed an ignore file; it was left untouched so ignored files and the restore commands stay safe. Merge the ignore rules by hand.`,
+  // D10 (traceability.md "Pre-checks" P-8, "Codes" UP-A14): the path is a submodule (a gitlink in
+  // the index) or lies under one; left untouched, since the restore commands cannot undo a change
+  // inside a submodule's own working tree.
+  'UP-A14': () =>
+    `UP-A14: the path is a submodule, or is inside one; it was left untouched, since the restore commands cannot undo a change there.`,
+  // P-9 (D12, T-0062).
+  'UP-A15': () =>
+    `UP-A15: the path's name on disk differs from upstream's (a short name, ignored characters, or letter case, in the path or a parent); it was left untouched.`,
+  // T-0027 increment 10 (traceability.md "Codes" UP-E09): a write failed, or a signal arrived,
+  // during step 9 (apply); names the path and the file-system error, or (for a signal) the signal
+  // name, plus the restore commands as one line in D14's order (`restoreCommandLine`: `git checkout
+  // -- . && git clean -fd`; D14 T-0063, D23 T-0066).
+  'UP-E09': ({ path, signal, detail }) =>
+    `UP-E09: ` +
+    (signal !== undefined
+      ? `a signal (${jsonValue(signal)}) stopped the upgrade while applying the plan`
+      : `applying the plan failed at ${jsonValue(path)}: ${jsonValue(detail)}`) +
+    `; the range may be partially changed. Run ${restoreCommandLine()} to restore it to HEAD.`,
+  // T-0027 increment 18 (traceability.md "Codes" UP-E11): planning (step 8) failed -- `git
+  // merge-file` exited outside 0-127 (or was ended by a signal, `code` `null`), or its output was
+  // not read in full (traceability.md's own wording for this code; no code path exercises that
+  // last clause -- see the ticket's coverage report). Nothing is written in the range before
+  // step 9, so there is nothing to restore (unlike UP-E09).
+  // `detail` is the underlying error's own text (a read error of o/b/t, or a `runGit` rejection
+  // for `merge-file`) -- absent for `MergeFileError` (U57's own "exited outside 0-127" case),
+  // which keeps its fixed wording instead.
+  'UP-E11': ({ path, detail }) =>
+    `UP-E11: planning the merge failed at ${jsonValue(path)}: ` +
+    (detail !== undefined ? jsonValue(detail) : `git merge-file did not finish normally.`),
+  // J6, D11, D18 (T-0061): the base read from range.json is not the commit upstream's tag names.
+  'UP-E12': ({ version, recordedCommit, tagCommit }) =>
+    `UP-E12: range.json records version ${jsonValue(version)} with commit ${jsonValue(recordedCommit)}, ` +
+    `but upstream's tag ${jsonValue(`v${version}`)} names commit ${jsonValue(tagCommit)}, so the recorded base is not an upstream release. ` +
+    `range.json may have been written with CREATE_WXL_COMMIT or by a package packed at a commit other than its version's tag, the tag may have moved since, or someone may have changed the setup record. ` +
+    recordedBaseRemediesText('en', 'not-release'),
+  // D15 (OQ-026; T-0061): an untracked range.json that the range's rules ignore.
+  'UP-E13': () =>
+    `UP-E13: range.json is not tracked and the range's ignore rules ignore it, so the restore commands could not undo the upgrade's change to it. ` +
+    `The rule may be in a .gitignore, in .git/info/exclude or in your core.excludesFile. ` +
+    `Remove the rule and commit that change, together with range.json when it exists; or, when range.json exists, track it with git add -f -- range.json and commit it. ` +
+    `If a tracked file's name differs from range.json only in letter case (such as Range.json), rename it to range.json with git mv and commit.`,
   'CW-E01': ({ running, minimum }) =>
     `CW-E01: the running Node.js ${jsonValue(running)} is older than the minimum ${jsonValue(minimum)}; install a newer Node.js from https://nodejs.org/.`,
   'CW-E02': ({ value, usage, reason = 'unknown', badValue }) =>
@@ -181,7 +335,9 @@ export const en = {
     '.',
   'CW-E05': ({ missing }) => cwE05Text('en', missing),
   'CW-E06': ({ message }) => `CW-E06: the engine rejected the answers: ${jsonValue(message)}.`,
-  'CW-E07': ({ url, detail }) => `CW-E07: downloading ${jsonValue(url)} failed: ${cwE07DetailText('en', detail)}.`,
+  // D18 (T-0061): `remedies` is set only for a 404 on the tag download of a base read from range.json.
+  'CW-E07': ({ url, detail, remedies }) =>
+    `CW-E07: downloading ${jsonValue(url)} failed: ${cwE07DetailText('en', detail)}.` + (remedies ? ` ${recordedBaseRemediesText('en', 'unchecked')}` : ''),
   'CW-E08': ({ rule, path, parseError, isCommentMarker }) =>
     parseError !== undefined
       ? `CW-E08: the archive could not be parsed: ${jsonValue(parseError)}.`
@@ -226,7 +382,7 @@ export const en = {
   'S6-REPO': ({ value }) => `  repository: ${jsonValue(value)}`,
   'S6-HOST': ({ value }) => `  host: ${jsonValue(value)}`,
   'S6-ORIGIN-ANSWER': ({ value }) => `  site address answered: ${jsonValue(value)}`,
-  'S6-ORIGIN': ({ origin }) => `  short link origin: ${jsonValue(origin)}`,
+  'S6-ORIGIN': ({ origin }) => `  range address, the origin of every copied link: ${jsonValue(origin)}`,
   'S6-SITE-NAME': ({ value }) => `  site name: ${jsonValue(value)}`,
   S6: () => `Apply these settings? [Y/n]`,
   'S6-INVALID': () => `Please answer y, yes, n or no (empty counts as yes).`,
@@ -248,6 +404,73 @@ export const en = {
 }
 
 export const zhTW = {
+  'UP-E01': ({ path }) => `UP-E01：${jsonValue(path)} 不是 git 工作目錄的頂層；請在靶場自己的根目錄執行 upgrade。`,
+  'UP-I01': ({ version, commit }) => `UP-I01：不需要升級；靶場目前已經是版本 ${jsonValue(version)}（commit ${jsonValue(commit)}）。`,
+  'UP-E02': ({ version }) =>
+    `UP-E02：git 無法執行，或版本低於 ${MINIMUM_GIT_VERSION_TEXT}` +
+    (version !== undefined ? `（偵測到 ${jsonValue(version)}）` : '') +
+    `；請到 https://git-scm.com/downloads 安裝較新版本。`,
+  'UP-E03': ({ reason }) => `UP-E03：靶場不乾淨（${jsonValue(reason)}）；請執行 git status 查看變更內容。`,
+  'UP-E04': () =>
+    `UP-E04：找不到 range.json，也沒有帶 --from；請帶上 --from <version> 或 --from <commit>，` +
+    `或是在用 create-wxl 建出來的靶場（一定會有 range.json）裡執行。`,
+  'UP-E05': ({ rangeRepository, sourceRepository }) =>
+    `UP-E05：range.json 的 upstream.repository ${jsonValue(rangeRepository)} 與上游的 repository ${jsonValue(sourceRepository)} 不一致。`,
+  'UP-E06': ({ reason }) => `UP-E06：range.json 不合法（${jsonValue(reason)}）。`,
+  'UP-E07': ({ baseVersion, targetVersion }) =>
+    `UP-E07：靶場目前的 base 版本 ${jsonValue(baseVersion)} 比 target 版本 ${jsonValue(targetVersion)} 還新，不支援降版。`,
+  'UP-E10': ({ version }) => {
+    if (version === undefined) {
+      return `UP-E10：無法讀出 base 版本；${MINIMUM_BASE_VERSION_TEXT} 之前的靶場無法用這個工具升級。`
+    }
+    if (typeof version !== 'string') {
+      const printed = jsonStringifyEscaped(version) ?? typeNameOf(version)
+      return `UP-E10：base 版本 ${printed} 格式不正確；${MINIMUM_BASE_VERSION_TEXT} 之前的靶場無法用這個工具升級。`
+    }
+    if (!VERSION_RE.test(version)) {
+      return `UP-E10：base 版本 ${jsonValue(version)} 格式不正確；${MINIMUM_BASE_VERSION_TEXT} 之前的靶場無法用這個工具升級。`
+    }
+    return `UP-E10：base 版本 ${jsonValue(version)} 低於 ${MINIMUM_BASE_VERSION_TEXT}；${MINIMUM_BASE_VERSION_TEXT} 之前的靶場無法用這個工具升級。`
+  },
+  'UP-E08': ({ tag, remedies }) =>
+    `UP-E08：tag ${jsonValue(tag)} 的 pax comment 不是 40 位小寫十六進位字元，讀不到 tag 指向的 commit。` +
+    (remedies ? recordedBaseRemediesText('zh-TW', 'unchecked') : ''),
+  // These UP-A* texts use an ASCII colon after the code, like `R1:`/`R2:`
+  // etc. elsewhere in the zh-TW report, instead of this table's own full-width "：" -- a R3 line
+  // is `R3: ` (ASCII) followed by one of these, so the two would otherwise mix colon styles in
+  // the same line.
+  'UP-A1': () => `UP-A1: 寫入了衝突標記，共三個標籤（range、base 版本、target 版本）。`,
+  'UP-A2': () => `UP-A2: 有二進位檔案兩邊都改了；保留靶場自己的版本。`,
+  'UP-A3': () => `UP-A3: 上游刪除了靶場改過的檔案；保留靶場自己的版本。`,
+  'UP-A4': () => `UP-A4: 上游新增的檔案在靶場裡已經是另一個不同的檔案；保留靶場自己的版本。`,
+  'UP-A5': () => `UP-A5: 靶場刪除了上游改過的檔案；維持刪除狀態。`,
+  'UP-A6': () => `UP-A6: lockfile 兩邊都改了；採用上游的版本，請執行 pnpm install。`,
+  'UP-A7': () => `UP-A7: 這個路徑本身或途經的目錄是靶場裡的符號連結；維持不動。`,
+  'UP-A9': () => `UP-A9: 這個路徑被靶場自己的規則忽略；維持不動。`,
+  'UP-A8': () => `UP-A8: 靶場裡另有一個路徑只差在大小寫或 Unicode 形式；維持不動。`,
+  'UP-A10': () => `UP-A10: 靶場這個路徑是目錄或其他非檔案的東西，但上游是檔案（或反過來）；維持不動。`,
+  'UP-A11': () => `UP-A11: JSON 乾淨合併後無法解析；保留靶場自己的版本。`,
+  'UP-A12': () =>
+    `UP-A12: 上游改了 pnpm fork:init 會寫入的檔案；請在解決所有注意項目後，用靶場原本的參數重新執行 pnpm fork:init；若靶場有部署用的 workflow，這個步驟也會一併更新它。`,
+  'UP-A13': () => `UP-A13: 上游改了一個忽略規則檔；維持不動，讓忽略的檔案與還原指令都安全。請自行手動合併忽略規則。`,
+  'UP-A14': () => `UP-A14: 這個路徑是子模組本身或在子模組裡面；維持不動，因為還原指令無法復原子模組內部的變更。`,
+  'UP-A15': () => `UP-A15: 這個路徑在磁碟上的實際名稱和上游的不同（短檔名、檔案系統會略過的字元或大小寫，在路徑本身或父目錄）；維持不動。`,
+  'UP-E09': ({ path, signal, detail }) =>
+    `UP-E09：` +
+    (signal !== undefined ? `收到訊號（${jsonValue(signal)}）後停止套用合併結果` : `套用合併結果時在 ${jsonValue(path)} 失敗：${jsonValue(detail)}`) +
+    `；靶場可能已經被部分改動。請執行 ${restoreCommandLine()} 還原到 HEAD。`,
+  'UP-E11': ({ path, detail }) =>
+    `UP-E11：規劃合併時在 ${jsonValue(path)} 失敗：` + (detail !== undefined ? jsonValue(detail) : `git merge-file 沒有正常結束。`),
+  'UP-E12': ({ version, recordedCommit, tagCommit }) =>
+    `UP-E12：range.json 記錄的版本是 ${jsonValue(version)}、commit 是 ${jsonValue(recordedCommit)}，` +
+    `但上游的 tag ${jsonValue(`v${version}`)} 指向 commit ${jsonValue(tagCommit)}，所以記錄的 base 不是上游的發布版。` +
+    `可能的原因：range.json 是用 CREATE_WXL_COMMIT，或由在不是該版本 tag 的 commit 打包的套件寫入的、這個 tag 之後被移動過，或是有人改了這份設定紀錄。` +
+    recordedBaseRemediesText('zh-TW', 'not-release'),
+  'UP-E13': () =>
+    `UP-E13：range.json 沒有被 git 追蹤，又被靶場的 ignore 規則排除，還原指令沒辦法撤銷升級對它的改動。` +
+    `這條規則可能在某個 .gitignore、.git/info/exclude，或你的 core.excludesFile 裡。` +
+    `請移除這條規則並 commit，range.json 存在時一起 commit；或者在 range.json 存在時，用 git add -f -- range.json 把它納入追蹤並 commit。` +
+    `如果被追蹤的檔名和 range.json 只差在大小寫（例如 Range.json），請用 git mv 改名為 range.json 並 commit。`,
   'CW-E01': ({ running, minimum }) =>
     `CW-E01：目前使用的 Node.js ${jsonValue(running)} 低於最低需求 ${jsonValue(minimum)}，請到 https://nodejs.org/ 下載較新版本。`,
   'CW-E02': ({ value, usage, reason = 'unknown', badValue }) =>
@@ -259,7 +482,8 @@ export const zhTW = {
     '。',
   'CW-E05': ({ missing }) => cwE05Text('zh-TW', missing),
   'CW-E06': ({ message }) => `CW-E06：引擎拒絕了這些答案：${jsonValue(message)}。`,
-  'CW-E07': ({ url, detail }) => `CW-E07：下載 ${jsonValue(url)} 失敗：${cwE07DetailText('zh-TW', detail)}。`,
+  'CW-E07': ({ url, detail, remedies }) =>
+    `CW-E07：下載 ${jsonValue(url)} 失敗：${cwE07DetailText('zh-TW', detail)}。` + (remedies ? recordedBaseRemediesText('zh-TW', 'unchecked') : ''),
   'CW-E08': ({ rule, path, parseError, isCommentMarker }) =>
     parseError !== undefined
       ? `CW-E08：壓縮檔無法解析：${jsonValue(parseError)}。`
@@ -301,7 +525,7 @@ export const zhTW = {
   'S6-REPO': ({ value }) => `  GitHub repository：${jsonValue(value)}`,
   'S6-HOST': ({ value }) => `  部署目標：${jsonValue(value)}`,
   'S6-ORIGIN-ANSWER': ({ value }) => `  回答的網站網址：${jsonValue(value)}`,
-  'S6-ORIGIN': ({ origin }) => `  短連結網址：${jsonValue(origin)}`,
+  'S6-ORIGIN': ({ origin }) => `  靶場網址（複製出來的每一條連結都從它開始）：${jsonValue(origin)}`,
   'S6-SITE-NAME': ({ value }) => `  網站名稱：${jsonValue(value)}`,
   S6: () => `要套用這些設定嗎？[Y/n]`,
   'S6-INVALID': () => `請回答 y、yes、n 或 no（留空視為 yes）。`,

package/src/patterns.mjs

@@ -0,0 +1,6 @@
+// Shared patterns (moved unchanged from run.mjs): the package source record's version and
+// commit shapes, reused by the upgrade path (traceability.md "Command grammar", "Base from
+// range.json").
+
+export const VERSION_RE = /^\d+\.\d+\.\d+$/
+export const COMMIT_RE = /^[0-9a-f]{40}$/

package/src/questions.mjs

@@ -197,9 +197,9 @@ async function askField(io, t, questioner, field, current) {
   }
 }
 
-/** S6: each answer, and the short-link origin the engine will write (traceability.md "Setup
- * questions"): the parsed args' `origin` when present, else `deriveGithubPagesOrigin(repo)` for
- * GitHub Pages. */
+/** S6: each answer, and the range address (the origin of every copied link) the engine will
+ * write (traceability.md "Setup questions"): the parsed args' `origin` when present, else
+ * `deriveGithubPagesOrigin(repo)` for GitHub Pages. */
 function printSummary(io, t, deps, current, parsedArgs) {
   io.stdout.write(t['S6-AUTHOR']({ value: current.author }) + '\n')
   io.stdout.write(t['S6-REPO']({ value: current.repo }) + '\n')

package/src/run-shared.mjs

@@ -0,0 +1,207 @@
+// Shared run helpers, moved out of run.mjs so steps 6-9 (0005) and the upgrade path's step 7
+// (0006) can call the same functions: the one place every "print a failure line, then remove the
+// temporary directory this run created, then fail" sequence lives, the file-system-vs-bug error
+// classifier, the download window (`downloadArchive`, now taking the repository/ref to download
+// instead of being tied to `deps.source`/`commit`), and the archive-read/mkdtemp/extract/
+// pristine-apply window (`readArchiveEntries` also gained the optional `tag` parameter here, for
+// 0006's tag-mode bases, and, with T-0061, `expectedCommit`/`tagVersion`/`remedies` for J6 and
+// D18; `downloadArchive` gained `remediesOn404`). The create path passes none of these.
+
+import { join } from 'node:path'
+import { SignalAbort } from './signals.mjs'
+import { parseArchive, ArchiveParseError } from './archive.mjs'
+import { checkEntryRules, ArchiveRuleError } from './archive-rules.mjs'
+import { extractEntries } from './fsops.mjs'
+import { applyChangelog, applyOpenQuestions, applyPackageJson, writeRangeJson, PristineError } from './pristine.mjs'
+import { COMMIT_RE } from './patterns.mjs'
+
+/** S-20: the one place every "print a failure line, then remove the temporary directory this run
+ * created, then fail" sequence lives (steps 8-10's CW-E09/CW-E10/CW-E04 branches, and the
+ * generic bug/signal catch, each used to repeat this pair of calls for itself). */
+export async function removeTmpDir(deps, tmpDir) {
+  await deps.fs.rm(tmpDir, { recursive: true, force: true })
+}
+
+export async function failWithCleanup(io, deps, tmpDir, line) {
+  io.stderr.write(line + '\n')
+  await removeTmpDir(deps, tmpDir)
+  return 1
+}
+
+/** CW-E09 (steps 8-9) vs. CW-E14 (a bug): a real file-system error carries a string `code` that
+ * does NOT start with `ERR_` (review finding C-12) -- Node's own argument-validation errors
+ * (`ERR_INVALID_ARG_TYPE`, `ERR_INVALID_ARG_VALUE`, `ERR_OUT_OF_RANGE`, ...) also carry a string
+ * `code`, but they are a programming bug in this codebase, not an environment problem to report
+ * as CW-E09. */
+export function isFileSystemError(err) {
+  return typeof err?.code === 'string' && !err.code.startsWith('ERR_')
+}
+
+/** The URL, `AbortController`, timeout, the `fetchArchive` race and CW-E07
+ * for a rejection, a timeout or a non-200 status -- the whole window 0005's step 6 (`runSteps`)
+ * and 0006's step 7 (`upgrade.mjs`) share, now taking the repository/ref to download instead of
+ * being tied to `deps.source`/`commit`. Returns `{ body }`, or `null` after CW-E07 is already
+ * printed; the caller's own `checkpoint('step-6')`/`guard.throwIfRaised()`/CW-W04 are unchanged by
+ * this move, and so is `checkpoint('step-7')` (both stay at the call site). `remediesOn404` (D18,
+ * T-0061) adds the recorded-base remedies to CW-E07 for a 404 status only -- never for a rejection,
+ * a timeout or another status; the upgrade sets it for the tag download of a base read from
+ * `range.json`. */
+export async function downloadArchive({ io, deps, t2, guard, repository, ref, remediesOn404 = false }) {
+  const url = `https://codeload.github.com/${repository}/tar.gz/${ref}`
+  const controller = new AbortController()
+  // decision 6: a signal during the download aborts it through this same controller, instead of
+  // waiting out the full `downloadTimeoutMs` -- traceability.md "Signals": "after a signal no new
+  // file-system operation starts" (the download itself is not a file-system operation, but the
+  // rule not to keep running applies the same way).
+  const unsubscribeAbort = guard.onRaise(() => controller.abort())
+  let timedOut = false
+  let timer
+  const timeoutPromise = new Promise((_resolveTimeout, rejectTimeout) => {
+    timer = setTimeout(() => {
+      timedOut = true
+      controller.abort()
+      rejectTimeout(new Error())
+    }, deps.downloadTimeoutMs)
+  })
+
+  let status, body
+  try {
+    ;({ status, body } = await Promise.race([deps.fetchArchive(repository, ref, { signal: controller.signal }), timeoutPromise]))
+  } catch (err) {
+    if (guard.raised()) throw new SignalAbort(guard.raised())
+    const detail = timedOut ? { kind: 'timeout' } : { kind: 'error', message: err?.message ?? String(err) }
+    io.stderr.write(t2['CW-E07']({ url, detail }) + '\n')
+    return null
+  } finally {
+    clearTimeout(timer)
+    // S-17: this window has closed either way; this `AbortController` is no longer useful to
+    // abort, so the callback is removed instead of lingering for the rest of the run.
+    unsubscribeAbort()
+  }
+
+  guard.throwIfRaised() // P-17/C-14: a signal already received wins over a non-200 status
+  if (status !== 200) {
+    io.stderr.write(t2['CW-E07']({ url, detail: { kind: 'status', status }, remedies: remediesOn404 && status === 404 }) + '\n')
+    return null
+  }
+
+  return { body }
+}
+
+/** With an optional `tag` (U16): parses `body` (CW-E08 on a parse
+ * failure) and validates its entries against the archive entry rules (CW-E08 for a broken rule),
+ * returning the enriched entry list, or `null` after the message is already printed -- never
+ * throwing for either of those two conditions; anything else (a bug) is rethrown. Without `tag`,
+ * `commit` is compared against the archive's own pax comment exactly as rule 2 always has
+ * (0005's own call site never passes `tag`, so its behaviour is unchanged, and the return value
+ * stays the bare entry list). With `tag` (a `--from <version>` base, or a base read from
+ * `range.json`, whose tag is `v<tagVersion>`), the comment is resolved
+ * first: when it is not a string matching `COMMIT_RE`, UP-E08 is printed instead of CW-E08 and
+ * `commit` is never consulted; otherwise the comment itself becomes the `commit` rule 2 compares
+ * against (unchanged `checkEntryRules`), and the resolved commit is also returned (U52, inc 22:
+ * `{ entries, commit: comment }`) so the caller can learn the base commit a tag download alone
+ * never names. `expectedCommit` (J6, T-0061: a base read from `range.json`) must then equal the
+ * comment, checked before every entry rule; otherwise UP-E12 names `tagVersion` and both commits.
+ * `remedies` (D18) adds the recorded-base remedies to UP-E08. */
+export async function readArchiveEntries({ io, t2, body, commit, tag, expectedCommit, tagVersion, remedies = false }) {
+  let parsedArchive
+  try {
+    parsedArchive = await parseArchive(body)
+  } catch (err) {
+    if (err instanceof ArchiveParseError) {
+      io.stderr.write(t2['CW-E08']({ parseError: err.message }) + '\n')
+      return null
+    }
+    throw err
+  }
+  let effectiveCommit = commit
+  if (tag !== undefined) {
+    const { comment } = parsedArchive
+    if (typeof comment !== 'string' || !COMMIT_RE.test(comment)) {
+      io.stderr.write(t2['UP-E08']({ tag, remedies }) + '\n')
+      return null
+    }
+    effectiveCommit = comment
+    // J6 (D11, T-0061): a base read from range.json must be the commit the tag names. Checked
+    // right after the comment's own shape and before every entry rule, so a mismatched archive is
+    // UP-E12 whatever else it holds.
+    if (expectedCommit !== undefined && comment !== expectedCommit) {
+      io.stderr.write(t2['UP-E12']({ version: tagVersion, recordedCommit: expectedCommit, tagCommit: comment }) + '\n')
+      return null
+    }
+  }
+  try {
+    const entries = checkEntryRules(parsedArchive, { commit: effectiveCommit })
+    return tag !== undefined ? { entries, commit: effectiveCommit } : entries
+  } catch (err) {
+    if (err instanceof ArchiveRuleError) {
+      io.stderr.write(t2['CW-E08']({ rule: err.rule, path: err.path, isCommentMarker: err.isCommentMarker }) + '\n')
+      return null
+    }
+    throw err
+  }
+}
+
+/** `deps.fs.mkdtemp(join(parent, prefix))`, reporting CW-E09 naming `parent` for a
+ * file-system error (mkdtemp itself failed: nothing was created, nothing to clean up), or
+ * rethrowing a bug. Returns the new directory's path, or `null` after the message is printed. */
+export async function makeTmpDir({ io, deps, t2, parent, prefix }) {
+  try {
+    return await deps.fs.mkdtemp(join(parent, prefix))
+  } catch (err) {
+    if (isFileSystemError(err)) {
+      io.stderr.write(t2['CW-E09']({ path: parent, detail: err.message }) + '\n')
+      return null
+    }
+    throw err
+  }
+}
+
+/** Extracts `entries` into `tmpDir` (S-19's `{ stopped: true }` turned into the same
+ * `SignalAbort` every other window throws), reporting CW-E09 through `failWithCleanup` for a
+ * file-system error. Returns `true` on success, `false` after `failWithCleanup` already printed
+ * the message and removed `tmpDir`; a `SignalAbort` or a bug is rethrown, uncaught. */
+export async function extractInto({ io, deps, t2, guard, entries, tmpDir }) {
+  try {
+    const { stopped } = await extractEntries(deps, entries, tmpDir, { shouldStop: () => guard.isRaised() })
+    if (stopped) throw new SignalAbort(guard.raised())
+  } catch (err) {
+    if (err instanceof SignalAbort) throw err
+    if (isFileSystemError(err)) {
+      await failWithCleanup(io, deps, tmpDir, t2['CW-E09']({ path: err.reportPath ?? tmpDir, detail: err.message }))
+      return false
+    }
+    throw err
+  }
+  return true
+}
+
+/** P1-P4 against `tmpDir`, with the guard checked in between each write (decision 6: a signal
+ * mid-step-9 stops before the next P-rule's write); `record` is P4's `{ repository, version,
+ * commit }`. CW-E10 for a `PristineError`, CW-E09 for a file-system error, each through
+ * `failWithCleanup`; anything else (including a `SignalAbort` from `guard.throwIfRaised()`) is
+ * rethrown, uncaught. Returns `true` on success, `false` after the message is printed and
+ * `tmpDir` removed. */
+export async function applyPristine({ io, deps, t2, guard, tmpDir, record }) {
+  try {
+    await applyChangelog(deps.fs, tmpDir)
+    guard.throwIfRaised()
+    await applyOpenQuestions(deps.fs, tmpDir)
+    guard.throwIfRaised()
+    await applyPackageJson(deps.fs, tmpDir)
+    guard.throwIfRaised()
+    await writeRangeJson(deps.fs, tmpDir, record)
+    guard.throwIfRaised()
+  } catch (err) {
+    if (err instanceof PristineError) {
+      await failWithCleanup(io, deps, tmpDir, t2['CW-E10']({ file: err.file, rule: err.rule }))
+      return false
+    }
+    if (isFileSystemError(err)) {
+      await failWithCleanup(io, deps, tmpDir, t2['CW-E09']({ path: err.reportPath ?? tmpDir, detail: err.message }))
+      return false
+    }
+    throw err
+  }
+  return true
+}