Automate Font Metadata Extraction in CI

For uncompressed fonts you don't even need a decompressor — opentype.js reads the sfnt directly. This emits the same JSON the browser tool downloads.

// extract-metadata.mjs
import fs from 'node:fs';
import opentype from 'opentype.js';

const NAME_LABELS = {
  copyright:'Copyright', fontFamily:'Family', fontSubfamily:'Subfamily',
  uniqueID:'Unique ID', fullName:'Full name', version:'Version',
  postScriptName:'PostScript name', trademark:'Trademark',
  manufacturer:'Manufacturer', designer:'Designer', description:'Description',
  manufacturerURL:'Manufacturer URL', designerURL:'Designer URL',
  license:'License', licenseURL:'License URL', sampleText:'Sample text',
};

function extract(path) {
  const buf = fs.readFileSync(path);
  const font = opentype.parse(buf.buffer.slice(buf.byteOffset, buf.byteOffset + buf.byteLength));
  const names = {};
  for (const k of Object.keys(font.names ?? {})) {
    const v = font.getEnglishName(k);
    if (v) names[NAME_LABELS[k] ?? k] = v;
  }
  return {
    filename: path.split('/').pop(),
    file_size: buf.byteLength,
    units_per_em: font.unitsPerEm,
    num_glyphs: font.numGlyphs,
    outlines_format: font.outlinesFormat,
    tables_present: Object.keys(font.tables).sort(),
    names,
  };
}

console.log(JSON.stringify(extract(process.argv[2]), null, 2));

WOFF2 must be Brotli-decompressed to an sfnt before opentype.js can parse it — the same step the browser tool runs via wawoff2. Decompress first, then feed the sfnt buffer to opentype.parse.

import wawoff2 from 'wawoff2';   // wasm WOFF2 codec
import opentype from 'opentype.js';
import fs from 'node:fs';

const woff2 = fs.readFileSync('Inter-Regular.woff2');
const sfnt = await wawoff2.decompress(new Uint8Array(woff2));
const font = opentype.parse(sfnt.buffer.slice(sfnt.byteOffset, sfnt.byteOffset + sfnt.byteLength));

// font.names, font.numGlyphs, font.outlinesFormat ... as before
// WOFF 1.0: inflate each table's zlib stream and rebuild the sfnt,
// then parse the same way.

The CI core: enumerate fonts, extract each, write a manifest file alongside. Commit dist/audit/ as the baseline future builds diff against.

import fs from 'node:fs';
import path from 'node:path';

const SRC = 'public/fonts', OUT = 'dist/audit';
fs.mkdirSync(OUT, { recursive: true });

for (const f of fs.readdirSync(SRC)) {
  if (!/\.(ttf|otf|woff|woff2)$/i.test(f)) continue;
  const meta = await extractAny(path.join(SRC, f)); // TTF/OTF/WOFF/WOFF2 aware
  fs.writeFileSync(path.join(OUT, f + '.json'), JSON.stringify(meta, null, 2));
  console.log(`extracted ${f}: ${meta.names.Family} ${meta.names.Version ?? ''}`);
}

Diff the freshly-extracted manifest against the committed baseline. Any difference fails the build until someone acknowledges it by updating the baseline in the PR.

# package.json
"scripts": {
  "fonts:extract": "node extract-all.mjs",
  "fonts:check": "node extract-all.mjs && git diff --exit-code dist/audit/"
}

# CI step
- run: npm run fonts:check
# exits non-zero if any font's metadata changed since the
# committed baseline -> reviewer must intentionally update it

If you'd rather use JAD's exact engine than reimplement, pair the runner and POST to localhost. The hosted /api/v1 endpoint only returns the schema and pairing instructions — it never accepts the font itself.

# 1. Pair the runner once (see /docs/runner)
# 2. Discover the tool (schema/info), no upload:
curl -H "Authorization: Bearer $JAD_KEY" \
  https://<host>/api/v1/tools/font-metadata-extractor

# 3. Execute on YOUR machine via the local runner:
curl -X POST http://127.0.0.1:9789/v1/tools/font-metadata-extractor/run \
  -F file=@public/fonts/Inter-Regular.woff2
# -> same metadata JSON the browser tool produces; the font
#    never leaves your network.

Font tools are browser-only, and JAD's public POST /api/v1/tools/.../run deliberately refuses uploads — it returns 400 with pairing instructions and the localhost runner endpoint. Don't build a pipeline that uploads fonts to the hosted API; either reimplement in Node or POST to the paired runner on 127.0.0.1:9789.

opentype.js cannot parse a WOFF2 (or WOFF) directly — it expects an sfnt. You must Brotli-decompress WOFF2 (wawoff2) or zlib-inflate WOFF first. The browser tool does this transparently; a Node reimplementation must do it explicitly, or every WOFF2 will throw.

The published wawoff2 wrapper has a known init race where the runtime callback can be missed and decompress hangs. The browser tool works around it by racing onRuntimeInitialized, Module.calledRun, and the bound function. In Node, either use a wrapper version that handles this or add your own readiness poll with a timeout so CI fails fast instead of hanging.

getEnglishName returns only the English record. A font that stores its records solely in another language yields a thin or empty names object even though records exist. If your audit must capture every platform/language record, the opentype.js path won't suffice — drop to fonttools ttx for those specific fonts.

The browser tool rejects .ttc, and the simple opentype.parse path won't handle a collection either. Filter .ttc out of your walk, or split each face first. If you skip them silently, your manifest will be missing those faces with no error — log skips explicitly.

If you drive the tool via the runner, the same per-file size limits apply (5 MB free, 50 MB Pro, 1 GB Developer). A reimplementation in pure Node has no such limit — only available memory — so for very large fonts the Node path is the more flexible automation route.

If your build subsets fonts per page, the manifest's num_glyphs and any fingerprint change every build, drowning real drift in noise. Pin the pre-subset source font's metadata for drift detection, and track the subset config (input glyph set) rather than the output binary.

Diffing on nameID 5 alone is fragile because foundries format it inconsistently and some don't bump it. Diff the whole manifest entry (version + num_glyphs + tables_present + sha256) so a change in any dimension trips the gate, not just the version string.

If your pipeline tries to edit records after extraction, note that opentype.js's name-table writer is unreliable for some platform/encoding combinations — the browser tool is read-only for exactly this reason. For edits, use a desktop tool or fonttools and re-extract to verify, rather than round-tripping through opentype.js.

Detect format from the first four magic bytes, not the extension — the browser tool does. A WOFF2 named .ttf will fail a naive 'if .ttf parse directly' branch. Sniff the magic (wOF2 = 0x774F4632, wOFF = 0x774F4646, 0x00010000 TTF, OTTO OTF) and route to the right decoder.