@qui-cli/core 4.1.0 → 5.0.1

package/CHANGELOG.md

@@ -2,35 +2,54 @@
 
 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/core/4.0.1...core/4.1.0) (2025-11-04)
+## [5.0.1](https://github.com/battis/qui-cli/compare/core/5.0.0...core/5.0.1) (2025-12-19)
+
+
+### Bug Fixes
+
+* update documentation to reflect current core plugin model ([dbb3f26](https://github.com/battis/qui-cli/commit/dbb3f269d3dc3996c1d7050eb3a1acfdd08ab640))
+
+## [5.0.0](https://github.com/battis/qui-cli/compare/core/4.1.0...core/5.0.0) (2025-11-07)
+
+### ⚠ BREAKING CHANGES
+
+- group arguments by plugin in usage
+- **plugin@4.0.0** auto-document default arg values
 
+### revert
+
+- group arguments by plugin in usage ([ec3d4bf](https://github.com/battis/qui-cli/commit/ec3d4bf6ef9c59a6da3ede8603554d2dcd2581ad))
+- **plugin@4.0.0** auto-document default arg values ([e01e157](https://github.com/battis/qui-cli/commit/e01e157f06a3a801628ca79366e3f0060be2322e))
+
+### Bug Fixes
+
+- merge plugin option in Plugin.Registrar, not in Core ([9a7464f](https://github.com/battis/qui-cli/commit/9a7464fab863c7a9005ade54703726cc9679c8c4))
+
+## [4.1.0](https://github.com/battis/qui-cli/compare/core/4.0.1...core/4.1.0) (2025-11-04)
 
 ### Features
 
-* support scripting markdown documentation for commands ([03ee6d5](https://github.com/battis/qui-cli/commit/03ee6d55f86f6d7b45bd205896cb0fb6a21523b5))
+- support scripting markdown documentation for commands ([03ee6d5](https://github.com/battis/qui-cli/commit/03ee6d55f86f6d7b45bd205896cb0fb6a21523b5))
 
 ## [4.0.1](https://github.com/battis/qui-cli/compare/core/4.0.0...core/4.0.1) (2025-08-04)
 
-
 ### Bug Fixes
 
-* update lagging peer dependency specs ([30c0c27](https://github.com/battis/qui-cli/commit/30c0c279d4247a69a30efef8a7426442752cd9c0))
+- update lagging peer dependency specs ([30c0c27](https://github.com/battis/qui-cli/commit/30c0c279d4247a69a30efef8a7426442752cd9c0))
 
 ## [4.0.0](https://github.com/battis/qui-cli/compare/core/3.1.0...core/4.0.0) (2025-08-02)
 
-
 ### ⚠ BREAKING CHANGES
 
-* rename @battis/qui-cli.core --> @qui-cli/core
-
-* rename @battis/qui-cli.core --> @qui-cli/core ([43367e9](https://github.com/battis/qui-cli/commit/43367e9d4316aa22fb28078e9436e6de35564f1f))
+- rename @battis/qui-cli.core --> @qui-cli/core
 
+- rename @battis/qui-cli.core --> @qui-cli/core ([43367e9](https://github.com/battis/qui-cli/commit/43367e9d4316aa22fb28078e9436e6de35564f1f))
 
 ### Bug Fixes
 
-* update dependencies to renamed @qui-cli/colors ([ff80e86](https://github.com/battis/qui-cli/commit/ff80e8625ef98834afdf04e57bfedb1906834e2b))
-* update dependencies to renamed @qui-cli/log ([1c8f0fb](https://github.com/battis/qui-cli/commit/1c8f0fbd5561b4274032382c5d10d33912956e7f))
-* update dependencies to renamed @qui-cli/plugin ([117ea85](https://github.com/battis/qui-cli/commit/117ea85256ec69c807c5b56293546d9c350fd43f))
+- update dependencies to renamed @qui-cli/colors ([ff80e86](https://github.com/battis/qui-cli/commit/ff80e8625ef98834afdf04e57bfedb1906834e2b))
+- update dependencies to renamed @qui-cli/log ([1c8f0fb](https://github.com/battis/qui-cli/commit/1c8f0fbd5561b4274032382c5d10d33912956e7f))
+- update dependencies to renamed @qui-cli/plugin ([117ea85](https://github.com/battis/qui-cli/commit/117ea85256ec69c807c5b56293546d9c350fd43f))
 
 ## [3.1.0](https://github.com/battis/qui-cli/compare/core/3.0.0...core/3.1.0) (2025-08-01)
 

package/README.md

@@ -44,19 +44,29 @@ See [examples](https://github.com/battis/qui-cli/tree/main/examples#readme) for
 
 Three core plugins are registered automatically to provide consistent functionality.
 
-### `jackspeak`
+### `JackSpeak`
 
-Manages any custom [jackspeak](https://www.npmjs.com/package/jackspeak#user-content-jackoptions-jackoptions----jack) options. As with any other plugin, it can be configured via `Core.configure()`:
+Manages any custom [jackspeak](https://www.npmjs.com/package/jackspeak#user-content-jackoptions-jackoptions----jack) options. As with any other plugin, it can be configured via `configure()`:
 
 ```ts
-await Core.configure({
-  jackspeak: {
-    envPrefix: 'MY_APP'
+import { Core, JackSpeak } from '@qui-cli/core';
+
+await JackSpeak.configure({
+  envPrefix: 'MY_APP'
+});
+
+await Core.init({
+  foo: {
+    description: 'bar'
   }
 });
+
+await Core.run();
+
+console.log(process.env.MY_APP_FOO);
 ```
 
-### `positionals`
+### `Positionals`
 
 Provides per-plugin positonal argument management and documentation. Individual plugins can require named positional arguments, which are collected and documented by `usage()` and accessible throgh the `Positionals` plugin.
 
@@ -97,7 +107,7 @@ Positionals.setMinArg(6);
 Positionals.setMaxArg(4);
 ```
 
-### `help`
+### `Help`
 
 Provides consistent `--help` (`-h`) flag for all commands that displays usage. No confiuration.
 

package/dist/Core.d.ts

@@ -3,13 +3,12 @@ import * as JackSpeak from './JackSpeak.js';
 export { Options } from '@qui-cli/plugin';
 export * from './Usage.js';
 export type Configuration = Plugin.Registrar.Configuration & {
-    /** @deprecated Use `jackspeak` property */
+    /** @deprecated Use {@link JackSpeak} core plugin */
     core?: JackSpeak.Configuration & {
-        /** @deprecated Use `Positional` plugin */
+        /** @deprecated Use {@link Positionals} core plugin */
         requirePositionals?: boolean | number;
     };
 };
 export declare function configure(config?: Configuration): Promise<void>;
-export declare function options(externalOptions?: Plugin.Options): Promise<Plugin.Options>;
 export declare function init(externalOptions?: Plugin.Options): Promise<Plugin.Arguments<Plugin.Options>>;
 export declare function run(externalOptions?: Plugin.Options): Promise<Plugin.AccumulatedResults | undefined>;

package/dist/Core.js

@@ -18,14 +18,6 @@ export async function configure(config = {}) {
     }
     await Plugin.Registrar.configure({ positionals, jackspeak });
 }
-export async function options(externalOptions = {}) {
-    /*
-     * TODO automate default value documentation
-       Issue URL: https://github.com/battis/qui-cli/issues/38
-     *  Including parsing `env` (#34) and `secret` (#33) fields
-     */
-    return Plugin.mergeOptions(await Plugin.Registrar.options(), externalOptions);
-}
 export async function init(externalOptions) {
     if (initialized) {
         throw new Error(`Already initialized with user-provided command line arguments.`);
@@ -36,7 +28,7 @@ export async function init(externalOptions) {
         }
     }
     if (externalOptions) {
-        JackSpeak.args(externalOptions);
+        JackSpeak.args(Plugin.documentDefaults(externalOptions));
     }
     const args = JackSpeak.parse();
     await Plugin.Registrar.init(args);

package/dist/Help.d.ts

@@ -1,5 +1,6 @@
 import * as Plugin from '@qui-cli/plugin';
 export type Configuration = Plugin.Configuration & {
+    /** Get usage information */
     help?: boolean;
 };
 export declare const name = "core.help";

package/dist/JackSpeak.d.ts

@@ -6,5 +6,18 @@ export declare function jack(): Jack<{}>;
 export declare function configure(config?: Configuration): void;
 export declare function args(options: Plugin.Options): void;
 export declare function parse(): import("jackspeak").Parsed<{}>;
+export declare function toJSON(): {
+    [k: string]: {
+        hint?: string | undefined;
+        default?: import("jackspeak").ConfigValue | undefined;
+        validOptions?: readonly number[] | readonly string[] | undefined;
+        validate?: ((v: unknown) => boolean) | ((v: unknown) => v is import("jackspeak").ValidValue<import("jackspeak").ConfigType, boolean>) | undefined;
+        description?: string | undefined;
+        short?: string | undefined;
+        delim?: string | undefined;
+        multiple?: boolean | undefined;
+        type: import("jackspeak").ConfigType;
+    };
+};
 export declare function usage(): string;
 export declare function usageMarkdown(): string;

package/dist/JackSpeak.js

@@ -39,6 +39,9 @@ export function args(options) {
 export function parse() {
     return jack().parse();
 }
+export function toJSON() {
+    return jack().toJSON();
+}
 export function usage() {
     return jack().usage();
 }

package/dist/Positionals.d.ts

@@ -1,12 +1,17 @@
 import * as Plugin from '@qui-cli/plugin';
 type PositionalConfig = {
+    /** Description of the purpose of the positional argument */
     description?: string;
+    /** Hint about the value of the positional argument */
     hint?: string;
+    /** Must return true for the argument to be accepted */
     validate?: (v?: string) => boolean | string;
 };
 type PositionalConfigSet = Record<string, PositionalConfig>;
 export type Configuration = Plugin.Configuration & {
+    /** Minimum number of accepted positional arguments */
     min?: number;
+    /** Maximum number of accepted positional arguments */
     max?: number;
 };
 export declare const name = "positionals";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@qui-cli/core",
-  "version": "4.1.0",
+  "version": "5.0.1",
   "description": "Core features of @qui-cli/qui-cli",
   "homepage": "https://github.com/battis/qui-cli/tree/main/packages/core#readme",
   "repository": {
@@ -18,7 +18,8 @@
   "types": "./dist/index.d.ts",
   "dependencies": {
     "jackspeak": "^4.1.1",
-    "wrap-ansi": "^9.0.2"
+    "wrap-ansi": "^9.0.2",
+    "@qui-cli/colors": "3.1.1"
   },
   "devDependencies": {
     "@tsconfig/node20": "^20.1.6",
@@ -26,13 +27,11 @@
     "commit-and-tag-version": "^12.6.0",
     "del-cli": "^6.0.0",
     "npm-run-all": "^4.1.5",
-    "typescript": "~5.8.3",
-    "@qui-cli/plugin": "3.0.0",
-    "@qui-cli/colors": "3.0.1"
+    "typescript": "^5.9.3",
+    "@qui-cli/plugin": "4.0.0"
   },
   "peerDependencies": {
-    "@qui-cli/colors": "3.x",
-    "@qui-cli/plugin": "3.x"
+    "@qui-cli/plugin": "4.x"
   },
   "target": "node",
   "scripts": {