pi-long-task 0.1.0

package/src/todo_generator.ts

@@ -0,0 +1,304 @@
+import { parseTasks, TodoParseError } from "./todo_parser.ts";
+
+const TODO_HEADING_RE = /^##\s+TODO\s+(\d+)\s+[—-]\s+(.+?)\s*$/gm;
+const TODO_HEADING_LINE_RE = /^##\s+TODO\s+(\d+)\s+[—-]\s+(.+?)\s*$/;
+const PROGRESS_HEADING_RE = /^##\s+Progress\s*$/im;
+const BULLET_ITEM_RE = /^\s*[-*+]\s+(?!-{2,}\s*$)(.+?)\s*$/;
+const NUMBERED_ITEM_RE = /^\s*\d+[.)]\s+(.+?)\s*$/;
+const FENCE_RE = /```(?:markdown|md)?\s*\n([\s\S]*?)\n```/gi;
+
+export class TodoGenerationError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "TodoGenerationError";
+  }
+}
+
+interface ExistingTask {
+  taskId: string;
+  title: string;
+  body: string;
+}
+
+export function todoMarkdownFromString(rawInput: string): string | undefined {
+  const input = rawInput.trim();
+  if (!input) {
+    return undefined;
+  }
+
+  if (hasTodoHeadings(input)) {
+    const markdown = normalizeExistingTodoMarkdown(input);
+    validateTodoMarkdown(markdown);
+    return markdown;
+  }
+
+  const listItems = simpleListItems(input);
+  if (listItems.length >= 2) {
+    const markdown = generatedTodoMarkdown(listItems);
+    validateTodoMarkdown(markdown);
+    return markdown;
+  }
+
+  return undefined;
+}
+
+export function generatedTodoMarkdown(items: string[]): string {
+  const titles = items.map(cleanTitle).filter((item) => item.length > 0);
+  if (titles.length === 0) {
+    throw new TodoGenerationError("Cannot generate TODO markdown without at least one task item.");
+  }
+
+  const progress = titles.map((title, idx) => `- [ ] TODO ${idx + 1} — ${title}`).join("\n");
+  const sections = titles
+    .map((title, idx) => {
+      const taskId = idx + 1;
+      return `## TODO ${taskId} — ${title}\n\n**Goal:** ${goalForTitle(title)}\n\n**Status:**\n- [ ] Complete ${lowercaseFirst(title)}\n\n**Verify:**\n- Run focused checks relevant to this task.\n\n**Done when:**\n- The task is implemented and verified.`;
+    })
+    .join("\n\n");
+
+  return `# Pi Long Task TODO\n\n## Progress\n\n${progress}\n\n---\n\n${sections}\n`;
+}
+
+export function validateTodoMarkdown(markdown: string): void {
+  const trimmed = markdown.trim();
+  if (!trimmed.startsWith("# Pi Long Task TODO")) {
+    throw new TodoGenerationError("TODO markdown must start with `# Pi Long Task TODO`.");
+  }
+  if (!PROGRESS_HEADING_RE.test(trimmed)) {
+    throw new TodoGenerationError("TODO markdown must include a `## Progress` section.");
+  }
+  if (!/^---\s*$/m.test(trimmed)) {
+    throw new TodoGenerationError("TODO markdown must include a `---` separator before task sections.");
+  }
+
+  let tasks;
+  try {
+    tasks = parseTasks(markdown);
+  } catch (error) {
+    if (error instanceof TodoParseError) {
+      throw new TodoGenerationError(error.message);
+    }
+    throw error;
+  }
+
+  if (tasks.length === 0) {
+    throw new TodoGenerationError("TODO markdown must include at least one task section.");
+  }
+
+  tasks.forEach((task, idx) => {
+    const expectedId = String(idx + 1);
+    if (task.taskId !== expectedId) {
+      throw new TodoGenerationError(
+        `Task IDs must be sequential. Expected TODO ${expectedId}, found TODO ${task.taskId}.`,
+      );
+    }
+
+    const progressLine = progressLineRegex(task.taskId, task.title);
+    if (!progressLine.test(markdown)) {
+      throw new TodoGenerationError(`Progress section must include an unchecked line for TODO ${task.taskId}.`);
+    }
+
+    if (!/\*\*Goal:\*\*/.test(task.section)) {
+      throw new TodoGenerationError(`TODO ${task.taskId} must include \`**Goal:**\`.`);
+    }
+    if (!/\*\*Status:\*\*/.test(task.section)) {
+      throw new TodoGenerationError(`TODO ${task.taskId} must include \`**Status:**\`.`);
+    }
+    if (task.statusCheckboxes.length === 0) {
+      throw new TodoGenerationError(`TODO ${task.taskId} must include status checkboxes.`);
+    }
+    if (!/\*\*Verify:\*\*/.test(task.section) && !/verification|verify|checks?/i.test(task.section)) {
+      throw new TodoGenerationError(`TODO ${task.taskId} must include \`**Verify:**\` or verification guidance.`);
+    }
+    if (!/\*\*Done when:\*\*/.test(task.section)) {
+      throw new TodoGenerationError(`TODO ${task.taskId} must include \`**Done when:**\`.`);
+    }
+  });
+}
+
+export function buildTodoCreationPrompt(rawInput: string): string {
+  return `Convert the following raw project request into Pi Long Task-compatible TODO markdown.\n\nRequirements:\n- Output only markdown, with no commentary and no code fence.\n- Start with exactly: # Pi Long Task TODO\n- Include a ## Progress section with one unchecked line per task: - [ ] TODO N — Title\n- Include a --- separator before task sections.\n- Create sequential sections named ## TODO N — Title.\n- Each task section must include **Goal:**, **Status:** with unchecked checkbox items, **Verify:** with concrete verification guidance, and **Done when:**.\n- Preserve any global instructions or constraints that apply to all tasks above ## Progress.\n- Keep tasks focused and independently assignable to worker sessions.\n\nRaw input:\n\n${rawInput.trim()}\n`;
+}
+
+export function extractTodoMarkdown(assistantText: string): string {
+  for (const block of fencedMarkdownBlocks(assistantText)) {
+    const candidate = normalizeCandidate(block);
+    if (candidate) {
+      return candidate;
+    }
+  }
+
+  const headerIndex = assistantText.indexOf("# Pi Long Task TODO");
+  if (headerIndex >= 0) {
+    const candidate = normalizeCandidate(assistantText.slice(headerIndex));
+    if (candidate) {
+      return candidate;
+    }
+  }
+
+  const todoHeading = assistantText.search(/^##\s+TODO\s+\d+\s+[—-]\s+/m);
+  if (todoHeading >= 0) {
+    const candidate = normalizeCandidate(assistantText.slice(todoHeading));
+    if (candidate) {
+      return candidate;
+    }
+  }
+
+  throw new TodoGenerationError("Could not extract valid Pi Long Task TODO markdown from assistant text.");
+}
+
+function normalizeCandidate(candidate: string): string | undefined {
+  try {
+    const markdown = todoMarkdownFromString(candidate.trim());
+    if (markdown) {
+      return markdown;
+    }
+    validateTodoMarkdown(candidate);
+    return ensureTrailingNewline(candidate.trim());
+  } catch {
+    return undefined;
+  }
+}
+
+function hasTodoHeadings(input: string): boolean {
+  TODO_HEADING_RE.lastIndex = 0;
+  return TODO_HEADING_RE.test(input);
+}
+
+function normalizeExistingTodoMarkdown(input: string): string {
+  const tasks = extractExistingTasks(input);
+  if (tasks.length === 0) {
+    throw new TodoGenerationError("No task headings found to normalize.");
+  }
+
+  const globalInstructions = extractGlobalInstructions(input);
+  const progress = tasks.map((task, idx) => `- [ ] TODO ${idx + 1} — ${task.title}`).join("\n");
+  const sections = tasks.map((task, idx) => normalizeTaskSection({ ...task, taskId: String(idx + 1) })).join("\n\n");
+
+  const globalBlock = globalInstructions ? `\n\n${globalInstructions}` : "";
+  return `# Pi Long Task TODO${globalBlock}\n\n## Progress\n\n${progress}\n\n---\n\n${sections}\n`;
+}
+
+function extractExistingTasks(input: string): ExistingTask[] {
+  TODO_HEADING_RE.lastIndex = 0;
+  const matches = [...input.matchAll(TODO_HEADING_RE)];
+  return matches.map((match, idx) => {
+    const bodyStart = (match.index ?? 0) + match[0].length;
+    const bodyEnd = idx + 1 < matches.length ? (matches[idx + 1].index ?? input.length) : input.length;
+    return {
+      taskId: match[1],
+      title: cleanTitle(match[2]),
+      body: input.slice(bodyStart, bodyEnd).trim(),
+    };
+  });
+}
+
+function extractGlobalInstructions(input: string): string {
+  const lines = input.replace(/\r\n?/g, "\n").split("\n");
+  const selected: string[] = [];
+
+  for (const line of lines) {
+    if (TODO_HEADING_LINE_RE.test(line.trim()) || /^##\s+Progress\s*$/i.test(line.trim())) {
+      break;
+    }
+    if (/^#\s+Pi Long Task TODO\s*$/i.test(line.trim())) {
+      continue;
+    }
+    selected.push(line);
+  }
+
+  return selected.join("\n").trim();
+}
+
+function normalizeTaskSection(task: ExistingTask): string {
+  const body = task.body.trim();
+  const blocks: string[] = [];
+  if (body) {
+    blocks.push(body);
+  }
+
+  const sectionProbe = `## TODO ${task.taskId} — ${task.title}\n\n${body}`;
+  if (!/\*\*Goal:\*\*/.test(sectionProbe)) {
+    blocks.push(`**Goal:** ${goalForTitle(task.title)}`);
+  }
+  if (!/\*\*Status:\*\*/.test(sectionProbe)) {
+    blocks.push(`**Status:**\n- [ ] Complete ${lowercaseFirst(task.title)}`);
+  } else if (!/^\s*-\s+\[[ xX]\]\s+/m.test(body)) {
+    blocks.push(`- [ ] Complete ${lowercaseFirst(task.title)}`);
+  }
+  if (!/\*\*Verify:\*\*/.test(sectionProbe) && !/verification|verify|checks?/i.test(sectionProbe)) {
+    blocks.push("**Verify:**\n- Run focused checks relevant to this task.");
+  }
+  if (!/\*\*Done when:\*\*/.test(sectionProbe)) {
+    blocks.push("**Done when:**\n- The task is implemented and verified.");
+  }
+
+  return `## TODO ${task.taskId} — ${task.title}\n\n${blocks.join("\n\n")}`.trimEnd();
+}
+
+function simpleListItems(input: string): string[] {
+  const lines = input.replace(/\r\n?/g, "\n").split("\n");
+  const nonBlank = lines.map((line) => line.trim()).filter(Boolean);
+  if (nonBlank.length < 2) {
+    return [];
+  }
+
+  const items: string[] = [];
+
+  for (const line of nonBlank) {
+    const bullet = BULLET_ITEM_RE.exec(line);
+    if (bullet) {
+      items.push(stripCheckboxMarker(bullet[1]));
+      continue;
+    }
+
+    const numbered = NUMBERED_ITEM_RE.exec(line);
+    if (numbered) {
+      items.push(stripCheckboxMarker(numbered[1]));
+      continue;
+    }
+
+    return [];
+  }
+
+  return items.map(cleanTitle).filter(Boolean);
+}
+
+function stripCheckboxMarker(value: string): string {
+  return value.replace(/^\[[ xX]\]\s+/, "");
+}
+
+function cleanTitle(value: string): string {
+  return value
+    .replace(/\s+/g, " ")
+    .trim()
+    .replace(/[.。]\s*$/, "");
+}
+
+function goalForTitle(title: string): string {
+  return `Complete ${lowercaseFirst(title)}.`;
+}
+
+function lowercaseFirst(value: string): string {
+  if (!value) {
+    return value;
+  }
+  return `${value[0].toLocaleLowerCase()}${value.slice(1)}`;
+}
+
+function progressLineRegex(taskId: string, title: string): RegExp {
+  return new RegExp(`^\\s*-\\s+\\[ \\]\\s+TODO\\s+${escapeRegExp(taskId)}\\s+[—-]\\s+${escapeRegExp(title)}\\s*$`, "m");
+}
+
+function escapeRegExp(value: string): string {
+  return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+
+function fencedMarkdownBlocks(text: string): string[] {
+  FENCE_RE.lastIndex = 0;
+  return [...text.matchAll(FENCE_RE)].map((match) => match[1]);
+}
+
+function ensureTrailingNewline(value: string): string {
+  return value.endsWith("\n") ? value : `${value}\n`;
+}

package/src/todo_parser.ts

@@ -0,0 +1,229 @@
+export interface Task {
+  taskId: string;
+  title: string;
+  section: string;
+  startLine: number;
+  endLine: number;
+  done: boolean;
+  progressDone?: boolean;
+  statusCheckboxes: boolean[];
+}
+
+export class TodoParseError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "TodoParseError";
+  }
+}
+
+const TASK_HEADING_RE = /^##\s+TODO\s+(\d+)\s+[—-]\s+(.+?)\s*$/;
+const CHECKBOX_RE = /^(\s*-\s+\[)([ xX])(\].*)$/;
+const GLOBAL_PROGRESS_HEADING_RE = /^##\s+Progress\s*$/i;
+
+function progressRegexForTask(taskId: string): RegExp {
+  return new RegExp(`^(\\s*-\\s+\\[)([ xX])(\\]\\s+TODO\\s+${escapeRegExp(taskId)}\\b.*)$`);
+}
+
+function escapeRegExp(value: string): string {
+  return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+
+function splitLinesKeepEnds(text: string): string[] {
+  return text.match(/[^\r\n]*(?:\r\n|\n|\r)|[^\r\n]+/g) ?? [];
+}
+
+function splitLines(text: string): string[] {
+  return splitLinesKeepEnds(text).map((line) => line.replace(/[\r\n]+$/g, ""));
+}
+
+function stripLineBreaks(line: string): string {
+  return line.replace(/[\r\n]+$/g, "");
+}
+
+interface TaskHeading {
+  startIdx: number;
+  taskId: string;
+  title: string;
+}
+
+function parseTaskHeadings(lines: string[]): TaskHeading[] {
+  const headings: TaskHeading[] = [];
+
+  lines.forEach((line, idx) => {
+    const match = TASK_HEADING_RE.exec(stripLineBreaks(line));
+    if (!match) {
+      return;
+    }
+
+    headings.push({
+      startIdx: idx,
+      taskId: match[1],
+      title: match[2].trim(),
+    });
+  });
+
+  return headings;
+}
+
+function findProgressDone(lines: string[], taskId: string): boolean | undefined {
+  const regex = progressRegexForTask(taskId);
+
+  for (const line of lines) {
+    const match = regex.exec(stripLineBreaks(line));
+    if (match) {
+      return match[2].toLowerCase() === "x";
+    }
+  }
+
+  return undefined;
+}
+
+function findStatusCheckboxes(lines: string[], startIdx: number, endIdx: number): boolean[] {
+  let inStatus = false;
+  let seenCheckbox = false;
+  const checkboxes: boolean[] = [];
+
+  for (let idx = startIdx; idx < endIdx; idx += 1) {
+    const stripped = lines[idx].trim();
+    if (stripped === "**Status:**") {
+      inStatus = true;
+      continue;
+    }
+
+    if (!inStatus) {
+      continue;
+    }
+
+    const checkbox = CHECKBOX_RE.exec(stripLineBreaks(lines[idx]));
+    if (checkbox) {
+      seenCheckbox = true;
+      checkboxes.push(checkbox[2].toLowerCase() === "x");
+      continue;
+    }
+
+    if (stripped === "") {
+      continue;
+    }
+
+    if (seenCheckbox) {
+      break;
+    }
+  }
+
+  return checkboxes;
+}
+
+function markStatusBlockDone(lines: string[], startIdx: number, endIdx: number): void {
+  let inStatus = false;
+  let seenCheckbox = false;
+
+  for (let idx = startIdx; idx < endIdx; idx += 1) {
+    const stripped = lines[idx].trim();
+    if (stripped === "**Status:**") {
+      inStatus = true;
+      continue;
+    }
+
+    if (!inStatus) {
+      continue;
+    }
+
+    const raw = stripLineBreaks(lines[idx]);
+    const newline = lines[idx].endsWith("\n") ? "\n" : "";
+    const checkbox = CHECKBOX_RE.exec(raw);
+    if (checkbox) {
+      seenCheckbox = true;
+      if (checkbox[2].toLowerCase() !== "x") {
+        lines[idx] = `${checkbox[1]}x${checkbox[3]}${newline}`;
+      }
+      continue;
+    }
+
+    if (stripped === "") {
+      continue;
+    }
+
+    if (seenCheckbox) {
+      break;
+    }
+  }
+}
+
+export function parseTasks(markdown: string): Task[] {
+  const lines = splitLinesKeepEnds(markdown);
+  const headings = parseTaskHeadings(lines);
+
+  if (headings.length === 0) {
+    throw new TodoParseError("No task sections found. Expected headings like `## TODO 1 — Task title`.");
+  }
+
+  return headings.map((heading, pos) => {
+    const endIdx = pos + 1 < headings.length ? headings[pos + 1].startIdx : lines.length;
+    const section = `${lines.slice(heading.startIdx, endIdx).join("").trimEnd()}\n`;
+    const progressDone = findProgressDone(lines, heading.taskId);
+    const statusCheckboxes = findStatusCheckboxes(lines, heading.startIdx, endIdx);
+    const done = progressDone ?? (statusCheckboxes.length > 0 ? statusCheckboxes.every(Boolean) : false);
+
+    const task: Task = {
+      taskId: heading.taskId,
+      title: heading.title,
+      section,
+      startLine: heading.startIdx + 1,
+      endLine: endIdx,
+      done,
+      statusCheckboxes,
+    };
+    if (progressDone !== undefined) {
+      task.progressDone = progressDone;
+    }
+    return task;
+  });
+}
+
+export function incompleteTasks(markdown: string): Task[] {
+  return parseTasks(markdown).filter((task) => !task.done);
+}
+
+export function markTaskDone(markdown: string, taskId: string): string {
+  const lines = splitLinesKeepEnds(markdown);
+  const progressRegex = progressRegexForTask(taskId);
+
+  lines.forEach((line, idx) => {
+    const raw = stripLineBreaks(line);
+    const newline = line.endsWith("\n") ? "\n" : "";
+    const match = progressRegex.exec(raw);
+    if (match && match[2].toLowerCase() !== "x") {
+      lines[idx] = `${match[1]}x${match[3]}${newline}`;
+    }
+  });
+
+  const headings = parseTaskHeadings(lines);
+  const headingPos = headings.findIndex((heading) => heading.taskId === taskId);
+  if (headingPos >= 0) {
+    const endIdx = headingPos + 1 < headings.length ? headings[headingPos + 1].startIdx : lines.length;
+    markStatusBlockDone(lines, headings[headingPos].startIdx, endIdx);
+  }
+
+  return lines.join("");
+}
+
+export function todoGlobalInstructions(markdown: string, limit = 6000): string {
+  const selected: string[] = [];
+
+  for (const line of splitLines(markdown)) {
+    const stripped = line.trim();
+    if (GLOBAL_PROGRESS_HEADING_RE.test(stripped)) {
+      break;
+    }
+    if (TASK_HEADING_RE.test(stripped)) {
+      break;
+    }
+    selected.push(line);
+  }
+
+  let text = selected.join("\n").trim();
+  if (text.length > limit) {
+    text = `${text.slice(0, limit).trimEnd()}\n\n[truncated by Pi Long Task]`;
+  }
+  return text;
+}

package/src/types.ts

@@ -0,0 +1,60 @@
+import type { Static } from "typebox";
+import { Type } from "typebox";
+
+import type { SessionOutcome } from "./worker_session.ts";
+
+export const PiLongTaskParams = Type.Object(
+  {
+    inputText: Type.String({ description: "TODO file content or long-task instructions to process." }),
+    commit: Type.Boolean({ description: "Whether Pi Long Task may commit completed worker changes." }),
+  },
+  { additionalProperties: false },
+);
+
+export type PiLongTaskInput = Static<typeof PiLongTaskParams>;
+
+export type CoordinatorStatus = "done" | "partial" | "blocked" | "failed";
+
+export interface CoordinatorCommitSummary {
+  taskId: string;
+  hash?: string;
+  error?: string;
+}
+
+export interface CoordinatorRemainingTask {
+  taskId: string;
+  title: string;
+  status: string;
+}
+
+export interface PiLongTaskResult {
+  status: CoordinatorStatus;
+  message: string;
+  summary: string;
+  runId: string;
+  runDir: string;
+  todoPath: string;
+  resultPath: string;
+  taskResultPath: string;
+  totalTasks: number;
+  completedTasks: number;
+  failedTasks: number;
+  blockedTasks: number;
+  attemptedTasks: number;
+  remainingTasks: CoordinatorRemainingTask[];
+  outcomes: SessionOutcome[];
+  commits: CoordinatorCommitSummary[];
+  attempts: Array<{
+    taskId: string;
+    title: string;
+    attempt: number;
+    reportedStatus: string;
+    done: boolean;
+    error?: string;
+    commitHash?: string;
+    commitError?: string;
+    commitSkipped?: string;
+  }>;
+  commit: boolean;
+  error?: string;
+}