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

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.
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. 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. The old SOW_TOOLS_DEV_BINARY dev override maps to $CRUCIBLE / $SOW_MODULE_BUILD / $SOW_TOPDATA_BUILD.