From a12d94c94aa5adcc762fad626feda3ce00a1e2be Mon Sep 17 00:00:00 2001 From: sepehr-safari Date: Mon, 13 Jul 2026 13:00:52 +0300 Subject: [PATCH] feat: umbrella landing + docs covering toolkit and Studio Make the site the front door for the whole ecosystem. The landing now presents both products with a comparison table and an interop note; the docs add a Studio overview and a download/install page; the docs nav lists every page grouped by product; and the stale v0.1 marketing and scenarios doc are refreshed to the current toolkit surface. - Shared SiteHeader across landing + docs - Two-product landing: hero CTAs, product cards, comparison table, interop note - New docs/studio (overview) + docs/studio/install (macOS one-liner, Linux, source) - Fixed docs nav (was missing five pages), grouped Toolkit / Studio - Refreshed scenarios doc from 5 scenarios / 3 rules to 15 scenarios / 16 rules - Reworked landing spec + new studio-docs spec Counts are source-verified against @ocpp-debugkit/toolkit@0.3.1 (16 failure codes, 15 scenarios); the toolkit prose was inconsistent. --- CURRENT_STATE.md | 18 +- src/app/docs/layout.tsx | 72 +++++--- src/app/docs/scenarios/page.tsx | 155 ++++++++++------ src/app/docs/studio/install/page.tsx | 67 +++++++ src/app/docs/studio/page.tsx | 89 ++++++++++ src/app/layout.tsx | 2 +- src/app/page.tsx | 253 ++++++++++++++++++++++----- src/components/SiteHeader.tsx | 42 +++++ tests/landing.spec.ts | 40 +++-- tests/studio-docs.spec.ts | 16 ++ 10 files changed, 601 insertions(+), 153 deletions(-) create mode 100644 src/app/docs/studio/install/page.tsx create mode 100644 src/app/docs/studio/page.tsx create mode 100644 src/components/SiteHeader.tsx create mode 100644 tests/studio-docs.spec.ts diff --git a/CURRENT_STATE.md b/CURRENT_STATE.md index 7631613..50b2b80 100644 --- a/CURRENT_STATE.md +++ b/CURRENT_STATE.md @@ -10,20 +10,20 @@ - Repository scaffolded: Next.js 16 (App Router), Tailwind v4, strict TypeScript, ESLint, Playwright. -- Web app migrated from `toolkit/apps/web` — landing, root layout, inspector, and - all docs pages — with **no behavior change**. -- The `/inspector` route now consumes the **published** `@ocpp-debugkit/toolkit` - npm package (`^0.3.1`) instead of a workspace dependency, decoupling the site - from the toolkit's build. +- Web app migrated from `toolkit/apps/web` with **no behavior change**; the + `/inspector` route consumes the **published** `@ocpp-debugkit/toolkit` npm + package (`^0.3.1`), decoupling the site from the toolkit's build. +- **Umbrella content:** the landing and docs cover **both** products — `toolkit` + (library · CLI · web inspector) and `studio` (native desktop app). Added a + shared site header, a two-product landing (comparison table + interop note), a + Studio overview page, and a Studio download/install page. Marketing and the + scenarios doc refreshed to the current toolkit surface — 16 detection rules and + 15 scenarios, source-verified. - CI: typecheck, lint, build, and Playwright end-to-end tests. - Community docs and issue/PR templates. ## What's Next -- **Umbrella rework:** make the landing and docs cover **both** products — - `toolkit` (library · CLI · web inspector) and `studio` (native desktop app) — - including a Studio overview, a download/install page, and a refresh of the - marketing content to the current toolkit version. - **Go-live:** import the repo into Vercel; then retire the old `toolkit/apps/web` so this becomes the canonical site. diff --git a/src/app/docs/layout.tsx b/src/app/docs/layout.tsx index 7dd0bf8..79d80d1 100644 --- a/src/app/docs/layout.tsx +++ b/src/app/docs/layout.tsx @@ -1,39 +1,57 @@ import Link from 'next/link'; +import SiteHeader from '@/components/SiteHeader'; -const docPages = [ - { href: '/docs/quickstart', label: 'Quick Start' }, - { href: '/docs/glossary', label: 'Glossary' }, - { href: '/docs/architecture', label: 'Architecture' }, - { href: '/docs/trace-format', label: 'Trace Format' }, - { href: '/docs/cli', label: 'CLI Reference' }, - { href: '/docs/scenarios', label: 'Scenarios' }, +const docGroups = [ + { + title: 'Toolkit', + pages: [ + { href: '/docs/quickstart', label: 'Quick Start' }, + { href: '/docs/glossary', label: 'Glossary' }, + { href: '/docs/architecture', label: 'Architecture' }, + { href: '/docs/trace-format', label: 'Trace Format' }, + { href: '/docs/cli', label: 'CLI Reference' }, + { href: '/docs/scenarios', label: 'Scenarios' }, + { href: '/docs/scenario-assertions', label: 'Scenario Assertions' }, + { href: '/docs/trace-diffing', label: 'Trace Diffing' }, + { href: '/docs/ci-mode', label: 'CI Mode' }, + { href: '/docs/anonymize', label: 'Anonymize' }, + { href: '/docs/examples', label: 'Examples' }, + ], + }, + { + title: 'Studio', + pages: [ + { href: '/docs/studio', label: 'Overview' }, + { href: '/docs/studio/install', label: 'Download & Install' }, + ], + }, ]; export default function DocsLayout({ children }: { children: React.ReactNode }) { return (
-
-
- - OCPP DebugKit - - Docs -
-
+
{children} diff --git a/src/app/docs/scenarios/page.tsx b/src/app/docs/scenarios/page.tsx index c41f054..3f4db70 100644 --- a/src/app/docs/scenarios/page.tsx +++ b/src/app/docs/scenarios/page.tsx @@ -3,83 +3,132 @@ export default function ScenariosPage() {

Scenarios

- Scenarios are predefined trace fixtures that test the analysis engine. Each scenario has a - trace and a list of expected failures. + Scenarios are predefined trace fixtures that test the analysis engine. Each scenario pairs a + trace with the failures it is expected to produce, so the detection engine can be checked + against known-good and known-bad sessions.

Built-in Scenarios

-

DebugKit v0.1 includes 5 scenarios:

- -

normal-session

-

- A complete charging session: boot, authorize, start transaction, meter values, stop - transaction. No failures expected. -

+

The toolkit ships 15 scenarios:

  • - expectedFailures: [] + normal-session — a complete session (boot, authorize, start, meter + values, stop) with no failures expected.
    • -
- -

failed-auth

-

- Failed authorization: the idTag is rejected by the CSMS. StartTransaction is not attempted. - The connector transitions to Faulted. -

-
  • - expectedFailures: ["FAILED_AUTHORIZATION"] + failed-auth — the idTag is rejected by the CSMS; StartTransaction is not + attempted. FAILED_AUTHORIZATION
    • -
- -

connector-fault

-

- Connector fault during an active session: the connector reports a Faulted status - mid-charging, and the transaction stops with a fault reason. -

-
  • - expectedFailures: ["CONNECTOR_FAULT"] + connector-fault — the connector faults mid-charging and the transaction + stops with a fault reason. CONNECTOR_FAULT
    • -
- -

station-offline

-

- Station goes offline during an active session: a StartTransaction is sent but no - StopTransaction follows. -

-
  • - expectedFailures: ["STATION_OFFLINE_DURING_SESSION"] + station-offline — a StartTransaction with no StopTransaction to follow.{' '} + STATION_OFFLINE_DURING_SESSION +
    • +
  • + meter-value-gap — an active transaction with no MeterValues between start + and stop. METER_VALUE_GAP +
    • +
  • + invalid-stop-reason — a StopTransaction reason not in the OCPP 1.6 + specification. INVALID_STOP_REASON +
    • +
  • + unexpected-start — a StartTransaction with no preceding BootNotification + or Authorize. UNEXPECTED_START +
    • +
  • + status-transition-violation — an invalid OCPP 1.6 connector status + transition (Available directly to Finishing). STATUS_TRANSITION_VIOLATION +
    • +
  • + diagnostics-failure — a DiagnosticsStatusNotification reporting + DiagnosisFailed. DIAGNOSTICS_FAILURE +
    • +
  • + slow-csms-response — the CSMS takes 15s to answer a BootNotification.{' '} + SLOW_RESPONSE +
    • +
  • + meter-anomaly — meter values decrease during a transaction + (non-monotonic). METER_VALUE_ANOMALY +
    • +
  • + short-session — a session lasting only ~10 seconds.{' '} + SUSPICIOUS_SESSION_DURATION +
    • +
  • + heartbeat-irregular — heartbeats at irregular intervals (300s expected, + 600s observed). HEARTBEAT_INTERVAL_VIOLATION +
    • +
  • + unresponsive-csms — a Call is sent but the CSMS never answers.{' '} + UNRESPONSIVE_CSMS +
    • +
  • + unexpected-stop-reason — a parser/timeline-only fixture (no detection + rule matches) that validates handling of stop events with error payloads.
-

unexpected-stop-reason

+

Failure Detection Rules

- A stop transaction with an unexpected stop reason. This is a parser/timeline-only fixture — - no v0.1 detection rule matches it. + The detection engine implements 16 rules covering the OCPP 1.6J failure taxonomy, ranked by + severity:

  • - expectedFailures: [] + FAILED_AUTHORIZATION — Authorize rejected by the CSMS +
    • +
  • + CONNECTOR_FAULT — connector reports Faulted during an active session +
    • +
  • + STATION_OFFLINE_DURING_SESSION — station drops offline mid-transaction, or a + transaction never stops +
    • +
  • + UNRESPONSIVE_CSMS — a Call is sent but never answered (no CallResult or + CallError) +
    • +
  • + SLOW_RESPONSE — a response exceeds the expected latency budget +
    • +
  • + TIMEOUT_NO_HEARTBEAT — no heartbeat within the expected window +
    • +
  • + HEARTBEAT_INTERVAL_VIOLATION — heartbeats arrive outside the configured + interval +
    • +
  • + REPEATED_BOOT_NOTIFICATION — repeated boots suggest a reboot loop +
    • +
  • + METER_VALUE_GAP — an active transaction with no MeterValues +
    • +
  • + METER_VALUE_ANOMALY — meter values decrease during a transaction +
    • +
  • + STATUS_TRANSITION_VIOLATION — an invalid connector status transition +
    • +
  • + UNEXPECTED_START — a StartTransaction without a preceding boot or authorize +
    • +
  • + INVALID_STOP_REASON — a StopTransaction reason outside the OCPP 1.6 spec
    • -
- -

Failure Detection Rules

-

Three detection rules are available in v0.1:

-
  • - FAILED_AUTHORIZATION — Authorize response with - idTagInfo.status = "Invalid" + SUSPICIOUS_SESSION_DURATION — a session ends suspiciously quickly
  • - CONNECTOR_FAULT — StatusNotification with - status = "Faulted" during an active session + DIAGNOSTICS_FAILURE — a diagnostics upload reports failure
  • - STATION_OFFLINE_DURING_SESSION — Session has StartTransaction but no - StopTransaction, or connector transitions to Unavailable/Offline during an active - transaction + FIRMWARE_UPDATE_FAILURE — a firmware update reports failure
diff --git a/src/app/docs/studio/install/page.tsx b/src/app/docs/studio/install/page.tsx new file mode 100644 index 0000000..489e59a --- /dev/null +++ b/src/app/docs/studio/install/page.tsx @@ -0,0 +1,67 @@ +export default function StudioInstallPage() { + return ( +
+

Download & Install Studio

+

+ OCPP DebugKit Studio is a native desktop app. It is pre-1.0 (0.x) while Zig, the Native SDK, + and the toolkit conformance reference are all pre-1.0. +

+ +

macOS (Apple silicon)

+

Paste this into a terminal. It installs the latest Studio into Applications and opens it:

+ 
+        {`curl -fsSL https://raw.githubusercontent.com/ocpp-debugkit/studio/main/scripts/install-macos.sh | bash`}
+
+

+ The script downloads the latest release, verifies its SHA-256, installs the app, and + launches it — no toolchain, no manual steps. Prefer to read it first? See{' '} + + scripts/install-macos.sh + + . +

+ +

Linux

+

+ Download the .tar.gz from the{' '} + + Releases + {' '} + page, extract it, and run the studio binary. Requires GTK 4 ( + libgtk-4, libwebkitgtk-6.0). +

+ +

Build from source

+

+ Prerequisites: Zig 0.16.0 and the + Native SDK CLI (npm install -g @native-sdk/cli). +

+ 
+        {`git clone https://github.com/ocpp-debugkit/studio.git
+cd studio
+native build        # produces the release binary`}
+
+ +

All downloads

+

+ Every release, with checksums and platform assets, is on the{' '} + + GitHub Releases + {' '} + page. +

+
+ ); +} diff --git a/src/app/docs/studio/page.tsx b/src/app/docs/studio/page.tsx new file mode 100644 index 0000000..f6e10d1 --- /dev/null +++ b/src/app/docs/studio/page.tsx @@ -0,0 +1,89 @@ +import Link from 'next/link'; + +export default function StudioOverviewPage() { + return ( +
+

OCPP DebugKit Studio

+

+ Studio is a native desktop debugger for OCPP charging sessions — the bench instrument of the + OCPP DebugKit ecosystem. It sits between a charging station and its backend, decodes every + frame live, flags protocol failures as they happen, and keeps a high-performance offline + inspector for the traces you capture. +

+

+ It is built in Zig on the Native SDK — native-rendered, no + browser, no Electron. It starts instantly, stays small, and does the things a browser tab + fundamentally cannot: open raw sockets, watch the filesystem, and run for days as a + background monitor. +

+ +

What it does

+
    +
  • + Inspect — open JSON / JSONL / bare-array traces in a virtualized timeline + that stays smooth past 500k events; unpack any message, see the session it correlates + into, and search or filter by action, direction, type, or severity. +
    • +
  • + Detect — the full OCPP 1.6J failure taxonomy (16 rules), conformant with + the toolkit's reference, ranked critical to info with remediation steps. +
    • +
  • + Watch — a live WebSocket proxy between a charge point and its CSMS: decode + frames in flight, run detection as events stream, record to the canonical trace format, + and get an OS notification the moment a critical failure appears. +
    • +
  • + Prove — Markdown / HTML reports, semantic trace diffing, + anonymize-on-export, and step-through replay. +
    • +
  • + Scale — native performance with no garbage collector; stream-parse traces + far past what a browser tab can hold. +
    • +
  • + Script — the same binary is a headless CLI ( + inspect, report, diff, anonymize,{' '} + capture, ci) for pipelines and automation. +
    • +
+ +

Native, not a browser tab

+

+ Studio and the toolkit's web inspector share no code. They meet only at a conformance + contract — the same trace format, the same normalized event model, and the same failure + taxonomy — verified in CI on every change. A trace captured in Studio opens in the web + inspector, and vice versa. See the{' '} + + conformance contract + + . +

+ +

Get Studio

+ +
+ ); +} diff --git a/src/app/layout.tsx b/src/app/layout.tsx index c89bcf8..447ec4f 100644 --- a/src/app/layout.tsx +++ b/src/app/layout.tsx @@ -15,7 +15,7 @@ const geistMono = Geist_Mono({ export const metadata: Metadata = { title: 'OCPP DebugKit', description: - 'Open-source DevTools for debugging OCPP charging sessions. Inspect traces, detect failures, and generate reports.', + 'Open-source DevTools for debugging OCPP charging sessions: a browser-based trace inspector and TypeScript toolkit, plus a native desktop debugger.', }; export default function RootLayout({ diff --git a/src/app/page.tsx b/src/app/page.tsx index e2f95f5..ae9a2fa 100644 --- a/src/app/page.tsx +++ b/src/app/page.tsx @@ -1,63 +1,175 @@ import Link from 'next/link'; +import SiteHeader from '@/components/SiteHeader'; export default function HomePage() { return (
+ + {/* Hero */}

OCPP DebugKit

- Open-source DevTools for debugging OCPP charging sessions. Inspect traces, detect - failures, and generate reports — right in your browser. + Open-source DevTools for debugging OCPP charging sessions. Parse, analyze, and diagnose + traces from a browser tab, your CI pipeline, or a native desktop instrument.

- Try Inspector + Try the Inspector + + + Download Studio +
+
+ + {/* Two products */} +
+

+ Two tools, one trace format +

+

+ The OCPP DebugKit family is two independent products that share the same trace format, + event model, and failure taxonomy. Use one, or both. +

+
+ + +
+
+ + {/* Comparison */} +
+
+ + + + + + + + + + + + + + + +
ToolkitStudio
+
+
+ + {/* Interop */} +
+

+ Capture in one, open in the other +

+

+ A trace captured in Studio opens in the toolkit's web inspector, and vice versa. The + two are independent implementations checked against the same{' '} - View on GitHub - -

+ conformance contract + {' '} + in CI — same format, same normalized events, same failure taxonomy. +

- {/* Features */} + {/* Capabilities */}
-

- Features +

+ What it does

+ + + +
{/* What it's not */}
-

+

What it's not

@@ -67,30 +179,14 @@ export default function HomePage() {
- {/* Architecture overview */} -
-

- Architecture -

-

- A single package with modular subpath exports. Use only what you need. -

-
- - - - -
-
- {/* Quick start */}
-

+

Quick Start 

-            {`# Install the CLI
+            {`# Install the toolkit CLI
 npm install -g @ocpp-debugkit/toolkit
 
 # Inspect a trace
@@ -119,14 +215,22 @@ ocpp-debugkit scenario run failed-auth`}