diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/apps.md | 57 | ||||
| -rw-r--r-- | docs/refactor-groups.md | 72 |
2 files changed, 123 insertions, 6 deletions
diff --git a/docs/apps.md b/docs/apps.md index 7ce1e73..7819dc9 100644 --- a/docs/apps.md +++ b/docs/apps.md @@ -146,6 +146,12 @@ async def set_enabled_apps(group_id, apps, set_by="") -> list[str]: ... from exactly one place: `webrtc_server.py`'s `_admin_exec_apps_enabled`, after `_verify_admin_sig` — nothing is applied before the signature checks out. +**An app's directories are the same shape one level down** (2026-09-06): +`ops.set_app_directories(state, group_id, app_key, paths)`, stored under +`<app_key>_directories`, reached by one MNP message (`app_directories`) and one +loopback route. Adding an app adds no function, no message type and no route — +which is what "plugin architecture" has to mean to be worth the phrase. + `_do_apps_enabled` in `webrtc_server.py` validates before it ever issues a challenge: - `apps` non-empty — the operator can never lock a group down to nothing. @@ -170,6 +176,37 @@ table. Changing it broadcasts `apps_enabled_ack` to everyone already connected waiting for a reconnection. The root ops (`root_update_ack`, `root_eject_ack`, `root_plug_ack`) broadcast the same way, through `onRootsChanged`. +### 3b. An app's settings + +Each app that has settings exports a component from +`static/<app>-app-settings.js` and names it in its `apps.js` entry. The Settings +page renders one collapsible section per registry entry, with the app's own +on/off switch in the header — the toggle *is* the enablement control, rather +than a checkbox list somewhere else that could disagree with it. + +Every pane takes the same props, and nothing else: `roots`, `dirs`, `settings`, +`saveDirectories` (bound to this app), `transport`, `signFn`. The split is the +point — **what every app has, the page does generically; what one app alone +has, the pane does itself.** Pointing an app at folders goes through +`saveDirectories`; a TMDB credential or a link-preview switch is the pane's own +business, made with the transport it is handed. An app that only needs +directories therefore touches neither `group-settings.js` nor `group-page.js`, +and `test_app_settings_plugin.py` fails if either of them starts naming apps +again. + +Two constraints that are not obvious: + +- **A pane must not import `group-settings.js`.** That is a cycle + (`group-settings` → `apps` → pane → `group-settings`), and ES modules answer + it with a temporal-dead-zone `ReferenceError` at first render — the component + does not appear, with nothing in the console to say why. The shared widgets + (`CollapsibleSection`, `ToggleSwitch`, `useSaver`) live in `settings-ui.js` + for this reason. +- **A new module must be added to `_ASSETS`** in `meshbay_hub/api/webapp.py`. + A file reached through the registry is not imported by name anywhere, so + nothing else would notice it changing, and a browser would go on serving the + cached copy. `test_asset_versioning` enforces it. + **Client side:** `apps.js`'s `visibleApps(enabledKeys)` filters the registry; `group-page.js` calls it with `enabledApps` state (from the ack, `null` until one arrives, which `visibleApps` reads as "show everything registered" — a @@ -187,8 +224,17 @@ registry, so a newly-registered app gets a checkbox for free. `icon.js` — do not re-implement `formatSize`, the download pipeline, or `Icon`. 2. **Register it** in `apps.js`'s `APPS` array: `{ key, icon, labelKey, - Component }`. `key` is the wire identifier — it must match what you add to - the node's allow-list next. + Component, Settings? }`. `key` is the wire identifier — it must match what + you add to the node's allow-list next, and it is also the row an app's + directories are stored under (`<key>_directories`). One identifier per app, + everywhere; `test_app_settings_plugin.py` checks the registry against + `ALLOWED_APPS`. +2b. **`<name>-app-settings.js`**, if the app has anything to configure, + exporting a component that takes `{ roots, dirs, settings, + saveDirectories, transport, signFn }` and nothing else (§3b). Folders go + through `saveDirectories`; anything only this app has, it does itself with + the transport. **Do not import `group-settings.js`** — that is a cycle, and + it fails as a component that silently does not render. 3. **Node-side allow-list**: add the key to `ALLOWED_APPS` in `webrtc_server.py`. Without this the node refuses `apps_enabled` for any set naming it (`"Unknown app(s): ..."`), so an operator can never turn it @@ -196,7 +242,7 @@ registry, so a newly-registered app gets a checkbox for free. 4. **i18n**: at minimum, a `group.tab_<name>` key (the tab's tooltip/label, reused as the Settings checkbox label) in all ten `static/locales/*.js` files. `test_locales.py` holds them to the same key set. -5. **`webapp.py`'s `_ASSETS`** tuple: add the new file. This is the +5. **`webapp.py`'s `_ASSETS`** tuple: add both new files. This is the cache-busting hash's input list — a file imported by the page but missing here can change without the served URL changing, which is the exact bug class `test_asset_versioning.py` exists for. Forgetting this step used to be @@ -216,6 +262,11 @@ registry, so a newly-registered app gets a checkbox for free. No protocol change, no hub change, no `daemon.py` change — steps 3 and 6 are the only node-side touches, and both are allow-lists, not new wire messages. +Directories in particular need nothing server-side at all: `app_directories` is +one generic op keyed by the app's name (§3), and an app storing its folders +under a key nobody wrote code for is the case +`test_app_directories.py::test_an_app_nobody_wrote_code_for_stores_its_directories` +pins. ## 5. What does not exist yet diff --git a/docs/refactor-groups.md b/docs/refactor-groups.md index 3d7412b..f94a18b 100644 --- a/docs/refactor-groups.md +++ b/docs/refactor-groups.md @@ -1,14 +1,14 @@ # Groups Refactor — Per-Root Permissions & App Plugin Architecture -> Status: **Phase 1 complete and reviewed** (2026-09-06). Phase 2 and 3 not started. +> Status: **Phases 1 and 2 complete** (2026-09-06). Phase 3 not started. > > This is the most significant refactoring of the project. It changes how roots > are permissioned, how group applications are configured, and how the Settings > and Create Group pages are structured. > > §7b records what the review of Phase 1 found and how the plan below was wrong -> where it was wrong. Read it before starting Phase 2 — two of its entries are -> rules the later phases have to follow, not one-off fixes. +> where it was wrong; §7c does the same for Phase 2. Read both before starting +> Phase 3 — several entries are rules rather than one-off fixes. --- @@ -752,3 +752,69 @@ configured directory. - `test_ops.py::test_a_backslash_path_written_into_node_toml_stays_parseable` fails on any non-Windows machine and always has — it builds a `PurePosixPath` from a Windows path. Unrelated to this refactor, left alone. + +--- + +## 7c. Phase 2 as built (2026-09-06) + +The plan held. Four things were done differently, and one of them is a rule. + +### The rule + +**A settings key added to the client must be added ten times.** `test_locales` +holds the nine other catalogues to `en.js`, so a missing key is a failing test +rather than a silent gap — but Phase 2 added 27 keys, and doing them one file +at a time is how the Phase 1 gap happened. Write the table, generate the +insert. + +**And a second one, which cost a bug in this phase:** `node --check foo.js` +does **not** reliably report a module syntax error. It accepted a file with +`${/* ... */''}` — htm template syntax, pasted into a plain object literal — +and reported success. Copying to `.mjs` first forces the module parser, which +reports it. `test_spa_syntax.py` now does that for every module; the suite had +no syntax check at all before, which is how the file was committed. + +### Done differently + +- **No migration script.** The plan (§4.3) called for one to rename + `video_root` → `video_directories` in `roster.db`. Instead the roster falls + back to the old key when the new one is unset, and the first save through the + new path leaves it behind. A script that has to be run by hand on the machine + where it matters is a step that does not happen; a fallback is one that + cannot be skipped. +- **`music`, not `audio`.** The app's registry key was `music` while its + storage said `audio_root` and its ops said `set_audio_root`. One identifier + per app now — the registry key — with the correspondence in exactly one + table (`Roster.LEGACY_DIR_KEYS`). +- **One storage shape.** `set_app_directory` (single) writes a one-element + list, so there is no scalar form anywhere below the wire. `video_root` and + friends survive on the handshake ack only, *derived* from the list rather + than stored beside it — a second stored value drifts within one run, which + reads as "it works after a restart". +- **The panes call the transport themselves.** The plan had every pane report + through one `onSave`, which would have made the page a dispatcher naming + every app's settings keys — the thing the phase exists to remove. The line + is: what every app has (directories) the page does, generically; what one + app alone has (a TMDB key, a link-preview switch) the pane does with the + transport it is handed. An app that only wants directories touches neither + file, which is `test_app_settings_plugin.py`'s subject. + +### Worth knowing + +- `settings-ui.js` exists because `group-settings` → `apps` → a pane → + `group-settings` is an import cycle, and ES modules answer that with a + temporal-dead-zone `ReferenceError` at first render — the component simply + does not appear, which is the fault already recorded in CLAUDE.md about hook + ordering. The shared widgets live outside both. +- The folder picker asks the node for **nothing**. The tree is derived from + paths the client already holds, so it shows what the group's index contains + and no more — a folder the node never indexed does not exist as far as the + group is concerned. There is no folder-browsing protocol and this does not + add one. +- `_ASSETS` in `webapp.py` had to grow by six. Modules reached through the + registry rather than imported by name are exactly the ones nothing else would + notice changing, and a stale one is served from a browser cache with no + version bump. `test_asset_versioning` caught it. +- **What Phase 3 still owes:** the HelloWorld app (§4.1) — which is the actual + proof of the above, since every test here reads source rather than adding an + app and watching it work — plus the CLI polish and the Windows pass. |