convex 1.34.1 → 1.35.0

package/src/cli/deploymentSelect.test.ts

@@ -3,11 +3,11 @@ import path from "path";
 import { nodeFs } from "../bundler/fs.js";
 import { deploymentSelect } from "./deploymentSelect.js";
 import { bigBrainAPI, bigBrainAPIMaybeThrows } from "./lib/utils/utils.js";
-import { runSystemQuery } from "./lib/run.js";
 import { globalConfigPath } from "./lib/utils/globalConfig.js";
 
-// Mock typedPlatformClient GET function — can be configured per test
+// Mock GET functions — can be configured per test
 const mockPlatformGet = vi.fn();
+const mockDeploymentGet = vi.fn();
 
 // In-memory filesystem — populated in beforeEach, written to by real configure code
 let testFiles: Map<string, string>;
@@ -33,6 +33,7 @@ vi.mock("./lib/utils/utils.js", async (importOriginal) => {
     bigBrainAPI: vi.fn(),
     bigBrainAPIMaybeThrows: vi.fn(),
     typedPlatformClient: vi.fn(() => ({ GET: mockPlatformGet })),
+    typedDeploymentClient: vi.fn(() => ({ GET: mockDeploymentGet })),
   };
 });
 
@@ -49,9 +50,14 @@ vi.mock("@sentry/node", () => ({
   close: vi.fn(),
 }));
 
-vi.mock("./lib/run.js", () => ({
-  runSystemQuery: vi.fn(),
-}));
+vi.mock("./lib/localDeployment/run.js", async (importOriginal) => {
+  const actual =
+    await importOriginal<typeof import("./lib/localDeployment/run.js")>();
+  return {
+    ...actual,
+    fetchLocalBackendStatus: vi.fn().mockResolvedValue({ kind: "running" }),
+  };
+});
 
 /**
  * Routes mock Big Brain API calls by path.
@@ -72,10 +78,14 @@ function setupBigBrainRoutes(routes: Record<string, (data?: any) => any>) {
 
 describe("npx convex select", () => {
   let savedEnv: NodeJS.ProcessEnv;
+  let savedIsTTY: boolean | undefined;
 
   beforeEach(() => {
     savedEnv = { ...process.env };
+    savedIsTTY = process.stdin.isTTY;
     process.env = {};
+    // Default to interactive TTY for existing tests
+    process.stdin.isTTY = true as any;
 
     // Start with minimal filesystem: package.json for readProjectConfig fallback
     testFiles = new Map([[path.resolve("package.json"), "{}"]]);
@@ -103,10 +113,12 @@ describe("npx convex select", () => {
       },
     );
 
-    // runSystemQuery is called by fetchDeploymentCanonicalSiteUrl to look up CONVEX_SITE_URL
-    vi.mocked(runSystemQuery).mockResolvedValue({
-      name: "CONVEX_SITE_URL",
-      value: "https://example.convex.site",
+    // typedDeploymentClient GET is called by fetchDeploymentCanonicalUrls
+    mockDeploymentGet.mockResolvedValue({
+      data: {
+        convexCloudUrl: "https://example.convex.cloud",
+        convexSiteUrl: "https://example.convex.site",
+      },
     });
 
     // typedPlatformClient is used for reference-based deployment resolution
@@ -115,6 +127,7 @@ describe("npx convex select", () => {
 
   afterEach(() => {
     process.env = savedEnv;
+    process.stdin.isTTY = savedIsTTY as any;
   });
 
   // Suppress process.exit and stderr
@@ -182,20 +195,36 @@ describe("npx convex select", () => {
           teamId: 1,
           projectId: 1,
         }),
-        "deployment/provision_and_authorize": () => ({
+        "teams/my-team/projects/my-project/deployments": () => true,
+        "deployment/authorize_within_current_project": () => ({
           adminKey: "dev-key",
           url: "https://joyful-capybara-123.convex.cloud",
           deploymentName: "joyful-capybara-123",
           deploymentType: "dev",
         }),
       });
+      mockPlatformGet.mockResolvedValue({
+        data: { name: "joyful-capybara-123" },
+        error: undefined,
+      });
 
       await deploymentSelect.parseAsync(["dev"], { from: "user" });
 
-      expect(bigBrainAPIMaybeThrows).toHaveBeenCalledWith(
+      expect(mockPlatformGet).toHaveBeenCalledWith(
+        "/teams/{team_id_or_slug}/projects/{project_slug}/deployment",
         expect.objectContaining({
-          path: "deployment/provision_and_authorize",
-          data: expect.objectContaining({ deploymentType: "dev" }),
+          params: expect.objectContaining({
+            path: { team_id_or_slug: "my-team", project_slug: "my-project" },
+            query: { defaultDev: true },
+          }),
+        }),
+      );
+      expect(bigBrainAPI).toHaveBeenCalledWith(
+        expect.objectContaining({
+          path: "deployment/authorize_within_current_project",
+          data: expect.objectContaining({
+            selectedDeploymentName: "joyful-capybara-123",
+          }),
         }),
       );
       const envContent = testFiles.get(path.resolve(".env.local"))!;
@@ -345,7 +374,7 @@ describe("npx convex select", () => {
     });
 
     describe("side effects on successful selection", () => {
-      it("fetches the site URL using the resolved deployment credentials", async () => {
+      it("fetches the canonical URLs using the resolved deployment credentials", async () => {
         setupBigBrainRoutes({
           "deployment/joyful-capybara-123/team_and_project": () => ({
             team: "my-team",
@@ -353,29 +382,30 @@ describe("npx convex select", () => {
             teamId: 1,
             projectId: 1,
           }),
-          "deployment/provision_and_authorize": () => ({
+          "teams/my-team/projects/my-project/deployments": () => true,
+          "deployment/authorize_within_current_project": () => ({
             adminKey: "dev-key",
             url: "https://joyful-capybara-123.convex.cloud",
             deploymentName: "joyful-capybara-123",
             deploymentType: "dev",
           }),
         });
+        mockPlatformGet.mockResolvedValue({
+          data: { name: "joyful-capybara-123" },
+          error: undefined,
+        });
 
         await deploymentSelect.parseAsync(["dev"], { from: "user" });
 
-        expect(runSystemQuery).toHaveBeenCalledWith(
-          expect.anything(),
-          expect.objectContaining({
-            adminKey: "dev-key",
-            deploymentUrl: "https://joyful-capybara-123.convex.cloud",
-          }),
-        );
+        expect(mockDeploymentGet).toHaveBeenCalledWith("/get_canonical_urls");
       });
 
       it("writes the fetched site URL to the env file", async () => {
-        vi.mocked(runSystemQuery).mockResolvedValue({
-          name: "CONVEX_SITE_URL",
-          value: "https://joyful-capybara-123.convex.site",
+        mockDeploymentGet.mockResolvedValue({
+          data: {
+            convexCloudUrl: "https://joyful-capybara-123.convex.cloud",
+            convexSiteUrl: "https://joyful-capybara-123.convex.site",
+          },
         });
         setupBigBrainRoutes({
           "deployment/joyful-capybara-123/team_and_project": () => ({
@@ -384,13 +414,18 @@ describe("npx convex select", () => {
             teamId: 1,
             projectId: 1,
           }),
-          "deployment/provision_and_authorize": () => ({
+          "teams/my-team/projects/my-project/deployments": () => true,
+          "deployment/authorize_within_current_project": () => ({
             adminKey: "dev-key",
             url: "https://joyful-capybara-123.convex.cloud",
             deploymentName: "joyful-capybara-123",
             deploymentType: "dev",
           }),
         });
+        mockPlatformGet.mockResolvedValue({
+          data: { name: "joyful-capybara-123" },
+          error: undefined,
+        });
 
         await deploymentSelect.parseAsync(["dev"], { from: "user" });
 
@@ -412,13 +447,18 @@ describe("npx convex select", () => {
             teamId: 1,
             projectId: 1,
           }),
-          "deployment/provision_and_authorize": () => ({
+          "teams/my-team/projects/my-project/deployments": () => true,
+          "deployment/authorize_within_current_project": () => ({
             adminKey: "dev-key",
             url: "https://joyful-capybara-123.convex.cloud",
             deploymentName: "joyful-capybara-123",
             deploymentType: "dev",
           }),
         });
+        mockPlatformGet.mockResolvedValue({
+          data: { name: "joyful-capybara-123" },
+          error: undefined,
+        });
 
         await deploymentSelect.parseAsync(["dev"], { from: "user" });
 
@@ -428,6 +468,48 @@ describe("npx convex select", () => {
         );
       });
     });
+
+    it("selects local deployment with 'local' selector", async () => {
+      testFiles.set(
+        path.resolve(".convex/local/default/config.json"),
+        JSON.stringify({
+          ports: { cloud: 3210, site: 3211 },
+          adminKey: "local-key",
+          backendVersion: "1.0.0",
+          deploymentName: "local-my_team-my_project-abc",
+        }),
+      );
+      // The local deployment name is looked up via Big Brain for project
+      // access checks (checkAccessToSelectedProject)
+      // FIXME We should probably avoid the Big Brain call here so that it works offline
+      setupBigBrainRoutes({
+        "deployment/local-my_team-my_project-abc/team_and_project": () => ({
+          team: "my-team",
+          project: "my-project",
+          teamId: 1,
+          projectId: 1,
+        }),
+      });
+
+      await deploymentSelect.parseAsync(["local"], { from: "user" });
+
+      const envContent = testFiles.get(path.resolve(".env.local"))!;
+      expect(envContent).toContain(
+        "CONVEX_DEPLOYMENT=local:local-my_team-my_project-abc",
+      );
+      // Site URL fetch should be skipped for local deployments
+      expect(envContent).not.toContain("CONVEX_SITE_URL");
+    });
+
+    it("fails with 'No local deployment found' when no local config exists", async () => {
+      await expect(
+        deploymentSelect.parseAsync(["local"], { from: "user" }),
+      ).rejects.toThrow();
+
+      expect(process.stderr.write).toHaveBeenCalledWith(
+        expect.stringContaining("No local deployment found"),
+      );
+    });
   });
 
   describe("without project configured", () => {
@@ -527,5 +609,32 @@ describe("npx convex select", () => {
       const envContent = testFiles.get(path.resolve(".env.local"))!;
       expect(envContent).toContain("CONVEX_DEPLOYMENT=dev:clever-otter-890");
     });
+
+    it("selects local deployment without project configured", async () => {
+      testFiles.set(
+        path.resolve(".convex/local/default/config.json"),
+        JSON.stringify({
+          ports: { cloud: 3210, site: 3211 },
+          adminKey: "local-key",
+          backendVersion: "1.0.0",
+          deploymentName: "local-my_team-my_project-abc",
+        }),
+      );
+      setupBigBrainRoutes({
+        "deployment/local-my_team-my_project-abc/team_and_project": () => ({
+          team: "my-team",
+          project: "my-project",
+          teamId: 1,
+          projectId: 1,
+        }),
+      });
+
+      await deploymentSelect.parseAsync(["local"], { from: "user" });
+
+      const envContent = testFiles.get(path.resolve(".env.local"))!;
+      expect(envContent).toContain(
+        "CONVEX_DEPLOYMENT=local:local-my_team-my_project-abc",
+      );
+    });
   });
 });

package/src/cli/deploymentSelect.ts

@@ -2,12 +2,13 @@ import { Command } from "@commander-js/extra-typings";
 import { Context, oneoffContext } from "../bundler/context.js";
 import { loadSelectedDeploymentCredentials } from "./lib/api.js";
 import {
+  DeploymentSelection,
   getDeploymentSelection,
   deploymentNameFromSelection,
 } from "./lib/deploymentSelection.js";
 import { parseDeploymentSelector } from "./lib/deploymentSelector.js";
 import { updateEnvAndConfigForDeploymentSelection } from "./configure.js";
-import { fetchDeploymentCanonicalSiteUrl } from "./lib/env.js";
+import { fetchDeploymentCanonicalUrls } from "./lib/deploy2.js";
 import { chalkStderr } from "chalk";
 
 export const deploymentSelect = new Command("select")
@@ -16,8 +17,8 @@ export const deploymentSelect = new Command("select")
     "Select the deployment to use when running commands.\n\n" +
       "The deployment will be used by all `npx convex` commands, except `npx convex deploy`. You can also run individual commands on another deployment by using the --deployment flag on that command.\n\n" +
       "Examples:\n" +
-      "  npx convex select dev                              # Select your personal dev deployment in the current project\n" +
-      "  npx convex select dev/james                        # Select a deployment in the same project by its reference\n" +
+      "  npx convex select dev                              # Select your personal cloud dev deployment in the current project\n" +
+      "  npx convex select local                            # Select your local deployment\n" +
       "  npx convex select dev/james                        # Select a deployment in the same project by its reference\n" +
       "  npx convex select some-project:dev/james           # Select a deployment in another project in the same team\n" +
       "  npx convex select some-team:some-project:dev/james # Select a deployment in a particular team/project\n",
@@ -30,45 +31,50 @@ export const deploymentSelect = new Command("select")
       adminKey: undefined,
       envFile: undefined,
     });
-    await selectDeployment(ctx, selector);
-  });
 
-export async function selectDeployment(
-  ctx: Context,
-  selector: string,
-): Promise<void> {
-  // Get the current deployment selection (no flags, just env/config state)
-  const currentSelection = await getDeploymentSelection(ctx, {});
+    // Get the current deployment selection (no flags, just env/config state)
+    const currentSelection = await getDeploymentSelection(ctx, {});
 
-  // If no project is configured and the selector needs project context, show a specific error
-  const parsed = parseDeploymentSelector(selector);
-  if (
-    currentSelection.kind === "chooseProject" &&
-    parsed.kind !== "inTeamProject" &&
-    parsed.kind !== "deploymentName"
-  ) {
-    return await ctx.crash({
-      exitCode: 1,
-      errorType: "fatal",
-      printedMessage: `No project configured. Run \`npx convex dev\` to set up a project first, or use a full selector like 'my-team:my-project:dev/james' or 'happy-capybara-123'.`,
+    // If no project is configured and the selector needs project context, show a specific error
+    const parsed = parseDeploymentSelector(selector);
+    if (
+      currentSelection.kind === "chooseProject" &&
+      parsed.kind !== "inTeamProject" &&
+      parsed.kind !== "deploymentName" &&
+      parsed.kind !== "local"
+    ) {
+      return await ctx.crash({
+        exitCode: 1,
+        errorType: "fatal",
+        printedMessage: `No project configured. Run \`npx convex dev\` to set up a project first, or use a full selector like 'my-team:my-project:dev/james' or 'happy-capybara-123'.`,
+      });
+    }
+
+    // Resolve the new deployment using the selector relative to the current project
+    const newSelection = await getDeploymentSelection(ctx, {
+      url: undefined,
+      adminKey: undefined,
+      envFile: undefined,
+      deployment: selector,
     });
-  }
 
-  // Resolve the new deployment using the selector relative to the current project
-  const newSelection = await getDeploymentSelection(ctx, {
-    url: undefined,
-    adminKey: undefined,
-    envFile: undefined,
-    deployment: selector,
+    await saveSelectedDeployment(
+      ctx,
+      selector,
+      newSelection,
+      deploymentNameFromSelection(currentSelection),
+    );
   });
 
-  const deployment = await loadSelectedDeploymentCredentials(
-    ctx,
-    newSelection,
-    {
-      ensureLocalRunning: false,
-    },
-  );
+export async function saveSelectedDeployment(
+  ctx: Context,
+  selector: string,
+  selection: DeploymentSelection,
+  previousDeploymentName: string | null,
+): Promise<void> {
+  const deployment = await loadSelectedDeploymentCredentials(ctx, selection, {
+    ensureLocalRunning: false,
+  });
 
   if (deployment.deploymentFields === null) {
     // Should be unreachable since for now, `select` only allows users
@@ -89,10 +95,13 @@ export async function selectDeployment(
     });
   }
 
-  const siteUrl = await fetchDeploymentCanonicalSiteUrl(ctx, {
-    adminKey: deployment.adminKey,
-    deploymentUrl: deployment.url,
-  });
+  const { convexSiteUrl: siteUrl } =
+    deployment.deploymentFields.deploymentType === "local"
+      ? { convexSiteUrl: null }
+      : await fetchDeploymentCanonicalUrls(ctx, {
+          adminKey: deployment.adminKey,
+          deploymentUrl: deployment.url,
+        });
 
   await updateEnvAndConfigForDeploymentSelection(
     ctx,
@@ -104,6 +113,6 @@ export async function selectDeployment(
       projectSlug: deployment.deploymentFields.projectSlug,
       deploymentType: deployment.deploymentFields.deploymentType,
     },
-    deploymentNameFromSelection(currentSelection),
+    previousDeploymentName,
   );
 }