@topogram/extractor-xstate-workflows

@topogram/extractor-xstate-workflows

Package-backed Topogram extractor for review-only XState workflow candidates.

Status: current Audience: extractor authors and maintainers Use when: you need to implement, verify, or package this Topogram extractor.

This extractor reads JavaScript and TypeScript source that defines XState machines with createMachine(...) and emits review-only workflow candidates: workflow definitions, states, and transitions. Topogram core owns persistence, extract reports, reconcile/adoption, and canonical topo/** writes.

Author Loop

npm install
npm test
npm run docs:rag:check
npm run check
npm run release:preflight

npm run check uses TOPOGRAM_CLI, then TOPOGRAM_BIN, then the locally installed @topogram/cli. Use TOPOGRAM_CLI=/path/to/topogram/engine/src/cli.js npm run check while developing against a local Topogram checkout.

npm run check runs:

• npm test
• npm run docs:rag:check
• topogram extractor check .
• topogram extract ./fixtures/basic-source --out <tmp> --from workflows --extractor .
• topogram extract plan <tmp>
• topogram query extract-plan <tmp>/topo
• topogram adopt --list <tmp>

The adapter in index.cjs is intentionally static and read-only. It scans source text; it does not evaluate the app, import user modules, mutate source files, write canonical topo/**, install packages, perform network access, or define adoption semantics.

Keep llms.txt curated and regenerate llms-full.txt after README or agent guidance changes:

npm run docs:rag:build
npm run docs:rag:check

The docs scripts resolve this package root from their own file location and refuse links or writes that escape the package root.

npm run release:preflight runs the author checks, npm pack --dry-run, and the package-local Gitleaks secret scan. If CI already ran Gitleaks, it may set TOPOGRAM_SECRET_SCAN_ALREADY_RAN=1 for this script; do not use that skip in local release prep.

Shared or published extractor packs should adopt SDLC so rules, tasks, and proof history are queryable by agents. Private one-off extractors may stay lightweight, but they should still follow the generated AGENTS.md rules.

Candidate output is validated by track. This package returns only workflow_definitions, workflow_states, and workflow_transitions, with stable IDs and project-relative evidence. It never returns files, patches, adoption plans, or write instructions.