system-git-sync/scripts/write_modules.py

#!/usr/bin/env python3
"""Write MODULE.md into every in-scope repo (callers, NATS, errors, storage)."""

from __future__ import annotations

from pathlib import Path

R = Path("/Users/marchon/research")
GIT = "https://git.georgelambert.org/marchon"

COMMON = """
This is **not** a HIPAA/SOC 2/ISO certificate.
Vocabulary: see `{git}/system-git-sync` `docs/thesaurus.md`.
Catalog: `{git}/nats-service-endpoints`.
"""

MODULES = {
    "system-git-sync": dict(
        who="Operators and later agents. Nothing publishes NATS from this repo.",
        callers="Humans / CI (`cicd/run-review.sh`, `cicd/deploy-ns1.sh`).",
        frm="Promoted SHAs, inventory, remaining-work.",
        to="Forgejo remotes and ns1 rsync after tests.",
        filt="No auto-deploy. Unsigned config never copied. Websites org inventory-only.",
        err="Review fail aborts deploy. Binary-busy: stop unit then copy.",
        store="Git only. Live signed files are on the host.",
        timeout="SSH/rsync operator-bound.",
    ),
    "nats-service-endpoints": dict(
        who="Every service that publishes `verae.*`.",
        callers="secure-messaging, pfc-py-admin, pfc-repl, pfc-ipfs, sm-leaf.",
        frm="`catalog/endpoints.json` (SM core) + `catalog/pfc-derived.json` (all subjects.json names).",
        to="Sphinx HTML/PDF on docs.pfc `/nats-service-endpoints/`.",
        filt="`reject[]` + `filter` + `timeout_sec`. Forbidden `verae.llm.turn.>`.",
        err="Unknown subject / missing fields → dead letter for SM; others `dead=none`.",
        store="JSON catalog in git.",
        timeout="See each row `timeout_sec` (5s request-reply, 4s queue, 30s pin).",
    ),
    "secure-messaging": dict(
        who="sm-leaf (Go) and pfc-py-admin (Python sign/history).",
        callers="Console send, tests, systemd `pfc-sm-leaf`.",
        frm="`verae.sm.send` envelopes (`to`, `from_lookup_id`, `alg`, `ct`).",
        to="Mailbox dest (clear); ack `lookup_id`. Failures → `verae.sm.error`, `verae.sm.dead`, `verae.sm.log.summary`.",
        filt="Missing `to`, empty `ct` (unless plain-lab), plaintext `body`, bad alg, summary `ct` field.",
        err="Network Error Bundle: `ct_sender` (sender only) + `ct_system` (ops). Never log mail body.",
        store="Signed wrapper path; admin-history JSONL cube.",
        timeout="NATS 5s; NPE seal 15s.",
    ),
    "peergos-for-compliance": dict(
        who="Shared Python lib (`pfc.*`) used by admin, ipfs, repl, connector.",
        callers="pfc-py-admin, tests, Pattern A inspect app outbox.",
        frm="HTTP browsers/CLI; NATS `verae.*` when `NATS_URL` set.",
        to="CubeStore `/PFC_DATA`, stamp leaf `verae.ts.batch`, pin, replicate.",
        filt="Profile validate (k>=2, author not officer); HIPAA bytes need inspect session.",
        err="AccessDenied, ProfileError, NatsError, hash mismatch.",
        store="`cubes/<id>/` chain, catalog card, hash registry.",
        timeout="NATS 5s; stamp sync 15s.",
    ),
    "peergos-for-compliance-admin": dict(
        who="Operators in the browser SPA.",
        callers="https://pfc.georgelambert.org (Caddy → 127.0.0.1:18780).",
        frm="Login/TOTP, cube/catalog/inspect/audit HTTP; NATS when bus configured.",
        to="CubeStore, UserStore, signed config, sm-leaf, pin, repl.",
        filt="`PFC_REQUIRE_AUTH=1`; TOTP for hipaa; k-of-n inspect; unsigned config rejected.",
        err="401 auth, 403 totp/admin, 400 profile, 501 missing signing key.",
        store="`PFC_DATA` users + cubes; host PEM for Ed25519.",
        timeout="HTTP 8s in tests; NATS 5s.",
    ),
    "peergos-for-compliance-ipfs": dict(
        who="Admin object put (pin) and hydrate.",
        callers="pfc-py-admin `verae.storage.pin` / HTTP `/v1/pin`.",
        frm="`sha256`, `bytes_hex`, `cube_id`, `tier`.",
        to="Kubo API localhost:15001 (never WAN 5001).",
        filt="Localhost Kubo only; hash must match bytes.",
        err="Kubo down → health 503 for ipfs backend; pin error JSON.",
        store="Kubo blocks; optional stash dir.",
        timeout="Kubo 30s.",
    ),
    "peergos-for-compliance-replication": dict(
        who="Lab HTTP coordinator. **Live ns1 uses Go pfc-repl** instead.",
        callers="Admin when `NATS_URL` unset (`PFC_REPL_URL`).",
        frm="POST `/v1/replicate` `{bytes_hex, sha256, cube_id}`.",
        to="Replica ingest URLs / `verae.pfc.replica.{a,b}.ingest`.",
        filt="`min_ok` acks including local.",
        err="503 when min_ok not met.",
        store="`PFC_REPL_DATA` files named by sha256.",
        timeout="4s per replica request.",
    ),
    "peergos-compliance-go": dict(
        who="ns1 leaf processes: pfc-repl, pfc-repl-a/b, pfc-configd, (inactive pfc-admin HTTP).",
        callers="systemd. pfc-py-admin health-probes pfc-repl `:18784`.",
        frm="NATS `verae.storage.replicate`, replica ingest, `verae.pfc.health`.",
        to="Local data dir + replica subjects; config UI static files.",
        filt="Coordinator only binds HTTP; ingest replicas NATS-only.",
        err="min_ok failure in replicate JSON; leaf hub parse `nats-leaf://` → `nats://`.",
        store="`/opt/pfc/data/repl`.",
        timeout="4s replica Request.",
    ),
    "peergos-compliance-docs": dict(
        who="Operators and auditors reading docs.pfc.",
        callers="Sphinx build; Caddy `docs.pfc.georgelambert.org`.",
        frm="RST sources + screenshots in `_static/screens/`.",
        to="HTML + LaTeX PDF under `/opt/pfc/docs/html`.",
        filt="No PHI examples; not a certificate.",
        err="latexmk optional; xelatex/pdflatex fallback.",
        store="git + ns1 docs tree.",
        timeout="n/a",
    ),
    "peergos-compliance-architecture": dict(
        who="Design readers. No runtime.",
        callers="Docs and plan repos.",
        frm="Architecture notes for DataCube + Peergos + NATS.",
        to="Links to runtime repos.",
        filt="Inventory; do not contradict signed-config design locks.",
        err="n/a",
        store="Markdown in git.",
        timeout="n/a",
    ),
    "peergos-compliance-config": dict(
        who="Operator building `pfc.json` before signing.",
        callers="Browser SPA `config.pfc.georgelambert.org`, bash/curses TUI, pfc-configd.",
        frm="Host, leaf hub, NATS URL, lab PSK, profile, min_ok.",
        to="Download JSON; **must be signed** (`signed_config.sign`) before load.",
        filt="Unsigned files rejected at load. Live changes append admin-history.",
        err="Invalid schema / missing crypto.mode.",
        store="`~/pfc.json` or host signed path.",
        timeout="n/a",
    ),
}


def render(name: str, m: dict) -> str:
    git = f"{GIT}/{name}"
    return f"""# MODULE — {name}

Git: {git}

{COMMON.format(git=GIT)}

## What this module is

Runtime or documentation unit in the Peergos-for-compliance / secure-messaging
set. See this repo `README.md` for the short intro.

## Who calls this module and why

{m['who']}

**Callers:** {m['callers']}

## Messages — from / to

- **From:** {m['frm']}
- **To:** {m['to']}

## Filters / security

{m['filt']}

## Errors and timeouts

- **Errors:** {m['err']}
- **Timeouts:** {m['timeout']}

## Where data is stored and how others use it

{m['store']}

Walkthroughs and screenshots: `{GIT}/peergos-compliance-docs` (`source/walkthrough.rst`).
"""


def main() -> None:
    hub = R / "system-git-sync" / "docs" / "modules"
    hub.mkdir(parents=True, exist_ok=True)
    for name, meta in MODULES.items():
        text = render(name, meta)
        (hub / f"{name}.md").write_text(text)
        dest = R / name / "MODULE.md"
        if dest.parent.exists():
            dest.write_text(text)
            print("wrote", dest)


if __name__ == "__main__":
    main()