@crustjs/man 0.1.1 → 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Chenxin Yan
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,11 +1,13 @@
 # @crustjs/man
 
-Generate **mdoc(7)** manual pages (section 1) from a Crust CLI definition.
+Generate mdoc(7) manual pages from Crust CLI definitions
 
-See the [Man module docs](https://crustjs.com/docs/modules/man) for install steps, `writeManPage`, `crust build --man`, and packaging notes.
+## Install
 
-## Roadmap (v2+)
+```sh
+bun add -d @crustjs/man
+```
 
-- Optional **one man page per subcommand** (or a mode switch)
-- Extra **meta** or sidecar content for long **DESCRIPTION**, **EXAMPLES**, **SEE ALSO**
-- **Subprocess**-based tree export when in-process `prepareCommandTree` is not enough
+## Documentation
+
+Full docs: [crustjs.com/docs/modules/man](https://crustjs.com/docs/modules/man)

package/dist/index.d.ts

@@ -1,44 +1,43 @@
-import { CommandNode } from "@crustjs/core";
+import { ExtensionFactory } from "@crustjs/core";
+import { CommandSnapshot } from "@crustjs/core/tooling";
+//#region src/extension.d.ts
+interface ManOptions {
+  /** Manual section. Defaults to 1. */
+  readonly section?: number;
+  /**
+   * Installed command name used for the page title and filename. Defaults to
+   * the application name; set it when `crust build --name` or the npm bin key
+   * installs the CLI under a different name.
+   */
+  readonly name?: string;
+}
+/** Adds build-time mdoc generation for the application. */
+export declare const man: ExtensionFactory<[options?: ManOptions]>;
+//#endregion
+//#region src/mdoc.d.ts
 interface RenderManPageMdocOptions {
-	/** Frozen root command node (e.g. from `prepareCommandTree()`). */
-	root: CommandNode;
-	/** Name shown in `man <name>` / `.Nm` (often matches the binary). */
-	name: string;
-	/** Manual section; user commands use `1`. */
-	section?: number;
-	/**
-	* Override the `.Dd` date (e.g. `"April 1, 2026"`). If omitted, uses
-	* `SOURCE_DATE_EPOCH` when set, otherwise today.
-	*/
-	date?: string;
+  /** Prepared, validated Command Snapshot for the CLI. */
+  root: CommandSnapshot;
+  /** Name for `.Nm` / `man <name>` (usually the installed binary name). */
+  name: string;
+  /**
+   * Manual section.
+   *
+   * @default 1
+   */
+  section?: number;
+  /** Override `.Dd` in the mdoc output (see `renderManPageMdoc` `date`). */
+  date?: string;
 }
-/**
-* Render an mdoc(7) manual page (section 1) for the root command tree.
-*/
-declare function renderManPageMdoc(options: RenderManPageMdocOptions): string;
-import { Crust } from "@crustjs/core";
-interface WriteManPageOptions {
-	/** Root Crust builder for your CLI. */
-	app: Crust;
-	/** Name for `.Nm` / `man <name>` (usually the installed binary name). */
-	name: string;
-	/** Output path (e.g. `man/mycli.1`). Parent directories are created. */
-	outfile: string;
-	/** Manual section; defaults to `1`. */
-	section?: number;
-	/** Override `.Dd` in the mdoc output (see `renderManPageMdoc` `date`). */
-	date?: string;
-	/** Synthetic argv passed to plugin `setup()`; defaults to `[]`. */
-	argv?: readonly string[];
-	/**
-	* When `true` (default), print plugin-setup warnings to `console.warn`.
-	* Set to `false` in tests or CI if you handle warnings yourself.
-	*/
-	logWarnings?: boolean;
+/** Render an mdoc(7) manual page for the root command. */
+export declare function renderManPageMdoc(options: RenderManPageMdocOptions): string;
+//#endregion
+//#region src/write-man-page.d.ts
+interface WriteManPageOptions extends RenderManPageMdocOptions {
+  /** Output path (e.g. `man/mycli.1`). Parent directories are created. */
+  outfile: string;
 }
-/**
-* Freeze and validate the command tree, render an mdoc(7) manual page, and
-* write it to `outfile`.
-*/
-declare function writeManPage(options: WriteManPageOptions): Promise<void>;
-export { writeManPage, renderManPageMdoc, WriteManPageOptions, RenderManPageMdocOptions };
+/** Render an mdoc(7) manual page from a Command Snapshot and write it to `outfile`. */
+export declare function writeManPage(options: WriteManPageOptions): Promise<void>;
+//#endregion
+export type { ManOptions, RenderManPageMdocOptions, WriteManPageOptions };

package/dist/index.js

@@ -1,10 +1,166 @@
-// @bun
-var C=["January","February","March","April","May","June","July","August","September","October","November","December"];function $(R){if(R.startsWith("."))return`\\&${R}`;return R}function F(R){if(typeof R==="number"&&!Number.isFinite(R))return String(R);if(Array.isArray(R))return R.map(String).join(", ");return JSON.stringify(R)}function T(R){return`[default: ${F(R)}]`}function w(R,P){if(P===void 0)return R??"";let q=T(P);if(!R)return q;return`${R} ${q}`}function M(R){let P=R.variadic?`${R.name}...`:R.name;return R.required?`<${P}>`:`[${P}]`}function D(R,P,q){if(R.usage)return R.usage;let j=[q.join(" ")];if(Object.keys(P.subCommands).length>0&&!P.run)j.push("<command>");if(P.args)for(let G of P.args)j.push(M(G));if(Object.keys(P.effectiveFlags).length>0)j.push("[options]");return j.join(" ")}function W(R,P){let q=[R];if(P.aliases)for(let G of P.aliases)q.push(G);let j=[];if(P.short)j.push(`-${P.short}`);for(let G of q)j.push(`--${G}`);if(P.type==="boolean"&&!P.noNegate)for(let G of q)j.push(`--no-${G}`);return j.join(", ")}function E(R){if(!R||R.length===0)return"";return`[choices: ${R.join(", ")}]`}function B(R,P,q){let j=w(R,P),G=E(q);if(!G)return j;if(!j)return G;return`${j} ${G}`}function V(R){return R.toUpperCase().replace(/[^A-Z0-9]+/g,"_").replace(/^_|_$/g,"")||"COMMAND"}function y(R){return R.replace(/\s+/g," ").trim()}function N(R){let P=y(R);if(P.startsWith("."))return`\\&${P}`;return P}function L(R){let P=8;for(let[q,j]of Object.entries(R))P=Math.max(P,W(q,j).length);return`${P}n`}function A(R,P){if(!P||P.length===0)return R;return`${R} (${P.join(", ")})`}function S(R){let P=8;for(let[q,j]of Object.entries(R.subCommands)){if(j.meta.hidden===!0)continue;let G=A(q,j.meta.aliases);P=Math.max(P,G.length)}return`${P}n`}function x(R){if(R)return R;let P=process.env.SOURCE_DATE_EPOCH;if(P!==void 0){let j=Number.parseInt(P,10);if(!Number.isNaN(j)&&j>=0){let G=new Date(j*1000);return`${C[G.getUTCMonth()]} ${G.getUTCDate()}, ${G.getUTCFullYear()}`}}let q=new Date;return`${C[q.getMonth()]} ${q.getDate()}, ${q.getFullYear()}`}function _(R){let{root:P,name:q,section:j=1,date:G}=R,z=x(G),O=[P.meta.name],U=D(P.meta,P,O),X=P.meta.description?.trim()||"No description provided.",I=[`.Dd ${z}`,`.Dt ${V(q)} ${j}`,".Os",".Sh NAME",`.Nm ${q}`,`.Nd ${N(X)}`,".Sh SYNOPSIS",".Bd -literal",U,".Ed",".Sh DESCRIPTION"];for(let J of X.split(`
-`))I.push($(J));let Y=Object.entries(P.subCommands).filter(([,J])=>J.meta.hidden!==!0);if(Y.length>0){I.push(".Sh SUBCOMMANDS"),I.push(`.Bl -tag -width ${S(P)}`);for(let[J,K]of Y.sort(([Q],[H])=>Q.localeCompare(H))){I.push(`.It Nm ${A(J,K.meta.aliases)}`);let Q=K.meta.description?.trim()||"";if(Q)I.push(Q.split(`
-`).map($).join(`
-`))}I.push(".El")}let Z=Object.entries(P.effectiveFlags).sort(([J],[K])=>J.localeCompare(K));if(Z.length>0){I.push(".Sh OPTIONS"),I.push(`.Bl -tag -width ${L(P.effectiveFlags)}`);for(let[J,K]of Z){let Q=W(J,K);I.push(`.It Sy ${Q}`);let H=K.type==="string"?K.choices:void 0,k=B(K.description,K.default,H).trim();if(k)I.push(k.split(`
-`).map($).join(`
-`))}I.push(".El")}if(P.args&&P.args.length>0){I.push(".Sh ARGUMENTS"),I.push(".Bl -tag -width 12n");for(let J of P.args){I.push(`.It Ql ${M(J)}`);let K=J.type==="string"?J.choices:void 0,Q=B(J.description,J.default,K).trim();if(Q)I.push(Q.split(`
-`).map($).join(`
-`))}I.push(".El")}return I.push(""),I.join(`
-`)}import{mkdirSync as v,writeFileSync as h}from"fs";import{dirname as p}from"path";async function g(R){let{app:P,name:q,outfile:j,section:G=1,date:z,argv:O,logWarnings:U=!0}=R,{root:X,warnings:I}=await P.prepareCommandTree({argv:O});if(U)for(let Z of I)console.warn(`Warning: ${Z}`);let Y=_({root:X,name:q,section:G,date:z});v(p(j),{recursive:!0}),h(j,Y,"utf8")}export{g as writeManPage,_ as renderManPageMdoc};
+import { dirname, join } from "node:path";
+import { defineExtension, defineExtensionId } from "@crustjs/core";
+import { buildCommandDocumentation, formatDescription, sectionsFor } from "@crustjs/core/tooling";
+import { mkdir, writeFile } from "node:fs/promises";
+//#region \0rolldown/runtime.js
+var __defProp = Object.defineProperty;
+var __exportAll = (all, no_symbols) => {
+	let target = {};
+	for (var name in all) __defProp(target, name, {
+		get: all[name],
+		enumerable: true
+	});
+	if (!no_symbols) __defProp(target, Symbol.toStringTag, { value: "Module" });
+	return target;
+};
+//#endregion
+//#region src/extension.ts
+const MAN = defineExtensionId("crust:man");
+/** Adds build-time mdoc generation for the application. */
+const man = defineExtension(MAN, (options = {}) => {
+	const section = options.section ?? 1;
+	return { async build({ snapshot, outDir }) {
+		const { writeManPage } = await Promise.resolve().then(() => write_man_page_exports);
+		const name = options.name ?? snapshot.meta.name;
+		if (/[\\/]/.test(name)) throw new Error(`Manual name "${name}" must not contain path separators.`);
+		const outfile = join("man", `${name}.${section}`);
+		await writeManPage({
+			root: snapshot,
+			name,
+			section,
+			outfile: join(outDir, outfile)
+		});
+		return [outfile];
+	} };
+});
+//#endregion
+//#region src/mdoc.ts
+function escapeMdocBodyLine(line) {
+	return /^[.']/.test(line) ? `\\&${line}` : line;
+}
+function macroArgument(text) {
+	return text.replace(/\\/g, "\\e");
+}
+function shTitle(title) {
+	return macroArgument(title.toUpperCase());
+}
+function dtTitle(name) {
+	return name.toUpperCase().replace(/[^A-Z0-9]+/g, "_").replace(/^_|_$/g, "") || "COMMAND";
+}
+function ndArgument(text) {
+	return escapeMdocBodyLine(text.replace(/\s+/g, " ").trim());
+}
+function flagMacro(spelling) {
+	return spelling.startsWith("--") ? `Fl Fl ${spelling.slice(2)}` : `Fl ${spelling.slice(1)}`;
+}
+function flagMacros(flag) {
+	return flag.spellings.map(flagMacro).join(" , ");
+}
+function commandLabel(command) {
+	return command.aliases.length === 0 ? command.name : `${command.name} (${command.aliases.join(", ")})`;
+}
+function commandSectionGroups(command) {
+	const groups = [];
+	function visit(node, path) {
+		const sections = [...sectionsFor(node.sections, MAN)];
+		if (sections.length > 0) groups.push({
+			path,
+			sections
+		});
+		for (const child of [...node.children].sort((a, b) => a.name.localeCompare(b.name))) visit(child, [...path, child.name]);
+	}
+	visit(command, []);
+	return groups;
+}
+function resolveDdLine(explicit) {
+	if (explicit) return explicit;
+	const sec = Number.parseInt(process.env.SOURCE_DATE_EPOCH ?? "", 10);
+	const fromEpoch = !Number.isNaN(sec) && sec >= 0;
+	return new Date(fromEpoch ? sec * 1e3 : Date.now()).toLocaleDateString("en-US", {
+		month: "long",
+		day: "numeric",
+		year: "numeric",
+		timeZone: fromEpoch ? "UTC" : void 0
+	});
+}
+/** Render an mdoc(7) manual page for the root command. */
+function renderManPageMdoc(options) {
+	const { root, name, section = 1, date } = options;
+	const model = buildCommandDocumentation(root);
+	const description = model.description?.trim() || "No description provided.";
+	const lines = [
+		`.Dd ${resolveDdLine(date)}`,
+		`.Dt ${dtTitle(name)} ${section}`,
+		".Os",
+		".Sh NAME",
+		`.Nm ${name}`,
+		`.Nd ${ndArgument(description)}`,
+		".Sh SYNOPSIS",
+		".Bd -literal",
+		model.usage,
+		".Ed",
+		".Sh DESCRIPTION"
+	];
+	for (const line of description.split("\n")) lines.push(escapeMdocBodyLine(line));
+	if (model.children.length > 0) {
+		lines.push(".Sh SUBCOMMANDS", `.Bl -tag -width ${Math.max(8, ...model.children.map((child) => commandLabel(child).length))}n`);
+		for (const child of [...model.children].sort((a, b) => a.name.localeCompare(b.name))) {
+			lines.push(`.It Nm ${commandLabel(child)}`);
+			if (child.description) lines.push(child.description.trim().split("\n").map(escapeMdocBodyLine).join("\n"));
+		}
+		lines.push(".El");
+	}
+	if (model.flags.length > 0) {
+		lines.push(".Sh OPTIONS", `.Bl -tag -width ${Math.max(8, ...model.flags.map((flag) => flag.spellings.join(", ").length))}n`);
+		for (const flag of [...model.flags].sort((a, b) => a.name.localeCompare(b.name))) {
+			lines.push(`.It ${flagMacros(flag)}`);
+			const body = formatDescription(flag.description, flag.default, flag.choices);
+			if (body) lines.push(body.split("\n").map(escapeMdocBodyLine).join("\n"));
+		}
+		lines.push(".El");
+	}
+	if (model.args.length > 0) {
+		lines.push(".Sh ARGUMENTS", ".Bl -tag -width 12n");
+		for (const arg of model.args) {
+			lines.push(`.It Ar ${arg.name}${arg.variadic ? " ..." : ""}`);
+			const body = formatDescription(arg.description, arg.default, arg.choices);
+			if (body) lines.push(body.split("\n").map(escapeMdocBodyLine).join("\n"));
+		}
+		lines.push(".El");
+	}
+	for (const metadataSection of sectionsFor(model.sections, MAN)) {
+		lines.push(`.Sh ${shTitle(metadataSection.title)}`);
+		for (const line of metadataSection.body.split("\n")) lines.push(escapeMdocBodyLine(line));
+	}
+	const commandSections = commandSectionGroups(model).filter(({ path }) => path.length > 0);
+	if (commandSections.length > 0) {
+		lines.push(".Sh COMMANDS");
+		for (const group of commandSections) {
+			lines.push(`.Ss ${macroArgument(group.path.join(" "))}`);
+			group.sections.forEach((commandSection, index) => {
+				if (index > 0) lines.push(".Pp");
+				lines.push(`.Sy ${shTitle(commandSection.title)}`);
+				for (const line of commandSection.body.split("\n")) lines.push(escapeMdocBodyLine(line));
+			});
+		}
+	}
+	lines.push("");
+	return lines.join("\n");
+}
+//#endregion
+//#region src/write-man-page.ts
+var write_man_page_exports = /* @__PURE__ */ __exportAll({ writeManPage: () => writeManPage });
+/** Render an mdoc(7) manual page from a Command Snapshot and write it to `outfile`. */
+async function writeManPage(options) {
+	const { root, name, outfile, section = 1, date } = options;
+	const mdoc = renderManPageMdoc({
+		root,
+		name,
+		section,
+		date
+	});
+	await mkdir(dirname(outfile), { recursive: true });
+	await writeFile(outfile, mdoc);
+}
+//#endregion
+export { man, renderManPageMdoc, writeManPage };

package/package.json

@@ -1,8 +1,9 @@
 {
 	"name": "@crustjs/man",
-	"version": "0.1.1",
+	"version": "0.2.0",
 	"description": "Generate mdoc(7) manual pages from Crust CLI definitions",
 	"type": "module",
+	"sideEffects": false,
 	"license": "MIT",
 	"author": "chenxin-yan",
 	"repository": {
@@ -27,28 +28,40 @@
 	],
 	"exports": {
 		".": {
-			"import": "./dist/index.js",
-			"types": "./dist/index.d.ts"
+			"types": "./dist/index.d.ts",
+			"import": "./dist/index.js"
 		}
 	},
 	"publishConfig": {
 		"access": "public"
 	},
 	"scripts": {
-		"build": "bunup",
-		"dev": "bunup --watch",
+		"build": "tsdown",
+		"dev": "tsdown --watch",
 		"check:types": "tsc --noEmit",
 		"test": "bun test",
-		"publish": "bun publish --no-git-checks || true"
+		"prepack": "cp ../../LICENSE LICENSE",
+		"postpack": "rm -f LICENSE"
 	},
 	"devDependencies": {
 		"@crustjs/config": "0.0.0",
-		"@crustjs/core": "0.0.18",
-		"@crustjs/plugins": "0.1.1",
-		"bunup": "^0.16.31"
+		"@crustjs/core": "0.2.0",
+		"@crustjs/extensions": "0.2.0",
+		"@crustjs/skills": "0.2.0",
+		"tsdown": "^0.23.0"
 	},
 	"peerDependencies": {
-		"@crustjs/core": "0.0.18",
-		"typescript": "^6.0.3"
+		"@crustjs/core": "^0.2.0",
+		"typescript": "^7.0.0"
+	},
+	"peerDependenciesMeta": {
+		"typescript": {
+			"optional": true
+		}
+	},
+	"engines": {
+		"bun": ">=1.3.14",
+		"node": ">=22",
+		"deno": ">=2.8"
 	}
 }