@crustjs/man 0.0.2

package/README.md

@@ -0,0 +1,11 @@
+# @crustjs/man
+
+Generate **mdoc(7)** manual pages (section 1) from a Crust CLI definition.
+
+See the [Man module docs](https://crustjs.com/docs/modules/man) for install steps, `writeManPage`, `crust build --man`, and packaging notes.
+
+## Roadmap (v2+)
+
+- 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

package/dist/index.d.ts

@@ -0,0 +1,44 @@
+import { CommandNode } from "@crustjs/core";
+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;
+}
+/**
+* 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;
+}
+/**
+* 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 };

package/dist/index.js

@@ -0,0 +1,10 @@
+// @bun
+var W=["January","February","March","April","May","June","July","August","September","October","November","December"];function Z(j){if(j.startsWith("."))return`\\&${j}`;return j}function E(j){if(typeof j==="number"&&!Number.isFinite(j))return String(j);if(Array.isArray(j))return j.map(String).join(", ");return JSON.stringify(j)}function M(j){return`[default: ${E(j)}]`}function _(j,P){if(P===void 0)return j??"";let q=M(P);if(!j)return q;return`${j} ${q}`}function k(j){let P=j.variadic?`${j.name}...`:j.name;return j.required?`<${P}>`:`[${P}]`}function A(j,P,q){if(j.usage)return j.usage;let G=[q.join(" ")];if(Object.keys(P.subCommands).length>0&&!P.run)G.push("<command>");if(P.args)for(let K of P.args)G.push(k(K));if(Object.keys(P.effectiveFlags).length>0)G.push("[options]");return G.join(" ")}function B(j,P){let q=[];if(P.short)q.push(`-${P.short}`);if(q.push(`--${j}`),P.type==="boolean"&&!P.noNegate)q.push(`--no-${j}`);return q.join(", ")}function D(j){return j.toUpperCase().replace(/[^A-Z0-9]+/g,"_").replace(/^_|_$/g,"")||"COMMAND"}function F(j){return j.replace(/\s+/g," ").trim()}function T(j){let P=F(j);if(P.startsWith("."))return`\\&${P}`;return P}function V(j){let P=8;for(let[q,G]of Object.entries(j))P=Math.max(P,B(q,G).length);return`${P}n`}function w(j){let P=8;for(let q of Object.keys(j.subCommands))P=Math.max(P,q.length);return`${P}n`}function S(j){if(j)return j;let P=process.env.SOURCE_DATE_EPOCH;if(P!==void 0){let G=Number.parseInt(P,10);if(!Number.isNaN(G)&&G>=0){let K=new Date(G*1000);return`${W[K.getUTCMonth()]} ${K.getUTCDate()}, ${K.getUTCFullYear()}`}}let q=new Date;return`${W[q.getMonth()]} ${q.getDate()}, ${q.getFullYear()}`}function U(j){let{root:P,name:q,section:G=1,date:K}=j,$=S(K),z=[P.meta.name],O=A(P.meta,P,z),Q=P.meta.description?.trim()||"No description provided.",C=[`.Dd ${$}`,`.Dt ${D(q)} ${G}`,".Os",".Sh NAME",`.Nm ${q}`,`.Nd ${T(Q)}`,".Sh SYNOPSIS",".Bd -literal",O,".Ed",".Sh DESCRIPTION"];for(let I of Q.split(`
+`))C.push(Z(I));let R=Object.keys(P.subCommands);if(R.length>0){C.push(".Sh SUBCOMMANDS"),C.push(`.Bl -tag -width ${w(P)}`);for(let I of R.sort()){let J=P.subCommands[I];if(!J)continue;C.push(`.It Nm ${I}`);let Y=J.meta.description?.trim()||"";if(Y)C.push(Y.split(`
+`).map(Z).join(`
+`))}C.push(".El")}let X=Object.entries(P.effectiveFlags).sort(([I],[J])=>I.localeCompare(J));if(X.length>0){C.push(".Sh OPTIONS"),C.push(`.Bl -tag -width ${V(P.effectiveFlags)}`);for(let[I,J]of X){let Y=B(I,J);C.push(`.It Sy ${Y}`);let H=_(J.description,J.default).trim();if(H)C.push(H.split(`
+`).map(Z).join(`
+`))}C.push(".El")}if(P.args&&P.args.length>0){C.push(".Sh ARGUMENTS"),C.push(".Bl -tag -width 12n");for(let I of P.args){C.push(`.It Ql ${k(I)}`);let J=_(I.description,I.default).trim();if(J)C.push(J.split(`
+`).map(Z).join(`
+`))}C.push(".El")}return C.push(""),C.join(`
+`)}import{mkdirSync as y,writeFileSync as L}from"fs";import{dirname as N}from"path";async function h(j){let{app:P,name:q,outfile:G,section:K=1,date:$,argv:z,logWarnings:O=!0}=j,{root:Q,warnings:C}=await P.prepareCommandTree({argv:z});if(O)for(let X of C)console.warn(`Warning: ${X}`);let R=U({root:Q,name:q,section:K,date:$});y(N(G),{recursive:!0}),L(G,R,"utf8")}export{h as writeManPage,U as renderManPageMdoc};

package/package.json

@@ -0,0 +1,54 @@
+{
+	"name": "@crustjs/man",
+	"version": "0.0.2",
+	"description": "Generate mdoc(7) manual pages from Crust CLI definitions",
+	"type": "module",
+	"license": "MIT",
+	"author": "chenxin-yan",
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/chenxin-yan/crust.git",
+		"directory": "packages/man"
+	},
+	"homepage": "https://crustjs.com",
+	"bugs": {
+		"url": "https://github.com/chenxin-yan/crust/issues"
+	},
+	"keywords": [
+		"cli",
+		"crust",
+		"man",
+		"mdoc",
+		"documentation",
+		"bun"
+	],
+	"files": [
+		"dist"
+	],
+	"exports": {
+		".": {
+			"import": "./dist/index.js",
+			"types": "./dist/index.d.ts"
+		}
+	},
+	"publishConfig": {
+		"access": "public"
+	},
+	"scripts": {
+		"build": "bunup",
+		"dev": "bunup --watch",
+		"check:types": "tsc --noEmit",
+		"test": "bun test",
+		"publish": "bun publish --no-git-checks || true"
+	},
+	"devDependencies": {
+		"@crustjs/config": "0.0.0",
+		"@crustjs/core": "0.0.16",
+		"@crustjs/plugins": "0.0.21",
+		"bunup": "^0.16.31"
+	},
+	"peerDependencies": {
+		"@crustjs/core": "0.0.16",
+		"typescript": "^6.0.2"
+	}
+}