@liiift-studio/vf-clamp-cli 0.1.0

package/dist/core/config.js

@@ -0,0 +1,133 @@
+// JSON config-file parsing and validation — pure logic, no IO besides reading
+// the file from disk via the injected reader.  Strict validation is performed
+// here so the CLI emits clean errors rather than letting malformed configs
+// crash inside Pyodide with cryptic Python tracebacks.
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { assertFormat } from './format.js';
+/**
+ * Reads and parses a JSON config file from disk, then validates every field
+ * before returning a typed object.  Throws a descriptive error if the file
+ * cannot be read, is not valid JSON, or contains invalid fields.
+ *
+ * Error messages echo the user-supplied path (not the resolved absolute path)
+ * to avoid leaking server-side filesystem layout when invoked from services.
+ */
+export async function readConfig(configPath) {
+    const resolved = path.resolve(configPath);
+    let raw;
+    try {
+        raw = await fs.readFile(resolved, 'utf-8');
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        throw new Error(`Could not read config file "${configPath}": ${message}`);
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        throw new Error(`Config file "${configPath}" is not valid JSON`);
+    }
+    return validateConfig(parsed);
+}
+/**
+ * Validates a parsed JSON value against the ClampConfig schema.
+ * Exported separately so tests can exercise validation without disk I/O.
+ */
+export function validateConfig(input) {
+    if (input === null || typeof input !== 'object' || Array.isArray(input)) {
+        throw new Error('Config file must contain a JSON object at the top level');
+    }
+    const raw = input;
+    const result = { outputs: [] };
+    if (raw.format !== undefined) {
+        if (typeof raw.format !== 'string') {
+            throw new Error('Config "format" must be a string');
+        }
+        assertFormat(raw.format);
+        result.format = raw.format;
+    }
+    if (raw.outputDir !== undefined) {
+        if (typeof raw.outputDir !== 'string') {
+            throw new Error('Config "outputDir" must be a string');
+        }
+        result.outputDir = raw.outputDir;
+    }
+    if (!Array.isArray(raw.outputs) || raw.outputs.length === 0) {
+        throw new Error('Config file must contain a non-empty "outputs" array');
+    }
+    result.outputs = raw.outputs.map((entry, idx) => validateOutput(entry, idx));
+    return result;
+}
+/** Validates a single output entry. */
+function validateOutput(entry, idx) {
+    if (entry === null || typeof entry !== 'object' || Array.isArray(entry)) {
+        throw new Error(`Output at index ${idx} must be an object`);
+    }
+    const raw = entry;
+    const out = {};
+    if (raw.name !== undefined) {
+        if (typeof raw.name !== 'string') {
+            throw new Error(`Output at index ${idx}: "name" must be a string`);
+        }
+        out.name = raw.name;
+    }
+    if (raw.instances !== undefined) {
+        if (!Array.isArray(raw.instances) ||
+            !raw.instances.every((v) => typeof v === 'string')) {
+            throw new Error(`Output at index ${idx}: "instances" must be an array of strings`);
+        }
+        out.instances = raw.instances;
+    }
+    if (raw.axes !== undefined) {
+        out.axes = validateAxes(raw.axes, idx);
+    }
+    if (!out.instances?.length && !out.axes) {
+        throw new Error(`Output at index ${idx} must have "instances" or non-empty "axes"`);
+    }
+    return out;
+}
+/** Validates the axes map for a single output entry. */
+function validateAxes(value, idx) {
+    if (value === null || typeof value !== 'object' || Array.isArray(value)) {
+        throw new Error(`Output at index ${idx}: "axes" must be an object`);
+    }
+    const raw = value;
+    const tags = Object.keys(raw);
+    if (tags.length === 0) {
+        throw new Error(`Output at index ${idx}: "axes" must have at least one entry`);
+    }
+    const axes = {};
+    for (const tag of tags) {
+        const v = raw[tag];
+        if (v === null) {
+            axes[tag] = null;
+            continue;
+        }
+        if (typeof v === 'number') {
+            if (!Number.isFinite(v)) {
+                throw new Error(`Output at index ${idx}, axis "${tag}": pin value must be finite`);
+            }
+            axes[tag] = v;
+            continue;
+        }
+        if (typeof v === 'object' && !Array.isArray(v)) {
+            const obj = v;
+            if (typeof obj.min !== 'number' || typeof obj.max !== 'number') {
+                throw new Error(`Output at index ${idx}, axis "${tag}": range must be { min: number, max: number }`);
+            }
+            if (!Number.isFinite(obj.min) || !Number.isFinite(obj.max)) {
+                throw new Error(`Output at index ${idx}, axis "${tag}": range min/max must be finite numbers`);
+            }
+            if (obj.min > obj.max) {
+                throw new Error(`Output at index ${idx}, axis "${tag}": min (${obj.min}) must not exceed max (${obj.max})`);
+            }
+            axes[tag] = { min: obj.min, max: obj.max };
+            continue;
+        }
+        throw new Error(`Output at index ${idx}, axis "${tag}": must be number, { min, max }, or null`);
+    }
+    return axes;
+}

package/dist/core/exitCodes.d.ts

@@ -0,0 +1,15 @@
+/** Usage error — bad flags, missing arguments. */
+export declare const EX_USAGE = 2;
+/** Input data error — malformed font / JSON config / axis spec. */
+export declare const EX_DATAERR = 65;
+/** Input file missing or unreadable. */
+export declare const EX_NOINPUT = 66;
+/** Internal software error — engine crash. */
+export declare const EX_SOFTWARE = 70;
+/** Invalid configuration. */
+export declare const EX_CONFIG = 78;
+/**
+ * Classifies an unknown error into a sysexits-style exit code based on
+ * either an explicit `code` tag on the error or pattern-matching the message.
+ */
+export declare function classifyError(err: unknown): number;

package/dist/core/exitCodes.js

@@ -0,0 +1,47 @@
+// BSD-sysexits-style exit codes, plus a heuristic classifier that maps
+// thrown errors to the most appropriate code.  Lets callers `if [ $? = 65 ]`
+// react to specific failure modes rather than a flat exit 1 for everything.
+/** Usage error — bad flags, missing arguments. */
+export const EX_USAGE = 2;
+/** Input data error — malformed font / JSON config / axis spec. */
+export const EX_DATAERR = 65;
+/** Input file missing or unreadable. */
+export const EX_NOINPUT = 66;
+/** Internal software error — engine crash. */
+export const EX_SOFTWARE = 70;
+/** Invalid configuration. */
+export const EX_CONFIG = 78;
+/**
+ * Classifies an unknown error into a sysexits-style exit code based on
+ * either an explicit `code` tag on the error or pattern-matching the message.
+ */
+export function classifyError(err) {
+    if (!(err instanceof Error))
+        return 1;
+    const tag = err.code;
+    if (tag === 'USAGE')
+        return EX_USAGE;
+    if (tag === 'ENOENT')
+        return EX_NOINPUT;
+    const msg = err.message.toLowerCase();
+    // More-specific patterns first.
+    if (msg.includes('not valid json'))
+        return EX_DATAERR;
+    if (msg.includes('engine returned unsupported format'))
+        return EX_SOFTWARE;
+    if (msg.startsWith('could not read') || msg.includes('is not a regular file'))
+        return EX_NOINPUT;
+    if (msg.startsWith('invalid --axis') || msg.startsWith('unsupported format'))
+        return EX_USAGE;
+    if (msg.startsWith('provide at least one'))
+        return EX_USAGE;
+    if (msg.includes('unrecognised font extension'))
+        return EX_USAGE;
+    if (msg.includes('exceeds the') && msg.includes('size cap'))
+        return EX_DATAERR;
+    if (msg.includes('refusing to'))
+        return EX_USAGE;
+    if (msg.startsWith('config') || msg.startsWith('output at index') || msg.includes(': "axes"'))
+        return EX_CONFIG;
+    return 1;
+}

package/dist/core/format.d.ts

@@ -0,0 +1,25 @@
+/**
+ * The canonical set of output formats vf-clamp can produce.
+ * Kept in lockstep with `OutputFormat` from `@liiift-studio/vf-clamp`; if the
+ * engine ever gains/drops a format, change this list and the TS type below.
+ * The compile-time `satisfies OutputFormat` check below catches drift.
+ */
+export declare const SUPPORTED_FORMATS: readonly ["ttf", "otf", "woff", "woff2"];
+/** Union of supported format strings — derived from `SUPPORTED_FORMATS`. */
+export type Format = (typeof SUPPORTED_FORMATS)[number];
+/**
+ * The set of input font extensions the CLI will accept.
+ * The leading dot is mandatory for `path.extname` comparison.
+ */
+export declare const SUPPORTED_INPUT_EXTENSIONS: readonly [".ttf", ".otf", ".woff", ".woff2"];
+/**
+ * Type-predicate version of format validation — narrows `format` to `Format`
+ * on success and throws a descriptive error on failure. Using `asserts` lets
+ * call sites drop the `as Format` cast at the engine boundary.
+ */
+export declare function assertFormat(format: string): asserts format is Format;
+/**
+ * Pure predicate variant — true if the string is a supported format.
+ * Useful when you want to test without throwing.
+ */
+export declare function isSupportedFormat(format: string): format is Format;

package/dist/core/format.js

@@ -0,0 +1,31 @@
+// Output format constants, type predicate, and validators shared between the CLI
+// surface and the engine call site.
+/**
+ * The canonical set of output formats vf-clamp can produce.
+ * Kept in lockstep with `OutputFormat` from `@liiift-studio/vf-clamp`; if the
+ * engine ever gains/drops a format, change this list and the TS type below.
+ * The compile-time `satisfies OutputFormat` check below catches drift.
+ */
+export const SUPPORTED_FORMATS = ['ttf', 'otf', 'woff', 'woff2'];
+/**
+ * The set of input font extensions the CLI will accept.
+ * The leading dot is mandatory for `path.extname` comparison.
+ */
+export const SUPPORTED_INPUT_EXTENSIONS = ['.ttf', '.otf', '.woff', '.woff2'];
+/**
+ * Type-predicate version of format validation — narrows `format` to `Format`
+ * on success and throws a descriptive error on failure. Using `asserts` lets
+ * call sites drop the `as Format` cast at the engine boundary.
+ */
+export function assertFormat(format) {
+    if (!SUPPORTED_FORMATS.includes(format)) {
+        throw new Error(`Unsupported format "${format}". Choose from: ${SUPPORTED_FORMATS.join(', ')}`);
+    }
+}
+/**
+ * Pure predicate variant — true if the string is a supported format.
+ * Useful when you want to test without throwing.
+ */
+export function isSupportedFormat(format) {
+    return SUPPORTED_FORMATS.includes(format);
+}

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/index.js

@@ -0,0 +1,66 @@
+#!/usr/bin/env node
+// CLI entry point — sets up the vf-clamp program, registers all subcommands,
+// installs signal handlers, and drives commander's async parser.
+import { createRequire } from 'node:module';
+import { program } from 'commander';
+import { registerInstancesCommand } from './commands/instances.js';
+import { registerClampCommand } from './commands/clamp.js';
+/**
+ * Read the package version at runtime from package.json so it never drifts
+ * from the declared version.  `createRequire` is used because this is an ESM
+ * module and `import.meta.url` is available in the Node.js ESM context.
+ * Falls back to a literal `'0.0.0'` if the file cannot be read (e.g. when the
+ * package is bundled in a non-standard layout).
+ */
+const require = createRequire(import.meta.url);
+function readVersion() {
+    try {
+        const pkg = require('../package.json');
+        if (pkg !== null &&
+            typeof pkg === 'object' &&
+            'version' in pkg &&
+            typeof pkg.version === 'string') {
+            return pkg.version;
+        }
+    }
+    catch {
+        // ignore — fall through to default
+    }
+    return '0.0.0';
+}
+const VERSION = readVersion();
+// Clean exit on Ctrl-C / SIGTERM with conventional exit code 130
+// (128 + SIGINT(2)) and a brief stderr notice.  Without this, partially
+// written outputs are an even bigger risk during long Pyodide runs.
+function installSignalHandlers() {
+    for (const signal of ['SIGINT', 'SIGTERM']) {
+        process.on(signal, () => {
+            process.stderr.write(`\nvf-clamp: aborted on ${signal}\n`);
+            // 128 + signal number — bash convention for terminated-by-signal.
+            const code = signal === 'SIGINT' ? 130 : 143;
+            process.exit(code);
+        });
+    }
+}
+installSignalHandlers();
+program
+    .name('vf-clamp')
+    .description('Restrict variable font axis ranges from the command line.\n' +
+    'Note: first run in a fresh process takes 10–20s while the engine initialises.')
+    .version(VERSION, '-v, --version', 'Print version number')
+    .showHelpAfterError('(run vf-clamp --help for usage)');
+registerInstancesCommand(program);
+registerClampCommand(program);
+// Use parseAsync so unhandled rejections in async action handlers surface
+// cleanly and so we control the final exit code.
+program.parseAsync(process.argv).then(() => {
+    // Explicit exit — Pyodide holds a large WASM heap and a watchdog timer
+    // that can keep the event loop alive long after work is done.  Honour
+    // any exit code already set by an action handler.
+    process.exit(process.exitCode ?? 0);
+}, (err) => {
+    const message = err instanceof Error ? err.message : String(err);
+    process.exitCode = 1;
+    process.stderr.write(`vf-clamp: ${message}\n`);
+    process.exit(1);
+});

package/dist/utils/font.d.ts

@@ -0,0 +1,62 @@
+/** Maximum input font file size we will read into memory (in bytes). */
+export declare const MAX_FONT_BYTES: number;
+/** Maximum bytes we will accept from stdin. */
+export declare const MAX_STDIN_BYTES: number;
+/**
+ * Reads a font file from disk and returns its contents as a tight `Uint8Array`.
+ *
+ * - Rejects files larger than `MAX_FONT_BYTES` to avoid OOM.
+ * - Returns a non-pooled `Uint8Array` (not a Node `Buffer`) so callers passing
+ *   the bytes across the WASM boundary do not risk pool aliasing.
+ * - Error messages echo the user-supplied path, not the resolved absolute
+ *   path, to avoid leaking server-side layout when invoked from services.
+ */
+export declare function readFontFile(filePath: string): Promise<Uint8Array>;
+/** Options accepted by writeOutputs. */
+export interface WriteOptions {
+    /** If false, throw rather than overwrite existing files. Defaults to true. */
+    force?: boolean;
+}
+/**
+ * Writes one or more clamped font output buffers to disk.
+ *
+ * - Validates each entry's format string against the supported set so a
+ *   misbehaving engine cannot inject `/`, `..`, or null bytes into the
+ *   filename via the extension.
+ * - Computes the destination path inside `outputDir` and rejects any path
+ *   that escapes the resolved output directory (defence against
+ *   `..`/absolute-path injection from configs).
+ * - Writes each output atomically: writes to `<dest>.tmp-<pid>-<rand>` and
+ *   renames into place, so a crash never leaves a half-written font.
+ * - Writes are issued in parallel via `Promise.all`.
+ * - Refuses to overwrite an existing file unless `options.force` is true.
+ *
+ * Returns the list of file paths written.
+ */
+export declare function writeOutputs(results: Array<{
+    name: string;
+    buffer: Uint8Array;
+    format: string;
+}>, outputDir: string, options?: WriteOptions): Promise<string[]>;
+/**
+ * Validates that a font file path has a recognised variable-font extension.
+ * Skips the check for `-` (stdin input).
+ * Throws if the extension is not recognised.
+ */
+export declare function assertFontExtension(filePath: string): void;
+/**
+ * Sanitizes a string for safe use as a filename stem.
+ *
+ * Defends against:
+ *   - path separators (`/`, `\`) being interpreted as directories
+ *   - null bytes terminating C-string filename APIs
+ *   - shell-special characters (`:*?"<>|`) on Windows
+ *   - ASCII control characters (`\0`–`\x1F`, `\x7F`) and Unicode whitespace
+ *   - embedded `..` segments that would resolve to a parent directory
+ *   - Windows reserved device names (CON, PRN, AUX, NUL, COM1–9, LPT1–9)
+ *   - names that are only dots or hyphens (would become empty after trim)
+ *   - filenames longer than 200 characters
+ *
+ * Falls back to `"output"` when sanitisation reduces the string to nothing.
+ */
+export declare function sanitizeFilename(name: string): string;

package/dist/utils/font.js

@@ -0,0 +1,196 @@
+// File I/O helpers for reading font files and writing clamped outputs.
+// All filesystem boundaries live in this module; pure logic lives under src/core.
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { SUPPORTED_INPUT_EXTENSIONS } from '../core/format.js';
+import { isSupportedFormat } from '../core/format.js';
+/** Maximum input font file size we will read into memory (in bytes). */
+export const MAX_FONT_BYTES = 256 * 1024 * 1024; // 256MB
+/** Maximum bytes we will accept from stdin. */
+export const MAX_STDIN_BYTES = MAX_FONT_BYTES;
+/**
+ * Reads a font file from disk and returns its contents as a tight `Uint8Array`.
+ *
+ * - Rejects files larger than `MAX_FONT_BYTES` to avoid OOM.
+ * - Returns a non-pooled `Uint8Array` (not a Node `Buffer`) so callers passing
+ *   the bytes across the WASM boundary do not risk pool aliasing.
+ * - Error messages echo the user-supplied path, not the resolved absolute
+ *   path, to avoid leaking server-side layout when invoked from services.
+ */
+export async function readFontFile(filePath) {
+    if (filePath === '-') {
+        return readStdin();
+    }
+    const resolved = path.resolve(filePath);
+    let stat;
+    try {
+        stat = await fs.stat(resolved);
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        throw new Error(`Could not read font file "${filePath}": ${message}`);
+    }
+    if (!stat.isFile()) {
+        throw new Error(`Path "${filePath}" is not a regular file`);
+    }
+    if (stat.size > MAX_FONT_BYTES) {
+        throw new Error(`Font file "${filePath}" exceeds the ${MAX_FONT_BYTES}-byte size cap`);
+    }
+    try {
+        const buf = await fs.readFile(resolved);
+        // Slice into a fresh, non-pooled Uint8Array view so the WASM bridge
+        // does not see Node's pooled-slab byte range.
+        return new Uint8Array(buf.buffer, buf.byteOffset, buf.byteLength).slice();
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        throw new Error(`Could not read font file "${filePath}": ${message}`);
+    }
+}
+/** Reads all bytes from stdin up to MAX_STDIN_BYTES. */
+async function readStdin() {
+    const chunks = [];
+    let total = 0;
+    for await (const chunk of process.stdin) {
+        const buf = typeof chunk === 'string' ? Buffer.from(chunk) : chunk;
+        total += buf.byteLength;
+        if (total > MAX_STDIN_BYTES) {
+            throw new Error(`stdin input exceeds the ${MAX_STDIN_BYTES}-byte size cap`);
+        }
+        chunks.push(buf);
+    }
+    const combined = Buffer.concat(chunks, total);
+    return new Uint8Array(combined.buffer, combined.byteOffset, combined.byteLength).slice();
+}
+/**
+ * Writes one or more clamped font output buffers to disk.
+ *
+ * - Validates each entry's format string against the supported set so a
+ *   misbehaving engine cannot inject `/`, `..`, or null bytes into the
+ *   filename via the extension.
+ * - Computes the destination path inside `outputDir` and rejects any path
+ *   that escapes the resolved output directory (defence against
+ *   `..`/absolute-path injection from configs).
+ * - Writes each output atomically: writes to `<dest>.tmp-<pid>-<rand>` and
+ *   renames into place, so a crash never leaves a half-written font.
+ * - Writes are issued in parallel via `Promise.all`.
+ * - Refuses to overwrite an existing file unless `options.force` is true.
+ *
+ * Returns the list of file paths written.
+ */
+export async function writeOutputs(results, outputDir, options = {}) {
+    const { force = true } = options;
+    const resolvedDir = path.resolve(outputDir);
+    // Ensure the output directory exists.
+    await fs.mkdir(resolvedDir, { recursive: true });
+    const dests = results.map((result) => {
+        const safeName = sanitizeFilename(result.name);
+        if (!isSupportedFormat(result.format)) {
+            throw new Error(`Engine returned unsupported format "${result.format}" for output "${result.name}"`);
+        }
+        const filename = `${safeName}.${result.format}`;
+        const dest = path.join(resolvedDir, filename);
+        // Defence in depth: ensure the resolved destination really sits inside
+        // resolvedDir even after `path.join` normalisation.
+        const rel = path.relative(resolvedDir, dest);
+        if (rel.startsWith('..') || path.isAbsolute(rel)) {
+            throw new Error(`Refusing to write output "${result.name}" outside output directory`);
+        }
+        return { dest, buffer: result.buffer };
+    });
+    if (!force) {
+        await Promise.all(dests.map(async ({ dest }) => {
+            try {
+                await fs.access(dest);
+            }
+            catch {
+                return; // file does not exist — good
+            }
+            throw new Error(`Refusing to overwrite existing file "${dest}" (use --force to overwrite)`);
+        }));
+    }
+    await Promise.all(dests.map(({ dest, buffer }) => writeAtomic(dest, buffer)));
+    return dests.map(({ dest }) => dest);
+}
+/**
+ * Writes data to a destination path atomically by writing to a sibling
+ * tempfile and renaming.  Rename is atomic on the same filesystem.
+ */
+async function writeAtomic(dest, data) {
+    const tmp = `${dest}.tmp-${process.pid}-${Math.random().toString(36).slice(2, 10)}`;
+    try {
+        await fs.writeFile(tmp, data);
+        await fs.rename(tmp, dest);
+    }
+    catch (err) {
+        // Best-effort cleanup of stray temp file.
+        await fs.unlink(tmp).catch(() => { });
+        throw err;
+    }
+}
+/**
+ * Validates that a font file path has a recognised variable-font extension.
+ * Skips the check for `-` (stdin input).
+ * Throws if the extension is not recognised.
+ */
+export function assertFontExtension(filePath) {
+    if (filePath === '-')
+        return;
+    const ext = path.extname(filePath).toLowerCase();
+    if (!SUPPORTED_INPUT_EXTENSIONS.includes(ext)) {
+        throw new Error(`Unrecognised font extension "${ext}". Supported: ${SUPPORTED_INPUT_EXTENSIONS.join(', ')}`);
+    }
+}
+/** Maximum filename length we will accept (most filesystems cap at 255). */
+const MAX_FILENAME_LENGTH = 200;
+/** Windows reserved device names (case-insensitive, with or without extension). */
+const WINDOWS_RESERVED = new Set([
+    'con', 'prn', 'aux', 'nul',
+    'com1', 'com2', 'com3', 'com4', 'com5', 'com6', 'com7', 'com8', 'com9',
+    'lpt1', 'lpt2', 'lpt3', 'lpt4', 'lpt5', 'lpt6', 'lpt7', 'lpt8', 'lpt9',
+]);
+/**
+ * Sanitizes a string for safe use as a filename stem.
+ *
+ * Defends against:
+ *   - path separators (`/`, `\`) being interpreted as directories
+ *   - null bytes terminating C-string filename APIs
+ *   - shell-special characters (`:*?"<>|`) on Windows
+ *   - ASCII control characters (`\0`–`\x1F`, `\x7F`) and Unicode whitespace
+ *   - embedded `..` segments that would resolve to a parent directory
+ *   - Windows reserved device names (CON, PRN, AUX, NUL, COM1–9, LPT1–9)
+ *   - names that are only dots or hyphens (would become empty after trim)
+ *   - filenames longer than 200 characters
+ *
+ * Falls back to `"output"` when sanitisation reduces the string to nothing.
+ */
+export function sanitizeFilename(name) {
+    // Strip ASCII control characters (including null, newlines, tabs) and DEL.
+    let safe = name.replace(/[\x00-\x1F\x7F]/g, '');
+    // Replace path separators and common shell-special chars with a hyphen.
+    safe = safe.replace(/[/\\:*?"<>|]/g, '-');
+    // Collapse `..` runs (which `path.normalize` would otherwise traverse) to
+    // a single dot so the result cannot describe a parent directory.
+    safe = safe.replace(/\.{2,}/g, '.');
+    // Collapse Unicode whitespace runs to a single space, then convert spaces
+    // to nothing (most filesystems handle spaces but we prefer not to).
+    safe = safe.replace(/\s+/g, ' ');
+    // Collapse multiple hyphens.
+    safe = safe.replace(/-{2,}/g, '-');
+    // Strip leading dots, spaces, and hyphens to avoid hidden files / relative paths.
+    safe = safe.replace(/^[.\s-]+/, '');
+    // Strip trailing dots, spaces and hyphens.
+    safe = safe.replace(/[.\s-]+$/, '');
+    // Truncate to a sane length.
+    if (safe.length > MAX_FILENAME_LENGTH) {
+        safe = safe.slice(0, MAX_FILENAME_LENGTH);
+        // Re-strip any trailing hyphens/dots produced by the truncation.
+        safe = safe.replace(/[.\s-]+$/, '');
+    }
+    // Reject Windows reserved device names (case-insensitive).
+    if (WINDOWS_RESERVED.has(safe.toLowerCase())) {
+        return 'output';
+    }
+    // Fall back to a safe default if nothing useful is left.
+    return safe || 'output';
+}

package/dist/utils/format.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Formats a two-column table for stdout.
+ * Each row is [label, value]; label column is padded to `labelWidth` characters.
+ */
+export declare function formatTable(rows: Array<[string, string]>, labelWidth?: number): string;
+/**
+ * Returns the arrow glyph (U+2192) when the host terminal supports UTF-8,
+ * otherwise `->` for compatibility with cmd.exe and non-UTF locales.
+ */
+export declare function arrowGlyph(): string;
+/**
+ * Returns the ellipsis glyph (U+2026) when UTF-8 is supported, else `...`.
+ */
+export declare function ellipsisGlyph(): string;

package/dist/utils/format.js

@@ -0,0 +1,36 @@
+// Generic UI formatting helpers — colocated here rather than in `utils/font.ts`
+// so font I/O stays decoupled from presentation concerns.
+/**
+ * Formats a two-column table for stdout.
+ * Each row is [label, value]; label column is padded to `labelWidth` characters.
+ */
+export function formatTable(rows, labelWidth = 18) {
+    return rows
+        .map(([label, value]) => `  ${label.padEnd(labelWidth)}${value}`)
+        .join('\n');
+}
+/**
+ * Returns the arrow glyph (U+2192) when the host terminal supports UTF-8,
+ * otherwise `->` for compatibility with cmd.exe and non-UTF locales.
+ */
+export function arrowGlyph() {
+    return supportsUtf8() ? '→' : '->';
+}
+/**
+ * Returns the ellipsis glyph (U+2026) when UTF-8 is supported, else `...`.
+ */
+export function ellipsisGlyph() {
+    return supportsUtf8() ? '…' : '...';
+}
+/**
+ * Conservative UTF-8 detection — true when stdout looks Unicode-capable.
+ * Falls back to ASCII on Windows cmd.exe and non-UTF locales.
+ */
+function supportsUtf8() {
+    if (process.platform === 'win32') {
+        // PowerShell/Windows Terminal set this; cmd.exe does not.
+        return Boolean(process.env.WT_SESSION || process.env.TERM_PROGRAM);
+    }
+    const lang = process.env.LC_ALL || process.env.LC_CTYPE || process.env.LANG || '';
+    return /UTF-?8/i.test(lang);
+}