@optique/man 1.0.0-dev.896 → 1.0.0-dev.908

package/dist/cli.cjs

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
-const require_man = require('./man-DFKETOWN.cjs');
+const require_man = require('./man-NL-hVPdd.cjs');
 require('./roff-Cl0vekdg.cjs');
-const require_generator = require('./generator-Bal_ioLr.cjs');
+const require_generator = require('./generator-BORgW1yS.cjs');
 const __optique_core_constructs = require_man.__toESM(require("@optique/core/constructs"));
 const __optique_core_primitives = require_man.__toESM(require("@optique/core/primitives"));
 const __optique_core_valueparser = require_man.__toESM(require("@optique/core/valueparser"));
@@ -17,7 +17,7 @@ const node_url = require_man.__toESM(require("node:url"));
 
 //#region deno.json
 var name = "@optique/man";
-var version = "1.0.0-dev.896+5a811a7f";
+var version = "1.0.0-dev.908+f60f037d";
 var license = "MIT";
 var exports$1 = {
 	".": "./src/index.ts",

package/dist/cli.js

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 import "./roff-CwBRpWCo.js";
-import "./man-BBDifH_Y.js";
-import { generateManPageAsync } from "./generator-CdDVvD4r.js";
+import "./man-CcjsLpyb.js";
+import { generateManPageAsync } from "./generator-Di1pIRAG.js";
 import { object } from "@optique/core/constructs";
 import { argument, option } from "@optique/core/primitives";
 import { choice, string } from "@optique/core/valueparser";
@@ -17,7 +17,7 @@ import { fileURLToPath, pathToFileURL } from "node:url";
 
 //#region deno.json
 var name = "@optique/man";
-var version = "1.0.0-dev.896+5a811a7f";
+var version = "1.0.0-dev.908+f60f037d";
 var license = "MIT";
 var exports = {
 	".": "./src/index.ts",

package/dist/{generator-Bal_ioLr.cjs → generator-BORgW1yS.cjs}

@@ -1,18 +1,42 @@
-const require_man = require('./man-DFKETOWN.cjs');
+const require_man = require('./man-NL-hVPdd.cjs');
 const __optique_core_parser = require_man.__toESM(require("@optique/core/parser"));
 
 //#region src/generator.ts
 /**
+* Checks if the given value looks like a {@link Parser} at runtime.
+*/
+function isParser(value) {
+	try {
+		if (value == null || typeof value !== "object") return false;
+		const p = value;
+		return "parse" in p && typeof p.parse === "function" && "complete" in p && typeof p.complete === "function" && "$mode" in p && (p.$mode === "sync" || p.$mode === "async") && "usage" in p && Array.isArray(p.usage) && "initialState" in p && "suggest" in p && typeof p.suggest === "function" && "getDocFragments" in p && typeof p.getDocFragments === "function";
+	} catch {
+		return false;
+	}
+}
+/**
 * Checks if the given value is a {@link Program} object.
 */
 function isProgram(value) {
-	return typeof value === "object" && value !== null && "parser" in value && "metadata" in value;
+	try {
+		return typeof value === "object" && value !== null && "parser" in value && "metadata" in value && typeof value.metadata === "object" && value.metadata !== null && "name" in value.metadata && typeof value.metadata.name === "string";
+	} catch {
+		return false;
+	}
+}
+/**
+* Validates that the extracted parser is a genuine Optique parser.
+* @throws {TypeError} If the value is not a valid Parser.
+*/
+function validateParser(value) {
+	if (!isParser(value)) throw new TypeError("The given value is not a valid Parser or Program.");
 }
 /**
 * Extracts parser and merged options from a parser or program.
 */
 function extractParserAndOptions(parserOrProgram, options) {
 	if (isProgram(parserOrProgram)) {
+		validateParser(parserOrProgram.parser);
 		const { metadata } = parserOrProgram;
 		const programOptions = options;
 		return {
@@ -33,6 +57,7 @@ function extractParserAndOptions(parserOrProgram, options) {
 			}
 		};
 	}
+	validateParser(parserOrProgram);
 	return {
 		parser: parserOrProgram,
 		mergedOptions: options

package/dist/{generator-CdDVvD4r.js → generator-Di1pIRAG.js}

@@ -1,18 +1,42 @@
-import { formatDocPageAsMan } from "./man-BBDifH_Y.js";
+import { formatDocPageAsMan } from "./man-CcjsLpyb.js";
 import { getDocPageAsync, getDocPageSync } from "@optique/core/parser";
 
 //#region src/generator.ts
 /**
+* Checks if the given value looks like a {@link Parser} at runtime.
+*/
+function isParser(value) {
+	try {
+		if (value == null || typeof value !== "object") return false;
+		const p = value;
+		return "parse" in p && typeof p.parse === "function" && "complete" in p && typeof p.complete === "function" && "$mode" in p && (p.$mode === "sync" || p.$mode === "async") && "usage" in p && Array.isArray(p.usage) && "initialState" in p && "suggest" in p && typeof p.suggest === "function" && "getDocFragments" in p && typeof p.getDocFragments === "function";
+	} catch {
+		return false;
+	}
+}
+/**
 * Checks if the given value is a {@link Program} object.
 */
 function isProgram(value) {
-	return typeof value === "object" && value !== null && "parser" in value && "metadata" in value;
+	try {
+		return typeof value === "object" && value !== null && "parser" in value && "metadata" in value && typeof value.metadata === "object" && value.metadata !== null && "name" in value.metadata && typeof value.metadata.name === "string";
+	} catch {
+		return false;
+	}
+}
+/**
+* Validates that the extracted parser is a genuine Optique parser.
+* @throws {TypeError} If the value is not a valid Parser.
+*/
+function validateParser(value) {
+	if (!isParser(value)) throw new TypeError("The given value is not a valid Parser or Program.");
 }
 /**
 * Extracts parser and merged options from a parser or program.
 */
 function extractParserAndOptions(parserOrProgram, options) {
 	if (isProgram(parserOrProgram)) {
+		validateParser(parserOrProgram.parser);
 		const { metadata } = parserOrProgram;
 		const programOptions = options;
 		return {
@@ -33,6 +57,7 @@ function extractParserAndOptions(parserOrProgram, options) {
 			}
 		};
 	}
+	validateParser(parserOrProgram);
 	return {
 		parser: parserOrProgram,
 		mergedOptions: options

package/dist/index.cjs

@@ -1,6 +1,6 @@
-const require_man = require('./man-DFKETOWN.cjs');
+const require_man = require('./man-NL-hVPdd.cjs');
 const require_roff = require('./roff-Cl0vekdg.cjs');
-const require_generator = require('./generator-Bal_ioLr.cjs');
+const require_generator = require('./generator-BORgW1yS.cjs');
 
 exports.escapeHyphens = require_roff.escapeHyphens;
 exports.escapeQuotedValue = require_roff.escapeQuotedValue;

package/dist/index.d.cts

@@ -1,5 +1,5 @@
 import { escapeHyphens, escapeQuotedValue, escapeRequestArg, escapeRoff, formatMessageAsRoff } from "./roff-C_87xXP6.cjs";
-import { ManPageOptions, formatDateForMan, formatDocPageAsMan, formatUsageTermAsRoff } from "./man-xPX8GhXq.cjs";
+import { ManPageOptions, formatDateForMan, formatDocPageAsMan, formatUsageTermAsRoff } from "./man-D2t8hkyn.cjs";
 import { Mode, ModeValue, Parser } from "@optique/core/parser";
 import { Program } from "@optique/core/program";
 
@@ -48,9 +48,10 @@ interface GenerateManPageProgramOptions extends Partial<Omit<ManPageOptions, "se
  * console.log(manPage);
  * ```
  *
- * @param parser The parser to generate documentation from.
+ * @param parserOrProgram The parser or program to generate documentation from.
  * @param options The man page generation options.
  * @returns The complete man page in roff format.
+ * @throws {TypeError} If the input is not a valid Parser or Program.
  * @since 0.10.0
  */
 declare function generateManPageSync<T>(program: Program<"sync", T>, options: GenerateManPageProgramOptions): string;
@@ -78,9 +79,10 @@ declare function generateManPageSync(parser: Parser<"sync", unknown, unknown>, o
  * });
  * ```
  *
- * @param parser The parser to generate documentation from.
+ * @param parserOrProgram The parser or program to generate documentation from.
  * @param options The man page generation options.
  * @returns A promise that resolves to the complete man page in roff format.
+ * @throws {TypeError} If the input is not a valid Parser or Program.
  * @since 0.10.0
  */
 declare function generateManPageAsync<M extends Mode, T>(program: Program<M, T>, options: GenerateManPageProgramOptions): Promise<string>;
@@ -148,6 +150,7 @@ declare function generateManPageAsync<M extends Mode>(parser: Parser<M, unknown,
  * @param parserOrProgram The parser or program to generate documentation from.
  * @param options The man page generation options.
  * @returns The complete man page in roff format, or a Promise for async parsers.
+ * @throws {TypeError} If the input is not a valid Parser or Program.
  * @since 0.10.0
  */
 declare function generateManPage<T>(program: Program<"sync", T>, options: GenerateManPageProgramOptions): string;

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 import { escapeHyphens, escapeQuotedValue, escapeRequestArg, escapeRoff, formatMessageAsRoff } from "./roff-DlmeL3KB.js";
-import { ManPageOptions, formatDateForMan, formatDocPageAsMan, formatUsageTermAsRoff } from "./man-CGKLHWkS.js";
+import { ManPageOptions, formatDateForMan, formatDocPageAsMan, formatUsageTermAsRoff } from "./man-DXQgwt1g.js";
 import { Program } from "@optique/core/program";
 import { Mode, ModeValue, Parser } from "@optique/core/parser";
 
@@ -48,9 +48,10 @@ interface GenerateManPageProgramOptions extends Partial<Omit<ManPageOptions, "se
  * console.log(manPage);
  * ```
  *
- * @param parser The parser to generate documentation from.
+ * @param parserOrProgram The parser or program to generate documentation from.
  * @param options The man page generation options.
  * @returns The complete man page in roff format.
+ * @throws {TypeError} If the input is not a valid Parser or Program.
  * @since 0.10.0
  */
 declare function generateManPageSync<T>(program: Program<"sync", T>, options: GenerateManPageProgramOptions): string;
@@ -78,9 +79,10 @@ declare function generateManPageSync(parser: Parser<"sync", unknown, unknown>, o
  * });
  * ```
  *
- * @param parser The parser to generate documentation from.
+ * @param parserOrProgram The parser or program to generate documentation from.
  * @param options The man page generation options.
  * @returns A promise that resolves to the complete man page in roff format.
+ * @throws {TypeError} If the input is not a valid Parser or Program.
  * @since 0.10.0
  */
 declare function generateManPageAsync<M extends Mode, T>(program: Program<M, T>, options: GenerateManPageProgramOptions): Promise<string>;
@@ -148,6 +150,7 @@ declare function generateManPageAsync<M extends Mode>(parser: Parser<M, unknown,
  * @param parserOrProgram The parser or program to generate documentation from.
  * @param options The man page generation options.
  * @returns The complete man page in roff format, or a Promise for async parsers.
+ * @throws {TypeError} If the input is not a valid Parser or Program.
  * @since 0.10.0
  */
 declare function generateManPage<T>(program: Program<"sync", T>, options: GenerateManPageProgramOptions): string;

package/dist/index.js

@@ -1,5 +1,5 @@
 import { escapeHyphens, escapeQuotedValue, escapeRequestArg, escapeRoff, formatMessageAsRoff } from "./roff-CwBRpWCo.js";
-import { formatDateForMan, formatDocPageAsMan, formatUsageTermAsRoff } from "./man-BBDifH_Y.js";
-import { generateManPage, generateManPageAsync, generateManPageSync } from "./generator-CdDVvD4r.js";
+import { formatDateForMan, formatDocPageAsMan, formatUsageTermAsRoff } from "./man-CcjsLpyb.js";
+import { generateManPage, generateManPageAsync, generateManPageSync } from "./generator-Di1pIRAG.js";
 
 export { escapeHyphens, escapeQuotedValue, escapeRequestArg, escapeRoff, formatDateForMan, formatDocPageAsMan, formatMessageAsRoff, formatUsageTermAsRoff, generateManPage, generateManPageAsync, generateManPageSync };

package/dist/{man-BBDifH_Y.js → man-CcjsLpyb.js}

@@ -5,6 +5,12 @@ import { isDocHidden, isUsageHidden } from "@optique/core/usage";
 /**
 * Formats a date for use in man pages.
 *
+* When a `Date` object is given, the month and year are extracted using
+* the host's local timezone (`getMonth()` / `getFullYear()`).  This means
+* the same `Date` instant may produce different output on machines in
+* different timezones.  Pass a pre-formatted string (e.g., `"January 2026"`)
+* if you need timezone-independent output.
+*
 * @param date The date to format, or undefined.
 * @returns The formatted date string, or undefined.
 * @since 0.10.0
@@ -28,9 +34,6 @@ function formatDateForMan(date) {
 	];
 	return `${months[date.getMonth()]} ${date.getFullYear()}`;
 }
-function escapeThField(value) {
-	return value.replace(/\\/g, "\\\\").replace(/"/g, "\\\"");
-}
 function formatCommandNameAsRoff(name) {
 	return `\\fB${escapeHyphens(escapeRoff(name))}\\fR`;
 }
@@ -221,22 +224,22 @@ function formatDocPageAsMan(page, options) {
 		throw new RangeError(`Invalid man page section number (must be 1–8): ${repr}`);
 	}
 	const lines = [];
-	const thParts = [escapeHyphens(escapeThField(options.name).toUpperCase()), options.section.toString()];
+	const thParts = [`"${escapeHyphens(escapeRequestArg(options.name.toUpperCase()))}"`, options.section.toString()];
 	const hasDate = options.date != null && options.date !== "";
 	const hasVersion = options.version != null && options.version !== "";
 	const hasManual = options.manual != null && options.manual !== "";
-	if (hasDate) thParts.push(`"${escapeThField(formatDateForMan(options.date))}"`);
+	if (hasDate) thParts.push(`"${escapeRequestArg(formatDateForMan(options.date))}"`);
 	else if (hasVersion || hasManual) thParts.push("\"\"");
-	if (hasVersion) thParts.push(`"${escapeHyphens(escapeThField(options.name))} ${escapeThField(options.version)}"`);
+	if (hasVersion) thParts.push(`"${escapeHyphens(escapeRequestArg(options.name))} ${escapeRequestArg(options.version)}"`);
 	else if (hasManual) thParts.push("\"\"");
-	if (hasManual) thParts.push(`"${escapeThField(options.manual)}"`);
+	if (hasManual) thParts.push(`"${escapeRequestArg(options.manual)}"`);
 	lines.push(`.TH ${thParts.join(" ")}`);
 	lines.push(".SH NAME");
 	if (page.brief) lines.push(`${escapeHyphens(escapeRoff(options.name))} \\- ${formatMessageAsRoff(page.brief)}`);
 	else lines.push(escapeHyphens(escapeRoff(options.name)));
 	if (page.usage) {
 		lines.push(".SH SYNOPSIS");
-		lines.push(`.B ${escapeHyphens(escapeRoff(options.name))}`);
+		lines.push(`.B "${escapeHyphens(escapeRequestArg(options.name))}"`);
 		const usageStr = formatUsageAsRoff(page.usage);
 		if (usageStr) lines.push(usageStr);
 	}
@@ -285,7 +288,7 @@ function formatDocPageAsMan(page, options) {
 		lines.push(".SH SEE ALSO");
 		const refs = options.seeAlso.map((ref, i) => {
 			const suffix = i < options.seeAlso.length - 1 ? "," : "";
-			return `.BR ${escapeHyphens(escapeRoff(ref.name))} (${ref.section})${suffix}`;
+			return `.BR "${escapeHyphens(escapeRequestArg(ref.name))}" (${ref.section})${suffix}`;
 		});
 		lines.push(refs.join("\n"));
 	}

package/dist/{man-xPX8GhXq.d.cts → man-D2t8hkyn.d.cts}

@@ -32,7 +32,9 @@ interface ManPageOptions {
   readonly section: ManPageSection;
   /**
    * The date to display in the man page footer.
-   * If a Date object is provided, it will be formatted as "Month Year".
+   * If a `Date` object is provided, it will be formatted as `"Month Year"`
+   * using the host's local timezone.  For timezone-independent output (e.g.,
+   * in CI), pass a pre-formatted string instead.
    * If a string is provided, it will be used as-is.
    */
   readonly date?: string | Date;
@@ -80,6 +82,12 @@ interface ManPageOptions {
 /**
  * Formats a date for use in man pages.
  *
+ * When a `Date` object is given, the month and year are extracted using
+ * the host's local timezone (`getMonth()` / `getFullYear()`).  This means
+ * the same `Date` instant may produce different output on machines in
+ * different timezones.  Pass a pre-formatted string (e.g., `"January 2026"`)
+ * if you need timezone-independent output.
+ *
  * @param date The date to format, or undefined.
  * @returns The formatted date string, or undefined.
  * @since 0.10.0

package/dist/{man-CGKLHWkS.d.ts → man-DXQgwt1g.d.ts}

@@ -32,7 +32,9 @@ interface ManPageOptions {
   readonly section: ManPageSection;
   /**
    * The date to display in the man page footer.
-   * If a Date object is provided, it will be formatted as "Month Year".
+   * If a `Date` object is provided, it will be formatted as `"Month Year"`
+   * using the host's local timezone.  For timezone-independent output (e.g.,
+   * in CI), pass a pre-formatted string instead.
    * If a string is provided, it will be used as-is.
    */
   readonly date?: string | Date;
@@ -80,6 +82,12 @@ interface ManPageOptions {
 /**
  * Formats a date for use in man pages.
  *
+ * When a `Date` object is given, the month and year are extracted using
+ * the host's local timezone (`getMonth()` / `getFullYear()`).  This means
+ * the same `Date` instant may produce different output on machines in
+ * different timezones.  Pass a pre-formatted string (e.g., `"January 2026"`)
+ * if you need timezone-independent output.
+ *
  * @param date The date to format, or undefined.
  * @returns The formatted date string, or undefined.
  * @since 0.10.0

package/dist/{man-DFKETOWN.cjs → man-NL-hVPdd.cjs}

@@ -28,6 +28,12 @@ const __optique_core_usage = __toESM(require("@optique/core/usage"));
 /**
 * Formats a date for use in man pages.
 *
+* When a `Date` object is given, the month and year are extracted using
+* the host's local timezone (`getMonth()` / `getFullYear()`).  This means
+* the same `Date` instant may produce different output on machines in
+* different timezones.  Pass a pre-formatted string (e.g., `"January 2026"`)
+* if you need timezone-independent output.
+*
 * @param date The date to format, or undefined.
 * @returns The formatted date string, or undefined.
 * @since 0.10.0
@@ -51,9 +57,6 @@ function formatDateForMan(date) {
 	];
 	return `${months[date.getMonth()]} ${date.getFullYear()}`;
 }
-function escapeThField(value) {
-	return value.replace(/\\/g, "\\\\").replace(/"/g, "\\\"");
-}
 function formatCommandNameAsRoff(name) {
 	return `\\fB${require_roff.escapeHyphens(require_roff.escapeRoff(name))}\\fR`;
 }
@@ -244,22 +247,22 @@ function formatDocPageAsMan(page, options) {
 		throw new RangeError(`Invalid man page section number (must be 1–8): ${repr}`);
 	}
 	const lines = [];
-	const thParts = [require_roff.escapeHyphens(escapeThField(options.name).toUpperCase()), options.section.toString()];
+	const thParts = [`"${require_roff.escapeHyphens(require_roff.escapeRequestArg(options.name.toUpperCase()))}"`, options.section.toString()];
 	const hasDate = options.date != null && options.date !== "";
 	const hasVersion = options.version != null && options.version !== "";
 	const hasManual = options.manual != null && options.manual !== "";
-	if (hasDate) thParts.push(`"${escapeThField(formatDateForMan(options.date))}"`);
+	if (hasDate) thParts.push(`"${require_roff.escapeRequestArg(formatDateForMan(options.date))}"`);
 	else if (hasVersion || hasManual) thParts.push("\"\"");
-	if (hasVersion) thParts.push(`"${require_roff.escapeHyphens(escapeThField(options.name))} ${escapeThField(options.version)}"`);
+	if (hasVersion) thParts.push(`"${require_roff.escapeHyphens(require_roff.escapeRequestArg(options.name))} ${require_roff.escapeRequestArg(options.version)}"`);
 	else if (hasManual) thParts.push("\"\"");
-	if (hasManual) thParts.push(`"${escapeThField(options.manual)}"`);
+	if (hasManual) thParts.push(`"${require_roff.escapeRequestArg(options.manual)}"`);
 	lines.push(`.TH ${thParts.join(" ")}`);
 	lines.push(".SH NAME");
 	if (page.brief) lines.push(`${require_roff.escapeHyphens(require_roff.escapeRoff(options.name))} \\- ${require_roff.formatMessageAsRoff(page.brief)}`);
 	else lines.push(require_roff.escapeHyphens(require_roff.escapeRoff(options.name)));
 	if (page.usage) {
 		lines.push(".SH SYNOPSIS");
-		lines.push(`.B ${require_roff.escapeHyphens(require_roff.escapeRoff(options.name))}`);
+		lines.push(`.B "${require_roff.escapeHyphens(require_roff.escapeRequestArg(options.name))}"`);
 		const usageStr = formatUsageAsRoff(page.usage);
 		if (usageStr) lines.push(usageStr);
 	}
@@ -308,7 +311,7 @@ function formatDocPageAsMan(page, options) {
 		lines.push(".SH SEE ALSO");
 		const refs = options.seeAlso.map((ref, i) => {
 			const suffix = i < options.seeAlso.length - 1 ? "," : "";
-			return `.BR ${require_roff.escapeHyphens(require_roff.escapeRoff(ref.name))} (${ref.section})${suffix}`;
+			return `.BR "${require_roff.escapeHyphens(require_roff.escapeRequestArg(ref.name))}" (${ref.section})${suffix}`;
 		});
 		lines.push(refs.join("\n"));
 	}

package/dist/man.cjs

@@ -1,4 +1,4 @@
-const require_man = require('./man-DFKETOWN.cjs');
+const require_man = require('./man-NL-hVPdd.cjs');
 require('./roff-Cl0vekdg.cjs');
 
 exports.formatDateForMan = require_man.formatDateForMan;

package/dist/man.d.cts

@@ -1,2 +1,2 @@
-import { ManPageOptions, ManPageSection, formatDateForMan, formatDocPageAsMan, formatUsageTermAsRoff } from "./man-xPX8GhXq.cjs";
+import { ManPageOptions, ManPageSection, formatDateForMan, formatDocPageAsMan, formatUsageTermAsRoff } from "./man-D2t8hkyn.cjs";
 export { ManPageOptions, ManPageSection, formatDateForMan, formatDocPageAsMan, formatUsageTermAsRoff };

package/dist/man.d.ts

@@ -1,2 +1,2 @@
-import { ManPageOptions, ManPageSection, formatDateForMan, formatDocPageAsMan, formatUsageTermAsRoff } from "./man-CGKLHWkS.js";
+import { ManPageOptions, ManPageSection, formatDateForMan, formatDocPageAsMan, formatUsageTermAsRoff } from "./man-DXQgwt1g.js";
 export { ManPageOptions, ManPageSection, formatDateForMan, formatDocPageAsMan, formatUsageTermAsRoff };

package/dist/man.js

@@ -1,4 +1,4 @@
 import "./roff-CwBRpWCo.js";
-import { formatDateForMan, formatDocPageAsMan, formatUsageTermAsRoff } from "./man-BBDifH_Y.js";
+import { formatDateForMan, formatDocPageAsMan, formatUsageTermAsRoff } from "./man-CcjsLpyb.js";
 
 export { formatDateForMan, formatDocPageAsMan, formatUsageTermAsRoff };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@optique/man",
-  "version": "1.0.0-dev.896+5a811a7f",
+  "version": "1.0.0-dev.908+f60f037d",
   "description": "Man page generator for Optique CLI parsers",
   "keywords": [
     "CLI",
@@ -84,8 +84,8 @@
     "optique-man": "./dist/cli.js"
   },
   "dependencies": {
-    "@optique/run": "1.0.0-dev.896+5a811a7f",
-    "@optique/core": "1.0.0-dev.896+5a811a7f"
+    "@optique/run": "1.0.0-dev.908+f60f037d",
+    "@optique/core": "1.0.0-dev.908+f60f037d"
   },
   "devDependencies": {
     "@types/node": "^20.19.9",