@skitterbyte/skitterspec-jira 0.0.0-stage → 2.0.0

package/src/env/provision.js

@@ -0,0 +1,466 @@
+'use strict'
+
+/**
+ * Pure provisioning planner for `spec-env up`.
+ *
+ * Given a resolved spec and its allocated slot, `planUp` returns the commands
+ * the caller runs from the primary checkout (the spec commit, `git worktree
+ * add`) and the worktree steps `spec-env bootstrap` runs afterwards (seeds, the
+ * env file, `setup`, the stack) — but performs no side effects itself. The caller (the CLI) reads/allocates the
+ * registry and passes the slot; this stays deterministic and unit-testable with
+ * no live git/docker.
+ */
+
+const { classifyDirtyTree } = require('./classify.js')
+const { portOffset } = require('./registry.js')
+const { renderEnvFile } = require('./render.js')
+const { expandTokens } = require('./resolve.js')
+
+// Cap a path list in a message: enough to recognise, not a wall of text.
+function listPaths(paths) {
+  const shown = paths.slice(0, 5).join(', ')
+  return paths.length > 5 ? `${shown}, and ${paths.length - 5} more` : shown
+}
+
+/**
+ * Decide what an uncommitted tree means for a provisioning run: commit it, refuse
+ * it, or ignore it.
+ *
+ * `/spec-start` refuses a dirty tree so another spec's unfinished work is never
+ * moved without its author asking. But the commonest dirty tree of all is the
+ * spec you just wrote and are now starting, and refusing THAT costs a round trip
+ * through `/commit` on every start. So the question asked here is not "does this
+ * dirt look important?" — a judgement the gate rightly declines to make — but
+ * membership in an exactly-known set (see `classify.js`). One foreign path
+ * disqualifies the whole tree.
+ *
+ * WHAT WOULD FOOL THIS: `ctx.dirtyPaths` being absent. That is not "the tree is
+ * clean" — it is "nobody looked", which happens on every legacy caller and
+ * whenever git itself could not be read. Either way it is never permission to
+ * commit: with no classification there is no owned set, so no commit is planned.
+ *
+ * Whether it also REFUSES depends on `carriesChanges`, and the asymmetry is the
+ * two modes' actual risk, not an inconsistency:
+ *
+ *   - checkout mode (`carriesChanges`) — `git switch -c` silently carries
+ *     uncommitted work onto the new branch. Unable to see the tree means unable
+ *     to rule that out, so it refuses, exactly as it did before this gate existed.
+ *   - worktree mode — `git worktree add` carries nothing, and forks from a commit
+ *     regardless. Refusing here would fire on a healthy repo whose git we merely
+ *     could not read, which is a cost paid by someone who did nothing wrong. So
+ *     it plans no commit and provisions as before.
+ *
+ * `specOnFork` is the other half, and a POSITIVE signal rather than an absence:
+ * the worktree forks from a specific commit, so a spec absent from it produces a
+ * branch missing the very spec it is for. A clean tree cannot detect that — the
+ * spec may be committed, just somewhere else. `null` means the caller could not
+ * tell (an unreadable git, or a hotfix, which forks from a tag predating its own
+ * spec), and routes to carrying on, never to refusing.
+ *
+ * FOREIGN DIRT IS THE SAME ASYMMETRY, for the same reason. Another spec's
+ * uncommitted work refuses in checkout mode, where `git switch -c` would carry
+ * it onto the new branch, and does not in worktree mode, where nothing carries
+ * anywhere. Refusing there fired on the commonest tree this workflow produces —
+ * author spec B while spec A is still uncommitted, then start B — and prevented
+ * nothing, since the only write to the primary checkout is a pathspec-limited
+ * commit of this spec's own paths. It is reported instead, on `foreign`.
+ *
+ * ctx: { dirtyPaths?, clean?, specOnFork?, specFoundOn?, forkRef?, specUntracked? }
+ * @returns {{blocked: boolean, reason: string|null, commands: string[],
+ *            owned: string[], foreign: string[]}}
+ */
+function planSpecCommit(spec, ctx, config, { carriesChanges = false } = {}) {
+  const ok = { blocked: false, reason: null, commands: [], owned: [], verb: null, foreign: [] }
+  const c = ctx || {}
+
+  if (!Array.isArray(c.dirtyPaths)) {
+    // Nobody looked: never commit, and refuse only where switching could carry
+    // work we cannot see (see the asymmetry above).
+    if (carriesChanges && c.clean === false) {
+      return {
+        blocked: true,
+        reason:
+          'the primary checkout has uncommitted changes — commit or stash them first' +
+          (carriesChanges ? ' (switching would carry them onto the new branch)' : ''),
+        commands: [],
+        owned: [],
+        verb: null,
+      }
+    }
+    return ok
+  }
+
+  const { owned, foreign } = classifyDirtyTree(spec, c.dirtyPaths, config)
+
+  // FOREIGN DIRT REFUSES ONLY WHERE IT CAN REACH THE BRANCH, which is checkout
+  // mode and nowhere else. `git switch -c` carries the working tree onto the new
+  // branch, silently, so there it is someone else's work being moved without
+  // them asking. `git worktree add` carries nothing and forks from a commit, so
+  // in worktree mode the same tree is simply none of this run's business.
+  //
+  // WHAT WOULD MAKE THIS UNSAFE AGAIN: an unbounded commit. The only thing this
+  // run does to the primary checkout is the spec commit below, and it is safe to
+  // leave a colleague's files sitting beside it only because that commit is
+  // pathspec-limited on BOTH halves (`git add --`, `git commit … --`) and so
+  // cannot reach a path it does not own — not even one another session has
+  // already staged into the shared index. Drop the `--` and this stops being a
+  // false guard and starts being a missing one.
+  if (foreign.length && carriesChanges) {
+    return {
+      blocked: true,
+      reason:
+        `the primary checkout has uncommitted changes that are not ${spec.folder}'s — ` +
+        'commit or stash them first (switching would carry them onto the new branch)' +
+        `: ${listPaths(foreign)}`,
+      commands: [],
+      owned: [],
+      verb: null,
+      foreign,
+    }
+  }
+
+  if (owned.length) {
+    // `add` or `update`? Asked of git (`ctx.specUntracked`, from `git ls-files`)
+    // rather than inferred from the shape of the status output. The inference —
+    // "a bare directory entry means the folder is wholly untracked" — was wrong in
+    // the ordinary case of the FIRST spec in a bucket, where git reports the
+    // bucket as the untracked directory instead. The old inference stays as a
+    // fallback for callers that pass no fact; unknown yields `update`, which is
+    // never a false claim.
+    const isNew =
+      typeof c.specUntracked === 'boolean'
+        ? c.specUntracked
+        : owned.includes(`specs/${spec.bucket}/${spec.folder}`)
+    const verb = isNew ? 'add' : 'update'
+    // BOTH HALVES ARE PATHSPEC-LIMITED, and they answer different failures.
+    // `add` is what makes a path git has never seen committable at all — every
+    // brand-new spec folder is untracked. The `--` on the COMMIT is what bounds
+    // what lands: a checkout has one `.git/index` and every session standing in
+    // it shares that index, so a bare `git commit` takes whatever another
+    // session has already staged, however exactly this one named its own paths.
+    // Dropping the `--` would leave the naming above as decoration.
+    const paths = owned.map((p) => `"${p}"`).join(' ')
+    return {
+      blocked: false,
+      reason: null,
+      owned,
+      verb,
+      foreign,
+      commands: [
+        `git add -- ${paths}`,
+        `git commit -m "chore(spec): ${verb} ${spec.folder}" -- ${paths}`,
+      ],
+    }
+  }
+
+  // Tree is clean. The spec must already be in the base branch's tree, or the
+  // worktree forks without it.
+  // Nothing of this spec's is uncommitted, but somebody else's may be — say so
+  // rather than returning the bare `ok`, or the caller has no way to report what
+  // it left alone.
+  if (foreign.length && c.specOnFork !== false) return { ...ok, foreign }
+
+  if (c.specOnFork === false) {
+    return {
+      blocked: true,
+      reason:
+        `${spec.folder} is not committed in ${c.forkRef || 'the fork point'}` +
+        (c.specFoundOn ? ` — it is on ${c.specFoundOn}` : '') +
+        ' — the worktree would fork without the spec it is for',
+      commands: [],
+    }
+  }
+  return ok
+}
+
+/**
+ * The `-f <composeFile>` argument for a `docker compose` invocation.
+ *
+ * ONLY when the configured file is known to be present, and that condition is
+ * the whole point. `docker.composeFile` was read, normalised and validated by
+ * the config loader and then never passed to docker at all, so a project naming
+ * a non-default file was silently relying on docker's own discovery instead.
+ * Passing it unconditionally would fix that project and BREAK the mirror image
+ * of it — one whose compose file is `compose.yaml` (a name docker finds by
+ * itself) while this key sits at its untouched default of `docker-compose.yml`.
+ *
+ * So the flag is added on the positive signal and omitted otherwise, which
+ * leaves docker's discovery exactly as it is for everyone it was already
+ * working for.
+ */
+function composeFileArg(config, present) {
+  const file = config && config.docker && config.docker.composeFile
+  return present === true && file ? ` -f ${file}` : ''
+}
+
+/**
+ * Does this spec want a Docker stack?
+ *
+ * ONE function, called by `planUp` and by the `up` command in `cli.js`. They
+ * used to each carry their own copy and the copies disagreed: the CLI read
+ * `spec.stack === 'docker'` with no fallback, so a header-less spec allocated no
+ * registry slot, while the planner fell back to the master switch and emitted
+ * `docker compose up -d` anyway — a stack brought up on a port offset derived
+ * from a slot that was never allocated.
+ *
+ * A SPEC WITH NO `Stack:` HEADER NEEDS THE COMPOSE FILE TO BE PRESENT. The
+ * master switch alone is not evidence that there is a stack to bring up: it is
+ * a project-wide default, and `/spec` has written the header on every spec for
+ * some time, so the specs reaching this fallback are legacy or hand-written. The
+ * compose file is the positive signal that the escalation would land on
+ * something real (`.claude/rules/negative-checks.md` rule 1).
+ *
+ * WHAT WOULD FOOL THIS, deliberately unhandled: a project whose compose file is
+ * generated during `setup` rather than committed. It does not exist when the
+ * plan is built, so a header-less spec there resolves to `worktree`. The answer
+ * is an explicit `> **Stack:** worktree + docker` header, which is checked first
+ * and never consults this at all — so being wrong costs a header, not a stack.
+ *
+ * `composeFilePresent` undefined means the caller did not look, which is
+ * cannot-tell rather than false. It routes to no escalation, the harmless
+ * branch: a missing stack surfaces as a header to add, where a spurious one
+ * surfaces as `docker compose` failing mid-provision (rule 4).
+ */
+function resolveStack(spec, config, { docs = false, composeFilePresent } = {}) {
+  const stack =
+    spec.stack || (config.docker.enabled && composeFilePresent === true ? 'docker' : 'worktree')
+  return { stack, wantsDocker: stack === 'docker' && config.docker.enabled && !docs }
+}
+
+/**
+ * The steps that bring a fresh worktree to ready, as data — the list
+ * `spec-env bootstrap` runs. In the order each depends on the last: seeds (the
+ * env file may be one), the env file, `setup` (which may derive values into
+ * it), and only then the stack.
+ *
+ * DATA AND NOT SHELL, and that is the reason the verb exists. These steps were
+ * printed as POSIX-sh one-liners for the agent to copy, and the copy was never
+ * faithful: merged into a loop, its echo text reworded, two steps glued into one
+ * call. A consumer's secrets hook — which refuses any Bash call naming a `.env`
+ * file and makes an exception only for the exact printed shape — then refused
+ * the rewrite, and bootstrap stopped with the user running it by hand. A step
+ * the engine runs itself has no text for anything to rewrite or refuse.
+ *
+ * `setup` entries stay shell strings: they are the project's own commands,
+ * written by the project. The docker step is an argv, run without a shell.
+ *
+ * Pure: `offset` is the spec's port offset (null without a stack), and every
+ * filesystem fact arrives in `opts`.
+ */
+function worktreeSteps(spec, offset, config, opts = {}) {
+  const { docs = false, wantsDocker = false, composeFilePresent: compose } = opts
+  const seed = config.seedFiles || { mode: 'symlink', files: [] }
+  const mode = seed.mode === 'copy' ? 'copy' : 'symlink'
+  const tokens = {
+    worktreePath: spec.worktreePath,
+    slug: spec.slug,
+    branch: spec.branch,
+    projectName: spec.projectName,
+    portOffset: offset === null || offset === undefined ? '' : String(offset),
+  }
+  const envFile = (config.docker && config.docker.envFile) || '.env'
+  const steps = (seed.files || []).map((file) => ({ kind: 'seed', file, mode }))
+  if (wantsDocker) {
+    steps.push({ kind: 'envFile', file: envFile, projectName: spec.projectName, offset })
+  }
+  // Documents mode drops `setup` and nothing else: seeding is cheap and a spec
+  // author may well want the gitignored files present, while `setup` is the
+  // expensive half that exists to make the tree run. `wantsDocker` is already
+  // false under `--docs` (`resolveStack`), so the stack drops with it.
+  if (!docs) {
+    for (const cmd of config.setup || []) {
+      steps.push({ kind: 'setup', command: expandTokens(cmd, tokens) })
+    }
+  }
+  if (wantsDocker) {
+    const file = composeFileArg(config, compose).trim().split(/\s+/).filter(Boolean)
+    steps.push({
+      kind: 'docker',
+      argv: [
+        'docker',
+        'compose',
+        ...file,
+        '--env-file',
+        envFile,
+        '--project-name',
+        spec.projectName,
+        'up',
+        '-d',
+      ],
+    })
+  }
+  return steps
+}
+
+/**
+ * Plan a provisioning run.
+ *
+ * @param {object} spec  resolved spec (from resolveSpec): { slug, type, branch,
+ *                       worktreePath, projectName, ... }
+ * @param {object} alloc { slot, attached } — attached:true when the slot already
+ *                       existed in the registry (re-run → attach, don't clobber).
+ * @param {object} config normalised env config.
+ * @param {object} opts  { docs } — documents mode (see below). Optional.
+ * @returns {object} { worktreePath, branch, projectName, slot, portOffset,
+ *                     envContents, commands, steps, docs, attached }
+ *
+ * `commands` run from the primary checkout (the spec commit, the fork); `steps`
+ * are what `spec-env bootstrap` runs in the worktree afterwards.
+ */
+function planUp(spec, alloc, config, ctx, opts = {}) {
+  const { slot, attached } = alloc
+
+  // DOCUMENTS MODE — a worktree to write a spec in, not to run code in.
+  //
+  // `/spec` provisions before it writes the spec folder, so that authoring never
+  // touches the base branch. What it needs is a checkout on a branch; what it
+  // does not need is `pnpm install --frozen-lockfile` and a database, to write
+  // markdown. So this mode keeps the fork and drops everything whose only
+  // purpose is making the tree runnable.
+  //
+  // It is not a lesser provision that has to be undone: `/spec-start` re-runs
+  // `up` over the same worktree WITHOUT this flag, and the setup commands run
+  // then — at the first moment the tree is used for code.
+  const docs = opts.docs === true
+
+  // Per-spec escalation, decided in ONE place (`resolveStack`) so the planner and
+  // the CLI cannot answer it differently — which they did, for exactly the
+  // header-less spec this gate is about.
+  const { wantsDocker } = resolveStack(spec, config, {
+    docs,
+    composeFilePresent: ctx ? ctx.composeFilePresent : undefined,
+  })
+
+  // Slot, port block and `.env` are Docker-only. A worktree-only spec takes none
+  // of them: no registry slot, no PORT_OFFSET, no `.env`.
+  const offset = wantsDocker ? portOffset(slot, config) : null
+  const envContents = wantsDocker
+    ? renderEnvFile({ projectName: spec.projectName, portOffset: offset })
+    : null
+
+  // Everything after the fork runs in the worktree, and `spec-env bootstrap`
+  // runs it — the steps are data, not shell for a caller to copy.
+  const steps = worktreeSteps(spec, offset, config, {
+    docs,
+    wantsDocker,
+    composeFilePresent: ctx ? ctx.composeFilePresent : undefined,
+  })
+
+  const commands = []
+  // Fresh branch → -b; attach an existing branch/slot → plain form (never clobber).
+  // A hotfix forks its fresh branch from a release tag (`spec.baseRef`, e.g.
+  // `v33.16.4`) instead of base HEAD — so the fix is built on the exact commit
+  // line prod runs. Attaching an existing branch ignores baseRef (already forked).
+  const forkPoint = !attached && spec.baseRef ? ` ${spec.baseRef}` : ''
+  commands.push(
+    attached
+      ? `git worktree add ${spec.worktreePath} ${spec.branch}`
+      : `git worktree add ${spec.worktreePath} -b ${spec.branch}${forkPoint}`,
+  )
+  // The tree gate. A worktree forks from the base branch's tree, so an
+  // uncommitted spec would produce a branch missing the spec it is for — this is
+  // where that gets committed, or refused. Worktree mode had NO clean gate before
+  // this: `git worktree add` does not carry uncommitted changes anywhere, so the
+  // failure surfaced three steps later as a live-overlay refusal naming the wrong
+  // stage. An absent `ctx` means no caller looked, and changes nothing.
+  const gate = planSpecCommit(spec, ctx, config)
+
+  return {
+    blocked: gate.blocked,
+    reason: gate.reason,
+    specCommit: gate.owned && gate.owned.length ? { paths: gate.owned, verb: gate.verb } : null,
+    // What this run deliberately did not touch. Carried out rather than dropped
+    // because "provisioned, and left four of your files alone" is a different
+    // report from "provisioned", and the caller cannot reconstruct it.
+    untouched: gate.foreign || [],
+    worktreePath: spec.worktreePath,
+    branch: spec.branch,
+    projectName: spec.projectName,
+    slot: wantsDocker ? slot : null,
+    portOffset: offset,
+    envContents,
+    commands: gate.blocked ? [] : [...gate.commands, ...commands],
+    // The worktree steps, in the order `spec-env bootstrap` runs them. Documents
+    // mode drops `setup` and the stack and keeps the seeds (`worktreeSteps`).
+    steps: gate.blocked ? [] : steps,
+    // Reported so a caller reading `--json` can tell a documents worktree from a
+    // full one POSITIVELY, rather than inferring it from what is missing. A step
+    // list with no `setup` also describes a project that configured none, and
+    // those two must not read alike.
+    docs,
+    attached,
+  }
+}
+
+/**
+ * Plan `spec-env up` in CHECKOUT mode — the branch is built in the primary
+ * checkout and there is no worktree at all.
+ *
+ * Pure: every git fact it needs arrives in `ctx`, and it writes nothing.
+ *
+ * ctx: { current, base, onBase, clean, branchExists }
+ *
+ * What it refuses, and why each is a refusal rather than a warning:
+ *  - a dirty tree, because `git switch -c` CARRIES uncommitted changes onto the
+ *    new branch. That is silent and it is the operator's work, so it is theirs
+ *    to place, not ours.
+ *  - standing on another branch, because switching away from it is a decision
+ *    about someone else's unfinished spec. Being on THIS spec's branch is not a
+ *    refusal — it is the re-run, and the answer is "already attached".
+ *
+ * There is no bootstrap: the primary checkout already has its dependencies.
+ *
+ * AND THAT IS WHY `--docs` IS INERT HERE, rather than unimplemented. Documents
+ * mode exists to skip making a fresh tree runnable; this mode makes no fresh
+ * tree, so there is nothing for it to skip. The flag is accepted and changes
+ * nothing, because a caller passing it is asking for a cheap checkout and gets
+ * one — refusing would make `/spec` mode-aware for no behavioural difference.
+ */
+function planCheckoutUp(spec, ctx, config) {
+  const base = ctx.base || (config && config.baseBranch) || 'main'
+  const result = {
+    mode: 'checkout',
+    blocked: false,
+    reason: null,
+    attached: false,
+    branch: spec.branch,
+    checkoutPath: ctx.checkoutPath || null,
+    commands: [],
+  }
+  const block = (reason) => ({ ...result, blocked: true, reason })
+
+  // Order matters: report "already attached" before anything else, so a re-run
+  // on the spec's own branch is never refused for a dirty tree it legitimately
+  // has — you are mid-phase, with the phase's own edits in progress.
+  if (ctx.current && ctx.current === spec.branch) {
+    return { ...result, attached: true }
+  }
+  // Same gate as worktree mode, but `git switch -c` genuinely CARRIES uncommitted
+  // work onto the new branch, so the refusal keeps saying so.
+  const gate = planSpecCommit(spec, ctx, config, { carriesChanges: true })
+  if (gate.blocked) return block(gate.reason)
+  if (!ctx.onBase) {
+    return block(
+      `the primary checkout is on ${ctx.current || '(detached)'}, not ${base} — ` +
+        'finish or park that branch first; checkout mode holds one spec at a time',
+    )
+  }
+
+  if (gate.owned && gate.owned.length) {
+    result.specCommit = { paths: gate.owned, verb: gate.verb }
+  }
+  result.commands.push(...gate.commands)
+  result.commands.push(
+    ctx.branchExists ? `git switch ${spec.branch}` : `git switch -c ${spec.branch}`,
+  )
+  return result
+}
+
+module.exports = {
+  planUp,
+  planCheckoutUp,
+  planSpecCommit,
+  worktreeSteps,
+  resolveStack,
+  composeFileArg,
+}

package/src/env/proxy.js

@@ -0,0 +1,225 @@
+'use strict'
+
+/**
+ * Front-door reverse proxy for `spec-env connect` — a small, dependency-free
+ * Node proxy that exposes the ONE connected spec's warm dev servers on the
+ * canonical ports (exclusive model: no cookie, one target at a time).
+ *
+ * `renderRoutes` is pure (procs → routes). `startProxy` builds one `http` server
+ * per route, forwarding HTTP and `upgrade` (WebSocket/HMR) to the spec's port.
+ * Run directly (`node proxy.js <routesFile>`) it becomes the long-lived,
+ * detached proxy process the CLI supervises with the Phase 1 seam.
+ */
+
+const http = require('node:http')
+const net = require('node:net')
+const fs = require('node:fs')
+
+/**
+ * The connected spec's `dev` processes that declare a `frontPort` → proxy routes.
+ * @param {Array} procs  from `planDev(...).procs`
+ * @returns {Array<{name, frontPort, targetPort}>}
+ */
+function renderRoutes(procs) {
+  return (procs || [])
+    .filter((p) => typeof p.frontPort === 'number')
+    .map((p) => ({ name: p.name, frontPort: p.frontPort, targetPort: p.port }))
+}
+
+// Build (but don't listen on) one proxy server: frontPort → targetPort. Forwards
+// regular requests and transparently pipes `upgrade` (WebSocket) connections.
+function createRouteServer(route, host = '127.0.0.1') {
+  const { targetPort } = route
+
+  const server = http.createServer((req, res) => {
+    const upstream = http.request(
+      { host, port: targetPort, method: req.method, path: req.url, headers: req.headers },
+      (ur) => {
+        res.writeHead(ur.statusCode || 502, ur.headers)
+        ur.pipe(res)
+      },
+    )
+    upstream.on('error', () => {
+      if (!res.headersSent) res.writeHead(502, { 'content-type': 'text/plain' })
+      res.end(`spec-connect: upstream 127.0.0.1:${targetPort} not reachable\n`)
+    })
+    req.pipe(upstream)
+  })
+
+  // WebSocket / HTTP upgrade passthrough — reconstruct the request line + headers
+  // onto a raw TCP connection to the upstream, then pipe both ways.
+  server.on('upgrade', (req, socket, head) => {
+    const upstream = net.connect(targetPort, host, () => {
+      let raw = `${req.method} ${req.url} HTTP/1.1\r\n`
+      for (let i = 0; i < req.rawHeaders.length; i += 2) {
+        raw += `${req.rawHeaders[i]}: ${req.rawHeaders[i + 1]}\r\n`
+      }
+      raw += '\r\n'
+      upstream.write(raw)
+      if (head && head.length) upstream.write(head)
+      socket.pipe(upstream)
+      upstream.pipe(socket)
+    })
+    upstream.on('error', () => socket.destroy())
+    socket.on('error', () => upstream.destroy())
+  })
+
+  return server
+}
+
+/**
+ * Start every route's server listening. Returns `{ servers, close() }` where
+ * `close()` resolves once all servers are shut. Rejects (via the returned
+ * promise on the server 'error') if a port can't be bound.
+ */
+function startProxy(routes, { host = '127.0.0.1' } = {}) {
+  const servers = routes.map((route) => {
+    const server = createRouteServer(route, host)
+    server.listen(route.frontPort, host)
+    return server
+  })
+  return {
+    servers,
+    close() {
+      return Promise.all(
+        servers.map((s) => new Promise((resolve) => s.close(() => resolve()))),
+      )
+    },
+  }
+}
+
+/**
+ * Which of `ports` are already bound (so `connect` can tell the operator to stop
+ * main first). Resolves to the list of busy ports. `host` scopes the check.
+ */
+function portsInUse(ports, host = '127.0.0.1') {
+  return Promise.all(
+    ports.map(
+      (port) =>
+        new Promise((resolve) => {
+          const tester = net
+            .createServer()
+            .once('error', () => resolve(port)) // EADDRINUSE → busy
+            .once('listening', () => tester.close(() => resolve(null)))
+            .listen(port, host)
+        }),
+    ),
+  ).then((results) => results.filter((p) => p !== null))
+}
+
+// Does `port` accept a TCP connection right now?
+function checkListening(port, host) {
+  return new Promise((resolve) => {
+    const sock = net.connect(port, host)
+    sock.once('connect', () => {
+      sock.destroy()
+      resolve(true)
+    })
+    sock.once('error', () => {
+      sock.destroy()
+      resolve(false)
+    })
+  })
+}
+
+/**
+ * Poll until every port in `ports` accepts a connection (the detached proxy has
+ * finished binding), or `timeoutMs` elapses. Resolves true when all are up.
+ * `now`/`wait` are injectable for tests.
+ */
+async function waitListening(
+  ports,
+  { host = '127.0.0.1', timeoutMs = 3000, intervalMs = 50, now = () => Date.now(), wait } = {},
+) {
+  const sleep = wait || ((ms) => new Promise((r) => setTimeout(r, ms)))
+  const deadline = now() + timeoutMs
+  while (now() < deadline) {
+    const results = await Promise.all(ports.map((p) => checkListening(p, host)))
+    if (results.every(Boolean)) return true
+    await sleep(intervalMs)
+  }
+  return false
+}
+
+
+/**
+ * Ask whether `port` is free on EVERY host it will need, one host at a time.
+ *
+ * SEQUENTIAL IS THE WHOLE POINT, and it is not a style choice. The probe works
+ * by binding, so two probes of the same port running concurrently contend with
+ * each other — and on Linux a wildcard bind and a loopback bind of one port are
+ * mutually exclusive, so the pair reports a completely free port as busy. The
+ * review server then refused to start on every Linux machine, which is to say
+ * on CI, while every macOS run stayed green because BSD lets the two coexist.
+ *
+ * Probing one host at a time asks the question that was always intended — is
+ * anything ELSE holding this port — instead of racing the caller against
+ * itself. Verified on node:24-alpine: parallel reports busy on a free port,
+ * sequential does not; both still refuse a real squatter on either address.
+ *
+ * `probe` is injectable so the concurrency can be asserted without sockets.
+ */
+async function portsInUseOn(port, hosts, probe = portsInUse) {
+  const busy = []
+  for (const host of [...new Set(hosts)]) {
+    busy.push(...(await probe([port], host)))
+  }
+  return [...new Set(busy)]
+}
+
+/**
+ * Which of `ports` accept a connection on `host` — "is a dev server running?".
+ *
+ * CONNECTS, never binds. A bind probe on 127.0.0.1 SUCCEEDS on macOS beside a
+ * server listening on every address (Vite `host: true`, Fastify `0.0.0.0`),
+ * because BSD lets the two coexist, so it read a running phone-on-wifi dev
+ * server as absent. Linux refuses the second bind, which is why CI never saw
+ * it. A server that answers is running on any OS. What could still fool it: a
+ * server bound only to a non-loopback address, which `host` does not reach.
+ */
+async function portsAnswering(ports, host = '127.0.0.1') {
+  const results = await Promise.all(ports.map((p) => checkListening(p, host)))
+  return ports.filter((_, i) => results[i])
+}
+
+/**
+ * Which of `ports` are taken for a new listener on `host` — "may the proxy
+ * have these?". Busy when the bind fails OR something already answers.
+ *
+ * The bind alone is not enough on macOS: beside a wildcard listener it
+ * succeeds, and the proxy would then own `localhost` while LAN clients still
+ * reach the old server — two apps behind one port number. The connect catches
+ * that. SEQUENTIAL, bind first: the bind probe's own listener is closed before
+ * the connect runs, so the connect can never find the probe itself.
+ */
+async function portsHeld(ports, host = '127.0.0.1') {
+  const bound = await portsInUse(ports, host)
+  const answering = await portsAnswering(ports, host)
+  return ports.filter((p) => bound.includes(p) || answering.includes(p))
+}
+
+module.exports = {
+  renderRoutes,
+  createRouteServer,
+  startProxy,
+  portsInUse,
+  portsInUseOn,
+  portsAnswering,
+  portsHeld,
+  waitListening,
+}
+
+// Entry point: run as a detached process by the CLI. Reads its routes from a
+// file so a re-`connect` just rewrites the file and restarts this (tiny) process.
+if (require.main === module) {
+  const routesFile = process.argv[2]
+  if (!routesFile) {
+    process.stderr.write('proxy: usage: node proxy.js <routesFile>\n')
+    process.exit(1)
+  }
+  const routes = JSON.parse(fs.readFileSync(routesFile, 'utf-8'))
+  const { close } = startProxy(routes)
+  const shutdown = () => close().then(() => process.exit(0))
+  process.on('SIGTERM', shutdown)
+  process.on('SIGINT', shutdown)
+}