convex 1.48.0 → 1.49.0-alpha.0

package/src/cli/lib/deployment.ts

@@ -102,7 +102,7 @@ export async function eraseDeploymentEnvVar(ctx: Context): Promise<boolean> {
   return true;
 }
 
-async function gitIgnoreEnvVarFile(ctx: Context): Promise<boolean> {
+export async function gitIgnoreEnvVarFile(ctx: Context): Promise<boolean> {
   const gitIgnorePath = ".gitignore";
   const gitIgnoreContents = ctx.fs.exists(gitIgnorePath)
     ? ctx.fs.readUtf8File(gitIgnorePath)
@@ -186,7 +186,7 @@ export async function deploymentNameFromAdminKeyOrCrash(
   return deploymentName;
 }
 
-function deploymentNameFromAdminKey(adminKey: string) {
+export function deploymentNameFromAdminKey(adminKey: string) {
   const parts = adminKey.split("|");
   if (parts.length === 1) {
     return null;

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 {
+  getAccountSelection,
+  AccountSelection,
+  readAccountAuth,
+} from "./accounts.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,
+        skipAccount: 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,
+  account?: AccountSelection,
 ) {
   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}`,
+    ...(account ? { account } : {}),
   });
 }
 
@@ -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;
+    skipAccount?: 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}`,
+      account: null,
     };
   }
   if (opts.projectKey !== null) {
@@ -200,12 +215,19 @@ function getBigBrainAuth(
       deploymentKey: opts.deploymentKey,
     };
   }
+  const account = opts.skipAccount
+    ? null
+    : await getAccountSelection(ctx, { envFile: opts.envFile });
+  if (account !== null) {
+    return await readAccountAuth(ctx, account);
+  }
   const globalConfig = readGlobalConfig(ctx);
   if (globalConfig) {
     return {
       kind: "accessToken",
       header: `Bearer ${globalConfig.accessToken}`,
       accessToken: globalConfig.accessToken,
+      account: 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

@@ -20,6 +20,7 @@ import {
   logMessage,
   logOutput,
   logVerbose,
+  logWarning,
   showSpinner,
 } from "../../bundler/log.js";
 import { Issuer } from "openid-client";
@@ -32,6 +33,18 @@ import {
   modifyGlobalConfig,
 } from "./utils/globalConfig.js";
 import { updateBigBrainAuthAfterLogin } from "./deploymentSelection.js";
+import {
+  getAccountSelection,
+  AccountSelection,
+  accountConfigPath,
+  writeAccountCredentials,
+  readAccountCredentials,
+} from "./accounts.js";
+import {
+  accountApi,
+  accountLoginMetadata,
+  revokeReplacedAccountToken,
+} from "./accountManagement.js";
 
 // Per https://github.com/panva/node-openid-client/tree/main/docs#customizing
 custom.setHttpOptionsDefaults({
@@ -291,6 +304,7 @@ export async function performLogin(
     anonymousId,
     vercel,
     vercelOverride,
+    account: selectedAccount,
   }: {
     overrideAuthUrl?: string | undefined;
     overrideAuthClient?: string | undefined;
@@ -307,8 +321,16 @@ export async function performLogin(
     anonymousId?: string | undefined;
     vercel?: boolean | undefined;
     vercelOverride?: string | undefined;
+    account?: AccountSelection | null;
   } = {},
 ) {
+  const auth = ctx.bigBrainAuth();
+  const account =
+    selectedAccount !== undefined
+      ? selectedAccount
+      : auth?.kind === "accessToken" && auth.account !== undefined
+        ? auth.account
+        : await getAccountSelection(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 +422,12 @@ export async function performLogin(
   }
 
   // Exchange the WorkOS access token for a Convex personal access token.
+  const previous =
+    account === null ? null : await readAccountCredentials(ctx, account, true);
+  const metadata =
+    account === null
+      ? {}
+      : await accountLoginMetadata(ctx, account, accessToken, previous);
   ctx._updateBigBrainAuth({
     accessToken: accessToken,
     kind: "accessToken",
@@ -417,8 +445,34 @@ export async function performLogin(
   const newAccessToken = response.data!.accessToken;
   const globalConfig = { accessToken: newAccessToken };
   try {
-    await modifyGlobalConfig(ctx, globalConfig);
-    const path = globalConfigPath();
+    if (account !== null) {
+      await writeAccountCredentials(
+        ctx,
+        account.name,
+        newAccessToken,
+        metadata,
+        previous,
+        async () => {
+          try {
+            const response = await accountApi(
+              newAccessToken,
+              "/v1/delete_personal_access_token",
+              { id: newAccessToken },
+            );
+            if (response.ok) return;
+          } catch {
+            // Report cleanup failure alongside the account conflict below.
+          }
+          logWarning(
+            "The unused login token could not be revoked. You can remove it in the dashboard's account settings.",
+          );
+        },
+      );
+    } else {
+      await modifyGlobalConfig(ctx, globalConfig);
+    }
+    const path =
+      account !== null ? accountConfigPath(account.name) : globalConfigPath();
     logFinishedStep(`Saved credentials to ${formatPathForPrinting(path)}`);
   } catch (err: unknown) {
     return await ctx.crash({
@@ -429,8 +483,15 @@ export async function performLogin(
     });
   }
 
+  if (account !== null) {
+    await revokeReplacedAccountToken(
+      ctx,
+      previous?.accessToken,
+      newAccessToken,
+    );
+  }
   logVerbose(`performLogin: updating big brain auth after login`);
-  await updateBigBrainAuthAfterLogin(ctx, newAccessToken);
+  await updateBigBrainAuthAfterLogin(ctx, newAccessToken, account ?? 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/plugins/claudeCode.ts

@@ -0,0 +1,201 @@
+import os from "os";
+import path from "path";
+import * as Sentry from "@sentry/node";
+import { z } from "zod";
+import type { Cli, Places } from "./harness.js";
+import {
+  convexMarketplaces,
+  type Marketplace,
+  type Plugin,
+  type Source,
+} from "./marketplaces.js";
+import {
+  fetchGitHubJson,
+  onPath,
+  parseList,
+  subfolders,
+  versionOf,
+} from "./utils.js";
+
+/** Builds `getClaudeCodeLocations` for the given places, so tests can point it at fixtures. */
+export const createGetClaudeCodeLocations =
+  (places: Omit<Places, "applications">) => async (): Promise<Cli[]> => {
+    const found: Omit<Cli, "version">[] = [
+      ...onPath("claude", places.path).map((p) => ({
+        source: "terminal" as const,
+        path: p,
+      })),
+      // The desktop app keeps every version it downloaded, as
+      // `<version>/<hash>/claude.app`, next to its own state files.
+      ...subfolders(
+        path.join(
+          places.home,
+          "Library",
+          "Application Support",
+          "Claude",
+          "claude-code",
+        ),
+      )
+        .flatMap(subfolders)
+        .map((dir) => ({
+          source: "desktop" as const,
+          path: path.join(dir, "claude.app", "Contents", "MacOS", "claude"),
+        })),
+      ...subfolders(path.join(places.home, ".vscode", "extensions"))
+        .filter((dir) =>
+          path.basename(dir).startsWith("anthropic.claude-code-"),
+        )
+        .map((dir) => ({
+          source: "vscode" as const,
+          path: path.join(dir, "resources", "native-binary", "claude"),
+        })),
+    ];
+    return Promise.all(
+      found.map(async (cli) => ({
+        ...cli,
+        version: await versionOf(cli.path),
+      })),
+    );
+  };
+
+/** Every copy of Claude Code on this machine: the terminal CLI, the Claude desktop app's copies and the VS Code extension's copies. */
+export const getClaudeCodeLocations = createGetClaudeCodeLocations({
+  home: os.homedir(),
+  path: process.env.PATH ?? "",
+});
+
+/** The newest Convex plugin a Claude Code user can install, which is the commit Anthropic's marketplace pins, not our main. */
+export async function claudeCodeLatest(): Promise<Record<string, string>> {
+  const marketplace = await fetchGitHubJson<{
+    plugins: { name: string; source: { url: string; sha: string } }[];
+  }>("anthropics/claude-plugins-official/main/.claude-plugin/marketplace.json");
+  if (marketplace === null) return {};
+  const source = marketplace.plugins.find((p) => p.name === "convex")?.source;
+  if (source === undefined) {
+    Sentry.captureMessage(
+      "Anthropic's marketplace has no convex plugin",
+      "error",
+    );
+    return {};
+  }
+  const repo = source.url
+    .replace(/^https:\/\/github\.com\//, "")
+    .replace(/\.git$/, "");
+  const plugin = await fetchGitHubJson<{ version: string }>(
+    `${repo}/${source.sha}/.claude-plugin/plugin.json`,
+  );
+  return plugin === null ? {} : { convex: plugin.version };
+}
+
+/** `claude plugin marketplace list --json` */
+const claudeCodeMarketplaceList = z.array(
+  z.union([
+    z.object({
+      name: z.string(),
+      source: z.literal("github"),
+      repo: z.string(),
+    }),
+    z.object({ name: z.string(), source: z.literal("git"), url: z.string() }),
+    z.object({
+      name: z.string(),
+      source: z.literal("directory"),
+      path: z.string(),
+    }),
+    // The list holds other people's marketplaces too, so a source type we
+    // haven't seen is kept by its type name instead of rejecting the list.
+    z.object({ name: z.string(), source: z.string() }),
+  ]),
+);
+
+/** Where a Claude Code marketplace comes from. zod keeps only the fields of the shape that matched. */
+function claudeCodeSource(
+  m: z.infer<typeof claudeCodeMarketplaceList>[number],
+): Source {
+  if ("repo" in m) return { kind: "github", repo: m.repo };
+  if ("url" in m) return { kind: "git", url: m.url };
+  if ("path" in m) return { kind: "folder", path: m.path };
+  return { kind: "other", type: m.source };
+}
+
+/** `claude plugin list --json` */
+const claudeCodePluginList = z.array(
+  z.object({
+    id: z.string(),
+    version: z.string(),
+    scope: z.string(),
+    enabled: z.boolean(),
+    folderVersion: z.string().optional(),
+  }),
+);
+
+/** Reads the plugins in `claude plugin list --json`, or returns null when it doesn't match. */
+function claudeCodePlugins(pluginList: string): Plugin[] | null {
+  const plugins = parseList(
+    claudeCodePluginList,
+    pluginList,
+    "claude plugin list --json",
+  );
+  if (plugins === null) return null;
+  return plugins.map((p) => {
+    const [name, marketplace] = p.id.split("@");
+    // A folder install runs from the folder, and `version` is the copy cached at install time.
+    return {
+      name,
+      marketplace,
+      version: p.folderVersion ?? p.version,
+      scope: p.scope,
+      enabled: p.enabled,
+      cachedVersion:
+        p.folderVersion !== undefined && p.folderVersion !== p.version
+          ? p.version
+          : undefined,
+    };
+  });
+}
+
+/** Reads Claude Code's Convex marketplaces from `claude plugin marketplace list --json` and `claude plugin list --json`, or returns null when either doesn't match. */
+export function claudeCodeMarketplaces(
+  marketplaceList: string,
+  pluginList: string,
+): Marketplace[] | null {
+  const marketplaces = parseList(
+    claudeCodeMarketplaceList,
+    marketplaceList,
+    "claude plugin marketplace list --json",
+  );
+  const plugins = claudeCodePlugins(pluginList);
+  if (marketplaces === null || plugins === null) return null;
+  return convexMarketplaces(
+    marketplaces.map((m) => ({ name: m.name, source: claudeCodeSource(m) })),
+    plugins,
+  );
+}
+
+const pluginId = "convex@claude-plugins-official";
+/** The install step that brings an installed plugin to the latest version. When it fails, the user keeps an old version. */
+const upgradeStep = ["plugin", "update", pluginId, "--scope", "user"];
+
+/** Claude Code as `npx convex plugins` installs and reads it. */
+export const claudeCode = {
+  id: "claudeCode" as const,
+  name: "Claude Code",
+  plugin: pluginId,
+  upgradeStep,
+  installSteps: [
+    // Notes:
+    //
+    // 1. Claude Code updates its local copy of the marketplace when it
+    //    installs, but `plugin install` skips a plugin that's already
+    //    installed, so an old version stays until the plugin is updated.
+
+    // Add the marketplace
+    ["plugin", "marketplace", "add", "anthropics/claude-plugins-official"],
+    // Install the plugin if it isn't installed yet
+    ["plugin", "install", pluginId, "--scope", "user"],
+    // Update an installed plugin to the latest version
+    upgradeStep,
+  ],
+  plugins: claudeCodePlugins,
+  marketplaces: claudeCodeMarketplaces,
+  latest: claudeCodeLatest,
+};