@yaawn/workflow 0.0.0-stage → 0.4.0

package/agents/skills/yaawn-save-plan/scripts/save-plan.ts

@@ -0,0 +1,539 @@
+import { execFileSync } from "node:child_process";
+import {
+  existsSync,
+  mkdirSync,
+  readFileSync,
+  readdirSync,
+  realpathSync,
+  unlinkSync,
+  writeFileSync,
+} from "node:fs";
+import path from "node:path";
+import {
+  dependsOnLine,
+  removeGroupLabels,
+} from "../../yaawn-implement-plan/scripts/targets.js";
+import {
+  branchName,
+  branchWorktreeFromPorcelain,
+  currentToplevel,
+  defaultBranches,
+  entriesFromPorcelain,
+  listPorcelain,
+  mainCopyFromPorcelain,
+} from "../../yaawn-implement-plan/scripts/worktrees.js";
+import {
+  type Section,
+  answerOpenQuestions,
+  buildBody,
+  filesToChangeContent,
+  findSection,
+  headingList,
+  humanReadableTitle,
+  openQuestions,
+  openQuestionsTitle,
+  ownLlmPlanContent,
+  planSubsections,
+  readyBlocker,
+  toLines,
+} from "./plan-body.js";
+
+const plansDir = ".yaawn/plans";
+const refinementLabel = "Yaawn: To Be Refined";
+const readyLabel = "Yaawn: Ready To Implement";
+const readyLabelColor = "0E8A16";
+const readyLabelDescription =
+  "Plan saved, no open questions — ready for /yaawn-implement-plan";
+const usage =
+  "Usage: npx tsx .agents/skills/yaawn-save-plan/scripts/save-plan.ts <find [issue]|open-questions <issue>|answer <issue>|preview <issue>|save <issue>>";
+
+const issuePattern = /^[1-9]\d*$/;
+const planFilePattern = /^yaawn-([1-9]\d*)-plan\.md$/;
+const issueBranchPattern = /^yaawn\/[1-9]\d*$/;
+
+export type Resolution<T> = { ok: true; value: T } | { ok: false; reason: string };
+
+export interface WorktreeSearch {
+  porcelain: string;
+  currentToplevel: string;
+  defaultBranches: string[];
+}
+
+export interface PlanFiles {
+  plan: string;
+  humanReadable: string;
+}
+
+export interface PlanCandidate {
+  issue: number;
+  worktree: string;
+}
+
+export const planPath = (worktree: string, issue: number): string =>
+  path.join(worktree, plansDir, `yaawn-${issue}-plan.md`);
+
+const humanReadablePath = (worktree: string, issue: number): string =>
+  path.join(worktree, plansDir, `yaawn-${issue}-human-readable.md`);
+
+// The issue body snapshots always stay in the current worktree.
+const currentBodyPath = (issue: number): string =>
+  `${plansDir}/yaawn-${issue}-body-current.md`;
+
+const newBodyPath = (issue: number): string =>
+  `${plansDir}/yaawn-${issue}-body.md`;
+
+// The user's answers to the plan's open questions — written by the agent,
+// consumed and deleted by the answer command. Like the body snapshots, it
+// lives in the current worktree.
+const answersPath = (issue: number): string =>
+  `${plansDir}/yaawn-${issue}-answers.json`;
+
+// The issue number ends up in file paths and branch names, so only a
+// positive integer is accepted.
+export function parseIssue(argument: string | undefined): number | null {
+  if (!issuePattern.test(argument ?? "")) return null;
+  const issue = Number(argument);
+  return Number.isSafeInteger(issue) ? issue : null;
+}
+
+const uniquePaths = (worktrees: (string | null)[]): string[] => [
+  ...new Set(
+    worktrees
+      .filter((worktree): worktree is string => worktree !== null)
+      .map((worktree) => path.resolve(worktree)),
+  ),
+];
+
+// --- plan file resolution
+
+// Order matters: the current worktree first, then the issue's own, then the
+// main copy.
+export function planCandidates(issue: number, search: WorktreeSearch): string[] {
+  return uniquePaths([
+    search.currentToplevel,
+    branchWorktreeFromPorcelain(search.porcelain, branchName(issue)),
+    mainCopyFromPorcelain(search.porcelain, search.defaultBranches),
+  ]);
+}
+
+const listedWorktrees = (worktrees: string[]): string =>
+  worktrees.map((worktree) => `  - ${worktree}`).join("\n");
+
+// The current worktree wins; elsewhere exactly one holder is required — a
+// guess between several could save the wrong plan.
+export function resolvePlanDir(
+  issue: number,
+  candidates: string[],
+  hasFile: (file: string) => boolean,
+): Resolution<string> {
+  const [current, ...others] = candidates;
+  if (current !== undefined && hasFile(planPath(current, issue))) {
+    return { ok: true, value: current };
+  }
+  const holders = others.filter((worktree) => hasFile(planPath(worktree, issue)));
+  if (holders.length === 1) return { ok: true, value: holders[0] as string };
+  if (holders.length > 1) {
+    return {
+      ok: false,
+      reason: `several worktrees hold yaawn-${issue}-plan.md — run this skill in the one whose plan you want to save:\n${listedWorktrees(holders)}`,
+    };
+  }
+  return {
+    ok: false,
+    reason: `no worktree holds yaawn-${issue}-plan.md — start a new session and run /yaawn-create-plan ${issue} first; searched:\n${listedWorktrees(candidates)}`,
+  };
+}
+
+// --- issue inference
+
+export function inferenceCandidates(search: WorktreeSearch): string[] {
+  const issueWorktrees = entriesFromPorcelain(search.porcelain)
+    .filter((entry) => !entry.bare && issueBranchPattern.test(entry.branch ?? ""))
+    .map((entry) => entry.path);
+  return uniquePaths([
+    search.currentToplevel,
+    ...issueWorktrees,
+    mainCopyFromPorcelain(search.porcelain, search.defaultBranches),
+  ]);
+}
+
+const plansIn = (
+  worktree: string,
+  planFiles: (worktree: string) => string[],
+): PlanCandidate[] =>
+  planFiles(worktree)
+    .map((file) => planFilePattern.exec(file)?.[1])
+    .filter((issue): issue is string => issue !== undefined)
+    .map((issue) => ({ issue: Number(issue), worktree }));
+
+const listedPlans = (plans: PlanCandidate[]): string =>
+  plans.map(({ issue, worktree }) => `  - #${issue} in ${worktree}`).join("\n");
+
+export function inferIssue(
+  candidates: string[],
+  planFiles: (worktree: string) => string[],
+): Resolution<number> {
+  const plans = candidates.flatMap((worktree) => plansIn(worktree, planFiles));
+  const issues = new Set(plans.map(({ issue }) => issue));
+  if (issues.size === 1) return { ok: true, value: [...issues][0] as number };
+  if (issues.size > 1) {
+    return {
+      ok: false,
+      reason: `several plan files found — which issue should be saved?\n${listedPlans(plans)}`,
+    };
+  }
+  return {
+    ok: false,
+    reason: "no plan file found — which issue number should be saved?",
+  };
+}
+
+// --- git and file system
+
+// Without git worktrees (no git, no repository) only the current directory
+// is searched — the behavior before worktree support.
+function worktreeSearch(): WorktreeSearch | null {
+  try {
+    return {
+      porcelain: listPorcelain(),
+      currentToplevel: currentToplevel(),
+      defaultBranches: defaultBranches(),
+    };
+  } catch {
+    return null;
+  }
+}
+
+function planFilesOf(worktree: string): string[] {
+  try {
+    return readdirSync(path.join(worktree, plansDir));
+  } catch {
+    return [];
+  }
+}
+
+const unwrap = <T>(resolution: Resolution<T>): T => {
+  if (!resolution.ok) throw new Error(resolution.reason);
+  return resolution.value;
+};
+
+function findPlanFiles(issue: number, search: WorktreeSearch | null): PlanFiles {
+  const candidates = search ? planCandidates(issue, search) : [process.cwd()];
+  const worktree = unwrap(resolvePlanDir(issue, candidates, existsSync));
+  return {
+    plan: planPath(worktree, issue),
+    humanReadable: humanReadablePath(worktree, issue),
+  };
+}
+
+function findIssue(search: WorktreeSearch | null): number {
+  const candidates = search ? inferenceCandidates(search) : [process.cwd()];
+  return unwrap(inferIssue(candidates, planFilesOf));
+}
+
+function gh(args: string[]): string {
+  return execFileSync("gh", args, { encoding: "utf-8" });
+}
+
+function readRequiredFile(file: string, hint: string): string {
+  if (!existsSync(file)) throw new Error(`${file} not found — ${hint}`);
+  const content = readFileSync(file, "utf-8").trim();
+  if (!content) throw new Error(`${file} is empty — ${hint}`);
+  return content;
+}
+
+function readAnswers(file: string): Map<string, string> {
+  if (!existsSync(file)) {
+    throw new Error(`${file} not found — write the user's answers there first`);
+  }
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(readFileSync(file, "utf-8"));
+  } catch (error) {
+    throw new Error(`${file} is not valid JSON — ${errorMessage(error)}`);
+  }
+  if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+    throw new Error(
+      `${file} must hold a JSON object mapping question numbers to answers`,
+    );
+  }
+  const answers = new Map<string, string>();
+  Object.entries(parsed).forEach(([number, answer]) => {
+    if (typeof answer !== "string" || answer.trim() === "") {
+      throw new Error(
+        `${file}: the answer for #${number} must be a non-empty string`,
+      );
+    }
+    answers.set(number, answer);
+  });
+  if (answers.size === 0) throw new Error(`${file} holds no answers`);
+  return answers;
+}
+
+function readPlanSubsections(planFile: string): Map<string, string> {
+  const lines = toLines(readRequiredFile(planFile, "run /yaawn-create-plan first"));
+  const sections = planSubsections.map((title) => ({
+    title,
+    section: findSection(lines, 3, title),
+  }));
+  const missing = sections.filter(({ section }) => section === null);
+  if (missing.length > 0) {
+    throw new Error(
+      `${planFile} lacks: ${headingList(missing.map(({ title }) => title))}`,
+    );
+  }
+  return new Map(
+    sections.map(({ title, section }) => [
+      title,
+      lines
+        .slice((section as Section).contentStart, (section as Section).contentEnd)
+        .join("\n")
+        .trim(),
+    ]),
+  );
+}
+
+function readNewContent(files: PlanFiles): Map<string, string> {
+  const content = readPlanSubsections(files.plan);
+  content.set(
+    humanReadableTitle,
+    readRequiredFile(
+      files.humanReadable,
+      "write the Human Readable summary first",
+    ),
+  );
+  return content;
+}
+
+function fetchBody(issue: number): string {
+  return gh(["issue", "view", String(issue), "--json", "body", "--jq", ".body"])
+    .replace(/\r\n/g, "\n")
+    .trimEnd();
+}
+
+// diff exits 1 when the files differ; its output is the result, not an error.
+function diffOf(currentPath: string, newPath: string): string {
+  try {
+    execFileSync("diff", ["-u", currentPath, newPath], { encoding: "utf-8" });
+    return "no changes";
+  } catch (error) {
+    const { stdout } = error as { stdout?: string };
+    if (stdout) return stdout;
+    throw error;
+  }
+}
+
+function preview(issue: number, files: PlanFiles): void {
+  const content = readNewContent(files);
+  const body = fetchBody(issue);
+  writeFileSync(currentBodyPath(issue), `${body}\n`);
+  writeFileSync(newBodyPath(issue), buildBody(body, content));
+  console.log(`existing plan: ${ownLlmPlanContent(body) ? "yes" : "no"}`);
+  console.log("--- diff of the issue body");
+  console.log(diffOf(currentBodyPath(issue), newBodyPath(issue)));
+}
+
+function issueLabels(issue: number): string[] {
+  return gh([
+    "issue",
+    "view",
+    String(issue),
+    "--json",
+    "labels",
+    "--jq",
+    ".labels[].name",
+  ])
+    .split("\n")
+    .filter((label) => label !== "");
+}
+
+function hasLabel(issue: number, label: string): boolean {
+  return issueLabels(issue).includes(label);
+}
+
+function removeRefinementLabel(issue: number): void {
+  if (!hasLabel(issue, refinementLabel)) {
+    console.log(`label "${refinementLabel}" not present`);
+    return;
+  }
+  gh(["issue", "edit", String(issue), "--remove-label", refinementLabel]);
+  console.log(`removed label "${refinementLabel}"`);
+}
+
+const errorMessage = (error: unknown): string =>
+  error instanceof Error ? error.message.trim() : String(error);
+
+// Runs after the body is saved: a label failure must not fail the save.
+function markReady(issue: number, content: Map<string, string>): void {
+  const blocker = readyBlocker(content);
+  if (blocker) {
+    console.log(`not marked ready: ${blocker}`);
+    return;
+  }
+  try {
+    ensureReadyLabelExists();
+    gh(["issue", "edit", String(issue), "--add-label", readyLabel]);
+    console.log(`added label "${readyLabel}"`);
+  } catch (error) {
+    console.warn(
+      `warning: could not add label "${readyLabel}" — add it manually: ${errorMessage(error)}`,
+    );
+  }
+}
+
+// Both sections feed the implementation grouping, so a change to either
+// invalidates the issue's group labels.
+function groupingInputsChanged(oldBody: string, newBody: string): boolean {
+  return (
+    filesToChangeContent(oldBody) !== filesToChangeContent(newBody) ||
+    dependsOnLine(oldBody) !== dependsOnLine(newBody)
+  );
+}
+
+function labelExists(label: string): boolean {
+  return gh([
+    "label",
+    "list",
+    "--search",
+    label,
+    "--limit",
+    "100",
+    "--json",
+    "name",
+    "--jq",
+    ".[].name",
+  ])
+    .split("\n")
+    .includes(label);
+}
+
+function ensureReadyLabelExists(): void {
+  if (labelExists(readyLabel)) return;
+  try {
+    gh([
+      "label",
+      "create",
+      readyLabel,
+      "--color",
+      readyLabelColor,
+      "--description",
+      readyLabelDescription,
+    ]);
+    console.log(`created label "${readyLabel}"`);
+  } catch (error) {
+    // Another run may have created it in the meantime ("already exists").
+    if (!labelExists(readyLabel)) throw error;
+  }
+}
+
+function save(issue: number, files: PlanFiles): void {
+  const content = readNewContent(files);
+  const oldBody = fetchBody(issue);
+  const newBody = buildBody(oldBody, content);
+  writeFileSync(newBodyPath(issue), newBody);
+  gh(["issue", "edit", String(issue), "--body-file", newBodyPath(issue)]);
+  console.log(`saved the plan to #${issue}`);
+  removeRefinementLabel(issue);
+  if (groupingInputsChanged(oldBody, newBody)) removeGroupLabels(issue);
+  markReady(issue, content);
+}
+
+function find(issueArgument: string | undefined): void {
+  const search = worktreeSearch();
+  const issue =
+    issueArgument === undefined ? findIssue(search) : parseIssue(issueArgument);
+  if (issue === null) throw new Error(usage);
+  const files = findPlanFiles(issue, search);
+  console.log(`issue: ${issue}`);
+  console.log(`plan: ${files.plan}`);
+  console.log(`summary: ${files.humanReadable}`);
+}
+
+function openQuestionsCommand(issueArgument: string | undefined): void {
+  const issue = parseIssue(issueArgument);
+  if (issue === null) throw new Error(usage);
+  const files = findPlanFiles(issue, worktreeSearch());
+  const content = readPlanSubsections(files.plan);
+  const questions = openQuestions(content.get(openQuestionsTitle) ?? "");
+  // The answers file lands in the current worktree — make sure it exists.
+  mkdirSync(plansDir, { recursive: true });
+  console.log(`plan: ${files.plan}`);
+  console.log(`open questions: ${questions.length}`);
+  questions.forEach(({ number, question, owner }) => {
+    console.log(
+      `#${number} ${question}${owner === "" ? "" : ` (owner: ${owner})`}`,
+    );
+  });
+}
+
+function answerCommand(issueArgument: string | undefined): void {
+  const issue = parseIssue(issueArgument);
+  if (issue === null) throw new Error(usage);
+  const files = findPlanFiles(issue, worktreeSearch());
+  const answers = readAnswers(answersPath(issue));
+  const plan = readRequiredFile(files.plan, "run /yaawn-create-plan first");
+  const lines = toLines(plan);
+  const section = findSection(lines, 3, openQuestionsTitle);
+  if (!section) {
+    throw new Error(`${files.plan} lacks: ### ${openQuestionsTitle}`);
+  }
+  const result = answerOpenQuestions(
+    lines.slice(section.contentStart, section.contentEnd).join("\n"),
+    answers,
+  );
+  if (result.unknown.length > 0) {
+    throw new Error(
+      `no open question(s) ${result.unknown.map((number) => `#${number}`).join(", ")} in ${files.plan} — the plan changed since the questions were listed; run open-questions again`,
+    );
+  }
+  if (result.answered.length === 0) {
+    throw new Error(
+      `no answers applied — ${answersPath(issue)} holds ${answers.size} answer(s), none matched an open question`,
+    );
+  }
+  writeFileSync(
+    files.plan,
+    `${[
+      ...lines.slice(0, section.contentStart),
+      ...toLines(result.section),
+      ...lines.slice(section.contentEnd),
+    ].join("\n").trimEnd()}\n`,
+  );
+  unlinkSync(answersPath(issue));
+  console.log(
+    `answered ${result.answered.length} open question(s) in ${files.plan}: ${result.answered.map((number) => `#${number}`).join(", ")}`,
+  );
+}
+
+function saveCommand(command: string, issueArgument: string | undefined): void {
+  const issue = parseIssue(issueArgument);
+  if (issue === null) throw new Error(usage);
+  const files = findPlanFiles(issue, worktreeSearch());
+  mkdirSync(plansDir, { recursive: true });
+  if (command === "preview") preview(issue, files);
+  else save(issue, files);
+}
+
+function main(): void {
+  const [command, issueArgument] = process.argv.slice(2);
+  if (command === "find") find(issueArgument);
+  else if (command === "open-questions") openQuestionsCommand(issueArgument);
+  else if (command === "answer") answerCommand(issueArgument);
+  else if (command === "preview" || command === "save")
+    saveCommand(command, issueArgument);
+  else throw new Error(usage);
+}
+
+const runsAsScript =
+  process.argv[1] !== undefined &&
+  existsSync(process.argv[1]) &&
+  path.basename(realpathSync(process.argv[1])) === "save-plan.ts";
+
+if (runsAsScript) {
+  try {
+    main();
+  } catch (error: unknown) {
+    console.error(error instanceof Error ? error.message : error);
+    process.exit(1);
+  }
+}