convex 1.48.0 → 1.49.0-alpha.0

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "convex",
   "description": "Client for the Convex Cloud",
-  "version": "1.48.0",
+  "version": "1.49.0-alpha.0",
   "author": "Convex, Inc. <no-reply@convex.dev>",
   "homepage": "https://convex.dev",
   "repository": {
@@ -213,7 +213,7 @@
     "@inquirer/search": "^4.1.0",
     "@inquirer/select": "^5.0.4",
     "@inquirer/testing": "^3.3.0",
-    "@modelcontextprotocol/server": "^2.0.0",
+    "@modelcontextprotocol/server": "^2.3.0",
     "@octokit/openapi-types": "~27.0.0",
     "@sentry/node": "^7.23.0",
     "@sentry/tracing": "^7.23.0",

package/src/bundler/context.ts

@@ -54,6 +54,7 @@ export type BigBrainAuth = {
   | {
       kind: "accessToken";
       accessToken: string;
+      account?: { name: string; source: string } | null;
     }
 );
 
@@ -190,16 +191,19 @@ export const oneoffContext: (args: {
   url?: string | undefined;
   adminKey?: string | undefined;
   envFile?: string | undefined;
+  skipAuth?: boolean;
 }) => Promise<OneoffCtx> = async (args) => {
   const ctx = new OneoffContextImpl();
   await detectSuspiciousEnvironmentVariables(
     ctx,
     !!process.env.CONVEX_IGNORE_SUSPICIOUS_ENV_VARS,
   );
-  await initializeBigBrainAuth(ctx, {
-    url: args.url,
-    adminKey: args.adminKey,
-    envFile: args.envFile,
-  });
+  if (!args.skipAuth) {
+    await initializeBigBrainAuth(ctx, {
+      url: args.url,
+      adminKey: args.adminKey,
+      envFile: args.envFile,
+    });
+  }
   return ctx;
 };

package/src/bundler/fs.ts

@@ -63,6 +63,7 @@ export interface Filesystem {
 
   exists(path: string): boolean;
   stat(path: string): Stats;
+  lstat(path: string): Stats;
   readUtf8File(path: string): string;
   // createReadStream returns a stream for which [Symbol.asyncIterator]
   // yields chunks of size highWaterMark (until the last one), or 64KB if
@@ -153,6 +154,9 @@ export class NodeFs implements Filesystem {
   stat(path: string) {
     return stdFs.statSync(path);
   }
+  lstat(path: string) {
+    return stdFs.lstatSync(path);
+  }
   readUtf8File(path: string) {
     return stdFs.readFileSync(path, { encoding: "utf-8" });
   }
@@ -260,6 +264,9 @@ export class RecordingFs implements Filesystem {
   // Absolute path -> observed stat (or null if observed nonexistent)
   private observedFiles: Map<string, Stats | null> = new Map();
 
+  // lstat observes the link itself, while stat observes its target.
+  private observedLstats: Map<string, Stats | null> = new Map();
+
   // Have we noticed that files have changed while recording?
   private invalidated = false;
 
@@ -305,6 +312,20 @@ export class RecordingFs implements Filesystem {
     return entries;
   }
 
+  lstat(filePath: string): Stats {
+    const absPath = path.resolve(filePath);
+    try {
+      const st = nodeFs.lstat(filePath);
+      this.registerNormalized(absPath, st, this.observedLstats);
+      return st;
+    } catch (err: any) {
+      if (err.code === "ENOENT") {
+        this.registerNormalized(absPath, null, this.observedLstats);
+      }
+      throw err;
+    }
+  }
+
   exists(path: string): boolean {
     try {
       const st = nodeFs.stat(path);
@@ -419,6 +440,8 @@ export class RecordingFs implements Filesystem {
     const newSt = nodeFs.stat(absPath);
     // Skip invalidation checking since we don't want to conflict if we previously read this file.
     this.observedFiles.set(absPath, newSt);
+    if (this.observedLstats.has(absPath))
+      this.observedLstats.set(absPath, nodeFs.lstat(absPath));
 
     // If we observed the parent, add our newly created file.
     const parentPath = path.resolve(path.dirname(absPath));
@@ -430,6 +453,8 @@ export class RecordingFs implements Filesystem {
   private updateOnDelete(absPath: string) {
     // Expect this file to be gone.
     this.observedFiles.set(absPath, null);
+    if (this.observedLstats.has(absPath))
+      this.observedLstats.set(absPath, null);
 
     // Unlink it from our parent if observed.
     const parentPath = path.resolve(path.dirname(absPath));
@@ -448,8 +473,12 @@ export class RecordingFs implements Filesystem {
     this.invalidated = true;
   }
 
-  registerNormalized(absPath: string, observed: Stats | null): void {
-    const existing = this.observedFiles.get(absPath);
+  registerNormalized(
+    absPath: string,
+    observed: Stats | null,
+    observations = this.observedFiles,
+  ): void {
+    const existing = observations.get(absPath);
     if (existing !== undefined) {
       const stMatch = stMatches(observed, existing);
       if (!stMatch.matches) {
@@ -466,14 +495,18 @@ export class RecordingFs implements Filesystem {
         this.invalidated = true;
       }
     }
-    this.observedFiles.set(absPath, observed);
+    observations.set(absPath, observed);
   }
 
   finalize(): Observations | "invalidated" {
     if (this.invalidated) {
       return "invalidated";
     }
-    return new Observations(this.observedDirectories, this.observedFiles);
+    return new Observations(
+      this.observedDirectories,
+      this.observedFiles,
+      this.observedLstats,
+    );
   }
 }
 
@@ -489,6 +522,7 @@ export class Observations {
   constructor(
     directories: Map<string, Set<string>>,
     files: Map<string, Stats | null>,
+    private lstats: Map<string, Stats | null> = new Map(),
   ) {
     this.directories = directories;
     this.files = files;
@@ -502,7 +536,8 @@ export class Observations {
     for (const path of this.files.keys()) {
       out.push(path);
     }
-    return out;
+    for (const path of this.lstats.keys()) out.push(path);
+    return [...new Set(out)];
   }
 
   overlaps({
@@ -529,6 +564,20 @@ export class Observations {
       }
     }
 
+    const observedLstat = this.lstats.get(absPath);
+    if (observedLstat !== undefined) {
+      let currentLstat: Stats | null;
+      try {
+        currentLstat = nodeFs.lstat(absPath);
+      } catch (err: any) {
+        if (err.code !== "ENOENT") throw err;
+        currentLstat = null;
+      }
+      const match = stMatches(observedLstat, currentLstat);
+      if (!match.matches)
+        return { overlaps: true, reason: `modified (${match.reason})` };
+    }
+
     // Second, check if we listed the directory this file is in.
     const parentPath = path.resolve(path.dirname(absPath));
     const observedParent = this.directories.get(parentPath);

package/src/cli/account.ts

@@ -0,0 +1,320 @@
+import { Command } from "@commander-js/extra-typings";
+import path from "path";
+import { createLoginCommand } from "./login.js";
+import { createLogoutCommand } from "./logout.js";
+import { Context, oneoffContext } from "../bundler/context.js";
+import {
+  logFinishedStep,
+  logMessage,
+  logOutput,
+  logWarning,
+} from "../bundler/log.js";
+import { loadProjectEnvironmentVariables } from "./lib/envvars.js";
+import { isAuthorizedHeader, performLogin } from "./lib/login.js";
+import {
+  getAccountSelection,
+  initializeDefaultAccount,
+  readAccountAuth,
+  readAccountCredentials,
+  readAccountSettings,
+  savedAccountNames,
+  validateAccountName,
+  updateAccountSettings,
+} from "./lib/accounts.js";
+import {
+  bindAccountToDirectory,
+  projectAccess,
+} from "./lib/accountManagement.js";
+import { warnIfDeployKeyOverridesLogin } from "./lib/deployKeyWarning.js";
+import { ProjectSelection } from "./lib/deploymentSelection.js";
+import { promptOptions, promptString } from "./lib/utils/prompts.js";
+
+async function accountContext() {
+  const ctx = await oneoffContext({ skipAuth: true });
+  loadProjectEnvironmentVariables();
+  return ctx;
+}
+
+const accountList = new Command("list")
+  .description(
+    "List saved accounts, credential status, and directory selections",
+  )
+  .allowExcessArguments(false)
+  .action(async () => {
+    const ctx = await accountContext();
+    const settings = await readAccountSettings(ctx);
+    const selected = await getAccountSelection(ctx);
+    const names = new Set([
+      ...savedAccountNames(ctx),
+      ...Object.values(settings.directories ?? {}),
+      ...(settings.defaultAccount === undefined
+        ? []
+        : [settings.defaultAccount]),
+      ...(selected === null ? [] : [selected.name]),
+    ]);
+    warnIfDeployKeyOverridesLogin(
+      ctx,
+      typeof settings.accessToken === "string" ||
+        savedAccountNames(ctx).length > 0,
+    );
+    if (names.size === 0) {
+      logMessage(
+        typeof settings.accessToken === "string"
+          ? (await isAuthorizedHeader(ctx, `Bearer ${settings.accessToken}`))
+            ? "Logged in without a named account. Name this login with `npx convex login --account personal --select`."
+            : "Your saved login is no longer valid. Run `npx convex login --account <name>`."
+          : "No saved accounts. Run `npx convex login --account <name>`.",
+      );
+      return;
+    }
+    if (selected !== null)
+      logMessage(`Selected account: ${selected.name} (${selected.source})`);
+    if (settings.defaultAccount !== undefined)
+      logMessage(`Default account: ${settings.defaultAccount}`);
+    for (const name of [...names].sort()) {
+      const credentials = await readAccountCredentials(
+        ctx,
+        { name, source: "saved accounts" },
+        true,
+      );
+      const valid =
+        credentials !== null &&
+        (await isAuthorizedHeader(ctx, `Bearer ${credentials.accessToken}`));
+      const label = `${name}${credentials?.email ? ` (${credentials.email})` : ""}`;
+      const status =
+        credentials === null
+          ? " ⚠️ Not logged in"
+          : valid
+            ? ""
+            : " ⚠️ Invalid credentials";
+      logOutput(`${label}${status}`);
+      for (const [directory, account] of Object.entries(
+        settings.directories ?? {},
+      )) {
+        if (account === name) logOutput(`    ${directory}`);
+      }
+    }
+  });
+
+const accountSelect = new Command("select")
+  .description("Use a saved account in this directory and its subdirectories")
+  .argument("<account>", "Account name, such as work or personal")
+  .option(
+    "--force",
+    "Select this account even if deployment access cannot be verified",
+  )
+  .allowExcessArguments(false)
+  .action(async (name, options) => {
+    const ctx = await accountContext();
+    if (!(await bindAccountToDirectory(ctx, name, options.force))) {
+      await ctx.crash({
+        exitCode: 1,
+        errorType: "fatal",
+        printedMessage: null,
+      });
+    }
+  });
+
+const accountDefault = new Command("default")
+  .description(
+    "Show or set the default account for directories without a directory selection",
+  )
+  .argument("[account]", "Account name")
+  .allowExcessArguments(false)
+  .action(async (name) => {
+    const ctx = await accountContext();
+    if (name === undefined) {
+      const settings = await readAccountSettings(ctx);
+      logOutput(
+        settings.defaultAccount === undefined
+          ? "No default account is set."
+          : `Default account: ${settings.defaultAccount}`,
+      );
+      return;
+    }
+    await updateAccountSettings(ctx, async (settings) => {
+      const credentials = await readAccountCredentials(ctx, {
+        name,
+        source: "account default",
+      });
+      settings.defaultAccount = name;
+      settings.accessToken = credentials!.accessToken;
+    });
+    logFinishedStep(`Default account: ${name}`);
+  });
+
+const accountDeselect = new Command("deselect")
+  .description(
+    "Clear this directory's account selection, inheriting its parent's selection or the default",
+  )
+  .allowExcessArguments(false)
+  .action(async () => {
+    const ctx = await accountContext();
+    const directory = path.resolve(process.cwd());
+    const removed = await updateAccountSettings(ctx, (settings) => {
+      if (
+        settings.directories &&
+        Object.hasOwn(settings.directories, directory)
+      ) {
+        delete settings.directories[directory];
+        return true;
+      }
+      return false;
+    });
+    if (removed)
+      logFinishedStep(`Removed the directory selection for ${directory}.`);
+    else logMessage(`No directory selection is saved for ${directory}.`);
+    const selected = await getAccountSelection(ctx);
+    if (selected !== null)
+      logMessage(`Selected account: ${selected.name} (${selected.source})`);
+  });
+
+const accountSettings = new Command("settings")
+  .summary("Show or change account settings")
+  .description(
+    "Show or change account settings.\n\n" +
+      "Renewing an account login revokes its replaced personal access token unless another saved login uses it. To keep replaced tokens active, run:\n\n" +
+      "  `npx convex@latest account settings revoke-replaced-tokens false`",
+  )
+  .argument("[name]", "revoke-replaced-tokens")
+  .argument("[value]", "true or false")
+  .allowExcessArguments(false)
+  .action(async (name, value, _options, cmd) => {
+    const ctx = await accountContext();
+    const settings = await readAccountSettings(ctx);
+    if (name === undefined && value === undefined) {
+      logOutput(
+        `revoke-replaced-tokens: ${settings.revokeReplacedTokens ?? true}`,
+      );
+      return;
+    }
+    if (
+      name !== "revoke-replaced-tokens" ||
+      (value !== "true" && value !== "false")
+    ) {
+      cmd.error(
+        "Usage: npx convex account settings revoke-replaced-tokens <true|false>",
+      );
+    }
+    await updateAccountSettings(ctx, (settings) => {
+      settings.revokeReplacedTokens = value === "true";
+    });
+    logFinishedStep(`Set revoke-replaced-tokens to ${value}.`);
+  });
+
+export const account = new Command("account")
+  .summary("Manage saved accounts and their directory selections")
+  .description(
+    "Manage saved accounts and their directory selections.\n\n" +
+      "Save logins for multiple Convex accounts under names such as work and personal. `npx convex@latest account login` and `npx convex@latest account logout` are aliases for the top-level login and logout commands, with the same options. Select the appropriate account for each personal, work, or client project.\n\n" +
+      "In your personal project directory, save an account:\n\n" +
+      "  `npx convex@latest login --account personal --select`\n\n" +
+      "In your work project directory, log in with your work account and check its teams:\n\n" +
+      "  `npx convex@latest login --account work --select`\n" +
+      "  `npx convex@latest login status`\n\n" +
+      "Choose the appropriate account in the browser; sign out of the dashboard first if it is using another account. Upgrade each project's `convex` dependency to a version that supports saved accounts, then run `npx convex dev` to develop with its selected account.\n\n" +
+      "`login --account` saves credentials without changing directory selections. Add `--select` to select the account for this directory and its subdirectories after checking deployment access. The first saved account becomes the default if no other account is saved. To select a saved account in another directory, run `npx convex@latest account select work`. Run `npx convex@latest account deselect` to remove this directory's selection and inherit its parent or default. Run `npx convex@latest account default` to show the default, or `npx convex@latest account default work` to change it. The closest directory selection wins. Selections use absolute paths, so select the account again after moving a project.\n\n" +
+      "The first account name is assigned to your existing login if you are already logged in, and becomes the default for directories without a selection. Use `--force` to authenticate another account instead, keeping the existing login as the default. Names start with a lowercase letter or number and contain only lowercase letters, numbers, hyphens, and underscores.\n\n" +
+      "`CONVEX_ACCOUNT` in the shell or project env file overrides directory selections and the default account. Deployment and project keys take priority over saved accounts.\n\n" +
+      "Use `npx convex@latest logout --account work` to remove one account's credentials, or `npx convex@latest logout --all` to remove all saved credentials. Logout preserves directory selections; a logged-out account requires login before use.\n\n" +
+      "After saving accounts, use `npx convex@latest` for login, logout, and account commands in every project directory on this machine. Plain `npx convex` can run the older version installed in that project. Specifying `@latest` runs the latest published CLI without updating the project's dependency.\n\n" +
+      "Older CLIs ignore directory selections and `CONVEX_ACCOUNT`, using the shared login instead (normally the default account). Upgrade the project's `convex` dependency to use saved accounts with project commands such as `npx convex dev` and `npx convex deploy`.\n\n" +
+      "Logging in with an older CLI can change the shared login independently of your saved accounts, or discard account settings if the shared login has been removed. Logging out with an older CLI deletes directory selections and the default selection but leaves named account credentials behind. Recreate any lost selections with `npx convex@latest account select <name>` and `npx convex@latest account default <name>`.\n\n" +
+      "Renewing an account login can revoke its previous token and interrupt running CLI processes of any version that still use it. Restart those commands after renewing the login, or keep replaced tokens active with `npx convex@latest account settings revoke-replaced-tokens false`.",
+  )
+  .addCommand(accountList)
+  .addCommand(accountSelect)
+  .addCommand(accountDefault)
+  .addCommand(accountDeselect)
+  .addCommand(accountSettings)
+  .addCommand(createLoginCommand())
+  .addCommand(createLogoutCommand())
+  .addHelpCommand(false);
+
+export async function handleNoAccessToConfiguredProject(
+  ctx: Context,
+  target: ProjectSelection,
+  envFile?: string,
+): Promise<"retry" | "chooseProject"> {
+  const auth = ctx.bigBrainAuth();
+  const current = auth?.kind === "accessToken" ? auth.account?.name : undefined;
+  const project =
+    target.kind === "deploymentName"
+      ? `deployment "${target.deploymentName}"`
+      : target.kind === "teamAndProjectSlugs"
+        ? `project "${target.teamSlug}/${target.projectSlug}"`
+        : "the configured project";
+  logWarning(
+    `${current ? `Account "${current}"` : "Your account"} cannot access ${project}. It may belong to another account.`,
+  );
+  const alternatives: string[] = [];
+  if (target.kind !== "projectDeployKey") {
+    for (const name of savedAccountNames(ctx)) {
+      if (name === current) continue;
+      const credentials = await readAccountCredentials(ctx, {
+        name,
+        source: "saved accounts",
+      });
+      if ((await projectAccess(credentials!.accessToken, target)) === "yes")
+        alternatives.push(name);
+    }
+  }
+  if (!process.stdin.isTTY) {
+    const selection = await getAccountSelection(ctx, { envFile });
+    const overrideHint = selection?.source.startsWith("CONVEX_ACCOUNT")
+      ? ` Update or unset CONVEX_ACCOUNT (${selection.source}) before retrying.`
+      : "";
+    return await ctx.crash({
+      exitCode: 1,
+      errorType: "fatal",
+      printedMessage: `${
+        alternatives.length > 0
+          ? `A saved account can access it: ${alternatives.map((name) => `\`npx convex account select ${name}\``).join(" or ")}.`
+          : "Log in to its account with `npx convex login --account <name> --select`."
+      }${overrideHint} To select a different project, run \`npx convex dev --configure\` (this changes CONVEX_DEPLOYMENT).`,
+    });
+  }
+  type Choice =
+    | { kind: "use"; name: string }
+    | { kind: "login" }
+    | { kind: "chooseProject" };
+  const choice = await promptOptions<Choice>(ctx, {
+    message: "Which account should this project use?",
+    choices: [
+      ...alternatives.map((name) => ({
+        name: `Use account "${name}"`,
+        value: { kind: "use", name } as const,
+      })),
+      { name: "Log in to another account", value: { kind: "login" } as const },
+      {
+        name: "Configure a different project (changes CONVEX_DEPLOYMENT)",
+        value: { kind: "chooseProject" } as const,
+      },
+    ],
+  });
+  if (choice.kind === "chooseProject") return "chooseProject";
+  const name =
+    choice.kind === "use"
+      ? choice.name
+      : await promptString(ctx, {
+          message: "Account name (for example, work):",
+        });
+  await validateAccountName(ctx, name);
+  if (choice.kind === "login") {
+    const selection = { name, source: "account recovery" };
+    await performLogin(ctx, { account: selection });
+    await initializeDefaultAccount(ctx, selection, false);
+  }
+  if (!(await bindAccountToDirectory(ctx, name, false, target)))
+    return "chooseProject";
+  const selection = await getAccountSelection(ctx, { envFile });
+  if (selection?.name !== name) {
+    return await ctx.crash({
+      exitCode: 1,
+      errorType: "invalid filesystem or env vars",
+      printedMessage: `Remove the account override from ${selection?.source} before retrying.`,
+    });
+  }
+  ctx._updateBigBrainAuth(await readAccountAuth(ctx, selection));
+  return "retry";
+}

package/src/cli/configure.ts

@@ -1,4 +1,5 @@
 import { chalkStderr } from "chalk";
+import { handleNoAccessToConfiguredProject } from "./account.js";
 import { Context } from "../bundler/context.js";
 import {
   logFailure,
@@ -350,11 +351,26 @@ async function handleDeploymentWithinProject(
     return result;
   }
 
-  const accessResult = await checkAccessToSelectedProject(
+  let accessResult = await checkAccessToSelectedProject(
     ctx,
     deploymentSelection.targetProject,
   );
-  if (accessResult.kind === "noAccess") {
+  while (accessResult.kind === "noAccess") {
+    const next =
+      cmdOptions.team !== undefined && cmdOptions.project !== undefined
+        ? "chooseProject"
+        : await handleNoAccessToConfiguredProject(
+            ctx,
+            deploymentSelection.targetProject,
+            cmdOptions.envFile,
+          );
+    if (next === "retry") {
+      accessResult = await checkAccessToSelectedProject(
+        ctx,
+        deploymentSelection.targetProject,
+      );
+      continue;
+    }
     logMessage("You don't have access to the selected project.");
     const result = await handleChooseProject(
       ctx,