convex 1.44.0 → 1.45.0-alpha.0

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "convex",
   "description": "Client for the Convex Cloud",
-  "version": "1.44.0",
+  "version": "1.45.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/sdk": "^1.25.2",
+    "@modelcontextprotocol/server": "^2.0.0",
     "@octokit/openapi-types": "~27.0.0",
     "@sentry/node": "^7.23.0",
     "@sentry/tracing": "^7.23.0",
@@ -277,7 +277,7 @@
   },
   "engines": {
     "npm": ">=7.0.0",
-    "node": ">=18.0.0"
+    "node": ">=20.0.0"
   },
   "scripts": {
     "build": "npm run generateApiSpec && python3 scripts/build.py 2>&1",

package/src/cli/convexExport.ts

@@ -46,7 +46,7 @@ export const convexExport = new Command("export")
       deploymentNotice,
       snapshotExportDashboardLink: deploymentDashboardUrlPage(
         deployment.deploymentFields?.deploymentName ?? null,
-        "/settings/snapshot-export",
+        "/settings/snapshots",
       ),
     });
   });

package/src/cli/index.ts

@@ -8,9 +8,8 @@ import { setGlobalDispatcher, EnvHttpProxyAgent } from "undici";
 import { logVerbose } from "../bundler/log.js";
 import { buildProgram } from "./program.js";
 
-const HARD_MINIMUM_NODE_MAJOR_VERSION = 16;
-const HARD_MINIMUM_NODE_MINOR_VERSION = 15;
-const SOFT_MINIMUM_NODE_MAJOR_VERSION = 20;
+const HARD_MINIMUM_NODE_MAJOR_VERSION = 20;
+const HARD_MINIMUM_NODE_MINOR_VERSION = 0;
 
 // console.error before it started being red by default in Node.js v20
 function logToStderr(...args: unknown[]) {
@@ -72,38 +71,6 @@ async function main() {
     process.exit(1);
   }
 
-  if (majorVersion < SOFT_MINIMUM_NODE_MAJOR_VERSION) {
-    logToStderr(
-      chalkStderr.yellow(
-        `Warning: Your Node version ${nodeVersion} is below the recommended minimum of Node v${SOFT_MINIMUM_NODE_MAJOR_VERSION}.x. Convex may work but could behave unexpectedly.`,
-      ),
-    );
-    logToStderr(
-      chalkStderr.gray(
-        `We recommend upgrading Node to v${SOFT_MINIMUM_NODE_MAJOR_VERSION} or newer.`,
-      ),
-    );
-    logToStderr(
-      chalkStderr.gray(
-        `You can use ${chalkStderr.bold(
-          "nvm",
-        )} (https://github.com/nvm-sh/nvm#installing-and-updating) to manage different versions of Node.`,
-      ),
-    );
-    logToStderr(
-      chalkStderr.gray(
-        "After installing `nvm`, install the latest version of Node with " +
-          chalkStderr.bold("`nvm install node`."),
-      ),
-    );
-    logToStderr(
-      chalkStderr.gray(
-        "Then, activate the installed version in your terminal with " +
-          chalkStderr.bold("`nvm use`."),
-      ),
-    );
-  }
-
   const program = buildProgram();
 
   // Run the command and be sure to flush Sentry before exiting.

package/src/cli/lib/api.ts

@@ -215,11 +215,17 @@ async function hasAccessToProject(
   selector: { projectSlug: string; teamSlug: string },
 ): Promise<boolean> {
   try {
-    await bigBrainAPIMaybeThrows({
-      ctx,
-      path: `teams/${selector.teamSlug}/projects/${selector.projectSlug}/deployments`,
-      method: "GET",
-    });
+    await typedPlatformClient(ctx, { throw: true }).GET(
+      "/teams/{team_id_or_slug}/projects/{project_slug}",
+      {
+        params: {
+          path: {
+            team_id_or_slug: selector.teamSlug,
+            project_slug: selector.projectSlug,
+          },
+        },
+      },
+    );
     return true;
   } catch (err) {
     if (

package/src/cli/lib/convexExport.ts

@@ -3,6 +3,7 @@ import {
   waitUntilCalled,
   deploymentFetch,
   logAndHandleFetchError,
+  ThrowingFetchError,
 } from "./utils/utils.js";
 import { Context } from "../../bundler/context.js";
 import {
@@ -12,6 +13,7 @@ import {
   logError,
   stopSpinner,
   changeSpinner,
+  failExistingSpinner,
 } from "../../bundler/log.js";
 import { subscribe } from "./run.js";
 import { nodeFs } from "../../bundler/fs.js";
@@ -46,6 +48,7 @@ export async function exportFromDeployment(
     inputPath,
     adminKey,
     deploymentUrl,
+    snapshotExportDashboardLink,
   });
 
   switch (snapshotExportState.state) {
@@ -156,6 +159,7 @@ export async function startSnapshotExport(
     inputPath: string;
     adminKey: string;
     deploymentUrl: string;
+    snapshotExportDashboardLink?: string | undefined;
   },
 ) {
   const fetch = deploymentFetch(ctx, {
@@ -170,6 +174,23 @@ export async function startSnapshotExport(
       },
     );
   } catch (e) {
+    if (
+      e instanceof ThrowingFetchError &&
+      e.serverErrorData?.code === "ExportInProgress"
+    ) {
+      failExistingSpinner();
+      const progressAdvice =
+        args.snapshotExportDashboardLink === undefined
+          ? ""
+          : `\nCheck its progress at ${args.snapshotExportDashboardLink}`;
+      return await ctx.crash({
+        exitCode: 1,
+        errorType: "fatal",
+        printedMessage:
+          "A snapshot export is already requested or in progress. Only one can run at a time, so wait for it to finish and try again." +
+          progressAdvice,
+      });
+    }
     return await logAndHandleFetchError(ctx, e);
   }
 

package/src/cli/lib/dashboard.ts

@@ -37,6 +37,8 @@ export async function getDashboardUrl(
   }
 }
 
+// FIXME: this doesn't work correctly in local-dev/self-hosted, where the
+// dashboard isn't at DASHBOARD_HOST and deployments aren't addressed by `/d/`.
 export function deploymentDashboardUrlPage(
   configuredDeployment: string | null,
   page: string,

package/src/cli/lib/generatedFunctionLogsApi.ts

@@ -101,6 +101,8 @@ export interface components {
             /** Format: int64 */
             databaseReadDocuments: number;
             /** Format: int64 */
+            databaseWriteDocuments: number;
+            /** Format: int64 */
             storageReadBytes: number;
             /** Format: int64 */
             storageWriteBytes: number;

package/src/cli/lib/localDeployment/upgrade.ts

@@ -1,35 +1,16 @@
-import path from "path";
 import { Context } from "../../../bundler/context.js";
 import {
-  logFailure,
   logFinishedStep,
   logVerbose,
+  logWarning,
 } from "../../../bundler/log.js";
-import { runSystemQuery } from "../run.js";
 import {
   LocalDeploymentConfig,
   LocalDeploymentKind,
-  deploymentStateDir,
   saveDeploymentConfig,
 } from "./filePaths.js";
-import {
-  ensureBackendStopped,
-  localDeploymentUrl,
-  runLocalBackend,
-} from "./run.js";
-import {
-  downloadSnapshotExport,
-  startSnapshotExport,
-} from "../convexExport.js";
-import { deploymentFetch, logAndHandleFetchError } from "../utils/utils.js";
-import {
-  confirmImport,
-  uploadForImport,
-  waitForStableImportState,
-} from "../convexImport.js";
-import { promptOptions, promptYesNo } from "../utils/prompts.js";
-import { recursivelyDelete } from "../fsUtils.js";
-import { LocalDeploymentError } from "./errors.js";
+import { runLocalBackend } from "./run.js";
+import { promptYesNo } from "../utils/prompts.js";
 import { ensureBackendBinaryDownloaded } from "./download.js";
 import {
   generateLocalDevSecretsWithLatestBinary,
@@ -126,44 +107,10 @@ export async function handlePotentialUpgradeAndStart(
     });
     return { cleanupHandle, adminKey };
   }
-  const choice =
-    args.forceUpgrade || !process.stdin.isTTY
-      ? "transfer"
-      : await promptOptions(ctx, {
-          message: "Transfer data from existing deployment?",
-          default: "transfer",
-          choices: [
-            { name: "transfer data", value: "transfer" },
-            { name: "start fresh", value: "reset" },
-          ],
-        });
-  const deploymentStatePath = deploymentStateDir(
-    ctx,
-    args.deploymentKind,
-    args.deploymentName,
-  );
-  if (choice === "reset") {
-    recursivelyDelete(ctx, deploymentStatePath, { force: true });
-    saveDeploymentConfig(
-      ctx,
-      args.deploymentKind,
-      args.deploymentName,
-      newConfig,
-    );
-    const { cleanupHandle } = await runLocalBackend(ctx, {
-      binaryPath: args.newBinaryPath,
-      deploymentKind: args.deploymentKind,
-      deploymentName: args.deploymentName,
-      ports: args.ports,
-      instanceSecret,
-      isLatestVersion: true,
-    });
-    return { cleanupHandle, adminKey };
-  }
   const { cleanupHandle } = await handleUpgrade(ctx, {
     deploymentKind: args.deploymentKind,
     deploymentName: args.deploymentName,
-    oldVersion: args.oldVersion!,
+    oldVersion: args.oldVersion,
     newBinaryPath: args.newBinaryPath,
     newVersion: args.newVersion,
     ports: args.ports,
@@ -174,6 +121,11 @@ export async function handlePotentialUpgradeAndStart(
   return { cleanupHandle, adminKey };
 }
 
+/**
+ * Upgrade in place: hand the existing data directory to the new binary, which
+ * migrates its own on-disk state on startup (the same path self-hosted
+ * deployments take).
+ */
 async function handleUpgrade(
   ctx: Context,
   args: {
@@ -191,80 +143,16 @@ async function handleUpgrade(
     cloudProjectId: number | undefined;
   },
 ): Promise<{ cleanupHandle: string }> {
-  const { adminKey } = args;
-  const { binaryPath: oldBinaryPath } = await ensureBackendBinaryDownloaded(
-    ctx,
-    {
-      kind: "version",
-      version: args.oldVersion,
-    },
-  );
-
-  logVerbose("Running backend on old version");
-  const { cleanupHandle: oldCleanupHandle } = await runLocalBackend(ctx, {
-    binaryPath: oldBinaryPath,
-    ports: args.ports,
-    deploymentKind: args.deploymentKind,
-    deploymentName: args.deploymentName,
-    instanceSecret: args.instanceSecret,
-    isLatestVersion: false,
-  });
-
-  logVerbose("Downloading env vars");
-  const deploymentUrl = localDeploymentUrl(args.ports.cloud);
-  const envs = (await runSystemQuery(ctx, {
-    deploymentUrl,
-    adminKey,
-    functionName: "_system/cli/queryEnvironmentVariables",
-    componentPath: undefined,
-    args: {},
-  })) as Array<{
-    name: string;
-    value: string;
-  }>;
-
-  logVerbose("Doing a snapshot export");
-  const exportPath = path.join(
-    deploymentStateDir(ctx, args.deploymentKind, args.deploymentName),
-    "export.zip",
-  );
-  if (ctx.fs.exists(exportPath)) {
-    ctx.fs.unlink(exportPath);
-  }
-  const snapshotExportState = await startSnapshotExport(ctx, {
-    deploymentUrl,
-    adminKey,
-    includeStorage: true,
-    inputPath: exportPath,
-  });
-  if (snapshotExportState.state !== "completed") {
-    return ctx.crash({
-      exitCode: 1,
-      errorType: "fatal",
-      printedMessage: "Failed to export snapshot",
-    });
+  const isDowngrade = _isDowngrade(args.oldVersion, args.newVersion);
+  if (isDowngrade) {
+    logWarning(
+      `Moving a local deployment back to an older backend version (${args.oldVersion} → ${args.newVersion}) isn't supported: ` +
+        `the older backend may not be able to read data written by the newer one. ` +
+        `If it fails to start, delete the deployment's state directory to start fresh on this version.`,
+    );
   }
-  await downloadSnapshotExport(ctx, {
-    snapshotExportTs: snapshotExportState.start_ts,
-    inputPath: exportPath,
-    adminKey,
-    deploymentUrl,
-  });
 
-  logVerbose("Stopping the backend on the old version");
-  const oldCleanupFunc = ctx.removeCleanup(oldCleanupHandle);
-  if (oldCleanupFunc) {
-    await oldCleanupFunc(0);
-  }
-  await ensureBackendStopped(ctx, {
-    ports: args.ports,
-    maxTimeSecs: 5,
-    deploymentName: args.deploymentName,
-    allowOtherDeployments: false,
-  });
-
-  // TODO(ENG-7078) save old artifacts to backup files
-  logVerbose("Running backend on new version");
+  logVerbose(`Running backend on new version ${args.newVersion}`);
   const { cleanupHandle } = await runLocalBackend(ctx, {
     binaryPath: args.newBinaryPath,
     ports: args.ports,
@@ -274,90 +162,29 @@ async function handleUpgrade(
     isLatestVersion: true,
   });
 
-  logVerbose("Importing the env vars");
-  if (envs.length > 0) {
-    const fetch = deploymentFetch(ctx, {
-      deploymentUrl,
-      adminKey,
-    });
-    try {
-      await fetch("/api/update_environment_variables", {
-        body: JSON.stringify({ changes: envs }),
-        method: "POST",
-      });
-    } catch (e) {
-      // TODO: this should ideally have a `LocalDeploymentError`
-      return await logAndHandleFetchError(ctx, e);
-    }
-  }
-
-  logVerbose("Doing a snapshot import");
-  const importId = await uploadForImport(ctx, {
-    deploymentUrl,
-    adminKey,
-    filePath: exportPath,
-    importArgs: { format: "zip", mode: "replace", tableName: undefined },
-    onImportFailed: async (e) => {
-      logFailure(`Failed to import snapshot: ${e}`);
-    },
-  });
-  logVerbose(`Snapshot import started`);
-  let status = await waitForStableImportState(ctx, {
-    importId,
-    deploymentUrl,
-    adminKey,
-    onProgress: () => {
-      // do nothing for now
-      return 0;
-    },
-  });
-  if (status.state !== "waiting_for_confirmation") {
-    const message = "Error while transferring data: Failed to upload snapshot";
-    return ctx.crash({
-      exitCode: 1,
-      errorType: "fatal",
-      printedMessage: message,
-      errForSentry: new LocalDeploymentError(message),
-    });
-  }
-
-  await confirmImport(ctx, {
-    importId,
-    adminKey,
-    deploymentUrl,
-    onError: async (e) => {
-      logFailure(`Failed to confirm import: ${e}`);
-    },
-  });
-  logVerbose(`Snapshot import confirmed`);
-  status = await waitForStableImportState(ctx, {
-    importId,
-    deploymentUrl,
-    adminKey,
-    onProgress: () => {
-      // do nothing for now
-      return 0;
-    },
-  });
-  logVerbose(`Snapshot import status: ${status.state}`);
-  if (status.state !== "completed") {
-    const message = "Error while transferring data: Failed to import snapshot";
-    return ctx.crash({
-      exitCode: 1,
-      errorType: "fatal",
-      printedMessage: message,
-      errForSentry: new LocalDeploymentError(message),
-    });
-  }
-
-  logFinishedStep("Successfully upgraded to a new backend version");
+  logFinishedStep(
+    `Successfully ${isDowngrade ? "moved" : "upgraded"} to backend version ${args.newVersion}`,
+  );
   saveDeploymentConfig(ctx, args.deploymentKind, args.deploymentName, {
     ports: args.ports,
     backendVersion: args.newVersion,
-    adminKey,
+    adminKey: args.adminKey,
     instanceSecret: args.instanceSecret,
     cloudProjectId: args.cloudProjectId,
   });
 
   return { cleanupHandle };
 }
+
+/** Whether `newVersion` predates `oldVersion`, as far as we can tell. */
+export function _isDowngrade(oldVersion: string, newVersion: string): boolean {
+  const oldDate = releaseDate(oldVersion);
+  const newDate = releaseDate(newVersion);
+  return oldDate !== null && newDate !== null && newDate < oldDate;
+}
+
+// Backend releases are tagged `precompiled-YYYY-MM-DD-<commit>`, so the dates
+// sort lexicographically.
+function releaseDate(version: string): string | null {
+  return /^precompiled-(\d{4}-\d{2}-\d{2})-/.exec(version)?.[1] ?? null;
+}

package/src/cli/lib/mcp/tools/index.ts

@@ -10,7 +10,7 @@ import { EnvListTool, EnvGetTool, EnvSetTool, EnvRemoveTool } from "./env.js";
 import { RunOneoffQueryTool } from "./runOneoffQuery.js";
 import { LogsTool } from "./logs.js";
 import { InsightsTool } from "./insights.js";
-import { Tool } from "@modelcontextprotocol/sdk/types.js";
+import { Tool } from "@modelcontextprotocol/server";
 
 export type ConvexTool<Input extends ZodTypeAny, Output extends ZodTypeAny> = {
   name: string;

package/src/cli/mcp.ts

@@ -1,14 +1,9 @@
 import { Command, Option } from "@commander-js/extra-typings";
 import { oneoffContext } from "../bundler/context.js";
-import { Server } from "@modelcontextprotocol/sdk/server/index.js";
-import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { CallToolRequest, Server } from "@modelcontextprotocol/server";
+import { StdioServerTransport } from "@modelcontextprotocol/server/stdio";
 import { actionDescription } from "./lib/command.js";
 import { checkAuthorization } from "./lib/login.js";
-import {
-  CallToolRequest,
-  CallToolRequestSchema,
-  ListToolsRequestSchema,
-} from "@modelcontextprotocol/sdk/types.js";
 import {
   McpOptions,
   RequestContext,
@@ -77,7 +72,7 @@ mcp
     }
   });
 
-function makeServer(options: McpOptions) {
+export function makeServer(options: McpOptions) {
   const disabledToolNames = new Set<string>();
   for (const toolName of options.disableTools?.split(",") ?? []) {
     const name = toolName.trim();
@@ -109,72 +104,69 @@ function makeServer(options: McpOptions) {
       },
     },
   );
-  server.setRequestHandler(
-    CallToolRequestSchema,
-    async (request: CallToolRequest) => {
-      const ctx = new RequestContext(options);
-      await initializeBigBrainAuth(ctx, options);
-      try {
-        const authorized = await checkAuthorization(ctx, false);
-        if (!authorized) {
-          await ctx.crash({
-            exitCode: 1,
-            errorType: "fatal",
-            printedMessage:
-              "Not Authorized: Run `npx convex dev` to login to your Convex project.",
-          });
-        }
-        if (!request.params.arguments) {
-          await ctx.crash({
-            exitCode: 1,
-            errorType: "fatal",
-            printedMessage: "No arguments provided",
-          });
-        }
-        const convexTool = enabledToolsByName[request.params.name];
-        if (!convexTool) {
-          await ctx.crash({
-            exitCode: 1,
-            errorType: "fatal",
-            printedMessage: `Tool ${request.params.name} not found`,
-          });
-        }
-        const input = convexTool.inputSchema.parse(request.params.arguments);
-
-        // Serialize tool handlers since they're mutating the current working directory.
-        const result = await mutex.runExclusive(async () => {
-          return await convexTool.handler(ctx, input);
+  server.setRequestHandler("tools/call", async (request: CallToolRequest) => {
+    const ctx = new RequestContext(options);
+    await initializeBigBrainAuth(ctx, options);
+    try {
+      const authorized = await checkAuthorization(ctx, false);
+      if (!authorized) {
+        await ctx.crash({
+          exitCode: 1,
+          errorType: "fatal",
+          printedMessage:
+            "Not Authorized: Run `npx convex dev` to login to your Convex project.",
         });
-        return {
-          content: [
-            {
-              type: "text",
-              text: JSON.stringify(result),
-            },
-          ],
-        };
-      } catch (error: any) {
-        let message: string;
-        if (error instanceof RequestCrash) {
-          message = error.printedMessage;
-        } else if (error instanceof Error) {
-          message = error.message;
-        } else {
-          message = String(error);
-        }
-        return {
-          content: [
-            {
-              type: "text",
-              text: JSON.stringify({ error: message }),
-            },
-          ],
-          isError: true,
-        };
       }
-    },
-  );
-  server.setRequestHandler(ListToolsRequestSchema, async () => {
+      if (!request.params.arguments) {
+        await ctx.crash({
+          exitCode: 1,
+          errorType: "fatal",
+          printedMessage: "No arguments provided",
+        });
+      }
+      const convexTool = enabledToolsByName[request.params.name];
+      if (!convexTool) {
+        await ctx.crash({
+          exitCode: 1,
+          errorType: "fatal",
+          printedMessage: `Tool ${request.params.name} not found`,
+        });
+      }
+      const input = convexTool.inputSchema.parse(request.params.arguments);
+
+      // Serialize tool handlers since they're mutating the current working directory.
+      const result = await mutex.runExclusive(async () => {
+        return await convexTool.handler(ctx, input);
+      });
+      return {
+        content: [
+          {
+            type: "text",
+            text: JSON.stringify(result),
+          },
+        ],
+      };
+    } catch (error: any) {
+      let message: string;
+      if (error instanceof RequestCrash) {
+        message = error.printedMessage;
+      } else if (error instanceof Error) {
+        message = error.message;
+      } else {
+        message = String(error);
+      }
+      return {
+        content: [
+          {
+            type: "text",
+            text: JSON.stringify({ error: message }),
+          },
+        ],
+        isError: true,
+      };
+    }
+  });
+  server.setRequestHandler("tools/list", async () => {
     return {
       tools: Object.values(enabledToolsByName).map(mcpTool),
     };

package/src/index.ts

@@ -1 +1 @@
-export const version = "1.44.0";
+export const version = "1.45.0-alpha.0";

package/dist/cjs-types/browser/http_client.test.d.ts

@@ -1,2 +0,0 @@
-export {};
-//# sourceMappingURL=http_client.test.d.ts.map

package/dist/cjs-types/browser/http_client.test.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"http_client.test.d.ts","sourceRoot":"","sources":["../../../src/browser/http_client.test.ts"],"names":[],"mappings":""}

package/dist/cjs-types/browser/query_options.test.d.ts

@@ -1,2 +0,0 @@
-export {};
-//# sourceMappingURL=query_options.test.d.ts.map

package/dist/cjs-types/browser/query_options.test.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"query_options.test.d.ts","sourceRoot":"","sources":["../../../src/browser/query_options.test.ts"],"names":[],"mappings":""}

package/dist/cjs-types/browser/simple_client.test.d.ts

@@ -1,2 +0,0 @@
-export {};
-//# sourceMappingURL=simple_client.test.d.ts.map

package/dist/cjs-types/browser/simple_client.test.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"simple_client.test.d.ts","sourceRoot":"","sources":["../../../src/browser/simple_client.test.ts"],"names":[],"mappings":""}

package/dist/cjs-types/browser/sync/client.test.d.ts

@@ -1,5 +0,0 @@
-/**
- * @vitest-environment custom-vitest-environment.ts
- */
-export {};
-//# sourceMappingURL=client.test.d.ts.map

package/dist/cjs-types/browser/sync/client.test.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"client.test.d.ts","sourceRoot":"","sources":["../../../../src/browser/sync/client.test.ts"],"names":[],"mappings":"AAAA;;GAEG"}