flow-walker-cli 0.2.0

package/src/push.ts

@@ -0,0 +1,170 @@
+// Remote API: upload/retrieve reports and run data from flow-walker hosted service
+
+import { readFileSync, existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { FlowWalkerError, ErrorCodes } from './errors.ts';
+
+const DEFAULT_API_URL = 'https://flow-walker.beastoin.workers.dev';
+
+function resolveApiUrl(apiUrl?: string): string {
+  return apiUrl || process.env.FLOW_WALKER_API_URL || DEFAULT_API_URL;
+}
+
+export interface PushResult {
+  id: string;
+  url: string;
+  htmlUrl: string;
+  expiresAt: string;
+}
+
+/** Upload a report to the hosted service */
+export async function pushReport(
+  runDir: string,
+  options: { apiUrl?: string; runId?: string } = {},
+): Promise<PushResult> {
+  const apiUrl = resolveApiUrl(options.apiUrl);
+
+  // Find report.html
+  const reportPath = join(runDir, 'report.html');
+  if (!existsSync(reportPath)) {
+    throw new FlowWalkerError(
+      ErrorCodes.FILE_NOT_FOUND,
+      'report.html not found in run directory',
+      'Generate it first: flow-walker report <run-dir>',
+    );
+  }
+
+  // Read metadata from run.json if available
+  let runId = options.runId;
+  let flowName: string | undefined;
+  let stepsTotal: number | undefined;
+  let stepsPass: number | undefined;
+  let duration: number | undefined;
+  let appName: string | undefined;
+  let appUrl: string | undefined;
+  let runJsonContent: string | undefined;
+  const runJsonPath = join(runDir, 'run.json');
+  if (existsSync(runJsonPath)) {
+    try {
+      const raw = readFileSync(runJsonPath, 'utf-8');
+      const runData = JSON.parse(raw);
+      if (!runId) runId = runData.id;
+      if (runData.flow) flowName = String(runData.flow);
+      if (typeof runData.duration === 'number') duration = runData.duration;
+      if (runData.app) appName = String(runData.app);
+      if (runData.appUrl || runData.app_url) appUrl = String(runData.appUrl || runData.app_url);
+      if (Array.isArray(runData.steps)) {
+        stepsTotal = runData.steps.length;
+        stepsPass = runData.steps.filter((s: { status?: string }) => s.status === 'pass').length;
+      }
+      // Prepare run.json for upload — strip local file paths
+      const uploadData = { ...runData };
+      delete uploadData.video;
+      delete uploadData.log;
+      if (Array.isArray(uploadData.steps)) {
+        uploadData.steps = uploadData.steps.map((s: Record<string, unknown>) => {
+          const { screenshot: _s, ...rest } = s;
+          return rest;
+        });
+      }
+      runJsonContent = JSON.stringify(uploadData);
+    } catch { /* ignore parse errors */ }
+  }
+
+  // Read report
+  const reportContent = readFileSync(reportPath);
+
+  // Upload report.html
+  const headers: Record<string, string> = {
+    'Content-Type': 'text/html',
+    'Content-Length': String(reportContent.byteLength),
+  };
+  if (runId) headers['X-Run-ID'] = runId;
+  if (flowName) headers['X-Flow-Name'] = flowName;
+  if (stepsTotal !== undefined) headers['X-Steps-Total'] = String(stepsTotal);
+  if (stepsPass !== undefined) headers['X-Steps-Pass'] = String(stepsPass);
+  if (duration !== undefined) headers['X-Duration'] = String(duration);
+  if (appName) headers['X-App-Name'] = appName;
+  if (appUrl) headers['X-App-URL'] = appUrl;
+
+  let response: Response;
+  try {
+    response = await fetch(`${apiUrl}/runs`, {
+      method: 'POST',
+      headers,
+      body: reportContent,
+    });
+  } catch (err) {
+    throw new FlowWalkerError(
+      ErrorCodes.COMMAND_FAILED,
+      `Failed to connect to ${apiUrl}: ${err instanceof Error ? err.message : String(err)}`,
+      `Check your network or set FLOW_WALKER_API_URL`,
+    );
+  }
+
+  if (!response.ok) {
+    let errorMsg = `Upload failed (HTTP ${response.status})`;
+    try {
+      const body = await response.json() as { error?: { message?: string } };
+      if (body.error?.message) errorMsg = body.error.message;
+    } catch { /* ignore */ }
+    throw new FlowWalkerError(
+      ErrorCodes.COMMAND_FAILED,
+      errorMsg,
+      'Try again or check FLOW_WALKER_API_URL',
+    );
+  }
+
+  const result = await response.json() as PushResult;
+
+  // Upload run.json (best-effort — don't fail push if this fails)
+  if (runJsonContent && result.id) {
+    try {
+      await fetch(`${apiUrl}/runs/${result.id}.json`, {
+        method: 'PUT',
+        headers: { 'Content-Type': 'application/json' },
+        body: runJsonContent,
+      });
+    } catch { /* best-effort */ }
+  }
+
+  return result;
+}
+
+/** Fetch run data from hosted service */
+export async function getRunData(
+  runId: string,
+  options: { apiUrl?: string } = {},
+): Promise<unknown> {
+  const apiUrl = resolveApiUrl(options.apiUrl);
+
+  let response: Response;
+  try {
+    response = await fetch(`${apiUrl}/runs/${runId}`, {
+      headers: { 'Accept': 'application/json' },
+    });
+  } catch (err) {
+    throw new FlowWalkerError(
+      ErrorCodes.COMMAND_FAILED,
+      `Failed to connect to ${apiUrl}: ${err instanceof Error ? err.message : String(err)}`,
+      'Check your network or set FLOW_WALKER_API_URL',
+    );
+  }
+
+  if (!response.ok) {
+    if (response.status === 404) {
+      throw new FlowWalkerError(
+        ErrorCodes.FILE_NOT_FOUND,
+        `Run ${runId} not found`,
+        'Check the run ID or push the run first: flow-walker push <run-dir>',
+      );
+    }
+    throw new FlowWalkerError(
+      ErrorCodes.COMMAND_FAILED,
+      `Failed to fetch run (HTTP ${response.status})`,
+      'Try again or check FLOW_WALKER_API_URL',
+    );
+  }
+
+  return response.json();
+}

package/src/reporter.ts

@@ -0,0 +1,211 @@
+// HTML report generator: run.json → self-contained HTML viewer
+
+import { readFileSync, writeFileSync } from 'node:fs';
+import { join, dirname } from 'node:path';
+import type { RunResult, StepResult } from './run-schema.ts';
+
+export interface ReportOptions {
+  noVideo?: boolean;
+  output?: string;
+}
+
+/** Generate a self-contained HTML report from a RunResult */
+export function generateReport(runResult: RunResult, runDir: string, options: ReportOptions = {}): string {
+  const outputPath = options.output ?? join(runDir, 'report.html');
+
+  // Embed video as base64 if available
+  let videoBase64 = '';
+  if (!options.noVideo && runResult.video) {
+    try {
+      const videoPath = join(runDir, runResult.video);
+      const videoData = readFileSync(videoPath);
+      videoBase64 = videoData.toString('base64');
+    } catch { /* video not available */ }
+  }
+
+  // Embed screenshots as base64
+  const screenshotData: Map<string, string> = new Map();
+  for (const step of runResult.steps) {
+    if (step.screenshot) {
+      try {
+        const imgPath = join(runDir, step.screenshot);
+        const imgData = readFileSync(imgPath);
+        screenshotData.set(step.screenshot, imgData.toString('base64'));
+      } catch { /* screenshot not available */ }
+    }
+  }
+
+  const html = buildHtml(runResult, videoBase64, screenshotData);
+  writeFileSync(outputPath, html);
+  return outputPath;
+}
+
+/** Build the HTML string */
+export function buildHtml(
+  run: RunResult,
+  videoBase64: string,
+  screenshots: Map<string, string>,
+): string {
+  const passCount = run.steps.filter(s => s.status === 'pass').length;
+  const failCount = run.steps.filter(s => s.status === 'fail').length;
+  const durationSec = (run.duration / 1000).toFixed(1);
+
+  return `<!DOCTYPE html>
+<html lang="en">
+<head>
+<meta charset="UTF-8">
+<meta name="viewport" content="width=device-width, initial-scale=1.0">
+<title>E2E Flow Viewer: ${escHtml(run.flow)}</title>
+<style>
+  * { margin: 0; padding: 0; box-sizing: border-box; }
+  body { font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif; background: #1a1a2e; color: #eee; padding: 20px; }
+  .header { text-align: center; margin-bottom: 20px; }
+  .header h1 { font-size: 1.5em; margin-bottom: 8px; }
+  .header .meta { font-size: 0.9em; color: #aaa; }
+  .legend { display: flex; gap: 16px; justify-content: center; margin: 12px 0; font-size: 0.85em; }
+  .dot { display: inline-block; width: 10px; height: 10px; border-radius: 50%; margin-right: 4px; }
+  .dot.pass { background: #00d26a; }
+  .dot.fail { background: #e94560; }
+  .dot.active { background: #ffa500; }
+  .container { display: flex; gap: 20px; max-width: 1200px; margin: 0 auto; }
+  .video-panel { flex: 1; position: sticky; top: 20px; align-self: flex-start; }
+  .video-panel video { width: 100%; max-width: 360px; border-radius: 12px; border: 2px solid #333; }
+  .steps-panel { flex: 1; display: flex; flex-direction: column; gap: 12px; }
+  .step { background: #16213e; border-radius: 10px; padding: 14px; cursor: pointer; border: 2px solid transparent; transition: border-color 0.2s; }
+  .step:hover { border-color: #555; }
+  .step.active { border-color: #ffa500; }
+  .step.pass { border-left: 4px solid #00d26a; }
+  .step.fail { border-left: 4px solid #e94560; }
+  .step-header { display: flex; align-items: center; gap: 10px; }
+  .step-num { font-weight: bold; font-size: 1.1em; min-width: 24px; }
+  .step-name { font-weight: 600; }
+  .step-detail { font-size: 0.85em; color: #aaa; margin-top: 4px; }
+  .step-time { font-size: 0.8em; color: #e94560; font-family: monospace; margin-top: 2px; }
+  .step-result { font-size: 0.85em; margin-top: 4px; }
+  .step-result.pass { color: #00d26a; }
+  .step-result.fail { color: #e94560; }
+  .step-thumb { max-width: 120px; border-radius: 6px; margin-top: 8px; display: none; }
+  .step.active .step-thumb { display: block; }
+  .no-video { display: flex; align-items: center; justify-content: center; width: 360px; height: 640px; background: #16213e; border-radius: 12px; border: 2px solid #333; color: #666; }
+  @media (max-width: 768px) {
+    .container { flex-direction: column; }
+    .video-panel { position: static; }
+    .video-panel video, .no-video { max-width: 100%; width: 100%; }
+  }
+</style>
+</head>
+<body>
+<div class="header">
+  <h1>${escHtml(run.flow)}</h1>
+  <div class="meta">${escHtml(run.device)} &middot; ${durationSec}s &middot; ${run.steps.length} steps</div>
+  <div class="legend">
+    <span><span class="dot pass"></span> PASS (${passCount})</span>
+    <span><span class="dot fail"></span> FAIL (${failCount})</span>
+    <span><span class="dot active"></span> Active step</span>
+    <span>Duration: ${durationSec}s | ${run.steps.length} steps | ${run.result === 'pass' ? 'All PASS' : failCount + ' FAIL'}</span>
+  </div>
+</div>
+<div class="container">
+  <div class="video-panel">
+    ${videoBase64
+      ? `<video id="video" controls><source src="data:video/mp4;base64,${videoBase64}" type="video/mp4"></video>`
+      : '<div class="no-video">No video</div>'}
+  </div>
+  <div class="steps-panel">
+${run.steps.map((s, i) => renderStep(s, i, screenshots)).join('\n')}
+  </div>
+</div>
+<script>
+const video = document.getElementById('video');
+const steps = document.querySelectorAll('.step');
+
+function jumpTo(time, el) {
+  if (video) { video.currentTime = time; video.play(); }
+  steps.forEach(s => s.classList.remove('active'));
+  if (el) el.classList.add('active');
+}
+
+// Keyboard shortcuts: 1-9 jump to step, Space play/pause
+document.addEventListener('keydown', (e) => {
+  const num = parseInt(e.key);
+  if (num >= 1 && num <= steps.length) {
+    const step = steps[num - 1];
+    const time = parseFloat(step.getAttribute('data-time') || '0');
+    jumpTo(time, step);
+  }
+  if (e.key === ' ' && video) {
+    e.preventDefault();
+    video.paused ? video.play() : video.pause();
+  }
+});
+
+// Auto-highlight step based on video time
+if (video) {
+  video.addEventListener('timeupdate', () => {
+    const t = video.currentTime;
+    let active = steps[0];
+    for (const step of steps) {
+      if (parseFloat(step.getAttribute('data-time') || '0') <= t) active = step;
+    }
+    steps.forEach(s => s.classList.remove('active'));
+    if (active) active.classList.add('active');
+  });
+}
+</script>
+</body>
+</html>`;
+}
+
+function renderStep(step: StepResult, index: number, screenshots: Map<string, string>): string {
+  const timeSec = (step.timestamp / 1000).toFixed(1);
+  const statusClass = step.status === 'pass' ? 'pass' : step.status === 'fail' ? 'fail' : '';
+  const statusIcon = step.status === 'pass' ? '✓' : step.status === 'fail' ? '✗' : '○';
+
+  let detail = step.action;
+  if (step.assertion?.interactive_count) {
+    detail = `assert: interactive_count ≥ ${step.assertion.interactive_count.min}`;
+  }
+  if (step.assertion?.bottom_nav_tabs) {
+    detail += (detail ? ', ' : 'assert: ') + `bottom_nav_tabs ≥ ${step.assertion.bottom_nav_tabs.min}`;
+  }
+
+  let resultText = '';
+  if (step.assertion?.interactive_count) {
+    resultText = `${statusIcon} ${step.assertion.interactive_count.actual} elements`;
+  }
+  if (step.assertion?.bottom_nav_tabs) {
+    resultText += (resultText ? ', ' : `${statusIcon} `) + `${step.assertion.bottom_nav_tabs.actual} nav tabs`;
+  }
+  if (step.error) {
+    resultText = `${statusIcon} ${step.error}`;
+  }
+  if (!resultText && step.status === 'pass') {
+    resultText = `${statusIcon} ${step.elementCount} elements`;
+  }
+
+  let thumbHtml = '';
+  if (step.screenshot && screenshots.has(step.screenshot)) {
+    thumbHtml = `<img class="step-thumb" src="data:image/png;base64,${screenshots.get(step.screenshot)}" alt="Step ${index + 1}">`;
+  }
+
+  return `    <div class="step ${statusClass}" data-time="${timeSec}" onclick="jumpTo(${timeSec}, this)">
+      <div class="step-header">
+        <div class="step-num">${index + 1}</div>
+        <div>
+          <div class="step-name">${escHtml(step.name)}</div>
+          <div class="step-detail">${escHtml(detail)}</div>
+          <div class="step-time">⏱ 0:${timeSec.padStart(4, '0')}</div>
+          <div class="step-result ${statusClass}">${escHtml(resultText)}</div>
+        </div>
+      </div>
+      ${thumbHtml}
+    </div>`;
+}
+
+function escHtml(str: string): string {
+  return str
+    .replace(/&/g, '&amp;')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+    .replace(/"/g, '&quot;');
+}

package/src/run-schema.ts

@@ -0,0 +1,71 @@
+// Run result schema for flow-walker
+
+import { randomBytes } from 'node:crypto';
+
+/** Generate a short URL-safe run ID (10 chars, base64url) */
+export function generateRunId(): string {
+  // 8 random bytes → 10 base64url chars (after trimming padding)
+  // Collision probability: ~1 in 2^64 — safe for any practical volume
+  return randomBytes(8)
+    .toString('base64url')
+    .slice(0, 10);
+}
+
+/** Result of executing a single step */
+export interface StepResult {
+  index: number;          // 0-based step index
+  name: string;
+  action: string;         // "press" | "scroll" | "fill" | "back" | "assert" | "screenshot"
+  status: 'pass' | 'fail' | 'skip';
+  timestamp: number;      // ms since flow start
+  duration: number;       // ms this step took
+  elementCount: number;
+  screenshot?: string;    // path to screenshot file
+  assertion?: {
+    interactive_count?: { min: number; actual: number };
+    bottom_nav_tabs?: { min: number; actual: number };
+    has_type?: { type: string; min: number; actual: number };
+    text_visible?: { expected: string[]; found: string[]; missing: string[] };
+    text_not_visible?: { expected_absent: string[]; absent: string[]; unexpected: string[] };
+  };
+  error?: string;         // error message if failed
+}
+
+/** Complete run result */
+export interface RunResult {
+  id: string;             // unique run ID (10-char base64url)
+  flow: string;           // flow name
+  app?: string;           // app name (from flow YAML)
+  appUrl?: string;        // app URL (from flow YAML)
+  device: string;         // device model/serial
+  startedAt: string;      // ISO 8601
+  duration: number;       // total ms
+  result: 'pass' | 'fail';
+  steps: StepResult[];
+  video?: string;         // path to video file
+  log?: string;           // path to log file
+}
+
+/** Validate a RunResult has all required fields */
+export function validateRunResult(data: unknown): data is RunResult {
+  if (typeof data !== 'object' || data === null) return false;
+  const r = data as Record<string, unknown>;
+  if (typeof r.id !== 'string') return false;
+  if (typeof r.flow !== 'string') return false;
+  if (typeof r.device !== 'string') return false;
+  if (typeof r.startedAt !== 'string') return false;
+  if (typeof r.duration !== 'number') return false;
+  if (r.result !== 'pass' && r.result !== 'fail') return false;
+  if (!Array.isArray(r.steps)) return false;
+  for (const step of r.steps) {
+    if (typeof step !== 'object' || step === null) return false;
+    const s = step as Record<string, unknown>;
+    if (typeof s.name !== 'string') return false;
+    if (typeof s.action !== 'string') return false;
+    if (s.status !== 'pass' && s.status !== 'fail' && s.status !== 'skip') return false;
+    if (typeof s.timestamp !== 'number') return false;
+    if (typeof s.duration !== 'number') return false;
+    if (typeof s.elementCount !== 'number') return false;
+  }
+  return true;
+}