Merge pull request #690 from dart-lang/merge-cli_util-package

Merge `package:cli_util`

.github/ISSUE_TEMPLATE/cli_util.md

@@ -0,0 +1,5 @@
+---
+name: "package:cli_util"
+about: "Create a bug or file a feature request against package:cli_util."
+labels: "package:cli_util"
+---

.github/labeler.yml

@@ -24,6 +24,10 @@
   - changed-files:
       - any-glob-to-any-file: 'pkgs/cli_config/**'
 
+'package:cli_util':
+  - changed-files:
+      - any-glob-to-any-file: 'pkgs/cli_util/**'
+
 'package:clock':
   - changed-files:
       - any-glob-to-any-file: 'pkgs/clock/**'

.github/workflows/cli_util.yaml

@@ -0,0 +1,66 @@
+name: package:cli_util
+
+on:
+  # Run on PRs and pushes to the default branch.
+  push:
+    branches: [ main ]
+    paths:
+      - '.github/workflows/cli_util.yml'
+      - 'pkgs/cli_util/**'
+  pull_request:
+    branches: [ main ]
+    paths:
+      - '.github/workflows/cli_util.yml'
+      - 'pkgs/cli_util/**'
+  schedule:
+    - cron: "0 0 * * 0"
+
+env:
+  PUB_ENVIRONMENT: bot.github
+
+
+defaults:
+  run:
+    working-directory: pkgs/cli_util/
+
+jobs:
+  analyze:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        sdk: [dev]
+    steps:
+    - uses: actions/checkout@d632683dd7b4114ad314bca15554477dd762a938
+    - uses: dart-lang/setup-dart@0a8a0fc875eb934c15d08629302413c671d3f672
+      with:
+        sdk: ${{ matrix.sdk }}
+    - id: install
+      name: Install dependencies
+      run: dart pub get
+    - name: Check formatting
+      run: dart format --output=none --set-exit-if-changed .
+      if: always() && steps.install.outcome == 'success'
+    - name: Analyze code
+      run: dart analyze --fatal-infos
+      if: always() && steps.install.outcome == 'success'
+
+  test:
+    needs: analyze
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest]
+        sdk: ['3.4', dev]
+    steps:
+    - uses: actions/checkout@d632683dd7b4114ad314bca15554477dd762a938
+    - uses: dart-lang/setup-dart@0a8a0fc875eb934c15d08629302413c671d3f672
+      with:
+        sdk: ${{ matrix.sdk }}
+    - id: install
+      name: Install dependencies
+      run: dart pub get
+    - name: Run tests
+      run: dart test --test-randomize-ordering-seed=random
+      if: always() && steps.install.outcome == 'success'

README.md

@@ -19,6 +19,7 @@ don't naturally belong to other topic monorepos (like
 | [boolean_selector](pkgs/boolean_selector/) | A flexible syntax for boolean expressions, based on a simplified version of Dart's expression syntax. | [![pub package](https://img.shields.io/pub/v/boolean_selector.svg)](https://pub.dev/packages/boolean_selector) |
 | [browser_launcher](pkgs/browser_launcher/) | Provides a standardized way to launch web browsers for testing and tools. | [![pub package](https://img.shields.io/pub/v/browser_launcher.svg)](https://pub.dev/packages/browser_launcher) |
 | [cli_config](pkgs/cli_config/) | A library to take config values from configuration files, CLI arguments, and environment variables. | [![pub package](https://img.shields.io/pub/v/cli_config.svg)](https://pub.dev/packages/cli_config) |
+| [cli_util](pkgs/cli_util/) | A library to help in building Dart command-line apps. | [![pub package](https://img.shields.io/pub/v/cli_util.svg)](https://pub.dev/packages/cli_util) |
 | [clock](pkgs/clock/) | A fakeable wrapper for dart:core clock APIs. | [![pub package](https://img.shields.io/pub/v/clock.svg)](https://pub.dev/packages/clock) |
 | [coverage](pkgs/coverage/) | Coverage data manipulation and formatting. | [![pub package](https://img.shields.io/pub/v/coverage.svg)](https://pub.dev/packages/coverage) |
 | [csslib](pkgs/csslib/) | A library for parsing and analyzing CSS (Cascading Style Sheets). | [![pub package](https://img.shields.io/pub/v/csslib.svg)](https://pub.dev/packages/csslib) |

pkgs/cli_util/.gitignore

@@ -0,0 +1,3 @@
+.dart_tool/
+.packages
+pubspec.lock

pkgs/cli_util/AUTHORS

@@ -0,0 +1,6 @@
+# Below is a list of people and organizations that have contributed
+# to the cli_util project. Names should be added to the list like so:
+#
+#   Name/Organization <email address>
+
+Google Inc.

pkgs/cli_util/CHANGELOG.md

@@ -0,0 +1,105 @@
+## 0.4.2
+
+- Add `sdkPath` getter, deprecate `getSdkPath` function.
+* Move to `dart-lang/tools` monorepo.
+
+## 0.4.1
+
+- Fix a broken link in the readme.
+- Require Dart 3.0.
+
+## 0.4.0
+
+- Remove the deprecated method `getSdkDir()` (instead, use `getSdkPath()`).
+- Require Dart 2.19.
+
+## 0.3.5
+- Make `applicationConfigHome` throw an `Exception` when it fails to find a
+  configuration folder.
+
+## 0.3.4
+
+- Introduce `applicationConfigHome` for making it easy to consistently find the
+  user-specific application configuration folder.
+
+## 0.3.3
+
+- Reverted `meta` constraint to `^1.3.0`.
+
+## 0.3.2
+
+- Update `meta` constraint to `>=1.3.0 <3.0.0`.
+
+## 0.3.1
+
+- Fix a bug in `AnsiProgress` where the spinning character doesn't every update.
+
+## 0.3.0
+
+- Stable null safety release.
+
+## 0.3.0-nullsafety.0
+
+- Updated to support 2.12.0 and null safety.
+
+## 0.2.1
+
+## 0.2.0
+
+- Add `Logger.write` and `Logger.writeCharCode` methods which write without
+  printing a trailing newline.
+
+## 0.1.4
+
+- Add `Ansi.reversed` getter.
+
+## 0.1.3+2
+
+- Update Dart SDK constraint to < 3.0.0.
+
+## 0.1.3+1
+
+- Update Dart SDK to 2.0.0-dev.
+
+## 0.1.3
+
+- In verbose mode, instead of printing the diff from the last log message,
+  print the total time since the tool started
+- Change to not buffer the last log message sent in verbose logging mode
+- Expose more classes from the logging library
+
+## 0.1.2+1
+
+- Remove unneeded change to Dart SDK constraint.
+
+## 0.1.2
+
+- Fix a bug in `getSdkDir` (#21)
+
+## 0.1.1
+
+- Updated to the output for indeterminate progress
+- Exposed a `Logger.isVerbose` getter
+
+## 0.1.0
+
+- Added a new `getSdkPath()` method to get the location of the SDK (this uses the new
+  `Platform.resolvedExecutable` API to locate the SDK)
+- Deprecated `getSdkDir()` in favor of `getSdkPath()`
+- Add the `cli_logging.dart` library - utilities to display output and progress
+
+## 0.0.1+3
+
+- Find SDK properly when invoked from inside SDK tests.
+
+## 0.0.1+2
+
+- Support an executable in a symlinked directory.
+
+## 0.0.1+1
+
+- Fix for when the dart executable can't be found by `which`.
+
+## 0.0.1
+
+- Initial version

pkgs/cli_util/LICENSE

@@ -0,0 +1,27 @@
+Copyright 2015, the Dart project authors. 
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are
+met:
+
+    * Redistributions of source code must retain the above copyright
+      notice, this list of conditions and the following disclaimer.
+    * Redistributions in binary form must reproduce the above
+      copyright notice, this list of conditions and the following
+      disclaimer in the documentation and/or other materials provided
+      with the distribution.
+    * Neither the name of Google LLC nor the names of its
+      contributors may be used to endorse or promote products derived
+      from this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+"AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
+A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
+OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
+LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

pkgs/cli_util/README.md

@@ -0,0 +1,68 @@
+[![Build Status](https://github.com/dart-lang/tools/actions/workflows/cli_util.yaml/badge.svg)](https://github.com/dart-lang/tools/actions/workflows/cli_util.yaml)
+[![Pub](https://img.shields.io/pub/v/cli_util.svg)](https://pub.dev/packages/cli_util)
+[![package publisher](https://img.shields.io/pub/publisher/cli_util.svg)](https://pub.dev/packages/cli_util/publisher)
+
+A package to help in building Dart command-line apps.
+
+## What's this?
+
+`package:cli_util` provides:
+- utilities to find the Dart SDK directory (`sdkPath`)
+- utilities to find the settings directory for a tool (`applicationConfigHome()`)
+- utilities to aid in showing rich CLI output and progress information (`cli_logging.dart`)
+
+## Locating the Dart SDK
+
+```dart
+import 'dart:io';
+
+import 'package:cli_util/cli_util.dart';
+import 'package:path/path.dart' as path;
+
+main(args) {
+  // Get SDK directory from cli_util.
+  var sdkDir = sdkPath;
+  
+  // Do stuff... For example, print version string
+  var versionFile = File(path.join(sdkDir, 'version'));
+  print(versionFile.readAsStringSync());
+}
+```
+
+## Displaying output and progress
+
+`package:cli_util` can also be used to help CLI tools display output and progress.
+It has a logging mechanism which can help differentiate between regular tool
+output and error messages, and can facilitate having a more verbose (`-v`) mode for
+output.
+
+In addition, it can display an indeterminate progress spinner for longer running
+tasks, and optionally display the elapsed time when finished: 
+
+```dart
+import 'package:cli_util/cli_logging.dart';
+
+void main(List<String> args) async {
+  var verbose = args.contains('-v');
+  var logger = verbose ? Logger.verbose() : Logger.standard();
+
+  logger.stdout('Hello world!');
+  logger.trace('message 1');
+  await Future.delayed(Duration(milliseconds: 200));
+  logger.trace('message 2');
+  logger.trace('message 3');
+
+  var progress = logger.progress('doing some work');
+  await Future.delayed(Duration(seconds: 2));
+  progress.finish(showTiming: true);
+
+  logger.stdout('All ${logger.ansi.emphasized('done')}.');
+  logger.flush();
+}
+```
+
+## Features and bugs
+
+Please file feature requests and bugs at the [issue tracker][tracker].
+
+[tracker]: https://github.com/dart-lang/tools/issues

pkgs/cli_util/analysis_options.yaml

@@ -0,0 +1,32 @@
+# https://dart.dev/guides/language/analysis-options
+include: package:dart_flutter_team_lints/analysis_options.yaml
+
+analyzer:
+  language:
+    strict-casts: true
+    strict-inference: true
+    strict-raw-types: true
+
+linter:
+  rules:
+  - avoid_bool_literals_in_conditional_expressions
+  - avoid_classes_with_only_static_members
+  - avoid_private_typedef_functions
+  - avoid_redundant_argument_values
+  - avoid_returning_this
+  - avoid_unused_constructor_parameters
+  - avoid_void_async
+  - cancel_subscriptions
+  - join_return_with_assignment
+  - literal_only_boolean_expressions
+  - missing_whitespace_between_adjacent_strings
+  - no_adjacent_strings_in_list
+  - no_runtimeType_toString
+  - prefer_const_declarations
+  - prefer_expression_function_bodies
+  - prefer_final_locals
+  - unnecessary_await_in_return
+  - unnecessary_raw_strings
+  - use_if_null_to_convert_nulls_to_bools
+  - use_raw_strings
+  - use_string_buffers

pkgs/cli_util/example/main.dart

@@ -0,0 +1,24 @@
+// Copyright (c) 2017, the Dart project authors.  Please see the AUTHORS file
+// for details. All rights reserved. Use of this source code is governed by a
+// BSD-style license that can be found in the LICENSE file.
+
+import 'dart:async';
+
+import 'package:cli_util/cli_logging.dart';
+
+Future<void> main(List<String> args) async {
+  final verbose = args.contains('-v');
+  final logger = verbose ? Logger.verbose() : Logger.standard();
+
+  logger.stdout('Hello world!');
+  logger.trace('message 1');
+  await Future<void>.delayed(const Duration(milliseconds: 200));
+  logger.trace('message 2');
+  logger.trace('message 3');
+
+  final progress = logger.progress('doing some work');
+  await Future<void>.delayed(const Duration(seconds: 2));
+  progress.finish(showTiming: true);
+
+  logger.stdout('All ${logger.ansi.emphasized('done')}.');
+}