@qui-cli/core 4.0.0

package/README.md

@@ -0,0 +1,130 @@
+# @qui-cli/core
+
+Core features of @qui-cli/qui-cli
+
+[![npm version](https://badge.fury.io/js/@qui-cli%2Fcore.svg)](https://npmjs.com/package/@qui-cli/core)
+[![Module type: ESM](https://img.shields.io/badge/module%20type-esm-brightgreen)](https://nodejs.org/api/esm.html)
+
+## Install
+
+```sh
+npm install @qui-cli/core
+```
+
+## Usage
+
+```ts
+import { Core } from '@qui-cli/core';
+import { Colors } from '@qui-cli/colors';
+import { Log } from '@qui-cli/log';
+
+// register custom arguments
+await Core.init({
+  opt: {
+    foo: {
+      description: 'bar'
+    }
+  }
+});
+
+// process user-provided command-line arguments
+const { values, positionals } = await Core.run();
+
+// use Log and Colors
+Log.debug(values.foo);
+Log.debug(positionals.length);
+Log.info(
+  `This is a ${Colors.value('value')} and a ${Colors.quotedValue('"quoted value"')}.`
+);
+```
+
+See [examples](https://github.com/battis/qui-cli/tree/main/examples#readme) for common use cases.
+
+## Core Plugins
+
+Three core plugins are registered automatically to provide consistent functionality.
+
+### `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()`:
+
+```ts
+await Core.configure({
+  jackspeak: {
+    envPrefix: 'MY_APP'
+  }
+});
+```
+
+### `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.
+
+```ts
+import { Core, Positionals } from '@qui-cli/core';
+
+Positionals.require({
+  my_number: {
+    description: 'How far left to move',
+    validate: (v?: string) => !isNaN(v) || 'my_number must be a numeric value'
+  }
+});
+
+await Core.run();
+
+console.log(Positionals.get('my_number'));
+```
+
+Positional arguments are processed in the order in which plugins are registered. Thus, if plugin A requires positional arguments `a1` and `a2`, plugn B requires positional arguments `b1` and `b2` and depends on plugin C which requires positional argument `c1`, the resulting positional argument order would be: `a1 a2 c1 b1 b2`.
+
+Unnamed arguments can also be required, however this is a dicey proposition to implement within a plugin and is likely best reserved for independent apps that consume plugins, as the `min` and `max` number of positional arguments check against the currently registered list of required named positonal arguments for validity (as well as their own respective values). In general, configuring unnamed positional arguments is best done before any required named positional arguments are defined.
+
+```ts
+// require at least 2 and no more than 5 unnamed positionals:
+//   arg0 arg1 [arg2 arg3 arg4]
+Positionals.configure({ min: 2, max: 5 });
+
+//.  nemo arg0 arg1 [arg2 arg3 arg4]
+Positionals.require({ nemo: { description: 'I have a name!' } });
+
+// fails: nemo is required, must be at least 1
+Positionals.setMinArg(0);
+
+// succeeds
+Positionals.setMinArg(6);
+
+// fails: is less than current min
+Positionals.setMaxArg(4);
+```
+
+### `help`
+
+Provides consistent `--help` (`-h`) flag for all commands that displays usage. No confiuration.
+
+## Configuration: `configure(config?: Configuration): void`
+
+Programmatic configuration to set defaults before generating user-facing usage documentation or processing user-provided command line arguments.
+
+Invoking `Core.configure()` triggers the `configure()` hook for all registered plugins.
+
+Refer to [@qui-cli/plugin](https://www.npmjs.com/package/@qui-cli/plugin#user-content-configuration) for further details on plugin configuration.
+
+## Options: `options(): Options`
+
+Generate command-line options for jackspeak initialization and user-facing usage documentation.
+
+Invoking `Core.options()` merges the `options()` hooks of all registered plugins.
+
+Refer to [@qui-cli/plugin](https://www.npmjs.com/package/@qui-cli/plugin#user-content-options) for further details on plugin options.
+
+The `--help` (`-h`) flag is appended to output user-readable usage information to the command-line.
+
+## Initialization: `init(options?: Options): Arguments`
+
+Initialize the app with user-provided command-line arguments, processed based on the result of `options()`, returning the [processed user-provided command-line arguments from jackspeak](https://www.npmjs.com/package/jackspeak#user-content-jackparseargs-string--processargv--positionals-string-values-optionsresults-).
+
+Invoking `Core.init()` also initializes the `init()` hook for all registered plugins.
+
+Refer to [@qui-cli/plugin](https://www.npmjs.com/package/@qui-cli/plugin#user-content-initialization) for further details on plugin initialization.
+
+Additional app-specific command-line options can be provided with an `Options` object as described in [@qui-cli/plugin](https://www.npmjs.com/package/@qui-cli/plugin#user-content-options).

package/dist/Core.d.ts

@@ -0,0 +1,15 @@
+import * as Plugin from '@qui-cli/plugin';
+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 */
+    core?: JackSpeak.Configuration & {
+        /** @deprecated Use `Positional` 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

@@ -0,0 +1,58 @@
+import * as Colors from '@qui-cli/colors/dist/Colors.js';
+import * as Plugin from '@qui-cli/plugin';
+import * as JackSpeak from './JackSpeak.js';
+import * as Positionals from './Positionals.js';
+import { usage } from './Usage.js';
+export * from './Usage.js';
+let initialized = false;
+export async function configure(config = {}) {
+    const { core = {}, jackspeak: jackOptions, positionals = {} } = config;
+    const { requirePositionals, ...deprecated } = core;
+    const jackspeak = {
+        ...deprecated,
+        allowPositionals: !!Positionals.requirePositionalsIsDeprecatedAndShouldNotBeUsed(positionals, requirePositionals),
+        ...jackOptions
+    };
+    if (jackspeak.allowPositionals === false) {
+        positionals.max = 0;
+    }
+    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.`);
+    }
+    for (const plugin of Plugin.Registrar.registered()) {
+        if (plugin.options) {
+            JackSpeak.args(await plugin.options());
+        }
+    }
+    if (externalOptions) {
+        JackSpeak.args(externalOptions);
+    }
+    const args = JackSpeak.parse();
+    await Plugin.Registrar.init(args);
+    initialized = true;
+    return args;
+}
+export async function run(externalOptions) {
+    try {
+        if (!initialized) {
+            await init(externalOptions);
+        }
+        return await Plugin.Registrar.run();
+    }
+    catch (e) {
+        const error = e;
+        console.log(`${Colors.error(error.message)}\n\n${usage()}`);
+        process.exit(1);
+    }
+}

package/dist/Help.d.ts

@@ -0,0 +1,9 @@
+import * as Plugin from '@qui-cli/plugin';
+export type Configuration = Plugin.Configuration & {
+    help?: boolean;
+};
+export declare const name = "core.help";
+export declare function configure(config?: Configuration): void;
+export declare function options(): Plugin.Options;
+export declare function init({ values }: Plugin.ExpectedArguments<typeof options>): void;
+export declare function run(): void;

package/dist/Help.js

@@ -0,0 +1,26 @@
+import * as Plugin from '@qui-cli/plugin';
+import * as Core from './Core.js';
+export const name = 'core.help';
+let help = false;
+export function configure(config = {}) {
+    help = Plugin.hydrate(config.help, help);
+}
+export function options() {
+    return {
+        flag: {
+            help: {
+                description: 'Get usage information',
+                short: 'h'
+            }
+        }
+    };
+}
+export function init({ values }) {
+    configure(values);
+}
+export function run() {
+    if (help) {
+        console.log(Core.usage());
+        process.exit(0);
+    }
+}

package/dist/JackSpeak.d.ts

@@ -0,0 +1,9 @@
+import * as Plugin from '@qui-cli/plugin';
+import { Jack, JackOptions } from 'jackspeak';
+export type Configuration = Plugin.Configuration & JackOptions;
+export declare const name = "jackspeak";
+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 usage(): string;

package/dist/JackSpeak.js

@@ -0,0 +1,44 @@
+import { Jack } from 'jackspeak';
+export const name = 'jackspeak';
+let instance = undefined;
+export function jack() {
+    if (!instance) {
+        configure();
+    }
+    if (!instance) {
+        throw new Error(`JackSpeak configuration failed.`);
+    }
+    return instance;
+}
+export function configure(config = {}) {
+    instance = new Jack(config);
+}
+export function args(options) {
+    for (const key in options) {
+        if (key === 'man') {
+            for (const paragraph of options[key]) {
+                if (paragraph.level) {
+                    jack().heading(paragraph.text, paragraph.level, {
+                        pre: paragraph.pre
+                    });
+                }
+                else {
+                    jack().description(paragraph.text, { pre: paragraph.pre });
+                }
+            }
+        }
+        else if (key === 'fields') {
+            jack().addFields({ ...options[key] });
+        }
+        else {
+            // @ts-expect-error 7053 typing is hard
+            jack()[key]({ ...options[key] });
+        }
+    }
+}
+export function parse() {
+    return jack().parse();
+}
+export function usage() {
+    return jack().usage();
+}

package/dist/Positionals.d.ts

@@ -0,0 +1,47 @@
+import * as Plugin from '@qui-cli/plugin';
+type PositionalConfig = {
+    description?: string;
+    hint?: string;
+    validate?: (v?: string) => boolean | string;
+};
+type PositionalConfigSet = Record<string, PositionalConfig>;
+export type Configuration = Plugin.Configuration & {
+    min?: number;
+    max?: number;
+};
+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 require(positionalConfigSet: PositionalConfigSet): void;
+export declare function minimumArgCount(): number;
+export declare function requireAtLeast(minimumArgs: number): void;
+export declare function maximumArgCount(): number | undefined;
+export declare function requireNoMoreThan(maximumArgs: number): void;
+export declare function allowOptionalArgs(): void;
+export declare function allowOnlyNamedArgs(): void;
+export declare function minimumUnnamedArgCount(): number;
+/**
+ * Caution: this should not be set within plugins due to potential confusion and
+ * overlap!
+ *
+ * @param minUnnamed Number of optional args to allow
+ */
+export declare function requireAtLeastUnnamedArgs(minUnnamed: number): void;
+export declare function maximumUnnamedCount(): number | undefined;
+/**
+ * Caution: this should not be set within plugins due to potential confusion and
+ * overlap!
+ *
+ * @param maxUnnamed Number of optional args to allow
+ */
+export declare function requireNoMoreThanUnnamedArgs(maxUnnamed: number): void;
+export declare function init(args: Plugin.ExpectedArguments<() => Plugin.Options>): void;
+export declare function usageArgs(): string;
+export declare function usage(usage: string): string;
+export declare function run(): void;
+export declare function get(positionalArgName: string): string | undefined;
+export declare function namedArgs(): Record<string, string | undefined>;
+export declare function unnamedArgs(): (string | undefined)[];
+export declare function unnamedArg(i: number): string | undefined;
+export {};

package/dist/Positionals.js

@@ -0,0 +1,203 @@
+import * as Colors from '@qui-cli/colors/dist/Colors.js';
+import * as Plugin from '@qui-cli/plugin';
+import wrapAnsi from 'wrap-ansi';
+export const name = 'positionals';
+let min = 0;
+let max = undefined;
+const configSet = {};
+let positionals = [];
+/** @deprecated Do not use, included for backwards compatibility */
+export function requirePositionalsIsDeprecatedAndShouldNotBeUsed(positionals, arg) {
+    if (arg !== undefined &&
+        positionals.min === undefined &&
+        positionals.max === undefined) {
+        if (typeof arg === 'number') {
+            requireAtLeast(arg);
+            requireNoMoreThan(arg);
+        }
+        else if (arg) {
+            requireAtLeast(1);
+        }
+    }
+    return 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 require(positionalConfigSet) {
+    const names = Object.keys(positionalConfigSet);
+    for (const name of names) {
+        if (name in configSet) {
+            throw new Error(`A positional argument named ${name} has already been defined and cannot be redefined.`);
+        }
+        configSet[name] = positionalConfigSet[name];
+    }
+    min += names.length;
+    if (max !== undefined) {
+        max += names.length;
+    }
+}
+function names() {
+    return Object.keys(configSet);
+}
+function namedCount() {
+    return names().length;
+}
+export function minimumArgCount() {
+    return 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.`);
+    }
+    min = minimumArgs;
+}
+export function maximumArgCount() {
+    return max;
+}
+export function requireNoMoreThan(maximumArgs) {
+    if (maximumArgs >= min && maximumArgs >= namedCount()) {
+        max = maximumArgs;
+    }
+    else {
+        throw new Error(`Cannot require max ${max} positional args, minimum ${namedCount()} required positional args are configured.`);
+    }
+}
+export function allowOptionalArgs() {
+    max = undefined;
+}
+export function allowOnlyNamedArgs() {
+    requireNoMoreThan(min);
+}
+export function minimumUnnamedArgCount() {
+    return Math.max(0, min - namedCount());
+}
+/**
+ * Caution: this should not be set within plugins due to potential confusion and
+ * overlap!
+ *
+ * @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.`);
+    }
+    requireAtLeast(min + minUnnamed);
+}
+export function maximumUnnamedCount() {
+    return max ? max - namedCount() : undefined;
+}
+/**
+ * Caution: this should not be set within plugins due to potential confusion and
+ * overlap!
+ *
+ * @param maxUnnamed Number of optional args to allow
+ */
+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.`);
+    }
+    requireNoMoreThan(namedCount() + maxUnnamed);
+}
+export function init(args) {
+    positionals = [...args.positionals];
+}
+function unnamed(args, count) {
+    for (let i = 0; i < count; i++) {
+        args.push(`arg${i}`);
+    }
+    return args;
+}
+function optional(args, required) {
+    if (required < args.length) {
+        args[required] = `[${args[required]}`;
+        args[args.length - 1] = `${args[args.length - 1]}]`;
+    }
+    return args;
+}
+function ellipsis(args, start, end) {
+    if (end - start > 3) {
+        args.splice(start + 1, end - start - 2, '...');
+    }
+    return args;
+}
+export function usageArgs() {
+    let args = names();
+    args = unnamed(args, (max || min) - namedCount());
+    if (!max) {
+        args.push('...');
+    }
+    args = optional(args, min);
+    if (max) {
+        args = ellipsis(args, min, args.length);
+    }
+    args = ellipsis(args, namedCount(), min);
+    return args.map((arg) => Colors.positionalArg(arg)).join(' ');
+}
+function wrap(text, indent) {
+    return wrapAnsi(text, process.stdout.columns - indent, { wordWrap: true })
+        .split('\n')
+        .map((line) => {
+        for (let i = 0; i < indent; i++) {
+            line = ' ' + line;
+        }
+        return line;
+    })
+        .join('\n');
+}
+export function usage(usage) {
+    const pre = usage.slice(0, usage.indexOf('\n') + 1);
+    const cmd = usage.slice(pre.length, usage.indexOf('\n\n'));
+    const post = usage.slice(pre.length + cmd.length);
+    return `${pre}${wrap(`${cmd
+        .split('\n')
+        .map((token) => token.trim())
+        .join(' ')} ${usageArgs()}`, 2)}${post}`;
+}
+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 (max !== undefined && positionals.length > max) {
+        throw new Error(`Expected no more than ${max} positional arguments, received ${positionals.length} positional argument${s}.`);
+    }
+    names().forEach((name, i) => {
+        if (configSet[name].validate) {
+            const message = configSet[name].validate(positionals[i]);
+            if (!message || typeof message === 'string') {
+                throw new Error(`Positional argument '${name}' (arg${i}) is not valid${!message ? '.' : `: ${message}`}`);
+            }
+        }
+    });
+}
+export function get(positionalArgName) {
+    const i = names().indexOf(positionalArgName);
+    if (i < 0) {
+        throw new Error(`'${positionalArgName}' is not a defined positional argument.`);
+    }
+    return positionals[i];
+}
+export function namedArgs() {
+    const args = {};
+    for (let i = 0; i < namedCount(); i++) {
+        args[names()[i]] = positionals[i];
+    }
+    return args;
+}
+export function unnamedArgs() {
+    return positionals.slice(namedCount());
+}
+export function unnamedArg(i) {
+    return unnamedArgs()[i];
+}

package/dist/Usage.d.ts

@@ -0,0 +1 @@
+export declare function usage(): string;

package/dist/Usage.js

@@ -0,0 +1,13 @@
+import * as Colors from '@qui-cli/colors/dist/Colors.js';
+import * as JackSpeak from './JackSpeak.js';
+import * as Positionals from './Positionals.js';
+function commandColor(usage) {
+    const pre = usage.slice(0, usage.indexOf('\n  ') + 3);
+    const cmd = usage.slice(pre.length, usage.indexOf(' ', pre.length));
+    const terms = usage.slice(pre.length + cmd.length, usage.indexOf('-', pre.length + cmd.length) - 1);
+    const post = usage.slice(pre.length + cmd.length + terms.length);
+    return `${pre}${Colors.command(`${Colors.keyword(cmd)}${terms}`)}${post}`;
+}
+export function usage() {
+    return Positionals.usage(commandColor(JackSpeak.usage()));
+}

package/dist/index.d.ts

@@ -0,0 +1,5 @@
+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 };

package/dist/index.js

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

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "@qui-cli/core",
+  "version": "4.0.0",
+  "description": "Core features of @qui-cli/qui-cli",
+  "homepage": "https://github.com/battis/qui-cli/tree/main/packages/core#readme",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/battis/qui-cli.git",
+    "directory": "packages/core"
+  },
+  "license": "GPL-3.0",
+  "author": {
+    "name": "Seth Battis",
+    "url": "https://github.com/battis"
+  },
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "dependencies": {
+    "jackspeak": "^4.1.1",
+    "wrap-ansi": "^9.0.0"
+  },
+  "devDependencies": {
+    "@tsconfig/node20": "^20.1.6",
+    "@types/node": "^24.1.0",
+    "commit-and-tag-version": "^12.5.2",
+    "del-cli": "^6.0.0",
+    "npm-run-all": "^4.1.5",
+    "typescript": "^5.9.2",
+    "@qui-cli/colors": "3.0.0",
+    "@qui-cli/plugin": "3.0.0"
+  },
+  "peerDependencies": {
+    "@qui-cli/colors": "2.x",
+    "@qui-cli/plugin": "^2.4"
+  },
+  "target": "node",
+  "scripts": {
+    "clean": "del ./dist",
+    "build": "run-s build:*",
+    "build:clean": "run-s clean",
+    "build:compile": "tsc",
+    "release": "commit-and-tag-version"
+  }
+}