@a5c-ai/babysitter-observer-dashboard 5.0.1-staging.7a8768ec

package/src/app/actions/__tests__/approve-breakpoint.test.ts

@@ -0,0 +1,246 @@
+import { describe, it, expect, vi, beforeEach } from "vitest";
+
+// Create hoisted mock functions
+const { mockAccess, mockWriteFile, mockMkdir, mockReaddir, mockFindRunDir } = vi.hoisted(() => ({
+  mockAccess: vi.fn(),
+  mockWriteFile: vi.fn(),
+  mockMkdir: vi.fn(),
+  mockReaddir: vi.fn(),
+  mockFindRunDir: vi.fn(),
+}));
+
+// Mock path-resolver
+vi.mock("@/lib/path-resolver", () => ({
+  findRunDir: mockFindRunDir,
+}));
+
+// Mock fs with a complete replacement that includes default export
+vi.mock("fs", () => {
+  return {
+    default: {
+      promises: {
+        access: mockAccess,
+        writeFile: mockWriteFile,
+        mkdir: mockMkdir,
+        readdir: mockReaddir,
+      },
+    },
+    promises: {
+      access: mockAccess,
+      writeFile: mockWriteFile,
+      mkdir: mockMkdir,
+      readdir: mockReaddir,
+    },
+  };
+});
+
+import { approveBreakpoint } from "../approve-breakpoint";
+
+const defaultSource = { path: "/projects", depth: 2, label: "test" };
+
+describe("approveBreakpoint", () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+    // Default: journal dir has some existing entries
+    mockMkdir.mockResolvedValue(undefined);
+    mockReaddir.mockResolvedValue(["000001.01ABC.json", "000002.01DEF.json"]);
+  });
+
+  // -------------------------------------------------------------------------
+  // Input validation
+  // -------------------------------------------------------------------------
+
+  it("returns error when runId is empty", async () => {
+    const result = await approveBreakpoint("", "eff-001", "yes");
+    expect(result.success).toBe(false);
+    expect(result.error).toContain("Missing or invalid runId");
+  });
+
+  it("returns error when effectId is empty", async () => {
+    const result = await approveBreakpoint("run-001", "", "yes");
+    expect(result.success).toBe(false);
+    expect(result.error).toContain("Missing or invalid effectId");
+  });
+
+  it("returns error when answer is empty", async () => {
+    const result = await approveBreakpoint("run-001", "eff-001", "");
+    expect(result.success).toBe(false);
+    expect(result.error).toContain("Answer cannot be empty");
+  });
+
+  it("returns error when answer is only whitespace", async () => {
+    const result = await approveBreakpoint("run-001", "eff-001", "   ");
+    expect(result.success).toBe(false);
+    expect(result.error).toContain("Answer cannot be empty");
+  });
+
+  it("returns error when runId contains path traversal characters", async () => {
+    const result = await approveBreakpoint("../etc", "eff-001", "yes");
+    expect(result.success).toBe(false);
+    expect(result.error).toContain("Invalid characters");
+  });
+
+  it("returns error when effectId contains path traversal characters", async () => {
+    const result = await approveBreakpoint("run-001", "../../etc", "yes");
+    expect(result.success).toBe(false);
+    expect(result.error).toContain("Invalid characters");
+  });
+
+  // -------------------------------------------------------------------------
+  // Run/task resolution
+  // -------------------------------------------------------------------------
+
+  it("returns error when run is not found", async () => {
+    mockFindRunDir.mockResolvedValue(null);
+
+    const result = await approveBreakpoint("run-999", "eff-001", "yes");
+    expect(result.success).toBe(false);
+    expect(result.error).toContain("Run not found");
+  });
+
+  it("returns error when task directory does not exist", async () => {
+    mockFindRunDir.mockResolvedValue({
+      runDir: "/projects/app/.a5c/runs/run-001",
+      source: defaultSource,
+      projectName: "app",
+      projectPath: "/projects/app",
+    });
+    mockAccess.mockRejectedValueOnce(new Error("ENOENT"));
+
+    const result = await approveBreakpoint("run-001", "eff-001", "yes");
+    expect(result.success).toBe(false);
+    expect(result.error).toContain("Task directory not found");
+  });
+
+  // -------------------------------------------------------------------------
+  // Success path
+  // -------------------------------------------------------------------------
+
+  it("writes result.json and journal entry on success", async () => {
+    const runDir = "/projects/app/.a5c/runs/run-001";
+    mockFindRunDir.mockResolvedValue({
+      runDir,
+      source: defaultSource,
+      projectName: "app",
+      projectPath: "/projects/app",
+    });
+    mockAccess.mockResolvedValue(undefined);
+    mockWriteFile.mockResolvedValue(undefined);
+
+    const result = await approveBreakpoint("run-001", "eff-001", "Deploy approved");
+    expect(result.success).toBe(true);
+
+    // Should write 2 files: result.json + journal entry
+    expect(mockWriteFile).toHaveBeenCalledTimes(2);
+
+    // First write: result.json
+    const [resultPath, resultContent] = mockWriteFile.mock.calls[0];
+    expect(resultPath).toContain("eff-001");
+    expect(resultPath).toContain("result.json");
+
+    const parsed = JSON.parse(resultContent as string);
+    expect(parsed.status).toBe("ok");
+    expect(parsed.value.answer).toBe("Deploy approved");
+    expect(parsed.value.approvedBy).toBe("observer-dashboard");
+    expect(parsed.value.approvedAt).toBeDefined();
+    expect(parsed.startedAt).toBeDefined();
+    expect(parsed.finishedAt).toBeDefined();
+
+    // Second write: journal entry
+    const [journalPath, journalContent] = mockWriteFile.mock.calls[1];
+    expect(journalPath).toContain("journal");
+    expect(journalPath).toMatch(/000003\./); // next seq after 000001, 000002
+
+    const journalParsed = JSON.parse(journalContent as string);
+    expect(journalParsed.type).toBe("EFFECT_RESOLVED");
+    expect(journalParsed.data.effectId).toBe("eff-001");
+    expect(journalParsed.data.status).toBe("ok");
+    expect(journalParsed.data.resultRef).toBe("tasks/eff-001/result.json");
+    expect(journalParsed.checksum).toBeDefined();
+    expect(typeof journalParsed.checksum).toBe("string");
+    expect(journalParsed.checksum.length).toBe(64); // SHA-256 hex
+  });
+
+  it("journal checksum is valid SHA-256 of payload without checksum", async () => {
+    const runDir = "/projects/app/.a5c/runs/run-001";
+    mockFindRunDir.mockResolvedValue({
+      runDir,
+      source: defaultSource,
+      projectName: "app",
+      projectPath: "/projects/app",
+    });
+    mockAccess.mockResolvedValue(undefined);
+    mockWriteFile.mockResolvedValue(undefined);
+
+    await approveBreakpoint("run-001", "eff-001", "yes");
+
+    const [, journalContent] = mockWriteFile.mock.calls[1];
+    const journalParsed = JSON.parse(journalContent as string);
+
+    // Recompute checksum: SHA-256 of JSON.stringify(payloadWithoutChecksum, null, 2) + "\n"
+    const { checksum: _checksum, ...payloadWithoutChecksum } = journalParsed;
+    const crypto = await import("crypto");
+    const expected = crypto.default
+      .createHash("sha256")
+      .update(JSON.stringify(payloadWithoutChecksum, null, 2) + "\n")
+      .digest("hex");
+    expect(journalParsed.checksum).toBe(expected);
+  });
+
+  it("uses seq 1 when journal dir is empty", async () => {
+    const runDir = "/projects/app/.a5c/runs/run-001";
+    mockFindRunDir.mockResolvedValue({
+      runDir,
+      source: defaultSource,
+      projectName: "app",
+      projectPath: "/projects/app",
+    });
+    mockAccess.mockResolvedValue(undefined);
+    mockWriteFile.mockResolvedValue(undefined);
+    mockReaddir.mockResolvedValue([]); // empty journal
+
+    await approveBreakpoint("run-001", "eff-001", "yes");
+
+    const [journalPath] = mockWriteFile.mock.calls[1];
+    expect(journalPath).toMatch(/000001\./);
+  });
+
+  it("trims whitespace from the answer", async () => {
+    const runDir = "/projects/app/.a5c/runs/run-001";
+    mockFindRunDir.mockResolvedValue({
+      runDir,
+      source: defaultSource,
+      projectName: "app",
+      projectPath: "/projects/app",
+    });
+    mockAccess.mockResolvedValue(undefined);
+    mockWriteFile.mockResolvedValue(undefined);
+
+    const result = await approveBreakpoint("run-001", "eff-001", "  yes  ");
+    expect(result.success).toBe(true);
+
+    const [, content] = mockWriteFile.mock.calls[0];
+    const parsed = JSON.parse(content as string);
+    expect(parsed.value.answer).toBe("yes");
+  });
+
+  // -------------------------------------------------------------------------
+  // Write failure
+  // -------------------------------------------------------------------------
+
+  it("returns error when file write fails", async () => {
+    const runDir = "/projects/app/.a5c/runs/run-001";
+    mockFindRunDir.mockResolvedValue({
+      runDir,
+      source: defaultSource,
+      projectName: "app",
+      projectPath: "/projects/app",
+    });
+    mockAccess.mockResolvedValue(undefined);
+    mockWriteFile.mockRejectedValue(new Error("EACCES: permission denied"));
+
+    const result = await approveBreakpoint("run-001", "eff-001", "yes");
+    expect(result.success).toBe(false);
+    expect(result.error).toContain("EACCES");
+  });
+});

package/src/app/actions/approve-breakpoint.ts

@@ -0,0 +1,145 @@
+"use server";
+
+import { promises as fs } from "fs";
+import path from "path";
+import crypto from "crypto";
+import { monotonicFactory } from "ulid";
+import { findRunDir } from "@/lib/path-resolver";
+
+export interface ApproveBreakpointResult {
+  success: boolean;
+  error?: string;
+}
+
+const nextUlid = monotonicFactory();
+
+/**
+ * Determine the next journal sequence number by scanning existing files.
+ */
+async function getNextJournalSeq(journalDir: string): Promise<number> {
+  try {
+    const files = await fs.readdir(journalDir);
+    let max = 0;
+    for (const f of files) {
+      const seqStr = f.split(".")[0];
+      const seq = Number(seqStr);
+      if (Number.isFinite(seq) && seq > max) max = seq;
+    }
+    return max + 1;
+  } catch {
+    // Journal dir may not exist yet — seq 1
+    return 1;
+  }
+}
+
+/**
+ * Write an EFFECT_RESOLVED journal entry using the same format as the
+ * babysitter SDK: SHA-256 checksum of the JSON payload (without checksum)
+ * serialized as `JSON.stringify(payload, null, 2) + "\n"`.
+ */
+async function appendJournalEntry(
+  runDir: string,
+  effectId: string,
+  now: string,
+): Promise<void> {
+  const journalDir = path.join(runDir, "journal");
+  await fs.mkdir(journalDir, { recursive: true });
+
+  const seq = await getNextJournalSeq(journalDir);
+  const ulid = nextUlid();
+  const filename = `${seq.toString().padStart(6, "0")}.${ulid}.json`;
+
+  const eventPayload = {
+    type: "EFFECT_RESOLVED",
+    recordedAt: now,
+    data: {
+      effectId,
+      status: "ok",
+      resultRef: `tasks/${effectId}/result.json`,
+      startedAt: now,
+      finishedAt: now,
+    },
+  };
+
+  const contents = JSON.stringify(eventPayload, null, 2) + "\n";
+  const checksum = crypto.createHash("sha256").update(contents).digest("hex");
+  const payloadWithChecksum = JSON.stringify({ ...eventPayload, checksum }, null, 2) + "\n";
+
+  await fs.writeFile(path.join(journalDir, filename), payloadWithChecksum, "utf-8");
+}
+
+/**
+ * Server Action: approve a breakpoint by writing both the result.json AND
+ * an EFFECT_RESOLVED journal entry. This ensures the SDK's state machine
+ * recognizes the resolution on the next `run:iterate` (the SDK auto-rebuilds
+ * its state cache when it detects journal head mismatch).
+ *
+ * Previous implementation only wrote result.json, leaving the journal
+ * untouched — the SDK never knew the breakpoint was resolved, causing runs
+ * to stay stuck in "Waiting" state permanently.
+ */
+export async function approveBreakpoint(
+  runId: string,
+  effectId: string,
+  answer: string,
+): Promise<ApproveBreakpointResult> {
+  // --- Validate inputs ---
+  if (!runId || typeof runId !== "string") {
+    return { success: false, error: "Missing or invalid runId" };
+  }
+  if (!effectId || typeof effectId !== "string") {
+    return { success: false, error: "Missing or invalid effectId" };
+  }
+  if (!answer || typeof answer !== "string" || answer.trim().length === 0) {
+    return { success: false, error: "Answer cannot be empty" };
+  }
+
+  // Sanitize IDs to prevent path traversal
+  const idPattern = /^[a-zA-Z0-9_\-]+$/;
+  if (!idPattern.test(runId) || !idPattern.test(effectId)) {
+    return { success: false, error: "Invalid characters in runId or effectId" };
+  }
+
+  try {
+    // --- Resolve the run directory ---
+    const found = await findRunDir(runId);
+    if (!found) {
+      return { success: false, error: `Run not found: ${runId}` };
+    }
+    const runDir = found.runDir;
+
+    // --- Verify the task directory exists ---
+    const taskDir = path.join(runDir, "tasks", effectId);
+    try {
+      await fs.access(taskDir);
+    } catch {
+      return { success: false, error: `Task directory not found: ${effectId}` };
+    }
+
+    // --- Write result.json (SDK-compatible format) ---
+    const now = new Date().toISOString();
+    const resultPayload = {
+      status: "ok",
+      value: {
+        answer: answer.trim(),
+        approvedAt: now,
+        approvedBy: "observer-dashboard",
+      },
+      startedAt: now,
+      finishedAt: now,
+    };
+    const resultPath = path.join(taskDir, "result.json");
+    await fs.writeFile(resultPath, JSON.stringify(resultPayload, null, 2), "utf-8");
+
+    // --- Append EFFECT_RESOLVED journal entry ---
+    // This is the critical piece that was missing: without a journal entry,
+    // the SDK's state machine never knows the breakpoint was resolved and
+    // the run stays stuck in "Waiting" forever.
+    await appendJournalEntry(runDir, effectId, now);
+
+    return { success: true };
+  } catch (err: unknown) {
+    const msg = err instanceof Error ? err.message : String(err);
+    return { success: false, error: msg };
+  }
+}

package/src/app/api/config/route.ts

@@ -0,0 +1,137 @@
+import { NextResponse } from "next/server";
+import { getConfig, invalidateConfigCache, writeConfig } from "@/lib/config-loader";
+import { invalidateAll, discoverAndCacheAll } from "@/lib/run-cache";
+import { normalizeError } from "@/lib/error-handler";
+
+export const dynamic = "force-dynamic";
+
+export async function GET() {
+  try {
+    const config = await getConfig();
+    return NextResponse.json(config);
+  } catch (err) {
+    const normalized = normalizeError(err);
+    return NextResponse.json(
+      { error: normalized.message, code: normalized.code },
+      { status: normalized.status }
+    );
+  }
+}
+
+export async function POST(request: Request) {
+  try {
+    const body = await request.json();
+
+    // Validate sources
+    if (!Array.isArray(body.sources)) {
+      return NextResponse.json(
+        { error: "sources must be an array" },
+        { status: 400 }
+      );
+    }
+
+    for (let i = 0; i < body.sources.length; i++) {
+      const s = body.sources[i];
+      if (!s || typeof s.path !== "string" || !s.path.trim()) {
+        return NextResponse.json(
+          { error: `sources[${i}].path must be a non-empty string` },
+          { status: 400 }
+        );
+      }
+      if (typeof s.depth !== "number" || s.depth < 0 || s.depth > 10) {
+        return NextResponse.json(
+          { error: `sources[${i}].depth must be a number between 0 and 10` },
+          { status: 400 }
+        );
+      }
+    }
+
+    // Validate pollInterval
+    if (body.pollInterval !== undefined) {
+      if (typeof body.pollInterval !== "number" || body.pollInterval < 500) {
+        return NextResponse.json(
+          { error: "pollInterval must be a number >= 500" },
+          { status: 400 }
+        );
+      }
+    }
+
+    // Validate theme
+    if (body.theme !== undefined) {
+      if (body.theme !== "dark" && body.theme !== "light") {
+        return NextResponse.json(
+          { error: "theme must be 'dark' or 'light'" },
+          { status: 400 }
+        );
+      }
+    }
+
+    // Validate staleThresholdMs
+    if (body.staleThresholdMs !== undefined) {
+      if (typeof body.staleThresholdMs !== "number" || body.staleThresholdMs < 0) {
+        return NextResponse.json(
+          { error: "staleThresholdMs must be a non-negative number" },
+          { status: 400 }
+        );
+      }
+    }
+
+    // Validate retentionDays
+    if (body.retentionDays !== undefined) {
+      if (typeof body.retentionDays !== "number" || body.retentionDays < 1 || body.retentionDays > 365) {
+        return NextResponse.json(
+          { error: "retentionDays must be a number between 1 and 365" },
+          { status: 400 }
+        );
+      }
+    }
+
+    // Validate hiddenProjects
+    if (body.hiddenProjects !== undefined) {
+      if (!Array.isArray(body.hiddenProjects) || body.hiddenProjects.some((p: unknown) => typeof p !== "string")) {
+        return NextResponse.json(
+          { error: "hiddenProjects must be an array of strings" },
+          { status: 400 }
+        );
+      }
+    }
+
+    // Build config to save
+    const configToSave = {
+      sources: body.sources.map((s: { path: string; depth: number; label?: string }) => ({
+        path: s.path.trim(),
+        depth: s.depth,
+        ...(s.label ? { label: s.label.trim() } : {}),
+      })),
+      ...(body.pollInterval !== undefined ? { pollInterval: body.pollInterval } : {}),
+      ...(body.theme !== undefined ? { theme: body.theme } : {}),
+      ...(body.staleThresholdMs !== undefined ? { staleThresholdMs: body.staleThresholdMs } : {}),
+      ...(body.retentionDays !== undefined ? { retentionDays: body.retentionDays } : {}),
+      ...(body.hiddenProjects !== undefined ? { hiddenProjects: body.hiddenProjects } : {}),
+    };
+
+    // Write to disk
+    await writeConfig(configToSave);
+
+    // Invalidate caches so next request reads fresh
+    invalidateConfigCache();
+    invalidateAll(); // Clear run cache so re-discovery uses new sources
+
+    // Read back the full merged config
+    const savedConfig = await getConfig();
+
+    // Re-discover all runs with new sources (fire and forget)
+    discoverAndCacheAll().catch((err) =>
+      console.error("Failed to re-discover runs after config change:", err)
+    );
+
+    return NextResponse.json(savedConfig);
+  } catch (err) {
+    console.error("Failed to save config:", err);
+    const normalized = normalizeError(err);
+    return NextResponse.json(
+      { error: normalized.message, code: normalized.code },
+      { status: normalized.status }
+    );
+  }
+}

package/src/app/api/digest/route.ts

@@ -0,0 +1,45 @@
+import { NextResponse } from "next/server";
+import { ensureInitialized } from "@/lib/server-init";
+import { getAllCachedDigests, discoverAndCacheAll } from "@/lib/run-cache";
+import { normalizeError } from "@/lib/error-handler";
+
+export const dynamic = "force-dynamic";
+
+export async function GET() {
+  try {
+    try {
+      await ensureInitialized();
+    } catch (initError) {
+      console.error("Server initialization failed:", initError);
+      return NextResponse.json(
+        { error: "Server initialization failed. Check observer configuration and watch sources.", code: "INIT_FAILED" },
+        { status: 500 }
+      );
+    }
+
+    // Ensure cache is populated — discoverAndCacheAll() is debounced internally
+    // (10s) so repeated calls are cheap. This guarantees runs invalidated by the
+    // watcher are re-populated before we read the cache.
+    await discoverAndCacheAll();
+    const runs = getAllCachedDigests();
+
+    // Sort by updatedAt descending (most recent first), with runId tiebreaker
+    // to ensure stable ordering when multiple runs share the same timestamp.
+    runs.sort((a, b) => {
+      const cmp = (b.updatedAt || "").localeCompare(a.updatedAt || "");
+      if (cmp !== 0) return cmp;
+      return a.runId.localeCompare(b.runId);
+    });
+
+    return NextResponse.json({ runs }, {
+      headers: { "Cache-Control": "no-cache, no-store" },
+    });
+  } catch (error) {
+    console.error("Failed to read digest:", error);
+    const normalized = normalizeError(error);
+    return NextResponse.json(
+      { error: normalized.message, code: normalized.code },
+      { status: normalized.status }
+    );
+  }
+}

package/src/app/api/runs/[runId]/events/route.ts

@@ -0,0 +1,56 @@
+import { NextResponse } from "next/server";
+import path from "path";
+import { findRunDir } from "@/lib/path-resolver";
+import { parseJournalDir } from "@/lib/parser";
+import { normalizeError } from "@/lib/error-handler";
+
+export const dynamic = "force-dynamic";
+
+function isValidId(id: string): boolean {
+  return /^[a-zA-Z0-9_\-]+$/.test(id);
+}
+
+export async function GET(
+  request: Request,
+  { params }: { params: { runId: string } }
+) {
+  try {
+    const { runId } = params;
+    if (!isValidId(runId)) {
+      return NextResponse.json({ error: "Invalid run ID" }, { status: 400 });
+    }
+
+    const found = await findRunDir(runId);
+    if (!found) {
+      return NextResponse.json({ error: "Run not found" }, { status: 404 });
+    }
+
+    const journalPath = path.join(found.runDir, "journal");
+
+    const url = new URL(request.url);
+    const limit = parseInt(url.searchParams.get("limit") || "50", 10);
+    const offset = parseInt(url.searchParams.get("offset") || "0", 10);
+
+    if (isNaN(limit) || isNaN(offset) || limit < 0 || offset < 0) {
+      return NextResponse.json(
+        { error: "Invalid pagination parameters", code: "INVALID_INPUT" },
+        { status: 400 }
+      );
+    }
+
+    const allEvents = await parseJournalDir(journalPath);
+    const total = allEvents.length;
+    const events = allEvents.slice(offset, offset + limit);
+
+    return NextResponse.json({ events, total }, {
+      headers: { "Cache-Control": "no-cache, no-store" },
+    });
+  } catch (error) {
+    console.error("Failed to read events:", error);
+    const normalized = normalizeError(error);
+    return NextResponse.json(
+      { error: normalized.message, code: normalized.code },
+      { status: normalized.status }
+    );
+  }
+}