From 316a09e31b40d3bc70eeb38dc2ca4c966ae0123a Mon Sep 17 00:00:00 2001
From: sepehr-safari <safari.sepehr@gmail.com>
Date: Fri, 17 Jul 2026 15:51:01 +0300
Subject: [PATCH] feat: adopt toolkit 0.4.0 and surface Open OCPP Trace interop

Bump @ocpp-debugkit/toolkit to ^0.4.0. The inspector's parseTrace now
auto-detects the vendor-neutral Open OCPP Trace format, so a trace from
another OCPP tool can be pasted and analyzed directly.

Landing: a section on moving traces between tools via the shared format.
Docs: an Open OCPP Trace section on the trace-format page and a convert
command on the CLI reference.
---
 package.json                       |  2 +-
 pnpm-lock.yaml                     | 10 +++++-----
 src/app/docs/cli/page.tsx          | 19 +++++++++++++++++++
 src/app/docs/trace-format/page.tsx | 26 ++++++++++++++++++++++++++
 src/app/page.tsx                   | 22 ++++++++++++++++++++++
 5 files changed, 73 insertions(+), 6 deletions(-)

diff --git a/package.json b/package.json
index 8975c6c..9c288ef 100644
--- a/package.json
+++ b/package.json
@@ -15,7 +15,7 @@
     "test:e2e": "playwright test"
   },
   "dependencies": {
-    "@ocpp-debugkit/toolkit": "^0.3.1",
+    "@ocpp-debugkit/toolkit": "^0.4.0",
     "next": "16.2.10",
     "react": "19.2.4",
     "react-dom": "19.2.4"
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index e358896..57dc78a 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -9,8 +9,8 @@ importers:
   .:
     dependencies:
       '@ocpp-debugkit/toolkit':
-        specifier: ^0.3.1
-        version: 0.3.1(react-dom@19.2.4(react@19.2.4))(react@19.2.4)
+        specifier: ^0.4.0
+        version: 0.4.0(react-dom@19.2.4(react@19.2.4))(react@19.2.4)
       next:
         specifier: 16.2.10
         version: 16.2.10(@babel/core@7.29.7)(@playwright/test@1.61.1)(react-dom@19.2.4(react@19.2.4))(react@19.2.4)
@@ -424,8 +424,8 @@ packages:
     resolution: {integrity: sha512-nn5ozdjYQpUCZlWGuxcJY/KpxkWQs4DcbMCmKojjyrYDEAGy4Ce19NN4v5MduafTwJlbKc99UA8YhSVqq9yPZA==}
     engines: {node: '>=12.4.0'}
 
-  '@ocpp-debugkit/toolkit@0.3.1':
-    resolution: {integrity: sha512-cENflhAwRSvY51P8LtsBEzguGLDqWSWbQDszfbFCgdcC38Z+F3gjlD6XxpMhwtBBUHAXfDAPKwYaJtTls0GLwA==}
+  '@ocpp-debugkit/toolkit@0.4.0':
+    resolution: {integrity: sha512-A/k7RdH0hNJhxSeB2wxYDrVoAzF28J7nypjyzQFcknchp780F4RfR4d447zOZJcL30SsfREpKQ/mcL4fgs/1cw==}
     hasBin: true
     peerDependencies:
       react: ^18.0.0 || ^19.0.0
@@ -2364,7 +2364,7 @@ snapshots:
 
   '@nolyfill/is-core-module@1.0.39': {}
 
-  '@ocpp-debugkit/toolkit@0.3.1(react-dom@19.2.4(react@19.2.4))(react@19.2.4)':
+  '@ocpp-debugkit/toolkit@0.4.0(react-dom@19.2.4(react@19.2.4))(react@19.2.4)':
     dependencies:
       commander: 13.1.0
       zod: 4.4.3
diff --git a/src/app/docs/cli/page.tsx b/src/app/docs/cli/page.tsx
index 35d7afd..6049216 100644
--- a/src/app/docs/cli/page.tsx
+++ b/src/app/docs/cli/page.tsx
@@ -134,6 +134,25 @@ ocpp-debugkit ci --format json`}</code>
         <code>{`ocpp-debugkit diff trace-a.json trace-b.json`}</code>
       </pre>
 
+      <h2>convert</h2>
+      <p>
+        Convert any readable trace to the vendor-neutral Open OCPP Trace v1.1 format (JSONL), so it
+        can be consumed by other OCPP tools.
+      </p>
+      <pre>
+        <code>{`ocpp-debugkit convert <file> [options]`}</code>
+      </pre>
+      <h3>Options</h3>
+      <ul>
+        <li>
+          <code>-o, --output &lt;file&gt;</code> - Write converted trace to file (default: stdout)
+        </li>
+      </ul>
+      <p>Example:</p>
+      <pre>
+        <code>{`ocpp-debugkit convert trace.json -o trace.openocpp.jsonl`}</code>
+      </pre>
+
       <h2>Global Options</h2>
       <ul>
         <li>
diff --git a/src/app/docs/trace-format/page.tsx b/src/app/docs/trace-format/page.tsx
index 9065374..01168e7 100644
--- a/src/app/docs/trace-format/page.tsx
+++ b/src/app/docs/trace-format/page.tsx
@@ -4,6 +4,8 @@ export default function TraceFormatPage() {
       <h1>Trace Format</h1>
       <p>
         DebugKit accepts three trace formats. All formats use the OCPP 1.6 JSON message structure.
+        It also reads and writes the vendor-neutral Open OCPP Trace interchange format, described
+        below.
       </p>
 
       <h2>JSON Object Format</h2>
@@ -55,6 +57,30 @@ export default function TraceFormatPage() {
       </pre>
       <p>Direction is inferred; timestamps are null.</p>
 
+      <h2>Open OCPP Trace Format</h2>
+      <p>
+        The vendor-neutral{' '}
+        <a
+          href="https://github.com/open-ocpp-trace/specification"
+          target="_blank"
+          rel="noopener noreferrer"
+        >
+          Open OCPP Trace
+        </a>{' '}
+        interchange format lets traces move between DebugKit and other OCPP tools. It is a stream of
+        records (JSONL or a JSON array), one frame per record:
+      </p>
+      <pre>
+        <code>{`{"schemaVersion":"1.1","timestamp":"2024-01-15T10:30:00.000Z","transport":"json","direction":"cp-to-csms","messageType":"CALL","messageId":"msg-001","action":"BootNotification","payload":{"chargePointVendor":"SyntheticVendor","chargePointModel":"SM-100"}}
+{"schemaVersion":"1.1","timestamp":"2024-01-15T10:30:00.500Z","transport":"json","direction":"csms-to-cp","messageType":"CALLRESULT","messageId":"msg-001","payload":{"status":"Accepted"}}`}</code>
+      </pre>
+      <p>
+        Each record also carries a <code>raw</code> field with the verbatim frame, so byte-exact or
+        malformed frames survive the round trip. The inspector auto-detects this format on paste;
+        write it back out with the <code>convert</code> CLI command. The parser and exporter are
+        checked against the format&apos;s conformance fixtures in CI.
+      </p>
+
       <h2>OCPP 1.6 JSON Message Structure</h2>
       <p>Three message types are supported:</p>
       <ul>
diff --git a/src/app/page.tsx b/src/app/page.tsx
index ae9a2fa..df44279 100644
--- a/src/app/page.tsx
+++ b/src/app/page.tsx
@@ -126,6 +126,28 @@ export default function HomePage() {
         </p>
       </section>
 
+      {/* Open trace format */}
+      <section className="mx-auto max-w-3xl px-6 py-16 text-center">
+        <h2 className="text-2xl font-bold text-neutral-900 dark:text-white">
+          Move traces between tools
+        </h2>
+        <p className="mx-auto mt-4 text-neutral-600 dark:text-neutral-400">
+          The toolkit reads and writes the vendor-neutral{' '}
+          <a
+            href="https://github.com/open-ocpp-trace/specification"
+            target="_blank"
+            rel="noopener noreferrer"
+            className="underline hover:text-neutral-900 dark:hover:text-white"
+          >
+            Open OCPP Trace
+          </a>{' '}
+          format, so a trace from a simulator, proxy, or CSMS test suite opens in
+          the inspector, and DebugKit can write the format back out for them. The
+          parser and exporter are checked against the format&apos;s conformance
+          fixtures in CI.
+        </p>
+      </section>
+
       {/* Capabilities */}
       <section className="mx-auto max-w-5xl px-6 py-16">
         <h2 className="text-center text-3xl font-bold text-neutral-900 dark:text-white">