@diy-accounting-uk/diya-gl 1.2.43 → 1.2.45

package/README.md

@@ -67,9 +67,84 @@ Each subcommand is also its own command, if you only want one on your `PATH`:
   another site. The book stays in the browser (the part of the address after `#` is never sent
   anywhere). The server stays up until Ctrl-C. The workbook templates come from
   spreadsheets.diyaccounting.co.uk the first time a page action needs one.
-- **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.
+- **mcp** runs a stdio [MCP](https://modelcontextprotocol.io) server with eight tools:
+  `extract_book`, `report`, `edit_lines`, `save_workbook`, and four that read every detail of
+  the loaded book: `lines` (filter and group every transaction, e.g. best customer or spend on
+  fuel in June), `chart` (the accounts and the report rows each feeds), `book` (the business,
+  period, tax settings and registers) and `checks` (every book check with the entryNumbers
+  behind it). Point an MCP client at `diya-gl-mcp` (or `diya-gl mcp`) with no arguments.
+
+## API
+
+The package root exports three functions that turn a book into the figures HMRC's MTD APIs
+take. Each takes the parsed book, its lines and a parameters object, and returns a promise.
+Nothing is sent anywhere: the answer is the request body to send, plus what fed it.
+
+Load a book first:
+
+```js
+import { readFileSync } from "node:fs";
+import { parse } from "smol-toml";
+
+function loadBook(dir) {
+  const book = parse(readFileSync(`${dir}/book.toml`, "utf8"));
+  const lines = readFileSync(`${dir}/lines.jsonl`, "utf8")
+    .split("\n")
+    .filter(Boolean)
+    .map((line) => JSON.parse(line));
+  return { book, lines };
+}
+```
+
+### `deriveVatReturn(book, lines, { periodEnd, periodStart?, periodKey? })`
+
+The nine VAT return boxes for the three-month period ending `periodEnd` (YYYY-MM-DD), from a
+Limited Company book that declares `diya-gl:vatRegistered = true`. `periodStart`, when given,
+must open that quarter; `periodKey` is echoed back. The answer carries `boxes` (box1 to box9),
+`hmrc` (the same figures under HMRC's field names, boxes 1 to 5 to the penny and 6 to 9 in
+whole pounds), `months`, `dueDate`, `scheme`, and `lines`: the journal lines behind boxes 1, 4,
+6 and 7, each with what it contributes. A book whose lines do not reconcile with its VAT
+interface is refused.
+
+```js
+import { deriveVatReturn } from "@diy-accounting-uk/diya-gl";
+
+const { book, lines } = loadBook("my-company-book");
+const answer = await deriveVatReturn(book, lines, { periodStart: "2025-07-01", periodEnd: "2025-09-30" });
+console.log(answer.hmrc); // { vatDueSales, vatDueAcquisitions, totalVatDue, ..., totalAcquisitionsExVAT }
+```
+
+### `deriveItsaQuarterlyUpdate(book, lines, { periodEndDate?, quarterlyPeriodType?, taxYear? })`
+
+One period of HMRC's Self Employment Business API from a Self Employed book. In 2023-24 and
+2024-25 each period carries its own figures; from 2025-26 each carries the running total from
+6 April. `periodEndDate` picks the period among the year's four; without it every period is
+answered. `quarterlyPeriodType` is `standard` (6 April quarters, the default) or `calendar`.
+`taxYear` (as `2025-26`) overrides the year the book's dates imply. Each period lists the fields
+the book cannot source under `omitted`; those are left out of the body, never sent as zero.
+
+```js
+import { deriveItsaQuarterlyUpdate } from "@diy-accounting-uk/diya-gl";
+
+const { book, lines } = loadBook("my-self-employed-book");
+const answer = await deriveItsaQuarterlyUpdate(book, lines, { periodEndDate: "2025-10-05" });
+const [period] = answer.periods; // { periodDates, periodIncome, periodExpenses, ..., omitted, covers }
+```
+
+### `deriveItsaAnnualSubmission(book, lines, { taxYear? })`
+
+The year's allowances and adjustments for the same API's annual submission, from a Self
+Employed book, restricted to the fields HMRC accepts for that tax year. `taxYear` (as
+`2025-26`) overrides the year the book's dates imply. The answer carries `allowances`,
+`adjustments`, `omitted` and `warnings`.
+
+```js
+import { deriveItsaAnnualSubmission } from "@diy-accounting-uk/diya-gl";
+
+const { book, lines } = loadBook("my-self-employed-book");
+const answer = await deriveItsaAnnualSubmission(book, lines, { taxYear: "2025-26" });
+console.log(answer.allowances.annualInvestmentAllowance);
+```
 
 ## The format
 

package/bin/diya-gl-mcp.js

@@ -2,8 +2,9 @@
 // SPDX-License-Identifier: Apache-2.0
 // Copyright (C) 2006-2026 DIY Accounting Limited
 //
-// diya-gl-mcp.js — the stdio MCP server, four tools over a loaded diya-gl
-// book: extract_book, report, edit_lines, save_workbook. See
+// diya-gl-mcp.js — the stdio MCP server over a loaded diya-gl book:
+// extract_book, report, edit_lines, save_workbook, lines, chart, book and
+// checks. See
 // app/lib/mcp/server.js in the source repository for the method table.
 
 import { runDistBin } from "./run-dist-bin.js";

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

@@ -3,7 +3,8 @@
 // Copyright (C) 2006-2026 DIY Accounting Limited
 //
 // 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
+// tools: extract_book, report, edit_lines, save_workbook, lines, chart,
+// book and checks, over any of
 // the four products (Basic Sole Trader, Taxi Driver, Self Employed, Company).
 //
 // Transport: hand-rolled newline-delimited JSON-RPC 2.0

package/dist/app/data/releases.json

@@ -1351,6 +1351,58 @@
           "scorecard": "101605 passed, 0 warnings, 0 failed"
         }
       }
+    },
+    {
+      "tag": "diya-gl-v1.2.43",
+      "date": "2026-10-03",
+      "formatVersion": "diya-gl/1",
+      "engineVersion": "1.2.40+57de8f55b",
+      "taxDataHash": "89424bd36c0d",
+      "reconciledCommit": "54e8731a91279975e61b1a232fbb67fda89515f0",
+      "templates": {
+        "bst": {
+          "hash": "0d003e10e00c",
+          "scorecard": "812 passed, 0 warnings, 0 failed"
+        },
+        "taxi": {
+          "hash": "1ff69654d64d",
+          "scorecard": "700 passed, 0 warnings, 0 failed"
+        },
+        "se": {
+          "hash": "064605ae76ed",
+          "scorecard": "8014 passed, 0 warnings, 0 failed"
+        },
+        "ltd": {
+          "hash": "5bb7be9b6d97",
+          "scorecard": "101605 passed, 0 warnings, 0 failed"
+        }
+      }
+    },
+    {
+      "tag": "diya-gl-v1.2.44",
+      "date": "2026-10-03",
+      "formatVersion": "diya-gl/1",
+      "engineVersion": "1.2.40+57de8f55b",
+      "taxDataHash": "89424bd36c0d",
+      "reconciledCommit": "54e8731a91279975e61b1a232fbb67fda89515f0",
+      "templates": {
+        "bst": {
+          "hash": "0d003e10e00c",
+          "scorecard": "812 passed, 0 warnings, 0 failed"
+        },
+        "taxi": {
+          "hash": "1ff69654d64d",
+          "scorecard": "700 passed, 0 warnings, 0 failed"
+        },
+        "se": {
+          "hash": "064605ae76ed",
+          "scorecard": "8014 passed, 0 warnings, 0 failed"
+        },
+        "ltd": {
+          "hash": "5bb7be9b6d97",
+          "scorecard": "101605 passed, 0 warnings, 0 failed"
+        }
+      }
     }
   ]
 }

package/dist/app/lib/book-queries.js

@@ -0,0 +1,297 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (C) 2006-2026 DIY Accounting Limited
+//
+// book-queries.js — read-only questions over a diya-gl book: which lines
+// match a filter and what they add up to, the chart of accounts with the
+// report rows each account feeds, the book's own profile, and the book
+// checks with the entryNumbers behind each verdict. Pure functions over
+// (book, lines) and the documents the engine already builds, so the MCP
+// server and any other caller read the same answers.
+
+import { isStraddlingLine } from "./scenario-extractor.js";
+
+function isoDate(value) {
+  if (!value) return "";
+  if (value instanceof Date) return value.toISOString().slice(0, 10);
+  return String(value).slice(0, 10);
+}
+
+// A TOML date parses to a Date; JSON would print it with a midnight time the
+// book never stated, so a date-only value goes out as YYYY-MM-DD.
+function plainValue(value) {
+  if (value instanceof Date) {
+    const iso = value.toISOString();
+    return iso.endsWith("T00:00:00.000Z") ? iso.slice(0, 10) : iso;
+  }
+  if (Array.isArray(value)) return value.map(plainValue);
+  if (value && typeof value === "object") {
+    return Object.fromEntries(Object.entries(value).map(([key, inner]) => [key, plainValue(inner)]));
+  }
+  return value;
+}
+
+function asSet(filter) {
+  if (filter === undefined || filter === null || filter === "") return null;
+  return new Set((Array.isArray(filter) ? filter : [filter]).map(String));
+}
+
+/**
+ * A line's amount in pence with the sign a total wants: a credit note
+ * reverses its sale or purchase, and a credit on the bank or the journal
+ * (debitCreditCode "C", money out of a bank account) is negative.
+ *
+ * A credit note on the bad debts account (4005) or the fixed asset sale
+ * account (4006) is negative here too. Both templates book a written-off
+ * debt as a negative sale: the Basic Sole Trader sales tabs have one gross
+ * column feeding turnover, and the Limited Company sales tabs' "Bad Debts
+ * written off" column T reaches the P&L negated (TrialBalance row 81 =
+ * -Sales!T1, MnthP&L B34), so only a negative entry raises the expense. A
+ * customer's total therefore falls by the debt written off against them.
+ * @param {Object} line
+ * @returns {number}
+ */
+export function signedPence(line) {
+  const reverses = (line.sourceJournalID === "sales" || line.sourceJournalID === "purchases") && line.documentType === "credit-note";
+  const pence = Math.round((Number(line.amount) || 0) * 100);
+  return reverses || line.debitCreditCode === "C" ? -pence : pence;
+}
+
+const GROUP_KEYS = {
+  detailComment: (line) => line.detailComment ?? "",
+  accountMainID: (line) => String(line.accountMainID ?? ""),
+  month: (line) => isoDate(line.postingDate).slice(0, 7),
+};
+
+/** The fields `lines` can group by. */
+export const LINE_GROUPINGS = Object.keys(GROUP_KEYS);
+
+function accountNames(book) {
+  const names = {};
+  for (const accounts of Object.values(book?.accounts || {})) {
+    for (const [id, account] of Object.entries(accounts || {})) names[id] = account?.accountMainDescription;
+  }
+  return names;
+}
+
+const byLargest = (a, b) => Math.abs(b.totalPence) - Math.abs(a.totalPence) || (a.key < b.key ? -1 : a.key > b.key ? 1 : 0);
+
+/**
+ * The lines matching every filter given, their count and signed total in
+ * pence, and either the lines themselves or their groups.
+ *
+ * Grouped by detailComment or accountMainID, groups come largest total
+ * first; by month, in date order. Ungrouped with `top`, lines come largest
+ * amount first; ungrouped without it, in book order.
+ * @param {Object} book
+ * @param {Array} lines
+ * @param {Object} [filters]
+ * @param {string|string[]} [filters.journal] - sourceJournalID
+ * @param {string|string[]} [filters.accountMainID]
+ * @param {string} [filters.from] - YYYY-MM-DD, inclusive
+ * @param {string} [filters.to] - YYYY-MM-DD, inclusive
+ * @param {string} [filters.text] - case-insensitive, in detailComment or lineItemComment
+ * @param {string} [filters.documentReference] - case-insensitive, in documentReference
+ * @param {string} [filters.groupBy] - one of LINE_GROUPINGS
+ * @param {number} [filters.top] - at most this many groups (or lines)
+ * @returns {Object}
+ */
+export function queryLines(book, lines, filters = {}) {
+  const { journal, accountMainID, from, to, text, documentReference, groupBy, top } = filters;
+  if (groupBy !== undefined && !GROUP_KEYS[groupBy]) {
+    throw new Error(`groupBy must be one of ${LINE_GROUPINGS.join(", ")}, got "${groupBy}"`);
+  }
+  if (top !== undefined && (!Number.isInteger(top) || top < 1)) throw new Error(`top must be a whole number above zero, got "${top}"`);
+  const journals = asSet(journal);
+  const accounts = asSet(accountMainID);
+  const needle = text ? String(text).toLowerCase() : null;
+  const reference = documentReference ? String(documentReference).toLowerCase() : null;
+
+  const matched = lines.filter((line) => {
+    if (journals && !journals.has(String(line.sourceJournalID))) return false;
+    if (accounts && !accounts.has(String(line.accountMainID))) return false;
+    const date = isoDate(line.postingDate);
+    if (from && date < from) return false;
+    if (to && date > to) return false;
+    if (needle && !`${line.detailComment ?? ""}\n${line.lineItemComment ?? ""}`.toLowerCase().includes(needle)) return false;
+    if (
+      reference &&
+      !String(line.documentReference ?? "")
+        .toLowerCase()
+        .includes(reference)
+    )
+      return false;
+    return true;
+  });
+
+  const answer = { count: matched.length, totalPence: matched.reduce((sum, line) => sum + signedPence(line), 0) };
+
+  if (!groupBy) {
+    const ordered = top
+      ? matched
+          .slice()
+          .sort((a, b) => Math.abs(signedPence(b)) - Math.abs(signedPence(a)))
+          .slice(0, top)
+      : matched;
+    return { ...answer, lines: ordered };
+  }
+
+  const keyOf = GROUP_KEYS[groupBy];
+  const groups = new Map();
+  for (const line of matched) {
+    const key = keyOf(line);
+    if (!groups.has(key)) groups.set(key, { key, count: 0, totalPence: 0, entryNumbers: [] });
+    const group = groups.get(key);
+    group.count += 1;
+    group.totalPence += signedPence(line);
+    group.entryNumbers.push(line.entryNumber);
+  }
+  const names = groupBy === "accountMainID" ? accountNames(book) : {};
+  let ordered = [...groups.values()].map((group) => (names[group.key] ? { ...group, name: names[group.key] } : group));
+  ordered.sort(groupBy === "month" ? (a, b) => (a.key < b.key ? -1 : a.key > b.key ? 1 : 0) : byLargest);
+  if (top) ordered = ordered.slice(0, top);
+  return { ...answer, groupBy, groups: ordered };
+}
+
+// A reconciliation table, not a line of the accounts: its rows restate
+// journal totals the account rows already carry.
+const NOT_A_REPORT_ROW = "section/journal-category-vat-netting/";
+
+// The rows with the least else in them, among those a test admits.
+function smallestRows(rows, admits) {
+  let best = [];
+  let bestSize = Infinity;
+  for (const row of rows) {
+    if (!admits(row)) continue;
+    const size = row.entries.size;
+    if (size < bestSize) {
+      best = [row];
+      bestSize = size;
+    } else if (size === bestSize) {
+      best.push(row);
+    }
+  }
+  return best;
+}
+
+// The report rows an account feeds: of the rows built from whole accounts
+// (every year line of each account they touch, so a month's or a debtor's
+// slice of an account does not count), the smallest that holds every year
+// line of this one. An account the engine splits across rows (a bank
+// account whose opening line sits apart from its movements) feeds instead
+// the smallest of the rows holding the most of its lines. Read off the
+// engine's own attribution rather than restated here. A VAT-straddling line
+// belongs to a return outside the year and reaches no row of the year's
+// accounts.
+function rowsFed(account, rows, entriesOfAccount, accountOfEntry) {
+  const own = entriesOfAccount.get(account);
+  if (!own || own.size === 0) return [];
+  const holdsAll = (row) => [...own].every((entry) => row.entries.has(entry));
+  const wholeAccounts = (row) =>
+    [...row.entries].every((entry) => {
+      const other = entriesOfAccount.get(accountOfEntry.get(entry));
+      return !other || [...other].every((otherEntry) => row.entries.has(otherEntry));
+    });
+  let best = smallestRows(rows, (row) => holdsAll(row) && wholeAccounts(row));
+  if (best.length === 0) {
+    const held = (row) => [...own].filter((entry) => row.entries.has(entry)).length;
+    const most = Math.max(0, ...rows.map(held));
+    if (most > 0) best = smallestRows(rows, (row) => held(row) === most);
+  }
+  return best.map((row) => ({ key: row.key, label: row.label }));
+}
+
+/**
+ * The book's chart of accounts: each account's id, name, group (the
+ * book.toml table it sits in), its other declared fields, how many lines
+ * post to it and their signed total in pence, and the report rows it feeds.
+ * @param {Object} book
+ * @param {Array} lines
+ * @param {Object} attributedReport - R built with entryNumbers on every figure
+ * @returns {Array<Object>}
+ */
+export function chartOfAccounts(book, lines, attributedReport) {
+  const rows = attributedReport.values
+    .filter((entry) => entry.key.startsWith("section/") && !entry.key.startsWith(NOT_A_REPORT_ROW) && entry.entryNumbers?.length > 0)
+    .map((entry) => ({ key: entry.key, label: entry.label, entries: new Set(entry.entryNumbers) }));
+  const accountOfEntry = new Map();
+  const entriesOfAccount = new Map();
+  for (const line of lines) {
+    if (isStraddlingLine(line)) continue;
+    const account = String(line.accountMainID);
+    accountOfEntry.set(line.entryNumber, account);
+    if (!entriesOfAccount.has(account)) entriesOfAccount.set(account, new Set());
+    entriesOfAccount.get(account).add(line.entryNumber);
+  }
+  const chart = [];
+  for (const [group, accounts] of Object.entries(book?.accounts || {})) {
+    for (const [id, account] of Object.entries(accounts || {})) {
+      const { accountMainDescription, ...declared } = account || {};
+      const posted = lines.filter((line) => String(line.accountMainID) === id);
+      chart.push({
+        id,
+        name: accountMainDescription ?? null,
+        group,
+        ...plainValue(declared),
+        lineCount: posted.length,
+        totalPence: posted.reduce((sum, line) => sum + signedPence(line), 0),
+        feeds: rowsFed(id, rows, entriesOfAccount, accountOfEntry),
+      });
+    }
+  }
+  return chart;
+}
+
+/**
+ * The book's own profile: product, period, the business, its tax settings,
+ * its bank accounts, the journals its lines are posted on, and every other
+ * table book.toml carries (registers, opening balances, stock).
+ * @param {Object} book
+ * @param {Array} lines
+ * @param {string} product - bst, taxi, se or ltd
+ * @returns {Object}
+ */
+export function bookProfile(book, lines, product) {
+  const { documentInfo, entityInformation, tax, accounts, ...registers } = book || {};
+  const journals = new Map();
+  for (const line of lines) {
+    const id = line.sourceJournalID;
+    const date = isoDate(line.postingDate);
+    if (!journals.has(id)) journals.set(id, { journal: id, count: 0, firstDate: date, lastDate: date });
+    const entry = journals.get(id);
+    entry.count += 1;
+    if (date < entry.firstDate) entry.firstDate = date;
+    if (date > entry.lastDate) entry.lastDate = date;
+  }
+  return {
+    product,
+    period: { start: isoDate(documentInfo?.periodCoveredStart), end: isoDate(documentInfo?.periodCoveredEnd) },
+    documentInfo: plainValue(documentInfo ?? {}),
+    entity: plainValue(entityInformation ?? {}),
+    tax: plainValue(tax ?? {}),
+    bankAccounts: Object.entries(accounts?.bank || {}).map(([id, account]) => ({
+      id,
+      name: account?.accountMainDescription ?? null,
+      ...plainValue(Object.fromEntries(Object.entries(account || {}).filter(([key]) => key !== "accountMainDescription"))),
+    })),
+    journals: [...journals.values()].sort((a, b) => (a.journal < b.journal ? -1 : 1)),
+    ...plainValue(registers),
+  };
+}
+
+/**
+ * The book checks and warnings with each one's verdict and the entryNumbers
+ * of the lines that fail it.
+ * @param {{results: Array, summary: Object}} bookChecks - runBookChecks() output
+ * @returns {{summary: Object, checks: Array<Object>}}
+ */
+export function checksWithEntries(bookChecks) {
+  return {
+    summary: bookChecks.summary,
+    checks: bookChecks.results.map(({ result, offenders, ...rest }) => ({
+      ...rest,
+      verdict: result,
+      entryNumbers: (offenders || []).map((offender) => offender.entryNumber).filter((entry) => entry !== undefined),
+      offenders: offenders || [],
+    })),
+  };
+}