convex 1.34.0 → 1.35.0

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

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

@@ -0,0 +1,246 @@
+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 AiFilesState, attemptReadAiState } from "./state.js";
+import { type AiFilesProjectConfig } from "../config.js";
+import { isAiFilesDisabled } from "./index.js";
+import { readFileOrNull } from "./utils.js";
+
+function logGuidelinesStatus({
+  guidelinesFile,
+  guidelinesRelPath,
+  state,
+  canonicalGuidelinesHash,
+  networkAvailable,
+}: {
+  guidelinesFile: string | null;
+  guidelinesRelPath: string;
+  state: AiFilesState;
+  canonicalGuidelinesHash: string | null;
+  networkAvailable: boolean;
+}): void {
+  if (guidelinesFile === null || guidelinesFile === "") {
+    logMessage(
+      `  ${chalkStderr.yellow("⚠")} ${guidelinesRelPath}: not on disk — run ${chalkStderr.bold("npx convex ai-files install")} to reinstall`,
+    );
+    return;
+  }
+
+  const isLocallyModified =
+    state.guidelinesHash !== null &&
+    hashSha256(guidelinesFile) !== state.guidelinesHash;
+
+  if (isLocallyModified) {
+    logMessage(
+      `  ${chalkStderr.yellow("⚠")} ${guidelinesRelPath}: installed, modified locally (changes will be overwritten on next update)`,
+    );
+    return;
+  }
+
+  const isOutOfDate =
+    networkAvailable &&
+    canonicalGuidelinesHash !== null &&
+    state.guidelinesHash !== null &&
+    state.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,
+  state,
+  convexDirName,
+}: {
+  agentsContent: string | null;
+  state: AiFilesState;
+  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 (
+    state.agentsMdSectionHash !== null &&
+    state.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,
+  state,
+  convexDirName,
+}: {
+  claudeContent: string | null;
+  state: AiFilesState;
+  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 (state.claudeMdHash !== null && state.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({
+  state,
+  canonicalAgentSkillsSha,
+  networkAvailable,
+}: {
+  state: AiFilesState;
+  canonicalAgentSkillsSha: string | null;
+  networkAvailable: boolean;
+}): void {
+  if (state.installedSkillNames.length === 0) {
+    logMessage(
+      `  ${chalkStderr.yellow("⚠")} Agent skills: not installed — run ${chalkStderr.bold("npx convex ai-files install")} to install`,
+    );
+    return;
+  }
+
+  const skillsList = state.installedSkillNames.join(", ");
+  const isStale =
+    networkAvailable &&
+    canonicalAgentSkillsSha !== null &&
+    state.agentSkillsSha !== null &&
+    state.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,
+  aiFilesConfig,
+}: AiFilesPaths & {
+  aiFilesConfig?: AiFilesProjectConfig | undefined;
+}): Promise<void> {
+  const convexDirName = path.relative(projectDir, convexDir);
+  const guidelinesRelPath = path.relative(
+    projectDir,
+    guidelinesPathForConvexDir(convexDir),
+  );
+
+  if (isAiFilesDisabled(aiFilesConfig)) {
+    logMessage(`Convex AI files: ${chalkStderr.yellow("disabled")}`);
+    logMessage(
+      `  Run ${chalkStderr.bold("npx convex ai-files enable")} to re-enable.`,
+    );
+    return;
+  }
+
+  const stateResult = await attemptReadAiState(convexDir);
+
+  if (stateResult.kind !== "ok") {
+    logMessage(`Convex AI files: ${chalkStderr.yellow("not installed")}`);
+    logMessage(
+      `Run ${chalkStderr.bold("npx convex ai-files install")} to get started.`,
+    );
+    return;
+  }
+
+  const { state } = stateResult;
+
+  logMessage(`Convex AI files: ${chalkStderr.green("enabled")}`);
+
+  const [versionData, guidelinesFile, agentsContent, claudeContent] =
+    await Promise.all([
+      getVersion(),
+      readFileOrNull(guidelinesPathForConvexDir(convexDir)),
+      readFileOrNull(agentsMdPath(projectDir)),
+      readFileOrNull(claudeMdPath(projectDir)),
+    ]);
+
+  const networkAvailable = versionData.kind === "ok";
+  const canonicalGuidelinesHash = networkAvailable
+    ? versionData.data.guidelinesHash
+    : null;
+  const canonicalAgentSkillsSha = networkAvailable
+    ? versionData.data.agentSkillsSha
+    : null;
+
+  logGuidelinesStatus({
+    guidelinesFile,
+    guidelinesRelPath,
+    state,
+    canonicalGuidelinesHash,
+    networkAvailable,
+  });
+  logAgentsMdStatus({ agentsContent, state, convexDirName });
+  logClaudeMdStatus({ claudeContent, state, convexDirName });
+  logSkillsStatus({ state, canonicalAgentSkillsSha, networkAvailable });
+}

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

@@ -0,0 +1,50 @@
+import { describe, test, expect, beforeEach, afterEach } from "vitest";
+import fs from "fs";
+import os from "os";
+import path from "path";
+import { attemptReadFile } from "./utils.js";
+
+describe("attemptReadFile", () => {
+  let tmpDir: string;
+
+  beforeEach(() => {
+    tmpDir = fs.mkdtempSync(`${os.tmpdir()}${path.sep}`);
+  });
+
+  afterEach(() => {
+    fs.rmSync(tmpDir, { recursive: true, force: true });
+  });
+
+  test("returns content when the file has text", async () => {
+    const filePath = path.join(tmpDir, "content.txt");
+    fs.writeFileSync(filePath, "hello");
+
+    const result = await attemptReadFile(filePath);
+
+    expect(result).toEqual({ kind: "content", content: "hello" });
+  });
+
+  test("returns empty when the file exists but has no contents", async () => {
+    const filePath = path.join(tmpDir, "empty.txt");
+    fs.writeFileSync(filePath, "");
+
+    const result = await attemptReadFile(filePath);
+
+    expect(result).toEqual({ kind: "empty" });
+  });
+
+  test("returns not-found when the file does not exist", async () => {
+    const filePath = path.join(tmpDir, "missing.txt");
+
+    const result = await attemptReadFile(filePath);
+
+    expect(result).toEqual({ kind: "not-found" });
+  });
+
+  test("throws when fs.readFile fails for another reason", async () => {
+    const dirPath = path.join(tmpDir, "nested-dir");
+    fs.mkdirSync(dirPath);
+
+    await expect(attemptReadFile(dirPath)).rejects.toThrow();
+  });
+});

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

@@ -0,0 +1,191 @@
+// eslint-disable-next-line no-restricted-imports
+import { promises as fs } from "fs";
+import { chalkStderr } from "chalk";
+import { logMessage } from "../../../bundler/log.js";
+import { hashSha256 } from "../utils/hash.js";
+
+export function isInInteractiveTerminal(): boolean {
+  return process.stdin.isTTY === true;
+}
+
+export type ReadFileResult =
+  | { kind: "not-found" }
+  | { kind: "empty" }
+  | { kind: "content"; content: string };
+
+export async function attemptReadFile(
+  filePath: string,
+): Promise<ReadFileResult> {
+  try {
+    const content = await fs.readFile(filePath, "utf8");
+    if (content.length === 0) return { kind: "empty" };
+    return { kind: "content", content };
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === "ENOENT")
+      return { kind: "not-found" };
+
+    // eslint-disable-next-line no-restricted-syntax
+    throw error;
+  }
+}
+
+export async function readFileOrNull(filePath: string): Promise<string | null> {
+  const result = await attemptReadFile(filePath);
+  if (result.kind === "content") return result.content;
+  if (result.kind === "empty") return "";
+  if (result.kind === "not-found") return null;
+  return exhaustiveCheck(result);
+}
+
+/**
+ * Attempt to delete a file. Returns `true` if the file was deleted,
+ * `false` if it didn't exist or the deletion failed.
+ */
+export async function safelyDeleteFile(filePath: string): Promise<boolean> {
+  try {
+    await fs.unlink(filePath);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Generic managed-section helpers
+//
+// Several files (AGENTS.md, CLAUDE.md) contain a Convex-managed section
+// delimited by start/end markers. These helpers provide the common logic
+// for injecting, stripping, and detecting those sections.
+// ---------------------------------------------------------------------------
+
+export type ManagedSectionTarget = {
+  filePath: string;
+  startMarker: string;
+  endMarker: string;
+};
+
+export type InjectResult = {
+  sectionHash: string;
+  didWrite: boolean;
+};
+
+export const iife = <T>(fn: () => T): T => fn();
+
+/**
+ * Inject a managed section into a file. If the file already contains the
+ * markers, the section between them is replaced. Otherwise the section is
+ * appended (or the file is created). Only writes when content actually
+ * changes.
+ */
+export async function injectManagedSection(
+  opts: ManagedSectionTarget & { section: string },
+): Promise<InjectResult> {
+  const { filePath, startMarker, endMarker, section } = opts;
+
+  const existing = (await readFileOrNull(filePath)) ?? "";
+
+  const startIdx = existing.indexOf(startMarker);
+  const endIdx = existing.indexOf(endMarker);
+
+  const updated = iife(() => {
+    if (startIdx !== -1 && endIdx !== -1)
+      return (
+        existing.slice(0, startIdx) +
+        section +
+        existing.slice(endIdx + endMarker.length)
+      );
+    if (existing.length > 0)
+      return existing.trimEnd() + "\n\n" + section + "\n";
+
+    return section + "\n";
+  });
+
+  const didWrite = updated !== existing;
+  if (didWrite) await fs.writeFile(filePath, updated, "utf8");
+
+  return { sectionHash: hashSha256(section), didWrite };
+}
+
+export type StripResult = "none" | "section" | "file";
+
+/**
+ * Remove the managed section (between start/end markers) from a file.
+ * If the file is empty after removal, it is deleted.
+ *
+ * Returns `"none"` if the file doesn't exist or has no markers,
+ * `"section"` if the section was stripped, or `"file"` if the entire
+ * file was deleted.
+ */
+export async function attemptToStripManagedSection(
+  opts: ManagedSectionTarget,
+): Promise<StripResult> {
+  const { filePath, startMarker, endMarker } = opts;
+
+  const content = await readFileOrNull(filePath);
+  if (content === null) return "none";
+
+  const startIdx = content.indexOf(startMarker);
+  const endIdx = content.indexOf(endMarker);
+  if (startIdx === -1 || endIdx === -1) {
+    return "none";
+  }
+
+  const before = content.slice(0, startIdx).trimEnd();
+  const after = content.slice(endIdx + endMarker.length).trimStart();
+  const updated = [before, after].filter(Boolean).join("\n\n");
+
+  if (!updated.trim()) {
+    await safelyDeleteFile(filePath);
+    return "file";
+  }
+
+  await fs.writeFile(filePath, updated + "\n", "utf8");
+  return "section";
+}
+
+export function exhaustiveCheck(_param: never): never {
+  // eslint-disable-next-line no-restricted-syntax
+  throw new Error("Internal error: exhaustive check failed.");
+}
+
+export async function attemptToRemoveMarkdownSection({
+  projectDir,
+  strip,
+  fileName,
+}: {
+  projectDir: string;
+  strip: (dir: string) => Promise<StripResult>;
+  fileName: string;
+}): Promise<boolean> {
+  const result = await strip(projectDir);
+
+  if (result === "section") {
+    logMessage(
+      `${chalkStderr.green("✔")} Removed Convex section from ${fileName}.`,
+    );
+    return true;
+  }
+
+  if (result === "file") {
+    logMessage(`${chalkStderr.green("✔")} Deleted ${fileName}.`);
+    return true;
+  }
+
+  if (result === "none") return false;
+
+  return exhaustiveCheck(result);
+}
+
+/**
+ * Check whether a file contains a managed section (both markers present).
+ */
+export async function hasManagedSection(
+  opts: ManagedSectionTarget,
+): Promise<boolean> {
+  const content = await readFileOrNull(opts.filePath);
+  return (
+    content !== null &&
+    content.includes(opts.startMarker) &&
+    content.includes(opts.endMarker)
+  );
+}