72 lines
3.3 KiB
Markdown
72 lines
3.3 KiB
Markdown
# 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 (cutover performed)
|
|
|
|
The internal `app`/`pipeline`/`project`/`erf`/`gff`/`topdata`/`music`/`changelog`/
|
|
`validator` packages from `gitea/sow-tools` have been migrated into this tree, and
|
|
the `module`, `topdata`, `hak`, and `wiki` builders now **delegate to the migrated
|
|
`nwn-tool` command surface** (mapped in
|
|
[`docs/command-surface.md`](docs/command-surface.md)). `config` and `changelog`
|
|
are global commands on the dispatcher. `depot` has no migrated logic yet, so it
|
|
keeps the fail-closed path: exit `70`, never a faked artifact.
|
|
|
|
See [`docs/migration-from-nwn-tool.md`](docs/migration-from-nwn-tool.md) for what
|
|
was done and what remains (the consumer `--manifest/--source/--out` flag contract
|
|
is the open Phase-6 item).
|
|
|
|
## 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).
|