feat(state_machine): generate the example's HFSM from its model at build time

[finger563]

The example shipped ~2400 lines of generated C++ and no model. The machine couldn't be regenerated, edited, or checked against anything — and it had drifted: regenerating from the model with the current generator produces roughly two thousand different lines (after clang-format), three years of generator fixes the example never received.

So the model is the source now, and the C++ is a build product like an object file.

• main/Complex.json is checked in; the three generated files are not.
• CMake runs the generator at configure time and lists the model in CMAKE_CONFIGURE_DEPENDS, so editing the model regenerates on the next build, not the next clean.
• It generates with --no-support, so only the machine is produced. The shared runtime — state_base.hpp, the history states, magic_enum.hpp — comes from this component. A second copy beside the generated machine would land on the include path in front of espp's, and espp's are the ones the rest of the codebase is built against.

What it needs

node >= 18, and nothing else — npx fetches the generator on demand. Two escape hatches:

# work against a local generator checkout; also how to build offline
idf.py -DHFSM_GEN_COMMAND="node;/path/to/webgme-hfsm/bin/hfsm-gen.js" build

The esp-idf CI image has no node (IDF's own tools.json doesn't ship it), so that matrix entry installs it first. Worth being explicit: this is a new build-time dependency for this one example, which was the deliberate trade for not versioning generated code.

Editing the machine

The model opens in the HFSM Playground — browser-based, no install, no server — or straight to this example's machine. Save back over main/Complex.json and rebuild.

Verified

Actually built, not just configured, on esp-idf v6.1 / esp32:

• clean set-target + build from an empty tree, with freshly generated code three years newer than what was committed
• the fresh code compiles against espp's component headers — checked separately with only the three model files on the include path, so the generator's own headers couldn't satisfy it by accident
• edited Complex.json, rebuilt, confirmed the change reached the compiled source without a clean

Blocking on two things

1. --no-support is not released yet — it's Add --no-support, for projects that vendor the runtime already finger563/webgme-hfsm#241. The pin here is that PR's commit.
2. Once feat(motorgo): Add APIs for more customized use (single motor, delayed motor init, etc.) #241 and the v1.8.0 release land, HFSM_GEN_SPEC should become webgme-hfsm@^1.8.0. It's a git ref today because npx webgme-hfsm@1.7.0 doesn't work at all — installing that package and running the CLI fails outright, which is the packaging bug fixed in Make the WebGME server optional so the CLI can be installed finger563/webgme-hfsm#238 and not yet released.

A note on the vendored runtime

I checked whether this component's state_base.hpp / history headers had gone stale against the generator's, since the generated code had. They have not. All 19 shared method bodies are byte-identical once comments and whitespace are normalised; the differences are espp's own improvements (declaration/definition split into src/state_base.cpp, explicit constructors, doxygen). And magic_enum runs the other way: espp vendors 0.9.5, the generator ships 0.8.0. Nothing to update here — if anything the generator is the one behind.

[finger563]

Updated now that v1.8.0 is published — both blockers are gone.

HFSM_GEN_SPEC is webgme-hfsm@^1.8.0 from npm instead of a git commit. It was a git ref only because npx webgme-hfsm@1.7.0 could not run at all (the packaging bug) and --no-support did not exist; 1.8.0 is the first release with either.

Verified against the published package rather than assuming: a clean set-target + build on esp-idf v6.1 / esp32, and the npm CLI's output is byte-identical to a local checkout's.

^1.8.0 rather than an exact pin — reproducible enough for a build that regenerates from a checked-in model, and it picks up generator fixes without a commit here. Say the word if you'd rather it were exact.

[Copilot]

Warning

Copilot couldn't run its full agentic review because it didn't start before the timeout. Make sure your repository has a runner available, or add a copilot-code-review.yml file specifying one with the runs-on attribute. See the docs for more details.

Pull request overview

Moves the Complex HFSM example to treat the JSON model as the source of truth and generate the C++ state machine during the build, removing committed generated artifacts that had drifted from the generator output.

Changes:

• Add Complex.json model to source control and stop committing generated C++/metadata for the example.
• Generate the HFSM at CMake configure time via npx (with --no-support) and compile the generated .cpp from the build directory.
• Update documentation and CI to reflect/install the new Node-based build-time dependency.

Reviewed changes

Copilot reviewed 9 out of 9 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
components/state_machine/example/main/Complex_metadata.json	Removes committed generator metadata file.
components/state_machine/example/main/Complex_generated_states.hpp	Removes committed generated header (now build output).
components/state_machine/example/main/Complex_generated_states.cpp	Removes committed generated source (now build output).
components/state_machine/example/main/Complex_event_data.hpp	Removes committed generated event data header (now build output).
components/state_machine/example/main/Complex.json	Adds the HFSM model as the checked-in source of truth.
components/state_machine/example/main/CMakeLists.txt	Adds configure-time generation of the HFSM C++ via npx and compiles generated output.
components/state_machine/example/README.md	Documents generation workflow, Node requirement, and offline/local-generator option.
components/state_machine/README.md	Adds general guidance on generating state machines with webgme-hfsm / Playground.
.github/workflows/build.yml	Installs Node/NPM for this example build in CI and runs idf.py build.

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[github-actions]

✅Static analysis result - no issues found! ✅

[Copilot]

🟡 Changes recommended

The configured npm version is unavailable, and obsolete generated files can survive incremental regeneration.

Once you've addressed the issues Copilot identified, you can request another Copilot review.

Review details

• Files reviewed: 9/9 changed files
• Comments generated: 2
• Review effort level: Balanced

[finger563]

Done — espp_generate_hfsm() now lives in the component's project_include.cmake, which ESP-IDF includes before any component's CMakeLists, so any component can call it. The example went from ~50 lines of CMake to four:

if(NOT CMAKE_BUILD_EARLY_EXPANSION)
  espp_generate_hfsm(
    MODEL "${CMAKE_CURRENT_LIST_DIR}/Complex.json"
    OUTPUT_DIR "${CMAKE_CURRENT_BINARY_DIR}/hfsm"
    SOURCES_VAR hfsm_srcs
    INCLUDE_DIR_VAR hfsm_inc)
endif()

idf_component_register(SRCS "hfsm_example.cpp" ${hfsm_srcs}
                       INCLUDE_DIRS "." ${hfsm_inc})

It also finds the generated file names rather than making the caller name them — they come from the machine's name in the model, so the old hardcoded Complex_generated_states.cpp meant knowing what your own model was called and keeping that in step by hand. WITH_SUPPORT and NAMESPACE are there for callers who need them.

One wart worth knowing about, since it isn't obvious and I hit it: the call needs the if(NOT CMAKE_BUILD_EARLY_EXPANSION) guard. ESP-IDF's early requirements pass includes component CMakeLists without project_include.cmake, so without the guard the build fails with Unknown CMake command "espp_generate_hfsm". That pass doesn't read SRCS either, so the empty variables are exactly what it expects. It's documented at the call site and in the component README so the next person doesn't have to rediscover it.

The cache variables are ESPP_-prefixed now that they're the component's interface rather than one example's local detail: ESPP_HFSM_GEN_SPEC, ESPP_HFSM_GEN_COMMAND.

Verified on esp-idf v6.1 / esp32 — clean build, a model edit reaching the compiled source without a clean, the documented ESPP_HFSM_GEN_COMMAND override actually working against a local checkout, and both error paths (missing model, misspelled argument) naming the call that was wrong. Your stale-artifact cleanup and the --yes npx behaviour are carried into the function.

[Copilot]

Warning

Copilot couldn't run its full agentic review because it didn't start before the timeout. Make sure your repository has a runner available, or add a copilot-code-review.yml file specifying one with the runs-on attribute. See the docs for more details.

Pull request overview

Copilot reviewed 10 out of 10 changed files in this pull request and generated 5 comments.

[finger563]

@copilot Fix the code for all comments in this review thread.

When a review comment includes a suggested change, apply the suggestion exactly.

Do not make changes beyond what is described in the linked review thread.

[Copilot]

@copilot Fix the code for all comments in this review thread.

When a review comment includes a suggested change, apply the sug...

Addressed the review thread in commit 9aa95ec: OUTPUT_DIR is now required to resolve inside CMAKE_BINARY_DIR before recursive deletion, generated sources remain sorted, and CI installs Node 20 via an explicit signed NodeSource apt repository setup instead of piping a remote script to bash. The implementation and README already use the released webgme-hfsm@^1.8.0 package.

[finger563]

@copilot your latest changes broke the state machine ci build. Fix them.

[Copilot]

🟡 Changes recommended

The CI command has broken nested shell quoting, and the documented consumer setup omits a required component dependency.

Once you've addressed the issues Copilot identified, you can request another Copilot review.

Review details

Suppressed comments (2)

components/state_machine/project_include.cmake:37

• ^1.8.0 is not a reproducible pin: npx may select any later 1.x generator, changing the generated C++ (or breaking the build) without a repository change. Since generated files are no longer checked in or locked, pin the exact generator version and update it explicitly.

# Pinned to a minor range: reproducible enough for a build that
# regenerates from a checked-in model, and picks up generator fixes
# without a commit here. 1.8.0 is the first release the CLI can be
# installed from at all, and the first with --no-support.
set(ESPP_HFSM_GEN_SPEC "webgme-hfsm@^1.8.0"

components/state_machine/README.md:26

• The caret range can resolve to later 1.x releases, so the statement that this makes generation reproducible is incorrect. Use the same exact generator version as CMake (for example, webgme-hfsm@1.8.0) and update the adjacent explanation accordingly.

npx -y -p webgme-hfsm@^1.8.0 hfsm-gen my_machine.json -o generated

(-y skips npx's install prompt for non-interactive/CI use; the @^1.8.0
pin matches the example's CMake so generation is reproducible.)

- **Files reviewed:** 10/10 changed files
- **Comments generated:** 3
- **Review effort level:** Balanced
</details>

[Copilot]

@copilot your latest changes broke the state machine ci build. Fix them.

Fixed in 910adeb. The matrix command now avoids inner single quotes, so esp-idf-ci-action can embed it in its single-quoted shell command.