@m8i-51/shoal 0.1.0 → 0.1.2

package/.env.example

@@ -0,0 +1,76 @@
+# ================================================================
+# LLM Provider
+# ================================================================
+# LLM_PROVIDER に使いたいプロバイダ名を設定してください。
+# LLM_BASE_URL / LLM_MODEL は省略時にプロバイダのデフォルト値が使われます。
+
+# --- Anthropic (default) ---
+# LLM_PROVIDER=anthropic
+# ANTHROPIC_API_KEY=sk-ant-...
+# LLM_MODEL=claude-haiku-4-5-20251001   # 省略可
+
+# --- OpenAI ---
+# LLM_PROVIDER=openai
+# LLM_API_KEY=sk-...
+# LLM_MODEL=gpt-4o-mini                 # 省略可（デフォルト: gpt-4o-mini）
+
+# --- OpenAI Codex (ChatGPT サブスク OAuth) ---
+# 事前に認証が必要: npm run auth:codex
+# LLM_PROVIDER=codex
+# LLM_MODEL=gpt-5.1-codex-mini          # 省略可
+
+# --- Groq (無料枠あり・高速) ---
+# https://console.groq.com でキー取得
+# LLM_PROVIDER=groq
+# LLM_API_KEY=gsk_...
+# LLM_MODEL=llama-3.3-70b-versatile     # 省略可
+
+# --- Google Gemini (無料枠あり) ---
+# https://aistudio.google.com でキー取得
+# LLM_PROVIDER=gemini
+# LLM_API_KEY=AIzaSy...
+# LLM_MODEL=gemini-2.0-flash            # 省略可
+
+# --- Ollama (ローカル / クラウド) ---
+# LLM_PROVIDER=ollama
+# LLM_MODEL=llama3.2                    # 省略可
+# LLM_API_KEY=                          # クラウドモデルの場合は API キーを設定
+# LLM_BASE_URL=http://localhost:11434/v1 # 省略可（ローカルのデフォルト値）
+
+# --- LM Studio (ローカル) ---
+# LLM_PROVIDER=lm-studio
+# LLM_MODEL=<LM Studio に表示されるモデル名>
+# LLM_BASE_URL=http://localhost:1234/v1  # 省略可（デフォルト値）
+
+# --- OpenRouter (多数のモデルにアクセス可) ---
+# https://openrouter.ai でキー取得
+# LLM_PROVIDER=openrouter
+# LLM_API_KEY=sk-or-...
+# LLM_MODEL=google/gemini-flash-1.5     # 省略可 / モデル一覧: openrouter.ai/models
+
+# --- その他 OpenAI 互換エンドポイント ---
+# LLM_PROVIDER=openai
+# LLM_BASE_URL=https://your-endpoint/v1
+# LLM_API_KEY=your-key
+# LLM_MODEL=your-model
+
+# ================================================================
+# Target app
+# ================================================================
+
+TARGET=none             # example | none | カスタムターゲット名
+BASE_URL=http://localhost:3000
+
+# ================================================================
+# GitHub Issues (optional)
+# ================================================================
+
+GITHUB_TOKEN=
+GITHUB_REPO=owner/repo
+
+# ================================================================
+# Run config
+# ================================================================
+
+MAX_EXPLORERS=4
+MAX_BROWSERS=2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 m8i-51
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -2,13 +2,16 @@
 
 # shoal
 
+[![npm](https://img.shields.io/npm/v/@m8i-51/shoal?color=red)](https://www.npmjs.com/package/@m8i-51/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.
+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, and goal alignment. They explore independently via API and real browser, then a triage agent deduplicates findings and files GitHub Issues.
+
+A **web dashboard** lets you start runs, monitor live progress, review findings by category, and track estimated LLM cost per run.
 
 No test scripts. No test data. No prior knowledge of the app required.
 
@@ -19,7 +22,7 @@ No test scripts. No test data. No prior knowledge of the app required.
 ```
 Target App (any URL)
         │
-        ▼  autonomously learns what the app does
+        ▼  autonomously learns what the app does + its goals
   Product Discovery
         │
         ▼  generates a user persona team for that app
@@ -42,6 +45,36 @@ Target App (any URL)
 
 ## Quick Start
 
+**Install globally:**
+
+```bash
+npm install -g @m8i-51/shoal
+npx playwright install chromium
+```
+
+Move to the project you want to test, then run:
+
+```bash
+cd your-project
+shoal init     # creates .env with all available options
+```
+
+Open `.env` and set at minimum:
+
+```env
+ANTHROPIC_API_KEY=sk-ant-...
+BASE_URL=http://localhost:3000   # URL of the app to test
+```
+
+Then run:
+
+```bash
+shoal serve    # open web dashboard at http://localhost:4000
+shoal          # or run agents directly from the terminal
+```
+
+**Or clone and develop locally:**
+
 ```bash
 git clone https://github.com/m8i-51/shoal
 cd shoal
@@ -52,6 +85,23 @@ npm start
 
 ---
 
+## Web dashboard
+
+```bash
+shoal serve        # global install
+# or
+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
+- **Review past runs** — findings by category, agent count, duration, and estimated cost
+- **Edit app goals** — guide the goal-gap detector by defining what the app should achieve
+
+---
+
 ## Configuration
 
 | Variable | Default | Description |
@@ -70,20 +120,22 @@ npm start
 
 shoal loads `shoal.config.ts` from the **current working directory** at startup. Two common setups:
 
-**Option A — config inside the shoal repo** (simplest)
+**Option A — config in your project directory** (recommended)
 
 ```bash
-cp shoal.config.example.ts shoal.config.ts
-# edit shoal.config.ts, then:
-npm start
+# Copy the example from the repo (or create from scratch)
+curl -O https://raw.githubusercontent.com/m8i-51/shoal/main/shoal.config.example.ts
+mv shoal.config.example.ts shoal.config.ts
+# Edit shoal.config.ts, then:
+shoal
 ```
 
-**Option B — config in your project directory** (keeps shoal untouched)
+**Option B — config inside the cloned repo** (simplest for development)
 
 ```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
+cp shoal.config.example.ts shoal.config.ts
+# edit shoal.config.ts, then:
+npm start
 ```
 
 `shoal.config.ts` must export a `target` object with two fields:
@@ -106,6 +158,21 @@ Alternatively, copy `targets/example.ts`, register it in `targets/index.ts`, and
 
 ---
 
+## Account Manager
+
+For apps that require login, shoal includes an Account Manager agent that autonomously discovers and tests authentication. It finds login pages, tests credentials from `test-accounts/` (gitignored), and injects session state into explorer agents so they can reach authenticated routes.
+
+Create `test-accounts/accounts.json` with your test credentials:
+
+```json
+[
+  { "email": "test@example.com", "password": "testpassword", "role": "user" },
+  { "email": "admin@example.com", "password": "adminpassword", "role": "admin" }
+]
+```
+
+---
+
 ## LLM providers
 
 shoal defaults to Anthropic Claude. To use a different provider, set these variables in `.env`:
@@ -114,8 +181,15 @@ shoal defaults to Anthropic Claude. To use a different provider, set these varia
 |---|---|
 | Anthropic (default) | `ANTHROPIC_API_KEY` |
 | OpenAI | `LLM_PROVIDER=openai`, `LLM_API_KEY`, `LLM_MODEL` |
+| OpenRouter | `LLM_PROVIDER=openrouter`, `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.
+
+---
+
+## License
+
+[MIT](LICENSE)

package/bin/init.js

@@ -0,0 +1,106 @@
+import { intro, outro, select, text, isCancel, cancel } from "@clack/prompts";
+import { writeFileSync, existsSync } from "fs";
+import { join } from "path";
+
+const PROVIDERS = [
+  { value: "anthropic",   label: "Anthropic (Claude)",  hint: "recommended",        defaultModel: "claude-haiku-4-5-20251001" },
+  { value: "openai",      label: "OpenAI",                                           defaultModel: "gpt-4o-mini" },
+  { value: "groq",        label: "Groq",                hint: "free tier available", defaultModel: "llama-3.3-70b-versatile" },
+  { value: "gemini",      label: "Gemini",              hint: "free tier available", defaultModel: "gemini-2.0-flash" },
+  { value: "ollama",      label: "Ollama",              hint: "local",               defaultModel: null },
+  { value: "lm-studio",   label: "LM Studio",          hint: "local",               defaultModel: null },
+  { value: "openrouter",  label: "OpenRouter",                                       defaultModel: "google/gemini-flash-1.5" },
+];
+
+function guard(value) {
+  if (isCancel(value)) {
+    cancel("Setup cancelled.");
+    process.exit(0);
+  }
+  return value;
+}
+
+export async function runInit(cwd) {
+  const envPath = join(cwd, ".env");
+
+  if (existsSync(envPath)) {
+    console.log(".env already exists. Delete it and run shoal init again.");
+    process.exit(0);
+  }
+
+  intro("shoal init");
+
+  // ── Provider ──────────────────────────────────────────────────────
+  const provider = guard(await select({
+    message: "LLM provider",
+    options: PROVIDERS,
+  }));
+
+  const env = {};
+
+  const providerDef = PROVIDERS.find((p) => p.value === provider);
+
+  // ── Provider-specific questions ───────────────────────────────────
+  if (provider === "anthropic") {
+    env.ANTHROPIC_API_KEY = guard(await text({
+      message: "ANTHROPIC_API_KEY",
+      placeholder: "sk-ant-...",
+      validate: (v) => v?.trim() ? undefined : "Required",
+    }));
+  } else if (provider === "ollama") {
+    env.LLM_PROVIDER = "ollama";
+    const baseUrl = guard(await text({
+      message: "Ollama base URL",
+      defaultValue: "http://localhost:11434/v1",
+    }));
+    if (baseUrl !== "http://localhost:11434/v1") env.LLM_BASE_URL = baseUrl;
+  } else if (provider === "lm-studio") {
+    env.LLM_PROVIDER = "lm-studio";
+    const baseUrl = guard(await text({
+      message: "LM Studio base URL",
+      defaultValue: "http://localhost:1234/v1",
+    }));
+    if (baseUrl !== "http://localhost:1234/v1") env.LLM_BASE_URL = baseUrl;
+  } else {
+    env.LLM_PROVIDER = provider;
+    env.LLM_API_KEY = guard(await text({
+      message: "API key",
+      placeholder: "sk-...",
+      validate: (v) => v?.trim() ? undefined : "Required",
+    }));
+  }
+
+  const defaultModel = providerDef?.defaultModel;
+  const model = guard(await text({
+    message: "Model name",
+    placeholder: defaultModel ? `leave blank to use ${defaultModel}` : "required",
+    validate: !defaultModel ? (v) => v?.trim() ? undefined : "Required" : undefined,
+  }));
+  if (model.trim()) env.LLM_MODEL = model.trim();
+
+  // ── Target app ────────────────────────────────────────────────────
+  env.BASE_URL = guard(await text({
+    message: "URL of the app to test",
+    defaultValue: "http://localhost:3000",
+  }));
+
+  // ── GitHub (optional) ─────────────────────────────────────────────
+  const githubToken = guard(await text({
+    message: "GitHub token  (optional — for Issue creation)",
+    placeholder: "ghp_...  leave blank to skip",
+  }));
+  if (githubToken.trim()) {
+    env.GITHUB_TOKEN = githubToken.trim();
+    const githubRepo = guard(await text({
+      message: "GitHub repo",
+      placeholder: "owner/repo",
+    }));
+    if (githubRepo.trim()) env.GITHUB_REPO = githubRepo.trim();
+  }
+
+  // ── Write .env ────────────────────────────────────────────────────
+  const lines = Object.entries(env).map(([k, v]) => `${k}=${v}`);
+  writeFileSync(envPath, lines.join("\n") + "\n", "utf-8");
+
+  outro("Created .env\n\n  shoal serve   — open the dashboard at http://localhost:4000\n  shoal         — run agents from the terminal");
+}

package/bin/shoal.js

@@ -3,9 +3,10 @@
  * shoal CLI entry point
  *
  * Usage:
- *   npx shoal              # run exploration
- *   npx shoal triage       # triage-only mode
- *   npx shoal serve        # local web dashboard
+ *   shoal init     # interactive setup — creates .env in current directory
+ *   shoal serve    # web dashboard at http://localhost:4000
+ *   shoal          # run agents from the terminal
+ *   shoal triage   # triage-only mode
  */
 import { spawn, spawnSync } from "child_process";
 import { fileURLToPath } from "url";
@@ -14,43 +15,55 @@ 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);
+async function main() {
+  // init — 対話形式で .env をカレントディレクトリに生成する
+  if (subcommand === "init") {
+    const { runInit } = await import("./init.js");
+    await runInit(process.cwd());
+    process.exit(0);
+  }
+
+  // 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";
+
+  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));
 }
 
-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(),
+main().catch((e) => {
+  console.error(e);
+  process.exit(1);
 });
-
-child.on("exit", (code) => process.exit(code ?? 0));

package/package.json

@@ -1,8 +1,12 @@
 {
   "name": "@m8i-51/shoal",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "type": "module",
   "description": "Multi-agent web exploration framework — finds bugs, UX issues, and missing features by running AI agents against your app",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/m8i-51/shoal"
+  },
   "bin": {
     "shoal": "./bin/shoal.js"
   },
@@ -13,7 +17,8 @@
     "server/",
     "web/dist/",
     "run.ts",
-    "triage-only.ts"
+    "triage-only.ts",
+    ".env.example"
   ],
   "scripts": {
     "prepublishOnly": "npm run build:web",
@@ -29,7 +34,8 @@
     "test:watch": "vitest"
   },
   "dependencies": {
-    "@anthropic-ai/sdk": "^0.81.0",
+    "@anthropic-ai/sdk": "^0.91.1",
+    "@clack/prompts": "^1.3.0",
     "dotenv": "^17.3.1",
     "express": "^5.2.1",
     "openai": "^6.33.0",