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

package/README.md

@@ -1,3 +1,14 @@
-# Temporary Holding Version
+# @dogsbay/dita-publish
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Publishing DITA through DITA-OT as a dogsbay site. Command: `dogsbay-dita`.
+
+```bash
+npx -y @dogsbay/dita-publish@beta publish-dita <dita-ot-temp-dir> -o site
+npx -y @dogsbay/dita-publish@beta dita dev -d <deliverable>
+```
+
+- `publishDitaTemp` (`src/publish.ts`): DITA-OT's preprocessed temp folder → pages, `nav.yml`, resources. Converts topics with `@dogsbay/format-dita`, through its `./publish-support` hooks.
+- `dogsbay-dita publish-dita` and `dogsbay-dita dita dev`: the commands that used to be in the `dogsbay` CLI. `dita dev` builds and serves the site with the `dogsbay` CLI's `site` commands.
+- `scripts/bundle-publish-dita.mjs` (repo only): the single-file converter the DITA-OT plugin `@dogsbay/dita-ot-plugin` carries.
+
+Usually you publish with the DITA-OT plugin (`dita -f dogsbay`), which carries this converter. See "Publishing DITA" in the dogsbay documentation.

package/bin/cli.js

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+import "../dist/cli.js";

package/dist/cli.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/cli.js

@@ -0,0 +1,24 @@
+/**
+ * `dogsbay-dita`: the DITA publishing commands (moved out of the `dogsbay` CLI,
+ * whose site commands `dita dev` drives).
+ *
+ *   dogsbay-dita publish-dita <temp-dir> -o <site>   DITA-OT temp folder → site project
+ *   dogsbay-dita dita dev [map] -d <deliverable>     live preview through DITA-OT
+ *
+ * The DITA-OT plugin com.dogsbay.publish runs `publish-dita` from its own
+ * single-file bundle (scripts/bundle-publish-dita.mjs), or from this script
+ * when given as `dogsbay.converter`, which is what `dita dev` passes.
+ */
+import { readFileSync } from "node:fs";
+import { Command } from "commander";
+import { registerPublishDita } from "./commands/publish-dita.js";
+import { registerDitaDev } from "./commands/dita-dev.js";
+const { version } = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf-8"));
+const program = new Command("dogsbay-dita").description("Publish DITA through DITA-OT as a dogsbay site").version(version);
+const cliFail = (error) => {
+    console.error(error instanceof Error ? error.message : String(error));
+    process.exitCode = 1;
+};
+registerPublishDita(program, cliFail);
+registerDitaDev(program, cliFail);
+await program.parseAsync(process.argv);

package/dist/commands/dita-dev.d.ts

@@ -0,0 +1,125 @@
+import type { Command } from "commander";
+import type { SiteDevOptions } from "dogsbay/lib";
+import { type DitaDeliverable } from "../dita/project-file.js";
+export interface DitaDevOptions {
+    /**
+     * The site project folder the map is published into. Default: the deliverable's
+     * output, else `site`.
+     */
+    output?: string;
+    /** DITA-OT installation folder (default: DITA_HOME, else `dita` on the PATH). */
+    ditaOt?: string;
+    /** A DITA-OT project file (default: the project files found in the current folder). */
+    project?: string;
+    /** The deliverable to publish: its name, or its context id. */
+    deliverable?: string;
+    /** DITAVAL files (DITA-OT's --filter); given, they replace the deliverable's. */
+    filter?: string[];
+    /** DITA-OT and plugin parameters, `name=value`; they override the deliverable's. */
+    param?: string[];
+    /** Folders or files to watch (default: the project folder, or the map's folder). */
+    watch?: string[];
+    /** Astro's --host: listen on all addresses. */
+    host?: boolean;
+    /** Listen on this address instead (Astro's --host <address>). */
+    hostAddress?: string;
+    /** Print all of DITA-OT's output, not only its errors. */
+    verbose?: boolean;
+}
+export declare const PLUGIN_ID = "com.dogsbay.publish";
+/** Where `dita` is, and the DITA-OT installation it belongs to. */
+export interface DitaLocation {
+    dita: string;
+    home: string;
+}
+/**
+ * Find DITA-OT's `dita` command: `--dita-ot`, else `DITA_HOME`, else `dita` on the
+ * PATH (its installation is the folder above `bin`, links resolved).
+ */
+export declare function findDita(ditaOt: string | undefined, env?: NodeJS.ProcessEnv): DitaLocation;
+/** Refuse a DITA-OT without the dogsbay plugin, saying how to install it. */
+export declare function checkPlugin(home: string): void;
+/** This CLI's script, which DITA-OT's plugin runs for the conversion (`dogsbay.converter`). */
+export declare function cliScript(argv?: readonly string[]): string | undefined;
+/** The transtypes whose output folder is a dogsbay site project. */
+export declare const DOGSBAY_TRANSTYPES: string[];
+/** What a preview publishes: the map, where, with which filters and parameters, and what to watch. */
+export interface PublishPlan {
+    /** The deliverable's name, or the map's file name. */
+    label: string;
+    map: string;
+    output: string;
+    filters: string[];
+    params: Record<string, string>;
+    watch: string[];
+    /** The deliverable, when one was used. */
+    deliverable?: DitaDeliverable;
+}
+/** `-p name=value` options as parameters. */
+export declare function parseParams(params: readonly string[] | undefined): Record<string, string>;
+/**
+ * Work out what to publish. With a map, the options say everything (output `site` by
+ * default). Otherwise a deliverable from the project files: the one `--deliverable`
+ * names, else the only one that publishes a dogsbay site. The deliverable gives the
+ * map, output folder, filters and parameters; `-o` and `--filter` replace its own, and
+ * `-p` overrides its parameters by name. The transtype is always `dogsbay`, so a
+ * deliverable of another transtype needs `-o`, or its output folder would be replaced.
+ */
+export declare function planPublish(map: string | undefined, options: DitaDevOptions, cwd?: string): PublishPlan;
+/** The `dita` arguments that publish a plan into its site project, with `dogsbay` whatever the deliverable's transtype. */
+export declare function ditaArgs(plan: Pick<PublishPlan, "map" | "output" | "filters" | "params">, cli: string | undefined): string[];
+/**
+ * Whether a change is not a source change: the site project's own files, version
+ * control, packages, DITA-OT's temp folder, editor backup and swap files.
+ */
+export declare function isIgnored(path: string, output: string, roots?: readonly string[]): boolean;
+/**
+ * Runs `publish` after changes settle for `delayMs`, never two at once: a change during
+ * a publish runs one more publish after it.
+ */
+export declare function createRepublisher(publish: () => Promise<unknown>, delayMs: number): {
+    schedule: () => void;
+    idle: () => Promise<void>;
+    close: () => void;
+};
+/** A publish's outcome: whether the site project was written, and DITA-OT's error lines. */
+export interface PublishResult {
+    ok: boolean;
+    errors: string[];
+    millis: number;
+}
+/** Run `dita` and collect its error lines; print everything with `verbose`. */
+/**
+ * An argument for a .bat run through cmd.exe: quoted whole, so `&`, `|`, `<`, `>`, `^` and parentheses
+ * stay literal. cmd has no escape for `"` inside quotes and expands `%NAME%` even there, so an argument
+ * holding either is refused rather than passed on altered.
+ */
+export declare function cmdArgument(arg: string): string;
+export declare function runDita(dita: string, args: string[], cwd: string, verbose: boolean): Promise<{
+    code: number;
+    errors: string[];
+}>;
+/** The steps `ditaDev` runs, replaceable in tests. */
+export interface DitaDevSteps {
+    publish: (args: string[]) => Promise<{
+        code: number;
+        errors: string[];
+    }>;
+    scaffold: (output: string) => Promise<void>;
+    serve: (output: string, options: SiteDevOptions) => Promise<void>;
+    watch: (paths: string[], ignored: (path: string) => boolean, onChange: () => void) => {
+        close: () => Promise<void> | void;
+    };
+    log: (line: string) => void;
+}
+/**
+ * Publish the map, serve the site with `site dev`, and publish again on every source
+ * change. Resolves when `site dev` ends (it exits the process when Astro stops).
+ */
+export declare function ditaDev(map: string | undefined, options: DitaDevOptions, steps?: Partial<DitaDevSteps>): Promise<void>;
+export declare function registerDitaDev(program: Command, fail: (error: unknown) => void): void;
+/** Print a project's deliverables: name, transtype, map, filters, output and parameters. */
+export declare function ditaDeliverables(options: {
+    project?: string;
+    json?: boolean;
+}, cwd?: string, log?: (line: string) => void): void;

package/dist/commands/dita-dev.js

@@ -0,0 +1,450 @@
+/**
+ * `dogsbay-dita dita dev <map>` — a live preview of a DITA map as a dogsbay site.
+ * (@dogsbay/dita-publish; the `dogsbay` CLI no longer has it.)
+ *
+ *   1. Publish the map with DITA-OT's `dita` command and the `dogsbay`
+ *      transtype (plugin com.dogsbay.publish), converting with this CLI.
+ *   2. Scaffold the site project when it has none, then run `site dev` on it
+ *      (package install on the first run, site build, content watcher,
+ *      `astro dev`).
+ *   3. Watch the DITA sources and publish again after a change; `site dev`
+ *      sees the changed Markdown, rebuilds and the page reloads.
+ *
+ * DogsBay XML runs the same loop with DITA-OT kept running in the editor
+ * (Project > Live Preview); here each publish starts Java, which adds a few
+ * seconds. Plan: plans/dita-dev-command.md.
+ */
+import { spawn, spawnSync } from "node:child_process";
+import { accessSync, constants, existsSync, realpathSync } from "node:fs";
+import { basename, delimiter, dirname, join, relative, resolve, sep } from "node:path";
+import chokidar from "chokidar";
+import pc from "picocolors";
+import { deliverableOutput, deliverableParams, findDeliverable, findProjectFiles, loadDeliverables, } from "../dita/project-file.js";
+export const PLUGIN_ID = "com.dogsbay.publish";
+const WINDOWS = process.platform === "win32";
+/**
+ * Find DITA-OT's `dita` command: `--dita-ot`, else `DITA_HOME`, else `dita` on the
+ * PATH (its installation is the folder above `bin`, links resolved).
+ */
+export function findDita(ditaOt, env = process.env) {
+    const script = WINDOWS ? "dita.bat" : "dita";
+    const home = ditaOt ?? env.DITA_HOME;
+    if (home) {
+        const dita = join(resolve(home), "bin", script);
+        if (!existsSync(dita)) {
+            throw new Error(`${resolve(home)} is not a DITA-OT installation (no bin/${script})`);
+        }
+        return { dita, home: resolve(home) };
+    }
+    const pathKey = Object.keys(env).find((k) => k.toUpperCase() === "PATH") ?? "PATH";
+    for (const folder of (env[pathKey] ?? "").split(delimiter)) {
+        if (!folder)
+            continue;
+        const candidate = join(folder, script);
+        try {
+            accessSync(candidate, WINDOWS ? constants.F_OK : constants.X_OK);
+        }
+        catch {
+            continue;
+        }
+        const real = realpathSync(candidate);
+        return { dita: candidate, home: dirname(dirname(real)) };
+    }
+    throw new Error("DITA-OT was not found: pass --dita-ot <folder>, set DITA_HOME, or put DITA-OT's bin folder on the PATH");
+}
+/** Refuse a DITA-OT without the dogsbay plugin, saying how to install it. */
+export function checkPlugin(home) {
+    if (!existsSync(join(home, "plugins", PLUGIN_ID))) {
+        throw new Error(`The DITA-OT at ${home} does not have the ${PLUGIN_ID} plugin. Install it with:\n` +
+            `  npx -y @dogsbay/dita-ot-plugin@beta install ${home}`);
+    }
+}
+/** This CLI's script, which DITA-OT's plugin runs for the conversion (`dogsbay.converter`). */
+export function cliScript(argv = process.argv) {
+    const script = argv[1];
+    if (!script)
+        return undefined;
+    // A global install, npx and node_modules/.bin run the CLI through a link without an extension
+    let real = resolve(script);
+    try {
+        real = realpathSync(real);
+    }
+    catch {
+        // not a file on disk: judge by the name
+    }
+    return /\.[cm]?js$/.test(real) ? real : undefined;
+}
+/** The transtypes whose output folder is a dogsbay site project. */
+export const DOGSBAY_TRANSTYPES = ["dogsbay", "dogsbay-site"];
+/** `-p name=value` options as parameters. */
+export function parseParams(params) {
+    const out = {};
+    for (const p of params ?? []) {
+        const eq = p.indexOf("=");
+        if (eq <= 0)
+            throw new Error(`--param needs name=value, not "${p}"`);
+        out[p.slice(0, eq)] = p.slice(eq + 1);
+    }
+    return out;
+}
+function listNames(deliverables) {
+    return deliverables.map((d) => `${d.name} (${d.transtype ?? "no transtype"})`).join(", ");
+}
+/**
+ * Work out what to publish. With a map, the options say everything (output `site` by
+ * default). Otherwise a deliverable from the project files: the one `--deliverable`
+ * names, else the only one that publishes a dogsbay site. The deliverable gives the
+ * map, output folder, filters and parameters; `-o` and `--filter` replace its own, and
+ * `-p` overrides its parameters by name. The transtype is always `dogsbay`, so a
+ * deliverable of another transtype needs `-o`, or its output folder would be replaced.
+ */
+export function planPublish(map, options, cwd = process.cwd()) {
+    const cliParams = parseParams(options.param);
+    const cliFilters = (options.filter ?? []).map((f) => resolve(cwd, f));
+    const watchOption = (options.watch ?? []).map((w) => resolve(cwd, w));
+    if (map !== undefined) {
+        if (options.deliverable)
+            throw new Error("Give a map or --deliverable, not both.");
+        const mapPath = resolve(cwd, map);
+        if (!existsSync(mapPath))
+            throw new Error(`No such map: ${map}`);
+        return {
+            label: basename(mapPath),
+            map: mapPath,
+            output: resolve(cwd, options.output ?? "site"),
+            filters: cliFilters,
+            params: cliParams,
+            watch: watchOption.length ? watchOption : [dirname(mapPath)],
+        };
+    }
+    // The project folder is where the command runs, as it is the editor's open folder: --project only
+    // names the file, so a deliverable without an output publishes to the same out/<name> either way
+    const root = cwd;
+    if (!options.project && findProjectFiles(root).length === 0) {
+        throw new Error(`Give a map, or a deliverable from a DITA-OT project file: none found in ${root} (use --project <file>).`);
+    }
+    const deliverables = loadDeliverables(root, options.project ? resolve(cwd, options.project) : undefined);
+    let d;
+    if (options.deliverable) {
+        d = findDeliverable(deliverables, options.deliverable);
+        if (!d) {
+            throw new Error(`No deliverable named "${options.deliverable}". Deliverables: ${listNames(deliverables) || "none"}.`);
+        }
+    }
+    else {
+        const sites = deliverables.filter((x) => DOGSBAY_TRANSTYPES.includes(x.transtype ?? ""));
+        if (sites.length !== 1) {
+            throw new Error((sites.length === 0 ? "No deliverable publishes a dogsbay site" : "Several deliverables publish a dogsbay site") +
+                `; name one with --deliverable, or give a map. Deliverables: ${listNames(deliverables) || "none"}.`);
+        }
+        d = sites[0];
+    }
+    if (!DOGSBAY_TRANSTYPES.includes(d.transtype ?? "") && !options.output) {
+        throw new Error(`The deliverable "${d.name}" publishes ${d.transtype ?? "no transtype"} to ${deliverableOutput(d, root)}; ` +
+            "give -o <folder> for the preview's site project, so that output is not replaced.");
+    }
+    const watch = watchOption.length ? watchOption : [root];
+    const mapFolder = dirname(d.map);
+    if (!watchOption.length && !mapFolder.startsWith(root + sep) && mapFolder !== root)
+        watch.push(mapFolder);
+    return {
+        label: d.name,
+        map: d.map,
+        output: options.output ? resolve(cwd, options.output) : deliverableOutput(d, root),
+        filters: cliFilters.length ? cliFilters : d.ditavals,
+        params: { ...deliverableParams(d), ...cliParams },
+        watch,
+        deliverable: d,
+    };
+}
+/** The `dita` arguments that publish a plan into its site project, with `dogsbay` whatever the deliverable's transtype. */
+export function ditaArgs(plan, cli) {
+    const args = ["-i", plan.map, "-f", "dogsbay", "-o", plan.output];
+    for (const filter of plan.filters)
+        args.push(`--filter=${filter}`);
+    // -D takes any property; --name=value only those a plugin declares, so a deliverable's own
+    // parameter would fail the publish with "unsupported argument"
+    for (const [name, value] of Object.entries(plan.params))
+        args.push(`-D${name}=${value}`);
+    if (cli && !("dogsbay.converter" in plan.params))
+        args.push(`-Ddogsbay.converter=${cli}`);
+    return args;
+}
+const IGNORED_FOLDERS = new Set([".git", ".svn", ".hg", "node_modules", ".dogsbay", ".astro", "temp"]);
+/**
+ * Whether a change is not a source change: the site project's own files, version
+ * control, packages, DITA-OT's temp folder, editor backup and swap files.
+ */
+export function isIgnored(path, output, roots = []) {
+    const abs = resolve(path);
+    const out = resolve(output);
+    if (abs === out || abs.startsWith(out + sep))
+        return true;
+    // Folder names count only inside a watched folder: a project under /home/u/temp must still be watched
+    const root = roots.map((r) => resolve(r)).find((r) => abs === r || abs.startsWith(r + sep));
+    const inside = root ? relative(root, abs) : abs;
+    if (inside.split(sep).some((part) => IGNORED_FOLDERS.has(part)))
+        return true;
+    const name = basename(abs);
+    return name.endsWith("~") || name.endsWith(".swp") || name.endsWith(".swo") || name.startsWith(".#") || name === ".DS_Store";
+}
+/**
+ * Runs `publish` after changes settle for `delayMs`, never two at once: a change during
+ * a publish runs one more publish after it.
+ */
+export function createRepublisher(publish, delayMs) {
+    let timer;
+    let running;
+    let dirty = false;
+    let closed = false;
+    const run = async () => {
+        timer = undefined;
+        if (running || closed)
+            return;
+        while (dirty && !closed) {
+            dirty = false;
+            running = Promise.resolve(publish()).then(() => undefined, () => undefined);
+            await running;
+            running = undefined;
+        }
+    };
+    return {
+        schedule() {
+            if (closed)
+                return;
+            dirty = true;
+            if (timer)
+                clearTimeout(timer);
+            timer = setTimeout(() => void run(), delayMs);
+        },
+        async idle() {
+            while (timer || running) {
+                if (running)
+                    await running;
+                else
+                    await new Promise((r) => setTimeout(r, 10));
+            }
+        },
+        close() {
+            closed = true;
+            if (timer)
+                clearTimeout(timer);
+            timer = undefined;
+        },
+    };
+}
+const ERROR_LINE = /\[(ERROR|FATAL)\]|^Error:|BUILD FAILED/;
+/** Run `dita` and collect its error lines; print everything with `verbose`. */
+/**
+ * An argument for a .bat run through cmd.exe: quoted whole, so `&`, `|`, `<`, `>`, `^` and parentheses
+ * stay literal. cmd has no escape for `"` inside quotes and expands `%NAME%` even there, so an argument
+ * holding either is refused rather than passed on altered.
+ */
+export function cmdArgument(arg) {
+    if (/["%]/.test(arg)) {
+        throw new Error(`Cannot pass ${JSON.stringify(arg)} to dita.bat: it contains " or %, which cmd.exe would change`);
+    }
+    return `"${arg}"`;
+}
+/** End a process and, on Windows, everything it started (cmd.exe runs dita.bat, which runs Java). */
+function killTree(child) {
+    if (child.exitCode !== null || child.pid === undefined)
+        return;
+    if (WINDOWS) {
+        spawnSync("taskkill", ["/T", "/F", "/PID", String(child.pid)], { stdio: "ignore" });
+    }
+    else {
+        child.kill();
+    }
+}
+export function runDita(dita, args, cwd, verbose) {
+    return new Promise((resolvePromise) => {
+        let child;
+        try {
+            child = (WINDOWS
+                // Node runs a .bat only through the shell, which joins the arguments as they are
+                ? spawn(`"${dita}" ${args.map(cmdArgument).join(" ")}`, { cwd, shell: true })
+                : spawn(dita, args, { cwd }));
+        }
+        catch (err) {
+            resolvePromise({ code: 1, errors: [err.message] });
+            return;
+        }
+        // DITA-OT's Java process must not outlive this command: not on a normal exit, and not when the
+        // command is stopped by a signal before the dev server (which handles signals itself) is running
+        const killOnExit = () => killTree(child);
+        const onSignal = (signal) => {
+            killTree(child);
+            process.exit(signal === "SIGINT" ? 130 : 143);
+        };
+        process.once("exit", killOnExit);
+        process.once("SIGINT", onSignal);
+        process.once("SIGTERM", onSignal);
+        const errors = [];
+        let pending = "";
+        const onData = (chunk) => {
+            pending += chunk.toString("utf-8");
+            const lines = pending.split(/\r?\n/);
+            pending = lines.pop() ?? "";
+            for (const line of lines) {
+                if (verbose)
+                    console.log(pc.dim(`[dita] ${line}`));
+                if (ERROR_LINE.test(line))
+                    errors.push(line.trim());
+            }
+        };
+        child.stdout.on("data", onData);
+        child.stderr.on("data", onData);
+        child.on("error", (err) => resolvePromise({ code: 1, errors: [`Could not run ${dita}: ${err.message}`] }));
+        child.on("close", (code) => {
+            process.off("exit", killOnExit);
+            process.off("SIGINT", onSignal);
+            process.off("SIGTERM", onSignal);
+            if (pending && ERROR_LINE.test(pending))
+                errors.push(pending.trim());
+            resolvePromise({ code: code ?? 1, errors });
+        });
+    });
+}
+function defaultSteps(location, cwd, verbose) {
+    return {
+        publish: (args) => location ? runDita(location.dita, args, cwd, verbose) : Promise.reject(new Error("DITA-OT was not located")),
+        scaffold: async (output) => (await import("dogsbay/lib")).siteInit(output, { yes: true, scaffoldOnly: true }),
+        serve: async (output, options) => (await import("dogsbay/lib")).siteDev(output, options),
+        watch: (paths, ignored, onChange) => {
+            const watcher = chokidar.watch(paths, {
+                ignoreInitial: true,
+                ignored: (path) => ignored(path),
+                awaitWriteFinish: { stabilityThreshold: 50, pollInterval: 10 },
+            });
+            watcher.on("all", () => onChange());
+            return watcher;
+        },
+        log: (line) => console.log(line),
+    };
+}
+/**
+ * Publish the map, serve the site with `site dev`, and publish again on every source
+ * change. Resolves when `site dev` ends (it exits the process when Astro stops).
+ */
+export async function ditaDev(map, options, steps) {
+    const cwd = process.cwd();
+    const plan = planPublish(map, options, cwd);
+    const output = plan.output;
+    // A replaced publish step (tests) needs no DITA-OT
+    const location = steps?.publish ? undefined : findDita(options.ditaOt);
+    if (location)
+        checkPlugin(location.home);
+    const all = { ...defaultSteps(location, cwd, !!options.verbose), ...steps };
+    const args = ditaArgs(plan, cliScript());
+    const shown = relative(cwd, output) || ".";
+    const publish = async () => {
+        const started = Date.now();
+        const { code, errors } = await all.publish(args);
+        const ok = code === 0 && existsSync(join(output, "content", "nav.yml"));
+        const millis = Date.now() - started;
+        for (const line of errors)
+            all.log(pc.red(`[dita] ${line}`));
+        if (ok) {
+            all.log(pc.green(`[dita] published ${plan.label} to ${shown} in ${(millis / 1000).toFixed(1)} s`) +
+                (errors.length ? pc.yellow(` with ${errors.length} error(s)`) : ""));
+        }
+        else {
+            all.log(pc.red(`[dita] publishing failed (exit ${code})`) +
+                (options.verbose ? "" : pc.dim("; --verbose shows DITA-OT's output")));
+        }
+        return { ok, errors, millis };
+    };
+    if (plan.deliverable) {
+        all.log(pc.cyan(`[dita] deliverable ${plan.deliverable.name}: ${relative(cwd, plan.map)}` +
+            (plan.filters.length ? `, filters ${plan.filters.map((f) => relative(cwd, f)).join(", ")}` : "") +
+            (Object.keys(plan.params).length ? `, ${Object.keys(plan.params).length} parameter(s)` : "")));
+    }
+    all.log(pc.cyan(`[dita] publishing ${plan.label} with DITA-OT...`));
+    const first = await publish();
+    if (!first.ok)
+        throw new Error("The first publish failed; nothing to serve.");
+    if (!existsSync(join(output, "astro", "package.json"))) {
+        all.log(pc.cyan("[dita] scaffolding the site"));
+        await all.scaffold(output);
+    }
+    const watched = plan.watch;
+    const republisher = createRepublisher(async () => {
+        all.log(pc.cyan("[dita] source changed — publishing..."));
+        await publish();
+    }, 500);
+    const watcher = all.watch(watched, (path) => isIgnored(path, output, watched), () => republisher.schedule());
+    all.log(pc.cyan(`[dita] watching ${watched.map((p) => relative(cwd, p) || ".").join(", ")} for DITA changes`));
+    try {
+        await all.serve(output, { host: options.hostAddress ?? options.host });
+    }
+    finally {
+        republisher.close();
+        await watcher.close();
+    }
+}
+export function registerDitaDev(program, fail) {
+    const dita = program.command("dita").description("Work with DITA sources published through DITA-OT");
+    dita
+        .command("dev")
+        .description("Live preview of a DITA map: publish it with DITA-OT (plugin com.dogsbay.publish), serve the site with site dev, and publish again when a source changes")
+        .argument("[map]", "The DITA map (or topic) to publish; omit to publish a deliverable")
+        .option("-d, --deliverable <name>", "Publish a deliverable from the project file: its map, filters, parameters and output folder")
+        .option("--project <file>", "DITA-OT project file (default: project files in the current folder, as DogsBay XML finds them)")
+        .option("-o, --output <dir>", "Site project folder (default: the deliverable's output, else site)")
+        .option("--dita-ot <dir>", "DITA-OT installation (default: DITA_HOME, else dita on the PATH)")
+        .option("--filter <ditaval>", "DITAVAL file (repeatable); replaces the deliverable's filters", (v, prev = []) => [...prev, v])
+        .option("-p, --param <name=value>", "DITA-OT or plugin parameter, such as args.gen.task.lbl=YES (repeatable); overrides the deliverable's", (v, prev = []) => [...prev, v])
+        .option("--watch <path>", "Folder or file to watch for changes (repeatable; default: the project folder, or the map's folder)", (v, prev = []) => [...prev, v])
+        .option("--host", "Listen on all addresses, for a container or remote machine")
+        .option("--host-address <address>", "Listen on this address")
+        .option("--verbose", "Print all of DITA-OT's output")
+        .action(async (map, options) => {
+        await ditaDev(map, options).catch(fail);
+    });
+    dita
+        .command("deliverables")
+        .description("List the deliverables in DITA-OT project files, as dita dev --deliverable uses them")
+        .option("--project <file>", "DITA-OT project file (default: project files in the current folder)")
+        .option("--json", "Print JSON")
+        .action((options) => {
+        try {
+            ditaDeliverables(options);
+        }
+        catch (err) {
+            fail(err);
+        }
+    });
+}
+/** Print a project's deliverables: name, transtype, map, filters, output and parameters. */
+export function ditaDeliverables(options, cwd = process.cwd(), log = console.log) {
+    const root = cwd;
+    const deliverables = loadDeliverables(root, options.project ? resolve(cwd, options.project) : undefined);
+    const rows = deliverables.map((d) => ({
+        name: d.name,
+        transtype: d.transtype ?? null,
+        map: relative(cwd, d.map),
+        filters: d.ditavals.map((f) => relative(cwd, f)),
+        output: relative(cwd, deliverableOutput(d, root)),
+        params: deliverableParams(d),
+        site: DOGSBAY_TRANSTYPES.includes(d.transtype ?? ""),
+        projectFile: relative(cwd, d.sourceFile),
+    }));
+    if (options.json) {
+        log(JSON.stringify({ deliverables: rows }, null, 2));
+        return;
+    }
+    if (rows.length === 0) {
+        log(`No deliverables in ${options.project ?? "the project files in " + root}.`);
+        return;
+    }
+    for (const r of rows) {
+        log(`${pc.bold(r.name)}  ${r.transtype ?? "(no transtype)"}${r.site ? pc.green("  dogsbay site") : ""}`);
+        log(`  map     ${r.map}`);
+        if (r.filters.length)
+            log(`  filters ${r.filters.join(", ")}`);
+        log(`  output  ${r.output}`);
+        for (const [name, value] of Object.entries(r.params))
+            log(`  param   ${name}=${value}`);
+    }
+}