delurio
The open checker and page of delurio-graph/0, a format for writing a product's flows, screens and API as one graph that people review in words, that is checked against the code, replayed on the real app and turned into tutorials. The format is SPEC.md.
This package is the part a project's own CI runs: it reads graph files and nothing else. There is no network, no account and no model.
Install
Run it once, without installing:
npx @delurio/[email protected] check graphs --strict
or pin an exact version in a project, after which the command is delurio:
npm install --save-dev --save-exact @delurio/cli
npx delurio check graphs --strict
or the container image, pinned by its digest:
docker run --rm -v "$PWD:/work" -w /work ghcr.io/delurio-labs/delurio@sha256:<digest> check graphs --strict
Node 22.18 or later.
Check every graph
npx @delurio/cli check graphs --strict
-
Findings: one line each, in the GNU error format that compilers, editors and CI logs read:
graphs/billing/billing.payment/flow.yaml:176:7: error: restricted-only-when-retries-ran-out is broken: … [assertion-violated] graphs/billing/billing.payment/flow.yaml:176:7: note: start: role = manager, paid = false graphs/billing/billing.payment/flow.yaml:176:7: note: step 1: RETRIES_RAN_OUT -
SARIF:
--format sarif --output delurio.sarifwrites SARIF 2.1.0 for code scanning. The same input gives the same bytes. -
Baseline:
--baseline <sarif>fails only on errors that are new since an earlier run.
| Exit | Meaning |
|---|---|
| 0 | every graph loads, and under --strict nothing is wrong |
| 1 | a graph cannot be loaded, or is written for a newer format than this version reads |
| 2 | under --strict: a guarantee is broken, a catalog key or a sample is missing, the main story cannot be walked, a writing flow has no changes note… |
A graph's page
npx @delurio/cli page examples/qauth-authorize --out viz/qauth-authorize
The page shows the flow in words: its main story, every way it ends, its guarantees and whether they hold, its screens as wireframes, and its diagram, which opens fitted to the window and moves like a design tool's canvas (drag to move, Ctrl or ⌘ + scroll or a pinch to zoom, Shift+1 to fit). examples/qauth-authorize is a small graph to try it on.
Given a folder of graphs instead, it writes the page of every graph under it, each at its own path, and index.html listing them all with what their check found:
npx @delurio/cli page graphs --out viz
Write a graph in an editor
The package ships a JSON Schema (2020-12) for each kind of graph file in schemas/: flow, ui, nav (also nav.extracted.yaml), domain and catalog. With them an editor completes keys, explains each one from SPEC.md on hover, and marks a typo, a value of the wrong kind, or a title cut short by a comma inside { }. In VS Code, with the YAML extension, put this in .vscode/settings.json:
{
"yaml.schemas": {
"https://unpkg.com/@delurio/[email protected]/schemas/flow.schema.json": "**/flow.yaml",
"https://unpkg.com/@delurio/[email protected]/schemas/ui.schema.json": "**/ui.yaml",
"https://unpkg.com/@delurio/[email protected]/schemas/nav.schema.json": ["**/nav.yaml", "**/nav.extracted.yaml"],
"https://unpkg.com/@delurio/[email protected]/schemas/domain.schema.json": ["**/domain.yaml", "**/domain/*.yaml"]
},
"json.schemas": [
{ "fileMatch": ["**/catalog/*.json"], "url": "https://unpkg.com/@delurio/[email protected]/schemas/catalog.schema.json" }
]
}
A domain may be split across the files of its directory (SPEC.md §5); **/domain/*.yaml covers them in a directory named domain, and a file elsewhere names its schema on its first line: # yaml-language-server: $schema=<the domain schema's URL>. With the package installed, ./node_modules/@delurio/cli/schemas/<kind>.schema.json works the same, offline. check reports the same as the editor, as errors of the rule schema that fail --strict, and finds what a schema cannot see, such as a state that does not exist or a catalog key that is missing.
Next to the editor, keep the pages open and current:
npx @delurio/cli page graphs --serve # http://127.0.0.1:4600/, written again and reloaded on every save
--watch writes the pages again on every change without serving them. --serve listens on 127.0.0.1 only and serves the written pages and nothing else; when a save leaves a graph that cannot be loaded, the open page says why until the next good save.
What a revision changes, in words
npx @delurio/cli diff examples/qauth-authorize --base origin/main
This prints Markdown for a pull request. It covers what the flow does differently (found by running both revisions) and what changed in the graph.
As a library
A tool built on the format can use the same loader and checker the CLI uses:
import { load } from '@delurio/cli/graph';
import { explore, Model } from '@delurio/cli/model';
const g = load('graphs/billing/billing.payment');
const configurations = explore(new Model(g.flow)).configs.length;
The entry points are graph, model, story, wireframe, kit, edges, html, nav, expr and yaml, each with its types. yaml reads a graph file's text as the CLI does (readYaml), refusing what SPEC.md §1 rules out before the text is resolved; a server that reads graphs it was sent should read them with it. While the version is 0.x their API may change in any minor release: pin an exact version.
Licence
Apache-2.0. See LICENSE and NOTICE. The name "delurio" is not licensed with the code.