2e8ec845c8c7fd0f8923145c144fc7349e271420
1328
Commits
| Author | SHA1 | Message | Date | |
|---|---|---|---|---|
 pastilhas
|
2e8ec845c8 |
step 1/4: the permission engine is called permissions, not capabilities
The word meant four different things in this repo, not the three the offscale
doc records:
1. the permission registry → RENAMED here
2. $OFFICER_ROOT/capabilities/ items → kept; this is what capabilities are
3. sidecar routing keys → step 3, becoming `handles`
4. Lightning wallet features → kept; a domain term, and on the wire
to the mobile apps
The fourth was not in the doc and a global find-and-replace would have broken
the mobile wallet, which reads `{ kind, capabilities: Capability[] }` from the
wallet sidecar. So this renamed against an explicit file allowlist rather than
by sweeping the tree, and `CapabilityPage.tsx` — the UI for the item store, and
correctly named already — was left alone.
Moved: servers/capabilities/ → servers/permissions/, capability-gate.ts →
permission-gate.ts, users/capabilities-routes.ts → permissions-routes.ts,
hooks/useCapabilities.ts → usePermissions.ts. Identifiers follow.
Three breaks the typechecker could not see, all found by exercising it live.
The route paths moved with the prose sweep, so the server served
/user/permissions while the frontend still called /user/capabilities. A 404 on
every page load, and tsgo clean throughout.
The response FIELD moved too. `client.get<SelfPermissions>()` is an unchecked
cast, so `data.capabilities` became `undefined` at runtime with no compile
error — `can()` would have answered "no" to everything and the dock would have
emptied itself.
And the grants list was passed straight out of the database, so it arrived as
`{ role, capability, level }` while the screen read `grant.permission`. Every
role would have rendered as holding nothing. It is now mapped in the route:
the wire says `permission`, the column still says `capability`, and step 2
therefore changes nothing any client can see.
The stale react-query keys were the quiet one: two files still invalidated
['self-capabilities'] after the hook moved to ['self-permissions'], so
installing a plugin would have silently stopped refreshing the dock.
The database is untouched — `role_capabilities` and its `capability` column are
step 2, and the two call sites that cross that boundary say so in a comment.
Round-tripped the 9 live grants through the admin endpoint to prove the PUT
contract survived: 9 before, 9 after, Member's three intact.
Also reverted prettier churn on five landing-page files that a broad --write
picked up. Second time today; the lesson is not sticking.
tsgo clean. 797 tests, 787 pass, same 7 pre-existing failures — two of which
now read "path → permission" rather than "path → capability".
|
||
|
pastilhas
|
b0fcd8b81b |
stop tracking generated migrations, and delete the stale one
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 |
||
|
pastilhas
|
9b1c0a75b2 |
a dock tile can be bare, so artwork is not framed in a swatch
The tile background exists so a white lucide glyph has something to sit on — on nothing it is invisible. Artwork does not need it, and a logo framed in an arbitrary coloured square reads as a mistake. badge rounded square filled with `color`, icon inset (what a glyph needs) bare no background, artwork fills the tile (what a mark wants) DEFAULTED from whether the plugin ships assets/icon.png — artwork gets bare, a glyph gets badge — with `tile` on the manifest to override either way. Presence is the declaration, as everywhere else here; the field exists only for the plugin whose artwork genuinely wants a backdrop. Music sets nothing and gets bare. `color` is still required either way. It does four jobs and only one of them is the square: the active glow, the indicator dot and the plugins-list tint all read it too. The icon was also smaller than it looked. The source carried ~8% transparent margin on every side and the artwork is 233x221 inside a square frame, so with the old `h-7 w-7` inset inside a `w-10` box the duck occupied roughly 39% of the tile's area. Cropped to its alpha bounding box, padded back to square to keep aspect, and rescaled: it now fills 95% of the frame instead of 79%, and `bare` gives it the whole tile instead of half. Measured rather than eyeballed — the bounding box came from extracting the alpha plane and scanning it, then the crop was applied to the 1254px original so nothing was resampled twice. tsgo clean, 797 tests, 787 pass, same 7. Verified live: music reports tile=bare, example and offscale still badge. |
||
|
pastilhas
|
f78abbe05a |
a plugin ships its own dock icon as a file, not a lucide name
The manifest's `icon` was a lucide NAME, resolved by `resolveIcon` — which knows 106 glyphs out of lucide's ~1,500. A plugin naming one outside that set silently rendered a neutral box, and a plugin from a marketplace had no way to see the ceiling coming. So the icon is a FILE now: `plugins/<name>/assets/icon.png`, discovered by presence like everything else here. `manifest.icon` stays as an optional fallback for a plugin with no artwork — example and offscale still use it — and the file wins when both exist. No new mechanism was needed. The app store already published sidecar assets: `<dir>/assets/` → `public/plugins/<id>/`, served by a dynamic `/plugins/*` route, with `DockItem.image` rendering an <img>. `pluginDockManifests()` simply never emitted `image`. Install now publishes and uninstall unpublishes — the one thing uninstall is allowed to delete, because these are copies whose originals are still in the plugin's source. Base64 in the manifest was considered and dropped. It would ride in every /api/user/capabilities response for every user on every page load, can't be cached separately, and puts a 5KB string literal in a source file — against the rule this manifest keeps: what a directory listing can say, it says. It also needs no support: `image` goes straight into <img src>, so a data: URL already works for anyone who wants one. Music ships OffMusic.png, resized 1254² → 256² (1.6MB → 108KB) with alpha intact, sized for 3× DPI at the dock's 32px render. It also drops `icon` — the artwork is a voxel duck in headphones, not a glyph. The plugins page showed a generic Puzzle for every plugin; the list and detail header now show the plugin's own icon when it has one. Two bugs found while testing. Dock.tsx imported 26 lucide icons and used 14. The twelve dead ones — Music, Bitcoin, Receipt, Images, CalendarDays, Contact, Clapperboard, Mail, Network, ArrowDownUp, FileText, FolderKanban, MonitorSmartphone — were residue from when every feature had a hardcoded tile. Deleted. And uninstalling a plugin left its icon URL answering 500, not 404. server.tsx globs ./public at BOOT into one exact route per file, each holding a Bun.file handle, spread into the route table AHEAD of the /plugins/* wildcard. So an icon present at boot got an exact route that outlived the file, returning ENOENT on every dock render with the error logged each time — exactly what the wildcard's own comment says it exists to prevent. The comment covered the ADD case; this is its mirror. `plugins/` is now excluded from the boot glob, so the wildcard owns that prefix alone. Verified: 200 installed, 404 uninstalled, 200 reinstalled. [open] A plugin's icon cannot be seen BEFORE installing it, which is the one place an app store most wants to — assets are published at install by design, and an authenticated icon route is no use to an <img>. |
||
|
pastilhas
|
e11e0b6475 |
one port announcement instead of sixteen, so a plugin can name itself
protocol.ts declared a separate SidecarEvent member per sidecar — music, vault,
slskd, headscale, transmission, invoiceshelf, jellyfin, photos, memos, gitea,
caldav, wallet, pty, email, notify, opencode — each an identical one-liner. Two
of them were for plugins that had already left the repository, which is the
tell: the platform was declaring event types on behalf of code it no longer
contains.
The cost was that a plugin could not announce its own port. `connection.send`
takes a SidecarEvent, so `{ type: 'notes:server', port }` did not typecheck
until someone added a line to the platform. A third-party plugin needed a pull
request against Officer before its sidecar would compile — for the one message
every HTTP sidecar has to send.
Now:
export type SidecarPortAnnouncement = { type: `${string}:server`; port: number };
Nothing was lost at the point of use. The only consumer is
`sidecar.on(`${name}:server`, …)` in create-proxy.ts, which already cast to
read `.port`, because a handler typed `(event: SidecarEvent) => void` cannot
narrow from a computed template string.
The proof is a test that already existed: create-proxy.test.ts announces
`testcar:server` — a name never in the union — and now compiles without its
`as never`.
Removing the two casts that escaped the old type found something else. They
were not hiding union membership, they were hiding `port: number | undefined`:
Bun types Server.port as optional because a unix-socket server has none. So
`as SidecarEvent` on the whole object was suppressing a real nullability
warning, and would have suppressed a genuinely wrong event shape too. Replaced
with a narrow assertion on the port alone. Two further `as SidecarEvent` casts
in the same file turned out to be unnecessary altogether and are gone.
[open] The typo check is genuinely gone: a sidecar sending `muzik:server` while
its proxy listens for `music:server` now compiles, and the symptom is every
request answering 503 forever. The fix is not to restore the list — it is for
createSidecarConnector to announce the port itself from the `name` it already
holds, so the string is written once and the typo becomes unrepresentable.
Recorded in protocol.ts.
Verified live: officer and officer-music restarted, `[music] sidecar registered
on port 38803`, /api/music/manifest and /api/offscale/_health both 200.
tsgo clean, 797 tests, 787 pass, same 7.
|
||
|
pastilhas
|
0a55964db5 |
the player moves to the plugin, and src/ has no music code left
officerdev/src/MusicPlayer/ → plugins/music/web/. Engine, state, bar, favourites, lyrics toggle and the library vocabulary — ten files. The barrel stops exporting a player it no longer has, and DashboardLayout stops rendering one. The reasoning that kept it was removed rather than refuted. It stayed because the dashboard widget imported useMusicPlayer from officerdev and the platform cannot import from a plugin, so the state had to stay whatever was decided about the UI. The owner moved the widget into the plugin in the previous commit, and the constraint went with it: the whole remaining dependency became one line, DashboardLayout.tsx:66. MusicPlayerHost is mounted inside the MusicDetail panel. That reads odd until you notice it already returned null on /music — the mini bar is the transport there, and the host existed purely to own the GaplessEngine. In the panel it does exactly that, and the bar code stays intact for whenever there is a slot. [phase 2] Leaving /music unmounts the host and playback stops. Deferred on the owner's call; the bar was "navigating away must not break the application", and that holds: seekPlayer is optional-chained so a call with no host registered is a no-op, registerPlayerSeek clears only its own registration, the host's cleanup destroys the engine and nulls its ref, and the queue is global state so returning to /music remounts and reloads. Solving it properly needs either a shell slot a plugin can contribute to — which reopens "there is no way to export a component" — or the engine hoisted to module scope, which keeps the rule and loses only the off-route controls. Also: the parked widget now imports the player as a sibling rather than through officerdev, and shared.ts stopped being a re-export shim now that the real file is in the plugin. Verified: tsgo clean, 797 tests / 787 pass / same 7. Server restarts, mounts /example /music /offscale, / and /music both 200, and the player is in the built bundle (music.volume, music:lyrics, now-playing?device=web all present — GaplessEngine is a class name and the production build is minified, so grepping for it proves nothing). Not verified by me: what it looks like in a browser. That needs your eyes. |
||
|
pastilhas
|
f1bd75853d |
the music widget moves into the plugin, parked like cliamp
src/workspaces/widgets/MusicPlayer/ → plugins/music/widgets/, its export dropped from the widgets package, and its registration removed from WidgetRegistry. Plugins cannot contribute widgets and that mechanism is not being invented now, so it is parked next to cliamp rather than left in a workspace package the platform ships. `../Widget` became `widgets/Widget` — the sibling import turned into that package's declared export, which it already had. This removes the last non-plugin consumer of officerdev/src/MusicPlayer, and that matters more than the move. The argument for keeping the player in the platform was that the widget imported useMusicPlayer and PlayerTrack from officerdev, and the platform cannot import from a plugin — so the player STATE had to stay whatever was decided about the UI, and the engine stayed with the state. That constraint is now gone. The complete remaining platform dependency on the player is one line: DashboardLayout.tsx:66, `<MusicPlayerHost />`. So the seam is no longer "the widget pins it". It is purely the global overlay question, which is a platform gap about plugins owning a render slot outside <Routes> — the same shape as plugins owning a websocket. Recorded rather than acted on; the decision is the owner's and the previous reasoning for it no longer holds. bunx tsgo clean. 797 tests, 787 pass, same 7 pre-existing failures. |
||
|
pastilhas
|
9af52fd754 |
db:push regenerates the plugin schema barrel, so setup works on a clean machine
`officer_db/src/schema.ts` ends with an UNCONDITIONAL `export * from './plugin-schemas.gen'`. That file is gitignored — it describes this machine, not the project — and until now its only writer was installPlugin. So on a fresh clone the file does not exist and `bun db:push` dies with MODULE_NOT_FOUND before creating a single table. That is exactly what officer-setup.sh section 8 runs, so setup failed at the schema step on any clean machine, and the only thing that would have written the file was installing a plugin — which needs a working database. A deadlock, shipped with the plugin system on 2026-08-15. Reproduced by deleting the file and running push, not inferred. `db:push` now runs scripts/gen-plugin-schemas.ts first. Wired into the script rather than added as a setup step because setup is not the only caller: pushSchema() shells out to the same command, a developer types it by hand, and `git clean -xfd` removes the file at any time. A step someone has to remember is one they forget once; push regenerating it means the barrel cannot be stale when drizzle reads it. Both paths verified: barrel deleted then push (regenerates, "No changes detected"), and zero plugins on disk (writes a header-only barrel that schema.ts still imports cleanly). Also verified, on a scratch database, the premise the whole barrel design rests on — that push drops what it cannot see. Full schema pushed, a row seeded into music_favorites, then an empty barrel pushed: music_* and headscale_servers were DROPPED along with the row. So "following the directory rather than the install table" is load-bearing, not decorative. Worth recording how close that came to being logged as the opposite. An earlier run with an empty barrel reported "No changes detected", which read as evidence that push does not drop. It was this fix working — the script had regenerated the barrel before drizzle ran. The scratch database is what told them apart. bunx tsgo clean. 797 tests, 787 pass, same 7 pre-existing failures. Scratch database dropped; live plugin tables and rows verified intact. |
||
|
pastilhas
|
1e79b4effd |
revert prettier churn on four files the cliamp move never touched
I ran `bunx prettier --write` over whole directories instead of the files I edited, so FileViewContainer, SelectionActions, usePipelineRunner and Providers got rewrapped into a diff about cliamp. Pure whitespace, zero behaviour, and exactly what CLAUDE.md warns about — unexplained churn in someone else's file. Worth noting what it revealed rather than just undoing it: those four were not prettier-clean to begin with, so `bun format` on a clean tree would rewrite them too. That is a pre-existing inconsistency, not mine to fix in this commit. bunx tsgo clean. |
||
|
pastilhas
|
a9bf51407e |
cliamp moves into the plugin, and the platform loses its last music file
The owner read the code and asked why `plugins/music/api/router.ts` was three
lines importing `@@/api/music/router` — platform code that knows the string
'music'. He was right, and tracing it found the justification was hollow.
The chain: server.tsx:20 imported the cliamp relay's two exports, which are
used only on commented-out lines; so the relay's functions were never invoked;
so its call to getMusicServerWsUrl never ran; and the file's other export,
getMusicServerUrl, had no consumers at all. A dead import held a music-named
file in the platform, and I documented that as a "seam" last night after
checking the import existed and stopping there.
Everything cliamp now lives in plugins/music/cliamp/:
sidecar/music/{cliamp-ws,pulse-audio}.ts, asoundrc, the test
api/cliamp/relay.ts
apps/FileBrowser/{CliampPanel,AudioStreamPlayer}.tsx
src/servers/sidecar/music/, src/servers/api/cliamp/ and src/servers/api/music/
are gone. server.tsx has no cliamp import, provider name, handler entry or
route. The platform contains no file named for music or cliamp.
Two of the things that moved were live, not inert.
The file browser's `Play` context-menu item, on any audio file or folder, set
?play= and rendered a cliamp terminal pointed at /api/cliamp/ws — a route that
upgraded into a handlers entry that was commented out, so handlers[provider]!
asserted non-null on undefined. Using that menu item crashed the socket
handler. Removed: the action, the layout, the panel wiring and both menu
entries. Verified the routes now 404 rather than crash.
That closed the totality drift as a side effect. server.tsx's route table and
its handlers map agree again for the first time since 2026-08-13, and
registry.test.ts now asserts it rather than pinning the hole.
The proxy is built in the plugin now, and its prefix is DERIVED. It was the
literal '/api/music', which the proxy uses to strip characters off the path —
correct only because mountPrefix returns /music for a first-party publisher.
The same plugin published by anyone else mounts at /api/p/<publisher>/music and
would have forwarded /alice/music/stream to a sidecar expecting /stream. A
latent bug only third parties would ever hit, and a quiet violation of the rule
that mountPrefix is the one function allowed to know about provenance. Offscale
has the identical hardcode and still needs it.
Still open there: appName is passed as a literal, because a plugin's router
cannot see its own directory name — the platform imports the module and reads
`router`, so there is nowhere to inject it. The fix is a factory the installer
calls with the plugin's identity.
Plugin backend coupling is down to 7 imports, all of them "a plugin talks to
its host": data-path, sidecar/connect, sidecar/protocol, officer-url, the
manifest type, officerdb/db and the users.id FK. Nothing music-shaped left.
bunx tsgo clean. 797 tests, 787 pass, same 7 pre-existing failures. Verified
live: manifest 200, favorites 200, stream 206, /api/cliamp/ws 404.
|
||
|
pastilhas
|
8bfcd40bd2 |
music's library browser depends on another plugin's permission, not just its own
MusicBrowser lists folders with GET /file-browser/ls rather than through the music sidecar. /file-browser belongs to `files`, which is `confined` — so a member granted `music` and not `files` gets a working player, working favourites and an empty library, and `files` is not a grant that can simply be handed over, since authorize.ts drops a confined grant for an account with no Linux user. First cross-plugin PERMISSION dependency in the system, and a different animal from offscale's. That one is ConsoleView → TerminalView: code, resolved at build time, worst case a plugin that will not compile. This resolves at request time, per account, and fails as a screen that renders perfectly and shows nothing. Three shapes written down, none chosen. Moving the listing into the sidecar is probably right — it is the same rule offscale follows, that the sidecar absorbs everything — but it is tomorrow's call. Recorded now rather than trusted to memory: it was found by reading, after the extraction was already verified and pushed, so nothing was going to surface it again on its own. |
||
|
pastilhas
|
e930586878 |
plugins declare the host binaries they need, and the installer checks
Offscale was self-sufficient. Music is not — it shells out to ffmpeg and ffprobe — and the way it fails without them is the reason this is a check rather than a line in a README. It does not fail. Missing ffprobe means the indexer catches the spawn error and returns a track carrying its filename and nothing else: no title, artist, album, duration or embedded lyrics. It then walks the whole library, writes a complete cache tree and reports success. Five swallowed catches, no log, no counter, and the only tell is coversSaved: 0 in a report nobody reads. So `osDependencies` is a manifest field: the binary to probe on PATH, why it is needed, and a package name per package manager. The shape is taken from scripts/setup-old/setup.sh rather than invented — probe the binary, case on $PM — and the names are per-manager rather than canonical-with-overrides because lib/packages.sh already recorded why that indirection was rejected. Probing the binary is what makes "built-in on this OS" free: on PATH means the package map is never consulted. Four decisions worth naming. Missing and uninstallable REFUSES the install, first, before a table is created or a row written — so there is nothing to undo, and the alternative is a plugin that installs, answers 200 and quietly produces nothing. The status is on GET /api/plugins and rendered before the button, because the owner is deciding whether to let the server run a package manager as root and that needs answering first. Installing by hand and watching it flip to present is the escape hatch on a machine without passwordless sudo. Package names get a deliberately narrow regex and reach Bun.spawn as an argv ARRAY, never a shell. Both halves are load-bearing: the regex means a metacharacter cannot get there, argv means it would be an argument rather than syntax if it did. Narrower than package managers actually accept — no `:`, no `+` version pins — because a plugin needing one wants a conversation. Success is OBSERVED, not inferred: after installing, the binaries are re-probed. A package manager exiting 0 having installed something that does not provide the binary is exactly the failure this exists to catch. installCommand mirrors lib/packages.sh's pkg_install_now exactly, including apt's non-interactive environment, so there is one definition of "install a package" rather than two that drift. sudo always gets -n: under PM2 a password prompt is not a slow path, it is a hang. brew never escalates. Verified live. ffmpeg and ffprobe were absent on this machine all evening; the page showed both missing with the exact root command, the install streamed `dependencies: installing ffmpeg with apt` then `ffprobe, ffmpeg now on PATH`, and X-Audio-Duration appeared on a stream response for the first time. The refusal path was exercised against a temporary probe dependency: HTTP 400, steps: [], reason named. THIS CHANGED THE MACHINE: ffmpeg 6.1.1-3ubuntu5 is now installed via apt. Found on the way: a manifest is read once per process. Discovery does `await import()` and the module cache holds it, so editing a manifest changes nothing until pm2 restart officer — including `outdated`. Cost ten minutes and is now in the runbook. bunx tsgo clean. 797 tests, 787 pass, 7 fail — the same seven, +25 new. |
||
|
pastilhas
|
05eb947bd1 |
music is verified on the live server, and the runbook learns from it
Ran the whole table against platform.officer.dev rather than reasoning about it. install / API / range requests / dock / permissions / disable / enable / uninstall / db:push-while-uninstalled / reinstall / pm2 restart officer — all pass, recorded in plugins/music/PLUGIN.md with the actual numbers. Two results worth naming. The reinstall was a RESTORE: a favourite and a playlist seeded before uninstall came back untouched, which is the whole point of the barrel following directories rather than the install table. And `bun db:push` while uninstalled said `No changes detected` with the rows still there — the property that makes running push by hand safe at any moment. Range survives the proxy hop: 206 with a correct Content-Range and exactly the bytes asked for, 416 unsatisfiable, 400 on a path escaping the Music root. Two findings from the machine rather than the code. ffmpeg and ffprobe are not installed here, so X-Audio-Duration never appears and indexing would produce no tags or covers — the manifest already says a host binary cannot be declared, and now says it was checked. And ~/Music did not exist at all, so the library is empty; the sidecar handles both absences and logs them rather than failing. Music is left INSTALLED and enabled. It had been switched off since 2026-08-13, so this restores it. The runbook gains what generalises: map what the PLATFORM still needs from your feature before planning the split, because two imports pointing the wrong way dictated music's boundary rather than any judgement about what music is. Offscale had none, which made the job look cleaner than it is. Also two new traps — delete the app-store catalogue entry or the screen goes blank, and compare test FILE COUNTS across a run, since that is the only thing that shows a test which stopped being discovered. The global-overlay question is recorded as answered: no. A shell slot for a plugin-provided component reopens "there is no way to export a component", and that rule is what the frontend contract rests on. Seeded rows and the audio fixture removed; ~/Music deleted again. bunx tsgo clean. 772 tests, 762 pass, 7 fail — all pre-existing. |
||
|
pastilhas
|
de3340398c |
music becomes a plugin, and the player stays behind
The whole of music moves to plugins/music/: the sidecar (index, indexer,
stream-audio, nightly-reindex), the four Postgres tables and their queries,
the /music workspace panels, MUSIC_API.md and the reindex CLI. The platform
keeps no music routes, no music capability entry, no music screen and no
music schema.
Three things stayed, each on purpose.
cliamp and the widget were out of scope by the owner's decision. The plugin's
sidecar still serves the two cliamp sockets, so it imports cliamp-ws.ts and
pulse-audio.ts from @@/sidecar/music/ — the files stay where they were.
The player did not move, and that was the open judgement call. Deciding it
took one fact: the dashboard widget imports useMusicPlayer and PlayerTrack
from officerdev, and the platform cannot import from a plugin. So the player
STATE stays whatever is decided about the UI around it, and two copies would
mean two audio engines. Given that, the engine and the bar stayed with the
state rather than being split from the thing they drive. Moving them would
also have needed a shell slot rendering a plugin-provided component on every
route — the one escape hatch this system deleted on purpose. MusicPlayerHost
gates on can('music'), which is now the plugin's permission, so the seam
switches itself off with the plugin.
api/music/router.ts stays too: api/cliamp/relay.ts imports getMusicServerWsUrl
from it. The plugin's api/router.ts re-exports that proxy rather than building
a second one — two subscribers to the one-shot music:server port announcement
would work today and 503 on the first reconnect where only one was listening.
Two bugs found on the way, neither visible from reading.
The app-store catalogue still listed music. Availability is derived from
sidecar_installs and a PLUGIN never gets a row there, so `music` would have
been permanently unavailable — which puts /music into deniedRoutes and blanks
the screen on a server where the plugin was installed and healthy. Exactly
the headscale bug documented six lines above it in the same file, and it would
have fired on the first install. Entry removed.
[test] root was "./src", so moving lyrics.test.ts into plugins/ stopped it
running and said nothing — the count fell by nine and the suite still read
green. Root is now the repo. Positional filters cannot fix this: `bun test
plugins` matches under root and finds src/servers/plugins/ instead.
registry.test.ts tested the `personal` mechanism THROUGH the music capability.
Re-anchored on a fixture rather than on another entry, because borrowing a
feature only moves the problem to the next extraction — and three of those
four tests had been passing for the wrong reason since music's api was
commented out on 2026-08-13, when everything started resolving to "refused
because nothing is claimed". The cliamp sockets being claimed by nothing is
now pinned by a test instead of being rediscovered.
music's `personal` paths ride across on readOnlyWrites, the one field a
manifest has. isRequestAllowedAtLevel concatenates the two lists, so a read
grant permits exactly the four paths it permitted yesterday, and no field was
added to the manifest to design a per-user model that is not this work.
bunx tsgo clean. 772 tests, 762 pass, 7 fail — all seven pre-existing and
unrelated (cliamp, pty, and five capability tests that other switched-off
plugins break). Baseline was 757/10; the three that went green are the ones
re-anchored above.
Not yet verified on the live server — that is next.
|
||
 pastilhasandClaude Opus 5
|
18c4ebd0b4 |
the per-user model is not tonight's work either
personal, the four user-scoped tables, and what a member's grant means all stay exactly as they are. it gets built inside the plugin later, which is the entire reason the platform's answer is a uniform read/write and nothing more. leaving it alone is safe rather than lazy: the web frontend does not use those routes at all — favourites, playlists and now-playing are used only by the phone and tablet apps — so nothing visible in a browser can regress by carrying them across verbatim. and /queue, which is in that list, has no route anywhere. dead or aspirational; carried as-is, not investigated. the one unavoidable consequence stays named: registry.test.ts tests the personal mechanism through the music entry, so removing it breaks those tests. re-anchor on another entry that has personal. a test fix, not a redesign. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> |
||
|
pastilhasandClaude Opus 5
|
7d65732f77 |
the widget is out of scope too, leaving one open call
widgets/MusicPlayer stays in its third workspace package, registered where it is. plugins cannot contribute widgets and are not going to learn how tonight. with cliamp and the widget both cut, exactly one judgement is left in the music extraction: whether the global MusicPlayerHost overlay gets a contribution slot in the shell or stays in DashboardLayout gated as it already is. either is fine. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> |
||
|
pastilhasandClaude Opus 5
|
b5db3c47e1 |
cliamp is out of scope, which unblocks the music extraction
the two websocket providers exist for one thing: running the cliamp TUI on the server and piping its terminal and audio to the browser, via a pulseaudio null sink tapped by parec. a second, separate playback path — and the least important part of music. wanted eventually, not tonight. that removes the hardest of the three homeless parts entirely. no plugin can own a socket yet, and now none needs to: both sockets are already inert, and cliamp-ws.ts, pulse-audio.ts, asoundrc, the relay and the two providers all stay exactly where they are. if the relay's import is the only thing keeping api/music/router.ts alive, that stays too — a small documented seam. what music actually is: the /music screen, the library, and the phone and tablet apps that stream from it. that is what has to work. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> |
||
|
pastilhasandClaude Opus 5
|
8545b427dd |
the runbook tells the next agent to decide, not to ask
it previously said 'decide before moving a file, and tell me the decision', which turns an overnight run into a blocked one. every open call here has two defensible answers, a corrected decision is cheap, and a stalled extraction is not. adds a default for each of the three homeless parts — close the platform gap when there is runway, because every later plugin needs it too, but a working music with cliamp left in the platform beats a perfect design that did not land. the bar at the end is unchanged: install, enable, disable, uninstall cleanly. a piece left in the platform is a documented seam; a piece left dangling is a bug. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> |
||
|
pastilhasandClaude Opus 5
|
965ced52a6 |
a runbook for the next extraction, and a warning about music
plugins/EXTRACTING-A-PLUGIN.md: the rules that are not preferences, the order that worked, the verification cycle the owner actually ran, and the traps that each cost real time. the music section is the important half. music is NOT a bigger offscale — three of its parts have nowhere to go: two websocket providers (and no plugin can own a socket), a global UI overlay rendered by DashboardLayout on every route, and a dashboard widget in a third workspace package. its relay is platform code that imports the music router, so deleting that router breaks the platform. it also needs six external binaries a manifest cannot declare, ships a non-TS asset, and is the worked example the capability tests are written through. recorded before starting rather than discovered halfway, because a half-extracted music is worse than an unextracted one. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> |
||
|
pastilhasandClaude Opus 5
|
4a9f23c759 |
the design doc moves into the plugin it produced
docs/offscale-plugin.md becomes plugins/offscale/PLUGIN.md. most of it is about the plugin system generally rather than about offscale, which is exactly why it belongs with the worked example — the reasoning is most useful beside the code it produced, and the platform's docs should not carry the history of something it no longer knows exists. every reference updated. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> |
||
|
pastilhasandClaude Opus 5
|
b4dab16d2a |
the schema barrel stops describing a world that ended
three things wrong in one paragraph: it named ecosystem.light.config.cjs, which no longer exists; it called officer-headscale core, which it stopped being on 2026-08-14; and it said installing a plugin 'will have to uncomment its line and push, and building that is still ahead of us', which was built yesterday. now it says what is true — a plugin owns its schema at plugins/<name>/db and install generates the barrel and pushes — and keeps the commented lines for the sidecars still waiting their turn, which is what they are actually for. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> |
||
|
pastilhasandClaude Opus 5
|
2c89281bfc |
drop a comment describing an export that left with offscale
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> |
||
|
pastilhasandClaude Opus 5
|
585c046a64 |
the plugin system says permissions, not the other word
i named the field permissions and then narrated in the overloaded one anyway, which is worse than either — the whole reason for the rename was that the word already means three things here. renamed what was mine: setPluginCapabilities -> setPluginPermissions, pluginCapabilities -> pluginPermissions, and the prose throughout. what remains is the platform's own vocabulary, not the plugin system's: the type it imports, and the field on a dock manifest, which is the shape the shell already renders. renaming those is a separate change to a separate system and is the owner's to make. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> |
||
|
pastilhasandClaude Opus 5
|
8cc51cfb40 |
every plugin permission is grantable, and there is no field to say otherwise
offscale was missing from the permissions page because it declared ownerOnly, which mapped to kind admin, and admin capabilities are never offered for granting. correct by the old rule and wrong by the standard: every plugin follows the same platform-level permission model, appearing on the same page with the same read/write/none per role. so the field is gone rather than flipped. a plugin has no way to say owner-only, which makes the standard structural instead of remembered — the same move as the workspace rule. core, execution, confined and admin stay the platform's to assign and a plugin cannot name any of them, so the escalation question is removed rather than answered. this is the second draft of this decision to be deleted: first a full CapabilityKind with three of five values forbidden, then an ownerOnly boolean, now nothing. the doc records all three so the reasoning is visible rather than just the conclusion. finer visibility stays the plugin's job. offscale is the worked example of the gap that leaves and its manifest says so: it is grantable now, and its queries still scope by the caller, so a granted member would see their own empty server list rather than the owner's. closing that is a change inside the plugin. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> |
||
|
pastilhasandClaude Opus 5
|
8b6cb34ae0 |
plugins contribute dock tiles, and the doc says what is actually built
offscale had no dock tile: that field comes from the app store's catalogue, so a plugin installed through the plugin system was reachable only by typing its url or following the link on /plugins. built at runtime rather than baked into the generated bundle, deliberately — WHO sees a tile is a permission question, and a grant takes effect on the next request rather than the next build. presentation comes from the manifest and the route from mountPrefix, so there is one source for both, and is the plugin's first permission so the endpoint can filter a tile out for an account that cannot reach the screen. two sources for tiles today, because the app store still has its own catalogue. one when it is rebuilt on this. the doc now records the system as complete rather than half-stubbed, including the three bugs the extraction found — the sidecar-before-mount ordering, the missing tailwind, and the build that could delete its own shell — and what is genuinely still open. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> |
||
|
pastilhasandClaude Opus 5
|
8587ae20b7 |
a plugin creates its own tables, and uninstalling never drops them
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> |
||
|
pastilhasandClaude Opus 5
|
e13128846b |
offscale is a plugin
headscale leaves the platform. 45 files move to plugins/offscale/ and the
platform stops knowing it exists.
api/router.ts the thin auth-gated proxy, now at /api/offscale
sidecar/ 18 files, the whole headscale contract and its admin keys
db/ schema + queries, offscale_servers
web/ 26 files as panels and a layout — no screen, per the rule
removed from the platform: the hono mount, the `headscale` capability, the
App.tsx route pair, the screen and its barrel, the AppRegistry spread, the
officerdev re-exports, the dock tile, the page-title rule, and both database
barrels. tsgo is clean and nothing references it.
the imports tell the story of what the plugin↔host API actually is. the sidecar
takes @@/sidecar/protocol, @@/sidecar/connect, @@/data-path and
@@/officer-url.mjs; the queries take officerdb/db and officerdb/crypto; the
schema takes officerdb/auth/schema for the one reference a plugin may make; the
web half takes useClient, copyToClipboard, WorkspaceView and TerminalView from
the officerdev barrel. all of it resolves because a plugin lives inside the repo
— no publishing, no version negotiation.
AND IT FOUND A REAL BUG IN THE INSTALLER. createSidecarProxy learns its port
from a one-shot `<name>:server` event and subscribes when the plugin's router is
first imported — at mount. install started the sidecar BEFORE mounting, so the
announcement fired into a void: process online, routes mounted, every request
answering `503 sidecar not available` until something forced a reconnect. it
would have hit every plugin with an http sidecar. `example` never caught it
because it has no listener to announce.
install and enable now mount before starting; disable still unmounts before
stopping. neither direction leaves a mounted route in front of a sidecar that
cannot be reached.
verified live: /api/offscale/_officer/servers answers {"servers":[]}, /offscale
and /offscale/nodes serve, the old /api/headscale is 404, the offscale
capability is registered from the manifest, and officer-offscale is online.
757 pass, same 10 pre-existing failures.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
|
||
|
pastilhasandClaude Opus 5
|
0e24aa3d52 |
a way into the plugin from its detail panel
installing something and then having to guess its url is a small thing that makes the whole flow feel unfinished. the detail panel now links to the plugin's screen. shown only while installed AND enabled, and only when the plugin has a frontend at all. a link to an unmounted route lands on the home page, because the shell redirects an unknown path — which reads as a broken link rather than a plugin that is switched off. a backend-only plugin has no screen to open and gets no link rather than a dead one. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> |
||
|
pastilhasandClaude Opus 5
|
543e88a9a6 |
every plugin route renders a workspace, and it is not a rule you can forget
an exclusionary rule, made structural. a plugin does not render a screen: it
contributes panels and says how they are arranged, and the shell renders
WorkspaceView around them.
web/panels.ts appRegistryMetas — at least one panel
web/layout.ts defaultLayout — how they are arranged
both required the moment web/ exists, and missing either is refused at discovery
by name and with the reason. tested:
probeplug: has a web/ directory but is missing web/layout.ts.
Every plugin route renders a Workspace: contribute panels and a layout,
not a screen.
there is deliberately no way to export a component. one that could would be free
to render a bare div, a full-page form, or its own navigation, and the platform
would become a shell hosting strangers' layouts rather than one application.
non-compliance is not so much refused as unrepresentable — there is nowhere to
put a screen.
the shell registers <prefix> and <prefix>/:section, exactly as the core screens
do, so a plugin's sections stay addressable and cmd-clickable, and panels read
useParams independently rather than passing state between themselves.
appTypes.allowed is pinned to that plugin's own keys, so a persisted layout
naming something else falls back instead of rendering another plugin's panel
inside this screen.
the example plugin is rebuilt to model it — two panels, a layout, one of them
calling its own /api/example/ping through useClient — because the reference
implementation is what everyone copies.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
|
||
|
pastilhasandClaude Opus 5
|
2e3c935da6 |
the built SPA had no tailwind, and the build could destroy itself
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> |
||
|
pastilhasandClaude Opus 5
|
7b4137ccca |
a plugin's frontend, generated and rebuilt without a restart
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>
|
||
|
pastilhasandClaude Opus 5
|
a00116b2c0 |
a plugin's permissions become real capabilities, and survive a restart
two gaps between "a plugin can mount routes" and "a plugin is part of the platform". both closed. FIRST: nothing registered a plugin's declared permissions, so the capability gate could not resolve a plugin path at all. it resolved to null, and null is denied — the owner never noticed because isSuperAdmin short-circuits every check, which is exactly the shape of bug that reaches a member first. the registry is now rebuildable the same way the hono app is: CORE_REGISTRY holds the platform's own, CAPABILITIES is core plus whatever the installed plugins declare, and setPluginCapabilities replaces the plugin half wholesale rather than diffing it. two invariants hold by construction — DEFAULT_ROLE_- CAPABILITIES and CORE_CAPABILITIES derive from CORE_REGISTRY, so a plugin can never put itself in the fresh-install baseline and can never become `core` (every account, undeniable). a key colliding with a core one is refused and logged, because a plugin able to redefine `chat` could widen it. ownerOnly maps to admin, everything else to app. those are the only kinds a manifest can express, and it has no field for a kind at all. capabilities are registered BEFORE routes are mounted: the gate runs ahead of every router, so mounting a route whose permission is not yet registered would 403 the freshly installed plugin until something else happened to refresh. SECOND: nothing mounted plugins at boot. honoServer is built with none at import, because discovery reads disk and database and neither can be awaited at module scope, and every install verb rebuilt — so it tested perfectly and would have silently unmounted everything on the first restart. server.tsx now refreshes before serve(), so there is no window where an installed plugin 404s, and a plugin that will not load is logged rather than fatal. verified: after a restart, [plugins] mounted /example, the row survived, officer-example came back online from its ecosystem entry, capabilityForApiPath resolves /api/example/ping to the example capability at kind=app, and it appears in the owner's grantable list. 756 pass, same 10 pre-existing failures. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> |
||
|
pastilhasandClaude Opus 5
|
62ee0d1e60 |
the beat between steps is feedback, not decoration
the comment called it cosmetic and worth being honest about, which reads like an apology and invites the next reader to delete it as a pointless sleep. the real reason is better. some of this work is genuinely slow — pm2 start measures ~770ms — and some is effectively instant. without a pause the fast steps land in one frame, the log jumps from empty to finished, and you cannot tell 'it worked' from 'nothing happened'. the interval is what makes a step something you saw happen rather than something you found already done. only applied when something is listening, so the json path still runs flat out. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> |
||
|
pastilhasandClaude Opus 5
|
4d4606d4a2 |
close the owner's dotfiles once somebody else has a shell
ubuntu's default umask is 002 with user-private groups, so everything the owner
creates lands 775/664. alone on a machine that is harmless. it stops being
harmless the moment a member has a login — and member homes are NESTED inside
the owner's, so the owner's home must stay traversable AND readable (the
ancestor-read requirement bun exposed today) and every dotfile in it is legible
by default.
measured as green before writing this: ~/.pm2/logs (all 12 files, every log the
platform has written), ~/.pm2/dump.pm2, ~/.claude/projects (names every
directory the owner works in), ~/.config, ~/.local, ~/.cache, ~/.npm, ~/.bun,
~/.opencode — all listable. assertSecretsClosed was already holding the line
that matters: .env, .ssh, .zsh_history, .claude.json and the credentials are
denied, and dump.pm2 turned out to hold no secret values because bun loads .env
at runtime rather than through pm2.
so this is the tier below fatal: not tokens, but logs and the shape of the
owner's work.
it runs from PROVISIONING, not from setup, and that is the point. ~/.claude does
not exist until the agent has run once; a chmod at install time finds half the
list missing and silently does nothing — the same failure mode as the ACL mask
earlier today. every member's arrival re-closes whatever appeared since.
two directories are left open on purpose, and both are the same latent bug:
/usr/local/bin/bun -> /home/pastilhas/.bun/bin/bun
/usr/local/bin/gh -> /home/pastilhas/.local/bin/gh
system-wide tools installed into one user's home, so every member resolves them
through it. i found this by closing them and breaking bun and gh for green.
~/.local/share and ~/.local/state ARE closed; only the bin directory is
reachable. the honest fix is installing them outside the owner's home.
verified both directions on this host: green is denied .claude, .pm2, .config,
.local/share, .local/state, .cache — and still has working bun, gh, psql, their
own claude, and their own project tree.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
|
||
|
pastilhasandClaude Opus 5
|
a220342b22 |
stream the install, so it reads like a log instead of a spinner
each verb now reports its steps as they complete, over server-sent events, and the detail panel renders them arriving. POST rather than GET, so EventSource is unavailable — it sends no Authorization header and these routes are owner-only. The client reads the body and parses frames by hand, which is what useCompanionLogStream already does for the headscale container logs; the parser only has to understand what our own endpoint emits. the runner does not know whether anyone is listening. it takes an optional onStep and calls it, so the non-streaming path is the same code with no callback rather than a second implementation of the same four verbs. there is a 220ms beat between steps and it is cosmetic — worth saying out loud. pm2 start genuinely takes ~770ms, measured, but writing a row and rebuilding the router do not, and four lines landing in one frame look like a stall followed by a jump. small enough not to matter to a script, long enough to follow. writing to a closed stream is caught rather than fatal: navigating away mid-install must not abort the install, because by then it is the server's work and half an install is the one outcome the ordering was designed to avoid. verified over the wire with timestamps — frames arrive incrementally, the sidecar step showing its real duration rather than the beat. afterwards pm2 holds the five core apps, plugin_installs is zero, and ecosystem.config.cjs is byte-identical. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> |
||
|
pastilhasandClaude Opus 5
|
02e049cae8 |
terminal: stop replaying questions, stop opening two sockets, bind the word keys
three separate faults behind "reconnecting gets weird and the keyboard is not natural". ── the replay typed into the shell ── the pty buffer was stored raw and replayed verbatim on every re-attach. anything in it that ASKS the terminal a question — DSR, DA, DECRQM, XTVERSION, XTGETTCAP, the OSC colour queries — got asked again, and xterm answered correctly by writing the reply to its input. the pty receives that as a keystroke nobody typed. stripped on the way IN, since the buffer is the thing that gets replayed and a live client already answered them once when they were legitimately asked. only questions are removed; everything that draws is untouched. where a control shares its final byte with one that draws, the parameter is enumerated rather than wildcarded — CSI 18 t asks the window size, CSI 22 t pushes the title, and stripping the second would change what a replay renders. 36 tests, both directions, because both fail silently. ── two sockets on one session ── handleClose armed a reconnect timer; handleVisibilityChange fired on tab focus whenever readyState was CLOSED — which is exactly what a pending timer leaves. both ran. every keystroke went twice, two replay frames fought over the screen, and only one socket was ever cleaned up because __terminalCleanup is overwritten by whichever connect ran last. connect() is now the single guard, and a stale socket's close no longer speaks for the session. ── the keyboard ── alt-arrow was dead for everyone: xterm.js 5 rewrote it into the ctrl-arrow sequence, xterm.js 6 removed that rewrite and emits the honest ^[[1;3C/D (verified — the string 1;3D does not appear anywhere in the 6.0 bundle). nothing bound it. so it broke on a dependency bump, with no shell config changed. bound in zsh rather than translated in the browser, deliberately: tmux.conf claims M-Left/M-Right for pane switching, and a client-side rewrite would send ^[b to tmux and break it. the real sequence lets tmux handle it inside a session and zsh outside. ctrl-arrow was worse and more embarrassing: it worked for MEMBERS and not for the OWNER. shell-skel/zshrc has had the bindings all along; the owner's .zshrc is assembled in machine-setup and never got them. the owner had a strictly worse shell than the accounts they provision. confirmed with `zsh -i -c bindkey` before and after. also: escape-time 10 in tmux.conf. the 500ms default delays every Alt chord and every Escape, which is most of what "not natural" felt like. applied to this host by hand — setup only runs at install. cmd+arrow is left alone: xterm emits nothing for it, so there is no sequence to bind. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> |
||
|
pastilhasandClaude Opus 5
|
2634df7a04 |
the install runner: ecosystem entry, sidecar, row, mounts
closes the hole app-store/pm2.ts has carried since 2026-08-13 — "installing a
plugin has to append its entry here before starting it, that is the plugin
system's job and it is not built". this is that job, and it is why nothing in
the app-store catalogue installs end to end either.
verified against a running server with a sidecar in the tree:
install ecosystem added · sidecar started · recorded · mounted /example
route 200, pm2 online
disable sidecar stopped · unmounted
route 404, pm2 stopped
enable sidecar started · mounted
route 200, pm2 online
uninstall record removed · unmounted · sidecar stopped, deleted, entry gone
route 404, not in pm2, tables untouched
afterwards ecosystem.config.cjs is byte-identical to before, pm2 holds the same
five core apps, and plugin_installs is back to zero rows.
the ecosystem file is edited rather than regenerated: the core entries come from
officer-setup's shell array, so the platform does not know that list and a copy
here would be a second thing to drift. the header above module.exports is
preserved verbatim too — officer-setup's explains that bun auto-loads .env from
the working directory and that data-path derives the install root from its
PARENT, so a wrong cwd relocates the whole install rather than failing. losing
that to a plugin install would be a poor trade.
order is the design. bringing up goes outside-in, taking down goes inside-out,
so the worst intermediate state is "recorded but not running" — visible, and
fixed by a retry — never "running but forgotten", which nothing can see.
each verb returns what it actually did, in order, and the detail panel shows it.
an install that mounted routes but could not start a sidecar is a different
outcome from one that worked, and a spinner that stops cannot say which.
the schema push is still deliberately not wired, and the reason is now in the
code: db:push DROPS tables absent from the schema it is given, so an uninstall
that regenerated the barrel would delete a plugin's data as a side effect of
stopping it. offscale does not need it — headscale_servers already ships in the
platform schema.
720 pass, same 10 pre-existing failures.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
|
||
|
pastilhasandClaude Opus 5
|
ed195e0904 |
record what got built tonight
the plugin system works end to end for a plugin with an api/router.ts, at runtime, with no restart. what is wired, what is not (schema push, the sidecar's pm2 entry, websocket providers, totality across plugin routes), and what was deliberately left: offscale is not extracted, because moving it deletes working code across ~50 files and that wants someone watching. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> |
||
|
pastilhasandClaude Opus 5
|
98c400bf33 |
a /plugins screen to install, enable, disable and uninstall
the management surface for what the last commit made possible. two panels either side of a selection that lives in ?selected= and is read by both independently, so neither can be telling the other something stale — rows are real Links, not buttons holding the name in a closure. the detail panel shows what the tree declared (api, schema, sidecar, web), because "installed and nothing happened" is otherwise a mystery, and it names what uninstall does NOT do: neither disable nor uninstall deletes anything the plugin stored, and the screen says so rather than leaving someone to guess whether a button destroys their data. a directory whose manifest will not parse is listed with its error rather than skipped. a malformed plugin that simply does not appear is indistinguishable from one nobody wrote. `outdated` is surfaced as an Update button: the version on disk moving after an install is the normal state on a developer's machine, and it should be visible rather than inferred. the four mutations are written out rather than generated in a loop — useMutation is a hook, and a hook called from inside a helper is a rules-of-hooks violation even when the call order happens to be stable. caught before it shipped. verified against a running server: the spa builds (19.8 MB bundle containing the new screen), / serves 200, /api/plugins answers authenticated and 401s without a token. full suite 719 pass, same 10 pre-existing failures. live server and plugin_installs left untouched. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> |
||
|
pastilhasandClaude Opus 5
|
282a64a637 |
plugins install, enable, disable and uninstall at runtime
the rest of the mechanism, and it works end to end. against a real server, with
no restart at any point:
/api/example/ping BEFORE install 404
AFTER install 200 {"plugin":"example","ok":true}
AFTER disable 404
AFTER enable 200
AFTER uninstall 404
core route throughout 200
plugin_installs is a new table rather than a reuse of sidecar_installs. that one
belongs to the app store's model, where installing means provisioning a
container or pointing at a remote instance, and it carries mode, compose_dir and
completed_steps to say so. a plugin install has none of those, and reusing it
would have meant a `mode` that lies about every plugin. the two models coexist
until the app store is rebuilt on this one.
the row is needed because presence is not installation: plugins live in the
repository, so a developer writing one has the directory there and has installed
nothing. the tree says what could run, the table says what does.
mount.ts joins the two and rebuilds. an install row whose directory has gone is
dropped from the snapshot rather than reported — but the row is left in the
database, because deleting it there would turn "somebody moved the checkout"
into silent data loss. a plugin whose router will not load stays unmounted and
says why, rather than taking the other nine down with it.
/api/plugins is owner-only in its own right, like /api/app-store, and its
capability guards the MANAGEMENT surface only — a plugin's own permissions come
from its manifest, so a member can hold one at read without being able to
install anything.
plugins/example is the reference implementation and is meant to be read: the
smallest thing that is still a real plugin, with the directory layout as its own
documentation.
not wired yet, and marked [open] in the router: the schema push and the
sidecar's pm2 entry. a plugin with db/schema.ts or sidecar/ needs both before it
works end to end.
full suite: 719 pass, same 10 pre-existing failures.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
|
||
|
pastilhasandClaude Opus 5
|
0701aba902 |
brotli in the core package set
installed on this host already; verified round-tripping from a member shell. same package name on apt, pacman and dnf. on brew it is there because macOS ships the library but not the CLI. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> |
||
|
pastilhasandClaude Opus 5
|
2e6c263751 |
the hono app is built, not assembled once
first piece of the plugin system: the platform can now be rebuilt with a
different set of plugins mounted, at runtime, without restarting.
hono cannot do this the obvious way. its default SmartRouter throws "Can not add
a route since the matcher is already built" the moment a route is added after
serving begins, RegExpRouter does the same, and hono has no api to REMOVE a
route at all — so uninstall was impossible even with TrieRouter, which does
allow adding. tested all four.
so nothing is added to a live app. buildHonoApp(plugins) constructs a fresh one
and honoServer is reassigned, which keeps the default fast router and makes
uninstall expressible. server.tsx now serves it through a closure rather than
the bound honoServer.fetch — that one line is the whole mechanism, since the
bound method would capture whichever app existed at serve() and every rebuild
would silently do nothing.
buildHonoApp is pure: everything it needs arrives as an argument, so an app for
a hypothetical plugin set can be built without a database, a filesystem or a
running server.
alongside it, discovery. plugins live at platform/plugins/<app-name>/ — inside
the repo, because bun links the workspace packages into the root node_modules
and that is what lets a plugin author write `import { useClient } from
'hooks/useClient'` with no publishing and no version negotiation. verified with
Bun.resolveSync from a directory there.
discovery is by convention and presence is the declaration: api/router.ts,
db/schema.ts, sidecar/index.ts, web/Router.tsx. the app name comes from the
directory, so it cannot disagree with where the code sits, and the sidecar
runtime comes from the extension — .mjs is node, .ts is bun — which is already
the rule here and cannot contradict the file it describes.
a broken plugin is collected, never thrown: one unreadable manifest must not
stop the boot or hide the nine beside it that are fine.
verified by booting the refactored server on a spare port — /api answers 200,
protected routes still 401. full suite: 719 pass, and the same 10 failures as
before this change (8 in capabilities, plus cliamp and pty), stash-verified
earlier as pre-existing.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
|
||
|
pastilhasandClaude Opus 5
|
b2349b5480 |
install the psql client, matching the server it talks to
there was no psql on this machine. the server runs in a container, so nothing ever put a client on the host, and `docker exec officer-postgres psql` is the owner's tool — a member has their own Postgres role and no access to the owner's Docker socket. the version is derived from PG_IMAGE rather than typed again, because the pairing is load-bearing: pg_dump refuses a server newer than itself, and Ubuntu 24.04 ships client 16 against this 18 server. so the archive package is not merely old, it is unusable for dumps. that is also why this sits beside the server definition instead of in machine-setup's package list — one constant, one place to bump. PGDG added the same way docker.sh adds Docker's: key in its own file, one sources.list.d entry, no add-apt-repository. non-fatal, and the exit status is not the gate — apt can succeed while holding an older client back, so the check is that psql is present AND is the major we asked for. installed by hand on this host already: psql/pg_dump 18.6, verified as green connecting with their own role. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> |
||
|
pastilhasandClaude Opus 5
|
0ae0a5dc58 |
music is where the richer permission model gets designed
offscale is deliberately the simple case — one shared resource, read or write. music is the next extraction and the right place to build the in-plugin visibility system, because it has real per-user data (favourites, playlists, now-playing) on top of a real shared one (a single global library index). so 'whose is this row' has a non-uniform answer there, where offscale's is just 'the owner's'. not designed yet and deliberately not designed here. recorded so the intent survives the gap. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> |
||
|
pastilhasandClaude Opus 5
|
acd51c969c |
the platform grants read or write; richer rules belong to the plugin
the platform's contract is what it already has: a role holds read or write on a capability, stored in role_capabilities and enforced by the gate. anything beyond — who sees whose rows, per-user isolation, record ownership, visibility of any kind — is the plugin author's job, inside the plugin. the platform should not grow machinery for it. a plugin knows what its data means; the platform only knows whether this account got through the door. offscale v1 uses that exactly. one shared resource: read sees what the owner sees, write can change it including deleting a server the owner registered. that is dangerous on purpose — the stored credential is a headscale admin key with no read-only equivalent, so write is close to full control of the tailnet, and that is the owner's call. expected use is read for most roles. two consequences, both inside the plugin. the queries stop scoping by the caller and resolve to the owner's id, leaving the per-user shape in the table unused as the seam if isolation is ever wanted. and two POSTs are really reads — /ssh-test probes and /policy/assist explicitly never saves — so they need readOnlyWrites, or a read-level account finds a broken feature where a withheld permission should be. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> |
||
|
pastilhasandClaude Opus 5
|
4c3682dae6 |
let a member read the two directories above their own home
`bun run` from anywhere inside a member's home died with
error loading current directory
error: An internal error occurred (CouldntReadCurrentDirectory)
before it looked at package.json, bun.lock or .git — all of which were present.
it is not walking up looking for a workspace root. it primes its resolver cache
by walking DOWN from / and opening every component of the cwd for READING:
openat("/home/pastilhas/officerdev/") = 6
openat(".../officerdev/data/") = -1 EACCES
openat(".../officerdev/data/<email>/") = -1 EACCES
those two are 711 — traversable, not listable — which is enough to cd into a
home and not enough for a program that reads its ancestors. `getcwd` succeeds;
the ancestor read is what fails. `O_PATH` would need only `x`, so this is
arguably bun's bug, but it presents as a member's project being mysteriously
unbuildable and nothing here can fix it from the other side.
so DATA_PATH and the account dir now carry a named ACL entry per member. that
gives up the property the old comment named — a member can now `ls` DATA_PATH
and learn the other accounts' email addresses — and keeps everything that
matters: every home is still 700 and owned by its member, every platform
sibling still 700 and owned by the service user. verified as green: the account
list is visible, and email_accounts, another home, the repo .env, the owner's
ssh key, .pgpass and ~/.claude/.credentials.json are all still denied.
the mask is set explicitly to rx alongside the entry. chmod recomputes the mask
from the group bits, which for 711 is --x, so without that the next member's
provisioning would silently clamp every earlier member back to traverse-only.
applied by hand to the one existing account; provisioning covers new ones.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
|
||
|
pastilhasandClaude Opus 5
|
56bb383c6d |
a plugin installs with no questions unless it says otherwise
offscale needs none of the install fields the catalogue carries — no modes, no existingFields, no configFields, no composeTemplate, no members. nothing to provision, nothing to point at. install is put the code there, push the schema, start the sidecar, swap the routes, and it is available. configuration happens afterwards inside the app, which is already how headscale works: a server is registered at runtime and lands in offscale_servers. so no-questions is the default rather than offscale's special case, and the prompting machinery gets designed against the first extracted plugin that actually needs docker or a remote instance. part of why this was the right pilot — it exercises mounting, schema and sidecar without install being a variable at the same time. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> |
||
|
pastilhasandClaude Opus 5
|
327783532e |
reach a member's transcripts by listing them, not just by reading them
yesterday's fix routed transcript CONTENT through the member's identity and
stopped there, on the strength of a comment in ChatIdentity saying enumeration
never needed it — "their directories are 775 and the platform holds an ACL
entry, so readdirSync and statSync have always worked".
there are no 775 directories on this path. claude creates ~/.claude/projects/
and every project group at mode 700, and a 700 directory clamps the ACL mask to
--- exactly as a 600 file does:
user:officer:rwx #effective:---
mask::---
measured against a real member home:
existsSync(projects) -> true (stat only needs traverse on .claude)
readdirSync(projects) -> EACCES
existsSync(projects/<slug>) -> false
statSync(<transcript>) -> EACCES
existsSync answering false rather than throwing is why this was invisible: every
caller read it as "no such session". one root cause, three reported symptoms —
an empty conversation list, no title on a new chat, and a /chat/<id> deep link
that never restored the conversation. a fourth nobody had reported yet: delete
removed nothing and still answered ok, because unlink needs w+x on the group
directory too.
so enumeration goes through the same door as content, as ONE call rather than a
spawn per entry: listTranscriptsAs runs a single `find` as the member and
returns every transcript with its mtime, which readdir+stat could not do without
dozens of setpriv forks per request and a matching pile of auth.log lines. the
owner keeps a fork-free path — that process already IS the owner. removeAs does
the same for unlink, and readTailAs no longer stats a file it cannot stat.
summarizeTranscript now takes the mtime it is given instead of stat'ing again,
which is both the fix and one less syscall per file.
verified against jg@pertento.ai on this machine: 6 conversations listed with
titles from their first prompts, and a deep link by id alone loads 71 messages.
owner path re-checked and unchanged.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
|
||
|
pastilhasandClaude Opus 5
|
9f903479ce |
websocket routes reload too, so nothing needs a restart
the last gap. six ws providers live in bun's route table rather than hono's, so
the app swap does not reach them — but server.reload({routes}) does, and in both
directions: refused before, connected after install, refused again after
uninstall, with core routes untouched throughout.
so a plugin can own a socket from the start, and no part of an install needs the
process restarted.
still untested: whether connections already open across a reload survive it.
that matters before an install is allowed to interrupt somebody's terminal.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
|
||
|
pastilhasandClaude Opus 5
|
6ab838c77f |
mounting at runtime after all: rebuild the app and swap it
this went round twice — runtime dynamic, then generated-plus-restart on the
belief that hono could not mount after serving, then back once that was actually
tested. the doc keeps the route rather than just the destination.
tested: SmartRouter (hono's default) and RegExpRouter both throw 'Can not add a
route since the matcher is already built'. TrieRouter and PatternRouter accept
it. so runtime adding is possible but costs the fast matcher, and hono has no
remove-route api at all, which uninstall needs.
what solves both is not adding routes but rebuilding: construct a fresh app from
the current plugin set and reassign the variable. the fetch closure reads it per
request, so the reassignment is the swap — atomic, no dropped connections, no
server.reload, and the default SmartRouter is kept. verified 404 before install,
200 after, 404 again after uninstall, with core routes unaffected throughout.
the mechanical cost is one line: server.tsx:322 is '/api/*': honoServer.fetch, a
bound method evaluated once at serve(), and has to become a closure or the swap
does nothing.
websockets stay open: six providers live in bun's route table rather than
hono's, so a plugin owning a socket needs server.reload({routes}), untested.
offscale has none.
and totality stops being a boot check — buildApp() is now the single place
routes are mounted, so it is where the assertion belongs, refusing the swap
rather than refusing the boot.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
|