lib/pub.dart

// Copyright (c) 2012, 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' show StreamSink;

import 'package:args/command_runner.dart';
import 'package:file/file.dart' as f;
import 'package:http/http.dart' as http;

import 'src/entrypoint.dart';
import 'src/exceptions.dart';
import 'src/http.dart';
import 'src/io.dart';
import 'src/progress.dart';
import 'src/pub_embeddable_command.dart';
import 'src/solver/report.dart';
import 'src/source/git.dart';
import 'src/system_cache.dart';

export 'src/executable.dart'
    show
        CommandResolutionFailedException,
        CommandResolutionIssue,
        DartExecutableWithPackageConfig,
        getExecutableForCommand;
export 'src/progress.dart' show ProgressGracePeriod, withProgressGracePeriod;
export 'src/solver/report.dart' show SolveReportMode;

/// Returns a [Command] for pub functionality that can be used by an embedding
/// CommandRunner.
///
/// [isVerbose] should return `true` (after argument resolution) if the
/// embedding top-level is in verbose mode.
///
/// [progressGracePeriod] specifies the shared grace period before initial
/// spinners are displayed.
Command<int> pubCommand({
  required bool Function() isVerbose,
  String category = '',
  ProgressGracePeriod? progressGracePeriod,
  f.FileSystem? fileSystem,
  Map<String, String>? environment,
  String? platformVersion,
  Stream<List<int>>? stdin,
  StreamSink<List<int>>? stdout,
  StreamSink<List<int>>? stderr,
  http.Client? httpClient,
}) => withOverrides(
  () => PubEmbeddableCommand(
    isVerbose,
    category,
    fileSystem: fileSystem,
    environment: environment,
    platformVersion: platformVersion,
    stdin: stdin,
    stdout: stdout,
    stderr: stderr,
    httpClient: httpClient,
    progressGracePeriod: progressGracePeriod,
  ),
  progressGracePeriod: progressGracePeriod,
  fileSystem: fileSystem,
  environment: environment,
  platformVersion: platformVersion,
  stdin: stdin,
  stdout: stdout,
  stderr: stderr,
  httpClient: httpClient,
);

/// Makes sure that [dir]/pubspec.yaml is resolved such that pubspec.lock and
/// .dart_tool/package_config.json are up-to-date and all packages are
/// downloaded to the cache.
///
/// Will compare file timestamps to see if full resolution can be skipped.
///
/// [reportMode] specifies the level of reporting output on success. Defaults
/// to [SolveReportMode.none] (no output).
///
/// If [onlyOutputWhenTerminal] is `true` (the default) there will be no
/// output if no terminal is attached.
///
/// [progressGracePeriod] specifies the shared grace period before initial
/// spinners are displayed.
///
/// Throws a [ResolutionFailedException] if resolution fails.
Future<void> ensurePubspecResolved(
  String dir, {
  bool isOffline = false,
  SolveReportMode reportMode = SolveReportMode.none,
  bool onlyOutputWhenTerminal = true,
  ProgressGracePeriod? progressGracePeriod,
  f.FileSystem? fileSystem,
  Map<String, String>? environment,
  String? platformVersion,
  Stream<List<int>>? stdin,
  StreamSink<List<int>>? stdout,
  StreamSink<List<int>>? stderr,
  http.Client? httpClient,
}) => withOverrides(
  () async {
    try {
      await Entrypoint.ensureUpToDate(
        dir,
        cache: SystemCache(isOffline: isOffline),
        reportMode: reportMode,
        onlyOutputWhenTerminal: onlyOutputWhenTerminal,
      );
    } on ApplicationException catch (e) {
      throw ResolutionFailedException._(e.toString());
    } finally {
      // TODO(https://github.com/dart-lang/pub/issues/4200)
      // This is a bit of a hack.
      // We should most likely take a client here.
      globalHttpClient.close();
    }
  },
  progressGracePeriod: progressGracePeriod,
  fileSystem: fileSystem,
  environment: environment,
  platformVersion: platformVersion,
  stdin: stdin,
  stdout: stdout,
  stderr: stderr,
  httpClient: httpClient,
);

/// Exception thrown when package resolution fails in [ensurePubspecResolved].
final class ResolutionFailedException implements Exception {
  final String message;
  ResolutionFailedException._(this.message);

  @override
  String toString() => message;
}

/// Given a Git repo that contains a pub package, gets the name of the pub
/// package.
///
/// Will download the repo to the system cache under the assumption that the
/// package will be downloaded afterwards.
///
/// [url] points to the git repository. If it is a relative url, it is resolved
/// as a file url relative to the path [relativeTo].
///
/// [ref] is the commit, tag, or branch name where the package should be looked
/// up when fetching the name. If omitted, 'HEAD' is used.
///
/// [tagPattern] is a string containing `'{{version}}'` as a substring, the
/// latest tag matching the pattern will be used for fetching the name.
///
/// Only one of [ref] and [tagPattern] can be used.
///
/// If [isOffline], only the already cached versions of the repo is used.
Future<String> getPackageNameFromGitRepo(
  String url, {
  String? ref,
  String? path,
  String? tagPattern,
  String? relativeTo,
  bool isOffline = false,
}) async {
  return await GitSource.instance.getPackageNameFromRepo(
    url,
    ref,
    path,
    SystemCache(isOffline: isOffline),
    relativeTo: relativeTo,
    tagPattern: tagPattern,
  );
}