@versdotsh/reef 0.1.2

package/services/board/store.ts

@@ -0,0 +1,329 @@
+/**
+ * Board store — task tracking with notes and artifacts.
+ *
+ * Uses Bun's file APIs for persistence. JSON file with debounced writes.
+ */
+
+import { ulid } from "ulid";
+import { existsSync, mkdirSync } from "node:fs";
+import { dirname } from "node:path";
+
+// =============================================================================
+// Types
+// =============================================================================
+
+export type TaskStatus = "open" | "in_progress" | "in_review" | "blocked" | "done";
+export type NoteType = "finding" | "blocker" | "question" | "update";
+export type ArtifactType = "branch" | "report" | "deploy" | "diff" | "file" | "url";
+
+export interface Note {
+  id: string;
+  author: string;
+  content: string;
+  type: NoteType;
+  createdAt: string;
+}
+
+export interface Artifact {
+  type: ArtifactType;
+  url: string;
+  label: string;
+  addedAt: string;
+  addedBy?: string;
+}
+
+export interface Task {
+  id: string;
+  title: string;
+  description?: string;
+  status: TaskStatus;
+  assignee?: string;
+  tags: string[];
+  dependencies: string[];
+  createdBy: string;
+  createdAt: string;
+  updatedAt: string;
+  notes: Note[];
+  artifacts: Artifact[];
+  score: number;
+}
+
+export interface CreateTaskInput {
+  title: string;
+  description?: string;
+  status?: TaskStatus;
+  assignee?: string;
+  tags?: string[];
+  dependencies?: string[];
+  createdBy: string;
+}
+
+export interface UpdateTaskInput {
+  title?: string;
+  description?: string;
+  status?: TaskStatus;
+  assignee?: string | null;
+  tags?: string[];
+  dependencies?: string[];
+}
+
+export interface AddNoteInput {
+  author: string;
+  content: string;
+  type: NoteType;
+}
+
+export interface AddArtifactInput {
+  type: ArtifactType;
+  url: string;
+  label: string;
+  addedBy?: string;
+}
+
+export interface TaskFilters {
+  status?: TaskStatus;
+  assignee?: string;
+  tag?: string;
+}
+
+// =============================================================================
+// Validation
+// =============================================================================
+
+const VALID_STATUSES = new Set<string>(["open", "in_progress", "in_review", "blocked", "done"]);
+const VALID_NOTE_TYPES = new Set<string>(["finding", "blocker", "question", "update"]);
+const VALID_ARTIFACT_TYPES = new Set<string>(["branch", "report", "deploy", "diff", "file", "url"]);
+
+// =============================================================================
+// Errors
+// =============================================================================
+
+export class NotFoundError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "NotFoundError";
+  }
+}
+
+export class ValidationError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "ValidationError";
+  }
+}
+
+// =============================================================================
+// Store
+// =============================================================================
+
+export class BoardStore {
+  private tasks = new Map<string, Task>();
+  private filePath: string;
+  private writeTimer: ReturnType<typeof setTimeout> | null = null;
+
+  constructor(filePath = "data/board.json") {
+    this.filePath = filePath;
+    this.load();
+  }
+
+  private load(): void {
+    try {
+      const file = Bun.file(this.filePath);
+      if (existsSync(this.filePath)) {
+        // Synchronous read at startup — Bun.file().text() is async,
+        // so we use the fs import path for the initial load
+        const raw = require("node:fs").readFileSync(this.filePath, "utf-8");
+        const data = JSON.parse(raw);
+        if (Array.isArray(data.tasks)) {
+          for (const t of data.tasks) {
+            if (!t.artifacts) t.artifacts = [];
+            if (t.score === undefined) t.score = 0;
+            this.tasks.set(t.id, t);
+          }
+        }
+      }
+    } catch {
+      this.tasks = new Map();
+    }
+  }
+
+  private scheduleSave(): void {
+    if (this.writeTimer) return;
+    this.writeTimer = setTimeout(() => {
+      this.writeTimer = null;
+      this.flushAsync();
+    }, 100);
+  }
+
+  private async flushAsync(): Promise<void> {
+    const dir = dirname(this.filePath);
+    if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
+    const data = JSON.stringify({ tasks: Array.from(this.tasks.values()) }, null, 2);
+    await Bun.write(this.filePath, data);
+  }
+
+  flush(): void {
+    if (this.writeTimer) {
+      clearTimeout(this.writeTimer);
+      this.writeTimer = null;
+    }
+    const dir = dirname(this.filePath);
+    if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
+    const data = JSON.stringify({ tasks: Array.from(this.tasks.values()) }, null, 2);
+    require("node:fs").writeFileSync(this.filePath, data, "utf-8");
+  }
+
+  // --- CRUD ---
+
+  createTask(input: CreateTaskInput): Task {
+    if (!input.title?.trim()) throw new ValidationError("title is required");
+    if (!input.createdBy?.trim()) throw new ValidationError("createdBy is required");
+    if (input.status && !VALID_STATUSES.has(input.status)) {
+      throw new ValidationError(`invalid status: ${input.status}`);
+    }
+
+    const now = new Date().toISOString();
+    const task: Task = {
+      id: ulid(),
+      title: input.title.trim(),
+      description: input.description?.trim(),
+      status: input.status || "open",
+      assignee: input.assignee?.trim(),
+      tags: input.tags || [],
+      dependencies: input.dependencies || [],
+      createdBy: input.createdBy.trim(),
+      createdAt: now,
+      updatedAt: now,
+      notes: [],
+      artifacts: [],
+      score: 0,
+    };
+
+    this.tasks.set(task.id, task);
+    this.scheduleSave();
+    return task;
+  }
+
+  getTask(id: string): Task | undefined {
+    return this.tasks.get(id);
+  }
+
+  listTasks(filters?: TaskFilters): Task[] {
+    let results = Array.from(this.tasks.values());
+
+    if (filters?.status) results = results.filter((t) => t.status === filters.status);
+    if (filters?.assignee) results = results.filter((t) => t.assignee === filters.assignee);
+    if (filters?.tag) results = results.filter((t) => t.tags.includes(filters.tag!));
+
+    results.sort((a, b) => b.createdAt.localeCompare(a.createdAt));
+    return results;
+  }
+
+  updateTask(id: string, input: UpdateTaskInput): Task {
+    const task = this.tasks.get(id);
+    if (!task) throw new NotFoundError("task not found");
+
+    if (input.status !== undefined && !VALID_STATUSES.has(input.status)) {
+      throw new ValidationError(`invalid status: ${input.status}`);
+    }
+    if (input.title !== undefined) {
+      if (!input.title.trim()) throw new ValidationError("title cannot be empty");
+      task.title = input.title.trim();
+    }
+    if (input.description !== undefined) task.description = input.description?.trim();
+    if (input.status !== undefined) task.status = input.status;
+    if (input.assignee !== undefined) {
+      task.assignee = input.assignee === null ? undefined : input.assignee?.trim();
+    }
+    if (input.tags !== undefined) task.tags = input.tags;
+    if (input.dependencies !== undefined) task.dependencies = input.dependencies;
+
+    task.updatedAt = new Date().toISOString();
+    this.tasks.set(id, task);
+    this.scheduleSave();
+    return task;
+  }
+
+  deleteTask(id: string): boolean {
+    const existed = this.tasks.delete(id);
+    if (existed) this.scheduleSave();
+    return existed;
+  }
+
+  bumpTask(id: string): Task {
+    const task = this.tasks.get(id);
+    if (!task) throw new NotFoundError("task not found");
+
+    task.score = (task.score || 0) + 1;
+    task.updatedAt = new Date().toISOString();
+    this.tasks.set(id, task);
+    this.scheduleSave();
+    return task;
+  }
+
+  // --- Notes ---
+
+  addNote(taskId: string, input: AddNoteInput): Note {
+    const task = this.tasks.get(taskId);
+    if (!task) throw new NotFoundError("task not found");
+
+    if (!input.author?.trim()) throw new ValidationError("author is required");
+    if (!input.content?.trim()) throw new ValidationError("content is required");
+    if (!VALID_NOTE_TYPES.has(input.type)) throw new ValidationError(`invalid note type: ${input.type}`);
+
+    const note: Note = {
+      id: ulid(),
+      author: input.author.trim(),
+      content: input.content.trim(),
+      type: input.type,
+      createdAt: new Date().toISOString(),
+    };
+
+    task.notes.push(note);
+    task.updatedAt = new Date().toISOString();
+    this.tasks.set(taskId, task);
+    this.scheduleSave();
+    return note;
+  }
+
+  getNotes(taskId: string): Note[] {
+    const task = this.tasks.get(taskId);
+    if (!task) throw new NotFoundError("task not found");
+    return task.notes;
+  }
+
+  // --- Artifacts ---
+
+  addArtifacts(taskId: string, artifacts: AddArtifactInput[]): Artifact[] {
+    const task = this.tasks.get(taskId);
+    if (!task) throw new NotFoundError("task not found");
+
+    if (!Array.isArray(artifacts) || artifacts.length === 0) {
+      throw new ValidationError("artifacts array is required and must not be empty");
+    }
+
+    const now = new Date().toISOString();
+    const added: Artifact[] = [];
+
+    for (const a of artifacts) {
+      if (!VALID_ARTIFACT_TYPES.has(a.type)) throw new ValidationError(`invalid artifact type: ${a.type}`);
+      if (!a.url?.trim()) throw new ValidationError("artifact url is required");
+      if (!a.label?.trim()) throw new ValidationError("artifact label is required");
+
+      const artifact: Artifact = {
+        type: a.type,
+        url: a.url.trim(),
+        label: a.label.trim(),
+        addedAt: now,
+        addedBy: a.addedBy?.trim(),
+      };
+      task.artifacts.push(artifact);
+      added.push(artifact);
+    }
+
+    task.updatedAt = now;
+    this.tasks.set(taskId, task);
+    this.scheduleSave();
+    return added;
+  }
+}

package/services/board/tools.ts

@@ -0,0 +1,214 @@
+/**
+ * Board tools — registered on the pi extension so the LLM can manage tasks.
+ */
+
+import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
+import type { FleetClient } from "../src/core/types.js";
+import { Type } from "@sinclair/typebox";
+import { StringEnum } from "@mariozechner/pi-ai";
+
+const STATUS_ENUM = StringEnum(
+  ["open", "in_progress", "in_review", "blocked", "done"] as const,
+  { description: "Task status" },
+);
+
+const ARTIFACT_TYPE_ENUM = StringEnum(
+  ["branch", "report", "deploy", "diff", "file", "url"] as const,
+  { description: "Artifact type" },
+);
+
+export function registerTools(pi: ExtensionAPI, client: FleetClient) {
+  pi.registerTool({
+    name: "board_create_task",
+    label: "Board: Create Task",
+    description:
+      "Create a new task on the shared coordination board. Returns the created task with its ID.",
+    parameters: Type.Object({
+      title: Type.String({ description: "Task title" }),
+      description: Type.Optional(Type.String({ description: "Detailed task description" })),
+      assignee: Type.Optional(Type.String({ description: "Agent or user to assign to" })),
+      tags: Type.Optional(Type.Array(Type.String(), { description: "Tags for categorization" })),
+    }),
+    async execute(_id, params) {
+      if (!client.getBaseUrl()) return client.noUrl();
+      try {
+        const task = await client.api("POST", "/board/tasks", {
+          ...params,
+          createdBy: client.agentName,
+        });
+        return client.ok(JSON.stringify(task, null, 2), { task });
+      } catch (e: any) {
+        return client.err(e.message);
+      }
+    },
+  });
+
+  pi.registerTool({
+    name: "board_list_tasks",
+    label: "Board: List Tasks",
+    description:
+      "List tasks on the shared board. Optionally filter by status, assignee, or tag.",
+    parameters: Type.Object({
+      status: Type.Optional(STATUS_ENUM),
+      assignee: Type.Optional(Type.String({ description: "Filter by assignee" })),
+      tag: Type.Optional(Type.String({ description: "Filter by tag" })),
+    }),
+    async execute(_id, params) {
+      if (!client.getBaseUrl()) return client.noUrl();
+      try {
+        const qs = new URLSearchParams();
+        if (params.status) qs.set("status", params.status);
+        if (params.assignee) qs.set("assignee", params.assignee);
+        if (params.tag) qs.set("tag", params.tag);
+        const query = qs.toString();
+        const result = await client.api("GET", `/board/tasks${query ? `?${query}` : ""}`);
+        return client.ok(JSON.stringify(result, null, 2), { result });
+      } catch (e: any) {
+        return client.err(e.message);
+      }
+    },
+  });
+
+  pi.registerTool({
+    name: "board_update_task",
+    label: "Board: Update Task",
+    description:
+      "Update a task — change status, reassign, rename, or update tags.",
+    parameters: Type.Object({
+      id: Type.String({ description: "Task ID to update" }),
+      status: Type.Optional(STATUS_ENUM),
+      assignee: Type.Optional(Type.String({ description: "New assignee" })),
+      title: Type.Optional(Type.String({ description: "New title" })),
+      tags: Type.Optional(Type.Array(Type.String(), { description: "New tags" })),
+    }),
+    async execute(_toolCallId, params) {
+      if (!client.getBaseUrl()) return client.noUrl();
+      try {
+        const { id, ...updates } = params;
+        const task = await client.api("PATCH", `/board/tasks/${encodeURIComponent(id)}`, updates);
+        return client.ok(JSON.stringify(task, null, 2), { task });
+      } catch (e: any) {
+        return client.err(e.message);
+      }
+    },
+  });
+
+  pi.registerTool({
+    name: "board_add_note",
+    label: "Board: Add Note",
+    description:
+      "Add a note to a task — findings, blockers, questions, or status updates.",
+    parameters: Type.Object({
+      taskId: Type.String({ description: "Task ID to add the note to" }),
+      content: Type.String({ description: "Note content" }),
+      type: StringEnum(["finding", "blocker", "question", "update"] as const, {
+        description: "Note type",
+      }),
+    }),
+    async execute(_id, params) {
+      if (!client.getBaseUrl()) return client.noUrl();
+      try {
+        const { taskId, ...body } = params;
+        const note = await client.api(
+          "POST",
+          `/board/tasks/${encodeURIComponent(taskId)}/notes`,
+          { ...body, author: client.agentName },
+        );
+        return client.ok(JSON.stringify(note, null, 2), { note });
+      } catch (e: any) {
+        return client.err(e.message);
+      }
+    },
+  });
+
+  pi.registerTool({
+    name: "board_submit_for_review",
+    label: "Board: Submit for Review",
+    description:
+      "Submit a task for review — sets status to in_review, adds a summary note, and optionally attaches artifacts.",
+    parameters: Type.Object({
+      taskId: Type.String({ description: "Task ID to submit for review" }),
+      summary: Type.String({ description: "Review summary describing what was done" }),
+      artifacts: Type.Optional(
+        Type.Array(
+          Type.Object({
+            type: ARTIFACT_TYPE_ENUM,
+            url: Type.String({ description: "URL or path to the artifact" }),
+            label: Type.String({ description: "Human-readable label" }),
+          }),
+          { description: "Artifacts to attach" },
+        ),
+      ),
+    }),
+    async execute(_id, params) {
+      if (!client.getBaseUrl()) return client.noUrl();
+      try {
+        const body: Record<string, unknown> = {
+          summary: params.summary,
+          reviewedBy: client.agentName,
+        };
+        if (params.artifacts) body.artifacts = params.artifacts;
+        const task = await client.api(
+          "POST",
+          `/board/tasks/${encodeURIComponent(params.taskId)}/review`,
+          body,
+        );
+        return client.ok(JSON.stringify(task, null, 2), { task });
+      } catch (e: any) {
+        return client.err(e.message);
+      }
+    },
+  });
+
+  pi.registerTool({
+    name: "board_add_artifact",
+    label: "Board: Add Artifact",
+    description:
+      "Add artifact link(s) to any task — branches, reports, deploys, diffs, files, or URLs.",
+    parameters: Type.Object({
+      taskId: Type.String({ description: "Task ID" }),
+      artifacts: Type.Array(
+        Type.Object({
+          type: ARTIFACT_TYPE_ENUM,
+          url: Type.String({ description: "URL or path" }),
+          label: Type.String({ description: "Human-readable label" }),
+        }),
+        { description: "Artifacts to attach" },
+      ),
+    }),
+    async execute(_id, params) {
+      if (!client.getBaseUrl()) return client.noUrl();
+      try {
+        const task = await client.api(
+          "POST",
+          `/board/tasks/${encodeURIComponent(params.taskId)}/artifacts`,
+          { artifacts: params.artifacts.map((a) => ({ ...a, addedBy: client.agentName })) },
+        );
+        return client.ok(JSON.stringify(task, null, 2), { task });
+      } catch (e: any) {
+        return client.err(e.message);
+      }
+    },
+  });
+
+  pi.registerTool({
+    name: "board_bump",
+    label: "Board: Bump Task",
+    description: "Bump a task's score by 1. Use to signal priority or upvote.",
+    parameters: Type.Object({
+      taskId: Type.String({ description: "Task ID to bump" }),
+    }),
+    async execute(_id, params) {
+      if (!client.getBaseUrl()) return client.noUrl();
+      try {
+        const task = await client.api(
+          "POST",
+          `/board/tasks/${encodeURIComponent(params.taskId)}/bump`,
+        );
+        return client.ok(JSON.stringify(task, null, 2), { task });
+      } catch (e: any) {
+        return client.err(e.message);
+      }
+    },
+  });
+}