From 419613fdaf70197c2e3ac885f948c1d0e8d292c5 Mon Sep 17 00:00:00 2001 From: Danny Avila Date: Tue, 31 Mar 2026 21:50:38 -0400 Subject: [PATCH] =?UTF-8?q?=F0=9F=93=8B=20chore:=20Move=20project=20instru?= =?UTF-8?q?ctions=20from=20AGENTS.md=20to=20CLAUDE.md?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- AGENTS.md | 173 +----------------------------------------------------- CLAUDE.md | 173 +++++++++++++++++++++++++++++++++++++++++++++++++++++- 2 files changed, 173 insertions(+), 173 deletions(-) mode change 120000 => 100644 CLAUDE.md diff --git a/AGENTS.md b/AGENTS.md index 81362cfc57..ceb2b988dc 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,172 +1 @@ -# LibreChat - -## Project Overview - -LibreChat is a monorepo with the following key workspaces: - -| Workspace | Language | Side | Dependency | Purpose | -|---|---|---|---|---| -| `/api` | JS (legacy) | Backend | `packages/api`, `packages/data-schemas`, `packages/data-provider`, `@librechat/agents` | Express server — minimize changes here | -| `/packages/api` | **TypeScript** | Backend | `packages/data-schemas`, `packages/data-provider` | New backend code lives here (TS only, consumed by `/api`) | -| `/packages/data-schemas` | TypeScript | Backend | `packages/data-provider` | Database models/schemas, shareable across backend projects | -| `/packages/data-provider` | TypeScript | Shared | — | Shared API types, endpoints, data-service — used by both frontend and backend | -| `/client` | TypeScript/React | Frontend | `packages/data-provider`, `packages/client` | Frontend SPA | -| `/packages/client` | TypeScript | Frontend | `packages/data-provider` | Shared frontend utilities | - -The source code for `@librechat/agents` (major backend dependency, same team) is at `/home/danny/agentus`. - ---- - -## Workspace Boundaries - -- **All new backend code must be TypeScript** in `/packages/api`. -- Keep `/api` changes to the absolute minimum (thin JS wrappers calling into `/packages/api`). -- Database-specific shared logic goes in `/packages/data-schemas`. -- Frontend/backend shared API logic (endpoints, types, data-service) goes in `/packages/data-provider`. -- Build data-provider from project root: `npm run build:data-provider`. - ---- - -## Code Style - -### Naming and File Organization - -- **Single-word file names** whenever possible (e.g., `permissions.ts`, `capabilities.ts`, `service.ts`). -- When multiple words are needed, prefer grouping related modules under a **single-word directory** rather than using multi-word file names (e.g., `admin/capabilities.ts` not `adminCapabilities.ts`). -- The directory already provides context — `app/service.ts` not `app/appConfigService.ts`. - -### Structure and Clarity - -- **Never-nesting**: early returns, flat code, minimal indentation. Break complex operations into well-named helpers. -- **Functional first**: pure functions, immutable data, `map`/`filter`/`reduce` over imperative loops. Only reach for OOP when it clearly improves domain modeling or state encapsulation. -- **No dynamic imports** unless absolutely necessary. - -### DRY - -- Extract repeated logic into utility functions. -- Reusable hooks / higher-order components for UI patterns. -- Parameterized helpers instead of near-duplicate functions. -- Constants for repeated values; configuration objects over duplicated init code. -- Shared validators, centralized error handling, single source of truth for business rules. -- Shared typing system with interfaces/types extending common base definitions. -- Abstraction layers for external API interactions. - -### Iteration and Performance - -- **Minimize looping** — especially over shared data structures like message arrays, which are iterated frequently throughout the codebase. Every additional pass adds up at scale. -- Consolidate sequential O(n) operations into a single pass whenever possible; never loop over the same collection twice if the work can be combined. -- Choose data structures that reduce the need to iterate (e.g., `Map`/`Set` for lookups instead of `Array.find`/`Array.includes`). -- Avoid unnecessary object creation; consider space-time tradeoffs. -- Prevent memory leaks: careful with closures, dispose resources/event listeners, no circular references. - -### Type Safety - -- **Never use `any`**. Explicit types for all parameters, return values, and variables. -- **Limit `unknown`** — avoid `unknown`, `Record`, and `as unknown as T` assertions. A `Record` almost always signals a missing explicit type definition. -- **Don't duplicate types** — before defining a new type, check whether it already exists in the project (especially `packages/data-provider`). Reuse and extend existing types rather than creating redundant definitions. -- Use union types, generics, and interfaces appropriately. -- All TypeScript and ESLint warnings/errors must be addressed — do not leave unresolved diagnostics. - -### Comments and Documentation - -- Write self-documenting code; no inline comments narrating what code does. -- JSDoc only for complex/non-obvious logic or intellisense on public APIs. -- Single-line JSDoc for brief docs, multi-line for complex cases. -- Avoid standalone `//` comments unless absolutely necessary. - -### Import Order - -Imports are organized into three sections: - -1. **Package imports** — sorted shortest to longest line length (`react` always first). -2. **`import type` imports** — sorted longest to shortest (package types first, then local types; length resets between sub-groups). -3. **Local/project imports** — sorted longest to shortest. - -Multi-line imports count total character length across all lines. Consolidate value imports from the same module. Always use standalone `import type { ... }` — never inline `type` inside value imports. - -### JS/TS Loop Preferences - -- **Limit looping as much as possible.** Prefer single-pass transformations and avoid re-iterating the same data. -- `for (let i = 0; ...)` for performance-critical or index-dependent operations. -- `for...of` for simple array iteration. -- `for...in` only for object property enumeration. - ---- - -## Frontend Rules (`client/src/**/*`) - -### Localization - -- All user-facing text must use `useLocalize()`. -- Only update English keys in `client/src/locales/en/translation.json` (other languages are automated externally). -- Semantic key prefixes: `com_ui_`, `com_assistants_`, etc. - -### Components - -- TypeScript for all React components with proper type imports. -- Semantic HTML with ARIA labels (`role`, `aria-label`) for accessibility. -- Group related components in feature directories (e.g., `SidePanel/Memories/`). -- Use index files for clean exports. - -### Data Management - -- Feature hooks: `client/src/data-provider/[Feature]/queries.ts` → `[Feature]/index.ts` → `client/src/data-provider/index.ts`. -- React Query (`@tanstack/react-query`) for all API interactions; proper query invalidation on mutations. -- QueryKeys and MutationKeys in `packages/data-provider/src/keys.ts`. - -### Data-Provider Integration - -- Endpoints: `packages/data-provider/src/api-endpoints.ts` -- Data service: `packages/data-provider/src/data-service.ts` -- Types: `packages/data-provider/src/types/queries.ts` -- Use `encodeURIComponent` for dynamic URL parameters. - -### Performance - -- Prioritize memory and speed efficiency at scale. -- Cursor pagination for large datasets. -- Proper dependency arrays to avoid unnecessary re-renders. -- Leverage React Query caching and background refetching. - ---- - -## Development Commands - -| Command | Purpose | -|---|---| -| `npm run smart-reinstall` | Install deps (if lockfile changed) + build via Turborepo | -| `npm run reinstall` | Clean install — wipe `node_modules` and reinstall from scratch | -| `npm run backend` | Start the backend server | -| `npm run backend:dev` | Start backend with file watching (development) | -| `npm run build` | Build all compiled code via Turborepo (parallel, cached) | -| `npm run frontend` | Build all compiled code sequentially (legacy fallback) | -| `npm run frontend:dev` | Start frontend dev server with HMR (port 3090, requires backend running) | -| `npm run build:data-provider` | Rebuild `packages/data-provider` after changes | - -- Node.js: v20.19.0+ or ^22.12.0 or >= 23.0.0 -- Database: MongoDB -- Backend runs on `http://localhost:3080/`; frontend dev server on `http://localhost:3090/` - ---- - -## Testing - -- Framework: **Jest**, run per-workspace. -- Run tests from their workspace directory: `cd api && npx jest `, `cd packages/api && npx jest `, etc. -- Frontend tests: `__tests__` directories alongside components; use `test/layout-test-utils` for rendering. -- Cover loading, success, and error states for UI/data flows. - -### Philosophy - -- **Real logic over mocks.** Exercise actual code paths with real dependencies. Mocking is a last resort. -- **Spies over mocks.** Assert that real functions are called with expected arguments and frequency without replacing underlying logic. -- **MongoDB**: use `mongodb-memory-server` for a real in-memory MongoDB instance. Test actual queries and schema validation, not mocked DB calls. -- **MCP**: use real `@modelcontextprotocol/sdk` exports for servers, transports, and tool definitions. Mirror real scenarios, don't stub SDK internals. -- Only mock what you cannot control: external HTTP APIs, rate-limited services, non-deterministic system calls. -- Heavy mocking is a code smell, not a testing strategy. - ---- - -## Formatting - -Fix all formatting lint errors (trailing spaces, tabs, newlines, indentation) using auto-fix when available. All TypeScript/ESLint warnings and errors **must** be resolved. +CLAUDE.md diff --git a/CLAUDE.md b/CLAUDE.md deleted file mode 120000 index 47dc3e3d86..0000000000 --- a/CLAUDE.md +++ /dev/null @@ -1 +0,0 @@ -AGENTS.md \ No newline at end of file diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 0000000000..81362cfc57 --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,172 @@ +# LibreChat + +## Project Overview + +LibreChat is a monorepo with the following key workspaces: + +| Workspace | Language | Side | Dependency | Purpose | +|---|---|---|---|---| +| `/api` | JS (legacy) | Backend | `packages/api`, `packages/data-schemas`, `packages/data-provider`, `@librechat/agents` | Express server — minimize changes here | +| `/packages/api` | **TypeScript** | Backend | `packages/data-schemas`, `packages/data-provider` | New backend code lives here (TS only, consumed by `/api`) | +| `/packages/data-schemas` | TypeScript | Backend | `packages/data-provider` | Database models/schemas, shareable across backend projects | +| `/packages/data-provider` | TypeScript | Shared | — | Shared API types, endpoints, data-service — used by both frontend and backend | +| `/client` | TypeScript/React | Frontend | `packages/data-provider`, `packages/client` | Frontend SPA | +| `/packages/client` | TypeScript | Frontend | `packages/data-provider` | Shared frontend utilities | + +The source code for `@librechat/agents` (major backend dependency, same team) is at `/home/danny/agentus`. + +--- + +## Workspace Boundaries + +- **All new backend code must be TypeScript** in `/packages/api`. +- Keep `/api` changes to the absolute minimum (thin JS wrappers calling into `/packages/api`). +- Database-specific shared logic goes in `/packages/data-schemas`. +- Frontend/backend shared API logic (endpoints, types, data-service) goes in `/packages/data-provider`. +- Build data-provider from project root: `npm run build:data-provider`. + +--- + +## Code Style + +### Naming and File Organization + +- **Single-word file names** whenever possible (e.g., `permissions.ts`, `capabilities.ts`, `service.ts`). +- When multiple words are needed, prefer grouping related modules under a **single-word directory** rather than using multi-word file names (e.g., `admin/capabilities.ts` not `adminCapabilities.ts`). +- The directory already provides context — `app/service.ts` not `app/appConfigService.ts`. + +### Structure and Clarity + +- **Never-nesting**: early returns, flat code, minimal indentation. Break complex operations into well-named helpers. +- **Functional first**: pure functions, immutable data, `map`/`filter`/`reduce` over imperative loops. Only reach for OOP when it clearly improves domain modeling or state encapsulation. +- **No dynamic imports** unless absolutely necessary. + +### DRY + +- Extract repeated logic into utility functions. +- Reusable hooks / higher-order components for UI patterns. +- Parameterized helpers instead of near-duplicate functions. +- Constants for repeated values; configuration objects over duplicated init code. +- Shared validators, centralized error handling, single source of truth for business rules. +- Shared typing system with interfaces/types extending common base definitions. +- Abstraction layers for external API interactions. + +### Iteration and Performance + +- **Minimize looping** — especially over shared data structures like message arrays, which are iterated frequently throughout the codebase. Every additional pass adds up at scale. +- Consolidate sequential O(n) operations into a single pass whenever possible; never loop over the same collection twice if the work can be combined. +- Choose data structures that reduce the need to iterate (e.g., `Map`/`Set` for lookups instead of `Array.find`/`Array.includes`). +- Avoid unnecessary object creation; consider space-time tradeoffs. +- Prevent memory leaks: careful with closures, dispose resources/event listeners, no circular references. + +### Type Safety + +- **Never use `any`**. Explicit types for all parameters, return values, and variables. +- **Limit `unknown`** — avoid `unknown`, `Record`, and `as unknown as T` assertions. A `Record` almost always signals a missing explicit type definition. +- **Don't duplicate types** — before defining a new type, check whether it already exists in the project (especially `packages/data-provider`). Reuse and extend existing types rather than creating redundant definitions. +- Use union types, generics, and interfaces appropriately. +- All TypeScript and ESLint warnings/errors must be addressed — do not leave unresolved diagnostics. + +### Comments and Documentation + +- Write self-documenting code; no inline comments narrating what code does. +- JSDoc only for complex/non-obvious logic or intellisense on public APIs. +- Single-line JSDoc for brief docs, multi-line for complex cases. +- Avoid standalone `//` comments unless absolutely necessary. + +### Import Order + +Imports are organized into three sections: + +1. **Package imports** — sorted shortest to longest line length (`react` always first). +2. **`import type` imports** — sorted longest to shortest (package types first, then local types; length resets between sub-groups). +3. **Local/project imports** — sorted longest to shortest. + +Multi-line imports count total character length across all lines. Consolidate value imports from the same module. Always use standalone `import type { ... }` — never inline `type` inside value imports. + +### JS/TS Loop Preferences + +- **Limit looping as much as possible.** Prefer single-pass transformations and avoid re-iterating the same data. +- `for (let i = 0; ...)` for performance-critical or index-dependent operations. +- `for...of` for simple array iteration. +- `for...in` only for object property enumeration. + +--- + +## Frontend Rules (`client/src/**/*`) + +### Localization + +- All user-facing text must use `useLocalize()`. +- Only update English keys in `client/src/locales/en/translation.json` (other languages are automated externally). +- Semantic key prefixes: `com_ui_`, `com_assistants_`, etc. + +### Components + +- TypeScript for all React components with proper type imports. +- Semantic HTML with ARIA labels (`role`, `aria-label`) for accessibility. +- Group related components in feature directories (e.g., `SidePanel/Memories/`). +- Use index files for clean exports. + +### Data Management + +- Feature hooks: `client/src/data-provider/[Feature]/queries.ts` → `[Feature]/index.ts` → `client/src/data-provider/index.ts`. +- React Query (`@tanstack/react-query`) for all API interactions; proper query invalidation on mutations. +- QueryKeys and MutationKeys in `packages/data-provider/src/keys.ts`. + +### Data-Provider Integration + +- Endpoints: `packages/data-provider/src/api-endpoints.ts` +- Data service: `packages/data-provider/src/data-service.ts` +- Types: `packages/data-provider/src/types/queries.ts` +- Use `encodeURIComponent` for dynamic URL parameters. + +### Performance + +- Prioritize memory and speed efficiency at scale. +- Cursor pagination for large datasets. +- Proper dependency arrays to avoid unnecessary re-renders. +- Leverage React Query caching and background refetching. + +--- + +## Development Commands + +| Command | Purpose | +|---|---| +| `npm run smart-reinstall` | Install deps (if lockfile changed) + build via Turborepo | +| `npm run reinstall` | Clean install — wipe `node_modules` and reinstall from scratch | +| `npm run backend` | Start the backend server | +| `npm run backend:dev` | Start backend with file watching (development) | +| `npm run build` | Build all compiled code via Turborepo (parallel, cached) | +| `npm run frontend` | Build all compiled code sequentially (legacy fallback) | +| `npm run frontend:dev` | Start frontend dev server with HMR (port 3090, requires backend running) | +| `npm run build:data-provider` | Rebuild `packages/data-provider` after changes | + +- Node.js: v20.19.0+ or ^22.12.0 or >= 23.0.0 +- Database: MongoDB +- Backend runs on `http://localhost:3080/`; frontend dev server on `http://localhost:3090/` + +--- + +## Testing + +- Framework: **Jest**, run per-workspace. +- Run tests from their workspace directory: `cd api && npx jest `, `cd packages/api && npx jest `, etc. +- Frontend tests: `__tests__` directories alongside components; use `test/layout-test-utils` for rendering. +- Cover loading, success, and error states for UI/data flows. + +### Philosophy + +- **Real logic over mocks.** Exercise actual code paths with real dependencies. Mocking is a last resort. +- **Spies over mocks.** Assert that real functions are called with expected arguments and frequency without replacing underlying logic. +- **MongoDB**: use `mongodb-memory-server` for a real in-memory MongoDB instance. Test actual queries and schema validation, not mocked DB calls. +- **MCP**: use real `@modelcontextprotocol/sdk` exports for servers, transports, and tool definitions. Mirror real scenarios, don't stub SDK internals. +- Only mock what you cannot control: external HTTP APIs, rate-limited services, non-deterministic system calls. +- Heavy mocking is a code smell, not a testing strategy. + +--- + +## Formatting + +Fix all formatting lint errors (trailing spaces, tabs, newlines, indentation) using auto-fix when available. All TypeScript/ESLint warnings and errors **must** be resolved.