Hacktoberfest 2026 : les issues que les mainteneurs ont marquées pour octobre, ouvertes et accessibles aux débutants. Parcourir les issues Hacktoberfest

Use XState machines for designing and explaining complex state

Ouverte
  • Quelque chose ne va pas ?
#14 0 commentaires 0 réactions 0 personnes assignées Voir sur GitHub

Les mainteneurs répondent en général sous 1 jour

Personne n'a encore pris cette issue.

Évaluation

Difficulté
5/5
Temps estimé
Plus d'une semaine
Accessibilité débutants
35/100
Type d'issue
Fonctionnalité
Clarté
Plutôt claire
Activité
Active
Stack technique
node.js, typescript
Domaine
developer-experience

Piste de recherche

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.

Rédigé par le modèle d'indexation à partir du texte de l'issue.

Description

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.

Langage dominant
TypeScript
Étoiles
0
Forks
0
Merge moyen
3 h 33 min
PR mergées (30 j)
13

Préparer son environnement

Ce projet ne fournit ni conteneur de développement, ni Dockerfile, ni guide de contribution : l'installation est à votre charge. Commencez par son README, et consultez notre guide de la première contribution pour les étapes générales.

Par où commencer

  1. Lisez l'issue en entier, puis le guide de contribution du projet.
  2. Signalez en commentaire que vous la prenez — cela évite que deux personnes fassent le même travail.
  3. Forkez le dépôt et travaillez sur une branche.
  4. Ouvrez une pull request qui référence le numéro de l'issue.

Autres issues de gregogun/gstack

Toutes les issues de gregogun/gstack

Issues similaires

Plus d'issues TypeScript

Recevez les nouvelles issues par e-mail

Un résumé court des issues GitHub adaptées aux débutants.