# cli_pkg 2.4.6

Grinder tasks for releasing Dart CLI packages.




## Installing
```
export PUB_HOSTED_URL=https://pub.mirror.p-hatan.ir
flutter pub add 'cli_pkg:2.4.6'
```
Published: 2023-06-09T01:25:38.100311Z
Expected archive SHA-256: ecf59d84bb314f8cd13a3c13b8b40498b5706e03a1f43947eda2d368e1c7bf67

Available in cache; verification: upstream_checksum
## Direct dependencies
- archive: ^3.1.2
- async: ^2.5.0
- charcode: ^1.2.0
- cli_util: ^0.4.0
- collection: ^1.15.0
- crypto: ^3.0.0
- glob: ^2.0.0
- grinder: ^0.9.0
- http: ^0.13.0
- js: ^0.6.3
- meta: ^1.3.0
- node_interop: ^2.0.0
- node_preamble: ^2.0.0
- package_config: ^2.0.0
- path: ^1.8.0
- pool: ^1.5.0
- pub_semver: ^2.0.0
- pubspec_parse: ^1.0.0
- retry: ^3.1.0
- string_scanner: ^1.1.0
- test: ^1.16.7
- test_process: ^2.0.0
- xml: ^5.0.2
- yaml: ^3.1.0

## Package README (untrusted upstream documentation)
## Dart CLI Packager

This package provides a set of [Grinder][] tasks that make it easy to release a
Dart command-line application on many different release channels, to Dart users
and non-Dart users alike. It also integrates with Travis CI to make it easy to
automatically deploy packages.

[Grinder]: https://pub.dev/packages/grinder

To use this package, import `package:cli_pkg/cli_pkg.dart` and call
[`pkg.addAllTasks()`][] before calling [`grind()`][]:

[`pkg.addAllTasks()`]: https://pub.dev/documentation/cli_pkg/latest/cli_pkg/addAllTasks.html
[`grind()`]: https://pub.dev/documentation/grinder/latest/grinder/grind.html

```dart
import 'package:cli_pkg/cli_pkg.dart' as pkg;
import 'package:grinder/grinder.dart';

void main(List<String> args) {
  pkg.addAllTasks();
  grind(args);
}
```

The following sets of tasks are provided, each of which can also be enabled
individually:

* [Creating standalone archives for your package.](doc/standalone.md)
* [Uploading standalone archives to GitHub releases.](doc/github.md)
* [Compiling to JavaScript and publishing to npm.](doc/npm.md)
* [Uploading standalone archives to Chocolatey.](doc/chocolatey.md)
* [Updating a Homebrew formula to download from GitHub releases.](doc/homebrew.md)
* [Publishing to pub.](doc/pub.md)

It's strongly recommended that this package be imported with the prefix `pkg`.

### Configuration

This package is highly configurable, using [`ConfigVariable`][] fields defined
[at the top level of the library][]. By default, it infers as much configuration
as possible from the package's pubspec, but almost all properties can be
overridden in the `main()` method:

[`ConfigVariable`]: https://pub.dev/documentation/cli_pkg/latest/cli_pkg/ConfigVariable.html
[at the top level of the library]: https://pub.dev/documentation/sass/latest/sass/sass-library.html#properties

```dart
import 'package:cli_pkg/cli_pkg.dart' as pkg;
import 'package:grinder/grinder.dart';

void main(List<String> args) {
  pkg.name.value = "bot-name";
  pkg.humanName.value = "My App";

  pkg.addAllTasks();
  grind(args);
}
```

`ConfigVariable`s whose values are expensive to compute or that might fail under
some circumstances can also be set to callback functions, which are called
lazily when the variables are used by the Grinder tasks:

```dart
import 'package:cli_pkg/cli_pkg.dart' as pkg;
import 'package:grinder/grinder.dart';

void main(List<String> args) {
  pkg.githubReleaseNotes.fn = () => File.read("RELNOTES.md");

  pkg.addAllTasks();
  grind(args);
}
```

Each task describes exactly which configuration variables it uses. Configuration
that just applies to one set of tasks is always prefixed with a corresponding
name. For example, [`pkg.jsFlags`][] applies to JavaScript compilation.

[`pkg.jsFlags`]: https://pub.dev/documentation/cli_pkg/latest/cli_pkg/jsFlags.html

## Changelog
## 2.4.6

* Properly mark NPM packages as `"type": "module"` when `pkg.jsEsmExports` is
  set, and mark all CJS files as explicitly `.cjs`.

## 2.4.5

* Properly set the pub credentials for the latest versions of the Dart SDK.

* `pkg.homebrewFormula` now looks for formula files in the `Formula` directory
  as well as the repository root.

## 2.4.4

* Remove logical OR assignment operators that made the JS code generated by this
  package incompatible with older versions of Node.

## 2.4.3

* Fix a bug where Node.js executables failed with `jsEsmExports` set.

## 2.4.2

* Remove nullish coalescing operators that made the JS code generated by this
  package incompatible with older versions of Node.

## 2.4.1

* Fix a crash on dart sdks under experimental OS support.

* Work around a bug in Vite when bundling packages for the browser.

## 2.4.0

* Add standalone tasks for experimental dart sdks. These tasks are only
  available directly on experimental dart sdks.

## 2.3.0

* Added `pkg.jsEsmExports`. If this is set, `cli_pkg` will generate ESM
  libraries for each target in addition to CommonJS.

* Made `JSRequireTarget` a proper enum.

* Added `JSRequireTarget.defaultTarget`, which is explicitly loaded only by the
  `"default"` [conditional export] in package.json.

  [conditional export]: https://nodejs.org/api/packages.html#packages_conditional_exports

* It's now allowed to set `JSRequire`s with `JSRequireTarget.cli` without
  setting `jsModuleMainLibrary`.

* **Potentially breaking bug fix:** Instead of scraping source maps after the
  fact, added `--no-source-maps` to the default value of `jsReleaseFlags`.

## 2.2.0

* Use the current SDK's `dart` executable to build the standalone snapshot for
  current architecture.

* Generate a native snapshot rather than a self-contained executable on Linux.

## 2.1.9

* Use `readlink -f` in standalone scripts that wrap snapshots on operating
  systems where it's available. This ensures that the path resolution for those
  scripts is accurate even in the presence of complex symlinks.

## 2.1.8

* Properly follow GitHub API pagination links in `pkg-github-fix-permissions` so
  that it fixes all targets, not just the first page of results.

## 2.1.7

* **Important security bug fix:** Fix incorrect file permissions in the
  standalone `.tar.gz` archives. Previously, files in these archives were
  incorrectly marked as world-writable in the archive metadata. While this
  metadata is ignored under most circumstances, users on multi-user systems who
  explicitly pass `--preserve-permissions` or who extract the archives as root
  would end up with an executable that another user on the same system could
  overwrite with malicious code.

* Add a `pkg-github-fix-permissions` task which fixes this security issue in all
  archives which were uploaded to GitHub releases for the current package.

## 2.1.6

* Use `dart run` commands rather than `dart pub run` for compatibility with the
  latest Dart releases.

## 2.1.5

* **Potentially breaking bug fix:** The `pkg-homebrew-update` task must now
  download a repository archive from GitHub in order to generate the sha256
  hash rather than generating it directly from the local repository. This is
  necessary because GitHub changed their `.tar.gz` format so that it no longer
  precisely matches the format generated by `git archive`.

  This is only a breaking change if you were relying on running
  `pkg-homebrew-update` *before* pushing the tag in question to GitHub.

# 2.1.4

* Now merges `"exports"` **objects** declared in the original `package.json`
  when using `JsRequires` with a target other than `all`. Note that string and
  array values will still be overwritten.

# 2.1.3

* Don't mangle lists in automatically-extracted CHANGELOG entries for GitHub
  releases.

# 2.1.2

* Use `dart pub` commands rather than `pub` for compatibility with the latest
  Dart releases.

# 2.1.1

* Narrow the SDK constraint to reflect the use of a new API.

# 2.1.0

* Add `pkg-github-$os-$arch` tasks, which compile and upload binaries for the
  given operating system and architecture.

* `pkg-github-linux`, `pkg-github-macos`, and `pkg-github-windows` now compile
  and upload binaries for all supported architectures.

* Use `dart pub` commands rather than `pub` for compatibility with the latest
  Dart releases.

# 2.0.3

* Fix a bug where dynamic calls to `require()` would always be `null` in an npm
  package.

# 2.0.2

* Fix a bug where an npm package with target-specific `JSRequire`s would include
  an invalid `"main"` field in its `package.json`.

# 2.0.1

* Work around an npm bug that was causing `npm publish` to fail.

# 2.0.0

* **Breaking change:** The `jsRequires` map has been changed to a list of
  `JSRequire` objects. These objects allow packages to specify exactly which
  target(s) a given dependency should be loaded on, so for example they can
  provide a package that loads the `fs` module for Node.js but can still be
  bundled for the browser without it.

# 1.7.0

* Callbacks passed to `ConfigVariable.fn=` can now return nullable values even
  for non-nullable types. Doing so will cause the variable to use its default
  value. The behavior for nullable types remains unchanged.

# 1.6.0

* Add `pkg-standalone-linux-arm64` and `pkg-standalone-mac-arm64` tasks, which
  compile Linux and Mac OS binaries respectively for 64-bit ARM architectures.
  As with other 64-bit architectures, these will compile native executables when
  invoked on the same OS/architecture combination they're targeting, and will
  compile script snapshots otherwise.

* `pkg-standalone-all` now compiles Linux and Mac OS binaries for 64-bit ARM
  architectures.

# 1.5.2

* Use `dart compile exe` and `dart compile aot-snapshot` instead of
  `dart2native` when compiling standalone executables.

* The space character is no longer forbidden in environment constants, since
  https://github.com/dart-lang/sdk/issues/46050 has been fixed.

# 1.5.1

* Properly run executables from source in `testing.dart` when their public names
  are different than their filenames.

# 1.5.0

* Add `pkg.npmAdditionalFiles` to make it possible to add custom files to npm
  packages.

* `pkg.addChocolateyTasks()` no longer automatically adds standalone tasks,
  since Chocolatey tasks no longer depend on standalone tasks.

* `pkg-chocolatey` now creates a file named `LICENSE.txt` rather than `LICENSE`,
  at the request of the Chocolatey reviewers.

# 1.4.0

* Add `pkg.environmentConstants` to make it possible to define custom
  environment constants for the compiled executables.

# 1.3.0

* Migrate to null-safety.

# 1.2.0

* Add a `pkg.githubBearerToken` to make it easier to integrate with GitHub
  actions.

* Generate a fully standalone executable on Linux rather than a native snapshot.

# 1.1.0

* The main function generated by this package will return a `Promise` if the
  corresponding Dart main function returns a `Future`.

# 1.0.0

* Initial stable release.

### Changes since 1.0.0-beta.13

* Don't fold link reference declarations like paragraphs when generating GitHub
  release notes.

# 1.0.0-beta.13

* Add a `ConfigVariable.defaultValue` property to get the default value for
  variables that are overridden by functions.

* Fix a typo in error messages when files need to be regenerated for tests.

# 1.0.0-beta.12

* Deploy Chocolatey packages as source files rather than a zip file, to avoid
  validation errors around the need for a `VERIFICATION` file.

# 1.0.0-beta.11

* Properly load the Dart SDK license when it's in the directory above the SDK,
  as in a Homebrew installation.

* Use the latest version of the `xml` package.

# 1.0.0-beta.10

* **Breaking change:** All configurable variables are now defined as
  `ConfigVariable` objects rather than top-level fields. These objects make it
  possible to configure variables with callback functions and to freeze those
  variables once execution has begun.

* Properly handle git repositories that use branch names other than `master`.

# 1.0.0-beta.9

* Improve error messages if release notes can't be extracted from
  `CHANGELOG.md`.

# 1.0.0-beta.8

* Fixes a bug when reading a `CHANGELOG.md` with Windows-style line endings.

# 1.0.0-beta.7

* **Breaking change:** Dart snapshots are now named based on the executable name
  (specified in the pubspec or in `pkg.executables`) instead of the name of the
  Dart file in `bin`.

# 1.0.0-beta.6

* **Breaking change:** Chocolatey now uses the `choco` CLI to build and deploy
  packages, rather than re-implementing its logic in Dart. In particular:

  * The `pkg-chocolatey-build` task has been renamed to `pkg-chocolatey-pack` to
    match the CLI's naming scheme.

  * The `pkg-chocolatey-pack` and `pkg-chocolatey-deploy` tasks must be run in
    an environment with the `choco` command available.

* Add a `pkg-chocolatey` command that builds an un-archived Chocolatey package
  directory.

* Rather than releasing binary snapshots on Chocolatey, compile the source code
  to compile native executables on users' machines.

* Add a `chocolateyFiles` getter that returns the files that should be included
  in the Chocolatey package.

* Depend on the correct version of pre-release Dart SDKs from Chocolatey
  packages.

# 1.0.0-beta.5

* Use the correct URL when fetching GitHub release metadata.

# 1.0.0-beta.4

* Add a `pkg.npmDistTag` getter that controls the distribution tag for an npm
  release.

* Add a `pkg.homebrewCreateVersionedFormula` getter that controls whether the
  Homebrew release creates a new formula or updates an existing one.

* Run `pub publish --force` so it doesn't hang forever.

* Properly parse GitHub repositories from HTTP URLs ending in `.git`.

* Drop support for Mac OS ia32 packages, since Dart 2.7 doesn't support them
  anymore.

# 1.0.0-beta.3

* Add a `cli_pkg/testing.dart` library to make it easier for users to
  efficiently and reliably test their executables.

# 1.0.0-beta.2

* Add a `pkg-standalone-dev` task for building a script that can be invoked for
  testing.

* Fix a bug where the version variable wouldn't be set for certain executables.

# 1.0.0-beta.1

* Initial beta release.