kirby-ocpp 0.1.2 → 0.3.0

package/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2026
+Copyright (c) 2026 Kirill Belolipetsky
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/README.md

@@ -1,130 +1,234 @@
 # kirby-ocpp
 
-Terminal OCPP 1.6J charge point emulator for local and staging CSMS testing.
+Terminal OCPP 1.6J charge point emulator for local and staging CSMS testing, written in Rust.
 
-It runs as an interactive TUI, speaks OCPP 1.6 JSON over WebSocket, validates payloads against bundled OCPP 1.6J JSON schemas, and can persist station state per charge point id.
+It speaks OCPP 1.6 JSON over WebSocket (`ws://` and `wss://`, including mutual TLS), validates every payload against the bundled official OCPP 1.6J JSON schemas, persists station state per charge point id, and can be used three ways:
+
+- an interactive terminal UI (default when stdout is a terminal);
+- a headless event logger (`--no-tui`, `--json`);
+- a scripted scenario runner for CI (`kirby-ocpp run --scenario ...`).
 
 ## Install
 
-Run without installing:
+With Node.js (no Rust needed; installs the prebuilt binary for your platform):
 
 ```bash
 npx kirby-ocpp --url ws://localhost:9000/ocpp --id CP-001
-```
-
-Or install globally:
-
-```bash
 npm install -g kirby-ocpp
-kirby-ocpp --url ws://localhost:9000/ocpp --id CP-001
 ```
 
-## Usage
+With Cargo (Rust 1.88 or newer):
 
 ```bash
-kirby-ocpp --url ws://localhost:9000/ocpp --id CP-001
+cargo install kirby-ocpp
 ```
 
-Common options:
+Or download a prebuilt binary for Linux (x86_64 glibc, aarch64 glibc, x86_64 static musl for Alpine and minimal containers), macOS or Windows from the [GitHub releases](https://github.com/archhaze24/kirby-ocpp/releases). To build from a checkout: `cargo install --path crates/kirby-ocpp`.
 
-```bash
-kirby-ocpp \
-  --url ws://localhost:9000/ocpp \
-  --id CP-001 \
-  --vendor Kirby \
-  --model TUI-16 \
-  --connector 1 \
-  --connectors 2 \
-  --heartbeat 30
-```
-
-WSS/TLS options:
+## Quick start
 
 ```bash
-kirby-ocpp \
-  --url wss://csms.example.com/ocpp \
-  --id CP-001 \
-  --tls-ca ./ca.pem \
-  --tls-cert ./client-cert.pem \
-  --tls-key ./client-key.pem
+kirby-ocpp --url ws://localhost:9000/ocpp --id CP-001          # TUI
+kirby-ocpp --url ws://localhost:9000/ocpp --no-tui --json       # headless, JSON lines
+kirby-ocpp --url ws://localhost:9000/ocpp run --scenario charge-session
 ```
 
-Useful runtime flags:
-
-- `--no-persist`: run an ephemeral station.
-- `--state-dir <path>`: choose where station state is stored.
-- `--ws-subprotocol <protocol>`: defaults to `ocpp1.6`.
-- `--ws-ping <seconds>`: WebSocket ping interval, `0` disables pings.
-- `--no-reconnect`: disable automatic reconnect.
-- `--reconnect-initial-ms <ms>`, `--reconnect-max-ms <ms>`, `--reconnect-max-attempts <count>`: reconnect backoff.
-- `--call-timeout-ms <ms>`: OCPP CALL response timeout.
-- `--tls-server-name <name>` and `--tls-skip-verify`: local/self-signed WSS testing.
-
-Environment variables mirror the main flags: `OCPP_URL`, `OCPP_CHARGE_POINT_ID`, `OCPP_VENDOR`, `OCPP_MODEL`, `OCPP_WS_SUBPROTOCOL`, `OCPP_WS_PING_INTERVAL`, `OCPP_RECONNECT`, `OCPP_RECONNECT_INITIAL_MS`, `OCPP_RECONNECT_MAX_MS`, `OCPP_RECONNECT_MAX_ATTEMPTS`, `OCPP_CALL_TIMEOUT_MS`, `OCPP_TLS_CA_FILE`, `OCPP_TLS_CERT_FILE`, `OCPP_TLS_KEY_FILE`, `OCPP_TLS_SERVER_NAME`, and `OCPP_TLS_SKIP_VERIFY`.
+`--url` (or `OCPP_URL`) is the only required option. Precedence is flag, then environment variable, then default. Booleans accept `true/false/yes/no/y/n/on/off/1/0`.
+
+## Options
+
+| Flag | Env | Default | Meaning |
+| --- | --- | --- | --- |
+| `-u, --url` | `OCPP_URL` | required | CSMS WebSocket URL (`ws://` or `wss://`) |
+| `-i, --id` | `OCPP_CHARGE_POINT_ID` | `CP-001` | Charge point id |
+| `--vendor` | `OCPP_VENDOR` | `archhaze24` | BootNotification vendor |
+| `--model` | `OCPP_MODEL` | `KIRBY` | BootNotification model |
+| `--serial` | `OCPP_SERIAL` | none | Serial number (max 25 chars) |
+| `--firmware-version` | `OCPP_FIRMWARE_VERSION` | none | Firmware version (max 50 chars) |
+| `-c, --connector` | | `1` | Initial connector |
+| `--connectors` | | `1` | Number of connectors |
+| `--heartbeat` | | `30` | Fallback heartbeat interval (s) |
+| `--nominal-power-w` | | `7200` | Nominal charging power per connector (W); charging profiles can only lower it |
+| `--voltage-v` | | `230` | Voltage per phase (V), used for A to W conversion and the `Voltage` reading |
+| `--phases` | | `1` | Number of phases (1-3) |
+| `--ws-subprotocol` | `OCPP_WS_SUBPROTOCOL` | `ocpp1.6` | Requested subprotocol |
+| `--ws-ping` | `OCPP_WS_PING_INTERVAL` | `30` | WebSocket ping interval (s), `0` disables |
+| `--reconnect <BOOL>` | `OCPP_RECONNECT` | `true` | Auto-reconnect after unexpected disconnect |
+| `--no-reconnect` | | | Disable auto-reconnect (wins over `--reconnect`) |
+| `--reconnect-initial-ms` | `OCPP_RECONNECT_INITIAL_MS` | `1000` | Initial backoff; `0` is rejected (exit 2) unless `--reconnect-max-attempts` is set or reconnect is off |
+| `--reconnect-max-ms` | `OCPP_RECONNECT_MAX_MS` | `30000` | Maximum backoff |
+| `--reconnect-max-attempts` | `OCPP_RECONNECT_MAX_ATTEMPTS` | `0` | `0` = unlimited |
+| `--call-timeout-ms` | `OCPP_CALL_TIMEOUT_MS` | `30000` | CALL response timeout |
+| `--tls-ca` | `OCPP_TLS_CA_FILE` | system roots | CA bundle (PEM) |
+| `--tls-cert`, `--tls-key` | `OCPP_TLS_CERT_FILE`, `OCPP_TLS_KEY_FILE` | | Client certificate and key for mTLS (both or neither) |
+| `--tls-server-name` | `OCPP_TLS_SERVER_NAME` | URL host | SNI / verification name override |
+| `--tls-skip-verify` | `OCPP_TLS_SKIP_VERIFY` | off | Skip certificate verification (testing only) |
+| `--no-persist` | `KIRBY_OCPP_NO_PERSIST` | off | Do not load or save station state |
+| `--state-dir` | `KIRBY_OCPP_STATE_DIR` | `~/.kirby-ocpp/stations` | State directory (`%USERPROFILE%` on Windows) |
+| `--count` | `OCPP_COUNT` | `1` | Number of stations (fleet mode, 1-1000), see [Fleet mode](#fleet-mode) |
+| `--id-template` | `OCPP_ID_TEMPLATE` | the `--id` value | Charge point id template with `{n}` / `{n:03}` |
+| `--first-index` | `OCPP_FIRST_INDEX` | `1` | Index of the first station |
+| `--stagger-ms` | `OCPP_STAGGER_MS` | `0` | Delay between starting two stations (ms) |
+| `--rule ACTION=BEHAVIOR[*N]` | `KIRBY_OCPP_RULES` (`;` separates rules) | none | Response rule for a CSMS command, repeatable; see [Response rules](#response-rules) |
+| `--print-config` | | | Print the effective configuration as JSON and exit |
+| `--no-tui` | | | Never start the TUI; log to stdout |
+| `--json` | | | JSON lines instead of text (events and the `run` report) |
+| `--log-file` | | | Also append the headless event log to a file |
+| `--licenses` | | | Print licence notices and exit |
+| `-V, --version`, `-h, --help` | | | |
+
+Options are global and may be placed before or after a subcommand.
+
+## TLS
+
+`wss://` uses rustls. Without `--tls-ca` the operating system trust store is used. Use `--tls-ca` for a private CA, `--tls-cert`/`--tls-key` for client authentication, `--tls-server-name` when the URL host differs from the certificate name, and `--tls-skip-verify` only against local self-signed servers.
+
+## State persistence
+
+Per charge point id, one JSON file `<state dir>/<id>.station.json` holds the local authorization list and its version, authorization cache, charging profiles, writable configuration values, availability (including a `Scheduled` change waiting for a transaction to end), connector count and per-connector state (status, meter, reservation, transaction) and the offline transaction queue. Ids whose escaped name would exceed 100 bytes are shortened and get a hash suffix (`...~<16 hex>.station.json`) so the name always fits the filesystem limit. Files are versioned and written atomically (temp file plus rename, then the directory is fsynced); a corrupt file or one belonging to another charge point is moved to `<file>.bak` and the station starts clean. `--no-persist` disables both loading and saving.
+
+## Terminal UI
+
+Seven tabs, switched with `1`-`7` or `Tab`/`Shift-Tab`: Station, Connector, Transaction, Maintenance, Data, Logs, Scenarios. Panes: connectors, actions, log (move focus with Left/Right).
+
+| Key | Action |
+| --- | --- |
+| `Up/Down`, `j/k`, `PageUp/PageDown` | Move in the focused pane |
+| `[` `]` | Previous / next connector |
+| `Enter` | Run the selected action / open the selected log row |
+| letters | Accelerators of the current tab's actions (shown in the list) |
+| `/` or `:` or `Ctrl-P` | Command palette (fuzzy search over all actions); `/` searches the log when the log pane is focused on the Logs tab |
+| `Esc` | Close dialog / clear log search |
+| `?` | Help |
+| `q`, `Ctrl-C` | Quit |
+
+Actions: connect/disconnect/reconnect, BootNotification, Heartbeat, add connector, response rules (`m` adds one, `Action=off` removes one, `M` clears all; active rules are listed in the Station pane); plug/unplug, set status, StatusNotification, fault toggle; Authorize, StartTransaction, StopTransaction (with reason), MeterValues; set diagnostics/firmware outcome and send their status notifications; DataTransfer, vendor ping and raw CALLs.
+
+Data browser (Station tab: `K` config keys, `L` local authorization list, `P` charging profiles; also in the palette): one popup with three pages, switched with `Tab`/`Shift-Tab`, `Left`/`Right` or `1`-`3`. `/` filters the rows fuzzily (`Enter` keeps the filter, `Esc` clears it), `Up/Down`/`j/k`/`PageUp/PageDown`/`g`/`G` move, `Esc`/`q` closes. Forms and confirmations opened from the browser return to it. Edits are local commands that behave like the CSMS-triggered ones, without a CSMS round trip:
+
+| Page | Keys |
+| --- | --- |
+| Config keys | `Enter`/`e` edits the selected key (read-only keys are marked `(ro)` and refuse); the value is checked live with the station's own rules, as `ChangeConfiguration` would, and applied with the same side effects (heartbeat/metering timers) and persistence |
+| Local auth list | `a` adds, `Enter`/`e` edits (idTag, status, expiry, parent), `d` removes, `c` clears (asks first). Each add/edit/remove is a differential update that bumps the list version by one; clear empties the list and resets the version to 0 |
+| Charging profiles | `i` installs a profile from JSON (a template is prefilled; paste your own: `csChargingProfiles` object plus connector, validated against the `SetChargingProfile` schema and the station's profile rules), `e` edits the selected one (same id replaces it), `Enter` shows its JSON (`c` there copies), `d` deletes it, `c` clears all (asks first) |
+
+The snapshot behind it (`Snapshot::config`, `local_list`, `charging_profiles`) is also available to API users; the local list view holds at most 500 entries (`total` has the real count).
+
+Log view (Logs tab): CALL/RESULT/ERROR correlation, filters (all, calls, errors, station, csms; `f`), search (`s`), pause/follow (`p`), jump to newest (`G`), detail view with scroll (`Enter`; `c`/`y` copies), copy row (`y`) or visible rows (`Y`), export as JSONL (`e`, default `./kirby-ocpp-<id>-<timestamp>.jsonl`), clear with confirmation (`c`). The buffer keeps the last 2000 entries. Copying tries external clipboard tools first and falls back to the terminal's OSC 52 sequence.
+
+Scenarios tab: one `Run: <name>` action per built-in scenario (keys `o`, `w`, `s`, `i` for the first four) and `l` to load a scenario file, `x` to cancel the running one.
+
+## Headless mode and exit codes
+
+Without a TTY (or with `--no-tui`) the tool connects and prints events until SIGINT/SIGTERM, then closes the WebSocket cleanly. With `--json` each line is one JSON object; frames carry a `payload` field.
+
+`kirby-ocpp run --scenario <name|file.toml> [--report report.json] [--timeout 60] [--id-tag TAG]` connects, waits for an accepted BootNotification, runs the scenario and prints a PASS/FAIL/SKIP report (a JSON object with `"type": "report"` under `--json`).
+
+| Code | Meaning |
+| --- | --- |
+| 0 | Success (scenario passed, normal shutdown) |
+| 1 | Scenario failed or timed out, or a runtime error |
+| 2 | Usage or configuration error |
+| 130 | `run` interrupted by SIGINT (Ctrl-C); SIGTERM still ends it with 1 |
+
+## Fleet mode
+
+`--count N` runs N independent stations in one process against the same CSMS, for load and multi-station tests (terminal UI on a TTY, headless with `--no-tui` or without one).
 
-## TUI
-
-The interface is organized into tabs. Use `1`-`7` or `Tab` / `Shift+Tab` to switch tabs, `Up` / `Down` to select an action, and `Enter` to run it.
+```
+kirby-ocpp --url ws://localhost:9000/ocpp --id 'CP-{n:03}' --count 50 --stagger-ms 100 --no-tui
+kirby-ocpp --url ws://localhost:9000/ocpp --id 'CP-{n}' --count 20 run --scenario charge-session
+```
 
-- `1` Station
-- `2` Connector
-- `3` Transaction
-- `4` Maintenance
-- `5` Data
-- `6` Logs
-- `7` Scenarios
+- The id comes from `--id-template`, or from `--id` when no template is given. `{n}` is the station index, `{n:03}` the index zero-padded to 3 digits; `{{` and `}}` are literal braces. With `--count` above 1 the template needs a placeholder (otherwise exit 2). `--first-index` (default 1) is the index of the first station, so `--count 3 --first-index 10` gives `CP-10`, `CP-11`, `CP-12`. `--count 1` without `--id-template` uses `--id` as is; with an explicit template it is expanded too.
+- Every station is a normal station (own connection, transactions, state file named after its id, so state files never collide). `--stagger-ms` waits that long between starting two stations.
+- The terminal UI shows a selector row on top (`1 CP-001+* 2 CP-002- ...`: index, id, connection glyph `+` connected, `~` connecting/retrying, `-` offline, `*` a transaction is running) and the selected station below. Everything else (status, log, actions, `K`/`L`/`P` browsers, forms, scenarios) works on the selected station only; each station keeps its own log (last 500 rows), dialogs and scenario progress, and events of the other stations keep being recorded. `Alt` combinations may need "Option as Meta" in macOS terminals. With `--count 1` there is no selector and no extra keys. Quit stops the whole fleet.
+- Output is tagged with the station id: `[CP-001] ...` in front of every human line, a `"station"` field in every JSON line, stdout and `--log-file` alike. With `--count 1` nothing is tagged.
+- `run --scenario` runs the scenario on every station at the same time and prints one report per station (tagged), then one aggregate line: `fleet: 3/3 stations PASSED`, or `fleet: 2/3 stations passed, FAILED: CP-2`. With `--json` the aggregate is `{"type":"fleet_report","passed":bool,"total":n,"passed_count":n,"failed":[ids],"stations":[...]}`. `--timeout` covers the whole fleet, stagger included. `--report out.json` writes one file per station: `out.CP-001.json` (characters of the id other than letters, digits, `-` and `_` become `_`).
+
+| Fleet key | Action |
+|---|---|
+| `<` `>` | Previous / next station |
+| `Alt-1` .. `Alt-9` | Jump to station 1..9 |
+| `Alt-c` / `Alt-d` | Connect / disconnect all stations |
+
+Selector keys work in normal mode only (inside a dialog they are plain input).
+- Exit codes: 0 only if every station passes, 1 if any fails or times out, 2 usage error, 130 SIGINT.
+- `--print-config` with `--count > 1` prints `{"fleet": {...}, "config": {...}}` where `config` is the first station.
+
+## Scenarios
+
+`kirby-ocpp scenarios list` lists the built-in scenarios (`charge-session`, `fault-recovery`, `finish-session`, `offline-sync`); `kirby-ocpp scenarios show <name>` prints one as TOML. Built-ins target connector 1 unless `--connector` is given. `offline-sync` works on a stock station: `LocalAuthorizeOffline` and `AllowOfflineTxForUnknownId` default to `true` (switch them off with `ChangeConfiguration` to test the CSMS-side rejection path).
+
+```toml
+name = "my-session"
+description = "Plug in, start, meter, stop"
+
+[[steps]]
+action = "plug"
+connector = 1
+
+[[steps]]
+action = "start_tx"
+connector = 1
+id_tag = "KIRBY-TAG"        # implicitly expects status Accepted
+
+[[steps]]
+action = "meter"
+connector = 1
+wh_delta = 1000
+
+[[steps]]
+action = "expect_call"      # a CALL seen since the last matched expect_call
+call = "MeterValues"
+timeout_ms = 3000
+
+[[steps]]
+action = "stop_tx"
+connector = 1
+reason = "Local"
+expect = { status = "Accepted" }
+```
 
-Global shortcuts:
+Actions: `connect`, `disconnect`, `reconnect`, `boot`, `heartbeat`, `plug`, `unplug`, `authorize`, `start_tx`, `stop_tx`, `meter`, `status`, `fault`, `clear_fault`, `sleep`, `wait_for`, `expect_call` (`call`, optional `direction`, `match` payload subset), `send_raw` (`call`, `payload`, `validate`), `data_transfer`, `set_rule` (`rule`), `clear_rules` (optional `call`). Every step may have `name` and `expect` (`status`, `payload` subset, `error = true`). `wait_for` takes `condition = { kind = ... }` with kinds `connected`, `disconnected`, `registration`, `connector_status`, `tx_active`, `tx_idle`, `no_pending_messages`, and `timeout_ms` (default 5000). Unknown fields are rejected.
 
-- `/`: command palette.
-- `[` / `]`: previous/next connector.
-- `+`: add connector.
-- `j` / `k`: scroll logs.
-- `G`: jump logs to bottom.
-- `F`: cycle log filter.
-- `l`: full-screen plain log view.
-- `y`: copy current log buffer.
-- `?`: help.
-- `q`: quit.
+## Response rules
 
-Forms prompt for values such as `idTag`, connector id, measurands, and `DataTransfer` payloads. There is no built-in default RFID/idTag.
-On the Connector tab, `s` cycles the selected connector status and `S` opens a list of all OCPP connector statuses.
+Response rules make the station misbehave on purpose, to test how a CSMS reacts. A rule overrides how one CSMS command (any of the 19 the station handles, e.g. `Reset`, `RemoteStartTransaction`, `ChangeConfiguration`) is answered. Form: `ACTION=BEHAVIOR[*COUNT]`, action names case-insensitive.
 
-## Persistence
+| Behavior | Effect |
+| --- | --- |
+| `reject` | The action's own rejection (`Rejected`; `NotSupported` for `SendLocalList` and `UnlockConnector`). `GetConfiguration`, `GetLocalListVersion`, `ClearChargingProfile`, `GetDiagnostics` and `UpdateFirmware` have no rejection status, so they get CALLERROR `NotSupported`. |
+| `delay:MS` | The command is handled normally; only the reply is sent `MS` ms later (0 to 3600000). The station keeps working meanwhile. |
+| `error:CODE[:TEXT]` | CALLERROR with an OCPP 1.6 code (`NotImplemented`, `NotSupported`, `InternalError`, `ProtocolError`, `SecurityError`, `FormationViolation`, `PropertyConstraintViolation`, `OccurenceConstraintViolation`, `TypeConstraintViolation`, `GenericError`). |
+| `drop` | Close the WebSocket without replying; the normal reconnect lifecycle follows (disabled by `--no-reconnect`). |
+| `ignore` | Never reply, so the CSMS call timeout fires. |
 
-State is persisted by default per `chargePointId`. This includes mutable configuration, local auth lists/cache, charging profiles, connector meter values, reservations, and pending offline transactions.
+`*COUNT` applies the rule that many times and then removes it (default: unlimited). There is one rule per action; setting another replaces it. Except for `delay`, the command is **not executed** (no side effects). Rules are runtime only, never persisted. Set them with `--rule` (repeatable) or `KIRBY_OCPP_RULES`; in both, `;` separates several rules, so a rule (e.g. an `error:` text) must not contain `;`, in the TUI (Station tab, `m`), as scenario steps, or through `Command::SetResponseRule` / `ClearResponseRules` in the core API. Each application is logged (`response rule: Reset -> reject, 2 more`).
 
-```bash
-kirby-ocpp --url ws://localhost:9000/ocpp --id CP-001 --no-persist
-kirby-ocpp --url ws://localhost:9000/ocpp --id CP-001 --state-dir ./station-state
+```sh
+kirby-ocpp --url ws://localhost:9000/ocpp --rule Reset=reject --rule GetConfiguration=delay:5000 \
+  --rule ChangeConfiguration=error:InternalError*3 --rule RemoteStartTransaction=ignore*1
 ```
 
-## Scope
+In scenarios: `action = "set_rule"` with `rule = "Reset=reject*2"`, and `action = "clear_rules"` with an optional `call = "Reset"` (all rules when omitted).
 
-kirby-ocpp targets OCPP 1.6J. It supports common Charge Point calls and Central System commands for booting, authorization, transactions, metering, local auth lists, reservations, availability, reset, diagnostics, firmware, smart charging, trigger messages, and data transfer.
+## Testing against a mock
 
-Detailed coverage is tracked in [docs/OCPP_1.6J_CONFORMANCE.md](docs/OCPP_1.6J_CONFORMANCE.md).
+`crates/kirby-ocpp-testkit` is a dev-only scripted mock CSMS (plain and TLS) used by the integration tests; it is not published. Use it from tests of your own, or point `kirby-ocpp` at any real or local CSMS.
 
 ## Development
 
-```bash
-npm install
-npm run dev -- --url ws://localhost:9000/ocpp --id CP-001
-```
-
-Before publishing:
+Workspace crates: `kirby-ocpp-core` (protocol, station state machine, scenarios, WebSocket/TLS; no terminal code), `kirby-ocpp-tui` (ratatui UI), `kirby-ocpp` (binary: CLI and headless runner), `kirby-ocpp-testkit` (mock CSMS, not published).
 
 ```bash
-npm run typecheck
-npm test
-npm run smoke
-npm run pack:check
+cargo fmt --all --check
+cargo clippy --workspace --all-targets -- -D warnings
+cargo test --workspace          # includes doc tests and process-level CLI tests
 ```
 
-`npm run pack:check` builds the package, installs the generated tarball into a temporary directory, and verifies the installed CLI and bundled schemas.
-
-## Third-Party Materials
+Protocol coverage is documented in [docs/OCPP_1.6J_CONFORMANCE.md](docs/OCPP_1.6J_CONFORMANCE.md).
 
-This project is MIT licensed. Bundled OCPP 1.6J JSON schemas are sourced from the official Open Charge Alliance OCPP 1.6 download package and are included for validation/conformance. They are not owned by this project and are not covered by this project's MIT license.
+## License
 
-See [THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md).
+MIT, see [LICENSE](LICENSE). The bundled OCPP JSON schemas belong to the Open Charge Alliance; see [THIRD_PARTY_NOTICES.md](crates/kirby-ocpp/THIRD_PARTY_NOTICES.md) or run `kirby-ocpp --licenses`. Crate licences are recorded in `Cargo.lock` and the crates' metadata.

package/THIRD_PARTY_NOTICES.md

@@ -2,7 +2,7 @@
 
 ## OCPP 1.6J JSON schemas
 
-This package bundles the OCPP 1.6J JSON schemas under `dist/ocpp/schemas/json` for local protocol validation.
+`kirby-ocpp` bundles the OCPP 1.6J JSON schemas (`crates/kirby-ocpp-core/schemas`) and embeds them in the binary for local protocol validation.
 
 The schemas are sourced from the official Open Charge Alliance OCPP 1.6 download package:
 
@@ -12,4 +12,8 @@ The OCPP 1.6J specification package references Creative Commons Attribution-NoDe
 
 - https://creativecommons.org/licenses/by-nd/4.0/legalcode
 
-The bundled schemas are included for compatibility/conformance validation and are not owned by this project. The project license in `LICENSE` applies to this project's own source code, not to Open Charge Alliance materials. Open Charge Alliance does not sponsor or endorse this package.
+The bundled schemas are included, unmodified, for compatibility and conformance validation and are not owned by this project. The project license in `LICENSE` applies to this project's own source code, not to Open Charge Alliance materials. Open Charge Alliance does not sponsor or endorse this project.
+
+## Rust dependencies
+
+`kirby-ocpp` is statically linked from open-source Rust crates (tokio, rustls, ring, ratatui, crossterm, clap, serde and others), each under its own licence (MIT, Apache-2.0, ISC, BSD and similar permissive licences). Their names, versions and licences are recorded in `Cargo.lock` and each crate's own metadata; run `cargo install cargo-license && cargo license` in a source checkout, or inspect the dependency tree with `cargo tree`, for the exact list. Binary distributions must keep this notice together with the licence texts of those crates.

package/bin/kirby-ocpp.js

@@ -0,0 +1,77 @@
+#!/usr/bin/env node
+// Launcher: runs the native kirby-ocpp binary shipped by the matching platform package.
+"use strict";
+
+const { spawnSync } = require("node:child_process");
+const path = require("node:path");
+
+// Candidate packages per platform, in order of preference. The musl build is fully static,
+// so on Linux x64 it is also a valid fallback when the glibc package was not installed.
+const PLATFORMS = {
+  "linux-x64": ["@archhaze24/kirby-ocpp-linux-x64", "@archhaze24/kirby-ocpp-linux-x64-musl"],
+  "linux-arm64": ["@archhaze24/kirby-ocpp-linux-arm64"],
+  "darwin-x64": ["@archhaze24/kirby-ocpp-darwin-x64"],
+  "darwin-arm64": ["@archhaze24/kirby-ocpp-darwin-arm64"],
+  "win32-x64": ["@archhaze24/kirby-ocpp-win32-x64"],
+};
+
+// True on a musl-based Linux (Alpine etc.): glibc reports its version, musl does not.
+function isMusl() {
+  if (process.platform !== "linux") return false;
+  try {
+    const report = process.report.getReport();
+    const header = typeof report === "string" ? JSON.parse(report).header : report.header;
+    if (header && "glibcVersionRuntime" in header) return !header.glibcVersionRuntime;
+  } catch {
+    // fall through to the file check
+  }
+  try {
+    return require("node:fs").readdirSync("/lib").some((name) => name.startsWith("ld-musl-"));
+  } catch {
+    return false;
+  }
+}
+
+function binaryPath() {
+  const key = `${process.platform}-${process.arch}`;
+  const candidates = PLATFORMS[key];
+  if (!candidates) {
+    throw new Error(
+      `kirby-ocpp has no prebuilt binary for ${key}. Supported: ${Object.keys(PLATFORMS).join(", ")}. ` +
+        "Build from source instead: cargo install kirby-ocpp",
+    );
+  }
+  const ordered = key === "linux-x64" && isMusl() ? [...candidates].reverse() : candidates;
+  const exe = process.platform === "win32" ? "kirby-ocpp.exe" : "kirby-ocpp";
+  for (const pkg of ordered) {
+    try {
+      const manifest = require.resolve(`${pkg}/package.json`);
+      return path.join(path.dirname(manifest), "bin", exe);
+    } catch {
+      // not installed, try the next candidate
+    }
+  }
+  throw new Error(
+    `The platform package ${ordered[0]} is not installed (npm skipped the optional dependency). ` +
+      "Reinstall without --omit=optional, or run: cargo install kirby-ocpp",
+  );
+}
+
+let binary;
+try {
+  binary = binaryPath();
+} catch (error) {
+  console.error(`kirby-ocpp: ${error.message}`);
+  process.exit(1);
+}
+
+const result = spawnSync(binary, process.argv.slice(2), { stdio: "inherit" });
+if (result.error) {
+  console.error(`kirby-ocpp: could not run ${binary}: ${result.error.message}`);
+  process.exit(1);
+}
+if (result.signal) {
+  process.kill(process.pid, result.signal);
+} else {
+  process.exit(result.status ?? 1);
+}

package/package.json

@@ -1,62 +1,41 @@
 {
   "name": "kirby-ocpp",
-  "version": "0.1.2",
-  "description": "A terminal OCPP charge point emulator.",
-  "type": "module",
-  "author": "archhaze24",
-  "bin": {
-    "kirby-ocpp": "dist/cli.js"
-  },
-  "files": [
-    "dist",
-    "docs",
-    "README.md",
-    "THIRD_PARTY_NOTICES.md",
-    "LICENSE"
-  ],
-  "scripts": {
-    "build": "tsc -p tsconfig.json && node scripts/copy-schemas.mjs",
-    "dev": "tsx src/cli.ts",
-    "pack:check": "node scripts/check-packed-install.mjs",
-    "prepack": "npm run build",
-    "smoke": "npm run build && node scripts/smoke-ocpp.mjs",
-    "start": "node dist/cli.js",
-    "test": "npm run build && node --test tests/*.test.mjs",
-    "typecheck": "tsc -p tsconfig.json --noEmit"
-  },
+  "version": "0.3.0",
+  "description": "Terminal OCPP 1.6J charge point emulator for testing a CSMS (TUI, headless and scenarios)",
   "keywords": [
     "ocpp",
     "ocpp16",
+    "ev",
     "charge-point",
     "emulator",
-    "tui",
-    "cli"
+    "csms",
+    "tui"
   ],
   "license": "MIT",
+  "author": "archhaze24",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/archhaze24/kirby-ocpp.git"
   },
-  "bugs": {
-    "url": "https://github.com/archhaze24/kirby-ocpp/issues"
-  },
   "homepage": "https://github.com/archhaze24/kirby-ocpp#readme",
-  "engines": {
-    "node": ">=20"
+  "bin": {
+    "kirby-ocpp": "bin/kirby-ocpp.js"
   },
-  "dependencies": {
-    "blessed": "^0.1.81",
-    "commander": "^12.1.0",
-    "jsonschema": "^1.5.0",
-    "nanoid": "^5.0.7",
-    "ws": "^8.18.0",
-    "zod": "^3.23.8"
+  "files": [
+    "bin",
+    "README.md",
+    "LICENSE",
+    "THIRD_PARTY_NOTICES.md"
+  ],
+  "engines": {
+    "node": ">=18"
   },
-  "devDependencies": {
-    "@types/blessed": "^0.1.25",
-    "@types/node": "^22.10.2",
-    "@types/ws": "^8.5.13",
-    "tsx": "^4.19.2",
-    "typescript": "^5.7.2"
+  "optionalDependencies": {
+    "@archhaze24/kirby-ocpp-linux-x64": "0.3.0",
+    "@archhaze24/kirby-ocpp-linux-x64-musl": "0.3.0",
+    "@archhaze24/kirby-ocpp-linux-arm64": "0.3.0",
+    "@archhaze24/kirby-ocpp-darwin-x64": "0.3.0",
+    "@archhaze24/kirby-ocpp-darwin-arm64": "0.3.0",
+    "@archhaze24/kirby-ocpp-win32-x64": "0.3.0"
   }
 }

package/dist/cli.d.ts

@@ -1,2 +0,0 @@
-#!/usr/bin/env node
-export {};

package/dist/cli.js

@@ -1,72 +0,0 @@
-#!/usr/bin/env node
-import { Command } from "commander";
-import { createRequire } from "node:module";
-import { ZodError } from "zod";
-import { parseConfig } from "./config.js";
-import { Station } from "./station.js";
-import { Tui } from "./tui.js";
-const program = new Command();
-const require = createRequire(import.meta.url);
-const packageJson = require("../package.json");
-program
-    .name("kirby-ocpp")
-    .description("Terminal OCPP charge point emulator")
-    .version(packageJson.version ?? "0.1.0")
-    .option("-u, --url <url>", "Central System WebSocket URL, e.g. ws://localhost:9000/ocpp")
-    .option("-i, --id <id>", "charge point id", process.env.OCPP_CHARGE_POINT_ID ?? "CP-001")
-    .option("--vendor <vendor>", "charge point vendor", process.env.OCPP_VENDOR ?? "archhaze24")
-    .option("--model <model>", "charge point model", process.env.OCPP_MODEL ?? "KIRBY")
-    .option("-c, --connector <id>", "initial connector id", "1")
-    .option("--connectors <count>", "number of station connectors", "1")
-    .option("--heartbeat <seconds>", "fallback heartbeat interval in seconds", "30")
-    .option("--no-persist", "do not save station state such as local auth list and charging profiles")
-    .option("--state-dir <path>", "directory for persisted station state")
-    .option("--ws-subprotocol <protocol>", "WebSocket subprotocol to request", "ocpp1.6")
-    .option("--ws-ping <seconds>", "WebSocket ping interval in seconds, 0 disables pings", "30")
-    .option("--no-reconnect", "do not automatically reconnect after an unexpected WebSocket disconnect")
-    .option("--reconnect-initial-ms <milliseconds>", "initial automatic reconnect delay in milliseconds", "1000")
-    .option("--reconnect-max-ms <milliseconds>", "maximum automatic reconnect delay in milliseconds", "30000")
-    .option("--reconnect-max-attempts <attempts>", "maximum automatic reconnect attempts, 0 means unlimited", "0")
-    .option("--call-timeout-ms <milliseconds>", "OCPP CALL response timeout in milliseconds", "30000")
-    .option("--tls-ca <path>", "CA certificate bundle for wss:// connections")
-    .option("--tls-cert <path>", "client certificate for wss:// mutual TLS")
-    .option("--tls-key <path>", "client private key for wss:// mutual TLS")
-    .option("--tls-server-name <name>", "TLS server name override for wss:// connections")
-    .option("--tls-skip-verify", "disable TLS certificate verification for local/self-signed wss:// testing")
-    .parse();
-const options = program.opts();
-try {
-    const config = parseConfig({
-        centralSystemUrl: options.url,
-        chargePointId: options.id,
-        vendor: options.vendor,
-        model: options.model,
-        connectorId: options.connector,
-        connectorCount: Math.max(Number.parseInt(options.connectors, 10), Number.parseInt(options.connector, 10)),
-        heartbeatIntervalSeconds: options.heartbeat,
-        persistState: options.persist,
-        stateDirectory: options.stateDir,
-        webSocketSubprotocol: options.wsSubprotocol,
-        webSocketPingIntervalSeconds: options.wsPing,
-        webSocketReconnectEnabled: options.reconnect,
-        webSocketReconnectInitialDelayMs: options.reconnectInitialMs,
-        webSocketReconnectMaxDelayMs: options.reconnectMaxMs,
-        webSocketReconnectMaxAttempts: options.reconnectMaxAttempts,
-        callTimeoutMs: options.callTimeoutMs,
-        tlsRejectUnauthorized: !options.tlsSkipVerify,
-        tlsCaFile: options.tlsCa,
-        tlsCertFile: options.tlsCert,
-        tlsKeyFile: options.tlsKey,
-        tlsServerName: options.tlsServerName
-    });
-    const station = new Station(config);
-    const tui = new Tui(station);
-    tui.start();
-}
-catch (error) {
-    if (error instanceof ZodError) {
-        console.error(error.errors.map((issue) => `${issue.path.join(".")}: ${issue.message}`).join("\n"));
-        process.exit(1);
-    }
-    throw error;
-}

package/dist/config.d.ts

@@ -1,2 +0,0 @@
-import type { StationConfig } from "./ocpp/types.js";
-export declare function parseConfig(input: Partial<Record<keyof StationConfig, unknown>>): StationConfig;