@optique/core 1.4.0-dev.2628 → 1.4.0-dev.2631

package/dist/doc.cjs

@@ -138,12 +138,58 @@ function deduplicateDocFragments(fragments) {
 function cloneDocEntry(entry) {
 	return {
 		term: require_usage.cloneUsageTerm(entry.term),
+		...entry.envVars != null && { envVars: [...entry.envVars] },
 		...entry.description != null && { description: require_message.cloneMessage(entry.description) },
 		...entry.default != null && { default: require_message.cloneMessage(entry.default) },
 		...entry.choices != null && { choices: require_message.cloneMessage(entry.choices) }
 	};
 }
 /**
+* Derives an environment section from the visible entries on a help page.
+* Names are grouped in first-appearance order with references to their
+* associated entries. Empty names and hidden or empty terms are ignored.
+* This does not read environment values or modify the page. Entries without
+* CLI documentation, such as `bindEnv(fail(), ...)`, are not collected.
+*
+* @param page The documentation page to inspect.
+* @param options An optional heading for the generated section.
+* @returns A new section, or `undefined` when there are no visible names.
+* @throws {TypeError} If a used title is empty or contains control characters.
+* @since 1.4.0
+*/
+function deriveEnvironmentSection(page, options = {}) {
+	const bindings = /* @__PURE__ */ new Map();
+	for (const section of page.sections) for (const entry of section.entries) {
+		if (isDocEntryHidden(entry)) continue;
+		const rendered = require_usage.formatUsageTerm(entry.term, { context: "doc" });
+		if (rendered.trim() === "") continue;
+		const term = entry.term;
+		const reference = term.type === "option" ? [require_message.optionNames(term.names), ...term.metavar == null ? [] : [require_message.text(" "), require_message.metavar(term.metavar)]] : term.type === "argument" ? [require_message.metavar(term.metavar)] : term.type === "command" ? [require_message.commandLine(term.name)] : [require_message.text(rendered)];
+		for (const name of entry.envVars ?? []) {
+			if (name === "") continue;
+			let references = bindings.get(name);
+			if (references == null) {
+				references = /* @__PURE__ */ new Map();
+				bindings.set(name, references);
+			}
+			references.set(rendered, reference);
+		}
+	}
+	if (bindings.size === 0) return void 0;
+	const title = options.title ?? "Environment";
+	require_validate.validateLabel(title);
+	return {
+		title,
+		entries: Array.from(bindings, ([name, references]) => ({
+			term: {
+				type: "literal",
+				value: name
+			},
+			description: Array.from(references.values()).flatMap((reference, i) => i === 0 ? reference : [require_message.text(", "), ...reference])
+		}))
+	};
+}
+/**
 * Classifies a {@link DocSection} by its content type for use in the
 * default smart sort.
 *
@@ -224,6 +270,11 @@ function formatDocPage(programName, page, options = {}) {
 	const opaqueFormatter = options.messageFormatter != null && !require_message_registry.messageRenderers.has(options.messageFormatter);
 	const defaultAmbient = options.theme?.annotationStyles?.default ?? { dim: true };
 	const choicesAmbient = options.theme?.annotationStyles?.choices ?? { dim: true };
+	const environmentAmbient = options.theme?.annotationStyles?.environment ?? { dim: true };
+	const environmentStyle = require_terminal_internal.styleCode(environmentAmbient);
+	const environmentPlacement = typeof options.showEnvironment === "object" ? options.showEnvironment.placement ?? "inline" : options.showEnvironment ? "inline" : void 0;
+	const showInlineEnvironment = environmentPlacement === "inline" || environmentPlacement === "both";
+	const environmentContent = (entry) => [...new Set(entry.envVars ?? [])].filter((name) => name !== "").flatMap((name, i) => i === 0 ? [require_message.envVar(name)] : [require_message.text(", "), require_message.envVar(name)]);
 	const labelCache = /* @__PURE__ */ new Map();
 	const label = (label$1, kind) => {
 		const key = `${kind}:${label$1}`;
@@ -267,20 +318,29 @@ function formatDocPage(programName, page, options = {}) {
 			return rendered.trim() !== "";
 		})
 	}));
-	page = {
+	const environmentSection = environmentPlacement === "section" || environmentPlacement === "both" ? deriveEnvironmentSection({
 		...page,
 		sections: filteredSections
+	}, { title: typeof options.showEnvironment === "object" ? options.showEnvironment.sectionTitle : void 0 }) : void 0;
+	page = {
+		...page,
+		sections: environmentSection == null ? filteredSections : [...filteredSections, environmentSection]
 	};
 	if (typeof options.showChoices === "object" && options.showChoices.maxItems != null) {
 		const maxItems = options.showChoices.maxItems;
 		if (maxItems < 1) throw new RangeError(`showChoices.maxItems must be at least 1, but got ${maxItems}.`);
 	}
 	const hasContent = (msg) => Array.isArray(msg) && msg.length > 0;
-	const needsDescriptionColumn = (entry) => hasContent(entry.description) || (options.showDefault === true || typeof options.showDefault === "object") && hasContent(entry.default) || (options.showChoices === true || typeof options.showChoices === "object") && hasContent(entry.choices);
+	const needsDescriptionColumn = (entry) => hasContent(entry.description) || (options.showDefault === true || typeof options.showDefault === "object") && hasContent(entry.default) || (options.showChoices === true || typeof options.showChoices === "object") && hasContent(entry.choices) || showInlineEnvironment && hasContent(environmentContent(entry));
 	const annotations = /* @__PURE__ */ new Map();
 	const annotation = (kind) => {
 		const cached = annotations.get(kind);
 		if (cached != null) return cached;
+		if (kind === "environment") {
+			const layout$1 = require_text_layout.measureAnnotation(" [env: ", "]");
+			annotations.set(kind, layout$1);
+			return layout$1;
+		}
 		const config = kind === "default" ? options.showDefault : options.showChoices;
 		const prefix = punctuation(typeof config === "object" ? config.prefix ?? (kind === "default" ? " [" : " (") : kind === "default" ? " [" : " (", kind === "default" ? "defaultPrefix" : "choicesPrefix");
 		const suffix = punctuation(typeof config === "object" ? config.suffix ?? (kind === "default" ? "]" : ")") : kind === "default" ? "]" : ")", kind === "default" ? "defaultSuffix" : "choicesSuffix");
@@ -316,9 +376,13 @@ function formatDocPage(programName, page, options = {}) {
 	}
 	if (options.maxWidth != null) {
 		let minDescWidth = 1;
-		if (needsDescColumn) for (const kind of ["default", "choices"]) {
-			const enabled = kind === "default" ? options.showDefault : options.showChoices;
-			if (enabled && page.sections.some((section) => section.entries.some((entry) => hasContent(entry[kind])))) minDescWidth = Math.max(minDescWidth, annotation(kind).minWidth);
+		if (needsDescColumn) for (const kind of [
+			"default",
+			"choices",
+			"environment"
+		]) {
+			const enabled = kind === "default" ? options.showDefault : kind === "choices" ? options.showChoices : showInlineEnvironment;
+			if (enabled && page.sections.some((section) => section.entries.some((entry) => hasContent(kind === "environment" ? environmentContent(entry) : entry[kind])))) minDescWidth = Math.max(minDescWidth, annotation(kind).minWidth);
 		}
 		const splitEntryMin = termIndent + 2 + Math.max(2, 2 * minDescWidth - 1);
 		const fixedEntryMin = termIndent + 2 + termWidth + minDescWidth;
@@ -387,7 +451,7 @@ function formatDocPage(programName, page, options = {}) {
 		output += "\n";
 	}
 	const comparator = options.sectionOrder ?? defaultSectionOrder;
-	const sections = page.sections.map((s, i) => ({
+	const sections = filteredSections.map((s, i) => ({
 		section: s,
 		index: i
 	})).toSorted((a, b) => {
@@ -395,6 +459,7 @@ function formatDocPage(programName, page, options = {}) {
 		if (cmp !== 0) return cmp;
 		return a.index - b.index;
 	}).map(({ section }) => section);
+	if (environmentSection != null) sections.push(environmentSection);
 	for (const section of sections) {
 		if (section.entries.length < 1) continue;
 		output += "\n";
@@ -421,7 +486,7 @@ function formatDocPage(programName, page, options = {}) {
 			const extraTermOffset = descColumnWidth != null ? Math.max(0, termVisibleWidth - effectiveTermWidth) : 0;
 			const descFormatOptions = {
 				colors: options.colors,
-				quotes: !options.colors,
+				quotes: section === environmentSection ? false : !options.colors,
 				maxWidth: descColumnWidth,
 				initialWidth: extraTermOffset > 0 ? extraTermOffset : void 0
 			};
@@ -465,6 +530,10 @@ function formatDocPage(programName, page, options = {}) {
 				}
 				appendAnnotation(truncatedTerms, annotation("choices"), choicesStyle, choicesAmbient, false);
 			}
+			if (showInlineEnvironment) {
+				const content = environmentContent(entry);
+				if (hasContent(content)) appendAnnotation(content, annotation("environment"), environmentStyle, environmentAmbient, false);
+			}
 			const paddedTerm = ansiAwareRightPad(term, effectiveTermWidth);
 			output += `${" ".repeat(termIndent)}${multilineReplacement ? indentLines(paddedTerm, termIndent) : paddedTerm}${description === "" ? "" : `  ${indentLines(description, termIndent + effectiveTermWidth + 2)}`}\n`;
 		}
@@ -528,5 +597,6 @@ function ansiAwareRightPad(text$1, length, char = " ") {
 exports.cloneDocEntry = cloneDocEntry;
 exports.deduplicateDocEntries = deduplicateDocEntries;
 exports.deduplicateDocFragments = deduplicateDocFragments;
+exports.deriveEnvironmentSection = deriveEnvironmentSection;
 exports.formatDocPage = formatDocPage;
 exports.isDocEntryHidden = isDocEntryHidden;

package/dist/doc.d.cts

@@ -34,6 +34,13 @@ interface DocEntry {
    * @since 0.10.0
    */
   readonly choices?: Message;
+  /**
+   * Declared environment bindings associated with this entry, outermost
+   * first. These names do not guarantee that every binding is consulted
+   * during parsing. Renderers can display them with `showEnvironment`.
+   * @since 1.4.0
+   */
+  readonly envVars?: readonly string[];
 }
 /**
  * A section in a document that groups related entries together.
@@ -151,6 +158,32 @@ declare function deduplicateDocFragments(fragments: readonly DocFragment[]): Doc
  * @since 1.0.0
  */
 declare function cloneDocEntry(entry: DocEntry): DocEntry;
+/**
+ * Controls automatic environment documentation in help and man pages.
+ * @since 1.4.0
+ */
+interface ShowEnvironmentOptions {
+  /** The display layout. Defaults to `"inline"`. */
+  readonly placement?: "inline" | "section" | "both";
+  /** The generated section's heading. Defaults to `"Environment"`. */
+  readonly sectionTitle?: string;
+}
+/**
+ * Derives an environment section from the visible entries on a help page.
+ * Names are grouped in first-appearance order with references to their
+ * associated entries. Empty names and hidden or empty terms are ignored.
+ * This does not read environment values or modify the page. Entries without
+ * CLI documentation, such as `bindEnv(fail(), ...)`, are not collected.
+ *
+ * @param page The documentation page to inspect.
+ * @param options An optional heading for the generated section.
+ * @returns A new section, or `undefined` when there are no visible names.
+ * @throws {TypeError} If a used title is empty or contains control characters.
+ * @since 1.4.0
+ */
+declare function deriveEnvironmentSection(page: DocPage, options?: {
+  readonly title?: string;
+}): DocSection | undefined;
 /**
  * Configuration for customizing default value display formatting.
  *
@@ -207,6 +240,14 @@ interface ShowChoicesOptions {
  * Options for formatting a documentation page.
  */
 interface DocPageFormatOptions {
+  /**
+   * Displays declared environment bindings. `true` or `{}` selects inline
+   * annotations; `placement` can select a section or both. Defaults to `false`.
+   * Generated sections follow the regular sections, before examples, and are
+   * not passed to `sectionOrder`. The original page is not modified.
+   * @since 1.4.0
+   */
+  readonly showEnvironment?: boolean | ShowEnvironmentOptions;
   /**
    * Custom message renderer, taking precedence over theme for messages.
    * @since 1.3.0
@@ -362,4 +403,4 @@ interface DocPageFormatOptions {
  */
 declare function formatDocPage(programName: string, page: DocPage, options?: DocPageFormatOptions): string;
 //#endregion
-export { DocEntry, DocFragment, DocFragments, DocPage, DocPageFormatOptions, DocSection, ShowChoicesOptions, ShowDefaultOptions, cloneDocEntry, deduplicateDocEntries, deduplicateDocFragments, formatDocPage, isDocEntryHidden };
+export { DocEntry, DocFragment, DocFragments, DocPage, DocPageFormatOptions, DocSection, ShowChoicesOptions, ShowDefaultOptions, ShowEnvironmentOptions, cloneDocEntry, deduplicateDocEntries, deduplicateDocFragments, deriveEnvironmentSection, formatDocPage, isDocEntryHidden };

package/dist/doc.d.ts

@@ -34,6 +34,13 @@ interface DocEntry {
    * @since 0.10.0
    */
   readonly choices?: Message;
+  /**
+   * Declared environment bindings associated with this entry, outermost
+   * first. These names do not guarantee that every binding is consulted
+   * during parsing. Renderers can display them with `showEnvironment`.
+   * @since 1.4.0
+   */
+  readonly envVars?: readonly string[];
 }
 /**
  * A section in a document that groups related entries together.
@@ -151,6 +158,32 @@ declare function deduplicateDocFragments(fragments: readonly DocFragment[]): Doc
  * @since 1.0.0
  */
 declare function cloneDocEntry(entry: DocEntry): DocEntry;
+/**
+ * Controls automatic environment documentation in help and man pages.
+ * @since 1.4.0
+ */
+interface ShowEnvironmentOptions {
+  /** The display layout. Defaults to `"inline"`. */
+  readonly placement?: "inline" | "section" | "both";
+  /** The generated section's heading. Defaults to `"Environment"`. */
+  readonly sectionTitle?: string;
+}
+/**
+ * Derives an environment section from the visible entries on a help page.
+ * Names are grouped in first-appearance order with references to their
+ * associated entries. Empty names and hidden or empty terms are ignored.
+ * This does not read environment values or modify the page. Entries without
+ * CLI documentation, such as `bindEnv(fail(), ...)`, are not collected.
+ *
+ * @param page The documentation page to inspect.
+ * @param options An optional heading for the generated section.
+ * @returns A new section, or `undefined` when there are no visible names.
+ * @throws {TypeError} If a used title is empty or contains control characters.
+ * @since 1.4.0
+ */
+declare function deriveEnvironmentSection(page: DocPage, options?: {
+  readonly title?: string;
+}): DocSection | undefined;
 /**
  * Configuration for customizing default value display formatting.
  *
@@ -207,6 +240,14 @@ interface ShowChoicesOptions {
  * Options for formatting a documentation page.
  */
 interface DocPageFormatOptions {
+  /**
+   * Displays declared environment bindings. `true` or `{}` selects inline
+   * annotations; `placement` can select a section or both. Defaults to `false`.
+   * Generated sections follow the regular sections, before examples, and are
+   * not passed to `sectionOrder`. The original page is not modified.
+   * @since 1.4.0
+   */
+  readonly showEnvironment?: boolean | ShowEnvironmentOptions;
   /**
    * Custom message renderer, taking precedence over theme for messages.
    * @since 1.3.0
@@ -362,4 +403,4 @@ interface DocPageFormatOptions {
  */
 declare function formatDocPage(programName: string, page: DocPage, options?: DocPageFormatOptions): string;
 //#endregion
-export { DocEntry, DocFragment, DocFragments, DocPage, DocPageFormatOptions, DocSection, ShowChoicesOptions, ShowDefaultOptions, cloneDocEntry, deduplicateDocEntries, deduplicateDocFragments, formatDocPage, isDocEntryHidden };
+export { DocEntry, DocFragment, DocFragments, DocPage, DocPageFormatOptions, DocSection, ShowChoicesOptions, ShowDefaultOptions, ShowEnvironmentOptions, cloneDocEntry, deduplicateDocEntries, deduplicateDocFragments, deriveEnvironmentSection, formatDocPage, isDocEntryHidden };

package/dist/doc.js

@@ -4,7 +4,7 @@ import { validateLabel, validateProgramName } from "./validate.js";
 import { cloneUsageTerm, formatUsage, formatUsageTerm, isDocHidden } from "./usage.js";
 import { hasAutomaticWidth, minimumUsageWidth, reportAutomaticWidth } from "./terminal-width.js";
 import { messageRenderers } from "./message-registry.js";
-import { cloneMessage, text } from "./message.js";
+import { cloneMessage, commandLine, envVar, metavar, optionNames, text } from "./message.js";
 import { resolveMessageFormatter } from "./message-renderer.js";
 
 //#region src/doc.ts
@@ -138,12 +138,58 @@ function deduplicateDocFragments(fragments) {
 function cloneDocEntry(entry) {
 	return {
 		term: cloneUsageTerm(entry.term),
+		...entry.envVars != null && { envVars: [...entry.envVars] },
 		...entry.description != null && { description: cloneMessage(entry.description) },
 		...entry.default != null && { default: cloneMessage(entry.default) },
 		...entry.choices != null && { choices: cloneMessage(entry.choices) }
 	};
 }
 /**
+* Derives an environment section from the visible entries on a help page.
+* Names are grouped in first-appearance order with references to their
+* associated entries. Empty names and hidden or empty terms are ignored.
+* This does not read environment values or modify the page. Entries without
+* CLI documentation, such as `bindEnv(fail(), ...)`, are not collected.
+*
+* @param page The documentation page to inspect.
+* @param options An optional heading for the generated section.
+* @returns A new section, or `undefined` when there are no visible names.
+* @throws {TypeError} If a used title is empty or contains control characters.
+* @since 1.4.0
+*/
+function deriveEnvironmentSection(page, options = {}) {
+	const bindings = /* @__PURE__ */ new Map();
+	for (const section of page.sections) for (const entry of section.entries) {
+		if (isDocEntryHidden(entry)) continue;
+		const rendered = formatUsageTerm(entry.term, { context: "doc" });
+		if (rendered.trim() === "") continue;
+		const term = entry.term;
+		const reference = term.type === "option" ? [optionNames(term.names), ...term.metavar == null ? [] : [text(" "), metavar(term.metavar)]] : term.type === "argument" ? [metavar(term.metavar)] : term.type === "command" ? [commandLine(term.name)] : [text(rendered)];
+		for (const name of entry.envVars ?? []) {
+			if (name === "") continue;
+			let references = bindings.get(name);
+			if (references == null) {
+				references = /* @__PURE__ */ new Map();
+				bindings.set(name, references);
+			}
+			references.set(rendered, reference);
+		}
+	}
+	if (bindings.size === 0) return void 0;
+	const title = options.title ?? "Environment";
+	validateLabel(title);
+	return {
+		title,
+		entries: Array.from(bindings, ([name, references]) => ({
+			term: {
+				type: "literal",
+				value: name
+			},
+			description: Array.from(references.values()).flatMap((reference, i) => i === 0 ? reference : [text(", "), ...reference])
+		}))
+	};
+}
+/**
 * Classifies a {@link DocSection} by its content type for use in the
 * default smart sort.
 *
@@ -224,6 +270,11 @@ function formatDocPage(programName, page, options = {}) {
 	const opaqueFormatter = options.messageFormatter != null && !messageRenderers.has(options.messageFormatter);
 	const defaultAmbient = options.theme?.annotationStyles?.default ?? { dim: true };
 	const choicesAmbient = options.theme?.annotationStyles?.choices ?? { dim: true };
+	const environmentAmbient = options.theme?.annotationStyles?.environment ?? { dim: true };
+	const environmentStyle = styleCode(environmentAmbient);
+	const environmentPlacement = typeof options.showEnvironment === "object" ? options.showEnvironment.placement ?? "inline" : options.showEnvironment ? "inline" : void 0;
+	const showInlineEnvironment = environmentPlacement === "inline" || environmentPlacement === "both";
+	const environmentContent = (entry) => [...new Set(entry.envVars ?? [])].filter((name) => name !== "").flatMap((name, i) => i === 0 ? [envVar(name)] : [text(", "), envVar(name)]);
 	const labelCache = /* @__PURE__ */ new Map();
 	const label = (label$1, kind) => {
 		const key = `${kind}:${label$1}`;
@@ -267,20 +318,29 @@ function formatDocPage(programName, page, options = {}) {
 			return rendered.trim() !== "";
 		})
 	}));
-	page = {
+	const environmentSection = environmentPlacement === "section" || environmentPlacement === "both" ? deriveEnvironmentSection({
 		...page,
 		sections: filteredSections
+	}, { title: typeof options.showEnvironment === "object" ? options.showEnvironment.sectionTitle : void 0 }) : void 0;
+	page = {
+		...page,
+		sections: environmentSection == null ? filteredSections : [...filteredSections, environmentSection]
 	};
 	if (typeof options.showChoices === "object" && options.showChoices.maxItems != null) {
 		const maxItems = options.showChoices.maxItems;
 		if (maxItems < 1) throw new RangeError(`showChoices.maxItems must be at least 1, but got ${maxItems}.`);
 	}
 	const hasContent = (msg) => Array.isArray(msg) && msg.length > 0;
-	const needsDescriptionColumn = (entry) => hasContent(entry.description) || (options.showDefault === true || typeof options.showDefault === "object") && hasContent(entry.default) || (options.showChoices === true || typeof options.showChoices === "object") && hasContent(entry.choices);
+	const needsDescriptionColumn = (entry) => hasContent(entry.description) || (options.showDefault === true || typeof options.showDefault === "object") && hasContent(entry.default) || (options.showChoices === true || typeof options.showChoices === "object") && hasContent(entry.choices) || showInlineEnvironment && hasContent(environmentContent(entry));
 	const annotations = /* @__PURE__ */ new Map();
 	const annotation = (kind) => {
 		const cached = annotations.get(kind);
 		if (cached != null) return cached;
+		if (kind === "environment") {
+			const layout$1 = measureAnnotation(" [env: ", "]");
+			annotations.set(kind, layout$1);
+			return layout$1;
+		}
 		const config = kind === "default" ? options.showDefault : options.showChoices;
 		const prefix = punctuation(typeof config === "object" ? config.prefix ?? (kind === "default" ? " [" : " (") : kind === "default" ? " [" : " (", kind === "default" ? "defaultPrefix" : "choicesPrefix");
 		const suffix = punctuation(typeof config === "object" ? config.suffix ?? (kind === "default" ? "]" : ")") : kind === "default" ? "]" : ")", kind === "default" ? "defaultSuffix" : "choicesSuffix");
@@ -316,9 +376,13 @@ function formatDocPage(programName, page, options = {}) {
 	}
 	if (options.maxWidth != null) {
 		let minDescWidth = 1;
-		if (needsDescColumn) for (const kind of ["default", "choices"]) {
-			const enabled = kind === "default" ? options.showDefault : options.showChoices;
-			if (enabled && page.sections.some((section) => section.entries.some((entry) => hasContent(entry[kind])))) minDescWidth = Math.max(minDescWidth, annotation(kind).minWidth);
+		if (needsDescColumn) for (const kind of [
+			"default",
+			"choices",
+			"environment"
+		]) {
+			const enabled = kind === "default" ? options.showDefault : kind === "choices" ? options.showChoices : showInlineEnvironment;
+			if (enabled && page.sections.some((section) => section.entries.some((entry) => hasContent(kind === "environment" ? environmentContent(entry) : entry[kind])))) minDescWidth = Math.max(minDescWidth, annotation(kind).minWidth);
 		}
 		const splitEntryMin = termIndent + 2 + Math.max(2, 2 * minDescWidth - 1);
 		const fixedEntryMin = termIndent + 2 + termWidth + minDescWidth;
@@ -387,7 +451,7 @@ function formatDocPage(programName, page, options = {}) {
 		output += "\n";
 	}
 	const comparator = options.sectionOrder ?? defaultSectionOrder;
-	const sections = page.sections.map((s, i) => ({
+	const sections = filteredSections.map((s, i) => ({
 		section: s,
 		index: i
 	})).toSorted((a, b) => {
@@ -395,6 +459,7 @@ function formatDocPage(programName, page, options = {}) {
 		if (cmp !== 0) return cmp;
 		return a.index - b.index;
 	}).map(({ section }) => section);
+	if (environmentSection != null) sections.push(environmentSection);
 	for (const section of sections) {
 		if (section.entries.length < 1) continue;
 		output += "\n";
@@ -421,7 +486,7 @@ function formatDocPage(programName, page, options = {}) {
 			const extraTermOffset = descColumnWidth != null ? Math.max(0, termVisibleWidth - effectiveTermWidth) : 0;
 			const descFormatOptions = {
 				colors: options.colors,
-				quotes: !options.colors,
+				quotes: section === environmentSection ? false : !options.colors,
 				maxWidth: descColumnWidth,
 				initialWidth: extraTermOffset > 0 ? extraTermOffset : void 0
 			};
@@ -465,6 +530,10 @@ function formatDocPage(programName, page, options = {}) {
 				}
 				appendAnnotation(truncatedTerms, annotation("choices"), choicesStyle, choicesAmbient, false);
 			}
+			if (showInlineEnvironment) {
+				const content = environmentContent(entry);
+				if (hasContent(content)) appendAnnotation(content, annotation("environment"), environmentStyle, environmentAmbient, false);
+			}
 			const paddedTerm = ansiAwareRightPad(term, effectiveTermWidth);
 			output += `${" ".repeat(termIndent)}${multilineReplacement ? indentLines(paddedTerm, termIndent) : paddedTerm}${description === "" ? "" : `  ${indentLines(description, termIndent + effectiveTermWidth + 2)}`}\n`;
 		}
@@ -525,4 +594,4 @@ function ansiAwareRightPad(text$1, length, char = " ") {
 }
 
 //#endregion
-export { cloneDocEntry, deduplicateDocEntries, deduplicateDocFragments, formatDocPage, isDocEntryHidden };
+export { cloneDocEntry, deduplicateDocEntries, deduplicateDocFragments, deriveEnvironmentSection, formatDocPage, isDocEntryHidden };

package/dist/facade.cjs

@@ -818,7 +818,7 @@ function runParser(parserOrProgram, programNameOrArgs, argsOrOptions, optionsPar
 		options = optionsParam ?? {};
 	}
 	require_validate.validateProgramName(programName);
-	const { colors, messageFormatter, theme: requestedTheme, maxWidth: requestedMaxWidth, termWidth, showDefault, showChoices, sectionOrder, helpSections, showUsage, usageLine, commandList = "recursive", aboveError = "usage", onError = () => {
+	const { colors, messageFormatter, theme: requestedTheme, maxWidth: requestedMaxWidth, termWidth, showDefault, showChoices, showEnvironment, sectionOrder, helpSections, showUsage, usageLine, commandList = "recursive", aboveError = "usage", onError = () => {
 		throw new RunParserError("Failed to parse command line arguments.");
 	}, stderr = console.error, stdout = console.log, brief, description, examples, author, bugs, footer } = options;
 	let maxWidth = requestedMaxWidth;
@@ -1033,6 +1033,7 @@ function runParser(parserOrProgram, programNameOrArgs, argsOrOptions, optionsPar
 							termWidth,
 							showDefault,
 							showChoices,
+							showEnvironment,
 							sectionOrder,
 							showUsage
 						})));
@@ -1110,6 +1111,7 @@ function runParser(parserOrProgram, programNameOrArgs, argsOrOptions, optionsPar
 							termWidth,
 							showDefault,
 							showChoices,
+							showEnvironment,
 							sectionOrder,
 							showUsage
 						})));

package/dist/facade.d.cts

@@ -1,7 +1,7 @@
 import { Message, MessageFormatter } from "./message.cjs";
 import { TerminalTheme } from "./terminal.cjs";
 import { HiddenVisibility, OptionName, Usage } from "./usage.cjs";
-import { DocPage, DocSection, ShowChoicesOptions, ShowDefaultOptions } from "./doc.cjs";
+import { DocPage, DocSection, ShowChoicesOptions, ShowDefaultOptions, ShowEnvironmentOptions } from "./doc.cjs";
 import { InferMode, InferValue, Mode, ModeValue, Parser } from "./internal/parser.cjs";
 import { ShellCompletion } from "./completion.cjs";
 import { ParserValuePlaceholder, SourceContext, SourceContextRequest } from "./context.cjs";
@@ -148,6 +148,12 @@ interface RunOptions<THelp, TError> {
    * @since 0.10.0
    */
   readonly showChoices?: boolean | ShowChoicesOptions;
+  /**
+   * Displays declared environment bindings in help. `true` selects inline
+   * annotations; an object can select a section or both. Defaults to `false`.
+   * Also applies to full help above errors. @since 1.4.0
+   */
+  readonly showEnvironment?: boolean | ShowEnvironmentOptions;
   /**
    * Whether to include the usage synopsis in full help output.
    *

package/dist/facade.d.ts

@@ -1,7 +1,7 @@
 import { Message, MessageFormatter } from "./message.js";
 import { TerminalTheme } from "./terminal.js";
 import { HiddenVisibility, OptionName, Usage } from "./usage.js";
-import { DocPage, DocSection, ShowChoicesOptions, ShowDefaultOptions } from "./doc.js";
+import { DocPage, DocSection, ShowChoicesOptions, ShowDefaultOptions, ShowEnvironmentOptions } from "./doc.js";
 import { InferMode, InferValue, Mode, ModeValue, Parser } from "./internal/parser.js";
 import { ShellCompletion } from "./completion.js";
 import { ParserValuePlaceholder, SourceContext, SourceContextRequest } from "./context.js";
@@ -148,6 +148,12 @@ interface RunOptions<THelp, TError> {
    * @since 0.10.0
    */
   readonly showChoices?: boolean | ShowChoicesOptions;
+  /**
+   * Displays declared environment bindings in help. `true` selects inline
+   * annotations; an object can select a section or both. Defaults to `false`.
+   * Also applies to full help above errors. @since 1.4.0
+   */
+  readonly showEnvironment?: boolean | ShowEnvironmentOptions;
   /**
    * Whether to include the usage synopsis in full help output.
    *

package/dist/facade.js

@@ -818,7 +818,7 @@ function runParser(parserOrProgram, programNameOrArgs, argsOrOptions, optionsPar
 		options = optionsParam ?? {};
 	}
 	validateProgramName(programName);
-	const { colors, messageFormatter, theme: requestedTheme, maxWidth: requestedMaxWidth, termWidth, showDefault, showChoices, sectionOrder, helpSections, showUsage, usageLine, commandList = "recursive", aboveError = "usage", onError = () => {
+	const { colors, messageFormatter, theme: requestedTheme, maxWidth: requestedMaxWidth, termWidth, showDefault, showChoices, showEnvironment, sectionOrder, helpSections, showUsage, usageLine, commandList = "recursive", aboveError = "usage", onError = () => {
 		throw new RunParserError("Failed to parse command line arguments.");
 	}, stderr = console.error, stdout = console.log, brief, description, examples, author, bugs, footer } = options;
 	let maxWidth = requestedMaxWidth;
@@ -1033,6 +1033,7 @@ function runParser(parserOrProgram, programNameOrArgs, argsOrOptions, optionsPar
 							termWidth,
 							showDefault,
 							showChoices,
+							showEnvironment,
 							sectionOrder,
 							showUsage
 						})));
@@ -1110,6 +1111,7 @@ function runParser(parserOrProgram, programNameOrArgs, argsOrOptions, optionsPar
 							termWidth,
 							showDefault,
 							showChoices,
+							showEnvironment,
 							sectionOrder,
 							showUsage
 						})));

package/dist/index.cjs

@@ -40,6 +40,7 @@ exports.deduplicateDocFragments = require_doc.deduplicateDocFragments;
 exports.defaultTerminalTheme = require_terminal.defaultTerminalTheme;
 exports.deferredValue = require_modifiers.deferredValue;
 exports.dependency = require_internal_dependency.dependency;
+exports.deriveEnvironmentSection = require_doc.deriveEnvironmentSection;
 exports.deriveFrom = require_internal_dependency.deriveFrom;
 exports.deriveFromAsync = require_internal_dependency.deriveFromAsync;
 exports.deriveFromSync = require_internal_dependency.deriveFromSync;

package/dist/index.d.cts

@@ -3,7 +3,7 @@ import { NonEmptyString, ensureNonEmptyString, isNonEmptyString } from "./nonemp
 import { Message, MessageFormatOptions, MessageFormatter, MessageFormatterOptions, MessageTerm, ValueSetOptions, commandLine, createMessageFormatter, envVar, formatMessage, lineBreak, link, message, metavar, optionName, optionNames, text, value, valueSet, values } from "./message.cjs";
 import { ErrorLabelTerm, LabelTerm, ProgramNameTerm, SyntaxPunctuationTerm, TerminalColor, TerminalFormatContext, TerminalFormatter, TerminalFragment, TerminalStyle, TerminalTerm, TerminalTheme, defaultTerminalTheme } from "./terminal.cjs";
 import { HiddenVisibility, OptionName, Usage, UsageFormatOptions, UsageTerm, UsageTermFormatOptions, cloneUsage, cloneUsageTerm, extractArgumentMetavars, extractCommandNames, extractLiteralValues, extractOptionNames, formatUsage, formatUsageTerm, isDocHidden, isSuggestionHidden, isUsageHidden, mergeHidden, normalizeUsage } from "./usage.cjs";
-import { DocEntry, DocFragment, DocFragments, DocPage, DocPageFormatOptions, DocSection, ShowChoicesOptions, ShowDefaultOptions, cloneDocEntry, deduplicateDocEntries, deduplicateDocFragments, formatDocPage, isDocEntryHidden } from "./doc.cjs";
+import { DocEntry, DocFragment, DocFragments, DocPage, DocPageFormatOptions, DocSection, ShowChoicesOptions, ShowDefaultOptions, ShowEnvironmentOptions, cloneDocEntry, deduplicateDocEntries, deduplicateDocFragments, deriveEnvironmentSection, formatDocPage, isDocEntryHidden } from "./doc.cjs";
 import { ChoiceOptions, ChoiceOptionsBase, ChoiceOptionsNumber, ChoiceOptionsString, CidrOptions, CidrValue, Color, ColorFormat, ColorOptions, CronExpression, CronExpressionForOptions, CronOptions, DeferredMap, DomainOptions, EmailOptions, FileSizeOptions, FileSizeOptionsBigInt, FileSizeOptionsNumber, FileSizeUnit, FirstOfOptions, FloatOptions, HostnameOptions, IntegerOptionsBigInt, IntegerOptionsNumber, IpOptions, Ipv4Options, Ipv6Options, Json, JsonOptions, KeyValueOptions, LocaleOptions, MacAddressOptions, OriginOptions, PortOptionsBigInt, PortOptionsNumber, PortRangeOptionsBigInt, PortRangeOptionsNumber, PortRangeValueBigInt, PortRangeValueNumber, RegExpOptions, SemVer, SemVerOptionsObject, SemVerOptionsString, SemVerString, SocketAddressOptions, SocketAddressValue, StringOptions, TransformMapping, UrlOptions, Uuid, UuidOptions, ValueParser, ValueParserResult, biject, checkBooleanOption, checkEnumOption, choice, cidr, color, cron, domain, email, fileSize, firstOf, float, hostname, integer, ip, ipv4, ipv6, isValueParser, json, keyValue, locale, macAddress, origin, port, portRange, regExp, semVer, socketAddress, string, transform, url, uuid } from "./valueparser.cjs";
 import { CombineModes, DetailedParseResult, DocState, EffectfulCompletionSession, ExecutionContext, ExecutionPhase, InferMode, InferValue, Mode, ModeIterable, ModeValue, ParseFrame, Parser, ParserContext, ParserResult, Result, Suggestion, createParserContext, getDocPage, getDocPageAsync, getDocPageSync, parse, parseAsync, parseDetailed, parseSync, suggest, suggestAsync, suggestSync } from "./internal/parser.cjs";
 import { ShellCompletion, bash, fish, nu, pwsh, zsh } from "./completion.cjs";
@@ -13,4 +13,4 @@ import { ParserValuePlaceholder, SourceContext, SourceContextRequest } from "./c
 import { AnyDependencySource, CombineMode, CombinedDependencyMode, DependencyMode, DependencySource, DependencySourceInfo, DependencyValue, DependencyValues, DeriveAsyncOptions, DeriveFromAsyncOptions, DeriveFromOptions, DeriveFromSyncOptions, DeriveOptions, DeriveSyncOptions, DerivedValueParser, dependency, deriveFrom, deriveFromAsync, deriveFromSync, getDependencySourceInfo, isDependencySource, isDerivedValueParser } from "./internal/dependency.cjs";
 import { CommandListMode, CommandSubConfig, ContextOptionsParam, ExtractRequiredOptions, HelpSectionsOptions, OptionSubConfig, RunOptions, RunParserError, RunWithOptions, SubstituteParserValue, runParser, runParserAsync, runParserSync, runWith, runWithAsync, runWithSync } from "./facade.cjs";
 import { ArgumentErrorOptions, ArgumentOptions, CommandErrorOptions, CommandOptions, FlagErrorOptions, FlagOptions, NegatableFlagErrorOptions, NegatableFlagNameList, NegatableFlagNames, NegatableFlagOptions, NegatableFlagState, OptionErrorOptions, OptionOptions, OptionState, PassThroughFormat, PassThroughOptions, argument, command, constant, fail, flag, negatableFlag, option, passThrough } from "./primitives.cjs";
-export { type Annotations, AnyDependencySource, ArgumentErrorOptions, ArgumentOptions, ChoiceOptions, ChoiceOptionsBase, ChoiceOptionsNumber, ChoiceOptionsString, CidrOptions, CidrValue, Color, ColorFormat, ColorOptions, CombineMode, CombineModes, CombinedDependencyMode, CommandErrorOptions, CommandListMode, CommandOptions, CommandSubConfig, ConditionalErrorOptions, ConditionalOptions, ContextOptionsParam, CronExpression, CronExpressionForOptions, CronOptions, DeferredMap, DeferredValue, DeferredValueOptions, DeferredValueSource, DependencyMode, DependencySource, DependencySourceInfo, DependencyValue, DependencyValues, DeriveAsyncOptions, DeriveFromAsyncOptions, DeriveFromOptions, DeriveFromSyncOptions, DeriveOptions, DeriveSyncOptions, DerivedValueParser, DetailedParseResult, DocEntry, DocFragment, DocFragments, DocPage, DocPageFormatOptions, DocSection, DocState, DomainOptions, DuplicateOptionError, EffectfulCompletionSession, EmailOptions, ErrorLabelTerm, ExecutionContext, ExecutionPhase, ExtractRequiredOptions, FileSizeOptions, FileSizeOptionsBigInt, FileSizeOptionsNumber, FileSizeUnit, FirstOfOptions, FlagErrorOptions, FlagOptions, FloatOptions, FluentParser, GroupOptions, HelpSectionsOptions, HiddenVisibility, HostnameOptions, InferMode, InferValue, IntegerOptionsBigInt, IntegerOptionsNumber, IpOptions, Ipv4Options, Ipv6Options, Json, JsonOptions, KeyValueOptions, LabelTerm, LocaleOptions, LongestMatchErrorOptions, LongestMatchOptions, MacAddressOptions, MergeOptions, type Message, type MessageFormatOptions, type MessageFormatter, type MessageFormatterOptions, type MessageTerm, Mode, ModeIterable, ModeValue, MultipleErrorOptions, MultipleOptions, NegatableFlagErrorOptions, NegatableFlagNameList, NegatableFlagNames, NegatableFlagOptions, NegatableFlagState, NoMatchContext, NonEmptyString, ObjectErrorOptions, ObjectOptions, OptionErrorOptions, OptionName, OptionOptions, OptionState, OptionSubConfig, OrErrorOptions, OrOptions, OriginOptions, ParseFrame, type ParseOptions, Parser, ParserContext, ParserModifiers, ParserResult, ParserValuePlaceholder, PassThroughFormat, PassThroughOptions, PortOptionsBigInt, PortOptionsNumber, PortRangeOptionsBigInt, PortRangeOptionsNumber, PortRangeValueBigInt, PortRangeValueNumber, ProgramNameTerm, RegExpOptions, Result, RunOptions, RunParserError, RunWithOptions, SemVer, SemVerOptionsObject, SemVerOptionsString, SemVerString, SeqOptions, ShellCompletion, ShowChoicesOptions, ShowDefaultOptions, SocketAddressOptions, SocketAddressValue, SourceContext, SourceContextRequest, StringOptions, SubstituteParserValue, Suggestion, SyntaxPunctuationTerm, TerminalColor, TerminalFormatContext, TerminalFormatter, TerminalFragment, TerminalStyle, TerminalTerm, TerminalTheme, TransformMapping, TupleOptions, UrlOptions, Usage, UsageFormatOptions, UsageTerm, UsageTermFormatOptions, Uuid, UuidOptions, ValueParser, ValueParserResult, type ValueSetOptions, WithDefaultError, WithDefaultOptions, argument, bash, biject, checkBooleanOption, checkEnumOption, choice, cidr, cloneDocEntry, cloneUsage, cloneUsageTerm, color, command, commandLine, concat, conditional, constant, createMessageFormatter, createParserContext, cron, deduplicateDocEntries, deduplicateDocFragments, defaultTerminalTheme, deferredValue, dependency, deriveFrom, deriveFromAsync, deriveFromSync, domain, email, ensureNonEmptyString, envVar, extractArgumentMetavars, extractCommandNames, extractLiteralValues, extractOptionNames, fail, fileSize, firstOf, fish, flag, float, fluent, formatDocPage, formatMessage, formatUsage, formatUsageTerm, getAnnotations, getDependencySourceInfo, getDocPage, getDocPageAsync, getDocPageSync, group, hostname, integer, ip, ipv4, ipv6, isDeferredValue, isDependencySource, isDerivedValueParser, isDocEntryHidden, isDocHidden, isNonEmptyString, isSuggestionHidden, isUsageHidden, isValueParser, json, keyValue, lineBreak, link, locale, longestMatch, macAddress, map, merge, mergeHidden, message, metavar, multiple, negatableFlag, nonEmpty, normalizeUsage, nu, object, option, optionName, optionNames, optional, or, origin, parse, parseAsync, parseDetailed, parseSync, passThrough, port, portRange, pwsh, regExp, runParser, runParserAsync, runParserSync, runWith, runWithAsync, runWithSync, semVer, seq, socketAddress, string, suggest, suggestAsync, suggestSync, text, transform, tuple, url, uuid, value, valueSet, values, withDefault, zsh };
+export { type Annotations, AnyDependencySource, ArgumentErrorOptions, ArgumentOptions, ChoiceOptions, ChoiceOptionsBase, ChoiceOptionsNumber, ChoiceOptionsString, CidrOptions, CidrValue, Color, ColorFormat, ColorOptions, CombineMode, CombineModes, CombinedDependencyMode, CommandErrorOptions, CommandListMode, CommandOptions, CommandSubConfig, ConditionalErrorOptions, ConditionalOptions, ContextOptionsParam, CronExpression, CronExpressionForOptions, CronOptions, DeferredMap, DeferredValue, DeferredValueOptions, DeferredValueSource, DependencyMode, DependencySource, DependencySourceInfo, DependencyValue, DependencyValues, DeriveAsyncOptions, DeriveFromAsyncOptions, DeriveFromOptions, DeriveFromSyncOptions, DeriveOptions, DeriveSyncOptions, DerivedValueParser, DetailedParseResult, DocEntry, DocFragment, DocFragments, DocPage, DocPageFormatOptions, DocSection, DocState, DomainOptions, DuplicateOptionError, EffectfulCompletionSession, EmailOptions, ErrorLabelTerm, ExecutionContext, ExecutionPhase, ExtractRequiredOptions, FileSizeOptions, FileSizeOptionsBigInt, FileSizeOptionsNumber, FileSizeUnit, FirstOfOptions, FlagErrorOptions, FlagOptions, FloatOptions, FluentParser, GroupOptions, HelpSectionsOptions, HiddenVisibility, HostnameOptions, InferMode, InferValue, IntegerOptionsBigInt, IntegerOptionsNumber, IpOptions, Ipv4Options, Ipv6Options, Json, JsonOptions, KeyValueOptions, LabelTerm, LocaleOptions, LongestMatchErrorOptions, LongestMatchOptions, MacAddressOptions, MergeOptions, type Message, type MessageFormatOptions, type MessageFormatter, type MessageFormatterOptions, type MessageTerm, Mode, ModeIterable, ModeValue, MultipleErrorOptions, MultipleOptions, NegatableFlagErrorOptions, NegatableFlagNameList, NegatableFlagNames, NegatableFlagOptions, NegatableFlagState, NoMatchContext, NonEmptyString, ObjectErrorOptions, ObjectOptions, OptionErrorOptions, OptionName, OptionOptions, OptionState, OptionSubConfig, OrErrorOptions, OrOptions, OriginOptions, ParseFrame, type ParseOptions, Parser, ParserContext, ParserModifiers, ParserResult, ParserValuePlaceholder, PassThroughFormat, PassThroughOptions, PortOptionsBigInt, PortOptionsNumber, PortRangeOptionsBigInt, PortRangeOptionsNumber, PortRangeValueBigInt, PortRangeValueNumber, ProgramNameTerm, RegExpOptions, Result, RunOptions, RunParserError, RunWithOptions, SemVer, SemVerOptionsObject, SemVerOptionsString, SemVerString, SeqOptions, ShellCompletion, ShowChoicesOptions, ShowDefaultOptions, ShowEnvironmentOptions, SocketAddressOptions, SocketAddressValue, SourceContext, SourceContextRequest, StringOptions, SubstituteParserValue, Suggestion, SyntaxPunctuationTerm, TerminalColor, TerminalFormatContext, TerminalFormatter, TerminalFragment, TerminalStyle, TerminalTerm, TerminalTheme, TransformMapping, TupleOptions, UrlOptions, Usage, UsageFormatOptions, UsageTerm, UsageTermFormatOptions, Uuid, UuidOptions, ValueParser, ValueParserResult, type ValueSetOptions, WithDefaultError, WithDefaultOptions, argument, bash, biject, checkBooleanOption, checkEnumOption, choice, cidr, cloneDocEntry, cloneUsage, cloneUsageTerm, color, command, commandLine, concat, conditional, constant, createMessageFormatter, createParserContext, cron, deduplicateDocEntries, deduplicateDocFragments, defaultTerminalTheme, deferredValue, dependency, deriveEnvironmentSection, deriveFrom, deriveFromAsync, deriveFromSync, domain, email, ensureNonEmptyString, envVar, extractArgumentMetavars, extractCommandNames, extractLiteralValues, extractOptionNames, fail, fileSize, firstOf, fish, flag, float, fluent, formatDocPage, formatMessage, formatUsage, formatUsageTerm, getAnnotations, getDependencySourceInfo, getDocPage, getDocPageAsync, getDocPageSync, group, hostname, integer, ip, ipv4, ipv6, isDeferredValue, isDependencySource, isDerivedValueParser, isDocEntryHidden, isDocHidden, isNonEmptyString, isSuggestionHidden, isUsageHidden, isValueParser, json, keyValue, lineBreak, link, locale, longestMatch, macAddress, map, merge, mergeHidden, message, metavar, multiple, negatableFlag, nonEmpty, normalizeUsage, nu, object, option, optionName, optionNames, optional, or, origin, parse, parseAsync, parseDetailed, parseSync, passThrough, port, portRange, pwsh, regExp, runParser, runParserAsync, runParserSync, runWith, runWithAsync, runWithSync, semVer, seq, socketAddress, string, suggest, suggestAsync, suggestSync, text, transform, tuple, url, uuid, value, valueSet, values, withDefault, zsh };

package/dist/index.d.ts

@@ -3,7 +3,7 @@ import { NonEmptyString, ensureNonEmptyString, isNonEmptyString } from "./nonemp
 import { Message, MessageFormatOptions, MessageFormatter, MessageFormatterOptions, MessageTerm, ValueSetOptions, commandLine, createMessageFormatter, envVar, formatMessage, lineBreak, link, message, metavar, optionName, optionNames, text, value, valueSet, values } from "./message.js";
 import { ErrorLabelTerm, LabelTerm, ProgramNameTerm, SyntaxPunctuationTerm, TerminalColor, TerminalFormatContext, TerminalFormatter, TerminalFragment, TerminalStyle, TerminalTerm, TerminalTheme, defaultTerminalTheme } from "./terminal.js";
 import { HiddenVisibility, OptionName, Usage, UsageFormatOptions, UsageTerm, UsageTermFormatOptions, cloneUsage, cloneUsageTerm, extractArgumentMetavars, extractCommandNames, extractLiteralValues, extractOptionNames, formatUsage, formatUsageTerm, isDocHidden, isSuggestionHidden, isUsageHidden, mergeHidden, normalizeUsage } from "./usage.js";
-import { DocEntry, DocFragment, DocFragments, DocPage, DocPageFormatOptions, DocSection, ShowChoicesOptions, ShowDefaultOptions, cloneDocEntry, deduplicateDocEntries, deduplicateDocFragments, formatDocPage, isDocEntryHidden } from "./doc.js";
+import { DocEntry, DocFragment, DocFragments, DocPage, DocPageFormatOptions, DocSection, ShowChoicesOptions, ShowDefaultOptions, ShowEnvironmentOptions, cloneDocEntry, deduplicateDocEntries, deduplicateDocFragments, deriveEnvironmentSection, formatDocPage, isDocEntryHidden } from "./doc.js";
 import { ChoiceOptions, ChoiceOptionsBase, ChoiceOptionsNumber, ChoiceOptionsString, CidrOptions, CidrValue, Color, ColorFormat, ColorOptions, CronExpression, CronExpressionForOptions, CronOptions, DeferredMap, DomainOptions, EmailOptions, FileSizeOptions, FileSizeOptionsBigInt, FileSizeOptionsNumber, FileSizeUnit, FirstOfOptions, FloatOptions, HostnameOptions, IntegerOptionsBigInt, IntegerOptionsNumber, IpOptions, Ipv4Options, Ipv6Options, Json, JsonOptions, KeyValueOptions, LocaleOptions, MacAddressOptions, OriginOptions, PortOptionsBigInt, PortOptionsNumber, PortRangeOptionsBigInt, PortRangeOptionsNumber, PortRangeValueBigInt, PortRangeValueNumber, RegExpOptions, SemVer, SemVerOptionsObject, SemVerOptionsString, SemVerString, SocketAddressOptions, SocketAddressValue, StringOptions, TransformMapping, UrlOptions, Uuid, UuidOptions, ValueParser, ValueParserResult, biject, checkBooleanOption, checkEnumOption, choice, cidr, color, cron, domain, email, fileSize, firstOf, float, hostname, integer, ip, ipv4, ipv6, isValueParser, json, keyValue, locale, macAddress, origin, port, portRange, regExp, semVer, socketAddress, string, transform, url, uuid } from "./valueparser.js";
 import { CombineModes, DetailedParseResult, DocState, EffectfulCompletionSession, ExecutionContext, ExecutionPhase, InferMode, InferValue, Mode, ModeIterable, ModeValue, ParseFrame, Parser, ParserContext, ParserResult, Result, Suggestion, createParserContext, getDocPage, getDocPageAsync, getDocPageSync, parse, parseAsync, parseDetailed, parseSync, suggest, suggestAsync, suggestSync } from "./internal/parser.js";
 import { ShellCompletion, bash, fish, nu, pwsh, zsh } from "./completion.js";
@@ -13,4 +13,4 @@ import { ParserValuePlaceholder, SourceContext, SourceContextRequest } from "./c
 import { AnyDependencySource, CombineMode, CombinedDependencyMode, DependencyMode, DependencySource, DependencySourceInfo, DependencyValue, DependencyValues, DeriveAsyncOptions, DeriveFromAsyncOptions, DeriveFromOptions, DeriveFromSyncOptions, DeriveOptions, DeriveSyncOptions, DerivedValueParser, dependency, deriveFrom, deriveFromAsync, deriveFromSync, getDependencySourceInfo, isDependencySource, isDerivedValueParser } from "./internal/dependency.js";
 import { CommandListMode, CommandSubConfig, ContextOptionsParam, ExtractRequiredOptions, HelpSectionsOptions, OptionSubConfig, RunOptions, RunParserError, RunWithOptions, SubstituteParserValue, runParser, runParserAsync, runParserSync, runWith, runWithAsync, runWithSync } from "./facade.js";
 import { ArgumentErrorOptions, ArgumentOptions, CommandErrorOptions, CommandOptions, FlagErrorOptions, FlagOptions, NegatableFlagErrorOptions, NegatableFlagNameList, NegatableFlagNames, NegatableFlagOptions, NegatableFlagState, OptionErrorOptions, OptionOptions, OptionState, PassThroughFormat, PassThroughOptions, argument, command, constant, fail, flag, negatableFlag, option, passThrough } from "./primitives.js";
-export { type Annotations, AnyDependencySource, ArgumentErrorOptions, ArgumentOptions, ChoiceOptions, ChoiceOptionsBase, ChoiceOptionsNumber, ChoiceOptionsString, CidrOptions, CidrValue, Color, ColorFormat, ColorOptions, CombineMode, CombineModes, CombinedDependencyMode, CommandErrorOptions, CommandListMode, CommandOptions, CommandSubConfig, ConditionalErrorOptions, ConditionalOptions, ContextOptionsParam, CronExpression, CronExpressionForOptions, CronOptions, DeferredMap, DeferredValue, DeferredValueOptions, DeferredValueSource, DependencyMode, DependencySource, DependencySourceInfo, DependencyValue, DependencyValues, DeriveAsyncOptions, DeriveFromAsyncOptions, DeriveFromOptions, DeriveFromSyncOptions, DeriveOptions, DeriveSyncOptions, DerivedValueParser, DetailedParseResult, DocEntry, DocFragment, DocFragments, DocPage, DocPageFormatOptions, DocSection, DocState, DomainOptions, DuplicateOptionError, EffectfulCompletionSession, EmailOptions, ErrorLabelTerm, ExecutionContext, ExecutionPhase, ExtractRequiredOptions, FileSizeOptions, FileSizeOptionsBigInt, FileSizeOptionsNumber, FileSizeUnit, FirstOfOptions, FlagErrorOptions, FlagOptions, FloatOptions, FluentParser, GroupOptions, HelpSectionsOptions, HiddenVisibility, HostnameOptions, InferMode, InferValue, IntegerOptionsBigInt, IntegerOptionsNumber, IpOptions, Ipv4Options, Ipv6Options, Json, JsonOptions, KeyValueOptions, LabelTerm, LocaleOptions, LongestMatchErrorOptions, LongestMatchOptions, MacAddressOptions, MergeOptions, type Message, type MessageFormatOptions, type MessageFormatter, type MessageFormatterOptions, type MessageTerm, Mode, ModeIterable, ModeValue, MultipleErrorOptions, MultipleOptions, NegatableFlagErrorOptions, NegatableFlagNameList, NegatableFlagNames, NegatableFlagOptions, NegatableFlagState, NoMatchContext, NonEmptyString, ObjectErrorOptions, ObjectOptions, OptionErrorOptions, OptionName, OptionOptions, OptionState, OptionSubConfig, OrErrorOptions, OrOptions, OriginOptions, ParseFrame, type ParseOptions, Parser, ParserContext, ParserModifiers, ParserResult, ParserValuePlaceholder, PassThroughFormat, PassThroughOptions, PortOptionsBigInt, PortOptionsNumber, PortRangeOptionsBigInt, PortRangeOptionsNumber, PortRangeValueBigInt, PortRangeValueNumber, ProgramNameTerm, RegExpOptions, Result, RunOptions, RunParserError, RunWithOptions, SemVer, SemVerOptionsObject, SemVerOptionsString, SemVerString, SeqOptions, ShellCompletion, ShowChoicesOptions, ShowDefaultOptions, SocketAddressOptions, SocketAddressValue, SourceContext, SourceContextRequest, StringOptions, SubstituteParserValue, Suggestion, SyntaxPunctuationTerm, TerminalColor, TerminalFormatContext, TerminalFormatter, TerminalFragment, TerminalStyle, TerminalTerm, TerminalTheme, TransformMapping, TupleOptions, UrlOptions, Usage, UsageFormatOptions, UsageTerm, UsageTermFormatOptions, Uuid, UuidOptions, ValueParser, ValueParserResult, type ValueSetOptions, WithDefaultError, WithDefaultOptions, argument, bash, biject, checkBooleanOption, checkEnumOption, choice, cidr, cloneDocEntry, cloneUsage, cloneUsageTerm, color, command, commandLine, concat, conditional, constant, createMessageFormatter, createParserContext, cron, deduplicateDocEntries, deduplicateDocFragments, defaultTerminalTheme, deferredValue, dependency, deriveFrom, deriveFromAsync, deriveFromSync, domain, email, ensureNonEmptyString, envVar, extractArgumentMetavars, extractCommandNames, extractLiteralValues, extractOptionNames, fail, fileSize, firstOf, fish, flag, float, fluent, formatDocPage, formatMessage, formatUsage, formatUsageTerm, getAnnotations, getDependencySourceInfo, getDocPage, getDocPageAsync, getDocPageSync, group, hostname, integer, ip, ipv4, ipv6, isDeferredValue, isDependencySource, isDerivedValueParser, isDocEntryHidden, isDocHidden, isNonEmptyString, isSuggestionHidden, isUsageHidden, isValueParser, json, keyValue, lineBreak, link, locale, longestMatch, macAddress, map, merge, mergeHidden, message, metavar, multiple, negatableFlag, nonEmpty, normalizeUsage, nu, object, option, optionName, optionNames, optional, or, origin, parse, parseAsync, parseDetailed, parseSync, passThrough, port, portRange, pwsh, regExp, runParser, runParserAsync, runParserSync, runWith, runWithAsync, runWithSync, semVer, seq, socketAddress, string, suggest, suggestAsync, suggestSync, text, transform, tuple, url, uuid, value, valueSet, values, withDefault, zsh };
+export { type Annotations, AnyDependencySource, ArgumentErrorOptions, ArgumentOptions, ChoiceOptions, ChoiceOptionsBase, ChoiceOptionsNumber, ChoiceOptionsString, CidrOptions, CidrValue, Color, ColorFormat, ColorOptions, CombineMode, CombineModes, CombinedDependencyMode, CommandErrorOptions, CommandListMode, CommandOptions, CommandSubConfig, ConditionalErrorOptions, ConditionalOptions, ContextOptionsParam, CronExpression, CronExpressionForOptions, CronOptions, DeferredMap, DeferredValue, DeferredValueOptions, DeferredValueSource, DependencyMode, DependencySource, DependencySourceInfo, DependencyValue, DependencyValues, DeriveAsyncOptions, DeriveFromAsyncOptions, DeriveFromOptions, DeriveFromSyncOptions, DeriveOptions, DeriveSyncOptions, DerivedValueParser, DetailedParseResult, DocEntry, DocFragment, DocFragments, DocPage, DocPageFormatOptions, DocSection, DocState, DomainOptions, DuplicateOptionError, EffectfulCompletionSession, EmailOptions, ErrorLabelTerm, ExecutionContext, ExecutionPhase, ExtractRequiredOptions, FileSizeOptions, FileSizeOptionsBigInt, FileSizeOptionsNumber, FileSizeUnit, FirstOfOptions, FlagErrorOptions, FlagOptions, FloatOptions, FluentParser, GroupOptions, HelpSectionsOptions, HiddenVisibility, HostnameOptions, InferMode, InferValue, IntegerOptionsBigInt, IntegerOptionsNumber, IpOptions, Ipv4Options, Ipv6Options, Json, JsonOptions, KeyValueOptions, LabelTerm, LocaleOptions, LongestMatchErrorOptions, LongestMatchOptions, MacAddressOptions, MergeOptions, type Message, type MessageFormatOptions, type MessageFormatter, type MessageFormatterOptions, type MessageTerm, Mode, ModeIterable, ModeValue, MultipleErrorOptions, MultipleOptions, NegatableFlagErrorOptions, NegatableFlagNameList, NegatableFlagNames, NegatableFlagOptions, NegatableFlagState, NoMatchContext, NonEmptyString, ObjectErrorOptions, ObjectOptions, OptionErrorOptions, OptionName, OptionOptions, OptionState, OptionSubConfig, OrErrorOptions, OrOptions, OriginOptions, ParseFrame, type ParseOptions, Parser, ParserContext, ParserModifiers, ParserResult, ParserValuePlaceholder, PassThroughFormat, PassThroughOptions, PortOptionsBigInt, PortOptionsNumber, PortRangeOptionsBigInt, PortRangeOptionsNumber, PortRangeValueBigInt, PortRangeValueNumber, ProgramNameTerm, RegExpOptions, Result, RunOptions, RunParserError, RunWithOptions, SemVer, SemVerOptionsObject, SemVerOptionsString, SemVerString, SeqOptions, ShellCompletion, ShowChoicesOptions, ShowDefaultOptions, ShowEnvironmentOptions, SocketAddressOptions, SocketAddressValue, SourceContext, SourceContextRequest, StringOptions, SubstituteParserValue, Suggestion, SyntaxPunctuationTerm, TerminalColor, TerminalFormatContext, TerminalFormatter, TerminalFragment, TerminalStyle, TerminalTerm, TerminalTheme, TransformMapping, TupleOptions, UrlOptions, Usage, UsageFormatOptions, UsageTerm, UsageTermFormatOptions, Uuid, UuidOptions, ValueParser, ValueParserResult, type ValueSetOptions, WithDefaultError, WithDefaultOptions, argument, bash, biject, checkBooleanOption, checkEnumOption, choice, cidr, cloneDocEntry, cloneUsage, cloneUsageTerm, color, command, commandLine, concat, conditional, constant, createMessageFormatter, createParserContext, cron, deduplicateDocEntries, deduplicateDocFragments, defaultTerminalTheme, deferredValue, dependency, deriveEnvironmentSection, deriveFrom, deriveFromAsync, deriveFromSync, domain, email, ensureNonEmptyString, envVar, extractArgumentMetavars, extractCommandNames, extractLiteralValues, extractOptionNames, fail, fileSize, firstOf, fish, flag, float, fluent, formatDocPage, formatMessage, formatUsage, formatUsageTerm, getAnnotations, getDependencySourceInfo, getDocPage, getDocPageAsync, getDocPageSync, group, hostname, integer, ip, ipv4, ipv6, isDeferredValue, isDependencySource, isDerivedValueParser, isDocEntryHidden, isDocHidden, isNonEmptyString, isSuggestionHidden, isUsageHidden, isValueParser, json, keyValue, lineBreak, link, locale, longestMatch, macAddress, map, merge, mergeHidden, message, metavar, multiple, negatableFlag, nonEmpty, normalizeUsage, nu, object, option, optionName, optionNames, optional, or, origin, parse, parseAsync, parseDetailed, parseSync, passThrough, port, portRange, pwsh, regExp, runParser, runParserAsync, runParserSync, runWith, runWithAsync, runWithSync, semVer, seq, socketAddress, string, suggest, suggestAsync, suggestSync, text, transform, tuple, url, uuid, value, valueSet, values, withDefault, zsh };

package/dist/index.js

@@ -2,7 +2,7 @@ import { getAnnotations } from "./internal/annotations.js";
 import { defaultTerminalTheme } from "./terminal.js";
 import { cloneUsage, cloneUsageTerm, extractArgumentMetavars, extractCommandNames, extractLiteralValues, extractOptionNames, formatUsage, formatUsageTerm, isDocHidden, isSuggestionHidden, isUsageHidden, mergeHidden, normalizeUsage } from "./usage.js";
 import { commandLine, createMessageFormatter, envVar, formatMessage, lineBreak, link, message, metavar, optionName, optionNames, text, value, valueSet, values } from "./message.js";
-import { cloneDocEntry, deduplicateDocEntries, deduplicateDocFragments, formatDocPage, isDocEntryHidden } from "./doc.js";
+import { cloneDocEntry, deduplicateDocEntries, deduplicateDocFragments, deriveEnvironmentSection, formatDocPage, isDocEntryHidden } from "./doc.js";
 import { dependency, deriveFrom, deriveFromAsync, deriveFromSync, getDependencySourceInfo, isDependencySource, isDerivedValueParser } from "./internal/dependency.js";
 import { createParserContext, getDocPage, getDocPageAsync, getDocPageSync, parse, parseAsync, parseDetailed, parseSync, suggest, suggestAsync, suggestSync } from "./internal/parser.js";
 import { bash, fish, nu, pwsh, zsh } from "./completion.js";
@@ -13,4 +13,4 @@ import { biject, checkBooleanOption, checkEnumOption, choice, cidr, color, cron,
 import { argument, command, constant, fail, flag, negatableFlag, option, passThrough } from "./primitives.js";
 import { RunParserError, runParser, runParserAsync, runParserSync, runWith, runWithAsync, runWithSync } from "./facade.js";
 
-export { DuplicateOptionError, RunParserError, WithDefaultError, argument, bash, biject, checkBooleanOption, checkEnumOption, choice, cidr, cloneDocEntry, cloneUsage, cloneUsageTerm, color, command, commandLine, concat, conditional, constant, createMessageFormatter, createParserContext, cron, deduplicateDocEntries, deduplicateDocFragments, defaultTerminalTheme, deferredValue, dependency, deriveFrom, deriveFromAsync, deriveFromSync, domain, email, ensureNonEmptyString, envVar, extractArgumentMetavars, extractCommandNames, extractLiteralValues, extractOptionNames, fail, fileSize, firstOf, fish, flag, float, fluent, formatDocPage, formatMessage, formatUsage, formatUsageTerm, getAnnotations, getDependencySourceInfo, getDocPage, getDocPageAsync, getDocPageSync, group, hostname, integer, ip, ipv4, ipv6, isDeferredValue, isDependencySource, isDerivedValueParser, isDocEntryHidden, isDocHidden, isNonEmptyString, isSuggestionHidden, isUsageHidden, isValueParser, json, keyValue, lineBreak, link, locale, longestMatch, macAddress, map, merge, mergeHidden, message, metavar, multiple, negatableFlag, nonEmpty, normalizeUsage, nu, object, option, optionName, optionNames, optional, or, origin, parse, parseAsync, parseDetailed, parseSync, passThrough, port, portRange, pwsh, regExp, runParser, runParserAsync, runParserSync, runWith, runWithAsync, runWithSync, semVer, seq, socketAddress, string, suggest, suggestAsync, suggestSync, text, transform, tuple, url, uuid, value, valueSet, values, withDefault, zsh };
+export { DuplicateOptionError, RunParserError, WithDefaultError, argument, bash, biject, checkBooleanOption, checkEnumOption, choice, cidr, cloneDocEntry, cloneUsage, cloneUsageTerm, color, command, commandLine, concat, conditional, constant, createMessageFormatter, createParserContext, cron, deduplicateDocEntries, deduplicateDocFragments, defaultTerminalTheme, deferredValue, dependency, deriveEnvironmentSection, deriveFrom, deriveFromAsync, deriveFromSync, domain, email, ensureNonEmptyString, envVar, extractArgumentMetavars, extractCommandNames, extractLiteralValues, extractOptionNames, fail, fileSize, firstOf, fish, flag, float, fluent, formatDocPage, formatMessage, formatUsage, formatUsageTerm, getAnnotations, getDependencySourceInfo, getDocPage, getDocPageAsync, getDocPageSync, group, hostname, integer, ip, ipv4, ipv6, isDeferredValue, isDependencySource, isDerivedValueParser, isDocEntryHidden, isDocHidden, isNonEmptyString, isSuggestionHidden, isUsageHidden, isValueParser, json, keyValue, lineBreak, link, locale, longestMatch, macAddress, map, merge, mergeHidden, message, metavar, multiple, negatableFlag, nonEmpty, normalizeUsage, nu, object, option, optionName, optionNames, optional, or, origin, parse, parseAsync, parseDetailed, parseSync, passThrough, port, portRange, pwsh, regExp, runParser, runParserAsync, runParserSync, runWith, runWithAsync, runWithSync, semVer, seq, socketAddress, string, suggest, suggestAsync, suggestSync, text, transform, tuple, url, uuid, value, valueSet, values, withDefault, zsh };

package/dist/terminal-internal.cjs

@@ -287,7 +287,8 @@ function cacheTerminalTheme(theme = {}) {
 		errorLabel: cache(theme.errorLabel ?? require_terminal.defaultTerminalTheme.errorLabel),
 		annotationStyles: theme.annotationStyles == null ? void 0 : {
 			default: theme.annotationStyles.default == null ? void 0 : { ...theme.annotationStyles.default },
-			choices: theme.annotationStyles.choices == null ? void 0 : { ...theme.annotationStyles.choices }
+			choices: theme.annotationStyles.choices == null ? void 0 : { ...theme.annotationStyles.choices },
+			environment: theme.annotationStyles.environment == null ? void 0 : { ...theme.annotationStyles.environment }
 		}
 	};
 }

package/dist/terminal-internal.js

@@ -287,7 +287,8 @@ function cacheTerminalTheme(theme = {}) {
 		errorLabel: cache(theme.errorLabel ?? defaultTerminalTheme.errorLabel),
 		annotationStyles: theme.annotationStyles == null ? void 0 : {
 			default: theme.annotationStyles.default == null ? void 0 : { ...theme.annotationStyles.default },
-			choices: theme.annotationStyles.choices == null ? void 0 : { ...theme.annotationStyles.choices }
+			choices: theme.annotationStyles.choices == null ? void 0 : { ...theme.annotationStyles.choices },
+			environment: theme.annotationStyles.environment == null ? void 0 : { ...theme.annotationStyles.environment }
 		}
 	};
 }

package/dist/terminal.d.cts

@@ -114,6 +114,8 @@ type TerminalTheme = Partial<Formatters> & {
   readonly annotationStyles?: {
     readonly default?: TerminalStyle;
     readonly choices?: TerminalStyle;
+    /** Environment annotation style. @since 1.4.0 */
+    readonly environment?: TerminalStyle;
   };
 };
 /**

package/dist/terminal.d.ts

@@ -114,6 +114,8 @@ type TerminalTheme = Partial<Formatters> & {
   readonly annotationStyles?: {
     readonly default?: TerminalStyle;
     readonly choices?: TerminalStyle;
+    /** Environment annotation style. @since 1.4.0 */
+    readonly environment?: TerminalStyle;
   };
 };
 /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@optique/core",
-  "version": "1.4.0-dev.2628",
+  "version": "1.4.0-dev.2631",
   "description": "Type-safe combinatorial command-line interface parser",
   "keywords": [
     "CLI",
@@ -237,7 +237,7 @@
   },
   "sideEffects": false,
   "devDependencies": {
-    "@optique/env": "1.4.0-dev.2628+867c4f91",
+    "@optique/env": "1.4.0-dev.2631+0f2bd6a0",
     "@types/node": "^24.0.0",
     "fast-check": "^4.7.0",
     "tsdown": "^0.13.0",

package/skills/optique/SKILL.md

@@ -245,10 +245,10 @@ Common mistakes checklist
     `nonEmpty()` when at least one value is required.
  -  Do not confuse free-order parsing with `seq()`. Most constructs let child
     parsers compete by priority; use `seq()` only for truly ordered grammars.
- -  Do not concatenate plain strings for errors or descriptions. Use structured
-    `message` values.
+ -  Use structured `message` values for errors and descriptions.
  -  Register contexts for `bindEnv()`, `bindConfig()`, `bindDerivedDefault()`,
     and `bindKeyring()` in the runner's `contexts` option.
+ -  Show `bindEnv()` names in help with `showEnvironment: true`.
  -  Do not flatten a multi-level dependency graph into duplicated one-level
     factories. Wrap each derived value that becomes a later source with
     `dependency()` and derive the next parser from it.