mesh-tools
652b00b25b
Every directory and archive resource carries `unknown`: move-out for a home folder whose program writes nothing there (the node-engine, delivered in mesh-host #117, moves the rest to ~/.local/state/mesh-moved/<module>/ with a list), module for ~/.ssh and ~/.claude, program elsewhere; `knows` keeps what a program or the operator relies on (powerlevel10k's compiled files, i3's scripts and the asus/g14 drop-ins, dunst's slack rule, betterbird's records, node-env's forge credential, issue 1033). Two shared folders are no longer declared. Each module's README says it. checks/owned holds every manifest to it; checks/sshdir stays while main's merge check runs it (issue 1035). Tests that pin a manifest follow the new key only. Reviewed in three rounds.
records
The record, read where it is written (novox/hq ADR 0025, ADR 0153).
A module that keeps a checkout of a repository of decisions, designs and issues — the mesh's own
hq, or any repository of markdown on the forge — and answers questions about it over the bus, so
whoever holds the console sees records_search beside every other tool and a symptom can be looked up
in the design record without knowing it is there.
A checkout, not a copy. The same bytes the repository holds, at a commit every answer names,
brought up to date on every merge the forge announces (gitea.pull.merged) and every ten minutes
besides. Nothing is indexed, transformed or summarised, so nothing can drift from the source except by
lagging behind it, and the lag is in records_status.
Tools
| tool | answers |
|---|---|
records_search {query, limit?} |
where a phrase appears, as written: document, line, nearest heading, and the commit read |
records_read {path} |
one document, whole |
records_list {folder?} |
what a folder holds |
records_decisions {topic?} |
retired (hq issue 488): refuses, naming the knowledge base's knowledge-base.holds, ask and get. The decision records and research efforts live in the knowledge base (hq ADR 0290), and an index read from an emptied 02-DECISIONS would answer every topic empty as a success |
records_status |
repository, forge, commit and its date, last sync, document count, last error |
records_sync |
bring the checkout up to date now |
Configuring it
The module names no mesh (ADR 0112). It requires the git provision — the forge — and reads the
repository its settings name:
settings set records repository.json # {"repository": "<owner>/<name>"}
Public repositories only: it asks for no credential. Until a repository is set, it serves no tools and says so in its log.
The check ADR 0025 names
Search the mesh, through the console, for a phrase that appears only in one design document here, and
get it back. records_search {"query": "…"} is that search; its test does the same against a
repository it makes.
Where the checkout lives
A Go bundle the node's runtime launches as the operator account (cmd/records). It clones into
repository/ inside the directory the mesh gives it — a directory it makes, and so owns. An earlier
layout cloned into the given directory itself, from a container running as root, and left files the
operator account cannot change; git then refused every sync as "dubious ownership" (hq issue 251). What
that layout left is removed where it is the module's, and named in records_status (leftBehind, with
the one command that deletes it) where it is not.
Files it does not know
Each directory or archive this module declares says how it treats a file it did not write (ADR 0422, ADR 0416).
${dir:mesh-state}: everything in it is the program's; the mesh moves nothing out (ADR 0422 §2).${dir:checkout}: everything in it is the program's; the mesh moves nothing out (ADR 0422 §2).