Improve documentation of `pub token` and subcommands (#3778)
diff --git a/lib/src/authentication/token_store.dart b/lib/src/authentication/token_store.dart index a5ceba0..14a3d16 100644 --- a/lib/src/authentication/token_store.dart +++ b/lib/src/authentication/token_store.dart
@@ -29,7 +29,7 @@ /// [Credential]. List<Credential> _loadCredentials() { final result = <Credential>[]; - final path = _tokensFile; + final path = tokensFile; if (path == null || !fileExists(path)) { return result; } @@ -97,7 +97,7 @@ /// Writes [credentials] into "pub-tokens.json". void _saveCredentials(List<Credential> credentials) { - final tokensFile = _tokensFile; + final tokensFile = this.tokensFile; if (tokensFile == null) { missingConfigDir(); } @@ -171,7 +171,7 @@ /// Deletes pub-tokens.json file from the disk. void deleteTokensFile() { - final tokensFile = _tokensFile; + final tokensFile = this.tokensFile; if (tokensFile == null) { missingConfigDir(); } else if (!fileExists(tokensFile)) { @@ -185,7 +185,7 @@ /// Full path to the "pub-tokens.json" file. /// /// `null` if no config directory could be found. - String? get _tokensFile { + String? get tokensFile { var dir = configDir; return dir == null ? null : path.join(dir, 'pub-tokens.json'); }
diff --git a/lib/src/command.dart b/lib/src/command.dart index a0e4ebf..b7ee191 100644 --- a/lib/src/command.dart +++ b/lib/src/command.dart
@@ -37,7 +37,17 @@ 'upgrade': ['update'], }; -final lineLength = stdout.hasTerminal ? stdout.terminalColumns : 80; +final lineLength = _lineLength(); + +int _lineLength() { + final fromEnv = Platform.environment['_PUB_TEST_TERMINAL_COLUMNS']; + if (fromEnv != null) { + final parsed = int.tryParse(fromEnv); + if (parsed != null && parsed > 0) return parsed; + } + if (stdout.hasTerminal) return stdout.terminalColumns; + return 80; +} /// The base class for commands for the pub executable. ///
diff --git a/lib/src/command/token.dart b/lib/src/command/token.dart index 9886dcf..f1f15f1 100644 --- a/lib/src/command/token.dart +++ b/lib/src/command/token.dart
@@ -3,6 +3,7 @@ // BSD-style license that can be found in the LICENSE file. import '../command.dart'; +import '../command_runner.dart'; import 'token_add.dart'; import 'token_list.dart'; import 'token_remove.dart'; @@ -12,8 +13,17 @@ @override String get name => 'token'; @override - String get description => - 'Manage authentication tokens for hosted pub repositories.'; + String get description => ''' +Manage authentication tokens for hosted pub repositories. + +The tokens will be used for authorizing both when retrieving dependencies and +for publishing. + +Tokens are stored in `${tokenStore.tokensFile}`. + +For interactive authorization against pub.dev, use `$topLevelProgram pub login`.'''; + @override + String get docUrl => 'https://dart.dev/tools/pub/cmd/pub-token'; TokenCommand() { addSubcommand(TokenListCommand());
diff --git a/lib/src/command/token_add.dart b/lib/src/command/token_add.dart index 90805cb..5ade7ba 100644 --- a/lib/src/command/token_add.dart +++ b/lib/src/command/token_add.dart
@@ -7,6 +7,7 @@ import '../authentication/credential.dart'; import '../command.dart'; +import '../command_runner.dart'; import '../exceptions.dart'; import '../io.dart'; import '../log.dart' as log; @@ -18,12 +19,23 @@ @override String get name => 'add'; @override - String get description => - 'Add authentication tokens for a package repository.'; + String get description => ''' +Add an authentication token for a package repository. + +The token will be used for authorizing against <hosted-url> both when +retrieving dependencies and for publishing. + +Tokens are stored in ${tokenStore.tokensFile}. + +This command will prompt for the secret token over stdin. +(Unless `--env-var` is used). + +For interactive authorization against pub.dev, use `$topLevelProgram pub login`.'''; @override - String get invocation => 'pub token add'; + String get argumentsDescription => '[options] <hosted-url>'; + @override - String get argumentsDescription => '[hosted-url]'; + String get docUrl => 'https://dart.dev/tools/pub/cmd/pub-token'; String? get envVar => argResults['env-var']; @@ -32,6 +44,7 @@ 'env-var', help: 'Read the secret token from this environment variable when ' 'making requests.', + valueHelp: 'VARIABLE', ); }
diff --git a/lib/src/command/token_list.dart b/lib/src/command/token_list.dart index 3cf73ee..178d0a4 100644 --- a/lib/src/command/token_list.dart +++ b/lib/src/command/token_list.dart
@@ -12,7 +12,7 @@ @override String get description => 'List servers for which a token exists.'; @override - String get invocation => 'pub token list'; + String get docUrl => 'https://dart.dev/tools/pub/cmd/pub-token'; @override Future<void> runProtected() async {
diff --git a/lib/src/command/token_remove.dart b/lib/src/command/token_remove.dart index 1af2e18..b4a9a77 100644 --- a/lib/src/command/token_remove.dart +++ b/lib/src/command/token_remove.dart
@@ -12,11 +12,12 @@ @override String get name => 'remove'; @override - String get description => 'Remove secret token for package repository.'; + String get description => ''' +Remove secret token for package repository at <hosted-url>.'''; @override - String get invocation => 'pub token remove'; + String get argumentsDescription => '<hosted-url> | --all'; @override - String get argumentsDescription => '[hosted-url]'; + String get docUrl => 'https://dart.dev/tools/pub/cmd/pub-token'; bool get isAll => argResults['all'];
diff --git a/lib/src/io.dart b/lib/src/io.dart index c9230ca..54736c9 100644 --- a/lib/src/io.dart +++ b/lib/src/io.dart
@@ -1156,7 +1156,7 @@ final String? dartConfigDir = () { if (runningFromTest && Platform.environment.containsKey('_PUB_TEST_CONFIG_DIR')) { - return Platform.environment['_PUB_TEST_CONFIG_DIR']; + return path.join(Platform.environment['_PUB_TEST_CONFIG_DIR']!, 'dart'); } try { return applicationConfigHome('dart');
diff --git a/lib/src/oauth2.dart b/lib/src/oauth2.dart index b51fdfb..c729d4c 100644 --- a/lib/src/oauth2.dart +++ b/lib/src/oauth2.dart
@@ -30,8 +30,8 @@ ); /// The pub client's OAuth2 identifier. -const _identifier = '818368855108-8grd2eg9tj9f38os6f1urbcvsq399u8n.apps.' - 'googleusercontent.com'; +const _identifier = + '818368855108-8grd2eg9tj9f38os6f1urbcvsq399u8n.apps.googleusercontent.com'; /// The pub client's OAuth2 secret. ///
diff --git a/test/descriptor.dart b/test/descriptor.dart index be962c1..7f414cc 100644 --- a/test/descriptor.dart +++ b/test/descriptor.dart
@@ -226,8 +226,7 @@ String? refreshToken, DateTime? expiration, }) { - return dir( - configPath, + return configDir( [ file( 'pub-credentials.json', @@ -284,7 +283,7 @@ /// Describes the file in the system cache that contains credentials for /// third party hosted pub servers. Descriptor tokensFile([Map<String, dynamic> contents = const {}]) { - return dir(configPath, [file('pub-tokens.json', jsonEncode(contents))]); + return configDir([file('pub-tokens.json', jsonEncode(contents))]); } /// Describes the application directory, containing only a pubspec specifying
diff --git a/test/help_test.dart b/test/help_test.dart index 110ab84..767aad9 100644 --- a/test/help_test.dart +++ b/test/help_test.dart
@@ -42,7 +42,13 @@ final cmds = _extractCommands([], PubCommandRunner().commands.values); for (final c in cmds) { testWithGolden('pub ${c.join(' ')} --help', (ctx) async { - await ctx.run([...c, '--help']); + await ctx.run( + [...c, '--help'], + environment: { + // Use more columns to avoid unintended line breaking. + '_PUB_TEST_TERMINAL_COLUMNS': '200' + }, + ); }); } }
diff --git a/test/oauth2/logout_test.dart b/test/oauth2/logout_test.dart index 6c835a9..db083ac 100644 --- a/test/oauth2/logout_test.dart +++ b/test/oauth2/logout_test.dart
@@ -21,7 +21,7 @@ await runPub(args: ['logout'], output: contains('Logging out of pub.dev.')); - await d.dir(configPath, [d.nothing('pub-credentials.json')]).validate(); + await configDir([d.nothing('pub-credentials.json')]).validate(); }); test(
diff --git a/test/oauth2/with_a_malformed_credentials_authenticates_again_test.dart b/test/oauth2/with_a_malformed_credentials_authenticates_again_test.dart index 31c68a8..cb5280f 100644 --- a/test/oauth2/with_a_malformed_credentials_authenticates_again_test.dart +++ b/test/oauth2/with_a_malformed_credentials_authenticates_again_test.dart
@@ -16,10 +16,7 @@ await d.validPackage.create(); await servePackages(); - await d.dir( - configPath, - [d.file('pub-credentials.json', '{bad json')], - ).create(); + await configDir([d.file('pub-credentials.json', '{bad json')]).create(); var pub = await startPublish(globalServer); await confirmPublish(pub);
diff --git a/test/test_pub.dart b/test/test_pub.dart index e6aa8cc..e389f29 100644 --- a/test/test_pub.dart +++ b/test/test_pub.dart
@@ -61,6 +61,9 @@ /// sandbox directory. const String configPath = '.config'; +d.DirectoryDescriptor configDir(Iterable<d.Descriptor> contents) => + d.dir(configPath, [d.dir('dart', contents)]); + /// The path of the mock app directory used for tests, relative to the sandbox /// directory. const String appPath = 'myapp'; @@ -952,7 +955,8 @@ // Any paths in output should be relative to the sandbox and with forward // slashes to be stable across platforms. input = input.replaceAll(d.sandbox, r'$SANDBOX'); - input = input.replaceAllMapped(RegExp(r'\\(\S)'), (match) => '/${match[1]}'); + input = + input.replaceAllMapped(RegExp(r'\\(\S|\.)'), (match) => '/${match[1]}'); var port = _globalServer?.port; if (port != null) { input = input.replaceAll(port.toString(), '\$PORT');
diff --git a/test/testdata/goldens/help_test/pub add --help.txt b/test/testdata/goldens/help_test/pub add --help.txt index cc734f1..dfed108 100644 --- a/test/testdata/goldens/help_test/pub add --help.txt +++ b/test/testdata/goldens/help_test/pub add --help.txt
@@ -33,12 +33,10 @@ `dart pub add \ 'foo:{"git":{"url":"../foo.git","ref":"branch","path":"subdir"}}'` -Usage: pub add [options] [dev:]<package>[:descriptor] [[dev:]<package>[:descriptor] - ...] +Usage: pub add [options] [dev:]<package>[:descriptor] [[dev:]<package>[:descriptor] ...] -h, --help Print this usage information. --[no-]offline Use cached packages instead of accessing the network. --n, --dry-run Report what dependencies would change but don't change - any. +-n, --dry-run Report what dependencies would change but don't change any. --[no-]precompile Build executables in immediate dependencies. -C, --directory=<dir> Run this in the directory <dir>.
diff --git a/test/testdata/goldens/help_test/pub downgrade --help.txt b/test/testdata/goldens/help_test/pub downgrade --help.txt index 8e3a24f..483e764 100644 --- a/test/testdata/goldens/help_test/pub downgrade --help.txt +++ b/test/testdata/goldens/help_test/pub downgrade --help.txt
@@ -9,8 +9,7 @@ Usage: pub downgrade [dependencies...] -h, --help Print this usage information. --[no-]offline Use cached packages instead of accessing the network. --n, --dry-run Report what dependencies would change but don't change - any. +-n, --dry-run Report what dependencies would change but don't change any. -C, --directory=<dir> Run this in the directory <dir>. Run "pub help" to see global options.
diff --git a/test/testdata/goldens/help_test/pub get --help.txt b/test/testdata/goldens/help_test/pub get --help.txt index 80a482b..afd27d5 100644 --- a/test/testdata/goldens/help_test/pub get --help.txt +++ b/test/testdata/goldens/help_test/pub get --help.txt
@@ -7,10 +7,8 @@ Usage: pub get <subcommand> [arguments...] -h, --help Print this usage information. --[no-]offline Use cached packages instead of accessing the network. --n, --dry-run Report what dependencies would change but don't change - any. - --enforce-lockfile Enforce pubspec.lock. Fail resolution if pubspec.lock - does not satisfy pubspec.yaml +-n, --dry-run Report what dependencies would change but don't change any. + --enforce-lockfile Enforce pubspec.lock. Fail resolution if pubspec.lock does not satisfy pubspec.yaml --[no-]precompile Build executables in immediate dependencies. -C, --directory=<dir> Run this in the directory <dir>.
diff --git a/test/testdata/goldens/help_test/pub global activate --help.txt b/test/testdata/goldens/help_test/pub global activate --help.txt index 29aab49..75fbc3d 100644 --- a/test/testdata/goldens/help_test/pub global activate --help.txt +++ b/test/testdata/goldens/help_test/pub global activate --help.txt
@@ -12,10 +12,8 @@ --git-ref Git branch or commit to be retrieved --no-executables Do not put executables on PATH. -x, --executable Executable(s) to place on PATH. - --overwrite Overwrite executables from other packages with the same - name. --u, --hosted-url A custom pub server URL for the package. Only applies - when using the `hosted` source. + --overwrite Overwrite executables from other packages with the same name. +-u, --hosted-url A custom pub server URL for the package. Only applies when using the `hosted` source. Run "pub help" to see global options.
diff --git a/test/testdata/goldens/help_test/pub global run --help.txt b/test/testdata/goldens/help_test/pub global run --help.txt index b2d4cf1..df01700 100644 --- a/test/testdata/goldens/help_test/pub global run --help.txt +++ b/test/testdata/goldens/help_test/pub global run --help.txt
@@ -7,10 +7,7 @@ Usage: pub global run <package>:<executable> [args...] -h, --help Print this usage information. --[no-]enable-asserts Enable assert statements. - --enable-experiment=<experiment> Runs the executable in a VM with the - given experiments enabled. (Will disable - snapshotting, resulting in slower - startup). + --enable-experiment=<experiment> Runs the executable in a VM with the given experiments enabled. (Will disable snapshotting, resulting in slower startup). Run "pub help" to see global options.
diff --git a/test/testdata/goldens/help_test/pub outdated --help.txt b/test/testdata/goldens/help_test/pub outdated --help.txt index dc050f6..14e8323 100644 --- a/test/testdata/goldens/help_test/pub outdated --help.txt +++ b/test/testdata/goldens/help_test/pub outdated --help.txt
@@ -12,8 +12,7 @@ (defaults to on) --json Output the results using a json format. --[no-]prereleases Include prereleases in latest version. - --[no-]show-all Include dependencies that are already - fullfilling --mode. + --[no-]show-all Include dependencies that are already fullfilling --mode. --[no-]transitive Show transitive dependencies. -C, --directory=<dir> Run this in the directory <dir>.
diff --git a/test/testdata/goldens/help_test/pub remove --help.txt b/test/testdata/goldens/help_test/pub remove --help.txt index 3d9e6c1..f8da56e 100644 --- a/test/testdata/goldens/help_test/pub remove --help.txt +++ b/test/testdata/goldens/help_test/pub remove --help.txt
@@ -7,8 +7,7 @@ Usage: pub remove <package> -h, --help Print this usage information. --[no-]offline Use cached packages instead of accessing the network. --n, --dry-run Report what dependencies would change but don't change - any. +-n, --dry-run Report what dependencies would change but don't change any. --[no-]precompile Precompile executables in immediate dependencies. -C, --directory=<dir> Run this in the directory <dir>.
diff --git a/test/testdata/goldens/help_test/pub run --help.txt b/test/testdata/goldens/help_test/pub run --help.txt index 0808247..7e81314 100644 --- a/test/testdata/goldens/help_test/pub run --help.txt +++ b/test/testdata/goldens/help_test/pub run --help.txt
@@ -7,10 +7,8 @@ Usage: pub run <executable> [arguments...] -h, --help Print this usage information. --[no-]enable-asserts Enable assert statements. - --enable-experiment=<experiment> Runs the executable in a VM with the - given experiments enabled. - (Will disable snapshotting, resulting in - slower startup). + --enable-experiment=<experiment> Runs the executable in a VM with the given experiments enabled. + (Will disable snapshotting, resulting in slower startup). -C, --directory=<dir> Run this in the directory <dir>. Run "pub help" to see global options.
diff --git a/test/testdata/goldens/help_test/pub token --help.txt b/test/testdata/goldens/help_test/pub token --help.txt index fa164c5..9f29282 100644 --- a/test/testdata/goldens/help_test/pub token --help.txt +++ b/test/testdata/goldens/help_test/pub token --help.txt
@@ -4,13 +4,21 @@ $ pub token --help Manage authentication tokens for hosted pub repositories. +The tokens will be used for authorizing both when retrieving dependencies and +for publishing. + +Tokens are stored in `$SANDBOX/.config/dart/pub-tokens.json`. + +For interactive authorization against pub.dev, use `dart pub login`. + Usage: pub token [arguments...] -h, --help Print this usage information. Available subcommands: - add Add authentication tokens for a package repository. + add Add an authentication token for a package repository. list List servers for which a token exists. - remove Remove secret token for package repository. + remove Remove secret token for package repository at <hosted-url>. Run "pub help" to see global options. +See https://dart.dev/tools/pub/cmd/pub-token for detailed documentation.
diff --git a/test/testdata/goldens/help_test/pub token add --help.txt b/test/testdata/goldens/help_test/pub token add --help.txt index 7068a5c..d3e611d 100644 --- a/test/testdata/goldens/help_test/pub token add --help.txt +++ b/test/testdata/goldens/help_test/pub token add --help.txt
@@ -2,12 +2,22 @@ ## Section 0 $ pub token add --help -Add authentication tokens for a package repository. +Add an authentication token for a package repository. -Usage: pub token add --h, --help Print this usage information. - --env-var Read the secret token from this environment variable when - making requests. +The token will be used for authorizing against <hosted-url> both when +retrieving dependencies and for publishing. + +Tokens are stored in $SANDBOX/.config/dart/pub-tokens.json. + +This command will prompt for the secret token over stdin. +(Unless `--env-var` is used). + +For interactive authorization against pub.dev, use `dart pub login`. + +Usage: pub token add [options] <hosted-url> +-h, --help Print this usage information. + --env-var=<VARIABLE> Read the secret token from this environment variable when making requests. Run "pub help" to see global options. +See https://dart.dev/tools/pub/cmd/pub-token for detailed documentation.
diff --git a/test/testdata/goldens/help_test/pub token list --help.txt b/test/testdata/goldens/help_test/pub token list --help.txt index 5c333b5..d2ed712 100644 --- a/test/testdata/goldens/help_test/pub token list --help.txt +++ b/test/testdata/goldens/help_test/pub token list --help.txt
@@ -4,8 +4,9 @@ $ pub token list --help List servers for which a token exists. -Usage: pub token list +Usage: pub token list <subcommand> [arguments...] -h, --help Print this usage information. Run "pub help" to see global options. +See https://dart.dev/tools/pub/cmd/pub-token for detailed documentation.
diff --git a/test/testdata/goldens/help_test/pub token remove --help.txt b/test/testdata/goldens/help_test/pub token remove --help.txt index 1f79f81..ba06dbe 100644 --- a/test/testdata/goldens/help_test/pub token remove --help.txt +++ b/test/testdata/goldens/help_test/pub token remove --help.txt
@@ -2,11 +2,12 @@ ## Section 0 $ pub token remove --help -Remove secret token for package repository. +Remove secret token for package repository at <hosted-url>. -Usage: pub token remove +Usage: pub token remove <hosted-url> | --all -h, --help Print this usage information. --all Remove all secret tokens. Run "pub help" to see global options. +See https://dart.dev/tools/pub/cmd/pub-token for detailed documentation.
diff --git a/test/testdata/goldens/help_test/pub upgrade --help.txt b/test/testdata/goldens/help_test/pub upgrade --help.txt index af583b8..32b7eea 100644 --- a/test/testdata/goldens/help_test/pub upgrade --help.txt +++ b/test/testdata/goldens/help_test/pub upgrade --help.txt
@@ -7,11 +7,9 @@ Usage: pub upgrade [dependencies...] -h, --help Print this usage information. --[no-]offline Use cached packages instead of accessing the network. --n, --dry-run Report what dependencies would change but don't change - any. +-n, --dry-run Report what dependencies would change but don't change any. --[no-]precompile Precompile executables in immediate dependencies. - --major-versions Upgrades packages to their latest resolvable versions, - and updates pubspec.yaml. + --major-versions Upgrades packages to their latest resolvable versions, and updates pubspec.yaml. -C, --directory=<dir> Run this in the directory <dir>. Run "pub help" to see global options.
diff --git a/test/token/add_token_test.dart b/test/token/add_token_test.dart index bb61bf3..80b9223 100644 --- a/test/token/add_token_test.dart +++ b/test/token/add_token_test.dart
@@ -119,18 +119,18 @@ }); test('with invalid server url returns error', () async { - await d.dir(configPath).create(); + await configDir([]).create(); await runPub( args: ['token', 'add', 'http:;://invalid-url,.com'], error: contains('Invalid [hosted-url]'), exitCode: exit_codes.USAGE, ); - await d.dir(configPath, [d.nothing('pub-tokens.json')]).validate(); + await configDir([d.nothing('pub-tokens.json')]).validate(); }); test('with invalid token returns error', () async { - await d.dir(configPath).create(); + await configDir([]).create(); await runPub( args: ['token', 'add', 'https://pub.dev'], @@ -139,18 +139,18 @@ exitCode: exit_codes.DATA, ); - await d.dir(configPath, [d.nothing('pub-tokens.json')]).validate(); + await configDir([d.nothing('pub-tokens.json')]).validate(); }); test('with non-secure server url returns error', () async { - await d.dir(configPath).create(); + await configDir([]).create(); await runPub( args: ['token', 'add', 'http://mypub.com'], error: contains('insecure repositories cannot use authentication'), exitCode: exit_codes.USAGE, ); - await d.dir(configPath, [d.nothing('pub-tokens.json')]).validate(); + await configDir([d.nothing('pub-tokens.json')]).validate(); }); test(
diff --git a/test/token/remove_token_test.dart b/test/token/remove_token_test.dart index df880a4..06ec38e 100644 --- a/test/token/remove_token_test.dart +++ b/test/token/remove_token_test.dart
@@ -57,7 +57,7 @@ await runPub(args: ['token', 'remove', '--all']); - await d.dir(configPath, [d.nothing('pub-tokens.json')]).validate(); + await configDir([d.nothing('pub-tokens.json')]).validate(); }); test('with empty environment gives error message', () async {