@ai-ecoverse/slicc-man 1.0.0 → 1.1.0

package/README.md

@@ -30,7 +30,7 @@ The same installers are attached to every GitHub release, as `install.sh` and `i
 curl -fsSL https://github.com/ai-ecoverse/slicc-man/releases/latest/download/install.sh | sh
 ```
 
-They install the release's `scman` with a launcher in `~/.local/bin` (on Windows `%LOCALAPPDATA%\slicc-man\bin`, added to the user's `PATH`), and download Node 24 into the install when no Node 24 or later is on `PATH`. Options pass through (`curl -fsSL https://get.sliccy.ai/man | sh -s -- --help`): `--version <version>` installs that release instead of the latest, `--dir <dir>` puts the launcher in `<dir>`, and `--help` prints the usage. `install.ps1` takes the same options.
+They install the release's `scman` with a launcher in `~/.local/bin` (on Windows `%LOCALAPPDATA%\slicc-man\bin`, added to the user's `PATH`), and download Node 24 into the install when no Node 24 or later is on `PATH` (the `.tar.gz`, or the `.zip` on Windows), checked against nodejs.org's `SHASUMS256.txt`. Each release also carries the package tarball, `slicc-man-<version>.tgz`, and `SHA256SUMS`, which covers the tarball, `install.sh` and `install.ps1`: the installers check the tarball against it, unpack it into `${XDG_DATA_HOME:-~/.local/share}/slicc-man/<version>` (on Windows `%LOCALAPPDATA%\slicc-man\<version>`), write the launcher (`scman`, or `scman.ps1` and `scman.cmd` on Windows, which only start `node.exe` with the entry script and the arguments, the node call and its `exit` on one line of the `.cmd`), run it with `--version` (the version alone, or `scman <version>` from older releases), and print `scman <version> installed to <launcher>`. Options pass through (`curl -fsSL https://get.sliccy.ai/man | sh -s -- --help`): `--version <version>` installs that release instead of the latest, `--dir <dir>` puts the launcher in `<dir>`, and `--help` prints the usage; `install.sh` exits 2 for an unknown option or one without its value. `install.ps1` takes the same options, spelled `-Version`, `-Dir` and `-Help`. `SLICC_INSTALL_BASE_URL` replaces the directory the assets are downloaded from (by default `https://github.com/ai-ecoverse/slicc-man/releases/latest/download`, or `…/releases/download/v<version>` with `--version`), and `SLICC_NODE_DIST_BASE` nodejs.org, for mirrors and tests.
 
 On a machine with Node 24 or later, npm works too:
 
@@ -57,15 +57,15 @@ man [options] [section] topic...
 | `-a`, `--all` | show every matching page; there is only ever one, so it changes nothing |
 | `-w`, `--where`, `--path`, `--location` | print the page's URL, `https://www.sliccy.com/man/<topic>.md`, instead of showing it |
 | `-P <pager>`, `--pager=<pager>` | the pager (see [Rendering](#rendering)) |
-| `-l <file>`, `--local-file=<file>` | render a local Markdown file (`-` for stdin) as a page; the operands are files, not topics |
+| `-l`, `--local-file` | render the operands, local Markdown files (`-` for stdin), as pages; the page's name is the file's, without `.md`, and `stdin` for `-` |
 | `-i`, `--ignore-case` | the default |
 | `-I`, `--match-case` | look the topic up as typed, not in lower case |
 | `--nh`, `--no-hyphenation`, `--nj`, `--no-justification` | accepted; the renderer neither hyphenates nor justifies |
 | `-h`, `--help` | the usage to stdout, exit 0 |
-| `-V`, `--version` | `man <version>` (or `scman <version>`) to stdout, exit 0; every host command takes it, and the installer runs the launcher with it |
+| `-V`, `--version` | the version alone (`1.2.0`) to stdout, exit 0; every host command takes it, and the installer runs the launcher with it |
 | `--upgrade` | see [`--upgrade`](#--upgrade) |
 
-An option's value may be attached (`-s1`, `-Pcat`) or the next argument, and `--` ends the options. `man` with no topic prints `What manual page do you want?` and `For example, try 'man man'.` to stderr and exits 2.
+Short options may be grouped (`-aw`). An option's value may be attached (`-s1`, `-Pcat`, `--pager=cat`) or the next argument; options may come after the operands, and `--` ends the options. Of `-k` and `-f`, the last one given counts, and so for `-i` and `-I`. With `-k` or `-f`, the operands are matched with `apropos`'s and `whatis`'s defaults, and only `-s` of the other options counts. `man` with no topic prints `What manual page do you want?` and `For example, try 'man man'.` to stderr and exits 2.
 
 ## apropos and whatis
 
@@ -87,7 +87,7 @@ whatis [options] topic...
 | `-s <list>`, `--sections=<list>` | only those sections; without 1, nothing matches | the same |
 | `-h`, `-V`, `--upgrade` | as for `man` | the same |
 
-On a terminal, a line wider than the width (see [Rendering](#rendering)) is cut and ends in `...`; through a pipe it is whole. A keyword with no match prints `<keyword>: nothing appropriate.` to stderr. With `-a`, that is printed for the keywords together, when no page matches them all. A regular expression that doesn't parse is a usage error.
+On a terminal, a line wider than the width (see [Rendering](#rendering)) is cut and ends in `...`; through a pipe it is whole. A keyword with no match prints `<keyword>: nothing appropriate.` to stderr. With `-a`, that is printed for the keywords together, when no page matches them all. A regular expression that doesn't parse is a usage error, `<cmd>: <keyword>: invalid regular expression`. With no keyword, `apropos` prints `apropos what?` (`whatis`: `whatis what?`) to stderr and exits 2; `man -k` and `man -f` do the same.
 
 ## Not supported
 
@@ -96,7 +96,7 @@ These man-db options can't work here. They print `<cmd>: <option>: not supported
 - **man:** `-t`/`--troff`, `-T`/`--troff-device`, `-H`/`--html`, `-X`/`--gxditview`, `-Z`/`--ditroff`, `-M`/`--manpath`, `-m`/`--systems`, `-L`/`--locale`, `-C`/`--config-file`, `-d`/`--debug`, `-D`/`--default`, `-W`/`--where-cat`, `-c`/`--catman`, `-u`/`--update`, `-e`/`--extension`, `-p`/`--preprocessor`, `-R`/`--recode`, `-E`/`--encoding`, `-K`/`--global-apropos`, `-r`/`--prompt`, `--regex`, `--wildcard`, `--names-only`, `--no-subpages`.
 - **apropos, whatis:** `-M`/`--manpath`, `-m`/`--systems`, `-L`/`--locale`, `-C`/`--config-file`, `-d`/`--debug`, `-v`/`--verbose`.
 
-Any other option, or an option without its value, prints `<cmd>: unknown option: <option>` (or `<cmd>: <option>: needs a value`) and the usage to stderr, and exits 2.
+Any other option, or an option without its value, prints `<cmd>: unknown option: <option>` (or `<cmd>: <option>: needs a value`) and the usage to stderr, and exits 2. So does `--upgrade` with anything else, as `<cmd>: --upgrade takes no other arguments`.
 
 ## Exit codes
 
@@ -132,7 +132,7 @@ Pages, the sitemap and the topic index are cached:
 - on a host in `$XDG_CACHE_HOME/slicc-man`, by default `~/.cache/slicc-man`, and on Windows in `%LOCALAPPDATA%\slicc-man\cache`;
 - in SLICC in `~/.cache/slicc-man`, which lives in OPFS, so it survives reloads.
 
-Each site has its own directory in the cache, named by the base URL's host and port. A cached copy is fresh for the response's `Cache-Control` `max-age` (the site sends 4 hours), and 4 hours without one. A stale copy is revalidated with `If-Modified-Since` (the response's `Last-Modified`): `304` keeps it and makes it fresh again, `200` replaces it, and `404` drops it, so the topic has no page. When the site can't be reached, or answers 5xx, a cached copy is shown however old, after one line on stderr, `<cmd>: <url>: <reason>; showing the copy cached <date>`. With nothing cached, the command prints `<cmd>: <url>: <reason>` and exits 2. The cache is written atomically (a temporary file renamed into place), so two commands at once never see half a page; a cache that can't be written is skipped without a word.
+Each site has its own directory in the cache, named by the base URL's host and port (`www.sliccy.com`, `127.0.0.1-8080`), with one JSON file per page, `sitemap.json` and `index.json`. A cached copy is fresh for the response's `Cache-Control` `max-age` (the site sends 4 hours), and 4 hours without one. A stale copy is revalidated with `If-Modified-Since` (the response's `Last-Modified`): `304` keeps it and makes it fresh again, `200` replaces it, and `404` drops it, so the topic has no page. When the site can't be reached, or answers 5xx, a cached copy is shown however old, after one line on stderr, `<cmd>: <url>: <reason>; showing the copy cached <date>`. With nothing cached, the command prints `<cmd>: <url>: <reason>` and exits 2. The cache is written atomically (a temporary file renamed into place), so two commands at once never see half a page; a cache that can't be written is skipped without a word.
 
 `apropos` and `whatis` read the index: every `/man/<topic>` entry of the sitemap, with its description, the first paragraph of its page, rendered as plain text on one line. The index is built from the cached sitemap and pages, fetching what is missing or stale (pages through the same cache, several at a time), and cached itself under the same rules. A page that fails to load is listed without a description.
 
@@ -148,6 +148,8 @@ Every host command takes `--upgrade`. It runs the latest release's installer (`i
 
 The commands are `scman` on a host and `man`, `apropos`, `whatis` and `scman` in SLICC.
 
+The launcher the installer writes sets `SCMAN_INSTALL_DIR` to its own directory; that is how `scman` knows the installer put it there (it removes the variable before it starts a pager or the installer), and without it `scman` counts as installed with npm. The installer is downloaded from `https://github.com/ai-ecoverse/slicc-man/releases/latest/download/` and run as `sh install.sh --dir DIR`, or `powershell.exe -NoProfile -NonInteractive -ExecutionPolicy Bypass -File install.ps1 -Dir DIR` (else `pwsh.exe`); the line it prints, `scman <version> installed to <launcher>`, names the new version. A download that fails is the installer failing: `<cmd>: could not download <url>: <reason>`, exit 1. The download has 60 seconds; after that `--upgrade` prints `<cmd>: download timed out` to stderr and exits 1. `SLICC_INSTALL_BASE_URL`, when set, replaces that release URL for `--upgrade` and for the installers' own downloads.
+
 ## Platforms
 
 | platform | commands | cache | pager | network |
@@ -168,11 +170,13 @@ npm test
 npm run test:unit
 ```
 
-- `npm run lint`: Biome, the no-comment check and the other [slicc-shared-web](https://github.com/ai-ecoverse/slicc-shared-web) checks.
-- `npm test`: the integration tests in `test/integration/`. Host tests run the commands against a local HTTP server on an ephemeral port standing in for www.sliccy.com (`SLICC_MAN_URL`), with a temporary cache and fake tools, `less` among them, on a temporary `PATH`; only CI touches the real site. `test/integration/repo.test.mjs` checks the workflow, the release config, the package's shape, what `npm pack` ships and the repo rules.
+- `npm run lint`: Biome, the no-comment check and the other [slicc-shared-web](https://github.com/ai-ecoverse/slicc-shared-web) checks, then `shellcheck -s sh` and `dash -n` on `install.sh`.
+- `npm test`: the integration tests in `test/integration/`. `host.test.mjs` runs `scman` (in-process, so a terminal can be faked, and as `host/scman.mjs`) against a local HTTP server on an ephemeral port standing in for www.sliccy.com (`SLICC_MAN_URL`), serving copies of the site's `tree.md` and `man.md` (`pages.json`, with their expected renderings), with a temporary cache and fake tools, `less` among them, on a temporary `PATH`; only CI touches the real site. `install.test.mjs` runs `install.sh` on a tarball packed from the tree, with the Node on `PATH` and with a Node download from a fake nodejs.org, and `--upgrade` against a release served from a local server; `install.ps1` is checked statically, and run when `pwsh` is on `PATH`. `repo.test.mjs` checks the workflow, the release config, the package's shape, what `npm pack` ships and the repo rules.
 - `npm run test:unit`: the unit tests in the gitignored `test/unit/`, with Node's coverage in `coverage/unit/lcov.info`. The pre-commit hook wants 100% coverage of the changed lines.
 
-CI is `.github/workflows/ci.yml`, the only workflow, which runs [slicc-shared-web's pipeline](https://github.com/ai-ecoverse/slicc-shared-web#pipeline) at the devDependency's version, on Linux only: `npm run lint`, then `npm test`, then on a pull request the Claude and Codex reviews. The merge queue requires `ci / integration` and `ci / review`. On a push to `main`, semantic-release releases and publishes to npm through trusted publishing, with provenance from `ci.yml`.
+CI is `.github/workflows/ci.yml`, the only workflow, which runs [slicc-shared-web's pipeline](https://github.com/ai-ecoverse/slicc-shared-web#pipeline) at the devDependency's version, on Linux only: `npm run lint`, then `npm test`, then on a pull request the Claude and Codex reviews. The merge queue requires `ci / integration` and `ci / review`. On a push to `main`, semantic-release releases and publishes to npm through trusted publishing, with provenance from `ci.yml`, and attaches `slicc-man-<version>.tgz`, `SHA256SUMS`, `install.sh` and `install.ps1` to the GitHub release (`scripts/assets.mjs` renames the tarball and writes `SHA256SUMS`).
+
+The code is in `lib/` (options, the Markdown renderer, the cache and index, apropos and whatis, shared with SLICC) and `host/` (`scman.mjs`, the cache directory, the pager, `--upgrade`).
 
 ## License
 

package/host/cache.mjs

@@ -0,0 +1,43 @@
+import { mkdir, readFile, rename, rm, writeFile } from 'node:fs/promises';
+import { homedir } from 'node:os';
+import { isAbsolute, join } from 'node:path';
+import { variable } from './path.mjs';
+
+export function cacheRoot(platform, env) {
+  if (platform === 'win32') {
+    const local = variable(env, 'LOCALAPPDATA') || join(homedir(), 'AppData', 'Local');
+    return join(local, 'slicc-man', 'cache');
+  }
+  const xdg = env.XDG_CACHE_HOME;
+  if (xdg && isAbsolute(xdg)) return join(xdg, 'slicc-man');
+  return join(env.HOME || homedir(), '.cache', 'slicc-man');
+}
+
+let counter = 0;
+
+export function store(dir) {
+  const file = (id) => join(dir, `${id}.json`);
+  return {
+    async read(id) {
+      try {
+        return await readFile(file(id), 'utf8');
+      } catch {
+        return undefined;
+      }
+    },
+    async write(id, text) {
+      await mkdir(dir, { recursive: true });
+      const temp = join(dir, `.${id}.${process.pid}.${Date.now()}.${counter++}.tmp`);
+      try {
+        await writeFile(temp, text);
+        await rename(temp, file(id));
+      } catch (error) {
+        await rm(temp, { force: true });
+        throw error;
+      }
+    },
+    async remove(id) {
+      await rm(file(id), { force: true });
+    },
+  };
+}

package/host/io.mjs

@@ -0,0 +1,15 @@
+import { writeSync } from 'node:fs';
+
+export function say(fd, text) {
+  const data = Buffer.from(text);
+  let at = 0;
+  while (at < data.length) {
+    try {
+      at += writeSync(fd, data, at, data.length - at);
+    } catch (error) {
+      if (error.code === 'EAGAIN') continue;
+      if (error.code === 'EPIPE') return;
+      throw error;
+    }
+  }
+}

package/host/main.mjs

@@ -0,0 +1,54 @@
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { run } from '../lib/man.mjs';
+import { cacheRoot, store } from './cache.mjs';
+import { say } from './io.mjs';
+import { page } from './pager.mjs';
+import { lookup } from './path.mjs';
+import { upgrade, version } from './upgrade.mjs';
+
+const reasons = {
+  ENOENT: 'No such file or directory',
+  EACCES: 'Permission denied',
+  EISDIR: 'Is a directory',
+  ENOTDIR: 'Not a directory',
+};
+
+function read(file, fds) {
+  try {
+    return readFileSync(file === '-' ? fds[0] : file, 'utf8');
+  } catch (error) {
+    throw new Error(reasons[error.code] ?? error.message);
+  }
+}
+
+export async function main({
+  name,
+  argv,
+  env,
+  platform,
+  fds,
+  tty,
+  columns,
+  fetch = globalThis.fetch,
+  now,
+}) {
+  const child = { ...env };
+  delete child.SCMAN_INSTALL_DIR;
+  const root = cacheRoot(platform, env);
+  const io = {
+    tty,
+    columns,
+    fetch,
+    now,
+    version: version(),
+    out: (text) => say(fds[1], text),
+    err: (text) => say(fds[2], text),
+    store: (dir) => store(join(root, dir)),
+    which: (file) => lookup(file, platform, env) !== undefined,
+    page: (command, text) => page(command, text, { name, platform, env: child, fds }),
+    read: (file) => read(file, fds),
+    upgrade: () => upgrade({ name, env, platform, fds, fetch }),
+  };
+  return run({ kind: 'man', name, argv, env, io });
+}

package/host/pager.mjs

@@ -0,0 +1,38 @@
+import { spawn } from 'node:child_process';
+import { say } from './io.mjs';
+import { variable } from './path.mjs';
+
+export function shell(command, platform, env) {
+  if (platform === 'win32') {
+    return {
+      file: variable(env, 'COMSPEC') || 'cmd.exe',
+      args: ['/d', '/s', '/c', `"${command}"`],
+      options: { windowsVerbatimArguments: true },
+    };
+  }
+  return { file: '/bin/sh', args: ['-c', command], options: {} };
+}
+
+export function page(command, text, { name, platform, env, fds }) {
+  const run = shell(command, platform, env);
+  const ignore = () => {};
+  process.on('SIGINT', ignore);
+  return new Promise((done) => {
+    let failed = false;
+    const child = spawn(run.file, run.args, {
+      ...run.options,
+      env,
+      stdio: ['pipe', fds[1], fds[2]],
+    });
+    child.on('error', (error) => {
+      failed = true;
+      say(fds[2], `${name}: ${command}: ${error.message}\n`);
+    });
+    child.stdin.on('error', ignore);
+    child.stdin.end(text);
+    child.on('close', (code) => {
+      process.off('SIGINT', ignore);
+      done(failed || code === 126 || code === 127 ? 2 : 0);
+    });
+  });
+}

package/host/path.mjs

@@ -0,0 +1,33 @@
+import { accessSync, constants, statSync } from 'node:fs';
+import { join } from 'node:path';
+
+export function variable(env, name) {
+  const found = Object.keys(env).find((key) => key.toUpperCase() === name);
+  return found === undefined ? undefined : env[found];
+}
+
+export function lookup(file, platform, env) {
+  const windows = platform === 'win32';
+  const dirs = String((windows ? variable(env, 'PATH') : env.PATH) ?? '')
+    .split(windows ? ';' : ':')
+    .filter(Boolean);
+  const exts = windows
+    ? [
+        '',
+        ...String(variable(env, 'PATHEXT') || '.COM;.EXE;.BAT;.CMD')
+          .split(';')
+          .filter(Boolean),
+      ]
+    : [''];
+  for (const dir of dirs) {
+    for (const ext of exts) {
+      const path = join(dir, file + ext);
+      try {
+        if (!statSync(path).isFile()) continue;
+        if (!windows) accessSync(path, constants.X_OK);
+        return path;
+      } catch {}
+    }
+  }
+  return undefined;
+}

package/host/scman.mjs

@@ -0,0 +1,14 @@
+#!/usr/bin/env node
+import { isatty } from 'node:tty';
+import { main } from './main.mjs';
+
+const tty = isatty(1);
+process.exitCode = await main({
+  name: 'scman',
+  argv: process.argv.slice(2),
+  env: process.env,
+  platform: process.platform,
+  fds: [0, 1, 2],
+  tty,
+  columns: tty ? process.stdout.columns : undefined,
+});

package/host/upgrade.mjs

@@ -0,0 +1,93 @@
+import { spawn } from 'node:child_process';
+import { mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { say } from './io.mjs';
+import { lookup } from './path.mjs';
+
+export const LATEST = 'https://github.com/ai-ecoverse/slicc-man/releases/latest/download';
+
+export function version() {
+  return JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8')).version;
+}
+
+function reason(error) {
+  return error.cause?.message ?? error.message;
+}
+
+function installer(platform, env, path, dir) {
+  if (platform === 'win32') {
+    const file = ['powershell.exe', 'pwsh.exe'].find((name) => lookup(name, platform, env));
+    const args = ['-NoProfile', '-NonInteractive', '-ExecutionPolicy', 'Bypass', '-File', path];
+    return file && { file, tool: lookup(file, platform, env), args: [...args, '-Dir', dir] };
+  }
+  const tool = lookup('sh', platform, env);
+  return tool && { file: 'sh', tool, args: [path, '--dir', dir] };
+}
+
+function wait(file, args, options) {
+  return new Promise((done) => {
+    const out = [];
+    const child = spawn(file, args, options);
+    child.stdout.on('data', (chunk) => out.push(chunk));
+    child.on('error', (error) => done({ error }));
+    child.on('close', (code) => done({ code, stdout: Buffer.concat(out).toString() }));
+  });
+}
+
+export async function upgrade({ name, env, platform, fds, fetch }) {
+  const fail = (text) => {
+    say(fds[2], `${name}: ${text}\n`);
+    return 1;
+  };
+  const dir = env.SCMAN_INSTALL_DIR;
+  if (!dir) {
+    say(fds[1], 'npm install -g @ai-ecoverse/slicc-man@latest\n');
+    return 0;
+  }
+  const file = platform === 'win32' ? 'install.ps1' : 'install.sh';
+  const url = `${(env.SLICC_INSTALL_BASE_URL || LATEST).replace(/\/+$/, '')}/${file}`;
+  let text;
+  try {
+    const response = await fetch(url, { redirect: 'follow', signal: AbortSignal.timeout(60000) });
+    if (!response.ok) {
+      await response.body?.cancel();
+      return fail(`could not download ${url}: HTTP ${response.status}`);
+    }
+    text = await response.text();
+  } catch (error) {
+    if (error?.name === 'TimeoutError') return fail('download timed out');
+    return fail(`could not download ${url}: ${reason(error)}`);
+  }
+  const scratch = mkdtempSync(join(tmpdir(), 'scman-upgrade-'));
+  try {
+    const path = join(scratch, file);
+    writeFileSync(path, text);
+    const run = installer(platform, env, path, dir);
+    if (!run) {
+      const tried = platform === 'win32' ? 'powershell.exe, pwsh.exe' : 'sh';
+      return fail(`no shell found to run ${file} (tried ${tried})`);
+    }
+    const child = { ...env };
+    delete child.SCMAN_INSTALL_DIR;
+    const result = await wait(run.tool, run.args, {
+      env: child,
+      stdio: ['ignore', 'pipe', fds[2]],
+      windowsHide: true,
+    });
+    if (result.error) return fail(`${run.file}: ${result.error.message}`);
+    if (result.code !== 0) return 1;
+    const installed = /^scman (\S+) installed to /m.exec(result.stdout)?.[1];
+    if (!installed) return fail(`${file} did not say which version it installed`);
+    const old = version();
+    say(
+      fds[1],
+      installed === old
+        ? `${name}: already up to date (${old})\n`
+        : `${name}: ${old} → ${installed}\n`
+    );
+    return 0;
+  } finally {
+    rmSync(scratch, { recursive: true, force: true });
+  }
+}

package/lib/man.mjs

@@ -0,0 +1,215 @@
+import { clean } from './markdown.mjs';
+import { parse, usage } from './options.mjs';
+import { render } from './render.mjs';
+import { cut, line, matcher, search } from './search.mjs';
+import { base, folder, site } from './site.mjs';
+
+const OK = 0;
+const USAGE = 2;
+const NONE = 16;
+
+function worse(a, b) {
+  if (a === USAGE || b === USAGE) return USAGE;
+  return a === NONE || b === NONE ? NONE : OK;
+}
+
+function width(env, io) {
+  const manwidth = String(env.MANWIDTH ?? '').trim();
+  if (/^\d+$/.test(manwidth) && Number(manwidth) > 0) return Number(manwidth);
+  if (io.tty && Number.isInteger(io.columns) && io.columns > 0) return io.columns;
+  return 80;
+}
+
+function sections(text) {
+  return text.split(/[:,]/).filter(Boolean);
+}
+
+const sectionName = /^[0-9][A-Za-z]*$/;
+
+async function show(text, ctx) {
+  const { io, env, values } = ctx;
+  if (!io.tty) {
+    await io.out(text);
+    return OK;
+  }
+  let pager = values.pager ?? env.MANPAGER ?? env.PAGER;
+  if (pager === undefined) pager = (await io.which('less')) ? 'less -R' : '';
+  if (pager.trim() === '') {
+    await io.out(text);
+    return OK;
+  }
+  return io.page(pager, text);
+}
+
+function choose(kind, flags) {
+  if (flags.regex) return 'regex';
+  if (flags.wildcard) return 'wildcard';
+  if (flags.exact || kind === 'whatis') return 'exact';
+  return 'regex';
+}
+
+async function compile(kind, ctx, flags, operands) {
+  const mode = choose(kind, flags);
+  const matchers = [];
+  for (const keyword of operands) {
+    try {
+      matchers.push(matcher(kind, mode, keyword));
+    } catch {
+      await ctx.io.err(`${ctx.name}: ${keyword}: invalid regular expression\n`);
+      return undefined;
+    }
+  }
+  return matchers;
+}
+
+async function keywords(kind, ctx, parsed) {
+  const { io } = ctx;
+  const { flags, values, operands } = parsed;
+  if (operands.length === 0) {
+    await io.err(`${kind} what?\n`);
+    return USAGE;
+  }
+  const matchers = await compile(kind, ctx, flags, operands);
+  if (!matchers) return USAGE;
+  const all = Boolean(flags.and);
+  const nothing = async () => {
+    if (all) await io.err(`${operands.join(' ')}: nothing appropriate.\n`);
+    else for (const keyword of operands) await io.err(`${keyword}: nothing appropriate.\n`);
+    return NONE;
+  };
+  if (values.sections !== undefined && !sections(values.sections).includes('1')) return nothing();
+  const index = await ctx.site.index();
+  if (index.note) await io.err(`${index.note}\n`);
+  if (index.error) {
+    await io.err(`${index.error}\n`);
+    return USAGE;
+  }
+  const { found, hits } = search(index.entries, matchers, all);
+  const columns = width(ctx.env, io);
+  const long = flags.long || !io.tty;
+  let out = '';
+  for (const entry of found) {
+    const text = clean(line(entry));
+    out += `${long ? text : cut(text, columns)}\n`;
+  }
+  if (out) await io.out(out);
+  if (all) return found.length === 0 ? nothing() : OK;
+  let code = OK;
+  for (const [n, keyword] of operands.entries()) {
+    if (!hits[n]) {
+      await io.err(`${keyword}: nothing appropriate.\n`);
+      code = NONE;
+    }
+  }
+  return code;
+}
+
+function title(file) {
+  if (file === '-') return 'stdin';
+  const leaf = file.split(/[/\\]/).pop() || file;
+  return clean(leaf.replace(/\.(md|markdown)$/i, '')) || 'stdin';
+}
+
+async function local(ctx, files) {
+  const { io, name } = ctx;
+  let code = OK;
+  for (const file of files) {
+    let text;
+    try {
+      text = await io.read(file);
+    } catch (error) {
+      await io.err(`${name}: ${clean(file)}: ${error.message}\n`);
+      code = worse(code, USAGE);
+      continue;
+    }
+    const page = render(text, { topic: title(file), width: ctx.width, styled: ctx.styled });
+    const shown = await show(page, ctx);
+    if (shown !== OK) return worse(code, shown);
+  }
+  return code;
+}
+
+async function pages(ctx, parsed) {
+  const { io, flags, values } = ctx;
+  let operands = parsed.operands;
+  let given = values.sections;
+  if (given === undefined && operands.length >= 2 && sectionName.test(operands[0])) {
+    given = operands[0];
+    operands = operands.slice(1);
+  }
+  let code = OK;
+  for (const operand of operands) {
+    let topic = operand;
+    let section = given;
+    const suffix = /^(.+)\(([0-9][A-Za-z]*)\)$/.exec(operand);
+    if (suffix) {
+      topic = suffix[1];
+      section = suffix[2];
+    }
+    const shown = clean(topic);
+    const where = section === undefined ? '' : ` in section ${clean(section)}`;
+    if (section !== undefined && !sections(section).includes('1')) {
+      await io.err(`No manual entry for ${shown}${where}\n`);
+      code = worse(code, NONE);
+      continue;
+    }
+    const wanted = flags.match ? topic : topic.toLowerCase();
+    const found = await ctx.site.page(wanted);
+    if (found.note) await io.err(`${found.note}\n`);
+    if (found.status === 'error') {
+      await io.err(`${found.message}\n`);
+      code = worse(code, USAGE);
+      continue;
+    }
+    if (found.status === 'missing') {
+      await io.err(`No manual entry for ${shown}${where}\n`);
+      code = worse(code, NONE);
+      continue;
+    }
+    if (flags.where) {
+      await io.out(`${ctx.site.address(wanted)}\n`);
+      continue;
+    }
+    const page = render(found.body, { topic: wanted, width: ctx.width, styled: ctx.styled });
+    const paged = await show(page, ctx);
+    if (paged !== OK) return worse(code, paged);
+  }
+  return code;
+}
+
+export async function run({ kind = 'man', name, argv, env, io }) {
+  const parsed = parse(kind, argv);
+  if (parsed.error) {
+    await io.err(`${name}: ${parsed.error}\n${parsed.usage ? usage(kind, name) : ''}`);
+    return USAGE;
+  }
+  if (parsed.help) {
+    await io.out(usage(kind, name));
+    return OK;
+  }
+  if (parsed.version) {
+    await io.out(`${io.version}\n`);
+    return OK;
+  }
+  if (parsed.flags.upgrade) return io.upgrade();
+  const url = base(env);
+  const ctx = {
+    io,
+    env,
+    name,
+    flags: parsed.flags,
+    values: parsed.values,
+    width: width(env, io),
+    styled: Boolean(io.tty) && !env.NO_COLOR,
+    site: site({ url, store: io.store(folder(url)), fetch: io.fetch, now: io.now, name }),
+  };
+  if (kind !== 'man') return keywords(kind, ctx, parsed);
+  if (parsed.flags.apropos) return keywords('apropos', ctx, parsed);
+  if (parsed.flags.whatis) return keywords('whatis', ctx, parsed);
+  if (parsed.operands.length === 0) {
+    await io.err("What manual page do you want?\nFor example, try 'man man'.\n");
+    return USAGE;
+  }
+  if (parsed.flags.local) return local(ctx, parsed.operands);
+  return pages(ctx, parsed);
+}