pi-teams 0.5.2 → 0.7.3

package/src/utils/tasks.test.ts

@@ -1,8 +1,9 @@
+// Project: pi-teams
 import { describe, it, expect, vi, afterEach, beforeEach } from "vitest";
 import fs from "node:fs";
 import path from "node:path";
 import os from "node:os";
-import { createTask, updateTask, readTask, listTasks } from "./tasks";
+import { createTask, updateTask, readTask, listTasks, submitPlan, evaluatePlan } from "./tasks";
 import * as paths from "./paths";
 import * as teams from "./teams";
 
@@ -43,6 +44,24 @@ describe("Tasks Utilities", () => {
     expect(taskData.status).toBe("in_progress");
   });
 
+  it("should submit a plan successfully", async () => {
+    const task = await createTask("test-team", "Test Subject", "Test Description");
+    const plan = "Step 1: Do something\nStep 2: Profit";
+    const updated = await submitPlan("test-team", task.id, plan);
+    expect(updated.status).toBe("planning");
+    expect(updated.plan).toBe(plan);
+    
+    const taskData = JSON.parse(fs.readFileSync(path.join(testDir, `${task.id}.json`), "utf-8"));
+    expect(taskData.status).toBe("planning");
+    expect(taskData.plan).toBe(plan);
+  });
+
+  it("should fail to submit an empty plan", async () => {
+    const task = await createTask("test-team", "Empty Test", "Should fail");
+    await expect(submitPlan("test-team", task.id, "")).rejects.toThrow("Plan must not be empty");
+    await expect(submitPlan("test-team", task.id, "   ")).rejects.toThrow("Plan must not be empty");
+  });
+
   it("should list tasks", async () => {
     await createTask("test-team", "Task 1", "Desc 1");
     await createTask("test-team", "Task 2", "Desc 2");
@@ -74,4 +93,50 @@ describe("Tasks Utilities", () => {
     
     fs.unlinkSync(commonLockFile);
   });
+
+  it("should approve a plan successfully", async () => {
+    const task = await createTask("test-team", "Plan Test", "Should be approved");
+    await submitPlan("test-team", task.id, "Wait for it...");
+    
+    const approved = await evaluatePlan("test-team", task.id, "approve");
+    expect(approved.status).toBe("in_progress");
+    expect(approved.planFeedback).toBe("");
+  });
+
+  it("should reject a plan with feedback", async () => {
+    const task = await createTask("test-team", "Plan Test", "Should be rejected");
+    await submitPlan("test-team", task.id, "Wait for it...");
+    
+    const feedback = "Not good enough!";
+    const rejected = await evaluatePlan("test-team", task.id, "reject", feedback);
+    expect(rejected.status).toBe("planning");
+    expect(rejected.planFeedback).toBe(feedback);
+  });
+
+  it("should fail to evaluate a task not in 'planning' status", async () => {
+    const task = await createTask("test-team", "Status Test", "Invalid status for eval");
+    // status is "pending"
+    await expect(evaluatePlan("test-team", task.id, "approve")).rejects.toThrow("must be in 'planning' status");
+  });
+
+  it("should fail to evaluate a task without a plan", async () => {
+    const task = await createTask("test-team", "Plan Missing Test", "No plan submitted");
+    await updateTask("test-team", task.id, { status: "planning" }); // bypass submitPlan to have no plan
+    await expect(evaluatePlan("test-team", task.id, "approve")).rejects.toThrow("no plan has been submitted");
+  });
+
+  it("should fail to reject a plan without feedback", async () => {
+    const task = await createTask("test-team", "Feedback Test", "Should require feedback");
+    await submitPlan("test-team", task.id, "My plan");
+    await expect(evaluatePlan("test-team", task.id, "reject")).rejects.toThrow("Feedback is required when rejecting a plan");
+    await expect(evaluatePlan("test-team", task.id, "reject", "   ")).rejects.toThrow("Feedback is required when rejecting a plan");
+  });
+
+  it("should sanitize task IDs in all file operations", async () => {
+    const dirtyId = "../evil-id";
+    // sanitizeName should throw on this dirtyId
+    await expect(readTask("test-team", dirtyId)).rejects.toThrow(/Invalid name: "..\/evil-id"/);
+    await expect(updateTask("test-team", dirtyId, { status: "in_progress" })).rejects.toThrow(/Invalid name: "..\/evil-id"/);
+    await expect(evaluatePlan("test-team", dirtyId, "approve")).rejects.toThrow(/Invalid name: "..\/evil-id"/);
+  });
 });

package/src/utils/tasks.ts

@@ -1,9 +1,11 @@
+// Project: pi-teams
 import fs from "node:fs";
 import path from "node:path";
 import { TaskFile } from "./models";
 import { taskDir, sanitizeName } from "./paths";
 import { teamExists } from "./teams";
 import { withLock } from "./lock";
+import { runHook } from "./hooks";
 
 export function getTaskId(teamName: string): string {
   const dir = taskDir(teamName);
@@ -12,6 +14,12 @@ export function getTaskId(teamName: string): string {
   return ids.length > 0 ? (Math.max(...ids) + 1).toString() : "1";
 }
 
+function getTaskPath(teamName: string, taskId: string): string {
+  const dir = taskDir(teamName);
+  const safeTaskId = sanitizeName(taskId);
+  return path.join(dir, `${safeTaskId}.json`);
+}
+
 export async function createTask(
   teamName: string,
   subject: string,
@@ -48,9 +56,7 @@ export async function updateTask(
   updates: Partial<TaskFile>,
   retries?: number
 ): Promise<TaskFile> {
-  const dir = taskDir(teamName);
-  const safeTaskId = sanitizeName(taskId);
-  const p = path.join(dir, `${safeTaskId}.json`);
+  const p = getTaskPath(teamName, taskId);
 
   return await withLock(p, async () => {
     if (!fs.existsSync(p)) throw new Error(`Task ${taskId} not found`);
@@ -62,15 +68,81 @@ export async function updateTask(
       return updated;
     }
 
+    fs.writeFileSync(p, JSON.stringify(updated, null, 2));
+
+    if (updates.status === "completed") {
+      await runHook(teamName, "task_completed", updated);
+    }
+
+    return updated;
+  }, retries);
+}
+
+/**
+ * Submits a plan for a task, updating its status to "planning".
+ * @param teamName The name of the team
+ * @param taskId The ID of the task
+ * @param plan The content of the plan
+ * @returns The updated task
+ */
+export async function submitPlan(teamName: string, taskId: string, plan: string): Promise<TaskFile> {
+  if (!plan || !plan.trim()) throw new Error("Plan must not be empty");
+  return await updateTask(teamName, taskId, { status: "planning", plan });
+}
+
+/**
+ * Evaluates a submitted plan for a task.
+ * @param teamName The name of the team
+ * @param taskId The ID of the task
+ * @param action The evaluation action: "approve" or "reject"
+ * @param feedback Optional feedback for the evaluation (required for rejection)
+ * @param retries Number of times to retry acquiring the lock
+ * @returns The updated task
+ */
+export async function evaluatePlan(
+  teamName: string,
+  taskId: string,
+  action: "approve" | "reject",
+  feedback?: string,
+  retries?: number
+): Promise<TaskFile> {
+  const p = getTaskPath(teamName, taskId);
+
+  return await withLock(p, async () => {
+    if (!fs.existsSync(p)) throw new Error(`Task ${taskId} not found`);
+    const task: TaskFile = JSON.parse(fs.readFileSync(p, "utf-8"));
+
+    // 1. Validate state: Only "planning" tasks can be evaluated
+    if (task.status !== "planning") {
+      throw new Error(
+        `Cannot evaluate plan for task ${taskId} because its status is '${task.status}'. ` +
+        `Tasks must be in 'planning' status to be evaluated.`
+      );
+    }
+
+    // 2. Validate plan presence
+    if (!task.plan || !task.plan.trim()) {
+      throw new Error(`Cannot evaluate plan for task ${taskId} because no plan has been submitted.`);
+    }
+
+    // 3. Require feedback for rejections
+    if (action === "reject" && (!feedback || !feedback.trim())) {
+      throw new Error("Feedback is required when rejecting a plan.");
+    }
+
+    // 4. Perform update
+    const updates: Partial<TaskFile> = action === "approve" 
+      ? { status: "in_progress", planFeedback: "" }
+      : { status: "planning", planFeedback: feedback };
+
+    const updated = { ...task, ...updates };
     fs.writeFileSync(p, JSON.stringify(updated, null, 2));
     return updated;
   }, retries);
 }
 
 export async function readTask(teamName: string, taskId: string, retries?: number): Promise<TaskFile> {
-  const dir = taskDir(teamName);
-  const safeTaskId = sanitizeName(taskId);
-  const p = path.join(dir, `${safeTaskId}.json`);
+  const p = getTaskPath(teamName, taskId);
   if (!fs.existsSync(p)) throw new Error(`Task ${taskId} not found`);
   return await withLock(p, async () => {
     return JSON.parse(fs.readFileSync(p, "utf-8"));

package/src/utils/terminal-adapter.ts

@@ -0,0 +1,85 @@
+/**
+ * Terminal Adapter Interface
+ * 
+ * Abstracts terminal multiplexer operations (tmux, iTerm2, Zellij)
+ * to provide a unified API for spawning, managing, and terminating panes.
+ */
+
+import { spawnSync } from "node:child_process";
+
+/**
+ * Options for spawning a new terminal pane
+ */
+export interface SpawnOptions {
+  /** Name/identifier for the pane */
+  name: string;
+  /** Working directory for the new pane */
+  cwd: string;
+  /** Command to execute in the pane */
+  command: string;
+  /** Environment variables to set (key-value pairs) */
+  env: Record<string, string>;
+}
+
+/**
+ * Terminal Adapter Interface
+ * 
+ * Implementations provide terminal-specific logic for pane management.
+ */
+export interface TerminalAdapter {
+  /** Unique name identifier for this terminal type */
+  readonly name: string;
+
+  /**
+   * Detect if this terminal is currently available/active.
+   * Should check for terminal-specific environment variables or processes.
+   * 
+   * @returns true if this terminal should be used
+   */
+  detect(): boolean;
+
+  /**
+   * Spawn a new terminal pane with the given options.
+   * 
+   * @param options - Spawn configuration
+   * @returns Pane ID that can be used for subsequent operations
+   * @throws Error if spawn fails
+   */
+  spawn(options: SpawnOptions): string;
+
+  /**
+   * Kill/terminate a terminal pane.
+   * Should be idempotent - no error if pane doesn't exist.
+   * 
+   * @param paneId - The pane ID returned from spawn()
+   */
+  kill(paneId: string): void;
+
+  /**
+   * Check if a terminal pane is still alive/active.
+   * 
+   * @param paneId - The pane ID returned from spawn()
+   * @returns true if pane exists and is active
+   */
+  isAlive(paneId: string): boolean;
+
+  /**
+   * Set the title of the current terminal pane/window.
+   * Used for identifying panes in the terminal UI.
+   * 
+   * @param title - The title to set
+   */
+  setTitle(title: string): void;
+}
+
+/**
+ * Base helper for adapters to execute commands synchronously.
+ */
+export function execCommand(command: string, args: string[]): { stdout: string; stderr: string; status: number | null } {
+  const result = spawnSync(command, args, { encoding: "utf-8" });
+  return {
+    stdout: result.stdout?.toString() ?? "",
+    stderr: result.stderr?.toString() ?? "",
+    status: result.status,
+  };
+}