tom_build_base 2.6.2

Unified CLI framework for workspace traversal, tool definition, pipeline execution, and build configuration.

Tom Build Base

Unified CLI framework for workspace traversal, tool definition, pipeline execution, and build configuration.

This package provides the foundation that Tom CLI build tools (like buildkit, testkit, d4rtgen, etc.) use to define commands, discover projects, and traverse directory structures.

Features

• Declarative tool definition — ToolDefinition, CommandDefinition, OptionDefinition for structured CLI tools
• Automatic help generation — --help, help <command>, help <topic> with consistent formatting
• Built-in traversal — Project and git traversal with folder nature detection
• Pipelines, macros, defines — Multi-command tools get pipelines, runtime macros, and persistent defines automatically
• Nested tool wiring — Declarative integration of external tool binaries
• Configuration loading — TomBuildConfig for reading buildkit.yaml and buildkit_master.yaml
• YAML utilities — yamlToMap(), yamlListToList(), toStringList() for converting YAML nodes

Installation

dependencies:
  tom_build_base: ^2.6.0

Quick Start

import 'package:tom_build_base/tom_build_base.dart';

const myTool = ToolDefinition(
  name: 'mytool',
  description: 'My custom build tool',
  version: '1.0.0',
  mode: ToolMode.multiCommand,
  commands: [
    CommandDefinition(
      name: 'build',
      description: 'Build the project',
      requiredNatures: {DartProjectFolder},
    ),
  ],
);

void main(List<String> args) async {
  final runner = ToolRunner(
    tool: myTool,
    executors: {
      'build': CallbackExecutor(
        onExecute: (context, args) async {
          print('Building ${context.name}');
          return ItemResult.success(path: context.path, name: context.name);
        },
      ),
    },
  );
  final result = await runner.run(args);
  exit(result.success ? 0 : 1);
}

Configuration Format

Tom build tools use a two-tier configuration pattern:

buildkit_master.yaml (workspace root)

navigation:                   # shared defaults for all tools
  scan: .
  recursive: true
  exclude: [.git, build]

mytool:                       # tool-specific workspace defaults
  verbose: false

buildkit.yaml (inside a project)

mytool:
  verbose: true               # overrides workspace default

Documentation

• build_base_user_guide.md — Complete user guide with API reference
• cli_tools_navigation.md — CLI navigation options and implementation guide

License

BSD 3-Clause License — see LICENSE for details.

Author: Alexis Kyaw (LinkedIn)