@m8i-51/shoal 0.1.1 → 0.1.3

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/README.md

@@ -52,20 +52,25 @@ npm install -g @m8i-51/shoal
 npx playwright install chromium
 ```
 
-Create a `.env` in your working directory:
+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
-# GITHUB_TOKEN=...   # optional: enables Issue creation
-# GITHUB_REPO=owner/repo
+BASE_URL=http://localhost:3000   # URL of the app to test
 ```
 
 Then run:
 
 ```bash
-shoal          # run agents against BASE_URL
 shoal serve    # open web dashboard at http://localhost:4000
+shoal          # or run agents directly from the terminal
 ```
 
 **Or clone and develop locally:**

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.1",
+  "version": "0.1.3",
   "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",