popeye-cli 1.0.0

package/src/state/index.ts

@@ -0,0 +1,454 @@
+/**
+ * State management module
+ * Provides high-level API for managing project state
+ */
+
+import { v4 as uuidv4 } from 'uuid';
+import type {
+  ProjectState,
+  Task,
+  Milestone,
+  TaskStatus,
+  WorkflowPhase,
+} from '../types/workflow.js';
+import type { ConsensusIteration } from '../types/consensus.js';
+import type { ProjectSpec } from '../types/project.js';
+import {
+  loadState,
+  saveState,
+  stateExists,
+  deleteState,
+  backupState,
+} from './persistence.js';
+
+// Re-export persistence utilities
+export * from './persistence.js';
+
+/**
+ * Create a new project state
+ *
+ * @param spec - The project specification
+ * @param projectDir - The project root directory
+ * @returns The newly created project state
+ */
+export async function createProject(
+  spec: ProjectSpec,
+  projectDir: string
+): Promise<ProjectState> {
+  // Check if project already exists
+  if (await stateExists(projectDir)) {
+    throw new Error(`Project already exists at ${projectDir}. Use loadProject() instead.`);
+  }
+
+  const now = new Date().toISOString();
+
+  const state: ProjectState = {
+    id: uuidv4(),
+    name: spec.name || 'untitled-project',
+    idea: spec.idea,
+    language: spec.language,
+    openaiModel: spec.openaiModel,
+    phase: 'plan',
+    status: 'pending',
+    milestones: [],
+    currentMilestone: null,
+    currentTask: null,
+    consensusHistory: [],
+    createdAt: now,
+    updatedAt: now,
+  };
+
+  await saveState(projectDir, state);
+  return state;
+}
+
+/**
+ * Load an existing project
+ *
+ * @param projectDir - The project root directory
+ * @returns The project state
+ * @throws Error if project doesn't exist
+ */
+export async function loadProject(projectDir: string): Promise<ProjectState> {
+  const state = await loadState(projectDir);
+
+  if (!state) {
+    throw new Error(`No project found at ${projectDir}. Use createProject() first.`);
+  }
+
+  return state;
+}
+
+/**
+ * Check if a project exists at the given directory
+ *
+ * @param projectDir - The project root directory
+ * @returns True if project exists
+ */
+export async function projectExists(projectDir: string): Promise<boolean> {
+  return stateExists(projectDir);
+}
+
+/**
+ * Update project state with partial updates
+ *
+ * @param projectDir - The project root directory
+ * @param updates - Partial state updates
+ * @returns The updated state
+ */
+export async function updateState(
+  projectDir: string,
+  updates: Partial<ProjectState>
+): Promise<ProjectState> {
+  const current = await loadProject(projectDir);
+
+  const updated: ProjectState = {
+    ...current,
+    ...updates,
+    updatedAt: new Date().toISOString(),
+  };
+
+  await saveState(projectDir, updated);
+  return updated;
+}
+
+/**
+ * Set the current workflow phase
+ *
+ * @param projectDir - The project root directory
+ * @param phase - The new phase
+ * @returns The updated state
+ */
+export async function setPhase(
+  projectDir: string,
+  phase: WorkflowPhase
+): Promise<ProjectState> {
+  return updateState(projectDir, { phase });
+}
+
+/**
+ * Add milestones to the project
+ *
+ * @param projectDir - The project root directory
+ * @param milestones - Milestones to add
+ * @returns The updated state
+ */
+export async function addMilestones(
+  projectDir: string,
+  milestones: Omit<Milestone, 'id'>[]
+): Promise<ProjectState> {
+  const current = await loadProject(projectDir);
+
+  const newMilestones: Milestone[] = milestones.map((m, index) => ({
+    ...m,
+    id: `milestone-${current.milestones.length + index + 1}`,
+  }));
+
+  return updateState(projectDir, {
+    milestones: [...current.milestones, ...newMilestones],
+  });
+}
+
+/**
+ * Add tasks to a milestone
+ *
+ * @param projectDir - The project root directory
+ * @param milestoneId - The milestone ID
+ * @param tasks - Tasks to add
+ * @returns The updated state
+ */
+export async function addTasks(
+  projectDir: string,
+  milestoneId: string,
+  tasks: Omit<Task, 'id' | 'status' | 'testsPassed'>[]
+): Promise<ProjectState> {
+  const current = await loadProject(projectDir);
+
+  const milestoneIndex = current.milestones.findIndex((m) => m.id === milestoneId);
+  if (milestoneIndex === -1) {
+    throw new Error(`Milestone ${milestoneId} not found`);
+  }
+
+  const milestone = current.milestones[milestoneIndex];
+  const newTasks: Task[] = tasks.map((t, index) => ({
+    ...t,
+    id: `${milestoneId}-task-${milestone.tasks.length + index + 1}`,
+    status: 'pending' as TaskStatus,
+  }));
+
+  const updatedMilestones = [...current.milestones];
+  updatedMilestones[milestoneIndex] = {
+    ...milestone,
+    tasks: [...milestone.tasks, ...newTasks],
+  };
+
+  return updateState(projectDir, { milestones: updatedMilestones });
+}
+
+/**
+ * Update a task's status
+ *
+ * @param projectDir - The project root directory
+ * @param taskId - The task ID
+ * @param status - The new status
+ * @param additionalUpdates - Additional task updates
+ * @returns The updated state
+ */
+export async function updateTaskStatus(
+  projectDir: string,
+  taskId: string,
+  status: TaskStatus,
+  additionalUpdates: Partial<Task> = {}
+): Promise<ProjectState> {
+  const current = await loadProject(projectDir);
+
+  const updatedMilestones = current.milestones.map((milestone) => ({
+    ...milestone,
+    tasks: milestone.tasks.map((task) =>
+      task.id === taskId ? { ...task, status, ...additionalUpdates } : task
+    ),
+  }));
+
+  // Update milestone status if all tasks are complete
+  const updatedMilestonesWithStatus = updatedMilestones.map((milestone) => {
+    const allComplete = milestone.tasks.every((t) => t.status === 'complete');
+    const anyInProgress = milestone.tasks.some((t) => t.status === 'in-progress');
+
+    let milestoneStatus: TaskStatus = 'pending';
+    if (allComplete) {
+      milestoneStatus = 'complete';
+    } else if (anyInProgress || milestone.tasks.some((t) => t.status === 'complete')) {
+      milestoneStatus = 'in-progress';
+    }
+
+    return { ...milestone, status: milestoneStatus };
+  });
+
+  return updateState(projectDir, { milestones: updatedMilestonesWithStatus });
+}
+
+/**
+ * Set the current milestone being worked on
+ *
+ * @param projectDir - The project root directory
+ * @param milestoneId - The milestone ID (or null)
+ * @returns The updated state
+ */
+export async function setCurrentMilestone(
+  projectDir: string,
+  milestoneId: string | null
+): Promise<ProjectState> {
+  if (milestoneId) {
+    const current = await loadProject(projectDir);
+    const milestone = current.milestones.find((m) => m.id === milestoneId);
+    if (!milestone) {
+      throw new Error(`Milestone ${milestoneId} not found`);
+    }
+  }
+
+  return updateState(projectDir, { currentMilestone: milestoneId });
+}
+
+/**
+ * Set the current task being worked on
+ *
+ * @param projectDir - The project root directory
+ * @param taskId - The task ID (or null)
+ * @returns The updated state
+ */
+export async function setCurrentTask(
+  projectDir: string,
+  taskId: string | null
+): Promise<ProjectState> {
+  return updateState(projectDir, { currentTask: taskId });
+}
+
+/**
+ * Record a consensus iteration
+ *
+ * @param projectDir - The project root directory
+ * @param iteration - The consensus iteration to record
+ * @returns The updated state
+ */
+export async function recordConsensusIteration(
+  projectDir: string,
+  iteration: ConsensusIteration
+): Promise<ProjectState> {
+  const current = await loadProject(projectDir);
+
+  return updateState(projectDir, {
+    consensusHistory: [...current.consensusHistory, iteration],
+  });
+}
+
+/**
+ * Store the approved plan
+ *
+ * @param projectDir - The project root directory
+ * @param plan - The approved plan content
+ * @returns The updated state
+ */
+export async function storePlan(
+  projectDir: string,
+  plan: string
+): Promise<ProjectState> {
+  return updateState(projectDir, { plan });
+}
+
+/**
+ * Store the expanded specification
+ *
+ * @param projectDir - The project root directory
+ * @param specification - The expanded specification
+ * @returns The updated state
+ */
+export async function storeSpecification(
+  projectDir: string,
+  specification: string
+): Promise<ProjectState> {
+  return updateState(projectDir, { specification });
+}
+
+/**
+ * Mark the project as complete
+ *
+ * @param projectDir - The project root directory
+ * @returns The updated state
+ */
+export async function completeProject(projectDir: string): Promise<ProjectState> {
+  return updateState(projectDir, {
+    status: 'complete',
+    phase: 'complete',
+  });
+}
+
+/**
+ * Mark the project as failed
+ *
+ * @param projectDir - The project root directory
+ * @param error - The error message
+ * @returns The updated state
+ */
+export async function failProject(
+  projectDir: string,
+  error: string
+): Promise<ProjectState> {
+  return updateState(projectDir, {
+    status: 'failed',
+    error,
+  });
+}
+
+/**
+ * Get project progress summary
+ *
+ * @param projectDir - The project root directory
+ * @returns Progress summary
+ */
+export async function getProgress(projectDir: string): Promise<{
+  totalMilestones: number;
+  completedMilestones: number;
+  totalTasks: number;
+  completedTasks: number;
+  percentComplete: number;
+}> {
+  const state = await loadProject(projectDir);
+
+  const totalMilestones = state.milestones.length;
+  const completedMilestones = state.milestones.filter((m) => m.status === 'complete').length;
+
+  const allTasks = state.milestones.flatMap((m) => m.tasks);
+  const totalTasks = allTasks.length;
+  const completedTasks = allTasks.filter((t) => t.status === 'complete').length;
+
+  const percentComplete = totalTasks > 0 ? Math.round((completedTasks / totalTasks) * 100) : 0;
+
+  return {
+    totalMilestones,
+    completedMilestones,
+    totalTasks,
+    completedTasks,
+    percentComplete,
+  };
+}
+
+/**
+ * Get the next pending task
+ *
+ * @param projectDir - The project root directory
+ * @returns The next task to work on, or null if none
+ */
+export async function getNextTask(projectDir: string): Promise<{
+  milestone: Milestone;
+  task: Task;
+} | null> {
+  const state = await loadProject(projectDir);
+
+  for (const milestone of state.milestones) {
+    if (milestone.status === 'complete') continue;
+
+    const pendingTask = milestone.tasks.find((t) => t.status === 'pending');
+    if (pendingTask) {
+      return { milestone, task: pendingTask };
+    }
+  }
+
+  return null;
+}
+
+/**
+ * Reset project to a specific phase
+ *
+ * @param projectDir - The project root directory
+ * @param phase - The phase to reset to
+ * @returns The updated state
+ */
+export async function resetToPhase(
+  projectDir: string,
+  phase: WorkflowPhase
+): Promise<ProjectState> {
+  // Create backup before reset
+  await backupState(projectDir);
+
+  const current = await loadProject(projectDir);
+
+  const updates: Partial<ProjectState> = {
+    phase,
+    status: 'pending',
+    error: undefined,
+  };
+
+  if (phase === 'plan') {
+    // Reset everything
+    updates.milestones = [];
+    updates.currentMilestone = null;
+    updates.currentTask = null;
+    updates.plan = undefined;
+  } else if (phase === 'execution') {
+    // Reset task progress but keep milestones
+    updates.milestones = current.milestones.map((m) => ({
+      ...m,
+      status: 'pending' as TaskStatus,
+      tasks: m.tasks.map((t) => ({
+        ...t,
+        status: 'pending' as TaskStatus,
+        testsPassed: undefined,
+        error: undefined,
+      })),
+    }));
+    updates.currentMilestone = null;
+    updates.currentTask = null;
+  }
+
+  return updateState(projectDir, updates);
+}
+
+/**
+ * Delete a project
+ *
+ * @param projectDir - The project root directory
+ * @returns True if project was deleted
+ */
+export async function deleteProject(projectDir: string): Promise<boolean> {
+  return deleteState(projectDir);
+}

package/src/state/persistence.ts

@@ -0,0 +1,230 @@
+/**
+ * State persistence module
+ * Handles atomic read/write operations for project state
+ */
+
+import { promises as fs } from 'node:fs';
+import path from 'node:path';
+import { ProjectStateSchema, type ProjectState } from '../types/workflow.js';
+
+/**
+ * Default state directory name
+ */
+export const STATE_DIR = '.popeye';
+
+/**
+ * State file name
+ */
+export const STATE_FILE = 'state.json';
+
+/**
+ * Get the state directory path for a project
+ *
+ * @param projectDir - The project root directory
+ * @returns The state directory path
+ */
+export function getStateDir(projectDir: string): string {
+  return path.join(projectDir, STATE_DIR);
+}
+
+/**
+ * Get the state file path for a project
+ *
+ * @param projectDir - The project root directory
+ * @returns The state file path
+ */
+export function getStatePath(projectDir: string): string {
+  return path.join(getStateDir(projectDir), STATE_FILE);
+}
+
+/**
+ * Ensure the state directory exists
+ *
+ * @param projectDir - The project root directory
+ */
+export async function ensureStateDir(projectDir: string): Promise<void> {
+  const stateDir = getStateDir(projectDir);
+  await fs.mkdir(stateDir, { recursive: true });
+}
+
+/**
+ * Check if a state file exists for a project
+ *
+ * @param projectDir - The project root directory
+ * @returns True if state file exists
+ */
+export async function stateExists(projectDir: string): Promise<boolean> {
+  try {
+    const statePath = getStatePath(projectDir);
+    await fs.access(statePath);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Load project state from disk
+ *
+ * @param projectDir - The project root directory
+ * @returns The project state or null if not found
+ */
+export async function loadState(projectDir: string): Promise<ProjectState | null> {
+  try {
+    const statePath = getStatePath(projectDir);
+    const content = await fs.readFile(statePath, 'utf-8');
+    const data = JSON.parse(content);
+
+    // Validate with Zod schema
+    const result = ProjectStateSchema.safeParse(data);
+
+    if (!result.success) {
+      console.error('Invalid state file format:', result.error.message);
+      return null;
+    }
+
+    return result.data;
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === 'ENOENT') {
+      return null;
+    }
+    throw error;
+  }
+}
+
+/**
+ * Save project state to disk using atomic write
+ * Uses temp file + rename pattern to prevent corruption
+ *
+ * @param projectDir - The project root directory
+ * @param state - The state to save
+ */
+export async function saveState(projectDir: string, state: ProjectState): Promise<void> {
+  // Ensure state directory exists
+  await ensureStateDir(projectDir);
+
+  const statePath = getStatePath(projectDir);
+  const tempPath = `${statePath}.tmp.${Date.now()}`;
+
+  // Update the updatedAt timestamp
+  const stateToSave: ProjectState = {
+    ...state,
+    updatedAt: new Date().toISOString(),
+  };
+
+  // Validate before saving
+  const result = ProjectStateSchema.safeParse(stateToSave);
+  if (!result.success) {
+    throw new Error(`Invalid state: ${result.error.message}`);
+  }
+
+  // Write to temp file
+  const content = JSON.stringify(stateToSave, null, 2);
+  await fs.writeFile(tempPath, content, 'utf-8');
+
+  // Atomic rename
+  await fs.rename(tempPath, statePath);
+}
+
+/**
+ * Delete project state
+ *
+ * @param projectDir - The project root directory
+ * @returns True if state was deleted
+ */
+export async function deleteState(projectDir: string): Promise<boolean> {
+  try {
+    const statePath = getStatePath(projectDir);
+    await fs.unlink(statePath);
+    return true;
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === 'ENOENT') {
+      return false;
+    }
+    throw error;
+  }
+}
+
+/**
+ * Create a backup of the current state
+ *
+ * @param projectDir - The project root directory
+ * @returns The backup file path or null if no state exists
+ */
+export async function backupState(projectDir: string): Promise<string | null> {
+  const state = await loadState(projectDir);
+
+  if (!state) {
+    return null;
+  }
+
+  const stateDir = getStateDir(projectDir);
+  const timestamp = new Date().toISOString().replace(/[:.]/g, '-');
+  const backupPath = path.join(stateDir, `state.backup.${timestamp}.json`);
+
+  const content = JSON.stringify(state, null, 2);
+  await fs.writeFile(backupPath, content, 'utf-8');
+
+  return backupPath;
+}
+
+/**
+ * List all state backups
+ *
+ * @param projectDir - The project root directory
+ * @returns List of backup file paths
+ */
+export async function listBackups(projectDir: string): Promise<string[]> {
+  try {
+    const stateDir = getStateDir(projectDir);
+    const files = await fs.readdir(stateDir);
+
+    return files
+      .filter((f) => f.startsWith('state.backup.') && f.endsWith('.json'))
+      .map((f) => path.join(stateDir, f))
+      .sort()
+      .reverse(); // Most recent first
+  } catch {
+    return [];
+  }
+}
+
+/**
+ * Restore state from a backup
+ *
+ * @param backupPath - Path to the backup file
+ * @param projectDir - The project root directory
+ */
+export async function restoreFromBackup(
+  backupPath: string,
+  projectDir: string
+): Promise<ProjectState> {
+  const content = await fs.readFile(backupPath, 'utf-8');
+  const data = JSON.parse(content);
+
+  const result = ProjectStateSchema.safeParse(data);
+  if (!result.success) {
+    throw new Error(`Invalid backup file: ${result.error.message}`);
+  }
+
+  await saveState(projectDir, result.data);
+  return result.data;
+}
+
+/**
+ * Clean up old backups, keeping only the most recent N
+ *
+ * @param projectDir - The project root directory
+ * @param keepCount - Number of backups to keep (default 5)
+ */
+export async function cleanupBackups(projectDir: string, keepCount: number = 5): Promise<void> {
+  const backups = await listBackups(projectDir);
+
+  if (backups.length <= keepCount) {
+    return;
+  }
+
+  // Delete old backups
+  const toDelete = backups.slice(keepCount);
+  await Promise.all(toDelete.map((backup) => fs.unlink(backup)));
+}