Done with `tea` as admin: plugins/offscale made public, plugins/example created
public, both verified anonymously over https — which is the check that matters,
because fetch.ts clones with no credentials and a private plugin simply cannot be
installed from the marketplace.
plugins/example 8 files, cloned back and diffed identical
plugins/offscale now public (was private, so was uninstallable)
`.gitignore` is one line now — `/plugins/*/`. The trailing slash is the whole
design: it ignores DIRECTORIES, so files at the top of plugins/ stay tracked. The
documentation about plugins belongs to the platform; the plugins do not.
All three are in the marketplace catalogue, which is what makes this reversible:
before this, untracking offscale meant a fresh install could never get it back.
Now the store is the way in for all three.
CatalogueEntry gains `icon` (a lucide name) alongside `iconUrl`. Both new entries
ship glyphs rather than artwork, and without it they drew the generic puzzle piece
in the store and their real icon after install — which reads as the icon changing
rather than the store not knowing it.
EXTRACTING-A-PLUGIN.md pointed at four directories a fresh checkout no longer has.
It now gives repository URLs, says up front that this directory holds documentation
rather than plugins, and carries a table of where each one went. Checked first that
no tracked source statically imports a plugin directory — none does, so a fresh
clone still builds.
tsgo clean, frontend builds, 787 pass / 7 fail (unchanged).
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Pushed to gitea.officer.dev/plugins/offscale (50 files, verified byte-identical
to the working copy by cloning it back), then untracked here.
Order matters and it was this way round deliberately: until that push, this
repository was the only copy of those 49 files. Untracking first would have left
them on one disk. The push is what made the removal safe, so it happened first
and was verified before anything was removed.
The files stay on disk and the installed plugin keeps working — this changes who
owns the code, not what is running.
`example` stays tracked, alone. It has no repository yet, and it is the reference
implementation EXTRACTING-A-PLUGIN.md sends people to read; removing it would
both delete it from everywhere but this disk and leave the doc pointing at
nothing. It follows once it has a remote.
Not done, and worth knowing before a fresh install: plugins/offscale is PRIVATE,
and fetch.ts clones anonymously over https with no credentials by design. So
offscale cannot be installed from the marketplace the way music can. It needs to
be public, or the marketplace needs authentication — which is a feature, not an
oversight to patch quietly.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
The previous commit's `git add -A` committed plugins/music as a gitlink (mode
160000) — a pointer to a commit in a repository this one does not contain.
Anyone cloning the platform would get an empty directory and a broken checkout
if they could not reach gitea.
That is not a slip to be careful about next time: it is the normal consequence
of the marketplace, which puts a clone with its own .git inside this tree on
every install. So it is ignored by rule rather than by discipline.
/plugins/*/ with the shipped ones re-included by name. Adding an in-tree plugin
is deliberate, so maintaining that list by hand is the right friction — an
unlisted directory in plugins/ is an install, not source.
Verified: music ignored, example and offscale still tracked with all their files.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Nothing applies these. There is no __drizzle_migrations table, `drizzle-kit
migrate` has never run here, and `bun db:push` diffs the schema code against
the live database directly — the schema code is the source of truth, as
src/databases/CLAUDE.md says twice.
The file was badly stale besides: 36 tables describing a schema from before
capabilities, api_keys, agent_panels, the app store and the plugin system
existed, including task_logs, terminal_containers and queue_jobs, which no
longer exist anywhere in the codebase.
Ignored rather than merely deleted, because `bun db:gen` reads src/schema.ts —
whose last line imports plugin-schemas.gen.ts, generated from the plugin
DIRECTORIES on whichever machine ran it. A committed migration would launder
per-machine plugin state into the repository: generate it here and history
gains music_* and offscale_*; generate it on a fresh clone and the next commit
deletes them again. Two developers would fight over that file forever.
Generating one locally to read a diff still works, and stays local.
── The history purge was tried and undone, deliberately ──
git-filter-repo removed the blobs from all 1326 commits, cleanly: 1848 files
became 1845, only the three migrations gone, every other blob byte-identical,
verified against a bundle.
It was reverted anyway. This codebase cites 76 commit SHAs as evidence —
totality.ts points at 2873948 for the 2026-08-06 websocket incident,
registry.ts at 044aacf4, CLAUDE.md at f35c145 for the /chat exemplar — and a
rewrite changes every one. They survived locally only through 1,328 replace
refs, which are local to one clone and fooled my own verification into
reporting the pre-rewrite commit as already clean.
Three stale files nobody reads in old commits are not worth 76 dangling
citations in a codebase whose documentation works by pointing at the commit
that proves the claim. Untracking gets the entire practical benefit: gone from
the tree, ignored forever, never regenerated into git.
Recorded so nobody spends the afternoon rediscovering it.
the last unwired step. install now generates a drizzle barrel of plugin schemas
and runs db:push, so a plugin with db/schema.ts brings its tables with it.
the barrel follows the plugin DIRECTORIES on disk, not the install table, and
that difference is the entire safety property. push drops what it cannot see, so
a barrel tracking installs would delete a plugin's tables the moment it was
uninstalled — turning "stop running this" into "delete my data", which is the
one thing the install model refuses to do. following the directory means:
directory present, not installed in the barrel, tables exist unused
installed in the barrel, tables in use
uninstalled STILL in the barrel, every row survives
directory deleted out of the barrel, a push may drop them
so reinstall is a restore, and losing data requires deliberately deleting a
plugin's source.
proved end to end rather than argued. with offscale uninstalled and its entry
removed from the barrel, db:push DROPPED headscale_servers. installing it
recreated the table in 1882ms — columns, both unique indexes including the
partial one that enforces a single active server, and the fk. a canary row then
survived an uninstall AND a subsequent manual db:push, which reported "No
changes detected".
it shells out to the same `bun db:push` a human runs rather than driving
drizzle-kit in-process: one definition of applying the schema instead of two
that can disagree, and an owner can reproduce exactly what an install did.
--force because the barrel only ever gains entries unless source is deleted, and
a prompt with no terminal would hang an install rather than fail it.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
three fixes to last night's build switch, all found by using it.
THE CSS. bunfig.toml declares the tailwind plugin under [serve.static], which
applies to bun's static SERVING — the html-import path the app used until
yesterday — and not to a programmatic Bun.build(). so the first build emitted
the xterm css and no tailwind at all: layout intact, every utility class
missing. a plugin list is not inherited from bunfig; it has to be passed. css
goes 110KB to 278KB, 1127 --tw- variables, .flex present, --color-duck present.
THE BUILD DIRECTORY. clearing it before building was meant to stop 20MB of
content-hashed chunks accumulating per install, and instead meant a FAILED build
left nothing — the exact opposite of the promise in the comment directly above
it. it was also a race: two builds overlapping had one process's rm delete the
other's shell, leaving js and css with no html and a 503 that read as a build
failure when the build had succeeded.
now it builds into build.next/ and swaps only a complete, successful build into
place, and refuses to swap one that produced no shell at all — a build can
report success and emit no html, and serving that is worse than serving the
previous one.
AND IT SAYS WHICH PATH IS SERVING. "is it serving the build I just made, or the
one bundled at import?" was answerable only by hiding the shell and watching for
a 503, which is how it got answered once. the distinction matters precisely
where it is hardest to see: the html import is fixed when the module graph
loads, so an install would rebuild build/ and serve something else entirely.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
the last piece. installing a plugin now brings its UI with it.
a bundler cannot follow import(runtimeString), so which plugins have a frontend
cannot be answered from the database at render time — it has to be written into
source first. Plugins.gen.tsx is that file: concrete imports, generated from
what is installed, gitignored because it describes THIS machine.
App.tsx keeps its core routes and gains one map. the wildcard hands the whole
subtree to the plugin's own router, which react-router nests natively.
serving moved to build/ in production. the html import is bundled once when the
module graph loads and can never change after, which is precisely why a plugin's
frontend needed a restart; Bun.build measures ~900ms for a 25MB bundle, so an
install can just rebuild. development keeps the html import, because that is
what gives HMR and bun --watch restarts on every source change anyway.
verified end to end against a running server, no restart at any point: install
regenerated the module, rebuilt the bundle (chunk hash changed), and the
plugin's own markup was in it; /example and /example/deeper both served; disable
took it back out of both the module and the bundle and 404'd the api; enable put
it back.
three things worth recording because they were found rather than reasoned:
the shell output is named after the ENTRYPOINT — index.gen.html, not index.html
— and naming: { entry: '[name].[ext]' } does not change it because [name] is
'index.gen'. found as a 503 on the first boot after the switch.
App.tsx already destructured a `plugins`, from useServerSettings — the DEAD
plugin system that scans a directory which does not exist and always returns [].
it silently shadowed the import. the new one is `installedPlugins` and says why.
seedAppRegistry takes plugin panels as an argument rather than importing them:
officerdev is a dependency of the shell, so importing upward would invert that.
756 pass, same 10 pre-existing failures.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Deleted all four — ecosystem.config.cjs, .light., .mac.light. and the
.profile. they derived from. The repository now contains no ecosystem file at
all, and .gitignore keeps it that way.
officer-setup writes one at the end, describing exactly the six processes a core
install runs: officer, officer-anthropic-proxy, officer-agent, officer-opencode,
officer-pty and officer-headscale. No profiles, no derivation, no plugins.
The four existed because a profile has to subtract from something, so the full
list had to name every plugin's process whether or not anybody installed it —
and a test then had to assert the two files still agreed. Generating one file
removes the subtraction, the second list and the test that policed them.
It is .cjs, not the .js PM2's docs use, and that is not a preference:
package.json declares "type": "module", so a .js file here is ESM and
`module.exports` throws. PM2 require()s the config.
Sections 10 (Services) and 11 (Verify) are built on top of it — write,
startOrRestart, save, optional boot hook, then check every process is online with
a sane restart count AND that the API actually answers on PORT. A process can be
`online` and serving nothing, so the port is asked directly rather than inferred.
That completes all eleven sections.
catalogue.test.ts required both deleted files at import, so it could not even
load. Its central assertion — "the store offers exactly what light leaves out" —
has no meaning without a full list to subtract from, which is the point of the
change. Replaced by two weaker but real checks: the store must not offer a core
process, and every process it names must have a sidecar directory to run. The
second catches the same typo the old one did without needing a manifest of
everything; verified it holds for all 15 catalogue entries.
app-store/pm2.ts starts a sidecar with `--only` against this file, which now
holds core alone — so it can stop a plugin but cannot start one that was never
written in. Marked `[open]` there rather than left to be discovered: appending a
plugin's entry is the plugin system's job.
Generated one in a scratch directory and required it with node: six apps, correct
cwd on each, valid CommonJS.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
The second half of the install, and a much smaller script than the original: of
the old setup.sh's thirteen sections, seven are machine-setup's job now and two
more were already removed. What is left is the repository, dependencies, the
database, .env, the schema, the build and pm2.
Pre-flight asks nothing on a normal run. machine-setup saves the account, the
Officer path and the role beside itself, and this reads the same file — so
machine-setup then officer-setup is two scripts and one set of answers. It
prompts only where that file is absent, which is a supported case rather than an
error: somebody may have provisioned the box their own way.
It then checks the machine is actually ready — git, node, bun and pm2 required,
docker optional — and reports all of them together with what each is for. Finding
out about a missing bun three sections in, after a repository has been cloned and
a database started, is a worse way to learn it. A missing required tool stops the
run and names machine-setup.
Found by running it: a remembered answer can go stale. My own earlier testing had
left SETUP_USERNAME=gitfresh in that file, for a throwaway account I then deleted,
and the run dead-ended on it. A remembered account that no longer exists is a
reason to ask again, not a reason to stop — so it is checked before it is
trusted, reported, and replaced.
Docker being absent is a warning rather than a failure: Postgres can be one you
already run, and the app store simply cannot provision until Docker is there.
Sections 2 to 9 are listed and not built.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
The --only flag worked, in that it reached the section — but reaching it meant
answering four pre-flight questions first, every time, which is not usable for
working on one section. The same problem was already there without --only: a
resumed run re-asked the role, the account and the Officer path that it had been
told on the previous pass.
Answers are saved beside the progress file and loaded before anything is asked.
The environment still wins over what was saved, so SETUP_USERNAME=x on the
command line overrides it, and --reask throws the file away and asks again.
Read as assignments rather than sourced. The file sits next to the script and is
read by a run that is already root; sourcing it would make it executable content
in a place nothing guards.
Second run now goes straight through pre-flight, printing what it remembered, to
the one step asked for.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
A WIP boundary after section 2 so the finished part can be run start to finish
on its own, without the untouched sections below acting on the machine. It moves
down as each section is worked through and goes away when the walk ends.
Also ignores .setup-progress, which the script writes beside itself and is
per-machine. The exit message names it, because with it in place a second run
skips section 2 and the rewritten part cannot be re-felt from scratch.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Real PNG icons are coming, so this is the path they arrive by: a sidecar ships its assets beside its own
code, and install copies them to public/plugins/<id>/ where one static route serves them.
Copied rather than served in place because a sidecar shipping from its own repository has its assets
wherever that repository was unpacked, which is not a path the web server can be taught at build time.
One predictable destination means the serving rule never has to know how many plugins exist or where any
came from. It also makes assets a property of the INSTALL: uninstall removes them, and a plugin nobody
installed serves nothing.
Needed a new route, and the reason is a trap worth recording. `publicRoutes` in server.tsx is built by
globbing ./public at BOOT, so anything copied there afterwards is invisible to it — the first install of
a plugin would show a broken image until the server was restarted, and "install it, then restart to see
the icon" is not an install. `/plugins/*` resolves per request, like /novnc/* and /vendor/* already do.
Unlike those two it answers 404 rather than 500 for a missing file: an unpublished icon is an ordinary
state on a fresh machine, and a 500 would put a red line in the log for every dock render.
Proven end to end with a real asset: slskd's icon moved from public/slskd.png into the sidecar's own
assets/, published against an ALREADY RUNNING server, and fetched at 200 with the right bytes and
content-type — 404 before publishing, no restart between.
public/plugins/ is gitignored: it holds copies, and the originals live with each sidecar.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
git add -A swept up a throwaway verification script. it held no key material —
it read addresses from a file outside the repo — but it had no business being
committed. ignoring *.tmp.ts so the next one cannot repeat it.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
index.html hardcoded the deployment's domain in eight places, so every instance
had to carry its own edit of the file — the only thing separating the rezio
branch from master.
The tags genuinely need absolute URLs. OpenGraph is fetched standalone by
crawlers, and Bun's HTML bundler treats a root-relative href as an asset to
resolve on disk, failing the build with "Could not resolve: /favicon.ico" —
external URLs are the only form it passes through untouched.
Bun's HTML import offers no substitution hook, so scripts/gen-index.ts swaps
__PUBLIC_URL__ for the value in .env and writes index.gen.html, which the server
imports. index.html is the tracked template and is now identical on every
deployment; index.gen.html is gitignored. predev/prestart run the generator, and
it is idempotent so --watch does not loop.
Substituting also fixes the manifest: an absolute URL puts its fetch in CORS
mode, which failed whenever the hardcoded domain was not the serving origin.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
pastilhasandClaude Opus 5