convex 1.34.0 → 1.35.0

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

@@ -1,5 +1,10 @@
 import path from "path";
 
+export type AiFilesPaths = {
+  projectDir: string;
+  convexDir: string;
+};
+
 const AI_FILES_PARENT_DIR = "_generated";
 const AI_FILES_DIR = "ai";
 

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

@@ -1,11 +1,21 @@
 import { afterEach, beforeEach, describe, expect, test, vi } from "vitest";
-import { PassThrough, Writable } from "stream";
 import fs from "fs";
 import os from "os";
 import path from "path";
 import type { Context } from "../../../bundler/context.js";
+import {
+  AGENTS_MD_END_MARKER,
+  AGENTS_MD_START_MARKER,
+} from "../../codegen_templates/agentsmd.js";
 
-let testInput: PassThrough;
+const { mockPromptYesNo } = vi.hoisted(() => {
+  return { mockPromptYesNo: vi.fn() };
+});
+
+vi.mock("@sentry/node", () => ({
+  captureException: vi.fn(),
+  captureMessage: vi.fn(),
+}));
 
 vi.mock("../../../bundler/log.js", () => ({
   logMessage: vi.fn(),
@@ -16,10 +26,13 @@ vi.mock("../versionApi.js", () => ({
   downloadGuidelines: vi.fn(async () => "prompt test guidelines content"),
   fetchAgentSkillsSha: vi.fn(async () => "prompt-test-sha"),
   getVersion: vi.fn(async () => ({
-    message: null,
-    guidelinesHash: "prompt-test-guidelines-hash",
-    agentSkillsSha: "prompt-test-agent-skills-sha",
-    disableSkillsCli: false,
+    kind: "ok",
+    data: {
+      message: null,
+      guidelinesHash: "prompt-test-guidelines-hash",
+      agentSkillsSha: "prompt-test-agent-skills-sha",
+      disableSkillsCli: false,
+    },
   })),
 }));
 
@@ -35,22 +48,15 @@ vi.mock("child_process", () => ({
   },
 }));
 
-vi.mock("@inquirer/confirm", async (importOriginal) => {
-  const actual = await importOriginal<typeof import("@inquirer/confirm")>();
+vi.mock("../utils/prompts.js", async (importOriginal) => {
+  const actual = await importOriginal<typeof import("../utils/prompts.js")>();
   return {
     ...actual,
-    default: (config: any, context: any) => {
-      const output = new Writable({
-        write(_c, _e, cb) {
-          cb();
-        },
-      });
-      return actual.default(config, { ...context, input: testInput, output });
-    },
+    promptYesNo: mockPromptYesNo,
   };
 });
 
-import { maybeSetupAiFiles } from "./index.js";
+import { attemptSetupAiFiles } from "./index.js";
 
 function makeTmpDir(): string {
   return fs.mkdtempSync(`${os.tmpdir()}${path.sep}`);
@@ -92,7 +98,7 @@ describe("maybeSetupAiFiles interactive prompt", () => {
     fs.writeFileSync(path.join(convexDir, "schema.ts"), "");
     originalIsTTY = process.stdin.isTTY;
     process.stdin.isTTY = true;
-    testInput = new PassThrough();
+    mockPromptYesNo.mockResolvedValue(true);
   });
 
   afterEach(() => {
@@ -103,11 +109,9 @@ describe("maybeSetupAiFiles interactive prompt", () => {
   });
 
   test("user accepts prompt: AI files are installed", async () => {
-    const result = maybeSetupAiFiles(fakeCtx, convexDir, tmpDir);
+    mockPromptYesNo.mockResolvedValue(true);
 
-    // Simulate pressing Enter to accept the default (yes)
-    testInput.emit("keypress", null, { name: "enter" });
-    await result;
+    await attemptSetupAiFiles({ ctx: fakeCtx, convexDir, projectDir: tmpDir });
 
     expect(fs.existsSync(guidelinesPath())).toBe(true);
     expect(fs.existsSync(statePath())).toBe(true);
@@ -119,13 +123,9 @@ describe("maybeSetupAiFiles interactive prompt", () => {
   });
 
   test("user declines prompt: no config and no AI files are written", async () => {
-    const result = maybeSetupAiFiles(fakeCtx, convexDir, tmpDir);
+    mockPromptYesNo.mockResolvedValue(false);
 
-    // Type "n" then Enter to decline
-    testInput.write("n");
-    testInput.emit("keypress", null, { name: "n" });
-    testInput.emit("keypress", null, { name: "enter" });
-    await result;
+    await attemptSetupAiFiles({ ctx: fakeCtx, convexDir, projectDir: tmpDir });
 
     expect(fs.existsSync(guidelinesPath())).toBe(false);
     expect(fs.existsSync(path.join(tmpDir, "AGENTS.md"))).toBe(false);
@@ -133,10 +133,10 @@ describe("maybeSetupAiFiles interactive prompt", () => {
     expect(fs.existsSync(projectConfigPath())).toBe(false);
   });
 
-  test("agent mode skips the prompt and does not install AI files", async () => {
-    vi.stubEnv("CONVEX_AGENT_MODE", "anonymous");
+  test("non-interactive terminal skips the prompt and does not install AI files", async () => {
+    process.stdin.isTTY = false;
 
-    await maybeSetupAiFiles(fakeCtx, convexDir, tmpDir);
+    await attemptSetupAiFiles({ ctx: fakeCtx, convexDir, projectDir: tmpDir });
 
     expect(fs.existsSync(guidelinesPath())).toBe(false);
     expect(fs.existsSync(statePath())).toBe(false);
@@ -144,4 +144,52 @@ describe("maybeSetupAiFiles interactive prompt", () => {
     expect(fs.existsSync(path.join(tmpDir, "CLAUDE.md"))).toBe(false);
     expect(fs.existsSync(projectConfigPath())).toBe(false);
   });
+
+  test("existing state file updates AI files without prompting", async () => {
+    const stateDir = path.join(convexDir, "_generated", "ai");
+    fs.mkdirSync(stateDir, { recursive: true });
+    fs.writeFileSync(
+      path.join(stateDir, "ai-files.state.json"),
+      JSON.stringify(
+        {
+          guidelinesHash: "hash",
+          agentsMdSectionHash: "hash",
+          claudeMdHash: "hash",
+          agentSkillsSha: "sha",
+          installedSkillNames: [],
+        },
+        null,
+        2,
+      ),
+    );
+
+    await attemptSetupAiFiles({ ctx: fakeCtx, convexDir, projectDir: tmpDir });
+
+    expect(fs.existsSync(path.join(stateDir, "ai-files.state.json"))).toBe(
+      true,
+    );
+    expect(fs.existsSync(guidelinesPath())).toBe(true);
+    expect(fs.readFileSync(guidelinesPath(), "utf8")).toBe(
+      "prompt test guidelines content",
+    );
+  });
+
+  test("existing AGENTS.md managed section rebuilds state without prompting", async () => {
+    fs.writeFileSync(
+      path.join(tmpDir, "AGENTS.md"),
+      [
+        "# Team notes",
+        "",
+        AGENTS_MD_START_MARKER,
+        "Managed section",
+        AGENTS_MD_END_MARKER,
+        "",
+      ].join("\n"),
+    );
+
+    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

@@ -0,0 +1,243 @@
+import child_process from "child_process";
+import path from "path";
+// eslint-disable-next-line no-restricted-imports
+import { promises as fs } from "fs";
+import { chalkStderr } from "chalk";
+import { logMessage } from "../../../bundler/log.js";
+import { getVersion, fetchAgentSkillsSha } from "../versionApi.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.
+ */
+async function readInstalledSkillNames(projectDir: string): Promise<string[]> {
+  const skillsDir = path.join(projectDir, ".agents", "skills");
+  const entries = await iife(async () => {
+    try {
+      const dirents = await fs.readdir(skillsDir, { withFileTypes: true });
+      return dirents
+        .filter((d) => d.isDirectory() || d.isSymbolicLink())
+        .map((d) => d.name);
+    } catch {
+      return [] as string[];
+    }
+  });
+  if (entries.length === 0) return [];
+
+  const names: string[] = [];
+  for (const entry of entries) {
+    const skillMdPath = path.join(skillsDir, entry, "SKILL.md");
+    const content = await readFileOrNull(skillMdPath);
+    if (content === null) continue;
+    const match = content.match(/^---[\s\S]*?^name:\s*(.+?)\s*$/m);
+    if (match) {
+      names.push(match[1]);
+    }
+  }
+  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, 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);
+}
+
+/**
+ * Runs `npx skills remove <name...> --yes` to surgically remove only the
+ * Convex-managed skills, leaving any skills from other sources intact.
+ */
+function runSkillsRemove({
+  cwd,
+  skillNames,
+}: {
+  cwd: string;
+  skillNames: string[];
+}): Promise<boolean> {
+  return runSkillsCommand(cwd, ["remove", ...skillNames, "--yes"]);
+}
+
+/**
+ * This function exists so we have a way to disable skills installs without pushing a new
+ * version of the convex CLI
+ */
+async function shouldRunSkillsCli(): Promise<boolean> {
+  const versionData = await getVersion();
+
+  if (versionData.kind === "error") return true;
+
+  if (versionData.kind === "ok") {
+    if (versionData.data.disableSkillsCli) {
+      logMessage(chalkStderr.yellow(`Agent skills are temporarily disabled.`));
+      return false;
+    }
+    return true;
+  }
+
+  return exhaustiveCheck(versionData);
+}
+
+/**
+ * Remove the skills-lock.json file if it only contains skills that we
+ * are removing. The `npx skills remove` command leaves the lockfile behind
+ * even when it's logically empty.
+ */
+async function removeSkillsLockIfEmpty({
+  projectDir,
+  removedSkillNames,
+}: {
+  projectDir: string;
+  removedSkillNames: string[];
+}): Promise<boolean> {
+  const lockPath = path.join(projectDir, "skills-lock.json");
+  try {
+    const content = await fs.readFile(lockPath, "utf8");
+    const lock = JSON.parse(content);
+
+    if (
+      !lock ||
+      typeof lock !== "object" ||
+      !lock.skills ||
+      typeof lock.skills !== "object"
+    ) {
+      return false;
+    }
+
+    const remainingSkills = Object.keys(lock.skills).filter(
+      (name) => !removedSkillNames.includes(name),
+    );
+
+    if (remainingSkills.length === 0) {
+      await fs.unlink(lockPath);
+      return true;
+    }
+    return false;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * 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,
+  state,
+  aiFilesConfig,
+}: {
+  projectDir: string;
+  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, agents);
+  if (!skillsOk) {
+    logMessage(
+      chalkStderr.yellow(
+        "Could not install agent skills. You can retry manually with: npx skills add get-convex/agent-skills",
+      ),
+    );
+    return;
+  }
+
+  const sha = await fetchAgentSkillsSha();
+  if (sha) state.agentSkillsSha = sha;
+
+  const names = await readInstalledSkillNames(projectDir);
+  if (names.length > 0) state.installedSkillNames = names;
+
+  logMessage(`${chalkStderr.green("✔")} Skills installed`);
+}
+
+/**
+ * Remove Convex-managed agent skills and clean up the lock file if empty.
+ * Returns true if any removal occurred.
+ */
+export async function removeInstalledSkills({
+  projectDir,
+  skillNames,
+}: {
+  projectDir: string;
+  skillNames: string[];
+}): Promise<boolean> {
+  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 });
+  if (!skillsOk) {
+    logMessage(
+      chalkStderr.yellow(
+        "Could not remove agent skills automatically. Remove them manually with: npx skills remove",
+      ),
+    );
+    return false;
+  }
+
+  const lockRemoved = await removeSkillsLockIfEmpty({
+    projectDir,
+    removedSkillNames: skillNames,
+  });
+
+  if (lockRemoved)
+    logMessage(`${chalkStderr.green("✔")} Deleted skills-lock.json.`);
+
+  return true;
+}
+
+function runSkillsCommand(cwd: string, args: string[]): Promise<boolean> {
+  return new Promise((resolve) => {
+    const proc = child_process.spawn(
+      "npx",
+      ["--yes", "skills@latest", ...args],
+      {
+        cwd,
+        stdio: "pipe",
+        // .cmd files on Windows require shell execution.
+        shell: process.platform === "win32",
+      },
+    );
+    let capturedOutput = "";
+    proc.stdout?.on("data", (chunk) => {
+      capturedOutput += chunk.toString();
+    });
+    proc.stderr?.on("data", (chunk) => {
+      capturedOutput += chunk.toString();
+    });
+    proc.on("close", (code) => {
+      if (code !== 0 && capturedOutput.trim().length > 0) {
+        const lines = capturedOutput.trim().split(/\r?\n/);
+        const tail = lines.slice(-10).join("\n");
+        logMessage(chalkStderr.gray(`skills output (tail):\n${tail}`));
+      }
+      resolve(code === 0);
+    });
+    proc.on("error", () => resolve(false));
+  });
+}

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",
+    );
+  });
+});