@aria-cli/tools 1.0.9 → 1.0.11

package/src/utils/retry.ts

@@ -1,163 +0,0 @@
-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

@@ -1,176 +0,0 @@
-/**
- * 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

@@ -1,20 +0,0 @@
-/**
- * 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

@@ -1,57 +0,0 @@
-/**
- * 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

@@ -1,147 +0,0 @@
-/**
- * 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");
-  });
-});