convex 1.48.0-alpha.0 → 1.48.0

package/package.json

@@ -1,12 +1,12 @@
 {
   "name": "convex",
   "description": "Client for the Convex Cloud",
-  "version": "1.48.0-alpha.0",
+  "version": "1.48.0",
   "author": "Convex, Inc. <no-reply@convex.dev>",
   "homepage": "https://convex.dev",
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/get-convex/convex-backend.git",
+    "url": "git+https://github.com/convex/convex-backend.git",
     "directory": "npm-packages/convex"
   },
   "main": "./dist/cjs/index.js",
@@ -227,6 +227,7 @@
     "@types/semver": "^7.3.13",
     "@types/serve-handler": "~6.1.4",
     "@types/ws": "^8.5.13",
+    "@vercel/detect-agent": "^1.2.5",
     "@vitest/eslint-plugin": "~1.6.0",
     "adm-zip": "^0.6.1",
     "bufferutil": "^4.0.7",

package/schemas/convex.schema.json

@@ -123,8 +123,7 @@
         },
         "nodeVersion": {
           "type": "string",
-          "description": "The Node.js version to use for Node.js actions. The currently supported values are '20', '22', and '24'.\n\nDocumentation: https://docs.convex.dev/config/convex.json#configuring-the-nodejs-version",
-          "default": "20"
+          "description": "The Node.js version to use for Node.js actions. The currently supported values are '22' and '24'.\n\nAfter you push a new Node.js version, your functions may keep running on the previous version for a few minutes.\n\nDocumentation: https://docs.convex.dev/config/convex.json#configuring-the-nodejs-version"
         }
       }
     },

package/src/bundler/context.ts

@@ -54,7 +54,6 @@ export type BigBrainAuth = {
   | {
       kind: "accessToken";
       accessToken: string;
-      profile?: { name: string; source: string } | null;
     }
 );
 
@@ -191,19 +190,16 @@ 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,
   );
-  if (!args.skipAuth) {
-    await initializeBigBrainAuth(ctx, {
-      url: args.url,
-      adminKey: args.adminKey,
-      envFile: args.envFile,
-    });
-  }
+  await initializeBigBrainAuth(ctx, {
+    url: args.url,
+    adminKey: args.adminKey,
+    envFile: args.envFile,
+  });
   return ctx;
 };

package/src/bundler/fs.ts

@@ -63,7 +63,6 @@ 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
@@ -154,9 +153,6 @@ 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" });
   }
@@ -264,9 +260,6 @@ 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;
 
@@ -312,20 +305,6 @@ 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);
@@ -440,8 +419,6 @@ 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));
@@ -453,8 +430,6 @@ 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));
@@ -473,12 +448,8 @@ export class RecordingFs implements Filesystem {
     this.invalidated = true;
   }
 
-  registerNormalized(
-    absPath: string,
-    observed: Stats | null,
-    observations = this.observedFiles,
-  ): void {
-    const existing = observations.get(absPath);
+  registerNormalized(absPath: string, observed: Stats | null): void {
+    const existing = this.observedFiles.get(absPath);
     if (existing !== undefined) {
       const stMatch = stMatches(observed, existing);
       if (!stMatch.matches) {
@@ -495,18 +466,14 @@ export class RecordingFs implements Filesystem {
         this.invalidated = true;
       }
     }
-    observations.set(absPath, observed);
+    this.observedFiles.set(absPath, observed);
   }
 
   finalize(): Observations | "invalidated" {
     if (this.invalidated) {
       return "invalidated";
     }
-    return new Observations(
-      this.observedDirectories,
-      this.observedFiles,
-      this.observedLstats,
-    );
+    return new Observations(this.observedDirectories, this.observedFiles);
   }
 }
 
@@ -522,7 +489,6 @@ 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;
@@ -536,8 +502,7 @@ export class Observations {
     for (const path of this.files.keys()) {
       out.push(path);
     }
-    for (const path of this.lstats.keys()) out.push(path);
-    return [...new Set(out)];
+    return out;
   }
 
   overlaps({
@@ -564,20 +529,6 @@ 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/aiFiles.ts

@@ -34,9 +34,22 @@ const aiInstall = new Command("install")
   )
   .allowExcessArguments(false)
   .action(async () => {
-    const { projectDir, convexDir, aiFilesConfig } =
+    const { ctx, projectDir, convexDir, aiFilesConfig } =
       await resolveProjectPaths();
-    await installAiFiles({ projectDir, convexDir, aiFilesConfig });
+
+    const result = await installAiFiles({
+      projectDir,
+      convexDir,
+      aiFilesConfig,
+    });
+
+    if (result.kind === "error") {
+      return await ctx.crash({
+        exitCode: 1,
+        errorType: "fatal",
+        printedMessage: result.message,
+      });
+    }
 
     logMessage(`${chalkStderr.green("✔")} Convex AI files installed.`);
   });
@@ -72,9 +85,22 @@ const aiUpdate = new Command("update")
   )
   .allowExcessArguments(false)
   .action(async () => {
-    const { projectDir, convexDir, aiFilesConfig } =
+    const { ctx, projectDir, convexDir, aiFilesConfig } =
       await resolveProjectPaths();
-    await installAiFiles({ projectDir, convexDir, aiFilesConfig });
+
+    const result = await installAiFiles({
+      projectDir,
+      convexDir,
+      aiFilesConfig,
+    });
+
+    if (result.kind === "error") {
+      return await ctx.crash({
+        exitCode: 1,
+        errorType: "fatal",
+        printedMessage: result.message,
+      });
+    }
 
     logMessage(`${chalkStderr.green("✔")} Convex AI files updated.`);
   });

package/src/cli/configure.ts

@@ -1,5 +1,4 @@
 import { chalkStderr } from "chalk";
-import { handleNoAccessToConfiguredProject } from "./account.js";
 import { Context } from "../bundler/context.js";
 import {
   logFailure,
@@ -351,26 +350,11 @@ async function handleDeploymentWithinProject(
     return result;
   }
 
-  let accessResult = await checkAccessToSelectedProject(
+  const accessResult = await checkAccessToSelectedProject(
     ctx,
     deploymentSelection.targetProject,
   );
-  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;
-    }
+  if (accessResult.kind === "noAccess") {
     logMessage("You don't have access to the selected project.");
     const result = await handleChooseProject(
       ctx,

package/src/cli/env.ts

@@ -171,6 +171,8 @@ const envListCmd = new Command("list")
       "• List all variables and their values: `npx convex env list --include-values`",
       "• Save all variables to a file: `npx convex env list --include-values > .env.convex`",
       "• Append to a file: `npx convex env list --include-values >> .env.convex`",
+      "",
+      "When an AI agent runs this command (detected from environment variables like AI_AGENT or CLAUDECODE), only names are listed unless --include-values is passed.",
     ].join("\n"),
   )
   .option(
@@ -180,7 +182,7 @@ const envListCmd = new Command("list")
   .addOption(
     new Option(
       "--include-values",
-      "Print each variable's value alongside its name, in .env format (the default). Pass it explicitly in scripts that rely on the values.",
+      "Print each variable's value alongside its name, in .env format. This is the default unless an AI agent is detected, so pass it explicitly in scripts that rely on the values.",
     ).conflicts("namesOnly"),
   )
   .configureHelp({ showGlobalOptions: true })
@@ -198,6 +200,7 @@ const envListCmd = new Command("list")
         const backend = deploymentEnvBackend(ctx, deployment);
         await envList(ctx, backend, {
           namesOnly: cmdOptions.namesOnly ?? false,
+          includeValues: cmdOptions.includeValues ?? false,
         });
       },
     });

package/src/cli/envDefault.ts

@@ -147,6 +147,8 @@ const envDefaultList = addEnvDefaultOptions(
         "• List only default variable names (no values): `npx convex env default list --names-only`",
         "• List all default variables and their values: `npx convex env default list --include-values`",
         "",
+        "When an AI agent runs this command (detected from environment variables like AI_AGENT or CLAUDECODE), only names are listed unless --include-values is passed.",
+        "",
         "The deployment type is determined by the current deployment (local maps to dev), or by --type if provided.",
       ].join("\n"),
     )
@@ -157,7 +159,7 @@ const envDefaultList = addEnvDefaultOptions(
     .addOption(
       new Option(
         "--include-values",
-        "Print each variable's value alongside its name, in .env format (the default). Pass it explicitly in scripts that rely on the values.",
+        "Print each variable's value alongside its name, in .env format. This is the default unless an AI agent is detected, so pass it explicitly in scripts that rely on the values.",
       ).conflicts("namesOnly"),
     )
     .configureHelp({ showGlobalOptions: true })
@@ -169,6 +171,7 @@ const envDefaultList = addEnvDefaultOptions(
   await ensureHasConvexDependency(ctx, "env default list");
   await envList(ctx, backend, {
     namesOnly: cmdOptions.namesOnly ?? false,
+    includeValues: cmdOptions.includeValues ?? false,
   });
 });
 

package/src/cli/lib/aiFiles/guidelinesmd.ts

@@ -21,6 +21,8 @@ export async function hasGuidelinesInstalled(
  * Download and write the guidelines file.
  * Guidelines live in `_generated/` so local edits are not expected and are
  * not preserved.
+ *
+ * Returns false if the guidelines could not be downloaded.
  */
 export async function installGuidelinesFile({
   convexDir,
@@ -28,15 +30,16 @@ export async function installGuidelinesFile({
 }: {
   convexDir: string;
   state: AiFilesState;
-}): Promise<void> {
+}): Promise<boolean> {
   const guidelines = await downloadGuidelines();
+
   if (guidelines === null) {
     logMessage(
       chalkStderr.yellow(
         "Could not download Convex AI guidelines right now. You can retry with: npx convex ai-files install",
       ),
     );
-    return;
+    return false;
   }
 
   await fs.mkdir(aiDirForConvexDir(convexDir), { recursive: true });
@@ -46,4 +49,6 @@ export async function installGuidelinesFile({
   logMessage(
     `${chalkStderr.green("✔")} ${guidelinesPathForConvexDir(convexDir)} written`,
   );
+
+  return true;
 }

package/src/cli/lib/aiFiles/index.ts

@@ -44,11 +44,18 @@ async function hasExistingAiFilesArtifacts({
   );
 }
 
+type InstallAiFilesResult =
+  | { kind: "success" }
+  | { kind: "error"; message: string };
+
 /**
  * Install or refresh all Convex AI files.
  *
  * Reads the existing state if present, or starts from a blank one for a
  * fresh install.
+ *
+ * Writes everything it can even when the guidelines download or the skills
+ * install fails, and returns an error if either of them failed.
  */
 export async function installAiFiles({
   projectDir,
@@ -56,16 +63,29 @@ export async function installAiFiles({
   aiFilesConfig,
 }: AiFilesPaths & {
   aiFilesConfig?: AiFilesProjectConfig | undefined;
-}): Promise<void> {
+}): Promise<InstallAiFilesResult> {
   const convexDirName = path.relative(projectDir, convexDir);
   const state = await readAiStateOrDefault(convexDir);
 
-  await installGuidelinesFile({ convexDir, state });
+  const guidelinesInstalled = await installGuidelinesFile({ convexDir, state });
   await applyAgentsMdSection({ projectDir, state, convexDirName });
   await applyClaudeMdSection({ projectDir, state, convexDirName });
-  await installSkills({ projectDir, state, aiFilesConfig });
+  const skillsInstalled = await installSkills({
+    projectDir,
+    state,
+    aiFilesConfig,
+  });
   await removeLegacyCursorRules(projectDir);
   await writeAiState({ state, convexDir });
+
+  if (!guidelinesInstalled || !skillsInstalled) {
+    return {
+      kind: "error",
+      message:
+        "Some Convex AI files could not be installed. See the messages above.",
+    };
+  }
+  return { kind: "success" };
 }
 
 async function attemptToInstallAiFiles(

package/src/cli/lib/aiFiles/skills.ts

@@ -23,11 +23,11 @@ function configuredSkillAgents(
 }
 
 /**
- * Runs `npx skills add get-convex/agent-skills --yes --copy` in the given directory.
+ * Runs `npx skills add convex/agent-skills --yes --copy` in the given directory.
  * Returns true on success, false if the process fails or cannot be started.
  */
 function runSkillsAdd(cwd: string, agents: string[]): Promise<boolean> {
-  const args = ["add", "get-convex/agent-skills", "--yes", "--copy"];
+  const args = ["add", "convex/agent-skills", "--yes", "--copy"];
   for (const agent of agents) {
     args.push("--agent", agent);
   }
@@ -116,6 +116,9 @@ async function removeSkillsLockIfEmpty({
 /**
  * Install Convex agent skills and record the SHA into the state.
  * Handles the kill-switch check and all logging internally.
+ *
+ * Returns false if the skills CLI failed. Skipping skills because no agents
+ * are configured or the kill switch is on counts as success.
  */
 export async function installSkills({
   projectDir,
@@ -125,26 +128,27 @@ export async function installSkills({
   projectDir: string;
   state: AiFilesState;
   aiFilesConfig?: AiFilesProjectConfig | undefined;
-}): Promise<void> {
+}): Promise<boolean> {
   const agents = configuredSkillAgents(aiFilesConfig);
-  if (agents.length === 0) return;
-  if (!(await shouldRunSkillsCli())) return;
+  if (agents.length === 0) return true;
+  if (!(await shouldRunSkillsCli())) return true;
 
   logMessage("Installing Convex agent skills...");
   const skillsOk = await runSkillsAdd(projectDir, agents);
   if (!skillsOk) {
     logMessage(
       chalkStderr.yellow(
-        "Could not install agent skills. You can retry manually with: npx skills add get-convex/agent-skills --copy",
+        "Could not install agent skills. You can retry manually with: npx skills add convex/agent-skills --copy",
       ),
     );
-    return;
+    return false;
   }
 
   const sha = await fetchAgentSkillsSha();
   if (sha) state.agentSkillsSha = sha;
 
   logMessage(`${chalkStderr.green("✔")} Skills installed`);
+  return true;
 }
 
 export type RemoveInstalledSkillsStatus = "unchanged" | "removed" | "failed";

package/src/cli/lib/aiFiles/state.ts

@@ -11,7 +11,7 @@ export const aiFilesStateSchema = z.object({
   guidelinesHash: z.string().nullable(),
   agentsMdSectionHash: z.string().nullable(),
   claudeMdHash: z.string().nullable(),
-  // Commit SHA from get-convex/agent-skills that was current when skills were
+  // Commit SHA from convex/agent-skills that was current when skills were
   // last installed. Used to detect when newer skills are available.
   agentSkillsSha: z.string().nullable(),
 });

package/src/cli/lib/components.ts

@@ -43,7 +43,12 @@ import { typeCheckFunctionsInMode, TypeCheckMode } from "./typecheck.js";
 import { withTmpDir } from "../../bundler/fs.js";
 import { handleDebugBundlePath } from "./debugBundlePath.js";
 import { chalkStderr } from "chalk";
-import { StartPushRequest, StartPushResponse } from "./deployApi/startPush.js";
+import {
+  startPushResponseForLogging,
+  redactEnvironmentVariableValues,
+  StartPushRequest,
+  StartPushResponse,
+} from "./deployApi/startPush.js";
 import { DetailedDeploymentCredentials } from "./api.js";
 import { FinishPushDiff } from "./deployApi/finishPush.js";
 import { Reporter, Span } from "./tracing.js";
@@ -548,7 +553,10 @@ async function startComponentsPushAndCodegen(
   );
 
   if (options.verbose) {
-    logMessage("startPush: " + JSON.stringify(startPushResponse, null, 2));
+    logMessage(
+      "startPush: " +
+        JSON.stringify(startPushResponseForLogging(startPushResponse), null, 2),
+    );
   }
 
   if (options.codegen) {
@@ -734,7 +742,14 @@ function printDiff(
   opts: { verbose: boolean; dryRun: boolean; deploymentName: string | null },
 ) {
   if (opts.verbose) {
-    const diffString = JSON.stringify(finishPushResponse, null, 2);
+    const diffString = JSON.stringify(
+      redactEnvironmentVariableValues(
+        finishPushResponse,
+        startPushResponse.environmentVariables,
+      ),
+      null,
+      2,
+    );
     logMessage(diffString);
     return;
   }

package/src/cli/lib/deployApi/startPush.ts

@@ -48,6 +48,70 @@ export const startPushResponse = looseObject({
 });
 export type StartPushResponse = z.infer<typeof startPushResponse>;
 
+// Values this short are rarely secrets, and replacing them everywhere would
+// garble unrelated strings in the output.
+const MIN_SCRUBBED_VALUE_LENGTH = 8;
+
+/**
+ * Replaces every occurrence of an environment variable's value in `node`'s
+ * strings with `<redacted>`. Values reappear in push responses wherever the
+ * code read them, such as auth providers built from `process.env` in
+ * `auth.config.ts`.
+ */
+export function redactEnvironmentVariableValues<T>(
+  node: T,
+  environmentVariables: Record<string, string>,
+): T {
+  const values = Object.values(environmentVariables)
+    .filter((value) => value.length >= MIN_SCRUBBED_VALUE_LENGTH)
+    // Strings that hold JSON, like `authDiff` entries, contain the escaped form.
+    .flatMap((value) => {
+      const escaped = JSON.stringify(value).slice(1, -1);
+      return escaped === value ? [value] : [value, escaped];
+    })
+    .sort((a, b) => b.length - a.length);
+  const scrub = (child: unknown): unknown => {
+    if (typeof child === "string") {
+      return values.reduce(
+        (scrubbed, value) => scrubbed.split(value).join("<redacted>"),
+        child,
+      );
+    }
+    if (Array.isArray(child)) {
+      return child.map(scrub);
+    }
+    if (child !== null && typeof child === "object") {
+      return Object.fromEntries(
+        Object.entries(child).map(([key, grandchild]) => [
+          key,
+          scrub(grandchild),
+        ]),
+      );
+    }
+    return child;
+  };
+  return scrub(node) as T;
+}
+
+/**
+ * A copy of the response that is safe to print. `environmentVariables` holds
+ * every value on the deployment so `finish_push` can detect concurrent changes,
+ * and those values are often secrets.
+ */
+export function startPushResponseForLogging(
+  response: StartPushResponse,
+): StartPushResponse {
+  return {
+    ...redactEnvironmentVariableValues(response, response.environmentVariables),
+    environmentVariables: Object.fromEntries(
+      Object.keys(response.environmentVariables).map((name) => [
+        name,
+        "<redacted>",
+      ]),
+    ),
+  };
+}
+
 export const evaluatePushResponse = looseObject({
   schemaChange,
 });

package/src/cli/lib/deployment.ts

@@ -102,7 +102,7 @@ export async function eraseDeploymentEnvVar(ctx: Context): Promise<boolean> {
   return true;
 }
 
-export async function gitIgnoreEnvVarFile(ctx: Context): Promise<boolean> {
+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;
 }
 
-export function deploymentNameFromAdminKey(adminKey: string) {
+function deploymentNameFromAdminKey(adminKey: string) {
   const parts = adminKey.split("|");
   if (parts.length === 1) {
     return null;