@optique/man 0.10.0-dev.0

package/LICENSE

@@ -0,0 +1,20 @@
+MIT License
+
+Copyright 2025–2026 Hong Minhee
+
+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

@@ -0,0 +1,113 @@
+@optique/man
+============
+
+Man page generator for [Optique] CLI parsers.  This package generates Unix man
+pages from Optique's structured parser metadata, enabling automatic
+documentation generation that stays synchronized with your CLI's actual
+behavior.
+
+[Optique]: https://optique.dev/
+
+
+Installation
+------------
+
+::: code-group
+
+~~~~ bash [Deno]
+deno add jsr:@optique/man
+~~~~
+
+~~~~ bash [npm]
+npm add @optique/man
+~~~~
+
+~~~~ bash [pnpm]
+pnpm add @optique/man
+~~~~
+
+~~~~ bash [Yarn]
+yarn add @optique/man
+~~~~
+
+~~~~ bash [Bun]
+bun add @optique/man
+~~~~
+
+:::
+
+
+Quick start
+-----------
+
+~~~~ typescript
+import { generateManPage } from "@optique/man";
+import { object, option, argument } from "@optique/core/primitives";
+import { string, integer } from "@optique/core/valueparser";
+
+const parser = object({
+  port: option("-p", "--port", integer(), { description: "Port to listen on" }),
+  host: option("-h", "--host", string(), { description: "Host to bind to" }),
+});
+
+const manPage = generateManPage(parser, {
+  name: "myapp",
+  section: 1,
+  version: "1.0.0",
+  date: new Date(),
+});
+
+console.log(manPage);
+~~~~
+
+
+API
+---
+
+### Low-level: Message to roff conversion
+
+~~~~ typescript
+import { formatMessageAsRoff, escapeRoff } from "@optique/man/roff";
+import { message, optionName } from "@optique/core/message";
+
+// Escape special roff characters
+escapeRoff("Use .TH for title");  // "Use \\.TH for title"
+
+// Convert Message to roff
+const msg = message`Use ${optionName("--help")} for more info.`;
+formatMessageAsRoff(msg);  // "Use \\fB\\-\\-help\\fR for more info."
+~~~~
+
+### Mid-level: DocPage to man page
+
+~~~~ typescript
+import { formatDocPageAsMan } from "@optique/man/man";
+import type { DocPage } from "@optique/core/doc";
+
+const manPage = formatDocPageAsMan(docPage, {
+  name: "myapp",
+  section: 1,
+  version: "1.0.0",
+  author: message`Hong Minhee`,
+});
+~~~~
+
+### High-level: Parser to man page
+
+~~~~ typescript
+import { generateManPage } from "@optique/man";
+
+const manPage = generateManPage(parser, {
+  name: "myapp",
+  section: 1,
+  version: "1.0.0",
+});
+~~~~
+
+
+Documentation
+-------------
+
+See the [Optique documentation] for more information.
+
+[Optique documentation]: https://optique.dev/

package/dist/cli.cjs

@@ -0,0 +1,319 @@
+#!/usr/bin/env node
+const require_generator = require('./generator-DFTQgmHv.cjs');
+require('./roff-DzxoXJIL.cjs');
+require('./man-K9LPAprq.cjs');
+const __optique_core_constructs = require_generator.__toESM(require("@optique/core/constructs"));
+const __optique_core_primitives = require_generator.__toESM(require("@optique/core/primitives"));
+const __optique_core_valueparser = require_generator.__toESM(require("@optique/core/valueparser"));
+const __optique_core_modifiers = require_generator.__toESM(require("@optique/core/modifiers"));
+const __optique_core_message = require_generator.__toESM(require("@optique/core/message"));
+const __optique_core_program = require_generator.__toESM(require("@optique/core/program"));
+const __optique_run = require_generator.__toESM(require("@optique/run"));
+const node_fs = require_generator.__toESM(require("node:fs"));
+const node_fs_promises = require_generator.__toESM(require("node:fs/promises"));
+const node_path = require_generator.__toESM(require("node:path"));
+const node_process = require_generator.__toESM(require("node:process"));
+const node_url = require_generator.__toESM(require("node:url"));
+
+//#region deno.json
+var name = "@optique/man";
+var version = "0.10.0";
+var license = "MIT";
+var exports$1 = {
+	".": "./src/index.ts",
+	"./roff": "./src/roff.ts",
+	"./man": "./src/man.ts",
+	"./cli": "./src/cli.ts"
+};
+var imports = { "tsx/esm/api": "npm:tsx@^4.21.0/esm/api" };
+var exclude = ["dist/", "tsdown.config.ts"];
+var tasks = {
+	"build": "pnpm build",
+	"test": "deno test",
+	"test:node": {
+		"dependencies": ["build"],
+		"command": "node --experimental-transform-types --test"
+	},
+	"test:bun": {
+		"dependencies": ["build"],
+		"command": "bun test"
+	},
+	"test-all": { "dependencies": [
+		"test",
+		"test:node",
+		"test:bun"
+	] }
+};
+var deno_default = {
+	name,
+	version,
+	license,
+	exports: exports$1,
+	imports,
+	exclude,
+	tasks
+};
+
+//#endregion
+//#region src/cli.ts
+const EXIT_FILE_NOT_FOUND = 1;
+const EXIT_EXPORT_NOT_FOUND = 2;
+const EXIT_NOT_PROGRAM_OR_PARSER = 3;
+const EXIT_TSX_REQUIRED = 4;
+const EXIT_GENERATION_FAILED = 5;
+const EXIT_WRITE_FAILED = 6;
+const sectionValues = [
+	1,
+	2,
+	3,
+	4,
+	5,
+	6,
+	7,
+	8
+];
+/**
+* CLI program definition for optique-man.
+*/
+const cliProgram = (0, __optique_core_program.defineProgram)({
+	parser: (0, __optique_core_constructs.object)({
+		file: (0, __optique_core_primitives.argument)((0, __optique_core_valueparser.string)({ metavar: "FILE" }), { description: __optique_core_message.message`Path to a TypeScript or JavaScript file that exports
+a ${(0, __optique_core_message.metavar)("PROGRAM")} or ${(0, __optique_core_message.metavar)("PARSER")} to generate a man page from.` }),
+		section: (0, __optique_core_primitives.option)("-s", "--section", (0, __optique_core_valueparser.choice)(sectionValues, { metavar: "SECTION" }), { description: __optique_core_message.message`Man page section number (${"1"}-${"8"}). Common sections:
+
+  ${"1"}  User commands
+  ${"5"}  File formats
+  ${"8"}  System administration` }),
+		exportName: (0, __optique_core_modifiers.withDefault)((0, __optique_core_primitives.option)("-e", "--export", (0, __optique_core_valueparser.string)({ metavar: "NAME" }), { description: __optique_core_message.message`JavaScript export name to use. The export must be
+a ${(0, __optique_core_message.metavar)("PROGRAM")} (from ${(0, __optique_core_message.commandLine)("defineProgram()")}) or
+a ${(0, __optique_core_message.metavar)("PARSER")}. If not specified, the default export is used.` }), "default"),
+		output: (0, __optique_core_modifiers.optional)((0, __optique_core_primitives.option)("-o", "--output", (0, __optique_core_valueparser.string)({ metavar: "PATH" }), { description: __optique_core_message.message`Output file path. If not specified, the man page
+is written to stdout.` })),
+		name: (0, __optique_core_modifiers.optional)((0, __optique_core_primitives.option)("--name", (0, __optique_core_valueparser.string)({ metavar: "NAME" }), { description: __optique_core_message.message`Program name to use in the man page header.
+If not specified, inferred from the ${(0, __optique_core_message.metavar)("PROGRAM")} metadata
+or the input file name.` })),
+		date: (0, __optique_core_modifiers.optional)((0, __optique_core_primitives.option)("--date", (0, __optique_core_valueparser.string)({ metavar: "DATE" }), { description: __optique_core_message.message`Date to display in the man page footer.
+Defaults to the current date.` })),
+		versionString: (0, __optique_core_modifiers.optional)((0, __optique_core_primitives.option)("--version-string", (0, __optique_core_valueparser.string)({ metavar: "VERSION" }), { description: __optique_core_message.message`Version string for the man page footer
+(e.g., ${"MyApp 1.0.0"}). Overrides the version from
+${(0, __optique_core_message.metavar)("PROGRAM")} metadata if provided.` })),
+		manual: (0, __optique_core_modifiers.optional)((0, __optique_core_primitives.option)("--manual", (0, __optique_core_valueparser.string)({ metavar: "TITLE" }), { description: __optique_core_message.message`Manual name for the man page header
+(e.g., ${"User Commands"}).` }))
+	}),
+	metadata: {
+		name: "optique-man",
+		version: deno_default.version,
+		brief: __optique_core_message.message`Generate Unix man pages from Optique parsers`,
+		description: __optique_core_message.message`Generates a Unix man page from an Optique
+${(0, __optique_core_message.metavar)("PROGRAM")} or ${(0, __optique_core_message.metavar)("PARSER")} exported from a TypeScript
+or JavaScript file.
+
+The input file should export a ${(0, __optique_core_message.metavar)("PROGRAM")} (created with
+${(0, __optique_core_message.commandLine)("defineProgram()")}) or a ${(0, __optique_core_message.metavar)("PARSER")}. When using
+a ${(0, __optique_core_message.metavar)("PROGRAM")}, metadata like name, version, author, and examples
+are automatically extracted.`,
+		examples: __optique_core_message.message`Generate a man page for section ${"1"} (user commands):
+
+  ${(0, __optique_core_message.commandLine)("optique-man ./src/cli.ts -s 1")}
+
+Use a named export instead of the default export:
+
+  ${(0, __optique_core_message.commandLine)("optique-man ./src/cli.ts -s 1 -e myProgram")}
+
+Write output to a file:
+
+  ${(0, __optique_core_message.commandLine)("optique-man ./src/cli.ts -s 1 -o myapp.1")}
+
+Override the program name:
+
+  ${(0, __optique_core_message.commandLine)("optique-man ./src/cli.ts -s 1 --name myapp")}`,
+		bugs: __optique_core_message.message`Report bugs to: <https://github.com/dahlia/optique/issues>.`
+	}
+});
+/**
+* Gets the Node.js major and minor version numbers.
+* @returns A tuple of [major, minor] or null if not running on Node.js.
+*/
+function getNodeMajorMinor() {
+	if (typeof node_process.default === "undefined" || !node_process.default.versions?.node) return null;
+	const [major, minor] = node_process.default.versions.node.split(".").map(Number);
+	return [major, minor];
+}
+/**
+* Checks if Node.js natively supports TypeScript via type stripping.
+* Node.js 25.2.0+ has type stripping enabled by default.
+* @returns true if native TypeScript is supported.
+*/
+function nodeSupportsNativeTypeScript() {
+	const version$1 = getNodeMajorMinor();
+	if (version$1 == null) return false;
+	const [major, minor] = version$1;
+	return major > 25 || major === 25 && minor >= 2;
+}
+/**
+* Error handler for file not found.
+*/
+function fileNotFoundError(filePath) {
+	(0, __optique_run.printError)(__optique_core_message.message`File ${filePath} not found.
+
+Make sure the file path is correct and the file exists.`, { exitCode: EXIT_FILE_NOT_FOUND });
+}
+/**
+* Error handler for export not found.
+*/
+function exportNotFoundError(filePath, exportName, availableExports) {
+	const exportDisplay = exportName === "default" ? "default export" : `export ${exportName}`;
+	let suggestion;
+	if (availableExports.length > 0) suggestion = __optique_core_message.message`
+
+Available exports: ${availableExports.join(", ")}.
+Use ${(0, __optique_core_message.optionName)("-e")} to specify one of these exports.`;
+	else suggestion = __optique_core_message.message`
+
+The file has no exports. Make sure it exports a Program or Parser.`;
+	(0, __optique_run.printError)(__optique_core_message.message`No ${exportDisplay} found in ${filePath}.${suggestion}`, { exitCode: EXIT_EXPORT_NOT_FOUND });
+}
+/**
+* Error handler for invalid export type.
+*/
+function notProgramOrParserError(filePath, exportName, actualType) {
+	const exportDisplay = exportName === "default" ? "default export" : `export ${exportName}`;
+	(0, __optique_run.printError)(__optique_core_message.message`The ${exportDisplay} in ${filePath} is not a Program or Parser.
+
+Got type: ${actualType}
+
+The export should be created with ${(0, __optique_core_message.commandLine)("defineProgram()")} or be
+an Optique parser (e.g., from ${(0, __optique_core_message.commandLine)("object()")},
+${(0, __optique_core_message.commandLine)("command()")}, etc.).`, { exitCode: EXIT_NOT_PROGRAM_OR_PARSER });
+}
+/**
+* Error handler for missing tsx.
+*/
+function tsxRequiredError(filePath) {
+	const version$1 = getNodeMajorMinor();
+	const versionStr = version$1 ? `${version$1[0]}.${version$1[1]}` : "unknown";
+	(0, __optique_run.printError)(__optique_core_message.message`TypeScript file ${filePath} cannot be loaded on Node.js ${versionStr}.
+
+Install tsx as a dev dependency:
+
+  ${(0, __optique_core_message.commandLine)("npm install -D tsx")}
+
+Or upgrade to Node.js 25.2.0 or later, which supports TypeScript natively.
+
+Alternatively, use a pre-compiled JavaScript file instead.`, { exitCode: EXIT_TSX_REQUIRED });
+}
+/**
+* Error handler for man page generation failure.
+*/
+function generationError(error) {
+	(0, __optique_run.printError)(__optique_core_message.message`Failed to generate man page: ${error.message}`, { exitCode: EXIT_GENERATION_FAILED });
+}
+/**
+* Error handler for file write failure.
+*/
+function writeError(outputPath, error) {
+	(0, __optique_run.printError)(__optique_core_message.message`Failed to write to ${outputPath}: ${error.message}
+
+Make sure you have write permission and the parent directory exists.`, { exitCode: EXIT_WRITE_FAILED });
+}
+/**
+* Imports a module from the given file path.
+* Handles TypeScript files on Node.js by using tsx if needed.
+*/
+async function importModule(filePath) {
+	const absolutePath = (0, node_path.resolve)(filePath);
+	if (!(0, node_fs.existsSync)(absolutePath)) fileNotFoundError(filePath);
+	const isTypeScript = /\.[mc]?ts$/.test(filePath);
+	if (typeof globalThis.Deno !== "undefined") return await import(absolutePath);
+	if (typeof globalThis.Bun !== "undefined") return await import(absolutePath);
+	if (isTypeScript && !nodeSupportsNativeTypeScript()) try {
+		const tsx = await import("tsx/esm/api");
+		tsx.register();
+	} catch {
+		tsxRequiredError(filePath);
+	}
+	const fileUrl = (0, node_url.pathToFileURL)(absolutePath).href;
+	return await import(fileUrl);
+}
+/**
+* Checks if a value is a Program object.
+*/
+function isProgram(value) {
+	return value != null && typeof value === "object" && "parser" in value && "metadata" in value && typeof value.metadata === "object" && value.metadata != null;
+}
+/**
+* Checks if a value is a Parser object.
+*/
+function isParser(value) {
+	return value != null && typeof value === "object" && "parse" in value && typeof value.parse === "function" && "$mode" in value && "usage" in value;
+}
+/**
+* Infers the program name from a file path.
+*/
+function inferNameFromPath(filePath) {
+	const base = (0, node_path.basename)(filePath);
+	const ext = (0, node_path.extname)(base);
+	return base.slice(0, -ext.length);
+}
+/**
+* Gets available exports from a module.
+*/
+function getAvailableExports(mod) {
+	return Object.keys(mod).filter((key) => key !== "__esModule");
+}
+/**
+* Describes the type of a value for error messages.
+*/
+function describeType(value) {
+	if (value === null) return "null";
+	if (value === void 0) return "undefined";
+	if (Array.isArray(value)) return "array";
+	return typeof value;
+}
+/**
+* Main CLI entry point.
+*/
+async function main() {
+	const args = (0, __optique_run.runSync)(cliProgram, {
+		help: "option",
+		version: {
+			value: deno_default.version,
+			mode: "option"
+		}
+	});
+	const mod = await importModule(args.file);
+	const target = args.exportName === "default" ? mod.default : mod[args.exportName];
+	if (target === void 0) exportNotFoundError(args.file, args.exportName, getAvailableExports(mod));
+	if (!isProgram(target) && !isParser(target)) notProgramOrParserError(args.file, args.exportName, describeType(target));
+	const name$1 = args.name ?? (isProgram(target) ? target.metadata.name : null) ?? inferNameFromPath(args.file);
+	let manPage;
+	try {
+		if (isProgram(target)) manPage = await require_generator.generateManPageAsync(target, {
+			section: args.section,
+			name: args.name,
+			date: args.date,
+			version: args.versionString,
+			manual: args.manual
+		});
+		else manPage = await require_generator.generateManPageAsync(target, {
+			name: name$1,
+			section: args.section,
+			date: args.date,
+			version: args.versionString,
+			manual: args.manual
+		});
+	} catch (error) {
+		generationError(error instanceof Error ? error : new Error(String(error)));
+	}
+	if (args.output) try {
+		await (0, node_fs_promises.writeFile)(args.output, manPage, "utf-8");
+	} catch (error) {
+		writeError(args.output, error instanceof Error ? error : new Error(String(error)));
+	}
+	else console.log(manPage);
+}
+const isMain = "main" in import.meta ? void 0 : node_process.default.argv[1] === (0, node_url.fileURLToPath)(require("url").pathToFileURL(__filename).href);
+if (isMain) main();
+
+//#endregion
+exports.main = main;

package/dist/cli.d.cts

@@ -0,0 +1,7 @@
+//#region src/cli.d.ts
+/**
+ * Main CLI entry point.
+ */
+declare function main(): Promise<void>;
+//#endregion
+export { main };

package/dist/cli.d.ts

@@ -0,0 +1,7 @@
+//#region src/cli.d.ts
+/**
+ * Main CLI entry point.
+ */
+declare function main(): Promise<void>;
+//#endregion
+export { main };