retake-dev 0.4.0

package/src/server/mcp.js

@@ -0,0 +1,332 @@
+// `retake mcp`: an MCP server (stdio, JSON-RPC 2.0, one message per line) that
+// lets a coding agent read the notes left in the dock and answer them. It
+// talks to the running dev server over HTTP (CONTRACT.md "Server HTTP"), so
+// changes show up in the dock live.
+//
+//   npx -y retake-dev mcp   (registered as an MCP server in the coding agent)
+//
+// Finds the dev server from --url / RETAKE_URL, else <cwd or a parent>/.retake/server.json.
+import fs from "node:fs"
+import path from "node:path"
+
+const PROTOCOLS = ["2025-06-18", "2025-03-26", "2024-11-05"]
+const PKG = JSON.parse(fs.readFileSync(new URL("../../package.json", import.meta.url), "utf8"))
+
+function findServerInfo(from = process.cwd()) {
+  for (let dir = path.resolve(from); ; dir = path.dirname(dir)) {
+    const f = path.join(dir, ".retake", "server.json")
+    if (fs.existsSync(f)) {
+      try {
+        return JSON.parse(fs.readFileSync(f, "utf8"))
+      } catch {}
+    }
+    if (path.dirname(dir) === dir) return null
+  }
+}
+
+/** @param {{ url?: string | null, token?: string }} [options] */
+export function createClient({ url, token } = {}) {
+  /** @type {{ url: string, token?: string } | null} */
+  let info = null
+  const base = () => {
+    if (url) return url.replace(/\/$/, "")
+    info = info || findServerInfo()
+    if (!info) throw new Error("no running Retake dev server found. Start one with `npx retake-dev .` in the project (or pass --url)")
+    return info.url.replace(/\/$/, "")
+  }
+  async function getToken() {
+    if (token) return token
+    info = info || findServerInfo()
+    if (info && info.token && (!url || info.url.replace(/\/$/, "") === base())) return (token = info.token)
+    const html = await (await fetch(base() + "/")).text()
+    const m = html.match(/__RETAKE_TOKEN = "([0-9a-f]+)"/)
+    if (!m) throw new Error(`${base()} doesn't look like a Retake dev server`)
+    return (token = m[1])
+  }
+  async function call(method, p, body) {
+    let res
+    try {
+      res = await fetch(base() + p, {
+        method,
+        headers: body !== undefined || method !== "GET" ? { "content-type": "application/json", "x-retake-token": await getToken() } : {},
+        body: body === undefined ? undefined : JSON.stringify(body),
+      })
+    } catch (err) {
+      throw new Error(`can't reach the Retake dev server at ${base()} (${err.cause ? err.cause.code || err.cause.message : err.message}). Is it running?`)
+    }
+    const text = await res.text()
+    if (!res.ok) throw new Error(`${method} ${p} → ${res.status}: ${text.slice(0, 200)}`)
+    return text ? JSON.parse(text) : null
+  }
+  return {
+    base,
+    session: () => call("GET", "/__retake/session"),
+    notes: () => call("GET", "/__retake/notes"),
+    note: (id) => call("GET", `/__retake/notes/${encodeURIComponent(id)}`),
+    patch: (id, body) => call("PATCH", `/__retake/notes/${encodeURIComponent(id)}`, body),
+    // Resolves on the next matching SSE event (or null after `ms`).
+    async nextEvent(types, ms) {
+      const ac = new AbortController()
+      const timer = setTimeout(() => ac.abort(), ms)
+      try {
+        const res = await fetch(base() + "/__retake/events", { signal: ac.signal })
+        if (!res.body) return null
+        const reader = res.body.pipeThrough(new TextDecoderStream()).getReader()
+        let buf = ""
+        for (;;) {
+          const { done, value } = await reader.read()
+          if (done) return null
+          buf += value
+          let i
+          while ((i = buf.indexOf("\n\n")) >= 0) {
+            const block = buf.slice(0, i)
+            buf = buf.slice(i + 2)
+            const ev = /^event: (.*)$/m.exec(block)
+            const data = /^data: (.*)$/m.exec(block)
+            if (ev && types.includes(ev[1])) {
+              ac.abort()
+              return { event: ev[1], data: data ? JSON.parse(data[1]) : null }
+            }
+          }
+        }
+      } catch (err) {
+        if (err.name === "AbortError") return null
+        throw err
+      } finally {
+        clearTimeout(timer)
+      }
+    },
+  }
+}
+
+// ---- presenting notes -----------------------------------------------------------
+
+const fmt = (ms) => {
+  const s = Math.max(0, Number(ms) || 0) / 1000
+  return `${String(Math.floor(s / 60)).padStart(2, "0")}:${(s % 60).toFixed(2).padStart(5, "0")}`
+}
+
+function summary(n, session) {
+  const b = (session.branches || []).find((x) => String(x.id) === String(n.branchId))
+  return {
+    id: n.id,
+    status: n.status || "pending",
+    text: n.text,
+    timeline: b ? b.name : n.branchId,
+    at: fmt(n.t),
+    selector: n.selector || (n.el && n.el.selector) || null,
+    component: n.component || (n.el && n.el.components && n.el.components[0]) || null,
+    source: n.source ? `${n.source.file}${n.source.line ? ":" + n.source.line : ""}` : null,
+    replies: (n.replies || []).length,
+  }
+}
+
+function clipText(c) {
+  const name = c.label ? `${c.label} ` : ""
+  const at = `${Math.round(Number(c.offset) || 0)}ms into`
+  return Number(c.duration) > 0 ? `${at} a ${Math.round(c.duration)}ms ${name}animation (clip ${c.id})` : `${at} a running ${name}animation (clip ${c.id})`
+}
+
+// Everything an agent needs to act on one note, as readable text.
+function describe(n, session) {
+  const b = (session.branches || []).find((x) => String(x.id) === String(n.branchId))
+  const parent = b && (session.branches || []).find((x) => String(x.id) === String(b.parentId))
+  const el = n.el || {}
+  const lines = [
+    `Note ${n.id} (${n.status || "pending"}) on timeline "${b ? b.name : n.branchId}" at ${fmt(n.t)}`,
+    parent ? `That timeline branched from "${parent.name}" at ${fmt(b.forkAt)}${b.codeVersion ? `; it runs code version ${b.codeVersion}` : ""}.` : null,
+    "",
+    `What the user wants: ${n.text}`,
+    "",
+    `Element: ${el.label || ""}${el.text ? ` "${el.text}"` : ""}`.trim(),
+    `Selector: ${n.selector || el.selector || "?"}`,
+    n.component || (el.components && el.components.length) ? `Component: ${n.component || el.components.join(" < ")}` : null,
+    n.source ? `Source: ${n.source.file}${n.source.line ? ":" + n.source.line : ""}` : null,
+    n.classes && n.classes.length ? `Classes: ${[].concat(n.classes).join(" ")}` : null,
+    n.rect ? `Box: ${Math.round(n.rect.w)}×${Math.round(n.rect.h)} at (${Math.round(n.rect.x)}, ${Math.round(n.rect.y)})` : null,
+    n.clip ? `During an animation: ${clipText(n.clip)}` : null,
+    el.page ? `Page: ${el.page}` : null,
+  ]
+  if ((n.replies || []).length) {
+    lines.push("", "Conversation:")
+    for (const r of n.replies) lines.push(`- ${r.from}: ${r.text}`)
+  }
+  return lines.filter((l) => l != null).join("\n")
+}
+
+// ---- tools --------------------------------------------------------------------------
+
+const TOOLS = [
+  {
+    name: "list_notes",
+    description: "List the notes left in the Retake timeline (things the user wants changed in the prototype). Defaults to notes still waiting on you (pending or acknowledged).",
+    inputSchema: { type: "object", properties: { status: { type: "string", enum: ["open", "pending", "acknowledged", "resolved", "dismissed", "all"], description: "Filter; 'open' (default) = pending + acknowledged" } } },
+  },
+  {
+    name: "get_note",
+    description: "Everything about one note: what the user asked, the element (selector, React component, source file:line, classes, size), the moment and timeline, and the conversation so far.",
+    inputSchema: { type: "object", properties: { id: { type: ["string", "number"] } }, required: ["id"] },
+  },
+  {
+    name: "get_active_timeline",
+    description: "Which timeline the user is looking at in the Retake dock, how it relates to the others (branch point, code version) and its open notes.",
+    inputSchema: { type: "object", properties: {} },
+  },
+  {
+    name: "acknowledge",
+    description: "Tell the user you've seen a note and are working on it (its pin turns to 'acknowledged' in the dock). Optionally add a short message.",
+    inputSchema: { type: "object", properties: { id: { type: ["string", "number"] }, message: { type: "string" } }, required: ["id"] },
+  },
+  {
+    name: "resolve",
+    description: "Mark a note done, with a one or two sentence summary of what you changed. The summary shows in the dock.",
+    inputSchema: { type: "object", properties: { id: { type: ["string", "number"] }, summary: { type: "string" } }, required: ["id", "summary"] },
+  },
+  {
+    name: "reply",
+    description: "Reply on a note without changing its status (ask a question, explain a trade-off).",
+    inputSchema: { type: "object", properties: { id: { type: ["string", "number"] }, text: { type: "string" } }, required: ["id", "text"] },
+  },
+  {
+    name: "watch_notes",
+    description: "Wait until the user adds a note or replies to one, then return what changed. Returns an empty list on timeout.",
+    inputSchema: { type: "object", properties: { timeout_seconds: { type: "number", description: "How long to wait (default 60, max 600)" } } },
+  },
+]
+
+const isOpen = (n) => !n.status || n.status === "pending" || n.status === "acknowledged"
+
+export function createTools(client) {
+  const byId = async (id) => {
+    const note = await client.note(id).catch((err) => {
+      if (/→ 404/.test(err.message)) throw new Error(`no note with id ${id}; list_notes shows the ids`)
+      throw err
+    })
+    return note
+  }
+  const handlers = {
+    async list_notes({ status = "open" } = {}) {
+      const session = await client.session()
+      const notes = (session.notes || []).filter((n) => (status === "all" ? true : status === "open" ? isOpen(n) : (n.status || "pending") === status))
+      return { count: notes.length, notes: notes.map((n) => summary(n, session)) }
+    },
+    async get_note({ id }) {
+      const [session, note] = await Promise.all([client.session(), byId(id)])
+      return describe(note, session)
+    },
+    async get_active_timeline() {
+      const session = await client.session()
+      const branches = session.branches || []
+      const active = branches.find((b) => String(b.id) === String(session.activeId)) || null
+      const parent = active && branches.find((b) => String(b.id) === String(active.parentId))
+      return {
+        active: active && { id: active.id, name: active.name, forkAt: fmt(active.forkAt), parent: parent ? parent.name : null, codeVersion: active.codeVersion || null },
+        timelines: branches.map((b) => ({ id: b.id, name: b.name, parent: b.parentId, forkAt: fmt(b.forkAt), codeVersion: b.codeVersion || null })),
+        openNotes: (session.notes || []).filter((n) => isOpen(n) && active && String(n.branchId) === String(active.id)).map((n) => summary(n, session)),
+      }
+    },
+    async acknowledge({ id, message }) {
+      await byId(id)
+      const n = await client.patch(id, { status: "acknowledged", ...(message ? { reply: message } : {}) })
+      return `Acknowledged note ${n.id}.`
+    },
+    async resolve({ id, summary: text }) {
+      if (!text) throw new Error("resolve needs a summary of what you changed")
+      await byId(id)
+      const n = await client.patch(id, { status: "resolved", reply: text })
+      return `Resolved note ${n.id}.`
+    },
+    async reply({ id, text }) {
+      if (!text) throw new Error("reply needs text")
+      await byId(id)
+      await client.patch(id, { reply: text })
+      return `Replied on note ${id}.`
+    },
+    async watch_notes({ timeout_seconds = 60 } = {}) {
+      const ms = Math.min(Math.max(Number(timeout_seconds) || 60, 1), 600) * 1000
+      const key = (n) => `${n.status || "pending"}|${(n.replies || []).filter((r) => r.from === "user").length}|${n.text}`
+      const before = new Map(((await client.session()).notes || []).map((n) => [String(n.id), key(n)]))
+      const deadline = Date.now() + ms
+      while (Date.now() < deadline) {
+        const got = await client.nextEvent(["session", "note-updated"], deadline - Date.now())
+        if (!got) break
+        const session = await client.session()
+        const changed = (session.notes || []).filter((n) => before.get(String(n.id)) !== key(n))
+        // Ignore what agents did (replies from "agent" don't change the key).
+        if (changed.length) return { changed: changed.map((n) => ({ ...summary(n, session), new: !before.has(String(n.id)) })) }
+      }
+      return { changed: [] }
+    },
+  }
+  return { list: TOOLS, handlers }
+}
+
+/** @param {{ url?: string }} [options] */
+export async function runMcp({ url } = {}) {
+  const client = createClient({ url: url || null })
+  const tools = createTools(client)
+  const send = (msg) => process.stdout.write(JSON.stringify(msg) + "\n")
+  const reply = (id, result) => send({ jsonrpc: "2.0", id, result })
+  const error = (id, code, message) => send({ jsonrpc: "2.0", id, error: { code, message } })
+
+  async function handle(msg) {
+    const { id, method, params } = msg
+    if (method === "initialize") {
+      const asked = params && params.protocolVersion
+      return reply(id, {
+        protocolVersion: PROTOCOLS.includes(asked) ? asked : PROTOCOLS[0],
+        capabilities: { tools: { listChanged: false } },
+        serverInfo: { name: "retake", version: PKG.version },
+        instructions: "Notes are change requests the user left on elements of their prototype in the Retake timeline. list_notes, then get_note for details; acknowledge when you start, resolve with a summary when done.",
+      })
+    }
+    if (method === "notifications/initialized" || (method && method.startsWith("notifications/"))) return
+    if (method === "ping") return reply(id, {})
+    if (method === "tools/list") return reply(id, { tools: tools.list })
+    if (method === "tools/call") {
+      const h = tools.handlers[params && params.name]
+      if (!h) return error(id, -32602, `unknown tool ${params && params.name}`)
+      try {
+        const out = await h(params.arguments || {})
+        return reply(id, { content: [{ type: "text", text: typeof out === "string" ? out : JSON.stringify(out, null, 2) }] })
+      } catch (err) {
+        return reply(id, { content: [{ type: "text", text: err.message }], isError: true })
+      }
+    }
+    if (id !== undefined) error(id, -32601, `method not found: ${method}`)
+  }
+
+  let buf = ""
+  let inFlight = 0
+  let ended = false
+  const maybeExit = () => ended && inFlight === 0 && process.exit(0)
+  process.stdin.setEncoding("utf8")
+  process.stdin.on("data", (chunk) => {
+    buf += chunk
+    let i
+    while ((i = buf.indexOf("\n")) >= 0) {
+      const line = buf.slice(0, i).trim()
+      buf = buf.slice(i + 1)
+      if (!line) continue
+      let msg
+      try {
+        msg = JSON.parse(line)
+      } catch {
+        error(null, -32700, "parse error")
+        continue
+      }
+      inFlight++
+      handle(msg)
+        .catch((err) => msg.id !== undefined && error(msg.id, -32603, err.message))
+        .finally(() => {
+          inFlight--
+          maybeExit()
+        })
+    }
+  })
+  // The client closed its end: answer what's still in flight, then leave.
+  process.stdin.on("end", () => {
+    ended = true
+    maybeExit()
+  })
+}

package/src/shell/00-state.js

@@ -0,0 +1,85 @@
+// Shared pieces of the dock. The shell files are concatenated into one scope;
+// everything they share that changes over time lives on `D`, so a file never
+// reaches into another file's variables.
+const $ = (s) => document.querySelector(s)
+const KEY = "retake:"
+const store = {
+  get(k, fallback) {
+    try {
+      const v = localStorage.getItem(KEY + k)
+      return v == null ? fallback : JSON.parse(v)
+    } catch {
+      return fallback
+    }
+  },
+  set(k, v) {
+    try {
+      localStorage.setItem(KEY + k, JSON.stringify(v))
+    } catch {}
+  },
+}
+
+const D = {
+  // frames
+  frame: null, // the visible prototype frame
+  PT: null, // its runtime (window.__retake inside it)
+  // The one frame being built behind it (10-dock.js): { id, frame, pt, stash,
+  // url, viewport, branchId, sig, target, play, fork, visible, startedAt, via,
+  // restarts }. play / fork: do that once it's in. visible: nothing on screen
+  // shows its moment, so the user is waiting for it (waits()).
+  building: null,
+  buildSeq: 0, // numbers builds (and checkpoints), so a frame that reloaded itself is told apart
+  holdSwap: false, // tests: keep a finished build behind (it doesn't swap in)
+  buildWatchdogMs: 10000, // a build whose page loaded without starting it is tried again after this (tests shorten it)
+  cp: null, // a hidden paused frame at an earlier moment, to rewind from (12-checkpoint.js)
+  last: null, // the last runtime state seen
+  // timelines
+  branches: [], // { id, name, forkAt, parentId, json, end, born, version }
+  activeId: 0,
+  branchSeq: 0,
+  switching: false,
+  frameBranch: 0, // the timeline the visible frame is playing
+  // what's been said about them
+  notes: [],
+  markers: [], // bookmarks dropped with M: { id, t, branchId }
+  markerSeq: 0,
+  // pointer and tools
+  dragT: null, // the time under the playhead while scrubbing
+  dragX0: 0, // where the press was, and whether the pointer has moved off it (3px)
+  dragMoved: false,
+  frameNo: 0, // dock frames drawn (one direct scrub per frame)
+  branchT: null, // where a Control-click on the track would branch
+  hot: null, // what the pointer is over: { kind: "clip" | "mark", i }
+  keyT: null, // where arrow keys have taken the playhead, until it's built
+  snapT: null, // what the playhead snapped to while scrubbing
+  lanes: null, // lane id → { y, thin }, from the last draw
+  clipBars: [],
+  picking: null, // "comment" | "select" | null
+  metaHeld: false,
+  scopeEl: null, // the element the Select tool scoped scrubbing to
+  // dock size
+  height: store.get("height", 200),
+  view: null, // the window of time on the timeline (20-timeline.js)
+}
+
+const fmt = (ms) => {
+  const s = Math.max(0, ms) / 1000
+  return `${String(Math.floor(s / 60)).padStart(2, "0")}:${(s % 60).toFixed(2).padStart(5, "0")}`
+}
+const esc = (s) => String(s).replace(/[&<>"]/g, (c) => ({ "&": "&amp;", "<": "&lt;", ">": "&gt;", '"': "&quot;" })[c])
+const clamp = (v, a, b) => Math.min(Math.max(v, a), b)
+
+const activeBranch = () => D.branches.find((b) => b.id === D.activeId)
+const branchById = (id) => D.branches.find((b) => b.id === id)
+
+// Is the user waiting for this build (the readout says Building)?
+const waits = (b) => !!b && !!(b.play || b.fork || b.visible)
+// Do two moments of the active recording look exactly the same (no frame or
+// input between them)? The runtime knows; an older one is asked for 1ms.
+function samePlace(a, b) {
+  if (a == null || b == null) return false
+  try {
+    if (D.PT && typeof D.PT.sameMoment === "function") return D.PT.sameMoment(a, b)
+  } catch {}
+  return Math.abs(a - b) < 1
+}

package/src/shell/05-api.js

@@ -0,0 +1,136 @@
+// What the dock asks the runtime, through one door. The runtime's own
+// timeline() / clipAt() / isInteractive() are used when it has them
+// (CONTRACT.md). With an older runtime the same answers are derived from what
+// it does have (activity() and history()), so the dock always has something
+// true to draw.
+const MARKER_KINDS = { pointerdown: "click", click: "click", keydown: "key", input: "input", submit: "submit", popstate: "route", hashchange: "route" }
+
+let timelineMemo = { at: -1, key: "", value: null }
+
+function derivedTimeline(pt, s) {
+  const h = pt.history()
+  const markers = []
+  for (const ev of h.events || []) {
+    const kind = MARKER_KINDS[ev.type]
+    if (!kind || ev.t < s.start) continue
+    // One marker per click, not per pointerdown/click pair.
+    if (ev.type === "click" && markers.some((m) => m.kind === "click" && Math.abs(m.t - ev.t) < 60)) continue
+    markers.push({ t: ev.t, kind, label: kind === "key" ? ev.key || "" : "" })
+  }
+  // Each animation the runtime drove, from its debug log; failing that, the
+  // merged bands of activity().
+  let clips = []
+  try {
+    clips = pt.debug().anims.map((a, i) => ({
+      id: "a" + i,
+      start: a.vStart,
+      end: a.vEnd == null || a.vEnd === 0 ? (a.state === "running" ? null : a.vStart) : a.vEnd,
+      kind: "animation",
+      label: a.target ? String(a.target) : "animation",
+      selector: a.target && /^[\w-]+$/.test(a.target) ? "#" + a.target : "",
+    }))
+  } catch {
+    const act = pt.activity ? pt.activity() : { bands: [] }
+    clips = act.bands.map(([a, b], i) => ({ id: "band" + i, start: a, end: b, kind: "animation", label: "animation", selector: "" }))
+  }
+  const vp = h.viewport || null
+  return { now: s.now, end: s.end, viewport: vp, markers, clips, derived: true }
+}
+
+// Cached for a few frames; timeline() walks the whole recording.
+function timeline() {
+  const pt = D.PT
+  const s = D.last
+  if (!pt || !s) return { now: 0, end: 0, viewport: null, markers: [], clips: [] }
+  const key = `${D.activeId}:${s.end}:${s.now}:${s.seeking}`
+  const now = performance.now()
+  if (timelineMemo.value && timelineMemo.pt === pt && (timelineMemo.key === key || now - timelineMemo.at < 120)) return timelineMemo.value
+  let value
+  try {
+    value = typeof pt.timeline === "function" ? pt.timeline() : derivedTimeline(pt, s)
+  } catch (err) {
+    value = timelineMemo.value || { now: s.now, end: s.end, viewport: null, markers: [], clips: [] }
+  }
+  value.markers = value.markers || []
+  value.clips = value.clips || []
+  timelineMemo = { at: now, key, value, pt }
+  return value
+}
+
+// The clip playing at t (on an element, if given): { clip, offset } or null.
+function clipAt(t, selector) {
+  const pt = D.PT
+  if (pt && typeof pt.clipAt === "function") {
+    try {
+      return pt.clipAt(t, selector) || null
+    } catch {}
+  }
+  const end = (c) => (c.end == null ? (D.last ? D.last.end : t) : c.end)
+  const all = timeline().clips.filter((c) => c.start <= t && t <= end(c))
+  const pick = (selector && all.find((c) => c.selector && c.selector === selector)) || all[all.length - 1]
+  return pick ? { clip: pick, offset: t - pick.start } : null
+}
+
+// Can the user act in the app right now? Only at the live edge. In the past
+// the app is view-only, like a paused video.
+function isInteractive(s = D.last) {
+  const pt = D.PT
+  if (pt && typeof pt.isInteractive === "function") {
+    try {
+      return !!pt.isInteractive()
+    } catch {}
+  }
+  if (!s || !s.started) return true
+  return !!s.playing && !s.future && !s.previewing
+}
+
+function setToolActive(on) {
+  const pt = D.PT
+  if (pt && typeof pt.setToolActive === "function") {
+    try {
+      pt.setToolActive(!!on)
+    } catch {}
+  }
+}
+
+// Play: from the past it replays, and at the end it's live again.
+function play() {
+  const pt = D.PT
+  const s = state()
+  if (!pt || !s) return
+  // The moment on show is still being built behind: it plays once it's in.
+  const b = D.building
+  if (b && b.target != null) {
+    b.play = true
+    return
+  }
+  // A preview with nothing building (a scoped one): play from that moment.
+  if (s.previewing && typeof pt.buildAt === "function") return goTo(s.previewAt, { play: true })
+  if (typeof pt.play === "function") {
+    quietCheckpoint()
+    return pt.play()
+  }
+  // (A seek to exactly where it is doesn't move, so nudge it a millisecond.)
+  if (s.previewing) return pt.seek(Math.min(s.previewAt + 1, s.end), true)
+  if (s.future) return pt.seek(Math.min(s.now + 1, s.end), true)
+  pt.record()
+}
+function togglePlay() {
+  const s = state()
+  if (!D.PT || !s) return
+  if (D.dragT != null) return // mid-drag: letting go decides
+  // Keys just stepped somewhere: play from there.
+  if (D.keyT != null) {
+    const t = D.keyT
+    D.keyT = null
+    clearTimeout(keyTimer)
+    return goTo(t, { play: true })
+  }
+  // Waiting to play a moment being built: stop waiting (it carries on behind).
+  if (D.building && D.building.play) {
+    D.building.play = false
+    return
+  }
+  if (s.playing) D.PT.pause()
+  else play()
+}