1de026ca43
The account this was built against is in no rooms, so the whole space was invisible and easy to dismiss as an empty endpoint. It is not empty in general — the user had rooms until a teacher removed access — and the UI's naming actively hides the distinction: the sidebar's *Kurse* entry links to `/rooms/courses-overview` and lists courses, while *Räume* links to `/rooms` and lists rooms. A url containing `/rooms` identifies neither. list_rooms and get_room cover the latter. A room holds boards and nothing else, so get_room lists boards for get_board (which already reports "in room" from the board context) plus who else is in it. Room boards report `isVisible`, which the course-page projection does not, so a draft is named as a draft instead of being offered and then answering 403. Rooms also go through the crawl, or they would have become the next blind spot: their boards are indexed, searchable by both the index and the live-crawl path, diffed by what_changed, and mirrored by the CLI under the room's name. The board traversal and the snapshot matcher are now shared between courses and rooms rather than duplicated, which also fixed the live-crawl path silently not searching pad contents. The CLI needed no new command — it is file-centric and inherits rooms through the manifest — but `--course` now accepts a room id, and says so. `kind` gains 'room'; the column is plain TEXT, so no migration. 112 tests. Smoke: 42/42 and 44/44 local, 41/41 and 43/43 live. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
109 lines
4.6 KiB
Markdown
109 lines
4.6 KiB
Markdown
# The `schulcloud` CLI
|
|
|
|
Browses and mirrors your Schulcloud files from a laptop, by talking to the
|
|
schulcloud-mcp server on the Pi.
|
|
|
|
## Why it goes through the Pi
|
|
|
|
The CLI never talks to Schulcloud. It holds no `jwt` cookie, no Schulcloud
|
|
credential of any kind — only this server's bearer token.
|
|
|
|
That is not an accident of layering; it solves a real problem. A Schulcloud
|
|
session dies after two hours of inactivity, and a CLI process lives for seconds,
|
|
so a CLI with its own token would be dead most times you reached for it. The Pi
|
|
already keeps one session alive around the clock. Routing through it means one
|
|
session, one keepalive, and one place to paste a fresh cookie once a month.
|
|
|
|
It also means the laptop cannot accidentally end the server's session: nothing
|
|
here can call logout.
|
|
|
|
## Setup
|
|
|
|
```bash
|
|
schulcloud login --server https://mcp.example.org --token <MCP_AUTH_TOKEN> --dir ~/Schulcloud
|
|
```
|
|
|
|
The token is the same `MCP_AUTH_TOKEN` the Claude connector uses — one token
|
|
guards both surfaces. `login` verifies it before saving, so a typo fails
|
|
immediately rather than on first real use. Config is written to
|
|
`~/.config/schulcloud/config.json` with mode `0600`.
|
|
|
|
`SCHULCLOUD_SERVER`, `SCHULCLOUD_TOKEN` and `SCHULCLOUD_SYNC_DIR` override the
|
|
file, for CI or one-off invocations.
|
|
|
|
## Commands
|
|
|
|
```
|
|
schulcloud status how fresh the server's index is
|
|
schulcloud ls [--course <id>] [--long]
|
|
schulcloud get <fileId> [--out <path>]
|
|
schulcloud sync [--dry-run] [--full] [--prune] [--dir <path>] [--jobs <n>]
|
|
schulcloud refresh [--course <id>] [--force]
|
|
```
|
|
|
|
`ls --long` prints file ids, which is what `get` takes.
|
|
|
|
`--course` accepts a **course or a room id** — rooms ("Räume") are mirrored
|
|
alongside courses, with their files under the room's name rather than a course's.
|
|
|
|
`refresh` asks the server to re-read Schulcloud. Pass `--course` when you know
|
|
what changed: that is a handful of requests, where a full re-crawl reads every
|
|
course. The server refuses a repeat within a minute unless you pass `--force`.
|
|
|
|
## How sync works
|
|
|
|
It is a **one-way mirror, not a two-way sync**, and that follows from the data
|
|
rather than from laziness: Schulcloud file records are immutable — editing a
|
|
file upstream produces a *new* record — so there is no content versioning, no
|
|
conflict resolution and no merge. "Download what I do not have" is the whole
|
|
algorithm.
|
|
|
|
Local state lives in `.schulcloud-sync.json` at the root of the sync directory,
|
|
**keyed by file record id with the path as derived output**. That is what makes
|
|
renames cheap: when a teacher renames a board column, the file moves on disk
|
|
instead of being downloaded again under a new name and left duplicated under the
|
|
old one.
|
|
|
|
What it checks, and why only that:
|
|
|
|
- **Size**, not a checksum. The download endpoint exposes no `ETag` and
|
|
Schulcloud publishes no hash, so verifying content would mean re-downloading
|
|
every file to learn what it already told us. Size reliably catches the failure
|
|
that actually happens — a truncated or interrupted download — and costs a
|
|
`stat`.
|
|
- Downloads land on a `.part` neighbour and are renamed into place, so an
|
|
interrupted run never leaves a half-file that a later run mistakes for
|
|
complete.
|
|
|
|
**Deletions are not propagated by default.** A teacher removing a worksheet is
|
|
not a reason to destroy your copy of it; `sync` reports those as "gone upstream,
|
|
kept". Pass `--prune` to actually delete them.
|
|
|
|
`--dry-run` prints exactly what would happen, writes nothing, and does not
|
|
advance the cursor.
|
|
|
|
## Cursors
|
|
|
|
The server's sync cursor is a **crawl generation id**, not a timestamp. This is
|
|
deliberate and measured: `GET /course-rooms/{id}/board` returns the *request
|
|
time* as `updatedAt` for most elements, so a timestamp cursor would report every
|
|
board as changed on every crawl. Comparing generations by identity also detects
|
|
deletions, which no timestamp scheme can.
|
|
|
|
`--since` on the server API accepts an ISO date for convenience, resolved to the
|
|
nearest generation — but correctness never depends on it.
|
|
|
|
If the server no longer recognises your stored cursor it returns `409` rather
|
|
than silently treating everything as new, so you are never tricked into
|
|
re-downloading the world. Run `sync --full` deliberately in that case.
|
|
|
|
## Paths
|
|
|
|
Mirror paths are `Course/Board/Card/filename`, built by `core/paths.ts`.
|
|
|
|
Every component of that path originates in Schulcloud — course titles, card
|
|
titles and filenames are all user-supplied upstream — so each is reduced to a
|
|
single safe path component, and the result is re-checked against the sync root
|
|
before anything is written. A file named `../../.ssh/authorized_keys` cannot
|
|
escape, and `sync` refuses such an entry rather than writing it.
|