trackfw 6.10.0 → 7.1.0

package/src/ship/runner.js

@@ -8,11 +8,11 @@
  */
 
 const { spawnSync } = require('child_process')
-const fs = require('fs')
-const path = require('path')
 const { load: loadConfig, reset: resetConfig } = require('../config')
 const { resolve: forgeResolve } = require('../forge/resolve')
 const { forgeAdapter } = require('../forge/adapter')
+const validator = require('../validator')
+const { evaluateBranchIntegration, DECISION: BRANCH_PRUNE_DECISION } = require('../branch/prune')
 
 // Git subcommands that modify local or remote state.
 // In --dry-run mode these are printed but not executed.
@@ -28,11 +28,26 @@ function isGitWriteCmd(args) {
 }
 
 /**
- * isShipBranch returns true when branch matches feat|fix|refactor/<slug>.
+ * isShipBranch returns true when branch matches feat|fix|refactor|chore|docs/<slug> — the full
+ * vocabulary `trackfw ship` accepts on the branch name. feat/fix/refactor are gated on Step 2's
+ * branch_has_wip_roadmap governance check (a hard gate not affected by lenient mode); chore/docs
+ * are housekeeping types — already exempted from that gate by `trackfw branch new` and
+ * `trackfw commit` — and ship without it too.
  * @param {string} branch
  * @returns {boolean}
  */
 function isShipBranch(branch) {
+  return /^(feat|fix|refactor|chore|docs)\/.+/.test(branch)
+}
+
+/**
+ * isGatedShipBranch returns true when branch matches feat|fix|refactor/<slug> — the subset of
+ * isShipBranch's vocabulary that requires Step 2's branch_has_wip_roadmap governance check.
+ * chore/docs branches satisfy isShipBranch but return false here.
+ * @param {string} branch
+ * @returns {boolean}
+ */
+function isGatedShipBranch(branch) {
   return /^(feat|fix|refactor)\/.+/.test(branch)
 }
 
@@ -62,64 +77,25 @@ function defaultCheckGovernance() {
 
 /**
  * checkShipGovernance — hard gate (bypasses config/baseline/lenient).
- * Checks:
- *   1. Current branch has a matching roadmap in wip/
- *   2. WIP roadmaps have a linked REQ
+ *
+ * Delegates entirely to the shared validator functions already used by `trackfw validate`,
+ * `trackfw branch new` and `trackfw commit` — never reimplement this logic locally. Byte-
+ * identical to Go's CheckShipGovernance (internal/validator/validator.go), which has the same
+ * no-args shape and the same two checks:
+ *   1. validateBranchHasWIPRoadmap — current branch (feat/fix/refactor only; re-derived
+ *      internally from TRACKFW_BRANCH/git, same as Go) has a matching roadmap in wip/ OR done/
+ *   2. validateWIPHasREQ — every roadmap in wip/ has a linked REQ
+ * Before this ML, this function reimplemented both checks locally with its own wording (no
+ * "nor done/" clause, no done/ directory scan at all) — see
+ * vault/notes/ship-checkgovernance-error-stream-wording-divergence-2026-08-16.md. Duplicating
+ * the check was the actual root cause of the drift, not just the wording.
  * @returns {string[]} violation messages
  */
 function checkShipGovernance() {
-  const violations = []
-
-  // Resolve roadmap dir via config module (single source of truth; default: docs/roadmaps)
-  const roadmapDir = resolveRoadmapDir()
-  const wipDir = path.join(roadmapDir, 'wip')
-
-  // Get branch name
-  const branchResult = defaultExecGit(['symbolic-ref', '--short', 'HEAD'])
-  const branch = branchResult.error ? '' : branchResult.stdout.trim()
-
-  // Check branch has matching roadmap in wip/
-  if (branch && isShipBranch(branch)) {
-    const slug = normalizeBranchSlug(branch.split('/').slice(1).join('/'))
-    let hasMatch = false
-    let wipFiles = []
-
-    if (fs.existsSync(wipDir)) {
-      wipFiles = fs.readdirSync(wipDir).filter(f => f.endsWith('.md'))
-      for (const f of wipFiles) {
-        if (normalizeBranchSlug(f).includes(slug)) {
-          hasMatch = true
-          break
-        }
-      }
-    }
-
-    if (wipFiles.length === 0) {
-      violations.push(
-        `branch "${branch}" is a feat/fix/refactor branch but no roadmap is in wip/ — create governance artifacts first:\n` +
-        '  trackfw req new "<title>"\n' +
-        '  trackfw roadmap new "<title>"\n' +
-        '  trackfw roadmap move <name> wip'
-      )
-    } else if (!hasMatch) {
-      violations.push(
-        `branch "${branch}" has no matching roadmap in wip/ (found: ${wipFiles.join(', ')}) — ` +
-        'include the branch slug in the roadmap filename'
-      )
-    }
-
-    // Check WIP roadmaps have a linked REQ
-    if (hasMatch && fs.existsSync(wipDir)) {
-      for (const f of wipFiles) {
-        const content = fs.readFileSync(path.join(wipDir, f), 'utf8')
-        if (!content.includes('REQ:') && !content.includes('req:')) {
-          violations.push(`roadmap "${f}" is in wip but has no linked REQ`)
-        }
-      }
-    }
-  }
-
-  return violations
+  return [
+    ...validator.validateBranchHasWIPRoadmap(),
+    ...validator.validateWIPHasREQ(),
+  ]
 }
 
 /**
@@ -155,8 +131,17 @@ function normalizeBranchSlug(value) {
 }
 
 /**
- * detectPendingSquashMerges warns about remote branches with non-empty diffs vs origin/main.
- * Non-blocking.
+ * detectPendingSquashMerges warns about remote branches with genuinely pending work vs
+ * origin/main. Non-blocking.
+ *
+ * Reuses evaluateBranchIntegration (branch/prune.js) — the same touched-files heuristic
+ * `trackfw branch prune` uses — instead of a naive bidirectional `git diff origin/main <branch>
+ * --stat`. The naive check false-positives on a branch that was squash-merged and is now merely
+ * stale (main advanced further afterwards): it always shows a non-empty diff even though nothing
+ * from the branch is actually missing from main. Only DECISION.PENDING_WORK — genuine,
+ * unintegrated work — surfaces this warning; every other decision (no_own_work,
+ * content_identical, review_doc_config, no_merge_base, eval_error) stays silent, the same
+ * posture the naive check had on error (skip, no warning).
  * @param {string} currentBranch
  * @param {function} execGit
  * @param {function} writeln
@@ -171,9 +156,8 @@ function detectPendingSquashMerges(currentBranch, execGit, writeln) {
     const shortName = candidate.replace(/^origin\//, '')
     if (shortName === currentBranch) continue
 
-    const { stdout: diff, error: derr } = execGit(['diff', 'origin/main', candidate, '--stat'])
-    if (derr) continue
-    if (diff.trim()) {
+    const evalResult = evaluateBranchIntegration(candidate, execGit)
+    if (evalResult.decision === BRANCH_PRUNE_DECISION.PENDING_WORK) {
       writeln(`Warning: branch "${shortName}" appears to have unmerged changes vs origin/main.`)
     }
   }
@@ -217,6 +201,137 @@ function firstLine(s) {
   return idx >= 0 ? s.slice(0, idx) : s
 }
 
+/**
+ * splitNonEmptyLines splits git output (e.g. `diff --cached --name-only`) into an array
+ * of trimmed, non-empty lines.
+ * @param {string} s
+ * @returns {string[]}
+ */
+function splitNonEmptyLines(s) {
+  const trimmed = (s || '').trim()
+  if (!trimmed) return []
+  return trimmed
+    .split('\n')
+    .map((line) => line.trim())
+    .filter((line) => line !== '')
+}
+
+/**
+ * allDocOnly returns true when there is at least one staged file and every staged file is
+ * doc-only: under docs/ or vault/ (path prefix), or has a .md extension. A single file
+ * outside that criterion makes it return false. Mirrors the doc-only exception documented
+ * in CLAUDE.md §7 ("Alteração doc-only (markdown, comentários)").
+ * @param {string[]} files
+ * @returns {boolean}
+ */
+function allDocOnly(files) {
+  if (!files || files.length === 0) return false
+  for (const f of files) {
+    if (f.startsWith('docs/') || f.startsWith('vault/') || f.endsWith('.md')) continue
+    return false
+  }
+  return true
+}
+
+/**
+ * commitMessageSep delimits full commit messages (%B) in the output of gitCommitsSince's
+ * `git log --format=%B<sep>`. Same non-printable separator used by the Go implementation
+ * (internal/commands/ship.go) — cannot appear in a real commit message.
+ */
+const COMMIT_MESSAGE_SEP = '\x1e'
+
+/**
+ * defaultBaseBranch resolves the repository's default branch for `git log <base>..HEAD`.
+ * Tries `git symbolic-ref refs/remotes/origin/HEAD` (format "refs/remotes/origin/main" —
+ * only the name after the last slash is kept) and falls back to "main" when that fails or
+ * yields nothing.
+ * @param {function} execGit
+ * @returns {string}
+ */
+function defaultBaseBranch(execGit) {
+  const { stdout, error } = execGit(['symbolic-ref', 'refs/remotes/origin/HEAD'])
+  if (error) return 'main'
+  const out = (stdout || '').trim()
+  const idx = out.lastIndexOf('/')
+  if (idx < 0 || idx + 1 >= out.length) return 'main'
+  return out.slice(idx + 1)
+}
+
+/**
+ * gitCommitsSince returns the full message (subject + body) of every non-merge commit in
+ * base..HEAD, most-recent-first (git log's natural order). Returns [] on any git error or
+ * when the range is empty.
+ * @param {string} base
+ * @param {function} execGit
+ * @returns {string[]}
+ */
+function gitCommitsSince(base, execGit) {
+  const { stdout, error } = execGit(['log', `${base}..HEAD`, '--no-merges', `--format=%B${COMMIT_MESSAGE_SEP}`])
+  if (error) return []
+  const out = (stdout || '').trim()
+  if (!out) return []
+  const parts = out.split(COMMIT_MESSAGE_SEP)
+  const commits = []
+  for (let p of parts) {
+    p = p.replace(/^\n+|\n+$/g, '')
+    if (p.trim() === '') continue
+    commits.push(p)
+  }
+  return commits
+}
+
+/**
+ * buildPRBody constructs the PR/MR body. With 0 or 1 non-merge commit on the branch (the
+ * trivial case — just the commit `ship` itself made), it keeps the original minimal body,
+ * not a regression. With 2+ commits, it aggregates the branch's commit history:
+ *
+ *   ## Commits
+ *   - <subject of commit 1>
+ *   - <subject of commit 2>
+ *
+ *   ## Detalhes
+ *   <full body of each commit that has one, in blocks>
+ *
+ *   ---
+ *   Branch: <branch>
+ *
+ * @param {string} branch
+ * @param {string[]} commits
+ * @returns {string}
+ */
+function buildPRBody(branch, commits) {
+  if (!commits || commits.length <= 1) {
+    return `Branch: ${branch}\n\nCreated by trackfw ship.`
+  }
+
+  const subjects = []
+  const details = []
+  for (const c of commits) {
+    const nlIdx = c.indexOf('\n')
+    const subject = (nlIdx >= 0 ? c.slice(0, nlIdx) : c).trim()
+    if (subject === '') continue
+    subjects.push(subject)
+    if (nlIdx >= 0) {
+      const bodyText = c.slice(nlIdx + 1).trim()
+      if (bodyText !== '') {
+        details.push(`**${subject}**\n\n${bodyText}`)
+      }
+    }
+  }
+
+  let b = '## Commits\n\n'
+  for (const s of subjects) {
+    b += `- ${s}\n`
+  }
+  if (details.length > 0) {
+    b += '\n## Detalhes\n\n'
+    b += details.join('\n\n')
+    b += '\n'
+  }
+  b += `\n---\nBranch: ${branch}\n`
+  return b
+}
+
 /**
  * buildForgeCreateArgs appends --title and --body (or --description for azure)
  * to a copy of adapter.cliArgs. Never mutates the original array.
@@ -248,6 +363,15 @@ function runShip(opts, deps = {}) {
   const execGit = deps.execGit || defaultExecGit
   const checkGovernanceFn = deps.checkGovernance || defaultCheckGovernance
   const writeln = deps.writeln || ((s) => process.stdout.write(s + '\n'))
+  // writeErr — the terminal error line for every abort path below, written to STDERR with the
+  // "Error: " prefix. Mirrors Go exactly: ship.go returns these same messages as a bare
+  // fmt.Errorf(...), and internal/commands/root.go's Execute() wrapper prints them to stderr as
+  // `fmt.Fprintln(os.Stderr, cmd.ErrPrefix(), err.Error())` — cmd.ErrPrefix() is "Error:", and
+  // Fprintln inserts exactly one space between operands, so the wire format is
+  // "Error: <message>\n". Every multi-line detail printed BEFORE the abort (violation lists,
+  // remediation hints, "Note: ..." blocks) stays on stdout via writeln, same as Go's deps.out —
+  // only this final one-line (or one-block) summary moves to stderr.
+  const writeErr = deps.writeErr || ((s) => process.stderr.write(`Error: ${s}\n`))
 
   // Inner git wrapper: skips write commands in dry-run mode.
   function git(args) {
@@ -258,22 +382,30 @@ function runShip(opts, deps = {}) {
     return execGit(args)
   }
 
+  // ─── Step 0: staged files ───────────────────────────────────────────────────
+  // Read once, up front, so Steps 1 and 2 can grant a doc-only exception before they run —
+  // and so Step 4 below reuses the same read instead of querying git twice.
+  const { stdout: stagedOut } = execGit(['diff', '--cached', '--name-only'])
+  const stagedFiles = splitNonEmptyLines(stagedOut)
+  const docOnly = allDocOnly(stagedFiles)
+
   // ─── Step 1: Branch validation ─────────────────────────────────────────────
   const branchResult = execGit(['symbolic-ref', '--short', 'HEAD'])
   if (branchResult.error) {
-    writeln(`error: could not determine current branch (are you in a git repo?): ${branchResult.error.message}`)
+    writeErr(`could not determine current branch (are you in a git repo?): ${branchResult.error.message}`)
     return 1
   }
   const branch = branchResult.stdout.trim()
 
+  // main/master is blocked unconditionally — the doc-only exception never applies here.
   if (branch === 'main' || branch === 'master') {
-    writeln(`error: trackfw ship cannot run on "${branch}" — use a feature branch:\n  git checkout -b feat/<slug>`)
+    writeErr(`trackfw ship cannot run on "${branch}" — use a feature branch:\n  git checkout -b feat/<slug>`)
     return 1
   }
 
-  if (!isShipBranch(branch)) {
-    writeln(
-      `error: branch "${branch}" does not match the required pattern feat|fix|refactor/<slug>\n` +
+  if (!docOnly && !isShipBranch(branch)) {
+    writeErr(
+      `branch "${branch}" does not match the required pattern feat|fix|refactor|chore|docs/<slug>\n` +
       'Rename your branch or create a new one:\n  git checkout -b feat/<slug>'
     )
     return 1
@@ -282,25 +414,35 @@ function runShip(opts, deps = {}) {
   writeln(`Branch: ${branch}`)
 
   // ─── Step 2: Governance ────────────────────────────────────────────────────
-  const violations = checkGovernanceFn()
-  if (violations.length > 0) {
-    writeln('\nGovernance check failed:')
-    for (const v of violations) {
-      writeln(`  ${v}`)
+  // Doc-only changes (all staged files under docs/, vault/, or *.md) are exempt from
+  // REQ+roadmap governance — mirrors the CLAUDE.md §7 exception for doc-only changes.
+  if (docOnly) {
+    writeln('Governance: skipped (doc-only change)')
+  } else if (isShipBranch(branch) && !isGatedShipBranch(branch)) {
+    // chore/docs: housekeeping types already exempted from this gate by
+    // `trackfw branch new` and `trackfw commit` — ship without it too.
+    writeln('Governance: skipped (chore/docs branch)')
+  } else {
+    const violations = checkGovernanceFn()
+    if (violations.length > 0) {
+      writeln('\nGovernance check failed:')
+      for (const v of violations) {
+        writeln(`  ${v}`)
+      }
+      writeln('\nCreate the required artifacts before running ship:')
+      writeln('  trackfw req new "<title>"')
+      writeln('  trackfw roadmap new "<title>"')
+      writeln('  trackfw roadmap move <name> wip')
+      writeln("\nNote: this governance check is a hard gate — it is not affected by lenient")
+      writeln("mode or per-rule severity configured in trackfw.yaml. If 'trackfw validate'")
+      writeln("passes but 'trackfw ship' aborts here, you likely have lenient mode")
+      writeln("configured — ship always requires REQ + roadmap in wip/.")
+      writeErr(`governance check failed: ${violations.length} violation(s)`)
+      return 1
     }
-    writeln('\nCreate the required artifacts before running ship:')
-    writeln('  trackfw req new "<title>"')
-    writeln('  trackfw roadmap new "<title>"')
-    writeln('  trackfw roadmap move <name> wip')
-    writeln("\nNote: this governance check is a hard gate — it is not affected by lenient")
-    writeln("mode or per-rule severity configured in trackfw.yaml. If 'trackfw validate'")
-    writeln("passes but 'trackfw ship' aborts here, you likely have lenient mode")
-    writeln("configured — ship always requires REQ + roadmap in wip/.")
-    writeln(`\nerror: governance check failed: ${violations.length} violation(s)`)
-    return 1
-  }
 
-  writeln('Governance: OK')
+    writeln('Governance: OK')
+  }
 
   // ─── Step 3: Squash-merge detection ────────────────────────────────────────
   if (opts.dryRun) {
@@ -323,10 +465,10 @@ function runShip(opts, deps = {}) {
   if (diffStatOut) writeln(diffStatOut)
   writeln('────────────────────────────────────────────────────────\n')
 
-  const { stdout: cachedFiles } = execGit(['diff', '--cached', '--name-only'])
-  if (!cachedFiles.trim()) {
-    writeln(
-      'error: nothing is staged — stage your files explicitly before running ship:\n' +
+  // Reuses stagedFiles read at the top of the function (Step 0) — never re-query git here.
+  if (stagedFiles.length === 0) {
+    writeErr(
+      'nothing is staged — stage your files explicitly before running ship:\n' +
       '  git add <file1> <file2> ...\n' +
       "Never use 'git add .' or 'git add -A'"
     )
@@ -335,8 +477,8 @@ function runShip(opts, deps = {}) {
 
   // ─── Step 5: Commit ────────────────────────────────────────────────────────
   if (!opts.message) {
-    writeln(
-      'error: commit message is required — use -m:\n' +
+    writeErr(
+      'commit message is required — use -m:\n' +
       '  trackfw ship -m "feat(<scope>): <description>"'
     )
     return 1
@@ -344,7 +486,7 @@ function runShip(opts, deps = {}) {
 
   const { error: commitErr } = git(['commit', '-m', opts.message])
   if (commitErr) {
-    writeln(`error: git commit failed: ${commitErr.message}`)
+    writeErr(`git commit failed: ${commitErr.message}`)
     return 1
   }
 
@@ -356,7 +498,7 @@ function runShip(opts, deps = {}) {
   const pushArgs = buildPushArgs(branch, execGit)
   const { error: pushErr } = git(pushArgs)
   if (pushErr) {
-    writeln(`error: git push failed: ${pushErr.message}`)
+    writeErr(`git push failed: ${pushErr.message}`)
     return 1
   }
 
@@ -391,7 +533,23 @@ function runShip(opts, deps = {}) {
     return 0
   }
 
+  // Title/body computed once for every remaining branch below (dry-run and real CLI
+  // invocation alike). git log/diff are read-only — they run in --dry-run mode too, same
+  // as the staged-files read in Step 0.
+  //
+  // Design decision (documented per roadmap ML-1A, mirrored from the Go implementation):
+  // the title is always firstLine(opts.message), the -m message passed to this very `ship`
+  // call, even when the branch carries multiple prior commits. Deriving a distinct "PR
+  // title" from N unrelated commit subjects would need a heuristic with no unambiguous
+  // answer — the simplest, least surprising rule is that -m is the PR's summary.
+  const base = defaultBaseBranch(execGit)
+  const commits = gitCommitsSince(base, execGit)
+  const title = firstLine(opts.message || '')
+  const body = buildPRBody(branch, commits)
+
   if (opts.dryRun) {
+    writeln(`[dry-run] Title: ${title}`)
+    writeln(`[dry-run] Body:\n${body}`)
     if (!adapter.available && resolution.forge !== 'manual') {
       const url = adapter.fallbackURL(remoteURL, branch)
       if (url) {
@@ -423,8 +581,6 @@ function runShip(opts, deps = {}) {
   }
 
   // CLI is available — invoke it.
-  const title = firstLine(opts.message || '')
-  const body = `Branch: ${branch}\n\nCreated by trackfw ship.`
   const cliArgs = buildForgeCreateArgs(adapter, title, body)
   const execForgeCLI = deps.execForgeCLI || defaultExecForgeCLI
   const cliErr = execForgeCLI(adapter.cliName, cliArgs)
@@ -443,6 +599,7 @@ function runShip(opts, deps = {}) {
 module.exports = {
   runShip,
   isShipBranch,
+  isGatedShipBranch,
   isGitWriteCmd,
   normalizeBranchSlug,
   checkShipGovernance,
@@ -451,4 +608,11 @@ module.exports = {
   GIT_WRITE_COMMANDS,
   buildForgeCreateArgs,
   firstLine,
+  allDocOnly,
+  splitNonEmptyLines,
+  defaultBaseBranch,
+  gitCommitsSince,
+  buildPRBody,
+  COMMIT_MESSAGE_SEP,
+  detectPendingSquashMerges,
 }

package/src/thirdparty/fetch.js

@@ -0,0 +1,140 @@
+'use strict'
+
+// Node port of internal/thirdparty/fetch.go — the network fetch primitive
+// used by the two-phase third-party artifact gate (skills/agents installed
+// from a URL). See:
+// docs/adr/ADR-2026-08-15-gate-de-duas-fases-para-artefatos-de-terceiro-quarentena-parecer-vinculado-por-checksum-e-deteccao-por-proveniencia-versionada.md
+// (D7).
+
+const https = require('node:https')
+const { URL } = require('node:url')
+
+// MAX_CONTENT_SIZE is the network fetch cap for third-party text artifacts
+// (D7): 2 MiB — mirrors internal/thirdparty/fetch.go:maxContentSize.
+const MAX_CONTENT_SIZE = 2 * 1024 * 1024
+
+// MAX_REDIRECTS mirrors internal/thirdparty/fetch.go:maxRedirects (3). Note
+// the Go reference's own net/http.Client.CheckRedirect semantics: the check
+// runs BEFORE following a redirect and compares the count of requests
+// ALREADY COMPLETED (via.length, which includes the request that just
+// returned the redirect) against maxRedirects — so in practice only
+// (maxRedirects - 1) redirects are ever followed before the next one is
+// refused. Reproduced here byte-for-byte via requestsCompleted, not
+// "fixed" to what the doc comment alone might suggest.
+const MAX_REDIRECTS = 3
+
+const TIMEOUT_MS = 30 * 1000
+
+// ALLOWED_CONTENT_TYPES mirrors internal/thirdparty/fetch.go:allowedContentTypes.
+const ALLOWED_CONTENT_TYPES = new Set(['text/plain', 'text/markdown', 'text/x-markdown'])
+
+// contentTypeAllowed mirrors internal/thirdparty/fetch.go:contentTypeAllowed
+// — tolerates an optional "; charset=..." (or any other parameter) suffix.
+function contentTypeAllowed(contentType) {
+  const raw = String(contentType || '')
+  const semi = raw.indexOf(';')
+  const base = (semi >= 0 ? raw.slice(0, semi) : raw).trim().toLowerCase()
+  return ALLOWED_CONTENT_TYPES.has(base)
+}
+
+// api is the module.exports object itself, referenced internally via
+// `api.requestOnce(...)` so tests can substitute the single HTTP round
+// trip without a real TLS socket — mirrors the thirdPartyFetch
+// package-var substitution pattern already used at the command layer
+// (npm/src/commands/thirdparty.js). Added in ML-4C to close a coverage
+// gap hefesto-tf found: the resp.statusCode !== 200 branch below existed
+// but was never exercised by any test.
+const api = {}
+
+function requestOnce(rawURL) {
+  return new Promise((resolve, reject) => {
+    const req = https.get(rawURL, { timeout: TIMEOUT_MS }, res => {
+      const chunks = []
+      let total = 0
+      let tooLarge = false
+      res.on('data', chunk => {
+        if (tooLarge) return
+        total += chunk.length
+        if (total > MAX_CONTENT_SIZE) {
+          tooLarge = true
+          res.destroy()
+          return
+        }
+        chunks.push(chunk)
+      })
+      res.on('end', () => {
+        resolve({ statusCode: res.statusCode, headers: res.headers, body: Buffer.concat(chunks), tooLarge })
+      })
+      res.on('error', err => reject(new Error(`failed to read response body: ${err.message}`)))
+    })
+    req.on('timeout', () => req.destroy(new Error('fetch failed: request timed out after 30s')))
+    req.on('error', err => reject(new Error(`fetch failed: ${err.message}`)))
+  })
+}
+
+// fetchOnce follows redirects with the same accounting as Go's
+// fetchClient.CheckRedirect (see MAX_REDIRECTS doc above). requestsCompleted
+// starts at 0 and is incremented after every completed HTTP request.
+async function fetchOnce(rawURL, requestsCompleted) {
+  let parsed
+  try {
+    parsed = new URL(rawURL)
+  } catch (err) {
+    throw new Error(`invalid URL "${rawURL}": ${err.message}`)
+  }
+  if (parsed.protocol !== 'https:') {
+    throw new Error(`refused: URL scheme must be https, got "${parsed.protocol.replace(/:$/, '')}"`)
+  }
+
+  const res = await api.requestOnce(rawURL)
+  requestsCompleted += 1
+
+  if (res.statusCode >= 300 && res.statusCode < 400 && res.headers.location) {
+    if (requestsCompleted >= MAX_REDIRECTS) {
+      throw new Error(`fetch failed: stopped after ${MAX_REDIRECTS} redirects`)
+    }
+    let next
+    try {
+      next = new URL(res.headers.location, rawURL).toString()
+    } catch (err) {
+      throw new Error(`invalid redirect location: ${err.message}`)
+    }
+    const nextScheme = new URL(next).protocol
+    if (nextScheme !== 'https:') {
+      throw new Error(`redirect to non-https URL refused: ${next}`)
+    }
+    return fetchOnce(next, requestsCompleted)
+  }
+
+  if (res.statusCode !== 200) {
+    throw new Error(`fetch failed: HTTP ${res.statusCode} for ${rawURL}`)
+  }
+
+  const contentType = res.headers['content-type']
+  if (!contentTypeAllowed(contentType)) {
+    throw new Error(`refused: unsupported Content-Type "${contentType || ''}" (allowed: text/plain, text/markdown, text/x-markdown)`)
+  }
+
+  if (res.tooLarge) {
+    throw new Error(`refused: content exceeds ${MAX_CONTENT_SIZE} bytes`)
+  }
+
+  return res.body
+}
+
+// fetch downloads the content at rawURL under the D7 network policy:
+// https-only (validated before the first request), a 30s timeout, at most
+// (MAX_REDIRECTS - 1) redirect hops (each revalidated for https), a 2 MiB
+// size cap, and a Content-Type allowlist. Mirrors
+// internal/thirdparty/fetch.go:Fetch.
+async function fetch(rawURL) {
+  return fetchOnce(rawURL, 0)
+}
+
+api.fetch = fetch
+api.contentTypeAllowed = contentTypeAllowed
+api.requestOnce = requestOnce
+api.MAX_CONTENT_SIZE = MAX_CONTENT_SIZE
+api.MAX_REDIRECTS = MAX_REDIRECTS
+
+module.exports = api