From 922e8e03c329b1ce3affd397a5bdcece409f001b Mon Sep 17 00:00:00 2001 From: sepehr-safari Date: Tue, 7 Jul 2026 23:37:47 +0300 Subject: [PATCH] docs: add CONTRIBUTING, CODE_OF_CONDUCT, ROADMAP, README, SECURITY - CONTRIBUTING.md: setup, conventions, PR process, AI-assisted dev section (tool-neutral, no AI tool references) - CODE_OF_CONDUCT.md: Contributor Covenant 2.1 - ROADMAP.md: milestone summary (M0 through v1.0.0) - README.md: description, badges, architecture, quickstart, support section (USDT/BEP20), links - SECURITY.md: vulnerability reporting via GitHub private advisories, security principles for untrusted input handling - CURRENT_STATE.md: updated to reflect all M0 PRs Closes #9, closes #10, closes #11 --- CODE_OF_CONDUCT.md | 130 +++++++++++++++++++++++++++++++ CONTRIBUTING.md | 188 +++++++++++++++++++++++++++++++++++++++++++++ CURRENT_STATE.md | 18 +++-- README.md | 106 ++++++++++++++++++++++++- ROADMAP.md | 135 ++++++++++++++++++++++++++++++++ SECURITY.md | 39 ++++++++++ 6 files changed, 610 insertions(+), 6 deletions(-) create mode 100644 CODE_OF_CONDUCT.md create mode 100644 CONTRIBUTING.md create mode 100644 ROADMAP.md create mode 100644 SECURITY.md diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md new file mode 100644 index 0000000..cc321a8 --- /dev/null +++ b/CODE_OF_CONDUCT.md @@ -0,0 +1,130 @@ +# Contributor Covenant Code of Conduct + +## Our Pledge + +We as members, contributors, and leaders pledge to make participation in our +community a harassment-free experience for everyone, regardless of age, body +size, visible or invisible disability, ethnicity, sex characteristics, gender +identity and expression, level of experience, education, socio-economic status, +nationality, personal appearance, race, caste, color, religion, or sexual +identity and orientation. + +We pledge to act and interact in ways that contribute to an open, welcoming, +diverse, inclusive, and healthy community. + +## Our Standards + +Examples of behavior that promotes a positive environment: + +* Demonstrating empathy and kindness toward other people +* Being respectful of differing opinions, viewpoints, and experiences +* Giving and gracefully accepting constructive feedback +* Accepting responsibility, apologizing to those affected by our mistakes, + and learning from the experience +* Focusing on what is best for the overall community + +Examples of unacceptable behavior: + +* The use of sexualized language or imagery, and sexual attention or advances + of any kind +* Trolling, insulting or derogatory comments, and personal or political attacks +* Public or private harassment +* Publishing others' private information, such as a physical or email address, + without their explicit permission +* Other conduct which could reasonably be considered inappropriate in a + professional setting + +## Enforcement Responsibilities + +Community leaders are responsible for clarifying and enforcing our standards +of acceptable behavior and will take appropriate and fair corrective action in +response to any behavior that they deem inappropriate, threatening, offensive, +or harmful. + +Community leaders have the right and responsibility to remove, edit, or reject +comments, commits, code, wiki edits, issues, and other contributions that are +not aligned to this Code of Conduct, and will communicate reasons for moderation +decisions when appropriate. + +## Scope + +This Code of Conduct applies within all community spaces, and also applies when +an individual is officially representing the community in public spaces. +Examples of representing our community include using an official email address, +posting via an official social media account, or acting as an appointed +representative at an online or offline event. + +## Enforcement + +Instances of abusive, harassing, or otherwise unacceptable behavior may be +reported via [GitHub's private reporting channel](https://github.com/ocpp-debugkit/ocpp-debugkit/security/advisories/new). + +All complaints will be reviewed and investigated promptly and fairly. + +All community leaders are obligated to respect the privacy and security of the +reporter of any incident. + +## Enforcement Guidelines + +Community leaders will follow these Community Impact Guidelines in determining +the consequences for any action they deem in violation of this Code of Conduct: + +### 1. Correction + +**Community Impact**: Use of inappropriate language or other behavior deemed +unprofessional or unwelcome in the community. + +**Consequence**: A private, written warning from community leaders, providing +clarity around the nature of the violation and an explanation of why the +behavior was inappropriate. A public apology may be requested. + +### 2. Warning + +**Community Impact**: A violation through a single incident or series of +actions. + +**Consequence**: A warning with consequences for continued behavior. No +interaction with the people involved, including unsolicited interaction with +those enforcing the Code of Conduct, for a specified period of time. This +includes avoiding interactions in community spaces as well as external channels +like social media. Violating these terms may lead to a temporary or permanent +ban. + +### 3. Temporary Ban + +**Community Impact**: A serious violation of community standards, including +sustained inappropriate behavior. + +**Consequence**: A temporary ban from any sort of interaction or public +communication with the community for a specified period of time. No public or +private interaction with the people involved, including unsolicited +interaction with those enforcing the Code of Conduct, is allowed during this +period. Violating these terms may lead to a permanent ban. + +### 4. Permanent Ban + +**Community Impact**: Demonstrating a pattern of violation of community +standards, including sustained inappropriate behavior, harassment of an +individual, or aggression toward or disparagement of classes of individuals. + +**Consequence**: A permanent ban from any sort of public interaction within the +community. + +## Attribution + +This Code of Conduct is adapted from the [Contributor Covenant][homepage], +version 2.1, available at +[https://www.contributor-covenant.org/version/2/1/code_of_conduct.html][v2.1]. + +Community Impact Guidelines were inspired by +[Mozilla's code of conduct enforcement ladder][mozilla-coc]. + +For answers to common questions about this code of conduct, see the FAQ at +[https://www.contributor-covenant.org/faq][faq]. Translations are available at +[https://www.contributor-covenant.org/translations][translations]. + +[homepage]: https://www.contributor-covenant.org +[v2.1]: https://www.contributor-covenant.org/version/2/1/code_of_conduct.html +[mozilla-coc]: https://www.mozilla.org/en-US/about/governance/policies/enforcement/ +[faq]: https://www.contributor-covenant.org/faq +[translations]: https://www.contributor-covenant.org/translations diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..969f773 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,188 @@ +# Contributing to OCPP DebugKit + +Thank you for your interest in contributing to OCPP DebugKit! This document +covers setup, conventions, and the contribution workflow. + +## Getting Started + +### Prerequisites + +- **Node.js** >= 20.0.0 +- **pnpm** 10.x (`npm install -g pnpm`) +- **Git** + +### Local Setup + +```bash +# Clone the repository +git clone https://github.com/ocpp-debugkit/ocpp-debugkit.git +cd ocpp-debugkit + +# Install dependencies +pnpm install + +# Verify everything works +pnpm lint +pnpm test +pnpm build +``` + +## Monorepo Structure + +``` +ocpp-debugkit/ +├── packages/ +│ ├── core/ # Data model, parser, normalizer, timeline, failure detection +│ ├── scenarios/ # Predefined trace scenarios for testing +│ ├── reporter/ # Report generators (Markdown, HTML) +│ ├── cli/ # Command-line interface +│ ├── replay/ # Replay engine (v0.2+) +│ └── react/ # Reusable React components (v0.2+) +├── apps/ +│ └── web/ # Single Next.js app (landing, inspector, docs, blog) +└── ... +``` + +See [`AGENTS.md`](./AGENTS.md) for a detailed overview of the architecture, +build commands, and package dependency graph. + +## Development Workflow + +### 1. Find or Create an Issue + +All work should be tracked via GitHub Issues. Check existing issues or create +a new one using the appropriate issue template (bug report, feature request, +or scenario request). + +### 2. Create a Branch + +```bash +git checkout -b feat/- +``` + +### 3. Make Your Changes + +- Follow the code style (TypeScript strict, Prettier, ESLint). +- Write tests for the behavior you introduce. +- Update documentation as needed. + +### 4. Verify Locally + +```bash +pnpm lint +pnpm typecheck +pnpm test +pnpm build +``` + +### 5. Add a Changeset + +If your PR changes publishable package behavior, add a changeset: + +```bash +pnpm changeset +``` + +This creates a file in `.changeset/` describing the change and which packages +are affected. + +### 6. Open a Pull Request + +- Use the PR template. +- Link the issue with `Closes #N`. +- Ensure CI passes (lint, typecheck, test, build). + +## Conventions + +### Commit Messages + +This project uses [Conventional Commits](https://www.conventionalcommits.org/): + +``` +feat(core): implement trace parser for JSON input +fix(cli): handle missing trace file gracefully +docs: add architecture overview to docs +chore: add vitest configuration +test(core): add parser edge case tests +``` + +### Branch Naming + +``` +feat/- # e.g. feat/core-parse-trace +fix/- # e.g. fix/cli-stdout-encoding +chore/ # e.g. chore/ci-workflow +docs/ # e.g. docs/readme +test/ # e.g. test/core-coverage +``` + +### Code Style + +- **TypeScript strict mode** — no `any` without justification. +- **Prettier** for formatting (single quotes, trailing commas, 100 char width). +- **ESLint** with `typescript-eslint` strict rules. +- Use `import type` for type-only imports. + +### Testing + +- Tests use **Vitest**. +- Test files: `*.test.ts` / `*.spec.ts`. +- Tests live next to the code they test. +- Coverage target: 70%+ for core package. + +## Security Guidelines + +OCPP DebugKit processes untrusted input (trace files, pasted content). When +working on parsing, CLI, or UI code: + +- **Validate all external input** — CLI args, file content, paste input. +- **Safe JSON parsing** — always use try/catch and enforce size limits. +- **No dynamic code execution** — no `eval()`, `Function()` on untrusted input. +- **No prototype pollution** — validate object shapes, use safe parsing. +- **Path safety** — validate file paths, prevent path traversal. +- **Safe rendering** — no `dangerouslySetInnerHTML`, no unsafe HTML injection. +- **Browser-local processing** — no automatic uploading of user data. +- **No secrets in committed files** — no credentials, API keys, or tokens. +- **No sensitive data in committed artifacts** — use synthetic data in trace + fixtures, sample data, and test data. Real station IDs, transaction IDs, IPs, + or personal information must not appear in committed files. User-loaded + traces and runtime-generated reports are **not** subject to this rule — they + contain the user's own data and must not be redacted. + +If you discover a security vulnerability, please see the +[Security Policy](./SECURITY.md) for responsible disclosure. + +## AI-Assisted Development + +Maintainers may use AI-assisted development tools, but all contributions must +be reviewed, tested, documented, and scoped like normal engineering work. +AI-generated code is held to the same standards as any other contribution: it +must pass CI, include tests, be security-reviewed, and be understandable by a +human reviewer. + +Contributors using AI agents can point them at [`AGENTS.md`](./AGENTS.md) for +a structured overview of this repository's architecture, conventions, and build +system. [`CURRENT_STATE.md`](./CURRENT_STATE.md) reflects what has been built +so far and what is in progress — use it to orient your agent before starting +work. + +No AI tool preference is assumed or required. The project does not endorse any +specific AI tool. + +## Living Documents + +The following documents are updated as part of the work, inside the PR: + +| Document | When updated | +|----------|-------------| +| `CURRENT_STATE.md` | Inside every PR, before merge | +| `AGENTS.md` | When architecture, packages, or build commands change | +| `CONTRIBUTING.md` | When contribution process or conventions change | +| `ROADMAP.md` | At each milestone boundary | +| `README.md` | When description, badges, quickstart, or links change | + +## Questions? + +- Open a [GitHub Issue](https://github.com/ocpp-debugkit/ocpp-debugkit/issues) +- Read the [documentation](https://ocppdebugkit.com/docs) +- Check the [roadmap](./ROADMAP.md) diff --git a/CURRENT_STATE.md b/CURRENT_STATE.md index 064d009..2107960 100644 --- a/CURRENT_STATE.md +++ b/CURRENT_STATE.md @@ -21,7 +21,7 @@ feature code lands. - ✅ GitHub labels created (type, package, priority, workflow) - ✅ 11 tracking issues created and assigned to M0 milestone -### Monorepo & Tooling (in progress — PR #12) +### Monorepo & Tooling (PR #12) - ✅ Root `package.json` with pnpm workspace - ✅ `pnpm-workspace.yaml` (`packages/*`, `apps/*`) - ✅ `tsconfig.base.json` (strict TypeScript config) @@ -32,21 +32,29 @@ feature code lands. - ✅ `NOTICE` file (Apache 2.0) - ✅ `AGENTS.md` + `CURRENT_STATE.md` (initial versions) -### CI & Release (in progress — this PR) +### CI & Release (PR #13) - ✅ `.github/workflows/ci.yml` — lint, format check, typecheck, test, build on PR + push - ✅ `.github/workflows/release.yml` — Changesets version PR, npm publish, ecosystem tag + GitHub release - ✅ `.changeset/config.json` — public access, base branch main -### GitHub Templates (in progress — this PR) +### GitHub Templates (PR #14) - ✅ `.github/PULL_REQUEST_TEMPLATE.md` - ✅ `.github/ISSUE_TEMPLATE/bug_report.md` - ✅ `.github/ISSUE_TEMPLATE/feature_request.md` - ✅ `.github/ISSUE_TEMPLATE/scenario_request.md` +### Community Docs (in progress — this PR) +- ✅ `CONTRIBUTING.md` (setup, conventions, PR process, AI-assisted dev section) +- ✅ `CODE_OF_CONDUCT.md` (Contributor Covenant 2.1) +- ✅ `ROADMAP.md` (milestone summary) +- ✅ `README.md` (description, badges, architecture, quickstart, support, links) +- ✅ `SECURITY.md` (vulnerability reporting, security principles) +## What's Next -1. **PR4** (Issues #9–#11): CONTRIBUTING, CODE_OF_CONDUCT, ROADMAP, README -2. **M0 complete** → proceed to M0.5 (Protocol & Trace-Format Design Phase) +1. **M0 complete** → maintainer reviews and merges PRs #12–#15 +2. Add required status checks to branch protection (after CI runs on main) +3. Proceed to M0.5 (Protocol & Trace-Format Design Phase) ## Known Blockers / Decisions Pending diff --git a/README.md b/README.md index 19d4ce7..3157397 100644 --- a/README.md +++ b/README.md @@ -1 +1,105 @@ -# ocpp-debugkit \ No newline at end of file +# OCPP DebugKit + +> Open-source DevTools for debugging OCPP charging sessions. + +[![CI](https://github.com/ocpp-debugkit/ocpp-debugkit/actions/workflows/ci.yml/badge.svg)](https://github.com/ocpp-debugkit/ocpp-debugkit/actions/workflows/ci.yml) +[![License](https://img.shields.io/badge/license-Apache--2.0-blue.svg)](https://github.com/ocpp-debugkit/ocpp-debugkit/blob/main/LICENSE) +[![npm](https://img.shields.io/badge/npm-%40ocpp--debugkit-blue.svg)](https://www.npmjs.com/org/ocpp-debugkit) + +OCPP DebugKit is a developer toolkit for inspecting, analyzing, and debugging +OCPP (Open Charge Point Protocol) charging session traces. It helps EV charging +infrastructure developers diagnose failures, understand session timelines, and +validate behavior against known scenarios. + +## Features + +- **Trace Inspector** — Load OCPP traces, view session timelines, inspect + 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. +- **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. + +## What It's Not + +- Not a CSMS (Charging Station Management System) +- Not a charging station simulator +- Not a compliance certification tool +- Not an active endpoint tester (scenario evaluation is offline/static) + +## Architecture + +OCPP DebugKit is a pnpm monorepo with independently versioned packages. + +``` + core ← everything depends on this + / | \ + scenarios | reporter | replay + \ | / | + cli | + | | + 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) | + +**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 +git clone https://github.com/ocpp-debugkit/ocpp-debugkit.git +cd ocpp-debugkit +pnpm install +pnpm build +``` + +### CLI (when published) + +```bash +npm install -g @ocpp-debugkit/cli +ocpp-debugkit inspect trace.json +``` + +### Web App + +Visit [ocppdebugkit.com/inspector](https://ocppdebugkit.com/inspector) to +load a trace directly in your browser — no installation required. + +## Links + +- [Documentation](https://ocppdebugkit.com/docs) +- [GitHub](https://github.com/ocpp-debugkit/ocpp-debugkit) +- [npm](https://www.npmjs.com/org/ocpp-debugkit) +- [Roadmap](./ROADMAP.md) +- [Contributing](./CONTRIBUTING.md) + +## Support the project + +This project is free and open source. + +If it saves you time, you can contribute any amount to help cover +maintenance, testing, documentation, and infrastructure. + +- Support with USDT — BNB Smart Chain (BEP20): `0x5Fd014e5f9d6C2d6d440752e296d0681aA943633` + +## License + +[Apache License 2.0](./LICENSE) diff --git a/ROADMAP.md b/ROADMAP.md new file mode 100644 index 0000000..8cf5250 --- /dev/null +++ b/ROADMAP.md @@ -0,0 +1,135 @@ +# Roadmap + +> OCPP DebugKit — Open-source DevTools for debugging OCPP charging sessions. + +This roadmap tracks the milestone-based development of OCPP DebugKit. +Each milestone maps to a semantic version release. + +--- + +## M0 — Repository & Tooling Foundation + +**Status:** In progress + +Professional monorepo skeleton with CI, linting, testing, release tooling, +GitHub metadata, and agent onboarding docs — before any feature code lands. + +- pnpm monorepo + workspace +- TypeScript strict config +- ESLint + Prettier + EditorConfig +- Vitest + example test +- Turborepo pipeline +- GitHub Actions CI +- Changesets release workflow +- GitHub labels, milestones, PR/issue templates +- README, CONTRIBUTING, CODE_OF_CONDUCT, ROADMAP, AGENTS.md, CURRENT_STATE.md + +**Exit criteria:** `pnpm install` / `pnpm test` / `pnpm lint` / `pnpm build` +all work. CI green on main. No release yet — infrastructure only. + +--- + +## M0.5 — Protocol & Trace-Format Design Phase + +**Status:** Not started + +Resolve all foundational design decisions before core implementation. +Produce ADRs and synthetic fixtures that validate the internal model. + +- OCPP version scope (1.6 JSON primary, extensible to 2.0.1) +- Input trace formats (JSON, JSONL) +- Canonical internal event model +- Message direction and timestamp normalization +- Station, connector, transaction correlation +- Malformed/incomplete trace handling +- Browser-local processing and privacy +- ADRs for each major decision +- 3+ synthetic trace fixtures + +**Exit criteria:** ADRs written, trace format spec documented, fixtures +validate against proposed model. Maintainer approves design. + +--- + +## v0.1.0 — Inspector MVP + +**Status:** Not started + +A user visits ocppdebugkit.com, loads a trace, sees a timeline, sees detected +failures, and exports a report — without installing anything. Developers can +also use the CLI locally. + +- **Core:** Trace parser, event normalizer, session timeline, failure detection + (3 rules), summarizer, validator, package config +- **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) +- **Tests:** Playwright smoke tests +- **Docs:** Quickstart, glossary, architecture, CLI reference, API reference + +**Exit criteria:** Hosted demo, CLI on npm, trace→timeline→failures→report +workflow, 5 scenarios, 3 failure rules, GitHub release `release-v0.1.0`. + +--- + +## v0.2.0 — Scenario Evaluator & Replay + +**Status:** Not started + +Make the tool genuinely useful for developers' daily workflows. + +- Expanded failure detection rules (7 new rules) +- 10 total scenarios +- Replay engine package +- Extracted React components package +- CLI: external scenario files, offline evaluator +- HTML report format +- App: replay UI, report viewer, React refactor + +**Exit criteria:** GitHub release `release-v0.2.0`. + +--- + +## v0.3.0 — Integrations & OSS Credibility + +**Status:** Not started + +Connect to real ecosystem workflows. Attract external engagement. + +- v0.3 failure detection rules +- Trace diffing +- Rich scenario assertions +- CLI: CI mode, anonymize, diff commands +- Integration examples (simple-trace, simple-csms, simulator-output, etc.) +- Contribution guide + good-first-issues + +**Exit criteria:** GitHub release `release-v0.3.0`. + +--- + +## v1.0.0 — Stable FOSS Ecosystem + +**Status:** Not started + +Mature APIs, stable formats, contributor-ready. + +- API stabilization +- 20+ scenarios +- Docs overhaul (tutorials, deep-dives) +- Release workflow hardening +- Contributor onboarding + +**Exit criteria:** GitHub release `release-v1.0.0`. + +--- + +## Future Considerations + +Explicitly out of scope for v1.0 but may be revisited: + +- **Active scenario runner** — connects to live charging stations or CSMS + endpoints via WebSocket. Requires transport, timing, state management, and + protocol interaction design. +- **Playground** (`/playground`) — interactive OCPP message composer/sandbox. +- **YAML trace format support** — JSON first, YAML later if useful. diff --git a/SECURITY.md b/SECURITY.md new file mode 100644 index 0000000..283b25e --- /dev/null +++ b/SECURITY.md @@ -0,0 +1,39 @@ +# Security Policy + +## Reporting a Vulnerability + +If you discover a security vulnerability in OCPP DebugKit, please report it +responsibly: + +1. **Do not** open a public GitHub issue. +2. Go to [github.com/ocpp-debugkit/ocpp-debugkit/security/advisories/new](https://github.com/ocpp-debugkit/ocpp-debugkit/security/advisories/new) + and create a private security advisory. +3. Include a description of the vulnerability, steps to reproduce, and + potential impact. +4. You will receive an acknowledgment within 48 hours. +5. We will investigate and work with you on a fix before any public disclosure. + +## Security Considerations + +OCPP DebugKit processes untrusted input (trace files, pasted content). The +following security principles are enforced: + +- **Input validation** at all external entry points (CLI args, file content, + paste input in the browser). +- **Safe JSON parsing** — try/catch with size guards on all untrusted input. +- **No dynamic code execution** — no `eval()`, `Function()`, or similar on + untrusted input. +- **No prototype pollution** — object shapes validated, safe parsing used. +- **Path safety** — file paths validated to prevent path traversal in CLI. +- **Safe rendering** — no `dangerouslySetInnerHTML` or unsafe HTML injection. +- **Browser-local processing** — no automatic uploading of user trace data. +- **Size limits** — file-size and event-count limits enforced on trace input. +- **No secrets in committed files** — no credentials, API keys, or tokens. +- **No sensitive data in committed artifacts** — synthetic data only in + trace fixtures, sample data, and test data. + +## Scope + +This policy applies to the OCPP DebugKit codebase, including all packages and +the web application. It does not apply to user-loaded traces or runtime-generated +reports — those contain the user's own data and are processed locally.