clyops-doc 0.0.0-stage → 0.7.0

package/dist/model.js

@@ -0,0 +1,280 @@
+// 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,
+            epilog: node.epilog,
+            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: set it in the environment, never on the command line');
+    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(', ')}.`
+            : 'Effects: not declared, so treat it as possibly destructive.',
+        ...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 = [];
+    const page = opts.page || name;
+    sections.push({ title: 'NAME', blocks: [{ kind: 'p', text: summary ? `${page} - ${summary}` : page }] });
+    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 if (opts.split) {
+        // The commands have pages of their own: the program's options here, and a list of the commands.
+        const own = schema.options.filter((o) => o.name !== 'help').map((o) => ({ term: optionLabel(o), text: optionText(o) }));
+        if (own.length)
+            sections.push({ title: 'OPTIONS', blocks: [{ kind: 'p', text: 'Accepted by every command.' }, { kind: 'dl', items: own }] });
+        sections.push({
+            title: 'COMMANDS',
+            blocks: [{ kind: 'dl', items: all.map((l) => ({ term: [name, ...l.words].join(' '), text: `${sentence(l.description)}See ${pageName(name, l.words)}(${opts.section || '1'}).` })) }],
+        });
+    }
+    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 opts.split && !program ? [{ options: schema.options }] : 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 = opts.split && !program ? Boolean(schema.roles?.length) : all.some((l) => l.roles.length);
+    sections.push({
+        title: 'ENVIRONMENT',
+        blocks: [
+            { kind: 'p', text: schema.config
+                    ? '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.'
+                    : 'An option given on the command line 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.' },
+                ],
+            },
+        ],
+    });
+    if (schema.config)
+        sections.push({ title: 'FILES', blocks: files(schema.config, schema.options) });
+    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+$/, '') }] });
+    if (opts.split && !program)
+        sections.push({ title: 'SEE ALSO', blocks: [{ kind: 'refs', items: all.map((l) => ({ page: pageName(name, l.words), section: opts.section || '1' })) }] });
+    return { name, page, section: opts.section || '1', version: opts.version || '', date: opts.date || defaultDate(), summary, sections };
+}
+// The config file (spec section 4): where it comes from and what a line looks like.
+function files(config, options) {
+    const opt = options.find((o) => o.name === config.option);
+    const from = [`--${config.option}`, ...(opt?.variableName ? [opt.variableName] : [])].join(' or ');
+    const where = opt?.default ? `, ${opt.default} by default` : '';
+    const prefixes = config.prefixes.length ? `, on lines starting with ${config.prefixes.join(' or ')}` : '';
+    const example = options.find((o) => o.name !== config.option && o.name !== 'help' && !o.isFlag) ?? options.find((o) => o.name !== config.option && o.name !== 'help');
+    return [
+        { kind: 'p', text: `The config file is the one named by ${from}${where}, resolved against the current directory. An empty value or disabled skips it; a file that doesn't exist is an error.` },
+        { kind: 'p', text: `It sets options with one key=value per line${prefixes}. The key is an option's long name, with or without the leading --. Blank lines and lines starting with # are ignored, and @include PATH reads another file in place, relative to the one including it. Later lines override earlier ones, and an option given on the command line wins over the file.` },
+        ...(example ? [{ kind: 'pre', text: `${config.prefixes[0] ?? ''}${example.name}=${example.isFlag ? 'true' : example.default || 'VALUE'}` }] : []),
+    ];
+}
+// Text as a sentence followed by a space, ending in a full stop unless it has its own; nothing for none.
+function sentence(text) {
+    return text ? `${text}${/[.!?]$/.test(text) ? '' : '.'} ` : '';
+}
+/** A page's name: the invocation's words joined by hyphens, e.g. `mytool-db-migrate`. */
+export function pageName(name, words = []) {
+    return [name, ...words].join(' ').trim().split(/\s+/).join('-');
+}
+/** A runnable command as a program of its own, with everything it inherits, for a page of its own. */
+export function leafSchema(schema, leaf) {
+    return {
+        clyops: 1, script: schema.script, description: leaf.description, epilog: leaf.epilog,
+        arguments: leaf.arguments, options: leaf.options, config: schema.config ?? null,
+        requiredCommands: leaf.requiredCommands, effects: leaf.effects,
+        constraints: leaf.constraints, stdin: leaf.stdin, stdout: leaf.stdout,
+        roles: leaf.roles, commands: [],
+    };
+}
+/**
+ * The index page of a directory of tools (`--root`): what the dispatcher `name` runs, each tool with
+ * a reference to its own page.
+ */
+export function toolsetDoc(name, description, tools, opts = {}) {
+    const section = opts.section || '1';
+    const page = opts.page || pageName(name);
+    const summary = firstSentence(description);
+    const sections = [
+        { title: 'NAME', blocks: [{ kind: 'p', text: summary ? `${page} - ${summary}` : page }] },
+        { title: 'SYNOPSIS', blocks: [{ kind: 'pre', text: tools.map((t) => `${[name, ...t.words].join(' ')} [ARGUMENTS] [OPTIONS]`).join('\n') }] },
+    ];
+    if (description)
+        sections.push({ title: 'DESCRIPTION', blocks: description.split(/\n{2,}/).map((text) => ({ kind: 'p', text })) });
+    sections.push({
+        title: 'TOOLS',
+        blocks: [{ kind: 'dl', items: tools.map((t) => ({ term: [name, ...t.words].join(' '), text: `${sentence(firstSentence(t.description))}See ${pageName(name, t.words)}(${section}).` })) }],
+    });
+    sections.push({ title: 'SEE ALSO', blocks: [{ kind: 'refs', items: tools.map((t) => ({ page: pageName(name, t.words), section })) }] });
+    return { name, page, section, version: opts.version || '', date: opts.date || defaultDate(), summary, sections };
+}

package/dist/render.d.ts

@@ -0,0 +1,23 @@
+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 first line of a Markdown page: a comment, invisible when rendered, saying it is generated. */
+export declare const MARKDOWN_MARKER = "<!-- Generated by clyops-doc from --help-json-schema. Do not edit; regenerate instead. -->";
+/** 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;AAsBD,qCAAqC;AACrC,wBAAgB,SAAS,CAAC,GAAG,EAAE,GAAG,GAAG,MAAM,CAgB1C;AAMD;;;GAGG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAWjD;AA8BD,qGAAqG;AACrG,eAAO,MAAM,eAAe,+FAA+F,CAAC;AAE5H,gCAAgC;AAChC,wBAAgB,cAAc,CAAC,GAAG,EAAE,GAAG,GAAG,MAAM,CAS/C;AAMD,mDAAmD;AACnD,wBAAgB,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAE7C;AA2BD,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,165 @@
+// ---------------------------------------------------------------------------
+// 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)]);
+        case 'refs':
+            return ['.PP', ...b.items.map((r, n) => `.BR ${arg(r.page)} ${arg(`(${r.section})${n < b.items.length - 1 ? ',' : ''}`)}`)];
+    }
+}
+/** The document as a man(7) page. */
+export function renderMan(doc) {
+    const title = doc.page.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.page}${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)}`), ''];
+        case 'refs':
+            return [b.items.map((r) => `[${markdownText(`${r.page}(${r.section})`)}](${encodeURI(r.page)}.md)`).join(', '), ''];
+    }
+}
+/** The first line of a Markdown page: a comment, invisible when rendered, saying it is generated. */
+export const MARKDOWN_MARKER = '<!-- Generated by clyops-doc from --help-json-schema. Do not edit; regenerate instead. -->';
+/** The document as Markdown. */
+export function renderMarkdown(doc) {
+    const lines = [MARKDOWN_MARKER, '', `# ${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>`;
+        case 'refs':
+            return `<p>${b.items.map((r) => `<a href="${htmlText(encodeURI(r.page))}.html"><code>${htmlText(r.page)}</code>(${htmlText(r.section)})</a>`).join(', ')}</p>`;
+    }
+}
+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.page)}(${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,53 @@
 {
   "name": "clyops-doc",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.7.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.7.0",
+    "clyops-schema": "0.7.0",
+    "clyops-tools": "0.7.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"
+  }
 }