naudachu
1815d91cdf
A discussion leaves behind a directory of markdown somewhere outside this repo, and the only durable home for it is the Gitea wiki. Getting it there by hand means re-deriving the same three things every time: what each file should be called, where it goes, and whether the page already exists. Two skills wrap that, along the split the repo already uses. `skills/page` is domain, offline, stdlib-only, and knows nothing about Gitea. It imports a directory into a space under `tmp/wiki/`, titles every file, records the result in `.pages.json`, and writes the index. `skills/wiki` is the bridge — `wikimap.py` translates, and the transport is `_gitea.py`, the same one the issue side uses. There is no second transport, and `tea` has no wiki subcommand to offer one. The Gitea wiki is flat, and that fact shapes everything There are no directories. A title of `a/b` is stored as one file named `a%2Fb.md`, and Gitea escapes it by rules of its own: space becomes `-`, `/` becomes `%2F`, and a literal `-` forces a trailing `.-` marker so the two stay distinct. `Chain decisions — DC` under two levels of prefix comes back as `Simple-Chains%2FParked%2FChain-decisions-%E2%80%94-DC`. So `sub_url` is the identity, it is read back from whatever the API returned, and it is never constructed. One built by hand that is almost right does not fail — it creates a second page and abandons the first. And a real subdirectory committed into a wiki's git repository is a ghost: the file exists, the API and the web UI do not see it. `folder/page.md` in this repo's own wiki is one. Nothing here clones a wiki repo. A title is a decision, not a derivation Titles come from the first heading, because there is no mechanical route from `03-q-01-do-we-know-the-chain-participant-by-name.md` to `Q-01. Do We Know the Chain Participant by Name`. But they are derived exactly once. A re-import replaces bodies and keeps titles, so editing a heading cannot rename a published page — which would not rename it, it would publish a second one. `--retitle` opts in. It finds the prior entry by `source` rather than by path, because the path is derived from the title and a retitle moves it; looked up by path the page would read as new and the next push would duplicate it. The old file goes, `sub_url` comes along, and `pushed` is cleared — a rename can leave the body byte-identical, and push decides by body hash alone, so a stale hash would skip the rename forever. Ordering is a `NN-` file-name prefix and never reaches the title. `00-` means "this is the directory's own page", and that page is named for the directory, not for its own heading: a child's title has to extend its parent's exactly, and `ideas/00-intro.md` opens with "Ideas for chain business requirements". Path collisions are reported and never resolved. Picking a winner is how a discussion loses a document. The index is navigation, not decoration Nothing draws a tree from flat titles. `page_index.py` writes one as an ordinary page, nested by title depth rather than by manifest path order — those disagree, since on disk `Top/System.md` sorts before `Top/Ideas/Scale.md` while in the hierarchy System is a child and Scale a grandchild. A parent with no page of its own still gets a node, so its children are not hidden. Links use `sub_url` when there is one and Gitea's `[[Title|label]]` syntax when there is not, so the order is push, rebuild, push. The same stances as the issue store, for the same reasons Pull overwrites, push is additive and never deletes, change detection is one hash and there is no drift model. A page with no `sub_url` has never been published, and that is a durable state. Issues gain a `wiki:` field holding page titles — titles, not URLs, so the reference stays in the domain. It already round-trips as a foreign key; this documents it. Verified against a live Gitea 1.26.1: create, update with a message, unchanged-skip, prefix-filtered pull, byte-identical round trip, and the per-page revision history carrying the operator's own words. The probe pages were deleted afterwards. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
5.1 KiB
name, description
| name | description |
|---|---|
| wiki | Move wiki pages between a local space and Gitea — fetch a page and everything under it as a local cache, publish a page tree with an update message, list what the wiki holds. Load when the user asks to read/fetch a wiki page, cache a wiki subtree for a discussion, or publish artifacts to the wiki. Organizing artifacts into a page tree (titles, ordering, the index) is /tea:page and needs no network. |
/tea:wiki — the bridge between a local space and a Gitea wiki
One job: translate between tmp/wiki/<space>/ and Gitea's wiki JSON, and carry
the result over the wire. Everything about what a page tree is — titles,
ordering, paths, the index — belongs to /tea:page and is imported from there,
never redefined here.
Transport is tea api through skills/sync/scripts/_gitea.py: the same login
pin, the same pagination, the same payload files. There is no second transport.
The wiki is flat, and that is the whole design
Gitea's wiki is a list of pages, not a tree. Nesting exists only inside a
title, as /, and Gitea escapes that title into a filename by rules that are
its own:
| title | sub_url |
|---|---|
Abstract Issue |
Abstract-Issue |
zz-probe/child |
zz-probe%2Fchild.- |
Simple Chains/Parked/Chain decisions — DC |
Simple-Chains%2FParked%2FChain-decisions-%E2%80%94-DC |
sub_url is the identity and is never constructed. It is read back from
the API and stored in the manifest. Building one by hand that is almost right
does not fail loudly — it creates a second page and abandons the first.
Never commit a subdirectory into the wiki's git repository. A real
folder/page.md is invisible to the API and to the web UI. It is a ghost file.
Do not clone the wiki repo to work in; use these scripts.
Scripts
In <skill-base-dir>/scripts/.
| Script | What it does |
|---|---|
wiki_ls.py [--prefix T] |
what the wiki actually holds — titles, sub_url, last commit. One call, no bodies |
wiki_pull.py [--prefix T] [--space S] |
fetch a page and everything under it into a local space |
wiki_push.py -m MSG [--prefix T] [PATH…] |
publish; create what is new, update what changed, skip what is not |
wikimap.py |
md ↔ wiki JSON, pure — not a command |
Fetching a subtree as a cache
"A page and its children" is a prefix test on the title, run against one listing call, followed by one GET per page. There is no tree endpoint and no bulk-body endpoint.
python3 scripts/wiki_ls.py --prefix "Simple Chains" # what is there
python3 scripts/wiki_pull.py --prefix "Simple Chains" # cache it locally
A pull overwrites the local body — a fetch, not a merge. synced tells you
how old your copy is; re-pull when it matters. Nothing tracks drift.
The space defaults to the repo's own owner/repo, so a pull with no flags
caches this repo's whole wiki into tmp/wiki/<owner>/<repo>/.
Publishing
python3 scripts/wiki_push.py -m "Import the simple-chains discussion" --dry-run
python3 scripts/wiki_push.py -m "Import the simple-chains discussion"
-m is required and is the wiki commit message — the only record of why a page
changed, and it shows up in wiki/revisions/<sub_url>. One operation, one
message.
Change detection is a hash: a page whose file matches pushed is skipped.
A page with no sub_url is created; one with a sub_url is edited in place,
using the title from the manifest — sending a different title to the edit
endpoint is a rename and leaves nothing at the old address.
Selection, narrowest first: positional PATH-or-TITLE arguments (matched
exactly), then --prefix, then the whole space.
Pushing is additive. A page deleted locally is not deleted in the wiki.
Removing a published page is an explicit act — the web UI, or
tea api --login "$GITEA_LOGIN" -X DELETE repos/{owner}/{repo}/wiki/page/<sub_url>.
Order of operations for a fresh tree
The index links published pages by sub_url, which does not exist until the
first push. So:
python3 ../page/scripts/page_import.py --from DIR --prefix "Simple Chains"
python3 scripts/wiki_push.py -m "Import the simple-chains discussion"
python3 ../page/scripts/page_index.py --prefix "Simple Chains" # now with real links
python3 scripts/wiki_push.py -m "Index"
Linking an issue to a page
An issue's wiki: field holds page titles, not URLs — a title is a name for
a document and stays in the domain; the URL is bookkeeping. wiki_ls.py --titles prints them one per line, which is what to paste.
Endpoints, for when a script is not enough
Reach for /tea:use and tea api directly only for what has no script — a
delete, or a page's history.
| list | GET repos/{owner}/{repo}/wiki/pages |
| read | GET repos/{owner}/{repo}/wiki/page/{sub_url} |
| create | POST repos/{owner}/{repo}/wiki/new — {title, content_base64, message} |
| edit | PATCH repos/{owner}/{repo}/wiki/page/{sub_url} — same body |
| delete | DELETE repos/{owner}/{repo}/wiki/page/{sub_url} |
| history | GET repos/{owner}/{repo}/wiki/revisions/{sub_url} |
The tea CLI has no wiki subcommand. tea api is the only route.