convex 1.34.0 → 1.35.0

package/src/cli/deploymentCreate.ts

@@ -10,6 +10,7 @@ import {
   DeploymentSelection,
   getDeploymentSelection,
   getProjectDetails,
+  deploymentNameFromSelection,
 } from "./lib/deploymentSelection.js";
 import {
   logNoDefaultRegionMessage,
@@ -19,35 +20,53 @@ import {
 } from "./lib/utils/utils.js";
 import { PlatformProjectDetails } from "@convex-dev/platform/managementApi";
 import { getTeamAndProjectFromPreviewAdminKey } from "./lib/deployment.js";
-import { selectDeployment } from "./deploymentSelect.js";
+import { saveSelectedDeployment } from "./deploymentSelect.js";
 import { promptOptions, promptString } from "./lib/utils/prompts.js";
 import { chalkStderr } from "chalk";
 import { parseDeploymentSelector } from "./lib/deploymentSelector.js";
+import {
+  parseExpiration,
+  resolveExpiration,
+  validateExpiration,
+} from "./lib/expiration.js";
+import { ensureBackendBinaryDownloaded } from "./lib/localDeployment/download.js";
+import {
+  loadProjectLocalConfig,
+  saveDeploymentConfig,
+} from "./lib/localDeployment/filePaths.js";
+import {
+  chooseLocalBackendPorts,
+  LOCAL_BACKEND_INSTANCE_SECRET,
+} from "./lib/localDeployment/utils.js";
+import { bigBrainStart } from "./lib/localDeployment/bigBrain.js";
+
+const SUPPORTED_TYPES = ["dev", "prod", "preview"] as const;
 
 export const deploymentCreate = new Command("create")
-  .summary("Create a new cloud deployment for a project")
+  .summary("Create a new deployment for a project")
   .description(
-    "Create a new cloud deployment for a project.\n\n" +
-      "  Create a dev deployment and select it: `npx convex deployment create dev/my-new-feature --type dev --select`\n" +
-      "  Create a prod staging deployment:      `npx convex deployment create staging --type prod`\n",
+    "Create a new deployment for a project.\n\n" +
+      "  Create a dev deployment and select it:    `npx convex deployment create dev/my-new-feature --type dev --select`\n" +
+      "  Create a prod deployment named “staging”: `npx convex deployment create staging --type prod`\n" +
+      "  Create a local deployment:                `npx convex deployment create local`\n",
   )
   .argument("[ref]")
   .allowExcessArguments(false)
   .addOption(
-    new Option("--type <type>", "Deployment type").choices([
-      "dev",
-      "prod",
-      "preview",
-    ] as const),
+    new Option("--type <type>", "Deployment type").choices(SUPPORTED_TYPES),
   )
   .option("--region <region>", "Deployment region")
   .option(
     "--select",
-    "Select the new deployment. This will update the Convex environment variables in .env.local and `npx convex dev` will run against this deployment.",
+    "Select the new deployment. This will update the Convex environment variables in .env.local. Subsequent `npx convex` commands will run against this deployment.",
   )
   .option(
     "--default",
-    "Set the new deployment as your default development or production deployment.",
+    "Make the new deployment your default production deployment (used by `npx convex deploy`) or your personal dev deployment.",
+  )
+  .option(
+    "--expiration <value>",
+    'When the deployment expires (e.g. "none", "in 7 days", "2026-04-01T00:00:00Z", or a UNIX timestamp in seconds or milliseconds)',
   )
   .action(async (refParam, options) => {
     const ctx = await oneoffContext({
@@ -56,10 +75,62 @@ export const deploymentCreate = new Command("create")
       envFile: undefined,
     });
 
-    const { ref, regionDetails, projectId, type, isDefault } = process.stdin
-      .isTTY
-      ? await resolveOptionsInteractively(ctx, refParam, options)
-      : await resolveOptionsNoninteractively(ctx, refParam, options);
+    const currentDeployment = await getDeploymentSelection(ctx, {
+      url: undefined,
+      adminKey: undefined,
+      envFile: undefined,
+    });
+
+    // Handle `deployment create local`
+    if (refParam !== undefined) {
+      if (refParam === "local") {
+        const cloudOnlyFlags = [
+          "type",
+          "region",
+          "default",
+          "expiration",
+        ] as const;
+        for (const flag of cloudOnlyFlags) {
+          if (options[flag]) {
+            return await ctx.crash({
+              exitCode: 1,
+              errorType: "fatal",
+              printedMessage: `--${flag} cannot be used when creating a local deployment`,
+            });
+          }
+        }
+        await createLocalDeployment(
+          ctx,
+          currentDeployment,
+          options.select ?? false,
+        );
+        return;
+      }
+    }
+
+    const expiresAt = await resolveExpiresAtOrCrash(ctx, options.expiration);
+
+    const {
+      ref,
+      regionDetails,
+      projectId,
+      type,
+      isDefault,
+      teamSlug,
+      projectSlug,
+    } = process.stdin.isTTY
+      ? await resolveOptionsInteractively(
+          ctx,
+          currentDeployment,
+          refParam,
+          options,
+        )
+      : await resolveOptionsNoninteractively(
+          ctx,
+          currentDeployment,
+          refParam,
+          options,
+        );
 
     showSpinner(
       `Creating ${type} deployment` +
@@ -79,6 +150,7 @@ export const deploymentCreate = new Command("create")
             region: regionDetails?.name ?? null,
             reference: ref ?? null,
             isDefault,
+            ...(expiresAt !== undefined ? { expiresAt } : {}),
           },
         },
       )
@@ -97,20 +169,113 @@ export const deploymentCreate = new Command("create")
 
     if (!options.select) {
       logFinishedStep(
-        `Provisioned a ${created.isDefault ? "default " : ""}${created.deploymentType} deployment. Select this deployment to develop against using \`npx convex deployment select ${created.reference}\``,
-      );
-      logMessage(
-        chalkStderr.gray(
-          "Hint: use `npx convex deployment create --select` to immediately select the newly created deployment.",
-        ),
+        `Provisioned a ${created.isDefault ? "default " : ""}${created.deploymentType} deployment.`,
       );
+      if (type !== "prod") {
+        const selectRef = `${teamSlug}:${projectSlug}:${created.reference}`;
+        logMessage(
+          `\nTo make \`npx convex\` use this deployment, run ${chalkStderr.bold(`npx convex deployment select ${selectRef}`)}`,
+        );
+        logMessage(
+          chalkStderr.gray(
+            "Hint: use `--select` to immediately select the newly created deployment.",
+          ),
+        );
+      }
     }
 
     if (options.select) {
-      await selectDeployment(ctx, created.reference);
+      const selection: DeploymentSelection = {
+        kind: "deploymentWithinProject",
+        targetProject: {
+          kind: "teamAndProjectSlugs",
+          teamSlug,
+          projectSlug,
+        },
+        selectionWithinProject: {
+          kind: "deploymentSelector",
+          selector: created.reference,
+        },
+      };
+      await saveSelectedDeployment(
+        ctx,
+        created.reference,
+        selection,
+        deploymentNameFromSelection(currentDeployment),
+      );
     }
   });
 
+async function createLocalDeployment(
+  ctx: Context,
+  currentDeployment: DeploymentSelection,
+  select: boolean,
+): Promise<void> {
+  const existing = loadProjectLocalConfig(ctx);
+  if (existing) {
+    return await ctx.crash({
+      exitCode: 1,
+      errorType: "fatal",
+      printedMessage: "A local deployment already exists.",
+    });
+  }
+
+  const { teamSlug, slug: projectSlug } = await resolveProject(
+    ctx,
+    currentDeployment,
+  );
+
+  showSpinner("Downloading local backend...");
+  const { version } = await ensureBackendBinaryDownloaded(ctx, {
+    kind: "latest",
+  });
+
+  const { cloudPort, sitePort } = await chooseLocalBackendPorts(ctx);
+
+  showSpinner("Registering local deployment...");
+  const { deploymentName, adminKey } = await bigBrainStart(ctx, {
+    port: cloudPort,
+    projectSlug,
+    teamSlug,
+    instanceName: null,
+  });
+
+  saveDeploymentConfig(ctx, "local", deploymentName, {
+    backendVersion: version,
+    ports: { cloud: cloudPort, site: sitePort },
+    adminKey,
+    instanceSecret: LOCAL_BACKEND_INSTANCE_SECRET,
+  });
+
+  logFinishedStep("Created local deployment.");
+
+  if (select) {
+    const selection: DeploymentSelection = {
+      kind: "deploymentWithinProject",
+      targetProject: {
+        kind: "deploymentName",
+        deploymentName,
+        deploymentType: "local",
+      },
+      selectionWithinProject: {
+        kind: "deploymentSelector",
+        selector: "local",
+      },
+    };
+    await saveSelectedDeployment(
+      ctx,
+      "local",
+      selection,
+      deploymentNameFromSelection(currentDeployment),
+    );
+  }
+
+  const devCommand = select
+    ? "npx convex dev"
+    : "npx convex dev --deployment local";
+  logMessage(`\nRun ${chalkStderr.bold(devCommand)} to start it.`);
+}
+
 type RefParam = Parameters<Parameters<typeof deploymentCreate.action>[0]>[0];
 type OptionsParam = Parameters<
   Parameters<typeof deploymentCreate.action>[0]
@@ -118,6 +283,7 @@ type OptionsParam = Parameters<
 
 async function resolveOptionsNoninteractively(
   ctx: Context,
+  currentDeployment: DeploymentSelection,
   refParam: RefParam,
   options: OptionsParam,
 ) {
@@ -151,7 +317,7 @@ async function resolveOptionsNoninteractively(
     return await ctx.crash({
       exitCode: 1,
       errorType: "fatal",
-      printedMessage: "--type is required. Use --type dev or --type prod.",
+      printedMessage: `--type is required (supported values: ${SUPPORTED_TYPES.join(", ")})`,
     });
   }
 
@@ -161,14 +327,7 @@ async function resolveOptionsNoninteractively(
         teamSlug: teamAndProject.teamSlug,
         projectSlug: teamAndProject.projectSlug,
       })
-    : await resolveProject(
-        ctx,
-        await getDeploymentSelection(ctx, {
-          url: undefined,
-          adminKey: undefined,
-          envFile: undefined,
-        }),
-      );
+    : await resolveProject(ctx, currentDeployment);
   const projectId = project.id;
 
   // If no region is passed in, the team's default region will be used
@@ -188,11 +347,14 @@ async function resolveOptionsNoninteractively(
     projectId,
     regionDetails,
     type: options.type,
+    teamSlug: project.teamSlug,
+    projectSlug: project.slug,
   };
 }
 
 async function resolveOptionsInteractively(
   ctx: Context,
+  currentDeployment: DeploymentSelection,
   refParam: RefParam,
   options: OptionsParam,
 ) {
@@ -232,7 +394,15 @@ async function resolveOptionsInteractively(
     }
   }
   while (ref === undefined) {
-    const input = await promptString(ctx, { message: "Deployment ref?" });
+    const input = await promptString(ctx, {
+      message:
+        "How to name this deployment?\n" +
+        chalkStderr.reset.dim(
+          "The deployment reference will be used to identify your deployment on the dashboard and in CLI commands.\nExamples: staging, dev/james/feature-payment-integration",
+        ) +
+        "\n>",
+      validate: validateTentativeReference,
+    });
     const result = parseSelectorForNewDeployment(input);
     if (result.kind === "invalid") {
       logFailure(result.message);
@@ -248,14 +418,7 @@ async function resolveOptionsInteractively(
         teamSlug: teamAndProject.teamSlug,
         projectSlug: teamAndProject.projectSlug,
       })
-    : await resolveProject(
-        ctx,
-        await getDeploymentSelection(ctx, {
-          url: undefined,
-          adminKey: undefined,
-          envFile: undefined,
-        }),
-      );
+    : await resolveProject(ctx, currentDeployment);
 
   const availableRegions = await fetchAvailableRegions(ctx, project.teamId);
   let regionDetails: AvailableRegion;
@@ -300,6 +463,8 @@ async function resolveOptionsInteractively(
     projectId: project.id,
     regionDetails,
     type: deploymentType,
+    teamSlug: project.teamSlug,
+    projectSlug: project.slug,
   };
 }
 
@@ -316,6 +481,11 @@ function parseSelectorForNewDeployment(
 ): NewDeploymentSelectorResult {
   const selector = parseDeploymentSelector(selectorString);
   switch (selector.kind) {
+    case "local":
+      return {
+        kind: "invalid",
+        message: `"local" is not a valid deployment reference. To create a local deployment, run ${chalkStderr.bold("npx convex deployment create local")}`,
+      };
     case "deploymentName":
       return {
         kind: "invalid",
@@ -508,6 +678,36 @@ async function crashInvalidRegion(
   });
 }
 
+async function resolveExpiresAtOrCrash(
+  ctx: Context,
+  expiration: string | undefined,
+): Promise<number | null | undefined> {
+  if (!expiration) {
+    return undefined;
+  }
+  const parsed = parseExpiration(expiration);
+  if (parsed.kind === "error") {
+    return await ctx.crash({
+      exitCode: 1,
+      errorType: "fatal",
+      printedMessage: parsed.message,
+    });
+  }
+  const now = Date.now();
+  const resolved = resolveExpiration(parsed, now);
+  if (resolved !== null) {
+    const validation = validateExpiration(resolved, now);
+    if (validation.kind === "error") {
+      return await ctx.crash({
+        exitCode: 1,
+        errorType: "fatal",
+        printedMessage: validation.message,
+      });
+    }
+  }
+  return resolved;
+}
+
 /**
  * Helper to log a value passed in as a CLI argument in the interactive flow.
  */
@@ -515,3 +715,30 @@ function logAndUse<T extends string | boolean>(label: string, value: T): T {
   logFinishedStep(`Using ${label}: ${chalkStderr.bold(value)}`);
   return value;
 }
+
+// This is an oversimplification, it’s fine if it fails later
+function validateTentativeReference(tentativeReference: string): true | string {
+  if (tentativeReference.length < 3) {
+    return "References must be at least 3 characters";
+  }
+  if (tentativeReference.length > 100) {
+    return "References must be at most 100 characters";
+  }
+  if (!/^[a-z0-9/-]+$/.test(tentativeReference)) {
+    return "References can only contain lowercase letters, numbers, hyphens, and slashes";
+  }
+  if (tentativeReference === "dev") {
+    return '"dev" is not a valid deployment reference.';
+  }
+  if (tentativeReference === "prod") {
+    return '"prod" is not a valid deployment reference.';
+  }
+  if (tentativeReference === "local") {
+    return `"local" is not a valid deployment reference. To create a local deployment, run ${chalkStderr.bold("npx convex deployment create local")}`;
+  }
+  if (/^[a-z]+-[a-z]+-\d+$/.test(tentativeReference)) {
+    return "References cannot be in the format abc-xyz-123, as it is reserved for deployment names";
+  }
+
+  return true;
+}