@tailglow/cli 0.2.0

package/src/help.js

@@ -0,0 +1,307 @@
+import { CLI_COMMANDS } from "./commands.generated.js";
+import { CLI_CONFIGS, CONFIG_KEYS } from "./config.js";
+import { describeFlagSyntax, toFlagName } from "./flags.js";
+
+/**
+ * The runtime's own flags, described once.
+ *
+ * Prose help and machine help both render FROM this. They were written separately at first, and the
+ * two drifted immediately: the machine form listed no global flags at all, so an agent never
+ * learned that `--all`, `--max` or `TAILGLOW_API_KEY` existed and put its credential on the command
+ * line instead. One list is the only way that stays fixed.
+ *
+ * @type {{ flag: string; argument: string | null; env: string | null; description: string }[]}
+ */
+export const GLOBAL_FLAGS = [
+  {
+    flag: "--json",
+    argument: null,
+    env: null,
+    description: "Emit JSON. Implied whenever output is piped or redirected."
+  },
+  {
+    flag: "--all",
+    argument: null,
+    env: null,
+    description:
+      "Follow pagination on a list command until the results run out or --max is reached. Owns paging, so it cannot be combined with --limit or --before."
+  },
+  {
+    flag: "--max",
+    argument: "<n>",
+    env: null,
+    description: `Total rows --all may return. Defaults to ${CLI_CONFIGS.DEFAULT_MAX_RECORDS}. Only valid with --all.`
+  },
+  {
+    flag: "--after",
+    argument: "<cursor>",
+    env: null,
+    description: "Resume a list from a cursor a previous run reported."
+  },
+  {
+    flag: "--yes",
+    argument: null,
+    env: null,
+    description:
+      "Skip the confirmation on a delete. A delete run without a terminal never prompts, so this is only needed interactively."
+  },
+  {
+    flag: "--project",
+    argument: "<id>",
+    env: "TAILGLOW_PROJECT",
+    description: "Project to act on, when a command needs one and --project-id is not given."
+  },
+  {
+    flag: "--team",
+    argument: "<id>",
+    env: "TAILGLOW_TEAM",
+    description: "Team to act on, when a command needs one and --team-id is not given."
+  },
+  {
+    flag: "--api-key",
+    argument: "<key>",
+    env: "TAILGLOW_API_KEY",
+    description:
+      "Credential to authenticate with. Prefer the environment variable: a key passed as a flag is visible in the process list and in shell history."
+  },
+  {
+    flag: "--api-url",
+    argument: "<url>",
+    env: "TAILGLOW_API_URL",
+    description: `API origin to call. Defaults to ${CLI_CONFIGS.DEFAULT_API_URL}.`
+  },
+  { flag: "--help", argument: null, env: null, description: "Describe the command and stop." },
+  { flag: "--version", argument: null, env: null, description: "Print the version and stop." }
+];
+
+/**
+ * How the CLI behaves, in the places where knowing it changes what you type.
+ *
+ * Carried in BOTH help forms for the same reason as the flag list: an agent that only ever sees the
+ * machine form was missing all of it.
+ */
+export const USAGE_NOTES = [
+  "Flags are the field name in kebab-case: a field named `time_window_minutes` is `--time-window-minutes`.",
+  "Path parameters are flags too, never positional: `--project-id prj_x`, not `tglow ... prj_x`.",
+  "A true/false flag is passed alone for true, or written attached for false: `--is-public` or `--is-public=false`.",
+  'A field typed `object`, `object[]` or `Scopes` takes JSON as a single argument: --joins \'[{"view_id":"view_b"}]\'.',
+  "A field typed `string[]` takes a comma-separated list or a JSON array.",
+  "JSON output is the API response as it was sent: read `.data` for results and `.pagination.next_cursor` to continue.",
+  "Under --all, JSON output is instead { data, truncated, next_cursor }, so a capped run can resume with --after.",
+  "`--all` replaces `--limit` and `--before` rather than combining with them: use `--max` for the total, or `--limit` alone for one page.",
+  "Deletes are immediate and unconfirmed when there is no terminal attached. Many resources delete softly; the response says so.",
+  "Precedence for anything that has a default is flag, then environment variable, then `tglow config`."
+];
+
+/** @param {import("./types.d.ts").CliCommand[]} commands */
+function listResources(commands) {
+  return [...new Set(commands.map((command) => command.resource))].sort();
+}
+
+/** @param {(typeof GLOBAL_FLAGS)[number]} entry */
+function renderGlobalFlag(entry) {
+  const left = entry.argument ? `${entry.flag} ${entry.argument}` : entry.flag;
+  return {
+    left,
+    description: entry.env ? `${entry.description} (${entry.env})` : entry.description
+  };
+}
+
+/**
+ * One command's flags, named the way they are typed rather than the way the API names them.
+ *
+ * The registry stores wire names, so handing it over unchanged tells a reader that the flag is
+ * `--show_onboarding_ui`. It is not; it is `--show-onboarding-ui`, and that cost a model three
+ * attempts to create one project.
+ *
+ * @param {import("./types.d.ts").CliCommand} command
+ */
+export function describeCommandFlags(command) {
+  // A resource reachable at two paths declares the same field in two places: `project_id` is a path
+  // parameter on the nested form AND a body field on the flat one, so listing both showed the same
+  // flag twice with contradicting requiredness. What the caller needs is what THIS command will do,
+  // which is decided by the placeholders in the path it actually calls.
+  const placeholders = new Set([...command.path.matchAll(/:([a-z_]+)/g)].map(([, name]) => name));
+
+  /** @param {import("./types.d.ts").CliField[]} fields @param {string} location */
+  const describe = (fields, location) =>
+    fields.map((field) => ({
+      flag: `--${toFlagName(field.name)}`,
+      field: field.name,
+      in: location,
+      type: field.type,
+      required: location === "path" ? true : field.required,
+      description: field.description,
+      allowed_values: field.allowed_values,
+      syntax: describeFlagSyntax(toFlagName(field.name), field.type),
+      deprecated: field.deprecated
+    }));
+
+  const path_flags = describe(
+    command.path_params.filter((field) => placeholders.has(field.name)),
+    "path"
+  );
+  const claimed = new Set(path_flags.map((entry) => entry.field));
+
+  return [
+    ...path_flags,
+    ...describe(
+      command.query_params.filter((field) => !claimed.has(field.name)),
+      "query"
+    ),
+    ...describe(
+      command.body_fields.filter((field) => !claimed.has(field.name)),
+      "body"
+    )
+  ];
+}
+
+/**
+ * The same help, for a reader that is not a person.
+ *
+ * Not the registry entry: the registry describes the API, and what a caller needs is the COMMAND
+ * LINE. Flag spelling, what is required, how to encode a value, and every global flag that
+ * applies.
+ *
+ * @param {{ resource?: string; command?: import("./types.d.ts").CliCommand }} [subject]
+ */
+export function describeForMachines({ resource, command } = {}) {
+  const globals = GLOBAL_FLAGS.map(({ flag, argument, env, description }) => ({
+    flag,
+    argument,
+    env,
+    description
+  }));
+
+  if (command) {
+    return {
+      resource: command.resource,
+      command: command.command,
+      usage: `tglow ${command.resource} ${command.command} [flags]`,
+      operation_id: command.operation_id,
+      summary: command.summary,
+      description: command.description,
+      method: command.method,
+      path: command.path,
+      alternate_paths: command.alternate_paths,
+      scopes: command.scopes,
+      notes: command.notes,
+      flags: describeCommandFlags(command),
+      global_flags: globals,
+      usage_notes: USAGE_NOTES
+    };
+  }
+
+  if (resource) {
+    return {
+      resource,
+      usage: `tglow ${resource} <command> [flags]`,
+      commands: CLI_COMMANDS.filter((entry) => entry.resource === resource).map((entry) => ({
+        command: entry.command,
+        operation_id: entry.operation_id,
+        summary: entry.summary,
+        method: entry.method,
+        path: entry.path
+      })),
+      global_flags: globals,
+      usage_notes: USAGE_NOTES
+    };
+  }
+
+  return {
+    usage: "tglow <resource> <command> [flags]",
+    resources: listResources(CLI_COMMANDS),
+    config: {
+      command: "tglow config",
+      path: CLI_CONFIGS.CONFIG_PATH,
+      keys: Object.keys(CONFIG_KEYS)
+    },
+    global_flags: globals,
+    usage_notes: USAGE_NOTES
+  };
+}
+
+export function renderRootHelp() {
+  const resources = listResources(CLI_COMMANDS);
+  const globals = GLOBAL_FLAGS.map(renderGlobalFlag);
+  const width = Math.max(...globals.map((entry) => entry.left.length));
+
+  return [
+    "tglow: the Tailglow command line",
+    "",
+    "Usage:",
+    "  tglow <resource> <command> [flags]",
+    "",
+    "Resources:",
+    ...resources.map((resource) => `  ${resource}`),
+    "  config  (stored defaults and credentials)",
+    "",
+    "Run `tglow <resource>` to list its commands, or `tglow <resource> <command> --help`.",
+    "",
+    "Global flags:",
+    ...globals.map((entry) => `  ${entry.left.padEnd(width)}  ${entry.description}`),
+    "",
+    "Notes:",
+    ...USAGE_NOTES.map((note) => `  - ${note}`)
+  ].join("\n");
+}
+
+/** @param {string} resource */
+export function renderResourceHelp(resource) {
+  const commands = CLI_COMMANDS.filter((command) => command.resource === resource);
+  if (commands.length === 0) return null;
+
+  const width = Math.max(...commands.map((command) => command.command.length));
+
+  return [
+    `tglow ${resource}`,
+    "",
+    "Commands:",
+    ...commands.map(
+      (command) => `  ${command.command.padEnd(width)}  ${command.summary} (${command.method})`
+    ),
+    "",
+    `Run \`tglow ${resource} <command> --help\` for its flags.`,
+    "Run `tglow --help` for the flags every command accepts."
+  ].join("\n");
+}
+
+/** @param {{ fields: import("./types.d.ts").CliField[]; title: string }} section */
+function renderFields({ fields, title }) {
+  if (fields.length === 0) return [];
+
+  return [
+    "",
+    `${title}:`,
+    ...fields.map((field) => {
+      const flag = toFlagName(field.name);
+      const required = field.required ? " (required)" : "";
+      const allowed =
+        field.allowed_values.length > 0 ? ` [${field.allowed_values.join(", ")}]` : "";
+      const description = field.description ? `  ${field.description}` : "";
+
+      return `  ${describeFlagSyntax(flag, field.type)}${required}${allowed}${description}`;
+    })
+  ];
+}
+
+/** @param {import("./types.d.ts").CliCommand} command */
+export function renderCommandHelp(command) {
+  const paths = [command.path, ...command.alternate_paths];
+
+  return [
+    `tglow ${command.resource} ${command.command}: ${command.summary}`,
+    "",
+    command.description,
+    "",
+    "Endpoint:",
+    ...paths.map((path) => `  ${command.method} ${path}`),
+    ...(command.scopes.length > 0 ? ["", `Scope: ${command.scopes.join(" + ")}`] : []),
+    ...renderFields({ fields: command.path_params, title: "Path parameters" }),
+    ...renderFields({ fields: command.query_params, title: "Query flags" }),
+    ...renderFields({ fields: command.body_fields, title: "Body flags" }),
+    ...(command.notes.length > 0 ? ["", "Notes:", ...command.notes.map((n) => `  - ${n}`)] : []),
+    "",
+    "Run `tglow --help` for the flags every command accepts."
+  ].join("\n");
+}

package/src/index.js

@@ -0,0 +1,370 @@
+#!/usr/bin/env node
+import { realpathSync } from "node:fs";
+import fs from "node:fs/promises";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { parseArgs } from "node:util";
+import { confirm, isCancel } from "@clack/prompts";
+import { CLI_COMMANDS } from "./commands.generated.js";
+import { runConfigCommand } from "./config-command.js";
+import { CLI_CONFIGS, loadConfig, resolveSetting } from "./config.js";
+import {
+  assertSuppliedValuesArePresent,
+  buildParserOptions,
+  buildRequestParts,
+  isIntegerText,
+  normalizeSwitches,
+  toFlagName
+} from "./flags.js";
+import {
+  describeForMachines,
+  renderCommandHelp,
+  renderResourceHelp,
+  renderRootHelp
+} from "./help.js";
+import { renderPagedResult, renderResponse, sanitizeText, shouldEmitJson } from "./output.js";
+import { requestAllPages, requestApi } from "./request.js";
+
+/** Path parameters people refer to by the shorter name they actually type. */
+const PATH_ALIASES = { project_id: "project", team_id: "team" };
+
+/**
+ * Path values a URL parser would act on rather than carry.
+ *
+ * `encodeURIComponent` leaves a dot alone, so `--team=..` would build `/v1/teams/../users/usr_x`,
+ * which `new URL` resolves to `/v1/users/usr_x`: a different endpoint than the command claims to
+ * call. There are four such collisions in the current registry.
+ */
+const UNSAFE_PATH_VALUES = new Set([".", ".."]);
+
+const PARSER_OPTIONS = buildParserOptions(CLI_COMMANDS);
+
+/** @param {string[]} argv */
+function parseFlags(argv) {
+  return parseArgs({
+    args: argv,
+    strict: false,
+    allowPositionals: true,
+    options: PARSER_OPTIONS
+  });
+}
+
+/** @param {string} token */
+function quoteToken(token) {
+  const safe = sanitizeText(token);
+  return /^[A-Za-z0-9._:/=-]+$/.test(safe) ? safe : `'${safe.replaceAll("'", `'\\''`)}'`;
+}
+
+/**
+ * Rebuilds the command as typed, minus the credential and any old cursor, plus the new one.
+ *
+ * Naming only the resource, command and cursor is not enough: `metrics list --project prj_other
+ * --all --max 1` would print a continuation with no `--project`, which either fails outright or,
+ * worse, addresses whatever project is configured using a cursor minted for a different one. The
+ * words someone typed are the only faithful description of what they asked for.
+ *
+ * @param {string[]} argv
+ * @param {string} cursor
+ */
+export function buildResumeCommand(argv, cursor) {
+  /** @type {string[]} */
+  const parts = [];
+
+  for (let index = 0; index < argv.length; index += 1) {
+    const token = argv[index];
+    const flag = token.startsWith("--") ? token.slice(2).split("=")[0] : null;
+
+    // The key must never be echoed, and the old cursor is about to be replaced.
+    if (flag === "api-key" || flag === "after") {
+      if (!token.includes("=") && PARSER_OPTIONS[flag]?.type === "string") index += 1;
+      continue;
+    }
+
+    parts.push(quoteToken(token));
+  }
+
+  return `tglow ${parts.join(" ")} --after ${quoteToken(cursor)}`;
+}
+
+/**
+ * @param {Record<string, unknown>} flags
+ * @param {string} flag
+ */
+function readFlag(flags, flag) {
+  const value = flags[flag];
+  return typeof value === "string" && value.length > 0 ? value : null;
+}
+
+/**
+ * Fills `:placeholders` from flags, then configuration.
+ *
+ * Falling back to configuration is what lets `tglow metrics list` work at all: nearly every path is
+ * project-scoped, and repeating the project on every call is the difference between a tool someone
+ * uses and one they wrap in a shell function.
+ *
+ * @param {import("./types.d.ts").CliCommand} command
+ * @param {{ flags: Record<string, unknown>; config: Record<string, string> }} sources
+ */
+function resolvePath(command, { flags, config }) {
+  const placeholders = [...command.path.matchAll(/:([a-z_]+)/g)].map(([, name]) => name);
+  /** @type {string[]} */
+  const missing = [];
+  /** @type {string[]} */
+  const unsafe = [];
+  /** @type {Set<string>} */
+  const consumed = new Set();
+
+  const path = placeholders.reduce((current, name) => {
+    // Only project and team fall back to configuration. Resolving EVERY placeholder that way would
+    // make `TAILGLOW_SOURCE_ID` an implicit delete target: `tglow sources delete --project prj_x
+    // --yes` would find a source id nobody named on the command line and destroy it.
+    const alias = PATH_ALIASES[/** @type {keyof typeof PATH_ALIASES} */ (name)] ?? null;
+    const value =
+      readFlag(flags, toFlagName(name)) ??
+      (alias ? resolveSetting(alias, { flags, config }) : null);
+
+    if (!value) {
+      missing.push(name);
+      return current;
+    }
+    if (UNSAFE_PATH_VALUES.has(value)) {
+      unsafe.push(name);
+      return current;
+    }
+
+    consumed.add(name);
+    return current.replace(`:${name}`, encodeURIComponent(value));
+  }, command.path);
+
+  return { path, missing, unsafe, consumed };
+}
+
+/** @param {import("./types.d.ts").CliCommand} command */
+function isPaginated(command) {
+  return command.method === "GET" && command.query_params.some((field) => field.name === "after");
+}
+
+async function readVersion() {
+  const manifest = join(dirname(fileURLToPath(import.meta.url)), "..", "package.json");
+  const { version } = JSON.parse(await fs.readFile(manifest, "utf-8"));
+  return version;
+}
+
+/**
+ * @param {string} message
+ * @param {{ json?: unknown }} flags
+ */
+function fail(message, flags) {
+  return { output: shouldEmitJson(flags) ? JSON.stringify({ error: message }) : message, code: 1 };
+}
+
+/**
+ * @param {import("./types.d.ts").CliCommand} command
+ * @param {Record<string, unknown>} flags
+ */
+async function confirmDestructive(command, flags) {
+  // Only a terminal gets asked. A scripted `tglow projects delete --project prj_x` already said what
+  // it meant, and blocking it on a flag would break every caller that cannot answer a prompt.
+  //
+  // JSON mode counts as scripted even on a TTY: the prompt draws itself on stdout, which would put
+  // interface text in front of the document a caller is parsing.
+  if (command.method !== "DELETE" || flags.yes || shouldEmitJson(flags)) return true;
+  if (!process.stdout.isTTY) return true;
+
+  const answer = await confirm({
+    message: `${command.summary}. This cannot be undone. Continue?`,
+    initialValue: false
+  });
+
+  return !isCancel(answer) && answer === true;
+}
+
+/**
+ * @param {string[]} argv
+ * @returns {Promise<{ output: string; code: number }>}
+ */
+export async function run(argv) {
+  const { values: flags, positionals } = parseFlags(argv);
+
+  try {
+    normalizeSwitches(flags);
+    assertSuppliedValuesArePresent(flags, PARSER_OPTIONS);
+
+    const describe = shouldEmitJson(flags);
+    /** @param {string} text @param {unknown} machine_readable */
+    const inform = (text, machine_readable) => ({
+      output: describe ? JSON.stringify(machine_readable, null, 2) : text,
+      code: 0
+    });
+
+    if (flags.version) {
+      const version = await readVersion();
+      return inform(version, { version });
+    }
+
+    const [resource, name, ...rest] = positionals;
+    if (!resource) return inform(renderRootHelp(), describeForMachines());
+    if (resource === "config") return await runConfigCommand([name, ...rest], flags);
+
+    const commands = CLI_COMMANDS.filter((entry) => entry.resource === resource);
+    if (commands.length === 0) {
+      return fail(`Unknown resource "${resource}". Run \`tglow\` for the list.`, flags);
+    }
+
+    if (!name) {
+      return inform(renderResourceHelp(resource) ?? "", describeForMachines({ resource }));
+    }
+
+    const command = commands.find((entry) => entry.command === name);
+    if (!command) {
+      return fail(
+        `Unknown command "${resource} ${name}". ` +
+          `Run \`tglow ${resource}\` for what ${resource} accepts.`,
+        flags
+      );
+    }
+    if (flags.help) return inform(renderCommandHelp(command), describeForMachines({ command }));
+
+    const config = await loadConfig();
+    const { path, missing, unsafe, consumed } = resolvePath(command, { flags, config });
+
+    if (unsafe.length > 0) {
+      const named = unsafe.map((entry) => `--${toFlagName(entry)}`).join(", ");
+      return fail(
+        `${named} cannot be "." or "..". Those resolve to a different endpoint than this command calls.`,
+        flags
+      );
+    }
+    if (missing.length > 0) {
+      // Only project and team have a stored default, so only they can be answered with `config set`.
+      // Suggesting it for a missing source or metric id sends the reader after a setting that does
+      // not exist and cannot help.
+      const configurable = missing.filter((entry) => entry in PATH_ALIASES);
+      const advice = configurable.map(
+        (entry) =>
+          `\nSet a default with \`tglow config set ${PATH_ALIASES[/** @type {keyof typeof PATH_ALIASES} */ (entry)]} <id>\` to stop repeating it.`
+      );
+
+      return fail(
+        `Missing ${missing.map((entry) => `--${toFlagName(entry)}`).join(", ")}.` + advice.join(""),
+        flags
+      );
+    }
+
+    const { query, body, unknown } = buildRequestParts(command, flags, {
+      consumed_path_fields: consumed
+    });
+    if (unknown.length > 0) {
+      return fail(
+        `Unknown flag${unknown.length === 1 ? "" : "s"}: ${unknown.map((entry) => `--${entry}`).join(", ")}.\n` +
+          `Run \`tglow ${resource} ${name} --help\` for the accepted flags.`,
+        flags
+      );
+    }
+
+    // A true/false flag never consumes the token after it, so `--is-public false` sets the flag TRUE
+    // and leaves `false` sitting here. Ignoring the leftover would send the opposite of what was
+    // typed. Checked after the unknown-flag pass, so a mistyped flag is named rather than its value.
+    if (rest.length > 0) {
+      return fail(
+        `Unexpected argument${rest.length === 1 ? "" : "s"}: ${rest.join(", ")}.\n` +
+          "A value goes after its flag (--name Acme). A true/false flag is either passed alone " +
+          "for true, or written as --flag=false.",
+        flags
+      );
+    }
+
+    if (flags.all) {
+      if (!isPaginated(command)) {
+        return fail(
+          `\`${resource} ${name}\` does not return a paginated list, so --all does not apply.`,
+          flags
+        );
+      }
+      // `--all` owns paging: it walks forwards from `after` and sizes each page itself. `--before`
+      // asks the API to page the other way at the same time, and `--limit` states a page size that
+      // the cap then has to override. Refusing both beats silently reinterpreting either.
+      if (query.before !== undefined) {
+        return fail(
+          "--before cannot be combined with --all. Use --after to choose a start.",
+          flags
+        );
+      }
+      if (query.limit !== undefined) {
+        return fail("--limit cannot be combined with --all. Use --max to cap the total.", flags);
+      }
+
+      // `--max` written bare parses as `true`, and checking `Number(raw)` rather than the text lets
+      // `1e-400` and `1.0000000000000001` through as whole numbers.
+      const raw_max = flags.max === undefined ? String(CLI_CONFIGS.DEFAULT_MAX_RECORDS) : flags.max;
+      if (typeof raw_max !== "string" || !isIntegerText(raw_max) || Number(raw_max) < 1) {
+        return fail(`--max must be a whole number of at least 1, received "${raw_max}".`, flags);
+      }
+
+      const result = await requestAllPages({
+        method: command.method,
+        path,
+        query,
+        flags,
+        config,
+        max: Number(raw_max)
+      });
+
+      return {
+        output: renderPagedResult(
+          {
+            ...result,
+            resume_command: result.next_cursor ? buildResumeCommand(argv, result.next_cursor) : ""
+          },
+          flags
+        ),
+        code: 0
+      };
+    }
+
+    // `--max` only means anything to `--all`. Accepting it alone would return one default-sized page
+    // while looking like it honoured the cap.
+    if (flags.max !== undefined) {
+      return fail("--max only applies with --all. Use --limit to size a single page.", flags);
+    }
+
+    if (!(await confirmDestructive(command, flags))) return fail("Cancelled.", flags);
+
+    const payload = await requestApi({ method: command.method, path, query, body, flags, config });
+    return { output: renderResponse(payload, flags), code: 0 };
+  } catch (err) {
+    return fail(err instanceof Error ? err.message : String(err), flags);
+  }
+}
+
+/**
+ * Whether this file was run, rather than imported.
+ *
+ * `import.meta.main` would be shorter but is Bun-only until very recent Node, and this package
+ * installs under whatever runtime the user already has. Both sides are resolved through the real
+ * path because a global install invokes the command through a symlink in `node_modules/.bin`.
+ */
+function isEntrypoint() {
+  if (!process.argv[1]) return false;
+  try {
+    return realpathSync(process.argv[1]) === realpathSync(fileURLToPath(import.meta.url));
+  } catch {
+    return false;
+  }
+}
+
+if (isEntrypoint()) {
+  // `process.exit` discards whatever is still buffered for a pipe, and a pipe's buffer is 64 KB.
+  // `tglow records list --all --json | jq` would receive a JSON document cut off mid-value, which
+  // is exactly the invariant this CLI sells. Set the code and let the write drain instead.
+  try {
+    const { output, code } = await run(process.argv.slice(2));
+    // Anything that failed belongs on stderr, so a `--json` pipeline reading stdout never has to
+    // tell a result apart from an explanation of why there is none.
+    process.exitCode = code;
+    (code === 0 ? process.stdout : process.stderr).write(`${output}\n`);
+  } catch (err) {
+    process.exitCode = 1;
+    process.stderr.write(`${err instanceof Error ? err.message : String(err)}\n`);
+  }
+}