diff --git a/AGENTS.md b/AGENTS.md index 3b972e233e..6db760e607 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -13,8 +13,9 @@ default branch, so close linked issues by hand. Worktrees share one stash stack, Write the description for a reader who has not followed the branch: what breaks, what triggers it, how it behaves after the change, then one or two views of the mechanism — a focused diff, a call tree, a shallow file tree, or a Mermaid sequence. Keep only what the change carries, and describe -the code as it stands rather than narrating earlier commits or review rounds. The formats and -examples live in `.github/pull_request_template.md`. +the code as it stands rather than narrating earlier commits or review rounds. Naming the merged +pull request that caused the bug is not the same thing; that is history the reader needs. The +formats and examples live in `.github/pull_request_template.md`. ## Review and completion @@ -47,6 +48,28 @@ changed. `packages/client` excludes `*.spec.ts(x)` and `*.test.ts(x)` from typec `npm run sort-imports` with no arguments rewrites every source root — pass the paths you touched. See `CLAUDE.md` under "Typechecking" and "Formatting". +## Module boundaries and configuration + +Database contracts belong to `packages/data-schemas`. Keep Mongoose types (`FilterQuery`, +`Types.ObjectId`, `Document`) out of exported signatures in `packages/api`, `packages/data-provider` +and `client`, because they make the storage engine part of that module's public API. Take and return +plain typed objects and express the query behind a data-schemas method. The boundary already leaks +across `packages/api`, so stop widening it rather than rewriting what exists; the client carries none +of it and must stay that way. + +New levers ship configurable: a limit, timeout, toggle or capability introduced in code earns a field +on `configSchema` (`packages/data-provider/src/config.ts`) so it can be set in `librechat.yaml`, with +a default that reproduces today's behavior. Hard-coded constants and env-only switches need a reason. +Modules take their dependencies rather than reaching for them: code in `packages/api` receives its +config, database methods and clients from the caller, the way `createModels(mongoose)` receives the +app's connection, instead of importing app singletons or reading global state. Integrations (provider +SDKs, storage backends, vector stores, OAuth servers) arrive through an interface the caller +supplies, so a second implementation is a new argument instead of a new branch. The static singletons +under `packages/api/src/mcp` are the shape to stop extending, not a pattern to copy. This is the +backend half of client state ownership: pass it in, do not reach for it. + +See `CLAUDE.md` under "Workspace Boundaries". + ## Frontend theming and styling For frontend work, compose existing `@librechat/client` primitives and variants before adding diff --git a/CLAUDE.md b/CLAUDE.md index 1667036b2e..b4ff8546d8 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -25,6 +25,29 @@ The source code for `@librechat/agents` (major backend dependency, same team) li - 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`. +- **Database contracts stay inside `/packages/data-schemas`.** A Mongoose type in an exported + signature — `FilterQuery`, `Types.ObjectId`, `Document`, `HydratedDocument` — makes the storage + engine part of that module's public API, and every consumer then depends on Mongo instead of on + the data it needs. Take and return plain typed objects, and express the query behind a + data-schemas method. The boundary already leaks across dozens of files in `/packages/api`, so the + rule is to stop widening it rather than to rewrite what exists; `/client` carries none of it and + must stay that way. +- **New levers ship configurable.** A limit, timeout, toggle or capability introduced in code earns + a field on `configSchema` (`packages/data-provider/src/config.ts`) so an operator can set it in + `librechat.yaml`, with a default that reproduces today's behavior. Hard-coded constants and + env-only switches need a reason. The schema is also what keeps one definition of the value instead + of a constant, a fallback and a doc line that drift apart. +- **A backend module takes its dependencies, it does not reach for them.** Code in `/packages/api` + should receive its config, database methods and clients from the caller the way + `createModels(mongoose)` receives the app's connection, rather than importing app singletons or + reading global state. A module the caller constructs can be tested without a running app and moved + to another workspace without a rewrite; one that calls `getInstance()` can do neither. This is the + backend half of "Client State Ownership" — pass it in, do not reach for it. The static singletons + under `packages/api/src/mcp` are the shape to stop extending, not a pattern to copy. +- **Integrations arrive through an interface the caller supplies.** A provider SDK, storage backend, + vector store or OAuth server is injected, so a second implementation is a new argument instead of + a new branch in shared code, and a test can exercise the real logic against a substitute at the + boundary rather than mocking the module that holds it. --- @@ -98,7 +121,9 @@ findings that keep arriving mean the subsystem needs a sweep, not another patch. ARIA intact, and compose shared primitives and semantic theme roles before adding local styling (see "Frontend Rules"). Custom styling that proves unavoidable still supports light/dark and reduced motion. -- Preserve existing defaults, configuration compatibility, stored data, and mixed-version behavior. +- Preserve existing defaults, configuration compatibility, stored data, and mixed-version behavior, + and expose any new lever through `configSchema` rather than a constant (see "Workspace + Boundaries"). - Make the fix the smallest one consistent with the patterns already in the file, and test the behavior that was missed rather than the line a reviewer pointed at. - **Report what you actually ran**: the pushed head, the local checks from "Testing" and