Command 1.0.0: JSON Command Interpreter (#9)

.github/workflows/tests.yml

@@ -3,8 +3,6 @@ name: Tests
 on:
   push:
   pull_request:
-    branches:
-      - main
 
 jobs:
   host-tests:
@@ -17,13 +15,73 @@ jobs:
             echo 'Core Command umbrella must not acquire Event integration.'
             exit 1
           fi
+      - name: Verify core Command remains JSON-adapter-free
+        run: |
+          if grep -R -nE '#[[:space:]]*include[[:space:]]*[<\"](ArduinoJson|ESPressio_JsonCommandInterpreter)' src/ESPressio_Command.hpp src/ESPressio_Commands.hpp; then
+            echo 'Core Command umbrella must not require the optional JSON adapter.'
+            exit 1
+          fi
       - name: Configure
         run: cmake -S tests -B build
       - name: Build
         run: cmake --build build --parallel
       - name: Test
         run: ctest --test-dir build --output-on-failure
 
+  esp32-json-integration:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          path: project/ESPressio-Command
+      - uses: actions/checkout@v4
+        with:
+          repository: Flowduino/ESPressio-Observable
+          ref: 3.0.1
+          path: project/dependencies/ESPressio-Observable
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.x'
+      - name: Install PlatformIO
+        run: pip install platformio
+      - name: Create JSON interpreter compile project
+        shell: bash
+        run: |
+          mkdir -p project/compile-json/src
+          cat > project/compile-json/platformio.ini <<'EOF'
+          [env:esp32]
+          platform = espressif32
+          board = esp32dev
+          framework = arduino
+          build_flags = -std=gnu++17 -frtti
+          build_unflags = -std=gnu++11 -fno-rtti
+          lib_ldf_mode = deep+
+          lib_deps =
+              bblanchon/ArduinoJson@^7.4.3
+              ../dependencies/ESPressio-Observable
+              ../ESPressio-Command
+          EOF
+          cat > project/compile-json/src/main.cpp <<'EOF'
+          #include <Arduino.h>
+          #include <ESPressio_Command.hpp>
+          #include <ESPressio_TextCommandInterpreter.hpp>
+          #include <ESPressio_JsonCommandInterpreter.hpp>
+          ESPressio::Command::CommandRegistry registry;
+          ESPressio::Command::JsonCommandInterpreter json(registry);
+          void setup() {
+              auto& command = registry.Command("gpio").Command("write");
+              command.Parameter<int>("pin");
+              command.Parameter<bool>("state");
+              command.OnExecute([](const ESPressio::Command::CommandContext&) {
+                  return ESPressio::Command::CommandResult::Ok();
+              });
+              (void)json.Invoke("{\"path\":[\"gpio\",\"write\"],\"parameters\":{\"pin\":2,\"state\":true}}");
+          }
+          void loop() {}
+          EOF
+      - name: Compile JSON Command integration
+        run: pio run -d project/compile-json
+
   esp32-event-integration:
     runs-on: ubuntu-latest
     steps:

CHANGELOG.md

@@ -1,3 +1,49 @@
+## 1.0.0 — 2026-08-21
+
+### Added
+
+- Added `CommandValue`, a representation-neutral scalar value type supporting strings, booleans, signed/unsigned integers and floating-point values.
+- Added `CommandContext::Value()` for access to the native structured `CommandValue`; `Raw()` remains available as a normalized textual view.
+- Added `TextCommandInterpreter` as an explicit facade for the existing human-oriented text interpretation path.
+- Added optional `JsonCommandInterpreter` support using ArduinoJson 7.x without making ArduinoJson a core Command dependency.
+- Added JSON command input using either a canonical `path` array or a convenience `command` string, with named and positional scalar parameters.
+- Added structured JSON `CommandResult` output through `SerializeResult()` / `InvokeToJson()`.
+- Added JSON command discovery through `Describe()`, including descriptions, executability, aliases, visibility/deprecation metadata and parameter type/default/range/choice metadata.
+- Added `CommandRegistry::Resolve()` / `Root()` and public metadata accessors required by representation-independent discovery tools.
+- Added comprehensive host and ESP32 validation for the JSON interpreter and typed invocation model.
+
+### Changed
+
+- `CommandInvocation::positional` now stores `CommandValue` rather than `std::string`.
+- `CommandInvocation::named` now stores `CommandValue` rather than `std::string`.
+- Structured invocation is now genuinely representation-neutral: typed callers no longer need to flatten JSON/native scalar values into strings before invoking a Command.
+- Registry parameter validation now consumes typed `CommandValue` instances directly while retaining existing text conversion semantics.
+- The normal `ESPressio_Commands.hpp` umbrella exposes `TextCommandInterpreter` but deliberately does not include `JsonCommandInterpreter`, keeping ArduinoJson opt-in.
+- CI now validates stacked pull requests, enforces the JSON adapter boundary and compiles the optional JSON integration for ESP32.
+
+### Breaking changes
+
+- Code depending on the exact public types `std::vector<std::string>` and `std::map<std::string, std::string>` for `CommandInvocation::positional` / `named` must update to the corresponding `CommandValue` containers.
+- Common assignments such as `invocation.named["pin"] = "2"` and initializer lists of string values remain supported through implicit `CommandValue` construction.
+- New structured callers should prefer native values such as `invocation.named["pin"] = 2` and `invocation.named["enabled"] = true`.
+
+### JSON constraints
+
+- This release intentionally supports scalar Command parameters only, matching the existing Command parameter model.
+- JSON object, array and null parameter values are rejected rather than silently stringified.
+- The JSON interpreter is optional and requires ArduinoJson 7.x only when `ESPressio_JsonCommandInterpreter.hpp` is included.
+
+### Compatibility
+
+- Existing textual Command syntax, `TextCommandParser`, `CommandLine`, help/completion, parameter validation, middleware, callbacks, registry observation and Event integration remain supported.
+- `CommandContext::Raw()` remains source-compatible as the normalized string representation of a resolved parameter.
+- ESPressio Observable remains the only required ESPressio dependency.
+- The optional Command -> Event integration remains compatible with ESPressio Event 6.x.
+
+### Tracking
+
+- Implements #9.
+
 ## 0.4.0 — 2026-08-21
 
 ### Added

ESPRESSIO_DEPENDENCY_CHART.md

@@ -1,32 +1,34 @@
-# ESPressio Dependency Chart — Command 0.4.0
+# ESPressio Dependency Chart — Command 1.0.0
 
 ![ESPressio Library Dependency Chart](ESPRESSIO_DEPENDENCY_CHART.svg)
 
-## Command 0.4.0
+## Command 1.0.0
 
 ```text
-Command 0.4.0
+Command 1.0.0
     -> Observable >= 3.0.1 < 4.0.0
     - - -> Event >= 6.0.0 < 7.0.0
             Command Event types / CommandRegistryEventBridge only
 ```
 
 The Event relationship is opt-in. Normal Command use remains Event-free.
 
-## Final coordinated ecosystem
+The optional `JsonCommandInterpreter` uses **ArduinoJson 7.x**, but ArduinoJson is an external adapter dependency rather than an ESPressio library dependency and is therefore intentionally not represented as an edge in this ESPressio-only chart. Applications that do not include `ESPressio_JsonCommandInterpreter.hpp` do not require ArduinoJson.
+
+## Current ecosystem generation
 
 ```text
 Observable 3.0.1
 Serializable 0.10.2
 Units 0.2.3
 Timing 2.2.4
 Threads 3.1.4
-Command 0.4.0
+Command 1.0.0
 Security 0.3.0
 Event 6.0.0
 Sockets 0.6.0
 ESP-Now 0.6.0
 Serial 0.6.0
 ```
 
-Command owns its Command-specific Event bridge. Event 6.0.0 does not depend back on Command, so no reciprocal edge remains.
+Command owns its Command-specific Event bridge. Event 6.0.0 does not depend back on Command, so no reciprocal edge exists.