@aria-cli/tools 1.0.0

package/tests/tool-factory.test.ts

@@ -0,0 +1,188 @@
+import { describe, it, expect } from "vitest";
+import { z } from "zod";
+import { tool } from "../src/tool-factory.js";
+import { ToolRegistry } from "../src/registry/index.js";
+
+describe("tool() factory", () => {
+  const weatherSchema = z.object({
+    city: z.string(),
+    units: z.enum(["F", "C"]),
+  });
+
+  it("creates tool with Zod schema, returns object with Tool interface fields", () => {
+    const getWeather = tool({
+      name: "get_weather",
+      description: "Get weather for a city",
+      parameters: weatherSchema,
+      execute: async (input) => ({
+        success: true,
+        message: `Weather in ${input.city}: sunny`,
+      }),
+    });
+
+    expect(getWeather).toHaveProperty("name", "get_weather");
+    expect(getWeather).toHaveProperty("description", "Get weather for a city");
+    expect(getWeather).toHaveProperty("parameters");
+    expect(getWeather).toHaveProperty("riskLevel");
+    expect(getWeather).toHaveProperty("isReadOnly");
+    expect(getWeather).toHaveProperty("category");
+    expect(getWeather).toHaveProperty("execute");
+    expect(typeof getWeather.execute).toBe("function");
+  });
+
+  it("execute receives Zod-parsed typed input", async () => {
+    let receivedInput: unknown = null;
+
+    const getWeather = tool({
+      name: "get_weather",
+      description: "Get weather for a city",
+      parameters: weatherSchema,
+      execute: async (input) => {
+        receivedInput = input;
+        return { success: true, message: "ok" };
+      },
+    });
+
+    const ctx = {
+      workingDir: "/tmp",
+      env: {},
+      confirm: async () => true,
+    };
+
+    await getWeather.execute({ city: "NYC", units: "F" }, ctx);
+
+    expect(receivedInput).toEqual({ city: "NYC", units: "F" });
+    expect((receivedInput as { city: string }).city).toBe("NYC");
+    expect((receivedInput as { units: string }).units).toBe("F");
+  });
+
+  it("rejects invalid input at runtime with ZodError", async () => {
+    const getWeather = tool({
+      name: "get_weather",
+      description: "Get weather for a city",
+      parameters: weatherSchema,
+      execute: async (input) => ({
+        success: true,
+        message: `Weather in ${input.city}`,
+      }),
+    });
+
+    const ctx = {
+      workingDir: "/tmp",
+      env: {},
+      confirm: async () => true,
+    };
+
+    // city should be a string, not a number
+    await expect(getWeather.execute({ city: 123 }, ctx)).rejects.toThrow();
+  });
+
+  it("uses defaults: riskLevel='safe', isReadOnly=true, category='meta'", () => {
+    const t = tool({
+      name: "simple_tool",
+      description: "A simple tool",
+      parameters: z.object({ input: z.string() }),
+      execute: async () => ({ success: true, message: "ok" }),
+    });
+
+    expect(t.riskLevel).toBe("safe");
+    expect(t.isReadOnly).toBe(true);
+    expect(t.category).toBe("meta");
+  });
+
+  it("preserves custom riskLevel, isReadOnly, and category when specified", () => {
+    const t = tool({
+      name: "dangerous_tool",
+      description: "A dangerous tool",
+      parameters: z.object({ target: z.string() }),
+      execute: async () => ({ success: true, message: "done" }),
+      riskLevel: "dangerous",
+      isReadOnly: false,
+      category: "shell",
+    });
+
+    expect(t.riskLevel).toBe("dangerous");
+    expect(t.isReadOnly).toBe(false);
+    expect(t.category).toBe("shell");
+  });
+
+  it("generates valid JSON Schema in the parameters field", () => {
+    const t = tool({
+      name: "schema_tool",
+      description: "Tool with schema",
+      parameters: z.object({
+        city: z.string(),
+        units: z.enum(["F", "C"]),
+      }),
+      execute: async () => ({ success: true, message: "ok" }),
+    });
+
+    const params = t.parameters;
+    expect(params).toHaveProperty("type", "object");
+    expect(params).toHaveProperty("properties");
+
+    const props = (params as { properties: Record<string, unknown> })
+      .properties;
+    expect(props).toHaveProperty("city");
+    expect(props).toHaveProperty("units");
+
+    // required should list the non-optional fields
+    expect(params).toHaveProperty("required");
+    const required = (params as { required: string[] }).required;
+    expect(required).toContain("city");
+    expect(required).toContain("units");
+  });
+
+  it("works with optional parameters", async () => {
+    const optionalSchema = z.object({
+      city: z.string(),
+      units: z.enum(["F", "C"]).optional(),
+    });
+
+    let receivedInput: unknown = null;
+
+    const t = tool({
+      name: "optional_tool",
+      description: "Tool with optional param",
+      parameters: optionalSchema,
+      execute: async (input) => {
+        receivedInput = input;
+        return { success: true, message: "ok" };
+      },
+    });
+
+    const ctx = {
+      workingDir: "/tmp",
+      env: {},
+      confirm: async () => true,
+    };
+
+    // Execute without the optional field
+    await t.execute({ city: "NYC" }, ctx);
+    expect(receivedInput).toEqual({ city: "NYC" });
+
+    // Execute with the optional field
+    await t.execute({ city: "NYC", units: "C" }, ctx);
+    expect(receivedInput).toEqual({ city: "NYC", units: "C" });
+
+    // The JSON Schema should only require 'city', not 'units'
+    const required = (t.parameters as { required?: string[] }).required ?? [];
+    expect(required).toContain("city");
+    expect(required).not.toContain("units");
+  });
+
+  it("can be registered in a ToolRegistry", () => {
+    const t = tool({
+      name: "registry_tool",
+      description: "Tool for registry test",
+      parameters: z.object({ query: z.string() }),
+      execute: async () => ({ success: true, message: "found" }),
+    });
+
+    const registry = new ToolRegistry();
+    registry.register(t);
+
+    expect(registry.has("registry_tool")).toBe(true);
+    expect(registry.get("registry_tool")).toBe(t);
+  });
+});

package/tests/utils/retry.test.ts

@@ -0,0 +1,231 @@
+/**
+ * TDD RED phase tests for fetchWithRetry
+ *
+ * fetchWithRetry wraps fetch with automatic retry logic for transient failures.
+ * All tests MUST fail because fetchWithRetry throws "not implemented".
+ *
+ * NOTE: Tests that exercise retry behavior use a helper that awaits the promise
+ * concurrently with timer advancement, avoiding unhandled rejection warnings
+ * from the stub's immediate throw.
+ */
+
+import { describe, it, expect, beforeEach, afterEach, vi } from "vitest";
+import { fetchWithRetry } from "../../src/utils/retry.js";
+
+describe("fetchWithRetry", () => {
+  let mockFetch: ReturnType<typeof vi.fn>;
+
+  beforeEach(() => {
+    vi.useFakeTimers();
+    mockFetch = vi.fn();
+    vi.stubGlobal("fetch", mockFetch);
+  });
+
+  afterEach(() => {
+    vi.useRealTimers();
+    vi.restoreAllMocks();
+  });
+
+  /** Helper to create a Response-like object */
+  function ok200(body = "ok"): Response {
+    return new Response(body, { status: 200 });
+  }
+
+  function response(status: number, headers?: Record<string, string>): Response {
+    return new Response(null, { status, headers });
+  }
+
+  /**
+   * Helper: run fetchWithRetry and advance fake timers concurrently.
+   * This ensures the promise rejection from the stub is always caught
+   * (avoids "PromiseRejectionHandledWarning" during RED phase).
+   * When the real implementation exists, timers drive the retry delays.
+   */
+  async function fetchAndAdvance(
+    url: string,
+    init: RequestInit,
+    options?: Parameters<typeof fetchWithRetry>[2],
+  ): Promise<Response> {
+    const [res] = await Promise.all([
+      fetchWithRetry(url, init, options),
+      vi.advanceTimersByTimeAsync(60_000),
+    ]);
+    return res;
+  }
+
+  it("success on first attempt — no retry needed", async () => {
+    mockFetch.mockResolvedValueOnce(ok200());
+
+    const res = await fetchWithRetry("https://example.com", {});
+
+    expect(res.status).toBe(200);
+    expect(mockFetch).toHaveBeenCalledTimes(1);
+  });
+
+  it("retry on 429 — succeeds on second attempt", async () => {
+    mockFetch.mockResolvedValueOnce(response(429)).mockResolvedValueOnce(ok200());
+
+    const res = await fetchAndAdvance("https://example.com", {});
+
+    expect(res.status).toBe(200);
+    expect(mockFetch).toHaveBeenCalledTimes(2);
+  });
+
+  it.each([500, 502, 503, 504])("retry on %d — server error triggers retry", async (status) => {
+    mockFetch.mockResolvedValueOnce(response(status)).mockResolvedValueOnce(ok200());
+
+    const res = await fetchAndAdvance("https://example.com", {});
+
+    expect(res.status).toBe(200);
+    expect(mockFetch).toHaveBeenCalledTimes(2);
+  });
+
+  it("retry on ECONNRESET — network error triggers retry", async () => {
+    const err = Object.assign(new Error("connection reset"), { code: "ECONNRESET" });
+    mockFetch.mockRejectedValueOnce(err).mockResolvedValueOnce(ok200());
+
+    const res = await fetchAndAdvance("https://example.com", {});
+
+    expect(res.status).toBe(200);
+    expect(mockFetch).toHaveBeenCalledTimes(2);
+  });
+
+  it("retry on ETIMEDOUT and EPIPE — transient network errors trigger retry", async () => {
+    const etimedout = Object.assign(new Error("timed out"), { code: "ETIMEDOUT" });
+    mockFetch.mockRejectedValueOnce(etimedout).mockResolvedValueOnce(ok200());
+
+    const res1 = await fetchAndAdvance("https://example.com", {});
+    expect(res1.status).toBe(200);
+
+    mockFetch.mockReset();
+
+    const epipe = Object.assign(new Error("broken pipe"), { code: "EPIPE" });
+    mockFetch.mockRejectedValueOnce(epipe).mockResolvedValueOnce(ok200());
+
+    const res2 = await fetchAndAdvance("https://example.com", {});
+    expect(res2.status).toBe(200);
+  });
+
+  it("retry when code is nested under error.cause (undici fetch failed shape)", async () => {
+    const nestedCause = Object.assign(new Error("connect timeout"), {
+      code: "UND_ERR_CONNECT_TIMEOUT",
+    });
+    const wrapped = new TypeError("fetch failed");
+    (wrapped as Error & { cause?: unknown }).cause = nestedCause;
+    mockFetch.mockRejectedValueOnce(wrapped).mockResolvedValueOnce(ok200());
+
+    const res = await fetchAndAdvance("https://example.com", {});
+
+    expect(res.status).toBe(200);
+    expect(mockFetch).toHaveBeenCalledTimes(2);
+  });
+
+  it("ENOTFOUND does NOT retry — throws immediately", async () => {
+    const err = Object.assign(new Error("not found"), { code: "ENOTFOUND" });
+    mockFetch.mockRejectedValueOnce(err);
+
+    await expect(fetchWithRetry("https://nonexistent.invalid", {})).rejects.toThrow("not found");
+    expect(mockFetch).toHaveBeenCalledTimes(1);
+  });
+
+  it("fetchFn callback invoked — custom fetch function used instead of global", async () => {
+    const customFetch = vi.fn().mockResolvedValueOnce(ok200("custom"));
+
+    const res = await fetchWithRetry(
+      "https://example.com",
+      {},
+      {
+        fetchFn: customFetch,
+      },
+    );
+
+    expect(res.status).toBe(200);
+    expect(customFetch).toHaveBeenCalledTimes(1);
+    expect(customFetch).toHaveBeenCalledWith("https://example.com", {});
+    // Global fetch should NOT have been called
+    expect(mockFetch).not.toHaveBeenCalled();
+  });
+
+  it("respect maxAttempts — stops retrying after limit", async () => {
+    mockFetch
+      .mockResolvedValueOnce(response(500))
+      .mockResolvedValueOnce(response(500))
+      .mockResolvedValueOnce(ok200());
+
+    // Should throw after 2 attempts, never reaching the 3rd (200) response
+    await expect(fetchAndAdvance("https://example.com", {}, { maxAttempts: 2 })).rejects.toThrow();
+    expect(mockFetch).toHaveBeenCalledTimes(2);
+  });
+
+  it("Cloudflare detection — 403 with cf-mitigated header triggers retry", async () => {
+    mockFetch
+      .mockResolvedValueOnce(response(403, { "cf-mitigated": "challenge" }))
+      .mockResolvedValueOnce(ok200());
+
+    const res = await fetchAndAdvance("https://example.com", {});
+
+    expect(res.status).toBe(200);
+    expect(mockFetch).toHaveBeenCalledTimes(2);
+  });
+
+  it("jitter produces non-deterministic delays — Math.random is used", async () => {
+    const randomSpy = vi.spyOn(Math, "random").mockReturnValue(0.5);
+
+    mockFetch.mockResolvedValueOnce(response(500)).mockResolvedValueOnce(ok200());
+
+    await fetchAndAdvance("https://example.com", {});
+
+    // Math.random should have been called at least once for jitter calculation
+    expect(randomSpy).toHaveBeenCalled();
+
+    randomSpy.mockRestore();
+  });
+
+  // TDD red: fetchWithRetry's abort-during-delay uses DOMException with message "The operation was aborted"
+  // but test expects error name "AbortError" — vitest toThrow() matches on message, not name
+  it("AbortSignal cancels during retry delay — does not wait for full backoff", async () => {
+    // First attempt returns 500 (retryable), then during the delay the signal aborts
+    mockFetch.mockResolvedValueOnce(response(500)).mockResolvedValueOnce(ok200());
+
+    const controller = new AbortController();
+
+    const fetchPromise = fetchWithRetry(
+      "https://example.com",
+      { signal: controller.signal },
+      { maxAttempts: 3, baseDelayMs: 10_000 },
+    );
+    // Attach rejection handler before timers advance to avoid unhandled rejection noise.
+    const rejection = expect(fetchPromise).rejects.toThrow("AbortError");
+
+    // Abort after a short delay (well before the 10s retry delay would complete)
+    setTimeout(() => controller.abort(), 50);
+
+    // Advance timers just enough to trigger the setTimeout in the test, not the full retry delay
+    await vi.advanceTimersByTimeAsync(100);
+    await rejection;
+
+    // Only 1 attempt should have been made — aborted during the delay before attempt 2
+    expect(mockFetch).toHaveBeenCalledTimes(1);
+  });
+
+  // TDD red: fetchWithRetry doesn't check signal.aborted before first attempt
+  it("AbortSignal already aborted — rejects immediately without fetching", async () => {
+    const controller = new AbortController();
+    controller.abort();
+
+    mockFetch.mockResolvedValueOnce(ok200());
+
+    // When signal is already aborted, the first fetch call will throw because
+    // the AbortSignal is passed through to fetch. The native fetch throws AbortError.
+    mockFetch.mockImplementation((_url: string, init: RequestInit) => {
+      if (init.signal?.aborted) {
+        return Promise.reject(new DOMException("The operation was aborted", "AbortError"));
+      }
+      return Promise.resolve(ok200());
+    });
+
+    await expect(
+      fetchWithRetry("https://example.com", { signal: controller.signal }),
+    ).rejects.toThrow("AbortError");
+  });
+});

package/tests/utils/url.test.ts

@@ -0,0 +1,63 @@
+/**
+ * TDD RED phase tests for URL utilities
+ *
+ * normalizeGitHubUrl converts GitHub blob URLs to raw.githubusercontent.com URLs.
+ * getUserAgent returns a configurable User-Agent string.
+ * All tests MUST fail because stubs throw "not implemented".
+ */
+
+import { describe, it, expect, beforeEach, afterEach } from "vitest";
+import { normalizeGitHubUrl, getUserAgent } from "../../src/utils/url.js";
+
+describe("normalizeGitHubUrl", () => {
+  it("GitHub blob URL converted to raw.githubusercontent.com", () => {
+    const input = "https://github.com/user/repo/blob/main/src/file.ts";
+    const expected = "https://raw.githubusercontent.com/user/repo/main/src/file.ts";
+
+    expect(normalizeGitHubUrl(input)).toBe(expected);
+  });
+
+  it("non-GitHub URLs pass through unchanged", () => {
+    const input = "https://example.com/foo";
+
+    expect(normalizeGitHubUrl(input)).toBe(input);
+  });
+
+  it("GitHub tree URLs NOT converted — only blob URLs are raw-friendly", () => {
+    const input = "https://github.com/user/repo/tree/main/src";
+
+    expect(normalizeGitHubUrl(input)).toBe(input);
+  });
+
+  it("GitHub commit URLs NOT converted", () => {
+    const input = "https://github.com/user/repo/commit/abc123";
+
+    expect(normalizeGitHubUrl(input)).toBe(input);
+  });
+});
+
+describe("getUserAgent", () => {
+  const originalEnv = process.env.ARIA_USER_AGENT;
+
+  afterEach(() => {
+    // Restore original env state
+    if (originalEnv !== undefined) {
+      process.env.ARIA_USER_AGENT = originalEnv;
+    } else {
+      delete process.env.ARIA_USER_AGENT;
+    }
+  });
+
+  it("configurable UA — reads from ARIA_USER_AGENT env var", () => {
+    process.env.ARIA_USER_AGENT = "CustomBot/1.0";
+
+    expect(getUserAgent()).toBe("CustomBot/1.0");
+  });
+
+  it("default UA fallback — returns string containing ARIA when env var is unset", () => {
+    delete process.env.ARIA_USER_AGENT;
+
+    const ua = getUserAgent();
+    expect(ua).toContain("ARIA");
+  });
+});

package/tsconfig.cjs.json

@@ -0,0 +1,16 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": {
+    "composite": true,
+    "module": "CommonJS",
+    "moduleResolution": "Node",
+    "outDir": "./dist-cjs",
+    "rootDir": "./src",
+    "declaration": true,
+    "declarationMap": false,
+    "tsBuildInfoFile": "./dist-cjs/.tsbuildinfo"
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist", "dist-cjs", "tests", "**/*.test.ts", "**/*.test.tsx"],
+  "references": [{ "path": "../types" }]
+}

package/tsconfig.json

@@ -0,0 +1,12 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": {
+    "composite": true,
+    "outDir": "./dist",
+    "tsBuildInfoFile": "./dist/.tsbuildinfo",
+    "rootDir": "./src"
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist", "tests", "**/*.test.ts", "**/*.test.tsx"],
+  "references": [{ "path": "../types" }]
+}

package/vitest.config.ts

@@ -0,0 +1,55 @@
+import { fileURLToPath } from "node:url";
+import { defineConfig } from "vitest/config";
+import {
+  INFRA_EXCLUDES,
+  sharedPoolConfig,
+  workspaceSourceAliases,
+} from "../../vitest.shared.ts";
+import {
+  getToolsTestLaneFileParallelism,
+  getToolsTestLaneFiles,
+  getToolsTestLaneMaxWorkers,
+  getToolsTestLanePool,
+  getToolsTestLaneSetupFiles,
+} from "./tests/test-lane-manifest.ts";
+
+const workspaceRoot = fileURLToPath(new URL("../..", import.meta.url));
+
+export default defineConfig({
+  resolve: {
+    alias: workspaceSourceAliases(workspaceRoot, {
+      "@aria/auth": "packages/auth/src/index.ts",
+      "@aria/models": "packages/models/src/index.ts",
+      "@aria/tools/network-runtime": "packages/tools/src/network-runtime/index.ts",
+      "@aria/tools": "packages/tools/src/index.ts",
+      "@aria/memoria/storage": "packages/memoria/src/storage/index.ts",
+      "@aria/memoria": "packages/memoria/src/index.ts",
+      "@aria/types": "packages/types/src/index.ts",
+    }),
+  },
+  test: {
+    ...sharedPoolConfig,
+    globals: true,
+    environment: "node",
+    include: getToolsTestLaneFiles("unit"),
+    maxWorkers: getToolsTestLaneMaxWorkers("unit"),
+    pool: getToolsTestLanePool("unit"),
+    fileParallelism: getToolsTestLaneFileParallelism("unit"),
+    exclude: INFRA_EXCLUDES,
+    setupFiles: getToolsTestLaneSetupFiles("unit"),
+    testTimeout: 30_000,
+    coverage: {
+      provider: "v8",
+      reporter: ["text", "json", "html"],
+      reportOnFailure: true,
+      include: ["src/**"],
+      exclude: ["**/__tests__/**", "**/test-utils/**", "**/*.test.ts", "**/*.test.tsx"],
+      thresholds: {
+        statements: 77,
+        branches: 71,
+        functions: 68,
+        lines: 78,
+      },
+    },
+  },
+});

package/vitest.e2e.config.ts

@@ -0,0 +1,24 @@
+import { defineConfig } from "vitest/config";
+import { INFRA_EXCLUDES } from "../../vitest.shared.ts";
+import {
+  getToolsTestLaneFileParallelism,
+  getToolsTestLaneFiles,
+  getToolsTestLaneMaxWorkers,
+  getToolsTestLanePool,
+  getToolsTestLaneSetupFiles,
+} from "./tests/test-lane-manifest.ts";
+
+export default defineConfig({
+  test: {
+    globals: true,
+    environment: "node",
+    include: getToolsTestLaneFiles("e2e"),
+    maxWorkers: getToolsTestLaneMaxWorkers("e2e"),
+    pool: getToolsTestLanePool("e2e"),
+    fileParallelism: getToolsTestLaneFileParallelism("e2e"),
+    exclude: INFRA_EXCLUDES,
+    setupFiles: getToolsTestLaneSetupFiles("e2e"),
+    testTimeout: 60_000,
+    hookTimeout: 15_000,
+  },
+});

package/vitest.integration.config.ts

@@ -0,0 +1,24 @@
+import { defineConfig } from "vitest/config";
+import { INFRA_EXCLUDES } from "../../vitest.shared.ts";
+import {
+  getToolsTestLaneFileParallelism,
+  getToolsTestLaneFiles,
+  getToolsTestLaneMaxWorkers,
+  getToolsTestLanePool,
+  getToolsTestLaneSetupFiles,
+} from "./tests/test-lane-manifest.ts";
+
+export default defineConfig({
+  test: {
+    globals: true,
+    environment: "node",
+    include: getToolsTestLaneFiles("integration"),
+    maxWorkers: getToolsTestLaneMaxWorkers("integration"),
+    pool: getToolsTestLanePool("integration"),
+    fileParallelism: getToolsTestLaneFileParallelism("integration"),
+    exclude: INFRA_EXCLUDES,
+    setupFiles: getToolsTestLaneSetupFiles("integration"),
+    testTimeout: 30_000,
+    hookTimeout: 10_000,
+  },
+});

package/vitest.native.config.ts

@@ -0,0 +1,24 @@
+import { defineConfig } from "vitest/config";
+import { INFRA_EXCLUDES } from "../../vitest.shared.ts";
+import {
+  getToolsTestLaneFileParallelism,
+  getToolsTestLaneFiles,
+  getToolsTestLaneMaxWorkers,
+  getToolsTestLanePool,
+  getToolsTestLaneSetupFiles,
+} from "./tests/test-lane-manifest.ts";
+
+export default defineConfig({
+  test: {
+    globals: true,
+    environment: "node",
+    include: getToolsTestLaneFiles("native"),
+    maxWorkers: getToolsTestLaneMaxWorkers("native"),
+    pool: getToolsTestLanePool("native"),
+    fileParallelism: getToolsTestLaneFileParallelism("native"),
+    exclude: INFRA_EXCLUDES,
+    setupFiles: getToolsTestLaneSetupFiles("native"),
+    testTimeout: 30_000,
+    hookTimeout: 10_000,
+  },
+});