tom_build_kit 1.12.0

Build orchestration tool with pipelines that integrates Tom build tools.

Tom Build Kit

Published on pub.dev as tom_build_kit 1.12.0.

Tom Build Kit is part of the Tom framework by al-the-bear. Distributed under the terms in this package's license — see LICENSE.

Build orchestration tool with pipelines that integrates Tom build tools.

tom_build_kit is the package behind the buildkit command — the pipeline-based orchestrator for the whole Tom workspace. From a single invocation it runs named build pipelines, invokes individual build commands (:versioner, :compiler, :runner, :pubget, …), drives git across every repository in the workspace, and scans many projects in dependency order. Every command is a native v2 CommandExecutor dispatched by the shared ToolRunner from tom_build_base, so buildkit gets argument parsing, workspace traversal, pipeline execution and end-of-run summaries for free.

A second, smaller binary — findproject — resolves a project by name, ID or folder and prints its path, so a shell wrapper can cd to it.

---

Overview

A Tom workspace is a tree of many Dart/Flutter packages spread across nested git repositories. Building, versioning, compiling, fetching dependencies and managing git across all of them by hand does not scale. buildkit makes the whole workspace addressable from one command in two complementary ways:

• Pipelines — named sequences of steps defined in buildkit_master.yaml (e.g. a build pipeline that runs :versioner, then :runner, then :compiler). Run buildkit build and the steps execute in order, across the selected projects, in dependency order.
• Direct commands — invoke a single build tool with :command syntax (buildkit :compiler), optionally across a project selection.

Both share the same engine. buildkit is a v2 tool: it declares a ToolDefinition (buildkitTool) listing every command, and a matching map of CommandExecutors (createBuildkitExecutors()). The bin/buildkit.dart entry point hands both to a ToolRunner from tom_build_base, which parses the arguments, resolves the project/git traversal, runs the chosen executor against each matched folder, and renders a consistent errors/skips summary. buildkit itself contributes the commands; the framework — parsing, traversal, pipelines, option precedence, multi-workspace navigation — lives in tom_build_base.

How a command flows

buildkit :pubget --project='tom_*'
        │
        ▼
  ToolRunner (tom_build_base)
   • parse args against buildkitTool (ToolDefinition)
   • resolve project selection + traversal order
   • for each matched DartProjectFolder:
        └─► PubGetExecutor.execute(...)  →  dart/flutter pub get
   • aggregate ToolResult, render run summary

---

Installation

tom_build_kit is on pub.dev. Activate its executables globally:

dart pub global activate tom_build_kit

It depends on the hosted tom_build_base: ^2.17.0 from pub.dev (the shared CLI / build framework), plus analyzer, args, dcli, glob, meta, path, yaml, yaml_edit and console_markdown.

The package declares two executables:

executables:
  buildkit:
  findproject:

In day-to-day use the binaries are activated/compiled and put on PATH:

# From tom_ai/basics/tom_build_kit
dart pub get
dart run bin/buildkit.dart --help     # or, once on PATH: buildkit --help

A short alias and a cd-helper are conventional:

alias bk=buildkit

# Jump to a project by name / ID / folder using findproject
goto() {
  local d; d="$(findproject "$@" 2>/dev/null)"
  if [[ -n "$d" && -d "$d" ]]; then cd "$d"; else findproject "$@"; return 1; fi
}

SDK requirement: Dart ^3.10.4.

---

Features

Feature	Description
Pipeline execution	Define and run named build pipelines from buildkit_master.yaml (base-owned).
Direct commands	Run build tools directly with :command syntax.
Sequential execution	Mix pipelines and commands in a single invocation.
Project scanning	Run pipelines/commands across many projects in dependency order.
Platform filtering	Run steps only on specific platforms.
Git orchestration	Drive git across every repository in the workspace with one command.
Dependency management	dart/flutter pub get / upgrade across the selected projects.
Dry-run mode	Preview what would be executed without running it.
Guided mode	Interactive -g / --guide flow for git and standalone tools.

---

Quick start

# Run a pipeline
buildkit build

# Run multiple pipelines in sequence
buildkit clean build

# Run tool commands directly
buildkit :versioner :compiler

# Mix pipelines and commands
buildkit build :cleanup --all

# Scan all projects under the current directory
buildkit build --scan . --recursive

▶ build › versioner   (12 projects)   ok
▶ build › runner      (3 projects)     ok
▶ build › compiler    (5 projects)     ok
Run summary: 20 ok · 0 skipped · 0 errors

---

Example projects

Where	Demonstrates
bin/buildkit.dart	The v2 entry point: ToolRunner(tool: buildkitTool, executors: createBuildkitExecutors()).
bin/findproject.dart	A standalone project-resolver tool wrapped by a shell goto() function.
test/	182 tests covering executors, pipelines, project scanning and git commands — each is a runnable usage example.
tom_build_kit_sample	Authoring a small build tool / pipeline with buildkit against a fixture workspace (planned — forward reference until the samples build-out lands).

---

Usage

buildkit [options] <pipeline|:command> [args...] [<pipeline|:command> [args...]]...

Options:
  -h, --help         Show help
  -v, --verbose      Verbose output
  -n, --dry-run      Show what would be executed
  -l, --list         List available pipelines
  -s, --scan         Scan directory for projects
  -R, --recursive    Scan recursively into projects
  -p, --project      Project(s) to process (comma-separated, globs: tom_*_builder, ./*)

Built-in commands

Command	Description
:versioner	Generate version.versioner.dart from pubspec.yaml.
:compiler	Compile Dart to native executables.
:runner	Run build_runner for code generation.
:cleanup	Clean build artifacts.
:dependencies	Report/resolve inter-project dependencies.
:publisher	Publish packages.
:status	Show tool/repo status across the workspace.
:buildsorter	Compute the dependency build order.
:execute	Execute a shell command in each traversed folder.
:unreferenced	Audit the exported symbols no lib/ or bin/ file names, per the project's unreferenced: section.

Unreferenced-export audit

:unreferenced reports every public symbol a set of packages exports from lib/ that no other lib/ or bin/ file names — a feature only its tests build, a getter nothing reads, a setting saved and never acted on. A test seam marked @visibleForTesting passes while a test names it; a symbol unreferenced by design is allowlisted with its reason, and an entry that stops matching a finding fails the audit. The project's buildkit.yaml says what is audited:

unreferenced:
  root: ..                    # holds the audited packages
  package-prefix: my_         # which of them are audited
  exclude: [my_testkit]
  consumer-repositories: [../../other_repo]   # consumers only
  allow:
    - package: my_core
      symbol: Store.reserved  # `Name` or `Type.member`; a type covers its members
      reason: the later release that reads it

buildkit -p . :unreferenced            # exit code is the verdict
buildkit -p . :unreferenced --verbose  # also lists the allowlisted symbols

The audit is also a library, package:tom_build_kit/unreferenced_exports.dart (UnreferencedExportsConfig.load(dir).audit()), for a suite that holds its repository to it.

Dependency commands

:pubget and :pubupdate run the SDK's dependency commands per matched Dart project (recursive by default). They pick dart vs flutter automatically based on the project's nature:

# Fetch dependencies across all matched Dart/Flutter projects
buildkit :pubget                  # alias: :pg

# Limit to a project selection
buildkit :pubget --project='tom_*'

# Upgrade dependencies to the latest allowed versions
buildkit :pubupdate               # alias: :pu

Command	Aliases	Runs
:pubget	:pg	dart pub get / flutter pub get per project (recursive).
:pubgetall	:pga	Deprecated alias for :pubget.
:pubupdate	:pu	dart pub upgrade / flutter pub upgrade per project.
:pubupdateall	:pua	Deprecated alias for :pubupdate.

These commands declare worksWithNatures: {DartProjectFolder}, so the ToolRunner only invokes them on folders detected as Dart/Flutter projects and skips everything else.

Execute command

Run a shell command in every traversed folder, with placeholder substitution:

# Echo folder name in each git repo
buildkit -i :execute "echo ${folder.name}"

# Run dart pub get only in dart projects
buildkit -i :execute --condition dart.exists "dart pub get"

# Conditional output based on project type
buildkit -i :execute "echo ${dart.publishable?(Publishable):(Not publishable)}"

# Git status in all repos
buildkit -i :execute --condition git.exists "git status"

Available placeholders:

• Path: ${root}, ${folder}, ${folder.name}, ${folder.relative}
• Platform: ${current-os}, ${current-arch}, ${current-platform}
• Nature existence: ${dart.exists}, ${flutter.exists}, ${git.exists}
• Dart: ${dart.name}, ${dart.version}, ${dart.publishable}
• Git: ${git.branch}, ${git.remote}, ${git.dirty}

Ternary syntax: ${condition?(true-value):(false-value)}

Git commands

Manage git repositories across the entire workspace with a single command. Each command has a defined traversal order (inner-first or outer-first) so operations are safe across nested repositories:

Command	Description	Traversal
:gitstatus	Show status of all repositories	inner-first (default)
:gitcommit	Commit and push all repos with same message	inner-first (fixed)
:gitpull	Pull latest from all repositories	outer-first (fixed)
:gitsync	Full sync: stash, fetch, merge, push	outer-first (fixed)
:gitbranch	Manage branches across repos	inner-first (fixed)
:gittag	Manage tags across repos	inner-first (fixed)
:gitcheckout	Checkout branch/tag/commit	outer-first (fixed)
:gitreset	Reset repos to specific state	outer-first (fixed)
:gitclean	Remove untracked files	inner-first (fixed)
:gitprune	Remove stale remote-tracking branches	outer-first (fixed)
:gitstash	Stash uncommitted changes	inner-first (fixed)
:gitunstash	Restore stashed changes	outer-first (fixed)
:gitcompare	Compare current branch with another	inner-first (fixed)
:gitmerge	Merge branch into current branch	inner-first (fixed)
:gitsquash	Squash merge branch into current	inner-first (fixed)
:gitrebase	Rebase current branch onto another	inner-first (fixed)
:git	Run arbitrary git commands	requires -i/-o

# Check status of all repos
bk :gitstatus

# Commit all repos with same message
bk :gitcommit -m "Add feature X"

# Full sync (stash, pull, push)
bk :gitsync

# Create branch in all repos
bk :gitbranch -c feature/new

# Run arbitrary git command
bk :git -i -- log --oneline -5

Project selection

Specify projects with --project using comma-separated values and glob patterns:

# Single project
buildkit build --project=my_app

# Multiple projects (comma-separated)
buildkit build --project='project1,project2'

# Glob patterns
buildkit build --project='tom_*_builder'

# Current directory children
buildkit build --project='./*'

Pipeline configuration

Define pipelines in buildkit_master.yaml (workspace root):

buildkit:
  pipelines:
    build:
      core:
        - commands:
            - buildkit :versioner
            - buildkit :runner
            - buildkit :compiler

Pipeline command prefixes: buildkit (delegate to a tool command), shell (run in the workspace root), shell-scan (run once per project). Pipeline execution, option precedence and multi-workspace traversal are handled by tom_build_base.

---

Architecture

buildkit is a thin command catalogue over the tom_build_base v2 framework. It declares what the commands are (buildkitTool) and how each one runs (the executor map); the framework decides where they run (traversal) and when (pipeline order).

                bin/buildkit.dart
                       │ builds
                       ▼
        ToolRunner(tool: buildkitTool,
                   executors: createBuildkitExecutors())
                       │  (ToolRunner, traversal, pipelines
                       │   all from tom_build_base v2)
        ┌──────────────┼───────────────────────────────┐
        ▼              ▼                                ▼
  buildkitTool    project / git                  CommandExecutor map
  (ToolDefinition  traversal                     name → executor
   = list of       (filter pipeline,             ┌───────────────────┐
   CommandDefs)    build order)                  │ versioner → Versioner│
        │                                        │ compiler  → Compiler │
        │ each CommandDefinition names           │ pubget    → PubGet   │
        │ its options, natures, traversal        │ gitstatus → GitStatus│
        └───────────────────────────────────────┤ …                  │
                                                 └───────────────────┘

Key types (the v2 model)

Type	Origin	Responsibility
ToolRunner	tom_build_base	Parses args, resolves traversal, dispatches to executors, aggregates the ToolResult.
ToolDefinition	tom_build_base	The tool's full command catalogue; buildkit's instance is buildkitTool.
CommandDefinition	tom_build_base	One command's metadata: name, aliases, options, worksWithNatures, traversal flags, examples.
OptionDefinition	tom_build_base	A flag/option on a command (e.g. versionerOptions).
CommandExecutor	tom_build_base	Base class every buildkit command extends; execute(...) does the work for one folder.
buildkitTool	tom_build_kit	The ToolDefinition listing every buildkit command.
createBuildkitExecutors()	tom_build_kit	Builds the name → CommandExecutor map wired into the ToolRunner.
VersionerExecutor / CompilerExecutor / RunnerExecutor / CleanupExecutor / DependenciesExecutor	tom_build_kit	The core build-step executors.
PubGetExecutor / PubUpdateExecutor	tom_build_kit	Per-project pub get / pub upgrade (auto-selecting dart vs flutter).
Git*Executor (e.g. GitStatusExecutor, GitCommitExecutor, GitSyncExecutor)	tom_build_kit	One executor per git command, each with a fixed traversal order.
FindProjectExecutor	tom_build_kit	Resolves a project by name/ID/folder for the findproject binary.

Adding a command is therefore two coordinated edits: a CommandDefinition in buildkitTool and a CommandExecutor registered in createBuildkitExecutors().

---

Ecosystem

buildkit sits at the top of the build toolchain, built on the shared framework and reusing the workspace understanding from tom_build.

                      buildkit · findproject   (this package)
                             │ built on
                             ▼
                    ┌──────────────────┐
                    │  tom_build_kit   │  ← you are here
                    └────────┬─────────┘
              depends on     │  (hosted ^2.6.25)
                             ▼
                    ┌──────────────────┐
                    │  tom_build_base  │  CLI framework: ToolRunner,
                    │  (basics layer)  │  traversal, pipelines, config
                    └──────────────────┘

The shared CLI framework tom_build_base lives in the basics layer (tom_ai/basics/tom_build_base) and is taken as a hosted dependency — buildkit consumes a published version, never a path override. The sibling kits tom_test_kit and tom_issue_kit follow the same pattern.

---

Further documentation

In-package guides under doc/:

Document	What's there
doc/buildkit_user_guide.md	The BuildKit orchestrator: pipelines, commands, scanning, security.
doc/tools_user_guide.md	Reference for the individual tools: versioner, cleanup, compiler, runner, dependencies, pubget, …
doc/git_guide_mode.md	The guided (-g / --guide) mode for git commands.
doc/standalone_guided_mode.md	Guided mode for standalone tools beyond git.
doc/test_coverage.md	The buildkit test-coverage plan and status.
doc/issues.md	Historical record of the consolidation issues (all resolved).

Related packages (don't duplicate — follow the link):

Package	Relationship
tom_build_base	The CLI / build framework buildkit is built on (ToolRunner, traversal, pipelines).
tom_build	The workspace analyzer + metadata buildkit's traversal builds on.
tom_test_kit	Sibling kit — test tracking, same framework.
tom_issue_kit	Sibling kit — issue tracking, same framework.
Tom DevOps map	The repository-level index for the whole devops toolchain.

---

Status

• Version: 1.12.0 (on pub.dev)
• SDK: Dart ^3.10.4
• Base: tom_build_base: ^2.17.0 (hosted)
• Tests: dart test (executor, pipeline, project-scan and git suites).
• Binaries: buildkit (primary), findproject.

---

License

See LICENSE; each package in this repository carries its own license terms.