Phase 5: scaffold Crucible (sow-tools) — dispatcher + builder shims, container, PR-first CI, fail-closed (D11, D19).

2026-06-11 20:36:13 +02:00
parent ff264f0d7c
commit 97f8427c4b
154 changed files with 948 additions and 76902 deletions
@@ -0,0 +1,49 @@
+# 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 ...` when wired. Needs `ffmpeg` at runtime.
+- `config *` (`validate`, `effective`, `inspect`, `explain`, `sources`) → a
+  **global** concern shared by every builder; exposed as a global subcommand
+  group, not its own binary.
+- `build-changelog` → release tooling; lands as a global `crucible changelog`
+  rather than a content builder.
+
+## Global commands (implemented in the scaffold)
+
+```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 list` is machine-readable so CI can enumerate builders without parsing
+help text.
+
+## 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`.