mirror of
https://github.com/danny-avila/LibreChat.git
synced 2026-11-20 15:02:02 +00:00
⛴️ chore: Bring Canary Up to Date With Dev
This commit is contained in:
commit
ffa54e0259
31 changed files with 1085 additions and 537 deletions
133
AGENTS.md
133
AGENTS.md
|
|
@ -1,4 +1,9 @@
|
|||
See CLAUDE.md.
|
||||
# LibreChat contributor and agent guidance
|
||||
|
||||
`AGENTS.md` is the repository's contributor guidance. Backend code lives in `packages/api`
|
||||
(TypeScript) and `packages/data-schemas` (database methods); `api` is legacy Express wiring.
|
||||
Shared API types and services live in `packages/data-provider`, and the React app lives in
|
||||
`client` with shared primitives in `packages/client`.
|
||||
|
||||
## Branching and pull requests
|
||||
|
||||
|
|
@ -18,8 +23,9 @@ explicitly based on `canary` stays there; the main-to-dev retarget workflow does
|
|||
Still link related issues in the PR (for example, `Related to #N`) so the work remains
|
||||
traceable. `Fixes #N` does not close an issue on a `dev` or `canary` merge — GitHub honors closing
|
||||
keywords only on the default branch. Close resolved issues by hand after merging. Worktrees share
|
||||
one stash stack, so never use a bare `git stash pop`. See the detailed policy in `CLAUDE.md` under
|
||||
"Branching and Pull Requests".
|
||||
one stash stack, so never use a bare `git stash pop`. Prefer a WIP commit; if a stash is necessary,
|
||||
apply the specific tagged entry. The `target: main` label and release-bound upstream branches are
|
||||
exempt from the main-to-dev retarget workflow; do not use either to backport ordinary work.
|
||||
|
||||
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
|
||||
|
|
@ -34,17 +40,18 @@ Read the inline review threads themselves — a summary comment or notification
|
|||
Audit each one against the current code, fix what is valid, and reject what is obsolete in a reply
|
||||
that says why. After each round: focused tests, `npx tsc --noEmit` in every workspace you changed,
|
||||
push, then request the next review naming the pull request's exact remote head — a clean review of
|
||||
an earlier head says nothing about what you just pushed, and CI runs on its own clock. After two
|
||||
actionable rounds, stop patching thread by thread and read the subsystem by invariant instead.
|
||||
Which reviewer and what phrase triggers it will change; that the review must cover the exact pushed
|
||||
head will not.
|
||||
an earlier head says nothing about what you just pushed, and CI runs on its own clock. Reply on
|
||||
each resolved thread with the resolving commit and evidence. After two actionable rounds, stop
|
||||
patching thread by thread and read the subsystem by invariant instead: identity, authorization,
|
||||
persistence, retry, cancellation, cleanup and mixed-version behavior where relevant. Which reviewer
|
||||
and what phrase triggers it will change; that the review must cover the exact pushed head will not.
|
||||
|
||||
A clean review is one completion signal, not the definition of done. Ship the observable experience
|
||||
— loading, empty, success, failure, cancellation, retry, restored session — with strings localized,
|
||||
accessibility intact, defaults and stored data preserved, and no backend capability left without a
|
||||
frontend entry point. Report the pushed head, what you ran locally, CI state, the review result at
|
||||
that head, and any finding you rejected with the reasoning. See `CLAUDE.md` under "Review and
|
||||
Completion".
|
||||
frontend entry point. Keep fixes small and test the missed behavior. Report the pushed head, what you
|
||||
ran locally, CI state, the review result at that head, any finding you rejected with the reasoning,
|
||||
and checks you could not run.
|
||||
|
||||
## Verification
|
||||
|
||||
|
|
@ -56,11 +63,17 @@ See [budgets, reproduction and failure diagnosis](e2e/lighthouse/README.md).
|
|||
A green build is not a typecheck: `packages/api`, `packages/client` and `packages/data-schemas` build
|
||||
with `tsdown`, which emits without checking types. Run `npx tsc --noEmit` in the workspace you
|
||||
changed. `packages/client` excludes `*.spec.ts(x)` and `*.test.ts(x)` from typechecking entirely.
|
||||
`npm run sort-imports` with no arguments rewrites every source root — pass the paths you touched. See
|
||||
`CLAUDE.md` under "Typechecking" and "Formatting".
|
||||
`npm run sort-imports` with no arguments rewrites every source root — pass the paths you touched.
|
||||
Run `npm run static-checks -- --against origin/dev` to reproduce the PR's static checks; use
|
||||
`npm run static-checks:full` for the slower gates. Fix all formatting, lint, and TypeScript
|
||||
warnings/errors in the code you change.
|
||||
|
||||
## Module boundaries and configuration
|
||||
|
||||
All new backend behavior belongs in TypeScript under `packages/api`; database-specific shared logic
|
||||
belongs in `packages/data-schemas`, and frontend/backend shared API logic belongs in
|
||||
`packages/data-provider`. Build data-provider from the project root with `npm run build:data-provider`.
|
||||
|
||||
`/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
|
||||
|
|
@ -85,7 +98,46 @@ supplies, so a second implementation is a new argument instead of a new branch.
|
|||
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".
|
||||
## Service failures and user-facing errors
|
||||
|
||||
This section applies to backend services (`packages/api`) and database methods/repositories
|
||||
(`packages/data-schemas`), not to React components. For new or substantially changed code in
|
||||
those layers, choose failure behavior at the contract boundary instead of treating every
|
||||
unsuccessful outcome as an exception:
|
||||
|
||||
- Return a plain value on success. Use `null` only for a documented absence (for example, a
|
||||
successful lookup with no record), never to hide a query failure.
|
||||
- For an expected failure the caller can handle without aborting the operation, prefer a typed
|
||||
discriminated result such as `{ ok: true; value: T } | { ok: false; error: { code: string;
|
||||
message?: string } }`. Keep an existing domain-specific result shape when changing it would
|
||||
break callers; do not introduce interchangeable `ok`, `valid`, and bare `{ message }` contracts
|
||||
in the same service. Codes should be stable, machine-readable identifiers when the caller
|
||||
needs to distinguish failures. Internal validation helpers may use the existing local pattern.
|
||||
- Throw for unexpected operational failures (database, provider, network) and violated invariants.
|
||||
Use a typed/coded error when a boundary must recognize a particular failure. Catch where you can
|
||||
recover or translate it; otherwise let it reach the owning request or job boundary. Do not catch
|
||||
an exception and return a truthy record, `null`, or `{ message }` in its place: callers can then
|
||||
mistake an outage for data or send it as an HTTP 200. Keep separate migrations for existing
|
||||
contracts, with their callers and tests, rather than changing wire shapes incidentally.
|
||||
- At the HTTP, stream, or job boundary, map failures to the existing status and response contract.
|
||||
Only expose intentionally approved codes and helpful user-safe information. Error disclosure is
|
||||
a security boundary: never forward raw exceptions, stacks, query text, credentials, request
|
||||
bodies, headers, provider payloads, or arbitrary `error.message` to a client or persisted
|
||||
user-visible status. Sanitize diagnostics and log only what the path can safely retain. For
|
||||
errors that may echo submitted content, prefer `getSafeErrorMetadata` over error text;
|
||||
`packages/api/src/utils/errors.ts` documents when redacted error text is appropriate.
|
||||
- Localization is a UI responsibility, not a database-method return shape. When a failure reaches
|
||||
a user-facing surface, expose a safe, stable code the UI can map to localized, actionable copy
|
||||
and a fallback. See `client/src/components/Messages/Content/Error/registry.ts` and
|
||||
`client/src/components/Chat/Trace/Viewer.tsx`. Keep any intentionally disclosed provider detail
|
||||
behind its existing protection policy rather than treating arbitrary upstream text as safe.
|
||||
|
||||
Examples of local contracts, not a mandate to copy their shapes: `packages/api/src/admin/auditLog.ts`
|
||||
uses a parsing result, `packages/api/src/agents/openai/service.ts` validates before mapping to an
|
||||
OpenAI-compatible response, and `packages/api/src/skills/sync/errors.ts` names a sync failure by
|
||||
stable code. `packages/data-schemas/src/methods/prompt.ts` currently returns `{ message }` on query
|
||||
failure; do not extend that pattern. Test absence versus failure, the boundary's non-success response,
|
||||
and that sensitive diagnostics cannot reach a user-visible surface.
|
||||
|
||||
## Frontend theming and styling
|
||||
|
||||
|
|
@ -93,22 +145,16 @@ For frontend work, compose existing `@librechat/client` primitives and variants
|
|||
feature-local styles. Use semantic theme/Tailwind roles for color and shared appearance; do not
|
||||
introduce raw palette utilities, hard-coded colors, or arbitrary theme CSS. If the system cannot
|
||||
express a reusable design need, deepen the shared primitive or versioned theme-token registry
|
||||
instead of copying classes into a feature. Keep genuine layout and behavior local, and document
|
||||
why any new custom CSS cannot be expressed by the shared system.
|
||||
|
||||
`npm run lint` enforces this: `@shadcn/lint` reads each primitive's `cva` variants and reports a
|
||||
`className` that overrides what the primitive owns, naming the variant, size or file to use
|
||||
instead. Do not reach for `eslint-disable`, and do not widen a file's recorded count in
|
||||
`eslint-suppressions.json` to land a restyle — that file holds the backlog the rules inherited, so
|
||||
raising an entry is a reviewable claim that the override is right. After fixing violations, run
|
||||
`npm run lint:design:prune`; after moving a file that carries suppressions, run
|
||||
`npm run lint:design:suppress`. See the detailed policy in `CLAUDE.md` under “Theming and styling.”
|
||||
instead of copying classes into a feature. Theme definitions select semantic colors and appearance,
|
||||
not selectors, app behavior, or alternate layouts. Keep genuine layout and behavior local, and
|
||||
explain why any new custom CSS cannot use shared primitives. Support light/dark and reduced motion;
|
||||
preserve defaults and test a deliberately different reference theme for reusable new variants.
|
||||
|
||||
## Backend auth cache
|
||||
|
||||
When adding or changing code that mutates user documents, invalidate the auth user document cache
|
||||
for affected users, including bulk role and user mutations. See the detailed policy in `CLAUDE.md`
|
||||
under “Auth cache invalidation”.
|
||||
for affected users, including bulk role and user mutations. Otherwise burst-cached JWT requests can
|
||||
serve a stale `req.user` until the cache expires.
|
||||
|
||||
## Client state ownership
|
||||
|
||||
|
|
@ -122,5 +168,38 @@ and keep it inside the feature; app-global preferences and shell state a feature
|
|||
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”.
|
||||
Jotai conversion scoped to the state a feature owns. For persisted atoms, use the helpers in
|
||||
`client/src/store/jotai-utils.ts`.
|
||||
|
||||
## Code style and performance
|
||||
|
||||
Use short, single-word file names when possible; group related modules in a single-word directory.
|
||||
Prefer flat early returns, pure functions, and explicit types. Avoid `any`, broad `unknown`/casts,
|
||||
duplicated types, and dynamic imports. Extract genuinely repeated logic instead of copying it;
|
||||
write comments only for non-obvious behavior or public API contracts.
|
||||
|
||||
Imports have three sections: package values (shortest line first, with `react` first), `import type`
|
||||
(longest line first, package types before local types), and local/project values (longest line first).
|
||||
Use standalone `import type { ... }`, not inline `type` within a value import. Run the scoped
|
||||
import sorter on files you change.
|
||||
|
||||
Avoid extra passes over shared message arrays and unnecessary allocations. For startup and
|
||||
request paths, reuse already-loaded user/config data, avoid serial database reads, and start
|
||||
independent reads in parallel. Do not weaken authorization or tenant checks or write a response
|
||||
before those checks succeed.
|
||||
|
||||
## Frontend rules
|
||||
|
||||
Use `useLocalize()` for all visible copy and update only English keys in
|
||||
`client/src/locales/en/translation.json`. Use semantic HTML, keyboard behavior, and ARIA labels.
|
||||
Use React Query for API interactions and invalidate related queries after mutations; define query
|
||||
and mutation keys in `packages/data-provider/src/keys.ts`. Put shared endpoint definitions, types,
|
||||
and data services in `packages/data-provider`, and encode dynamic URL parameters. Cover loading,
|
||||
success, and failure states in focused component tests.
|
||||
|
||||
## Testing
|
||||
|
||||
Run focused Jest tests from the owning workspace, not the entire monorepo. Prefer real logic and
|
||||
spies over mocked internals; use `mongodb-memory-server` for database queries and the real MCP SDK
|
||||
for MCP behavior. Mock only external HTTP APIs or uncontrollable services. For frontend tests use
|
||||
the component's colocated `__tests__` and `test/layout-test-utils` where applicable.
|
||||
|
|
|
|||
469
CLAUDE.md
469
CLAUDE.md
|
|
@ -1,469 +0,0 @@
|
|||
# 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) lives at
|
||||
<https://github.com/LibreChat-AI/agents>.
|
||||
|
||||
---
|
||||
|
||||
## Workspace Boundaries
|
||||
|
||||
- **All new backend code must be TypeScript** in `/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`.
|
||||
- **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.
|
||||
|
||||
---
|
||||
|
||||
## Branching and Pull Requests
|
||||
|
||||
- **Normally branch off `dev` and target `dev`.** This is the default for work ready to follow the
|
||||
regular release path. A maintainer-directed canary exception is described below.
|
||||
- **`main` is the released branch.** It is kept as a fast-forward of `dev` and synced as-is, so it
|
||||
is always an ancestor of `dev` — equal to it right after a sync, behind it otherwise. It never
|
||||
carries a commit that `dev` does not have.
|
||||
- **Never open a backport pull request to `main`.** Anything merged to `dev` reaches `main` at the
|
||||
next sync; a second pull request for the same change is redundant.
|
||||
- **The repository's default branch is `main`**, so `gh pr create` and the GitHub UI target it
|
||||
unless told otherwise — pass `--base dev` for normal work or `--base canary` for an explicitly
|
||||
maintainer-directed canary PR.
|
||||
- Pull requests opened against `main` are retargeted to `dev` automatically by
|
||||
`.github/workflows/pr-retarget-dev.yml`. The `target: main` label exempts one, as do release-bound
|
||||
upstream branches (`dev`, `release/*`, `hotfix/*`). PRs deliberately based on `canary` are not
|
||||
retargeted, including manual sweeps; the script skips them explicitly. Backport branches are
|
||||
deliberately not exempt — a backport merged straight to `main` breaks the fast-forward invariant.
|
||||
- **Canary is an explicit, maintainer-selected integration target, not a path that automatically
|
||||
flows to `dev` or `main`.** Experimental changes and PRs that are ready to merge following review
|
||||
but must not enter the next `main` sync can go to `canary`. The maintainer may decide this when
|
||||
assigning the work or while reviewing an older/stale PR. For a new canary PR, branch from the
|
||||
current `origin/canary` and set `--base canary`. Never infer that a canary-targeted PR should move
|
||||
to `dev` just because `dev` is the default; do not copy canary features into `dev` without an
|
||||
explicit maintainer decision. If a stale PR is reassigned to canary, check the PR's base, diff and
|
||||
exact reviewed head against current canary before changing its base or proposing a new canary
|
||||
branch/PR; if a rebase changes the head, verify and review that new head before merging.
|
||||
- **Link related issues in the PR even when they will not auto-close.** Reference each relevant
|
||||
issue in the description (for example, `Related to #N`) so reviewers can find the context and
|
||||
track the work. GitHub honors `Fixes #N` and other closing keywords only when a pull request
|
||||
merges into the default branch (`main`). Merging to `dev` or `canary` does not close an issue,
|
||||
and the later fast-forward of `main` is not a merge event either — close resolved issues by hand
|
||||
after merging.
|
||||
- **Git worktrees share one stash stack.** `refs/stash` lives in the common `.git` directory, so a
|
||||
bare `git stash pop` in one worktree can take work stashed in another. Prefer a throwaway WIP
|
||||
commit; if you must stash, `git stash push -m <tag>` and `apply` that specific entry.
|
||||
- **Write the description for a reader who has not followed the branch.** Say what breaks, what
|
||||
triggers it, and how it behaves after the change, then show the mechanism with whichever one or
|
||||
two views make it reviewable — a focused diff, a call tree, a shallow file tree, or a Mermaid
|
||||
sequence — keeping only the calls, files and state the change actually carries. Describe the code
|
||||
as it stands: do not narrate what earlier commits tried or what a review round changed. Naming the
|
||||
merged pull request that caused the bug is different — that is history the reader needs.
|
||||
`.github/pull_request_template.md` carries the formats and examples.
|
||||
|
||||
---
|
||||
|
||||
## Review and Completion
|
||||
|
||||
### AI review cycles
|
||||
|
||||
The reviewer, its trigger phrase and its cadence all change; this subsection is the fluid one, so
|
||||
rewrite it when they do. What survives a change of tool: a review counts only for the exact commit
|
||||
it ran on, its findings are judged against the code rather than accepted or dismissed wholesale, and
|
||||
findings that keep arriving mean the subsystem needs a sweep, not another patch.
|
||||
|
||||
- **Inline review threads are the source of truth.** A summary comment, a check name or a
|
||||
notification list omits findings — read the threads on the pull request itself.
|
||||
- Audit every finding against the current code. Fix the valid ones; reject the obsolete or wrong
|
||||
ones in a reply that says why.
|
||||
- After each round of fixes, run the focused tests and `npx tsc --noEmit` for every workspace you
|
||||
changed, push, read the pull request's remote head (`gh pr view <n> --json headRefOid`), and
|
||||
request the next review naming that exact SHA. **A clean review of an earlier head says nothing
|
||||
about what you just pushed.** Do not wait for CI before asking — review and CI run on their own
|
||||
clocks.
|
||||
- Reply on each thread you resolved with the commit that resolved it and the coverage that proves
|
||||
it.
|
||||
- **After two actionable rounds** — or sooner, when each fix uncovers an adjacent defect — stop
|
||||
answering threads one at a time and read the subsystem by invariant: identity, ownership,
|
||||
authorization, persistence, retry, replay, abort, cleanup, expiry, rollout. Follow producers,
|
||||
consumers, adapters, alternate write paths, and the final consumer of every limit; check
|
||||
mixed-version behavior in both directions; read the whole base-to-head diff with the callers and
|
||||
tests around it; then add transition or failure-injection coverage at the deepest boundary that
|
||||
owns the behavior.
|
||||
- The cycle ends when the exact pushed head draws no major findings, or only repeats ones already
|
||||
resolved. A clean review is one completion signal, not the definition of done.
|
||||
|
||||
### Definition of done
|
||||
|
||||
- **Ship the observable experience, not the reported path.** Where they apply, cover loading, empty,
|
||||
success, failure, cancellation, retry and restored-session behavior.
|
||||
- **A backend capability with no frontend entry point is unfinished**, and so is a control with no
|
||||
validation, persistence, error handling or authorization behind it.
|
||||
- Localize every visible string through `useLocalize()`, keep semantic HTML, keyboard behavior and
|
||||
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,
|
||||
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
|
||||
"Typechecking", CI state, the review result at that head, and any finding you rejected with the
|
||||
reasoning. Name the checks you could not run instead of implying coverage.
|
||||
|
||||
---
|
||||
|
||||
## 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.
|
||||
|
||||
### Backend Database Performance
|
||||
|
||||
- On request startup and first page load paths, watch for serial database reads.
|
||||
Multiple round trips to MongoDB can add significant latency when the database
|
||||
is far from the app server.
|
||||
- Prefer passing already-loaded request/user/config data through helper
|
||||
functions instead of re-reading the same user, role, tenant, or principal data.
|
||||
- When two reads are independent, start them in parallel and gate the response
|
||||
on the authorization or validation result before returning data.
|
||||
- Keep authorization, permission, and tenant checks semantically identical when
|
||||
parallelizing reads. Speculative reads must remain scoped to the authenticated
|
||||
user or tenant and must not write to the response before validation succeeds.
|
||||
|
||||
### Type Safety
|
||||
|
||||
- **Never use `any`**. Explicit types for all parameters, return values, and variables.
|
||||
- **Limit `unknown`** — avoid `unknown`, `Record<string, unknown>`, and `as unknown as T` assertions. A `Record<string, unknown>` 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.
|
||||
|
||||
### Theming and styling
|
||||
|
||||
- **Compose before styling.** Search `@librechat/client` for an existing primitive, semantic
|
||||
variant, or composition before adding feature-local classes or CSS.
|
||||
- **Use semantic roles.** Colors and shared appearance values must come from the semantic
|
||||
Tailwind/theme roles. Do not add raw palette utilities, hard-coded hex/RGB/HSL colors, or
|
||||
light/dark-specific values in feature components.
|
||||
- **Deepen the system when the need is reusable.** Add a focused variant to a shared primitive or
|
||||
extend the canonical, versioned theme-token registry when multiple screens should share the
|
||||
same design decision. Do not create shallow local wrappers that merely relocate class strings.
|
||||
- **Themes are data, not arbitrary CSS.** Theme definitions may select semantic colors and shared
|
||||
appearance roles. They must not contain selectors, arbitrary CSS, application behavior, or
|
||||
alternate feature layouts. Preserve existing environment and stored-theme compatibility when
|
||||
changing the theme engine.
|
||||
- **Keep layout and behavior local.** Feature structure, responsive layout, state-driven
|
||||
transitions, and specialized visualization may remain feature-owned. Expose a theme role only
|
||||
when it represents a stable, reusable appearance decision; do not turn every measurement into a
|
||||
global token.
|
||||
- **Treat custom CSS as an exception.** Use it only when shared primitives and semantic utilities
|
||||
cannot express the requirement. Keep it narrowly scoped, consume theme variables where
|
||||
applicable, support light/dark and reduced motion, and add a brief code or PR explanation of why
|
||||
the exception is necessary.
|
||||
- **Preserve defaults and prove variability.** New theme-aware variants must reproduce the current
|
||||
default appearance unless a redesign is explicitly requested. Test semantic-token use and, when
|
||||
extending theme capabilities, include a deliberately different reference theme to prove that
|
||||
components adapt without feature-specific overrides.
|
||||
- **The design rules are enforced by `npm run lint`.** `@shadcn/lint` is registered in
|
||||
`eslint.config.mjs` for `client/src/**` and `packages/client/src/**`. It resolves
|
||||
`@librechat/client` (and the `~/components/ui` re-exports) as the design system, reads each
|
||||
primitive's `cva` variants, and reports a `className` that overrides what the primitive owns —
|
||||
naming the variants, sizes and defining file to use instead. Six rules run at `error`:
|
||||
`no-restyle` (layout and `icon-*` sizing allowed), `no-raw-colors`, `no-arbitrary-values`
|
||||
(layout allowed), `no-inline-styles` (measured geometry allowed: width, height, inset,
|
||||
transform, z-index), `require-static-classes` and `no-unknown-classes`. The last one asks the
|
||||
installed Tailwind whether a class generates any CSS, which needs v4 and the color tokens in
|
||||
CSS (`packages/client/src/theme/tokens.css`) for the rule to resolve a theme; under 3.4 its
|
||||
fallback reported every preset utility (`duration-theme-fast`, `rounded-theme-control`) as a
|
||||
typo. What it cannot see is a class defined in a stylesheet Tailwind does not read, or one a
|
||||
dependency puts in the DOM, so those live in its `allow` list in `eslint.config.mjs`, add a
|
||||
name there when a plain selector or a third party owns it, and fix the class when nothing
|
||||
defines it. `no-raw-colors` additionally reports a `bg-`/`text-`/`border-` name whose token is
|
||||
not declared in the theme, which is the same failure wearing a color's clothes.
|
||||
- **Contracts say what a caller owns; suppressions say what is owed.** A `no-restyle` contract in
|
||||
`eslint.config.mjs` opens a category for one component because the caller legitimately owns it:
|
||||
`Label`, `Description`, `DialogTitle` and `DialogDescription` take the caller's typography, and
|
||||
`Skeleton` takes the silhouette and footprint of the content it stands in for. Color stays with
|
||||
the theme in every case. Widen a contract when a whole category belongs to callers; do not widen
|
||||
one to clear a single call site.
|
||||
- **The existing backlog is recorded, not exempted.** `eslint-suppressions.json` holds the
|
||||
violations the tree carried when the rules landed, as a per-file, per-rule count.
|
||||
Adding a violation to a file reports every violation of that rule in it, so raising a file's
|
||||
count is a visible diff in that file, review it like any other change, and expect a raise to
|
||||
be justified by what the diff does. Strengthening a rule is the one case where counts rise in
|
||||
files nobody edited: when a rule starts seeing a class it could not classify before, the
|
||||
violations it reports are the tree's existing styling, and recording them is the same backlog
|
||||
arriving later. Say which change did that and keep the two apart in review.
|
||||
`npm run lint:design:prune` drops entries whose violations are gone (do this after fixing
|
||||
some); `npm run lint:design:suppress` re-records the design rules and then prunes, which is
|
||||
what a file move needs, since suppressions are keyed by path, the re-record adds the new
|
||||
path and only the prune removes the old one. It re-baselines everything under `client/src`
|
||||
and `packages/client/src`, so for a single move prefer a scoped re-record of just that file:
|
||||
the same six `--suppress-rule` flags `lint:design:suppress` passes (`shadcn/no-restyle`,
|
||||
`no-raw-colors`, `no-arbitrary-values`, `no-inline-styles`, `require-static-classes`,
|
||||
`no-unknown-classes`) with
|
||||
`<new/path.tsx>` in place of the directories, since a moved file usually carries entries for
|
||||
more than one rule, followed by `npm run lint:design:prune`;
|
||||
`npm run lint:design:suppress -- <file>` does not scope, because npm appends the argument to
|
||||
the script's own directory arguments. Neither command changes which rules run; both only
|
||||
rewrite the recorded counts. The re-record's own exit status is deliberately ignored: it lints
|
||||
the roots under every rule, those roots carry a pre-existing error backlog, and the baseline is
|
||||
written before ESLint reports it — so `lint:design:suppress` runs `lint:design:record` inside
|
||||
`|| node -e ""` (`true` is not a command under `cmd.exe`, where npm runs scripts on Windows)
|
||||
and lets the prune be the step that can fail. Expect the same when running a scoped re-record
|
||||
by hand, and build the primitives first: `shadcn/no-restyle` reads each variant out of
|
||||
`packages/client/dist`, so a missing or stale bundle records counts that describe a library
|
||||
nobody is compiling against. `lint`, `lint:fix`, `lint:design:record` and `lint:design:prune`
|
||||
each run `npm run build:client-package` before they lint, which is why `lint:design:suppress`
|
||||
no longer builds on its own account; a bare `eslint --suppress-rule ...` does not, so run that
|
||||
build ahead of it.
|
||||
- **The ratchet is on the count, and on what the count stands for.** ESLint compares a file's
|
||||
current violation count for a rule against the recorded one and suppresses when it is not higher,
|
||||
so replacing one suppressed violation with a different violation of the same rule in the same
|
||||
file keeps the count equal and ESLint reports nothing. The backlog is a budget per file, but it is
|
||||
not a budget you may respend: for every file a diff touches, the runner lints that file's version
|
||||
at the merge base and reports a design-rule message the head has that the base did not, beyond
|
||||
whatever that entry's count grew by. So a swap arrives as a failure naming the new violation, a
|
||||
violation that merely moved does not, adding one with the count raised to cover it is the
|
||||
documented `npm run lint:design:suppress` path and stays green — the raised count is the line a
|
||||
reviewer reads — and a file the change adds brings no allowance with it, while a renamed one
|
||||
keeps what its violations came with. Two kinds of swap still pass: one whose diagnostic message
|
||||
is the same as the message it replaced, because some rules name the property and not the value
|
||||
(`Inline style sets display.` is one message for `none` and for `flex`), and one caused by the
|
||||
diff's own change to a primitive or to the config, because both versions are linted under the
|
||||
head's design inputs. `npm run static-checks` and the Static Checks lane also
|
||||
validate the baseline itself (shape, positive counts, rules the plugin defines, paths that still
|
||||
exist, paths a design-rule lint actually reports on, and counts that match the file's violations).
|
||||
- **The design rules read JSX, not CSS.** They are AST rules over `className`, `cva` and
|
||||
`style` in `{ts,tsx,js,jsx}`, so a `.css` file under either root — `client/src/style.css`,
|
||||
`packages/client/src/components/Field.css` — is outside every one of them, and so is the
|
||||
changed-file runner's selection. A raw hex in a stylesheet is caught by review, not by
|
||||
`npm run lint`. The theme tokens are the exception: they live in CSS and carry their own
|
||||
check.
|
||||
|
||||
### 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`.
|
||||
|
||||
### Client State Ownership
|
||||
|
||||
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, 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. 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
|
||||
state a feature actually owns instead of dragging the global migration forward early.
|
||||
|
||||
### 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.
|
||||
|
||||
---
|
||||
|
||||
## Backend Rules (`api/**`, `packages/api/**`)
|
||||
|
||||
### Auth cache invalidation
|
||||
|
||||
When adding or changing code that mutates user documents, invalidate the auth user document cache
|
||||
for the affected users. This covers single-user updates as well as bulk role and user mutations.
|
||||
Without it, OpenID JWT request burst caching can serve a stale `req.user` until its TTL expires.
|
||||
|
||||
---
|
||||
|
||||
## 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 |
|
||||
| `npm run lint:design:prune` | Drop `eslint-suppressions.json` entries whose violations are fixed |
|
||||
| `npm run lint:design:suppress` | Re-record the design-rule backlog, then prune (needed after a file move) |
|
||||
|
||||
- Node.js: v24.16.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 <pattern>`, `cd packages/api && npx jest <pattern>`, etc.
|
||||
- Frontend tests: `__tests__` directories alongside components; use `test/layout-test-utils` for rendering.
|
||||
- Cover loading, success, and error states for UI/data flows.
|
||||
|
||||
### Typechecking
|
||||
|
||||
- **A green build is not a typecheck.** `packages/api`, `packages/client` and `packages/data-schemas`
|
||||
build with `tsdown` alone, which emits without checking types. Only `packages/data-provider` runs
|
||||
`tsc` as part of its build.
|
||||
- Run `npx tsc --noEmit` in the workspace you changed before calling it done. `client` also exposes
|
||||
it as `npm run typecheck`.
|
||||
- `packages/client/tsconfig.json` excludes `*.spec.ts(x)` and `*.test.ts(x)`, so test files there are
|
||||
never typechecked — a type error in a spec surfaces only when the test runs.
|
||||
- `npm run static-checks` runs the Static Checks CI job locally against your staged files;
|
||||
`npm run static-checks -- --against origin/dev` reproduces what CI sees for a pull request, and
|
||||
`npm run static-checks:full` adds the slow gates (TypeScript, config migration tests, unused i18n
|
||||
keys, unused npm packages).
|
||||
|
||||
### 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.
|
||||
|
||||
`npm run sort-imports` with no arguments rewrites every file under `api/`, `client/src` and the four
|
||||
`packages/*/src` roots — far beyond what you touched. Always pass explicit paths:
|
||||
`npm run sort-imports -- path/to/file.ts`.
|
||||
|
|
@ -85,7 +85,6 @@ const { getAppConfig } = require('./services/Config');
|
|||
const staticCache = require('./utils/staticCache');
|
||||
const optionalJwtAuth = require('./middleware/optionalJwtAuth');
|
||||
const noIndex = require('./middleware/noIndex');
|
||||
const routes = require('./routes');
|
||||
const agentEventMethods = require('~/models');
|
||||
|
||||
/** Route admin file-config MIME patterns through a linear-time engine (ReDoS-safe) on upload. */
|
||||
|
|
@ -517,6 +516,10 @@ if (cluster.isMaster) {
|
|||
await updateInterfacePerms({ appConfig, getRoleByName, updateAccessPermissions });
|
||||
});
|
||||
|
||||
/* Route modules build their rate limiters as they load, so they load only after the
|
||||
* startup checks have applied `rateLimits` from librechat.yaml. */
|
||||
const routes = require('./routes');
|
||||
|
||||
/** Load index.html for SPA serving */
|
||||
const indexPath = path.join(appConfig.paths.dist, 'index.html');
|
||||
let indexHTML = fs.readFileSync(indexPath, 'utf8');
|
||||
|
|
|
|||
|
|
@ -87,7 +87,6 @@ const createSpaFallback = require('./utils/fallback');
|
|||
const { getAppConfig } = require('./services/Config');
|
||||
const staticCache = require('./utils/staticCache');
|
||||
const noIndex = require('./middleware/noIndex');
|
||||
const routes = require('./routes');
|
||||
const agentEventMethods = require('~/models');
|
||||
|
||||
/** Route admin file-config MIME patterns through a linear-time engine (ReDoS-safe) on upload. */
|
||||
|
|
@ -273,6 +272,10 @@ const startServer = async () => {
|
|||
await updateInterfacePermissions({ appConfig, getRoleByName, updateAccessPermissions });
|
||||
});
|
||||
|
||||
/* Route modules build their rate limiters as they load, so they load only after the
|
||||
* startup checks have applied `rateLimits` from librechat.yaml. */
|
||||
const routes = require('./routes');
|
||||
|
||||
const indexPath = path.join(appConfig.paths.dist, 'index.html');
|
||||
let indexHTML = fs.readFileSync(indexPath, 'utf8');
|
||||
|
||||
|
|
|
|||
|
|
@ -28,7 +28,12 @@
|
|||
}
|
||||
</style>
|
||||
<script>
|
||||
const theme = localStorage.getItem('color-theme');
|
||||
let theme = null;
|
||||
try {
|
||||
theme = localStorage.getItem('color-theme');
|
||||
} catch (e) {
|
||||
/* Web Storage denied by browser policy: the shell falls back to the system theme. */
|
||||
}
|
||||
const loadingContainerStyle = document.createElement('style');
|
||||
let backgroundColor;
|
||||
|
||||
|
|
|
|||
|
|
@ -100,6 +100,7 @@ const TwoFactorScreen: React.FC = React.memo(() => {
|
|||
value={value != null ? value : ''}
|
||||
onChange={onChange}
|
||||
pattern={REGEXP_ONLY_DIGITS}
|
||||
aria-label={localize('com_ui_2fa_verification_required')}
|
||||
>
|
||||
<InputOTPGroup>
|
||||
<InputOTPSlot index={0} />
|
||||
|
|
@ -131,6 +132,7 @@ const TwoFactorScreen: React.FC = React.memo(() => {
|
|||
value={value != null ? value : ''}
|
||||
onChange={onChange}
|
||||
pattern={REGEXP_ONLY_DIGITS_AND_CHARS}
|
||||
aria-label={localize('com_ui_backup_code_verification_required')}
|
||||
>
|
||||
<InputOTPGroup>
|
||||
<InputOTPSlot index={0} />
|
||||
|
|
@ -154,7 +156,6 @@ const TwoFactorScreen: React.FC = React.memo(() => {
|
|||
<Button
|
||||
type="submit"
|
||||
variant="submit"
|
||||
aria-label={localize('com_auth_continue')}
|
||||
data-testid="login-button"
|
||||
disabled={isLoading}
|
||||
className="w-full rounded-2xl px-4 py-3 text-sm font-medium disabled:opacity-80"
|
||||
|
|
|
|||
|
|
@ -13,6 +13,17 @@ import type { TChatProject, TMessage, TConversation } from 'librechat-data-provi
|
|||
import type { SetterOrUpdater } from 'recoil';
|
||||
import type { ExtendedFile, FileSetter, ConvoGenerator, TAskFunction } from '~/common';
|
||||
import type { QueuedMessageContext } from '~/hooks/Chat/useSteering';
|
||||
import {
|
||||
cn,
|
||||
getModelSpec,
|
||||
hasIncompleteFiles,
|
||||
removeFocusRings,
|
||||
getComposerDraftId,
|
||||
getPendingDraftId,
|
||||
clearAllDrafts,
|
||||
getFilesDraftCached,
|
||||
isPastedTextFileMarked,
|
||||
} from '~/utils';
|
||||
import {
|
||||
useTextarea,
|
||||
useAutoSave,
|
||||
|
|
@ -32,15 +43,6 @@ import {
|
|||
useComposerRestoreHost,
|
||||
BadgeRowProvider,
|
||||
} from '~/Providers';
|
||||
import {
|
||||
cn,
|
||||
getModelSpec,
|
||||
hasIncompleteFiles,
|
||||
removeFocusRings,
|
||||
getComposerDraftId,
|
||||
getFilesDraftCached,
|
||||
isPastedTextFileMarked,
|
||||
} from '~/utils';
|
||||
import {
|
||||
PendingToolApprovalButton,
|
||||
PendingToolApprovalPanel,
|
||||
|
|
@ -705,12 +707,18 @@ const ChatForm = memo(function ChatForm({
|
|||
{
|
||||
answerMode,
|
||||
steering,
|
||||
submitMessage,
|
||||
submitMessage: (message) => {
|
||||
const result = submitMessage(message);
|
||||
if (result !== false) {
|
||||
clearAllDrafts(getPendingDraftId(index));
|
||||
}
|
||||
return result;
|
||||
},
|
||||
reset: () => methods.reset(),
|
||||
},
|
||||
data,
|
||||
),
|
||||
[answerMode, steering, submitMessage, methods],
|
||||
[answerMode, steering, submitMessage, methods, index],
|
||||
);
|
||||
|
||||
return (
|
||||
|
|
@ -753,7 +761,7 @@ const ChatForm = memo(function ChatForm({
|
|||
data-testid="composer-context-rail"
|
||||
className={cn(
|
||||
'mx-4 -mb-3 flex min-w-0 flex-wrap items-center gap-1 rounded-t-2xl',
|
||||
'border-border-light bg-surface-secondary border px-2 pt-1 pb-4',
|
||||
'border-border-light bg-surface-secondary border px-2 pb-4 pt-1',
|
||||
isRTL && 'flex-row-reverse',
|
||||
)}
|
||||
>
|
||||
|
|
@ -807,7 +815,7 @@ const ChatForm = memo(function ChatForm({
|
|||
squared off at the bottom (`rounded-t-theme-surface-lg`) and no disclaimer
|
||||
follows it — so the action row is the last thing in it, with no
|
||||
band of padding under the buttons. */
|
||||
'rounded-t-theme-surface-lg sm:rounded-theme-surface-lg relative flex w-full grow flex-col overflow-hidden',
|
||||
'relative flex w-full grow flex-col overflow-hidden rounded-t-theme-surface-lg sm:rounded-theme-surface-lg',
|
||||
composerSurfaceClasses(),
|
||||
isTextAreaFocused ? composerSurfaceShadow.focused : composerSurfaceShadow.blurred,
|
||||
/* Temporary-chat accent is a ChatForm-only override, not part of
|
||||
|
|
@ -910,14 +918,14 @@ const ChatForm = memo(function ChatForm({
|
|||
active={dictation.active}
|
||||
className={cn(
|
||||
'pointer-events-none absolute inset-y-2',
|
||||
isMoreThanThreeRows ? 'right-2 left-5' : 'inset-x-5',
|
||||
isMoreThanThreeRows ? 'left-5 right-2' : 'inset-x-5',
|
||||
)}
|
||||
/>
|
||||
)}
|
||||
{/* Sits over the fade scrim in the corner of the input
|
||||
rather than in its own column beside it, so a long draft
|
||||
does not push an orphaned control off to the side. */}
|
||||
<div className="absolute right-2 bottom-1 z-10">
|
||||
<div className="absolute bottom-1 right-2 z-10">
|
||||
<CollapseChat
|
||||
isCollapsed={isCollapsed}
|
||||
isScrollable={isMoreThanThreeRows}
|
||||
|
|
|
|||
|
|
@ -10,13 +10,15 @@ import { QueryClient, QueryClientProvider } from '@tanstack/react-query';
|
|||
import { QueryKeys, FileSources, EModelEndpoint } from 'librechat-data-provider';
|
||||
import { render, screen, within, waitFor, fireEvent } from '@testing-library/react';
|
||||
import type { TFile, TFileUpload, TConversation } from 'librechat-data-provider';
|
||||
import type { ChatFormValues } from '~/common';
|
||||
import type { ChatFormValues, TAskFunction } from '~/common';
|
||||
import { getDraft, getPendingDraftId, setDraft } from '~/utils';
|
||||
import ChatForm, { toRestoredComposerFile } from '../ChatForm';
|
||||
import { ChatContext, ChatFormProvider } from '~/Providers';
|
||||
import { AuthContextProvider } from '~/hooks/AuthContext';
|
||||
import store from '~/store';
|
||||
|
||||
const mockUpload = jest.fn();
|
||||
const mockAsk = jest.fn();
|
||||
|
||||
jest.mock('librechat-data-provider', () => {
|
||||
const actual = jest.requireActual('librechat-data-provider');
|
||||
|
|
@ -68,7 +70,7 @@ let commits = 0;
|
|||
|
||||
function Harness() {
|
||||
const [files, setFiles] = useRecoilState(store.filesByIndex(0));
|
||||
const [isSubmitting] = useRecoilState(store.isSubmittingFamily(0));
|
||||
const [isSubmitting, setIsSubmitting] = useRecoilState(store.isSubmittingFamily(0));
|
||||
/* ChatView owns this read and passes it in; the harness stands in for it. */
|
||||
const [speechSettingsInitialized] = useRecoilState(store.speechSettingsInitialized);
|
||||
const [, setFilesLoading] = useState(false);
|
||||
|
|
@ -91,7 +93,13 @@ function Harness() {
|
|||
stopGenerating: () => undefined,
|
||||
getMessages: () => undefined,
|
||||
setMessages: () => undefined,
|
||||
ask: () => undefined,
|
||||
ask: (...args: Parameters<TAskFunction>) => {
|
||||
const result = mockAsk(...args);
|
||||
if (result !== false) {
|
||||
setIsSubmitting(true);
|
||||
}
|
||||
return result;
|
||||
},
|
||||
regenerate: () => undefined,
|
||||
setSiblingIdx: () => undefined,
|
||||
showPopover: false,
|
||||
|
|
@ -105,7 +113,7 @@ function Harness() {
|
|||
handleRegenerate: () => undefined,
|
||||
handleContinue: () => undefined,
|
||||
}) as unknown as React.ContextType<typeof ChatContext>,
|
||||
[files, setFiles, isSubmitting],
|
||||
[files, setFiles, isSubmitting, setIsSubmitting],
|
||||
);
|
||||
|
||||
return (
|
||||
|
|
@ -180,6 +188,7 @@ describe('ChatForm attachments', () => {
|
|||
global.URL.revokeObjectURL = jest.fn();
|
||||
(global as unknown as { Image: unknown }).Image = StubImage;
|
||||
mockUpload.mockReset();
|
||||
mockAsk.mockReset();
|
||||
/** The server echoes the id the client sent back as `temp_file_id`. */
|
||||
mockUpload.mockImplementation((body: FormData) =>
|
||||
Promise.resolve({ ...uploadResponse, temp_file_id: body.get('file_id') as string }),
|
||||
|
|
@ -258,6 +267,42 @@ describe('ChatForm attachments', () => {
|
|||
expect(textarea).toHaveFocus();
|
||||
}, 20000);
|
||||
|
||||
test('does not restore an older fragment of the sent message while the run starts', async () => {
|
||||
renderComposer();
|
||||
const textarea = await screen.findByTestId('text-input');
|
||||
const message = 'i would like to learn how to use it for a demo or is it too early days';
|
||||
await userEvent.type(textarea, message);
|
||||
setDraft({ id: getPendingDraftId(), value: 'i would like to learn how to use it for a dem' });
|
||||
|
||||
await userEvent.click(sendButton());
|
||||
|
||||
await waitFor(() =>
|
||||
expect(mockAsk).toHaveBeenCalledWith(
|
||||
expect.objectContaining({ text: message }),
|
||||
expect.anything(),
|
||||
),
|
||||
);
|
||||
expect(textarea).toHaveValue('');
|
||||
expect(getDraft(getPendingDraftId())).toBe('');
|
||||
|
||||
await userEvent.type(textarea, 'a different follow-up');
|
||||
await waitFor(() => expect(getDraft(getPendingDraftId())).toBe('a different follow-up'));
|
||||
}, 20000);
|
||||
|
||||
test('keeps the draft intact when the normal send is refused', async () => {
|
||||
mockAsk.mockReturnValue(false);
|
||||
renderComposer();
|
||||
const textarea = await screen.findByTestId('text-input');
|
||||
await userEvent.type(textarea, 'not sent');
|
||||
setDraft({ id: getPendingDraftId(), value: 'earlier follow-up' });
|
||||
|
||||
await userEvent.click(sendButton());
|
||||
|
||||
await waitFor(() => expect(mockAsk).toHaveBeenCalled());
|
||||
expect(textarea).toHaveValue('not sent');
|
||||
expect(getDraft(getPendingDraftId())).toBe('earlier follow-up');
|
||||
}, 20000);
|
||||
|
||||
test('still returns focus to the textarea after a plain control click', async () => {
|
||||
renderComposer();
|
||||
const textarea = await screen.findByTestId('text-input');
|
||||
|
|
|
|||
|
|
@ -29,12 +29,17 @@ jest.mock('~/components/Chat/Messages/Content/ProgressText', () => ({
|
|||
phase,
|
||||
inProgressText,
|
||||
finishedText,
|
||||
icon,
|
||||
}: {
|
||||
phase: 'running' | 'completed' | 'cancelled' | 'failed';
|
||||
inProgressText: string;
|
||||
finishedText: string;
|
||||
icon: React.ReactNode;
|
||||
}) => (
|
||||
<div data-testid="progress-text">{phase === 'running' ? inProgressText : finishedText}</div>
|
||||
<div data-testid="progress-text">
|
||||
{icon}
|
||||
{phase === 'running' ? inProgressText : finishedText}
|
||||
</div>
|
||||
),
|
||||
}));
|
||||
|
||||
|
|
@ -132,6 +137,7 @@ describe('FileAuthoringCall', () => {
|
|||
);
|
||||
|
||||
expect(screen.getByTestId('progress-text')).toHaveTextContent('Updated SKILL.md');
|
||||
expect(document.querySelector('.lucide-file-pen-line')).not.toBeNull();
|
||||
});
|
||||
|
||||
it('prefers the output diff over the args preview after edit_file completes', () => {
|
||||
|
|
|
|||
|
|
@ -7,6 +7,8 @@ import {
|
|||
ArrowRightLeft,
|
||||
FileSearch,
|
||||
FileText,
|
||||
FilePlus2,
|
||||
FilePenLine,
|
||||
MessageCircleQuestion,
|
||||
ScrollText,
|
||||
Brain,
|
||||
|
|
@ -32,6 +34,8 @@ export type ToolIconType =
|
|||
| 'file_search'
|
||||
| 'skill'
|
||||
| 'read_file'
|
||||
| 'create_file'
|
||||
| 'edit_file'
|
||||
| 'bash_tool'
|
||||
| 'background_tasks'
|
||||
| 'ask_user_question'
|
||||
|
|
@ -49,6 +53,8 @@ const ICON_MAP: Record<ToolIconType, React.ComponentType<{ className?: string }>
|
|||
file_search: FileSearch,
|
||||
skill: ScrollText,
|
||||
read_file: FileText,
|
||||
create_file: FilePlus2,
|
||||
edit_file: FilePenLine,
|
||||
bash_tool: BashIcon,
|
||||
background_tasks: ListChecks,
|
||||
ask_user_question: MessageCircleQuestion,
|
||||
|
|
@ -88,6 +94,9 @@ export function getToolIconType(name: string): ToolIconType {
|
|||
if (name === 'read_file') {
|
||||
return 'read_file';
|
||||
}
|
||||
if (name === 'create_file' || name === 'edit_file') {
|
||||
return name;
|
||||
}
|
||||
if (name === 'bash_tool' || name === Constants.BASH_PROGRAMMATIC_TOOL_CALLING) {
|
||||
return 'bash_tool';
|
||||
}
|
||||
|
|
|
|||
|
|
@ -178,6 +178,45 @@ describe('ActivityPhaseGroup', () => {
|
|||
expect(screen.getByText(LABEL).parentElement).toHaveClass('flex-1', 'text-left');
|
||||
});
|
||||
|
||||
test.each([
|
||||
['create_file', '', 'lucide-file-plus-2'],
|
||||
['edit_file', '', 'lucide-file-pen-line'],
|
||||
['create_file', 'Created skills/demo/SKILL.md', 'lucide-file-plus-2'],
|
||||
['create_file', 'Updated AGENTS.md with safe diagnostic guidance', 'lucide-file-pen-line'],
|
||||
['edit_file', 'Edited AGENTS.md', 'lucide-file-pen-line'],
|
||||
])(
|
||||
'shows the file-row glyph on settled and live phase headers for %s: %s',
|
||||
(name, output, glyph) => {
|
||||
const part = {
|
||||
type: ContentTypes.TOOL_CALL,
|
||||
[ContentTypes.TOOL_CALL]: {
|
||||
id: 'file-1',
|
||||
name,
|
||||
args: '{"path":"AGENTS.md"}',
|
||||
output,
|
||||
type: 'tool_call',
|
||||
},
|
||||
} as unknown as TMessageContentParts;
|
||||
const { rerender } = render(
|
||||
<ActivityPhaseGroup labelPart={labelPart} hasContent spanParts={[part]}>
|
||||
<div data-testid="phase-content" />
|
||||
</ActivityPhaseGroup>,
|
||||
);
|
||||
|
||||
expect(screen.getByRole('button', { name: LABEL }).querySelector(`.${glyph}`)).not.toBeNull();
|
||||
expect(
|
||||
screen.getByRole('button', { name: LABEL }).querySelector('.lucide-wrench'),
|
||||
).toBeNull();
|
||||
|
||||
rerender(
|
||||
<ActivityPhaseGroup labelPart={labelPart} hasContent liveParts={[part]}>
|
||||
<div data-testid="phase-content" />
|
||||
</ActivityPhaseGroup>,
|
||||
);
|
||||
expect(screen.getByRole('button').querySelector(`.${glyph}`)).not.toBeNull();
|
||||
},
|
||||
);
|
||||
|
||||
test('keeps the focus ring inside the clipped header', () => {
|
||||
render(
|
||||
<ActivityPhaseGroup labelPart={labelPart} hasContent>
|
||||
|
|
|
|||
|
|
@ -48,6 +48,15 @@ describe('shared header glyphs', () => {
|
|||
},
|
||||
);
|
||||
|
||||
it.each([
|
||||
['create_file', 'lucide-file-plus-2'],
|
||||
['edit_file', 'lucide-file-pen-line'],
|
||||
])('renders %s with the same glyph as its file row', (name, glyph) => {
|
||||
const { container } = render(<StackedToolIcons toolNames={[name]} />);
|
||||
expect(container.querySelector(`.${glyph}`)).not.toBeNull();
|
||||
expect(container.querySelector('.lucide-wrench')).toBeNull();
|
||||
});
|
||||
|
||||
it('retains a bounded stack and overflow count', () => {
|
||||
const { container } = render(
|
||||
<StackedToolIcons
|
||||
|
|
|
|||
|
|
@ -886,6 +886,26 @@ describe('ToolCallGroup image hoisting', () => {
|
|||
expect(screen.queryByText(/web_search|file_search|retrieval/)).not.toBeInTheDocument();
|
||||
});
|
||||
|
||||
it('uses the edit glyph for a create_file overwrite without changing its tool label', () => {
|
||||
renderGroup({
|
||||
...baseProps,
|
||||
parts: [
|
||||
{
|
||||
part: makePart(
|
||||
'file-1',
|
||||
'Updated AGENTS.md with safe diagnostic guidance',
|
||||
'create_file',
|
||||
),
|
||||
idx: 0,
|
||||
},
|
||||
],
|
||||
lastContentIdx: 0,
|
||||
});
|
||||
|
||||
expect(screen.getByTestId('stacked-icons')).toHaveAttribute('data-tool-names', 'edit_file');
|
||||
expect(screen.getByRole('button', { name: 'Create File' })).toBeInTheDocument();
|
||||
});
|
||||
|
||||
it('keeps repeated action counts and failed-call status in the compact summary', () => {
|
||||
renderGroup({
|
||||
...baseProps,
|
||||
|
|
|
|||
|
|
@ -26,6 +26,13 @@ describe('getToolIconType - ACTN-01: Action delimiter detection', () => {
|
|||
expect(getToolIconType('some_plain_tool')).toBe('generic');
|
||||
});
|
||||
|
||||
it('gives native file authoring tools their row glyphs without changing MCP identity', () => {
|
||||
expect(getToolIconType('create_file')).toBe('create_file');
|
||||
expect(getToolIconType('edit_file')).toBe('edit_file');
|
||||
expect(getToolIconType(`create_file${Constants.mcp_delimiter}remote`)).toBe('mcp');
|
||||
expect(getToolIconType(`edit_file${Constants.mcp_delimiter}remote`)).toBe('mcp');
|
||||
});
|
||||
|
||||
it('gives the native background-task tool its own icon while preserving MCP identity', () => {
|
||||
expect(getToolIconType(Constants.CHECK_BACKGROUND_TASK)).toBe('background_tasks');
|
||||
expect(
|
||||
|
|
|
|||
|
|
@ -1,4 +1,4 @@
|
|||
import { Tools, Constants, ContentTypes, stripToolCallErrorPrefix } from 'librechat-data-provider';
|
||||
import { Constants, ContentTypes, stripToolCallErrorPrefix } from 'librechat-data-provider';
|
||||
import type {
|
||||
Agents,
|
||||
TAttachment,
|
||||
|
|
@ -12,9 +12,8 @@ import { getBatchActivityLabelPart, getActivityLabelText } from '~/utils/activit
|
|||
import { hasPendingApprovalInPart, hasPendingAuthInPart } from '~/utils/groupToolCalls';
|
||||
import { ASK_USER_QUESTION, getSubmittedAskAnswer } from '~/utils/approval';
|
||||
import { getToolDisplayLabel, parseToolName } from '~/utils/toolLabels';
|
||||
import { getToolIconName, getToolMeta, summarizeSpan } from './outcome';
|
||||
import { boundIntentLabel, getToolCallIntent } from './Parts/intent';
|
||||
import { isBashProgrammaticToolCall } from './routing';
|
||||
import { getToolMeta, summarizeSpan } from './outcome';
|
||||
import { isError } from './ToolOutput';
|
||||
|
||||
/** How often a live fold's header may repaint. A streamed intent moves the
|
||||
|
|
@ -246,7 +245,7 @@ export function getSpanIconNames(parts: ReadonlyArray<TMessageContentParts | und
|
|||
const toolCall = part == null ? undefined : getStandardToolCall(part);
|
||||
if (toolCall != null) {
|
||||
const name = toolCall.name ?? '';
|
||||
icons.add(isBashProgrammaticToolCall(name, toolCall.args) ? Tools.bash_tool : name);
|
||||
icons.add(getToolIconName(name, toolCall.args, toolCall.output));
|
||||
continue;
|
||||
}
|
||||
const legacy = part == null ? null : getToolMeta(part);
|
||||
|
|
|
|||
|
|
@ -38,6 +38,19 @@ function hasFailedOutput(output: unknown): boolean {
|
|||
return typeof output === 'string' && isError(output);
|
||||
}
|
||||
|
||||
/** A create_file overwrite displays the edit glyph in its own row. Headers use
|
||||
* the same identity, without changing the tool name used for labels/counts. */
|
||||
export function getToolIconName(
|
||||
name: string,
|
||||
args?: string | Record<string, unknown>,
|
||||
output?: string | null,
|
||||
): string {
|
||||
if (name === 'create_file' && output?.startsWith('Updated ')) {
|
||||
return 'edit_file';
|
||||
}
|
||||
return isBashProgrammaticToolCall(name, args) ? Tools.bash_tool : name;
|
||||
}
|
||||
|
||||
/**
|
||||
* Group metadata must agree with the individual card, which resolves its
|
||||
* outcome from the run step's terminal verdict through `resolveToolCallPhase`.
|
||||
|
|
@ -105,7 +118,7 @@ export function getToolMeta(
|
|||
* agents" on completion even when the child returned no text. */
|
||||
const completed = !!tc.output || tc.progress === 1;
|
||||
const name = tc.name ?? '';
|
||||
const iconName = isBashProgrammaticToolCall(name, tc.args) ? Tools.bash_tool : name;
|
||||
const iconName = getToolIconName(name, tc.args, tc.output);
|
||||
/** Memory tools report failure in prose ("Invalid key ...") that generic
|
||||
* `isError` parsing does not recognize, so `MemoryCall` classifies it with
|
||||
* its own predicate. Reuse that here or a persisted call with no terminal
|
||||
|
|
|
|||
|
|
@ -22,9 +22,10 @@ import {
|
|||
import type * as t from 'librechat-data-provider';
|
||||
import type { ReactNode } from 'react';
|
||||
import {
|
||||
SESSION_KEY,
|
||||
isSafeRedirect,
|
||||
getPostLoginRedirect,
|
||||
dropStoredRedirect,
|
||||
readStoredRedirect,
|
||||
clearComposerDraftStorage,
|
||||
clearRetainedFileDeletions,
|
||||
openFileDeletionRetention,
|
||||
|
|
@ -226,8 +227,8 @@ const AuthContextProvider = ({
|
|||
}
|
||||
const { user, token = '' } = data ?? {};
|
||||
if (token) {
|
||||
const storedRedirect = sessionStorage.getItem(SESSION_KEY);
|
||||
sessionStorage.removeItem(SESSION_KEY);
|
||||
const storedRedirect = readStoredRedirect();
|
||||
dropStoredRedirect();
|
||||
const baseUrl = apiBaseUrl();
|
||||
const rawPath = window.location.pathname;
|
||||
const strippedPath =
|
||||
|
|
|
|||
|
|
@ -1221,6 +1221,7 @@
|
|||
"com_ui_background_finished": "Finished in background",
|
||||
"com_ui_background_running": "Running in background",
|
||||
"com_ui_backup_code_number": "Code #{{number}}",
|
||||
"com_ui_backup_code_verification_required": "Enter your backup code to continue",
|
||||
"com_ui_backup_codes": "Backup Codes",
|
||||
"com_ui_backup_codes_regenerate_error": "There was an error regenerating backup codes",
|
||||
"com_ui_backup_codes_regenerated": "Backup codes have been regenerated successfully",
|
||||
|
|
|
|||
|
|
@ -1,3 +1,4 @@
|
|||
import './polyfills/storage';
|
||||
import './polyfills/regeneratorRuntime';
|
||||
import { createRoot } from 'react-dom/client';
|
||||
import { initializeI18n } from './locales/i18n';
|
||||
|
|
|
|||
74
client/src/polyfills/__tests__/storage.test.ts
Normal file
74
client/src/polyfills/__tests__/storage.test.ts
Normal file
|
|
@ -0,0 +1,74 @@
|
|||
import { createMemoryStorage, installStorageFallback } from '../storage';
|
||||
|
||||
function deniedWindow(): Pick<Window, 'localStorage' | 'sessionStorage'> {
|
||||
const target = {} as Pick<Window, 'localStorage' | 'sessionStorage'>;
|
||||
for (const name of ['localStorage', 'sessionStorage']) {
|
||||
Object.defineProperty(target, name, {
|
||||
configurable: true,
|
||||
get() {
|
||||
throw new DOMException('denied', 'SecurityError');
|
||||
},
|
||||
});
|
||||
}
|
||||
return target;
|
||||
}
|
||||
|
||||
describe('installStorageFallback', () => {
|
||||
it('leaves accessible storage untouched', () => {
|
||||
const storage = createMemoryStorage();
|
||||
const target = { localStorage: storage, sessionStorage: storage };
|
||||
expect(installStorageFallback(target)).toEqual([]);
|
||||
expect(target.localStorage).toBe(storage);
|
||||
});
|
||||
|
||||
it('replaces a throwing getter with a working in-memory storage', () => {
|
||||
const target = deniedWindow();
|
||||
expect(() => target.localStorage).toThrow('denied');
|
||||
|
||||
expect(installStorageFallback(target)).toEqual(['localStorage', 'sessionStorage']);
|
||||
|
||||
target.localStorage.setItem('color-theme', 'dark');
|
||||
expect(target.localStorage.getItem('color-theme')).toBe('dark');
|
||||
target.sessionStorage.setItem('lc-rum-queue', '[]');
|
||||
expect(target.sessionStorage.getItem('lc-rum-queue')).toBe('[]');
|
||||
expect(target.localStorage.getItem('lc-rum-queue')).toBeNull();
|
||||
expect(target.localStorage).toBe(target.localStorage);
|
||||
});
|
||||
});
|
||||
|
||||
describe('createMemoryStorage', () => {
|
||||
it('implements the Storage methods', () => {
|
||||
const storage = createMemoryStorage();
|
||||
expect(storage.getItem('missing')).toBeNull();
|
||||
storage.setItem('a', '1');
|
||||
storage.setItem('b', '2');
|
||||
expect(storage).toHaveLength(2);
|
||||
expect(storage.key(1)).toBe('b');
|
||||
expect(storage.key(5)).toBeNull();
|
||||
storage.removeItem('a');
|
||||
expect(storage.getItem('a')).toBeNull();
|
||||
storage.clear();
|
||||
expect(storage).toHaveLength(0);
|
||||
});
|
||||
|
||||
it('reports stored keys as own properties, as key-scanning readers expect', () => {
|
||||
const storage = createMemoryStorage();
|
||||
storage.setItem('textDraft_1', 'hello');
|
||||
storage.setItem('getItem', 'shadow');
|
||||
expect(Object.keys(storage)).toEqual(['textDraft_1', 'getItem']);
|
||||
expect(storage.textDraft_1).toBe('hello');
|
||||
expect(typeof storage.getItem).toBe('function');
|
||||
expect(storage.getItem('getItem')).toBe('shadow');
|
||||
});
|
||||
|
||||
it('routes named-property writes and deletes through the stored items', () => {
|
||||
const storage = createMemoryStorage();
|
||||
storage.lastModel = 'gpt';
|
||||
expect(storage.getItem('lastModel')).toBe('gpt');
|
||||
expect(storage).toHaveLength(1);
|
||||
expect(Object.keys(storage)).toEqual(['lastModel']);
|
||||
delete storage.lastModel;
|
||||
expect(storage.getItem('lastModel')).toBeNull();
|
||||
expect(storage).toHaveLength(0);
|
||||
});
|
||||
});
|
||||
87
client/src/polyfills/storage.ts
Normal file
87
client/src/polyfills/storage.ts
Normal file
|
|
@ -0,0 +1,87 @@
|
|||
type StorageName = 'localStorage' | 'sessionStorage';
|
||||
type StorageHost = Pick<Window, StorageName>;
|
||||
|
||||
const STORAGE_NAMES: StorageName[] = ['localStorage', 'sessionStorage'];
|
||||
|
||||
/** A session-lived stand-in for Web Storage. Stored keys are reported as own enumerable
|
||||
* properties, as on a real `Storage`, so `Object.keys(localStorage)` keeps working. */
|
||||
export function createMemoryStorage(): Storage {
|
||||
const items = new Map<string, string>();
|
||||
const storage: Storage = {
|
||||
get length() {
|
||||
return items.size;
|
||||
},
|
||||
key: (index: number) => Array.from(items.keys())[index] ?? null,
|
||||
getItem: (key: string) => items.get(String(key)) ?? null,
|
||||
setItem: (key: string, value: string) => {
|
||||
items.set(String(key), String(value));
|
||||
},
|
||||
removeItem: (key: string) => {
|
||||
items.delete(String(key));
|
||||
},
|
||||
clear: () => items.clear(),
|
||||
};
|
||||
|
||||
return new Proxy(storage, {
|
||||
get: (target, property, receiver) => {
|
||||
if (typeof property !== 'string' || property in target) {
|
||||
return Reflect.get(target, property, receiver);
|
||||
}
|
||||
return items.get(property);
|
||||
},
|
||||
set: (target, property, value, receiver) => {
|
||||
if (typeof property !== 'string' || property in target) {
|
||||
return Reflect.set(target, property, value, receiver);
|
||||
}
|
||||
items.set(property, String(value));
|
||||
return true;
|
||||
},
|
||||
deleteProperty: (target, property) => {
|
||||
if (typeof property !== 'string' || property in target) {
|
||||
return Reflect.deleteProperty(target, property);
|
||||
}
|
||||
items.delete(property);
|
||||
return true;
|
||||
},
|
||||
ownKeys: () => Array.from(items.keys()),
|
||||
getOwnPropertyDescriptor: (_target, property) => {
|
||||
if (typeof property !== 'string' || !items.has(property)) {
|
||||
return undefined;
|
||||
}
|
||||
return { value: items.get(property), writable: true, enumerable: true, configurable: true };
|
||||
},
|
||||
});
|
||||
}
|
||||
|
||||
function isAccessible(target: StorageHost, name: StorageName): boolean {
|
||||
try {
|
||||
return target[name] != null;
|
||||
} catch {
|
||||
return false;
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* A browser that denies Web Storage by policy throws a `SecurityError` from the
|
||||
* `localStorage`/`sessionStorage` getter itself, which would take down every reader in the
|
||||
* app. Where the getter throws, it is replaced with an in-memory storage for the page's
|
||||
* lifetime, so the app runs on defaults and remembers nothing across reloads.
|
||||
*/
|
||||
export function installStorageFallback(target: StorageHost): StorageName[] {
|
||||
return STORAGE_NAMES.filter((name) => {
|
||||
if (isAccessible(target, name)) {
|
||||
return false;
|
||||
}
|
||||
const fallback = createMemoryStorage();
|
||||
Object.defineProperty(target, name, {
|
||||
configurable: true,
|
||||
enumerable: true,
|
||||
get: () => fallback,
|
||||
});
|
||||
return true;
|
||||
});
|
||||
}
|
||||
|
||||
if (typeof window !== 'undefined') {
|
||||
installStorageFallback(window);
|
||||
}
|
||||
|
|
@ -1,7 +1,7 @@
|
|||
import { useEffect, useState } from 'react';
|
||||
import { Outlet, useNavigate, useLocation } from 'react-router-dom';
|
||||
import type { TStartupConfig } from 'librechat-data-provider';
|
||||
import { DEFAULT_APP_TITLE, REDIRECT_PARAM, SESSION_KEY, setDocumentTitle } from '~/utils';
|
||||
import { DEFAULT_APP_TITLE, REDIRECT_PARAM, hasStoredRedirect, setDocumentTitle } from '~/utils';
|
||||
import { TranslationKeys, useLocalize } from '~/hooks';
|
||||
import { useGetStartupConfig } from '~/data-provider';
|
||||
import AuthLayout from '~/components/Auth/AuthLayout';
|
||||
|
|
@ -32,8 +32,7 @@ export default function StartupLayout({ isAuthenticated }: { isAuthenticated?: b
|
|||
useEffect(() => {
|
||||
if (isAuthenticated) {
|
||||
const hasPendingRedirect =
|
||||
new URLSearchParams(window.location.search).has(REDIRECT_PARAM) ||
|
||||
sessionStorage.getItem(SESSION_KEY) != null;
|
||||
new URLSearchParams(window.location.search).has(REDIRECT_PARAM) || hasStoredRedirect();
|
||||
if (!hasPendingRedirect) {
|
||||
navigate('/c/new', { replace: true });
|
||||
}
|
||||
|
|
|
|||
|
|
@ -3,6 +3,7 @@ import {
|
|||
getPostLoginRedirect,
|
||||
isSafeRedirect,
|
||||
withBasePath,
|
||||
hasStoredRedirect,
|
||||
SESSION_KEY,
|
||||
} from '../redirect';
|
||||
|
||||
|
|
@ -271,3 +272,40 @@ describe('persistRedirectToSession', () => {
|
|||
expect(sessionStorage.getItem(SESSION_KEY)).toBeNull();
|
||||
});
|
||||
});
|
||||
|
||||
describe('blocked session storage', () => {
|
||||
/** Embedded and private contexts throw on access rather than answering null. */
|
||||
const originalDescriptor = Object.getOwnPropertyDescriptor(window, 'sessionStorage');
|
||||
|
||||
beforeEach(() => {
|
||||
Object.defineProperty(window, 'sessionStorage', {
|
||||
configurable: true,
|
||||
get() {
|
||||
throw new DOMException('Storage is blocked in this context', 'SecurityError');
|
||||
},
|
||||
});
|
||||
});
|
||||
|
||||
afterAll(() => {
|
||||
if (originalDescriptor != null) {
|
||||
Object.defineProperty(window, 'sessionStorage', originalDescriptor);
|
||||
}
|
||||
});
|
||||
|
||||
it('persisting a destination does not take down the sign-in', () => {
|
||||
expect(() => persistRedirectToSession('/c/new')).not.toThrow();
|
||||
});
|
||||
|
||||
it('a blocked store reads as empty so the URL param still resolves', () => {
|
||||
const params = new URLSearchParams('redirect_to=%2Fc%2Fnew');
|
||||
expect(getPostLoginRedirect(params)).toBe('/c/new');
|
||||
});
|
||||
|
||||
it('no destination resolves when only the blocked store exists', () => {
|
||||
expect(getPostLoginRedirect(new URLSearchParams())).toBeNull();
|
||||
});
|
||||
|
||||
it('hasStoredRedirect counts a blocked store as empty', () => {
|
||||
expect(hasStoredRedirect()).toBe(false);
|
||||
});
|
||||
});
|
||||
|
|
|
|||
|
|
@ -31,6 +31,35 @@ function resolvesToSameOrigin(url: string): boolean {
|
|||
}
|
||||
}
|
||||
|
||||
/** Session storage is blocked outright in embedded and private contexts, where it throws on
|
||||
* access rather than returning null. The destination is a convenience, never a credential, so a
|
||||
* blocked store must cost the deep link, never the sign-in that carries it: every access
|
||||
* degrades to "no destination stored". Every other session-storage consumer in the client is
|
||||
* already guarded this way; the redirect flow was the one reaching for the store bare-handed. */
|
||||
export const readStoredRedirect = (): string | null => {
|
||||
try {
|
||||
return sessionStorage.getItem(SESSION_KEY);
|
||||
} catch {
|
||||
return null;
|
||||
}
|
||||
};
|
||||
|
||||
export const dropStoredRedirect = (): void => {
|
||||
try {
|
||||
sessionStorage.removeItem(SESSION_KEY);
|
||||
} catch {
|
||||
// A blocked store holds nothing to drop.
|
||||
}
|
||||
};
|
||||
|
||||
const writeStoredRedirect = (value: string): void => {
|
||||
try {
|
||||
sessionStorage.setItem(SESSION_KEY, value);
|
||||
} catch {
|
||||
// The destination cannot cross a document swap in this context; the sign-in continues.
|
||||
}
|
||||
};
|
||||
|
||||
/** Validates that a redirect target is a safe relative path (not an absolute or protocol-relative URL) */
|
||||
export function isSafeRedirect(url: string): boolean {
|
||||
if (hasControlChar(url)) {
|
||||
|
|
@ -46,18 +75,21 @@ export function isSafeRedirect(url: string): boolean {
|
|||
return resolvesToSameOrigin(url);
|
||||
}
|
||||
|
||||
/** Whether a destination is waiting to be consumed; storage that refuses to answer counts as none. */
|
||||
export const hasStoredRedirect = (): boolean => readStoredRedirect() != null;
|
||||
|
||||
/**
|
||||
* Resolves the post-login redirect from URL params and sessionStorage,
|
||||
* cleans up both sources, and returns the validated target (or null).
|
||||
*/
|
||||
export function getPostLoginRedirect(searchParams: URLSearchParams): string | null {
|
||||
const urlRedirect = searchParams.get(REDIRECT_PARAM);
|
||||
const storedRedirect = sessionStorage.getItem(SESSION_KEY);
|
||||
const storedRedirect = readStoredRedirect();
|
||||
|
||||
const target = urlRedirect ?? storedRedirect;
|
||||
|
||||
if (storedRedirect) {
|
||||
sessionStorage.removeItem(SESSION_KEY);
|
||||
dropStoredRedirect();
|
||||
}
|
||||
|
||||
if (target == null || !isSafeRedirect(target)) {
|
||||
|
|
@ -91,6 +123,6 @@ export function withBasePath(path: string): string {
|
|||
|
||||
export function persistRedirectToSession(value: string): void {
|
||||
if (isSafeRedirect(value)) {
|
||||
sessionStorage.setItem(SESSION_KEY, value);
|
||||
writeStoredRedirect(value);
|
||||
}
|
||||
}
|
||||
|
|
|
|||
|
|
@ -32,6 +32,15 @@ memory:
|
|||
personalize: true
|
||||
tokenLimit: 10000
|
||||
|
||||
# Budgets that exist only here, not in the environment, so
|
||||
# yaml-rate-limits.spec.ts proves librechat.yaml reaches the limiters that route
|
||||
# modules build while loading. No other spec calls the speech routes.
|
||||
rateLimits:
|
||||
stt:
|
||||
userMax: 2
|
||||
tts:
|
||||
userMax: 2
|
||||
|
||||
# __E2E_MCP_APP_SANDBOX__
|
||||
|
||||
mcpSettings:
|
||||
|
|
|
|||
92
e2e/specs/mock/scenarios/denied-web-storage.spec.ts
Normal file
92
e2e/specs/mock/scenarios/denied-web-storage.spec.ts
Normal file
|
|
@ -0,0 +1,92 @@
|
|||
import { expect, test } from '@playwright/test';
|
||||
import type { Page } from '@playwright/test';
|
||||
import { NEW_CHAT_PATH, messagesView, replyPrompt, replyText, sendMessage } from '../helpers';
|
||||
|
||||
/**
|
||||
* A browser that denies Web Storage by policy throws a `SecurityError` from the
|
||||
* `localStorage` and `sessionStorage` getters themselves. The denial is in place
|
||||
* before the document's first script, as it is in a real browser, and the app has
|
||||
* to run on defaults instead of handing the page to the error boundary.
|
||||
*/
|
||||
|
||||
declare global {
|
||||
interface Window {
|
||||
/** Set by the init script when the getters were denied before the app loaded. */
|
||||
__storageDenied?: boolean;
|
||||
}
|
||||
}
|
||||
|
||||
async function denyWebStorage(page: Page) {
|
||||
await page.addInitScript(() => {
|
||||
for (const name of ['localStorage', 'sessionStorage']) {
|
||||
Object.defineProperty(window, name, {
|
||||
configurable: true,
|
||||
get() {
|
||||
throw new DOMException('denied', 'SecurityError');
|
||||
},
|
||||
});
|
||||
}
|
||||
window.__storageDenied = true;
|
||||
});
|
||||
}
|
||||
|
||||
function collectPageErrors(page: Page): string[] {
|
||||
const errors: string[] = [];
|
||||
page.on('pageerror', (error) => errors.push(error.message));
|
||||
return errors;
|
||||
}
|
||||
|
||||
async function expectNoErrorBoundary(page: Page, errors: string[]) {
|
||||
await expect(page.getByText('Oops! Something Unexpected Occurred')).toHaveCount(0);
|
||||
expect(errors, `Unexpected runtime errors: ${errors.join(', ')}`).toEqual([]);
|
||||
}
|
||||
|
||||
test.describe('denied web storage', () => {
|
||||
test('the chat shell loads when the browser denies Web Storage @scenario:denied-web-storage-loads-the-chat', async ({
|
||||
page,
|
||||
}) => {
|
||||
const errors = collectPageErrors(page);
|
||||
await denyWebStorage(page);
|
||||
|
||||
await page.goto(NEW_CHAT_PATH, { timeout: 15000 });
|
||||
|
||||
await expect(page.getByRole('textbox', { name: 'Message input' })).toBeVisible();
|
||||
await expect(page.getByRole('main')).toBeVisible();
|
||||
const storage = await page.evaluate(() => {
|
||||
window.localStorage.setItem('probe', 'kept');
|
||||
return {
|
||||
denied: window.__storageDenied === true,
|
||||
probe: window.localStorage.getItem('probe'),
|
||||
session: typeof window.sessionStorage.getItem,
|
||||
};
|
||||
});
|
||||
expect(storage).toEqual({ denied: true, probe: 'kept', session: 'function' });
|
||||
await expectNoErrorBoundary(page, errors);
|
||||
});
|
||||
|
||||
test('a user can chat and start a new chat when the browser denies Web Storage @scenario:denied-web-storage-chats-and-starts-a-new-chat', async ({
|
||||
page,
|
||||
}) => {
|
||||
const errors = collectPageErrors(page);
|
||||
await denyWebStorage(page);
|
||||
await page.goto(NEW_CHAT_PATH, { timeout: 15000 });
|
||||
|
||||
await sendMessage(page, replyPrompt('denied-storage'));
|
||||
await expect(messagesView(page).getByText(replyText('denied-storage'))).toBeVisible({
|
||||
timeout: 30000,
|
||||
});
|
||||
await expect(page).toHaveURL(/\/c\/(?!new$)[^/]+$/);
|
||||
|
||||
await page
|
||||
.getByRole('link', { name: 'New chat', exact: true })
|
||||
.or(page.getByRole('button', { name: 'New chat', exact: true }))
|
||||
.filter({ visible: true })
|
||||
.first()
|
||||
.click();
|
||||
|
||||
await expect(page).toHaveURL(/\/c\/new$/);
|
||||
await expect(page.getByRole('textbox', { name: 'Message input' })).toBeVisible();
|
||||
await expect(messagesView(page).getByText(replyText('denied-storage'))).toHaveCount(0);
|
||||
await expectNoErrorBoundary(page, errors);
|
||||
});
|
||||
});
|
||||
264
e2e/specs/mock/scenarios/two-factor-deep-link.spec.ts
Normal file
264
e2e/specs/mock/scenarios/two-factor-deep-link.spec.ts
Normal file
|
|
@ -0,0 +1,264 @@
|
|||
import { expect, test } from '@playwright/test';
|
||||
import type { Page, Route } from '@playwright/test';
|
||||
|
||||
/**
|
||||
* An ordinary (already enrolled) 2FA sign-in parks its destination in session storage when the
|
||||
* login screen mounts, swaps the document to `/` once the challenge is verified, and rebuilds
|
||||
* the session through the silent refresh. The destination has to survive that document swap and
|
||||
* be consumed by the sign-in that carried it, and the sign-in itself must never depend on the
|
||||
* store being writable at all.
|
||||
*/
|
||||
|
||||
/** A non-default destination: reaching it proves the deep link outlived the whole challenge.
|
||||
* The marker rides the query so no conversation has to exist for the landing to hold. */
|
||||
const DEEP_LINK = '/c/new?model=test&deep-link=proof';
|
||||
const DEEP_LINK_PATTERN = /\/c\/new\?model=test&deep-link=proof$/;
|
||||
/** The second sign-in's own destination: distinct from the first's on purpose. */
|
||||
const SECOND_LINK = '/c/new?from=second-signin';
|
||||
const SECOND_LINK_PATTERN = /\/c\/new\?from=second-signin$/;
|
||||
const DEFAULT_PATTERN = /\/c\/new$/;
|
||||
const CHALLENGE_PATTERN = /\/login\/2fa\?tempToken=temp-token$/;
|
||||
|
||||
const ENROLLED_USER = {
|
||||
id: 'user-2fa',
|
||||
_id: 'user-2fa',
|
||||
name: 'Two Factor User',
|
||||
username: 'twofactor',
|
||||
email: 'twofactor@example.com',
|
||||
provider: 'local',
|
||||
role: 'USER',
|
||||
emailVerified: true,
|
||||
twoFactorEnabled: true,
|
||||
createdAt: '2026-01-01T00:00:00.000Z',
|
||||
updatedAt: '2026-01-01T00:00:00.000Z',
|
||||
};
|
||||
|
||||
const json = (route: Route, body: unknown, status = 200) =>
|
||||
route.fulfill({ status, contentType: 'application/json', body: JSON.stringify(body) });
|
||||
|
||||
/** The PWA service worker serves API GETs itself, which would bypass every `page.route` below. */
|
||||
test.use({ storageState: { cookies: [], origins: [] }, serviceWorkers: 'block' });
|
||||
|
||||
/**
|
||||
* The auth endpoints are intercepted so the ordinary challenge answers deterministically: login
|
||||
* always demands the temp-token challenge, and the refresh endpoint speaks for the cookie the
|
||||
* real verify controller sets — dead before verification, live after it, dead again on logout.
|
||||
*/
|
||||
async function mockChallengeAuth(page: Page) {
|
||||
let sessionLive = false;
|
||||
|
||||
/** Registered first, so every specific mock below takes precedence. The shell's
|
||||
* authenticated queries are answered with their empty shapes: letting them 401 against
|
||||
* the real backend (the bearer is a stand-in for the cookie the real verify controller
|
||||
* sets) would spin the auth-recovery interceptor, whose login bounce carries the current
|
||||
* URL as redirect_to — re-declaring a destination mid-test and re-persisting it at the
|
||||
* login screen. Only /api/config stays real: the login screen renders from it. */
|
||||
await page.route('**/api/**', async (route) => {
|
||||
const url = route.request().url();
|
||||
if (route.request().method() !== 'GET') {
|
||||
await json(route, {});
|
||||
return;
|
||||
}
|
||||
if (/\/api\/config(\?|$)/.test(url)) {
|
||||
const response = await route.fetch();
|
||||
await route.fulfill({ response });
|
||||
return;
|
||||
}
|
||||
if (url.includes('/api/endpoints')) {
|
||||
await json(route, []);
|
||||
return;
|
||||
}
|
||||
if (url.includes('/api/agents/chat/active')) {
|
||||
await json(route, []);
|
||||
return;
|
||||
}
|
||||
if (url.includes('/api/presets')) {
|
||||
await json(route, []);
|
||||
return;
|
||||
}
|
||||
if (/\/api\/tags(\?|$)/.test(url)) {
|
||||
await json(route, []);
|
||||
return;
|
||||
}
|
||||
if (url.includes('/api/models')) {
|
||||
await json(route, {});
|
||||
return;
|
||||
}
|
||||
if (url.includes('/api/convos?')) {
|
||||
await json(route, { conversations: [], pageInfo: { hasMore: false, page: 1, size: 0 } });
|
||||
return;
|
||||
}
|
||||
if (url.includes('/api/convos?pinned')) {
|
||||
await json(route, { conversations: [], pageInfo: { hasMore: false, page: 1, size: 0 } });
|
||||
return;
|
||||
}
|
||||
if (url.includes('/api/projects')) {
|
||||
await json(route, { projects: [], hasMore: false });
|
||||
return;
|
||||
}
|
||||
if (url.includes('/api/user/settings/')) {
|
||||
await json(route, []);
|
||||
return;
|
||||
}
|
||||
if (url.includes('/api/search/enable')) {
|
||||
await json(route, false);
|
||||
return;
|
||||
}
|
||||
if (url.includes('/api/balance')) {
|
||||
await json(route, {});
|
||||
return;
|
||||
}
|
||||
if (url.includes('/api/banner')) {
|
||||
await json(route, { banner: '' });
|
||||
return;
|
||||
}
|
||||
if (url.includes('/api/files/speech')) {
|
||||
await json(route, { enabled: false });
|
||||
return;
|
||||
}
|
||||
if (url.includes('/api/files')) {
|
||||
await json(route, []);
|
||||
return;
|
||||
}
|
||||
await json(route, {});
|
||||
});
|
||||
await page.route('**/api/auth/login', (route) =>
|
||||
json(route, { twoFAPending: true, tempToken: 'temp-token' }),
|
||||
);
|
||||
await page.route('**/api/auth/refresh', async (route) => {
|
||||
if (!sessionLive) {
|
||||
/** The shape the server really sends when no refresh cookie is presented. */
|
||||
await route.fulfill({
|
||||
status: 200,
|
||||
contentType: 'text/html; charset=utf-8',
|
||||
body: 'Refresh token not provided',
|
||||
});
|
||||
return;
|
||||
}
|
||||
await json(route, { token: 'auth-token', user: ENROLLED_USER });
|
||||
});
|
||||
await page.route('**/api/auth/2fa/verify-temp', async (route) => {
|
||||
expect(route.request().postDataJSON()).toEqual({ tempToken: 'temp-token', token: '123456' });
|
||||
sessionLive = true;
|
||||
await json(route, { token: 'auth-token', user: ENROLLED_USER });
|
||||
});
|
||||
await page.route('**/api/auth/logout', async (route) => {
|
||||
sessionLive = false;
|
||||
await json(route, {});
|
||||
});
|
||||
await page.route('**/api/user', (route) =>
|
||||
sessionLive ? json(route, ENROLLED_USER) : json(route, { message: 'Unauthorized' }, 401),
|
||||
);
|
||||
await page.route('**/api/roles/**', (route) => json(route, { name: 'USER', permissions: {} }));
|
||||
}
|
||||
|
||||
/** Drives one full ordinary-challenge sign-in from the login screen. The password field
|
||||
* is located by label: SecretInput renders input[type=password], whose role mapping is
|
||||
* not something the spec should depend on. */
|
||||
async function signInThroughChallenge(page: Page) {
|
||||
await page.getByRole('textbox', { name: 'Email' }).fill(ENROLLED_USER.email);
|
||||
await page.getByLabel('Password').fill('password');
|
||||
await page.getByRole('button', { name: 'Continue' }).click();
|
||||
await expect(page).toHaveURL(CHALLENGE_PATTERN);
|
||||
await page.getByLabel('Enter your 2FA code to continue').fill('123456');
|
||||
await page.getByRole('button', { name: 'Verify' }).click();
|
||||
}
|
||||
|
||||
/** The authenticated shell shows its account button on wide viewports and its header
|
||||
* toggle on narrow ones; either mounting proves the sign-in completed and stayed. */
|
||||
async function expectAuthenticatedShell(page: Page) {
|
||||
await expect
|
||||
.poll(
|
||||
async () =>
|
||||
(await page.getByTestId('nav-user').isVisible()) ||
|
||||
(await page.getByTestId('header-open-sidebar-button').isVisible()),
|
||||
{ timeout: 30000 },
|
||||
)
|
||||
.toBe(true);
|
||||
}
|
||||
|
||||
/** Ends the stand-in session the way the app itself would: an in-page logout request
|
||||
* (page.request would bypass the route mocks) flips the session, and the next document
|
||||
* load finds no session and keeps the login screen. */
|
||||
async function endMockSession(page: Page) {
|
||||
await page.evaluate(() =>
|
||||
fetch('/api/auth/logout', { method: 'POST', credentials: 'include' }).catch(() => undefined),
|
||||
);
|
||||
}
|
||||
|
||||
test.describe('ordinary 2FA challenge · deep links', () => {
|
||||
test('a safe destination survives the challenge and is consumed by that sign-in @scenario:2fa-deep-link-survives-challenge', async ({
|
||||
page,
|
||||
}) => {
|
||||
test.setTimeout(90000);
|
||||
await mockChallengeAuth(page);
|
||||
|
||||
await page.goto(`/login?redirect_to=${encodeURIComponent(DEEP_LINK)}`);
|
||||
await signInThroughChallenge(page);
|
||||
|
||||
await expect(page).toHaveURL(DEEP_LINK_PATTERN, { timeout: 15000 });
|
||||
/** The authenticated shell mounts and settles here rather than bouncing back to /login. */
|
||||
await expectAuthenticatedShell(page);
|
||||
/** Consumed by that sign-in: nothing is left to misdirect a later one. */
|
||||
expect(await page.evaluate(() => sessionStorage.getItem('post_login_redirect_to'))).toBeNull();
|
||||
|
||||
/** A fixed window is the point: the destination must survive the follow-up auth traffic. */
|
||||
await page.waitForTimeout(3000);
|
||||
await expect(page).toHaveURL(DEEP_LINK_PATTERN);
|
||||
|
||||
/** A reload authenticates through the refreshed session and stays on the deep link. */
|
||||
await page.reload();
|
||||
await expectAuthenticatedShell(page);
|
||||
await expect(page).toHaveURL(DEEP_LINK_PATTERN);
|
||||
});
|
||||
|
||||
test('the sign-in completes when session storage is blocked @scenario:2fa-signin-completes-when-storage-blocked', async ({
|
||||
page,
|
||||
}) => {
|
||||
test.setTimeout(90000);
|
||||
await mockChallengeAuth(page);
|
||||
await page.addInitScript(() => {
|
||||
Object.defineProperty(window, 'sessionStorage', {
|
||||
/** Configurable because the CI-mode build's storage polyfill replaces a broken
|
||||
* sessionStorage with its own in-memory shim rather than crashing on a frozen
|
||||
* property. The shim is per-document, so the challenge's document swap still
|
||||
* empties it and the landing contract is identical either way. */
|
||||
configurable: true,
|
||||
get() {
|
||||
throw new DOMException('Storage is blocked in this context', 'SecurityError');
|
||||
},
|
||||
});
|
||||
});
|
||||
|
||||
await page.goto(`/login?redirect_to=${encodeURIComponent(DEEP_LINK)}`);
|
||||
/** The store being unwritable must cost the destination, never the sign-in itself. */
|
||||
await expect(page.getByRole('textbox', { name: 'Email' })).toBeVisible({ timeout: 15000 });
|
||||
await signInThroughChallenge(page);
|
||||
|
||||
await expectAuthenticatedShell(page);
|
||||
await expect(page).toHaveURL(DEFAULT_PATTERN);
|
||||
});
|
||||
|
||||
test('a consumed destination does not misdirect the next sign-in in the tab @scenario:2fa-destination-consumed-once-across-signins', async ({
|
||||
page,
|
||||
}) => {
|
||||
test.setTimeout(120000);
|
||||
await mockChallengeAuth(page);
|
||||
|
||||
await page.goto(`/login?redirect_to=${encodeURIComponent(DEEP_LINK)}`);
|
||||
await signInThroughChallenge(page);
|
||||
await expect(page).toHaveURL(DEEP_LINK_PATTERN, { timeout: 15000 });
|
||||
await expectAuthenticatedShell(page);
|
||||
|
||||
await endMockSession(page);
|
||||
|
||||
/** The second sign-in declares a destination of its own: it must land there,
|
||||
* not on the first sign-in's, and leave nothing behind for a third. */
|
||||
await page.goto(`/login?redirect_to=${encodeURIComponent(SECOND_LINK)}`);
|
||||
await expect(page.getByRole('textbox', { name: 'Email' })).toBeVisible({ timeout: 15000 });
|
||||
await signInThroughChallenge(page);
|
||||
await expect(page).toHaveURL(SECOND_LINK_PATTERN, { timeout: 15000 });
|
||||
await expectAuthenticatedShell(page);
|
||||
expect(await page.evaluate(() => sessionStorage.getItem('post_login_redirect_to'))).toBeNull();
|
||||
});
|
||||
});
|
||||
75
e2e/specs/mock/scenarios/yaml-rate-limits.spec.ts
Normal file
75
e2e/specs/mock/scenarios/yaml-rate-limits.spec.ts
Normal file
|
|
@ -0,0 +1,75 @@
|
|||
import { randomUUID } from 'crypto';
|
||||
import { expect, test } from '@playwright/test';
|
||||
import type { APIRequestContext } from '@playwright/test';
|
||||
import cleanupUser from '../../../setup/cleanupUser';
|
||||
import type { User } from '../../../types';
|
||||
|
||||
/**
|
||||
* `rateLimits` in librechat.yaml is applied during startup, and the speech routes
|
||||
* build their limiters when their module loads. The harness sets `userMax: 2` for
|
||||
* `stt` and `tts` in the yaml only, against a built-in default of 50, so the third
|
||||
* request from a fresh user is refused only when the yaml budget reached the
|
||||
* limiter.
|
||||
*/
|
||||
|
||||
const YAML_USER_MAX = 2;
|
||||
|
||||
async function registerAndLogin(request: APIRequestContext, user: User): Promise<string> {
|
||||
const registerResponse = await request.post('/api/auth/register', {
|
||||
data: {
|
||||
email: user.email,
|
||||
name: user.name,
|
||||
password: user.password,
|
||||
confirm_password: user.password,
|
||||
},
|
||||
});
|
||||
expect(registerResponse.ok()).toBeTruthy();
|
||||
|
||||
const loginResponse = await request.post('/api/auth/login', {
|
||||
data: { email: user.email, password: user.password },
|
||||
});
|
||||
expect(loginResponse.ok()).toBeTruthy();
|
||||
const { token } = (await loginResponse.json()) as { token?: string };
|
||||
if (!token) {
|
||||
throw new Error('Expected login response to include a bearer token');
|
||||
}
|
||||
return token;
|
||||
}
|
||||
|
||||
test.describe('rate limits from librechat.yaml', () => {
|
||||
test('the speech routes enforce the yaml budget @scenario:yaml-rate-limits-reach-speech-limiters', async ({
|
||||
request,
|
||||
}) => {
|
||||
const user: User = {
|
||||
email: `yaml-rate-limits-${randomUUID()}@example.com`,
|
||||
name: 'Yaml Rate Limits',
|
||||
password: 'securepassword123',
|
||||
};
|
||||
|
||||
try {
|
||||
const token = await registerAndLogin(request, user);
|
||||
const headers = { Authorization: `Bearer ${token}` };
|
||||
|
||||
for (const lane of ['stt', 'tts'] as const) {
|
||||
const statuses: number[] = [];
|
||||
let body: { message?: string } = {};
|
||||
for (let attempt = 0; attempt <= YAML_USER_MAX; attempt++) {
|
||||
const response = await request.post(`/api/files/speech/${lane}`, {
|
||||
headers,
|
||||
data: { input: 'hello' },
|
||||
});
|
||||
statuses.push(response.status());
|
||||
if (response.status() === 429) {
|
||||
body = (await response.json()) as { message?: string };
|
||||
}
|
||||
}
|
||||
|
||||
expect(statuses.slice(0, YAML_USER_MAX)).not.toContain(429);
|
||||
expect(statuses[YAML_USER_MAX]).toBe(429);
|
||||
expect(body.message).toBe(`Too many ${lane.toUpperCase()} requests. Try again later`);
|
||||
}
|
||||
} finally {
|
||||
await cleanupUser(user);
|
||||
}
|
||||
});
|
||||
});
|
||||
|
|
@ -170,6 +170,104 @@ test.describe('mid-run steering and queuing', () => {
|
|||
await expect(queuedRows(page)).toHaveCount(0);
|
||||
});
|
||||
|
||||
test('keeps a pending fenced-code steer inside the composer at desktop and mobile widths', async ({
|
||||
page,
|
||||
}) => {
|
||||
test.setTimeout(150000);
|
||||
const label = uniqueLabel('steer-code-layout');
|
||||
const steerText = `Please use this example:\n\n\`\`\`js\n${`const payload = '${'x'.repeat(300)}';\n`.repeat(12)}\`\`\``;
|
||||
|
||||
await page.goto(NEW_CHAT_PATH, { timeout: 10000 });
|
||||
await selectMockEndpoint(page, PROVIDER_C);
|
||||
await selectEphemeralMCP(page);
|
||||
await establishConversation(page, `steer-code-setup-${label}`);
|
||||
|
||||
const run = await sendMessage(page, `E2E_STEER_TOOL_REPLY:${label}`);
|
||||
expect(run.ok()).toBeTruthy();
|
||||
await typeDuringRun(page, steerText);
|
||||
const [steerResponse] = await Promise.all([
|
||||
page.waitForResponse(isSteerRequest, { timeout: 15000 }),
|
||||
messageInput(page).press('Enter'),
|
||||
]);
|
||||
expect(steerResponse.status()).toBe(202);
|
||||
|
||||
const row = inFlightSteers(page).filter({ hasText: 'const payload' });
|
||||
await expect(row.locator('.markdown pre > div')).toHaveCount(1);
|
||||
await expect(row.getByRole('button', { name: 'Show more' })).toBeInViewport();
|
||||
for (const width of [1200, 390]) {
|
||||
await page.setViewportSize({ width, height: 850 });
|
||||
const bounds = await row.evaluate((element) => {
|
||||
const stack = element.closest('[data-testid="in-flight-steers"]')?.getBoundingClientRect();
|
||||
const bubble = element.querySelector('.rounded-theme-surface')?.getBoundingClientRect();
|
||||
const codeBlock = element.querySelector('.markdown pre > div')?.getBoundingClientRect();
|
||||
const code = element.querySelector('.markdown pre code');
|
||||
const codeScroller = code?.parentElement;
|
||||
if (!stack || !bubble || !codeBlock || !code || !codeScroller) {
|
||||
throw new Error('Pending steer code block is missing');
|
||||
}
|
||||
return {
|
||||
stackLeft: stack.left,
|
||||
stackRight: stack.right,
|
||||
bubbleLeft: bubble.left,
|
||||
bubbleRight: bubble.right,
|
||||
codeLeft: codeBlock.left,
|
||||
codeRight: codeBlock.right,
|
||||
codeStartLeft: code.getBoundingClientRect().left,
|
||||
codeScrollWidth: codeScroller.scrollWidth,
|
||||
codeClientWidth: codeScroller.clientWidth,
|
||||
};
|
||||
});
|
||||
expect(bounds.bubbleLeft).toBeGreaterThanOrEqual(bounds.stackLeft);
|
||||
expect(bounds.bubbleRight).toBeLessThanOrEqual(bounds.stackRight);
|
||||
expect(bounds.codeLeft).toBeGreaterThanOrEqual(bounds.bubbleLeft);
|
||||
expect(bounds.codeRight).toBeLessThanOrEqual(bounds.bubbleRight);
|
||||
expect(bounds.codeStartLeft).toBeGreaterThanOrEqual(bounds.codeLeft);
|
||||
await expect(row.locator('.markdown pre').getByText('js', { exact: true })).toBeInViewport();
|
||||
expect(bounds.codeScrollWidth).toBeGreaterThan(bounds.codeClientWidth);
|
||||
await expect(row.getByRole('button', { name: 'Show more' })).toBeInViewport();
|
||||
}
|
||||
await row.getByRole('button', { name: 'Show more' }).click();
|
||||
await expect(row.getByRole('button', { name: 'Show less' })).toBeVisible();
|
||||
});
|
||||
|
||||
test('keeps the beginning of a short code steer visible without expanding', async ({ page }) => {
|
||||
test.setTimeout(150000);
|
||||
const label = uniqueLabel('steer-code-short');
|
||||
const steerText = `\`\`\`js\nconst payload = '${'x'.repeat(300)}';\n\`\`\``;
|
||||
|
||||
await page.goto(NEW_CHAT_PATH, { timeout: 10000 });
|
||||
await selectMockEndpoint(page, PROVIDER_C);
|
||||
await selectEphemeralMCP(page);
|
||||
await establishConversation(page, `steer-code-setup-${label}`);
|
||||
|
||||
const run = await sendMessage(page, `E2E_STEER_TOOL_REPLY:${label}`);
|
||||
expect(run.ok()).toBeTruthy();
|
||||
await typeDuringRun(page, steerText);
|
||||
const [steerResponse] = await Promise.all([
|
||||
page.waitForResponse(isSteerRequest, { timeout: 15000 }),
|
||||
messageInput(page).press('Enter'),
|
||||
]);
|
||||
expect(steerResponse.status()).toBe(202);
|
||||
|
||||
const row = inFlightSteers(page).filter({ hasText: 'const payload' });
|
||||
await expect(row.locator('.markdown pre code')).toContainText('const payload');
|
||||
for (const width of [1200, 390]) {
|
||||
await page.setViewportSize({ width, height: 850 });
|
||||
const bounds = await row.evaluate((element) => {
|
||||
const stack = element.closest('[data-testid="in-flight-steers"]')?.getBoundingClientRect();
|
||||
const code = element.querySelector('.markdown pre code')?.getBoundingClientRect();
|
||||
if (!stack || !code) {
|
||||
throw new Error('Pending steer code is missing');
|
||||
}
|
||||
return { stackLeft: stack.left, stackRight: stack.right, codeStartLeft: code.left };
|
||||
});
|
||||
expect(bounds.codeStartLeft).toBeGreaterThanOrEqual(bounds.stackLeft);
|
||||
expect(bounds.codeStartLeft).toBeLessThan(bounds.stackRight);
|
||||
await expect(row.locator('.markdown pre').getByText('js', { exact: true })).toBeInViewport();
|
||||
await expect(row.getByRole('button', { name: 'Show more' })).toHaveCount(0);
|
||||
}
|
||||
});
|
||||
|
||||
/**
|
||||
* Two steers submitted in quick succession must BOTH inject at the next
|
||||
* tool-batch boundary: the drain is an atomic take-all, the hook returns one
|
||||
|
|
|
|||
|
|
@ -162,7 +162,7 @@ describe('MeterSwatch', () => {
|
|||
});
|
||||
});
|
||||
|
||||
/** CLAUDE.md requires a deliberately different reference theme, to prove the
|
||||
/** AGENTS.md requires a deliberately different reference theme, to prove the
|
||||
* component follows theme data rather than the bundled LibreChat values. */
|
||||
const referenceTheme: ThemeDefinition = {
|
||||
version: THEME_VERSION,
|
||||
|
|
|
|||
|
|
@ -1,7 +1,7 @@
|
|||
#!/usr/bin/env node
|
||||
/**
|
||||
* Sorts imports across the LibreChat monorepo per project convention
|
||||
* (CLAUDE.md § Import Order):
|
||||
* (AGENTS.md § Code style and performance):
|
||||
*
|
||||
* 1. Package value imports — shortest line to longest (`react` always first)
|
||||
* 2. import type from packages — longest line to shortest
|
||||
|
|
@ -81,7 +81,7 @@ function extractSpec(raw: string): string | null {
|
|||
return raw.match(/from\s+['"]([^'"]+)['"]/)?.[1] ?? null;
|
||||
}
|
||||
|
||||
/** Applies the CLAUDE.md grouping/length ordering to a run of pure imports. */
|
||||
/** Applies the AGENTS.md grouping/length ordering to a run of pure imports. */
|
||||
function sortSegment(stmts: Stmt[]): string[] {
|
||||
const g1 = stmts
|
||||
.filter((s) => !s.isType && !s.isLocal)
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue