flow-walker-cli 0.2.0

package/src/agent-bridge.ts

@@ -0,0 +1,189 @@
+import { execFileSync, execSync } from 'node:child_process';
+import type { SnapshotElement, ScreenSnapshot } from './types.ts';
+import { FlowWalkerError, ErrorCodes } from './errors.ts';
+
+/** Package name for the app under test — used to bring app to foreground */
+const DEFAULT_PACKAGE = 'com.friend.ios.dev';
+
+/**
+ * Thin wrapper around the agent-flutter CLI.
+ * All device interaction goes through this bridge.
+ */
+export class AgentBridge {
+  private bin: string;
+  private timeout: number;
+  private lastUri?: string;
+  private lastBundleId?: string;
+
+  constructor(agentFlutterPath: string = 'agent-flutter', timeout: number = 30000) {
+    this.bin = agentFlutterPath;
+    this.timeout = timeout;
+  }
+
+  /** Connect to a Flutter app by VM Service URI */
+  connect(uri: string): void {
+    this.lastUri = uri;
+    this.exec(['connect', uri]);
+  }
+
+  /** Connect to a Flutter app by bundle ID */
+  connectBundle(bundleId: string): void {
+    this.lastBundleId = bundleId;
+    this.exec(['connect', '--bundle-id', bundleId]);
+  }
+
+  /** Store URI for reconnection without connecting (for skip-connect mode) */
+  setUri(uri: string): void {
+    this.lastUri = uri;
+  }
+
+  /** Reconnect using the last connection parameters */
+  reconnect(): boolean {
+    try {
+      try { this.exec(['disconnect']); } catch { /* ignore */ }
+      if (this.lastUri) {
+        this.exec(['connect', this.lastUri]);
+      } else if (this.lastBundleId) {
+        this.exec(['connect', '--bundle-id', this.lastBundleId]);
+      } else {
+        return false;
+      }
+      return true;
+    } catch {
+      return false;
+    }
+  }
+
+  /** Disconnect from the current app */
+  disconnect(): void {
+    this.exec(['disconnect']);
+  }
+
+  /** Take a snapshot of interactive elements, with auto-reconnect on failure */
+  snapshot(): ScreenSnapshot {
+    let raw: string;
+    try {
+      raw = this.exec(['snapshot', '-i', '--json']);
+    } catch {
+      // Try reconnecting once
+      if (!this.reconnect()) throw new FlowWalkerError(ErrorCodes.DEVICE_ERROR, 'Snapshot failed and reconnect failed', 'Check device connection: adb devices');
+      raw = this.exec(['snapshot', '-i', '--json']);
+    }
+    const parsed = JSON.parse(raw);
+
+    // agent-flutter returns { elements: [...] } or an array directly
+    const rawElements = Array.isArray(parsed) ? parsed : (parsed.elements || []);
+
+    const elements: SnapshotElement[] = rawElements.map((el: Record<string, unknown>) => ({
+      ref: String(el.ref || ''),
+      type: String(el.type || ''),
+      text: String(el.text || el.label || ''),
+      flutterType: el.flutterType ? String(el.flutterType) : undefined,
+      enabled: el.enabled !== false,
+      bounds: el.bounds as SnapshotElement['bounds'],
+    }));
+
+    return { elements, raw };
+  }
+
+  /** Press an element by ref */
+  press(ref: string): string {
+    return this.exec(['press', ref, '--json']);
+  }
+
+  /** Scroll in a direction */
+  scroll(direction: string): string {
+    return this.exec(['scroll', direction]);
+  }
+
+  /** Fill text into an element by ref */
+  fill(ref: string, text: string): string {
+    return this.exec(['fill', ref, text]);
+  }
+
+  /** Navigate back */
+  back(): string {
+    return this.exec(['back', '--json']);
+  }
+
+  /** Get all visible text from UIAutomator accessibility layer */
+  text(): string[] {
+    try {
+      const raw = this.exec(['text', '--json']);
+      const parsed = JSON.parse(raw);
+      return Array.isArray(parsed) ? parsed : [];
+    } catch {
+      return [];
+    }
+  }
+
+  /** Check if specific text is visible on screen */
+  textVisible(query: string): boolean {
+    try {
+      this.exec(['text', query]);
+      return true;
+    } catch {
+      return false;
+    }
+  }
+
+  /** Get connection status */
+  status(): string {
+    return this.exec(['status', '--json']);
+  }
+
+  /** Bring app to foreground via ADB am start */
+  bringToForeground(packageName: string = DEFAULT_PACKAGE): boolean {
+    try {
+      const adbArgs = this.adbDeviceArgs();
+      execFileSync('adb', [
+        ...adbArgs, 'shell', 'am', 'start', '-n',
+        `${packageName}/${packageName.replace('.dev', '')}.MainActivity`,
+      ], { encoding: 'utf8', timeout: 5000 });
+      return true;
+    } catch {
+      return false;
+    }
+  }
+
+  /** Check if the current foreground app matches our package */
+  isAppInForeground(packageName: string = DEFAULT_PACKAGE): boolean {
+    try {
+      const adbArgs = this.adbDeviceArgs().join(' ');
+      const result = execSync(
+        `adb ${adbArgs} shell "dumpsys window displays | grep mCurrentFocus"`,
+        { encoding: 'utf8', timeout: 5000 },
+      );
+      // mCurrentFocus=null means window transition — treat as in foreground
+      if (result.includes('null')) return true;
+      return result.includes(packageName);
+    } catch {
+      // If the grep/dumpsys fails, assume in foreground to avoid false negatives
+      return true;
+    }
+  }
+
+  /** Get ADB device args from AGENT_FLUTTER_DEVICE env var */
+  private adbDeviceArgs(): string[] {
+    const device = process.env.AGENT_FLUTTER_DEVICE;
+    return device ? ['-s', device] : [];
+  }
+
+  private exec(args: string[]): string {
+    try {
+      const result = execFileSync(this.bin, args, {
+        encoding: 'utf8',
+        timeout: this.timeout,
+        env: { ...process.env, AGENT_FLUTTER_JSON: '1' },
+      });
+      return result.trim();
+    } catch (err: unknown) {
+      const error = err as { stderr?: string; message?: string };
+      throw new FlowWalkerError(
+        ErrorCodes.COMMAND_FAILED,
+        `agent-flutter ${args[0]} failed: ${error.stderr || error.message}`,
+        `Run: agent-flutter doctor`,
+      );
+    }
+  }
+}

package/src/capture.ts

@@ -0,0 +1,102 @@
+// Screenshot, video, and logcat capture helpers
+
+import { execSync, spawn, type ChildProcess, type StdioOptions } from 'node:child_process';
+import { existsSync, mkdirSync } from 'node:fs';
+
+const PIPE_STDIO: StdioOptions = ['pipe', 'pipe', 'pipe'];
+
+function adbArgs(): string[] {
+  const addr = process.env.ANDROID_ADB_SERVER_ADDRESS;
+  const port = process.env.ANDROID_ADB_SERVER_PORT;
+  const device = process.env.AGENT_FLUTTER_DEVICE;
+  const args: string[] = [];
+  if (addr) args.push('-H', addr);
+  if (port) args.push('-P', port);
+  if (device) args.push('-s', device);
+  return args;
+}
+
+function adb(shellArgs: string[], timeout = 10000): string {
+  const args = [...adbArgs(), ...shellArgs];
+  return execSync(`adb ${args.join(' ')}`, {
+    encoding: 'utf-8',
+    timeout,
+    stdio: PIPE_STDIO,
+  }).trim();
+}
+
+/** Take a screenshot via ADB and pull to local path */
+export function screenshot(localPath: string): boolean {
+  try {
+    const devicePath = '/sdcard/fw-screenshot.png';
+    adb(['shell', 'screencap', '-p', devicePath]);
+    adb(['pull', devicePath, localPath]);
+    adb(['shell', 'rm', devicePath]);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/** Start ADB screen recording. Returns handle to stop it later. */
+export function startRecording(devicePath: string = '/sdcard/fw-recording.mp4'): {
+  process: ChildProcess;
+  devicePath: string;
+} {
+  const args = [...adbArgs(), 'shell', 'screenrecord', '--time-limit', '180', devicePath];
+  const proc = spawn('adb', args, { stdio: 'ignore', detached: true });
+  return { process: proc, devicePath };
+}
+
+/** Stop recording and pull video to local path */
+export function stopRecording(
+  handle: { process: ChildProcess; devicePath: string },
+  localPath: string,
+): boolean {
+  try {
+    // Send SIGINT to stop recording
+    handle.process.kill('SIGINT');
+    // Wait a moment for file to finalize
+    execSync('sleep 2', { stdio: 'ignore' });
+    adb(['pull', handle.devicePath, localPath], 30000);
+    adb(['shell', 'rm', handle.devicePath]);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/** Start logcat capture. Returns handle to stop it later. */
+export function startLogcat(): { process: ChildProcess; lines: string[] } {
+  const args = [...adbArgs(), 'logcat', '-v', 'time', '-s', 'flutter'];
+  // Clear first
+  try { adb(['logcat', '-c']); } catch { /* ignore */ }
+  const proc = spawn('adb', args, { stdio: ['ignore', 'pipe', 'ignore'] });
+  const lines: string[] = [];
+  proc.stdout?.on('data', (data: Buffer) => {
+    lines.push(...data.toString().split('\n').filter(Boolean));
+  });
+  return { process: proc, lines };
+}
+
+/** Stop logcat capture and return collected lines */
+export function stopLogcat(handle: { process: ChildProcess; lines: string[] }): string[] {
+  handle.process.kill('SIGTERM');
+  return handle.lines;
+}
+
+/** Get device model name */
+export function getDeviceName(): string {
+  try {
+    return adb(['shell', 'getprop', 'ro.product.model']);
+  } catch {
+    return process.env.AGENT_FLUTTER_DEVICE ?? 'unknown';
+  }
+}
+
+/** Ensure output directory exists */
+export function ensureDir(dir: string): void {
+  if (!existsSync(dir)) {
+    mkdirSync(dir, { recursive: true });
+  }
+}

package/src/cli.ts

@@ -0,0 +1,352 @@
+#!/usr/bin/env node --experimental-strip-types
+import { parseArgs } from 'node:util';
+import { readFileSync } from 'node:fs';
+import type { WalkerConfig } from './types.ts';
+import { walk } from './walker.ts';
+import { parseFlowFile } from './flow-parser.ts';
+import { runFlow, dryRunFlow, type RunOptions } from './runner.ts';
+import { generateReport, type ReportOptions } from './reporter.ts';
+import { validateRunResult, type RunResult } from './run-schema.ts';
+import { FlowWalkerError, ErrorCodes, formatError } from './errors.ts';
+import { validateFlowPath, validateOutputDir, validateUri, validateBundleId, validateRunDir } from './validate.ts';
+import { COMMAND_SCHEMAS, SCHEMA_VERSION, getCommandSchema, getSchemaEnvelope } from './command-schema.ts';
+import { pushReport, getRunData } from './push.ts';
+
+const DEFAULT_BLOCKLIST = 'delete,sign out,remove,reset,unpair,logout,clear all';
+
+/** Resolve JSON output mode: --no-json > --json > env > TTY detection */
+function resolveJsonMode(flags: Record<string, unknown>): boolean {
+  if (flags['no-json']) return false;
+  if (flags['json']) return true;
+  if (process.env.FLOW_WALKER_JSON === '1') return true;
+  if (!process.stdout.isTTY) return true;
+  return false;
+}
+
+function printUsage(): void {
+  console.log(`flow-walker — Auto-discover app flows, execute YAML test flows, generate HTML reports
+
+Usage:
+  flow-walker walk [options]        Auto-explore app and generate YAML flows
+  flow-walker run <flow.yaml>       Execute a YAML flow and produce run.json
+  flow-walker report <run-dir>      Generate HTML report from run results
+  flow-walker push <run-dir>        Upload report and return shareable URL
+  flow-walker get <run-id>          Fetch run data from hosted service
+  flow-walker schema [command]      Show command schema for agent discovery
+
+Run: flow-walker schema for machine-readable command descriptions.
+`);
+}
+
+async function main(): Promise<void> {
+  const { values, positionals } = parseArgs({
+    allowPositionals: true,
+    options: {
+      'app-uri': { type: 'string' },
+      'bundle-id': { type: 'string' },
+      'max-depth': { type: 'string', default: '5' },
+      'output-dir': { type: 'string' },
+      'output': { type: 'string' },
+      'blocklist': { type: 'string', default: DEFAULT_BLOCKLIST },
+      'agent-flutter-path': { type: 'string' },
+      'json': { type: 'boolean', default: false },
+      'no-json': { type: 'boolean', default: false },
+      'dry-run': { type: 'boolean', default: false },
+      'skip-connect': { type: 'boolean', default: false },
+      'no-video': { type: 'boolean', default: false },
+      'no-logs': { type: 'boolean', default: false },
+      'help': { type: 'boolean', default: false },
+      'version': { type: 'boolean', default: false },
+    },
+  });
+
+  const subcommand = positionals[0];
+  const json = resolveJsonMode(values);
+
+  // Env var overrides
+  const agentPath = (values['agent-flutter-path'] as string | undefined)
+    ?? process.env.FLOW_WALKER_AGENT_PATH
+    ?? 'agent-flutter';
+  const dryRun = (values['dry-run'] as boolean) || process.env.FLOW_WALKER_DRY_RUN === '1';
+
+  if (values.version) {
+    if (json) {
+      console.log(JSON.stringify({ version: SCHEMA_VERSION }));
+    } else {
+      console.log(`flow-walker ${SCHEMA_VERSION}`);
+    }
+    process.exit(0);
+  }
+
+  if (values.help || !subcommand) {
+    if (json && subcommand) {
+      // --help --json → schema for that command
+      const schema = getCommandSchema(subcommand);
+      if (schema) {
+        console.log(JSON.stringify(schema));
+        process.exit(0);
+      }
+    }
+    printUsage();
+    process.exit(subcommand ? 0 : 1);
+  }
+
+  try {
+    if (subcommand === 'walk') {
+      await handleWalk(values, positionals, json, agentPath, dryRun);
+    } else if (subcommand === 'run') {
+      await handleRun(values, positionals, json, agentPath, dryRun);
+    } else if (subcommand === 'report') {
+      await handleReport(values, positionals, json);
+    } else if (subcommand === 'push') {
+      await handlePush(values, positionals, json);
+    } else if (subcommand === 'get') {
+      await handleGet(values, positionals, json);
+    } else if (subcommand === 'schema') {
+      handleSchema(positionals);
+    } else {
+      throw new FlowWalkerError(
+        ErrorCodes.INVALID_ARGS,
+        `Unknown subcommand: ${subcommand}`,
+        'Available: walk, run, report, push, get, schema. Run: flow-walker schema',
+      );
+    }
+  } catch (err) {
+    console.error(formatError(err, json));
+    process.exit(2);
+  }
+}
+
+async function handleWalk(
+  values: Record<string, unknown>,
+  _positionals: string[],
+  json: boolean,
+  agentPath: string,
+  dryRun: boolean,
+): Promise<void> {
+  // Validate inputs
+  if (values['app-uri']) validateUri(values['app-uri'] as string);
+  if (values['bundle-id']) validateBundleId(values['bundle-id'] as string);
+
+  if (!values['app-uri'] && !values['bundle-id'] && !values['skip-connect']) {
+    throw new FlowWalkerError(
+      ErrorCodes.INVALID_ARGS,
+      'Either --app-uri, --bundle-id, or --skip-connect is required',
+      'Run: flow-walker schema walk',
+    );
+  }
+
+  const outputDir = (values['output-dir'] as string | undefined)
+    ?? process.env.FLOW_WALKER_OUTPUT_DIR
+    ?? './flows/';
+  validateOutputDir(outputDir);
+
+  const config: WalkerConfig = {
+    appUri: values['app-uri'] as string | undefined,
+    bundleId: values['bundle-id'] as string | undefined,
+    maxDepth: parseInt(values['max-depth'] as string, 10),
+    outputDir,
+    blocklist: (values['blocklist'] as string).split(',').map(s => s.trim()),
+    json,
+    dryRun,
+    agentFlutterPath: agentPath,
+    skipConnect: values['skip-connect'] as boolean,
+  };
+
+  const result = await walk(config);
+
+  if (json) {
+    console.log(JSON.stringify({ type: 'result', ...result }));
+  } else {
+    console.log(`\nDone. ${result.screensFound} screens, ${result.flowsGenerated} flows, ${result.elementsSkipped} skipped.`);
+  }
+
+  process.exit(0);
+}
+
+async function handleRun(
+  values: Record<string, unknown>,
+  positionals: string[],
+  json: boolean,
+  agentPath: string,
+  dryRun: boolean,
+): Promise<void> {
+  const flowPath = positionals[1];
+  if (!flowPath) {
+    throw new FlowWalkerError(
+      ErrorCodes.INVALID_ARGS,
+      'Flow YAML path is required',
+      'Usage: flow-walker run <flow.yaml>. Run: flow-walker schema run',
+    );
+  }
+
+  validateFlowPath(flowPath);
+
+  const outputDir = (values['output-dir'] as string | undefined)
+    ?? process.env.FLOW_WALKER_OUTPUT_DIR
+    ?? './run-output/';
+  validateOutputDir(outputDir);
+
+  const flow = parseFlowFile(flowPath);
+
+  // Dry-run mode: parse and resolve without executing
+  if (dryRun) {
+    const dryResult = await dryRunFlow(flow, agentPath);
+    console.log(JSON.stringify(dryResult, null, json ? undefined : 2));
+    process.exit(0);
+  }
+
+  const options: RunOptions = {
+    outputDir,
+    noVideo: values['no-video'] as boolean,
+    noLogs: values['no-logs'] as boolean,
+    json,
+    agentFlutterPath: agentPath,
+  };
+
+  if (!json) {
+    console.log(`Running flow: ${flow.name} (${flow.steps.length} steps)`);
+  }
+
+  const result = await runFlow(flow, options);
+
+  if (json) {
+    console.log(JSON.stringify(result));
+  } else {
+    const icon = result.result === 'pass' ? '✓' : '✗';
+    console.log(`\n${icon} Flow "${result.flow}" ${result.result.toUpperCase()} (${(result.duration / 1000).toFixed(1)}s)`);
+    console.log(`  Run ID: ${result.id}`);
+    console.log(`  Output: ${outputDir}/${result.id}/`);
+  }
+
+  process.exit(result.result === 'pass' ? 0 : 1);
+}
+
+async function handleReport(
+  values: Record<string, unknown>,
+  positionals: string[],
+  json: boolean,
+): Promise<void> {
+  const runDir = positionals[1];
+  if (!runDir) {
+    throw new FlowWalkerError(
+      ErrorCodes.INVALID_ARGS,
+      'Run directory is required',
+      'Usage: flow-walker report <run-dir>. Run: flow-walker schema report',
+    );
+  }
+
+  validateRunDir(runDir);
+
+  const raw = readFileSync(`${runDir}/run.json`, 'utf-8');
+  const data = JSON.parse(raw);
+  if (!validateRunResult(data)) {
+    throw new FlowWalkerError(
+      ErrorCodes.FLOW_PARSE_ERROR,
+      'Invalid run.json format',
+      'Ensure run.json was produced by flow-walker run',
+    );
+  }
+  const runResult: RunResult = data;
+
+  const reportOptions: ReportOptions = {
+    noVideo: values['no-video'] as boolean,
+    output: values['output'] as string | undefined,
+  };
+
+  const outputPath = generateReport(runResult, runDir, reportOptions);
+
+  if (json) {
+    console.log(JSON.stringify({ report: outputPath }));
+  } else {
+    console.log(`Report generated: ${outputPath}`);
+  }
+
+  process.exit(0);
+}
+
+async function handlePush(
+  _values: Record<string, unknown>,
+  positionals: string[],
+  json: boolean,
+): Promise<void> {
+  const runDir = positionals[1];
+  if (!runDir) {
+    throw new FlowWalkerError(
+      ErrorCodes.INVALID_ARGS,
+      'Run directory is required',
+      'Usage: flow-walker push <run-dir>. Run: flow-walker schema push',
+    );
+  }
+
+  validateRunDir(runDir);
+
+  const apiUrl = process.env.FLOW_WALKER_API_URL;
+  const result = await pushReport(runDir, { apiUrl });
+
+  if (json) {
+    console.log(JSON.stringify(result));
+  } else {
+    console.log(`\nReport uploaded successfully.`);
+    console.log(`  JSON: ${result.url}`);
+    console.log(`  HTML: ${result.htmlUrl}`);
+    console.log(`  ID:   ${result.id}`);
+    console.log(`  Expires: ${result.expiresAt}`);
+  }
+
+  process.exit(0);
+}
+
+async function handleGet(
+  _values: Record<string, unknown>,
+  positionals: string[],
+  json: boolean,
+): Promise<void> {
+  const runId = positionals[1];
+  if (!runId) {
+    throw new FlowWalkerError(
+      ErrorCodes.INVALID_ARGS,
+      'Run ID is required',
+      'Usage: flow-walker get <run-id>. Run: flow-walker schema get',
+    );
+  }
+
+  if (!/^[A-Za-z0-9_-]{6,20}$/.test(runId)) {
+    throw new FlowWalkerError(
+      ErrorCodes.INVALID_INPUT,
+      'Invalid run ID format',
+      'Run IDs are 6-20 characters: letters, digits, hyphens, underscores',
+    );
+  }
+
+  const apiUrl = process.env.FLOW_WALKER_API_URL;
+  const data = await getRunData(runId, { apiUrl });
+
+  if (json) {
+    console.log(JSON.stringify(data));
+  } else {
+    console.log(JSON.stringify(data, null, 2));
+  }
+
+  process.exit(0);
+}
+
+function handleSchema(positionals: string[]): void {
+  const commandName = positionals[1];
+  if (commandName) {
+    const schema = getCommandSchema(commandName);
+    if (!schema) {
+      throw new FlowWalkerError(
+        ErrorCodes.INVALID_ARGS,
+        `Unknown command: ${commandName}`,
+        `Available: ${COMMAND_SCHEMAS.map(s => s.name).join(', ')}`,
+      );
+    }
+    console.log(JSON.stringify(schema, null, 2));
+  } else {
+    console.log(JSON.stringify(getSchemaEnvelope(), null, 2));
+  }
+  process.exit(0);
+}
+
+main();