@qui-cli/plugin 3.0.0 → 4.1.0

package/CHANGELOG.md

@@ -2,6 +2,37 @@
 
 All notable changes to this project will be documented in this file. See [commit-and-tag-version](https://github.com/absolute-version/commit-and-tag-version) for commit guidelines.
 
+## [4.1.0](https://github.com/battis/qui-cli/compare/plugin/4.0.0...plugin/4.1.0) (2026-01-18)
+
+
+### Features
+
+* deprecated Plugin.hydrate() ([4194966](https://github.com/battis/qui-cli/commit/41949660396847f2560675242aed460370a3b7b4))
+* simple Plugin.Conf.defaultHook() factory ([ee881f6](https://github.com/battis/qui-cli/commit/ee881f6bf91b39876dc05a49f434260725e52301))
+
+
+### Bug Fixes
+
+* compile against Node.js v24 ([7b06b4f](https://github.com/battis/qui-cli/commit/7b06b4f4ac4f9688719041ab8b1d837b3a0ee214))
+* no longer require ESM modules only as plugins ([cbf178c](https://github.com/battis/qui-cli/commit/cbf178c8a6f3cec49aff8b6de08fd547e66fb9f7))
+
+## [4.0.0](https://github.com/battis/qui-cli/compare/plugin/3.0.0...plugin/4.0.0) (2025-11-07)
+
+
+### ⚠ BREAKING CHANGES
+
+* group arguments by plugin in usage
+* auto-document default arg values
+
+### revert
+
+* group arguments by plugin in usage ([ec3d4bf](https://github.com/battis/qui-cli/commit/ec3d4bf6ef9c59a6da3ede8603554d2dcd2581ad))
+
+
+### Features
+
+* auto-document default arg values ([e01e157](https://github.com/battis/qui-cli/commit/e01e157f06a3a801628ca79366e3f0060be2322e))
+
 ## [3.0.0](https://github.com/battis/qui-cli/compare/plugin/2.4.2...plugin/3.0.0) (2025-08-02)
 
 

package/README.md

@@ -158,7 +158,7 @@ export function options() {
     },
     opt: {
       bar: {
-        description: `Bar value (default: "argle-bargle")`,
+        description: `Bar value`,
         short: 'b',
         default: 'argle-bargle'
       }

package/dist/Conf.d.ts

@@ -0,0 +1,5 @@
+export type Base = Record<string, unknown>;
+export type Hook<C extends Base = Base> = (config: C) => void | Promise<void>;
+export type Validator<C extends Base = Base> = Record<keyof C, (proposal?: unknown) => boolean | Promise<boolean>>;
+export declare function propose<C extends Base = Base>(config: C, proposal?: C, validator?: Validator<C>): Promise<void>;
+export declare function defaultHook<C extends Base = Base>(config: C, validator?: Validator<C>): Hook<C>;

package/dist/Conf.js

@@ -0,0 +1,12 @@
+export async function propose(config, proposal = {}, validator = {}) {
+    for (const key in proposal) {
+        if (proposal[key] !== undefined) {
+            if (!validator[key] || (await validator[key](proposal[key]))) {
+                config[key] = proposal[key];
+            }
+        }
+    }
+}
+export function defaultHook(config, validator) {
+    return async (proposal = {}) => propose(config, proposal, validator);
+}

package/dist/{Utilities/hydrate.d.ts → Deprecated.d.ts}

@@ -1 +1,2 @@
+/** @deprecated use default  */
 export declare function hydrate<Fallback, Proposed extends Fallback | undefined>(proposed: Proposed, fallback: Fallback): Fallback;

package/dist/{Utilities/hydrate.js → Deprecated.js}

@@ -1,3 +1,4 @@
+/** @deprecated use default  */
 export function hydrate(proposed, fallback) {
     if (proposed === undefined) {
         return fallback;

package/dist/Init.d.ts

@@ -0,0 +1,10 @@
+import { ConfigSetFromMetaSet, OptionsResults } from 'jackspeak';
+import * as Opt from './Opt.js';
+type FlattenConfigMetaSets<O extends Opt.Options> = ConfigSetFromMetaSet<'number', false, Exclude<O['num'], undefined>> & ConfigSetFromMetaSet<'number', true, Exclude<O['numList'], undefined>> & ConfigSetFromMetaSet<'string', false, Exclude<O['opt'], undefined>> & ConfigSetFromMetaSet<'string', false, Exclude<O['opt'], undefined>> & ConfigSetFromMetaSet<'string', true, Exclude<O['optList'], undefined>> & ConfigSetFromMetaSet<'boolean', false, Exclude<O['flag'], undefined>> & ConfigSetFromMetaSet<'boolean', true, Exclude<O['flagList'], undefined>> & Exclude<O['fields'], undefined>;
+export type Arguments<O extends Opt.Options> = {
+    positionals: (string | undefined)[];
+    values: OptionsResults<FlattenConfigMetaSets<O>>;
+};
+export type ExpectedArguments<H extends Opt.Hook> = Arguments<Awaited<ReturnType<H>>>;
+export type Hook<O extends Opt.Options = Opt.Options> = (args: Arguments<O>) => void | Promise<void>;
+export {};

package/dist/{Options.d.ts → Opt.d.ts}

@@ -1,7 +1,12 @@
 import { ConfigMetaSet, ConfigSet, ConfigType } from 'jackspeak';
+type DocumentationOptions = {
+    [longOption: string]: {
+        secret?: boolean;
+    };
+};
 type MetaSet<T extends ConfigType> = {
-    value: ConfigMetaSet<T, false>;
-    list: ConfigMetaSet<T, true>;
+    value: ConfigMetaSet<T, false> & DocumentationOptions;
+    list: ConfigMetaSet<T, true> & DocumentationOptions;
 };
 type opt = MetaSet<'string'>;
 type flag = MetaSet<'boolean'>;
@@ -21,6 +26,6 @@ export type Options = {
     fields?: ConfigSet;
     man?: Paragraph[];
 };
-export declare function merge<A extends Options = Options, B extends Options = Options>(a: A, b: B): A & B;
+export declare function documentDefaults(options: Options): Options;
 export type Hook = () => Options | Promise<Options>;
 export {};

package/dist/Opt.js

@@ -0,0 +1,46 @@
+import { Colors } from '@qui-cli/colors';
+function stringify(value) {
+    switch (typeof value) {
+        case 'string':
+            return Colors.quotedValue(`"${value}"`);
+        case 'object':
+            return Colors.regexpValue(value);
+        default:
+            return Colors.value(value);
+    }
+}
+export function documentDefaults(options) {
+    let paramType;
+    for (paramType in options) {
+        if (paramType !== 'man' && paramType !== 'fields') {
+            const params = options[paramType];
+            if (params) {
+                let paramName;
+                for (paramName in params) {
+                    const param = params[paramName];
+                    let docs = '';
+                    if (param.default !== undefined && !param.secret) {
+                        if (!docs.length) {
+                            docs = 'Default';
+                        }
+                        docs = `${docs}: ${Array.isArray(param.default)
+                            ? param.default.map((v) => stringify(v)).join(', ')
+                            : stringify(param.default)}`;
+                    }
+                    if (paramType === 'flag' && param.default) {
+                        docs = `${docs}${docs.length ? ', u' : 'U'}se ${Colors.flagArg(`--no-${paramName}`)} to disable`;
+                    }
+                    if (docs.length) {
+                        if (param.description?.length) {
+                            param.description = `${param.description} (${docs})`;
+                        }
+                        else {
+                            param.description = docs;
+                        }
+                    }
+                }
+            }
+        }
+    }
+    return options;
+}

package/dist/Plugin.d.ts

@@ -1,11 +1,11 @@
-import * as Configuration from './Configuration.js';
-import * as Initialization from './Initialization.js';
-import * as Options from './Options.js';
+import * as Conf from './Conf.js';
+import * as Init from './Init.js';
+import * as Opt from './Opt.js';
 import * as Run from './Run.js';
 export type Base = {
     name: string;
-    configure?: Configuration.Hook;
-    options?: Options.Hook;
-    init?: Initialization.Hook;
+    configure?: Conf.Hook;
+    options?: Opt.Hook;
+    init?: Init.Hook;
     run?: Run.Hook;
 } & Record<string, unknown>;

package/dist/Registrar.d.ts

@@ -1,15 +1,14 @@
-import { Base as PluginConfiguration } from './Configuration.js';
-import { Arguments } from './Initialization.js';
-import { Options } from './Options.js';
-import { Base as Plugin } from './Plugin.js';
-import { AccumulatedResults } from './Run.js';
-export declare function registered(): Plugin[];
-export declare function register(plugin: Plugin): Promise<void>;
+import * as Conf from './Conf.js';
+import * as Init from './Init.js';
+import * as Opt from './Opt.js';
+import * as Plugin from './Plugin.js';
+import * as Run from './Run.js';
+export declare function registered(): Plugin.Base[];
+export declare function register(plugin: Plugin.Base): Promise<void>;
 export declare function reset(): void;
 export type Configuration = {
-    [key: string]: PluginConfiguration;
+    [key: string]: Conf.Base;
 };
 export declare function configure(config?: Configuration): Promise<void>;
-export declare function options(): Promise<Options>;
-export declare function init(args: Arguments<Awaited<ReturnType<typeof options>>>): Promise<void>;
-export declare function run(): Promise<AccumulatedResults>;
+export declare function init(args: Init.Arguments<Opt.Options>): Promise<void>;
+export declare function run(): Promise<Run.AccumulatedResults>;

package/dist/Registrar.js

@@ -1,4 +1,4 @@
-import { merge } from './Options.js';
+import * as Opt from './Opt.js';
 const plugins = [];
 export function registered() {
     return plugins;
@@ -12,7 +12,15 @@ export async function register(plugin) {
             return;
         }
     }
-    plugins.push(plugin);
+    plugins.push({
+        name: plugin.name,
+        configure: plugin.configure ? plugin.configure.bind(plugin) : undefined,
+        options: plugin.options
+            ? async () => plugin.options ? Opt.documentDefaults(await plugin.options()) : {}
+            : undefined,
+        init: plugin.init ? plugin.init.bind(plugin) : undefined,
+        run: plugin.run ? plugin.run.bind(plugin) : undefined
+    });
 }
 export function reset() {
     for (const name in plugins) {
@@ -26,15 +34,6 @@ export async function configure(config = {}) {
         }
     }
 }
-export async function options() {
-    let options = {};
-    for (const plugin of plugins) {
-        if (plugin.options) {
-            options = merge(options, await plugin.options());
-        }
-    }
-    return options;
-}
 export async function init(args) {
     for (const plugin of plugins) {
         if (plugin.init) {

package/dist/Run.d.ts

@@ -1,3 +1,3 @@
-export type Result = any;
+export type Result = unknown;
 export type AccumulatedResults = Record<string, Result>;
 export type Hook = (results?: AccumulatedResults) => Result | Promise<Result>;

package/dist/index.d.ts

@@ -1,9 +1,11 @@
-import { merge } from './Options.js';
-import { register } from './Registrar.js';
-export { Base as Configuration } from './Configuration.js';
-export { Arguments, ExpectedArguments } from './Initialization.js';
-export { Options } from './Options.js';
+export * as Conf from './Conf.js';
+export * as Init from './Init.js';
+export * as Opt from './Opt.js';
 export * as Registrar from './Registrar.js';
+export * as Run from './Run.js';
+export { Base as Configuration } from './Conf.js';
+export { Arguments, ExpectedArguments } from './Init.js';
+export { Options, documentDefaults } from './Opt.js';
 export { AccumulatedResults } from './Run.js';
-export * from './Utilities.js';
-export { merge as mergeOptions, register };
+export { register } from './Registrar.js';
+export * from './Deprecated.js';

package/dist/index.js

@@ -1,5 +1,8 @@
-import { merge } from './Options.js';
-import { register } from './Registrar.js';
+export * as Conf from './Conf.js';
+export * as Init from './Init.js';
+export * as Opt from './Opt.js';
 export * as Registrar from './Registrar.js';
-export * from './Utilities.js';
-export { merge as mergeOptions, register };
+export * as Run from './Run.js';
+export { documentDefaults } from './Opt.js';
+export { register } from './Registrar.js';
+export * from './Deprecated.js';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@qui-cli/plugin",
-  "version": "3.0.0",
+  "version": "4.1.0",
   "description": "@qui-cli plugin structure and registrar",
   "homepage": "https://github.com/battis/qui-cli/tree/main/packages/plugin#readme",
   "repository": {
@@ -17,15 +17,16 @@
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
   "dependencies": {
-    "jackspeak": "^4.1.1"
+    "jackspeak": "^4.1.1",
+    "@qui-cli/colors": "3.2.3"
   },
   "devDependencies": {
-    "@tsconfig/node20": "^20.1.6",
-    "@types/node": "^24.1.0",
-    "commit-and-tag-version": "^12.5.2",
-    "del-cli": "^6.0.0",
+    "@tsconfig/node24": "^24.0.4",
+    "@types/node": "^24.10.9",
+    "commit-and-tag-version": "^12.6.1",
+    "del-cli": "^7.0.0",
     "npm-run-all": "^4.1.5",
-    "typescript": "^5.9.2"
+    "typescript": "^5.9.3"
   },
   "target": "node",
   "scripts": {
@@ -33,6 +34,6 @@
     "build": "run-s build:*",
     "build:clean": "run-s clean",
     "build:compile": "tsc",
-    "release": "commit-and-tag-version"
+    "version": "commit-and-tag-version"
   }
 }

package/dist/Configuration.d.ts

@@ -1,2 +0,0 @@
-export type Base = Record<string, unknown>;
-export type Hook = (config: Base) => void | Promise<void>;

package/dist/Initialization.d.ts

@@ -1,10 +0,0 @@
-import { ConfigSetFromMetaSet, OptionsResults } from 'jackspeak';
-import * as Options from './Options.js';
-type FlattenConfigMetaSets<O extends Options.Options> = ConfigSetFromMetaSet<'number', false, Exclude<O['num'], undefined>> & ConfigSetFromMetaSet<'number', true, Exclude<O['numList'], undefined>> & ConfigSetFromMetaSet<'string', false, Exclude<O['opt'], undefined>> & ConfigSetFromMetaSet<'string', false, Exclude<O['opt'], undefined>> & ConfigSetFromMetaSet<'string', true, Exclude<O['optList'], undefined>> & ConfigSetFromMetaSet<'boolean', false, Exclude<O['flag'], undefined>> & ConfigSetFromMetaSet<'boolean', true, Exclude<O['flagList'], undefined>> & Exclude<O['fields'], undefined>;
-export type Arguments<O extends Options.Options> = {
-    positionals: (string | undefined)[];
-    values: OptionsResults<FlattenConfigMetaSets<O>>;
-};
-export type ExpectedArguments<H extends Options.Hook> = Arguments<Awaited<ReturnType<H>>>;
-export type Hook<O extends Options.Options = Options.Options> = (args: Arguments<O>) => void | Promise<void>;
-export {};

package/dist/Initialization.js

@@ -1 +0,0 @@
-export {};

package/dist/Options.js

@@ -1,12 +0,0 @@
-export function merge(a, b) {
-    return {
-        num: { ...a.num, ...b.num },
-        numList: { ...a.numList, ...b.numList },
-        opt: { ...a.opt, ...b.opt },
-        optList: { ...a.optList, ...b.optList },
-        flag: { ...a.flag, ...b.flag },
-        flagList: { ...a.flagList, ...b.flagList },
-        fields: { ...a.fields, ...b.fields },
-        man: [...(a.man || []), ...(b.man || [])]
-    };
-}

package/dist/Utilities.d.ts

@@ -1 +0,0 @@
-export * from './Utilities/hydrate.js';

package/dist/Utilities.js

@@ -1 +0,0 @@
-export * from './Utilities/hydrate.js';