command and help ux pass
This commit is contained in:
+56
-46
@@ -1,67 +1,77 @@
|
||||
# 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`.
|
||||
`internal/dispatch.Registry` is the single source of truth for Crucible's
|
||||
builders, visible commands, descriptions, help, and hidden compatibility
|
||||
aliases.
|
||||
|
||||
## Builders
|
||||
## Visible commands
|
||||
|
||||
| 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` |
|
||||
| Builder | Command | Purpose |
|
||||
| --- | --- | --- |
|
||||
| `hak` | `build` | Build configured HAK archives and their manifest. |
|
||||
| `hak` | `manifest` | Apply a generated HAK list to module source. |
|
||||
| `module` | `build` | Build the module and configured project outputs. |
|
||||
| `module` | `extract` | Extract built archives into configured source trees. |
|
||||
| `module` | `validate` | Validate project layout, config, and source inventory. |
|
||||
| `module` | `compare` | Compare source content with built archives. |
|
||||
| `module` | `manifest` | Apply a generated HAK list to module source. |
|
||||
| `topdata` | `validate` | Validate topdata source and canonical JSON compatibility. |
|
||||
| `topdata` | `build` | Compile topdata and refresh the configured package. |
|
||||
| `topdata` | `package` | Package cached outputs into HAK and TLK files. |
|
||||
| `topdata` | `compare` | Compare current output with a fresh native build. |
|
||||
| `topdata` | `convert` | Convert between 2DA and native JSON/module formats. |
|
||||
| `wiki` | `build` | Render wiki page drafts from compiled topdata. |
|
||||
| `wiki` | `deploy` | Deploy generated wiki pages to NodeBB. |
|
||||
|
||||
† `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`.
|
||||
`crucible-depot` remains registered but unwired. It fails closed with exit `70`
|
||||
and never emits placeholder artifacts.
|
||||
|
||||
## Folded / global commands
|
||||
## Hidden compatibility aliases
|
||||
|
||||
These legacy commands are **not** top-level builders:
|
||||
Existing scripts may continue using these names indefinitely. They are accepted
|
||||
but omitted from routine help and the interactive menu:
|
||||
|
||||
- `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.
|
||||
| Builder | Hidden alias | Implementation |
|
||||
| --- | --- | --- |
|
||||
| `hak` | `build-haks` | `build-haks` |
|
||||
| `hak` | `apply-hak-manifest` | `apply-hak-manifest` |
|
||||
| `module` | `build-module` | module-only `build-module` |
|
||||
| `module` | `apply-hak-manifest` | `apply-hak-manifest` |
|
||||
| `topdata` | `validate-topdata` | `validate-topdata` |
|
||||
| `topdata` | `build-topdata` | `build-topdata` |
|
||||
| `topdata` | `build-top-package` | `build-top-package` |
|
||||
| `topdata` | `compare-topdata` | `compare-topdata` |
|
||||
| `topdata` | `convert-topdata` | `convert-topdata` |
|
||||
| `wiki` | `build-wiki` | `build-wiki` |
|
||||
| `wiki` | `deploy-wiki` | `deploy-wiki` |
|
||||
|
||||
## Global commands (implemented)
|
||||
`module build-module` deliberately retains its narrower module-only behavior;
|
||||
it is not redirected to the broader `module build`.
|
||||
|
||||
## Global commands
|
||||
|
||||
```text
|
||||
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 version | -V build version
|
||||
crucible list name<TAB>binary<TAB>summary
|
||||
crucible config [args] inspect and validate effective configuration
|
||||
crucible changelog [args] generate a release changelog
|
||||
```
|
||||
|
||||
`crucible list` is machine-readable so CI can enumerate builders without parsing
|
||||
help text.
|
||||
|
||||
## HAK builder source modes
|
||||
## HAK build options
|
||||
|
||||
```text
|
||||
build-haks [--hak <hak-name> ...] [--archive <archive-name> ...]
|
||||
[--source-manifest <path>] [--content-addressed-root <path>]
|
||||
[--plan-only] [--skip-music] [--music-dataset <id> ...]
|
||||
crucible hak build
|
||||
[--hak <hak-name> ...]
|
||||
[--archive <archive-name> ...]
|
||||
[--source-manifest <path>]
|
||||
[--content-addressed-root <path>]
|
||||
[--plan-only]
|
||||
[--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
|
||||
`--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`.
|
||||
while writing selected HAK archives. Authored `.bmu` files are ordinary assets
|
||||
and require no conversion pipeline.
|
||||
|
||||
Reference in New Issue
Block a user