convex 1.34.0 → 1.34.1

package/src/cli/lib/{ai → aiFiles}/config.ts

@@ -6,8 +6,9 @@ import { promises as fs } from "fs";
 import path from "path";
 import { z } from "zod";
 import { aiFilesStatePathForConvexDir } from "./paths.js";
+import { iife, readFileSafe } from "./utils.js";
 
-const aiFilesStateSchema = z.object({
+export const aiFilesStateSchema = z.object({
   guidelinesHash: z.string().nullable(),
   agentsMdSectionHash: z.string().nullable(),
   claudeMdHash: z.string().nullable(),
@@ -23,17 +24,21 @@ const aiFilesProjectConfigSchema = z
   .object({
     aiFiles: z
       .object({
-        disableStalenessMessage: z.boolean().default(false),
+        // `enabled` is the canonical field. When present it takes full
+        // precedence - `enabled: true` will re-enable even if the legacy
+        // disableStalenessMessage field is still `true` in the file.
+        enabled: z.boolean().optional(),
+        // @deprecated - use `enabled` instead. Read for backward compat;
+        // new writes always emit `enabled` and drop this key.
+        disableStalenessMessage: z.boolean().optional(),
       })
-      .default({ disableStalenessMessage: false }),
+      .default({}),
   })
   .passthrough();
 
-export const aiFilesSchema = aiFilesStateSchema;
-
 type AiFilesState = z.infer<typeof aiFilesStateSchema>;
 export type AiFilesConfig = AiFilesState & {
-  disableStalenessMessage: boolean;
+  enabled: boolean;
 };
 
 const EMPTY_AI_STATE: AiFilesState = {
@@ -44,35 +49,38 @@ const EMPTY_AI_STATE: AiFilesState = {
   installedSkillNames: [],
 };
 
-async function readAiDisabledFromProjectConfig(
+async function readAiEnabledFromProjectConfig(
   projectDir: string,
 ): Promise<boolean> {
-  let raw: string;
-  try {
-    raw = await fs.readFile(path.join(projectDir, "convex.json"), "utf8");
-  } catch {
-    return false;
-  }
+  const raw = await readFileSafe(path.join(projectDir, "convex.json"));
+  if (raw === null) return true;
   try {
     const parsed = aiFilesProjectConfigSchema.parse(JSON.parse(raw));
-    return parsed.aiFiles.disableStalenessMessage;
+    // `enabled` takes full precedence when explicitly set.
+    if (parsed.aiFiles.enabled !== undefined) return parsed.aiFiles.enabled;
+    // Legacy `disableStalenessMessage` - invert it.
+    return !(parsed.aiFiles.disableStalenessMessage ?? false);
   } catch (err) {
     Sentry.captureException(err);
-    return false;
+    return true;
   }
 }
 
-export async function writeAiDisabledToProjectConfig(
-  disableStalenessMessage: boolean,
-  projectDir: string,
-): Promise<void> {
+export async function writeAiEnabledToProjectConfig({
+  projectDir,
+  enabled,
+}: {
+  projectDir: string;
+  enabled: boolean;
+}): Promise<void> {
   const filePath = path.join(projectDir, "convex.json");
-  let existing: unknown = {};
-  try {
-    existing = JSON.parse(await fs.readFile(filePath, "utf8"));
-  } catch {
-    // Use a minimal object when convex.json doesn't exist yet or is unreadable.
-  }
+  const existing = await iife(async () => {
+    try {
+      return JSON.parse(await fs.readFile(filePath, "utf8")) as unknown;
+    } catch {
+      return {} as unknown;
+    }
+  });
   const base =
     existing !== null &&
     typeof existing === "object" &&
@@ -86,54 +94,75 @@ export async function writeAiDisabledToProjectConfig(
       ? (base.aiFiles as Record<string, unknown>)
       : {};
   const { $schema, ...rest } = base;
+  // Remove legacy keys on every write.
+  const { disableStalenessMessage: _legacy, ...restAiFiles } = aiFilesValue;
   const next: Record<string, unknown> = {
     $schema: $schema ?? "node_modules/convex/schemas/convex.schema.json",
     ...rest,
-    aiFiles: {
-      ...aiFilesValue,
-      disableStalenessMessage,
-    },
+    aiFiles: { ...restAiFiles, enabled },
   };
   await fs.writeFile(filePath, JSON.stringify(next, null, 2) + "\n", "utf8");
 }
 
-export async function readAiConfig(
-  projectDir: string,
-  convexDir: string,
-): Promise<AiFilesConfig | null> {
-  const disableStalenessMessage =
-    await readAiDisabledFromProjectConfig(projectDir);
-  let rawState: string;
-  try {
-    rawState = await fs.readFile(
-      aiFilesStatePathForConvexDir(convexDir),
-      "utf8",
-    );
-  } catch {
+export async function readAiConfig({
+  projectDir,
+  convexDir,
+}: {
+  projectDir: string;
+  convexDir: string;
+}): Promise<AiFilesConfig | null> {
+  const enabled = await readAiEnabledFromProjectConfig(projectDir);
+  const rawState = await readFileSafe(aiFilesStatePathForConvexDir(convexDir));
+  if (rawState === null) {
     // No state file means AI files are not installed, unless the user has
-    // explicitly disabled install/staleness messages in convex.json.
-    return disableStalenessMessage
-      ? { ...EMPTY_AI_STATE, disableStalenessMessage }
-      : null;
+    // explicitly disabled in convex.json.
+    return !enabled ? { ...EMPTY_AI_STATE, enabled } : null;
   }
   try {
     const state = aiFilesStateSchema.parse(JSON.parse(rawState));
-    return {
-      ...state,
-      disableStalenessMessage,
-    };
+    return { ...state, enabled };
   } catch (err) {
     Sentry.captureException(err);
     return null;
   }
 }
 
-export async function writeAiConfig(
-  config: AiFilesConfig,
-  projectDir: string,
-  convexDir: string,
-  options?: { persistDisabledPreference?: "ifTrue" | "always" | "never" },
-): Promise<void> {
+export async function hasAiFilesConfig({
+  projectDir,
+  convexDir,
+}: {
+  projectDir: string;
+  convexDir: string;
+}): Promise<boolean> {
+  if (!(await readAiEnabledFromProjectConfig(projectDir))) {
+    return true;
+  }
+  try {
+    const rawState = await fs.readFile(
+      aiFilesStatePathForConvexDir(convexDir),
+      "utf8",
+    );
+    aiFilesStateSchema.parse(JSON.parse(rawState));
+    return true;
+  } catch (err) {
+    if ((err as NodeJS.ErrnoException).code !== "ENOENT") {
+      Sentry.captureException(err);
+    }
+    return false;
+  }
+}
+
+export async function writeAiConfig({
+  config,
+  projectDir,
+  convexDir,
+  options,
+}: {
+  config: AiFilesConfig;
+  projectDir: string;
+  convexDir: string;
+  options?: { persistEnabledPreference?: "ifFalse" | "always" | "never" };
+}): Promise<void> {
   const state = aiFilesStateSchema.parse({
     guidelinesHash: config.guidelinesHash,
     agentsMdSectionHash: config.agentsMdSectionHash,
@@ -146,14 +175,14 @@ export async function writeAiConfig(
     JSON.stringify(state, null, 2) + "\n",
     "utf8",
   );
-  const persistMode = options?.persistDisabledPreference ?? "ifTrue";
+
+  const persistMode = options?.persistEnabledPreference ?? "ifFalse";
   if (
     persistMode === "always" ||
-    (persistMode === "ifTrue" && config.disableStalenessMessage)
-  ) {
-    await writeAiDisabledToProjectConfig(
-      config.disableStalenessMessage,
+    (persistMode === "ifFalse" && !config.enabled)
+  )
+    await writeAiEnabledToProjectConfig({
       projectDir,
-    );
-  }
+      enabled: config.enabled,
+    });
 }

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

@@ -0,0 +1,25 @@
+import path from "path";
+import { chalkStderr } from "chalk";
+import { logMessage } from "../../../bundler/log.js";
+import { safelyDeleteFile } from "./utils.js";
+
+/**
+ * Remove the legacy `.cursor/rules/convex_rules.mdc` file if it exists.
+ * This file was written by the old cursor rules auto-update feature (removed
+ * in favour of the AI files system). We clean it up unconditionally
+ * during `writeAiFiles`, `convex ai-files update`, and `convex ai-files remove`
+ * since it was always auto-managed and is now superseded by
+ * `convex/_generated/ai/guidelines.md`.
+ */
+export async function removeLegacyCursorRulesFile(
+  projectDir: string,
+): Promise<boolean> {
+  const removed = await safelyDeleteFile(
+    path.join(projectDir, ".cursor", "rules", "convex_rules.mdc"),
+  );
+  if (removed)
+    logMessage(
+      `${chalkStderr.green("✔")} Removed legacy .cursor/rules/convex_rules.mdc (superseded by convex/_generated/ai/guidelines.md).`,
+    );
+  return removed;
+}

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

@@ -0,0 +1,40 @@
+import { describe, test, expect, beforeEach, afterEach } from "vitest";
+import fs from "fs";
+import os from "os";
+import path from "path";
+import { hasGuidelinesInstalled } from "./guidelinesmd.js";
+
+describe("hasGuidelinesInstalled", () => {
+  let tmpDir: string;
+  let convexDir: string;
+
+  beforeEach(() => {
+    tmpDir = fs.mkdtempSync(`${os.tmpdir()}${path.sep}`);
+    convexDir = path.join(tmpDir, "convex");
+    fs.mkdirSync(path.join(convexDir, "_generated", "ai"), { recursive: true });
+  });
+
+  afterEach(() => {
+    fs.rmSync(tmpDir, { recursive: true, force: true });
+  });
+
+  test("returns false when guidelines.md does not exist", async () => {
+    expect(await hasGuidelinesInstalled(convexDir)).toBe(false);
+  });
+
+  test("returns true when guidelines.md exists", async () => {
+    fs.writeFileSync(
+      path.join(convexDir, "_generated", "ai", "guidelines.md"),
+      "some content",
+    );
+    expect(await hasGuidelinesInstalled(convexDir)).toBe(true);
+  });
+
+  test("returns true even when guidelines.md is empty", async () => {
+    fs.writeFileSync(
+      path.join(convexDir, "_generated", "ai", "guidelines.md"),
+      "",
+    );
+    expect(await hasGuidelinesInstalled(convexDir)).toBe(true);
+  });
+});

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

@@ -0,0 +1,41 @@
+// eslint-disable-next-line no-restricted-imports
+import { promises as fs } from "fs";
+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";
+
+export async function hasGuidelinesInstalled(
+  convexDir: string,
+): Promise<boolean> {
+  return (await readFileSafe(guidelinesPathForConvexDir(convexDir))) !== null;
+}
+
+/**
+ * Download and write the guidelines file.
+ * Guidelines live in `_generated/` so local edits are not expected and are
+ * not preserved.
+ */
+export async function installGuidelinesFile({
+  convexDir,
+  config,
+}: {
+  convexDir: string;
+  config: AiFilesConfig;
+}): Promise<void> {
+  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;
+  }
+
+  await fs.writeFile(guidelinesPathForConvexDir(convexDir), guidelines, "utf8");
+  config.guidelinesHash = hashSha256(guidelines);
+}