@assistkick/create 1.19.0 → 1.22.0

package/templates/assistkick-product-system/packages/shared/tools/app_use_run.ts

@@ -0,0 +1,348 @@
+#!/usr/bin/env node
+
+/**
+ * app_use_run — Execute a YAML flow file against a target platform.
+ *
+ * Parses the flow, translates each step to agent-browser commands (for web),
+ * executes them sequentially, reports pass/fail per step with timing.
+ *
+ * Usage:
+ *   pnpm tsx packages/shared/tools/app_use_run.ts <flow.yaml> [--env KEY=VALUE] [--headed] [--platform web]
+ *   pnpm tsx packages/shared/tools/app_use_run.ts exec --type click --selector "@e1"
+ *   pnpm tsx packages/shared/tools/app_use_run.ts exec --type fill --selector "@e2" --value "hello"
+ *   pnpm tsx packages/shared/tools/app_use_run.ts exec --type snapshot --params '{"interactive":true}'
+ *   pnpm tsx packages/shared/tools/app_use_run.ts assert-ai <screenshot-path> --prompt "The login form is visible"
+ */
+
+import {program} from 'commander';
+import chalk from 'chalk';
+import {execSync, spawn} from 'node:child_process';
+import {
+  type FlowResult,
+  type FlowStep,
+  interpolate,
+  readFlowFile,
+  type StepResult,
+  stepToAgentBrowserArgs,
+  validateFlow,
+} from '../lib/app_use_flow.js';
+
+// ── Helpers ───────────────────────────────────────────────────────────────────
+
+function runAgentBrowser(args: string[], timeoutMs = 30_000): { stdout: string; exitCode: number } {
+  const cmd = `agent-browser ${args.map(a => a.includes(' ') ? `"${a}"` : a).join(' ')}`;
+  try {
+    const stdout = execSync(cmd, {
+      timeout: timeoutMs,
+      encoding: 'utf-8',
+      stdio: ['pipe', 'pipe', 'pipe'],
+    });
+    return { stdout: stdout.trim(), exitCode: 0 };
+  } catch (err: any) {
+    return {
+      stdout: err.stdout?.toString()?.trim() || '',
+      exitCode: err.status ?? 1,
+    };
+  }
+}
+
+function assertVisibleInSnapshot(snapshotOutput: string, text: string): boolean {
+  // Check if the text appears in the accessibility snapshot
+  return snapshotOutput.toLowerCase().includes(text.toLowerCase());
+}
+
+async function assertWithAI(screenshotPath: string, prompt: string): Promise<{ passes: boolean; details: string }> {
+  const systemPrompt = [
+    'You are a UI test assertion engine. You analyze screenshots to verify assertions.',
+    'Output ONLY valid JSON with these fields:',
+    '{"passes": boolean, "confidence": "high"|"medium"|"low", "details": "brief explanation"}',
+    'No other text, no code fences.',
+  ].join(' ');
+
+  const fullPrompt = `Look at the screenshot and determine: ${prompt}`;
+
+  return new Promise((resolve) => {
+    const args = [
+      '-p', fullPrompt,
+      '--system-prompt', systemPrompt,
+      '--model', 'claude-haiku-4-5',
+      '--output-format', 'text',
+      '--max-turns', '1',
+      '--dangerously-skip-permissions',
+      screenshotPath,
+    ];
+
+    const child = spawn('claude', args, {
+      stdio: ['ignore', 'pipe', 'pipe'],
+      env: { ...process.env },
+      timeout: 30_000,
+    });
+
+    let stdout = '';
+    child.stdout.on('data', (d: Buffer) => { stdout += d.toString(); });
+
+    child.on('close', (code) => {
+      if (code === 0 && stdout.trim()) {
+        try {
+          // Try parsing JSON directly
+          let jsonStr = stdout.trim();
+          const fenceMatch = jsonStr.match(/```(?:json)?\s*\n?([\s\S]*?)\n?```/);
+          if (fenceMatch) jsonStr = fenceMatch[1].trim();
+          const result = JSON.parse(jsonStr);
+          resolve({ passes: !!result.passes, details: result.details || '' });
+        } catch {
+          // If JSON parsing fails, check for positive keywords
+          const lower = stdout.toLowerCase();
+          const passes = lower.includes('"passes": true') || lower.includes('"passes":true');
+          resolve({ passes, details: stdout.trim() });
+        }
+      } else {
+        resolve({ passes: false, details: `AI assertion failed (exit code: ${code})` });
+      }
+    });
+
+    child.on('error', () => {
+      resolve({ passes: false, details: 'Failed to spawn Claude CLI for AI assertion' });
+    });
+  });
+}
+
+// ── Single step execution (for agent interactive use) ─────────────────────────
+
+async function execSingleStep(opts: any): Promise<void> {
+  const step: FlowStep = {
+    type: opts.type,
+    selector: opts.selector,
+    value: opts.value,
+    params: opts.params ? JSON.parse(opts.params) : undefined,
+  };
+
+  const args = stepToAgentBrowserArgs(step);
+  const { stdout, exitCode } = runAgentBrowser(args);
+
+  if (exitCode === 0) {
+    console.log(stdout);
+    console.log('\n' + JSON.stringify({ status: 'ok', step: step.type, output: stdout }));
+  } else {
+    console.error(chalk.red(`Step failed: ${step.type}`));
+    if (stdout) console.error(stdout);
+    console.log('\n' + JSON.stringify({ status: 'error', step: step.type, output: stdout }));
+    process.exit(1);
+  }
+}
+
+// ── Flow execution ────────────────────────────────────────────────────────────
+
+async function runFlow(flowPath: string, opts: any): Promise<void> {
+  const flow = readFlowFile(flowPath);
+
+  // Validate first
+  const issues = validateFlow(flow);
+  if (issues.length > 0) {
+    console.error(chalk.red('Flow validation failed:'));
+    for (const issue of issues) console.error(chalk.red(`  - ${issue}`));
+    process.exit(1);
+  }
+
+  // Merge env from CLI and flow config
+  const env: Record<string, string> = { ...flow.config.env };
+  if (opts.env) {
+    for (const e of Array.isArray(opts.env) ? opts.env : [opts.env]) {
+      const [k, ...rest] = e.split('=');
+      if (k) env[k] = rest.join('=');
+    }
+  }
+
+  const platform = opts.platform || flow.config.platform || 'web';
+  if (platform !== 'web') {
+    console.error(chalk.red(`Platform "${platform}" is not yet supported. Only "web" is available.`));
+    process.exit(1);
+  }
+
+  const flowName = flow.config.name || flowPath;
+  console.log(chalk.cyan.bold(`\nRunning flow: ${flowName}`));
+  console.log(`Platform: ${platform} | Steps: ${flow.steps.length}`);
+  if (opts.headed) console.log('Mode: headed');
+  console.log();
+
+  // Auto-session: open browser if configured
+  if (flow.config.autoSession && flow.config.appId) {
+    const headedArgs = opts.headed ? ['--headed'] : [];
+    const openArgs = ['open', interpolate(flow.config.appId, env), ...headedArgs];
+    console.log(chalk.gray(`  [setup] agent-browser ${openArgs.join(' ')}`));
+    runAgentBrowser(openArgs);
+  }
+
+  const results: StepResult[] = [];
+  const startTime = Date.now();
+  let aborted = false;
+
+  for (let i = 0; i < flow.steps.length; i++) {
+    if (aborted) {
+      results.push({
+        step: flow.steps[i], index: i, status: 'skipped', durationMs: 0,
+      });
+      continue;
+    }
+
+    const step = flow.steps[i];
+    const stepStart = Date.now();
+    const label = step.label || `${step.type}${step.value ? ` ${step.value}` : ''}${step.selector ? ` ${step.selector}` : ''}`;
+
+    try {
+      // Handle assertion steps specially
+      if (step.type === 'assertVisible' || step.type === 'assertNotVisible') {
+        const { stdout } = runAgentBrowser(['snapshot', '-i']);
+        const text = step.value || '';
+        const found = assertVisibleInSnapshot(stdout, text);
+        const shouldBeVisible = step.type === 'assertVisible';
+
+        if (found === shouldBeVisible) {
+          const ms = Date.now() - stepStart;
+          console.log(chalk.green(`  [${i + 1}/${flow.steps.length}] PASS  ${label} (${ms}ms)`));
+          results.push({ step, index: i, status: 'passed', durationMs: ms });
+        } else {
+          throw new Error(`Expected "${text}" to be ${shouldBeVisible ? 'visible' : 'not visible'}`);
+        }
+        continue;
+      }
+
+      if (step.type === 'assertUrl') {
+        const { stdout } = runAgentBrowser(['get', 'url']);
+        const expected = step.value ? interpolate(step.value, env) : '';
+        if (!stdout.includes(expected)) {
+          throw new Error(`URL assertion failed: expected "${expected}" in "${stdout}"`);
+        }
+        const ms = Date.now() - stepStart;
+        console.log(chalk.green(`  [${i + 1}/${flow.steps.length}] PASS  ${label} (${ms}ms)`));
+        results.push({ step, index: i, status: 'passed', durationMs: ms });
+        continue;
+      }
+
+      if (step.type === 'assertText') {
+        const sel = step.selector ? interpolate(step.selector, env) : '';
+        const { stdout } = runAgentBrowser(['get', 'text', sel]);
+        const expected = step.value ? interpolate(step.value, env) : '';
+        if (!stdout.includes(expected)) {
+          throw new Error(`Text assertion failed: expected "${expected}" in "${stdout}"`);
+        }
+        const ms = Date.now() - stepStart;
+        console.log(chalk.green(`  [${i + 1}/${flow.steps.length}] PASS  ${label} (${ms}ms)`));
+        results.push({ step, index: i, status: 'passed', durationMs: ms });
+        continue;
+      }
+
+      if (step.type === 'assertWithAI') {
+        const screenshotResult = runAgentBrowser(['screenshot']);
+        // Extract screenshot path from agent-browser output
+        const pathMatch = screenshotResult.stdout.match(/(?:saved to |Screenshot: ?)(.+\.png)/i);
+        const screenshotPath = pathMatch?.[1]?.trim();
+        if (!screenshotPath) {
+          throw new Error('Could not capture screenshot for AI assertion');
+        }
+        const aiResult = await assertWithAI(screenshotPath, step.value || '');
+        if (aiResult.passes) {
+          const ms = Date.now() - stepStart;
+          console.log(chalk.green(`  [${i + 1}/${flow.steps.length}] PASS  ${label} (${ms}ms) — ${aiResult.details}`));
+          results.push({ step, index: i, status: 'passed', durationMs: ms, output: aiResult.details });
+        } else {
+          throw new Error(`AI assertion failed: ${aiResult.details}`);
+        }
+        continue;
+      }
+
+      // Normal step: translate to agent-browser command and run
+      const args = stepToAgentBrowserArgs(step, env);
+      const { stdout, exitCode } = runAgentBrowser(args);
+
+      if (exitCode !== 0) {
+        throw new Error(stdout || `agent-browser exited with code ${exitCode}`);
+      }
+
+      const ms = Date.now() - stepStart;
+      console.log(chalk.green(`  [${i + 1}/${flow.steps.length}] PASS  ${label} (${ms}ms)`));
+      results.push({ step, index: i, status: 'passed', durationMs: ms, output: stdout });
+
+    } catch (err) {
+      const ms = Date.now() - stepStart;
+      const errMsg = (err as Error).message;
+
+      if (step.optional) {
+        console.log(chalk.yellow(`  [${i + 1}/${flow.steps.length}] SKIP  ${label} (optional, ${ms}ms) — ${errMsg}`));
+        results.push({ step, index: i, status: 'skipped', durationMs: ms, error: errMsg });
+      } else {
+        console.log(chalk.red(`  [${i + 1}/${flow.steps.length}] FAIL  ${label} (${ms}ms) — ${errMsg}`));
+        results.push({ step, index: i, status: 'failed', durationMs: ms, error: errMsg });
+        aborted = true;
+      }
+    }
+  }
+
+  // Auto-session: close browser
+  if (flow.config.autoSession) {
+    runAgentBrowser(['close']);
+  }
+
+  // Summary
+  const totalMs = Date.now() - startTime;
+  const passed = results.filter(r => r.status === 'passed').length;
+  const failed = results.filter(r => r.status === 'failed').length;
+  const skipped = results.filter(r => r.status === 'skipped').length;
+  const status = failed === 0 ? 'passed' : 'failed';
+
+  console.log();
+  const statusColor = status === 'passed' ? chalk.green : chalk.red;
+  console.log(statusColor.bold(`${status.toUpperCase()}: ${passed} passed, ${failed} failed, ${skipped} skipped (${totalMs}ms)`));
+
+  const result: FlowResult = {
+    flowName, platform, status, totalSteps: flow.steps.length,
+    passed, failed, skipped, durationMs: totalMs, steps: results,
+  };
+  console.log('\n' + JSON.stringify(result));
+
+  if (failed > 0) process.exit(1);
+}
+
+// ── CLI ───────────────────────────────────────────────────────────────────────
+
+program
+  .argument('<action>', 'Flow file path, or "exec" for single step, or "assert-ai" for AI assertion')
+  .argument('[target]', 'Screenshot path (for assert-ai)')
+  .option('--env <pairs...>', 'Environment variables (KEY=VALUE)')
+  .option('--headed', 'Run browser in headed mode')
+  .option('--platform <platform>', 'Override platform (web, ios, android)')
+  .option('--type <type>', 'Step type (for exec action)')
+  .option('--selector <sel>', 'Element selector (for exec action)')
+  .option('--value <val>', 'Step value (for exec action)')
+  .option('--params <json>', 'Additional params as JSON (for exec action)')
+  .option('--prompt <text>', 'Assertion prompt (for assert-ai action)')
+  .parse();
+
+const [action, target] = program.args;
+const opts = program.opts();
+
+(async () => {
+  try {
+    if (action === 'exec') {
+      if (!opts.type) throw new Error('--type is required for exec action');
+      await execSingleStep(opts);
+    } else if (action === 'assert-ai') {
+      if (!target) throw new Error('Screenshot path is required for assert-ai');
+      if (!opts.prompt) throw new Error('--prompt is required for assert-ai');
+      const result = await assertWithAI(target, opts.prompt);
+      if (result.passes) {
+        console.log(chalk.green(`PASS: ${result.details}`));
+      } else {
+        console.log(chalk.red(`FAIL: ${result.details}`));
+      }
+      console.log(JSON.stringify(result));
+      if (!result.passes) process.exit(1);
+    } else {
+      // Treat action as a flow file path
+      await runFlow(action, opts);
+    }
+  } catch (err) {
+    console.error(chalk.red(`Error: ${(err as Error).message}`));
+    process.exit(1);
+  }
+})();

package/templates/assistkick-product-system/packages/shared/tools/app_use_validate.ts

@@ -0,0 +1,67 @@
+#!/usr/bin/env node
+
+/**
+ * app_use_validate — Validate a YAML flow file without executing it.
+ *
+ * Usage:
+ *   pnpm tsx packages/shared/tools/app_use_validate.ts <flow.yaml>
+ *   pnpm tsx packages/shared/tools/app_use_validate.ts <flow.yaml> --show-steps
+ */
+
+import { program } from 'commander';
+import chalk from 'chalk';
+import { readFlowFile, validateFlow } from '../lib/app_use_flow.js';
+
+program
+  .argument('<flow>', 'Path to flow YAML file')
+  .option('--show-steps', 'Show parsed steps for debugging')
+  .parse();
+
+const [flowPath] = program.args;
+const opts = program.opts();
+
+(async () => {
+  try {
+    const flow = readFlowFile(flowPath);
+    const issues = validateFlow(flow);
+
+    console.log(chalk.cyan.bold(`\nFlow: ${flow.config.name || flowPath}\n`));
+    console.log(`  Platform: ${flow.config.platform || 'web'}`);
+    if (flow.config.appId) console.log(`  App: ${flow.config.appId}`);
+    console.log(`  Steps: ${flow.steps.length}`);
+    console.log(`  Auto-session: ${flow.config.autoSession !== false}`);
+    if (flow.config.env) {
+      console.log(`  Env vars: ${Object.keys(flow.config.env).join(', ')}`);
+    }
+    console.log();
+
+    if (opts.showSteps) {
+      console.log(chalk.cyan('  Steps:'));
+      for (let i = 0; i < flow.steps.length; i++) {
+        const s = flow.steps[i];
+        const parts: string[] = [s.type];
+        if (s.selector) parts.push(s.selector);
+        if (s.value) parts.push(`"${s.value}"`);
+        if (s.optional) parts.push('(optional)');
+        if (s.label) parts.push(`— ${s.label}`);
+        console.log(`    ${i + 1}. ${parts.join(' ')}`);
+      }
+      console.log();
+    }
+
+    if (issues.length === 0) {
+      console.log(chalk.green.bold('Valid flow — no issues found'));
+      console.log(JSON.stringify({ valid: true, steps: flow.steps.length, issues: [] }));
+    } else {
+      console.log(chalk.yellow.bold(`Found ${issues.length} issue(s):`));
+      for (const issue of issues) {
+        console.log(chalk.yellow(`  - ${issue}`));
+      }
+      console.log('\n' + JSON.stringify({ valid: false, steps: flow.steps.length, issues }));
+      process.exit(1);
+    }
+  } catch (err) {
+    console.error(chalk.red(`Error: ${(err as Error).message}`));
+    process.exit(1);
+  }
+})();