docs: basic distributable command example

Author: battis

examples/01 Distributable Command/README.md

@@ -1,4 +1,65 @@
 # @examples/distributable-command
 
+An example of a @qui-cli command that can be distributed as an Node package
+
 [![npm version](https://badge.fury.io/js/@examples%2fdistributable-command.svg)](https://npmjs.com/package/@examples/distributable-command)
 [![Module type: ESM](https://img.shields.io/badge/module%20type-esm-brightgreen)](https://nodejs.org/api/esm.html)
+
+## Create from template
+
+This package is created using the @qui-cli/command template and making a few quick edits:
+
+```sh
+> pnpm create @qui-cli/command --scope examples "Distributable Command" --description "An example of a @qui-cli command that can be distributed as an Node package"
+```
+
+## Consistent Usage
+
+The command itself is distributed in the module's [bin](./bin/) directory (as indicated in [package.json](./package.json#L16-L18)) as Node executable. It can be invoked either by installing the package globally (and adding the global package manager's bin directory to your path, as one does) or by invoking you favorite package manager's exec function:
+
+```sh
+> pnpm exec distributable-command
+```
+
+The command is self-documenting, and its usage can be invoked with `--help` (or `-h`):
+
+```sh
+> ./bin/distributable-command -h
+Usage:
+  distributable-command -hf --t=<"argle bargle"> --number=<3.14159> --logFilePath=<logFilePath> --stdoutLevel=<all|trace|debug|info|warning|error|fatal|off>
+  --fileLevel=<all|trace|debug|info|warning|error|fatal|off> [target]
+
+Positional arguments
+
+  target
+
+    A positional text argument
+
+  -h --help  Show this usage information
+
+Command Options
+
+  -t<"argle bargle"> --text=<"argle bargle">
+             A text parameter
+
+  --number=<3.14159>
+             A numeric parameter (Default: 2.171)
+  -f --flag  A boolean parameter
+
+Logging options
+
+  --logFilePath=<logFilePath>
+             Path to log file (optional)
+
+  --stdoutLevel=<all|trace|debug|info|warning|error|fatal|off>
+             Log level to console stdout (Default: "info")
+
+  --fileLevel=<all|trace|debug|info|warning|error|fatal|off>
+             Log level to log file if --logFilePath provided (Default: "all")
+```
+
+## Easy development
+
+All of the API hooks that are defined in the [example](./src/DistributableCommand.ts) are optional (with the exception of the plugin [name](./src/DistributableCommand.ts#30-L31)). The hooks are documented in detail in the [@qui-cli/plugin](https://www.npmjs.com/package/@qui-cli/plugin) module.
+
+In combination with [@qui-cli/core](https://www.npmjs.com/package/@qui-cli/core), the plugin can be [registered an the Core invoked](./src/index.ts).

examples/01 Distributable Command/bin/distributable-command

@@ -1,3 +1,3 @@
 #!/usr/bin/env node
 
-import '../dist.index.js';
+import '../dist/index.js';

examples/01 Distributable Command/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@examples/distributable-command",
   "version": "0.0.0",
-  "description": "",
+  "description": "An example of a @qui-cli command that can be distributed as an Node package",
   "homepage": "https://github.com/battis/qui-cli/tree/main/examples/01%20Distributable%20Command#readme",
   "repository": {
     "type": "git",
@@ -23,7 +23,10 @@
     "build:compile": "tsc"
   },
   "dependencies": {
-    "@qui-cli/core": "^7.0.0"
+    "@qui-cli/colors": "workspace:*",
+    "@qui-cli/core": "workspace:*",
+    "@qui-cli/log": "workspace:*",
+    "@qui-cli/plugin": "workspace:*"
   },
   "devDependencies": {
     "@tsconfig/node-lts": "^24.0.0",

examples/01 Distributable Command/src/DistributableCommand.ts

@@ -1,7 +1,94 @@
+import { Colors } from '@qui-cli/colors';
+import { Positionals } from '@qui-cli/core';
+import { Log } from '@qui-cli/log';
 import * as Plugin from '@qui-cli/plugin';
 
-export type Configuration = Plugin.Configuration & {};
+/**
+ * The expected configuration parameters, which may the same as or different
+ * from the command line options
+ */
+export type Configuration = Plugin.Configuration & {
+  target?: string;
+  text?: string;
+  number?: number;
+  flag?: boolean;
+};
 
+/**
+ * Configure positionals outside of the hooks, so that you don't run the risk of
+ * having the configuration invoked multiple times, creating a series of
+ * unanticipated positional arguments
+ */
+Positionals.require({
+  target: {
+    description: 'A positional text argument'
+  }
+});
+Positionals.allowOnlyNamedArgs();
+Positionals.requireAtLeast(0);
+
+/** A unique name for the command to identify it within the Plugin.Registrar */
 export const name = 'distributable-command';
 
-export async function run() {}
+const config: Configuration = {
+  number: 2.171
+};
+
+/**
+ * The command line optoons that the can be passed to the command
+ *
+ * @returns Plugin.Options …but don't declare that, because it is _way_ more
+ *   useful to have it typed as the literal object that it returns
+ */
+export function options() {
+  return {
+    man: [{ level: 1, text: 'Command Options' }],
+    opt: {
+      text: {
+        description: 'A text parameter',
+        short: 't',
+        hint: Colors.quotedValue(`"argle bargle"`)
+      }
+    },
+    num: {
+      number: {
+        description: 'A numeric parameter',
+        hint: Colors.value('3.14159'),
+        /**
+         * Setting defaults in the config variable above allows
+         * pre-initialization updates to the defaults by other modules that
+         * depend on this one
+         */
+        default: config.number
+      }
+    },
+    flag: {
+      flag: {
+        description: 'A boolean parameter',
+        short: 'f'
+      }
+    }
+  };
+}
+
+/**
+ * Update the configuration (may be called by other modules and may be called
+ * multiple times)
+ */
+export function configure(proposal: Configuration = {}) {
+  for (const key in proposal) {
+    if (proposal[key] !== undefined) {
+      config[key] = proposal[key];
+    }
+  }
+}
+
+/** Initialize the command with the command line arguments */
+export function init({ values }: Plugin.ExpectedArguments<typeof options>) {
+  configure({ target: Positionals.get('target'), ...values });
+}
+
+/** The actual "business logic" of the command */
+export async function run() {
+  Log.syntaxColor({ config });
+}