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

package/README.md

@@ -38,11 +38,12 @@ diya-gl recalc --package bst --data my-book --years se-2025-2026 --output-dir ou
 diya-gl read-workbook --file my-workbook.xlsx --output-dir out
 diya-gl write-workbook --data my-book --output-dir out
 diya-gl link my-book
+diya-gl view my-book
 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-link`, `diya-gl-mcp`.
+`diya-gl-recalc`, `diya-gl-read-workbook`, `diya-gl-write-workbook`, `diya-gl-link`, `diya-gl-view`, `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
@@ -57,6 +58,15 @@ Each subcommand is also its own command, if you only want one on your `PATH`:
   opens it, the whole book carried in the fragment so nothing is uploaded. `--base <url>`
   replaces the origin. The fragment length goes to stderr, with a warning past 64 KB (about
   2,000 lines), where chat, email and QR codes start to cut links off.
+- **view** takes the same book sources as **link**, serves the full diya-gl pages on
+  `127.0.0.1` (`--port <number>`, default a free port) and opens the book in your default
+  browser (`--no-open` prints the address only). The pages are not in this package: the local
+  server fetches each file from https://diya-gl.co.uk on first use and caches it under the
+  system temporary directory, one directory per package version, so the first run needs the
+  network and later runs of the same version reuse the cache. `--origin <url>` fetches from
+  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.

package/bin/diya-gl-view.js

@@ -0,0 +1,9 @@
+#!/usr/bin/env node
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (C) 2006-2026 DIY Accounting Limited
+//
+// diya-gl-view.js — open a book in the full diya-gl pages, served locally
+// from this package.
+
+import { runDistBin } from "./run-dist-bin.js";
+runDistBin("app/bin/view.js", process.argv.slice(2));

package/bin/diya-gl.js

@@ -2,7 +2,7 @@
 // SPDX-License-Identifier: Apache-2.0
 // Copyright (C) 2006-2026 DIY Accounting Limited
 //
-// diya-gl.js — the dispatcher: diya-gl <recalc|read-workbook|write-workbook|link|mcp> [args].
+// diya-gl.js — the dispatcher: diya-gl <recalc|read-workbook|write-workbook|link|view|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.
 
@@ -17,6 +17,7 @@ const SUBCOMMANDS = {
   "read-workbook": "app/bin/export.js",
   "write-workbook": "app/bin/write-workbook.js",
   "link": "app/bin/link.js",
+  "view": "app/bin/view.js",
   "mcp": "app/bin/diya-gl-mcp.js",
 };
 

package/dist/app/bin/link.js

@@ -55,13 +55,17 @@ async function readBookText(source) {
   return { toml: canonicalBookToml(book), lines: canonicalLinesJsonl(lines), book };
 }
 
-export async function bookLink(source, base = DEFAULT_BASE) {
+export async function readBookFragment(source) {
   const { toml, lines, book } = await readBookText(source);
   const declared = book.entityInformation && book.entityInformation["diya-gl:product"];
   const product = productIdOf(declared);
   if (!product)
     throw new Error(`The book declares no product with a page: entityInformation."diya-gl:product" is ${JSON.stringify(declared)}.`);
-  const { fragment, length, warning } = encodeBookFragment({ toml, lines });
+  return { product, ...encodeBookFragment({ toml, lines }) };
+}
+
+export async function bookLink(source, base = DEFAULT_BASE) {
+  const { product, fragment, length, warning } = await readBookFragment(source);
   return { url: `${base}/${product}.html#${FRAGMENT_KEY}=${fragment}`, length, warning };
 }
 

package/dist/app/bin/view.js

@@ -0,0 +1,108 @@
+#!/usr/bin/env node
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (C) 2006-2026 DIY Accounting Limited
+//
+// view.js — open a book in the full diya-gl pages, served on 127.0.0.1 by a
+// caching proxy that fetches each page file from diya-gl.co.uk on first use.
+//
+// Usage:
+//   node app/bin/view.js examples/basic-taxi-driver
+//   node app/bin/view.js my-book-diya-gl.zip --port 8080 --no-open
+//
+// The book is any source link.js reads: a directory holding book.toml and
+// lines.jsonl, or a diya-gl zip, JSON or workbook file. The server stays up
+// until Ctrl-C. Fetched files are cached under the system temporary directory,
+// one directory per package version and origin host.
+
+import { spawn } from "child_process";
+import { existsSync, readFileSync } from "fs";
+import { tmpdir } from "os";
+import { dirname, join, resolve } from "path";
+import { fileURLToPath } from "url";
+import { readBookFragment } from "./link.js";
+import { FRAGMENT_KEY } from "../lib/diya-gl-link.js";
+import { DEFAULT_ORIGIN, startViewServer } from "../lib/diya-gl-view-server.js";
+
+const USAGE =
+  "Usage: diya-gl view <book directory | diya-gl zip | diya-gl JSON file | workbook> [--port <number>] [--origin <url>] [--no-open]";
+
+// The nearest package.json above this file: the package's own in dist/, the
+// repository's in a checkout. Both carry the version the cache is keyed on.
+function packageVersion() {
+  let directory = dirname(fileURLToPath(import.meta.url));
+  for (;;) {
+    const candidate = join(directory, "package.json");
+    if (existsSync(candidate)) return JSON.parse(readFileSync(candidate, "utf8")).version;
+    const parent = dirname(directory);
+    if (parent === directory) throw new Error("No package.json found above " + import.meta.url);
+    directory = parent;
+  }
+}
+
+function parseArgs(argv) {
+  const args = argv.slice(2);
+  let port = 0;
+  let origin = DEFAULT_ORIGIN;
+  let open = true;
+  const positional = [];
+  for (let i = 0; i < args.length; i++) {
+    if (args[i] === "--port") {
+      const value = args[++i];
+      port = Number(value);
+      if (!Number.isInteger(port) || port < 0 || port > 65535)
+        throw new Error(`--port needs a number from 0 to 65535, got "${value}". ${USAGE}`);
+    } else if (args[i] === "--origin") {
+      origin = args[++i];
+      let parsed;
+      try {
+        parsed = new URL(origin);
+      } catch {
+        throw new Error(`--origin needs an http or https URL, got "${origin}". ${USAGE}`);
+      }
+      if (parsed.protocol !== "http:" && parsed.protocol !== "https:")
+        throw new Error(`--origin needs an http or https URL, got "${origin}". ${USAGE}`);
+    } else if (args[i] === "--no-open") {
+      open = false;
+    } else {
+      positional.push(args[i]);
+    }
+  }
+  if (positional.length !== 1) throw new Error(USAGE);
+  return { source: positional[0], port, origin, open };
+}
+
+function openInBrowser(url) {
+  const [command, args] =
+    process.platform === "darwin"
+      ? ["open", [url]]
+      : process.platform === "win32"
+        ? ["cmd", ["/c", "start", "", url]]
+        : ["xdg-open", [url]];
+  const child = spawn(command, args, { stdio: "ignore", detached: true });
+  child.on("error", (error) => console.error(`Could not open a browser (${error.message}). Open the address above.`));
+  child.unref();
+}
+
+async function main() {
+  const { source, port, origin, open } = parseArgs(process.argv);
+  const { product, fragment, length, warning } = await readBookFragment(source);
+  const cacheDir = join(tmpdir(), "diya-gl-view", packageVersion(), new URL(origin).host.replace(/[^A-Za-z0-9.-]/g, "_"));
+  const running = await startViewServer({ cacheDir, origin, port });
+  const url = `http://${running.host}:${running.port}/${product}.html#${FRAGMENT_KEY}=${fragment}`;
+  console.log(url);
+  console.error(`Fragment length: ${length} characters`);
+  if (warning) console.error(`Warning: ${warning}`);
+  console.error(`Fetching pages from ${running.origin} on first use.`);
+  console.error(`Cache directory: ${running.cacheDir}`);
+  console.error("Serving on 127.0.0.1 until you press Ctrl-C.");
+  if (open) openInBrowser(url);
+
+  process.on("SIGINT", () => {
+    running.close().then(() => process.exit(0));
+  });
+}
+
+main().catch((error) => {
+  console.error(error.message);
+  process.exit(1);
+});

package/dist/app/data/releases.json

@@ -1325,6 +1325,32 @@
           "scorecard": "101605 passed, 0 warnings, 0 failed"
         }
       }
+    },
+    {
+      "tag": "diya-gl-v1.2.42",
+      "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/diya-gl-view-server.js

@@ -0,0 +1,203 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (C) 2006-2026 DIY Accounting Limited
+//
+// diya-gl-view-server.js — a read-only caching proxy on 127.0.0.1 for the
+// diya-gl pages. A GET or HEAD for /<path> is answered from the cache
+// directory when it holds the file; otherwise the file is fetched from the
+// origin site, stored with its content type, and served. A non-2xx answer
+// from the origin passes through with its status and is not stored.
+//
+// The pages are not part of the npm package: they are fetched from the site
+// on first use. The service worker script is answered 404, so the browser
+// never layers a second cache over this one.
+//
+// The workbook templates are fetched from the template source (the same site
+// the engine's own template loader uses) and streamed back unchanged.
+
+import { createServer } from "http";
+import { mkdir, readFile, realpath, rename, writeFile } from "fs/promises";
+import { extname, resolve, sep } from "path";
+
+export const DEFAULT_ORIGIN = "https://diya-gl.co.uk";
+export const DEFAULT_TEMPLATE_SOURCE = "https://spreadsheets.diyaccounting.co.uk/diya-gl/assets";
+const TEMPLATE_URL_PREFIX = "/assets/templates/";
+// A template is "meta.toml" or "<product>/<file>" with a workbook or TOML extension; nothing else
+// is proxied, so the upstream URL is always the template source plus one of these names.
+const TEMPLATE_NAME = /^(?:[a-z]+\/)?[A-Za-z0-9][A-Za-z0-9._-]*\.(?:xlsx|toml)$/;
+
+const CONTENT_TYPES = {
+  ".html": "text/html; charset=utf-8",
+  ".js": "text/javascript; charset=utf-8",
+  ".mjs": "text/javascript; charset=utf-8",
+  ".css": "text/css; charset=utf-8",
+  ".json": "application/json; charset=utf-8",
+  ".jsonl": "application/x-ndjson; charset=utf-8",
+  ".toml": "text/plain; charset=utf-8",
+  ".txt": "text/plain; charset=utf-8",
+  ".svg": "image/svg+xml",
+  ".png": "image/png",
+  ".ico": "image/x-icon",
+  ".webmanifest": "application/manifest+json",
+  ".xlsx": "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
+  ".zip": "application/zip",
+};
+
+function send(response, status, body, contentType = "text/plain; charset=utf-8") {
+  response.writeHead(status, { "Content-Type": contentType, "Cache-Control": "no-store", "X-Content-Type-Options": "nosniff" });
+  response.end(body);
+}
+
+const SERVICE_WORKER_PATH = "/sw.js";
+
+/**
+ * The cache entry paths for a URL path, or null when the path would leave the
+ * cache directory. The body and its content type are stored side by side.
+ */
+function cacheEntryFor(cacheReal, urlPath) {
+  let decoded;
+  try {
+    decoded = decodeURIComponent(urlPath);
+  } catch {
+    return null;
+  }
+  if (decoded.includes("\0") || decoded.includes("\\")) return null;
+  const segments = decoded.split("/").filter((segment) => segment !== "");
+  if (segments.some((segment) => segment === "." || segment === "..")) return null;
+  if (decoded.endsWith("/") || segments.length === 0) segments.push("index.html");
+  const body = resolve(cacheReal, "body", ...segments);
+  if (!body.startsWith(resolve(cacheReal, "body") + sep)) return null;
+  return { body, type: resolve(cacheReal, "type", ...segments) };
+}
+
+async function readIfPresent(path, cacheReal) {
+  try {
+    const real = await realpath(path);
+    if (!real.startsWith(cacheReal + sep)) return null;
+    return await readFile(real);
+  } catch (error) {
+    if (error.code === "ENOENT" || error.code === "ENOTDIR" || error.code === "EISDIR") return null;
+    throw error;
+  }
+}
+
+async function writeAtomically(path, data) {
+  await mkdir(resolve(path, ".."), { recursive: true });
+  const temporary = `${path}.${process.pid}.${Math.random().toString(36).slice(2)}.tmp`;
+  await writeFile(temporary, data);
+  await rename(temporary, path);
+}
+
+async function serveFromOrigin(request, response, { origin, cacheReal, urlPath, search }) {
+  const entry = cacheEntryFor(cacheReal, urlPath);
+  if (!entry) {
+    send(response, 404, "Not found\n");
+    return;
+  }
+  const cachedBody = await readIfPresent(entry.body, cacheReal);
+  const cachedType = cachedBody ? await readIfPresent(entry.type, cacheReal) : null;
+  if (cachedBody && cachedType) {
+    response.writeHead(200, {
+      "Content-Type": cachedType.toString("utf8"),
+      "Cache-Control": "no-store",
+      "X-Content-Type-Options": "nosniff",
+    });
+    response.end(request.method === "HEAD" ? undefined : cachedBody);
+    return;
+  }
+  const url = `${origin}${urlPath}${search}`;
+  let upstream;
+  try {
+    upstream = await fetch(url);
+  } catch (cause) {
+    send(response, 502, `${url} could not be fetched: ${cause.message}\n`);
+    return;
+  }
+  const body = Buffer.from(await upstream.arrayBuffer());
+  const contentType = upstream.headers.get("content-type") ?? "application/octet-stream";
+  if (!upstream.ok) {
+    send(response, upstream.status, request.method === "HEAD" ? undefined : body, contentType);
+    return;
+  }
+  await writeAtomically(entry.body, body);
+  await writeAtomically(entry.type, contentType);
+  send(response, 200, request.method === "HEAD" ? undefined : body, contentType);
+}
+
+async function proxyTemplate(response, templateSource, urlPath) {
+  const requested = urlPath.slice(TEMPLATE_URL_PREFIX.length);
+  const base = `${templateSource.replace(/\/$/, "")}/templates/`;
+  const url = TEMPLATE_NAME.test(requested) ? new URL(requested, base) : null;
+  if (!url || url.origin !== new URL(base).origin || !url.href.startsWith(base)) {
+    send(response, 404, "Not found\n");
+    return;
+  }
+  let upstream;
+  try {
+    upstream = await fetch(url);
+  } catch (cause) {
+    send(response, 502, `The workbook template could not be fetched from ${url.href}: ${cause.message}\n`);
+    return;
+  }
+  if (!upstream.ok) {
+    send(response, upstream.status === 404 ? 404 : 502, `${url.href} returned ${upstream.status}\n`);
+    return;
+  }
+  send(response, 200, Buffer.from(await upstream.arrayBuffer()), CONTENT_TYPES[extname(url.pathname)] ?? "application/octet-stream");
+}
+
+/**
+ * @param {Object} options
+ * @param {string} options.cacheDir - the directory fetched files are stored in; created when absent
+ * @param {string} [options.origin] - the site pages are fetched from
+ * @param {number} [options.port] - 0 or absent lets the OS choose a free port
+ * @param {string} [options.templateSource] - where /assets/templates/ requests are fetched from
+ * @returns {Promise<{server: import("http").Server, port: number, host: string, origin: string, cacheDir: string, close: () => Promise<void>}>}
+ */
+export async function startViewServer({ cacheDir, origin = DEFAULT_ORIGIN, port = 0, templateSource = DEFAULT_TEMPLATE_SOURCE }) {
+  await mkdir(cacheDir, { recursive: true });
+  const cacheReal = await realpath(cacheDir);
+  const host = "127.0.0.1";
+  const originBase = origin.replace(/\/$/, "");
+
+  const server = createServer(async (request, response) => {
+    try {
+      if (request.method !== "GET" && request.method !== "HEAD") {
+        send(response, 405, "Method not allowed\n");
+        return;
+      }
+      // The path as sent: new URL() would collapse dot segments before the escape check sees them.
+      const queryAt = request.url.indexOf("?");
+      const urlPath = queryAt === -1 ? request.url : request.url.slice(0, queryAt);
+      const search = queryAt === -1 ? "" : request.url.slice(queryAt);
+      if (!urlPath.startsWith("/") || urlPath === SERVICE_WORKER_PATH) {
+        send(response, 404, "Not found\n");
+        return;
+      }
+      if (urlPath.startsWith(TEMPLATE_URL_PREFIX)) {
+        await proxyTemplate(response, templateSource, urlPath);
+        return;
+      }
+      await serveFromOrigin(request, response, { origin: originBase, cacheReal, urlPath, search });
+    } catch (error) {
+      send(response, 500, `${error.message}\n`);
+    }
+  });
+
+  await new Promise((resolveListening, rejectListening) => {
+    server.once("error", rejectListening);
+    server.listen(port, host, resolveListening);
+  });
+
+  return {
+    server,
+    host,
+    origin: originBase,
+    cacheDir: cacheReal,
+    port: server.address().port,
+    close: () =>
+      new Promise((resolveClosed) => {
+        server.close(() => resolveClosed());
+        server.closeAllConnections();
+      }),
+  };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@diy-accounting-uk/diya-gl",
-  "version": "1.2.42",
+  "version": "1.2.43",
   "type": "module",
   "description": "Recalculate, read and write DIYA-GL books from the command line",
   "license": "Apache-2.0",
@@ -17,6 +17,7 @@
     "diya-gl-read-workbook": "bin/diya-gl-read-workbook.js",
     "diya-gl-write-workbook": "bin/diya-gl-write-workbook.js",
     "diya-gl-link": "bin/diya-gl-link.js",
+    "diya-gl-view": "bin/diya-gl-view.js",
     "diya-gl-mcp": "bin/diya-gl-mcp.js"
   },
   "files": ["bin/", "dist/", "README.md", "NOTICE"],