Commit graph

18 commits

Author SHA1 Message Date
Lia
bbb58a867e ⛴️ fix: Preserve Canary Sync Resolutions (#16457)
Retain the tracked-file integration outcomes recorded by original canary sync PR #16457.

No new implementation is introduced. Shared and ambiguous corrections are carried by the final sync-resolution commit so the resulting tracked tree equals frozen canary f66ad88e1c.

Original-PR: https://github.com/LibreChat-AI/LibreChat/pull/16457
Resolution-Sources: ffa54e0259, 7fe6eab03e, 8f64336ee4, 207ee8b0df, 7f3f82f284, e9e5b36bd2, ff3f0f8bef, 6bd657753a, 84a53a4464, f66ad88e1c
2026-10-01 03:46:19 +00:00
Marco Beretta
339a323ff1 🎨 chore: Enforce Design-System Rules With @shadcn/lint (#15981)
* 🎨 chore: Enforce Design-System Rules With @shadcn/lint

Registers @shadcn/lint for client/src and packages/client/src, resolving\n@librechat/client as the design system so a className that overrides what a\nprimitive owns is reported with the variants and sizes to use instead.\n\nFive rules run at error. no-unknown-classes stays off: it needs Tailwind v4.\nContracts record what callers legitimately own (text typography, skeleton\nsilhouette); eslint-suppressions.json records the 3,141 violations the tree\nalready carried, so the rules gate new code without a tree-wide migration.\n

* 🩹 fix: Close the Gaps Review Found in the Design-Rule Gate

Five findings against this pull request, and one that killed its CI:

- The lockfile entries this change added resolved to a private mirror, so every
  job died in `npm ci`. They now resolve from registry.npmjs.org, with each
  integrity hash checked against the tarball npmjs.org serves.
- The pre-commit hook ran ESLint twice and the first run had no
  `--pass-on-unpruned-suppressions`, so it exited 2 on the suppression the fix
  had just made unused and lint-staged never reached the command that tolerates
  it. One invocation now does both; ESLint applies suppressions after fixes, so
  it reports the post-fix state.
- `scripts/static-checks.mts` omitted that same flag, so `npm run static-checks`
  failed locally on a diff the Static Checks lane passes.
- `lint:design:suppress` recorded a moved file's new path and left the old one
  behind, because only `--prune-suppressions` removes it and ESLint refuses both
  flags in one run. The script now chains the prune, and CLAUDE.md documents the
  scoped recipe that does not re-baseline the whole surface.
- The design rules matched only `.ts`/`.tsx`, so the client's `.jsx` entry points
  bypassed all five. Both globs now cover `.js`/`.jsx`; the one violation that
  exposed — an inline `display: none` on App.jsx's silent-audio iframe — is fixed
  at the source rather than recorded.
- A suppressions-only diff started no workflow and nothing read the baseline. It
  is now a trigger path and its own filter group, and a new `suppressions` check
  rejects a shape ESLint cannot load, a count no run can reach, a rule the plugin
  does not define, and a path that no longer exists.

The count-neutral swap two reviewers raised is not closed: ESLint's baseline
format records a count, not violation identities, so replacing one suppressed
violation with another of the same rule in the same file is invisible here.
CLAUDE.md now says that instead of implying detection.

Four `@scenario`-tagged specs cover the developer-facing behaviour: the report a
caller gets on a primitive override, a `.jsx` file being checked, the fixing
commit staying green (with the counter-proof that it exits 2 without the flag),
the move recipe dropping the old path, and every locked tarball being fetchable
from the public registry.

* 🧪 fix: Close the Dormant-Entry and Gate-Trigger Gaps

The suppressions gate did not run when the file that implements it changed, a
count recorded against a path no design-rule lint reaches passed validation, the
documented re-record chain could not run under cmd.exe, and the lockfile
scenario failed a legitimate SheetJS upgrade. The trigger scenarios also ran
four full-tree sweeps inside one test that declared a 180s deadline for work
measured at 100-280s per sweep.

- scripts/static-checks.mts: `scripts/static-checks.mts` joins the suppressions
  filter and the whole-record trigger, and a recorded path ESLint never reports
  on is rejected as dormant.
- package.json/CLAUDE.md: `|| node -e ""` in place of `|| true`, which cmd.exe
  does not define.
- e2e: the whole-record triggers are a matrix over a miniature repository (2-6s
  each instead of 100-280s), the oversized scenario is split into five
  behaviour-shaped ones, scratch baselines live in os.tmpdir(), and the lint
  gate runs in one project because it has no viewport.

* 📏 chore: Re-Record the Counts Dev Moved Under the Backlog

Rebasing onto dev brought #16067, which restyled three files the recorded
backlog speaks for: MarketplaceSidebar.tsx gained one arbitrary value and two
`no-restyle` violations, ToolsMarketplaceDialog.tsx gained one, and SkillsDialog
lost one. Counts above the file fail the lint for whoever edits it next; the one
below leaves capacity a later violation would spend. Scoped re-record and prune
of those three paths, per the recipe in CLAUDE.md.

* 🧭 test: Run the Copied Runner From the Tree It Is Testing

The trigger matrix pointed the copied static-checks runner at a miniature
repository but invoked it from the real one. The runner derives its repository
from its own location and relativizes file arguments against the working
directory, so `eslint.config.mjs` resolved to a path outside the miniature tree,
the suppressions group read as "not affected by this diff", and the scenario
passed a check that never ran (verify recorded it as a failure: exit 0 where a
rejection was expected). `run` now takes a `cwd`, and both synthetic-root probes
use it.

* 🔇 fix: Reject a Disable Comment With Nothing Behind It Yet

Comparing the two ESLint runs finds a directive only while it is silencing
something. A `/* eslint-disable shadcn/no-raw-colors */` over a file with no raw
colour left both runs agreeing, so it landed unseen and then silenced the first
violation anyone added to that file. The configured run now also asks for unused
directives, which is how ESLint names a disable with nothing behind it: a
dormant design-rule disable and a dormant blanket disable are rejected, a
dormant directive for another rule is not. Neither root carries one today (0
reports across 2,241 files), so what this rejects is new ones.

The same pass also has to see the primitives' variants, so `validateSuppressions`
builds `packages/client/dist` before the directive check rather than inside the
capacity scan that follows it; without the metadata both runs report strictly
fewer design diagnostics and a comment silencing a `no-restyle` violation is
invisible to the comparison.

* 🧱 fix: Count the Library's Build Inputs as Sources

`designMetadataIsFresh` compared `packages/client/dist` with `packages/client/src`
alone, so a commit that changed only the library's manifest or its tsdown config
left every source older than the build and the runner skipped the rebuild. The
design rules then classified against output emitted under the old contract —
locally only, since CI always builds before validating, which is the shape of
divergence nobody sees until the lane disagrees with the commit that passed.

Both files already count as design metadata everywhere else (the suppressions
filter, the whole-record trigger); they now count in the freshness comparison
too. The scenario runs the miniature repository with an observable
`build:client-package`: a current build is not rebuilt, and touching either
input asks for one.

* ⏱️ test: Set the Times the Freshness Rule Compares

The rebuild scenario wrote the build output and then the manifest, and node
wrote both inside the same millisecond, so the manifest was not newer than the
build and the runner correctly declined to rebuild — the assertion failed on the
filesystem clock rather than on the rule. The scenario now sets each mtime it
depends on with `utimesSync`, which is what it meant to say.

* 🩹 fix: Restore the Write the Import Edit Dropped

Adding \ to the import list replaced \ instead of joining it, and nothing local caught it: no tsconfig covers e2e/, and the flat config leaves \ to TypeScript there. The mock harness did — every scenario in the file failed with ReferenceError — which is the point of running it. Typechecked the four scenario files directly this time.

* 🚫 fix: Reject Every Inline Escape, Not Only the Ones in Use

Codex found three more ways past the gate, one shape each. A blanket
\ busy silencing an unrelated rule is used, so ESLint's
unused-directive report never names it, and the configured-versus-ignored
comparison sees no design delta — it waits for the file's first design
violation and takes it. Inline \ over a
clean file is invisible the same way. And a nested baseline that drops an entry
for an unchanged source was checked against its remaining keys only, so the
violation it used to speak for went unread.

The directive check now has two halves: ESLint still answers what a comment is
silencing today, and the comments themselves are read out of the parser — not
the text, so a string that reads like a directive is not one — for a disable
naming a design rule, a blanket disable, or inline configuration naming a
design rule, whether or not anything is behind it yet. That supersedes
\, which could only see the unused ones.
Neither design root carries any of the three today.

\ unions the entries a diff removes into a nested baseline's
file list, and \ joins the design metadata: it
carries the \ mapping, the entry emit and the include/exclude that decide
what reaches the bundle the rules read, which is why the repository's own build
caches key on \.

* 🔐 fix: Make the Hook Select What the Lane Selects, and Distrust a Half-Built Bundle

Two more shapes of the same mistake — trusting a proxy for the thing itself.

The pre-commit group listed individual files while the Static Checks lane's
filter also names both design roots, so staging a primitive ran ESLint locally
and the whole-record sweep only in CI: the commit passed and the lane failed on
callers nobody staged. The hook's group is now the lane's filter pattern for
pattern, and the count-edit scenario reads both files and fails when the two
lists differ, so the next path added to one has to reach the other.

Freshness took the newest timestamp under \ as proof of a
finished build. The build empties that directory before it writes, so a build
that failed halfway leaves a recent directory over a bundle with no entry
point, and every later run skipped rebuilding it. The check now also requires
what \ promises inside \ — its entry fields
and every string leaf of \ — to exist.

* 🧾 fix: Give the CDN Exception to xlsx, Not to the Host

The lockfile rule allowed \ for anything and then compared
versions against the base branch, so regenerating the lockfile against that CDN
could move any package off the public registry at the same version and pass.
The exception now belongs to the package — \, at any version, nested or
not — and every other entry has to come from the registry, which drops the
version comparison and the shallow-clone caveat with it.

The rule is a function the scenario applies to the repository's lockfile and to
lockfiles written for the purpose: an xlsx upgrade on its CDN passes, lodash
rewritten onto the same CDN at the same version fails, a new package from a
private mirror fails, and a nested xlsx is still xlsx.

* ↩️ fix: One Local Entry Point, Asked of the Runner

The pre-commit group I added for the backlog and the design metadata was
redundant and slower: \ already ends by running the runner
over the staged diff with \, and that run
selects its groups from the same filters — including both design roots, and
including deletions, which lint-staged never hands to a task. The group made
the whole-record sweep run twice for one commit. It is gone.

The scenario now asserts the property instead of a copy of the list: the hook
still runs the runner over the staged diff, and for every path the lane's
suppressions paths-filter names, the runner reports that check as selected
(\), while a path outside both roots is not affected.

* 🗺️ fix: Assert Where the Rules Are Asked, Not Only What They Found

A report cannot say where the rules were asked. Narrowing the design block over
a subtree that happens to be clean today — \, say —
produces no new diagnostic, no changed count, and no baseline entry to inspect,
so every gate stays green while the styling written there next goes unread.

The new scenario asks the resolved flat configuration instead: for one
representative path of each source extension in every directory under both
roots, all five design rules must be at error in the app and at the library's
own profile inside \ (overriding a primitive is off there;
colour and inline geometry still hold), and server code must carry none of
them. 1,184 paths, answered through ESLint's API in one process in under a
second — \ would have been eleven minutes of subprocesses.

* 🎯 fix: Spend the Budget Once — Reject a Swap Inside the Allowance

The recorded count is a budget per file and rule, and until now it could be
respent: removing one raw colour while adding a different one keeps the total
equal, so ESLint suppresses the new violation inside the old allowance and the
count checks see nothing move. The backlog was documented as unable to tell
that apart, and it was the one hole Codex kept finding its way back to.

What the totals cannot distinguish the diagnostics can. For every design source
a diff touches, the runner now lints that file's version at the base — through
ESLint's API, one process for the whole diff — and reports a design-rule
message the head has that the base did not, naming it. A violation that only
moved keeps its message and is not reported; a file with no version at the base
has no allowance to hide in and the count checks already answer for it.

Measured on the checkout: swapping one `fill="#AFC1FF"` for `fill="#BEEF11"`
in a file recording five raw colours is rejected in 4.9s naming the new one,
and the unchanged file passes. The scenario proves all three states — recorded,
moved, swapped — in a miniature repository with a history of its own, and
CLAUDE.md no longer claims the swap is undetectable.

* 🧰 fix: The Root Manifests Are Build Inputs Too

\ is defined in the root manifest and runs with the
toolchain the root lockfile pins, and both already select the suppressions
check — but neither counted as an input to bundle freshness, so a commit that
changed the build definition could validate locally against output made by the
previous one while CI rebuilt. They count now, beside the library's own
manifest, build config and compiler options, and the rebuild scenario drives
the lockfile case through the miniature repository's observable build.

* 🧭 fix: Read the Base From the Merge Base, and Give a New File No Allowance

Two holes in the swap check, both about what "the base" means.

It read each changed file's prior version from the base branch's tip, while the
changed-file set comes from \. With \ moving under a branch,
that calls a violation dev added since the branch diverged this change's doing,
and forgives one this change added that dev happens to carry. It resolves the
merge base once and reads from there.

And a file with no version at the base was skipped, so adding a source with a
violation and recording it in the same commit passed as "already recorded".
A file the change adds has no allowance to inherit: every design violation in
it is new. Renames are followed (\), so the
documented re-record of a moved path stays green — its violations came with the
file.

The scenario now walks recorded, moved, swapped, added-with-its-own-entry and
renamed through one miniature repository with a history of its own.

* 🔗 fix: One Base Commit, Asked Once

\ resolved the merge base; \ still read
the baseline from the base branch's tip, so the two checks in the same run
disagreed about what "before" meant — and an entry the base branch edited after
the branch diverged entered \ as though this change had edited it.

\ resolves it once and both ask it.

* 🔤 fix: A Suppressed Message Carries Its Text

\ omitted \, and the swap check reads it
— the union of messages and suppressed messages is what a file's diagnostics
are, and what the baseline silences is exactly what that check has to see.
Nothing local caught it: node strips types without checking them and no
tsconfig covers scripts/, so the runner is now typechecked directly
(                                                                               
                This is not the tsc command you are looking for                
                                                                               

To get access to the TypeScript compiler, tsc, from the command line either:

- Use npm install typescript to first add TypeScript to your project before using npx
- Use yarn to avoid accidentally running code from un-installed packages, clean).

* ⚖️ fix: Let the Record Grow, Out Loud

The swap check reported every violation a change added, which also forbade the
one path CLAUDE.md sanctions: add the violation and raise the count, so the
debt arrives as a line in the diff a reviewer reads. What separates that from a
swap is not the violation, it is whether the record said so — a swap keeps the
count still.

The check now charges each new diagnostic against how much that entry's count
grew between the merge base and here, and reports only what the growth does not
cover. Measured: a swap at an unchanged count fails, the same violation with
the count raised passes, and raising nothing fails naming the class. CLAUDE.md
says which of the three is which.

* 🚧 fix: A File the Change Adds Brings No Allowance

Letting the record grow to cover a new violation is right for a file that
already existed — the raised count is the line a reviewer reads — but it also
let a brand-new source arrive with its own entry, which is the backlog
recording what the tree never owed. Growth applies only where there is
something to grow: a file present at the merge base, renamed or not. A file the
change adds owes everything in it, and the message says so.

* ✏️ test: Assert the Wording the Added-File Rule Uses

The scenario still expected "is new here" for a file the change adds, which now
gets its own message — the backlog records what the tree owed, not what a new
file brings. The harness caught it; the assertion follows the rule.

* 🧮 fix: Ask Git What Existed, and Where Its Entry Lived

Three faults in the new swap check, one cause: it inferred from content what
only git can answer.

A tracked empty file at the base reads as absent, so an existing file was
treated as newly added and its recorded growth refused. A renamed file's
growth was measured at the new key, where the base has no entry at all, so the
move itself looked like room to spend. And a base commit missing from the clone
made every changed file look new, silently.

Existence is now \ succeeding, the allowance is read under the name
the entry had (the rename map already resolved the source; it resolves the
entry too), and a base commit that is not in the clone is reported rather than
guessed at. Measured: a rename carrying a new violation with its count raised
at the new key fails, a plain rename passes, a swap at an equal count fails.

* 🗃️ fix: A Deleted Baseline Is a Deleted Baseline, Nested or Not

The root baseline's deletion failed the check; a nested one was quietly dropped
from the target list by the same \ filter that was meant to skip
paths never present. What a nested baseline silences goes back to being
reported — or stops being — and nothing else reads it, so its deletion is the
same failure and now says which file is missing.

* 📚 fix: A Baseline in the Diff Is Read in Full

The comment said a baseline named in the diff is checked in full; the code
checked only the entries the diff moved, because \ made
\ non-empty and the full-record branch required it to be empty. So a
count edit never revalidated the rest of the record — dormant paths and stale
counts in unedited entries went unread. Editing the baseline now reads every
path it records.

And the rename map keyed on git's raw line, so a CRLF checkout left a \ on
the new path and the rename never matched — the file read as added and its
inherited allowance was refused. The lines are trimmed.

* 🧷 fix: Lint the Base Under the Name It Had, and Compare a Commit With Its Parent

Two last seams in the swap check.

A renamed file's base contents were linted under the new path, so moving a
component out of \ — where overriding a primitive is the
library's own business — into \ made the destination's stricter
rules apply to both sides: the diagnostics the move itself introduces looked
inherited, and a matching entry would have hidden them. The base is linted as
the path it had.

And \, the documented single-commit mode, resolved its
comparison to \ — the commit against itself, which forgives everything.
It resolves to the commit's parent.

* 🔖 fix: Quotes Do Not Hide an Inline Rule Configuration

ESLint reads \ exactly as it reads
the unquoted key, but the comment scan required the colon to follow the rule id
directly, so the quoted form passed over a file that does not violate the rule
yet — and then silences the first violation a primitive or config fan-out
creates there. Over a violating file the two-run comparison always caught it;
the dormant case is the one that slipped. The scan accepts either quoting, and
the scenario carries the quoted spelling beside the rest.

* 🧪 perf: A Spec Is Not Component Metadata

Both roots the design rules police are full of specs — every primitive in
`packages/client/src/components` has one — and editing any of them ran the
two-root suppression sweep, because the metadata predicate asked only whether
the path was a lintable source under a metadata root. A spec is neither: the
flat config turns all five design rules off inside it and the library's
tsconfig keeps it out of the bundle the caller rules resolve primitives
through, so it carries no `cva` variant and can report no design diagnostic of
its own.

`packages/client/src/components/Button.spec.tsx` through the runner:
59.7s before, 0.0s after.

The same `DESIGN_TEST_SOURCE` test is applied everywhere the invariant holds:
the freshness input no longer treats a spec as something `dist` is built from
(directory mtimes stay, so an added or deleted source still forces a rebuild),
the directive gate no longer fails a commit over a comment in a file where the
design rules are already off, and the base-vs-head lint no longer fetches a
spec's base version to ask a question with one possible answer.

* 🔎 fix: A Build That Reports Success Is Not a Build

Two gates trusted a signal instead of the condition it stands for.

`buildClientPackage` returned on the build's exit code. A build that exits 0
while leaving `packages/client/dist` incomplete or older than its sources left
`designMetadataIsFresh()`'s answer exactly as it found it, and the suppression
lint that follows then classified callers against a bundle describing something
else — reporting fewer violations than CI, which is the failure the rebuild
exists to prevent, reached through the branch meant to fix it. The freshness
question is now asked again after a successful build, and a bundle still stale
is an error naming `packages/client/dist`.

The workflow's `on.pull_request.paths` named only the root
`eslint-suppressions.json` while the inner `suppressions` filter names
`**/eslint-suppressions.json`. A diff touching only a nested baseline outside
`api|client|config|packages|scripts` — `e2e/fixtures`, say — started no
workflow at all, so `validateSuppressions()` never ran over exactly the nested
baselines it advertises. The trigger carries both spellings now.

The miniature repository's `build:client-package` writes the bundle its
manifest promises instead of only a marker, so the rebuild rows assert a
finished build rather than a claim of one, and a build that writes nothing is
its own row.

* 🧭 fix: Ask the Tool, Don't Reconstruct Its Answer

Four findings on the last head, and three of them were the next variant of a
family this branch had already patched once. The shared cause is one habit:
the gate re-derived a fact from a cheaper proxy instead of asking whatever owns
it, and every round found another case the proxy got wrong.

An inline `eslint` configuration comment was matched by the spelling of its
rule key, so `shadcn/x`, `"shadcn/x"`, `"shadcn\/x"` and `"shadcn\u002fx"` —
one key, four spellings, all of which ESLint honours — needed four regexes.
The key is now decoded before it is compared, which ends the family rather
than adding the fourth.

Bundle freshness reduced a set of outputs to the newest file anywhere under
`dist`. A resolver loads one entry, not a directory, so a build that rewrote
the ESM bundle and left the CJS one or the type declarations behind passed
while `@shadcn/lint` read the stale one. Every declared output is compared
now, which is the same reason their existence was already checked one by one.

Target discovery read `git diff --name-only` with rename detection, which
names one side. `git mv eslint-suppressions.json backlog.json` therefore
selected no group that owns the source, and the baseline's disappearance was
reported by nothing. `--no-renames` at the single funnel makes a rename two
paths; the one caller that wants the pairing asks for it separately.

The fourth was the parity assertion added last round, sitting in the mock
Playwright lane — whose own trigger excludes `.github/workflows` apart from its
own file, so a workflow-only diff never ran the assertion guarding it. The
claim moved into the runner, where the file that can break it already
activates the group, and the scenario now exercises the runner both ways over
a copy of the real workflow instead of reimplementing its parser.

* 📝 docs: Say Which Swaps the Ratchet Misses

The ratchet paragraph claimed a swap arrives as a failure, full stop. Two do
not, and a reader deciding whether to trust the gate needs both.

A swap whose diagnostic message equals the one it replaced is invisible,
because the comparison keys on the message and some rules name the property
without the value — `Inline style sets display.` is one message for `none` and
for `flex`. And a swap the diff itself causes, by changing a primitive or the
config, is invisible because both versions are linted under the head's design
inputs.

Tracked at berry-13/LibreChat#70 and berry-13/LibreChat#69.

* 📏 chore: Re-Record the Count Dev Moved Under the Backlog

`dev` fixed one `shadcn/no-restyle` violation in
`client/src/components/SharePoint/SharePointPickerDialog.tsx`, so the rebased
branch records 8 where the file now has 7. An entry with slack is exactly what
this change added a check for: the unused 1 would silence the next violation
anyone writes there, and the gate says so rather than letting it through.

`npm run lint:design:prune` drops the one count; the trailing newline it strips
is restored by prettier, the way the pre-commit hook's `*.json` group does.

* 📝 docs: Drop a Recorded Count That Dev Keeps Moving

The backlog total moves with every rebase that picks up new violations from
`dev`, so a number written into CLAUDE.md is stale by the next re-record — it
read 3,230 against a baseline holding 3,232. The recipe does not need the
figure; `eslint-suppressions.json` is the record.

* 📏 chore: Re-Record the Counts Canary Moved Under the Backlog

Retargeting onto canary changes the tree the design rules read, so five
files carry different violation counts than the recorded backlog claims:
Wakeup and SubagentConversation shed no-restyle violations and picked up
a require-static-classes one, and Ledger, UnifiedSidebar and ChatRoute
each gained one. Re-recorded those entries and pruned; nothing else in
the baseline moved.

* 🧱 fix: Build the Primitives Before Recording What They Own

`lint:design:record` was the one exposed design script that linted without
building `packages/client/dist` first. The rules read each primitive's `cva`
variants out of that bundle, so a fresh checkout or a primitive change left
the recording run classifying against a library that does not exist yet and
writing counts lower than the ones CI reports.

Moved the build onto the record script, where the other three already have
it, and dropped it from the `lint:design:suppress` wrapper so the wrapper
still pays for exactly two builds. A build failure inside the wrapper is
still loud: the record step cannot rewrite the baseline when the build it is
chained to fails, and the prune that follows does not swallow its own.

* 📏 chore: Re-Record the Counts Canary Moved Under the Backlog

Rebasing onto canary picks up PR #15798, which rewrote the agent marketplace
components, so eighteen recorded entries no longer describe the files they
name: AgentDetail is gone, AgentCard traded its restyle and arbitrary-value
violations for inline styles, AgentDetailContent grew to eighteen restyles,
and CopyLink, GridSkeleton, Marketplace, MineFilterToggle, SortDropdown and
LoadingDots arrived with violations nothing had recorded.

Re-recorded and pruned; every entry that moved belongs to a file that commit
touched, and nothing else in the baseline changed.

* 🧪 test: Assert the Record Asks for a Build Before It Writes

The build-freshness scenario covers the runner. Nothing covered the other
entry point: `npm run lint:design:record`, which writes the budget every
later change is measured against and, until now, linted whatever bundle
happened to be on disk.

The miniature repository's `build:client-package` appends to a log, so the
scenario can ask whether the record built before it wrote, and whether a
build that fails still stops the wrapper now that the wrapper no longer
carries a build of its own.

---------

Co-authored-by: berry-13 <berry-13@users.noreply.github.com>
(cherry picked from commit 8d5e1a75ee)

Original-PR: https://github.com/LibreChat-AI/LibreChat/pull/15981
2026-10-01 03:46:16 +00:00
lia-by-librechat[bot]
76dbb931a1
🧤 docs: Define Safe Backend Error Contracts in AGENTS.md (#16443)
Co-authored-by: Lia <lia@librechat.ai>
2026-09-28 08:25:26 -04:00
lia-by-librechat[bot]
290e37e5c5
🐤 docs: Clarify Maintainer-Directed Canary Pull Requests (#16291)
* 🐤 docs: Clarify Maintainer-Directed Canary Pull Requests

* 🐤 docs: Link Issues on Dev and Canary PRs

---------

Co-authored-by: Lia <lia@librechat.ai>
2026-09-24 06:49:32 -04:00
Danny Avila
e6376f6df4
👣 docs: Define CJS and Jotai Migration Triggers (#15756)
Both migration rules described an end state and left the trigger implicit, which is why they get skipped.

"Keep /api changes to the absolute minimum" reads as "make a small edit here", the opposite of what it means, and it is phrased for new code while the common case is editing an existing CJS file. It now says /api holds wiring and not behavior, that minimum describes how much behavior /api gains rather than diff size, and that lifting the function out is the larger and correct diff. MCPRequestContext.js is named as the shape.

"Convert the areas you touch" never defined an area, and never said an atom cannot be half converted, so mixed Recoil and Jotai imports in one file read as permission. The rule now states that new state is always Jotai, that the unit of conversion is one atom plus every reader and writer, and that an atom with a consumer outside the feature stays on Recoil and gets passed in. jotai-utils.ts is named for persisted atoms.
2026-09-08 22:20:14 -04:00
Danny Avila
49a3b71919
🧱 docs: Hold Module Boundaries, Configurable Levers and Injected Dependencies (#15754)
* 🧶 docs: Keep the Breadcrumb Carve-Out in AGENTS.md

The template and CLAUDE.md both say that naming the merged pull request which caused a bug is history the reader needs, not a breadcrumb. The condensed AGENTS.md version dropped that half, leaving a flat rule against referencing earlier work, which is the file most agents actually read.

* 🧱 docs: Hold the Database Boundary and Make New Levers Configurable

Workspace Boundaries said where database logic lives but not what may cross the line, so Mongoose types travel outward in exported signatures and make the storage engine part of each module's public API. That is the tax a second engine would pay, and it is cheaper to stop widening than to unwind: packages/api already imports mongoose in dozens of non-test files, while client carries none.

Nothing in either file mentioned configSchema or librechat.yaml either, so a new limit or toggle lands as a constant by default and an operator cannot reach it.

Both rules now sit in Workspace Boundaries, with the configurability half cross-referenced from the definition of done. Condensed into AGENTS.md as Module boundaries and configuration.

* 🔌 docs: Take Dependencies, Do Not Reach for Them

Client State Ownership already tells a frontend feature to accept app-global state through props rather than reaching into the store, and gives the reason: it is what lets the feature move to its own workspace later without a rewrite. The backend had no equivalent, and neither file mentioned dependency injection at all.

Backend modules now carry the same rule one layer down, with createModels(mongoose) as the shape to copy and the static singletons under packages/api/src/mcp as the shape to stop extending. Integrations get it explicitly: an injected provider SDK, storage backend, vector store or OAuth server makes a second implementation a new argument instead of a new branch, and lets a test substitute at the boundary rather than mocking the module that holds it.
2026-09-08 17:25:44 -04:00
Danny Avila
2dd7ca478a
📐 docs: Set PR Description, Review and Completion Standards (#15753)
* 📐 docs: Ask Pull Requests to Show the Mechanism

The template asked for a brief summary and a test process, so descriptions land as a list of changed behavior with no view of how the change works. Reviewers then rebuild the call order from the diff.

Summary now asks for the trigger and the resulting behavior. A new optional How it works section offers four views — a focused diff, a call tree, a shallow file tree, and a Mermaid sequence — with the instruction to pick one or two and delete the section when the summary already covers it. All guidance rides in HTML comments, so an unfilled template renders exactly as it does today.

CLAUDE.md and AGENTS.md carry the same rule for agent-authored descriptions.

Adapted from HumanLayer's show-me skill and an internal ClickHouse PR-template proposal.

* 🧭 docs: Add Review and Completion Standards

Both files describe how to write a change and how to test it, but not how a pull request gets from opened to done. That gap is where review rounds stall: a finding gets patched, the next review runs against an older head, and a working code path ships without its empty, failure or restored-session behavior.

The new Review and Completion section states the review-cycle invariants — inline threads are the source of truth, findings are judged against the code, a review counts only for the commit it ran on, and repeated findings mean the subsystem needs a sweep — followed by a definition of done covering the observable experience, compatibility, and honest reporting of what was actually run.

The reviewer and its trigger phrase are named as the part expected to change, so that subsection can be rewritten without touching the invariants around it. Nothing here restates the existing Testing, Typechecking or Frontend rules; it points at them.

* 🧹 docs: Drop the Shipped Insights Design Note

`docs/agent-insights-access-design.md` was the pre-implementation spec for #15549, and it says so: "design reference for work based on upstream/dev after PR #14898". Everything it specifies shipped — PermissionBits.VIEW_INSIGHTS = 16, /api/insights, the server-owned initial_agent_id — so the code and its tests are the source of truth now and the note can only drift from them. Nothing in the repository links to it.

docs/skills-management-api.md stays: it describes a machine API surface that has no equivalent on librechat.ai, and its details still match packages/api/src/skills/management.ts.
2026-09-08 17:00:32 -04:00
Ravi Kumar L
de888cc362
🎈 ci: Gate Page Loads Under Database Latency (#15646)
Co-authored-by: Danny Avila <danny@librechat.ai>
2026-09-06 12:01:44 -04:00
Danny Avila
c3beae1e18
🔌 refactor: Give the Subagent Surface a Host Seam and Its Own Jotai State (#15455)
* 📐 docs: Record Who Owns Which Piece of Client State

* 🔌 refactor: Give the Subagent Surface a Host Seam and Its Own Jotai State

The subagent chat surface reached up into seven application atoms and could
not be lifted anywhere, and the six atoms it owns were still Recoil while its
sibling stores had already moved to Jotai.

Feature-owned state converts to Jotai and stays where it is: the selection,
per-task control receipts, live progress and the parent-stream fence. The
control atom keeps its session-storage retry — restored per store rather than
per family member, so a reload still sees what the last one persisted.

App-global state now arrives through one `ChatSurface` value the host supplies:
`enterToSend`, `maximizeChatSpace`, `showScrollButton`, the reader's composer
bindings, a `claimForeground` command for the slot the panel and the artifacts
panel share, and `handOffComposerText` for a continuation's unsent words. Two
hosts mount the same adapter — the conversation view and the shared-link view.

Opening the panel was three copies of "clear the artifacts slot, then select";
that is now `useOpenSubagentPanel`, and the three call sites say what they mean.

Nothing under `Chat/Subagents/**` imports `~/store` or `recoil` any more, and
its whole suite runs with no `RecoilRoot` at all.

* 🧹 refactor: Move Subagent State Into the Feature and Free Its Drained Atoms

Two review findings, both fair.

The selection atom still lived in `~/store`, which handed the supposedly
liftable surface an implicit dependency on the application store alongside its
declared host interface — and contradicted the ownership rule this branch
added to CLAUDE.md two commits ago. The module moves to
`components/Chat/Subagents/state.ts`; the hosts that write it (the SSE step
handler, the message renderers) now import from the feature, which is the
direction that survives an extraction.

The conversation-switch drain blanked its two atom-family members but left
them cached. Every invocation key is unique, so a long-lived tab accumulated
two atom configurations per subagent call it ever saw — exactly what the
comment at that boundary says it exists to prevent. `removeSubagentProgressAtoms`
releases them after the values are cleared, mirroring `removeUsageAtoms`. The
new test fails without the release.

* 🔎 fix: Let a Subagent Card Render Where There Is No Panel to Open

Search results render the same card through `Part`, and that route is not
beneath either chat surface — so a search hit containing a subagent tool call
threw on `useChatSurface()` before it could render at all.

Rendering the card and opening a panel are different requirements. The host
stays required for the panel, the activity view and the event group, all of
which only ever mount inside one. `useOpenSubagentPanel` reads the context
optionally instead and answers `null` where there is no host, which is also
the honest answer for search: there is no panel on that route to open, so the
card renders with its details control disabled.

The new test renders the card with no surface at all, and throws with the
reported error when the hook is put back the way it was.

* 🧮 fix: Enrol Read-Created Progress Atoms in the Drain Registry

The read is what creates a family member, and only the streaming paths were
registering their keys. A card rendering a conversation that finished
streaming long ago — or a search result that never streams at all — created
one the navigation drain could not see, so browsing history accumulated an
atom configuration per card for the life of the tab.

`useSubagentProgress` does both halves: it reads the invocation's progress and
enrols its key, so every route into the family shares the one cleanup
boundary. The panel and the parent card both read through it now.

* 🧽 fix: Free a Read-Created Progress Atom at Its Own Card's Unmount

Enrolling read-created keys in the drain registry only helps where something
runs the drain, and `/search` is a standalone route that never mounts the chat
event handlers. Scrolling a virtualised result list therefore kept minting
members nothing would ever free.

`useSubagentProgress` cleans up after itself instead: on unmount it frees the
family members when the read is the only reason they exist. Two guards keep
that from taking live history with it — a key the stream registered belongs to
the drain, and a member holding folded activity is the record of what the child
did, so reopening its card still shows it.

* 🔗 fix: Free a Progress Atom Only After Its Last Reader Lets Go

Opening a foreground panel before the first event gives one still-empty member
two readers: the card that spawned the child and the panel showing it. Closing
the panel freed it while the card was still subscribed — and a subscriber does
not re-render just because its atom left the family, so the first SSE update
landed on the replacement member and the card's ticker stayed dead.

`useSubagentProgress` counts its mounted readers and frees only when the last
one lets go, alongside the two claims that already blocked it: a key the stream
registered, and a member holding folded activity.
2026-09-01 11:15:42 -04:00
Danny Avila
f20b978075
🎯 ci: Retarget Pull Requests Opened Against main to dev (#15416)
* 🎯 ci: Retarget Pull Requests Opened Against `main` to `dev`

Contributions land on `dev`; `main` only moves at release time. With `main` as
the repository's default branch, pull requests default to it, and the mismatch
has been resolved by hand at merge time.

Adds a `pull_request_target` hook that switches a newly opened or reopened pull
request's base from `main` to `dev` and posts a one-time explanation, plus a
manual `workflow_dispatch` sweep (dry-run by default) for the existing backlog.

Release-bound upstream branches keep `main` as their base: `dev`, `release/*`,
`hotfix/*`, `backport/*` and `*-main`. The `target: main` label exempts any
pull request. The exemptions apply only to branches on this repository, so a
fork branch that happens to match one of those names is still retargeted.

The job checks out the trusted base commit rather than the pull request head,
so the write-scoped token never runs contributor code.

`pull_request_target` reads its workflow definition from the base branch, so
this must exist on `main` to take effect.

* 📝 docs: Record the `dev`-First Branch Policy for Agents

`CLAUDE.md` and `AGENTS.md` never stated which branch work targets, and the
default branch is `main` — so `gh pr create` and the GitHub UI point at `main`
unless told otherwise, and an agent following the defaults gets it wrong.

States the policy, the reason a backport to `main` is never needed (`main` is
kept as a strict ancestor of `dev`), and the exemptions the retarget workflow
honors.

* 📐 docs: Record Typecheck, Formatting and Issue-Closing Gotchas for Agents

Four repeat cycle-wasters that neither file stated, each verified against the
current tree:

- `tsdown` emits without typechecking, so `npm run build` proves nothing about
  types in `packages/api`, `packages/client` or `packages/data-schemas`; only
  `packages/data-provider` runs `tsc` in its build.
- `packages/client/tsconfig.json` excludes `*.spec.ts(x)` and `*.test.ts(x)`,
  so type errors in its specs surface only at run time.
- `npm run sort-imports` with no arguments rewrites all six source roots.
- `Fixes #N` never closes an issue here, because closing keywords are honored
  only on merges into the default branch and everything merges to `dev`.

Also notes that worktrees share one stash stack, and points at
`npm run static-checks -- --against origin/dev` as the local mirror of CI.

* 🔁 fix: Address Codex Review on the Retarget Workflow

- **Backport branches are no longer exempt.** Exempting `backport/*` and
  `*-main` contradicted the invariant the policy rests on: `main` is a
  fast-forward of `dev`, so a backport merged straight to `main` is precisely
  what breaks it. `target: main` remains the deliberate, explicit escape hatch;
  `dev`, `release/*` and `hotfix/*` stay exempt as release-bound branches.
- **`npm run update` does not sync `dev`.** `config/update.js` hard-codes
  `git checkout main` and `git pull origin main` — it is the self-host
  deployment updater, not a branch-sync tool. Telling contributors to refresh
  `dev` with it would have branched them off `main` and recreated the very
  flow this change exists to prevent. Replaced with the explicit git commands.
- **A dry run no longer reports work it did not do.** The summary said
  "Retargeted N" on a dispatch that wrote nothing, which could read as a
  completed sweep.
- **A failed explanation comment is recorded, not swallowed.** The base edit
  has already landed at that point, so a later run would skip the pull request
  and the contributor would never receive the note. It now counts, fails the
  run, and names the retry: `EXPLAIN_MISSING=true`, which posts a missing
  explanation onto an already-retargeted pull request.
- **The sweep paginates.** `gh pr list --limit 500` is a cap, not a page size,
  and would have silently ignored the remainder while reporting success.

Verified against the stubbed `gh` boundary: `*-main` now retargets, the dry run
performs zero writes and says so, a failing comment yields a non-zero exit, and
`EXPLAIN_MISSING` posts onto a pull request already based on `dev`. The
paginated query returns all 258 open pull requests based on `main`.

* 🧷 fix: Address the Second Codex Round on the Retarget Workflow

- **`already_explained` now separates "lookup failed" from "no marker".** A
  transient comments-API failure returned the same status as a clean miss, so
  the run would post a second explanation and report success — defeating the
  deduplication it exists for. A failed read now declines to post and is
  recorded.
- **`CONTRIBUTING.md` syncs from the canonical remote.** The previous fix
  pulled `dev` from `origin`, which in the fork-based flow described two
  sections later is the contributor's own fork — so it would fail outright or
  silently sync a stale branch, landing them on the wrong base again.
- **The hook retries on `synchronize`.** If the `opened` run failed before
  `gh pr edit` landed, nothing retried and the pull request stayed on `main`.
  A retargeted pull request no longer matches `branches: [main]`, so this adds
  no redundant runs — and the existing backlog now drains on contributor
  activity rather than only by sweep.
- **Sweeps serialize against each other** via a shared concurrency group, while
  the hook stays keyed per pull request. Deliberately not one global group:
  GitHub keeps a single pending job per group, so a burst of openings would
  cancel queued retargets — trading a rare duplicate comment for dropped
  retargets is the wrong way round.
- **`main` is an ancestor of `dev`, not a strict one.** Right after a sync the
  two refs are equal, which the previous wording described as a violated
  invariant.

Verified: a failing comments lookup edits the base but posts nothing and exits
non-zero.
2026-08-31 11:29:34 -04:00
Alexandre Beguel
6baeff801c
📐 docs: Make CLAUDE.md Portable and Restore AGENTS.md Parity (#15046)
CLAUDE.md pointed at /home/danny/agentus for the @librechat/agents source.
That path resolves on one machine, so for every other contributor the line
occupies context on every turn while pointing nowhere. Replaced with the
public repository URL.

AGENTS.md opens with "See CLAUDE.md", which makes CLAUDE.md the source of
truth, but it carried an auth cache invalidation rule that appears nowhere
in CLAUDE.md. Claude Code reads CLAUDE.md and not AGENTS.md, so contributors
using it never received a rule about serving stale req.user.

Moved that rule into a Backend Rules section in CLAUDE.md, mirroring the
existing Frontend Rules section, and left AGENTS.md pointing at it the same
way its theming paragraph already does.

Closes #15045
2026-08-20 17:28:49 -04:00
Danny Avila
c3a429ddcd
🎨 feat: Add Versioned Theme Foundation (#14709)
* 🎨 feat: Add Versioned Theme Foundation

* 🧩 fix: Keep Theme-Aware Chip Actions Consistent

* 🎛️ fix: Preserve Default Theme Geometry

* 🪪 fix: Keep Theme Identity in Sync

* 🧭 docs: Define Theme Styling Policy

* 🧹 chore: Sort Theme Imports

* 🧵 fix: Preserve Theme Compatibility Contracts

* 🛡️ fix: Harden Theme Compatibility Boundaries

* 🧵 fix: Publish Theme Appearance Preset

* 🐳 fix: Include Theme Preset in Docker Build

* 🪢 fix: Preserve Legacy Theme Compatibility

* 🧭 fix: Harden Theme Lifecycle Boundaries

* 🧱 fix: Align Theme Appearance Defaults

* 🧬 fix: Record Persisted Theme Provenance

* 🧭 fix: Preserve Theme Transition State

* 🧷 fix: Preserve Legacy Theme Contracts
2026-08-10 13:41:03 -04:00
Ravi Kumar L
329ed48246
📉 perf: cache OpenID JWT user documents (#14187)
* feat(auth): cache OpenID JWT user documents

* fix(auth): invalidate cached auth users on role changes
2026-07-12 07:53:50 -04:00
Ravi Kumar L
44d1275f36
⚙️ perf: reduce first-load MongoDB round trips (#14101)
* perf(api): reduce first-load database round trips

* docs: move agent guidance to claude docs

* refactor(api): move message validation into api package

* fix(api): narrow active generation job lookup

* fix(api): preserve omitted source identity
2026-07-06 09:36:34 -04:00
Danny Avila
419613fdaf 📋 chore: Move project instructions from AGENTS.md to CLAUDE.md 2026-03-31 21:50:38 -04:00
Danny Avila
4b6d68b3b5
🎛️ feat: DB-Backed Per-Principal Config System (#12354)
* ✨ feat: Add Config schema, model, and methods for role-based DB config overrides

Add the database foundation for principal-based configuration overrides
(user, group, role) in data-schemas. Includes schema with tenantId and
tenant isolation, CRUD methods, and barrel exports.

* 🔧 fix: Add shebang and enforce LF line endings for git hooks

The pre-commit hook was missing #!/bin/sh, and core.autocrlf=true was
converting it to CRLF, both causing "Exec format error" on Windows.
Add .gitattributes to force LF for .husky/* and *.sh files.

* ✨ feat: Add admin config API routes with section-level capability checks

Add /api/admin/config endpoints for managing per-principal config
overrides (user, group, role). Handlers in @librechat/api use DI pattern
with section-level hasConfigCapability checks for granular access control.

Supports full overrides replacement, per-field PATCH via dot-paths, field
deletion, toggle active, and listing.

* 🐛 fix: Move deleteConfigField fieldPath from URL param to request body

The path-to-regexp wildcard syntax (:fieldPath(*)) is not supported by
the version used in Express. Send fieldPath in the DELETE request body
instead, which also avoids URL-encoding issues with dotted paths.

* ✨ feat: Wire config resolution into getAppConfig with override caching

Add mergeConfigOverrides utility in data-schemas for deep-merging DB
config overrides into base AppConfig by priority order.

Update getAppConfig to query DB for applicable configs when role/userId
is provided, with short-TTL caching and a hasAnyConfigs feature flag
for zero-cost when no DB configs exist.

Also: add unique compound index on Config schema, pass userId from
config middleware, and signal config changes from admin API handlers.

* 🔄 refactor: Extract getAppConfig logic into packages/api as TS service

Move override resolution, caching strategy, and signalConfigChange from
api/server/services/Config/app.js into packages/api/src/app/appConfigService.ts
using the DI factory pattern (createAppConfigService). The JS file becomes
a thin wiring layer injecting loadBaseConfig, cache, and DB dependencies.

* 🧹 chore: Rename configResolution.ts to resolution.ts

* ✨ feat: Move admin types & capabilities to librechat-data-provider

Move SystemCapabilities, CapabilityImplications, and utility functions
(hasImpliedCapability, expandImplications) from data-schemas to
data-provider so they are available to external consumers like the
admin panel without a data-schemas dependency.

Add API-friendly admin types: TAdminConfig, TAdminSystemGrant,
TAdminAuditLogEntry, TAdminGroup, TAdminMember, TAdminUserSearchResult,
TCapabilityCategory, and CAPABILITY_CATEGORIES.

data-schemas re-exports these from data-provider and extends with
config-schema-derived types (ConfigSection, SystemCapability union).

Bump version to 0.8.500.

* feat: Add JSON-serializable admin config API response types to data-schemas

Add AdminConfig, AdminConfigListResponse, AdminConfigResponse, and
AdminConfigDeleteResponse types so both LibreChat API handlers and the
admin panel can share the same response contract. Bump version to 0.0.41.

* refactor: Move admin capabilities & types from data-provider to data-schemas

SystemCapabilities, CapabilityImplications, utility functions,
CAPABILITY_CATEGORIES, and admin API response types should not be in
data-provider as it gets compiled into the frontend bundle, exposing
the capability surface. Moved everything to data-schemas (server-only).

All consumers already import from @librechat/data-schemas, so no
import changes needed elsewhere. Consolidated duplicate AdminConfig
type (was in both config.ts and admin.ts).

* chore: Bump @librechat/data-schemas to 0.0.42

* refactor: Reorganize admin capabilities into admin/ and types/admin.ts

Split systemCapabilities.ts following data-schemas conventions:
- Types (BaseSystemCapability, SystemCapability, AdminConfig, etc.)
  → src/types/admin.ts
- Runtime code (SystemCapabilities, CapabilityImplications, utilities)
  → src/admin/capabilities.ts

Revert data-provider version to 0.8.401 (no longer modified).

* chore: Fix import ordering, rename appConfigService to service

- Rename app/appConfigService.ts → app/service.ts (directory provides context)
- Fix import order in admin/config.ts, types/admin.ts, types/config.ts
- Add naming convention to AGENTS.md

* feat: Add DB base config support (role/__base__)

- Add BASE_CONFIG_PRINCIPAL_ID constant for reserved base config doc
- getApplicableConfigs always includes __base__ in queries
- getAppConfig queries DB even without role/userId when DB configs exist
- Bump @librechat/data-schemas to 0.0.43

* fix: Address PR review issues for admin config

- Add listAllConfigs method; listConfigs endpoint returns all active
  configs instead of only __base__
- Normalize principalId to string in all config methods to prevent
  ObjectId vs string mismatch on user/group lookups
- Block __proto__ and all dunder-prefixed segments in field path
  validation to prevent prototype pollution
- Fix configVersion off-by-one: default to 0, guard pre('save') with
  !isNew, use $inc on findOneAndUpdate
- Remove unused getApplicableConfigs from admin handler deps

* fix: Enable tree-shaking for data-schemas, bump packages

- Switch data-schemas Rollup output to preserveModules so each source
  file becomes its own chunk; consumers (admin panel) can now import
  just the modules they need without pulling in winston/mongoose/etc.
- Add sideEffects: false to data-schemas package.json
- Bump data-schemas to 0.0.44, data-provider to 0.8.402

* feat: add capabilities subpath export to data-schemas

Adds `@librechat/data-schemas/capabilities` subpath export so browser
consumers can import BASE_CONFIG_PRINCIPAL_ID and capability constants
without pulling in Node.js-only modules (winston, async_hooks, etc.).

Bump version to 0.0.45.

* fix: include dist/ in data-provider npm package

Add explicit files field so npm includes dist/types/ in the published
package. Without this, the root .gitignore exclusion of dist/ causes
npm to omit type declarations, breaking TypeScript consumers.

* chore: bump librechat-data-provider to 0.8.403

* feat: add GET /api/admin/config/base for raw AppConfig

Returns the full AppConfig (YAML + DB base merged) so the admin panel
can display actual config field values and structure. The startup config
endpoint (/api/config) returns TStartupConfig which is a different shape
meant for the frontend app.

* chore: imports order

* fix: address code review findings for admin config

Critical:
- Fix clearAppConfigCache: was deleting from wrong cache store (CONFIG_STORE
  instead of APP_CONFIG), now clears BASE and HAS_DB_CONFIGS keys
- Eliminate race condition: patchConfigField and deleteConfigField now use
  atomic MongoDB $set/$unset with dot-path notation instead of
  read-modify-write cycles, removing the lost-update bug entirely
- Add patchConfigFields and unsetConfigField atomic DB methods

Major:
- Reorder cache check before principal resolution in getAppConfig so
  getUserPrincipals DB query only fires on cache miss
- Replace '' as ConfigSection with typed BROAD_CONFIG_ACCESS constant
- Parallelize capability checks with Promise.all instead of sequential
  awaits in for loops
- Use loose equality (== null) for cache miss check to handle both null
  and undefined returns from cache implementations
- Set HAS_DB_CONFIGS_KEY to true on successful config fetch

Minor:
- Remove dead pre('save') hook from config schema (all writes use
  findOneAndUpdate which bypasses document hooks)
- Consolidate duplicate type imports in resolution.ts
- Remove dead deepGet/deepSet/deepUnset functions (replaced by atomic ops)
- Add .sort({ priority: 1 }) to getApplicableConfigs query
- Rename _impliedBy to impliedByMap

* fix: self-referencing BROAD_CONFIG_ACCESS constant

* fix: replace type-cast sentinel with proper null parameter

Update hasConfigCapability to accept ConfigSection | null where null
means broad access check (MANAGE_CONFIGS or READ_CONFIGS only).
Removes the '' as ConfigSection type lie from admin config handlers.

* fix: remaining review findings + add tests

- listAllConfigs accepts optional { isActive } filter so admin listing
  can show inactive configs (#9)
- Standardize session application to .session(session ?? null) across
  all config DB methods (#15)
- Export isValidFieldPath and getTopLevelSection for testability
- Add 38 tests across 3 spec files:
  - config.spec.ts (api): path validation, prototype pollution rejection
  - resolution.spec.ts: deep merge, priority ordering, array replacement
  - config.spec.ts (data-schemas): full CRUD, ObjectId normalization,
    atomic $set/$unset, configVersion increment, toggle, __base__ query

* fix: address second code review findings

- Fix cross-user cache contamination: overrideCacheKey now handles
  userId-without-role case with its own cache key (#1)
- Add broad capability check before DB lookup in getConfig to prevent
  config existence enumeration (#2/#3)
- Move deleteConfigField fieldPath from request body to query parameter
  for proxy/load balancer compatibility (#5)
- Derive BaseSystemCapability from SystemCapabilities const instead of
  manual string union (#6)
- Return 201 on upsert creation, 200 on update (#11)
- Remove inline narration comments per AGENTS.md (#12)
- Type overrides as Partial<TCustomConfig> in DB methods and handler
  deps (#13)
- Replace double as-unknown-as casts in resolution.ts with generic
  deepMerge<T> (#14)
- Make override cache TTL injectable via AppConfigServiceDeps (#16)
- Add exhaustive never check in principalModel switch (#17)

* fix: remaining review findings — tests, rename, semantics

- Rename signalConfigChange → markConfigsDirty with JSDoc documenting
  the stale-window tradeoff and overrideCacheTtl knob
- Fix DEFAULT_OVERRIDE_CACHE_TTL naming convention
- Add createAppConfigService tests (14 cases): cache behavior, feature
  flag, cross-user key isolation, fallback on error, markConfigsDirty
- Add admin handler integration tests (13 cases): auth ordering,
  201/200 on create/update, fieldPath from query param, markConfigsDirty
  calls, capability checks

* fix: global flag corruption + empty overrides auth bypass

- Remove HAS_DB_CONFIGS_KEY=false optimization: a scoped query returning
  no configs does not mean no configs exist globally. Setting the flag
  false from a per-principal query short-circuited all subsequent users.
- Add broad manage capability check before section checks in
  upsertConfigOverrides: empty overrides {} no longer bypasses auth.

* test: add regression and invariant tests for config system

Regression tests:
- Bug 1: User A's empty result does not short-circuit User B's overrides
- Bug 2: Empty overrides {} returns 403 without MANAGE_CONFIGS

Invariant tests (applied across ALL handlers):
- All 5 mutation handlers call markConfigsDirty on success
- All 5 mutation handlers return 401 without auth
- All 5 mutation handlers return 403 without capability
- All 3 read handlers return 403 without capability

* fix: third review pass — all findings addressed

Service (service.ts):
- Restore HAS_DB_CONFIGS=false for base-only queries (no role/userId)
  so deployments with zero DB configs skip DB queries (#1)
- Resolve cache once at factory init instead of per-invocation (#8)
- Use BASE_CONFIG_PRINCIPAL_ID constant in overrideCacheKey (#10)
- Add JSDoc to clearAppConfigCache documenting stale-window (#4)
- Fix log message to not say "from YAML" (#14)

Admin handlers (config.ts):
- Use configVersion===1 for 201 vs 200, eliminating TOCTOU race (#2)
- Add Array.isArray guard on overrides body (#5)
- Import CapabilityUser from capabilities.ts, remove duplicate (#6)
- Replace as-unknown-as cast with targeted type assertion (#7)
- Add MAX_PATCH_ENTRIES=100 cap on entries array (#15)
- Reorder deleteConfigField to validate principalType first (#12)
- Export CapabilityUser from middleware/capabilities.ts

DB methods (config.ts):
- Remove isActive:true from patchConfigFields to prevent silent
  reactivation of disabled configs (#3)

Schema (config.ts):
- Change principalId from Schema.Types.Mixed to String (#11)

Tests:
- Add patchConfigField unsafe fieldPath rejection test (#9)
- Add base-only HAS_DB_CONFIGS=false test (#1)
- Update 201/200 tests to use configVersion instead of findConfig (#2)

* fix: add read handler 401 invariant tests + document flag behavior

- Add invariant: all 3 read handlers return 401 without auth
- Document on markConfigsDirty that HAS_DB_CONFIGS stays true after
  all configs are deleted until clearAppConfigCache or restart

* fix: remove HAS_DB_CONFIGS false optimization entirely

getApplicableConfigs([]) only queries for __base__, not all configs.
A deployment with role/group configs but no __base__ doc gets the
flag poisoned to false by a base-only query, silently ignoring all
scoped overrides. The optimization is not safe without a comprehensive
Config.exists() check, which adds its own DB cost. Removed entirely.

The flag is now write-once-true (set when configs are found or by
markConfigsDirty) and only cleared by clearAppConfigCache/restart.

* chore: reorder import statements in app.js for clarity

* refactor: remove HAS_DB_CONFIGS_KEY machinery entirely

The three-state flag (false/null/true) was the source of multiple bugs
across review rounds. Every attempt to safely set it to false was
defeated by getApplicableConfigs querying only a subset of principals.

Removed: HAS_DB_CONFIGS_KEY constant, all reads/writes of the flag,
markConfigsDirty (now a no-op concept), notifyChange wrapper, and all
tests that seeded false manually.

The per-user/role TTL cache (overrideCacheTtl, default 60s) is the
sole caching mechanism. On cache miss, getApplicableConfigs queries
the DB. This is one indexed query per user per TTL window — acceptable
for the config override use case.

* docs: rewrite admin panel remaining work with current state

* perf: cache empty override results to avoid repeated DB queries

When getApplicableConfigs returns no configs for a principal, cache
baseConfig under their override key with TTL. Without this, every
user with no per-principal overrides hits MongoDB on every request
after the 60s cache window expires.

* fix: add tenantId to cache keys + reject PUBLIC principal type

- Include tenantId in override cache keys to prevent cross-tenant
  config contamination. Single-tenant deployments (tenantId undefined)
  use '_' as placeholder — no behavior change for them.
- Reject PrincipalType.PUBLIC in admin config validation — PUBLIC has
  no PrincipalModel and is never resolved by getApplicableConfigs,
  so config docs for it would be dead data.
- Config middleware passes req.user.tenantId to getAppConfig.

* fix: fourth review pass findings

DB methods (config.ts):
- findConfigByPrincipal accepts { includeInactive } option so admin
  GET can retrieve inactive configs (#5)
- upsertConfig catches E11000 duplicate key on concurrent upserts and
  retries without upsert flag (#2)
- unsetConfigField no longer filters isActive:true, consistent with
  patchConfigFields (#11)
- Typed filter objects replace Record<string, unknown> (#12)

Admin handlers (config.ts):
- patchConfigField: serial broad capability check before Promise.all
  to pre-warm ALS principal cache, preventing N parallel DB calls (#3)
- isValidFieldPath rejects leading/trailing dots and consecutive
  dots (#7)
- Duplicate fieldPaths in patch entries return 400 (#8)
- DEFAULT_PRIORITY named constant replaces hardcoded 10 (#14)
- Admin getConfig and patchConfigField pass includeInactive to
  findConfigByPrincipal (#5)
- Route import uses barrel instead of direct file path (#13)

Resolution (resolution.ts):
- deepMerge has MAX_MERGE_DEPTH=10 guard to prevent stack overflow
  from crafted deeply nested configs (#4)

* fix: final review cleanup

- Remove ADMIN_PANEL_REMAINING.md (local dev notes with Windows paths)
- Add empty-result caching regression test
- Add tenantId to AdminConfigDeps.getAppConfig type
- Restore exhaustive never check in principalModel switch
- Standardize toggleConfigActive session handling to options pattern

* fix: validate priority in patchConfigField handler

Add the same non-negative number validation for priority that
upsertConfigOverrides already has. Without this, invalid priority
values could be stored via PATCH and corrupt merge ordering.

* chore: remove planning doc from PR

* fix: correct stale cache key strings in service tests

* fix: clean up service tests and harden tenant sentinel

- Remove no-op cache delete lines from regression tests
- Change no-tenant sentinel from '_' to '__default__' to avoid
  collision with a real tenant ID when multi-tenancy is enabled
- Remove unused CONFIG_STORE from AppConfigServiceDeps

* chore: bump @librechat/data-schemas to 0.0.46

* fix: block prototype-poisoning keys in deepMerge

Skip __proto__, constructor, and prototype keys during config merge
to prevent prototype pollution via PUT /api/admin/config overrides.
2026-03-25 19:39:29 -04:00
Danny Avila
6167ce6e57
🧪 chore: MCP Reconnect Storm Follow-Up Fixes and Integration Tests (#12172)
* 🧪 test: Add reconnection storm regression tests for MCPConnection

Introduced a comprehensive test suite for reconnection storm scenarios, validating circuit breaker, throttling, cooldown, and timeout fixes. The tests utilize real MCP SDK transports and a StreamableHTTP server to ensure accurate behavior under rapid connect/disconnect cycles and error handling for SSE 400/405 responses. This enhances the reliability of the MCPConnection by ensuring proper handling of reconnection logic and circuit breaker functionality.

* 🔧 fix: Update createUnavailableToolStub to return structured response

Modified the `createUnavailableToolStub` function to return an array containing the unavailable message and a null value, enhancing the response structure. Additionally, added a debug log to skip tool creation when the result is null, improving the handling of reconnection scenarios in the MCP service.

* 🧪 test: Enhance MCP tool creation tests for cache and throttle interactions

Added new test cases for the `createMCPTool` function to validate the caching behavior when tools are unavailable or throttled. The tests ensure that tools are correctly cached as missing and prevent unnecessary reconnects across different users, improving the reliability of the MCP service under concurrent usage scenarios. Additionally, introduced a test for the `createMCPTools` function to verify that it returns an empty array when reconnect is throttled, ensuring proper handling of throttling logic.

* 📝 docs: Update AGENTS.md with testing philosophy and guidelines

Expanded the testing section in AGENTS.md to emphasize the importance of using real logic over mocks, advocating for the use of spies and real dependencies in tests. Added specific recommendations for testing with MongoDB and MCP SDK, highlighting the need to mock only uncontrollable external services. This update aims to improve testing practices and encourage more robust test implementations.

* 🧪 test: Enhance reconnection storm tests with socket tracking and SSE handling

Updated the reconnection storm test suite to include a new socket tracking mechanism for better resource management during tests. Improved the handling of SSE 400/405 responses by ensuring they are processed in the same branch as 404 errors, preventing unhandled cases. This enhances the reliability of the MCPConnection under rapid reconnect scenarios and ensures proper error handling.

* 🔧 fix: Implement cache eviction for stale reconnect attempts and missing tools

Added an `evictStale` function to manage the size of the `lastReconnectAttempts` and `missingToolCache` maps, ensuring they do not exceed a maximum cache size. This enhancement improves resource management by removing outdated entries based on a specified time-to-live (TTL), thereby optimizing the MCP service's performance during reconnection scenarios.
2026-03-10 17:44:13 -04:00
Danny Avila
c3da148fa0
📝 docs: Add AGENTS.md for Project Structure and Coding Standards (#11866)
* 📝 docs: Add AGENTS.md for project structure and coding standards

- Introduced AGENTS.md to outline project workspaces, coding standards, and development commands.
- Defined workspace boundaries for backend and frontend development, emphasizing TypeScript usage.
- Established guidelines for code style, iteration performance, type safety, and import order.
- Updated CONTRIBUTING.md to reference AGENTS.md for coding standards and project conventions.
- Modified package.json to streamline build commands, consolidating frontend and backend build processes.

* chore: Update build commands and improve smart reinstall process

- Modified AGENTS.md to clarify the purpose of `npm run smart-reinstall` and other build commands, emphasizing Turborepo's role in dependency management and builds.
- Updated package.json to streamline build commands, replacing the legacy frontend build with a Turborepo-based approach for improved performance.
- Enhanced the smart reinstall script to fully delegate build processes to Turborepo, including cache management and dependency checks, ensuring a more efficient build workflow.
2026-02-19 16:33:43 -05:00