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.
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.
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.
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:
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— buildregistry.westgate.pw/sow/crucible:<sha>; publish only onmain. 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.