autocomplete 1.0.0

Fig-style CLI completion specs and runtime (parse command, load spec, get suggestions). Pure Dart

autocomplete (Dart)

中文文档

This project is a pure Dart translation and port of withfig/autocomplete.

All completion specifications (Specs) data structures, core logic, and the Runtime have been directly ported from the withfig/autocomplete and microsoft/inshellisense repositories, aiming to provide command-line autocomplete capabilities completely consistent with the original for the Dart ecosystem.

This is a pure Dart library that does not depend on Flutter and can be used in any Dart project. It contains:

1. Specs: Completion specification data converted from TypeScript.
2. Runtime: The core logic for parsing command-line input, loading specifications, and generating suggestions.

• SDK Requirements: >=2.17.0 <4.0.0
• Specs: Pure data definitions (e.g., cd, ls, git, tree). Currently contains some common commands; more specs will be added continuously.
• Runtime: Reference implementation based on microsoft/inshellisense (including parser, spec loading, subcommand/argument/option handling, templates, etc.).

Usage

import 'package:autocomplete/autocomplete.dart';
import 'dart:io';

void main() async {
  // 1. Register built-in completion specs (cd, ls, git, tree, etc.)
  registerBuiltinSpecs();

  // 2. Provide your own adapter implementation.
  // See example/local_adapter.dart for a local dart:io version.
  final adapter = MyCompleteAdapter();

  // 3. Get completion suggestions
  // Arguments: input command string, current working directory, Shell type
  final blob = await getSuggestions(
    'git sta',
    Directory.current.path,
    Shell.bash,
    adapter,
  );

  // blob.suggestions is a list containing suggestion items (Suggestion)
  // e.g.: [Suggestion(name: 'status', ...)]
  if (blob != null) {
    for (final suggestion in blob.suggestions) {
      print('${suggestion.name} - ${suggestion.description}');
    }
  }
}

Streamed suggestions

Keep the simple getSuggestions(...) usage above for one-shot completion. If you want incremental updates for terminal-style UIs, use requestSuggestions(...):

import 'dart:io';

import 'package:autocomplete/autocomplete.dart';

void main() async {
  registerBuiltinSpecs();
  final adapter = MyCompleteAdapter();

  final engine = AutocompleteEngine(
    adapter: adapter,
  );

  final handle = engine.requestSuggestions(
    'git co ',
    Directory.current.path,
    Shell.zsh,
    timeout: const Duration(milliseconds: 1500),
    mode: SuggestionRequestMode.staticThenFinal,
  );

  await for (final event in handle.stream) {
    print('event: ${event.kind}');
    if (event.blob != null) {
      for (final suggestion in event.blob!.suggestions.take(5)) {
        print('  ${suggestion.name}');
      }
    }
  }

  final result = await handle.done;
  print('final suggestions: ${result?.suggestions.length ?? 0}');
  engine.dispose();
}

See example/local_adapter.dart for a local dart:io adapter, and example/stream_suggest_v2.dart for a fuller example with live terminal rendering and event logging.

Layout

• lib/src/: Core logic, including spec models, generators, registry, parser, runtime, templates, and suggestion objects.
• lib/specs/: Completion spec files, where each command corresponds to a Dart file (e.g., cd.dart, ls.dart).
  • all_specs_v2.dart: The default v2 deferred-loading registry used by registerBuiltinSpecs().
  • all_specs.dart: Eagerly imports all specs and can be used when you want everything loaded up front.
• assets/icons/: Icons/Logos referenced by specs.
  • TypeScript sources usually use URLs or Data URIs; here we store them as files so Flutter apps can bundle and use them. See assets/icons/README.md.
• example/run_suggest_v2.dart: Recommended one-shot completion example for 1.0.0.
• example/stream_suggest_v2.dart: Recommended streamed / incremental completion example for 1.0.0.
• example/example.dart: Minimal compatibility example.

Run Example

Run from the dart/ directory:

dart run example/run_suggest_v2.dart "git sta"

Or specify a Shell:

dart run example/run_suggest_v2.dart "cd " --shell zsh

For the v2 stream / incremental mode:

dart run example/stream_suggest_v2.dart "git ch"
dart run example/stream_suggest_v2.dart "cd " --shell zsh
dart run example/stream_suggest_v2.dart "git co " --live

Contributing

We warmly welcome contributions to this project! As this is a massive porting effort, we greatly need help from the community.

1. Fixing Specs

Most current Dart Spec files (located in lib/specs/) are batch converted from TypeScript via scripts.

• Existing Issues: Due to limitations in automated conversion, some complex Spec logic, types, or parameters may contain errors or omissions.
• How to Help: If you find that completion for a command is inaccurate or causes errors during use, please feel free to modify the corresponding lib/specs/<command>.dart file directly and submit a PR. Manual proofreading and fixes are highly appreciated!

2. Tools

If you see a tools/ directory in the repository (or related scripts in the root), they are typically used for:

• Batch Conversion: Converting upstream TS Specs to Dart code.
• List Generation: Scanning and generating index files like all_specs_v2.dart.
• Validation: Checking the syntax and structural correctness of Spec files. Detailed usage instructions can be found in the comments at the top of each script file.

3. Adding a new spec

1. Add a <command>.dart file under lib/specs/ defining a FigSpec (e.g., const FigSpec myCommandSpec = ...).
2. In lib/specs/all_specs_v2.dart:
   • Add import '<command>.dart';
   • Add the registration entry for <command> so it can be loaded by the default v2 registry.

Acknowledgements

This project is the result of open-source community collaboration. Special thanks to the following projects for providing inspiration, spec data, and reference implementations:

• withfig/autocomplete (MIT License): The primary source of completion spec data (Specs) for this project.
• microsoft/inshellisense (MIT License): The reference for the runtime logic (Runtime) and parser design from its TypeScript implementation.
• withfig/autocomplete-tools: Provided tools and definition references regarding Spec structure.

Thanks to all developers who have contributed to these open-source projects!

F&Q (Common Issues)

1. Why is some command completion inaccurate?

• This may be due to errors during the automated conversion process. The automated conversion script cannot cover all complex TypeScript logic.

• You can directly modify the corresponding Dart file to correct the error.

2. Why is some completion suggestions placed in directories like dart_aws/, dart_az/, dart_gcloud/, and dart_xxx/?

• Due to limitations of pub.dev, the completion content for these commands is too extensive, resulting in a large project size exceeding 100MB (uncompressed).

• Therefore, this code is not currently included in the project and cannot be accessed at present. It will be released as a separate package later.

3. Why is the implementation of the local adapter placed in the ./example directory?

• Because the local adapter uses dart:io, which is not included to allow this project to be cross-platform (web). But I've defined the interface, and you can implement it yourself according to your needs, or you can directly copy the code from the example.