fix(api): address review feedback on --fapi passthrough

- Move dry-run check before resolveFapiHost so --fapi --dry-run avoids
  the Platform API round-trip; shows <fapi-host> placeholder instead
- Import CLERK_JS_API_VERSION from lib/fapi.ts instead of redeclaring it
- Warn when --secret-key is provided with --fapi (key is ignored)
- Add tests: --fapi no-app NOT_LINKED error, /environment and
  /v1/environment path normalization, --secret-key warning, --dry-run
  no network call

Author: rafa-thayto

packages/cli-core/src/commands/api/fapi.ts

@@ -15,14 +15,11 @@ import {
   throwUsageError,
   withApiContext,
 } from "../../lib/errors.ts";
-import { decodePublishableKey } from "../../lib/fapi.ts";
+import { decodePublishableKey, CLERK_JS_API_VERSION } from "../../lib/fapi.ts";
 import { loggedFetch } from "../../lib/fetch.ts";
 import { fetchApplication, type ApplicationInstance } from "../../lib/plapi.ts";
 import type { BapiResponse } from "./bapi.ts";
 
-/** clerk-js API version FAPI shapes its `/v1/environment` payload for. */
-const CLERK_JS_API_VERSION = "5";
-
 interface ResolveOptions {
   app?: string;
   instance?: string;

packages/cli-core/src/commands/api/index.test.ts

@@ -542,6 +542,77 @@ describe("api command", () => {
     expect(captured.out).toContain(JSON.stringify(errorBody, null, 2));
   });
 
+  test("--fapi without --app and no linked project errors with NOT_LINKED guidance", async () => {
+    delete process.env.CLERK_SECRET_KEY;
+
+    await expect(runApi("/environment", { fapi: true })).rejects.toThrow(/clerk link|--app/);
+  });
+
+  test.each([
+    ["/environment", "/v1/environment"],
+    ["/v1/environment", "/v1/environment"],
+  ])("--fapi: %s resolves to the same FAPI path %s", async (input, expectedPath) => {
+    process.env.CLERK_PLATFORM_API_KEY = "ak_test_platform";
+    const pk = `pk_test_${btoa("clerk.example.com$")}`;
+    let capturedPath = "";
+
+    stubFetch(async (input) => {
+      const url = input.toString();
+      if (url.includes("/v1/platform/applications/app_1")) {
+        return new Response(
+          JSON.stringify({
+            application_id: "app_1",
+            instances: [
+              { instance_id: "ins_dev", environment_type: "development", publishable_key: pk },
+            ],
+          }),
+          { status: 200 },
+        );
+      }
+      capturedPath = new URL(url).pathname;
+      return new Response(JSON.stringify({}), { status: 200 });
+    });
+
+    await runApi(input, { fapi: true, app: "app_1" });
+    expect(capturedPath).toBe(expectedPath);
+  });
+
+  test("--fapi + --secret-key emits a warning that --secret-key is ignored", async () => {
+    process.env.CLERK_PLATFORM_API_KEY = "ak_test_platform";
+    const pk = `pk_test_${btoa("clerk.example.com$")}`;
+
+    stubFetch(async (input) => {
+      const url = input.toString();
+      if (url.includes("/v1/platform/applications/app_1")) {
+        return new Response(
+          JSON.stringify({
+            application_id: "app_1",
+            instances: [
+              { instance_id: "ins_dev", environment_type: "development", publishable_key: pk },
+            ],
+          }),
+          { status: 200 },
+        );
+      }
+      return new Response(JSON.stringify({}), { status: 200 });
+    });
+
+    await runApi("/environment", { fapi: true, app: "app_1", secretKey: "sk_test_ignored" });
+    expect(captured.err).toMatch(/--secret-key is ignored/);
+  });
+
+  test("--fapi + --dry-run does not make any network request", async () => {
+    let fetchCalled = false;
+    stubFetch(async () => {
+      fetchCalled = true;
+      return new Response(JSON.stringify({}), { status: 200 });
+    });
+
+    await runApi("/environment", { fapi: true, app: "app_1", dryRun: true });
+    expect(fetchCalled).toBe(false);
+    expect(captured.err).toContain("[dry-run] GET <fapi-host>");
+  });
+
   // --- Error handling ---
 
   test("errors when no secret key available", async () => {

packages/cli-core/src/commands/api/index.ts

@@ -35,18 +35,21 @@ const MUTATING_METHODS = new Set(["POST", "PUT", "PATCH", "DELETE"]);
 
 type RunRequest = (req: { method: string; path: string; body?: string }) => Promise<BapiResponse>;
 
+/** Validate fapi flag combinations and emit warnings for ignored flags. */
+function validateFapiOptions(options: ApiOptions): void {
+  if (options.platform) {
+    throwUsageError("--fapi and --platform cannot be combined.", undefined, ERROR_CODE.USAGE_ERROR);
+  }
+  if (options.secretKey) {
+    log.warn("--secret-key is ignored when --fapi is set.");
+  }
+}
+
 /** Resolve the API surface (base URL + request executor) from the flags. */
 async function resolveApiTarget(
   options: ApiOptions,
 ): Promise<{ baseUrl: string; runRequest: RunRequest }> {
   if (options.fapi) {
-    if (options.platform) {
-      throwUsageError(
-        "--fapi and --platform cannot be combined.",
-        undefined,
-        ERROR_CODE.USAGE_ERROR,
-      );
-    }
     const fapiHost = await resolveFapiHost(options);
     const baseUrl = `https://${fapiHost}`;
     return { baseUrl, runRequest: (req) => fapiRequest({ ...req, fapiHost }) };
@@ -93,18 +96,27 @@ export async function api(
     // 2. Determine HTTP method
     const method = (options.method ?? (body ? "POST" : "GET")).toUpperCase();
 
-    // 3. Resolve the request target (base URL + executor)
-    const { baseUrl, runRequest } = await resolveApiTarget(options);
-
-    // 4. Dry run
+    // 3. Dry run — for --fapi, skip host resolution to avoid a real Platform API round-trip
     if (options.dryRun) {
-      log.info(`[dry-run] ${method} ${baseUrl}${normalizeBapiPath(endpoint)}`);
+      if (options.fapi) {
+        validateFapiOptions(options);
+        log.info(`[dry-run] ${method} <fapi-host>${normalizeBapiPath(endpoint)}`);
+      } else {
+        const { baseUrl } = await resolveApiTarget(options);
+        log.info(`[dry-run] ${method} ${baseUrl}${normalizeBapiPath(endpoint)}`);
+      }
       if (body) {
         prettyPrint(body);
       }
       return;
     }
 
+    // 4. Resolve the request target (base URL + executor)
+    if (options.fapi) {
+      validateFapiOptions(options);
+    }
+    const { runRequest } = await resolveApiTarget(options);
+
     // 5. Confirmation for mutating methods
     if (MUTATING_METHODS.has(method) && isHuman() && !options.yes) {
       log.info(`\nAbout to ${method} ${endpoint}`);

packages/cli-core/src/lib/fapi.ts

@@ -15,7 +15,7 @@ const PK_LIVE_PREFIX = "pk_live_";
  * The clerk-js client version FAPI's `/v1/environment` payload is shaped for.
  * Bump when consuming response fields introduced in a later major version.
  */
-const CLERK_JS_API_VERSION = "5";
+export const CLERK_JS_API_VERSION = "5";
 
 export type InstanceType = "development" | "production";