diff --git a/AGENTS.md b/AGENTS.md index 6db760e607..da0c9b75a8 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -50,6 +50,12 @@ changed. `packages/client` excludes `*.spec.ts(x)` and `*.test.ts(x)` from typec ## Module boundaries and configuration +`/api` holds wiring, not behavior. When a change would add logic to a CJS file there — a branch, a +helper, a validation step, a service call — the logic belongs in `packages/api`, and the JS file +keeps requires, route registration and the call into the TS module (`MCPRequestContext.js` is the +shape, thirteen lines of re-export). "Minimum" means how much behavior `/api` gains, not how small +the diff is, and the rule applies to editing existing CJS, which is the common case. + 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 @@ -88,11 +94,15 @@ under “Auth cache invalidation”. ## Client state ownership -The client is migrating from Recoil to Jotai — convert the areas you touch, not the whole store. +The client is migrating from Recoil to Jotai. New state is always Jotai, even in a file that already +imports Recoil; many files import both, so mixed imports say nothing about which to use. For existing +state the unit of conversion is one atom plus every file that reads or writes it, because an atom +cannot be half converted — convert the areas you touch, not the whole store. Split by ownership: state a feature both writes and reads is feature-owned, so convert it to Jotai and keep it inside the feature; app-global preferences and shell state a feature merely consumes (`maximizeChatSpace`, `showScrollButton`, `enterToSend`, artifact visibility) must be passed in -through props or a small host-supplied context rather than reached for through `~/store`. Passing +through props or a small host-supplied context rather than reached for through `~/store`; when a +consumer sits outside the feature you are changing, leave that atom on Recoil and pass it in. Passing them in is what lets a feature move to its own workspace later without a rewrite, and it keeps the Jotai conversion scoped to the state a feature owns. See the detailed policy in `CLAUDE.md` under “Client State Ownership”. diff --git a/CLAUDE.md b/CLAUDE.md index b4ff8546d8..389554a231 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -21,7 +21,13 @@ The source code for `@librechat/agents` (major backend dependency, same team) li ## 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`). +- **`/api` holds wiring, not behavior.** When a change would add logic to a CJS file under `/api` — + a branch, a helper, a validation step, a new service call — that logic goes in `/packages/api`, + and the JS file keeps only what wires it up: requires, route registration, request plumbing, and + the call into the TS module. `api/server/services/MCPRequestContext.js` is the shape, at thirteen + lines of re-export. "Minimum" describes how much behavior `/api` gains, not how small the diff is: + lifting a function into `/packages/api` and calling it is the larger diff and the correct one. + Editing an existing CJS file is the common case and the rule applies there, not only to new files. - 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`. @@ -261,15 +267,24 @@ Multi-line imports count total character length across all lines. Consolidate va ### Client State Ownership -The client is migrating from Recoil to Jotai. Convert the areas you touch rather than -migrating wholesale, and split the work by who owns the state: +The client is migrating from Recoil to Jotai. **New state is always Jotai**, including inside a file +that already imports Recoil. For existing state, the unit of conversion is one atom together with +every file that reads or writes it: the two libraries hold different atom objects, so an atom cannot +be half converted, and many files already import both — mixed imports are not a signal that either +choice is fine here. Convert the areas you touch rather than migrating wholesale, and split the work +by who owns the state: - **Feature-owned state** — atoms a single feature both writes and reads. Convert these to - Jotai as you touch them, and keep them inside the feature. + Jotai as you touch them, with all of their consumers, and keep them inside the feature. + `client/src/store/jotai-utils.ts` carries the equivalents for persisted atoms + (`createStorageAtom`, `createStorageAtomWithEffect`, `createTabIsolatedAtom`), so a Recoil atom + with a localStorage effect has a direct port. - **App-global state** — preferences and shell state a feature merely consumes (`maximizeChatSpace`, `showScrollButton`, `enterToSend`, artifact visibility). A feature that could plausibly be extracted must not reach into `~/store` for these; accept them - through props or a small context the host supplies. + through props or a small context the host supplies. When a consumer sits outside the feature you + are changing, leave the atom on Recoil and pass it in — do not convert the shell to make one + feature tidy. Passing app-global state in — rather than reaching for it — is what lets a feature move to its own workspace later without a rewrite, and it keeps the Jotai conversion scoped to the