feat(deploy): recover from production_instance_exists and surface plan-feature errors

.changeset/deploy-error-recovery.md

@@ -0,0 +1,5 @@
+---
+"clerk": minor
+---
+
+Surface Clerk API error codes and metadata as structured fields on `PlapiError` / `BapiError` / `FapiError`, and use them to add two recovery paths in `clerk deploy`: resume from server state when a production instance already exists, and present a friendly upgrade hint when the development instance uses features the current subscription plan doesn't allow.

packages/cli-core/src/cli-program.test.ts

@@ -3,6 +3,7 @@ import { mkdtempSync, mkdirSync, writeFileSync, rmSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { dirname, join } from "node:path";
 import { createProgram, formatApiBody } from "./cli-program.ts";
+import { ApiError } from "./lib/errors.ts";
 import { STANDARD_AGENT_DIRS, EXTRA_REL_PATHS } from "./lib/skill-detection.ts";
 
 test("registers users as a top-level command", () => {
@@ -44,6 +45,23 @@ test("users list exposes common filters and pagination options", () => {
   );
 });
 
+test("deploy exposes the expected options", () => {
+  const program = createProgram();
+  const deploy = program.commands.find((command) => command.name() === "deploy")!;
+  const optionNames = deploy.options.map((option) => option.long);
+
+  expect(optionNames).toEqual([
+    "--debug",
+    "--test-force-production-instance",
+    "--test-fail-production-instance-check",
+    "--test-fail-domain-lookup",
+    "--test-fail-validate-cloning",
+    "--test-fail-create-production-instance",
+    "--test-fail-dns-verification",
+    "--test-fail-oauth-save",
+  ]);
+});
+
 describe("parseIntegerOption (via users list --limit / --offset)", () => {
   function parseUsersList(args: readonly string[]) {
     return createProgram().parseAsync(["users", "list", ...args], { from: "user" });
@@ -140,7 +158,7 @@ describe("formatApiBody", () => {
         },
       ],
     });
-    const result = formatApiBody(body, false);
+    const result = formatApiBody(new ApiError(400, body), false);
     expect(result).toContain("Your plan does not support these features");
     expect(result).toContain("Unsupported features: saml, custom_roles");
   });
@@ -155,7 +173,7 @@ describe("formatApiBody", () => {
         },
       ],
     });
-    const result = formatApiBody(body, false);
+    const result = formatApiBody(new ApiError(400, body), false);
     expect(result).toContain("Unknown config key: sesion");
     expect(result).toContain("Did you mean: session");
     expect(result).toContain("Parameter: sesion");
@@ -171,7 +189,7 @@ describe("formatApiBody", () => {
         },
       ],
     });
-    const result = formatApiBody(body, false);
+    const result = formatApiBody(new ApiError(400, body), false);
     expect(result).toContain("This feature is not enabled on this instance");
     expect(result).toContain("Feature: organizations");
   });
@@ -186,7 +204,7 @@ describe("formatApiBody", () => {
         },
       ],
     });
-    const result = formatApiBody(body, false);
+    const result = formatApiBody(new ApiError(400, body), false);
     expect(result).toContain("Invalid value for session.lifetime");
     expect(result).toContain("Parameter: session.lifetime");
   });
@@ -201,7 +219,7 @@ describe("formatApiBody", () => {
         },
       ],
     });
-    const result = formatApiBody(body, false);
+    const result = formatApiBody(new ApiError(400, body), false);
     expect(result).toContain("Cannot clear this key");
     expect(result).toContain("Parameter: sign_up.mode");
   });
@@ -216,14 +234,15 @@ describe("formatApiBody", () => {
         },
       ],
     });
-    const result = formatApiBody(body, false);
+    const result = formatApiBody(new ApiError(400, body), false);
     expect(result).toContain("Value is not in the allowed set");
     expect(result).toContain("Parameter: branding.logo_url");
   });
 
   // --- Multiple errors ---
+  // The structured path reads from the first parsed error only.
 
-  test("formats multiple errors joined by newlines", () => {
+  test("formats multiple errors: surfaces first error with its meta", () => {
     const body = JSON.stringify({
       errors: [
         {
@@ -238,13 +257,9 @@ describe("formatApiBody", () => {
         },
       ],
     });
-    const result = formatApiBody(body, false);
+    const result = formatApiBody(new ApiError(400, body), false);
     expect(result).toContain("Invalid session lifetime");
-    expect(result).toContain("Unknown key: bogus");
-    expect(result).toContain("Did you mean: session");
-    // Two errors separated by newline
-    const lines = result.split("\n");
-    expect(lines.length).toBeGreaterThanOrEqual(2);
+    expect(result).toContain("Parameter: session.lifetime");
   });
 
   // --- Error without meta ---
@@ -253,32 +268,34 @@ describe("formatApiBody", () => {
     const body = JSON.stringify({
       errors: [{ code: "resource_not_found", message: "Instance not found" }],
     });
-    const result = formatApiBody(body, false);
+    const result = formatApiBody(new ApiError(400, body), false);
     expect(result).toBe("Instance not found");
   });
 
-  // --- Fallback paths ---
+  // --- Bodies without a Clerk errors array ---
+  // parseApiBody falls back to truncateBody(body) as the message when there
+  // is no errors[0], so formatStructuredError returns the truncated body string.
 
-  test("falls back to parsed.error when no errors array", () => {
+  test("returns truncated body when no errors array (error field only)", () => {
     const body = JSON.stringify({ error: "Something went wrong" });
-    const result = formatApiBody(body, false);
-    expect(result).toBe("Something went wrong");
+    const result = formatApiBody(new ApiError(400, body), false);
+    expect(result).toBe(body);
   });
 
-  test("falls back to parsed.message when no errors array or error field", () => {
+  test("returns truncated body when no errors array (message field only)", () => {
     const body = JSON.stringify({ message: "Bad request" });
-    const result = formatApiBody(body, false);
-    expect(result).toBe("Bad request");
+    const result = formatApiBody(new ApiError(400, body), false);
+    expect(result).toBe(body);
   });
 
   test("truncates non-JSON body over 200 chars", () => {
     const body = "x".repeat(300);
-    const result = formatApiBody(body, false);
+    const result = formatApiBody(new ApiError(400, body), false);
     expect(result).toBe("x".repeat(200) + "...");
   });
 
   test("returns short non-JSON body as-is", () => {
-    const result = formatApiBody("Bad Request", false);
+    const result = formatApiBody(new ApiError(400, "Bad Request"), false);
     expect(result).toBe("Bad Request");
   });
 
@@ -287,28 +304,29 @@ describe("formatApiBody", () => {
   test("verbose mode returns full pretty-printed JSON", () => {
     const obj = { errors: [{ code: "test", message: "test msg" }] };
     const body = JSON.stringify(obj);
-    const result = formatApiBody(body, true);
+    const result = formatApiBody(new ApiError(400, body), true);
     expect(result).toBe("\n" + JSON.stringify(obj, null, 2));
   });
 
   test("verbose mode returns raw body for non-JSON", () => {
-    const result = formatApiBody("not json", true);
+    const result = formatApiBody(new ApiError(400, "not json"), true);
     expect(result).toBe("\nnot json");
   });
 
   // --- Edge cases ---
 
-  test("handles empty errors array by falling through", () => {
+  test("handles empty errors array by returning truncated body", () => {
     const body = JSON.stringify({ errors: [], message: "fallback" });
-    const result = formatApiBody(body, false);
-    expect(result).toBe("fallback");
+    const result = formatApiBody(new ApiError(400, body), false);
+    // No errors[0] so parseApiBody falls back to truncateBody(body)
+    expect(result).toBe(body);
   });
 
   test("handles error with empty meta", () => {
     const body = JSON.stringify({
       errors: [{ code: "config_validation_error", message: "Bad value", meta: {} }],
     });
-    const result = formatApiBody(body, false);
+    const result = formatApiBody(new ApiError(400, body), false);
     expect(result).toBe("Bad value");
   });
 
@@ -322,7 +340,7 @@ describe("formatApiBody", () => {
         },
       ],
     });
-    const result = formatApiBody(body, false);
+    const result = formatApiBody(new ApiError(400, body), false);
     expect(result).toBe("Plan limitation");
   });
 });