fe-harness 1.0.0

package/fe-harness/bin/browser.cjs

@@ -0,0 +1,271 @@
+#!/usr/bin/env node
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const { ensureDir, findProjectRoot } = require('./lib/core.cjs');
+const {
+  listSessions,
+  launch,
+  connect,
+  stop,
+  cleanup,
+  formatA11yNode,
+} = require('./lib/browser-core.cjs');
+const { initLogger, log, closeLogger } = require('./lib/logger.cjs');
+
+const args = process.argv.slice(2);
+const command = args[0];
+
+function output(data) {
+  process.stdout.write(JSON.stringify(data, null, 2) + '\n');
+}
+
+function parseFlags(args) {
+  const flags = {};
+  for (let i = 0; i < args.length; i++) {
+    if (args[i].startsWith('--')) {
+      const key = args[i].slice(2);
+      const next = args[i + 1];
+      if (next && !next.startsWith('--')) {
+        flags[key] = next;
+        i++;
+      } else {
+        flags[key] = true;
+      }
+    }
+  }
+  return flags;
+}
+
+async function main() {
+  try { initLogger(findProjectRoot()); } catch (_) { /* best-effort */ }
+
+  try {
+    switch (command) {
+      case 'start': {
+        const flags = parseFlags(args.slice(1));
+        const opts = {};
+
+        if (flags.viewport) {
+          const [w, h] = flags.viewport.split('x').map(Number);
+          if (w && h) {
+            opts.viewportWidth = w;
+            opts.viewportHeight = h;
+          }
+        }
+
+        if (flags.maximized) {
+          opts.maximized = true;
+        }
+
+        const session = await launch(opts);
+
+        log('INFO', 'browser', `浏览器启动`, { sessionId: session.sessionId });
+        if (flags['session-id-only']) {
+          process.stdout.write(session.sessionId);
+        } else {
+          output({ ok: true, ...session });
+        }
+        break;
+      }
+
+      case 'navigate': {
+        const sessionId = args[1];
+        const url = args[2];
+        if (!sessionId || !url) {
+          output({ error: 'Usage: browser.cjs navigate <sessionId> <url> [--wait-for text] [--timeout ms]' });
+          process.exit(1);
+        }
+
+        const flags = parseFlags(args.slice(3));
+        const timeout = parseInt(flags.timeout) || 30000;
+
+        const { browser, page } = await connect(sessionId);
+        try {
+          await page.goto(url, { waitUntil: 'networkidle2', timeout });
+
+          if (flags['wait-for']) {
+            await page.waitForFunction(
+              (text) => document.body?.innerText?.includes(text),
+              { timeout },
+              flags['wait-for']
+            );
+          }
+
+          const title = await page.title();
+          log('INFO', 'browser', `页面导航`, { url, title });
+          output({ ok: true, url, title });
+        } finally {
+          browser.disconnect();
+        }
+        break;
+      }
+
+      case 'screenshot': {
+        const sessionId = args[1];
+        const outputPath = args[2];
+        if (!sessionId || !outputPath) {
+          output({ error: 'Usage: browser.cjs screenshot <sessionId> <outputPath> [--full-page] [--selector css]' });
+          process.exit(1);
+        }
+
+        const flags = parseFlags(args.slice(3));
+        const resolvedPath = path.resolve(outputPath);
+
+        // Ensure output directory exists
+        ensureDir(path.dirname(resolvedPath));
+
+        const { browser, page } = await connect(sessionId);
+        try {
+          const screenshotOpts = { path: resolvedPath, type: 'png' };
+
+          if (flags.selector) {
+            const element = await page.$(flags.selector);
+            if (!element) {
+              output({ error: `Element not found: ${flags.selector}` });
+              break;
+            }
+            await element.screenshot(screenshotOpts);
+          } else {
+            screenshotOpts.fullPage = !!flags['full-page'];
+            await page.screenshot(screenshotOpts);
+          }
+
+          const viewport = page.viewport();
+          log('INFO', 'browser', `截图完成`, { path: resolvedPath });
+          output({
+            ok: true,
+            path: resolvedPath,
+            width: viewport?.width || 0,
+            height: viewport?.height || 0,
+          });
+        } finally {
+          browser.disconnect();
+        }
+        break;
+      }
+
+      case 'eval': {
+        const sessionId = args[1];
+        if (!sessionId) {
+          output({ error: 'Usage: browser.cjs eval <sessionId> <expression> | --stdin' });
+          process.exit(1);
+        }
+
+        const flags = parseFlags(args.slice(2));
+        let expression;
+
+        if (flags.stdin || flags.stdin === true) {
+          expression = fs.readFileSync('/dev/stdin', 'utf8').trim();
+        } else {
+          // Collect all remaining non-flag args as expression
+          expression = args.slice(2).filter(a => !a.startsWith('--')).join(' ');
+        }
+
+        if (!expression) {
+          output({ error: 'No expression provided' });
+          process.exit(1);
+        }
+
+        const { browser, page } = await connect(sessionId);
+        try {
+          // Wrap in async IIFE if it looks like a function
+          let result;
+          if (expression.trim().startsWith('(') || expression.trim().startsWith('async')) {
+            result = await page.evaluate(expression);
+          } else {
+            result = await page.evaluate(`(() => { return ${expression}; })()`);
+          }
+          output({ ok: true, result });
+        } finally {
+          browser.disconnect();
+        }
+        break;
+      }
+
+      case 'snapshot': {
+        const sessionId = args[1];
+        if (!sessionId) {
+          output({ error: 'Usage: browser.cjs snapshot <sessionId> [--file path]' });
+          process.exit(1);
+        }
+
+        const flags = parseFlags(args.slice(2));
+
+        const { browser, page } = await connect(sessionId);
+        try {
+          const snapshot = await page.accessibility.snapshot();
+          const formatted = formatA11yNode(snapshot);
+
+          if (flags.file) {
+            const resolvedPath = path.resolve(flags.file);
+            const dir = path.dirname(resolvedPath);
+            if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
+            fs.writeFileSync(resolvedPath, formatted, 'utf8');
+            output({ ok: true, path: resolvedPath });
+          } else {
+            output({ ok: true, snapshot: formatted });
+          }
+        } finally {
+          browser.disconnect();
+        }
+        break;
+      }
+
+      case 'stop': {
+        const sessionId = args[1];
+        if (!sessionId) {
+          output({ error: 'Usage: browser.cjs stop <sessionId>' });
+          process.exit(1);
+        }
+
+        const result = await stop(sessionId);
+        log('INFO', 'browser', `浏览器停止`, { sessionId });
+        output({ ok: true, sessionId, ...result });
+        break;
+      }
+
+      case 'cleanup': {
+        const flags = parseFlags(args.slice(1));
+        const maxAge = parseInt(flags['max-age']) || 60;
+        const result = await cleanup({ maxAge });
+        log('INFO', 'browser', `浏览器清理`, { maxAge, ...result });
+        output({ ok: true, ...result });
+        break;
+      }
+
+      case 'list': {
+        const sessions = listSessions();
+        output({ ok: true, sessions });
+        break;
+      }
+
+      default: {
+        output({
+          error: 'Unknown command',
+          usage: {
+            start: 'browser.cjs start [--viewport WxH] [--session-id-only]',
+            navigate: 'browser.cjs navigate <sid> <url> [--wait-for text] [--timeout ms]',
+            screenshot: 'browser.cjs screenshot <sid> <outputPath> [--full-page] [--selector css]',
+            eval: 'browser.cjs eval <sid> <expression> | --stdin',
+            snapshot: 'browser.cjs snapshot <sid> [--file path]',
+            stop: 'browser.cjs stop <sid>',
+            cleanup: 'browser.cjs cleanup [--max-age minutes]',
+            list: 'browser.cjs list',
+          },
+        });
+        process.exit(1);
+      }
+    }
+  } catch (err) {
+    log('ERROR', 'browser', `浏览器操作失败: ${err.message}`, { command });
+    closeLogger();
+    output({ error: err.message });
+    process.exit(1);
+  } finally {
+    closeLogger();
+  }
+}
+
+main();

package/fe-harness/bin/fe-tools.cjs

@@ -0,0 +1,317 @@
+#!/usr/bin/env node
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const { findProjectRoot, getContextDir, ensureDir } = require('./lib/core.cjs');
+const { listTasks, getTask, updateTask, updateTaskJSON, getNextTask, getWaves, checkConflicts, resolveConflicts, propagateFailure, failTask, completeTasks, saveRetryState, resetTask, resetAllFailed, getStatus, getCompletionSummary, archiveTasks } = require('./lib/tasks.cjs');
+const { getConfig, setConfig, initConfig } = require('./lib/config.cjs');
+const { calculateScore, checkRegression } = require('./lib/scoring.cjs');
+const { initLogger, log, getLogPath, closeLogger } = require('./lib/logger.cjs');
+
+const args = process.argv.slice(2);
+const command = args[0];
+const subcommand = args[1];
+
+const root = findProjectRoot();
+
+// Initialize logger (silent no-op if .fe-runtime doesn't exist yet)
+try { initLogger(root); } catch (_) { /* ignore — logging is best-effort */ }
+
+function output(data) {
+  process.stdout.write(JSON.stringify(data, null, 2) + '\n');
+}
+
+/**
+ * Read JSON from stdin (for --stdin flag).
+ * Reads all remaining args after --stdin as space-separated JSON objects,
+ * or reads from actual stdin if no inline data follows.
+ */
+function readStdinSync() {
+  return fs.readFileSync('/dev/stdin', 'utf8').trim();
+}
+
+function usage() {
+  output({
+    commands: {
+      'tasks list': 'List all tasks',
+      'tasks waves': 'Get wave-grouped task execution plan (dependency-based)',
+      'tasks check-conflicts': 'Check for file ownership conflicts within waves',
+      'tasks resolve-conflicts': 'Auto-resolve conflicts by adding dependencies',
+      'tasks next': 'Get next executable task (dependency-aware)',
+      'tasks get <id>': 'Get task by ID',
+      'tasks update <id> <field> <value>': 'Update a task field',
+      'tasks update-json <id> <field> <json>': 'Update a task field with JSON value',
+      'tasks propagate-failure <id>': 'Propagate failure to dependent tasks',
+      'tasks reset <id>': 'Reset a task to pending',
+      'tasks reset-all-failed': 'Reset all failed/skipped tasks',
+      'tasks fail <id> [--error "msg"]': 'Mark task failed + set error + propagate failure (atomic)',
+      'tasks complete <id1> [id2 ...]': 'Batch-mark tasks as done with verifyPassed=true',
+      'tasks summary': 'Get completion summary with stats, scores and warnings',
+      'tasks archive': 'Archive tasks.json + context to .fe-runtime/history/ and clean up',
+      'tasks save-retry <id> --stdin': 'Update retryCount + bestScore + bestScoresJSON atomically (JSON stdin)',
+      'tasks status': 'Get status overview',
+      'scoring calculate <type> <scores-json|--stdin>': 'Calculate weighted score (type: design|logic)',
+      'scoring check-regression <current-json> <best-json> | --stdin': 'Check for score regression',
+      'config get': 'Get project config',
+      'config set <key> <value>': 'Set a config value',
+      'config init <config-json>': 'Initialize config',
+      'init execute': 'Pre-execution checks',
+      'init context': 'Ensure context directory exists and is clean',
+    },
+  });
+}
+
+try {
+  switch (command) {
+    case 'tasks': {
+      switch (subcommand) {
+        case 'list':
+          output(listTasks(root));
+          break;
+        case 'next':
+          output(getNextTask(root));
+          break;
+        case 'waves': {
+          const wavesResult = getWaves(root);
+          log('INFO', 'wave', `Wave 计划: ${wavesResult.waveOrder?.length || 0} 个 wave, ${wavesResult.taskCount || 0} 个任务`, { remaining: wavesResult.remaining, completedWaves: wavesResult.completedWaves });
+          output(wavesResult);
+          break;
+        }
+        case 'check-conflicts':
+          output(checkConflicts(root));
+          break;
+        case 'resolve-conflicts': {
+          const resolveResult = resolveConflicts(root);
+          if (resolveResult.resolved > 0) {
+            log('WARN', 'task', `文件冲突已自动解决`, { resolved: resolveResult.resolved, added: resolveResult.added });
+          }
+          output(resolveResult);
+          break;
+        }
+        case 'get':
+          output(getTask(root, args[2]));
+          break;
+        case 'update': {
+          const updateResult = updateTask(root, args[2], args[3], args[4]);
+          if (args[3] === 'status') {
+            log('INFO', 'task', `任务状态变更 #${args[2]} ${args[3]}=${args[4]}`);
+          }
+          output(updateResult);
+          break;
+        }
+        case 'update-json': {
+          const field = args[3] === '--stdin' ? args[4] : args[3];
+          const jsonValue = args[3] === '--stdin' ? JSON.parse(readStdinSync()) : JSON.parse(args[4]);
+          output(updateTaskJSON(root, args[2], field, jsonValue));
+          break;
+        }
+        case 'propagate-failure':
+          output(propagateFailure(root, args[2]));
+          break;
+        case 'reset':
+          output(resetTask(root, args[2]));
+          break;
+        case 'reset-all-failed':
+          output(resetAllFailed(root));
+          break;
+        case 'fail': {
+          const errIdx = args.indexOf('--error');
+          const errorMsg = errIdx >= 0 ? args.slice(errIdx + 1).join(' ') : '';
+          const failResult = failTask(root, args[2], errorMsg);
+          log('WARN', 'task', `任务失败 #${args[2]}`, { error: errorMsg, skipped: failResult.skipped });
+          output(failResult);
+          break;
+        }
+        case 'complete': {
+          const completeResult = completeTasks(root, args.slice(2));
+          log('INFO', 'task', `任务完成`, { completed: completeResult.completed });
+          output(completeResult);
+          break;
+        }
+        case 'save-retry': {
+          const retryData = JSON.parse(readStdinSync());
+          output(saveRetryState(root, args[2], retryData));
+          break;
+        }
+        case 'status':
+          output(getStatus(root));
+          break;
+        case 'summary':
+          output(getCompletionSummary(root));
+          break;
+        case 'archive':
+          output(archiveTasks(root));
+          break;
+        default:
+          output({ error: `Unknown tasks subcommand: ${subcommand}` });
+      }
+      break;
+    }
+
+    case 'scoring': {
+      const cfg = getConfig(root);
+      const thresholds = {
+        verifyThreshold: cfg.verifyThreshold || 80,
+        reviewThreshold: cfg.reviewThreshold || 80,
+        dimensionThreshold: cfg.dimensionThreshold || 6,
+        scoreDropTolerance: cfg.scoreDropTolerance || 3,
+      };
+
+      switch (subcommand) {
+        case 'calculate': {
+          const type = args[2]; // 'design' or 'logic'
+          let scores;
+          if (args[3] === '--stdin') {
+            scores = JSON.parse(readStdinSync());
+          } else {
+            scores = JSON.parse(args[3]);
+          }
+          const scoreResult = calculateScore(scores, type, thresholds);
+          log('INFO', 'scoring', `评分计算 type=${type}`, { score: scoreResult.score, passed: scoreResult.passed });
+          output(scoreResult);
+          break;
+        }
+        case 'check-regression': {
+          let current, best;
+          if (args[2] === '--stdin') {
+            // Read two JSON objects from stdin (newline separated or as array)
+            const stdinData = readStdinSync();
+            const parts = stdinData.split('\n').filter(Boolean);
+            if (parts.length >= 2) {
+              current = JSON.parse(parts[0]);
+              best = JSON.parse(parts[1]);
+            } else {
+              const arr = JSON.parse(stdinData);
+              current = arr[0];
+              best = arr[1];
+            }
+          } else {
+            current = JSON.parse(args[2]);
+            best = JSON.parse(args[3]);
+          }
+          const regResult = checkRegression(current, best, thresholds);
+          if (regResult.regressed) {
+            log('WARN', 'scoring', `检测到评分回归`, { regressed: regResult.regressed, details: regResult.regressions });
+          }
+          output(regResult);
+          break;
+        }
+        default:
+          output({ error: `Unknown scoring subcommand: ${subcommand}` });
+      }
+      break;
+    }
+
+    case 'config': {
+      switch (subcommand) {
+        case 'get':
+          output(getConfig(root));
+          break;
+        case 'set':
+          output(setConfig(root, args[2], args[3]));
+          break;
+        case 'init':
+          output(initConfig(root, JSON.parse(args[2])));
+          break;
+        default:
+          output({ error: `Unknown config subcommand: ${subcommand}` });
+      }
+      break;
+    }
+
+    case 'init': {
+      switch (subcommand) {
+        case 'execute': {
+          // Pre-execution checks
+          const cfg = getConfig(root);
+          if (cfg.error) { output(cfg); break; }
+          const tasks = listTasks(root);
+          if (tasks.length === 0) { output({ error: 'No tasks found. Run /fe:plan first.' }); break; }
+
+          // Check if any design tasks exist (need dev server)
+          const hasDesignTasks = tasks.some(t => !!t.figmaUrl);
+
+          const missing = [];
+          if (hasDesignTasks) {
+            if (!cfg.devServerCommand) missing.push('devServerCommand');
+          }
+          if (missing.length > 0) {
+            output({ error: `Config incomplete (design tasks require dev server). Missing: ${missing.join(', ')}` });
+            break;
+          }
+
+          const initResult = {
+            ok: true,
+            config: cfg,
+            taskCount: tasks.length,
+            hasDesignTasks,
+            pending: tasks.filter(t => t.status === 'pending').length,
+            in_progress: tasks.filter(t => t.status === 'in_progress').length,
+            done: tasks.filter(t => t.status === 'done').length,
+          };
+          log('INFO', 'init', `执行初始化完成`, { taskCount: initResult.taskCount, hasDesignTasks, pending: initResult.pending, done: initResult.done, logPath: getLogPath() });
+          output(initResult);
+          break;
+        }
+        case 'context': {
+          const contextDir = getContextDir(root);
+          ensureDir(contextDir);
+          // Optional: pass task IDs to only clean files for specific tasks
+          // Usage: fe-tools.cjs init context [id1 id2 ...]
+          const taskIds = args.slice(2).map(Number).filter(n => !isNaN(n));
+
+          // Build patterns: if task IDs provided, only match those IDs; otherwise match all
+          const idPattern = taskIds.length > 0
+            ? `(${taskIds.join('|')})`
+            : '\\d+';
+          const contextPatterns = [
+            new RegExp(`^impl-result-${idPattern}\\.json$`),
+            new RegExp(`^verify-result-${idPattern}\\.json$`),
+            new RegExp(`^verify-analysis-${idPattern}\\.md$`),
+            new RegExp(`^review-result-${idPattern}\\.json$`),
+            new RegExp(`^review-analysis-${idPattern}\\.md$`),
+            new RegExp(`^fix-result-${idPattern}\\.json$`),
+            new RegExp(`^(impl-screenshot|self-check|fix-check)-${idPattern}\\.png$`),
+            new RegExp(`^a11y-snapshot-${idPattern}\\.txt$`),
+          ];
+          // Always clean non-ID-suffixed legacy files and backpressure results
+          const legacyPatterns = [
+            /^impl-result\.json$/,
+            /^verify-result\.json$/,
+            /^verify-analysis\.md$/,
+            /^review-result\.json$/,
+            /^review-analysis\.md$/,
+            /^fix-result\.json$/,
+            /^fix-result-bp\.json$/,
+          ];
+          const allPatterns = [...contextPatterns, ...legacyPatterns];
+
+          const files = fs.readdirSync(contextDir);
+          let cleaned = 0;
+          for (const f of files) {
+            if (allPatterns.some(p => p.test(f))) {
+              fs.unlinkSync(path.join(contextDir, f));
+              cleaned++;
+            }
+          }
+          output({ ok: true, contextDir, cleaned, taskIds: taskIds.length > 0 ? taskIds : 'all' });
+          break;
+        }
+        default:
+          output({ error: `Unknown init subcommand: ${subcommand}` });
+      }
+      break;
+    }
+
+    default:
+      usage();
+  }
+} catch (err) {
+  log('ERROR', 'system', `未捕获异常: ${err.message}`, { stack: err.stack });
+  closeLogger();
+  output({ error: err.message, stack: err.stack });
+  process.exit(1);
+} finally {
+  closeLogger();
+}