Building CLI Tools

{
  "name": "bookshelf-cli",
  "version": "0.1.0",
  "description": "Manage the Bookshelf catalogue from a terminal",
  "type": "module",
  "bin": {
    "bookshelf": "./bin/bookshelf.js"
  },
  "files": [
    "bin",
    "src"
  ],
  "engines": {
    "node": ">=22"
  },
  "license": "MIT"
}

#!/usr/bin/env node
import { constants } from 'node:os';
import { stdout } from 'node:process';
import { main } from '../src/main.js';

const controller = new AbortController();
let caught;
for (const name of ['SIGINT', 'SIGTERM']) {
  process.once(name, () => {
    caught = name;
    controller.abort();
  });
}

// A closed pipe (`bookshelf list | head -n 1`) is not a failure.
stdout.on('error', (err) => {
  if (err.code === 'EPIPE') process.exit(0);
  throw err;
});

const code = await main(process.argv.slice(2), { signal: controller.signal });
// Shell convention: a process ended by signal N reports 128 + N.
process.exitCode = caught ? 128 + constants.signals[caught] : code;

import { parseArgs, styleText } from 'node:util';
// ...
export async function main(argv, { signal } = {}) {
  try {
    const { values, positionals } = parseArgs({
      args: argv,
      allowPositionals: true,
      allowNegative: true,
      options: {
        help: { type: 'boolean', short: 'h' },
        version: { type: 'boolean', short: 'v' },
        json: { type: 'boolean' },
        color: { type: 'boolean' },
        file: { type: 'string', short: 'f' },
        year: { type: 'string', short: 'y' },
      },
    });
    const [command, ...rest] = positionals;
    if (values.help) { console.log(HELP); return EXIT.OK; }
    if (values.version) { console.log(pkg.version); return EXIT.OK; }
    if (!command) throw new UsageError('missing command');
    // ...
  } catch (err) {
    if (err instanceof UsageError || String(err.code).startsWith('ERR_PARSE_ARGS_')) {
      stderr.write(`bookshelf: ${err.message}\nTry 'bookshelf --help'.\n`);
      return EXIT.USAGE;
    }
    // ...
  }
}

$ bookshelf frobnicate; echo "exit $?"
bookshelf: unknown command 'frobnicate'
Try 'bookshelf --help'.
exit 2
$ bookshelf list --bogus 2>&1 | head -n 1
bookshelf: Unknown option '--bogus'. To specify a positional argument starting with a '-', place it at the end of the command after '--', as in '-- "--bogus"
$ bookshelf --version
0.1.0

const config = await loadConfig({ file: values.file, color: values.color });
const paint = (format, text) => (config.color ? styleText(format, text, { stream: stdout }) : text);
// ...
case 'list': {
  const lines = values.json || !stdout.isTTY;
  for (const b of books) {
    console.log(lines ? JSON.stringify(b) : `${paint('bold', b.title)} ${paint('dim', `(${b.year})`)}`);
  }
  return EXIT.OK;
}

$ bookshelf list                      # TTY, colours on
'\x1b[1mDune\x1b[22m \x1b[2m(1965)\x1b[22m\r\n\x1b[1mHyperion\x1b[22m ...'
$ bookshelf list --no-color           # TTY, flag
'Dune (1965)\r\nHyperion (1989)\r\n...'
$ NO_COLOR=1 bookshelf list           # TTY, environment
'Dune (1965)\r\nHyperion (1989)\r\n...'
$ bookshelf list | cat                # not a TTY
{"title":"Dune","year":1965}
{"title":"Hyperion","year":1989}

import { createInterface } from 'node:readline/promises';
import { stdin, stderr } from 'node:process';

// Interactive only: the caller checks stdin.isTTY first. Prompts go to stderr so stdout stays clean.
export async function ask(questions, { signal } = {}) {
  const rl = createInterface({ input: stdin, output: stderr });
  // On a terminal Ctrl+C is a keystroke (raw mode), not a signal: readline reports it as 'SIGINT'.
  const cancelled = new AbortController();
  rl.once('SIGINT', () => cancelled.abort());
  const abort = AbortSignal.any([cancelled.signal, ...(signal ? [signal] : [])]);
  try {
    const answers = {};
    for (const [key, query] of Object.entries(questions)) {
      answers[key] = (await rl.question(`${query}: `, { signal: abort })).trim();
    }
    return answers;
  } catch (err) {
    // Ctrl+D also rejects with an AbortError, but nobody aborted our signal: report it as plain failure.
    if (err.name === 'AbortError' && !abort.aborted) throw new Error('input ended before every question was answered');
    throw err;
  } finally {
    rl.close();
  }
}

case 'import': {
  let count = 0;
  // The signal option closes the interface (ending the loop) when the caller aborts.
  for await (const line of createInterface({ input: stdin, crlfDelay: Infinity, signal })) {
    if (line.trim() === '') continue;
    books.push(JSON.parse(line));
    count++;
  }
  signal?.throwIfAborted();                          // interrupted: save nothing
  await writeBooks(config.file, books);
  console.error(`imported ${count} books`);
  return EXIT.OK;
}

$ printf '{"title":"Hyperion","year":1989}\n{"title":"Solaris","year":1961}\n' | bookshelf import
imported 2 books
$ bookshelf list | head -n 1
{"title":"Dune","year":1965}

import { text } from 'node:stream/consumers';
import { stdin } from 'node:process';

// Fine for small inputs; for large ones read line by line instead.
const input = await text(stdin);
const books = JSON.parse(input);
console.log(`${books.length} books, first: ${books[0]?.title}`);

2 books, first: Dune

SIGTERM  ->  exit status 143, nothing written to the catalogue
SIGINT   ->  exit status 130, nothing written to the catalogue

import { readFile } from 'node:fs/promises';
import { homedir } from 'node:os';
import { join } from 'node:path';

const defaults = {
  file: join(process.env.XDG_DATA_HOME ?? join(homedir(), '.local', 'share'), 'bookshelf', 'books.json'),
  color: true,
};

async function readConfigFile() {
  const dir = process.env.XDG_CONFIG_HOME ?? join(homedir(), '.config');
  const path = join(dir, 'bookshelf', 'config.json');
  try {
    return JSON.parse(await readFile(path, 'utf8'));
  } catch (err) {
    if (err.code === 'ENOENT') return {};            // no config file is fine
    throw new Error(`cannot use ${path}: ${err.message}`);
  }
}

// Precedence, lowest to highest: defaults < config file < environment < command-line flags.
export async function loadConfig(flags) {
  const fromEnv = {};
  if (process.env.BOOKSHELF_FILE) fromEnv.file = process.env.BOOKSHELF_FILE;
  if (process.env.NO_COLOR) fromEnv.color = false;
  const fromFlags = Object.fromEntries(Object.entries(flags).filter(([, v]) => v !== undefined));
  return { ...defaults, ...(await readConfigFile()), ...fromEnv, ...fromFlags };
}

$ cat $XDG_CONFIG_HOME/bookshelf/config.json
{ "file": "/work/from-config.json" }
$ bookshelf add A -y 2000                                    # config file  -> /work/from-config.json
$ BOOKSHELF_FILE=/work/from-env.json bookshelf add B -y 2001   # environment   -> /work/from-env.json
$ BOOKSHELF_FILE=/work/from-env.json bookshelf add C -y 2002 --file /work/from-flag.json   # flag -> /work/from-flag.json

import { loadEnvFile } from 'node:process';

// Load ./.env if it exists; variables already in the environment win over the file.
try {
  loadEnvFile('.env');
} catch (err) {
  if (err.code !== 'ENOENT') throw err;
}
console.log(process.env.BOOKSHELF_FILE ?? '(BOOKSHELF_FILE not set)');

$ node env-demo.mjs
/tmp/from-dotenv.json
$ BOOKSHELF_FILE=/tmp/from-shell.json node env-demo.mjs
/tmp/from-shell.json
$ cd .. && node envdemo/env-demo.mjs
(BOOKSHELF_FILE not set)

import { test } from 'node:test';
import assert from 'node:assert/strict';
import { spawn, spawnSync } from 'node:child_process';
import { mkdtempSync } from 'node:fs';
import { tmpdir } from 'node:os';
import { join } from 'node:path';

const bin = new URL('../bin/bookshelf.js', import.meta.url).pathname;
const env = { ...process.env, BOOKSHELF_FILE: join(mkdtempSync(join(tmpdir(), 'shelf-')), 'books.json'), XDG_CONFIG_HOME: tmpdir() };
const run = (args, input) => spawnSync(process.execPath, [bin, ...args], { env, input, encoding: 'utf8' });

test('a usage error exits with 2 and explains itself on stderr', () => {
  const { status, stdout, stderr } = run(['frobnicate']);
  assert.equal(status, 2);
  assert.equal(stdout, '');
  assert.match(stderr, /unknown command 'frobnicate'/);
});

test('imported books come back as NDJSON when stdout is a pipe', () => {
  assert.equal(run(['import'], '{"title":"Dune","year":1965}\n').status, 0);
  const { status, stdout } = run(['list']);
  assert.equal(status, 0);
  assert.deepEqual(JSON.parse(stdout.trim()), { title: 'Dune', year: 1965 });
});

test('SIGTERM during import exits with 143 and saves nothing', async () => {
  const child = spawn(process.execPath, [bin, 'import'], { env, stdio: ['pipe', 'ignore', 'ignore'] });
  await new Promise((resolve) => setTimeout(resolve, 500));   // let it start reading stdin
  child.kill('SIGTERM');
  const [code, signal] = await new Promise((resolve) => child.on('close', (c, s) => resolve([c, s])));
  assert.deepEqual([code, signal], [143, null]);
});

✔ a usage error exits with 2 and explains itself on stderr
✔ imported books come back as NDJSON when stdout is a pipe
✔ SIGTERM during import exits with 143 and saves nothing
ℹ pass 3
ℹ fail 0

$ npm pack --dry-run
npm notice package: bookshelf-cli@0.1.0
npm notice Tarball Contents
npm notice 687B bin/bookshelf.js
npm notice 291B package.json
npm notice 1.1kB src/config.js
npm notice 4.0kB src/main.js
npm notice 1.1kB src/prompt.js
npm notice 615B src/store.js
npm notice package size: 3.2 kB
npm notice unpacked size: 7.8 kB
npm notice total files: 6

$ npm pack --pack-destination ..
$ cd ../consumer && npm install ../bookshelf-cli-0.1.0.tgz
added 1 package, and audited 2 packages in 353ms
$ ls -l node_modules/.bin
bookshelf -> ../bookshelf-cli/bin/bookshelf.js
$ npx bookshelf --version
0.1.0
$ npm exec -- bookshelf --help
usage: bookshelf <command> [options]

npx esbuild bin/bookshelf.js --bundle --platform=node --format=esm --outfile=bookshelf.mjs
cat > sea-config.json <<'JSON'
{
  "main": "bookshelf.mjs",
  "mainFormat": "module",
  "output": "bookshelf-sea",
  "disableExperimentalSEAWarning": true
}
JSON
node --build-sea sea-config.json
codesign --sign - bookshelf-sea      # macOS only; see below
./bookshelf-sea --version

Generated single executable /Users/.../v26.10.0/bin/node + sea-config.json -> bookshelf-sea
$ ls -l bookshelf-sea
-rwxr-xr-x  1 user  wheel  144953248 ...  bookshelf-sea
$ ./bookshelf-sea --version
0.1.0
$ BOOKSHELF_FILE=./s.json ./bookshelf-sea add Z -y 2020 && BOOKSHELF_FILE=./s.json ./bookshelf-sea list
added Z
{"title":"Z","year":2020}
$ ./bookshelf-sea frob; echo $?
bookshelf: unknown command 'frob'
Try 'bookshelf --help'.
2
$ ./bookshelf-sea --help | head -n 1
usage: bookshelf <command> [options]

import { parseArgs, styleText } from 'node:util';
import { createInterface } from 'node:readline/promises';
import { stdin, stdout, stderr } from 'node:process';
import { loadConfig } from './config.js';
import { readBooks, writeBooks } from './store.js';
import { ask } from './prompt.js';
import pkg from '../package.json' with { type: 'json' };

export const EXIT = { OK: 0, FAILURE: 1, USAGE: 2, SIGINT: 130 };

const HELP = `usage: bookshelf <command> [options]

commands:
  list                     print the catalogue (NDJSON when piped)
  add [title] [-y year]    add a book, prompting for what is missing
  import                   read NDJSON books from standard input

options:
  -f, --file <path>        catalogue file
  -h, --help               show this help
  -v, --version            print the version
      --json               force NDJSON output
      --no-color           disable colours`;

class UsageError extends Error {}

export async function main(argv, { signal } = {}) {
  try {
    const { values, positionals } = parseArgs({
      args: argv,
      allowPositionals: true,
      allowNegative: true,
      options: {
        help: { type: 'boolean', short: 'h' },
        version: { type: 'boolean', short: 'v' },
        json: { type: 'boolean' },
        color: { type: 'boolean' },
        file: { type: 'string', short: 'f' },
        year: { type: 'string', short: 'y' },
      },
    });
    const [command, ...rest] = positionals;
    if (values.help) { console.log(HELP); return EXIT.OK; }
    if (values.version) { console.log(pkg.version); return EXIT.OK; }
    if (!command) throw new UsageError('missing command');

    const config = await loadConfig({ file: values.file, color: values.color });
    const paint = (format, text) => (config.color ? styleText(format, text, { stream: stdout }) : text);
    const books = await readBooks(config.file);

    switch (command) {
      case 'list': {
        const lines = values.json || !stdout.isTTY;
        for (const b of books) {
          console.log(lines ? JSON.stringify(b) : `${paint('bold', b.title)} ${paint('dim', `(${b.year})`)}`);
        }
        return EXIT.OK;
      }
      case 'add': {
        let title = rest.join(' ');
        let year = values.year;
        if (!title || !year) {
          if (!stdin.isTTY) throw new UsageError('title and --year are required when stdin is not a terminal');
          const answers = await ask({ ...(title ? {} : { title: 'Title' }), ...(year ? {} : { year: 'Year' }) }, { signal });
          title ||= answers.title;
          year ||= answers.year;
        }
        if (!title || !/^\d{4}$/.test(year)) throw new UsageError('a title and a four-digit year are required');
        books.push({ title, year: Number(year) });
        await writeBooks(config.file, books);
        console.error(`added ${title}`);
        return EXIT.OK;
      }
      case 'import': {
        let count = 0;
        // The signal option closes the interface (ending the loop) when the caller aborts.
        for await (const line of createInterface({ input: stdin, crlfDelay: Infinity, signal })) {
          if (line.trim() === '') continue;
          books.push(JSON.parse(line));
          count++;
        }
        signal?.throwIfAborted();                          // interrupted: save nothing
        await writeBooks(config.file, books);
        console.error(`imported ${count} books`);
        return EXIT.OK;
      }
      default:
        throw new UsageError(`unknown command '${command}'`);
    }
  } catch (err) {
    if (err instanceof UsageError || String(err.code).startsWith('ERR_PARSE_ARGS_')) {
      stderr.write(`bookshelf: ${err.message}\nTry 'bookshelf --help'.\n`);
      return EXIT.USAGE;
    }
    if (err.name === 'AbortError') {
      stderr.write('\n');
      return EXIT.SIGINT;                                 // cancelled: 128 + SIGINT
    }
    stderr.write(`bookshelf: ${err.message}\n`);
    return EXIT.FAILURE;
  }
}

import { mkdir, readFile, rename, writeFile } from 'node:fs/promises';
import { dirname } from 'node:path';

export async function readBooks(file) {
  try {
    return JSON.parse(await readFile(file, 'utf8'));
  } catch (err) {
    if (err.code === 'ENOENT') return [];
    throw err;
  }
}

// Write to a temporary file and rename it: readers never see a half-written catalogue.
export async function writeBooks(file, books) {
  await mkdir(dirname(file), { recursive: true });
  const tmp = `${file}.${process.pid}.tmp`;
  await writeFile(tmp, JSON.stringify(books, null, 2) + '\n');
  await rename(tmp, file);
}