Hacktoberfest 2026: le issue che i maintainer hanno segnato per ottobre, aperte e adatte ai principianti. Sfoglia le issue Hacktoberfest

Use XState machines for designing and explaining complex state

Aperta
  • Qualcosa non va?
#14 0 commenti 0 reazioni 0 assegnatari Vedi su GitHub

I maintainer di solito rispondono entro 1 giorno

Nessuno ha ancora preso questa issue.

Valutazione

Difficoltà
5/5
Tempo stimato
Più di una settimana
Idoneità per principianti
35/100
Tipo di issue
Funzionalità
Chiarezza
Abbastanza chiara
Stato di attività
Attiva
Stack tecnologico
node.js, typescript
Ambito
developer-experience

Direzione di ricerca

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.

Scritto dal modello di indicizzazione a partire dal testo della issue.

Descrizione

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.

Lingua principale
TypeScript
Stelle
0
Fork
0
Merge medio
3h 33m
PR unite (30g)
13

Preparare l'ambiente

Questo progetto non fornisce container di sviluppo, Dockerfile né guida per i contributori, quindi l'ambiente è a tuo carico: parti dal suo README e consulta la nostra guida al primo contributo per i passaggi generali.

Come iniziare

  1. Leggi tutta la issue e poi la guida ai contributi del progetto.
  2. Commenta sulla issue per dire che te ne occupi tu — evita che due persone facciano lo stesso lavoro.
  3. Fai un fork del repository e lavora su un branch.
  4. Apri una pull request che faccia riferimento al numero della issue.

Altre issue di gregogun/gstack

Tutte le issue di gregogun/gstack

Issue simili

Altre issue su TypeScript

Ricevi le nuove issue nella tua casella

Un breve riepilogo di issue GitHub adatte ai principianti.