feat(tapbundle_protocol): Add package export for tapbundle_protocol to expose protocol utilities

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
 

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",

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
 

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'
 }