@cephalization/math 0.3.2 → 0.4.0

package/src/migration.ts

@@ -0,0 +1,122 @@
+import { createInterface } from "node:readline/promises";
+import { existsSync } from "node:fs";
+import { mkdir, rename } from "node:fs/promises";
+import { join } from "node:path";
+import { getMathDir, getTodoDir } from "./paths";
+
+const colors = {
+  reset: "\x1b[0m",
+  bold: "\x1b[1m",
+  green: "\x1b[32m",
+  yellow: "\x1b[33m",
+  cyan: "\x1b[36m",
+};
+
+/**
+ * Check if the legacy todo/ directory exists and contains the expected files.
+ */
+export function hasLegacyTodoDir(): boolean {
+  const legacyDir = join(process.cwd(), "todo");
+
+  if (!existsSync(legacyDir)) {
+    return false;
+  }
+
+  // Check for at least one of the expected files
+  const expectedFiles = ["PROMPT.md", "TASKS.md", "LEARNINGS.md"];
+  return expectedFiles.some((file) => existsSync(join(legacyDir, file)));
+}
+
+/**
+ * Check if we've already migrated to the new .math/todo structure.
+ */
+export function hasNewTodoDir(): boolean {
+  return existsSync(getTodoDir());
+}
+
+/**
+ * Prompt the user to confirm migration.
+ * Returns true if user confirms, false otherwise.
+ */
+async function promptForMigration(): Promise<boolean> {
+  const rl = createInterface({
+    input: process.stdin,
+    output: process.stdout,
+  });
+
+  try {
+    console.log();
+    console.log(
+      `${colors.yellow}${colors.bold}Migration Required${colors.reset}`
+    );
+    console.log(
+      `Found legacy ${colors.cyan}todo/${colors.reset} directory structure.`
+    );
+    console.log(
+      `This will be migrated to ${colors.cyan}.math/todo/${colors.reset}`
+    );
+    console.log();
+
+    const answer = await rl.question(
+      `${colors.cyan}Migrate now?${colors.reset} (Y/n) `
+    );
+    rl.close();
+    return answer.toLowerCase() !== "n";
+  } catch {
+    rl.close();
+    return false;
+  }
+}
+
+/**
+ * Perform the migration from todo/ to .math/todo/.
+ */
+async function performMigration(): Promise<void> {
+  const legacyDir = join(process.cwd(), "todo");
+  const mathDir = getMathDir();
+  const newTodoDir = getTodoDir();
+
+  // Create .math directory if it doesn't exist
+  if (!existsSync(mathDir)) {
+    await mkdir(mathDir, { recursive: true });
+  }
+
+  // Move todo/ to .math/todo/
+  await rename(legacyDir, newTodoDir);
+
+  console.log(
+    `${colors.green}✓${colors.reset} Migrated ${colors.cyan}todo/${colors.reset} to ${colors.cyan}.math/todo/${colors.reset}`
+  );
+  console.log();
+}
+
+/**
+ * Check if migration is needed and perform it if the user confirms.
+ * This function is idempotent - safe to call multiple times.
+ *
+ * Returns true if migration was performed or not needed, false if user declined.
+ */
+export async function migrateIfNeeded(): Promise<boolean> {
+  // Already migrated - nothing to do
+  if (hasNewTodoDir()) {
+    return true;
+  }
+
+  // No legacy directory - nothing to migrate
+  if (!hasLegacyTodoDir()) {
+    return true;
+  }
+
+  // Legacy directory exists, prompt for migration
+  const shouldMigrate = await promptForMigration();
+
+  if (!shouldMigrate) {
+    console.log(
+      `${colors.yellow}Migration skipped.${colors.reset} Some commands may not work correctly.`
+    );
+    return false;
+  }
+
+  await performMigration();
+  return true;
+}

package/src/paths.test.ts

@@ -0,0 +1,36 @@
+import { test, expect } from "bun:test";
+import { getMathDir, getTodoDir, getBackupsDir } from "./paths";
+import { join } from "node:path";
+
+test("getMathDir returns .math in current directory", () => {
+  const result = getMathDir();
+  const expected = join(process.cwd(), ".math");
+  expect(result).toBe(expected);
+});
+
+test("getTodoDir returns .math/todo in current directory", () => {
+  const result = getTodoDir();
+  const expected = join(process.cwd(), ".math", "todo");
+  expect(result).toBe(expected);
+});
+
+test("getBackupsDir returns .math/backups in current directory", () => {
+  const result = getBackupsDir();
+  const expected = join(process.cwd(), ".math", "backups");
+  expect(result).toBe(expected);
+});
+
+test("all paths are absolute", () => {
+  expect(getMathDir()).toMatch(/^\//);
+  expect(getTodoDir()).toMatch(/^\//);
+  expect(getBackupsDir()).toMatch(/^\//);
+});
+
+test("paths have correct hierarchy", () => {
+  const mathDir = getMathDir();
+  const todoDir = getTodoDir();
+  const backupsDir = getBackupsDir();
+
+  expect(todoDir.startsWith(mathDir)).toBe(true);
+  expect(backupsDir.startsWith(mathDir)).toBe(true);
+});

package/src/paths.ts

@@ -0,0 +1,22 @@
+import { join } from "node:path";
+
+/**
+ * Get the root math directory path (.math)
+ */
+export function getMathDir(): string {
+  return join(process.cwd(), ".math");
+}
+
+/**
+ * Get the todo directory path (.math/todo)
+ */
+export function getTodoDir(): string {
+  return join(process.cwd(), ".math", "todo");
+}
+
+/**
+ * Get the backups directory path (.math/backups)
+ */
+export function getBackupsDir(): string {
+  return join(process.cwd(), ".math", "backups");
+}

package/src/plan.ts

@@ -226,14 +226,14 @@ Read the attached files and update TASKS.md with a well-structured task list for
       console.log();
       console.log(`${colors.bold}Next steps:${colors.reset}`);
       console.log(
-        `  1. Review ${colors.cyan}todo/TASKS.md${colors.reset} to verify the plan`
+        `  1. Review ${colors.cyan}.math/todo/TASKS.md${colors.reset} to verify the plan`
       );
       console.log(
         `  2. Run ${colors.cyan}math run${colors.reset} to start executing tasks`
       );
     } else {
       console.log(
-        `${colors.yellow}Planning completed with warnings. Check todo/TASKS.md${colors.reset}`
+        `${colors.yellow}Planning completed with warnings. Check .math/todo/TASKS.md${colors.reset}`
       );
     }
   } catch (error) {

package/src/prune.test.ts

@@ -4,76 +4,87 @@ import { mkdirSync, rmSync, existsSync } from "node:fs";
 import { join } from "node:path";
 
 const TEST_DIR = join(import.meta.dir, ".test-prune");
+const BACKUPS_DIR = join(TEST_DIR, ".math", "backups");
+
+// Store original cwd to restore after tests
+let originalCwd: string;
 
 beforeEach(() => {
-  mkdirSync(TEST_DIR, { recursive: true });
+  originalCwd = process.cwd();
+  mkdirSync(BACKUPS_DIR, { recursive: true });
+  process.chdir(TEST_DIR);
 });
 
 afterEach(() => {
+  process.chdir(originalCwd);
   rmSync(TEST_DIR, { recursive: true, force: true });
 });
 
-test("findArtifacts returns empty array for empty directory", () => {
-  const result = findArtifacts(TEST_DIR);
+test("findArtifacts returns empty array for empty .math/backups directory", () => {
+  const result = findArtifacts();
   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"));
+test("findArtifacts finds all backup directories in .math/backups", () => {
+  mkdirSync(join(BACKUPS_DIR, "core-infrastructure"));
+  mkdirSync(join(BACKUPS_DIR, "auth-setup"));
 
-  const result = findArtifacts(TEST_DIR);
+  const result = findArtifacts();
 
   expect(result).toHaveLength(2);
-  expect(result).toContain(join(TEST_DIR, "todo-1-15-2025"));
-  expect(result).toContain(join(TEST_DIR, "todo-12-31-2024"));
+  expect(result).toContain(join(BACKUPS_DIR, "core-infrastructure"));
+  expect(result).toContain(join(BACKUPS_DIR, "auth-setup"));
 });
 
-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"));
+test("findArtifacts finds backup directories with numeric suffixes", () => {
+  mkdirSync(join(BACKUPS_DIR, "core-infrastructure"));
+  mkdirSync(join(BACKUPS_DIR, "core-infrastructure-1"));
+  mkdirSync(join(BACKUPS_DIR, "core-infrastructure-42"));
 
-  const result = findArtifacts(TEST_DIR);
+  const result = findArtifacts();
 
   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"));
+  expect(result).toContain(join(BACKUPS_DIR, "core-infrastructure"));
+  expect(result).toContain(join(BACKUPS_DIR, "core-infrastructure-1"));
+  expect(result).toContain(join(BACKUPS_DIR, "core-infrastructure-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
+test("findArtifacts only returns directories", () => {
+  mkdirSync(join(BACKUPS_DIR, "core-infrastructure"));
+  mkdirSync(join(BACKUPS_DIR, "auth-setup"));
+  // Create a file that should be ignored
+  Bun.write(join(BACKUPS_DIR, "some-file.txt"), "not a directory");
 
-  const result = findArtifacts(TEST_DIR);
+  const result = findArtifacts();
 
-  expect(result).toHaveLength(1);
-  expect(result).toContain(join(TEST_DIR, "todo-1-15-2025"));
+  expect(result).toHaveLength(2);
+  expect(result).toContain(join(BACKUPS_DIR, "core-infrastructure"));
+  expect(result).toContain(join(BACKUPS_DIR, "auth-setup"));
 });
 
-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");
+test("findArtifacts ignores files in .math/backups", () => {
+  mkdirSync(join(BACKUPS_DIR, "core-infrastructure"));
+  // Create a file that should be ignored
+  Bun.write(join(BACKUPS_DIR, "readme.md"), "not a directory");
 
-  const result = findArtifacts(TEST_DIR);
+  const result = findArtifacts();
 
   expect(result).toHaveLength(1);
-  expect(result).toContain(join(TEST_DIR, "todo-1-15-2025"));
+  expect(result).toContain(join(BACKUPS_DIR, "core-infrastructure"));
 });
 
-test("findArtifacts returns empty array for non-existent directory", () => {
-  const result = findArtifacts(join(TEST_DIR, "does-not-exist"));
+test("findArtifacts returns empty array when .math/backups does not exist", () => {
+  // Remove the backups directory
+  rmSync(BACKUPS_DIR, { recursive: true, force: true });
+
+  const result = findArtifacts();
   expect(result).toEqual([]);
 });
 
 test("findArtifacts returns absolute paths", () => {
-  mkdirSync(join(TEST_DIR, "todo-1-15-2025"));
+  mkdirSync(join(BACKUPS_DIR, "core-infrastructure"));
 
-  const result = findArtifacts(TEST_DIR);
+  const result = findArtifacts();
 
   expect(result).toHaveLength(1);
   expect(result[0]).toMatch(/^\//); // Starts with / (absolute path)

package/src/prune.ts

@@ -1,42 +1,33 @@
 import { readdirSync, statSync, rmSync } from "node:fs";
 import { join, basename } from "node:path";
 import { createInterface } from "node:readline/promises";
+import { getBackupsDir } from "./paths.js";
 
 /**
- * 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.
+ * Finds all math artifacts (backup directories) in `.math/backups/`.
  *
- * Artifacts include:
- * - Backup directories matching pattern todo-{M}-{D}-{Y} or todo-{M}-{D}-{Y}-{N}
+ * Scans the `.math/backups/` directory and returns all subdirectories
+ * as artifacts. These are created by `math iterate` with summary-based names.
  *
- * @param directory - The directory to search in (defaults to cwd)
- * @returns Array of absolute paths to artifacts
+ * @returns Array of absolute paths to backup directories
  */
-export function findArtifacts(directory: string = process.cwd()): string[] {
+export function findArtifacts(): string[] {
   const artifacts: string[] = [];
+  const backupsDir = getBackupsDir();
 
   try {
-    const entries = readdirSync(directory);
+    const entries = readdirSync(backupsDir);
 
     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.)
+      const fullPath = join(backupsDir, entry);
+
+      try {
+        const stat = statSync(fullPath);
+        if (stat.isDirectory()) {
+          artifacts.push(fullPath);
         }
+      } catch {
+        // Skip entries we can't stat (permission issues, etc.)
       }
     }
   } catch {

package/src/summary.test.ts

@@ -0,0 +1,97 @@
+import { describe, it, expect } from "bun:test";
+import { generatePlanSummary } from "./summary";
+
+describe("generatePlanSummary", () => {
+  it("should extract summary from phase name", () => {
+    const content = `# Project Tasks
+
+## Phase 1: Core Infrastructure
+
+### add-paths-module
+- content: Create paths module
+- status: pending
+- dependencies: none
+`;
+    expect(generatePlanSummary(content)).toBe("core-infrastructure");
+  });
+
+  it("should truncate phase name to max 5 words", () => {
+    const content = `# Project Tasks
+
+## Phase 1: Very Long Phase Name With Many Words Here
+
+### task-1
+- content: Some task
+- status: pending
+- dependencies: none
+`;
+    expect(generatePlanSummary(content)).toBe("very-long-phase-name-with");
+  });
+
+  it("should fall back to task ID when no phase name", () => {
+    const content = `# Project Tasks
+
+### auth-flow-setup
+- content: Setup auth flow
+- status: pending
+- dependencies: none
+`;
+    expect(generatePlanSummary(content)).toBe("auth-flow-setup");
+  });
+
+  it("should handle task ID with special characters", () => {
+    const content = `# Project Tasks
+
+### add_user_auth!
+- content: Add user auth
+- status: pending
+- dependencies: none
+`;
+    expect(generatePlanSummary(content)).toBe("adduserauth");
+  });
+
+  it("should return 'plan' as ultimate fallback", () => {
+    const content = `# Project Tasks
+
+Just some random content without tasks or phases.
+`;
+    expect(generatePlanSummary(content)).toBe("plan");
+  });
+
+  it("should handle empty content", () => {
+    expect(generatePlanSummary("")).toBe("plan");
+  });
+
+  it("should handle multiple phases and use the first one", () => {
+    const content = `# Project Tasks
+
+## Phase 1: Setup
+
+### task-1
+- content: Task 1
+- status: complete
+- dependencies: none
+
+## Phase 2: Implementation
+
+### task-2
+- content: Task 2
+- status: pending
+- dependencies: task-1
+`;
+    expect(generatePlanSummary(content)).toBe("setup");
+  });
+
+  it("should handle phase name with numbers", () => {
+    const content = `# Project Tasks
+
+## Phase 1: OAuth2 Integration
+
+### oauth2-setup
+- content: Setup OAuth2
+- status: pending
+- dependencies: none
+`;
+    expect(generatePlanSummary(content)).toBe("oauth2-integration");
+  });
+});

package/src/summary.ts

@@ -0,0 +1,92 @@
+/**
+ * Generate a short kebab-case summary from TASKS.md content
+ * Used for naming backup directories
+ */
+
+/**
+ * Extract task IDs from TASKS.md content
+ */
+function extractTaskIds(content: string): string[] {
+  const taskIds: string[] = [];
+  const lines = content.split("\n");
+
+  for (const line of lines) {
+    // Task IDs are defined as ### task-id
+    const taskMatch = line.match(/^###\s+(.+)$/);
+    if (taskMatch && taskMatch[1]) {
+      taskIds.push(taskMatch[1].trim());
+    }
+  }
+
+  return taskIds;
+}
+
+/**
+ * Extract phase names from TASKS.md content
+ */
+function extractPhaseNames(content: string): string[] {
+  const phases: string[] = [];
+  const lines = content.split("\n");
+
+  for (const line of lines) {
+    // Phase names are defined as ## Phase N: Name
+    const phaseMatch = line.match(/^##\s+Phase\s+\d+:\s*(.+)$/);
+    if (phaseMatch && phaseMatch[1]) {
+      phases.push(phaseMatch[1].trim());
+    }
+  }
+
+  return phases;
+}
+
+/**
+ * Convert a string to kebab-case
+ */
+function toKebabCase(str: string): string {
+  return str
+    .toLowerCase()
+    .replace(/[^a-z0-9\s-]/g, "") // Remove special characters
+    .replace(/\s+/g, "-") // Replace spaces with hyphens
+    .replace(/-+/g, "-") // Collapse multiple hyphens
+    .replace(/^-|-$/g, ""); // Trim leading/trailing hyphens
+}
+
+/**
+ * Generate a short kebab-case summary from TASKS.md content
+ * Max 5 words, e.g., "auth-flow-setup"
+ *
+ * Strategy:
+ * 1. Try to use the first phase name if available
+ * 2. Fall back to combining first few task IDs
+ * 3. Truncate to max 5 words
+ */
+export function generatePlanSummary(tasksContent: string): string {
+  const MAX_WORDS = 5;
+
+  // Try phase names first
+  const phases = extractPhaseNames(tasksContent);
+  if (phases.length > 0 && phases[0]) {
+    const kebab = toKebabCase(phases[0]);
+    const words = kebab.split("-").filter(Boolean);
+    if (words.length > 0) {
+      return words.slice(0, MAX_WORDS).join("-");
+    }
+  }
+
+  // Fall back to task IDs
+  const taskIds = extractTaskIds(tasksContent);
+  if (taskIds.length > 0) {
+    // Take the first task ID and use it as the summary
+    const firstTaskId = taskIds[0];
+    if (firstTaskId) {
+      const kebab = toKebabCase(firstTaskId);
+      const words = kebab.split("-").filter(Boolean);
+      if (words.length > 0) {
+        return words.slice(0, MAX_WORDS).join("-");
+      }
+    }
+  }
+
+  // Ultimate fallback
+  return "plan";
+}

package/src/tasks.ts

@@ -1,5 +1,6 @@
 import { join } from "node:path";
 import { existsSync } from "node:fs";
+import { getTodoDir } from "./paths";
 
 export interface Task {
   id: string;
@@ -178,7 +179,7 @@ export function updateTaskStatus(
 export async function readTasks(
   todoDir?: string
 ): Promise<{ tasks: Task[]; content: string }> {
-  const dir = todoDir || join(process.cwd(), "todo");
+  const dir = todoDir || getTodoDir();
   const tasksPath = join(dir, "TASKS.md");
 
   if (!existsSync(tasksPath)) {
@@ -198,7 +199,7 @@ export async function writeTasks(
   content: string,
   todoDir?: string
 ): Promise<void> {
-  const dir = todoDir || join(process.cwd(), "todo");
+  const dir = todoDir || getTodoDir();
   const tasksPath = join(dir, "TASKS.md");
   await Bun.write(tasksPath, content);
 }

package/src/templates.ts

@@ -105,6 +105,10 @@ Only commit AFTER tests pass.
 | Stage all | \`git add -A\` |
 | Commit | \`git commit -m "feat: ..."\` |
 
+**Directory Structure:**
+- \`.math/todo/\` - Active sprint files (PROMPT.md, TASKS.md, LEARNINGS.md)
+- \`.math/backups/<summary>/\` - Archived sprints from \`math iterate\`
+
 ---
 
 ## Remember