Log Refactor

LOG_REFACTOR_CONTRACT.md

@@ -0,0 +1,149 @@
+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.