Skip to content

Latest commit

 

History

History
386 lines (253 loc) · 18 KB

CHANGELOG.md

File metadata and controls

386 lines (253 loc) · 18 KB

Changelog

All notable changes to this project will be documented in this auto-generated file. The format is based on Conventional Commits; this project adheres to Semantic Versioning.


@black-flag/core@2.0.0 (2025-03-14)

💥 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.

  • 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.

  • 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.

  • Do not output entire help text when a command fails

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

  • Positionals are now available to builders alongside all other flags

    This is how vanilla Yargs does it. 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.

  • 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.

  • 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.

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

  • 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)

🔥 Reverted

  • "build(deps): bump core-js from 3.40.0 to 3.41.0" (488206d)

🏗️ Patch @black-flag/core@2.0.5 (2025-03-28)

🪄 Fixes

  • assets/transformers: improve error output when handling internal yargs error instances (269046f)
  • src: loosen builder function form return type (f15e922)

⚙️ Build System

  • readme: improve documentation (5231dd4)

🏗️ Patch @black-flag/core@2.0.4 (2025-03-25)

🪄 Fixes

  • src: allow Configuration::builder function value to explicitly accept void return type (2676cbe)

⚙️ Build System

  • deps: bump type-fest from 4.37.0 to 4.38.0 (9e25b0c)

🏗️ Patch @black-flag/core@2.0.2 (2025-03-19)

🪄 Fixes

  • packages/extensions: improve safeDeepClone to account for own symbol properties (119919e)
  • readme: update quick start example (bdafbf8)
  • readme: use latest interface to extract positional in quick start example (33895e7)
  • src: do not make context descriptors unenumerable (2e6c05b)

⚙️ Build System

  • deps: bump @-xun/js from 1.0.0 to 1.1.0 (0adf956)
  • deps: bump @-xun/js from 1.1.0 to 1.1.1 (f3f1f74)

🏗️ Patch @black-flag/core@2.0.1 (2025-03-17)

🪄 Fixes

⚙️ Build System

  • deps: bump core-js from 3.40.0 to 3.41.0 (9371719)

@black-flag/core@1.3.0 (2024-07-12)

✨ Features

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

🏗️ Patch @black-flag/core@1.3.2 (2024-07-12)

🪄 Fixes

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

🏗️ Patch @black-flag/core@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/core@1.2.0 (2024-03-18)

✨ Features

  • Add showHelp option to CliError (b5a1e58)

🏗️ Patch @black-flag/core@1.2.7 (2024-06-30)


🏗️ Patch @black-flag/core@1.2.6 (2024-06-02)

🪄 Fixes

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

🏗️ Patch @black-flag/core@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)

🏗️ Patch @black-flag/core@1.2.4 (2024-03-27)

🪄 Fixes

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

🏗️ Patch @black-flag/core@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)

🏗️ Patch @black-flag/core@1.2.2 (2024-03-21)

🪄 Fixes

  • No longer include default command when listing subcommands (be2960a)

⚙️ Build System

  • husky: update to latest hooks (75d5c66)
  • src: do not filter to own methods when proxying and rebinding (8bb0254)

🏗️ Patch @black-flag/core@1.2.1 (2024-03-19)


@black-flag/core@1.1.0 (2023-12-31)

✨ Features

  • src: support file://-style URLs (0e5067e)

🪄 Fixes

  • src: ensure --version is included in help text output when relevant (4f159dc)

🏗️ Patch @black-flag/core@1.1.4 (2024-03-16)


🏗️ Patch @black-flag/core@1.1.3 (2024-03-15)

🪄 Fixes

  • Add support for export default X syntax (bad391d)
  • Ensure demandOption is properly supported (2f205c1)

🏗️ Patch @black-flag/core@1.1.2 (2023-12-31)

🪄 Fixes

  • readme: move parserConfiguration call out of dead zone in example (f79c114)

🏗️ Patch @black-flag/core@1.1.1 (2023-12-31)

🪄 Fixes

  • Fix Node10 type resolution failure (b6178c9)

@black-flag/core@1.0.0 (2023-12-29)

✨ Features

  • src: disallow creating commands with conflicting names/aliases (78bf8ff)

🪄 Fixes

  • Rename package from "black-flag" to "@black-flag/core" npm typosquat workaround (292ead5)

⚙️ Build System

  • tsconfig: fix internal path resolution (fbe3a69)
  • tsconfig: upgrade to NodeNext (d3a499e)