retake-dev 0.4.0

package/LICENSE

@@ -0,0 +1,91 @@
+Required Notice: Copyright (c) 2026 Rushil (https://github.com/LightningDesigner/retake)
+
+# PolyForm Shield License 1.0.0
+
+<https://polyformproject.org/licenses/shield/1.0.0>
+
+## Acceptance
+
+In order to get any license under these terms, you must agree to them as both strict obligations and conditions to all your licenses.
+
+## Copyright License
+
+The licensor grants you a copyright license for the software to do everything you might do with the software that would otherwise infringe the licensor's copyright in it for any permitted purpose.  However, you may only distribute the software according to [Distribution License](#distribution-license) and make changes or new works based on the software according to [Changes and New Works License](#changes-and-new-works-license).
+
+## Distribution License
+
+The licensor grants you an additional copyright license to distribute copies of the software.  Your license to distribute covers distributing the software with changes and new works permitted by [Changes and New Works License](#changes-and-new-works-license).
+
+## Notices
+
+You must ensure that anyone who gets a copy of any part of the software from you also gets a copy of these terms or the URL for them above, as well as copies of any plain-text lines beginning with `Required Notice:` that the licensor provided with the software.  For example:
+
+> Required Notice: Copyright Yoyodyne, Inc. (http://example.com)
+
+## Changes and New Works License
+
+The licensor grants you an additional copyright license to make changes and new works based on the software for any permitted purpose.
+
+## Patent License
+
+The licensor grants you a patent license for the software that covers patent claims the licensor can license, or becomes able to license, that you would infringe by using the software.
+
+## Noncompete
+
+Any purpose is a permitted purpose, except for providing any product that competes with the software or any product the licensor or any of its affiliates provides using the software.
+
+## Competition
+
+Goods and services compete even when they provide functionality through different kinds of interfaces or for different technical platforms.  Applications can compete with services, libraries with plugins, frameworks with development tools, and so on, even if they're written in different programming languages or for different computer architectures.  Goods and services compete even when provided free of charge.  If you market a product as a practical substitute for the software or another product, it definitely competes.
+
+## New Products
+
+If you are using the software to provide a product that does not compete, but the licensor or any of its affiliates brings your product into competition by providing a new version of the software or another product using the software, you may continue using versions of the software available under these terms beforehand to provide your competing product, but not any later versions.
+
+## Discontinued Products
+
+You may begin using the software to compete with a product or service that the licensor or any of its affiliates has stopped providing, unless the licensor includes a plain-text line beginning with `Licensor Line of Business:` with the software that mentions that line of business.  For example:
+
+> Licensor Line of Business: YoyodyneCMS Content Management System (http://example.com/cms)
+
+## Sales of Business
+
+If the licensor or any of its affiliates sells a line of business developing the software or using the software to provide a product, the buyer can also enforce [Noncompete](#noncompete) for that product.
+
+## Fair Use
+
+You may have "fair use" rights for the software under the law. These terms do not limit them.
+
+## No Other Rights
+
+These terms do not allow you to sublicense or transfer any of your licenses to anyone else, or prevent the licensor from granting licenses to anyone else.  These terms do not imply any other licenses.
+
+## Patent Defense
+
+If you make any written claim that the software infringes or contributes to infringement of any patent, your patent license for the software granted under these terms ends immediately. If your company makes such a claim, your patent license ends immediately for work on behalf of your company.
+
+## Violations
+
+The first time you are notified in writing that you have violated any of these terms, or done anything with the software not covered by your licenses, your licenses can nonetheless continue if you come into full compliance with these terms, and take practical steps to correct past violations, within 32 days of receiving notice.  Otherwise, all your licenses end immediately.
+
+## No Liability
+
+***As far as the law allows, the software comes as is, without any warranty or condition, and the licensor will not be liable to you for any damages arising out of these terms or the use or nature of the software, under any kind of legal claim.***
+
+## Definitions
+
+The **licensor** is the individual or entity offering these terms, and the **software** is the software the licensor makes available under these terms.
+
+A **product** can be a good or service, or a combination of them.
+
+**You** refers to the individual or entity agreeing to these terms.
+
+**Your company** is any legal entity, sole proprietorship, or other kind of organization that you work for, plus all its affiliates.
+
+**Affiliates** means the other organizations than an organization has control over, is under the control of, or is under common control with.
+
+**Control** means ownership of substantially all the assets of an entity, or the power to direct its management and policies by vote, contract, or otherwise.  Control can be direct or indirect.
+
+**Your licenses** are all the licenses granted to you for the software under these terms.
+
+**Use** means anything you do with the software requiring one of your licenses.

package/README.md

@@ -0,0 +1,198 @@
+# Retake
+
+A time machine for your dev server: Vite apps, Next.js, React Router and other
+frameworks. A timeline docks over the bottom of your app and records everything from page load. Drag it back and the app is at that
+moment. Ctrl-click the timeline to start a new take from there; the old one
+stays as a lane you can click back into. Dev only: nothing ships in builds.
+
+## Getting started
+
+### Requirements
+- Node 18 or newer
+- A Vite 5+ app served from an `index.html` (React, Vue, Svelte, plain JS), or anything
+  else with a dev server that serves HTML (Next.js, React Router, Remix, Nuxt, SvelteKit, Astro...):
+  see [Frameworks](#frameworks).
+- Chrome, Edge or another Chromium browser (that's what it's tested on)
+
+### Try it without installing
+From your app's folder:
+
+```sh
+npx retake-dev .          # npm
+pnpm dlx retake-dev .     # pnpm
+yarn dlx retake-dev .     # yarn (berry)
+bunx retake-dev .         # bun
+```
+
+Open the URL it prints (default http://localhost:3014). Your files aren't
+touched: on a Vite app it runs your own `vite.config` through a wrapper kept in your temp
+folder; on a framework it runs your `dev` script and sits in front of it.
+Retake keeps its session in a `.retake/` folder in the app (it git-ignores itself).
+
+> Use the full name `retake-dev` with `npx`/`dlx`. The short `retake` command only
+> exists after you install `retake-dev` in the project (an unrelated npm package
+> is called `retake`).
+
+### Install it in the project
+```sh
+npm i -D retake-dev       # or: pnpm add -D retake-dev / yarn add -D retake-dev / bun add -d retake-dev
+npx retake .              # same as above, now from node_modules
+```
+
+Or keep your usual `npm run dev` and add the plugin to `vite.config`:
+
+```js
+import { retake } from "retake-dev"
+
+export default defineConfig({
+  plugins: [retake(), /* ...your plugins */],
+})
+```
+
+`retake()` only runs in `vite dev`; `vite build` output has no Retake code in it.
+
+### Connect your coding agent (MCP)
+Notes you leave in the dock can go straight to your coding agent. Register the
+MCP server once, from the app folder. With Claude Code:
+
+```sh
+claude mcp add retake -- npx -y retake-dev mcp
+```
+
+Any other MCP client (Cursor, Codex, Windsurf...) takes the same command,
+`npx -y retake-dev mcp`, in its MCP settings.
+
+With the dev server running, the agent can `list_notes`, `get_note`,
+`get_active_timeline`, `acknowledge`, `resolve`, `reply` and `watch_notes`.
+It finds the server through `.retake/server.json` (or pass `--url http://localhost:3014`).
+Acknowledging and resolving show up on the note in the dock right away.
+
+### The first 60 seconds
+1. **Use your app** for a few seconds: it's being recorded already.
+2. **Pause** with space (or ⌥P, or the play button). The app goes view-only:
+   you can scroll, not click.
+3. **Rewind**: drag the playhead back. Let go and the moment is rebuilt for real.
+   ⌘-scroll on the timeline zooms in; ←/→ step frame by frame; F fits everything.
+4. **Branch**: Ctrl-click the timeline at a moment to start a new take there.
+   It starts paused: press play and do something different. Click the other
+   lane to go back to the first take.
+5. **Note**: hold ⌘ and click an element (or one of its animation layers),
+   write what should change, press Enter. "Copy for agent" copies a prompt with
+   the element, its React component, source file:line and CSS; or let your
+   agent pick it up over MCP.
+
+### Uninstall
+```sh
+npm uninstall retake-dev          # or pnpm remove / yarn remove / bun remove
+rm -rf .retake                    # Retake's session and recordings
+claude mcp remove retake          # if you added the MCP server (or remove it in your client's MCP settings)
+```
+Remove `retake()` from `vite.config` if you added it.
+
+## Commands
+```sh
+retake <project>                     # run the project's dev server with the timeline
+retake <project> --port 4000
+retake <project> --code-branches     # each timeline keeps its own version of the code (Vite apps; rewrites files!)
+retake <project> -- --host           # anything after -- goes to the dev server
+retake -- <dev command>              # run that command with the timeline in front (retake -- next dev)
+retake http://localhost:3000         # put the timeline in front of a dev server that's already running
+retake init                          # print the vite.config lines
+retake mcp                           # the MCP server your coding agent runs
+```
+`--root <dir>` puts `.retake/` somewhere else; `--verbose` logs every request the
+front server handles to `.retake/front.log`. Opt out for one page load with `?retake=0`.
+
+Recordings hold what you typed and what your API answered. Retake's front server
+only answers on localhost; with the plugin and `vite --host`, anyone on your
+network can read the session.
+
+## Frameworks
+
+Retake needs to put a small script first in the page the dock frames. A Vite
+single-page app gets it from the Vite plugin. Anything that renders its own HTML
+gets it from Retake's **front server**: Retake listens on its port (3014), serves
+the dock there, and passes everything else through to your dev server, adding the
+script to the frame's page as it streams. Assets, data fetches, server actions,
+API routes and the HMR socket go through untouched. Your config isn't changed.
+
+`retake .` works out which one you have. A project that depends on Next, Nuxt,
+React Router (framework mode), Remix, SvelteKit, Astro, TanStack Start, SolidStart,
+Vike, Waku or Analog gets the front server, in front of its `dev` script (run with
+the package manager its lockfile names):
+
+| Framework | Run | Notes |
+|---|---|---|
+| Vite SPA (React, Vue, Svelte, plain) | `npx retake-dev .` | or `plugins: [retake()]` in `vite.config` |
+| Next.js | `npx retake-dev .` | tested on 16.3 (app and pages router, server actions) and 15.5 (app router), Turbopack |
+| React Router 7 framework mode | `npx retake-dev .` | or `plugins: [retake(), reactRouter()]` and your usual `npm run dev`; tested on 7.18 |
+| Remix 2 (Vite) | `npx retake-dev .` | tested on 2.17 |
+| Astro | `npx retake-dev .` | tested on 7.3 with React islands and `<ClientRouter />` |
+| SvelteKit | `npx retake-dev .` | tested on 3.0 (Svelte 5) |
+| Nuxt | `npx retake-dev .` | tested on 4.5; runs `nuxt dev` behind Retake (it ignores `PORT`: `npx retake-dev . -- --port 3001` picks its port) |
+| TanStack Start, SolidStart, Vike... | `npx retake-dev .` | untested; with Vite you can also add `retake()` to its Vite plugins |
+| Anything else that serves HTML | `npx retake-dev -- <your dev command>` | e.g. `npx retake-dev -- npm run dev` |
+| A dev server that's already running | `npx retake-dev http://localhost:3000` | `.retake/` goes in the current folder (or `--root`) |
+
+Tested means: the app hydrates in the dock with no warning, and recording, scrubbing back, the rebuilt moment, Play, hot
+updates and reloads all work, started either way (`retake .` or `retake http://localhost:…`). The untested ones go
+through the same front server and should work; say so if one doesn't.
+
+- **Which port?** Retake sets `PORT` to a free port for the dev command (or keeps
+  yours), and otherwise uses the first `http://localhost:…` the command prints, so
+  tools that ignore `PORT` work too. Ctrl-C stops the dev server with it.
+- **The plugin in a Vite-based framework.** With `retake()` in `vite.config` and
+  no `index.html` in the Vite root, the plugin docks into the pages your framework
+  renders, on your usual dev server port: no second server.
+- **Signing in.** Sign-in pages (OAuth) refuse to load inside a frame, so sign in
+  at your app's own port first (cookies on `localhost` are shared across ports),
+  then open Retake's. A sign-in redirect that comes back from another site gets the
+  plain page so it completes; reload to get the dock back.
+- **Next 16.** Next 16 sends React debug data for every request over its HMR
+  socket (`experimental.reactDebugChannel`). Retake keeps it with the recording and
+  hands it back on replay, so nothing needs changing. Other Next versions with a
+  debug channel aren't known yet: if replayed navigations or server actions don't
+  show, Retake's warning says to set `experimental: { reactDebugChannel: false }`.
+- **Exact replays on server-rendered pages.** Behind the front server the clock
+  starts once the page has loaded and nothing more is loading (so an app that
+  imports itself after load, like Nuxt's, has mounted), scripts and stylesheets added later (lazily
+  loaded chunks) run at their recorded moment, the dev server's own traffic (HMR)
+  is left out of the recording, and a rebuilt moment gets the page's HTML as it
+  was recorded (kept in `.retake/docs/`), not rendered again. Native `import()`
+  (Vite's lazy routes, Astro islands) can't be held to its moment.
+- **Bottom of the app hidden by the dock?** The dock floats over the bottom of
+  the app (a cookie banner's buttons, Next's dev badge). Drag the dock's divider
+  down, or open the app with `?retake=0`.
+- **Not rewound.** Retake rewinds the browser, not your server: database writes,
+  server sessions and server-action side effects stay as they are (replays answer
+  from the recording). Service workers are off while Retake is in front, and
+  `--code-branches` is Vite-only.
+
+**Code per timeline** (`--code-branches`): when the source changes, the timeline
+you're on takes the new code; the others keep theirs. Stepping into a timeline
+checks its code out on disk (snapshots are kept in `.retake/`, and the newest
+code is put back when the server stops), but use it on prototypes, not shared repos.
+
+## How going back works
+
+It doesn't snapshot the DOM. It records every input (pointer, keys, typing,
+scrolling, back/forward), runs time on a virtual clock (timers, rAF, `Date`,
+idle callbacks, CSS and Web Animations) and seeds randomness (`Math.random`,
+`crypto`). Going back reloads the app and replays those inputs at full speed up
+to the chosen moment, with the app's own code rebuilding the screen.
+
+Server traffic is answered from the recording: `fetch` (streamed replies too,
+chunk by chunk at the pace they arrived), `XMLHttpRequest`, `EventSource` and
+`WebSocket`. So are observer callbacks and worker messages. Web storage,
+cookies and IndexedDB go back to how they were when the recording began.
+
+It rewinds the browser, not your server, so it suits prototypes whose backends
+don't remember state. Not covered: the Cache API / service workers, and
+cross-origin iframes.
+
+Requires Node 18+, and Vite 5 or newer for Vite apps and the plugin.
+
+## License
+
+[PolyForm Shield 1.0.0](LICENSE). Use it, change it and share it for anything,
+except building a product that competes with Retake.

package/bin/retake.js

@@ -0,0 +1,319 @@
+#!/usr/bin/env node
+// Retake CLI.
+//   retake [dev] <project> [--port 3014] [--code-branches] [-- ...dev server args]
+//     A Vite single-page app: runs the project's own Vite with the timeline
+//     added, from a wrapper config kept outside the project. A framework with
+//     its own dev server (Next, Nuxt, React Router, Remix, SvelteKit, Astro...):
+//     runs its dev command and puts Retake in front of it (src/server/front.js).
+//     Nothing in the project is touched (except with --code-branches, Vite
+//     only, which checks timelines' code out on disk).
+//   retake http://localhost:3000
+//     Puts Retake in front of a dev server that's already running.
+//   retake -- <dev command>
+//     Runs that command (e.g. `retake -- next dev`) and puts Retake in front.
+//   retake init
+//     Prints the lines that add Retake to a project's vite.config instead.
+//   retake mcp
+//     MCP server (stdio) for coding agents, talking to a running dev server.
+import fs from "node:fs"
+import os from "node:os"
+import path from "node:path"
+import crypto from "node:crypto"
+import { spawn } from "node:child_process"
+import { createRequire } from "node:module"
+import { fileURLToPath, pathToFileURL } from "node:url"
+import { detectProject, nextDebugChannelWarning, shellQuote, withArgs } from "../src/server/detect.js"
+import { runDevCommand } from "../src/server/child.js"
+
+const HOME = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..")
+const PKG = JSON.parse(fs.readFileSync(path.join(HOME, "package.json"), "utf8"))
+const CONFIGS = ["vite.config.ts", "vite.config.mts", "vite.config.cts", "vite.config.js", "vite.config.mjs", "vite.config.cjs"]
+const USAGE = `Retake ${PKG.version}: a time machine for your dev server
+
+Usage:
+  retake <project>                  run the project's dev server with the timeline
+                                    (Vite apps, Next, Nuxt, React Router, Remix,
+                                    SvelteKit, Astro...)
+  retake dev <project> [options]    same thing
+  retake http://localhost:3000      put the timeline in front of a running dev server
+  retake -- <dev command>           run that command with the timeline in front
+                                    (e.g. retake -- next dev, retake -- pnpm dev)
+  retake init                       print the vite.config lines instead
+  retake mcp [--url http://localhost:3014]
+                                    MCP server for coding agents (stdio)
+
+Options:
+  --port <n>          port to serve on (default 3014)
+  --root <dir>        where .retake/ (sessions, recordings) goes
+                      (default: the project, or this folder)
+  --code-branches     each timeline keeps its own version of the code
+                      (Vite apps only; rewrites files on disk)
+  --verbose           log every request to .retake/front.log (front server)
+  --                  after a project: arguments for its dev server
+                      (e.g. retake . -- --host); without one: the dev command
+  -v, --version       print the version
+  -h, --help          show this help`
+
+/** @returns {never} */
+function fail(msg, hint) {
+  console.error(`retake: ${msg}`)
+  if (hint) console.error(`        ${hint}`)
+  process.exit(1)
+}
+
+// Minimal argv parsing with validation. After `--`: with no project, the dev
+// command to run (`retake -- next dev`); otherwise arguments for the dev server.
+export function parseArgs(argv) {
+  const dash = argv.indexOf("--")
+  const own = dash < 0 ? argv : argv.slice(0, dash)
+  let passthrough = dash < 0 ? [] : argv.slice(dash + 1)
+  /** @type {{ cmd: string | null, project: string | null, upstream: string | null, command: string[] | null, root: string | null, verbose: boolean,
+   *   port: number, portSet?: boolean, codeBranches: boolean, url: string | null, passthrough: string[], help: boolean, version: boolean }} */
+  const out = { cmd: null, project: null, upstream: null, command: null, root: null, verbose: false, port: 3014, codeBranches: false, url: null, passthrough, help: false, version: false }
+  const positional = []
+  const value = (a, i, what) => {
+    const v = a.includes("=") ? a.slice(a.indexOf("=") + 1) : own[i]
+    if (v == null || v === "") throw new Error(`${a.split("=")[0]} needs ${what}`)
+    return v
+  }
+  for (let i = 0; i < own.length; i++) {
+    const a = own[i]
+    if (a === "-h" || a === "--help") out.help = true
+    else if (a === "-v" || a === "--version") out.version = true
+    else if (a === "--code-branches") out.codeBranches = true
+    else if (a === "--verbose") out.verbose = true
+    else if (a === "--port" || a.startsWith("--port=")) {
+      const v = a.includes("=") ? a.split("=")[1] : own[++i]
+      const n = Number(v)
+      if (v == null || v === "" || !Number.isInteger(n) || n < 1 || n > 65535) throw new Error(`--port needs a number between 1 and 65535 (got ${v == null ? "nothing" : JSON.stringify(v)})`)
+      out.port = n
+      out.portSet = true
+    } else if (a === "--url" || a.startsWith("--url=")) {
+      out.url = a.includes("=") ? a.split("=")[1] : own[++i]
+      if (!out.url) throw new Error("--url needs a value, like http://localhost:3014")
+    } else if (a === "--root" || a.startsWith("--root=")) {
+      out.root = value(a, a.includes("=") ? i : ++i, "a folder")
+    } else if (a.startsWith("-")) throw new Error(`unknown option ${a} (pass dev server options after --, e.g. retake . -- ${a})`)
+    else positional.push(a)
+  }
+  if (["dev", "init", "mcp", "help"].includes(positional[0])) out.cmd = positional.shift()
+  else if (positional.length) out.cmd = "dev" // a bare path (or URL) means dev
+  if (out.cmd === "help") out.help = true
+  const target = positional.shift() ?? null
+  if (target && /^https?:\/\//i.test(target)) {
+    try {
+      out.upstream = new URL(target).href
+    } catch {
+      throw new Error(`${JSON.stringify(target)} isn't a URL`)
+    }
+  } else out.project = target
+  if (positional.length) throw new Error(`unexpected argument ${JSON.stringify(positional[0])}`)
+  // `retake -- next dev`: no project, and the first word isn't an option.
+  if (!out.project && !out.upstream && passthrough.length && !passthrough[0].startsWith("-") && (out.cmd === null || out.cmd === "dev")) {
+    out.command = passthrough
+    out.passthrough = passthrough = []
+    out.cmd = "dev"
+  }
+  return out
+}
+
+// The project's own Vite (so its plugins match), found the way Node would find
+// it from the project, walking up to a workspace root. Falls back to ours.
+export function resolveVite(project) {
+  const ours = path.join(HOME, "package.json")
+  for (const from of [path.join(project, "package.json"), ours]) {
+    try {
+      const pkgPath = createRequire(from).resolve("vite/package.json")
+      const pkg = JSON.parse(fs.readFileSync(pkgPath, "utf8"))
+      const bin = typeof pkg.bin === "string" ? pkg.bin : pkg.bin && pkg.bin.vite
+      return { bin: path.join(path.dirname(pkgPath), bin || "bin/vite.js"), version: pkg.version, own: from === ours }
+    } catch {}
+  }
+  return null
+}
+
+// Wrapper config and Vite's dep cache live outside the project, keyed by the
+// project's absolute path so two projects with the same folder name don't clash.
+export function workDir(project) {
+  const hash = crypto.createHash("sha1").update(project).digest("hex").slice(0, 10)
+  const base = process.env.RETAKE_CACHE_DIR || path.join(os.tmpdir(), "retake")
+  return path.join(base, `${path.basename(project)}-${hash}`)
+}
+
+async function dev(opts) {
+  if (opts.upstream || opts.command) {
+    if (opts.codeBranches) fail("--code-branches only works on Vite apps (retake <project>)")
+    const root = path.resolve(opts.root || ".")
+    // `retake -- "next dev --turbo"` (one word) is a command line as it is.
+    const command = opts.command && (opts.command.length === 1 ? opts.command[0] : opts.command.map(shellQuote).join(" "))
+    // Run from a framework's folder, it's that framework (it tunes the runtime).
+    const here = opts.command ? detectProject(process.cwd()) : null
+    const framework = here && here.mode === "front" ? here.framework : null
+    return front({ ...opts, root, upstream: opts.upstream, command, cwd: process.cwd(), framework, dir: framework ? process.cwd() : null })
+  }
+  const project = path.resolve(opts.project || ".")
+  if (!fs.existsSync(project)) fail(`${project} doesn't exist`)
+  if (!fs.existsSync(path.join(project, "package.json"))) fail(`no package.json in ${project}`, "point retake at your app's folder, e.g. retake ./my-app, or run retake -- <your dev command>")
+  const found = detectProject(project)
+  if (found.mode === "front") {
+    if (opts.codeBranches) fail(`--code-branches only works on Vite apps, not ${found.framework}`, "drop --code-branches; everything else works the same")
+    if (found.framework === "next") {
+      const warning = nextDebugChannelWarning(project)
+      if (warning) console.warn(`retake: ${warning}`)
+    }
+    return front({ ...opts, root: path.resolve(opts.root || project), command: withArgs(found.command, opts.passthrough, found.pm), cwd: project, framework: found.framework, dir: project })
+  }
+  if (found.mode !== "vite") {
+    fail(`${found.reason}`, `run your dev server through Retake instead: retake -- <your dev command> (e.g. retake -- npm run dev), or retake http://localhost:<port> if it's already running`)
+  }
+  viteDev(project, opts)
+}
+
+// A Vite single-page app: the project's own Vite, with the plugin added from a
+// wrapper config outside the project.
+function viteDev(project, opts) {
+  const vite = resolveVite(project)
+  if (!vite) fail(`vite isn't installed for ${project}`, "run your package manager's install there first")
+  if (vite.own) console.warn(`retake: vite not found from ${project}; using retake's own vite ${vite.version}`)
+  const config = CONFIGS.map((f) => path.join(project, f)).find((f) => fs.existsSync(f))
+  const work = workDir(project)
+  fs.mkdirSync(work, { recursive: true })
+  // One wrapper (and dep cache) per port: Vite watches its config, so two runs
+  // on one project sharing a wrapper would restart each other on the wrong port.
+  const wrapper = path.join(work, `vite.config.${opts.port}.mjs`)
+  const url = (p) => JSON.stringify(pathToFileURL(p).href)
+  fs.writeFileSync(
+    wrapper,
+    `// Generated by retake; regenerated on every run.
+import { retake } from ${url(path.join(HOME, "src", "plugin.js"))}
+${config ? `import base from ${url(config)}` : "const base = {}"}
+
+export default async (env) => {
+  const cfg = (typeof base === "function" ? await base(env) : await base) || {}
+  return {
+    ...cfg,
+    root: cfg.root ? cfg.root : ${JSON.stringify(project)},
+    // Our own dep cache, so the project's node_modules/.vite is left alone.
+    cacheDir: ${JSON.stringify(path.join(work, `vite-${opts.port}`))},
+    plugins: [retake({ codeBranches: ${opts.codeBranches}, banner: true${opts.root ? `, root: ${JSON.stringify(path.resolve(opts.root))}` : ""} }), ...(cfg.plugins || [])],
+    server: { ...cfg.server, port: ${opts.port}, strictPort: true },
+  }
+}
+`,
+  )
+  const child = spawn(process.execPath, [vite.bin, "--config", wrapper, ...opts.passthrough], {
+    cwd: project,
+    stdio: "inherit",
+    env: { ...process.env, VITE_CONFIG_NATIVE_IGNORE_WARNING: "true", RETAKE_PROJECT: project },
+  })
+  child.on("exit", (code, signal) => process.exit(code ?? (signal ? 1 : 0)))
+  for (const sig of /** @type {NodeJS.Signals[]} */ (["SIGINT", "SIGTERM", "SIGHUP"])) process.on(sig, () => child.kill(sig))
+}
+
+// Front-server mode: Retake on --port, in front of a dev server that's
+// running (`upstream`) or that `command` starts.
+async function front(opts) {
+  const { startFront } = await import(pathToFileURL(path.join(HOME, "src", "server", "front.js")).href)
+  // Where the dev command listens isn't known until it says (or answers).
+  let found = /** @type {{ resolve: (url: string) => void, reject: (err: any) => void } | null} */ (null)
+  const upstream = opts.upstream || new Promise((resolve, reject) => (found = { resolve, reject }))
+  let label = opts.upstream ? new URL(opts.upstream).host : opts.command
+  let server
+  try {
+    server = await startFront({
+      upstream,
+      port: opts.port,
+      root: opts.root,
+      verbose: opts.verbose,
+      framework: opts.framework,
+      dir: opts.dir,
+      watch: opts.dir || (opts.command ? opts.cwd : null), // whose edits retire kept pages
+      get label() {
+        return label // the waiting page's "Waiting for next dev on :3015…"
+      },
+    })
+  } catch (err) {
+    if (err.code === "EADDRINUSE") fail(`port ${opts.port} is in use`, `pick another with --port, e.g. --port ${opts.port === 65535 ? 3014 : opts.port + 1}`)
+    throw err
+  }
+  // "Retake  timeline docked at http://localhost:3014  (in front of next dev on :3015)"
+  const banner = (url, what) => {
+    console.log(`\n  \x1b[1mRetake\x1b[0m  timeline docked at ${server.url}  (in front of ${what})`)
+    console.log(`          Using sign-in? Sign in at ${new URL(url).origin} first.\n`)
+  }
+  const stop = async (code) => {
+    await server.close().catch(() => {})
+    process.exit(code)
+  }
+  if (opts.upstream) {
+    banner(opts.upstream, new URL(opts.upstream).origin)
+    for (const sig of ["SIGINT", "SIGTERM", "SIGHUP"]) process.on(sig, () => stop(0))
+    return
+  }
+  // PORT is the dev server's, unless it's the one Retake took.
+  const env = { ...process.env }
+  if (Number(env.PORT) === server.port) delete env.PORT
+  const dev = await runDevCommand(opts.command, { cwd: opts.cwd, env })
+  if (dev.portTaken) console.warn(`retake: PORT ${dev.portTaken} is already in use; the dev command gets PORT=${dev.port}`)
+  label = `${opts.command} on :${dev.port}`
+  for (const sig of /** @type {NodeJS.Signals[]} */ (["SIGINT", "SIGTERM", "SIGHUP"])) {
+    process.on(sig, () => {
+      dev.stop(sig)
+      // A dev server that ignores the signal gets SIGKILL after 5 s.
+      setTimeout(() => dev.stop("SIGKILL"), 5000).unref()
+    })
+  }
+  // Exit with the dev command's exit code, once what it started has stopped
+  // too (a wrapper can exit on Ctrl-C before its server does: that one gets
+  // SIGKILL 5 s on, not left running on its own).
+  dev.exited.then(async (code) => {
+    await dev.reap(5000)
+    stop(code)
+  })
+  try {
+    const url = await dev.url
+    found?.resolve(url)
+    label = `${opts.command} on :${new URL(url).port}`
+    banner(url, label)
+  } catch (err) {
+    found?.reject(err)
+  }
+}
+function init() {
+  console.log(`Add Retake to vite.config (dev only; it does nothing in builds):
+
+  import { retake } from "retake-dev"
+
+  export default defineConfig({
+    plugins: [retake(), /* ...your plugins */],
+  })
+
+Options: retake({ codeBranches: true }) gives each timeline its own version of the code.
+Or leave the project untouched and run:  npx retake-dev .
+(Next, Nuxt, React Router, SvelteKit, Astro... too: it puts Retake in front of your dev server.)`)
+}
+
+async function main() {
+  let opts
+  try {
+    opts = parseArgs(process.argv.slice(2))
+  } catch (err) {
+    fail(err.message, "run retake --help for usage")
+  }
+  if (opts.version) return console.log(PKG.version)
+  if (opts.help || !opts.cmd) {
+    console.log(USAGE)
+    return
+  }
+  if (opts.cmd === "dev") return dev(opts).catch((err) => fail(err.message))
+  if (opts.cmd === "init") return init()
+  if (opts.cmd === "mcp") {
+    const { runMcp } = await import(pathToFileURL(path.join(HOME, "src", "server", "mcp.js")).href)
+    // Without --url/--port it finds the server from <cwd>/.retake/server.json.
+    return runMcp({ url: opts.url || process.env.RETAKE_URL || (opts.portSet ? `http://localhost:${opts.port}` : null) })
+  }
+}
+
+// Only run when executed, not when imported by tests.
+const invoked = process.argv[1] && fs.realpathSync(process.argv[1]) === fileURLToPath(import.meta.url)
+if (invoked) main()