@m8i-51/shoal 0.1.0

package/framework/org-designer.ts

@@ -0,0 +1,85 @@
+import Anthropic from "@anthropic-ai/sdk";
+import type { LLMClient } from "./llm-client";
+import { createMessageWithRetry } from "./agent-loop";
+import type { ProductSpec } from "./product-discovery";
+
+export interface OrgDesign {
+  hrGuidance: string;
+}
+
+// Evaluation lenses always included regardless of app type / アプリ種別に関わらず常に含める観点
+export const UNIVERSAL_LENSES = [
+  "Accessibility: keyboard navigation, screen reader compatibility, error message clarity, non-color-dependent information, sufficient contrast, focus indicators / アクセシビリティ観点",
+  "Security: missing auth checks, input validation gaps, excessive error detail exposure, CSRF exposure, sensitive data in URLs / セキュリティ観点",
+  "Business logic: calculation accuracy, status transitions, approval flow correctness, edge case handling in forms / ビジネスロジック観点",
+  "Data integrity: UI reflects actual state after actions, silent save failures, optimistic update inconsistencies / データ整合性観点",
+  "New user: first-time usability, onboarding clarity, instruction completeness, error recovery, empty state messaging / 新規ユーザー観点",
+  "UX design: interaction feedback (loading states, success/error messages), form usability, modal and dialog behavior, navigation consistency, micro-interactions — evaluate against established patterns from Apple HIG and Material Design (clear affordances, immediate feedback, forgiving interactions) / UXデザイン観点",
+  "Visual design: spacing and alignment consistency, typography hierarchy, color usage and contrast, component coherence across screens, mobile responsiveness — flag anything that looks broken, cramped, or visually inconsistent / ビジュアルデザイン観点",
+  "Product/PM: feature discoverability, user journey clarity, obvious next actions, drop-off risk points, call-to-action prominence, whether the app communicates its value clearly, missing features that users of this type would expect / プロダクト・PM観点",
+  "Power user: keyboard shortcuts availability, bulk operations, filtering/sorting depth, export options, API access, customization options / パワーユーザー観点",
+  "Mobile/touch: touch target sizes, gesture support, viewport adaptation, thumb-reachable key actions / モバイル・タッチ観点",
+];
+
+export async function designOrg(spec: ProductSpec, client: LLMClient, model: string, coverageSummary?: string): Promise<OrgDesign> {
+  console.log("\n[org-design] starting...");
+
+  const response = await createMessageWithRetry(client, {
+    model,
+    max_tokens: 1024,
+    system: `You are a software QA expert.
+Given an app specification, infer the organization and user base,
+then define an agent recruitment policy for testing.`,
+    tools: [],
+    messages: [
+      {
+        role: "user",
+        content: `Design a test agent recruitment policy for the following app.
+
+[App Overview]
+${spec.appDescription}
+
+[Target Users]
+${spec.targetUsers}
+
+[Implemented Features]
+${spec.features}
+${spec.designContext ? `\n[Design Context]\n${spec.designContext}\n` : ""}${coverageSummary ? `\n[Coverage History]\n${coverageSummary}\nUse this to identify underrepresented perspectives and adjust the recruitment policy accordingly.\n` : ""}
+Please output the following:
+
+## User types for this app
+(What kinds of users exist — roles, skill levels, usage scenarios)
+
+## Agent types to recruit (5–8 types)
+By job function, role, and technical literacy. Always include:
+- At least one UX/product designer persona (evaluates visual consistency, interaction patterns, HIG/Material compliance)
+- At least one product manager or business analyst persona (evaluates feature completeness, user journey clarity)
+- At least one target end-user with low technical literacy (first-time or reluctant user)
+- Domain-specific roles relevant to this app type
+
+## Recruitment instructions for the HR agent
+(Concrete hiring/retirement guidelines based on the above — emphasize persona diversity across technical skill levels, job functions, and design sensitivity)`,
+      },
+    ],
+  });
+
+  const text = response.content
+    .filter((b): b is Anthropic.TextBlock => b.type === "text")
+    .map((b) => b.text)
+    .join("");
+
+  const hrGuidance = `${text}
+
+[Universal Evaluation Lenses]
+Include one of the following perspectives in each agent's persona to ensure diverse findings:
+${UNIVERSAL_LENSES.map((l) => `- ${l}`).join("\n")}
+
+[Design Standards Reference]
+When recruiting UX/design-oriented agents, give them awareness of these standards:
+- Apple HIG: clear visual hierarchy, immediate feedback, forgiveness (undo/cancel), consistent navigation, minimal cognitive load
+- Material Design: meaningful motion, bold clear typography, responsive layout, accessible color contrast (WCAG AA minimum)
+- General web conventions: F-pattern reading, above-the-fold CTAs, error prevention over error recovery, progressive disclosure for complex forms`;
+
+  console.log("[org-design] done");
+  return { hrGuidance };
+}

package/framework/product-discovery.ts

@@ -0,0 +1,327 @@
+import * as fs from "fs";
+import * as path from "path";
+import type { Page } from "playwright";
+import type { LLMClient } from "./llm-client";
+import { createMessageWithRetry } from "./agent-loop";
+import Anthropic from "@anthropic-ai/sdk";
+
+// ================================================================
+// Documentation gathering (local or GitHub)
+// ================================================================
+
+const DOC_CANDIDATES = [
+  "README.md", "README_JA.md", "README.ja.md", "README.txt",
+  "docs/index.md", "docs/overview.md", "docs/README.md",
+  "openapi.json", "openapi.yaml", "swagger.json", "swagger.yaml",
+  "package.json",
+];
+const MAX_DOC_CHARS = 6000;
+
+function readLocalDocs(projectPath: string): string {
+  const sections: string[] = [];
+  let totalChars = 0;
+
+  for (const candidate of DOC_CANDIDATES) {
+    if (totalChars >= MAX_DOC_CHARS) break;
+    const filePath = path.join(projectPath, candidate);
+    if (!fs.existsSync(filePath)) continue;
+    try {
+      let content = fs.readFileSync(filePath, "utf-8");
+      if (candidate === "package.json") {
+        // package.json は name / description / scripts だけ抜く
+        const pkg = JSON.parse(content) as Record<string, unknown>;
+        content = JSON.stringify({ name: pkg.name, description: pkg.description, scripts: pkg.scripts }, null, 2);
+      }
+      const remaining = MAX_DOC_CHARS - totalChars;
+      const chunk = content.slice(0, remaining);
+      sections.push(`### ${candidate}\n${chunk}`);
+      totalChars += chunk.length;
+      console.log(`  [product-discovery] local doc: ${candidate} (${chunk.length} chars)`);
+    } catch {
+      // ignore unreadable files
+    }
+  }
+
+  return sections.join("\n\n");
+}
+
+async function fetchGitHubReadme(githubRepo: string): Promise<string> {
+  for (const branch of ["main", "master"]) {
+    const url = `https://raw.githubusercontent.com/${githubRepo}/${branch}/README.md`;
+    try {
+      const res = await fetch(url, { signal: AbortSignal.timeout(8000) });
+      if (!res.ok) continue;
+      const text = await res.text();
+      const content = text.slice(0, MAX_DOC_CHARS);
+      console.log(`  [product-discovery] GitHub README fetched (${content.length} chars, branch: ${branch})`);
+      return `### README.md (GitHub: ${githubRepo})\n${content}`;
+    } catch {
+      continue;
+    }
+  }
+  return "";
+}
+
+async function gatherDocumentation(projectPath?: string): Promise<string> {
+  if (projectPath) {
+    const docs = readLocalDocs(projectPath);
+    if (docs) return docs;
+    console.log("  [product-discovery] local docs: nothing found, falling back to GitHub");
+  }
+
+  const githubRepo = process.env.GITHUB_REPO ?? "";
+  if (githubRepo && githubRepo !== "owner/repo") {
+    return fetchGitHubReadme(githubRepo);
+  }
+
+  return "";
+}
+
+export interface ProductSpec {
+  appName: string;
+  appDescription: string;
+  targetUsers: string;
+  features: string;
+  designContext: string;
+  uiFeatures: string;
+  appGoals: string[];
+  confidence: "high" | "medium" | "low";
+  sources: string[];
+  discoveredAt?: string;
+}
+
+function specCachePath(baseUrl: string): string {
+  const host = new URL(baseUrl).host.replace(/[^a-zA-Z0-9]/g, "-");
+  return path.join(process.cwd(), "product-specs", `${host}.json`);
+}
+
+export function loadCachedSpec(baseUrl: string): ProductSpec | null {
+  const filePath = specCachePath(baseUrl);
+  if (!fs.existsSync(filePath)) return null;
+  try {
+    return JSON.parse(fs.readFileSync(filePath, "utf-8")) as ProductSpec;
+  } catch {
+    return null;
+  }
+}
+
+function saveSpec(baseUrl: string, spec: ProductSpec): void {
+  const filePath = specCachePath(baseUrl);
+  fs.mkdirSync(path.dirname(filePath), { recursive: true });
+  fs.writeFileSync(filePath, JSON.stringify(spec, null, 2), "utf-8");
+  console.log(`  [product-discovery] spec saved: ${filePath}`);
+
+  if (spec.uiFeatures) {
+    const mdPath = filePath.replace(/\.json$/, "_UI_FEATURES.md");
+    const md = `# UI Features — ${spec.appName}\n\n> Auto-generated by product-discovery on ${new Date().toISOString().slice(0, 10)}\n> UI-only interactions invisible from API responses.\n\n${spec.uiFeatures}\n`;
+    fs.writeFileSync(mdPath, md, "utf-8");
+    console.log(`  [product-discovery] UI_FEATURES saved: ${mdPath}`);
+  }
+}
+
+function printSpec(spec: ProductSpec): void {
+  console.log(`\n${"─".repeat(60)}`);
+  console.log(`  app: ${spec.appName}`);
+  console.log(`  description: ${spec.appDescription}`);
+  console.log(`  users: ${spec.targetUsers}`);
+  console.log(`  features:\n${spec.features.split("\n").map((l) => `    ${l}`).join("\n")}`);
+  console.log(`  confidence: ${spec.confidence} / sources: ${spec.sources.join(", ")}`);
+  console.log(`${"─".repeat(60)}\n`);
+}
+
+const DISCOVERY_TOOLS: Anthropic.Tool[] = [
+  {
+    name: "navigate_and_read",
+    description: "Navigate to a path and read page text + ARIA tree / アプリの指定パスに移動しテキストとARIAツリーを取得する",
+    input_schema: {
+      type: "object",
+      properties: {
+        path: { type: "string", description: "Path to observe (e.g. /, /tasks, /purchases)" },
+      },
+      required: ["path"],
+    },
+  },
+  {
+    name: "fetch_url",
+    description: "Fetch text content from an external URL (README, About page, etc.) / 外部URLのテキストを取得する",
+    input_schema: {
+      type: "object",
+      properties: {
+        url: { type: "string", description: "URL to fetch" },
+      },
+      required: ["url"],
+    },
+  },
+  {
+    name: "output_spec",
+    description: "Finalize and output the product spec once enough information has been gathered / 十分な情報が集まったらプロダクト仕様を確定して出力する",
+    input_schema: {
+      type: "object",
+      properties: {
+        appName: { type: "string", description: "App name" },
+        appDescription: { type: "string", description: "What the app does, who it's for, and its main value (2-3 sentences)" },
+        targetUsers: { type: "string", description: "Target users: roles, technical level, usage scenarios" },
+        features: { type: "string", description: "Implemented features, listed per screen as bullet points" },
+        designContext: {
+          type: "string",
+          description: "Detected UI framework, visual style, and applicable design standards. Include: (1) UI framework/library if detectable (Tailwind CSS, Material UI, Bootstrap, etc.), (2) visual style (minimalist, corporate, playful, dense, etc.), (3) design conventions relevant to this app type (e.g. enterprise UX patterns, consumer mobile conventions, dashboard best practices). Example: 'Tailwind CSS, minimalist corporate style — enterprise conventions: clear status indicators, inline validation, progressive disclosure for complex forms'",
+        },
+        uiFeatures: {
+          type: "string",
+          description: "UI-only interactions and features that are NOT visible from API responses alone — things only discoverable by looking at the actual screen. List per screen. Examples: client-side filters, view mode toggles (card/compact), warning modals, inline validation messages, hover states, keyboard shortcuts, drag-and-drop, collapsible panels, tabs that switch without navigation, tooltips, empty-state messages, loading skeletons. Format: 'Screen: feature 1 · feature 2 · feature 3'",
+        },
+        appGoals: {
+          type: "array",
+          items: { type: "string" },
+          description: "3–6 concrete, measurable goals this app is designed to achieve — from the perspective of its users and the business. Each goal should be a complete sentence describing a success condition. Examples: 'New employees can submit a purchase request without any training', 'Approvers can review and act on a request within 60 seconds', 'Managers can see the status of all open requests at a glance'. Infer from the app's purpose, target users, and key workflows.",
+        },
+        confidence: {
+          type: "string",
+          enum: ["high", "medium", "low"],
+          description: "Inference confidence: high if README/docs obtained, low if UI observation only",
+        },
+        sources: {
+          type: "array",
+          items: { type: "string" },
+          description: "Sources used (e.g. ['/ (top page)', '/tasks (UI)', 'README'])",
+        },
+      },
+      required: ["appName", "appDescription", "targetUsers", "features", "designContext", "uiFeatures", "appGoals", "confidence", "sources"],
+    },
+  },
+];
+
+export async function discoverProduct(
+  baseUrl: string,
+  page: Page,
+  client: LLMClient,
+  model: string,
+  projectPath?: string,
+): Promise<ProductSpec> {
+  console.log("\n[product-discovery] starting...");
+
+  const systemPrompt = `You are a product discovery agent.
+Observe the given web app and infer what it is.
+
+Steps:
+1. Use navigate_and_read to observe the top page
+2. Observe 2-3 key screens (follow tabs or navigation)
+3. If a README or About page is available, fetch it with fetch_url
+4. Once you have enough information, call output_spec (finish within 6 observations)
+
+Guidelines for output_spec:
+- appDescription: 2-3 sentences covering who uses it, why, and the main value
+- targetUsers: roles, technical level, and usage scenarios (be specific)
+- features: list per screen as "Screen name: feature 1 · feature 2 · feature 3"
+- designContext: note the UI framework (look for class names like "tw-", "MuiButton", "btn btn-"), visual style, and what design conventions apply for this app type
+- uiFeatures: list UI-only features per screen that are invisible from API responses (filters, toggles, modals, validation messages, empty states, etc.)
+- confidence: high if README/official docs obtained, low if UI observation only
+- appGoals: 3–6 concrete goals this app is designed to achieve (user + business perspective)`;
+
+  const docs = await gatherDocumentation(projectPath);
+  const initialContent = docs
+    ? `App URL: ${baseUrl}\n\nInvestigate what this app is.\n\n[Available Documentation]\n${docs}`
+    : `App URL: ${baseUrl}\n\nInvestigate what this app is.`;
+
+  const messages: Anthropic.MessageParam[] = [
+    { role: "user", content: initialContent },
+  ];
+
+  let spec: ProductSpec | null = null;
+  let iterations = 0;
+
+  while (iterations < 8 && !spec) {
+    iterations++;
+
+    const response = await createMessageWithRetry(client, {
+      model,
+      max_tokens: 2048,
+      system: systemPrompt,
+      tools: DISCOVERY_TOOLS,
+      messages,
+    });
+
+    messages.push({ role: "assistant", content: response.content });
+
+    const toolUses = response.content.filter(
+      (b): b is Anthropic.ToolUseBlock => b.type === "tool_use"
+    );
+    if (toolUses.length === 0 || response.stop_reason === "end_turn") break;
+
+    const toolResults: Anthropic.ToolResultBlockParam[] = [];
+    for (const toolUse of toolUses) {
+      let result: string;
+
+      if (toolUse.name === "navigate_and_read") {
+        const { path } = toolUse.input as { path: string };
+        try {
+          await page.goto(`${baseUrl}${path}`, { waitUntil: "networkidle", timeout: 10000 });
+          await page.waitForTimeout(500);
+          const [text, aria] = await Promise.all([
+            page.evaluate(() => document.body.innerText.slice(0, 1500)),
+            page.ariaSnapshot({ mode: "ai", depth: 5 }).then((s) => s.slice(0, 1500)),
+          ]);
+          result = `[${path} text]\n${text}\n\n[ARIA tree]\n${aria}`;
+          console.log(`  [product-discovery] observed: ${path}`);
+        } catch (e) {
+          result = `fetch failed: ${String(e)}`;
+        }
+
+      } else if (toolUse.name === "fetch_url") {
+        const { url } = toolUse.input as { url: string };
+        try {
+          const res = await fetch(url, { signal: AbortSignal.timeout(8000) });
+          const text = await res.text();
+          result = text.replace(/<[^>]+>/g, " ").replace(/\s+/g, " ").trim().slice(0, 2000);
+          console.log(`  [product-discovery] fetched: ${url}`);
+        } catch (e) {
+          result = `fetch failed: ${String(e)}`;
+        }
+
+      } else if (toolUse.name === "output_spec") {
+        const input = toolUse.input as ProductSpec;
+        spec = {
+          appName: String(input.appName),
+          appDescription: String(input.appDescription),
+          targetUsers: String(input.targetUsers),
+          features: String(input.features),
+          designContext: String(input.designContext ?? ""),
+          uiFeatures: String(input.uiFeatures ?? ""),
+          appGoals: Array.isArray(input.appGoals) ? input.appGoals.map(String) : [],
+          confidence: input.confidence,
+          sources: Array.isArray(input.sources) ? input.sources.map(String) : [],
+        };
+        result = "product spec finalized";
+        console.log(`  [product-discovery] spec confirmed (confidence: ${spec.confidence})`);
+
+      } else {
+        result = "unknown tool";
+      }
+
+      toolResults.push({ type: "tool_result", tool_use_id: toolUse.id, content: result });
+    }
+
+    messages.push({ role: "user", content: toolResults });
+  }
+
+  if (!spec) {
+    console.log("  [product-discovery] spec not confirmed, using fallback");
+    spec = {
+      appName: new URL(baseUrl).hostname,
+      appDescription: "(auto-discovery failed)",
+      targetUsers: "(unknown)",
+      features: "(auto-discovery failed)",
+      designContext: "(unknown)",
+      uiFeatures: "(unknown)",
+      appGoals: [],
+      confidence: "low",
+      sources: [],
+    };
+  }
+
+  spec.discoveredAt = new Date().toISOString();
+  saveSpec(baseUrl, spec);
+  console.log(`[product-discovery] done: "${spec.appName}" (confidence: ${spec.confidence})`);
+  printSpec(spec);
+  return spec;
+}