archvillainette
f9051a2c01
Builds the code half of #60, and closes the CLI gap the #53 sweep found: PR #71 shipped #53's original surface rather than the one #56, #62 and #65 settled. ## What lands **`depot.KeyStore`** — `ProbeKey` / `PutReader` / `GetKey`, addressing the zone by object key rather than by depot sha. NWSync cannot use the sha-addressed path: a blob is named after the sha1 of its *uncompressed* bytes while the body uploaded is the compressed form, and Bunny's `Checksum` header is sha256 of the body. Per #55 this reuses `internal/depot`'s `httpBackend` — same IPv4-pinned transport, same retry, same tri-state probe — and the sha-addressed `Backend` is now rewritten on top of it. No second HTTP client, no per-instance hash-function fields: the caller passes the key and the checksum, which turned out simpler than #55 expected. **A sink in `internal/nwsync`** — the zone by default, a local tree under `--out DIR` as the conformance path. Blobs upload as they are produced and the index lands last, so the presence of an index is the publication marker. A blob already in the zone is skipped via #55's probe *without* paying for compression (the body is a thunk) — which matters for the backfill, where compression is the expensive part. **The settled CLI** ``` nwsync emit [--as NAME] [--out DIR] <artifact-key> <file> nwsync assemble --group-id N [--tlk-key KEY] [--out DIR] <artifact-key>... ``` Artifact keys are depot keys; an index lives beside its artifact with the extension replaced (#62), derived in exactly one place so `emit` and `assemble` cannot disagree. Flags may now follow positionals — Go's `flag` stops at the first non-flag argument, which cost a run during #59. **Fail-closed in two places** — an artifact key whose embedded digest does not match the file is refused (publishing an index under the wrong key silently pairs a manifest with the wrong artifact), and `assemble` refuses an artifact with no index rather than publishing a manifest missing a hak. ## Checks `make check` green. Six new tests run against a Bunny-shaped `httptest` zone that verifies the `Checksum` header the way Bunny does: blobs-then-index ordering, skip-if-present, no index after a failed upload, key/file mismatch, and assemble reading indexes back out of the zone. Conformance re-run through the new CLI against upstream `nwn_nwsync_write` 2.1.2 over `sow_vfxs_01.hak` (#59's oracle): the manifest is still **byte-identical**. ## Not in this PR - **Live upload against the real zone.** The nwsync zone and its credential are #61, still open. Everything here is proven against a fake zone only. - **Consumer wiring** — #65, in the three producer repos. - **The mid-hak failure *policy*.** The mechanism is here (fail closed, orphan blobs left, re-run resumes); whether a module release may proceed when an emit failed is a human call, still open on #60. 🤖 Generated with [Claude Code](https://claude.com/claude-code)Reviewed-on: #73 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.