@optique/run 1.0.0-dev.908 → 1.0.0

package/README.md

@@ -23,6 +23,12 @@ Use *@optique/core* instead when:
  -  Working in environments without `process` (browsers, web workers)
  -  Building reusable parser components
 
+Built-in help, version, and completion are parser-aware.  Optique only
+intercepts `help`, `version`, `completion`, `--help`, `--version`,
+`--completion`, and configured aliases when the user parser leaves them
+unconsumed.  If your parser uses the same token sequence as ordinary
+data, the parse result wins.
+
 
 Installation
 ------------

package/dist/run.cjs

@@ -32,17 +32,17 @@ function run(parserOrProgram, options = {}) {
 	return runImpl(parserOrProgram, options);
 }
 function runSync(parserOrProgram, options = {}) {
+	const parserToCheck = "parser" in parserOrProgram && "metadata" in parserOrProgram ? parserOrProgram.parser : parserOrProgram;
+	if (parserToCheck.mode !== "sync") throw new TypeError("Cannot use an async parser with runSync(). Use run() or runAsync() instead.");
 	const contexts = options.contexts;
 	if (contexts && contexts.length > 0) {
 		const resolved = resolveProgramInput(parserOrProgram, options);
 		const { parser, programMetadata } = resolved;
 		options = resolved.options;
 		const { programName, args, coreOptions } = buildCoreOptions(options, programMetadata);
-		const contextOptions = {};
-		for (const key of Object.keys(options)) if (!knownRunOptionsKeys.has(key)) contextOptions[key] = options[key];
 		const runWithOptions = {
 			...coreOptions,
-			...contextOptions,
+			contextOptions: options.contextOptions,
 			args
 		};
 		return (0, __optique_core_facade.runWithSync)(parser, programName, contexts, runWithOptions);
@@ -173,35 +173,6 @@ function buildCoreOptions(options, programMetadata) {
 		coreOptions
 	};
 }
-/**
-* Set of known RunOptions field names.  Used by `runImpl()` to separate
-* RunOptions fields from context-required options via rest-spread.
-*/
-const knownRunOptionsKeyList = [
-	"programName",
-	"args",
-	"stdout",
-	"stderr",
-	"onExit",
-	"colors",
-	"maxWidth",
-	"showDefault",
-	"showChoices",
-	"sectionOrder",
-	"help",
-	"version",
-	"completion",
-	"aboveError",
-	"errorExitCode",
-	"brief",
-	"description",
-	"examples",
-	"author",
-	"bugs",
-	"footer",
-	"contexts"
-];
-const knownRunOptionsKeys = new Set(knownRunOptionsKeyList);
 function runImpl(parserOrProgram, options = {}) {
 	const resolved = resolveProgramInput(parserOrProgram, options);
 	const { parser, programMetadata } = resolved;
@@ -209,11 +180,9 @@ function runImpl(parserOrProgram, options = {}) {
 	const contexts = options.contexts;
 	if (contexts && contexts.length > 0) {
 		const { programName: programName$1, args: args$1, coreOptions: coreOptions$1 } = buildCoreOptions(options, programMetadata);
-		const contextOptions = {};
-		for (const key of Object.keys(options)) if (!knownRunOptionsKeys.has(key)) contextOptions[key] = options[key];
 		const runWithOptions = {
 			...coreOptions$1,
-			...contextOptions,
+			contextOptions: options.contextOptions,
 			args: args$1
 		};
 		return (0, __optique_core_facade.runWith)(parser, programName$1, contexts, runWithOptions);

package/dist/run.d.cts

@@ -1,6 +1,6 @@
 import { ShellCompletion } from "@optique/core/completion";
 import { SourceContext } from "@optique/core/context";
-import { CommandSubConfig, ExtractRequiredOptions, OptionSubConfig } from "@optique/core/facade";
+import { CommandSubConfig, ContextOptionsParam, OptionSubConfig } from "@optique/core/facade";
 import { InferMode, InferValue, Mode, ModeValue, Parser } from "@optique/core/parser";
 import { Program } from "@optique/core/program";
 import { DocSection, ShowChoicesOptions, ShowDefaultOptions } from "@optique/core/doc";
@@ -225,6 +225,15 @@ interface RunOptions {
    * @since 1.0.0
    */
   readonly contexts?: readonly SourceContext<unknown>[];
+  /**
+   * Options to forward to source contexts.  When contexts declare
+   * required options (via `$requiredOptions`), pass them here to
+   * avoid name collisions with runner-level options such as `help`,
+   * `programName`, or `version`.
+   *
+   * @since 1.0.0
+   */
+  readonly contextOptions?: Record<string, unknown>;
 }
 /**
  * Rejects context tuples that are statically known to be empty so those calls
@@ -323,23 +332,25 @@ type AcceptExactOptionalRunOptions<TOptions> = [TOptions] extends [RunOptions |
  * // myapp --format=<TAB>                                # Use completion
  * ```
  *
- * @since 0.11.0 Added support for {@link Program} objects.
+ * Supports {@link Program} objects.
+ *
+ * @since 1.0.0
  */
 declare function run<T extends Parser<Mode, unknown, unknown>, const TContexts extends NonEmptySourceContexts>(parser: T, options: RunOptions & {
   readonly contexts: TContexts;
-} & ExtractRequiredOptions<TContexts, InferValue<T>>): Promise<InferValue<T>>;
+} & ContextOptionsParam<TContexts, InferValue<T>>): Promise<InferValue<T>>;
 declare function run<T extends Parser<Mode, unknown, unknown>, const TContexts extends readonly SourceContext<unknown>[]>(parser: T, options: RunOptions & {
   readonly contexts: TContexts;
-} & RejectEmptyContexts<TContexts> & ExtractRequiredOptions<TContexts, InferValue<T>>): ModeValue<InferMode<T>, InferValue<T>> | Promise<InferValue<T>>;
+} & RejectEmptyContexts<TContexts> & ContextOptionsParam<TContexts, InferValue<T>>): ModeValue<InferMode<T>, InferValue<T>> | Promise<InferValue<T>>;
 declare function run<M extends Mode, T, const TContexts extends NonEmptySourceContexts>(program: Program<M, T>, options: RunOptions & {
   readonly contexts: TContexts;
-} & ExtractRequiredOptions<TContexts, T>): Promise<T>;
+} & ContextOptionsParam<TContexts, T>): Promise<T>;
 declare function run<T, const TContexts extends readonly SourceContext<unknown>[]>(program: Program<"sync", T>, options: RunOptions & {
   readonly contexts: TContexts;
-} & RejectEmptyContexts<TContexts> & ExtractRequiredOptions<TContexts, T>): T | Promise<T>;
+} & RejectEmptyContexts<TContexts> & ContextOptionsParam<TContexts, T>): T | Promise<T>;
 declare function run<T, const TContexts extends readonly SourceContext<unknown>[]>(program: Program<"async", T>, options: RunOptions & {
   readonly contexts: TContexts;
-} & RejectEmptyContexts<TContexts> & ExtractRequiredOptions<TContexts, T>): Promise<T>;
+} & RejectEmptyContexts<TContexts> & ContextOptionsParam<TContexts, T>): Promise<T>;
 declare function run<T, const TOptions extends RunOptions | undefined>(program: Program<"sync", T>, options?: TOptions & RejectContextfulOptions<TOptions> & RejectUnknownRunOptionKeys<TOptions>): T;
 declare function run<T, TOptions extends RunOptions>(program: Program<"sync", T>, options: TOptions & AcceptExactRunOptions<TOptions>): T | Promise<T>;
 declare function run<T, const TOptions extends RunOptions | undefined>(program: Program<"async", T>, options?: TOptions & RejectContextfulOptions<TOptions> & RejectUnknownRunOptionKeys<TOptions>): Promise<T>;
@@ -358,14 +369,16 @@ declare function run<T extends Parser<Mode, unknown, unknown>>(parser: T, option
  * @param parser The synchronous command-line parser to execute.
  * @param options Configuration options for customizing behavior.
  * @returns The parsed result if successful.
+ * @throws {TypeError} If an async parser (or a {@link Program} wrapping one)
+ * is passed at runtime.  Use {@link run} or {@link runAsync} instead.
  * @since 0.9.0
  */
 declare function runSync<T extends Parser<"sync", unknown, unknown>, TContexts extends readonly SourceContext<unknown>[]>(parser: T, options: RunOptions & {
   readonly contexts: TContexts;
-} & ExtractRequiredOptions<TContexts, InferValue<T>>): InferValue<T>;
+} & ContextOptionsParam<TContexts, InferValue<T>>): InferValue<T>;
 declare function runSync<T, const TContexts extends readonly SourceContext<unknown>[]>(program: Program<"sync", T>, options: RunOptions & {
   readonly contexts: TContexts;
-} & RejectEmptyContexts<TContexts> & ExtractRequiredOptions<TContexts, T>): T;
+} & RejectEmptyContexts<TContexts> & ContextOptionsParam<TContexts, T>): T;
 declare function runSync<T, const TOptions extends RunOptions | undefined>(program: Program<"sync", T>, options?: TOptions & RejectContextfulOptions<TOptions> & RejectUnknownRunOptionKeys<TOptions>): T;
 declare function runSync<T, TOptions extends RunOptions>(program: Program<"sync", T>, options: TOptions & AcceptExactRunOptions<TOptions>): T;
 declare function runSync<T, TOptions extends RunOptions | undefined>(program: Program<"sync", T>, options: TOptions & AcceptExactOptionalRunOptions<TOptions>): T;
@@ -385,10 +398,10 @@ declare function runSync<T extends Parser<"sync", unknown, unknown>>(parser: T,
  */
 declare function runAsync<T extends Parser<Mode, unknown, unknown>, TContexts extends readonly SourceContext<unknown>[]>(parser: T, options: RunOptions & {
   readonly contexts: TContexts;
-} & ExtractRequiredOptions<TContexts, InferValue<T>>): Promise<InferValue<T>>;
+} & ContextOptionsParam<TContexts, InferValue<T>>): Promise<InferValue<T>>;
 declare function runAsync<M extends Mode, T, const TContexts extends readonly SourceContext<unknown>[]>(program: Program<M, T>, options: RunOptions & {
   readonly contexts: TContexts;
-} & RejectEmptyContexts<TContexts> & ExtractRequiredOptions<TContexts, T>): Promise<T>;
+} & RejectEmptyContexts<TContexts> & ContextOptionsParam<TContexts, T>): Promise<T>;
 declare function runAsync<T, const TOptions extends RunOptions | undefined>(program: Program<"sync", T>, options?: TOptions & RejectContextfulOptions<TOptions> & RejectUnknownRunOptionKeys<TOptions>): Promise<T>;
 declare function runAsync<T, const TOptions extends RunOptions | undefined>(program: Program<"async", T>, options?: TOptions & RejectContextfulOptions<TOptions> & RejectUnknownRunOptionKeys<TOptions>): Promise<T>;
 declare function runAsync<T, TOptions extends RunOptions>(program: Program<Mode, T>, options: TOptions & AcceptExactRunOptions<TOptions>): Promise<T>;

package/dist/run.d.ts

@@ -1,4 +1,4 @@
-import { CommandSubConfig, ExtractRequiredOptions, OptionSubConfig } from "@optique/core/facade";
+import { CommandSubConfig, ContextOptionsParam, OptionSubConfig } from "@optique/core/facade";
 import { Message } from "@optique/core/message";
 import { ShellCompletion } from "@optique/core/completion";
 import { SourceContext } from "@optique/core/context";
@@ -225,6 +225,15 @@ interface RunOptions {
    * @since 1.0.0
    */
   readonly contexts?: readonly SourceContext<unknown>[];
+  /**
+   * Options to forward to source contexts.  When contexts declare
+   * required options (via `$requiredOptions`), pass them here to
+   * avoid name collisions with runner-level options such as `help`,
+   * `programName`, or `version`.
+   *
+   * @since 1.0.0
+   */
+  readonly contextOptions?: Record<string, unknown>;
 }
 /**
  * Rejects context tuples that are statically known to be empty so those calls
@@ -323,23 +332,25 @@ type AcceptExactOptionalRunOptions<TOptions> = [TOptions] extends [RunOptions |
  * // myapp --format=<TAB>                                # Use completion
  * ```
  *
- * @since 0.11.0 Added support for {@link Program} objects.
+ * Supports {@link Program} objects.
+ *
+ * @since 1.0.0
  */
 declare function run<T extends Parser<Mode, unknown, unknown>, const TContexts extends NonEmptySourceContexts>(parser: T, options: RunOptions & {
   readonly contexts: TContexts;
-} & ExtractRequiredOptions<TContexts, InferValue<T>>): Promise<InferValue<T>>;
+} & ContextOptionsParam<TContexts, InferValue<T>>): Promise<InferValue<T>>;
 declare function run<T extends Parser<Mode, unknown, unknown>, const TContexts extends readonly SourceContext<unknown>[]>(parser: T, options: RunOptions & {
   readonly contexts: TContexts;
-} & RejectEmptyContexts<TContexts> & ExtractRequiredOptions<TContexts, InferValue<T>>): ModeValue<InferMode<T>, InferValue<T>> | Promise<InferValue<T>>;
+} & RejectEmptyContexts<TContexts> & ContextOptionsParam<TContexts, InferValue<T>>): ModeValue<InferMode<T>, InferValue<T>> | Promise<InferValue<T>>;
 declare function run<M extends Mode, T, const TContexts extends NonEmptySourceContexts>(program: Program<M, T>, options: RunOptions & {
   readonly contexts: TContexts;
-} & ExtractRequiredOptions<TContexts, T>): Promise<T>;
+} & ContextOptionsParam<TContexts, T>): Promise<T>;
 declare function run<T, const TContexts extends readonly SourceContext<unknown>[]>(program: Program<"sync", T>, options: RunOptions & {
   readonly contexts: TContexts;
-} & RejectEmptyContexts<TContexts> & ExtractRequiredOptions<TContexts, T>): T | Promise<T>;
+} & RejectEmptyContexts<TContexts> & ContextOptionsParam<TContexts, T>): T | Promise<T>;
 declare function run<T, const TContexts extends readonly SourceContext<unknown>[]>(program: Program<"async", T>, options: RunOptions & {
   readonly contexts: TContexts;
-} & RejectEmptyContexts<TContexts> & ExtractRequiredOptions<TContexts, T>): Promise<T>;
+} & RejectEmptyContexts<TContexts> & ContextOptionsParam<TContexts, T>): Promise<T>;
 declare function run<T, const TOptions extends RunOptions | undefined>(program: Program<"sync", T>, options?: TOptions & RejectContextfulOptions<TOptions> & RejectUnknownRunOptionKeys<TOptions>): T;
 declare function run<T, TOptions extends RunOptions>(program: Program<"sync", T>, options: TOptions & AcceptExactRunOptions<TOptions>): T | Promise<T>;
 declare function run<T, const TOptions extends RunOptions | undefined>(program: Program<"async", T>, options?: TOptions & RejectContextfulOptions<TOptions> & RejectUnknownRunOptionKeys<TOptions>): Promise<T>;
@@ -358,14 +369,16 @@ declare function run<T extends Parser<Mode, unknown, unknown>>(parser: T, option
  * @param parser The synchronous command-line parser to execute.
  * @param options Configuration options for customizing behavior.
  * @returns The parsed result if successful.
+ * @throws {TypeError} If an async parser (or a {@link Program} wrapping one)
+ * is passed at runtime.  Use {@link run} or {@link runAsync} instead.
  * @since 0.9.0
  */
 declare function runSync<T extends Parser<"sync", unknown, unknown>, TContexts extends readonly SourceContext<unknown>[]>(parser: T, options: RunOptions & {
   readonly contexts: TContexts;
-} & ExtractRequiredOptions<TContexts, InferValue<T>>): InferValue<T>;
+} & ContextOptionsParam<TContexts, InferValue<T>>): InferValue<T>;
 declare function runSync<T, const TContexts extends readonly SourceContext<unknown>[]>(program: Program<"sync", T>, options: RunOptions & {
   readonly contexts: TContexts;
-} & RejectEmptyContexts<TContexts> & ExtractRequiredOptions<TContexts, T>): T;
+} & RejectEmptyContexts<TContexts> & ContextOptionsParam<TContexts, T>): T;
 declare function runSync<T, const TOptions extends RunOptions | undefined>(program: Program<"sync", T>, options?: TOptions & RejectContextfulOptions<TOptions> & RejectUnknownRunOptionKeys<TOptions>): T;
 declare function runSync<T, TOptions extends RunOptions>(program: Program<"sync", T>, options: TOptions & AcceptExactRunOptions<TOptions>): T;
 declare function runSync<T, TOptions extends RunOptions | undefined>(program: Program<"sync", T>, options: TOptions & AcceptExactOptionalRunOptions<TOptions>): T;
@@ -385,10 +398,10 @@ declare function runSync<T extends Parser<"sync", unknown, unknown>>(parser: T,
  */
 declare function runAsync<T extends Parser<Mode, unknown, unknown>, TContexts extends readonly SourceContext<unknown>[]>(parser: T, options: RunOptions & {
   readonly contexts: TContexts;
-} & ExtractRequiredOptions<TContexts, InferValue<T>>): Promise<InferValue<T>>;
+} & ContextOptionsParam<TContexts, InferValue<T>>): Promise<InferValue<T>>;
 declare function runAsync<M extends Mode, T, const TContexts extends readonly SourceContext<unknown>[]>(program: Program<M, T>, options: RunOptions & {
   readonly contexts: TContexts;
-} & RejectEmptyContexts<TContexts> & ExtractRequiredOptions<TContexts, T>): Promise<T>;
+} & RejectEmptyContexts<TContexts> & ContextOptionsParam<TContexts, T>): Promise<T>;
 declare function runAsync<T, const TOptions extends RunOptions | undefined>(program: Program<"sync", T>, options?: TOptions & RejectContextfulOptions<TOptions> & RejectUnknownRunOptionKeys<TOptions>): Promise<T>;
 declare function runAsync<T, const TOptions extends RunOptions | undefined>(program: Program<"async", T>, options?: TOptions & RejectContextfulOptions<TOptions> & RejectUnknownRunOptionKeys<TOptions>): Promise<T>;
 declare function runAsync<T, TOptions extends RunOptions>(program: Program<Mode, T>, options: TOptions & AcceptExactRunOptions<TOptions>): Promise<T>;

package/dist/run.js

@@ -31,17 +31,17 @@ function run(parserOrProgram, options = {}) {
 	return runImpl(parserOrProgram, options);
 }
 function runSync(parserOrProgram, options = {}) {
+	const parserToCheck = "parser" in parserOrProgram && "metadata" in parserOrProgram ? parserOrProgram.parser : parserOrProgram;
+	if (parserToCheck.mode !== "sync") throw new TypeError("Cannot use an async parser with runSync(). Use run() or runAsync() instead.");
 	const contexts = options.contexts;
 	if (contexts && contexts.length > 0) {
 		const resolved = resolveProgramInput(parserOrProgram, options);
 		const { parser, programMetadata } = resolved;
 		options = resolved.options;
 		const { programName, args, coreOptions } = buildCoreOptions(options, programMetadata);
-		const contextOptions = {};
-		for (const key of Object.keys(options)) if (!knownRunOptionsKeys.has(key)) contextOptions[key] = options[key];
 		const runWithOptions = {
 			...coreOptions,
-			...contextOptions,
+			contextOptions: options.contextOptions,
 			args
 		};
 		return runWithSync(parser, programName, contexts, runWithOptions);
@@ -172,35 +172,6 @@ function buildCoreOptions(options, programMetadata) {
 		coreOptions
 	};
 }
-/**
-* Set of known RunOptions field names.  Used by `runImpl()` to separate
-* RunOptions fields from context-required options via rest-spread.
-*/
-const knownRunOptionsKeyList = [
-	"programName",
-	"args",
-	"stdout",
-	"stderr",
-	"onExit",
-	"colors",
-	"maxWidth",
-	"showDefault",
-	"showChoices",
-	"sectionOrder",
-	"help",
-	"version",
-	"completion",
-	"aboveError",
-	"errorExitCode",
-	"brief",
-	"description",
-	"examples",
-	"author",
-	"bugs",
-	"footer",
-	"contexts"
-];
-const knownRunOptionsKeys = new Set(knownRunOptionsKeyList);
 function runImpl(parserOrProgram, options = {}) {
 	const resolved = resolveProgramInput(parserOrProgram, options);
 	const { parser, programMetadata } = resolved;
@@ -208,11 +179,9 @@ function runImpl(parserOrProgram, options = {}) {
 	const contexts = options.contexts;
 	if (contexts && contexts.length > 0) {
 		const { programName: programName$1, args: args$1, coreOptions: coreOptions$1 } = buildCoreOptions(options, programMetadata);
-		const contextOptions = {};
-		for (const key of Object.keys(options)) if (!knownRunOptionsKeys.has(key)) contextOptions[key] = options[key];
 		const runWithOptions = {
 			...coreOptions$1,
-			...contextOptions,
+			contextOptions: options.contextOptions,
 			args: args$1
 		};
 		return runWith(parser, programName$1, contexts, runWithOptions);

package/dist/valueparser.cjs

@@ -18,8 +18,14 @@ const node_fs = require_rolldown_runtime.__toESM(require("node:fs"));
 *   `"file"`, `"directory"`, or `"either"`.
 * @throws {TypeError} If any entry in {@link PathOptionsBase.extensions} does
 *   not start with a dot (e.g., `"json"` instead of `".json"`).
+* @throws {TypeError} If {@link PathOptionsMustExist.mustExist} is not a
+*   boolean.
+* @throws {TypeError} If {@link PathOptionsMustNotExist.mustNotExist} is not a
+*   boolean.
+* @throws {TypeError} If {@link PathOptionsBase.allowCreate} is not a boolean.
 * @throws {TypeError} If both {@link PathOptionsMustExist.mustExist} and
 *   {@link PathOptionsMustNotExist.mustNotExist} are `true`.
+* @throws {TypeError} If `placeholder` is not a string.
 *
 * @example
 * ```typescript
@@ -51,14 +57,20 @@ function path(options = {}) {
 	(0, __optique_core_nonempty.ensureNonEmptyString)(metavar);
 	if (type !== "file" && type !== "directory" && type !== "either") throw new TypeError(`Unsupported path type: ${JSON.stringify(type)}. Expected "file", "directory", or "either".`);
 	if (extensions) {
-		for (const ext of extensions) if (!ext.startsWith(".")) throw new TypeError(`Each extension must start with a dot, got: ${JSON.stringify(ext)}`);
+		for (const ext of extensions) if (typeof ext !== "string" || !ext.startsWith(".")) throw new TypeError(`Each extension must start with a dot, got: ${JSON.stringify(ext)}`);
 	}
+	if (options.allowCreate !== void 0 && typeof options.allowCreate !== "boolean") throw new TypeError(`Expected allowCreate to be a boolean, but got ${typeof options.allowCreate}: ${String(options.allowCreate)}.`);
+	const rawOptions = options;
+	if ("mustExist" in options && rawOptions.mustExist !== void 0 && typeof rawOptions.mustExist !== "boolean") throw new TypeError(`Expected mustExist to be a boolean, but got ${typeof rawOptions.mustExist}: ${String(rawOptions.mustExist)}.`);
+	if ("mustNotExist" in options && rawOptions.mustNotExist !== void 0 && typeof rawOptions.mustNotExist !== "boolean") throw new TypeError(`Expected mustNotExist to be a boolean, but got ${typeof rawOptions.mustNotExist}: ${String(rawOptions.mustNotExist)}.`);
+	if (options.placeholder !== void 0 && typeof options.placeholder !== "string") throw new TypeError(`Expected placeholder to be a string, but got ${typeof options.placeholder}: ${String(options.placeholder)}.`);
 	const mustExist = "mustExist" in options ? options.mustExist : false;
 	const mustNotExist = "mustNotExist" in options ? options.mustNotExist : false;
 	if (mustExist && mustNotExist) throw new TypeError("Options mustExist and mustNotExist are mutually exclusive.");
 	return {
-		$mode: "sync",
+		mode: "sync",
 		metavar,
+		placeholder: options.placeholder ?? ".",
 		parse(input) {
 			if (input.trim() === "") return {
 				success: false,
@@ -128,7 +140,7 @@ function path(options = {}) {
 				pattern: prefix,
 				type: type === "either" ? "any" : type,
 				extensions,
-				includeHidden: (0, node_path.basename)(prefix).startsWith("."),
+				includeHidden: (0, node_path.basename)(prefix).startsWith(".") && (0, node_path.basename)(prefix) !== "..",
 				description: type === "directory" ? __optique_core_message.message`Directory` : type === "file" ? __optique_core_message.message`File` : __optique_core_message.message`File or directory`
 			};
 		}

package/dist/valueparser.d.cts

@@ -82,6 +82,14 @@ interface PathOptionsBase {
    * start with a dot (e.g. `".json"`, `".yaml"`).
    */
   readonly extensions?: readonly string[];
+  /**
+   * A custom placeholder value used during deferred prompt resolution.
+   * Override the default `"."` when downstream `map()` transforms or
+   * path constraints require a specific path shape.
+   *
+   * @since 1.0.0
+   */
+  readonly placeholder?: string;
   /**
    * Custom error messages for path validation failures.
    * @since 0.5.0
@@ -153,8 +161,14 @@ type PathOptions = PathOptionsMustExist | PathOptionsMustNotExist | PathOptionsN
  *   `"file"`, `"directory"`, or `"either"`.
  * @throws {TypeError} If any entry in {@link PathOptionsBase.extensions} does
  *   not start with a dot (e.g., `"json"` instead of `".json"`).
+ * @throws {TypeError} If {@link PathOptionsMustExist.mustExist} is not a
+ *   boolean.
+ * @throws {TypeError} If {@link PathOptionsMustNotExist.mustNotExist} is not a
+ *   boolean.
+ * @throws {TypeError} If {@link PathOptionsBase.allowCreate} is not a boolean.
  * @throws {TypeError} If both {@link PathOptionsMustExist.mustExist} and
  *   {@link PathOptionsMustNotExist.mustNotExist} are `true`.
+ * @throws {TypeError} If `placeholder` is not a string.
  *
  * @example
  * ```typescript

package/dist/valueparser.d.ts

@@ -82,6 +82,14 @@ interface PathOptionsBase {
    * start with a dot (e.g. `".json"`, `".yaml"`).
    */
   readonly extensions?: readonly string[];
+  /**
+   * A custom placeholder value used during deferred prompt resolution.
+   * Override the default `"."` when downstream `map()` transforms or
+   * path constraints require a specific path shape.
+   *
+   * @since 1.0.0
+   */
+  readonly placeholder?: string;
   /**
    * Custom error messages for path validation failures.
    * @since 0.5.0
@@ -153,8 +161,14 @@ type PathOptions = PathOptionsMustExist | PathOptionsMustNotExist | PathOptionsN
  *   `"file"`, `"directory"`, or `"either"`.
  * @throws {TypeError} If any entry in {@link PathOptionsBase.extensions} does
  *   not start with a dot (e.g., `"json"` instead of `".json"`).
+ * @throws {TypeError} If {@link PathOptionsMustExist.mustExist} is not a
+ *   boolean.
+ * @throws {TypeError} If {@link PathOptionsMustNotExist.mustNotExist} is not a
+ *   boolean.
+ * @throws {TypeError} If {@link PathOptionsBase.allowCreate} is not a boolean.
  * @throws {TypeError} If both {@link PathOptionsMustExist.mustExist} and
  *   {@link PathOptionsMustNotExist.mustNotExist} are `true`.
+ * @throws {TypeError} If `placeholder` is not a string.
  *
  * @example
  * ```typescript

package/dist/valueparser.js

@@ -17,8 +17,14 @@ import { existsSync, statSync } from "node:fs";
 *   `"file"`, `"directory"`, or `"either"`.
 * @throws {TypeError} If any entry in {@link PathOptionsBase.extensions} does
 *   not start with a dot (e.g., `"json"` instead of `".json"`).
+* @throws {TypeError} If {@link PathOptionsMustExist.mustExist} is not a
+*   boolean.
+* @throws {TypeError} If {@link PathOptionsMustNotExist.mustNotExist} is not a
+*   boolean.
+* @throws {TypeError} If {@link PathOptionsBase.allowCreate} is not a boolean.
 * @throws {TypeError} If both {@link PathOptionsMustExist.mustExist} and
 *   {@link PathOptionsMustNotExist.mustNotExist} are `true`.
+* @throws {TypeError} If `placeholder` is not a string.
 *
 * @example
 * ```typescript
@@ -50,14 +56,20 @@ function path(options = {}) {
 	ensureNonEmptyString(metavar);
 	if (type !== "file" && type !== "directory" && type !== "either") throw new TypeError(`Unsupported path type: ${JSON.stringify(type)}. Expected "file", "directory", or "either".`);
 	if (extensions) {
-		for (const ext of extensions) if (!ext.startsWith(".")) throw new TypeError(`Each extension must start with a dot, got: ${JSON.stringify(ext)}`);
+		for (const ext of extensions) if (typeof ext !== "string" || !ext.startsWith(".")) throw new TypeError(`Each extension must start with a dot, got: ${JSON.stringify(ext)}`);
 	}
+	if (options.allowCreate !== void 0 && typeof options.allowCreate !== "boolean") throw new TypeError(`Expected allowCreate to be a boolean, but got ${typeof options.allowCreate}: ${String(options.allowCreate)}.`);
+	const rawOptions = options;
+	if ("mustExist" in options && rawOptions.mustExist !== void 0 && typeof rawOptions.mustExist !== "boolean") throw new TypeError(`Expected mustExist to be a boolean, but got ${typeof rawOptions.mustExist}: ${String(rawOptions.mustExist)}.`);
+	if ("mustNotExist" in options && rawOptions.mustNotExist !== void 0 && typeof rawOptions.mustNotExist !== "boolean") throw new TypeError(`Expected mustNotExist to be a boolean, but got ${typeof rawOptions.mustNotExist}: ${String(rawOptions.mustNotExist)}.`);
+	if (options.placeholder !== void 0 && typeof options.placeholder !== "string") throw new TypeError(`Expected placeholder to be a string, but got ${typeof options.placeholder}: ${String(options.placeholder)}.`);
 	const mustExist = "mustExist" in options ? options.mustExist : false;
 	const mustNotExist = "mustNotExist" in options ? options.mustNotExist : false;
 	if (mustExist && mustNotExist) throw new TypeError("Options mustExist and mustNotExist are mutually exclusive.");
 	return {
-		$mode: "sync",
+		mode: "sync",
 		metavar,
+		placeholder: options.placeholder ?? ".",
 		parse(input) {
 			if (input.trim() === "") return {
 				success: false,
@@ -127,7 +139,7 @@ function path(options = {}) {
 				pattern: prefix,
 				type: type === "either" ? "any" : type,
 				extensions,
-				includeHidden: basename(prefix).startsWith("."),
+				includeHidden: basename(prefix).startsWith(".") && basename(prefix) !== "..",
 				description: type === "directory" ? message`Directory` : type === "file" ? message`File` : message`File or directory`
 			};
 		}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@optique/run",
-  "version": "1.0.0-dev.908+f60f037d",
+  "version": "1.0.0",
   "description": "Type-safe combinatorial command-line interface parser",
   "keywords": [
     "CLI",
@@ -70,7 +70,7 @@
   },
   "sideEffects": false,
   "dependencies": {
-    "@optique/core": "1.0.0-dev.908+f60f037d"
+    "@optique/core": "1.0.0"
   },
   "devDependencies": {
     "@types/node": "^20.19.9",