sow-tools/LOG_REFACTOR_CONTRACT.md

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

Status Snapshot

Current state as of 2026-05-13:

• This work is largely implemented for the current build-haks path.
• The app layer now exposes --quiet, --verbose, and --debug, and normal mode prints compact music summaries instead of raw per-file mappings.
• Detailed mapping output is available behind verbose logging, and app tests cover the compact versus detailed presentation split.

Remaining work:

• continue applying the same presentation discipline to other command families where raw pipeline output still leaks through
• keep summary wording and phase naming aligned as new generated-asset stages are added

Active Scope

Logging remains an active priority, but no longer for build-haks alone.

The next logging phase should target:

• build-topdata
• validate-topdata
• compare-topdata
• build-wiki
• deploy-wiki
• release wrapper flows that currently interleave raw shell/tool output

Current Findings

The asset-side log refactor proved the presentation model. The remaining gap is uneven command coverage:

• topdata and wiki commands do not yet have the same polished phase/summarized output contract as build-haks
• release scripts still emit long shell-oriented logs that are useful for CI diagnosis but not shaped into the same structured presentation model
• wrapper-side status lines and toolkit-side progress lines are not yet fully harmonized

Deferred Scope

Defer cosmetic-only logging work that does not improve operator clarity.

For now, prioritize:

• structured summaries
• deterministic phase labels
• stderr/stdout hygiene
• parity between topdata/wiki flows and the existing build-haks presentation

Immediate Plan

1. Reuse the existing verbosity model for topdata and wiki command families.
2. Define concise normal-mode summaries for topdata build/validate/compare.
3. Add deploy/build wiki progress summaries that surface:
   • local pages scanned
   • create/update/skip/drift counts
   • manifest path
4. Keep debug mode capable of exposing raw internal progress when diagnosis is required.
5. Extend app-layer tests to cover topdata/wiki presentation once those commands adopt the structured output contract.

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.