A guide can be carried to another site
All checks were successful
CI / naming (push) Successful in 4s
CI / frontend (push) Successful in 12s
CI / migrations-mysql (push) Successful in 40s
CI / backend (push) Successful in 3m32s

Guides are written on one site and needed on all of them, and the sites that
matter are air-gapped from wherever the writing happens. Until now a procedure
was stranded in the database it was typed into: the HTML importer could rebuild
one from its original article, but anything authored in the editor had nowhere
to go.

flask guides export writes one .guide.json per guide, with every image the
blocks reference carried inside it as base64. One file on purpose - a bundle
that needs its images copied alongside it is a bundle that will eventually
arrive without them. flask guides import reads them back, a directory at a
time, and refuses anything that is not a bundle before it writes a row rather
than half-importing a stray .json sitting in the same folder.

What travels is the content: title, summary, tags, blocks, images. What does
not is ids, revision history, authorship and publication state, because those
belong to whichever database issued them - an imported guide starts as a draft
at revision 1, owned by whoever ran the import. The SLUG does travel: it is the
address somebody pastes into a work order, and the same guide should answer to
the same name on every site.

--replace updates the guide already carrying that slug instead of creating a
second one, which is how a corrected guide is re-shipped. It drops the stored
images first: the incoming bundle is the whole truth for that guide, and a
guide re-shipped monthly would otherwise accumulate orphans nothing points at.

Bundles refuse a version they are too old to read rather than importing the
parts they recognise. A newer site's guide is not a guide this one can be
trusted to render.

Proven by round-tripping a five-guide export back into the same site, including
one carrying two PNG screenshots, and reading it in a browser.
This commit is contained in:
cproudlock
2026-08-27 11:46:50 -04:00
parent c8efadefba
commit 8531559f22
5 changed files with 470 additions and 7 deletions

View File

@@ -22,6 +22,19 @@ ADR-007 and ADR-002.
tables; in self-hosted mode one stored loan expands into a take and a return,
so a returned drive is distinguishable from one still out.
- **`flask guides export` / `flask guides import` - a guide can reach another
site.** Sites are separate databases and the ones that matter are air-gapped
from wherever a guide gets written, so a procedure written once was stranded
where it was typed. Export writes one `.guide.json` per guide with its images
carried inside it - one file, because a bundle that needs its images copied
alongside it is a bundle that will eventually arrive without them - and
import reads them back. The slug travels, since that is the address somebody
pastes into a work order and the same guide should answer to the same name on
every site; ids, revision history and publication state do not, because those
belong to the database that issued them. Imports arrive as drafts;
`--replace` updates a guide already carrying that slug rather than creating a
second one, which is how a corrected guide is re-shipped.
- **`flask guides import-html` - an existing HTML article becomes a guide.**
A site adopting this app arrives holding procedures already written: styled
HTML pages that get mailed around and opened off a share. Retyping one into