Surface inbound GMCP packets as raw module + JSON to the delegate

[jaborsh]

Summary

Adds an optional TelnetSessionDelegate method telnetSession(_:gmcpReceived:) fired from processSbGmcp before the existing json2msdp fallback. The delegate receives a GMCPPacket carrying the module name plus the JSON payload, with a generic decode<T: Decodable>(_:) helper for typed consumption.

Why

Hosts that consume nested-object GMCP packages (e.g. an authentication module sending Char.Login.Credentials { account, password, device }) can't reconstruct the payload from MSDPManager.processVarVal, which is a flat key/value pipeline. This delegate surfaces the raw packet directly. Consumer site:

guard packet.module == "Char.Login.Credentials",
      let creds = try packet.decode(Credentials.self)
else { return }
// use creds

The MSDP fallback path is preserved — it still runs after the delegate returns — so existing flat-var consumers (Core.Hello, etc.) keep working unchanged. The new method has a default-empty extension implementation, so the protocol change is additive.

API surface

GMCPPacket:

• module: String — public read; always non-empty
• payload: Data — internal; consumers go through decode(_:)
• byteCount: Int — public read; lets consumers enforce size policies (e.g. drop packets > N KB) without exposing bytes
• decode<T: Decodable>(_:) -> T? — returns nil for module-only packets (Core.Ping), throws DecodingError on malformed JSON
• init — internal; only MTH constructs them

The delegate is not called for:

• Empty IAC SB GMCP IAC SE blocks (no body)
• Bodies that produce an empty module name (e.g. body starts with a space)

Test plan

• swift build clean
• New unit tests in Tests/MTHTests/TelnetSessionTests.swift:
  • delegate receives module + payload for a JSON-bearing packet
  • module-only packet (Core.Ping) — decode returns nil
  • empty-body packet does not call the delegate
  • leading-space body (would produce empty module) does not call the delegate
  • malformed JSON — decode throws DecodingError
  • byteCount reports the payload byte size
  • the MSDP-flat-var fallback still runs after the delegate fires (regression check on MSDP {"LIST":"COMMANDS"})
• Full MTH test suite passes (149 tests)

[Copilot]

Pull request overview

Adds a new additive delegate callback to surface inbound GMCP packets as a raw module name plus payload bytes (with a convenience decoding helper), while preserving the existing GMCP→MSDP flattening fallback behavior in TelnetSession.

Changes:

• Introduces GMCPPacket (module + raw payload Data) and an optional TelnetSessionDelegate callback for inbound GMCP.
• Updates processSbGmcp to call the delegate before running the existing json2msdp/MSDP processing path.
• Ignores SwiftPM build artifacts by adding .build/ to .gitignore.

Reviewed changes

Copilot reviewed 2 out of 3 changed files in this pull request and generated 3 comments.

File	Description
Sources/SwiftMTH/TelnetSessionDelegate.swift	Adds GMCPPacket + new optional delegate method to receive inbound GMCP as module + raw payload.
Sources/SwiftMTH/TelnetSession.swift	Surfaces inbound GMCP packets to the delegate prior to the existing MSDP fallback processing.
.gitignore	Ignores SwiftPM .build/ output directory.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.