diff --git a/docs/superpowers/plans/2026-07-31-font-conversion.md b/docs/superpowers/plans/2026-07-31-font-conversion.md new file mode 100644 index 0000000..92102b7 --- /dev/null +++ b/docs/superpowers/plans/2026-07-31-font-conversion.md @@ -0,0 +1,746 @@ +# Font Conversion (ttf/otf/woff/dfont) Implementation Plan + +> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking. + +**Goal:** Add font format conversion — `ttf`/`otf`/`woff` bidirectional, plus `dfont` (Mac OS X font suitcase) as a source-only format. + +**Architecture:** Two new converter modules (`src/converters/font.js`, `src/converters/dfont.js`) register into the existing generic `sourceFormat -> targetFormat` registry, following the exact pattern `src/converters/ico.js`/`heic.js` already use. `fonteditor-core` is the primary read/write engine (robust against real-world fonts, but cannot write `.otf`). `opentype.js` fills the one gap — writing `.otf` — but is best-effort: it throws for fonts using certain OpenType layout tables, and that throw is left to the existing generic worker error handling, not specially caught. `fontkit` is used only to parse a `dfont`'s resource-fork-style container and locate the raw bytes of its embedded font(s), which are then run back through the same `font.js` logic used for a normal upload. + +**Tech Stack:** Node.js (ESM), Express, Prisma/MySQL, vitest+supertest. + +## Global Constraints + +- No dependency with native/compiled bindings — `fonteditor-core`, `opentype.js`, and `fontkit` are all pure JS/WASM with no compile step (verified: none ship a `binding.gyp`), satisfying o2switch's shared-hosting/no-toolchain requirement. +- `cff` and `cid` are explicitly **out of scope** — dropped during design, no viable library either direction. Never add a converter, MIME entry, or fixture for them. +- `dfont` is **source-only** — never register anything with `dfont` as a `targetFormat`. +- `.otf` as a **target** is best-effort. It will throw for some real fonts (confirmed: `"Unable to write GSUB lookup type 7 tables."` for Arial/Times New Roman/Candara). Do not add try/catch or fallback logic around this — the existing `processJob` catch-all in `src/worker.js` already turns any thrown error into a failed job with a generic message. +- `fontkit` has **no default ESM export** in this project's `"type": "module"` setup — `import fontkit from 'fontkit'` throws `SyntaxError: The requested module 'fontkit' does not provide an export named 'default'`. Always use `import * as fontkit from 'fontkit'`. +- Any new converter registration must be added to **both** `src/app.js` and `src/worker.js` — they independently duplicate the registration call list. +- Local test runs must use `.env.local`-equivalent inline env vars, never load real `.env` prod credentials (see `CLAUDE.md`). Run tests with: + ``` + DB_HOST=127.0.0.1 DB_USER=convert_user DB_PASSWORD=change_me DB_NAME=file_converter STORAGE_DIR=./storage PORT=3000 npx vitest run + ``` +- Font fixtures cannot be synthesized by the toolchain — they must be real, openly-licensed files committed to `test/fixtures/`, with an attribution file documenting source and license (see `test/fixtures/HEIC_ATTRIBUTION.md` for the existing convention). + +--- + +### Task 1: Dependencies and font fixtures + +**Files:** +- Modify: `package.json` (add `fonteditor-core`, `opentype.js`, `fontkit`) +- Create: `test/fixtures/sample.otf`, `test/fixtures/sample.ttf`, `test/fixtures/sample.dfont` +- Create: `test/fixtures/FONT_ATTRIBUTION.md` +- Create: `test/converters/font.test.js` (fixture smoke test only, extended in Task 2) + +**Interfaces:** +- Consumes: nothing. +- Produces: `test/fixtures/sample.otf` (Adobe Source Code Pro Regular, CFF outlines, 1568 glyphs), `test/fixtures/sample.ttf` (same font family's TTF build, glyf outlines, same 1568 glyphs — deliberately matched so later tasks can assert glyph-count fidelity across conversions), `test/fixtures/sample.dfont` (fonttools' own tiny test fixture, one embedded TrueType `sfnt` resource, 7 glyphs). + +- [ ] **Step 1: Install the font libraries** + +```bash +npm install fonteditor-core opentype.js fontkit +``` + +- [ ] **Step 2: Download the font fixtures** + +```bash +curl -sL -o test/fixtures/sample.otf "https://raw.githubusercontent.com/adobe-fonts/source-code-pro/release/OTF/SourceCodePro-Regular.otf" +curl -sL -o test/fixtures/sample.ttf "https://raw.githubusercontent.com/adobe-fonts/source-code-pro/release/TTF/SourceCodePro-Regular.ttf" +curl -sL -o test/fixtures/sample.dfont "https://raw.githubusercontent.com/fonttools/fonttools/main/Tests/ttx/data/TestDFONT.dfont" +``` + +Verify each downloaded correctly (should print recognizable font file descriptions, not HTML/error pages): + +```bash +file test/fixtures/sample.otf test/fixtures/sample.ttf test/fixtures/sample.dfont +``` + +Expected: `sample.otf: OpenType font data`, `sample.ttf: TrueType Font data...`, `sample.dfont: Mac OSX datafork font, TrueType...`. + +- [ ] **Step 3: Write the attribution file** + +Create `test/fixtures/FONT_ATTRIBUTION.md`: + +```markdown +# Font fixture attribution + +`sample.otf` and `sample.ttf` are the Regular weight of +[Source Code Pro](https://github.com/adobe-fonts/source-code-pro) by Adobe, +licensed under the SIL Open Font License 1.1 (see that repo's +`LICENSE.md`). Both are the same font family deliberately, so tests can +assert glyph-count fidelity (1568 glyphs) across otf/ttf/woff conversions +of "the same font" rather than comparing unrelated files. + +`sample.dfont` is `Tests/ttx/data/TestDFONT.dfont` from +[fonttools/fonttools](https://github.com/fonttools/fonttools), MIT +licensed. It is a small (3.5KB) fixture containing one real embedded +`sfnt` TrueType resource (7 glyphs) — used to exercise this project's +dfont-container extraction code without needing a large real-world +font suitcase. +``` + +- [ ] **Step 4: Write the fixture smoke test** + +Create `test/converters/font.test.js`: + +```js +import { describe, it, expect } from 'vitest'; +import fs from 'node:fs/promises'; +import path from 'node:path'; +import opentype from 'opentype.js'; +import * as fontkit from 'fontkit'; + +async function parseWithOpentype(fixtureName) { + const buf = await fs.readFile(path.join(import.meta.dirname, '..', 'fixtures', fixtureName)); + const ab = buf.buffer.slice(buf.byteOffset, buf.byteOffset + buf.byteLength); + return opentype.parse(ab); +} + +describe('font fixtures', () => { + it('sample.otf parses as a CFF-flavored OpenType font', async () => { + const font = await parseWithOpentype('sample.otf'); + expect(font.outlinesFormat).toBe('cff'); + expect(font.glyphs.length).toBe(1568); + }); + + it('sample.ttf parses as a TrueType font with the same glyph count as sample.otf', async () => { + const font = await parseWithOpentype('sample.ttf'); + expect(font.outlinesFormat).toBe('truetype'); + expect(font.glyphs.length).toBe(1568); + }); + + it('sample.dfont is a valid dfont container with one embedded sfnt font', async () => { + const buffer = await fs.readFile(path.join(import.meta.dirname, '..', 'fixtures', 'sample.dfont')); + const dfont = fontkit.create(buffer); + const sfntType = dfont.header.map.typeList.types.find((t) => t.name === 'sfnt'); + expect(sfntType.refList).toHaveLength(1); + }); +}); +``` + +- [ ] **Step 5: Run the test to verify it passes** + +Run: `DB_HOST=127.0.0.1 DB_USER=convert_user DB_PASSWORD=change_me DB_NAME=file_converter STORAGE_DIR=./storage PORT=3000 npx vitest run test/converters/font.test.js` +Expected: PASS (3 tests) — this confirms the dependencies installed correctly and the fixtures are what they're claimed to be, before any project code is written against them. + +- [ ] **Step 6: Commit** + +```bash +git add package.json package-lock.json test/fixtures/sample.otf test/fixtures/sample.ttf test/fixtures/sample.dfont test/fixtures/FONT_ATTRIBUTION.md test/converters/font.test.js +git commit -m "feat: add font conversion dependencies and test fixtures" +``` + +--- + +### Task 2: `ttf`/`otf`/`woff` bidirectional converter (`src/converters/font.js`) + +**Files:** +- Create: `src/converters/font.js` +- Modify: `test/converters/font.test.js` (extend from Task 1) + +**Interfaces:** +- Consumes: `register` from `src/converters/registry.js` (`register({ family, sourceFormat, targetFormat, convert })`, already existing). +- Produces: `registerFontConverter()` — registers every non-identity pair among `ttf`/`otf`/`woff` with `family: 'font'`. `convertBufferToOtf(buffer, outputPath)` — exported so `dfont.js` (Task 3) can reuse the otf-writing logic instead of duplicating it. + +- [ ] **Step 1: Write the failing tests** + +Update the import block at the top of `test/converters/font.test.js` to match this (adds `os`, `registerFontConverter`, `resolve`/`listTargetFormats`, `detectInputMime`, and `beforeAll`/`afterAll`): + +```js +import { describe, it, expect, beforeAll, afterAll } from 'vitest'; +import fs from 'node:fs/promises'; +import path from 'node:path'; +import os from 'node:os'; +import opentype from 'opentype.js'; +import * as fontkit from 'fontkit'; +import { registerFontConverter } from '../../src/converters/font.js'; +import { resolve, listTargetFormats } from '../../src/converters/registry.js'; +import { detectInputMime } from '../../src/mime.js'; +``` + +Keep the existing `describe('font fixtures', ...)` block and its `parseWithOpentype` helper from Task 1 unchanged. Append the following to the end of the file: + +```js +let tmpDir; + +beforeAll(async () => { + registerFontConverter(); + tmpDir = await fs.mkdtemp(path.join(os.tmpdir(), 'converter-font-')); +}); + +afterAll(async () => { + await fs.rm(tmpDir, { recursive: true, force: true }); +}); + +async function glyphCountOf(filePath) { + const buf = await fs.readFile(filePath); + const ab = buf.buffer.slice(buf.byteOffset, buf.byteOffset + buf.byteLength); + return opentype.parse(ab).glyphs.length; +} + +describe('font converter registration', () => { + it('registers ttf, otf, and woff as sources and targets of each other', () => { + expect(listTargetFormats('ttf')).toEqual(expect.arrayContaining(['otf', 'woff'])); + expect(listTargetFormats('otf')).toEqual(expect.arrayContaining(['ttf', 'woff'])); + expect(listTargetFormats('woff')).toEqual(expect.arrayContaining(['ttf', 'otf'])); + }); + + it('does not register a format as its own target', () => { + expect(listTargetFormats('ttf')).not.toContain('ttf'); + }); + + it('has no registered converter for cff or cid in either direction', () => { + expect(listTargetFormats('cff')).toEqual([]); + expect(listTargetFormats('cid')).toEqual([]); + expect(resolve('cff', 'ttf')).toBeNull(); + expect(resolve('ttf', 'cff')).toBeNull(); + expect(resolve('cid', 'ttf')).toBeNull(); + }); +}); + +describe('font format conversion', () => { + it('converts otf to ttf, preserving glyph count', async () => { + const inputPath = path.join(import.meta.dirname, '..', 'fixtures', 'sample.otf'); + const outputPath = path.join(tmpDir, 'from-otf.ttf'); + + await resolve('otf', 'ttf').convert(inputPath, outputPath); + + const detected = await detectInputMime(outputPath); + expect(detected.mime).toBe('font/ttf'); + expect(await glyphCountOf(outputPath)).toBe(1568); + }); + + it('converts ttf to woff', async () => { + const inputPath = path.join(import.meta.dirname, '..', 'fixtures', 'sample.ttf'); + const outputPath = path.join(tmpDir, 'from-ttf.woff'); + + await resolve('ttf', 'woff').convert(inputPath, outputPath); + + const detected = await detectInputMime(outputPath); + expect(detected.mime).toBe('font/woff'); + }); + + it('round-trips ttf -> woff -> ttf, preserving glyph count', async () => { + const woffPath = path.join(tmpDir, 'roundtrip.woff'); + const ttfPath = path.join(tmpDir, 'roundtrip.ttf'); + + await resolve('ttf', 'woff').convert(path.join(import.meta.dirname, '..', 'fixtures', 'sample.ttf'), woffPath); + await resolve('woff', 'ttf').convert(woffPath, ttfPath); + + expect(await glyphCountOf(ttfPath)).toBe(1568); + }); + + it('converts ttf to otf', async () => { + const inputPath = path.join(import.meta.dirname, '..', 'fixtures', 'sample.ttf'); + const outputPath = path.join(tmpDir, 'from-ttf.otf'); + + await resolve('ttf', 'otf').convert(inputPath, outputPath); + + const detected = await detectInputMime(outputPath); + expect(detected.mime).toBe('font/otf'); + }); +}); +``` + +- [ ] **Step 2: Run the tests to verify they fail** + +Run: `DB_HOST=127.0.0.1 DB_USER=convert_user DB_PASSWORD=change_me DB_NAME=file_converter STORAGE_DIR=./storage PORT=3000 npx vitest run test/converters/font.test.js` +Expected: FAIL — `Cannot find module '../../src/converters/font.js'`. + +- [ ] **Step 3: Implement `src/converters/font.js`** + +```js +import fs from 'node:fs/promises'; +import { Font } from 'fonteditor-core'; +import opentype from 'opentype.js'; +import { register } from './registry.js'; + +const FONT_FORMATS = ['ttf', 'otf', 'woff']; + +export async function convertBufferToOtf(buffer, outputPath) { + const ab = buffer.buffer.slice(buffer.byteOffset, buffer.byteOffset + buffer.byteLength); + const font = opentype.parse(ab); + await fs.writeFile(outputPath, Buffer.from(font.toArrayBuffer())); +} + +async function convertViaFontEditor(inputPath, outputPath, sourceFormat, targetFormat) { + const buffer = await fs.readFile(inputPath); + const font = Font.create(buffer, { type: sourceFormat }); + const out = font.write({ type: targetFormat }); + await fs.writeFile(outputPath, Buffer.from(out)); +} + +export function registerFontConverter() { + for (const sourceFormat of FONT_FORMATS) { + for (const targetFormat of FONT_FORMATS) { + if (sourceFormat === targetFormat) continue; + register({ + family: 'font', + sourceFormat, + targetFormat, + convert: async (inputPath, outputPath) => { + if (targetFormat === 'otf') { + await convertBufferToOtf(await fs.readFile(inputPath), outputPath); + } else { + await convertViaFontEditor(inputPath, outputPath, sourceFormat, targetFormat); + } + }, + }); + } + } +} +``` + +- [ ] **Step 4: Run the tests to verify they pass** + +Run: `DB_HOST=127.0.0.1 DB_USER=convert_user DB_PASSWORD=change_me DB_NAME=file_converter STORAGE_DIR=./storage PORT=3000 npx vitest run test/converters/font.test.js` +Expected: PASS (all tests in the file). + +- [ ] **Step 5: Commit** + +```bash +git add src/converters/font.js test/converters/font.test.js +git commit -m "feat: add bidirectional ttf/otf/woff font converter" +``` + +--- + +### Task 3: `dfont` source-only converter (`src/converters/dfont.js`) + +**Files:** +- Create: `src/converters/dfont.js` +- Create: `test/converters/dfont.test.js` (separate file from `font.test.js` since it has its own `beforeAll`/`tmpDir` setup) + +**Interfaces:** +- Consumes: `convertBufferToOtf` from `src/converters/font.js` (Task 2). `register` from `src/converters/registry.js`. +- Produces: `probeDfont(buffer)` — returns `true`/`false`, used by `src/mime.js` (Task 4). `extractSfntBuffer(buffer)` — returns a `Buffer` containing a byte-exact standalone sfnt font. `registerDfontConverter()` — registers `dfont -> ttf/otf/woff`. + +- [ ] **Step 1: Write the failing tests** + +Create `test/converters/dfont.test.js`: + +```js +import { describe, it, expect, beforeAll, afterAll } from 'vitest'; +import fs from 'node:fs/promises'; +import path from 'node:path'; +import os from 'node:os'; +import opentype from 'opentype.js'; +import { probeDfont, extractSfntBuffer, registerDfontConverter } from '../../src/converters/dfont.js'; +import { resolve, listTargetFormats } from '../../src/converters/registry.js'; +import { detectInputMime } from '../../src/mime.js'; + +let tmpDir; + +beforeAll(async () => { + registerDfontConverter(); + tmpDir = await fs.mkdtemp(path.join(os.tmpdir(), 'converter-dfont-')); +}); + +afterAll(async () => { + await fs.rm(tmpDir, { recursive: true, force: true }); +}); + +describe('probeDfont', () => { + it('returns true for a real dfont fixture', async () => { + const buffer = await fs.readFile(path.join(import.meta.dirname, '..', 'fixtures', 'sample.dfont')); + expect(probeDfont(buffer)).toBe(true); + }); + + it('returns false for content starting with the ICO-colliding magic bytes but no real dfont structure', () => { + const buffer = Buffer.from([0x00, 0x00, 0x01, 0x00, 0x01, 0x00, 0x10, 0x10]); + expect(probeDfont(buffer)).toBe(false); + }); +}); + +describe('extractSfntBuffer', () => { + it('extracts a valid, byte-exact standalone sfnt font from the dfont fixture', async () => { + const buffer = await fs.readFile(path.join(import.meta.dirname, '..', 'fixtures', 'sample.dfont')); + const sfnt = extractSfntBuffer(buffer); + + const ab = sfnt.buffer.slice(sfnt.byteOffset, sfnt.byteOffset + sfnt.byteLength); + const font = opentype.parse(ab); + expect(font.outlinesFormat).toBe('truetype'); + expect(font.glyphs.length).toBe(7); + }); +}); + +describe('dfont converter registration', () => { + it('registers dfont as a source for ttf, otf, and woff', () => { + expect(listTargetFormats('dfont')).toEqual(expect.arrayContaining(['ttf', 'otf', 'woff'])); + }); + + it('never registers dfont as a target format', () => { + expect(listTargetFormats('ttf')).not.toContain('dfont'); + expect(listTargetFormats('otf')).not.toContain('dfont'); + expect(listTargetFormats('woff')).not.toContain('dfont'); + }); +}); + +describe('dfont -> font conversion', () => { + it('converts the dfont fixture to ttf', async () => { + const inputPath = path.join(import.meta.dirname, '..', 'fixtures', 'sample.dfont'); + const outputPath = path.join(tmpDir, 'from-dfont.ttf'); + + await resolve('dfont', 'ttf').convert(inputPath, outputPath); + + const detected = await detectInputMime(outputPath); + expect(detected.mime).toBe('font/ttf'); + }); + + it('converts the dfont fixture to woff', async () => { + const inputPath = path.join(import.meta.dirname, '..', 'fixtures', 'sample.dfont'); + const outputPath = path.join(tmpDir, 'from-dfont.woff'); + + await resolve('dfont', 'woff').convert(inputPath, outputPath); + + const detected = await detectInputMime(outputPath); + expect(detected.mime).toBe('font/woff'); + }); + + it('converts the dfont fixture to otf', async () => { + const inputPath = path.join(import.meta.dirname, '..', 'fixtures', 'sample.dfont'); + const outputPath = path.join(tmpDir, 'from-dfont.otf'); + + await resolve('dfont', 'otf').convert(inputPath, outputPath); + + const detected = await detectInputMime(outputPath); + expect(detected.mime).toBe('font/otf'); + }); +}); +``` + +- [ ] **Step 2: Run the tests to verify they fail** + +Run: `DB_HOST=127.0.0.1 DB_USER=convert_user DB_PASSWORD=change_me DB_NAME=file_converter STORAGE_DIR=./storage PORT=3000 npx vitest run test/converters/dfont.test.js` +Expected: FAIL — `Cannot find module '../../src/converters/dfont.js'`. + +- [ ] **Step 3: Implement `src/converters/dfont.js`** + +```js +import fs from 'node:fs/promises'; +import * as fontkit from 'fontkit'; +import { Font } from 'fonteditor-core'; +import { register } from './registry.js'; +import { convertBufferToOtf } from './font.js'; + +export function probeDfont(buffer) { + try { + const dfont = fontkit.create(buffer); + const types = dfont.header?.map?.typeList?.types ?? []; + return types.some((t) => t.name === 'sfnt'); + } catch { + return false; + } +} + +export function extractSfntBuffer(buffer) { + const dfont = fontkit.create(buffer); + const sfntType = dfont.header.map.typeList.types.find((t) => t.name === 'sfnt'); + const ref = sfntType.refList[0]; + const lenPos = dfont.header.dataOffset + ref.dataOffset; + const len = buffer.readUInt32BE(lenPos); + const start = lenPos + 4; + return buffer.subarray(start, start + len); +} + +function sniffSfntType(buffer) { + return buffer.slice(0, 4).toString('ascii') === 'OTTO' ? 'otf' : 'ttf'; +} + +export function registerDfontConverter() { + for (const targetFormat of ['ttf', 'otf', 'woff']) { + register({ + family: 'font', + sourceFormat: 'dfont', + targetFormat, + convert: async (inputPath, outputPath) => { + const dfontBuffer = await fs.readFile(inputPath); + const sfntBuffer = extractSfntBuffer(dfontBuffer); + + if (targetFormat === 'otf') { + await convertBufferToOtf(sfntBuffer, outputPath); + } else { + const sourceFormat = sniffSfntType(sfntBuffer); + const font = Font.create(sfntBuffer, { type: sourceFormat }); + const out = font.write({ type: targetFormat }); + await fs.writeFile(outputPath, Buffer.from(out)); + } + }, + }); + } +} +``` + +- [ ] **Step 4: Run the tests to verify they pass** + +Run: `DB_HOST=127.0.0.1 DB_USER=convert_user DB_PASSWORD=change_me DB_NAME=file_converter STORAGE_DIR=./storage PORT=3000 npx vitest run test/converters/dfont.test.js` +Expected: PASS (all tests in the file). + +- [ ] **Step 5: Commit** + +```bash +git add src/converters/dfont.js test/converters/dfont.test.js +git commit -m "feat: add source-only dfont font converter" +``` + +--- + +### Task 4: `mime.js` — font output MIME types and the dfont/ico detection collision fix + +**Files:** +- Modify: `src/mime.js` +- Test: `test/mime.test.js` + +**Interfaces:** +- Consumes: `probeDfont` from `src/converters/dfont.js` (Task 3). +- Produces: `outputMimeType('ttf'/'otf'/'woff')` returns `'font/ttf'`/`'font/otf'`/`'font/woff'`. `resolveInputFormat(path, 'dfont')` correctly validates real dfont content even though `file-type` misreports it as `ico`, returning `{ mime: 'application/x-dfont', valid: true }` for real dfonts and `{ mime: null, valid: false }` otherwise. + +- [ ] **Step 1: Write the failing tests** + +Add to `test/mime.test.js`: + +```js +describe('outputMimeType — fonts', () => { + it('returns the correct MIME type for each font target format', () => { + expect(outputMimeType('ttf')).toBe('font/ttf'); + expect(outputMimeType('otf')).toBe('font/otf'); + expect(outputMimeType('woff')).toBe('font/woff'); + }); +}); + +describe('resolveInputFormat — dfont', () => { + it('confirms file-type alone misidentifies the dfont fixture as ico (documents the bug this fix works around)', async () => { + const fixturePath = path.join(import.meta.dirname, 'fixtures', 'sample.dfont'); + const detected = await detectInputMime(fixturePath); + expect(detected.ext).toBe('ico'); + }); + + it('accepts a real dfont file despite that misidentification', async () => { + const fixturePath = path.join(import.meta.dirname, 'fixtures', 'sample.dfont'); + const result = await resolveInputFormat(fixturePath, 'dfont'); + expect(result).toEqual({ mime: 'application/x-dfont', valid: true }); + }); + + it('rejects content starting with the colliding magic bytes that is not a real dfont', async () => { + const fixturePath = path.join(import.meta.dirname, 'fixtures', 'sample-fake.dfont'); + await fs.writeFile(fixturePath, Buffer.from([0x00, 0x00, 0x01, 0x00, 0x01, 0x00, 0x10, 0x10])); + + const result = await resolveInputFormat(fixturePath, 'dfont'); + expect(result).toEqual({ mime: null, valid: false }); + + await fs.unlink(fixturePath); + }); +}); +``` + +- [ ] **Step 2: Run the tests to verify they fail** + +Run: `DB_HOST=127.0.0.1 DB_USER=convert_user DB_PASSWORD=change_me DB_NAME=file_converter STORAGE_DIR=./storage PORT=3000 npx vitest run test/mime.test.js` +Expected: the `outputMimeType` font cases throw `No known MIME type for target format "ttf"` (etc); the "misidentifies... as ico" case passes already (it's asserting current, pre-fix behavior); the "accepts a real dfont file" case fails because `resolveInputFormat` currently reports `valid: false` for it. + +- [ ] **Step 3: Implement** + +In `src/mime.js`, add the import and the three font MIME entries: + +```js +import { fileTypeFromFile } from 'file-type'; +import fs from 'node:fs/promises'; +import { probeDfont } from './converters/dfont.js'; + +const OUTPUT_MIME_TYPES = { + jpg: 'image/jpeg', + jpeg: 'image/jpeg', + png: 'image/png', + webp: 'image/webp', + gif: 'image/gif', + tiff: 'image/tiff', + avif: 'image/avif', + bmp: 'image/bmp', + ico: 'image/x-icon', + pdf: 'application/pdf', + html: 'text/html', + txt: 'text/plain', + docx: 'application/vnd.openxmlformats-officedocument.wordprocessingml.document', + md: 'text/markdown', + csv: 'text/csv', + xlsx: 'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet', + ttf: 'font/ttf', + otf: 'font/otf', + woff: 'font/woff', +}; +``` + +Update `resolveInputFormat` to special-case `dfont` before the generic `file-type` path: + +```js +export async function resolveInputFormat(filePath, declaredFormat) { + if (declaredFormat === 'dfont') { + const buffer = await fs.readFile(filePath); + return probeDfont(buffer) + ? { mime: 'application/x-dfont', valid: true } + : { mime: null, valid: false }; + } + + const detected = await detectInputMime(filePath); + + if (!detected) { + const fallbackMime = UNDETECTABLE_TEXT_FORMATS[declaredFormat]; + if (fallbackMime) { + return { mime: fallbackMime, valid: true }; + } + return { mime: null, valid: false }; + } + + const valid = normalizeFormat(detected.ext) === normalizeFormat(declaredFormat); + return { mime: detected.mime, valid }; +} +``` + +- [ ] **Step 4: Run the tests to verify they pass** + +Run: `DB_HOST=127.0.0.1 DB_USER=convert_user DB_PASSWORD=change_me DB_NAME=file_converter STORAGE_DIR=./storage PORT=3000 npx vitest run test/mime.test.js` +Expected: PASS (all tests in the file). + +- [ ] **Step 5: Commit** + +```bash +git add src/mime.js test/mime.test.js +git commit -m "feat: add font MIME types and fix dfont/ico detection collision" +``` + +--- + +### Task 5: Wire converters into the app/worker and end-to-end API tests + +**Files:** +- Modify: `src/app.js` +- Modify: `src/worker.js` +- Test: `test/api/jobs.test.js` + +**Interfaces:** +- Consumes: `registerFontConverter` (Task 2), `registerDfontConverter` (Task 3). +- Produces: nothing new for later tasks — this is the last task in the plan. + +- [ ] **Step 1: Write the failing tests** + +Add to `test/api/jobs.test.js`: + +```js +describe('POST /api/jobs — fonts', () => { + it('creates a pending job converting an OTF upload to ttf', async () => { + const fixturePath = path.join(import.meta.dirname, '..', 'fixtures', 'sample.otf'); + + const response = await request(app) + .post('/api/jobs') + .field('targetFormats', JSON.stringify(['ttf'])) + .attach('files', fixturePath, 'font.otf'); + + expect(response.status).toBe(201); + expect(response.body.jobs[0].status).toBe('pending'); + + const job = await getJobByUuid(prisma, response.body.jobs[0].id); + expect(job.sourceFormat).toBe('otf'); + expect(job.targetFormat).toBe('ttf'); + expect(job.family).toBe('font'); + expect(job.inputMimeType).toBe('font/otf'); + }); + + it('creates a pending job converting a dfont upload despite file-type misidentifying its content as ico', async () => { + const fixturePath = path.join(import.meta.dirname, '..', 'fixtures', 'sample.dfont'); + + const response = await request(app) + .post('/api/jobs') + .field('targetFormats', JSON.stringify(['ttf'])) + .attach('files', fixturePath, 'font.dfont'); + + expect(response.status).toBe(201); + expect(response.body.jobs[0].status).toBe('pending'); + + const job = await getJobByUuid(prisma, response.body.jobs[0].id); + expect(job.sourceFormat).toBe('dfont'); + expect(job.inputMimeType).toBe('application/x-dfont'); + }); + + it('lists ttf/otf/woff as targets for each other via GET /api/formats, and never lists dfont as a target', async () => { + const ttfTargets = await request(app).get('/api/formats').query({ source: 'ttf' }); + expect(ttfTargets.body.targets).toEqual(expect.arrayContaining(['otf', 'woff'])); + + const otfTargets = await request(app).get('/api/formats').query({ source: 'otf' }); + expect(otfTargets.body.targets).not.toContain('dfont'); + }); +}); +``` + +- [ ] **Step 2: Run the tests to verify they fail** + +Run: `DB_HOST=127.0.0.1 DB_USER=convert_user DB_PASSWORD=change_me DB_NAME=file_converter STORAGE_DIR=./storage PORT=3000 npx vitest run test/api/jobs.test.js` +Expected: FAIL — both new POST cases get `response.body.jobs[0].error` matching `/Unsupported conversion/` instead of a pending job, since `registerFontConverter`/`registerDfontConverter` are never called by `src/app.js`. + +- [ ] **Step 3: Wire the converters into `src/app.js`** + +Add the imports alongside the existing converter imports: + +```js +import { registerFontConverter } from './converters/font.js'; +import { registerDfontConverter } from './converters/dfont.js'; +``` + +Add both calls inside `registerAllConverters()`: + +```js +function registerAllConverters() { + if (convertersRegistered) return; + registerImageConverters(); + registerImageToPdfConverter(); + registerDocumentConverters(); + registerIcoConverter(); + registerHeicConverter(); + registerFontConverter(); + registerDfontConverter(); + convertersRegistered = true; +} +``` + +- [ ] **Step 4: Wire the converters into `src/worker.js`** + +Add the same imports, and add both calls inside `main()`: + +```js +import { registerFontConverter } from './converters/font.js'; +import { registerDfontConverter } from './converters/dfont.js'; +``` + +```js + registerImageConverters(); + registerImageToPdfConverter(); + registerDocumentConverters(); + registerIcoConverter(); + registerHeicConverter(); + registerFontConverter(); + registerDfontConverter(); +``` + +- [ ] **Step 5: Run the tests to verify they pass** + +Run: `DB_HOST=127.0.0.1 DB_USER=convert_user DB_PASSWORD=change_me DB_NAME=file_converter STORAGE_DIR=./storage PORT=3000 npx vitest run test/api/jobs.test.js` +Expected: PASS (all tests in the file). + +- [ ] **Step 6: Run the full test suite** + +Run: `DB_HOST=127.0.0.1 DB_USER=convert_user DB_PASSWORD=change_me DB_NAME=file_converter STORAGE_DIR=./storage PORT=3000 npx vitest run` +Expected: PASS, except the two pre-existing unrelated failures documented in `CLAUDE.md` (`test/cleanup.test.js` and `test/jobs/jobRepository.test.js` expired-job clock/timezone issue) — verify against `main` first if any other failure appears. + +- [ ] **Step 7: Commit** + +```bash +git add src/app.js src/worker.js test/api/jobs.test.js +git commit -m "feat: register font/dfont converters in the app and worker" +``` + +--- + +## Not in this plan + +- Frontend changes: none needed. `frontend/src/App.jsx`'s target-format dropdown and per-format controls (`QUALITY_FORMATS`, `'ico'`, `'png'`, `'pdf'` checks) are all driven by `GET /api/formats`, which reflects the registry — font formats work automatically once Task 5 is done. Do a manual browser check (upload a `.otf`/`.ttf`/`.woff`/`.dfont` file, confirm the target dropdown and conversion work) since there is no frontend test framework, consistent with how `quality`/`iconSize` were verified. +- Database changes: none. `family` is a free-text `VARCHAR(32)` column (no enum), and fonts have no quality/size-style knob.