create-wxl 0.0.0-stage → 3.1.0

package/src/questions.mjs

@@ -0,0 +1,274 @@
+// The interactive question machinery (traceability.md "Setup questions", step 3 and step 5):
+// one `readline` interface per run, created on first use and closed before `run` returns (so a
+// `--no-setup` run, or one with every flag given, never touches `io.stdin` at all); the EOF
+// sentinel `run.mjs` turns into CW-E15; and the summary's yes/no/second-pass classification (S6).
+
+import { createInterface } from 'node:readline'
+import { SignalAbort } from './signals.mjs'
+
+export class QuestionEofError extends Error {
+  constructor() {
+    super('input ended while a question was open')
+    this.name = 'QuestionEofError'
+  }
+}
+
+/**
+ * `ask()` resolves to the next line `io.stdin` writes, after calling `deps.checkpoint('question')`
+ * (the test driver uses that call to schedule the next scripted line); it rejects with
+ * `QuestionEofError` when `io.stdin` ends (EOF) before a line arrives, including when it had
+ * already ended before this `ask()` call. `close()` is idempotent and distinguishes itself
+ * closing the `readline` interface from the stream's own EOF, so a run that never asks a second
+ * question after EOF does not also reject that EOF on the interface's own `close` event.
+ *
+ * The `readline` interface's own `line` listener is resident (attached once, for the life of the
+ * interface), not attached only while a question is open: `readline`, in non-terminal mode, emits
+ * every complete line already sitting in one input chunk synchronously, one after another, so a
+ * line arriving before the NEXT `ask()` call had the chance to attach its own listener would
+ * otherwise be silently dropped (P-18/C-05) -- type-ahead or a multi-line paste on the real
+ * terminal, or, in a test, several scripted answers written in one chunk. A line that arrives with
+ * no question open is queued; `ask()` takes the queue's head first, only waiting when the queue is
+ * empty.
+ */
+export function makeQuestioner(io, deps, guard) {
+  let rl = null
+  let closedByUs = false
+  let ended = false
+  const queue = []
+  let pending = null
+
+  function ensureRl() {
+    if (rl) return
+    rl = createInterface({ input: io.stdin })
+    // traceability.md "Signals": "the bin ... forwards a readline interface's own SIGINT event to
+    // the same handler, so Ctrl-C at a question ends the run instead of pausing it". `readline`
+    // itself only emits this on a real TTY; `deps.signals.emit('SIGINT')` (the bin, or a test) is
+    // the one path this module relies on, but forwarding `rl`'s own event keeps that promise
+    // explicit here, not just in the bin.
+    rl.on('SIGINT', () => deps.signals.emit('SIGINT'))
+    rl.on('line', (line) => {
+      if (pending) {
+        const { resolve } = pending
+        pending = null
+        guard?.clearWait() // S-17: settled by a line, not a signal -- the pending slot is done
+        resolve(line)
+      } else {
+        queue.push(line)
+      }
+    })
+    rl.on('close', () => {
+      ended = true
+      if (pending) {
+        const { reject } = pending
+        pending = null
+        guard?.clearWait() // S-17: settled by EOF, not a signal
+        if (!closedByUs) reject(new QuestionEofError())
+      }
+    })
+  }
+
+  function ask() {
+    deps.checkpoint('question')
+    // A signal already raised by the time this question starts (T-0024's checkpoint-driven
+    // tests): reject immediately, never waiting on `io.stdin` at all.
+    if (guard?.raised()) return Promise.reject(new SignalAbort(guard.raised()))
+    ensureRl()
+    if (queue.length > 0) return Promise.resolve(queue.shift())
+    if (ended || io.stdin.readableEnded) return Promise.reject(new QuestionEofError())
+    return new Promise((resolve, reject) => {
+      pending = { resolve, reject }
+      // A signal arriving while this question is already pending (decision 4): the guard calls
+      // this the moment it is raised, rejecting the same way EOF does above.
+      guard?.waitForSignal((err) => {
+        pending = null
+        reject(err)
+      })
+    })
+  }
+
+  function close() {
+    closedByUs = true
+    guard?.clearWait()
+    if (rl) rl.close()
+  }
+
+  return { ask, close }
+}
+
+/** S6 (traceability.md): trimmed, compared case-insensitively. Empty or `y`/`yes` -> proceed;
+ * `n`/`no` -> second pass; anything else -> invalid (asked again). */
+export function classifySummaryAnswer(raw) {
+  const trimmed = raw.trim().toLowerCase()
+  if (trimmed === '' || trimmed === 'y' || trimmed === 'yes') return 'proceed'
+  if (trimmed === 'n' || trimmed === 'no') return 'second-pass'
+  return 'invalid'
+}
+
+// Step 5's engine argv order (traceability.md "Step order", row 5): author, repo, host, origin,
+// site-name. `site-name`'s flag/answer key uses the hyphenated form the Command grammar and the
+// engine's own argv both use.
+const ENGINE_ARGV_ORDER = ['author', 'repo', 'host', 'origin', 'site-name']
+
+/** Builds `--flag=value` items in the fixed order, verbatim, omitting any flag not present. */
+export function buildEngineArgv(flags) {
+  return ENGINE_ARGV_ORDER.filter((name) => name in flags).map((name) => `--${name}=${flags[name]}`)
+}
+
+/** CW-E05 (traceability.md "Error and warning codes"): `--author`, `--repo`, `--host` always
+ * required; `--origin` only when `--host` is EXACTLY `cloudflare-pages` (Command grammar: flag
+ * values are verbatim, so this is a plain string compare, never case-insensitive). */
+export function missingRequiredFlags(flags) {
+  const missing = []
+  if (!('author' in flags)) missing.push('author')
+  if (!('repo' in flags)) missing.push('repo')
+  if (!('host' in flags)) missing.push('host')
+  if (flags.host === 'cloudflare-pages' && !('origin' in flags)) missing.push('origin')
+  return missing
+}
+
+// ─── interactive setup questions (S1-S6) ──────────────────────────────────────────────────────
+
+const FIELD_FLAG_NAME = { author: 'author', repo: 'repo', host: 'host', origin: 'origin', siteName: 'site-name' }
+const FIELD_ORDER = ['author', 'repo', 'host', 'origin', 'siteName']
+
+function currentToFlags(current) {
+  const flags = {}
+  for (const field of FIELD_ORDER) {
+    if (current[field] !== undefined) flags[FIELD_FLAG_NAME[field]] = current[field]
+  }
+  return flags
+}
+
+/** S3's mapping (traceability.md "Setup questions"): `1`, `2`, `github-pages`, `cloudflare-pages`
+ * (case-insensitive, already trimmed by the caller) map to the canonical host value; anything
+ * else is not a valid answer. Only applied to a TYPED answer -- Enter reuses `current.host`
+ * verbatim, whatever form it is already in (a flag's raw value, or an earlier mapped answer). */
+function mapHostAnswer(trimmed) {
+  const lower = trimmed.toLowerCase()
+  if (trimmed === '1' || lower === 'github-pages') return 'github-pages'
+  if (trimmed === '2' || lower === 'cloudflare-pages') return 'cloudflare-pages'
+  return null
+}
+
+/** Asks one field's question, re-asking on an invalid answer (printing why first), and returns
+ * the accepted value. Enter keeps `current[field]` verbatim (decision C: a default that came
+ * from a flag is never re-trimmed or re-mapped); a non-empty answer is trimmed, then validated
+ * (and, for `host`, mapped). `origin`/`siteName` accept a lone `-` to clear the current answer
+ * (traceability.md "Setup questions": "A single `-` answered to S4 or S5 clears the current
+ * answer"). */
+async function askField(io, t, questioner, field, current) {
+  const promptId = { author: 'S1', repo: 'S2', host: 'S3', origin: 'S4', siteName: 'S5' }[field]
+  const allowClear = field === 'origin' || field === 'siteName'
+
+  while (true) {
+    io.stdout.write(t[promptId]() + '\n')
+    const raw = await questioner.ask()
+    const trimmed = raw.trim()
+
+    let candidate
+    if (trimmed === '') {
+      candidate = current[field]
+    } else if (allowClear && trimmed === '-') {
+      candidate = undefined
+    } else {
+      candidate = trimmed
+    }
+
+    if (field === 'host' && trimmed !== '') {
+      const mapped = mapHostAnswer(trimmed)
+      if (mapped === null) {
+        io.stdout.write(t['S3-INVALID']({ value: trimmed }) + '\n')
+        continue
+      }
+      candidate = mapped
+    }
+
+    if ((field === 'author' || field === 'repo') && (candidate === undefined || candidate === '')) {
+      io.stdout.write(t[field === 'author' ? 'S1-EMPTY' : 'S2-EMPTY']() + '\n')
+      continue
+    }
+
+    if (field === 'origin' && current.host === 'cloudflare-pages' && (candidate === undefined || candidate === '')) {
+      io.stdout.write(t['S4-REQUIRED']() + '\n')
+      continue
+    }
+
+    return candidate
+  }
+}
+
+/** 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')
+  io.stdout.write(t['S6-HOST']({ value: current.host }) + '\n')
+  if (current.origin !== undefined) {
+    io.stdout.write(t['S6-ORIGIN-ANSWER']({ value: current.origin }) + '\n')
+  }
+  const origin =
+    parsedArgs.origin !== undefined
+      ? parsedArgs.origin
+      : parsedArgs.host === 'github-pages'
+        ? deps.engine.deriveGithubPagesOrigin(parsedArgs.repo)
+        : undefined
+  if (origin !== undefined) {
+    io.stdout.write(t['S6-ORIGIN']({ origin }) + '\n')
+  }
+  if (current.siteName !== undefined) {
+    io.stdout.write(t['S6-SITE-NAME']({ value: current.siteName }) + '\n')
+  }
+  io.stdout.write(t['S6']() + '\n')
+}
+
+/**
+ * Steps 3-5's setup-questions orchestration, interactive branch (traceability.md "Setup
+ * questions"). First pass asks only the questions whose flag was not given; an engine rejection
+ * or a summary `n` starts a second pass that asks every question S1-S5, with the current answers
+ * as defaults regardless of flags. Returns the last `parseForkInitArgs` result once the summary
+ * is accepted (empty, `y` or `yes`); throws `QuestionEofError` on EOF, or rethrows anything that
+ * is not `deps.engine.ForkInitArgError`.
+ */
+export async function collectInteractiveAnswers(io, deps, t, flags, questioner) {
+  const current = {
+    author: flags.author,
+    repo: flags.repo,
+    host: flags.host !== undefined ? flags.host : 'github-pages',
+    origin: flags.origin,
+    siteName: flags['site-name'],
+  }
+  let pass = 1
+
+  outer: for (;;) {
+    const fields = pass === 1 ? FIELD_ORDER.filter((field) => !(FIELD_FLAG_NAME[field] in flags)) : FIELD_ORDER
+    for (const field of fields) {
+      current[field] = await askField(io, t, questioner, field, current)
+    }
+
+    const argv = buildEngineArgv(currentToFlags(current))
+    let parsedArgs
+    try {
+      parsedArgs = deps.engine.parseForkInitArgs(argv)
+    } catch (err) {
+      if (err instanceof deps.engine.ForkInitArgError) {
+        io.stdout.write(t['ENGINE-REJECTED']({ message: err.message }) + '\n')
+        pass = 2
+        continue outer
+      }
+      throw err
+    }
+
+    for (;;) {
+      printSummary(io, t, deps, current, parsedArgs)
+      const raw = await questioner.ask()
+      const classification = classifySummaryAnswer(raw)
+      if (classification === 'proceed') return { parsedArgs, argv }
+      if (classification === 'second-pass') {
+        pass = 2
+        continue outer
+      }
+      io.stdout.write(t['S6-INVALID']() + '\n')
+    }
+  }
+}

package/src/raw-tar.mjs

@@ -0,0 +1,188 @@
+// A minimal, read-only raw tar header walker, used by `archive.mjs` to recover the ONE byte
+// `tar`'s own `Header.decode` does not expose faithfully: the typeflag at offset 156.
+// `Header.decode` reclassifies a type `0` entry whose path ends in `/` as type `5` (Directory)
+// (node-tar header.js, "old tar versions marked dirs as a file with a trailing /"), and forces a
+// directory's decoded size to 0 regardless of what is encoded, which makes such an entry
+// indistinguishable from a real directory through node-tar's own `entry.type`/`entry.header.size`
+// alone. T-0021's archive entry rules 1 and 3 need the untouched byte to tell the two apart.
+//
+// Review finding P-01/C-02: two independent parsers walking the SAME bytes must apply the SAME
+// size rules, or they desync (an attacker-chosen typeflag can be paired with the wrong entry,
+// hiding e.g. a symlink from rule 1). This walker therefore replicates `tar`'s own size rules --
+// a pax extended header's `size`/`path` override the next entry's, and a directory's effective
+// size is forced to 0 -- so it advances through the SAME bytes `tar` does. `archive.mjs` still
+// cross-checks each pairing's path and size against `tar`'s own decoded header as a second line
+// of defence: any divergence this walker's replica missed is caught there, not silently accepted.
+//
+// This walker does not decode uid/gid/mtime or GNU long-LINKPATH bodies: only the fields the
+// cross-check in archive.mjs needs (typeflag, path, size), in archive order. It supports both a
+// gzip-compressed body (auto-detected by magic bytes) and a plain, already-decompressed tar
+// (T-0025's X7 reuses it against `git archive`'s plain tar output, through this export only --
+// the `--no-setup` run path itself requires gzip, see archive.mjs).
+
+import { gunzipSync } from 'node:zlib'
+
+const GZIP_MAGIC_0 = 0x1f
+const GZIP_MAGIC_1 = 0x8b
+
+// Matches node-tar's own `maxDecompressionRatio` default (parse.js): bounds the decompressed size
+// so a crafted small gzip body cannot force an unbounded allocation before any rule runs (P-12/C-06).
+const DECOMPRESSION_RATIO_LIMIT = 1000
+
+// Typeflags `tar`'s `ReadEntry` treats as metadata (pax extended/global, GNU long-name/long-link,
+// and GNU's older long-path code): these never reach an 'entry' or 'ignoredEntry' event.
+export const META_TYPEFLAGS = new Set(['K', 'L', 'N', 'g', 'x', 'X'])
+
+function toBuffer(bytes) {
+  return Buffer.isBuffer(bytes) ? bytes : Buffer.from(bytes)
+}
+
+function maybeDecompress(bytes) {
+  const buf = toBuffer(bytes)
+  if (buf.length >= 2 && buf[0] === GZIP_MAGIC_0 && buf[1] === GZIP_MAGIC_1) {
+    try {
+      return gunzipSync(buf, { maxOutputLength: Math.max(buf.length * DECOMPRESSION_RATIO_LIMIT, 1 << 20) })
+    } catch (err) {
+      throw new Error(`gzip decompression failed or exceeded the size limit: ${err?.message ?? String(err)}`)
+    }
+  }
+  return buf
+}
+
+function isNullBlock(buf, offset) {
+  for (let i = offset; i < offset + 512; i++) {
+    if (buf[i] !== 0) return false
+  }
+  return true
+}
+
+function decString(buf, off, len) {
+  return buf.subarray(off, off + len).toString('utf8').replace(/\0.*/, '')
+}
+
+/** Decodes a tar numeric field: the common space/NUL-terminated octal text, or (for a field whose
+ * first byte has the high bit set) the GNU base-256 binary extension used for values too large
+ * for octal text. */
+function decodeNumericField(buf, offset, length) {
+  if ((buf[offset] & 0x80) !== 0) {
+    let value = BigInt(buf[offset] & 0x7f)
+    for (let i = 1; i < length; i++) value = (value << 8n) | BigInt(buf[offset + i])
+    return Number(value)
+  }
+  let str = ''
+  for (let i = 0; i < length; i++) {
+    const c = buf[offset + i]
+    if (c === 0 || c === 0x20) break
+    str += String.fromCharCode(c)
+  }
+  str = str.trim()
+  return str === '' ? 0 : parseInt(str, 8)
+}
+
+/** The ustar name, joined with its `prefix` field when the ustar magic is present (header.js's
+ * own decode: a byte at offset 475 selects a 155- or 130-byte prefix field). Does not apply any
+ * pax/GNU override -- callers do that with the returned name as the fallback. */
+function decodeUstarPath(buf, off) {
+  const name = decString(buf, off, 100)
+  const isUstar = buf.subarray(off + 257, off + 265).toString('latin1') === 'ustar\u000000'
+  if (!isUstar) return name
+  const longPrefix = buf[off + 475] !== 0
+  const prefix = decString(buf, off + 345, longPrefix ? 155 : 130)
+  return prefix ? `${prefix}/${name}` : name
+}
+
+/** Parses a pax extended header's body (the length-prefixed `"%d %s=%s\n"` records), returning
+ * only the two fields the cross-check needs. */
+function parsePaxOverrides(bodyBuf) {
+  const body = bodyBuf.toString('utf8')
+  const overrides = {}
+  let rest = body
+  while (rest.length > 0) {
+    const m = /^(\d+) /.exec(rest)
+    if (!m) break
+    const recLen = parseInt(m[1], 10)
+    if (!(recLen > 0) || recLen > rest.length) break
+    const record = rest.slice(0, recLen)
+    rest = rest.slice(recLen)
+    const inner = record.slice(m[1].length + 1)
+    const eq = inner.indexOf('=')
+    if (eq === -1) continue
+    const key = inner.slice(0, eq)
+    let value = inner.slice(eq + 1)
+    if (value.endsWith('\n')) value = value.slice(0, -1)
+    if (key === 'path') overrides.path = value
+    if (key === 'size') {
+      const n = Number(value)
+      // node-tar's own `#slurp` drops a negative `size` override (header.js); mirrored here so a
+      // negative pax size cannot make the two walkers disagree on how much to skip.
+      if (Number.isFinite(n) && n >= 0) overrides.size = n
+    }
+  }
+  return overrides
+}
+
+/**
+ * Walks `bytes` (gzip or plain tar) header block by header block, returning one record per block
+ * in archive order: `{ rawTypeflag, isMeta }` for a metadata header, or
+ * `{ rawTypeflag, isMeta: false, path, size }` for a real one, where `path`/`size` already have a
+ * preceding pax extended header's or GNU long-name's override applied (reset after each real
+ * entry, exactly as `tar`'s own `EX` is), and `size` is forced to 0 when the (overridden) path
+ * ends in `/` or the (NUL-normalised) typeflag is `5` -- matching `Header.decode`'s own forcing
+ * rule, so a lying `size` next to a directory typeflag cannot hide another header in "its" data.
+ */
+export function walkRawEntries(bytes) {
+  const buf = maybeDecompress(bytes)
+  const result = []
+  let offset = 0
+  let consecutiveNulls = 0
+  let pendingPath
+  let pendingSize
+
+  while (offset + 512 <= buf.length) {
+    if (isNullBlock(buf, offset)) {
+      consecutiveNulls += 1
+      offset += 512
+      if (consecutiveNulls >= 2) break
+      continue
+    }
+    consecutiveNulls = 0
+    const rawTypeflag = String.fromCharCode(buf[offset + 156])
+    const ustarSize = decodeNumericField(buf, offset + 124, 12)
+    const bodyStart = offset + 512
+
+    if (META_TYPEFLAGS.has(rawTypeflag)) {
+      const dataBlocks = Math.ceil(ustarSize / 512)
+      if (rawTypeflag === 'L') {
+        const bodyBuf = buf.subarray(bodyStart, Math.min(bodyStart + ustarSize, buf.length))
+        pendingPath = bodyBuf.toString('utf8').replace(/\0.*/, '')
+      } else if (rawTypeflag === 'x') {
+        const bodyBuf = buf.subarray(bodyStart, Math.min(bodyStart + ustarSize, buf.length))
+        const overrides = parsePaxOverrides(bodyBuf)
+        if (overrides.path !== undefined) pendingPath = overrides.path
+        if (overrides.size !== undefined) pendingSize = overrides.size
+      }
+      // 'K' (GNU long linkpath), 'N' (old GNU long path) and 'g'/'X' (pax/old-pax global) are
+      // consumed for offset purposes only: linkpath and global headers are never applied to the
+      // next entry's path/size by `tar` itself (header.js's `#slurp` excludes `path`/`linkpath`
+      // from a global header; `K`/comment handling is unrelated to this cross-check).
+      result.push({ rawTypeflag, isMeta: true })
+      offset = bodyStart + dataBlocks * 512
+      continue
+    }
+
+    const name = decodeUstarPath(buf, offset)
+    const path = pendingPath !== undefined ? pendingPath : name
+    const sizeBeforeDirRule = pendingSize !== undefined ? pendingSize : ustarSize
+    const normalizedType = rawTypeflag === '\u0000' ? '0' : rawTypeflag
+    const finalType = normalizedType === '0' && path.endsWith('/') ? '5' : normalizedType
+    const size = finalType === '5' ? 0 : sizeBeforeDirRule
+
+    result.push({ rawTypeflag, isMeta: false, path, size })
+    pendingPath = undefined
+    pendingSize = undefined
+
+    const dataBlocks = Math.ceil(size / 512)
+    offset = bodyStart + dataBlocks * 512
+  }
+  return result
+}

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
+}