clyops-doc 0.0.0-stage → 0.6.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Dan VerWeire
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,58 @@
-# Temporary Holding Version
+# clyops-doc
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Documentation from any [clyops](https://github.com/wankdanker/clyops) tool's `--help-json-schema`: a
+man page, Markdown or a standalone HTML page. It only reads the schema, so it works for a tool in
+any of the nine languages, compiled ones included, and needs nothing from the tool itself.
+
+```sh
+npm install -g clyops-doc
+
+mytool --help-json-schema | clyops-doc > mytool.1                 # man page (the default)
+mytool --help-json-schema | clyops-doc --format markdown > mytool.md
+mytool --help-json-schema | clyops-doc --format html > mytool.html
+man -l mytool.1
+```
+
+`clyops-doc` is a clyops tool too, so it documents itself:
+`clyops-doc --help-json-schema | clyops-doc | man -l -`.
+
+| Option | |
+| --- | --- |
+| `-f, --format` | `man` (default), `markdown` or `html` |
+| `-n, --name` | How the tool is run, default the schema's name; for a dispatcher path, `--name "mytool media to-pcm"` |
+| `-s, --section` | Manual section for the man page header (default `1`) |
+| `-V, --version` | Version shown in the header |
+| `-d, --date` | Date shown in the header, YYYY-MM-DD (default today, or `SOURCE_DATE_EPOCH` for reproducible builds) |
+| `--schema FILE` | Read the schema from a file instead of stdin |
+
+Each option can also be set as `CLYOPS_DOC_<OPTION>`. Input that isn't a clyops schema (`"clyops": 1`)
+is rejected with exit status 1.
+
+## What goes where
+
+| Section | From the schema |
+| --- | --- |
+| NAME, SYNOPSIS | the name, the first sentence of `description`, and a usage line per command, as help prints it |
+| DESCRIPTION | `description` |
+| ARGUMENTS, OPTIONS | each argument and option with its default, accepted values ([spec §5](https://github.com/wankdanker/clyops/blob/main/spec/SPEC.md#5-validation-rules)), whether it repeats or is a secret, and its environment variable |
+| COMMANDS | for a program with commands, a subsection per command with the options it inherits and the nearest declared effects, stdin, stdout and roles |
+| STREAMS | `stdin`, `stdout` and [roles](https://github.com/wankdanker/clyops/blob/main/spec/SPEC.md#14-roles-on-file-descriptors) with their types |
+| NOTES | effects, option relationships and required commands |
+| ENVIRONMENT | each option's variable, the precedence rule, `CLYOPS_FDS` when there are roles, `CLYOPS_SILENT`, `CLYOPS_MAX_WIDTH` and `NO_COLOR` |
+| EXIT STATUS | 0, 1, and the tool's own |
+| EXAMPLES | `epilog` |
+
+Man pages use the plain `man(7)` macros, which groff and mandoc both render; text is escaped so a
+line can't start a request and option dashes are `\-`, so they copy and paste. The HTML page is
+self-contained, with every value escaped.
+
+## As a library
+
+```js
+import { document, buildDoc, renderMarkdown } from 'clyops-doc';
+
+const page = document(schema, 'man', { name: 'mytool', version: '1.2.0' });
+const md = renderMarkdown(buildDoc(schema)); // or build the document once and render it several ways
+```
+
+ESM only, Node 20+.

package/dist/cli.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+export {};
+//# sourceMappingURL=cli.d.ts.map

package/dist/cli.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":""}

package/dist/cli.js

@@ -0,0 +1,38 @@
+#!/usr/bin/env node
+// clyops-doc: a clyops tool's --help-json-schema on stdin, as a man page, Markdown or HTML.
+import { Cli, die } from 'clyops';
+import { readFileSync } from 'node:fs';
+import { document } from './index.js';
+import { defaultDate } from './model.js';
+const cli = new Cli({ name: 'clyops-doc' });
+cli.setDescription('Render a clyops tool\'s --help-json-schema as documentation: a man page, Markdown or HTML. It reads the schema on stdin, so it works with any clyops tool, compiled ones included.');
+cli.setEpilog('Examples:\n  mytool --help-json-schema | clyops-doc > mytool.1\n  mytool --help-json-schema | clyops-doc --format markdown > mytool.md\n  clyops-doc --schema schema.json --name "mytool media to-pcm" --format html > to-pcm.html\n  clyops-doc --help-json-schema | clyops-doc | man -l -');
+cli.setEffects('read-only');
+cli.setStdin('The tool\'s --help-json-schema output (unless --schema is given)', 'application/json');
+cli.setStdout('The documentation, in the format --format names', 'text/plain');
+cli.opt('CLYOPS_DOC_FORMAT', 'format', 'f', 'man', 'Output format', 'Output', 'choice:man,markdown,html');
+cli.opt('CLYOPS_DOC_NAME', 'name', 'n', 'optional', 'How the tool is run (default: the schema\'s name), e.g. "mytool media to-pcm"', 'Output');
+cli.opt('CLYOPS_DOC_SECTION', 'section', 's', '1', 'Manual section for the man page header', 'Output', 'regex:^[1-9][a-z]*$');
+cli.opt('CLYOPS_DOC_VERSION', 'version', 'V', 'optional', 'Version shown in the header', 'Output');
+cli.opt('CLYOPS_DOC_DATE', 'date', 'd', 'optional', 'Date shown in the header (default: today, or SOURCE_DATE_EPOCH)', 'Output', 'date:YYYY-MM-DD');
+cli.opt('CLYOPS_DOC_SCHEMA', 'schema', '', 'optional', 'Read the schema from this file instead of stdin', 'Input', 'file:readable');
+const args = cli.run();
+let schema;
+try {
+    const text = readFileSync(args.CLYOPS_DOC_SCHEMA ?? 0, 'utf8');
+    schema = JSON.parse(text);
+}
+catch (err) {
+    die(1, 'Could not read the schema: %s', err.message);
+}
+try {
+    process.stdout.write(document(schema, args.CLYOPS_DOC_FORMAT, {
+        name: args.CLYOPS_DOC_NAME ?? undefined,
+        section: args.CLYOPS_DOC_SECTION,
+        version: args.CLYOPS_DOC_VERSION ?? undefined,
+        date: args.CLYOPS_DOC_DATE ?? defaultDate(),
+    }));
+}
+catch (err) {
+    die(1, '%s', err.message);
+}

package/dist/index.d.ts

@@ -0,0 +1,8 @@
+export * from './model.js';
+export * from './render.js';
+import type { Schema } from 'clyops-schema';
+import { type DocOptions } from './model.js';
+import { type Format } from './render.js';
+/** A schema's documentation in `format` (default man). Throws for input that isn't a clyops schema. */
+export declare function document(schema: Schema, format?: Format, opts?: DocOptions): string;
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,cAAc,YAAY,CAAC;AAC3B,cAAc,aAAa,CAAC;AAE5B,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,eAAe,CAAC;AAC5C,OAAO,EAAY,KAAK,UAAU,EAAE,MAAM,YAAY,CAAC;AACvD,OAAO,EAAU,KAAK,MAAM,EAAE,MAAM,aAAa,CAAC;AAElD,uGAAuG;AACvG,wBAAgB,QAAQ,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,GAAE,MAAc,EAAE,IAAI,GAAE,UAAe,GAAG,MAAM,CAE9F"}

package/dist/index.js

@@ -0,0 +1,9 @@
+// clyops-doc: documentation (man, Markdown, HTML) from a clyops tool's --help-json-schema.
+export * from './model.js';
+export * from './render.js';
+import { buildDoc } from './model.js';
+import { render } from './render.js';
+/** A schema's documentation in `format` (default man). Throws for input that isn't a clyops schema. */
+export function document(schema, format = 'man', opts = {}) {
+    return render(buildDoc(schema, opts), format);
+}

package/dist/model.d.ts

@@ -0,0 +1,99 @@
+import type { Schema, SchemaArgument, SchemaOption, SchemaRole, SchemaStream } from 'clyops-schema';
+/** One piece of a section. Terms are option names, commands and the like: code in every format. */
+export type Block = {
+    kind: 'p';
+    text: string;
+} | {
+    kind: 'pre';
+    text: string;
+} | {
+    kind: 'dl';
+    items: {
+        term: string;
+        text: string;
+    }[];
+} | {
+    kind: 'h';
+    text: string;
+};
+/** A top-level section, e.g. OPTIONS. */
+export interface Section {
+    /** Upper-case title, as in man pages: NAME, SYNOPSIS, OPTIONS. */
+    title: string;
+    /** The section's content, in order. */
+    blocks: Block[];
+}
+/** The document for one program: its header and sections. */
+export interface Doc {
+    /** How the program is run, e.g. `mytool` or `mytool media to-pcm`. */
+    name: string;
+    /** Manual section, e.g. `1`. */
+    section: string;
+    /** Version shown in the header, or empty. */
+    version: string;
+    /** Date shown in the header (YYYY-MM-DD). */
+    date: string;
+    /** The first line of the program's description. */
+    summary: string;
+    /** The sections, in order. */
+    sections: Section[];
+}
+/** What a renderer needs to know beyond the schema. */
+export interface DocOptions {
+    /** How the program is run (default: the schema's `script`). */
+    name?: string;
+    /** Manual section (default `1`). */
+    section?: string;
+    /** Version for the header. */
+    version?: string;
+    /** Date for the header, YYYY-MM-DD (default: today). */
+    date?: string;
+}
+/** A runnable level: a program without commands, or a leaf command, with what it inherits. */
+export interface Leaf {
+    /** The command words after the program name, e.g. ['db', 'migrate']; empty for the program. */
+    words: string[];
+    /** The level's own description. */
+    description: string;
+    /** Positional arguments. */
+    arguments: SchemaArgument[];
+    /** Its own options, then those it inherits, nearest first. */
+    options: SchemaOption[];
+    /** The nearest declared effects. */
+    effects: string[];
+    /** The nearest declared stdin. */
+    stdin: SchemaStream | null;
+    /** The nearest declared stdout. */
+    stdout: SchemaStream | null;
+    /** Its roles (spec section 14), the nearest declaration of each name winning. */
+    roles: SchemaRole[];
+    /** Option relationships from the program down. */
+    constraints: {
+        type: string;
+        options: string[];
+    }[];
+    /** Required commands from the program down. */
+    requiredCommands: {
+        command: string;
+        description: string;
+        installHint: string;
+    }[];
+}
+/** Every runnable level of a schema, the way clyops-tools expands commands (spec section 1.7). */
+export declare function leaves(schema: Schema): Leaf[];
+/** The usage line, as help prints it (spec section 7). */
+export declare function synopsis(name: string, leaf: Leaf): string;
+/** An option's label: `-s, --long=<value>`, or `--long` for a flag. */
+export declare function optionLabel(o: SchemaOption): string;
+/** An option's description with its notes, as help annotates it (spec section 7). */
+export declare function optionText(o: SchemaOption): string;
+/** The first sentence of a description (its first line at most), for the NAME line. */
+export declare function firstSentence(text: string): string;
+/** Today in UTC, or SOURCE_DATE_EPOCH's date for reproducible builds. */
+export declare function defaultDate(env?: NodeJS.ProcessEnv): string;
+/**
+ * The document for a schema. Throws for input that isn't a clyops schema (`"clyops": 1`, with
+ * description, options and arguments).
+ */
+export declare function buildDoc(schema: Schema, opts?: DocOptions): Doc;
+//# sourceMappingURL=model.d.ts.map

package/dist/model.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"model.d.ts","sourceRoot":"","sources":["../src/model.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,MAAM,EAAE,cAAc,EAAc,YAAY,EAAE,UAAU,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AAEhH,mGAAmG;AACnG,MAAM,MAAM,KAAK,GACb;IAAoC,IAAI,EAAE,GAAG,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GAC7D;IAAkD,IAAI,EAAE,KAAK,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GAC7E;IAAqD,IAAI,EAAE,IAAI,CAAC;IAAC,KAAK,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,EAAE,CAAA;CAAE,GAC1G;IAAqD,IAAI,EAAE,GAAG,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,CAAC;AAEnF,yCAAyC;AACzC,MAAM,WAAW,OAAO;IACtB,kEAAkE;IAClE,KAAK,EAAE,MAAM,CAAC;IACd,uCAAuC;IACvC,MAAM,EAAE,KAAK,EAAE,CAAC;CACjB;AAED,6DAA6D;AAC7D,MAAM,WAAW,GAAG;IAClB,sEAAsE;IACtE,IAAI,EAAE,MAAM,CAAC;IACb,gCAAgC;IAChC,OAAO,EAAE,MAAM,CAAC;IAChB,6CAA6C;IAC7C,OAAO,EAAE,MAAM,CAAC;IAChB,6CAA6C;IAC7C,IAAI,EAAE,MAAM,CAAC;IACb,mDAAmD;IACnD,OAAO,EAAE,MAAM,CAAC;IAChB,8BAA8B;IAC9B,QAAQ,EAAE,OAAO,EAAE,CAAC;CACrB;AAED,uDAAuD;AACvD,MAAM,WAAW,UAAU;IACzB,+DAA+D;IAC/D,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,oCAAoC;IACpC,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,8BAA8B;IAC9B,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,wDAAwD;IACxD,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED,8FAA8F;AAC9F,MAAM,WAAW,IAAI;IACnB,+FAA+F;IAC/F,KAAK,EAAE,MAAM,EAAE,CAAC;IAChB,mCAAmC;IACnC,WAAW,EAAE,MAAM,CAAC;IACpB,4BAA4B;IAC5B,SAAS,EAAE,cAAc,EAAE,CAAC;IAC5B,8DAA8D;IAC9D,OAAO,EAAE,YAAY,EAAE,CAAC;IACxB,oCAAoC;IACpC,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,kCAAkC;IAClC,KAAK,EAAE,YAAY,GAAG,IAAI,CAAC;IAC3B,mCAAmC;IACnC,MAAM,EAAE,YAAY,GAAG,IAAI,CAAC;IAC5B,iFAAiF;IACjF,KAAK,EAAE,UAAU,EAAE,CAAC;IACpB,kDAAkD;IAClD,WAAW,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,EAAE,CAAA;KAAE,EAAE,CAAC;IACnD,+CAA+C;IAC/C,gBAAgB,EAAE;QAAE,OAAO,EAAE,MAAM,CAAC;QAAC,WAAW,EAAE,MAAM,CAAC;QAAC,WAAW,EAAE,MAAM,CAAA;KAAE,EAAE,CAAC;CACnF;AAED,kGAAkG;AAClG,wBAAgB,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,EAAE,CAgC7C;AAED,0DAA0D;AAC1D,wBAAgB,QAAQ,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,IAAI,GAAG,MAAM,CAIzD;AAED,uEAAuE;AACvE,wBAAgB,WAAW,CAAC,CAAC,EAAE,YAAY,GAAG,MAAM,CAGnD;AAED,qFAAqF;AACrF,wBAAgB,UAAU,CAAC,CAAC,EAAE,YAAY,GAAG,MAAM,CASlD;AAgDD,uFAAuF;AACvF,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAIlD;AAED,yEAAyE;AACzE,wBAAgB,WAAW,CAAC,GAAG,GAAE,MAAM,CAAC,UAAwB,GAAG,MAAM,CAIxE;AAED;;;GAGG;AACH,wBAAgB,QAAQ,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,GAAE,UAAe,GAAG,GAAG,CAqEnE"}

package/dist/model.js

@@ -0,0 +1,208 @@
+// A clyops schema (spec section 8) as a small document: sections of paragraphs, definition lists
+// and preformatted text, which each output format renders.
+import { describeRule } from 'clyops';
+/** Every runnable level of a schema, the way clyops-tools expands commands (spec section 1.7). */
+export function leaves(schema) {
+    const out = [];
+    const visit = (chain, words) => {
+        const node = chain[chain.length - 1];
+        if (node.commands?.length) {
+            for (const child of node.commands)
+                visit([...chain, child], [...words, child.name]);
+            return;
+        }
+        const nearest = (pick, empty = () => false) => {
+            for (let i = chain.length - 1; i >= 0; i--) {
+                const v = pick(chain[i]);
+                if (v !== undefined && v !== null && !empty(v))
+                    return v;
+            }
+            return undefined;
+        };
+        const roles = new Map();
+        for (const level of chain)
+            for (const r of level.roles ?? [])
+                roles.set(r.name, r);
+        out.push({
+            words,
+            description: node.description,
+            arguments: node.arguments,
+            options: [...chain].reverse().flatMap((s) => s.options),
+            effects: nearest((s) => s.effects, (v) => v.length === 0) ?? [],
+            stdin: nearest((s) => s.stdin) ?? null,
+            stdout: nearest((s) => s.stdout) ?? null,
+            roles: [...roles.values()],
+            constraints: chain.flatMap((s) => s.constraints ?? []),
+            requiredCommands: chain.flatMap((s) => s.requiredCommands),
+        });
+    };
+    visit([schema], []);
+    return out;
+}
+/** The usage line, as help prints it (spec section 7). */
+export function synopsis(name, leaf) {
+    const parts = [name, ...leaf.words];
+    for (const a of leaf.arguments)
+        parts.push(a.isVariadic ? `[<${a.name}...>]` : a.required ? `<${a.name}>` : `[<${a.name}>]`);
+    return [...parts, '[OPTIONS]'].join(' ');
+}
+/** An option's label: `-s, --long=<value>`, or `--long` for a flag. */
+export function optionLabel(o) {
+    const long = `--${o.name}${o.isFlag ? '' : '=<value>'}`;
+    return o.shortName ? `-${o.shortName}, ${long}` : long;
+}
+/** An option's description with its notes, as help annotates it (spec section 7). */
+export function optionText(o) {
+    const notes = [];
+    if (o.required)
+        notes.push('required');
+    if (o.isArray)
+        notes.push('repeatable');
+    if (o.secret)
+        notes.push('secret: prefer the environment');
+    if (o.default && !o.isFlag)
+        notes.push(`default: ${o.default}`);
+    if (o.validation)
+        notes.push(`accepts: ${describeRule(o.validation)}`);
+    notes.push(`environment: ${o.variableName}`);
+    return `${o.description}${o.description ? ' ' : ''}(${notes.join('; ')})`;
+}
+function argumentText(a) {
+    const notes = [];
+    if (a.isVariadic)
+        notes.push('any number');
+    else if (!a.required)
+        notes.push(a.default ? `default: ${a.default}` : 'optional');
+    if (a.validation)
+        notes.push(`accepts: ${describeRule(a.validation)}`);
+    return notes.length ? `${a.description}${a.description ? ' ' : ''}(${notes.join('; ')})` : a.description;
+}
+function stream(s) {
+    return [s.description, s.contentType && `(${s.contentType})`].filter(Boolean).join(' ') || 'Declared, without a description.';
+}
+const CONSTRAINT = {
+    exclusive: (o) => `At most one of ${o.map((n) => `--${n}`).join(', ')}.`,
+    requires: (o) => `Giving --${o[0]} requires ${o.slice(1).map((n) => `--${n}`).join(', ')}.`,
+    oneOf: (o) => `At least one of ${o.map((n) => `--${n}`).join(', ')}.`,
+};
+const EFFECTS = {
+    'read-only': 'changes nothing',
+    idempotent: 'running it twice is the same as once',
+    destructive: 'deletes or overwrites things',
+    network: 'talks to the outside world',
+};
+/** A leaf's parts: its arguments, options and streams as definition lists, and notes as text. */
+function leafParts(leaf) {
+    const dl = (items) => (items.length ? { kind: 'dl', items } : undefined);
+    const streams = [
+        ...(leaf.stdin ? [{ term: 'stdin', text: stream(leaf.stdin) }] : []),
+        ...(leaf.stdout ? [{ term: 'stdout', text: stream(leaf.stdout) }] : []),
+        ...leaf.roles.map((r) => ({ term: `${r.direction === 'in' ? 'input' : 'output'} role ${r.name}`, text: stream(r) })),
+    ];
+    const notes = [
+        ...(leaf.effects.length ? [`Effects: ${leaf.effects.map((e) => `${e} (${EFFECTS[e] ?? e})`).join(', ')}.`] : []),
+        ...leaf.constraints.map((c) => CONSTRAINT[c.type]?.(c.options) ?? ''),
+        ...leaf.requiredCommands.map((r) => `Needs ${r.command} on PATH: ${r.description}${r.installHint ? ` (${r.installHint})` : ''}.`),
+    ].filter(Boolean);
+    return {
+        args: dl(leaf.arguments.map((a) => ({ term: a.isVariadic ? `<${a.name}...>` : `<${a.name}>`, text: argumentText(a) }))),
+        options: dl(leaf.options.filter((o) => o.name !== 'help').map((o) => ({ term: optionLabel(o), text: optionText(o) }))),
+        streams: dl(streams),
+        notes: notes.map((text) => ({ kind: 'p', text })),
+    };
+}
+/** The first sentence of a description (its first line at most), for the NAME line. */
+export function firstSentence(text) {
+    const line = text.split('\n')[0].trim();
+    const end = line.search(/[.!?](\s|$)/);
+    return end < 0 ? line : line.slice(0, end);
+}
+/** Today in UTC, or SOURCE_DATE_EPOCH's date for reproducible builds. */
+export function defaultDate(env = process.env) {
+    const epoch = Number(env.SOURCE_DATE_EPOCH);
+    const when = Number.isFinite(epoch) && env.SOURCE_DATE_EPOCH ? new Date(epoch * 1000) : new Date();
+    return when.toISOString().slice(0, 10);
+}
+/**
+ * The document for a schema. Throws for input that isn't a clyops schema (`"clyops": 1`, with
+ * description, options and arguments).
+ */
+export function buildDoc(schema, opts = {}) {
+    if (!schema || typeof schema !== 'object' || schema.clyops !== 1 || !Array.isArray(schema.options) || !Array.isArray(schema.arguments)) {
+        throw new Error('not a clyops schema (expected "clyops": 1 with options and arguments)');
+    }
+    const name = opts.name || schema.script;
+    const all = leaves(schema);
+    const program = all.length === 1 && all[0].words.length === 0;
+    const summary = firstSentence(schema.description || '');
+    const sections = [];
+    sections.push({ title: 'NAME', blocks: [{ kind: 'p', text: summary ? `${name} - ${summary}` : name }] });
+    sections.push({ title: 'SYNOPSIS', blocks: [{ kind: 'pre', text: all.map((l) => synopsis(name, l)).join('\n') }] });
+    if (schema.description)
+        sections.push({ title: 'DESCRIPTION', blocks: schema.description.split(/\n{2,}/).map((text) => ({ kind: 'p', text })) });
+    if (program) {
+        const { args, options, streams, notes } = leafParts(all[0]);
+        if (args)
+            sections.push({ title: 'ARGUMENTS', blocks: [args] });
+        if (options)
+            sections.push({ title: 'OPTIONS', blocks: [options] });
+        if (streams)
+            sections.push({ title: 'STREAMS', blocks: [streams] });
+        if (notes.length)
+            sections.push({ title: 'NOTES', blocks: notes });
+    }
+    else {
+        // One subsection per runnable command, with what it inherits.
+        const blocks = [];
+        for (const leaf of all) {
+            const { args, options, streams, notes } = leafParts(leaf);
+            blocks.push({ kind: 'h', text: [name, ...leaf.words].join(' ') });
+            if (leaf.description)
+                blocks.push({ kind: 'p', text: leaf.description });
+            blocks.push({ kind: 'pre', text: synopsis(name, leaf) });
+            for (const [label, part] of [['Arguments', args], ['Options', options], ['Streams', streams]]) {
+                if (part)
+                    blocks.push({ kind: 'p', text: `${label}:` }, part);
+            }
+            blocks.push(...notes);
+        }
+        sections.push({ title: 'COMMANDS', blocks });
+    }
+    // Every option's variable, once, in the order first seen.
+    const env = new Map();
+    for (const leaf of all)
+        for (const o of leaf.options)
+            if (o.name !== 'help' && !env.has(o.variableName))
+                env.set(o.variableName, `Sets --${o.name}.${o.secret ? ' A secret: set it here rather than on the command line.' : ''}`);
+    const anyRoles = all.some((l) => l.roles.length);
+    sections.push({
+        title: 'ENVIRONMENT',
+        blocks: [
+            { kind: 'p', text: 'An option given on the command line takes precedence over the config file, which takes precedence over the environment, which takes precedence over the default.' },
+            {
+                kind: 'dl',
+                items: [
+                    ...[...env].map(([term, text]) => ({ term, text })),
+                    ...(anyRoles ? [{ term: 'CLYOPS_FDS', text: 'Maps roles to file descriptors, e.g. meta:3,progress:4; set by the program that runs it. Without it, roles are not written.' }] : []),
+                    { term: 'CLYOPS_SILENT', text: 'true suppresses informational and warning messages.' },
+                    { term: 'CLYOPS_MAX_WIDTH', text: 'The width help is wrapped to (default 100).' },
+                    { term: 'NO_COLOR', text: 'Set to turn off colored log levels.' },
+                ],
+            },
+        ],
+    });
+    sections.push({
+        title: 'EXIT STATUS',
+        blocks: [{
+                kind: 'dl',
+                items: [
+                    { term: '0', text: 'Success, or help was shown.' },
+                    { term: '1', text: 'Invalid arguments, options or input, a missing required command, or a failure the program reports.' },
+                    { term: 'other', text: 'Defined by the program.' },
+                ],
+            }],
+    });
+    if (schema.epilog)
+        sections.push({ title: 'EXAMPLES', blocks: [{ kind: 'pre', text: schema.epilog.replace(/\n+$/, '') }] });
+    return { name, section: opts.section || '1', version: opts.version || '', date: opts.date || defaultDate(), summary, sections };
+}

package/dist/render.d.ts

@@ -0,0 +1,21 @@
+import type { Doc } from './model.js';
+/** Output formats. */
+export type Format = 'man' | 'markdown' | 'html';
+/** Text for a troff line: backslashes and dashes escaped, a leading `.` or `'` made literal. */
+export declare function troff(text: string): string;
+/** The document as a man(7) page. */
+export declare function renderMan(doc: Doc): string;
+/**
+ * Text that renders as itself in CommonMark: characters that can start markup escaped, and nothing
+ * else, so the Markdown stays readable (`DRY_RUN`, `(default: 1)`).
+ */
+export declare function markdownText(text: string): string;
+/** The document as Markdown. */
+export declare function renderMarkdown(doc: Doc): string;
+/** Text with HTML's special characters escaped. */
+export declare function htmlText(text: string): string;
+/** The document as a standalone HTML page. */
+export declare function renderHtml(doc: Doc): string;
+/** The document in `format`. */
+export declare function render(doc: Doc, format: Format): string;
+//# sourceMappingURL=render.d.ts.map

package/dist/render.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"render.d.ts","sourceRoot":"","sources":["../src/render.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAS,GAAG,EAAE,MAAM,YAAY,CAAC;AAE7C,sBAAsB;AACtB,MAAM,MAAM,MAAM,GAAG,KAAK,GAAG,UAAU,GAAG,MAAM,CAAC;AAMjD,gGAAgG;AAChG,wBAAgB,KAAK,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAQ1C;AAoBD,qCAAqC;AACrC,wBAAgB,SAAS,CAAC,GAAG,EAAE,GAAG,GAAG,MAAM,CAgB1C;AAMD;;;GAGG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAWjD;AA4BD,gCAAgC;AAChC,wBAAgB,cAAc,CAAC,GAAG,EAAE,GAAG,GAAG,MAAM,CAS/C;AAMD,mDAAmD;AACnD,wBAAgB,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAE7C;AAyBD,8CAA8C;AAC9C,wBAAgB,UAAU,CAAC,GAAG,EAAE,GAAG,GAAG,MAAM,CAsB3C;AAED,gCAAgC;AAChC,wBAAgB,MAAM,CAAC,GAAG,EAAE,GAAG,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,CAEvD"}

package/dist/render.js

@@ -0,0 +1,157 @@
+// ---------------------------------------------------------------------------
+// man(7): plain .TH .SH .SS .PP .TP .nf/.fi macros, which groff and mandoc both render.
+// ---------------------------------------------------------------------------
+/** Text for a troff line: backslashes and dashes escaped, a leading `.` or `'` made literal. */
+export function troff(text) {
+    return text
+        .split('\n')
+        .map((line) => {
+        const escaped = line.replace(/\\/g, '\\e').replace(/-/g, '\\-');
+        return /^[.']/.test(escaped) ? `\\&${escaped}` : escaped;
+    })
+        .join('\n');
+}
+/** A macro argument: escaped, and quoted so spaces stay in it. */
+function arg(text) {
+    return `"${troff(text).replace(/"/g, '\\(dq')}"`;
+}
+function manBlock(b) {
+    switch (b.kind) {
+        case 'p':
+            return ['.PP', troff(b.text)];
+        case 'h':
+            return [`.SS ${arg(b.text)}`];
+        case 'pre':
+            return ['.PP', '.nf', '.RS 4', troff(b.text), '.RE', '.fi'];
+        case 'dl':
+            return b.items.flatMap((i) => ['.TP', `\\fB${troff(i.term)}\\fR`, troff(i.text)]);
+    }
+}
+/** The document as a man(7) page. */
+export function renderMan(doc) {
+    const title = doc.name.toUpperCase().replace(/\s+/g, '-');
+    const lines = [
+        `.\\" Generated by clyops-doc from ${doc.name} --help-json-schema.`,
+        `.TH ${arg(title)} ${arg(doc.section)} ${arg(doc.date)} ${arg([doc.name, doc.version].filter(Boolean).join(' '))} ${arg('User Commands')}`,
+    ];
+    for (const s of doc.sections) {
+        lines.push(`.SH ${arg(s.title)}`);
+        // NAME is one line, "name \- summary", without a paragraph macro (man(7)).
+        if (s.title === 'NAME') {
+            lines.push(troff(`${doc.name}${doc.summary ? ` - ${doc.summary}` : ''}`));
+            continue;
+        }
+        for (const b of s.blocks)
+            lines.push(...manBlock(b));
+    }
+    return lines.join('\n') + '\n';
+}
+// ---------------------------------------------------------------------------
+// Markdown (CommonMark)
+// ---------------------------------------------------------------------------
+/**
+ * Text that renders as itself in CommonMark: characters that can start markup escaped, and nothing
+ * else, so the Markdown stays readable (`DRY_RUN`, `(default: 1)`).
+ */
+export function markdownText(text) {
+    return text
+        .split('\n')
+        .map((line) => line
+        .replace(/[\\`*[\]<>|]/g, '\\$&')
+        // _ only emphasises at a word boundary.
+        .replace(/(^|[^A-Za-z0-9])_|_(?=[^A-Za-z0-9]|$)/g, (m) => m.replace('_', '\\_'))
+        // A block marker at the start of a line: a heading, quote, list item or rule.
+        .replace(/^(\s*)([#>+=-]|\d+[.)])/, '$1\\$2'))
+        .join('\n');
+}
+/** Inline code that may itself contain backticks. */
+function code(text) {
+    const run = Math.max(0, ...(text.match(/`+/g) ?? []).map((m) => m.length)) + 1;
+    const fence = '`'.repeat(run);
+    return run > 1 ? `${fence} ${text} ${fence}` : `${fence}${text}${fence}`;
+}
+function fenced(text) {
+    const run = Math.max(2, ...(text.match(/`+/g) ?? []).map((m) => m.length)) + 1;
+    const fence = '`'.repeat(run);
+    return [fence, text, fence];
+}
+function markdownBlock(b) {
+    switch (b.kind) {
+        case 'p':
+            return [markdownText(b.text), ''];
+        case 'h':
+            return [`### ${code(b.text)}`, ''];
+        case 'pre':
+            return [...fenced(b.text), ''];
+        case 'dl':
+            return [...b.items.map((i) => `- ${code(i.term)}: ${markdownText(i.text)}`), ''];
+    }
+}
+/** The document as Markdown. */
+export function renderMarkdown(doc) {
+    const lines = [`# ${code(doc.name)}`, ''];
+    const header = [doc.version && `Version ${doc.version}`, doc.date].filter(Boolean).join(' · ');
+    if (header)
+        lines.push(`_${markdownText(header)}_`, '');
+    for (const s of doc.sections) {
+        lines.push(`## ${s.title}`, '');
+        for (const b of s.blocks)
+            lines.push(...markdownBlock(b));
+    }
+    return lines.join('\n').replace(/\n+$/, '\n');
+}
+// ---------------------------------------------------------------------------
+// HTML: one standalone page, everything escaped.
+// ---------------------------------------------------------------------------
+/** Text with HTML's special characters escaped. */
+export function htmlText(text) {
+    return text.replace(/[&<>"']/g, (c) => ({ '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;', "'": '&#39;' })[c]);
+}
+const slug = (text) => text.toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-|-$/g, '');
+function htmlBlock(b) {
+    switch (b.kind) {
+        case 'p':
+            return `<p>${htmlText(b.text)}</p>`;
+        case 'h':
+            return `<h3 id="${slug(b.text)}"><code>${htmlText(b.text)}</code></h3>`;
+        case 'pre':
+            return `<pre><code>${htmlText(b.text)}</code></pre>`;
+        case 'dl':
+            return `<dl>\n${b.items.map((i) => `<dt><code>${htmlText(i.term)}</code></dt>\n<dd>${htmlText(i.text)}</dd>`).join('\n')}\n</dl>`;
+    }
+}
+const STYLE = `body{font:16px/1.55 system-ui,sans-serif;max-width:46rem;margin:2rem auto;padding:0 1rem;color:#1d1f21;background:#fff}
+code,pre{font-family:ui-monospace,SFMono-Regular,Menlo,monospace;font-size:.9em}
+pre{background:#f4f5f6;padding:.8rem 1rem;overflow-x:auto;border-radius:4px}
+h2{margin-top:2rem;font-size:1.05rem;letter-spacing:.04em}
+dt{margin-top:.6rem;font-weight:600}dd{margin:.2rem 0 0 1.5rem}
+.meta{color:#5b6168}
+@media (prefers-color-scheme:dark){body{color:#e3e5e8;background:#17191c}pre{background:#23262a}.meta{color:#9aa1a9}}`;
+/** The document as a standalone HTML page. */
+export function renderHtml(doc) {
+    const header = [doc.version && `Version ${doc.version}`, doc.date].filter(Boolean).join(' · ');
+    const body = doc.sections
+        .map((s) => `<section id="${slug(s.title)}">\n<h2>${htmlText(s.title)}</h2>\n${s.blocks.map(htmlBlock).join('\n')}\n</section>`)
+        .join('\n');
+    return `<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<meta name="generator" content="clyops-doc">
+<title>${htmlText(doc.name)}(${htmlText(doc.section)})</title>
+<style>${STYLE}</style>
+</head>
+<body>
+<header><h1><code>${htmlText(doc.name)}</code></h1>${header ? `<p class="meta">${htmlText(header)}</p>` : ''}</header>
+<main>
+${body}
+</main>
+</body>
+</html>
+`;
+}
+/** The document in `format`. */
+export function render(doc, format) {
+    return format === 'man' ? renderMan(doc) : format === 'markdown' ? renderMarkdown(doc) : renderHtml(doc);
+}

package/package.json

@@ -1,6 +1,52 @@
 {
   "name": "clyops-doc",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.6.0",
+  "description": "Documentation (man pages, Markdown, HTML) from any clyops tool's --help-json-schema.",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/wankdanker/clyops.git",
+    "directory": "apps/doc"
+  },
+  "keywords": [
+    "clyops",
+    "man",
+    "manpage",
+    "documentation",
+    "markdown",
+    "cli"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "type": "module",
+  "bin": {
+    "clyops-doc": "./dist/cli.js"
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src"
+  ],
+  "dependencies": {
+    "clyops": "0.6.0",
+    "clyops-schema": "0.6.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "typescript": "^5.6.0"
+  },
+  "homepage": "https://clyops.io/applications.html",
+  "scripts": {
+    "build": "tsc -p tsconfig.json && chmod +x dist/cli.js",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "node --test test/*.test.mjs"
+  }
 }

package/src/cli.ts

@@ -0,0 +1,40 @@
+#!/usr/bin/env node
+// clyops-doc: a clyops tool's --help-json-schema on stdin, as a man page, Markdown or HTML.
+import { Cli, die } from 'clyops';
+import { readFileSync } from 'node:fs';
+import type { Schema } from 'clyops-schema';
+import { document } from './index.js';
+import { defaultDate } from './model.js';
+import type { Format } from './render.js';
+
+const cli = new Cli({ name: 'clyops-doc' });
+cli.setDescription('Render a clyops tool\'s --help-json-schema as documentation: a man page, Markdown or HTML. It reads the schema on stdin, so it works with any clyops tool, compiled ones included.');
+cli.setEpilog('Examples:\n  mytool --help-json-schema | clyops-doc > mytool.1\n  mytool --help-json-schema | clyops-doc --format markdown > mytool.md\n  clyops-doc --schema schema.json --name "mytool media to-pcm" --format html > to-pcm.html\n  clyops-doc --help-json-schema | clyops-doc | man -l -');
+cli.setEffects('read-only');
+cli.setStdin('The tool\'s --help-json-schema output (unless --schema is given)', 'application/json');
+cli.setStdout('The documentation, in the format --format names', 'text/plain');
+cli.opt('CLYOPS_DOC_FORMAT',  'format',  'f', 'man',      'Output format',                                                  'Output', 'choice:man,markdown,html');
+cli.opt('CLYOPS_DOC_NAME',    'name',    'n', 'optional', 'How the tool is run (default: the schema\'s name), e.g. "mytool media to-pcm"', 'Output');
+cli.opt('CLYOPS_DOC_SECTION', 'section', 's', '1',        'Manual section for the man page header',                         'Output', 'regex:^[1-9][a-z]*$');
+cli.opt('CLYOPS_DOC_VERSION', 'version', 'V', 'optional', 'Version shown in the header',                                    'Output');
+cli.opt('CLYOPS_DOC_DATE',    'date',    'd', 'optional', 'Date shown in the header (default: today, or SOURCE_DATE_EPOCH)', 'Output', 'date:YYYY-MM-DD');
+cli.opt('CLYOPS_DOC_SCHEMA',  'schema',  '',  'optional', 'Read the schema from this file instead of stdin',               'Input',  'file:readable');
+const args = cli.run();
+
+let schema: Schema;
+try {
+  const text = readFileSync((args.CLYOPS_DOC_SCHEMA as string | null) ?? 0, 'utf8');
+  schema = JSON.parse(text) as Schema;
+} catch (err) {
+  die(1, 'Could not read the schema: %s', (err as Error).message);
+}
+try {
+  process.stdout.write(document(schema, args.CLYOPS_DOC_FORMAT as Format, {
+    name: (args.CLYOPS_DOC_NAME as string | null) ?? undefined,
+    section: args.CLYOPS_DOC_SECTION as string,
+    version: (args.CLYOPS_DOC_VERSION as string | null) ?? undefined,
+    date: (args.CLYOPS_DOC_DATE as string | null) ?? defaultDate(),
+  }));
+} catch (err) {
+  die(1, '%s', (err as Error).message);
+}

package/src/index.ts

@@ -0,0 +1,12 @@
+// clyops-doc: documentation (man, Markdown, HTML) from a clyops tool's --help-json-schema.
+export * from './model.js';
+export * from './render.js';
+
+import type { Schema } from 'clyops-schema';
+import { buildDoc, type DocOptions } from './model.js';
+import { render, type Format } from './render.js';
+
+/** A schema's documentation in `format` (default man). Throws for input that isn't a clyops schema. */
+export function document(schema: Schema, format: Format = 'man', opts: DocOptions = {}): string {
+  return render(buildDoc(schema, opts), format);
+}

package/src/model.ts

@@ -0,0 +1,266 @@
+// A clyops schema (spec section 8) as a small document: sections of paragraphs, definition lists
+// and preformatted text, which each output format renders.
+import { describeRule } from 'clyops';
+import type { Schema, SchemaArgument, SchemaBody, SchemaOption, SchemaRole, SchemaStream } from 'clyops-schema';
+
+/** One piece of a section. Terms are option names, commands and the like: code in every format. */
+export type Block =
+  | { /** A paragraph of plain text. */ kind: 'p'; text: string }
+  | { /** Text shown as is, in a fixed-width font. */ kind: 'pre'; text: string }
+  | { /** A list of terms, each with its description. */ kind: 'dl'; items: { term: string; text: string }[] }
+  | { /** A subsection heading, e.g. one per command. */ kind: 'h'; text: string };
+
+/** A top-level section, e.g. OPTIONS. */
+export interface Section {
+  /** Upper-case title, as in man pages: NAME, SYNOPSIS, OPTIONS. */
+  title: string;
+  /** The section's content, in order. */
+  blocks: Block[];
+}
+
+/** The document for one program: its header and sections. */
+export interface Doc {
+  /** How the program is run, e.g. `mytool` or `mytool media to-pcm`. */
+  name: string;
+  /** Manual section, e.g. `1`. */
+  section: string;
+  /** Version shown in the header, or empty. */
+  version: string;
+  /** Date shown in the header (YYYY-MM-DD). */
+  date: string;
+  /** The first line of the program's description. */
+  summary: string;
+  /** The sections, in order. */
+  sections: Section[];
+}
+
+/** What a renderer needs to know beyond the schema. */
+export interface DocOptions {
+  /** How the program is run (default: the schema's `script`). */
+  name?: string;
+  /** Manual section (default `1`). */
+  section?: string;
+  /** Version for the header. */
+  version?: string;
+  /** Date for the header, YYYY-MM-DD (default: today). */
+  date?: string;
+}
+
+/** A runnable level: a program without commands, or a leaf command, with what it inherits. */
+export interface Leaf {
+  /** The command words after the program name, e.g. ['db', 'migrate']; empty for the program. */
+  words: string[];
+  /** The level's own description. */
+  description: string;
+  /** Positional arguments. */
+  arguments: SchemaArgument[];
+  /** Its own options, then those it inherits, nearest first. */
+  options: SchemaOption[];
+  /** The nearest declared effects. */
+  effects: string[];
+  /** The nearest declared stdin. */
+  stdin: SchemaStream | null;
+  /** The nearest declared stdout. */
+  stdout: SchemaStream | null;
+  /** Its roles (spec section 14), the nearest declaration of each name winning. */
+  roles: SchemaRole[];
+  /** Option relationships from the program down. */
+  constraints: { type: string; options: string[] }[];
+  /** Required commands from the program down. */
+  requiredCommands: { command: string; description: string; installHint: string }[];
+}
+
+/** Every runnable level of a schema, the way clyops-tools expands commands (spec section 1.7). */
+export function leaves(schema: Schema): Leaf[] {
+  const out: Leaf[] = [];
+  const visit = (chain: SchemaBody[], words: string[]) => {
+    const node = chain[chain.length - 1];
+    if (node.commands?.length) {
+      for (const child of node.commands) visit([...chain, child], [...words, child.name]);
+      return;
+    }
+    const nearest = <T>(pick: (s: SchemaBody) => T | null | undefined, empty: (v: T) => boolean = () => false) => {
+      for (let i = chain.length - 1; i >= 0; i--) {
+        const v = pick(chain[i]);
+        if (v !== undefined && v !== null && !empty(v)) return v;
+      }
+      return undefined;
+    };
+    const roles = new Map<string, SchemaRole>();
+    for (const level of chain) for (const r of level.roles ?? []) roles.set(r.name, r);
+    out.push({
+      words,
+      description: node.description,
+      arguments: node.arguments,
+      options: [...chain].reverse().flatMap((s) => s.options),
+      effects: nearest((s) => s.effects, (v) => v.length === 0) ?? [],
+      stdin: nearest((s) => s.stdin) ?? null,
+      stdout: nearest((s) => s.stdout) ?? null,
+      roles: [...roles.values()],
+      constraints: chain.flatMap((s) => s.constraints ?? []),
+      requiredCommands: chain.flatMap((s) => s.requiredCommands),
+    });
+  };
+  visit([schema], []);
+  return out;
+}
+
+/** The usage line, as help prints it (spec section 7). */
+export function synopsis(name: string, leaf: Leaf): string {
+  const parts = [name, ...leaf.words];
+  for (const a of leaf.arguments) parts.push(a.isVariadic ? `[<${a.name}...>]` : a.required ? `<${a.name}>` : `[<${a.name}>]`);
+  return [...parts, '[OPTIONS]'].join(' ');
+}
+
+/** An option's label: `-s, --long=<value>`, or `--long` for a flag. */
+export function optionLabel(o: SchemaOption): string {
+  const long = `--${o.name}${o.isFlag ? '' : '=<value>'}`;
+  return o.shortName ? `-${o.shortName}, ${long}` : long;
+}
+
+/** An option's description with its notes, as help annotates it (spec section 7). */
+export function optionText(o: SchemaOption): string {
+  const notes: string[] = [];
+  if (o.required) notes.push('required');
+  if (o.isArray) notes.push('repeatable');
+  if (o.secret) notes.push('secret: prefer the environment');
+  if (o.default && !o.isFlag) notes.push(`default: ${o.default}`);
+  if (o.validation) notes.push(`accepts: ${describeRule(o.validation)}`);
+  notes.push(`environment: ${o.variableName}`);
+  return `${o.description}${o.description ? ' ' : ''}(${notes.join('; ')})`;
+}
+
+function argumentText(a: SchemaArgument): string {
+  const notes: string[] = [];
+  if (a.isVariadic) notes.push('any number');
+  else if (!a.required) notes.push(a.default ? `default: ${a.default}` : 'optional');
+  if (a.validation) notes.push(`accepts: ${describeRule(a.validation)}`);
+  return notes.length ? `${a.description}${a.description ? ' ' : ''}(${notes.join('; ')})` : a.description;
+}
+
+function stream(s: SchemaStream): string {
+  return [s.description, s.contentType && `(${s.contentType})`].filter(Boolean).join(' ') || 'Declared, without a description.';
+}
+
+const CONSTRAINT = {
+  exclusive: (o: string[]) => `At most one of ${o.map((n) => `--${n}`).join(', ')}.`,
+  requires: (o: string[]) => `Giving --${o[0]} requires ${o.slice(1).map((n) => `--${n}`).join(', ')}.`,
+  oneOf: (o: string[]) => `At least one of ${o.map((n) => `--${n}`).join(', ')}.`,
+} as Record<string, (o: string[]) => string>;
+
+const EFFECTS: Record<string, string> = {
+  'read-only': 'changes nothing',
+  idempotent: 'running it twice is the same as once',
+  destructive: 'deletes or overwrites things',
+  network: 'talks to the outside world',
+};
+
+/** A leaf's parts: its arguments, options and streams as definition lists, and notes as text. */
+function leafParts(leaf: Leaf): { args?: Block; options?: Block; streams?: Block; notes: Block[] } {
+  const dl = (items: { term: string; text: string }[]): Block | undefined => (items.length ? { kind: 'dl', items } : undefined);
+  const streams = [
+    ...(leaf.stdin ? [{ term: 'stdin', text: stream(leaf.stdin) }] : []),
+    ...(leaf.stdout ? [{ term: 'stdout', text: stream(leaf.stdout) }] : []),
+    ...leaf.roles.map((r) => ({ term: `${r.direction === 'in' ? 'input' : 'output'} role ${r.name}`, text: stream(r) })),
+  ];
+  const notes = [
+    ...(leaf.effects.length ? [`Effects: ${leaf.effects.map((e) => `${e} (${EFFECTS[e] ?? e})`).join(', ')}.`] : []),
+    ...leaf.constraints.map((c) => CONSTRAINT[c.type]?.(c.options) ?? ''),
+    ...leaf.requiredCommands.map((r) => `Needs ${r.command} on PATH: ${r.description}${r.installHint ? ` (${r.installHint})` : ''}.`),
+  ].filter(Boolean);
+  return {
+    args: dl(leaf.arguments.map((a) => ({ term: a.isVariadic ? `<${a.name}...>` : `<${a.name}>`, text: argumentText(a) }))),
+    options: dl(leaf.options.filter((o) => o.name !== 'help').map((o) => ({ term: optionLabel(o), text: optionText(o) }))),
+    streams: dl(streams),
+    notes: notes.map((text) => ({ kind: 'p', text })),
+  };
+}
+
+/** The first sentence of a description (its first line at most), for the NAME line. */
+export function firstSentence(text: string): string {
+  const line = text.split('\n')[0].trim();
+  const end = line.search(/[.!?](\s|$)/);
+  return end < 0 ? line : line.slice(0, end);
+}
+
+/** Today in UTC, or SOURCE_DATE_EPOCH's date for reproducible builds. */
+export function defaultDate(env: NodeJS.ProcessEnv = process.env): string {
+  const epoch = Number(env.SOURCE_DATE_EPOCH);
+  const when = Number.isFinite(epoch) && env.SOURCE_DATE_EPOCH ? new Date(epoch * 1000) : new Date();
+  return when.toISOString().slice(0, 10);
+}
+
+/**
+ * The document for a schema. Throws for input that isn't a clyops schema (`"clyops": 1`, with
+ * description, options and arguments).
+ */
+export function buildDoc(schema: Schema, opts: DocOptions = {}): Doc {
+  if (!schema || typeof schema !== 'object' || schema.clyops !== 1 || !Array.isArray(schema.options) || !Array.isArray(schema.arguments)) {
+    throw new Error('not a clyops schema (expected "clyops": 1 with options and arguments)');
+  }
+  const name = opts.name || schema.script;
+  const all = leaves(schema);
+  const program = all.length === 1 && all[0].words.length === 0;
+  const summary = firstSentence(schema.description || '');
+  const sections: Section[] = [];
+
+  sections.push({ title: 'NAME', blocks: [{ kind: 'p', text: summary ? `${name} - ${summary}` : name }] });
+  sections.push({ title: 'SYNOPSIS', blocks: [{ kind: 'pre', text: all.map((l) => synopsis(name, l)).join('\n') }] });
+  if (schema.description) sections.push({ title: 'DESCRIPTION', blocks: schema.description.split(/\n{2,}/).map((text) => ({ kind: 'p', text })) });
+
+  if (program) {
+    const { args, options, streams, notes } = leafParts(all[0]);
+    if (args) sections.push({ title: 'ARGUMENTS', blocks: [args] });
+    if (options) sections.push({ title: 'OPTIONS', blocks: [options] });
+    if (streams) sections.push({ title: 'STREAMS', blocks: [streams] });
+    if (notes.length) sections.push({ title: 'NOTES', blocks: notes });
+  } else {
+    // One subsection per runnable command, with what it inherits.
+    const blocks: Block[] = [];
+    for (const leaf of all) {
+      const { args, options, streams, notes } = leafParts(leaf);
+      blocks.push({ kind: 'h', text: [name, ...leaf.words].join(' ') });
+      if (leaf.description) blocks.push({ kind: 'p', text: leaf.description });
+      blocks.push({ kind: 'pre', text: synopsis(name, leaf) });
+      for (const [label, part] of [['Arguments', args], ['Options', options], ['Streams', streams]] as const) {
+        if (part) blocks.push({ kind: 'p', text: `${label}:` }, part);
+      }
+      blocks.push(...notes);
+    }
+    sections.push({ title: 'COMMANDS', blocks });
+  }
+
+  // Every option's variable, once, in the order first seen.
+  const env = new Map<string, string>();
+  for (const leaf of all) for (const o of leaf.options) if (o.name !== 'help' && !env.has(o.variableName)) env.set(o.variableName, `Sets --${o.name}.${o.secret ? ' A secret: set it here rather than on the command line.' : ''}`);
+  const anyRoles = all.some((l) => l.roles.length);
+  sections.push({
+    title: 'ENVIRONMENT',
+    blocks: [
+      { kind: 'p', text: 'An option given on the command line takes precedence over the config file, which takes precedence over the environment, which takes precedence over the default.' },
+      {
+        kind: 'dl',
+        items: [
+          ...[...env].map(([term, text]) => ({ term, text })),
+          ...(anyRoles ? [{ term: 'CLYOPS_FDS', text: 'Maps roles to file descriptors, e.g. meta:3,progress:4; set by the program that runs it. Without it, roles are not written.' }] : []),
+          { term: 'CLYOPS_SILENT', text: 'true suppresses informational and warning messages.' },
+          { term: 'CLYOPS_MAX_WIDTH', text: 'The width help is wrapped to (default 100).' },
+          { term: 'NO_COLOR', text: 'Set to turn off colored log levels.' },
+        ],
+      },
+    ],
+  });
+  sections.push({
+    title: 'EXIT STATUS',
+    blocks: [{
+      kind: 'dl',
+      items: [
+        { term: '0', text: 'Success, or help was shown.' },
+        { term: '1', text: 'Invalid arguments, options or input, a missing required command, or a failure the program reports.' },
+        { term: 'other', text: 'Defined by the program.' },
+      ],
+    }],
+  });
+  if (schema.epilog) sections.push({ title: 'EXAMPLES', blocks: [{ kind: 'pre', text: schema.epilog.replace(/\n+$/, '') }] });
+  return { name, section: opts.section || '1', version: opts.version || '', date: opts.date || defaultDate(), summary, sections };
+}

package/src/render.ts

@@ -0,0 +1,178 @@
+// The document (model.ts) as a man page, Markdown or HTML.
+import type { Block, Doc } from './model.js';
+
+/** Output formats. */
+export type Format = 'man' | 'markdown' | 'html';
+
+// ---------------------------------------------------------------------------
+// man(7): plain .TH .SH .SS .PP .TP .nf/.fi macros, which groff and mandoc both render.
+// ---------------------------------------------------------------------------
+
+/** Text for a troff line: backslashes and dashes escaped, a leading `.` or `'` made literal. */
+export function troff(text: string): string {
+  return text
+    .split('\n')
+    .map((line) => {
+      const escaped = line.replace(/\\/g, '\\e').replace(/-/g, '\\-');
+      return /^[.']/.test(escaped) ? `\\&${escaped}` : escaped;
+    })
+    .join('\n');
+}
+
+/** A macro argument: escaped, and quoted so spaces stay in it. */
+function arg(text: string): string {
+  return `"${troff(text).replace(/"/g, '\\(dq')}"`;
+}
+
+function manBlock(b: Block): string[] {
+  switch (b.kind) {
+    case 'p':
+      return ['.PP', troff(b.text)];
+    case 'h':
+      return [`.SS ${arg(b.text)}`];
+    case 'pre':
+      return ['.PP', '.nf', '.RS 4', troff(b.text), '.RE', '.fi'];
+    case 'dl':
+      return b.items.flatMap((i) => ['.TP', `\\fB${troff(i.term)}\\fR`, troff(i.text)]);
+  }
+}
+
+/** The document as a man(7) page. */
+export function renderMan(doc: Doc): string {
+  const title = doc.name.toUpperCase().replace(/\s+/g, '-');
+  const lines = [
+    `.\\" Generated by clyops-doc from ${doc.name} --help-json-schema.`,
+    `.TH ${arg(title)} ${arg(doc.section)} ${arg(doc.date)} ${arg([doc.name, doc.version].filter(Boolean).join(' '))} ${arg('User Commands')}`,
+  ];
+  for (const s of doc.sections) {
+    lines.push(`.SH ${arg(s.title)}`);
+    // NAME is one line, "name \- summary", without a paragraph macro (man(7)).
+    if (s.title === 'NAME') {
+      lines.push(troff(`${doc.name}${doc.summary ? ` - ${doc.summary}` : ''}`));
+      continue;
+    }
+    for (const b of s.blocks) lines.push(...manBlock(b));
+  }
+  return lines.join('\n') + '\n';
+}
+
+// ---------------------------------------------------------------------------
+// Markdown (CommonMark)
+// ---------------------------------------------------------------------------
+
+/**
+ * Text that renders as itself in CommonMark: characters that can start markup escaped, and nothing
+ * else, so the Markdown stays readable (`DRY_RUN`, `(default: 1)`).
+ */
+export function markdownText(text: string): string {
+  return text
+    .split('\n')
+    .map((line) =>
+      line
+        .replace(/[\\`*[\]<>|]/g, '\\$&')
+        // _ only emphasises at a word boundary.
+        .replace(/(^|[^A-Za-z0-9])_|_(?=[^A-Za-z0-9]|$)/g, (m) => m.replace('_', '\\_'))
+        // A block marker at the start of a line: a heading, quote, list item or rule.
+        .replace(/^(\s*)([#>+=-]|\d+[.)])/, '$1\\$2'))
+    .join('\n');
+}
+
+/** Inline code that may itself contain backticks. */
+function code(text: string): string {
+  const run = Math.max(0, ...(text.match(/`+/g) ?? []).map((m) => m.length)) + 1;
+  const fence = '`'.repeat(run);
+  return run > 1 ? `${fence} ${text} ${fence}` : `${fence}${text}${fence}`;
+}
+
+function fenced(text: string): string[] {
+  const run = Math.max(2, ...(text.match(/`+/g) ?? []).map((m) => m.length)) + 1;
+  const fence = '`'.repeat(run);
+  return [fence, text, fence];
+}
+
+function markdownBlock(b: Block): string[] {
+  switch (b.kind) {
+    case 'p':
+      return [markdownText(b.text), ''];
+    case 'h':
+      return [`### ${code(b.text)}`, ''];
+    case 'pre':
+      return [...fenced(b.text), ''];
+    case 'dl':
+      return [...b.items.map((i) => `- ${code(i.term)}: ${markdownText(i.text)}`), ''];
+  }
+}
+
+/** The document as Markdown. */
+export function renderMarkdown(doc: Doc): string {
+  const lines = [`# ${code(doc.name)}`, ''];
+  const header = [doc.version && `Version ${doc.version}`, doc.date].filter(Boolean).join(' · ');
+  if (header) lines.push(`_${markdownText(header)}_`, '');
+  for (const s of doc.sections) {
+    lines.push(`## ${s.title}`, '');
+    for (const b of s.blocks) lines.push(...markdownBlock(b));
+  }
+  return lines.join('\n').replace(/\n+$/, '\n');
+}
+
+// ---------------------------------------------------------------------------
+// HTML: one standalone page, everything escaped.
+// ---------------------------------------------------------------------------
+
+/** Text with HTML's special characters escaped. */
+export function htmlText(text: string): string {
+  return text.replace(/[&<>"']/g, (c) => ({ '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;', "'": '&#39;' })[c] as string);
+}
+
+const slug = (text: string) => text.toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-|-$/g, '');
+
+function htmlBlock(b: Block): string {
+  switch (b.kind) {
+    case 'p':
+      return `<p>${htmlText(b.text)}</p>`;
+    case 'h':
+      return `<h3 id="${slug(b.text)}"><code>${htmlText(b.text)}</code></h3>`;
+    case 'pre':
+      return `<pre><code>${htmlText(b.text)}</code></pre>`;
+    case 'dl':
+      return `<dl>\n${b.items.map((i) => `<dt><code>${htmlText(i.term)}</code></dt>\n<dd>${htmlText(i.text)}</dd>`).join('\n')}\n</dl>`;
+  }
+}
+
+const STYLE = `body{font:16px/1.55 system-ui,sans-serif;max-width:46rem;margin:2rem auto;padding:0 1rem;color:#1d1f21;background:#fff}
+code,pre{font-family:ui-monospace,SFMono-Regular,Menlo,monospace;font-size:.9em}
+pre{background:#f4f5f6;padding:.8rem 1rem;overflow-x:auto;border-radius:4px}
+h2{margin-top:2rem;font-size:1.05rem;letter-spacing:.04em}
+dt{margin-top:.6rem;font-weight:600}dd{margin:.2rem 0 0 1.5rem}
+.meta{color:#5b6168}
+@media (prefers-color-scheme:dark){body{color:#e3e5e8;background:#17191c}pre{background:#23262a}.meta{color:#9aa1a9}}`;
+
+/** The document as a standalone HTML page. */
+export function renderHtml(doc: Doc): string {
+  const header = [doc.version && `Version ${doc.version}`, doc.date].filter(Boolean).join(' · ');
+  const body = doc.sections
+    .map((s) => `<section id="${slug(s.title)}">\n<h2>${htmlText(s.title)}</h2>\n${s.blocks.map(htmlBlock).join('\n')}\n</section>`)
+    .join('\n');
+  return `<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<meta name="generator" content="clyops-doc">
+<title>${htmlText(doc.name)}(${htmlText(doc.section)})</title>
+<style>${STYLE}</style>
+</head>
+<body>
+<header><h1><code>${htmlText(doc.name)}</code></h1>${header ? `<p class="meta">${htmlText(header)}</p>` : ''}</header>
+<main>
+${body}
+</main>
+</body>
+</html>
+`;
+}
+
+/** The document in `format`. */
+export function render(doc: Doc, format: Format): string {
+  return format === 'man' ? renderMan(doc) : format === 'markdown' ? renderMarkdown(doc) : renderHtml(doc);
+}