convex 1.34.0 → 1.35.0

package/src/cli/lib/api.ts

@@ -23,6 +23,7 @@ import {
   parseDeploymentSelector,
   InProjectSelector,
 } from "./deploymentSelector.js";
+import { loadProjectLocalConfig } from "./localDeployment/filePaths.js";
 import { chalkStderr } from "chalk";
 export type DeploymentName = string;
 export type CloudDeploymentType = "prod" | "dev" | "preview" | "custom";
@@ -104,7 +105,7 @@ export const deploymentSelectionWithinProjectSchema = z.discriminatedUnion(
     z.object({ kind: z.literal("deploymentName"), deploymentName: z.string() }),
     z.object({ kind: z.literal("prod") }),
     z.object({ kind: z.literal("implicitProd") }),
-    z.object({ kind: z.literal("ownDev") }),
+    z.object({ kind: z.literal("unspecified") }),
     z.object({
       kind: z.literal("deploymentSelector"),
       selector: z.string(),
@@ -152,7 +153,7 @@ export function deploymentSelectionWithinProjectFromOptions(
   if (options.implicitProd) {
     return { kind: "implicitProd" };
   }
-  return { kind: "ownDev" };
+  return { kind: "unspecified" };
 }
 
 export async function validateDeploymentSelectionForExistingDeployment(
@@ -161,7 +162,7 @@ export async function validateDeploymentSelectionForExistingDeployment(
   source: "selfHosted" | "deployKey" | "cliArgs",
 ) {
   if (
-    deploymentSelection.kind === "ownDev" ||
+    deploymentSelection.kind === "unspecified" ||
     deploymentSelection.kind === "implicitProd"
   ) {
     // These are both considered the "default" selection depending on the command, so this is always fine
@@ -421,6 +422,9 @@ async function fetchExistingDevDeploymentCredentialsOrCrash(
 // Helpers for `loadSelectedDeploymentCredentials`
 // ----------------------------------------------------------------------
 
+// Returns the user's own dev deployment, which may be a local deployment
+// if one is configured. Used for dev commands (including `npx convex dev`)
+// when no specific deployment is specified.
 async function handleOwnDev(
   ctx: Context,
   projectSelection: ProjectSelection,
@@ -595,7 +599,9 @@ async function fetchDeploymentCredentialsWithinCurrentProject(
   deploymentType: DeploymentType;
 }> {
   switch (deploymentSelection.kind) {
-    case "ownDev": {
+    case "unspecified": {
+      // default to the user's default dev deployment
+      // TODO: this currently also handles local dev, but that should probably be split out into a different DeploymenSelection kind
       return await handleOwnDev(ctx, projectSelection);
     }
     case "implicitProd":
@@ -659,7 +665,7 @@ async function resolveDeploymentNameByReference(
       return await ctx.crash({
         exitCode: 1,
         errorType: "fatal",
-        printedMessage: `Deployment “${reference}” not found. To create a new deployment, use ${chalkStderr.bold(`npx convex deployment create ${reference} --team ${teamSlug} --project ${projectSlug} --select`)}`,
+        printedMessage: `Deployment “${reference}” not found. To create a new deployment, use ${chalkStderr.bold(`npx convex deployment create ${teamSlug}:${projectSlug}:${reference} --select`)}`,
         errForSentry: err,
       });
     }
@@ -678,8 +684,31 @@ async function handleRefInProject(
   deploymentType: DeploymentType;
 }> {
   switch (selector.kind) {
-    case "dev":
-      return await handleOwnDev(ctx, projectSelection);
+    case "dev": {
+      const access = await checkAccessToSelectedProject(ctx, projectSelection);
+      if (access.kind !== "hasAccess") {
+        return await ctx.crash({
+          exitCode: 1,
+          errorType: "fatal",
+          printedMessage:
+            "You don't have access to the selected project. Run `npx convex dev` to select a different project.",
+        });
+      }
+      const deploymentName = await resolveDefaultCloudDevDeploymentName(
+        ctx,
+        access.teamSlug,
+        access.projectSlug,
+      );
+      // Pass teamAndProjectSlugs instead of the original projectSelection,
+      // because handleDeploymentName sends projectSelection to Big Brain's
+      // authorize_within_current_project endpoint, which doesn't understand
+      // deploymentType "local".
+      return await handleDeploymentName(ctx, deploymentName, {
+        kind: "teamAndProjectSlugs",
+        teamSlug: access.teamSlug,
+        projectSlug: access.projectSlug,
+      });
+    }
     case "prod":
       return await handleProd(ctx, projectSelection);
     case "reference": {
@@ -721,6 +750,26 @@ async function handleDeploymentSelector(
         parsed.deploymentName,
         projectSelection,
       );
+    case "local": {
+      const localConfig = loadProjectLocalConfig(ctx);
+      if (localConfig === null) {
+        return ctx.crash({
+          exitCode: 1,
+          errorType: "fatal",
+          printedMessage: `No local deployment found. Run ${chalkStderr.bold("npx convex deployment create local")} to create one.`,
+        });
+      }
+      const credentials = await loadLocalDeploymentCredentials(
+        ctx,
+        localConfig.deploymentName,
+      );
+      return {
+        deploymentName: localConfig.deploymentName,
+        adminKey: credentials.adminKey,
+        url: credentials.deploymentUrl,
+        deploymentType: "local",
+      };
+    }
     case "inCurrentProject":
       return await handleRefInProject(ctx, parsed.selector, projectSelection);
     case "inProject": {
@@ -970,3 +1019,35 @@ export async function getTeamsForUser(ctx: Context) {
   );
   return teams;
 }
+
+async function resolveDefaultCloudDevDeploymentName(
+  ctx: Context,
+  teamSlug: string,
+  projectSlug: string,
+): Promise<string> {
+  try {
+    const result = await typedPlatformClient(ctx, { throw: true }).GET(
+      "/teams/{team_id_or_slug}/projects/{project_slug}/deployment",
+      {
+        params: {
+          path: { team_id_or_slug: teamSlug, project_slug: projectSlug },
+          query: { defaultDev: true },
+        },
+      },
+    );
+    return result.data!.name;
+  } catch (err) {
+    if (
+      err instanceof ThrowingFetchError &&
+      err.serverErrorData?.code === "DeploymentNotFound"
+    ) {
+      return await ctx.crash({
+        exitCode: 1,
+        errorType: "fatal",
+        printedMessage: `You don’t have a personal cloud dev deployment in this project. Run ${chalkStderr.bold("npx convex deployment create --type dev --default")} to create one.`,
+        errForSentry: err,
+      });
+    }
+    return await logAndHandleFetchError(ctx, err);
+  }
+}

package/src/cli/lib/command.ts

@@ -213,10 +213,14 @@ Command.prototype.addDeploymentSelectionOptions = function (
       new Option(
         "--deployment <deployment>",
         action +
-          " the specified deployment. Accepts a deployment name (e.g. joyful-capybara-123), ref (e.g. dev/james), 'dev' (for your personal dev deployment), 'prod' (for your project’s default production deployment). You can also select deployments in other projects with 'project-slug:ref' or 'team-slug:project-slug:ref'.",
-      )
-        .conflicts(["--prod", "--preview-name", "--deployment-name", "--url"])
-        .hideHelp(), // TODO(nicolas) Make this public
+          " a specific deployment. Accepts:\n" +
+          "• a deployment name (e.g. joyful-capybara-123)\n" +
+          "• a deployment ref (e.g. dev/james)\n" +
+          "• `dev` (for your personal dev deployment)\n" +
+          "• `prod` (for your project’s default production deployment)\n" +
+          "• `local` (for your local dev deployment)." +
+          "\nYou can also select deployments in other projects with `project-slug:ref` or `team-slug:project-slug:ref`.",
+      ).conflicts(["--prod", "--preview-name", "--deployment-name", "--url"]),
     )
     .addOption(
       new Option(
@@ -243,8 +247,9 @@ export async function normalizeDevOptions(
     codegen: "enable" | "disable";
     once?: boolean;
     untilSuccess: boolean;
-    run?: string | undefined;
+    start?: string;
     runSh?: string;
+    run?: string | undefined;
     runComponent?: string;
     tailLogs?: string | true;
     traceEvents: boolean;
@@ -309,10 +314,10 @@ export async function normalizeDevOptions(
             name: cmdOptions.run,
             component: cmdOptions.runComponent,
           }
-        : cmdOptions.runSh !== undefined
+        : (cmdOptions.start ?? cmdOptions.runSh) !== undefined
           ? {
               kind: "shell",
-              command: cmdOptions.runSh,
+              command: (cmdOptions.start ?? cmdOptions.runSh)!,
             }
           : undefined,
     tailLogs:
@@ -333,7 +338,12 @@ Command.prototype.addDeployOptions = function () {
       "--dry-run",
       "Print out the generated configuration without deploying to your Convex deployment",
     )
-    .option("-y, --yes", "Skip confirmation prompt when running locally")
+    .addOption(
+      new Option(
+        "-y, --yes",
+        "Skip confirmation prompt when running interactively. Warning: this deploys to PRODUCTION. To deploy to your current dev environment, run npx convex dev --once",
+      ).hideHelp(),
+    )
     .addOption(
       new Option(
         "--typecheck <mode>",

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

@@ -1,10 +1,23 @@
-import { vi, test, expect, beforeEach, MockInstance, beforeAll } from "vitest";
+import {
+  vi,
+  test,
+  expect,
+  beforeEach,
+  afterEach,
+  describe,
+  MockInstance,
+  beforeAll,
+} from "vitest";
+import fs from "fs";
+import os from "os";
+import path from "path";
 import {
   parseProjectConfig,
-  ProjectConfig,
-  writeProjectConfig,
+  type ProjectConfig,
+  ensureConvexFunctionsDir,
   readProjectConfig,
   resetUnknownKeyWarnings,
+  writeAiFilesConfig,
 } from "./config.js";
 import { Context, oneoffContext } from "../../bundler/context.js";
 import { logFailure } from "../../bundler/log.js";
@@ -250,7 +263,7 @@ test("parseProjectConfig - top-level validation", async () => {
   );
 });
 
-test("writeProjectConfig - creates functions directory", async () => {
+test("ensureConvexFunctionsDir - creates functions directory", async () => {
   let mkdirCalled = false;
   let mkdirPath = "";
   const testCtx = {
@@ -272,12 +285,12 @@ test("writeProjectConfig - creates functions directory", async () => {
     codegen: { staticApi: false, staticDataModel: false },
   };
 
-  await writeProjectConfig(testCtx, config);
+  await ensureConvexFunctionsDir(testCtx, config);
   expect(mkdirCalled).toBe(true);
   expect(mkdirPath).toMatch(/^my-functions[\\/]$/);
 });
 
-test("writeProjectConfig - does not write to convex.json", async () => {
+test("ensureConvexFunctionsDir - does not write to convex.json", async () => {
   let writeUtf8FileCalled = false;
   const testCtx = {
     ...ctx,
@@ -299,7 +312,7 @@ test("writeProjectConfig - does not write to convex.json", async () => {
     codegen: { staticApi: true, staticDataModel: true },
   };
 
-  await writeProjectConfig(testCtx, config);
+  await ensureConvexFunctionsDir(testCtx, config);
   expect(writeUtf8FileCalled).toBe(false);
 });
 
@@ -327,7 +340,7 @@ test("readProjectConfig - returns defaults when file doesn't exist", async () =>
     node: { externalPackages: [] },
     generateCommonJSApi: false,
     codegen: { staticApi: false, staticDataModel: false },
-    aiFiles: { disableStalenessMessage: false },
+    aiFiles: {},
   });
 });
 
@@ -431,6 +444,39 @@ test("parseProjectConfig - warns about unknown properties", async () => {
   expect(stripVTControlCharacters(stderr5)).not.toContain("Unknown");
 });
 
+test("parseProjectConfig - aiFiles fields", async () => {
+  await assertParses(
+    {
+      functions: "convex/",
+      aiFiles: {
+        enabled: false,
+        disableStalenessMessage: true,
+        skills: {
+          agents: ["cursor", "windsurf"],
+        },
+      },
+    },
+    {
+      functions: "convex/",
+      aiFiles: {
+        enabled: false,
+        disableStalenessMessage: true,
+        skills: {
+          agents: ["cursor", "windsurf"],
+        },
+      },
+      codegen: {
+        staticApi: false,
+        staticDataModel: false,
+      },
+      generateCommonJSApi: false,
+      node: {
+        externalPackages: [],
+      },
+    },
+  );
+});
+
 // AuthKit configuration tests
 test("parseProjectConfig - authKit basic valid configs", async () => {
   // Basic config with no settings
@@ -850,3 +896,134 @@ test("parseProjectConfig - authKit preview and prod restrictions", async () => {
     },
   );
 });
+
+// ---------------------------------------------------------------------------
+// writeAiFilesConfig
+// ---------------------------------------------------------------------------
+
+describe("writeAiFilesConfig", () => {
+  let tmpDir: string;
+
+  beforeEach(() => {
+    tmpDir = fs.mkdtempSync(`${os.tmpdir()}${path.sep}`);
+  });
+
+  afterEach(() => {
+    fs.rmSync(tmpDir, { recursive: true, force: true });
+  });
+
+  test("creates convex.json with $schema when file does not exist", async () => {
+    await writeAiFilesConfig({
+      projectDir: tmpDir,
+      aiFiles: { enabled: false },
+    });
+
+    const written = JSON.parse(
+      fs.readFileSync(path.join(tmpDir, "convex.json"), "utf8"),
+    );
+    expect(written.$schema).toBe(
+      "node_modules/convex/schemas/convex.schema.json",
+    );
+    expect(written.aiFiles).toEqual({ enabled: false });
+  });
+
+  test("writes aiFiles as-is without merging sub-keys", async () => {
+    fs.writeFileSync(
+      path.join(tmpDir, "convex.json"),
+      JSON.stringify({ aiFiles: { disableStalenessMessage: true } }, null, 2),
+      "utf8",
+    );
+
+    await writeAiFilesConfig({
+      projectDir: tmpDir,
+      aiFiles: { enabled: false },
+    });
+
+    const written = JSON.parse(
+      fs.readFileSync(path.join(tmpDir, "convex.json"), "utf8"),
+    );
+    expect(written.aiFiles).toEqual({ enabled: false });
+  });
+
+  test("preserves other existing fields in convex.json", async () => {
+    fs.writeFileSync(
+      path.join(tmpDir, "convex.json"),
+      JSON.stringify(
+        {
+          functions: "src/convex/",
+          customKey: "preserved",
+          aiFiles: { skills: { agents: ["cursor"] } },
+        },
+        null,
+        2,
+      ),
+      "utf8",
+    );
+
+    await writeAiFilesConfig({
+      projectDir: tmpDir,
+      aiFiles: { enabled: false },
+    });
+
+    const written = JSON.parse(
+      fs.readFileSync(path.join(tmpDir, "convex.json"), "utf8"),
+    );
+    expect(written.functions).toBe("src/convex/");
+    expect(written.customKey).toBe("preserved");
+    expect(written.aiFiles).toEqual({ enabled: false });
+  });
+
+  test("removes aiFiles key when undefined", async () => {
+    fs.writeFileSync(
+      path.join(tmpDir, "convex.json"),
+      JSON.stringify({ aiFiles: { enabled: false } }, null, 2),
+      "utf8",
+    );
+
+    await writeAiFilesConfig({
+      projectDir: tmpDir,
+      aiFiles: undefined,
+    });
+
+    const written = JSON.parse(
+      fs.readFileSync(path.join(tmpDir, "convex.json"), "utf8"),
+    );
+    expect(written.aiFiles).toBeUndefined();
+  });
+
+  test("preserves existing $schema when file already has one", async () => {
+    fs.writeFileSync(
+      path.join(tmpDir, "convex.json"),
+      JSON.stringify({ $schema: "./custom-schema.json" }, null, 2),
+      "utf8",
+    );
+
+    await writeAiFilesConfig({
+      projectDir: tmpDir,
+      aiFiles: undefined,
+    });
+
+    const written = JSON.parse(
+      fs.readFileSync(path.join(tmpDir, "convex.json"), "utf8"),
+    );
+    expect(written.$schema).toBe("./custom-schema.json");
+  });
+
+  test("handles invalid JSON in existing convex.json gracefully", async () => {
+    fs.writeFileSync(
+      path.join(tmpDir, "convex.json"),
+      "not valid json",
+      "utf8",
+    );
+
+    await writeAiFilesConfig({
+      projectDir: tmpDir,
+      aiFiles: { enabled: false },
+    });
+
+    const written = JSON.parse(
+      fs.readFileSync(path.join(tmpDir, "convex.json"), "utf8"),
+    );
+    expect(written.aiFiles).toEqual({ enabled: false });
+  });
+});

package/src/cli/lib/config.ts

@@ -1,5 +1,7 @@
 import { chalkStderr } from "chalk";
 import path from "path";
+// eslint-disable-next-line no-restricted-imports
+import { promises as nodeFs } from "fs";
 import { z } from "zod";
 import { Context } from "../../bundler/context.js";
 import { TypescriptCompiler } from "./typecheck.js";
@@ -102,8 +104,16 @@ export interface ProjectConfig {
 
   // Convex AI files user preferences.
   aiFiles?: {
-    // When true, suppresses AI files install/staleness nags.
+    // When false, disables all AI files prompts and staleness messages.
+    enabled?: boolean;
+    // @deprecated use `enabled` instead.
     disableStalenessMessage?: boolean;
+    // Configuration for agent skills installed by Convex.
+    skills?: {
+      // List of agents to install skills for (e.g. 'claude-code', 'codex', 'cursor').
+      // Defaults to ['claude-code', 'codex'].
+      agents?: string[];
+    };
   };
 }
 
@@ -131,9 +141,9 @@ export function usesTypeScriptCodegen(projectConfig: ProjectConfig): boolean {
   return projectConfig.codegen.fileType === "ts";
 }
 
-/** Whether the new component API import style should be used (default is false) */
+/** Whether the new component API import style should be used */
 export function usesComponentApiImports(projectConfig: ProjectConfig): boolean {
-  return projectConfig.codegen.legacyComponentApi === false;
+  return projectConfig.codegen.legacyComponentApi !== true;
 }
 
 /**
@@ -289,7 +299,13 @@ const BundlerSchema = z.object({
 });
 
 const AiFilesSchema = z.object({
-  disableStalenessMessage: z.boolean().default(false),
+  enabled: z.boolean().optional(),
+  disableStalenessMessage: z.boolean().optional(),
+  skills: z
+    .object({
+      agents: z.array(z.string()).optional(),
+    })
+    .optional(),
 });
 
 const refineToObject = <T extends z.ZodTypeAny>(schema: T) =>
@@ -553,9 +569,7 @@ export async function readProjectConfig(ctx: Context): Promise<{
           staticApi: false,
           staticDataModel: false,
         },
-        aiFiles: {
-          disableStalenessMessage: false,
-        },
+        aiFiles: {},
       },
       configPath: configName(),
     };
@@ -743,12 +757,10 @@ export async function readConfig(
 /**
  * Ensure the functions directory exists.
  *
- * Note: This function no longer writes to or deletes `convex.json`. The config
- * file is now treated as user-owned and is not modified by the CLI. This allows
- * users to maintain their preferred formatting and any comments they may add
- * (if we later support JSONC parsing).
+ * Note: convex.json is treated as user-owned and is not modified by the CLI.
+ * Use writeAiFilesConfig() to explicitly patch the aiFiles section.
  */
-export async function writeProjectConfig(
+export async function ensureConvexFunctionsDir(
   ctx: Context,
   projectConfig: ProjectConfig,
 ) {
@@ -1006,3 +1018,52 @@ export async function handlePushConfigError(
   logFailure(defaultMessage);
   return await logAndHandleFetchError(ctx, error);
 }
+
+export type AiFilesProjectConfig = NonNullable<ProjectConfig["aiFiles"]>;
+
+function tryParseJson(raw: string): unknown {
+  try {
+    return JSON.parse(raw);
+  } catch {
+    return {};
+  }
+}
+
+function toRecord(val: unknown): Record<string, unknown> {
+  if (val !== null && typeof val === "object" && !Array.isArray(val))
+    return val as Record<string, unknown>;
+  return {};
+}
+
+/**
+ * Write the `aiFiles` section of `convex.json`, preserving all other keys.
+ * Writes the given object as-is with no merging or default logic.
+ * If `aiFiles` is undefined, the key is removed from the file.
+ */
+export async function writeAiFilesConfig({
+  projectDir,
+  aiFiles,
+}: {
+  projectDir: string;
+  aiFiles: AiFilesProjectConfig | undefined;
+}): Promise<void> {
+  const filePath = path.join(projectDir, "convex.json");
+  const raw = await nodeFs.readFile(filePath, "utf8").catch(() => null);
+  const base = toRecord(raw !== null ? tryParseJson(raw) : {});
+
+  const { $schema, aiFiles: _existing, ...rest } = base;
+
+  const hasContent = aiFiles !== undefined && Object.keys(aiFiles).length > 0;
+
+  const next: Record<string, unknown> = {
+    $schema: $schema ?? "node_modules/convex/schemas/convex.schema.json",
+    ...rest,
+    ...(hasContent ? { aiFiles } : {}),
+  };
+
+  await nodeFs.writeFile(
+    filePath,
+    JSON.stringify(next, null, 2) + "\n",
+    "utf8",
+  );
+}

package/src/cli/lib/deploy2.ts

@@ -8,7 +8,11 @@ import {
   showSpinner,
 } from "../../bundler/log.js";
 import { spawnSync } from "child_process";
-import { deploymentFetch, logAndHandleFetchError } from "./utils/utils.js";
+import {
+  deploymentFetch,
+  logAndHandleFetchError,
+  typedDeploymentClient,
+} from "./utils/utils.js";
 import {
   EvaluatePushResponse,
   evaluatePushResponse,
@@ -31,7 +35,6 @@ import { PushOptions } from "./components.js";
 import { DeploymentType } from "./api.js";
 import { runPush } from "./components.js";
 import { suggestedEnvVarNames } from "./envvars.js";
-import { runSystemQuery } from "./run.js";
 import {
   handlePushConfigError,
   readProjectConfig,
@@ -40,7 +43,6 @@ import {
 import { deploymentDashboardUrlPage } from "./dashboard.js";
 import { addProgressLinkIfSlow } from "./indexes.js";
 import { ensureAuthKitProvisionedBeforeBuild } from "./workos/workos.js";
-import { fetchDeploymentCanonicalSiteUrl } from "./env.js";
 
 const brotli = promisify(zlib.brotliCompress);
 
@@ -485,14 +487,10 @@ export async function runCommand(
       deploymentUrl: options.url,
       adminKey: options.adminKey,
     };
-    const canonicalCloudUrl = await fetchDeploymentCanonicalCloudUrl(
-      ctx,
-      deployment,
-    );
-    const canonicalSiteUrl = await fetchDeploymentCanonicalSiteUrl(
-      ctx,
-      deployment,
-    );
+    const {
+      convexCloudUrl: canonicalCloudUrl,
+      convexSiteUrl: canonicalSiteUrl,
+    } = await fetchDeploymentCanonicalUrls(ctx, deployment);
 
     const env = { ...process.env };
     env[urlVar] = canonicalCloudUrl;
@@ -517,22 +515,11 @@ export async function runCommand(
   );
 }
 
-export async function fetchDeploymentCanonicalCloudUrl(
+export async function fetchDeploymentCanonicalUrls(
   ctx: Context,
   options: { deploymentUrl: string; adminKey: string },
-): Promise<string> {
-  const result = await runSystemQuery(ctx, {
-    ...options,
-    functionName: "_system/cli/convexUrl:cloudUrl",
-    componentPath: undefined,
-    args: {},
-  });
-  if (typeof result !== "string") {
-    return await ctx.crash({
-      exitCode: 1,
-      errorType: "invalid filesystem or env vars",
-      printedMessage: "Invalid process.env.CONVEX_CLOUD_URL",
-    });
-  }
-  return result;
+): Promise<{ convexCloudUrl: string; convexSiteUrl: string }> {
+  const client = typedDeploymentClient(ctx, options);
+  const result = await client.GET("/get_canonical_urls");
+  return result.data!;
 }

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

@@ -12,7 +12,10 @@ export const componentArgumentValidator = looseObject({
 });
 
 export const componentDefinitionType = z.union([
-  looseObject({ type: z.literal("app") }),
+  looseObject({
+    type: z.literal("app"),
+    httpPrefix: z.string().optional(),
+  }),
   looseObject({
     type: z.literal("childComponent"),
     name: identifier,