aontu 0.56.0 → 0.58.0

package/src/cli.ts

@@ -12,7 +12,7 @@
 import { evalFailure } from './query'
 // __importStar downlevel helper, whose branches no supported Node takes.
 import {
-  mkdirSync, mkdtempSync, readFileSync, rmSync, statSync, writeFileSync,
+  existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, statSync, writeFileSync,
 } from 'node:fs'
 import { basename, dirname, join, resolve } from 'node:path'
 import { tmpdir } from 'node:os'
@@ -23,8 +23,15 @@ import {
   exactJSON, vet, subsume, trimCheck, relationCheck,
   hcanon, canonHash,
   get, why, patch, agentsMd,
+  render,
+  renderProfile,
 } from './aontu'
+import type { RenderCoverage, RenderReport } from './render'
+import { desugarTemplate, resugarTemplate, markerFor } from './template'
+import { outsideRoot } from './mcp'
 import { sarifReport } from './report-sarif'
+import { main as lspMain } from './lsp-server'
+import { main as mcpMain } from './mcp-server'
 import { jsonSchema } from './jsonschema'
 import { modTidy, modVerify, modVendor, modManifest } from './mod-tool'
 import type {
@@ -66,15 +73,21 @@ const HELP = `Usage: aontu [options] [file]
        aontu view <kind> [options] <file>...
        aontu view --views <path> [--check] [options] <file>
        aontu jsonschema [--at <path>] [--strict] [options] <file>
+       aontu render [--at <path>] [--profile <file>]... [--unit <path>]
+                    [--stdout | --out <dir> | --check <dir> | --coverage]
+                    [--coverage-at <path>] [--strict] <file>
+       aontu template [--resugar] [--check] [--marker <token>] <file>
        aontu hash [options] <file>
        aontu mod tidy|verify|vendor|manifest [options] [dir]
        aontu get <path> [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>...
+       aontu fmt [-w|-l|--check|-d|--lint] <file>...
+       aontu lsp
+       aontu mcp [--root <dir>]
 
-Evaluate an Aontu source file and print the result as JSON.
+Evaluate an aontu source file and print the result as JSON.
 With no file on an interactive terminal, start a REPL.
 With no file and piped input, read the source from stdin.
 
@@ -106,10 +119,10 @@ Mod options:
 
 Mod subcommands:
   tidy      Resolve the module closure by minimum version selection and
-            rewrite mod-lock.aon in canonical form
-  verify    Check every locked module still means what mod-lock.aon
+            rewrite aontu_meta/mod-lock.aon in canonical form
+  verify    Check every locked module still means what the lockfile
             pins, and change nothing (the CI gate; tidy rewrites)
-  vendor    Materialise the locked closure into aon_vendor/
+  vendor    Materialise the locked closure into aontu_meta/vendor/
   manifest  Print the OCI artifact a publish would push, gated on the
             breaking check against --against
 
@@ -256,6 +269,51 @@ View exit codes: 0 rendered, 1 --check mismatch or lossy under
 --strict, 2 usage or --max-rows exceeded, 4 the document does not stand
 up on its own, or a relation, root or path that names nothing.
 
+Render options:
+  --at <path>       Render the value at this path ($.a.b); the root by
+                    default
+  --profile <file>  A profile document, profile: {lang, ...}, vetted
+                    against aontu:profile; repeatable, one per language
+  --unit <path>     Render only the unit with this path
+  --stdout          One unit's bytes and nothing else (with --unit when
+                    the instance has several)
+  --out <dir>       Write every unit below dir, or nothing; never deletes
+  --check <dir>     Compare every unit with dir/<path>; drift is listed
+  --coverage        Report what the render read and what it did not:
+                    model paths no output consumed, and rendered
+                    declarations no rule produced. Writes nothing
+  --coverage-at <p> Measure coverage under this path only, instead of
+                    the document root
+  --strict          Refuse the opaque escapes (a text declaration, a raw
+                    block)
+  --format <f>      text (default) or json, the whole report; json
+                    carries the dispatch trace, one entry per emitted
+                    piece
+
+Render exit codes: 0 rendered, 1 lossy under --strict or drift under
+--check, 2 usage or I/O (a refused unit path included), 4 the document
+does not stand up or the instance is not aontu:code.
+
+A render entry file whose extension is not .aon is a TEMPLATE: a
+generator in the target's own syntax, whose marker lines carry aontu
+and whose other lines are output. It is desugared before it is
+evaluated, and --marker names the marker for a language the table does
+not know.
+
+Template options:
+  --resugar       The file is the canonical aontu; print the template
+                  form instead of reading one
+  --check         Desugar and resugar, and exit 1 if the file is not
+                  what the round trip answers
+  --marker <t>    The marker, when the extension does not name it
+                  (default //-, and #- --- /*- by extension)
+
+The template verb prints the canonical aontu form of a generator
+written in the target's own syntax: a marked line is aontu source, and
+every other line is a line of output.
+
+Template exit codes: 0 written, 1 --check drift, 2 usage or I/O.
+
 Set options:
   --entry <file>    The document the change is checked against
   --overlay <file>  The file the change is appended to (created if
@@ -290,12 +348,25 @@ Fmt options:
   --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
+  --lint          Report the style findings, key case and repeated
+                  shapes, on standard error, and print nothing else
+  --strict        With --lint, and exit 1 when there is a finding
 
 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.
+Fmt exit codes: 0 formatted or clean, 1 a --check file would change or
+a --strict finding, 2 usage, 4 a document does not parse.
+
+The lsp verb runs the language server over standard input and output
+(LSP: JSON-RPC with Content-Length framing) until the client exits;
+editors launch it with no arguments. The standalone aontu-lsp binary
+runs the same server.
+
+The mcp verb runs the Model Context Protocol server over standard
+input and output (newline-delimited JSON-RPC), confined below --root
+when one is given. It is part of the npm build, as the standalone
+aontu-mcp binary is.
 
 REPL commands:
   :help           Show REPL help
@@ -712,7 +783,7 @@ function runRepl(initialMode: Mode, jsonl: boolean, trust: TrustArg): void {
 
   if (!jsonl) {
     process.stdout.write(
-      `Aontu v${version()} REPL — :help for commands, :quit to exit\n`)
+      `aontu v${version()} REPL — :help for commands, :quit to exit\n`)
   }
   rl.prompt()
 
@@ -1994,6 +2065,16 @@ function runMod(argv: string[]): number {
     return 2
   }
 
+  // THE OLD LAYOUT IS NAMED, NOT READ. The lockfile and the vendored
+  // closure moved under aontu_meta/; a project that still carries them
+  // at its root would otherwise look untouched by any of these verbs,
+  // which is the one silence worth breaking.
+  if (existsSync(join(dir, 'aon_vendor')) || existsSync(join(dir, 'mod-lock.aon'))) {
+    process.stderr.write(
+      'aontu: aon_vendor/ and mod-lock.aon now live under aontu_meta/: ' +
+      'move them, or run aontu mod tidy and aontu mod vendor\n')
+  }
+
   // `--against` gates a manifest and means nothing to the other two;
   // accepting it there would say it had been honoured.
   if (null != against && 'manifest' !== sub) {
@@ -2830,6 +2911,439 @@ function runJsonSchema(argv: string[]): number {
     strict && 'lossy' === report.verdict ? 1 : 0
 }
 
+// ---------------------------------------------------------------------
+// THE RENDER VERB (docs/design/RENDER.0.md D8): evaluate a document,
+// vet the value at --at against aontu:code, fold code.units into bytes,
+// and put them where the flag says -- one unit on stdout, every unit
+// below --out (all or nothing), or compared against --check. Exit codes
+// mirror jsonschema's: 0 ok; 1 lossy under --strict or drift under
+// --check; 2 usage or I/O, a refused unit path included; 4 the
+// document does not stand up or the instance is not aontu:code.
+
+const RENDER_HELP =
+  'aontu render [--at <path>] [--profile <file>]... [--unit <path>] ' +
+  '[--stdout | --out <dir> | --check <dir> | --coverage] ' +
+  '[--coverage-at <path>] [--strict] [--marker <token>] <file> (try --help)'
+
+function runRender(argv: string[]): number {
+  const trusted = takeTrust(argv)
+  if (null == trusted) {
+    return 2
+  }
+  argv = trusted.argv
+  const trust = trusted.trust
+  const files: string[] = []
+  const profileFiles: string[] = []
+  let format: SubsumeFormat = 'text'
+  let at: string | undefined = undefined
+  let unit: string | undefined = undefined
+  let out: string | undefined = undefined
+  let check: string | undefined = undefined
+  let toStdout = false
+  let strict = false
+  let coverage = false
+  let coverageAt: string | undefined = undefined
+  let marker: string | undefined = undefined
+
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i]
+    if ('-h' === arg || '--help' === arg) {
+      process.stdout.write(HELP)
+      return 0
+    }
+    if ('--format' === arg) {
+      const f = argv[++i]
+      if ('text' !== f && 'json' !== f) {
+        process.stderr.write('aontu: --format needs text or json\n')
+        return 2
+      }
+      format = f
+    }
+    else if ('--at' === arg) {
+      at = argv[++i]
+      if (null == at) {
+        process.stderr.write('aontu: --at needs a path\n')
+        return 2
+      }
+    }
+    else if ('--unit' === arg) {
+      unit = argv[++i]
+      if (null == unit) {
+        process.stderr.write('aontu: --unit needs a unit path\n')
+        return 2
+      }
+    }
+    else if ('--profile' === arg) {
+      const pf = argv[++i]
+      if (null == pf) {
+        process.stderr.write('aontu: --profile needs a file\n')
+        return 2
+      }
+      profileFiles.push(pf)
+    }
+    else if ('--out' === arg) {
+      out = argv[++i]
+      if (null == out) {
+        process.stderr.write('aontu: --out needs a directory\n')
+        return 2
+      }
+    }
+    else if ('--check' === arg) {
+      check = argv[++i]
+      if (null == check) {
+        process.stderr.write('aontu: --check needs a directory\n')
+        return 2
+      }
+    }
+    else if ('--stdout' === arg) {
+      toStdout = true
+    }
+    else if ('--coverage' === arg) {
+      coverage = true
+    }
+    else if ('--marker' === arg) {
+      marker = argv[++i]
+      if (null == marker) {
+        process.stderr.write('aontu: --marker needs a token\n')
+        return 2
+      }
+    }
+    else if ('--coverage-at' === arg) {
+      coverageAt = argv[++i]
+      if (null == coverageAt) {
+        process.stderr.write('aontu: --coverage-at needs a path\n')
+        return 2
+      }
+    }
+    else if ('--strict' === arg) {
+      strict = true
+    }
+    else if (arg.startsWith('-')) {
+      process.stderr.write(
+        `aontu: unknown render option ${arg} (try --help)\n`)
+      return 2
+    }
+    else {
+      files.push(arg)
+    }
+  }
+
+  if (1 !== files.length) {
+    process.stderr.write(`aontu: render needs one file\n${RENDER_HELP}\n`)
+    return 2
+  }
+  const modes = [toStdout, undefined !== out, undefined !== check, coverage]
+    .filter((on) => on).length
+  if (1 < modes) {
+    process.stderr.write(
+      'aontu: render takes one of --stdout, --out, --check or --coverage\n')
+    return 2
+  }
+  // A NARROWER MEASURE NEEDS SOMETHING TO NARROW. `--coverage-at`
+  // without `--coverage` asks for a report the run does not compute,
+  // and answering silently would be the wrong half of the request.
+  if (undefined !== coverageAt && !coverage) {
+    process.stderr.write('aontu: --coverage-at needs --coverage\n')
+    return 2
+  }
+
+  let src: string
+  try {
+    src = readFileSync(files[0], 'utf8')
+  }
+  catch (err: any) {
+    process.stderr.write(`aontu: cannot read ${err.path}: ${err.message}\n`)
+    return 2
+  }
+
+  // THE ENTRY MAY BE A TEMPLATE (TEMPLATE.0.md; P8), and its EXTENSION
+  // decides, as an include's extension decides what the include is
+  // (ADR-012): a generator is a file in the target's own syntax, so it
+  // carries the target's extension and never `.aon`. Desugared here
+  // rather than anywhere deeper, because a template is an entry
+  // spelling and not a value: an include is still aontu.
+  if (!files[0].endsWith('.aon')) {
+    src = desugarTemplate(src, marker ?? markerFor(files[0]))
+  }
+
+  // THE PROFILES (D5): each --profile file is a document whose root is
+  // `profile: {lang, ...}`, evaluated under the verb's trust and vetted
+  // against aontu:profile as a settled value before the fold reads it
+  // (renderProfile, which also fills the defaults). Two files claiming
+  // one lang is a usage error: the fold could not choose.
+  const profiles: any[] = []
+  const langs = new Map<string, string>()
+  for (const pf of profileFiles) {
+    let text: string
+    try {
+      text = readFileSync(pf, 'utf8')
+    }
+    catch (err: any) {
+      process.stderr.write(`aontu: cannot read ${err.path}: ${err.message}\n`)
+      return 2
+    }
+    const loaded = renderProfile(text,
+      { path: resolve(pf), ...verbOpts(trust, entryRootOf(pf)) })
+    if (undefined !== loaded.errors) {
+      process.stderr.write(loaded.errors.map(renderFinding).join('\n') + '\n')
+      return 4
+    }
+    const profile = loaded.profile
+    const prev = langs.get(profile.lang)
+    if (undefined !== prev) {
+      process.stderr.write(
+        `aontu: two profiles claim ${profile.lang}: ${prev} and ${pf}\n`)
+      return 2
+    }
+    langs.set(profile.lang, pf)
+    profiles.push(profile)
+  }
+
+  const report = render(src, {
+    at, unit, strict, profiles, path: files[0],
+    coverage, coverageAt,
+    // THE JSON REPORT CARRIES THE TRACE (D9), which is what the shape
+    // there has always said; a text run computes it only when the
+    // coverage report needs it.
+    trace: 'json' === format,
+    ...verbOpts(trust, entryRootOf(files[0])),
+  })
+
+  if ('json' === format) {
+    process.stdout.write(exactJSON({
+      aontu: { version: version(), verb: 'render' },
+      verdict: report.verdict,
+      units: report.units,
+      lossy: report.lossy,
+      ...(null == report.errors ? {} : { errors: report.errors }),
+      ...(null == report.trace ? {} : { trace: report.trace }),
+      ...(null == report.coverage ? {} : { coverage: report.coverage }),
+    }, 2) + '\n')
+    return renderExit(report, 0)
+  }
+  if ('error' === report.verdict) {
+    process.stderr.write(
+      (report.errors as VetFinding[]).map(renderFinding).join('\n') + '\n')
+    return renderExit(report, 0)
+  }
+
+  let drift = 0
+  if (toStdout) {
+    // ONE UNIT'S BYTES AND NOTHING ELSE, so the output can be piped
+    // into a formatter or a file.
+    if (1 !== report.units.length) {
+      process.stderr.write(
+        'aontu: --stdout needs exactly one unit, and the instance has ' +
+        `${report.units.length}; --unit names one\n`)
+      return 2
+    }
+    process.stdout.write(report.units[0].text)
+  }
+  else if (undefined !== out) {
+    // EVERY UNIT BELOW <dir>, OR NOTHING: every unit rendered first
+    // (the report above), and no file touched unless all did. The
+    // directory is realpath-confined; a unit path is already a relative
+    // descent (render_path refuses the rest), and the check here is
+    // against the symlink inside it. render never deletes.
+    for (const u of report.units) {
+      if (outsideRoot(out, resolve(out, u.path))) {
+        process.stderr.write(`aontu: ${u.path} escapes ${out}\n`)
+        return 2
+      }
+    }
+    for (const u of report.units) {
+      const full = resolve(out, u.path)
+      try {
+        mkdirSync(dirname(full), { recursive: true })
+        writeFileSync(full, u.text, 'utf8')
+      }
+      catch (err: any) {
+        process.stderr.write(`aontu: cannot write ${u.path}: ${err.message}\n`)
+        return 2
+      }
+      process.stderr.write(`wrote ${u.path}\n`)
+    }
+  }
+  else if (undefined !== check) {
+    // RENDER AND COMPARE: a unit whose bytes differ from the file at
+    // <dir>/<path>, or whose file is absent, is drift, listed by path.
+    // The CI form.
+    for (const u of report.units) {
+      let have: string | undefined = undefined
+      try {
+        have = readFileSync(resolve(check, u.path), 'utf8')
+      }
+      catch {
+        // Absent is drift, reported below.
+      }
+      if (undefined === have) {
+        drift++
+        process.stderr.write(`aontu: ${u.path} is missing from ${check}\n`)
+      }
+      else if (have !== u.text) {
+        drift++
+        process.stderr.write(`aontu: ${u.path} differs from the rendered unit\n`)
+      }
+    }
+  }
+  else if (coverage) {
+    // THE COVERAGE REPORT (P7), one line per finding and a count at
+    // the end: dead model first, then the declarations no rule
+    // produced. A clean report is the count line alone.
+    const cov = report.coverage as RenderCoverage
+    for (const d of cov.dead) {
+      process.stdout.write(`dead: ${d}\n`)
+    }
+    for (const u of cov.unruled) {
+      process.stdout.write(`unruled: ${u.unit} ${u.path}\n`)
+    }
+    process.stdout.write(
+      `coverage: ${cov.read.length} path(s) read, ${cov.dead.length} ` +
+      `no output consumed, ${cov.unruled.length} declaration(s) ` +
+      'no rule produced\n')
+  }
+  else {
+    // THE SUMMARY: one line per unit -- its path, its language and its
+    // size -- since several units have no one text to print.
+    for (const u of report.units) {
+      process.stdout.write(`${u.path}\t${u.lang}\t${u.text.length} bytes\n`)
+    }
+  }
+  for (const l of report.lossy) {
+    process.stderr.write(
+      `lossy: ${l.unit} ${l.path} tier ${l.tier} ${l.construct}: ${l.reason}\n`)
+  }
+  return renderExit(report, drift)
+}
+
+// D8's exit table over a report: a refused unit path is usage (2), a
+// strict refusal is lossy (1), any other error is the document's (4);
+// drift under --check is 1.
+function renderExit(report: RenderReport, drift: number): number {
+  if ('error' === report.verdict) {
+    const errors = report.errors as VetFinding[]
+    if (errors.every((f) => 'render_path' === f.code)) {
+      return 2
+    }
+    if (errors.every((f) => 'render_strict' === f.code)) {
+      return 1
+    }
+    return 4
+  }
+  return 0 < drift ? 1 : 0
+}
+
+
+// ---------------------------------------------------------------------
+// THE TEMPLATE SURFACE (docs/design/TEMPLATE.0.md; RENDER.0.md P8): the
+// two transforms and the round trip between them. `render` reads a
+// template directly, by its extension; this verb is for seeing the
+// canonical form, for writing one by hand and sugaring it, and for the
+// check that keeps a committed template and its meaning in agreement.
+
+const TEMPLATE_HELP =
+  'aontu template [--resugar] [--check] [--marker <token>] <file> (try --help)'
+
+function runTemplate(argv: string[]): number {
+  const files: string[] = []
+  let resugar = false
+  let check = false
+  let marker: string | undefined = undefined
+
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i]
+    if ('-h' === arg || '--help' === arg) {
+      process.stdout.write(HELP)
+      return 0
+    }
+    else if ('--resugar' === arg) {
+      resugar = true
+    }
+    else if ('--check' === arg) {
+      check = true
+    }
+    else if ('--marker' === arg) {
+      marker = argv[++i]
+      if (null == marker) {
+        process.stderr.write('aontu: --marker needs a token\n')
+        return 2
+      }
+    }
+    else if (arg.startsWith('-')) {
+      process.stderr.write(
+        `aontu: unknown template option ${arg} (try --help)\n`)
+      return 2
+    }
+    else {
+      files.push(arg)
+    }
+  }
+
+  if (1 !== files.length) {
+    process.stderr.write(`aontu: template needs one file\n${TEMPLATE_HELP}\n`)
+    return 2
+  }
+  // THE TWO ARE DIRECTIONS, NOT MODES THAT COMPOSE: `--check` reads a
+  // template and asks whether the round trip answers it back, and
+  // `--resugar` reads the canonical form instead. A run cannot be both
+  // at once, because the file is one thing or the other.
+  if (resugar && check) {
+    process.stderr.write(
+      'aontu: template takes one of --resugar or --check\n')
+    return 2
+  }
+
+  let src: string
+  try {
+    src = readFileSync(files[0], 'utf8')
+  }
+  catch (err: any) {
+    process.stderr.write(`aontu: cannot read ${err.path}: ${err.message}\n`)
+    return 2
+  }
+
+  const mark = marker ?? markerFor(files[0])
+
+  if (check) {
+    // THE ROUND TRIP IS THE CHECK (D6): the file held to the spelling
+    // the two transforms answer. What that names is a marker line the
+    // transform would not have written -- one without its space, or one
+    // whose aontu is indented after the marker rather than before it,
+    // since the marker keeps its own indentation. It does NOT name a
+    // changed body line: a template's whitespace is output, so a
+    // trimmed trailing space is still a valid template and it is
+    // `render --check` against the committed files that catches it.
+    // The first line that differs is the report, since a whole diff of
+    // a generator is the file again.
+    const back = resugarTemplate(desugarTemplate(src, mark), mark)
+    if (back === src) {
+      return 0
+    }
+    const want = back.split('\n')
+    const have = src.split('\n')
+    let n = 0
+    while (n < want.length && n < have.length && want[n] === have[n]) {
+      n++
+    }
+    // THE TWO ARE THE SAME LENGTH, always: each transform maps one
+    // line to one line and applies the same trailing-newline rule, so
+    // `back` has as many lines as `src`. The loop above therefore stops
+    // at a real difference rather than by running out of either -- an
+    // equal prefix all the way to the end IS `back === src`, which
+    // returned above. So both indexes are in range here.
+    process.stderr.write(
+      `aontu: ${files[0]}:${n + 1} is not what the round trip answers\n` +
+      `  have: ${JSON.stringify(have[n])}\n` +
+      `  want: ${JSON.stringify(want[n])}\n`)
+    return 1
+  }
+
+  process.stdout.write(resugar ?
+    resugarTemplate(src, mark) : desugarTemplate(src, mark))
+  return 0
+}
+
+
 // ---------------------------------------------------------------------
 // The canon-hash (G6 phase 1): the pin an agent, a lockfile or a
 // registry stores for "this module, this meaning". The hash covers the
@@ -3421,13 +3935,17 @@ function runAgentsMd(argv: string[]): number {
 // 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)'
+const FMT_HELP = 'aontu fmt [-w|-l|--check|-d|--lint] <file>... (try --help)'
 
-type FmtFlags = { write: boolean, list: boolean, check: boolean, diff: boolean }
+type FmtFlags = {
+  write: boolean, list: boolean, check: boolean, diff: boolean, lint: boolean, strict: boolean,
+}
 
 function runFmt(argv: string[]): number | Promise<number> {
   const files: string[] = []
-  const flags: FmtFlags = { write: false, list: false, check: false, diff: false }
+  const flags: FmtFlags = {
+    write: false, list: false, check: false, diff: false, lint: false, strict: false,
+  }
 
   for (const arg of argv) {
     if ('-h' === arg || '--help' === arg) {
@@ -3446,6 +3964,13 @@ function runFmt(argv: string[]): number | Promise<number> {
     else if ('-d' === arg || '--diff' === arg) {
       flags.diff = true
     }
+    else if ('--lint' === arg) {
+      flags.lint = true
+    }
+    else if ('--strict' === arg) {
+      flags.lint = true
+      flags.strict = true
+    }
     else if (arg.startsWith('-')) {
       process.stderr.write(`aontu: unknown fmt option ${arg} (try --help)\n`)
       return 2
@@ -3477,12 +4002,29 @@ function runFmt(argv: string[]): number | Promise<number> {
   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`)
+      `--list, --check, --diff or --lint\n${FMT_HELP}\n`)
     return 2
   }
 
   let worst = 0
   for (const file of files) {
+    // FMT FORMATS AONTU SOURCE, AND THE EXTENSION SAYS WHAT A FILE IS
+    // (ADR-012's rule, and the one `render` reads a template by).
+    // A TEMPLATE FILE IS NOT AONTU (docs/design/TEMPLATE.0.md; P8):
+    // its marker lines are fragments of a document and its other lines
+    // are the target's, so there is nothing here to format that would
+    // not also rewrite the output. Refused rather than attempted, and
+    // refused BY NAME rather than by a parse failure, because a `#-`
+    // template parses: `#` opens a comment, so every marker line
+    // vanishes and what is left is read as a document that was never
+    // written. The verb answered `0` over one, having understood none
+    // of it.
+    if (!/[.](aon|aontu)$/.test(file)) {
+      process.stderr.write(
+        `aontu: ${file} is not aontu source (.aon, .aontu); a generator ` +
+        'written in the target\'s own syntax is aontu template\'s\n')
+      return 2
+    }
     let src: string
     try {
       src = readFileSync(file, 'utf8')
@@ -3496,28 +4038,34 @@ function runFmt(argv: string[]): number | Promise<number> {
   return worst
 }
 
-// An option that says what to do with a file that would change, in
-// place of printing it.
+// An option that says what to do with a file, in place of printing
+// it: what to do when its form would change, or the lint.
 function fmtQuiet(flags: FmtFlags): boolean {
-  return flags.write || flags.list || flags.check || flags.diff
+  return flags.write || flags.list || flags.check || flags.diff || flags.lint
 }
 
 // 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.
+// change, or a --strict finding; 2 a file that cannot be written; 4 a
+// document that does not format, with the finding that says why. The
+// style findings go to standard error, one line each, in the shape
+// every linter prints: `file:line:col: rule: message`.
 function fmtOne(name: string, src: string, flags: FmtFlags): number {
-  const report = format(src, { path: name })
+  const report = format(src, { path: name, lint: flags.lint })
   if ('error' === report.verdict) {
     process.stderr.write(`aontu: ${name} was not formatted\n` +
       report.errors.map(renderFinding).join('\n') + '\n')
     return 4
   }
+  for (const f of report.findings) {
+    process.stderr.write(`${name}:${f.line}:${f.col}: ${f.rule}: ${f.message}\n`)
+  }
+  const strict = flags.strict && 0 < report.findings.length ? 1 : 0
   if (!fmtQuiet(flags)) {
     process.stdout.write(report.text)
     return 0
   }
   if (!report.changed) {
-    return 0
+    return strict
   }
   if (flags.list || flags.check) {
     process.stdout.write(name + '\n')
@@ -3534,7 +4082,49 @@ function fmtOne(name: string, src: string, flags: FmtFlags): number {
       return 2
     }
   }
-  return flags.check ? 1 : 0
+  return flags.check ? 1 : strict
+}
+
+
+// ---------------------------------------------------------------------
+// The servers as verbs: `aontu lsp` runs the language server and
+// `aontu mcp` the MCP server over the CLI's own streams, so the one
+// command on PATH is the editor's and the agent's server too, and a
+// version manager (docs/design/ENV.0.md) has one thing to resolve. The
+// standalone bins (aontu-lsp, aontu-mcp) run the same functions. Each
+// server owns its exit; the CLI only dispatches. The pair is a
+// parameter of main so that a test can see the dispatch without a
+// server taking the test's own stdin.
+
+type Servers = {
+  lsp: () => void
+  mcp: (argv: string[]) => void
+}
+
+// The real pair takes the process's own stdin and stdout, which no
+// in-process test can lend it; the executable-entry tests in
+// cli.test.ts run each through a child process instead, so these two
+// lines are excluded from the in-process count, as the stdio wiring
+// of lsp-server.ts is.
+/* node:coverage ignore next 4 */
+const SERVERS: Servers = {
+  lsp: () => void lspMain(),
+  mcp: (argv) => void mcpMain(undefined, undefined, undefined, undefined, argv),
+}
+
+// undefined: the server took the process; a number: an answer the CLI
+// gives itself, --help or a usage error.
+function runLsp(argv: string[], servers: Servers): number | undefined {
+  for (const arg of argv) {
+    if ('-h' === arg || '--help' === arg) {
+      process.stdout.write(HELP)
+      return 0
+    }
+    process.stderr.write(`aontu: lsp takes no arguments (try --help)\n`)
+    return 2
+  }
+  servers.lsp()
+  return undefined
 }
 
 
@@ -3562,7 +4152,7 @@ function parseTrustArg(value: string): TrustArg | undefined {
 }
 
 
-function main(argv: string[]): void {
+function main(argv: string[], servers: Servers = SERVERS): void {
   // COLOUR OFF WHEN THE DESTINATION IS NOT A TERMINAL. Error frames
   // hardcoded their ANSI escapes, so a piped report and a `--jsonl`
   // answer carried terminal control codes into whatever read them (the
@@ -3612,6 +4202,13 @@ function main(argv: string[]): void {
   if ('fmt' === argv[2]) {
     return void Promise.resolve(runFmt(argv.slice(3))).then(finish)
   }
+  if ('lsp' === argv[2]) {
+    const code = runLsp(argv.slice(3), servers)
+    return undefined === code ? undefined : finish(code)
+  }
+  if ('mcp' === argv[2]) {
+    return servers.mcp(argv.slice(3))
+  }
 
   if ('set' === argv[2]) {
     return finish(runSet(argv.slice(3)))
@@ -3641,6 +4238,14 @@ function main(argv: string[]): void {
     return finish(runJsonSchema(argv.slice(3)))
   }
 
+  if ('render' === argv[2]) {
+    return finish(runRender(argv.slice(3)))
+  }
+
+  if ('template' === argv[2]) {
+    return finish(runTemplate(argv.slice(3)))
+  }
+
   if ('reaches' === argv[2]) {
     return finish(runReaches(argv.slice(3)))
   }
@@ -3747,7 +4352,7 @@ function main(argv: string[]): void {
   else {
     runStdin(mode, trust).then((code) => finish(code))
   }
-} /* node:coverage ignore next 16 */
+} /* node:coverage ignore next 18 */
 
 
 // No require.main guard here: bin/aontu.js is the executable entry and
@@ -3759,6 +4364,8 @@ export {
   runReaches,
   runView,
   runJsonSchema,
+  runRender,
+  runTemplate,
   runMod,
   runHash, runGet,
   runWhy, renderWhyText, runSet, runAgentsMd, runFmt,