feat(deploy): recover from production_instance_exists and surface plan-feature errors by wyattjoh · Pull Request #289 · clerk/cli

wyattjoh · 2026-05-13T22:30:05Z

Summary

Adds two live-error recovery paths in clerk deploy and the small refactors that make them readable. When production-instance creation returns production_instance_exists (HTTP 400) the wizard now refetches the application, persists the existing production instance id, and jumps straight into the reconcile flow as if local state had been intact. When clone validation returns unsupported_subscription_plan_features (HTTP 402) the wizard rethrows a CliError that lists the unsupported features from error.meta.unsupported_features and points at the billing-plans docs.

Details

createProductionInstance is wrapped in a try/catch that branches on the new structured PlapiError.code. On production_instance_exists, reloadProductionState calls fetchApplication, finds the existing production instance, persists its id, and returns an updated DeployContext; the wizard then calls reconcileExistingDeploy and returns, so subsequent runs short-circuit. runValidateCloning is wrapped similarly to translate the plan-features error before any UI is rendered. A small guard rejects production-instance creation responses that come back without active_domain; this required loosening active_domain to nullable in ProductionInstanceResponse so callers must check.

Test plumbing adds two mock injection flags on clerk deploy: --testFailCreateProductionInstanceExists and --testFailValidateCloningUnsupportedFeatures=<feature-list>. The mock layer in commands/deploy/mock.ts produces the corresponding PLAPI error envelopes so the new code paths can be exercised end-to-end without hitting a real Platform API. The deploy README.md gains a "Recovery paths" section documenting both error codes and the wizard's response.

Test plan

bun run scripts/run-tests.ts --pattern 'packages/cli-core/src/commands/deploy/**' --concurrency 1
bun run typecheck
bun run lint
CI green

wyattjoh · 2026-05-13T22:30:11Z

Stack: api-errors-and-deploy

refactor(errors): expose structured Clerk error fields on ApiError subclasses #288
- feat(deploy): added deploy wizard #260
  - feat(deploy): recover from production_instance_exists and surface plan-feature errors #289 👈 this PR

Part of a stacked-prs chain. Do not merge manually.

changeset-bot · 2026-05-13T22:30:12Z

🦋 Changeset detected

Latest commit: fae8e67

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 1 package

Name	Type
clerk	Minor

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

… fields

Replace formatApiBody(body: string) with formatApiBody(error: ApiError), deleting extractApiErrorCode, extractApiErrors, and formatSingleError. The new formatStructuredError reads code/message/meta directly from the parsed ApiError instance. The agent path builds ApiErrorEntry inline from structured fields and surfaces clerkTraceId in verbose human mode. Tests updated to construct ApiError instances and reflect single-error output for multi-error bodies.

- Preserve completed providers when pausing OAuth setup mid-loop, so `clerk deploy --continue` can finish multi-provider stacks. - Surface a warning for OAuth providers enabled in dev that the wizard does not yet support, instead of silently skipping them. - Close the gutter as Paused (not Failed) when DNS verification times out, since the state is recoverable via --continue. - Tighten the production-domain regex to reject malformed inputs like example..com or example-.com before they reach the API.

Move deploy lifecycle endpoint wrappers into the shared PLAPI client while routing the deploy wizard through a command-local adapter that defaults to mocked operations until the backend endpoints are ready.

…ceParams

…plan features

…e state

…ures When validateCloning returns HTTP 402 with code unsupported_subscription_plan_features, rethrow a CliError whose message lists the unsupported features from meta.unsupported_features and includes a docs URL hint pointing at clerk.com/docs/billing/plans.

wyattjoh · 2026-05-21T15:56:12Z

Closing in favor of #260. The error-recovery work (HTTP 409 production_instance_exists + HTTP 402 unsupported_subscription_plan_features) landed on the parent PR via the dedicated errors.ts mapping module (commands/deploy/errors.ts), which covers a broader set of PLAPI error codes than this branch originally proposed. The two remaining defensive cleanups from this branch — typing active_domain as nullable with a runtime guard, and dropping the unused is_secondary field — have been folded into #260.

wyattjoh · 2026-05-13T22:30:05Z

Summary

Adds two live-error recovery paths in clerk deploy and the small refactors that make them readable. When production-instance creation returns production_instance_exists (HTTP 400) the wizard now refetches the application, persists the existing production instance id, and jumps straight into the reconcile flow as if local state had been intact. When clone validation returns unsupported_subscription_plan_features (HTTP 402) the wizard rethrows a CliError that lists the unsupported features from error.meta.unsupported_features and points at the billing-plans docs.

Details

createProductionInstance is wrapped in a try/catch that branches on the new structured PlapiError.code. On production_instance_exists, reloadProductionState calls fetchApplication, finds the existing production instance, persists its id, and returns an updated DeployContext; the wizard then calls reconcileExistingDeploy and returns, so subsequent runs short-circuit. runValidateCloning is wrapped similarly to translate the plan-features error before any UI is rendered. A small guard rejects production-instance creation responses that come back without active_domain; this required loosening active_domain to nullable in ProductionInstanceResponse so callers must check.

Test plumbing adds two mock injection flags on clerk deploy: --testFailCreateProductionInstanceExists and --testFailValidateCloningUnsupportedFeatures=<feature-list>. The mock layer in commands/deploy/mock.ts produces the corresponding PLAPI error envelopes so the new code paths can be exercised end-to-end without hitting a real Platform API. The deploy README.md gains a "Recovery paths" section documenting both error codes and the wizard's response.

Test plan

bun run scripts/run-tests.ts --pattern 'packages/cli-core/src/commands/deploy/**' --concurrency 1
bun run typecheck
bun run lint
CI green

wyattjoh · 2026-05-13T22:30:11Z

Stack: api-errors-and-deploy

refactor(errors): expose structured Clerk error fields on ApiError subclasses #288
- feat(deploy): added deploy wizard #260
  - feat(deploy): recover from production_instance_exists and surface plan-feature errors #289 👈 this PR

Part of a stacked-prs chain. Do not merge manually.

changeset-bot · 2026-05-13T22:30:12Z

🦋 Changeset detected

Latest commit: fae8e67

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 1 package

Name	Type
clerk	Minor

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

… fields

Replace formatApiBody(body: string) with formatApiBody(error: ApiError), deleting extractApiErrorCode, extractApiErrors, and formatSingleError. The new formatStructuredError reads code/message/meta directly from the parsed ApiError instance. The agent path builds ApiErrorEntry inline from structured fields and surfaces clerkTraceId in verbose human mode. Tests updated to construct ApiError instances and reflect single-error output for multi-error bodies.

- Preserve completed providers when pausing OAuth setup mid-loop, so `clerk deploy --continue` can finish multi-provider stacks. - Surface a warning for OAuth providers enabled in dev that the wizard does not yet support, instead of silently skipping them. - Close the gutter as Paused (not Failed) when DNS verification times out, since the state is recoverable via --continue. - Tighten the production-domain regex to reject malformed inputs like example..com or example-.com before they reach the API.

Move deploy lifecycle endpoint wrappers into the shared PLAPI client while routing the deploy wizard through a command-local adapter that defaults to mocked operations until the backend endpoints are ready.

…ceParams

…plan features

…e state

…ures When validateCloning returns HTTP 402 with code unsupported_subscription_plan_features, rethrow a CliError whose message lists the unsupported features from meta.unsupported_features and includes a docs URL hint pointing at clerk.com/docs/billing/plans.

wyattjoh · 2026-05-21T15:56:12Z

Closing in favor of #260. The error-recovery work (HTTP 409 production_instance_exists + HTTP 402 unsupported_subscription_plan_features) landed on the parent PR via the dedicated errors.ts mapping module (commands/deploy/errors.ts), which covers a broader set of PLAPI error codes than this branch originally proposed. The two remaining defensive cleanups from this branch — typing active_domain as nullable with a runtime guard, and dropping the unused is_secondary field — have been folded into #260.

wyattjoh · 2026-05-13T22:30:05Z

Summary

Adds two live-error recovery paths in clerk deploy and the small refactors that make them readable. When production-instance creation returns production_instance_exists (HTTP 400) the wizard now refetches the application, persists the existing production instance id, and jumps straight into the reconcile flow as if local state had been intact. When clone validation returns unsupported_subscription_plan_features (HTTP 402) the wizard rethrows a CliError that lists the unsupported features from error.meta.unsupported_features and points at the billing-plans docs.

Details

createProductionInstance is wrapped in a try/catch that branches on the new structured PlapiError.code. On production_instance_exists, reloadProductionState calls fetchApplication, finds the existing production instance, persists its id, and returns an updated DeployContext; the wizard then calls reconcileExistingDeploy and returns, so subsequent runs short-circuit. runValidateCloning is wrapped similarly to translate the plan-features error before any UI is rendered. A small guard rejects production-instance creation responses that come back without active_domain; this required loosening active_domain to nullable in ProductionInstanceResponse so callers must check.

Test plumbing adds two mock injection flags on clerk deploy: --testFailCreateProductionInstanceExists and --testFailValidateCloningUnsupportedFeatures=<feature-list>. The mock layer in commands/deploy/mock.ts produces the corresponding PLAPI error envelopes so the new code paths can be exercised end-to-end without hitting a real Platform API. The deploy README.md gains a "Recovery paths" section documenting both error codes and the wizard's response.

Test plan

bun run scripts/run-tests.ts --pattern 'packages/cli-core/src/commands/deploy/**' --concurrency 1
bun run typecheck
bun run lint
CI green

wyattjoh · 2026-05-13T22:30:11Z

Stack: api-errors-and-deploy

refactor(errors): expose structured Clerk error fields on ApiError subclasses #288
- feat(deploy): added deploy wizard #260
  - feat(deploy): recover from production_instance_exists and surface plan-feature errors #289 👈 this PR

Part of a stacked-prs chain. Do not merge manually.

changeset-bot · 2026-05-13T22:30:12Z

🦋 Changeset detected

Latest commit: fae8e67

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 1 package

Name	Type
clerk	Minor

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

… fields

Replace formatApiBody(body: string) with formatApiBody(error: ApiError), deleting extractApiErrorCode, extractApiErrors, and formatSingleError. The new formatStructuredError reads code/message/meta directly from the parsed ApiError instance. The agent path builds ApiErrorEntry inline from structured fields and surfaces clerkTraceId in verbose human mode. Tests updated to construct ApiError instances and reflect single-error output for multi-error bodies.

- Preserve completed providers when pausing OAuth setup mid-loop, so `clerk deploy --continue` can finish multi-provider stacks. - Surface a warning for OAuth providers enabled in dev that the wizard does not yet support, instead of silently skipping them. - Close the gutter as Paused (not Failed) when DNS verification times out, since the state is recoverable via --continue. - Tighten the production-domain regex to reject malformed inputs like example..com or example-.com before they reach the API.

Move deploy lifecycle endpoint wrappers into the shared PLAPI client while routing the deploy wizard through a command-local adapter that defaults to mocked operations until the backend endpoints are ready.

…ceParams

…plan features

…e state

…ures When validateCloning returns HTTP 402 with code unsupported_subscription_plan_features, rethrow a CliError whose message lists the unsupported features from meta.unsupported_features and includes a docs URL hint pointing at clerk.com/docs/billing/plans.

wyattjoh · 2026-05-21T15:56:12Z

Closing in favor of #260. The error-recovery work (HTTP 409 production_instance_exists + HTTP 402 unsupported_subscription_plan_features) landed on the parent PR via the dedicated errors.ts mapping module (commands/deploy/errors.ts), which covers a broader set of PLAPI error codes than this branch originally proposed. The two remaining defensive cleanups from this branch — typing active_domain as nullable with a runtime guard, and dropping the unused is_secondary field — have been folded into #260.

wyattjoh · 2026-05-13T22:30:05Z

Summary

Adds two live-error recovery paths in clerk deploy and the small refactors that make them readable. When production-instance creation returns production_instance_exists (HTTP 400) the wizard now refetches the application, persists the existing production instance id, and jumps straight into the reconcile flow as if local state had been intact. When clone validation returns unsupported_subscription_plan_features (HTTP 402) the wizard rethrows a CliError that lists the unsupported features from error.meta.unsupported_features and points at the billing-plans docs.

Details

createProductionInstance is wrapped in a try/catch that branches on the new structured PlapiError.code. On production_instance_exists, reloadProductionState calls fetchApplication, finds the existing production instance, persists its id, and returns an updated DeployContext; the wizard then calls reconcileExistingDeploy and returns, so subsequent runs short-circuit. runValidateCloning is wrapped similarly to translate the plan-features error before any UI is rendered. A small guard rejects production-instance creation responses that come back without active_domain; this required loosening active_domain to nullable in ProductionInstanceResponse so callers must check.

Test plumbing adds two mock injection flags on clerk deploy: --testFailCreateProductionInstanceExists and --testFailValidateCloningUnsupportedFeatures=<feature-list>. The mock layer in commands/deploy/mock.ts produces the corresponding PLAPI error envelopes so the new code paths can be exercised end-to-end without hitting a real Platform API. The deploy README.md gains a "Recovery paths" section documenting both error codes and the wizard's response.

Test plan

bun run scripts/run-tests.ts --pattern 'packages/cli-core/src/commands/deploy/**' --concurrency 1
bun run typecheck
bun run lint
CI green

wyattjoh · 2026-05-13T22:30:11Z

Stack: api-errors-and-deploy

refactor(errors): expose structured Clerk error fields on ApiError subclasses #288
- feat(deploy): added deploy wizard #260
  - feat(deploy): recover from production_instance_exists and surface plan-feature errors #289 👈 this PR

Part of a stacked-prs chain. Do not merge manually.

changeset-bot · 2026-05-13T22:30:12Z

🦋 Changeset detected

Latest commit: fae8e67

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 1 package

Name	Type
clerk	Minor

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

… fields

Replace formatApiBody(body: string) with formatApiBody(error: ApiError), deleting extractApiErrorCode, extractApiErrors, and formatSingleError. The new formatStructuredError reads code/message/meta directly from the parsed ApiError instance. The agent path builds ApiErrorEntry inline from structured fields and surfaces clerkTraceId in verbose human mode. Tests updated to construct ApiError instances and reflect single-error output for multi-error bodies.

- Preserve completed providers when pausing OAuth setup mid-loop, so `clerk deploy --continue` can finish multi-provider stacks. - Surface a warning for OAuth providers enabled in dev that the wizard does not yet support, instead of silently skipping them. - Close the gutter as Paused (not Failed) when DNS verification times out, since the state is recoverable via --continue. - Tighten the production-domain regex to reject malformed inputs like example..com or example-.com before they reach the API.

Move deploy lifecycle endpoint wrappers into the shared PLAPI client while routing the deploy wizard through a command-local adapter that defaults to mocked operations until the backend endpoints are ready.

…ceParams

…plan features

…e state

…ures When validateCloning returns HTTP 402 with code unsupported_subscription_plan_features, rethrow a CliError whose message lists the unsupported features from meta.unsupported_features and includes a docs URL hint pointing at clerk.com/docs/billing/plans.

wyattjoh · 2026-05-21T15:56:12Z

Closing in favor of #260. The error-recovery work (HTTP 409 production_instance_exists + HTTP 402 unsupported_subscription_plan_features) landed on the parent PR via the dedicated errors.ts mapping module (commands/deploy/errors.ts), which covers a broader set of PLAPI error codes than this branch originally proposed. The two remaining defensive cleanups from this branch — typing active_domain as nullable with a runtime guard, and dropping the unused is_secondary field — have been folded into #260.

wyattjoh · 2026-05-13T22:30:05Z

Summary

Adds two live-error recovery paths in clerk deploy and the small refactors that make them readable. When production-instance creation returns production_instance_exists (HTTP 400) the wizard now refetches the application, persists the existing production instance id, and jumps straight into the reconcile flow as if local state had been intact. When clone validation returns unsupported_subscription_plan_features (HTTP 402) the wizard rethrows a CliError that lists the unsupported features from error.meta.unsupported_features and points at the billing-plans docs.

Details

createProductionInstance is wrapped in a try/catch that branches on the new structured PlapiError.code. On production_instance_exists, reloadProductionState calls fetchApplication, finds the existing production instance, persists its id, and returns an updated DeployContext; the wizard then calls reconcileExistingDeploy and returns, so subsequent runs short-circuit. runValidateCloning is wrapped similarly to translate the plan-features error before any UI is rendered. A small guard rejects production-instance creation responses that come back without active_domain; this required loosening active_domain to nullable in ProductionInstanceResponse so callers must check.

Test plumbing adds two mock injection flags on clerk deploy: --testFailCreateProductionInstanceExists and --testFailValidateCloningUnsupportedFeatures=<feature-list>. The mock layer in commands/deploy/mock.ts produces the corresponding PLAPI error envelopes so the new code paths can be exercised end-to-end without hitting a real Platform API. The deploy README.md gains a "Recovery paths" section documenting both error codes and the wizard's response.

Test plan

bun run scripts/run-tests.ts --pattern 'packages/cli-core/src/commands/deploy/**' --concurrency 1
bun run typecheck
bun run lint
CI green

wyattjoh · 2026-05-13T22:30:11Z

Stack: api-errors-and-deploy

refactor(errors): expose structured Clerk error fields on ApiError subclasses #288
- feat(deploy): added deploy wizard #260
  - feat(deploy): recover from production_instance_exists and surface plan-feature errors #289 👈 this PR

Part of a stacked-prs chain. Do not merge manually.

changeset-bot · 2026-05-13T22:30:12Z

🦋 Changeset detected

Latest commit: fae8e67

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 1 package

Name	Type
clerk	Minor

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

… fields

Replace formatApiBody(body: string) with formatApiBody(error: ApiError), deleting extractApiErrorCode, extractApiErrors, and formatSingleError. The new formatStructuredError reads code/message/meta directly from the parsed ApiError instance. The agent path builds ApiErrorEntry inline from structured fields and surfaces clerkTraceId in verbose human mode. Tests updated to construct ApiError instances and reflect single-error output for multi-error bodies.

- Preserve completed providers when pausing OAuth setup mid-loop, so `clerk deploy --continue` can finish multi-provider stacks. - Surface a warning for OAuth providers enabled in dev that the wizard does not yet support, instead of silently skipping them. - Close the gutter as Paused (not Failed) when DNS verification times out, since the state is recoverable via --continue. - Tighten the production-domain regex to reject malformed inputs like example..com or example-.com before they reach the API.

Move deploy lifecycle endpoint wrappers into the shared PLAPI client while routing the deploy wizard through a command-local adapter that defaults to mocked operations until the backend endpoints are ready.

…ceParams

…plan features

…e state

…ures When validateCloning returns HTTP 402 with code unsupported_subscription_plan_features, rethrow a CliError whose message lists the unsupported features from meta.unsupported_features and includes a docs URL hint pointing at clerk.com/docs/billing/plans.

wyattjoh · 2026-05-21T15:56:12Z

Closing in favor of #260. The error-recovery work (HTTP 409 production_instance_exists + HTTP 402 unsupported_subscription_plan_features) landed on the parent PR via the dedicated errors.ts mapping module (commands/deploy/errors.ts), which covers a broader set of PLAPI error codes than this branch originally proposed. The two remaining defensive cleanups from this branch — typing active_domain as nullable with a runtime guard, and dropping the unused is_secondary field — have been folded into #260.

wyattjoh · 2026-05-13T22:30:05Z

Summary

Adds two live-error recovery paths in clerk deploy and the small refactors that make them readable. When production-instance creation returns production_instance_exists (HTTP 400) the wizard now refetches the application, persists the existing production instance id, and jumps straight into the reconcile flow as if local state had been intact. When clone validation returns unsupported_subscription_plan_features (HTTP 402) the wizard rethrows a CliError that lists the unsupported features from error.meta.unsupported_features and points at the billing-plans docs.

Details

createProductionInstance is wrapped in a try/catch that branches on the new structured PlapiError.code. On production_instance_exists, reloadProductionState calls fetchApplication, finds the existing production instance, persists its id, and returns an updated DeployContext; the wizard then calls reconcileExistingDeploy and returns, so subsequent runs short-circuit. runValidateCloning is wrapped similarly to translate the plan-features error before any UI is rendered. A small guard rejects production-instance creation responses that come back without active_domain; this required loosening active_domain to nullable in ProductionInstanceResponse so callers must check.

Test plumbing adds two mock injection flags on clerk deploy: --testFailCreateProductionInstanceExists and --testFailValidateCloningUnsupportedFeatures=<feature-list>. The mock layer in commands/deploy/mock.ts produces the corresponding PLAPI error envelopes so the new code paths can be exercised end-to-end without hitting a real Platform API. The deploy README.md gains a "Recovery paths" section documenting both error codes and the wizard's response.

Test plan

bun run scripts/run-tests.ts --pattern 'packages/cli-core/src/commands/deploy/**' --concurrency 1
bun run typecheck
bun run lint
CI green

wyattjoh · 2026-05-13T22:30:11Z

Stack: api-errors-and-deploy

refactor(errors): expose structured Clerk error fields on ApiError subclasses #288
- feat(deploy): added deploy wizard #260
  - feat(deploy): recover from production_instance_exists and surface plan-feature errors #289 👈 this PR

Part of a stacked-prs chain. Do not merge manually.

changeset-bot · 2026-05-13T22:30:12Z

🦋 Changeset detected

Latest commit: fae8e67

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 1 package

Name	Type
clerk	Minor

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

… fields

Replace formatApiBody(body: string) with formatApiBody(error: ApiError), deleting extractApiErrorCode, extractApiErrors, and formatSingleError. The new formatStructuredError reads code/message/meta directly from the parsed ApiError instance. The agent path builds ApiErrorEntry inline from structured fields and surfaces clerkTraceId in verbose human mode. Tests updated to construct ApiError instances and reflect single-error output for multi-error bodies.

- Preserve completed providers when pausing OAuth setup mid-loop, so `clerk deploy --continue` can finish multi-provider stacks. - Surface a warning for OAuth providers enabled in dev that the wizard does not yet support, instead of silently skipping them. - Close the gutter as Paused (not Failed) when DNS verification times out, since the state is recoverable via --continue. - Tighten the production-domain regex to reject malformed inputs like example..com or example-.com before they reach the API.

Move deploy lifecycle endpoint wrappers into the shared PLAPI client while routing the deploy wizard through a command-local adapter that defaults to mocked operations until the backend endpoints are ready.

…ceParams

…plan features

…e state

…ures When validateCloning returns HTTP 402 with code unsupported_subscription_plan_features, rethrow a CliError whose message lists the unsupported features from meta.unsupported_features and includes a docs URL hint pointing at clerk.com/docs/billing/plans.

wyattjoh · 2026-05-21T15:56:12Z

Closing in favor of #260. The error-recovery work (HTTP 409 production_instance_exists + HTTP 402 unsupported_subscription_plan_features) landed on the parent PR via the dedicated errors.ts mapping module (commands/deploy/errors.ts), which covers a broader set of PLAPI error codes than this branch originally proposed. The two remaining defensive cleanups from this branch — typing active_domain as nullable with a runtime guard, and dropping the unused is_secondary field — have been folded into #260.

wyattjoh · 2026-05-13T22:30:05Z

Summary

Adds two live-error recovery paths in clerk deploy and the small refactors that make them readable. When production-instance creation returns production_instance_exists (HTTP 400) the wizard now refetches the application, persists the existing production instance id, and jumps straight into the reconcile flow as if local state had been intact. When clone validation returns unsupported_subscription_plan_features (HTTP 402) the wizard rethrows a CliError that lists the unsupported features from error.meta.unsupported_features and points at the billing-plans docs.

Details

createProductionInstance is wrapped in a try/catch that branches on the new structured PlapiError.code. On production_instance_exists, reloadProductionState calls fetchApplication, finds the existing production instance, persists its id, and returns an updated DeployContext; the wizard then calls reconcileExistingDeploy and returns, so subsequent runs short-circuit. runValidateCloning is wrapped similarly to translate the plan-features error before any UI is rendered. A small guard rejects production-instance creation responses that come back without active_domain; this required loosening active_domain to nullable in ProductionInstanceResponse so callers must check.

Test plumbing adds two mock injection flags on clerk deploy: --testFailCreateProductionInstanceExists and --testFailValidateCloningUnsupportedFeatures=<feature-list>. The mock layer in commands/deploy/mock.ts produces the corresponding PLAPI error envelopes so the new code paths can be exercised end-to-end without hitting a real Platform API. The deploy README.md gains a "Recovery paths" section documenting both error codes and the wizard's response.

Test plan

bun run scripts/run-tests.ts --pattern 'packages/cli-core/src/commands/deploy/**' --concurrency 1
bun run typecheck
bun run lint
CI green

wyattjoh · 2026-05-13T22:30:11Z

Stack: api-errors-and-deploy

refactor(errors): expose structured Clerk error fields on ApiError subclasses #288
- feat(deploy): added deploy wizard #260
  - feat(deploy): recover from production_instance_exists and surface plan-feature errors #289 👈 this PR

Part of a stacked-prs chain. Do not merge manually.

changeset-bot · 2026-05-13T22:30:12Z

🦋 Changeset detected

Latest commit: fae8e67

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 1 package

Name	Type
clerk	Minor

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

… fields

Replace formatApiBody(body: string) with formatApiBody(error: ApiError), deleting extractApiErrorCode, extractApiErrors, and formatSingleError. The new formatStructuredError reads code/message/meta directly from the parsed ApiError instance. The agent path builds ApiErrorEntry inline from structured fields and surfaces clerkTraceId in verbose human mode. Tests updated to construct ApiError instances and reflect single-error output for multi-error bodies.

- Preserve completed providers when pausing OAuth setup mid-loop, so `clerk deploy --continue` can finish multi-provider stacks. - Surface a warning for OAuth providers enabled in dev that the wizard does not yet support, instead of silently skipping them. - Close the gutter as Paused (not Failed) when DNS verification times out, since the state is recoverable via --continue. - Tighten the production-domain regex to reject malformed inputs like example..com or example-.com before they reach the API.

Move deploy lifecycle endpoint wrappers into the shared PLAPI client while routing the deploy wizard through a command-local adapter that defaults to mocked operations until the backend endpoints are ready.

…ceParams

…plan features

…e state

…ures When validateCloning returns HTTP 402 with code unsupported_subscription_plan_features, rethrow a CliError whose message lists the unsupported features from meta.unsupported_features and includes a docs URL hint pointing at clerk.com/docs/billing/plans.

wyattjoh · 2026-05-21T15:56:12Z

Closing in favor of #260. The error-recovery work (HTTP 409 production_instance_exists + HTTP 402 unsupported_subscription_plan_features) landed on the parent PR via the dedicated errors.ts mapping module (commands/deploy/errors.ts), which covers a broader set of PLAPI error codes than this branch originally proposed. The two remaining defensive cleanups from this branch — typing active_domain as nullable with a runtime guard, and dropping the unused is_secondary field — have been folded into #260.

wyattjoh · 2026-05-13T22:30:05Z

Summary

Adds two live-error recovery paths in clerk deploy and the small refactors that make them readable. When production-instance creation returns production_instance_exists (HTTP 400) the wizard now refetches the application, persists the existing production instance id, and jumps straight into the reconcile flow as if local state had been intact. When clone validation returns unsupported_subscription_plan_features (HTTP 402) the wizard rethrows a CliError that lists the unsupported features from error.meta.unsupported_features and points at the billing-plans docs.

Details

createProductionInstance is wrapped in a try/catch that branches on the new structured PlapiError.code. On production_instance_exists, reloadProductionState calls fetchApplication, finds the existing production instance, persists its id, and returns an updated DeployContext; the wizard then calls reconcileExistingDeploy and returns, so subsequent runs short-circuit. runValidateCloning is wrapped similarly to translate the plan-features error before any UI is rendered. A small guard rejects production-instance creation responses that come back without active_domain; this required loosening active_domain to nullable in ProductionInstanceResponse so callers must check.

Test plumbing adds two mock injection flags on clerk deploy: --testFailCreateProductionInstanceExists and --testFailValidateCloningUnsupportedFeatures=<feature-list>. The mock layer in commands/deploy/mock.ts produces the corresponding PLAPI error envelopes so the new code paths can be exercised end-to-end without hitting a real Platform API. The deploy README.md gains a "Recovery paths" section documenting both error codes and the wizard's response.

Test plan

bun run scripts/run-tests.ts --pattern 'packages/cli-core/src/commands/deploy/**' --concurrency 1
bun run typecheck
bun run lint
CI green

wyattjoh · 2026-05-13T22:30:11Z

Stack: api-errors-and-deploy

refactor(errors): expose structured Clerk error fields on ApiError subclasses #288
- feat(deploy): added deploy wizard #260
  - feat(deploy): recover from production_instance_exists and surface plan-feature errors #289 👈 this PR

Part of a stacked-prs chain. Do not merge manually.

changeset-bot · 2026-05-13T22:30:12Z

🦋 Changeset detected

Latest commit: fae8e67

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 1 package

Name	Type
clerk	Minor

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

… fields

Replace formatApiBody(body: string) with formatApiBody(error: ApiError), deleting extractApiErrorCode, extractApiErrors, and formatSingleError. The new formatStructuredError reads code/message/meta directly from the parsed ApiError instance. The agent path builds ApiErrorEntry inline from structured fields and surfaces clerkTraceId in verbose human mode. Tests updated to construct ApiError instances and reflect single-error output for multi-error bodies.

- Preserve completed providers when pausing OAuth setup mid-loop, so `clerk deploy --continue` can finish multi-provider stacks. - Surface a warning for OAuth providers enabled in dev that the wizard does not yet support, instead of silently skipping them. - Close the gutter as Paused (not Failed) when DNS verification times out, since the state is recoverable via --continue. - Tighten the production-domain regex to reject malformed inputs like example..com or example-.com before they reach the API.

Move deploy lifecycle endpoint wrappers into the shared PLAPI client while routing the deploy wizard through a command-local adapter that defaults to mocked operations until the backend endpoints are ready.

…ceParams

…plan features

…e state

…ures When validateCloning returns HTTP 402 with code unsupported_subscription_plan_features, rethrow a CliError whose message lists the unsupported features from meta.unsupported_features and includes a docs URL hint pointing at clerk.com/docs/billing/plans.

wyattjoh · 2026-05-21T15:56:12Z

Closing in favor of #260. The error-recovery work (HTTP 409 production_instance_exists + HTTP 402 unsupported_subscription_plan_features) landed on the parent PR via the dedicated errors.ts mapping module (commands/deploy/errors.ts), which covers a broader set of PLAPI error codes than this branch originally proposed. The two remaining defensive cleanups from this branch — typing active_domain as nullable with a runtime guard, and dropping the unused is_secondary field — have been folded into #260.

This was referenced May 13, 2026
refactor(errors): expose structured Clerk error fields on ApiError subclasses #288
Merged
feat(deploy): added deploy wizard #260
Merged

wyattjoh changed the title ~~wyattjoh/deploy error recovery~~feat(deploy): recover from production_instance_exists and surface plan-feature errorsMay 13, 2026

wyattjoh added 25 commits May 19, 2026 07:55

refactor(errors): parse Clerk error envelope into structured ApiError…
91a6fe0
… fields

feat(errors): add fromResponse factories to ApiError subclasses
8dfb8b5

refactor(plapi): construct PlapiError via fromResponse
9ab0662

refactor(fapi): construct FapiError via fromResponse
c90bf4f

refactor(keyless): construct BapiError via fromResponse
1ae6d36

refactor(bapi): construct BapiError via fromResponse
0090584

refactor(users): construct BapiError via fromResponse
f352c6f

test: construct ApiError subclasses via fromBody in fixtures
4f9ddc2

feat(deploy): implement resumable deploy wizard
5466ad3

refactor(deploy): isolate lifecycle api calls
3847ef2
Move deploy lifecycle endpoint wrappers into the shared PLAPI client while routing the deploy wizard through a command-local adapter that defaults to mocked operations until the backend endpoints are ready.

feat(deploy): resolve production state from API
50cf7ea

fix(deploy): route test failures through api path
5c766e6

fix(deploy): remove gutter tone plumbing
e830ef6

fix(deploy): require human mode for production setup
61e1dc3

refactor(deploy): route lifecycle test failures through api mock
9c99950

refactor(deploy): extract mock api into its own module
371a082

refactor(deploy): construct simulated PlapiError via fromBody
c878c51

refactor(plapi): drop unused is_secondary from CreateProductionInstan…
0b70486
…ceParams

feat(deploy/mock): inject production_instance_exists and unsupported …
0fd13de
…plan features

feat(deploy): recover from production_instance_exists by resuming liv…
3cbc0c5
…e state

refactor(plapi): allow null active_domain and guard in deploy wizard
9218f4a

docs(deploy): document live-error recovery paths and add changeset
fae8e67

wyattjoh force-pushed the wyattjoh/deploy-error-recovery branch from ce49854 to fae8e67Compare May 19, 2026 13:55

wyattjoh force-pushed the wyattjoh/deploy branch 3 times, most recently from a3d8b46 to 7e6819cCompare May 21, 2026 15:26

wyattjoh closed this May 21, 2026

wyattjoh deleted the wyattjoh/deploy-error-recovery branch May 21, 2026 15:56