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 {
