create-wxl 0.0.0-stage → 3.1.0

package/src/git-env.mjs

@@ -0,0 +1,13 @@
+// "Git steps" (traceability.md): every git command runs with `deps.env` minus every variable
+// whose name starts with `GIT_`, plus exactly `GIT_TERMINAL_PROMPT=0` and `GIT_CONFIG_NOSYSTEM=1`.
+// The filter compares the name exactly, as the spec says (decision 5): Windows' case-insensitive
+// environment names are a recorded known limit, not handled here.
+
+export function buildGitEnv(env) {
+  const filtered = {}
+  for (const [key, value] of Object.entries(env)) {
+    if (key.startsWith('GIT_')) continue
+    filtered[key] = value
+  }
+  return { ...filtered, GIT_TERMINAL_PROMPT: '0', GIT_CONFIG_NOSYSTEM: '1' }
+}

package/src/git-named.mjs

@@ -0,0 +1,43 @@
+// D19 (traceability.md revision 3.1; T-0061, moved here in T-0062 so step 8 shares it): runs one
+// git command and, when `runGit` rejects (not an exit code -- the spawn itself failed), rethrows it
+// as a bug whose message names the command, so CW-E14 says which git command failed. A signal
+// already received, or a `SignalAbort`, passes through unchanged so the run still exits 130.
+
+import { SignalAbort } from './signals.mjs'
+import { buildGitEnv } from './git-env.mjs'
+
+export async function runGitNamed(deps, guard, args, opts, name) {
+  try {
+    return await deps.runGit(args, opts)
+  } catch (err) {
+    if (err instanceof SignalAbort) throw err
+    guard.throwIfRaised()
+    throw new Error(`git ${name} failed: ${err?.message ?? String(err)}`, { cause: err })
+  }
+}
+
+/** P-5 and D15 (traceability.md "Pre-checks", step 5; Vocabulary's own "ignored path" -- "a path
+ * that is not tracked and that `git check-ignore -q --no-index -- ./<path>` reports as ignored by
+ * the range's rules"); shared by both since T-0062 (S1). `check-ignore`'s own exit codes are 0
+ * (ignored) and 1 (not ignored); any other exit code, or a `runGit` rejection, is a bug naming the
+ * command -- fail closed (D6, D19), never silently read as either answer. Called only for a path
+ * the caller has already found untracked (a force-added, tracked file that also matches an ignore
+ * rule is never P-5, and never D15). */
+export async function isIgnoredPath(deps, guard, rangeRoot, path) {
+  // `./` keeps the path literal: `check-ignore` refuses every pathspec magic (`--literal-pathspecs`
+  // included), and a path starting with `:` would otherwise be read as magic and check another path.
+  const name = `check-ignore -- ./${path}`
+  const result = await runGitNamed(
+    deps,
+    guard,
+    ['check-ignore', '-q', '--no-index', '--', `./${path}`],
+    { cwd: rangeRoot, env: buildGitEnv(deps.env) },
+    name,
+  )
+  // A signal this process already received while that `runGit` call was in flight wins over
+  // interpreting its result, the same way `runMergeFile` already does.
+  guard.throwIfRaised()
+  if (result.code === 0) return true
+  if (result.code === 1) return false
+  throw new Error(`git ${name} failed (exit code ${result.code}): ${result.stderr}`)
+}

package/src/git-runner.mjs

@@ -0,0 +1,120 @@
+// The real `runGit` implementation ("Git steps", traceability.md): spawns `git` without a shell,
+// using only the env the caller gives (never merged with `process.env` -- running under a git hook
+// during this repository's own tests would otherwise leak `GIT_DIR`/`GIT_INDEX_FILE` into the
+// isolated run). `git` is resolved from the absolute directories of `PATH` only: a relative entry
+// is ignored, and so is an entry whose realpath equals the current call's own `cwd` (the target)
+// or lies under it (decision 2, "never from the target directory"); a `PATH` entry that does not
+// exist is simply skipped. `bin`'s own wiring is T-0025's.
+
+import { spawn } from 'node:child_process'
+import { accessSync, constants as fsConstants, realpathSync, statSync } from 'node:fs'
+import { delimiter, isAbsolute, join, relative, resolve as resolvePath, sep } from 'node:path'
+
+function candidateNames(platform) {
+  return platform === 'win32' ? ['git.exe'] : ['git']
+}
+
+/** Windows' environment variable names are case-insensitive (`Path`, not just `PATH`); find the
+ * first key that matches `PATH` case-insensitively on win32, and only `PATH` exactly elsewhere. */
+function findPathValue(env, platform) {
+  if (platform !== 'win32') return env.PATH ?? ''
+  for (const [key, value] of Object.entries(env)) {
+    if (key.toUpperCase() === 'PATH') return value ?? ''
+  }
+  return ''
+}
+
+/** True when `dir` (already realpath'd) is `base` itself or lies under it -- a plain prefix check
+ * on the two realpaths, which also makes this case-insensitive-filesystem-safe (macOS APFS,
+ * Windows): `realpathSync.native` returns the on-disk casing regardless of the casing given. */
+function isSameOrUnder(dir, base) {
+  if (dir === base) return true
+  const rel = relative(base, dir)
+  return rel !== '' && rel !== '..' && !rel.startsWith(`..${sep}`) && !isAbsolute(rel)
+}
+
+function resolveGitPath(env, cwd, platform) {
+  const pathValue = findPathValue(env, platform)
+  const dirs = pathValue.split(delimiter).filter((entry) => entry !== '')
+  let excludedDir
+  try {
+    excludedDir = realpathSync.native(cwd)
+  } catch {
+    excludedDir = resolvePath(cwd)
+  }
+  for (const dir of dirs) {
+    if (!isAbsolute(dir)) continue
+    let resolvedDir
+    try {
+      resolvedDir = realpathSync.native(dir)
+    } catch {
+      continue
+    }
+    if (isSameOrUnder(resolvedDir, excludedDir)) continue
+    for (const name of candidateNames(platform)) {
+      const candidate = join(resolvedDir, name)
+      try {
+        if (!statSync(candidate).isFile()) continue
+        accessSync(candidate, fsConstants.X_OK)
+        return candidate
+      } catch {
+        continue
+      }
+    }
+  }
+  return null
+}
+
+/** Returns a `runGit(args, { cwd, env, binary })` function matching `deps.runGit`'s contract:
+ * resolves to `{ code, stdout, stderr }`, or rejects (ENOENT when `git` cannot be resolved from
+ * `PATH`, or whatever `child_process.spawn`'s own `error` event reports). `platform` (default
+ * `process.platform`) is injectable so tests can exercise the win32 lookup on any host. T-0027
+ * (D4, increment 25): `binary` (default falsy; every existing call site is unaffected) keeps
+ * `stdout` as a `Buffer` -- `git merge-file -p`'s own output is the one caller (`merge-plan.mjs`)
+ * that cannot afford the string-decoding path below silently replacing an invalid UTF-8 byte
+ * sequence (a non-UTF-8 text file, e.g. Big5) with U+FFFD before it is ever written back. */
+export function createSpawnGitRunner({ platform = process.platform } = {}) {
+  return function runGit(args, { cwd, env, binary = false }) {
+    return new Promise((resolvePromise, reject) => {
+      const gitPath = resolveGitPath(env, cwd, platform)
+      if (!gitPath) {
+        const err = new Error('spawn git ENOENT')
+        err.code = 'ENOENT'
+        reject(err)
+        return
+      }
+      let child
+      try {
+        child = spawn(gitPath, args, { cwd, env, shell: false })
+      } catch (err) {
+        reject(err)
+        return
+      }
+      // stderr is always decoded as text (a multibyte UTF-8 character can land split across two
+      // `data` events; `setEncoding` buffers an incomplete trailing sequence until the rest
+      // arrives, decoding each chunk on its own would mangle it). stdout does the same UNLESS
+      // `binary` asks for the raw bytes instead, accumulated as `Buffer` chunks and concatenated
+      // once on `close` -- never `setEncoding('utf8')`, which would already have thrown away the
+      // original bytes by the time `close` fires.
+      child.stderr.setEncoding('utf8')
+      let stderr = ''
+      child.stderr.on('data', (chunk) => {
+        stderr += chunk
+      })
+      if (binary) {
+        const stdoutChunks = []
+        child.stdout.on('data', (chunk) => stdoutChunks.push(chunk))
+        child.on('error', (err) => reject(err))
+        child.on('close', (code) => resolvePromise({ code, stdout: Buffer.concat(stdoutChunks), stderr }))
+        return
+      }
+      child.stdout.setEncoding('utf8')
+      let stdout = ''
+      child.stdout.on('data', (chunk) => {
+        stdout += chunk
+      })
+      child.on('error', (err) => reject(err))
+      child.on('close', (code) => resolvePromise({ code, stdout, stderr }))
+    })
+  }
+}

package/src/git-steps.mjs

@@ -0,0 +1,148 @@
+// Git steps (traceability.md "Git steps", G0-G4): turns the configured range into a git
+// repository on `main` with exactly one commit, isolated from the teacher's global git
+// configuration. `runGitSteps` runs G0-G4 in order and classifies any failure into one of
+// CW-W01 (G0), CW-W02 (G3: no identity) or CW-W03 (any other command failure).
+
+import { buildGitEnv } from './git-env.mjs'
+import { parseGitVersion, isGitVersionOk } from './git-version.mjs'
+
+const CONFIG_GLOBAL_NAME = 'git config --global user.name "<your name>"'
+const CONFIG_GLOBAL_EMAIL = 'git config --global user.email "<you@example.com>"'
+
+/** The printed forms of G1, G2 and G4 (traceability.md "Git steps", "Printed form" column), the
+ * one source `cwE12FinishingCommands` (messages.mjs) also builds from (S-09). */
+export function printedForms(version) {
+  return {
+    init: 'git init',
+    symbolicRef: 'git symbolic-ref HEAD refs/heads/main',
+    add: 'git add -A',
+    commit: `git commit -m "Create range from WXL ${version}"`,
+  }
+}
+
+/** S-20: `printedForms`' own G1/G2/G4 lines, in Step order (the one array this module's own
+ * `orderedForms` and CW-W05's step-12 window -- run.mjs -- both need; a signal before step 12's
+ * G0 ever ran means none of them have). */
+export function orderedPrintedForms(version) {
+  const forms = printedForms(version)
+  return [forms.init, forms.symbolicRef, forms.add, forms.commit]
+}
+
+/** Runs `run(args)`, turning a rejection into the same shape a resolved call has (`threw: true`
+ * instead of a `code`), so every call site classifies both the same way. */
+async function attempt(run, args) {
+  try {
+    const result = await run(args)
+    return { threw: false, code: result.code, stdout: result.stdout ?? '', stderr: result.stderr ?? '' }
+  } catch (err) {
+    return { threw: true, error: err }
+  }
+}
+
+/** The text CW-W03 and N2 print for a command's failure: its stderr when it ran (even empty), or
+ * the rejection's own message when it never returned at all. */
+function detailOf(result) {
+  return result.threw ? (result.error?.message ?? String(result.error)) : result.stderr
+}
+
+/** G3's own rule (traceability.md "Git steps" and the revision 2.1 self-check "G3's exit 1 is
+ * CW-W02, not CW-W03"): exit 1, or exit 0 with empty output, is "no identity" (CW-W02); a
+ * rejection or any other exit code (e.g. 128, "fatal: bad config") is CW-W03 ("error"). */
+function classifyConfigGet(result) {
+  if (result.threw) return 'error'
+  if (result.code === 1) return 'missing'
+  if (result.code === 0 && result.stdout.trim() === '') return 'missing'
+  if (result.code === 0) return 'ok'
+  return 'error'
+}
+
+/**
+ * Runs G0-G4 in order through `runGit(args, { cwd, env })` with `buildGitEnv(env)`. Returns
+ * `{ warningId: null }` on success, or one of:
+ * - `{ warningId: 'CW-W01', remainingCommands }` (G0 rejected, exited non-zero, or reported an
+ *   unparsable or too-old version)
+ * - `{ warningId: 'CW-W02', remainingCommands }` (G3: no explicit committer identity)
+ * - `{ warningId: 'CW-W03', command, detail, remainingCommands }` (any other git command failure,
+ *   decision 4: a G1-G4 rejection is always CW-W03, never CW-W01)
+ * `remainingCommands` are the printed forms (traceability.md "Git steps") still to run, in order;
+ * for CW-W02 the two `git config --global` commands come first.
+ */
+export async function runGitSteps({ runGit, cwd, env: rawEnv, version, shouldStop }) {
+  const env = buildGitEnv(rawEnv)
+  const run = (args) => runGit(args, { cwd, env })
+  const forms = printedForms(version)
+  const orderedForms = orderedPrintedForms(version)
+  const isSignaled = shouldStop ?? (() => false)
+
+  const versionResult = await attempt(run, ['--version'])
+  if (isSignaled()) return { signal: true, remainingCommands: orderedForms }
+  if (versionResult.threw || versionResult.code !== 0 || !isGitVersionOk(parseGitVersion(versionResult.stdout))) {
+    return { warningId: 'CW-W01', remainingCommands: orderedForms }
+  }
+
+  const mainArgs = [
+    ['init', '--template='],
+    ['symbolic-ref', 'HEAD', 'refs/heads/main'],
+    ['-c', 'core.excludesFile=', 'add', '-A', '--force'],
+  ]
+  for (let i = 0; i < mainArgs.length; i++) {
+    const result = await attempt(run, mainArgs[i])
+    // C-13/P-22: a command that already succeeded is not "not run", even when a signal arrives
+    // right after it -- checked first, so CW-W05 never lists a command this run already did.
+    if (!result.threw && result.code === 0) {
+      if (isSignaled()) return { signal: true, remainingCommands: orderedForms.slice(i + 1) }
+      continue
+    }
+    // traceability.md "Signals": "a git command that exits non-zero after a signal counts as the
+    // signal, not as CW-W03" -- checked before the failure classification below, so a command this
+    // run's own injected signal made fail is never misreported as a `runGit` failure.
+    if (isSignaled()) return { signal: true, remainingCommands: orderedForms.slice(i) }
+    return { warningId: 'CW-W03', command: orderedForms[i], detail: detailOf(result), remainingCommands: orderedForms.slice(i) }
+  }
+
+  const nameResult = await attempt(run, ['config', '--get', 'user.name'])
+  if (isSignaled()) return { signal: true, remainingCommands: [forms.commit] }
+  const nameClass = classifyConfigGet(nameResult)
+  if (nameClass === 'error') {
+    return {
+      warningId: 'CW-W03',
+      command: 'git config --get user.name',
+      detail: detailOf(nameResult),
+      remainingCommands: [forms.commit],
+    }
+  }
+  const emailResult = await attempt(run, ['config', '--get', 'user.email'])
+  if (isSignaled()) return { signal: true, remainingCommands: [forms.commit] }
+  const emailClass = classifyConfigGet(emailResult)
+  if (emailClass === 'error') {
+    return {
+      warningId: 'CW-W03',
+      command: 'git config --get user.email',
+      detail: detailOf(emailResult),
+      remainingCommands: [forms.commit],
+    }
+  }
+  if (nameClass === 'missing' || emailClass === 'missing') {
+    return { warningId: 'CW-W02', remainingCommands: [CONFIG_GLOBAL_NAME, CONFIG_GLOBAL_EMAIL, forms.commit] }
+  }
+
+  const commitResult = await attempt(run, [
+    '-c',
+    'user.useConfigOnly=true',
+    '-c',
+    'commit.gpgsign=false',
+    '-c',
+    'core.hooksPath=',
+    'commit',
+    '--no-verify',
+    '-m',
+    `Create range from WXL ${version}`,
+  ])
+  // C-13/P-22: G4 already succeeded is not "not run" either -- the range is complete.
+  if (!commitResult.threw && commitResult.code === 0) {
+    if (isSignaled()) return { signal: true, remainingCommands: [] }
+    return { warningId: null }
+  }
+  if (isSignaled()) return { signal: true, remainingCommands: [forms.commit] }
+  return { warningId: 'CW-W03', command: forms.commit, detail: detailOf(commitResult), remainingCommands: [forms.commit] }
+}

package/src/git-version.mjs

@@ -0,0 +1,27 @@
+// G0 (traceability.md "Git steps"): `git --version` must report 2.26 or later (0006's D21, 0005
+// revision 2.3: before 2.26 git runs `core.fsmonitor=true` as a hook and may report no changes, and
+// before 2.25.2 `git check-ignore` ignores `!` re-inclusions). `git --version`'s
+// own output is `git version <major>.<minor>.<patch>[<anything>]` (a Homebrew/Xcode suffix like
+// `(Apple Git-154)`, or a Windows suffix like `.windows.1`); only the leading `\d+\.\d+(\.\d+)?` is
+// read, compared with `numeric-version.mjs`'s shared helper (S-11) so `2.9.5` is not mistaken
+// for newer than `2.26.0`.
+
+import { isAtLeast } from './numeric-version.mjs'
+
+export const MINIMUM_GIT_VERSION = [2, 26]
+
+const VERSION_PREFIX_RE = /^git version (\d+)\.(\d+)(?:\.(\d+))?/
+
+/** Returns `[major, minor, patch]` (patch 0 when absent), or `null` when `stdout` does not start
+ * with a recognisable `git version <N>.<N>` prefix. */
+export function parseGitVersion(stdout) {
+  const match = VERSION_PREFIX_RE.exec(String(stdout))
+  if (!match) return null
+  return [Number(match[1]), Number(match[2]), Number(match[3] ?? '0')]
+}
+
+/** `parsed`: `parseGitVersion`'s result. `null` (unparsable) is never ok. */
+export function isGitVersionOk(parsed, minimum = MINIMUM_GIT_VERSION) {
+  if (parsed === null) return false
+  return isAtLeast(parsed, minimum)
+}

package/src/language.mjs

@@ -0,0 +1,14 @@
+// "Language" (traceability.md): `--lang` if given and valid; otherwise the first of `LC_ALL`,
+// `LC_MESSAGES`, `LANG` in `deps.env` that is set and non-empty; otherwise `deps.locale`. CW-E01
+// and CW-E02 use the environment rule only (they happen before or during parsing): callers pass no
+// `explicitLang` for those. Every message after argv has parsed passes `parsed.lang` here.
+
+export function selectLanguage(deps, explicitLang) {
+  if (explicitLang === 'en' || explicitLang === 'zh-TW') return explicitLang
+  const candidates = [deps.env?.LC_ALL, deps.env?.LC_MESSAGES, deps.env?.LANG]
+  for (const candidate of candidates) {
+    if (candidate) return /^zh/i.test(candidate) ? 'zh-TW' : 'en'
+  }
+  const locale = deps.locale ?? ''
+  return /^zh/i.test(locale) ? 'zh-TW' : 'en'
+}

package/src/merge-apply.mjs

@@ -0,0 +1,156 @@
+// Step 9 (traceability.md "Step order" row 9): deletions first, then writes, in sorted path
+// order; each write goes to a new file in the destination directory, then renamed over the
+// destination, creating any missing parent directory first. traceability.md "Merge table" M5: a
+// brand-new path takes `op.newFileExecutable`'s own bit (under the process's own umask, through
+// the ordinary `writeFile` mode option); an existing path keeps ITS OWN current mode --
+// write-then-rename always creates a new inode, so that mode is never carried forward for free,
+// hence the explicit `lstat`-then-`chmod` here (T-0027 increment 7). T-0027 increment 10 (U27):
+// a real file-system error on any delete or write is reported as `{ ok: false, path, detail }`
+// instead of propagating as a bug (CW-E14); the half-written temp file, if any, is unlinked
+// first. T-0027 increment 11 (U28): `guard` is checked after every successful operation (delete
+// or write) -- traceability.md "Codes" UP-E09: a signal already raised there stops the loop
+// before the next operation starts and before `range.json` is ever rewritten, reported as
+// `{ ok: false, signal }`.
+
+import { randomBytes } from 'node:crypto'
+import { dirname, join } from 'node:path'
+
+/** A dotfile alongside the destination, inside the same directory (so the final `rename` is
+ * same-device): `.create-wxl-upgrade-tmp-<16 random hex chars>`, a FIXED LENGTH never growing
+ * with the destination's own basename -- a brand-new path whose own basename is already close to
+ * `NAME_MAX` must not fail with `ENAMETOOLONG` only because of space this temporary name added on
+ * top of it. The random part alone still keeps every concurrent write
+ * (in the same destination directory, in the same run) its own temporary name; a FIXED name with
+ * no random part at all could already exist -- an ignored file the teacher has, or a symbolic
+ * link -- and the write loop's own `writeFile`, below, uses `flag: 'wx'` (never the default
+ * `'w'`) so it refuses to create over whatever that existing name turns out to be, instead of
+ * silently truncating it or following a symlink through it. */
+function tempPathFor(rangeRoot, path) {
+  const parts = path.split('/')
+  const last = parts.pop()
+  const dest = join(rangeRoot, ...parts, last)
+  const tmp = join(rangeRoot, ...parts, `.create-wxl-upgrade-tmp-${randomBytes(8).toString('hex')}`)
+  return { dest, tmp }
+}
+
+/** `range.json` after the plan (traceability.md "`range.json` after the plan", T-0027 increment
+ * 8): read the current file (or start from `{}`), replace `upstream`'s value with `upstream`
+ * (keeping every other top-level key and the order of keys -- `upstream` keeps its own position,
+ * or is first when added), two-space indent, one trailing LF. */
+function buildRangeJson(current, upstream) {
+  if (Object.prototype.hasOwnProperty.call(current, 'upstream')) {
+    const next = {}
+    // R-6 (T-0063): define each key as the object's own, as `JSON.parse` did -- a plain assignment
+    // of a `__proto__` key would set `next`'s prototype instead, and the key would be lost.
+    for (const key of Object.keys(current)) {
+      Object.defineProperty(next, key, {
+        value: key === 'upstream' ? upstream : current[key],
+        enumerable: true,
+        writable: true,
+        configurable: true,
+      })
+    }
+    return next
+  }
+  return { upstream, ...current }
+}
+
+/** `range.json`'s own write (the last of step 9) goes through the
+ * same write-then-rename, file-system-error-vs-bug and signal handling as every other write in
+ * the loop below -- a failure here has already deleted/written every other op, so the range may
+ * be partially changed exactly the same way, and needs the same `UP-E09` + restore commands,
+ * not `CW-E14`. Returns `{ ok: true }`, or `{ ok: false, path: 'range.json', detail }` / `{ ok:
+ * false, signal }`, mirroring the write loop's own return shape. */
+async function writeRangeJson(deps, guard, rangeRoot, upstream) {
+  const { dest: path, tmp } = tempPathFor(rangeRoot, 'range.json')
+  try {
+    let current = {}
+    try {
+      current = JSON.parse(await deps.fs.readFile(path, 'utf8'))
+    } catch (err) {
+      if (err?.code !== 'ENOENT') throw err
+    }
+    await deps.fs.writeFile(tmp, JSON.stringify(buildRangeJson(current, upstream), null, 2) + '\n', { flag: 'wx' })
+    if (guard.isRaised()) {
+      try {
+        await deps.fs.unlink(tmp)
+      } catch {
+        // Never created, or already gone -- either way, nothing left to clean up.
+      }
+      return { ok: false, signal: guard.raised() }
+    }
+    await deps.fs.rename(tmp, path)
+  } catch (err) {
+    try {
+      await deps.fs.unlink(tmp)
+    } catch {
+      // Never created, or already gone -- either way, nothing left to clean up.
+    }
+    return { ok: false, path: 'range.json', detail: err.message }
+  }
+  if (guard.isRaised()) return { ok: false, signal: guard.raised() }
+  return { ok: true }
+}
+
+/** `applyMerge({ deps, guard, rangeRoot, ops, upstream })` -> `{ ok: true }` on success, or
+ * `{ ok: false, path, detail }` (a file-system error at that path) / `{ ok: false, signal }` (a
+ * signal raised mid-apply, U28) otherwise -- the caller (`upgrade.mjs`) turns either into
+ * `UP-E09` and exit 1 / 130. `ops` is `planMerge`'s own sorted array; this function re-sorts
+ * defensively so a caller's own ordering is never relied on by accident. `upstream` (T-0027
+ * increment 8) is `range.json`'s own `upstream` value after the run: `{ repository, version,
+ * commit }` of the target, written last (after every deletion/write), the same write-then-rename
+ * path -- never reached when a delete/write already failed or a signal already stopped the loop,
+ * so an incomplete apply is never recorded as done (U24's deferred sub-case). */
+export async function applyMerge({ deps, guard, rangeRoot, ops, upstream }) {
+  const deletes = ops.filter((op) => op.action === 'delete').sort((a, b) => (a.path < b.path ? -1 : 1))
+  const writes = ops.filter((op) => op.action === 'write').sort((a, b) => (a.path < b.path ? -1 : 1))
+
+  for (const op of deletes) {
+    const { dest } = tempPathFor(rangeRoot, op.path)
+    try {
+      await deps.fs.unlink(dest)
+    } catch (err) {
+      return { ok: false, path: op.path, detail: err.message }
+    }
+    if (guard.isRaised()) return { ok: false, signal: guard.raised() }
+  }
+
+  for (const op of writes) {
+    const { dest, tmp } = tempPathFor(rangeRoot, op.path)
+    try {
+      await deps.fs.mkdir(dirname(dest), { recursive: true })
+
+      let existingMode
+      if (op.existedBefore) {
+        try {
+          existingMode = (await deps.fs.lstat(dest)).mode & 0o777
+        } catch (err) {
+          // Only ENOENT (gone by some other means -- nothing to preserve) is read as absent;
+          // any other error (e.g. EACCES) is a planning failure, not evidence of absence --
+          // fail closed, the same convention every other pre-check's own `lstat` already uses.
+          // Rethrown here, this reaches the write loop's own catch, below, which reports it as
+          // `UP-E09` with the restore commands, the same as any other failed write.
+          if (err?.code !== 'ENOENT') throw err
+          existingMode = undefined
+        }
+      }
+
+      const writeOptions = { flag: 'wx' }
+      if (!op.existedBefore && op.newFileExecutable) writeOptions.mode = 0o755
+      await deps.fs.writeFile(tmp, op.content, writeOptions)
+      if (existingMode !== undefined) await deps.fs.chmod(tmp, existingMode)
+      await deps.fs.rename(tmp, dest)
+    } catch (err) {
+      // The half-written temp file never survives a failed write.
+      try {
+        await deps.fs.unlink(tmp)
+      } catch {
+        // Never created, or already gone -- either way, nothing left to clean up.
+      }
+      return { ok: false, path: op.path, detail: err.message }
+    }
+    if (guard.isRaised()) return { ok: false, signal: guard.raised() }
+  }
+
+  return await writeRangeJson(deps, guard, rangeRoot, upstream)
+}