WorkOS Provisioning CLI (#41203)

Add (currently) Convex cloud-only version of an WorkOS integration that allows every development deployment to have its own WorkOS environment which is configured automatically during a `convex dev` session.

Upon running `npm run dev` in a project
- `WORKOS_CLIENT_ID` is missing in the deployment? Trigger point!
    - Once “AuthKit dev deployment auto-provisioning” is enabled, this will be the default when a WORKOS_CLIENT_ID is missing.
    - Until then, ask the user if they'd like to set up the integration
- Try to provision a team if necessary (this can be done through the UI but a dashboard flow would be nicer)
- Try to provision an environment
    - Does the deployment have `AUTHKIT_CLIENT_ID` and `AUTHKIT_ENVIRONMENT_ID` and `AUTHKIT_ENVIRONMENT_API_KEY` already set? If so done, just call the WorkOS environment API endpoints.
    - check for an existing environment + API key for this deployment stored on the Convex cloud
- Set relevant Convex deployment environment variables
- Set relevant local environment variables (mostly `WORKOS_CLIENT_ID`)
- Set relevant WorkOS environment settings (redirect URI, CORS, etc.)

GitOrigin-RevId: 31c2b0a3b30ff160ae16b882391c7ce60471a7ac

Author: thomasballinger

npm-packages/convex/src/bundler/context.ts

@@ -28,6 +28,9 @@ export type ErrorType =
   // The error was some transient issue (e.g. a network
   // error). This will then cause a retry after an exponential backoff.
   | "transient"
+  // This error was caught, handled, and now all that needs to happen
+  // is for the proces to restart. No error is logged or reported.
+  | "already handled"
   // This error is truly permanent. Exit `npx convex dev` because the
   // developer will need to take a manual commandline action.
   | "fatal";

npm-packages/convex/src/cli/env.ts

@@ -9,7 +9,7 @@ import {
 import { actionDescription } from "./lib/command.js";
 import { ensureHasConvexDependency } from "./lib/utils/utils.js";
 import {
-  envGetInDeployment,
+  envGetInDeploymentAction,
   envListInDeployment,
   envRemoveInDeployment,
   envSetInDeployment,
@@ -83,7 +83,7 @@ const envGet = new Command("get")
     const options = cmd.optsWithGlobals();
     const { ctx, deployment } = await selectEnvDeployment(options);
     await ensureHasConvexDependency(ctx, "env get");
-    await envGetInDeployment(ctx, deployment, envVarName);
+    await envGetInDeploymentAction(ctx, deployment, envVarName);
   });
 
 const envRemove = new Command("remove")

npm-packages/convex/src/cli/index.ts

@@ -31,6 +31,7 @@ import { disableLocalDeployments } from "./disableLocalDev.js";
 import { mcp } from "./mcp.js";
 import dns from "node:dns";
 import net from "node:net";
+import { integration } from "./integration.js";
 
 const MINIMUM_MAJOR_VERSION = 16;
 const MINIMUM_MINOR_VERSION = 15;
@@ -115,6 +116,7 @@ async function main() {
     .addCommand(update)
     .addCommand(logout)
     .addCommand(networkTest, { hidden: true })
+    .addCommand(integration, { hidden: true })
     .addCommand(functionSpec)
     .addCommand(disableLocalDeployments)
     .addCommand(mcp)

npm-packages/convex/src/cli/integration.ts

@@ -0,0 +1,135 @@
+/**
+ * Debugging commands for the WorkOS integration; these are unstable, undocumented, and will change or disappear as the WorkOS integration evolves.
+ **/
+import { Command } from "@commander-js/extra-typings";
+import { Context, oneoffContext } from "../bundler/context.js";
+import chalk from "chalk";
+import {
+  DeploymentSelectionOptions,
+  deploymentSelectionWithinProjectFromOptions,
+  getTeamAndProjectSlugForDeployment,
+  loadSelectedDeploymentCredentials,
+} from "./lib/api.js";
+import { actionDescription } from "./lib/command.js";
+import { ensureHasConvexDependency } from "./lib/utils/utils.js";
+import { getDeploymentSelection } from "./lib/deploymentSelection.js";
+import { ensureWorkosEnvironmentProvisioned } from "./lib/workos/workos.js";
+import {
+  getCandidateEmailsForWorkIntegration,
+  getDeploymentCanProvisionWorkOSEnvironments,
+} from "./lib/workos/platformApi.js";
+import { logMessage } from "../bundler/log.js";
+
+async function selectEnvDeployment(
+  options: DeploymentSelectionOptions,
+): Promise<{
+  ctx: Context;
+  deployment: {
+    deploymentUrl: string;
+    deploymentName: string;
+    adminKey: string;
+    deploymentNotice: string;
+  };
+}> {
+  const ctx = await oneoffContext(options);
+  const deploymentSelection = await getDeploymentSelection(ctx, options);
+  const selectionWithinProject =
+    deploymentSelectionWithinProjectFromOptions(options);
+  const {
+    adminKey,
+    url: deploymentUrl,
+    deploymentFields,
+  } = await loadSelectedDeploymentCredentials(
+    ctx,
+    deploymentSelection,
+    selectionWithinProject,
+  );
+  const deploymentNotice =
+    deploymentFields !== null
+      ? ` (on ${chalk.bold(deploymentFields.deploymentType)} deployment ${chalk.bold(deploymentFields.deploymentName)})`
+      : "";
+  return {
+    ctx,
+    deployment: {
+      deploymentName: deploymentFields!.deploymentName,
+      deploymentUrl,
+      adminKey,
+      deploymentNotice,
+    },
+  };
+}
+
+const workosTeamStatus = new Command("status")
+  .summary("Status of associated WorkOS team")
+  .action(async (_options, cmd) => {
+    const options = cmd.optsWithGlobals();
+    const { ctx, deployment } = await selectEnvDeployment(options);
+
+    const { hasAssociatedWorkosTeam } =
+      await getDeploymentCanProvisionWorkOSEnvironments(
+        ctx,
+        deployment.deploymentName,
+      );
+
+    const info = await getTeamAndProjectSlugForDeployment(ctx, {
+      deploymentName: deployment.deploymentName,
+    });
+
+    const { availableEmails } = await getCandidateEmailsForWorkIntegration(ctx);
+
+    if (!hasAssociatedWorkosTeam) {
+      logMessage(
+        `Convex team ${info?.teamSlug} does not have an associated WorkOS team.`,
+      );
+      logMessage(
+        `Verified emails that mighe be able to add one: ${availableEmails.join(" ")}`,
+      );
+      return;
+    }
+
+    logMessage(`Convex team ${info?.teamSlug} has an associated WorkOS team.`);
+  });
+
+const workosProvisionEnvironment = new Command("provision-environment")
+  .summary("Provision a WorkOS environment")
+  .description(
+    "Create or get the WorkOS environment and API key for this deployment",
+  )
+  .configureHelp({ showGlobalOptions: true })
+  .allowExcessArguments(false)
+  .addDeploymentSelectionOptions(
+    actionDescription("Provision WorkOS environment for"),
+  )
+  .action(async (_options, cmd) => {
+    const options = cmd.optsWithGlobals();
+    const { ctx, deployment } = await selectEnvDeployment(options);
+    await ensureHasConvexDependency(
+      ctx,
+      "integration workos provision-environment",
+    );
+
+    try {
+      await ensureWorkosEnvironmentProvisioned(
+        ctx,
+        deployment.deploymentName,
+        deployment,
+      );
+    } catch (error) {
+      await ctx.crash({
+        exitCode: 1,
+        errorType: "fatal",
+        errForSentry: error,
+        printedMessage: `Failed to provision WorkOS environment: ${String(error)}`,
+      });
+    }
+  });
+const workos = new Command("workos")
+  .summary("WorkOS integration commands")
+  .description("Manage WorkOS team provisioning and environment setup")
+  .addCommand(workosProvisionEnvironment)
+  .addCommand(workosTeamStatus);
+
+export const integration = new Command("integration")
+  .summary("Integration commands")
+  .description("Commands for managing third-party integrations")
+  .addCommand(workos);

npm-packages/convex/src/cli/lib/api.ts

@@ -249,7 +249,7 @@ export async function checkAccessToSelectedProject(
   }
 }
 
-async function getTeamAndProjectSlugForDeployment(
+export async function getTeamAndProjectSlugForDeployment(
   ctx: Context,
   selector: { deploymentName: string },
 ): Promise<{ teamSlug: string; projectSlug: string } | null> {
@@ -810,3 +810,14 @@ export async function fetchTeamAndProjectForKey(
 
   return data;
 }
+
+export async function getTeamsForUser(ctx: Context) {
+  const teams = await bigBrainAPI<{ id: number; name: string; slug: string }[]>(
+    {
+      ctx,
+      method: "GET",
+      url: "teams",
+    },
+  );
+  return teams;
+}

npm-packages/convex/src/cli/lib/components.ts

@@ -445,7 +445,7 @@ export async function runComponentsPush(
     options.verbose,
   );
 
-  changeSpinner("Diffing local code and deployment state");
+  changeSpinner("Diffing local code and deployment state...");
   const { diffString } = diffConfig(
     remoteConfigWithModuleHashes,
     localConfig,

npm-packages/convex/src/cli/lib/config.ts

@@ -41,6 +41,7 @@ import {
   printLocalDeploymentOnError,
 } from "./localDeployment/errors.js";
 import { debugIsolateBundlesSerially } from "../../bundler/debugBundle.js";
+import { ensureWorkosEnvironmentProvisioned } from "./workos/workos.js";
 export { productionProvisionHost, provisionHost } from "./utils/utils.js";
 
 const brotli = promisify(zlib.brotliCompress);
@@ -841,6 +842,11 @@ export async function pushConfig(
       error,
       "Error: Unable to push deployment config to " + options.url,
       options.deploymentName,
+      {
+        adminKey: options.adminKey,
+        deploymentUrl: options.url,
+        deploymentNotice: "",
+      },
     );
   }
 }
@@ -1087,13 +1093,37 @@ export async function handlePushConfigError(
   error: unknown,
   defaultMessage: string,
   deploymentName: string | null,
-) {
+  deployment?: {
+    deploymentUrl: string;
+    adminKey: string;
+    deploymentNotice: string;
+  },
+): Promise<never> {
   const data: ErrorData | undefined =
     error instanceof ThrowingFetchError ? error.serverErrorData : undefined;
   if (data?.code === "AuthConfigMissingEnvironmentVariable") {
     const errorMessage = data.message || "(no error message given)";
     const [, variableName] =
       errorMessage.match(/Environment variable (\S+)/i) ?? [];
+
+    // WORKOS_CLIENT_ID is a special environment variable because cloud Convex
+    // deployments may be able to supply it by provisioning a fresh WorkOS
+    // environment on demand.
+    if (variableName === "WORKOS_CLIENT_ID" && deploymentName && deployment) {
+      const result = await ensureWorkosEnvironmentProvisioned(
+        ctx,
+        deploymentName,
+        deployment,
+      );
+      if (result === "ready") {
+        return await ctx.crash({
+          exitCode: 1,
+          errorType: "already handled",
+          printedMessage: null,
+        });
+      }
+    }
+
     const envVarMessage =
       `Environment variable ${chalk.bold(
         variableName,

npm-packages/convex/src/cli/lib/deploy2.ts

@@ -92,6 +92,11 @@ export async function startPush(
       error,
       "Error: Unable to start push to " + options.url,
       options.deploymentName,
+      {
+        adminKey: request.adminKey,
+        deploymentUrl: options.url,
+        deploymentNotice: "",
+      },
     );
   }
 }

npm-packages/convex/src/cli/lib/deployment.ts

@@ -59,18 +59,24 @@ export async function writeDeploymentEnvVar(
   );
   const deploymentEnvVarValue =
     deploymentType + ":" + deployment.deploymentName;
+  // The `existingValue` that reaches this function is at least sometimes is missing its prefix.
+  // Until this is cleaned up consider either of these values not a change.
+  // Otherwise we spam the init instructions (Welcome to Convex etc.) on every run of `npx convex dev`.
+  const changedDeploymentEnvVar =
+    existingValue !== deployment.deploymentName &&
+    existingValue !== deploymentEnvVarValue;
 
   if (changedFile !== null) {
     ctx.fs.writeUtf8File(ENV_VAR_FILE_PATH, changedFile);
     // Only do this if we're not reinitializing an existing setup
     return {
       wroteToGitIgnore: await gitIgnoreEnvVarFile(ctx),
-      changedDeploymentEnvVar: existingValue !== deploymentEnvVarValue,
+      changedDeploymentEnvVar,
     };
   }
   return {
     wroteToGitIgnore: false,
-    changedDeploymentEnvVar: existingValue !== deploymentEnvVarValue,
+    changedDeploymentEnvVar,
   };
 }
 

npm-packages/convex/src/cli/lib/dev.ts

@@ -189,16 +189,18 @@ export async function watchAndPush(
         break;
       }
       // Retry after an exponential backoff if we hit a transient error.
-      if (e.errorType === "transient") {
+      if (e.errorType === "transient" || e.errorType === "already handled") {
         const delay = nextBackoff(numFailures);
         numFailures += 1;
-        logWarning(
-          chalk.yellow(
-            `Failed due to network error, retrying in ${formatDuration(
-              delay,
-            )}...`,
-          ),
-        );
+        if (e.errorType === "transient") {
+          logWarning(
+            chalk.yellow(
+              `Failed due to network error, retrying in ${formatDuration(
+                delay,
+              )}...`,
+            ),
+          );
+        }
         await new Promise((resolve) => setTimeout(resolve, delay));
         continue;
       }