@aria-cli/tools 1.0.0

package/src/utils/retry.ts

@@ -0,0 +1,163 @@
+export interface RetryOptions {
+  maxAttempts?: number;
+  baseDelayMs?: number;
+  maxDelayMs?: number;
+  retryableStatuses?: number[];
+  retryableCodes?: string[];
+  /** Custom fetch function for per-attempt wrappers (e.g., DNS pinning). */
+  fetchFn?: (url: string, init: RequestInit) => Promise<Response>;
+}
+
+function createAbortError(): Error {
+  const err = new Error("AbortError");
+  err.name = "AbortError";
+  return err;
+}
+
+/**
+ * AbortSignal-aware sleep that rejects immediately if the signal fires during the delay.
+ */
+function abortAwareSleep(ms: number, signal?: AbortSignal | null): Promise<void> {
+  if (signal?.aborted) {
+    return Promise.reject(createAbortError());
+  }
+
+  return new Promise<void>((resolve, reject) => {
+    let settled = false;
+    let abortHandler: (() => void) | undefined;
+    const timer = setTimeout(() => {
+      if (settled) return;
+      settled = true;
+      if (signal && abortHandler) {
+        signal.removeEventListener("abort", abortHandler);
+      }
+      resolve();
+    }, ms);
+
+    if (signal) {
+      abortHandler = () => {
+        if (settled) return;
+        settled = true;
+        signal.removeEventListener("abort", abortHandler!);
+        clearTimeout(timer);
+        reject(createAbortError());
+      };
+      signal.addEventListener("abort", abortHandler, { once: true });
+    }
+  });
+}
+
+function isAbortError(err: unknown): boolean {
+  if (!(err instanceof Error)) return false;
+  const domErr = err as DOMException;
+  return domErr.name === "AbortError" || err.message === "AbortError";
+}
+
+function getErrorCode(err: unknown): string | undefined {
+  if (
+    typeof err === "object" &&
+    err !== null &&
+    "code" in err &&
+    typeof (err as { code: unknown }).code === "string"
+  ) {
+    return (err as { code: string }).code;
+  }
+  if (err instanceof Error && err.cause) {
+    const cause = err.cause as { code?: unknown };
+    if (typeof cause.code === "string") {
+      return cause.code;
+    }
+  }
+  return undefined;
+}
+
+export async function fetchWithRetry(
+  url: string,
+  init: RequestInit,
+  options?: RetryOptions,
+): Promise<Response> {
+  const maxAttempts = options?.maxAttempts ?? 3;
+  const baseDelayMs = options?.baseDelayMs ?? 1000;
+  const maxDelayMs = options?.maxDelayMs ?? 30000;
+  const retryableStatuses = options?.retryableStatuses ?? [429, 500, 502, 503, 504];
+  const retryableCodes = options?.retryableCodes ?? [
+    "ECONNRESET",
+    "ETIMEDOUT",
+    "EPIPE",
+    "ENETUNREACH",
+    "EHOSTUNREACH",
+    "ECONNREFUSED",
+    "EAI_AGAIN",
+    "UND_ERR_CONNECT_TIMEOUT",
+    "UND_ERR_SOCKET",
+  ];
+  const doFetch = options?.fetchFn ?? fetch;
+  const signal = init.signal ?? null;
+
+  if (signal?.aborted) {
+    throw createAbortError();
+  }
+
+  let lastError: Error | undefined;
+
+  for (let attempt = 0; attempt < maxAttempts; attempt++) {
+    try {
+      const response = await doFetch(url, init);
+
+      // Check for Cloudflare 403 challenge
+      if (response.status === 403 && response.headers.get("cf-mitigated") === "challenge") {
+        if (attempt < maxAttempts - 1) {
+          // Retry with simplified UA
+          const delay = Math.min(baseDelayMs * 2 ** attempt + Math.random() * 500, maxDelayMs);
+          await abortAwareSleep(delay, signal);
+          continue;
+        }
+        // Last attempt - throw
+        throw new Error(`Cloudflare challenge after ${maxAttempts} attempts: ${response.status}`);
+      }
+
+      // Check for retryable status codes
+      if (!response.ok && retryableStatuses.includes(response.status)) {
+        if (attempt < maxAttempts - 1) {
+          const delay = Math.min(baseDelayMs * 2 ** attempt + Math.random() * 500, maxDelayMs);
+          await abortAwareSleep(delay, signal);
+          continue;
+        }
+        // Last attempt - throw
+        throw new Error(`Request failed after ${maxAttempts} attempts: ${response.status}`);
+      }
+
+      return response;
+    } catch (err: unknown) {
+      // Re-throw AbortError immediately — do not retry aborted requests
+      if (isAbortError(err)) {
+        throw err;
+      }
+      const code = getErrorCode(err);
+      if (code && retryableCodes.includes(code) && attempt < maxAttempts - 1) {
+        const delay = Math.min(baseDelayMs * 2 ** attempt + Math.random() * 500, maxDelayMs);
+        await abortAwareSleep(delay, signal);
+        continue;
+      }
+      lastError = err as Error;
+      throw err;
+    }
+  }
+
+  throw lastError ?? new Error("fetchWithRetry: unreachable");
+}
+
+export async function fetchWithSsrf(
+  url: string,
+  init: RequestInit,
+  retryOptions?: RetryOptions,
+): Promise<Response> {
+  const { fetchWithDnsPinning } = await import("../security/dns-pinning.js");
+
+  return fetchWithRetry(url, init, {
+    ...retryOptions,
+    fetchFn: async (attemptUrl: string, attemptInit: RequestInit) => {
+      return fetchWithDnsPinning(attemptUrl, attemptInit);
+    },
+  });
+}

package/src/utils/safe-parse-json.ts

@@ -0,0 +1,176 @@
+/**
+ * Safe JSON extraction and parsing utilities for LLM output.
+ *
+ * Handles code fences, preamble text, bare JSON, and validates against Zod schemas.
+ * NEVER throws -- always returns a typed Result.
+ */
+
+import type { ZodType } from "zod";
+
+export type JsonParseResult<T> =
+  | { ok: true; data: T }
+  | { ok: false; reason: "no_json" | "parse_error" | "schema_mismatch"; raw: string };
+
+const MAX_SCAN_CHARS = 12_000;
+const MAX_JSON_CANDIDATES = 16;
+
+function isJsonRootStart(char: string | undefined): boolean {
+  return char === "{" || char === "[";
+}
+
+/**
+ * Find the end index of a balanced JSON root (object/array) starting at `start`.
+ * Returns -1 when no balanced root can be found.
+ */
+function findBalancedJsonEnd(input: string, start: number): number {
+  if (start < 0 || start >= input.length) return -1;
+  const first = input[start];
+  if (!isJsonRootStart(first)) return -1;
+
+  const stack: string[] = [];
+  let inString = false;
+  let escaped = false;
+
+  for (let i = start; i < input.length; i++) {
+    const char = input[i];
+    if (!char) continue;
+
+    if (inString) {
+      if (escaped) {
+        escaped = false;
+        continue;
+      }
+      if (char === "\\") {
+        escaped = true;
+        continue;
+      }
+      if (char === '"') {
+        inString = false;
+      }
+      continue;
+    }
+
+    if (char === '"') {
+      inString = true;
+      continue;
+    }
+
+    if (char === "{" || char === "[") {
+      stack.push(char);
+      continue;
+    }
+
+    if (char === "}" || char === "]") {
+      const opener = stack.pop();
+      if (!opener) return -1;
+      if ((opener === "{" && char !== "}") || (opener === "[" && char !== "]")) {
+        return -1;
+      }
+      if (stack.length === 0) {
+        return i;
+      }
+    }
+  }
+
+  return -1;
+}
+
+function collectJsonCandidates(raw: string): string[] {
+  const trimmed = raw.trim();
+  if (!trimmed) return [];
+
+  const seen = new Set<string>();
+  const candidates: string[] = [];
+  const add = (candidate: string) => {
+    if (candidates.length >= MAX_JSON_CANDIDATES) return;
+    const value = candidate.trim();
+    if (!value || !isJsonRootStart(value[0] ?? "")) return;
+    if (seen.has(value)) return;
+    seen.add(value);
+    candidates.push(value);
+  };
+
+  const collectFromText = (text: string) => {
+    const bounded = text.slice(0, MAX_SCAN_CHARS);
+    for (let i = 0; i < bounded.length && candidates.length < MAX_JSON_CANDIDATES; i++) {
+      const char = bounded[i];
+      if (!char || !isJsonRootStart(char)) continue;
+      const end = findBalancedJsonEnd(bounded, i);
+      if (end === -1) continue;
+      add(bounded.slice(i, end + 1));
+      i = end;
+    }
+  };
+
+  // 1) Prefer explicit code-fence blocks first.
+  const fenceRegex = /```(?:json|JSON)?\s*\n?([\s\S]*?)```/g;
+  for (const match of trimmed.matchAll(fenceRegex)) {
+    const fenced = match[1]?.trim();
+    if (!fenced) continue;
+    if (isJsonRootStart(fenced[0] ?? "")) {
+      add(fenced);
+    } else {
+      collectFromText(fenced);
+    }
+    if (candidates.length >= MAX_JSON_CANDIDATES) break;
+  }
+
+  // 2) Full-text scan (handles preamble + trailing text + multiple snippets).
+  if (candidates.length < MAX_JSON_CANDIDATES) {
+    if (isJsonRootStart(trimmed[0] ?? "")) {
+      add(trimmed);
+    }
+    collectFromText(trimmed);
+  }
+
+  return candidates;
+}
+
+/**
+ * Extract JSON substring from LLM output.
+ * Returns the first candidate found by robust balanced scanning.
+ */
+export function extractJson(raw: string): string | null {
+  return collectJsonCandidates(raw)[0] ?? null;
+}
+
+/**
+ * Safely extract and parse JSON from LLM output with Zod validation.
+ * Handles code fences, preamble text, bare JSON.
+ * NEVER throws -- always returns a typed Result.
+ */
+export function safeParseJson<T>(raw: string, schema: ZodType<T>): JsonParseResult<T> {
+  const candidates = collectJsonCandidates(raw);
+  if (candidates.length === 0) {
+    return { ok: false, reason: "no_json", raw };
+  }
+
+  let parseErrorRaw: string | null = null;
+  let schemaMismatchRaw: string | null = null;
+
+  for (const jsonStr of candidates) {
+    let parsed: unknown;
+    try {
+      parsed = JSON.parse(jsonStr);
+    } catch {
+      parseErrorRaw = jsonStr;
+      continue;
+    }
+
+    const validated = schema.safeParse(parsed);
+    if (validated.success) {
+      return { ok: true, data: validated.data };
+    }
+
+    schemaMismatchRaw = jsonStr;
+  }
+
+  if (schemaMismatchRaw) {
+    return { ok: false, reason: "schema_mismatch", raw: schemaMismatchRaw };
+  }
+  if (parseErrorRaw) {
+    return { ok: false, reason: "parse_error", raw: parseErrorRaw };
+  }
+
+  return { ok: false, reason: "no_json", raw };
+}

package/src/utils/url.ts

@@ -0,0 +1,20 @@
+/**
+ * Convert GitHub blob URLs to raw.githubusercontent.com URLs.
+ * GitHub blob URLs return HTML wrappers; raw URLs return actual file content.
+ */
+export function normalizeGitHubUrl(url: string): string {
+  const match = url.match(/^https?:\/\/github\.com\/([^/]+)\/([^/]+)\/blob\/(.+)$/);
+  if (match) {
+    return `https://raw.githubusercontent.com/${match[1]}/${match[2]}/${match[3]}`;
+  }
+  return url;
+}
+
+/**
+ * Get configurable User-Agent string.
+ * Reads from ARIA_USER_AGENT env var, falls back to default.
+ */
+export function getUserAgent(): string {
+  const DEFAULT_UA = `Mozilla/5.0 (compatible; ARIA/1.0.0; +https://github.com/aria)`;
+  return process.env.ARIA_USER_AGENT ?? DEFAULT_UA;
+}

package/tests/benchmarks/registry.bench.ts

@@ -0,0 +1,57 @@
+/**
+ * ToolRegistry performance benchmarks.
+ *
+ * Measures core registry operations: registration, lookup, listing,
+ * and tool info generation under realistic load.
+ */
+import { bench, describe } from "vitest";
+import { ToolRegistry } from "../../src/registry/registry.js";
+import type { Tool } from "../../src/types.js";
+
+function createMockTool(name: string): Tool {
+  return {
+    name,
+    description: `Mock tool ${name} for benchmarking`,
+    parameters: {
+      type: "object" as const,
+      properties: {
+        input: { type: "string", description: "Input parameter" },
+      },
+      required: ["input"],
+    },
+    execute: async () => ({ success: true, message: "ok" }),
+  };
+}
+
+// ── Setup: registry with 50 tools ─────────────────────────────────
+const registry = new ToolRegistry();
+for (let i = 0; i < 50; i++) {
+  registry.register(createMockTool(`tool_${i}`));
+}
+
+describe("ToolRegistry lookup", () => {
+  bench("get() existing tool", () => {
+    registry.get("tool_25");
+  });
+
+  bench("get() non-existent tool", () => {
+    registry.get("nonexistent_tool");
+  });
+
+  bench("getAll() with 50 tools", () => {
+    registry.getAll();
+  });
+});
+
+describe("ToolRegistry registration", () => {
+  bench("register() new tool", () => {
+    const reg = new ToolRegistry();
+    reg.register(createMockTool("bench_tool"));
+  });
+});
+
+describe("ToolRegistry info", () => {
+  bench("getToolInfos() with 50 tools", () => {
+    registry.getToolInfos();
+  });
+});

package/tests/cache/web-cache.test.ts

@@ -0,0 +1,147 @@
+/**
+ * TDD RED phase tests for WebCache
+ *
+ * WebCache is an in-memory LRU cache with TTL expiration.
+ * All tests MUST fail because get/set throw "not implemented".
+ */
+
+import { describe, it, expect, beforeEach, afterEach, vi } from "vitest";
+import { WebCache } from "../../src/cache/web-cache.js";
+
+describe("WebCache", () => {
+  beforeEach(() => {
+    vi.useFakeTimers();
+  });
+
+  afterEach(() => {
+    vi.useRealTimers();
+  });
+
+  it("get/set basic operations — set a key, get returns the value", () => {
+    const cache = new WebCache<string>();
+
+    cache.set("greeting", "hello");
+    const result = cache.get("greeting");
+
+    expect(result).toBe("hello");
+  });
+
+  it("TTL expiration — get returns undefined after TTL elapses", () => {
+    const ttlMs = 5000;
+    const cache = new WebCache<string>(100, ttlMs);
+
+    cache.set("ephemeral", "value");
+
+    // Still valid before TTL
+    vi.advanceTimersByTime(ttlMs - 1);
+    expect(cache.get("ephemeral")).toBe("value");
+
+    // Expired after TTL
+    vi.advanceTimersByTime(2);
+    expect(cache.get("ephemeral")).toBeUndefined();
+  });
+
+  it("LRU eviction — oldest entry evicted when maxEntries exceeded", () => {
+    const cache = new WebCache<string>(2);
+
+    cache.set("first", "1");
+    cache.set("second", "2");
+    cache.set("third", "3"); // Should evict "first"
+
+    expect(cache.get("first")).toBeUndefined();
+    expect(cache.get("second")).toBe("2");
+    expect(cache.get("third")).toBe("3");
+  });
+
+  it("access refresh — get refreshes LRU order so accessed entry survives eviction", () => {
+    const cache = new WebCache<string>(2);
+
+    cache.set("first", "1");
+    cache.set("second", "2");
+
+    // Access "first" to refresh its position (now "second" is least-recently-used)
+    cache.get("first");
+
+    // Adding "fourth" should evict "second" (LRU), not "first" (recently accessed)
+    cache.set("fourth", "4");
+
+    expect(cache.get("first")).toBe("1");
+    expect(cache.get("second")).toBeUndefined();
+    expect(cache.get("fourth")).toBe("4");
+  });
+
+  it("separate caches don't collide — same key in different instances", () => {
+    const cacheA = new WebCache<string>();
+    const cacheB = new WebCache<number>();
+
+    cacheA.set("key", "stringValue");
+    cacheB.set("key", 42);
+
+    expect(cacheA.get("key")).toBe("stringValue");
+    expect(cacheB.get("key")).toBe(42);
+  });
+
+  it("expired entries cleaned up on get — doesn't count toward maxEntries", () => {
+    const ttlMs = 1000;
+    const cache = new WebCache<string>(2, ttlMs);
+
+    cache.set("willExpire", "gone");
+
+    // Advance past TTL so "willExpire" is expired
+    vi.advanceTimersByTime(ttlMs + 1);
+
+    // Confirm it's gone
+    expect(cache.get("willExpire")).toBeUndefined();
+
+    // Now set two new entries — should succeed without eviction issues
+    // because the expired entry was cleaned up and doesn't count
+    cache.set("new1", "a");
+    cache.set("new2", "b");
+
+    expect(cache.get("new1")).toBe("a");
+    expect(cache.get("new2")).toBe("b");
+  });
+
+  it("evictExpired — proactively removes expired entries without requiring get()", () => {
+    const ttlMs = 1000;
+    const cache = new WebCache<string>(100, ttlMs);
+
+    // Add some entries
+    cache.set("a", "1");
+    cache.set("b", "2");
+    cache.set("c", "3");
+
+    expect(cache.size).toBe(3);
+
+    // Advance past TTL so all entries are expired
+    vi.advanceTimersByTime(ttlMs + 1);
+
+    // Without evictExpired, the entries still exist in the map
+    // (they'd only be cleaned up lazily on get())
+    // Call evictExpired to proactively sweep them
+    cache.evictExpired();
+
+    expect(cache.size).toBe(0);
+  });
+
+  it("evictExpired — only removes expired entries, keeps valid ones", () => {
+    const ttlMs = 5000;
+    const cache = new WebCache<string>(100, ttlMs);
+
+    cache.set("old", "will-expire");
+
+    // Advance 3s — not yet expired
+    vi.advanceTimersByTime(3000);
+
+    cache.set("fresh", "still-valid");
+
+    // Advance 3s more — "old" is now 6s old (expired), "fresh" is 3s old (valid)
+    vi.advanceTimersByTime(3000);
+
+    cache.evictExpired();
+
+    expect(cache.size).toBe(1);
+    expect(cache.get("old")).toBeUndefined();
+    expect(cache.get("fresh")).toBe("still-valid");
+  });
+});