feat: add idea tracking to state for crash recovery

- Add currentIdeaPath and currentIdeaFilename fields to State interface
- Persist idea tracking across restarts for crash recovery
- Update state tests for new fields

Signed-off-by: leocavalcante <[email protected]>

Author: leocavalcante

src/state.ts

@@ -11,10 +11,14 @@ const DEFAULT_STATE: State = {
 	phase: "init",
 	taskIndex: 0,
 	lastUpdate: "",
+	currentIdeaPath: undefined,
+	currentIdeaFilename: undefined,
 }
 
 /**
- * Load state from file, or return default state if file doesn't exist
+ * Load state from file, or return default state if file doesn't exist.
+ * @param stateFile - Path to the state JSON file
+ * @returns RuntimeState loaded from file or default state
  */
 export async function loadState(stateFile: string): Promise<RuntimeState> {
 	const content = await readFileOrNull(stateFile)
@@ -26,24 +30,65 @@ export async function loadState(stateFile: string): Promise<RuntimeState> {
 	try {
 		const parsed = JSON.parse(content) as Partial<State>
 
+		// Validate cycle is a positive number
+		if (parsed.cycle !== undefined && (typeof parsed.cycle !== "number" || parsed.cycle < 1)) {
+			console.warn(
+				`Warning: Invalid cycle value in ${stateFile} (expected positive number, got ${parsed.cycle}). Using default.`,
+			)
+			parsed.cycle = DEFAULT_STATE.cycle
+		}
+
+		// Validate taskIndex is a non-negative number
+		if (
+			parsed.taskIndex !== undefined &&
+			(typeof parsed.taskIndex !== "number" || parsed.taskIndex < 0)
+		) {
+			console.warn(
+				`Warning: Invalid taskIndex in ${stateFile} (expected non-negative number, got ${parsed.taskIndex}). Using default.`,
+			)
+			parsed.taskIndex = DEFAULT_STATE.taskIndex
+		}
+
+		// Validate phase
+		const validatedPhase = validatePhase(parsed.phase)
+		if (parsed.phase !== undefined && validatedPhase === null) {
+			console.warn(
+				`Warning: Invalid phase in ${stateFile} (got "${parsed.phase}", expected one of: init, plan, build, evaluation). Using default.`,
+			)
+		}
+
 		// Merge with defaults to handle missing fields
 		const state: State = {
 			cycle: parsed.cycle ?? DEFAULT_STATE.cycle,
-			phase: validatePhase(parsed.phase) ?? DEFAULT_STATE.phase,
+			phase: validatedPhase ?? DEFAULT_STATE.phase,
 			taskIndex: parsed.taskIndex ?? DEFAULT_STATE.taskIndex,
 			sessionId: parsed.sessionId,
 			lastUpdate: parsed.lastUpdate ?? DEFAULT_STATE.lastUpdate,
+			currentIdeaPath: parsed.currentIdeaPath,
+			currentIdeaFilename: parsed.currentIdeaFilename,
 		}
 
 		return toRuntimeState(state)
 	} catch (err) {
-		console.warn(`Warning: Failed to parse state file, using defaults: ${err}`)
+		// Provide specific guidance based on error type
+		if (err instanceof SyntaxError) {
+			console.warn(
+				`Warning: Failed to parse ${stateFile} - invalid JSON syntax. ` +
+					`The file may be corrupted. Using default state. Error: ${err.message}`,
+			)
+		} else {
+			console.warn(
+				`Warning: Failed to load state from ${stateFile}. Using default state. Error: ${err}`,
+			)
+		}
 		return toRuntimeState(DEFAULT_STATE)
 	}
 }
 
 /**
- * Save state to file
+ * Save state to file.
+ * @param stateFile - Path to the state JSON file
+ * @param state - RuntimeState to persist
  */
 export async function saveState(stateFile: string, state: RuntimeState): Promise<void> {
 	// Only persist the State fields, not RuntimeState extras
@@ -53,6 +98,8 @@ export async function saveState(stateFile: string, state: RuntimeState): Promise
 		taskIndex: state.taskIndex,
 		sessionId: state.sessionId,
 		lastUpdate: getISOTimestamp(),
+		currentIdeaPath: state.currentIdeaPath,
+		currentIdeaFilename: state.currentIdeaFilename,
 	}
 
 	const content = JSON.stringify(persistedState, null, 2)
@@ -83,7 +130,8 @@ function validatePhase(phase: unknown): Phase | null {
 }
 
 /**
- * Reset state to initial values for a new run
+ * Reset state to initial values for a new run.
+ * @returns Fresh RuntimeState with cycle 1 and init phase
  */
 export function resetState(): RuntimeState {
 	return toRuntimeState({
@@ -93,7 +141,9 @@ export function resetState(): RuntimeState {
 }
 
 /**
- * Create a fresh state for starting a new cycle
+ * Create a fresh state for starting a new cycle.
+ * @param currentCycle - The current cycle number
+ * @returns Partial RuntimeState with incremented cycle and reset task fields
  */
 export function newCycleState(currentCycle: number): Partial<RuntimeState> {
 	return {
@@ -104,5 +154,7 @@ export function newCycleState(currentCycle: number): Partial<RuntimeState> {
 		totalTasks: 0,
 		currentTaskNum: 0,
 		currentTaskDesc: "",
+		currentIdeaPath: undefined,
+		currentIdeaFilename: undefined,
 	}
 }

tests/state.test.ts

@@ -2,10 +2,10 @@
  * Tests for state module
  */
 
-import { describe, expect, test, beforeEach, afterEach } from "bun:test"
-import { mkdirSync, rmSync, existsSync } from "node:fs"
+import { afterEach, beforeEach, describe, expect, test } from "bun:test"
+import { existsSync, mkdirSync, rmSync } from "node:fs"
 import { join } from "node:path"
-import { loadState, saveState, resetState, newCycleState } from "../src/state.ts"
+import { loadState, newCycleState, resetState, saveState } from "../src/state.ts"
 
 const TEST_DIR = "/tmp/opencoder-test-state"
 
@@ -71,6 +71,36 @@ describe("state", () => {
 			expect(state.phase).toBe("init") // default
 			expect(state.taskIndex).toBe(0) // default
 		})
+
+		test("handles invalid cycle value with default", async () => {
+			const stateFile = join(TEST_DIR, "invalid-cycle.json")
+			await Bun.write(stateFile, JSON.stringify({ cycle: -5, phase: "build" }))
+
+			const state = await loadState(stateFile)
+
+			expect(state.cycle).toBe(1) // default due to invalid negative value
+			expect(state.phase).toBe("build") // valid phase should be kept
+		})
+
+		test("handles invalid phase value with default", async () => {
+			const stateFile = join(TEST_DIR, "invalid-phase.json")
+			await Bun.write(stateFile, JSON.stringify({ cycle: 3, phase: "invalid_phase" }))
+
+			const state = await loadState(stateFile)
+
+			expect(state.cycle).toBe(3) // valid cycle should be kept
+			expect(state.phase).toBe("init") // default due to invalid phase
+		})
+
+		test("handles invalid taskIndex value with default", async () => {
+			const stateFile = join(TEST_DIR, "invalid-taskindex.json")
+			await Bun.write(stateFile, JSON.stringify({ cycle: 2, taskIndex: -1 }))
+
+			const state = await loadState(stateFile)
+
+			expect(state.cycle).toBe(2) // valid cycle should be kept
+			expect(state.taskIndex).toBe(0) // default due to invalid negative value
+		})
 	})
 
 	describe("saveState", () => {