add sentinels for cli CONVEX_DEPLOY_KEY (#43076)

GitOrigin-RevId: 5461b97c477132229f8a655eac06a2a50013309b

Author: atrakh

src/cli/lib/deploymentSelection.ts

@@ -25,6 +25,7 @@ import {
   CONVEX_SELF_HOSTED_URL_VAR_NAME,
   ENV_VAR_FILE_PATH,
   bigBrainAPI,
+  processDeployKeyValue,
 } from "./utils/utils.js";
 import * as dotenv from "dotenv";
 
@@ -84,7 +85,8 @@ export async function initializeBigBrainAuth(
       });
     }
     const config = dotenv.parse(existingFile);
-    const deployKey = config[CONVEX_DEPLOY_KEY_ENV_VAR_NAME];
+    const rawDeployKey = config[CONVEX_DEPLOY_KEY_ENV_VAR_NAME];
+    const deployKey = await processDeployKeyValue(ctx, rawDeployKey);
     if (deployKey !== undefined) {
       const bigBrainAuth = getBigBrainAuth(ctx, {
         previewDeployKey: isPreviewDeployKey(deployKey) ? deployKey : null,
@@ -97,7 +99,8 @@ export async function initializeBigBrainAuth(
   }
   dotenv.config({ path: ENV_VAR_FILE_PATH });
   dotenv.config();
-  const deployKey = process.env[CONVEX_DEPLOY_KEY_ENV_VAR_NAME];
+  const rawDeployKey = process.env[CONVEX_DEPLOY_KEY_ENV_VAR_NAME];
+  const deployKey = await processDeployKeyValue(ctx, rawDeployKey);
   if (deployKey !== undefined) {
     const bigBrainAuth = getBigBrainAuth(ctx, {
       previewDeployKey: isPreviewDeployKey(deployKey) ? deployKey : null,
@@ -425,8 +428,12 @@ async function getDeploymentSelectionFromEnv(
 ): Promise<
   { kind: "success"; metadata: DeploymentSelection } | { kind: "unknown" }
 > {
-  const deployKey = getEnv(CONVEX_DEPLOY_KEY_ENV_VAR_NAME);
-  if (deployKey !== null) {
+  const rawDeployKey = getEnv(CONVEX_DEPLOY_KEY_ENV_VAR_NAME);
+  const deployKey = await processDeployKeyValue(
+    ctx,
+    rawDeployKey === null ? undefined : rawDeployKey,
+  );
+  if (deployKey !== undefined) {
     const deployKeyType = isPreviewDeployKey(deployKey)
       ? "preview"
       : isProjectKey(deployKey)

src/cli/lib/utils/utils.ts

@@ -40,6 +40,45 @@ const MAX_RETRIES = 6;
 // After 3 retries, log a progress message that we're retrying the request
 const RETRY_LOG_THRESHOLD = 3;
 
+/**
+ * Processes the CONVEX_DEPLOY_KEY value to handle special sentinel values.
+ *
+ * - If the value is `<ignore_deploy_key>`, treats it as if the env var isn't set (returns undefined)
+ * - If the value matches `<missing_deploy_key:$STRING>`, crashes with the message in $STRING
+ * - Otherwise returns the value as-is
+ *
+ * @param ctx Context for crashing if needed
+ * @param deployKey The raw deploy key value from environment or config
+ * @returns The processed deploy key value or undefined
+ */
+export async function processDeployKeyValue(
+  ctx: Context,
+  deployKey: string | undefined,
+): Promise<string | undefined> {
+  if (deployKey === undefined) {
+    return undefined;
+  }
+
+  // Check for <ignore_deploy_key> sentinel
+  if (deployKey === "<ignore_deploy_key>") {
+    return undefined;
+  }
+
+  // Check for <missing_deploy_key:$STRING> sentinel
+  const missingKeyPattern = /^<missing_deploy_key:(.+)>$/;
+  const match = deployKey.match(missingKeyPattern);
+  if (match) {
+    const errorMessage = match[1];
+    return await ctx.crash({
+      exitCode: 1,
+      errorType: "fatal",
+      printedMessage: errorMessage,
+    });
+  }
+
+  return deployKey;
+}
+
 export function parsePositiveInteger(value: string) {
   const parsedValue = parseInteger(value);
   if (parsedValue <= 0) {