flow-walker-cli 0.2.0

package/src/runner.ts

@@ -0,0 +1,391 @@
+// Flow executor: runs YAML flows via agent-flutter
+
+import { join } from 'node:path';
+import { writeFileSync } from 'node:fs';
+import type { Flow, FlowStep, SnapshotElement } from './types.ts';
+import { AgentBridge } from './agent-bridge.ts';
+import { generateRunId, type RunResult, type StepResult } from './run-schema.ts';
+import { screenshot as captureScreenshot, startRecording, stopRecording, startLogcat, stopLogcat, getDeviceName, ensureDir } from './capture.ts';
+
+export interface RunOptions {
+  outputDir: string;
+  noVideo?: boolean;
+  noLogs?: boolean;
+  json?: boolean;
+  agentFlutterPath?: string;
+}
+
+/** Execute a flow and produce a RunResult */
+export async function runFlow(flow: Flow, options: RunOptions): Promise<RunResult> {
+  const bridge = new AgentBridge(options.agentFlutterPath ?? 'agent-flutter');
+  const runId = generateRunId();
+
+  // Append run ID to output dir so multiple runs don't overwrite each other
+  const outputDir = join(options.outputDir, runId);
+  ensureDir(outputDir);
+
+  const device = getDeviceName();
+  const startedAt = new Date().toISOString();
+  const t0 = Date.now();
+  const steps: StepResult[] = [];
+
+  // Start video recording
+  let videoHandle: ReturnType<typeof startRecording> | null = null;
+  if (!options.noVideo) {
+    try {
+      videoHandle = startRecording();
+    } catch { /* warn but continue */ }
+  }
+
+  // Start logcat
+  let logHandle: ReturnType<typeof startLogcat> | null = null;
+  if (!options.noLogs) {
+    try {
+      logHandle = startLogcat();
+    } catch { /* warn but continue */ }
+  }
+
+  // Execute each step
+  for (let i = 0; i < flow.steps.length; i++) {
+    const step = flow.steps[i];
+    const stepStart = Date.now();
+    const timestamp = stepStart - t0;
+
+    try {
+      const result = await executeStep(step, bridge, outputDir, i + 1);
+      steps.push({
+        ...result,
+        index: i,
+        timestamp,
+        duration: Date.now() - stepStart,
+      });
+    } catch (err) {
+      // Step failed — mark and continue
+      const snapshot = await safeSnapshot(bridge);
+      steps.push({
+        index: i,
+        name: step.name,
+        action: getStepAction(step),
+        status: 'fail',
+        timestamp,
+        duration: Date.now() - stepStart,
+        elementCount: snapshot.length,
+        error: String(err),
+      });
+    }
+
+    if (!options.json) {
+      const s = steps[steps.length - 1];
+      const icon = s.status === 'pass' ? '✓' : s.status === 'fail' ? '✗' : '○';
+      console.log(`  ${icon} Step ${i + 1}: ${s.name} [${s.status}] (${s.duration}ms, ${s.elementCount} elements)`);
+    }
+  }
+
+  const duration = Date.now() - t0;
+
+  // Stop video
+  let videoPath: string | undefined;
+  if (videoHandle) {
+    const localVideo = join(outputDir, 'recording.mp4');
+    if (stopRecording(videoHandle, localVideo)) {
+      videoPath = 'recording.mp4';
+    }
+  }
+
+  // Stop logcat
+  let logPath: string | undefined;
+  if (logHandle) {
+    const logLines = stopLogcat(logHandle);
+    if (logLines.length > 0) {
+      const localLog = join(outputDir, 'device.log');
+      writeFileSync(localLog, logLines.join('\n'));
+      logPath = 'device.log';
+    }
+  }
+
+  const overallResult = steps.every(s => s.status !== 'fail') ? 'pass' as const : 'fail' as const;
+
+  const runResult: RunResult = {
+    id: runId,
+    flow: flow.name,
+    ...(flow.app ? { app: flow.app } : {}),
+    ...(flow.appUrl ? { appUrl: flow.appUrl } : {}),
+    device,
+    startedAt,
+    duration,
+    result: overallResult,
+    steps,
+    video: videoPath,
+    log: logPath,
+  };
+
+  // Write run.json
+  const runJsonPath = join(outputDir, 'run.json');
+  writeFileSync(runJsonPath, JSON.stringify(runResult, null, 2));
+
+  return runResult;
+}
+
+/** Execute a single step */
+async function executeStep(
+  step: FlowStep,
+  bridge: AgentBridge,
+  outputDir: string,
+  stepNum: number,
+): Promise<StepResult> {
+  const action = getStepAction(step);
+  let elements = await safeSnapshot(bridge);
+
+  // Execute the action
+  if (step.press) {
+    const target = resolvePress(step.press, elements);
+    if (target) {
+      await bridge.press(target.ref);
+      await delay(1500); // wait for transition
+      elements = await safeSnapshot(bridge);
+    } else {
+      return {
+        index: 0, // filled by caller
+        name: step.name,
+        action,
+        status: 'fail',
+        timestamp: 0,
+        duration: 0,
+        elementCount: elements.length,
+        error: `Could not resolve press target: ${JSON.stringify(step.press)}`,
+      };
+    }
+  } else if (step.scroll) {
+    await bridge.scroll(step.scroll);
+    await delay(1000);
+    elements = await safeSnapshot(bridge);
+  } else if (step.fill) {
+    const target = resolveFill(step.fill, elements);
+    if (target) {
+      await bridge.fill(target.ref, step.fill.value);
+      await delay(500);
+      elements = await safeSnapshot(bridge);
+    } else {
+      return {
+        index: 0, // filled by caller
+        name: step.name,
+        action,
+        status: 'fail',
+        timestamp: 0,
+        duration: 0,
+        elementCount: elements.length,
+        error: `Could not resolve fill target: ${JSON.stringify(step.fill)}`,
+      };
+    }
+  } else if (step.back) {
+    await bridge.back();
+    await delay(1500);
+    elements = await safeSnapshot(bridge);
+  }
+
+  // Take screenshot
+  let screenshotPath: string | undefined;
+  if (step.screenshot) {
+    const filename = `step-${stepNum}-${step.screenshot}.png`;
+    const fullPath = join(outputDir, filename);
+    if (captureScreenshot(fullPath)) {
+      screenshotPath = filename;
+    }
+  }
+
+  // Check assertions
+  let status: 'pass' | 'fail' = 'pass';
+  let assertion: StepResult['assertion'];
+
+  if (step.assert) {
+    assertion = {};
+    if (step.assert.interactive_count) {
+      const actual = elements.length;
+      const min = step.assert.interactive_count.min;
+      assertion.interactive_count = { min, actual };
+      if (actual < min) status = 'fail';
+    }
+    if (step.assert.bottom_nav_tabs) {
+      const navTabs = elements.filter(e =>
+        e.flutterType === 'InkWell' && e.bounds && e.bounds.y > 780
+      );
+      const actual = navTabs.length;
+      const min = step.assert.bottom_nav_tabs.min;
+      assertion.bottom_nav_tabs = { min, actual };
+      if (actual < min) status = 'fail';
+    }
+    if (step.assert.has_type) {
+      const searchType = step.assert.has_type.type.toLowerCase();
+      const matching = elements.filter(e =>
+        e.type === searchType || e.flutterType?.toLowerCase().includes(searchType)
+      );
+      const actual = matching.length;
+      const min = step.assert.has_type.min ?? 1;
+      assertion.has_type = { type: step.assert.has_type.type, min, actual };
+      if (actual < min) status = 'fail';
+    }
+    if (step.assert.text_visible || step.assert.text_not_visible) {
+      // Fetch all visible text from UIAutomator accessibility layer
+      const screenTexts = bridge.text();
+
+      if (step.assert.text_visible) {
+        const missing: string[] = [];
+        const found: string[] = [];
+        for (const query of step.assert.text_visible) {
+          const lowerQuery = query.toLowerCase();
+          const match = screenTexts.find(t => t.toLowerCase().includes(lowerQuery));
+          if (match) {
+            found.push(query);
+          } else {
+            missing.push(query);
+            status = 'fail';
+          }
+        }
+        assertion.text_visible = { expected: step.assert.text_visible, found, missing };
+      }
+
+      if (step.assert.text_not_visible) {
+        const unexpected: string[] = [];
+        const absent: string[] = [];
+        for (const query of step.assert.text_not_visible) {
+          const lowerQuery = query.toLowerCase();
+          const match = screenTexts.find(t => t.toLowerCase().includes(lowerQuery));
+          if (match) {
+            unexpected.push(query);
+            status = 'fail';
+          } else {
+            absent.push(query);
+          }
+        }
+        assertion.text_not_visible = { expected_absent: step.assert.text_not_visible, absent, unexpected };
+      }
+    }
+  }
+
+  return {
+    index: 0, // filled by caller
+    name: step.name,
+    action,
+    status,
+    timestamp: 0, // filled by caller
+    duration: 0,  // filled by caller
+    elementCount: elements.length,
+    screenshot: screenshotPath,
+    assertion,
+  };
+}
+
+/** Resolve a press target from the snapshot */
+export function resolvePress(
+  press: NonNullable<FlowStep['press']>,
+  elements: SnapshotElement[],
+): SnapshotElement | null {
+  if (press.ref) {
+    return elements.find(e => e.ref === press.ref) ?? null;
+  }
+
+  if (press.bottom_nav_tab !== undefined) {
+    const navItems = elements
+      .filter(e => e.flutterType === 'InkWell' && e.bounds && e.bounds.y > 780)
+      .sort((a, b) => (a.bounds?.x ?? 0) - (b.bounds?.x ?? 0));
+    return navItems[press.bottom_nav_tab] ?? null;
+  }
+
+  if (press.type) {
+    const typeMatches = elements.filter(e =>
+      e.type === press.type || e.flutterType?.toLowerCase().includes(press.type!.toLowerCase())
+    );
+
+    if (press.position === 'rightmost') {
+      return typeMatches.sort((a, b) => (b.bounds?.x ?? 0) - (a.bounds?.x ?? 0))[0] ?? null;
+    }
+    if (press.position === 'leftmost') {
+      return typeMatches.sort((a, b) => (a.bounds?.x ?? 0) - (b.bounds?.x ?? 0))[0] ?? null;
+    }
+
+    return typeMatches[0] ?? null;
+  }
+
+  return null;
+}
+
+/** Resolve a fill target from the snapshot */
+export function resolveFill(
+  fill: NonNullable<FlowStep['fill']>,
+  elements: SnapshotElement[],
+): SnapshotElement | null {
+  if (fill.type) {
+    return elements.find(e =>
+      e.type === fill.type || e.type === 'textfield' || e.flutterType === 'TextField'
+    ) ?? null;
+  }
+  return elements.find(e => e.type === 'textfield' || e.flutterType === 'TextField') ?? null;
+}
+
+export function getStepAction(step: FlowStep): string {
+  if (step.press) return 'press';
+  if (step.scroll) return 'scroll';
+  if (step.fill) return 'fill';
+  if (step.back) return 'back';
+  if (step.assert) return 'assert';
+  if (step.screenshot) return 'screenshot';
+  return 'unknown';
+}
+
+/** Dry-run: parse flow and resolve step targets without executing */
+export async function dryRunFlow(flow: Flow, agentFlutterPath: string = 'agent-flutter'): Promise<{
+  flow: string;
+  steps: { index: number; name: string; action: string; target: unknown; resolved: boolean; reason?: string }[];
+  dryRun: true;
+}> {
+  const bridge = new AgentBridge(agentFlutterPath);
+  let elements: SnapshotElement[] = [];
+  try {
+    elements = await safeSnapshot(bridge);
+  } catch { /* no device = empty snapshot */ }
+
+  const hasDevice = elements.length > 0;
+
+  const steps = flow.steps.map((step, i) => {
+    const action = getStepAction(step);
+    let target: unknown = null;
+    let resolved = true;
+    let reason: string | undefined;
+
+    if (step.press) {
+      const el = resolvePress(step.press, elements);
+      target = el ? { ref: el.ref, type: el.type, text: el.text } : step.press;
+      resolved = el !== null;
+      if (!resolved) reason = hasDevice ? 'element not found in current snapshot' : 'no device connected for snapshot';
+    } else if (step.fill) {
+      const el = resolveFill(step.fill, elements);
+      target = el ? { ref: el.ref, type: el.type } : step.fill;
+      resolved = el !== null;
+      if (!resolved) reason = hasDevice ? 'textfield not found in current snapshot' : 'no device connected for snapshot';
+    } else if (step.scroll) {
+      target = { direction: step.scroll };
+    } else if (step.back) {
+      target = { back: true };
+    } else if (step.assert) {
+      target = step.assert;
+      // Assertions always "resolve" — they check conditions at runtime
+    }
+
+    return { index: i, name: step.name, action, target, resolved, ...(reason ? { reason } : {}) };
+  });
+
+  return { flow: flow.name, steps, dryRun: true };
+}
+
+async function safeSnapshot(bridge: AgentBridge): Promise<SnapshotElement[]> {
+  try {
+    const snapshot = await bridge.snapshot();
+    return snapshot.elements;
+  } catch {
+    return [];
+  }
+}
+
+function delay(ms: number): Promise<void> {
+  return new Promise(resolve => setTimeout(resolve, ms));
+}

package/src/safety.ts

@@ -0,0 +1,74 @@
+import type { SnapshotElement } from './types.ts';
+
+const DEFAULT_BLOCKLIST = [
+  'delete', 'sign out', 'remove', 'reset', 'unpair', 'logout', 'clear all',
+  'delete account', 'factory reset', 'erase', 'uninstall',
+];
+
+/**
+ * Check if an element is safe to press.
+ * Returns { safe: true } or { safe: false, reason: string }.
+ */
+export function isSafe(
+  element: SnapshotElement,
+  nearbyElements: SnapshotElement[],
+  blocklist: string[] = DEFAULT_BLOCKLIST,
+): { safe: boolean; reason?: string } {
+  // Skip disabled elements
+  if (element.enabled === false) {
+    return { safe: false, reason: 'element is disabled' };
+  }
+
+  // Check element's own text against blocklist
+  const elementText = element.text.toLowerCase();
+  for (const keyword of blocklist) {
+    if (elementText.includes(keyword.toLowerCase())) {
+      return { safe: false, reason: `text matches blocklist: "${keyword}"` };
+    }
+  }
+
+  // Check nearby elements' text for context clues
+  // "nearby" = elements within a small vertical range
+  if (element.bounds) {
+    const nearbyTexts = nearbyElements
+      .filter(el => {
+        if (!el.bounds || el.ref === element.ref) return false;
+        const verticalDist = Math.abs(el.bounds.y - element.bounds!.y);
+        return verticalDist < 60; // within 60px vertically
+      })
+      .map(el => el.text.toLowerCase());
+
+    for (const text of nearbyTexts) {
+      for (const keyword of blocklist) {
+        if (text.includes(keyword.toLowerCase())) {
+          return { safe: false, reason: `nearby text matches blocklist: "${keyword}"` };
+        }
+      }
+    }
+  }
+
+  return { safe: true };
+}
+
+/**
+ * Filter a list of elements to only safe-to-press ones.
+ * Returns [safeElements, skippedElements].
+ */
+export function filterSafe(
+  elements: SnapshotElement[],
+  blocklist: string[] = DEFAULT_BLOCKLIST,
+): [SnapshotElement[], Array<{ element: SnapshotElement; reason: string }>] {
+  const safe: SnapshotElement[] = [];
+  const skipped: Array<{ element: SnapshotElement; reason: string }> = [];
+
+  for (const el of elements) {
+    const result = isSafe(el, elements, blocklist);
+    if (result.safe) {
+      safe.push(el);
+    } else {
+      skipped.push({ element: el, reason: result.reason! });
+    }
+  }
+
+  return [safe, skipped];
+}

package/src/types.ts

@@ -0,0 +1,82 @@
+// Shared types for flow-walker
+
+/** An interactive element from agent-flutter snapshot */
+export interface SnapshotElement {
+  ref: string;          // e.g. "@e1"
+  type: string;         // e.g. "button", "textfield", "gesture"
+  text: string;         // label/text content
+  flutterType?: string; // e.g. "ElevatedButton", "InkWell"
+  enabled?: boolean;
+  bounds?: { x: number; y: number; width: number; height: number };
+}
+
+/** A snapshot of a screen's interactive elements */
+export interface ScreenSnapshot {
+  elements: SnapshotElement[];
+  raw?: string; // raw agent-flutter output
+}
+
+/** A node in the navigation graph */
+export interface ScreenNode {
+  id: string;           // fingerprint hash
+  name: string;         // human-readable name derived from elements
+  elementTypes: string[]; // sorted type list used for fingerprint
+  elementCount: number;
+  firstSeen: number;    // timestamp
+  visits: number;
+}
+
+/** An edge in the navigation graph */
+export interface ScreenEdge {
+  source: string;       // source screen fingerprint
+  target: string;       // target screen fingerprint
+  element: {
+    ref: string;
+    type: string;
+    text: string;
+  };
+}
+
+/** A step in a YAML flow */
+export interface FlowStep {
+  name: string;
+  press?: { type?: string; position?: string; hint?: string; bottom_nav_tab?: number; ref?: string };
+  scroll?: string;
+  fill?: { type?: string; value: string };
+  back?: boolean;
+  assert?: {
+    interactive_count?: { min: number; verified?: string };
+    bottom_nav_tabs?: { min: number };
+    has_type?: { type: string; min?: number };
+    text?: string;
+    text_visible?: string[];
+    text_not_visible?: string[];
+  };
+  screenshot?: string;
+  note?: string;
+}
+
+/** A complete YAML flow */
+export interface Flow {
+  name: string;
+  description: string;
+  app?: string;
+  appUrl?: string;
+  covers?: string[];
+  prerequisites?: string[];
+  setup: string;
+  steps: FlowStep[];
+}
+
+/** Walker configuration */
+export interface WalkerConfig {
+  appUri?: string;
+  bundleId?: string;
+  maxDepth: number;
+  outputDir: string;
+  blocklist: string[];
+  json: boolean;
+  dryRun: boolean;
+  agentFlutterPath: string;
+  skipConnect: boolean;
+}

package/src/validate.ts

@@ -0,0 +1,115 @@
+// Input validation for flow-walker
+// "Agents hallucinate. Build like it." — validate all inputs before dispatch.
+
+import { existsSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { FlowWalkerError, ErrorCodes } from './errors.ts';
+
+/** Reject strings containing ASCII control characters (except \n and \t) */
+export function rejectControlChars(str: string, fieldName: string): void {
+  if (/[\x00-\x08\x0b\x0c\x0e-\x1f]/.test(str)) {
+    throw new FlowWalkerError(
+      ErrorCodes.INVALID_INPUT,
+      `${fieldName} contains invalid control characters`,
+      `Remove ASCII control characters (\\n and \\t are allowed)`,
+    );
+  }
+}
+
+/** Reject path traversal attempts */
+function rejectPathTraversal(path: string, fieldName: string): void {
+  const normalized = resolve(path);
+  if (path.includes('..')) {
+    throw new FlowWalkerError(
+      ErrorCodes.INVALID_INPUT,
+      `${fieldName} contains path traversal (..)`,
+      `Use an absolute path or a path relative to cwd without ..`,
+    );
+  }
+}
+
+/** Validate a YAML flow file path */
+export function validateFlowPath(path: string): void {
+  rejectControlChars(path, 'Flow path');
+  rejectPathTraversal(path, 'Flow path');
+
+  if (!path.endsWith('.yaml') && !path.endsWith('.yml')) {
+    throw new FlowWalkerError(
+      ErrorCodes.INVALID_INPUT,
+      `Flow path must end in .yaml or .yml: ${path}`,
+      `Provide a YAML flow file. Run: flow-walker schema run`,
+    );
+  }
+
+  if (!existsSync(path)) {
+    throw new FlowWalkerError(
+      ErrorCodes.FILE_NOT_FOUND,
+      `Flow file not found: ${path}`,
+      `Check the path and try again. Run: ls ${path}`,
+    );
+  }
+}
+
+/** Validate an output directory path */
+export function validateOutputDir(dir: string): void {
+  rejectControlChars(dir, 'Output directory');
+  rejectPathTraversal(dir, 'Output directory');
+}
+
+/** Validate a VM Service WebSocket URI */
+export function validateUri(uri: string): void {
+  rejectControlChars(uri, 'URI');
+
+  if (!uri.startsWith('ws://') && !uri.startsWith('wss://')) {
+    throw new FlowWalkerError(
+      ErrorCodes.INVALID_INPUT,
+      `URI must start with ws:// or wss://: ${uri}`,
+      `Example: ws://127.0.0.1:38047/abc=/ws`,
+    );
+  }
+
+  try {
+    new URL(uri);
+  } catch {
+    throw new FlowWalkerError(
+      ErrorCodes.INVALID_INPUT,
+      `Invalid URI format: ${uri}`,
+      `Provide a valid WebSocket URI. Example: ws://127.0.0.1:38047/abc=/ws`,
+    );
+  }
+}
+
+/** Validate a bundle ID (reverse-domain format) */
+export function validateBundleId(id: string): void {
+  rejectControlChars(id, 'Bundle ID');
+
+  if (!/^[a-zA-Z][a-zA-Z0-9._-]*(\.[a-zA-Z][a-zA-Z0-9._-]*)+$/.test(id)) {
+    throw new FlowWalkerError(
+      ErrorCodes.INVALID_INPUT,
+      `Invalid bundle ID format: ${id}`,
+      `Bundle ID must be reverse-domain format. Example: com.example.app`,
+    );
+  }
+}
+
+/** Validate a run directory exists and contains run.json */
+export function validateRunDir(dir: string): void {
+  rejectControlChars(dir, 'Run directory');
+  rejectPathTraversal(dir, 'Run directory');
+
+  if (!existsSync(dir)) {
+    throw new FlowWalkerError(
+      ErrorCodes.FILE_NOT_FOUND,
+      `Run directory not found: ${dir}`,
+      `Provide the output directory from a previous flow-walker run`,
+    );
+  }
+
+  if (!existsSync(`${dir}/run.json`)) {
+    throw new FlowWalkerError(
+      ErrorCodes.FILE_NOT_FOUND,
+      `run.json not found in ${dir}`,
+      `Run a flow first: flow-walker run <flow.yaml> --output-dir ${dir}`,
+    );
+  }
+}