@m8i-51/shoal 0.1.20 → 0.1.22

package/.env.example

@@ -19,6 +19,14 @@
 # LLM_PROVIDER=codex
 # LLM_MODEL=gpt-5.1-codex-mini          # 省略可
 
+# --- Amazon Bedrock ---
+# AWS_ACCESS_KEY_ID / AWS_SECRET_ACCESS_KEY / AWS_REGION は AWS SDK が自動で読み取ります
+# LLM_PROVIDER=bedrock
+# AWS_ACCESS_KEY_ID=
+# AWS_SECRET_ACCESS_KEY=
+# AWS_REGION=us-east-1
+# LLM_MODEL=anthropic.claude-3-5-haiku-20241022-v1:0  # 省略可 / クロスリージョン推論プロファイルも対応
+
 # --- Groq (無料枠あり・高速) ---
 # https://console.groq.com でキー取得
 # LLM_PROVIDER=groq
@@ -100,6 +108,9 @@ GITHUB_REPO=owner/repo
 MAX_EXPLORERS=4
 MAX_BROWSERS=2
 
+# 1 に設定するとキャッシュ済みの product spec を無視し product discovery を再実行します
+# REFRESH_SPEC=1
+
 # Persona templates (optional)
 # Path to a local YAML/JSON file, or an npm package name.
 # If omitted, shoal auto-discovers personas.yaml / personas.yml / personas.json in the project root.

package/README.md

@@ -119,6 +119,7 @@ Opens at `http://localhost:4000`. From there you can:
 - **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
+- **Schedule a weekly run** — pick a day and time directly in the dashboard for automatic recurring runs (the `shoal serve` process must stay running; for a serverless alternative see [Scheduled runs](#scheduled-runs) below)
 
 ---
 
@@ -246,6 +247,8 @@ shoal defaults to Anthropic Claude. To use a different provider, set these varia
 | Amazon Bedrock | `LLM_PROVIDER=bedrock`, `AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY`, `AWS_REGION` |
 | OpenAI | `LLM_PROVIDER=openai`, `LLM_API_KEY`, `LLM_MODEL` |
 | OpenRouter | `LLM_PROVIDER=openrouter`, `LLM_API_KEY`, `LLM_MODEL` |
+| Groq | `LLM_PROVIDER=groq`, `LLM_API_KEY`, `LLM_MODEL` |
+| Gemini | `LLM_PROVIDER=gemini`, `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` |

package/framework/coverage.ts

@@ -1,6 +1,6 @@
 import * as fs from "fs";
 import * as path from "path";
-import type { Finding } from "./types";
+import { isFinding, type Finding } from "./types";
 import type { Scenario } from "./scenario-designer";
 
 export interface RunCoverage {
@@ -231,9 +231,10 @@ export function getFindingHotspots(topN = 12): FindingHotspot[] {
     const dir = path.join(base, runDir);
     try {
       for (const file of fs.readdirSync(dir)) {
-        if (!file.endsWith(".json")) continue;
+        if (!file.endsWith(".json") || file === "triage_result.json") continue;
         try {
-          const f: Finding = JSON.parse(fs.readFileSync(path.join(dir, file), "utf-8"));
+          const f: unknown = JSON.parse(fs.readFileSync(path.join(dir, file), "utf-8"));
+          if (!isFinding(f)) continue;
           const p = extractPath(f);
           const entry = counts.get(p) ?? { total: 0, categories: {} };
           entry.total++;

package/framework/cross-run-dedup.ts

@@ -0,0 +1,43 @@
+import type { Finding } from "./types";
+
+function tokenize(text: string): Set<string> {
+  return new Set(text.toLowerCase().match(/[a-z0-9]+/g) ?? []);
+}
+
+function jaccard(a: Set<string>, b: Set<string>): number {
+  const intersection = [...a].filter((x) => b.has(x)).length;
+  const union = new Set([...a, ...b]).size;
+  return union === 0 ? 0 : intersection / union;
+}
+
+/**
+ * タイトル+本文の単語集合の Jaccard 係数で finding をクラスタリングする。
+ * triage は同一 run 内の重複しか除去しないため、run をまたいで
+ * 繰り返し報告されている問題を見つけるための補助。
+ */
+export function groupSimilarFindings(findings: Finding[], threshold = 0.3): Finding[][] {
+  const tokensByIndex = findings.map((f) => tokenize(`${f.title} ${f.body}`));
+  const seen = new Set<number>();
+  const clusters: Finding[][] = [];
+
+  for (let i = 0; i < findings.length; i++) {
+    if (seen.has(i)) continue;
+    const clusterIndices = [i];
+    for (let j = i + 1; j < findings.length; j++) {
+      if (seen.has(j)) continue;
+      if (jaccard(tokensByIndex[i], tokensByIndex[j]) >= threshold) {
+        clusterIndices.push(j);
+        seen.add(j);
+      }
+    }
+    seen.add(i);
+    clusters.push(clusterIndices.map((idx) => findings[idx]));
+  }
+
+  return clusters;
+}
+
+/** 2件以上で構成されるクラスタ（= run をまたいだ重複候補）のみ返す */
+export function findCrossRunDuplicates(findings: Finding[], threshold = 0.3): Finding[][] {
+  return groupSimilarFindings(findings, threshold).filter((cluster) => cluster.length > 1);
+}

package/framework/diary.ts

@@ -1,16 +1,18 @@
 import * as fs from "fs";
 import * as path from "path";
 import { createLLMClient } from "./llm-client.js";
-import type { Finding } from "./types.js";
+import { isFinding, type Finding } from "./types.js";
 
 function loadFindings(runId: string): Finding[] {
   const dir = path.join(process.cwd(), "findings", runId);
   if (!fs.existsSync(dir)) return [];
   const out: Finding[] = [];
   for (const file of fs.readdirSync(dir)) {
-    if (!file.endsWith(".json")) continue;
+    if (!file.endsWith(".json") || file === "triage_result.json") continue;
     try {
-      out.push(JSON.parse(fs.readFileSync(path.join(dir, file), "utf-8")));
+      const f: unknown = JSON.parse(fs.readFileSync(path.join(dir, file), "utf-8"));
+      if (!isFinding(f)) continue;
+      out.push(f);
     } catch { /* skip */ }
   }
   return out;

package/framework/llm-client.ts

@@ -200,7 +200,10 @@ class OpenAICompatClient {
   private defaultModel: string;
 
   constructor(apiKey: string, baseURL?: string, defaultModel?: string) {
-    this.client = new OpenAI({ apiKey, baseURL });
+    // ローカルプロバイダ（Ollama/LM Studio）は空のキーで使われることがある。
+    // openai SDK は空文字列のキーをコンストラクタで拒否するバージョンがあるため、
+    // ダミー値で代替する（API互換エンドポイント側はキーを検証しない）。
+    this.client = new OpenAI({ apiKey: apiKey || "not-needed", baseURL });
     this.defaultModel = defaultModel ?? "gpt-4o-mini";
   }
 

package/framework/types.ts

@@ -25,6 +25,17 @@ export interface Finding {
   screenshotPath?: string;
 }
 
+/**
+ * findings/run_<id>/ ディレクトリには各 finding の JSON と並んで
+ * triage_result.json（集計ファイル、Finding ではない）が置かれる。
+ * 読み込んだ JSON が実際に Finding かどうかをここで一括判定する。
+ */
+export function isFinding(v: unknown): v is Finding {
+  if (typeof v !== "object" || v === null) return false;
+  const o = v as Record<string, unknown>;
+  return typeof o.id === "string" && typeof o.category === "string" && typeof o.timestamp === "string";
+}
+
 export interface RegressionCheck {
   issueNumber: number;
   issueTitle: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@m8i-51/shoal",
-  "version": "0.1.20",
+  "version": "0.1.22",
   "type": "module",
   "description": "Multi-agent web exploration framework — finds bugs, UX issues, and missing features by running AI agents against your app",
   "repository": {
@@ -18,7 +18,8 @@
     "web/dist/",
     "run.ts",
     "triage-only.ts",
-    ".env.example"
+    ".env.example",
+    "!**/__tests__/**"
   ],
   "scripts": {
     "prepublishOnly": "npm run build:web",
@@ -31,7 +32,8 @@
     "build:web": "vite build web",
     "auth:codex": "tsx scripts/auth-codex.ts",
     "test": "vitest run",
-    "test:watch": "vitest"
+    "test:watch": "vitest",
+    "test:coverage": "vitest run --coverage"
   },
   "dependencies": {
     "@anthropic-ai/bedrock-sdk": "^0.29.1",
@@ -42,7 +44,7 @@
     "express-rate-limit": "^8.5.0",
     "openai": "^6.33.0",
     "playwright": "^1.59.1",
-    "tsx": "^4.21.0",
+    "tsx": "^4.22.4",
     "yaml": "^2.9.0"
   },
   "devDependencies": {

package/server/index.ts

@@ -8,7 +8,8 @@ import { listRuns, getReportPath } from "./runs.js";
 import { activeSessions, spawnRun, cancelSession } from "./runner.js";
 import { loadSchedule, saveSchedule, startScheduler, type ScheduleConfig } from "./scheduler.js";
 import { generateDiary, getDiaryPath } from "../framework/diary.js";
-import type { Finding } from "../framework/types.js";
+import { findCrossRunDuplicates } from "../framework/cross-run-dedup.js";
+import { isFinding, type Finding } from "../framework/types.js";
 
 function specFilePath(baseUrl: string): string {
   try {
@@ -141,9 +142,10 @@ function loadAllFindings(): (Finding & { runId: string })[] {
     const dir = join(base, runDir);
     try {
       for (const file of readdirSync(dir)) {
-        if (!file.endsWith(".json")) continue;
+        if (!file.endsWith(".json") || file === "triage_result.json") continue;
         try {
-          const f: Finding = JSON.parse(readFileSync(join(dir, file), "utf-8"));
+          const f: unknown = JSON.parse(readFileSync(join(dir, file), "utf-8"));
+          if (!isFinding(f)) continue;
           all.push({ ...f, runId: runDir });
         } catch { /* skip */ }
       }
@@ -156,6 +158,10 @@ app.get("/api/findings", (_req, res) => {
   res.json(loadAllFindings());
 });
 
+app.get("/api/findings/cross-run-duplicates", (_req, res) => {
+  res.json(findCrossRunDuplicates(loadAllFindings()));
+});
+
 app.get("/api/findings/export", (_req, res) => {
   const findings = loadAllFindings().map(({ id, title, body, category, agentName, role, timestamp, runId }) => ({
     id, title, body, category, agentName, role, timestamp, runId,
@@ -321,6 +327,27 @@ app.get("/api/runs/:runId/log", (req, res) => {
   res.status(404).json({ error: "no log found" });
 });
 
+// ----------------------------------------------------------------
+// API: schedule config
+// ----------------------------------------------------------------
+app.get("/api/schedule", (_req, res) => {
+  res.json(loadSchedule());
+});
+
+app.patch("/api/schedule", (req, res) => {
+  const current = loadSchedule();
+  const { enabled, dayOfWeek, hour, minute } = req.body as Partial<ScheduleConfig>;
+  const updated: ScheduleConfig = {
+    ...current,
+    ...(enabled != null ? { enabled: Boolean(enabled) } : {}),
+    ...(dayOfWeek != null && Number.isInteger(dayOfWeek) && dayOfWeek >= 0 && dayOfWeek <= 6 ? { dayOfWeek } : {}),
+    ...(hour != null && Number.isInteger(hour) && hour >= 0 && hour <= 23 ? { hour } : {}),
+    ...(minute != null && Number.isInteger(minute) && minute >= 0 && minute <= 59 ? { minute } : {}),
+  };
+  saveSchedule(updated);
+  res.json(updated);
+});
+
 // ----------------------------------------------------------------
 // Static: serve built React app
 // ----------------------------------------------------------------
@@ -352,27 +379,6 @@ process.on("unhandledRejection", (reason) => {
   console.error("[server] unhandledRejection:", reason);
 });
 
-// ----------------------------------------------------------------
-// API: schedule config
-// ----------------------------------------------------------------
-app.get("/api/schedule", (_req, res) => {
-  res.json(loadSchedule());
-});
-
-app.patch("/api/schedule", (req, res) => {
-  const current = loadSchedule();
-  const { enabled, dayOfWeek, hour, minute } = req.body as Partial<ScheduleConfig>;
-  const updated: ScheduleConfig = {
-    ...current,
-    ...(enabled != null ? { enabled: Boolean(enabled) } : {}),
-    ...(dayOfWeek != null && Number.isInteger(dayOfWeek) && dayOfWeek >= 0 && dayOfWeek <= 6 ? { dayOfWeek } : {}),
-    ...(hour != null && Number.isInteger(hour) && hour >= 0 && hour <= 23 ? { hour } : {}),
-    ...(minute != null && Number.isInteger(minute) && minute >= 0 && minute <= 59 ? { minute } : {}),
-  };
-  saveSchedule(updated);
-  res.json(updated);
-});
-
 export { app };
 
 if (process.env.NODE_ENV !== "test") {

package/server/runs.ts

@@ -1,6 +1,6 @@
 import * as fs from "fs";
 import * as path from "path";
-import type { RunLog, Finding } from "../framework/types";
+import { isFinding, type RunLog } from "../framework/types";
 
 export interface RunSummary {
   runId: string;
@@ -25,9 +25,10 @@ function countFindings(runId: string): { total: number; byCategory: Record<strin
   const byCategory: Record<string, number> = {};
   let total = 0;
   for (const file of fs.readdirSync(dir)) {
-    if (!file.endsWith(".json")) continue;
+    if (!file.endsWith(".json") || file === "triage_result.json") continue;
     try {
-      const f: Finding = JSON.parse(fs.readFileSync(path.join(dir, file), "utf-8"));
+      const f: unknown = JSON.parse(fs.readFileSync(path.join(dir, file), "utf-8"));
+      if (!isFinding(f)) continue;
       byCategory[f.category] = (byCategory[f.category] ?? 0) + 1;
       total++;
     } catch {