@cephalization/math 0.2.0

package/src/prune.test.ts

@@ -0,0 +1,174 @@
+import { test, expect, beforeEach, afterEach } from "bun:test";
+import { findArtifacts, deleteArtifacts, confirmPrune } from "./prune";
+import { mkdirSync, rmSync, existsSync } from "node:fs";
+import { join } from "node:path";
+
+const TEST_DIR = join(import.meta.dir, ".test-prune");
+
+beforeEach(() => {
+  mkdirSync(TEST_DIR, { recursive: true });
+});
+
+afterEach(() => {
+  rmSync(TEST_DIR, { recursive: true, force: true });
+});
+
+test("findArtifacts returns empty array for empty directory", () => {
+  const result = findArtifacts(TEST_DIR);
+  expect(result).toEqual([]);
+});
+
+test("findArtifacts finds backup directories with basic pattern", () => {
+  mkdirSync(join(TEST_DIR, "todo-1-15-2025"));
+  mkdirSync(join(TEST_DIR, "todo-12-31-2024"));
+
+  const result = findArtifacts(TEST_DIR);
+
+  expect(result).toHaveLength(2);
+  expect(result).toContain(join(TEST_DIR, "todo-1-15-2025"));
+  expect(result).toContain(join(TEST_DIR, "todo-12-31-2024"));
+});
+
+test("findArtifacts finds backup directories with counter suffix", () => {
+  mkdirSync(join(TEST_DIR, "todo-1-15-2025"));
+  mkdirSync(join(TEST_DIR, "todo-1-15-2025-1"));
+  mkdirSync(join(TEST_DIR, "todo-1-15-2025-42"));
+
+  const result = findArtifacts(TEST_DIR);
+
+  expect(result).toHaveLength(3);
+  expect(result).toContain(join(TEST_DIR, "todo-1-15-2025"));
+  expect(result).toContain(join(TEST_DIR, "todo-1-15-2025-1"));
+  expect(result).toContain(join(TEST_DIR, "todo-1-15-2025-42"));
+});
+
+test("findArtifacts ignores non-matching directories", () => {
+  mkdirSync(join(TEST_DIR, "todo-1-15-2025"));
+  mkdirSync(join(TEST_DIR, "todo")); // Not a backup
+  mkdirSync(join(TEST_DIR, "node_modules")); // Not a backup
+  mkdirSync(join(TEST_DIR, "todo-invalid")); // Invalid pattern
+
+  const result = findArtifacts(TEST_DIR);
+
+  expect(result).toHaveLength(1);
+  expect(result).toContain(join(TEST_DIR, "todo-1-15-2025"));
+});
+
+test("findArtifacts ignores files matching pattern", () => {
+  mkdirSync(join(TEST_DIR, "todo-1-15-2025"));
+  // Create a file that matches the pattern (should be ignored)
+  Bun.write(join(TEST_DIR, "todo-2-20-2025"), "not a directory");
+
+  const result = findArtifacts(TEST_DIR);
+
+  expect(result).toHaveLength(1);
+  expect(result).toContain(join(TEST_DIR, "todo-1-15-2025"));
+});
+
+test("findArtifacts returns empty array for non-existent directory", () => {
+  const result = findArtifacts(join(TEST_DIR, "does-not-exist"));
+  expect(result).toEqual([]);
+});
+
+test("findArtifacts returns absolute paths", () => {
+  mkdirSync(join(TEST_DIR, "todo-1-15-2025"));
+
+  const result = findArtifacts(TEST_DIR);
+
+  expect(result).toHaveLength(1);
+  expect(result[0]).toMatch(/^\//); // Starts with / (absolute path)
+});
+
+// deleteArtifacts tests
+
+test("deleteArtifacts deletes directories successfully", () => {
+  const dir1 = join(TEST_DIR, "todo-1-15-2025");
+  const dir2 = join(TEST_DIR, "todo-2-20-2025");
+  mkdirSync(dir1);
+  mkdirSync(dir2);
+
+  const result = deleteArtifacts([dir1, dir2]);
+
+  expect(result.deleted).toHaveLength(2);
+  expect(result.deleted).toContain(dir1);
+  expect(result.deleted).toContain(dir2);
+  expect(result.failed).toHaveLength(0);
+  expect(existsSync(dir1)).toBe(false);
+  expect(existsSync(dir2)).toBe(false);
+});
+
+test("deleteArtifacts deletes directories with contents", () => {
+  const dir = join(TEST_DIR, "todo-1-15-2025");
+  mkdirSync(dir);
+  Bun.write(join(dir, "file.txt"), "content");
+  mkdirSync(join(dir, "subdir"));
+  Bun.write(join(dir, "subdir", "nested.txt"), "nested content");
+
+  const result = deleteArtifacts([dir]);
+
+  expect(result.deleted).toHaveLength(1);
+  expect(result.failed).toHaveLength(0);
+  expect(existsSync(dir)).toBe(false);
+});
+
+test("deleteArtifacts returns empty arrays for empty input", () => {
+  const result = deleteArtifacts([]);
+
+  expect(result.deleted).toHaveLength(0);
+  expect(result.failed).toHaveLength(0);
+});
+
+test("deleteArtifacts handles non-existent paths gracefully", () => {
+  const nonExistent = join(TEST_DIR, "does-not-exist");
+
+  const result = deleteArtifacts([nonExistent]);
+
+  // rmSync with force: true doesn't throw for non-existent paths
+  expect(result.deleted).toHaveLength(1);
+  expect(result.failed).toHaveLength(0);
+});
+
+test("deleteArtifacts continues after a failure", () => {
+  const dir1 = join(TEST_DIR, "todo-1-15-2025");
+  const dir2 = join(TEST_DIR, "todo-2-20-2025");
+  mkdirSync(dir1);
+  mkdirSync(dir2);
+
+  // Delete first one manually to prove second still gets processed
+  rmSync(dir1, { recursive: true });
+
+  const result = deleteArtifacts([dir1, dir2]);
+
+  // Both should succeed since rmSync with force:true handles non-existent
+  expect(result.deleted).toHaveLength(2);
+  expect(result.failed).toHaveLength(0);
+  expect(existsSync(dir2)).toBe(false);
+});
+
+// confirmPrune tests
+
+test("confirmPrune returns confirmed: true with force flag", async () => {
+  const paths = ["/some/path/todo-1-15-2025", "/some/path/todo-2-20-2025"];
+
+  const result = await confirmPrune(paths, { force: true });
+
+  expect(result.confirmed).toBe(true);
+  expect(result.paths).toEqual(paths);
+});
+
+test("confirmPrune returns confirmed: true with empty paths", async () => {
+  const result = await confirmPrune([]);
+
+  expect(result.confirmed).toBe(true);
+  expect(result.paths).toEqual([]);
+});
+
+test("confirmPrune returns paths even with force flag", async () => {
+  const paths = ["/a/todo-1-1-2025", "/b/todo-2-2-2025"];
+
+  const result = await confirmPrune(paths, { force: true });
+
+  expect(result.paths).toHaveLength(2);
+  expect(result.paths).toContain("/a/todo-1-1-2025");
+  expect(result.paths).toContain("/b/todo-2-2-2025");
+});

package/src/prune.ts

@@ -0,0 +1,146 @@
+import { readdirSync, statSync, rmSync } from "node:fs";
+import { join, basename } from "node:path";
+import { createInterface } from "node:readline/promises";
+
+/**
+ * Pattern for backup directories created by `math iterate`
+ * Matches: todo-{M}-{D}-{Y} or todo-{M}-{D}-{Y}-{N}
+ * Examples: todo-1-15-2025, todo-12-31-2024-1, todo-1-1-2026-42
+ */
+const BACKUP_DIR_PATTERN = /^todo-\d{1,2}-\d{1,2}-\d{4}(-\d+)?$/;
+
+/**
+ * Finds all math artifacts in a directory.
+ *
+ * Artifacts include:
+ * - Backup directories matching pattern todo-{M}-{D}-{Y} or todo-{M}-{D}-{Y}-{N}
+ *
+ * @param directory - The directory to search in (defaults to cwd)
+ * @returns Array of absolute paths to artifacts
+ */
+export function findArtifacts(directory: string = process.cwd()): string[] {
+  const artifacts: string[] = [];
+
+  try {
+    const entries = readdirSync(directory);
+
+    for (const entry of entries) {
+      const fullPath = join(directory, entry);
+
+      // Check if it's a backup directory
+      if (BACKUP_DIR_PATTERN.test(entry)) {
+        try {
+          const stat = statSync(fullPath);
+          if (stat.isDirectory()) {
+            artifacts.push(fullPath);
+          }
+        } catch {
+          // Skip entries we can't stat (permission issues, etc.)
+        }
+      }
+    }
+  } catch {
+    // If we can't read the directory, return empty array
+  }
+
+  return artifacts;
+}
+
+/**
+ * Result of a delete operation
+ */
+export interface DeleteResult {
+  /** Paths that were successfully deleted */
+  deleted: string[];
+  /** Paths that failed to delete with their error messages */
+  failed: { path: string; error: string }[];
+}
+
+/**
+ * Deletes the provided artifact paths.
+ *
+ * Handles errors gracefully - if a path fails to delete (e.g., permission denied),
+ * it continues with the remaining paths and reports the failure.
+ *
+ * @param paths - Array of absolute paths to delete
+ * @returns Summary of deleted paths and any failures
+ */
+export function deleteArtifacts(paths: string[]): DeleteResult {
+  const result: DeleteResult = {
+    deleted: [],
+    failed: [],
+  };
+
+  for (const path of paths) {
+    try {
+      rmSync(path, { recursive: true, force: true });
+      result.deleted.push(path);
+    } catch (err) {
+      const errorMessage =
+        err instanceof Error ? err.message : "Unknown error";
+      result.failed.push({ path, error: errorMessage });
+    }
+  }
+
+  return result;
+}
+
+/**
+ * Result of a confirmation prompt
+ */
+export interface ConfirmationResult {
+  /** Whether the user confirmed the action */
+  confirmed: boolean;
+  /** The paths that were shown to the user */
+  paths: string[];
+}
+
+/**
+ * Shows an interactive confirmation prompt for pruning artifacts.
+ *
+ * Lists all artifacts that will be deleted and asks for user confirmation.
+ * If `force` is true, skips the prompt and returns confirmed: true.
+ *
+ * @param paths - Array of absolute paths to be deleted
+ * @param options - Configuration options
+ * @param options.force - If true, skip confirmation and return confirmed: true
+ * @returns Result indicating whether user confirmed and what paths were shown
+ */
+export async function confirmPrune(
+  paths: string[],
+  options: { force?: boolean } = {}
+): Promise<ConfirmationResult> {
+  // If force flag is set, skip confirmation
+  if (options.force) {
+    return { confirmed: true, paths };
+  }
+
+  // If no paths, nothing to confirm
+  if (paths.length === 0) {
+    return { confirmed: true, paths };
+  }
+
+  // Show what will be deleted
+  console.log("\nThe following artifacts will be deleted:\n");
+  for (const path of paths) {
+    console.log(`  - ${basename(path)}/`);
+  }
+  console.log();
+
+  // Ask for confirmation
+  const rl = createInterface({
+    input: process.stdin,
+    output: process.stdout,
+  });
+
+  try {
+    const answer = await rl.question("Delete these artifacts? (y/N) ");
+    rl.close();
+
+    const confirmed = answer.toLowerCase() === "y";
+    return { confirmed, paths };
+  } catch {
+    rl.close();
+    return { confirmed: false, paths };
+  }
+}

package/src/tasks.ts

@@ -0,0 +1,204 @@
+import { join } from "node:path";
+import { existsSync } from "node:fs";
+
+export interface Task {
+  id: string;
+  content: string;
+  status: "pending" | "in_progress" | "complete";
+  dependencies: string[];
+}
+
+export interface TaskCounts {
+  pending: number;
+  in_progress: number;
+  complete: number;
+  total: number;
+}
+
+/**
+ * Parse TASKS.md file and extract all tasks
+ *
+ * Expected format:
+ * ### task-id
+ * - content: Description of the task
+ * - status: pending | in_progress | complete
+ * - dependencies: task-1, task-2
+ */
+export function parseTasks(content: string): Task[] {
+  const tasks: Task[] = [];
+  const lines = content.split("\n");
+
+  let currentTask: Partial<Task> | null = null;
+
+  for (const line of lines) {
+    // New task starts with ### task-id
+    const taskMatch = line.match(/^###\s+(.+)$/);
+    if (taskMatch && taskMatch[1]) {
+      // Save previous task if exists
+      if (currentTask?.id) {
+        tasks.push({
+          id: currentTask.id,
+          content: currentTask.content || "",
+          status: currentTask.status || "pending",
+          dependencies: currentTask.dependencies || [],
+        });
+      }
+      currentTask = { id: taskMatch[1].trim() };
+      continue;
+    }
+
+    if (!currentTask) continue;
+
+    // Parse content line
+    const contentMatch = line.match(/^-\s+content:\s*(.+)$/);
+    if (contentMatch && contentMatch[1]) {
+      currentTask.content = contentMatch[1].trim();
+      continue;
+    }
+
+    // Parse status line
+    const statusMatch = line.match(
+      /^-\s+status:\s*(pending|in_progress|complete)$/
+    );
+    if (statusMatch && statusMatch[1]) {
+      currentTask.status = statusMatch[1] as Task["status"];
+      continue;
+    }
+
+    // Parse dependencies line
+    const depsMatch = line.match(/^-\s+dependencies:\s*(.*)$/);
+    if (depsMatch && depsMatch[1]) {
+      const deps = depsMatch[1].trim();
+      if (deps && deps.toLowerCase() !== "none") {
+        currentTask.dependencies = deps
+          .split(",")
+          .map((d) => d.trim())
+          .filter(Boolean);
+      } else {
+        currentTask.dependencies = [];
+      }
+      continue;
+    }
+  }
+
+  // Don't forget the last task
+  if (currentTask?.id) {
+    tasks.push({
+      id: currentTask.id,
+      content: currentTask.content || "",
+      status: currentTask.status || "pending",
+      dependencies: currentTask.dependencies || [],
+    });
+  }
+
+  return tasks;
+}
+
+/**
+ * Count tasks by status
+ */
+export function countTasks(tasks: Task[]): TaskCounts {
+  const counts: TaskCounts = {
+    pending: 0,
+    in_progress: 0,
+    complete: 0,
+    total: tasks.length,
+  };
+
+  for (const task of tasks) {
+    counts[task.status]++;
+  }
+
+  return counts;
+}
+
+/**
+ * Find the next task to work on:
+ * - Status must be "pending"
+ * - All dependencies must be "complete"
+ */
+export function findNextTask(tasks: Task[]): Task | null {
+  const completedIds = new Set(
+    tasks.filter((t) => t.status === "complete").map((t) => t.id)
+  );
+
+  for (const task of tasks) {
+    if (task.status !== "pending") continue;
+
+    // Check if all dependencies are complete
+    const depsComplete = task.dependencies.every((dep) =>
+      completedIds.has(dep)
+    );
+    if (depsComplete) {
+      return task;
+    }
+  }
+
+  return null;
+}
+
+/**
+ * Update a task's status in the TASKS.md content
+ */
+export function updateTaskStatus(
+  content: string,
+  taskId: string,
+  newStatus: Task["status"]
+): string {
+  const lines = content.split("\n");
+  const result: string[] = [];
+  let inTargetTask = false;
+
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i] ?? "";
+
+    // Check if we're entering a task section
+    const taskMatch = line.match(/^###\s+(.+)$/);
+    if (taskMatch && taskMatch[1]) {
+      inTargetTask = taskMatch[1].trim() === taskId;
+    }
+
+    // If we're in the target task and this is a status line, replace it
+    if (
+      inTargetTask &&
+      line.match(/^-\s+status:\s*(pending|in_progress|complete)$/)
+    ) {
+      result.push(`- status: ${newStatus}`);
+    } else {
+      result.push(line);
+    }
+  }
+
+  return result.join("\n");
+}
+
+/**
+ * Read and parse tasks from the todo directory
+ */
+export async function readTasks(
+  todoDir?: string
+): Promise<{ tasks: Task[]; content: string }> {
+  const dir = todoDir || join(process.cwd(), "todo");
+  const tasksPath = join(dir, "TASKS.md");
+
+  if (!existsSync(tasksPath)) {
+    throw new Error(`TASKS.md not found at ${tasksPath}`);
+  }
+
+  const content = await Bun.file(tasksPath).text();
+  const tasks = parseTasks(content);
+
+  return { tasks, content };
+}
+
+/**
+ * Write updated content to TASKS.md
+ */
+export async function writeTasks(
+  content: string,
+  todoDir?: string
+): Promise<void> {
+  const dir = todoDir || join(process.cwd(), "todo");
+  const tasksPath = join(dir, "TASKS.md");
+  await Bun.write(tasksPath, content);
+}

package/src/templates.ts

@@ -0,0 +1,172 @@
+export const PROMPT_TEMPLATE = `# Agent Task Prompt
+
+You are a coding agent implementing tasks one at a time.
+
+## Your Mission
+
+Implement ONE task from TASKS.md, test it, commit it, log your learnings, then EXIT.
+
+## The Loop
+
+1. **Read TASKS.md** - Find the first task with \`status: pending\` where ALL dependencies have \`status: complete\`
+2. **Mark in_progress** - Update the task's status to \`in_progress\` in TASKS.md
+3. **Implement** - Write the code following the project's patterns
+4. **Write tests** - For behavioral code changes, create unit tests in the appropriate directory. Skip for documentation-only tasks.
+5. **Run tests** - Execute tests from the package directory (ensures existing tests still pass)
+6. **Fix failures** - If tests fail, debug and fix. DO NOT PROCEED WITH FAILING TESTS.
+7. **Mark complete** - Update the task's status to \`complete\` in TASKS.md
+8. **Log learnings** - Append insights to LEARNINGS.md
+9. **Commit** - Stage and commit: \`git add -A && git commit -m "feat: <task-id> - <description>"\`
+10. **EXIT** - Stop. The loop will reinvoke you for the next task.
+
+---
+
+## Signs
+
+READ THESE CAREFULLY. They are guardrails that prevent common mistakes.
+
+---
+
+### SIGN: One Task Only
+
+- You implement **EXACTLY ONE** task per invocation
+- After your commit, you **STOP**
+- Do NOT continue to the next task
+- Do NOT "while you're here" other improvements
+- The loop will reinvoke you for the next task
+
+---
+
+### SIGN: Dependencies Matter
+
+Before starting a task, verify ALL its dependencies have \`status: complete\`.
+
+\`\`\`
+❌ WRONG: Start task with pending dependencies
+✅ RIGHT: Check deps, proceed only if all complete
+✅ RIGHT: If deps not complete, EXIT with clear error message
+\`\`\`
+
+Do NOT skip ahead. Do NOT work on tasks out of order.
+
+---
+
+### SIGN: Learnings are Required
+
+Before exiting, append to \`LEARNINGS.md\`:
+
+\`\`\`markdown
+## <task-id>
+
+- Key insight or decision made
+- Gotcha or pitfall discovered
+- Pattern that worked well
+- Anything the next agent should know
+\`\`\`
+
+Be specific. Be helpful. Future agents will thank you.
+
+---
+
+### SIGN: Commit Format
+
+One commit per task. Format:
+
+\`\`\`
+feat: <task-id> - <short description>
+\`\`\`
+
+Only commit AFTER tests pass.
+
+---
+
+### SIGN: Don't Over-Engineer
+
+- Implement what the task specifies, nothing more
+- Don't add features "while you're here"
+- Don't refactor unrelated code
+- Don't add abstractions for "future flexibility"
+- Don't make perfect mocks in tests - use simple stubs instead
+- Don't use complex test setups - keep tests simple and focused
+- YAGNI: You Ain't Gonna Need It
+
+---
+
+## Quick Reference
+
+<!-- This table should be customized for your project's tooling -->
+<!-- Run 'math plan' to auto-detect and populate these commands -->
+
+| Action | Command |
+|--------|---------|
+| Run tests | \`<your-test-command>\` |
+| Build | \`<your-build-command>\` |
+| Lint | \`<your-lint-command>\` |
+| Stage all | \`git add -A\` |
+| Commit | \`git commit -m "feat: ..."\` |
+
+---
+
+## Remember
+
+You do one thing. You do it well. You learn. You exit.
+`;
+
+export const TASKS_TEMPLATE = `# Project Tasks
+
+Task tracker for multi-agent development.
+Each agent picks the next pending task, implements it, and marks it complete.
+
+## How to Use
+
+1. Find the first task with \`status: pending\` where ALL dependencies have \`status: complete\`
+2. Change that task's status to \`in_progress\`
+3. Implement the task
+4. Write and run tests
+5. Change the task's status to \`complete\`
+6. Append learnings to LEARNINGS.md
+7. Commit with message: \`feat: <task-id> - <description>\`
+8. EXIT
+
+## Task Statuses
+
+- \`pending\` - Not started
+- \`in_progress\` - Currently being worked on
+- \`complete\` - Done and committed
+
+---
+
+## Phase 1: Setup
+
+### example-task
+
+- content: Replace this with your first task description
+- status: pending
+- dependencies: none
+
+### another-task
+
+- content: This task depends on example-task
+- status: pending
+- dependencies: example-task
+`;
+
+export const LEARNINGS_TEMPLATE = `# Project Learnings Log
+
+This file is appended by each agent after completing a task.
+Key insights, gotchas, and patterns discovered during implementation.
+
+Use this knowledge to avoid repeating mistakes and build on what works.
+
+---
+
+<!-- Agents: Append your learnings below this line -->
+<!-- Format:
+## <task-id>
+
+- Key insight or decision made
+- Gotcha or pitfall discovered
+- Pattern that worked well
+- Anything the next agent should know
+-->
+`;