feat: choose the visual level and test suites per run (--visual, --tests)

[dadachi]

Closes #160

Changes

1. CLI (src/index.ts, src/run-options.ts) — --visual=0|1|2 (also --visual 2), --tests, --no-tests. Precedence: flag > NATIVEAPPTEMPLATE_VISUAL / NATIVEAPPTEMPLATE_TESTS > default (0, no tests). The variables keep their old reading. An invalid --visual (3, high, empty, missing) exits 2 with error: --visual must be 0, 1, or 2 (got "3"). Tests still imply build mode.

2. MCP generate_app (src/mcp.ts) — optional visual (0|1|2, zod literal union) and tests (boolean). They go to dispatch() as DispatchOptions.visual / .tests for that call only. process.env is never written, so nothing carries over to the server's next call. createMcpServer({ dispatch }) is the test seam.

3. Preflight (src/preflight.ts, called from dispatch() so the CLI, MCP and plugin all get it). When the visual level is >= 1, before the planner (the first Anthropic API call), it checks for:

   • a booted iOS simulator (xcrun simctl list devices booted -j, iOS runtimes only); if NATIVEAPPTEMPLATE_MOBILE_IOS_DEVICE is set, that udid/name must be booted.
   • an online Android device (adb devices via resolveAdbPath + the existing parseAdbDevices); if NATIVEAPPTEMPLATE_ADB_SERIAL is set, that serial must be attached.
   • for level 2, mise --version.

   If something is missing it throws PreflightError with the list. The CLI prints it plus "Nothing was generated and no API call was made." and exits 2. MCP returns isError. The checks are injectable (DispatchOptions.preflight, PreflightDeps, explicit env) and are skipped in judge-stub mode, so unit tests never touch real simctl/adb/mise.

4. Plugin skill (plugin/skills/generate-app/SKILL.md):

   • maps "visual 2" / "visual validation" / "check the UI too" / "画面も確認して" to --visual=2, "visual 1" / "just check the home screen" to --visual=1, and "run the tests" / "テストも回して" to --tests.
   • gives time and cost per level from the README Runtime table (0: ~2–3 min, ~$0.02; 1: ~2.5 min, ~$0.13; 2: ~7–8 min, ~$0.22), plus prerequisites. For levels 1/2 it asks the user to confirm before running.
   • explains how to relay a preflight failure.
   • PARTIAL / semantic-depth advice now suggests --visual=1 instead of restarting with NATIVEAPPTEMPLATE_VISUAL=1.

5. Docs:

   • README: new "Validation flags" table next to the naming flags; the env bullets and Runtime header mention the flags.
   • plugin/README.md: a plain-language paragraph.
   • docs/PLUGIN-GUIDE.md: §6.2 overrides, §9 CLI flag table, §7.2 example, and troubleshooting now refer to the flags.
   • Report: the footer's "Reproduce this run" line and the PARTIAL badge/CLI hint use the flags.

Tests

New tests:

• parseArgs: both forms, --tests / --no-tests, invalid values become errors.
• resolveVisualLevel / resolveTests precedence.
• dispatch: options override the env, and preflight runs only at level >= 1, with the resolved level.
• dispatch rejects with PreflightError.
• preflightVisual with mocked simctl/adb/mise: none booted, adb failure, level 1 without mise, and the override variables.
• parseBootedIosSimulators.
• MCP: two calls on one server. {visual: 2, tests: true} then {} gives seen = [{visual:2,tests:true}, {}], reports 2/true then 0/unset, and process.env stays untouched. visual: 3 is rejected by the schema.
• MCP preflight failure becomes an error result.

Each new test was seen red against a mutation of its target (flag ignored, precedence flipped, MCP dropping visual, mise / serial checks removed, dispatch preflight skipped, invalid value accepted, watchOS runtime not filtered), then green. npm run ci: 196 pass.

Real check

• preflightVisual(1) and (2) against this machine (booted iPhone 17 Pro, emulator-5554 + a phone, mise installed): [].
• PATH=/usr/bin:/bin:<node> NATIVEAPPTEMPLATE_ADB_SERIAL=bogus-1 node dist/index.js "a queue" --visual 2:

  error: visual level 2 needs a few things that aren't ready:
    - NATIVEAPPTEMPLATE_ADB_SERIAL="bogus-1" is not attached (adb devices: 1C081FDF600CMG, emulator-5554). Boot it or fix the variable.
    - `mise` isn't on PATH: visual level 2 boots the generated Rails API with `mise exec -- bin/dev` for the Stage 2 walk. Install it (https://mise.jdx.dev) or use --visual=1.
  Nothing was generated and no API call was made.
  

  Exit 2. --visual=5 also exits 2 with the usage line. No paid end-to-end run was made.

Notes

• The plugin's .mcp.json / npx -y nativeapptemplate-agent resolve the published package, so the new flags and MCP args reach plugin users with the next npm release.
• fix(stage2): launch the app under test in English whatever the device language #161 (Stage 2 fails when the simulator/emulator isn't in English #159) touches different code. The two PRs are independent and both edit tests/smoke.test.ts in different places.

🤖 Generated with Claude Code

https://claude.ai/code/session_01UZJxUoubntzu7Ec7DPVfAr