@descent-vtt/spec-brief 0.6.0 → 0.7.0

package/CHANGELOG.md

@@ -11,6 +11,102 @@ release that can turn a run red. This is the family's policy, recorded in
 releases up to 0.2.7 came before it, and several of their patches changed
 what a run reports.
 
+## 0.7.0
+
+An input that is set and names nothing is refused, exit 2, by a line that
+names it, where it was read as if it had not been given: a
+`SOURCE_DATE_EPOCH` that is no date, an option given an empty value, an
+argument a command does not take, a `--root` that is no directory, a list
+that names no brief or has a place that names none.
+
+### Changed
+
+- **A `SOURCE_DATE_EPOCH` that is set and cannot be read as a date is
+  refused, not read as unset.** `new` and `archive` without `--date` took
+  `tomorrow`, `1.5`, `-1`, a value with a space beside its digits and an
+  empty one for no value at all, wrote the clock's date and exited 0. Each
+  now writes nothing and ends with exit 2 and a line that names the variable
+  and shows what it holds, and `today()` from the package throws for them
+  (ADR-0004, [Today's date](README.md#todays-date)).
+  Upgrading: set it to whole seconds in digits alone, as `date +%s` prints
+  them, no more than `253402300799` (9999-12-31), or pass `--date`, or leave
+  it unset; set and empty is not unset.
+- **An option given an empty value is refused by its name, not read as the
+  option left out.** `new "T" --id ""` wrote `briefs/_t.md`, a file no
+  command reads again; `--root ""` ran in the current directory; `archive
+  --summary ""` wrote a banner without the sentence; `init --briefs " "`
+  made a directory named with a space. Every option that takes a value now
+  ends the run with exit 2 and `--id is "", which is no value` for one that
+  is empty or only space, nothing written; the ones refused already say the
+  same line (ADR-0001, [An input that names nothing](README.md#an-input-that-names-nothing)).
+  Upgrading: where a script may hand an option nothing, leave the option
+  out, as `${ID:+--id "$ID"}` does in a shell.
+- **`new --depends-on` refuses a list that names no brief, and a place in
+  one that names none.** `--depends-on ,` scaffolded a brief with no
+  dependency, and `7,8,` or `7,,8` one that depends on 7 and 8, as `"$A,$B"`
+  with `$B` unset made one that depends on `$A` alone, each exit 0.
+  Upgrading: leave the option out for a brief that depends on nothing, and
+  write the list with one comma between each two ids and none at either end.
+- **`init`, `list`, `matrix` and `schedule` refuse an argument, which they
+  do not take.** `list nonsense` listed every brief, `schedule later
+  --write` ran as `schedule --write`, and `init mydir` set up the current
+  directory, each exit 0; each is now exit 2 with the argument named and the
+  command's usage. Upgrading: drop the argument; `init --root mydir` sets up another
+  directory, and `--briefs mydir` names the one for the briefs.
+- **A `--root` that is no directory is refused.** Given a file or a path
+  that does not exist, the search for a configuration went on from its
+  parent: `lint --root tpyo` linted the tree above, and `new --root tpyo`
+  wrote into it, exit 0. `init` still makes a root that is not there.
+  Upgrading: give `--root` a directory that exists.
+
+### Fixed
+
+- A terminal that says `TERM=dumb` gets no colour, unless `FORCE_COLOR` or
+  `--color` asks for it, as the family's other tools have it. It was sent
+  the escape sequences it had said it does not read.
+- A `SOURCE_DATE_EPOCH` that cannot be read stops only a run that would
+  write its date. One of more seconds than any date has ended `lint`,
+  `list`, `matrix`, `schedule`, `init` and `unarchive`, and `new` and
+  `archive` given `--date`, with exit 2; they now run whatever it holds.
+- A `SOURCE_DATE_EPOCH` in the years 10000 to 275760 is refused by name,
+  where `new` and `archive` said `"+010000-01" is not a date written
+  YYYY-MM-DD`. Exit 2, as before.
+- The README says what `SOURCE_DATE_EPOCH` does, and `--help` names it
+  beside `--date`.
+- A configuration that is a directory, named by `--config` or found as
+  `.spec-brief.json`, is said in one line, `adir: is a directory, not a
+  configuration file`, where the run ended on `unexpected error: Error:
+  EISDIR` and a stack. Exit 2, as before.
+- A configuration that is not JSON is refused in one line whatever the file
+  holds. A line break the parser quoted from it made the refusal two lines,
+  and any other control character reached the terminal as it was; each is
+  now written as its escape. Exit 2, as before.
+
+## 0.6.1
+
+Four ways a run ended with `unexpected error:` and a stack for something
+that was no defect of spec-brief's. Each is one line now; every exit code is
+as it was.
+
+### Fixed
+
+- **A reader that closes the output is answered in one line, not a stack.**
+  `spec-brief list | head` could end with `spec-brief: unexpected error:
+  Error: EPIPE: broken pipe, write` and a stack once `head` had left; it now
+  prints `spec-brief: stdout was closed before all of the output was
+  written` on stderr, exit 2 as before
+  ([the family contract](https://github.com/DescentVTT/spec-core/blob/main/docs/adr/0005-the-family-contract.md)).
+- A `SOURCE_DATE_EPOCH` of more seconds than any date has is named, with
+  what to do about it, where the run ended on `RangeError: Invalid time
+  value` and a stack. Exit 2, as before.
+- `archive` reports what git was not handed or could not do by its message
+  alone: `"-x" is not a revision` for a `--commit`, a `--base` or an
+  `archiving.base` that would be read as an option, and git's own words
+  when its status or its diff fails. Exit 2, as before.
+- `init --briefs ../docs` and `--archive` likewise are refused as the
+  configuration refuses them, `--briefs must be a directory inside the
+  repository`, where the path's error came with a stack. Exit 2, as before.
+
 ## 0.6.0
 
 An error spec-brief did not expect before a command started, or where

package/README.md

@@ -95,11 +95,11 @@ A brief is read as CommonMark reads it wherever that decides what is code or a c
 
 ### `spec-brief init`
 
-Writes `.spec-brief.json` with every default spelled out, and creates the brief and archive directories. `--briefs <dir>` and `--archive <dir>` choose them.
+Writes `.spec-brief.json` with every default spelled out, and creates the brief and archive directories. `--briefs <dir>` and `--archive <dir>` choose them, and `--root <dir>` the directory to set up, which `init` makes when it is not there. It takes no argument: `init mydir` is [refused](#an-input-that-names-nothing).
 
 ### `spec-brief new <title>`
 
-Scaffolds a brief with the next free number - one more than the highest id, live or archived, since ids are never reused - and every required section, each holding its `hint` in a comment. A comment is not content, so a fresh brief reads as unwritten until someone writes it. `--id`, `--type`, `--wave`, `--depends-on 7,8` and `--date` fill the front matter.
+Scaffolds a brief with the next free number - one more than the highest id, live or archived, since ids are never reused - and every required section, each holding its `hint` in a comment. A comment is not content, so a fresh brief reads as unwritten until someone writes it. `--id`, `--type`, `--wave`, `--depends-on 7,8` and `--date` fill the front matter; without `--date` the date is [today's](#todays-date).
 
 ### `spec-brief lint [brief...]`
 
@@ -230,6 +230,7 @@ With `archiving.rewriteLinks` off, no link is rewritten, and the links other liv
 | `--base <rev>` | Measures from the merge base instead, for a branch of several commits. |
 | `--pr <n>` | Links the pull request. |
 | `--summary <text>` | What the round did, in the banner. |
+| `--date <YYYY-MM-DD>` | The date in the banner, where it is not [today's](#todays-date). |
 | `--dry-run` | Prints the plan and the banner, and writes nothing. |
 
 spec-brief reads git and never writes it. Review the change and commit it with the round.
@@ -247,13 +248,13 @@ Reopens an archived brief: the banner and the hash come off, the status goes bac
 
 | Flag | What it does |
 | --- | --- |
-| `--root <dir>` | Runs from another directory. |
+| `--root <dir>` | Runs from another directory, which must be there: only `init` makes one that is not. |
 | `--config <file>` | Names the configuration. |
 | `--no-config` | Uses the defaults. |
 | `--format <format>` | `pretty` by default, or `json`; `lint`, `matrix` and `schedule`, which report findings, also write `sarif`, `github` and `gitlab`, and `--help` lists each command's formats. |
 | `--strict` | Makes warnings fail the run. |
 | `--no-git` | Leaves git out even inside a repository: the tree is read from disk, and `archive` records no commit. |
-| `--color`, `--no-color` | Override `NO_COLOR`, `FORCE_COLOR` and the terminal check. |
+| `--color`, `--no-color` | Override `NO_COLOR`, `FORCE_COLOR`, `TERM=dumb` and the terminal check. |
 | `--help`, `--version` | Do what they say. |
 
 **Exit codes:**
@@ -262,10 +263,28 @@ Reopens an archived brief: the banner and the hash come off, the status goes bac
 | --- | --- |
 | `0` | Clean. |
 | `1` | Findings, a collision, or a refused action. |
-| `2` | The run could not be trusted - a bad flag, a configuration that does not load, a brief that does not exist, or an error spec-brief did not expect, reported on stderr as `spec-brief: unexpected error:` with its stack. |
+| `2` | The run could not be trusted, or its answer did not arrive - a bad flag, [an input that names nothing](#an-input-that-names-nothing), a configuration that does not load, a brief that does not exist, a git command that failed, a `SOURCE_DATE_EPOCH` that [cannot be read as a date](#todays-date) where one is to be written, a stdout its reader closed before all of the output was written, as a pipeline into `head` does, each said in one line on stderr, or an error spec-brief did not expect, reported on stderr as `spec-brief: unexpected error:` with its stack. |
 
 A run over a briefs directory that does not exist exits 2, because a check over nothing looks exactly like a clean one.
 
+### An input that names nothing
+
+An option, an argument or a path that is given and names nothing is refused: exit 2, one line that names it, nothing written. None is read as if it had not been given. `--root "$DIR"` where the variable is not set would otherwise run in the current directory, and the answer would look like the one that was asked for.
+
+- **An option given nothing.** Every option that takes a value refuses one that is empty or only space, by the option's name: `--id is "", which is no value`. No option gives an empty value a meaning; leave the option out for what it does by default.
+- **A list that names nothing.** `--depends-on ,` names no brief, and a brief that depends on nothing is one scaffolded without the option. A place in a list that names no brief, the comma too many in `7,8,` or the gap in `7,,8`, is refused as well: it is a brief left out, as `"$A,$B"` is with one of the two unset.
+- **An argument a command does not take.** `init`, `list`, `matrix` and `schedule` take none and refuse one by name, with their usage. `init mydir` set up the current directory; `init --root mydir` is what sets up another.
+- **A `--root` that is no directory.** A file, or a path that does not exist, is refused: the search for a configuration would go on from its parent, and the run would report on, or `new` write into, the tree above. A directory below the configuration's is a place to start from, as the current directory is.
+- **A configuration that is a directory**, named by `--config` or found under the configuration's name, does not load, and is said so in a line, as one that is not JSON is.
+
+### Today's date
+
+`new` writes a date into the front matter and `archive` one into the banner: the one `--date` gives, or today's. Today is the clock's date in UTC, unless `SOURCE_DATE_EPOCH` is set, the variable a pipeline sets to have every run write the same bytes ([its specification](https://reproducible-builds.org/specs/source-date-epoch/)): then it is the date of that time, in UTC.
+
+- **What it holds**: whole seconds since 1970-01-01 in digits alone, as `date +%s` prints them, from `0` to `253402300799`, the last second of 9999-12-31 and of the dates written `YYYY-MM-DD`.
+- **Anything else is refused**, never read as unset: a word, `1.5`, `-1`, a space or a newline beside the digits, a later time, or nothing at all, which is what `SOURCE_DATE_EPOCH=$(git log -1 --format=%ct)` leaves where git failed. `new` and `archive` then write nothing and exit 2 with a line that names the variable and shows what it holds. The clock's date, written where a pipeline asked for its own, would look like any other.
+- **Only a run that would use it reads it**: `--date` gives the date instead, and `init`, `lint`, `list`, `matrix`, `schedule`, `unarchive`, `--version` and `--help` write none, so each runs whatever the variable holds.
+
 ## Configuration
 
 `.spec-brief.json` (or `spec-brief.json`) at the root; the nearest one above the working directory is used, and its directory is the root. It is JSON, validated against [`schema.json`](schema.json): an unknown key, a misspelt rule or a value of the wrong type stops the run with exit 2 rather than falling back to defaults and reporting on the wrong rules.

package/bin/spec-brief.js

@@ -7,8 +7,15 @@
 // main answers the errors it awaits with exit 2. What nothing awaits - a
 // stream's error, a timer's, a promise nobody holds - Node ends with exit 1,
 // which a script reads as findings: the same answer for those.
+//
+// A reader that closed stdout, as `| head` does, is no defect, and it arrives
+// here, as the stream's error: one line, with no stack to send a person
+// looking for a bug. The code alone names it, since stdout and stderr are the
+// only pipes spec-brief writes to, and a line about a closed stderr reaches
+// nobody.
 process.on('uncaughtException', (error) => {
-  process.stderr.write(`spec-brief: unexpected error: ${error?.stack ?? error}\n`);
+  const said = error?.code === 'EPIPE' ? 'stdout was closed before all of the output was written' : `unexpected error: ${error?.stack ?? error}`;
+  process.stderr.write(`spec-brief: ${said}\n`);
   process.exit(2);
 });
 

package/dist/cli.js

@@ -6,13 +6,14 @@
  * that does not load, a brief that does not exist. A run that checked nothing
  * must never exit as though it found nothing.
  */
-import { readFile } from 'node:fs/promises';
+import { readFile, stat } from 'node:fs/promises';
 import { parseArgs } from 'node:util';
 import { TransactionError, ConflictError } from './apply.js';
 import { reported } from './collisions.js';
 import { CONFIG_FILES, ConfigError, initialConfig } from './config.js';
 import { BriefEngine, EngineError, today } from './engine.js';
 import { NodeFileSystem } from './fs.js';
+import { GitError } from './git.js';
 import { failing, sortFindings, summarise } from './lint.js';
 import { normalisePath } from './links.js';
 import { briefJson, findingJson, FORMATS, githubCommands, gitlabCodeQuality, jsonDocument, matrixJson, planJson, prettyFindings, prettyList, prettyMatrix, prettyPlan, prettySchedule, sarif, scheduleJson, sectionsJson, summaryLine, } from './report.js';
@@ -38,7 +39,11 @@ const GLOBAL = {
     version: { type: 'boolean', short: 'v' },
 };
 const TABLE = {
-    init: { options: { briefs: { type: 'string' }, archive: { type: 'string' } }, formats: ['pretty', 'json'] },
+    init: {
+        options: { briefs: { type: 'string' }, archive: { type: 'string' } },
+        formats: ['pretty', 'json'],
+        noArgument: '; --root <dir> names the directory it sets up, and --briefs <dir> the one for the briefs',
+    },
     new: {
         options: {
             id: { type: 'string' },
@@ -50,9 +55,9 @@ const TABLE = {
         formats: ['pretty', 'json'],
     },
     lint: { options: {}, formats: FORMATS },
-    list: { options: { ready: { type: 'boolean' }, archived: { type: 'boolean' } }, formats: ['pretty', 'json'] },
-    matrix: { options: { 'all-waves': { type: 'boolean' } }, formats: FORMATS },
-    schedule: { options: { write: { type: 'boolean' } }, formats: FORMATS },
+    list: { options: { ready: { type: 'boolean' }, archived: { type: 'boolean' } }, formats: ['pretty', 'json'], noArgument: '' },
+    matrix: { options: { 'all-waves': { type: 'boolean' } }, formats: FORMATS, noArgument: '' },
+    schedule: { options: { write: { type: 'boolean' } }, formats: FORMATS, noArgument: '' },
     archive: {
         options: {
             pr: { type: 'string' },
@@ -104,7 +109,7 @@ Commands:
   unarchive <brief>     reopen an archived brief
 
 Options for every command:
-  --root <dir>          run from this directory instead of the current one
+  --root <dir>          run from this directory instead of the current one; it must exist, unless init makes it
   --config <file>       use this configuration file
   --no-config           use the defaults, ignoring any configuration file
   --format <format>     the output format, pretty by default; each command's are below
@@ -126,7 +131,7 @@ new:
   --type <type>         a brief type from the configuration
   --wave <n>            the wave it runs in
   --depends-on <ids>    comma-separated ids it runs after
-  --date <YYYY-MM-DD>   the date in its front matter; default today
+  --date <YYYY-MM-DD>   the date in its front matter; default SOURCE_DATE_EPOCH's, or today's in UTC
 
 list:
   --ready               only briefs that can run now: dependencies archived, not drafts or deferred
@@ -143,13 +148,16 @@ archive:
   --commit <rev>        the commit the round landed as
   --base <rev>          the branch it started from; the diff runs from the merge base
   --summary <text>      what the round did, for the banner
-  --date <YYYY-MM-DD>   the archival date; default today
+  --date <YYYY-MM-DD>   the archival date; default SOURCE_DATE_EPOCH's, or today's in UTC
   --allow-dirty         archive although the tree has uncommitted work
   --dry-run             print the plan and change nothing
 
 unarchive:
   --dry-run             print the plan and change nothing
 
+An option given an empty value, a list that names nothing and an argument a
+command does not take are refused, not read as if they were not there.
+
 Exit codes: 0 clean, 1 findings or refused, 2 the run could not be trusted.
 `;
 /** Global options that take a value, so the value is not mistaken for the command. */
@@ -174,18 +182,34 @@ export function parse(argv) {
     if (command !== undefined && spec === undefined) {
         throw new UsageError(`"${command}" is not a command; run spec-brief --help`);
     }
+    let parsed;
     try {
-        const { values, positionals } = parseArgs({
+        parsed = parseArgs({
             args: [...argv],
             options: { ...GLOBAL, ...(spec?.options ?? {}) },
             allowPositionals: true,
             strict: true,
         });
-        return { command, values: values, positionals: positionals.slice(1) };
     }
     catch (error) {
         throw new UsageError(error.message);
     }
+    const positionals = parsed.positionals.slice(1);
+    // What the parser takes is not yet what names something. An option whose
+    // value is empty, as `--root "$DIR"` is where the variable is not set, was
+    // read as the option left out, and an argument no command asked for was
+    // dropped: either way the run answered a question nobody had put, exit 0.
+    for (const [name, value] of Object.entries(parsed.values)) {
+        if (typeof value === 'string' && value.trim() === '') {
+            // Shown as JSON, where a tab or a line break in it can be seen.
+            throw new UsageError(`--${name} is ${JSON.stringify(value)}, which is no value; give it one, or leave the option out`);
+        }
+    }
+    if (spec?.noArgument !== undefined && positionals.length > 0) {
+        const extra = positionals.map((argument) => `"${argument}"`).join(', ');
+        throw new UsageError(`${command} takes no argument, not ${extra}: spec-brief ${command}${spec.noArgument}`);
+    }
+    return { command, values: parsed.values, positionals };
 }
 /** The value of an option declared a string, which is all `parseArgs` gives one. */
 function text(values, key) {
@@ -217,6 +241,10 @@ function useColor(values, io) {
     const force = env['FORCE_COLOR'];
     if (force !== undefined && force !== '')
         return force !== '0';
+    // A terminal that says it is dumb has asked for no escape sequence, and
+    // Node itself counts one colour for it: the family's tools read it alike.
+    if (env['TERM'] === 'dumb')
+        return false;
     return (io.stdout ?? process.stdout).isTTY === true;
 }
 async function openEngine(run) {
@@ -257,8 +285,18 @@ async function runInit(run) {
         if (await fs.exists(name))
             throw new UsageError(`${name} already exists here; edit it instead`);
     }
-    const briefs = normalisePath(text(run.values, 'briefs') ?? 'briefs');
-    const archive = normalisePath(text(run.values, 'archive') ?? `${briefs}/archive`);
+    // A directory above the root is refused as the configuration refuses one
+    // (config.ts), in the same words, before anything is written.
+    const inside = (option, given) => {
+        try {
+            return normalisePath(given);
+        }
+        catch {
+            throw new UsageError(`--${option} must be a directory inside the repository, not "${given}"`);
+        }
+    };
+    const briefs = inside('briefs', text(run.values, 'briefs') ?? 'briefs');
+    const archive = inside('archive', text(run.values, 'archive') ?? `${briefs}/archive`);
     if (briefs === '' || archive === '' || briefs === archive)
         throw new UsageError('--briefs and --archive must be two directories');
     const config = `${JSON.stringify(initialConfig(briefs, archive), null, 2)}\n`;
@@ -281,18 +319,26 @@ async function runNew(run) {
     const title = run.positionals.join(' ').trim();
     if (title === '')
         throw new UsageError('new needs a title: spec-brief new "<title>"');
+    const listed = text(run.values, 'depends-on');
+    const dependsOn = listed?.split(',').map((d) => d.trim());
+    // A list that names no brief is not a brief that depends on none: written
+    // as given, "," scaffolded a brief with no dependency and said nothing.
+    if (dependsOn?.every((d) => d === '')) {
+        throw new UsageError(`--depends-on is ${JSON.stringify(listed)}, which names no brief; give it ids with commas between them, as in 7,8, or leave the option out`);
+    }
+    // And a place in it that names none is a brief left out: "$A,$B" with one
+    // of the two unset scaffolded a brief that depends on the other alone.
+    if (dependsOn?.includes('')) {
+        throw new UsageError(`--depends-on is ${JSON.stringify(listed)}, which names no brief in one of its places; give it ids with one comma between each two, as in 7,8, and none before or after`);
+    }
     const engine = await openEngine(run);
-    const dependsOn = text(run.values, 'depends-on')
-        ?.split(',')
-        .map((d) => d.trim())
-        .filter((d) => d !== '');
     const created = await engine.create({
         title,
         id: text(run.values, 'id'),
         type: text(run.values, 'type'),
         wave: integer(run.values, 'wave', 0),
         dependsOn,
-        date: text(run.values, 'date') ?? run.today,
+        date: text(run.values, 'date') ?? run.today(),
     });
     if (run.format === 'json')
         run.out(jsonDocument('new', run.version, { ok: true, file: created.file }));
@@ -378,7 +424,7 @@ async function runTransition(run, action) {
             commit: text(run.values, 'commit'),
             base: text(run.values, 'base'),
             summary: text(run.values, 'summary'),
-            date: text(run.values, 'date') ?? run.today,
+            date: text(run.values, 'date') ?? run.today(),
             allowDirty: flag(run.values, 'allow-dirty'),
             strict: run.strict,
             noGit: flag(run.values, 'no-git'),
@@ -409,7 +455,7 @@ export async function main(argv = process.argv.slice(2), io = {}) {
     }
     const { command, values, positionals } = parsed;
     // From here on, so that what comes before a command is covered as the
-    // command is: --version and --help, the package's own manifest, the date.
+    // command is: --version and --help, the package's own manifest, the colour.
     // An error there left main as a rejection, which the launcher ended as
     // Node's uncaught error with exit 1, "findings" to a script.
     try {
@@ -428,8 +474,20 @@ export async function main(argv = process.argv.slice(2), io = {}) {
             err(`--format for ${command} is one of ${spec.formats.join(', ')}, not "${format}"`);
             return EXIT_ERROR;
         }
+        // A file, or a name with nothing behind it, had the search for a
+        // configuration go on from its parent: the run reported on a tree nobody
+        // had named, and `new` wrote into it. A path that cannot be reached is
+        // not there to the run either. `init` alone is given a directory that
+        // does not exist yet, which it makes.
+        const root = text(values, 'root');
+        if (root !== undefined) {
+            const found = await stat(root).catch(() => null);
+            if (found === null ? command !== 'init' : !found.isDirectory()) {
+                throw new UsageError(`--root is "${root}", which is no directory; give it one, or leave the option out`);
+            }
+        }
         const run = {
-            today: today(io.env ?? process.env),
+            today: () => today(io.env ?? process.env),
             out: (t) => {
                 stdout.write(t);
             },
@@ -463,12 +521,24 @@ export async function main(argv = process.argv.slice(2), io = {}) {
         }
     }
     catch (error) {
-        const expected = [ConfigError, UsageError, EngineError, ConflictError, TransactionError];
+        // What git refused or could not do is git's message, and no line here.
+        const expected = [ConfigError, UsageError, EngineError, ConflictError, TransactionError, GitError];
         if (expected.some((kind) => error instanceof kind)) {
             err(error.message);
             return EXIT_ERROR;
         }
-        err(`unexpected error: ${error instanceof Error ? (error.stack ?? error.message) : String(error)}`);
+        // A write its reader had closed the pipe for is no defect either: the
+        // answer was not delivered, which is still 2, and no stack sends a person
+        // looking for a bug. The process's own streams report it as an event,
+        // which the launcher answers in the same words; here it is a caller's
+        // stream that throws it. It is read by its code: stdout and stderr are the
+        // only pipes spec-brief writes to.
+        if (!(error instanceof Error))
+            err(`unexpected error: ${String(error)}`);
+        else if (error.code === 'EPIPE')
+            err('stdout was closed before all of the output was written');
+        else
+            err(`unexpected error: ${error.stack ?? error.message}`);
         return EXIT_ERROR;
     }
 }