convex 1.34.0 → 1.34.1

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,18 +48,11 @@ 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,
   };
 });
 
@@ -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 maybeSetupAiFiles({ 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 maybeSetupAiFiles({ 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 maybeSetupAiFiles({ 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 maybeSetupAiFiles({ 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 maybeSetupAiFiles({ 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,213 @@
+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 AiFilesConfig } from "./config.js";
+import { iife, readFileSafe } from "./utils.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 readFileSafe(skillMdPath);
+    if (content === null) continue;
+    const match = content.match(/^---[\s\S]*?^name:\s*(.+?)\s*$/m);
+    if (match) {
+      names.push(match[1]);
+    }
+  }
+  return names;
+}
+
+/**
+ * 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"]);
+}
+
+/**
+ * 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.data.disableSkillsCli) {
+    logMessage(chalkStderr.yellow(`Agent skills are temporarily disabled.`));
+    return false;
+  }
+
+  return true;
+}
+
+/**
+ * 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 config.
+ * Handles the kill-switch check and all logging internally.
+ */
+export async function installSkills({
+  projectDir,
+  config,
+}: {
+  projectDir: string;
+  config: AiFilesConfig;
+}): Promise<void> {
+  if (!(await shouldRunSkillsCli())) return;
+
+  logMessage("Installing Convex agent skills...");
+  const skillsOk = await runSkillsAdd(projectDir);
+  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) config.agentSkillsSha = sha;
+
+  const names = await readInstalledSkillNames(projectDir);
+  if (names.length > 0) config.installedSkillNames = names;
+}
+
+/**
+ * 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 || !(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/status.ts

@@ -0,0 +1,240 @@
+import path from "path";
+import { chalkStderr } from "chalk";
+import { logMessage } from "../../../bundler/log.js";
+import {
+  AGENTS_MD_START_MARKER,
+  AGENTS_MD_END_MARKER,
+  agentsMdConvexSection,
+} from "../../codegen_templates/agentsmd.js";
+import {
+  CLAUDE_MD_START_MARKER,
+  CLAUDE_MD_END_MARKER,
+  claudeMdConvexSection,
+} from "../../codegen_templates/claudemd.js";
+import { getVersion } from "../versionApi.js";
+import { hashSha256 } from "../utils/hash.js";
+import {
+  type AiFilesPaths,
+  agentsMdPath,
+  claudeMdPath,
+  guidelinesPathForConvexDir,
+} from "./paths.js";
+import { type AiFilesConfig, readAiConfig } from "./config.js";
+import { readFileSafe } from "./utils.js";
+
+function logGuidelinesStatus({
+  guidelinesFile,
+  guidelinesRelPath,
+  config,
+  canonicalGuidelinesHash,
+  networkAvailable,
+}: {
+  guidelinesFile: string | null;
+  guidelinesRelPath: string;
+  config: AiFilesConfig;
+  canonicalGuidelinesHash: string | null;
+  networkAvailable: boolean;
+}): void {
+  if (guidelinesFile === null) {
+    logMessage(
+      `  ${chalkStderr.yellow("⚠")} ${guidelinesRelPath}: not on disk — run ${chalkStderr.bold("npx convex ai-files install")} to reinstall`,
+    );
+    return;
+  }
+
+  const isLocallyModified =
+    config.guidelinesHash !== null &&
+    hashSha256(guidelinesFile) !== config.guidelinesHash;
+
+  if (isLocallyModified) {
+    logMessage(
+      `  ${chalkStderr.yellow("⚠")} ${guidelinesRelPath}: installed, modified locally (changes will be overwritten on next update)`,
+    );
+    return;
+  }
+
+  const isOutOfDate =
+    networkAvailable &&
+    canonicalGuidelinesHash !== null &&
+    config.guidelinesHash !== null &&
+    config.guidelinesHash !== canonicalGuidelinesHash;
+
+  if (isOutOfDate) {
+    logMessage(
+      `  ${chalkStderr.yellow("⚠")} ${guidelinesRelPath}: installed, out of date — run ${chalkStderr.bold("npx convex ai-files update")}`,
+    );
+    return;
+  }
+
+  logMessage(
+    `  ${chalkStderr.green("✔")} ${guidelinesRelPath}: installed${networkAvailable ? ", up to date" : ""}`,
+  );
+}
+
+function logAgentsMdStatus({
+  agentsContent,
+  config,
+  convexDirName,
+}: {
+  agentsContent: string | null;
+  config: AiFilesConfig;
+  convexDirName: string;
+}): void {
+  const hasSection =
+    agentsContent !== null &&
+    agentsContent.includes(AGENTS_MD_START_MARKER) &&
+    agentsContent.includes(AGENTS_MD_END_MARKER);
+
+  if (!hasSection) {
+    logMessage(
+      `  ${chalkStderr.yellow("⚠")} AGENTS.md: Convex section missing — run ${chalkStderr.bold("npx convex ai-files install")} to reinstall`,
+    );
+    return;
+  }
+
+  const currentHash = hashSha256(agentsMdConvexSection(convexDirName));
+  if (
+    config.agentsMdSectionHash !== null &&
+    config.agentsMdSectionHash !== currentHash
+  ) {
+    logMessage(
+      `  ${chalkStderr.yellow("⚠")} AGENTS.md: Convex section out of date — run ${chalkStderr.bold("npx convex ai-files update")}`,
+    );
+  } else {
+    logMessage(
+      `  ${chalkStderr.green("✔")} AGENTS.md: Convex section present, up to date`,
+    );
+  }
+}
+
+function logClaudeMdStatus({
+  claudeContent,
+  config,
+  convexDirName,
+}: {
+  claudeContent: string | null;
+  config: AiFilesConfig;
+  convexDirName: string;
+}): void {
+  const hasSection =
+    claudeContent !== null &&
+    claudeContent.includes(CLAUDE_MD_START_MARKER) &&
+    claudeContent.includes(CLAUDE_MD_END_MARKER);
+
+  if (!hasSection) {
+    if (claudeContent === null) {
+      logMessage(
+        `  ${chalkStderr.yellow("⚠")} CLAUDE.md: missing - run ${chalkStderr.bold("npx convex ai-files install")} to create it`,
+      );
+    } else {
+      logMessage(
+        `  ${chalkStderr.yellow("⚠")} CLAUDE.md: no Convex section present - run ${chalkStderr.bold("npx convex ai-files update")} to add it`,
+      );
+    }
+    return;
+  }
+
+  const currentHash = hashSha256(claudeMdConvexSection(convexDirName));
+  if (config.claudeMdHash !== null && config.claudeMdHash !== currentHash) {
+    logMessage(
+      `  ${chalkStderr.yellow("⚠")} CLAUDE.md: Convex section out of date - run ${chalkStderr.bold("npx convex ai-files update")}`,
+    );
+  } else {
+    logMessage(
+      `  ${chalkStderr.green("✔")} CLAUDE.md: Convex section present, up to date`,
+    );
+  }
+}
+
+function logSkillsStatus({
+  config,
+  canonicalAgentSkillsSha,
+  networkAvailable,
+}: {
+  config: AiFilesConfig;
+  canonicalAgentSkillsSha: string | null;
+  networkAvailable: boolean;
+}): void {
+  if (config.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 isStale =
+    networkAvailable &&
+    canonicalAgentSkillsSha !== null &&
+    config.agentSkillsSha !== null &&
+    config.agentSkillsSha !== canonicalAgentSkillsSha;
+
+  if (isStale) {
+    logMessage(
+      `  ${chalkStderr.yellow("⚠")} Agent skills: ${skillsList} — out of date, run ${chalkStderr.bold("npx convex ai-files update")}`,
+    );
+  } else {
+    logMessage(
+      `  ${chalkStderr.green("✔")} Agent skills: ${skillsList}${networkAvailable ? " (up to date)" : ""}`,
+    );
+  }
+}
+
+export async function statusAiFiles({
+  projectDir,
+  convexDir,
+}: AiFilesPaths): 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")}`);
+    logMessage(
+      `  Run ${chalkStderr.bold("npx convex ai-files install")} to get started, ` +
+        `or ${chalkStderr.bold("npx convex ai-files disable")} to opt out.`,
+    );
+    return;
+  }
+
+  if (!config.enabled) {
+    logMessage(`Convex AI files: ${chalkStderr.yellow("disabled")}`);
+    logMessage(
+      `  Run ${chalkStderr.bold("npx convex ai-files enable")} to re-enable.`,
+    );
+    return;
+  }
+
+  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)),
+    ]);
+
+  const networkAvailable = versionData.kind === "ok";
+  const canonicalGuidelinesHash = networkAvailable
+    ? versionData.data.guidelinesHash
+    : null;
+  const canonicalAgentSkillsSha = networkAvailable
+    ? versionData.data.agentSkillsSha
+    : null;
+
+  logGuidelinesStatus({
+    guidelinesFile,
+    guidelinesRelPath,
+    config,
+    canonicalGuidelinesHash,
+    networkAvailable,
+  });
+  logAgentsMdStatus({ agentsContent, config, convexDirName });
+  logClaudeMdStatus({ claudeContent, config, convexDirName });
+  logSkillsStatus({ config, canonicalAgentSkillsSha, networkAvailable });
+}