sow-tools/docs/migration-from-nwn-tool.md

Migrating from nwn-tool to Crucible (cutover — DONE)

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. The cutover below has been performed: the internal/ packages are migrated and the module/topdata/hak/wiki builders delegate to them. The checklist is kept as the record of what was done.

Status. Steps 1–8 are complete. depot is the one remaining unwired builder (no legacy source — it was shell mc/S3). The open follow-up is the consumer flag contract: sow-module / sow-topdata / sow-assets-manifest wrappers invoke crucible-<name> with --manifest/--source/--out style flags (see consumer-contract.md), whereas the migrated commands use the legacy CWD/project model. Reconciling the two is the Phase-6 consumer task and is not part of this cutover.

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,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.
4. Kill the home-dir / NWN_ROOT defaulting. Honor only explicit env/flag roots per 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. 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. The old SOW_TOOLS_DEV_BINARY dev override maps to $CRUCIBLE / $SOW_MODULE_BUILD / $SOW_TOPDATA_BUILD.