@guanghechen/commander 4.7.9 → 4.8.1

package/CHANGELOG.md

@@ -1,5 +1,18 @@
 # Change Log
 
+## 4.8.1
+
+### Patch Changes
+
+- Fix negative-number preset option serialization, reject empty coerce input, and avoid long-name
+  conflicts with no- negation options.
+
+## 4.8.0
+
+### Minor Changes
+
+- Expose preset directives in command help output under a dedicated `Preset Directives:` section.
+
 ## 4.7.9
 
 ### Patch Changes

package/lib/cjs/browser.cjs

@@ -489,7 +489,7 @@ function validateOptionConfig(params) {
     if (opt.type === 'number' && opt.args === 'optional') {
         throw new CommanderError('ConfigurationError', `number option "--${opt.long}" does not support args: 'optional'`, commandPath);
     }
-    if (opt.long.startsWith('no')) {
+    if (/^no[A-Z]/.test(opt.long)) {
         throw new CommanderError('ConfigurationError', `option long name cannot start with "no": "${opt.long}"`, commandPath);
     }
     if (!/^[a-z][a-zA-Z0-9]*$/.test(opt.long)) {
@@ -1333,6 +1333,7 @@ class CommandHelpRenderer {
             usage,
             arguments: argumentsLines,
             options,
+            presetDirectives: params.presetDirectives ?? [],
             commands,
             examples,
         };
@@ -1403,6 +1404,14 @@ class CommandHelpRenderer {
             }
             lines.push('');
         }
+        const presetDirectives = helpData.presetDirectives ?? [];
+        if (presetDirectives.length > 0) {
+            lines.push('Preset Directives:');
+            for (const { sig, desc } of presetDirectives) {
+                lines.push(this.#renderAlignedHelpLine(sig, desc, labelWidth));
+            }
+            lines.push('');
+        }
         if (helpData.commands.length > 0) {
             lines.push('Commands:');
             for (const { name, desc } of helpData.commands) {
@@ -1442,6 +1451,14 @@ class CommandHelpRenderer {
             }
             lines.push('');
         }
+        const presetDirectives = helpData.presetDirectives ?? [];
+        if (presetDirectives.length > 0) {
+            lines.push(styleText('Preset Directives:', TERMINAL_STYLE.bold, TERMINAL_STYLE.underline));
+            for (const { sig, desc } of presetDirectives) {
+                lines.push(this.#renderAlignedHelpLine(sig, desc, labelWidth, value => styleText(value, TERMINAL_STYLE.cyan)));
+            }
+            lines.push('');
+        }
         if (helpData.commands.length > 0) {
             lines.push(styleText('Commands:', TERMINAL_STYLE.bold, TERMINAL_STYLE.underline));
             for (const { name, desc } of helpData.commands) {
@@ -1464,6 +1481,7 @@ class CommandHelpRenderer {
         const labels = [
             ...helpData.arguments.map(line => line.sig),
             ...helpData.options.map(line => line.sig),
+            ...(helpData.presetDirectives ?? []).map(line => line.sig),
             ...helpData.commands.map(line => line.name),
         ];
         if (labels.length === 0) {
@@ -2130,13 +2148,23 @@ class CommandPresetProfileParser {
                 continue;
             }
             if (typeof rawValue === 'number') {
-                argv.push(positiveFlag, String(rawValue));
+                const value = String(rawValue);
+                if (value.startsWith('-'))
+                    argv.push(`${positiveFlag}=${value}`);
+                else
+                    argv.push(positiveFlag, value);
                 continue;
             }
             if (rawValue.length === 0) {
                 continue;
             }
-            argv.push(positiveFlag, ...rawValue.map(value => String(value)));
+            if (rawValue.some(value => typeof value === 'number' && String(value).startsWith('-'))) {
+                for (const value of rawValue)
+                    argv.push(`${positiveFlag}=${String(value)}`);
+            }
+            else {
+                argv.push(positiveFlag, ...rawValue.map(value => String(value)));
+            }
         }
         return argv;
     }
@@ -3386,6 +3414,16 @@ class Command {
             commandPath: this.#getCommandPath(),
             arguments: this.#arguments,
             options: this.#resolveOptionPolicy().mergedOptions,
+            presetDirectives: [
+                {
+                    sig: `${PRESET_FILE_FLAG} <value>`,
+                    desc: 'Load preset manifest file',
+                },
+                {
+                    sig: `${PRESET_PROFILE_FLAG} <value>`,
+                    desc: 'Select preset profile: <profile> or <profile>:<variant>; requires --preset-file or command preset.file',
+                },
+            ],
             supportsBuiltinVersion: this.#supportsBuiltinVersion(),
             subcommands,
             examples: this.#examples,
@@ -3657,10 +3695,10 @@ function isDomain(rawValue) {
 
 class Coerce {
     constructor() { }
-    static create(name, expectedType, validator, errorMessage) {
+    static createNumberCoerce(name, expectedType, validator, errorMessage) {
         return (rawValue) => {
             const value = Number(rawValue);
-            if (!validator(value)) {
+            if (rawValue.trim() === '' || !validator(value)) {
                 throw new Error(errorMessage ?? `${name} is expected as ${expectedType}, but got ${rawValue}`);
             }
             return value;
@@ -3691,7 +3729,7 @@ class Coerce {
         };
     }
     static integer(name, errorMessage) {
-        return this.create(name, 'an integer', value => Number.isInteger(value), errorMessage);
+        return this.createNumberCoerce(name, 'an integer', value => Number.isInteger(value), errorMessage);
     }
     static ip(name, errorMessage) {
         return (rawValue) => {
@@ -3702,16 +3740,16 @@ class Coerce {
         };
     }
     static number(name, errorMessage) {
-        return this.create(name, 'a finite number', value => Number.isFinite(value), errorMessage);
+        return this.createNumberCoerce(name, 'a finite number', value => Number.isFinite(value), errorMessage);
     }
     static port(name, errorMessage) {
-        return this.create(name, 'a valid port number (0-65535)', value => Number.isInteger(value) && value >= 0 && value <= 65535, errorMessage);
+        return this.createNumberCoerce(name, 'a valid port number (0-65535)', value => Number.isInteger(value) && value >= 0 && value <= 65535, errorMessage);
     }
     static positiveInteger(name, errorMessage) {
-        return this.create(name, 'a positive integer', value => Number.isInteger(value) && value > 0, errorMessage);
+        return this.createNumberCoerce(name, 'a positive integer', value => Number.isInteger(value) && value > 0, errorMessage);
     }
     static positiveNumber(name, errorMessage) {
-        return this.create(name, 'a positive number', value => Number.isFinite(value) && value > 0, errorMessage);
+        return this.createNumberCoerce(name, 'a positive number', value => Number.isFinite(value) && value > 0, errorMessage);
     }
 }
 

package/lib/cjs/node.cjs

@@ -502,7 +502,7 @@ function validateOptionConfig(params) {
     if (opt.type === 'number' && opt.args === 'optional') {
         throw new CommanderError('ConfigurationError', `number option "--${opt.long}" does not support args: 'optional'`, commandPath);
     }
-    if (opt.long.startsWith('no')) {
+    if (/^no[A-Z]/.test(opt.long)) {
         throw new CommanderError('ConfigurationError', `option long name cannot start with "no": "${opt.long}"`, commandPath);
     }
     if (!/^[a-z][a-zA-Z0-9]*$/.test(opt.long)) {
@@ -1346,6 +1346,7 @@ class CommandHelpRenderer {
             usage,
             arguments: argumentsLines,
             options,
+            presetDirectives: params.presetDirectives ?? [],
             commands,
             examples,
         };
@@ -1416,6 +1417,14 @@ class CommandHelpRenderer {
             }
             lines.push('');
         }
+        const presetDirectives = helpData.presetDirectives ?? [];
+        if (presetDirectives.length > 0) {
+            lines.push('Preset Directives:');
+            for (const { sig, desc } of presetDirectives) {
+                lines.push(this.#renderAlignedHelpLine(sig, desc, labelWidth));
+            }
+            lines.push('');
+        }
         if (helpData.commands.length > 0) {
             lines.push('Commands:');
             for (const { name, desc } of helpData.commands) {
@@ -1455,6 +1464,14 @@ class CommandHelpRenderer {
             }
             lines.push('');
         }
+        const presetDirectives = helpData.presetDirectives ?? [];
+        if (presetDirectives.length > 0) {
+            lines.push(styleText('Preset Directives:', TERMINAL_STYLE.bold, TERMINAL_STYLE.underline));
+            for (const { sig, desc } of presetDirectives) {
+                lines.push(this.#renderAlignedHelpLine(sig, desc, labelWidth, value => styleText(value, TERMINAL_STYLE.cyan)));
+            }
+            lines.push('');
+        }
         if (helpData.commands.length > 0) {
             lines.push(styleText('Commands:', TERMINAL_STYLE.bold, TERMINAL_STYLE.underline));
             for (const { name, desc } of helpData.commands) {
@@ -1477,6 +1494,7 @@ class CommandHelpRenderer {
         const labels = [
             ...helpData.arguments.map(line => line.sig),
             ...helpData.options.map(line => line.sig),
+            ...(helpData.presetDirectives ?? []).map(line => line.sig),
             ...helpData.commands.map(line => line.name),
         ];
         if (labels.length === 0) {
@@ -2143,13 +2161,23 @@ class CommandPresetProfileParser {
                 continue;
             }
             if (typeof rawValue === 'number') {
-                argv.push(positiveFlag, String(rawValue));
+                const value = String(rawValue);
+                if (value.startsWith('-'))
+                    argv.push(`${positiveFlag}=${value}`);
+                else
+                    argv.push(positiveFlag, value);
                 continue;
             }
             if (rawValue.length === 0) {
                 continue;
             }
-            argv.push(positiveFlag, ...rawValue.map(value => String(value)));
+            if (rawValue.some(value => typeof value === 'number' && String(value).startsWith('-'))) {
+                for (const value of rawValue)
+                    argv.push(`${positiveFlag}=${String(value)}`);
+            }
+            else {
+                argv.push(positiveFlag, ...rawValue.map(value => String(value)));
+            }
         }
         return argv;
     }
@@ -3399,6 +3427,16 @@ class Command {
             commandPath: this.#getCommandPath(),
             arguments: this.#arguments,
             options: this.#resolveOptionPolicy().mergedOptions,
+            presetDirectives: [
+                {
+                    sig: `${PRESET_FILE_FLAG} <value>`,
+                    desc: 'Load preset manifest file',
+                },
+                {
+                    sig: `${PRESET_PROFILE_FLAG} <value>`,
+                    desc: 'Select preset profile: <profile> or <profile>:<variant>; requires --preset-file or command preset.file',
+                },
+            ],
             supportsBuiltinVersion: this.#supportsBuiltinVersion(),
             subcommands,
             examples: this.#examples,
@@ -3670,10 +3708,10 @@ function isDomain(rawValue) {
 
 class Coerce {
     constructor() { }
-    static create(name, expectedType, validator, errorMessage) {
+    static createNumberCoerce(name, expectedType, validator, errorMessage) {
         return (rawValue) => {
             const value = Number(rawValue);
-            if (!validator(value)) {
+            if (rawValue.trim() === '' || !validator(value)) {
                 throw new Error(errorMessage ?? `${name} is expected as ${expectedType}, but got ${rawValue}`);
             }
             return value;
@@ -3704,7 +3742,7 @@ class Coerce {
         };
     }
     static integer(name, errorMessage) {
-        return this.create(name, 'an integer', value => Number.isInteger(value), errorMessage);
+        return this.createNumberCoerce(name, 'an integer', value => Number.isInteger(value), errorMessage);
     }
     static ip(name, errorMessage) {
         return (rawValue) => {
@@ -3715,16 +3753,16 @@ class Coerce {
         };
     }
     static number(name, errorMessage) {
-        return this.create(name, 'a finite number', value => Number.isFinite(value), errorMessage);
+        return this.createNumberCoerce(name, 'a finite number', value => Number.isFinite(value), errorMessage);
     }
     static port(name, errorMessage) {
-        return this.create(name, 'a valid port number (0-65535)', value => Number.isInteger(value) && value >= 0 && value <= 65535, errorMessage);
+        return this.createNumberCoerce(name, 'a valid port number (0-65535)', value => Number.isInteger(value) && value >= 0 && value <= 65535, errorMessage);
     }
     static positiveInteger(name, errorMessage) {
-        return this.create(name, 'a positive integer', value => Number.isInteger(value) && value > 0, errorMessage);
+        return this.createNumberCoerce(name, 'a positive integer', value => Number.isInteger(value) && value > 0, errorMessage);
     }
     static positiveNumber(name, errorMessage) {
-        return this.create(name, 'a positive number', value => Number.isFinite(value) && value > 0, errorMessage);
+        return this.createNumberCoerce(name, 'a positive number', value => Number.isFinite(value) && value > 0, errorMessage);
     }
 }
 

package/lib/esm/browser.mjs

@@ -487,7 +487,7 @@ function validateOptionConfig(params) {
     if (opt.type === 'number' && opt.args === 'optional') {
         throw new CommanderError('ConfigurationError', `number option "--${opt.long}" does not support args: 'optional'`, commandPath);
     }
-    if (opt.long.startsWith('no')) {
+    if (/^no[A-Z]/.test(opt.long)) {
         throw new CommanderError('ConfigurationError', `option long name cannot start with "no": "${opt.long}"`, commandPath);
     }
     if (!/^[a-z][a-zA-Z0-9]*$/.test(opt.long)) {
@@ -1331,6 +1331,7 @@ class CommandHelpRenderer {
             usage,
             arguments: argumentsLines,
             options,
+            presetDirectives: params.presetDirectives ?? [],
             commands,
             examples,
         };
@@ -1401,6 +1402,14 @@ class CommandHelpRenderer {
             }
             lines.push('');
         }
+        const presetDirectives = helpData.presetDirectives ?? [];
+        if (presetDirectives.length > 0) {
+            lines.push('Preset Directives:');
+            for (const { sig, desc } of presetDirectives) {
+                lines.push(this.#renderAlignedHelpLine(sig, desc, labelWidth));
+            }
+            lines.push('');
+        }
         if (helpData.commands.length > 0) {
             lines.push('Commands:');
             for (const { name, desc } of helpData.commands) {
@@ -1440,6 +1449,14 @@ class CommandHelpRenderer {
             }
             lines.push('');
         }
+        const presetDirectives = helpData.presetDirectives ?? [];
+        if (presetDirectives.length > 0) {
+            lines.push(styleText('Preset Directives:', TERMINAL_STYLE.bold, TERMINAL_STYLE.underline));
+            for (const { sig, desc } of presetDirectives) {
+                lines.push(this.#renderAlignedHelpLine(sig, desc, labelWidth, value => styleText(value, TERMINAL_STYLE.cyan)));
+            }
+            lines.push('');
+        }
         if (helpData.commands.length > 0) {
             lines.push(styleText('Commands:', TERMINAL_STYLE.bold, TERMINAL_STYLE.underline));
             for (const { name, desc } of helpData.commands) {
@@ -1462,6 +1479,7 @@ class CommandHelpRenderer {
         const labels = [
             ...helpData.arguments.map(line => line.sig),
             ...helpData.options.map(line => line.sig),
+            ...(helpData.presetDirectives ?? []).map(line => line.sig),
             ...helpData.commands.map(line => line.name),
         ];
         if (labels.length === 0) {
@@ -2128,13 +2146,23 @@ class CommandPresetProfileParser {
                 continue;
             }
             if (typeof rawValue === 'number') {
-                argv.push(positiveFlag, String(rawValue));
+                const value = String(rawValue);
+                if (value.startsWith('-'))
+                    argv.push(`${positiveFlag}=${value}`);
+                else
+                    argv.push(positiveFlag, value);
                 continue;
             }
             if (rawValue.length === 0) {
                 continue;
             }
-            argv.push(positiveFlag, ...rawValue.map(value => String(value)));
+            if (rawValue.some(value => typeof value === 'number' && String(value).startsWith('-'))) {
+                for (const value of rawValue)
+                    argv.push(`${positiveFlag}=${String(value)}`);
+            }
+            else {
+                argv.push(positiveFlag, ...rawValue.map(value => String(value)));
+            }
         }
         return argv;
     }
@@ -3384,6 +3412,16 @@ class Command {
             commandPath: this.#getCommandPath(),
             arguments: this.#arguments,
             options: this.#resolveOptionPolicy().mergedOptions,
+            presetDirectives: [
+                {
+                    sig: `${PRESET_FILE_FLAG} <value>`,
+                    desc: 'Load preset manifest file',
+                },
+                {
+                    sig: `${PRESET_PROFILE_FLAG} <value>`,
+                    desc: 'Select preset profile: <profile> or <profile>:<variant>; requires --preset-file or command preset.file',
+                },
+            ],
             supportsBuiltinVersion: this.#supportsBuiltinVersion(),
             subcommands,
             examples: this.#examples,
@@ -3655,10 +3693,10 @@ function isDomain(rawValue) {
 
 class Coerce {
     constructor() { }
-    static create(name, expectedType, validator, errorMessage) {
+    static createNumberCoerce(name, expectedType, validator, errorMessage) {
         return (rawValue) => {
             const value = Number(rawValue);
-            if (!validator(value)) {
+            if (rawValue.trim() === '' || !validator(value)) {
                 throw new Error(errorMessage ?? `${name} is expected as ${expectedType}, but got ${rawValue}`);
             }
             return value;
@@ -3689,7 +3727,7 @@ class Coerce {
         };
     }
     static integer(name, errorMessage) {
-        return this.create(name, 'an integer', value => Number.isInteger(value), errorMessage);
+        return this.createNumberCoerce(name, 'an integer', value => Number.isInteger(value), errorMessage);
     }
     static ip(name, errorMessage) {
         return (rawValue) => {
@@ -3700,16 +3738,16 @@ class Coerce {
         };
     }
     static number(name, errorMessage) {
-        return this.create(name, 'a finite number', value => Number.isFinite(value), errorMessage);
+        return this.createNumberCoerce(name, 'a finite number', value => Number.isFinite(value), errorMessage);
     }
     static port(name, errorMessage) {
-        return this.create(name, 'a valid port number (0-65535)', value => Number.isInteger(value) && value >= 0 && value <= 65535, errorMessage);
+        return this.createNumberCoerce(name, 'a valid port number (0-65535)', value => Number.isInteger(value) && value >= 0 && value <= 65535, errorMessage);
     }
     static positiveInteger(name, errorMessage) {
-        return this.create(name, 'a positive integer', value => Number.isInteger(value) && value > 0, errorMessage);
+        return this.createNumberCoerce(name, 'a positive integer', value => Number.isInteger(value) && value > 0, errorMessage);
     }
     static positiveNumber(name, errorMessage) {
-        return this.create(name, 'a positive number', value => Number.isFinite(value) && value > 0, errorMessage);
+        return this.createNumberCoerce(name, 'a positive number', value => Number.isFinite(value) && value > 0, errorMessage);
     }
 }
 

package/lib/esm/node.mjs

@@ -500,7 +500,7 @@ function validateOptionConfig(params) {
     if (opt.type === 'number' && opt.args === 'optional') {
         throw new CommanderError('ConfigurationError', `number option "--${opt.long}" does not support args: 'optional'`, commandPath);
     }
-    if (opt.long.startsWith('no')) {
+    if (/^no[A-Z]/.test(opt.long)) {
         throw new CommanderError('ConfigurationError', `option long name cannot start with "no": "${opt.long}"`, commandPath);
     }
     if (!/^[a-z][a-zA-Z0-9]*$/.test(opt.long)) {
@@ -1344,6 +1344,7 @@ class CommandHelpRenderer {
             usage,
             arguments: argumentsLines,
             options,
+            presetDirectives: params.presetDirectives ?? [],
             commands,
             examples,
         };
@@ -1414,6 +1415,14 @@ class CommandHelpRenderer {
             }
             lines.push('');
         }
+        const presetDirectives = helpData.presetDirectives ?? [];
+        if (presetDirectives.length > 0) {
+            lines.push('Preset Directives:');
+            for (const { sig, desc } of presetDirectives) {
+                lines.push(this.#renderAlignedHelpLine(sig, desc, labelWidth));
+            }
+            lines.push('');
+        }
         if (helpData.commands.length > 0) {
             lines.push('Commands:');
             for (const { name, desc } of helpData.commands) {
@@ -1453,6 +1462,14 @@ class CommandHelpRenderer {
             }
             lines.push('');
         }
+        const presetDirectives = helpData.presetDirectives ?? [];
+        if (presetDirectives.length > 0) {
+            lines.push(styleText('Preset Directives:', TERMINAL_STYLE.bold, TERMINAL_STYLE.underline));
+            for (const { sig, desc } of presetDirectives) {
+                lines.push(this.#renderAlignedHelpLine(sig, desc, labelWidth, value => styleText(value, TERMINAL_STYLE.cyan)));
+            }
+            lines.push('');
+        }
         if (helpData.commands.length > 0) {
             lines.push(styleText('Commands:', TERMINAL_STYLE.bold, TERMINAL_STYLE.underline));
             for (const { name, desc } of helpData.commands) {
@@ -1475,6 +1492,7 @@ class CommandHelpRenderer {
         const labels = [
             ...helpData.arguments.map(line => line.sig),
             ...helpData.options.map(line => line.sig),
+            ...(helpData.presetDirectives ?? []).map(line => line.sig),
             ...helpData.commands.map(line => line.name),
         ];
         if (labels.length === 0) {
@@ -2141,13 +2159,23 @@ class CommandPresetProfileParser {
                 continue;
             }
             if (typeof rawValue === 'number') {
-                argv.push(positiveFlag, String(rawValue));
+                const value = String(rawValue);
+                if (value.startsWith('-'))
+                    argv.push(`${positiveFlag}=${value}`);
+                else
+                    argv.push(positiveFlag, value);
                 continue;
             }
             if (rawValue.length === 0) {
                 continue;
             }
-            argv.push(positiveFlag, ...rawValue.map(value => String(value)));
+            if (rawValue.some(value => typeof value === 'number' && String(value).startsWith('-'))) {
+                for (const value of rawValue)
+                    argv.push(`${positiveFlag}=${String(value)}`);
+            }
+            else {
+                argv.push(positiveFlag, ...rawValue.map(value => String(value)));
+            }
         }
         return argv;
     }
@@ -3397,6 +3425,16 @@ class Command {
             commandPath: this.#getCommandPath(),
             arguments: this.#arguments,
             options: this.#resolveOptionPolicy().mergedOptions,
+            presetDirectives: [
+                {
+                    sig: `${PRESET_FILE_FLAG} <value>`,
+                    desc: 'Load preset manifest file',
+                },
+                {
+                    sig: `${PRESET_PROFILE_FLAG} <value>`,
+                    desc: 'Select preset profile: <profile> or <profile>:<variant>; requires --preset-file or command preset.file',
+                },
+            ],
             supportsBuiltinVersion: this.#supportsBuiltinVersion(),
             subcommands,
             examples: this.#examples,
@@ -3668,10 +3706,10 @@ function isDomain(rawValue) {
 
 class Coerce {
     constructor() { }
-    static create(name, expectedType, validator, errorMessage) {
+    static createNumberCoerce(name, expectedType, validator, errorMessage) {
         return (rawValue) => {
             const value = Number(rawValue);
-            if (!validator(value)) {
+            if (rawValue.trim() === '' || !validator(value)) {
                 throw new Error(errorMessage ?? `${name} is expected as ${expectedType}, but got ${rawValue}`);
             }
             return value;
@@ -3702,7 +3740,7 @@ class Coerce {
         };
     }
     static integer(name, errorMessage) {
-        return this.create(name, 'an integer', value => Number.isInteger(value), errorMessage);
+        return this.createNumberCoerce(name, 'an integer', value => Number.isInteger(value), errorMessage);
     }
     static ip(name, errorMessage) {
         return (rawValue) => {
@@ -3713,16 +3751,16 @@ class Coerce {
         };
     }
     static number(name, errorMessage) {
-        return this.create(name, 'a finite number', value => Number.isFinite(value), errorMessage);
+        return this.createNumberCoerce(name, 'a finite number', value => Number.isFinite(value), errorMessage);
     }
     static port(name, errorMessage) {
-        return this.create(name, 'a valid port number (0-65535)', value => Number.isInteger(value) && value >= 0 && value <= 65535, errorMessage);
+        return this.createNumberCoerce(name, 'a valid port number (0-65535)', value => Number.isInteger(value) && value >= 0 && value <= 65535, errorMessage);
     }
     static positiveInteger(name, errorMessage) {
-        return this.create(name, 'a positive integer', value => Number.isInteger(value) && value > 0, errorMessage);
+        return this.createNumberCoerce(name, 'a positive integer', value => Number.isInteger(value) && value > 0, errorMessage);
     }
     static positiveNumber(name, errorMessage) {
-        return this.create(name, 'a positive number', value => Number.isFinite(value) && value > 0, errorMessage);
+        return this.createNumberCoerce(name, 'a positive number', value => Number.isFinite(value) && value > 0, errorMessage);
     }
 }
 

package/lib/types/browser.d.ts

@@ -391,6 +391,11 @@ interface IHelpOptionLine {
     sig: string;
     desc: string;
 }
+/** Help preset directive line (internal) */
+interface IHelpPresetDirectiveLine {
+    sig: string;
+    desc: string;
+}
 /** Help argument line (internal) */
 interface IHelpArgumentLine {
     sig: string;
@@ -413,6 +418,7 @@ interface IHelpData {
     usage: string;
     arguments: IHelpArgumentLine[];
     options: IHelpOptionLine[];
+    presetDirectives?: IHelpPresetDirectiveLine[];
     commands: IHelpCommandLine[];
     examples: IHelpExampleLine[];
 }
@@ -586,7 +592,7 @@ declare class Command implements ICommand {
  */
 declare class Coerce {
     private constructor();
-    private static create;
+    private static createNumberCoerce;
     static choice<TValue extends string>(name: string, values: ReadonlyArray<TValue>, errorMessage?: string): (rawValue: string) => TValue;
     static domain(name: string, errorMessage?: string): (rawValue: string) => string;
     static host(name: string, errorMessage?: string): (rawValue: string) => string;
@@ -674,4 +680,4 @@ declare function getDefaultCommandRuntime(): ICommandRuntime;
 declare function setDefaultCommandRuntime(runtime: ICommandRuntime): void;
 
 export { Coerce, Command, CommanderError, createBrowserCommandRuntime, getDefaultCommandRuntime, isDomain, isIp, isIpv4, isIpv6, logColorfulOption, logDateOption, setDefaultCommandRuntime, silentOption };
-export type { ICommand, ICommandAction, ICommandActionParams, ICommandArgumentConfig, ICommandArgumentKind, ICommandArgumentType, ICommandArgvSegment, ICommandBuiltinConfig, ICommandBuiltinOptionConfig, ICommandBuiltinOptionResolved, ICommandBuiltinParsedOptions, ICommandBuiltinResolved, ICommandConfig, ICommandContext, ICommandControlScanResult, ICommandControls, ICommandErrorIssue, ICommandErrorIssueCode, ICommandErrorMeta, ICommandExample, ICommandHintIssue, ICommandHintIssueCode, ICommandInputSources, ICommandIssue, ICommandIssueBase, ICommandIssueCode, ICommandIssueKind, ICommandIssueReason, ICommandIssueScope, ICommandIssueSourceAttribution, ICommandOptionArgs, ICommandOptionConfig, ICommandOptionType, ICommandParseResult, ICommandParsedArgs, ICommandParsedOpts, ICommandPresetConfig, ICommandPresetIssueMeta, ICommandPresetProfileDefaults, ICommandPresetProfileItem, ICommandPresetProfileManifest, ICommandPresetProfileOptionValue, ICommandPresetProfileVariantItem, ICommandPresetResult, ICommandPresetSourceMeta, ICommandPresetSourceState, ICommandResolveResult, ICommandRouteResult, ICommandRunParams, ICommandRuntime, ICommandRuntimeStats, ICommandShiftResult, ICommandStage, ICommandToken, ICommandTokenSource, ICommandTokenType, ICommandTokenizeResult, ICommanderErrorKind, ICompletionArgumentMeta, ICompletionCommandConfig, ICompletionMeta, ICompletionOptionMeta, ICompletionPaths, ICompletionShellType, IHelpArgumentLine, IHelpCommandLine, IHelpData, IHelpExampleLine, IHelpOptionLine, ISubcommandEntry };
+export type { ICommand, ICommandAction, ICommandActionParams, ICommandArgumentConfig, ICommandArgumentKind, ICommandArgumentType, ICommandArgvSegment, ICommandBuiltinConfig, ICommandBuiltinOptionConfig, ICommandBuiltinOptionResolved, ICommandBuiltinParsedOptions, ICommandBuiltinResolved, ICommandConfig, ICommandContext, ICommandControlScanResult, ICommandControls, ICommandErrorIssue, ICommandErrorIssueCode, ICommandErrorMeta, ICommandExample, ICommandHintIssue, ICommandHintIssueCode, ICommandInputSources, ICommandIssue, ICommandIssueBase, ICommandIssueCode, ICommandIssueKind, ICommandIssueReason, ICommandIssueScope, ICommandIssueSourceAttribution, ICommandOptionArgs, ICommandOptionConfig, ICommandOptionType, ICommandParseResult, ICommandParsedArgs, ICommandParsedOpts, ICommandPresetConfig, ICommandPresetIssueMeta, ICommandPresetProfileDefaults, ICommandPresetProfileItem, ICommandPresetProfileManifest, ICommandPresetProfileOptionValue, ICommandPresetProfileVariantItem, ICommandPresetResult, ICommandPresetSourceMeta, ICommandPresetSourceState, ICommandResolveResult, ICommandRouteResult, ICommandRunParams, ICommandRuntime, ICommandRuntimeStats, ICommandShiftResult, ICommandStage, ICommandToken, ICommandTokenSource, ICommandTokenType, ICommandTokenizeResult, ICommanderErrorKind, ICompletionArgumentMeta, ICompletionCommandConfig, ICompletionMeta, ICompletionOptionMeta, ICompletionPaths, ICompletionShellType, IHelpArgumentLine, IHelpCommandLine, IHelpData, IHelpExampleLine, IHelpOptionLine, IHelpPresetDirectiveLine, ISubcommandEntry };

package/lib/types/node.d.ts

@@ -391,6 +391,11 @@ interface IHelpOptionLine {
     sig: string;
     desc: string;
 }
+/** Help preset directive line (internal) */
+interface IHelpPresetDirectiveLine {
+    sig: string;
+    desc: string;
+}
 /** Help argument line (internal) */
 interface IHelpArgumentLine {
     sig: string;
@@ -413,6 +418,7 @@ interface IHelpData {
     usage: string;
     arguments: IHelpArgumentLine[];
     options: IHelpOptionLine[];
+    presetDirectives?: IHelpPresetDirectiveLine[];
     commands: IHelpCommandLine[];
     examples: IHelpExampleLine[];
 }
@@ -594,7 +600,7 @@ declare class Command implements ICommand {
  */
 declare class Coerce {
     private constructor();
-    private static create;
+    private static createNumberCoerce;
     static choice<TValue extends string>(name: string, values: ReadonlyArray<TValue>, errorMessage?: string): (rawValue: string) => TValue;
     static domain(name: string, errorMessage?: string): (rawValue: string) => string;
     static host(name: string, errorMessage?: string): (rawValue: string) => string;
@@ -727,4 +733,4 @@ declare class PwshCompletion {
 }
 
 export { BashCompletion, Coerce, Command, CommanderError, CompletionCommand, FishCompletion, PwshCompletion, createBrowserCommandRuntime, createNodeCommandRuntime, getDefaultCommandRuntime, isDomain, isIp, isIpv4, isIpv6, logColorfulOption, logDateOption, setDefaultCommandRuntime, silentOption };
-export type { ICommand, ICommandAction, ICommandActionParams, ICommandArgumentConfig, ICommandArgumentKind, ICommandArgumentType, ICommandArgvSegment, ICommandBuiltinConfig, ICommandBuiltinOptionConfig, ICommandBuiltinOptionResolved, ICommandBuiltinParsedOptions, ICommandBuiltinResolved, ICommandConfig, ICommandContext, ICommandControlScanResult, ICommandControls, ICommandErrorIssue, ICommandErrorIssueCode, ICommandErrorMeta, ICommandExample, ICommandHintIssue, ICommandHintIssueCode, ICommandInputSources, ICommandIssue, ICommandIssueBase, ICommandIssueCode, ICommandIssueKind, ICommandIssueReason, ICommandIssueScope, ICommandIssueSourceAttribution, ICommandOptionArgs, ICommandOptionConfig, ICommandOptionType, ICommandParseResult, ICommandParsedArgs, ICommandParsedOpts, ICommandPresetConfig, ICommandPresetIssueMeta, ICommandPresetProfileDefaults, ICommandPresetProfileItem, ICommandPresetProfileManifest, ICommandPresetProfileOptionValue, ICommandPresetProfileVariantItem, ICommandPresetResult, ICommandPresetSourceMeta, ICommandPresetSourceState, ICommandResolveResult, ICommandRouteResult, ICommandRunParams, ICommandRuntime, ICommandRuntimeStats, ICommandShiftResult, ICommandStage, ICommandToken, ICommandTokenSource, ICommandTokenType, ICommandTokenizeResult, ICommanderErrorKind, ICompletionArgumentMeta, ICompletionCommandConfig, ICompletionMeta, ICompletionOptionMeta, ICompletionPaths, ICompletionShellType, IHelpArgumentLine, IHelpCommandLine, IHelpData, IHelpExampleLine, IHelpOptionLine, ISubcommandEntry };
+export type { ICommand, ICommandAction, ICommandActionParams, ICommandArgumentConfig, ICommandArgumentKind, ICommandArgumentType, ICommandArgvSegment, ICommandBuiltinConfig, ICommandBuiltinOptionConfig, ICommandBuiltinOptionResolved, ICommandBuiltinParsedOptions, ICommandBuiltinResolved, ICommandConfig, ICommandContext, ICommandControlScanResult, ICommandControls, ICommandErrorIssue, ICommandErrorIssueCode, ICommandErrorMeta, ICommandExample, ICommandHintIssue, ICommandHintIssueCode, ICommandInputSources, ICommandIssue, ICommandIssueBase, ICommandIssueCode, ICommandIssueKind, ICommandIssueReason, ICommandIssueScope, ICommandIssueSourceAttribution, ICommandOptionArgs, ICommandOptionConfig, ICommandOptionType, ICommandParseResult, ICommandParsedArgs, ICommandParsedOpts, ICommandPresetConfig, ICommandPresetIssueMeta, ICommandPresetProfileDefaults, ICommandPresetProfileItem, ICommandPresetProfileManifest, ICommandPresetProfileOptionValue, ICommandPresetProfileVariantItem, ICommandPresetResult, ICommandPresetSourceMeta, ICommandPresetSourceState, ICommandResolveResult, ICommandRouteResult, ICommandRunParams, ICommandRuntime, ICommandRuntimeStats, ICommandShiftResult, ICommandStage, ICommandToken, ICommandTokenSource, ICommandTokenType, ICommandTokenizeResult, ICommanderErrorKind, ICompletionArgumentMeta, ICompletionCommandConfig, ICompletionMeta, ICompletionOptionMeta, ICompletionPaths, ICompletionShellType, IHelpArgumentLine, IHelpCommandLine, IHelpData, IHelpExampleLine, IHelpOptionLine, IHelpPresetDirectiveLine, ISubcommandEntry };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@guanghechen/commander",
-  "version": "4.7.9",
+  "version": "4.8.1",
   "description": "A minimal, type-safe command-line interface builder with fluent API",
   "author": {
     "name": "guanghechen",

package/lib/schema/preset.config.schema.json

@@ -1,152 +0,0 @@
-{
-  "$schema": "https://json-schema.org/draft/2020-12/schema",
-  "$id": "https://guanghechen.github.io/sora/schemas/commander/preset.config.schema.json",
-  "title": "Commander Preset Config",
-  "description": "Preset profile manifest for @guanghechen/commander --preset-file.",
-  "type": "object",
-  "additionalProperties": false,
-  "required": ["version", "profiles"],
-  "examples": [
-    {
-      "version": 1,
-      "defaults": { "profile": "dev:local" },
-      "profiles": {
-        "dev": {
-          "envFile": "dev.env",
-          "envs": { "NODE_ENV": "development" },
-          "opts": { "logLevel": "debug", "retry": 2 },
-          "defaultVariant": "local",
-          "variants": {
-            "local": { "opts": { "retry": 1 } },
-            "ci": { "envFile": "ci.env", "envs": { "CI": "1" } }
-          }
-        }
-      }
-    }
-  ],
-  "properties": {
-    "$schema": {
-      "type": "string",
-      "description": "Optional schema reference for editors (e.g. VSCode)."
-    },
-    "version": {
-      "type": "integer",
-      "const": 1,
-      "description": "Schema version."
-    },
-    "defaults": {
-      "type": "object",
-      "additionalProperties": false,
-      "properties": {
-        "profile": {
-          "$ref": "#/$defs/profileSelector"
-        }
-      },
-      "description": "Default selector when --preset-profile is not provided."
-    },
-    "profiles": {
-      "type": "object",
-      "minProperties": 1,
-      "propertyNames": {
-        "$ref": "#/$defs/profileName"
-      },
-      "additionalProperties": {
-        "$ref": "#/$defs/profileItem"
-      },
-      "description": "Profiles keyed by profile name."
-    }
-  },
-  "$defs": {
-    "profileName": {
-      "type": "string",
-      "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]*$",
-      "description": "Profile/variant name."
-    },
-    "profileSelector": {
-      "type": "string",
-      "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]*(?::[A-Za-z0-9][A-Za-z0-9._-]*)?$",
-      "description": "Selector format: <profile> or <profile>:<variant>."
-    },
-    "optionName": {
-      "type": "string",
-      "pattern": "^(?:--)?(?:[a-z][a-zA-Z0-9]*|[A-Za-z][A-Za-z0-9]*(?:-[A-Za-z0-9]+)+)$",
-      "description": "Option key in opts map; aligned with runtime normalization."
-    },
-    "optionValue": {
-      "oneOf": [
-        { "type": "boolean" },
-        { "type": "string" },
-        { "type": "number" },
-        {
-          "type": "array",
-          "items": {
-            "oneOf": [{ "type": "string" }, { "type": "number" }]
-          }
-        }
-      ]
-    },
-    "envMap": {
-      "type": "object",
-      "additionalProperties": {
-        "type": "string"
-      }
-    },
-    "optsMap": {
-      "type": "object",
-      "propertyNames": {
-        "$ref": "#/$defs/optionName"
-      },
-      "additionalProperties": {
-        "$ref": "#/$defs/optionValue"
-      }
-    },
-    "variantItem": {
-      "type": "object",
-      "additionalProperties": false,
-      "properties": {
-        "envFile": {
-          "type": "string",
-          "minLength": 1
-        },
-        "envs": {
-          "$ref": "#/$defs/envMap"
-        },
-        "opts": {
-          "$ref": "#/$defs/optsMap"
-        }
-      }
-    },
-    "variantsMap": {
-      "type": "object",
-      "propertyNames": {
-        "$ref": "#/$defs/profileName"
-      },
-      "additionalProperties": {
-        "$ref": "#/$defs/variantItem"
-      }
-    },
-    "profileItem": {
-      "type": "object",
-      "additionalProperties": false,
-      "properties": {
-        "envFile": {
-          "type": "string",
-          "minLength": 1
-        },
-        "envs": {
-          "$ref": "#/$defs/envMap"
-        },
-        "opts": {
-          "$ref": "#/$defs/optsMap"
-        },
-        "defaultVariant": {
-          "$ref": "#/$defs/profileName"
-        },
-        "variants": {
-          "$ref": "#/$defs/variantsMap"
-        }
-      },
-      "description": "defaultVariant existence in variants must still be validated by runtime."
-    }
-  }
-}