sow-tools/README.md

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 — 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.