refactor: restructure all examples to use directories.bin approach to command names

Author: battis

examples/dev-command/README.md

@@ -4,6 +4,6 @@ A distributable command-line app
 
 # Notes
 
-- [Command.ts](./src/Command.ts) is a plugin that defines the command. See [@battis/qui-cli.plugin](../../packages/plugin/README.md#usage) for plugin documentation.
-- [index.ts](./src/index.ts) registers the `Command` plugin and run the app.
-- [package.json](./package.json) `bin` points to compiled script
+- [index.ts](./src/index.ts) implements the command.
+- [package.json](./package.json) `directories.bin` points to directory of registered scripts.
+- [bin/dev-command](./bin/dev-command) is executable (`chmod +x`) and has the standard node shebang, and imports the command -- this structure allows for reliable use of the command across different package managers.

examples/dev-command/bin/dev-command

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

examples/dev-command/package.json

@@ -14,8 +14,8 @@
   "type": "module",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
-  "bin": {
-    "myCommand": "./dist/index.js"
+  "directories": {
+    "bin": "./bin"
   },
   "scripts": {
     "clean": "del ./dist",
@@ -26,8 +26,7 @@
   "dependencies": {
     "@battis/qui-cli.colors": "workspace:*",
     "@battis/qui-cli.core": "workspace:*",
-    "@battis/qui-cli.log": "workspace:*",
-    "@battis/qui-cli.plugin": "workspace:*"
+    "@battis/qui-cli.log": "workspace:*"
   },
   "devDependencies": {
     "@tsconfig/node20": "^20.1.6",

examples/dev-command/src/Command.ts

@@ -1,6 +1,19 @@
+import { Colors } from '@battis/qui-cli.colors';
 import { Core } from '@battis/qui-cli.core';
-import { register } from '@battis/qui-cli.plugin';
-import * as Command from './Command.js';
+import { Log } from '@battis/qui-cli.log';
+
+const {
+  values: { foo }
+} = await Core.init({
+  opt: {
+    foo: {
+      description: 'Type of foo-ness'
+    }
+  }
+});
 
-await register(Command);
 await Core.run();
+
+Log.info(
+  `The value of ${Colors.value('foo')} is ${Colors.quotedValue(`"${foo}"`)}`
+);

examples/dev-command/src/index.ts

@@ -10,7 +10,7 @@ Defines a reusable plugin package
 
 - [src/MyPlugin.ts](./plugin-provider/src/MyPlugin.ts) defines a reusable plugin. See [@battis/qui-cli.plugin](../../packages/plugin/README.md#usage) for plugin documentation.
 - [src/index.ts](./plugin-provider/src/index.ts) registers and exports the plugin for re-use.
-- [package.json](./plugin-provider/package.json) defines its dependency on another plugin ([@battis/qui-cli.log](../../packages/log/)) as a peer with a more lenient version descriptor than the dev dependency that is used for local development, trusting semantic versioning.
+- [package.json](./plugin-provider/package.json) defines its dependency on another plugin ([@battis/qui-cli.log](../../packages/log/)) as a peer with a more lenient version descriptor than the dev dependency that is used for local development, trusting semantic versioning. Peering assures that this plugin and its dependencies will be hoisted to the same level when imported into other projects.
 
 ## Consumers
 

examples/dev-plugin/README.md

@@ -0,0 +1,38 @@
+{
+  "name": "@examples/dev-plugin.conflict",
+  "version": "0.0.0",
+  "homepage": "https://github.com/battis/qui-cli/tree/main/examples/dev-plugin/plugin-conflict#readme",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/battis/qui-cli.git",
+    "directory": "examples/dev-plugin/plugin-conflict"
+  },
+  "author": {
+    "name": "Seth Battis",
+    "url": "https://github.com/battis"
+  },
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "directories": {
+    "bin": ":./bin"
+  },
+  "scripts": {
+    "clean": "del ./dist",
+    "build": "run-s build:*",
+    "build:clean": "run-s clean",
+    "build:compile": "tsc"
+  },
+  "dependencies": {
+    "@battis/qui-cli.core": "workspace:*",
+    "@battis/qui-cli.log": "workspace:*",
+    "@battis/qui-cli.plugin": "workspace:*",
+    "@examples/dev-plugin.provider": "workspace:*"
+  },
+  "devDependencies": {
+    "@tsconfig/node20": "^20.1.6",
+    "del-cli": "^6.0.0",
+    "npm-run-all": "^4.1.5",
+    "typescript": "^5.8.3"
+  }
+}

examples/dev-plugin/plugin-conflict/package.json

@@ -0,0 +1,54 @@
+import { Log } from '@battis/qui-cli.log';
+import * as Plugin from '@battis/qui-cli.plugin';
+
+export type Configuration = Plugin.Configuration & {
+  foo?: string;
+};
+
+export const name = 'my-plugin';
+
+let foo = 'foob';
+let bar: string | undefined = undefined;
+let baz = false;
+
+export function configure(config: Configuration = {}) {
+  foo = Plugin.hydrate(config.foo, foo);
+}
+
+export function options(): Plugin.Options {
+  return {
+    opt: {
+      foo: {
+        description: `Type of foo-ness (default ${foo})`,
+        default: foo
+      },
+      bar: {
+        description: 'Type of bar-ness'
+      }
+    },
+    flag: {
+      baz: {
+        description: `Whether or not to baz (default ${baz})`,
+        default: baz
+      }
+    }
+  };
+}
+
+export function init({ values }: Plugin.Arguments<ReturnType<typeof options>>) {
+  foo = Plugin.hydrate(values.foo, foo);
+  bar = Plugin.hydrate(values.bar, bar);
+  baz = Plugin.hydrate(values.baz, baz);
+}
+
+export function run() {
+  Log.info(`${foo} ${bar} ${baz ? 'baz' : 'not-baz'}`);
+}
+
+export function getFoo() {
+  return foo;
+}
+
+export function isBaz() {
+  return baz;
+}

examples/dev-plugin/plugin-conflict/src/ConflictingPlugin.ts

@@ -0,0 +1,12 @@
+import { register } from '@battis/qui-cli.plugin';
+import { MyPlugin } from '@examples/dev-plugin.provider';
+import { Core } from '../../../../packages/core/dist/index.js';
+import * as ConflictingPlugin from './ConflictingPlugin.js';
+
+// no problem re-registering a plugin that has already been registered
+await register(MyPlugin);
+
+// cannot register a _different_ plugin with the same name!
+await register(ConflictingPlugin);
+
+await Core.run();

examples/dev-plugin/plugin-conflict/src/index.ts

@@ -0,0 +1,7 @@
+{
+  "extends": "@tsconfig/node20/tsconfig.json",
+  "compilerOptions": {
+    "outDir": "./dist"
+  },
+  "include": ["./src"]
+}