convex 1.34.0 → 1.35.0

package/src/cli/lib/updates.test.ts

@@ -1,8 +1,8 @@
 import { describe, it, expect, beforeEach, afterEach, vi } from "vitest";
-import { checkVersion } from "./updates.js";
+import { checkVersionAndAiFilesStaleness } from "./updates.js";
 import { getVersion } from "./versionApi.js";
 import { logMessage } from "../../bundler/log.js";
-import { checkAiFilesStaleness } from "./ai/index.js";
+import { checkAiFilesStalenessAndLog } from "./aiFiles/index.js";
 import { readProjectConfig } from "./config.js";
 import type { Context } from "../../bundler/context.js";
 
@@ -10,8 +10,13 @@ vi.mock("./versionApi.js", () => ({
   getVersion: vi.fn(),
 }));
 
-vi.mock("./ai/index.js", () => ({
-  checkAiFilesStaleness: vi.fn(),
+vi.mock("./aiFiles/index.js", () => ({
+  checkAiFilesStalenessAndLog: vi.fn(),
+  isAiFilesDisabled: vi.fn((aiFilesConfig) =>
+    aiFilesConfig?.enabled !== undefined
+      ? aiFilesConfig.enabled === false
+      : aiFilesConfig?.disableStalenessMessage === true,
+  ),
 }));
 
 vi.mock("../../bundler/log.js", () => ({
@@ -24,15 +29,26 @@ vi.mock("./config.js", () => ({
 
 const mockGetVersion = vi.mocked(getVersion);
 const mockLogMessage = vi.mocked(logMessage);
-const mockCheckAiFilesStaleness = vi.mocked(checkAiFilesStaleness);
+const mockCheckAiFilesStalenessAndLog = vi.mocked(checkAiFilesStalenessAndLog);
 const mockReadProjectConfig = vi.mocked(readProjectConfig);
 
 const fakeCtx = {} as Context;
 
-describe("updates", () => {
+const okVersion = (overrides?: object) => ({
+  kind: "ok" as const,
+  data: {
+    message: null,
+    guidelinesHash: "abc-guidelines-hash",
+    agentSkillsSha: "abc-skills-sha",
+    disableSkillsCli: false,
+    ...overrides,
+  },
+});
+
+describe("checkVersionAndAiFilesStaleness", () => {
   beforeEach(() => {
     vi.clearAllMocks();
-    mockCheckAiFilesStaleness.mockResolvedValue(undefined);
+    mockCheckAiFilesStalenessAndLog.mockResolvedValue(undefined);
     mockReadProjectConfig.mockResolvedValue({
       projectConfig: {
         functions: "convex",
@@ -48,72 +64,93 @@ describe("updates", () => {
     vi.resetAllMocks();
   });
 
-  describe("checkVersion", () => {
-    it("logs message and passes both hashes to staleness check", async () => {
-      const sha = "abc123def456abc123def456abc123def456abc1";
-      mockGetVersion.mockResolvedValue({
-        message: "New version available: 1.2.3",
-        guidelinesHash:
-          "02e43fc1ff0ee48db8da468f5c7525877d8056fcd56c77d78a166ac447efb91c",
-        agentSkillsSha: sha,
-        disableSkillsCli: false,
-      });
+  it("logs version message when server provides one", async () => {
+    mockGetVersion.mockResolvedValue(
+      okVersion({ message: "New version available: 1.2.3" }),
+    );
 
-      await checkVersion(fakeCtx);
+    await checkVersionAndAiFilesStaleness(fakeCtx);
 
-      expect(mockGetVersion).toHaveBeenCalled();
-      expect(mockLogMessage).toHaveBeenCalledWith(
-        "New version available: 1.2.3",
-      );
-      expect(mockCheckAiFilesStaleness).toHaveBeenCalledWith(
-        "02e43fc1ff0ee48db8da468f5c7525877d8056fcd56c77d78a166ac447efb91c",
-        sha,
-        expect.any(String),
-        expect.any(String),
-      );
-    });
+    expect(mockLogMessage).toHaveBeenCalledWith("New version available: 1.2.3");
+  });
+
+  it("does not log when version has no message", async () => {
+    mockGetVersion.mockResolvedValue(okVersion());
 
-    it("does not log when version has no message", async () => {
-      mockGetVersion.mockResolvedValue({
-        message: null,
+    await checkVersionAndAiFilesStaleness(fakeCtx);
+
+    expect(mockLogMessage).not.toHaveBeenCalled();
+  });
+
+  it("does nothing when getVersion returns error", async () => {
+    mockGetVersion.mockResolvedValue({ kind: "error" });
+
+    await checkVersionAndAiFilesStaleness(fakeCtx);
+
+    expect(mockLogMessage).not.toHaveBeenCalled();
+    expect(mockCheckAiFilesStalenessAndLog).not.toHaveBeenCalled();
+  });
+
+  it("passes hashes and project paths to staleness check", async () => {
+    mockGetVersion.mockResolvedValue(
+      okVersion({
         guidelinesHash:
           "02e43fc1ff0ee48db8da468f5c7525877d8056fcd56c77d78a166ac447efb91c",
-        agentSkillsSha: null,
-        disableSkillsCli: false,
-      });
+        agentSkillsSha: "abc123def456abc123def456abc123def456abc1",
+      }),
+    );
 
-      await checkVersion(fakeCtx);
+    await checkVersionAndAiFilesStaleness(fakeCtx);
 
-      expect(mockGetVersion).toHaveBeenCalled();
-      expect(mockLogMessage).not.toHaveBeenCalled();
+    expect(mockCheckAiFilesStalenessAndLog).toHaveBeenCalledWith({
+      canonicalGuidelinesHash:
+        "02e43fc1ff0ee48db8da468f5c7525877d8056fcd56c77d78a166ac447efb91c",
+      canonicalAgentSkillsSha: "abc123def456abc123def456abc123def456abc1",
+      projectDir: expect.any(String),
+      convexDir: expect.any(String),
     });
+  });
 
-    it("doesn't do anything when getVersion returns null", async () => {
-      mockGetVersion.mockResolvedValue(null);
+  it("passes null hashes when version has none", async () => {
+    mockGetVersion.mockResolvedValue(
+      okVersion({ guidelinesHash: null, agentSkillsSha: null }),
+    );
 
-      await checkVersion(fakeCtx);
+    await checkVersionAndAiFilesStaleness(fakeCtx);
 
-      expect(mockGetVersion).toHaveBeenCalled();
-      expect(mockLogMessage).not.toHaveBeenCalled();
-      expect(mockCheckAiFilesStaleness).not.toHaveBeenCalled();
+    expect(mockCheckAiFilesStalenessAndLog).toHaveBeenCalledWith({
+      canonicalGuidelinesHash: null,
+      canonicalAgentSkillsSha: null,
+      projectDir: expect.any(String),
+      convexDir: expect.any(String),
     });
+  });
 
-    it("passes null hashes to staleness check when version has none", async () => {
-      mockGetVersion.mockResolvedValue({
-        message: "New version available: 1.2.3",
-        guidelinesHash: null,
-        agentSkillsSha: null,
-        disableSkillsCli: false,
-      });
-
-      await checkVersion(fakeCtx);
-
-      expect(mockCheckAiFilesStaleness).toHaveBeenCalledWith(
-        null,
-        null,
-        expect.any(String),
-        expect.any(String),
-      );
+  it("skips staleness check when aiFiles.disableStalenessMessage is true", async () => {
+    mockGetVersion.mockResolvedValue(okVersion());
+    mockReadProjectConfig.mockResolvedValue({
+      projectConfig: {
+        functions: "convex",
+        node: { externalPackages: [] },
+        generateCommonJSApi: false,
+        codegen: { staticApi: true, staticDataModel: true },
+        aiFiles: { disableStalenessMessage: true },
+      },
+      configPath: "convex.json",
     });
+
+    await checkVersionAndAiFilesStaleness(fakeCtx);
+
+    expect(mockCheckAiFilesStalenessAndLog).not.toHaveBeenCalled();
+  });
+
+  it("silently skips staleness check when project config cannot be resolved", async () => {
+    mockGetVersion.mockResolvedValue(okVersion());
+    mockReadProjectConfig.mockRejectedValue(new Error("no convex.json"));
+
+    await expect(
+      checkVersionAndAiFilesStaleness(fakeCtx),
+    ).resolves.toBeUndefined();
+    expect(mockCheckAiFilesStalenessAndLog).not.toHaveBeenCalled();
   });
 });

package/src/cli/lib/updates.ts

@@ -3,34 +3,36 @@ import { logMessage } from "../../bundler/log.js";
 import type { Context } from "../../bundler/context.js";
 import { readProjectConfig } from "./config.js";
 import { functionsDir } from "./utils/utils.js";
-import { checkAiFilesStaleness } from "./ai/index.js";
+import {
+  checkAiFilesStalenessAndLog,
+  isAiFilesDisabled,
+} from "./aiFiles/index.js";
 import { getVersion } from "./versionApi.js";
 
 /**
- * Check the version of the `convex` NPM package and nag if Convex AI files
- * are out of date.
+ * Fetch the latest version data, log any server nag message, and warn if
+ * Convex AI files are out of date. Both checks share the one getVersion()
+ * round-trip.
  */
-export async function checkVersion(ctx: Context) {
+export async function checkVersionAndAiFilesStaleness(ctx: Context) {
   const version = await getVersion();
+  if (version.kind === "error") return;
 
-  if (version === null) {
-    return;
-  }
-
-  if (version.message) {
-    logMessage(version.message);
-  }
+  if (version.data.message) logMessage(version.data.message);
 
   try {
     const { configPath, projectConfig } = await readProjectConfig(ctx);
+    const aiFilesConfig = projectConfig.aiFiles;
+    if (isAiFilesDisabled(aiFilesConfig)) return;
     const convexDir = path.resolve(functionsDir(configPath, projectConfig));
     const projectDir = path.resolve(path.dirname(configPath));
-    await checkAiFilesStaleness(
-      version.guidelinesHash,
-      version.agentSkillsSha,
+    await checkAiFilesStalenessAndLog({
+      canonicalGuidelinesHash: version.data.guidelinesHash,
+      canonicalAgentSkillsSha: version.data.agentSkillsSha,
+      aiFilesConfig,
       projectDir,
       convexDir,
-    );
+    });
   } catch {
     // Non-fatal: skip staleness check if project config can't be resolved.
   }

package/src/cli/lib/usage.ts

@@ -3,6 +3,7 @@ import { Context } from "../../bundler/context.js";
 import { logWarning } from "../../bundler/log.js";
 import { teamDashboardUrl } from "./dashboard.js";
 import { fetchTeamAndProject } from "./api.js";
+import { isAnonymousDeployment } from "./deployment.js";
 import { bigBrainAPI } from "./utils/utils.js";
 
 async function warn(
@@ -53,7 +54,8 @@ export async function usageStateWarning(
     auth === null ||
     auth.kind === "projectKey" ||
     auth.kind === "deploymentKey" ||
-    process.env.CONVEX_AGENT_MODE === "anonymous"
+    process.env.CONVEX_AGENT_MODE === "anonymous" ||
+    isAnonymousDeployment(targetDeployment)
   ) {
     return;
   }

package/src/cli/lib/utils/prompts.ts

@@ -30,12 +30,14 @@ export const promptString = async (
   options: {
     message: string;
     default?: string;
+    validate?: (value: string) => boolean | string | Promise<string | boolean>;
   },
 ): Promise<string> => {
   if (process.stdin.isTTY) {
     return input({
       message: options.message,
       ...(options.default !== undefined ? { default: options.default } : {}),
+      ...(options.validate !== undefined ? { validate: options.validate } : {}),
     }).catch(handlePromptError(ctx));
   } else {
     return ctx.crash({

package/src/cli/lib/utils/utils.test.ts

@@ -65,7 +65,7 @@ describe("bigBrainFetch", () => {
     const mockFetch = stubFetch();
     const ctx = makeContext(null);
 
-    const fetch = await bigBrainFetch(ctx);
+    const fetch = bigBrainFetch(ctx);
     await fetch("https://api.convex.dev/api/test", { method: "GET" });
 
     expect(mockFetch).toHaveBeenCalledOnce();
@@ -82,7 +82,7 @@ describe("bigBrainFetch", () => {
       accessToken: "test-token",
     });
 
-    const fetch = await bigBrainFetch(ctx);
+    const fetch = bigBrainFetch(ctx);
     await fetch("https://api.convex.dev/api/test", { method: "GET" });
 
     expect(mockFetch).toHaveBeenCalledOnce();
@@ -99,7 +99,7 @@ describe("bigBrainFetch", () => {
       accessToken: "original-token",
     });
 
-    const fetch = await bigBrainFetch(ctx);
+    const fetch = bigBrainFetch(ctx);
     await fetch("https://api.convex.dev/api/test", {
       method: "POST",
       headers: {
@@ -124,7 +124,7 @@ describe("bigBrainFetch", () => {
       headers: { "X-Custom-Header": "custom-value" },
     });
 
-    const fetch = await bigBrainFetch(ctx);
+    const fetch = bigBrainFetch(ctx);
     await fetch(request, undefined);
 
     expect(mockFetch).toHaveBeenCalledOnce();
@@ -143,7 +143,7 @@ describe("bigBrainFetch", () => {
       headers: { "X-Custom-Header": "from-request" },
     });
 
-    const fetch = await bigBrainFetch(ctx);
+    const fetch = bigBrainFetch(ctx);
     await fetch(request, {
       headers: { "X-Custom-Header": "from-options" },
     });
@@ -160,7 +160,7 @@ describe("bigBrainFetch", () => {
       method: "POST",
     });
 
-    const fetch = await bigBrainFetch(ctx);
+    const fetch = bigBrainFetch(ctx);
     await fetch(request);
 
     expect(mockFetch).toHaveBeenCalledOnce();

package/src/cli/lib/utils/utils.ts

@@ -1,3 +1,4 @@
+import { paths as PlatformDeploymentPaths } from "@convex-dev/platform/deploymentApi";
 import { paths as PlatformManagementPaths } from "@convex-dev/platform/managementApi";
 import { chalkStderr } from "chalk";
 import os from "os";
@@ -692,7 +693,7 @@ export function cacheDir() {
  *
  * This fetch() also has retries and throws if the response is not ok.
  */
-export async function bigBrainFetch(ctx: Context): Promise<typeof fetch> {
+export function bigBrainFetch(ctx: Context): typeof fetch {
   const authHeader = ctx.bigBrainAuth()?.header;
   const bigBrainHeaders: Record<string, string> = authHeader
     ? {
@@ -758,26 +759,25 @@ export async function bigBrainAPI<T = any>({
  *
  * Pass { throw: true } to throw ThrowingFetchErrors instead of exiting the process.
  */
-function typedBigBrainClientFactory<T>(baseUrl: string) {
+function typedApiClientFactory<T>(
+  baseUrl: string,
+  fetchBuilder: (ctx: Context) => typeof fetch,
+) {
   return (ctx: Context, options: { throw?: boolean } = {}) => {
     type Paths = T extends CliManagementPaths
       ? CliManagementPaths
       : T extends PlatformManagementPaths
         ? PlatformManagementPaths
-        : never;
-    const bigBrainClient = createClient<Paths>({
+        : T extends PlatformDeploymentPaths
+          ? PlatformDeploymentPaths
+          : never;
+    const client = createClient<Paths>({
       baseUrl,
-      fetch: async (
-        resource: Request,
-        options?: RequestInit,
-      ): Promise<Response> => {
-        const fetch = await bigBrainFetch(ctx);
-        return fetch(resource, options);
-      },
+      fetch: fetchBuilder(ctx),
     });
 
     // Wrap the client with error handling - go back to proxy since middleware doesn't catch parsing errors
-    return new Proxy(bigBrainClient, {
+    return new Proxy(client, {
       get(target, prop) {
         const originalMethod = target[prop as keyof typeof target];
 
@@ -810,13 +810,31 @@ function typedBigBrainClientFactory<T>(baseUrl: string) {
   };
 }
 
-export const typedBigBrainClient =
-  typedBigBrainClientFactory<CliManagementPaths>(BIG_BRAIN_URL);
+export const typedBigBrainClient = typedApiClientFactory<CliManagementPaths>(
+  BIG_BRAIN_URL,
+  bigBrainFetch,
+);
 export const typedPlatformClient =
-  typedBigBrainClientFactory<PlatformManagementPaths>(
+  typedApiClientFactory<PlatformManagementPaths>(
     PLATFORM_MANAGEMENT_API_URL,
+    bigBrainFetch,
   );
 
+export function typedDeploymentClient(
+  ctx: Context,
+  args: { deploymentUrl: string; adminKey: string },
+  options: { throw?: boolean } = {},
+) {
+  return typedApiClientFactory<PlatformDeploymentPaths>(
+    `${args.deploymentUrl}/api/v1`,
+    (ctx) =>
+      deploymentFetch(ctx, {
+        deploymentUrl: args.deploymentUrl,
+        adminKey: args.adminKey,
+      }),
+  )(ctx, options);
+}
+
 export async function bigBrainAPIMaybeThrows({
   ctx,
   method,
@@ -828,7 +846,7 @@ export async function bigBrainAPIMaybeThrows({
   path: string;
   data?: any;
 }): Promise<any> {
-  const fetch = await bigBrainFetch(ctx);
+  const fetch = bigBrainFetch(ctx);
   const dataString =
     data === undefined
       ? method === "POST"
@@ -894,19 +912,40 @@ export function waitUntilCalled(): [Promise<unknown>, () => void] {
   return [waitPromise, () => onCalled(null)];
 }
 
-// We can eventually switch to something like `filesize` for i18n and
-// more robust formatting, but let's keep our CLI bundle small for now.
+const BYTE_UNITS: [number, string][] = [
+  [1 << 30, "GiB"],
+  [1_000_000_000, "GB"],
+  [1 << 20, "MiB"],
+  [1_000_000, "MB"],
+  [1 << 10, "KiB"],
+  [1_000, "KB"],
+];
+
+/**
+ * Format a byte count into a human-friendly string.
+ *
+ * Picks the unit (binary or decimal) that divides most cleanly.
+ * Shows one decimal place only when it divides exactly (e.g. "4.1 MiB").
+ * Falls back to raw bytes when no unit divides cleanly.
+ */
 export function formatSize(n: number): string {
-  if (n < 1024) {
-    return `${n} B`;
+  if (n === 0) {
+    return "0 bytes";
   }
-  if (n < 1024 * 1024) {
-    return `${(n / 1024).toFixed(1)} KB`;
-  }
-  if (n < 1024 * 1024 * 1024) {
-    return `${(n / 1024 / 1024).toFixed(1)} MB`;
+  for (const [unitSize, unitName] of BYTE_UNITS) {
+    if (n < unitSize) {
+      continue;
+    }
+    if (n % unitSize === 0) {
+      return `${n / unitSize} ${unitName}`;
+    }
+    if ((n * 10) % unitSize === 0) {
+      const whole = Math.floor(n / unitSize);
+      const frac = Math.floor((n * 10) / unitSize) % 10;
+      return `${whole}.${frac} ${unitName}`;
+    }
   }
-  return `${(n / 1024 / 1024 / 1024).toFixed(2)} GB`;
+  return `${n} bytes`;
 }
 
 export function formatDuration(ms: number): string {
@@ -1236,7 +1275,7 @@ export function deploymentFetch(
     adminKey: string;
     onError?: (err: any) => void;
   },
-): typeof throwingFetch {
+): typeof fetch {
   const { deploymentUrl, adminKey, onError } = options;
   const onErrorWithAttempt = (err: any, attempt: number) => {
     onError?.(err);

package/src/cli/lib/versionApi.test.ts

@@ -40,10 +40,13 @@ describe("versionApi", () => {
       const result = await getVersion();
 
       expect(result).toEqual({
-        message: "New version available",
-        guidelinesHash: null,
-        agentSkillsSha: sha,
-        disableSkillsCli: false,
+        kind: "ok",
+        data: {
+          message: "New version available",
+          guidelinesHash: null,
+          agentSkillsSha: sha,
+          disableSkillsCli: false,
+        },
       });
       expect(mockFetch).toHaveBeenCalledWith(
         "https://version.convex.dev/v1/version",
@@ -59,15 +62,15 @@ describe("versionApi", () => {
       );
     });
 
-    it("returns null on network error", async () => {
+    it("returns error on network error", async () => {
       mockFetch.mockRejectedValue(new Error("Network error"));
 
       const result = await getVersion();
 
-      expect(result).toBeNull();
+      expect(result).toEqual({ kind: "error" });
     });
 
-    it("returns null on non-ok response", async () => {
+    it("returns error on non-ok response", async () => {
       const mockResponse = {
         ok: false,
         status: 500,
@@ -76,10 +79,10 @@ describe("versionApi", () => {
 
       const result = await getVersion();
 
-      expect(result).toBeNull();
+      expect(result).toEqual({ kind: "error" });
     });
 
-    it("returns null on invalid JSON response", async () => {
+    it("returns error on invalid JSON response", async () => {
       const mockResponse = {
         ok: true,
         json: vi.fn().mockResolvedValue("invalid json"),
@@ -88,7 +91,7 @@ describe("versionApi", () => {
 
       const result = await getVersion();
 
-      expect(result).toBeNull();
+      expect(result).toEqual({ kind: "error" });
     });
   });
 

package/src/cli/lib/versionApi.ts

@@ -20,7 +20,11 @@ export type VersionResult = {
   disableSkillsCli: boolean;
 };
 
-export async function getVersion(): Promise<VersionResult | null> {
+export type VersionFetchResult =
+  | { kind: "ok"; data: VersionResult }
+  | { kind: "error" };
+
+export async function getVersion(): Promise<VersionFetchResult> {
   try {
     const req = await fetch(VERSION_ENDPOINT, {
       headers: HEADERS,
@@ -30,14 +34,17 @@ export async function getVersion(): Promise<VersionResult | null> {
       Sentry.captureException(
         new Error(`Failed to fetch version: status = ${req.status}`),
       );
-      return null;
+      return { kind: "error" };
     }
 
     const json = await req.json();
-    return validateVersionResult(json);
+    const result = validateVersionResult(json);
+
+    if (result === null) return { kind: "error" };
+    return { kind: "ok", data: result };
   } catch (error) {
     Sentry.captureException(error);
-    return null;
+    return { kind: "error" };
   }
 }
 
@@ -71,7 +78,8 @@ export function validateVersionResult(json: any): VersionResult | null {
 /** Fetch the latest agent skills SHA from version.convex.dev. */
 export async function fetchAgentSkillsSha(): Promise<string | null> {
   const versionData = await getVersion();
-  return versionData?.agentSkillsSha ?? null;
+  if (versionData.kind === "error") return null;
+  return versionData.data.agentSkillsSha;
 }
 
 export async function downloadGuidelines(): Promise<string | null> {

package/src/cli/lib/workos/workos.ts

@@ -618,12 +618,11 @@ export async function tryToCreateAssociatedWorkosTeam(
   );
 
   if (!result.success) {
-    const dashboardUrl = deploymentDashboardUrlPage(
-      deploymentName,
-      `/settings/environment-variables?var=WORKOS_CLIENT_ID`,
-    );
     logMessage(
-      `To provide your own WorkOS environment credentials instead, set environment variables manually on the dashboard:\n  ${dashboardUrl}`,
+      `To provide your own WorkOS environment credentials instead, set environment variables manually:
+
+npx convex env set WORKOS_CLIENT_ID $YOUR_CLIENT_ID_HERE
+npx convex env set WORKOS_API_KEY $YOUR_API_KEY_HERE`,
     );
     return "choseNotToAssociatedTeam";
   }

package/src/index.ts

@@ -1 +1 @@
-export const version = "1.34.0";
+export const version = "1.35.0";