fix(cli): sanitize hardware-controlled terminal output

[VailElla]

Summary

• add a shared terminal-field encoder that renders C0/C1 controls as visible \\u{HEX} text
• apply it at the human-readable CLI, --watch, --raw, and --tb-debug output boundaries
• preserve formatter-owned ANSI/newlines and leave structured JSON strings unchanged

Security impact

USB/Thunderbolt descriptors and raw IOKit properties are hardware-controlled. Encoding their control characters before terminal interpolation prevents OSC/title changes, injected ANSI state, and forged output rows while keeping the original values inspectable.

Validation

• DEVELOPER_DIR=/Applications/Xcode.app/Contents/Developer xcrun swift build --quiet
• xcrun swift test --quiet --filter TextFormatterTests — 21 passed
• xcrun swift test --quiet --filter ANSITests — 5 passed
• xcrun swift test --quiet --filter Terminal — 6 passed
• xcrun swift test --quiet --filter terminalEncodingDoesNotAlterJSON — 1 passed
• pre-fix regression tests reproduced raw OSC/BEL/newline injection; the same tests pass with this patch

The full suite was also compared against a clean origin/main worktree. Both runs report the same 76 existing corpus issues because research/customer-probes and several research/dumps fixtures are absent from this checkout; the candidate run includes all 8 new tests, which pass.

Summary by CodeRabbit

• New Features
  • Added terminal-safe encoding for control characters in user-provided text and diagnostic metadata.
  • Updated text and Thunderbolt output to display escaped values instead of emitting raw terminal control sequences.
• Bug Fixes
  • Improved ANSI rendering consistency across enabled and disabled terminal modes.
  • Preserved original values in structured JSON output, including non-ASCII text and escape sequences.
• Tests
  • Added coverage for terminal safety, ANSI formatting, Unicode preservation, and JSON output integrity.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: 4c786859-91b0-40ec-9c45-0faea3cf1250

📥 Commits

Reviewing files that changed from the base of the PR and between 0dcfc8a and 9a50fa9.

📒 Files selected for processing (9)

• Sources/WhatCableCore/Output/ANSI.swift
• Sources/WhatCableCore/Output/TerminalFieldEncoder.swift
• Sources/WhatCableCore/Output/TextFormatter.swift
• Sources/WhatCableDarwinBackend/Debug/ThunderboltProbe.swift
• Tests/WhatCableCoreTests/ANSITests.swift
• Tests/WhatCableCoreTests/JSONFormatterTests.swift
• Tests/WhatCableCoreTests/TerminalFieldEncoderTests.swift
• Tests/WhatCableCoreTests/TextFormatterTests.swift
• Tests/WhatCableDarwinTests/ThunderboltProbeTerminalSafetyTests.swift

---

📝 Walkthrough

Walkthrough

Adds a shared terminal-field encoder for control characters, applies it across core text formatting and Thunderbolt diagnostics, preserves raw JSON values, and adds ANSI, formatter, encoder, and probe safety tests.

Changes

Terminal output safety

Layer / File(s)	Summary
Encoding contract and ANSI seam Sources/WhatCableCore/Output/TerminalFieldEncoder.swift, Sources/WhatCableCore/Output/ANSI.swift, Tests/WhatCableCoreTests/TerminalFieldEncoderTests.swift, Tests/WhatCableCoreTests/ANSITests.swift	Control characters are rendered as uppercase Unicode escape sequences, ordinary Unicode is preserved, and ANSI wrapping uses an explicit enablement seam with safety coverage.
Core formatter integration Sources/WhatCableCore/Output/TextFormatter.swift, Tests/WhatCableCoreTests/TextFormatterTests.swift, Tests/WhatCableCoreTests/JSONFormatterTests.swift	Terminal-facing display, port, device, diagnostic, trust-signal, and raw-property fields are encoded; JSON formatting retains original field values.
Thunderbolt probe integration Sources/WhatCableDarwinBackend/Debug/ThunderboltProbe.swift, Tests/WhatCableDarwinTests/ThunderboltProbeTerminalSafetyTests.swift	Thunderbolt class names, property keys, string values, dictionary keys, and fallback values are encoded before diagnostic output.

Estimated code review effort: 3 (Moderate) | ~25 minutes

Sequence Diagram(s)

sequenceDiagram
  participant Formatter as TextFormatter
  participant Encoder as TerminalFieldEncoder
  participant ANSI
  participant Terminal
  Formatter->>Encoder: encode external terminal field
  Encoder-->>Formatter: escaped field
  Formatter->>ANSI: wrap formatted text
  ANSI-->>Terminal: terminal-safe output

Loading

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 53.85% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly summarizes the main change: sanitizing hardware-controlled terminal output in the CLI.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}