@ilya-lesikov/pi-pi 0.1.0

package/extensions/orchestrator/state.test.ts

@@ -0,0 +1,343 @@
+import { mkdtempSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "fs";
+import { tmpdir } from "os";
+import { join } from "path";
+import { afterEach, describe, expect, it, vi } from "vitest";
+import lockfile from "proper-lockfile";
+import { createTask, getActiveTask, listTasks, loadTask, saveTask, taskAge, taskName, validateFromPath, type TaskState } from "./state.js";
+
+const tempDirs: string[] = [];
+
+function makeCwd(): string {
+  const dir = mkdtempSync(join(tmpdir(), "pi-pi-state-"));
+  tempDirs.push(dir);
+  return dir;
+}
+
+afterEach(() => {
+  vi.restoreAllMocks();
+  while (tempDirs.length > 0) {
+    const dir = tempDirs.pop();
+    if (dir) rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+describe("createTask", () => {
+  it("creates implement task directory and initial state", () => {
+    const cwd = makeCwd();
+    const taskDir = createTask(cwd, "implement", "Build New Feature");
+    const state = loadTask(taskDir);
+
+    expect(taskDir).toContain(join(cwd, ".pp", "state", "implement"));
+    expect(state.phase).toBe("brainstorm");
+    expect(state.from).toBeNull();
+    expect(state.description).toBe("Build New Feature");
+    expect(new Date(state.startedAt).toString()).not.toBe("Invalid Date");
+
+    const raw = readFileSync(join(taskDir, "state.json"), "utf-8");
+    expect(raw.endsWith("\n")).toBe(true);
+  });
+
+  it("uses debug as initial phase for debug", () => {
+    const cwd = makeCwd();
+    const taskDir = createTask(cwd, "debug", "Fix timeout issue");
+    const state = loadTask(taskDir);
+    expect(state.phase).toBe("debug");
+    expect(state.step).toBe("llm_work");
+    expect(state.reviewCycle).toBeNull();
+    expect(state.reviewPass).toBe(0);
+  });
+
+  it("uses brainstorm as initial phase for brainstorm", () => {
+    const cwd = makeCwd();
+    const taskDir = createTask(cwd, "brainstorm", "Explore ideas");
+    const state = loadTask(taskDir);
+    expect(state.phase).toBe("brainstorm");
+    expect(state.step).toBe("llm_work");
+    expect(state.reviewCycle).toBeNull();
+    expect(state.reviewPass).toBe(0);
+  });
+});
+
+describe("loadTask", () => {
+  it("reads and parses state.json", () => {
+    const cwd = makeCwd();
+    const taskDir = createTask(cwd, "implement", "Readable state");
+    const state = loadTask(taskDir);
+    expect(state.description).toBe("Readable state");
+  });
+
+  it("throws descriptive error on corrupt json", () => {
+    const cwd = makeCwd();
+    const taskDir = createTask(cwd, "implement", "Corrupt me");
+    writeFileSync(join(taskDir, "state.json"), "{ this-is-not-json", "utf-8");
+
+    expect(() => loadTask(taskDir)).toThrowError(/Failed to parse .*state\.json:/);
+  });
+});
+
+describe("saveTask", () => {
+  it("writes state.json correctly", () => {
+    const cwd = makeCwd();
+    const taskDir = createTask(cwd, "implement", "Initial");
+    const state: TaskState = {
+      phase: "implement",
+      step: "user_gate",
+      reviewCycle: { kind: "auto", step: "await_reviewers", pass: 2 },
+      reviewPass: 1,
+      from: "implement/some-task",
+      description: "Updated",
+      startedAt: "2026-04-20T00:00:00.000Z",
+    };
+
+    saveTask(taskDir, state);
+
+    const loaded = loadTask(taskDir);
+    expect(loaded).toEqual(state);
+  });
+});
+
+describe("listTasks", () => {
+  it("lists only non-done tasks and respects type filter", () => {
+    const cwd = makeCwd();
+    const implementTask = createTask(cwd, "implement", "Implement feature");
+    const debugTask = createTask(cwd, "debug", "Debug crash");
+    const brainstormTask = createTask(cwd, "brainstorm", "Idea storm");
+
+    const doneState = loadTask(debugTask);
+    doneState.phase = "done";
+    saveTask(debugTask, doneState);
+
+    const all = listTasks(cwd);
+    const allDirs = all.map((t) => t.dir);
+    expect(allDirs).toContain(implementTask);
+    expect(allDirs).toContain(brainstormTask);
+    expect(allDirs).not.toContain(debugTask);
+
+    const brainstormOnly = listTasks(cwd, "brainstorm");
+    expect(brainstormOnly).toHaveLength(1);
+    expect(brainstormOnly[0].dir).toBe(brainstormTask);
+    expect(brainstormOnly[0].type).toBe("brainstorm");
+  });
+
+  it("skips corrupt task entries", () => {
+    const cwd = makeCwd();
+    createTask(cwd, "implement", "Healthy task");
+    const corrupt = createTask(cwd, "implement", "Broken task");
+    writeFileSync(join(corrupt, "state.json"), "{ nope", "utf-8");
+
+    const errorSpy = vi.spyOn(console, "error").mockImplementation(() => undefined);
+    const tasks = listTasks(cwd, "implement");
+
+    expect(tasks).toHaveLength(1);
+    expect(tasks[0].state.description).toBe("Healthy task");
+    expect(errorSpy).toHaveBeenCalled();
+  });
+});
+
+describe("validateFromPath", () => {
+  it("rejects paths containing dot-dot", () => {
+    const cwd = makeCwd();
+    expect(validateFromPath(cwd, "implement/../x")).toEqual({
+      ok: false,
+      reason: "Path must not contain '..'",
+    });
+  });
+
+  it("rejects escaping .pp/state", () => {
+    const cwd = makeCwd();
+    const result = validateFromPath(cwd, "/tmp");
+    expect(result).toEqual({
+      ok: false,
+      reason: "Path escapes .pp/state/ directory",
+    });
+  });
+
+  it("rejects missing source directories", () => {
+    const cwd = makeCwd();
+    expect(validateFromPath(cwd, "implement/missing")).toEqual({
+      ok: false,
+      reason: "Source task not found: implement/missing",
+    });
+  });
+
+  it("rejects directories without state.json", () => {
+    const cwd = makeCwd();
+    const relative = "implement/no-state";
+    mkdirSync(join(cwd, ".pp", "state", relative), { recursive: true });
+
+    expect(validateFromPath(cwd, relative)).toEqual({
+      ok: false,
+      reason: "No state.json found at implement/no-state — not a valid task directory",
+    });
+  });
+
+  it("accepts valid task directories", () => {
+    const cwd = makeCwd();
+    const taskDir = createTask(cwd, "implement", "Valid source");
+    const relative = taskDir.replace(join(cwd, ".pp", "state") + "/", "");
+
+    expect(validateFromPath(cwd, relative)).toEqual({ ok: true, dir: taskDir });
+  });
+
+  it("allows fromPath resolving to state root and then fails state.json validation", () => {
+    const cwd = makeCwd();
+    mkdirSync(join(cwd, ".pp", "state"), { recursive: true });
+
+    expect(validateFromPath(cwd, ".")).toEqual({
+      ok: false,
+      reason: "No state.json found at . — not a valid task directory",
+    });
+  });
+});
+
+describe("taskName", () => {
+  it("returns description from state.json", () => {
+    const cwd = makeCwd();
+    const taskDir = createTask(cwd, "implement", "My readable task name");
+    expect(taskName(taskDir)).toBe("My readable task name");
+  });
+
+  it("falls back to parsed directory name", () => {
+    const cwd = makeCwd();
+    const taskDir = join(cwd, ".pp", "state", "implement", "123456789012_my-fallback-name");
+    mkdirSync(taskDir, { recursive: true });
+
+    const errorSpy = vi.spyOn(console, "error").mockImplementation(() => undefined);
+    expect(taskName(taskDir)).toBe("my fallback name");
+    expect(errorSpy).toHaveBeenCalled();
+  });
+});
+
+describe("taskAge", () => {
+  it("formats minutes", () => {
+    const state: TaskState = {
+      phase: "brainstorm",
+      step: null,
+      reviewCycle: null,
+      reviewPass: 0,
+      from: null,
+      description: "x",
+      startedAt: new Date(Date.now() - 5 * 60 * 1000).toISOString(),
+    };
+    expect(taskAge(state)).toBe("5m");
+  });
+
+  it("formats hours", () => {
+    const state: TaskState = {
+      phase: "brainstorm",
+      step: null,
+      reviewCycle: null,
+      reviewPass: 0,
+      from: null,
+      description: "x",
+      startedAt: new Date(Date.now() - 3 * 60 * 60 * 1000).toISOString(),
+    };
+    expect(taskAge(state)).toBe("3h");
+  });
+
+  it("formats days", () => {
+    const state: TaskState = {
+      phase: "brainstorm",
+      step: null,
+      reviewCycle: null,
+      reviewPass: 0,
+      from: null,
+      description: "x",
+      startedAt: new Date(Date.now() - 2 * 24 * 60 * 60 * 1000).toISOString(),
+    };
+    expect(taskAge(state)).toBe("2d");
+  });
+
+  it("returns '?' for empty startedAt", () => {
+    const state: TaskState = {
+      phase: "brainstorm",
+      step: null,
+      reviewCycle: null,
+      reviewPass: 0,
+      from: null,
+      description: "x",
+      startedAt: "",
+    };
+    expect(taskAge(state)).toBe("?");
+  });
+
+  it("returns '?' for non-date startedAt", () => {
+    const state: TaskState = {
+      phase: "brainstorm",
+      step: null,
+      reviewCycle: null,
+      reviewPass: 0,
+      from: null,
+      description: "x",
+      startedAt: "not-a-date",
+    };
+    expect(taskAge(state)).toBe("?");
+  });
+
+  it("returns '?' for undefined startedAt", () => {
+    const state = {
+      phase: "brainstorm",
+      step: null,
+      reviewCycle: null,
+      reviewPass: 0,
+      from: null,
+      description: "x",
+      startedAt: undefined,
+    } as any;
+    expect(taskAge(state)).toBe("?");
+  });
+});
+
+describe("getActiveTask", () => {
+  it("returns single unlocked task for restoration", () => {
+    const cwd = makeCwd();
+    const taskDir = createTask(cwd, "implement", "Abandoned task");
+    const checkSpy = vi.spyOn(lockfile, "checkSync").mockReturnValue(false);
+
+    const result = getActiveTask(cwd);
+
+    expect(checkSpy).toHaveBeenCalledWith(join(taskDir, "state.json"), expect.objectContaining({ stale: 600000 }));
+    expect(result?.dir).toBe(taskDir);
+  });
+
+  it("returns null when task is locked by another process", () => {
+    const cwd = makeCwd();
+    createTask(cwd, "implement", "Active elsewhere");
+    vi.spyOn(lockfile, "checkSync").mockReturnValue(true);
+
+    expect(getActiveTask(cwd)).toBeNull();
+  });
+
+  it("returns null when multiple unlocked tasks exist (ambiguous)", () => {
+    const cwd = makeCwd();
+    createTask(cwd, "implement", "First abandoned");
+    createTask(cwd, "debug", "Second abandoned");
+    vi.spyOn(lockfile, "checkSync").mockReturnValue(false);
+
+    expect(getActiveTask(cwd)).toBeNull();
+  });
+
+  it("returns the single unlocked task when others are locked", () => {
+    const cwd = makeCwd();
+    const lockedTask = createTask(cwd, "implement", "Locked by other");
+    const unlockedTask = createTask(cwd, "debug", "Abandoned");
+
+    vi.spyOn(lockfile, "checkSync").mockImplementation((path: string, _options?: { stale?: number }) => {
+      if (path === join(lockedTask, "state.json")) return true;
+      return false;
+    });
+
+    const result = getActiveTask(cwd);
+    expect(result?.dir).toBe(unlockedTask);
+  });
+
+  it("uses custom lockStale for stale detection", () => {
+    const cwd = makeCwd();
+    const taskDir = createTask(cwd, "implement", "Stale test");
+    const checkSpy = vi.spyOn(lockfile, "checkSync").mockReturnValue(false);
+
+    getActiveTask(cwd, 1234);
+
+    expect(checkSpy).toHaveBeenCalledWith(join(taskDir, "state.json"), expect.objectContaining({ stale: 1234 }));
+  });
+});

package/extensions/orchestrator/state.ts

@@ -0,0 +1,237 @@
+import { appendFileSync, readFileSync, writeFileSync, existsSync, mkdirSync, readdirSync } from "fs";
+import { join, basename, resolve } from "path";
+import lockfile from "proper-lockfile";
+
+function getLockfileFs(): typeof import("fs") | undefined {
+  try {
+    const fs = require("fs");
+    fs.statSync(process.cwd());
+    return fs;
+  } catch {
+    return undefined;
+  }
+}
+import type { TimeoutConfig } from "./config.js";
+
+export type TaskType = "implement" | "debug" | "brainstorm";
+
+export type ImplementPhase = "brainstorm" | "plan" | "implement" | "done";
+export type DebugPhase = "debug" | "plan" | "implement" | "done";
+export type BrainstormPhase = "brainstorm" | "plan" | "implement" | "done";
+export type Phase = ImplementPhase | DebugPhase | BrainstormPhase;
+
+export interface TaskState {
+  phase: Phase;
+  step: string | null;
+  reviewCycle: { kind: string; step: string; pass: number } | null;
+  reviewPass: number;
+  reviewPassByKind?: Record<string, number>;
+  modifiedFiles?: string[];
+  repoCwd?: string;
+  from: string | null;
+  description: string;
+  startedAt: string;
+}
+
+export interface TaskInfo {
+  dir: string;
+  state: TaskState;
+  type: TaskType;
+}
+
+function stateDir(cwd: string): string {
+  return join(cwd, ".pp", "state");
+}
+
+function taskStatePath(taskDir: string): string {
+  return join(taskDir, "state.json");
+}
+
+export function createTask(cwd: string, type: TaskType, description: string): string {
+  const id = crypto.randomUUID().slice(0, 12);
+  const safeName = description
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, "-")
+    .replace(/^-|-$/g, "")
+    .slice(0, 40);
+  const dirName = `${id}_${safeName}`;
+  const taskDir = join(stateDir(cwd), type, dirName);
+
+  mkdirSync(taskDir, { recursive: true });
+
+  const state: TaskState = {
+    phase: type === "implement" ? "brainstorm" : type === "debug" ? "debug" : "brainstorm",
+    step: "llm_work",
+    reviewCycle: null,
+    reviewPass: 0,
+    from: null,
+    description,
+    startedAt: new Date().toISOString(),
+  };
+
+  writeFileSync(taskStatePath(taskDir), JSON.stringify(state, null, 2) + "\n", "utf-8");
+  return taskDir;
+}
+
+export function loadTask(taskDir: string): TaskState {
+  const sp = taskStatePath(taskDir);
+  const raw = readFileSync(sp, "utf-8");
+  try {
+    const state = JSON.parse(raw) as TaskState & { phase?: string };
+    if (state.phase === "planning") {
+      state.phase = "plan";
+    }
+    return state;
+  } catch (err: any) {
+    throw new Error(`Failed to parse ${sp}: ${err.message}`);
+  }
+}
+
+export function saveTask(taskDir: string, state: TaskState): void {
+  writeFileSync(taskStatePath(taskDir), JSON.stringify(state, null, 2) + "\n", "utf-8");
+}
+
+export function listTasks(cwd: string, type?: TaskType): TaskInfo[] {
+  const base = stateDir(cwd);
+  if (!existsSync(base)) return [];
+
+  const types: TaskType[] = type ? [type] : ["implement", "debug", "brainstorm"];
+  const results: TaskInfo[] = [];
+
+  for (const t of types) {
+    const typeDir = join(base, t);
+    if (!existsSync(typeDir)) continue;
+
+    for (const entry of readdirSync(typeDir, { withFileTypes: true })) {
+      if (!entry.isDirectory()) continue;
+      const dir = join(typeDir, entry.name);
+      const sp = taskStatePath(dir);
+      if (!existsSync(sp)) continue;
+
+      try {
+        const state = loadTask(dir);
+        if (state.phase !== "done") {
+          results.push({ dir, state, type: t });
+        }
+      } catch {
+        console.error(`[pi-pi] Skipping corrupt task at ${dir}`);
+      }
+    }
+  }
+
+  results.sort((a, b) => {
+    const aTime = a.state.startedAt ? new Date(a.state.startedAt).getTime() : 0;
+    const bTime = b.state.startedAt ? new Date(b.state.startedAt).getTime() : 0;
+    return bTime - aTime;
+  });
+
+  return results;
+}
+
+export async function lockTask(taskDir: string, timeouts: TimeoutConfig): Promise<() => Promise<void>> {
+  const sp = taskStatePath(taskDir);
+  if (!existsSync(sp)) {
+    throw new Error(`Task state file not found: ${sp}`);
+  }
+  const lockFs = getLockfileFs();
+  const release = await lockfile.lock(sp, {
+    ...(lockFs && { fs: lockFs }),
+    stale: timeouts.lockStale,
+    update: timeouts.lockUpdate,
+    retries: { retries: 3, minTimeout: 200, maxTimeout: 1000 },
+    onCompromised: (err: Error) => {
+      console.error(`[pi-pi] Lock compromised for ${sp}: ${err.message}`);
+    },
+  });
+  return release;
+}
+
+export function getActiveTask(cwd: string, lockStale?: number): TaskInfo | null {
+  const tasks = listTasks(cwd);
+  if (tasks.length === 0) return null;
+
+  const stale = lockStale ?? 600000;
+  const unlocked: TaskInfo[] = [];
+  for (const task of tasks) {
+    try {
+      const checkFs = getLockfileFs();
+      if (!lockfile.checkSync(taskStatePath(task.dir), { ...(checkFs && { fs: checkFs }), stale })) {
+        unlocked.push(task);
+      }
+    } catch {
+      console.error(`[pi-pi] Failed to check lock for ${task.dir}`);
+    }
+  }
+
+  if (unlocked.length !== 1) return null;
+  return unlocked[0];
+}
+
+export function validateFromPath(cwd: string, fromPath: string): { ok: true; dir: string } | { ok: false; reason: string } {
+  if (fromPath.includes("..")) {
+    return { ok: false, reason: "Path must not contain '..'" };
+  }
+
+  const stateRoot = resolve(stateDir(cwd));
+  const resolved = resolve(stateRoot, fromPath);
+
+  if (resolved !== stateRoot && !resolved.startsWith(stateRoot + "/")) {
+    return { ok: false, reason: "Path escapes .pp/state/ directory" };
+  }
+
+  if (!existsSync(resolved)) {
+    return { ok: false, reason: `Source task not found: ${fromPath}` };
+  }
+
+  const sp = taskStatePath(resolved);
+  if (!existsSync(sp)) {
+    return { ok: false, reason: `No state.json found at ${fromPath} — not a valid task directory` };
+  }
+
+  return { ok: true, dir: resolved };
+}
+
+export function taskName(taskDir: string): string {
+  try {
+    const state = loadTask(taskDir);
+    let desc = state.description ?? "";
+
+    if (["implement", "debug", "brainstorm"].includes(desc)) {
+      const urPath = join(taskDir, "USER_REQUEST.md");
+      if (existsSync(urPath)) {
+        const content = readFileSync(urPath, "utf-8");
+        const lines = content.split("\n").map((l) => l.trim()).filter((l) => l.length > 0);
+        const firstContent = lines.find((l) => !l.startsWith("#"));
+        if (firstContent) desc = firstContent;
+      }
+    }
+
+    if (desc) {
+      desc = desc.replace(/\s+/g, " ").trim();
+      if (desc.length > 60) desc = desc.slice(0, 57) + "...";
+      return desc;
+    }
+  } catch {
+    console.error(`[pi-pi] Failed to read task name from ${taskDir}`);
+  }
+  const dir = basename(taskDir);
+  const match = dir.match(/^\d+_(.+)$/);
+  return match ? match[1].replace(/-/g, " ") : dir;
+}
+
+export function taskAge(state: TaskState): string {
+  const ms = Date.now() - new Date(state.startedAt).getTime();
+  if (isNaN(ms)) return "?";
+  const minutes = Math.floor(ms / 60000);
+  if (minutes < 60) return `${minutes}m`;
+  const hours = Math.floor(minutes / 60);
+  if (hours < 24) return `${hours}h`;
+  return `${Math.floor(hours / 24)}d`;
+}
+
+export function appendTaskLog(taskDir: string, fileName: string, entry: Record<string, unknown>): string {
+  mkdirSync(taskDir, { recursive: true });
+  const filePath = join(taskDir, fileName);
+  appendFileSync(filePath, JSON.stringify(entry) + "\n", "utf-8");
+  return filePath;
+}

package/extensions/orchestrator/validate-artifacts.test.ts

@@ -0,0 +1,88 @@
+import { describe, expect, it } from "vitest";
+import { validatePlan, validateUserRequest } from "./validate-artifacts.js";
+
+describe("validateUserRequest", () => {
+  it("rejects placeholder distillation and constraints content", () => {
+    const content = `# User Request
+TBD
+
+## Problem
+Real problem statement.
+
+## Constraints
+-
+`;
+
+    const result = validateUserRequest(content);
+    expect(result.ok).toBe(false);
+    if (result.ok) return;
+    expect(result.errors).toContain(
+      "Distillation is missing between # User Request and the first ## section. Expected 1-3 non-empty sentences.",
+    );
+    expect(result.errors).toContain("Section ## Constraints is empty. Expected non-empty constraints.");
+  });
+});
+
+describe("validatePlan", () => {
+  it("ignores checkbox items outside Checklist section", () => {
+    const content = `# Plan
+
+## Scope
+Ship minimal fix.
+
+## Checklist
+- [ ] Implement fix — Done when: tests pass
+
+## Blockers
+- [ ] external dependency not resolved
+`;
+
+    const result = validatePlan(content);
+    expect(result.ok).toBe(true);
+  });
+
+  it("accepts multiline Done when continuation", () => {
+    const content = `# Plan
+
+## Scope
+Ship minimal fix.
+
+## Checklist
+- [ ] Implement fix
+  Done when: tests pass and docs updated
+`;
+
+    const result = validatePlan(content);
+    expect(result.ok).toBe(true);
+  });
+
+  it("accepts section names with trailing colon or inline text", () => {
+    const content = `# Plan
+
+## Scope: Handle panics gracefully
+Ship minimal fix.
+
+## Checklist:
+- [ ] Implement fix — Done when: tests pass
+`;
+
+    const result = validatePlan(content);
+    expect(result.ok).toBe(true);
+  });
+
+  it("rejects placeholder scope", () => {
+    const content = `# Plan
+
+## Scope
+...
+
+## Checklist
+- [ ] Implement fix — Done when: tests pass
+`;
+
+    const result = validatePlan(content);
+    expect(result.ok).toBe(false);
+    if (result.ok) return;
+    expect(result.errors).toContain("Section ## Scope is empty. Expected 2-4 lines summarizing scope and constraints.");
+  });
+});