From 3dac80a45a0735f6797c512351921f6020eca6a4 Mon Sep 17 00:00:00 2001 From: sepehr-safari Date: Wed, 8 Jul 2026 12:36:31 +0300 Subject: [PATCH] =?UTF-8?q?docs:=20post-v0.1.0=20cleanup=20=E2=80=94=20upd?= =?UTF-8?q?ate=20README,=20ROADMAP,=20CURRENT=5FSTATE,=20web=20README?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Update all stale documentation to reflect the released v0.1.0 state: - README: remove 'not yet published' caveat, add npm version badges to package table, fix Features list (Scenario Evaluator is v0.2 scope), add CLI usage examples, correct reporter to Markdown-only - ROADMAP: mark M0/M0.5/v0.1.0 as complete with release details, set v0.2.0 as 'Next up', fix docs description (Nextra → Next.js, no API ref) - CURRENT_STATE: fix 'What's Next' (v0.1.0 release is done), update package status table to published/0.1.1/deployed - apps/web/README: replace create-next-app boilerplate with real project description, routes, architecture, dev/test instructions --- CURRENT_STATE.md | 20 +++++++++------- README.md | 43 +++++++++++++++++++++------------- ROADMAP.md | 17 ++++++++------ apps/web/README.md | 58 ++++++++++++++++++++++++++++------------------ 4 files changed, 84 insertions(+), 54 deletions(-) diff --git a/CURRENT_STATE.md b/CURRENT_STATE.md index 9d9e64c..c20c69f 100644 --- a/CURRENT_STATE.md +++ b/CURRENT_STATE.md @@ -158,9 +158,13 @@ All v0.1.0 issues complete. Packages published to npm. Web app deployed. ## What's Next -1. **v0.1.0 release** — merge version PR, CI publishes packages, creates tag + GitHub release -2. **v0.2.0** — Scenario evaluator & replay (new failure rules, replay engine, @ocpp-debugkit/react) -3. **v0.3.0** — Integrations & OSS credibility (trace diffing, CI mode, anonymize, examples) +1. **v0.2.0** — Scenario evaluator & replay (expanded failure rules, replay + engine, `@ocpp-debugkit/react`, CLI external scenario files, HTML report + format, app replay UI) +2. **v0.3.0** — Integrations & OSS credibility (trace diffing, CI mode, + anonymize, integration examples) +3. **v1.0.0** — API stabilization, 20+ scenarios, docs overhaul, contributor + onboarding ## Known Blockers / Decisions Pending @@ -170,10 +174,10 @@ All v0.1.0 issues complete. Packages published to npm. Web app deployed. | Package | Status | Version | |---------|--------|---------| -| `@ocpp-debugkit/core` | done (v0.1.0) | 0.1.0 | -| `@ocpp-debugkit/scenarios` | done (v0.1.0) | 0.1.0 | -| `@ocpp-debugkit/reporter` | done (v0.1.0) | 0.1.0 | -| `@ocpp-debugkit/cli` | done (v0.1.0) | 0.1.0 | +| `@ocpp-debugkit/core` | published | 0.1.1 | +| `@ocpp-debugkit/scenarios` | published | 0.1.1 | +| `@ocpp-debugkit/reporter` | published | 0.1.1 | +| `@ocpp-debugkit/cli` | published | 0.1.1 | | `@ocpp-debugkit/replay` | not started | — | | `@ocpp-debugkit/react` | not started | — | -| `apps/web` | done (v0.1.0) | — | +| `apps/web` | deployed | — | diff --git a/README.md b/README.md index 3157397..0f90a92 100644 --- a/README.md +++ b/README.md @@ -17,13 +17,17 @@ validate behavior against known scenarios. individual messages, and identify failures. - **Failure Detection** — Automatically detect common session failure patterns (failed authorization, connector faults, station offline). -- **Scenario Evaluator** — Run predefined scenarios through the analysis engine - and compare detected vs expected failures. -- **Report Generation** — Export session analysis as Markdown or HTML reports. +- **Scenario Library** — 5 predefined trace scenarios with expected failure + outcomes for testing the analysis engine. +- **Report Generation** — Export session analysis as Markdown reports. - **CLI** — Analyze traces from the command line. - **Browser-Local** — All trace processing happens in your browser. No data leaves your machine when using the web app. +> **Scenario Evaluator & Replay** (comparing detected vs expected failures, +> replay engine, extracted React components) is planned for v0.2.0. See the +> [Roadmap](./ROADMAP.md). + ## What It's Not - Not a CSMS (Charging Station Management System) @@ -45,23 +49,20 @@ OCPP DebugKit is a pnpm monorepo with independently versioned packages. apps/web (single Next.js app) ``` -| Package | Description | -|---------|-------------| -| `@ocpp-debugkit/core` | Data model, trace parser, event normalizer, timeline, failure detection | -| `@ocpp-debugkit/scenarios` | Predefined trace scenarios for testing | -| `@ocpp-debugkit/reporter` | Report generators (Markdown, HTML) | -| `@ocpp-debugkit/cli` | Command-line interface | -| `@ocpp-debugkit/replay` | Replay engine (v0.2+) | -| `@ocpp-debugkit/react` | Reusable React components (v0.2+) | -| `apps/web` | Single Next.js app (landing, inspector, docs) | +| Package | Description | Version | +|---------|-------------|---------| +| `@ocpp-debugkit/core` | Data model, trace parser, event normalizer, timeline, failure detection | [![npm](https://img.shields.io/npm/v/@ocpp-debugkit/core.svg)](https://www.npmjs.com/package/@ocpp-debugkit/core) | +| `@ocpp-debugkit/scenarios` | Predefined trace scenarios for testing | [![npm](https://img.shields.io/npm/v/@ocpp-debugkit/scenarios.svg)](https://www.npmjs.com/package/@ocpp-debugkit/scenarios) | +| `@ocpp-debugkit/reporter` | Report generators (Markdown) | [![npm](https://img.shields.io/npm/v/@ocpp-debugkit/reporter.svg)](https://www.npmjs.com/package/@ocpp-debugkit/reporter) | +| `@ocpp-debugkit/cli` | Command-line interface | [![npm](https://img.shields.io/npm/v/@ocpp-debugkit/cli.svg)](https://www.npmjs.com/package/@ocpp-debugkit/cli) | +| `@ocpp-debugkit/replay` | Replay engine | _planned (v0.2.0)_ | +| `@ocpp-debugkit/react` | Reusable React components | _planned (v0.2.0)_ | +| `apps/web` | Single Next.js app (landing, inspector, docs) | — | **Build order:** core → scenarios/reporter/replay → cli → app ## Quickstart -> Packages are not yet published to npm. This section will be updated when -> v0.1.0 is released. - ### From source ```bash @@ -71,13 +72,23 @@ pnpm install pnpm build ``` -### CLI (when published) +### CLI + +Packages are published to npm under the `@ocpp-debugkit` scope: ```bash npm install -g @ocpp-debugkit/cli ocpp-debugkit inspect trace.json ``` +Other commands: + +```bash +ocpp-debugkit report trace.json --output report.md +ocpp-debugkit scenario list +ocpp-debugkit scenario run failed-auth +``` + ### Web App Visit [ocppdebugkit.com/inspector](https://ocppdebugkit.com/inspector) to diff --git a/ROADMAP.md b/ROADMAP.md index 8cf5250..c1e9950 100644 --- a/ROADMAP.md +++ b/ROADMAP.md @@ -9,7 +9,7 @@ Each milestone maps to a semantic version release. ## M0 — Repository & Tooling Foundation -**Status:** In progress +**Status:** ✅ Complete (merged via PR #12–#15) Professional monorepo skeleton with CI, linting, testing, release tooling, GitHub metadata, and agent onboarding docs — before any feature code lands. @@ -31,7 +31,7 @@ all work. CI green on main. No release yet — infrastructure only. ## M0.5 — Protocol & Trace-Format Design Phase -**Status:** Not started +**Status:** ✅ Complete (merged via PR #19) Resolve all foundational design decisions before core implementation. Produce ADRs and synthetic fixtures that validate the internal model. @@ -53,7 +53,9 @@ validate against proposed model. Maintainer approves design. ## v0.1.0 — Inspector MVP -**Status:** Not started +**Status:** ✅ Released — GitHub release `release-v0.1.0`, packages published +to npm at 0.1.1 (`@ocpp-debugkit/core`, `scenarios`, `reporter`, `cli`). +Web app deployed at ocppdebugkit.com. A user visits ocppdebugkit.com, loads a trace, sees a timeline, sees detected failures, and exports a report — without installing anything. Developers can @@ -64,18 +66,19 @@ also use the CLI locally. - **Scenarios:** 5 initial scenarios with expected failures - **Reporter:** Markdown report generator - **CLI:** inspect, report, scenario list/run commands -- **App:** Single Next.js app (landing, inspector, docs via Nextra) +- **App:** Single Next.js app (landing, inspector, docs) - **Tests:** Playwright smoke tests -- **Docs:** Quickstart, glossary, architecture, CLI reference, API reference +- **Docs:** Quickstart, glossary, architecture, CLI reference, scenarios **Exit criteria:** Hosted demo, CLI on npm, trace→timeline→failures→report -workflow, 5 scenarios, 3 failure rules, GitHub release `release-v0.1.0`. +workflow, 5 scenarios, 3 failure rules, GitHub release `release-v0.1.0`. ✅ All +met. --- ## v0.2.0 — Scenario Evaluator & Replay -**Status:** Not started +**Status:** Next up Make the tool genuinely useful for developers' daily workflows. diff --git a/apps/web/README.md b/apps/web/README.md index e215bc4..d8aaa92 100644 --- a/apps/web/README.md +++ b/apps/web/README.md @@ -1,36 +1,48 @@ -This is a [Next.js](https://nextjs.org) project bootstrapped with [`create-next-app`](https://nextjs.org/docs/app/api-reference/cli/create-next-app). +# OCPP DebugKit — Web App -## Getting Started +The web front-end for [OCPP DebugKit](https://github.com/ocpp-debugkit/ocpp-debugkit), +a DevTools project for debugging OCPP charging session traces. -First, run the development server: +This is a [Next.js](https://nextjs.org) app (App Router) using Tailwind CSS. It +is the only app in the monorepo and hosts the landing page, trace inspector, +and documentation. -```bash -npm run dev -# or -yarn dev -# or -pnpm dev -# or -bun dev -``` +## Routes -Open [http://localhost:3000](http://localhost:3000) with your browser to see the result. +| Route | Description | +|-------|-------------| +| `/` | Landing page — hero, features, architecture, quick start | +| `/inspector` | Trace inspector — paste/upload a trace, view timeline, failures, export report | +| `/docs` | Documentation — quickstart, glossary, architecture, trace format, CLI reference, scenarios | -You can start editing the page by modifying `app/page.tsx`. The page auto-updates as you edit the file. +## Architecture -This project uses [`next/font`](https://nextjs.org/docs/app/building-your-application/optimizing/fonts) to automatically optimize and load [Geist](https://vercel.com/font), a new font family for Vercel. +All trace processing happens client-side in the browser — no trace data is +uploaded to a server. The app uses workspace dependencies on +`@ocpp-debugkit/core`, `@ocpp-debugkit/scenarios`, and +`@ocpp-debugkit/reporter` for parsing, analysis, and report generation. -## Learn More +## Development -To learn more about Next.js, take a look at the following resources: +```bash +# From the monorepo root +pnpm install +pnpm dev +``` + +Open [http://localhost:3000](http://localhost:3000). -- [Next.js Documentation](https://nextjs.org/docs) - learn about Next.js features and API. -- [Learn Next.js](https://nextjs.org/learn) - an interactive Next.js tutorial. +## Testing -You can check out [the Next.js GitHub repository](https://github.com/vercel/next.js) - your feedback and contributions are welcome! +Playwright E2E smoke tests cover the landing page, navigation, and inspector +flows: -## Deploy on Vercel +```bash +# From apps/web +pnpm exec playwright install --with-deps chromium +pnpm test:e2e +``` -The easiest way to deploy your Next.js app is to use the [Vercel Platform](https://vercel.com/new?utm_medium=default-template&filter=next.js&utm_source=create-next-app&utm_campaign=create-next-app-readme) from the creators of Next.js. +## License -Check out our [Next.js deployment documentation](https://nextjs.org/docs/app/building-your-application/deploying) for more details. +Apache 2.0 — see the [monorepo LICENSE](../../LICENSE).