flywheel-uat

Flywheel UAT

Input: Flywheel acceptance criteria, source revision, configured auth and provider state, and a session scratch directory.

Compose generic UAT. Install with bun run install:local; never substitute bun run dev or bin/flywheel. Discover the driver with bun run uat:tui --help. Start with bun run uat:tui start --scratch-root <your-session-scratch> --source-project-root <source-root>. When your instructions name an auth profile for development, add --env FLYWHEEL_AUTH_PROFILE=<profile>; otherwise the harness uses your configured default profile. Pass required non-secret configuration with --config <file> and environment values with repeated --env K=V. Write files only inside your own session scratchpad. The driver returns a sandbox root handle and the first pane. It owns unique HOME, project, evidence, tmux readiness, credential cloning, failure diagnostics, and cleanup.

Drive one bounded action per tool call with bun run uat:tui <verb> <handle> .... Each action prints the pane so you can act, observe, then decide. Use type '<prompt>', submit, keys Escape, click '<visible text>', capture pane.log, history history.log, wait '<text>' --timeout 30000, and events <search-args>. Use wait '<pattern>' --regex for a regular expression. Find controls in the current pane and click by visible text, not guessed labels or coordinates. Use click '<text>' --last when a modal repeats transcript text. Coordinate clicks remain available as click <col> <row>. Wait until a selected modal row is loaded before sending Enter.

Credential-backed UAT is the default. Unless a criterion explicitly requires an unauthenticated state, let the shared harness resolve and clone the selected profile. The start request's --env FLYWHEEL_AUTH_PROFILE takes precedence over the harness process environment and the configured default. The harness uses the resolved profile ID for both cloning and launch. Its credential contract is: Clone only that profile's auth.json and optional profile.json, write a token-free reference for each Claude login, reject links, apply owner-only directory and file permissions, and set FLYWHEEL_AUTH_PROFILE. Claude references share the original login and its refresh lock; the harness never reads or copies a Claude token. Never copy caches, usage databases, other profiles, or credential bytes into logs or artifacts. Never implement a separate credential copy or launch against the real HOME. A missing configured profile or unsafe copy is blocked. A Claude sign-in or re-login criterion also runs on the reference, so the engine's login keeps its token in the person's own login keychain. Never pass cloneAuth: false or create a new Claude login folder in the isolated home for it: that home has no keychain, the token is not saved, and macOS offers a "Reset To Defaults" button that erases the person's keychain.

The harness sets FLYWHEEL_TEST_SUPPRESS_AUTO_DIALOGS=1 by default. Direct installed-TUI launches must set the same flag. This suppresses automatic auth and paid-use dialogs, including late, post-login, profile-change, and submission prompts. It does not grant authentication or paid permissions, record answers, or suppress manually opened dialogs. Unauthenticated chat remains blocked. Keep meaningful credentials and provider configuration; do not disable providers or close questions to prevent unexpected popups.

For a criterion that tests automatic dialogs, pass --env FLYWHEEL_TEST_SUPPRESS_AUTO_DIALOGS=0 to start. Direct launchers for that criterion must set FLYWHEEL_TEST_SUPPRESS_AUTO_DIALOGS=0. Absence or 0 preserves normal product behavior. Observe and answer those dialogs only as the criterion requires. The harness never dismisses auth or paid-use questions.

The harness resolves only an installed flywheel, initializes and validates an isolated git root, sets FLYWHEEL_PROJECT_ROOT, and redirects stderr. It waits for for fresh chat every 50 ms for at most 45 seconds. It never closes startup dialogs. Opt-in dialog scenarios own their observations and interactions. A pane process that exits before the marker, or a readiness timeout, is blocked; before cleanup retain the final pane capture, available pane history, and stderr file. Setup and launch failures are also blocked.