@diy-accounting-uk/diya-gl 1.0.0

package/README.md

@@ -0,0 +1,63 @@
+# @diy-accounting-uk/diya-gl
+
+Run a UK sole trader's or company's accounts from the command line. A diya-gl book is a
+book.toml and a lines.jsonl file, usually a few kilobytes, that hold a year of transactions
+and the chart of accounts they post to. This package recalculates one, reads one out of an
+Excel workbook, writes one back into a workbook, and serves one over MCP, all through the
+same engine the [DIY Accounting spreadsheets site](https://spreadsheets.diyaccounting.co.uk)
+reconciles in CI.
+
+Four products: Basic Sole Trader, Taxi Driver, Self Employed, Limited Company.
+
+## Install
+
+```
+npm install -g @diy-accounting-uk/diya-gl
+```
+
+## Use
+
+```
+diya-gl recalc --package bst --data my-book --years se-2025-2026 --output-dir out
+diya-gl read-workbook --file my-workbook.xlsx --output-dir out
+diya-gl write-workbook --data my-book --output-dir out
+diya-gl mcp
+```
+
+Each subcommand is also its own command, if you only want one on your `PATH`:
+`diya-gl-recalc`, `diya-gl-read-workbook`, `diya-gl-write-workbook`, `diya-gl-mcp`.
+
+- **recalc** takes a diya-gl book (`--data`) or a populated workbook (`--source-dir`,
+  `--mode saved|recalculate`) and writes `report.json`: every figure, report section and
+  compliance check the engine computes.
+- **read-workbook** takes an `.xlsx`, a package zip, or a diya-gl zip or JSON file
+  (`--file`), and writes `book.toml`, `lines.jsonl`, `report.json` and `bookchecks.json`.
+- **write-workbook** takes a diya-gl book (`--data` or `--file`) and writes the Excel
+  package its product composes onto its template — the same client-side path the site's
+  books page uses, so it never needs LibreOffice. Add `--zip` for the package as one zip.
+- **mcp** runs a stdio [MCP](https://modelcontextprotocol.io) server with four tools:
+  `extract_book`, `report`, `edit_lines`, `save_workbook`. Point an MCP client at
+  `diya-gl-mcp` (or `diya-gl mcp`) with no arguments.
+
+## The format
+
+A diya-gl book's fields are drawn from the XBRL Global Ledger Taxonomy Framework 2015 and
+map onto HMRC's SA103S boxes. The two schemas that validate a book are published at
+[`/schema/diya-gl-book-v2.schema.json`](https://spreadsheets.diyaccounting.co.uk/schema/diya-gl-book-v2.schema.json)
+and
+[`/schema/diya-gl-lines-v2.schema.json`](https://spreadsheets.diyaccounting.co.uk/schema/diya-gl-lines-v2.schema.json).
+The full field mapping, the check catalogue and the reconciliation evidence behind them are
+on the [format spec page](https://spreadsheets.diyaccounting.co.uk/diya-gl.html).
+
+## Provenance
+
+Every book this package writes carries five stamps: the format version, this package's own
+version and commit, a hash over the tax-year data applied, and each product's template hash
+and reconciliation scorecard. Recalculating an old book either reproduces its `report.json`
+byte for byte or names the stamp that differs. Every published release is cut from a commit
+whose reconciliation checks passed; the scorecards are on the
+[reconciled releases page](https://spreadsheets.diyaccounting.co.uk/reconciliation/releases.html).
+
+## License
+
+AGPL-3.0-only. Copyright (C) 2026 DIY Accounting Ltd.

package/bin/diya-gl-mcp.js

@@ -0,0 +1,10 @@
+#!/usr/bin/env node
+// SPDX-License-Identifier: AGPL-3.0-only
+// Copyright (C) 2026 DIY Accounting Ltd
+//
+// diya-gl-mcp.js — the stdio MCP server, four tools over a loaded diya-gl
+// book: extract_book, report, edit_lines, save_workbook. See
+// app/lib/mcp/server.js in the source repository for the method table.
+
+import { runDistBin } from "./run-dist-bin.js";
+runDistBin("app/bin/diya-gl-mcp.js", process.argv.slice(2));

package/bin/diya-gl-read-workbook.js

@@ -0,0 +1,11 @@
+#!/usr/bin/env node
+// SPDX-License-Identifier: AGPL-3.0-only
+// Copyright (C) 2026 DIY Accounting Ltd
+//
+// diya-gl-read-workbook.js — reads an .xlsx, a package zip, or any of the
+// diya-gl formats, and extracts book.toml, lines.jsonl, report.json and
+// bookchecks.json. See app/bin/export.js in the source repository for the
+// full option list (--file or --source-dir plus --package).
+
+import { runDistBin } from "./run-dist-bin.js";
+runDistBin("app/bin/export.js", process.argv.slice(2));

package/bin/diya-gl-recalc.js

@@ -0,0 +1,10 @@
+#!/usr/bin/env node
+// SPDX-License-Identifier: AGPL-3.0-only
+// Copyright (C) 2026 DIY Accounting Ltd
+//
+// diya-gl-recalc.js — report.json and bookchecks.json from a diya-gl book
+// or a populated Excel package. See `diya-gl recalc --help` for usage, or
+// app/bin/report.js in the source repository for the full option list.
+
+import { runDistBin } from "./run-dist-bin.js";
+runDistBin("app/bin/report.js", process.argv.slice(2));

package/bin/diya-gl-write-workbook.js

@@ -0,0 +1,12 @@
+#!/usr/bin/env node
+// SPDX-License-Identifier: AGPL-3.0-only
+// Copyright (C) 2026 DIY Accounting Ltd
+//
+// diya-gl-write-workbook.js — writes the Excel package a diya-gl book
+// composes onto its product's template, with no LibreOffice: the same
+// client-side compose path the books page uses. See
+// app/bin/write-workbook.js in the source repository for the full option
+// list (--data or --file, plus --zip for the package download).
+
+import { runDistBin } from "./run-dist-bin.js";
+runDistBin("app/bin/write-workbook.js", process.argv.slice(2));

package/bin/diya-gl.js

@@ -0,0 +1,24 @@
+#!/usr/bin/env node
+// SPDX-License-Identifier: AGPL-3.0-only
+// Copyright (C) 2026 DIY Accounting Ltd
+//
+// diya-gl.js — the dispatcher: diya-gl <recalc|read-workbook|write-workbook|mcp> [args].
+// Each subcommand is also its own bin (diya-gl-recalc, and so on), for a
+// caller that wants one command on its PATH without the others.
+
+import { runDistBin } from "./run-dist-bin.js";
+
+const SUBCOMMANDS = {
+  "recalc": "app/bin/report.js",
+  "read-workbook": "app/bin/export.js",
+  "write-workbook": "app/bin/write-workbook.js",
+  "mcp": "app/bin/diya-gl-mcp.js",
+};
+
+const [subcommand, ...rest] = process.argv.slice(2);
+const target = SUBCOMMANDS[subcommand];
+if (!target) {
+  console.error(`Usage: diya-gl <${Object.keys(SUBCOMMANDS).join("|")}> [args]`);
+  process.exit(1);
+}
+runDistBin(target, rest);

package/bin/run-dist-bin.js

@@ -0,0 +1,23 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+// Copyright (C) 2026 DIY Accounting Ltd
+//
+// run-dist-bin.js — every wrapper below spawns the real entry point under
+// dist/ as a child process rather than importing it, so each one runs the
+// same way regardless of whether the target file guards its own main() on
+// import.meta.url (report.js does not; export.js and write-workbook.js do)
+// -- an import would silently skip the guarded ones. stdio is inherited,
+// so the MCP server's stdin/stdout JSON-RPC transport passes straight
+// through to whatever spawned this wrapper.
+
+import { spawnSync } from "child_process";
+import { dirname, resolve } from "path";
+import { fileURLToPath } from "url";
+
+const BIN_DIR = dirname(fileURLToPath(import.meta.url));
+
+export function runDistBin(relativePath, args) {
+  const target = resolve(BIN_DIR, "..", "dist", relativePath);
+  const result = spawnSync(process.execPath, [target, ...args], { stdio: "inherit" });
+  if (result.error) throw result.error;
+  process.exit(result.status ?? 1);
+}