create-wxl 0.0.0-stage → 3.0.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 short-link origin 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
+}