dash_cli.dart

// Copyright (c) 2025, 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 'dart:convert';

import 'package:dart_mcp/server.dart';
import 'package:path/path.dart' as p;

import '../utils/cli_utils.dart';
import '../utils/constants.dart';
import '../utils/file_system.dart';
import '../utils/process_manager.dart';
import '../utils/sdk.dart';

/// Mix this in to any MCPServer to add support for running Dart or Flutter CLI
/// commands like `dart fix`, `dart format`, and `flutter test`.
///
/// The MCPServer must already have the [ToolsSupport] and [LoggingSupport]
/// mixins applied.
base mixin DashCliSupport on ToolsSupport, LoggingSupport, RootsTrackingSupport
    implements ProcessManagerSupport, FileSystemSupport, SdkSupport {
  @override
  FutureOr<InitializeResult> initialize(InitializeRequest request) {
    try {
      return super.initialize(request);
    } finally {
      // Can't call `supportsRoots` until after `super.initialize`.
      if (supportsRoots && sdk.dartSdkPath != null) {
        registerTool(dartFixTool, _runDartFixTool);
        registerTool(dartFormatTool, _runDartFormatTool);
        registerTool(runTestsTool, _runTests);
        registerTool(createProjectTool, _runCreateProjectTool);
      }
    }
  }

  /// Implementation of the [dartFixTool].
  Future<CallToolResult> _runDartFixTool(CallToolRequest request) async {
    return runCommandInRoots(
      request,
      commandForRoot: (_, _, sdk) => sdk.dartExecutablePath,
      arguments: ['fix', '--apply'],
      commandDescription: 'dart fix',
      processManager: processManager,
      knownRoots: await roots,
      fileSystem: fileSystem,
      sdk: sdk,
    );
  }

  /// Implementation of the [dartFormatTool].
  Future<CallToolResult> _runDartFormatTool(CallToolRequest request) async {
    return runCommandInRoots(
      request,
      commandForRoot: (_, _, sdk) => sdk.dartExecutablePath,
      arguments: ['format'],
      commandDescription: 'dart format',
      processManager: processManager,
      defaultPaths: ['.'],
      knownRoots: await roots,
      fileSystem: fileSystem,
      sdk: sdk,
    );
  }

  /// Implementation of the [runTestsTool].
  Future<CallToolResult> _runTests(CallToolRequest request) async {
    final testRunnerArguments =
        request.arguments?[ParameterNames.testRunnerArgs]
            as Map<String, Object?>?;
    final hasReporterArg =
        testRunnerArguments?.containsKey('reporter') ?? false;
    return runCommandInRoots(
      request,
      arguments: [
        'test',
        if (!hasReporterArg) '--reporter=failures-only',
        ...?testRunnerArguments?.asCliArgs(),
      ],
      commandDescription: 'dart|flutter test',
      processManager: processManager,
      knownRoots: await roots,
      fileSystem: fileSystem,
      sdk: sdk,
    );
  }

  /// Implementation of the [createProjectTool].
  Future<CallToolResult> _runCreateProjectTool(CallToolRequest request) async {
    final args = request.arguments;

    final errors = createProjectTool.inputSchema.validate(args);
    final projectType = args?[ParameterNames.projectType] as String?;
    if (projectType != 'dart' && projectType != 'flutter') {
      errors.add(
        ValidationError(
          ValidationErrorType.itemInvalid,
          path: [ParameterNames.projectType],
          details: 'Only `dart` and `flutter` are allowed values.',
        ),
      );
    }
    final directory = args![ParameterNames.directory] as String;
    if (p.isAbsolute(directory)) {
      errors.add(
        ValidationError(
          ValidationErrorType.itemInvalid,
          path: [ParameterNames.directory],
          details: 'Directory must be a relative path.',
        ),
      );
    }
    final platforms =
        ((args[ParameterNames.platform] as List?)?.cast<String>() ?? [])
            .toSet();
    if (projectType == 'flutter') {
      // Platforms are ignored for Dart, so no need to validate them.
      final invalidPlatforms = platforms.difference(_allowedFlutterPlatforms);
      if (invalidPlatforms.isNotEmpty) {
        final plural =
            invalidPlatforms.length > 1
                ? 'are not valid platforms'
                : 'is not a valid platform';
        errors.add(
          ValidationError(
            ValidationErrorType.itemInvalid,
            path: [ParameterNames.platform],
            details:
                '${invalidPlatforms.join(',')} $plural. Platforms '
                '${_allowedFlutterPlatforms.map((e) => '`$e`').join(', ')} '
                'are the only allowed values for the platform list argument.',
          ),
        );
      }
    }

    if (errors.isNotEmpty) {
      return CallToolResult(
        content: [
          for (final error in errors) Content.text(text: error.toErrorString()),
        ],
        isError: true,
      );
    }

    final template = args[ParameterNames.template] as String?;

    final commandArgs = [
      'create',
      if (template != null && template.isNotEmpty) ...['--template', template],
      if (projectType == 'flutter' && platforms.isNotEmpty)
        '--platform=${platforms.join(',')}',
      // Create an "empty" project by default so the LLM doesn't have to deal
      // with all the boilerplate and comments.
      if (projectType == 'flutter' &&
          (args[ParameterNames.empty] as bool? ?? true))
        '--empty',
      directory,
    ];

    return runCommandInRoot(
      request,
      arguments: commandArgs,
      commandForRoot:
          (_, _, sdk) =>
              switch (projectType) {
                    'dart' => sdk.dartExecutablePath,
                    'flutter' => sdk.flutterExecutablePath,
                    _ => StateError('Unknown project type: $projectType'),
                  }
                  as String,
      commandDescription: '$projectType create',
      fileSystem: fileSystem,
      processManager: processManager,
      knownRoots: await roots,
      sdk: sdk,
    );
  }

  static final dartFixTool = Tool(
    name: 'dart_fix',
    description: 'Runs `dart fix --apply` for the given project roots.',
    annotations: ToolAnnotations(title: 'Dart fix', destructiveHint: true),
    inputSchema: Schema.object(
      properties: {ParameterNames.roots: rootsSchema()},
    ),
  );

  static final dartFormatTool = Tool(
    name: 'dart_format',
    description: 'Runs `dart format .` for the given project roots.',
    annotations: ToolAnnotations(title: 'Dart format', destructiveHint: true),
    inputSchema: Schema.object(
      properties: {ParameterNames.roots: rootsSchema(supportsPaths: true)},
    ),
  );

  static final Tool runTestsTool = () {
    final cliSchemaJson =
        jsonDecode(_dartTestCliSchema) as Map<String, Object?>;
    const blocklist = {'color', 'debug', 'help', 'pause-after-load', 'version'};
    cliSchemaJson.removeWhere((argument, _) => blocklist.contains(argument));
    final cliSchema = Schema.fromMap(cliSchemaJson);
    return Tool(
      name: 'run_tests',
      description:
          'Run Dart or Flutter tests with an agent centric UX. '
          'ALWAYS use instead of `dart test` or `flutter test` shell commands.',
      annotations: ToolAnnotations(title: 'Run tests', readOnlyHint: true),
      inputSchema: Schema.object(
        properties: {
          ParameterNames.roots: rootsSchema(supportsPaths: true),
          ParameterNames.testRunnerArgs: cliSchema,
        },
      ),
    );
  }();

  static final createProjectTool = Tool(
    name: 'create_project',
    description: 'Creates a new Dart or Flutter project.',
    annotations: ToolAnnotations(
      title: 'Create project',
      destructiveHint: true,
    ),
    inputSchema: Schema.object(
      properties: {
        ParameterNames.root: rootSchema,
        ParameterNames.directory: Schema.string(
          description:
              'The subdirectory in which to create the project, must '
              'be a relative path.',
        ),
        ParameterNames.projectType: Schema.string(
          description: "The type of project: 'dart' or 'flutter'.",
        ),
        ParameterNames.template: Schema.string(
          description:
              'The project template to use (e.g., "console-full", "app").',
        ),
        ParameterNames.platform: Schema.list(
          items: Schema.string(),
          description:
              'The list of platforms this project supports. Only valid '
              'for Flutter projects. The allowed values are '
              '${_allowedFlutterPlatforms.map((e) => '`$e`').join(', ')}. '
              'Defaults to creating a project for all platforms.',
        ),
        ParameterNames.empty: Schema.bool(
          description:
              'Whether or not to create an "empty" project with minimized '
              'boilerplate and example code. Defaults to true.',
        ),
      },
      required: [ParameterNames.directory, ParameterNames.projectType],
    ),
  );

  static const _allowedFlutterPlatforms = {
    'web',
    'linux',
    'macos',
    'windows',
    'android',
    'ios',
  };
}

extension on Map<String, Object?> {
  Iterable<String> asCliArgs() sync* {
    for (final MapEntry(:key, :value) in entries) {
      if (value is List) {
        for (final element in value) {
          yield '--$key';
          yield element as String;
        }
        continue;
      }
      yield '--$key';
      if (value is bool) continue;
      yield value as String;
    }
  }
}

// Generated by the test runner using an un-merged commit.
// To update merge the latest argument changes to the `json-schema` branch and
// run with the `--json-help` argument. Pipe to `sed 's/\\/\\\\/g'` to escape
// as a Dart source string.
// https://github.com/dart-lang/test/pull/2508
const _dartTestCliSchema = '''
{"type":"object","properties":{"help":{"type":"boolean","description":"Show this usage information.\\ndefaults to \\"false\\""},"version":{"type":"boolean","description":"Show the package:test version.\\ndefaults to \\"false\\""},"name":{"type":"array","description":"A substring of the name of the test to run.\\nRegular expression syntax is supported.\\nIf passed multiple times, tests must match all substrings.\\ndefaults to \\"[]\\"","items":{"type":"string"}},"plain-name":{"type":"array","description":"A plain-text substring of the name of the test to run.\\nIf passed multiple times, tests must match all substrings.\\ndefaults to \\"[]\\"","items":{"type":"string"}},"tags":{"type":"array","description":"Run only tests with all of the specified tags.\\nSupports boolean selector syntax.\\ndefaults to \\"[]\\"","items":{"type":"string"}},"exclude-tags":{"type":"array","description":"Don't run tests with any of the specified tags.\\nSupports boolean selector syntax.\\ndefaults to \\"[]\\"","items":{"type":"string"}},"run-skipped":{"type":"boolean","description":"Run skipped tests instead of skipping them.\\ndefaults to \\"false\\""},"platform":{"type":"array","description":"The platform(s) on which to run the tests.\\n[vm (default), chrome, firefox, edge, node].\\nEach platform supports the following compilers:\\n[vm]: kernel (default), source, exe\\n[chrome]: dart2js (default), dart2wasm\\n[firefox]: dart2js (default), dart2wasm\\n[edge]: dart2js (default)\\n[node]: dart2js (default), dart2wasm\\ndefaults to \\"[]\\"","items":{"type":"string"}},"compiler":{"type":"array","description":"The compiler(s) to use to run tests, supported compilers are [dart2js, dart2wasm, exe, kernel, source].\\nEach platform has a default compiler but may support other compilers.\\nYou can target a compiler to a specific platform using arguments of the following form [<platform-selector>:]<compiler>.\\nIf a platform is specified but no given compiler is supported for that platform, then it will use its default compiler.\\ndefaults to \\"[]\\"","items":{"type":"string"}},"preset":{"type":"array","description":"The configuration preset(s) to use.\\ndefaults to \\"[]\\"","items":{"type":"string"}},"concurrency":{"type":"string","description":"The number of concurrent test suites run.\\ndefaults to \\"8\\""},"total-shards":{"type":"string","description":"The total number of invocations of the test runner being run."},"shard-index":{"type":"string","description":"The index of this test runner invocation (of --total-shards)."},"timeout":{"type":"string","description":"The default test timeout. For example: 15s, 2x, none\\ndefaults to \\"30s\\""},"ignore-timeouts":{"type":"boolean","description":"Ignore all timeouts (useful if debugging)\\ndefaults to \\"false\\""},"pause-after-load":{"type":"boolean","description":"Pause for debugging before any tests execute.\\nImplies --concurrency=1, --debug, and --ignore-timeouts.\\nCurrently only supported for browser tests.\\ndefaults to \\"false\\""},"debug":{"type":"boolean","description":"Run the VM and Chrome tests in debug mode.\\ndefaults to \\"false\\""},"coverage":{"type":"string","description":"Gather coverage and output it to the specified directory.\\nImplies --debug."},"chain-stack-traces":{"type":"boolean","description":"Use chained stack traces to provide greater exception details\\nespecially for asynchronous code. It may be useful to disable\\nto provide improved test performance but at the cost of\\ndebuggability.\\ndefaults to \\"false\\""},"no-retry":{"type":"boolean","description":"Don't rerun tests that have retry set.\\ndefaults to \\"false\\""},"test-randomize-ordering-seed":{"type":"string","description":"Use the specified seed to randomize the execution order of test cases.\\nMust be a 32bit unsigned integer or \\"random\\".\\nIf \\"random\\", pick a random seed to use.\\nIf not passed, do not randomize test case execution order."},"fail-fast":{"type":"boolean","description":"Stop running tests after the first failure.\\n\\ndefaults to \\"false\\""},"reporter":{"type":"string","description":"Set how to print test results.\\ndefaults to \\"compact\\"\\nallowed values: compact, expanded, failures-only, github, json, silent"},"file-reporter":{"type":"string","description":"Enable an additional reporter writing test results to a file.\\nShould be in the form <reporter>:<filepath>, Example: \\"json:reports/tests.json\\""},"verbose-trace":{"type":"boolean","description":"Emit stack traces with core library frames.\\ndefaults to \\"false\\""},"js-trace":{"type":"boolean","description":"Emit raw JavaScript stack traces for browser tests.\\ndefaults to \\"false\\""},"color":{"type":"boolean","description":"Use terminal colors.\\n(auto-detected by default)\\ndefaults to \\"false\\""}},"required":[]}
''';