@yaawn/workflow 0.0.0-stage → 0.4.0

package/agents/skills/yaawn-implement-plan/scripts/processes.ts

@@ -0,0 +1,53 @@
+import type { ChildProcess } from "node:child_process";
+import type { Readable } from "node:stream";
+import { finished } from "node:stream/promises";
+import { setTimeout as delay } from "node:timers/promises";
+
+const outputDrainTimeoutMs = 5000;
+
+function processStreams(child: ChildProcess): Readable[] {
+  return [child.stdout, child.stderr].filter(
+    (stream): stream is Readable => stream !== null,
+  );
+}
+
+function ignoreAbort(error: unknown): void {
+  if (error instanceof Error && error.name === "AbortError") return;
+  throw error;
+}
+
+// 'exit' can fire before the last output lines are read. Wait for the pipes
+// to close, but not forever: a background process the child left running may
+// hold them open, which would also keep this orchestrator from exiting.
+// The losing timeout is aborted so no timer outlives the drain.
+export async function drainOutput(
+  child: ChildProcess,
+  timeoutMs = outputDrainTimeoutMs,
+): Promise<void> {
+  const streams = processStreams(child);
+  const timeout = new AbortController();
+  const allClosed = Promise.all(
+    streams.map((stream) => finished(stream).catch(() => undefined)),
+  );
+  const timedOut = delay(timeoutMs, undefined, { signal: timeout.signal })
+    .catch(ignoreAbort);
+  try {
+    await Promise.race([allClosed, timedOut]);
+  } finally {
+    timeout.abort();
+  }
+  streams.forEach((stream) => stream.destroy());
+}
+
+// -pid reaches the child's whole process group; spawn the child detached.
+export function killProcessGroup(
+  child: ChildProcess,
+  signal: NodeJS.Signals,
+): void {
+  if (child.pid === undefined) return;
+  try {
+    process.kill(-child.pid, signal);
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code !== "ESRCH") throw error;
+  }
+}

package/agents/skills/yaawn-implement-plan/scripts/stages.ts

@@ -0,0 +1,65 @@
+import { issueRefs } from "./targets.js";
+
+export const STAGES = ["implement", "review", "fix"] as const;
+
+export type Stage = (typeof STAGES)[number];
+
+// A lane that stops before its first stage marker arrives has no stage yet.
+export const laneStartedLabel = "started";
+
+export type StageLabel = Stage | typeof laneStartedLabel;
+
+export type LaneOutcomeState = "started" | "done" | "failed" | "stopped";
+
+export interface LaneOutcome {
+  issue: number;
+  state: LaneOutcomeState;
+  stage?: StageLabel;
+}
+
+const stageMarkerPrefix = "yaawn-stage:";
+
+export function stageMarker(issue: number, stage: Stage): string {
+  return `${stageMarkerPrefix} ${issue} ${stage}`;
+}
+
+// Lane output is untrusted: accept only the exact marker of the lane's own issue.
+export function parseStageMarker(line: string, issue: number): Stage | undefined {
+  return STAGES.find((stage) => line === stageMarker(issue, stage));
+}
+
+export function runningResult(issue: number, stage: StageLabel): string {
+  return `#${issue} running — stage ${stage}`;
+}
+
+export function stoppedResult(issue: number, stage: StageLabel): string {
+  return `#${issue} stopped in ${stage}`;
+}
+
+function issuesIn(lanes: LaneOutcome[], states: LaneOutcomeState[]): number[] {
+  return lanes
+    .filter((lane) => states.includes(lane.state))
+    .map((lane) => lane.issue);
+}
+
+function failedPart(failed: number[]): string {
+  const refs = failed.length > 0 ? ` (${issueRefs(failed)})` : "";
+  return `${failed.length} failed${refs}`;
+}
+
+function stoppedPart(stopped: LaneOutcome[]): string {
+  const refs = stopped
+    .map((lane) => `#${lane.issue} in ${lane.stage ?? laneStartedLabel}`)
+    .join(", ");
+  return `, ${stopped.length} stopped (${refs})`;
+}
+
+export function runResultLine(lanes: LaneOutcome[]): string {
+  const done = issuesIn(lanes, ["done"]);
+  if (done.length === lanes.length)
+    return `run result: all ${lanes.length} lanes done`;
+  const failed = issuesIn(lanes, ["started", "failed"]);
+  const stopped = lanes.filter((lane) => lane.state === "stopped");
+  const stoppedSuffix = stopped.length > 0 ? stoppedPart(stopped) : "";
+  return `run result: ${done.length} done, ${failedPart(failed)}${stoppedSuffix}`;
+}

package/agents/skills/yaawn-implement-plan/scripts/targets.ts

@@ -0,0 +1,381 @@
+import { execFile, execFileSync } from "node:child_process";
+import { existsSync, readFileSync } from "node:fs";
+import { promisify } from "node:util";
+import { groupLabelRemovals } from "./groups.js";
+
+// Shared by the overnight scripts of yaawn-implement-plan and
+// yaawn-verify-executed-plan: both work on the same targets.
+
+export interface Issue {
+  number: number;
+  title: string;
+  body: string;
+  dependsOn: number[];
+  externalDependsOn: number[];
+}
+
+interface RawIssue {
+  number: number;
+  title: string;
+  body: string | null;
+}
+
+export const plansDir = ".yaawn/plans";
+const groupLabelColor = "5319E7";
+const groupLabelDescription = "Issues with this label can be implemented together in parallel";
+const execFileAsync = promisify(execFile);
+
+export const resultPath = (issue: number): string =>
+  `${plansDir}/yaawn-${issue}-overnight-result.md`;
+
+export const progressPath = (issue: number): string =>
+  `${plansDir}/yaawn-${issue}-progress.md`;
+
+export const issueRefs = (issues: (number | string)[], prefix = "#"): string =>
+  issues.map((issue) => `${prefix}${issue}`).join(", ");
+
+export function gh(args: string[]): string {
+  return execFileSync("gh", args, { encoding: "utf-8" });
+}
+
+export function succeeds(command: string, args: string[]): boolean {
+  try {
+    execFileSync(command, args, { stdio: "ignore" });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+export async function ghAsync(args: string[]): Promise<string> {
+  const { stdout } = await execFileAsync("gh", args, { encoding: "utf-8" });
+  return stdout;
+}
+
+export async function succeedsAsync(command: string, args: string[]): Promise<boolean> {
+  try {
+    await execFileAsync(command, args);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+// --- labels
+
+const labelNames = (output: string): string[] =>
+  output.split("\n").map((name) => name.trim()).filter(Boolean);
+
+export function issueLabels(issue: number): string[] {
+  return labelNames(
+    gh(["issue", "view", String(issue), "--json", "labels", "--jq", ".labels[].name"]),
+  );
+}
+
+export function addLabel(issue: number, label: string): void {
+  gh(["issue", "edit", String(issue), "--add-label", label]);
+}
+
+export function removeLabel(issue: number, label: string): void {
+  gh(["issue", "edit", String(issue), "--remove-label", label]);
+}
+
+function labelExists(label: string): boolean {
+  return labelNames(
+    gh(["label", "list", "--search", label, "--limit", "100", "--json", "name", "--jq", ".[].name"]),
+  ).includes(label);
+}
+
+export function ensureGroupLabel(label: string): void {
+  if (labelExists(label)) return;
+  try {
+    gh(["label", "create", label, "--color", groupLabelColor, "--description", groupLabelDescription]);
+    console.log(`created label "${label}"`);
+  } catch (error) {
+    // Another run may have created it in the meantime ("already exists").
+    if (!labelExists(label)) throw error;
+  }
+}
+
+function errorMessage(error: unknown): string {
+  return error instanceof Error ? error.message : String(error);
+}
+
+const firstLine = (text: string): string => text.split("\n")[0];
+
+// The one reset of the implementation-group labels, shared by every skill that
+// changes a plan. It only warns: a failed reset never blocks the caller.
+export function removeGroupLabels(issue: number): void {
+  if (!Number.isSafeInteger(issue) || issue < 1) {
+    console.log(`WARN group labels not reset: invalid issue ${JSON.stringify(issue)}`);
+    return;
+  }
+  try {
+    groupLabelRemovals(issue, issueLabels(issue)).forEach(({ label }) => {
+      removeLabel(issue, label);
+      console.log(`removed label "${label}" on #${issue}`);
+    });
+  } catch (error) {
+    console.log(`WARN could not reset group labels on #${issue}: ${firstLine(errorMessage(error))}`);
+  }
+}
+
+// --- issues
+
+const dependsOnPattern = /\*\*Depends on:\*\*\s*(.+)/;
+
+export function dependsOnLine(body: string): string {
+  return dependsOnPattern.exec(body)?.[0] ?? "";
+}
+
+function parseDependsOn(body: string): number[] {
+  const line = dependsOnPattern.exec(body)?.[1] ?? "";
+  return [...line.matchAll(/#(\d+)/g)].map((match) => Number(match[1]));
+}
+
+function toIssue({ number, title, body }: RawIssue): Issue {
+  return {
+    number,
+    title,
+    body: body ?? "",
+    dependsOn: parseDependsOn(body ?? ""),
+    externalDependsOn: [],
+  };
+}
+
+const fetchIssueArgs = (issue: number): string[] => [
+  "issue",
+  "view",
+  String(issue),
+  "--json",
+  "number,title,body",
+];
+
+const parseIssue = (output: string): Issue => toIssue(JSON.parse(output) as RawIssue);
+
+export function fetchIssue(issue: number): Issue {
+  return parseIssue(gh(fetchIssueArgs(issue)));
+}
+
+export async function fetchIssueAsync(issue: number): Promise<Issue> {
+  return parseIssue(await ghAsync(fetchIssueArgs(issue)));
+}
+
+function splitDependencies(targets: Issue[]): Issue[] {
+  const targetNumbers = new Set(targets.map((issue) => issue.number));
+  return targets.map((issue) => ({
+    ...issue,
+    dependsOn: issue.dependsOn.filter((dep) => targetNumbers.has(dep)),
+    externalDependsOn: issue.dependsOn.filter((dep) => !targetNumbers.has(dep)),
+  }));
+}
+
+export function resolveTargets(parent: number): Issue[] {
+  return splitDependencies([fetchIssue(parent)]);
+}
+
+export async function resolveTargetsAsync(parent: number): Promise<Issue[]> {
+  return splitDependencies([await fetchIssueAsync(parent)]);
+}
+
+const issueStateArgs = (issue: number): string[] => [
+  "api",
+  `repos/{owner}/{repo}/issues/${issue}`,
+  "--jq",
+  ".state",
+];
+
+export function isOpen(issue: number): boolean {
+  return gh(issueStateArgs(issue)).trim() === "open";
+}
+
+export async function isOpenAsync(issue: number): Promise<boolean> {
+  return (await ghAsync(issueStateArgs(issue))).trim() === "open";
+}
+
+export function isDone(issue: number): boolean {
+  if (!existsSync(progressPath(issue))) return false;
+  const progress = readFileSync(progressPath(issue), "utf-8");
+  return progress.includes("- [x]") && !progress.includes("- [ ]");
+}
+
+// Dependencies first; issues whose dependencies are equally settled keep
+// ascending issue-number order.
+export function executionOrder(issues: Issue[]): Issue[] {
+  const placed = new Set<number>();
+  const ordered: Issue[] = [];
+  let remaining = [...issues].sort((a, b) => a.number - b.number);
+  while (remaining.length > 0) {
+    const ready = remaining.filter((issue) =>
+      issue.dependsOn.every((dep) => placed.has(dep)),
+    );
+    if (ready.length === 0) {
+      throw new Error(
+        `Circular dependency among ${issueRefs(remaining.map((issue) => issue.number))}`,
+      );
+    }
+    ready.forEach((issue) => placed.add(issue.number));
+    ordered.push(...ready);
+    remaining = remaining.filter((issue) => !placed.has(issue.number));
+  }
+  return ordered;
+}
+
+// The planning and run files under .yaawn/plans/ are not the human's changes.
+const uncommittedChangesArgs = ["status", "--short", "--", ".", `:!${plansDir}`];
+
+export function uncommittedChanges(): string {
+  return execFileSync("git", uncommittedChangesArgs, { encoding: "utf-8" });
+}
+
+export async function uncommittedChangesAsync(): Promise<string> {
+  const { stdout } = await execFileAsync("git", uncommittedChangesArgs, {
+    encoding: "utf-8",
+  });
+  return stdout;
+}
+
+const fenceMarkers = ["```", "~~~"];
+const sectionBoundaryPattern = /^#{2,4} /;
+
+function fenceMarkerOf(trimmedLine: string): string | null {
+  return fenceMarkers.find((marker) => trimmedLine.startsWith(marker)) ?? null;
+}
+
+function linesOutsideFences(lines: string[]): boolean[] {
+  let openFence: string | null = null;
+  return lines.map((line) => {
+    const marker = fenceMarkerOf(line.trim());
+    if (openFence === null && marker !== null) {
+      openFence = marker;
+      return false;
+    }
+    if (openFence !== null) {
+      if (marker === openFence) openFence = null;
+      return false;
+    }
+    return true;
+  });
+}
+
+export function sectionContent(body: string, heading: string): string {
+  const lines = body.split("\n");
+  const outside = linesOutsideFences(lines);
+  const marker = `### ${heading}`;
+  const start = lines.findIndex((line, index) => outside[index] && line.trim() === marker);
+  if (start === -1) return "";
+  const relativeEnd = lines
+    .slice(start + 1)
+    .findIndex(
+      (line, offset) =>
+        outside[start + 1 + offset] && sectionBoundaryPattern.test(line.trim()),
+    );
+  const end = relativeEnd === -1 ? lines.length : start + 1 + relativeEnd;
+  return lines
+    .slice(start + 1, end)
+    .join("\n")
+    .replace(/<!--[\s\S]*?-->/g, "")
+    .trim();
+}
+
+// Cells may contain escaped pipes ("\|"); only unescaped pipes separate cells.
+function tableBodyRows(markdown: string): string[][] {
+  const headerAndSeparator = 2;
+  return markdown
+    .split("\n")
+    .filter((line) => line.trim().startsWith("|"))
+    .slice(headerAndSeparator)
+    .map((line) =>
+      line
+        .split(/(?<!\\)\|/)
+        .slice(1, -1)
+        .map((cell) => cell.trim()),
+    );
+}
+
+function unansweredQuestionRows(body: string): string[][] {
+  return tableBodyRows(sectionContent(body, "Open Questions")).filter(
+    ([, question, , answer]) => Boolean(question) && !answer,
+  );
+}
+
+export function unansweredQuestions(body: string): string[] {
+  return unansweredQuestionRows(body).map(([id, question]) => id || question);
+}
+
+// ID and text of each unanswered question, so it can be asked without
+// re-reading the issue.
+export function unansweredQuestionTexts(body: string): string[] {
+  return unansweredQuestionRows(body).map(([id, question]) =>
+    id ? `${id} ${question}` : question,
+  );
+}
+
+function missingPlanFailures(issue: Issue): string[] {
+  return sectionContent(issue.body, "LLM Plan")
+    ? []
+    : [`#${issue.number} has no saved plan (run yaawn-save-plan)`];
+}
+
+function unansweredQuestionFailures(issue: Issue): string[] {
+  const missing = unansweredQuestions(issue.body);
+  return missing.length === 0
+    ? []
+    : [`#${issue.number} unanswered questions: ${issueRefs(missing, "Q#")}`];
+}
+
+type DependencyState = "open" | "closed" | { failure: string };
+
+// Fails closed: a dependency whose state cannot be read blocks the issue.
+async function dependencyState(issue: Issue, dependency: number): Promise<DependencyState> {
+  try {
+    return (await isOpenAsync(dependency)) ? "open" : "closed";
+  } catch (error) {
+    return {
+      failure: `#${issue.number} could not check dependency #${dependency}: ${firstLine(errorMessage(error))}`,
+    };
+  }
+}
+
+// Sync: the readiness checks of implement-plan's pre-flight, single and multi-issue.
+function openExternalDependencyFailures(issue: Issue): string[] {
+  const openExternal = issue.externalDependsOn.filter(isOpen);
+  return openExternal.length === 0
+    ? []
+    : [
+        `#${issue.number} depends on open issues outside this run: ${issueRefs(openExternal)}`,
+      ];
+}
+
+export function issueFailures(issue: Issue): string[] {
+  return [
+    ...missingPlanFailures(issue),
+    ...unansweredQuestionFailures(issue),
+    ...openExternalDependencyFailures(issue),
+  ];
+}
+
+// Async: every dependency lookup runs to completion, so all failures show at once.
+async function openExternalDependencyFailuresAsync(issue: Issue): Promise<string[]> {
+  const states = await Promise.all(
+    issue.externalDependsOn.map((dependency) => dependencyState(issue, dependency)),
+  );
+  const openExternal = issue.externalDependsOn.filter((_, index) => states[index] === "open");
+  const lookupFailures = states.flatMap((state) =>
+    typeof state === "object" ? [state.failure] : [],
+  );
+  return openExternal.length === 0
+    ? lookupFailures
+    : [
+        `#${issue.number} depends on open issues outside this run: ${issueRefs(openExternal)}`,
+        ...lookupFailures,
+      ];
+}
+
+export async function issueFailuresAsync(issue: Issue): Promise<string[]> {
+  return [
+    ...missingPlanFailures(issue),
+    ...unansweredQuestionFailures(issue),
+    ...(await openExternalDependencyFailuresAsync(issue)),
+  ];
+}