@liiift-studio/vf-clamp-cli 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Liiift Studio
+
+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,194 @@
+# @liiift-studio/vf-clamp-cli
+
+A command-line interface for [`@liiift-studio/vf-clamp`](https://www.npmjs.com/package/@liiift-studio/vf-clamp) — restrict variable font axis ranges from the terminal without writing any JavaScript.
+
+## Install
+
+Requires **Node.js 18 or newer**.
+
+```bash
+npm install -g @liiift-studio/vf-clamp-cli
+```
+
+## Discovery
+
+```bash
+vf-clamp --help              # top-level overview, both subcommands
+vf-clamp --version           # also: -v
+vf-clamp clamp --help        # subcommand-specific help, examples, axis spec guide
+vf-clamp instances --help
+```
+
+## Usage
+
+### Inspect a font
+
+List all variable axes and named instances in a font file (TTF, OTF, WOFF, or WOFF2):
+
+```bash
+vf-clamp instances MyFont.ttf
+vf-clamp instances MyFont.ttf --json     # machine-readable
+```
+
+Example output (exact column spacing depends on your font):
+
+```
+Axes:
+  wght  Weight     100 → 900  (default: 400)
+  slnt  Slant      -10 → 0    (default: 0)
+
+Instances (18):
+  Thin              wght=100 slnt=0
+  ExtraLight        wght=200 slnt=0
+  Light             wght=300 slnt=0
+  Regular           wght=400 slnt=0
+  Medium            wght=500 slnt=0
+  SemiBold          wght=600 slnt=0
+  Bold              wght=700 slnt=0
+  ...
+```
+
+### Clamp a font
+
+Produce a restricted VF spanning the hull of named instances:
+
+```bash
+vf-clamp clamp MyFont.ttf --instance Light --instance Bold --name Light-Bold
+```
+
+Short flags are accepted for every option:
+
+```bash
+vf-clamp clamp MyFont.ttf -i Light -i Bold -n Light-Bold
+```
+
+Restrict using explicit axis ranges:
+
+```bash
+vf-clamp clamp MyFont.ttf -a wght:300:700 -n Custom -f woff2
+```
+
+Pin a single axis value, or keep an axis at its full original range:
+
+```bash
+vf-clamp clamp MyFont.ttf -a wght:400 -n Regular-Only
+vf-clamp clamp MyFont.ttf -i Light -i Bold -a wdth:*       # keep wdth untouched
+```
+
+Combine instances and axis overrides:
+
+```bash
+vf-clamp clamp MyFont.ttf -i Light -i Bold -a slnt:-5:0 -n LightBold-Slanted
+```
+
+Read source font from stdin and pipe results:
+
+```bash
+cat MyFont.ttf | vf-clamp clamp - -i Bold -n Bold-only -o ./out
+```
+
+Write output to a specific directory:
+
+```bash
+vf-clamp clamp MyFont.ttf -i Light -i Bold -o ./dist/fonts
+```
+
+When `--name` is omitted, the output filename is derived from the instance names (`Light-Bold`) or axis tags. All names are sanitised for filesystem safety: characters like `/`, `\`, `:`, `..`, ASCII control codes, and Windows reserved device names are stripped or rejected.
+
+### Clamp using a config file
+
+For multiple outputs in one pass, use a JSON config file. All outputs are produced in a single engine invocation — the font is parsed once, not N times.
+
+```bash
+vf-clamp clamp MyFont.ttf -c clamp.config.json
+```
+
+**clamp.config.json:**
+
+```json
+{
+  "format": "ttf",
+  "outputDir": "./output",
+  "outputs": [
+    {
+      "name": "Light-Bold",
+      "instances": ["Light", "Bold"]
+    },
+    {
+      "name": "Condensed",
+      "axes": { "wdth": { "min": 50, "max": 75 } }
+    },
+    {
+      "name": "WeightRange-KeepWidth",
+      "axes": { "wght": { "min": 100, "max": 700 }, "wdth": null }
+    }
+  ]
+}
+```
+
+Each output must specify either `instances`, `axes` (non-empty), or both. Axis values may be a number (pin), `{ "min": …, "max": … }` (range), or `null` (keep full original range).
+
+CLI flags `--instance`, `--axis`, and `--name` are ignored when `--config` is used; a warning is printed to stderr.
+
+## Options
+
+### `vf-clamp instances <font>`
+
+| Argument / Option | Description |
+|----------|-------------|
+| `<font>` | Path to TTF, OTF, WOFF, or WOFF2 file (or `-` for stdin) |
+| `--json` | Print results as JSON to stdout |
+| `-q, --quiet` | Suppress progress messages on stderr |
+| `--verbose` | Print Python tracebacks on engine errors |
+
+### `vf-clamp clamp <font> [options]`
+
+| Option | Description |
+|--------|-------------|
+| `<font>` | Path to TTF, OTF, WOFF, or WOFF2 file (or `-` for stdin) |
+| `-i, --instance <name>` | Named instance to include (repeatable) |
+| `-a, --axis <tag:value>` | Pin an axis to a fixed value |
+| `-a, --axis <tag:min:max>` | Restrict an axis to a range |
+| `-a, --axis <tag:*>` (or `tag:keep`) | Keep axis at its full original range |
+| `-n, --name <name>` | Output name (filename stem; sanitised for filesystem safety) |
+| `-f, --format <fmt>` | Output format: `ttf` (default), `otf`, `woff`, `woff2` |
+| `-o, --output <dir>` | Output directory (default: current directory) |
+| `-c, --config <file>` | JSON config file (for multiple outputs) |
+| `--no-force` | Refuse to overwrite existing output files |
+| `--dry-run` | Validate inputs without invoking the engine or writing files |
+| `--json` | Print results as JSON to stdout |
+| `-q, --quiet` | Suppress progress messages on stderr |
+| `--verbose` | Print Python tracebacks on engine errors |
+
+## Output and exit codes
+
+For scripting, output paths are written one-per-line to **stdout**; all progress and error messages go to **stderr**:
+
+```bash
+vf-clamp clamp MyFont.ttf -i Light -i Bold | xargs -n1 woff2_compress
+```
+
+Exit codes follow BSD `sysexits` conventions:
+
+| Code | Meaning |
+|------|---------|
+| 0 | Success |
+| 2 | Usage / validation error (bad flags, malformed `--axis`, missing inputs) |
+| 65 | Input data error (bad font, bad JSON config) |
+| 66 | Input file missing or unreadable |
+| 70 | Internal engine error |
+| 78 | Invalid configuration |
+| 130 | Aborted by Ctrl-C (SIGINT) |
+
+## Performance Note
+
+The underlying engine uses Pyodide (Python WASM). The first run in a process takes approximately **10–20 seconds** to initialise. Subsequent calls in the same process are **1–2 seconds**. This is expected — plan config-file batching for large workflows so the engine pays cold-start only once.
+
+## Related
+
+- [`@liiift-studio/vf-clamp`](https://www.npmjs.com/package/@liiift-studio/vf-clamp) — the core library
+- [vfclamp.com](https://vfclamp.com) — web interface
+
+## License
+
+MIT © [Liiift Studio](https://liiift.studio)

package/dist/commands/clamp.d.ts

@@ -0,0 +1,9 @@
+import type { Command } from 'commander';
+import { EX_USAGE, EX_DATAERR, EX_NOINPUT, EX_CONFIG, EX_SOFTWARE } from '../core/exitCodes.js';
+export { parseAxisSpecs } from '../core/axisSpecs.js';
+/**
+ * Registers the `clamp` subcommand on the given commander program.
+ * Usage: vf-clamp clamp <font> [options]
+ */
+export declare function registerClampCommand(program: Command): void;
+export { EX_USAGE, EX_DATAERR, EX_NOINPUT, EX_CONFIG, EX_SOFTWARE };

package/dist/commands/clamp.js

@@ -0,0 +1,202 @@
+// `vf-clamp clamp <font>` — produce one or more restricted variable font files.
+// Wires commander flags onto the pure config/parser/format-validator layer in
+// `src/core/*` and the IO helpers in `src/utils/*`.
+import { readFontFile, writeOutputs, assertFontExtension, sanitizeFilename } from '../utils/font.js';
+import { ellipsisGlyph } from '../utils/format.js';
+import { SUPPORTED_FORMATS, assertFormat } from '../core/format.js';
+import { parseAxisSpecs } from '../core/axisSpecs.js';
+import { readConfig } from '../core/config.js';
+import { EX_USAGE, EX_DATAERR, EX_NOINPUT, EX_CONFIG, EX_SOFTWARE, classifyError } from '../core/exitCodes.js';
+// Re-export parseAxisSpecs for backward compatibility with existing tests
+// while keeping the canonical home in `src/core/axisSpecs.ts`.
+export { parseAxisSpecs } from '../core/axisSpecs.js';
+/**
+ * Registers the `clamp` subcommand on the given commander program.
+ * Usage: vf-clamp clamp <font> [options]
+ */
+export function registerClampCommand(program) {
+    program
+        .command('clamp <font>')
+        .description('Produce one or more restricted variable font files.\n' +
+        'Pass "-" for <font> to read the source font from stdin.')
+        .option('-i, --instance <name>', 'Named instance to include in hull (repeatable)', collect, [])
+        .option('-a, --axis <spec>', 'Pin or restrict an axis: tag:value, tag:min:max, or tag:* (repeatable)', collect, [])
+        .option('-n, --name <name>', 'Output name (filename stem)')
+        .option('-f, --format <fmt>', `Output format: ${SUPPORTED_FORMATS.join(' | ')}`, 'ttf')
+        .option('-o, --output <dir>', 'Output directory', '.')
+        .option('-c, --config <file>', 'JSON config file for multiple outputs')
+        .option('--force', 'Overwrite existing output files without warning', true)
+        .option('--no-force', 'Refuse to overwrite existing output files')
+        .option('--dry-run', 'Validate inputs without invoking the engine or writing files')
+        .option('--json', 'Print results as JSON to stdout')
+        .option('-q, --quiet', 'Suppress progress messages on stderr')
+        .option('--verbose', 'Print extra diagnostic output (Python tracebacks on error)')
+        .addHelpText('after', `
+Examples:
+  $ vf-clamp clamp MyFont.ttf -i Light -i Bold -n Light-Bold
+  $ vf-clamp clamp MyFont.ttf -a wght:300:700 -f woff2
+  $ vf-clamp clamp MyFont.ttf -a wght:400 -n Regular-Only
+  $ vf-clamp clamp MyFont.ttf -i Light -i Bold -a slnt:-5:0 -n LightBold-Slanted
+  $ vf-clamp clamp MyFont.ttf -c clamp.config.json
+  $ cat MyFont.ttf | vf-clamp clamp - -i Bold -n Bold-only
+
+Axis spec forms:
+  tag:value      pin the axis to a single value
+  tag:min:max    restrict the axis to a sub-range
+  tag:*          keep the axis at its full original range
+  tag:keep       alias for tag:*
+
+Exit codes:
+  0  success
+  2  usage / validation error (bad flags, malformed --axis, missing inputs)
+  65 input data error (bad font, bad JSON config)
+  66 input file missing or unreadable
+  70 internal engine error
+  78 invalid configuration
+
+First run in a fresh process takes 10–20s while Pyodide initialises.
+`)
+        .action(async (fontPath, opts) => {
+        try {
+            await runClamp(fontPath, opts);
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            const code = classifyError(err);
+            const detail = opts.verbose && err instanceof Error && err.stack ? `\n${err.stack}` : '';
+            // Set exitCode and write to stderr; the entry point's parseAsync
+            // handler will exit with the correct code after the event loop drains.
+            process.exitCode = code;
+            process.stderr.write(`vf-clamp clamp: ${message}${detail}\n`);
+        }
+    });
+}
+/**
+ * Core clamp action — separated from the commander handler so it can be
+ * driven directly from tests.
+ */
+async function runClamp(fontPath, opts) {
+    assertFontExtension(fontPath);
+    // Build request list and resolve effective format/outputDir.
+    let outputRequests;
+    let format;
+    let outputDir;
+    if (opts.config) {
+        // Warn loudly when CLI flags conflict with config-supplied values.
+        warnIfFlagsIgnored(opts);
+        const config = await readConfig(opts.config);
+        outputRequests = config.outputs.map((output, idx) => ({
+            name: sanitizeFilename(output.name ?? `output-${idx + 1}`),
+            ...(output.instances ? { instances: output.instances } : {}),
+            ...(output.axes ? { axes: output.axes } : {}),
+        }));
+        const candidateFormat = config.format ?? opts.format;
+        assertFormat(candidateFormat);
+        format = candidateFormat;
+        outputDir = config.outputDir ?? opts.output;
+    }
+    else {
+        assertFormat(opts.format);
+        format = opts.format;
+        outputDir = opts.output;
+        outputRequests = buildRequestFromFlags(opts);
+    }
+    if (opts.dryRun) {
+        const lines = outputRequests.map((r, i) => `  [${i + 1}] ${r.name}.${format}`).join('\n');
+        writeLog(opts, `Dry run: ${outputRequests.length} output(s) would be written to ${outputDir}\n${lines}\n`);
+        return;
+    }
+    // Read source font (after dry-run check so dry-run does not read the file).
+    const buffer = await readFontFile(fontPath);
+    writeLog(opts, `Processing ${outputRequests.length} output(s)${ellipsisGlyph()} (first run may take 10–20s)\n`);
+    // Dynamic import so `--help`/`--version`/dry-run do not pay the engine's
+    // ESM resolution and Pyodide bootstrap cost.
+    const { clampFont } = await import('@liiift-studio/vf-clamp');
+    // Batch ALL outputs into a single clampFont call so Pyodide is initialised
+    // once, the font buffer crosses the WASM bridge once, and fontTools parses
+    // the TTFont once.  The engine's `outputs` array is designed for this.
+    const clampOutputs = outputRequests.map(buildClampOutput);
+    const results = await clampFont(buffer, {
+        outputs: clampOutputs,
+        format,
+    });
+    // Pair engine results back with the names we requested so writeOutputs can
+    // compose filenames using our sanitised names rather than whatever the
+    // engine echoed back.
+    const writeInputs = results.map((result, i) => ({
+        name: outputRequests[i]?.name ?? result.name,
+        buffer: result.buffer,
+        format: result.format ?? format,
+    }));
+    const written = await writeOutputs(writeInputs, outputDir, { force: opts.force !== false });
+    if (opts.json) {
+        process.stdout.write(JSON.stringify({ written }) + '\n');
+    }
+    else {
+        for (const filePath of written) {
+            // Bare paths on stdout so consumers can `... | xargs` them.
+            process.stdout.write(`${filePath}\n`);
+        }
+    }
+}
+/** Commander value collector — appends each repeated flag value into an array. */
+function collect(value, previous) {
+    return [...previous, value];
+}
+/**
+ * Emits stderr warnings when --config is combined with flags whose values
+ * would have been used in flag-mode.  Avoids the silent-override footgun.
+ */
+function warnIfFlagsIgnored(opts) {
+    const ignored = [];
+    if (opts.instance.length > 0)
+        ignored.push('--instance');
+    if (opts.axis.length > 0)
+        ignored.push('--axis');
+    if (opts.name)
+        ignored.push('--name');
+    if (ignored.length > 0 && !opts.quiet) {
+        process.stderr.write(`vf-clamp clamp: warning — ${ignored.join(', ')} ignored when --config is used\n`);
+    }
+}
+/**
+ * Builds a single output request from CLI flags.
+ * Requires at least one --instance or --axis flag.
+ */
+function buildRequestFromFlags(opts) {
+    const { instance: instances, axis: axisSpecs, name } = opts;
+    if (instances.length === 0 && axisSpecs.length === 0) {
+        const err = new Error('Provide at least one --instance or --axis flag, or use --config for a config file.');
+        // Mark for the exit-code classifier.
+        err.code = 'USAGE';
+        throw err;
+    }
+    const axes = parseAxisSpecs(axisSpecs);
+    const rawName = name ?? (instances.length > 0 ? instances.join('-') : Object.keys(axes).join('-'));
+    const safeName = sanitizeFilename(rawName);
+    const req = { name: safeName };
+    if (instances.length > 0)
+        req.instances = instances;
+    if (Object.keys(axes).length > 0)
+        req.axes = axes;
+    return [req];
+}
+/**
+ * Converts an OutputRequest into the shape expected by clampFont's `outputs` array.
+ */
+function buildClampOutput(req) {
+    return {
+        name: req.name,
+        ...(req.instances ? { instances: req.instances } : {}),
+        ...(req.axes ? { axes: req.axes } : {}),
+    };
+}
+/** Writes a progress/log line to stderr unless quiet or stderr is closed. */
+function writeLog(opts, message) {
+    if (opts.quiet || opts.json)
+        return;
+    process.stderr.write(message);
+}
+// Re-export typed exit codes so other modules can use them without
+// reaching into core/.
+export { EX_USAGE, EX_DATAERR, EX_NOINPUT, EX_CONFIG, EX_SOFTWARE };

package/dist/commands/instances.d.ts

@@ -0,0 +1,6 @@
+import type { Command } from 'commander';
+/**
+ * Registers the `instances` subcommand on the given commander program.
+ * Usage: vf-clamp instances <font>
+ */
+export declare function registerInstancesCommand(program: Command): void;

package/dist/commands/instances.js

@@ -0,0 +1,89 @@
+// `vf-clamp instances <font>` — print all variable axes and named instances in a font.
+import { readFontFile, assertFontExtension } from '../utils/font.js';
+import { formatTable, arrowGlyph, ellipsisGlyph } from '../utils/format.js';
+import { classifyError } from '../core/exitCodes.js';
+/**
+ * Registers the `instances` subcommand on the given commander program.
+ * Usage: vf-clamp instances <font>
+ */
+export function registerInstancesCommand(program) {
+    program
+        .command('instances <font>')
+        .description('List all variable axes and named instances in a font file.\n' +
+        'Pass "-" for <font> to read the source font from stdin.')
+        .option('--json', 'Print results as JSON to stdout')
+        .option('-q, --quiet', 'Suppress progress messages on stderr')
+        .option('--verbose', 'Print extra diagnostic output (Python tracebacks on error)')
+        .addHelpText('after', '\nFirst run in a fresh process takes 10–20s while Pyodide initialises.\n')
+        .action(async (fontPath, opts) => {
+        try {
+            await runInstances(fontPath, opts);
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            const code = classifyError(err);
+            const detail = opts.verbose && err instanceof Error && err.stack ? `\n${err.stack}` : '';
+            process.exitCode = code;
+            process.stderr.write(`vf-clamp instances: ${message}${detail}\n`);
+        }
+    });
+}
+/** Core action — extracted so tests can drive it directly. */
+async function runInstances(fontPath, opts) {
+    assertFontExtension(fontPath);
+    const buffer = await readFontFile(fontPath);
+    if (!opts.quiet && !opts.json) {
+        process.stderr.write(`Reading font${ellipsisGlyph()} (first run may take 10–20s)\n`);
+    }
+    // Dynamic import so --help/--version do not pay engine ESM resolution cost.
+    const { getInstances } = await import('@liiift-studio/vf-clamp');
+    const { axes, instances } = await getInstances(buffer);
+    if (axes.length === 0 && !opts.quiet && !opts.json) {
+        process.stderr.write(`Warning: "${fontPath}" has no variable axes — this appears to be a static font.\n`);
+    }
+    if (opts.json) {
+        process.stdout.write(JSON.stringify({ axes, instances }) + '\n');
+        return;
+    }
+    printAxes(axes);
+    printInstances(instances);
+}
+/**
+ * Prints the axes section to stdout.
+ * Format: tag  Name   min → max  (default: N)
+ */
+function printAxes(axes) {
+    process.stdout.write('\nAxes:\n');
+    if (axes.length === 0) {
+        process.stdout.write('  (none — this may not be a variable font)\n');
+        return;
+    }
+    const TAG_WIDTH = Math.max(4, ...axes.map((a) => a.tag.length)) + 2;
+    const NAME_WIDTH = Math.max(4, ...axes.map((a) => a.name.length)) + 2;
+    const arrow = arrowGlyph();
+    for (const axis of axes) {
+        const tag = axis.tag.padEnd(TAG_WIDTH);
+        const name = axis.name.padEnd(NAME_WIDTH);
+        const range = `${axis.minimum} ${arrow} ${axis.maximum}`;
+        process.stdout.write(`  ${tag}${name}${range}  (default: ${axis.default})\n`);
+    }
+}
+/**
+ * Prints the named instances section to stdout.
+ * Format: Name   wght=300 slnt=0 …
+ */
+function printInstances(instances) {
+    process.stdout.write(`\nInstances (${instances.length}):\n`);
+    if (instances.length === 0) {
+        process.stdout.write('  (none)\n');
+        return;
+    }
+    const NAME_WIDTH = Math.max(4, ...instances.map((i) => i.name.length)) + 2;
+    const rows = instances.map((inst) => {
+        const coords = Object.entries(inst.coordinates)
+            .map(([tag, val]) => `${tag}=${val}`)
+            .join(' ');
+        return [inst.name, coords];
+    });
+    process.stdout.write(formatTable(rows, NAME_WIDTH) + '\n');
+}

package/dist/core/axisSpecs.d.ts

@@ -0,0 +1,15 @@
+import type { AxisValue } from '@liiift-studio/vf-clamp';
+/**
+ * Parses `--axis` flag values into a structured axes map.
+ * Accepted forms:
+ *   tag:value        → pin to exact value (stored as a number)
+ *   tag:min:max      → restrict to range (both min and max are required)
+ *   tag:*  / tag:keep → keep axis at its full original range (stored as null)
+ *
+ * Rejects non-finite numbers (Infinity, NaN), empty strings, and tags that
+ * are not the OpenType 4-character printable-ASCII form.
+ *
+ * Negative values are supported: slnt:-10:0 parses correctly because `-10`
+ * contains no colon.
+ */
+export declare function parseAxisSpecs(specs: string[]): Record<string, AxisValue>;

package/dist/core/axisSpecs.js

@@ -0,0 +1,85 @@
+// Axis spec parser — pure logic, no commander/IO dependencies.
+// Moved out of `commands/clamp.ts` so the test suite can import it without
+// pulling commander or the engine.
+/** Regex for OpenType axis tags — exactly 4 printable ASCII characters. */
+const AXIS_TAG_REGEX = /^[\x20-\x7E]{4}$/;
+/**
+ * Parses `--axis` flag values into a structured axes map.
+ * Accepted forms:
+ *   tag:value        → pin to exact value (stored as a number)
+ *   tag:min:max      → restrict to range (both min and max are required)
+ *   tag:*  / tag:keep → keep axis at its full original range (stored as null)
+ *
+ * Rejects non-finite numbers (Infinity, NaN), empty strings, and tags that
+ * are not the OpenType 4-character printable-ASCII form.
+ *
+ * Negative values are supported: slnt:-10:0 parses correctly because `-10`
+ * contains no colon.
+ */
+export function parseAxisSpecs(specs) {
+    const axes = {};
+    for (const spec of specs) {
+        const colonIdx = spec.indexOf(':');
+        if (colonIdx === -1) {
+            throw new Error(`Invalid --axis value "${spec}". Expected tag:value or tag:min:max`);
+        }
+        const tag = spec.slice(0, colonIdx).trim();
+        if (!tag) {
+            throw new Error(`Invalid --axis value "${spec}": axis tag is empty`);
+        }
+        // OpenType axis tags are exactly 4 printable ASCII characters.  Reject
+        // anything else early — the engine error otherwise is cryptic.
+        if (!AXIS_TAG_REGEX.test(tag)) {
+            throw new Error(`Invalid --axis value "${spec}": tag "${tag}" must be exactly 4 printable ASCII characters`);
+        }
+        const rest = spec.slice(colonIdx + 1);
+        // Null form: tag:* or tag:keep — keep axis at its full original range.
+        if (rest === '*' || rest.toLowerCase() === 'keep') {
+            axes[tag] = null;
+            continue;
+        }
+        const secondColon = rest.indexOf(':');
+        if (secondColon === -1) {
+            // Pin form: tag:value
+            const value = parseFiniteNumber(rest);
+            if (value === null) {
+                throw new Error(`Invalid --axis value "${spec}": "${rest}" is not a finite number`);
+            }
+            axes[tag] = value;
+        }
+        else {
+            // Range form: tag:min:max
+            const minStr = rest.slice(0, secondColon);
+            const maxStr = rest.slice(secondColon + 1);
+            const min = parseFiniteNumber(minStr);
+            const max = parseFiniteNumber(maxStr);
+            if (min === null) {
+                throw new Error(`Invalid --axis value "${spec}": min "${minStr}" is not a finite number`);
+            }
+            if (max === null) {
+                throw new Error(`Invalid --axis value "${spec}": max "${maxStr}" is not a finite number`);
+            }
+            if (min > max) {
+                throw new Error(`Invalid --axis "${spec}": min (${min}) must not exceed max (${max})`);
+            }
+            axes[tag] = { min, max };
+        }
+    }
+    return axes;
+}
+/**
+ * Parses a string as a finite number, returning `null` for any value that
+ * is not a finite, fully-numeric string.  Unlike global `isNaN`, this:
+ *   - rejects the empty string (`Number('')` returns 0)
+ *   - rejects `'Infinity'` and `'-Infinity'`
+ *   - rejects whitespace-only or trailing-garbage strings
+ */
+function parseFiniteNumber(raw) {
+    const trimmed = raw.trim();
+    if (trimmed === '')
+        return null;
+    const n = Number(trimmed);
+    if (!Number.isFinite(n))
+        return null;
+    return n;
+}

package/dist/core/config.d.ts

@@ -0,0 +1,35 @@
+import type { AxisValue } from '@liiift-studio/vf-clamp';
+import { type Format } from './format.js';
+/** Shape of a single output entry in a config file. */
+export interface ConfigOutput {
+    name?: string;
+    instances?: string[];
+    /** Axis constraints: number to pin, {min,max} to restrict, null to keep full range. */
+    axes?: Record<string, AxisValue>;
+}
+/** Validated shape of a config file. */
+export interface ClampConfig {
+    format?: Format;
+    outputDir?: string;
+    outputs: ConfigOutput[];
+}
+/** A resolved output request passed to clampFont. */
+export interface OutputRequest {
+    name: string;
+    instances?: string[];
+    axes?: Record<string, AxisValue>;
+}
+/**
+ * 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 declare function readConfig(configPath: string): Promise<ClampConfig>;
+/**
+ * Validates a parsed JSON value against the ClampConfig schema.
+ * Exported separately so tests can exercise validation without disk I/O.
+ */
+export declare function validateConfig(input: unknown): ClampConfig;