get-handoff 1.0.0

package/bin/handoff.mjs

@@ -0,0 +1,104 @@
+#!/usr/bin/env node
+import { readFileSync, writeFileSync } from "node:fs";
+import { basename } from "node:path";
+import { parsePlan } from "../src/plan.js";
+import { openBrowser } from "../src/browser.js";
+import { walkPlan } from "../src/walk.js";
+import { buildPayload } from "../src/payload.js";
+import { uploadFrames, uploadClips, createDraft, revokeWalkthrough } from "../src/api.js";
+import { readGitContext } from "../src/git.js";
+
+const args = process.argv.slice(2);
+const cmd = args[0];
+
+if (!["walk", "revoke"].includes(cmd) || !args[1]) {
+  console.error(`handoff walk <план.md> [опции]
+handoff revoke <слаг|id>  — закрыть доступ к уже разосланной ссылке
+
+  --attach <url>     подключиться к запущенному браузеру (по умолчанию — свой профиль)
+  --headless         не показывать окно
+  --out <файл>       записать тело запроса в файл вместо создания черновика
+  --api <url>        база edge-функций (или HANDOFF_API)
+  --key <ключ>       agent key (или HANDOFF_KEY)
+
+Сводку «что изменилось» CLI не пишет: её дописывает агент, глядя на свой диff
+и на снятые кадры, — и только он может выполнить правило «пункт ссылается на шаг».`);
+  process.exit(1);
+}
+
+const opt = (name, fallback = null) => {
+  const i = args.indexOf(`--${name}`);
+  return i >= 0 ? args[i + 1] : fallback;
+};
+const has = (name) => args.includes(`--${name}`);
+
+const cfgEarly = {
+  apiBase: opt("api", process.env.HANDOFF_API ?? "http://127.0.0.1:54321/functions/v1"),
+  agentKey: opt("key", process.env.HANDOFF_KEY ?? ""),
+};
+
+// Отзыв — единственная кнопка «стоп» для ссылки, которая уже у людей в чатах.
+if (cmd === "revoke") {
+  if (!cfgEarly.agentKey) {
+    console.error("Нужен agent key: --key или HANDOFF_KEY.");
+    process.exit(2);
+  }
+  const res = await revokeWalkthrough(args[1], cfgEarly);
+  console.log(res.alreadyRevoked
+    ? `Ссылка ${res.slug} и так была отозвана.`
+    : `Ссылка ${res.slug} отозвана — страница больше не открывается.`);
+  process.exit(0);
+}
+
+const plan = parsePlan(readFileSync(args[1], "utf8"));
+// Файл плана — это и есть личность прогона: `help.md` остаётся `help.md`,
+// как бы ни звучал заголовок внутри.
+plan.planKey = basename(args[1]).replace(/\.md$/i, "");
+const cfg = {
+  apiBase: opt("api", process.env.HANDOFF_API ?? "http://127.0.0.1:54321/functions/v1"),
+  agentKey: opt("key", process.env.HANDOFF_KEY ?? ""),
+};
+
+console.log(`Прогон «${plan.title}» — ${plan.steps.length} шагов на ${plan.origin}`);
+const { page, close } = await openBrowser({ attach: opt("attach"), headless: has("headless") });
+let shots;
+try {
+  shots = await walkPlan(page, plan);
+} finally {
+  await close();
+}
+
+const failed = shots.filter((s) => s.status === "failed");
+for (const s of shots) console.log(`  ${s.status === "ok" ? "снят" : "ПРОВАЛ"}  ${s.title}${s.failure ? " — " + s.failure : ""}`);
+
+const outFile = opt("out");
+
+// С ключом кадры заливаются всегда — даже когда результат уходит в файл.
+// Иначе агент не смог бы сделать то, ради чего труд и разделён: посмотреть на
+// СНЯТЫЕ кадры, дописать summary и только потом создать черновик. Без ключа
+// остаётся сухой режим: посмотреть, что сняли, не трогая облако.
+// Сперва стоп-кадры, потом клипы: клип — украшение, и его заливка уже не может
+// отнять у шага снятый кадр.
+const framed = cfg.agentKey ? await uploadFrames(shots, cfg) : shots;
+const uploaded = cfg.agentKey ? await uploadClips(framed, cfg) : framed;
+const payload = buildPayload(plan, uploaded, readGitContext());
+
+if (outFile) {
+  writeFileSync(outFile, JSON.stringify(payload, null, 2));
+  console.log(`\nТело запроса записано в ${outFile}${cfg.agentKey ? " (кадры залиты)" : " (кадры НЕ залиты — нет ключа)"}.`);
+  console.log("Допиши summary — каждый пункт со ссылкой на шаг — и создай черновик:");
+  console.log(`  curl -X POST $HANDOFF_API/walkthrough-create -H "Authorization: Bearer <ключ>" \\
+       -H "content-type: application/json" --data @${outFile}`);
+  process.exit(failed.length ? 1 : 0);
+}
+
+if (!cfg.agentKey) {
+  console.error("\nНужен agent key: --key или HANDOFF_KEY.");
+  process.exit(2);
+}
+const draft = await createDraft(payload, cfg);
+
+console.log(`\nЧерновик готов: ${draft.walkthroughId} (slug ${draft.slug})`);
+console.log("Сводка пуста — допиши её и опубликуй через walkthrough-publish.");
+if (failed.length) console.log(`Внимание: ${failed.length} шаг(ов) провалились — посмотри перед публикацией.`);
+process.exit(failed.length ? 1 : 0);

package/package.json

@@ -0,0 +1,19 @@
+{
+  "name": "get-handoff",
+  "version": "1.0.0",
+  "type": "module",
+  "bin": { "handoff": "./bin/handoff.mjs", "get-handoff": "./bin/handoff.mjs" },
+  "files": ["bin/", "src/", "!src/**/*.test.js"],
+  "publishConfig": { "access": "public" },
+  "dependencies": {
+    "playwright-core": "^1.61.0"
+  },
+  "scripts": {
+    "test": "vitest run",
+    "smoke:capture": "node e2e/capture-smoke.mjs"
+  },
+  "devDependencies": {
+    "jsdom": "^25.0.1",
+    "vitest": "^2.1.9"
+  }
+}

package/src/api.js

@@ -0,0 +1,82 @@
+// Тонкий клиент к edge-функциям части 1. fetch передаётся параметром —
+// так его подменяют тесты, и так же он берётся из окружения в бою.
+
+import { timeline } from "./clip.js";
+
+export function pngDataUrl(bytes) {
+  return `data:image/png;base64,${Buffer.from(bytes).toString("base64")}`;
+}
+
+export async function uploadFrames(shots, cfg, fetchImpl = fetch) {
+  const out = [];
+  for (const shot of shots) {
+    if (!shot.png) { out.push({ ...shot, screenshotPath: null }); continue; }
+    const res = await fetchImpl(`${cfg.apiBase}/screenshot-upload`, {
+      method: "POST",
+      headers: { Authorization: `Bearer ${cfg.agentKey}`, "content-type": "application/json" },
+      body: JSON.stringify({ dataUrl: pngDataUrl(shot.png) }),
+    });
+    const body = await res.json().catch(() => ({}));
+    if (!res.ok) throw new Error(`не удалось залить кадр: ${body.error ?? res.status}`);
+    out.push({ ...shot, screenshotPath: body.path });
+  }
+  return out;
+}
+
+export function jpegDataUrl(base64) {
+  return `data:image/jpeg;base64,${base64}`;
+}
+
+// Кадры клипа льются тем же screenshot-upload, что и стоп-кадры (он принимает
+// JPEG). Клип — украшение: если кадр не залился, шаг остаётся со стоп-кадром,
+// а прогон не падает.
+export async function uploadClips(shots, cfg, fetchImpl = fetch) {
+  const out = [];
+  for (const shot of shots) {
+    const frames = shot.clipFrames ?? [];
+    if (frames.length === 0) { out.push({ ...shot, clipPaths: [] }); continue; }
+    const stamped = [];
+    let broken = false;
+    for (const frame of frames) {
+      const res = await fetchImpl(`${cfg.apiBase}/screenshot-upload`, {
+        method: "POST",
+        headers: { Authorization: `Bearer ${cfg.agentKey}`, "content-type": "application/json" },
+        body: JSON.stringify({ dataUrl: jpegDataUrl(frame.data) }),
+      }).catch(() => null);
+      const body = res ? await res.json().catch(() => ({})) : {};
+      if (!res || !res.ok || !body.path) { broken = true; break; }
+      // Время у кадра НАСТОЯЩЕЕ, снятое при записи: страница проигрывает клип
+      // по этим паузам, поэтому рваная съёмка не притворится равномерной.
+      stamped.push({ path: body.path, t: frame.t });
+    }
+    // У старых записей времени может не быть — тогда раскладываем по частоте.
+    const complete = stamped.every((f) => typeof f.t === "number");
+    out.push({ ...shot, clipPaths: broken ? [] : (complete ? stamped : timeline(stamped.map((f) => f.path))) });
+  }
+  return out;
+}
+
+export async function createDraft(payload, cfg, fetchImpl = fetch) {
+  const res = await fetchImpl(`${cfg.apiBase}/walkthrough-create`, {
+    method: "POST",
+    headers: { Authorization: `Bearer ${cfg.agentKey}`, "content-type": "application/json" },
+    body: JSON.stringify(payload),
+  });
+  const body = await res.json().catch(() => ({}));
+  if (!res.ok) throw new Error(`не удалось создать черновик: ${body.error ?? res.status}`);
+  return body;
+}
+
+// Отзыв ссылки: единственная кнопка «стоп» для прогона, который уже разослали.
+// Принимает слаг из адреса или id черновика — что оказалось под рукой.
+export async function revokeWalkthrough(target, cfg, fetchImpl = fetch) {
+  const body = /^wlk_/.test(target) ? { walkthroughId: target } : { slug: target };
+  const res = await fetchImpl(`${cfg.apiBase}/walkthrough-revoke`, {
+    method: "POST",
+    headers: { Authorization: `Bearer ${cfg.agentKey}`, "content-type": "application/json" },
+    body: JSON.stringify(body),
+  });
+  const data = await res.json().catch(() => ({}));
+  if (!res.ok) throw new Error(`не удалось отозвать: ${data.error ?? res.status}`);
+  return data;
+}

package/src/browser.js

@@ -0,0 +1,49 @@
+import { chromium } from "playwright-core";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { collectElements } from "./collect.js";
+
+// По умолчанию — ОТДЕЛЬНЫЙ постоянный профиль: агент не лезет в окно, где
+// человек работает, а сессии (логины на стенде) живут между запусками.
+// --attach подключается к уже запущенному браузеру с отладочным портом.
+export const PROFILE_DIR = join(homedir(), ".handoff", "browser");
+export const VIEWPORT = { width: 1280, height: 800 };
+
+export async function openBrowser({ attach = null, headless = false } = {}) {
+  if (attach) {
+    const browser = await chromium.connectOverCDP(attach);
+    const ctx = browser.contexts()[0] ?? (await browser.newContext({ viewport: VIEWPORT }));
+    const page = ctx.pages()[0] ?? (await ctx.newPage());
+    await page.setViewportSize(VIEWPORT);
+    return { page, close: () => browser.close() };
+  }
+  const ctx = await chromium.launchPersistentContext(PROFILE_DIR, {
+    channel: "chrome",             // playwright-core не тащит браузер — берём системный Chrome
+    headless,
+    viewport: VIEWPORT,
+    deviceScaleFactor: 1,          // rect и пиксели кадра должны совпадать один в один
+  });
+  const page = ctx.pages()[0] ?? (await ctx.newPage());
+  return { page, close: () => ctx.close() };
+}
+
+// Снимок шага: чистый кадр + карта геометрии + прямоугольник действия.
+// Метки НЕ впекаются в картинку — их рисует страница поверх по этим координатам.
+export async function captureStep(page, { actionSelector = null } = {}) {
+  const png = await page.screenshot();
+  // collectElements самодостаточна, поэтому уезжает в браузер как есть.
+  const elementMap = await page.evaluate(collectElements);
+  let actionRect = null;
+  if (actionSelector) {
+    const box = await page.locator(actionSelector).first().boundingBox().catch(() => null);
+    if (box) actionRect = { x: Math.round(box.x), y: Math.round(box.y), w: Math.round(box.width), h: Math.round(box.height) };
+  }
+  return {
+    png,
+    elementMap,
+    actionRect,
+    url: page.url(),
+    viewport: `${VIEWPORT.width}x${VIEWPORT.height}`,
+    devicePixelRatio: 1,
+  };
+}

package/src/clip.js

@@ -0,0 +1,71 @@
+// Клип вокруг действия — без кодеков: CDP отдаёт поток JPEG-кадров, они лежат
+// в бакете рядом со стоп-кадрами, а страница проигрывает их флипбуком.
+//
+// Числа сознательно ВЧЕТВЕРО легче спековских (3 с / 12 fps / 40 кадров):
+// движение «доехал и нажал» читается и за полторы секунды, а 40 кадров на шаг
+// превращаются в десятки мегабайт на канале коллеги. Поднять обратно —
+// поменять эти четыре цифры.
+export const CLIP = {
+  FPS: 8,
+  MAX_FRAMES: 12,
+  MAX_MS: 1600,
+  QUALITY: 55,
+};
+
+// Потолок на всякий случай: основное прореживание делает выборка по времени,
+// но если браузер прислал шквал кадров с одинаковым временем, лимит спасает.
+export function capFrames(frames, max = CLIP.MAX_FRAMES) {
+  return frames.length <= max ? frames : frames.slice(0, max);
+}
+
+// Решение «брать ли этот кадр»: между соседними кадрами должно пройти не меньше
+// 1/FPS секунды, а весь клип не длиннее MAX_MS.
+//
+// 🔴 ОПЛАЧЕННЫЙ УРОК: сначала кадры ограничивались ТОЛЬКО их числом. Экран
+// отдаёт до 60 кадров в секунду, поэтому лимит в 12 штук кончался за 0.2 с —
+// клип обрывался, не доехав до цели, и нажатия в нём не было вовсе. Считать
+// надо время, а не порядок прихода.
+export function shouldKeep(elapsedMs, lastKeptMs, { fps = CLIP.FPS, maxMs = CLIP.MAX_MS } = {}) {
+  if (elapsedMs > maxMs) return false;
+  if (lastKeptMs === null) return true;
+  return elapsedMs - lastKeptMs >= 1000 / fps - 1;
+}
+
+export function timeline(paths, fps = CLIP.FPS) {
+  return paths.map((path, i) => ({ path, t: Math.round((i / fps) * 1000) / 1000 }));
+}
+
+// cdp — сессия Playwright (page.context().newCDPSession(page)) или её двойник.
+// Возвращает кадры как `{ data, t }`: `data` — base64 JPEG, `t` — секунды от
+// начала записи. Время настоящее, а не «индекс делить на fps», поэтому рваная
+// съёмка на странице проиграется такой же рваной, а не соврёт равномерностью.
+export async function startClip(cdp, { viewport = { width: 1280, height: 800 }, now = () => Date.now() } = {}) {
+  const frames = [];
+  let started = null, lastKept = null;
+  cdp.on("Page.screencastFrame", (ev) => {
+    const at = now();
+    if (started === null) started = at;
+    const elapsed = at - started;
+    if (frames.length < CLIP.MAX_FRAMES && shouldKeep(elapsed, lastKept)) {
+      lastKept = elapsed;
+      frames.push({ data: ev.data, t: Math.round(elapsed) / 1000 });
+    }
+    // Подтверждение обязательно: без него браузер замолкает после первого кадра.
+    // Страница могла уже уйти на другой URL — сессия CDP отваливается, но это
+    // не должно ронять прогон, поэтому ошибку молча глотаем.
+    cdp.send("Page.screencastFrameAck", { sessionId: ev.sessionId }).catch(() => {});
+  });
+  await cdp.send("Page.startScreencast", {
+    format: "jpeg",
+    quality: CLIP.QUALITY,
+    maxWidth: viewport.width,
+    maxHeight: viewport.height,
+    everyNthFrame: 1,
+  });
+  return {
+    async stop() {
+      await cdp.send("Page.stopScreencast").catch(() => {});
+      return capFrames(frames);
+    },
+  };
+}

package/src/collect.js

@@ -0,0 +1,57 @@
+// Карта геометрии кадра: из неё клик коллеги по картинке превращается в
+// настоящий CSS-селектор.
+//
+// ВАЖНО: функция обязана быть САМОДОСТАТОЧНОЙ — Playwright сериализует её
+// исходник и выполняет в браузере, где нет ни импортов, ни констант модуля,
+// ни соседних функций. Поэтому хелперы и пороги живут внутри, а document и
+// window берутся глобальные (в jsdom-тестах они тоже глобальные).
+
+export function collectElements() {
+  // Коллега тычет не только в кнопки: в значок, в бейдж, в кусок текста.
+  // Каждый непокрытый тег — это «элемент не распознан» вместо селектора,
+  // поэтому берём и визуальные атомы (span/svg/code), и всё, что размечено
+  // ролью или подписью. Обёртки (div/section) намеренно НЕ берём: правило
+  // «самый мелкий элемент под точкой» и так вернёт то, что внутри.
+  const INTERESTING = "a, button, input, select, textarea, h1, h2, h3, h4, p, img, li, label," +
+    " span, svg, code, [role], [aria-label]";
+  const MIN_SIDE = 8;      // полоски тоньше этого кликать невозможно
+  const TEXT_MAX = 60;
+
+  // 🔴 ОПЛАЧЕННЫЙ УРОК: классы Tailwind сплошь содержат символы, которые в
+  // селекторе значат другое — `group/menu-item`, `hover:bg-x`, `w-1/2`. Без
+  // экранирования querySelectorAll БРОСАЕТ, карта кадра не собирается вообще,
+  // и шаг помечается провалом. Один такой класс убивал всю съёмку.
+  const esc = (s) => (typeof CSS !== "undefined" && CSS.escape
+    ? CSS.escape(s)
+    : String(s).replace(/[^\w-]/g, (c) => "\\" + c));
+
+  const cssPath = (el) => {
+    const tag = el.tagName.toLowerCase();
+    if (el.id) return `#${esc(el.id)}`;
+    const cls = (el.getAttribute("class") || "")
+      .trim().split(/\s+/).filter(Boolean).slice(0, 2).map(esc);
+    const base = tag + (cls.length ? "." + cls.join(".") : "");
+    try {
+      const same = [...document.querySelectorAll(base)];
+      return same.length > 1 ? `${base}:nth-of-type(${same.indexOf(el) + 1})` : base;
+    } catch {
+      // Экранирование не спасло (бывает у совсем экзотической разметки) —
+      // отдаём хотя бы тег: неточный селектор лучше пустого кадра.
+      return tag;
+    }
+  };
+
+  const out = [];
+  for (const el of document.querySelectorAll(INTERESTING)) {
+    const r = el.getBoundingClientRect();
+    if (r.width < MIN_SIDE || r.height < MIN_SIDE) continue;
+    if (r.bottom < 0 || r.top > window.innerHeight) continue;     // вне кадра
+    out.push({
+      selector: cssPath(el),
+      rect: { x: Math.round(r.x), y: Math.round(r.y), w: Math.round(r.width), h: Math.round(r.height) },
+      tag: el.tagName.toLowerCase(),
+      text: (el.textContent || "").trim().slice(0, TEXT_MAX),
+    });
+  }
+  return out;
+}

package/src/cursor.js

@@ -0,0 +1,74 @@
+// Курсор-призрак: его видно в клипе, потому что он живёт на самой снимаемой
+// странице, а не рисуется поверх картинки потом.
+//
+// ВАЖНО: каждая функция обязана быть САМОДОСТАТОЧНОЙ — Playwright сериализует
+// её исходник и выполняет в браузере, где нет ни импортов, ни констант модуля.
+// Поэтому идентификатор хоста продублирован строкой внутри каждой функции, а
+// общее состояние хранится в самом DOM.
+//
+// Правила работы поверх чужой страницы (память overlay-on-hostile-page-rules):
+// свой shadow root, pointer-events:none, анимация только transform/opacity.
+export const GHOST_HOST_ID = "__ft_ghost_cursor__";
+
+export function installGhost() {
+  const ID = "__ft_ghost_cursor__";
+  if (document.getElementById(ID)) return;
+  const host = document.createElement("div");
+  host.id = ID;
+  host.style.cssText = "position:fixed;left:0;top:0;width:0;height:0;z-index:2147483647;pointer-events:none";
+  const root = host.attachShadow({ mode: "open" });
+  root.innerHTML = `
+    <style>
+      .dot{position:fixed;left:0;top:0;width:22px;height:22px;margin:-11px 0 0 -11px;
+        border-radius:50%;background:rgba(15,27,51,.92);border:2px solid #fff;
+        box-shadow:0 2px 8px rgba(15,27,51,.4);opacity:0;
+        transition:transform 400ms cubic-bezier(.22,.61,.36,1), opacity 160ms linear}
+      .ring{position:fixed;left:0;top:0;width:22px;height:22px;margin:-11px 0 0 -11px;
+        border-radius:50%;border:2px solid #F5A524;opacity:0;
+        transition:transform 420ms ease-out, opacity 420ms ease-out}
+    </style>
+    <div class="ring"></div><div class="dot"></div>`;
+  document.documentElement.appendChild(host);
+}
+
+// Аргументы приезжают ОДНИМ массивом: page.evaluate передаёт в браузер ровно
+// один аргумент, и разворачивать его надо здесь, а не на вызывающей стороне.
+export function moveGhost([x, y, ms]) {
+  const host = document.getElementById("__ft_ghost_cursor__");
+  if (!host) return;
+  for (const el of host.shadowRoot.querySelectorAll(".dot,.ring")) {
+    // Задаём переход целиком, а не только длительность: одна `transitionDuration`
+    // растянула бы на ту же длину и появление, и курсор половину клипа был бы
+    // полупрозрачным пятном. Появление быстрое, поездка — длинная.
+    el.style.transition = `transform ${ms}ms cubic-bezier(.22,.61,.36,1), opacity 120ms linear`;
+    el.style.transform = `translate3d(${x}px, ${y}px, 0)`;
+  }
+  host.shadowRoot.querySelector(".dot").style.opacity = "1";
+}
+
+export function pulseGhost() {
+  const host = document.getElementById("__ft_ghost_cursor__");
+  if (!host) return;
+  const dot = host.shadowRoot.querySelector(".dot");
+  const ring = host.shadowRoot.querySelector(".ring");
+  // Кольцо расходится из той же точки, где стоит курсор: берём его же
+  // трансформ и добавляем масштаб.
+  const at = dot.style.transform;
+  ring.style.transitionDuration = "0ms";
+  ring.style.transform = at;
+  ring.style.opacity = "1";
+  // jsdom (тестовое окружение) не всегда даёт requestAnimationFrame —
+  // фолбэк на таймаут не меняет смысл: важно, что переход к следующему
+  // кадру случится ПОСЛЕ применения стартового состояния кольца.
+  const raf = typeof requestAnimationFrame === "function" ? requestAnimationFrame : (fn) => setTimeout(fn, 0);
+  raf(() => {
+    ring.style.transitionDuration = "420ms";
+    ring.style.transform = `${at} scale(2.6)`;
+    ring.style.opacity = "0";
+  });
+}
+
+export function removeGhost() {
+  const host = document.getElementById("__ft_ghost_cursor__");
+  if (host) host.remove();
+}

package/src/git.js

@@ -0,0 +1,57 @@
+import { execFileSync } from "node:child_process";
+
+// Шапка прогона говорит, на чём он снят. Чистая часть отделена от вызовов git,
+// чтобы её можно было проверить без репозитория.
+
+// Откуда считать «сколько файлов изменено». Первая ветка, которая существует,
+// и становится точкой отсчёта.
+export const BASE_CANDIDATES = ["origin/HEAD", "origin/master", "origin/main", "master", "main"];
+
+// 🔴 ОПЛАЧЕННЫЙ УРОК: считали только НЕЗАКОММИЧЕННЫЕ правки (`diff HEAD`), и у
+// человека, чья работа уже в коммитах, в шапке всегда стоял честный ноль —
+// «0 файлов» читается как «ничего не менялось». Считать надо всю ветку от базы
+// плюс то, что ещё не закоммичено.
+export function countChangedFiles(...lists) {
+  const all = new Set();
+  for (const list of lists) {
+    for (const line of String(list ?? "").split("\n")) {
+      const f = line.trim();
+      if (f) all.add(f);
+    }
+  }
+  return all.size;
+}
+
+export function parseGitContext({ branch, sha, baseSha, files, uncommitted }) {
+  return {
+    branch: String(branch).trim() || null,
+    headSha: String(sha).trim().slice(0, 7) || null,
+    baseSha: String(baseSha ?? "").trim().slice(0, 7) || null,
+    filesChanged: countChangedFiles(files, uncommitted),
+  };
+}
+
+export function readGitContext(cwd = process.cwd()) {
+  const run = (args) => {
+    try { return execFileSync("git", args, { cwd, encoding: "utf8" }); }
+    catch { return ""; }
+  };
+
+  // База ветки: с какого коммита началась эта работа.
+  let baseSha = "";
+  for (const ref of BASE_CANDIDATES) {
+    const resolved = run(["rev-parse", "--abbrev-ref", ref]).trim() || ref;
+    const merged = run(["merge-base", "HEAD", resolved]).trim();
+    if (merged) { baseSha = merged; break; }
+  }
+
+  return parseGitContext({
+    branch: run(["rev-parse", "--abbrev-ref", "HEAD"]),
+    sha: run(["rev-parse", "HEAD"]),
+    baseSha,
+    // Что сделано в ветке…
+    files: baseSha ? run(["diff", "--name-only", `${baseSha}..HEAD`]) : "",
+    // …и что ещё не закоммичено.
+    uncommitted: run(["diff", "--name-only", "HEAD"]),
+  });
+}

package/src/payload.js

@@ -0,0 +1,39 @@
+// Тело запроса к walkthrough-create. CLI отвечает за механику, поэтому summary
+// остаётся ПУСТЫМ: его пишет агент, глядя на свой диff и на снятые кадры —
+// и только он может выполнить правило «пункт обязан ссылаться на шаг».
+
+export const ACTION_MAP = { open: "navigate", click: "click", type: "type", check: "assert", scroll: "scroll" };
+
+export function buildPayload(plan, shots, git = {}) {
+  return {
+    origin: plan.origin,
+    title: plan.title,
+    // Личность прогона: имя файла плана. Заголовок можно переписывать сколько
+    // угодно — вытеснение предыдущей версии держится на этом.
+    planKey: plan.planKey ?? null,
+    branch: git.branch ?? null,
+    baseSha: git.baseSha ?? null,
+    headSha: git.headSha ?? null,
+    filesChanged: git.filesChanged ?? null,
+    summary: [],
+    steps: shots.map((s) => ({
+      url: s.url,
+      title: s.title,
+      note: s.note ?? null,
+      screenshotPath: s.screenshotPath ?? null,
+      action: {
+        type: ACTION_MAP[s.action] ?? "assert",
+        // У перехода цель — путь страницы, а не элемент: селектора у него нет.
+        selector: s.action === "open" ? undefined : (s.target ?? undefined),
+        label: s.label ?? undefined,
+        rect: s.actionRect ?? null,
+      },
+      elementMap: s.elementMap ?? [],
+      clipFrames: s.clipPaths ?? [],
+      viewport: s.viewport ?? null,
+      devicePixelRatio: s.devicePixelRatio ?? null,
+      status: s.status ?? "ok",
+      failure: s.failure ?? null,
+    })),
+  };
+}

package/src/plan.js

@@ -0,0 +1,83 @@
+// План прогона — markdown, который агент правит ТЕКСТОМ до дорогой съёмки.
+// Формат намеренно скучный: фронтматтер + нумерованные шаги.
+//
+//   ---
+//   title: Новый чекаут
+//   origin: http://localhost:3000
+//   ---
+//   1. open /cart — Корзина
+//   2. click button.promo-apply — Применить промокод
+//   3. type input.promo "SALE20" — Ввести код
+//   4. check .cart-total — Сумма пересчиталась
+//   5. scroll .terms — Условия ниже сгиба
+
+export const ACTIONS = ["open", "click", "type", "check", "scroll"];
+
+// Действия, которым без цели делать нечего.
+const NEEDS_TARGET = ["open", "click", "type", "check", "scroll"];
+
+export function parsePlan(source) {
+  const lines = String(source).split(/\r?\n/);
+  const meta = {};
+  let i = 0;
+
+  if (lines[0]?.trim() === "---") {
+    i = 1;
+    for (; i < lines.length && lines[i].trim() !== "---"; i++) {
+      const m = lines[i].match(/^\s*([a-zA-Z_]+)\s*:\s*(.+?)\s*$/);
+      if (m) meta[m[1]] = m[2];
+    }
+    i++; // закрывающий ---
+  }
+  if (!meta.origin) throw new Error("В плане не указан origin (фронтматтер `origin:`)");
+
+  const steps = [];
+  for (; i < lines.length; i++) {
+    const raw = lines[i];
+    if (!raw.trim()) continue;
+    const m = raw.match(/^\s*\d+\.\s*(.+)$/);
+    if (!m) continue;                                   // прозаические строки между шагами игнорируем
+
+    // тело шага: <действие> [цель] ["текст"] <тире> <подпись>
+    //
+    // Цель можно взять в ОДИНАРНЫЕ кавычки — тогда в ней разрешены пробелы.
+    // Без этого на живом приложении не за что зацепиться: у кнопок в Tailwind
+    // классы вида `button.flex.items-center:nth-of-type(7)`, они едут от любой
+    // правки вёрстки, а устойчивый селектор — текстовый:
+    //   click 'button:has-text("Продвинуть сделку по этапам")' — Выбрал тур
+    // Двойные кавычки остаются за текстом для `type`, поэтому путаницы нет.
+    const [body, caption] = splitCaption(m[1], i + 1);
+    const parts = body.trim().match(/^(\S+)(?:\s+(?:'([^']*)'|(\S+)))?(?:\s+"([^"]*)")?\s*$/);
+    if (!parts) throw new Error(`строка ${i + 1}: не разобрать шаг «${raw.trim()}»`);
+
+    const action = parts[1];
+    if (!ACTIONS.includes(action)) {
+      throw new Error(`строка ${i + 1}: неизвестное действие «${action}» (можно: ${ACTIONS.join(", ")})`);
+    }
+    const target = parts[2] ?? parts[3] ?? null;
+    if (NEEDS_TARGET.includes(action) && !target) {
+      throw new Error(`строка ${i + 1}: действию «${action}» нужна цель (путь или селектор)`);
+    }
+    if (action === "type" && !parts[4]) {
+      throw new Error(`строка ${i + 1}: действию «type» нужен текст в кавычках`);
+    }
+    steps.push({ action, target, text: parts[4] ?? null, title: caption });
+  }
+
+  if (steps.length === 0) throw new Error("В плане нет ни одного шага");
+  return { title: meta.title ?? "Прогон", origin: meta.origin, steps };
+}
+
+// Подпись отделяется тире — длинным или обычным, как удобно писавшему.
+function splitCaption(line, lineNo) {
+  const idx = findSeparator(line);
+  if (idx < 0) throw new Error(`строка ${lineNo}: нет подписи (ожидается «… — подпись»)`);
+  return [line.slice(0, idx), line.slice(idx + 1).trim()];
+}
+
+function findSeparator(line) {
+  const em = line.indexOf("—");
+  if (em >= 0) return em;
+  const hyphen = line.search(/\s-\s/);
+  return hyphen >= 0 ? hyphen + 1 : -1;
+}

package/src/version.js

@@ -0,0 +1 @@
+export const CLI_NAME = "handoff";

package/src/walk.js

@@ -0,0 +1,108 @@
+import { captureStep } from "./browser.js";
+import { installGhost, moveGhost, pulseGhost, removeGhost } from "./cursor.js";
+import { startClip } from "./clip.js";
+
+// Пауза после действия: даём странице доехать до нового состояния, иначе
+// снимем кадр «между» — с полупримененной анимацией.
+const SETTLE_MS = 400;
+// Сколько курсор едет к цели. Меньше — движение не читается, больше — клип
+// уходит в лимит кадров, ничего не показав.
+const TRAVEL_MS = 400;
+
+export async function walkPlan(page, plan, { capture = captureStep, settle = SETTLE_MS } = {}) {
+  const shots = [];
+  for (const step of plan.steps) {
+    let status = "ok", failure = null, clipFrames = [];
+    // Курсор едет только туда, куда человек и правда наводит. У перехода
+    // (`open`) цели на экране нет, а у прокрутки цель ещё ЗА экраном — курсор
+    // улетел бы в пустоту; движение там показывает сама поехавшая страница.
+    const withCursor = ["click", "type", "check"].includes(step.action) && Boolean(step.target);
+    // Пульс — это язык нажатия. На проверке (`check`) никто ничего не нажимает,
+    // и кольцо там соврало бы: курсор доезжает показать, куда смотреть, и всё.
+    const withPress = withCursor && step.action !== "check";
+    let clip = null;
+
+    // Клип и курсор — УКРАШЕНИЕ, и своим падением они не имеют права портить
+    // шаг: не завелась запись — шаг всё равно снимется стоп-кадром.
+    try {
+      if (withCursor) await page.evaluate(installGhost);
+      clip = await startClip(await page.context().newCDPSession(page));
+      if (withCursor) {
+        const box = await page.locator(step.target).first().boundingBox().catch(() => null);
+        if (box) {
+          await page.evaluate(moveGhost, [Math.round(box.x + box.width / 2), Math.round(box.y + box.height / 2), TRAVEL_MS]);
+          await page.waitForTimeout(TRAVEL_MS);
+          if (withPress) await page.evaluate(pulseGhost);
+        }
+      }
+    } catch {
+      clip = null;
+    }
+
+    try {
+      await perform(page, plan, step);
+      await page.waitForTimeout(settle);
+    } catch (e) {
+      // Провал шага не роняет прогон: остальные снимутся, а автор увидит
+      // причину в черновике и решит сам.
+      status = "failed";
+      failure = e instanceof Error ? e.message : String(e);
+    }
+
+    // Запись и курсор снимаются ВСЕГДА, даже если шаг провалился: иначе призрак
+    // останется в кадре следующего шага, а screencast продолжит жечь CPU.
+    // Уборка обёрнута целиком: на закрытой странице вызов может бросить сразу,
+    // до возврата промиса, и тогда .catch() бесполезен, а прогон падает из-за
+    // украшения — ровно того, что не имеет права ничего ронять.
+    try {
+      if (clip) clipFrames = await clip.stop();
+      await page.evaluate(removeGhost);
+    } catch {
+      // Уже снятые кадры оставляем: если упало на снятии курсора, клип цел.
+    }
+
+    const shot = status === "ok"
+      ? await capture(page, { actionSelector: step.action === "open" ? null : step.target })
+      : { png: null, elementMap: [], actionRect: null, url: page.url(), viewport: null, devicePixelRatio: null };
+
+    shots.push({
+      ...shot,
+      clipFrames,
+      title: step.title,
+      action: step.action,
+      target: step.target,
+      label: step.text ?? step.title,
+      status,
+      failure,
+    });
+  }
+  return shots;
+}
+
+// Всегда ПЕРВОЕ совпадение. Playwright в строгом режиме падает, если селектор
+// нашёл больше одного элемента, а на живой странице так и бывает: кнопка
+// «Далее» есть и в туре, и в скрытом диалоге рядом. Съёмка рамки уже берёт
+// first() — здесь то же самое, иначе шаг падал бы на многозначности.
+async function perform(page, plan, step) {
+  switch (step.action) {
+    case "open":
+      return page.goto(absolute(plan.origin, step.target), { waitUntil: "networkidle" });
+    case "click":
+      return page.locator(step.target).first().click();
+    case "type":
+      return page.locator(step.target).first().fill(step.text ?? "");
+    case "check":
+      return page.locator(step.target).first().waitFor({ state: "visible" });
+    // Кадр — это вьюпорт, а не вся страница: содержимое ниже сгиба в него не
+    // попадает. Прокрутка к элементу — единственный способ показать длинный
+    // справочник или форму целиком, не разрезая их на куски.
+    case "scroll":
+      return page.locator(step.target).first().scrollIntoViewIfNeeded();
+    default:
+      throw new Error(`неизвестное действие «${step.action}»`);
+  }
+}
+
+function absolute(origin, target) {
+  return /^https?:\/\//.test(target) ? target : origin.replace(/\/$/, "") + target;
+}