convex 1.34.1 → 1.35.0

package/src/cli/dev.ts

@@ -1,4 +1,5 @@
 import { Command, Option } from "@commander-js/extra-typings";
+import { chalkStderr } from "chalk";
 import { oneoffContext } from "../bundler/context.js";
 import { logVerbose } from "../bundler/log.js";
 import { deploymentCredentialsOrConfigure } from "./configure.js";
@@ -9,8 +10,11 @@ import {
   CONVEX_DEPLOYMENT_ENV_VAR_NAME,
   CONVEX_SELF_HOSTED_URL_VAR_NAME,
 } from "./lib/utils/utils.js";
-import { getDeploymentSelection } from "./lib/deploymentSelection.js";
-import { checkVersion } from "./lib/updates.js";
+import {
+  getDeploymentSelection,
+  type DeploymentSelection,
+} from "./lib/deploymentSelection.js";
+import { checkVersionAndAiFilesStaleness } from "./lib/updates.js";
 
 export const dev = new Command("dev")
   .summary("Develop against a dev deployment, watching for changes")
@@ -18,7 +22,7 @@ export const dev = new Command("dev")
     "Develop against a dev deployment, watching for changes\n\n" +
       "  1. Configures a new or existing project (if needed)\n" +
       "  2. Updates generated types and pushes code to the configured dev deployment\n" +
-      "  3. Runs the provided command (if `--run` or `--run-sh` is used)\n" +
+      "  3. Runs the provided command (if `--start` or `--run` is used)\n" +
       "  4. Watches for file changes, and repeats step 2\n",
   )
   .allowExcessArguments(false)
@@ -59,25 +63,31 @@ export const dev = new Command("dev")
     "Execute only the first 3 steps, on failure watch for local and remote changes and retry steps 2 and 3",
     false,
   )
+  .addOption(
+    new Option(
+      "--start <command>",
+      "Start a long-running command alongside `convex dev`, like a frontend " +
+        "dev server. The command inherits stdin/stdout so you can interact " +
+        "with it directly. Example: npx convex dev --start 'vite --open'",
+    ).conflicts(["--run", "--run-sh"]),
+  )
+  .addOption(
+    new Option("--run-sh <command>", "Deprecated: use --start instead.")
+      .conflicts(["--start", "--run"])
+      .hideHelp(),
+  )
   .addOption(
     new Option(
       "--run <functionName>",
       "The identifier of the function to run in step 3, " +
         "like `api.init.createData` or `myDir/myFile:myFunction`",
-    ).conflicts(["--run-sh"]),
+    ).conflicts(["--start"]),
   )
   .option(
     "--run-component <functionName>",
     "If --run is used and the function is in a component, the path the component tree defined in convex.config.ts. " +
       "Components are a beta feature. This flag is unstable and may change in subsequent releases.",
   )
-  .addOption(
-    new Option(
-      "--run-sh <command>",
-      "A shell command to run in step 3, like `node myScript.js`. " +
-        "If you just want to run a Convex function, use `--run` instead.",
-    ).conflicts(["--run"]),
-  )
   .addOption(
     new Option(
       "--tail-logs [mode]",
@@ -96,7 +106,7 @@ export const dev = new Command("dev")
       "Ignore existing configuration and configure new or existing project, interactively or set by --team <team_slug>, --project <project_slug>, and --dev-deployment local|cloud",
     )
       .choices(["new", "existing"] as const)
-      .conflicts(["--local", "--cloud"]),
+      .conflicts(["--local", "--cloud", "--url", "--admin-key", "--env-file"]),
   )
   .addOption(
     new Option(
@@ -147,6 +157,7 @@ Same format as .env.local or .env files, and overrides them.`,
   .addOption(new Option("--local-site-port <port>").hideHelp())
   .addOption(new Option("--local-backend-version <version>").hideHelp())
   .addOption(new Option("--local-force-upgrade").default(false).hideHelp())
+  .addOption(new Option("--deployment <deployment>").hideHelp())
   .addOption(
     new Option(
       "--local",
@@ -173,6 +184,20 @@ Same format as .env.local or .env files, and overrides them.`,
       await ctx.flushAndExit(-2);
     });
 
+    if (cmdOptions.deployment !== undefined) {
+      return await ctx.crash({
+        exitCode: 1,
+        errorType: "fatal",
+        printedMessage:
+          "`--deployment` can’t be used with `npx convex dev`. \n\n" +
+          "  To select this deployment for development, run: \n" +
+          chalkStderr.bold(
+            `      npx convex deployment select ${cmdOptions.deployment}\n`,
+          ) +
+          "  Then, run `npx convex dev` again.",
+      });
+    }
+
     const devOptions = await normalizeDevOptions(ctx, cmdOptions);
 
     if (cmdOptions.configure === undefined) {
@@ -225,7 +250,17 @@ Same format as .env.local or .env files, and overrides them.`,
 
     const configure =
       cmdOptions.configure === true ? "ask" : (cmdOptions.configure ?? null);
-    const deploymentSelection = await getDeploymentSelection(ctx, cmdOptions);
+    // --configure means "pick a project" — skip deployment selection entirely
+    const deploymentSelection =
+      configure !== null
+        ? ({
+            kind: "chooseProject",
+            selectionWithinProject: {
+              // For backwards compatibility, allow `--configure --prod`
+              kind: cmdOptions.prod ? "prod" : "unspecified",
+            },
+          } satisfies DeploymentSelection)
+        : await getDeploymentSelection(ctx, cmdOptions);
     const credentials = await deploymentCredentialsOrConfigure(
       ctx,
       deploymentSelection,
@@ -260,7 +295,7 @@ Same format as .env.local or .env files, and overrides them.`,
       ...(credentials.deploymentFields !== null
         ? [
             usageStateWarning(ctx, credentials.deploymentFields.deploymentName),
-            checkVersion(ctx),
+            checkVersionAndAiFilesStaleness(ctx),
           ]
         : []),
     ]);

package/src/cli/docs.ts

@@ -38,7 +38,7 @@ export const docs = new Command("docs")
       `get_cookie/${configuredDeployment}`,
       BIG_BRAIN_URL,
     );
-    const fetch = await bigBrainFetch(ctx);
+    const fetch = bigBrainFetch(ctx);
     try {
       const res = await fetch(getCookieUrl);
       deprecationCheckWarning(ctx, res);

package/src/cli/init.ts

@@ -3,7 +3,7 @@ import { oneoffContext } from "../bundler/context.js";
 import { logVerbose } from "../bundler/log.js";
 import { deploymentCredentialsOrConfigure } from "./configure.js";
 import { getDeploymentSelection } from "./lib/deploymentSelection.js";
-import { checkVersion } from "./lib/updates.js";
+import { checkVersionAndAiFilesStaleness } from "./lib/updates.js";
 import { usageStateWarning } from "./lib/usage.js";
 
 // Equivalent to `npx convex dev --once --skip-push`.
@@ -37,7 +37,7 @@ export const init = new Command("init")
     if (credentials.deploymentFields !== null) {
       await Promise.all([
         usageStateWarning(ctx, credentials.deploymentFields.deploymentName),
-        checkVersion(ctx),
+        checkVersionAndAiFilesStaleness(ctx),
       ]);
     }
 

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

@@ -4,16 +4,18 @@ import {
   agentsMdConvexSection,
 } from "../../codegen_templates/agentsmd.js";
 import { agentsMdPath } from "./paths.js";
-import { type AiFilesConfig } from "./config.js";
+import { type AiFilesState } from "./state.js";
 import {
   type ManagedSectionTarget,
   type InjectResult,
   type StripResult,
   injectManagedSection,
-  stripManagedSection,
+  attemptToStripManagedSection,
   hasManagedSection,
-  removeMarkdownSection,
+  attemptToRemoveMarkdownSection,
 } from "./utils.js";
+import { logMessage } from "../../../bundler/log.js";
+import { chalkStderr } from "chalk";
 
 function target(projectDir?: string): ManagedSectionTarget {
   return {
@@ -33,18 +35,18 @@ export async function injectAgentsMdSection({
   return injectManagedSection({ ...target(projectDir), section });
 }
 
-export async function stripAgentsMdSection(
+export async function attemptToStripAgentsMdSection(
   projectDir: string,
 ): Promise<StripResult> {
-  return stripManagedSection(target(projectDir));
+  return attemptToStripManagedSection(target(projectDir));
 }
 
-export async function removeAgentsMdSection(
+export async function attemptToRemoveAgentsMdSection(
   projectDir: string,
 ): Promise<boolean> {
-  return removeMarkdownSection({
+  return attemptToRemoveMarkdownSection({
     projectDir,
-    strip: stripAgentsMdSection,
+    strip: attemptToStripAgentsMdSection,
     fileName: "AGENTS.md",
   });
 }
@@ -61,17 +63,19 @@ export async function hasAgentsMdInstalled(
  */
 export async function applyAgentsMdSection({
   projectDir,
-  config,
+  state,
   convexDirName,
 }: {
   projectDir: string;
-  config: AiFilesConfig;
+  state: AiFilesState;
   convexDirName: string;
 }): Promise<boolean> {
   const result = await injectAgentsMdSection({
     section: agentsMdConvexSection(convexDirName),
     projectDir,
   });
-  config.agentsMdSectionHash = result.sectionHash;
+  if (result.didWrite)
+    logMessage(`${chalkStderr.green("✔")} AGENTS.md written`);
+  state.agentsMdSectionHash = result.sectionHash;
   return result.didWrite;
 }

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

@@ -4,16 +4,18 @@ import {
   claudeMdConvexSection,
 } from "../../codegen_templates/claudemd.js";
 import { claudeMdPath } from "./paths.js";
-import { type AiFilesConfig } from "./config.js";
+import { type AiFilesState } from "./state.js";
 import {
   type ManagedSectionTarget,
   type InjectResult,
   type StripResult,
   injectManagedSection,
-  stripManagedSection,
+  attemptToStripManagedSection,
   hasManagedSection,
-  removeMarkdownSection,
+  attemptToRemoveMarkdownSection,
 } from "./utils.js";
+import { logMessage } from "../../../bundler/log.js";
+import { chalkStderr } from "chalk";
 
 function target(projectDir?: string): ManagedSectionTarget {
   return {
@@ -33,18 +35,18 @@ export async function injectClaudeMdSection({
   return injectManagedSection({ ...target(projectDir), section });
 }
 
-export async function stripClaudeMdSection(
+export async function attemptToStripClaudeMdSection(
   projectDir: string,
 ): Promise<StripResult> {
-  return stripManagedSection(target(projectDir));
+  return attemptToStripManagedSection(target(projectDir));
 }
 
-export async function removeClaudeMdSection(
+export async function attemptToRemoveClaudeMdSection(
   projectDir: string,
 ): Promise<boolean> {
-  return removeMarkdownSection({
+  return attemptToRemoveMarkdownSection({
     projectDir,
-    strip: stripClaudeMdSection,
+    strip: attemptToStripClaudeMdSection,
     fileName: "CLAUDE.md",
   });
 }
@@ -61,17 +63,19 @@ export async function hasClaudeMdInstalled(
  */
 export async function applyClaudeMdSection({
   projectDir,
-  config,
+  state,
   convexDirName,
 }: {
   projectDir: string;
-  config: AiFilesConfig;
+  state: AiFilesState;
   convexDirName: string;
 }): Promise<boolean> {
   const result = await injectClaudeMdSection({
     section: claudeMdConvexSection(convexDirName),
     projectDir,
   });
-  config.claudeMdHash = result.sectionHash;
+  if (result.didWrite)
+    logMessage(`${chalkStderr.green("✔")} CLAUDE.md written`);
+  state.claudeMdHash = result.sectionHash;
   return result.didWrite;
 }

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

@@ -30,11 +30,21 @@ describe("hasGuidelinesInstalled", () => {
     expect(await hasGuidelinesInstalled(convexDir)).toBe(true);
   });
 
-  test("returns true even when guidelines.md is empty", async () => {
+  test("returns false when guidelines.md is empty", async () => {
     fs.writeFileSync(
       path.join(convexDir, "_generated", "ai", "guidelines.md"),
       "",
     );
-    expect(await hasGuidelinesInstalled(convexDir)).toBe(true);
+    expect(await hasGuidelinesInstalled(convexDir)).toBe(false);
+  });
+
+  test("throws when guidelines.md cannot be read", async () => {
+    fs.rmSync(path.join(convexDir, "_generated", "ai", "guidelines.md"), {
+      force: true,
+      recursive: true,
+    });
+    fs.mkdirSync(path.join(convexDir, "_generated", "ai", "guidelines.md"));
+
+    await expect(hasGuidelinesInstalled(convexDir)).rejects.toThrow();
   });
 });

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

@@ -4,14 +4,17 @@ import { chalkStderr } from "chalk";
 import { logMessage } from "../../../bundler/log.js";
 import { downloadGuidelines } from "../versionApi.js";
 import { hashSha256 } from "../utils/hash.js";
-import { guidelinesPathForConvexDir } from "./paths.js";
-import { readFileSafe } from "./utils.js";
-import { type AiFilesConfig } from "./config.js";
+import { aiDirForConvexDir, guidelinesPathForConvexDir } from "./paths.js";
+import { attemptReadFile, exhaustiveCheck } from "./utils.js";
+import { type AiFilesState } from "./state.js";
 
 export async function hasGuidelinesInstalled(
   convexDir: string,
 ): Promise<boolean> {
-  return (await readFileSafe(guidelinesPathForConvexDir(convexDir))) !== null;
+  const result = await attemptReadFile(guidelinesPathForConvexDir(convexDir));
+  if (result.kind === "content") return true;
+  if (result.kind === "empty" || result.kind === "not-found") return false;
+  return exhaustiveCheck(result);
 }
 
 /**
@@ -21,10 +24,10 @@ export async function hasGuidelinesInstalled(
  */
 export async function installGuidelinesFile({
   convexDir,
-  config,
+  state,
 }: {
   convexDir: string;
-  config: AiFilesConfig;
+  state: AiFilesState;
 }): Promise<void> {
   const guidelines = await downloadGuidelines();
   if (guidelines === null) {
@@ -36,6 +39,11 @@ export async function installGuidelinesFile({
     return;
   }
 
+  await fs.mkdir(aiDirForConvexDir(convexDir), { recursive: true });
   await fs.writeFile(guidelinesPathForConvexDir(convexDir), guidelines, "utf8");
-  config.guidelinesHash = hashSha256(guidelines);
+  state.guidelinesHash = hashSha256(guidelines);
+
+  logMessage(
+    `${chalkStderr.green("✔")} ${guidelinesPathForConvexDir(convexDir)} written`,
+  );
 }