convex 1.34.0 → 1.34.1

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

@@ -0,0 +1,77 @@
+import {
+  AGENTS_MD_START_MARKER,
+  AGENTS_MD_END_MARKER,
+  agentsMdConvexSection,
+} from "../../codegen_templates/agentsmd.js";
+import { agentsMdPath } from "./paths.js";
+import { type AiFilesConfig } from "./config.js";
+import {
+  type ManagedSectionTarget,
+  type InjectResult,
+  type StripResult,
+  injectManagedSection,
+  stripManagedSection,
+  hasManagedSection,
+  removeMarkdownSection,
+} from "./utils.js";
+
+function target(projectDir?: string): ManagedSectionTarget {
+  return {
+    filePath: agentsMdPath(projectDir),
+    startMarker: AGENTS_MD_START_MARKER,
+    endMarker: AGENTS_MD_END_MARKER,
+  };
+}
+
+export async function injectAgentsMdSection({
+  section,
+  projectDir,
+}: {
+  section: string;
+  projectDir?: string;
+}): Promise<InjectResult> {
+  return injectManagedSection({ ...target(projectDir), section });
+}
+
+export async function stripAgentsMdSection(
+  projectDir: string,
+): Promise<StripResult> {
+  return stripManagedSection(target(projectDir));
+}
+
+export async function removeAgentsMdSection(
+  projectDir: string,
+): Promise<boolean> {
+  return removeMarkdownSection({
+    projectDir,
+    strip: stripAgentsMdSection,
+    fileName: "AGENTS.md",
+  });
+}
+
+export async function hasAgentsMdInstalled(
+  projectDir: string,
+): Promise<boolean> {
+  return hasManagedSection(target(projectDir));
+}
+
+/**
+ * Inject (or update) the Convex section in AGENTS.md and record the hash.
+ * Returns true if the file was actually written.
+ */
+export async function applyAgentsMdSection({
+  projectDir,
+  config,
+  convexDirName,
+}: {
+  projectDir: string;
+  config: AiFilesConfig;
+  convexDirName: string;
+}): Promise<boolean> {
+  const result = await injectAgentsMdSection({
+    section: agentsMdConvexSection(convexDirName),
+    projectDir,
+  });
+  config.agentsMdSectionHash = result.sectionHash;
+  return result.didWrite;
+}

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

@@ -0,0 +1,92 @@
+import { describe, test, expect, beforeEach, afterEach } from "vitest";
+import fs from "fs";
+import os from "os";
+import path from "path";
+import { injectClaudeMdSection, hasClaudeMdInstalled } from "./claudemd.js";
+import {
+  CLAUDE_MD_START_MARKER,
+  CLAUDE_MD_END_MARKER,
+} from "../../codegen_templates/claudemd.js";
+
+describe("injectClaudeMdSection", () => {
+  let tmpDir: string;
+
+  beforeEach(() => {
+    tmpDir = fs.mkdtempSync(`${os.tmpdir()}${path.sep}`);
+  });
+
+  afterEach(() => {
+    fs.rmSync(tmpDir, { recursive: true, force: true });
+  });
+
+  const section = `${CLAUDE_MD_START_MARKER}\n## Convex\nRead guidelines.\n${CLAUDE_MD_END_MARKER}`;
+
+  test("creates CLAUDE.md when it does not exist", async () => {
+    const result = await injectClaudeMdSection({ section, projectDir: tmpDir });
+
+    const content = fs.readFileSync(path.join(tmpDir, "CLAUDE.md"), "utf8");
+    expect(content).toContain(CLAUDE_MD_START_MARKER);
+    expect(content).toContain(CLAUDE_MD_END_MARKER);
+    expect(result.didWrite).toBe(true);
+  });
+
+  test("appends managed section to existing CLAUDE.md content", async () => {
+    fs.writeFileSync(
+      path.join(tmpDir, "CLAUDE.md"),
+      "My custom instructions\n",
+    );
+
+    const result = await injectClaudeMdSection({ section, projectDir: tmpDir });
+
+    const content = fs.readFileSync(path.join(tmpDir, "CLAUDE.md"), "utf8");
+    expect(content).toContain("My custom instructions");
+    expect(content).toContain(CLAUDE_MD_START_MARKER);
+    expect(result.didWrite).toBe(true);
+  });
+
+  test("replaces managed section without touching user content", async () => {
+    const oldSection = `${CLAUDE_MD_START_MARKER}\nOld\n${CLAUDE_MD_END_MARKER}`;
+    fs.writeFileSync(
+      path.join(tmpDir, "CLAUDE.md"),
+      `# Header\n\n${oldSection}\n\n# Footer\n`,
+      "utf8",
+    );
+
+    await injectClaudeMdSection({ section, projectDir: tmpDir });
+
+    const content = fs.readFileSync(path.join(tmpDir, "CLAUDE.md"), "utf8");
+    expect(content).toContain("# Header");
+    expect(content).toContain("# Footer");
+    expect(content).toContain("## Convex");
+    expect(content).not.toContain("Old");
+  });
+});
+
+describe("hasClaudeMdInstalled", () => {
+  let tmpDir: string;
+
+  beforeEach(() => {
+    tmpDir = fs.mkdtempSync(`${os.tmpdir()}${path.sep}`);
+  });
+
+  afterEach(() => {
+    fs.rmSync(tmpDir, { recursive: true, force: true });
+  });
+
+  test("returns false when CLAUDE.md does not exist", async () => {
+    expect(await hasClaudeMdInstalled(tmpDir)).toBe(false);
+  });
+
+  test("returns false when CLAUDE.md exists but has no managed markers", async () => {
+    fs.writeFileSync(path.join(tmpDir, "CLAUDE.md"), "User content only\n");
+    expect(await hasClaudeMdInstalled(tmpDir)).toBe(false);
+  });
+
+  test("returns true when both markers are present", async () => {
+    fs.writeFileSync(
+      path.join(tmpDir, "CLAUDE.md"),
+      `${CLAUDE_MD_START_MARKER}\n## Convex\n${CLAUDE_MD_END_MARKER}\n`,
+    );
+    expect(await hasClaudeMdInstalled(tmpDir)).toBe(true);
+  });
+});

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

@@ -0,0 +1,77 @@
+import {
+  CLAUDE_MD_END_MARKER,
+  CLAUDE_MD_START_MARKER,
+  claudeMdConvexSection,
+} from "../../codegen_templates/claudemd.js";
+import { claudeMdPath } from "./paths.js";
+import { type AiFilesConfig } from "./config.js";
+import {
+  type ManagedSectionTarget,
+  type InjectResult,
+  type StripResult,
+  injectManagedSection,
+  stripManagedSection,
+  hasManagedSection,
+  removeMarkdownSection,
+} from "./utils.js";
+
+function target(projectDir?: string): ManagedSectionTarget {
+  return {
+    filePath: claudeMdPath(projectDir),
+    startMarker: CLAUDE_MD_START_MARKER,
+    endMarker: CLAUDE_MD_END_MARKER,
+  };
+}
+
+export async function injectClaudeMdSection({
+  section,
+  projectDir,
+}: {
+  section: string;
+  projectDir?: string;
+}): Promise<InjectResult> {
+  return injectManagedSection({ ...target(projectDir), section });
+}
+
+export async function stripClaudeMdSection(
+  projectDir: string,
+): Promise<StripResult> {
+  return stripManagedSection(target(projectDir));
+}
+
+export async function removeClaudeMdSection(
+  projectDir: string,
+): Promise<boolean> {
+  return removeMarkdownSection({
+    projectDir,
+    strip: stripClaudeMdSection,
+    fileName: "CLAUDE.md",
+  });
+}
+
+export async function hasClaudeMdInstalled(
+  projectDir: string,
+): Promise<boolean> {
+  return hasManagedSection(target(projectDir));
+}
+
+/**
+ * Inject (or update) the Convex section in CLAUDE.md and record the hash.
+ * Returns true if the file was actually written.
+ */
+export async function applyClaudeMdSection({
+  projectDir,
+  config,
+  convexDirName,
+}: {
+  projectDir: string;
+  config: AiFilesConfig;
+  convexDirName: string;
+}): Promise<boolean> {
+  const result = await injectClaudeMdSection({
+    section: claudeMdConvexSection(convexDirName),
+    projectDir,
+  });
+  config.claudeMdHash = result.sectionHash;
+  return result.didWrite;
+}

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

@@ -2,10 +2,11 @@ import { describe, test, expect, vi, beforeEach, afterEach } from "vitest";
 import * as Sentry from "@sentry/node";
 import { promises as fs } from "fs";
 import {
-  aiFilesSchema,
+  aiFilesStateSchema,
+  hasAiFilesConfig,
   readAiConfig,
   writeAiConfig,
-  writeAiDisabledToProjectConfig,
+  writeAiEnabledToProjectConfig,
 } from "./config.js";
 
 vi.mock("@sentry/node", () => ({
@@ -26,9 +27,9 @@ const mockCaptureException = vi.mocked(Sentry.captureException);
 const dummyProjectDir = "/tmp/test-project";
 const dummyConvexDir = "/tmp/test-project/convex";
 
-describe("aiFilesSchema", () => {
+describe("aiFilesStateSchema", () => {
   test("accepts a fully populated valid state object", () => {
-    const result = aiFilesSchema.safeParse({
+    const result = aiFilesStateSchema.safeParse({
       guidelinesHash: "abc123",
       agentsMdSectionHash: "def456",
       claudeMdHash: "ghi789",
@@ -39,7 +40,7 @@ describe("aiFilesSchema", () => {
   });
 
   test("accepts null hashes", () => {
-    const result = aiFilesSchema.safeParse({
+    const result = aiFilesStateSchema.safeParse({
       guidelinesHash: null,
       agentsMdSectionHash: null,
       claudeMdHash: null,
@@ -49,7 +50,7 @@ describe("aiFilesSchema", () => {
   });
 
   test("applies default for installedSkillNames when absent", () => {
-    const result = aiFilesSchema.safeParse({
+    const result = aiFilesStateSchema.safeParse({
       guidelinesHash: "abc",
       agentsMdSectionHash: null,
       claudeMdHash: null,
@@ -62,7 +63,7 @@ describe("aiFilesSchema", () => {
   });
 
   test("rejects a number where a string hash is expected", () => {
-    const result = aiFilesSchema.safeParse({
+    const result = aiFilesStateSchema.safeParse({
       guidelinesHash: 123,
       agentsMdSectionHash: null,
       claudeMdHash: null,
@@ -72,7 +73,7 @@ describe("aiFilesSchema", () => {
   });
 
   test("rejects missing required fields", () => {
-    const result = aiFilesSchema.safeParse({
+    const result = aiFilesStateSchema.safeParse({
       guidelinesHash: "abc",
     });
     expect(result.success).toBe(false);
@@ -88,13 +89,16 @@ describe("readAiConfig", () => {
       Object.assign(new Error("ENOENT"), { code: "ENOENT" }),
     );
 
-    const result = await readAiConfig(dummyProjectDir, dummyConvexDir);
+    const result = await readAiConfig({
+      projectDir: dummyProjectDir,
+      convexDir: dummyConvexDir,
+    });
 
     expect(result).toBeNull();
     expect(mockCaptureException).not.toHaveBeenCalled();
   });
 
-  test("returns parsed state with disableStalenessMessage=false when convex.json is missing", async () => {
+  test("returns parsed state with enabled=true when convex.json is missing", async () => {
     mockFs.readFile
       .mockRejectedValueOnce(
         Object.assign(new Error("ENOENT"), { code: "ENOENT" }),
@@ -108,7 +112,10 @@ describe("readAiConfig", () => {
         }),
       );
 
-    const result = await readAiConfig(dummyProjectDir, dummyConvexDir);
+    const result = await readAiConfig({
+      projectDir: dummyProjectDir,
+      convexDir: dummyConvexDir,
+    });
 
     expect(result).toEqual({
       guidelinesHash: "abc",
@@ -116,7 +123,7 @@ describe("readAiConfig", () => {
       claudeMdHash: null,
       agentSkillsSha: null,
       installedSkillNames: [],
-      disableStalenessMessage: false,
+      enabled: true,
     });
   });
 
@@ -129,7 +136,10 @@ describe("readAiConfig", () => {
         Object.assign(new Error("ENOENT"), { code: "ENOENT" }),
       );
 
-    const result = await readAiConfig(dummyProjectDir, dummyConvexDir);
+    const result = await readAiConfig({
+      projectDir: dummyProjectDir,
+      convexDir: dummyConvexDir,
+    });
 
     expect(result).toEqual({
       guidelinesHash: null,
@@ -137,7 +147,7 @@ describe("readAiConfig", () => {
       claudeMdHash: null,
       agentSkillsSha: null,
       installedSkillNames: [],
-      disableStalenessMessage: true,
+      enabled: false,
     });
   });
 
@@ -148,7 +158,10 @@ describe("readAiConfig", () => {
       )
       .mockResolvedValueOnce("not valid json {{{}");
 
-    const result = await readAiConfig(dummyProjectDir, dummyConvexDir);
+    const result = await readAiConfig({
+      projectDir: dummyProjectDir,
+      convexDir: dummyConvexDir,
+    });
 
     expect(result).toBeNull();
     expect(mockCaptureException).toHaveBeenCalledWith(expect.any(Error));
@@ -166,18 +179,21 @@ describe("readAiConfig", () => {
         }),
       );
 
-    const result = await readAiConfig(dummyProjectDir, dummyConvexDir);
+    const result = await readAiConfig({
+      projectDir: dummyProjectDir,
+      convexDir: dummyConvexDir,
+    });
 
     expect(result).toBeNull();
     expect(mockCaptureException).toHaveBeenCalledWith(expect.any(Error));
   });
 
-  test("returns parsed state and reads disableStalenessMessage from convex.json", async () => {
+  test("reads enabled=false from legacy disableStalenessMessage field for backward compat", async () => {
     const stored = {
       guidelinesHash: "abc",
       agentsMdSectionHash: "def",
       claudeMdHash: null,
-      agentSkillsSha: "deadbeef",
+      agentSkillsSha: null,
     };
     mockFs.readFile
       .mockResolvedValueOnce(
@@ -185,13 +201,113 @@ describe("readAiConfig", () => {
       )
       .mockResolvedValueOnce(JSON.stringify(stored));
 
-    const result = await readAiConfig(dummyProjectDir, dummyConvexDir);
+    const result = await readAiConfig({
+      projectDir: dummyProjectDir,
+      convexDir: dummyConvexDir,
+    });
 
     expect(result).toEqual({
       ...stored,
       installedSkillNames: [],
-      disableStalenessMessage: true,
+      enabled: false,
+    });
+  });
+
+  test("enabled: true takes precedence over legacy disableStalenessMessage: true", async () => {
+    const stored = {
+      guidelinesHash: "abc",
+      agentsMdSectionHash: "def",
+      claudeMdHash: null,
+      agentSkillsSha: null,
+    };
+    mockFs.readFile
+      .mockResolvedValueOnce(
+        JSON.stringify({
+          aiFiles: { enabled: true, disableStalenessMessage: true },
+        }),
+      )
+      .mockResolvedValueOnce(JSON.stringify(stored));
+
+    const result = await readAiConfig({
+      projectDir: dummyProjectDir,
+      convexDir: dummyConvexDir,
+    });
+
+    expect(result).toEqual({
+      ...stored,
+      installedSkillNames: [],
+      enabled: true,
+    });
+  });
+});
+
+describe("hasAiFilesConfig", () => {
+  beforeEach(() => vi.clearAllMocks());
+  afterEach(() => vi.resetAllMocks());
+
+  test("returns false when neither convex.json nor state file exists", async () => {
+    mockFs.readFile.mockRejectedValue(
+      Object.assign(new Error("ENOENT"), { code: "ENOENT" }),
+    );
+
+    const result = await hasAiFilesConfig({
+      projectDir: dummyProjectDir,
+      convexDir: dummyConvexDir,
+    });
+
+    expect(result).toBe(false);
+    expect(mockCaptureException).not.toHaveBeenCalled();
+  });
+
+  test("returns true when convex.json disables staleness messages", async () => {
+    mockFs.readFile.mockResolvedValueOnce(
+      JSON.stringify({ aiFiles: { disableStalenessMessage: true } }),
+    );
+
+    const result = await hasAiFilesConfig({
+      projectDir: dummyProjectDir,
+      convexDir: dummyConvexDir,
     });
+
+    expect(result).toBe(true);
+  });
+
+  test("returns true when a valid state file exists", async () => {
+    mockFs.readFile
+      .mockRejectedValueOnce(
+        Object.assign(new Error("ENOENT"), { code: "ENOENT" }),
+      )
+      .mockResolvedValueOnce(
+        JSON.stringify({
+          guidelinesHash: "abc",
+          agentsMdSectionHash: "def",
+          claudeMdHash: null,
+          agentSkillsSha: null,
+        }),
+      );
+
+    const result = await hasAiFilesConfig({
+      projectDir: dummyProjectDir,
+      convexDir: dummyConvexDir,
+    });
+
+    expect(result).toBe(true);
+  });
+
+  test("returns false and captures exception when the state file is invalid", async () => {
+    mockFs.readFile
+      .mockRejectedValueOnce(
+        Object.assign(new Error("ENOENT"), { code: "ENOENT" }),
+      )
+      .mockResolvedValueOnce("not valid json {{{}");
+
+    const result = await hasAiFilesConfig({
+      projectDir: dummyProjectDir,
+      convexDir: dummyConvexDir,
+    });
+
+    expect(result).toBe(false);
+    expect(mockCaptureException).toHaveBeenCalledWith(expect.any(Error));
   });
 });
 
@@ -199,11 +315,11 @@ describe("writeAiConfig", () => {
   beforeEach(() => vi.clearAllMocks());
   afterEach(() => vi.resetAllMocks());
 
-  test("writes state file and does not persist disableStalenessMessage=false by default", async () => {
+  test("writes state file and does not persist enabled=true by default", async () => {
     mockFs.writeFile.mockResolvedValue(undefined);
 
     const config = {
-      disableStalenessMessage: false,
+      enabled: true,
       guidelinesHash: "abc",
       agentsMdSectionHash: "def",
       claudeMdHash: null,
@@ -211,7 +327,11 @@ describe("writeAiConfig", () => {
       installedSkillNames: ["convex-migrations"],
     };
 
-    await writeAiConfig(config, dummyProjectDir, dummyConvexDir);
+    await writeAiConfig({
+      config,
+      projectDir: dummyProjectDir,
+      convexDir: dummyConvexDir,
+    });
 
     expect(mockFs.writeFile).toHaveBeenCalledTimes(1);
     expect(mockFs.writeFile).toHaveBeenCalledWith(
@@ -231,23 +351,23 @@ describe("writeAiConfig", () => {
     );
   });
 
-  test("persists disableStalenessMessage=false when requested explicitly", async () => {
+  test("persists enabled=true when requested explicitly", async () => {
     mockFs.writeFile.mockResolvedValue(undefined);
     mockFs.readFile.mockResolvedValue("{}");
 
-    await writeAiConfig(
-      {
-        disableStalenessMessage: false,
+    await writeAiConfig({
+      config: {
+        enabled: true,
         guidelinesHash: null,
         agentsMdSectionHash: null,
         claudeMdHash: null,
         agentSkillsSha: null,
         installedSkillNames: [],
       },
-      dummyProjectDir,
-      dummyConvexDir,
-      { persistDisabledPreference: "always" },
-    );
+      projectDir: dummyProjectDir,
+      convexDir: dummyConvexDir,
+      options: { persistEnabledPreference: "always" },
+    });
 
     expect(mockFs.writeFile).toHaveBeenNthCalledWith(
       2,
@@ -255,9 +375,7 @@ describe("writeAiConfig", () => {
       JSON.stringify(
         {
           $schema: "node_modules/convex/schemas/convex.schema.json",
-          aiFiles: {
-            disableStalenessMessage: false,
-          },
+          aiFiles: { enabled: true },
         },
         null,
         2,
@@ -266,48 +384,48 @@ describe("writeAiConfig", () => {
     );
   });
 
-  test("persists to convex.json by default when disableStalenessMessage is true", async () => {
+  test("persists enabled=false to convex.json by default", async () => {
     mockFs.writeFile.mockResolvedValue(undefined);
     mockFs.readFile.mockResolvedValue("{}");
 
-    await writeAiConfig(
-      {
-        disableStalenessMessage: true,
+    await writeAiConfig({
+      config: {
+        enabled: false,
         guidelinesHash: null,
         agentsMdSectionHash: null,
         claudeMdHash: null,
         agentSkillsSha: null,
         installedSkillNames: [],
       },
-      dummyProjectDir,
-      dummyConvexDir,
-    );
+      projectDir: dummyProjectDir,
+      convexDir: dummyConvexDir,
+    });
 
     expect(mockFs.writeFile).toHaveBeenCalledTimes(2);
     expect(mockFs.writeFile).toHaveBeenNthCalledWith(
       2,
       expect.stringContaining("convex.json"),
-      expect.stringContaining('"disableStalenessMessage": true'),
+      expect.stringContaining('"enabled": false'),
       "utf8",
     );
   });
 
-  test("never writes to convex.json when persistDisabledPreference is 'never'", async () => {
+  test("never writes to convex.json when persistEnabledPreference is 'never'", async () => {
     mockFs.writeFile.mockResolvedValue(undefined);
 
-    await writeAiConfig(
-      {
-        disableStalenessMessage: true,
+    await writeAiConfig({
+      config: {
+        enabled: false,
         guidelinesHash: null,
         agentsMdSectionHash: null,
         claudeMdHash: null,
         agentSkillsSha: null,
         installedSkillNames: [],
       },
-      dummyProjectDir,
-      dummyConvexDir,
-      { persistDisabledPreference: "never" },
-    );
+      projectDir: dummyProjectDir,
+      convexDir: dummyConvexDir,
+      options: { persistEnabledPreference: "never" },
+    });
 
     expect(mockFs.writeFile).toHaveBeenCalledTimes(1);
     expect(mockFs.writeFile).toHaveBeenCalledWith(
@@ -318,21 +436,25 @@ describe("writeAiConfig", () => {
   });
 });
 
-describe("writeAiDisabledToProjectConfig", () => {
+describe("writeAiEnabledToProjectConfig", () => {
   beforeEach(() => vi.clearAllMocks());
   afterEach(() => vi.resetAllMocks());
 
-  test("writes only convex.json with disableStalenessMessage=true", async () => {
-    mockFs.readFile.mockResolvedValue("{}");
+  test("writes enabled=false to convex.json and drops legacy disableStalenessMessage", async () => {
+    mockFs.readFile.mockResolvedValue(
+      JSON.stringify({ aiFiles: { disableStalenessMessage: true } }),
+    );
     mockFs.writeFile.mockResolvedValue(undefined);
 
-    await writeAiDisabledToProjectConfig(true, dummyProjectDir);
+    await writeAiEnabledToProjectConfig({
+      projectDir: dummyProjectDir,
+      enabled: false,
+    });
 
     expect(mockFs.writeFile).toHaveBeenCalledTimes(1);
-    expect(mockFs.writeFile).toHaveBeenCalledWith(
-      expect.stringContaining("convex.json"),
-      expect.stringContaining('"disableStalenessMessage": true'),
-      "utf8",
-    );
+    const written = mockFs.writeFile.mock.calls[0][1] as string;
+    const parsed = JSON.parse(written);
+    expect(parsed.aiFiles.enabled).toBe(false);
+    expect(parsed.aiFiles.disableStalenessMessage).toBeUndefined();
   });
 });