track: cli-default-experimental-api-20260430

[amondnet]

---

product_spec_domain: deployment

CLI Default with Experimental API Mode

Track: cli-default-experimental-api-20260430

Overview

Restore the Vercel CLI as the default deployment client, and provide the @vercel/client API-based deployment as an opt-in experimental feature gated by a new experimental-api action input.

The previous track (api-based-deployment-20260329) made API the default when vercel-args was empty. However, @vercel/client is an internal Vercel package without semver guarantees, so users should explicitly opt in to the API path rather than have it imposed as the default.

Requirements

Functional Requirements

• FR-1: Add a new experimental-api boolean input to action.yml (default: false).
• FR-2: Default routing in createVercelClient() returns VercelCliClient when experimental-api is false (or unset).
• FR-3: When experimental-api is true, createVercelClient() returns VercelApiClient and emits a core.warning line stating that API mode is experimental and may break across @vercel/client updates.
• FR-4: When experimental-api is true AND vercel-args is non-empty, the action MUST fail fast with a clear configuration error explaining that the two inputs are mutually exclusive, and instruct the user to choose one.
• FR-5: When vercel-args is non-empty and experimental-api is false, route to VercelCliClient (legacy passthrough preserved).
• FR-6: Remove the deprecationMessage block from vercel-args and scope inputs in action.yml — CLI is now the standard mode and these inputs are no longer deprecated.
• FR-7: Update ActionConfig type and getActionConfig() parser in src/config.ts to surface the new experimentalApi: boolean field.
• FR-8: Update README.md with: (a) a new "Deployment Mode" section explaining CLI is default and experimental-api opt-in, (b) the warning that API mode is experimental, (c) the mutual exclusion rule with vercel-args.

Non-functional Requirements

• NFR-1: Behavior parity — when API mode is enabled via experimental-api, deployment outputs (preview-url, preview-name, deployment-id) must match the previous API-default behavior.
• NFR-2: Released as a semver MINOR bump (no user code change is required to keep working — workflows that set vercel-args continue unchanged; users who relied on API as default must opt in, but this is a behavior change documented in release notes, not an API contract change).
• NFR-3: Test coverage ≥80% for new routing logic and config parsing changes.

Acceptance Criteria

• AC-1: pnpm test — new unit tests cover all four routing matrix cases:
  • experimental-api=false, vercel-args="" → VercelCliClient
  • experimental-api=false, vercel-args="--prod" → VercelCliClient
  • experimental-api=true, vercel-args="" → VercelApiClient (with warning)
  • experimental-api=true, vercel-args="--prod" → throws config error before client construction
• AC-2: pnpm test:integration — emulator-backed test confirms experimental-api=true end-to-end deployment still produces the expected preview URL.
• AC-3: pnpm build succeeds and dist/index.js rebuilds cleanly.
• AC-4: pnpm lint passes with no new warnings.
• AC-5: Running the action with default inputs (no experimental-api, no vercel-args) on a sample workflow uses CLI mode (verifiable via core.info log line).
• AC-6: The core.warning is emitted exactly once per action run when experimental-api=true.

Out of Scope

• Removing the vercel CLI npm dependency or the @actions/exec dependency.
• Removing or migrating @vercel/client away from internal-package status.

---

Track: cli-default-experimental-api-20260430
Plan: .please/docs/tracks/active/cli-default-experimental-api-20260430/plan.md

[amondnet]

Progress Update

Phase 1 — Config foundation complete.

Progress: 4/12 tasks (33%)

• T001 Add experimental-api input to action.yml
• T002 Add experimentalApi to ActionConfig
• T003 Parse + mutual-exclusion validation in getActionConfig()
• T004 Config tests (defaults, parsing, mutual-exclusion error)

Branch: amondnet/cli-default-api-exp
PR: #363

[amondnet]

Implementation Complete

All 12 tasks complete. Summary:

Phase	Tasks	Outcome
1 — Config foundation	T001–T004	New experimental-api input + mutual-exclusion validation in getActionConfig(); 7 new config tests
2 — Routing change	T005–T007	createVercelClient() defaults to VercelCliClient; API path is opt-in with core.warning; four-case routing matrix tests
3 — action.yml cleanup	T008	Real description for vercel-args; reworded scope deprecation message
4 — Documentation	T009–T010	New "Deployment Mode" section in README; migration note for users on previous v42 API default
5 — Integration + quality gate	T011–T012	Factory routing integration tests; lint, typecheck, build, full test suite all green

Test totals: 244 unit tests + 19 integration tests pass.

Doc sync: product.md updated to mention experimental API mode as opt-in extension.

PR #363 (draft) is ready for review and contains all changes.

[amondnet]

Implementation Complete — PR Ready for Review

PR #363 is now Ready for Review.

Summary

Restored the Vercel CLI as the default deployment client and gated the @vercel/client API path behind a new experimental-api opt-in input. After review feedback, the (experimental-api × vercel-args) mutual-exclusion is encoded in the type system as a discriminated union — illegal states are unrepresentable.

Stats

• 12/12 tasks complete
• 243 unit tests + 19 integration tests passing
• 2 iterations of code review; 0 remaining issues
• dist/ rebuilt and committed
• Spec compliance: 17/17 IMPLEMENTED