@aria-cli/tools 1.0.0

package/tests/integration/quest-round-trip.test.ts

@@ -0,0 +1,303 @@
+/**
+ * Integration tests for the quest system — round-trip through executors
+ *
+ * Tests create → list → update → filter flows through executeQuestUpdate and
+ * executeQuestList with a mock QuestStore that stores data in memory.
+ */
+
+import { describe, it, expect, beforeEach, vi } from "vitest";
+import type {
+  ToolContext,
+  QuestStoreRef,
+  QuestStoreItem,
+  QuestStoreStatus,
+} from "../../src/types.js";
+import {
+  executeQuestUpdate,
+  executeQuestList,
+  type QuestUpdateOutput,
+  type QuestListOutput,
+} from "../../src/executors/meta.js";
+
+// ─── In-memory QuestStore mock ──────────────────────────────────
+
+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;
+    }),
+  };
+};
+
+// ─── Helpers ─────────────────────────────────────────────────────
+
+function createContext(questStore: QuestStoreRef): ToolContext {
+  return {
+    workingDir: "/tmp/test",
+    env: {},
+    confirm: async () => true,
+    questStore,
+  };
+}
+
+// ─── Tests ───────────────────────────────────────────────────────
+
+describe("Quest round-trip integration", () => {
+  let questStore: ReturnType<typeof createMockQuestStore>;
+  let ctx: ToolContext;
+
+  beforeEach(() => {
+    questStore = createMockQuestStore();
+    ctx = createContext(questStore);
+  });
+
+  it("create a quest → list it → verify it appears", async () => {
+    // Create
+    const createResult = await executeQuestUpdate(
+      {
+        quests: [{ title: "Fix authentication bug", status: "open" }],
+      },
+      ctx,
+    );
+
+    expect(createResult.success).toBe(true);
+    const createData = createResult.data as QuestUpdateOutput;
+    expect(createData.quests).toHaveLength(1);
+    expect(createData.quests[0]!.action).toBe("created");
+    const questId = createData.quests[0]!.id;
+
+    // List
+    const listResult = await executeQuestList({}, ctx);
+
+    expect(listResult.success).toBe(true);
+    const listData = listResult.data as QuestListOutput;
+    expect(listData.count).toBeGreaterThanOrEqual(1);
+
+    const found = listData.quests.find((q) => q.id === questId);
+    expect(found).toBeDefined();
+    expect(found!.status).toBe("open");
+  });
+
+  it("create quest → update status → list filtered → verify filter works", async () => {
+    // Create two quests
+    const createResult = await executeQuestUpdate(
+      {
+        quests: [
+          { title: "Task A", status: "open" },
+          { title: "Task B", status: "open" },
+        ],
+      },
+      ctx,
+    );
+
+    expect(createResult.success).toBe(true);
+    const createData = createResult.data as QuestUpdateOutput;
+    const idA = createData.quests[0]!.id;
+
+    // Update Task A to active
+    const updateResult = await executeQuestUpdate(
+      {
+        quests: [{ id: idA, title: "Task A", status: "active" }],
+      },
+      ctx,
+    );
+
+    expect(updateResult.success).toBe(true);
+    const updateData = updateResult.data as QuestUpdateOutput;
+    expect(updateData.quests[0]!.action).toBe("updated");
+
+    // List only active quests
+    const listResult = await executeQuestList({ status: "active" }, ctx);
+
+    expect(listResult.success).toBe(true);
+    const listData = listResult.data as QuestListOutput;
+    // Should find Task A (active) but not Task B (open)
+    expect(listData.count).toBe(1);
+    expect(listData.quests[0]!.id).toBe(idA);
+    expect(listData.quests[0]!.status).toBe("active");
+  });
+
+  it("create quest → complete it → list with status filter", async () => {
+    // Create
+    const createResult = await executeQuestUpdate(
+      {
+        quests: [{ title: "Deploy to staging", status: "open" }],
+      },
+      ctx,
+    );
+
+    const createData = createResult.data as QuestUpdateOutput;
+    const questId = createData.quests[0]!.id;
+
+    // Complete it
+    const completeResult = await executeQuestUpdate(
+      {
+        quests: [{ id: questId, title: "Deploy to staging", status: "done" }],
+      },
+      ctx,
+    );
+
+    expect(completeResult.success).toBe(true);
+
+    // List done quests
+    const listDone = await executeQuestList({ status: "done" }, ctx);
+    expect(listDone.success).toBe(true);
+    const doneData = listDone.data as QuestListOutput;
+    expect(doneData.count).toBe(1);
+    expect(doneData.quests[0]!.id).toBe(questId);
+    expect(doneData.quests[0]!.status).toBe("done");
+
+    // List open quests — should NOT include the done quest
+    const listOpen = await executeQuestList({ status: "open" }, ctx);
+    expect(listOpen.success).toBe(true);
+    const openData = listOpen.data as QuestListOutput;
+    const stillOpen = openData.quests.find((q) => q.id === questId);
+    expect(stillOpen).toBeUndefined();
+  });
+
+  it("all quests are visible regardless of creation order", async () => {
+    await executeQuestUpdate(
+      {
+        quests: [{ title: "Quest 1", status: "open" }],
+      },
+      ctx,
+    );
+
+    await executeQuestUpdate(
+      {
+        quests: [{ title: "Quest 2", status: "active" }],
+      },
+      ctx,
+    );
+
+    // Both quests should be retrievable
+    const listResult = await executeQuestList({}, ctx);
+    expect(listResult.success).toBe(true);
+    const listData = listResult.data as QuestListOutput;
+    expect(listData.count).toBe(2);
+
+    const titles = listData.quests.map((q) => q.title);
+    expect(titles).toContain("Quest 1");
+    expect(titles).toContain("Quest 2");
+  });
+
+  it("partial update — status only, title preserved", async () => {
+    // Create a quest
+    const createResult = await executeQuestUpdate(
+      {
+        quests: [{ title: "Important task", status: "open", notes: "Initial notes" }],
+      },
+      ctx,
+    );
+
+    const createData = createResult.data as QuestUpdateOutput;
+    const questId = createData.quests[0]!.id;
+
+    // Update only status — no title or notes
+    const updateResult = await executeQuestUpdate(
+      {
+        quests: [{ id: questId, status: "active" }],
+      },
+      ctx,
+    );
+
+    expect(updateResult.success).toBe(true);
+    const updateData = updateResult.data as QuestUpdateOutput;
+    expect(updateData.quests[0]!.action).toBe("updated");
+    expect(updateData.quests[0]!.title).toBe("Important task"); // preserved
+
+    // List and verify all fields preserved
+    const listResult = await executeQuestList({}, ctx);
+    const listData = listResult.data as QuestListOutput;
+    const quest = listData.quests.find((q) => q.id === questId);
+    expect(quest).toBeDefined();
+    expect(quest!.title).toBe("Important task");
+    expect(quest!.status).toBe("active");
+    expect(quest!.notes).toBe("Initial notes"); // preserved
+  });
+
+  it("quest with notes and blockedBy round-trips correctly", async () => {
+    const createResult = await executeQuestUpdate(
+      {
+        quests: [
+          {
+            title: "Investigate flaky tests",
+            status: "blocked",
+            blocked_by: "quest_xyz",
+            notes: "Waiting on CI fix",
+          },
+        ],
+      },
+      ctx,
+    );
+
+    expect(createResult.success).toBe(true);
+    const createData = createResult.data as QuestUpdateOutput;
+    const questId = createData.quests[0]!.id;
+
+    const listResult = await executeQuestList({}, ctx);
+    expect(listResult.success).toBe(true);
+    const listData = listResult.data as QuestListOutput;
+
+    const quest = listData.quests.find((q) => q.id === questId);
+    expect(quest).toBeDefined();
+    expect(quest!.status).toBe("blocked");
+    expect(quest!.blocked_by).toBe("quest_xyz");
+    expect(quest!.notes).toBe("Waiting on CI fix");
+  });
+});

package/tests/integration/registry-executor-flow.test.ts

@@ -0,0 +1,85 @@
+import { describe, it, expect, beforeEach, afterEach } from "vitest";
+import { createToolRegistry } from "../../src/index.js";
+import type { ToolRegistry, ToolContext } from "../../src/types.js";
+import * as fs from "node:fs/promises";
+import * as path from "node:path";
+import * as os from "node:os";
+
+describe("Tool Registry→Executor Integration", () => {
+  let registry: ToolRegistry;
+  let tempDir: string;
+  let mockContext: ToolContext;
+
+  beforeEach(async () => {
+    tempDir = await fs.mkdtemp(path.join(os.tmpdir(), "registry-test-"));
+    mockContext = {
+      workingDir: tempDir,
+      env: {},
+      confirm: async () => true,
+    };
+    registry = createToolRegistry();
+  });
+
+  afterEach(async () => {
+    await fs.rm(tempDir, { recursive: true, force: true }).catch(() => {});
+  });
+
+  it("should execute read_file tool through registry", async () => {
+    const testFile = path.join(tempDir, "test.txt");
+    await fs.writeFile(testFile, "Hello from registry test");
+
+    const tool = registry.get("read_file");
+    expect(tool).toBeDefined();
+    expect(tool!.name).toBe("read_file");
+
+    const result = await tool!.execute({ path: "test.txt" }, mockContext);
+
+    expect(result.success).toBe(true);
+    expect(result.data).toBe("Hello from registry test");
+  });
+
+  it("should execute write_file tool through registry", async () => {
+    const tool = registry.get("write_file");
+    expect(tool).toBeDefined();
+
+    const result = await tool!.execute(
+      { path: "output.txt", content: "Written via registry" },
+      mockContext,
+    );
+
+    expect(result.success).toBe(true);
+
+    const writtenContent = await fs.readFile(
+      path.join(tempDir, "output.txt"),
+      "utf-8",
+    );
+    expect(writtenContent).toBe("Written via registry");
+  });
+
+  it("should execute bash tool through registry", async () => {
+    const tool = registry.get("bash");
+    expect(tool).toBeDefined();
+
+    const result = await tool!.execute(
+      { command: "echo 'Registry test'" },
+      mockContext,
+    );
+
+    expect(result.success).toBe(true);
+    const data = result.data as { stdout: string };
+    expect(data.stdout).toMatch(/Registry test/);
+  });
+
+  it("should return undefined for non-existent tool", () => {
+    const tool = registry.get("nonexistent_tool");
+    expect(tool).toBeUndefined();
+  });
+
+  it("should list all registered tools", () => {
+    const tools = registry.list();
+    expect(tools.length).toBeGreaterThan(0);
+    expect(tools.map((t) => t.name)).toContain("read_file");
+    expect(tools.map((t) => t.name)).toContain("write_file");
+    expect(tools.map((t) => t.name)).toContain("bash");
+  });
+});

package/tests/integration.test.ts

@@ -0,0 +1,177 @@
+// packages/tools/tests/integration.test.ts
+import { describe, it, expect, beforeEach, afterEach } from "vitest";
+import { mkdir, rm, writeFile } from "fs/promises";
+import { join } from "path";
+import { tmpdir } from "os";
+import {
+  ToolRegistry,
+  createToolRegistry,
+  getCoreTools,
+  getCoreTool,
+  executeReadFile,
+  executeBash,
+  PTYSession,
+  createPTYSession,
+  SpawnedProcessRegistry,
+} from "../src/index.js";
+import type { ToolContext } from "../src/index.js";
+
+// Check if PTY is available in this environment
+let ptyAvailable = true;
+try {
+  const nodePty = await import("node-pty");
+  const testPty = nodePty.spawn("/bin/echo", ["test"]);
+  testPty.kill();
+} catch {
+  ptyAvailable = false;
+}
+
+describe("@aria/tools Integration", () => {
+  let testDir: string;
+  let ctx: ToolContext;
+
+  beforeEach(async () => {
+    testDir = join(tmpdir(), `aria-tools-int-${Date.now()}`);
+    await mkdir(testDir, { recursive: true });
+    ctx = { workingDir: testDir, env: {}, confirm: async () => true };
+  });
+
+  afterEach(async () => {
+    await rm(testDir, { recursive: true, force: true });
+  });
+
+  describe("Complete workflow", () => {
+    it("should register core tools and execute them", async () => {
+      const registry = new ToolRegistry();
+
+      // Register all core tools
+      for (const tool of getCoreTools()) {
+        registry.register(tool);
+      }
+
+      expect(registry.size).toBe(getCoreTools().length);
+
+      // Use read_file tool
+      const filePath = join(testDir, "test.txt");
+      await writeFile(filePath, "Hello from integration test");
+
+      const readTool = registry.get("read_file");
+      expect(readTool).toBeDefined();
+
+      const result = await readTool!.execute({ path: filePath }, ctx);
+      expect(result.success).toBe(true);
+      expect(result.data).toBe("Hello from integration test");
+    });
+
+    it("should search for tools", async () => {
+      const registry = new ToolRegistry();
+
+      for (const tool of getCoreTools()) {
+        registry.register(tool);
+      }
+
+      const fileTools = registry.search("file");
+      expect(fileTools.length).toBeGreaterThan(0);
+
+      const shellTools = registry.list("shell");
+      expect(shellTools).toHaveLength(
+        getCoreTools().filter((tool) => tool.category === "shell").length,
+      );
+    });
+
+    it("should directly use executors", async () => {
+      const filePath = join(testDir, "direct.txt");
+      await writeFile(filePath, "Direct access");
+
+      const result = await executeReadFile({ path: filePath }, ctx);
+      expect(result.success).toBe(true);
+      expect(result.data).toBe("Direct access");
+    });
+
+    it("should wire shell process observability tools through definitions", async () => {
+      const processRegistry = new SpawnedProcessRegistry();
+      const ctxWithRegistry: ToolContext = {
+        ...ctx,
+        processRegistry,
+      };
+
+      const spawnTool = getCoreTool("spawn");
+      const listTool = getCoreTool("list_processes");
+      const waitTool = getCoreTool("wait_process");
+
+      expect(spawnTool).toBeDefined();
+      expect(listTool).toBeDefined();
+      expect(waitTool).toBeDefined();
+
+      const spawned = await spawnTool!.execute({ program: "sleep", args: ["1"] }, ctxWithRegistry);
+      expect(spawned.success).toBe(true);
+      const { pid } = spawned.data as { pid: number };
+
+      const listed = await listTool!.execute({}, ctxWithRegistry);
+      expect(listed.success).toBe(true);
+      expect(listed.data).toMatchObject({
+        processes: expect.arrayContaining([expect.objectContaining({ pid, status: "running" })]),
+      });
+
+      const waited = await waitTool!.execute({ pid, timeoutMs: 3_000 }, ctxWithRegistry);
+      expect(waited.success).toBe(true);
+      expect(waited.data).toMatchObject({
+        pid,
+        exited: true,
+        timedOut: false,
+      });
+    });
+
+    it.skipIf(!ptyAvailable)("should run interactive PTY sessions", async () => {
+      const session = await createPTYSession({
+        command: "echo",
+        args: ["PTY works"],
+        cwd: testDir,
+      });
+
+      const output = await session.waitForExit();
+      expect(output).toContain("PTY works");
+
+      session.close();
+    });
+  });
+
+  describe("Exports", () => {
+    it("should export all necessary types", async () => {
+      // These imports should all work
+      const {
+        ToolRegistry,
+        getCoreTools,
+        getCoreTool,
+        getCoreToolsByCategory,
+        getCoreToolsByRiskLevel,
+        CORE_TOOL_DEFINITIONS,
+        executeReadFile,
+        executeWriteFile,
+        executeBash,
+        executeExec,
+        PTYSession,
+        createPTYSession,
+        runInPTY,
+      } = await import("../src/index.js");
+
+      expect(ToolRegistry).toBeDefined();
+      expect(getCoreTools).toBeDefined();
+      expect(executeReadFile).toBeDefined();
+      expect(PTYSession).toBeDefined();
+    });
+  });
+
+  describe("createToolRegistry", () => {
+    it("should create registry with builtins by default", () => {
+      const registry = createToolRegistry();
+      expect(registry.size).toBeGreaterThan(0);
+      expect(registry.has("read_file")).toBe(true);
+    });
+
+    it("should create empty registry when includeBuiltins is false", () => {
+      const registry = createToolRegistry({ includeBuiltins: false });
+      expect(registry.size).toBe(0);
+    });
+  });
+});

package/tests/loading-tier.test.ts

@@ -0,0 +1,126 @@
+/**
+ * Tests for loadingTier field on Tool type.
+ *
+ * loadingTier determines which tools are sent to the LLM on every request
+ * ("always") vs. which are only available via search ("deferred").
+ *
+ * After the aria-c3x refactoring, ALL built-in tools are "always" (no deferred built-ins).
+ * MCP tools may still be deferred, but that is handled by the MCP layer.
+ */
+
+import { describe, it, expect } from "vitest";
+import { z } from "zod";
+import { CORE_TOOL_DEFINITIONS } from "../src/definitions/core.js";
+import { tool } from "../src/tool-factory.js";
+
+describe("loadingTier", () => {
+  describe("Tool interface: all core tools have loadingTier defined", () => {
+    it("every core tool has loadingTier as either 'always' or 'deferred'", () => {
+      expect(CORE_TOOL_DEFINITIONS.length).toBeGreaterThan(0);
+
+      for (const t of CORE_TOOL_DEFINITIONS) {
+        expect(
+          (t as Record<string, unknown>).loadingTier,
+          `Tool "${t.name}" should have loadingTier defined`,
+        ).toBeDefined();
+
+        expect(
+          ["always", "deferred"],
+          `Tool "${t.name}" should have loadingTier of "always" or "deferred"`,
+        ).toContain((t as Record<string, unknown>).loadingTier);
+      }
+    });
+  });
+
+  describe("All built-in tools are always-on or explicitly deferred", () => {
+    const ALLOWED_DEFERRED = new Set(["session_history", "self_diagnose"]);
+    it("every core tool has loadingTier === 'always' except explicitly deferred tools", () => {
+      for (const t of CORE_TOOL_DEFINITIONS) {
+        if (ALLOWED_DEFERRED.has(t.name)) {
+          expect(
+            (t as Record<string, unknown>).loadingTier,
+            `Tool "${t.name}" should have loadingTier === "deferred"`,
+          ).toBe("deferred");
+        } else {
+          expect(
+            (t as Record<string, unknown>).loadingTier,
+            `Tool "${t.name}" should have loadingTier === "always"`,
+          ).toBe("always");
+        }
+      }
+    });
+  });
+
+  describe("requiresConfirmation tools", () => {
+    it("forget and kill have requiresConfirmation: true", () => {
+      const forgetTool = CORE_TOOL_DEFINITIONS.find((t) => t.name === "forget");
+      const killTool = CORE_TOOL_DEFINITIONS.find((t) => t.name === "kill");
+
+      expect(forgetTool).toBeDefined();
+      expect(killTool).toBeDefined();
+      expect(forgetTool!.requiresConfirmation).toBe(true);
+      expect(killTool!.requiresConfirmation).toBe(true);
+    });
+
+    it("apply_patch has requiresConfirmation: true", () => {
+      const applyPatch = CORE_TOOL_DEFINITIONS.find((t) => t.name === "apply_patch");
+      expect(applyPatch).toBeDefined();
+      expect(applyPatch!.requiresConfirmation).toBe(true);
+    });
+
+    it("bash has requiresConfirmation: true", () => {
+      const bash = CORE_TOOL_DEFINITIONS.find((t) => t.name === "bash");
+      expect(bash).toBeDefined();
+      expect(bash!.requiresConfirmation).toBe(true);
+    });
+  });
+
+  describe("Tool factory", () => {
+    it("sets loadingTier when specified", () => {
+      const t = tool({
+        name: "test_deferred_tool",
+        description: "A test tool with deferred loading",
+        parameters: z.object({ input: z.string() }),
+        execute: async () => ({ success: true, message: "ok" }),
+        loadingTier: "deferred",
+      } as Parameters<typeof tool>[0] & { loadingTier: "deferred" });
+
+      expect(
+        (t as Record<string, unknown>).loadingTier,
+        "Tool created with loadingTier: 'deferred' should have that value on the result",
+      ).toBe("deferred");
+    });
+
+    it("defaults loadingTier to 'always' when not specified", () => {
+      const t = tool({
+        name: "test_default_tool",
+        description: "A test tool without explicit loadingTier",
+        parameters: z.object({ input: z.string() }),
+        execute: async () => ({ success: true, message: "ok" }),
+      });
+
+      expect(
+        (t as Record<string, unknown>).loadingTier,
+        "Tool created without loadingTier should default to 'always'",
+      ).toBe("always");
+    });
+  });
+
+  describe("Total core tools split", () => {
+    it("62 always + 2 deferred = 64 total core tools", () => {
+      // Verify total count
+      expect(CORE_TOOL_DEFINITIONS.length).toBe(64);
+
+      const alwaysTools = CORE_TOOL_DEFINITIONS.filter(
+        (t) => (t as Record<string, unknown>).loadingTier === "always",
+      );
+      const deferredTools = CORE_TOOL_DEFINITIONS.filter(
+        (t) => (t as Record<string, unknown>).loadingTier === "deferred",
+      );
+
+      expect(alwaysTools.length).toBe(62);
+      expect(deferredTools.length).toBe(2);
+      expect(alwaysTools.length + deferredTools.length).toBe(64);
+    });
+  });
+});