affe967ef40d9ff7d3eccb60dce4d02524628bae
1347
Commits
| Author | SHA1 | Message | Date | |
|---|---|---|---|---|
  pastilhasandClaude Opus 5
|
affe967ef4 |
todo: the code editor, and what is known about it before going deeper
Recorded so it survives a context reset rather than living in a chat message. The useful part is not the request, it is the four things established today: the screen has been unreachable for six months and so has no users, nothing about it has been verified beyond the URL plumbing, an empty-file editing bug of exactly the expected kind was already found next door, and whether 'Open in editor' should still exist is genuinely undecided. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> |
||
|
pastilhasandClaude Opus 5
|
c945f50e60 |
creating a file just creates it — and an empty file is editable
Two halves of one behaviour. ── New file no longer navigates ── It created the file and then took you to /code-editor, which made it the only action in the browser that leaves the browser. Creating a folder does not leave the folder; uploading does not open what you uploaded. Now the file appears in the listing and that is the whole operation. Editing is the same double-click that opens anything else — the viewer's pane already has an editor in it, with a save. One way to open a thing, one place it appears. ── The bug that would have broken that on the first try ── FileViewerHeader gated its Edit toggle on `editable && content`. `content` is `string | null` and an empty file is the EMPTY STRING, which is falsy — so a file with nothing in it rendered no pencil and could not be edited. That is precisely the file you most want to edit, and it is exactly what "New file" produces: the flow above would have dead-ended on its first use. Now `content !== null`, which is what FileViewerBody already used two files away. Checked the other two truthiness gates rather than changing them blindly, and both are right: `isJson` returns false for empty (an empty string is not JSON, and JSON.parse would throw), and Read Aloud stays hidden because speaking an empty file is not a thing. `Open in editor` still goes to /code-editor and is untouched — that route is a different tool, with a tree and tabs, and today's links are the first way to reach it at all. Worth deciding separately. tsgo clean, frontend builds, 817 pass / 7 fail unchanged. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> |
||
|
pastilhasandClaude Opus 5
|
d7b602ff34 |
a real dialog for New file, New folder and Clone
`New file` shipped this morning behind `window.prompt()`, and prompt is the wrong
tool for a reason that is not cosmetic: it cannot validate. It takes whatever you
type, so the first thing you learned about a bad name was a red toast after the
round trip — and for New file specifically, the server refuses to clobber, so the
way you discovered a name was taken was by having the creation rejected.
One dialog now serves all three. It checks on every keystroke, against the names
already on screen:
- empty is not an error, just nothing to submit — no red "required" before you
have typed anything
- `.` and `..` refused; a LEADING dot is fine, because a dotfile is a real
thing to want
- `/` refused rather than quietly doing mkdir -p, which is a surprise from a box
labelled "Folder name" and is why the rename endpoint refuses slashes too
- a collision is caught before the request, and case-SENSITIVELY: this is Linux,
so Notes.txt and notes.txt genuinely coexist and refusing one would refuse a
legal name
The server keeps its own refusal. This is the courtesy; that is the lock.
Clone joined them because it was the last prompt() I had added, and the URL check
is deliberately loose: git takes ssh, git://, a local path and a host alias from
~/.ssh/config, so validating for https would break working setups to prevent a
mistake git already reports well. Only whitespace is refused.
The open state moved into `useFileBrowserApp` because two surfaces open the same
dialog — the background menu and the toolbar — and each having its own would be
two dialogs that could both be open. One mount, five call sites.
The toolbar's New folder was on prompt() before today and is now on the dialog
too, so there is no prompt() left anywhere in the file browser.
16 tests over the two validators. tsgo clean, frontend builds, 817 pass / 7 fail —
the 7 unchanged.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
|
||
|
pastilhasandClaude Opus 5
|
84d6d7e7ce |
file browser: the eight defects from the audit
1. Kebab Cut/Copy silently did nothing, and sometimes cut the wrong rows. `EllipsisMenu` stops click propagation so opening it does not toggle selection — but Cut, Copy, Download, Delete and Compress all act on the SELECTION, which meant the kebab operated on whatever was selected elsewhere, or returned early with no toast at all. Right-click never had this because it selects first. Both now call one `ensureSelected`, on open. 2. Every menu vanished during a search. That branch had no ContextMenu and its rows are not FileItems, so right-click fell through to the browser. The folder menu is now declared once and mounted in both branches — it acts on `currentPath`, which a search does not change, so it stays meaningful. Search ROWS get their own three-item menu rather than the row menu: a hit carries an absolute path from anywhere in the tree, while every row-menu handler builds its path from the folder being browsed. Reusing it would have acted on a different file with the same name. `DirEntry.path` is optional — only search results carry one — so it is guarded, not asserted. 3. Download and Copy path now fan out over a multi-selection, the rule Delete and Compress already used. The menu downloaded one of six selected files while the toolbar zipped all six. Chat is deliberately NOT included: `chatContext` is a single path that the provider string-splits into a working directory, so a list would need Chat's contract changed. Left alone rather than half-done. 4. Read Aloud stopped offering TTS on binaries — same guard the editor got, since `text` is `getFileType`'s fallback and caught .exe and .sqlite. 5. `POST /file-browser/download` is filed as a read. It zips a selection and writes nothing; it is a POST only because a list of paths does not fit a query string. A read-level member could download a whole folder but not two files. Proved by hand that `readOnlyWrites: ['/download']` permits GET and POST /download, and still denies /download-video, /rm and /write — `isPrefixOf` is segment-aware, so the sibling route does not leak. 6. `disabled` had no use anywhere in the feature — the shared item type did not even expose it. It does now, and the first real case: `/file-browser/read` refuses over 5 MB, so Open in editor on a 40 MB log opened an editor that then failed. Hiding it would have suggested the file is not text; disabled says the true thing. 7. The grid kebab could fade out while its own dropdown was open — list view had `data-[state=open]:opacity-100` and grid did not. 8. Dead exports `getMatchingTasks` / `getMatchingAgents` removed. Both were the ungrouped input to the grouped form the menu actually renders; exporting them invited a second code path that never arrived. 9 is untouched on purpose — a plugin cannot register a menu item, and the music plugin is where that should be designed. tsgo clean, frontend builds, 808 pass / 7 fail unchanged. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> |
||
|
pastilhasandClaude Opus 5
|
e2b0d5c06b |
edit any text file, and make new ones from the empty panel
Two things, both asked for. ── Open in editor now covers text ── It was markdown and code only, because `text` is `getFileType`'s FALLBACK and so also catches binaries. That was the wrong trade: media, archives and pdf are already claimed by earlier branches, so what actually lands in the fallback is .txt, .log, .csv, .conf, dotfiles, Makefile-likes and anything with an extension the platform has never heard of. Refusing all of that to avoid one bad case cost far more than it saved. The bad case is named instead of guessed at — a ~40-entry list of extensions that reach the fallback but are not text (.exe .so .sqlite .docx .woff …). A denylist that is too short costs one bad render; a `text` test that is too strict costs the feature. Not a security control: `/file-browser/read` is UTF-8 and capped at 5 MB, so the worst outcome is mojibake. Checked against 18 names: notes.txt, server.log, data.csv, nginx.conf, .env, Makefile, script.sh, and an extensionless file all offer it; jpg, mp3, zip, pdf, exe, so, sqlite and docx all do not. ── New file, from the empty panel ── Right-click → New file takes a name WHOLE, extension included, creates it empty and opens it in the editor. The extension is what the editor uses to pick a language, so guessing one would be wrong more often than not; no extension is fine and opens as plain text. It refuses to clobber. `/write` is an overwrite, so creating over an existing name would silently empty it — the one outcome nobody wants from a menu item called "New file". There is no stat endpoint, so the check is a read that is expected to fail. `prompt()` to match New folder directly above it. Both deserve a real dialog and neither has one; making this one different would just be inconsistent. ── Verified rather than assumed ── `getActiveFile()` only matches ALREADY-OPEN files, so a path arriving in the URL could have landed on an empty editor — the exact silent failure this whole audit keeps turning up. It does not: CodeEditor.tsx:60-76 fetches and opens an unopened `?file=`, with an `unreadable` set guarding the retry loop. Confirmed /code-editor renders with `urlState`, without which the param is ignored entirely. The param is imported as `EDITOR_FILE_PARAM` rather than written as 'file' twice, so renaming it cannot leave this behind. tsgo clean, frontend builds, 808 pass / 7 fail unchanged. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> |
||
|
pastilhasandClaude Opus 5
|
cc889a864c |
file browser: close the accidental gaps in the context menu
The audit split the menu's omissions in two. Three were deliberate — OCR, Transcribe and Extract Audio were removed in July because the task system does them better, and those stay gone. The rest were nobody's decision. This is the rest. ── One menu body instead of two ── `DropdownMenuItems` and `ContextMenuItems` were character-identical apart from the component prefix: 159 lines duplicated, including the same comment twice. Radix gives both families the same props, so the components are now a parameter and there is one list. That is why this diff removes more than it adds while adding seven items — and why the next item only has to be written once. ── Added to the row menu ── - Open — double-click was the only way. Every file manager puts it first. - Open in editor — `/code-editor` is on the SAME `files` permission as `/files`, so anyone who can browse could already edit; there was just no way to get there from a file. Narrower than Read Aloud on purpose: that one uses the `text` FALLBACK type, which matches .exe and .bin. - Paste into folder — a move was only expressible as cut → navigate → paste. Right-clicking the destination is the obvious gesture and did not exist. - Duplicate — one call away the whole time; `/copy` already resolves collisions to " (copy 2)". - Compress — the missing half of Extract. `/download` shelled out to zip but streamed the result away, so nothing could make an archive and keep it. New `POST /file-browser/compress` writes it beside the original. - Pin / Unpin — pinning existed only in the widget, which is not where you meet a file worth keeping to hand. ── Added to the background menu ── - Clone repository and Show/Hide hidden files. Both were toolbar-only, and the toolbar hides them under `md:` — so on a phone neither existed. All four desktop-only toolbar actions are now in this menu, which long-press reaches. - Paste is gated on the clipboard, as both toolbars already were. Ungated it fell through to the OS clipboard path and either toasted a secure-context error or silently did nothing — an item that looked available and was not. ── Removed ── `pcm-worklet-processor.js`, orphaned when cliamp left for the music plugin this morning. Verified unreferenced; the plugin ships its own copy inline. The `Play` hole itself is NOT closed and cannot be from here: there is no way for a plugin to register a context-menu item. Tasks and agents are the only extension mechanism and a task can only contribute a task entry. That is a platform gap and wants its own decision. Verified the zip invocation by hand for all three shapes — single file, directory (recursive, contents included), and a multi-item selection. Archive naming strips the extension only for a file, so a directory called `my.photos` stays `my.photos.zip` rather than becoming `my.zip`. tsgo clean, frontend builds, 808 pass / 7 fail unchanged. SelectionActions.tsx and usePipelineRunner.ts are prettier reflowing long lines — no semantic change, caught by formatting the folder. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> |
||
|
pastilhasandClaude Opus 5
|
640529ccba |
offscale in the catalogue, and the comments the rename falsified
The plugin half is in gitea.officer.dev/plugins/offscale (95b84ea). This is what
the platform owed it.
- marketplace: offscale now ships assets/icon.png, so the catalogue carries an
iconUrl and a `bare` tile like music's. The lucide `icon` stays as the fallback
for a failed asset publish — a glyph beats the generic box.
- Four schema files cited `headscale_servers` as the shape they copied. The table
is `offscale_servers` as of today, so those sentences named a table that no
longer exists. Same for secret-store.ts's list of purposes.
The crypto purpose moved with it: `decryptSecret('headscale', …)` in the plugin
is now `'offscale'`, and the secret-store row was renamed rather than abandoned,
so the key material is preserved and the change is reversible. Safe only because
offscale_servers held 0 rows — one stored API key and this would have been a
re-encryption, not a rename.
Verified: offscale_servers, uq_offscale_servers_one_active and
uq_offscale_servers_user_url all exist in Postgres and nothing named headscale
does. Dropped the empty table by hand first, because drizzle-kit push treats a
rename as an interactive prompt and would have hung.
tsgo clean. 808 pass / 7 fail — +21 from offscale's first tests, same 7 failures.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
|
||
|
pastilhasandClaude Opus 5
|
dd26e4a688 |
example leaves too; plugins/ is documentation now
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> |
||
|
pastilhasandClaude Opus 5
|
cca85a7524 |
offscale moves to its own repository
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> |
||
|
pastilhasandClaude Opus 5
|
2258812d4a |
untrack marketplace-installed plugins
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> |
||
|
pastilhasandClaude Opus 5
|
29170dd922 |
installing a plugin pins its dock tile, with no reload
Installing Music left the dock unchanged. The tile existed server-side the moment the plugin was enabled, and the only way to see it was Profile → Dock, by hand, after a page refresh. Installing something is already the decision to use it; saying so twice is the bug. Three separate causes, which is why it looked like one stubborn one: 1. `dock_configs.paths` is a COMPLETE ordered list, not a diff — useDock renders the saved list rather than everything available, so anything not named in it is invisible. Nothing in the plugin system had ever written to that table. installPlugin now appends the new route, for the caller (threaded through the route) rather than a guessed owner id. Only for a user who HAS a row. A user without one is left alone deliberately: there is nothing to append to, and writing one would freeze today's defaults into their account permanently. That case is (2). 2. The fallback for a user who never customised was DEFAULT_DOCK_PATHS, which is core-only — so a plugin tile was hidden there too. `defaultDockPaths(plugins)` is now that list plus a tile per installed plugin, and the dock and its settings screen both call it so they cannot disagree about what "default" means. 3. useDock holds ['DOCK'] at staleTime: Infinity and the plugin verbs invalidated only ['plugins'] and ['self-permissions']. So even once the server wrote the path, nothing asked again — that is the part that made a reload necessary. Also fixes a guard I broke reaching for this: typing VERBS as Record<string, VerbFn> widens keyof to `string`, which makes `isVerb` prove nothing and lets an unknown verb index the map. `satisfies` instead, and there is now a check that Verb is still the four-member union. Uninstall deliberately does not remove the path. A stale path with no item behind it is dropped by useDock, and keeping it means disable/enable and reinstall put the tile back where the user had it rather than at the end. tsgo clean, frontend builds. 787 pass / 7 fail — 6 identical to before; the 7th is plugins/music/cliamp, which install pulled into test discovery and which the manifest documents as parked. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> |
||
|
pastilhasandClaude Opus 5
|
dadfdc26af |
plugins page becomes a marketplace: catalogue, clone-on-install
The /plugins route showed only what was already on disk, so a plugin nobody had copied in by hand did not exist. It now shows a third list — what a remote catalogue offers — and installing one fetches its source. - plugins/marketplace.ts — a stand-in for the remote store, a JSON array in process. One entry: music, pointing at gitea.officer.dev/plugins/music. It is deliberately a module and not a fetch, so the shape of a catalogue entry gets settled before anything depends on a server answering. - plugins/fetch.ts — git clone --depth 1 into plugins/<appName>/, INSIDE the platform repo because bun resolves the workspace links by walking up and a plugin cloned beside it cannot import anything the platform provides (measured, not assumed). https only, no credentials, GIT_TERMINAL_PROMPT=0 so a repo that turned private fails instead of hanging. A failed clone removes the directory: a half-written one reads as a broken plugin rather than an absent one, which is the worse of the two. - install.ts fetches first when the directory is missing, then RE-DISCOVERS rather than assuming what it cloned. Everything after is the existing path, including the frontend rebuild — so a cloned plugin's panels reach the SPA without a restart. - GET /api/plugins returns `available`, catalogue minus what is on disk. Each entry gets the same live PATH probe a local plugin gets, so music's ffmpeg and ffprobe are answered for this machine BEFORE the clone rather than after. - The detail panel is a separate component for a catalogue entry, not a mode of the installed one: there is no sidecar status, no enabled state and no route to open, and what there IS — the source URL — the installed panel has no reason to show. The streaming log is shared, because the marketplace install is the case that needs it most: it clones before it does anything, and a slow clone behind a blank panel looks like a hang. The catalogue's icon is an absolute URL to the store's copy, which is the [open] question the previous commit left: assets only publish at install, so a plugin you have never installed had no artwork to draw. Not done: no update verb, no signature, no private repos, and removePluginSource has no caller — deleting source drops tables on the next push, and that wants a verb that says so. tsgo clean. 767 pass / 6 fail, all 6 identical on HEAD without this change. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> |
||
|
pastilhas
|
256f8185f5 |
music leaves the platform repository entirely
41 files moved to ~/officer-dev/plugins/music, now its own git repository
pushed to gitea.officer.dev/plugins/music. The platform tracks none of it.
Done in the order the design intends, and each step verified rather than
assumed:
uninstall via /plugins sidecar stopped and deleted from PM2, ecosystem
entry removed, routes unmounted, icon unpublished,
TABLES DELIBERATELY KEPT
copy out, verify `diff -r` identical before removing anything
git rm from the platform
regenerate the barrel 1 plugin schema now: offscale
bun db:push --force music_favorites, music_playlists,
music_playlist_items and music_now_playing DROPPED
That last step is the one destructive property this system has, and until today
nobody had watched it happen. `plugins/schema.ts` has said since it was written
that the barrel follows plugin DIRECTORIES rather than the install table, so
that uninstalling keeps every row and only deleting the source can lose data.
Both halves are now observed: uninstall kept the tables, deleting the directory
dropped them. Nothing else moved — headscale_servers intact, plugin_installs
correct, all 9 permission grants untouched.
The platform boots clean, mounts /example and /offscale, reports no broken
plugins, and answers 404 on /api/music.
── What this cost, and it is the interesting part ──
The test suite went from 797 tests across 58 files to 776 across 55. Music took
its three test files with it, and one of the seven known failures — the cliamp
socket test — left with them. So the platform no longer tests music at all, and
music's repository has no CI. That is correct and it is also a gap.
And the repository does not build. Measured from outside the platform checkout,
every one of `hooks/useClient`, `officerdev` and `officerdb/db` fails to
resolve: 7 imports in the backend, ~29 in the frontend. A symlink back into
platform/plugins/ was tested and does resolve, but the owner declined it — the
point of moving was to stop pretending.
So music is now a source of truth that cannot run, and the host API has to
become something a plugin depends on rather than reaches into. That was already
the known problem; it is now the blocking one.
|
||
|
pastilhas
|
abb8fe4320 |
the migration script stops needing the app it migrates
It died on its first real use, on a production server, before running a single statement: error: Cannot find module './plugin-schemas.gen' from officer_db/src/schema.ts It imported `officerdb/db`, which imports `schema.ts`, which imports the gitignored `plugin-schemas.gen.ts`. That file does not exist on a fresh clone — which is exactly the state every machine this script is FOR is in. It had been tested against a scratch database on a machine where the barrel happened to exist, so the one condition that mattered was the one condition never tested. A migration issues ALTER statements. It has no business needing the application's schema barrel, its table objects or its query layer. It now opens its own `postgres` connection and imports none of them. Tested the way it failed: barrel moved out of the tree, script run against a scratch database built in the old shape. Renames the table, the column, both indexes and all three CHECK constraints, keeps the rows, and the idempotent path still no-ops. Verified by reading pg_indexes and pg_constraint afterwards rather than trusting the exit code. Deployed to edge-pertento today with two real users. Nine grants migrated intact, old table gone, permissions page confirmed in the browser. The only casualty was a minute lost to this bug, because the database had not been touched when it failed — the import blew up before the first query, which is the one place a crash costs nothing. `bun db:push` was already immune: it runs scripts/gen-plugin-schemas.ts first. That fix existed because the same trap was found earlier today in the setup path. It was not applied here because I did not think of this script as something that runs on a fresh clone, which is precisely what it is. |
||
|
pastilhas
|
9c2d6a97f7 |
a tested migration script for the capabilities→permissions rename
Other machines have to make the same database change, and pasted SQL is the
wrong way to ship it. `scripts/rename-capabilities-to-permissions.ts` renames
the table, its column, both indexes and its three CHECK constraints in one
transaction, and refuses to guess:
neither table nothing to do; db:push will create it
already renamed no-op, prints the grant count
BOTH tables present stops and says a human must decide
old table only migrates, counts before and after, prints every grant
Testing it found a bug that reading it had not. The existence checks were
inside the transaction but ran on the pool rather than on `tx`, so they could
not see the uncommitted rename: `columnExists('role_permissions','capability')`
answered false because that table did not exist yet on that connection, and the
COLUMN rename was silently skipped. The result was a `role_permissions` table
with a `capability` column — half migrated, and only failing on the next query.
That was found by building a scratch database in edge-pertento's exact shape
and running the script against it, rather than by review. Every check now
happens before the transaction, against the old names.
Verified end to end on that scratch: 6 grants migrated intact, a second run
correctly no-ops, and `db:push` afterwards leaves role_permissions and its rows
alone while creating the rest of the schema. Indexes come out as
role_permissions_pkey and uq_role_permissions_role_permission.
Also swept the last all-caps survivors the case-sensitive passes missed:
CORE_CAPABILITIES → CORE_PERMISSIONS, and a react-query key still spelling
['ROLE_CAPABILITIES']. The only CAPABILITIES left in src/ is the wallet's, which
is Lightning and stays.
|
||
|
pastilhas
|
027b10bd6e |
step 4/4: the docs say permissions too, and capability means one thing again
44 files of prose — CLAUDE.md, AGENTS.md, TODO.md, 20 docs, both plugin design
documents, and the comment surface the earlier steps could not reach.
Applied against an explicit keep-list, not swept, because the word turned out to
have SIX meanings in this repository rather than the three the offscale doc
recorded:
permissions renamed (steps 1–2)
$OFFICER_ROOT/capabilities/ KEPT — the item store, and now the only thing
the word means that is ours
sidecar routing keys renamed to `handles` (step 3)
Lightning wallet KEPT — a domain term, and on the wire to the mobile apps
terminfo queries KEPT — XTGETTCAP, in the pty sidecar
InvoiceShelf KEPT — per-resource { write, bulkDelete } flags
The sweep still falsified two things, both caught by checking rather than by
review, and both in prose that discusses more than one meaning at once:
CLAUDE.md began claiming the item store lives at `$OFFICER_ROOT/permissions`.
It does not; that directory is on disk and full of skills and tools.
And the offscale doc's own note about the collision became
"Named `permissions`, NOT `permissions`" — a sentence that had eaten the thing
it existed to warn about.
Both restored, and the note rewritten to say what is now true: capability means
one thing of ours, and three that belong to somebody else's vocabulary.
Verified live after restart: self and admin permission endpoints 200, gated
route 200, agent-status 200, 9 grants intact with 6 permissions offered.
tsgo clean, 797 tests, 787 pass, same 7.
The rename is done. Four steps, no data lost, no client break that survived
the step it was introduced in.
|
||
|
pastilhas
|
f9fd002ff4 |
step 3 verified live: the whole estate re-registered with handles
`pm2 restart all`, and all six came back on the new protocol:
agent handles=[claude] opencode handles=[opencode]
proxy handles=[proxy] headscale handles=[headscale]
pty handles=[terminal] music handles=[music]
`pty` → `handles=[terminal]` is the case that makes the rename worth it: the
name and the handled kind were never the same string, and calling the list
"capabilities" hid that behind a word already doing three other jobs here.
The strongest evidence is not in the log. The session that wrote this change
runs on officer-claude-code, and `restart all` bounced it — so the conversation
continuing at all means `sendCommand('claude', …)` resolved through
findSidecarHandling against a freshly registered sidecar. The one path that
would have failed silently proved itself by working.
Checked besides: agent-status 200, chat/models 200 (both sendCommand paths),
music manifest 200 and offscale health 200 (port-announcement paths, which the
`<name>:server` generalisation touched earlier today). No "No sidecar handling
X is connected" anywhere in the log.
/api/terminal/* answers 404 rather than 503, which is the distinction that
matters: 503 is the proxy having no port for the sidecar, 404 is the sidecar
answering and having no such route. The pty proxy resolved its port.
Permissions unaffected across all three steps: 9 grants, {role, permission,
level}.
Step 4 — the last of the doc and comment surface — is all that remains.
|
||
|
pastilhas
|
5afa2d832e |
step 3/4: sidecar routing keys become handles — NOT YET VERIFIED LIVE
Committed before restarting, deliberately: this changes the registration wire, and the restart that proves it also bounces officer-claude-code, which is what the session doing the work runs on. An uncommitted 25-file protocol change is worse to inherit than one marked unverified. `capabilities: ['music']` → `handles: ['music']` on the registration message, across 20 sidecars, both plugins, the connector, the registry and the protocol type. findSidecarByCapability → findSidecarHandling, waitForCapability → waitForHandler. The name: a sidecar already has `handleCommand`, so the list is literally what it handles. `provider` was rejected — 390 existing uses and it already means websocket door. `serves` was rejected — collides with HTTP serving, which sidecars also do. THIS IS A BREAKING WIRE CHANGE with no compatibility shim. A platform expecting `handles` reads `undefined` from a sidecar sending `capabilities`, registers it with an empty list, and every sendCommand finds nobody — chat, terminal and music all fail with "No sidecar handling X is connected". So the whole estate has to restart together; there is no rolling upgrade. If it goes wrong: `git revert HEAD` and `pm2 restart all` again. The registry is in-memory and nothing about this touches the database, so a revert is complete. Found a fifth meaning of the word on the way, correctly named and untouched: the pty sidecar's terminfo capability queries (XTGETTCAP escape sequences). That is now five — permissions, the item store, routing keys, Lightning wallet features, and terminfo. tsgo clean, 797 tests, 787 pass, same 7. Not exercised against a live sidecar. |
||
|
pastilhas
|
5ec354cfcb |
step 2/4: role_capabilities becomes role_permissions, without losing a grant
The dangerous one. `drizzle-kit push` does not understand renames — it sees a
table gone and a table added, and with --force it resolves that by dropping and
creating. The 9 live grants would have vanished silently and every member would
have lost terminal, chat and files until someone noticed and re-granted by hand.
So the database moved FIRST, by explicit ALTER, and the code followed:
ALTER TABLE role_capabilities RENAME TO role_permissions
ALTER TABLE role_permissions RENAME COLUMN capability TO permission
ALTER INDEX uq_role_capabilities_role_capability RENAME TO uq_role_permissions_role_permission
ALTER TABLE ... RENAME CONSTRAINT ck_role_capabilities_{role,level,not_owner} TO ck_role_permissions_*
ALTER INDEX role_capabilities_pkey RENAME TO role_permissions_pkey
Seven objects, not one, and all in a single transaction: a partial rename would
leave drizzle-kit seeing a table it half-recognised, which is the same drop.
The names were read out of pg_indexes and pg_constraint rather than assumed.
`bun db:push` then reported **No changes detected** — which is the whole proof.
It means the ALTERs matched the schema code exactly, so there was nothing for
push to reconcile and nothing for --force to destroy.
Grants verified against a JSON backup taken before the first ALTER: 9 rows,
byte-identical, `role_capabilities` gone from the database.
No client noticed. Step 1 had already moved the wire to `permission` by mapping
in the route while the column still said `capability`, so this step deleted the
mapping rather than changing any response. The two call sites that carried a
`capability` key with a comment explaining why now say `permission` and the
comments are gone.
Also renamed officer_db/src/capabilities/ → permissions/, roleCapabilities →
rolePermissions, CapabilityLevelValue → PermissionLevelValue.
Verified live after restart: self 200, admin list 200, gated route 200, no
token 401, grants read back as {role, permission, level}, and a PUT round trip
left 9 grants intact.
tsgo clean. 797 tests, 787 pass, same 7.
|
||
|
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>
|