convex 1.47.0 → 1.48.0-alpha.0

package/src/cli/lib/deploymentSelection.ts

@@ -31,18 +31,26 @@ import {
   targetProjectForLocalSelector,
 } from "./localDeployment/projectMismatch.js";
 import { chalkStderr } from "chalk";
-import { getBuildEnvironment } from "./envvars.js";
+import {
+  getBuildEnvironment,
+  loadProjectEnvironmentVariables,
+} from "./envvars.js";
 import { readGlobalConfig } from "./utils/globalConfig.js";
+import {
+  getProfileSelection,
+  ProfileSelection,
+  readProfileAuth,
+} from "./profiles.js";
 import {
   CONVEX_DEPLOYMENT_ENV_VAR_NAME,
   CONVEX_DEPLOYMENT_TOKEN_ENV_VAR_NAME,
   CONVEX_DEPLOY_KEY_ENV_VAR_NAME,
   CONVEX_SELF_HOSTED_ADMIN_KEY_VAR_NAME,
   CONVEX_SELF_HOSTED_URL_VAR_NAME,
-  ENV_VAR_FILE_PATH,
   bigBrainAPI,
   processDeployKeyValue,
   readDeployKeyFromEnv,
+  readDeployKeyEnvVar,
   typedPlatformClient,
 } from "./utils/utils.js";
 import * as dotenv from "dotenv";
@@ -83,10 +91,11 @@ export async function initializeBigBrainAuth(
   if (initialArgs.url !== undefined && initialArgs.adminKey !== undefined) {
     // Do not check any env vars if `url` and `adminKey` are specified via CLI
     ctx._updateBigBrainAuth(
-      getBigBrainAuth(ctx, {
+      await getBigBrainAuth(ctx, {
         previewDeployKey: null,
         projectKey: null,
         deploymentKey: null,
+        skipProfile: true,
       }),
     );
     return;
@@ -106,30 +115,31 @@ export async function initializeBigBrainAuth(
     const rawDeployKey = readDeployKeyFromEnv((name) => config[name]);
     const deployKey = await processDeployKeyValue(ctx, rawDeployKey);
     if (deployKey !== undefined) {
-      const bigBrainAuth = getBigBrainAuth(ctx, {
+      const bigBrainAuth = await getBigBrainAuth(ctx, {
         previewDeployKey: isPreviewDeployKey(deployKey) ? deployKey : null,
         projectKey: isProjectKey(deployKey) ? deployKey : null,
         deploymentKey: isDeploymentKey(deployKey) ? deployKey : null,
+        envFile: initialArgs.envFile,
       });
       ctx._updateBigBrainAuth(bigBrainAuth);
       return;
     }
     // No deploy key was found in the env file, so fall back on using the global config
     ctx._updateBigBrainAuth(
-      getBigBrainAuth(ctx, {
+      await getBigBrainAuth(ctx, {
         previewDeployKey: null,
         projectKey: null,
         deploymentKey: null,
+        envFile: initialArgs.envFile,
       }),
     );
     return;
   }
-  dotenv.config({ path: ENV_VAR_FILE_PATH });
-  dotenv.config();
+  loadProjectEnvironmentVariables();
   const rawDeployKey = readDeployKeyFromEnv((name) => process.env[name]);
   const deployKey = await processDeployKeyValue(ctx, rawDeployKey);
   if (deployKey !== undefined) {
-    const bigBrainAuth = getBigBrainAuth(ctx, {
+    const bigBrainAuth = await getBigBrainAuth(ctx, {
       previewDeployKey: isPreviewDeployKey(deployKey) ? deployKey : null,
       projectKey: isProjectKey(deployKey) ? deployKey : null,
       deploymentKey: isDeploymentKey(deployKey) ? deployKey : null,
@@ -138,7 +148,7 @@ export async function initializeBigBrainAuth(
     return;
   }
   ctx._updateBigBrainAuth(
-    getBigBrainAuth(ctx, {
+    await getBigBrainAuth(ctx, {
       previewDeployKey: null,
       projectKey: null,
       deploymentKey: null,
@@ -150,6 +160,7 @@ export async function initializeBigBrainAuth(
 export async function updateBigBrainAuthAfterLogin(
   ctx: Context,
   accessToken: string,
+  profile?: ProfileSelection,
 ) {
   const existingAuth = ctx.bigBrainAuth();
   if (existingAuth !== null && existingAuth.kind === "projectKey") {
@@ -162,6 +173,7 @@ export async function updateBigBrainAuthAfterLogin(
     accessToken: accessToken,
     kind: "accessToken",
     header: `Bearer ${accessToken}`,
+    ...(profile ? { profile } : {}),
   });
 }
 
@@ -169,19 +181,22 @@ export async function clearBigBrainAuth(ctx: Context) {
   ctx._updateBigBrainAuth(null);
 }
 
-function getBigBrainAuth(
+async function getBigBrainAuth(
   ctx: Context,
   opts: {
     previewDeployKey: string | null;
     projectKey: string | null;
     deploymentKey: string | null;
+    envFile?: string;
+    skipProfile?: boolean;
   },
-): BigBrainAuth | null {
+): Promise<BigBrainAuth | null> {
   if (process.env.CONVEX_OVERRIDE_ACCESS_TOKEN) {
     return {
       accessToken: process.env.CONVEX_OVERRIDE_ACCESS_TOKEN,
       kind: "accessToken",
       header: `Bearer ${process.env.CONVEX_OVERRIDE_ACCESS_TOKEN}`,
+      profile: null,
     };
   }
   if (opts.projectKey !== null) {
@@ -200,12 +215,19 @@ function getBigBrainAuth(
       deploymentKey: opts.deploymentKey,
     };
   }
+  const profile = opts.skipProfile
+    ? null
+    : await getProfileSelection(ctx, { envFile: opts.envFile });
+  if (profile !== null) {
+    return await readProfileAuth(ctx, profile);
+  }
   const globalConfig = readGlobalConfig(ctx);
   if (globalConfig) {
     return {
       kind: "accessToken",
       header: `Bearer ${globalConfig.accessToken}`,
       accessToken: globalConfig.accessToken,
+      profile: null,
     };
   }
   if (opts.previewDeployKey !== null) {
@@ -272,9 +294,9 @@ export async function ensureAuthCanCreateDeployment(
       )} and try again.`,
     });
   }
-  const envVar = process.env[CONVEX_DEPLOY_KEY_ENV_VAR_NAME]
-    ? CONVEX_DEPLOY_KEY_ENV_VAR_NAME
-    : CONVEX_DEPLOYMENT_TOKEN_ENV_VAR_NAME;
+  const envVar =
+    readDeployKeyEnvVar((name) => process.env[name])?.name ??
+    CONVEX_DEPLOY_KEY_ENV_VAR_NAME;
   return await ctx.crash({
     exitCode: 1,
     errorType: "fatal",
@@ -569,10 +591,7 @@ async function resolveBaseDeploymentSelection(
     }
     return result.metadata;
   }
-  // start with .env.local (but doesn't override existing)
-  dotenv.config({ path: ENV_VAR_FILE_PATH });
-  // for variables not already set, use .env values
-  dotenv.config();
+  loadProjectEnvironmentVariables();
   const result = await getDeploymentSelectionFromEnv(
     ctx,
     selectionWithinProject,

package/src/cli/lib/envvars.ts

@@ -6,7 +6,49 @@ import * as dotenv from "dotenv";
 
 import { Context } from "../../bundler/context.js";
 import { logWarning } from "../../bundler/log.js";
-import { loadPackageJson } from "./utils/utils.js";
+import {
+  CONVEX_DEPLOY_KEY_ENV_VAR_NAME,
+  readDeployKeyEnvVar,
+  ENV_VAR_FILE_PATH,
+  loadPackageJson,
+} from "./utils/utils.js";
+
+export const CONVEX_ACCOUNT_ENV_VAR = "CONVEX_ACCOUNT";
+
+const loadedEnvironment = new Map<string, { value: string; source: string }>();
+
+export function loadProjectEnvironmentVariables() {
+  // Only remove values supplied by our previous load; later shell overrides win.
+  for (const [name, { value }] of loadedEnvironment) {
+    if (process.env[name] === value) delete process.env[name];
+  }
+  loadedEnvironment.clear();
+  const environment: Record<string, string> = {};
+  for (const [name, value] of Object.entries(process.env)) {
+    if (value !== undefined) environment[name] = value;
+  }
+  for (const file of [ENV_VAR_FILE_PATH, ".env"]) {
+    dotenv.config({ path: file, processEnv: environment });
+    for (const [name, value] of Object.entries(environment)) {
+      // Account selection reads the current project's files directly.
+      if (name !== CONVEX_ACCOUNT_ENV_VAR && process.env[name] === undefined) {
+        process.env[name] = value;
+        loadedEnvironment.set(name, { value, source: file });
+      }
+    }
+  }
+}
+
+export function getDeployKeySource(key: string) {
+  const envVarName =
+    readDeployKeyEnvVar((name) => process.env[name])?.name ??
+    CONVEX_DEPLOY_KEY_ENV_VAR_NAME;
+  const loaded = loadedEnvironment.get(envVarName);
+  return {
+    envVarName,
+    source: loaded?.value === key ? loaded.source : "shell environment",
+  };
+}
 
 const _FRAMEWORKS = [
   "create-react-app",

package/src/cli/lib/fsUtils.ts

@@ -6,12 +6,15 @@ import { NodeFs } from "../../bundler/fs.js";
 export function recursivelyDelete(
   ctx: Context,
   deletePath: string,
-  opts?: { force?: boolean; dryRun?: boolean },
+  opts?: { force?: boolean; dryRun?: boolean; followSymlinks?: boolean },
 ) {
   const dryRun = !!opts?.dryRun;
   let st;
   try {
-    st = ctx.fs.stat(deletePath);
+    st =
+      opts?.followSymlinks === false
+        ? ctx.fs.lstat(deletePath)
+        : ctx.fs.stat(deletePath);
   } catch (err: any) {
     if (err.code === "ENOENT" && opts?.force) {
       return;

package/src/cli/lib/generateDocs.ts

@@ -299,7 +299,7 @@ function renderCopyableCommands(text: string): string {
     .map((line) =>
       /^- /.test(line)
         ? line.replace(
-            /`(npx convex [^`]*)`/g,
+            /`(npx convex(?:@[^\s`]+)? [^`]*)`/g,
             (_, command) =>
               `<CodeWithCopyButton text={${JSON.stringify(command)}} />`,
           )

package/src/cli/lib/login.ts

@@ -32,6 +32,17 @@ import {
   modifyGlobalConfig,
 } from "./utils/globalConfig.js";
 import { updateBigBrainAuthAfterLogin } from "./deploymentSelection.js";
+import {
+  getProfileSelection,
+  ProfileSelection,
+  profileConfigPath,
+  writeProfileCredentials,
+  readProfileCredentials,
+} from "./profiles.js";
+import {
+  profileLoginMetadata,
+  revokeReplacedProfileToken,
+} from "./profileManagement.js";
 
 // Per https://github.com/panva/node-openid-client/tree/main/docs#customizing
 custom.setHttpOptionsDefaults({
@@ -291,6 +302,7 @@ export async function performLogin(
     anonymousId,
     vercel,
     vercelOverride,
+    profile: selectedProfile,
   }: {
     overrideAuthUrl?: string | undefined;
     overrideAuthClient?: string | undefined;
@@ -307,8 +319,16 @@ export async function performLogin(
     anonymousId?: string | undefined;
     vercel?: boolean | undefined;
     vercelOverride?: string | undefined;
+    profile?: ProfileSelection | null;
   } = {},
 ) {
+  const auth = ctx.bigBrainAuth();
+  const profile =
+    selectedProfile !== undefined
+      ? selectedProfile
+      : auth?.kind === "accessToken" && auth.profile !== undefined
+        ? auth.profile
+        : await getProfileSelection(ctx);
   loginFlow = loginFlow || "auto";
   // Get access token from big-brain
   // Default the device name to the hostname, but allow the user to change this if the terminal is interactive.
@@ -400,6 +420,12 @@ export async function performLogin(
   }
 
   // Exchange the WorkOS access token for a Convex personal access token.
+  const previous =
+    profile === null ? null : await readProfileCredentials(ctx, profile, true);
+  const metadata =
+    profile === null
+      ? {}
+      : await profileLoginMetadata(ctx, profile, accessToken, previous);
   ctx._updateBigBrainAuth({
     accessToken: accessToken,
     kind: "accessToken",
@@ -417,8 +443,19 @@ export async function performLogin(
   const newAccessToken = response.data!.accessToken;
   const globalConfig = { accessToken: newAccessToken };
   try {
-    await modifyGlobalConfig(ctx, globalConfig);
-    const path = globalConfigPath();
+    if (profile !== null) {
+      await writeProfileCredentials(
+        ctx,
+        profile.name,
+        newAccessToken,
+        metadata,
+        previous,
+      );
+    } else {
+      await modifyGlobalConfig(ctx, globalConfig);
+    }
+    const path =
+      profile !== null ? profileConfigPath(profile.name) : globalConfigPath();
     logFinishedStep(`Saved credentials to ${formatPathForPrinting(path)}`);
   } catch (err: unknown) {
     return await ctx.crash({
@@ -429,8 +466,15 @@ export async function performLogin(
     });
   }
 
+  if (profile !== null) {
+    await revokeReplacedProfileToken(
+      ctx,
+      previous?.accessToken,
+      newAccessToken,
+    );
+  }
   logVerbose(`performLogin: updating big brain auth after login`);
-  await updateBigBrainAuthAfterLogin(ctx, newAccessToken);
+  await updateBigBrainAuthAfterLogin(ctx, newAccessToken, profile ?? undefined);
 
   logVerbose(`performLogin: checking opt ins, acceptOptIns: ${acceptOptIns}`);
   // Do opt in to TOS and Privacy Policy stuff

package/src/cli/lib/mcp/requestContext.ts

@@ -149,7 +149,13 @@ export function encodeDeploymentSelector(
     projectDir,
     deployment,
   };
-  return `${deployment.kind}:${btoa(JSON.stringify(payload))}`;
+  // ASCII JSON escapes support Unicode paths with the existing Latin-1 decoder.
+  const serialized = JSON.stringify(payload).replace(
+    /[\u0080-\uffff]/g,
+    (character) =>
+      `\\u${character.charCodeAt(0).toString(16).padStart(4, "0")}`,
+  );
+  return `${deployment.kind}:${btoa(serialized)}`;
 }
 
 const payloadSchema = z.object({

package/src/cli/lib/profileManagement.ts

@@ -0,0 +1,262 @@
+import { ProjectSelection } from "./deploymentSelection.js";
+import { Context } from "../../bundler/context.js";
+import { logMessage, logWarning } from "../../bundler/log.js";
+import { provisionHost } from "./config.js";
+import { version } from "../version.js";
+import {
+  isAnonymousDeployment,
+  getDeploymentTypeFromConfiguredDeployment,
+  stripDeploymentTypePrefix,
+} from "./deployment.js";
+import { CONVEX_DEPLOYMENT_ENV_VAR_NAME } from "./utils/utils.js";
+import { promptYesNo } from "./utils/prompts.js";
+import { loadProjectEnvironmentVariables } from "./envvars.js";
+import {
+  ProfileCredentials,
+  ProfileSelection,
+  readProfileCredentials,
+  readProfileSettings,
+  readProfileToken,
+  savedProfileNames,
+  writeProfileDirectory,
+} from "./profiles.js";
+
+export async function profileApi(
+  token: string,
+  pathname: string,
+  body?: unknown,
+) {
+  return await fetch(`${provisionHost}${pathname}`, {
+    method: body === undefined ? "GET" : "POST",
+    headers: {
+      Authorization: `Bearer ${token}`,
+      "Convex-Client": `npm-cli-${version}`,
+      ...(body === undefined ? {} : { "Content-Type": "application/json" }),
+    },
+    ...(body === undefined ? {} : { body: JSON.stringify(body) }),
+    signal: AbortSignal.timeout(10_000),
+  });
+}
+
+export async function deploymentAccess(
+  token: string,
+  deploymentName: string,
+): Promise<"yes" | "no" | "unknown"> {
+  try {
+    const response = await profileApi(
+      token,
+      `/v1/deployments/${encodeURIComponent(deploymentName)}`,
+    );
+    if (response.ok) return "yes";
+    return [401, 403, 404].includes(response.status) ? "no" : "unknown";
+  } catch {
+    return "unknown";
+  }
+}
+
+export async function projectAccess(
+  token: string,
+  target: ProjectSelection,
+): Promise<"yes" | "no" | "unknown"> {
+  if (target.kind === "deploymentName")
+    return deploymentAccess(token, target.deploymentName);
+  if (target.kind !== "teamAndProjectSlugs") return "unknown";
+  try {
+    const response = await profileApi(
+      token,
+      `/v1/teams/${encodeURIComponent(target.teamSlug)}/projects/${encodeURIComponent(target.projectSlug)}`,
+    );
+    if (response.ok) return "yes";
+    return [401, 403, 404].includes(response.status) ? "no" : "unknown";
+  } catch {
+    return "unknown";
+  }
+}
+
+function configuredCloudDeployment(): string | null {
+  const configured = process.env[CONVEX_DEPLOYMENT_ENV_VAR_NAME]?.trim();
+  if (
+    !configured ||
+    getDeploymentTypeFromConfiguredDeployment(configured) === "local"
+  )
+    return null;
+  const name = stripDeploymentTypePrefix(configured);
+  return isAnonymousDeployment(name) ? null : name;
+}
+
+export async function bindProfileToDirectory(
+  ctx: Context,
+  name: string,
+  force = false,
+  target?: ProjectSelection,
+): Promise<boolean> {
+  const credentials = await readProfileCredentials(ctx, {
+    name,
+    source: "account selection",
+  });
+  loadProjectEnvironmentVariables();
+  const deployment = configuredCloudDeployment();
+  const selectedTarget =
+    target ??
+    (deployment === null
+      ? null
+      : {
+          kind: "deploymentName" as const,
+          deploymentName: deployment,
+          deploymentType: null,
+        });
+  if (!force && selectedTarget !== null) {
+    const label =
+      selectedTarget.kind === "teamAndProjectSlugs"
+        ? `project "${selectedTarget.teamSlug}/${selectedTarget.projectSlug}"`
+        : `deployment "${selectedTarget.kind === "deploymentName" ? selectedTarget.deploymentName : "configured"}"`;
+    const access = await projectAccess(
+      credentials!.accessToken,
+      selectedTarget,
+    );
+    if (access !== "yes") {
+      logWarning(
+        access === "no"
+          ? `Account "${name}" cannot access ${label}.`
+          : `Could not verify whether account "${name}" can access ${label}.`,
+      );
+      if (
+        !process.stdin.isTTY ||
+        !(await promptYesNo(ctx, {
+          message: `Use account "${name}" here anyway?`,
+          default: false,
+        }))
+      ) {
+        logMessage(
+          `Directory selection unchanged. To select this account anyway, run \`npx convex account select ${name} --force\`.`,
+        );
+        return false;
+      }
+    }
+  }
+  await writeProfileDirectory(ctx, name);
+  return true;
+}
+
+export async function profileLoginMetadata(
+  ctx: Context,
+  profile: ProfileSelection,
+  loginToken: string,
+  previous: ProfileCredentials | null,
+): Promise<Omit<ProfileCredentials, "accessToken">> {
+  let identity: { memberId: string; email: string } | null = null;
+  try {
+    const response = await profileApi(loginToken, "/api/dashboard/profile");
+    if (response.ok) {
+      const data = await response.json();
+      if (
+        (typeof data.id === "number" || typeof data.id === "string") &&
+        typeof data.email === "string"
+      ) {
+        identity = { memberId: String(data.id), email: data.email };
+      }
+    }
+  } catch {
+    // Older authentication tokens can be valid without access to the dashboard profile API.
+  }
+  const sameAccount =
+    previous !== null && (previous.memberId === undefined || identity === null)
+      ? await tokensBelongToSameAccount(previous.accessToken, loginToken)
+      : null;
+  if (
+    previous !== null &&
+    (previous.memberId === undefined || identity === null
+      ? sameAccount !== true
+      : identity.memberId !== previous.memberId)
+  ) {
+    return await ctx.crash({
+      exitCode: 1,
+      errorType: "fatal",
+      printedMessage:
+        sameAccount === null &&
+        (previous.memberId === undefined || identity === null)
+          ? `Could not verify the identity of saved account "${profile.name}". To replace this saved login, run \`npx convex logout --account ${profile.name}\` followed by \`npx convex login --account ${profile.name}\`. Choose the intended account when logging in.`
+          : `The login does not match saved account "${profile.name}". Log in with the matching account, or choose another name with \`npx convex login --account <name>\`.`,
+    });
+  }
+  return {
+    ...(identity ??
+      (previous?.memberId === undefined
+        ? {}
+        : { memberId: previous.memberId, email: previous.email })),
+  };
+}
+
+async function tokensBelongToSameAccount(
+  older: string,
+  newer: string,
+): Promise<boolean | null> {
+  try {
+    const responses = await Promise.all(
+      [older, newer].map((token) =>
+        profileApi(token, "/v1/list_personal_access_tokens?limit=100"),
+      ),
+    );
+    if (responses.some((response) => !response.ok)) return null;
+    const lists = await Promise.all(
+      responses.map((response) => response.json()),
+    );
+    if (
+      lists.some(
+        (list) => !Array.isArray(list.items) || list.items.length === 0,
+      )
+    )
+      return null;
+    const ids = new Set(
+      lists[0].items.map((token: { id: unknown }) => String(token.id)),
+    );
+    if (
+      lists[1].items.some((token: { id: unknown }) => ids.has(String(token.id)))
+    )
+      return true;
+    // Disjoint partial pages cannot establish that the accounts differ.
+    return lists.some((list) => list.pagination?.hasMore !== false)
+      ? null
+      : false;
+  } catch {
+    return null;
+  }
+}
+
+export async function revokeReplacedProfileToken(
+  ctx: Context,
+  previous: string | undefined,
+  accessToken: string,
+) {
+  if (previous === undefined || previous === accessToken) return;
+  const settings = await readProfileSettings(ctx);
+  if (
+    settings.revokeReplacedTokens === false ||
+    settings.accessToken === previous
+  )
+    return;
+  for (const name of savedProfileNames(ctx)) {
+    const token = readProfileToken(ctx, name);
+    if (token === null) {
+      logWarning(
+        `The new login was saved, but account "${name}" could not be read. Skipping revocation of the replaced token.`,
+      );
+      return;
+    }
+    if (token === previous) return;
+  }
+  try {
+    // The API verifies token ownership using the newly authenticated account.
+    const response = await profileApi(
+      accessToken,
+      "/v1/delete_personal_access_token",
+      { id: previous },
+    );
+    if (response.ok) return;
+  } catch {
+    // The new credentials are already saved, so a failed revocation can be retried in the dashboard.
+  }
+  logWarning(
+    "The new login was saved, but the replaced token could not be revoked. You can remove it in the dashboard's account settings.",
+  );
+}