convex 1.34.1 → 1.35.1

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

@@ -56,7 +56,7 @@ vi.mock("../utils/prompts.js", async (importOriginal) => {
   };
 });
 
-import { maybeSetupAiFiles } from "./index.js";
+import { attemptSetupAiFiles } from "./index.js";
 
 function makeTmpDir(): string {
   return fs.mkdtempSync(`${os.tmpdir()}${path.sep}`);
@@ -111,7 +111,7 @@ describe("maybeSetupAiFiles interactive prompt", () => {
   test("user accepts prompt: AI files are installed", async () => {
     mockPromptYesNo.mockResolvedValue(true);
 
-    await maybeSetupAiFiles({ ctx: fakeCtx, convexDir, projectDir: tmpDir });
+    await attemptSetupAiFiles({ ctx: fakeCtx, convexDir, projectDir: tmpDir });
 
     expect(fs.existsSync(guidelinesPath())).toBe(true);
     expect(fs.existsSync(statePath())).toBe(true);
@@ -125,7 +125,7 @@ describe("maybeSetupAiFiles interactive prompt", () => {
   test("user declines prompt: no config and no AI files are written", async () => {
     mockPromptYesNo.mockResolvedValue(false);
 
-    await maybeSetupAiFiles({ ctx: fakeCtx, convexDir, projectDir: tmpDir });
+    await attemptSetupAiFiles({ ctx: fakeCtx, convexDir, projectDir: tmpDir });
 
     expect(fs.existsSync(guidelinesPath())).toBe(false);
     expect(fs.existsSync(path.join(tmpDir, "AGENTS.md"))).toBe(false);
@@ -136,7 +136,7 @@ describe("maybeSetupAiFiles interactive prompt", () => {
   test("non-interactive terminal skips the prompt and does not install AI files", async () => {
     process.stdin.isTTY = false;
 
-    await maybeSetupAiFiles({ ctx: fakeCtx, convexDir, projectDir: tmpDir });
+    await attemptSetupAiFiles({ ctx: fakeCtx, convexDir, projectDir: tmpDir });
 
     expect(fs.existsSync(guidelinesPath())).toBe(false);
     expect(fs.existsSync(statePath())).toBe(false);
@@ -163,7 +163,7 @@ describe("maybeSetupAiFiles interactive prompt", () => {
       ),
     );
 
-    await maybeSetupAiFiles({ ctx: fakeCtx, convexDir, projectDir: tmpDir });
+    await attemptSetupAiFiles({ ctx: fakeCtx, convexDir, projectDir: tmpDir });
 
     expect(fs.existsSync(path.join(stateDir, "ai-files.state.json"))).toBe(
       true,
@@ -187,7 +187,7 @@ describe("maybeSetupAiFiles interactive prompt", () => {
       ].join("\n"),
     );
 
-    await maybeSetupAiFiles({ ctx: fakeCtx, convexDir, projectDir: tmpDir });
+    await attemptSetupAiFiles({ ctx: fakeCtx, convexDir, projectDir: tmpDir });
 
     expect(fs.existsSync(statePath())).toBe(true);
     expect(fs.existsSync(guidelinesPath())).toBe(true);

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

@@ -5,8 +5,10 @@ import { promises as fs } from "fs";
 import { chalkStderr } from "chalk";
 import { logMessage } from "../../../bundler/log.js";
 import { getVersion, fetchAgentSkillsSha } from "../versionApi.js";
-import { type AiFilesConfig } from "./config.js";
-import { iife, readFileSafe } from "./utils.js";
+import { type AiFilesState } from "./state.js";
+import { exhaustiveCheck, iife, readFileOrNull } from "./utils.js";
+
+import { type AiFilesProjectConfig } from "../config.js";
 
 /**
  * Read the frontmatter `name:` values from skills installed by the skills CLI.
@@ -28,7 +30,7 @@ async function readInstalledSkillNames(projectDir: string): Promise<string[]> {
   const names: string[] = [];
   for (const entry of entries) {
     const skillMdPath = path.join(skillsDir, entry, "SKILL.md");
-    const content = await readFileSafe(skillMdPath);
+    const content = await readFileOrNull(skillMdPath);
     if (content === null) continue;
     const match = content.match(/^---[\s\S]*?^name:\s*(.+?)\s*$/m);
     if (match) {
@@ -38,12 +40,28 @@ async function readInstalledSkillNames(projectDir: string): Promise<string[]> {
   return names;
 }
 
+/**
+ * Resolve the configured agent list, falling back to defaults.
+ */
+function configuredSkillAgents(
+  aiFilesConfig?: AiFilesProjectConfig | undefined,
+): string[] {
+  // We default to the two most popular agents for now, "codex" installs to `.agents` which also
+  // covers cursor and many other tools. See: https://github.com/vercel-labs/skills?tab=readme-ov-file#supported-agents
+  const defaultAgents = ["claude-code", "codex"];
+  return aiFilesConfig?.skills?.agents ?? defaultAgents;
+}
+
 /**
  * Runs `npx skills add get-convex/agent-skills --yes` in the given directory.
  * Returns true on success, false if the process fails or cannot be started.
  */
-function runSkillsAdd(cwd: string): Promise<boolean> {
-  return runSkillsCommand(cwd, ["add", "get-convex/agent-skills", "--yes"]);
+function runSkillsAdd(cwd: string, agents: string[]): Promise<boolean> {
+  const args = ["add", "get-convex/agent-skills", "--yes"];
+  for (const agent of agents) {
+    args.push("--agent", agent);
+  }
+  return runSkillsCommand(cwd, args);
 }
 
 /**
@@ -69,12 +87,15 @@ async function shouldRunSkillsCli(): Promise<boolean> {
 
   if (versionData.kind === "error") return true;
 
-  if (versionData.data.disableSkillsCli) {
-    logMessage(chalkStderr.yellow(`Agent skills are temporarily disabled.`));
-    return false;
+  if (versionData.kind === "ok") {
+    if (versionData.data.disableSkillsCli) {
+      logMessage(chalkStderr.yellow(`Agent skills are temporarily disabled.`));
+      return false;
+    }
+    return true;
   }
 
-  return true;
+  return exhaustiveCheck(versionData);
 }
 
 /**
@@ -118,20 +139,24 @@ async function removeSkillsLockIfEmpty({
 }
 
 /**
- * Install Convex agent skills and record the SHA and names into the config.
+ * Install Convex agent skills and record the SHA and names into the state.
  * Handles the kill-switch check and all logging internally.
  */
 export async function installSkills({
   projectDir,
-  config,
+  state,
+  aiFilesConfig,
 }: {
   projectDir: string;
-  config: AiFilesConfig;
+  state: AiFilesState;
+  aiFilesConfig?: AiFilesProjectConfig | undefined;
 }): Promise<void> {
   if (!(await shouldRunSkillsCli())) return;
+  const agents = configuredSkillAgents(aiFilesConfig);
+  if (agents.length === 0) return;
 
   logMessage("Installing Convex agent skills...");
-  const skillsOk = await runSkillsAdd(projectDir);
+  const skillsOk = await runSkillsAdd(projectDir, agents);
   if (!skillsOk) {
     logMessage(
       chalkStderr.yellow(
@@ -142,10 +167,12 @@ export async function installSkills({
   }
 
   const sha = await fetchAgentSkillsSha();
-  if (sha) config.agentSkillsSha = sha;
+  if (sha) state.agentSkillsSha = sha;
 
   const names = await readInstalledSkillNames(projectDir);
-  if (names.length > 0) config.installedSkillNames = names;
+  if (names.length > 0) state.installedSkillNames = names;
+
+  logMessage(`${chalkStderr.green("✔")} Skills installed`);
 }
 
 /**
@@ -159,7 +186,8 @@ export async function removeInstalledSkills({
   projectDir: string;
   skillNames: string[];
 }): Promise<boolean> {
-  if (skillNames.length === 0 || !(await shouldRunSkillsCli())) return false;
+  if (skillNames.length === 0) return false;
+  if (!(await shouldRunSkillsCli())) return false;
 
   logMessage(`Removing Convex agent skills: ${skillNames.join(", ")}`);
   const skillsOk = await runSkillsRemove({ cwd: projectDir, skillNames });
@@ -176,8 +204,10 @@ export async function removeInstalledSkills({
     projectDir,
     removedSkillNames: skillNames,
   });
+
   if (lockRemoved)
     logMessage(`${chalkStderr.green("✔")} Deleted skills-lock.json.`);
+
   return true;
 }
 

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

@@ -0,0 +1,280 @@
+import { describe, test, expect, vi, beforeEach, afterEach } from "vitest";
+import * as Sentry from "@sentry/node";
+import { promises as fs } from "fs";
+import {
+  aiFilesStateSchema,
+  attemptReadAiState,
+  hasAiState,
+  readAiStateOrDefault,
+  writeAiState,
+} from "./state.js";
+
+vi.mock("@sentry/node", () => ({
+  captureException: vi.fn(),
+  captureMessage: vi.fn(),
+}));
+
+vi.mock("fs", () => ({
+  promises: {
+    readFile: vi.fn(),
+    writeFile: vi.fn(),
+    mkdir: vi.fn().mockResolvedValue(undefined),
+  },
+}));
+
+const mockFs = vi.mocked(fs);
+const mockCaptureException = vi.mocked(Sentry.captureException);
+
+const dummyConvexDir = "/tmp/test-project/convex";
+
+describe("aiFilesStateSchema", () => {
+  test("accepts a fully populated valid state object", () => {
+    const result = aiFilesStateSchema.safeParse({
+      guidelinesHash: "abc123",
+      agentsMdSectionHash: "def456",
+      claudeMdHash: "ghi789",
+      agentSkillsSha: "deadbeef",
+      installedSkillNames: ["convex-migrations", "convex-perf-review"],
+    });
+    expect(result.success).toBe(true);
+  });
+
+  test("accepts null hashes", () => {
+    const result = aiFilesStateSchema.safeParse({
+      guidelinesHash: null,
+      agentsMdSectionHash: null,
+      claudeMdHash: null,
+      agentSkillsSha: null,
+    });
+    expect(result.success).toBe(true);
+  });
+
+  test("applies default for installedSkillNames when absent", () => {
+    const result = aiFilesStateSchema.safeParse({
+      guidelinesHash: "abc",
+      agentsMdSectionHash: null,
+      claudeMdHash: null,
+      agentSkillsSha: null,
+    });
+    expect(result.success).toBe(true);
+    if (result.success) {
+      expect(result.data.installedSkillNames).toEqual([]);
+    }
+  });
+
+  test("rejects a number where a string hash is expected", () => {
+    const result = aiFilesStateSchema.safeParse({
+      guidelinesHash: 123,
+      agentsMdSectionHash: null,
+      claudeMdHash: null,
+      agentSkillsSha: null,
+    });
+    expect(result.success).toBe(false);
+  });
+
+  test("rejects missing required fields", () => {
+    const result = aiFilesStateSchema.safeParse({
+      guidelinesHash: "abc",
+    });
+    expect(result.success).toBe(false);
+  });
+});
+
+describe("attemptReadAiState", () => {
+  beforeEach(() => vi.clearAllMocks());
+  afterEach(() => vi.resetAllMocks());
+
+  test("returns no-file when the state file does not exist", async () => {
+    mockFs.readFile.mockRejectedValue(
+      Object.assign(new Error("ENOENT"), { code: "ENOENT" }),
+    );
+
+    const result = await attemptReadAiState(dummyConvexDir);
+
+    expect(result).toEqual({ kind: "no-file" });
+    expect(mockCaptureException).not.toHaveBeenCalled();
+  });
+
+  test("returns no-file when the state file is empty", async () => {
+    mockFs.readFile.mockResolvedValueOnce("");
+
+    const result = await attemptReadAiState(dummyConvexDir);
+
+    expect(result).toEqual({ kind: "no-file" });
+    expect(mockCaptureException).not.toHaveBeenCalled();
+  });
+
+  test("throws when reading the state file fails for reasons other than not found", async () => {
+    const error = Object.assign(new Error("EACCES"), { code: "EACCES" });
+    mockFs.readFile.mockRejectedValueOnce(error);
+
+    await expect(attemptReadAiState(dummyConvexDir)).rejects.toBe(error);
+    expect(mockCaptureException).not.toHaveBeenCalled();
+  });
+
+  test("returns ok with parsed state", async () => {
+    mockFs.readFile.mockResolvedValueOnce(
+      JSON.stringify({
+        guidelinesHash: "abc",
+        agentsMdSectionHash: "def",
+        claudeMdHash: null,
+        agentSkillsSha: null,
+      }),
+    );
+
+    const result = await attemptReadAiState(dummyConvexDir);
+
+    expect(result).toEqual({
+      kind: "ok",
+      state: {
+        guidelinesHash: "abc",
+        agentsMdSectionHash: "def",
+        claudeMdHash: null,
+        agentSkillsSha: null,
+        installedSkillNames: [],
+      },
+    });
+  });
+
+  test("returns parse-error and captures exception when JSON is invalid", async () => {
+    mockFs.readFile.mockResolvedValueOnce("not valid json {{{}");
+
+    const result = await attemptReadAiState(dummyConvexDir);
+
+    expect(result.kind).toBe("parse-error");
+    expect(mockCaptureException).toHaveBeenCalledWith(expect.any(Error));
+  });
+
+  test("returns parse-error and captures exception when schema validation fails", async () => {
+    mockFs.readFile.mockResolvedValueOnce(
+      JSON.stringify({
+        guidelinesHash: 99,
+        agentsMdSectionHash: null,
+      }),
+    );
+
+    const result = await attemptReadAiState(dummyConvexDir);
+
+    expect(result.kind).toBe("parse-error");
+    expect(mockCaptureException).toHaveBeenCalledWith(expect.any(Error));
+  });
+});
+
+describe("readAiStateOrDefault", () => {
+  beforeEach(() => vi.clearAllMocks());
+  afterEach(() => vi.resetAllMocks());
+
+  test("returns default state when no state file exists", async () => {
+    mockFs.readFile.mockRejectedValue(
+      Object.assign(new Error("ENOENT"), { code: "ENOENT" }),
+    );
+
+    const result = await readAiStateOrDefault(dummyConvexDir);
+
+    expect(result).toEqual({
+      guidelinesHash: null,
+      agentsMdSectionHash: null,
+      claudeMdHash: null,
+      agentSkillsSha: null,
+      installedSkillNames: [],
+    });
+  });
+
+  test("returns default state on parse error", async () => {
+    mockFs.readFile.mockResolvedValueOnce("not valid json {{{}");
+
+    const result = await readAiStateOrDefault(dummyConvexDir);
+
+    expect(result).toEqual({
+      guidelinesHash: null,
+      agentsMdSectionHash: null,
+      claudeMdHash: null,
+      agentSkillsSha: null,
+      installedSkillNames: [],
+    });
+    expect(mockCaptureException).toHaveBeenCalled();
+  });
+
+  test("returns parsed state when state file exists", async () => {
+    const stored = {
+      guidelinesHash: "abc",
+      agentsMdSectionHash: "def",
+      claudeMdHash: null,
+      agentSkillsSha: "deadbeef",
+    };
+    mockFs.readFile.mockResolvedValueOnce(JSON.stringify(stored));
+
+    const result = await readAiStateOrDefault(dummyConvexDir);
+
+    expect(result).toEqual({
+      ...stored,
+      installedSkillNames: [],
+    });
+  });
+});
+
+describe("hasAiState", () => {
+  beforeEach(() => vi.clearAllMocks());
+  afterEach(() => vi.resetAllMocks());
+
+  test("returns false when state file does not exist", async () => {
+    mockFs.readFile.mockRejectedValue(
+      Object.assign(new Error("ENOENT"), { code: "ENOENT" }),
+    );
+
+    const result = await hasAiState(dummyConvexDir);
+
+    expect(result).toBe(false);
+    expect(mockCaptureException).not.toHaveBeenCalled();
+  });
+
+  test("returns true when a valid state file exists", async () => {
+    mockFs.readFile.mockResolvedValueOnce(
+      JSON.stringify({
+        guidelinesHash: "abc",
+        agentsMdSectionHash: "def",
+        claudeMdHash: null,
+        agentSkillsSha: null,
+      }),
+    );
+
+    const result = await hasAiState(dummyConvexDir);
+
+    expect(result).toBe(true);
+  });
+
+  test("returns false and captures exception when the state file is invalid", async () => {
+    mockFs.readFile.mockResolvedValueOnce("not valid json {{{}");
+
+    const result = await hasAiState(dummyConvexDir);
+
+    expect(result).toBe(false);
+    expect(mockCaptureException).toHaveBeenCalledWith(expect.any(Error));
+  });
+});
+
+describe("writeAiState", () => {
+  beforeEach(() => vi.clearAllMocks());
+  afterEach(() => vi.resetAllMocks());
+
+  test("writes state file", async () => {
+    mockFs.writeFile.mockResolvedValue(undefined);
+
+    const state = {
+      guidelinesHash: "abc",
+      agentsMdSectionHash: "def",
+      claudeMdHash: null,
+      agentSkillsSha: null,
+      installedSkillNames: ["convex-migrations"],
+    };
+
+    await writeAiState({ state, convexDir: dummyConvexDir });
+
+    expect(mockFs.writeFile).toHaveBeenCalledTimes(1);
+    expect(mockFs.writeFile).toHaveBeenCalledWith(
+      expect.stringContaining("ai-files.state.json"),
+      JSON.stringify(state, null, 2) + "\n",
+      "utf8",
+    );
+  });
+});

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

@@ -0,0 +1,82 @@
+import * as Sentry from "@sentry/node";
+// Use raw fs (not ctx.fs) so these operations run asynchronously and don't
+// interfere with the file-watcher used by `convex dev`.
+// eslint-disable-next-line no-restricted-imports
+import { promises as fs } from "fs";
+import { z } from "zod";
+import { aiDirForConvexDir, aiFilesStatePathForConvexDir } from "./paths.js";
+import { attemptReadFile, exhaustiveCheck } from "./utils.js";
+
+export const aiFilesStateSchema = z.object({
+  guidelinesHash: z.string().nullable(),
+  agentsMdSectionHash: z.string().nullable(),
+  claudeMdHash: z.string().nullable(),
+  // Commit SHA from get-convex/agent-skills that was current when skills were
+  // last installed. Used to detect when newer skills are available.
+  agentSkillsSha: z.string().nullable(),
+  // Names of skills installed by `npx skills add`, used by `remove` to
+  // only remove Convex-managed skills.
+  installedSkillNames: z.array(z.string()).default([]),
+});
+
+export type AiFilesState = z.infer<typeof aiFilesStateSchema>;
+
+const DEFAULT_AI_STATE: AiFilesState = {
+  guidelinesHash: null,
+  agentsMdSectionHash: null,
+  claudeMdHash: null,
+  agentSkillsSha: null,
+  installedSkillNames: [],
+};
+
+export type AttemptReadAiStateResult =
+  | { kind: "no-file" }
+  | { kind: "ok"; state: AiFilesState }
+  | { kind: "parse-error"; error: unknown };
+
+export async function attemptReadAiState(
+  convexDir: string,
+): Promise<AttemptReadAiStateResult> {
+  const result = await attemptReadFile(aiFilesStatePathForConvexDir(convexDir));
+  if (result.kind === "not-found" || result.kind === "empty")
+    return { kind: "no-file" };
+
+  try {
+    const state = aiFilesStateSchema.parse(JSON.parse(result.content));
+    return { kind: "ok", state };
+  } catch (error) {
+    Sentry.captureException(error);
+    return { kind: "parse-error", error };
+  }
+}
+
+export async function readAiStateOrDefault(
+  convexDir: string,
+): Promise<AiFilesState> {
+  const result = await attemptReadAiState(convexDir);
+  if (result.kind === "ok") return result.state;
+  if (result.kind === "no-file") return { ...DEFAULT_AI_STATE };
+  if (result.kind === "parse-error") return { ...DEFAULT_AI_STATE };
+  return exhaustiveCheck(result);
+}
+
+export async function hasAiState(convexDir: string): Promise<boolean> {
+  const result = await attemptReadAiState(convexDir);
+  return result.kind === "ok";
+}
+
+export async function writeAiState({
+  state,
+  convexDir,
+}: {
+  state: AiFilesState;
+  convexDir: string;
+}): Promise<void> {
+  const validated = aiFilesStateSchema.parse(state);
+  await fs.mkdir(aiDirForConvexDir(convexDir), { recursive: true });
+  await fs.writeFile(
+    aiFilesStatePathForConvexDir(convexDir),
+    JSON.stringify(validated, null, 2) + "\n",
+    "utf8",
+  );
+}