docs(examples): commit finished "error" and "esm-cjs" and "exports" and "hierarchy" examples

Author: Xunnamius

examples/black-flag/error/cli.js

@@ -2,4 +2,13 @@
 
 import { runProgram } from '@black-flag/core';
 
-export default runProgram(import.meta.resolve('./commands'));
+export default runProgram(import.meta.resolve('./commands'), {
+  configureErrorHandlingEpilogue(...args) {
+    if (args[2].state.didOutputHelpOrVersionText) {
+      console.log('\n--\n');
+    }
+
+    console.log('handled error in error handling hook');
+    console.log('hook args entries (reversed):', Object.entries(args).reverse());
+  }
+});

examples/black-flag/error/commands/index.js

@@ -1,3 +1,91 @@
 // @ts-check
 
-export {};
+import { CliError, GracefulEarlyExitError } from '@black-flag/core';
+import { defaultUsageText } from '@black-flag/core/util';
+
+/**
+ * @type {() => import('@black-flag/core').RootConfiguration<{ 'fail-style':
+ * 'short' | 'full', 'fail-for-yargs': boolean, 'fail-for-cli': boolean,
+ * 'fail-for-other': boolean, 'no-show-help': boolean, throw?: 'graceful' |
+ * 'cli' | 'other' }>}
+ */
+export default function command() {
+  return {
+    usage:
+      defaultUsageText +
+      'Use --throw to throw a specific type of error. To throw a Yargs error, enter an unknown argument.',
+
+    builder(bf, _, argv) {
+      bf.example('$0 --throw graceful', '');
+      bf.example('$0 --throw cli', '');
+      bf.example('$0 --fake', '');
+      bf.example('$0 --fake --no-show-help', '');
+      bf.example('$0 --throw other', '');
+      bf.example('$0 --throw other --fail-for-other', '');
+      bf.example('$0 --fake --fail-for-yargs false', '');
+
+      bf.parserConfiguration({ 'boolean-negation': false });
+
+      if (argv) {
+        bf.showHelpOnFail(
+          argv.noShowHelp
+            ? false
+            : {
+                outputStyle: argv.failStyle,
+                showFor: {
+                  cli: argv.failForCli,
+                  yargs: argv.failForYargs,
+                  other: argv.failForOther
+                }
+              }
+        );
+      }
+
+      return {
+        'fail-style': { choices: ['short', 'full'], default: 'short' },
+        'fail-for-yargs': { boolean: true, default: true },
+        'fail-for-cli': { boolean: true, default: false },
+        'fail-for-other': { boolean: true, default: false },
+        'no-show-help': {
+          boolean: true,
+          default: false
+          // We could do this in Black Flag Extensions, but vanilla Yargs does
+          // not support this otherwise-intuitive use of `conflicts`!
+          // conflicts: [
+          //   'fail-for-style',
+          //   'fail-for-yargs',
+          //   'fail-for-cli',
+          //   'fail-for-other'
+          // ]
+        },
+        throw: {
+          choices: ['graceful', 'cli', 'other']
+        }
+      };
+    },
+
+    handler(argv) {
+      switch (argv.throw) {
+        case 'graceful': {
+          throw new GracefulEarlyExitError('thrown GracefulEarlyExit error');
+          break;
+        }
+
+        case 'cli': {
+          throw new CliError('thrown CLI error');
+          break;
+        }
+
+        case 'other': {
+          throw new Error('thrown error');
+          break;
+        }
+
+        default: {
+          console.log('hello, world!');
+          break;
+        }
+      }
+    }
+  };
+}

examples/black-flag/esm-cjs/cli.cjs

@@ -1,7 +1,5 @@
 #!/usr/bin/env node
 
-const path = require('node:path');
-
 const { runProgram } = require('@black-flag/core');
 
-module.exports = runProgram(path.dirname(require.resolve('./commands')));
+module.exports = runProgram('./commands');

examples/black-flag/esm-cjs/cli.js

@@ -0,0 +1,12 @@
+// @ts-check
+
+/**
+ * @type {() => import('@black-flag/core').RootConfiguration}
+ */
+module.exports = function command() {
+  return {
+    handler() {
+      console.log('ran command at', __filename);
+    }
+  };
+};

examples/black-flag/esm-cjs/commands/index.cjs

@@ -0,0 +1,12 @@
+// @ts-check
+
+/**
+ * @type {() => import('@black-flag/core').RootConfiguration}
+ */
+export default function command() {
+  return {
+    handler() {
+      console.log('ran command at', import.meta.filename);
+    }
+  };
+}

examples/black-flag/esm-cjs/commands/ndx.js

@@ -1,3 +1,10 @@
 // @ts-check
 
-export {};
+/**
+ * @type {import('@black-flag/core').RootConfiguration['builder']}
+ */
+export const builder = (bf) => {
+  bf.example('$0 --help', '');
+  bf.example('$0 recommended --help', '');
+  bf.example('$0 recommended cjs --help', '');
+};

examples/black-flag/exports/cli.js

@@ -0,0 +1,45 @@
+// @ts-check
+
+const { $executionContext } = require('@black-flag/core');
+const { defaultUsageText } = require('@black-flag/core/util');
+
+/**
+ * @type {import('@black-flag/core').ChildConfiguration<{ name: string, id:
+ * string, force: boolean }>}
+ */
+module.exports = {
+  command: '$0 <name> <id>',
+  description: 'Add a new remote',
+
+  usage: `${defaultUsageText}.
+
+You can also provide long-form explanatory text here that will only be displayed when --help is given. Long-form usage text will not be shown when errors occur by default, but this can be configured using \`configureExecutionContext\`.
+
+See the documentation for more details.`,
+
+  builder(blackFlag, _, argv) {
+    blackFlag.positional('name', {
+      description: `The name of the remote to${argv?.force ? ' forcibly' : ''} add`
+    });
+
+    blackFlag.positional('id', { description: 'The remote identifier' });
+
+    return {
+      force: {
+        alias: 'f',
+        boolean: true,
+        description: 'Override protections',
+        default: false
+      }
+    };
+  },
+
+  async handler({ name, id, force, [$executionContext]: context }) {
+    if (force) {
+      console.log('Running with --force, recommended protections DISABLED!');
+    }
+
+    console.log(`Added new remote "${name}": ${id}`);
+    console.log('Saw context.somethingSpecial:', context.somethingSpecial);
+  }
+};

examples/black-flag/exports/commands/index.js

@@ -0,0 +1,45 @@
+// @ts-check
+
+import { $executionContext } from '@black-flag/core';
+import { defaultUsageText } from '@black-flag/core/util';
+
+/**
+ * @type {import('@black-flag/core').ChildConfiguration<{ name: string, id:
+ * string, force: boolean }>}
+ */
+export default {
+  command: '$0 <name> <id>',
+  description: 'Add a new remote',
+
+  usage: `${defaultUsageText}.
+
+You can also provide long-form explanatory text here that will only be displayed when --help is given. Long-form usage text will not be shown when errors occur by default, but this can be configured using \`configureExecutionContext\`.
+
+See the documentation for more details.`,
+
+  builder(blackFlag, _, argv) {
+    blackFlag.positional('name', {
+      description: `The name of the remote to${argv?.force ? ' forcibly' : ''} add`
+    });
+
+    blackFlag.positional('id', { description: 'The remote identifier' });
+
+    return {
+      force: {
+        alias: 'f',
+        boolean: true,
+        description: 'Override protections',
+        default: false
+      }
+    };
+  },
+
+  async handler({ name, id, force, [$executionContext]: context }) {
+    if (force) {
+      console.log('Running with --force, recommended protections DISABLED!');
+    }
+
+    console.log(`Added new remote "${name}": ${id}`);
+    console.log('Saw context.somethingSpecial:', context.somethingSpecial);
+  }
+};