@optique/core 0.10.0-dev.324 → 0.10.0-dev.328

package/dist/doc.cjs

@@ -46,7 +46,8 @@ function formatDocPage(programName, page, options = {}) {
 		output += "\n";
 	}
 	if (page.usage != null) {
-		output += "Usage: ";
+		const usageLabel = options.colors ? "\x1B[1;2mUsage:\x1B[0m " : "Usage: ";
+		output += usageLabel;
 		output += indentLines(require_usage.formatUsage(programName, page.usage, {
 			colors: options.colors,
 			maxWidth: options.maxWidth == null ? void 0 : options.maxWidth - 7,
@@ -67,7 +68,10 @@ function formatDocPage(programName, page, options = {}) {
 	for (const section of sections) {
 		if (section.entries.length < 1) continue;
 		output += "\n";
-		if (section.title != null) output += `${section.title}:\n`;
+		if (section.title != null) {
+			const sectionLabel = options.colors ? `\x1b[1;2m${section.title}:\x1b[0m\n` : `${section.title}:\n`;
+			output += sectionLabel;
+		}
 		for (const entry of section.entries) {
 			const term = require_usage.formatUsageTerm(entry.term, {
 				colors: options.colors,
@@ -92,6 +96,42 @@ function formatDocPage(programName, page, options = {}) {
 			output += `${" ".repeat(termIndent)}${ansiAwareRightPad(term, termWidth)}  ${description === "" ? "" : indentLines(description, termIndent + termWidth + 2)}\n`;
 		}
 	}
+	if (page.examples != null) {
+		output += "\n";
+		const examplesLabel = options.colors ? "\x1B[1;2mExamples:\x1B[0m\n" : "Examples:\n";
+		output += examplesLabel;
+		const examplesContent = require_message.formatMessage(page.examples, {
+			colors: options.colors,
+			maxWidth: options.maxWidth == null ? void 0 : options.maxWidth - 2,
+			quotes: !options.colors
+		});
+		output += "  " + indentLines(examplesContent, 2);
+		output += "\n";
+	}
+	if (page.author != null) {
+		output += "\n";
+		const authorLabel = options.colors ? "\x1B[1;2mAuthor:\x1B[0m\n" : "Author:\n";
+		output += authorLabel;
+		const authorContent = require_message.formatMessage(page.author, {
+			colors: options.colors,
+			maxWidth: options.maxWidth == null ? void 0 : options.maxWidth - 2,
+			quotes: !options.colors
+		});
+		output += "  " + indentLines(authorContent, 2);
+		output += "\n";
+	}
+	if (page.bugs != null) {
+		output += "\n";
+		const bugsLabel = options.colors ? "\x1B[1;2mBugs:\x1B[0m\n" : "Bugs:\n";
+		output += bugsLabel;
+		const bugsContent = require_message.formatMessage(page.bugs, {
+			colors: options.colors,
+			maxWidth: options.maxWidth == null ? void 0 : options.maxWidth - 2,
+			quotes: !options.colors
+		});
+		output += "  " + indentLines(bugsContent, 2);
+		output += "\n";
+	}
 	if (page.footer != null) {
 		output += "\n";
 		output += require_message.formatMessage(page.footer, {

package/dist/doc.d.cts

@@ -43,6 +43,21 @@ interface DocPage {
   readonly usage?: Usage;
   readonly description?: Message;
   readonly sections: readonly DocSection[];
+  /**
+   * Usage examples for the program.
+   * @since 0.10.0
+   */
+  readonly examples?: Message;
+  /**
+   * Author information.
+   * @since 0.10.0
+   */
+  readonly author?: Message;
+  /**
+   * Information about where to report bugs.
+   * @since 0.10.0
+   */
+  readonly bugs?: Message;
   readonly footer?: Message;
 }
 /**

package/dist/doc.d.ts

@@ -43,6 +43,21 @@ interface DocPage {
   readonly usage?: Usage;
   readonly description?: Message;
   readonly sections: readonly DocSection[];
+  /**
+   * Usage examples for the program.
+   * @since 0.10.0
+   */
+  readonly examples?: Message;
+  /**
+   * Author information.
+   * @since 0.10.0
+   */
+  readonly author?: Message;
+  /**
+   * Information about where to report bugs.
+   * @since 0.10.0
+   */
+  readonly bugs?: Message;
   readonly footer?: Message;
 }
 /**

package/dist/doc.js

@@ -46,7 +46,8 @@ function formatDocPage(programName, page, options = {}) {
 		output += "\n";
 	}
 	if (page.usage != null) {
-		output += "Usage: ";
+		const usageLabel = options.colors ? "\x1B[1;2mUsage:\x1B[0m " : "Usage: ";
+		output += usageLabel;
 		output += indentLines(formatUsage(programName, page.usage, {
 			colors: options.colors,
 			maxWidth: options.maxWidth == null ? void 0 : options.maxWidth - 7,
@@ -67,7 +68,10 @@ function formatDocPage(programName, page, options = {}) {
 	for (const section of sections) {
 		if (section.entries.length < 1) continue;
 		output += "\n";
-		if (section.title != null) output += `${section.title}:\n`;
+		if (section.title != null) {
+			const sectionLabel = options.colors ? `\x1b[1;2m${section.title}:\x1b[0m\n` : `${section.title}:\n`;
+			output += sectionLabel;
+		}
 		for (const entry of section.entries) {
 			const term = formatUsageTerm(entry.term, {
 				colors: options.colors,
@@ -92,6 +96,42 @@ function formatDocPage(programName, page, options = {}) {
 			output += `${" ".repeat(termIndent)}${ansiAwareRightPad(term, termWidth)}  ${description === "" ? "" : indentLines(description, termIndent + termWidth + 2)}\n`;
 		}
 	}
+	if (page.examples != null) {
+		output += "\n";
+		const examplesLabel = options.colors ? "\x1B[1;2mExamples:\x1B[0m\n" : "Examples:\n";
+		output += examplesLabel;
+		const examplesContent = formatMessage(page.examples, {
+			colors: options.colors,
+			maxWidth: options.maxWidth == null ? void 0 : options.maxWidth - 2,
+			quotes: !options.colors
+		});
+		output += "  " + indentLines(examplesContent, 2);
+		output += "\n";
+	}
+	if (page.author != null) {
+		output += "\n";
+		const authorLabel = options.colors ? "\x1B[1;2mAuthor:\x1B[0m\n" : "Author:\n";
+		output += authorLabel;
+		const authorContent = formatMessage(page.author, {
+			colors: options.colors,
+			maxWidth: options.maxWidth == null ? void 0 : options.maxWidth - 2,
+			quotes: !options.colors
+		});
+		output += "  " + indentLines(authorContent, 2);
+		output += "\n";
+	}
+	if (page.bugs != null) {
+		output += "\n";
+		const bugsLabel = options.colors ? "\x1B[1;2mBugs:\x1B[0m\n" : "Bugs:\n";
+		output += bugsLabel;
+		const bugsContent = formatMessage(page.bugs, {
+			colors: options.colors,
+			maxWidth: options.maxWidth == null ? void 0 : options.maxWidth - 2,
+			quotes: !options.colors
+		});
+		output += "  " + indentLines(bugsContent, 2);
+		output += "\n";
+	}
 	if (page.footer != null) {
 		output += "\n";
 		output += formatMessage(page.footer, {

package/dist/facade.cjs

@@ -403,10 +403,36 @@ function handleCompletion(completionArgs, programName, parser, completionParser,
 	for (const chunk of shell.encodeSuggestions(suggestions)) stdout(chunk);
 	return callOnCompletion(0);
 }
-function runParser(parser, programName, args, options = {}) {
+function runParser(parserOrProgram, programNameOrArgs, argsOrOptions, optionsParam) {
+	const isProgram = typeof programNameOrArgs !== "string";
+	let parser;
+	let programName;
+	let args;
+	let options;
+	if (isProgram) {
+		const program = parserOrProgram;
+		parser = program.parser;
+		programName = program.metadata.name;
+		args = programNameOrArgs;
+		options = argsOrOptions ?? {};
+		options = {
+			...options,
+			brief: options.brief ?? program.metadata.brief,
+			description: options.description ?? program.metadata.description,
+			examples: options.examples ?? program.metadata.examples,
+			author: options.author ?? program.metadata.author,
+			bugs: options.bugs ?? program.metadata.bugs,
+			footer: options.footer ?? program.metadata.footer
+		};
+	} else {
+		parser = parserOrProgram;
+		programName = programNameOrArgs;
+		args = argsOrOptions;
+		options = optionsParam ?? {};
+	}
 	const { colors, maxWidth, showDefault, aboveError = "usage", onError = () => {
 		throw new RunParserError("Failed to parse command line arguments.");
-	}, stderr = console.error, stdout = console.log, brief, description, footer } = options;
+	}, stderr = console.error, stdout = console.log, brief, description, examples, author, bugs, footer } = options;
 	const helpMode = options.help?.mode ?? "option";
 	const onHelp = options.help?.onShow ?? (() => ({}));
 	const versionMode = options.version?.mode ?? "option";
@@ -507,6 +533,9 @@ function runParser(parser, programName, args, options = {}) {
 							...doc,
 							brief: !isMetaCommandHelp ? brief ?? doc.brief : doc.brief,
 							description: !isMetaCommandHelp ? description ?? doc.description : doc.description,
+							examples: !isMetaCommandHelp ? examples ?? doc.examples : doc.examples,
+							author: !isMetaCommandHelp ? author ?? doc.author : doc.author,
+							bugs: !isMetaCommandHelp ? bugs ?? doc.bugs : doc.bugs,
 							footer: !isMetaCommandHelp ? footer ?? doc.footer : doc.footer
 						};
 						stdout(require_doc.formatDocPage(programName, augmentedDoc, {
@@ -534,6 +563,9 @@ function runParser(parser, programName, args, options = {}) {
 							...doc,
 							brief: brief ?? doc.brief,
 							description: description ?? doc.description,
+							examples: examples ?? doc.examples,
+							author: author ?? doc.author,
+							bugs: bugs ?? doc.bugs,
 							footer: footer ?? doc.footer
 						};
 						stderr(require_doc.formatDocPage(programName, augmentedDoc, {

package/dist/facade.d.cts

@@ -2,6 +2,7 @@ import { Message } from "./message.cjs";
 import { ShowDefaultOptions } from "./doc.cjs";
 import { InferMode, InferValue, Mode, ModeValue, Parser } from "./parser.cjs";
 import { ShellCompletion } from "./completion.cjs";
+import { Program } from "./program.cjs";
 
 //#region src/facade.d.ts
 
@@ -177,6 +178,24 @@ interface RunOptions<THelp, TError> {
    * @since 0.4.0
    */
   readonly description?: Message;
+  /**
+   * Usage examples for the program.
+   *
+   * @since 0.10.0
+   */
+  readonly examples?: Message;
+  /**
+   * Author information.
+   *
+   * @since 0.10.0
+   */
+  readonly author?: Message;
+  /**
+   * Information about where to report bugs.
+   *
+   * @since 0.10.0
+   */
+  readonly bugs?: Message;
   /**
    * Footer text shown at the bottom of help text.
    *
@@ -213,7 +232,10 @@ interface RunOptions<THelp, TError> {
  *          callbacks.
  * @throws {RunParserError} When parsing fails and no `onError` callback is
  *          provided.
+ * @since 0.10.0 Added support for {@link Program} objects.
  */
+declare function runParser<T, THelp = void, TError = never>(program: Program<"sync", T>, args: readonly string[], options?: RunOptions<THelp, TError>): T;
+declare function runParser<T, THelp = void, TError = never>(program: Program<"async", T>, args: readonly string[], options?: RunOptions<THelp, TError>): Promise<T>;
 declare function runParser<TParser extends Parser<"sync", unknown, unknown>, THelp = void, TError = never>(parser: TParser, programName: string, args: readonly string[], options?: RunOptions<THelp, TError>): InferValue<TParser>;
 declare function runParser<TParser extends Parser<"async", unknown, unknown>, THelp = void, TError = never>(parser: TParser, programName: string, args: readonly string[], options?: RunOptions<THelp, TError>): Promise<InferValue<TParser>>;
 declare function runParser<TParser extends Parser<Mode, unknown, unknown>, THelp = void, TError = never>(parser: TParser, programName: string, args: readonly string[], options?: RunOptions<THelp, TError>): ModeValue<InferMode<TParser>, InferValue<TParser>>;

package/dist/facade.d.ts

@@ -2,6 +2,7 @@ import { Message } from "./message.js";
 import { ShowDefaultOptions } from "./doc.js";
 import { InferMode, InferValue, Mode, ModeValue, Parser } from "./parser.js";
 import { ShellCompletion } from "./completion.js";
+import { Program } from "./program.js";
 
 //#region src/facade.d.ts
 
@@ -177,6 +178,24 @@ interface RunOptions<THelp, TError> {
    * @since 0.4.0
    */
   readonly description?: Message;
+  /**
+   * Usage examples for the program.
+   *
+   * @since 0.10.0
+   */
+  readonly examples?: Message;
+  /**
+   * Author information.
+   *
+   * @since 0.10.0
+   */
+  readonly author?: Message;
+  /**
+   * Information about where to report bugs.
+   *
+   * @since 0.10.0
+   */
+  readonly bugs?: Message;
   /**
    * Footer text shown at the bottom of help text.
    *
@@ -213,7 +232,10 @@ interface RunOptions<THelp, TError> {
  *          callbacks.
  * @throws {RunParserError} When parsing fails and no `onError` callback is
  *          provided.
+ * @since 0.10.0 Added support for {@link Program} objects.
  */
+declare function runParser<T, THelp = void, TError = never>(program: Program<"sync", T>, args: readonly string[], options?: RunOptions<THelp, TError>): T;
+declare function runParser<T, THelp = void, TError = never>(program: Program<"async", T>, args: readonly string[], options?: RunOptions<THelp, TError>): Promise<T>;
 declare function runParser<TParser extends Parser<"sync", unknown, unknown>, THelp = void, TError = never>(parser: TParser, programName: string, args: readonly string[], options?: RunOptions<THelp, TError>): InferValue<TParser>;
 declare function runParser<TParser extends Parser<"async", unknown, unknown>, THelp = void, TError = never>(parser: TParser, programName: string, args: readonly string[], options?: RunOptions<THelp, TError>): Promise<InferValue<TParser>>;
 declare function runParser<TParser extends Parser<Mode, unknown, unknown>, THelp = void, TError = never>(parser: TParser, programName: string, args: readonly string[], options?: RunOptions<THelp, TError>): ModeValue<InferMode<TParser>, InferValue<TParser>>;

package/dist/facade.js

@@ -403,10 +403,36 @@ function handleCompletion(completionArgs, programName, parser, completionParser,
 	for (const chunk of shell.encodeSuggestions(suggestions)) stdout(chunk);
 	return callOnCompletion(0);
 }
-function runParser(parser, programName, args, options = {}) {
+function runParser(parserOrProgram, programNameOrArgs, argsOrOptions, optionsParam) {
+	const isProgram = typeof programNameOrArgs !== "string";
+	let parser;
+	let programName;
+	let args;
+	let options;
+	if (isProgram) {
+		const program = parserOrProgram;
+		parser = program.parser;
+		programName = program.metadata.name;
+		args = programNameOrArgs;
+		options = argsOrOptions ?? {};
+		options = {
+			...options,
+			brief: options.brief ?? program.metadata.brief,
+			description: options.description ?? program.metadata.description,
+			examples: options.examples ?? program.metadata.examples,
+			author: options.author ?? program.metadata.author,
+			bugs: options.bugs ?? program.metadata.bugs,
+			footer: options.footer ?? program.metadata.footer
+		};
+	} else {
+		parser = parserOrProgram;
+		programName = programNameOrArgs;
+		args = argsOrOptions;
+		options = optionsParam ?? {};
+	}
 	const { colors, maxWidth, showDefault, aboveError = "usage", onError = () => {
 		throw new RunParserError("Failed to parse command line arguments.");
-	}, stderr = console.error, stdout = console.log, brief, description, footer } = options;
+	}, stderr = console.error, stdout = console.log, brief, description, examples, author, bugs, footer } = options;
 	const helpMode = options.help?.mode ?? "option";
 	const onHelp = options.help?.onShow ?? (() => ({}));
 	const versionMode = options.version?.mode ?? "option";
@@ -507,6 +533,9 @@ function runParser(parser, programName, args, options = {}) {
 							...doc,
 							brief: !isMetaCommandHelp ? brief ?? doc.brief : doc.brief,
 							description: !isMetaCommandHelp ? description ?? doc.description : doc.description,
+							examples: !isMetaCommandHelp ? examples ?? doc.examples : doc.examples,
+							author: !isMetaCommandHelp ? author ?? doc.author : doc.author,
+							bugs: !isMetaCommandHelp ? bugs ?? doc.bugs : doc.bugs,
 							footer: !isMetaCommandHelp ? footer ?? doc.footer : doc.footer
 						};
 						stdout(formatDocPage(programName, augmentedDoc, {
@@ -534,6 +563,9 @@ function runParser(parser, programName, args, options = {}) {
 							...doc,
 							brief: brief ?? doc.brief,
 							description: description ?? doc.description,
+							examples: examples ?? doc.examples,
+							author: author ?? doc.author,
+							bugs: bugs ?? doc.bugs,
 							footer: footer ?? doc.footer
 						};
 						stderr(formatDocPage(programName, augmentedDoc, {

package/dist/program.cjs

@@ -0,0 +1,44 @@
+
+//#region src/program.ts
+/**
+* Defines a CLI program with a parser and metadata.
+*
+* This is a helper function that returns its argument unchanged, but provides
+* automatic type inference for the program. This eliminates the need to
+* manually specify type parameters when defining a program.
+*
+* @template M - The mode of the parser ("sync" or "async").
+* @template T - The type of value produced by the parser.
+* @param program - The program definition with parser and metadata.
+* @returns The same program object with inferred types.
+*
+* @example
+* ```typescript
+* import { defineProgram } from "@optique/core/program";
+* import { object } from "@optique/core/constructs";
+* import { option } from "@optique/core/primitives";
+* import { string } from "@optique/core/valueparser";
+* import { message } from "@optique/core/message";
+*
+* const prog = defineProgram({
+*   parser: object({
+*     name: option("-n", "--name", string()),
+*   }),
+*   metadata: {
+*     name: "myapp",
+*     version: "1.0.0",
+*     brief: message`A simple CLI tool`,
+*   },
+* });
+* // TypeScript automatically infers:
+* // Program<"sync", { readonly name: string }>
+* ```
+*
+* @since 0.11.0
+*/
+function defineProgram(program) {
+	return program;
+}
+
+//#endregion
+exports.defineProgram = defineProgram;

package/dist/program.d.cts

@@ -0,0 +1,124 @@
+import { Message } from "./message.cjs";
+import { Mode, Parser } from "./parser.cjs";
+
+//#region src/program.d.ts
+
+/**
+ * Metadata for a CLI program.
+ *
+ * @since 0.10.0
+ */
+interface ProgramMetadata {
+  /**
+   * The name of the program.
+   */
+  readonly name: string;
+  /**
+   * The version of the program.
+   */
+  readonly version?: string;
+  /**
+   * A brief one-line description of the program.
+   */
+  readonly brief?: Message;
+  /**
+   * A detailed description of the program.
+   */
+  readonly description?: Message;
+  /**
+   * Author information.
+   */
+  readonly author?: Message;
+  /**
+   * Information about where to report bugs.
+   */
+  readonly bugs?: Message;
+  /**
+   * Usage examples for the program.
+   */
+  readonly examples?: Message;
+  /**
+   * Footer text shown at the end of help output.
+   */
+  readonly footer?: Message;
+}
+/**
+ * A CLI program consisting of a parser and its metadata.
+ *
+ * This interface bundles a parser with its metadata (name, version,
+ * description, etc.), providing a single source of truth for CLI application
+ * information that can be shared across different functionalities.
+ *
+ * @template M - The mode of the parser ("sync" or "async").
+ * @template T - The type of value produced by the parser.
+ *
+ * @example
+ * ```typescript
+ * import type { Program } from "@optique/core/program";
+ * import { command, option, string } from "@optique/core";
+ * import { message } from "@optique/core/message";
+ *
+ * const prog: Program<"sync", { name: string }> = {
+ *   parser: command("greet", () => ({
+ *     name: option("name", string()).default("World"),
+ *   })),
+ *   metadata: {
+ *     name: "greet",
+ *     version: "1.0.0",
+ *     brief: message`A simple greeting CLI tool`,
+ *     author: message`Jane Doe <jane@example.com>`,
+ *   },
+ * };
+ * ```
+ *
+ * @since 0.11.0
+ */
+interface Program<M extends Mode, T> {
+  /**
+   * The parser for the program.
+   */
+  readonly parser: Parser<M, T, unknown>;
+  /**
+   * Metadata about the program.
+   */
+  readonly metadata: ProgramMetadata;
+}
+/**
+ * Defines a CLI program with a parser and metadata.
+ *
+ * This is a helper function that returns its argument unchanged, but provides
+ * automatic type inference for the program. This eliminates the need to
+ * manually specify type parameters when defining a program.
+ *
+ * @template M - The mode of the parser ("sync" or "async").
+ * @template T - The type of value produced by the parser.
+ * @param program - The program definition with parser and metadata.
+ * @returns The same program object with inferred types.
+ *
+ * @example
+ * ```typescript
+ * import { defineProgram } from "@optique/core/program";
+ * import { object } from "@optique/core/constructs";
+ * import { option } from "@optique/core/primitives";
+ * import { string } from "@optique/core/valueparser";
+ * import { message } from "@optique/core/message";
+ *
+ * const prog = defineProgram({
+ *   parser: object({
+ *     name: option("-n", "--name", string()),
+ *   }),
+ *   metadata: {
+ *     name: "myapp",
+ *     version: "1.0.0",
+ *     brief: message`A simple CLI tool`,
+ *   },
+ * });
+ * // TypeScript automatically infers:
+ * // Program<"sync", { readonly name: string }>
+ * ```
+ *
+ * @since 0.11.0
+ */
+declare function defineProgram<M extends Mode, T>(program: Program<M, T>): Program<M, T>;
+//#endregion
+export { Program, ProgramMetadata, defineProgram };

package/dist/program.d.ts

@@ -0,0 +1,124 @@
+import { Message } from "./message.js";
+import { Mode, Parser } from "./parser.js";
+
+//#region src/program.d.ts
+
+/**
+ * Metadata for a CLI program.
+ *
+ * @since 0.10.0
+ */
+interface ProgramMetadata {
+  /**
+   * The name of the program.
+   */
+  readonly name: string;
+  /**
+   * The version of the program.
+   */
+  readonly version?: string;
+  /**
+   * A brief one-line description of the program.
+   */
+  readonly brief?: Message;
+  /**
+   * A detailed description of the program.
+   */
+  readonly description?: Message;
+  /**
+   * Author information.
+   */
+  readonly author?: Message;
+  /**
+   * Information about where to report bugs.
+   */
+  readonly bugs?: Message;
+  /**
+   * Usage examples for the program.
+   */
+  readonly examples?: Message;
+  /**
+   * Footer text shown at the end of help output.
+   */
+  readonly footer?: Message;
+}
+/**
+ * A CLI program consisting of a parser and its metadata.
+ *
+ * This interface bundles a parser with its metadata (name, version,
+ * description, etc.), providing a single source of truth for CLI application
+ * information that can be shared across different functionalities.
+ *
+ * @template M - The mode of the parser ("sync" or "async").
+ * @template T - The type of value produced by the parser.
+ *
+ * @example
+ * ```typescript
+ * import type { Program } from "@optique/core/program";
+ * import { command, option, string } from "@optique/core";
+ * import { message } from "@optique/core/message";
+ *
+ * const prog: Program<"sync", { name: string }> = {
+ *   parser: command("greet", () => ({
+ *     name: option("name", string()).default("World"),
+ *   })),
+ *   metadata: {
+ *     name: "greet",
+ *     version: "1.0.0",
+ *     brief: message`A simple greeting CLI tool`,
+ *     author: message`Jane Doe <jane@example.com>`,
+ *   },
+ * };
+ * ```
+ *
+ * @since 0.11.0
+ */
+interface Program<M extends Mode, T> {
+  /**
+   * The parser for the program.
+   */
+  readonly parser: Parser<M, T, unknown>;
+  /**
+   * Metadata about the program.
+   */
+  readonly metadata: ProgramMetadata;
+}
+/**
+ * Defines a CLI program with a parser and metadata.
+ *
+ * This is a helper function that returns its argument unchanged, but provides
+ * automatic type inference for the program. This eliminates the need to
+ * manually specify type parameters when defining a program.
+ *
+ * @template M - The mode of the parser ("sync" or "async").
+ * @template T - The type of value produced by the parser.
+ * @param program - The program definition with parser and metadata.
+ * @returns The same program object with inferred types.
+ *
+ * @example
+ * ```typescript
+ * import { defineProgram } from "@optique/core/program";
+ * import { object } from "@optique/core/constructs";
+ * import { option } from "@optique/core/primitives";
+ * import { string } from "@optique/core/valueparser";
+ * import { message } from "@optique/core/message";
+ *
+ * const prog = defineProgram({
+ *   parser: object({
+ *     name: option("-n", "--name", string()),
+ *   }),
+ *   metadata: {
+ *     name: "myapp",
+ *     version: "1.0.0",
+ *     brief: message`A simple CLI tool`,
+ *   },
+ * });
+ * // TypeScript automatically infers:
+ * // Program<"sync", { readonly name: string }>
+ * ```
+ *
+ * @since 0.11.0
+ */
+declare function defineProgram<M extends Mode, T>(program: Program<M, T>): Program<M, T>;
+//#endregion
+export { Program, ProgramMetadata, defineProgram };

package/dist/program.js

@@ -0,0 +1,43 @@
+//#region src/program.ts
+/**
+* Defines a CLI program with a parser and metadata.
+*
+* This is a helper function that returns its argument unchanged, but provides
+* automatic type inference for the program. This eliminates the need to
+* manually specify type parameters when defining a program.
+*
+* @template M - The mode of the parser ("sync" or "async").
+* @template T - The type of value produced by the parser.
+* @param program - The program definition with parser and metadata.
+* @returns The same program object with inferred types.
+*
+* @example
+* ```typescript
+* import { defineProgram } from "@optique/core/program";
+* import { object } from "@optique/core/constructs";
+* import { option } from "@optique/core/primitives";
+* import { string } from "@optique/core/valueparser";
+* import { message } from "@optique/core/message";
+*
+* const prog = defineProgram({
+*   parser: object({
+*     name: option("-n", "--name", string()),
+*   }),
+*   metadata: {
+*     name: "myapp",
+*     version: "1.0.0",
+*     brief: message`A simple CLI tool`,
+*   },
+* });
+* // TypeScript automatically infers:
+* // Program<"sync", { readonly name: string }>
+* ```
+*
+* @since 0.11.0
+*/
+function defineProgram(program) {
+	return program;
+}
+
+//#endregion
+export { defineProgram };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@optique/core",
-  "version": "0.10.0-dev.324+5bba27e5",
+  "version": "0.10.0-dev.328+4e5f40d5",
   "description": "Type-safe combinatorial command-line interface parser",
   "keywords": [
     "CLI",
@@ -131,6 +131,14 @@
       "import": "./dist/primitives.js",
       "require": "./dist/primitives.cjs"
     },
+    "./program": {
+      "types": {
+        "import": "./dist/program.d.ts",
+        "require": "./dist/program.d.cts"
+      },
+      "import": "./dist/program.js",
+      "require": "./dist/program.cjs"
+    },
     "./usage": {
       "types": {
         "import": "./dist/usage.d.ts",