feat(deploy): added deploy wizard

[wyattjoh]

Summary

Adds clerk deploy, an interactive wizard that promotes a linked Clerk application from development to production. The wizard validates clone compatibility, creates the production instance and primary domain, walks the user through the returned CNAME records (with optional BIND zone export to ./clerk-<domain>.zone), verifies DNS/SSL/mail with a per-component spinner chain, and collects production OAuth credentials for Google, GitHub, Microsoft, Apple, and Linear.

State is derived from the Platform API on each run, not persisted locally. The wizard reads the live application, domains, deploy status, and instance config on entry and resumes from the next pending step. The only profile write is instances.production once the production instance exists. Pressing Ctrl-C or picking "Skip" at an OAuth provider exits with Deploy paused and exit code 1; rerunning resumes from whatever the API now reports.

Platform API errors specific to the deploy lifecycle are mapped to typed CliErrors in commands/deploy/errors.ts (unsupported plan features, provider/taken domains, production_instance_exists recovery, SSL/mail retry throttles). The wizard refuses to start in agent mode because production configuration is interactive.

Test plan

• bun run format:check
• bun run lint
• bun run typecheck
• bun run test
• bun run test:e2e:op
• Manual smoke: unlinked directory exits with error: No Clerk project linked; linked directory walks through create → DNS records → BIND export → verification → OAuth → production summary; Ctrl-C at OAuth exits with Deploy paused and exit code 1; rerun resumes at the skipped provider.

[changeset-bot]

🦋 Changeset detected

Latest commit: fa5821c

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

[wyattjoh]

!snapshot

[github-actions]

Snapshot published

npm install -g clerk@1.3.1-snapshot.0dd30be

Package	Version
clerk	1.3.1-snapshot.0dd30be

Published from 0dd30be

[wyattjoh]

Stack: wyattjoh/deploy

• feat(deploy): added deploy wizard #260 👈 this PR

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

[coderabbitai]

Actionable comments posted: 1

🧹 Nitpick comments (1)

scripts/cleanup-test-users.test.ts (1)

11-28: ⚡ Quick win

Consider simplifying the mock pattern.

The current mock reads its own call count via mock.calls.length, which creates a circular type reference requiring the complex casting chain. A simpler approach uses a closure variable:

♻️ Simpler mock pattern

  test("retries transient Platform API failures before returning JSON", async () => {
+   let attempts = 0;
    globalThis.fetch = mock(async () => {
-     const attempts = (globalThis.fetch as unknown as ReturnType<typeof mock>).mock.calls.length;
+     attempts++;
      if (attempts === 1) {
        return new Response("temporary failure", { status: 500 });
      }

      return Response.json({ instances: [] });
-   }) as unknown as typeof fetch;
+   }) as typeof fetch;

    const result = await plapiGet("/v1/platform/applications/app_123", "ak_test", {
      delayMs: 0,
    });

    expect(result).toEqual({ instances: [] });
    expect(globalThis.fetch).toHaveBeenCalledTimes(2);
  });

🤖 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 `@scripts/cleanup-test-users.test.ts` around lines 11 - 28, The mock for
globalThis.fetch is overcomplicated by reading its own mock.calls.length
(causing the cast chain); change the mock in the test "retries transient
Platform API failures before returning JSON" to use a closure-scoped counter
variable (e.g., let attempts = 0) that you increment each invocation inside the
mock instead of querying (globalThis.fetch as ...).mock.calls.length, and keep
the existing behavior of returning a 500 on the first call and Response.json({
instances: [] }) thereafter so plapiGet is exercised and the expectation on call
count still holds.

🤖 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 `@packages/cli-core/src/commands/deploy/prompts.ts`:
- Around line 64-72: The retry prompt in chooseDnsVerificationRetryAction
currently lists "Skip DNS verification for now" first so Enter defaults to skip;
update chooseDnsVerificationRetryAction (returning DnsVerificationAction) to
make "Check again" the safe default by either placing the { name: "Check again",
value: "check" } choice first in the choices array and/or explicitly setting the
select helper's default/initial value to "check" (use the select API's
initial/default property for this prompt if available) so pressing Enter
triggers "check" not "skip".

---

Nitpick comments:
In `@scripts/cleanup-test-users.test.ts`:
- Around line 11-28: The mock for globalThis.fetch is overcomplicated by reading
its own mock.calls.length (causing the cast chain); change the mock in the test
"retries transient Platform API failures before returning JSON" to use a
closure-scoped counter variable (e.g., let attempts = 0) that you increment each
invocation inside the mock instead of querying (globalThis.fetch as
...).mock.calls.length, and keep the existing behavior of returning a 500 on the
first call and Response.json({ instances: [] }) thereafter so plapiGet is
exercised and the expectation on call count still holds.

🪄 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: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: 20ba068c-6400-4d41-a9d3-8f51af568904

📥 Commits

Reviewing files that changed from the base of the PR and between f65cea4 and c735a0b.

📒 Files selected for processing (21)

• .changeset/deploy-wizard.md
• .claude/rules/logging.md
• packages/cli-core/src/cli-program.test.ts
• packages/cli-core/src/cli-program.ts
• packages/cli-core/src/commands/auth/login.ts
• packages/cli-core/src/commands/deploy/README.md
• packages/cli-core/src/commands/deploy/copy.test.ts
• packages/cli-core/src/commands/deploy/copy.ts
• packages/cli-core/src/commands/deploy/errors.ts
• packages/cli-core/src/commands/deploy/index.test.ts
• packages/cli-core/src/commands/deploy/index.ts
• packages/cli-core/src/commands/deploy/prompts.ts
• packages/cli-core/src/commands/deploy/providers.test.ts
• packages/cli-core/src/commands/deploy/providers.ts
• packages/cli-core/src/lib/errors.ts
• packages/cli-core/src/lib/plapi.test.ts
• packages/cli-core/src/lib/plapi.ts
• packages/cli-core/src/lib/spinner.test.ts
• packages/cli-core/src/lib/spinner.ts
• scripts/cleanup-test-users.test.ts
• scripts/cleanup-test-users.ts

💤 Files with no reviewable changes (2)

• packages/cli-core/src/lib/errors.ts
• packages/cli-core/src/commands/deploy/errors.ts

✅ Files skipped from review due to trivial changes (3)

• .claude/rules/logging.md
• packages/cli-core/src/commands/auth/login.ts
• .changeset/deploy-wizard.md

🚧 Files skipped from review as they are similar to previous changes (1)

• packages/cli-core/src/commands/deploy/copy.ts

[rafa-thayto]

retriesRemaining and nextRetryDelay live outside the component loop, so all three spinners share one budget. With the constants here (5 retries, 3s base, x2 backoff) that totals ~93s, and whichever component is checked first (mail) can spend all of it. Once it does, the dns and ssl spinners reach while (retriesRemaining > 0) with zero left and return false right away, reporting the domain as unverified even when one more poll would have flipped them. Give each component its own budget:

Suggested change

	let retriesRemaining = DEPLOY_STATUS_MAX_RETRIES;
	let nextRetryDelay = DEPLOY_STATUS_INITIAL_RETRY_DELAY_MS;
	for (const component of DEPLOY_COMPONENT_ORDER) {
	for (const component of DEPLOY_COMPONENT_ORDER) {
	let retriesRemaining = DEPLOY_STATUS_MAX_RETRIES;
	let nextRetryDelay = DEPLOY_STATUS_INITIAL_RETRY_DELAY_MS;

[rafa-thayto]

These three components handle a missing field three different ways. dns reads as pending when absent and ignores required entirely, ssl reads as pending when absent, but mail goes through checkStatusComplete where !undefined?.required is true, so an absent mail field reports as verified without ever being checked. Worth making all three uniform so the absent case means the same thing everywhere:

    dns: checkStatusComplete(response.dns),
    ssl: checkStatusComplete(response.ssl),
    mail: checkStatusComplete(response.mail),

That needs dns?: DomainCheckStatus in plapi.ts and checkStatusComplete taking { status: string; required?: boolean } | undefined. Decide whether an absent component should count as complete or pending and apply it in the one helper rather than per field.

[rafa-thayto]

loadProductionDomain and loadDevelopmentOAuthProviders both take only ctx and don't depend on each other, yet they run one after the other, adding a round trip to every resume run. Only loadProductionState needs domain.id, so the first two can go together:

  const [domain, oauth] = await Promise.all([
    loadProductionDomain(ctx),
    loadDevelopmentOAuthProviders(ctx),
  ]);
  if (!domain) return undefined;
  const { descriptors: oauthProviderDescriptors, unsupported } = oauth;

[rafa-thayto]

These five lookups (providerFields, providerCredentialLabel, providerRedirectLabel, providerSetupCopy, providerGotcha) repeat the same if (hasProviderOverride(provider)) return MAP[provider]; return default shape. A small generic collapses the repetition:

function fromOverride<T>(
  provider: OAuthProvider,
  map: Record<ProviderWithOverride, T>,
  fallback: T,
): T {
  return hasProviderOverride(provider) ? map[provider] : fallback;
}

export function providerFields(provider: OAuthProvider): OAuthField[] {
  return fromOverride(provider, PROVIDER_FIELDS, [
    { key: "client_id", label: "Client ID" },
    { key: "client_secret", label: "Client Secret", secret: true },
  ]);
}
// providerCredentialLabel / providerRedirectLabel / providerSetupCopy / providerGotcha follow the same shape.