Document the trash and file versions, which shipped without their pages - #437
Merged
Merged
Conversation
cerede2000
pushed a commit
to cerede2000/NextExplorer
that referenced
this pull request
Sep 26, 2026
The batch is reversed, so its findings move from PORT to DONE in the same commit that sends them. What is left to reverse is whatever `scripts/parity.mjs` still reports.
added 6 commits
September 26, 2026 19:06
The About page's list of optional tools showed its own keys:
`settings.about.tools.title` where the heading belongs, and
`settings.about.tools.gives.videoThumbnails` under each one. The page was
ported with no catalogue entries at all, and nothing failed — the build
succeeded, the page rendered, and the words were missing. It is the one defect
a batch of screens can ship with while passing every other gate.
Twelve more keys were already in that state, on eleven screens: the Back
button on an account, the folder-size "Excluded" mark and its explanation, the
Access heading on both share lists, the branding page's note after choosing the
default logo, the empty user list, and six strings in the share dialog —
Password, Protected, Expires, Shared with, Creating, Loading users.
So a test reads every `t('…')` a screen asks for and holds it to the English
catalogue. English alone: a key missing from the others falls back to it, which
is a reader seeing the wrong language rather than a key. A prefix being built
up — `t('settings.categories.' + name)` — is not a key and is passed over,
which is also the limit of what can be checked from the source.
…t carry
Batch 33 of the plan was "the locale catalogues, with the key-parity test". The
catalogues are at parity on `main` today; nothing holds them there. The test that
was supposed to travel with them stayed in the fork, where it is a frontend spec
and there is no frontend runner here to execute it.
So it is written where the runner CI executes lives, reading the catalogues as
files. Three things, each the failure it prevents:
- **Every English key in every language.** A key added in English and nowhere
else falls back to English: a reader seeing the wrong language, quieter than a
raw key and just as wrong.
- **No key English does not define.** A key left behind after it was renamed in
English is dead weight nobody will ever see again.
- **The placeholders survive translation.** `{count} items` translated without
`{count}` says "items", with the number silently gone.
All three pass as things stand. Each was checked by breaking one catalogue — a key
removed from French, an invented key added to German, `{percent}` dropped from
Spanish — and each assertion named its own mutation and nothing else.
`auth.sessionSecret` fell back to `crypto.randomBytes(32)` whenever SESSION_SECRET was not set, and `configureSession` drew a second one of its own behind it. The sessions themselves survive a restart — they are rows in CACHE_DIR/sessions.db — but a cookie signed with the previous secret no longer verifies, so the row was read as a stranger's. Every restart, every upgrade and every crash asked everyone to sign in again, on the default configuration. The secrets derived from it went with it: ONLYOFFICE without ONLYOFFICE_SECRET, and the signed thumbnail links. So the first start draws one and keeps it in CONFIG_DIR, and later starts read it back. SESSION_SECRET still wins and nothing is written then. The file is written beside its final name and renamed into place, so a start interrupted half-way leaves either no file or a whole one, and it is created 0600 — nobody but the user the server runs as has business reading it. A CONFIG_DIR that cannot be written is not fatal: the start says, in words, that a secret is being used for this run only and that the next restart will sign everyone out, which is the behaviour it had all along. `configureSession` now takes the resolved value rather than drawing its own, so there is one secret and one place that decides it.
Node's default for a rejected promise with no listener is to raise it as an uncaught exception and stop the process. So one forgotten `await` anywhere — on a path check, a database read, a stat — answers a single bad request by taking the server down, and everybody else's work goes with it. That price is out of proportion to the cause. A rejection raised while serving a request is almost always confined to that request: the connection fails, and nothing else is touched. So it is reported, with what it was rejected with, and the server carries on. An uncaught exception is treated as what it is. There the stack unwound through code that had no chance to put anything back, so a lock may still be held and a transaction half applied; serving from that is worse than stopping. It shuts down — the ordinary cleanup first, so the store and the sweeps close as they would on SIGTERM — and exits 1. The shutdown runs in the same unknown state, so it is bounded: five seconds, or a failure of its own, and the process still ends. Nothing is hidden from development. Only `server.js` installs this; the test suites never load it, and the runner still fails a run that leaves an unhandled rejection behind.
`POST /api/files/office-document` and `createOfficeDocument` in the API layer both
landed with nothing calling them: there is no screen from which a blank Word,
Excel or PowerPoint document can be created, so the route cannot be reached.
The New menu gains a New document row, and a drawer beside it listing what can be
made — the three office formats when an editor is configured, and text, Markdown
and CSV, which are worth creating whether one is or not. A blank .docx is only
useful if something opens it, so the office entries are hidden when neither
ONLYOFFICE nor Collabora is set up.
Naming comes first here, unlike everywhere else in the app: the document opens
straight into an editor covering the whole window, so an inline rename box would
be behind it. The dialog shows the extension and does not let it be edited — the
format was chosen from the menu and the server owns the extension either way.
Once created, the document opens in the editor rather than landing back in the
listing, which would leave the person to find and open a file they have just
asked for by name.
Two defects in the files this touches, fixed here:
`createFile` in the file store read the created name from `created?.name`, where
the route answers `{ success, item }`. That was always undefined and always fell
back to the name asked for, so when that name was taken and the server picked the
next free one, the store looked up the asked-for name in the refreshed listing,
found the file that already held it, and opened the rename box on *that* — making
a second untitled file renamed the first one.
The button that opens the New menu sits outside the menu, so `onClickOutside`
counted its click as outside: the handler shut the menu in the capture phase and
the button's own toggle opened it again, and the button could open the menu but
never close it. It is now ignored by name.
The drawer is measured against the viewport each time it opens, and hands itself
to the other side when there is not room — a menu near the right edge would open
its drawer off-screen otherwise.
The plan's own rule is that a batch carries its documentation. The trash landed in nxzai#405 and nxzai#416, file versions in nxzai#406 and nxzai#417, and neither brought a page: there is nothing under `docs/` that describes either, so the retention settings, what a restore keeps, who sees what in the trash and how versions are thinned are all readable only in the source. Two new pages, and nine existing ones brought up to what the application now does — the environment reference gains the variables the last twenty batches added, the feature and workflow pages gain the trash, versions, archives and search index, and the sidebar gains the two new entries in both of its shapes. Both pages were trimmed to what `main` has, rather than copied. Three things are deliberately left out and travel with the batch that brings them: - restoring to a folder of your choosing. `POST /api/trash/restore` accepts a destination, but nothing on the screen offers one and `restoreTrashItems` does not send one, so the page would describe an action nobody can reach. - `COPY_PRESERVE_PERMISSIONS`, `PREVIEW_MAX_RENDER_SIZE`, `BULK_DELETE_CONCURRENCY`, `MAX_BROWSABLE_ARCHIVE_SIZE`, `ARCHIVE_CACHE_MAX_SIZE`, `UPLOAD_CHUNKED_AUTO_FALLBACK` and the six `PERFORMANCE_DIAGNOSTICS_*` — twelve rows for variables the configuration does not read yet. - recent destinations, per-folder preferences and the inline quick-actions menu. ## Checks `npm run docs:build` — and it is worth saying that it was failing before this last pass: three links pointed at an installation page that only exists in the fork, and vitepress treats a dead link as an error. Every internal link in the eleven pages was resolved against the tree, which is how those turned up. `npm run format:check` reports the same 22 files as `main` does on its own; the eleven pages and the config are clean. `npm run build` and the backend module load both pass, untouched by a documentation batch.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
P3-05 of phase 3 (see #373). Stacked on #433, #434, #435 and #436 — merge those first and this shrinks to the twelve documentation files it is about.
Two features shipped without their pages
The plan's own rule is that a batch carries its documentation. The trash landed in
#405 and #416, file versions in #406 and #417, and neither brought a page. Nothing
under
docs/describes either, so the retention settings, what a restore keeps, whosees what in the trash, and how versions are thinned are readable only in the source.
docs/admin/trash.mdanddocs/admin/versions.md, plus the two sidebar entries inboth of the config's shapes — a page nothing links to is a page that did not ship.
Nine pages brought up to what the application does
The environment reference gains the variables the last twenty batches added. The
feature and workflow pages gain the trash, versions, archive browsing and the search
index. The reverse-proxy, deployment, contributing and FAQ pages gain what changed
underneath them.
What is deliberately left out
Both new pages were trimmed to what
mainhas rather than copied, and three thingstravel with the batch that brings them:
POST /api/trash/restoreaccepts adestination, but nothing on the Trash screen offers one andrestoreTrashItemsdoes not send one. The page would describe an action nobody can reach, so the
section goes with the destination dialog (P3-17).
COPY_PRESERVE_PERMISSIONS,PREVIEW_MAX_RENDER_SIZE,BULK_DELETE_CONCURRENCY,MAX_BROWSABLE_ARCHIVE_SIZE,ARCHIVE_CACHE_MAX_SIZE,UPLOAD_CHUNKED_AUTO_FALLBACKand the sixPERFORMANCE_DIAGNOSTICS_*.the last of which you closed in Add a configurable inline quick-actions menu (off by default) #333 and which stays in the fork.
Checked mechanically: every
[…](/path)in the eleven pages resolved against thetree, and every
`VARIABLE`in the two new pages checked againstbackend/src. 147 variables documented, all of them read by this configuration.Checks
npm run docs:buildpasses — and it was failing before the last pass. Threelinks pointed at an installation page that exists only in the fork, and vitepress
treats a dead link as a build error. The link check above is what turned them up.
npm run format:checkreports the same 22 files asmaindoes on its own. Theeleven pages and the config are clean; the two pages prettier wanted to reformat in
passing were reverted, since they are not this batch's business.
npm run buildand the backend module load both pass, untouched.