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.
ConsoleMarkdownSink: A StringSink that applies .toConsole() to every line written.
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.
ExecutePlaceholderContext: Context for resolving execute command placeholders.
ExecutePlaceholderResolver: Resolves placeholders in command strings for execute commands.
FilterPipeline: Applies filters to folder lists based on TraversalInfo configuration.
FlutterProjectFolder: Flutter project nature.
FolderContext: A scanned folder with its detected natures.
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.
HelpTopic: A named help topic that can be shown via tool help <name>.
ItemResult: Result for a single processed item (folder/project).
ListExecutor: No-op executor that just lists folders.
MkLinkExecutor: Generic cross-platform symbolic-link executor.
NatureDetector: Detects and creates folder natures based on filesystem markers.
NavigationFeatures: Navigation features supported by a tool.
NestedToolExecutor: Executor that delegates to an external tool binary.
OptionDefinition: Definition of a CLI option.
PerCommandArgs: Per-command arguments for multi-command tools.
PipelineCommandPrefixParser
PipelineCommandSpec
PipelineDefinition
PipelineOptionResolver
PipelineStepConfig
ProcessingResult: Result of a traversal operation.
ProjectTraversalInfo: Configuration for project-based traversal.
RepositoryIdLookup: Lookup helper for repository IDs.
RunFolder: Base class for folder natures detected during execution.
ScanResults: Result of workspace scanning with nature detection.
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.
ToolDefinitionSerializer: Serializes a ToolDefinition tree to YAML format.
ToolPipelineConfig
ToolPipelineConfigLoader
ToolPipelineExecutor
ToolResult: Result of running a tool or command.
ToolRunner: Runs tools based on their definitions.
ToolWiringEntry: Describes how a nested tool is wired into a host tool.
TraversalDefaults: Traversal defaults loaded from buildkit_master.yaml navigation section.
TypeScriptFolder: TypeScript project nature.
VsCodeExtensionFolder: VS Code extension nature.
WiringLoader: Loads and resolves nested tool wiring for a host tool.
WiringResult: Result of loading and resolving wired tool definitions.
WorkspaceNavigationArgs: Parsed navigation options for workspace traversal.
WorkspaceScanner: Scans workspace directories and detects folder natures.

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.
PipelineCommandPrefix
ShellType: Shell type for completion scripts.
SpecialCommandResult: Result of checking for special commands.
ToolMode: Mode in which a tool can operate.
WiringMode: Mode for how a nested tool is wired into a host tool.

Extensions

CommandListOps on List<CommandDefinition>: Extension methods for manipulating command lists.
ToolDefinitionCompletion on ToolDefinition: Extension to generate completions.

Constants

commonOptions → const List<OptionDefinition>: Common options for all tools.
defaultHelpTopics → const List<HelpTopic>: All built-in help topics that apply to every tool.
definesHelpTopic → const HelpTopic: Help topic documenting the defines system.
gitTraversalOptions → const List<OptionDefinition>: Standard options for git traversal.
kAlwaysSkipDirectories → const Set<String>: Directories that should always be skipped during recursive scanning.
kBuildkitMasterYaml → const String: Filename for the workspace-level buildkit configuration.
kBuildkitSkipYaml → const String: Filename for the buildkit skip marker.
kConsoleMarkdownZoneKey → const Symbol: Zone-local key that indicates console_markdown rendering is active.
kTomCodeWorkspace → const String: Filename for the VS Code workspace file.
kTomSkipYaml → const String: Filename for the global skip marker (all tools).
macrosHelpTopic → const HelpTopic: Help topic documenting the macro system.
masterYamlHelpTopics → const List<HelpTopic>: Help topics for tools that use a {tool}_master.yaml configuration file.
pipelinesHelpTopic → const HelpTopic: Help topic documenting pipeline configuration.
placeholdersHelpTopic → const HelpTopic: Help topic documenting placeholder and environment variable usage.
projectTraversalOptions → const List<OptionDefinition>: Standard options for project traversal.
wiringHelpTopic → const HelpTopic: Help topic documenting nested tool wiring.

Properties

isConsoleMarkdownActive → bool: Returns true if the current zone already applies console_markdown.
no setter

Functions

addNavigationOptions(ArgParser parser) → void: Add standard navigation options to an ArgParser.
decodeProcessOutput(Object? raw) → String: Decode raw process output as UTF-8, tolerating malformed byte sequences.
enableUtf8Console() → void: Switch the process to UTF-8 console output so non-ASCII tool output renders correctly.
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 execution modes explanation lines.
getRequiredArgCount(String macroValue) → int: Get the number of required arguments for a macro.
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).
isBinaryOnPath(String binary) → bool: Check if a binary is available on the system PATH.
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 execution modes explanation to stdout.
resolveBinary(String binary) → String: Platform-aware binary resolution and checking utilities.
resolveExecutionRoot(WorkspaceNavigationArgs navArgs, {required String currentDir}) → String: Determine the execution root based on navigation args.
runBinary(String binary, List<String> args, String workingDirectory) → Future<ProcessResult>: Run a binary with the given arguments in a working directory.
runBinaryStreaming(String binary, List<String> args, String workingDirectory) → Future<int>: Run a binary with streaming output directly to stdout/stderr.
runWithConsoleMarkdown<T>(Future<T> body(), {void onError(Object error, StackTrace stack)?}) → Future<T>: Run body inside a Dart zone that automatically renders console_markdown syntax in every print() call.
runWithConsoleMarkdownSync<T>(T body(), {void onError(Object error, StackTrace stack)?}) → T: Synchronous variant of runWithConsoleMarkdown for tools that don't need async (rarely used — prefer the async version).
scanForDartProjects(String dir, {bool recursive = false, bool includeTestProjects = false, bool verbose = false}) → List<String>: Scan a directory for Dart projects (directories containing pubspec.yaml).

Exceptions / Errors

MacroExpansionException: Exception thrown when macro expansion fails.
UnresolvedPlaceholderException: Exception thrown when a placeholder cannot be resolved.

tom_build_base_v2 library

Quick Start

Classes

Enums

Extensions

Constants

Properties

Functions

Exceptions / Errors

tom_build_base package

tom_build_base_v2 library