refactor(onboard): centralize machine state metadata - #4362
Merged
Conversation
Signed-off-by: Carlos Villela <cvillela@nvidia.com>
Signed-off-by: Carlos Villela <cvillela@nvidia.com>
|
Auto-sync is disabled for draft pull requests in this repository. Workflows must be run manually. Contributors can view more details about this message here. |
Contributor
|
No actionable comments were generated in the recent review. 🎉 ℹ️ Recent review info⚙️ Run configurationConfiguration used: Path: .coderabbit.yaml Review profile: CHILL Plan: Enterprise Run ID: 📒 Files selected for processing (2)
💤 Files with no reviewable changes (2)
📝 WalkthroughWalkthroughThis PR centralizes onboard machine state vocabulary by introducing a canonical state-definition module that exports a readonly tuple of state objects with terminal flags, optional step names, and progress metadata. It derives ordered state ID arrays and TypeScript union types from these definitions, then refactors the existing types.ts module to import these canonical exports instead of maintaining duplicate declarations. A comprehensive test suite validates state ordering consistency, terminal/non-terminal derivation, step name uniqueness, progress metadata constraints, and state lookup behavior. ChangesOnboard FSM State Vocabulary
Estimated code review effort🎯 3 (Moderate) | ⏱️ ~20 minutes Suggested labels
Suggested reviewers
Poem
🚥 Pre-merge checks | ✅ 4 | ❌ 1❌ Failed checks (1 warning)
✅ Passed checks (4 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches📝 Generate docstrings
🧪 Generate unit tests (beta)
Comment |
Contributor
E2E Advisor RecommendationRequired E2E: Dispatch hint: Full advisor summaryE2E Recommendation AdvisorBase: Required E2E
Optional E2E
New E2E recommendations
Dispatch hint
|
Contributor
E2E Scenario Advisor RecommendationRequired scenario E2E: Dispatch required scenario E2E:
Full scenario advisor summaryE2E Scenario AdvisorBase: Required scenario E2E
Optional scenario E2E
Relevant changed files
|
Contributor
PR Review AdvisorFindings: 0 needs attention, 2 worth checking, 0 nice ideas Review findings🛠️ Needs attention
🔎 Worth checking
🌱 Nice ideas
Since last review detailsCurrent findings:
This is an automated advisory review. A human maintainer must make the final merge decision. |
wscurran
added
the
refactor
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
Contributor
There was a problem hiding this comment.
Actionable comments posted: 1
🧹 Nitpick comments (2)
src/lib/onboard/machine/definition.ts (1)
45-55: ⚡ Quick winConsider whether shared
progress.number: 7foragent_setupandopenclawis intentional (lines 48, 54)
src/lib/onboard/machine/definition.test.tsvalidates only thatprogress.numberis within1..total(andstepNames are unique); it does not enforce uniqueness/ordering ofprogress.number.- Since
sandboxbranches to bothopenclawandagent_setup, using the sameprogress.number/title may be deliberate. Ifprogress.numberis intended to represent distinct sequential UI steps, updateopenclaw/agent_setupto differentprogress.numberand/or titles.🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@src/lib/onboard/machine/definition.ts` around lines 45 - 55, The entries for state "agent_setup" and "openclaw" both use progress.number: 7 and the same title, which may be unintended; review progress semantics and if these represent sequential UI steps, change one of the progress.number values (and optionally its progress.title) so "agent_setup" and "openclaw" have distinct progress numbers (e.g., 7 and 8) and update any dependent labels; ensure the machine node definitions for state "agent_setup" and state "openclaw" in definition.ts (and any expectations in the test file definition.test.ts) remain consistent after the change.src/lib/onboard/machine/definition.test.ts (1)
79-84: ⚡ Quick winExpand test coverage for
getOnboardMachineStateDefinitionto include error and edge cases.The current test only validates the happy path (known state with stepName). Per the layer description, the function throws on unknown identifiers, but this error behavior is not tested. Consider adding test cases for:
- Unknown state ID (should throw)
- Terminal state lookup (e.g., "complete")
- Non-terminal state without stepName (e.g., "init")
🧪 Proposed additional test cases
it("looks up definitions by state", () => { expect(getOnboardMachineStateDefinition("gateway")).toMatchObject({ state: "gateway", stepName: "gateway", }); + + expect(getOnboardMachineStateDefinition("complete")).toMatchObject({ + state: "complete", + terminal: true, + }); + + expect(getOnboardMachineStateDefinition("init")).toMatchObject({ + state: "init", + terminal: false, + }); + }); + + it("throws on unknown state ID", () => { + expect(() => getOnboardMachineStateDefinition("unknown" as any)).toThrow(); }); });🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@src/lib/onboard/machine/definition.test.ts` around lines 79 - 84, Add tests to cover error and edge cases for getOnboardMachineStateDefinition: add a test asserting that calling getOnboardMachineStateDefinition with an unknown id throws (use toThrow), add a test that looking up a terminal state (e.g., "complete") returns the correct object shape (state: "complete") and does not require a stepName, and add a test for a non-terminal state that intentionally lacks stepName (e.g., "init") asserting it returns the state and either stepName is undefined or absent. Use the existing test style (expect(...).toMatchObject / expect(() => ...).toThrow) and reference getOnboardMachineStateDefinition in each case.
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@src/lib/onboard/machine/definition.ts`:
- Around line 72-74: Replace the hardcoded ONBOARD_MACHINE_TERMINAL_STATE_IDS
with a derived constant that filters ONBOARD_MACHINE_STATE_DEFINITIONS for
entries where def.isTerminal is true and maps to their id, and then move the
OnboardTerminalMachineStateId type so it is declared after that derived constant
(i.e., let OnboardTerminalMachineStateId = (typeof
ONBOARD_MACHINE_TERMINAL_STATE_IDS)[number]) to keep types consistent and
prevent future drift between definitions and terminal IDs.
---
Nitpick comments:
In `@src/lib/onboard/machine/definition.test.ts`:
- Around line 79-84: Add tests to cover error and edge cases for
getOnboardMachineStateDefinition: add a test asserting that calling
getOnboardMachineStateDefinition with an unknown id throws (use toThrow), add a
test that looking up a terminal state (e.g., "complete") returns the correct
object shape (state: "complete") and does not require a stepName, and add a test
for a non-terminal state that intentionally lacks stepName (e.g., "init")
asserting it returns the state and either stepName is undefined or absent. Use
the existing test style (expect(...).toMatchObject / expect(() => ...).toThrow)
and reference getOnboardMachineStateDefinition in each case.
In `@src/lib/onboard/machine/definition.ts`:
- Around line 45-55: The entries for state "agent_setup" and "openclaw" both use
progress.number: 7 and the same title, which may be unintended; review progress
semantics and if these represent sequential UI steps, change one of the
progress.number values (and optionally its progress.title) so "agent_setup" and
"openclaw" have distinct progress numbers (e.g., 7 and 8) and update any
dependent labels; ensure the machine node definitions for state "agent_setup"
and state "openclaw" in definition.ts (and any expectations in the test file
definition.test.ts) remain consistent after the change.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Path: .coderabbit.yaml
Review profile: CHILL
Plan: Enterprise
Run ID: b211652d-f217-46f6-aa80-2c68225a3834
📒 Files selected for processing (3)
src/lib/onboard/machine/definition.test.tssrc/lib/onboard/machine/definition.tssrc/lib/onboard/machine/types.ts
Collaborator
|
lgtm. content audit verified:
delivers migration stage 1 from #4361's README: "state metadata is defined once and derived." |
cjagwani
approved these changes
May 28, 2026
cjagwani
left a comment
cjagwani
left a comment
Collaborator
There was a problem hiding this comment.
approving per audit above — definition matches transitions 1:1, types.ts re-exports preserve consumer API, tests pass locally + CI green.
cv
marked this pull request as ready for review
May 29, 2026 17:21
Signed-off-by: Carlos Villela <cvillela@nvidia.com>
This was referenced May 29, 2026
wscurran
added
area: onboarding
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
3 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Introduce a canonical metadata table for the coarse onboarding machine states. Existing state/type exports remain stable while state IDs, terminal IDs, and non-terminal IDs now flow from the shared machine definition.
Changes
src/lib/onboard/machine/definition.tsas the ordered catalog of onboard FSM states and metadata.src/lib/onboard/machine/types.tsto re-export state catalogs from the definition.src/lib/onboard/machine/definition.test.tsto guard ordering, terminal/non-terminal catalogs, and step metadata uniqueness.Type of Change
Verification
npx prek run --all-filespassesnpm testpassesnpm run docsbuilds without warnings (doc changes only)Signed-off-by: Carlos Villela cvillela@nvidia.com
Summary by CodeRabbit
Tests
Refactor