convex 1.34.1 → 1.35.0

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);
 });
 
@@ -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";
@@ -106,6 +108,12 @@ export interface ProjectConfig {
     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[];
+    };
   };
 }
 
@@ -133,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;
 }
 
 /**
@@ -293,6 +301,11 @@ const BundlerSchema = z.object({
 const AiFilesSchema = z.object({
   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) =>
@@ -744,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,
 ) {
@@ -1007,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,

package/src/cli/lib/deploymentSelection.ts

@@ -8,6 +8,7 @@ import {
   deploymentSelectionWithinProjectFromOptions,
   DeploymentType,
   fetchTeamAndProjectForKey,
+  getTeamAndProjectSlugForDeployment,
   validateDeploymentSelectionForExistingDeployment,
 } from "./api.js";
 import {
@@ -21,6 +22,8 @@ import {
   stripDeploymentTypePrefix,
 } from "./deployment.js";
 import { parseDeploymentSelector } from "./deploymentSelector.js";
+import { loadProjectLocalConfig } from "./localDeployment/filePaths.js";
+import { chalkStderr } from "chalk";
 import { getBuildEnvironment } from "./envvars.js";
 import { readGlobalConfig } from "./utils/globalConfig.js";
 import {
@@ -381,9 +384,9 @@ async function _getDeploymentSelection(
     };
   }
 
-  // If --deployment is a fully qualified selector (team:project:ref or a
-  // deployment name), we don't need a current project context — handle it
-  // before env var resolution.
+  // If --deployment is a fully qualified selector (team:project:ref,
+  // deployment name, or "local"), we don't need a current project context
+  // → handle it before env var resolution.
   if (cliArgs.deployment !== undefined) {
     const parsed = parseDeploymentSelector(cliArgs.deployment);
     if (parsed.kind === "inTeamProject") {
@@ -414,6 +417,25 @@ async function _getDeploymentSelection(
         },
       };
     }
+    if (parsed.kind === "local") {
+      const localConfig = loadProjectLocalConfig(ctx);
+      if (localConfig !== null) {
+        return {
+          kind: "deploymentWithinProject",
+          targetProject: {
+            kind: "deploymentName",
+            deploymentName: localConfig.deploymentName,
+            deploymentType: "local",
+          },
+          selectionWithinProject,
+        };
+      }
+      return ctx.crash({
+        exitCode: 1,
+        errorType: "fatal",
+        printedMessage: `No local deployment found. Run ${chalkStderr.bold("npx convex deployment create local")} to create one.`,
+      });
+    }
   }
 
   if (cliArgs.envFile !== undefined) {
@@ -467,10 +489,12 @@ async function _getDeploymentSelection(
   }
   // none of these?
 
-  // Check if they're logged in
   const isLoggedIn = ctx.bigBrainAuth() !== null;
   if (
-    (!isLoggedIn || process.env.CONVEX_AGENT_MODE === "anonymous") &&
+    (!isLoggedIn ||
+      process.env.CONVEX_AGENT_MODE === "anonymous" ||
+      !process.stdin.isTTY) &&
+    !cliArgs.implicitProd &&
     shouldAllowAnonymousDevelopment()
   ) {
     return {
@@ -654,6 +678,16 @@ async function getDeploymentSelectionFromEnv(
       };
     }
 
+    // Overwrite the selection within project
+    const newSelectionWithinProject =
+      selectionWithinProject.kind === "unspecified" &&
+      // Fetching local deployment credentials uses the "unspecified" code path
+      targetDeploymentType !== "local"
+        ? {
+            kind: "deploymentName" as const,
+            deploymentName: targetDeploymentName,
+          }
+        : selectionWithinProject;
     return {
       kind: "success",
       metadata: {
@@ -663,7 +697,7 @@ async function getDeploymentSelectionFromEnv(
           deploymentName: targetDeploymentName,
           deploymentType: targetDeploymentType,
         },
-        selectionWithinProject,
+        selectionWithinProject: newSelectionWithinProject,
       },
     };
   }
@@ -753,6 +787,25 @@ export async function getProjectDetails(
 ): Promise<PlatformProjectDetails> {
   switch (projectSelection.kind) {
     case "deploymentName": {
+      if (projectSelection.deploymentType === "local") {
+        const result = await getTeamAndProjectSlugForDeployment(ctx, {
+          deploymentName: projectSelection.deploymentName,
+        });
+        if (result === null) {
+          return 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.",
+          });
+        }
+        return await getProjectDetails(ctx, {
+          kind: "teamAndProjectSlugs",
+          teamSlug: result.teamSlug,
+          projectSlug: result.projectSlug,
+        });
+      }
+
       const deployment = (
         await typedPlatformClient(ctx).GET("/deployments/{deployment_name}", {
           params: {

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

@@ -16,6 +16,12 @@ describe("parseDeploymentSelector", () => {
     });
   });
 
+  test('"local"', () => {
+    expect(parseDeploymentSelector("local")).toEqual({
+      kind: "local",
+    });
+  });
+
   test('"tall-forest-123"', () => {
     expect(parseDeploymentSelector("tall-forest-123")).toEqual({
       kind: "deploymentName",

package/src/cli/lib/deploymentSelector.ts

@@ -5,6 +5,7 @@ export type InProjectSelector =
 
 export type ParsedDeploymentSelector =
   | { kind: "deploymentName"; deploymentName: string }
+  | { kind: "local" }
   | { kind: "inCurrentProject"; selector: InProjectSelector }
   | { kind: "inProject"; projectSlug: string; selector: InProjectSelector }
   | {
@@ -26,6 +27,7 @@ function parseInProjectSelector(s: string): InProjectSelector {
 export function parseDeploymentSelector(
   selector: string,
 ): ParsedDeploymentSelector {
+  if (selector === "local") return { kind: "local" };
   if (/^[a-z]+-[a-z]+-[0-9]+$/.test(selector)) {
     return { kind: "deploymentName", deploymentName: selector };
   }