A smooth kernel interpolates. On a photograph that is right; on a drawing it is destructive in a way
that shows up as SIZE rather than as blur — a logo with 174 flat colours downscaled with lanczos3
comes out with thousands of interpolated ones, and the lossless encoder that was winning a moment ago
then has to describe every one.
Measured on fofos-logo-saffron at 160 pixels, all lossless:
lanczos3 13,356 mitchell + nearLossless 7,982
mitchell 9,854 nearest 3,436
The whole 300-pixel original is 8,886. Every smooth option produced a 160-pixel file heavier than the
full-size one, which is what "the ladder made it worse" looks like from the inside.
The cost is real and accepted: nearest at a fractional scale drops rows rather than blending them, so
edges alias. These renditions are shown smaller than they are and the browser's own downscale smooths
what nearest left behind — a 160-pixel logo in an 80-pixel slot is where this lives.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
It probed at 96 pixels and got the answer wrong on exactly the file it was written for. Downscaling a
logo to 96 resamples its flat areas into gradients, so by the time the probe sees it, it already looks
like a photograph. Lossy wins that comparison, and the verdict is applied to every rung above — where
the flat areas are still flat and lossless would have won by a wide margin.
fofos-logo-saffron came out with a 13,074-byte 160-pixel rung and a 22,432-byte 256-pixel one, beside
a 9,144-byte 300-pixel original. Three files larger than the thing they were made from.
480 now, or the source's own width when it is smaller — which is the case that matters, because that
is what a logo is. Not the full size: a picture is still recognisably itself at 480, and probing a
4000x6000 photograph losslessly to learn something already obvious is minutes of encoding across a
library.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
160 was still not a floor. A logo renders at 80 CSS pixels, which is 140 device pixels on an ordinary
phone and 80 on a plain one, and the smallest rung being 160 meant the plain screen had nothing to
take but the retina file.
96 and 128 cost a few hundred bytes each and only exist for things this small — a logo, an icon, an
avatar. Every photograph in the library skips them, because nothing is ever upscaled and a rung wider
than the source is not written.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Lossy WebP is built for photographs — it discards detail the eye does not miss in something full of
texture. A logo is the opposite: flat areas, hard edges, a handful of colours. Encoding one lossily is
worse than useless twice over. It softens the edges, and it makes the file BIGGER, because flat
regions are exactly what lossless compression is good at and exactly what lossy encoding turns into
gradients it then has to describe.
Measured, not theorised: fofos-logo-saffron.png is 300x300 and produced a 22,432-byte 256x256 rung
beside a 9,144-byte full-size one. A smaller picture, two and a half times the file.
The decision is measured too. Every heuristic for this is wrong somewhere — a PNG can hold a
photograph, a JPEG can hold a diagram, plenty of logos are opaque — so it encodes the smallest rung
both ways and keeps the answer. One extra encode of a 160-pixel image per original, and what comes out
is not an opinion about the file: it is the file saying which encoder suits it. Applied to every rung,
because an image does not stop being a drawing at 640 pixels. Recorded in the manifest, because
somebody wondering why one directory is shaped differently should find the answer rather than
re-derive it.
Two other things the logos exposed:
The ladder had no floor. It started at 320 and a logo renders at 80, so fofos-logo-black got a single
12,350-byte rung against a 12,678-byte original — a ladder that saved 328 bytes. 160 and 256 are now
the bottom, and 128 and 192 on the square side.
And square crops of things already square. Both logos are 300x300, so their square rung cropped
nothing: the same image under a second name. The aspect ladder already produces squares for a square
source. 2% tolerance, because a 1000x1002 photograph is square for every purpose this serves.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
The hero declares a sizes well under its real width on phones so the browser stops multiplying by the
pixel ratio and asks for roughly one image pixel per screen pixel. 448 is the rung that lands on a
412-wide phone once that cap applies; without it the nearest was 512.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
The still is the input for three things — the placeholder, poster.webp, and now the poster rungs — and
it is removed once they are done. I added the rung loop BELOW the removal, so sharp was handed a path
that no longer existed and every video failed to convert.
The comment warning that these lines are ordered deliberately was three lines above the mistake.
The removal now sits after everything that reads it, which is where it should have been all along
rather than in the middle of the sequence.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
A poster was one file at the video's full size — 1280x720 for a hero displayed 412 CSS pixels wide.
Three times the pixels a phone can show, on the element that IS the page's Largest Contentful Paint,
which is the most expensive place on the site to be careless.
384, 512, 768, 1024, plus poster.webp as the widest rung. Those are viewport widths times the density
behind them: 412 at 1.75 wants 768, a tablet wants 768, a desktop wants 1280.
Cut from the still rather than from poster.webp, so each rung is scaled once from the original frame
instead of being a re-encode of an encode. poster.webp keeps its name — the placeholder is cut from
it, the site falls back to it, and a directory built before this has only that one.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
The ladder was 320, 480, 640, and the middle of that was the problem. A gallery slot measures 193 CSS
pixels on a phone, so at 1.75x it needs 338 device pixels — which did not exist, so the browser
correctly took 480 and downloaded 1.4x the pixels it could use.
Now 256, 384, 480, 640, 960, which is 193 and 475 CSS pixels times the densities people actually hold.
960 is the other end of the same mistake: the ladder stopped at 640, so a retina desktop wanting 950
took 640 and showed it soft.
A rung is a few kilobytes of square WebP. A missing rung is paid for on every visit by everyone whose
screen falls in the gap.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
A gallery grid is square slots and the ladder is the picture's own shape, so a 480x720 portrait
arrived, object-cover cropped it to 480x480 in the browser, and a third of every file was discarded
before anyone saw it. Measured here: 108,388 bytes shipped where a 480x480 crop is 70,070.
Cropping in the browser is the right default when the shape is unknown. It is the wrong one when the
shape is known at build time, and for a carousel of square thumbnails it always is.
Thumbnail widths only — 320, 480, 640. Anything larger is a picture being looked at, and a square crop
is a loss of information that only makes sense when the slot demands it.
Centre, never sharp's `attention`. Smart cropping decides differently for every picture, so a row of
thumbnails framed by an algorithm has no common logic to it and the one it gets wrong cannot be
predicted or explained. Centre is what a photographer framing for a square already assumes.
It is a default: a placement carrying its own crop keeps the aspect file and frames it in CSS, because
that crop is a person saying which part matters. Nothing here knows about placements, and should not.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Quality 82 went on every rung, so a picture 173 CSS pixels wide in a gallery grid carried the same
fidelity as the copy somebody opens full screen. Compression artefacts scale with display size: at
thumbnail size 74 is indistinguishable from 82 and 15% smaller — 108,388 bytes to 92,568 on the worst
image in this gallery, measured rather than assumed.
640 is the line because it is the widest rung a phone picks for a grid slot. Above it something is
showing the picture large, and 82 is the right answer again.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
The comment I added used backticks around ?v= and no-cache, inside a template literal. That closed the
string early and made the file unparseable — committed and deployed before the typecheck was read.
Caught by tsgo immediately afterwards; officer stayed online because pm2 kept the previous module
loaded, but the next restart would not have come back.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Seven days was correct while the URLs were bare: a stable name with a long life means somebody running
last week's script against this week's markup.
The site's layout now stamps every asset URL with the build's id, so a build that changes a file
changes its URL, and the HTML carrying those URLs is no-cache and revalidated every visit. The two
cannot disagree, which is what earns `immutable` and a year.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
The ladder went 320 then 640, and a phone lands between them. Lighthouse measured the home gallery's
slots at 454 device pixels; with only those two rungs the browser correctly took 640, which is a
184 KB file for a 454-pixel slot — and the same on every image in that carousel.
A rung is one more WebP beside files that already exist, chosen only when it fits better than its
neighbours. Not having it is paid for on every visit.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
It was reachable only when the SOURCE was smaller than 720, which is backwards: the rung a phone wants
is the one a 720p master never produces. The hero here is 1280x720 and the only file that existed for
it was 7.8 MB of 720p, served to every device.
`b:a` overrides the preset's 96k with 64k. The audio on a hero loop is ambience, and 64k AAC carries
it — the same argument as the preset's crf 26 for the picture. The rung exists for a phone on a mobile
connection and every kilobit is one it is paying for.
The override goes through av-club's documented contract: a preset supplies the options and anything
passed explicitly wins.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
TEMPORARY, and inert unless set. Bisecting a Performance score means a build between every
measurement, and rendering all 48 routes to change one of them is most of the wait.
FOFOS_BUILD_ONLY is passed through to the site's build script, which renders only the listed paths and
— the part that is not optional — skips the prune at the swap. The swap deletes anything in dist/ that
the run did not stage, so a one-page build would otherwise take every other page of the live site with
it, 404 until the next full build.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Everything sat at seven days, which Lighthouse counts as short for a file that never changes.
/fonts/ now gets a year and `immutable`. A typeface is not edited — it is replaced, and a replacement
arrives under a new name. It is the one directory here where a long life cannot pin something stale.
Everything else stays at a week deliberately. Those names are stable across builds and the HTML that
references them revalidates every time, so a longer life means somebody running last week's stylesheet
against this week's markup. Fingerprinted filenames are what would earn a year, and the build does not
write them.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
A photograph here is 189 KB of tufted yarn — high-frequency detail in every pixel, which is the worst
case for any lossy codec and not something a quality setting can fix. Re-encoding the same original
with ImageMagick at the same quality 82 gives 199 KB, so av-club is already slightly ahead of a
reference encoder. The 858 KB Lighthouse wants back is not available without softening the texture
the site exists to sell.
What was available was the wait. Each ladder now carries the picture at 16 pixels wide as a `data:`
URI inside its manifest — 300 to 500 bytes — and the site paints it as the image's own background. It
costs no request, which is the point: a placeholder you have to fetch is a smaller version of the
problem. When the real photograph arrives it paints over its own background and the placeholder is
gone, with no load handler, no class to remove and nothing to clean up if the script never ran. The
blur is the browser stretching 16 pixels across the box.
Videos take theirs from the poster still, before it is deleted — the same frame, so the two agree, and
sharp can read a JPEG where it cannot read an MP4.
── Existing directories are topped up, not rebuilt ──
The obvious move is to make `upToDate` insist on a placeholder, which turns all 62 ladders stale and
re-derives the library: minutes of CPU and 67 MB rewritten to add 400 bytes to each. Every rung in
them is already correct.
So `topUp` makes only the missing piece, and reads `320.webp` rather than the original — already
small, already browser-readable, already rotated. Going back to a 4000×6000 HEIC to produce a
16-pixel picture is the expensive half of a rebuild and precisely what this avoids. A directory with
no small rung is skipped rather than forced.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
`nginx:alpine` ships a config that serves the directory and does nothing else: no compression, and no
cache headers at all. Every asset on the live site carried a TTL of zero, so a returning visitor
re-downloaded all of it — 1.1 MB by Lighthouse's count.
Written out on every start rather than kept as a file somebody edits, so what nginx does is decided in
this file and cannot drift from it.
Three lifetimes, because there are three kinds of file. `derived/` renditions are rebuilt IN PLACE —
av-club replaces the contents of `1280.webp` rather than writing a new name — so they cannot be
`immutable` however much they look like they could be, or a re-crop stays invisible for a year to
everyone who saw the old one. Bundled assets change only when a build runs, and a build changes the
HTML that names them: a week. HTML revalidates every time, because anything longer makes a publish
invisible to whoever already visited, which is the one failure that makes the whole panel look broken.
`^~` on the prefix locations. A regex location beats a prefix location in nginx, so the extension rule
would otherwise capture /derived/…/1280.webp and give it the wrong lifetime.
Validated with `nginx -t` in the real image rather than by reading it.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
pg_dump warns that `service_nodes` carries a circular foreign key and that a --data-only dump of it
may not restore. Today the rows come out parents-first and it loads either way, but the previous shape
made that a load-bearing accident: truncate in one psql call, load in the next, so the day the
ordering changes the live site is left EMPTY until somebody notices and restores by hand.
Both statements now run as one transaction — TRUNCATE is transactional in Postgres — with foreign-key
checks off for the session. A failed load rolls the truncate back with it.
Verified against a scratch copy of production rather than reasoned about: a `create database ...
template fofos_website`, a deliberately failing load, and all nine rows still there afterwards. The
same copy confirmed what the real run will do — gallery and its nine items promoted, hero pointing at
the new file, and `users` and `contact_submissions` untouched at 2 and 8 rows.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
The admin edits development and the build renders production, so nothing written in the panel could
reach the live site. Build was only half of publishing, and the missing half was invisible: it
succeeded, against the content somebody last promoted, and a successful build of yesterday's site
reads as a broken renderer.
Publish copies the site's content tables across and then builds. Two things it will not copy: `users`,
because production's logins are not development's and nobody should be locked out of the live site to
publish a photograph; and `contact_submissions`, the legacy inbox, because development's is empty and
production's is not — copying it would destroy real messages in order to publish nothing.
The table list is written out rather than derived. A table added later should be considered rather
than swept along, and an empty development table quietly overwriting production-only data is
discovered far too late to fix.
Order is load-bearing in two places. Production is dumped before anything is destroyed, and the
publish refuses to start if that dump fails. Development is read BEFORE production is cleared, so a
failure to read leaves production untouched rather than empty for a reason that had nothing to do with
it. `TRUNCATE ... RESTART IDENTITY`, so the sequences the copy sets are not merely ahead of the rows
it inserts — otherwise the collision arrives on the client's next save, hours later, somewhere else.
`backupAfterPublish` has been sitting in backups.ts without a caller since the day "On publish" became
a backup schedule. This is the caller.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
`readdir` returns entries in the filesystem's own order — inode order on ext4 —
which is arbitrary and stable only until somebody moves a file.
Harmless for the sync, which does the same work whatever the order. Not harmless
for "Create Gallery": that list becomes the gallery's initial order, and nine
photographs arriving as 05, 08, 01, 07 reads as a bug even though nothing is
wrong.
`numeric` collation, so galeria2 sorts before galeria10 — which is what anybody
naming files that way means.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
The thumbnail comes from the DERIVED ladder, which is the point of the whole
pipeline: most of these are HEIC and a browser cannot display the original at
all. 320 is the smallest rung and still sharp at this size.
Served by this plugin from disk rather than by the site. The panel talks to the
plugin and the catch-all forwards everything to the site's /api/admin, which is a
different route — and more importantly, looking at a gallery should not require
the development server to be running. Editing the site is not the same as
reading it.
Not under /_config, because that prefix is owner-only and a thumbnail is not a
credential: a member who can open the section can see the pictures in it, which
is what the section is. Registered before the catch-all, or the catch-all would
forward it to fofos.
Path traversal is refused by resolving first and comparing against the directory
plus a separator — a bare startsWith accepts `derived-old` for a root of
`derived`.
An item whose conversion has not run has no rung, and the thumbnail hides rather
than showing a broken-image glyph, which reads as corrupt rather than pending.
Captions save on blur. A caption is a sentence somebody is in the middle of, and
a request per keystroke would be wasteful and a race with itself.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
`listOriginals` already includes the prefix in what it yields — it builds
`prefix/name` as it descends — so prefixing again produced
Home_Page_Gallery/Home_Page_Gallery/…, a real-looking path to nothing.
Found by calling the route rather than reading it.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
It stored the folder. What somebody right-clicks is a directory; what a gallery
holds is pictures — obvious the moment you look at the result, and not before.
Expanded by the server, because that side already knows which extensions are
media and how to walk the tree. It is the same `listOriginals` the sync uses, so
a gallery cannot end up holding a file the pipeline would never convert.
Recursive, deliberately: a folder of folders is still "these pictures", and
refusing to descend would silently miss most of what was pointed at.
An expansion that returns nothing creates nothing. Falling back to the folder
itself is exactly the bug being fixed, and doing it quietly is worse than doing
nothing.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
You should not have had to press Sync. Nine files moved into a folder and
nothing noticed.
Two gaps, and neither would have caught it. The platform's event bus emits
`files:uploaded` and `archive:extracted` — things Officer's own file browser
DID — so a move emits nothing at all, and neither would an rsync, a drop over
SMB, or anything done in a terminal. And no plugin subscribes to hooks anyway.
That is not a bug in the bus: it reports actions, and this needs to know about a
directory. So a filesystem watcher, the same shape as the mailbox one already
here.
The debounce is twenty seconds and long on purpose. A move of nine files is
dozens of events and an upload of two hundred is thousands, while a sync walks
the whole tree — so waiting for quiet means one run after the dust settles rather
than one per file. Being slightly late costs nothing, because the sync skips
everything already current; being eager costs a full walk per event.
It cannot feed itself: only originals/ is watched and the sync writes only to
derived/. Worth stating, because the opposite arrangement is a loop that looks
like a busy machine and nothing else.
A run already in flight is left alone rather than queued — it walks the tree when
it starts, and whatever lands after that is what the next quiet stretch is for.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Moving a file into a folder made the sync look at a new path, find nothing, and
convert it again — minutes of work to produce bytes that already existed a
directory away — while the old folder stayed behind forever, because nothing ever
deleted one.
A move preserves size and mtime, and both are already in the manifest and in the
stat. So the sync indexes what is already derived on that pair, and a file that
has moved has its ladder RENAMED across.
An ambiguous match is refused rather than guessed. Two originals can share a size
and an mtime — a camera dump can write a whole card in one second — and
rebuilding is merely slow where attaching the wrong photographs to a name is
wrong.
Orphans are removed afterwards, and only on a WHOLE-TREE sync. A scoped run knows
about one folder, so everything outside it looks abandoned; deleting on that
basis would take out the library the first time somebody re-synced a subfolder.
Safe otherwise because derived/ is reproducible by definition, which is what its
name has meant since these two folders stopped being called `user` and `treated`.
Both are counted, recorded in the ledger and shown only when they happened, so an
ordinary run stays one short line.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
`ready` was hardcoded false for as long as the sections proxied to an address
nobody could set — the connection form was removed and nothing replaced it, so
nine doors led to the same "not connected" message.
Both halves exist now and neither is typed by a person: the development server
runs on a port this plugin chose, holding a FOFOS_API_TOKEN this plugin
generated and handed it at start. So the credentials are DERIVED rather than
stored. Asking somebody to copy a value out of one part of this plugin into
another was never a setting, it was a chore.
Development and not production, and that is not a preference. Production is a
directory of files behind nginx — no API, no database, nothing listening — so
editing against it is impossible rather than merely wrong. Sections read and
write dev; Build is what publishes. An edit is visible immediately and public
only when somebody decides it should be.
The gate asks whether the server ANSWERS, not whether pm2 says online. `bun
--hot` survives a crash at startup: the process stays up, pm2 reports online,
and nothing is listening. Opening nine sections onto that would make one failed
boot look like nine broken screens.
And when /status itself cannot be reached, `configured` stays true while `ready`
goes false. Telling somebody they have set nothing up is alarming and wrong;
opening nine sections onto a server we could not confirm is answering is nine
screens that each fail separately. Cannot-tell keeps them shut and lets the next
poll open them.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
NPM runs in a container and crosses the docker bridge to reach host services;
ufw allows that subnet to named ports only. A development server on a port
nobody opened answers `curl 127.0.0.1` perfectly and is invisible to the proxy.
What that looks like is a browser timing out against a valid certificate, a
correct proxy host and a healthy process — with the cause written down in
exactly one place nobody thinks to read: nginx's own error log, "upstream timed
out while connecting to upstream: http://172.20.0.1:3011/". It cost an evening,
which is why this is code rather than a line in a README.
The panel is what chooses the port, so the panel is what opens it. A setting that
silently requires a second undocumented step elsewhere will be wrong most times
it is changed.
Opened BEFORE the process starts, so the port is reachable the moment it binds,
and idempotent by ufw's own behaviour — it runs on every start rather than only
the first, so a firewall reset repairs itself next time somebody presses Start.
Never fatal: a rule that could not be added is a line in the output and the
server still starts.
Closed when the port CHANGES, in savePorts, which is the only place that knows
both values. Not on stop — a stopped dev server is usually about to start again,
and a rule for a port nothing listens on grants nothing, while leaving it on
every change is how a firewall accumulates holes nobody remembers opening.
`sudo -n`, so a host without passwordless sudo fails rather than hanging on a
prompt nothing will answer. The port is an integer validated before it arrives
and every command is an argv array, so there is no shell and nothing to inject —
that is the whole boundary, and it is why the parameter is typed number rather
than read from a request.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
`bun run build:site` resolves the script from the package.json in the current
directory. The helper had no cwd parameter, so it ran in the platform's own
directory, which has no such script — and the error, "Script not found
build:site", reads as the site missing a script rather than as it being asked in
the wrong place.
Second time today a spawn helper quietly lacked something the caller needed: the
first was the environment for pm2. Both had the same shape — assembled correctly
and then not passed.
Verified by running the real build with the same environment the plugin builds:
29 entries in dist and an index.html with the site in it.
The site's own build script says it outright: "The public site is not served by
Bun in production — it is a directory of files behind nginx. Output: dist/."
So production has no port, nothing to restart, and nothing that can crash at
three in the morning. It is built or stale, and served or not served.
Showing it as a pm2 process was showing something that does not exist, and its
Start button could only ever have failed. It now has Build, Serve and Stop, and
the two states are reported separately — a build can succeed while nothing
serves it, and a container can serve a directory built weeks ago. They fail
independently and are fixed differently.
The container exists because nginx could not see the files. NPM mounts only its
own /data and /etc/letsencrypt, and there is no other nginx on the box. The
alternatives were putting site files inside NPM's own volume, or editing NPM's
compose and restarting it — which takes every site on this machine down for a
moment. So: one nginx:alpine, dist mounted READ-ONLY, on NPM's own network with
NO published port. NPM reaches it by name, and nothing about the site is exposed
except through the proxy.
Recreated rather than restarted, for the same reason pm2 is: a container keeps
the mounts it was created with, so a root location changed here would be saved,
displayed, and still serving the old directory.
Domains follows. Production's forward target is a container NAME, not the docker
gateway that reaches a host process — and matching what already points at it
uses the full target rather than the port, since every other site behind this
NPM on port 80 would otherwise be listed as fofos's.
The compiler found the dead branches this left in startServer once production
could no longer reach it. Removed rather than left to read as though the case
were still possible.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Without it, pm2 resurrects the list as it was the last time somebody happened to
run `pm2 save` — so a machine that reboots comes back without the site, and with
nothing to indicate anything was meant to be there. The systemd unit is enabled
on this host, so the resurrect definitely happens; the only question was what it
would restore.
After stopping too, not only after starting. The dump has to match reality in
both directions: a server stopped here and left in the dump comes back on its
own at the next reboot, which is the same bug pointing the other way.
A failed save does not fail the action — the process is already started or
stopped by then, and reporting "could not start" about something that did start
is worse than a line saying the list was not persisted. It is in the console
either way.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Three things, and the second is why the panel was confidently wrong.
The site refuses to start without FOFOS_API_TOKEN, ADMIN_SESSION_SECRET,
PUBLIC_URL, API_URL and FOFOS_MEDIA_DIR, and the checkout has no .env at all.
Every one of those is either already known here — the port, the media directory
— or a random secret nobody should be asked to invent. So they are generated
once, kept encrypted under this plugin's own purpose key, and supplied. Once,
not per start: regenerating would invalidate every session and token anybody had
noted down.
pm2 saying `online` is NOT the site being up. `bun --hot` survives a crash at
startup — the process stays alive, pm2 reports online, and nothing is listening.
That is precisely what development did: reported up, served nothing, and this
panel repeated it. The status now also asks whether the port answers, any
response counting, and says "not answering" out loud when the two disagree.
And the buttons are a fixed width, because Start and Restart are different
lengths and rows that size to their own label leave the inputs on different
vertical lines.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
pm2 for BOTH, development included. A `bun dev` started in a terminal dies with
the terminal, and nobody can tell whether it is running without finding the
window it was started in. Under pm2 the two are the same kind of thing — a named
process with a status, an uptime and a log, startable from here and inspectable
from anywhere. The cost is that development stops printing to a console somebody
is watching, which is what `pm2 logs fofos-dev` is for; the process names are in
the panel so nobody has to guess them.
This plugin owns exactly two names, `fofos-dev` and `fofos-prod`, and every
command is built from that pair and from nothing a caller supplies. No request
can stop, restart or delete another process on the machine. That matters more
than usual here: Officer's own processes share this pm2 daemon, and a plugin
able to name any of them would be a way to take the host down through a web
form.
Start is really a replace — delete, then start. Not `restart`: it fails on a
process that has never existed, and on one that has it reuses the environment it
was started with, so a port or database changed here would be saved, displayed,
and not in effect. That is an hour of somebody's debugging.
The environment is assembled here because this plugin is what knows the ports
and the database names, and it is handed to pm2 through the invoking command's
own environment — pm2 has no flag for it; `--env` names a block in an ecosystem
file. The site reads .env files first and the environment last, so this fills
what is absent rather than overriding what somebody wrote down.
Ports have no default. It is the one setting where a plausible guess is worst:
it binds, the site appears to work, and it is quietly answering on a port
another service wanted.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Two databases with identical structure look identical until you count what is in
them — one is the live site and one is a copy. So a row now reads "18 tables ·
155 rows" with the time anything was last written, rather than only reporting
that a schema exists.
Counted with query_to_xml over information_schema, which is exact. reltuples
from the planner would be free and is an ESTIMATE: it reads as zero on a table
nobody has analysed, which is precisely the freshly restored database this is
meant to reassure somebody about. That is not a hypothetical — it is why
pg_stat_user_tables reported an empty database earlier today that had 155 rows
in it.
And the block collapses with a check once everything is in order, on the same
terms as Root location: both databases existing with a schema, and backups
configured. Not backups having RUN — a site set up an hour ago has taken none,
and calling that incomplete is telling somebody to fix what is not broken.
Seeded from /summary so the first paint is already right, then kept live by what
the block and BackupsRow know. The `null` sentinel in `collapsed` is left alone
while unsettled, which is the bug that stopped Root location folding at all.
BackupsRow reports its bit from an EFFECT, not during render: calling the
parent's setter mid-render is an update to a different component, which React
refuses outright.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Messages are the one thing that happens between publishes. A backup triggered by
publishing would never contain them, and a RESTORE would destroy every message
received since the dump being restored — turning a routine recovery into losing
the only copy of something a stranger sent, with nothing about the operation
looking like it had done that.
So they live in their own SQLite file, in the shape Officer's email plugin
already uses. Not a schema that fits a contact form: this IS mail — a from, a
subject, a date and a body wearing a form — and storing it as a mailbox means
the mail client can open it, and anybody's agent already knows how to read it
without being told. The form's own fields become labelled lines in text_body,
where a reader and a grep both find them; inventing columns would be the moment
it stopped being a mailbox.
This side watches the file and copies it within seconds of a write, to the local
backup directory and to the machine off this one. The alternative is a window: a
message at ten past nine and a disk that fails at twenty past is a message
nobody sees, while the sender believes they contacted you.
Two details are the whole reason this is not a `cp`. The WAL is checkpointed
first — the site writes in WAL mode, so a new message lives in messages.db-wal
and not yet in messages.db, and copying the main file alone yields a database
that is intact, readable, and missing exactly the message that triggered the
copy. And the DIRECTORY is watched rather than the file, because SQLite replaces
files during a checkpoint and a watch on a replaced inode goes quiet for good —
a watcher that silently stops is worse than none, since the panel would go on
implying the inbox is protected.
The copy is current, not history; the ordinary backup runs take a timestamped
one alongside the dumps, so a restored site can have the inbox that matches it.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
A nightly backup of a site that only changes when somebody publishes spends most
of its life copying a database identical to yesterday's, and misses the one
moment worth capturing. So "On publish" joins the schedules, and goes first.
Stored in the same column as a cron expression because it answers the same
question — WHEN — and a second column would mean every read had to decide which
of the two was authoritative.
It creates no cron job and no catch-up tick. A missed run is a run whose TIME
passed while the machine was down; an event has no time, so there is nothing to
have missed, and a catch-up here would take a backup every fifteen minutes of a
site nobody had touched.
`backupAfterPublish()` does nothing unless this is the configured trigger, so
the publish path can call it unconditionally and never has to know what the
backup settings say. It swallows failures for the same reason the timer does: a
backup that could not be taken must not present as a publish that failed, when
the thing the person asked for worked.
Nothing calls it yet — there is no publish in this plugin, because the sections
that would do the publishing are not built.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
A pg_dump carries CREATE TABLE, so it cannot be layered onto a database that
already has the schema — it fails on every object. The only honest restore
empties the target first, and that is not a detail to bury behind a button. So
choosing a destination and confirming are two separate clicks, and the second
names what it is about to destroy.
`confirm` is required by the function, not merely by the panel, so no code path
can reach a restore by accident.
The file is matched against what listDumps actually found in the backup
directory rather than taken as given. There is no path to traverse out of and no
way to point psql at a file this module did not write: an unknown name is
refused before anything is opened, rather than sanitised and hoped about.
Emptied with DROP SCHEMA public CASCADE through psql, not by dropping the
DATABASE — that would need a connection to another one, fail while anything is
attached, and lose whatever was granted on it. Replacing the schema does the
same job to the part that matters.
psql rather than pg_restore, because these are plain-SQL dumps, which is what
pg_dump writes without -F c.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Requiring an absolute one was simply wrong. `scp file host:db-backups/fofos/`
lands under the remote account's home — that is what every ssh tool does, and
what anybody typing a destination expects, since the home directory is the one
place they are certain to be able to write.
What is still refused is unchanged and is the part that matters: the characters
a shell would act on. This value IS interpreted remotely, since `ssh host
mkdir -p <path>` runs through a shell, so they are rejected rather than escaped
— refusing is checkable by reading the function, escaping is checkable only by
being right about every shell.
The summary shows a relative destination as ~/… because that is where it lands.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Three things.
The local directory defaults to <officerdev root>/dockers/postgres/dumps,
derived from OFFICER_ROOT rather than written down — the same reasoning as
rootPath: a path fixed at install freezes the layout of the machine it was
installed on, and a restore elsewhere then points somewhere that is not there
while looking deliberately chosen.
The destination is SSH, and it is now what "set up" MEANS: a dump sitting on the
machine it came from is a second copy on one disk, lost to the same failure that
would make anybody want it. So local is staging and the copy off the box is the
backup, and a schedule with nowhere to send it does not count as configured.
Testable, in two steps reported separately, because they fail for different
reasons and the fixes differ: the connection is keys and networking, the
directory is permissions on the far side. It tests what is in the FORM rather
than what is stored — testing a saved destination while somebody looks at a
different one is worse than not testing.
Everything goes out with BatchMode=yes. Nobody is at a terminal when this runs,
so a key that has lost access must FAIL rather than block forever on a prompt
nothing will answer. It is also why no credential is stored: there is none to
store and none to leak.
The remote path is the one value here a shell interprets — `ssh host mkdir -p
<path>` runs through it — so shell characters are refused rather than escaped.
Refusing is checkable by reading it; escaping is checkable by being right about
every shell.
And rotation keeps the newest N per database at both ends. Per database, because
two sharing one budget means a busy one evicts the other's history. Sorted by
NAME rather than mtime: the timestamp is in the filename and is sortable, while
mtime stops meaning "when this was taken" the moment a file is copied.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Restore goes. What it would read from was never decided, and a disabled button
with a tooltip explaining it is not built is worse than no button.
In its place, backups. `cron` was already a dependency and used nowhere, so the
schedule is a real cron expression — a backup wants to happen at an HOUR, and an
interval counted from whenever somebody pressed save drifts across the clock
until it runs mid-afternoon.
Cron alone is not enough, and this is the part worth writing down: it does not
run a job it was down for. A daily backup at three on a machine that restarts
overnight is skipped silently — the schedule is still there, the next fire is
still in the future, and a month later there is one file. So `lastBackupAt` is
in the database, and both the startup and a fifteen-minute tick compare it
against the schedule's own period, computed from two successive fires. A backup
that should already have happened happens now.
The job handle is module-level and stopped before a new one is made. Two saves
leaving two jobs is a bug that surfaces as backups arriving in pairs, weeks
later, with nothing connecting it to a settings form.
Back up now exists because a scheduled job nobody has ever run by hand is a
guess — it is how you learn the location is writable and pg_dump can reach the
databases without waiting until three to find out it cannot. The list underneath
is a readdir of the location rather than a record of what should be there: a
schedule that has been failing quietly looks exactly like a working one until
you count the files.
pg_dump per database, not pg_dumpall — a cluster dump would also carry Officer's
own, which is not this plugin's to copy around. And a failed run still records
the timestamp, or one undumpable database would have the catch-up tick retrying
every fifteen minutes for the rest of the week.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Both names, on every push, whichever target it is. The site's guard checks that
the two environments expect DIFFERENT databases, so it needs both to do that at
all — and passing only the one being pushed to would leave the other falling
back to the name the repository shipped with, which is a comparison against
something nobody configured.
This makes the plugin the authority on what the site's databases are called,
which is the whole point of the change on the other side: the site stopped
hardcoding them.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
A text box invites an edit nobody is here to make. Named and created, the two
things somebody wants are per-database actions, so the inputs and the button go
and each database becomes a label, a table count, and what can be done to it.
Push schema runs the WEBSITE's own `db:push`. Not drizzle-kit driven from here
with a config this plugin assembles — the schema, the drizzle version and the
push command all belong to that repository, and reimplementing any of them would
be a second definition of the site's database going stale on its own schedule.
This supplies the connection and runs their script.
The connection goes in the environment, which works because src/env-file.ts
consults .env files first and process.env last. So an ambient value is used only
where no file in the checkout sets that key, and this cannot quietly override a
connection somebody wrote down.
Their name guard still applies and should: env.ts refuses to connect unless the
database name matches what FOFOS_ENV expects. A plugin that worked around that
would be defeating the one check standing between development and live data.
"Schema pushed" is a COUNT of tables in public, not a comparison against the
site's expected tables — that list would be a second copy of the site's schema,
stale the first time it gains a table, and the question being asked is only
whether anything is in there yet.
Restore is present and disabled, gated on the schema being pushed. It is not
wired: which backup it reads from is not decided, and guessing at the source of
a restore is not a thing to do with a client's data.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Two buttons was the wrong model, and it failed in the worst way: Create keyed
off the SAVED names, so on a fresh screen with both fields filled it did not
render at all — and the hint explaining why was behind the same condition. Two
filled fields, one Save, and nothing saying what came next.
Naming and creating are not separate decisions from the outside. You type two
names because you want two databases. So one button that records them and
creates whatever is missing, labelled with whichever of those it is about to do,
and disabled only when there is genuinely nothing to press.
The tick beside each field now asks pg_database about the text in the BOX rather
than the text last saved. That is the question somebody typing a name has, and
answering it about a different name was worse than silence.
The PUT that only stored names goes with the second button. Nothing called it,
and a second way to write the same two columns is a second thing that can drift.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Production and development, stored as NAMES rather than URLs. The site runs on
the same Postgres Officer is already connected to — that is the whole reason a
name is enough — and a URL here would be a second copy of a host, a port and a
credential that already exist in the platform's configuration, free to drift
from it and free to point at another machine.
Naming and creating are separate, and were worth two buttons. A database that
already exists still needs its name recorded, and making Create the only way to
save would leave nobody able to point the site at something already set up. The
tick beside each field comes from pg_database, not from what was typed — the
useful question is whether the thing exists, and that came apart from "somebody
saved a name" the moment the two actions split.
CREATE DATABASE cannot be parameterised, so the name goes into the statement as
text and the identifier check is the entire security boundary. It is therefore
strict rather than accommodating — lowercase, leading letter or underscore,
nothing else — and it is re-run immediately before the statement is built,
because the gap between storing a name and using it is exactly where a check
that happened earlier stops being a check. Postgres folds unquoted identifiers
to lowercase, so accepting `Fofos` would create `fofos` and then report a name
nobody could find; refusing is kinder than silently changing it.
Officer's own database and the Postgres templates are refused outright. Pointing
the site at Officer's database would not read as a configuration mistake — it
would read as the platform corrupting itself.
Nothing here drops a database, and nothing should: `fofos_website` and
`fofos_old` are one keystroke apart and one of them holds the client's site.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
It could not. Each part of Root location fetches its own status, so the block
had no way to know whether it was finished until its children had mounted and
reported — meaning it painted open and then folded away, on every load. That is
not a rendering problem to tune: the information genuinely was not there yet.
So one request answers the three bits first, and nothing renders until both it
and the path have arrived. The children still own their detail and still report
changes upward while the block is open; the summary only seeds the opening
state. Two sources for one fact with a clean division — the summary is what is
true on ARRIVAL, the callbacks are what changes while somebody is looking.
`settledNow` picks between them: the summary while nothing has reported, the
live value once anything has. Using the live value throughout would open the
block for exactly the gap between the summary landing and the children
answering, which is the flicker with extra steps.
The summary walks the media tree, so it is deliberately not polled, and it skips
the walk entirely when there is no media folder to walk.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Two things the panel could not answer. A run's state lives in a Map, so a
restart erased it — and with it any record that a file FAILED. That is the gap
the manifests structurally cannot cover: a derived folder records the size,
mtime and variants it was built from, so provenance is already precise, but a
file that did not build has no folder and leaves no trace. Once the watcher is
running, a failure at three in the morning would never be discovered.
So one JSON line per run, appended to media/.sync-log.jsonl. A file rather than
a table because db/schema.ts is emphatic that the connection is the only thing
this plugin stores, and a ledger is losable — re-run and it rebuilds. Beside
derived/ rather than inside it, so wiping derived does not erase the history of
what happened before, which is the comparison it exists for. Written in a
finally, so a run that died still records that it did.
And the line above the button now says what is TRUE rather than what a run once
did: reconcile() walks originals, reads each manifest, and reports current,
missing and changed. It uses upToDate — the same predicate the sync uses to skip
a file — because two definitions of "current" is how a panel comes to say
everything is in step while the next run rebuilds half of it. Missing and
changed are separated because only the second means somebody edited something.
The ledger is not polled. It reads the whole tree, so it loads on arrival and
again when a run stops — the only two moments its answer can change.
Sync also takes an optional folder now, so a subtree can be re-synced on its own
rather than the whole library. The scope is recorded on each run, because "3
built" means different things for one folder and for everything.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
`web-1080` was asked for whenever the source was at least 720 tall, so a 720p
video was upscaled to 1080p — the exact thing the image ladder is careful never
to do. The output was a 14.6 MB file that looks worse than the 7.8 MB one beside
it, and it cost 84 seconds of a single core on an idle box. Under a running sync
that overran av-club's 255 s idle timeout and homepage_video.mp4 failed
outright, which is the only reason the waste was noticed.
A rung is now made only when the source is at least that tall. `web-480` becomes
a floor rather than a rung, so a source smaller than 720 still gets something
instead of nothing or an enlargement. An unreadable height makes everything: a
probe that told us nothing is not evidence the video is small.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
A HEIC was being decoded once per rung. av-club is stateless per request, so
seven rungs asked for from the original are seven ImageMagick conversions of it
— measured on fofos at 8.5 s each, against 1.1 s for the resize and encode that
follow. Six of the seven produced a pixel-identical intermediate and threw it
away: about 67 seconds per photograph where 16 would do, paid again on every
future upload.
So when av-club says a format needs converting, convert it ONCE into the staging
directory and cut every rung from that. `needsConversion` is asked rather than
guessed, because which formats are expensive is av-club's fact and a list of
them kept here would go on paying after its build stopped needing it. JPEG and
PNG are untouched — writing a full-resolution intermediate to save six cheap
reads would cost more than it saved.
Concurrency drops to one. Two was chosen to match av-club and is the right
number on a machine with room; fofos has 1.87 GiB of RAM, and two concurrent
12-megapixel decodes left 520 MiB free with 648 MB already paged out. The work
is CPU-bound on a box already at 99%, so the second worker was not buying
throughput — it was buying a second resident bitmap.
And the sharp calls now name their output format properly. `output` takes
`{ format, options }`; passing `{ webp: { … } }` was silently ignored, so
everything built before this encoded at sharp's default quality rather than the
82 asked for.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
The mapping: derived/ mirrors originals/ directory for directory, and where
originals holds a FILE, derived holds a DIRECTORY of the same name — extension
included — with the renditions inside it. Keeping the extension is what makes it
total: a.jpg and a.png are different originals and must not share a folder. The
inverse is pure string work, so the filesystem is the record and there is no
second copy of the truth.
Images get a WebP ladder at 320/640/960/1280/1920/2560 plus full.webp, and
nothing is ever upscaled — a rung wider than the original would be a soft file
that srcset then confidently prefers over the sharp one. full.webp always
exists because for a HEIC it is the only browser-readable copy of the picture
there is.
Video gets av-club's web-1080 and web-720 presets by name, plus a poster. Images
are named by width because srcset descriptors are widths; video by height
because that is av-club's vocabulary and nobody misreads 1080.mp4.
The ladder is fixed here and the SITE chooses from it. This never reads
website/src/media/slots.ts — a plugin that knows a website's layout is a plugin
for one website, and that boundary is the difference between a template and
something fofos-shaped.
Each derived folder carries a manifest naming the size and mtime it was built
from, so the sync is idempotent and resumable: a run that died halfway is
finished by running it again. That is what makes an in-memory job acceptable
rather than merely convenient. It builds into <name>.partial and renames, so an
interruption can never leave a folder that looks finished.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
TWO REPORTS, AND THE SECOND ONE WAS A DESIGN MISTAKE RATHER THAN A SETTING.
Media is pinned now, beside Administration. it sat at the end of the scrolling list,
which is the bottom of the LIST and not the bottom of the panel. it belongs in the
foot for the same reason Administration does: both are about this machine, while
everything above them is about the site's pages.
and it was LOCKED BEHIND A CONNECTION IT NEVER USES. `ready` was one global flag —
"can anything be opened" — and Media is a folder on this disk that never speaks to
fofos. so sections now declare what they need:
'connection' the site's pages, which read fofos
'root' Media, which needs a folder and nothing else
'nothing' Administration, because locking the door you fix things through is
locking somebody out entirely
`sectionOpen` is one function, used by the nav to decide whether to offer a link and
by the detail panel to decide what to render — so the two cannot disagree about a
section. that was already the rule with one flag; it matters more now that each
section asks a different question.
`/status` gained `rootSet`, a BOOLEAN, and stays not-owner-only. the nav needs the
answer for every account that can see the section; the path itself stays behind
`/_config`, which is owner-only. whether a root has been chosen reveals nothing
about the machine — where it is would.
the empty-state line follows too: "set a root location below to begin" before there
is one, "connect fofos to open the rest" after — rather than one sentence naming a
step that is not the next one.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
pastilhasandClaude Opus 5