@optique/run 1.0.0-dev.921 → 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,6 +32,8 @@ 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);

package/dist/run.d.cts

@@ -332,7 +332,9 @@ 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;
@@ -367,6 +369,8 @@ 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 & {

package/dist/run.d.ts

@@ -332,7 +332,9 @@ 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;
@@ -367,6 +369,8 @@ 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 & {

package/dist/run.js

@@ -31,6 +31,8 @@ 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);

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.921+754748bd",
+  "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.921+754748bd"
+    "@optique/core": "1.0.0"
   },
   "devDependencies": {
     "@types/node": "^20.19.9",