feat(runner): provide shared local flow runtime deps

[Mateus Zitelli (MateusZitelli)]

Summary

Stacked on #1372.

• Add architecture-neutral FlowRuntimeDeps
• Wire shared runtime deps into both web and Android flows
• Add .env-backed local implementations for:
  • setEnvironmentVariable
  • fetchLatestEnvironmentVariables
• Add lazy getInbox support using either:
  • EMAILER_URL, or
  • QA Wolf auth / API credentials
• Wire runtime deps through normal runs, flows run --env, and worker subprocesses

Why

Local flows need the same runtime capabilities regardless of architecture. Email inbox access should work for Android and web flows, and should not eagerly load/configure email dependencies unless a flow actually calls getInbox.

Stack

• Depends on refactor(core): move dotenv helpers to core #1372
• Independent of fix(flows): skip invalid dotenv keys on pull #1373

Tests

• bun run lint
• bun run typecheck
• bun run test src/commands/flows/flowRuntimeDeps.test.ts src/commands/flows/envVarDeps.test.ts src/domains/runner/runWebFlow.test.ts src/domains/runner/runAndroidFlow.test.ts src/commands/flows/runDefaults.handle.test.ts src/commands/flows/hybridRun.test.ts src/commands/flows/runDefaults.reporterWiring.test.ts

[coderabbitai]

Walkthrough

This PR adds shared FlowRuntimeDeps for lazy email inbox access and environment-variable persistence. It implements .env read/write helpers, refactors email configuration to accept typed options, and injects runtime dependencies into web and Android flows. Staged runs, workers, hybrid defaults, and related tests now construct or mock the shared dependency bundle.

Estimated code review effort: 4 (Complex) | ~60 minutes

Possibly related PRs

• qawolf/cli#1381: Modifies flow-runner dependency wiring in the same runner dependency contracts extended here.

Suggested reviewers: chajac, smonn, michael-pr

🚥 Pre-merge checks | ✅ 4

✅ Passed checks (4 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title follows Conventional Commits and accurately describes the shared flow runtime dependency work.
Description check	✅ Passed	The description covers the change summary, rationale, dependency stack, and testing, though it does not mirror the template exactly.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch wiz-shared-flow-runtime-deps

---

_{Comment @coderabbitai help to get the list of available commands.}

[Chase J (chajac)]

Tested against node and binary versions only one addition needed is that some flows will call mail.inbox() which was failing.

[coderabbitai]

Actionable comments posted: 2

Caution

Some comments are outside the diff and can’t be posted inline due to platform limitations.

⚠️ Outside diff range comments (1)

src/commands/flows/runStagedFlows.ts (1)

75-77: 🗄️ Data Integrity & Integration | 🟠 Major | ⚡ Quick win

envDir should point at the project .env directory here, not runtimeEnv.depsRoot. makeEnvVarDeps uses this value as the .env target, so the current wiring writes env changes into the managed cache instead of the project/--env directory and breaks the persistence round-trip. Pass envDir ?? projectDir ?? process.cwd() instead.

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@src/commands/flows/runStagedFlows.ts` around lines 75 - 77, Update the
environment-directory argument used by makeEnvVarDeps in the runStagedFlows flow
so it receives envDir ?? projectDir ?? process.cwd(), rather than
runtimeEnv.depsRoot. Keep loadEnvFile aligned with this same project/--env
directory selection to preserve environment changes in the intended location.

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@src/commands/flows/runDefaults.handle.test.ts`:
- Around line 27-30: Replace the loosely typed createFlowRuntimeDepsMock
declarations in runDefaults.handle.test.ts and hybridRun.test.ts with
mock<StagedRunDeps["createFlowRuntimeDeps"]>(), and remove the corresponding
unknown-based double casts when assigning them to createFlowRuntimeDeps. Apply
this to both occurrences in hybridRun.test.ts so the mocks enforce the real
function signature.

In `@src/domains/emails/configureEmails.ts`:
- Around line 58-65: Update registerLazyEmailsClient to configure the SDK with a
complete EmailsClient rather than only { getInbox }; preserve lazy behavior by
supplying valid implementations for all required client methods, or introduce
and call a dedicated lazy-specific setter in the SDK. Ensure the configured
client supports mail.inbox() and satisfies the configureEmailsClient type
contract.

---

Outside diff comments:
In `@src/commands/flows/runStagedFlows.ts`:
- Around line 75-77: Update the environment-directory argument used by
makeEnvVarDeps in the runStagedFlows flow so it receives envDir ?? projectDir ??
process.cwd(), rather than runtimeEnv.depsRoot. Keep loadEnvFile aligned with
this same project/--env directory selection to preserve environment changes in
the intended location.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: ASSERTIVE

Plan: Pro Plus

Run ID: 7cdb3e3e-9d77-4b89-95c5-702f71c6afdb

📥 Commits

Reviewing files that changed from the base of the PR and between 11016d9 and 248e6d4.

📒 Files selected for processing (21)

• .changeset/shared-flow-runtime-deps.md
• src/commands/flows/buildFlowsRunDeps.ts
• src/commands/flows/envVarDeps.test.ts
• src/commands/flows/envVarDeps.ts
• src/commands/flows/flowRuntimeDeps.test.ts
• src/commands/flows/flowRuntimeDeps.ts
• src/commands/flows/hybridRun.test.ts
• src/commands/flows/hybridRunDefaults.ts
• src/commands/flows/runDefaults.handle.test.ts
• src/commands/flows/runDefaults.reporterWiring.test.ts
• src/commands/flows/runDefaults.ts
• src/commands/flows/runStagedFlows.test.ts
• src/commands/flows/runStagedFlows.ts
• src/commands/flows/runWorker.register.ts
• src/domains/emails/configureEmails.test.ts
• src/domains/emails/configureEmails.ts
• src/domains/runner/flowRuntimeDeps.ts
• src/domains/runner/runAndroidFlow.getInbox.fixture.ts
• src/domains/runner/runAndroidFlow.test.ts
• src/domains/runner/runAndroidFlow.ts
• src/domains/runner/runWebFlow.ts