Hacktoberfest 2026: những issue maintainer đã đánh dấu cho tháng Mười, đang mở và phù hợp người mới. Xem issue Hacktoberfest

Use XState machines for designing and explaining complex state

Đang mở
  • Có gì không ổn?
#14 0 bình luận 0 reaction 0 người được giao Xem trên GitHub

Maintainer thường phản hồi trong vòng 1 ngày

Chưa có ai nhận issue này.

Đánh giá

Độ khó
5/5
Thời gian dự kiến
Hơn một tuần
Mức phù hợp với người mới
35/100
Loại issue
Tính năng
Độ rõ ràng
Khá rõ ràng
Mức độ hoạt động
Sôi nổi
Công nghệ
node.js, typescript
Lĩnh vực
developer-experience

Hướng nghiên cứu

Start by reading the architect, interrogate, how, and teach entry points and the repository’s existing reference files. Then resolve the listed questions about Stately login, privacy, sketch format, and tooling before drafting state-machines.md and updating the relevant phases. Done means the guidance and edits cover the agreed workflow and its fallback; the issue does not name tests to run.

Do mô hình lập chỉ mục viết ra từ nội dung của issue.

Mô tả

enhancement grilling

Problem

When agents design or explain parts of a system, everything comes back as prose. Lifecycle and protocol state (auth flows, sync, retry/cancel/timeout, wizards, connection handling) is hard to review that way. Impossible states hide in boolean flags, and nobody can check that the code still matches the agreed design.

Idea

Use XState machines as the notation for complex state. An agent writes the machine as code, the human reviews it as a diagram, and the same machine yields a test plan and a check for drift. Use the Stately CLI (statelyai) for the tooling.

Draft placement:

Where What
New state-machines.md reference When to reach for XState: lifecycle or protocol state, async flows with cancel/retry/timeout, or several booleans that can combine into impossible states. When not to: simple toggles and plain data transforms.
architect Phase A statelyai scan --json to find existing machines while grounding.
architect Phase B For state-heavy work, the sketch includes a machine next to the types.
architect Phase C At a checkpoint, statelyai open gives the human an editable diagram.
architect Phase D statelyai diff checks the implementation against the agreed machine. @xstate/graph paths become the test plan for tdd.
interrogate statelyai diff against the base when a diff touches a machine.
how / teach Offer open when a subsystem already has a machine.

Default to using the machine as a design document: the sketch lives outside the project's source, and the project gains no dependency. Adding xstate to the app is a separate architect candidate. It's labelled as adding a dependency and goes ahead only on approval, or when scan shows the project already uses xstate.

Tldraw is out of scope for now. It would need its own bridge into Claude Code, and the Stately CLI already covers the state-machine case.

Findings (tested 2026-10-22)

Probes ran in throwaway folders with no package.json or node_modules.

  • The CLI needs no xstate in the target project. It reads the source as text and never imports xstate.
    • scan --json found the machines with no config and no login.
    • diff a.ts b.ts --fail-on-changes works on two local files. It reported Added edges: root.closed->SLAM->root.open, exiting 1 when the machines differ and 0 when they match.
  • [email protected] (latest) doesn't install. It depends on @statelyai/[email protected], which isn't on npm (404). 0.14.3 works. Pin an exact version.
  • A JSON machine compares equal to the same machine in TS. diff door.machine.ts door.json reported no changes. A plain .json sketch would avoid the problem of an import 'xstate' line breaking the project's typecheck. scan only listed the .ts file, though.
  • diff can't read Mermaid. It fails on .mmd with a JSON parse error, even though the CLI's file pattern includes .mmd/.mermaid.
  • open needs a Stately account. The CLI starts a local server, but the editor is an iframe from editor.stately.ai. Its access endpoint (/api/editor-sync/access) returns 401 AUTH_INVALID: A valid Stately credential is required for editor sync without a credential. Write-back to the source file is not verified.
  • Path generation works outside the project. @xstate/[email protected] with [email protected] and tsx, installed in a scratch folder, produced shortest paths as event sequences. Example: FETCH → REJECT → RETRY → RESOLVE.
  • Sketches with stubbed actions give misleading paths. In a retry machine whose bumpRetries action was named but not implemented, the retry count never changed, and gaveUp was never reached. With bumpRetries implemented as an assign, it was reached via FETCH, REJECT, RETRY, REJECT, RETRY, REJECT, RETRY, along with 13 paths in all. Implementing the action also showed that CANCEL doesn't reset the retry count. That's the kind of design gap this approach should surface.

Open questions

  • Stately account. Is a login acceptable for the visual part, and does the free tier cover editor sync? Without one, gstack gets scan, diff and test paths, but no diagram editing.
  • Privacy. With open, the machine is shown in a page hosted by Stately. Does the machine content leave the machine (i.e. reach Stately's servers)? Is that OK for private repos?
  • Write-back. Once logged in, do edits in open land cleanly in a .ts sketch? What about a .json one? And what does --source-update preserve|rewrite do to formatting?
  • Fallback diagram. Without an account, what do we show? Options: a Mermaid stateDiagram written by the agent, or one generated from the machine.
  • Sketch format and location. .ts (scan finds it, but it imports xstate) or .json (no import, diff works, scan doesn't list it)? Scratchpad or a committed planning folder?
  • Stubbed implementations. Should architect require real assigns for context the guards read? Or should paths only be generated from an implemented machine?
  • Path explosion. Context values multiply the states the path search explores. What limits do we set before we feed the paths to tdd?
  • Tooling dependency. gstack would need Node, npx and network access to fetch pinned packages. Is that acceptable for a skill, and what's the fallback when they're missing?
  • Trigger. How does architect decide that work is "state-heavy" without asking every time?

Next step

Grill the open questions, starting with the Stately account and privacy questions. Then write state-machines.md and the architect edits.

Ngôn ngữ chính
TypeScript
Star
0
Fork
0
Merge trung bình
3 giờ 33 phút
Pull request đã merge (30 ngày)
13

Chuẩn bị môi trường

Dự án này không cung cấp dev container, Dockerfile hay hướng dẫn đóng góp, nên bạn cần tự thiết lập môi trường: hãy bắt đầu từ README và xem hướng dẫn đóng góp lần đầu của chúng tôi để biết các bước chung.

Bắt đầu từ đâu

  1. Đọc hết issue, rồi đọc hướng dẫn đóng góp của dự án.
  2. Bình luận trên issue rằng bạn sẽ nhận — tránh hai người làm cùng một việc.
  3. Fork repository và làm thay đổi trên một nhánh.
  4. Mở pull request có tham chiếu số hiệu của issue.

Issue khác của gregogun/gstack

Tất cả issue của gregogun/gstack

Issue tương tự

Thêm issue về TypeScript

Nhận issue mới trong hộp thư của bạn

Bản tóm tắt ngắn những issue GitHub phù hợp với người mới.