@thi.ng/args 2.4.0 → 2.6.0

package/CHANGELOG.md

@@ -1,6 +1,6 @@
 # Change Log
 
-- **Last updated**: 2025-06-27T11:09:55Z
+- **Last updated**: 2025-06-28T06:35:49Z
 - **Generator**: [thi.ng/monopub](https://thi.ng/monopub)
 
 All notable changes to this project will be documented in this file.
@@ -11,6 +11,22 @@ See [Conventional Commits](https://conventionalcommits.org/) for commit guidelin
 **Note:** Unlisted _patch_ versions only involve non-code or otherwise excluded changes
 and/or version bumps of transitive dependencies.
 
+## [2.6.0](https://github.com/thi-ng/umbrella/tree/@thi.ng/args@2.6.0) (2025-06-28)
+
+#### 🚀 Features
+
+- emit colorized error messages in cliApp() ([36f66b6](https://github.com/thi-ng/umbrella/commit/36f66b6))
+
+## [2.5.0](https://github.com/thi-ng/umbrella/tree/@thi.ng/args@2.5.0) (2025-06-27)
+
+#### 🚀 Features
+
+- update ColorTheme, add color support for cmd list ([75b1ef1](https://github.com/thi-ng/umbrella/commit/75b1ef1))
+  - add `ColorTheme.command` option
+  - migrate internal formatting helpers to own file
+  - refactor cliApp() & usage() internals
+- add thi.ng logo header tpl ([838e417](https://github.com/thi-ng/umbrella/commit/838e417))
+
 ## [2.4.0](https://github.com/thi-ng/umbrella/tree/@thi.ng/args@2.4.0) (2025-06-27)
 
 #### 🚀 Features

package/api.d.ts

@@ -164,6 +164,7 @@ export interface UsageOpts {
  */
 export interface ColorTheme {
     default: number;
+    command: number;
     hint: number;
     multi: number;
     param: number;

package/api.js

@@ -1,5 +1,6 @@
 const DEFAULT_THEME = {
   default: 95,
+  command: 92,
   hint: 90,
   multi: 90,
   param: 96,

package/cli.js

@@ -1,12 +1,18 @@
 import { illegalArgs } from "@thi.ng/errors/illegal-arguments";
 import { StreamLogger } from "@thi.ng/logger/stream";
-import { padRight } from "@thi.ng/strings/pad-right";
 import { PRESET_ANSI16, PRESET_NONE } from "@thi.ng/text-format/presets";
 import { parse } from "./parse.js";
-import { __wrapWithIndent, usage } from "./usage.js";
+import { usage } from "./usage.js";
+import {
+  __ansi,
+  __colorTheme,
+  __padRightAnsi,
+  __wrapWithIndent
+} from "./utils.js";
 const cliApp = async (config) => {
   const argv = config.argv || process.argv;
   const isColor = !process.env.NO_COLOR;
+  const format = isColor ? PRESET_ANSI16 : PRESET_NONE;
   const usageOpts = {
     prefix: "",
     color: isColor,
@@ -23,26 +29,28 @@ const cliApp = async (config) => {
     } else {
       cmdID = argv[start];
       cmd = config.commands[cmdID];
-      usageOpts.prefix += __descriptions(
-        config.commands,
-        config.usage.lineWidth
-      );
-      if (!cmd) __usageAndExit(config, usageOpts);
+      if (!cmd) {
+        usageOpts.prefix += __descriptions(config.commands, usageOpts);
+        __usageAndExit(config, usageOpts);
+      }
       start++;
     }
     let parsed;
     try {
       parsed = parse({ ...config.opts, ...cmd.opts }, argv, {
-        showUsage: true,
+        showUsage: false,
         usageOpts,
         start
       });
-    } catch (_) {
+    } catch (e) {
+      __printError(e.message, format);
+    }
+    if (!parsed) {
+      __usageAndExit(config, usageOpts);
+      process.exit(1);
     }
-    if (!parsed) process.exit(1);
     if (cmd.inputs !== void 0 && cmd.inputs !== parsed.rest.length) {
-      process.stderr.write(`expected ${cmd.inputs || 0} input(s)
-`);
+      __printError(`expected ${cmd.inputs || 0} input(s)`, format);
       __usageAndExit(config, usageOpts);
     }
     const ctx = await config.ctx(
@@ -57,7 +65,7 @@ const cliApp = async (config) => {
     await cmd.fn(ctx);
     if (config.post) await config.post(ctx, cmd);
   } catch (e) {
-    process.stderr.write(e.message + "\n\n");
+    __printError(e.message, format);
     process.exit(1);
   }
 };
@@ -65,13 +73,17 @@ const __usageAndExit = (config, usageOpts) => {
   process.stderr.write(usage(config.opts, usageOpts));
   process.exit(1);
 };
-const __descriptions = (commands, lineWidth = 80) => {
+const __descriptions = (commands, { color, lineWidth = 80 } = {}) => {
   const names = Object.keys(commands);
   const maxLength = Math.max(...names.map((x) => x.length));
+  const theme = __colorTheme(color);
   return [
     "\nAvailable commands:\n",
     ...names.map(
-      (x) => `${padRight(maxLength)(x)} : ${__wrapWithIndent(
+      (x) => `${__padRightAnsi(
+        __ansi(x, theme.command),
+        maxLength
+      )} : ${__wrapWithIndent(
         commands[x].desc,
         maxLength + 3,
         lineWidth
@@ -80,6 +92,7 @@ const __descriptions = (commands, lineWidth = 80) => {
     "\n"
   ].join("\n");
 };
+const __printError = (msg, fmt) => process.stderr.write(fmt.red(msg) + "\n\n");
 export {
   cliApp
 };

package/header.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Re-usable logo header for various thi.ng CLI tools.
+ *
+ * @param name
+ * @param version
+ * @param desc
+ *
+ * @internal
+ */
+export declare const THING_HEADER: (name: string, version: string, desc: string) => string;
+//# sourceMappingURL=header.d.ts.map

package/header.js

@@ -0,0 +1,10 @@
+const THING_HEADER = (name, version, desc) => `
+ \u2588 \u2588   \u2588           \u2502
+\u2588\u2588 \u2588               \u2502
+ \u2588 \u2588 \u2588 \u2588   \u2588 \u2588 \u2588 \u2588 \u2502 ${name} v${version}
+ \u2588 \u2588 \u2588 \u2588 \u2588 \u2588 \u2588 \u2588 \u2588 \u2502 ${desc}
+                 \u2588 \u2502
+               \u2588 \u2588 \u2502`;
+export {
+  THING_HEADER
+};

package/index.d.ts

@@ -2,6 +2,7 @@ export * from "./api.js";
 export * from "./args.js";
 export * from "./cli.js";
 export * from "./coerce.js";
+export * from "./header.js";
 export * from "./parse.js";
 export * from "./usage.js";
 //# sourceMappingURL=index.d.ts.map

package/index.js

@@ -2,5 +2,6 @@ export * from "./api.js";
 export * from "./args.js";
 export * from "./cli.js";
 export * from "./coerce.js";
+export * from "./header.js";
 export * from "./parse.js";
 export * from "./usage.js";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@thi.ng/args",
-  "version": "2.4.0",
+  "version": "2.6.0",
   "description": "Declarative, functional CLI argument/options parser, value coercions, sub-commands etc.",
   "type": "module",
   "module": "./index.js",
@@ -96,6 +96,9 @@
     "./coerce": {
       "default": "./coerce.js"
     },
+    "./header": {
+      "default": "./header.js"
+    },
     "./parse": {
       "default": "./parse.js"
     },
@@ -107,5 +110,5 @@
     "tag": "cli",
     "year": 2018
   },
-  "gitHead": "7fa97c11435e6f616bac62b731050784694ee08d\n"
+  "gitHead": "42ee16fdd391d5e04daeae9817f6c7dc378e371e\n"
 }

package/usage.d.ts

@@ -1,6 +1,4 @@
 import type { IObjectOf } from "@thi.ng/api";
 import { type Args, type UsageOpts } from "./api.js";
 export declare const usage: <T extends IObjectOf<any>>(specs: Args<T>, opts?: Partial<UsageOpts>) => string;
-/** @internal */
-export declare const __wrapWithIndent: (body: string, indent: number, width: number) => string;
 //# sourceMappingURL=usage.d.ts.map

package/usage.js

@@ -1,13 +1,14 @@
-import { isPlainObject } from "@thi.ng/checks/is-plain-object";
-import { lengthAnsi } from "@thi.ng/strings/ansi";
 import { capitalize, kebab } from "@thi.ng/strings/case";
-import { padRight } from "@thi.ng/strings/pad-right";
-import { repeat } from "@thi.ng/strings/repeat";
 import { stringify } from "@thi.ng/strings/stringify";
-import { SPLIT_ANSI, wordWrapLines } from "@thi.ng/strings/word-wrap";
 import {
-  DEFAULT_THEME
 } from "./api.js";
+import {
+  __ansi,
+  __colorTheme,
+  __padRightAnsi,
+  __wrap,
+  __wrapWithIndent
+} from "./utils.js";
 const usage = (specs, opts = {}) => {
   opts = {
     lineWidth: 80,
@@ -18,7 +19,7 @@ const usage = (specs, opts = {}) => {
     groups: ["flags", "main"],
     ...opts
   };
-  const theme = isPlainObject(opts.color) ? { ...DEFAULT_THEME, ...opts.color } : opts.color ? DEFAULT_THEME : {};
+  const theme = __colorTheme(opts.color);
   const format = (ids) => ids.map(
     (id) => __argUsage(id, specs[id], opts, theme, opts.paramWidth)
   );
@@ -52,7 +53,7 @@ const __argUsage = (id, spec, opts, theme, indent) => {
   isRequired && prefixes.push("required");
   spec.multi && prefixes.push("multiple");
   const body = __argPrefix(prefixes, theme, isRequired) + (spec.desc || "") + __argDefault(spec, opts, theme);
-  return padRight(opts.paramWidth)(params, lengthAnsi(params)) + __wrapWithIndent(body, indent, opts.lineWidth);
+  return __padRightAnsi(params, opts.paramWidth) + __wrapWithIndent(body, indent, opts.lineWidth);
 };
 const __argHint = (spec, theme) => spec.hint ? __ansi(" " + spec.hint, theme.hint) : "";
 const __argAlias = (spec, theme, hint) => spec.alias ? `${__ansi("-" + spec.alias, theme.param)}${hint}, ` : "";
@@ -66,17 +67,6 @@ const __argDefault = (spec, opts, theme) => opts.showDefaults && spec.default !=
   )})`,
   theme.default
 ) : "";
-const __ansi = (x, col) => col != null ? `\x1B[${col}m${x}\x1B[0m` : x;
-const __wrap = (str, width) => str ? wordWrapLines(str, {
-  width,
-  splitter: SPLIT_ANSI,
-  hard: false
-}) : [];
-const __wrapWithIndent = (body, indent, width) => {
-  const prefix = repeat(" ", indent);
-  return __wrap(body, width - indent).map((l, i) => i ? prefix + l : l).join("\n");
-};
 export {
-  __wrapWithIndent,
   usage
 };

package/utils.d.ts

@@ -0,0 +1,13 @@
+import type { Maybe } from "@thi.ng/api";
+import { type ColorTheme } from "./api.js";
+/** @internal */
+export declare const __ansi: (x: string, col: number) => string;
+/** @internal */
+export declare const __padRightAnsi: (x: string, width: number) => string;
+/** @internal */
+export declare const __wrap: (str: Maybe<string>, width: number) => import("@thi.ng/strings/word-wrap").Line[];
+/** @internal */
+export declare const __wrapWithIndent: (body: string, indent: number, width: number) => string;
+/** @internal */
+export declare const __colorTheme: (color?: boolean | Partial<ColorTheme>) => ColorTheme;
+//# sourceMappingURL=utils.d.ts.map

package/utils.js

@@ -0,0 +1,25 @@
+import { isPlainObject } from "@thi.ng/checks/is-plain-object";
+import { repeat } from "@thi.ng/strings/repeat";
+import { SPLIT_ANSI, wordWrapLines } from "@thi.ng/strings/word-wrap";
+import { DEFAULT_THEME } from "./api.js";
+import { lengthAnsi } from "@thi.ng/strings/ansi";
+import { padRight } from "@thi.ng/strings/pad-right";
+const __ansi = (x, col) => col != null ? `\x1B[${col}m${x}\x1B[0m` : x;
+const __padRightAnsi = (x, width) => padRight(width)(x, lengthAnsi(x));
+const __wrap = (str, width) => str ? wordWrapLines(str, {
+  width,
+  splitter: SPLIT_ANSI,
+  hard: false
+}) : [];
+const __wrapWithIndent = (body, indent, width) => {
+  const prefix = repeat(" ", indent);
+  return __wrap(body, width - indent).map((l, i) => i ? prefix + l : l).join("\n");
+};
+const __colorTheme = (color) => isPlainObject(color) ? { ...DEFAULT_THEME, ...color } : color ? DEFAULT_THEME : {};
+export {
+  __ansi,
+  __colorTheme,
+  __padRightAnsi,
+  __wrap,
+  __wrapWithIndent
+};