@lmctl-ai/lmformat 0.13.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Lattice Systems LLC
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,250 @@
+# lmformat
+
+Dependency-free Node.js library for CLI output formatting: automatically sized
+tables, compact counts, durations, and timestamps.
+Install with `npm install @lmctl-ai/lmformat`.
+
+Pass an array of rows; each row is an array of cells. No column widths are needed.
+
+```js
+const { formatTable, printTable } = require('@lmctl-ai/lmformat');
+// ESM also supports: import { formatTable, printTable } from '@lmctl-ai/lmformat';
+
+const rows = [
+  ['triage.lmctl', 'Triage', 'done', 5, '25s'],
+  ['math.lmctl', 'Lead', 'done', 120, '2s'],
+];
+printTable(rows, {
+  headers: ['team', 'alias', 'status', 'msgs', 'time spent'],
+  align: ['left', 'left', 'left', 'right', 'right'],
+});
+```
+
+```text
+team          alias   status  msgs  time spent
+triage.lmctl  Triage  done       5         25s
+math.lmctl    Lead    done     120          2s
+```
+
+`formatTable(rows, { headers, align }?)` returns a string without a final newline.
+`printTable(rows, { headers, align, stream }?)` writes it with a final newline to
+`process.stdout` or a supplied writable stream. Empty output writes nothing.
+Headers are optional. You can also include a header as the first row.
+`align` optionally sets each column to `'left'` (default) or `'right'`;
+numeric columns read best right-aligned. Headers follow their column's alignment.
+
+## Measuring and rendering separately
+
+`formatTable` measures and renders in one step. To align SEVERAL tables on one
+shared grid — for example per-section tables under standalone headings — split
+the two steps:
+
+```js
+const { measureColumns, renderGrid } = require('@lmctl-ai/lmformat');
+
+const running = [['math.lmctl:Lead', 'exec', 'running 16h ago']];
+const idle = [
+  ['triage.lmctl:Triage', 'chat', 'ran 24s, idle 5m ago'],
+  ['or.lmctl:Lead', 'chat', 'ran 5s, idle 6m ago'],
+];
+
+const widths = measureColumns([running, idle]); // one width set across all grids
+console.log(renderGrid(running, { widths, margin: 2 }));
+console.log(renderGrid(idle, { widths, margin: 2 }));
+```
+
+```text
+  math.lmctl:Lead      exec  running 16h ago
+  triage.lmctl:Triage  chat  ran 24s, idle 5m ago
+  or.lmctl:Lead        chat  ran 5s, idle 6m ago
+```
+
+`measureColumns(grids, { max }?)` takes an array of grids; a grid is a rows array or
+`{ rows, headers }`. It returns the display width of each column across all
+grids — simply the widest cell, headers included; pass `max` (an array of
+per-column caps, `null`/`undefined` entries uncapped) to bound chosen columns.
+`renderGrid(rows, { widths, headers, align, margin }?)` renders one grid
+with explicit widths; a non-trailing cell wider than its width is truncated
+with an ellipsis (pass `truncate: false` to let it overflow). Trailing cells
+are open-ended by default; `truncateTrailing: true` bounds them as well.
+`margin` (a number of spaces or a string) indents every rendered line, so
+section grids can sit under their headings without caller-side prefixing.
+Omitting `widths` makes `renderGrid` measure its own rows — exactly what
+`formatTable` does; `max` caps that self-measurement (passing both `widths`
+and `max` throws). Measure globally and render per section, or measure per
+section — the caller chooses.
+
+All rows are loaded before formatting. Each column takes the maximum cell length
+across headers and data, capped per column by `max` when given; cells are
+right-padded with spaces and columns have a
+two-space gap. Trailing empty cells add no padding. Ragged rows are accepted;
+`null`, `undefined`, and missing cells become empty strings. Other values use
+`String(value)`. Inputs are not modified. Long text is never wrapped; cells
+over their column's width (measured or capped) are truncated with an ellipsis,
+except trailing cells unless `truncateTrailing: true`. `truncate: false`
+disables all truncation.
+
+## Column widths and caps (manual, per call)
+
+One giant cell should not stretch a whole column — and no statistics should
+decide what "giant" means. The widest cell is the default, which callers can override.
+When you have inspected real output and know a column should never exceed a
+width, say so: `measureColumns(grids, { max: [26, null, 20] })` caps column 0
+at 26 and column 2 at 20, leaving column 1 uncapped. Caps also work through
+`renderGrid`/`formatTable`/`printTable` when they self-measure. A cap smaller
+than the header caps the header too (you own both); a cap on the trailing
+column takes effect only with `truncateTrailing: true`. When
+rendering, a non-trailing cell wider than its column is truncated to the
+width with a trailing `…`; pass `truncate: false` to let such cells overflow
+instead.
+
+To override just one column, measure first and edit that entry. This can either
+narrow or widen the column while leaving the other measurements intact:
+
+```js
+const widths = measureColumns([running, idle]);
+widths[1] = 20;
+console.log(renderGrid(running, { widths }));
+console.log(renderGrid(idle, { widths }));
+```
+
+To bound a long trailing reason, opt into truncating the last populated cell
+of each row. This also applies to headers, ragged rows, and single-column tables:
+
+```js
+const rows = [['math', 'a very long reason']];
+const widths = measureColumns([rows]);
+widths[1] = 10;
+renderGrid(rows, { widths, truncateTrailing: true }); // 'math  a very lo…'
+// The same result using automatic measurement with a cap:
+formatTable(rows, { max: [null, 10], truncateTrailing: true });
+```
+
+`truncateTrailing` defaults to `false` and works in `renderGrid`, `formatTable`,
+and `printTable`. It uses the existing column width and `ellipsis` option.
+`truncate: false` takes precedence. Zero or missing explicit widths remain
+unconstrained. Left-aligned trailing cells stay unpadded; right alignment still
+pads on the left. This is single-line truncation, not wrapping within cells.
+
+The truncation mark itself is an option: `ellipsis` defaults to `…`; pass
+`'...'` for ASCII-only terminals or `''` for a hard cut. A mark wider than the
+column falls back to `…`. Like the bar glyphs (`fill`/`empty`/`unknown`), every
+baked-in glyph is a caller option whose default keeps existing output unchanged.
+
+Cells must be plain single-line text: tabs, newlines, ANSI escape sequences, and
+other terminal control characters are rejected (use `escapeCell` to sanitize
+untrusted text first). Widths are terminal display widths: East Asian
+wide/fullwidth characters and most emoji count double, combining marks and
+zero-width characters count zero (a pragmatic zero-dependency approximation,
+not a full UAX #11 implementation). A terminal
+narrower than the output may wrap lines.
+
+Requires Node.js 18 or newer. Run `npm test` for alignment tests, `npm run check`
+for syntax checks, and `npm run example` for the complete session example.
+
+## Relative timestamps
+
+```js
+const { formatRelativeTime, printTable } = require('@lmctl-ai/lmformat');
+const now = '2026-09-25T20:00:00Z'; // Omit to use Date.now().
+printTable([
+  ['weekly', formatRelativeTime('2026-09-28T20:00:00Z', { now })],
+  ['session', formatRelativeTime('2026-09-25T20:40:00Z', { now })],
+  ['missing', formatRelativeTime('unknown', { now })],
+], { headers: ['limit', 'resets in'] });
+// limit    resets in
+// weekly   3d
+// session  40m
+// missing  unknown
+```
+
+`formatRelativeTime(timestamp, { now }?)` accepts a Date, an epoch timestamp in
+milliseconds, or a date string accepted by `Date.parse`. Prefer ISO 8601 strings
+with an explicit timezone. It returns the largest whole unit (`w`, `d`, `h`,
+`m`, `s`), rounding down: 2 days and 20 hours becomes `2d`. Days mean 24 hours;
+weeks mean 7 days.
+Future timestamps return `3d`; past timestamps return `3d ago`; differences below
+one second return `now`. Missing or invalid timestamps return `unknown`.
+An invalid explicit `now` throws a TypeError. Capture `now` once when formatting
+multiple timestamps so the report uses a consistent reference time.
+
+Run `npm run example:ratelimit` for the supplied provider and rate-limit data,
+including read ages, reset countdowns, credits, and exhausted status. This example
+uses the fixed snapshot time `2026-09-25T20:33:47Z` for reproducible output.
+Transform timestamp cells before passing rows to the table formatter; widths
+are calculated from the resulting text automatically.
+
+## Counts, durations, and clocks
+
+```js
+const {
+  formatCount, formatDuration, formatPercent, formatClock, formatLocalTimestamp,
+  formatBar, formatTimer,
+} = require('@lmctl-ai/lmformat');
+
+formatCount(960_462);        // "960K"   (>= 1M keeps one decimal: "15.8M")
+formatDuration(7_500_000);   // "2h 5m"  (up to two units: "3m 12s", "1w 2d")
+formatDuration(788_400_000, { maxUnit: "d" });  // "9d 3h" (cap the largest unit)
+formatDuration(180_180_000, { style: "compact" }); // "2d02h03m" (dense, no seconds)
+formatPercent(0.16);         // "16%"
+formatBar(0.16);             // "##        "  (bare fill, no frame)
+formatBar(0.5, { width: 6, fill: '█', empty: '░' }); // "███░░░"
+formatBar(null, { width: 3, unknown: '·' });        // "···"
+formatTimer(2_172_000);       // "00:36:12"  ("5d 18:24:33" past 24h)
+formatClock();               // "09:05:03"          local wall clock, now or given time
+formatLocalTimestamp();      // "2026-01-02 09:05:03"  local date and time
+```
+
+`formatCount` accepts a finite number and returns `unknown` otherwise. It rounds
+symmetrically for negative values and promotes units after rounding, so
+`999_999` becomes `"1.0M"` rather than `"1000K"`.
+`formatDuration` takes milliseconds, clamps negatives to `0s`, and returns
+`unknown` for non-finite input. `formatPercent` takes a fraction (`0.16` for 16%)
+and returns `?%` for non-finite input — deliberately not `unknown`, since the
+inline `used ?% remaining ?%` context wants the unit suffix kept. `formatClock` and `formatLocalTimestamp`
+accept a Date, epoch milliseconds, or a parseable date string (default: now),
+and return `unknown` for invalid input.
+
+`formatBar` defaults to width 10, fill `#`, empty space, and unknown `?`.
+Each custom glyph must be a single character with terminal display width 1;
+wide emoji/CJK, combining marks, control characters, and multi-character strings
+are rejected. Fractions still round to the nearest filled cell and clamp to
+0–1. Non-finite input repeats the `unknown` glyph across the bar.
+
+MIT licensed. Project homepage: [lmctl.com](https://lmctl.com).
+
+## Publishing
+
+CI builds and tests pushes to `main` and pull requests on Node 18, 20, 22, and 24.
+It also installs the built tarball and checks CommonJS and ESM imports.
+`npm run build` checks syntax and produces `release/lmctl-ai-lmformat-VERSION.tgz`.
+Only the library, package metadata, README, and license are included.
+
+Publishing uses [npm trusted publishing](https://docs.npmjs.com/trusted-publishers/)
+from GitHub Actions with provenance. No npm token is stored in GitHub.
+
+One-time setup by an npm account with access to the `@lmctl-ai` scope:
+
+1. Run `npm login`, then `npm ci && npm test && npm run build` and
+   `npm publish ./release/lmctl-ai-lmformat-0.1.0.tgz --access public` to create
+   the first package version. Complete npm's authentication/2FA prompt if requested.
+2. On npmjs.com, open `@lmctl-ai/lmformat` → Settings → Trusted Publisher and
+   select GitHub Actions. Set organization to `lmctl-ai`, repository to `lmformat`,
+   and workflow filename to `publish.yml`. Leave environment blank and allow
+   direct publishing (`npm publish`).
+3. Subsequent versions publish automatically when their matching version tag is
+   pushed. The workflow tests and builds again before publishing with provenance.
+
+For example, after committing changes on `main`:
+
+```sh
+npm version patch -m 'Release %s for npm consumers'
+git push origin main
+git push origin --tags
+```
+
+The tag must equal `v` plus the version in `package.json`. A tag for an already
+published version cannot republish it. No version is changed by CI itself.
+For a build and publish dry run, use the Publish workflow's **Run workflow** button
+with `dry_run` checked. To retry an unpublished tagged version, select that tag
+and uncheck `dry_run`. Real manual publishes from branch refs are rejected.

package/index.d.ts

@@ -0,0 +1,67 @@
+export type TableCell = string | number | boolean | null | undefined;
+export type ColumnAlign = 'left' | 'right';
+
+export interface TableOptions {
+  headers?: TableCell[];
+  align?: ColumnAlign[];
+  /** Truncate over-width cells (default true). False disables all truncation. */
+  truncate?: boolean;
+  /** Also truncate the last populated cell of each row (default false).
+   * Uses its column width and ellipsis; requires truncate to be enabled. */
+  truncateTrailing?: boolean;
+  /** Leading indent for every line: a number of spaces or a string. */
+  margin?: number | string;
+  /** Per-column width caps from manual inspection; null/undefined entries
+   * stay uncapped. Over-width non-trailing cells truncate with an ellipsis. */
+  max?: Array<number | null | undefined>;
+  /** Truncation mark (default '…'); '' gives a hard cut. A mark wider than
+   * the column falls back to '…'. */
+  ellipsis?: string;
+}
+
+export interface Grid {
+  rows: TableCell[][];
+  headers?: TableCell[];
+}
+
+export interface RenderGridOptions extends TableOptions {
+  widths?: number[];
+}
+
+export interface MeasureOptions {
+  /** Per-column width caps from manual inspection; null/undefined entries
+   * stay uncapped. */
+  max?: Array<number | null | undefined>;
+}
+
+export interface PrintTableOptions extends TableOptions {
+  stream?: { write(text: string): void };
+}
+
+export function measureColumns(grids: Array<Grid | TableCell[][]>, options?: MeasureOptions): number[];
+export function renderGrid(rows: TableCell[][], options?: RenderGridOptions): string;
+export function formatTable(rows: TableCell[][], options?: TableOptions): string;
+export function printTable(rows: TableCell[][], options?: PrintTableOptions): void;
+
+export type TimestampInput = Date | number | string;
+
+export function formatRelativeTime(value: TimestampInput, options?: { now?: TimestampInput }): string;
+export function formatCount(value: number | null | undefined): string;
+export type DurationUnit = 'w' | 'd' | 'h' | 'm' | 's';
+
+export function formatDuration(milliseconds: number | null | undefined, options?: { maxUnit?: DurationUnit; style?: 'spaced' | 'compact' }): string;
+export function formatClock(value?: TimestampInput): string;
+export function formatLocalTimestamp(value?: TimestampInput): string;
+export function formatPercent(fraction: number | null | undefined): string;
+export interface BarOptions {
+  width?: number;
+  /** Single character of display width 1 (default '#'). */
+  fill?: string;
+  /** Single character of display width 1 (default ' '). */
+  empty?: string;
+  /** Single character of display width 1 for non-finite input (default '?'). */
+  unknown?: string;
+}
+export function formatBar(fraction: number | null | undefined, options?: BarOptions): string;
+export function formatTimer(milliseconds: number | null | undefined): string;
+export function escapeCell(value: unknown): string;

package/index.js

@@ -0,0 +1,405 @@
+'use strict';
+
+function normalizeRow(row) {
+  if (!Array.isArray(row)) {
+    throw new TypeError('Each row and headers must be an array of cells');
+  }
+  return Array.from(row, (value) => {
+    const cell = value == null ? '' : String(value);
+    if (/[\x00-\x1f\x7f-\x9f]/u.test(cell)) {
+      throw new TypeError('Cells must be single-line text without terminal control characters');
+    }
+    return cell;
+  });
+}
+
+function normalizeAlign(align) {
+  if (align === undefined) return [];
+  if (!Array.isArray(align)) {
+    throw new TypeError('align must be an array of "left" or "right" per column');
+  }
+  return align.map((value) => {
+    if (value !== 'left' && value !== 'right') {
+      throw new TypeError('align entries must be "left" or "right"');
+    }
+    return value;
+  });
+}
+
+/** Approximate terminal display width (zero-dependency wcwidth): combining
+ * marks and zero-width characters add nothing; East Asian wide/fullwidth
+ * code points and most emoji count double. Close enough for column
+ * alignment; not a full UAX #11 implementation. */
+function displayWidth(text) {
+  let width = 0;
+  for (const char of text) {
+    const cp = char.codePointAt(0);
+    if (
+      (cp >= 0x0300 && cp <= 0x036f) ||   // combining diacritical marks
+      (cp >= 0x1ab0 && cp <= 0x1aff) ||   // combining diacriticals extended
+      (cp >= 0x1dc0 && cp <= 0x1dff) ||   // combining diacriticals supplement
+      (cp >= 0x20d0 && cp <= 0x20ff) ||   // combining marks for symbols
+      (cp >= 0xfe00 && cp <= 0xfe0f) ||   // variation selectors
+      (cp >= 0xfe20 && cp <= 0xfe2f) ||   // combining half marks
+      cp === 0x200b ||                    // zero-width space
+      (cp >= 0xe0100 && cp <= 0xe01ef)    // variation selectors supplement
+    ) continue;
+    if (
+      (cp >= 0x1100 && cp <= 0x115f) ||   // Hangul Jamo
+      (cp >= 0x2e80 && cp <= 0x303e) ||   // CJK radicals, Kangxi, ideographic
+      (cp >= 0x3041 && cp <= 0x33ff) ||   // Hiragana, Katakana, CJK compatibility
+      (cp >= 0x3400 && cp <= 0x4dbf) ||   // CJK extension A
+      (cp >= 0x4e00 && cp <= 0x9fff) ||   // CJK unified ideographs
+      (cp >= 0xa000 && cp <= 0xa4cf) ||   // Yi
+      (cp >= 0xac00 && cp <= 0xd7a3) ||   // Hangul syllables
+      (cp >= 0xf900 && cp <= 0xfaff) ||   // CJK compatibility ideographs
+      (cp >= 0xfe30 && cp <= 0xfe6f) ||   // CJK compatibility forms
+      (cp >= 0xff00 && cp <= 0xff60) ||   // fullwidth forms
+      (cp >= 0xffe0 && cp <= 0xffe6) ||   // fullwidth signs
+      (cp >= 0x2600 && cp <= 0x27bf) ||   // misc symbols + dingbats
+      (cp >= 0x1f000 && cp <= 0x1faff) || // emoji (incl. transport, supplemental)
+      (cp >= 0x20000 && cp <= 0x3fffd)    // CJK extensions B+
+    ) {
+      width += 2;
+      continue;
+    }
+    width += 1;
+  }
+  return width;
+}
+
+function padDisplay(cell, width, right) {
+  const padding = ' '.repeat(Math.max(0, width - displayWidth(cell)));
+  return right ? padding + cell : cell + padding;
+}
+
+function normalizeGrid(grid) {
+  if (Array.isArray(grid)) return { rows: grid };
+  if (grid !== null && typeof grid === 'object' && Array.isArray(grid.rows)) return grid;
+  throw new TypeError('each grid must be a rows array or { rows, headers }');
+}
+
+function normalizeEllipsis(ellipsis) {
+  if (ellipsis === undefined) return '…';
+  if (typeof ellipsis !== 'string' || /[\x00-\x1f\x7f-\x9f]/u.test(ellipsis)) {
+    throw new TypeError('ellipsis must be a single-line string without terminal control characters');
+  }
+  return ellipsis;
+}
+
+/** Truncate a cell to a display width, ending with an ellipsis. A custom
+ * `ellipsis` (including '' for a hard cut) replaces the default '…'; one
+ * wider than the column falls back to '…'. */
+function truncateDisplay(cell, width, ellipsis = '…') {
+  if (displayWidth(cell) <= width) return cell;
+  const mark = displayWidth(ellipsis) > width ? '…' : ellipsis;
+  const markWidth = displayWidth(mark);
+  if (width <= markWidth) return mark;
+  let out = '';
+  let used = 0;
+  for (const char of cell) {
+    const charWidth = displayWidth(char);
+    if (used + charWidth > width - markWidth) break;
+    out += char;
+    used += charWidth;
+  }
+  return `${out}${mark}`;
+}
+
+function normalizeMax(max) {
+  if (max === undefined) return [];
+  if (!Array.isArray(max)) {
+    throw new TypeError('max must be an array of per-column width caps');
+  }
+  return max.map((value) => {
+    if (value === null || value === undefined) return undefined;
+    if (typeof value !== 'number' || !Number.isInteger(value) || value < 1) {
+      throw new TypeError('max entries must be positive integers, null, or undefined');
+    }
+    return value;
+  });
+}
+
+/** Measure column display widths across one or more grids. Pair with
+ * renderGrid to align several tables on one shared grid.
+ * Each column's width is simply the widest cell (headers included) — no
+ * statistical trimming. When real data shows a column needs a bound, pass
+ * { max: [cap, ...] } with a manually chosen cap per column (null/undefined
+ * entries stay uncapped); over-width non-trailing cells then truncate with
+ * an ellipsis at render time. A cap on the trailing column has no visible
+ * effect by default: pass truncateTrailing at render time to bound it too. */
+function measureColumns(grids, { max } = {}) {
+  if (!Array.isArray(grids)) {
+    throw new TypeError('grids must be an array of grids');
+  }
+  const caps = normalizeMax(max);
+  const widths = [];
+  const push = (column, width) => {
+    widths[column] = Math.max(widths[column] ?? 0, width);
+  };
+  for (const input of grids) {
+    const grid = normalizeGrid(input);
+    if (grid.headers !== undefined) {
+      normalizeRow(grid.headers).forEach((cell, column) => {
+        push(column, displayWidth(cell));
+      });
+    }
+    for (const row of grid.rows.map(normalizeRow)) {
+      row.forEach((cell, column) => {
+        push(column, displayWidth(cell));
+      });
+    }
+  }
+  return widths.map((width, column) => {
+    const cap = caps[column];
+    return cap === undefined ? width : Math.min(width, cap);
+  });
+}
+
+exports.measureColumns = measureColumns;
+
+function normalizeMargin(margin) {
+  if (margin === undefined) return '';
+  if (typeof margin === 'number' && Number.isInteger(margin) && margin >= 0) return ' '.repeat(margin);
+  if (typeof margin === 'string' && !/[\x00-\x1f\x7f-\x9f]/u.test(margin)) return margin;
+  throw new TypeError('margin must be a number of spaces or a single-line string');
+}
+
+/** Render rows with explicit column widths (from measureColumns). Non-trailing
+ * cells wider than their column are truncated with an ellipsis so the grid
+ * stays aligned (pass { truncate: false } to let them overflow); trailing
+ * cells render in full by default. Set truncateTrailing to also truncate the
+ * last populated cell of each row; left-aligned trailing cells stay unpadded.
+ * Omitted widths measure the given rows alone (equivalent to
+ * formatTable); { max } caps that self-measurement per column (it is an
+ * error to pass both widths and max). `margin` (spaces count or string)
+ * indents every line; `ellipsis` (default '…') is the truncation mark —
+ * '' gives a hard cut. */
+function renderGrid(rows, { widths, headers, align, truncate = true, truncateTrailing = false, margin, max, ellipsis } = {}) {
+  if (!Array.isArray(rows)) {
+    throw new TypeError('rows must be an array of row arrays');
+  }
+  if (widths !== undefined && !Array.isArray(widths)) {
+    throw new TypeError('widths must be an array of column widths');
+  }
+  if (widths !== undefined && max !== undefined) {
+    throw new TypeError('pass widths or max, not both (max caps a measurement)');
+  }
+  const indent = normalizeMargin(margin);
+  const alignment = normalizeAlign(align);
+  const mark = normalizeEllipsis(ellipsis);
+  const columns = widths ?? measureColumns([{ rows, headers }], { max });
+  const table = rows.map(normalizeRow);
+  if (headers !== undefined) table.unshift(normalizeRow(headers));
+
+  const body = table.map((row) => {
+    // Omit absent trailing cells, but preserve padding before later populated cells.
+    let last = row.length - 1;
+    while (last >= 0 && row[last] === '') last--;
+    return row.slice(0, last + 1).map((cell, column) => {
+      const width = columns[column] || 0;
+      const fitted = truncate && width > 0 && (column !== last || truncateTrailing)
+        ? truncateDisplay(cell, width, mark) : cell;
+      if (alignment[column] === 'right') return padDisplay(fitted, width, true);
+      return column === last ? fitted : padDisplay(fitted, width, false);
+    }).join('  ');
+  }).join('\n');
+  if (body === '' || indent === '') return body;
+  return `${indent}${body.split('\n').join(`\n${indent}`)}`;
+}
+
+exports.renderGrid = renderGrid;
+
+/** Format rows using the widest cell in each column, with two spaces between columns. */
+function formatTable(rows, { headers, align, truncate, truncateTrailing, margin, max, ellipsis } = {}) {
+  return renderGrid(rows, { headers, align, truncate, truncateTrailing, margin, max, ellipsis });
+}
+
+/** Print a formatted table and a final newline; empty output writes nothing. */
+function printTable(rows, { headers, align, truncate, truncateTrailing, margin, max, ellipsis, stream = process.stdout } = {}) {
+  const output = formatTable(rows, { headers, align, truncate, truncateTrailing, margin, max, ellipsis });
+  if (output) stream.write(`${output}\n`);
+}
+
+exports.formatTable = formatTable;
+exports.printTable = printTable;
+
+function timestamp(value) {
+  if (value instanceof Date) return value.getTime();
+  if (typeof value === 'number') return value;
+  if (typeof value === 'string' && value.trim()) return Date.parse(value);
+  return NaN;
+}
+
+/** Compact time until a timestamp; past times carry an "ago" suffix. */
+function formatRelativeTime(value, { now = Date.now() } = {}) {
+  const reference = timestamp(now);
+  if (!Number.isFinite(reference)) throw new TypeError('now must be a valid timestamp');
+  const target = timestamp(value);
+  if (!Number.isFinite(target)) return 'unknown';
+
+  const difference = target - reference;
+  const seconds = Math.floor(Math.abs(difference) / 1000);
+  if (seconds === 0) return 'now';
+  for (const [unit, size] of [['w', 604800], ['d', 86400], ['h', 3600], ['m', 60], ['s', 1]]) {
+    if (seconds >= size) {
+      return `${Math.floor(seconds / size)}${unit}${difference < 0 ? ' ago' : ''}`;
+    }
+  }
+}
+
+exports.formatRelativeTime = formatRelativeTime;
+
+/** Compact token/byte-style count: 960462 -> "960K", 15791104 -> "15.8M". */
+function formatCount(value) {
+  if (typeof value !== 'number' || !Number.isFinite(value)) return 'unknown';
+  const sign = value < 0 ? '-' : '';
+  const absolute = Math.abs(value);
+  if (absolute < 1_000) return String(value);
+  const thousands = Math.round(absolute / 1_000);
+  // Promote after rounding so 999_999 becomes "1.0M", not "1000K".
+  if (thousands < 1_000) return `${sign}${thousands}K`;
+  return `${sign}${(absolute / 1_000_000).toFixed(1)}M`;
+}
+
+exports.formatCount = formatCount;
+
+const DURATION_UNITS = [['w', 604800], ['d', 86400], ['h', 3600], ['m', 60], ['s', 1]];
+
+/** Elapsed duration. Default style is up to two spaced units: "45s",
+ * "3m 12s", "2h 5m", "1w 2d". `style: 'compact'` renders zero-padded
+ * adjacent units down to MINUTES with no seconds: "2d02h03m", "04h59m",
+ * "<1m" — dense cells for grids. `maxUnit` ('w' default, or 'd'/'h'/'m'/'s')
+ * caps the largest unit — e.g. 'd' renders 9 days as "9d 3h" / "9d03h"
+ * instead of "1w 2d". */
+function formatDuration(milliseconds, { maxUnit = 'w', style = 'spaced' } = {}) {
+  if (typeof milliseconds !== 'number' || !Number.isFinite(milliseconds)) return 'unknown';
+  const start = DURATION_UNITS.findIndex(([unit]) => unit === maxUnit);
+  if (start === -1) throw new TypeError('maxUnit must be one of "w", "d", "h", "m", "s"');
+  if (style !== 'spaced' && style !== 'compact') throw new TypeError('style must be "spaced" or "compact"');
+  const secondsTotal = Math.floor(Math.max(0, milliseconds) / 1000);
+  if (style === 'compact') {
+    const units = DURATION_UNITS.slice(start).filter(([unit]) => unit !== 's');
+    if (units.length === 0 || secondsTotal < 60) return '<1m';
+    const parts = [];
+    let rest = secondsTotal;
+    let started = false;
+    for (const [unit, size] of units) {
+      const amount = Math.floor(rest / size);
+      rest -= amount * size;
+      if (amount > 0 && !started) {
+        const text = unit === 'd' || unit === 'w' ? `${amount}${unit}` : `${pad2(amount)}${unit}`;
+        parts.push({ text, zero: false });
+        started = true;
+      } else if (started) {
+        parts.push({ text: `${pad2(amount)}${unit}`, zero: amount === 0 });
+      }
+    }
+    // Positional zeros stay mid-sequence ("2d00h03m"); trailing zeros drop.
+    while (parts.length > 0 && parts[parts.length - 1].zero) parts.pop();
+    return parts.map((part) => part.text).join('');
+  }
+  let seconds = secondsTotal;
+  const parts = [];
+  for (const [unit, size] of DURATION_UNITS.slice(start)) {
+    if (seconds >= size || (unit === 's' && parts.length === 0)) {
+      const amount = Math.floor(seconds / size);
+      seconds -= amount * size;
+      parts.push(`${amount}${unit}`);
+      if (parts.length === 2) break;
+    }
+  }
+  return parts.join(' ');
+}
+
+exports.formatDuration = formatDuration;
+
+function localDate(value) {
+  if (value === undefined) return new Date();
+  if (value instanceof Date) return value;
+  if (typeof value === 'number' || typeof value === 'string') return new Date(value);
+  return new Date(NaN);
+}
+
+function pad2(value) {
+  return String(value).padStart(2, '0');
+}
+
+/** Local wall clock "HH:MM:SS", for step narration on stderr. */
+function formatClock(value) {
+  const date = localDate(value);
+  if (Number.isNaN(date.getTime())) return 'unknown';
+  return `${pad2(date.getHours())}:${pad2(date.getMinutes())}:${pad2(date.getSeconds())}`;
+}
+
+exports.formatClock = formatClock;
+
+/** Local timestamp "YYYY-MM-DD HH:MM:SS", for log-style lines. */
+function formatLocalTimestamp(value) {
+  const date = localDate(value);
+  if (Number.isNaN(date.getTime())) return 'unknown';
+  const day = `${date.getFullYear()}-${pad2(date.getMonth() + 1)}-${pad2(date.getDate())}`;
+  return `${day} ${formatClock(date)}`;
+}
+
+exports.formatLocalTimestamp = formatLocalTimestamp;
+
+/** Percentage from a fraction: 0.16 -> "16%"; non-finite input -> "?%". */
+function formatPercent(fraction) {
+  return typeof fraction === 'number' && Number.isFinite(fraction)
+    ? `${Math.round(fraction * 100)}%`
+    : '?%';
+}
+
+exports.formatPercent = formatPercent;
+
+/** Progress bar with customizable single-column glyphs; defaults to ASCII.
+ * Non-finite input repeats the unknown glyph (default "?"). */
+function formatBar(fraction, { width = 10, fill = '#', empty = ' ', unknown = '?' } = {}) {
+  if (typeof width !== 'number' || !Number.isInteger(width) || width < 1) {
+    throw new TypeError('width must be a positive integer');
+  }
+  for (const [name, glyph] of [['fill', fill], ['empty', empty], ['unknown', unknown]]) {
+    if (typeof glyph !== 'string' || [...glyph].length !== 1 ||
+        /[\x00-\x1f\x7f-\x9f]/u.test(glyph) || displayWidth(glyph) !== 1) {
+      throw new TypeError(`${name} must be a single character with terminal display width 1`);
+    }
+  }
+  if (typeof fraction !== 'number' || !Number.isFinite(fraction)) {
+    return unknown.repeat(width);
+  }
+  const filled = Math.min(width, Math.max(0, Math.round(fraction * width)));
+  return `${fill.repeat(filled)}${empty.repeat(width - filled)}`;
+}
+
+exports.formatBar = formatBar;
+
+/** Clock-style remaining time: "00:36:12", days-prefixed past 24h
+ * ("5d 18:24:33"). Floors to whole seconds. */
+function formatTimer(milliseconds) {
+  if (typeof milliseconds !== 'number' || !Number.isFinite(milliseconds)) return 'unknown';
+  let seconds = Math.floor(Math.max(0, milliseconds) / 1000);
+  const days = Math.floor(seconds / 86400);
+  seconds -= days * 86400;
+  const hours = Math.floor(seconds / 3600);
+  seconds -= hours * 3600;
+  const minutes = Math.floor(seconds / 60);
+  seconds -= minutes * 60;
+  const clock = `${pad2(hours)}:${pad2(minutes)}:${pad2(seconds)}`;
+  return days > 0 ? `${days}d ${clock}` : clock;
+}
+
+exports.formatTimer = formatTimer;
+
+/** Escape terminal control characters so untrusted text survives formatTable. */
+function escapeCell(value) {
+  const text = value == null ? '' : String(value);
+  return text.replace(/[\x00-\x1f\x7f-\x9f]/gu, (char) => {
+    if (char === '\n') return '\\n';
+    if (char === '\t') return '\\t';
+    if (char === '\r') return '\\r';
+    return `\\x${char.codePointAt(0).toString(16).padStart(2, '0')}`;
+  });
+}
+
+exports.escapeCell = escapeCell;

package/package.json

@@ -0,0 +1,21 @@
+{
+  "name": "@lmctl-ai/lmformat",
+  "version": "0.13.0",
+  "description": "Dependency-free CLI output formatting: auto-sized tables, compact counts, durations, and timestamps",
+  "main": "index.js",
+  "types": "index.d.ts",
+  "license": "MIT",
+  "author": "Mike Ma <mike.ma@lmctl.com>",
+  "homepage": "https://lmctl.com",
+  "repository": { "type": "git", "url": "git+https://github.com/lmctl-ai/lmformat.git" },
+  "files": ["index.js", "index.d.ts"],
+  "publishConfig": { "access": "public", "registry": "https://registry.npmjs.org/" },
+  "scripts": {
+    "build": "npm run check && node scripts/build.js",
+    "test": "node --test",
+    "check": "node --check index.js && node --check test/table.test.js && node --check test/time.test.js && node --check test/format.test.js && node --check examples/sessions.js && node --check examples/ratelimit.js",
+    "example": "node examples/sessions.js",
+    "example:ratelimit": "node examples/ratelimit.js"
+  },
+  "engines": { "node": ">=18" }
+}