Phase 5: scaffold Crucible (sow-tools) — dispatcher + builder shims, container, PR-first CI, fail-closed (D11, D19).

2026-06-11 20:36:13 +02:00
commit 0d6eb2aeaa
28 changed files with 987 additions and 0 deletions
@@ -0,0 +1,68 @@
+# sow-tools — Crucible
+
+Crucible is the Shadows Over Westgate build/conversion/sync toolchain: one Go
+module producing several small binaries plus a `crucible` dispatcher (D11). It is
+the **only** repo that owns builder logic; the artifact repos (`sow-module`,
+`sow-topdata`, `sow-assets-manifest`) invoke Crucible through wrapper scripts and
+never embed a toolkit.
+
+```text
+Repos produce artifacts.  sow-platform deploys artifacts.
+Crucible is how the artifact repos turn source into artifacts.
+```
+
+## Binaries
+
+| Binary             | Dispatcher form    | Owns                                            |
+| ------------------ | ------------------ | ----------------------------------------------- |
+| `crucible`         | —                  | dispatcher: `crucible <builder> [args]`         |
+| `crucible-depot`   | `crucible depot`   | content-addressed depot blob verify/move        |
+| `crucible-hak`     | `crucible hak`     | ERF/HAK pack/unpack + hak manifests             |
+| `crucible-module`  | `crucible module`  | build/extract/validate/compare the `.mod`       |
+| `crucible-topdata` | `crucible topdata` | compile 2da/tlk topdata + packages              |
+| `crucible-wiki`    | `crucible wiki`    | render + deploy mechanical wiki pages           |
+
+The dispatcher and the standalone shims share one registry
+(`internal/dispatch`); the shims exist so consumer wrapper scripts can resolve a
+single-token command. The full legacy `nwn-tool` command surface and where each
+command lands is mapped in [`docs/command-surface.md`](docs/command-surface.md).
+
+## Status (Phase 5 scaffold)
+
+The suite **builds, vets, tests, and runs**, but every builder is **unwired**:
+running one fails closed with exit `70` and never fakes an artifact. The internal
+pipeline/topdata/erf/wiki/music packages from `gitea/sow-tools` are migrated by
+the operator at cutover — the workspace hard rules forbid transplanting that
+source automatically. See [`docs/migration-from-nwn-tool.md`](docs/migration-from-nwn-tool.md).
+
+This matches the downstream skeletons: `sow-module` / `sow-topdata` package
+scripts already fail closed until they can resolve a Crucible binary.
+
+## Develop
+
+Self-contained (D8) — a host with only Nix can run everything:
+
+```bash
+nix develop            # Go + ffmpeg + shellcheck + yamllint + make
+make check             # go vet + go test + shellcheck + yamllint
+make build             # build every cmd/* into ./bin (gitignored)
+make smoke             # build + assert the fail-closed contract
+make image             # docker build -> crucible:<sha>
+```
+
+Binaries are **never committed** — they are CI artifacts / image layers (D19).
+This retires the old habit of checking in `nwn-tool` / `sow-toolkit`.
+
+## CI
+
+PR-first (D7): every check runs on pull requests and on push to `main`.
+
+- `test.yml` — vet, test, shellcheck, yamllint, binary smoke.
+- `build-image.yml` — build `registry.westgate.pw/sow/crucible:<sha>`; publish
+  only on `main`. PRs build but never push. No mutable tags.
+- `release.yml` — tag-gated binary bundles; image re-tag is wired in Phase 6.
+
+## Consumers
+
+How the artifact repos resolve a Crucible binary (and the `NWN_ROOT` rule) is
+documented in [`docs/consumer-contract.md`](docs/consumer-contract.md).