create-wxl 3.0.0 → 3.1.0

package/src/run.mjs

@@ -1,43 +1,18 @@
-import { dirname, join, resolve as resolvePath } from 'node:path'
+import { dirname, resolve as resolvePath } from 'node:path'
 import { createHash } from 'node:crypto'
 import { messages, cwE12FinishingCommandsList } from './messages.mjs'
 import { jsonValue } from './text.mjs'
 import { selectLanguage } from './language.mjs'
-import { parseArchive, ArchiveParseError } from './archive.mjs'
-import { checkEntryRules, ArchiveRuleError } from './archive-rules.mjs'
 import { parseArgvStrict, ArgvError, SETUP_FLAG_NAMES } from './argv.mjs'
-import { checkTarget, extractEntries, moveIntoPlace, MoveIntoPlaceError } from './fsops.mjs'
-import { applyChangelog, applyOpenQuestions, applyPackageJson, writeRangeJson, PristineError } from './pristine.mjs'
+import { checkTarget, moveIntoPlace, MoveIntoPlaceError } from './fsops.mjs'
 import { isNodeVersionOk, MINIMUM_NODE_VERSION } from './node-version.mjs'
 import { makeQuestioner, QuestionEofError, buildEngineArgv, missingRequiredFlags, collectInteractiveAnswers } from './questions.mjs'
 import { runGitSteps, orderedPrintedForms } from './git-steps.mjs'
 import { buildNextSteps } from './next-steps.mjs'
 import { createSignalGuard, SignalAbort } from './signals.mjs'
-
-const VERSION_RE = /^\d+\.\d+\.\d+$/
-const COMMIT_RE = /^[0-9a-f]{40}$/
-
-/** 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). */
-async function removeTmpDir(deps, tmpDir) {
-  await deps.fs.rm(tmpDir, { recursive: true, force: true })
-}
-
-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. */
-function isFileSystemError(err) {
-  return typeof err?.code === 'string' && !err.code.startsWith('ERR_')
-}
+import { VERSION_RE, COMMIT_RE } from './patterns.mjs'
+import { removeTmpDir, downloadArchive, readArchiveEntries, makeTmpDir, extractInto, applyPristine } from './run-shared.mjs'
+import { runUpgrade } from './upgrade.mjs'
 
 /** Step 2's package source record check (D2): `deps.engineFile` is read through `deps.fs` and its
  * SHA-256 compared with `source.engineSha256`. */
@@ -62,7 +37,8 @@ async function validateSourceRecord(deps) {
 /**
  * create-wxl's one exported seam (0005-S1): the Step order table's steps 1-13, every signal
  * window (traceability.md "Signals"), and the full set of failure-path messages (CW-E09,
- * CW-E11, CW-E14, CW-W05).
+ * CW-E11, CW-E14, CW-W05). An argv whose first positional is `upgrade` is dispatched to
+ * 0006's upgrade path instead (0006-S1, `runUpgrade` in upgrade.mjs).
  */
 export async function run(argv, io, deps) {
   // traceability.md "Signals": "errors writing the messages are ignored". Without a listener, a
@@ -143,6 +119,9 @@ async function runBody(argv, io, deps) {
   const guard = createSignalGuard(deps.signals, ['SIGINT', 'SIGTERM', 'SIGHUP'])
   const questioner = makeQuestioner(io, deps, guard)
   try {
+    if (parsed.mode === 'upgrade') {
+      return await runUpgrade(parsed, io, deps, t2, lang2, guard, { hasOverride, overrideRaw })
+    }
     return await runSteps(parsed, io, deps, t2, lang2, questioner, guard, { hasOverride, overrideRaw })
   } catch (err) {
     if (err instanceof QuestionEofError) {
@@ -289,121 +268,42 @@ async function runStepsBody(
   if (hasOverride) {
     io.stderr.write(t2['CW-W04']({ commit }) + '\n')
   }
-  const url = `https://codeload.github.com/${deps.source.repository}/tar.gz/${commit}`
-  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(deps.source.repository, commit, { 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 1
-  } finally {
-    clearTimeout(timer)
-    // S-17: step 6's own 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 } }) + '\n')
-    return 1
-  }
+  // The URL/AbortController/timeout/race/CW-E07 window lives in `run-shared.mjs`'s
+  // `downloadArchive`, shared with the upgrade path (traceability.md "Step order" row 7); this
+  // call site's own checkpoints and CW-W04 are unchanged.
+  const downloaded = await downloadArchive({ io, deps, t2, guard, repository: deps.source.repository, ref: commit })
+  if (!downloaded) return 1
+  const { body } = downloaded
 
   deps.checkpoint('step-7')
   guard.throwIfRaised()
-  let parsedArchive
-  try {
-    parsedArchive = await parseArchive(body)
-  } catch (err) {
-    if (err instanceof ArchiveParseError) {
-      io.stderr.write(t2['CW-E08']({ parseError: err.message }) + '\n')
-      return 1
-    }
-    throw err
-  }
-  let validatedEntries
-  try {
-    validatedEntries = checkEntryRules(parsedArchive, { commit })
-  } catch (err) {
-    if (err instanceof ArchiveRuleError) {
-      io.stderr.write(t2['CW-E08']({ rule: err.rule, path: err.path, isCommentMarker: err.isCommentMarker }) + '\n')
-      return 1
-    }
-    throw err
-  }
+  // Parsing, entry-rule validation, mkdtemp, extraction and P1-P4 live in `run-shared.mjs`,
+  // shared with the upgrade path; this call site's own checkpoints, `setTmpDir` and argument
+  // shape are unchanged.
+  const validatedEntries = await readArchiveEntries({ io, t2, body, commit })
+  if (!validatedEntries) return 1
 
   deps.checkpoint('step-8')
   guard.throwIfRaised()
   const parentDir = dirname(target)
-  let tmpDir
-  try {
-    tmpDir = await deps.fs.mkdtemp(join(parentDir, '.create-wxl-'))
-    setTmpDir(tmpDir)
-  } catch (err) {
-    if (isFileSystemError(err)) {
-      io.stderr.write(t2['CW-E09']({ path: parentDir, detail: err.message }) + '\n')
-      return 1 // mkdtemp itself failed: nothing was created, nothing to clean up
-    }
-    throw err
-  }
-  try {
-    // S-19: `{ stopped: true }` (never a silent early return) is the one signal `extractEntries`
-    // gives for "a signal arrived mid-extraction"; turned into the same `SignalAbort` every other
-    // window throws, right here, instead of a separate check the caller could forget.
-    const { stopped } = await extractEntries(deps, validatedEntries, tmpDir, { shouldStop: () => guard.isRaised() })
-    if (stopped) throw new SignalAbort(guard.raised())
-  } catch (err) {
-    if (err instanceof SignalAbort) throw err
-    if (isFileSystemError(err)) {
-      return failWithCleanup(io, deps, tmpDir, t2['CW-E09']({ path: err.reportPath ?? tmpDir, detail: err.message }))
-    }
-    throw err
-  }
+  const tmpDir = await makeTmpDir({ io, deps, t2, parent: parentDir, prefix: '.create-wxl-' })
+  if (!tmpDir) return 1 // mkdtemp itself failed: nothing was created, nothing to clean up
+  setTmpDir(tmpDir)
+  if (!(await extractInto({ io, deps, t2, guard, entries: validatedEntries, tmpDir }))) return 1
 
   deps.checkpoint('step-9')
   guard.throwIfRaised()
-  try {
-    await applyChangelog(deps.fs, tmpDir)
-    guard.throwIfRaised() // decision 6: a signal mid-step-9 stops before the next P-rule's write
-    await applyOpenQuestions(deps.fs, tmpDir)
-    guard.throwIfRaised()
-    await applyPackageJson(deps.fs, tmpDir)
-    guard.throwIfRaised()
-    await writeRangeJson(deps.fs, tmpDir, {
-      repository: deps.source.repository,
-      version: deps.source.version,
-      commit,
-    })
-    guard.throwIfRaised() // P-02/C-01: a signal during step 9's last write starts no step-10 work
-  } catch (err) {
-    if (err instanceof PristineError) {
-      return failWithCleanup(io, deps, tmpDir, t2['CW-E10']({ file: err.file, rule: err.rule }))
-    }
-    if (isFileSystemError(err)) {
-      return failWithCleanup(io, deps, tmpDir, t2['CW-E09']({ path: err.reportPath ?? tmpDir, detail: err.message }))
-    }
-    throw err
+  if (
+    !(await applyPristine({
+      io,
+      deps,
+      t2,
+      guard,
+      tmpDir,
+      record: { repository: deps.source.repository, version: deps.source.version, commit },
+    }))
+  ) {
+    return 1
   }
 
   deps.checkpoint('step-10')

package/src/text.mjs

@@ -45,6 +45,38 @@ export function jsonValue(value) {
   return out + '"'
 }
 
+/** Candidate 22 (stage 7, security-T-0026): prints `value` through `JSON.stringify` -- unlike
+ * `jsonValue`, without wrapping the result in its own extra quotes, so an array or object prints
+ * as itself (`["3.1.0"]`, `{"toString":1}`), not through `String(value)` (which calls `toString`,
+ * throwing for a value whose own `toString` property is not callable, and collapsing an array
+ * like `["3.1.0"]` into the indistinguishable-from-a-real-version `"3.1.0"`). Any DEL/C1
+ * character or lone surrogate `JSON.stringify`'s own algorithm leaves unescaped (it already
+ * escapes every C0 character and lone surrogate itself, ES2019) is escaped the same way
+ * `escapeChar` would (D10). Returns `undefined` when `JSON.stringify` throws (a `BigInt`, a
+ * circular structure) or itself returns `undefined` (a bare `function` or `undefined` value) --
+ * the caller falls back to a type name in that case. */
+const SHORT_ESCAPE_CODES = { b: '0008', f: '000c', r: '000d', t: '0009' }
+
+export function jsonStringifyEscaped(value) {
+  let str
+  try {
+    str = JSON.stringify(value)
+  } catch {
+    return undefined
+  }
+  if (typeof str !== 'string') return undefined
+  // D10: JSON.stringify's own short escapes for backspace, form feed, CR and tab become `\uXXXX`
+  // (a line feed keeps `\n`); matching escape pairs left to right leaves `\\` followed by a
+  // letter untouched.
+  str = str.replace(/\\(.)/g, (pair, c) => (c in SHORT_ESCAPE_CODES ? `\\u${SHORT_ESCAPE_CODES[c]}` : pair))
+  let out = ''
+  for (const ch of str) {
+    const code = ch.codePointAt(0)
+    out += isControlCodePoint(code) || isLoneSurrogate(code) ? `\\u${code.toString(16).padStart(4, '0')}` : ch
+  }
+  return out
+}
+
 const BARE_RE = /^[A-Za-z0-9._\-/@%+=:,]+$/
 
 export function posixQuoteWord(word) {
@@ -78,3 +110,18 @@ export function hasControlChar(str) {
   }
   return false
 }
+
+/** `\` is Windows' own path separator; comparing after turning `\` into `/` (traceability.md
+ * "Step order" row 3, Vocabulary "name on disk") makes a path comparison platform-neutral. Shared
+ * by step 3 and P-9 since T-0062. */
+export function toSlash(value) {
+  return String(value).replace(/\\/g, '/')
+}
+
+/** ASCII-only case folding (`[A-Z]` to lowercase), the way git's own `tolower` and J5's repository
+ * comparison fold -- never JavaScript's Unicode-aware lowercasing. Shared by J5 and entry rule 3
+ * since T-0062. */
+export function foldAsciiCase(value) {
+  return value.replace(/[A-Z]/g, (c) => c.toLowerCase())
+}
+

package/src/upgrade-report.mjs

@@ -0,0 +1,134 @@
+// Step 10 (traceability.md "Step order" row 10, "Report"): prints R1-R5, one per line, each
+// starting with its own id, in the run's language (`t2`). R3 renders each attention item through the
+// language table's own UP-A* text. R2 lists every path M6 deleted after the counts (D16). R4
+// (traceability.md "Report" R4) is a fixed body of next-steps advice plus three conditional bullets:
+// D16's `|||||||` line only when R3 holds UP-A1, `pnpm install` only when the run wrote
+// `package.json` or `pnpm-lock.yaml`, and the deploy-tag push only for a range with
+// `.github/workflows/deploy.yml`.
+
+import { jsonValue, posixCommand } from './text.mjs'
+
+/** D14 (T-0063): the restore commands, in order -- `checkout` first, so a missing or changed
+ * ignore file is back before `clean` runs, and `clean` never deletes a file `HEAD`'s rules ignore.
+ * R5 and UP-E09 print them, and U70 runs them, from this one list. */
+export const RESTORE_COMMANDS = Object.freeze([
+  Object.freeze(['git', 'checkout', '--', '.']),
+  Object.freeze(['git', 'clean', '-fd']),
+])
+
+/** D23 (T-0066): the restore commands as the one line R5 and UP-E09 print, joined with `&&`, so a
+ * `git checkout -- .` that fails never lets `git clean -fd` run (a shell without `&&`, such as
+ * Windows PowerShell 5.1, refuses the whole line, and nothing runs). */
+export function restoreCommandLine() {
+  return RESTORE_COMMANDS.map((command) => posixCommand(command)).join(' && ')
+}
+
+/** `ops` carrying a `report` code (M10, or an M12 conflict/UP-A11 outcome) are written, but not
+ * counted here (traceability.md "Report" R2's own "M10 is not counted as updated"). */
+function countsFromOps(ops) {
+  const counts = { updated: 0, added: 0, deleted: 0 }
+  for (const op of ops) {
+    if (op.report !== undefined) continue
+    if (op.action === 'delete') counts.deleted++
+    else if (op.action === 'write') counts[op.existedBefore ? 'updated' : 'added']++
+  }
+  return counts
+}
+
+/** UP-A12 sorts last among attention lines (traceability.md "Report" R3); every other code sorts
+ * by path. */
+function sortAttention(attention) {
+  const rest = attention.filter((item) => item.code !== 'UP-A12').sort((a, b) => (a.path < b.path ? -1 : a.path > b.path ? 1 : 0))
+  const anchor = attention.filter((item) => item.code === 'UP-A12')
+  return [...rest, ...anchor]
+}
+
+/** T-0027 increment 21 (U26), traceability.md "Report" R2's own "M10 is not counted as updated":
+ * unlike `countsFromOps`, above, this does not look at `op.report` at all -- a written
+ * `package.json`/`pnpm-lock.yaml` still needs `pnpm install` advice whether or not it was an M10
+ * lockfile-conflict write or a plain M5/M12 write. */
+function wroteDependencyFile(ops) {
+  return ops.some((op) => op.action === 'write' && (op.path === 'package.json' || op.path === 'pnpm-lock.yaml'))
+}
+
+/** R4 (traceability.md "Report"): a fixed body of next-steps advice, plus three conditional
+ * bullets (D16's `|||||||` line, `pnpm install`, the `v*` tag), each its own `R4:` line (mirrors
+ * R3's own one-line-per-item convention). */
+function buildR4Lines(lang2, { ops, attention, hasDeployWorkflow }) {
+  const zh = lang2 === 'zh-TW'
+  const lines = [
+    zh ? 'R4: 執行 git status 與 git diff' : 'R4: run git status and git diff',
+    // Named generically here (never the literal code "UP-A1"), so this fixed bullet never
+    // collides with a path-specific assertion elsewhere checking a particular attention code's
+    // ABSENCE from the whole run's stdout (e.g. U56, increment 17's own `not.toContain('UP-A1')`).
+    zh
+      ? 'R4: 處理上面的衝突標記（搜尋 <<<<<<<）與其他注意項目'
+      : 'R4: resolve the conflict markers above (search for <<<<<<<) and the other attention items',
+  ]
+  // D16 (T-0063): when R3 holds UP-A1, say whose text the `|||||||` section of a conflict block is.
+  // Like the bullet above, it never names the code itself.
+  if (attention.some((item) => item.code === 'UP-A1')) {
+    lines.push(
+      zh
+        ? 'R4: 衝突區塊裡 ||||||| 之後的段落是 R1 所列 base 版本的內容；如果這個 base 不是靶場原本所依據的版本，請先執行 R5 的指令'
+        : 'R4: in a conflict block, the section after ||||||| is the text of the base version in R1; ' +
+            'if that base is not the version the range came from, run the R5 commands first',
+    )
+  }
+  if (wroteDependencyFile(ops)) lines.push(zh ? 'R4: 執行 pnpm install' : 'R4: run pnpm install')
+  lines.push(zh ? 'R4: build 並測試' : 'R4: build and test')
+  lines.push('R4: commit')
+  if (hasDeployWorkflow) lines.push(zh ? 'R4: 推送新的 v* tag 以觸發部署' : 'R4: push a new v* tag to deploy')
+  return lines
+}
+
+export function buildReport({ lang2, toolVersion, baseVersion, baseCommit, targetVersion, targetCommit, ops, attention, hasDeployWorkflow, t2, baseUnchecked = false }) {
+  const zh = lang2 === 'zh-TW'
+  const counts = countsFromOps(ops)
+  const lines = []
+  // D17 (traceability.md "Report" R1; T-0061): a `--from <commit>` base is whatever that commit
+  // holds -- R1 says it was not checked against an upstream tag.
+  const uncheckedNote = baseUnchecked
+    ? zh
+      ? '；base 由 --from <commit> 指定，沒有比對上游的 tag'
+      : '; the base was given by --from <commit> and not checked against an upstream tag'
+    : ''
+  lines.push(
+    zh
+      ? `R1: create-wxl ${jsonValue(toolVersion)}；base 版本 ${jsonValue(baseVersion)}（commit ${jsonValue(baseCommit)}）；` +
+          `target 版本 ${jsonValue(targetVersion)}（commit ${jsonValue(targetCommit)}）` +
+          uncheckedNote
+      // Names the commit the same way the zh-TW text above already does.
+      : `R1: create-wxl ${jsonValue(toolVersion)}; base ${jsonValue(baseVersion)} (commit ${jsonValue(baseCommit)}); ` +
+          `target ${jsonValue(targetVersion)} (commit ${jsonValue(targetCommit)})` +
+          uncheckedNote,
+  )
+  lines.push(
+    zh
+      ? `R2: 更新 ${counts.updated} 新增 ${counts.added} 刪除 ${counts.deleted}`
+      : `R2: updated ${counts.updated} added ${counts.added} deleted ${counts.deleted}`,
+  )
+  // D16 (T-0063): then every path M6 deleted (the only deleting row), sorted by UTF-16 code units,
+  // without a code.
+  const deletedPaths = ops.filter((op) => op.action === 'delete').map((op) => op.path)
+  for (const path of deletedPaths.sort((a, b) => (a < b ? -1 : a > b ? 1 : 0))) lines.push(`R2: ${jsonValue(path)}`)
+  // T-0027 verification follow-up (item 1/2): each attention line is rendered through `t2`
+  // (traceability.md:206 "in the run's language"), the same en/zh-TW UP-A* message table every
+  // other code already uses -- UP-A12 (T-0027 increment 20, U59) is not tied to any one path
+  // (traceability.md "Fork:init-derived content"), so it prints without one, unlike every other
+  // UP-A* line.
+  for (const item of sortAttention(attention)) {
+    lines.push(item.code === 'UP-A12' ? `R3: ${t2[item.code]()}` : `R3: ${t2[item.code]()} ${jsonValue(item.path)}`)
+  }
+  lines.push(...buildR4Lines(lang2, { ops, attention, hasDeployWorkflow }))
+  // traceability.md "Report" R5; spec.en.md B4: the restore commands undo
+  // the WHOLE upgrade, so they are only safe BEFORE any other change -- the fixed bare commands
+  // alone, without that warning, let a teacher who edits first lose that edit too.
+  // The same one line UP-E09 prints (messages.mjs, D23).
+  lines.push(
+    zh
+      ? `R5: 如果要撤銷整個升級，請在做其他變更之前執行 ${restoreCommandLine()}`
+      : `R5: to undo the whole upgrade before making other changes, run ${restoreCommandLine()}`,
+  )
+  return lines.join('\n') + '\n'
+}