@aria-cli/tools 1.0.0

package/tests/executors/meta.test.ts

@@ -0,0 +1,683 @@
+/**
+ * @aria/tools - Meta executor tests
+ *
+ * Tests for ask_user, quest_update, and quest_list executors.
+ */
+
+import { describe, it, expect, beforeEach, vi } from "vitest";
+import type {
+  ToolContext,
+  QuestStoreRef,
+  QuestStoreItem,
+  QuestStoreStatus,
+} from "../../src/types.js";
+import {
+  executeAskUser,
+  executeQuestUpdate,
+  executeQuestList,
+  resetAskUserCounter,
+} from "../../src/executors/meta.js";
+
+// Helper to create a mock QuestStore
+const createMockQuestStore = (): QuestStoreRef & { _quests: Map<string, QuestStoreItem> } => {
+  const quests = new Map<string, QuestStoreItem>();
+  return {
+    _quests: quests,
+    createQuest: vi.fn(
+      (input: {
+        id: string;
+        title: string;
+        description?: string;
+        priority?: number;
+        status?: QuestStoreStatus;
+        progress?: string;
+        blockedBy?: string;
+      }) => {
+        const now = Date.now();
+        const quest: QuestStoreItem = {
+          id: input.id,
+          title: input.title,
+          description: input.description,
+          priority: input.priority ?? 2,
+          status: input.status ?? "open",
+          progress: input.progress ?? "",
+          blockedBy: input.blockedBy,
+          attempts: 0,
+          createdAt: now,
+          updatedAt: now,
+        };
+        quests.set(input.id, quest);
+        return quest;
+      },
+    ),
+    updateQuest: vi.fn(
+      (
+        id: string,
+        updates: Partial<{
+          title: string;
+          description: string;
+          priority: number;
+          status: QuestStoreStatus;
+          progress: string;
+          blockedBy: string;
+        }>,
+      ) => {
+        const existing = quests.get(id);
+        if (!existing) throw new Error(`Quest not found: ${id}`);
+        // Match real QuestStore behavior: only apply non-undefined fields
+        const updated: QuestStoreItem = { ...existing, updatedAt: Date.now() };
+        for (const [key, value] of Object.entries(updates)) {
+          if (value !== undefined) (updated as Record<string, unknown>)[key] = value;
+        }
+        quests.set(id, updated);
+        return updated;
+      },
+    ),
+    getQuest: vi.fn((id: string) => quests.get(id) ?? null),
+    listQuests: vi.fn((filter?: { status?: string }) => {
+      const all = Array.from(quests.values());
+      if (filter?.status) return all.filter((q) => q.status === filter.status);
+      return all;
+    }),
+  };
+};
+
+// Helper to create a base context
+const createContext = (overrides?: Partial<ToolContext>): ToolContext => ({
+  workingDir: "/test/dir",
+  env: {},
+  confirm: async () => true,
+  ...overrides,
+});
+
+describe("Meta Executors", () => {
+  describe("executeAskUser", () => {
+    beforeEach(() => {
+      resetAskUserCounter();
+    });
+
+    it("returns answers when userInteraction is wired", async () => {
+      const mockAsk = vi.fn().mockResolvedValue([{ answer: "yes" }, { answer: "blue" }]);
+      const ctx = createContext({
+        userInteraction: { ask: mockAsk },
+      });
+
+      const result = await executeAskUser(
+        {
+          questions: [
+            { question: "Continue?", options: ["yes", "no"] },
+            { question: "Favorite color?" },
+          ],
+        },
+        ctx,
+      );
+
+      expect(result.success).toBe(true);
+      expect(result.message).toContain("2 answers");
+      expect((result.data as { answers: unknown[] }).answers).toHaveLength(2);
+      expect(mockAsk).toHaveBeenCalledWith([
+        { question: "Continue?", options: ["yes", "no"] },
+        { question: "Favorite color?" },
+      ]);
+    });
+
+    it("returns graceful error when userInteraction is not wired", async () => {
+      const ctx = createContext(); // no userInteraction
+
+      const result = await executeAskUser({ questions: [{ question: "Hello?" }] }, ctx);
+
+      expect(result.success).toBe(false);
+      expect(result.message).toContain("not available");
+    });
+
+    it("rate limits: 4th call returns error (max 3 per turn)", async () => {
+      const mockAsk = vi.fn().mockResolvedValue([{ answer: "ok" }]);
+      const ctx = createContext({
+        userInteraction: { ask: mockAsk },
+      });
+
+      const input = { questions: [{ question: "test?" }] };
+
+      // First 3 calls succeed
+      const r1 = await executeAskUser(input, ctx);
+      expect(r1.success).toBe(true);
+
+      const r2 = await executeAskUser(input, ctx);
+      expect(r2.success).toBe(true);
+
+      const r3 = await executeAskUser(input, ctx);
+      expect(r3.success).toBe(true);
+
+      // 4th call is rate-limited
+      const r4 = await executeAskUser(input, ctx);
+      expect(r4.success).toBe(false);
+      expect(r4.message).toContain("Rate limit");
+      expect(r4.message).toContain("3");
+    });
+
+    it("rejects empty questions array", async () => {
+      const ctx = createContext({
+        userInteraction: { ask: vi.fn() },
+      });
+
+      const result = await executeAskUser({ questions: [] }, ctx);
+
+      expect(result.success).toBe(false);
+      expect(result.message).toContain("required");
+    });
+
+    it("handles abort signal", async () => {
+      const controller = new AbortController();
+      controller.abort();
+      const ctx = createContext({
+        userInteraction: { ask: vi.fn() },
+        abortSignal: controller.signal,
+      });
+
+      const result = await executeAskUser({ questions: [{ question: "test?" }] }, ctx);
+
+      expect(result.success).toBe(false);
+      expect(result.message).toContain("cancelled");
+    });
+
+    it("does not burn ask_user quota when answers are exhausted mid-resume", async () => {
+      let invocationCount = 0;
+      const mockAsk = vi.fn(async () => {
+        invocationCount++;
+        if (invocationCount === 1) {
+          const error = new Error("ask_user requested more answers than provided.");
+          Object.assign(error, {
+            code: "ASK_USER_ANSWERS_EXHAUSTED",
+            questions: [{ question: "Choose a deployment region" }],
+          });
+          throw error;
+        }
+
+        return [{ answer: "us-east-1" }];
+      });
+      const askUserCallCounter = { count: 0 };
+      const ctx = createContext({
+        userInteraction: { ask: mockAsk },
+        askUserCallCounter,
+      });
+      const input = { questions: [{ question: "Choose a deployment region" }] };
+
+      await expect(executeAskUser(input, ctx)).rejects.toMatchObject({
+        code: "ASK_USER_ANSWERS_EXHAUSTED",
+      });
+      expect(askUserCallCounter.count).toBe(0);
+
+      const result1 = await executeAskUser(input, ctx);
+      const result2 = await executeAskUser(input, ctx);
+      const result3 = await executeAskUser(input, ctx);
+      const result4 = await executeAskUser(input, ctx);
+
+      expect(result1.success).toBe(true);
+      expect(result2.success).toBe(true);
+      expect(result3.success).toBe(true);
+      expect(result4.success).toBe(false);
+      expect(result4.message).toContain("Rate limit");
+      expect(askUserCallCounter.count).toBe(3);
+      expect(mockAsk).toHaveBeenCalledTimes(4);
+    });
+
+    it("still burns ask_user quota when the prompt attempt fails for non-exhaustion reasons", async () => {
+      const mockAsk = vi.fn(async () => {
+        throw new Error("socket closed");
+      });
+      const askUserCallCounter = { count: 0 };
+      const ctx = createContext({
+        userInteraction: { ask: mockAsk },
+        askUserCallCounter,
+      });
+      const input = { questions: [{ question: "Choose a deployment region" }] };
+
+      const result1 = await executeAskUser(input, ctx);
+      const result2 = await executeAskUser(input, ctx);
+      const result3 = await executeAskUser(input, ctx);
+      const result4 = await executeAskUser(input, ctx);
+
+      expect(result1.success).toBe(false);
+      expect(result1.message).toContain("socket closed");
+      expect(result2.success).toBe(false);
+      expect(result3.success).toBe(false);
+      expect(result4.success).toBe(false);
+      expect(result4.message).toContain("Rate limit");
+      expect(askUserCallCounter.count).toBe(3);
+      expect(mockAsk).toHaveBeenCalledTimes(3);
+    });
+  });
+
+  describe("executeQuestUpdate", () => {
+    let mockQuestStore: ReturnType<typeof createMockQuestStore>;
+
+    beforeEach(() => {
+      mockQuestStore = createMockQuestStore();
+    });
+
+    it("creates a quest with auto-generated ID when no id provided", async () => {
+      const ctx = createContext({ questStore: mockQuestStore });
+
+      const result = await executeQuestUpdate(
+        {
+          quests: [{ title: "Fix the bug", status: "open" }],
+        },
+        ctx,
+      );
+
+      expect(result.success).toBe(true);
+      expect(result.message).toContain("1 created");
+      const data = result.data as { quests: Array<{ id: string; action: string }> };
+      expect(data.quests).toHaveLength(1);
+      expect(data.quests[0]!.id).toMatch(/^quest_/);
+      expect(data.quests[0]!.action).toBe("created");
+      expect(mockQuestStore.createQuest).toHaveBeenCalled();
+    });
+
+    it("updates existing quest when id is provided", async () => {
+      // Pre-seed a quest
+      mockQuestStore.createQuest({
+        id: "quest_abc123",
+        title: "Old title",
+        status: "open",
+      });
+
+      const ctx = createContext({ questStore: mockQuestStore });
+
+      const result = await executeQuestUpdate(
+        {
+          quests: [{ id: "quest_abc123", title: "Updated title", status: "active" }],
+        },
+        ctx,
+      );
+
+      expect(result.success).toBe(true);
+      expect(result.message).toContain("1 updated");
+      const data = result.data as { quests: Array<{ id: string; action: string }> };
+      expect(data.quests[0]!.action).toBe("updated");
+      expect(mockQuestStore.updateQuest).toHaveBeenCalledWith(
+        "quest_abc123",
+        expect.objectContaining({
+          title: "Updated title",
+          status: "active",
+        }),
+      );
+    });
+
+    it("returns error when questStore is not available", async () => {
+      const ctx = createContext(); // no questStore
+
+      const result = await executeQuestUpdate(
+        {
+          quests: [{ title: "No store", status: "open" }],
+        },
+        ctx,
+      );
+
+      expect(result.success).toBe(false);
+      expect(result.message).toContain("QuestStore is not available");
+    });
+
+    it("rejects empty quests array", async () => {
+      const ctx = createContext({ questStore: mockQuestStore });
+
+      const result = await executeQuestUpdate({ quests: [] }, ctx);
+
+      expect(result.success).toBe(false);
+      expect(result.message).toContain("required");
+    });
+
+    it("reports failure when updating non-existent quest", async () => {
+      const ctx = createContext({ questStore: mockQuestStore });
+
+      const result = await executeQuestUpdate(
+        {
+          quests: [{ id: "quest_nonexistent", title: "Ghost", status: "active" }],
+        },
+        ctx,
+      );
+
+      // All quests failed → result is failure
+      expect(result.success).toBe(false);
+      expect(result.message).toContain("failed");
+      const data = result.data as { quests: Array<{ action: string; error?: string }> };
+      expect(data.quests[0]!.action).toBe("failed");
+      expect(data.quests[0]!.error).toContain("Quest not found");
+    });
+
+    it("creates quest with priority and blockedBy", async () => {
+      const ctx = createContext({ questStore: mockQuestStore });
+
+      const result = await executeQuestUpdate(
+        {
+          quests: [
+            {
+              title: "Blocked task",
+              status: "blocked",
+              priority: 1,
+              blocked_by: "quest_xyz",
+            },
+          ],
+        },
+        ctx,
+      );
+
+      expect(result.success).toBe(true);
+      expect(mockQuestStore.createQuest).toHaveBeenCalledWith(
+        expect.objectContaining({
+          title: "Blocked task",
+          status: "blocked",
+          priority: 1,
+          blockedBy: "quest_xyz",
+        }),
+      );
+    });
+
+    // P1-3: Runtime status validation
+    it("rejects invalid status values", async () => {
+      const ctx = createContext({ questStore: mockQuestStore });
+
+      const result = await executeQuestUpdate(
+        {
+          quests: [{ title: "Bad status", status: "invalid_status" as QuestStoreStatus }],
+        },
+        ctx,
+      );
+
+      expect(result.success).toBe(false);
+      expect(result.message).toContain("failed");
+      const data = result.data as { quests: Array<{ action: string; error?: string }> };
+      expect(data.quests[0]!.action).toBe("failed");
+      expect(data.quests[0]!.error).toContain("Invalid status");
+    });
+
+    // P0-2: Mixed batch — some succeed, some fail
+    it("continues processing batch when one quest fails", async () => {
+      const ctx = createContext({ questStore: mockQuestStore });
+
+      const result = await executeQuestUpdate(
+        {
+          quests: [
+            { title: "Good quest", status: "open" },
+            { id: "quest_doesnt_exist", title: "Will fail", status: "active" },
+            { title: "Another good one", status: "open" },
+          ],
+        },
+        ctx,
+      );
+
+      // Partial success — not all failed
+      expect(result.success).toBe(true);
+      expect(result.message).toContain("2 created");
+      expect(result.message).toContain("1 failed");
+      expect(result.message).toContain("partial failure");
+      const data = result.data as {
+        quests: Array<{ action: string; title: string; error?: string }>;
+      };
+      expect(data.quests).toHaveLength(3);
+      expect(data.quests[0]!.action).toBe("created");
+      expect(data.quests[1]!.action).toBe("failed");
+      expect(data.quests[2]!.action).toBe("created");
+    });
+
+    // P0-1: Notes map to progress consistently on create
+    it("maps notes to progress on create", async () => {
+      const ctx = createContext({ questStore: mockQuestStore });
+
+      await executeQuestUpdate(
+        {
+          quests: [{ title: "Quest with notes", status: "open", notes: "Some progress info" }],
+        },
+        ctx,
+      );
+
+      expect(mockQuestStore.createQuest).toHaveBeenCalledWith(
+        expect.objectContaining({
+          progress: "Some progress info",
+        }),
+      );
+      // Should NOT map notes to description
+      const callArg = (mockQuestStore.createQuest as ReturnType<typeof vi.fn>).mock.calls[0][0];
+      expect(callArg.description).toBeUndefined();
+    });
+
+    // P0-1: Notes map to progress consistently on update
+    it("maps notes to progress on update", async () => {
+      mockQuestStore.createQuest({
+        id: "quest_progress",
+        title: "Test quest",
+        status: "open",
+      });
+      const ctx = createContext({ questStore: mockQuestStore });
+
+      await executeQuestUpdate(
+        {
+          quests: [
+            { id: "quest_progress", title: "Test quest", status: "active", notes: "Now active" },
+          ],
+        },
+        ctx,
+      );
+
+      expect(mockQuestStore.updateQuest).toHaveBeenCalledWith(
+        "quest_progress",
+        expect.objectContaining({
+          progress: "Now active",
+        }),
+      );
+    });
+
+    // P1-5: Priority round-trips correctly
+    it("round-trips priority through create → list", async () => {
+      const ctx = createContext({ questStore: mockQuestStore });
+
+      await executeQuestUpdate(
+        {
+          quests: [{ title: "Critical", status: "open", priority: 0 }],
+        },
+        ctx,
+      );
+
+      const listResult = await executeQuestList({}, ctx);
+      const data = listResult.data as { quests: Array<{ priority: number }> };
+      expect(data.quests[0]!.priority).toBe(0);
+    });
+
+    // R4: Create without title fails
+    it("rejects quest creation without title", async () => {
+      const ctx = createContext({ questStore: mockQuestStore });
+
+      const result = await executeQuestUpdate(
+        {
+          quests: [{ status: "open" }],
+        },
+        ctx,
+      );
+
+      expect(result.success).toBe(false);
+      const data = result.data as { quests: Array<{ action: string; error?: string }> };
+      expect(data.quests[0]!.action).toBe("failed");
+      expect(data.quests[0]!.error).toContain("title is required");
+    });
+
+    // R4: Create defaults status to "open" when not specified
+    it("defaults status to open when creating without status", async () => {
+      const ctx = createContext({ questStore: mockQuestStore });
+
+      const result = await executeQuestUpdate(
+        {
+          quests: [{ title: "No status quest" }],
+        },
+        ctx,
+      );
+
+      expect(result.success).toBe(true);
+      const data = result.data as { quests: Array<{ status: string }> };
+      expect(data.quests[0]!.status).toBe("open");
+      expect(mockQuestStore.createQuest).toHaveBeenCalledWith(
+        expect.objectContaining({ status: "open" }),
+      );
+    });
+
+    // R4: Partial update — only status, preserves title
+    it("updates only status without overwriting title", async () => {
+      mockQuestStore.createQuest({
+        id: "quest_partial",
+        title: "Original title",
+        status: "open",
+      });
+      const ctx = createContext({ questStore: mockQuestStore });
+
+      const result = await executeQuestUpdate(
+        {
+          quests: [{ id: "quest_partial", status: "active" }],
+        },
+        ctx,
+      );
+
+      expect(result.success).toBe(true);
+      const data = result.data as { quests: Array<{ title: string; status: string }> };
+      expect(data.quests[0]!.title).toBe("Original title");
+      expect(data.quests[0]!.status).toBe("active");
+      // updateQuest should NOT have title in the updates
+      expect(mockQuestStore.updateQuest).toHaveBeenCalledWith("quest_partial", {
+        status: "active",
+      });
+    });
+
+    // R4: Partial update — only notes, preserves title and status
+    it("updates only notes without overwriting other fields", async () => {
+      mockQuestStore.createQuest({
+        id: "quest_notes_only",
+        title: "Keep this title",
+        status: "active",
+        progress: "Old progress",
+      });
+      const ctx = createContext({ questStore: mockQuestStore });
+
+      const result = await executeQuestUpdate(
+        {
+          quests: [{ id: "quest_notes_only", notes: "New progress" }],
+        },
+        ctx,
+      );
+
+      expect(result.success).toBe(true);
+      // Should only pass progress to updateQuest, not title or status
+      expect(mockQuestStore.updateQuest).toHaveBeenCalledWith("quest_notes_only", {
+        progress: "New progress",
+      });
+      // Title should be preserved from the store
+      const data = result.data as { quests: Array<{ title: string; status: string }> };
+      expect(data.quests[0]!.title).toBe("Keep this title");
+      expect(data.quests[0]!.status).toBe("active");
+    });
+
+    // P1-5: Abort signal for quest update
+    it("handles abort signal", async () => {
+      const controller = new AbortController();
+      controller.abort();
+      const ctx = createContext({
+        questStore: mockQuestStore,
+        abortSignal: controller.signal,
+      });
+
+      const result = await executeQuestUpdate(
+        {
+          quests: [{ title: "Will not run", status: "open" }],
+        },
+        ctx,
+      );
+
+      expect(result.success).toBe(false);
+      expect(result.message).toContain("cancelled");
+    });
+  });
+
+  describe("executeQuestList", () => {
+    let mockQuestStore: ReturnType<typeof createMockQuestStore>;
+
+    beforeEach(() => {
+      mockQuestStore = createMockQuestStore();
+    });
+
+    it("lists quests from QuestStore", async () => {
+      mockQuestStore.createQuest({ id: "quest_a", title: "Fix bug", status: "open" });
+      mockQuestStore.createQuest({ id: "quest_b", title: "Add feature", status: "active" });
+      const ctx = createContext({ questStore: mockQuestStore });
+
+      const result = await executeQuestList({}, ctx);
+
+      expect(result.success).toBe(true);
+      expect(result.message).toContain("2 quests");
+      const data = result.data as { quests: unknown[]; count: number };
+      expect(data.count).toBe(2);
+      expect(data.quests).toHaveLength(2);
+    });
+
+    it("filters by status", async () => {
+      mockQuestStore.createQuest({ id: "quest_a", title: "Fix bug", status: "open" });
+      mockQuestStore.createQuest({ id: "quest_b", title: "Done feature", status: "done" });
+      const ctx = createContext({ questStore: mockQuestStore });
+
+      const result = await executeQuestList({ status: "open" }, ctx);
+
+      expect(result.success).toBe(true);
+      const data = result.data as { quests: Array<{ id: string }>; count: number };
+      expect(data.count).toBe(1);
+      expect(data.quests[0]!.id).toBe("quest_a");
+    });
+
+    it("returns error when questStore is not available", async () => {
+      const ctx = createContext(); // no questStore
+
+      const result = await executeQuestList({}, ctx);
+
+      expect(result.success).toBe(false);
+      expect(result.message).toContain("QuestStore is not available");
+    });
+
+    it("returns empty list when no quests exist", async () => {
+      const ctx = createContext({ questStore: mockQuestStore });
+
+      const result = await executeQuestList({}, ctx);
+
+      expect(result.success).toBe(true);
+      const data = result.data as { quests: unknown[]; count: number };
+      expect(data.count).toBe(0);
+      expect(data.quests).toHaveLength(0);
+    });
+
+    // P1-5: Abort signal for quest list
+    it("handles abort signal", async () => {
+      const controller = new AbortController();
+      controller.abort();
+      const ctx = createContext({
+        questStore: mockQuestStore,
+        abortSignal: controller.signal,
+      });
+
+      const result = await executeQuestList({}, ctx);
+
+      expect(result.success).toBe(false);
+      expect(result.message).toContain("cancelled");
+    });
+
+    // P0-1: Notes from list come from progress, not description
+    it("returns notes from progress field, not description", async () => {
+      mockQuestStore.createQuest({
+        id: "quest_notes",
+        title: "Test",
+        status: "open",
+        description: "Some description",
+        progress: "Actual progress",
+      });
+      const ctx = createContext({ questStore: mockQuestStore });
+
+      const result = await executeQuestList({}, ctx);
+      const data = result.data as { quests: Array<{ notes: string }> };
+      // Notes should come from progress, NOT description
+      expect(data.quests[0]!.notes).toBe("Actual progress");
+    });
+  });
+});