49 lines
2.6 KiB
Markdown
49 lines
2.6 KiB
Markdown
# Migrating from `nwn-tool` to Crucible (operator cutover)
|
|
|
|
The legacy toolchain lives at `gitea/sow-tools` as a single `nwn-tool` binary
|
|
(entry `cmd/nwn-tool`, logic under `internal/`). This repo is the Crucible
|
|
rewrite. Per the migration hard rules, the `internal/` source is **not**
|
|
transplanted automatically — the operator migrates it. This is the checklist.
|
|
|
|
## Why a clean scaffold first
|
|
|
|
- The hard rules forbid copying old-repo source into the migration tree
|
|
(`build from scratch; reference, don't transplant`).
|
|
- The downstream skeletons (`sow-module`, `sow-topdata`) already fail closed
|
|
until they can resolve a Crucible binary; the scaffold satisfies that contract
|
|
without faking artifacts.
|
|
- The scaffold pins the **shape** (module path, dispatcher, multi-binary layout,
|
|
container, CI) so the migrated logic drops into a stable frame.
|
|
|
|
## Cutover steps
|
|
|
|
1. **Move the internal packages.** Bring `internal/{app,pipeline,project,erf,
|
|
gff,topdata,music,changelog,validator}` from `gitea/sow-tools` into this repo.
|
|
Re-home `internal/app` command wiring behind `internal/dispatch` instead of
|
|
the old flag parser in `cmd/nwn-tool`.
|
|
2. **Restore dependencies.** Add `golang.org/x/text` and `gopkg.in/yaml.v3` back
|
|
to `go.mod`; commit the resulting `go.sum`. (`docker/Dockerfile` already
|
|
tolerates an absent `go.sum` for the scaffold; it will be present after this.)
|
|
3. **Wire each builder.** In `internal/dispatch`, register a handler per builder
|
|
and remove it from the unwired fail-closed path. Map the legacy commands per
|
|
[`command-surface.md`](command-surface.md).
|
|
4. **Kill the home-dir / `NWN_ROOT` defaulting.** Honor only explicit
|
|
env/flag roots per [`consumer-contract.md`](consumer-contract.md).
|
|
5. **Drop the committed binary.** Delete `nwn-tool` / `tools/sow-toolkit` from
|
|
the source tree; `.gitignore` already excludes them. Binaries become CI
|
|
artifacts and image layers only.
|
|
6. **Carry the determinism test.** Port
|
|
`TestBuildNativeKeepsGeneratedIDsStableAcrossRepeatedBuilds` and keep it green.
|
|
7. **Runtime base for music.** If music conversion is wired, switch the final
|
|
Docker stage from `distroless/static` to a debian-slim base that includes
|
|
`ffmpeg`.
|
|
8. **Update `make smoke`.** Once a builder is wired, change the smoke
|
|
expectation for it from exit `70` to a real success path.
|
|
|
|
## Wrapper contract carried over
|
|
|
|
Consumer repos keep the `SCRIPT_WRAPPER_CONTRACT` resolution behavior, now
|
|
pointed at Crucible binaries — see [`consumer-contract.md`](consumer-contract.md).
|
|
The old `SOW_TOOLS_DEV_BINARY` dev override maps to `$CRUCIBLE` /
|
|
`$SOW_MODULE_BUILD` / `$SOW_TOPDATA_BUILD`.
|