yo-bug 0.1.0

package/src/mcp/index.ts

@@ -0,0 +1,327 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { z } from 'zod';
+import { FeedbackStore } from '../storage/store.js';
+import { startTestSession } from './tools/start-session.js';
+import { stopTestSession } from './tools/stop-session.js';
+import { listFeedbacks } from './tools/list-feedbacks.js';
+import { getFeedback } from './tools/get-feedback.js';
+import { resolveFeedback } from './tools/resolve-feedback.js';
+import { createChecklist, getChecklistStatus } from './tools/checklist.js';
+import { saveTestRecord, getTestHistory } from './tools/test-history.js';
+
+const store = new FeedbackStore();
+
+const WORKFLOW_GUIDE = `# yo-bug — AI Workflow Guide
+
+You have visual test feedback capabilities. Here is the complete workflow:
+
+## When to Use
+- After writing or modifying frontend code, before telling the user "it's done"
+- When the user says "let me test" or "something looks wrong"
+- When you want the user to verify your changes
+
+## Complete Workflow (follow this order)
+
+### 1. Start test session
+Call start_test_session() to launch the test environment.
+This auto-detects the dev server, starts a reverse proxy with the test SDK injected, and opens the browser.
+The user's project code is NOT modified — the SDK is injected via the proxy.
+
+### 2. Check test history (if applicable)
+Call get_test_history(module) to see if this module has been tested before.
+Look for frequently failing scenarios — make sure your checklist covers them.
+
+### 3. Push a test checklist
+Call create_checklist(title, items) with structured test items.
+Follow the 8 QA dimensions in the tool description. Each item needs:
+- step: exactly what the user should do
+- expect: exactly what they should see
+- priority: "critical" for core paths, "normal" for edge cases
+- dimension: which QA dimension this tests
+
+### 4. Wait for the user to test
+Tell the user: "Test session is ready. Go through the checklist in the browser. When you find issues, press Alt+Q to quick-flag them, or Alt+S to screenshot and annotate."
+The user tests at their own pace. Don't rush them.
+
+### 5. Check results
+Call get_checklist_status() to see pass/fail results.
+Call list_feedbacks() to see any bug reports the user submitted.
+Call get_feedback(id) to see full details including:
+- Annotated screenshots (returned as image content you can see)
+- Element CSS selectors and computed styles
+- Console errors and stack traces
+- Failed network requests
+- User's action recording (what they clicked/typed before the bug)
+
+### 6. Fix issues
+Fix the code based on the feedback details.
+After fixing each issue, call resolve_feedback(id).
+This pushes a "Verify Fix" card to the user's browser — they click "Fixed" or "Still broken".
+
+### 7. Save test record
+Call save_test_record(module, title, items, results, failedItems) to persist the test results.
+Next time you modify this module, get_test_history will show what failed before.
+
+### 8. End session
+When testing is complete, call stop_test_session().
+This returns a session summary with stats and weak dimension analysis.
+
+## Keyboard Shortcuts (tell user about these)
+- Alt+Q: Quick flag mode — click an element to instantly report it
+- Alt+D: Detail mode — click an element, then describe the issue
+- Alt+S: Screenshot mode — drag to select area, annotate with drawings
+- Alt+X: Toggle test mode
+- Esc: Exit test mode
+
+## Tips
+- The user's browser automatically captures console errors, network failures, and action steps. You don't need to ask them to check DevTools.
+- When you see a feedback with action steps, you can trace the exact reproduction path.
+- Screenshots are returned as image content blocks — you can see the annotations directly.
+- The checklist appears in the user's browser automatically. You don't need to list the items in chat.
+`;
+
+const server = new McpServer({
+  name: 'yo-bug',
+  version: '0.1.0',
+});
+
+// --- Resource: workflow guide ---
+server.resource(
+  'workflow-guide',
+  'yo-bug://workflow',
+  { description: 'Complete workflow guide for using yo-bug. READ THIS FIRST before calling any tools.', mimeType: 'text/markdown' },
+  async () => ({
+    contents: [{
+      uri: 'yo-bug://workflow',
+      mimeType: 'text/markdown',
+      text: WORKFLOW_GUIDE,
+    }],
+  })
+);
+
+// --- Tool: start_test_session ---
+server.tool(
+  'start_test_session',
+  `Start test mode. Auto-detects dev server, starts a reverse proxy with injected test feedback SDK, and opens the browser.
+
+After calling this, follow these steps:
+1. Call get_test_history(module) to check past test records
+2. Call create_checklist(title, items) to push a structured test plan
+3. Tell the user to test. Shortcuts: Alt+Q (quick flag), Alt+D (describe), Alt+S (screenshot), Esc (exit)
+4. Call get_checklist_status() and list_feedbacks() to read results
+5. Fix issues, call resolve_feedback(id) for each — user verifies in browser
+6. Call save_test_record() to persist results
+7. Call stop_test_session() when done`,
+  {
+    port: z.number().optional().describe('Dev server port. Auto-detected from package.json if not provided.'),
+    open: z.boolean().optional().describe('Whether to auto-open browser. Default: true.'),
+  },
+  async ({ port, open }) => {
+    const result = await startTestSession(store, { port, open });
+    return {
+      content: [{ type: 'text', text: result.message }],
+      isError: result.status === 'error',
+    };
+  }
+);
+
+// --- Tool: stop_test_session ---
+server.tool(
+  'stop_test_session',
+  'Stop test mode. Shuts down the reverse proxy and any auto-started dev server. Returns a test session summary.',
+  {},
+  async () => {
+    const result = await stopTestSession(store);
+    return {
+      content: [{ type: 'text', text: result.message }],
+    };
+  }
+);
+
+// --- Tool: list_feedbacks ---
+server.tool(
+  'list_feedbacks',
+  'List user-submitted test feedback. Returns a summary of each feedback item.',
+  {
+    status: z.enum(['open', 'verify', 'resolved', 'all']).optional().describe('Filter by status. Default: open.'),
+    type: z.string().optional().describe('Filter by problem type: bug, ui-issue, performance, feature-request, other.'),
+    limit: z.number().optional().describe('Max items to return. Default: 20.'),
+  },
+  async ({ status, type, limit }) => {
+    const result = await listFeedbacks(store, { status, type, limit });
+    return {
+      content: [{
+        type: 'text',
+        text: result.text + '\n\n' + JSON.stringify(result.items, null, 2),
+      }],
+    };
+  }
+);
+
+// --- Tool: get_feedback ---
+server.tool(
+  'get_feedback',
+  'Get full details of a feedback item, including element info, console errors, network errors, action steps, and annotated screenshot (as image content).',
+  {
+    id: z.string().describe('Feedback ID.'),
+  },
+  async ({ id }) => {
+    const result = await getFeedback(store, { id });
+    if (result.error) {
+      return { content: [{ type: 'text', text: result.text! }], isError: true };
+    }
+    return { content: result.content! };
+  }
+);
+
+// --- Tool: resolve_feedback ---
+server.tool(
+  'resolve_feedback',
+  'Mark a feedback item as fixed. This pushes a verification request to the browser — the user will confirm whether the fix actually works. Status changes to "verify" until user confirms.',
+  {
+    id: z.string().describe('Feedback ID.'),
+  },
+  async ({ id }) => {
+    const result = await resolveFeedback(store, { id });
+    return {
+      content: [{ type: 'text', text: result.text }],
+      isError: result.error,
+    };
+  }
+);
+
+// --- Tool: create_checklist ---
+server.tool(
+  'create_checklist',
+  `Create a test checklist and push it to the user's browser. Users can go through items one by one and mark each as passed/failed.
+
+You MUST systematically generate the checklist based on the actual code changes, reviewing each of the 8 test dimensions below. Include items for every dimension that is relevant to your changes:
+
+1. Happy path (critical)
+   - Complete positive flow of core functionality
+   - Use realistic data (not "test"/"123")
+   - Verify results display correctly and remain interactive
+
+2. Empty/boundary values
+   - Submit all input fields empty
+   - Input only whitespace
+   - Input exceeding max length (200+ characters)
+   - Special characters: < > " ' & ; \` ${"${}"}
+   - Numeric fields: 0, negative, decimal, non-numeric text
+   - Date fields: past, future, invalid format
+   - Lists/tables: 0 items, 1 item, 100+ items
+
+3. Error states
+   - Submit while offline (DevTools Network → Offline)
+   - Server returns 400/500 error
+   - Request timeout (DevTools Network → Slow 3G)
+   - Error messages are clear and positioned near the problem
+   - Can recover and retry after an error
+
+4. Duplicate operations
+   - Rapidly click submit button 3 times
+   - Submit the same form data twice consecutively
+   - Trigger action while previous request is still pending
+   - Buttons/forms show disabled state during processing
+
+5. State recovery
+   - Refresh page (F5) after completing action — data persists?
+   - Browser back then forward — state correct?
+   - Direct URL access to a deep page
+   - Close tab and reopen
+   - Refresh mid-way through a form — data recovered or warning shown?
+
+6. Loading/async
+   - First load shows loading state (not blank)
+   - Failed data load shows empty state or error message
+   - Can interact with other parts while loading
+   - UI updates promptly after data changes
+
+7. Responsive
+   - Shrink browser to 375px width (or DevTools mobile mode)
+   - Key buttons and forms are usable, not obscured
+   - Text doesn't overflow or get clipped
+   - No horizontal scrollbar
+
+8. Interaction details
+   - Tab key follows logical focus order
+   - Enter key submits forms
+   - Escape key closes modals/cancels actions
+   - Disabled buttons are truly non-clickable
+   - Focus moves to the correct element after actions
+
+Each item MUST have a specific step and expected result.
+Step should be specific: "Type 200 'a' characters in the email field, click Submit".
+Expected should be specific: "Red error text appears below email field: 'Invalid email format'".
+Never write vague expectations like "should work normally".
+
+Important: Before generating a checklist, call get_test_history to check historical test records for this module. Focus on previously failed scenarios. After testing is complete, call save_test_record to save the results.`,
+  {
+    title: z.string().describe('Checklist title. Briefly describe test scope, e.g. "Login feature test".'),
+    items: z.array(z.object({
+      step: z.string().describe('Specific action steps for the user. Be concrete: what to click, what to type, under what conditions.'),
+      expect: z.string().describe('Expected result after the action. Be concrete: what text appears, where it navigates, what changes.'),
+      priority: z.enum(['critical', 'normal']).optional().describe('critical = core path must pass, normal = boundary/error/detail scenario. Default: normal.'),
+      dimension: z.string().optional().describe('Test dimension: happy-path / empty-boundary / error-state / duplicate-ops / state-recovery / loading-async / responsive / interaction-detail'),
+    })).describe('Test items. List critical items first, then normal, ensuring systematic coverage.'),
+  },
+  async ({ title, items }) => {
+    const result = await createChecklist({ title, items });
+    return { content: [{ type: 'text', text: result.text }] };
+  }
+);
+
+// --- Tool: get_checklist_status ---
+server.tool(
+  'get_checklist_status',
+  'Get current checklist status: which items passed, failed, or are pending, and any user feedback on failed items.',
+  {},
+  async () => {
+    const result = await getChecklistStatus();
+    return { content: [{ type: 'text', text: result.text }] };
+  }
+);
+
+// --- Tool: save_test_record ---
+server.tool(
+  'save_test_record',
+  'Save test results for a module. Call after checklist testing is complete to accumulate test history. This data is used by get_test_history to identify frequently failing scenarios.',
+  {
+    module: z.string().describe('Feature module name, e.g. "login", "order-submit", "user-management".'),
+    title: z.string().describe('Test session title.'),
+    items: z.array(z.any()).describe('Test items (from get_checklist_status).'),
+    results: z.object({
+      passed: z.number(),
+      failed: z.number(),
+      total: z.number(),
+    }).describe('Test result counts.'),
+    failedItems: z.array(z.string()).describe('Descriptions of failed test items.'),
+  },
+  async ({ module, title, items, results, failedItems }) => {
+    const result = await saveTestRecord({ module, title, items, results, failedItems });
+    return { content: [{ type: 'text', text: result.text }] };
+  }
+);
+
+// --- Tool: get_test_history ---
+server.tool(
+  'get_test_history',
+  'Get historical test records for a module, including frequently failing scenarios. Call this BEFORE generating a new checklist to ensure coverage of previously problematic areas.',
+  {
+    module: z.string().describe('Feature module name, e.g. "login", "order-submit", "user-management".'),
+  },
+  async ({ module }) => {
+    const result = await getTestHistory({ module });
+    return { content: [{ type: 'text', text: result.text }] };
+  }
+);
+
+// --- Start ---
+async function main() {
+  await store.init();
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+}
+
+main().catch(console.error);

package/src/mcp/tools/checklist.ts

@@ -0,0 +1,61 @@
+/**
+ * Create a test checklist and push it to the browser.
+ */
+export async function createChecklist(args: {
+  title: string;
+  items: { step: string; expect: string; priority?: string; dimension?: string }[];
+}): Promise<{ text: string }> {
+  try {
+    const res = await fetch('http://localhost:3695/api/checklist', {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ title: args.title, items: args.items }),
+    });
+    if (!res.ok) throw new Error(`HTTP ${res.status}`);
+    const data = await res.json();
+    return {
+      text: `测试清单已推送到浏览器（${data.count} 项）。用户可以在页面上逐项测试并勾选结果。`,
+    };
+  } catch {
+    return { text: '推送失败。测试模式可能未启动。' };
+  }
+}
+
+/**
+ * Get the current checklist status from the browser.
+ */
+export async function getChecklistStatus(): Promise<{ text: string; data: any }> {
+  try {
+    const res = await fetch('http://localhost:3695/api/checklist');
+    if (!res.ok) throw new Error(`HTTP ${res.status}`);
+    const data = await res.json();
+
+    if (!data.items || data.items.length === 0) {
+      return { text: '当前没有测试清单。', data: null };
+    }
+
+    const passed = data.items.filter((i: any) => i.status === 'passed').length;
+    const failed = data.items.filter((i: any) => i.status === 'failed').length;
+    const pending = data.items.filter((i: any) => i.status === 'pending').length;
+
+    const lines = [
+      `测试清单: ${data.title}`,
+      `进度: ${passed} 通过 / ${failed} 失败 / ${pending} 待测`,
+      '',
+    ];
+
+    for (const item of data.items) {
+      const icon = item.status === 'passed' ? '[PASS]' :
+                   item.status === 'failed' ? '[FAIL]' : '[    ]';
+      const priority = item.priority === 'critical' ? ' [!]' : '';
+      const dim = item.dimension ? ` [${item.dimension}]` : '';
+      lines.push(`${icon}${priority}${dim} ${item.step}`);
+      lines.push(`     预期: ${item.expect}`);
+      if (item.feedback) lines.push(`     反馈: ${item.feedback}`);
+    }
+
+    return { text: lines.join('\n'), data };
+  } catch {
+    return { text: '无法获取清单状态。测试模式可能未启动。', data: null };
+  }
+}

package/src/mcp/tools/get-feedback.ts

@@ -0,0 +1,34 @@
+import { FeedbackStore } from '../../storage/store.js';
+
+export async function getFeedback(
+  store: FeedbackStore,
+  args: { id: string }
+) {
+  await store.init();
+  const item = await store.getById(args.id);
+  if (!item) {
+    return { error: true, text: `反馈 ${args.id} 不存在。` };
+  }
+
+  // Build content blocks
+  const content: any[] = [
+    {
+      type: 'text' as const,
+      text: JSON.stringify(item, null, 2),
+    },
+  ];
+
+  // Include screenshot if available
+  if (item.hasScreenshot) {
+    const screenshot = await store.getScreenshot(args.id);
+    if (screenshot) {
+      content.push({
+        type: 'image' as const,
+        data: screenshot.toString('base64'),
+        mimeType: 'image/png',
+      });
+    }
+  }
+
+  return { error: false, content };
+}

package/src/mcp/tools/list-feedbacks.ts

@@ -0,0 +1,37 @@
+import { FeedbackStore } from '../../storage/store.js';
+
+export async function listFeedbacks(
+  store: FeedbackStore,
+  args: { status?: string; type?: string; limit?: number }
+) {
+  await store.init();
+  const result = await store.list({
+    status: args.status || 'open',
+    type: args.type,
+    limit: args.limit || 20,
+  });
+
+  if (result.items.length === 0) {
+    return { text: '当前没有反馈。', items: [] };
+  }
+
+  const summary = result.items.map((item) => ({
+    id: item.id,
+    mode: item.mode,
+    problemType: item.problemType,
+    description: item.description.slice(0, 100),
+    pageUrl: item.pageUrl,
+    status: item.status,
+    createdAt: item.createdAt,
+    hasScreenshot: item.hasScreenshot,
+    errorCount:
+      item.consoleErrors.length +
+      item.networkErrors.length +
+      item.unhandledErrors.length,
+  }));
+
+  return {
+    text: `共 ${result.total} 条反馈（显示 ${summary.length} 条）`,
+    items: summary,
+  };
+}

package/src/mcp/tools/resolve-feedback.ts

@@ -0,0 +1,34 @@
+import { FeedbackStore } from '../../storage/store.js';
+
+export async function resolveFeedback(
+  store: FeedbackStore,
+  args: { id: string }
+) {
+  await store.init();
+  const item = await store.getById(args.id);
+  if (!item) {
+    return { error: true, text: `反馈 ${args.id} 不存在。` };
+  }
+
+  // Mark as "verify" — waiting for user to confirm the fix
+  await store.updateStatus(args.id, 'verify');
+
+  // Push verification request to browser
+  try {
+    await fetch('http://localhost:3695/api/verify', {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({
+        feedbackId: args.id,
+        description: item.description,
+        problemType: item.problemType,
+        element: item.element?.selector,
+      }),
+    });
+  } catch {}
+
+  return {
+    error: false,
+    text: `反馈 ${args.id} 已标记为待验证。已通知用户在浏览器中确认修复效果。`,
+  };
+}

package/src/mcp/tools/start-session.ts

@@ -0,0 +1,65 @@
+import open from 'open';
+import { detectDevServer } from '../../detect/dev-server.js';
+import { spawnDevServer } from '../../detect/spawn-dev.js';
+import { startProxyServer, isProxyRunning } from '../../server/proxy-server.js';
+import { FeedbackStore } from '../../storage/store.js';
+
+export async function startTestSession(
+  store: FeedbackStore,
+  args: { port?: number; open?: boolean }
+): Promise<{ proxyUrl: string; targetUrl: string; status: string; message: string }> {
+  if (isProxyRunning()) {
+    return {
+      proxyUrl: 'http://localhost:3695',
+      targetUrl: '',
+      status: 'already_running',
+      message: '测试模式已在运行中。浏览器访问 http://localhost:3695 即可测试。',
+    };
+  }
+
+  const cwd = process.cwd();
+  const info = await detectDevServer(cwd, args.port);
+
+  let message = '';
+
+  if (info.isRunning) {
+    message = `检测到 ${info.framework} dev server 已在运行 → localhost:${info.port}`;
+  } else if (info.command) {
+    message = `启动 ${info.framework} dev server...`;
+    const started = await spawnDevServer(cwd, info.command, info.port);
+    if (!started) {
+      return {
+        proxyUrl: '',
+        targetUrl: '',
+        status: 'error',
+        message: `Dev server 启动超时（端口 ${info.port}）。请确认 dev server 能正常启动，或使用 port 参数手动指定端口。`,
+      };
+    }
+    message = `${info.framework} dev server 已启动 → localhost:${info.port}`;
+  } else {
+    return {
+      proxyUrl: '',
+      targetUrl: '',
+      status: 'error',
+      message: '未找到 package.json 或 dev 脚本。请使用 port 参数指定 dev server 端口。',
+    };
+  }
+
+  // Initialize store
+  await store.init();
+
+  // Start proxy
+  const { proxyUrl, targetUrl } = await startProxyServer(info.port, store);
+
+  // Open browser
+  if (args.open !== false) {
+    await open(proxyUrl);
+  }
+
+  return {
+    proxyUrl,
+    targetUrl,
+    status: 'running',
+    message: `${message}\n代理已启动 → ${proxyUrl}\n测试模式已开启，用户可以在浏览器中提交反馈。`,
+  };
+}

package/src/mcp/tools/stop-session.ts

@@ -0,0 +1,93 @@
+import { stopProxyServer, isProxyRunning } from '../../server/proxy-server.js';
+import { killDevServer, isDevServerSpawned } from '../../detect/spawn-dev.js';
+import { FeedbackStore } from '../../storage/store.js';
+
+export async function stopTestSession(
+  store: FeedbackStore
+): Promise<{ status: string; message: string }> {
+  if (!isProxyRunning()) {
+    return {
+      status: 'not_running',
+      message: '测试模式未在运行。',
+    };
+  }
+
+  // Gather session summary before stopping
+  const { items: allItems } = await store.list({ status: 'all', limit: 100 });
+  const openItems = allItems.filter(i => i.status === 'open');
+  const resolvedItems = allItems.filter(i => i.status === 'resolved');
+
+  // Count by type
+  const typeCounts: Record<string, number> = {};
+  for (const item of openItems) {
+    typeCounts[item.problemType] = (typeCounts[item.problemType] || 0) + 1;
+  }
+
+  // Check checklist status
+  let checklistSummary = '';
+  try {
+    const res = await fetch('http://localhost:3695/api/checklist');
+    const cl = await res.json();
+    if (cl.items && cl.items.length > 0) {
+      const passed = cl.items.filter((i: any) => i.status === 'passed').length;
+      const failed = cl.items.filter((i: any) => i.status === 'failed').length;
+      const pending = cl.items.filter((i: any) => i.status === 'pending').length;
+      checklistSummary = `\n测试清单「${cl.title}」: ${passed} 通过 / ${failed} 失败 / ${pending} 未测`;
+
+      // Identify weak dimensions
+      const failedDimensions = cl.items
+        .filter((i: any) => i.status === 'failed' && i.dimension)
+        .map((i: any) => i.dimension);
+      const pendingDimensions = cl.items
+        .filter((i: any) => i.status === 'pending' && i.dimension)
+        .map((i: any) => i.dimension);
+
+      if (failedDimensions.length > 0) {
+        const unique = [...new Set(failedDimensions)];
+        checklistSummary += `\n失败集中维度: ${unique.join('、')}`;
+      }
+      if (pendingDimensions.length > 0) {
+        const unique = [...new Set(pendingDimensions)];
+        checklistSummary += `\n未测维度: ${unique.join('、')}`;
+      }
+    }
+  } catch {}
+
+  // Stop proxy
+  stopProxyServer();
+
+  // Kill spawned dev server (if we started it)
+  if (isDevServerSpawned()) {
+    killDevServer();
+  }
+
+  // Build summary
+  const lines = ['测试模式已关闭。\n', '── 测试会话总结 ──'];
+
+  lines.push(`反馈: ${allItems.length} 条（${openItems.length} 待修复, ${resolvedItems.length} 已修复）`);
+
+  if (Object.keys(typeCounts).length > 0) {
+    const typeStr = Object.entries(typeCounts)
+      .map(([type, count]) => `${type}: ${count}`)
+      .join(', ');
+    lines.push(`问题分布: ${typeStr}`);
+  }
+
+  if (checklistSummary) {
+    lines.push(checklistSummary);
+  }
+
+  // Actionable conclusion
+  if (openItems.length > 0) {
+    lines.push(`\n建议: 还有 ${openItems.length} 条未修复反馈，请查看 list_feedbacks() 并逐一处理。`);
+  } else if (allItems.length > 0) {
+    lines.push('\n结论: 所有反馈已修复。');
+  } else {
+    lines.push('\n结论: 本次未收到反馈。');
+  }
+
+  return {
+    status: 'stopped',
+    message: lines.join('\n'),
+  };
+}