convex 1.34.1 → 1.35.1

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

@@ -19,23 +19,25 @@ import {
   claudeMdPath,
   guidelinesPathForConvexDir,
 } from "./paths.js";
-import { type AiFilesConfig, readAiConfig } from "./config.js";
-import { readFileSafe } from "./utils.js";
+import { type AiFilesState, attemptReadAiState } from "./state.js";
+import { type AiFilesProjectConfig } from "../config.js";
+import { isAiFilesDisabled } from "./index.js";
+import { readFileOrNull } from "./utils.js";
 
 function logGuidelinesStatus({
   guidelinesFile,
   guidelinesRelPath,
-  config,
+  state,
   canonicalGuidelinesHash,
   networkAvailable,
 }: {
   guidelinesFile: string | null;
   guidelinesRelPath: string;
-  config: AiFilesConfig;
+  state: AiFilesState;
   canonicalGuidelinesHash: string | null;
   networkAvailable: boolean;
 }): void {
-  if (guidelinesFile === null) {
+  if (guidelinesFile === null || guidelinesFile === "") {
     logMessage(
       `  ${chalkStderr.yellow("⚠")} ${guidelinesRelPath}: not on disk — run ${chalkStderr.bold("npx convex ai-files install")} to reinstall`,
     );
@@ -43,8 +45,8 @@ function logGuidelinesStatus({
   }
 
   const isLocallyModified =
-    config.guidelinesHash !== null &&
-    hashSha256(guidelinesFile) !== config.guidelinesHash;
+    state.guidelinesHash !== null &&
+    hashSha256(guidelinesFile) !== state.guidelinesHash;
 
   if (isLocallyModified) {
     logMessage(
@@ -56,8 +58,8 @@ function logGuidelinesStatus({
   const isOutOfDate =
     networkAvailable &&
     canonicalGuidelinesHash !== null &&
-    config.guidelinesHash !== null &&
-    config.guidelinesHash !== canonicalGuidelinesHash;
+    state.guidelinesHash !== null &&
+    state.guidelinesHash !== canonicalGuidelinesHash;
 
   if (isOutOfDate) {
     logMessage(
@@ -73,11 +75,11 @@ function logGuidelinesStatus({
 
 function logAgentsMdStatus({
   agentsContent,
-  config,
+  state,
   convexDirName,
 }: {
   agentsContent: string | null;
-  config: AiFilesConfig;
+  state: AiFilesState;
   convexDirName: string;
 }): void {
   const hasSection =
@@ -94,8 +96,8 @@ function logAgentsMdStatus({
 
   const currentHash = hashSha256(agentsMdConvexSection(convexDirName));
   if (
-    config.agentsMdSectionHash !== null &&
-    config.agentsMdSectionHash !== currentHash
+    state.agentsMdSectionHash !== null &&
+    state.agentsMdSectionHash !== currentHash
   ) {
     logMessage(
       `  ${chalkStderr.yellow("⚠")} AGENTS.md: Convex section out of date — run ${chalkStderr.bold("npx convex ai-files update")}`,
@@ -109,11 +111,11 @@ function logAgentsMdStatus({
 
 function logClaudeMdStatus({
   claudeContent,
-  config,
+  state,
   convexDirName,
 }: {
   claudeContent: string | null;
-  config: AiFilesConfig;
+  state: AiFilesState;
   convexDirName: string;
 }): void {
   const hasSection =
@@ -135,7 +137,7 @@ function logClaudeMdStatus({
   }
 
   const currentHash = hashSha256(claudeMdConvexSection(convexDirName));
-  if (config.claudeMdHash !== null && config.claudeMdHash !== currentHash) {
+  if (state.claudeMdHash !== null && state.claudeMdHash !== currentHash) {
     logMessage(
       `  ${chalkStderr.yellow("⚠")} CLAUDE.md: Convex section out of date - run ${chalkStderr.bold("npx convex ai-files update")}`,
     );
@@ -147,27 +149,27 @@ function logClaudeMdStatus({
 }
 
 function logSkillsStatus({
-  config,
+  state,
   canonicalAgentSkillsSha,
   networkAvailable,
 }: {
-  config: AiFilesConfig;
+  state: AiFilesState;
   canonicalAgentSkillsSha: string | null;
   networkAvailable: boolean;
 }): void {
-  if (config.installedSkillNames.length === 0) {
+  if (state.installedSkillNames.length === 0) {
     logMessage(
       `  ${chalkStderr.yellow("⚠")} Agent skills: not installed — run ${chalkStderr.bold("npx convex ai-files install")} to install`,
     );
     return;
   }
 
-  const skillsList = config.installedSkillNames.join(", ");
+  const skillsList = state.installedSkillNames.join(", ");
   const isStale =
     networkAvailable &&
     canonicalAgentSkillsSha !== null &&
-    config.agentSkillsSha !== null &&
-    config.agentSkillsSha !== canonicalAgentSkillsSha;
+    state.agentSkillsSha !== null &&
+    state.agentSkillsSha !== canonicalAgentSkillsSha;
 
   if (isStale) {
     logMessage(
@@ -183,40 +185,44 @@ function logSkillsStatus({
 export async function statusAiFiles({
   projectDir,
   convexDir,
-}: AiFilesPaths): Promise<void> {
+  aiFilesConfig,
+}: AiFilesPaths & {
+  aiFilesConfig?: AiFilesProjectConfig | undefined;
+}): Promise<void> {
   const convexDirName = path.relative(projectDir, convexDir);
   const guidelinesRelPath = path.relative(
     projectDir,
     guidelinesPathForConvexDir(convexDir),
   );
 
-  const config = await readAiConfig({ projectDir, convexDir });
-
-  if (config === null) {
-    logMessage(`Convex AI files: ${chalkStderr.yellow("not installed")}`);
+  if (isAiFilesDisabled(aiFilesConfig)) {
+    logMessage(`Convex AI files: ${chalkStderr.yellow("disabled")}`);
     logMessage(
-      `  Run ${chalkStderr.bold("npx convex ai-files install")} to get started, ` +
-        `or ${chalkStderr.bold("npx convex ai-files disable")} to opt out.`,
+      `  Run ${chalkStderr.bold("npx convex ai-files enable")} to re-enable.`,
     );
     return;
   }
 
-  if (!config.enabled) {
-    logMessage(`Convex AI files: ${chalkStderr.yellow("disabled")}`);
+  const stateResult = await attemptReadAiState(convexDir);
+
+  if (stateResult.kind !== "ok") {
+    logMessage(`Convex AI files: ${chalkStderr.yellow("not installed")}`);
     logMessage(
-      `  Run ${chalkStderr.bold("npx convex ai-files enable")} to re-enable.`,
+      `Run ${chalkStderr.bold("npx convex ai-files install")} to get started.`,
     );
     return;
   }
 
+  const { state } = stateResult;
+
   logMessage(`Convex AI files: ${chalkStderr.green("enabled")}`);
 
   const [versionData, guidelinesFile, agentsContent, claudeContent] =
     await Promise.all([
       getVersion(),
-      readFileSafe(guidelinesPathForConvexDir(convexDir)),
-      readFileSafe(agentsMdPath(projectDir)),
-      readFileSafe(claudeMdPath(projectDir)),
+      readFileOrNull(guidelinesPathForConvexDir(convexDir)),
+      readFileOrNull(agentsMdPath(projectDir)),
+      readFileOrNull(claudeMdPath(projectDir)),
     ]);
 
   const networkAvailable = versionData.kind === "ok";
@@ -230,11 +236,11 @@ export async function statusAiFiles({
   logGuidelinesStatus({
     guidelinesFile,
     guidelinesRelPath,
-    config,
+    state,
     canonicalGuidelinesHash,
     networkAvailable,
   });
-  logAgentsMdStatus({ agentsContent, config, convexDirName });
-  logClaudeMdStatus({ claudeContent, config, convexDirName });
-  logSkillsStatus({ config, canonicalAgentSkillsSha, networkAvailable });
+  logAgentsMdStatus({ agentsContent, state, convexDirName });
+  logClaudeMdStatus({ claudeContent, state, convexDirName });
+  logSkillsStatus({ state, canonicalAgentSkillsSha, networkAvailable });
 }

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

@@ -0,0 +1,50 @@
+import { describe, test, expect, beforeEach, afterEach } from "vitest";
+import fs from "fs";
+import os from "os";
+import path from "path";
+import { attemptReadFile } from "./utils.js";
+
+describe("attemptReadFile", () => {
+  let tmpDir: string;
+
+  beforeEach(() => {
+    tmpDir = fs.mkdtempSync(`${os.tmpdir()}${path.sep}`);
+  });
+
+  afterEach(() => {
+    fs.rmSync(tmpDir, { recursive: true, force: true });
+  });
+
+  test("returns content when the file has text", async () => {
+    const filePath = path.join(tmpDir, "content.txt");
+    fs.writeFileSync(filePath, "hello");
+
+    const result = await attemptReadFile(filePath);
+
+    expect(result).toEqual({ kind: "content", content: "hello" });
+  });
+
+  test("returns empty when the file exists but has no contents", async () => {
+    const filePath = path.join(tmpDir, "empty.txt");
+    fs.writeFileSync(filePath, "");
+
+    const result = await attemptReadFile(filePath);
+
+    expect(result).toEqual({ kind: "empty" });
+  });
+
+  test("returns not-found when the file does not exist", async () => {
+    const filePath = path.join(tmpDir, "missing.txt");
+
+    const result = await attemptReadFile(filePath);
+
+    expect(result).toEqual({ kind: "not-found" });
+  });
+
+  test("throws when fs.readFile fails for another reason", async () => {
+    const dirPath = path.join(tmpDir, "nested-dir");
+    fs.mkdirSync(dirPath);
+
+    await expect(attemptReadFile(dirPath)).rejects.toThrow();
+  });
+});

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

@@ -8,14 +8,35 @@ export function isInInteractiveTerminal(): boolean {
   return process.stdin.isTTY === true;
 }
 
-export async function readFileSafe(filePath: string): Promise<string | null> {
+export type ReadFileResult =
+  | { kind: "not-found" }
+  | { kind: "empty" }
+  | { kind: "content"; content: string };
+
+export async function attemptReadFile(
+  filePath: string,
+): Promise<ReadFileResult> {
   try {
-    return await fs.readFile(filePath, "utf8");
-  } catch {
-    return null;
+    const content = await fs.readFile(filePath, "utf8");
+    if (content.length === 0) return { kind: "empty" };
+    return { kind: "content", content };
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === "ENOENT")
+      return { kind: "not-found" };
+
+    // eslint-disable-next-line no-restricted-syntax
+    throw error;
   }
 }
 
+export async function readFileOrNull(filePath: string): Promise<string | null> {
+  const result = await attemptReadFile(filePath);
+  if (result.kind === "content") return result.content;
+  if (result.kind === "empty") return "";
+  if (result.kind === "not-found") return null;
+  return exhaustiveCheck(result);
+}
+
 /**
  * Attempt to delete a file. Returns `true` if the file was deleted,
  * `false` if it didn't exist or the deletion failed.
@@ -61,7 +82,7 @@ export async function injectManagedSection(
 ): Promise<InjectResult> {
   const { filePath, startMarker, endMarker, section } = opts;
 
-  const existing = (await readFileSafe(filePath)) ?? "";
+  const existing = (await readFileOrNull(filePath)) ?? "";
 
   const startIdx = existing.indexOf(startMarker);
   const endIdx = existing.indexOf(endMarker);
@@ -95,12 +116,12 @@ export type StripResult = "none" | "section" | "file";
  * `"section"` if the section was stripped, or `"file"` if the entire
  * file was deleted.
  */
-export async function stripManagedSection(
+export async function attemptToStripManagedSection(
   opts: ManagedSectionTarget,
 ): Promise<StripResult> {
   const { filePath, startMarker, endMarker } = opts;
 
-  const content = await readFileSafe(filePath);
+  const content = await readFileOrNull(filePath);
   if (content === null) return "none";
 
   const startIdx = content.indexOf(startMarker);
@@ -122,7 +143,12 @@ export async function stripManagedSection(
   return "section";
 }
 
-export async function removeMarkdownSection({
+export function exhaustiveCheck(_param: never): never {
+  // eslint-disable-next-line no-restricted-syntax
+  throw new Error("Internal error: exhaustive check failed.");
+}
+
+export async function attemptToRemoveMarkdownSection({
   projectDir,
   strip,
   fileName,
@@ -145,7 +171,9 @@ export async function removeMarkdownSection({
     return true;
   }
 
-  return false;
+  if (result === "none") return false;
+
+  return exhaustiveCheck(result);
 }
 
 /**
@@ -154,7 +182,7 @@ export async function removeMarkdownSection({
 export async function hasManagedSection(
   opts: ManagedSectionTarget,
 ): Promise<boolean> {
-  const content = await readFileSafe(opts.filePath);
+  const content = await readFileOrNull(opts.filePath);
   return (
     content !== null &&
     content.includes(opts.startMarker) &&

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: