@delurio/cli 0.1.0 → 0.2.0

package/CHANGELOG.md

@@ -0,0 +1,21 @@
+# Changelog
+
+While the version is 0.x, a release that can judge the same graphs differently (a new check, a stricter schema) bumps the minor; a fix that judges nothing differently bumps the patch.
+
+## 0.2.0 (2026-10-25)
+
+- JSON Schemas (2020-12) for `flow`, `ui`, `nav` (and `nav.extracted.yaml`), `domain` and `catalog` files, shipped in `schemas/`, for editors: completion, hover help from SPEC.md, and errors such as a typo in a key or a title cut short by a comma inside `{ }`.
+- `page --watch` writes the pages again on every change under the folder; `page --serve [--port <n>]` also serves them on 127.0.0.1 and reloads the open page after each write, or says why a graph could not be loaded.
+- `check` validates every graph file against its kind's schema: each place a file does not follow it is an error of the new rule `schema`, at its line and column, which fails `--strict` (exit 2) and works with `--baseline`.
+
+## 0.1.1 (2026-10-25)
+
+- `page` on a folder writes the page of every graph under it and `index.html` listing them, in one process.
+- A folder that holds no graph gets one line instead of a stack trace; counts read in the singular when there is one.
+- The README runs every command as `npx @delurio/cli`.
+
+## 0.1.0 (2026-10-25)
+
+- `check`: every graph under a folder, as GNU error lines or SARIF 2.1.0, with `--baseline`; exit 0, 1 or 2.
+- `page`: a graph's page in words, with its guarantees, screens and diagram.
+- `diff`: what a revision changes in a graph, in words, for a pull request.

package/README.md

@@ -6,10 +6,17 @@ This package is the part a project's own CI runs: it reads graph files and nothi
 
 ## Install
 
-Pin an exact version:
+Run it once, without installing:
+
+```sh
+npx @delurio/cli@0.1.1 check graphs --strict
+```
+
+or pin an exact version in a project, after which the command is `delurio`:
 
 ```sh
 npm install --save-dev --save-exact @delurio/cli
+npx delurio check graphs --strict
 ```
 
 or the container image, pinned by its digest:
@@ -23,15 +30,15 @@ Node 22.18 or later.
 ## Check every graph
 
 ```sh
-npx delurio check graphs --strict
+npx @delurio/cli check graphs --strict
 ```
 
 - **Findings:** one line each, in the GNU error format that compilers, editors and CI logs read:
 
   ```
-  graphs/billing/payment/flow.yaml:176:7: error: restricted-only-when-retries-ran-out is broken: … [assertion-violated]
-  graphs/billing/payment/flow.yaml:176:7: note: start: role = manager, paid = false
-  graphs/billing/payment/flow.yaml:176:7: note: step 1: RETRIES_RAN_OUT
+  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.sarif` writes SARIF 2.1.0 for code scanning. The same input gives the same bytes.
@@ -46,15 +53,49 @@ npx delurio check graphs --strict
 ## A graph's page
 
 ```sh
-npx delurio page graphs/billing/payment --out viz/payment
+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. `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:
+
+```sh
+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`:
+
+```json
+{
+  "yaml.schemas": {
+    "https://unpkg.com/@delurio/cli@0.2.0/schemas/flow.schema.json": "**/flow.yaml",
+    "https://unpkg.com/@delurio/cli@0.2.0/schemas/ui.schema.json": "**/ui.yaml",
+    "https://unpkg.com/@delurio/cli@0.2.0/schemas/nav.schema.json": ["**/nav.yaml", "**/nav.extracted.yaml"],
+    "https://unpkg.com/@delurio/cli@0.2.0/schemas/domain.schema.json": "**/domain.yaml"
+  },
+  "json.schemas": [
+    { "fileMatch": ["**/catalog/*.json"], "url": "https://unpkg.com/@delurio/cli@0.2.0/schemas/catalog.schema.json" }
+  ]
+}
+```
+
+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:
+
+```sh
+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
 
 ```sh
-npx delurio diff graphs/billing/payment --base origin/main
+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.

package/SPEC.md

@@ -68,7 +68,7 @@ states: { <state>: { .. } }
 assertions: [ { id, never: "<expression>", say, source } ]
 ```
 
-A flow is a statechart, and its meaning is a subset of SCXML's (W3C Recommendation, 2015). A transition in `on` is an SCXML transition with an event, `always` is a list of eventless transitions, a list of transitions is tried in document order, `invoke` and `type: final` mean what they mean in SCXML, a guard is a `cond` and an effect an `<assign>`; `DONE` and `FAIL.<class>` stand for SCXML's `done.invoke` and `error` events. A flow can therefore be written out as SCXML; that export is an open issue.
+A flow is a statechart, and its meaning is a subset of SCXML's (W3C Recommendation, 2015). A transition in `on` is an SCXML transition with an event, `always` is a list of eventless transitions, a list of transitions is tried in document order, `invoke` and `type: final` mean what they mean in SCXML, a guard is a `cond` and an effect an `<assign>`; `DONE` and `FAIL.<class>` stand for SCXML's `done.invoke` and `error` events. A flow can therefore be written out as SCXML; that export is [#9](https://github.com/delurio-labs/delurio/issues/9).
 
 ### Context
 
@@ -117,7 +117,7 @@ A configuration is a state together with a value for every context variable. The
 
 Each assertion is `never: <expression>`: it holds when no reachable configuration satisfies the expression. A violation is reported with the shortest event path from a starting situation. Under `--strict` a violated assertion exits 2.
 
-The checker does not yet fail on unreachable states, transitions no situation takes, or states with no way out; the page already shows them. That is an open issue. Paths that cover every transition are an open issue.
+The checker does not yet fail on unreachable states, transitions no situation takes, or states with no way out; the page already shows them. That is [#2](https://github.com/delurio-labs/delurio/issues/2). Paths that cover every transition are [#4](https://github.com/delurio-labs/delurio/issues/4).
 
 ### Several flows
 
@@ -177,7 +177,7 @@ rules: [ { id, rule } ]
 
 A `role` is a WAI-ARIA 1.2 role, and `name` is the accessible name that Accessible Name and Description Computation 1.2 gives the node; `kit check` reads both from the browser's accessibility tree.
 
-A node is shown in a state when the state is in `in`, not in `unless`, and `when` holds. `edges` records relations the page and the checks use: a node labelled by another, an action that leads to a state. `rules` are written but no tool reads them yet; checking them, together with dialogs, focus return, confirmation before a destructive action and events handled where shown, is an open issue.
+A node is shown in a state when the state is in `in`, not in `unless`, and `when` holds. `edges` records relations the page and the checks use: a node labelled by another, an action that leads to a state. `rules` are written but no tool reads them yet; checking them, together with dialogs, focus return, confirmation before a destructive action and events handled where shown, is [#3](https://github.com/delurio-labs/delurio/issues/3).
 
 ### Catalog
 
@@ -231,11 +231,13 @@ invariants:
 
 A capture may carry more words of its own on a field (`owner`, `note`, `editableBy`, `matching`, `opaque`). They are kept and compared, and no tool reads them.
 
+An action, a refusal and an invariant may carry `note`: the author's own words, which no tool reads. An invariant the code does not keep is still written, with `holds: false` and the `finding` that reports it: the finding's id in the graph's report, such as `MS-7`. A capture describes the code, so the invariant says what should hold and the finding says where it does not. Decided on 25 Oct 2026.
+
 **The API.** An action with a `route` (`METHOD /path`) is one OpenAPI 3.1 operation: its name is the `operationId`, `needs` its security requirement, `query` (a JSON Schema object) its query parameters, `body` its request body, `result` its response (`returns` an entity, a `redirect`, a `status`, or a JSON Schema), and each refusal one more response. When a refusal has a body, it is RFC 9457 problem details with the refusal code as its `type`. So a domain can be written out as an OpenAPI document, and an app that already publishes one names it at the top (`openapi: <file>`) and each action's operation by `operationId`, instead of copying them. An action with no route is a step inside the service. `needs`, `policies`, `sideEffects`, `refusals.<code>.redirect` and `invariants` are delurio's own: no standard says who may do what to which data, or what must always hold.
 
-This form was decided on 22 Oct 2026. Graphs captured before it may still give fields as `{ kind: text }`; they are converted when a tool first reads fields. The OpenAPI export and import are an open issue.
+This form was decided on 22 Oct 2026. Graphs captured before it may still give fields as `{ kind: text }`; they are converted when a tool first reads fields. The OpenAPI export and import are [#8](https://github.com/delurio-labs/delurio/issues/8).
 
-No tool checks a domain yet: the revision diff compares it and anchors lock its `source:` keys. Loading it with the flow and checking policies, secrets and `invoke` names is an open issue; generating it from Drizzle and Zod is an open issue; a registry that every API operation and route is covered by a graph is an open issue.
+No tool checks a domain yet: the revision diff compares it and anchors lock its `source:` keys. Loading it with the flow and checking policies, secrets and `invoke` names is [#5](https://github.com/delurio-labs/delurio/issues/5); generating it from Drizzle and Zod is [#6](https://github.com/delurio-labs/delurio/issues/6); a registry that every API operation and route is covered by a graph is [#7](https://github.com/delurio-labs/delurio/issues/7).
 
 ## 6. Navigation (`kind: nav`)
 
@@ -324,12 +326,12 @@ graphs/product/flow.yaml:88:7: note: step 2: CODE_CHANGED from developing, with
 
 The same input gives the same bytes: no times, no random ids, results in a fixed order. Every file written is valid against the OASIS schema.
 
-There is no other machine format: no JSON of delurio's own, and nothing that only one CI reads. A converter for a CI that reads neither (GitLab's Code Quality report, Bitbucket's Code Insights) is written when a customer needs it, outside the checker. The public, pinned, offline CLI that gives both outputs is an open issue.
+There is no other machine format: no JSON of delurio's own, and nothing that only one CI reads. A converter for a CI that reads neither (GitLab's Code Quality report, Bitbucket's Code Insights) is written when a customer needs it, outside the checker. The public, pinned, offline CLI that gives both outputs is `@delurio/cli`, built from this repository; what its first release left out is [#1](https://github.com/delurio-labs/delurio/issues/1).
 
 ## 11. Writing a graph
 
 - Model the few cases that change behaviour; a guard over hundreds of permission codes is wrong.
-- Quote a YAML list item that contains `: `, or YAML reads it as a map.
+- Quote a YAML list item that contains `: `, or YAML reads it as a map. Quote a value inside `{ }` that contains `, ` too, or YAML cuts it there and reads the rest as a key: `{ type: final, title: "Paid, and sent" }`.
 - Say every rule that must hold as an assertion; do not leave it implied by the drawing.
 - In capture mode, describe what the code does today: no new feature, no fix. An invariant the code breaks is modelled as the code has it and reported, not written as an assertion that fails.
 - One process, one flow. A process that runs beside another starts it (`starts:`) or waits for it (`invoke: { flow }`).

package/dist/check.js

@@ -14,6 +14,7 @@ import { checkStarts } from './starts.js';
 import { checkChanges } from './changes.js';
 import { KitError, resolveKit } from './kit.js';
 import { checkGoals, findings, loadNav, viewOf } from './nav.js';
+import { schemaKindOf, validateFile } from './schemas.js';
 export const CHECK_USAGE = [
     '  node src/cli.ts check <graphs folder> [--strict] [--baseline <sarif>] [--format sarif --output <file>]',
     '    checks every graph under the folder and writes nothing else: GNU error lines on stdout, or SARIF 2.1.0;',
@@ -24,6 +25,7 @@ const SKIP = new Set(['viz', 'video', 'recording', 'node_modules', '.git']);
 const RULES = [
     { id: 'load', text: 'The graph cannot be loaded', level: 'error' },
     { id: 'format-newer', text: 'The graph is written for a newer format than this checker reads', level: 'error' },
+    { id: 'schema', text: "A graph file does not follow its kind's schema (SPEC.md)", level: 'error' },
     { id: 'assertion-violated', text: 'A guarantee of the flow is broken by a reachable situation', level: 'error' },
     { id: 'main-story-unwalkable', text: 'The declared main story cannot be walked', level: 'error' },
     { id: 'catalog-key-missing', text: 'A catalog key the screens use is missing', level: 'error' },
@@ -39,6 +41,7 @@ const RULES = [
     { id: 'nav-note', text: 'A note on the navigation graph', level: 'warning' },
 ];
 const LEVEL = new Map(RULES.map((r) => [r.id, r.level]));
+export const count = (n, word) => `${n} ${word}${n === 1 ? '' : 's'}`;
 // the 1-based line and column of the first occurrence of `needle`, else the file's start
 function placeOf(abs, needle) {
     if (needle === null || !existsSync(abs))
@@ -51,7 +54,8 @@ function placeOf(abs, needle) {
     }
     return { line: 1, column: 1 };
 }
-function graphDirs(root, out = []) {
+// every graph folder at or under root, in path order
+export function graphDirs(root, out = []) {
     if (existsSync(join(root, 'flow.yaml')) || existsSync(join(root, 'nav.yaml')))
         out.push(root);
     for (const name of readdirSync(root).sort()) {
@@ -63,6 +67,19 @@ function graphDirs(root, out = []) {
     }
     return out;
 }
+// every file under root that a schema covers (flow, ui, nav, nav.extracted, domain, catalog), in path order
+function graphFiles(root, out = []) {
+    for (const name of readdirSync(root).sort()) {
+        if (SKIP.has(name) || name.startsWith('.'))
+            continue;
+        const path = join(root, name);
+        if (statSync(path).isDirectory())
+            graphFiles(path, out);
+        else if (schemaKindOf(path) !== null)
+            out.push(path);
+    }
+    return out;
+}
 // the format the file says it is written in: null when it is this one
 function newerFormat(abs) {
     const doc = parse(readFileSync(abs, 'utf8'));
@@ -237,6 +254,11 @@ export function checkMain(args) {
             results.push(result('load', file, linePos === undefined ? { line: 1, column: 1 } : { line: linePos.line, column: linePos.col }, err.message.split('\n')[0], rel(d), 'load'));
         }
     }
+    // every graph file against its kind's schema: what an editor with the schemas marks, check reports
+    for (const file of graphFiles(root)) {
+        for (const f of validateFile(file))
+            results.push(result('schema', file, f, f.message, f.graph ?? rel(file), f.element));
+    }
     results.sort((a, b) => a.file.localeCompare(b.file) || a.line - b.line || a.column - b.column || a.rule.localeCompare(b.rule) || a.message.localeCompare(b.message));
     if (baseline !== undefined) {
         const prints = baselinePrints(baseline);
@@ -260,7 +282,9 @@ export function checkMain(args) {
                 console.log(`${n.file}:${n.line}:${n.column}: note: ${n.message}`);
         }
         const graphs = graphDirs(root).length;
-        console.error(`delurio check: ${graphs} graphs, ${results.filter((r) => r.level === 'error').length} errors, ${results.filter((r) => r.level === 'warning').length} warnings; exit ${exitCode}`);
+        const errors = results.filter((r) => r.level === 'error').length;
+        const warnings = results.filter((r) => r.level === 'warning').length;
+        console.error(`delurio check: ${count(graphs, 'graph')}, ${count(errors, 'error')}, ${count(warnings, 'warning')}; exit ${exitCode}`);
     }
     return exitCode;
 }

package/dist/cli.js

@@ -2,9 +2,9 @@
 // delurio: the open checker and page of delurio-graph/0 (SPEC.md). Reads graph files and nothing else: no network, no
 // account, no model.
 import { mkdirSync, writeFileSync } from 'node:fs';
-import { existsSync } from 'node:fs';
-import { join, resolve } from 'node:path';
-import { GraphError, load } from './graph.js';
+import { existsSync, statSync } from 'node:fs';
+import { basename, join, relative, resolve, sep } from 'node:path';
+import { GraphError, humanize, load } from './graph.js';
 import { checkAssertions, explore, finalPaths, Model, ModelError } from './model.js';
 import { renderMermaid } from './mermaid.js';
 import { renderSpine } from './spine.js';
@@ -17,20 +17,24 @@ import { checkGoals, findings, loadNav, menuRows, viewOf } from './nav.js';
 import { renderNavMermaid, renderNavPage } from './nav-page.js';
 import { DIFF_USAGE, diffMain } from './diff.js';
 import { KitError, resolveKit } from './kit.js';
-import { CHECK_USAGE, checkMain } from './check.js';
+import { CHECK_USAGE, checkMain, count, graphDirs } from './check.js';
+import { renderIndexPage } from './index-page.js';
+import { watchPages } from './watch.js';
 const USAGE = [
     'usage:',
     CHECK_USAGE,
-    '  delurio page <graph dir> [--out <dir>] [--kit <kit>] [--locale <code>] [--strict]',
-    '    writes the graph\'s page: <out>/index.html and its diagram (default out: <graph dir>/viz)',
+    '  delurio page <graph dir | graphs folder> [--out <dir>] [--kit <kit>] [--locale <code>] [--strict] [--watch] [--serve [--port <n>]]',
+    '    writes the graph\'s page: <out>/index.html and its diagram (default out: <graph dir>/viz); on a folder of graphs,',
+    '    the page of each at <out>/<its path> and an index of them all at <out>/index.html (default out: <folder>/viz);',
+    '    --watch writes them again on every change under the folder; --serve also shows them at http://127.0.0.1:<port>/',
+    '    (default 4600) and reloads the open page after each write',
     DIFF_USAGE.replaceAll('node src/cli.ts', 'delurio'),
 ].join('\n').replaceAll('node src/cli.ts', 'delurio');
 const flag = (args, name) => {
     const i = args.indexOf(name);
     return i >= 0 ? args[i + 1] : undefined;
 };
-function navPage(dir, args) {
-    const out = resolve(flag(args, '--out') ?? join(dir, 'viz'));
+function navPage(dir, out, args) {
     const { g, warnings } = loadNav(dir, flag(args, '--locale'));
     const views = g.personas.map((p) => viewOf(g, p));
     const rows = menuRows(g, views);
@@ -40,14 +44,15 @@ function navPage(dir, args) {
     writeFileSync(join(out, 'index.html'), renderNavPage({ g, views, rows, goals, found, repo: null, warnings }));
     writeFileSync(join(out, 'nav.mmd'), renderNavMermaid(g));
     const problems = found.filter((f) => f.level === 'problem');
-    console.log(`${g.id}: ${Object.keys(g.pages).length} pages, ${g.specs.length} ways to move, ${g.personas.length} kinds of user; ${problems.length} problems, ${found.length - problems.length} notes`);
+    console.log(`${g.id}: ${count(Object.keys(g.pages).length, 'page')}, ${count(g.specs.length, 'way')} to move, ${g.personas.length} ${g.personas.length === 1 ? 'kind' : 'kinds'} of user; ${count(problems.length, 'problem')}, ${count(found.length - problems.length, 'note')}`);
     for (const w of warnings)
         console.error(`warning: ${w}`);
-    console.log(`wrote ${join(out, 'index.html')} and ${join(out, 'nav.mmd')}`);
-    return args.includes('--strict') && (warnings.length > 0 || problems.length > 0) ? 2 : 0;
+    return {
+        code: args.includes('--strict') && (warnings.length > 0 || problems.length > 0) ? 2 : 0,
+        entry: { path: '', kind: 'nav', id: g.id, title: `${g.title}: where people go`, status: g.status, holds: 0, total: problems.length, warnings, error: null },
+    };
 }
-async function flowPage(dir, args) {
-    const out = resolve(flag(args, '--out') ?? join(dir, 'viz'));
+async function flowPage(dir, out, args) {
     const warnings = [];
     const warn = (m) => {
         if (!warnings.includes(m))
@@ -78,13 +83,71 @@ async function flowPage(dir, args) {
     writeFileSync(join(out, 'index.html'), renderPage({ g, m: model, ex, assertions, finals, main, spineMain, spineFull, screens, kit, handOvers }));
     writeFileSync(join(out, 'flow.mmd'), renderMermaid(g, ex));
     const violated = assertions.filter((a) => a.violation !== undefined);
-    console.log(`${g.flow.id}: ${Object.keys(g.flow.states).length} states, ${ex.configs.length} configurations from ${ex.starts} starts, ${assertions.length - violated.length}/${assertions.length} assertions hold`);
+    console.log(`${g.flow.id}: ${count(Object.keys(g.flow.states).length, 'state')}, ${count(ex.configs.length, 'configuration')} from ${count(ex.starts, 'start')}, ${assertions.length - violated.length}/${assertions.length} assertions hold`);
     for (const a of violated)
         console.log(`  violated: ${a.id}`);
     for (const w of warnings)
         console.error(`warning: ${w}`);
-    console.log(`wrote ${join(out, 'index.html')} and ${join(out, 'flow.mmd')}`);
-    return args.includes('--strict') && (violated.length > 0 || warnings.length > 0) ? 2 : 0;
+    return {
+        code: args.includes('--strict') && (violated.length > 0 || warnings.length > 0) ? 2 : 0,
+        entry: { path: '', kind: 'flow', id: g.flow.id, title: g.flow.title ?? humanize(g.flow.id), status: g.flow.status ?? null, holds: assertions.length - violated.length, total: assertions.length, warnings, error: null },
+    };
+}
+const isGraph = (dir) => existsSync(join(dir, 'flow.yaml')) || existsSync(join(dir, 'nav.yaml'));
+// every graph under the folder, each into <out>/<its path>, and the index of them all. A graph that cannot be loaded
+// is listed as such and the rest are still written: exit 1 when one cannot be loaded, else 2 under --strict when one
+// would fail on its own, else 0.
+async function treePages(root, out, args) {
+    const dirs = graphDirs(root);
+    if (dirs.length === 0) {
+        const message = `${root} is not a graph and holds none: there is no flow.yaml or nav.yaml in it or under it`;
+        console.error(`error: ${message}`);
+        return { code: 1, message };
+    }
+    const entries = [];
+    let broken = false;
+    let failing = false;
+    for (const dir of dirs) {
+        const path = relative(root, dir).split(sep).join('/');
+        const nav = !existsSync(join(dir, 'flow.yaml'));
+        try {
+            const { code, entry } = nav ? navPage(dir, join(out, path), args) : await flowPage(dir, join(out, path), args);
+            entries.push({ ...entry, path });
+            failing ||= code !== 0;
+        }
+        catch (err) {
+            if (!loadError(err))
+                throw err;
+            broken = true;
+            const message = err.message.split('\n')[0].replace(/:$/, '');
+            console.error(`error: ${path}: ${message}`);
+            entries.push({ path, kind: nav ? 'nav' : 'flow', id: null, title: path, status: null, holds: 0, total: 0, warnings: [], error: message });
+        }
+    }
+    mkdirSync(out, { recursive: true });
+    writeFileSync(join(out, 'index.html'), renderIndexPage(basename(resolve(root)), entries));
+    console.log(`wrote ${join(out, 'index.html')} and the pages of ${count(entries.length - entries.filter((e) => e.error !== null).length, 'graph')} under ${out}`);
+    const firstError = entries.find((e) => e.error !== null);
+    return { code: broken ? 1 : failing ? 2 : 0, message: firstError === undefined ? '' : `${firstError.path}: ${firstError.error}` };
+}
+const loadError = (err) => err instanceof GraphError || err instanceof ModelError || err instanceof KitError || (err instanceof Error && err.name === 'YAMLParseError');
+// one graph's page, or the pages of every graph under the folder
+async function writePages(dir, out, args) {
+    if (!isGraph(dir))
+        return treePages(dir, out, args);
+    try {
+        const flow = existsSync(join(dir, 'flow.yaml'));
+        const { code } = flow ? await flowPage(dir, out, args) : navPage(dir, out, args);
+        console.log(`wrote ${join(out, 'index.html')} and ${join(out, flow ? 'flow.mmd' : 'nav.mmd')}`);
+        return { code, message: '' };
+    }
+    catch (err) {
+        if (!loadError(err))
+            throw err;
+        const message = err.message.split('\n')[0].replace(/:$/, '');
+        console.error(`error: ${message}`);
+        return { code: 1, message };
+    }
 }
 async function main() {
     const args = process.argv.slice(2);
@@ -94,13 +157,30 @@ async function main() {
         return diffMain(args.slice(1));
     if (args[0] === 'page') {
         const rest = args.slice(1);
-        const withValue = ['--out', '--kit', '--locale'];
+        const withValue = ['--out', '--kit', '--locale', '--port'];
         const dir = rest.find((a, i) => !a.startsWith('--') && !withValue.includes(rest[i - 1] ?? ''));
         if (dir === undefined) {
             console.error(USAGE);
             return 1;
         }
-        return existsSync(join(dir, 'flow.yaml')) ? flowPage(dir, rest) : navPage(dir, rest);
+        if (!existsSync(dir) || !statSync(dir).isDirectory()) {
+            console.error(`error: ${dir} is not a folder`);
+            return 1;
+        }
+        const out = resolve(flag(rest, '--out') ?? join(dir, 'viz'));
+        const first = await writePages(dir, out, rest);
+        const serve = rest.includes('--serve');
+        if (!serve && !rest.includes('--watch'))
+            return first.code;
+        const port = Number(flag(rest, '--port') ?? 4600);
+        if (!Number.isInteger(port) || port < 1 || port > 65535) {
+            console.error(`error: --port is a port number, not ${flag(rest, '--port')}`);
+            return 1;
+        }
+        return watchPages(dir, out, async () => {
+            const again = await writePages(dir, out, rest);
+            return { ok: again.code !== 1, message: again.message };
+        }, serve ? port : null);
     }
     console.error(USAGE);
     return args.length === 0 || args.includes('--help') ? 0 : 1;

package/dist/index-page.js

@@ -0,0 +1,50 @@
+// The index of `page` on a folder of graphs: one row per graph, grouped by the folder it sits in, with what its check
+// found and a link to its page.
+import { CSS } from './html.js';
+import { count } from './check.js';
+const esc = (s) => s.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;').replace(/"/g, '&quot;');
+const INDEX_CSS = `
+.groups h2 { font-size: 18px; margin: 32px 0 10px; } .groups table { table-layout: fixed; } .groups col.check { width: 9em; }
+.groups a { color: var(--accent); } .groups td { overflow-wrap: anywhere; }
+.meta { margin-top: 2px; } .meta .tag { margin-left: 6px; } .warn { margin-top: 6px; color: var(--muted); font-size: 14px; } .warn ul { margin: 4px 0 0; padding-left: 18px; }
+`;
+function stateCell(e) {
+    if (e.error !== null)
+        return `<span class="bad">cannot be loaded</span>`;
+    if (e.kind === 'nav')
+        return `<span class="${e.total === 0 ? 'ok' : 'bad'}">${esc(count(e.total, 'problem'))}</span>`;
+    if (e.total === 0)
+        return '<span class="muted">no guarantees</span>';
+    return e.holds === e.total ? `<span class="ok">${e.holds}/${e.total} hold</span>` : `<span class="bad">${e.total - e.holds} of ${e.total} broken</span>`;
+}
+// root: the indexed folder's name, which also heads the graphs that sit right in it
+export function renderIndexPage(root, entries) {
+    const out = [];
+    const failing = entries.filter((e) => e.error !== null || (e.kind === 'flow' ? e.holds < e.total : e.total > 0));
+    const flows = entries.filter((e) => e.kind === 'flow').length;
+    const navs = entries.length - flows;
+    out.push('<!doctype html><html lang="en"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width, initial-scale=1">');
+    out.push(`<title>All graphs</title><style>${CSS}${INDEX_CSS}</style></head><body><main>`);
+    out.push(`<p class="eyebrow"><span class="mono">${esc(root)}/</span> · delurio-graph/0</p><h1>All graphs</h1>`);
+    const kinds = [flows > 0 ? count(flows, 'flow') : '', navs > 0 ? count(navs, 'navigation graph') : ''].filter((s) => s !== '').join(' and ');
+    out.push(`<p class="lede">${esc(kinds)}. ${failing.length === 0 ? 'Every guarantee holds and nothing blocks anyone.' : `${esc(count(failing.length, 'graph'))} need${failing.length === 1 ? 's' : ''} a look: marked in red below.`}</p>`);
+    const groups = new Map();
+    for (const e of entries) {
+        const slash = e.path.lastIndexOf('/');
+        const folder = slash < 0 ? root : e.path.slice(0, slash);
+        groups.set(folder, [...(groups.get(folder) ?? []), e]);
+    }
+    out.push('<div class="groups">');
+    for (const [folder, rows] of groups) {
+        out.push(`<h2>${esc(folder)}</h2><div class="scroll"><table><colgroup><col><col class="check"></colgroup><thead><tr><th>Graph</th><th>Check</th></tr></thead><tbody>`);
+        for (const e of rows) {
+            const name = e.error !== null ? esc(e.title) : `<a href="${esc(e.path)}/index.html">${esc(e.title)}</a>`;
+            const meta = e.id === null ? '' : `<div class="meta"><span class="mono muted">${esc(e.id)}</span>${e.status === null ? '' : `<span class="tag">${esc(e.status)}</span>`}</div>`;
+            const warn = e.error !== null ? `<div class="warn">${esc(e.error)}</div>` : e.warnings.length === 0 ? '' : `<div class="warn">${esc(count(e.warnings.length, 'warning'))}<ul>${e.warnings.map((w) => `<li>${esc(w)}</li>`).join('')}</ul></div>`;
+            out.push(`<tr><td>${name}${meta}${warn}</td><td class="state">${stateCell(e)}</td></tr>`);
+        }
+        out.push('</tbody></table></div>');
+    }
+    out.push('</div></main></body></html>');
+    return out.join('\n');
+}