@diy-accounting-uk/diya-gl 1.0.0

package/dist/app/bin/build-sitemaps.js

@@ -0,0 +1,51 @@
+#!/usr/bin/env node
+// SPDX-License-Identifier: AGPL-3.0-only
+// Copyright (C) 2025-2026 DIY Accounting Ltd
+//
+// build-sitemaps.js — Generate sitemap.xml for spreadsheets site
+//
+// Usage:
+//   node app/bin/build-sitemaps.js
+//
+// Reads:  web/spreadsheets.diyaccounting.co.uk/public/knowledge-base.toml
+//         web/spreadsheets.diyaccounting.co.uk/public/catalogue.toml
+// Writes: web/spreadsheets.diyaccounting.co.uk/public/sitemap.xml
+
+import { parse as parseTOML } from "smol-toml";
+import { readFileSync, writeFileSync, existsSync, readdirSync } from "fs";
+import { resolve, dirname } from "path";
+import { fileURLToPath } from "url";
+import { buildSitemapXml } from "../lib/sitemap-builder.js";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const ROOT = resolve(__dirname, "..", "..");
+const PUBLIC_DIR = resolve(ROOT, "web", "spreadsheets.diyaccounting.co.uk", "public");
+const KB_TOML = resolve(PUBLIC_DIR, "knowledge-base.toml");
+const CATALOGUE_TOML = resolve(PUBLIC_DIR, "catalogue.toml");
+const SITEMAP_PATH = resolve(PUBLIC_DIR, "sitemap.xml");
+
+let articles = [];
+if (existsSync(KB_TOML)) {
+  const kb = parseTOML(readFileSync(KB_TOML, "utf8"));
+  articles = kb.article || [];
+}
+
+let products = [];
+if (existsSync(CATALOGUE_TOML)) {
+  const cat = parseTOML(readFileSync(CATALOGUE_TOML, "utf8"));
+  products = cat.products || [];
+}
+
+// Reconciliation pages, discovered from the metadata files the page builder writes
+const RECONCILIATION_DIR = resolve(PUBLIC_DIR, "reconciliation");
+let reconciliationPages = [];
+if (existsSync(RECONCILIATION_DIR)) {
+  reconciliationPages = readdirSync(RECONCILIATION_DIR)
+    .filter((f) => f.endsWith(".json"))
+    .map((f) => f.replace(/\.json$/, ""))
+    .sort();
+}
+
+const { xml, urlCount } = buildSitemapXml(products, articles, reconciliationPages);
+writeFileSync(SITEMAP_PATH, xml, "utf8");
+console.log(`Spreadsheets sitemap: ${SITEMAP_PATH} (${urlCount} URLs)`);

package/dist/app/bin/compliance-report.js

@@ -0,0 +1,125 @@
+#!/usr/bin/env node
+// SPDX-License-Identifier: AGPL-3.0-only
+// Copyright (C) 2026 DIY Accounting Ltd
+//
+// compliance-report.js — Generate markdown compliance report from existing test reports.
+// Does NOT run tests — expects reports to already exist.
+//
+// Usage:
+//   node app/bin/compliance-report.js --target URL [--output FILE]
+
+import { readFileSync, writeFileSync, existsSync } from "node:fs";
+import { join, resolve, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+import {
+  parseNpmAudit,
+  parseEslintSecurity,
+  parsePa11yReport,
+  parseAxeResults,
+  parseLighthouseResults,
+  parseTextSpacingResults,
+  parseRetireResults,
+  generateReport,
+} from "../lib/compliance-report.js";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const projectRoot = resolve(__dirname, "..", "..");
+
+const args = process.argv.slice(2);
+const getArg = (name, defaultValue) => {
+  const idx = args.indexOf(name);
+  if (idx !== -1 && args[idx + 1]) return args[idx + 1];
+  return defaultValue;
+};
+
+const targetUrl = getArg("--target", null);
+const outputFile = getArg("--output", "REPORT_ACCESSIBILITY_PENETRATION.md");
+
+if (!targetUrl) {
+  console.error("Error: --target URL is required");
+  console.error("Usage: node app/bin/compliance-report.js --target URL [--output FILE]");
+  process.exit(1);
+}
+
+const targetDir = join(projectRoot, "web/spreadsheets.diyaccounting.co.uk/public/tests");
+const accessibilityDir = join(targetDir, "accessibility");
+const penetrationDir = join(targetDir, "penetration");
+
+function readJsonFile(path) {
+  try {
+    if (existsSync(path)) return JSON.parse(readFileSync(path, "utf8"));
+  } catch (error) {
+    console.warn(`Warning: Could not parse ${path}: ${error.message}`);
+  }
+  return null;
+}
+
+function readTextFile(path) {
+  try {
+    if (existsSync(path)) return readFileSync(path, "utf8");
+  } catch (error) {
+    console.warn(`Warning: Could not read ${path}: ${error.message}`);
+  }
+  return null;
+}
+
+function getPackageVersion() {
+  const pkg = readJsonFile(join(projectRoot, "package.json"));
+  return pkg?.version || "unknown";
+}
+
+function main() {
+  console.log("Compliance Report Generator");
+  console.log("===========================");
+  console.log(`Target: ${targetUrl}`);
+  console.log(`Output: ${outputFile}`);
+  console.log("");
+
+  const reportFiles = [
+    join(penetrationDir, "npm-audit.json"),
+    join(penetrationDir, "eslint-security.txt"),
+    join(penetrationDir, "retire.json"),
+    join(accessibilityDir, "pa11y-report.txt"),
+    join(accessibilityDir, "axe-results.json"),
+    join(accessibilityDir, "axe-wcag22-results.json"),
+    join(accessibilityDir, "lighthouse-results.json"),
+    join(accessibilityDir, "text-spacing-results.json"),
+  ];
+
+  const sourceFiles = [];
+  let foundCount = 0;
+  for (const file of reportFiles) {
+    const exists = existsSync(file);
+    const relativePath = file.replace(projectRoot + "/", "");
+    console.log(`  ${exists ? "+" : "-"} ${relativePath}`);
+    sourceFiles.push({ path: relativePath, exists });
+    if (exists) foundCount++;
+  }
+  console.log(`\nFound ${foundCount}/${reportFiles.length} report files.`);
+
+  if (foundCount === 0) {
+    console.error("\nError: No report files found. Run compliance tests first:");
+    console.error("  npm run compliance:ci-report");
+    process.exit(1);
+  }
+
+  console.log("\nGenerating compliance report...");
+  const report = generateReport({
+    targetUrl,
+    version: getPackageVersion(),
+    sourceFiles,
+    npmAudit: parseNpmAudit(readJsonFile(join(penetrationDir, "npm-audit.json"))),
+    eslint: parseEslintSecurity(readTextFile(join(penetrationDir, "eslint-security.txt"))),
+    pa11y: parsePa11yReport(readTextFile(join(accessibilityDir, "pa11y-report.txt"))),
+    axe: parseAxeResults(readJsonFile(join(accessibilityDir, "axe-results.json"))),
+    axeWcag22: parseAxeResults(readJsonFile(join(accessibilityDir, "axe-wcag22-results.json"))),
+    lighthouse: parseLighthouseResults(readJsonFile(join(accessibilityDir, "lighthouse-results.json"))),
+    textSpacing: parseTextSpacingResults(readJsonFile(join(accessibilityDir, "text-spacing-results.json"))),
+    retire: parseRetireResults(readJsonFile(join(penetrationDir, "retire.json"))),
+  });
+  const outputPath = join(projectRoot, outputFile);
+  writeFileSync(outputPath, report);
+  console.log(`\nReport written to: ${outputPath}`);
+}
+
+main();

package/dist/app/bin/cross-package-reconciliation.js

@@ -0,0 +1,92 @@
+#!/usr/bin/env node
+// SPDX-License-Identifier: AGPL-3.0-only
+// Copyright (C) 2026 DIY Accounting Ltd
+//
+// cross-package-reconciliation.js — Check that values which should be
+// consistent between packages are consistent across reconciliation reports.
+//
+// For a non-VAT scenario with the same transactions, pre-tax profit should
+// be identical in BST, SE, and Ltd (since amounts are face value, no VAT split).
+//
+// Usage:
+//   node app/bin/cross-package-reconciliation.js
+//   npm run cross-package-reconciliation
+
+import { readFileSync, readdirSync, existsSync } from "fs";
+import { resolve, dirname } from "path";
+import { fileURLToPath } from "url";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const REPORTS_DIR = resolve(__dirname, "..", "..", "reports");
+
+if (!existsSync(REPORTS_DIR)) {
+  console.error("No reports/ directory. Run reconciliation first.");
+  process.exit(1);
+}
+
+const reports = readdirSync(REPORTS_DIR)
+  .filter((f) => f.endsWith(".md"))
+  .map((f) => {
+    const content = readFileSync(resolve(REPORTS_DIR, f), "utf-8");
+    return { name: f, content };
+  });
+
+console.log(`Found ${reports.length} reconciliation reports`);
+
+// Extract scenario name and key values from each report
+function extractValues(content) {
+  const scenario = content.match(/Scenario: (.+)/)?.[1] || "";
+  const status = content.match(/Status: (.+)/)?.[1] || "";
+
+  // Extract cell values from appendix
+  const values = {};
+  const cellMatches = [...content.matchAll(/\| ([A-Z]+\d+) \| .+? \| ([^\|]+?) \|/g)];
+  for (const m of cellMatches) {
+    const val = parseFloat(m[2].trim());
+    if (!isNaN(val)) values[m[1]] = val;
+  }
+
+  return { scenario, status, values };
+}
+
+// Group reports by scenario
+const byScenario = {};
+for (const r of reports) {
+  const { scenario, status, values } = extractValues(r.content);
+  if (!byScenario[scenario]) byScenario[scenario] = [];
+
+  // Detect product from filename
+  let product = "unknown";
+  if (r.name.includes("Basic_Sole_Trader")) product = "bst";
+  else if (r.name.includes("Self_Employed")) product = "se";
+  else if (r.name.includes("Company")) product = "ltd";
+  else if (r.name.includes("Taxi")) product = "taxi";
+
+  byScenario[scenario].push({ name: r.name, product, status, values });
+}
+
+let failures = 0;
+
+// For each scenario that appears in multiple products, check consistency
+for (const [scenario, entries] of Object.entries(byScenario)) {
+  if (entries.length < 2) continue;
+
+  console.log(`\nScenario: ${scenario} (${entries.length} reports)`);
+  for (const e of entries) {
+    console.log(`  ${e.product}: ${e.status}`);
+  }
+
+  // Check: all reports should RECONCILE
+  const anomalies = entries.filter((e) => e.status.includes("ANOMALY"));
+  if (anomalies.length > 0) {
+    console.log(`  CROSS-CHECK FAIL: ${anomalies.length} anomalies detected`);
+    failures++;
+  }
+}
+
+if (failures > 0) {
+  console.log(`\n=== ${failures} cross-package failures ===`);
+  process.exit(1);
+} else {
+  console.log(`\n=== All cross-package checks passed ===`);
+}

package/dist/app/bin/diya-gl-mcp.js

@@ -0,0 +1,27 @@
+#!/usr/bin/env node
+// SPDX-License-Identifier: AGPL-3.0-only
+// Copyright (C) 2026 DIY Accounting Ltd
+//
+// diya-gl-mcp.js — a stdio MCP server exposing the diya-gl pipeline as
+// four tools: extract_book, report, edit_lines, save_workbook, over any of
+// the four products (Basic Sole Trader, Taxi Driver, Self Employed, Company).
+//
+// Transport: hand-rolled newline-delimited JSON-RPC 2.0
+// (app/lib/mcp/jsonrpc-stdio.js), not @modelcontextprotocol/sdk. The SDK's
+// Node package pulls in express, hono, cors, jose and zod -- an HTTP
+// server framework and an HTTP-transport dependency set -- to reach the
+// three JSON-RPC methods a stdio-only server actually receives here
+// (initialize, tools/list, tools/call). This repo carries no server
+// framework at all (see CLAUDE.md's "what this repo does NOT have"): adding
+// one to speak three methods over stdin/stdout would be exactly the heavy
+// dependency the plan's own escape hatch names. The protocol surface this
+// server implements is small enough to write directly and test without a
+// mock of someone else's transport.
+//
+// Run directly: node app/bin/diya-gl-mcp.js
+// Registered for this repo's own Claude Code sessions in .mcp.json.
+
+import { createMethods } from "../lib/mcp/server.js";
+import { serveJsonRpc } from "../lib/mcp/jsonrpc-stdio.js";
+
+serveJsonRpc({ input: process.stdin, output: process.stdout, methods: createMethods() });

package/dist/app/bin/export.js

@@ -0,0 +1,318 @@
+#!/usr/bin/env node
+// SPDX-License-Identifier: AGPL-3.0-only
+// Copyright (C) 2026 DIY Accounting Ltd
+//
+// export.js — Extract diya-gl data from a populated Excel package.
+//
+// Usage:
+//   node app/bin/export.js --package bst --source-dir examples/bst-latest --output-dir /tmp/exported
+//   node app/bin/export.js --package se --source-dir examples/se-latest --output-dir /tmp/exported
+//   node app/bin/export.js --file my-file.xlsx
+//   node app/bin/export.js --file my-package.zip --output-dir /tmp/exported
+//   node app/bin/export.js --package se --file my-package.zip --output-dir /tmp/exported
+//
+// --source-dir reads a package the pipeline already unpacked into its own
+// directory, and always needs --package to say which product's extractors
+// to run. --file takes any of the kinds books-interchange.js reads -- a
+// customer's own download, not a directory this repo laid out -- and writes
+// beside that input unless --output-dir says otherwise; --package is
+// optional there, since the file itself says which product it is (the
+// anchor guard for a single workbook, the sheets a package zip carries for
+// the rest). Given anyway, --package is checked against what the file
+// sniffs as and a disagreement is refused by name.
+//
+// book.toml and lines.jsonl are written through app/lib/diya-gl-canonical.js,
+// the one form D is compared in, so a re-ordered line, a re-ordered field or
+// a formatting difference can never register as a data difference. The
+// exported book is validated against the published v2 schemas before it is
+// written. --file also emits report.json: R, computed by the JS engine from
+// the D just extracted, through the same modules report.js --data uses, so
+// one run is the whole extract-recalculate-report loop. Alongside it goes
+// overtyped.json, every sum the template computes that this copy of it
+// carries as a typed value instead -- present only when the input carried an
+// actual workbook to compare against a computed value in the first place.
+// --file also emits bookchecks.json: the book checks and warnings
+// app/lib/book-checks.js runs over D, for whichever of the five kinds the
+// input sniffed as -- the tax data behind the VAT threshold warning comes
+// from loadTaxDataForBook, the book's own declared year read straight off
+// app/data/, so the figure is real rather than a stand-in constant.
+
+import { readFileSync, writeFileSync, mkdirSync } from "fs";
+import { resolve, dirname, basename } from "path";
+import { extractBook, extractLines } from "../lib/xlsx-exporter.js";
+import { workbookSetFromDirectory } from "../lib/workbook-set.js";
+import { canonicalBookToml, canonicalLinesJsonl } from "../lib/diya-gl-canonical.js";
+import { stampBook } from "../lib/provenance.js";
+import { validateBook, validateLines } from "../lib/diya-gl-schema.js";
+import { extractTaxDataFromBook, diyaGlToScenario } from "../lib/diya-gl-loader.js";
+import { calculateFromDiyaGl } from "../lib/diya-gl-calculator.js";
+import { calculateExpectedTax } from "../lib/tax/income-tax.js";
+import { buildReportDocument, serializeReportDocument } from "../lib/report-serializer.js";
+import { runBookChecks, bookChecksJson } from "../lib/book-checks.js";
+import { loadTaxDataForBook, productOf } from "../lib/product-workbook.js";
+import {
+  readBookSource,
+  AnchorError,
+  XlsBookSourceError,
+  UnknownBookSourceError,
+  InvalidDiyaGlBookError,
+  InvalidDiyaGlJsonError,
+  PackagePartError,
+  ProductNotAvailableError,
+} from "../lib/books-interchange.js";
+import { PRODUCTS } from "../lib/products.js";
+
+// A book read through --file whose sniffed product disagrees with the
+// --package it was given, so the CLI reports it by name rather than
+// building R for the wrong product.
+export class PackageMismatchError extends Error {
+  constructor(given, actualProductName) {
+    super(`--package ${given} was given but the file is a ${actualProductName} workbook`);
+    this.name = "PackageMismatchError";
+  }
+}
+
+// Every error a book source can refuse a read with, named rather than a
+// stack trace: --file prints the message and exits, exactly as the anchor
+// guard already did before books-interchange.js grew four more ways a file
+// can be rejected.
+const NAMED_BOOK_SOURCE_ERRORS = [
+  AnchorError,
+  XlsBookSourceError,
+  UnknownBookSourceError,
+  InvalidDiyaGlBookError,
+  InvalidDiyaGlJsonError,
+  PackagePartError,
+  ProductNotAvailableError,
+  PackageMismatchError,
+];
+
+function isNamedBookSourceError(err) {
+  return NAMED_BOOK_SOURCE_ERRORS.some((ErrorClass) => err instanceof ErrorClass);
+}
+
+function parseArgs(argv) {
+  const args = argv.slice(2);
+  const getArg = (name) => {
+    const idx = args.indexOf(name);
+    return idx !== -1 && args[idx + 1] ? args[idx + 1] : null;
+  };
+
+  const packageName = getArg("--package");
+  const sourceDir = getArg("--source-dir");
+  const file = getArg("--file");
+  const outputDir = getArg("--output-dir");
+
+  const usage =
+    "Usage: node app/bin/export.js --package <bst|taxi|se|ltd> --source-dir <path> --output-dir <path>\n" +
+    "   or: node app/bin/export.js --file <path.xlsx|path.zip> [--package <bst|taxi|se|ltd>] [--output-dir <path>]";
+
+  if (!sourceDir && !file) {
+    console.error(usage);
+    process.exit(1);
+  }
+  if (sourceDir && file) {
+    console.error("Error: --source-dir and --file are mutually exclusive");
+    process.exit(1);
+  }
+  if (sourceDir && !packageName) {
+    console.error(usage);
+    process.exit(1);
+  }
+  if (sourceDir && !outputDir) {
+    console.error("Error: --output-dir is required with --source-dir");
+    process.exit(1);
+  }
+
+  return { packageName, sourceDir, file, outputDir };
+}
+
+// R for a (book, lines) pair: the JS engine's own D -> R loop --
+// diyaGlToScenario -> calculateFromDiyaGl -> checkCompliance ->
+// buildReportDocument -- the same loop report.js's --data mode runs, so the
+// CLI's --file mode, report.js and the MCP server's tools never diverge on
+// how R is built from the same D. Pure: no disk access, no console output.
+export function buildFileReportDocument(book, lines, packageName, productMod) {
+  const taxData = extractTaxDataFromBook(book, packageName);
+  const scenario = diyaGlToScenario(book, lines, packageName);
+  const results = calculateFromDiyaGl(book, lines, packageName, taxData, scenario);
+  const mergedScenario = { ...scenario, ...scenario.expected };
+  const periodEnd = book.documentInfo?.periodCoveredEnd;
+  const yearEnd = periodEnd ? new Date(periodEnd).toISOString().slice(0, 10) : null;
+  const checks =
+    typeof productMod.checkCompliance === "function"
+      ? productMod.checkCompliance({ ...results }, mergedScenario, taxData, calculateExpectedTax, yearEnd)
+      : [];
+  return buildReportDocument({
+    packageName,
+    engine: "js",
+    results,
+    productMod,
+    scenario: mergedScenario,
+    checks,
+    scenarioName: book.documentInfo?.entriesComment,
+    yearEnd,
+  });
+}
+
+function writeReportJson(outputDir, document) {
+  writeFileSync(resolve(outputDir, "report.json"), serializeReportDocument(document));
+  console.log(`  report.json: ${document.values.length} values`);
+}
+
+function writeOvertypedJson(outputDir, overtyped) {
+  writeFileSync(resolve(outputDir, "overtyped.json"), `${JSON.stringify(overtyped, null, 2)}\n`);
+  const count = Object.keys(overtyped).length;
+  console.log(`  overtyped.json: ${count} ${count === 1 ? "cell" : "cells"} typed over a template formula`);
+}
+
+// R's calculated cell map alone, the same D -> R half buildFileReportDocument
+// runs before it builds a whole report document -- for a caller (the book
+// checks, which only read a handful of R's cells for a warning like Ltd's
+// distributable-profits one) that has no use for the rest of it.
+export function calculatedResultsFor(book, lines, taxData) {
+  const packageName = productOf(book);
+  const scenario = diyaGlToScenario(book, lines, packageName);
+  return calculateFromDiyaGl(book, lines, packageName, taxData, scenario);
+}
+
+// The book checks and warnings, run over D with the book's own tax year's
+// data behind the VAT threshold warning -- loadTaxDataForBook resolves that
+// year from book.documentInfo alone, so this runs the same way whichever of
+// the five kinds --file read the book from. Also carries R, so a
+// product's own warning that reads the calculated accounts (Ltd's dividend
+// warning against distributable profits) sees them here too, not just
+// through the report.
+async function writeBookChecksJson(outputDir, book, lines) {
+  const taxData = await loadTaxDataForBook(book);
+  const calculatedResults = calculatedResultsFor(book, lines, taxData);
+  const { results } = runBookChecks({ book, lines, taxData, results: calculatedResults });
+  writeFileSync(resolve(outputDir, "bookchecks.json"), bookChecksJson(results));
+  const failing = results.filter((r) => r.result === "fail").length;
+  console.log(`  bookchecks.json: ${results.length} rules, ${failing} failing`);
+}
+
+// The whole --file extraction: books-interchange.js sniffs the input and
+// turns it into D (a workbook or a package zip runs the anchor guard and
+// the extractors over a workbook set; a diya-gl zip, a JSON file or that
+// JSON zipped validate straight against the published schemas), then this
+// builds R from that D. --source-dir's CLI path and the MCP server's
+// extract_book tool both call this rather than each reaching into
+// books-interchange.js on their own, so a change to how D or R are produced
+// can only ever happen in one place.
+//
+// The product is whichever of the four the file sniffs as; a caller that
+// already knows which product it expects (--package, or the MCP tool's own
+// argument) passes it as `product` and gets a named refusal when the file
+// disagrees, rather than silently reading it as something it is not.
+export async function extractBookFromFile(filePath, { product } = {}) {
+  const resolvedFile = resolve(filePath);
+  const bytes = readFileSync(resolvedFile);
+  const { product: sniffedProduct, book, lines, overtyped } = await readBookSource(bytes, basename(resolvedFile), { products: PRODUCTS });
+  if (product && product !== sniffedProduct) {
+    throw new PackageMismatchError(product, PRODUCTS[sniffedProduct].PRODUCT.name);
+  }
+  const productMod = PRODUCTS[sniffedProduct];
+  const document = buildFileReportDocument(book, lines, sniffedProduct, productMod);
+  return { product: sniffedProduct, book, lines, document, overtyped };
+}
+
+// The v2 schema validation, then book.toml + lines.jsonl written through
+// diya-gl-canonical.js, shared by both --source-dir and --file so the two
+// can only ever differ in how they got to (book, lines), never in how that
+// pair reaches disk -- which is what the byte-for-byte verification rests on.
+function writeDiyaGlData(outputDir, book, lines) {
+  const stamped = stampBook(book);
+  const bookErrors = validateBook(stamped);
+  if (!bookErrors.valid) {
+    console.error(`The exported book does not conform to the published v2 book schema:`);
+    for (const error of bookErrors.errors) console.error(`  ${error}`);
+    process.exit(1);
+  }
+  const lineErrors = validateLines(lines, stamped);
+  if (!lineErrors.valid) {
+    console.error(`The exported lines do not conform to the published v2 lines schema:`);
+    for (const error of lineErrors.errors.slice(0, 20)) console.error(`  ${error}`);
+    if (lineErrors.errors.length > 20) console.error(`  ... and ${lineErrors.errors.length - 20} more`);
+    process.exit(1);
+  }
+
+  mkdirSync(outputDir, { recursive: true });
+  writeFileSync(resolve(outputDir, "lines.jsonl"), canonicalLinesJsonl(lines));
+  writeFileSync(resolve(outputDir, "book.toml"), canonicalBookToml(stamped));
+
+  console.log(`  lines.jsonl: ${lines.length} entries`);
+  console.log(`  book.toml: ${Object.keys(stamped).length} tables`);
+}
+
+async function runFileMode(filePath, outputDirArg, packageName) {
+  const resolvedFile = resolve(filePath);
+  const resolvedOutput = resolve(outputDirArg || dirname(resolvedFile));
+
+  console.log(`=== export.js ===`);
+  console.log(`File:       ${resolvedFile}`);
+  console.log(`Output:     ${resolvedOutput}`);
+
+  let extracted;
+  try {
+    extracted = await extractBookFromFile(resolvedFile, { product: packageName });
+  } catch (err) {
+    if (isNamedBookSourceError(err)) {
+      console.error(err.message);
+      process.exit(1);
+    }
+    throw err;
+  }
+
+  const { product, book, lines, document, overtyped } = extracted;
+  console.log(`Package:    ${product}`);
+  writeDiyaGlData(resolvedOutput, book, lines);
+  writeReportJson(resolvedOutput, document);
+  if (overtyped) writeOvertypedJson(resolvedOutput, overtyped);
+  await writeBookChecksJson(resolvedOutput, book, lines);
+
+  console.log(`\nExported ${lines.length} transactions to ${resolvedOutput}`);
+}
+
+async function main() {
+  const { packageName, sourceDir, file, outputDir } = parseArgs(process.argv);
+  if (packageName && !PRODUCTS[packageName]) {
+    console.error(`Unknown package: ${packageName}. Available: ${Object.keys(PRODUCTS).join(", ")}`);
+    process.exit(1);
+  }
+
+  if (file) {
+    await runFileMode(file, outputDir, packageName);
+    return;
+  }
+
+  const productMod = PRODUCTS[packageName];
+  const resolvedSource = resolve(sourceDir);
+  const resolvedOutput = resolve(outputDir);
+
+  console.log(`=== export.js ===`);
+  console.log(`Package:    ${packageName}`);
+  console.log(`Source:     ${resolvedSource}`);
+  console.log(`Output:     ${resolvedOutput}`);
+
+  const set = await workbookSetFromDirectory(resolvedSource);
+  if (set.names().length === 0) {
+    console.error(`No xlsx file found in ${resolvedSource}`);
+    process.exit(1);
+  }
+
+  const lines = await extractLines(set, packageName);
+  const book = await extractBook(set, packageName, lines, productMod.CELL_MAP);
+  writeDiyaGlData(resolvedOutput, book, lines);
+  console.log(`\nExported ${lines.length} transactions to ${resolvedOutput}`);
+}
+
+// Only run as a CLI when invoked directly; a caller importing
+// extractBookFromFile or buildFileReportDocument (the MCP server does both)
+// must never trigger a second, argv-driven run of this file's own main().
+if (import.meta.url === `file://${process.argv[1]}`) {
+  main().catch((err) => {
+    console.error(err);
+    process.exit(1);
+  });
+}