muonroi-cli 1.4.0 → 1.5.0

package/src/ee/offline-queue.test.ts

@@ -1,302 +0,0 @@
-/**
- * Unit + integration tests for offline-queue module.
- *
- * Tests cover all 10 behaviors:
- *  1. enqueue() creates queue directory lazily
- *  2. enqueue() writes correct JSON content
- *  3. enqueue() enforces 100-entry cap by deleting oldest
- *  4. getQueueDir() returns correct path
- *  5. drainQueue() replays entries in FIFO order
- *  6. drainQueue() stops on failure, leaves remaining entries
- *  7. drainQueue() handles non-existent queue directory
- *  8. drainQueue() discards corrupt JSON files
- *  9. Filename format matches /^\d+-[a-z0-9]{4}\.json$/
- * 10. drainQueue() is fire-and-forget (returns void)
- */
-import { mkdir, readdir, rm, writeFile } from "node:fs/promises";
-import * as os from "node:os";
-import * as path from "node:path";
-import { afterEach, beforeEach, describe, expect, it } from "vitest";
-import { startStubEEServer } from "../__test-stubs__/ee-server.js";
-import { drainQueue, drainQueueAsync, enqueue, getQueueDir } from "./offline-queue.js";
-
-// ─── Helpers ──────────────────────────────────────────────────────────────────
-
-let tmpDir: string;
-
-beforeEach(async () => {
-  // Create isolated temp directory for each test
-  const base = path.join(os.tmpdir(), "queue-test-");
-  // Use a unique timestamp+random suffix
-  const suffix = `${Date.now()}-${Math.random().toString(36).slice(2, 6)}`;
-  tmpDir = base + suffix;
-  await mkdir(tmpDir, { recursive: true });
-});
-
-afterEach(async () => {
-  await rm(tmpDir, { recursive: true, force: true, maxRetries: 10, retryDelay: 50 });
-});
-
-/**
- * Helper: get the ee-offline-queue dir inside tmpDir.
- */
-function queueDir(): string {
-  return getQueueDir(tmpDir);
-}
-
-/**
- * Helper: write N pre-populated queue files with sequential timestamps.
- */
-async function populateQueue(count: number, startTs = 1000): Promise<string[]> {
-  const dir = queueDir();
-  await mkdir(dir, { recursive: true });
-  const filenames: string[] = [];
-  for (let i = 0; i < count; i++) {
-    const ts = startTs + i;
-    const filename = `${ts}-test.json`;
-    const entry = {
-      endpoint: "/api/feedback",
-      body: { i },
-      enqueuedAt: ts,
-    };
-    await writeFile(path.join(dir, filename), JSON.stringify(entry), "utf8");
-    filenames.push(filename);
-  }
-  return filenames;
-}
-
-// ─── Test 1: enqueue() creates queue directory lazily ─────────────────────────
-
-describe("enqueue()", () => {
-  it("creates the queue directory lazily on first call", async () => {
-    // Queue dir should NOT exist before enqueue
-    const dir = queueDir();
-    const files = await readdir(dir).catch(() => null);
-    expect(files).toBeNull(); // dir does not exist yet
-
-    // Call enqueue — should create dir
-    await enqueue({ endpoint: "/api/feedback", body: { test: 1 }, enqueuedAt: 1000 }, tmpDir);
-
-    // Dir should now exist
-    const filesAfter = await readdir(dir);
-    expect(Array.isArray(filesAfter)).toBe(true);
-  });
-
-  // ─── Test 9: Filename format ───────────────────────────────────────────────
-
-  it("creates exactly 1 file with correct filename pattern after one enqueue", async () => {
-    await enqueue({ endpoint: "/api/feedback", body: { test: 1 }, enqueuedAt: 1000 }, tmpDir);
-
-    const files = await readdir(queueDir());
-    expect(files).toHaveLength(1);
-    expect(files[0]).toMatch(/^\d+-[a-z0-9]{4}\.json$/);
-  });
-
-  // ─── Test 2: enqueue() writes correct JSON content ────────────────────────
-
-  it("writes correct JSON content matching the input entry", async () => {
-    const entry = {
-      endpoint: "/api/feedback",
-      body: { test: 1 },
-      enqueuedAt: 1000,
-    };
-    await enqueue(entry, tmpDir);
-
-    const dir = queueDir();
-    const files = await readdir(dir);
-    const raw = await import("node:fs/promises").then((fs) => fs.readFile(path.join(dir, files[0]), "utf8"));
-    const parsed = JSON.parse(raw);
-
-    expect(parsed).toEqual(entry);
-  });
-
-  // ─── Test 3: enqueue() enforces 100-entry cap ─────────────────────────────
-
-  it("enforces 100-entry cap: deletes oldest when queue is at capacity", async () => {
-    // Pre-populate with exactly 100 files
-    const existing = await populateQueue(100, 1000);
-    const oldestFile = existing[0]; // timestamp 1000-test.json
-
-    // Enqueue one more entry
-    await enqueue(
-      {
-        endpoint: "/api/feedback",
-        body: { new: true },
-        enqueuedAt: 99999,
-      },
-      tmpDir,
-    );
-
-    const files = await readdir(queueDir());
-
-    // Should still have exactly 100 files
-    expect(files).toHaveLength(100);
-
-    // Oldest file should be gone
-    expect(files).not.toContain(oldestFile);
-
-    // New file should exist (it has a fresh timestamp prefix via makeFilename())
-    const newFiles = files.filter((f) => !existing.includes(f));
-    expect(newFiles).toHaveLength(1);
-  });
-});
-
-// ─── Test 4: getQueueDir() returns correct path ───────────────────────────────
-
-describe("getQueueDir()", () => {
-  it("returns path under os.homedir() when no override given", () => {
-    const result = getQueueDir();
-    expect(result).toBe(path.join(os.homedir(), ".muonroi-cli", "ee-offline-queue"));
-  });
-
-  it("returns path under homeOverride when provided", () => {
-    const result = getQueueDir("/tmp/test");
-    expect(result).toBe(path.join("/tmp/test", ".muonroi-cli", "ee-offline-queue"));
-  });
-});
-
-// ─── Test 5: drainQueue() replays entries in FIFO order ───────────────────────
-
-describe("drainQueueAsync()", () => {
-  it("replays entries in FIFO order and deletes them after success", async () => {
-    // Pre-populate 3 entries with distinct timestamps
-    await populateQueue(3, 1000);
-
-    const stub = await startStubEEServer({ feedback: () => {} });
-
-    try {
-      await drainQueueAsync(fetch, { "Content-Type": "application/json" }, `http://127.0.0.1:${stub.port}`, tmpDir);
-
-      // 3 requests received in order
-      expect(stub.calls.feedback).toHaveLength(3);
-      expect(stub.calls.feedback[0].enqueuedAt ?? stub.calls.feedback[0].i).toBeDefined();
-
-      // FIFO: first enqueued (ts=1000) should come first
-      const receivedEnqueuedAts = stub.calls.feedback.map((b: any) => b.enqueuedAt ?? b.i);
-      expect(receivedEnqueuedAts[0]).toBeLessThan(receivedEnqueuedAts[1]);
-      expect(receivedEnqueuedAts[1]).toBeLessThan(receivedEnqueuedAts[2]);
-
-      // All files deleted after successful replay
-      const remainingFiles = await readdir(queueDir()).catch(() => []);
-      expect(remainingFiles).toHaveLength(0);
-    } finally {
-      await stub.stop();
-    }
-  });
-
-  // ─── Test 6: drainQueue() stops on failure, leaves remaining ──────────────
-
-  it("stops on 2nd entry failure and leaves 2nd + 3rd entries on disk", async () => {
-    await populateQueue(3, 1000);
-
-    let _callCount = 0;
-    const stub = await startStubEEServer({
-      feedback: () => {
-        _callCount++;
-      },
-    });
-
-    // Override the server to return 500 on 2nd call
-    // We'll track calls and use a custom stub that serves 500 on 2nd request
-    await stub.stop();
-
-    // Build a minimal stub that returns 500 on 2nd POST to /api/feedback
-    const { createServer } = await import("node:http");
-    let reqCount = 0;
-    const customServer = createServer((req, res) => {
-      if (req.url === "/api/feedback" && req.method === "POST") {
-        reqCount++;
-        const chunks: Buffer[] = [];
-        req.on("data", (c: Buffer) => chunks.push(c));
-        req.on("end", () => {
-          if (reqCount === 2) {
-            res.writeHead(500);
-            res.end("error");
-          } else {
-            res.writeHead(200);
-            res.end("ok");
-          }
-        });
-      } else {
-        res.writeHead(404);
-        res.end();
-      }
-    });
-
-    await new Promise<void>((resolve) => customServer.listen(0, "127.0.0.1", () => resolve()));
-    const addr = customServer.address();
-    const port = typeof addr === "object" && addr ? (addr as { port: number }).port : 0;
-
-    try {
-      await drainQueueAsync(fetch, { "Content-Type": "application/json" }, `http://127.0.0.1:${port}`, tmpDir);
-
-      // 1st success, 2nd failure → should have made 2 requests total
-      expect(reqCount).toBe(2);
-
-      // 2nd and 3rd files remain on disk (1st was deleted on success)
-      const remainingFiles = await readdir(queueDir());
-      expect(remainingFiles).toHaveLength(2);
-    } finally {
-      await new Promise<void>((resolve) => customServer.close(() => resolve()));
-    }
-  });
-
-  // ─── Test 7: drainQueue() handles non-existent queue directory ────────────
-
-  it("returns cleanly when queue directory does not exist", async () => {
-    // No queue dir created — just call drainQueueAsync with a fresh tmpDir
-    await expect(
-      drainQueueAsync(fetch, { "Content-Type": "application/json" }, "http://127.0.0.1:9999", tmpDir),
-    ).resolves.toBeUndefined();
-  });
-
-  // ─── Test 8: drainQueue() discards corrupt JSON files ─────────────────────
-
-  it("discards corrupt JSON files and replays valid entries after them", async () => {
-    const dir = queueDir();
-    await mkdir(dir, { recursive: true });
-
-    // Write corrupt file first (older timestamp)
-    const corruptFile = "1000-bad1.json";
-    await writeFile(path.join(dir, corruptFile), "NOT VALID JSON {{{{", "utf8");
-
-    // Write valid entry after (newer timestamp)
-    const validEntry = {
-      endpoint: "/api/feedback",
-      body: { valid: true },
-      enqueuedAt: 2000,
-    };
-    await writeFile(path.join(dir, "2000-good.json"), JSON.stringify(validEntry), "utf8");
-
-    const stub = await startStubEEServer({ feedback: () => {} });
-
-    try {
-      await drainQueueAsync(fetch, { "Content-Type": "application/json" }, `http://127.0.0.1:${stub.port}`, tmpDir);
-
-      // Corrupt file should be deleted
-      const remaining = await readdir(dir);
-      expect(remaining).not.toContain(corruptFile);
-
-      // Valid entry should have been replayed
-      expect(stub.calls.feedback).toHaveLength(1);
-      expect(stub.calls.feedback[0]).toEqual(validEntry.body);
-
-      // Valid file should be deleted after replay
-      expect(remaining).toHaveLength(0);
-    } finally {
-      await stub.stop();
-    }
-  });
-});
-
-// ─── Test 10: drainQueue() is fire-and-forget ─────────────────────────────────
-
-describe("drainQueue() fire-and-forget wrapper", () => {
-  it("returns void (undefined), not a Promise", () => {
-    // Call drainQueue (the fire-and-forget wrapper) — should return undefined immediately
-    const result = drainQueue(fetch, { "Content-Type": "application/json" }, "http://127.0.0.1:9999", tmpDir);
-
-    // drainQueue() must return void (undefined), not a Promise
-    expect(result).toBeUndefined();
-  });
-});

package/src/ee/offline-queue.ts

@@ -1,205 +0,0 @@
-/**
- * Offline queue module for Experience Engine write operations.
- *
- * Persists failed EE requests (feedback, extract, prompt-stale) to disk so they
- * survive process restarts and are replayed when EE recovers.
- *
- * Design decisions (from CONTEXT.md):
- *  - D-01: One JSON file per entry in ~/.muonroi-cli/ee-offline-queue/
- *  - D-02: Timestamp-based filenames for natural FIFO ordering
- *  - D-03: Each entry stores endpoint, body, enqueuedAt
- *  - D-04: Cap at 100 entries; oldest deleted before writing new
- *  - D-08: drainQueue() is fire-and-forget (returns void)
- *  - D-11: Queue directory created lazily on first enqueue
- *
- * NO imports from client.ts or intercept.ts (prevents circular deps).
- * fetchImpl and headers are passed as parameters.
- */
-import { promises as fs } from "node:fs";
-import * as os from "node:os";
-import * as path from "node:path";
-
-// ─── Constants ────────────────────────────────────────────────────────────────
-
-const MAX_QUEUE_SIZE = 100;
-const QUEUE_DIR_NAME = "ee-offline-queue";
-
-// ─── Types ────────────────────────────────────────────────────────────────────
-
-/** Queue entry shape — self-contained, no external type deps. */
-export interface QueueEntry {
-  endpoint: string; // e.g. "/api/feedback", "/api/extract", "/api/prompt-stale"
-  body: unknown; // original request payload verbatim
-  enqueuedAt: number; // Date.now() at enqueue time
-}
-
-// ─── Path helpers ─────────────────────────────────────────────────────────────
-
-/**
- * Returns the absolute path to the offline queue directory.
- * Consistent with auth.ts homeOverride pattern.
- */
-export function getQueueDir(homeOverride?: string): string {
-  return path.join(homeOverride ?? os.homedir(), ".muonroi-cli", QUEUE_DIR_NAME);
-}
-
-// ─── Internal helpers ─────────────────────────────────────────────────────────
-
-/**
- * Generate a unique filename for a new queue entry.
- * Format: `{Date.now()}-{random4}.json` (D-02)
- * The timestamp prefix ensures natural FIFO ordering on readdir + sort.
- */
-function makeFilename(): string {
-  const ts = Date.now();
-  const rnd = Math.random().toString(36).slice(2, 6);
-  return `${ts}-${rnd}.json`;
-}
-
-/**
- * Returns sorted list of .json filenames in the queue directory.
- * Lexicographic sort on timestamp-prefixed names = chronological FIFO order.
- *
- * Throws ENOENT if directory does not exist — callers handle this.
- */
-async function getSortedFiles(dir: string): Promise<string[]> {
-  const entries = await fs.readdir(dir);
-  return entries.filter((f) => f.endsWith(".json")).sort();
-}
-
-// ─── Public API ───────────────────────────────────────────────────────────────
-
-/**
- * Persists a failed EE request to the local queue.
- *
- * Creates queue directory lazily (D-11).
- * Enforces MAX_QUEUE_SIZE cap by deleting oldest entry (D-04).
- */
-export async function enqueue(entry: QueueEntry, homeOverride?: string): Promise<void> {
-  const dir = getQueueDir(homeOverride);
-
-  // D-11: lazy init — create dir only when needed
-  await fs.mkdir(dir, { recursive: true });
-
-  const files = await getSortedFiles(dir);
-
-  // D-04: cap enforcement — drop oldest before writing new
-  if (files.length >= MAX_QUEUE_SIZE) {
-    await fs.unlink(path.join(dir, files[0])).catch(() => {
-      /* ignore if already gone */
-    });
-  }
-
-  const filename = makeFilename();
-  await fs.writeFile(path.join(dir, filename), JSON.stringify(entry), "utf8");
-
-  if (process.env.MUONROI_DEBUG) {
-    console.debug("[muonroi-cli] EE offline queue: enqueued %s (cap=%d)", entry.endpoint, MAX_QUEUE_SIZE);
-  }
-}
-
-/**
- * Internal async implementation shared by drainQueue (fire-and-forget)
- * and drainQueueAsync (awaitable, for tests).
- *
- * Sequential replay (D-06):
- *  - Reads sorted queue files in FIFO order
- *  - POSTs each entry to baseUrl + entry.endpoint
- *  - Deletes file on HTTP success (resp.ok)
- *  - Discards corrupt (unparseable) files silently
- *  - Stops on HTTP failure or network error (D-07) — leaves file + remaining
- *
- * D-11: If queue directory doesn't exist yet, returns early (no error).
- */
-async function drainQueueInternal(
-  fetchImpl: typeof fetch,
-  headers: Record<string, string>,
-  baseUrl: string,
-  homeOverride?: string,
-): Promise<void> {
-  const dir = getQueueDir(homeOverride);
-
-  let files: string[];
-  try {
-    files = await getSortedFiles(dir);
-  } catch {
-    // ENOENT — queue dir never created (no entries ever queued). Normal path.
-    return;
-  }
-
-  for (const file of files) {
-    const filePath = path.join(dir, file);
-
-    // Parse entry — discard corrupt files
-    let entry: QueueEntry;
-    try {
-      const raw = await fs.readFile(filePath, "utf8");
-      entry = JSON.parse(raw) as QueueEntry;
-    } catch {
-      // Corrupt JSON — delete silently and continue
-      await fs.unlink(filePath).catch(() => {});
-      continue;
-    }
-
-    // Replay the entry
-    try {
-      const resp = await fetchImpl(`${baseUrl}${entry.endpoint}`, {
-        method: "POST",
-        headers,
-        body: JSON.stringify(entry.body),
-        signal: AbortSignal.timeout(5000),
-      });
-
-      if (resp.ok) {
-        // Success — delete file and continue to next
-        await fs.unlink(filePath).catch(() => {});
-
-        if (process.env.MUONROI_DEBUG) {
-          console.debug("[muonroi-cli] EE offline queue: replayed %s", entry.endpoint);
-        }
-      } else {
-        // D-07: server returned error — stop drain, leave file + remaining
-        break;
-      }
-    } catch {
-      // D-07: network failure — stop drain, leave file + remaining
-      break;
-    }
-  }
-}
-
-/**
- * Replays queued EE requests in FIFO order.
- *
- * Fire-and-forget wrapper (D-08) — returns void immediately.
- * The caller (recordCircuitSuccess in client.ts) must NOT await this.
- *
- * @param fetchImpl - fetch implementation (injectable for tests)
- * @param headers   - HTTP headers to include (Content-Type + optional auth)
- * @param baseUrl   - EE base URL (e.g. "http://localhost:8082")
- * @param homeOverride - Optional home dir override (for tests)
- */
-export function drainQueue(
-  fetchImpl: typeof fetch,
-  headers: Record<string, string>,
-  baseUrl: string,
-  homeOverride?: string,
-): void {
-  // D-08: fire-and-forget — the returned Promise is intentionally not awaited
-  void drainQueueInternal(fetchImpl, headers, baseUrl, homeOverride);
-}
-
-/**
- * Awaitable version of drainQueue — for tests only.
- *
- * Production code must use drainQueue() (void).
- * Tests use drainQueueAsync() to await completion before asserting.
- */
-export async function drainQueueAsync(
-  fetchImpl: typeof fetch,
-  headers: Record<string, string>,
-  baseUrl: string,
-  homeOverride?: string,
-): Promise<void> {
-  await drainQueueInternal(fetchImpl, headers, baseUrl, homeOverride);
-}

package/src/ee/phase-outcome.test.ts

@@ -1,107 +0,0 @@
-import { afterEach, beforeEach, describe, expect, it } from "vitest";
-import {
-  _resetPhaseOutcomeState,
-  fireAndForgetPhaseOutcome,
-  firePhaseOutcome,
-  type PhaseOutcomePayload,
-} from "./phase-outcome.js";
-
-function makeStubFetch(handler: (url: string, init: RequestInit) => Promise<Response> | Response) {
-  return (input: string | URL | Request, init?: RequestInit) => {
-    const url = typeof input === "string" ? input : input.toString();
-    return Promise.resolve(handler(url, init ?? {}));
-  };
-}
-
-const samplePayload: PhaseOutcomePayload = {
-  sessionId: "sid-1",
-  phaseName: "implement",
-  outcome: "pass",
-  toolEventIds: [{ collection: "code", pointId: "p1" }],
-};
-
-describe("firePhaseOutcome", () => {
-  beforeEach(() => _resetPhaseOutcomeState());
-  afterEach(() => _resetPhaseOutcomeState());
-
-  it("posts to /api/phase-outcome with JSON body and returns parsed result", async () => {
-    let receivedUrl = "";
-    let receivedBody = "";
-    const stubFetch = makeStubFetch(async (url, init) => {
-      receivedUrl = url;
-      receivedBody = String(init.body ?? "");
-      return new Response(JSON.stringify({ ok: true, applied: 1, skipped: 0 }), {
-        status: 200,
-        headers: { "Content-Type": "application/json" },
-      });
-    });
-    const result = await firePhaseOutcome(samplePayload, {
-      baseUrl: "http://x:1",
-      fetchImpl: stubFetch as typeof fetch,
-    });
-    expect(receivedUrl).toBe("http://x:1/api/phase-outcome");
-    expect(JSON.parse(receivedBody).sessionId).toBe("sid-1");
-    expect(result).toEqual({ ok: true, applied: 1, skipped: 0 });
-  });
-
-  it("returns null when server responds 404 (endpoint disabled)", async () => {
-    const stubFetch = makeStubFetch(async () => new Response("not found", { status: 404 }));
-    const result = await firePhaseOutcome(samplePayload, {
-      fetchImpl: stubFetch as typeof fetch,
-    });
-    expect(result).toBeNull();
-  });
-
-  it("returns null and warns once on non-404 error", async () => {
-    const warnings: string[] = [];
-    const origWarn = console.warn;
-    console.warn = (msg: string) => warnings.push(msg);
-    try {
-      const stubFetch = makeStubFetch(async () => new Response("boom", { status: 500 }));
-      const r1 = await firePhaseOutcome(samplePayload, {
-        fetchImpl: stubFetch as typeof fetch,
-      });
-      const r2 = await firePhaseOutcome(samplePayload, {
-        fetchImpl: stubFetch as typeof fetch,
-      });
-      expect(r1).toBeNull();
-      expect(r2).toBeNull();
-      expect(warnings.length).toBe(1);
-    } finally {
-      console.warn = origWarn;
-    }
-  });
-
-  it("returns null on network error", async () => {
-    const stubFetch = (() => Promise.reject(new Error("network down"))) as unknown as typeof fetch;
-    const result = await firePhaseOutcome(samplePayload, {
-      fetchImpl: stubFetch,
-    });
-    expect(result).toBeNull();
-  });
-
-  it("includes Authorization header when authToken provided", async () => {
-    let authHeader: string | null = null;
-    const stubFetch = makeStubFetch(async (_url, init) => {
-      const headers = init.headers as Record<string, string>;
-      authHeader = headers.Authorization;
-      return new Response(JSON.stringify({ ok: true }), { status: 200 });
-    });
-    await firePhaseOutcome(samplePayload, {
-      fetchImpl: stubFetch as typeof fetch,
-      authToken: "secret-token",
-    });
-    expect(authHeader).toBe("Bearer secret-token");
-  });
-});
-
-describe("fireAndForgetPhaseOutcome", () => {
-  beforeEach(() => _resetPhaseOutcomeState());
-
-  it("does not throw on rejection", () => {
-    const stubFetch = (() => Promise.reject(new Error("nope"))) as unknown as typeof fetch;
-    expect(() => {
-      fireAndForgetPhaseOutcome(samplePayload, { fetchImpl: stubFetch });
-    }).not.toThrow();
-  });
-});