flow-walker-cli 0.2.0

package/src/command-schema.ts

@@ -0,0 +1,178 @@
+// Command schema for flow-walker — single source of truth
+// Used by: schema subcommand, --help --json, agent introspection
+
+export interface SchemaArg {
+  name: string;
+  required: boolean;
+  description: string;
+  type: 'string' | 'path' | 'integer';
+}
+
+export interface SchemaFlag {
+  name: string;
+  description: string;
+  type: 'string' | 'boolean' | 'integer' | 'path';
+  default?: string;
+}
+
+export interface OutputField {
+  name: string;
+  type: string;
+  description: string;
+}
+
+export interface CommandSchema {
+  name: string;
+  description: string;
+  args: SchemaArg[];
+  flags: SchemaFlag[];
+  exitCodes: Record<string, string>;
+  examples: string[];
+  outputShape?: OutputField[];
+}
+
+export const COMMAND_SCHEMAS: CommandSchema[] = [
+  {
+    name: 'walk',
+    description: 'Auto-explore app via BFS, discover screens, generate YAML flows',
+    args: [],
+    flags: [
+      { name: '--app-uri', type: 'string', description: 'VM Service WebSocket URI (ws://...)' },
+      { name: '--bundle-id', type: 'string', description: 'Connect by bundle ID' },
+      { name: '--max-depth', type: 'integer', description: 'Max navigation depth', default: '5' },
+      { name: '--output-dir', type: 'path', description: 'Output directory for YAML flows', default: './flows/' },
+      { name: '--blocklist', type: 'string', description: 'Comma-separated destructive keywords to avoid', default: 'delete,sign out,remove,reset,unpair,logout,clear all' },
+      { name: '--agent-flutter-path', type: 'path', description: 'Path to agent-flutter binary', default: 'agent-flutter' },
+      { name: '--json', type: 'boolean', description: 'NDJSON output (one event per line)' },
+      { name: '--no-json', type: 'boolean', description: 'Force human-readable output' },
+      { name: '--dry-run', type: 'boolean', description: 'Snapshot and plan without pressing' },
+      { name: '--skip-connect', type: 'boolean', description: 'Use existing agent-flutter session' },
+    ],
+    exitCodes: { '0': 'success', '2': 'error' },
+    examples: [
+      'flow-walker walk --app-uri ws://127.0.0.1:38047/abc=/ws',
+      'flow-walker walk --skip-connect --max-depth 3',
+      'flow-walker walk --bundle-id com.example.app --json',
+    ],
+  },
+  {
+    name: 'run',
+    description: 'Execute a YAML flow, produce run.json + video + screenshots',
+    args: [
+      { name: 'flow', required: true, description: 'Path to YAML flow file', type: 'path' },
+    ],
+    flags: [
+      { name: '--output-dir', type: 'path', description: 'Output directory for results', default: './run-output/' },
+      { name: '--agent-flutter-path', type: 'path', description: 'Path to agent-flutter binary', default: 'agent-flutter' },
+      { name: '--no-video', type: 'boolean', description: 'Skip video recording' },
+      { name: '--no-logs', type: 'boolean', description: 'Skip logcat capture' },
+      { name: '--json', type: 'boolean', description: 'Machine-readable JSON output' },
+      { name: '--no-json', type: 'boolean', description: 'Force human-readable output' },
+      { name: '--dry-run', type: 'boolean', description: 'Parse and resolve without executing' },
+    ],
+    exitCodes: { '0': 'all steps pass', '1': 'one or more steps fail', '2': 'error' },
+    examples: [
+      'flow-walker run flows/tab-navigation.yaml',
+      'flow-walker run flows/login.yaml --output-dir ./results/ --json',
+      'flow-walker run flows/settings.yaml --dry-run',
+    ],
+    outputShape: [
+      { name: 'id', type: 'string', description: 'Unique 10-char run ID' },
+      { name: 'flow', type: 'string', description: 'Flow name' },
+      { name: 'result', type: 'pass|fail', description: 'Overall result' },
+      { name: 'duration', type: 'number', description: 'Total milliseconds' },
+      { name: 'steps', type: 'StepResult[]', description: 'Per-step results with index, name, action, status, duration, elementCount, assertion' },
+      { name: 'device', type: 'string', description: 'Device model' },
+      { name: 'video', type: 'string?', description: 'Recording filename' },
+    ],
+  },
+  {
+    name: 'report',
+    description: 'Generate self-contained HTML report from run results',
+    args: [
+      { name: 'run-dir', required: true, description: 'Directory containing run.json', type: 'path' },
+    ],
+    flags: [
+      { name: '--output', type: 'path', description: 'Output HTML file path', default: '<run-dir>/report.html' },
+      { name: '--no-video', type: 'boolean', description: 'Exclude video from report' },
+    ],
+    exitCodes: { '0': 'success', '2': 'error' },
+    examples: [
+      'flow-walker report ./run-output/',
+      'flow-walker report ./results/ --output /tmp/report.html',
+      'flow-walker report ./results/ --no-video',
+    ],
+  },
+  {
+    name: 'push',
+    description: 'Upload report to hosted service and return shareable URL',
+    args: [
+      { name: 'run-dir', required: true, description: 'Directory containing run.json and report.html', type: 'path' },
+    ],
+    flags: [
+      { name: '--json', type: 'boolean', description: 'Machine-readable JSON output' },
+      { name: '--no-json', type: 'boolean', description: 'Force human-readable output' },
+    ],
+    exitCodes: { '0': 'success', '2': 'error' },
+    examples: [
+      'flow-walker push ./run-output/P-tnB_sgKA/',
+      'flow-walker push ./run-output/P-tnB_sgKA/ --json',
+    ],
+    outputShape: [
+      { name: 'id', type: 'string', description: 'Run ID' },
+      { name: 'url', type: 'string', description: 'JSON URL (agent-first)' },
+      { name: 'htmlUrl', type: 'string', description: 'HTML report URL (human)' },
+      { name: 'expiresAt', type: 'string', description: 'ISO 8601 expiry (30 days)' },
+    ],
+  },
+  {
+    name: 'get',
+    description: 'Fetch run data from hosted service',
+    args: [
+      { name: 'run-id', required: true, description: 'Run ID (from push or run output)', type: 'string' },
+    ],
+    flags: [
+      { name: '--json', type: 'boolean', description: 'Compact JSON output (default: pretty-printed)' },
+      { name: '--no-json', type: 'boolean', description: 'Force human-readable output' },
+    ],
+    exitCodes: { '0': 'success', '2': 'error (not found, network)' },
+    examples: [
+      'flow-walker get 25h7afGwBK',
+      'flow-walker get 25h7afGwBK --json',
+      'flow-walker get 25h7afGwBK | jq \'.steps[] | select(.status=="fail")\'',
+    ],
+    outputShape: [
+      { name: 'id', type: 'string', description: 'Run ID' },
+      { name: 'flow', type: 'string', description: 'Flow name' },
+      { name: 'result', type: 'pass|fail', description: 'Overall result' },
+      { name: 'duration', type: 'number', description: 'Total milliseconds' },
+      { name: 'steps', type: 'StepResult[]', description: 'Per-step results' },
+    ],
+  },
+  {
+    name: 'schema',
+    description: 'Show command schema for agent discovery (always JSON)',
+    args: [
+      { name: 'command', required: false, description: 'Specific command to describe', type: 'string' },
+    ],
+    flags: [],
+    exitCodes: { '0': 'success', '2': 'error (unknown command)' },
+    examples: [
+      'flow-walker schema',
+      'flow-walker schema run',
+      'flow-walker schema walk',
+    ],
+  },
+];
+
+export const SCHEMA_VERSION = '0.2.0';
+
+/** Get schema for a specific command */
+export function getCommandSchema(name: string): CommandSchema | undefined {
+  return COMMAND_SCHEMAS.find(s => s.name === name);
+}
+
+/** Get full schema envelope with version */
+export function getSchemaEnvelope(): { version: string; commands: CommandSchema[] } {
+  return { version: SCHEMA_VERSION, commands: COMMAND_SCHEMAS };
+}

package/src/errors.ts

@@ -0,0 +1,63 @@
+// Structured error handling for flow-walker
+// Every error has: code, message, hint, diagnosticId
+
+import { randomUUID } from 'node:crypto';
+
+export const ErrorCodes = {
+  INVALID_ARGS: 'INVALID_ARGS',
+  INVALID_INPUT: 'INVALID_INPUT',
+  FILE_NOT_FOUND: 'FILE_NOT_FOUND',
+  FLOW_PARSE_ERROR: 'FLOW_PARSE_ERROR',
+  STEP_FAILED: 'STEP_FAILED',
+  DEVICE_ERROR: 'DEVICE_ERROR',
+  COMMAND_FAILED: 'COMMAND_FAILED',
+} as const;
+
+export type ErrorCode = typeof ErrorCodes[keyof typeof ErrorCodes];
+
+export class FlowWalkerError extends Error {
+  code: ErrorCode;
+  hint?: string;
+  diagnosticId: string;
+
+  constructor(code: ErrorCode, message: string, hint?: string) {
+    super(message);
+    this.name = 'FlowWalkerError';
+    this.code = code;
+    this.hint = hint;
+    this.diagnosticId = randomUUID().slice(0, 8);
+  }
+
+  toJSON(): { error: { code: string; message: string; hint?: string; diagnosticId: string } } {
+    return {
+      error: {
+        code: this.code,
+        message: this.message,
+        ...(this.hint ? { hint: this.hint } : {}),
+        diagnosticId: this.diagnosticId,
+      },
+    };
+  }
+}
+
+/** Format any error as structured output */
+export function formatError(err: unknown, json: boolean): string {
+  if (err instanceof FlowWalkerError) {
+    if (json) {
+      return JSON.stringify(err.toJSON());
+    }
+    const parts = [`Error [${err.code}:${err.diagnosticId}]: ${err.message}`];
+    if (err.hint) parts.push(`Hint: ${err.hint}`);
+    return parts.join('\n');
+  }
+
+  // Wrap unknown errors
+  const wrapped = new FlowWalkerError(
+    ErrorCodes.COMMAND_FAILED,
+    String(err),
+  );
+  if (json) {
+    return JSON.stringify(wrapped.toJSON());
+  }
+  return `Error [${wrapped.code}:${wrapped.diagnosticId}]: ${wrapped.message}`;
+}

package/src/fingerprint.ts

@@ -0,0 +1,82 @@
+import { createHash } from 'node:crypto';
+import type { SnapshotElement } from './types.ts';
+
+/**
+ * Compute a deterministic screen fingerprint from interactive elements.
+ * Uses element types and counts only — ignores text content (which is dynamic).
+ * Similar screens with minor count differences produce the same fingerprint
+ * via count bucketing.
+ */
+export function computeFingerprint(elements: SnapshotElement[]): string {
+  // Count elements by type
+  const typeCounts = new Map<string, number>();
+  for (const el of elements) {
+    const key = el.flutterType || el.type;
+    typeCounts.set(key, (typeCounts.get(key) || 0) + 1);
+  }
+
+  // Bucket counts to handle minor variations (e.g., list length differences)
+  // 0 → 0, 1 → 1, 2-3 → 2, 4-7 → 4, 8+ → 8
+  const bucketed = new Map<string, number>();
+  for (const [type, count] of typeCounts) {
+    bucketed.set(type, bucketCount(count));
+  }
+
+  // Sort by type name for determinism
+  const sorted = [...bucketed.entries()].sort((a, b) => a[0].localeCompare(b[0]));
+
+  // Hash the type:count pairs
+  const input = sorted.map(([type, count]) => `${type}:${count}`).join('|');
+  return createHash('sha256').update(input).digest('hex').slice(0, 12);
+}
+
+/** Bucket a count to reduce sensitivity to minor variations */
+function bucketCount(n: number): number {
+  if (n <= 1) return n;
+  if (n <= 3) return 2;
+  if (n <= 7) return 4;
+  return 8;
+}
+
+/**
+ * Derive a human-readable screen name from its elements.
+ * Picks the most descriptive text from the first few elements.
+ */
+export function deriveScreenName(elements: SnapshotElement[]): string {
+  // Look for text that looks like a title (short, at top of screen)
+  const candidates = elements
+    .filter(el => el.text && el.text.length > 0 && el.text.length < 40)
+    .map(el => el.text);
+
+  if (candidates.length > 0) {
+    return toKebabCase(candidates[0]);
+  }
+
+  // Fallback: use dominant element type
+  const types = elements.map(el => el.type);
+  const dominant = mode(types) || 'unknown';
+  return `screen-${dominant}-${elements.length}`;
+}
+
+function toKebabCase(s: string): string {
+  return s
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-|-$/g, '');
+}
+
+function mode(arr: string[]): string | undefined {
+  const counts = new Map<string, number>();
+  for (const item of arr) {
+    counts.set(item, (counts.get(item) || 0) + 1);
+  }
+  let best: string | undefined;
+  let bestCount = 0;
+  for (const [item, count] of counts) {
+    if (count > bestCount) {
+      best = item;
+      bestCount = count;
+    }
+  }
+  return best;
+}

package/src/flow-parser.ts

@@ -0,0 +1,222 @@
+// YAML flow parser for flow-walker
+// Parses the flow format used in app/e2e/flows/*.yaml
+
+import { readFileSync } from 'node:fs';
+import type { Flow, FlowStep } from './types.ts';
+import { FlowWalkerError, ErrorCodes } from './errors.ts';
+
+/** Parse a YAML flow file into a Flow object */
+export function parseFlow(yamlContent: string): Flow {
+  const lines = yamlContent.split('\n');
+  const flow: Partial<Flow> = { steps: [] };
+  let currentStep: Partial<FlowStep> | null = null;
+  let inSteps = false;
+  let inCovers = false;
+  let inPrerequisites = false;
+
+  for (const rawLine of lines) {
+    const line = rawLine.trimEnd();
+
+    // Skip comments and blank lines at top level
+    if (line.startsWith('#') || line.trim() === '') continue;
+
+    // Top-level fields
+    if (!line.startsWith(' ') && !line.startsWith('\t')) {
+      inCovers = false;
+      inPrerequisites = false;
+
+      if (line.startsWith('name:')) {
+        flow.name = parseScalarValue(line.slice(5));
+      } else if (line.startsWith('description:')) {
+        flow.description = parseScalarValue(line.slice(12));
+      } else if (line.startsWith('app:')) {
+        flow.app = parseScalarValue(line.slice(4));
+      } else if (line.startsWith('app_url:')) {
+        flow.appUrl = parseScalarValue(line.slice(8));
+      } else if (line.startsWith('setup:')) {
+        flow.setup = parseScalarValue(line.slice(6));
+      } else if (line.startsWith('covers:')) {
+        inCovers = true;
+        flow.covers = [];
+      } else if (line.startsWith('prerequisites:')) {
+        inPrerequisites = true;
+        flow.prerequisites = [];
+      } else if (line.startsWith('steps:')) {
+        inSteps = true;
+      }
+      continue;
+    }
+
+    // Array items under covers/prerequisites
+    const trimmed = line.trim();
+    if (inCovers && trimmed.startsWith('- ')) {
+      flow.covers!.push(parseScalarValue(trimmed.slice(2)));
+      continue;
+    }
+    if (inPrerequisites && trimmed.startsWith('- ')) {
+      flow.prerequisites!.push(parseScalarValue(trimmed.slice(2)));
+      continue;
+    }
+
+    if (!inSteps) continue;
+
+    // Step list items
+    if (trimmed.startsWith('- name:')) {
+      if (currentStep && currentStep.name) {
+        flow.steps!.push(currentStep as FlowStep);
+      }
+      currentStep = { name: parseScalarValue(trimmed.slice(7)) };
+      continue;
+    }
+
+    if (!currentStep) continue;
+
+    // Step fields
+    if (trimmed.startsWith('press:')) {
+      currentStep.press = parseInlineObject(trimmed.slice(6).trim()) as FlowStep['press'];
+    } else if (trimmed.startsWith('scroll:')) {
+      currentStep.scroll = parseScalarValue(trimmed.slice(7));
+    } else if (trimmed.startsWith('fill:')) {
+      currentStep.fill = parseInlineObject(trimmed.slice(5).trim()) as FlowStep['fill'];
+    } else if (trimmed.startsWith('back:')) {
+      currentStep.back = parseScalarValue(trimmed.slice(5)) === 'true';
+    } else if (trimmed.startsWith('screenshot:')) {
+      currentStep.screenshot = parseScalarValue(trimmed.slice(11));
+    } else if (trimmed.startsWith('note:')) {
+      currentStep.note = parseScalarValue(trimmed.slice(5));
+    } else if (trimmed.startsWith('assert:')) {
+      const inlineVal = trimmed.slice(7).trim();
+      if (inlineVal) {
+        currentStep.assert = parseInlineObject(inlineVal) as FlowStep['assert'];
+      } else {
+        currentStep.assert = {};
+      }
+    } else if (trimmed.startsWith('interactive_count:')) {
+      if (!currentStep.assert) currentStep.assert = {};
+      currentStep.assert.interactive_count = parseInlineObject(trimmed.slice(18).trim()) as { min: number };
+    } else if (trimmed.startsWith('bottom_nav_tabs:')) {
+      if (!currentStep.assert) currentStep.assert = {};
+      currentStep.assert.bottom_nav_tabs = parseInlineObject(trimmed.slice(16).trim()) as { min: number };
+    } else if (trimmed.startsWith('has_type:')) {
+      if (!currentStep.assert) currentStep.assert = {};
+      currentStep.assert.has_type = parseInlineObject(trimmed.slice(9).trim()) as { type: string; min?: number };
+    } else if (trimmed.startsWith('text_visible:')) {
+      if (!currentStep.assert) currentStep.assert = {};
+      currentStep.assert.text_visible = parseInlineArray(trimmed.slice(13).trim());
+    } else if (trimmed.startsWith('text_not_visible:')) {
+      if (!currentStep.assert) currentStep.assert = {};
+      currentStep.assert.text_not_visible = parseInlineArray(trimmed.slice(17).trim());
+    }
+  }
+
+  // Push last step
+  if (currentStep && currentStep.name) {
+    flow.steps!.push(currentStep as FlowStep);
+  }
+
+  if (!flow.name) throw new FlowWalkerError(ErrorCodes.FLOW_PARSE_ERROR, 'Flow missing required field: name', 'Add a name: field at the top of the YAML flow');
+  if (!flow.steps || flow.steps.length === 0) throw new FlowWalkerError(ErrorCodes.FLOW_PARSE_ERROR, 'Flow has no steps', 'Add steps: with at least one - name: entry');
+
+  return {
+    name: flow.name,
+    description: flow.description ?? '',
+    ...(flow.app ? { app: flow.app } : {}),
+    ...(flow.appUrl ? { appUrl: flow.appUrl } : {}),
+    covers: flow.covers,
+    prerequisites: flow.prerequisites,
+    setup: flow.setup ?? 'normal',
+    steps: flow.steps,
+  };
+}
+
+/** Load and parse a YAML flow from a file path */
+export function parseFlowFile(filePath: string): Flow {
+  const content = readFileSync(filePath, 'utf-8');
+  return parseFlow(content);
+}
+
+/** Parse a scalar YAML value (strip quotes, inline comments) */
+function parseScalarValue(raw: string): string {
+  let val = raw.trim();
+  // Remove inline comments (but not # inside quotes)
+  const commentIdx = val.indexOf('  #');
+  if (commentIdx > 0) val = val.slice(0, commentIdx).trim();
+  // Strip surrounding quotes
+  if ((val.startsWith('"') && val.endsWith('"')) ||
+      (val.startsWith("'") && val.endsWith("'"))) {
+    val = val.slice(1, -1);
+  }
+  return val;
+}
+
+/** Parse an inline YAML object like { type: button, position: rightmost } */
+function parseInlineObject(raw: string): Record<string, unknown> {
+  const str = raw.trim();
+  if (!str.startsWith('{') || !str.endsWith('}')) {
+    // Simple scalar — return as-is in a value field
+    return { value: parseScalarValue(str) } as Record<string, unknown>;
+  }
+
+  const inner = str.slice(1, -1).trim();
+  const result: Record<string, unknown> = {};
+
+  // Split by comma, handling quoted strings
+  const pairs = splitCommas(inner);
+  for (const pair of pairs) {
+    const colonIdx = pair.indexOf(':');
+    if (colonIdx < 0) continue;
+    const key = pair.slice(0, colonIdx).trim();
+    const valRaw = pair.slice(colonIdx + 1).trim();
+    const val = parseScalarValue(valRaw);
+
+    // Type coercion
+    if (val === 'true') result[key] = true;
+    else if (val === 'false') result[key] = false;
+    else if (/^\d+$/.test(val)) result[key] = parseInt(val, 10);
+    else if (/^\d+\.\d+$/.test(val)) result[key] = parseFloat(val);
+    else result[key] = val;
+  }
+
+  return result;
+}
+
+/** Parse an inline YAML array like ["Featured", "Create Your Own App"] */
+function parseInlineArray(raw: string): string[] {
+  const str = raw.trim();
+  if (!str.startsWith('[') || !str.endsWith(']')) {
+    // Single value — wrap in array
+    const val = parseScalarValue(str);
+    return val ? [val] : [];
+  }
+
+  const inner = str.slice(1, -1).trim();
+  if (!inner) return [];
+
+  return splitCommas(inner).map(s => parseScalarValue(s)).filter(Boolean);
+}
+
+/** Split string by commas, respecting quoted strings */
+function splitCommas(str: string): string[] {
+  const parts: string[] = [];
+  let current = '';
+  let inQuote = false;
+  let quoteChar = '';
+
+  for (const ch of str) {
+    if (!inQuote && (ch === '"' || ch === "'")) {
+      inQuote = true;
+      quoteChar = ch;
+      current += ch;
+    } else if (inQuote && ch === quoteChar) {
+      inQuote = false;
+      current += ch;
+    } else if (!inQuote && ch === ',') {
+      parts.push(current.trim());
+      current = '';
+    } else {
+      current += ch;
+    }
+  }
+  if (current.trim()) parts.push(current.trim());
+  return parts;
+}

package/src/graph.ts

@@ -0,0 +1,73 @@
+import type { ScreenNode, ScreenEdge } from './types.ts';
+
+/**
+ * Directed navigation graph tracking screens and transitions.
+ */
+export class NavigationGraph {
+  nodes: Map<string, ScreenNode> = new Map();
+  edges: ScreenEdge[] = [];
+
+  /** Add or update a screen node */
+  addScreen(id: string, name: string, elementTypes: string[], elementCount: number): ScreenNode {
+    const existing = this.nodes.get(id);
+    if (existing) {
+      existing.visits += 1;
+      return existing;
+    }
+    const node: ScreenNode = {
+      id,
+      name,
+      elementTypes,
+      elementCount,
+      firstSeen: Date.now(),
+      visits: 1,
+    };
+    this.nodes.set(id, node);
+    return node;
+  }
+
+  /** Add an edge (transition) between two screens */
+  addEdge(source: string, target: string, element: { ref: string; type: string; text: string }): void {
+    // Avoid duplicate edges for same source→target via same element type+text
+    const exists = this.edges.some(
+      e => e.source === source && e.target === target &&
+           e.element.type === element.type && e.element.text === element.text,
+    );
+    if (!exists) {
+      this.edges.push({ source, target, element });
+    }
+  }
+
+  /** Check if a screen has been visited */
+  hasScreen(id: string): boolean {
+    return this.nodes.has(id);
+  }
+
+  /** Get visit count for a screen */
+  visitCount(id: string): number {
+    return this.nodes.get(id)?.visits ?? 0;
+  }
+
+  /** Get all edges from a source screen */
+  edgesFrom(source: string): ScreenEdge[] {
+    return this.edges.filter(e => e.source === source);
+  }
+
+  /** Get all edges to a target screen */
+  edgesTo(target: string): ScreenEdge[] {
+    return this.edges.filter(e => e.target === target);
+  }
+
+  /** Get unique screen count */
+  screenCount(): number {
+    return this.nodes.size;
+  }
+
+  /** Export graph as JSON-serializable object */
+  toJSON(): { nodes: ScreenNode[]; edges: ScreenEdge[] } {
+    return {
+      nodes: [...this.nodes.values()],
+      edges: this.edges,
+    };
+  }
+}