From ef6f21fc9c445b177e702618cf3c9758d659e196 Mon Sep 17 00:00:00 2001
From: Juergen Kunz <juergen@foss.global>
Date: Sun, 26 Oct 2025 19:47:06 +0000
Subject: [PATCH] feat(tapbundle_protocol): Add package export for
 tapbundle_protocol to expose protocol utilities

---
 changelog.md             |   7 +++
 package.json             |   3 +-
 readme.md                | 123 +++++++++++++++++++++++++++++++++++++++
 ts/00_commitinfo_data.ts |   2 +-
 4 files changed, 133 insertions(+), 2 deletions(-)

diff --git a/changelog.md b/changelog.md
index a0ba8fb..8fe1017 100644
--- a/changelog.md
+++ b/changelog.md
@@ -1,5 +1,12 @@
 # Changelog
 
+## 2025-10-26 - 2.7.0 - feat(tapbundle_protocol)
+Add package export for tapbundle_protocol to expose protocol utilities
+
+- Add './tapbundle_protocol' export in package.json pointing to './dist_ts_tapbundle_protocol/index.js'.
+- Allows consumers to import protocol utilities (ProtocolEmitter, ProtocolParser, types) via '@git.zone/tstest/tapbundle_protocol'.
+- Non-breaking: only extends package exports surface.
+
 ## 2025-10-17 - 2.6.2 - fix(@push.rocks/smartrequest)
 Bump @push.rocks/smartrequest from ^4.3.1 to ^4.3.2
 
diff --git a/package.json b/package.json
index b1ec01e..9be450a 100644
--- a/package.json
+++ b/package.json
@@ -6,7 +6,8 @@
   "exports": {
     ".": "./dist_ts/index.js",
     "./tapbundle": "./dist_ts_tapbundle/index.js",
-    "./tapbundle_node": "./dist_ts_tapbundle_node/index.js"
+    "./tapbundle_node": "./dist_ts_tapbundle_node/index.js",
+    "./tapbundle_protocol": "./dist_ts_tapbundle_protocol/index.js"
   },
   "type": "module",
   "author": "Lossless GmbH",
diff --git a/readme.md b/readme.md
index d9853b0..8c2cfd0 100644
--- a/readme.md
+++ b/readme.md
@@ -319,6 +319,129 @@ tstest provides multiple exports for different use cases:
 - `@git.zone/tstest` - Main CLI and test runner functionality
 - `@git.zone/tstest/tapbundle` - Browser-compatible test framework
 - `@git.zone/tstest/tapbundle_node` - Node.js-specific test utilities
+- `@git.zone/tstest/tapbundle_protocol` - Protocol V2 emitter and parser for TAP extensions
+
+## tapbundle Protocol V2
+
+tstest includes an enhanced TAP protocol (Protocol V2) that extends standard TAP 13 with additional metadata while maintaining backwards compatibility.
+
+### Overview
+
+Protocol V2 adds structured metadata to TAP output using Unicode markers (`⟦TSTEST:...⟧`) that standard TAP parsers safely ignore. This allows for:
+
+- **Timing information** - Test execution duration in milliseconds
+- **Structured errors** - Stack traces, diffs, and detailed error data
+- **Test events** - Real-time progress and lifecycle events
+- **Snapshots** - Snapshot testing data exchange
+- **Custom metadata** - Tags, retry counts, file locations
+
+### Using the Protocol
+
+```typescript
+import {
+  ProtocolEmitter,
+  ProtocolParser,
+  PROTOCOL_MARKERS,
+  PROTOCOL_VERSION
+} from '@git.zone/tstest/tapbundle_protocol';
+
+// Create an emitter
+const emitter = new ProtocolEmitter();
+
+// Emit protocol header
+console.log(emitter.emitProtocolHeader());
+// Output: ⟦TSTEST:PROTOCOL:2.0.0⟧
+
+// Emit TAP version
+console.log(emitter.emitTapVersion(13));
+// Output: TAP version 13
+
+// Emit a test result with metadata
+const testResult = {
+  ok: true,
+  testNumber: 1,
+  description: 'user authentication works',
+  metadata: {
+    time: 123,
+    tags: ['auth', 'unit']
+  }
+};
+console.log(emitter.emitTest(testResult).join('\n'));
+// Output: ok 1 - user authentication works ⟦TSTEST:time:123⟧
+//         ⟦TSTEST:META:{"tags":["auth","unit"]}⟧
+```
+
+### Protocol Markers
+
+```typescript
+PROTOCOL_MARKERS = {
+  START: '⟦TSTEST:',
+  END: '⟧',
+  META_PREFIX: 'META:',
+  ERROR_PREFIX: 'ERROR',
+  SNAPSHOT_PREFIX: 'SNAPSHOT:',
+  SKIP_PREFIX: 'SKIP:',
+  TODO_PREFIX: 'TODO:',
+  EVENT_PREFIX: 'EVENT:'
+}
+```
+
+### Use Cases
+
+#### Creating Custom Test Runners
+
+```typescript
+import { ProtocolEmitter } from '@git.zone/tstest/tapbundle_protocol';
+
+const emitter = new ProtocolEmitter();
+
+// Emit header and version
+console.log(emitter.emitProtocolHeader());
+console.log(emitter.emitTapVersion(13));
+console.log(emitter.emitPlan({ start: 1, end: 2 }));
+
+// Run your tests and emit results
+const startTime = Date.now();
+// ... run test ...
+const duration = Date.now() - startTime;
+
+console.log(emitter.emitTest({
+  ok: true,
+  testNumber: 1,
+  description: 'my custom test',
+  metadata: { time: duration }
+}).join('\n'));
+```
+
+#### Parsing tapbundle Output
+
+```typescript
+import { ProtocolParser } from '@git.zone/tstest/tapbundle_protocol';
+
+const parser = new ProtocolParser();
+
+// Parse TAP output line by line
+parser.parseLine('⟦TSTEST:PROTOCOL:2.0.0⟧');
+parser.parseLine('TAP version 13');
+parser.parseLine('1..1');
+parser.parseLine('ok 1 - test name ⟦TSTEST:time:123⟧');
+
+// Get parsed results
+const results = parser.getResults();
+console.log(results);
+```
+
+### Backwards Compatibility
+
+Protocol V2 is fully backwards compatible with standard TAP 13. The Unicode markers are treated as comments by standard TAP parsers, so Protocol V2 output can be consumed by any TAP-compliant tool:
+
+```
+⟦TSTEST:PROTOCOL:2.0.0⟧    ← Ignored by standard TAP parsers
+TAP version 13               ← Standard TAP
+1..2                         ← Standard TAP
+ok 1 - test ⟦TSTEST:time:45⟧ ← TAP parsers see: "ok 1 - test"
+ok 2 - another test          ← Standard TAP
+```
 
 ## tapbundle Test Framework
 
diff --git a/ts/00_commitinfo_data.ts b/ts/00_commitinfo_data.ts
index 8663744..c880bcd 100644
--- a/ts/00_commitinfo_data.ts
+++ b/ts/00_commitinfo_data.ts
@@ -3,6 +3,6 @@
  */
 export const commitinfo = {
   name: '@git.zone/tstest',
-  version: '2.6.2',
+  version: '2.7.0',
   description: 'a test utility to run tests that match test/**/*.ts'
 }