sow-tools/LOG_REFACTOR_CONTRACT.md

You are improving CLI/build logs for a NWN asset toolchain.

Goal: Make the logs cleaner, prettier, less repetitive, and easier to understand, without hiding important diagnostics.

Current issues:

- The same credits refresh output appears twice.
- Long file-by-file mappings overwhelm the main log.
- Some messages are noisy or too implementation-focused.
- The final build summary is useful but visually cramped.
- Paths are too long for normal human reading unless needed for debugging.
- Status prefixes are inconsistent: [credits], [build-haks], run-nwn-tool.sh, [|].

Desired behavior:

1. Use clear phase headers.
2. Collapse repetitive file listings by default.
3. Show counts and summaries in normal mode.
4. Keep detailed mappings available behind a verbose/debug flag.
5. Avoid printing the same credits scan twice unless something changed.
6. Use consistent prefixes and indentation.
7. Prefer relative paths when possible.
8. Group related output together.
9. End with a compact, readable summary.
10. Preserve warnings, errors, and actionable diagnostics prominently.

Suggested output style:

Build HAKs ────────── • Refreshing credits cache

- Scanned: envi/music/westgate
- Tracks: 38
- Output: .cache/credits/envi/music/westgate/credits.json
- Aggregate cache updated

• Validating project • Collecting asset resources • Writing autogen manifests

- sow-parts-manifest.json
- sow-head-vfx-manifest.json

• Planning HAK chunks • Resolving module HAK order • Reusing unchanged HAKs

- 12 / 12 reused
- 65,320 assets total

• Cleaning stale generated HAKs • Writing HAK manifest

Summary ─────── Project: Shadows Over Westgate HAK archives: 12 HAK assets: 65,320 Manifest: assets/build/haks.json Credits artifacts: 2 Autogen manifests: 2 Status: complete

Rules:

- In normal mode, do not print every `mp3 -> bmu` mapping.
- Instead print something like: `Mapped 38 music files. Use --verbose to list mappings.`
- In verbose mode, print mappings under an indented section.
- If the credits cache is refreshed before and after the build for normalization, make the second refresh terse: `Restored normalized credits cache: unchanged.`
- If files changed, say how many changed and where.
- Do not remove any warnings or errors.
- Do not make failure logs terse; failures should include enough context to debug.
- Keep output deterministic so CI diffs remain readable.
- Use plain ASCII unless the toolchain already supports Unicode reliably.
- Do not introduce color unless color can be disabled with NO_COLOR or --no-color.

Implementation guidance:

- Add logging helpers for phases, steps, summaries, verbose details, warnings, and errors.
- Add a verbosity level, for example: quiet, normal, verbose, debug.
- Route repeated detailed output through verbose/debug logging.
- Track counts while scanning instead of printing every scanned item.
- Detect unchanged cache writes and report them as unchanged rather than rewriting noisy output.
- Normalize absolute paths to project-relative paths in normal output.
- Keep machine-readable artifacts unchanged.

Concrete implementation plan:

1. CLI presentation layer

- Keep the pipeline responsible for state and artifact generation.
- Move `build-haks` presentation rules into `internal/app/app.go`.
- Introduce `--quiet`, `--verbose`, and `--debug` for `build-haks`.
- In normal mode, print grouped sections and a compact summary.
- In verbose mode, include detailed mapping and per-archive action lines.
- In debug mode, preserve raw pipeline progress messages for diagnosis.

2. Spinner behavior

- Reuse the existing spinner infrastructure instead of adding a second animation system.
- Make the spinner phase-aware so it shows the current high-level step, for example:
  - `Build HAKs: refreshing credits cache`
  - `Build HAKs: collecting asset resources`
  - `Build HAKs: planning HAK chunks`
- Only animate on interactive TTY stderr.
- Disable spinner animation automatically in CI and non-interactive output.
- Always keep stable human-readable logs on stdout.

3. Pipeline data surfaced to the CLI

- Extend `pipeline.BuildResult` with log-summary metadata instead of forcing the CLI to parse raw strings.
- Return credits refresh summary data:
  - scanned music directories
  - converted track count
  - generated credits artifact paths
  - per-file source/output mappings
  - changed-versus-unchanged artifact count
- Return HAK archive summary data:
  - total archive count
  - reused archive count
  - written archive count
  - per-archive actions for verbose mode

4. Credits artifact handling

- Stop blindly deleting and rewriting `.cache/credits` on every run.
- Render the desired credits outputs in memory first.
- Compare desired artifacts against the current on-disk artifacts.
- Rewrite only changed files.
- Remove stale artifacts that are no longer desired.
- Report `unchanged` when the second pass produces identical output.

5. Output rules

- Normal mode:
  - show phase blocks
  - show counts
  - show relative paths
  - hide file-by-file mappings
- Verbose mode:
  - show music mappings under an indented `mappings:` section
  - show per-archive `reused` or `wrote` details
- Quiet mode:
  - keep only the final summary
- Debug mode:
  - allow raw internal progress lines in addition to the formatted summary

6. Tests

- Add app-layer tests for:
  - compact normal-mode output
  - verbose mapping output
- Add pipeline regression coverage proving:
  - music conversion still writes the expected credits artifacts
  - a second identical credits refresh reports zero changed files

Acceptance checks:

- `build-haks` emits the new grouped summary format.
- `build-haks --verbose` includes per-track mappings and per-archive details.
- The spinner reflects phase changes without polluting stdout logs.
- Re-running the same build keeps credits refresh output deterministic and reports `unchanged` when applicable.
- Existing machine-readable artifacts remain unchanged in schema and location.