@black-flag/[email protected]

💥 BREAKING CHANGES 💥

• Positionals are now available to builders alongside all other flags

  This is how vanilla Yargs (and Black Flag) does it for handlers. The behavior is now consistent in builders taking advantage of dynamic options. In earlier versions, builders' argv param had all positionals dumped into argv._ due to a suboptimal parsing extension.

• Show any available child commands in ALL error text

  This includes when trying to use a command that is not found.

• Do not output entire help text when a command fails

  Skip all but the first line of usage text in output by default.

• Upgrade ExecutionContext::state.showHelpOnFail to allow configuration of help text output style

  New output style options include "short" (first line of usage only, this is now the default) and "full" (full usage string). Also allows configuration of which error kinds trigger help text output and which do not. See documentation for details.

• Surface new CliError::showHelp parameter values

  • "short"/true, which will print the command help text without all but the first line of usage text.

  • "default", which will defer to ExecutionContext::state.showHelpOnFail.

  • "full", which will force the old functionality.

  • false, which ensures help text is never printed with respect to the current error instance.

• Better help text output for dynamic options

  With this change, Black Flag lets Yargs fully parse argv and run through the builder twice before bailing to print help text when --help (or the equivalent option) is given.

  This allows input that triggers dynamic options like my-command --flag-1 --flag-2 --help to show help text specific to the final resolved builder configurations of --flag-1 --flag-2 rather than always showing the most generic help text, which was the behavior of older Black Flag versions. See documentation for details.

• $executionContext and $artificiallyInvoked symbols are now drawn from the global symbol registry. They will not match symbols from previous versions!

• All instances in source where commandModulePath appeared have been replaced by commandModulesPath. This includes the call signatures of functions like makeRunner.

  The fix is simple: find-and-replace all instances of commandModulePath with commandModulesPath.

• Along with implementing the errorHandlingBehavior DX improvement in makeRunner, this update also addresses several small discrepancies in the behavior of configureProgram, runProgram, and makeRunner. These functions should now behave identically where appropriate (i.e. as described in their documentation), including consistently triggering the same error handling behavior at the same points for the same reasons given the same inputs.

  Additionally, non-graceful errors that are not handled by ConfigureErrorHandlingEpilogue will be consistently presented to the user as framework errors (assertion failures). As such, runProgram (and the low-order function returned by makeRunner) should no longer throw in some edge cases, such as when being passed a rejected promise or when a hook that is evaluated early throws.

• ErrorMessage export was renamed to BfErrorMessage

✨ Features

• src: export getDeepestErrorCause under /util (bf001c4)
• src: implement errorHandlingBehavior option in makeRunner (5e4eb3d)
• src: make expectedHelpTextRegExp utility a public export (8f2cb13)
• src: make positionals available to builders normally (no longer in argv._) (42367ce)
• src: output help text with greater fidelity (02a497f) ^{see #172}
• Support Windows-style paths (cd288c5)

🪄 Fixes

• Fix Windows interop issues (b3abf95) ^{see #174}
• package: add @types/yargs as production dependency (8d50a56)
• src: ensure ESM file bare exports are seen by black flag (389a2dc)
• src: fix node@18 interop issue (c1b5f61) ^{see #173}
• src: improve isX type assertion exports (b980544)
• src: improve intellisense across various exports (d6b1e73)
• src: more consistently handle various errors; improve output fidelity (9412aa6)
• src: throw upon encountering a command export with invalid yargs DSL (7312b8d)
• src: throw upon encountering an async builder export (78eb0a2)

⚙️ Build System

• deps: bump type-fest from 4.35.0 to 4.36.0 (33b2099)
• deps: bump type-fest from 4.36.0 to 4.37.0 (cdd8f61)
• husky: force lint-staged (via husky) to only use global config file (5d3f2cc)
• package: add @-xun/symbiote dev dependency (074a930)
• package: prune unnecessary dependencies (1b5cdbf)
• Throw in runProgram when an incompatible Node.js runtime version is detected (cb56f8d)

🧙🏿 Refactored

• Make exported symbols cross-realm (af78a8f)
• Rename and restructure exports for better docs generation (8303ba7)
• src: ErrorMessage export is now BfErrorMessage (3918a29)

@black-flag/[email protected]

💥 BREAKING CHANGES 💥

• All instances in source where commandModulePath appeared have been replaced by commandModulesPath. This includes the call signatures of functions like makeRunner.

  The fix is simple: find-and-replace all instances of commandModulePath with commandModulesPath.

✨ Features

• packages/checks: implement @black-flag/checks (64029b9)
• packages/checks: implement checkArrayNoConflicts and checkArrayUnique (10cd0eb)

🪄 Fixes

• Fix Windows interop issues (b3abf95) ^{see #174}

⚙️ Build System

• husky: force lint-staged (via husky) to only use global config file (5d3f2cc)
• husky: update to latest hooks (75d5c66)
• tsconfig: fix internal path resolution (fbe3a69)
• tsconfig: upgrade to NodeNext (d3a499e)

🧙🏿 Refactored

• Rename and restructure exports for better docs generation (8303ba7)

@black-flag/[email protected]

1.3.2 (2024-07-12)

🪄 Fixes

• src: tweak error handling debug verboseness in certain edge cases (96ce293)

@black-flag/[email protected]

1.3.1 (2024-07-12)

🪄 Fixes

• src: add trap door to alert developer when erroneously re-entering top-level error handler (99e2b3a)

@black-flag/[email protected]

1.3.0 (2024-07-12)

✨ Features

• clierror: add dangerouslyFatal option, update cause option handling (1c369fb)

@black-flag/[email protected]

1.2.7 (2024-06-30)

🪄 Fixes

• types: pass through CustomExecutionContext as context type in ImportedConfigurationModule (cdc6af5)

⚙️ Build system

• spellcheck-commit: fix commit spellchecker (6e7a268)

@black-flag/[email protected]

1.2.6 (2024-06-02)

🪄 Fixes

• src: ignore --help and --version if they occur after -- in argv (35f66cc)

@black-flag/[email protected]

1.2.5 (2024-05-30)

🪄 Fixes

• src: permanently fix --version support regression in node@22 (c201c2f)

⚙️ Build system

• package: append node@22 to supported node versions (98815d1)

@black-flag/[email protected]

1.2.4 (2024-03-27)

🪄 Fixes

• src: explicitly ignore .d.ts files within command dirs (d6618d3)

@black-flag/[email protected]

1.2.3 (2024-03-27)

🪄 Fixes

• package: bump minimum node support to 20 LTS (4b8c975)
• src: ignore unknown file extension errors when discovering commands (4babf12)