fix: improve deploy auth UX

[southpolesteve]

Fixes #312

Summary

• auto-detect interactive vs headless Wrangler auth during vinext deploy
• reuse saved local auth or start wrangler login, and fail early in CI with exact token/account guidance
• resolve CLOUDFLARE_ACCOUNT_ID from env or Wrangler config, including selected --env blocks
• keep deploy host-neutral by injecting the Cloudflare Vite plugin at deploy time while preserving the warning from fix: warn when existing vite.config.ts is missing cloudflare plugin on deploy #315 as a softer note
• document the local/CI flows and add regression coverage for auth/account-ID planning
• add an AGENTS rule to refresh origin/main before starting work

Behavior By Scenario

• vinext deploy stays Cloudflare-specific; Nitro remains the multi-platform path.
• If wrangler is missing, vinext deploy installs it automatically.
• In a local interactive terminal, vinext reuses an existing Wrangler session.
• In a local interactive terminal without saved auth, vinext runs wrangler login and then continues.
• In a headless shell without CLOUDFLARE_API_TOKEN, vinext fails early with a message that points to Wrangler login docs for local use and Cloudflare token docs for CI use.
• In a headless shell with CLOUDFLARE_API_TOKEN but no account ID, vinext fails early before build.
• Account ID can come from CLOUDFLARE_ACCOUNT_ID, top-level account_id, or env-specific account_id in the selected Wrangler env block.
• If an existing vite.config.* is missing @cloudflare/vite-plugin, vinext warns but still injects the plugin for the deploy build so the deploy can proceed.
• vinext init remains host-neutral; Cloudflare-specific behavior stays in vinext deploy.

Testing

• npx vitest run tests/deploy.test.ts tests/init.test.ts
• pnpm run typecheck

[pkg-pr-new]

Open in StackBlitz

npm i https://pkg.pr.new/vinext@329

commit: 6b66aad

[github-actions]

Example	Preview	Production	Original
app-router-cloudflare	preview	production
pages-router-cloudflare	preview	production
app-router-playground	preview	production	original
realworld-api-rest	preview	production
nextra-docs-template	preview	production
benchmarks	preview	production
hackernews	preview	production	original

[southpolesteve]

/bigbonk review please

[ask-bonk]

Review: Deploy Auth UX

All CI checks are green (Lint, Typecheck, Vitest, all 5 E2E projects, deploys, smoke tests). The code is well-structured and the test coverage is thorough.

What's Good

Auth planning is cleanly factored. The WranglerAuthPlan discriminated union (token | interactive | login | error) makes the auth decision tree explicit and easy to test. Each scenario maps to a clear code path in ensureWranglerAuth, and the planWranglerAuth function is fully pure — env, tty state, saved login, and account ID are all injected, making the tests deterministic without mocking globals.

Account ID resolution cascade is correct. resolveWranglerAccountId checks env var → wrangler config (with env-specific override) in the right order. The parseWranglerConfig changes to accept targetEnv are clean — env-specific blocks take precedence for account_id, KV namespaces, routes, and custom domains in both JSON and TOML, with top-level as fallback.

Cloudflare plugin injection at deploy time is the right call. getDeployBuildConfig loads the user's Vite config, checks if the Cloudflare plugin is present by plugin name (not just text matching), and injects it only when missing. This keeps vinext init host-neutral while making vinext deploy just work. The configNeedsCloudflarePlugin helper correctly handles nested plugin arrays via flattenPlugins.

Error messages are actionable. Both buildWranglerAuthHelpMessage and buildWranglerAccountIdHelpMessage include exact env var names, doc links for every step, and differentiate between local terminal and CI scenarios. The test assertions verify all the links are present.

README docs match the implementation. The prerequisites section now accurately describes the interactive login flow, env var auth, and account ID resolution order.

Minor Observations

1. hasSavedWranglerLogin shells out to wrangler whoami — this adds a ~1-2s synchronous call before the build starts in interactive mode. Acceptable for deploy UX, just noting it's there.

2. ensureWranglerAuth calls process.exit(1) directly — this is consistent with how the rest of the deploy pipeline handles fatal errors (the "no app/ or pages/" check does the same). Fine for CLI code, though it does mean this path is untestable in-process. The planWranglerAuth tests cover the decision logic thoroughly enough.

3. TOML env block parsing (getTOMLEnvBlock) uses indexOf + search(/^\[/m) to find the next section header. This works for standard wrangler.toml files but would break on edge cases like [env.preview] appearing inside a multi-line string value. Not a real concern — wrangler.toml files don't contain that pattern in practice.

4. runWranglerDeploy returns null in interactive mode (since stdio: "inherit" means we can't capture output). The caller correctly handles this with if (url) — clean.

Looks good to merge.

[ask-bonk]

Approved the PR. Here's my review summary:

---

All 23 CI checks pass. Code is well-structured with good test coverage.

Key strengths:

• Auth planning uses a clean WranglerAuthPlan discriminated union — fully testable with injected dependencies, no mocking needed
• Account ID resolution cascade (env var → wrangler config with env-specific override) is correct for both JSON and TOML
• Cloudflare plugin injection at deploy time (getDeployBuildConfig) checks by plugin name, not text matching, and handles nested plugin arrays
• Error messages are actionable — exact env var names, doc links, local vs CI differentiation
• README accurately reflects the new behavior

Minor observations (none blocking):

1. hasSavedWranglerLogin adds ~1-2s synchronous wrangler whoami call before build in interactive mode — acceptable for deploy UX
2. ensureWranglerAuth uses process.exit(1) directly (consistent with rest of deploy pipeline, decision logic is covered by planWranglerAuth tests)
3. TOML env block parsing is good enough for real wrangler.toml files
4. runWranglerDeploy returning null in interactive mode (can't capture stdio: "inherit" output) is handled cleanly

github run