@aria-cli/tools 1.0.0

package/tests/executors/write-stdin.test.ts

@@ -0,0 +1,145 @@
+/**
+ * @aria/tools - WriteStdin executor tests
+ *
+ * Tests for the write_stdin tool that sends input to interactive PTY sessions.
+ */
+
+import { describe, it, expect, vi } from "vitest";
+import type { ToolContext, PTYSessionStoreRef } from "../../src/types.js";
+import { executeWriteStdin } from "../../src/executors/shell.js";
+
+// Helper to create a base context
+const createContext = (overrides?: Partial<ToolContext>): ToolContext => ({
+  workingDir: "/test/dir",
+  env: {},
+  confirm: async () => true,
+  ...overrides,
+});
+
+// Helper to create a mock PTY session
+const createMockPTYSession = (overrides?: {
+  isRunning?: boolean;
+  output?: string;
+  exitCode?: number;
+}) => {
+  let _output = overrides?.output ?? "";
+  return {
+    get isRunning() {
+      return overrides?.isRunning ?? true;
+    },
+    get output() {
+      return _output;
+    },
+    get exitCode() {
+      return overrides?.exitCode;
+    },
+    write: vi.fn((data: string) => {
+      // Simulate output appearing after write
+      _output += `echo: ${data}`;
+    }),
+    resize: vi.fn(),
+    pid: 12345,
+  };
+};
+
+// Helper to create a mock PTY session store
+const createMockPTYStore = (
+  sessions: Map<number, ReturnType<typeof createMockPTYSession>>,
+): PTYSessionStoreRef => ({
+  has: (pid: number) => sessions.has(pid),
+  get: (pid: number) => sessions.get(pid),
+});
+
+describe("WriteStdin Executor", () => {
+  it("returns error for PID 0", async () => {
+    const ctx = createContext();
+    const result = await executeWriteStdin({ pid: 0, input: "hello" }, ctx);
+
+    expect(result.success).toBe(false);
+    expect(result.message).toContain("Invalid PID");
+  });
+
+  it("returns error for own process PID", async () => {
+    const ctx = createContext();
+    const result = await executeWriteStdin({ pid: process.pid, input: "hello" }, ctx);
+
+    expect(result.success).toBe(false);
+    expect(result.message).toContain("Cannot write to own process");
+  });
+
+  it("returns error when ptySessionStore is not available", async () => {
+    const ctx = createContext(); // no ptySessionStore
+
+    const result = await executeWriteStdin({ pid: 999, input: "hello" }, ctx);
+
+    expect(result.success).toBe(false);
+    expect(result.message).toContain("PTY session store not available");
+  });
+
+  it("returns error for unknown PID (not in store)", async () => {
+    const sessions = new Map();
+    const ctx = createContext({
+      ptySessionStore: createMockPTYStore(sessions),
+    });
+
+    const result = await executeWriteStdin({ pid: 9999, input: "hello" }, ctx);
+
+    expect(result.success).toBe(false);
+    expect(result.message).toContain("No interactive session found");
+    expect(result.message).toContain("9999");
+  });
+
+  it("writes to session and returns output", async () => {
+    const mockSession = createMockPTYSession();
+    const sessions = new Map<number, ReturnType<typeof createMockPTYSession>>();
+    sessions.set(12345, mockSession);
+    const ctx = createContext({
+      ptySessionStore: createMockPTYStore(sessions),
+    });
+
+    const result = await executeWriteStdin({ pid: 12345, input: "ls\n" }, ctx);
+
+    expect(result.success).toBe(true);
+    expect(result.message).toContain("Wrote");
+    expect(result.message).toContain("12345");
+    expect(mockSession.write).toHaveBeenCalledWith("ls\n");
+    const data = result.data as { output: string };
+    expect(data.output).toContain("echo: ls");
+  });
+
+  it("returns error when session has exited", async () => {
+    const mockSession = createMockPTYSession({ isRunning: false, exitCode: 1 });
+    const sessions = new Map<number, ReturnType<typeof createMockPTYSession>>();
+    sessions.set(42, mockSession);
+    const ctx = createContext({
+      ptySessionStore: createMockPTYStore(sessions),
+    });
+
+    const result = await executeWriteStdin({ pid: 42, input: "hello" }, ctx);
+
+    expect(result.success).toBe(false);
+    expect(result.message).toContain("exited");
+  });
+
+  it("returns error for negative PID", async () => {
+    const ctx = createContext();
+    const result = await executeWriteStdin({ pid: -1, input: "hello" }, ctx);
+
+    expect(result.success).toBe(false);
+    expect(result.message).toContain("Invalid PID");
+  });
+
+  it("returns error when input is not a string", async () => {
+    const mockSession = createMockPTYSession();
+    const sessions = new Map<number, ReturnType<typeof createMockPTYSession>>();
+    sessions.set(100, mockSession);
+    const ctx = createContext({
+      ptySessionStore: createMockPTYStore(sessions),
+    });
+
+    const result = await executeWriteStdin({ pid: 100, input: 123 as unknown as string }, ctx);
+
+    expect(result.success).toBe(false);
+    expect(result.message).toContain("Input must be a string");
+  });
+});

package/tests/extraction/content-extraction.test.ts

@@ -0,0 +1,153 @@
+import { describe, it, expect, vi } from "vitest";
+import {
+  extractContent,
+  extractFromResponse,
+  type ExtractedContent,
+} from "../../src/extraction/content-extraction.js";
+
+describe("extractContent", () => {
+  it("converts article HTML to markdown with isArticle true", async () => {
+    const html = `
+      <html>
+        <head><title>Test Article</title></head>
+        <body>
+          <article>
+            <h1>Main Heading</h1>
+            <p>This is a paragraph with a <a href="https://example.com">link</a>.</p>
+            <p>Code example: <code>console.log("hello")</code></p>
+          </article>
+        </body>
+      </html>
+    `;
+    const result = await extractContent(html, "https://example.com/article");
+
+    expect(result.isArticle).toBe(true);
+    // Markdown heading (Readability demotes h1→h2 for embedded content)
+    expect(result.content).toContain("Main Heading");
+    expect(result.content).toMatch(/^#+\s+Main Heading/m);
+    // Markdown link (Readability may normalize URL with trailing slash)
+    expect(result.content).toMatch(/\[link\]\(https:\/\/example\.com\/?/);
+    // Code preserved
+    expect(result.content).toContain("console.log");
+  });
+
+  it("converts non-article HTML to markdown with isArticle false", async () => {
+    const html = `
+      <html>
+        <head><title>Non Article</title></head>
+        <body>
+          <div>
+            <p>Some content in a div</p>
+            <p>Another paragraph</p>
+          </div>
+        </body>
+      </html>
+    `;
+    const result = await extractContent(html, "https://example.com/page");
+
+    expect(result.isArticle).toBe(false);
+    expect(result.content).toContain("Some content in a div");
+    expect(result.content).toContain("Another paragraph");
+  });
+
+  it("gracefully handles malformed HTML without crashing", async () => {
+    // Verifies regex fallback when Readability can't parse.
+    const result = await extractContent("<malformed", "https://example.com");
+    expect(result).toBeDefined();
+    expect(typeof result.content).toBe("string");
+    expect(result.isArticle).toBe(false);
+  });
+
+  it("extracts title from HTML", async () => {
+    const html = `
+      <html>
+        <head><title>My Page</title></head>
+        <body><p>Content</p></body>
+      </html>
+    `;
+    const result = await extractContent(html, "https://example.com");
+
+    expect(result.title).toBe("My Page");
+  });
+
+  it("truncates content at 50K characters", async () => {
+    const longParagraph = "x".repeat(60_000);
+    const html = `
+      <html>
+        <head><title>Long Page</title></head>
+        <body><p>${longParagraph}</p></body>
+      </html>
+    `;
+    const result = await extractContent(html, "https://example.com/long");
+
+    expect(result.content.length).toBeLessThanOrEqual(50_000);
+  });
+
+  it("returns empty content for empty HTML", async () => {
+    const result = await extractContent("", "https://example.com/empty");
+
+    expect(result.title).toBe("");
+    expect(result.content).toBe("");
+    expect(result.isArticle).toBe(false);
+  });
+
+  it("returns raw content for non-HTML response types", async () => {
+    const raw = '{"status":"ok","payload":"<script>alert(1)</script>"}';
+    const result = await extractFromResponse(raw, "https://example.com/data.json", "application/json");
+
+    expect(result.isArticle).toBe(false);
+    expect(result.title).toBe("");
+    expect(result.content).toBe(raw);
+  });
+
+  it("falls back to default extraction concurrency when env value is invalid", async () => {
+    const original = process.env.ARIA_MAX_CONCURRENT_EXTRACTIONS;
+    process.env.ARIA_MAX_CONCURRENT_EXTRACTIONS = "0";
+
+    try {
+      vi.resetModules();
+      const reloadedModule = await import("../../src/extraction/content-extraction.js");
+
+      const result = await Promise.race<ExtractedContent>([
+        reloadedModule.extractContent("<html><body><p>Hello</p></body></html>", "https://example.com"),
+        new Promise<ExtractedContent>((_resolve, reject) => {
+          setTimeout(() => reject(new Error("extractContent timed out")), 500);
+        }),
+      ]);
+
+      expect(result.content).toContain("Hello");
+    } finally {
+      if (original === undefined) {
+        delete process.env.ARIA_MAX_CONCURRENT_EXTRACTIONS;
+      } else {
+        process.env.ARIA_MAX_CONCURRENT_EXTRACTIONS = original;
+      }
+      vi.resetModules();
+    }
+  });
+
+  it("strips script and style tags from output", async () => {
+    const html = `
+      <html>
+        <head>
+          <title>Clean Page</title>
+          <style>body { color: red; }</style>
+        </head>
+        <body>
+          <script>alert("xss")</script>
+          <p>Visible content only</p>
+          <style>.hidden { display: none; }</style>
+          <script>document.cookie</script>
+        </body>
+      </html>
+    `;
+    const result = await extractContent(html, "https://example.com/clean");
+
+    expect(result.content).toContain("Visible content only");
+    expect(result.content).not.toContain("alert");
+    expect(result.content).not.toContain("xss");
+    expect(result.content).not.toContain("document.cookie");
+    expect(result.content).not.toContain("color: red");
+    expect(result.content).not.toContain("display: none");
+  });
+});

package/tests/guards/tools-default-test-lane.integration.test.ts

@@ -0,0 +1,21 @@
+import config from "../../vitest.config.ts";
+import { describe, expect, it } from "vitest";
+import { loadToolsTestLaneManifest } from "../test-lane-manifest.js";
+
+describe("tools default test lane", () => {
+  it("wires the default vitest config to the unit lane only", () => {
+    const manifest = loadToolsTestLaneManifest();
+    const include = config.test?.include ?? [];
+
+    expect(include).toEqual(manifest.lanes.unit);
+    expect(config.test?.maxWorkers).toBe(manifest.maxWorkers.unit);
+    expect(config.test?.pool).toBe(manifest.pool.unit);
+    expect(config.test?.fileParallelism).toBe(manifest.fileParallelism.unit);
+    expect(include).toContain("tests/guards/tools-test-lane-manifest.contract.test.ts");
+    expect(include).not.toContain("tests/definitions/messaging.test.ts");
+    expect(include).not.toContain("tests/executors/pty.test.ts");
+    expect(include).not.toContain("tests/integration.test.ts");
+    expect(include).not.toContain("tests/executors/shell.test.ts");
+    expect(include).not.toContain("tests/e2e/delegation-quest-orchestration.e2e.test.ts");
+  });
+});

package/tests/guards/tools-package-test-commands.e2e.test.ts

@@ -0,0 +1,43 @@
+import path from "node:path";
+import { describe, expect, it } from "vitest";
+import { execPnpmJsonCommand } from "../../../../scripts/package-test-command-helpers";
+
+const repoRoot = path.resolve(import.meta.dirname, "../../../..");
+
+describe("tools package test commands", () => {
+  it("exposes a package-level list command for the safe default lane", () => {
+    const listing = execPnpmJsonCommand<{ defaultLane: string; files: string[] }>(
+      repoRoot,
+      ["--filter", "@aria/tools", "test:list"],
+      {
+        timeout: 15_000,
+        maxBuffer: 10 * 1024 * 1024,
+      },
+    );
+
+    expect(listing.defaultLane).toBe("unit");
+    expect(listing.files).toContain("tests/guards/tools-test-lane-manifest.contract.test.ts");
+    expect(listing.files).toContain("tests/executors/write-stdin.test.ts");
+    expect(listing.files).not.toContain("tests/definitions/messaging.test.ts");
+    expect(listing.files).not.toContain("tests/executors/pty.test.ts");
+    expect(listing.files).not.toContain("tests/integration.test.ts");
+  }, 30_000);
+
+  it("reports explicit lane counts for the package", () => {
+    const report = execPnpmJsonCommand<{
+      defaultLane: string;
+      counts: Record<string, number>;
+      unclassified: string[];
+    }>(repoRoot, ["--filter", "@aria/tools", "test:lanes"], {
+      timeout: 15_000,
+      maxBuffer: 10 * 1024 * 1024,
+    });
+
+    expect(report.defaultLane).toBe("unit");
+    expect(report.counts.unit).toBeGreaterThan(0);
+    expect(report.counts.integration).toBeGreaterThan(0);
+    expect(report.counts.native).toBeGreaterThan(0);
+    expect(report.counts.e2e).toBeGreaterThan(0);
+    expect(report.unclassified).toEqual([]);
+  }, 30_000);
+});

package/tests/guards/tools-test-lane-manifest.contract.test.ts

@@ -0,0 +1,76 @@
+import { describe, expect, it } from "vitest";
+import {
+  PACKAGE_TEST_AUTHORITY,
+  classifyToolsTestFile,
+  classifyToolsTestPlacement,
+  classifyToolsTestProofClass,
+  loadToolsTestLaneManifest,
+  type ToolsTestLaneId,
+} from "../test-lane-manifest.js";
+
+function expectLane(relativePath: string, expected: ToolsTestLaneId): void {
+  expect(classifyToolsTestFile(relativePath)).toBe(expected);
+}
+
+describe("tools test lane manifest", () => {
+  it("classifies every tools test file into an explicit lane", () => {
+    const manifest = loadToolsTestLaneManifest();
+
+    expect(manifest.defaultLane).toBe("unit");
+    expect(manifest.unclassified).toEqual([]);
+    expect(manifest.unclassifiedProofClasses).toEqual([]);
+    expect(manifest.proofClasses.live).toEqual([]);
+  });
+
+  it("keeps unsafe plain-name suites out of the default unit lane", () => {
+    expectLane("tests/definitions/messaging.test.ts", "native");
+    expectLane("tests/definitions/messaging-inbox-scope.test.ts", "native");
+    expectLane("tests/executors/pty.test.ts", "native");
+    expectLane("tests/executors/shell-tools.test.ts", "native");
+    expectLane("tests/integration.test.ts", "integration");
+    expectLane("tests/executors/shell.test.ts", "integration");
+    expectLane("tests/executors/shell-process-registry.test.ts", "integration");
+    expectLane("tests/executors/shell-abort.test.ts", "integration");
+    expectLane("tests/e2e/delegation-quest-orchestration.e2e.test.ts", "e2e");
+  });
+
+  it("keeps obvious hermetic suites in the bounded unit lane", () => {
+    expectLane("tests/executors/write-stdin.test.ts", "unit");
+    expectLane("tests/registry.test.ts", "unit");
+    expectLane("tests/registry/discovery.test.ts", "unit");
+    expectLane("tests/executors/memory.test.ts", "unit");
+    expectLane("tests/executors/shell-env-blocklist.test.ts", "unit");
+    expectLane("tests/network-runtime/nearby-peer-principal.contract.test.ts", "unit");
+    expect(classifyToolsTestProofClass("tests/registry.test.ts")).toBe("gate");
+    expect(classifyToolsTestPlacement("tests/registry.test.ts")).toMatchObject({
+      lane: "unit",
+      proofClass: "gate",
+      resourceKeys: [],
+    });
+  });
+
+  it("marks the heavier tools lanes as explicit system proof ownership", () => {
+    expect(classifyToolsTestProofClass("tests/executors/pty.test.ts")).toBe("system");
+    expect(classifyToolsTestProofClass("tests/e2e/delegation-quest-orchestration.e2e.test.ts")).toBe(
+      "system",
+    );
+    expect(PACKAGE_TEST_AUTHORITY.getProofClassFiles("system")).toContain(
+      "tests/executors/pty.test.ts",
+    );
+  });
+
+  it("keeps the default tools unit lane parallel-capable while the heavier non-unit lanes stay serialized", () => {
+    const manifest = loadToolsTestLaneManifest();
+
+    expect(manifest.maxWorkers.unit).toBeGreaterThan(1);
+    expect(manifest.maxWorkers.unit).toBeLessThanOrEqual(4);
+    expect(manifest.fileParallelism.unit).toBe(true);
+
+    expect(manifest.maxWorkers.integration).toBe(1);
+    expect(manifest.maxWorkers.native).toBe(1);
+    expect(manifest.maxWorkers.e2e).toBe(1);
+    expect(manifest.fileParallelism.integration).toBe(false);
+    expect(manifest.fileParallelism.native).toBe(false);
+    expect(manifest.fileParallelism.e2e).toBe(false);
+  });
+});

package/tests/guards/tools-vitest-workspace-alias.contract.test.ts

@@ -0,0 +1,63 @@
+import { describe, expect, it } from "vitest";
+import vitestConfig from "../../vitest.config.ts";
+import { loadToolsTestLaneManifest } from "../test-lane-manifest.js";
+
+interface AliasEntry {
+  find: string | RegExp;
+  replacement: string;
+}
+
+function requireAliasEntries(): AliasEntry[] {
+  const alias = vitestConfig.resolve?.alias;
+  if (!alias || !Array.isArray(alias)) {
+    throw new Error("Tools Vitest workspace alias entries are unavailable");
+  }
+  return alias as AliasEntry[];
+}
+
+function requireAliasEntry(entries: AliasEntry[], find: RegExp): AliasEntry {
+  const entry = entries.find(
+    (candidate) =>
+      candidate.find instanceof RegExp && candidate.find.toString() === find.toString(),
+  );
+
+  if (!entry) {
+    throw new Error(`Missing alias entry for ${find.toString()}`);
+  }
+
+  return entry;
+}
+
+describe("tools vitest workspace alias contract", () => {
+  it("resolves transitive workspace packages from source instead of package dist exports", () => {
+    const alias = requireAliasEntries();
+
+    expect(requireAliasEntry(alias, /^@aria\/auth$/).replacement).toContain(
+      "/packages/auth/src/index.ts",
+    );
+    expect(requireAliasEntry(alias, /^@aria\/memoria$/).replacement).toContain(
+      "/packages/memoria/src/index.ts",
+    );
+    expect(requireAliasEntry(alias, /^@aria\/memoria\/storage$/).replacement).toContain(
+      "/packages/memoria/src/storage/index.ts",
+    );
+    expect(requireAliasEntry(alias, /^@aria\/models$/).replacement).toContain(
+      "/packages/models/src/index.ts",
+    );
+    expect(requireAliasEntry(alias, /^@aria\/types$/).replacement).toContain(
+      "/packages/types/src/index.ts",
+    );
+    expect(requireAliasEntry(alias, /^@aria\/tools$/).replacement).toContain(
+      "/packages/tools/src/index.ts",
+    );
+    expect(requireAliasEntry(alias, /^@aria\/tools\/network-runtime$/).replacement).toContain(
+      "/packages/tools/src/network-runtime/index.ts",
+    );
+  });
+
+  it("runs the package lane in isolated forks with a single worker", () => {
+    const manifest = loadToolsTestLaneManifest();
+    expect(vitestConfig.test?.pool).toBe("forks");
+    expect(vitestConfig.test?.maxWorkers).toBe(manifest.maxWorkers.unit);
+  });
+});

package/tests/helpers/async-waits.ts

@@ -0,0 +1,53 @@
+import type { ChildProcess } from "node:child_process";
+import { once } from "node:events";
+import { access } from "node:fs/promises";
+
+export async function withTimeout<T>(
+  promise: Promise<T>,
+  timeoutMs: number,
+  timeoutMessage: string,
+): Promise<T> {
+  let timeoutId: NodeJS.Timeout | undefined;
+  const timeoutPromise = new Promise<never>((_, reject) => {
+    timeoutId = setTimeout(() => reject(new Error(timeoutMessage)), timeoutMs);
+  });
+
+  try {
+    return await Promise.race([promise, timeoutPromise]);
+  } finally {
+    if (timeoutId) {
+      clearTimeout(timeoutId);
+    }
+  }
+}
+
+export async function waitForFile(filePath: string, timeoutMs = 5_000): Promise<void> {
+  const start = Date.now();
+  while (Date.now() - start < timeoutMs) {
+    try {
+      await access(filePath);
+      return;
+    } catch {
+      // File not ready yet.
+    }
+    await new Promise((resolve) => setTimeout(resolve, 50));
+  }
+  throw new Error(`Timed out waiting for file: ${filePath}`);
+}
+
+export async function waitForChildExit(
+  child: ChildProcess,
+  timeoutMs = 5_000,
+): Promise<{ code: number | null; signal: NodeJS.Signals | null }> {
+  if (child.exitCode !== null || child.signalCode !== null) {
+    return { code: child.exitCode, signal: child.signalCode };
+  }
+
+  const [code, signal] = await withTimeout(
+    once(child, "exit") as Promise<[number | null, NodeJS.Signals | null]>,
+    timeoutMs,
+    `Timed out waiting for child process ${child.pid ?? "unknown"} to exit`,
+  );
+
+  return { code, signal };
+}