@dogsbay/dita-ot-plugin 0.0.0-stage → 0.2.0-beta.116

package/dist/com.dogsbay.publish/plugin.xml

@@ -0,0 +1,37 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+  com.dogsbay.publish: publish a DITA deliverable as a dogsbay site.
+
+  dogsbay       DITA-OT preprocessing, then the publish-dita converter on the
+                temp folder: content/*.md, content/nav.yml, dogsbay.config.yml.
+                The converter is converter/publish-dita.mjs (run with Node.js),
+                or the converter dogsbay.converter names.
+  dogsbay-site  dogsbay, then `dogsbay site build` and the Astro build:
+                HTML, .md copies, llms.txt, Pagefind search.
+
+  Conditions are resolved by DITA-OT with args.filter, as for any output.
+-->
+<plugin id="com.dogsbay.publish" version="0.2.0.beta-116">
+  <require plugin="org.dita.base"/>
+  <transtype name="dogsbay" desc="dogsbay site project (Markdown, navigation, site config)">
+    <param name="dogsbay.cli" desc="The dogsbay CLI that dogsbay-site runs for site init and site build: a command on the PATH, or an absolute path to its bin script (default: dogsbay)" type="string"/>
+    <param name="dogsbay.converter" desc="The publish-dita converter: a command on the PATH, or an absolute path to its script (default: the plugin's converter/publish-dita.mjs)" type="string"/>
+    <param name="dogsbay.node" desc="The Node.js executable that runs a script converter (default: node on the PATH)" type="file"/>
+    <param name="dogsbay.family.links" desc="Parent, previous and next topic links after each topic, as the html5 output has them (a dogsbay site has previous/next buttons and a sidebar)" type="enum">
+      <val>yes</val>
+      <val default="true">no</val>
+    </param>
+    <param name="dogsbay.numbering" desc="Number titled tables and figures (Table 1., Figure 1.) as the html5 output does" type="enum">
+      <val default="true">yes</val>
+      <val>no</val>
+    </param>
+  </transtype>
+  <transtype name="dogsbay-site" extends="dogsbay" desc="dogsbay site (Astro HTML, .md copies, llms.txt, search)">
+    <param name="dogsbay.site.install" desc="Install the site's npm dependencies before building" type="enum">
+      <val default="true">yes</val>
+      <val>no</val>
+    </param>
+    <param name="dogsbay.site.npm" desc="The package manager that installs and builds the site: npm (default), pnpm or yarn" type="string"/>
+  </transtype>
+  <feature extension="ant.import" file="build_dogsbay.xml"/>
+</plugin>

package/dist/com.dogsbay.publish-0.2.0-beta.116.zip.sha256

@@ -0,0 +1 @@
+2faf46eb73ab6e76711932d51847bef112d4be004590efcaf09ba257c15740c2  com.dogsbay.publish-0.2.0-beta.116.zip

package/lib/index.js

@@ -0,0 +1,61 @@
+/**
+ * The DITA-OT plugin com.dogsbay.publish, as built into this package's dist/,
+ * and installing it into a DITA-OT installation.
+ */
+import { spawnSync } from "node:child_process";
+import { cpSync, existsSync, readFileSync, rmSync, statSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+export const PLUGIN_ID = "com.dogsbay.publish";
+
+const packageRoot = join(dirname(fileURLToPath(import.meta.url)), "..");
+
+/** This package's version: the plugin's version. */
+export const version = JSON.parse(readFileSync(join(packageRoot, "package.json"), "utf-8")).version;
+
+/** The built plugin folder (dist/com.dogsbay.publish). */
+export const pluginDir = join(packageRoot, "dist", PLUGIN_ID);
+
+/** The built plugin zip, for `dita install <zip>`. */
+export const pluginZip = join(packageRoot, "dist", `${PLUGIN_ID}-${version}.zip`);
+
+/**
+ * Copy the plugin into a DITA-OT installation's plugins/ folder (replacing an
+ * earlier copy), then integrate it with DITA-OT's `dita install`.
+ *
+ * @param {string} ditaOt the DITA-OT installation folder
+ * @param {{ integrate?: boolean, run?: (command: string, args: string[], cwd: string) => number, from?: string }} [options]
+ *   integrate: run `dita install` (default true); run: runs the command and returns its exit
+ *   status (for tests); from: the plugin folder to install (default: this package's build)
+ * @returns {{ target: string, integrated: boolean }}
+ */
+export function installPlugin(ditaOt, options = {}) {
+  const home = resolve(ditaOt);
+  const from = options.from ?? pluginDir;
+  if (!existsSync(join(from, "plugin.xml"))) {
+    throw new Error(`The plugin is not built: ${from} has no plugin.xml (run the package's build)`);
+  }
+  if (!existsSync(home) || !statSync(home).isDirectory() || !existsSync(join(home, "plugins")) || !existsSync(join(home, "build.xml"))) {
+    throw new Error(`${home} is not a DITA-OT installation (no plugins/ folder and build.xml)`);
+  }
+  const target = join(home, "plugins", PLUGIN_ID);
+  rmSync(target, { recursive: true, force: true });
+  cpSync(from, target, { recursive: true });
+  if (options.integrate === false) return { target, integrated: false };
+
+  const windows = process.platform === "win32";
+  const dita = join(home, "bin", windows ? "dita.bat" : "dita");
+  if (!existsSync(dita)) {
+    throw new Error(`Copied the plugin to ${target}, but ${dita} is missing: integrate it with DITA-OT's installer`);
+  }
+  const run = options.run ?? ((command, args, cwd) =>
+    windows
+      // Node runs a .bat only through the shell, which joins arguments unquoted: quote the
+      // command so a DITA-OT path with spaces (C:\Program Files\...) stays one word
+      ? spawnSync(`"${command}" ${args.join(" ")}`, { cwd, stdio: "inherit", shell: true }).status ?? 1
+      : spawnSync(command, args, { cwd, stdio: "inherit" }).status ?? 1);
+  const status = run(dita, ["install"], home);
+  if (status !== 0) throw new Error(`dita install failed (exit ${status}); the plugin is in ${target}`);
+  return { target, integrated: true };
+}

package/lib/version.js

@@ -0,0 +1,20 @@
+/**
+ * The plugin.xml version for a package version. DITA-OT checks plugin versions against
+ * major.minor.micro[.qualifier], where the qualifier has no dots (PluginParser
+ * VERSION_PATTERN), so a pre-release `0.2.0-beta.116` becomes `0.2.0.beta-116`, and
+ * build metadata joins the qualifier (`1.0.0-rc.1+build.5` → `1.0.0.rc-1_build-5`).
+ * @param {string} version a semantic version
+ * @returns {string}
+ */
+export function pluginVersion(version) {
+  const match = /^(\d+\.\d+\.\d+)(?:-([^+]*))?(?:\+(.*))?$/.exec(version);
+  if (!match) throw new Error(`No DITA-OT plugin version for ${version}`);
+  const [, release, pre, build] = match;
+  const qualifier = [pre, build].filter(Boolean).join("+").replace(/\./g, "-").replace(/[^0-9A-Za-z_-]/g, "_");
+  const out = qualifier ? `${release}.${qualifier}` : release;
+  if (!DITA_OT_VERSION.test(out)) throw new Error(`No DITA-OT plugin version for ${version}`);
+  return out;
+}
+
+/** DITA-OT's plugin version pattern (org.dita.dost.platform.PluginParser.VERSION_PATTERN). */
+export const DITA_OT_VERSION = /^\d+(?:\.\d+(?:\.\d+(?:\.[0-9a-zA-Z_-]+)?)?)?$/;

package/lib/zip.js

@@ -0,0 +1,89 @@
+/**
+ * A minimal zip writer (deflate, no dependencies): enough for the plugin zip
+ * DITA-OT's `dita install` reads, without a `zip` binary on the build machine.
+ */
+import { deflateRawSync } from "node:zlib";
+
+const CRC_TABLE = (() => {
+  const table = new Uint32Array(256);
+  for (let n = 0; n < 256; n++) {
+    let c = n;
+    for (let k = 0; k < 8; k++) c = c & 1 ? 0xedb88320 ^ (c >>> 1) : c >>> 1;
+    table[n] = c >>> 0;
+  }
+  return table;
+})();
+
+const crc32 = (data) => {
+  let crc = 0xffffffff;
+  for (const byte of data) crc = CRC_TABLE[(crc ^ byte) & 0xff] ^ (crc >>> 8);
+  return (crc ^ 0xffffffff) >>> 0;
+};
+
+/** DOS date and time for 1980-01-01 00:00, so a build is reproducible. */
+const DOS_TIME = 0;
+const DOS_DATE = (1 << 5) | 1;
+
+/**
+ * A zip archive of `entries` ({ name, data }), in the order given. Folder
+ * entries are names ending in "/" with empty data.
+ * @param {Array<{ name: string, data: Buffer }>} entries
+ * @returns {Buffer}
+ */
+export function createZip(entries) {
+  // No ZIP64: the plugin is a handful of files, well inside these limits
+  if (entries.length > 0xffff) throw new Error("createZip: more than 65535 entries needs ZIP64");
+  const locals = [];
+  const centrals = [];
+  let offset = 0;
+  for (const { name, data } of entries) {
+    const nameBytes = Buffer.from(name, "utf-8");
+    const isDir = name.endsWith("/");
+    const compressed = isDir ? Buffer.alloc(0) : deflateRawSync(data);
+    const method = isDir ? 0 : 8;
+    const crc = isDir ? 0 : crc32(data);
+    const local = Buffer.alloc(30);
+    local.writeUInt32LE(0x04034b50, 0);
+    local.writeUInt16LE(20, 4);
+    local.writeUInt16LE(0x0800, 6); // UTF-8 names
+    local.writeUInt16LE(method, 8);
+    local.writeUInt16LE(DOS_TIME, 10);
+    local.writeUInt16LE(DOS_DATE, 12);
+    local.writeUInt32LE(crc, 14);
+    local.writeUInt32LE(compressed.length, 18);
+    local.writeUInt32LE(data.length, 22);
+    local.writeUInt16LE(nameBytes.length, 26);
+    local.writeUInt16LE(0, 28);
+    const central = Buffer.alloc(46);
+    central.writeUInt32LE(0x02014b50, 0);
+    central.writeUInt16LE(0x031e, 4); // made by Unix, zip 3.0
+    central.writeUInt16LE(20, 6);
+    central.writeUInt16LE(0x0800, 8);
+    central.writeUInt16LE(method, 10);
+    central.writeUInt16LE(DOS_TIME, 12);
+    central.writeUInt16LE(DOS_DATE, 14);
+    central.writeUInt32LE(crc, 16);
+    central.writeUInt32LE(compressed.length, 20);
+    central.writeUInt32LE(data.length, 24);
+    central.writeUInt16LE(nameBytes.length, 28);
+    central.writeUInt16LE(0, 30);
+    central.writeUInt16LE(0, 32);
+    central.writeUInt16LE(0, 34);
+    central.writeUInt16LE(0, 36);
+    // Unix permissions: folders 755, files 644
+    central.writeUInt32LE(((isDir ? 0o40755 : 0o100644) << 16) >>> 0, 38);
+    central.writeUInt32LE(offset, 42);
+    locals.push(local, nameBytes, compressed);
+    centrals.push(central, nameBytes);
+    offset += local.length + nameBytes.length + compressed.length;
+  }
+  const centralSize = centrals.reduce((n, b) => n + b.length, 0);
+  if (offset + centralSize > 0xffffffff) throw new Error("createZip: archives over 4 GB need ZIP64");
+  const end = Buffer.alloc(22);
+  end.writeUInt32LE(0x06054b50, 0);
+  end.writeUInt16LE(entries.length, 8);
+  end.writeUInt16LE(entries.length, 10);
+  end.writeUInt32LE(centralSize, 12);
+  end.writeUInt32LE(offset, 16);
+  return Buffer.concat([...locals, ...centrals, end]);
+}

package/package.json

@@ -1,6 +1,48 @@
 {
   "name": "@dogsbay/dita-ot-plugin",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.2.0-beta.116",
+  "description": "DITA-OT plugin com.dogsbay.publish: publish DITA as a dogsbay site (transtypes dogsbay and dogsbay-site)",
+  "type": "module",
+  "bin": {
+    "dogsbay-dita-ot-plugin": "./bin/cli.js"
+  },
+  "exports": {
+    ".": "./lib/index.js"
+  },
+  "files": [
+    "dist",
+    "bin",
+    "lib",
+    "README.md"
+  ],
+  "keywords": [
+    "dogsbay",
+    "dita",
+    "dita-ot",
+    "dita-ot-plugin",
+    "documentation"
+  ],
+  "devDependencies": {
+    "vitest": "^4.1.10",
+    "@dogsbay/dita-publish": "0.2.0-beta.116"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/dogsbay/dogsbay.git",
+    "directory": "packages/dita-ot-plugin"
+  },
+  "homepage": "https://github.com/dogsbay/dogsbay/tree/main/packages/dita-ot-plugin",
+  "bugs": {
+    "url": "https://github.com/dogsbay/dogsbay/issues"
+  },
+  "scripts": {
+    "build": "node scripts/build-plugin.mjs",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "smoke": "bash scripts/smoke.sh"
+  }
 }