CLI — @uurtech/jdf-cli

Command-line tool for validating .jdf / .jdfx documents against the JSON Schema and converting source formats into JDF. Designed to be safe to drop into CI.

Install

# run on demand (no install)
npx @uurtech/jdf-cli validate doc.jdf

# or install globally
npm install -g @uurtech/jdf-cli
jdf --help

Commands

jdf validate <file.jdf|file.jdfx>

Runs Ajv against spec/jdf-schema.json and reports path-level errors with warnings vs hard failures separated. For .jdfx bundles the validator opens the zip, validates document.json, and prints the asset count from the manifest.

$ jdf validate spec/examples/hello-world.jdf

✓ Valid: hello-world.jdf
  Format:    1.0.0
  Title:     Hello, JDF
  Pages:     2
  Elements:  14

Failures look like:

$ jdf validate broken.jdf

✗ Invalid: broken.jdf
  /pages/0/elements/3/heading — must be one of [true, 1, 2, 3, 4, 5, 6]
  /pages/0/elements/5 — required property "type" missing

Exit code: 0 if valid, 1 if not. Drop into a CI step:

# .github/workflows/ci.yml
- run: npx @uurtech/jdf-cli validate docs/whitepaper.jdf

jdf import <file.{md,pdf}> [-o output.{jdf,jdfx}]

Convert a Markdown or PDF file to a JDF document:

jdf import README.md                       # text-only → README.jdf
jdf import notes.md                        # with images → notes.jdfx (auto)
jdf import notes.md -o notes.jdfx          # force the bundle form
jdf import paper.pdf -o paper.jdf          # PDF (planned, see below)

Markdown import uses marked-style parsing with full GFM (tables, blockquotes, fenced code, links, images, task lists, hr, strikethrough). Bold/italic emit as richtext runs. Image references like ![alt](komojam_target_architecture.drawio.png) resolve against the source file's directory and are read from disk during import.

Auto file-shape selection. When you don't pass -o, the importer picks the right output:

• Document has no embedded assets → writes file.jdf (plain JSON).
• Document has at least one embedded image / font → writes file.jdfx (zip bundle: document.json + manifest.json + assets/).

If you specify -o foo.jdf explicitly on a document with assets, the assets stay base64-inline in resources.images. The schema is identical either way.

PDF import is currently a placeholder — it prints a hint to use the desktop Reader. The plan is to extract apps/reader/src/import/pdfToJdf.ts into a shared @uurtech/jdf-pdf-import package with a Node entry point so the CLI can run the same PDF.js-based extractor (positions, fonts, colors, vector shapes, embedded images).

Schema validation in CI

If your project generates .jdf files programmatically, validate them on every PR. Example workflow:

name: Validate JDF docs

on: [pull_request]

jobs:
  validate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 20
      - run: npx @uurtech/jdf-cli validate docs/*.jdf