@qui-cli/plugin 3.0.0 → 4.0.0

package/CHANGELOG.md

@@ -2,6 +2,23 @@
 
 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.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/Options.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/Options.js

@@ -1,12 +1,46 @@
-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 || [])]
-    };
+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/Registrar.d.ts

@@ -10,6 +10,5 @@ export type Configuration = {
     [key: string]: PluginConfiguration;
 };
 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 init(args: Arguments<Options>): Promise<void>;
 export declare function run(): Promise<AccumulatedResults>;

package/dist/Registrar.js

@@ -1,4 +1,4 @@
-import { merge } from './Options.js';
+import { documentDefaults } from './Options.js';
 const plugins = [];
 export function registered() {
     return plugins;
@@ -12,7 +12,17 @@ export async function register(plugin) {
             return;
         }
     }
-    plugins.push(plugin);
+    plugins.push({
+        ...plugin,
+        options: async () => {
+            if (plugin.options) {
+                return documentDefaults(await plugin.options());
+            }
+            else {
+                return {};
+            }
+        }
+    });
 }
 export function reset() {
     for (const name in plugins) {
@@ -26,15 +36,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/index.d.ts

@@ -1,9 +1,7 @@
-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 { Options, documentDefaults } from './Options.js';
 export * as Registrar from './Registrar.js';
 export { AccumulatedResults } from './Run.js';
 export * from './Utilities.js';
-export { merge as mergeOptions, register };
+export { register } from './Registrar.js';

package/dist/index.js

@@ -1,5 +1,4 @@
-import { merge } from './Options.js';
-import { register } from './Registrar.js';
+export { documentDefaults } from './Options.js';
 export * as Registrar from './Registrar.js';
 export * from './Utilities.js';
-export { merge as mergeOptions, register };
+export { register } from './Registrar.js';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@qui-cli/plugin",
-  "version": "3.0.0",
+  "version": "4.0.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.1.0"
   },
   "devDependencies": {
     "@tsconfig/node20": "^20.1.6",
-    "@types/node": "^24.1.0",
-    "commit-and-tag-version": "^12.5.2",
+    "@types/node": "^24.10.0",
+    "commit-and-tag-version": "^12.6.0",
     "del-cli": "^6.0.0",
     "npm-run-all": "^4.1.5",
-    "typescript": "^5.9.2"
+    "typescript": "^5.9.3"
   },
   "target": "node",
   "scripts": {