tom_build_base_v2 library

tom_build_base v2 - Unified CLI framework for workspace traversal.

This library provides:

Structured traversal configuration (TraversalInfo)
Automatic folder scanning and nature detection
Filter pipelines for flexible project selection
Type-safe command context (CommandContext)

Quick Start

import 'package:tom_build_base/tom_build_base_v2.dart';

void main() async {
  await BuildBase.traverse(
    info: ProjectTraversalInfo(
      scan: '.',
      recursive: true,
      executionRoot: Directory.current.path,
    ),
    run: (ctx) async {
      print('Processing: ${ctx.name}');
      return true;
    },
  );
}

Classes

AnchorWalker: Walks up the directory tree to find "anchor" directories.
AnsiColors: ANSI color codes for terminal output.
BaseTraversalInfo: Base class for traversal configuration.
BuildBase: Main entry point for workspace traversal.
BuildkitFolder: Buildkit configuration nature.
BuildOrderComputer: Computes build order for Dart projects using topological sort.
BuildRunnerFolder: Build runner (build.yaml) nature.
CallbackExecutor: Callback-based command executor.
CliArgParser: Parser for command-line arguments.
CliArgs: Parsed command-line arguments.
CommandContext: Context provided to commands during execution.
CommandDefinition: Definition of a command within a multi-command tool.
CommandExecutor: Base class for command executors.
CompletionGenerator: Generates shell completion scripts from tool definitions.
DartConsoleFolder: Dart console application nature.
DartExecutor: Executor that invokes a Dart function for each project.
DartPackageFolder: Dart package nature (library).
DartProjectFolder: Base class for Dart project natures.
FilterPipeline: Applies filters to folder lists based on TraversalInfo configuration.
FlutterProjectFolder: Flutter project nature.
FolderScanner: Scans directories and builds a list of FsFolders.
FolderSorter: Sorts folders based on traversal configuration.
FsFolder: Filesystem folder during scanning (minimal info).
GitFolder: Git repository nature.
GitRepoFinder: Finds git repositories under a given root.
GitTraversalInfo: Configuration for git repository traversal.
HelpGenerator: Generates help text from tool and command definitions.
ItemResult: Result for a single processed item (folder/project).
ListExecutor: No-op executor that just lists folders.
NatureDetector: Detects and creates folder natures based on filesystem markers.
NavigationFeatures: Navigation features supported by a tool.
OptionDefinition: Definition of a CLI option.
PerCommandArgs: Per-command arguments for multi-command tools.
ProcessingResult: Result of a traversal operation.
ProjectTraversalInfo: Configuration for project-based traversal.
RepositoryIdLookup: Lookup table for repository IDs.
RunFolder: Base class for folder natures detected during execution.
ShellExecutor: Executor that runs a shell command in each folder.
SyncExecutor: Synchronous callback-based executor.
TomBuildFolder: Tom project configuration nature.
TomBuildMasterFolder: Tom build master configuration nature.
ToolDefinition: Definition of a CLI tool for buildkit and similar applications.
ToolResult: Result of running a tool or command.
ToolRunner: Runs tools based on their definitions.
TraversalDefaults: Traversal defaults loaded from buildkit_master.yaml navigation section.
TypeScriptFolder: TypeScript project nature.
VsCodeExtensionFolder: VS Code extension nature.
WorkspaceNavigationArgs: Parsed navigation options for workspace traversal.

Enums

ExecutionMode: Represents the execution mode for a tool.
GitTraversalMode: Git traversal order mode.
GitTraversalOrder: Git traversal order when both inner-first and outer-first are valid.
OptionType: Type of option value.
ShellType: Shell type for completion scripts.
SpecialCommandResult: Result of checking for special commands.
ToolMode: Mode in which a tool can operate.

Extensions

ToolDefinitionCompletion on ToolDefinition: Extension to generate completions.

Constants

commonOptions → const List<OptionDefinition>: Common options for all tools.
gitTraversalOptions → const List<OptionDefinition>: Standard options for git traversal.
kBuildkitMasterYaml → const String: Constants for workspace configuration files.
kBuildkitSkipYaml → const String
kTomCodeWorkspace → const String
kTomSkipYaml → const String: Global skip file that blocks all tools.
kTomWorkspaceYaml → const String
projectTraversalOptions → const List<OptionDefinition>: Standard options for project traversal.

Functions

addNavigationOptions(ArgParser parser) → void: Adds the following options:
expandMacros(List<String> args, Map<String, String> macros) → List<String>: Expand macros in argument list.
findWorkspaceRoot(String startPath) → String: Find the workspace root by traversing upwards looking for workspace markers.
generatePlainCommandHelp(ToolDefinition tool, CommandDefinition cmd) → String: Generate plain-text help for a command (no ANSI colors).
generatePlainToolHelp(ToolDefinition tool) → String: Generate plain-text tool help (no ANSI colors).
getExecutionModesHelpLines() → List<String>: Returns just the execution modes explanation.
getNavigationOptionsHelpLines() → List<String>: Returns the standard navigation options help text.
getRequiredArgCount(String macroValue) → int: Get the number of required arguments for a macro.
getToolHelpFooter({String? toolName}) → List<String>: Generates the standard footer for help output.
getToolHelpHeader({required String toolName, required String toolDescription, required List<String> usagePatterns}) → List<String>: Generates a complete help header for a Tom build tool.
handleSpecialCommands(List<String> args, ToolDefinition tool, {void printer(String)?, String toolHelpGenerator(ToolDefinition)?, String commandHelpGenerator(ToolDefinition, CommandDefinition)?, String versionGenerator(ToolDefinition)?}) → SpecialCommandResult: Check for and handle special commands (help, version).
isHelpCommand(List<String> args) → bool: Check if the first argument is a help command.
isVersionCommand(List<String> args) → bool: Check if the first argument is a version command.
isWorkspaceBoundary(String dirPath) → bool: Check if a directory is a workspace boundary (contains buildkit_master.yaml).
parseNavigationArgs(ArgResults results, {bool bareRoot = false}) → WorkspaceNavigationArgs: Parse navigation options from ArgResults.
preprocessRootFlag(List<String> args) → (List<String>, bool): Preprocess command-line arguments to handle special -R behavior.
printExecutionModesHelp() → void: Prints just the execution modes explanation to stdout.
printNavigationOptionsHelp() → void: Prints the navigation options help text to stdout.
resolveExecutionRoot(WorkspaceNavigationArgs navArgs, {required String currentDir}) → String: Determine the execution root based on navigation args.

Exceptions / Errors

MacroExpansionException: Exception thrown when macro expansion fails.

tom_build_base_v2 library

Quick Start

Classes

Enums

Extensions

Constants

Functions

Exceptions / Errors

tom_build_base package

tom_build_base_v2 library