pdf-fill 0.6.0

package/README.md

@@ -0,0 +1,13 @@
+# pdffill
+
+CLI for listing, diagnosing, diffing, and filling PDF AcroForms.
+
+```bash
+npm install -g pdffill
+pdffill doctor template.pdf
+pdffill run template.pdf data.json -o filled.pdf
+```
+
+Requires Node.js 18+. Library: [`@lzlz94/pdffill-core`](https://www.npmjs.com/package/@lzlz94/pdffill-core).
+
+Documentation: [README](https://github.com/lz1834career/pdf-fill/blob/main/README.md).

package/dist/index.js

@@ -0,0 +1,899 @@
+#!/usr/bin/env node
+
+// src/index.ts
+import { Command } from "commander";
+
+// src/commands/list.ts
+import { listFields } from "@lzlz94/pdffill-core";
+
+// src/util/read-file.ts
+import { readFile } from "fs/promises";
+async function readBinary(path) {
+  const buf = await readFile(path);
+  return new Uint8Array(buf.buffer, buf.byteOffset, buf.byteLength);
+}
+async function readJson(path) {
+  const text = await readFile(path, "utf8");
+  return JSON.parse(text);
+}
+async function readJsonSchema(path) {
+  return await readJson(path);
+}
+
+// src/commands/list.ts
+function printTable(fields) {
+  if (fields.length === 0) {
+    console.log("No AcroForm fields found.");
+    return;
+  }
+  for (const f of fields) {
+    const opts = f.options?.length ? ` options=[${f.options.join(", ")}]` : "";
+    const ro = f.readOnly ? " readonly" : "";
+    console.log(`${f.name}	${f.type}${ro}${opts}`);
+  }
+}
+function registerListCommand(program2) {
+  program2.command("list").description("List AcroForm fields in a PDF").argument("<pdf>", "Path to PDF template").option("--json", "Output as JSON array").action(async (pdfPath, opts) => {
+    const bytes = await readBinary(pdfPath);
+    const fields = await listFields(bytes);
+    if (opts.json) {
+      console.log(JSON.stringify(fields, null, 2));
+    } else {
+      printTable(fields);
+    }
+  });
+}
+
+// src/commands/doctor.ts
+import { doctor } from "@lzlz94/pdffill-core";
+function registerDoctorCommand(program2) {
+  program2.command("doctor").description("Diagnose whether a PDF can be filled with pdffill").argument("<pdf>", "Path to PDF template").option("--json", "Output report as JSON").action(async (pdfPath, opts) => {
+    const bytes = await readBinary(pdfPath);
+    const report = await doctor(bytes);
+    if (opts.json) {
+      console.log(JSON.stringify(report, null, 2));
+    } else {
+      console.log(report.ok ? "OK" : "NOT OK");
+      console.log(`encrypted: ${report.encrypted}`);
+      console.log(`hasXFA: ${report.hasXFA}`);
+      console.log(`fieldCount: ${report.fieldCount}`);
+      for (const issue of report.issues) {
+        console.log(`[${issue.level}] ${issue.code}: ${issue.message}`);
+      }
+    }
+    if (!report.ok) process.exitCode = 1;
+  });
+}
+
+// src/commands/fill.ts
+import { writeFile as writeFile2 } from "fs/promises";
+import {
+  fillForm,
+  doctor as doctor2,
+  assertDoctorReady,
+  buildFillReport,
+  SchemaValidationError,
+  PdfFillError as PdfFillError2,
+  parseFillDataInput as parseFillDataInput2,
+  parseMappingFile as parseMappingFile2,
+  applyFieldMapping as applyFieldMapping2
+} from "@lzlz94/pdffill-core";
+
+// src/util/config.ts
+import {
+  mergePdffillConfig,
+  parsePdffillConfig
+} from "@lzlz94/pdffill-core";
+async function loadPdffillConfig(path) {
+  if (!path) return void 0;
+  const raw = await readJson(path);
+  return parsePdffillConfig(raw);
+}
+function mergeConfig(config, cli) {
+  if (!config) return cli;
+  return mergePdffillConfig(config, cli);
+}
+function resolveIgnoreFields(config, cliList) {
+  if (cliList) {
+    return cliList.split(",").map((s) => s.trim()).filter(Boolean);
+  }
+  return config?.ignoreFields ?? [];
+}
+function resolveMappingPath(config, cliPath) {
+  return cliPath ?? config?.mapping;
+}
+
+// src/util/print-diff.ts
+function printFieldDiff(result) {
+  console.log(
+    `Fields: ${result.pdfFieldCount} in PDF, ${result.dataKeyCount} in data \u2014 ${result.ok ? "OK" : "issues found"}`
+  );
+  if (result.missingInData.length) {
+    console.log(`Missing in data (${result.missingInData.length}):`);
+    for (const f of result.missingInData) console.log(`  - ${f}`);
+  }
+  if (result.unknownInData.length) {
+    console.log(`Unknown in data (${result.unknownInData.length}):`);
+    for (const f of result.unknownInData) console.log(`  - ${f}`);
+  }
+  if (result.missingInBusinessData?.length) {
+    console.log(`Missing in business JSON (${result.missingInBusinessData.length}):`);
+    for (const g of result.missingInBusinessData) {
+      console.log(`  - ${g.sourcePath} \u2192 ${g.pdfField}`);
+    }
+  }
+  if (result.unmappedPdfFields?.length) {
+    console.log(`Unmapped PDF fields (${result.unmappedPdfFields.length}):`);
+    for (const f of result.unmappedPdfFields) console.log(`  - ${f}`);
+  }
+  if (result.typeMismatches?.length) {
+    console.log(`Type mismatches (${result.typeMismatches.length}):`);
+    for (const m of result.typeMismatches) {
+      console.log(`  - ${m.field}: ${m.message}`);
+    }
+  }
+  if (result.unchangedFromTemplate?.length) {
+    console.log(
+      `Unchanged from template (${result.unchangedFromTemplate.length}):`
+    );
+    for (const u of result.unchangedFromTemplate) {
+      console.log(`  - ${u.field}`);
+    }
+  }
+}
+
+// src/util/resolve-data-diff.ts
+import {
+  applyFieldMapping,
+  diffFields,
+  diffFieldsWithMapping,
+  listFields as listFields2,
+  parseFillDataInput,
+  parseMappingFile,
+  PdfFillError
+} from "@lzlz94/pdffill-core";
+async function resolveDataAndDiff(opts) {
+  const diffOpts = {
+    ignoreFields: opts.ignoreFields ?? [],
+    includeReadOnly: opts.includeReadOnly ?? false,
+    compareTemplate: opts.compareTemplate ?? false
+  };
+  if (opts.mappingPath) {
+    const mapping = parseMappingFile(await readJson(opts.mappingPath));
+    if (typeof opts.raw !== "object" || opts.raw === null || Array.isArray(opts.raw)) {
+      throw new PdfFillError(
+        "With --mapping, data must be a JSON object",
+        "INVALID_FILL_DATA_SHAPE"
+      );
+    }
+    const business = opts.raw;
+    const fields = await listFields2(opts.template);
+    const diff2 = diffFieldsWithMapping(fields, business, mapping, diffOpts);
+    const data2 = applyFieldMapping(business, mapping);
+    return { data: data2, diff: diff2 };
+  }
+  const data = parseFillDataInput(opts.raw);
+  const diff = await diffFields(opts.template, data, diffOpts);
+  return { data, diff };
+}
+function assertDiffOk(diff) {
+  if (diff.ok) return;
+  const parts = [];
+  if (diff.missingInData.length) {
+    parts.push(`${diff.missingInData.length} missing in data`);
+  }
+  if (diff.unknownInData.length) {
+    parts.push(`${diff.unknownInData.length} unknown in data`);
+  }
+  if (diff.typeMismatches?.length) {
+    parts.push(`${diff.typeMismatches.length} type mismatch(es)`);
+  }
+  if (diff.missingInBusinessData?.length) {
+    parts.push(`${diff.missingInBusinessData.length} missing in business data`);
+  }
+  if (diff.unmappedPdfFields?.length) {
+    parts.push(`${diff.unmappedPdfFields.length} unmapped PDF field(s)`);
+  }
+  throw new PdfFillError(
+    `Field diff failed: ${parts.join(", ")}`,
+    "DIFF_FAILED"
+  );
+}
+
+// src/util/resolve-fill-cli.ts
+import {
+  parseFailOnWarningsSpec
+} from "@lzlz94/pdffill-core";
+function resolveFillCli(opts, fileConfig) {
+  const missingRaw = opts.missing ?? fileConfig?.missing ?? "skip";
+  return {
+    mappingPath: resolveMappingPath(fileConfig, opts.mapping),
+    ignoreFields: resolveIgnoreFields(fileConfig, opts.ignoreFields),
+    flatten: opts.flatten ?? fileConfig?.flatten ?? false,
+    strict: opts.strict ?? fileConfig?.strict ?? false,
+    missing: missingRaw === "error" ? "error" : "skip",
+    updateAppearances: opts.updateAppearances === false ? false : fileConfig?.updateAppearances === false ? false : true,
+    fontPath: opts.font ?? fileConfig?.fontPath,
+    requireDoctor: opts.requireDoctor ?? fileConfig?.requireDoctor ?? false,
+    skipDoctor: opts.skipDoctor ?? false,
+    failOnWarnings: parseFailOnWarningsSpec(opts.failOnWarnings) ?? fileConfig?.failOnWarnings
+  };
+}
+
+// src/util/write-report.ts
+import { writeFile } from "fs/promises";
+import {
+  serializeBatchManifest
+} from "@lzlz94/pdffill-core";
+async function writeJsonReport(path, data) {
+  await writeFile(path, `${JSON.stringify(data, null, 2)}
+`, "utf8");
+  console.log(`Wrote report ${path}`);
+}
+async function writeBatchManifest(path, entries, format = "json") {
+  await writeFile(path, serializeBatchManifest(entries, format), "utf8");
+  console.log(`Wrote manifest ${path} (${format})`);
+}
+
+// src/commands/fill.ts
+function registerFillCommand(program2) {
+  program2.command("fill").description("Fill PDF form fields from JSON (editable by default)").argument("<pdf>", "Path to PDF template").argument("<data.json>", "JSON object: field name \u2192 value").requiredOption("-o, --output <path>", "Output PDF path").option("--flatten", "Flatten form (read-only output)").option("--strict", "Fail on unknown fields in JSON").option("--schema <path>", "JSON Schema file to validate data").option(
+    "--missing <mode>",
+    "When template field missing in JSON: skip or error",
+    "skip"
+  ).option(
+    "--no-update-appearances",
+    "Skip appearance regeneration (Unicode may use NeedAppearances only)"
+  ).option(
+    "--font <path>",
+    "Font file (.ttf/.otf/.ttc) for Chinese/Unicode field appearances"
+  ).option(
+    "--mapping <path>",
+    "Map business JSON paths to PDF field names (see mapping.json)"
+  ).option(
+    "--ignore-fields <names>",
+    "Comma-separated PDF field names to skip MISSING_FIELD warnings"
+  ).option("--require-doctor", "Run doctor before fill").option("--report <path>", "Write operation report JSON").option("--config <path>", "pdffill.json (ignoreFields, fontPath, mapping, \u2026)").option("--diff", "Run field diff before fill; fail on mismatch").option(
+    "--compare-template",
+    "With --diff: flag values unchanged from template"
+  ).option(
+    "--fail-on-warnings <codes>",
+    "Fail if warnings match codes (comma-separated, or * for any)"
+  ).action(
+    async (pdfPath, dataPath, opts) => {
+      const startedAt = /* @__PURE__ */ new Date();
+      let fieldDiff;
+      try {
+        const fileConfig = await loadPdffillConfig(opts.config);
+        const resolved = resolveFillCli(opts, fileConfig);
+        const template = await readBinary(pdfPath);
+        const raw = await readJson(dataPath);
+        let data;
+        if (opts.diff) {
+          const resolvedDiff = await resolveDataAndDiff({
+            template,
+            raw,
+            mappingPath: resolved.mappingPath,
+            ignoreFields: resolved.ignoreFields,
+            compareTemplate: opts.compareTemplate ?? false
+          });
+          fieldDiff = resolvedDiff.diff;
+          if (!fieldDiff.ok) printFieldDiff(fieldDiff);
+          assertDiffOk(fieldDiff);
+          data = resolvedDiff.data;
+        } else if (resolved.mappingPath) {
+          const map = parseMappingFile2(await readJson(resolved.mappingPath));
+          if (typeof raw !== "object" || raw === null || Array.isArray(raw)) {
+            throw new PdfFillError2(
+              "With --mapping, data file must be a JSON object (business fields)",
+              "INVALID_FILL_DATA_SHAPE"
+            );
+          }
+          data = applyFieldMapping2(
+            raw,
+            map
+          );
+        } else {
+          data = parseFillDataInput2(raw);
+        }
+        const schema = opts.schema ? await readJsonSchema(opts.schema) : void 0;
+        const doctorReport = resolved.requireDoctor || opts.report ? resolved.requireDoctor ? await assertDoctorReady(template) : await doctor2(template) : void 0;
+        const result = await fillForm(template, data, {
+          flatten: resolved.flatten,
+          strict: resolved.strict,
+          missing: resolved.missing,
+          updateAppearances: resolved.updateAppearances,
+          fontPath: resolved.fontPath,
+          schema,
+          ignoreFields: resolved.ignoreFields,
+          failOnWarnings: resolved.failOnWarnings
+        });
+        await writeFile2(opts.output, result.pdf);
+        for (const w of result.warnings) {
+          console.warn(`[${w.code}] ${w.message}`);
+        }
+        console.log(
+          `Wrote ${opts.output} (${result.fieldsFilled.length} field(s) filled)`
+        );
+        if (opts.report) {
+          await writeJsonReport(
+            opts.report,
+            buildFillReport({
+              ok: true,
+              startedAt,
+              durationMs: Date.now() - startedAt.getTime(),
+              template: pdfPath,
+              output: opts.output,
+              fill: result,
+              doctor: doctorReport,
+              diff: fieldDiff
+            })
+          );
+        }
+      } catch (err) {
+        if (opts.report) {
+          const error = err instanceof PdfFillError2 ? { code: err.code, message: err.message } : err instanceof SchemaValidationError ? { code: "SCHEMA_VALIDATION", message: err.message } : {
+            code: "UNKNOWN",
+            message: err instanceof Error ? err.message : String(err)
+          };
+          await writeJsonReport(
+            opts.report,
+            buildFillReport({
+              ok: false,
+              startedAt,
+              durationMs: Date.now() - startedAt.getTime(),
+              template: pdfPath,
+              output: opts.output,
+              fill: { pdf: new Uint8Array(0), fieldsFilled: [], warnings: [] },
+              diff: fieldDiff,
+              error
+            })
+          );
+        }
+        if (err instanceof SchemaValidationError) {
+          console.error(err.message, err.errors);
+          process.exitCode = 2;
+          return;
+        }
+        if (err instanceof PdfFillError2) {
+          console.error(`${err.code}: ${err.message}`);
+          process.exitCode = 1;
+          return;
+        }
+        throw err;
+      }
+    }
+  );
+}
+
+// src/commands/scaffold.ts
+import { writeFile as writeFile3 } from "fs/promises";
+import {
+  listFields as listFields3,
+  scaffoldAll,
+  scaffoldFromTemplate,
+  scaffoldJsonSchema
+} from "@lzlz94/pdffill-core";
+function registerScaffoldCommand(program2) {
+  program2.command("scaffold").description(
+    "Generate fill-ready data.json (and optional fields.json / schema.json) from a template"
+  ).argument("<pdf>", "Path to PDF template").option("-o, --output <path>", "PDF field names \u2192 values (fill direct)", "data.json").option(
+    "--fields-output <path>",
+    "Also write field metadata (same as list --json)"
+  ).option("--schema-output <path>", "Also write JSON Schema for fill data").option("--include-readonly", "Include read-only fields").option(
+    "--with-mapping",
+    "Also write business data + mapping.json for --mapping fill/batch"
+  ).option(
+    "--business-output <path>",
+    "Business JSON path (with --with-mapping)",
+    "data.business.json"
+  ).option(
+    "--mapping-output <path>",
+    "Mapping JSON path (with --with-mapping)",
+    "mapping.json"
+  ).option(
+    "--business-style <style>",
+    "nested (applicant.name \u2192 tree) or flat (applicant_name keys)",
+    "nested"
+  ).option(
+    "--prefill-from-template",
+    "Use non-empty values already in the PDF as defaults"
+  ).action(
+    async (pdfPath, opts) => {
+      const bytes = await readBinary(pdfPath);
+      const fields = await listFields3(bytes);
+      if (fields.length === 0) {
+        console.error("No AcroForm fields found. Run pdffill doctor first.");
+        process.exitCode = 1;
+        return;
+      }
+      const style = opts.businessStyle === "flat" ? "flat" : "nested";
+      const scaffoldOpts = {
+        includeReadOnly: opts.includeReadonly ?? false,
+        withMapping: opts.withMapping ?? false,
+        businessStyle: style,
+        prefillFromTemplate: opts.prefillFromTemplate ?? false
+      };
+      const bundle = opts.prefillFromTemplate ? await scaffoldFromTemplate(bytes, scaffoldOpts) : scaffoldAll(fields, scaffoldOpts);
+      await writeFile3(
+        opts.output,
+        `${JSON.stringify(bundle.pdfData, null, 2)}
+`,
+        "utf8"
+      );
+      console.log(
+        `Wrote ${opts.output} (${Object.keys(bundle.pdfData).length} PDF field(s))`
+      );
+      if (bundle.business) {
+        await writeFile3(
+          opts.businessOutput,
+          `${JSON.stringify(bundle.business.businessData, null, 2)}
+`,
+          "utf8"
+        );
+        const mappingPayload = { mapping: bundle.business.mapping };
+        await writeFile3(
+          opts.mappingOutput,
+          `${JSON.stringify(mappingPayload, null, 2)}
+`,
+          "utf8"
+        );
+        console.log(
+          `Wrote ${opts.businessOutput} + ${opts.mappingOutput} (${Object.keys(bundle.business.mapping).length} mapped field(s), ${style})`
+        );
+        console.log(
+          "Fill with: pdffill fill <pdf> " + opts.businessOutput + " -o out.pdf --mapping " + opts.mappingOutput
+        );
+      }
+      if (opts.fieldsOutput) {
+        await writeFile3(
+          opts.fieldsOutput,
+          `${JSON.stringify(fields, null, 2)}
+`,
+          "utf8"
+        );
+        console.log(`Wrote ${opts.fieldsOutput} (field metadata)`);
+      }
+      if (opts.schemaOutput) {
+        const schema = scaffoldJsonSchema(fields, {
+          includeReadOnly: opts.includeReadonly ?? false
+        });
+        await writeFile3(
+          opts.schemaOutput,
+          `${JSON.stringify(schema, null, 2)}
+`,
+          "utf8"
+        );
+        console.log(`Wrote ${opts.schemaOutput} (JSON Schema)`);
+      }
+    }
+  );
+}
+
+// src/commands/verify.ts
+import {
+  parseFillDataInput as parseFillDataInput3,
+  verifyFilledPdf,
+  PdfFillError as PdfFillError3
+} from "@lzlz94/pdffill-core";
+function registerVerifyCommand(program2) {
+  program2.command("verify").description("Verify filled PDF field values match expected data.json").argument("<pdf>", "Path to filled PDF").argument("<data.json>", "Expected field values (same shape as fill)").option("--json", "Output result as JSON").action(async (pdfPath, dataPath, opts) => {
+    try {
+      const pdf = await readBinary(pdfPath);
+      const raw = await readJson(dataPath);
+      const expected = parseFillDataInput3(raw);
+      const result = await verifyFilledPdf(pdf, expected);
+      if (opts.json) {
+        console.log(JSON.stringify(result, null, 2));
+      } else {
+        console.log(result.ok ? "OK" : "FAILED");
+        console.log(`checked: ${result.checked.length}`);
+        for (const m of result.mismatches) {
+          console.log(
+            `  mismatch ${m.field}: expected ${JSON.stringify(m.expected)}, got ${JSON.stringify(m.actual)}`
+          );
+        }
+        for (const name of result.missingInPdf) {
+          console.log(`  missing in PDF: ${name}`);
+        }
+      }
+      if (!result.ok) process.exitCode = 1;
+    } catch (err) {
+      if (err instanceof PdfFillError3) {
+        console.error(`${err.code}: ${err.message}`);
+        process.exitCode = 1;
+        return;
+      }
+      throw err;
+    }
+  });
+}
+
+// src/commands/batch.ts
+import { mkdir, readFile as readFile2, writeFile as writeFile4 } from "fs/promises";
+import { dirname, join } from "path";
+import {
+  batchFill,
+  diffFields as diffFields2,
+  verifyFilledPdf as verifyFilledPdf2,
+  PdfFillError as PdfFillError4,
+  SchemaValidationError as SchemaValidationError2,
+  parseRowsJson,
+  parseRowsCsv,
+  rowsToFillData,
+  csvRowsToFillData,
+  parseMappingFile as parseMappingFile3
+} from "@lzlz94/pdffill-core";
+
+// src/util/format-output.ts
+function formatOutputPath(pattern, ctx, index) {
+  let out = pattern.replace(/\{index\}/g, String(index));
+  for (const [key, value] of Object.entries(ctx)) {
+    if (value === void 0) continue;
+    out = out.replaceAll(`{${key}}`, String(value));
+  }
+  return out;
+}
+
+// src/commands/batch.ts
+function registerBatchCommand(program2) {
+  program2.command("batch").description("Fill one template with many data rows (JSON array or CSV)").argument("<pdf>", "PDF template path").argument("<rows>", "JSON array file or .csv file").requiredOption("-o, --output-dir <dir>", "Output directory").option("--pattern <tpl>", "Output filename pattern", "{index}.pdf").option("--mapping <path>", "Field mapping JSON (source path \u2192 PDF field)").option("--flatten", "Flatten each output PDF").option("--strict", "Fail on unknown fields").option("--schema <path>", "JSON Schema applied to each row").option("--missing <mode>", "skip or error", "skip").option("--no-update-appearances", "Skip appearance regeneration").option("--font <path>", "CJK/Unicode font path").option("--fail-fast", "Stop on first row error").option("--verify", "Verify each output PDF against its row data").option(
+    "--ignore-fields <names>",
+    "Comma-separated PDF field names to skip MISSING_FIELD warnings"
+  ).option("--manifest <path>", "Write batch manifest (per-row results)").option(
+    "--manifest-format <fmt>",
+    "Manifest format: json (array) or jsonl (one object per line)",
+    "json"
+  ).option("--config <path>", "pdffill.json config file").option("--diff", "Run field diff on each row before fill").option(
+    "--fail-on-warnings <codes>",
+    "Fail if warnings match codes (comma-separated, or * for any)"
+  ).action(
+    async (pdfPath, rowsPath, opts) => {
+      try {
+        const fileConfig = await loadPdffillConfig(opts.config);
+        const resolved = resolveFillCli(opts, fileConfig);
+        const template = await readBinary(pdfPath);
+        const isCsv = rowsPath.toLowerCase().endsWith(".csv");
+        const mapping = resolved.mappingPath ? parseMappingFile3(await readJson(resolved.mappingPath)) : void 0;
+        const schema = opts.schema ? await readJsonSchema(opts.schema) : void 0;
+        let fillRows;
+        let rawRowsForNames = [];
+        if (isCsv) {
+          const text = await readFile2(rowsPath, "utf8");
+          const csvRows = parseRowsCsv(text);
+          fillRows = csvRowsToFillData(csvRows, mapping);
+          rawRowsForNames = csvRows.map((r) => ({ ...r }));
+        } else {
+          const raw = await readJson(rowsPath);
+          const jsonRows = parseRowsJson(raw);
+          fillRows = rowsToFillData(jsonRows, mapping);
+          rawRowsForNames = jsonRows.map((r) => {
+            const flat = {};
+            for (const [k, v] of Object.entries(r)) {
+              if (typeof v === "string" || typeof v === "number" || typeof v === "boolean") {
+                flat[k] = v;
+              }
+            }
+            return flat;
+          });
+        }
+        await mkdir(opts.outputDir, { recursive: true });
+        const rowDiffs = [];
+        if (opts.diff) {
+          for (let i = 0; i < fillRows.length; i++) {
+            const diff = await diffFields2(template, fillRows[i], {
+              ignoreFields: resolved.ignoreFields
+            });
+            rowDiffs[i] = diff;
+            if (!diff.ok) {
+              console.error(`Row ${i}: field diff failed`);
+              printFieldDiff(diff);
+              assertDiffOk(diff);
+            }
+          }
+        }
+        const results = await batchFill(template, fillRows, {
+          flatten: resolved.flatten,
+          strict: resolved.strict,
+          missing: resolved.missing,
+          updateAppearances: resolved.updateAppearances,
+          fontPath: resolved.fontPath,
+          schema,
+          failFast: opts.failFast ?? false,
+          ignoreFields: resolved.ignoreFields,
+          failOnWarnings: resolved.failOnWarnings
+        });
+        let failCount = 0;
+        let verifyFailCount = 0;
+        const manifestEntries = [];
+        for (const row of results) {
+          const rowStarted = Date.now();
+          if (!row.ok) {
+            failCount++;
+            console.error(`Row ${row.index}: ${row.error}`);
+            manifestEntries.push({
+              index: row.index,
+              ok: false,
+              warnings: row.warnings,
+              error: row.error,
+              durationMs: Date.now() - rowStarted
+            });
+            continue;
+          }
+          const ctx = { ...rawRowsForNames[row.index], index: row.index };
+          const name = formatOutputPath(opts.pattern, ctx, row.index);
+          const outPath = join(opts.outputDir, name);
+          await mkdir(dirname(outPath), { recursive: true });
+          await writeFile4(outPath, row.pdf);
+          for (const w of row.warnings) {
+            console.warn(`Row ${row.index} [${w.code}] ${w.message}`);
+          }
+          let verifyResult;
+          if (opts.verify) {
+            verifyResult = await verifyFilledPdf2(
+              row.pdf,
+              fillRows[row.index]
+            );
+            if (!verifyResult.ok) {
+              verifyFailCount++;
+              console.error(
+                `Row ${row.index}: verify failed (${verifyResult.mismatches.length} mismatch, ${verifyResult.missingInPdf.length} missing)`
+              );
+            }
+          }
+          console.log(`Row ${row.index}: ${outPath}`);
+          manifestEntries.push({
+            index: row.index,
+            ok: verifyResult ? verifyResult.ok : true,
+            output: outPath,
+            fieldsFilled: row.fieldsFilled,
+            warnings: row.warnings,
+            verify: verifyResult,
+            diff: rowDiffs[row.index],
+            durationMs: Date.now() - rowStarted
+          });
+        }
+        const ok = results.filter((r) => r.ok).length;
+        console.log(`Done: ${ok}/${results.length} \u2192 ${opts.outputDir}`);
+        if (opts.manifest) {
+          const manifestFormat = opts.manifestFormat === "jsonl" ? "jsonl" : "json";
+          await writeBatchManifest(
+            opts.manifest,
+            manifestEntries,
+            manifestFormat
+          );
+        }
+        if (failCount > 0 || verifyFailCount > 0) process.exitCode = 1;
+      } catch (err) {
+        if (err instanceof SchemaValidationError2) {
+          console.error(err.message, err.errors);
+          process.exitCode = 2;
+          return;
+        }
+        if (err instanceof PdfFillError4) {
+          console.error(`${err.code}: ${err.message}`);
+          process.exitCode = 1;
+          return;
+        }
+        throw err;
+      }
+    }
+  );
+}
+
+// src/commands/run.ts
+import { writeFile as writeFile5 } from "fs/promises";
+import {
+  runPipeline,
+  buildRunReport,
+  parseFillDataInput as parseFillDataInput4,
+  parseMappingFile as parseMappingFile4,
+  applyFieldMapping as applyFieldMapping3,
+  PdfFillError as PdfFillError5,
+  SchemaValidationError as SchemaValidationError3
+} from "@lzlz94/pdffill-core";
+function registerRunCommand(program2) {
+  program2.command("run").description("One-shot: doctor \u2192 fill \u2192 verify").argument("<pdf>", "PDF template path").argument("<data.json>", "Fill data (object) or business JSON with --mapping").requiredOption("-o, --output <path>", "Output PDF path").option("--mapping <path>", "Business JSON \u2192 PDF field mapping").option("--flatten", "Flatten form").option("--strict", "Fail on unknown fields in data").option("--schema <path>", "JSON Schema for data").option("--missing <mode>", "skip or error", "skip").option("--no-update-appearances", "Skip appearance regeneration").option("--font <path>", "CJK/Unicode font").option("--skip-doctor", "Skip template doctor check").option("--no-verify", "Skip post-fill verify").option(
+    "--ignore-fields <names>",
+    "Comma-separated PDF field names to skip MISSING_FIELD warnings"
+  ).option("--report <path>", "Write operation report JSON").option("--config <path>", "pdffill.json config file").option("--diff", "Run field diff before pipeline; fail on mismatch").option(
+    "--compare-template",
+    "With --diff: flag values unchanged from template"
+  ).option(
+    "--fail-on-warnings <codes>",
+    "Fail if warnings match codes (comma-separated, or * for any)"
+  ).action(
+    async (pdfPath, dataPath, opts) => {
+      const startedAt = /* @__PURE__ */ new Date();
+      let fieldDiff;
+      try {
+        const fileConfig = await loadPdffillConfig(opts.config);
+        const resolved = resolveFillCli(opts, fileConfig);
+        const template = await readBinary(pdfPath);
+        const raw = await readJson(dataPath);
+        let data;
+        if (opts.diff) {
+          const resolvedDiff = await resolveDataAndDiff({
+            template,
+            raw,
+            mappingPath: resolved.mappingPath,
+            ignoreFields: resolved.ignoreFields,
+            compareTemplate: opts.compareTemplate ?? false
+          });
+          fieldDiff = resolvedDiff.diff;
+          if (!fieldDiff.ok) printFieldDiff(fieldDiff);
+          assertDiffOk(fieldDiff);
+          data = resolvedDiff.data;
+        } else if (resolved.mappingPath) {
+          const map = parseMappingFile4(await readJson(resolved.mappingPath));
+          if (typeof raw !== "object" || raw === null || Array.isArray(raw)) {
+            throw new PdfFillError5(
+              "With --mapping, data must be a JSON object",
+              "INVALID_FILL_DATA_SHAPE"
+            );
+          }
+          data = applyFieldMapping3(raw, map);
+        } else {
+          data = parseFillDataInput4(raw);
+        }
+        const schema = opts.schema ? await readJsonSchema(opts.schema) : void 0;
+        const result = await runPipeline(template, data, {
+          flatten: resolved.flatten,
+          strict: resolved.strict,
+          missing: resolved.missing,
+          updateAppearances: resolved.updateAppearances,
+          fontPath: resolved.fontPath,
+          schema,
+          skipDoctor: resolved.skipDoctor,
+          verify: opts.noVerify !== true,
+          ignoreFields: resolved.ignoreFields,
+          failOnWarnings: resolved.failOnWarnings
+        });
+        await writeFile5(opts.output, result.fill.pdf);
+        for (const w of result.fill.warnings) {
+          console.warn(`[${w.code}] ${w.message}`);
+        }
+        console.log(`OK: ${opts.output} (${result.fill.fieldsFilled.length} field(s))`);
+        if (result.verify) {
+          console.log(`Verified ${result.verify.checked.length} field(s)`);
+        }
+        if (opts.report) {
+          await writeJsonReport(
+            opts.report,
+            buildRunReport({
+              ok: true,
+              startedAt,
+              durationMs: Date.now() - startedAt.getTime(),
+              template: pdfPath,
+              output: opts.output,
+              fill: result.fill,
+              doctor: result.doctor,
+              verify: result.verify,
+              diff: fieldDiff
+            })
+          );
+        }
+      } catch (err) {
+        if (opts.report) {
+          const error = err instanceof PdfFillError5 ? { code: err.code, message: err.message } : err instanceof SchemaValidationError3 ? { code: "SCHEMA_VALIDATION", message: err.message } : {
+            code: "UNKNOWN",
+            message: err instanceof Error ? err.message : String(err)
+          };
+          await writeJsonReport(
+            opts.report,
+            buildRunReport({
+              ok: false,
+              startedAt,
+              durationMs: Date.now() - startedAt.getTime(),
+              template: pdfPath,
+              output: opts.output,
+              fill: { pdf: new Uint8Array(0), fieldsFilled: [], warnings: [] },
+              diff: fieldDiff,
+              error
+            })
+          );
+        }
+        if (err instanceof SchemaValidationError3) {
+          console.error(err.message, err.errors);
+          process.exitCode = 2;
+          return;
+        }
+        if (err instanceof PdfFillError5) {
+          console.error(`${err.code}: ${err.message}`);
+          process.exitCode = 1;
+          return;
+        }
+        throw err;
+      }
+    }
+  );
+}
+
+// src/commands/diff.ts
+import { writeFile as writeFile6 } from "fs/promises";
+import {
+  diffFields as diffFields3,
+  diffFieldsWithMapping as diffFieldsWithMapping2,
+  listFields as listFields4,
+  parseFillDataInput as parseFillDataInput5,
+  parseMappingFile as parseMappingFile5,
+  PdfFillError as PdfFillError6
+} from "@lzlz94/pdffill-core";
+function registerDiffCommand(program2) {
+  program2.command("diff").description("Compare template fields to fill data (catch missing/unknown keys)").argument("<pdf>", "PDF template path").argument("<data.json>", "Fill data or business JSON (with --mapping)").option("--config <path>", "pdffill.json config file").option("--mapping <path>", "Business field mapping (overrides config.mapping)").option(
+    "--ignore-fields <names>",
+    "Comma-separated PDF fields to exclude from missing checks"
+  ).option("--include-readonly", "Include read-only PDF fields in diff").option(
+    "--compare-template",
+    "Flag values identical to current template field values"
+  ).option("--json", "Write diff result as JSON to stdout or --output").option("-o, --output <path>", "Write JSON diff result to file").action(
+    async (pdfPath, dataPath, opts) => {
+      try {
+        const fileConfig = await loadPdffillConfig(opts.config);
+        const merged = mergeConfig(fileConfig, opts);
+        const template = await readBinary(pdfPath);
+        const raw = await readJson(dataPath);
+        const mappingPath = resolveMappingPath(fileConfig, opts.mapping);
+        const ignoreFields = resolveIgnoreFields(fileConfig, opts.ignoreFields);
+        const diffOpts = {
+          ignoreFields,
+          includeReadOnly: opts.includeReadonly ?? false,
+          compareTemplate: opts.compareTemplate ?? false
+        };
+        let result;
+        if (mappingPath) {
+          const mapping = parseMappingFile5(await readJson(mappingPath));
+          if (typeof raw !== "object" || raw === null || Array.isArray(raw)) {
+            throw new PdfFillError6(
+              "With --mapping, data must be a JSON object",
+              "INVALID_FILL_DATA_SHAPE"
+            );
+          }
+          const fields = await listFields4(template);
+          result = diffFieldsWithMapping2(
+            fields,
+            raw,
+            mapping,
+            diffOpts
+          );
+        } else {
+          const data = parseFillDataInput5(raw);
+          result = await diffFields3(template, data, diffOpts);
+        }
+        if (opts.json || opts.output) {
+          const text = `${JSON.stringify(result, null, 2)}
+`;
+          if (opts.output) {
+            await writeFile6(opts.output, text, "utf8");
+            console.log(`Wrote ${opts.output}`);
+          } else {
+            console.log(text.trimEnd());
+          }
+        } else {
+          printFieldDiff(result);
+        }
+        if (!result.ok) process.exitCode = 1;
+      } catch (err) {
+        if (err instanceof PdfFillError6) {
+          console.error(`${err.code}: ${err.message}`);
+          process.exitCode = 1;
+          return;
+        }
+        throw err;
+      }
+    }
+  );
+}
+
+// src/index.ts
+var program = new Command();
+program.name("pdffill").description("List, diagnose, and fill PDF AcroForms (pdf-lib, no pdftk)").version("0.6.0");
+registerListCommand(program);
+registerDoctorCommand(program);
+registerFillCommand(program);
+registerScaffoldCommand(program);
+registerVerifyCommand(program);
+registerBatchCommand(program);
+registerRunCommand(program);
+registerDiffCommand(program);
+program.parse();

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "pdf-fill",
+  "version": "0.6.0",
+  "description": "CLI for listing, diagnosing, and filling PDF AcroForms",
+  "type": "module",
+  "bin": {
+    "pdffill": "./dist/index.js"
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsup src/index.ts --format esm --clean --external @lzlz94/pdffill-core",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "prepublishOnly": "npm run build"
+  },
+  "dependencies": {
+    "@lzlz94/pdffill-core": "0.6.0",
+    "commander": "^12.1.0"
+  },
+  "devDependencies": {
+    "tsup": "^8.3.5",
+    "typescript": "^5.7.2"
+  },
+  "license": "MIT",
+  "engines": {
+    "node": ">=18"
+  },
+  "keywords": [
+    "pdf",
+    "acroform",
+    "cli",
+    "pdf-form",
+    "pdffill"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/lz1834career/pdf-fill.git",
+    "directory": "packages/cli"
+  },
+  "bugs": {
+    "url": "https://github.com/lz1834career/pdf-fill/issues"
+  },
+  "homepage": "https://github.com/lz1834career/pdf-fill/tree/main/packages/cli#readme"
+}