55 lines
3.0 KiB
Markdown
55 lines
3.0 KiB
Markdown
# 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`](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`](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. **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`.
|