diff --git a/CHANGELOG.md b/CHANGELOG.md new file mode 100644 index 0000000..1eda5a3 --- /dev/null +++ b/CHANGELOG.md @@ -0,0 +1,54 @@ +# Changelog + +All notable changes to OCPP DebugKit Studio are documented here. + +The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/). This +project is pre-1.0: while Zig, the Native SDK, and the toolkit conformance +reference are all pre-1.0, minor (0.x) releases may include breaking changes. + +## [Unreleased] + +The upcoming **0.5.0** — Studio's first packaged, signed public release, +assembled across milestones S0–S5. Highlights: + +### Added + +- **Engine** — a pure-Zig, headless OCPP 1.6J engine: canonical event / session / + failure model, a trace parser (JSON object, JSONL, and bare-array formats with + untrusted-input limits), timestamp + direction normalization, and + `transactionId` session correlation. +- **Detection** — the full 16-rule OCPP 1.6J failure taxonomy, conformant with the + TypeScript toolkit and locked to the `contract-v1` goldens (15/15 scenarios). +- **Inspector** — a native window with a virtualized event timeline (smooth past + 500k events), a message inspector (raw OCPP-J array, normalized fields, a + bounded payload disclosure tree), a session-correlation panel, a ranked failure + drawer with remediation steps, and search / filter facets. Traces open from + command-line paths, with a built-in sample. +- **Analysis** — Markdown and self-contained HTML reports, anonymize-on-export + (redacts idTag / serials / stationId / identifier, resequences transaction ids, + and scrubs email / phone / IPv4 patterns), semantic trace diff, and a + deterministic step-through replay engine with a manual scrub transport. +- **Live capture** — a live WebSocket MITM proxy between a charge point and its + CSMS (hand-rolled RFC 6455 subset): frames are relayed verbatim, decoded in + flight into canonical events, run through detection as they stream, and recorded + to the canonical trace format. Surfaced both in a live inspector timeline and + from the CLI; **OS notifications** fire on critical live failures. +- **Headless CLI** — the same binary is a scriptable CLI: `inspect`, `report` + (markdown / html), `diff` (text / json), `anonymize`, `capture`, `ci`, and + `scenario`. +- **Packaging** — macOS (`.dmg`, ad-hoc signed) and Linux (`.tar.gz`) packages via + `native package`, published by a tag-triggered release workflow. +- **Conformance contract** — the Studio ⇄ toolkit contract frozen and documented + as `contract-v1` ([CONTRACT.md](docs/CONTRACT.md)), CI-gated on every change. + +### Known limitations + +- macOS builds are ad-hoc signed, not notarized (first launch needs + right-click → Open). Notarization is planned post-0.5. +- Failure detection is capped at 50k events (several rules are O(n²)); larger + traces stay fully inspectable with detection skipped. The O(n) rewrite is + tracked upstream. +- TLS (`wss://`) live capture, a menu-bar monitor, and interactive open + (dialog / drag-drop) are planned for later releases. + +[Unreleased]: https://github.com/ocpp-debugkit/studio/commits/main diff --git a/CURRENT_STATE.md b/CURRENT_STATE.md index 7b86622..664d505 100644 --- a/CURRENT_STATE.md +++ b/CURRENT_STATE.md @@ -23,9 +23,11 @@ publishes both to a GitHub release (see [RELEASING.md](RELEASING.md)). The automation smoke now **drives** the GUI (#71) — clicking the replay transport, a filter facet, and the Live tab, asserting the semantics tree after each and screenshotting the inspector + live surfaces. The conformance contract is frozen -as `contract-v1` (#72, [docs/CONTRACT.md](docs/CONTRACT.md), ADR-0012). Remaining: -release-ready docs (#73) and the v0.5.0 cut (#74). The menu-bar monitor and -notarization are post-0.5; see [ROADMAP.md](ROADMAP.md). +as `contract-v1` (#72, [docs/CONTRACT.md](docs/CONTRACT.md), ADR-0012). The docs +are release-ready (#73): the README is present-tense with install / usage and a +live inspector screenshot, and a [CHANGELOG](CHANGELOG.md) stages the 0.5.0 notes. +Remaining: the v0.5.0 cut (#74). The menu-bar monitor and notarization are +post-0.5; see [ROADMAP.md](ROADMAP.md). ## What's done diff --git a/README.md b/README.md index b025e7d..55656e0 100644 --- a/README.md +++ b/README.md @@ -9,7 +9,7 @@ Studio is built in [Zig](https://ziglang.org) on the [Native SDK](https://github.com/vercel-labs/native) — 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. -> 🚧 **Early development.** The foundation is in place (a native window, green CI on macOS + Linux, an automation-driven smoke test). The OCPP engine and inspector UI are next — see the [roadmap](ROADMAP.md). +![The Studio inspector: a virtualized event timeline, message inspector with session correlation, and a failure drawer.](docs/assets/inspector.png) ## The ecosystem @@ -22,26 +22,56 @@ Studio is one of two independent products under the OCPP DebugKit umbrella: The two share **no code**. They meet only at a *conformance contract*: the same trace format, the same normalized event model, the same failure taxonomy, and the same scenario fixtures. A trace captured in Studio opens in the toolkit's web inspector, and vice versa — two independent implementations, one format, checked in CI on every change. See **[the conformance contract](docs/CONTRACT.md)** (`contract-v1`) and [ADR-0001](docs/adr/0001-independent-implementation.md). -## What it will do +## What it does -The near-term vision, in priority order (full detail in the [roadmap](ROADMAP.md)): +- **Inspect** — open JSON / JSONL / bare-array traces in a virtualized timeline that stays smooth past **500k events**; unpack any message (raw OCPP-J array, normalized fields, a payload disclosure tree), see the session it correlates into, and search / filter by action, direction, type, or severity. +- **Detect** — the full **OCPP 1.6J failure taxonomy** (16 rules), bit-for-bit conformant with the toolkit's reference, ranked critical → warning → info with remediation steps. +- **Watch** — a **live WebSocket proxy** between a charge point and its CSMS: decode OCPP 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 GC; 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. -- **Inspect** — open JSON / JSONL / bare-array traces; virtualized timeline, per-message inspector, session correlation, failure list. -- **Detect** — the full OCPP 1.6J failure taxonomy, streaming, as events arrive. -- **Watch** — a live WebSocket proxy between charge point and CSMS, decoding OCPP frames in flight and recording them to the canonical trace format. -- **Prove** — reports, trace diffing, anonymize-on-export, and wall-clock replay. -- **Scale** — stream-parse traces far past what a browser tab can hold. +## Install -## Quick start +Download the latest release for your platform from the +[**Releases**](https://github.com/ocpp-debugkit/studio/releases) page. -Studio is a source-first project during early development. +- **macOS** — open the `.dmg` and drag *OCPP DebugKit Studio* to Applications. The + 0.5.0 build is **ad-hoc signed** (not yet notarized), so the first launch needs + **right-click → Open** (or *System Settings → Privacy & Security → Open Anyway*). +- **Linux** — extract the `.tar.gz` and run the `studio` binary. Requires GTK 4 + (`libgtk-4`, `libwebkitgtk-6.0`). -**Prerequisites** +Studio is pre-1.0 (0.x) while Zig, the Native SDK, and the toolkit conformance +reference are all pre-1.0 — see the [roadmap](ROADMAP.md). -- [Zig](https://ziglang.org/download/) `0.16.0` -- The Native SDK CLI: `npm install -g @native-sdk/cli` +## Usage -**Build and run** +Open a trace in the GUI, or drive the headless CLI: + +```sh +studio path/to/trace.json # open the inspector on a trace +studio # open with the built-in sample + +# Live capture: proxy a charge point ↔ CSMS session and stream it to a file +studio capture --listen 127.0.0.1:9000 \ + --upstream ws://csms.example:9000/ocpp --ndjson > session.jsonl + +# Headless analysis (stdout) +studio inspect trace.json # a parsed + analyzed summary +studio report trace.json -f html > report.html # a full report (markdown | html) +studio diff before.json after.json # semantic diff of two traces +studio anonymize trace.json > shareable.json # strip sensitive fields +studio ci # run the conformance contract (exit 0/1) +``` + +Point your charge point (or the toolkit's tooling) at the `--listen` address and +its traffic is proxied to `--upstream`, decoded, and recorded. Full CLI ⇄ toolkit +parity is documented in [docs/cli-parity.md](docs/cli-parity.md). + +## Build from source + +**Prerequisites:** [Zig](https://ziglang.org/download/) `0.16.0` and the Native SDK CLI (`npm install -g @native-sdk/cli`). ```sh git clone https://github.com/ocpp-debugkit/studio.git @@ -53,7 +83,8 @@ native build # produce a ReleaseFast binary in zig-out/bin/ native check # validate src/*.native markup and app.zon ``` -The `native` CLI owns the build — there is no `build.zig` to manage. +The `native` CLI owns the build — there is no `build.zig` to manage. To build a +distributable package, see [RELEASING.md](RELEASING.md). ## Non-goals @@ -65,7 +96,7 @@ Studio is a debugging instrument, not infrastructure. It is **not**: ## Contributing -Contributions are welcome. Start with [CONTRIBUTING.md](CONTRIBUTING.md), and point your tooling at [AGENTS.md](AGENTS.md) for a structured overview of the architecture and conventions. [CURRENT_STATE.md](CURRENT_STATE.md) tracks what is built and what is in progress. +Contributions are welcome. Start with [CONTRIBUTING.md](CONTRIBUTING.md), and point your tooling at [AGENTS.md](AGENTS.md) for a structured overview of the architecture and conventions. [CURRENT_STATE.md](CURRENT_STATE.md) tracks what is built and what is in progress; [CHANGELOG.md](CHANGELOG.md) records what shipped in each release. ## Security diff --git a/docs/assets/inspector.png b/docs/assets/inspector.png new file mode 100644 index 0000000..373db62 Binary files /dev/null and b/docs/assets/inspector.png differ