58 lines
2.4 KiB
Markdown
58 lines
2.4 KiB
Markdown
---
|
|
description: sow-tools / Crucible — the build/conversion/sync toolchain repo.
|
|
alwaysApply: true
|
|
---
|
|
|
|
# sow-tools / Crucible Agent Guide
|
|
|
|
This repo owns the **builder logic** for the migration: one Go module
|
|
(`gitea.westgate.pw/ShadowsOverWestgate/sow-tools`) producing the `crucible`
|
|
dispatcher and the `crucible-<name>` binaries (D11). Read
|
|
[`../AGENTS.md`](../AGENTS.md) (migration hub) and
|
|
[`../../KICKOFF_PROMPT.md`](../../KICKOFF_PROMPT.md) first.
|
|
|
|
## What this repo owns / does not own
|
|
|
|
Owns: build/extract/validate/compare pipeline, ERF/HAK packing, topdata 2da/tlk
|
|
compilation, wiki rendering/deploy, depot blob verify, music conversion,
|
|
changelog. Does **not** own authored game content (that is `sow-module` /
|
|
`sow-topdata` / `sow-assets-manifest`) or any production deploy authority (that
|
|
is `sow-platform`).
|
|
|
|
## Scaffold rules (Phase 5)
|
|
|
|
1. **Source is not transplanted.** The migration hard rules forbid copying the
|
|
`internal/` packages from `gitea/sow-tools` automatically. The operator
|
|
migrates them at cutover; see [`docs/migration-from-nwn-tool.md`](docs/migration-from-nwn-tool.md).
|
|
2. **Fail closed, never fake.** Unwired builders exit `70`. Do not stub a
|
|
builder to emit a placeholder artifact.
|
|
3. **Binaries are not committed.** They are CI artifacts / image layers (D19).
|
|
`/bin/`, `*.exe`, `nwn-tool`, `sow-toolkit` are gitignored.
|
|
4. **No home-dir / `NWN_ROOT` guessing.** Builders take roots explicitly via
|
|
flag or env. See [`docs/consumer-contract.md`](docs/consumer-contract.md).
|
|
5. **The registry is the command surface.** `internal/dispatch.Registry` is the
|
|
single source of truth; keep it in sync with `cmd/` and
|
|
[`docs/command-surface.md`](docs/command-surface.md). Adding a builder = a
|
|
`cmd/crucible-<name>/main.go` shim + a `Registry` entry + a doc row.
|
|
|
|
## Wiring a builder (operator cutover)
|
|
|
|
1. Migrate the relevant `internal/` package(s) from `gitea/sow-tools`.
|
|
2. Register a handler and flip the builder off the unwired path in
|
|
`internal/dispatch`.
|
|
3. Add tests; keep outputs deterministic (same input → same bytes).
|
|
4. `make check` must stay green; `make smoke` is updated to expect a wired exit.
|
|
|
|
## Commands
|
|
|
|
```bash
|
|
nix develop && make check # vet + test + shellcheck + yamllint
|
|
make build # cmd/* -> ./bin
|
|
make smoke # assert fail-closed contract
|
|
make image # crucible:<sha>
|
|
```
|
|
|
|
## Git
|
|
|
|
Never commit, branch, or push. Suggest a commit message; let the operator do it.
|