retake-dev 0.4.0

package/src/server/api.js

@@ -0,0 +1,285 @@
+// The dev-server side of the dock: session + recordings persisted under
+// <root>/.retake, notes that agents can update, and an SSE stream so the dock
+// hears about changes live. See CONTRACT.md ("Server HTTP").
+//
+//   GET/PUT  /__retake/session
+//   GET/PUT/DELETE /__retake/recording/:branchId
+//   GET      /__retake/notes
+//   GET      /__retake/notes/:id
+//   PATCH    /__retake/notes/:id          { status?, reply? }
+//   GET      /__retake/events             SSE: note-updated, code-version, active-changed, session
+//
+// Mutating requests need `x-retake-token`. The token is injected into the
+// shell page and written to <root>/.retake/server.json for local tools (MCP).
+import fs from "node:fs"
+import path from "node:path"
+import zlib from "node:zlib"
+import { promisify } from "node:util"
+
+const gzip = promisify(zlib.gzip)
+const gunzip = promisify(zlib.gunzip)
+
+const STATUSES = new Set(["pending", "acknowledged", "resolved", "dismissed"])
+const MAX_BODY = 256 * 1024 * 1024
+const EMPTY = () => ({ branches: [], activeId: null, markers: [], notes: [] })
+
+export function createBus() {
+  const clients = new Set()
+  return {
+    clients,
+    emit(event, data) {
+      const msg = `event: ${event}\ndata: ${JSON.stringify(data ?? {})}\n\n`
+      for (const res of clients) res.write(msg)
+    },
+  }
+}
+
+export function sessionStore(root) {
+  const dir = path.join(root, ".retake")
+  const recDir = path.join(dir, "recordings")
+  const sessionFile = path.join(dir, "session.json")
+  fs.mkdirSync(recDir, { recursive: true })
+  const ignore = path.join(dir, ".gitignore")
+  if (!fs.existsSync(ignore)) fs.writeFileSync(ignore, "*\n")
+
+  const atomic = (file, data) => {
+    const tmp = `${file}.${process.pid}-${Date.now()}.tmp`
+    fs.writeFileSync(tmp, data)
+    fs.renameSync(tmp, file)
+  }
+  const recFile = (id) => {
+    if (!/^[\w-]{1,64}$/.test(String(id))) throw Object.assign(new Error("bad branch id"), { status: 400 })
+    return path.join(recDir, `${id}.json`)
+  }
+  return {
+    dir,
+    getSession() {
+      try {
+        return { ...EMPTY(), ...JSON.parse(fs.readFileSync(sessionFile, "utf8")) }
+      } catch {
+        return EMPTY()
+      }
+    },
+    putSession(s) {
+      atomic(sessionFile, JSON.stringify({ ...EMPTY(), ...s }))
+    },
+    // Recordings are gzipped on disk (JSON compresses ~10×), written off the
+    // request path and atomically.
+    async getRecording(id) {
+      const f = recFile(id)
+      try {
+        return (await gunzip(await fs.promises.readFile(f + ".gz"))).toString("utf8")
+      } catch {}
+      try {
+        return await fs.promises.readFile(f, "utf8") // older, uncompressed
+      } catch {
+        return null
+      }
+    },
+    async putRecording(id, text) {
+      const f = recFile(id)
+      const tmp = `${f}.gz.${process.pid}-${Date.now()}.tmp`
+      await fs.promises.writeFile(tmp, await gzip(text, { level: 6 }))
+      await fs.promises.rename(tmp, f + ".gz")
+      fs.rmSync(f, { force: true })
+    },
+    deleteRecording(id) {
+      const f = recFile(id)
+      fs.rmSync(f, { force: true })
+      fs.rmSync(f + ".gz", { force: true })
+    },
+    // Drop recordings of branches the session no longer has ("Start fresh", deletes).
+    prune(session) {
+      const keep = new Set((session.branches || []).map((b) => `${b.id}.json`))
+      for (const f of fs.readdirSync(recDir)) {
+        const base = f.replace(/\.gz$/, "")
+        if (base.endsWith(".json") && !keep.has(base)) fs.rmSync(path.join(recDir, f), { force: true })
+      }
+    },
+  }
+}
+
+function readBody(req) {
+  return new Promise((resolve, reject) => {
+    let size = 0
+    const chunks = []
+    req.on("data", (c) => {
+      size += c.length
+      if (size > MAX_BODY) {
+        reject(Object.assign(new Error("body too large"), { status: 413 }))
+        req.destroy()
+      } else chunks.push(c)
+    })
+    req.on("end", () => resolve(Buffer.concat(chunks).toString("utf8")))
+    req.on("error", reject)
+  })
+}
+
+// Apply a PATCH to a note: a status change and/or a reply.
+export function patchNote(note, body, from = "agent") {
+  if (body.status != null) {
+    if (!STATUSES.has(body.status)) throw Object.assign(new Error(`status must be one of ${[...STATUSES].join(", ")}`), { status: 400 })
+    note.status = body.status
+  }
+  if (body.reply != null) {
+    const text = typeof body.reply === "string" ? body.reply : body.reply.text
+    if (!text) throw Object.assign(new Error("reply needs text"), { status: 400 })
+    note.replies = [...(note.replies || []), { from: body.reply.from || from, text: String(text), at: Date.now() }]
+  }
+  if (!note.status) note.status = "pending"
+  if (!note.replies) note.replies = []
+  return note
+}
+
+const cleanups = new Set()
+// <root>/.retake/server.json tells local tools (MCP) where the server is and
+// its token. Removed again when this process exits (if it's still ours).
+export function writeServerInfo({ root, url, token, base = "/" }) {
+  const dir = path.join(root, ".retake")
+  const file = path.join(dir, "server.json")
+  try {
+    fs.mkdirSync(dir, { recursive: true })
+    fs.writeFileSync(file, JSON.stringify({ url, base, token, pid: process.pid }), { mode: 0o600 })
+  } catch {}
+  if (!cleanups.has(file)) {
+    cleanups.add(file)
+    process.once("exit", () => {
+      try {
+        if (JSON.parse(fs.readFileSync(file, "utf8")).pid === process.pid) fs.rmSync(file, { force: true })
+      } catch {}
+    })
+  }
+}
+
+/**
+ * The /__retake/ API as a plain `(req, res, next)` handler, for any Node HTTP
+ * server (Vite's middleware stack, the front server, a bare http.Server).
+ * Requests outside it (and /__retake/ routes it doesn't know, like the code
+ * versions' ones) go to `next`, or get a 404 without one.
+ * @param {{ root: string, token: string, bus: ReturnType<typeof createBus> }} options
+ */
+export function createSessionHandler({ root, token, bus }) {
+  const store = sessionStore(root)
+  const heartbeat = setInterval(() => {
+    for (const res of bus.clients) res.write(": ping\n\n")
+  }, 25_000)
+  heartbeat.unref()
+
+  const send = (res, code, body, type = "application/json") => {
+    res.statusCode = code
+    res.setHeader("Content-Type", type)
+    res.setHeader("Cache-Control", "no-store")
+    res.end(typeof body === "string" ? body : JSON.stringify(body))
+  }
+
+  const handler = async (req, res, next = () => send(res, 404, { error: "not found" })) => {
+    const url = new URL(req.url, "http://x")
+    const p = url.pathname
+    if (!p.startsWith("/__retake/")) return next()
+    const route = p.slice("/__retake/".length).split("/")
+    const mutating = req.method !== "GET" && req.method !== "HEAD"
+    if (route[0] === "tailwind" && req.method === "GET") {
+      // Where Tailwind is configured: a v3 config file, or (v4) the CSS that imports it.
+      const cfg = ["tailwind.config.ts", "tailwind.config.js", "tailwind.config.mjs", "tailwind.config.cjs"].find((f) => fs.existsSync(path.join(root, f)))
+      let config = cfg || null
+      if (!config) {
+        const walk = (d, depth) => {
+          if (depth > 4 || config) return
+          for (const e of fs.readdirSync(d, { withFileTypes: true })) {
+            if (config || e.name.startsWith(".") || e.name === "node_modules" || e.name === "dist") continue
+            const f = path.join(d, e.name)
+            if (e.isDirectory()) walk(f, depth + 1)
+            else if (/\.css$/.test(e.name) && /@import\s+["']tailwindcss/.test(fs.readFileSync(f, "utf8"))) config = path.relative(root, f)
+          }
+        }
+        try {
+          walk(root, 0)
+        } catch {}
+      }
+      return send(res, 200, { config })
+    }
+    const known = ["session", "recording", "notes", "events"].includes(route[0])
+    if (!known) return next() // e.g. /__retake/version and /checkout (code-versions)
+    if (mutating && req.headers["x-retake-token"] !== token) return send(res, 403, { error: "missing or wrong x-retake-token" })
+    try {
+      if (route[0] === "events" && req.method === "GET") {
+        res.writeHead(200, { "Content-Type": "text/event-stream", "Cache-Control": "no-store", Connection: "keep-alive" })
+        res.write(": retake\n\n")
+        bus.clients.add(res)
+        req.on("close", () => bus.clients.delete(res))
+        return
+      }
+      if (route[0] === "session" && route.length === 1) {
+        if (req.method === "GET") return send(res, 200, store.getSession())
+        if (req.method === "PUT") {
+          const before = store.getSession()
+          const next = JSON.parse(await readBody(req))
+          store.putSession(next)
+          store.prune(next)
+          if (next.activeId !== before.activeId) bus.emit("active-changed", { activeId: next.activeId })
+          bus.emit("session", { at: Date.now() })
+          return send(res, 200, { ok: true })
+        }
+      }
+      if (route[0] === "recording" && route.length === 2) {
+        const id = decodeURIComponent(route[1])
+        if (req.method === "GET") {
+          const text = await store.getRecording(id)
+          return text == null ? send(res, 404, { error: "no recording" }) : send(res, 200, text)
+        }
+        if (req.method === "PUT") {
+          const text = await readBody(req)
+          JSON.parse(text) // must be valid JSON
+          await store.putRecording(id, text)
+          return send(res, 200, { ok: true })
+        }
+        if (req.method === "DELETE") {
+          store.deleteRecording(id)
+          return send(res, 200, { ok: true })
+        }
+      }
+      if (route[0] === "notes") {
+        const session = store.getSession()
+        const notes = session.notes || []
+        if (route.length === 1 && req.method === "GET") return send(res, 200, notes)
+        const id = route[1] && decodeURIComponent(route[1])
+        const note = notes.find((n) => String(n.id) === String(id))
+        if (route.length === 2 && req.method === "GET") return note ? send(res, 200, note) : send(res, 404, { error: "no such note" })
+        if (route.length === 2 && req.method === "PATCH") {
+          if (!note) return send(res, 404, { error: "no such note" })
+          patchNote(note, JSON.parse((await readBody(req)) || "{}"), req.headers["x-retake-from"] === "user" ? "user" : "agent")
+          store.putSession(session)
+          bus.emit("note-updated", note)
+          return send(res, 200, note)
+        }
+      }
+      return send(res, 405, { error: `${req.method} not supported on ${p}` })
+    } catch (err) {
+      return send(res, err.status || (err instanceof SyntaxError ? 400 : 500), { error: err.message })
+    }
+  }
+  handler.store = store
+  // Ends the heartbeat and the open event streams (a front server closing).
+  handler.close = () => {
+    clearInterval(heartbeat)
+    for (const res of bus.clients) res.end()
+    bus.clients.clear()
+  }
+  return handler
+}
+
+// The Vite adapter: the handler on Vite's middleware stack, and server.json
+// written once Vite is listening.
+export function sessionApi(server, { token, bus, root = server.config.root }) {
+  const handler = createSessionHandler({ root, token, bus })
+  const address = () => {
+    const a = server.httpServer && server.httpServer.address()
+    const port = a && typeof a === "object" ? a.port : server.config.server.port
+    return `${server.config.server.https ? "https" : "http"}://localhost:${port}`
+  }
+  const info = () => writeServerInfo({ root, url: address(), token, base: server.config.base || "/" })
+  if (server.httpServer) server.httpServer.once("listening", info)
+  else info()
+  server.middlewares.use(handler)
+  return { store: handler.store, address }
+}

package/src/server/child.js

@@ -0,0 +1,174 @@
+// Runs the app's own dev command (`next dev`, `pnpm run dev`...) for the front
+// server, and finds out where it listens: the first local URL it prints wins
+// (Vite-based tools ignore PORT), else PORT, which is set to a free port unless
+// it already was (and that one is free: a PORT exported in the shell with
+// another app on it would have been taken for the dev server). The command runs
+// in its own process group, so stopping it stops what it started too
+// (`pnpm dev` → `next dev`), even what outlives the command itself (`reap`).
+import http from "node:http"
+import https from "node:https"
+import net from "node:net"
+import path from "node:path"
+import fs from "node:fs"
+import { spawn, spawnSync } from "node:child_process"
+
+const ANSI = /\x1b\[[0-9;?]*[ -/]*[@-~]|\x1b\][^\x07]*\x07/g
+const LOCAL_URL = /\bhttps?:\/\/(?:localhost|127\.0\.0\.1|\[::1\]|0\.0\.0\.0):(\d{2,5})\b[^\s'"]*/
+
+// The first local URL in a line of output (0.0.0.0 means this machine).
+export function localUrlIn(text) {
+  const m = LOCAL_URL.exec(String(text).replace(ANSI, ""))
+  return m ? m[0].replace("0.0.0.0", "localhost").replace(/[).,;]+$/, "") : null
+}
+
+export function freePort() {
+  return new Promise((resolve, reject) => {
+    const s = net.createServer()
+    s.unref()
+    s.once("error", reject)
+    s.listen(0, "127.0.0.1", () => {
+      const { port } = /** @type {import("node:net").AddressInfo} */ (s.address())
+      s.close(() => resolve(port))
+    })
+  })
+}
+
+// Can we listen on this port (on any loopback address an app would use)?
+function portFree(port) {
+  const on = (host) =>
+    new Promise((resolve) => {
+      const s = net.createServer()
+      s.unref()
+      s.once("error", (/** @type {NodeJS.ErrnoException} */ e) => resolve(e.code === "EADDRNOTAVAIL" || e.code === "EAFNOSUPPORT"))
+      s.listen(port, host, () => s.close(() => resolve(true)))
+    })
+  return Promise.all([on("127.0.0.1"), on("::1")]).then((r) => r.every(Boolean))
+}
+
+// Does anything answer HTTP there (any status)?
+export function answers(url, timeout = 2000) {
+  return new Promise((resolve) => {
+    const u = new URL(url)
+    const lib = u.protocol === "https:" ? https : http
+    const r = lib.request(u, /** @type {import("node:https").RequestOptions} */ ({ method: "HEAD", autoSelectFamily: true, rejectUnauthorized: false, timeout }), (res) => {
+      res.resume()
+      resolve(true)
+    })
+    r.on("timeout", () => r.destroy())
+    r.on("error", () => resolve(false))
+    r.end()
+  })
+}
+
+// The project's node_modules/.bin folders (walking up to a workspace root), so
+// `retake -- next dev` finds the project's own `next`.
+function binPath(cwd) {
+  const dirs = []
+  for (let d = path.resolve(cwd); ; d = path.dirname(d)) {
+    const bin = path.join(d, "node_modules", ".bin")
+    if (fs.existsSync(bin)) dirs.push(bin)
+    if (path.dirname(d) === d) break
+  }
+  return dirs
+}
+
+/**
+ * @param {string} command a shell command line
+ * @param {{ cwd?: string, env?: NodeJS.ProcessEnv, onOutput?: (chunk: Buffer, stream: "stdout" | "stderr") => void }} [options]
+ * @returns {Promise<{ child: import("node:child_process").ChildProcess, port: number, portTaken: number | null,
+ *   url: Promise<string>, exited: Promise<number>, stop(signal?: NodeJS.Signals): void, reap(ms?: number): Promise<void> }>}
+ *   `url` resolves once the server answers (it rejects if the command exits first).
+ *   `portTaken`: the PORT given, if something else was already on it. `reap`:
+ *   once the command has exited, what it started that's still running gets
+ *   SIGTERM (unless it was signalled already), then SIGKILL `ms` after that.
+ */
+export async function runDevCommand(command, { cwd = process.cwd(), env = process.env, onOutput } = {}) {
+  const asked = env.PORT ? Number(env.PORT) : null
+  const portTaken = asked && !(await portFree(asked)) ? asked : null
+  const port = asked && !portTaken ? asked : await freePort()
+  const sep = process.platform === "win32" ? ";" : ":"
+  /** @type {NodeJS.ProcessEnv} */
+  const childEnv = { ...env, PORT: String(port), PATH: [...binPath(cwd), env.PATH || env.Path || ""].join(sep) }
+  // Astro (7.x) moves `astro dev` into a detached background process when it
+  // thinks a coding agent ran it: out of this process
+  // group, so stopping Retake left it running, and the next run found "already
+  // running" and exited. Retake is the foreground owner; this is how Astro's own
+  // background child tells it not to background again.
+  if (childEnv.ASTRO_DEV_BACKGROUND == null) childEnv.ASTRO_DEV_BACKGROUND = "1"
+  if (process.stdout.isTTY && childEnv.FORCE_COLOR == null && childEnv.NO_COLOR == null) childEnv.FORCE_COLOR = "1"
+  const win = process.platform === "win32"
+  const child = spawn(command, { cwd, env: childEnv, shell: true, detached: !win, stdio: ["inherit", "pipe", "pipe"], windowsHide: true })
+
+  /** @type {string | null} */
+  let printed = null
+  let pending = ""
+  const scan = (chunk) => {
+    if (printed) return
+    pending = (pending + chunk.toString("utf8")).slice(-4096)
+    const u = localUrlIn(pending)
+    if (u) printed = u
+  }
+  const pass = (name) => (chunk) => {
+    scan(chunk)
+    if (onOutput) onOutput(chunk, name)
+    else (name === "stderr" ? process.stderr : process.stdout).write(chunk)
+  }
+  child.stdout.on("data", pass("stdout"))
+  child.stderr.on("data", pass("stderr"))
+
+  /** @type {number | null} */
+  let exitCode = null
+  const exited = new Promise((resolve) => {
+    child.on("exit", (code, signal) => resolve((exitCode = code ?? (signal ? 1 : 0))))
+    child.on("error", () => resolve((exitCode = 127)))
+  })
+
+  // The printed URL (once it answers) wins; PORT answering first means the
+  // tool honoured it.
+  const url = (async () => {
+    const fallback = `http://localhost:${port}`
+    for (;;) {
+      if (exitCode != null) throw new Error(`the dev command exited (code ${exitCode}) before it started a server`)
+      if (printed) {
+        const origin = new URL(printed).origin
+        if (await answers(origin)) return origin
+      } else if (await answers(fallback, 500)) return fallback
+      await new Promise((r) => setTimeout(r, 250))
+    }
+  })()
+  url.catch(() => {})
+
+  // The command's process group: its leader (the shell, a package manager) can
+  // exit while what it started is still stopping.
+  let signalled = false
+  const groupAlive = () => {
+    if (win || child.pid == null) return false
+    try {
+      process.kill(-child.pid, 0)
+      return true
+    } catch (e) {
+      return e.code === "EPERM"
+    }
+  }
+  const stop = (/** @type {NodeJS.Signals} */ signal = "SIGTERM") => {
+    if (child.pid == null || (exitCode != null && !groupAlive())) return
+    signalled = true
+    try {
+      if (win) spawnSync("taskkill", ["/pid", String(child.pid), "/T", "/F"], { stdio: "ignore" })
+      else process.kill(-child.pid, signal)
+    } catch {
+      try {
+        child.kill(signal)
+      } catch {}
+    }
+  }
+  const reap = async (ms = 5000) => {
+    await exited
+    if (!groupAlive()) return
+    if (!signalled) stop("SIGTERM")
+    const end = Date.now() + ms
+    while (groupAlive() && Date.now() < end) await new Promise((r) => setTimeout(r, 100))
+    if (groupAlive()) stop("SIGKILL")
+  }
+  return { child, port, portTaken, url, exited, stop, reap }
+}

package/src/server/detect.js

@@ -0,0 +1,167 @@
+// What kind of project `retake <dir>` was pointed at, and how to run it.
+//   front: a framework with its own dev server (Next, Nuxt, React Router,
+//          Remix, SvelteKit, Astro...). Retake runs its dev command and sits in
+//          front of it (server/front.js).
+//   vite:  a Vite single-page app (index.html). Retake runs the project's own
+//          Vite with the plugin added, from a wrapper config (bin/retake.js).
+import fs from "node:fs"
+import path from "node:path"
+
+// Dependency → framework, and the framework's own dev command (the last resort,
+// when package.json has no dev script).
+export const FRAMEWORKS = {
+  next: { name: "next", cli: "next dev" },
+  nuxt: { name: "nuxt", cli: "nuxt dev" },
+  "@remix-run/dev": { name: "remix", cli: "remix vite:dev" },
+  "@react-router/dev": { name: "react-router", cli: "react-router dev" },
+  "@sveltejs/kit": { name: "sveltekit", cli: "vite dev" },
+  astro: { name: "astro", cli: "astro dev" },
+  "@tanstack/react-start": { name: "tanstack-start", cli: "vite dev" },
+  "@solidjs/start": { name: "solid-start", cli: "vinxi dev" },
+  vike: { name: "vike", cli: "vike dev" },
+  waku: { name: "waku", cli: "waku dev" },
+  "@analogjs/platform": { name: "analog", cli: "vite" },
+}
+const VITE_CONFIGS = ["vite.config.ts", "vite.config.mts", "vite.config.cts", "vite.config.js", "vite.config.mjs", "vite.config.cjs"]
+const LOCKS = [
+  ["pnpm-lock.yaml", "pnpm"],
+  ["yarn.lock", "yarn"],
+  ["bun.lock", "bun"],
+  ["bun.lockb", "bun"],
+  ["package-lock.json", "npm"],
+]
+
+// The package manager: package.json's `packageManager`, else the nearest lockfile
+// (a workspace's is at its root), else npm.
+export function packageManager(dir, pkg = readPkg(dir)) {
+  const declared = pkg && typeof pkg.packageManager === "string" && /^(pnpm|yarn|bun|npm)@/.exec(pkg.packageManager)
+  if (declared) return declared[1]
+  for (let d = path.resolve(dir); ; d = path.dirname(d)) {
+    for (const [file, pm] of LOCKS) if (fs.existsSync(path.join(d, file))) return pm
+    if (path.dirname(d) === d) return "npm"
+  }
+}
+
+function readPkg(dir) {
+  try {
+    return JSON.parse(fs.readFileSync(path.join(dir, "package.json"), "utf8"))
+  } catch {
+    return null
+  }
+}
+
+/**
+ * @param {string} dir the project folder
+ * @returns {{ mode: "front" | "vite" | null, framework: string | null, command: string | null, pm: string | null, reason?: string }}
+ */
+export function detectProject(dir) {
+  const pkg = readPkg(dir)
+  if (!pkg) return { mode: null, framework: null, command: null, pm: null, reason: `no package.json in ${dir}` }
+  const deps = { ...pkg.peerDependencies, ...pkg.optionalDependencies, ...pkg.devDependencies, ...pkg.dependencies }
+  const dep = Object.keys(FRAMEWORKS).find((d) => d in deps)
+  const pm = packageManager(dir, pkg)
+  if (dep) {
+    const fw = FRAMEWORKS[dep]
+    const scripts = pkg.scripts || {}
+    /** @type {string | null} */
+    let command = null
+    if (scripts.dev) command = `${pm} run dev`
+    // A start script that runs a dev server (never a production `next start`).
+    else if (scripts.start && /\bdev\b|^\s*vite(\s|$)/.test(scripts.start) && !/\bnext\s+start\b/.test(scripts.start)) command = `${pm} run start`
+    else command = `${pm === "npm" ? "npx --no-install" : `${pm} exec`} ${fw.cli}`
+    return { mode: "front", framework: fw.name, command, pm }
+  }
+  if (VITE_CONFIGS.some((f) => fs.existsSync(path.join(dir, f))) || fs.existsSync(path.join(dir, "index.html"))) {
+    return { mode: "vite", framework: "vite", command: null, pm }
+  }
+  return { mode: null, framework: null, command: null, pm, reason: `no framework or Vite app found in ${dir}` }
+}
+
+// The dev server's own traffic, by URL (regular expressions on path + query),
+// for the runtime to leave alone (RT.exemptUrls, see isExemptUrl in the
+// runtime): HMR sockets, overlays and hot updates. A call stack can't always
+// tell (Turbopack bundles Next's router and its HMR client into one chunk).
+const VITE_TRAFFIC = ["^/@vite/client", "^/@react-refresh"]
+export const DEV_TRAFFIC = {
+  next: ["^/_next/webpack-hmr", "^/_next/hmr\\b", "^/__nextjs_", "\\.hot-update\\."],
+  nuxt: ["^/__nuxt_devtools__", "^/_nuxt/@vite/client", ...VITE_TRAFFIC],
+  astro: ["^/__astro_dev_toolbar", ...VITE_TRAFFIC],
+  vite: VITE_TRAFFIC,
+}
+export const devTraffic = (framework) => DEV_TRAFFIC[framework] || VITE_TRAFFIC
+
+// The version of Next installed for the project (null: not found): its
+// node_modules or a parent folder's, as Node would find it from there, but not
+// through NODE_PATH, where pnpm puts every package of the workspace Retake was
+// started from (F74).
+export function nextVersion(dir) {
+  for (let d = path.resolve(dir); ; d = path.dirname(d)) {
+    try {
+      return JSON.parse(fs.readFileSync(path.join(d, "node_modules", "next", "package.json"), "utf8")).version || null
+    } catch {}
+    if (path.dirname(d) === d) return null
+  }
+}
+
+// The major version of Next the project uses (null: not found).
+export function nextMajor(dir) {
+  try {
+    const v = nextVersion(dir)
+    return Number(v.split(".")[0]) || null
+  } catch {
+    return null
+  }
+}
+
+/**
+ * How the runtime runs behind the front server (RT, see core.js) for a
+ * framework (null: not known yet; the front server sniffs Next itself).
+ * The clock starts at the window's load (F47) and scripts added later are
+ * held to their recorded moments (F48). `next`: the Next major version the
+ * debug-channel adapter is for (F49; only 16 is known), "auto" when the
+ * runtime has to ask Next's client (no project folder to look in).
+ * @param {string | null} framework
+ * @param {string | null} [dir]
+ * @returns {import("../../types/index.js").RuntimeConfig}
+ */
+export function frontRuntime(framework, dir) {
+  /** @type {import("../../types/index.js").RuntimeConfig} */
+  const rt = { bootAt: "load", holdScripts: true, exemptUrls: devTraffic(framework) }
+  // (No project folder, or Next not found from it: the runtime reads Next's own version, "auto".)
+  if (framework === "next") rt.next = (dir && nextMajor(dir)) || "auto"
+  return rt
+}
+
+// Extra arguments for a detected dev command (`retake . -- --turbopack`).
+export function withArgs(command, args, pm) {
+  if (!args || !args.length) return command
+  const quoted = args.map(shellQuote).join(" ")
+  // `npm run dev --foo` would give --foo to npm itself.
+  return pm === "npm" && /^npm run /.test(command) ? `${command} -- ${quoted}` : `${command} ${quoted}`
+}
+
+export const shellQuote = (a) => (/^[\w@%+=:,./-]+$/.test(a) ? a : process.platform === "win32" ? `"${a.replace(/"/g, '\\"')}"` : `'${a.replace(/'/g, "'\\''")}'`)
+
+// Next 16 sends React's debug data for every page request over its HMR socket
+// (`experimental.reactDebugChannel`, on by default), and a replayed request
+// never gets it, so replayed navigations and server actions never show. Read
+// as text, never evaluated. Returns the warning, or null.
+export function nextDebugChannelWarning(dir) {
+  /** @type {string | null} */
+  let version = null
+  try {
+    version = nextVersion(dir)
+  } catch {
+    return null
+  }
+  if (!version || Number(version.split(".")[0]) < 16) return null
+  const config = ["next.config.js", "next.config.mjs", "next.config.ts", "next.config.cjs", "next.config.mts"].map((f) => path.join(dir, f)).find((f) => fs.existsSync(f))
+  let text = ""
+  try {
+    text = config ? fs.readFileSync(config, "utf8") : ""
+  } catch {}
+  if (/reactDebugChannel\s*:\s*false/.test(text)) return null
+  // Retake speaks Next 16's debug channel itself (runtime/37-next.js).
+  if (Number(version.split(".")[0]) === 16) return null
+  return `Next ${version}: if replayed navigations and server actions don't show, set experimental: { reactDebugChannel: false } in ${config ? path.basename(config) : "next.config"} (Retake knows Next 16's debug channel, not this version's).`
+}