clyops-doc 0.0.0-stage → 0.7.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,98 @@
-# 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 |
+| `-r, --root DIR` | Document every tool in a directory (or dispatcher definition), with an index page (needs `--out-dir` or `--prefix`) |
+| `-o, --out-dir DIR` | Write page files into `DIR` (created if missing) instead of to stdout |
+| `-p, --prefix PREFIX` | Install man pages into `PREFIX/share/man/manN`, and warn if `man` won't find them |
+| `--split` | A page per command, git-style (needs `--out-dir` or `--prefix`) |
+| `-x, --execute` | Write the files; without it, `--out-dir` and `--prefix` only list them |
+
+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.
+
+## A page per command
+
+```sh
+mytool --help-json-schema | clyops-doc --split --out-dir man1            # lists the files
+mytool --help-json-schema | clyops-doc --split --out-dir man1 --execute  # writes them
+```
+
+`mytool.1` gets the program's own options and a list of the commands, and each runnable command gets
+its own page, `mytool-db-migrate.1`, with the options it inherits and the nearest declared effects,
+stdin, stdout and roles. They refer to each other under SEE ALSO, as links in Markdown and HTML
+(`.md`, `.html`). A program without commands is one page. Files that already say the same are left
+alone, so a rerun is a no-op. Because it can write files, clyops-doc declares the `idempotent` and
+`destructive` effects, although nothing is written without `--execute`.
+
+## A whole directory of tools
+
+```sh
+clyops-doc --root ~/mytool/scripts --name mytool --prefix ~/.local            # lists the pages
+clyops-doc --root ~/mytool/scripts --name mytool --prefix ~/.local --execute  # installs them
+man mytool-media-to-pcm
+```
+
+`--root` finds tools the way `clyops-dispatch`, `clyops-api` and `clyops-mcp` do (subdirectories
+become command words, `.clyops` files give descriptions and ignores, nested dispatchers are
+followed), asks each for `--help-json-schema`, and writes a page per tool, or with `--split` per
+command, plus an index page named after the dispatcher (`--name`, default the directory's name)
+that lists them all. Executables that aren't clyops tools, or that fail to give a schema, are
+skipped with a warning.
+
+`--prefix` writes into `PREFIX/share/man/man1` (`man8` with `--section 8`) and checks `manpath`
+(or `MANPATH`), saying how to add the directory when `man` won't look there.
+
+## 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` |
+| FILES | the config file: the option and variable naming it, its default, the line format and prefixes |
+| EXIT STATUS | 0, 1, and the tool's own |
+| EXAMPLES | `epilog` |
+| SEE ALSO | with `--split`, the other pages |
+
+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 { buildDoc, document, pages, 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
+for (const { file, content } of pages(schema, 'man')) { /* mytool.1, mytool-db-migrate.1, ... */ }
+```
+
+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,150 @@
+#!/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, info, warn } from 'clyops';
+import { commands, discover, loadSchema } from 'clyops-tools';
+import { execFileSync } from 'node:child_process';
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { delimiter, join, resolve } from 'node:path';
+import { document, extension, pages } from './index.js';
+import { defaultDate, firstSentence, pageName, toolsetDoc } from './model.js';
+import { render } 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 -\n  mytool --help-json-schema | clyops-doc --split --out-dir man1 --execute\n  clyops-doc --root ~/mytool/scripts --name mytool --prefix ~/.local --execute');
+// It writes files only with --out-dir or --prefix and --execute, and then only its own pages.
+cli.setEffects('idempotent', 'destructive');
+cli.setStdin('The tool\'s --help-json-schema output (unless --schema or --root is given)', 'application/json');
+// One declared type per program: what it writes is text/troff, text/markdown or text/html by --format.
+cli.setStdout('The documentation as --format says: text/troff, text/markdown or text/html; with --out-dir or --prefix, the files written (or, without --execute, that would be), one per line', '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"; with --root, the dispatcher\'s name (default: the directory\'s)', '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');
+cli.opt('CLYOPS_DOC_ROOT', 'root', 'r', 'optional', 'Document every tool in this directory (or dispatcher definition), found as clyops-dispatch, clyops-api and clyops-mcp find them, with an index page', 'Input', 'path');
+cli.opt('CLYOPS_DOC_OUT_DIR', 'out-dir', 'o', 'optional', 'Write page files into this directory (created if missing) instead of to stdout', 'Files', 'path');
+cli.opt('CLYOPS_DOC_PREFIX', 'prefix', 'p', 'optional', 'Install man pages into PREFIX/share/man/manSECTION and check that man finds them', 'Files', 'path');
+cli.opt('CLYOPS_DOC_SPLIT', 'split', '', 'flag', 'A page per command, git-style: mytool.1 lists them, mytool-db-migrate.1 documents one', 'Files');
+cli.opt('CLYOPS_DOC_EXECUTE', 'execute', 'x', 'flag', 'Write the files; without it, only list them', 'Files');
+cli.exclusive('schema', 'root');
+cli.exclusive('out-dir', 'prefix');
+const args = cli.run();
+const format = args.CLYOPS_DOC_FORMAT;
+const opts = {
+    name: args.CLYOPS_DOC_NAME ?? undefined,
+    section: args.CLYOPS_DOC_SECTION,
+    version: args.CLYOPS_DOC_VERSION ?? undefined,
+    date: args.CLYOPS_DOC_DATE ?? defaultDate(),
+};
+const root = args.CLYOPS_DOC_ROOT;
+const prefix = args.CLYOPS_DOC_PREFIX;
+const split = args.CLYOPS_DOC_SPLIT;
+const execute = args.CLYOPS_DOC_EXECUTE;
+const manDir = prefix === null ? null : join(prefix, 'share', 'man');
+const outDir = args.CLYOPS_DOC_OUT_DIR ?? (manDir === null ? null : join(manDir, `man${opts.section}`));
+if (prefix !== null && format !== 'man')
+    die(1, '--prefix installs man pages; use --out-dir for --format %s', format);
+if (outDir === null) {
+    // Several pages, or writing them, need somewhere to go.
+    const needs = root !== null ? 'root' : split ? 'split' : execute ? 'execute' : null;
+    if (needs)
+        die(1, '--%s needs --out-dir or --prefix', needs);
+}
+try {
+    if (root !== null)
+        writePages(await toolsetPages(root));
+    else {
+        const schema = readSchema();
+        if (outDir === null)
+            process.stdout.write(document(schema, format, opts));
+        else
+            writePages(split ? pages(schema, format, opts) : [{ file: `${pageName(opts.name || schema.script)}.${extension(format, opts.section)}`, content: document(schema, format, opts) }]);
+    }
+}
+catch (err) {
+    die(1, '%s', err.message);
+}
+function readSchema() {
+    try {
+        return JSON.parse(readFileSync(args.CLYOPS_DOC_SCHEMA ?? 0, 'utf8'));
+    }
+    catch (err) {
+        return die(1, 'Could not read the schema: %s', err.message);
+    }
+}
+// --root: a page (or, with --split, pages) per tool, and an index page named after the dispatcher.
+async function toolsetPages(dir) {
+    const group = discover(dir, { name: opts.name });
+    const ext = extension(format, opts.section);
+    const out = [];
+    const tools = [];
+    for (const cmd of commands(group)) {
+        if (cmd.kind !== 'tool') {
+            warn('Skipping %s: not a clyops tool', cmd.file);
+            continue;
+        }
+        let schema;
+        try {
+            schema = await loadSchema(cmd.file);
+        }
+        catch (err) {
+            warn('Skipping %s', err.message);
+            continue;
+        }
+        const name = [group.name, ...cmd.words].join(' ');
+        out.push(...(split
+            ? pages(schema, format, { ...opts, name })
+            : [{ file: `${pageName(name)}.${ext}`, content: document(schema, format, { ...opts, name, page: pageName(name) }) }]));
+        tools.push({ words: cmd.words, description: firstSentence(schema.description) });
+    }
+    if (!tools.length)
+        throw new Error(`no clyops tools in ${dir}`);
+    const all = [{ file: `${pageName(group.name)}.${ext}`, content: render(toolsetDoc(group.name, group.description, tools, opts), format) }, ...out];
+    const seen = new Set();
+    for (const p of all) {
+        if (seen.has(p.file))
+            throw new Error(`two pages would be named ${p.file}`);
+        seen.add(p.file);
+    }
+    return all;
+}
+// Each page into the directory, leaving files that already say the same alone.
+function writePages(all) {
+    const dir = outDir;
+    let replaced = 0;
+    let unchanged = 0;
+    if (execute)
+        mkdirSync(dir, { recursive: true });
+    for (const page of all) {
+        const path = join(dir, page.file);
+        const before = existsSync(path) ? readFileSync(path, 'utf8') : null;
+        if (before === page.content)
+            unchanged++;
+        else {
+            if (before !== null)
+                replaced++;
+            if (execute)
+                writeFileSync(path, page.content);
+        }
+        process.stdout.write(`${path}\n`);
+    }
+    const counts = `${all.length - unchanged} page(s)${replaced ? ` (replacing ${replaced})` : ''}${unchanged ? `; ${unchanged} already up to date` : ''}`;
+    info(execute ? `Wrote ${counts} in ${dir}.` : `Would write ${counts} in ${dir}; add --execute to write them.`);
+    if (manDir !== null)
+        checkManPath(manDir);
+}
+// --prefix: say so when man won't look in PREFIX/share/man.
+function checkManPath(dir) {
+    let paths = process.env.MANPATH ?? '';
+    try {
+        paths = execFileSync('manpath', [], { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'], timeout: 5000 }).trim();
+    }
+    catch {
+        // No manpath(1): MANPATH is all there is to go on.
+    }
+    const want = resolve(dir);
+    if (!paths.split(delimiter).some((p) => p && resolve(p) === want)) {
+        warn('man won\'t find these pages: %s is not on its search path. Add it with: export MANPATH="%s%s$(manpath)"', want, want, delimiter);
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,23 @@
+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;
+/** One file of a split document. */
+export interface Page {
+    /** File name, e.g. `mytool-db-migrate.1`, `mytool.md`. */
+    file: string;
+    /** The page in its format. */
+    content: string;
+}
+/** A page's file extension: the manual section for man, else the format's. */
+export declare function extension(format: Format, section?: string): string;
+/**
+ * The documentation as a page per runnable command, git-style: `mytool.1` lists the commands and
+ * each has its own, e.g. `mytool-db-migrate.1`, with what it inherits. A program without commands
+ * is one page. Throws for input that isn't a clyops schema, or for two commands with one page name.
+ */
+export declare function pages(schema: Schema, format?: Format, opts?: DocOptions): Page[];
+//# 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,EAA0C,KAAK,UAAU,EAAE,MAAM,YAAY,CAAC;AACrF,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;AAED,oCAAoC;AACpC,MAAM,WAAW,IAAI;IACnB,0DAA0D;IAC1D,IAAI,EAAE,MAAM,CAAC;IACb,8BAA8B;IAC9B,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,8EAA8E;AAC9E,wBAAgB,SAAS,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,SAAM,GAAG,MAAM,CAE/D;AAED;;;;GAIG;AACH,wBAAgB,KAAK,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,GAAE,MAAc,EAAE,IAAI,GAAE,UAAe,GAAG,IAAI,EAAE,CAgB3F"}

package/dist/index.js

@@ -0,0 +1,37 @@
+// clyops-doc: documentation (man, Markdown, HTML) from a clyops tool's --help-json-schema.
+export * from './model.js';
+export * from './render.js';
+import { buildDoc, leafSchema, leaves, pageName } 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);
+}
+/** A page's file extension: the manual section for man, else the format's. */
+export function extension(format, section = '1') {
+    return format === 'man' ? section : format === 'markdown' ? 'md' : 'html';
+}
+/**
+ * The documentation as a page per runnable command, git-style: `mytool.1` lists the commands and
+ * each has its own, e.g. `mytool-db-migrate.1`, with what it inherits. A program without commands
+ * is one page. Throws for input that isn't a clyops schema, or for two commands with one page name.
+ */
+export function pages(schema, format = 'man', opts = {}) {
+    const name = opts.name || schema?.script || '';
+    const top = buildDoc(schema, { ...opts, split: true, page: pageName(name) });
+    const ext = extension(format, top.section);
+    const out = [{ file: `${top.page}.${ext}`, content: render(top, format) }];
+    const all = leaves(schema);
+    if (all.length === 1 && all[0].words.length === 0)
+        return out;
+    for (const leaf of all) {
+        const page = pageName(name, leaf.words);
+        const doc = buildDoc(leafSchema(schema, leaf), { ...opts, split: false, name: [name, ...leaf.words].join(' '), page });
+        doc.sections.push({ title: 'SEE ALSO', blocks: [{ kind: 'refs', items: [{ page: pageName(name), section: top.section }] }] });
+        const file = `${page}.${ext}`;
+        if (out.some((p) => p.file === file))
+            throw new Error(`two pages would be named ${file}`);
+        out.push({ file, content: render(doc, format) });
+    }
+    return out;
+}

package/dist/model.d.ts

@@ -0,0 +1,129 @@
+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;
+} | {
+    kind: 'refs';
+    items: {
+        page: string;
+        section: 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;
+    /** The page's name in the header and NAME line: `name`, or a split page's, e.g. `mytool-db-migrate`. */
+    page: 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;
+    /** The page's name (default: `name`); see `Doc.page`. */
+    page?: string;
+    /** Commands get pages of their own (see `pages`): list them, with a SEE ALSO, instead of documenting each. */
+    split?: boolean;
+}
+/** 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;
+    /** Text after its help, e.g. examples. */
+    epilog: 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;
+/** A page's name: the invocation's words joined by hyphens, e.g. `mytool-db-migrate`. */
+export declare function pageName(name: string, words?: string[]): string;
+/** A runnable command as a program of its own, with everything it inherits, for a page of its own. */
+export declare function leafSchema(schema: Schema, leaf: Leaf): Schema;
+/** One tool of a toolset, for its index page (see `toolsetDoc`). */
+export interface ToolEntry {
+    /** The words after the toolset's name, e.g. ['media', 'to-pcm']. */
+    words: string[];
+    /** The tool's description. */
+    description: string;
+}
+/**
+ * The index page of a directory of tools (`--root`): what the dispatcher `name` runs, each tool with
+ * a reference to its own page.
+ */
+export declare function toolsetDoc(name: string, description: string, tools: ToolEntry[], 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":"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"}