@qui-cli/core 6.0.1 → 6.0.3

package/CHANGELOG.md

@@ -2,6 +2,22 @@
 
 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.
 
+## [6.0.3](https://github.com/battis/qui-cli/compare/core/6.0.2...core/6.0.3) (2026-02-22)
+
+
+### Bug Fixes
+
+* allow overlaying configurations in Jackspeak, as in other plugins ([29bc7ad](https://github.com/battis/qui-cli/commit/29bc7adfdbafb3d961e0768988473d3f2ecd6aaf))
+* extirpate last non-debugging console.log invocation ([d67975d](https://github.com/battis/qui-cli/commit/d67975d80aa47b2e5ffefdb2fff35fbdec726277))
+* initialize Positionals options to correctly display plugin-required positionals ([fde874c](https://github.com/battis/qui-cli/commit/fde874ca39d9823892d49ff3009a9c2afece84eb))
+
+## [6.0.2](https://github.com/battis/qui-cli/compare/core/6.0.1...core/6.0.2) (2026-02-21)
+
+
+### Bug Fixes
+
+* display positional arg documentation ([c97c454](https://github.com/battis/qui-cli/commit/c97c45477df474880b6ae3071d4e9c2f11b17a97))
+
 ## [6.0.1](https://github.com/battis/qui-cli/compare/core/6.0.0...core/6.0.1) (2026-02-21)
 
 

package/dist/Core.d.ts

@@ -2,6 +2,7 @@ import * as Plugin from '@qui-cli/plugin';
 import * as JackSpeak from './JackSpeak.js';
 export { Options } from '@qui-cli/plugin';
 export * from './Usage.js';
+/** Core configuration options */
 export type Configuration = Plugin.Registrar.Configuration & {
     /**
      * Usage information for plugins is diplayed in LIFO (last-in, first-out)
@@ -18,6 +19,34 @@ export type Configuration = Plugin.Registrar.Configuration & {
         requirePositionals?: boolean | number;
     };
 };
-export declare function configure(config?: Configuration): Promise<void>;
+/**
+ * Configure core options
+ *
+ * May be called multiple times, overlaying partial configurations they become
+ * available/defined
+ *
+ * @see {@link Configuration}
+ */
+export declare function configure(proposal?: Configuration): Promise<void>;
+/**
+ * Initialize plugins from the environment and provided command line options
+ *
+ * May only be called once
+ *
+ * @param externalOptions Optional additional options to initialze
+ * @returns Result of
+ *   {@link https://github.com/isaacs/jackspeak?tab=readme-ov-file#jackparseargs-string--processargv--positionals-string-values-optionsresults- Jackspeak.parse()}
+ *   (Additional Jackspeak configuration may be done via the {@link JackSpeak}
+ *   core plugin)
+ * @throws If invoked after {@link run} invocation or otherwise invoked for a
+ *   second time
+ */
 export declare function init(externalOptions?: Plugin.Options): Promise<Plugin.Arguments<Plugin.Options>>;
+/**
+ * Initialize plugins from provided command line options and the environment, if
+ * not already initialized and run registered plugins.
+ *
+ * @param externalOptions Optional additional options to initialze
+ * @returns Hash of accumulated results of all plugin `run()` methods
+ */
 export declare function run(externalOptions?: Plugin.Options): Promise<Plugin.AccumulatedResults | undefined>;

package/dist/Core.js

@@ -1,12 +1,24 @@
 import * as Plugin from '@qui-cli/plugin';
+import * as Help from './Help.js';
 import * as JackSpeak from './JackSpeak.js';
 import * as Positionals from './Positionals.js';
 export * from './Usage.js';
 let initialized = false;
-let lifoUsage = true;
-export async function configure(config = {}) {
-    lifoUsage = Plugin.hydrate(config.lifoUsage, lifoUsage);
-    const { core = {}, jackspeak: jackOptions, positionals = {} } = config;
+// TODO improve typing
+// Issue URL: https://github.com/battis/qui-cli/issues/100
+// @ts-expect-error 2322
+const config = { lifoUsage: true };
+/**
+ * Configure core options
+ *
+ * May be called multiple times, overlaying partial configurations they become
+ * available/defined
+ *
+ * @see {@link Configuration}
+ */
+export async function configure(proposal = {}) {
+    config.lifoUsage = Plugin.hydrate(proposal.lifoUsage, config.lifoUsage);
+    const { core = {}, jackspeak: jackOptions, positionals = {} } = proposal;
     const { requirePositionals, ...deprecated } = core;
     const jackspeak = {
         ...deprecated,
@@ -18,37 +30,56 @@ export async function configure(config = {}) {
     }
     await Plugin.Registrar.configure({ positionals, jackspeak });
 }
+function requireUnusedOptions(plugin) {
+    return (!!plugin.options &&
+        plugin.name !== Positionals.name &&
+        plugin.name !== Help.name);
+}
+/**
+ * Initialize plugins from the environment and provided command line options
+ *
+ * May only be called once
+ *
+ * @param externalOptions Optional additional options to initialze
+ * @returns Result of
+ *   {@link https://github.com/isaacs/jackspeak?tab=readme-ov-file#jackparseargs-string--processargv--positionals-string-values-optionsresults- Jackspeak.parse()}
+ *   (Additional Jackspeak configuration may be done via the {@link JackSpeak}
+ *   core plugin)
+ * @throws If invoked after {@link run} invocation or otherwise invoked for a
+ *   second time
+ */
 export async function init(externalOptions) {
     if (initialized) {
         throw new Error(`Already initialized with user-provided command line arguments.`);
     }
-    if (lifoUsage) {
-        // lifo plugin usage order
-        if (externalOptions) {
-            JackSpeak.args(Plugin.documentDefaults(externalOptions));
-        }
-        for (const plugin of Plugin.Registrar.registered().toReversed()) {
-            if (plugin.options) {
-                JackSpeak.args(await plugin.options());
-            }
-        }
+    const usage = [
+        ...(await Promise.all(Plugin.Registrar.registered()
+            .filter(requireUnusedOptions)
+            .map(async (plugin) => await plugin.options())))
+    ];
+    if (externalOptions) {
+        usage.push(Plugin.documentDefaults(externalOptions));
+    }
+    if (config.lifoUsage) {
+        usage.reverse();
     }
-    else {
-        // fifo plugin usage order
-        for (const plugin of Plugin.Registrar.registered()) {
-            if (plugin.options) {
-                JackSpeak.args(await plugin.options());
-            }
-        }
-        if (externalOptions) {
-            JackSpeak.args(Plugin.documentDefaults(externalOptions));
-        }
+    JackSpeak.args(Help.options());
+    JackSpeak.args(Positionals.options());
+    for (const options of usage) {
+        JackSpeak.args(options);
     }
     const args = JackSpeak.parse();
     await Plugin.Registrar.init(args);
     initialized = true;
     return args;
 }
+/**
+ * Initialize plugins from provided command line options and the environment, if
+ * not already initialized and run registered plugins.
+ *
+ * @param externalOptions Optional additional options to initialze
+ * @returns Hash of accumulated results of all plugin `run()` methods
+ */
 export async function run(externalOptions) {
     if (!initialized) {
         await init(externalOptions);

package/dist/Help.js

@@ -7,10 +7,9 @@ export function configure(config = {}) {
 }
 export function options() {
     return {
-        man: [{ level: 1, text: 'Usage information' }],
         flag: {
             help: {
-                description: 'Get usage information',
+                description: 'Show this usage information',
                 short: 'h'
             }
         }
@@ -19,7 +18,7 @@ export function options() {
 export function init({ values }) {
     configure(values);
     if (help) {
-        console.log(Core.usage());
+        process.stdout.write(Core.usage());
         process.exit(0);
     }
 }

package/dist/JackSpeak.d.ts

@@ -2,10 +2,26 @@ import * as Plugin from '@qui-cli/plugin';
 import { Jack, JackOptions } from 'jackspeak';
 export type Configuration = Plugin.Configuration & JackOptions;
 export declare const name = "jackspeak";
+/** Jackspeak instance used to parse command line arguments */
 export declare function jack(): Jack<{}>;
-export declare function configure(config?: Configuration): void;
+/**
+ * Configure Jackspeak options
+ *
+ * @see {@link JackOptions}
+ */
+export declare function configure(proposal?: Configuration): void;
+/**
+ * Apply {@link Plugin.Options} to Jackspeak
+ *
+ * Generally called only by Core
+ */
 export declare function args(options: Plugin.Options): void;
+/**
+ * Convenience pass-through to
+ * {@link https://github.com/isaacs/jackspeak?tab=readme-ov-file#jackparseargs-string--processargv--positionals-string-values-optionsresults- Jackspeak.parse()}
+ */
 export declare function parse(): import("jackspeak").Parsed<{}>;
+/** Convenience pass-through to (undocumented) Jackspeak.toJSON() */
 export declare function toJSON(): {
     [k: string]: {
         hint?: string | undefined;
@@ -19,5 +35,13 @@ export declare function toJSON(): {
         type: import("jackspeak").ConfigType;
     };
 };
+/**
+ * Convenience pass-through to
+ * {@link https://github.com/isaacs/jackspeak?tab=readme-ov-file#jackusage-string Jackspeak.usage()}
+ */
 export declare function usage(): string;
+/**
+ * Convenience pass-through to
+ * {@link https://github.com/isaacs/jackspeak?tab=readme-ov-file#jackusagemarkdown-string Jackspeak.usageMarkdown()}
+ */
 export declare function usageMarkdown(): string;

package/dist/JackSpeak.js

@@ -1,18 +1,39 @@
 import { Jack } from 'jackspeak';
 export const name = 'jackspeak';
+const config = {};
 let instance = undefined;
+/** Jackspeak instance used to parse command line arguments */
 export function jack() {
     if (!instance) {
-        configure();
+        instance = new Jack(config);
     }
     if (!instance) {
         throw new Error(`JackSpeak configuration failed.`);
     }
     return instance;
 }
-export function configure(config = {}) {
-    instance = new Jack(config);
+/**
+ * Configure Jackspeak options
+ *
+ * @see {@link JackOptions}
+ */
+export function configure(proposal = {}) {
+    let changed = false;
+    for (const key in proposal) {
+        if (proposal[key] !== undefined) {
+            changed = config[key] !== proposal[key];
+            config[key] = proposal[key];
+        }
+    }
+    if (changed) {
+        instance = undefined;
+    }
 }
+/**
+ * Apply {@link Plugin.Options} to Jackspeak
+ *
+ * Generally called only by Core
+ */
 export function args(options) {
     for (const key in options) {
         if (key === 'man') {
@@ -36,15 +57,28 @@ export function args(options) {
         }
     }
 }
+/**
+ * Convenience pass-through to
+ * {@link https://github.com/isaacs/jackspeak?tab=readme-ov-file#jackparseargs-string--processargv--positionals-string-values-optionsresults- Jackspeak.parse()}
+ */
 export function parse() {
     return jack().parse();
 }
+/** Convenience pass-through to (undocumented) Jackspeak.toJSON() */
 export function toJSON() {
     return jack().toJSON();
 }
+/**
+ * Convenience pass-through to
+ * {@link https://github.com/isaacs/jackspeak?tab=readme-ov-file#jackusage-string Jackspeak.usage()}
+ */
 export function usage() {
     return jack().usage();
 }
+/**
+ * Convenience pass-through to
+ * {@link https://github.com/isaacs/jackspeak?tab=readme-ov-file#jackusagemarkdown-string Jackspeak.usageMarkdown()}
+ */
 export function usageMarkdown() {
     return jack().usageMarkdown();
 }

package/dist/Positionals.d.ts

@@ -1,6 +1,11 @@
 import * as Plugin from '@qui-cli/plugin';
 type PositionalConfig = {
-    /** Description of the purpose of the positional argument */
+    /**
+     * Optional description of the purpose of the positional argument.
+     *
+     * If not provided, the argument will not be separately listed in the
+     * Positional usage section
+     */
     description?: string;
     /** Hint about the value of the positional argument */
     hint?: string;
@@ -9,6 +14,13 @@ type PositionalConfig = {
 };
 type PositionalConfigSet = Record<string, PositionalConfig>;
 export type Configuration = Plugin.Configuration & {
+    /**
+     * Preamble description paragraph(s) to Positionals usage section
+     *
+     * This may provide a clearer way of explaining positional arguments than
+     * listing them like options.
+     */
+    description?: string | string[];
     /** Minimum number of accepted positional arguments */
     min?: number;
     /** Maximum number of accepted positional arguments */
@@ -17,7 +29,7 @@ export type Configuration = Plugin.Configuration & {
 export declare const name = "positionals";
 /** @deprecated Do not use, included for backwards compatibility */
 export declare function requirePositionalsIsDeprecatedAndShouldNotBeUsed(positionals: Configuration, arg?: boolean | number): number;
-export declare function configure(config?: Configuration): void;
+export declare function configure(proposal?: Configuration): void;
 export declare function require(positionalConfigSet: PositionalConfigSet): void;
 export declare function minimumArgCount(): number;
 export declare function requireAtLeast(minimumArgs: number): void;
@@ -41,6 +53,7 @@ export declare function maximumUnnamedCount(): number | undefined;
  * @param maxUnnamed Number of optional args to allow
  */
 export declare function requireNoMoreThanUnnamedArgs(maxUnnamed: number): void;
+export declare function options(): Plugin.Options;
 export declare function init(args: Plugin.ExpectedArguments<() => Plugin.Options>): void;
 export declare function usageArgs(): string;
 export declare function usage(usage: string, isMarkdown?: boolean): string;

package/dist/Positionals.js

@@ -1,9 +1,7 @@
-import * as Colors from '@qui-cli/colors/dist/Colors.js';
-import * as Plugin from '@qui-cli/plugin';
+import { Colors } from '@qui-cli/colors';
 import wrapAnsi from 'wrap-ansi';
 export const name = 'positionals';
-let min = 0;
-let max = undefined;
+const config = { min: 0 };
 const configSet = {};
 let positionals = [];
 /** @deprecated Do not use, included for backwards compatibility */
@@ -19,13 +17,17 @@ export function requirePositionalsIsDeprecatedAndShouldNotBeUsed(positionals, ar
             requireAtLeast(1);
         }
     }
-    return min;
+    return config.min;
 }
-export function configure(config = {}) {
-    requireAtLeast(Plugin.hydrate(config.min, min));
-    const m = Plugin.hydrate(config.max, max);
-    if (m !== undefined) {
-        requireNoMoreThan(m);
+export function configure(proposal = {}) {
+    for (const key in proposal) {
+        if (proposal[key] !== undefined) {
+            config[key] = proposal[key];
+        }
+    }
+    requireAtLeast(config.min);
+    if (config.max !== undefined) {
+        requireNoMoreThan(config.max);
     }
 }
 export function require(positionalConfigSet) {
@@ -36,9 +38,9 @@ export function require(positionalConfigSet) {
         }
         configSet[name] = positionalConfigSet[name];
     }
-    min += names.length;
-    if (max !== undefined) {
-        max += names.length;
+    config.min += names.length;
+    if (config.max !== undefined) {
+        config.max += names.length;
     }
 }
 function names() {
@@ -48,36 +50,36 @@ function namedCount() {
     return names().length;
 }
 export function minimumArgCount() {
-    return min;
+    return config.min;
 }
 export function requireAtLeast(minimumArgs) {
     if (minimumArgs < 0) {
         throw new Error(`Cannot require fewer than 0 positional args.`);
     }
-    if (max !== undefined && minimumArgs > max) {
-        throw new Error(`Cannot require min ${minimumArgs} positional args, maximum ${max} required positional args are configured.`);
+    if (config.max !== undefined && minimumArgs > config.max) {
+        throw new Error(`Cannot require min ${minimumArgs} positional args, maximum ${config.max} required positional args are configured.`);
     }
-    min = minimumArgs;
+    config.min = minimumArgs;
 }
 export function maximumArgCount() {
-    return max;
+    return config.max;
 }
 export function requireNoMoreThan(maximumArgs) {
-    if (maximumArgs >= min && maximumArgs >= namedCount()) {
-        max = maximumArgs;
+    if (maximumArgs >= (config.min || 0) && maximumArgs >= namedCount()) {
+        config.max = maximumArgs;
     }
     else {
-        throw new Error(`Cannot require max ${max} positional args, minimum ${namedCount()} required positional args are configured.`);
+        throw new Error(`Cannot require max ${config.max} positional args, minimum ${namedCount()} required positional args are configured.`);
     }
 }
 export function allowOptionalArgs() {
-    max = undefined;
+    config.max = undefined;
 }
 export function allowOnlyNamedArgs() {
-    requireNoMoreThan(min);
+    requireNoMoreThan(config.min);
 }
 export function minimumUnnamedArgCount() {
-    return Math.max(0, min - namedCount());
+    return Math.max(0, config.min - namedCount());
 }
 /**
  * Caution: this should not be set within plugins due to potential confusion and
@@ -86,13 +88,13 @@ export function minimumUnnamedArgCount() {
  * @param minUnnamed Number of optional args to allow
  */
 export function requireAtLeastUnnamedArgs(minUnnamed) {
-    if (max && min + minUnnamed > max) {
-        throw new Error(`Cannot require min ${minUnnamed} unnamed positional args, maximum ${max - namedCount()} unnamed positioal args are configure.`);
+    if (config.max && config.min + minUnnamed > config.max) {
+        throw new Error(`Cannot require min ${minUnnamed} unnamed positional args, maximum ${config.max - namedCount()} unnamed positioal args are configure.`);
     }
-    requireAtLeast(min + minUnnamed);
+    requireAtLeast(config.min + minUnnamed);
 }
 export function maximumUnnamedCount() {
-    return max ? max - namedCount() : undefined;
+    return config.max ? config.max - namedCount() : undefined;
 }
 /**
  * Caution: this should not be set within plugins due to potential confusion and
@@ -104,11 +106,39 @@ export function requireNoMoreThanUnnamedArgs(maxUnnamed) {
     if (maxUnnamed < 0) {
         throw new Error(`Cannot require a negative number of unnamed positional args.`);
     }
-    if (maxUnnamed < min - namedCount()) {
-        throw new Error(`Cannot require max ${maxUnnamed} unnamed positional args, minimum ${min - namedCount()} unnamed positional args are configured.`);
+    if (maxUnnamed < config.min - namedCount()) {
+        throw new Error(`Cannot require max ${maxUnnamed} unnamed positional args, minimum ${config.min - namedCount()} unnamed positional args are configured.`);
     }
     requireNoMoreThan(namedCount() + maxUnnamed);
 }
+export function options() {
+    const man = [];
+    if (config.description) {
+        if (Array.isArray(config.description)) {
+            man.push(...config.description.map((text) => ({ text })));
+        }
+        else {
+            man.push({ text: config.description });
+        }
+    }
+    for (const arg in configSet) {
+        if (configSet[arg].description || configSet[arg].hint)
+            man.push({
+                level: 2,
+                text: Colors.positionalArg(arg)
+            });
+        if (configSet[arg].description) {
+            man.push({ text: configSet[arg].description });
+        }
+        if (configSet[arg].hint) {
+            man.push({ text: configSet[arg].hint });
+        }
+    }
+    if (man.length > 0) {
+        man.unshift({ level: 1, text: 'Positional arguments' });
+    }
+    return { man };
+}
 export function init(args) {
     positionals = [...args.positionals];
 }
@@ -133,15 +163,15 @@ function ellipsis(args, start, end) {
 }
 export function usageArgs() {
     let args = names();
-    args = unnamed(args, (max || min) - namedCount());
-    if (!max) {
+    args = unnamed(args, (config.max || config.min) - namedCount());
+    if (!config.max) {
         args.push('...');
     }
-    args = optional(args, min);
-    if (max) {
-        args = ellipsis(args, min, args.length);
+    args = optional(args, config.min);
+    if (config.max) {
+        args = ellipsis(args, config.min, args.length);
     }
-    args = ellipsis(args, namedCount(), min);
+    args = ellipsis(args, namedCount(), config.min);
     return args.map((arg) => Colors.positionalArg(arg)).join(' ');
 }
 function wrap(text, indent) {
@@ -171,11 +201,11 @@ export function usage(usage, isMarkdown = false) {
 }
 export function run() {
     const s = positionals.length !== 1 ? 's' : '';
-    if (positionals.length < min) {
-        throw new Error(`Expected at least ${min} positional arguments, received ${positionals.length} positional argument${s}.`);
+    if (positionals.length < config.min) {
+        throw new Error(`Expected at least ${config.min} positional arguments, received ${positionals.length} positional argument${s}.`);
     }
-    if (max !== undefined && positionals.length > max) {
-        throw new Error(`Expected no more than ${max} positional arguments, received ${positionals.length} positional argument${s}.`);
+    if (config.max !== undefined && positionals.length > config.max) {
+        throw new Error(`Expected no more than ${config.max} positional arguments, received ${positionals.length} positional argument${s}.`);
     }
     names().forEach((name, i) => {
         if (configSet[name].validate) {

package/dist/index.js

@@ -2,8 +2,8 @@ import { register } from '@qui-cli/plugin';
 import * as Help from './Help.js';
 import * as JackSpeak from './JackSpeak.js';
 import * as Positionals from './Positionals.js';
+export * as Core from './Core.js';
+export { Help, JackSpeak, Positionals };
 await register(Help);
 await register(JackSpeak);
 await register(Positionals);
-export * as Core from './Core.js';
-export { Help, JackSpeak, Positionals };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@qui-cli/core",
-  "version": "6.0.1",
+  "version": "6.0.3",
   "description": "Core features of @qui-cli/qui-cli",
   "homepage": "https://github.com/battis/qui-cli/tree/main/packages/core#readme",
   "repository": {