@dadado/agent-kit-cli 5.15.1 → 5.17.0

package/dist/handoff-3UI6VKVG.js

@@ -0,0 +1,302 @@
+import {
+  pruneHandoffText
+} from "./chunk-IHROBTNM.js";
+import {
+  extractFieldBlock,
+  extractHandoffNamedPlans,
+  namedPlanCandidatePaths,
+  parsePlanFrontmatter
+} from "./chunk-KD2MYBB6.js";
+import {
+  PM_TOOL_LABELS
+} from "./chunk-F6C3GFKV.js";
+import {
+  logger
+} from "./chunk-ZB43YMHW.js";
+import {
+  HANDOFF_REL
+} from "./chunk-5VCOWTTP.js";
+import {
+  ensureDir,
+  fileExists,
+  readJson
+} from "./chunk-77V75A7O.js";
+
+// src/commands/handoff.ts
+import { spawn } from "child_process";
+import { appendFile, readFile, readdir, writeFile } from "fs/promises";
+import path from "path";
+import { defineCommand } from "citty";
+var HANDOFF_PRUNE_DEFAULT_KEEP = 5;
+function pruneArchiveTimestamp(now2 = /* @__PURE__ */ new Date()) {
+  const pad = (n) => String(n).padStart(2, "0");
+  return `${now2.getFullYear()}-${pad(now2.getMonth() + 1)}-${pad(now2.getDate())}-${pad(now2.getHours())}${pad(now2.getMinutes())}`;
+}
+async function runPrune(cwd, keep) {
+  const handoffPath = path.join(cwd, ".cursor", "HANDOFF.md");
+  if (!await fileExists(handoffPath)) {
+    logger.warn("No .cursor/HANDOFF.md to prune.");
+    return;
+  }
+  const original = await readFile(handoffPath, "utf8");
+  const result = pruneHandoffText(original, keep);
+  if (!result.ok) {
+    logger.warn(`Refusing to prune: ${result.reason}`);
+    process.exitCode = 1;
+    return;
+  }
+  if (!result.archived || result.archived.length === 0) {
+    logger.info(
+      `HANDOFF.md already at or under ${keep} narrative ${keep === 1 ? "entry" : "entries"}; nothing to prune.`
+    );
+    return;
+  }
+  const archiveDir = path.join(cwd, ".cursor", "context", "archive");
+  await ensureDir(archiveDir);
+  const archivePath = path.join(archiveDir, `handoff-${pruneArchiveTimestamp()}.md`);
+  const header = [
+    `<!-- Pruned from .cursor/HANDOFF.md at ${(/* @__PURE__ */ new Date()).toISOString()} -->`,
+    `<!-- ${result.archived.length} narrative ${result.archived.length === 1 ? "entry" : "entries"} archived, keep=${keep} -->`,
+    ""
+  ].join("\n");
+  const body = `${result.archived.join("\n\n")}
+`;
+  if (await fileExists(archivePath)) {
+    await appendFile(archivePath, `
+${header}${body}`, "utf8");
+  } else {
+    await writeFile(archivePath, `${header}${body}`, "utf8");
+  }
+  await writeFile(handoffPath, result.text ?? original, "utf8");
+  logger.success(
+    `HANDOFF.md pruned: kept ${result.keptCount} narrative ${result.keptCount === 1 ? "entry" : "entries"}, archived ${result.archived.length} to ${path.relative(cwd, archivePath)}.`
+  );
+}
+var PRESERVED_FIELDS = [
+  "Run queue",
+  "Queue cursor",
+  "Queue status",
+  "Queue outcomes",
+  "Backlog plans",
+  "Parked plans"
+];
+function hasFrontmatter(raw) {
+  return /^---\r?\n[\s\S]*?\r?\n---/.test(raw);
+}
+function todoText(t) {
+  return (t.content ?? t.id).replace(/^["']|["']$/g, "");
+}
+function copyFieldBlock(text, label) {
+  if (extractFieldBlock(text, label) === null) return null;
+  const lines = text.split("\n");
+  const start = lines.findIndex((l) => l.startsWith(`- **${label}:**`));
+  if (start < 0) return null;
+  let end = start + 1;
+  while (end < lines.length) {
+    const line = lines[end] ?? "";
+    if (/^- \*\*[^*:\n]+:\*\*/.test(line) || line.trim() && !/^\s+\S/.test(line)) break;
+    end += 1;
+  }
+  while (end > start + 1 && !lines[end - 1]?.trim()) end -= 1;
+  return lines.slice(start, end).join("\n");
+}
+async function findActivePlan(root, handoff) {
+  const active = extractHandoffNamedPlans(handoff).active;
+  if (active) {
+    for (const candidate of namedPlanCandidatePaths(root, active)) {
+      if (await fileExists(candidate)) {
+        return { file: active, raw: await readFile(candidate, "utf8") };
+      }
+    }
+  }
+  const plansDir = path.join(root, ".cursor", "plans");
+  if (!await fileExists(plansDir)) return null;
+  const files = (await readdir(plansDir)).filter((f) => f.endsWith(".plan.md")).sort().reverse();
+  for (const file of files) {
+    const raw = await readFile(path.join(plansDir, file), "utf8");
+    const fm = parsePlanFrontmatter(raw);
+    if (fm?.todos?.some((t) => t.status !== "completed" && t.status !== "cancelled")) {
+      return { file, raw };
+    }
+  }
+  return files[0] ? { file: files[0], raw: await readFile(path.join(plansDir, files[0]), "utf8") } : null;
+}
+function now() {
+  return (/* @__PURE__ */ new Date()).toISOString().replace("T", " ").slice(0, 16);
+}
+async function loadProfile(rootDir) {
+  const configPath = path.join(rootDir, ".cursor", "agent-kit.config.json");
+  try {
+    return await readJson(configPath);
+  } catch {
+    return null;
+  }
+}
+function buildRoutines(profile) {
+  const lines = [];
+  const workflow = profile?.git.workflow;
+  if (workflow === "homolog-prod") {
+    lines.push("- [ ] `git staging` - move changes to staging");
+    lines.push("- [ ] `git prod` - promote to production (after approval)");
+  } else {
+    lines.push("- [ ] Commit, push and open PR/MR");
+  }
+  const pmTools = profile?.services.projectManagement;
+  if (pmTools && pmTools.length > 0) {
+    const labels = pmTools.map((t) => PM_TOOL_LABELS[t]).join(", ");
+    lines.push(`- [ ] Update tasks in ${labels} (if applicable)`);
+  }
+  lines.push("- [ ] Review CHANGELOG");
+  return lines;
+}
+function closingInstruction(profile) {
+  const pmTools = profile?.services.projectManagement;
+  if (pmTools && pmTools.length > 0) {
+    const labels = pmTools.map((t) => PM_TOOL_LABELS[t]).join(", ");
+    return `All todos completed. Check git staging/prod and update ${labels} if applicable.`;
+  }
+  return "All todos completed. Check commit/push and PR/MR.";
+}
+function buildHandoff(planFile, fm, profile, preserved = []) {
+  const completed = fm.todos?.filter((t) => t.status === "completed") ?? [];
+  const pending = fm.todos?.filter((t) => t.status === "pending") ?? [];
+  const inProgress = fm.todos?.filter((t) => t.status === "in_progress") ?? [];
+  const nextTodo = inProgress[0] ?? pending[0];
+  const completedPhase = completed.length;
+  const totalPhases = fm.todos?.length ?? 0;
+  const routines = buildRoutines(profile);
+  return [
+    `# Handoff - ${fm.name ?? planFile}`,
+    "",
+    `- **Plan:** ${planFile}`,
+    `- **Last updated:** ${now()}`,
+    `- **Progress:** ${completedPhase}/${totalPhases} todos completed`,
+    ...preserved,
+    "",
+    "## Completed",
+    ...completed.length > 0 ? completed.map((t) => `- [x] \`${t.id}\`: ${todoText(t)}`) : ["- (none)"],
+    "",
+    "## In progress",
+    ...inProgress.length > 0 ? inProgress.map((t) => `- [ ] \`${t.id}\`: ${todoText(t)}`) : ["- (none)"],
+    "",
+    "## Pending",
+    ...pending.length > 0 ? pending.map((t) => `- [ ] \`${t.id}\`: ${todoText(t)}`) : ["- (none)"],
+    "",
+    "## Instruction for Next Agent",
+    "",
+    nextTodo ? `Continue from todo \`${nextTodo.id}\`: ${todoText(nextTodo)}.` : closingInstruction(profile),
+    "",
+    "## Suggested routines",
+    "",
+    ...routines,
+    "",
+    "---",
+    "*Generated by `agent-kit handoff`. To resume: open new conversation and say `/continue-plan`.*",
+    ""
+  ].join("\n");
+}
+function printV3Guidance() {
+  logger.info("No plan in .cursor/plans/ and no ./cursor-handoff in this directory.");
+  logger.info(
+    "Create a plan with todos or update .cursor/HANDOFF.md manually (/handoff command in Cursor)."
+  );
+  logger.info("Resume in IDE: /resume, summaries and transcripts.");
+}
+function runCursorHandoff(scriptPath, cwd) {
+  return new Promise((resolve, reject) => {
+    const child = spawn("sh", [scriptPath, "handoff"], {
+      cwd,
+      stdio: "inherit"
+    });
+    child.on("error", (err) => reject(err));
+    child.on("close", (code) => resolve(code ?? 1));
+  });
+}
+var handoffCommand = defineCommand({
+  meta: {
+    name: "handoff",
+    description: "Write .cursor/HANDOFF.md from the active plan (or cursor-handoff fallback)."
+  },
+  args: {
+    cwd: {
+      type: "string",
+      description: "Project root directory",
+      default: process.cwd()
+    },
+    prune: {
+      type: "boolean",
+      description: "Prune .cursor/HANDOFF.md in place instead of regenerating it: keep the most recent narrative entries, archive the rest to .cursor/context/archive/. Never auto-triggered.",
+      default: false
+    },
+    keep: {
+      type: "string",
+      description: `With --prune, how many recent narrative entries to keep in place (default ${HANDOFF_PRUNE_DEFAULT_KEEP}).`
+    }
+  },
+  async run({ args }) {
+    if (args.prune) {
+      const keepArg = typeof args.keep === "string" ? Number.parseInt(args.keep, 10) : void 0;
+      const keep = keepArg !== void 0 && Number.isFinite(keepArg) && keepArg >= 0 ? keepArg : HANDOFF_PRUNE_DEFAULT_KEEP;
+      await runPrune(args.cwd, keep);
+      return;
+    }
+    const profile = await loadProfile(args.cwd);
+    const handoffPath = path.join(args.cwd, HANDOFF_REL);
+    const previous = await fileExists(handoffPath) ? await readFile(handoffPath, "utf8") : "";
+    const plan = await findActivePlan(args.cwd, previous);
+    if (plan) {
+      if (hasFrontmatter(plan.raw)) {
+        const fm = parsePlanFrontmatter(plan.raw);
+        const preserved = PRESERVED_FIELDS.map((label) => copyFieldBlock(previous, label)).filter(
+          (block) => block !== null
+        );
+        await ensureDir(path.join(args.cwd, ".cursor"));
+        const content = buildHandoff(plan.file, fm, profile, preserved);
+        await writeFile(handoffPath, content, "utf8");
+        logger.success("HANDOFF.md updated: .cursor/HANDOFF.md");
+        logger.info(
+          `Plan: ${plan.file} (${fm.todos?.filter((t) => t.status === "completed").length}/${fm.todos?.length} completed)`
+        );
+        logger.info("");
+        logger.info("Suggested next steps:");
+        let n = 1;
+        for (const line of buildRoutines(profile)) {
+          logger.info(`  ${n}. ${line.replace(/^- \[ \] /, "")}`);
+          n += 1;
+        }
+        logger.info("");
+        logger.info("To resume: open new conversation and say /continue-plan");
+        return;
+      }
+      logger.warn(`Plan ${plan.file} without valid frontmatter; trying legacy flow.`);
+    }
+    const scriptPath = path.join(args.cwd, "cursor-handoff");
+    if (!await fileExists(scriptPath)) {
+      printV3Guidance();
+      return;
+    }
+    if (process.platform === "win32") {
+      logger.warn(
+        "cursor-handoff is a shell script. On Windows, run in Git Bash or WSL: sh cursor-handoff handoff"
+      );
+      printV3Guidance();
+      return;
+    }
+    try {
+      const code = await runCursorHandoff(scriptPath, args.cwd);
+      if (code !== 0) {
+        process.exitCode = code;
+      }
+    } catch (err) {
+      logger.warn(`Failed to execute cursor-handoff: ${String(err)}`);
+      printV3Guidance();
+    }
+  }
+});
+export {
+  HANDOFF_PRUNE_DEFAULT_KEEP,
+  buildRoutines,
+  handoffCommand,
+  loadProfile,
+  runPrune
+};