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.
This commit is contained in:
+20
-13
@@ -6,13 +6,13 @@ Everything the `/system-monitor` web screen renders, for building the same in th
|
||||
|
||||
- Send the JWT as **`Authorization: Bearer <token>`**, or as **`?token=<token>`** in the query string
|
||||
(required for the SSE endpoints — `EventSource` can't set headers).
|
||||
- **Owner-only.** These routes belong to the `server-admin` capability, which is `kind: 'admin'` and
|
||||
- **Owner-only.** These routes belong to the `server-admin` permission, which is `kind: 'admin'` and
|
||||
therefore never grantable — a non-owner account gets `403` here whatever its role. The full
|
||||
**officer-mobile** client (which authenticates as the owner) has access; the music app does not.
|
||||
- Note for anyone who read this before 2026-08-07: the old rule was that non-owner accounts were
|
||||
confined to a hardcoded `/api/auth` + `/api/music`. That list is gone, replaced by per-role
|
||||
capability grants. The *outcome* for these routes is unchanged — still owner-only — but the reason is
|
||||
now the capability's kind, not a two-element array.
|
||||
permission grants. The _outcome_ for these routes is unchanged — still owner-only — but the reason is
|
||||
now the permission's kind, not a two-element array.
|
||||
- All responses are `application/json` except the two `/logs` endpoints, which are `text/event-stream`.
|
||||
|
||||
---
|
||||
@@ -20,7 +20,7 @@ Everything the `/system-monitor` web screen renders, for building the same in th
|
||||
## `GET /api/system-monitor/stats`
|
||||
|
||||
One full snapshot. Poll it on a steady interval (the web client uses **2 s**) — a few fields are rates
|
||||
computed from the delta since your *previous* call (see notes), so a steady cadence matters.
|
||||
computed from the delta since your _previous_ call (see notes), so a steady cadence matters.
|
||||
|
||||
```jsonc
|
||||
{
|
||||
@@ -65,6 +65,7 @@ computed from the delta since your *previous* call (see notes), so a steady cade
|
||||
```
|
||||
|
||||
**Notes**
|
||||
|
||||
- `net.*BytesPerSec` and `power.cpuWatts` are **deltas since the previous `/stats` call**. The **first**
|
||||
call returns `0`/`null` for these; steady-interval polling gives stable numbers.
|
||||
- `cpuWatts` is usually `null` — RAPL `energy_uj` is root-only unless a udev rule opens it. `gpuWatts` works.
|
||||
@@ -77,16 +78,18 @@ computed from the delta since your *previous* call (see notes), so a steady cade
|
||||
```jsonc
|
||||
{
|
||||
"processes": [
|
||||
{ "id": 0, // pm2 id (pm_id) — use this for the logs endpoint
|
||||
{
|
||||
"id": 0, // pm2 id (pm_id) — use this for the logs endpoint
|
||||
"name": "officer",
|
||||
"status": "online", // online | stopped | errored | …
|
||||
"pid": 3339851, // OS pid, or null
|
||||
"status": "online", // online | stopped | errored | …
|
||||
"pid": 3339851, // OS pid, or null
|
||||
"cpuPct": 0,
|
||||
"memBytes": 10354688,
|
||||
"restarts": 44,
|
||||
"uptimeMs": 420000 } // 0 unless status === "online"
|
||||
"uptimeMs": 420000,
|
||||
}, // 0 unless status === "online"
|
||||
],
|
||||
"error": "…" // present only if pm2 couldn't be read
|
||||
"error": "…", // present only if pm2 couldn't be read
|
||||
}
|
||||
```
|
||||
|
||||
@@ -95,14 +98,16 @@ computed from the delta since your *previous* call (see notes), so a steady cade
|
||||
```jsonc
|
||||
{
|
||||
"containers": [
|
||||
{ "id": "abc123def456", // short id (12 chars) — use for the logs endpoint
|
||||
{
|
||||
"id": "abc123def456", // short id (12 chars) — use for the logs endpoint
|
||||
"name": "jellyfin",
|
||||
"image": "jellyfin/jellyfin",
|
||||
"state": "running", // running | exited | …
|
||||
"state": "running", // running | exited | …
|
||||
"status": "Up 3 hours",
|
||||
"ports": "0.0.0.0:9301->8096/tcp" }
|
||||
"ports": "0.0.0.0:9301->8096/tcp",
|
||||
},
|
||||
],
|
||||
"error": "…"
|
||||
"error": "…",
|
||||
}
|
||||
```
|
||||
|
||||
@@ -114,12 +119,14 @@ Both stream one **`data: <log line>`** frame per line, plus `: hb` heartbeat com
|
||||
server kills the underlying tail when the connection closes. Open with `EventSource` using `?token=`.
|
||||
|
||||
### `GET /api/system-monitor/pm2/logs?id=<pm_id>&lines=<n>`
|
||||
|
||||
- `id` — **numeric** pm2 id from `/pm2` (required).
|
||||
- `lines` — initial backlog, default `100`, max `1000`.
|
||||
- Source: `pm2 logs <id> --raw` (combined stdout+stderr, follows live). The first frames include a short
|
||||
pm2 `[TAILING] …` header.
|
||||
|
||||
### `GET /api/system-monitor/docker/logs?id=<container>&lines=<n>`
|
||||
|
||||
- `id` — container id or name from `/docker` (charset-validated).
|
||||
- `lines` — initial backlog (`--tail`), default `100`, max `1000`.
|
||||
- Source: `docker logs -f --tail <n> <id>` (combined stdout+stderr).
|
||||
|
||||
Reference in New Issue
Block a user