get-handoff 1.0.0 → 1.2.0

package/bin/handoff.mjs

@@ -5,24 +5,45 @@ 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 { uploadFrames, uploadClips, createDraft, revokeWalkthrough, publishWalkthrough, listWalkthroughs, pruneWalkthroughs } 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> [опции]
+const USAGE = `handoff walk <план.md> [опции]
+handoff publish <wlk_id> [--summary <файл.json>]  — опубликовать черновик (и прикрепить сводку)
+handoff list              — показать свои прогоны (снятые и черновики)
+handoff prune             — удалить свои ЧЕРНОВИКИ (опубликованное не трогается)
 handoff revoke <слаг|id>  — закрыть доступ к уже разосланной ссылке
 
   --attach <url>     подключиться к запущенному браузеру (по умолчанию — свой профиль)
   --headless         не показывать окно
+  --settle <мс>      пауза после каждого шага (или HANDOFF_SETTLE; медленным SPA — больше)
+  --no-clip          не писать клип-запись (страница её не читает — быстрее и легче)
+  --fail-fast        не создавать черновик, если хоть один шаг провалился
   --out <файл>       записать тело запроса в файл вместо создания черновика
+  --summary <файл>   (для publish) JSON-массив [{stepIdx, text}, …] — по пункту на шаг
   --api <url>        база edge-функций (или HANDOFF_API)
   --key <ключ>       agent key (или HANDOFF_KEY)
+  -h, --help         показать эту справку
+
+Действия плана: open <путь> · click <селектор> · type <селектор> "текст" · check <селектор> ·
+scroll <селектор> · wait <селектор|мс> (только ждать, кадр НЕ снимать). Цель может содержать
+пробелы без кавычек — подпись отделяется тире: click button:has-text("Оформить") — Оформление.
+
+Сводку «что изменилось» CLI не пишет: её дописывает агент, посмотрев снятые кадры, и прикрепляет
+при публикации — MCP-тул publish_walkthrough(walkthroughId, summary).`;
+
+const args = process.argv.slice(2);
+const cmd = args[0];
 
-Сводку «что изменилось» CLI не пишет: её дописывает агент, глядя на свой диff
-и на снятые кадры, — и только он может выполнить правило «пункт ссылается на шаг».`);
+// --help/-h (и пустой вызов) — справка в stdout, код 0. Раньше `walk --help`
+// трактовал --help как путь к файлу плана и падал ENOENT со стектрейсом.
+if (!cmd || cmd === "--help" || cmd === "-h" || args.includes("--help") || args.includes("-h")) {
+  console.log(USAGE);
+  process.exit(0);
+}
+const NEEDS_ARG = ["walk", "publish", "revoke"]; // list/prune аргумента не требуют
+if (!["walk", "publish", "revoke", "list", "prune"].includes(cmd) || (NEEDS_ARG.includes(cmd) && !args[1])) {
+  console.error(USAGE);
   process.exit(1);
 }
 
@@ -50,6 +71,45 @@ if (cmd === "revoke") {
   process.exit(0);
 }
 
+// Публикация из CLI — гомогенно с revoke (браузер не нужен). Сводку читаем из
+// JSON-файла: [{stepIdx, text}, …], по пункту на шаг. Без --summary просто
+// публикуем; повторный вызов со свежей сводкой обновляет её на месте.
+if (cmd === "publish") {
+  if (!cfgEarly.agentKey) {
+    console.error("Нужен agent key: --key или HANDOFF_KEY.");
+    process.exit(2);
+  }
+  const summaryFile = opt("summary");
+  let summary;
+  if (summaryFile) {
+    try { summary = JSON.parse(readFileSync(summaryFile, "utf8")); }
+    catch (e) { console.error(`не прочитать summary ${summaryFile}: ${e.message}`); process.exit(2); }
+  }
+  const res = await publishWalkthrough(args[1], summary, cfgEarly);
+  console.log(res.alreadyPublished
+    ? `Обновлено: ${res.url}${summary ? " (сводка обновлена)" : ""}`
+    : `Опубликовано: ${res.url}`);
+  process.exit(0);
+}
+
+if (cmd === "list") {
+  if (!cfgEarly.agentKey) { console.error("Нужен agent key: --key или HANDOFF_KEY."); process.exit(2); }
+  const items = await listWalkthroughs(cfgEarly);
+  if (items.length === 0) { console.log("Прогонов пока нет."); process.exit(0); }
+  for (const w of items) {
+    const tail = w.url ? `  ${w.url}` : "";
+    console.log(`  ${w.status.padEnd(10)} ${w.walkthroughId}  ${w.planKey ?? "—"}  «${w.title}»${tail}`);
+  }
+  process.exit(0);
+}
+
+if (cmd === "prune") {
+  if (!cfgEarly.agentKey) { console.error("Нужен agent key: --key или HANDOFF_KEY."); process.exit(2); }
+  const n = await pruneWalkthroughs(cfgEarly);
+  console.log(n === 0 ? "Черновиков на удаление нет." : `Удалено черновиков: ${n} (опубликованное не тронуто).`);
+  process.exit(0);
+}
+
 const plan = parsePlan(readFileSync(args[1], "utf8"));
 // Файл плана — это и есть личность прогона: `help.md` остаётся `help.md`,
 // как бы ни звучал заголовок внутри.
@@ -59,11 +119,18 @@ const cfg = {
   agentKey: opt("key", process.env.HANDOFF_KEY ?? ""),
 };
 
+// Пауза после каждого шага. Медленным SPA (данные тянутся XHR-ом, кнопки
+// рендерятся секунды) можно дать больше; невалидное значение → дефолт walkPlan.
+const settleRaw = opt("settle", process.env.HANDOFF_SETTLE);
+const settle = settleRaw != null && settleRaw !== "" && Number.isFinite(Number(settleRaw))
+  ? Number(settleRaw) : undefined;
+
+const recordClip = !has("no-clip");
 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);
+  shots = await walkPlan(page, plan, { settle, recordClip });
 } finally {
   await close();
 }
@@ -71,6 +138,17 @@ try {
 const failed = shots.filter((s) => s.status === "failed");
 for (const s of shots) console.log(`  ${s.status === "ok" ? "снят" : "ПРОВАЛ"}  ${s.title}${s.failure ? " — " + s.failure : ""}`);
 
+// Провалы видно ЗАМЕТНО и ДО создания черновика: раньше «снят/ПРОВАЛ» тонули в
+// логе, и брак уезжал в публикацию. --fail-fast вообще не создаёт черновик.
+if (failed.length) {
+  console.log(`\n⚠️  ${failed.length} шаг(ов) провалились — проверь перед публикацией:`);
+  for (const s of failed) console.log(`     ✗ ${s.title}${s.failure ? " — " + s.failure : ""}`);
+  if (has("fail-fast")) {
+    console.error("\n--fail-fast: черновик не создаю. Почини план и переснимай.");
+    process.exit(1);
+  }
+}
+
 const outFile = opt("out");
 
 // С ключом кадры заливаются всегда — даже когда результат уходит в файл.
@@ -99,6 +177,5 @@ if (!cfg.agentKey) {
 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} шаг(ов) провалились — посмотри перед публикацией.`);
+console.log(`Посмотри кадры, затем опубликуй со сводкой: publish_walkthrough(walkthroughId="${draft.walkthroughId}", summary=[…]) (MCP).`);
 process.exit(failed.length ? 1 : 0);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "get-handoff",
-  "version": "1.0.0",
+  "version": "1.2.0",
   "type": "module",
   "bin": { "handoff": "./bin/handoff.mjs", "get-handoff": "./bin/handoff.mjs" },
   "files": ["bin/", "src/", "!src/**/*.test.js"],

package/src/api.js

@@ -67,6 +67,44 @@ export async function createDraft(payload, cfg, fetchImpl = fetch) {
   return body;
 }
 
+// Публикация черновика со сводкой — тот же контракт, что MCP publish_walkthrough
+// (сводку валидирует сервер: по пункту на шаг, покрыты все). summary можно не
+// передавать — тогда просто публикуем; повторный вызов обновляет сводку на месте.
+export async function publishWalkthrough(walkthroughId, summary, cfg, fetchImpl = fetch) {
+  const res = await fetchImpl(`${cfg.apiBase}/walkthrough-publish`, {
+    method: "POST",
+    headers: { Authorization: `Bearer ${cfg.agentKey}`, "content-type": "application/json" },
+    body: JSON.stringify(summary === undefined ? { walkthroughId } : { walkthroughId, summary }),
+  });
+  const data = await res.json().catch(() => ({}));
+  if (!res.ok) throw new Error(`не удалось опубликовать: ${data.error ?? res.status}`);
+  return data;
+}
+
+// Список прогонов этого ключа (что снято, что осталось черновиком).
+export async function listWalkthroughs(cfg, fetchImpl = fetch) {
+  const res = await fetchImpl(`${cfg.apiBase}/walkthrough-list`, {
+    method: "POST",
+    headers: { Authorization: `Bearer ${cfg.agentKey}`, "content-type": "application/json" },
+    body: "{}",
+  });
+  const data = await res.json().catch(() => ({}));
+  if (!res.ok) throw new Error(`не удалось получить список: ${data.error ?? res.status}`);
+  return data.walkthroughs ?? [];
+}
+
+// Подчистить черновики этого ключа (опубликованное не трогается).
+export async function pruneWalkthroughs(cfg, fetchImpl = fetch) {
+  const res = await fetchImpl(`${cfg.apiBase}/walkthrough-prune`, {
+    method: "POST",
+    headers: { Authorization: `Bearer ${cfg.agentKey}`, "content-type": "application/json" },
+    body: "{}",
+  });
+  const data = await res.json().catch(() => ({}));
+  if (!res.ok) throw new Error(`не удалось подчистить: ${data.error ?? res.status}`);
+  return data.pruned ?? 0;
+}
+
 // Отзыв ссылки: единственная кнопка «стоп» для прогона, который уже разослали.
 // Принимает слаг из адреса или id черновика — что оказалось под рукой.
 export async function revokeWalkthrough(target, cfg, fetchImpl = fetch) {

package/src/git.js

@@ -32,11 +32,19 @@ export function parseGitContext({ branch, sha, baseSha, files, uncommitted }) {
 }
 
 export function readGitContext(cwd = process.cwd()) {
+  // stderr в /dev/null: без него git-usage (десятки строк про --histogram и т.п.)
+  // сыпался в вывод прогона и топил полезные строки «ПРОВАЛ …» / «Черновик готов».
   const run = (args) => {
-    try { return execFileSync("git", args, { cwd, encoding: "utf8" }); }
+    try { return execFileSync("git", args, { cwd, encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] }); }
     catch { return ""; }
   };
 
+  // Не git-репозиторий — контекст не собираем и НИЧЕГО не печатаем. Прогон часто
+  // снимают вне репо (чужое приложение), и там git-команды только шумят.
+  if (run(["rev-parse", "--is-inside-work-tree"]).trim() !== "true") {
+    return parseGitContext({ branch: "", sha: "", baseSha: "", files: "", uncommitted: "" });
+  }
+
   // База ветки: с какого коммита началась эта работа.
   let baseSha = "";
   for (const ref of BASE_CANDIDATES) {

package/src/plan.js

@@ -10,11 +10,24 @@
 //   3. type input.promo "SALE20" — Ввести код
 //   4. check .cart-total — Сумма пересчиталась
 //   5. scroll .terms — Условия ниже сгиба
+//   6. wait .deal-card — ждём карточку (кадр НЕ снимается)
+//
+// Цель может содержать ПРОБЕЛЫ без кавычек: подпись отделяется тире, а всё между
+// действием и тире — это цель целиком. Раньше цель бралась одним whitespace-токеном,
+// и `check button:has-text("Создать сделку")` не разбирался — теперь разбирается.
+// Одинарные кавычки вокруг цели по-прежнему допускаются (обратная совместимость) и
+// снимаются при разборе.
 
-export const ACTIONS = ["open", "click", "type", "check", "scroll"];
+export const ACTIONS = ["open", "click", "type", "check", "scroll", "wait"];
 
 // Действия, которым без цели делать нечего.
-const NEEDS_TARGET = ["open", "click", "type", "check", "scroll"];
+const NEEDS_TARGET = ["open", "click", "type", "check", "scroll", "wait"];
+
+// `wait` только ждёт (кадр не снимается) — подпись ему не нужна.
+const NEEDS_CAPTION = ["open", "click", "type", "check", "scroll"];
+
+const SYNTAX_HINT =
+  'формат: <действие> <цель> — <подпись>. пример: click button:has-text("Оформить") — Оформление';
 
 export function parsePlan(source) {
   const lines = String(source).split(/\r?\n/);
@@ -36,45 +49,59 @@ export function parsePlan(source) {
     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 (!m) continue; // прозаические строки между шагами игнорируем
+    steps.push(parseStep(m[1], i + 1));
   }
 
   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()];
+// Тело шага: <действие> <цель...> ["текст"] — <подпись>.
+// Действие — первый токен; всё до разделителя-тире — цель (пробелы разрешены);
+// подпись — после тире. У `type` в хвосте цели стоит "текст" в двойных кавычках.
+function parseStep(body, lineNo) {
+  const head = body.match(/^(\S+)\s*([\s\S]*)$/);
+  const action = head[1];
+  if (!ACTIONS.includes(action)) {
+    throw new Error(`строка ${lineNo}: неизвестное действие «${action}» (можно: ${ACTIONS.join(", ")})`);
+  }
+
+  const sep = findSeparator(head[2]);
+  const targetPart = (sep >= 0 ? head[2].slice(0, sep) : head[2]).trim();
+  const caption = sep >= 0 ? head[2].slice(sep + 1).trim() : null;
+
+  if (caption === null && NEEDS_CAPTION.includes(action)) {
+    throw new Error(`строка ${lineNo}: нет подписи (${SYNTAX_HINT})`);
+  }
+
+  let target = null, text = null;
+  if (action === "type") {
+    const tm = targetPart.match(/^([\s\S]*?)\s+"([^"]*)"\s*$/);
+    if (!tm) {
+      throw new Error(`строка ${lineNo}: действию «type» нужен текст в двойных кавычках (${SYNTAX_HINT})`);
+    }
+    target = stripQuotes(tm[1]);
+    text = tm[2];
+  } else {
+    target = stripQuotes(targetPart) || null;
+  }
+
+  if (NEEDS_TARGET.includes(action) && !target) {
+    const kind = action === "wait" ? "селектор или число мс" : "путь или селектор";
+    throw new Error(`строка ${lineNo}: действию «${action}» нужна цель (${kind})`);
+  }
+
+  return { action, target, text, title: caption };
 }
 
+// Снять одинарные кавычки вокруг цели, если писавший их поставил (обратная совместимость).
+function stripQuotes(s) {
+  const t = String(s ?? "").trim();
+  return /^'.*'$/.test(t) ? t.slice(1, -1) : t;
+}
+
+// Подпись отделяется тире — длинным или обычным, как удобно писавшему.
 function findSeparator(line) {
   const em = line.indexOf("—");
   if (em >= 0) return em;

package/src/walk.js

@@ -8,10 +8,26 @@ const SETTLE_MS = 400;
 // Сколько курсор едет к цели. Меньше — движение не читается, больше — клип
 // уходит в лимит кадров, ничего не показав.
 const TRAVEL_MS = 400;
+// Верхняя граница ожидания сетевого простоя после шага. SPA тянет данные XHR-ом
+// ПОСЛЕ первичной загрузки, и `networkidle` в момент goto срабатывает в «окне
+// тишины» до старта отложенного запроса — поэтому ждём простой ещё раз, уже
+// после действия. Никогда не роняем прогон: истёк таймаут — просто идём дальше.
+const NETIDLE_MS = 8000;
+// Стабилизация DOM: XHR долетел, но React ещё перерисовывает. Ждём, пока размер
+// разметки не перестанет меняться два замера подряд, с общим потолком.
+const DOM_SAMPLES = 8;
+const DOM_GAP_MS = 150;
 
-export async function walkPlan(page, plan, { capture = captureStep, settle = SETTLE_MS } = {}) {
+export async function walkPlan(page, plan, { capture = captureStep, settle = SETTLE_MS, recordClip = true } = {}) {
   const shots = [];
   for (const step of plan.steps) {
+    // `wait` только ждёт — кадр НЕ снимается (медленным страницам нужно дать
+    // догрузиться без паразитного кадра со спиннером). В прогон не попадает.
+    if (step.action === "wait") {
+      await doWait(page, step);
+      continue;
+    }
+
     let status = "ok", failure = null, clipFrames = [];
     // Курсор едет только туда, куда человек и правда наводит. У перехода
     // (`open`) цели на экране нет, а у прокрутки цель ещё ЗА экраном — курсор
@@ -26,7 +42,9 @@ export async function walkPlan(page, plan, { capture = captureStep, settle = SET
     // шаг: не завелась запись — шаг всё равно снимется стоп-кадром.
     try {
       if (withCursor) await page.evaluate(installGhost);
-      clip = await startClip(await page.context().newCDPSession(page));
+      // Клип (screencast) — украшение, которое СТРАНИЦА ДАЖЕ НЕ ЧИТАЕТ (жест
+      // синтетический, по координатам). --no-clip его не пишет: быстрее и не жжёт CPU.
+      clip = recordClip ? await startClip(await page.context().newCDPSession(page)) : null;
       if (withCursor) {
         const box = await page.locator(step.target).first().boundingBox().catch(() => null);
         if (box) {
@@ -39,14 +57,23 @@ export async function walkPlan(page, plan, { capture = captureStep, settle = SET
       clip = null;
     }
 
+    let aborted = false;
     try {
       await perform(page, plan, step);
-      await page.waitForTimeout(settle);
+      await settleAfter(page, settle);
     } catch (e) {
       // Провал шага не роняет прогон: остальные снимутся, а автор увидит
-      // причину в черновике и решит сам.
+      // причину в черновике и решит сам. Исключение — когда исчезло само окно:
+      // остальные шаги всё равно упадут тем же, поэтому прекращаем и говорим
+      // человеку понятную причину вместо пяти одинаковых «page has been closed».
       status = "failed";
-      failure = e instanceof Error ? e.message : String(e);
+      const msg = e instanceof Error ? e.message : String(e);
+      if (/has been closed|target (page|closed)|browser has been closed/i.test(msg)) {
+        failure = `целевая вкладка/окно закрыто во время прогона — не закрывай окно, к которому подключён recorder (${msg})`;
+        aborted = true;
+      } else {
+        failure = msg;
+      }
     }
 
     // Запись и курсор снимаются ВСЕГДА, даже если шаг провалился: иначе призрак
@@ -75,10 +102,47 @@ export async function walkPlan(page, plan, { capture = captureStep, settle = SET
       status,
       failure,
     });
+
+    if (aborted) break; // окно исчезло — дальше снимать нечего
   }
   return shots;
 }
 
+// Дождаться, пока страница доедет до устойчивого состояния после действия:
+// сетевой простой (повторно — после отложенного XHR) + стабилизация DOM +
+// базовая пауза. Каждое ожидание best-effort: истекло — идём дальше.
+async function settleAfter(page, settle) {
+  if (page.waitForLoadState) {
+    await page.waitForLoadState("networkidle", { timeout: NETIDLE_MS }).catch(() => {});
+  }
+  await domStable(page).catch(() => {});
+  await page.waitForTimeout(settle);
+}
+
+// DOM «устоялся» = размер разметки не изменился два замера подряд. Дёшево и
+// достаточно: ловит XHR-рендер, который долетает уже после networkidle.
+async function domStable(page) {
+  let prev = null;
+  for (let i = 0; i < DOM_SAMPLES; i++) {
+    const sig = await page.evaluate(() => document.documentElement.outerHTML.length).catch(() => null);
+    if (typeof sig === "number" && sig === prev) return; // два одинаковых подряд — устоялся
+    prev = sig;
+    await page.waitForTimeout(DOM_GAP_MS);
+  }
+}
+
+// `wait <селектор>` — ждать появления элемента (кадр не снимаем). `wait <мс>` —
+// глухая пауза. Best-effort: не дождались — не роняем прогон, следующий шаг
+// снимется как есть, а автор увидит по кадру, что было рано.
+async function doWait(page, step) {
+  const t = String(step.target ?? "").trim();
+  if (/^\d+$/.test(t)) {
+    await page.waitForTimeout(Number(t));
+    return;
+  }
+  await page.locator(t).first().waitFor({ state: "visible", timeout: 30000 }).catch(() => {});
+}
+
 // Всегда ПЕРВОЕ совпадение. Playwright в строгом режиме падает, если селектор
 // нашёл больше одного элемента, а на живой странице так и бывает: кнопка
 // «Далее» есть и в туре, и в скрытом диалоге рядом. Съёмка рамки уже берёт