aontu 0.54.0 → 0.56.0

package/dist/cli.js

@@ -20,6 +20,7 @@ exports.runWhy = runWhy;
 exports.renderWhyText = renderWhyText;
 exports.runSet = runSet;
 exports.runAgentsMd = runAgentsMd;
+exports.runFmt = runFmt;
 exports.watchChange = watchChange;
 exports.watchSignature = watchSignature;
 exports.deprecatedAt = deprecatedAt;
@@ -46,6 +47,8 @@ const vet_1 = require("./vet");
 const reach_1 = require("./reach");
 const view_1 = require("./view");
 const agentsmd_1 = require("./agentsmd");
+const format_1 = require("./format");
+const utility_1 = require("./utility");
 const HELP = `Usage: aontu [options] [file]
        aontu vet [options] <schema> <data> [more-data...]
        aontu subsume [options] <general> <specific>
@@ -62,6 +65,7 @@ const HELP = `Usage: aontu [options] [file]
        aontu why <path> [options] <file>
        aontu set <path>=<value>... --entry <file> --overlay <file>
        aontu agentsmd [--write <AGENTS.md>] <file>
+       aontu fmt [-w|-l|--check|-d] <file>...
 
 Evaluate an Aontu source file and print the result as JSON.
 With no file on an interactive terminal, start a REPL.
@@ -84,6 +88,10 @@ Options:
                   Every verb takes it too, and a bare root means the
                   document's own directory
   --include-root <dir>  Shorthand for --trust root:<dir>
+  --text-ext <e>  Read these extensions as text too, comma-separated
+                  and without dots (md,sql). .txt needs no flag; a
+                  named format keeps its meaning, and .js stays
+                  refused. Every verb takes it
 
 Mod options:
   --format <f>    text (default) or json
@@ -175,21 +183,22 @@ Why options:
 Why exit codes mirror get's: 0 explained, 1 the path names nothing,
 2 usage, 4 the document does not stand up on its own.
 
-View kinds: tree, matrix, graph, layer, sets, layers, ladder, poset
-(the poset takes several files). The figure goes to stdout, the loss
+View kinds: doc, lattice, tree, matrix, graph, layer, sets, layers,
+ladder, poset (the poset takes several files). The figure goes to stdout, the loss
 report to stderr. With --views it draws every figure a document
 declares as data, from one evaluation: each declaration names its own
 kind and out file, nothing is written unless every figure rendered,
 and --check gates the committed set.
 
 View options:
-  --as <profile>    text | mermaid | dot | er | svg, per kind: tree,
-                    matrix, sets and layers draw text (default) or
-                    svg; graph draws mermaid (default), dot or er;
-                    layer draws text (default), mermaid or svg; ladder
-                    and poset draw mermaid (default) or dot
+  --as <profile>    text | mermaid | dot | er | svg, per kind: doc,
+                    lattice, tree, matrix, sets and layers draw text
+                    (default) or svg; graph draws mermaid (default),
+                    dot or er; layer draws text (default), mermaid or
+                    svg; ladder and poset draw mermaid (default) or dot
   --at <path>       Restrict the figure to nodes under this path; the
-                    path the ladder draws; where the poset compares
+                    subtree doc draws; the subtree the lattice counts;
+                    the path the ladder draws; where the poset compares
   --views <path>    Draw every figure the document declares at this
                     path, one evaluation, all or nothing; each
                     declaration names its own kind and out file
@@ -198,7 +207,20 @@ View options:
                     nothing is written
   --strict          Exit 1 when the loss report holds anything beyond
                     edges_deduped, inverse_suppressed and crossings
+  --depth <n>       doc: how many levels of key to draw (default 3)
   --max-rows <n>    Refuse a figure above this many rows (default 60)
+  --style <s>       auto (default), none, ansi or css. A figure's
+                    marks carry their meaning -- a direct cell, a
+                    closure cell, an upward edge -- and each profile
+                    has one way to show it: SGR escapes for text, CSS
+                    classes for svg. auto picks that mechanism where
+                    the destination can carry it: escapes only on a
+                    terminal (NO_COLOR is honoured), and an svg keeps
+                    the stylesheet that makes it standalone. none
+                    drops both; on svg the classes stay and only the
+                    stylesheet goes, for a host page that has already
+                    bound --av-ink and its kin. Escapes are never
+                    written to a file
   --format <f>      text (default) or json, the whole report
   --relation <n>    tree, matrix, layer: draw over this relation only;
                     graph: keep this predicate (repeatable)
@@ -255,6 +277,19 @@ Agentsmd options:
 Agentsmd exit codes: 0 generated, 2 usage, 4 the document does not
 stand up on its own.
 
+Fmt options:
+  -w, --write     Rewrite each file in place, when its form would change
+  -l, --list      Print the name of each file whose form would change
+  --check         Like --list, and exit 1 when any would: the CI gate
+  -d, --diff      Print a unified diff for each file whose form would
+                  change
+
+The fmt verb prints one document in the agreed form; with no file it
+reads standard input. Several files need one of the options above.
+
+Fmt exit codes: 0 formatted or clean, 1 a --check file would change,
+2 usage, 4 a document does not parse.
+
 REPL commands:
   :help           Show REPL help
   :load <file>    Evaluate a document and hold it for the commands below
@@ -319,15 +354,16 @@ function makeTrustWarn() {
 // entryRoot (the entry file's directory, or the working directory for
 // stdin/REPL).
 function trustOpts(trust, entryRoot) {
+    const text = 0 === trust.textExt.length ? {} : { textExt: trust.textExt };
     switch (trust.kind) {
         case 'none':
-            return { trust: { include: 'none' } };
+            return { ...text, trust: { include: 'none' } };
         case 'root':
-            return { trust: { include: { root: trust.dir ?? entryRoot } } };
+            return { ...text, trust: { include: { root: trust.dir ?? entryRoot } } };
         case 'system':
-            return {};
+            return { ...text };
         default: // system-warn: today's default plus the warning window
-            return { trustWarn: makeTrustWarn(), trustWarnRoot: entryRoot };
+            return { ...text, trustWarn: makeTrustWarn(), trustWarnRoot: entryRoot };
     }
 }
 // EVERY VERB honours the include capability, not just the bare
@@ -342,7 +378,8 @@ function trustOpts(trust, entryRoot) {
 // already printed: the caller answers the usage class.
 function takeTrust(argv) {
     const rest = [];
-    let trust = { kind: 'system-warn' };
+    let trust = { kind: 'system-warn', textExt: [] };
+    let textExt = [];
     for (let i = 0; i < argv.length; i++) {
         const arg = argv[i];
         if ('--trust' === arg) {
@@ -359,18 +396,42 @@ function takeTrust(argv) {
                 process.stderr.write('aontu: --include-root needs a directory\n');
                 return undefined;
             }
-            trust = { kind: 'root', dir };
+            trust = { kind: 'root', dir, textExt };
+        }
+        else if ('--text-ext' === arg) {
+            const list = null == argv[i + 1] ? undefined : parseTextExt(argv[++i]);
+            if (null == list) {
+                process.stderr.write('aontu: --text-ext needs extensions, without dots' +
+                    ' (--text-ext md,sql)\n');
+                return undefined;
+            }
+            textExt = [...textExt, ...list];
         }
         else {
             rest.push(arg);
         }
     }
-    return { argv: rest, trust };
+    return { argv: rest, trust: { ...trust, textExt } };
+}
+// `md,sql` or `.md,.sql` -- the dot is accepted and dropped, because a
+// reader who has just written `@"notes.txt"` reaches for one. An empty
+// element, or anything that is not an extension, is a usage error
+// rather than a silently ignored word: a flag that quietly does
+// nothing is how a document ends up refused with no reason visible.
+function parseTextExt(arg) {
+    const out = [];
+    for (const raw of arg.split(',')) {
+        const ext = raw.trim().replace(/^\./, '').toLowerCase();
+        if ('' === ext || !/^[a-z0-9]+$/.test(ext)) {
+            return undefined;
+        }
+        out.push(ext);
+    }
+    return out;
 }
 // The evaluator options a REPL session's capability means.
 function replTrust(state, entryRoot) {
-    const capability = verbTrust(state.trust ?? { kind: 'system-warn' }, entryRoot);
-    return null == capability ? {} : { trust: capability };
+    return verbOpts(state.trust ?? { kind: 'system-warn', textExt: [] }, entryRoot);
 }
 // The capability a verb's engine runs under. `system` and the staged
 // warning default both mean today's behaviour (no option); the warning
@@ -386,6 +447,18 @@ function verbTrust(trust, entryRoot) {
             return undefined;
     }
 }
+// THE INCLUDE OPTIONS A VERB RUNS UNDER, spread into its engine call:
+// the capability above, and the extensions `--text-ext` widened. Both
+// are absent when unset rather than present-and-undefined, so a verb's
+// options bag is byte-identical to what it was before either flag
+// existed and no engine sees a key it has to ignore.
+function verbOpts(trust, entryRoot) {
+    const include = verbTrust(trust, entryRoot);
+    return {
+        ...(undefined === include ? {} : { trust: include }),
+        ...(0 === trust.textExt.length ? {} : { textExt: trust.textExt }),
+    };
+}
 // The directory a bare `--trust root` confines to for a verb: the
 // primary document's own, matching the bare command's entry root.
 function entryRootOf(file) {
@@ -491,7 +564,7 @@ function replCommand(state, line, read) {
             if (':why' === cmd) {
                 const report = (0, aontu_1.why)(src, path, {
                     path: state.name,
-                    trust: verbTrust(state.trust ?? { kind: 'system-warn' }, entryRootOf(state.name)),
+                    ...verbOpts(state.trust ?? { kind: 'system-warn', textExt: [] }, entryRootOf(state.name)),
                 });
                 return report.ok
                     ? answer(renderWhyText(report.record))
@@ -501,7 +574,7 @@ function replCommand(state, line, read) {
                 ? 'keys' : 'canon' === state.mode ? 'canon' : 'json';
             const report = (0, aontu_1.get)(src, path, {
                 view, path: state.name,
-                trust: verbTrust(state.trust ?? { kind: 'system-warn' }, entryRootOf(state.name)),
+                ...verbOpts(state.trust ?? { kind: 'system-warn', textExt: [] }, entryRootOf(state.name)),
             });
             return report.ok
                 ? answer(report.out)
@@ -732,7 +805,7 @@ function vetOnce(args, trust) {
     const findings = [];
     for (const source of sources) {
         const report = (0, aontu_1.vet)(schemaSrc, source.src, {
-            trust: verbTrust(trust, entryRootOf(args.schema)),
+            ...verbOpts(trust, entryRootOf(args.schema)),
             at: args.at,
             closed: args.closed,
             partial: args.partial,
@@ -971,7 +1044,7 @@ function runSubsume(argv) {
         return 2;
     }
     const report = (0, aontu_1.subsume)(generalSrc, specificSrc, {
-        trust: verbTrust(trust, entryRootOf(args.general)),
+        ...verbOpts(trust, entryRootOf(args.general)),
         profile: args.profile,
         at: args.at,
         generalUrl: args.general,
@@ -1151,15 +1224,17 @@ function oldVersion(spec, file) {
 // The document's own compatibility declaration: `$.aontu_policy.compat`,
 // a disjunction whose default is the declared mode. Undefined when the
 // key is absent or does not spell a mode.
-function policyCompat(newSrc, path, trust) {
+function policyCompat(newSrc, path, include) {
     const aontu = new aontu_1.Aontu();
     const ctx = aontu.ctx({ collect: true });
     // The declaration is read by EVALUATING the document, so this leg
-    // runs the include resolver too and has to run it under the verb's
-    // capability -- a `breaking --trust none` that read its own mode
-    // through an unconfined resolver would confine the comparison and
-    // not the question (use-cases/REVIEW.md finding G).
-    const v = aontu.unify(newSrc, { path, ...(null == trust ? {} : { trust }) }, ctx);
+    // runs the include resolver too and has to run it under BOTH of the
+    // verb's include options -- a `breaking --trust none` that read its
+    // own mode through an unconfined resolver would confine the
+    // comparison and not the question (use-cases/REVIEW.md finding G),
+    // and one that took the capability alone read no mode at all when
+    // the declaration arrived through a `--text-ext` include.
+    const v = aontu.unify(newSrc, { path, ...(0, utility_1.includeOpts)(include) }, ctx);
     if (0 < ctx.err.length || true === v?.isNil) {
         return undefined;
     }
@@ -1252,7 +1327,7 @@ function runBreaking(argv) {
     // neither means backward, the index's framing (v1-valid documents
     // stay valid).
     const mode = args.mode ??
-        policyCompat(newSrc, args.file, verbTrust(trust, entryRootOf(args.file))) ??
+        policyCompat(newSrc, args.file, verbOpts(trust, entryRootOf(args.file))) ??
         'backward';
     if ('none' === mode) {
         // The document declares no compatibility promise: nothing to check.
@@ -1295,7 +1370,7 @@ function runBreaking(argv) {
             const oldPath = old.path;
             for (const check of checks) {
                 const report = (0, aontu_1.subsume)(check.general[0], check.specific[0], {
-                    trust: verbTrust(trust, entryRootOf(args.file)),
+                    ...verbOpts(trust, entryRootOf(args.file)),
                     at: args.at,
                     generalUrl: check.general[1],
                     specificUrl: check.specific[1],
@@ -1425,7 +1500,7 @@ function runTrim(argv) {
         return 2;
     }
     const report = (0, aontu_1.trimCheck)(src, {
-        path: files[0], trust: verbTrust(trust, entryRootOf(files[0])),
+        path: files[0], ...verbOpts(trust, entryRootOf(files[0])),
     });
     const text = 'json' === format
         ? renderTrimJson(report)
@@ -1476,9 +1551,40 @@ const REACHES_EXIT = {
     error: 4,
 };
 const VIEW_HELP = 'aontu view <kind> [options] <file>... (try --help)';
-const VIEW_KINDS = ['tree', 'matrix', 'graph', 'layer', 'sets', 'layers', 'ladder', 'poset'];
+const VIEW_KINDS = ['doc', 'lattice', 'tree', 'matrix', 'graph', 'layer', 'sets', 'layers',
+    'ladder', 'poset'];
 const VIEW_PROFILES = ['text', 'mermaid', 'dot', 'er', 'svg'];
 const VIEW_EDGES = ['upward', 'all', 'none'];
+// The styles the CLI accepts (VIEWS.0.md, "7. Styling"). `auto` is
+// here and NOT in ViewStyle: resolving it means knowing whether stdout
+// is a terminal, which is the CLI's to know and the library's never --
+// the same division err.ts already draws for the error frames.
+const VIEW_STYLES = ['auto', 'none', 'ansi', 'css'];
+// `--style auto` resolved, which only the CLI can do. The mechanism is
+// the PROFILE's and the library knows it -- an SVG carries its
+// stylesheet unless told not to, which is what makes a figure stand
+// alone. What the library cannot know is whether the DESTINATION is a
+// terminal, so that is the only thing decided here: escapes on the
+// text profile when stdout is a terminal and NO_COLOR is unset, the
+// same two conditions the error frames use. `undefined` leaves the
+// profile's own default in place.
+function viewStyleOf(asked, as) {
+    if (undefined !== asked && 'auto' !== asked) {
+        return asked;
+    }
+    // STDOUT'S OWN TERMINAL-NESS, and NO_COLOR read here rather than
+    // through colorActive(). The figure goes to STDOUT and the error
+    // frames go to STDERR, and they are not the same destination: main()
+    // has already called setColor for stderr, so asking colorActive()
+    // would answer the wrong question twice --- no escapes for
+    // `aontu view tree m.aon 2>/dev/null` at a terminal, and escapes
+    // into the pipe for `aontu view tree m.aon | less`. The NO_COLOR
+    // rule is the one no-color.org states and err.ts implements:
+    // set, to anything but empty, means no colour.
+    const no = process.env.NO_COLOR;
+    return 'text' === as && true === process.stdout.isTTY
+        && (null == no || '' === no) ? 'ansi' : undefined;
+}
 // The figure was drawn (0, `lossy` included: the loss report says
 // what it could not draw, and --strict is the gate on that), or the
 // document could not be drawn (4). An EMPTY figure is a drawing, not
@@ -1493,7 +1599,7 @@ const VIEW_EXIT = {
 const VIEW_USAGE_CODES = [
     'view_kind_unknown', 'view_profile_unknown', 'view_rows_exceeded',
     'view_at_required', 'view_sets_required', 'view_group_required',
-    'view_document_shape',
+    'view_document_shape', 'view_style_profile', 'view_style_unknown',
 ];
 const MOD_HELP = 'aontu mod tidy|verify|vendor|manifest [dir] (try --help)';
 // The module tooling (G6 phase 3, ts/src/mod-tool.ts). All LOCAL:
@@ -1552,7 +1658,8 @@ function runMod(argv) {
     const dir = rest[1] ?? '.';
     if ('get' === sub || 'publish' === sub) {
         process.stderr.write('aontu: mod ' + sub + ' needs a registry client, which this build ' +
-            'does not ship (docs/capability-review/g6-distribution.md)\n');
+            'does not ship; vendor the module by hand and run ' +
+            "'aontu mod tidy'\n");
         return 2;
     }
     if (!MOD_SUBS.includes(sub) || 2 < rest.length) {
@@ -1718,7 +1825,7 @@ function runRelations(argv) {
         return 2;
     }
     const report = (0, aontu_1.relationCheck)(src, {
-        path: files[0], trust: verbTrust(trust, entryRootOf(files[0])),
+        path: files[0], ...verbOpts(trust, entryRootOf(files[0])),
     });
     const text = 'json' === format
         ? renderRelationsJson(report)
@@ -1779,7 +1886,7 @@ function runReaches(argv) {
     }
     const report = (0, reach_1.reachCheck)(src, rest[0], rest[1], {
         path: rest[2], relation,
-        trust: verbTrust(trust, entryRootOf(rest[2])),
+        ...verbOpts(trust, entryRootOf(rest[2])),
     });
     const text = 'json' === format
         ? renderReachesJson(report)
@@ -1826,6 +1933,9 @@ function runView(argv) {
     const relations = [];
     const roots = [];
     const opts = {};
+    // The style ASKED FOR, which may be `auto` -- a word ViewStyle does
+    // not have, because resolving it is the CLI's job.
+    let style = undefined;
     // A flag that takes a value, read into `opts` by name.
     const valued = {
         '--as': 'as', '--at': 'at', '--order': 'order', '--group-by': 'groupBy',
@@ -1836,6 +1946,7 @@ function runView(argv) {
     const counted = {
         '--max-rows': 'maxRows', '--max-cols': 'maxCols',
         '--min-degree': 'minDegree', '--min-size': 'minSize',
+        '--depth': 'depth',
     };
     for (let i = 0; i < argv.length; i++) {
         const arg = argv[i];
@@ -1874,6 +1985,13 @@ function runView(argv) {
                 return 2;
             }
         }
+        else if ('--style' === arg) {
+            style = argv[++i];
+            if (null == style || !VIEW_STYLES.includes(style)) {
+                process.stderr.write(`aontu: --style needs one of ${VIEW_STYLES.join(', ')}\n`);
+                return 2;
+            }
+        }
         else if ('--check' === arg) {
             check = true;
         }
@@ -1915,9 +2033,24 @@ function runView(argv) {
             rest.push(arg);
         }
     }
+    // ESCAPES NEVER GO INTO A FILE. A pinned golden holding terminal
+    // control codes is not a golden anybody can read, and a byte
+    // comparison against one would fail on the reader's terminal
+    // settings. `auto` resolves to `none` there on its own; asking for
+    // `ansi` explicitly is a usage error rather than a silent downgrade,
+    // so a script that wanted colour is told where it went.
+    if ('ansi' === style && (undefined !== out || undefined !== opts.views)) {
+        process.stderr.write('aontu: --style ansi writes to a terminal, not to a file\n');
+        return 2;
+    }
     // THE VIEW DOCUMENT draws every figure a document declares, so it
     // names no kind: the declarations do, one each.
     if (undefined !== opts.views) {
+        // A declaration names its own profile, so the style is left to
+        // each figure's own default; `--style none` still reaches every
+        // one of them, which is how a host page that binds the CSS
+        // variables asks for eight figures without eight stylesheets.
+        opts.style = viewStyleOf(style, undefined);
         return runViewSet(rest, opts, trust, { format, check, strict, out });
     }
     if (2 > rest.length) {
@@ -1976,10 +2109,11 @@ function runView(argv) {
     }
     const report = (0, view_1.view)(srcs[0], {
         ...opts,
+        style: viewStyleOf(style, opts.as ?? (0, view_1.viewDefaultProfile)(kind)),
         kind,
         path: files[0],
         roots,
-        trust: verbTrust(trust, entryRootOf(files[0])),
+        ...verbOpts(trust, entryRootOf(files[0])),
         docs: files.slice(1).map((path, i) => ({ src: srcs[i + 1], path })),
     });
     if ('json' === format) {
@@ -2049,7 +2183,7 @@ function runViewSet(rest, opts, trust, how) {
         return 2;
     }
     const report = (0, view_1.viewSet)(src, {
-        ...opts, path: file, trust: verbTrust(trust, entryRootOf(file)),
+        ...opts, path: file, ...verbOpts(trust, entryRootOf(file)),
     });
     if ('json' === how.format) {
         process.stdout.write(renderViewSetJson(report) + '\n');
@@ -2246,7 +2380,7 @@ function runJsonSchema(argv) {
         return 2;
     }
     const report = (0, jsonschema_1.jsonSchema)(src, {
-        at, path: files[0], trust: verbTrust(trust, entryRootOf(files[0])),
+        at, path: files[0], ...verbOpts(trust, entryRootOf(files[0])),
     });
     if ('json' === format) {
         process.stdout.write((0, aontu_1.exactJSON)({
@@ -2329,8 +2463,7 @@ function runHash(argv) {
     }
     // The file's own directory is the include base, as every verb
     // resolves a named file (vet's aontuForPath rule).
-    const capability = verbTrust(trust, entryRootOf(files[0]));
-    const aontu = new aontu_1.Aontu(null == capability ? undefined : { trust: capability });
+    const aontu = new aontu_1.Aontu(verbOpts(trust, entryRootOf(files[0])));
     const ctx = aontu.ctx({ collect: true });
     const v = aontu.unify(src, { path: files[0] }, ctx);
     if (0 < ctx.err.length || true === v?.isNil) {
@@ -2434,7 +2567,7 @@ function runGet(argv) {
         return 2;
     }
     const report = (0, aontu_1.get)(src, path, {
-        view, depth, path: file, trust: verbTrust(trust, entryRootOf(file)),
+        view, depth, path: file, ...verbOpts(trust, entryRootOf(file)),
     });
     if ('json' === format) {
         process.stdout.write((0, aontu_1.exactJSON)({
@@ -2509,7 +2642,7 @@ function runWhy(argv) {
         return 2;
     }
     const report = (0, aontu_1.why)(src, path, {
-        path: file, trust: verbTrust(trust, entryRootOf(file)),
+        path: file, ...verbOpts(trust, entryRootOf(file)),
     });
     if ('json' === format) {
         process.stdout.write((0, aontu_1.exactJSON)({
@@ -2630,7 +2763,7 @@ function runSet(argv) {
         }
     }
     const report = (0, aontu_1.patch)(entrySrc, overlaySrc, assignments, {
-        trust: verbTrust(trust, entryRootOf(entry)),
+        ...verbOpts(trust, entryRootOf(entry)),
         entryPath: entry,
         overlayPath: overlayFile,
         inPlace,
@@ -2750,7 +2883,7 @@ function runAgentsMd(argv) {
     }
     const report = (0, aontu_1.agentsMd)(src, {
         name: files[0], path: files[0],
-        trust: verbTrust(trust, entryRootOf(files[0])),
+        ...verbOpts(trust, entryRootOf(files[0])),
     });
     if (!report.ok) {
         process.stderr.write(report.findings.map(renderFinding).join('\n') + '\n');
@@ -2796,6 +2929,116 @@ function runAgentsMd(argv) {
 // on the parity-probe discipline in AGENTS.md, which derives expected
 // spec values by piping BOTH CLIs and comparing. A truncated pipe there
 // reads as a port divergence.
+// ---------------------------------------------------------------------
+// The source formatter (docs/design/FMT.0.md): one agreed form, in the
+// tradition of gofmt. The verb prints, lists, checks, diffs or rewrites;
+// the form itself is the library's (ts/src/format.ts), and the two
+// ports agree on it row by row in test/spec/fmt.tsv.
+const FMT_HELP = 'aontu fmt [-w|-l|--check|-d] <file>... (try --help)';
+function runFmt(argv) {
+    const files = [];
+    const flags = { write: false, list: false, check: false, diff: false };
+    for (const arg of argv) {
+        if ('-h' === arg || '--help' === arg) {
+            process.stdout.write(HELP);
+            return 0;
+        }
+        if ('-w' === arg || '--write' === arg) {
+            flags.write = true;
+        }
+        else if ('-l' === arg || '--list' === arg) {
+            flags.list = true;
+        }
+        else if ('--check' === arg) {
+            flags.check = true;
+        }
+        else if ('-d' === arg || '--diff' === arg) {
+            flags.diff = true;
+        }
+        else if (arg.startsWith('-')) {
+            process.stderr.write(`aontu: unknown fmt option ${arg} (try --help)\n`);
+            return 2;
+        }
+        else {
+            files.push(arg);
+        }
+    }
+    if (0 === files.length) {
+        // Standard input: formatted onto standard output, or listed,
+        // checked and diffed under the name <stdin>. It cannot be written
+        // back.
+        if (flags.write) {
+            process.stderr.write(`aontu: --write needs a file\n${FMT_HELP}\n`);
+            return 2;
+        }
+        return new Promise((resolve) => {
+            let src = '';
+            process.stdin.setEncoding('utf8');
+            process.stdin.on('data', (d) => (src += d));
+            process.stdin.on('end', () => resolve(fmtOne('<stdin>', src, flags)));
+        });
+    }
+    // Several files onto standard output would be one stream nobody can
+    // split again (the note's X-6): the verb refuses unless an option
+    // says what to do with each.
+    if (1 < files.length && !fmtQuiet(flags)) {
+        process.stderr.write(`aontu: fmt prints one file; with ${files.length}, say --write, ` +
+            `--list, --check or --diff\n${FMT_HELP}\n`);
+        return 2;
+    }
+    let worst = 0;
+    for (const file of files) {
+        let src;
+        try {
+            src = (0, node_fs_1.readFileSync)(file, 'utf8');
+        }
+        catch (err) {
+            process.stderr.write(`aontu: cannot read ${err.path}: ${err.message}\n`);
+            return 2;
+        }
+        worst = Math.max(worst, fmtOne(file, src, flags));
+    }
+    return worst;
+}
+// An option that says what to do with a file that would change, in
+// place of printing it.
+function fmtQuiet(flags) {
+    return flags.write || flags.list || flags.check || flags.diff;
+}
+// One document: 0 printed, clean or done; 1 a --check that would
+// change; 2 a file that cannot be written; 4 a document that does not
+// format, with the finding that says why.
+function fmtOne(name, src, flags) {
+    const report = (0, format_1.format)(src, { path: name });
+    if ('error' === report.verdict) {
+        process.stderr.write(`aontu: ${name} was not formatted\n` +
+            report.errors.map(renderFinding).join('\n') + '\n');
+        return 4;
+    }
+    if (!fmtQuiet(flags)) {
+        process.stdout.write(report.text);
+        return 0;
+    }
+    if (!report.changed) {
+        return 0;
+    }
+    if (flags.list || flags.check) {
+        process.stdout.write(name + '\n');
+    }
+    if (flags.diff) {
+        process.stdout.write((0, format_1.unifiedDiff)(name, src, report.text));
+    }
+    if (flags.write) {
+        try {
+            (0, node_fs_1.writeFileSync)(name, report.text);
+        }
+        catch (err) {
+            process.stderr.write(`aontu: cannot write ${name}: ${err.message}\n`);
+            return 2;
+        }
+    }
+    return flags.check ? 1 : 0;
+}
 function finish(code) {
     process.exitCode = code;
 }
@@ -2803,16 +3046,16 @@ function finish(code) {
 // spelling, so the caller owns the usage error.
 function parseTrustArg(value) {
     if ('system' === value) {
-        return { kind: 'system' };
+        return { kind: 'system', textExt: [] };
     }
     if ('none' === value) {
-        return { kind: 'none' };
+        return { kind: 'none', textExt: [] };
     }
     if ('root' === value) {
-        return { kind: 'root' };
+        return { kind: 'root', textExt: [] };
     }
     if (value.startsWith('root:') && 'root:'.length < value.length) {
-        return { kind: 'root', dir: value.slice('root:'.length) };
+        return { kind: 'root', dir: value.slice('root:'.length), textExt: [] };
     }
     return undefined;
 }
@@ -2833,7 +3076,8 @@ function main(argv) {
     // overwritten twice. In a tool loop that reads as a passing
     // validation. Counting them is what lets the refusal below happen.
     const files = [];
-    let trust = { kind: 'system-warn' };
+    let trust = { kind: 'system-warn', textExt: [] };
+    let textExt = [];
     // The REPL's SESSION protocol (G7 phase 7): one JSON line per
     // answer, so a harness can drive the session. Named --jsonl rather
     // than the design's --json, which would read as the `:json` output
@@ -2860,6 +3104,9 @@ function main(argv) {
     if ('agentsmd' === argv[2]) {
         return finish(runAgentsMd(argv.slice(3)));
     }
+    if ('fmt' === argv[2]) {
+        return void Promise.resolve(runFmt(argv.slice(3))).then(finish);
+    }
     if ('set' === argv[2]) {
         return finish(runSet(argv.slice(3)));
     }
@@ -2927,7 +3174,16 @@ function main(argv) {
                 process.stderr.write('aontu: --include-root needs a directory\n');
                 return finish(2);
             }
-            trust = { kind: 'root', dir };
+            trust = { kind: 'root', dir, textExt };
+        }
+        else if ('--text-ext' === arg) {
+            const list = null == args[i + 1] ? undefined : parseTextExt(args[++i]);
+            if (null == list) {
+                process.stderr.write('aontu: --text-ext needs extensions, without dots' +
+                    ' (--text-ext md,sql)\n');
+                return finish(2);
+            }
+            textExt = [...textExt, ...list];
         }
         else if (arg.startsWith('-')) {
             process.stderr.write(`aontu: unknown option ${arg} (try --help)\n`);
@@ -2951,6 +3207,10 @@ function main(argv) {
             ' (try --help)\n');
         return finish(2);
     }
+    // The extensions ride with the capability from here on, so the three
+    // entry shapes below (file, REPL, stdin) each get them by threading
+    // the one value they already thread.
+    trust = { ...trust, textExt };
     const file = files[0];
     if (null != file) {
         finish(runFile(file, mode, trust));