feat!: core Usage plugin generates usage for stdout and Markdown

BREAKING CHANGE: Core no longer exports usage() or usageMarkdown() (they
are exported from the Usage plugin in the core module).

Author: battis

examples/dev-readme/README.md

@@ -8,10 +8,10 @@ Demonstrate using `@qui-cli/markdown` to generate a README
 - Call `Positionals.requireNoMoreThan(0)` immediately before `Core.init()` to override any required positionals from the imported command.
 - Note that the command name in the documentation is set by the name of the script that invokes `@qui-cli/markdown` (`./scripts/dev-readme` → `dev-readme`)
 
-## Usage:
-
-```bash
-  dev-readme -hA --z=<buzz> --bargle --commands --silent --logging --baz=<baz> --biz=<biz> --pi=<pi> --a=<a> --opAccount=<example.1password.com> --opItem=<1Password unique identifier> --opToken=<token value> --logFilePath=<logFilePath> --stdoutLevel=<all|trace|debug|info|warning|error|fatal|off> --fileLevel=<all|trace|debug|info|warning|error|fatal|off> `foo` `bar`
+Usage:
+  `foo` `bar`
+```
+dev-readme -hA --z=<buzz> --bargle --commands --silent --logging --baz=<baz> --biz=<biz> --pi=<pi> --a=<a> --opAccount=<example.1password.com> --opItem=<1Password unique identifier> --opToken=<token value> --logFilePath=<logFilePath> --stdoutLevel=<all|trace|debug|info|warning|error|fatal|off> --fileLevel=<all|trace|debug|info|warning|error|fatal|off>
 ```
 
 ## Arguments

packages/core/package.json

@@ -14,6 +14,9 @@
     "url": "https://github.com/battis"
   },
   "type": "module",
+  "imports": {
+    "#plugins": "./dist/Plugins/index.js"
+  },
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
   "scripts": {

packages/core/src/Core.ts

@@ -1,11 +1,8 @@
+import { Help, JackSpeak, Positionals } from '#plugins';
 import * as Plugin from '@qui-cli/plugin';
 import { Base } from '@qui-cli/plugin/dist/Plugin.js';
-import * as Help from './Help.js';
-import * as JackSpeak from './JackSpeak.js';
-import * as Positionals from './Positionals.js';
 
 export { Options } from '@qui-cli/plugin';
-export * from './Usage.js';
 
 /** Core configuration options */
 export type Configuration = Plugin.Registrar.Configuration & {

packages/core/src/Help.ts packages/core/src/Plugins/Help.tspackages/core/src/Help.ts renamed to packages/core/src/Plugins/Help.ts

@@ -1,5 +1,4 @@
 import * as Plugin from '@qui-cli/plugin';
-import * as Core from './Core.js';
 
 export type Configuration = Plugin.Configuration & {
   /** Get usage information */
@@ -27,8 +26,8 @@ export function options(): Plugin.Options {
 
 export function init({ values }: Plugin.ExpectedArguments<typeof options>) {
   configure(values);
-  if (help) {
-    process.stdout.write(Core.usage());
-    process.exit(0);
-  }
+}
+
+export function run() {
+  return true;
 }

packages/core/src/JackSpeak.ts packages/core/src/Plugins/JackSpeak.tspackages/core/src/JackSpeak.ts renamed to packages/core/src/Plugins/JackSpeak.ts

@@ -277,28 +277,30 @@ export function usage(usage: string, isMarkdown = false): string {
   )}${post}`;
 }
 
-export function run() {
-  const s = positionals.length !== 1 ? 's' : '';
-  if (positionals.length < config.min) {
-    throw new Error(
-      `Expected at least ${config.min} 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) {
-      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 run({ 'core.help': help }: Plugin.AccumulatedResults = {}) {
+  if (!help) {
+    const s = positionals.length !== 1 ? 's' : '';
+    if (positionals.length < config.min) {
+      throw new Error(
+        `Expected at least ${config.min} 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) {
+        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: string) {

packages/core/src/Positionals.ts packages/core/src/Plugins/Positionals.tspackages/core/src/Positionals.ts renamed to packages/core/src/Plugins/Positionals.ts

@@ -1,6 +1,8 @@
+import { JackSpeak, Positionals } from '#plugins';
 import * as Colors from '@qui-cli/colors/dist/Colors.js';
-import * as JackSpeak from './JackSpeak.js';
-import * as Positionals from './Positionals.js';
+import * as Plugin from '@qui-cli/plugin';
+
+export const name = 'core.usage';
 
 function commandColor(usage: string) {
   const pre = usage.slice(0, usage.indexOf('\n  ') + 3);
@@ -18,5 +20,12 @@ export function usage() {
 }
 
 export function usageMarkdown() {
-  return Positionals.usage(JackSpeak.usageMarkdown(), true);
+  return Positionals.usage(JackSpeak.usageMarkdown());
+}
+
+export function run({ 'core.help': help }: Plugin.AccumulatedResults = {}) {
+  if (help) {
+    process.stdout.write(usage());
+    process.exit(0);
+  }
 }

packages/core/src/Usage.ts packages/core/src/Plugins/Usage.tspackages/core/src/Usage.ts renamed to packages/core/src/Plugins/Usage.ts

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

packages/core/src/Plugins/index.ts

@@ -1,11 +1,2 @@
-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 * from '#plugins';
 export * as Core from './Core.js';
-export { Help, JackSpeak, Positionals };
-
-await register(Help);
-await register(JackSpeak);
-await register(Positionals);

packages/core/src/index.ts

@@ -1,5 +1,5 @@
 import { Colors } from '@qui-cli/colors';
-import { Core } from '@qui-cli/core';
+import { Usage } from '@qui-cli/core';
 import * as Plugin from '@qui-cli/plugin';
 import { Root } from '@qui-cli/root';
 import fs from 'node:fs';
@@ -122,7 +122,7 @@ export async function run() {
   fs.writeFileSync(
     config.outputPath,
     `${config.pre.length ? `${config.pre}\n` : ''}${adjustHeadingLevel(
-      stripAnsi(restyle(Core.usageMarkdown()))
+      stripAnsi(restyle(Usage.usageMarkdown()))
     )
       .replace('Usage:\n\n```', '## Usage:\n\n```bash')
       .replace(