archvillainette
a131b25e5b
Builds sow-tools#53. Format spec followed is the resolution comment of sow-platform#94, checked line by line against niv/neverwinter.nim at HEAD (`nwsync.nim`, `compressedbuf.nim`, `nwsync/private/libupdate.nim`). ## What lands `crucible nwsync emit <artifact> --out DIR` — explodes one `.hak`/`.erf`, or one loose file such as the TLK, into NWSync blobs plus a NSYM v3 manifest covering only that artifact, with the same `.json` sidecar upstream writes. Blob path `data/sha1/<h0h1>/<h2h3>/<sha1>`, body in NWCompressedBuffer framing (magic `NSYC`, version 3, algorithm 2, uncompressed size, zstd header version 1, dictionary 0, raw zstd frame). The sha1 that names a blob is over the uncompressed bytes. `crucible nwsync assemble --order NAMES --entries DIR --out DIR [--group-id N]` — merges the per-artifact manifests into one, reading no bulk data at all. Merge rule is resref shadowing, not concatenation: a resref in more than one artifact resolves to the earliest artifact in `--order`, which is how the game resolves it. `--group-id` stays caller-supplied (1 current, 2 testing; 0 is absent, matching upstream omitting a zero integer meta field). Rules taken from upstream and not re-invented: `nss`/`ndb`/`gic` always skipped; an unresolvable restype is a hard error, not a skip; a resource over 15 MB fails closed; no `latest` file and no `.origin` file, ever. A `.mod` is refused outright — a persistent world publishes no module contents, so the module contributes no bytes. ## Two deliberate departures - **Emitter version is its own field, not the build revision.** `emitter_version` is a constant bumped only when emitted bytes change. Keying the refuse-to-merge check on `created_with` would invalidate every published index on every unrelated crucible commit and force a re-emit of the whole 15 GB corpus — the opposite of "nothing downstream ever needs the hak again". - **`SOURCE_DATE_EPOCH` pins the sidecar timestamp.** The manifest itself was already deterministic; the sidecar's `created` was not, against the determinism rule in `docs/consumer-contract.md`. ## Not in this PR, and why - **Direct upload.** Only the local `--out` sink exists, which is the conformance path. The upload sink and the mid-hak-failure question are sow-tools#60, and the consumer wiring is #65. - **The conformance run against upstream.** sow-tools#59 owns getting `nwn_nwsync_write` running and capturing reference output. The format here was read from upstream source rather than from its output, so the byte-for-byte manifest comparison and the after-decompression blob comparison still have to happen — that is what #59 is for. The tests in this PR check the layout against the spec, so a shared misreading would pass them. - **The `artifacts/haks/sha256/<a>/<b>/<sha256>.nsym` location.** emit writes `<out>/<name>.nsym`; where a publisher puts it is the publisher's business (#65). - **The acceptance gate** — a real client syncing from an assembled manifest — is unchanged and still open. ## Checks `make check` green (vet, unit tests, shellcheck, yamllint, workflow contract), `make smoke` green with the new builder, `nix build .#crucible` produces `crucible-nwsync`. 🤖 Generated with [Claude Code](https://claude.com/claude-code)Reviewed-on: #71 Co-authored-by: vickydotbat <vickydotbat@tutamail.com>
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-nwsync |
crucible nwsync |
NWSync blob emit + manifest assemble |
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 (cutover performed)
The internal app/pipeline/project/erf/gff/topdata/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). 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 for what
was done and what remains (the consumer --manifest/--source/--out flag contract
is the open Phase-6 item).
Quick start (no Nix)
Teammates without Nix don't build anything — they run the bootstrap wrapper,
which downloads the latest released crucible for your OS and runs it:
./crucible # interactive menu (pick a command)
./crucible module build
./crucible topdata validate
Windows (PowerShell):
.\crucible.ps1 module build
The binary is cached under ~/.cache/crucible/<version>/ (%LOCALAPPDATA%\crucible
on Windows); --repo-local caches inside the repo instead. Private releases:
set CRUCIBLE_TOKEN or write the token to ~/.config/crucible/token.
Develop
Self-contained (D8) — a host with only Nix can run everything:
nix develop # Go + 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
Binaries are never committed — they are CI artifacts (D19).
This retires the old habit of checking in nwn-tool / sow-toolkit.
CI
PR-first (D7): checks run once on pull requests; the only publish event is a
v* tag (see runbooks/ci-trigger-standard.md in sow-docs,
https://git.westgate.pw/ShadowsOverWestgate/sow-docs).
ci.yml— vet, test, shellcheck, yamllint, binary smoke, and cross-build all targets once per pull request.build-binaries.yml— on av*tag, cross-build and upload the binaries,SHA256SUMS, and the wrappers to the Gitea release, then delete the assets of every release except the newest two — Gitea keeps them forever otherwise, and every binary is reproducible from its tag.sync-wrappers.yml— on amainpush that toucheswrappers/, auto-PR the canonical wrappers to the consumer repos inwrappers/consumers.txt. Consumer drift checks run after those PRs merge tomain, not on the PRs themselves, to avoid recursive cross-repo checks.
Consumers
How the artifact repos resolve a Crucible binary is
documented in docs/consumer-contract.md.