docs(examples): commit finished "hooks" and "positional" and "shared" examples

Author: Xunnamius

examples/black-flag-extensions/checks/README.md

@@ -3,7 +3,8 @@
 # Black Flag Extensions: Custom `check`s
 
 In this example we demonstrate taking full advantage of BFE's declarative
-per-option [check][3] functionality.
+per-option [check][3] functionality, including making use of [Black Flag
+Checks][4].
 
 ## Run This Example
 
@@ -16,3 +17,4 @@ You can also run this example's tests by executing `npm test`.
 [1]: ../../README.md
 [2]: ../README.md
 [3]: ../../../packages/extensions/README.md#check
+[4]: ../../../packages/checks/README.md

examples/black-flag/hooks/cli.js

@@ -1,5 +1,31 @@
 #!/usr/bin/env node
+// @ts-check
 
 import { runProgram } from '@black-flag/core';
 
-export default runProgram(import.meta.resolve('./commands'));
+export default runProgram(import.meta.resolve('./commands'), {
+  configureArguments(rawArgv, context) {
+    console.log('configureArguments -> rawArgv:', rawArgv);
+    console.log('configureArguments -> context:', context);
+    return rawArgv;
+  },
+  configureErrorHandlingEpilogue(meta, argv, _context) {
+    console.log('configureErrorHandlingEpilogue -> meta:', meta);
+    console.log('configureErrorHandlingEpilogue -> argv:', argv);
+    console.log('configureErrorHandlingEpilogue -> context:', '(the same)');
+  },
+  configureExecutionContext(context) {
+    context.customContextKey = { custom: 'value' };
+    console.log('configureExecutionContext -> context:', context);
+    return context;
+  },
+  configureExecutionEpilogue(argv, _context) {
+    console.log('configureExecutionEpilogue -> argv:', argv);
+    console.log('configureExecutionEpilogue -> context:', '(the same)');
+    return argv;
+  },
+  configureExecutionPrologue(rootPrograms, _context) {
+    console.log('configureExecutionPrologue -> rootPrograms:', rootPrograms);
+    console.log('configureExecutionPrologue -> context:', '(the same)');
+  }
+});

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

@@ -1,3 +1,18 @@
 // @ts-check
 
-export {};
+export function builder(bf) {
+  bf.example('$0', '');
+  bf.example('$0 --help', '');
+  bf.example('$0 --something "goes here"', '');
+  bf.example('$0 --error-on-purpose', '');
+
+  return {
+    something: {
+      string: true
+    }
+  };
+}
+
+export function handler() {
+  console.log('ran command');
+}

examples/black-flag/positional/cli.js

@@ -1,3 +1,39 @@
 // @ts-check
 
-export {};
+export const command = '$0 <type> <value>';
+
+/**
+ * @type {Extract<import('@black-flag/core').ChildConfiguration<{ type: 'string' | 'boolean', value: string, force: boolean }>['builder'], function>}
+ */
+export function builder(blackFlag, _, argv) {
+  blackFlag.positional('type', {
+    description: 'The type of the value you want to pass in',
+    choices: ['string', 'boolean']
+  });
+
+  blackFlag.positional('value', {
+    description: 'The value you want to pass in',
+    ...(argv?.type ? { type: argv.type } : {})
+  });
+
+  return {
+    force: {
+      alias: 'f',
+      boolean: true,
+      description: 'Override protections',
+      default: false
+    }
+  };
+}
+
+export async function handler(
+  /** @type {import('@black-flag/core').Arguments<{ type: 'string' | 'boolean',
+   * value: string, force: boolean },
+   * import('@black-flag/core/util').ExecutionContext>} */ { type, value, force }
+) {
+  if (force) {
+    console.log('Running with --force, recommended protections DISABLED!');
+  }
+
+  console.log(`Doing something with ${type} value: ${value}`);
+}

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

@@ -0,0 +1,18 @@
+// @ts-check
+
+import { sharedBuilder, sharedHandler } from '../shared.js';
+
+/**
+ * @type {() => import('@black-flag/core').RootConfiguration}
+ */
+export default function command() {
+  return {
+    builder: sharedBuilder({
+      flag: { string: true, description: 'An option specific to this command' }
+    }),
+
+    handler: sharedHandler((argv) => {
+      console.log('(custom functionality) argv:', argv);
+    })
+  };
+}

examples/black-flag/shared/cli.js

@@ -0,0 +1,18 @@
+// @ts-check
+
+import { sharedBuilder, sharedHandler } from '../shared.js';
+
+/**
+ * @type {() => import('@black-flag/core').RootConfiguration}
+ */
+export default function command() {
+  return {
+    builder: sharedBuilder({
+      flag: { count: true, description: 'An option specific to this command' }
+    }),
+
+    handler: sharedHandler((argv) => {
+      console.log('(custom functionality) argv:', argv);
+    })
+  };
+}

examples/black-flag/shared/commands/a.js

@@ -0,0 +1,18 @@
+// @ts-check
+
+import { sharedBuilder, sharedHandler } from '../shared.js';
+
+/**
+ * @type {() => import('@black-flag/core').RootConfiguration}
+ */
+export default function command() {
+  return {
+    builder: sharedBuilder({
+      flag: { boolean: true, description: 'An option specific to this command' }
+    }),
+
+    handler: sharedHandler((argv) => {
+      console.log('(custom functionality) argv:', argv);
+    })
+  };
+}

examples/black-flag/shared/commands/b.js

@@ -1,3 +1,25 @@
 // @ts-check
 
-export {};
+import { sharedBuilder, sharedHandler } from '../shared.js';
+
+/**
+ * @type {() => import('@black-flag/core').RootConfiguration}
+ */
+export default function command() {
+  return {
+    builder: sharedBuilder((bf) => {
+      bf.group(['version'], 'Global Options:');
+
+      return {
+        'custom-flag': {
+          string: true,
+          description: 'An option specific to this command'
+        }
+      };
+    }),
+
+    handler: sharedHandler((argv) => {
+      console.log('(custom functionality) argv:', argv);
+    })
+  };
+}