get-handoff 1.1.0 → 1.2.0

package/bin/handoff.mjs

@@ -5,17 +5,22 @@ 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 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         показать эту справку
@@ -36,7 +41,8 @@ if (!cmd || cmd === "--help" || cmd === "-h" || args.includes("--help") || args.
   console.log(USAGE);
   process.exit(0);
 }
-if (!["walk", "revoke"].includes(cmd) || !args[1]) {
+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);
 }
@@ -65,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`,
 // как бы ни звучал заголовок внутри.
@@ -80,11 +125,12 @@ 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, { settle });
+  shots = await walkPlan(page, plan, { settle, recordClip });
 } finally {
   await close();
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "get-handoff",
-  "version": "1.1.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/walk.js

@@ -18,7 +18,7 @@ const NETIDLE_MS = 8000;
 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` только ждёт — кадр НЕ снимается (медленным страницам нужно дать
@@ -42,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) {