Crucible command surface

Crucible re-homes the single nwn-tool (a.k.a. sow-toolkit) command surface into five builders plus a dispatcher (D11). This table maps every legacy command to its Crucible home. It is the migration contract — keep it in sync with internal/dispatch.Registry.

Builders

Builder	Legacy `nwn-tool` commands subsumed
`crucible-module`	`build`, `build-module`, `extract`, `validate`, `compare`, `apply-hak-manifest`†
`crucible-topdata`	`validate-topdata`, `build-topdata`, `build-top-package`, `compare-topdata`, `convert-topdata`
`crucible-hak`	`build-haks`, `apply-hak-manifest`
`crucible-wiki`	`build-wiki`, `deploy-wiki`
`crucible-depot`	(new) depot blob verify/move — was shell `mc`/S3 in `sow-assets-manifest`

† apply-hak-manifest is HAK-list maintenance on a module; it is reachable from both crucible-module and crucible-hak. Canonical home is crucible-hak.

Folded / global commands

These legacy commands are not top-level builders:

music * (list-datasets, scan, build, credits, validate, manifest, normalize) → folds into the module/hak build pipeline (music BMUs are packed into HAKs at build time). Exposed as crucible-module music ... / crucible-hak music .... Needs ffmpeg at runtime (in the image).
config * (validate, effective, inspect, explain, sources) → a global concern shared by every builder; exposed as the global crucible config ..., not its own binary.
build-changelog → release tooling; exposed as the global crucible changelog rather than a content builder.

Global commands (implemented)

crucible help | -h          usage + builder list
crucible version | -V       build version (git sha via -ldflags)
crucible list               builders, one per line: name<TAB>bin<TAB>summary
crucible config [args]      -> legacy `config` command group
crucible changelog [args]   -> legacy `build-changelog`

crucible list is machine-readable so CI can enumerate builders without parsing help text.

HAK builder source modes

build-haks [--hak <hak-name> ...] [--archive <archive-name> ...]
  [--source-manifest <path>] [--content-addressed-root <path>]
  [--plan-only] [--skip-music] [--music-dataset <id> ...]
  [--quiet|--verbose|--debug]

When a source manifest contains asset_sources, pass --content-addressed-root <directory> (or --content-addressed-root=<directory>). Crucible resolves each declared SHA-256 under sha256/<first-two>/<next-two>/<full-sha256> and verifies streamed bytes while writing the selected HAK archives. Source manifests without asset_sources continue to use the configured assets tree.

Global flags (planned, at wiring time)

--quiet, --verbose, --debug (the legacy verbosity model), passed after the builder name, e.g. crucible topdata build-topdata --verbose.

3.2 KiB Raw Blame History