@m8i-51/shoal 0.1.18 → 0.1.20

package/README.md

@@ -114,12 +114,26 @@ npm run serve      # from cloned repo
 Opens at `http://localhost:4000`. From there you can:
 
 - **Start a run** — configure agent count, target URL, and custom instructions
-- **Monitor live progress** — watch agents explore and file findings in real time
+- **Watch agents swim live** — the Swarm tab shows an animated real-time view of agents as they explore. When a finding is discovered, the agent's chip flashes with the finding title.
 - **Review past runs** — findings by category, agent count, duration, and estimated cost
+- **Generate an Agent Diary** — after a run completes, one LLM call turns the raw log into a story-style narrative of the exploration, readable by anyone on the team
+- **Hall of Issues** — browse all findings across every run with full-text search and category filter. Export as JSON to share, or paste a community findings URL to import findings from other projects.
 - **Edit app goals** — guide the goal-gap detector by defining what the app should achieve
 
 ---
 
+## Cross-run intelligence
+
+shoal gets smarter with each run.
+
+**Diff exploration** — after every browser navigation, shoal hashes the page content (SHA-256 of `innerText`). On the next run, agents that land on an unchanged page are nudged to move on: *"page content unchanged since last run — consider exploring a different area."* The hashes accumulate in `cache/page-hashes/` and steer future agents toward parts of the app that have actually changed.
+
+**Finding hotspots** — the persona designer has access to a `get_finding_hotspots` tool that aggregates findings by URL area across all past runs. It uses this to recruit agents toward under-investigated parts of the app, or to send specialists into zones where problems keep clustering.
+
+Both signals work passively — no configuration needed. They improve automatically as runs accumulate.
+
+---
+
 ## Configuration
 
 | Variable | Default | Description |

package/framework/__tests__/cost.test.ts

@@ -19,6 +19,18 @@ describe("formatCostUSD", () => {
     expect(formatCostUSD(undefined)).toBe("—");
   });
 
+  it("0 は < $0.0001", () => {
+    expect(formatCostUSD(0)).toBe("< $0.0001");
+  });
+
+  it("負値は < $0.0001", () => {
+    expect(formatCostUSD(-1)).toBe("< $0.0001");
+  });
+
+  it("0.0001 ちょうどは 4 桁小数", () => {
+    expect(formatCostUSD(0.0001)).toBe("$0.0001");
+  });
+
   it("0.00005 未満は < $0.0001", () => {
     expect(formatCostUSD(0.000005)).toBe("< $0.0001");
   });

package/framework/__tests__/coverage.test.ts

@@ -8,7 +8,7 @@ vi.mock("path", async (importOriginal) => {
   return { ...actual, join: (...args: string[]) => args.join("/") };
 });
 
-import { computeWeightedSummary, updateCoverage, loadCoverage } from "../coverage";
+import { computeWeightedSummary, updateCoverage, loadCoverage, getLastRunPaths, getFindingHotspots } from "../coverage";
 import type { Coverage, RunCoverage } from "../coverage";
 
 const HALF_LIFE_DAYS = 7;
@@ -170,7 +170,7 @@ describe("computeWeightedSummary", () => {
 
   it("14日以内に同じレンズが複数 run に登場するとボーナスが乗る", () => {
     const now = Date.now();
-    // 同じ Accessibility レンズが2回登場 → bonus = 1 + (2-1)*0.5 = 1.5
+    // 同じ Accessibility レンズが2回登場 → bonus = 1 + (2-1)^3 * 0.005 = 1.005
     setupMockCoverage({
       entries: [
         makeEntry({
@@ -249,22 +249,29 @@ describe("computeWeightedSummary", () => {
   });
 
   it("MAX_ENTRIES を超えると最新30件に切り捨てる", () => {
-    const entries = Array.from({ length: 35 }, (_, i) =>
+    // 既に30件ある状態で updateCoverage を呼ぶと31件→30件にトリムされることを確認
+    const entries = Array.from({ length: 30 }, (_, i) =>
       makeEntry({
         runId: `run_${i}`,
-        timestamp: new Date(Date.now() - i * 1000).toISOString(),
+        timestamp: new Date(Date.now() - (30 - 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 }));
+    vi.mocked(fs.writeFileSync).mockImplementation(() => {});
+    vi.mocked(fs.mkdirSync).mockReturnValue(undefined);
 
-    // computeWeightedSummary は entries をそのまま使うだけなので、
-    // 35件あってもエラーにならないことを確認
-    expect(() => computeWeightedSummary()).not.toThrow();
+    updateCoverage("run_new", [], new Map());
+
+    const calls = vi.mocked(fs.writeFileSync).mock.calls;
+    const written = calls[calls.length - 1][1] as string;
+    const saved = JSON.parse(written) as Coverage;
+    // 30件 + 1件 → MAX_ENTRIES(30) に切り詰め
+    expect(saved.entries).toHaveLength(30);
+    // 最新のエントリーが含まれる
+    expect(saved.entries.some((e) => e.runId === "run_new")).toBe(true);
+    // 最も古いエントリーが除外される
+    expect(saved.entries.some((e) => e.runId === "run_0")).toBe(false);
   });
 });
 
@@ -311,3 +318,112 @@ describe("updateCoverage", () => {
     expect(saved.entries[0].byScenario["New employee task"]).toBe(1);
   });
 });
+
+describe("getLastRunPaths", () => {
+  it("エントリーがない場合は null を返す", () => {
+    vi.mocked(fs.existsSync).mockReturnValue(false);
+    expect(getLastRunPaths()).toBeNull();
+  });
+
+  it("最後のエントリーの visitedPaths と runId を返す", () => {
+    setupMockCoverage({
+      entries: [
+        makeEntry({ runId: "run_1", visitedPaths: ["/old"] }),
+        makeEntry({ runId: "run_2", visitedPaths: ["/a", "/b"] }),
+      ],
+    });
+    const result = getLastRunPaths();
+    expect(result).not.toBeNull();
+    expect(result!.runId).toBe("run_2");
+    expect(result!.visitedPaths).toEqual(["/a", "/b"]);
+  });
+
+  it("visitedPaths が undefined のエントリーは空配列を返す", () => {
+    vi.mocked(fs.existsSync).mockReturnValue(true);
+    vi.mocked(fs.readFileSync).mockReturnValue(
+      JSON.stringify({ entries: [{ ...makeEntry({ runId: "run_1" }), visitedPaths: undefined }] })
+    );
+    const result = getLastRunPaths();
+    expect(result!.visitedPaths).toEqual([]);
+  });
+});
+
+describe("getFindingHotspots", () => {
+  beforeEach(() => {
+    vi.mocked(fs.mkdirSync).mockReturnValue(undefined);
+    vi.mocked(fs.writeFileSync).mockReturnValue(undefined);
+  });
+
+  it("findings ディレクトリが存在しない場合は空配列を返す", () => {
+    vi.mocked(fs.existsSync).mockReturnValue(false);
+    expect(getFindingHotspots()).toEqual([]);
+  });
+
+  it("run_\\d+ パターン以外のディレクトリは無視する", () => {
+    vi.mocked(fs.existsSync).mockReturnValue(true);
+    vi.mocked(fs.readdirSync).mockReturnValue(
+      [".DS_Store", "run_abc", "tmp"] as unknown as ReturnType<typeof fs.readdirSync>
+    );
+    expect(getFindingHotspots()).toEqual([]);
+  });
+
+  it("複数 run の findings を同一パスで合算する", () => {
+    vi.mocked(fs.existsSync).mockReturnValue(true);
+    vi.mocked(fs.readdirSync)
+      .mockReturnValueOnce(["run_1", "run_2"] as unknown as ReturnType<typeof fs.readdirSync>)
+      .mockReturnValueOnce(["f1.json"] as unknown as ReturnType<typeof fs.readdirSync>)
+      .mockReturnValueOnce(["f2.json"] as unknown as ReturnType<typeof fs.readdirSync>);
+
+    const finding1 = { id: "f1", runId: "run_1", agentId: "a1", agentName: "Alice", role: "r", title: "Bug on /settings page", body: "Found at /settings/profile", category: "bug", timestamp: new Date().toISOString() };
+    const finding2 = { id: "f2", runId: "run_2", agentId: "a2", agentName: "Bob", role: "r", title: "UX issue on /settings", body: "The /settings layout is confusing", category: "ux", timestamp: new Date().toISOString() };
+
+    vi.mocked(fs.readFileSync)
+      .mockReturnValueOnce(JSON.stringify(finding1) as unknown as ReturnType<typeof fs.readFileSync>)
+      .mockReturnValueOnce(JSON.stringify(finding2) as unknown as ReturnType<typeof fs.readFileSync>);
+
+    const hotspots = getFindingHotspots();
+    const settings = hotspots.find((h) => h.pathPrefix === "/settings");
+    expect(settings).toBeDefined();
+    expect(settings!.totalFindings).toBe(2);
+    expect(settings!.categories["bug"]).toBe(1);
+    expect(settings!.categories["ux"]).toBe(1);
+  });
+
+  it("topN パラメータで件数を絞る", () => {
+    vi.mocked(fs.existsSync).mockReturnValue(true);
+    vi.mocked(fs.readdirSync)
+      .mockReturnValueOnce(["run_1"] as unknown as ReturnType<typeof fs.readdirSync>)
+      .mockReturnValueOnce(["f1.json", "f2.json", "f3.json"] as unknown as ReturnType<typeof fs.readdirSync>);
+
+    const makeFinding = (id: string, path: string) => ({ id, runId: "run_1", agentId: "a", agentName: "A", role: "r", title: `Issue on ${path}`, body: `Problem at ${path}`, category: "bug", timestamp: new Date().toISOString() });
+    vi.mocked(fs.readFileSync)
+      .mockReturnValueOnce(JSON.stringify(makeFinding("f1", "/alpha")) as unknown as ReturnType<typeof fs.readFileSync>)
+      .mockReturnValueOnce(JSON.stringify(makeFinding("f2", "/beta")) as unknown as ReturnType<typeof fs.readFileSync>)
+      .mockReturnValueOnce(JSON.stringify(makeFinding("f3", "/gamma")) as unknown as ReturnType<typeof fs.readFileSync>);
+
+    expect(getFindingHotspots(2)).toHaveLength(2);
+  });
+
+  it("壊れた JSON ファイルはスキップする", () => {
+    vi.mocked(fs.existsSync).mockReturnValue(true);
+    vi.mocked(fs.readdirSync)
+      .mockReturnValueOnce(["run_1"] as unknown as ReturnType<typeof fs.readdirSync>)
+      .mockReturnValueOnce(["bad.json"] as unknown as ReturnType<typeof fs.readdirSync>);
+    vi.mocked(fs.readFileSync).mockReturnValueOnce("invalid{{{" as unknown as ReturnType<typeof fs.readFileSync>);
+
+    expect(() => getFindingHotspots()).not.toThrow();
+    expect(getFindingHotspots()).toEqual([]);
+  });
+
+  it("パスが見つからない場合は / にフォールバックする", () => {
+    vi.mocked(fs.existsSync).mockReturnValue(true);
+    vi.mocked(fs.readdirSync)
+      .mockReturnValueOnce(["run_1"] as unknown as ReturnType<typeof fs.readdirSync>)
+      .mockReturnValueOnce(["f1.json"] as unknown as ReturnType<typeof fs.readdirSync>);
+    const finding = { id: "f1", runId: "run_1", agentId: "a", agentName: "A", role: "r", title: "Generic error", body: "Something went wrong", category: "bug", timestamp: new Date().toISOString() };
+    vi.mocked(fs.readFileSync).mockReturnValueOnce(JSON.stringify(finding) as unknown as ReturnType<typeof fs.readFileSync>);
+
+    const hotspots = getFindingHotspots();
+    expect(hotspots.some((h) => h.pathPrefix === "/")).toBe(true);
+  });
+});

package/framework/__tests__/diary.test.ts

@@ -0,0 +1,139 @@
+import { describe, it, expect, vi, beforeEach } from "vitest";
+import * as fs from "fs";
+
+vi.mock("fs");
+vi.mock("path", async (importOriginal) => {
+  const actual = await importOriginal<typeof import("path")>();
+  return { ...actual, join: (...args: string[]) => args.join("/"), dirname: (p: string) => p.split("/").slice(0, -1).join("/") };
+});
+
+const mockCreateMessage = vi.fn();
+vi.mock("../llm-client.js", () => ({
+  createLLMClient: vi.fn(() => ({
+    client: { createMessage: mockCreateMessage },
+    defaultModel: "mock-model",
+  })),
+}));
+
+import { generateDiary, getDiaryPath } from "../diary";
+
+const DIARY_TEXT = "# 探索日誌 — run_123\n冒険が始まった。";
+
+beforeEach(() => {
+  vi.mocked(fs.existsSync).mockReturnValue(false);
+  vi.mocked(fs.mkdirSync).mockReturnValue(undefined);
+  vi.mocked(fs.writeFileSync).mockReturnValue(undefined);
+  vi.mocked(fs.readdirSync).mockReturnValue([] as unknown as ReturnType<typeof fs.readdirSync>);
+  mockCreateMessage.mockClear();
+  mockCreateMessage.mockResolvedValue({
+    content: [{ type: "text", text: DIARY_TEXT }],
+  });
+});
+
+describe("getDiaryPath", () => {
+  it("run_\\d+ 形式 + ファイル存在 → パスを返す", () => {
+    vi.mocked(fs.existsSync).mockReturnValue(true);
+    const result = getDiaryPath("run_123");
+    expect(result).not.toBeNull();
+    expect(result).toContain("run_123");
+  });
+
+  it("run_\\d+ 形式だがファイルなし → null", () => {
+    vi.mocked(fs.existsSync).mockReturnValue(false);
+    expect(getDiaryPath("run_123")).toBeNull();
+  });
+
+  it("不正な runId（英字）→ null", () => {
+    expect(getDiaryPath("run_abc")).toBeNull();
+  });
+
+  it("パストラバーサル試みは null", () => {
+    expect(getDiaryPath("../etc/passwd")).toBeNull();
+    expect(getDiaryPath("run_123/../../../etc")).toBeNull();
+  });
+});
+
+describe("generateDiary", () => {
+  it("生成されたテキストを返す", async () => {
+    const result = await generateDiary("run_123", []);
+    expect(result).toBe(DIARY_TEXT);
+  });
+
+  it("生成テキストをファイルに書き込む", async () => {
+    await generateDiary("run_123", []);
+    expect(fs.writeFileSync).toHaveBeenCalled();
+    const [, content] = vi.mocked(fs.writeFileSync).mock.calls[0];
+    expect(content).toBe(DIARY_TEXT);
+  });
+
+  it("ファイル書き込み前にディレクトリを作成する", async () => {
+    await generateDiary("run_123", []);
+    expect(fs.mkdirSync).toHaveBeenCalledWith(expect.any(String), { recursive: true });
+  });
+
+  it("findings がない場合はプロンプトに「発見なし」を含める", async () => {
+    vi.mocked(fs.existsSync).mockReturnValue(false);
+    await generateDiary("run_123", []);
+    const [params] = mockCreateMessage.mock.calls[0];
+    const userContent = (params.messages[0].content as string);
+    expect(userContent).toContain("発見なし");
+  });
+
+  it("findings がある場合はタイトルをプロンプトに含める", async () => {
+    vi.mocked(fs.existsSync).mockReturnValue(true);
+    vi.mocked(fs.readdirSync).mockReturnValue(["f1.json"] as unknown as ReturnType<typeof fs.readdirSync>);
+    const finding = { id: "f1", runId: "run_123", agentId: "a", agentName: "A", role: "r", title: "Login is broken", body: "", category: "bug", timestamp: new Date().toISOString() };
+    vi.mocked(fs.readFileSync).mockReturnValue(JSON.stringify(finding) as unknown as ReturnType<typeof fs.readFileSync>);
+
+    await generateDiary("run_123", []);
+    const [params] = mockCreateMessage.mock.calls[0];
+    expect(params.messages[0].content).toContain("Login is broken");
+  });
+
+  it("ログが空の場合はプロンプトに「イベントログなし」を含める", async () => {
+    await generateDiary("run_123", []);
+    const [params] = mockCreateMessage.mock.calls[0];
+    expect(params.messages[0].content).toContain("イベントログなし");
+  });
+
+  it("navigate 行は最大 25 件まで抽出する", async () => {
+    const lines = Array.from({ length: 30 }, (_, i) => `  → navigate({"path":"/page${i}"})`);
+    await generateDiary("run_123", lines);
+    const [params] = mockCreateMessage.mock.calls[0];
+    const content: string = params.messages[0].content;
+    const navCount = (content.match(/navigate/g) ?? []).length;
+    expect(navCount).toBeLessThanOrEqual(25);
+  });
+
+  it("agent start/done 行はすべて抽出する", async () => {
+    const lines = [
+      "[explorer] Alice start",
+      "[browser] Bob start",
+      "[explorer] Alice done",
+    ];
+    await generateDiary("run_123", lines);
+    const [params] = mockCreateMessage.mock.calls[0];
+    const content: string = params.messages[0].content;
+    expect(content).toContain("[explorer] Alice start");
+    expect(content).toContain("[browser] Bob start");
+    expect(content).toContain("[explorer] Alice done");
+  });
+
+  it("finding 発見ログは抽出される", async () => {
+    const lines = ['  → [findings] saved: "Login page crashes" (bug)'];
+    await generateDiary("run_123", lines);
+    const [params] = mockCreateMessage.mock.calls[0];
+    expect(params.messages[0].content).toContain("[findings] saved");
+  });
+
+  it("navigate 行が 100 文字超えると切り詰められる", async () => {
+    const longPath = "/very/long/path/" + "a".repeat(200);
+    const lines = [`  → navigate({"path":"${longPath}"})`];
+    await generateDiary("run_123", lines);
+    const [params] = mockCreateMessage.mock.calls[0];
+    const content: string = params.messages[0].content;
+    const lines2 = content.split("\n");
+    const navLine = lines2.find((l) => l.includes("navigate"));
+    expect(navLine!.length).toBeLessThanOrEqual(103); // 100 + "…"
+  });
+});

package/framework/__tests__/page-cache.test.ts

@@ -0,0 +1,106 @@
+import { describe, it, expect, vi, beforeEach } from "vitest";
+import * as fs from "fs";
+
+vi.mock("fs");
+vi.mock("path", async (importOriginal) => {
+  const actual = await importOriginal<typeof import("path")>();
+  return { ...actual, join: (...args: string[]) => args.join("/") };
+});
+
+import { loadPageHashes, updatePageHashes, hashContent } from "../page-cache";
+
+beforeEach(() => {
+  vi.mocked(fs.existsSync).mockReturnValue(false);
+  vi.mocked(fs.mkdirSync).mockReturnValue(undefined);
+  vi.mocked(fs.writeFileSync).mockReturnValue(undefined);
+});
+
+describe("hashContent", () => {
+  it("同じ文字列は常に同じハッシュを返す", () => {
+    expect(hashContent("hello")).toBe(hashContent("hello"));
+  });
+
+  it("異なる文字列は異なるハッシュを返す", () => {
+    expect(hashContent("hello")).not.toBe(hashContent("world"));
+  });
+
+  it("空文字列も一意のハッシュを返す", () => {
+    const h = hashContent("");
+    expect(typeof h).toBe("string");
+    expect(h.length).toBeGreaterThan(0);
+  });
+
+  it("16文字に切り詰められる", () => {
+    expect(hashContent("any content").length).toBe(16);
+  });
+});
+
+describe("loadPageHashes", () => {
+  it("キャッシュファイルがない場合は空オブジェクトを返す", () => {
+    vi.mocked(fs.existsSync).mockReturnValue(false);
+    expect(loadPageHashes("localhost:3000")).toEqual({});
+  });
+
+  it("キャッシュファイルがある場合はパースして返す", () => {
+    const data = { "/home": "abc123", "/about": "def456" };
+    vi.mocked(fs.existsSync).mockReturnValue(true);
+    vi.mocked(fs.readFileSync).mockReturnValue(JSON.stringify(data) as unknown as ReturnType<typeof fs.readFileSync>);
+    expect(loadPageHashes("localhost:3000")).toEqual(data);
+  });
+
+  it("壊れた JSON は空オブジェクトを返す（例外を投げない）", () => {
+    vi.mocked(fs.existsSync).mockReturnValue(true);
+    vi.mocked(fs.readFileSync).mockReturnValue("not valid json{{{" as unknown as ReturnType<typeof fs.readFileSync>);
+    expect(() => loadPageHashes("localhost:3000")).not.toThrow();
+    expect(loadPageHashes("localhost:3000")).toEqual({});
+  });
+
+  it("ホスト名の特殊文字（: や /）はファイルパスで - に変換される", () => {
+    vi.mocked(fs.existsSync).mockReturnValue(true);
+    vi.mocked(fs.readFileSync).mockReturnValue("{}" as unknown as ReturnType<typeof fs.readFileSync>);
+    loadPageHashes("localhost:3000");
+    const checkedPath = vi.mocked(fs.existsSync).mock.calls[0][0] as string;
+    expect(checkedPath).not.toContain(":");
+    expect(checkedPath).toContain("localhost-3000");
+  });
+});
+
+describe("updatePageHashes", () => {
+  it("空の updates を渡すと書き込みをしない", () => {
+    updatePageHashes("localhost:3000", {});
+    expect(fs.mkdirSync).not.toHaveBeenCalled();
+    expect(fs.writeFileSync).not.toHaveBeenCalled();
+  });
+
+  it("既存データと新データをマージして書き込む", () => {
+    const existing = { "/home": "old_hash", "/about": "about_hash" };
+    vi.mocked(fs.existsSync).mockReturnValue(true);
+    vi.mocked(fs.readFileSync).mockReturnValue(JSON.stringify(existing) as unknown as ReturnType<typeof fs.readFileSync>);
+
+    updatePageHashes("localhost:3000", { "/home": "new_hash", "/contact": "contact_hash" });
+
+    const written = JSON.parse(vi.mocked(fs.writeFileSync).mock.calls[0][1] as string);
+    expect(written["/home"]).toBe("new_hash");       // 上書き
+    expect(written["/about"]).toBe("about_hash");    // 既存を保持
+    expect(written["/contact"]).toBe("contact_hash"); // 新規追加
+  });
+
+  it("複数回呼ぶと蓄積される", () => {
+    vi.mocked(fs.existsSync).mockReturnValue(false);
+
+    updatePageHashes("localhost:3000", { "/a": "hash_a" });
+    // 2回目: 1回目の書き込み内容を既存として読み込む
+    vi.mocked(fs.existsSync).mockReturnValue(true);
+    vi.mocked(fs.readFileSync).mockReturnValue(JSON.stringify({ "/a": "hash_a" }) as unknown as ReturnType<typeof fs.readFileSync>);
+    updatePageHashes("localhost:3000", { "/b": "hash_b" });
+
+    const lastWrite = JSON.parse(vi.mocked(fs.writeFileSync).mock.calls.at(-1)![1] as string);
+    expect(lastWrite["/a"]).toBe("hash_a");
+    expect(lastWrite["/b"]).toBe("hash_b");
+  });
+
+  it("書き込み前にディレクトリを作成する", () => {
+    updatePageHashes("localhost:3000", { "/x": "hash_x" });
+    expect(fs.mkdirSync).toHaveBeenCalledWith(expect.any(String), { recursive: true });
+  });
+});

package/framework/__tests__/report.test.ts

@@ -126,6 +126,14 @@ describe("generateReport", () => {
     expect(html).toContain("<script>");
   });
 
+  it("finding の body が HTML エスケープされる", () => {
+    const finding = makeFinding({ body: 'Click <a href="javascript:void(0)" onclick="steal()">here</a>' });
+    generateReport(makeRunLog(), [finding], emptyTriage, makeProductSpec(), [], new Map());
+    const html = getSavedHtml();
+    expect(html).not.toContain("<a href=");
+    expect(html).toContain("&lt;a href=");
+  });
+
   it("issued finding に → Issue バッジが付く", () => {
     const finding = makeFinding({ id: "f1" });
     const triage: TriageResult = { issued: ["f1"], skipped: [], unprocessed: [], issuesCreated: 1 };

package/framework/coverage.ts

@@ -214,7 +214,7 @@ export interface FindingHotspot {
 
 function extractPath(finding: Finding): string {
   const text = `${finding.title} ${finding.body}`;
-  const m = text.match(/\b(\/[a-zA-Z0-9_/-]{2,})/);
+  const m = text.match(/(\/[a-zA-Z0-9_][a-zA-Z0-9_/-]*)/);
   if (!m) return "/";
   const segments = m[1].split("/").filter(Boolean);
   return segments.length > 0 ? `/${segments[0]}` : "/";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@m8i-51/shoal",
-  "version": "0.1.18",
+  "version": "0.1.20",
   "type": "module",
   "description": "Multi-agent web exploration framework — finds bugs, UX issues, and missing features by running AI agents against your app",
   "repository": {
@@ -50,6 +50,7 @@
     "@types/node": "^20",
     "@types/react": "^19.2.14",
     "@types/react-dom": "^19.2.3",
+    "@types/supertest": "^7.2.0",
     "@vitejs/plugin-react": "^4.7.0",
     "@vitest/coverage-v8": "^4.1.6",
     "concurrently": "^10.0.3",
@@ -58,6 +59,7 @@
     "react-dom": "^19.2.5",
     "react-i18next": "^17.0.4",
     "react-router-dom": "^7.14.1",
+    "supertest": "^7.2.2",
     "typescript": "^5",
     "vite": "^6.4.2",
     "vitest": "^4.1.5"

package/server/__tests__/api.test.ts

@@ -0,0 +1,307 @@
+import { describe, it, expect, vi, beforeEach } from "vitest";
+import request from "supertest";
+
+// ---- モック ----
+vi.mock("fs");
+vi.mock("path", async (importOriginal) => {
+  const actual = await importOriginal<typeof import("path")>();
+  return { ...actual, join: (...args: string[]) => args.join("/"), resolve: (...args: string[]) => args.join("/"), dirname: (p: string) => p };
+});
+vi.mock("../runner.js", () => ({ activeSessions: new Map(), spawnRun: vi.fn(), cancelSession: vi.fn() }));
+vi.mock("../runs.js", () => ({ listRuns: vi.fn(() => []), getReportPath: vi.fn(() => null) }));
+vi.mock("../scheduler.js", () => ({ loadSchedule: vi.fn(() => ({ enabled: false, dayOfWeek: 1, hour: 9, minute: 0, lastRunDate: null })), saveSchedule: vi.fn(), startScheduler: vi.fn() }));
+vi.mock("../../framework/diary.js", () => ({ generateDiary: vi.fn(), getDiaryPath: vi.fn(() => null) }));
+vi.mock("express-rate-limit", () => ({ rateLimit: () => (_req: unknown, _res: unknown, next: () => void) => next() }));
+
+import * as fs from "fs";
+import { generateDiary, getDiaryPath } from "../../framework/diary.js";
+import { activeSessions } from "../runner.js";
+
+// NODE_ENV=test なので app.listen は呼ばれない
+const { app } = await import("../index.js");
+
+// ----------------------------------------------------------------
+// テスト用ヘルパー
+// ----------------------------------------------------------------
+
+function mockFinding(overrides = {}) {
+  return {
+    id: "f1",
+    runId: "run_1",
+    agentId: "a1",
+    agentName: "Alice",
+    role: "tester",
+    title: "Test finding",
+    body: "Something broke",
+    category: "bug",
+    timestamp: new Date().toISOString(),
+    ...overrides,
+  };
+}
+
+function setupFindingsDir(runDirs: Record<string, object[]>) {
+  vi.mocked(fs.existsSync).mockImplementation((p: unknown) => {
+    const path = String(p);
+    return path.includes("findings") || Object.keys(runDirs).some((r) => path.includes(r));
+  });
+  vi.mocked(fs.readdirSync).mockImplementation((p: unknown) => {
+    const path = String(p);
+    const runId = Object.keys(runDirs).find((r) => path.endsWith(r));
+    if (runId) {
+      return runDirs[runId].map((_, i) => `f${i}.json`) as unknown as ReturnType<typeof fs.readdirSync>;
+    }
+    // findings ベースディレクトリ
+    return Object.keys(runDirs) as unknown as ReturnType<typeof fs.readdirSync>;
+  });
+  vi.mocked(fs.readFileSync).mockImplementation((p: unknown) => {
+    const path = String(p);
+    for (const [runId, items] of Object.entries(runDirs)) {
+      const idx = items.findIndex((_, i) => path.endsWith(`f${i}.json`));
+      if (idx >= 0 && path.includes(runId)) {
+        return JSON.stringify(items[idx]) as unknown as ReturnType<typeof fs.readFileSync>;
+      }
+    }
+    return "{}" as unknown as ReturnType<typeof fs.readFileSync>;
+  });
+}
+
+beforeEach(() => {
+  vi.mocked(fs.existsSync).mockReturnValue(false);
+  vi.mocked(fs.readdirSync).mockReturnValue([] as unknown as ReturnType<typeof fs.readdirSync>);
+  vi.mocked(fs.readFileSync).mockReturnValue("{}" as unknown as ReturnType<typeof fs.readFileSync>);
+  vi.mocked(fs.writeFileSync).mockReturnValue(undefined);
+  vi.mocked(fs.mkdirSync).mockReturnValue(undefined);
+  vi.mocked(getDiaryPath).mockReturnValue(null);
+  vi.mocked(generateDiary).mockResolvedValue("# 探索日誌");
+  (activeSessions as Map<string, unknown>).clear();
+});
+
+// ================================================================
+// GET /api/runs/:runId/diary
+// ================================================================
+describe("GET /api/runs/:runId/diary", () => {
+  it("不正な runId → 400", async () => {
+    const res = await request(app).get("/api/runs/run_abc/diary");
+    expect(res.status).toBe(400);
+  });
+
+  it("diary ファイルが存在しない → 404", async () => {
+    vi.mocked(getDiaryPath).mockReturnValue(null);
+    const res = await request(app).get("/api/runs/run_123/diary");
+    expect(res.status).toBe(404);
+  });
+
+  it("diary ファイルが存在する → 200 + content", async () => {
+    vi.mocked(getDiaryPath).mockReturnValue("/some/path/diary_run_123.md");
+    vi.mocked(fs.readFileSync).mockReturnValue("# 日誌" as unknown as ReturnType<typeof fs.readFileSync>);
+    const res = await request(app).get("/api/runs/run_123/diary");
+    expect(res.status).toBe(200);
+    expect(res.body.content).toBe("# 日誌");
+  });
+});
+
+// ================================================================
+// POST /api/runs/:runId/diary
+// ================================================================
+describe("POST /api/runs/:runId/diary", () => {
+  it("不正な runId → 400", async () => {
+    const res = await request(app).post("/api/runs/invalid/diary");
+    expect(res.status).toBe(400);
+  });
+
+  it("アクティブセッションがない + ログファイルなし → 404", async () => {
+    vi.mocked(fs.existsSync).mockReturnValue(false);
+    const res = await request(app).post("/api/runs/run_123/diary");
+    expect(res.status).toBe(404);
+  });
+
+  it("ログファイルがある → generateDiary を呼んで content を返す", async () => {
+    vi.mocked(fs.existsSync).mockReturnValue(true);
+    vi.mocked(fs.readFileSync).mockReturnValue("line1\nline2\n" as unknown as ReturnType<typeof fs.readFileSync>);
+    vi.mocked(generateDiary).mockResolvedValue("# 探索日誌");
+    const res = await request(app).post("/api/runs/run_123/diary");
+    expect(res.status).toBe(200);
+    expect(res.body.content).toBe("# 探索日誌");
+    expect(generateDiary).toHaveBeenCalledWith("run_123", ["line1", "line2"]);
+  });
+
+  it("アクティブセッションがある → session.lines を使う", async () => {
+    (activeSessions as Map<string, unknown>).set("run_123", { lines: ["live line"], done: false });
+    vi.mocked(generateDiary).mockResolvedValue("# ライブ日誌");
+    const res = await request(app).post("/api/runs/run_123/diary");
+    expect(res.status).toBe(200);
+    expect(generateDiary).toHaveBeenCalledWith("run_123", ["live line"]);
+  });
+
+  it("generateDiary が失敗 → 500", async () => {
+    vi.mocked(fs.existsSync).mockReturnValue(true);
+    vi.mocked(fs.readFileSync).mockReturnValue("line\n" as unknown as ReturnType<typeof fs.readFileSync>);
+    vi.mocked(generateDiary).mockRejectedValue(new Error("LLM error"));
+    const res = await request(app).post("/api/runs/run_123/diary");
+    expect(res.status).toBe(500);
+  });
+});
+
+// ================================================================
+// GET /api/findings
+// ================================================================
+describe("GET /api/findings", () => {
+  it("findings ディレクトリがない → 空配列", async () => {
+    vi.mocked(fs.existsSync).mockReturnValue(false);
+    const res = await request(app).get("/api/findings");
+    expect(res.status).toBe(200);
+    expect(res.body).toEqual([]);
+  });
+
+  it("findings を timestamp 降順で返す", async () => {
+    const older = mockFinding({ id: "f1", runId: "run_1", timestamp: "2026-01-01T00:00:00.000Z" });
+    const newer = mockFinding({ id: "f2", runId: "run_2", timestamp: "2026-06-01T00:00:00.000Z" });
+    setupFindingsDir({ run_1: [older], run_2: [newer] });
+    const res = await request(app).get("/api/findings");
+    expect(res.status).toBe(200);
+    expect(res.body[0].timestamp).toBe("2026-06-01T00:00:00.000Z");
+    expect(res.body[1].timestamp).toBe("2026-01-01T00:00:00.000Z");
+  });
+
+  it("run_\\d+ 以外のディレクトリは無視する", async () => {
+    vi.mocked(fs.existsSync).mockReturnValue(true);
+    vi.mocked(fs.readdirSync).mockReturnValue([".DS_Store", "tmp"] as unknown as ReturnType<typeof fs.readdirSync>);
+    const res = await request(app).get("/api/findings");
+    expect(res.body).toEqual([]);
+  });
+});
+
+// ================================================================
+// GET /api/findings/export
+// ================================================================
+describe("GET /api/findings/export", () => {
+  it("正しい Content-Disposition ヘッダーを返す", async () => {
+    vi.mocked(fs.existsSync).mockReturnValue(false);
+    const res = await request(app).get("/api/findings/export");
+    expect(res.status).toBe(200);
+    expect(res.headers["content-disposition"]).toContain("attachment");
+    expect(res.headers["content-disposition"]).toContain(".json");
+  });
+
+  it("レスポンスに version / exportedAt / source / findings が含まれる", async () => {
+    vi.mocked(fs.existsSync).mockReturnValue(false);
+    const res = await request(app).get("/api/findings/export");
+    expect(res.body.version).toBe("1");
+    expect(res.body.source).toBe("shoal");
+    expect(typeof res.body.exportedAt).toBe("string");
+    expect(Array.isArray(res.body.findings)).toBe(true);
+  });
+
+  it("findings の screenshotPath は除外される", async () => {
+    const f = mockFinding({ screenshotPath: "/secret/path.png" });
+    setupFindingsDir({ run_1: [f] });
+    const res = await request(app).get("/api/findings/export");
+    expect(res.body.findings[0]).not.toHaveProperty("screenshotPath");
+  });
+});
+
+// ================================================================
+// POST /api/findings/proxy-url — SSRF 防御テスト
+// ================================================================
+describe("POST /api/findings/proxy-url", () => {
+  it("url パラメータなし → 400", async () => {
+    const res = await request(app).post("/api/findings/proxy-url").send({});
+    expect(res.status).toBe(400);
+  });
+
+  it("http / https 以外のプロトコル → 400", async () => {
+    const cases = ["file:///etc/passwd", "javascript:alert(1)", "ftp://example.com"];
+    for (const url of cases) {
+      const res = await request(app).post("/api/findings/proxy-url").send({ url });
+      expect(res.status).toBe(400);
+    }
+  });
+
+  it("localhost → 400（SSRF 防御）", async () => {
+    const res = await request(app).post("/api/findings/proxy-url").send({ url: "http://localhost/data.json" });
+    expect(res.status).toBe(400);
+  });
+
+  it("127.0.0.1 → 400（SSRF 防御）", async () => {
+    const res = await request(app).post("/api/findings/proxy-url").send({ url: "http://127.0.0.1/data.json" });
+    expect(res.status).toBe(400);
+  });
+
+  it("::1（IPv6 localhost）→ 400（SSRF 防御）", async () => {
+    const res = await request(app).post("/api/findings/proxy-url").send({ url: "http://[::1]/data.json" });
+    expect(res.status).toBe(400);
+  });
+
+  it("192.168.x.x → 400（SSRF 防御）", async () => {
+    const res = await request(app).post("/api/findings/proxy-url").send({ url: "http://192.168.1.1/data.json" });
+    expect(res.status).toBe(400);
+  });
+
+  it("10.x.x.x → 400（SSRF 防御）", async () => {
+    const res = await request(app).post("/api/findings/proxy-url").send({ url: "http://10.0.0.1/data.json" });
+    expect(res.status).toBe(400);
+  });
+
+  it(".local ドメイン → 400（SSRF 防御）", async () => {
+    const res = await request(app).post("/api/findings/proxy-url").send({ url: "http://myserver.local/data.json" });
+    expect(res.status).toBe(400);
+  });
+
+  it("正常な外部 URL → upstream レスポンスを返す", async () => {
+    const bundle = { version: "1", source: "shoal", findings: [] };
+    vi.stubGlobal("fetch", vi.fn().mockResolvedValue({
+      ok: true,
+      json: async () => bundle,
+    }));
+    const res = await request(app).post("/api/findings/proxy-url").send({ url: "https://raw.githubusercontent.com/example/data.json" });
+    expect(res.status).toBe(200);
+    expect(res.body.version).toBe("1");
+    vi.unstubAllGlobals();
+  });
+
+  it("upstream が失敗 → 502", async () => {
+    vi.stubGlobal("fetch", vi.fn().mockResolvedValue({
+      ok: false,
+      status: 503,
+    }));
+    const res = await request(app).post("/api/findings/proxy-url").send({ url: "https://example.com/data.json" });
+    expect(res.status).toBe(502);
+    vi.unstubAllGlobals();
+  });
+
+  it("fetch 例外（タイムアウト等）→ 502", async () => {
+    vi.stubGlobal("fetch", vi.fn().mockRejectedValue(new Error("AbortError")));
+    const res = await request(app).post("/api/findings/proxy-url").send({ url: "https://example.com/data.json" });
+    expect(res.status).toBe(502);
+    vi.unstubAllGlobals();
+  });
+});
+
+// ================================================================
+// PATCH /api/schedule — 既存エンドポイントのバリデーション
+// ================================================================
+describe("PATCH /api/schedule", () => {
+  it("範囲外の dayOfWeek（-1, 7）は無視してデフォルト値を維持する", async () => {
+    const { loadSchedule } = await import("../scheduler.js");
+    vi.mocked(loadSchedule).mockReturnValue({ enabled: false, dayOfWeek: 1, hour: 9, minute: 0, lastRunDate: null });
+    const res = await request(app).patch("/api/schedule").send({ dayOfWeek: -1 });
+    expect(res.status).toBe(200);
+    expect(res.body.dayOfWeek).toBe(1); // デフォルト値を維持
+  });
+
+  it("範囲外の hour（24）は無視する", async () => {
+    const { loadSchedule } = await import("../scheduler.js");
+    vi.mocked(loadSchedule).mockReturnValue({ enabled: false, dayOfWeek: 1, hour: 9, minute: 0, lastRunDate: null });
+    const res = await request(app).patch("/api/schedule").send({ hour: 24 });
+    expect(res.status).toBe(200);
+    expect(res.body.hour).toBe(9);
+  });
+
+  it("enabled に数値を渡すと Boolean 変換される", async () => {
+    const { loadSchedule } = await import("../scheduler.js");
+    vi.mocked(loadSchedule).mockReturnValue({ enabled: false, dayOfWeek: 1, hour: 9, minute: 0, lastRunDate: null });
+    const res = await request(app).patch("/api/schedule").send({ enabled: 1 });
+    expect(res.status).toBe(200);
+    expect(res.body.enabled).toBe(true);
+  });
+});

package/server/__tests__/scheduler.test.ts

@@ -83,15 +83,17 @@ describe("scheduler — 時刻判定ロジック", () => {
   it("スケジュール時刻に一致したとき spawnRun を呼ぶ", async () => {
     vi.useFakeTimers();
 
-    // 月曜 09:00 に固定（UTC = ローカルとして扱う）
+    // 月曜 09:00 に固定。scheduler は new Date().getDay() などローカル時刻を使うため、
+    // テスト設定も同じメソッドで一致させる（環境のタイムゾーンに依存するが両者が整合する）
     const monday9am = new Date("2026-05-11T09:00:00.000Z");
     vi.setSystemTime(monday9am);
+    const now = new Date();
 
     const config: ScheduleConfig = {
       enabled: true,
-      dayOfWeek: monday9am.getDay(),
-      hour: monday9am.getHours(),
-      minute: monday9am.getMinutes(),
+      dayOfWeek: now.getDay(),
+      hour: now.getHours(),
+      minute: now.getMinutes(),
       lastRunDate: null,
     };
     vi.mocked(fs.existsSync).mockReturnValue(true);
@@ -111,13 +113,14 @@ describe("scheduler — 時刻判定ロジック", () => {
 
     const monday9am = new Date("2026-05-11T09:00:00.000Z");
     vi.setSystemTime(monday9am);
-    const today = monday9am.toISOString().slice(0, 10);
+    const now = new Date();
+    const today = now.toISOString().slice(0, 10); // scheduler と同じ UTC 日付を使う
 
     const config: ScheduleConfig = {
       enabled: true,
-      dayOfWeek: monday9am.getDay(),
-      hour: monday9am.getHours(),
-      minute: monday9am.getMinutes(),
+      dayOfWeek: now.getDay(),
+      hour: now.getHours(),
+      minute: now.getMinutes(),
       lastRunDate: today,
     };
     vi.mocked(fs.existsSync).mockReturnValue(true);

package/server/index.ts

@@ -174,7 +174,8 @@ app.post("/api/findings/proxy-url", async (req, res) => {
     parsed = new URL(url);
     if (!["http:", "https:"].includes(parsed.protocol)) throw new Error("invalid protocol");
     const h = parsed.hostname;
-    if (h === "localhost" || h === "127.0.0.1" || h === "::1" || h.startsWith("192.168.") || h.startsWith("10.") || h.endsWith(".local")) {
+    const bare = h.replace(/^\[|\]$/g, ""); // IPv6 brackets: [::1] → ::1
+    if (bare === "localhost" || bare === "127.0.0.1" || bare === "::1" || bare.startsWith("192.168.") || bare.startsWith("10.") || bare.endsWith(".local")) {
       res.status(400).json({ error: "private urls not allowed" });
       return;
     }
@@ -372,7 +373,11 @@ app.patch("/api/schedule", (req, res) => {
   res.json(updated);
 });
 
-app.listen(PORT, () => {
-  console.log(`\nshoal dashboard → http://localhost:${PORT}\n`);
-  startScheduler();
-});
+export { app };
+
+if (process.env.NODE_ENV !== "test") {
+  app.listen(PORT, () => {
+    console.log(`\nshoal dashboard → http://localhost:${PORT}\n`);
+    startScheduler();
+  });
+}