@centient/cli-utils

Dependency-free CLI primitives shared across Centient command-line tools:

• Terminal capability detection — NO_COLOR / FORCE_COLOR / TERM precedence with an injectable env record, so detection is unit-testable.
• ANSI color helpers — degrade to identity (empty-string) codes when color is unsupported.
• Semver-lite — parse / compare / satisfies for major.minor.patch[-prerelease], no external semver dependency.

Zero runtime dependencies. ESM-only.

Installation

npm install @centient/cli-utils

Or as a workspace dependency in the monorepo:

pnpm add @centient/cli-utils --workspace

Terminal capabilities & color

Detection is split into a pure core (takes an injectable env record and a stream descriptor — read no globals) and thin live-process wrappers for ergonomic CLI call sites.

Color precedence order

resolveColorSupport(env, isTTY) resolves color support by this exact precedence (highest wins):

1. FORCE_COLOR present (any value, including "") → color ON
2. NO_COLOR present (any value, including "") → color OFF
3. TERM === "dumb" → color OFF, isDumb = true
4. stream is a TTY → color ON
5. otherwise → color OFF

Presence is tested by key presence (the NO_COLOR convention): the variable's mere presence is the signal, regardless of value. A key whose value is undefined counts as absent.

import {
  detectCapabilities,
  makeAnsiColors,
  colorize,
} from "@centient/cli-utils";

// Pure / testable: pass an env record and a stream descriptor.
const caps = detectCapabilities(process.env, process.stdout);
// caps -> { isTTY, hasColor, isDumb, width }

const colors = makeAnsiColors(caps.hasColor);
console.log(colorize(colors, "green", "ok"));
// "ok" is wrapped in ANSI green when color is enabled, returned unchanged when not.

Live-process convenience wrappers

import { detectTerminalCapabilities, createAnsiColors } from "@centient/cli-utils";

const caps = detectTerminalCapabilities("stdout"); // reads process.env + process.stdout
const colors = createAnsiColors();                 // colors for the live stdout

Structured errors

import { writeError } from "@centient/cli-utils";

writeError("config not found", "a path to engram.json", "pass --config <path>");
// [ERROR] config not found
//   Expected: a path to engram.json
//   Recovery: pass --config <path>

The sink is injectable (writeError(what, expected, recovery, write?)), defaulting to process.stderr. Returns void; exit-code handling is the caller's responsibility.

Semver-lite

Parses major.minor.patch with optional pre-release identifiers and build metadata. Build metadata is parsed off and ignored for ordering (SemVer 2.0 §10). Pre-releases are ordered per SemVer 2.0 §11 — a pre-release sorts below its release.

import {
  parseSemver,
  tryParseSemver,
  formatSemver,
  compareSemver,
  compareVersions,
  satisfies,
} from "@centient/cli-utils";

parseSemver("1.2.3-rc.1");
// { major: 1, minor: 2, patch: 3, prerelease: ["rc", 1] }

tryParseSemver("v1.2.3"); // parsed tuple
tryParseSemver("not-a-version"); // null (diagnostic/fail-open paths)

const actual = tryParseSemver("v1.5.0");
const minimum = tryParseSemver("1.2.0");
const meetsMinimum =
  actual === null || minimum === null
    ? null // caller chooses whether to warn, skip, or fail open
    : compareSemver(actual, minimum) >= 0;

formatSemver(parseSemver("1.2.3-rc.1")); // "1.2.3-rc.1" (round-trips)

compareVersions("1.0.0-rc.1", "1.0.0"); // -1 (pre-release < release)

satisfies("1.5.3", "^1.2.0"); // true

Supported range forms

No compound ranges, no ||, no hyphen ranges.

parseSemver, compareVersions, and satisfies remain strict: malformed versions or ranges throw SemverError (carrying expected and input fields) rather than degrading silently. tryParseSemver is the explicit non-throwing boundary for externally reported versions; it returns null on invalid input and accepts one conventional lowercase v immediately before the numeric core.

API

License

MIT