@m8i-51/shoal 0.1.0

package/README.md

@@ -0,0 +1,121 @@
+[日本語版はこちら](README_JA.md)
+
+# shoal
+
+[![TypeScript](https://img.shields.io/badge/TypeScript-5-blue?logo=typescript&logoColor=white)](https://www.typescriptlang.org/)
+[![Playwright](https://img.shields.io/badge/Playwright-browser-45ba4b?logo=playwright&logoColor=white)](https://playwright.dev/)
+[![Anthropic](https://img.shields.io/badge/Anthropic-Claude-blueviolet?logo=anthropic&logoColor=white)](https://www.anthropic.com/)
+
+Point it at any web app. Agents explore it and file GitHub Issues.
+
+shoal drops a swarm of agents onto a web app. Each agent has a distinct persona and evaluation lens — accessibility, security, business logic, data integrity, new user experience. They explore independently via API and real browser, then a triage agent deduplicates findings and files GitHub Issues.
+
+No test scripts. No test data. No prior knowledge of the app required.
+
+---
+
+## How it works
+
+```
+Target App (any URL)
+        │
+        ▼  autonomously learns what the app does
+  Product Discovery
+        │
+        ▼  generates a user persona team for that app
+  Org Design
+        │
+        ▼  creates and maintains the agent roster
+  HR Agent
+        │
+        ├──────────────────────────────────┐
+        ▼                                  ▼
+  API Agents  ×N                   Browser Agents  ×N
+  explore via API                  browse the real UI
+        │                                  │
+        └──────────────┬───────────────────┘
+                       ▼  deduplicates and files GitHub Issues
+                 Triage Agent
+```
+
+---
+
+## Quick Start
+
+```bash
+git clone https://github.com/m8i-51/shoal
+cd shoal
+npm install && npx playwright install chromium
+cp .env.example .env   # set ANTHROPIC_API_KEY and BASE_URL
+npm start
+```
+
+---
+
+## Configuration
+
+| Variable | Default | Description |
+|---|---|---|
+| `TARGET` | `none` | Target config name (`example` \| `none` \| your custom name) |
+| `BASE_URL` | `http://localhost:3000` | Target app URL |
+| `MAX_EXPLORERS` | `4` | API explorer agent count (0 to disable) |
+| `MAX_BROWSERS` | `2` | Browser agent count |
+| `ANTHROPIC_API_KEY` | — | Required |
+| `GITHUB_TOKEN` | — | Optional — enables Issue creation |
+| `GITHUB_REPO` | — | `owner/repo` format |
+
+---
+
+## Adding a target
+
+shoal loads `shoal.config.ts` from the **current working directory** at startup. Two common setups:
+
+**Option A — config inside the shoal repo** (simplest)
+
+```bash
+cp shoal.config.example.ts shoal.config.ts
+# edit shoal.config.ts, then:
+npm start
+```
+
+**Option B — config in your project directory** (keeps shoal untouched)
+
+```bash
+cp /path/to/shoal/shoal.config.example.ts ./shoal.config.ts
+# edit shoal.config.ts, then run shoal from your project root:
+BASE_URL=http://localhost:3000 npm start --prefix /path/to/shoal
+```
+
+`shoal.config.ts` must export a `target` object with two fields:
+
+```typescript
+// shoal.config.ts
+export const target = {
+  appTools: [
+    { name: "list_items", description: "Get all items.", input_schema: { type: "object", properties: {}, required: [] } },
+  ],
+  async execute(toolName: string, input: Record<string, unknown>) {
+    if (toolName === "list_items") {
+      return fetch(`${process.env.BASE_URL}/api/items`).then(r => r.json());
+    }
+  },
+};
+```
+
+Alternatively, copy `targets/example.ts`, register it in `targets/index.ts`, and set `TARGET=my-app`.
+
+---
+
+## LLM providers
+
+shoal defaults to Anthropic Claude. To use a different provider, set these variables in `.env`:
+
+| Provider | Variables |
+|---|---|
+| Anthropic (default) | `ANTHROPIC_API_KEY` |
+| OpenAI | `LLM_PROVIDER=openai`, `LLM_API_KEY`, `LLM_MODEL` |
+| Codex (ChatGPT subscription) | run `npm run auth:codex` once, then `LLM_PROVIDER=codex` |
+| Ollama | `LLM_BASE_URL=http://localhost:11434/v1`, `LLM_MODEL` |
+| LM Studio | `LLM_BASE_URL=http://localhost:1234/v1`, `LLM_MODEL` |
+
+See `.env.example` for full examples.

package/bin/shoal.js

@@ -0,0 +1,56 @@
+#!/usr/bin/env node
+/**
+ * shoal CLI entry point
+ *
+ * Usage:
+ *   npx shoal              # run exploration
+ *   npx shoal triage       # triage-only mode
+ *   npx shoal serve        # local web dashboard
+ */
+import { spawn, spawnSync } from "child_process";
+import { fileURLToPath } from "url";
+import { dirname, join } from "path";
+import { existsSync } from "fs";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const packageRoot = join(__dirname, "..");
+
+const subcommand = process.argv[2];
+
+// serve の場合、web/dist が存在しなければ自動ビルドする
+if (subcommand === "serve") {
+  const distIndex = join(packageRoot, "web", "dist", "index.html");
+  const webSrc = join(packageRoot, "web", "src");
+  if (!existsSync(distIndex) && existsSync(webSrc)) {
+    console.log("[shoal] web/dist not found — building frontend...");
+    const viteBin = join(packageRoot, "node_modules", ".bin", "vite");
+    const buildBin = existsSync(viteBin) ? viteBin : "vite";
+    const result = spawnSync(buildBin, ["build", "web"], {
+      stdio: "inherit",
+      cwd: packageRoot,
+    });
+    if (result.status !== 0) {
+      console.error("[shoal] Frontend build failed. Run: npm run build:web");
+      process.exit(1);
+    }
+  }
+}
+
+const scriptMap = {
+  serve: "server/index.ts",
+  triage: "triage-only.ts",
+};
+const script = scriptMap[subcommand] ?? "run.ts";
+
+// tsx の bin を package 内から解決し、なければ PATH にフォールバック
+const tsxBin = join(packageRoot, "node_modules", ".bin", "tsx");
+const bin = existsSync(tsxBin) ? tsxBin : "tsx";
+const scriptPath = join(packageRoot, script);
+
+const child = spawn(bin, [scriptPath, ...process.argv.slice(subcommand ? 3 : 2)], {
+  stdio: "inherit",
+  env: process.env,
+  cwd: process.cwd(),
+});
+
+child.on("exit", (code) => process.exit(code ?? 0));

package/framework/__tests__/coverage.test.ts

@@ -0,0 +1,232 @@
+import { describe, it, expect, beforeEach, vi } from "vitest";
+import * as fs from "fs";
+import * as path from "path";
+
+vi.mock("fs");
+vi.mock("path", async (importOriginal) => {
+  const actual = await importOriginal<typeof path>();
+  return { ...actual, join: (...args: string[]) => args.join("/") };
+});
+
+import { computeWeightedSummary, updateCoverage, loadCoverage } from "../coverage";
+import type { Coverage, RunCoverage } from "../coverage";
+
+const HALF_LIFE_DAYS = 7;
+const halfLifeMs = HALF_LIFE_DAYS * 24 * 60 * 60 * 1000;
+
+function makeEntry(overrides: Partial<RunCoverage> = {}): RunCoverage {
+  return {
+    runId: "run_1",
+    timestamp: new Date().toISOString(),
+    findingsCount: 0,
+    byCategory: {},
+    byLens: {},
+    byScenario: {},
+    ...overrides,
+  };
+}
+
+function setupMockCoverage(coverage: Coverage) {
+  vi.mocked(fs.existsSync).mockReturnValue(true);
+  vi.mocked(fs.readFileSync).mockReturnValue(JSON.stringify(coverage) as unknown as ReturnType<typeof fs.readFileSync>);
+}
+
+describe("loadCoverage", () => {
+  it("空ファイルが存在しない場合は空のエントリーを返す", () => {
+    vi.mocked(fs.existsSync).mockReturnValue(false);
+    const result = loadCoverage();
+    expect(result).toEqual({ entries: [] });
+  });
+
+  it("ファイルが存在する場合はパースして返す", () => {
+    const coverage: Coverage = { entries: [makeEntry({ runId: "run_1" })] };
+    setupMockCoverage(coverage);
+    const result = loadCoverage();
+    expect(result.entries).toHaveLength(1);
+    expect(result.entries[0].runId).toBe("run_1");
+  });
+});
+
+describe("computeWeightedSummary", () => {
+  beforeEach(() => {
+    vi.mocked(fs.mkdirSync).mockReturnValue(undefined);
+    vi.mocked(fs.writeFileSync).mockReturnValue(undefined);
+  });
+
+  it("エントリーがない場合は空サマリーを返す", () => {
+    vi.mocked(fs.existsSync).mockReturnValue(false);
+    const result = computeWeightedSummary();
+    expect(result.totalWeighted).toBe(0);
+    expect(result.formatted).toContain("no coverage data");
+  });
+
+  it("直近のエントリーは重みが高い", () => {
+    const now = Date.now();
+    const recentEntry = makeEntry({
+      runId: "recent",
+      timestamp: new Date(now).toISOString(),
+      findingsCount: 10,
+      byLens: { Accessibility: 10 },
+    });
+    const oldEntry = makeEntry({
+      runId: "old",
+      timestamp: new Date(now - halfLifeMs * 2).toISOString(), // 半減期2倍 = weight 0.25
+      findingsCount: 10,
+      byLens: { Accessibility: 10 },
+    });
+    setupMockCoverage({ entries: [oldEntry, recentEntry] });
+
+    const result = computeWeightedSummary();
+    // recent(weight≈1.0) + old(weight≈0.25) なので合計は約 12.5
+    expect(result.totalWeighted).toBeGreaterThan(10);
+    expect(result.totalWeighted).toBeLessThan(15);
+  });
+
+  it("半減期2倍前のエントリーは重みが約0.25になる", () => {
+    const now = Date.now();
+    const oldTimestamp = new Date(now - halfLifeMs * 2).toISOString();
+    setupMockCoverage({
+      entries: [
+        makeEntry({
+          runId: "old",
+          timestamp: oldTimestamp,
+          findingsCount: 4,
+          byLens: { Security: 4 },
+        }),
+      ],
+    });
+
+    const result = computeWeightedSummary();
+    // weight = 0.5^2 = 0.25, findingsCount=4 → totalWeighted=1.0
+    expect(result.totalWeighted).toBeCloseTo(1.0, 0);
+    expect(result.byLens["Security"]).toBeCloseTo(1.0, 0);
+  });
+
+  it("カテゴリ別の集計が正しい", () => {
+    setupMockCoverage({
+      entries: [
+        makeEntry({
+          timestamp: new Date().toISOString(),
+          byCategory: { bug: 3, ux: 5 },
+          findingsCount: 8,
+        }),
+      ],
+    });
+
+    const result = computeWeightedSummary();
+    expect(result.byCategory["bug"]).toBeGreaterThan(0);
+    expect(result.byCategory["ux"]).toBeGreaterThan(result.byCategory["bug"]);
+  });
+
+  it("underrepresented レンズが formatted に含まれる", () => {
+    const now = Date.now();
+    // Accessibility は 10 件、Security は 1 件（平均 5.5 の半分未満 → underrepresented）
+    setupMockCoverage({
+      entries: [
+        makeEntry({
+          timestamp: new Date(now).toISOString(),
+          findingsCount: 11,
+          byLens: { Accessibility: 10, Security: 1 },
+        }),
+      ],
+    });
+
+    const result = computeWeightedSummary();
+    expect(result.formatted).toContain("Security");
+    expect(result.formatted.toLowerCase()).toContain("underrepresented");
+  });
+
+  it("全レンズが均等な場合は underrepresented なしのメッセージを出す", () => {
+    setupMockCoverage({
+      entries: [
+        makeEntry({
+          timestamp: new Date().toISOString(),
+          findingsCount: 6,
+          byLens: { Accessibility: 3, Security: 3 },
+        }),
+      ],
+    });
+
+    const result = computeWeightedSummary();
+    expect(result.formatted).toContain("comparable coverage");
+  });
+
+  it("シナリオ別の集計が結果に含まれる", () => {
+    setupMockCoverage({
+      entries: [
+        makeEntry({
+          timestamp: new Date().toISOString(),
+          findingsCount: 2,
+          byScenario: { "New employee submitting first purchase": 2 },
+        }),
+      ],
+    });
+
+    const result = computeWeightedSummary();
+    expect(result.byScenario["New employee submitting first purchase"]).toBeGreaterThan(0);
+    expect(result.formatted).toContain("By scenario");
+  });
+
+  it("MAX_ENTRIES を超えると最新30件に切り捨てる", () => {
+    const entries = Array.from({ length: 35 }, (_, i) =>
+      makeEntry({
+        runId: `run_${i}`,
+        timestamp: new Date(Date.now() - i * 1000).toISOString(),
+      })
+    );
+    setupMockCoverage({ entries });
+    vi.mocked(fs.writeFileSync).mockImplementation(() => {});
+
+    // updateCoverage が 31件目を追加してトリムすることを確認
+    vi.mocked(fs.existsSync).mockReturnValue(true);
+    vi.mocked(fs.readFileSync).mockReturnValue(JSON.stringify({ entries }) as unknown as Buffer);
+
+    // computeWeightedSummary は entries をそのまま使うだけなので、
+    // 35件あってもエラーにならないことを確認
+    expect(() => computeWeightedSummary()).not.toThrow();
+  });
+});
+
+describe("updateCoverage", () => {
+  beforeEach(() => {
+    vi.mocked(fs.existsSync).mockReturnValue(false);
+    vi.mocked(fs.mkdirSync).mockReturnValue(undefined);
+    vi.mocked(fs.writeFileSync).mockReturnValue(undefined);
+  });
+
+  it("新しいエントリーを追加して保存する", () => {
+    const findings = [
+      { id: "f1", runId: "run_1", agentId: "a1", agentName: "Alice", role: "tester", category: "bug", title: "Bug A", body: "", timestamp: new Date().toISOString() },
+      { id: "f2", runId: "run_1", agentId: "a2", agentName: "Bob", role: "tester", category: "ux", title: "UX B", body: "", timestamp: new Date().toISOString() },
+    ];
+    const agentAssignments = new Map([
+      ["a1", { lens: "Security: something" }],
+      ["a2", { lens: "Accessibility: something" }],
+    ]);
+
+    updateCoverage("run_1", findings, agentAssignments);
+
+    const calls = vi.mocked(fs.writeFileSync).mock.calls;
+    const written = calls[calls.length - 1][1] as string;
+    const saved = JSON.parse(written) as Coverage;
+    expect(saved.entries).toHaveLength(1);
+    expect(saved.entries[0].byCategory).toEqual({ bug: 1, ux: 1 });
+    expect(saved.entries[0].byLens["Security"]).toBe(1);
+    expect(saved.entries[0].byLens["Accessibility"]).toBe(1);
+  });
+
+  it("シナリオアサインのエントリーは byScenario に記録する", () => {
+    const findings = [
+      { id: "f1", runId: "run_1", agentId: "a1", agentName: "Alice", role: "tester", category: "ux", title: "UX", body: "", timestamp: new Date().toISOString() },
+    ];
+    const scenario = { id: "s1", title: "New employee task", context: "", goal: "", constraints: "" };
+    const agentAssignments = new Map([["a1", { scenario }]]);
+
+    updateCoverage("run_1", findings, agentAssignments);
+
+    const calls = vi.mocked(fs.writeFileSync).mock.calls;
+    const written = calls[calls.length - 1][1] as string;
+    const saved = JSON.parse(written) as Coverage;
+    expect(saved.entries[0].byScenario["New employee task"]).toBe(1);
+  });
+});

package/framework/__tests__/report.test.ts

@@ -0,0 +1,154 @@
+import { describe, it, expect, vi, beforeEach } from "vitest";
+import * as fs from "fs";
+import * as path from "path";
+
+vi.mock("fs");
+vi.mock("path", async (importOriginal) => {
+  const actual = await importOriginal<typeof path>();
+  return { ...actual, join: (...args: string[]) => args.join("/") };
+});
+
+import { generateReport } from "../report";
+import type { RunLog, Finding } from "../types";
+import type { TriageResult } from "../triage";
+import type { ProductSpec } from "../product-discovery";
+
+function getSavedHtml(): string {
+  const calls = vi.mocked(fs.writeFileSync).mock.calls;
+  return calls[calls.length - 1][1] as string;
+}
+
+function makeRunLog(overrides: Partial<RunLog> = {}): RunLog {
+  return {
+    runId: "run_test",
+    startedAt: "2026-04-27T00:00:00.000Z",
+    completedAt: "2026-04-27T00:05:00.000Z",
+    repo: "",
+    agents: [],
+    summary: {
+      totalAgents: 0,
+      completed: 0,
+      errors: 0,
+      iterationLimitReached: 0,
+      totalActions: 0,
+      totalIssuesPosted: 0,
+      regressionChecked: 0,
+      regressionFailed: 0,
+      rateLimitRetries: 0,
+      cost: { inputTokens: 0, outputTokens: 0, estimatedUSD: null },
+    },
+    ...overrides,
+  };
+}
+
+function makeProductSpec(overrides: Partial<ProductSpec> = {}): ProductSpec {
+  return {
+    appName: "Test App",
+    appDescription: "A test application",
+    targetUsers: "Engineers",
+    features: "Login, Dashboard",
+    designContext: "",
+    uiFeatures: "",
+    appGoals: [],
+    confidence: "high",
+    sources: [],
+    ...overrides,
+  };
+}
+
+function makeFinding(overrides: Partial<Finding> = {}): Finding {
+  return {
+    id: "f1",
+    runId: "run_test",
+    agentId: "a1",
+    agentName: "Alice",
+    role: "tester",
+    category: "bug",
+    title: "Login button broken",
+    body: "Clicking login does nothing",
+    timestamp: "2026-04-27T00:01:00.000Z",
+    ...overrides,
+  };
+}
+
+const emptyTriage: TriageResult = { issued: [], skipped: [], unprocessed: [], issuesCreated: 0 };
+
+describe("generateReport", () => {
+  beforeEach(() => {
+    vi.mocked(fs.existsSync).mockReturnValue(false);
+    vi.mocked(fs.mkdirSync).mockReturnValue(undefined);
+    vi.mocked(fs.writeFileSync).mockReturnValue(undefined);
+  });
+
+  it("ファイルパスを返す", () => {
+    const result = generateReport(makeRunLog(), [], emptyTriage, makeProductSpec(), [], new Map());
+    expect(result).toContain("report_run_test.html");
+  });
+
+  it("有効な HTML をファイルに書き出す", () => {
+    generateReport(makeRunLog(), [], emptyTriage, makeProductSpec(), [], new Map());
+    const html = getSavedHtml();
+    expect(html).toContain("<!DOCTYPE html>");
+    expect(html).toContain("</html>");
+  });
+
+  it("アプリ名がレポートに含まれる", () => {
+    generateReport(makeRunLog(), [], emptyTriage, makeProductSpec({ appName: "MySpecialApp" }), [], new Map());
+    expect(getSavedHtml()).toContain("MySpecialApp");
+  });
+
+  it("finding のタイトルが HTML エスケープされる", () => {
+    const finding = makeFinding({ title: "XSS <script>alert(1)</script>" });
+    generateReport(makeRunLog(), [finding], emptyTriage, makeProductSpec(), [], new Map());
+    const html = getSavedHtml();
+    expect(html).not.toContain("<script>alert(1)</script>");
+    expect(html).toContain("&lt;script&gt;");
+  });
+
+  it("issued finding に → Issue バッジが付く", () => {
+    const finding = makeFinding({ id: "f1" });
+    const triage: TriageResult = { issued: ["f1"], skipped: [], unprocessed: [], issuesCreated: 1 };
+    generateReport(makeRunLog(), [finding], triage, makeProductSpec(), [], new Map());
+    expect(getSavedHtml()).toContain("→ Issue");
+  });
+
+  it("skipped finding に skipped バッジが付く", () => {
+    const finding = makeFinding({ id: "f1" });
+    const triage: TriageResult = { issued: [], skipped: ["f1"], unprocessed: [], issuesCreated: 0 };
+    generateReport(makeRunLog(), [finding], triage, makeProductSpec(), [], new Map());
+    expect(getSavedHtml()).toContain("skipped");
+  });
+
+  it("シナリオ付きの finding にシナリオタグが付く", () => {
+    const finding = makeFinding({ agentId: "a1" });
+    const scenario = { id: "s1", title: "New employee task", context: "", goal: "", constraints: "" };
+    const agentAssignments = new Map([["a1", { scenario }]]);
+    generateReport(makeRunLog(), [finding], emptyTriage, makeProductSpec(), [scenario], agentAssignments);
+    const html = getSavedHtml();
+    expect(html).toContain("New employee task");
+    expect(html).toContain("scenario");
+  });
+
+  it("レンズ付きの finding にレンズタグが付く", () => {
+    const finding = makeFinding({ agentId: "a1" });
+    const agentAssignments = new Map([["a1", { lens: "Accessibility: keyboard navigation" }]]);
+    generateReport(makeRunLog(), [finding], emptyTriage, makeProductSpec(), [], agentAssignments);
+    const html = getSavedHtml();
+    expect(html).toContain("Accessibility");
+    expect(html).toContain("lens");
+  });
+
+  it("finding が issued → unprocessed → skipped の順に並ぶ", () => {
+    const f1 = makeFinding({ id: "f1", title: "Issued Finding" });
+    const f2 = makeFinding({ id: "f2", title: "Skipped Finding" });
+    const f3 = makeFinding({ id: "f3", title: "Unprocessed Finding" });
+    const triage: TriageResult = { issued: ["f1"], skipped: ["f2"], unprocessed: ["f3"], issuesCreated: 1 };
+    generateReport(makeRunLog(), [f2, f3, f1], triage, makeProductSpec(), [], new Map());
+    const html = getSavedHtml();
+    const issuedPos = html.indexOf("Issued Finding");
+    const unprocessedPos = html.indexOf("Unprocessed Finding");
+    const skippedPos = html.indexOf("Skipped Finding");
+    expect(issuedPos).toBeLessThan(unprocessedPos);
+    expect(unprocessedPos).toBeLessThan(skippedPos);
+  });
+});