readme.md

Tom Basics — the foundation layer of the Tom framework

> Tom Basics is part of the Tom framework by al-the-bear. > Distributed under the terms in each package's own license — see > LICENSE.md.

A small family of focused, dependency-light Dart packages that every other Tom component builds on: exception handling with traceable IDs, platform and console utilities, networking, the unified CLI / build framework (tom_build_base) and the buildkit build orchestrator that runs on it (tom_build_kit), cryptography, a unified messaging API, and a handful of documentation / workspace tools.

This document is the map. It orients you to the whole tom_ai/basics repository and routes you to the one package you actually need — each package carries its own README with the full manual, and the runnable samples live in tom_basics_samples/. Depth lives downstream; this page is just the index.

---

New here?

Start with the tom_basics_sample project — it walks the exception-handling-with-UUID-tracking model end to end and is the gentlest on-ramp into the ecosystem. From there, the samples learning path takes you category by category.

---

What you can do with Tom Basics

• Track every failure to its source — wrap and rethrow exceptions carrying

a stable UUID so a log line on one machine maps to a stack frame on another. - Write code that runs the same on console and in the browser — platform detection, console output, and an HTTP client that abstract the host away. - Talk to flaky networks reliably — HTTP retry with backoff and local server discovery. - Build your own CLI tools in minutes — declare a tool, its commands and options once and get argument parsing, help, workspace traversal, pipelines and config for free (tom_build_base). - Drive the whole workspace from one command — buildkit runs cleanup, versioning, compile, dependency resolution, publishing and git workflows as composable pipelines across every package (tom_build_kit). - Secure your data — issue and verify JWTs, hash and check passwords, and do RSA round trips. - Send a message anywhere — one chat API over Telegram, WhatsApp, Signal and more. - Keep generated docs and workspace metadata honest — non-destructive Markdown merges, workspace package scanning, and key generation.

---

How the packages fit together

Tom Basics splits into five concern areas. Read this framing before the component tables so the inventory makes sense:

• Core utilities — the universally-imported primitives: error model,

platform/console helpers, networking. Almost everything depends on these. - Build framework — tom_build_base is the shared engine behind every Tom CLI tool (buildkit, testkit, issuekit, …); tom_build_kit is the buildkit orchestrator built on it — the one package here that ships binaries; tom_analyzer_shared is the analyzer-summary cache that code generators sit on. - Crypto — security primitives, isolated so non-security code never pulls in the crypto dependency tree. - Messaging — a transport-agnostic chat abstraction. - Doc / workspace tooling — utilities that operate on the workspace itself: Markdown merge, package scanning, key generation.

                       ┌─────────────────────────────┐
                       │        Core utilities       │
                       │  tom_basics                 │
                       │  tom_basics_console         │
                       │  tom_basics_network         │
                       └──────────────┬──────────────┘
                                      │ used by everything
        ┌───────────────┬─────────────┼──────────────┬──────────────┐
        │               │             │              │              │
 ┌──────┴──────┐ ┌──────┴──────┐ ┌────┴─────┐ ┌──────┴──────┐ ┌─────┴───────┐
 │ Build       │ │ Crypto      │ │ Messaging│ │ Doc / WS    │ │ (downstream │
 │ framework   │ │ tom_crypto  │ │ tom_     │ │ tooling     │ │  Tom repos: │
 │ tom_build_  │ │             │ │ chattools│ │ tom_md_merge│ │  d4rt,      │
 │  base       │ │             │ │          │ │ tom_pkg_scan│ │  devops,    │
 │ tom_analyzer│ │             │ │          │ │ tom_tools   │ │  vscode …)  │
 │  _shared    │ │             │ │          │ │             │ │             │
 └─────────────┘ └─────────────┘ └──────────┘ └─────────────┘ └─────────────┘

---

Components

Every package appears in exactly one row below, linked to its own README. Only tom_build_kit ships standalone binaries (buildkit, findproject); the rest are libraries (tom_build_base and tom_tools ship their executables through the consuming CLI tools, not from here), so their Binary column is —.

Core utilities

Build framework

Crypto

Messaging

Doc / workspace tooling

---

Getting started

Add the package you need with its hosted version constraint (never a path override):

dependencies:
  tom_basics: ^1.0.0

dart pub add tom_basics

A minimal taste — wrap a failure with a traceable ID:

import 'package:tom_basics/tom_basics.dart';

void main() {
  try {
    throw StateError('disk full');
  } catch (e, s) {
    final tracked = TomException.wrap(e, s);
    print(tracked.id); // e.g. 3f2a9c41-... (stable UUID for cross-host tracing)
  }
}

Each package README opens with its own runnable quick-start — follow the link from the component tables above.

---

Samples learning path

Runnable, article-grade sample projects live in tom_basics_samples/, one self-contained Dart package each. Ordered from first contact to advanced framework use:

> Samples are written before some of their packages' deep-dive docs; until each > sample project lands, its link is a forward reference resolved by the samples > build-out.

---

Documentation index

In-package guides beyond the package READMEs:

---

Repository layout

tom_ai/basics/
├── README.md                 # this map
├── LICENSE.md                # per-package licensing note
├── analysis_options.yaml     # shared analyzer settings
│
├── tom_basics/               # error model + UUID tracking (core)
├── tom_basics_console/       # platform detection, console output, HTTP (core)
├── tom_basics_network/       # HTTP retry + server discovery (core)
│
├── tom_build_base/           # unified CLI / build framework
│   └── doc/                  # framework user guides
├── tom_build_kit/            # buildkit orchestrator + pipelines (ships buildkit, findproject)
│   └── doc/                  # buildkit + tools guides
├── tom_analyzer_shared/      # analyzer-summary caching for code generators
│
├── tom_crypto/               # JWT, password hashing, RSA
│   └── doc/                  # crypto reference
│
├── tom_chattools/            # unified chat API (Telegram/WhatsApp/Signal/…)
│
├── tom_markdown_merge/       # non-destructive Markdown region merge
├── tom_package_scanner/      # workspace package publication scanner
├── tom_tools/                # key-generator CLI
│
└── tom_basics_samples/       # runnable, article-grade sample projects

---

License

See LICENSE.md; each package carries its own license terms.

CHANGELOG.md

0.2.0

• Added resolveDartSdkPath() and looksLikeDartSdk() — a robust runtime

Dart SDK locator (in src/sdk/dart_sdk_locator.dart). The analyzer derives the SDK from Platform.resolvedExecutable, which is correct under dart run but fails for AOT-compiled tools (dart compile exe) where the executable is the tool itself, not the dart binary. The locator tries DART_SDK / DART_HOME, the resolved executable, and the dart/flutter executables on PATH (handling the Flutter bin/cache/dart-sdk layout), validating every candidate against the SDK marker file before returning it. The result is cached for the process lifetime. - SummaryGenerator now uses resolveDartSdkPath() to locate the SDK summary directory, fixing a PathNotFoundException for lib/_internal/allowed_experiments.json when run from a compiled binary.

0.1.0

• Initial release. Extracted summary-caching infrastructure from

tom_reflection_generator into a reusable library so multiple code generators (reflection, d4rt bridges, ...) can share the same <workspace>/.tom/analyzer-cache/ directory. - Public API: - PackageDependency, DependencySet - DependencyResolver (parses pubspec.lock, locates hosted/SDK package sources) - SummaryCacheManager (reads/writes {name}@{version}.sum files) - SummaryGenerator (generates the SDK summary and per-package summaries in topological order) - runSummaryCacheStage() and SummaryCacheResult — reusable orchestration helper that resolves dependencies, generates missing summaries, and returns the paths to pass to AnalysisContextCollectionImpl.

README.md

> Part of the Tom framework by al-the-bear. > © 2024–2026 Peter Nicolai Alexis Kyaw — BSD-3-Clause, see LICENSE.

Shared analyzer-summary caching infrastructure reused by Tom code generators (reflection, d4rt bridges, …).

Every tool that builds on the Dart analyzer package pays the same tax: before it can look at your code, the analyzer must resolve and analyse all of your dependencies — Flutter, provider, meta, the SDK itself. For a code generator that runs repeatedly, re-analysing the same stable packages on every run is pure waste. tom_analyzer_shared removes that waste by building analyzer summaries (.sum files) for the dependencies whose versions cannot change between runs, caching them in a shared workspace directory, and handing the paths back so the analyzer loads pre-digested type information instead of re-scanning sources.

It was extracted from tom_reflection_generator so that more than one generator could share one cache, and it is consumed today by both the reflection generator and the d4rt bridge generator.

---

Overview

The analyzer can be told, when it constructs an analysis context, "here are some pre-built summaries — trust them instead of reading these packages from source":

AnalysisContextCollectionImpl(
  includedPaths: [projectRoot],
  sdkSummaryPath: ...,        // a prebuilt SDK summary
  librarySummaryPaths: ...,   // prebuilt package summaries
);

The hard part is producing those summaries correctly: knowing which packages are safe to cache, locating their sources in the pub cache and the SDK, building each summary after the summaries it depends on, and storing them under a stable, version-keyed name so the next run finds them. tom_analyzer_shared owns that pipeline:

pubspec.lock ──▶ DependencyResolver ──▶ which deps are cacheable?
                                          │  (hosted + SDK = stable versions)
                                          ▼
                 SummaryGenerator ──▶ build SDK summary, then each package
                                          │  summary in topological order
                                          ▼
                 SummaryCacheManager ──▶ <workspace>/.tom/analyzer-cache/
                                          │  {package}@{version}.sum
                                          ▼
            SummaryCacheResult { summaryPaths, sdkSummaryPath } ──▶ analyzer

The whole pipeline is wrapped by one function — runSummaryCacheStage — that a CLI tool calls once and then feeds the result straight into its analysis context. The individual stages are public too, for tools that need finer control.

Why only some dependencies are cached

A summary is keyed by {package}@{version}. That key is only trustworthy when the version pins the content — which is true for hosted (pub.dev) and SDK packages, and false for path and git dependencies, whose files can change without the version changing. So tom_analyzer_shared caches hosted and SDK packages and leaves path/git dependencies to be analysed from source every run. This is the single rule encoded in PackageDependency.isCacheable.

---

Installation

dependencies:
  tom_analyzer_shared: ^0.1.0

Or from the command line:

dart pub add tom_analyzer_shared

Then import the single entry point:

import 'package:tom_analyzer_shared/tom_analyzer_shared.dart';

Requires Dart SDK ^3.10.4. It depends on analyzer, path, and yaml. It is a dart:io package (it reads pubspec.lock, the pub cache, and the SDK), so it runs on desktop, server, and CLI hosts.

---

Features

---

Quick start

Most callers need exactly one function. Resolve, generate what's missing, and get the paths to hand to the analyzer:

import 'package:analyzer/src/dart/analysis/analysis_context_collection.dart';
import 'package:tom_analyzer_shared/tom_analyzer_shared.dart';

Future<void> analyse(String projectRoot) async {
  final result = await runSummaryCacheStage(projectRoot, verbose: true);

  final collection = AnalysisContextCollectionImpl(
    includedPaths: [projectRoot],
    sdkSummaryPath: result?.sdkSummaryPath,
    librarySummaryPaths: result?.summaryPaths ?? const [],
  );
  // … use `collection` to analyse the project's own sources …
}

runSummaryCacheStage resolves dependencies from pubspec.lock, builds any summaries not already in <projectRoot>/.tom/analyzer-cache/, and returns a SummaryCacheResult. On the first run it generates the cache; on later runs it finds everything present and returns immediately. It returns null when no dependencies could be resolved or no summaries are available, so the null-aware result?.… is the intended usage.

---

Example projects

This package is consumed inside code-generator CLIs rather than run standalone, so it ships no example/ program. The worked sample lives in the samples folder:

The usage sections below and the consumers named under ecosystem are the inline reference.

---

Usage

The one-call stage

runSummaryCacheStage takes the project root and a handful of optional flags that mirror what a generator CLI exposes:

final result = await runSummaryCacheStage(
  projectRoot,
  verbose: true,                 // detail each generated/failed package
  rebuildCache: false,           // true → clear the cache first
  showCacheStatus: false,        // true → print status and return null
  cacheOnlyPackages: const [],   // non-empty → only these packages
  log: print,                    // redirect output (defaults to print)
);

• rebuildCache clears <root>/.tom/analyzer-cache/ before generating — use it

when a summary may be stale (e.g. after an SDK upgrade). - showCacheStatus prints a per-package CACHED/MISSING report and returns null without doing heavy work — the implementation behind a --cache-status flag. - cacheOnlyPackages narrows generation to named packages for targeted rebuilds. - log redirects the human-readable progress lines to your own sink.

Resolving dependencies

When you need the dependency list itself — to inspect it, filter it, or drive a custom generation — use DependencyResolver. It parses pubspec.lock and classifies every entry:

final resolver = DependencyResolver();
final deps = await resolver.resolveVersionedDependencies(projectRoot);

for (final dep in deps) {
  print('${dep.cacheKey}  source=${dep.source}  cacheable=${dep.isCacheable}');
}

A PackageDependency carries the name, exact version, source (hosted, sdk, path, git), and the source-specific extras (hostedUrl, sdkName, path). Its two derived members are the heart of the package:

• isCacheable — true only for hosted and sdk sources.
• cacheKey — '{name}@{version}', the cache file stem.

const dep = PackageDependency(name: 'provider', version: '6.1.2', source: 'hosted');
print(dep.isCacheable); // true
print(dep.cacheKey);    // provider@6.1.2

DependencySet.from(deps) splits a list into cacheable / uncacheable, and the DependencyListExtensions give you focused views:

final set = DependencySet.from(deps);
print(set.cacheable.length);        // hosted + sdk
print(deps.hosted.map((d) => d.name));  // hosted only
print(deps.findByName('flutter')?.cacheKey);

The cache directory

SummaryCacheManager owns <workspace>/.tom/analyzer-cache/ and the file naming. You construct it with the workspace root and ask it for paths or status — it never guesses a layout the analyzer can't find:

final cache = SummaryCacheManager(projectRoot);

print(cache.cacheDirectory);                       // …/.tom/analyzer-cache
print(cache.getCachePath('provider', '6.1.2'));    // …/provider@6.1.2.sum
print(cache.getSdkSummaryPath());                  // …/sdk@<dart-version>.sum

final stats = await cache.getStats();              // CacheStats
print('${stats.summaryCount} files, ${stats.totalSizeMB.toStringAsFixed(1)} MB');

It also offers hasSummary, findMissingSummaries, loadSummary, clearCache, cleanOutdated, and cleanUnusedSummaries for tools that manage the cache lifecycle directly.

Generating summaries directly

SummaryGenerator is the engine runSummaryCacheStage drives. Use it directly when you want to control SDK-vs-package ordering or capture per-package errors:

final generator = SummaryGenerator(
  cacheManager: cache,
  dependencyResolver: resolver,
);

await generator.generateSdkSummary();              // dart:core / dart:ui first

final cacheable = await resolver.resolveCacheableDependencies(projectRoot);
final result = await generator.generateMissingSummaries(
  cacheable,
  onProgress: (pkg, current, total) => print('  ($current/$total) $pkg'),
);

print('generated=${result.generated} skipped=${result.skipped} '
    'failed=${result.failed} total=${result.total}');
for (final entry in result.errors.entries) {
  print('  ${entry.key}: ${entry.value}');         // why a package failed
}

The SDK summary is built first because package summaries resolve dart:core (and, under Flutter, dart:ui) from it. Package summaries are then built in topological order so each can reference its dependencies' summaries. A single package failing to summarise is recorded in errors and does not abort the rest — the analyzer simply falls back to analysing that one from source.

---

Architecture

package:tom_analyzer_shared/tom_analyzer_shared.dart   (single entry point)
        │
        ├── runSummaryCacheStage()  ── orchestration ──┐
        │        returns SummaryCacheResult            │
        │                                              ▼
        ├── DependencyResolver  ── pubspec.lock ──▶ List<PackageDependency>
        │        resolveVersionedDependencies / resolveCacheableDependencies
        │        getHostedPackagePath / getSdkPackagePath / getFlutterSdkPath
        │
        ├── SummaryGenerator  ── generateSdkSummary / generateMissingSummaries
        │        topological order ──▶ SummaryGenerationResult
        │
        └── SummaryCacheManager  ── <workspace>/.tom/analyzer-cache/
                 getCachePath / getSdkSummaryPath / getStats / clearCache

The cache is keyed purely by package name and version, so it is safe to share across tools and across runs: two generators pointed at the same workspace reuse each other's summaries, and nothing in the key depends on which tool wrote it.

---

Ecosystem

tom_analyzer_shared is the analyzer-tooling member of the tom_ai/basics foundation layer. Its consumers are Tom's code generators, which all need a resolved analysis context fast:

• tom_reflection_generator — generates reflection metadata; the package

was originally extracted from it. - tom_d4rt_generator — generates d4rt bridge classes for native Dart APIs.

Both declare tom_analyzer_shared as a dependency and call runSummaryCacheStage so they share one .tom/analyzer-cache/ directory per workspace. Adding a third generator is a matter of the same one-call stage — the cache it shares is already there.

Sibling foundation packages: tom_basics · tom_basics_console · tom_basics_network · tom_build_base.

---

Further documentation

• ../README.md — the tom_ai/basics package map.
• The analyzer package's AnalysisContextCollectionImpl is the consumer of

this package's output; its sdkSummaryPath / librarySummaryPaths parameters are what SummaryCacheResult is built to fill.

---

Status

• Version: 0.1.0
• Tests: a test/summary/ suite covering dependency resolution, the cache

manager, summary generation, and an end-to-end integration test (dart test / testkit :test). - Analysis: clean under package:lints (dart analyze — no issues). - Platforms: any Dart runtime with dart:io (desktop, server, CLI).

license.md

BSD 3-Clause License

Copyright (c) 2024-2026, Peter Nicolai Alexis Kyaw
Find me on LinkedIn under Alexis Kyaw
All rights reserved.

Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions are met:

1. Redistributions of source code must retain the above copyright notice, this
   list of conditions and the following disclaimer.

2. Redistributions in binary form must reproduce the above copyright notice,
   this list of conditions and the following disclaimer in the documentation
   and/or other materials provided with the distribution.

3. Neither the name of the copyright holder nor the names of its
   contributors may be used to endorse or promote products derived from
   this software without specific prior written permission.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

CHANGELOG.md

1.0.0

• Initial version.

README.md

> Part of the Tom framework by al-the-bear. > © 2024–2026 Peter Nicolai Alexis Kyaw — BSD-3-Clause, see LICENSE.

Basic utilities for the Tom framework including exception handling with UUID tracking.

tom_basics is the bottom of the dependency stack. It carries the few primitives that almost every other Tom package imports — a traceable exception base, a configurable logger, a platform-abstraction layer, and a small runtime environment model — while keeping its own dependency list to just three well-known packages (uuid, stack_trace, http). Nothing here pulls in Flutter, a database, or a server framework, so it is safe to import from the most foundational corners of the codebase.

---

Overview

A foundational library has one job: give the layers above it a vocabulary they can share without dragging in heavy dependencies. tom_basics provides four such vocabularies, each independent of the others:

• Errors that can be traced across process boundaries. A

TomBaseException stamps every failure with a UUID at the moment it is created. When the same error is logged on a server, surfaced in a client, and filed in a bug tracker, the UUID is the thread that ties the three sightings together. The exception also captures a terse, core-folded stack trace (via stack_trace) so the noise of the SDK internals is stripped from the report.

• Logging you can dial up and down per class. The global

tomLog instance offers nine severity methods (trace → fatal plus status) and a bitwise level model that lets you compose, subtract, and match levels. You can raise the verbosity of a single class or method without touching the global level, and you can redirect all output to a destination of your choosing by swapping one field.

• Platform detail behind a single seam. Code that needs to know "are we on

the web?" or "give me an HTTP client" talks to TomPlatformUtils.current instead of importing dart:io or dart:html. The concrete implementation is injected once at startup, so the same library code compiles and runs on console, server, mobile, and web.

• A runtime environment model for wiring. [TomEnvironment,

TomPlatform, and TomRuntime](#runtime-environments-and-platforms) describe which environment (development / test / production) and which platform (web / macos / android / …) are active, with a parent hierarchy. Higher-level Tom packages use this to select environment- and platform-specific implementations.

These four concerns share no code with each other; you can import the package and use only the logger, only the exception base, or only the platform seam.

---

Installation

Add the dependency with its hosted version constraint:

dependencies:
  tom_basics: ^1.0.0

or from the command line:

dart pub add tom_basics

SDK: Dart ^3.10.0. Transitive dependencies: uuid, stack_trace, http — all pure-Dart and platform-neutral, so tom_basics itself adds no native or Flutter requirement.

---

Features

Exception handling

Logging

Platform abstraction

Runtime environments and platforms

---

Quick start

import 'package:tom_basics/tom_basics.dart';

void main() {
  // The global logger is ready to use immediately.
  tomLog.setLogLevel(TomLogLevel.development);
  tomLog.info('Application starting...');

  try {
    throw TomBaseException('EXAMPLE_ERROR', 'Something went wrong');
  } on TomBaseException catch (e) {
    tomLog.error('Caught: ${e.key} - ${e.defaultUserMessage}');
    print('Exception UUID: ${e.uuid}'); // e.g. aceec92a-90ab-4f7b-896e-...
  }

  tomLog.info('Application finished.');
}

Running it prints (timestamps and the UUID vary per run):

2026-06-16 21:27:22.128328 - INFO    Application starting...   [main]
2026-06-16 21:27:22.140356 - ERROR   Caught: EXAMPLE_ERROR - Something went wrong   [main]
Exception UUID: aceec92a-90ab-4f7b-896e-595d7f1a94ca
2026-06-16 21:27:22.140927 - INFO    Application finished.   [main]

This is exactly example/tom_basics_example.dart — run it with dart run example/tom_basics_example.dart.

---

Example projects

---

Usage

Exception handling with UUID tracking

The constructor takes a key (a stable, machine-readable code) and a default user message (human-readable), with everything else optional:

import 'package:tom_basics/tom_basics.dart';

void main() {
  final ex = TomBaseException(
    'VALIDATION_ERROR',
    'The email address is not valid',
    parameters: {'field': 'email', 'value': 'not-an-email'},
  );

  print(ex.key);                  // VALIDATION_ERROR
  print(ex.defaultUserMessage);   // The email address is not valid
  print(ex.parameters?['field']); // email
  print(ex.uuid.length);          // 36  (a UUIDv4 string)
}

*Why a key and a message?* The key is what your code branches on and what you grep logs for; it never changes when you reword the prose. The defaultUserMessage is the fallback text shown when no localized message is available. Keeping them separate means translators and programmers never fight over the same string.

Correlating an error with a request. Pass requestUuid so a failure deep in a handler can be matched back to the inbound call that triggered it:

TomBaseException(
  'DB_TIMEOUT',
  'The database did not respond in time',
  requestUuid: incomingRequestId,
  parameters: {'table': 'orders', 'timeoutMs': 5000},
);

Wrapping a lower-level error. When you catch an exception and rethrow a domain-level one, keep the original in rootException and the original trace in stack so nothing is lost:

try {
  await db.query(sql);
} catch (e, s) {
  throw TomBaseException(
    'ORDER_LOAD_FAILED',
    'Could not load the order',
    rootException: e,
    stack: s,
  );
}

Inspecting the trace. Each exception folds out core/SDK frames at construction time and stores the result in stackTrace. Print it directly, or use printStackTrace():

try {
  throw TomBaseException('BOOM', 'demo');
} on TomBaseException catch (e) {
  e.printStackTrace();      // writes "<uuid>-<requestUuid> exception stacktrace:\n..."
  // or inspect the stored string:
  print(e.stackTrace.split('\n').first); // the first non-core frame
}

> Note. tom_basics deliberately stops at this minimal base class. The > full-featured exception type with integrated logging lives in > tom_core_kernel as TomException; reach for that when you are above the > foundation layer.

Logging

The global tomLog instance is usable without any setup. Each severity has its own method:

import 'package:tom_basics/tom_basics.dart';

void main() {
  tomLog.info('Server started on port 8080');
  tomLog.warn('Cache miss for key user:42');
  tomLog.error('Failed to connect to database');
  tomLog.debug('Request payload: {"id": 42}');
  tomLog.trace('Entering computeChecksum()');
}

Output lines carry the timestamp, isolate name, level, message, and the detected origin (the class.method that called the logger), e.g.:

2026-06-16 21:27:22.140 - INFO    Server started on port 8080   [main]

Log levels are bit patterns

A TomLogLevel is a bit mask. Individual levels can be combined with + and removed with -, and a logger only emits a message when its level matches the message level:

// Build a custom level: info plus errors, nothing else.
var quiet = TomLogLevel.info + TomLogLevel.errors;
tomLog.setLogLevel(quiet);

tomLog.info('shown');      // matches -> printed
tomLog.debug('hidden');    // no overlap -> filtered out
tomLog.error('shown');     // matches -> printed

// Subtract a level from a preset.
var prodNoInfo = TomLogLevel.production - TomLogLevel.info;
print(prodNoInfo.matches(TomLogLevel.info)); // false
print(prodNoInfo.matches(TomLogLevel.warn)); // true

Named presets cover the common cases:

You can also resolve a level by name (useful for reading a level from config or an environment variable):

tomLog.setLogLevelByName('DEVELOPMENT');          // case-insensitive
final lvl = TomLogLevel.byName('SILENT');          // or null if unknown

Temporary verbosity with a level stack

To turn the volume up around one tricky section and restore it afterwards, push and pop:

tomLog.pushLogLevel(TomLogLevel.trace);
// ... noisy operations are fully traced here ...
tomLog.popLogLevel(); // back to whatever was active before

Per-class and per-method overrides

When stack-trace analysis is enabled (the default, TomLogger.globalSettingDetermineCaller == true), the logger detects which class.method emitted each message. That lets you raise verbosity for one location only:

// Trace everything in DatabaseService, debug one method of ApiClient.
tomLog.addNameLevel('DatabaseService', TomLogLevel.trace);
tomLog.addNameLevel('ApiClient.sendRequest', TomLogLevel.debug);

// Or configure several at once from a pattern string (e.g. from config):
tomLog.setLogLevelExceptions('DatabaseService=TRACE,ApiClient=DEBUG');

Redirecting output

The logger writes through logOutput, a TomLogOutput. The default is TomConsoleLogOutput (errors and status to stderr, everything else to stdout). Implement TomLogOutput.output to send logs anywhere:

class CollectingLogOutput extends TomLogOutput {
  final List<String> lines = [];

  @override
  void output(
    TomLogLevel loggerLevel,
    TomLogLevel logLevel,
    String level,
    Object message,
    String isolateName,
    DateTime timeStamp,
    String? origin,
  ) {
    if (logLevel.matches(loggerLevel)) {
      lines.add('$level ${convertToString(message)}');
    }
  }
}

void main() {
  final sink = CollectingLogOutput();
  tomLog.logOutput = sink;
  tomLog.info('captured');
  print(sink.lines); // [INFO    captured]
}

convertToString (provided by the base class) handles Strings, lazy Function messages, and TomLoggable objects automatically.

Custom log representation for your types

Implement TomLoggable so an object renders cleanly in logs without exposing internals:

class User implements TomLoggable {
  User(this.id, this.name);
  final String id;
  final String name;

  @override
  String get logRepresentation => 'User($id, $name)';
}

void main() {
  tomLog.info(User('42', 'Ada')); // logs: User(42, Ada)
}

Platform abstraction

Library code that must not import dart:io or dart:html directly talks to TomPlatformUtils.current. The concrete implementation is injected once at startup. Until you do that, the default TomFallbackPlatformUtils supports console output but throws UnimplementedError for detection — a loud, deliberate signal that the platform was never configured:

import 'package:tom_basics/tom_basics.dart';

// A Linux console/server implementation. Extending TomFallbackPlatformUtils
// gives working out/outError; we override every detection method so that
// TomRuntime.initializePlatform() (which probes them all) also works.
class ConsolePlatformUtils extends TomFallbackPlatformUtils {
  @override
  bool isDesktop() => true;
  @override
  bool isMobile() => false;
  @override
  bool isWeb() => false;
  @override
  bool isWindows() => false;
  @override
  bool isLinux() => true;
  @override
  bool isMacOs() => false;
  @override
  bool isFuchsia() => false;
  @override
  bool isAndroid() => false;
  @override
  bool isIos() => false;
}

void main() {
  TomPlatformUtils.setCurrentPlatform(ConsolePlatformUtils());

  final p = TomPlatformUtils.current;
  print(p.isDesktop()); // true
  print(p.isLinux());   // true
  p.out('hello from the platform seam'); // prints to stdout
}

A stub that overrides only isDesktop/isMobile/isWeb is enough for those three checks, but TomRuntime.initializePlatform() (below) probes the full set of OS methods — so a complete implementation like the one above is what makes detection work end to end. In real apps you don't write this yourself: tom_basics_console ships the desktop/server implementation and tom_core_flutter ships the Flutter one. The seam is what lets the same upstream code run on both.

The same singleton also hands out an HTTP client and a configuration map:

// Configuration that travels with the platform, not the call site.
TomPlatformUtils.envVars['API_BASE'] = 'https://api.example.com';
print(TomPlatformUtils.current.getTomEnvVars()['API_BASE']);
// https://api.example.com

// A platform-appropriate http client (once a real platform is configured):
// final client = TomPlatformUtils.current.httpClient();
// final res = await client.get(Uri.parse('https://api.example.com/health'));

Runtime environments and platforms

The runtime model answers "which environment and platform are active, and what is the chain of fallbacks?" Register environments, pick the current one, and walk the hierarchy:

import 'package:tom_basics/tom_basics.dart';

void main() {
  final prod = TomRuntime.addEnvironment(const TomEnvironment('production'));
  TomRuntime.addEnvironment(
    TomEnvironment('staging', parent: prod),
  );

  TomRuntime.setCurrentEnvironment('staging');
  print(TomRuntime.getCurrentEnvironment().env); // staging

  // Root-to-current chain, used by higher layers to resolve fallbacks.
  final chain = TomRuntime.getEnvironmentHierarchy().map((e) => e.env).toList();
  print(chain); // [production, staging]
}

An environment may carry an initializer that runs when it is activated:

final dev = TomEnvironment(
  'development',
  isDevelopment: true,
  initializer: (env) => tomLog.info('Activated ${env.env}'),
);
dev.initialize(); // logs: Activated development

Platform detection ties the platform seam to the runtime registry. Once a real TomPlatformUtils is configured, initializePlatform() detects and records the current platform:

TomPlatformUtils.setCurrentPlatform(ConsolePlatformUtils());
TomRuntime.setCurrentEnvironment('production');
TomRuntime.initializePlatform();
print(TomRuntime.printReport());
// TomRuntime: Platform TomPlatform: linux Root Environment ... Current Environment ...

---

Architecture

tom_basics is four small, independent modules behind a single barrel export (lib/tom_basics.dart):

                       package:tom_basics/tom_basics.dart
                                     │  (barrel export)
        ┌──────────────┬─────────────┼──────────────────┐
        │              │             │                  │
 ┌──────┴──────┐ ┌─────┴──────┐ ┌────┴─────────┐ ┌──────┴────────────┐
 │ exceptions/ │ │ logging/   │ │ runtime/     │ │ runtime/          │
 │ exception_  │ │ logging.   │ │ platform_    │ │ platform_         │
 │ base.dart   │ │ dart       │ │ neutral.dart │ │ environment_      │
 │             │ │            │ │              │ │ runtime.dart      │
 │ TomBase     │ │ TomLogger  │ │ TomPlatform  │ │ TomEnvironment    │
 │ Exception   │ │ TomLogLevel│ │ Utils        │ │ TomPlatform       │
 │             │ │ TomLogOut  │ │ (+ fallback) │ │ TomRuntime        │
 └─────────────┘ └─────┬──────┘ └──────┬───────┘ └───────────────────┘
   uuid,                │  uses         │ uses
   stack_trace          └───────────────┘
                     (logging routes its console
                      output through the platform seam)

The only internal coupling is that logging writes through the platform seam (TomConsoleLogOutput calls TomPlatformUtils.current.out/outError) and reads the isolate name from it. Exceptions and the environment model stand alone.

Key types

---

Ecosystem

tom_basics sits at the root of the basics layer; the rest of the framework imports it, never the other way around.

                      ┌───────────────────────────┐
                      │  tom_core_kernel / server  │   higher-level Tom packages
                      │  tom_core_flutter, d4rt …  │   (TomException, DI, …)
                      └─────────────┬──────────────┘
                                    │ depends on
        ┌────────────────┬──────────┼───────────────┐
        │                │          │               │
 ┌──────┴──────┐  ┌──────┴──────┐   │        ┌───────┴────────┐
 │ tom_basics_ │  │ tom_basics_ │   │        │  tom_crypto     │
 │ console     │  │ network     │   │        │  (uses logging) │
 │ (platform   │  │             │   │        └────────────────┘
 │  impl)      │  │             │   │
 └──────┬──────┘  └──────┬──────┘   │
        └────────────────┴──────────┘
                         │ all depend on
                  ┌──────┴───────┐
                  │  tom_basics  │  ← you are here
                  └──────────────┘
            (uuid · stack_trace · http only)

See the basics repository map for the full package catalogue and the samples learning path.

---

Further documentation

• Basics repository README — the map of all ten basics packages.
• tom_basics_console — supplies the desktop/server

TomPlatformUtils implementation that backs the platform seam. - tom_crypto — a downstream consumer that logs through tomLog. - tom_core_kernel (separate repo) — provides TomException, the full-featured exception type that builds on this base.

---

Status

• Version: 1.0.0
• SDK: Dart ^3.10.0
• Tests: 6 passing (TomBaseException group — construction, parameters,

custom UUID, cause capture, toString, stack-trace capture). Run with dart test or testkit :test. - Analyzer: clean (dart analyze → no issues).

license.md

BSD 3-Clause License

Copyright (c) 2024-2026, Peter Nicolai Alexis Kyaw
Find me on LinkedIn under Alexis Kyaw
All rights reserved.

Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions are met:

1. Redistributions of source code must retain the above copyright notice, this
   list of conditions and the following disclaimer.

2. Redistributions in binary form must reproduce the above copyright notice,
   this list of conditions and the following disclaimer in the documentation
   and/or other materials provided with the distribution.

3. Neither the name of the copyright holder nor the names of its
   contributors may be used to endorse or promote products derived from
   this software without specific prior written permission.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

CHANGELOG.md

1.0.0

• Initial version.

README.md

> Part of the Tom framework by al-the-bear. > © 2024–2026 Peter Nicolai Alexis Kyaw — BSD-3-Clause, see LICENSE.

Console and standalone platform utilities for Tom applications — platform detection, console output, and HTTP client support.

tom_basics_console is the standalone / server implementation of the platform seam declared in tom_basics. Where tom_basics defines the abstract TomPlatformUtils contract (and a fallback that throws for anything it can't do without a host), this package fills that contract in using dart:io: real OS detection, an IO-based HTTP client, environment variables from the process, and console output that renders Markdown as ANSI styling. It also re-exports all of tom_basics, so a console or server app needs only this one import to get the logger, the exception base, the runtime model, and a working platform implementation.

---

Overview

A Dart program that runs on the command line or a server has a host it can ask real questions: which OS am I on? what's in the environment? give me an HTTP client. The Tom framework deliberately keeps those questions behind the TomPlatformUtils seam so that library code stays platform-neutral and compiles for the web too. tom_basics_console is the piece that answers them for the standalone VM target.

It contributes exactly one class — TomStandalonePlatformUtils — plus a convenience getter. That class:

• Detects the platform for real. isDesktop, isWindows, isMacOs,

isAndroid, and the rest are backed by dart:io's Platform, replacing the throwing stubs of TomFallbackPlatformUtils. - Renders console output as styled text. out and outError pass their argument through console_markdown's .toConsole(), so **bold**, *italic*, __underline__, and the other Markdown markers come out as ANSI escapes in a terminal. - Supplies an IO HTTP client with a pragmatic localhost exception: bad TLS certificates are accepted only for localhost / 127.0.0.1 / 0.0.0.0, which makes talking to a dev server painless without weakening production calls. - Seeds the environment map from Platform.environment at construction, so getTomEnvVars() returns the real process environment. - Names the current isolate via Isolate.current.debugName, which the logger uses to tag each line.

Because the library file re-exports tom_basics, importing package:tom_basics_console/tom_basics_console.dart brings the whole foundation layer into scope — you do not import tom_basics separately in a console app.

---

Relationship to tom_basics

Rule of thumb: library packages that must stay web-safe depend on tom_basics; the entry-point of a console or server app depends on tom_basics_console and wires its implementation in once at startup. For a Flutter target, the equivalent implementation lives in tom_core_flutter.

---

Installation

dependencies:
  tom_basics_console: ^1.0.0

dart pub add tom_basics_console

SDK: Dart ^3.10.4. Direct dependencies: tom_basics (re-exported), console_markdown (the .toConsole() extension), and http (the Client type). You do not add tom_basics yourself — it comes transitively and is re-exported.

---

Features

---

Quick start

import 'package:tom_basics_console/tom_basics_console.dart';

void main() {
  final platform = TomStandalonePlatformUtils();

  print('Desktop: ${platform.isDesktop()}'); // Desktop: true   (on a desktop OS)
  print('Mobile: ${platform.isMobile()}');   // Mobile: false
  print('Web: ${platform.isWeb()}');         // Web: false

  // Console-formatted output: **bold** renders as ANSI bold in a terminal.
  platform.out('**Hello** from tom_basics_console!');
}

This is exactly example/tom_basics_console_example.dart — run it with dart run example/tom_basics_console_example.dart. On a desktop machine it prints:

Desktop: true
Mobile: false
Web: false
Hello from tom_basics_console!

(The word Hello is emitted bold via ANSI escape codes; the markers themselves never appear.)

---

Example projects

---

Usage

Wiring the implementation into the seam

The whole point of the package is to make TomPlatformUtils.current return a working implementation. Do this once, at startup, before any library code asks the seam a question:

import 'package:tom_basics_console/tom_basics_console.dart';

void main() {
  // Install the standalone implementation as the global platform.
  TomPlatformUtils.setCurrentPlatform(TomStandalonePlatformUtils());

  // From here on, code anywhere can use the seam without importing dart:io.
  if (TomPlatformUtils.current.isLinux()) {
    TomPlatformUtils.current.out('*running on Linux*');
  }
}

TomPlatformUtils, like setCurrentPlatform and current, comes from the re-exported tom_basics — you did not import it separately.

Platform detection

TomStandalonePlatformUtils answers all the detection questions truthfully on the VM:

final p = TomStandalonePlatformUtils();

print(p.isDesktop()); // true on Windows/macOS/Linux/Fuchsia
print(p.isMobile());  // true on Android/iOS
print(p.isWeb());     // true only when neither desktop nor mobile

print(p.isWindows()); // exactly one of these is true on a VM host
print(p.isLinux());
print(p.isMacOs());

isDesktop() is the disjunction of the four desktop OSes, isMobile() of the two mobile OSes, and isWeb() is "neither of the above" — so on a standalone VM it is always false.

Styled console output

out and outError push their text through console_markdown's .toConsole() extension, so a small Markdown vocabulary becomes terminal styling:

final p = TomStandalonePlatformUtils();

p.out('**Build complete** in *2.3s*');
p.outError('**error:** could not open `config.yaml`');

In a terminal, **Build complete** is bold, *2.3s* is italic, and the backtick-wrapped config.yaml is dimmed; the markers themselves are consumed. See the workspace console_markdown guideline for the full formatting vocabulary (colours, underline, nested tags).

Because the logger's default console sink routes through the platform seam, installing this implementation also makes tomLog output Markdown-styled:

TomPlatformUtils.setCurrentPlatform(TomStandalonePlatformUtils());
tomLog.info('**server** started on port 8080'); // "server" comes out bold

HTTP client

httpClient() returns a package:http Client backed by dart:io's HttpClient. The one non-default behaviour is a deliberate convenience: invalid TLS certificates are accepted only for local hosts, so a self-signed dev server just works while remote calls stay strict.

import 'package:tom_basics_console/tom_basics_console.dart';

Future<void> main() async {
  final client = TomStandalonePlatformUtils().httpClient();
  try {
    final res = await client.get(Uri.parse('https://localhost:8443/health'));
    print(res.statusCode); // e.g. 200 — self-signed cert accepted for localhost
  } finally {
    client.close();
  }
}

For any non-local host the standard certificate validation applies, exactly as with a plain IOClient.

Process environment and isolate name

The constructor copies Platform.environment into the seam's envVars map, so configuration the program was launched with is immediately available through the platform-neutral accessor:

final p = TomStandalonePlatformUtils();
final path = p.getTomEnvVars()['PATH'];
print(path != null); // true — the real process PATH

getIsolateName() returns Isolate.current.debugName (falling back to "main"), which the logger uses to tag each line with the originating isolate.

The standalonePlatformUtils getter

For call sites that just want an instance without naming the class, the library exposes a getter that returns a fresh TomStandalonePlatformUtils typed as the abstract TomPlatformUtils:

TomPlatformUtils.setCurrentPlatform(standalonePlatformUtils);

Using the re-exported foundation

Because tom_basics is re-exported, the full foundation surface is available from the single import — logger, exceptions, and the runtime model included:

import 'package:tom_basics_console/tom_basics_console.dart';

void main() {
  TomPlatformUtils.setCurrentPlatform(TomStandalonePlatformUtils());
  tomLog.setLogLevel(TomLogLevel.development);

  try {
    throw TomBaseException('CONFIG_MISSING', 'config.yaml not found');
  } on TomBaseException catch (e) {
    tomLog.error('**${e.key}** — ${e.defaultUserMessage} (${e.uuid})');
  }
}

See the tom_basics README for the full documentation of tomLog, TomBaseException, and TomRuntime.

---

Architecture

A single source file behind the barrel export (lib/tom_basics_console.dart):

        package:tom_basics_console/tom_basics_console.dart
                              │  (barrel export)
            ┌─────────────────┴──────────────────┐
            │                                     │
 ┌──────────┴───────────────┐        re-export of package:tom_basics
 │ src/runtime/             │        ┌────────────────────────────┐
 │ platform_detection_      │        │ TomPlatformUtils (abstract) │
 │ standalone.dart          │        │ TomFallbackPlatformUtils    │
 │                          │ extends│ TomLogger / tomLog          │
 │ TomStandalonePlatform    │───────▶│ TomBaseException            │
 │ Utils                    │        │ TomRuntime / TomEnvironment │
 │ standalonePlatformUtils  │        └────────────────────────────┘
 └──────────┬───────────────┘
            │ uses
   dart:io · dart:isolate · console_markdown · http/io_client

TomStandalonePlatformUtils extends TomFallbackPlatformUtils (from tom_basics) and overrides every host-dependent method. Everything else the app sees — the logger, the exception base, the runtime registry — flows straight through from the re-export.

Key types

(All other public types — TomPlatformUtils, TomLogger, TomBaseException, TomRuntime, … — are re-exported from tom_basics; see its key-types table.)

---

Ecosystem

        ┌───────────────────────────────┐
        │ console / server entry points │   (your `main()`)
        └───────────────┬───────────────┘
                        │ depends on
               ┌────────┴─────────┐
               │ tom_basics_      │  ← you are here
               │ console          │  (dart:io implementation)
               └───┬──────────┬───┘
        re-exports │          │ depends on
          ┌────────┴───┐  ┌───┴──────────────┐
          │ tom_basics │  │ console_markdown │
          │ (the seam) │  │ · http           │
          └────────────┘  └──────────────────┘

The web/Flutter counterpart is tom_core_flutter, which provides a TomPlatformUtils implementation for those targets. Library packages that must remain web-safe depend on tom_basics directly and never on this package.

See the basics repository map for the full package catalogue and the samples learning path.

---

Further documentation

• tom_basics README — the abstract platform seam,

the logger, and the exception base this package implements and re-exports. - Basics repository README — the map of all ten basics packages. - console_markdown guideline — the Markdown-to-ANSI vocabulary used by out / outError. - console_markdown on pub.dev — the upstream package providing .toConsole().

---

Status

• Version: 1.0.0
• SDK: Dart ^3.10.4
• Tests: none yet (the standalone implementation is exercised through

consuming packages and the tom_basics_console_sample); the package ships a runnable example/. - Analyzer: clean (dart analyze → no issues).

license.md

BSD 3-Clause License

Copyright (c) 2024-2026, Peter Nicolai Alexis Kyaw
Find me on LinkedIn under Alexis Kyaw
All rights reserved.

Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions are met:

1. Redistributions of source code must retain the above copyright notice, this
   list of conditions and the following disclaimer.

2. Redistributions in binary form must reproduce the above copyright notice,
   this list of conditions and the following disclaimer in the documentation
   and/or other materials provided with the distribution.

3. Neither the name of the copyright holder nor the names of its
   contributors may be used to endorse or promote products derived from
   this software without specific prior written permission.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

CHANGELOG.md

1.0.1

• Updated version info generator (versioner file rename).

1.0.0

• Initial version.

README.md

> Part of the Tom framework by al-the-bear. > © 2024–2026 Peter Nicolai Alexis Kyaw — BSD-3-Clause, see LICENSE.

Network utilities for Tom applications — HTTP retry with exponential backoff and LAN server discovery.

tom_basics_network packages the two networking concerns that almost every distributed Tom application needs but that the standard http package leaves to the caller: surviving transient failures and finding a peer on the local network without a configured address. It is a small, focused, pure-Dart package — two independent subsystems, no shared state, no platform plugins — built directly on package:http and dart:io.

The two subsystems are deliberately decoupled. You can take withRetry to wrap any Future-returning operation and never touch discovery, or use ServerDiscovery to locate a server and hand the URL to your own client. They share a package only because they share an audience: code that talks to other machines over an unreliable link.

---

Overview

A networked operation fails for two broad reasons. Either the transport hiccuped — a dropped socket, a timeout, a server that returned 503 because it was briefly overloaded — or something is actually wrong — a 404, a malformed request, an authentication failure. The first kind is worth retrying; the second is not. Retrying a 400 just wastes time and hammers the server.

tom_basics_network encodes that distinction:

• HTTP retry (withRetry, RetryConfig, RetryableResponse) — wraps an

operation in a backoff loop that retries only transient transport errors and only retryable HTTP status codes (5xx, 408, 429), and surfaces a single RetryExhaustedException when the budget runs out. - Server discovery (ServerDiscovery, DiscoveryOptions, DiscoveredServer) — probes localhost, this machine's own LAN addresses, and (optionally) the whole /24 subnet for a Tom server answering a known status endpoint, returning the first match, all matches, or throwing if none respond.

Neither subsystem holds state between calls. withRetry is a top-level function; ServerDiscovery exposes only static methods. Configuration is passed in per call as immutable value objects (RetryConfig, DiscoveryOptions), so the same code is safe to call concurrently from multiple isolates.

---

Installation

dependencies:
  tom_basics_network: ^1.0.1

Or from the command line:

dart pub add tom_basics_network

Then import the single entry point:

import 'package:tom_basics_network/tom_basics_network.dart';

Requires Dart SDK ^3.10.4. The package depends only on package:http; everything else comes from the Dart core libraries (dart:io, dart:async). It runs on any platform with dart:io (desktop, server, CLI) — server discovery uses dart:io networking and is not available on the web.

---

Features

HTTP retry

Server discovery

---

Quick start

Retry a flaky request

import 'package:http/http.dart' as http;
import 'package:tom_basics_network/tom_basics_network.dart';

Future<String> fetchScore() => withRetry(() async {
      final response = await http.get(Uri.parse('https://example.com/score'));
      if (response.isRetryable) {
        // A 5xx/408/429 — throw so withRetry backs off and tries again.
        throw http.ClientException('transient ${response.statusCode}');
      }
      return response.body;
    });

With no RetryConfig, withRetry uses RetryConfig.defaultConfig: up to five retries spaced 2 s, 4 s, 8 s, 16 s, 32 s apart. A ClientException is one of the error types it treats as transient, so the call above retries on those status codes and rethrows anything else immediately.

See the backoff schedule

import 'package:tom_basics_network/tom_basics_network.dart';

void main() {
  final schedule = kDefaultRetryDelaysMs.map((ms) => '${ms / 1000}s').join(', ');
  print('Default retry schedule: $schedule');
}

Output:

Default retry schedule: 2.0s, 4.0s, 8.0s, 16.0s, 32.0s

Find a Tom server on the LAN

import 'package:tom_basics_network/tom_basics_network.dart';

Future<void> main() async {
  final server = await ServerDiscovery.discover();
  if (server == null) {
    print('No server responded.');
    return;
  }
  print('Found ${server.service} v${server.version} at ${server.serverUrl}');
}

discover() returns the first server that answers GET /status with 200 and a JSON object, scanning localhost first, then this machine's LAN addresses, then the rest of the /24. It returns null rather than throwing when nothing answers — see discoverOrThrow for the throwing variant.

---

Example projects

Run the local example with:

dart run example/tom_basics_network_example.dart

For the full worked tour — retry, exhaustion, the retryable set, the default backoff schedule, server discovery and subnet arithmetic — see the tom_basics_network_sample; the usage sections below are the inline reference.

---

Usage

HTTP retry

What counts as retryable

withRetry retries an operation when it throws one of these transport errors:

• SocketException — connection refused / reset / no route
• HttpException — a dart:io HTTP-layer failure
• TimeoutException — the operation took too long
• http.ClientException — a package:http transport failure
• OSError — a lower-level OS networking error

Anything else — an ArgumentError, a FormatException, a thrown 404 handler — is not retried and propagates immediately. The point is to retry the network, not your bugs.

For HTTP status codes, the RetryableResponse extension classifies a response without you memorising the numbers:

import 'package:http/http.dart' as http;
import 'package:tom_basics_network/tom_basics_network.dart';

bool worthRetrying(http.Response r) => r.isRetryable;
// true for 500–599, 408 (Request Timeout), 429 (Too Many Requests)
// false for 200, 404, 400, 401, ...

Because withRetry reacts to thrown errors, the idiom is to inspect the response and throw a transient error when isRetryable is true (as in the quick-start example), letting non-retryable responses return normally.

Configuring the backoff

RetryConfig carries two things: the delay schedule and an optional callback.

import 'package:tom_basics_network/tom_basics_network.dart';

const fastConfig = RetryConfig(
  // Three retries: 100 ms, 200 ms, 400 ms.
  retryDelaysMs: [100, 200, 400],
  onRetry: _logRetry,
);

void _logRetry(int attempt, Object error, Duration nextDelay) {
  print('attempt $attempt failed ($error); retrying in '
      '${nextDelay.inMilliseconds}ms');
}

The length of retryDelaysMs is the retry budget: a list of three delays means the operation runs at most four times (one initial attempt plus three retries). onRetry fires once before each backoff sleep, receiving the 1-based attempt number, the error that triggered the retry, and the delay about to be waited — useful for logging or metrics without changing the control flow.

Narrowing what gets retried

Pass a shouldRetry predicate to override the default transport-error set. When supplied, an error is retried only if both shouldRetry(error) returns true and the error is in the built-in retryable set:

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

final result = await withRetry(
  _doRequest,
  shouldRetry: (error) => error is SocketException, // timeouts won't retry
);

This lets you be stricter than the default (retry connection failures but not timeouts, say). It cannot make a non-transport error retryable — that set is the floor.

When retries run out

After the last delay, withRetry gives up by throwing RetryExhaustedException, which packages the final failure for inspection:

import 'package:tom_basics_network/tom_basics_network.dart';

try {
  await withRetry(_doRequest, config: const RetryConfig(retryDelaysMs: [50, 50]));
} on RetryExhaustedException catch (e) {
  print('Gave up after ${e.attempts} attempts; last error: ${e.lastError}');
  // e.lastStackTrace is available for logging the original failure site.
}

Server discovery

How a scan proceeds

ServerDiscovery looks for a Tom server by probing candidate hosts in order of likelihood:

ServerDiscovery.discover(options)
        │
        ├─ 1. localhost            (the same machine)
        ├─ 2. local IPv4 addresses (this host's LAN interfaces)
        └─ 3. /24 subnet           (the other 253 hosts) — only if scanSubnet
                 │
                 └─ for each candidate: GET http://<host>:<port><statusPath>
                        expect 200 + JSON object → DiscoveredServer

Each probe is a single GET to http://<host>:<port><statusPath> with a short timeout. A host qualifies when it answers 200 with a JSON object body; that object becomes the DiscoveredServer.status map. Subnet scanning is batched so no more than maxConcurrent probes are in flight at once.

Choosing the right entry point

import 'package:tom_basics_network/tom_basics_network.dart';

// Best effort — null when nothing answers.
final maybe = await ServerDiscovery.discover();

// Every server on the network (e.g. to pick or list them).
final all = await ServerDiscovery.discoverAll();
print('Found ${all.length} server(s).');

<a id="fail-loudly-when-no-server-is-found"></a> When a missing server is a hard error, discoverOrThrow saves you the null-check:

import 'package:tom_basics_network/tom_basics_network.dart';

try {
  final server = await ServerDiscovery.discoverOrThrow();
  print('Connected to ${server.serverUrl}');
} on DiscoveryFailedException catch (e) {
  print('Discovery failed: $e');
}

Tuning the scan

DiscoveryOptions controls every knob; all fields have defaults and copyWith makes per-call tweaks ergonomic:

import 'package:tom_basics_network/tom_basics_network.dart';

const base = DiscoveryOptions(
  port: 8080,           // default 19880
  scanSubnet: false,    // localhost + local IPs only — fast, no subnet sweep
);

final verbose = base.copyWith(
  timeout: const Duration(seconds: 1),
  logger: print,       // trace each candidate as it is probed
);

Use statusValidator to reject servers that answer but aren't the one you want — for example, requiring a specific service name:

import 'package:tom_basics_network/tom_basics_network.dart';

const options = DiscoveryOptions(
  statusValidator: _isLedgerService,
);

bool _isLedgerService(Map<String, dynamic> status) =>
    status['service'] == 'tom_dist_ledger';

Reading a discovered server

DiscoveredServer pairs the URL with the parsed status payload and surfaces the common fields as typed getters:

import 'package:tom_basics_network/tom_basics_network.dart';

void describe(DiscoveredServer s) {
  print('URL:     ${s.serverUrl}');
  print('Service: ${s.service}');   // status['service']
  print('Version: ${s.version}');   // status['version']
  print('Port:    ${s.port}');      // status['port']
  // Anything else is in s.status, the raw decoded JSON map.
}

Working with addresses directly

The two address helpers that drive the scan are public, so you can reuse them for your own probing:

import 'package:tom_basics_network/tom_basics_network.dart';

Future<void> main() async {
  final mine = await ServerDiscovery.getLocalIpAddresses();
  print('This host: $mine');

  // Every other host in a /24, excluding the address you pass in.
  final peers = ServerDiscovery.getSubnetAddresses('192.168.1.100');
  print('${peers.length} candidates'); // 253: .1 … .254 minus .100
}

---

Architecture

package:tom_basics_network/tom_basics_network.dart   (single entry point)
        │
        ├── src/http_retry.dart
        │     withRetry<T>()  ──uses──▶ RetryConfig ──holds──▶ delays + onRetry
        │         │
        │         ├─ classifies errors  (SocketException, TimeoutException, …)
        │         ├─ RetryableResponse   (status-code helper on http.Response)
        │         └─ throws RetryExhaustedException when the budget is spent
        │
        └── src/server_discovery.dart
              ServerDiscovery (static)
                  │  discover / discoverOrThrow / discoverAll
                  ├─ getLocalIpAddresses / getSubnetAddresses
                  ├─ probes GET <host>:<port><statusPath>
                  └─ DiscoveryOptions → DiscoveredServer | DiscoveryFailedException

The package exposes no mutable singletons and no initialisation step. Both subsystems are pure functions over immutable configuration, which keeps them trivially testable and isolate-safe.

---

Ecosystem

tom_basics_network is one of the tom_ai/basics foundation packages:

• tom_basics — exceptions, logging, the platform seam, and

the runtime model that the rest of the basics layer builds on. - tom_basics_console — the standalone/server platform implementation, including an IO-based HTTP client that pairs naturally with withRetry.

This package depends on neither — it stands alone on package:http and dart:io — but it is built to sit alongside them in a Tom application. A typical server uses tom_basics_console for its platform layer, withRetry to harden its outbound calls, and ServerDiscovery to locate its peers.

---

Further documentation

• example/tom_basics_network_example.dart

— runnable demonstration of the retry schedule. - test/tom_basics_network_test.dart — the behavioural specification: retry success/exhaustion, error classification, subnet maths, and option defaults. - ../README.md — the tom_ai/basics package map.

---

Status

• Version: 1.0.1
• Tests: 12 passing (dart test) — RetryConfig,

RetryExhaustedException, withRetry, and ServerDiscovery. - Analysis: clean under package:lints (dart analyze — no issues). - Platforms: any Dart runtime with dart:io (desktop, server, CLI).

license.md

BSD 3-Clause License

Copyright (c) 2024-2026, Peter Nicolai Alexis Kyaw
Find me on LinkedIn under Alexis Kyaw
All rights reserved.

Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions are met:

1. Redistributions of source code must retain the above copyright notice, this
   list of conditions and the following disclaimer.

2. Redistributions in binary form must reproduce the above copyright notice,
   this list of conditions and the following disclaimer in the documentation
   and/or other materials provided with the distribution.

3. Neither the name of the copyright holder nor the names of its
   contributors may be used to endorse or promote products derived from
   this software without specific prior written permission.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

CHANGELOG.md

2.6.25

Added

• Shared end-of-run summary block for every tom_build_base tool — ToolResult.renderRunSummary() produces a single, consistent errors/skips report so outcomes are easy to read after a long run, instead of each tool re-implementing its own footer. The block lists a === Skipped === section (deliberately skipped items) above either a === Errors === section naming every failed item with an N error(s) in M project(s). tally, or the clean Done. No errors. footer when nothing failed. It returns an empty string when no items were processed (e.g. --version/--help/single-shot commands), so callers can print it unconditionally without a spurious footer. New ItemResult.skipped(...) constructor + ItemResult.skipped flag distinguish a configured/conditional skip (a non-failing success that never affects the exit code) from real work; the runner preserves the flag when tagging results. Covered by regression tests SUMM01–SUMM13.

2.6.24

Fixed

• Non-ASCII tool/subprocess output now renders correctly on Windows — added a UTF-8 console + process-output guard (console_encoding.dart). ProcessRunner.run/runShell and the shell executor now capture raw bytes and decode them as UTF-8 (decodeProcessOutput, tolerating malformed sequences) instead of relying on the host's ANSI code page, which previously turned UTF-8 diagnostics such as dart compile's "für" into double-mojibake ("für"). ToolRunner.run calls enableUtf8Console() at startup, which switches the Windows console code pages to UTF-8 (CP_UTF8, the chcp 65001 equivalent via kernel32) and routes the stdout/stderr sinks through UTF-8. No-op on non-Windows hosts and idempotent. Streaming decoders now tolerate malformed bytes so a single bad chunk no longer aborts the rest of the stream. Covered by regression tests ENC01–ENC09.

2.6.23

Fixed

• Per-command value options no longer shadowed by colliding global flags — a command that declares its own value-bearing option (e.g. versioner's --version <v> override) now receives the value when invoked as buildkit :versioner --version 9.9.9, instead of the token being captured by the global --version print-version flag. A bare --version (no value) still prints the tool version. Covered by regression tests BB-CLI-93–BB-CLI-95.

2.6.22

Fixed

• --help no longer advertises macros/defines/pipelines in an ineligible context — the runtime macro / persistent define help appendix is now gated on _isMacroDefineFeatureEligible() (a <tool>_master.yaml exists in the workspace), matching the gating already applied to the commands themselves. Previously the appendix was shown whenever the tool was multiCommand, even with no master yaml present, misleading users about unavailable features.
• --project <absolute path> now matches the target project on every platform — FilterPipeline project matching previously only recognised path patterns containing /, and never compared a folder's full path. A --project argument given as an absolute filesystem path (e.g. versioner --project C:\repo\_build on Windows, or any absolute POSIX path) therefore matched zero projects. Project/path matching is now separator-agnostic (/ and \ are equivalent) and absolute paths are compared against each folder's own path (case-insensitively on Windows). Covered by regression tests BB-FLT-41–BB-FLT-44.

2.6.21

Fixed

• Nested mode executes per-project logic — _runNestedMode and _runNestedCommand now create a CommandContext from CWD and call execute() instead of the no-op executeWithoutTraversal(). This fixes nested tools (e.g., d4rtgen called via buildkit) silently doing nothing.

2.6.20

Fixed

• Cross-platform path display — CommandContext.relativePath now always uses forward slashes, preventing backslash stripping by console markdown on Windows.

2.6.19

Added

• ItemResult.commandName — Optional field to track which command produced each result (e.g., 'runner', 'compiler'). Populated by ToolRunner when executing command chains.

Changed

• Compact tool output — ToolRunner now always prints one-line-per-command status ( -> :cmd message) instead of verbose multi-line output. Project headers (>>> path) are always shown.
• Nested tool output buffering — NestedToolExecutor buffers subprocess stdout/stderr and only displays on error, signal words, or --verbose mode.

2.6.18

Changed

• Project-name alias matching — Project resolution and filtering now treat pubspec.yaml name as a first-class project-name alias alongside tom_project.yaml and buildkit.yaml metadata.
• Workspace boundary markers — tom_workspace.yaml is no longer used as a workspace boundary marker; workspace boundary detection now relies on buildkit_master.yaml.

2.6.14

Added

• print pipeline prefix — Added a dedicated print <message> command prefix for pipelines to emit resolved messages without shell invocation.
• Mklink executor API — Added dcli-backed symlink execution support (MkLinkExecutor) for reusable cross-platform link creation in tool implementations.

Changed

• Pipeline help examples — Updated built-in help topic examples to use print for message output instead of shell-based echo commands.

2.6.13

Changed

• Repository ID lookup source — RepositoryIdLookup now reads repository_id and name from tom_repository.yaml files in the workspace instead of using a hardcoded ID map.
• Module filter resolution — --modules and --skip-modules resolution now uses workspace metadata (tom_repository.yaml) via execution-root-aware lookup.

Added

• Lookup cache controls — Added RepositoryIdLookup.clearCache() for test/runtime cache invalidation when repository metadata changes.

2.6.12

Fixed

• Bootstrap environment bypass — TOM_BOOTSTRAP_ALLOW_MISSING_SETUP=1 environment variable now correctly bypasses required-environment checks in ToolRunner.run(). This allows bootstrap_binaries.sh to run the versioner step even when optional binaries (astgen, reflector) are not yet installed. The :doctor command always runs full checks regardless of the bypass.

2.6.6

Fixed

• FolderScanner recursive semantics — The recursive flag now correctly controls recursion inside project directories only. Non-project (container) directories are always traversed to find projects, which is the fundamental purpose of scanning. Previously, recursive: false (the default) stopped all descent after the scan root, meaning nested projects inside container directories were never found.

Documentation

• Corrected FolderScanner.scan() doc to explain that recursive controls descent into project folders (containing pubspec.yaml), not overall directory traversal.
• Corrected CliArgs.toProjectTraversalInfo() doc: hardcoded default is recursive: false, and clarified that non-project directories are always traversed regardless of the flag.

2.6.5

Fixed

• Pipeline nested workspace discovery — _discoverNestedWorkspaces now skips test/, build/, node_modules/, and example/ directories when searching for nested workspaces to delegate pipeline execution to. Previously, buildkit_master.yaml files inside test fixtures (e.g., test/fixtures/) were incorrectly treated as real nested workspaces, causing pipeline delegation failures.

2.6.4

Fixed

• Nature parsing in tool wiring — ToolDefinitionSerializer.fromYamlMap() now correctly parses works_with_natures and required_natures fields from --dump-definitions YAML output. Previously, these fields were only serialized (via toYaml()) but not parsed when deserializing, causing nested tool commands to fail with "has no nature configuration" errors during wiring.

Added

• Private helpers — Added _stringToType() to convert nature type names ("DartProjectFolder", "FsFolder", etc.) back to Type objects, and _parseNaturesList() to parse YAML lists to Set<Type>.

2.6.3

• versionString support — Added optional versionString field to ToolDefinition for custom version display format. When set, --version will output this string instead of the default "name version" format.

2.6.2

• Build fixes — Minor fixes for tool compilation.

2.6.1

• Fix: Added missing WorkspaceScanner export to both barrel files (tom_build_base.dart and tom_build_base_v2.dart)

2.6.0

Breaking Changes

• Removed V1 API — The following V1 classes, functions, and files have been removed:
• ConfigLoader, LoadedConfig, PlaceholderDefinition, PlaceholderContext, resolvePlaceholders() (config_loader.dart)
• ConfigMerger (config_merger.dart)
• ProcessingResult — V1 version removed (processing_result.dart); V2 ToolResult/ItemResult remains
• isPathContained(), validatePathContainment() (path_utils.dart)
• isBuildYamlBuilderDefinition(), hasBuildYamlConsumerConfig(), isBuildYamlBuilderEnabled(), getBuildYamlBuilderOptions() (build_yaml_utils.dart)
• showVersions(), ShowVersionsResult, ShowVersionsOptions, readPubspecVersion() (show_versions.dart)
• bin/show_versions.dart CLI tool
• Unified barrel — tom_build_base.dart now exports the full API (framework + utility classes). The tom_build_base_v2.dart barrel is still available for backwards compatibility.
• Retained utility classes — TomBuildConfig, hasTomBuildConfig(), ProcessRunner, ToolLogger, yamlToMap(), yamlListToList(), toStringList() remain available.

2.5.16

Added

• Comprehensive help topics — Added definesHelpTopic, macrosHelpTopic, pipelinesHelpTopic, wiringHelpTopic as built-in help topics. All multiCommand tools automatically expose these via help defines, help macros, help pipelines, help wiring.
• --modes in global help — Added --modes to commonOptions so it appears in --help output for all tools.
• {TOOL} placeholder in help topics — generateTopicHelp() now replaces {TOOL} with the tool name in help topic content.
• Placeholder resolution in pipeline shell/stdin — shell and stdin pipeline commands now resolve standard %{...} placeholders (root, current-os, current-platform, etc.) before execution. shell-scan already had full placeholder support.

Changed

• Pipeline help — Converted hardcoded pipeline help from tool_runner.dart to a proper HelpTopic. Updated documentation to use correct %{...} placeholder syntax.
• Macro/define help routing — help defines and help macros now show comprehensive topic documentation instead of brief command summaries.
• Help appendix — Global help appendix now lists all 5 help topics (defines, macros, pipelines, placeholders, wiring).

2.5.15

Added

• cli_arg_parser.dart — Added --modes as a recognized global CLI flag. Accepts comma-separated mode names (e.g., --modes DEV or --modes DEV,CI). Parsed into CliArgs.modes as List<String>.
• tool_runner.dart — @[name] define placeholders are now resolved per-folder during traversal. Defines are loaded from {tool}_master.yaml (default + mode-specific sections based on --modes), then merged with per-project buildkit.yaml defines (project overrides master). Resolution happens after %{name} placeholder resolution and before executor execution.
• tool_runner.dart — Per-project buildkit.yaml define loading: project-level buildkit.yaml files can override master defines via defines: or {tool}: defines: sections, including mode-specific {MODE}-defines: sections.

2.5.14

Fixed

• macro_expansion.dart — Missing positional arguments ($1–$9) in macros are now treated as empty strings instead of throwing MacroExpansionException. This allows macros like @vc to be invoked without arguments even when the macro value contains placeholders.

2.5.13

Improved

• tool_runner.dart — When :macro, :define, :defines, :undefine, :unmacro, or :macros commands are used but {tool}_master.yaml cannot be found, a clear error message is shown explaining which file is missing and the detected workspace root. Previously these commands silently fell through to "Unknown command".
• tool_runner.dart — Help text for macro/define/pipeline commands is now shown even when the master yaml is missing, so users can understand how to set things up.

2.5.12

Fixed

• tool_runner.dart — Macro expansion (@macroName) now actually works. The expandMacros() function from macro_expansion.dart was never called during run(), so @macro invocations were passed through unparsed. Expansion now happens before arg parsing, after loading persisted macros.

2.5.11

Added

• tool_definition.dart — Added versionString property to ToolDefinition for custom --version output. When provided, this string (typically from versioner-generated code) is shown instead of the default "name vX.X.X" format.
• tool_runner.dart — :define and :undefine commands now support -m MODE or --mode MODE flag for mode-specific defines (e.g., buildkit :define -m DEV DEBUG=true).
• tool_runner.dart — :defines command now lists all defines including mode-specific ones (e.g., DEV-defines:, CI-defines:).
• tool_runner.dart — Macros now stored in {tool}_master.yaml under macros: section instead of separate {tool}_macros.yaml file.
• tool_runner.dart — Defines stored under {tool}: section in master.yaml with structure: {tool}: defines: for default and {tool}: {MODE}-defines: for mode-specific.

Changed

• cli_arg_parser.dart — Extended special-case greedy argument handling to include :undefine command (all args after :undefine are treated as positional to allow -m MODE name syntax).

2.5.10

Fixed

• tool_runner.dart — Runtime macros (:macro, :macros, :unmacro) now persist to {workspace_root}/{tool_name}_macros.yaml. Previously, macros defined in one buildkit invocation were lost in the next invocation because they were stored only in an in-memory map. The file is written on every add/remove and loaded lazily on the first macro operation of each invocation; it is deleted automatically when the last macro is removed.

2.5.9

Fixed

• cli_arg_parser.dart — :command tokens appearing after a :macro or :define command are now treated as positional arguments (part of the macro value) rather than being dispatched as separate commands. Previously, buildkit :macro vc=:v $1 :comp $2 would execute :comp immediately and store only :v as the macro value. Now the full token sequence is captured as the value.

2.5.6

Fixed

• cli_arg_parser.dart — Global navigation/feature flags (--dry-run, --verbose, -n, -v, --force, --list, etc.) now route to global state regardless of whether they appear before or after a command name. Previously buildkit :compiler --dry-run was silently ignored; now it works identically to buildkit --dry-run :compiler.

2.5.5

Added

• tool_runner.dart — Added required-environment validation support from <tool>_master.yaml (including buildkit_master.yaml fallback for buildkit), with checks for environment variables, folders, binaries, and caret-version constraints.
• tool_runner.dart — Added doctor-mode execution flow for tools: doctor requests now print requirement warnings/errors and return success/failure based on hard requirement violations.

Fixed

• tool_runner.dart — Normalized doctor token detection so both doctor and :doctor forms are recognized consistently in positional and command argument paths.

2.5.4

Fixed

• cli_arg_parser.dart — Fixed short option abbreviation collision when multiple commands share the same abbreviation (e.g. -c used by both runner and execute). _shortToLong now prioritizes the current command's options before falling through to all commands.

2.5.3

Changed

• execute_placeholder.dart — Migrated placeholder syntax from ${...} to %{...} to avoid shell variable expansion (${}) and YAML comment stripping (#{} after whitespace). All regex patterns, error messages, and help text updated.
• builtin_help_topics.dart — Updated all placeholder documentation to use %{...} syntax.

2.5.2

Changed

• repository_id_lookup.dart — Removed CRPT (tom_module_crypto) and COM (tom_module_communication) repository IDs after module consolidation into tom_module_basics.

2.5.1

Fixed

• builtin_help_topics.dart — Escaped * in placeholders help topic context reference table to prevent console_markdown from consuming it as italic markup.

2.5.0

Added

• console_markdown_zone.dart — Central console_markdown integration via Dart zones. Provides runWithConsoleMarkdown() (async) and runWithConsoleMarkdownSync() to wrap CLI tool execution in a zone that renders markdown syntax (**bold**, <cyan>text</cyan>, etc.) to ANSI escape codes.
• console_markdown_zone.dart — ConsoleMarkdownSink wrapper class for StringSink that applies .toConsole() rendering to all writes, enabling markdown rendering on stdout/stderr sinks.
• console_markdown_zone.dart — isConsoleMarkdownActive getter and kConsoleMarkdownZoneKey zone key for double-processing detection. Prevents nested zones (e.g. when tom_d4rt_dcli already wraps output).
• tool_runner.dart — ToolRunner now automatically wraps its output sink with ConsoleMarkdownSink when running inside a console_markdown zone, so all output.writeln() calls render markdown.
• pubspec.yaml — Added console_markdown: ^0.0.3 dependency.

2.4.0

Added

• execute_placeholder.dart — resolveCommand() now accepts skipUnknown parameter. When true, unrecognized placeholders are left as-is instead of throwing, enabling multi-phase resolution (e.g., general placeholders first, then compiler-specific ones).
• execute_placeholder.dart — Added ExecutePlaceholderContext.fromCommandContext() factory for easy creation from traversal's CommandContext.
• cli_arg_parser.dart — Added CliArgs.withResolvedStrings() method to create a copy with placeholders resolved in positional args, extra options, and per-command options.
• tool_runner.dart — ToolRunner now automatically resolves general placeholders (${folder}, ${dart.name}, etc.) in all CLI args per folder during traversal, giving universal placeholder support to all commands.
• tom_build_base_v2.dart — Exported execute_placeholder.dart from the v2 barrel.

2.3.0

Added

• help_topic.dart — New HelpTopic class for named help sections (topic content, summary, name).
• builtin_help_topics.dart — Built-in placeholdersHelpTopic with comprehensive placeholder documentation.
• tool_definition.dart — Added helpTopics field and findHelpTopic() method.
• help_generator.dart — Added generateTopicHelp() and "Help Topics" section in tool help.
• special_commands.dart — Help topic lookup in handleSpecialCommands() and generatePlainToolHelp().
• tool_runner.dart — Help topic lookup before "Unknown command" error.

2.2.0

Added

• filter_pipeline.dart — Added _matchesRelativePath() and _isPathPattern() for path-based pattern matching in --exclude-projects and --project filters. Patterns containing / (e.g., core/tom_core_kernel) are now matched against relative paths using glob matching, enabling directory-scoped project exclusion.
• filter_pipeline.dart — Updated matchesProjectPattern() to accept optional executionRoot parameter for path-based matching.
• tool_runner.dart — ToolRunner.run() now handles bare version as a positional arg (in addition to --version/-V), consistent with handleSpecialCommands.
• help_generator.dart — generateCommandHelp() now includes a "Common Options" section showing --help, --verbose, and --dry-run.
• tool_runner.dart — Per-command matchesProjectPattern() calls now pass executionRoot for path-based pattern support.

2.1.0

Added

• navigation_bridge.dart — Re-introduces WorkspaceNavigationArgs, addNavigationOptions(), preprocessRootFlag(), parseNavigationArgs(), resolveExecutionRoot(), isVersionCommand(), isHelpCommand() as v2-clean code (dart:io only, no DCli dependency). These bridge the package:args ArgParser to the v2 traversal system for tools that use ArgParser for global option parsing.
• Exported from both tom_build_base.dart and tom_build_base_v2.dart barrels.

2.0.0

Breaking Changes — V1 Navigation System Removed

Deleted the entire v1 project navigation/discovery system:

• workspace_mode.dart — WorkspaceNavigationArgs, ExecutionMode, addNavigationOptions(), parseNavigationArgs(), preprocessRootFlag(), resolveExecutionRoot(), and related helpers are removed.
• project_discovery.dart — ProjectDiscovery class (including scanForProjects(), resolveProjectPatterns(), hasSkipFile(), getSkipFileName(), applyModulesFilter(), findGitRepositories(), filterByModules(), resolveModulePaths()) is removed.
• project_navigator.dart — ProjectNavigator, NavigationConfig, NavigationResult, NavigationDefaults are removed.
• project_scanner.dart — ProjectScanner class is removed.

Migration

All these APIs have v2 replacements in tom_build_base_v2.dart:

Preserved APIs

• findWorkspaceRoot() — Moved to workspace_utils.dart (exported from both barrels). Same API, now uses dart:io instead of DCli.
• kBuildkitMasterYaml, kTomWorkspaceYaml, kTomCodeWorkspace, kBuildkitSkipYaml — Constants moved to workspace_utils.dart.
• isWorkspaceBoundary() — Moved to workspace_utils.dart.
• All shared utility files (build_config.dart, config_loader.dart, config_merger.dart, tool_logging.dart, path_utils.dart, processing_result.dart, yaml_utils.dart, build_yaml_utils.dart, show_versions.dart) are unchanged.

Internal

• show_versions.dart — Migrated from ProjectDiscovery/ProjectScanner to inline directory scanning with dart:io and glob.
• Removed v1-specific tests (10 tests removed; 547 remaining tests pass).

1.15.0

Breaking Changes

• Renamed --all / -a to --no-skip — The global CLI option that ignores skip markers (tom_skip.yaml, *_skip.yaml) has been renamed from --all / -a to --no-skip (no abbreviation). This resolves conflicts with per-command -a/--all options in buildkit tools (dependencies, publisher, gitcommit, gitbranch).

Features

• --no-skip flag in v1 system — Added noSkip field to WorkspaceNavigationArgs, wired through addNavigationOptions(), parseNavigationArgs(), ProjectDiscovery.scanForProjects(), and ProjectNavigator. Both v1 (buildkit ArgParser) and v2 (CliArgs) systems now support --no-skip.

• --no-skip in projectTraversalOptions — Added to the standard v2 option definitions for consistent help output.

1.14.0

Features

• AnchorWalker class — New utility for walking up the directory tree to find workspace/repository root "anchor" directories. Anchors are identified by .git (directory or file), tom_workspace.yaml, or buildkit_master.yaml markers. Enables reusable upward-search logic for tools like goto.

1.13.0

Features

• --all / -a flag — New CLI option to traverse into folders that would normally be skipped (subworkspaces, tom_skip.yaml, <tool>_skip.yaml). Skip messages still print but traversal continues. (Renamed to --no-skip in 1.15.0)

• Skip messages to stderr — FolderScanner now always prints skip messages to stderr when encountering workspace boundaries or skip marker files: "Skipping subworkspace: \<folder\>", "Skipping - tom_skip.yaml found: \<folder\>", "Skipping - \<tool\>_skip.yaml found: \<folder\>".

Bug Fixes

• allGlobalOptions dedup precedence — Fixed option deduplication to use first-wins (putIfAbsent) instead of last-wins. User-defined globalOptions now correctly take precedence over commonOptions defaults.

Code Quality

• Fixed unnecessary_brace_in_string_interps lint issues in completion_generator.dart.
• Fixed curly_braces_in_flow_control_structures lint issues in nature_detector.dart.

1.12.0

Features

• BuildkitFolder.projectName — BuildkitFolder nature now reads the name field from buildkit.yaml, enabling project name matching for buildkit-configured projects.

• --project ID and name matching — FilterPipeline now matches --project values against project IDs and names from both tom_project.yaml and buildkit.yaml:
• TomBuildFolder: matches project_id and short-id fields
• BuildkitFolder: matches id and name fields
• Case-insensitive matching

• handleSpecialCommands() — New utility function for tools to handle help and version commands consistently without custom parsing.

• BuildOrderComputer — Topological sort (Kahn's algorithm) moved from tom_build_kit to tom_build_base. Available for any tool that needs dependency-ordered traversal.

Breaking Changes

• Nature filtering is now mandatory — BuildBase.traverse() throws ArgumentError if neither requiredNatures nor worksWithNatures is configured. Previously, null requiredNatures silently visited all folders. Tools that want all folders must now set requiredNatures: {FsFolder} or worksWithNatures: {FsFolder} explicitly.

• ToolRunner validates nature config — ToolRunner._runWithTraversal() returns ToolResult.failure with an error message before traversal starts if no nature configuration is present on the command.

Bug Fixes

• Nature detection before filter application — Fixed BuildBase.traverse() to detect folder natures before applying project filters. Previously, applyProjectFilters() was called before detectNatures(), causing ID/name-based --project matching to always fail.

• tom_project.yaml field name — NatureDetector._createTomProjectNature() now reads project_id (underscore) in addition to short-id (hyphen) from tom_project.yaml.

Internal

• ToolLogger / ProcessRunner — Central logging infrastructure with --verbose support for consistent tool output.

---

1.11.0

Features

• Command prefix matching — findCommand() now supports unambiguous command prefixes.
• :vers matches :versioner if no other command starts with "vers"
• :co is ambiguous if both :compiler and :config exist, returns null
• Exact matches (name or alias) always take priority over prefix matches
• findCommandsWithPrefix() returns all commands matching a prefix (for error messages)

• Improved error messages — When a prefix is ambiguous, tool shows all matching commands.

---

1.10.0

Features

• ExecutePlaceholderResolver — New placeholder resolution system for execute commands.
• Path placeholders: ${root}, ${folder}, ${folder.name}, ${folder.relative}
• Platform placeholders: ${current-os}, ${current-arch}, ${current-platform}
• Nature existence (boolean): ${dart.exists}, ${flutter.exists}, ${git.exists}, etc.
• Nature attributes: ${dart.name}, ${dart.version}, ${git.branch}, etc.
• Ternary syntax: ${condition?(true-value):(false-value)} for boolean placeholders
• checkCondition() for filtering based on boolean placeholders

• ExecutePlaceholderContext — Context class holding folder, root, and natures for resolution.

• UnresolvedPlaceholderException — Exception thrown when placeholder cannot be resolved.

---

1.9.0

Breaking Changes

• Default traversal behavior changed:
• Default is now --scan . -R --not-recursive (workspace mode, single directory)
• Previously defaulted to current directory without workspace root detection
• Use -r flag to explicitly enable recursive traversal

Features

• Traversal cascade: CLI options > buildkit_master.yaml navigation > hardcoded defaults
• Explicit CLI tracking: scanExplicitlySet and recursiveExplicitlySet fields in CliArgs
• TraversalDefaults class: Loads navigation defaults from buildkit_master.yaml
• Git mode validation: toGitTraversalInfo() now returns null if git mode not specified
• WorkspaceScanner: Unified scanning API with FolderScanner + NatureDetector
• Top repository navigation (-T, --top-repo): Traverse up to find topmost git repo
• DartProjectFolder.isPublishable: Check if package can be published to pub.dev

Classes Modified

• CliArgs — Added scanExplicitlySet, recursiveExplicitlySet fields
• TraversalDefaults — New class for config defaults with fromMap() factory
• ToolRunner._runWithTraversal() — Loads defaults, applies cascade, validates git mode
• _ParseState — Tracks explicit CLI options

---

1.11.0

Features

• WorkspaceScanner — Unified scanning API combining FolderScanner + NatureDetector.
• scan() returns ScanResults with type-safe byNature<T>() filtering.
• findGitRepos(), findDartProjects(), findPublishable() — Nature-based queries.
• findGitRepoPaths(), findDartProjectPaths(), findPublishablePaths() — Path convenience methods.
• FolderContext provides folder + natures together with hasNature<T>(), getNature<T>().

• DartProjectFolder.isPublishable — New getter to check if package can be published to pub.dev.

Exports

• V2 traversal API now exported from main barrel: WorkspaceScanner, GitFolder, DartProjectFolder, etc.

---

1.10.0

Features

• Top repository navigation (-T, --top-repo) — New git traversal option.
• Traverses UP the directory tree to find the topmost (outermost) git repository.
• Uses that repository as the root for subsequent traversal.
• Can be combined with -i (inner-first-git) or -o (outer-first-git).
• Added GitRepoFinder.findTopRepo() method for upward git repo discovery.
• Example: buildkit -T -i :compile — finds top repo, then processes inner repos first.

Classes Modified

• CliArgs — Added topRepo field.
• WorkspaceNavigationArgs — Added topRepo field and updated execution mode detection.
• GitRepoFinder — Added findTopRepo(String startPath) method.
• ProjectNavigator — Integrated topRepo option in navigation.
• CliArgParser — Added parsing for -T and --top-repo flags.
• OptionDefinition — Added top-repo to gitTraversalOptions.

---

1.9.0

Features

• DCli integration — Refactored file operations to use DCli library for improved code readability.
• File(path).existsSync() → exists(path)
• File(path).readAsStringSync() → read(path).toParagraph()
• Directory(path).listSync() → find('*', types: [Find.directory])
• Improved directory filtering with DCli's find() type filtering.

Dependencies

• Added dcli package as dependency for file and directory operations.

Files Refactored

• build_config.dart — Config file loading
• build_yaml_utils.dart — Build.yaml utilities
• config_loader.dart — Configuration loading with placeholders
• project_discovery.dart — Project discovery and scanning
• project_scanner.dart — Project validation and scanning
• show_versions.dart — Version display functionality
• workspace_mode.dart — Workspace navigation utilities

---

1.8.0

Features

• ConfigLoader class — New unified configuration loader with mode processing and placeholder resolution.
• Loads {basename}_master.yaml (workspace) and {basename}.yaml (project) configuration files.
• Processes mode-prefixed keys (e.g., DEV-target, CI-enabled) with merging behavior.
• Resolves @[...] define placeholders from the defines: section.
• Resolves @{...} tool placeholders (project-path, project-name, workspace-root, etc.).
• Custom tool placeholders via PlaceholderDefinition.

• Mode system — Workspace-wide configuration dimensions.
• --modes CLI option to override active modes (e.g., --modes=DEV,CI).
• Mode sources: CLI option (highest) → tom_workspace.yaml default.
• UPPERCASE mode prefixes merge in order, later modes override earlier.

• Skip file system — Directory-level skip markers.
• tom_skip.yaml — Skips directory for ALL tools.
• {basename}_skip.yaml — Skips directory for specific tool only.
• Skip reason readable from YAML reason: field.

• resolvePlaceholders() function — Standalone placeholder resolution utility.
• Supports @[...] defines, @{...} tool placeholders.
• Environment variable resolution with $VAR and $[VAR] syntax.
• Recursive resolution (max depth 10).

API Changes

• New config_loader.dart exported from tom_build_base.dart.
• WorkspaceNavigationArgs.modes — New field for active modes.
• addNavigationOptions() registers --modes option.
• parseNavigationArgs() parses modes as comma-separated, uppercased values.
• ProjectNavigator accepts optional toolBasename parameter for tool-specific skip files.
• ProjectDiscovery.hasSkipFile(basename) — Updated signature with basename parameter.
• ProjectDiscovery.getSkipFileName(basename) — Returns tool-specific skip filename.
• ProjectDiscovery.globalSkipFileName — Constant for tom_skip.yaml.
• v2 FolderScanner — Now supports tool-specific skip files:
• Constructor accepts toolBasename parameter (defaults to 'buildkit').
• Checks for tom_skip.yaml (global skip for all tools).
• Checks for {toolBasename}_skip.yaml (tool-specific skip).
• New skipFilename getter returns tool-specific skip filename.
• New kTomSkipYaml constant exported.

1.7.1

• Changelog update for 1.7.0 features.

1.7.0

Features

• ProjectNavigator class — New unified project navigation and discovery class that can be shared across CLI tools. Supports all navigation modes: project patterns, directory scanning, git-based traversal.
• NavigationConfig class — Configurable opt-in/opt-out for navigation features (path exclude, name exclude, modules filter, skip files, master config defaults, build order, git traversal).
• NavigationDefaults class — Navigation defaults loaded from master config.
• NavigationResult class — Result container with discovered paths and metadata.
• Build order sorting — ProjectNavigator.sortByBuildOrder() uses Kahn's algorithm for dependency-based topological sorting.
• Git repository discovery — ProjectNavigator.findGitRepositories() recursively scans for .git folders.
• Static filter methods — filterByPath(), filterByName(), filterSkippedProjects(), hasSkipFile().
• Master config loading — loadNavigationDefaults() and loadMasterExcludeProjects() static methods.

API Changes

• New project_navigator.dart exported from tom_build_base.dart.
• kBuildkitSkipYaml constant now exported from workspace_mode.dart.
• toStringList() utility added to yaml_utils.dart.

1.6.0

Features

• --no-recursive support — The --recursive flag is now negatable. Pass --no-recursive to suppress recursion when applied via buildkit.yaml or parent directories.
• --no-build-order support — The --build-order flag is now negatable. Pass --no-build-order to skip dependency-based sorting.
• recursiveExplicitlySet field — WorkspaceNavigationArgs now tracks whether the -r, --recursive flag was explicitly set by the user, allowing downstream tools to distinguish between defaulted and explicit values.

API Changes

• WorkspaceNavigationArgs.recursiveExplicitlySet — New boolean field indicating explicit user setting.
• parseNavigationArgs() now uses wasParsed('recursive') to detect explicit usage.
• withDefaults() and withProjectModeDefaults() respect explicit settings and don't override them.

1.5.0

Features

• --modules / -m navigation option — New include filter to limit project discovery to specific git modules (repositories). Comma-separated list of module names (e.g., --modules tom_module_d4rt,tom_module_basics). Use "root" or "tom" to reference the main repository.
• ProjectDiscovery.findGitRepositories() — Static method to discover all git repositories in a workspace.
• ProjectDiscovery.resolveModulePaths() — Resolve module names to absolute paths.
• ProjectDiscovery.filterByModules() — Filter project list to only those within specified modules.
• ProjectDiscovery.applyModulesFilter() — Convenience method combining resolution and filtering.

API Changes

• WorkspaceNavigationArgs now includes a modules field (List<String>).
• addNavigationOptions() registers the -m, --modules option.
• parseNavigationArgs() parses the modules option as comma-separated values.
• Help text updated with modules documentation.

1.3.2

Internal

• Config filename standardization — Updated all code references from tom_build.yaml to buildkit.yaml. The TomBuildConfig.projectFilename constant was already correct; this release ensures hasTomBuildConfig() and ProjectDiscovery.getProjectRecursiveSetting() use the constant instead of hardcoded strings.

1.3.0

Features

• yamlToMap() utility — Public function to recursively convert YamlMap to plain Map<String, dynamic>. Eliminates private YAML-to-Map conversion duplicated across build tools.
• yamlListToList() utility — Companion function to recursively convert YamlList to plain List<dynamic>.

Internal

• Replaced private _convertYamlToMap in build_config.dart and _yamlToMap/_yamlListToList in build_yaml_utils.dart with the shared public utilities.

1.2.0

Features

• show_versions CLI tool — New executable in bin/show_versions.dart. Run via dart run tom_build_base:show_versions [workspace-path] or install globally with dart pub global activate tom_build_base.
• showVersions() library function — Importable API in lib/src/show_versions.dart that discovers projects and reads their pubspec versions. Returns a structured ShowVersionsResult.
• readPubspecVersion() helper — Reusable function to read the version: field from any project's pubspec.yaml.

Improvements

• Example file now delegates to the library function instead of reimplementing the logic.

1.1.0

Improvements

• Comprehensive example — Rewrote the example as a show_versions CLI tool that exercises every library feature: config loading & merging, project scanning & discovery, build.yaml utilities, path validation, and result tracking.
• Updated user guide — Complete rewrite of doc/build_base_user_guide.md with accurate API signatures, ConfigMerger documentation, ProjectDiscovery section, and an API quick-reference table.
• Updated README — Refreshed usage examples to cover ConfigMerger, ProjectDiscovery, and all build.yaml utility functions.

1.0.0

Features

• TomBuildConfig: Unified configuration loading from tom_build.yaml files with support for project paths, glob patterns, scan directories, recursive traversal, exclusion patterns, and tool-specific options.
• ProjectScanner: Directory traversal with configurable project validation. Finds subprojects, scans directories recursively, supports glob-based project matching, and applies exclusion patterns.
• ProjectDiscovery: Advanced project discovery with proper scan vs recursive semantics. Scans until it hits a project boundary; recursive mode also looks inside found projects for nested projects. Supports comma-separated glob patterns with brace group handling.
• build.yaml utilities: Detect builder definitions (isBuildYamlBuilderDefinition) vs consumer configurations (hasBuildYamlConsumerConfig) — so CLI tools can skip packages that define builders and only process consumer packages.
• Path utilities: Path containment validation (isPathContained) and multi-path validation (validatePathContainment) for security.
• ProcessingResult: Simple success/failure/file-count tracking for batch operations.
• Multi-project support: --project option accepts comma-separated lists and glob patterns (e.g., tom_*, xternal/tom_module_*/*).
• --list flag support: Tools can list discovered projects without processing.

README.md

> Part of the Tom framework by al-the-bear. > © 2024–2026 Peter Nicolai Alexis Kyaw — BSD-3-Clause, see LICENSE.

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

tom_build_base is the foundation every Tom command-line tool is built on — buildkit, testkit, issuekit, d4rtgen, and the rest. It answers the questions that every workspace tool has to answer and that nobody should have to re-answer: how do I declare commands and options, how do I generate help, how do I find the projects in this workspace, in what order do I process them, and how do I run a pipeline of shell and tool steps over them. A tool author declares what their tool does (a ToolDefinition with commands and an executor per command); tom_build_base supplies how it runs.

This is a deliberately large, single-purpose package. It is also the reason the Tom CLI tools feel like one product rather than a pile of scripts: they share this framework, so they share their navigation flags, their help format, their configuration model, and their end-of-run summaries.

---

buildkit_master.yaml (workspace root) — shared defaults

navigation: scan: . recursive: true exclude: [.git, build]

mytool: verbose: false

buildkit.yaml (inside a project) — overrides

mytool: verbose: true

### Pipelines

Multi-command tools get pipelines for free. A pipeline is a list of steps, each
with a prefix that decides how the step runs:

| Prefix | Behaviour |
| --- | --- |
| `shell <cmd>` | Run a shell command once |
| `shell-scan <cmd>` | Run the command once per traversed project |
| `stdin <cmd>` | Run with multiline stdin content |
| `print <msg>` | Print exactly one resolved message (no shell noise) |
| `{TOOL} <cmd>` | Delegate to one of the tool's own commands |

Pipelines also support runtime **macros** (`$name`, defined on the command line
and persisted per tool) and persistent **defines** (key/value pairs in the
master and project YAML). See
[`multiws_pipelines_macros_defines.md`](doc/multiws_pipelines_macros_defines.md)
and [`modes_and_placeholders.md`](doc/modes_and_placeholders.md) for the full
model.

---

Architecture

package:tom_build_base/tom_build_base.dart   (full surface)
package:tom_build_base/tom_build_base_v2.dart (framework only, no legacy utils)
        │
   ┌────┴───────────────── Tool definition ──────────────────┐
   │ ToolDefinition ── commands ─▶ CommandDefinition          │
   │      │                             │                     │
   │   features                      options ─▶ OptionDefinition
   │   (NavigationFeatures)                                   │
   └──────────────┬──────────────────────────────────────────┘
                  │ given to
                  ▼
            ToolRunner ── executors: { name → CommandExecutor }
                  │  parse args → route command → traverse → aggregate
                  ▼
            BuildBase.traverse
                  │ scan ─▶ NatureDetector ─▶ FilterPipeline ─▶ FolderSorter
                  ▼
            CommandContext (path + natures) ─▶ executor ─▶ ItemResult
                  │
                  ▼
            ToolResult.fromItems(...) ─▶ renderRunSummary()

The framework holds no global mutable state across tools: a ToolDefinition is an immutable value, traversal is a pure scan over the filesystem, and a ToolRunner owns only the state of its own invocation.

---

Ecosystem

tom_build_base is the build-framework member of the tom_ai/basics foundation layer:

• tom_basics — exceptions, logging, the platform seam, and

the runtime model. - tom_basics_console — the standalone/server platform implementation. - tom_basics_network — HTTP retry and LAN server discovery.

Downstream, the Tom CLI tools are all tom_build_base tools: buildkit, testkit, issuekit, and the code generators each ship a ToolDefinition and a set of executors and let this package supply everything else. That is the design rule for the workspace — shared CLI infrastructure lives here, never re-implemented in a tool. New capability that a tool needs is added to tom_build_base, published, and then consumed.

---

Further documentation

The doc/ folder holds the in-depth guides:

• build_base_user_guide.md — the complete user

guide and API reference. - cli_tools_navigation.md — the navigation flag model and how traversal selection works. - modes_and_placeholders.md — modes and placeholder resolution. - multiws_pipelines_macros_defines.md — pipelines, multi-workspace runs, macros, and defines. - tool_inheritance_and_nesting.md — deriving tools (copyWith + CommandListOps) and nested tool wiring. - test_coverage.md — the test-coverage map.

See also ../README.md, the tom_ai/basics package map, and example/tom_build_base_example.dart.

---

Status

• Version: 2.6.25
• Tests: an extensive suite under test/ (dart test / testkit :test)

covering tool definition, argument parsing, help and completion generation, traversal, filtering and build-order, pipelines, macros and defines, and configuration loading. - Analysis: clean under package:lints (dart analyze — no issues). - Platforms: any Dart runtime with dart:io (desktop, server, CLI).

build_base_user_guide.md

This guide explains how to use tom_build_base to create CLI tools that integrate with Tom workspace configuration patterns.

buildkit_master.yaml (workspace root)

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

mytool: # tool-specific section verbose: false

buildkit.yaml (inside a project)

mytool: verbose: true # overrides workspace default

### Loading Configuration

const toolKey = 'mytool'; final basePath = Directory.current.path;

// Load workspace-level config final masterConfig = TomBuildConfig.loadMaster( dir: basePath, toolKey: toolKey, );

// Load project-level config final projectConfig = TomBuildConfig.load( dir: basePath, toolKey: toolKey, );

The `navigation:` section in the master file provides shared defaults (scan, recursive, exclude, recursion-exclude) that are automatically merged as fallbacks for every tool section.

### TomBuildConfig Properties

| Property | Type | Description |
|----------|------|-------------|
| `project` | `String?` | Single project directory path |
| `projects` | `List<String>` | Glob patterns for project discovery |
| `scan` | `String?` | Root directory to scan |
| `config` | `String?` | Explicit config file path |
| `recursive` | `bool` | Recurse into found projects |
| `exclude` | `List<String>` | Glob patterns to exclude projects |
| `excludeProjects` | `List<String>` | Exclusions matched against directory basename only |
| `recursionExclude` | `List<String>` | Directories to skip during recursive traversal |
| `verbose` | `bool` | Enable detailed output |
| `toolOptions` | `Map<String, dynamic>` | All raw options from the tool section |

### Merging Configurations

Use `TomBuildConfig.merge()` to combine master and project configs:

final config = (masterConfig != null && projectConfig != null) ? masterConfig.merge(projectConfig) // project overrides master : projectConfig ?? masterConfig ?? const TomBuildConfig();

### Checking for Configuration

// Does this project have a specific tool section in buildkit.yaml? if (hasTomBuildConfig(projectPath, 'mytool')) { print('Has tool config'); }

// Does the config specify any project navigation options? if (config.hasProjectOptions) { print('Has project/scan/config options'); }

---

Best Practices

1. Define tools declaratively — use ToolDefinition and CommandDefinition for consistent behavior. 2. Use folder natures — check context.isDartProject / context.getNature<T>() for type-safe project info. 3. Merge configs — load master, load project, master.merge(project). 4. Respect verbose — honour config.verbose for debugging output. 5. Use exit codes — return 0 on success, 1 on failures. 6. Use help topics — add custom HelpTopic entries for tool-specific documentation.

---

API Quick Reference

Tool Framework

Folder Natures

Utility Classes

cli_tools_navigation.md

This document describes the standard CLI patterns and workspace navigation options used by all Tom build tools.

These are equivalent in project mode:

astgen astgen --scan . --recursive --build-order

### Workspace Mode

When navigation options are provided, tools operate in **workspace mode**:

- Triggered by: `-R`, `-s <path>` (where path ≠ "."), `-i`, or `-o`
- Does NOT auto-apply defaults
- Processes exactly what you specify

Workspace mode examples:

astgen -R # From detected workspace root astgen -R /path/to/workspace # From specified workspace astgen -s packages/ # Scan specific directory astgen -i # Inner-first git mode

Navigation Options

Scanning and Traversal

Workspace Root

Workspace detection looks for these files (in order): - buildkit_master.yaml - tom_workspace.yaml - tom.code-workspace

Git Repository Traversal

Use cases: - -i: For commit/push operations (leaf repos first) - -o: For pull/fetch operations (parent repos first) - -T: Find and operate on the parent repository containing the current directory

The --top-repo flag traverses upward from the current directory to find the topmost git repository. It requires a git traversal mode (-i or -o) to be specified. This is useful when running from a nested subdirectory and you want to operate on the containing repository hierarchy.

From inside a submodule, find all repos from the top

gitstatus -T -i gitcommit -T -i -m "Update all"

### Modes

| Option | Abbr | Description |
|--------|------|-------------|
| `--modes=<mode>` | | Active modes for mode-specific defines (e.g., `DEV,CI`) |

Modes activate mode-specific configuration sections. They affect define resolution, pipeline behavior, and any mode-prefixed YAML keys. See [Modes and Placeholders](modes_and_placeholders.md) for the full specification.

buildkit --modes=DEV :compiler # Use DEV-prefixed defines/options buildkit --modes=CI,RELEASE :build # Multiple modes, applied left-to-right buildkit --modes= :compiler # Explicitly disable all modes

### Exclusion Patterns

| Option | Abbr | Description |
|--------|------|-------------|
| `--exclude=<glob>` | `-x` | Exclude patterns (path-based globs) |
| `--exclude-projects=<pattern>` | | Exclude projects by name or path |
| `--recursion-exclude=<glob>` | | Exclude patterns during recursive scan |

**Pattern syntax:**
- `*` matches any characters except `/`
- `**` matches any characters including `/`
- Can be specified multiple times

Examples:

astgen -R -x '/test/' -x '/example/' astgen --exclude-projects='zom_,test_' astgen --recursion-exclude='/.git/,/node_modules/'

### V2 Framework Options

These options are part of `commonOptions` in the V2 `ToolRunner` framework and are available to all V2 tools:

| Option | Abbr | Description |
|--------|------|-------------|
| `--verbose` | `-v` | Enable verbose output |
| `--dry-run` | `-n` | Show what would be done without executing |
| `--test` | | Include test projects in traversal |
| `--test-only` | | Process only test projects |
| `--no-skip` | | Ignore skip markers (`tom_skip.yaml`, `<tool>_skip.yaml`) |
| `--nested` | | Run in nested mode (skip traversal, single-project execution) |
| `--dump-definitions` | | Dump complete tool definition as YAML |

**`--nested`** is used by host tools when delegating to nested tools. It tells the tool to skip its own traversal and wiring, and execute directly in the current directory. End users typically don't use this flag directly.

**`--dump-definitions`** serializes the tool's complete definition — all commands, options, nature requirements, and features — as YAML. This is used by host tools for auto-discovery during [nested tool wiring](tool_inheritance_and_nesting.md).

Implementation Guide

Adding Navigation to Your Tool

There are two approaches for implementing navigation:

1. ProjectNavigator (recommended) — Unified navigation with configurable features 2. Manual discovery — Use ProjectDiscovery directly for custom control

Using ProjectNavigator (Recommended)

import 'dart:io';
import 'package:args/args.dart';
import 'package:tom_build_base/tom_build_base.dart';

void main(List<String> args) async {
  // 1. Check for help/version commands first
  if (isHelpCommand(args)) {
    _printUsage();
    return;
  }
  if (isVersionCommand(args)) {
    print('MyTool $version');
    return;
  }

  // 2. Preprocess args for bare -R detection
  final (processedArgs, bareRoot) = preprocessRootFlag(args);

  // 3. Create parser with tool-specific options
  final parser = ArgParser()
    ..addOption('config', abbr: 'c', help: 'Config file path')
    ..addFlag('verbose', abbr: 'v', help: 'Verbose output')
    ..addFlag('help', abbr: 'h', negatable: false, help: 'Show help');
  
  // 4. Add standard navigation options
  addNavigationOptions(parser);

  // 5. Parse arguments
  final results = parser.parse(processedArgs);
  
  if (results['help'] as bool) {
    _printUsage();
    return;
  }

  final verbose = results['verbose'] as bool;

  // 6. Parse navigation options
  final navArgs = parseNavigationArgs(results, bareRoot: bareRoot);
  
  // 7. Resolve execution root
  final executionRoot = resolveExecutionRoot(
    navArgs,
    currentDir: Directory.current.path,
  );

  // 8. Apply defaults if needed
  final effectiveNavArgs = navArgs.withDefaults();

  // 9. Create navigator with tool-specific config
  final navigator = ProjectNavigator(
    config: NavigationConfig(
      usePathExclude: true,
      useNameExclude: true,
      useModulesFilter: true,
      useRecursionExclude: true,
      useSkipFiles: true,
      useMasterConfigDefaults: true,
      useBuildOrder: effectiveNavArgs.buildOrder,
      useGitTraversal: true,
      projectFilter: _isValidProject,  // Optional: custom filter
    ),
    verbose: verbose,
  );

  // 10. Navigate to find projects
  final result = await navigator.navigate(
    effectiveNavArgs,
    basePath: executionRoot,
  );

  if (result.hasError) {
    stderr.writeln('Error: ${result.errorMessage}');
    exit(1);
  }

  // 11. Process projects
  for (final project in result.paths) {
    await processProject(project);
  }
}

bool _isValidProject(String dirPath) {
  return File('$dirPath/pubspec.yaml').existsSync();
}

void _printUsage() {
  print('MyTool - Does something useful');
  print('');
  print('Usage:');
  print('  mytool [options]');
  print('  mytool help');
  print('  mytool version');
  print('');
  print('Tool Options:');
  print('  -c, --config=<path>  Config file path');
  print('  -v, --verbose        Verbose output');
  print('  -h, --help           Show help');
  print('');
  printNavigationOptionsHelp();
}

Using ProjectDiscovery (Manual Approach)

Generating Consistent Help Output

Use the helper functions to ensure consistent help text:

void _printUsage(ArgParser parser) {
  // Print header
  for (final line in getToolHelpHeader(
    toolName: 'Astgen',
    toolDescription: 'Converts Dart source files to serialized AST YAML files',
    usagePatterns: [
      'astgen [options]',
      'astgen help',
      'astgen version',
    ],
  )) {
    print(line);
  }

  // Print tool-specific options
  print('Tool Options:');
  print(parser.usage);  // ArgParser's built-in usage
  print('');

  // Print navigation options
  printNavigationOptionsHelp();

  // Print footer with examples
  for (final line in getToolHelpFooter(toolName: 'astgen')) {
    print(line);
  }
}

API Reference

Functions

Navigation Classes

NavigationConfig Properties

Skip Files

Skip files allow directories to be excluded from tool processing without command-line options.

Tool-specific skip files:

Resolution order: When scanning a directory, tools check for: 1. tom_skip.yaml — if present, skip for ALL tools 2. {basename}_skip.yaml — if present, skip for this tool only

Skip file format: The file can be empty (presence is sufficient) or contain optional skip reasons:

Optional skip reason

reason: "Legacy project, not actively maintained"

### NavigationResult Properties

| Property | Type | Description |
|----------|------|-------------|
| `paths` | `List<String>` | Discovered project or repo paths |
| `isGitMode` | `bool` | True if git traversal was used |
| `hasError` | `bool` | True if an error occurred |
| `errorMessage` | `String?` | Error message if `hasError` is true |

### WorkspaceNavigationArgs Properties

| Property | Type | Description |
|----------|------|-------------|
| `scan` | `String?` | Scan directory path |
| `recursive` | `bool` | Recursive scanning enabled |
| `buildOrder` | `bool` | Sort by dependency order |
| `project` | `String?` | Project pattern(s) |
| `root` | `String?` | Explicit workspace root path |
| `bareRoot` | `bool` | True if bare `-R` was used |
| `workspaceRecursion` | `bool` | Shell out to sub-workspaces |
| `innerFirstGit` | `bool` | Inner-first git traversal |
| `outerFirstGit` | `bool` | Outer-first git traversal |
| `topRepo` | `bool` | Find topmost git repo by traversing up |
| `exclude` | `List<String>` | Exclude patterns |
| `excludeProjects` | `List<String>` | Excluded project names/paths |
| `recursionExclude` | `List<String>` | Recursion exclude patterns |
| `executionMode` | `ExecutionMode` | Computed: project or workspace |
| `isWorkspaceMode` | `bool` | True if in workspace mode |
| `isProjectMode` | `bool` | True if in project mode |

### WorkspaceNavigationArgs Methods

| Method | Description |
|--------|-------------|
| `withDefaults()` | Apply default scan/recursive/build-order if no explicit nav |
| `copyWith(...)` | Create modified copy |

Tools Using This System

All these tools share identical navigation options:

Tools marked V2 use the ToolRunner framework with ToolDefinition-based configuration, automatic help generation, and support for help topics, modes, macros, defines, and pipelines.

modes_and_placeholders.md

This document specifies the mode support system and placeholder resolution for Tom workspace tools. It applies to all tools that use the tom_build_base infrastructure: buildkit, testkit, issuekit, linkkit, and others.

buildkit_master.yaml

buildkit: defines: binaryPath: $HOME/.tom/bin outputDir: @[binaryPath]/output # Can reference other defines DEV-defines: binaryPath: $HOME/.tom/bin/dev

project/buildkit.yaml

compiler: compiles: - pipeline: - shell mkdir -p @[binaryPath]/${target-platform-vs} - shell dart compile exe ${file} -o @[binaryPath]/${target-platform-vs}/${file.name}

**Notes:**
- `@[...]` placeholders can contain `${...}` placeholders inside their resolved values
- Resolution is recursive (max depth: 10) — a define value can reference other defines

### Tool Placeholders (`@{...}`)

Tool placeholders are defined by the tool itself and resolved after mode processing, once per project (not per command). Tools register these placeholders with descriptions for help output.

project/buildkit.yaml

compiler: compiles: - pipeline: - shell echo "Building in @{project-path}" - shell echo "Tool version: @{tool-version}"

**Example tool placeholders:**

| Placeholder | Description |
|-------------|-------------|
| `@{project-path}` | Absolute path to current project |
| `@{project-name}` | Name of current project |
| `@{tool-version}` | Version of the tool |
| `@{workspace-root}` | Root path of the workspace |

**Notes:**
- Tool placeholders are resolved once per project, before any commands execute
- Tools register their placeholders for help output generation
- The same placeholder resolution utility is used (recursive, max depth 10)

### Command Placeholders (`${...}`)

Command placeholders are resolved by specific commands during execution. Each command defines its own set of available placeholders.

**Example placeholders from the `:compiler` command:**

| Placeholder | Description |
|-------------|-------------|
| `${file}` | Source file path |
| `${file.name}` | File name without extension |
| `${file.basename}` | File name with extension |
| `${file.extension}` | File extension (e.g., `.dart`) |
| `${file.dir}` | File directory path |
| `${target-os}` | Target OS (macos, linux, windows) |
| `${target-arch}` | Target architecture (x64, arm64, arm) |
| `${target-platform}` | Dart target format (macos-arm64) |
| `${target-platform-vs}` | VS Code format (darwin-arm64) |
| `${current-os}` | Current OS |
| `${current-arch}` | Current architecture |
| `${current-platform}` | Current platform (Dart format) |
| `${current-platform-vs}` | Current platform (VS Code format) |

### Pipeline Placeholders (`%{...}`)

Pipeline placeholders are resolved during pipeline step execution by the `ToolPipelineExecutor`. They provide context about the current execution environment and are available in **all pipeline command types**: `shell`, `shell-scan`, `stdin`, and `tool` prefixed commands.

**Available pipeline placeholders:**

| Placeholder | Description |
|-------------|-------------|
| `%{folder}` | Absolute path to the current folder being processed |
| `%{folder.name}` | Name of the current folder |
| `%{current-os}` | Current operating system |
| `%{current-arch}` | Current architecture |
| `%{current-platform}` | Current platform (Dart target format, e.g., `macos-arm64`) |
| `%{current-platform-vs}` | Current platform (VS Code format, e.g., `darwin-arm64`) |

**Example usage in pipeline steps:**

buildkit: pipelines: build: core: - commands: - "print Building on %{current-platform}" - "shell-scan echo Processing %{folder.name} at %{folder}" - | stdin dcli --stdin print("Building in %{folder}");

**Notes:**
- `%{...}` placeholders are distinct from `@[...]` define placeholders and `${...}` command placeholders
- They are resolved by `ToolPipelineExecutor` before passing the command to the shell or tool
- `@[...]` define placeholders are also resolved per folder during pipeline traversal
- Run `<tool> help placeholders` for the complete, up-to-date reference

### Environment Variables (`$VAR` / `$[VAR]`)

Environment variables from the shell environment. Two syntaxes are supported:

| Syntax | Use case |
|--------|----------|
| `$VAR` | When followed by non-word characters (e.g., `$HOME/.tom`) |
| `$[VAR]` | When more characters follow the variable name (e.g., `$[HOME]path`) |

compiler: compiles: - pipeline: - shell mkdir -p $HOME/.tom/bin # $HOME followed by / - shell echo $[USER]_backup # $[USER] allows _backup suffix

---

Mode System

Concept

Modes represent workspace-wide configuration dimensions that can be changed independently. They allow switching all configurations across all projects between different environments.

Multiple modes can be active simultaneously, allowing orthogonal configuration:

• DEV + LOCAL = Local development
• DEV + DOCKER = Development in Docker
• PROD + CLOUD = Production deployment

Mode Sources (Priority)

1. CLI option — --modes DEV,DOCKER (highest priority) 2. tom_workspace.yaml — Default modes for the workspace

tom_workspace.yaml

build: modes: DEV, LOCAL # default modes for all tools

### No Mode / Implicit "None" State

Modes are **opt-in feature switches**. The base (unprefixed) configuration represents the default behavior when no modes are active.

**Single mode as feature flag:**

A mode like `CI` acts as a feature switch. When `CI` is active, `CI-` prefixed keys override their base keys. When `CI` is not active, only the base keys are used.

versioner: enabled: true # Default: versioner runs CI-enabled: false # In CI mode: skip versioner

**Dimension modes with implicit "none":**

For dimensions with multiple modes (like `DEV`, `TEST`, `PROD`), there's always an implicit fourth state: **none of them active**. This means the base configuration is used — which typically represents production/default behavior.

| Active Mode | Configuration Used |
|-------------|-------------------|
| (none) | Base keys only (production defaults) |
| `DEV` | Base + `DEV-` overrides |
| `TEST` | Base + `TEST-` overrides |
| `PROD` | Base + `PROD-` overrides |

**Example:**

compiler: target-restriction: [darwin-arm64, linux-x64, linux-arm64] # Default: all platforms DEV-target-restriction: darwin-arm64 # DEV: current platform only CI-target-restriction: [linux-x64, linux-arm64] # CI: server platforms only

- No modes active → all 3 platforms
- `DEV` active → darwin-arm64 only
- `CI` active → linux-x64 and linux-arm64
- `DEV, CI` active → `CI-` overrides `DEV-` (mode order matters)

### Mode-Prefixed Keys

Any configuration key can have mode-prefixed variants. **Mode prefixes are UPPERCASE** to make them visually distinct:

buildkit_master.yaml

buildkit: defines: binaryPath: $HOME/.tom/bin DEV-defines: binaryPath: $HOME/.tom/bin/dev DOCKER-defines: binaryPath: /app/bin

compiler: target-restriction: [darwin-arm64, linux-x64, linux-arm64] DEV-target-restriction: darwin-arm64 CI-target-restriction: [linux-x64, linux-arm64]

### Mode Prefix Syntax

- **UPPERCASE letters and numbers only**: `DEV`, `PROD`, `TEST1`, `CI`
- **Followed by hyphen**: `DEV-`, `CI-`
- **Applied to any key**: `DEV-target-restriction`, `DEV-defines`, `CI-enabled`

Valid mode prefixes

DEV-target-restriction: darwin-arm64 CI-skip-versioner: true TEST1-output-path: ./test-build/

Invalid (not recognized as mode prefixes)

dev-target-restriction: ... # lowercase Dev-target-restriction: ... # mixed case DEV_target_restriction: ... # underscore instead of hyphen

### Mode Merging Behavior

For YAML map nodes (like `defines:`), mode-prefixed versions are **merged** with the base, not replaced. Merging happens in mode order, with later modes overriding earlier values for the same keys.

**Convention:** The unprefixed (base) node represents **production/default settings**. Mode-prefixed nodes provide overrides for specific environments.

#### Example: Multiple modes with merging

buildkit: modes: DEV, CLOUD defines: binaryPath: $HOME/.tom/bin cloudProvider: AWS DEV-defines: binaryPath: $HOME/.tom/bin/dev CLOUD-defines: cloudProvider: GCP

**Resolution with `modes: DEV, CLOUD`:**

1. Start with base `defines:` → `{ binaryPath: $HOME/.tom/bin, cloudProvider: AWS }`
2. Merge `DEV-defines:` → `{ binaryPath: $HOME/.tom/bin/dev, cloudProvider: AWS }`
3. Merge `CLOUD-defines:` → `{ binaryPath: $HOME/.tom/bin/dev, cloudProvider: GCP }`

**Final result:**

defines: binaryPath: $HOME/.tom/bin/dev # from DEV-defines cloudProvider: GCP # from CLOUD-defines (overrides AWS)

---

Resolution Flow

Modes are global for all tools — YAML files are processed once per project, not per command.

┌─────────────────────────────────────────────────────────────────┐
│ 1. Determine active modes                                       │
│    - CLI --modes option OR                                      │
│    - tom_workspace.yaml build.modes default                     │
└─────────────────────────────────────────────────────────────────┘
                              ▼
┌─────────────────────────────────────────────────────────────────┐
│ 2. Load {tool}_master.yaml                                      │
│    a) Process mode prefixes:                                    │
│       - For each active mode, merge MODE-key: into key:         │
│       - Discard all MODE- prefixed keys (for inactive modes)    │
│    b) Resolve @[...] placeholders using merged defines:         │
└─────────────────────────────────────────────────────────────────┘
                              ▼
┌─────────────────────────────────────────────────────────────────┐
│ 3. Load project {tool}.yaml                                     │
│    a) Process mode prefixes (same as above)                     │
│    b) Resolve @[...] placeholders using:                        │
│       - Local defines (project)                                 │
│       - Master defines (workspace)                              │
└─────────────────────────────────────────────────────────────────┘
                              ▼
┌─────────────────────────────────────────────────────────────────┐
│ 4. Resolve @{...} tool placeholders (once per project)          │
│    - Tool provides values: project-path, tool-version, etc.     │
│    - Applied to both workspace and project YAMLs                │
└─────────────────────────────────────────────────────────────────┘
                              ▼
┌─────────────────────────────────────────────────────────────────┐
│ 5. Pass clean workspace and project YAMLs to tool/commands      │
│    - Both YAMLs have NO @[...] or @{...} placeholders           │
│    - Both YAMLs have NO MODE- prefixed keys                     │
│    - Tool performs merge using tool-specific merge rules        │
└─────────────────────────────────────────────────────────────────┘
                              ▼
┌─────────────────────────────────────────────────────────────────┐
│ 6. Command execution                                            │
│    a) Command resolves ${...} placeholders (file, target, etc.) │
│    b) Shell/tool resolves $VAR / $[VAR] environment variables   │
└─────────────────────────────────────────────────────────────────┘

---

Configuration Example

tom_workspace.yaml

build: modes: DEV, LOCAL

buildkit_master.yaml

buildkit: defines: binaryPath: $HOME/.tom/bin buildOutputPath: $HOME/.tom/build DEV-defines: binaryPath: $HOME/.tom/bin/dev buildOutputPath: ./build DOCKER-defines: binaryPath: /app/bin buildOutputPath: /app/build

compiler: DEV-target-restriction: darwin-arm64

project/buildkit.yaml

compiler: compiles: - pipeline: - shell mkdir -p @[binaryPath]/${target-platform-vs} - shell dart compile exe ${file} -o @[binaryPath]/${target-platform-vs}/${file.name} files: - bin/my_tool.dart platforms: [darwin-arm64, linux-x64, linux-arm64]

**With modes `DEV, LOCAL`:**
- `@[binaryPath]` → `$HOME/.tom/bin/dev`
- `target-restriction` → `darwin-arm64`
- Only `darwin-arm64` compiled

**With modes `DOCKER`:**
- `@[binaryPath]` → `/app/bin`
- No target restriction
- All 3 platforms compiled

---

Shared Infrastructure in tom_build_base

Components

String Replacement Utility

The shared replacement utility provides recursive placeholder resolution:

/// Resolves placeholders in a template string.
/// 
/// Parameters:
/// - [template]: String containing placeholders
/// - [values]: Map of placeholder names to values
/// - [resolveEnvVars]: Whether to also resolve $VAR and $[VAR] environment variables
/// - [maxDepth]: Maximum recursion depth (default: 10)
/// 
/// Returns the resolved string. Unresolved placeholders remain unchanged.
String resolvePlaceholders(
  String template,
  Map<String, String> values, {
  bool resolveEnvVars = false,
  int maxDepth = 10,
});

Behavior: - Recursively resolves placeholders (a resolved value may contain new placeholders) - Maximum recursion depth of 10 to prevent infinite loops - Optional environment variable resolution via resolveEnvVars parameter - Unresolved placeholders remain unchanged (no error, enables later resolution)

Example:

final values = {
  'binaryPath': '\$HOME/.tom/bin',
  'outputDir': '@[binaryPath]/output',
};

// Without env var resolution
resolvePlaceholders('@[outputDir]/${file}', values);
// → '$HOME/.tom/bin/output/${file}'

// With env var resolution  
resolvePlaceholders('@[outputDir]/${file}', values, resolveEnvVars: true);
// → '/Users/alex/.tom/bin/output/${file}'

Placeholder Registration

Both tools and commands register their placeholders with descriptions for help generation:

// Tool-level registration (in buildkit tool)
toolRegistry.register('project-path', 'Absolute path to current project');
toolRegistry.register('workspace-root', 'Root path of the workspace');

// Command-level registration (in compiler command)
commandRegistry.register('file', 'Source file path');
commandRegistry.register('file.name', 'File name without extension');
commandRegistry.register('target-platform-vs', 'Target platform (VS Code format)');

Used for: - Help output generation (<tool> help parameters, <tool> help :compiler parameters) - Documentation generation - Could validate configs (unresolved placeholders = warning), but not required initially - Invalid/unknown placeholders simply remain unresolved

---

Command Line Mode Override

Modes are global for all tools and apply to all commands within a tool invocation. The --modes option is a global tool option (not command-specific).

Use default mode from tom_workspace.yaml

buildkit :compiler :versioner

Override to no mode (uses only base/unprefixed keys)

buildkit --modes= :compiler :versioner

Override to specific mode (applies to ALL commands)

buildkit --modes=CI :compiler :versioner :gitcommit

Use multiple modes (in priority order)

buildkit --modes=CI,RELEASE :compiler :versioner

### Standalone Command Executables

When a command is also available as a standalone executable, modes only apply to that single command:

Standalone compiler executable — modes apply only to this command

compiler --modes=CI

### Standalone Tool Configuration Inheritance

A command can be exposed both as a subcommand of the parent tool (e.g., `buildkit :deploy`) and as a standalone executable (e.g., `deployer`). **Standalone tools inherit configuration from the parent tool's config file**, not their own separate config file.

**Key principle:** The standalone tool knows it's logically part of the parent tool, so it reads from:
- `{parent-basename}_master.yaml` — for workspace configuration
- `{parent-basename}.yaml` — for project configuration

**Example:**

The `deployer` standalone executable is also available as `buildkit :deploy`. Both read configuration from `buildkit_master.yaml` and project `buildkit.yaml`:

buildkit_master.yaml

deploy: target: production region: us-east-1 DEV-target: staging DEV-region: us-west-2

These are equivalent — both read from buildkit config

buildkit :deploy --modes=DEV deployer --modes=DEV

**Implementation pattern:**

class DeployerStandalone { final String basename = 'buildkit'; // Parent tool basename final String commandName = 'deploy'; // Command section in config

Future<void> run() async { final loader = ConfigLoader(basename: basename); final loaded = await loader.load(...);

// Extract command-specific configuration final deployConfig = loaded.masterConfig[commandName]; // ... } }

This pattern ensures:
- Consistent configuration between tool and standalone modes
- Modes work the same way in both execution contexts
- Skip files apply based on the parent tool's basename


---

Target Restrictions (Buildkit-Specific)

Target restrictions limit which platforms are compiled. This is particularly useful for:

• Development: Only compile for current platform — cross-platform binaries are useless locally
• CI pipelines: Restrict to specific target platforms per build agent

buildkit_master.yaml

compiler: DEV-target-restriction: darwin-arm64

| Project requests | DEV restriction | Actual targets (DEV) | Actual targets (no mode) |
|------------------|-----------------|----------------------|--------------------------|
| `[darwin-arm64, linux-x64, linux-arm64]` | `darwin-arm64` | `[darwin-arm64]` | `[darwin-arm64, linux-x64, linux-arm64]` |
| `[darwin-arm64, linux-x64]` | `linux-x64` | `[linux-x64]` | `[darwin-arm64, linux-x64]` |
| `[win32-x64]` | `darwin-arm64` | `[]` (none) | `[win32-x64]` |

---

Tool Configuration

Config File Basename

Each tool specifies a basename that determines its configuration file names:

Tools specify their basename when registering with tom_build_base:

final tool = ToolConfig(
  basename: 'buildkit',  // → buildkit_master.yaml, buildkit.yaml, buildkit_skip.yaml
  // ...
);

Configuration File Locations

---

V2 Integration API

Transparent Mode and Placeholder Resolution

The tom_build_base v2 implementation makes mode and placeholder resolution transparent to tools and commands. The framework handles all resolution before passing configuration to commands.

ToolConfig Registration

/// Tool configuration with mode and placeholder support.
class ToolConfig {
  /// Config file basename (e.g., 'buildkit' → buildkit.yaml, buildkit_master.yaml)
  final String basename;
  
  /// Tool name for display
  final String name;
  
  /// Tool placeholders (resolved once per project)
  final Map<String, PlaceholderDefinition> toolPlaceholders;
  
  /// Commands with their placeholder definitions
  final List<CommandDefinition> commands;
}

/// Placeholder definition for registration and help output.
class PlaceholderDefinition {
  final String name;
  final String description;
  final String Function(CommandContext ctx)? resolver;
}

ConfigLoader API

The ConfigLoader handles mode processing, placeholder resolution, and returns clean YAML:

/// Loads and processes configuration files with mode and placeholder resolution.
class ConfigLoader {
  /// Load configuration for a project.
  /// 
  /// Steps performed automatically:
  /// 1. Load {basename}_master.yaml from workspace root
  /// 2. Load {basename}.yaml from project root
  /// 3. Apply mode processing (merge MODE-keys, discard inactive)
  /// 4. Resolve @[...] define placeholders
  /// 5. Resolve @{...} tool placeholders
  /// 6. Return clean configs ready for tool-specific merge
  Future<LoadedConfig> load({
    required String basename,
    required String workspaceRoot,
    required String projectPath,
    required List<String> activeModes,
    required Map<String, String> toolPlaceholders,
  });
}

/// Result of configuration loading — all placeholders and modes resolved.
class LoadedConfig {
  /// Processed master config (no @[...], @{...}, or MODE- keys)
  final Map<String, dynamic> masterConfig;
  
  /// Processed project config (no @[...], @{...}, or MODE- keys)
  final Map<String, dynamic> projectConfig;
  
  /// Active modes that were applied
  final List<String> appliedModes;
}

Command Execution Context

Commands receive fully resolved configuration:

/// Context passed to command execution — all pre-processing done.
class CommandContext {
  /// Project path
  final String projectPath;
  
  /// Workspace root
  final String workspaceRoot;
  
  /// Merged configuration (tool performed its merge)
  final Map<String, dynamic> config;
  
  /// Placeholder resolver for ${...} command placeholders
  final PlaceholderResolver resolver;
  
  /// Active modes (for informational purposes)
  final List<String> activeModes;
}

What Tools/Commands Need to Do

For existing tools: No changes required — mode processing and placeholder resolution happen automatically.

To use new features:

1. Register tool placeholders (optional):

   toolPlaceholders: {
     'project-path': PlaceholderDefinition(
       name: 'project-path',
       description: 'Absolute path to current project',
       resolver: (ctx) => ctx.projectPath,
     ),
   }

2. Register command placeholders (optional, for help output):

   commandPlaceholders: {
     'file': PlaceholderDefinition(
       name: 'file',
       description: 'Source file path',
     ),
   }

---

Migration Path

Existing configurations continue to work unchanged. To adopt mode support:

1. Add build.modes: to tom_workspace.yaml with default modes (e.g., DEV) 2. Add defines: under {tool}: in {tool}_master.yaml with common paths 3. Add DEV-defines: for development-specific overrides 4. Update project config files to use @[placeholder] for define references 5. Add mode-prefixed overrides as needed (e.g., DEV-target-restriction:)

---

Implementation Notes

Parser Requirements

1. When parsing any YAML key, check if it starts with [A-Z][A-Z0-9]+- 2. If yes, extract the prefix and the actual key name 3. Build a lookup table of: { key: { mode: value, ... } } 4. At resolution time, iterate through active modes and look up prefixed keys

Placeholder Resolution Order

1. Resolve mode-specific values (merge MODE-key into key, discard inactive mode keys) 2. Resolve @[...] define placeholders (recursive, max depth 10) 3. Resolve @{...} tool placeholders (once per project) 4. Pass clean YAML to tool for tool-specific merge 5. Pipeline executor resolves %{...} placeholders during step execution (shell, shell-scan, stdin, tool) 6. Pipeline executor also resolves @[...] defines per folder during traversal 7. Command resolves ${...} placeholders during execution 8. Resolve $VAR / $[VAR] environment variables (when appropriate)

Error Handling

• Unknown mode prefixes: warn but don't fail
• Missing defines: error with clear message showing which placeholder failed
• Circular define references: error after hitting recursion limit
• Unresolved command placeholders: remain unchanged (may be resolved later or warn at execution)

multiws_pipelines_macros_defines.md

This document describes the pipeline execution model, runtime macro system, and persistent define system as implemented in tom_build_base. These features are available to all multi-command tools that define a <tool>_master.yaml.

Both are equivalent — pass literal $1 and $2 to the tool:

buildkit :macro vc=:versioner --project \$1 :compiler \$2 buildkit ':macro' 'vc=:versioner --project $1 :compiler $2'

---

Persistent Defines

Persistent defines are key-value pairs stored in <tool>_master.yaml under the defines: section. They are resolved as @[name] placeholders at YAML load time, before any commands execute.

Adding Defines

Use :define to add or update a define:

buildkit :define env=production
buildkit :define output_dir=build/release

Confirmation output: Added define: <name>: <value>

Mode-Specific Defines

Defines can target a specific mode using -m:

buildkit :define -m DEV output_dir=build/debug
buildkit :define -m CI output_dir=/tmp/ci-output

This creates mode-prefixed sections in <tool>_master.yaml:

buildkit:
  defines:
    output_dir: build/release
  DEV-defines:
    output_dir: build/debug
  CI-defines:
    output_dir: /tmp/ci-output

Resolution Order

When modes are active (via --modes CLI option or tom_workspace.yaml defaults), defines are merged in order:

1. Default defines (defines: section) 2. First mode defines (e.g., DEV-defines: if --modes DEV,CI) 3. Second mode defines (e.g., CI-defines: if --modes DEV,CI) 4. Project-level defines (from <tool>.yaml per project)

Later sources override earlier ones for the same key. This means project-level defines can override workspace-level defines, and later modes override earlier modes.

Referencing Defines in YAML

Use @[name] syntax anywhere in YAML configuration files:

compiler:
  binaryPath: @[output_dir]/bin/@[arch]

Define resolution is recursive (max depth 10):

defines:
  base: /opt/tools
  bin: @[base]/bin          # Resolves to /opt/tools/bin

Resolved values can themselves contain ${...} command placeholders, which are resolved later during command execution.

Managing Defines

<tool> :defines              # List all defines (default + mode-specific)
<tool> :undefine <name>      # Remove a default define
<tool> :undefine -m DEV <name>  # Remove a mode-specific define

Removal confirmation: Removed define: <name> : <value>

Defines are always written in alphabetical key order.

Project-Level Overrides

Users can manually add defines to project-level <tool>.yaml files:

project/buildkit.yaml

buildkit: defines: output_dir: ./local-build # Overrides workspace define DEV-defines: debug: true # Project-specific DEV define

Project defines are merged on top of workspace defines once per project during configuration loading.

---

Configuration Authority

All three features are implemented in tom_build_base and consumed by tools like buildkit, issuekit, and testkit without any tool-local implementation.

test_coverage.md

This document lists all testable features across tom_build_base and tracks test implementation status.

Status Legend

• ✅ Test implemented and passing
• ⬜ Test not yet implemented

---

Overview

---

1. Command Prefix Matching

Test file: test/v2/command_prefix_test.dart

Tests for ToolDefinition.findCommand prefix matching logic.

---

2. Execute Placeholder Resolver

Test file: test/v2/execute_placeholder_test.dart

Comprehensive tests for ExecutePlaceholderResolver — 55 tests covering all placeholder types.

Path Placeholders (BB-EPH-01–04)

Platform Placeholders (BB-EPH-05–07)

Nature Existence (BB-EPH-08–11, 44–53)

Attribute Placeholders (BB-EPH-12–24)

Convenience Aliases (BB-EPH-39–43)

Expression & Error Handling (BB-EPH-25–38, 54–55)

---

3. Macro Expansion

Test file: test/v2/macro_expansion_test.dart

Tests for MacroExpander — positional placeholders ($1–$9), rest placeholder ($$), nested macros, and edge cases.

---

4. CLI Argument Parser

Test file: test/v2/core/cli_arg_parser_test.dart

Exhaustive tests for CliArgs — 96 tests covering option parsing, command extraction, bundled flags, and complex command lines.

---

5. CommandDefinition

Test file: test/v2/core/command_definition_test.dart

---

6. Completion Generator

Test file: test/v2/core/completion_generator_test.dart

---

7. Features — Modes, Defines, Macros, Pipelines

Test file: test/v2/core/features_test.dart

Tests for the recently implemented features: modes, persistent defines, runtime macros, and pipelines.

Modes

Defines

Macros

Execute Placeholders (in features context)

Pipelines

---

8. Help Generator

Test file: test/v2/core/help_generator_test.dart

---

9. OptionDefinition

Test file: test/v2/core/option_definition_test.dart

---

10. ToolDefinition

Test file: test/v2/core/tool_definition_test.dart

---

11. ToolDefinition Serializer

Test file: test/v2/core/tool_definition_serializer_test.dart

---

12. Wiring Loader

Test file: test/v2/core/wiring_loader_test.dart

---

13. Pipeline Config

Test file: test/v2/core/pipeline_config_test.dart

---

14. Pipeline Executor

Test file: test/v2/core/pipeline_executor_test.dart

---

15. ToolRunner

Test file: test/v2/core/tool_runner_test.dart

---

16. ToolRunner — Nested Tools

Test file: test/v2/core/tool_runner_nested_test.dart

---

17. Nested Tool Executor

Test file: test/v2/core/nested_tool_executor_test.dart

---

18. Folder Scanner

Test file: test/v2/traversal/folder_scanner_test.dart

---

19. Nature Detector

Test file: test/v2/traversal/nature_detector_test.dart

---

20. Nature Filter

Test file: test/v2/traversal/nature_filter_test.dart

---

21. Filter Pipeline

Test file: test/v2/traversal/filter_pipeline_test.dart

---

22. Build Order

Test file: test/v2/traversal/build_order_test.dart

---

23. Traversal Info

Test file: test/v2/traversal/traversal_info_test.dart

---

24. Build Base Integration

Test file: test/v2/traversal/build_base_integration_test.dart

Full integration test using filesystem fixtures — end-to-end workspace scanning, detection, filtering, and ordering.

---

25. Comprehensive Traversal

Test file: test/v2/traversal/traversal_comprehensive_test.dart

51 tests covering complex workspace scenarios — the most thorough traversal test suite.

---

Test Gaps & Potential Additions

The current test suite is comprehensive. Areas where additional tests could be valuable:

Overall coverage assessment: Excellent — 718 tests covering all features.

tool_inheritance_and_nesting.md

> Reference documentation for tool composition, command inheritance, and nested tool > execution in tom_build_base.

Existing buildkit config (navigation, pipelines, etc.)

navigation: recursive: true exclude-projects: [zom_*]

buildkit: pipelines: build: [cleanup, versioner, runner, compiler]

NEW: nested tool wiring

nested_tools: testkit: binary: testkit mode: multi_command commands: buildkittest: test # :buildkittest in buildkit → :test in testkit buildkitbaseline: baseline # :buildkitbaseline → :baseline in testkit buildkitAstgen: binary: astgen mode: standalone # single-command tool, no :commands buildkitD4rtgen: binary: d4rtgen mode: standalone

**YAML structure per entry:**

| Field | Required | Values | Purpose |
|-------|----------|--------|---------|
| `binary` | Yes | String | Executable name (no `.exe` — added automatically on Windows) |
| `mode` | Yes | `multi_command` / `standalone` | Whether tool has sub-commands |
| `commands` | If multi_command | Map of `host_name: nested_name` | Command mapping with renames |

That's it. Everything else is auto-discovered.

---

### 5. Startup Flow: Lazy Wiring

Wiring is **demand-driven** — the host tool only queries nested tools that are
actually needed for the current invocation. This ensures:

- **No startup failures** when workspace binaries haven't been built yet
  (e.g., `buildkit :compiler` works even if testkit doesn't exist)
- **No unnecessary `--dump-definitions` calls** for tools not involved
  in the current command

#### Wiring Sources

The effective wiring is assembled from two sources:

1. **Code-level:** `tool.defaultIncludes` (if any)
2. **File-level:** `nested_tools:` from the resolved `wiringFile` (if file exists)

YAML entries override code entries when both define wiring for the same binary.

#### Flow

ToolRunner.run() 1. Parse CLI args → determine requested commands 2. If --nested: skip wiring, run single-project → return 3. If --dump-definitions: serialize full tool definition → return 4. Merge wiring sources: a. Start with tool.defaultIncludes (code-level) b. Overlay nested_tools: from wiringFile (file-level, wins on conflict) c. Build command → wiring lookup (which entry owns which host command) 5. Determine which nested tools are needed: - Normal invocation: only tools providing commands in the request - Help/list mode: ALL wired tools are candidates 6. For each needed tool: a. Resolve platform-aware binary name (append .exe on Windows) b. Check binary exists (which/where) - Help mode: skip missing binaries, mark commands as unavailable - Execution mode: fail immediately if binary is missing c. Run: <binary> --dump-definitions d. Parse full YAML response e. Extract commands listed in the wiring config f. Verify all wired commands exist in the dump g. Build CommandDefinition objects (host names, descriptions from dump) h. Build NestedToolExecutor instances i. Register in command + executor maps 7. Proceed with normal traversal + dispatch (or help display)

#### Examples

**Only native commands — no nested tools queried:**

$ buildkit :compiler

[startup] Merging wiring: 3 code defaults + 0 YAML overrides → 4 wired commands [startup] Commands requested: :compiler [startup] No nested tools needed — skipping all --dump-definitions calls [traversal] ...

**Mixed native + nested — only the needed tool is queried:**

$ buildkit -r :cleanup :buildkittest --test-args="--name parser"

[startup] Merging wiring: 3 code defaults + 0 YAML overrides → 4 wired commands [startup] Commands requested: :cleanup, :buildkittest [startup] Need testkit (provides :buildkittest) — querying [startup] Skip astgen (no commands requested) [startup] Skip d4rtgen (no commands requested) [startup] testkit --dump-definitions → 12 commands received [startup] Wiring: buildkittest → test, buildkitbaseline → baseline [startup] Binary check: testkit ✓ [traversal] ...

**Help mode — all tools queried, missing binaries tolerated:**

$ buildkit --help

[startup] Merging wiring: 3 code defaults + 0 YAML overrides → 4 wired commands [startup] Help requested — attempting to wire all tools [startup] testkit --dump-definitions → 12 commands received [startup] astgen: binary not found — commands marked as unavailable [startup] d4rtgen --dump-definitions → standalone tool [help] ...

---

### 6. Option Forwarding

When a nested command is invoked per-project, the host tool forwards only:

- **Command-specific options** — as parsed by the host tool under the host
  command name. These map 1:1 to the nested tool's command options (auto-
  discovered from `--dump-definitions`).
- **Behavioral global options** — `--verbose` and `--dry-run` only. These are
  universal across all tom_build_base tools.
- **`--nested`** — always added, to tell the nested tool to skip traversal.

**NOT forwarded:**

- Traversal options (`-s`, `-r`, `-R`, `-b`, `-p`, `--modules`, etc.) — the
  host tool owns traversal.
- Host-specific global options (`--list`, `--workspace-recursion`, `--tui`) —
  meaningless to the nested tool.

/// Build CLI args for the nested tool invocation. List<String> _buildNestedArgs({ required CliArgs hostArgs, required String hostCommandName, required String nestedCommand, // null for standalone required bool isStandalone, }) { final args = <String>['--nested'];

// Forward behavioral globals if (hostArgs.verbose) args.add('--verbose'); if (hostArgs.dryRun) args.add('--dry-run');

// For multi-command tools, add the nested command if (!isStandalone) { args.add(':$nestedCommand'); }

// Forward command-specific options final perCmd = hostArgs.commandArgs[hostCommandName]; if (perCmd != null) { for (final entry in perCmd.options.entries) { final name = entry.key; final value = entry.value; if (value == true) { args.add('--$name'); } else if (value == false) { continue; // Skip false flags } else if (value is String && value.isNotEmpty) { args.addAll(['--$name', value]); } else if (value is List) { for (final v in value) { args.addAll(['--$name', v.toString()]); } } } }

return args; }

**Example invocation chain:**

User runs:

buildkit -s . -r -v :buildkittest --test-args="--name parser"

Buildkit traverses projects, for each Dart project calls:

testkit --nested --verbose :test --test-args="--name parser"

testkit sees --nested, skips traversal, runs :test in cwd

---

### 7. Help Integration

Wired commands appear in the host tool's help output alongside native commands.
When a user asks for detailed help on a wired command, the host tool delegates
to the nested tool.

#### Command list in `--help`

The general help output includes wired commands with descriptions obtained
from `--dump-definitions`. Commands are grouped by source:

Available commands: :cleanup Cleanup build artifacts :versioner Manage project versions :compiler Compile project ... (native commands)

Nested commands: :buildkittest Run tests and add result column (via testkit) :buildkitbaseline Create a new baseline CSV file (via testkit) :buildkitAstgen AST generator for Dart projects (via astgen)

If a binary is not found during help (lazy wiring tolerates this):

:buildkitAstgen [binary astgen not found]

Descriptions come from the `--dump-definitions` output — specifically the
command's `description` field for multi-command tools, or the tool's
`description` field for standalone tools.

#### Detailed help: `<tool> help <command>`

When the user requests detailed help for a wired command, the host tool
delegates to the nested tool's own help system:

For multi-command nested tools:

buildkit help buildkittest

→ Calls: testkit --nested help test

Shows testkit's native help for the :test command

For standalone nested tools:

buildkit help buildkitAstgen

→ Calls: astgen --nested --help

Shows astgen's full help output

If the nested binary is not available:

Command :buildkitAstgen — binary astgen not found.

---

### 8. NestedToolExecutor

A single generic `CommandExecutor` subclass handles both standalone and
multi-command nested tools:

/// Executor that delegates to an external tool binary. /// /// Created dynamically at startup from wiring YAML + --dump-definitions. class NestedToolExecutor extends CommandExecutor { /// Name of the external binary (must be on PATH). final String binary;

/// Command name in the external tool (e.g., 'test'). /// Null for standalone tools. final String? nestedCommand;

/// Whether this is a standalone (single-command) tool. final bool isStandalone;

/// The host command name (may differ from nestedCommand due to renames). final String hostCommandName;

NestedToolExecutor({ required this.binary, required this.hostCommandName, this.nestedCommand, this.isStandalone = false, });

@override Future<ItemResult> execute(CommandContext context, CliArgs args) async { final cmdArgs = _buildNestedArgs( hostArgs: args, hostCommandName: hostCommandName, nestedCommand: nestedCommand ?? '', isStandalone: isStandalone, ); return _runBinary(binary, cmdArgs, context.path); } }

---

### 9. Binary Pre-Check

Binary validation is integrated into the lazy wiring flow (step 6b in
Section 5). Only binaries for **requested** commands are checked — and
in help mode, missing binaries are tolerated:

/// Resolve platform-aware binary name. String _resolveBinary(String binary) => Platform.isWindows ? '$binary.exe' : binary;

/// Check that nested tool binaries are available for requested commands. /// /// Only checks binaries for commands that will actually be invoked. /// Running buildkit :cleanup :versioner does not require testkit. /// /// In help mode, [tolerateMissing] is true — missing binaries are /// returned as warnings rather than errors. List<String> validateNestedBinaries({ required Set<String> requestedCommands, bool tolerateMissing = false, }) { final missing = <String>[]; for (final cmdName in requestedCommands) { final executor = executors[cmdName]; if (executor is NestedToolExecutor) { final resolved = _resolveBinary(executor.binary); if (!_isBinaryOnPath(resolved)) { missing.add(':$cmdName — binary $resolved not found'); } } } return missing; }

// In ToolRunner.run(), after lazy wiring but before traversal: final missingBinaries = validateNestedBinaries( requestedCommands: cliArgs.commands.toSet(), tolerateMissing: cliArgs.isHelpMode, ); if (!cliArgs.isHelpMode && missingBinaries.isNotEmpty) { output.writeln('Error: Missing required tool binaries:'); for (final msg in missingBinaries) { output.writeln(' - $msg'); } return ToolResult.failure('Missing nested tool binaries'); }

---

### 10. Concrete Example: Full Lifecycle

#### Code-Level Defaults (from `buildkitTool`)

const buildkitTool = ToolDefinition( name: 'buildkit', wiringFile: ToolDefinition.kAutoWiringFile, defaultIncludes: [ ToolWiringEntry(binary: 'testkit', mode: WiringMode.multiCommand, commands: {'buildkittest': 'test', 'buildkitbaseline': 'baseline'}), ToolWiringEntry(binary: 'astgen', mode: WiringMode.standalone), ToolWiringEntry(binary: 'd4rtgen', mode: WiringMode.standalone), ], // ... );

#### Optional YAML Override in `buildkit_master.yaml`

Only needed if overriding or extending code-level defaults

nested_tools: testkit: binary: testkit mode: multi_command commands: buildkittest: test buildkitbaseline: baseline buildkitstatus: status # additional command not in code defaults

#### Startup (lazy — only needed tools queried)

$ buildkit -s . -r :buildkittest --test-args="--name parser"

[startup] Merging wiring: 3 code defaults + 1 YAML override → 5 wired commands [startup] Commands requested: :buildkittest [startup] Need testkit (provides :buildkittest) — querying [startup] Skip astgen (no commands in current request) [startup] Skip d4rtgen (no commands in current request) [startup] testkit --dump-definitions [startup] Full dump received: 12 commands [startup] Wiring: buildkittest → test [startup] → :buildkittest registered (testkit :test, natures: [dart_project]) [startup] Binary check: testkit ✓ [traversal] Scanning . recursively...

#### Per-Project Execution

[tom_build_base] testkit --nested --verbose :test --test-args="--name parser" → testkit sees --nested, runs :test in tom_build_base/ → Tests run, results tracked

[tom_build_kit] testkit --nested --verbose :test --test-args="--name parser" → testkit sees --nested, runs :test in tom_build_kit/ → Tests run, results tracked

#### Error: Missing Binary

$ buildkit :buildkittest :cleanup

Error: Missing required tool binaries: - :buildkittest requires "testkit" — not found

#### Native-Only Invocation (no nested tools needed)

$ buildkit :compiler

[startup] Merging wiring: 3 code defaults + 0 YAML overrides → 4 wired commands [startup] Commands requested: :compiler [startup] No nested tools needed — skipping all --dump-definitions calls [traversal] Scanning . recursively...

No binary checks, no `--dump-definitions` calls. Works even if testkit,
astgen and d4rtgen haven't been compiled yet.

#### Help Display

$ buildkit --help

[startup] Help requested — wiring all tools [startup] testkit --dump-definitions → 12 commands [startup] astgen: binary not found — marked as unavailable [startup] d4rtgen --dump-definitions → standalone tool

buildkit 3.1.0 — Pipeline-based build orchestration tool

Usage: buildkit [options] :command [command-options]

Commands: :cleanup Cleanup build artifacts :versioner Manage project versions :compiler Compile project ... (native commands)

Nested commands: :buildkittest Run tests and add result column (via testkit) :buildkitbaseline Create a new baseline CSV file (via testkit) :buildkitAstgen [astgen not found — run buildkit :compiler first]

#### Registration Workflow

Inspect what testkit offers (full dump — all commands, all options):

$ testkit --dump-definitions name: testkit version: 1.2.0 description: Test result tracking for Dart projects mode: multi_command features: project_traversal: true ... required_natures: [dart_project] global_options: - { name: tui, type: flag, description: "Run in TUI mode" } commands: test: description: Run tests and add result column to the most recent baseline options: - { name: test-args, type: option, ... } works_with_natures: [dart_project] baseline: description: Create a new baseline CSV file ... status: description: Show test status summary ... # ... all 12 native commands listed ...

Pick the commands you want and add wiring to buildkit_master.yaml:

nested_tools:

testkit:

binary: testkit

mode: multi_command

commands:

buildkittest: test

buildkitbaseline: baseline

---

### 11. `_runBinary` Helper

Binary names are resolved to their platform-specific form before execution:

Future<ItemResult> _runBinary( String binary, List<String> args, String workingDirectory, ) async { final resolved = _resolveBinary(binary); final result = await Process.run( resolved, args, workingDirectory: workingDirectory, runInShell: Platform.isWindows, );

final stdout = result.stdout.toString().trim(); final stderr = result.stderr.toString().trim();

if (stdout.isNotEmpty) print(stdout); if (stderr.isNotEmpty) print(stderr);

if (result.exitCode == 0) { return ItemResult.success(path: workingDirectory); } else { return ItemResult.failure( path: workingDirectory, message: '$resolved exited with code ${result.exitCode}', ); } }

---

### 12. Binary Path Resolution and Platform Awareness

All binary names in both code-level `defaultIncludes` and YAML `nested_tools:`
are stored **without** platform extensions. The `.exe` suffix is appended
automatically on Windows at every resolution point.

Binaries are assumed to be on the system PATH. There is no custom lookup in
`$HOME/.tom/bin/` or other tool-specific directories — if a binary needs to
be found, the user is responsible for ensuring it is on the PATH (or in a
directory that `where`/`which` can find).

/// Resolve a platform-specific binary name. /// /// On Windows, appends .exe to the binary name. /// On macOS/Linux, returns the name unchanged. String _resolveBinary(String binary) => Platform.isWindows ? '$binary.exe' : binary;

/// Check if a binary is available on the system PATH. bool isBinaryOnPath(String binary) { try { final cmd = Platform.isWindows ? 'where' : 'which'; final result = Process.runSync(cmd, [binary]); return result.exitCode == 0; } catch () { return false; } }

**Resolution points** (all use `_resolveBinary`):
- `validateNestedBinaries` — existence check via `which`/`where`
- `_runBinary` — actual process execution
- `--dump-definitions` calls during lazy wiring

This means wiring YAML, `ToolWiringEntry.binary`, and serialized definitions
all use platform-neutral names (`testkit`, not `testkit.exe`).

---

Architecture Summary

                    ┌──────────────────────────────────────┐
                    │            tom_build_base             │
                    │                                      │
                    │  ToolDefinition                      │
                    │    + wiringFile: String?              │
                    │    + defaultIncludes: [WiringEntry]?  │
                    │    + copyWith(...)                    │
                    │                                      │
                    │  ToolWiringEntry                      │
                    │    binary, mode, commands             │
                    │                                      │
                    │  commonOptions                       │
                    │    + --nested                        │
                    │    + --dump-definitions               │
                    │    + --modes                         │
                    │                                      │
                    │  ToolRunner                           │
                    │    + lazy wiring (demand-driven)      │
                    │    + nested mode bypass               │
                    │    + dump-definitions bypass          │
                    │    + help integration                 │
                    │    + help topics (auto-injected)      │
                    │    + validateNestedBinaries()         │
                    │    + _resolveBinary() (platform)      │
                    │                                      │
                    │  NestedToolExecutor                   │
                    │  ToolDefinitionSerializer             │
                    └────────────────┬─────────────────────┘
                                     │
              ┌──────────────────────┼──────────────────────┐
              │                      │                      │
    ┌─────────▼────────┐  ┌─────────▼────────┐  ┌──────────▼───────┐
    │     buildkit      │  │     testkit      │  │     d4rtgen      │
    │                   │  │                  │  │                  │
    │ wiringFile: ''    │  │ wiringFile: null  │  │ wiringFile: null │
    │ defaultIncludes:  │  │ (no hosting)     │  │ (no hosting)     │
    │   [testkit,       │  │                  │  │                  │
    │    astgen,        │  │ Responds to:     │  │ Responds to:     │
    │    d4rtgen]       │  │ --dump-defs      │  │ --dump-defs      │
    │                   │  │ --nested         │  │ --nested         │
    │ + YAML overrides  │  │                  │  │                  │
    └───────────────────┘  └──────────────────┘  └──────────────────┘

---

Design Notes

These notes document design decisions made during implementation:

1. Streaming vs buffered output — Nested tool output currently uses buffered execution (Process.run). Streaming (Process.start) may be added later for interactive use cases.

2. Exit code propagation — A nested tool failure stops pipeline processing for that project (fail-fast), consistent with native command behavior.

3. Version checking — The host tool does not currently verify nested tool versions. The --dump-definitions output includes the tool version, enabling future min_version: support in wiring YAML.

4. Caching --dump-definitions — Results are not currently cached. Lazy wiring minimizes impact by only querying tools needed for the current invocation.

5. Config passthrough — Nested tools read their own config sections (e.g., d4rtgen: in buildkit.yaml). The host tool doesn't need to know about this — nature filters from --dump-definitions ensure the host only invokes nested tools on appropriate projects.

license.md

BSD 3-Clause License

Copyright (c) 2024-2026, Peter Nicolai Alexis Kyaw
Find me on LinkedIn under Alexis Kyaw
All rights reserved.

Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions are met:

1. Redistributions of source code must retain the above copyright notice, this
   list of conditions and the following disclaimer.

2. Redistributions in binary form must reproduce the above copyright notice,
   this list of conditions and the following disclaimer in the documentation
   and/or other materials provided with the distribution.

3. Neither the name of the copyright holder nor the names of its
   contributors may be used to endorse or promote products derived from
   this software without specific prior written permission.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

CHANGELOG.md

1.0.2

• Moved to tom_module_basics repository (from tom_module_communication).
• Updated repository and homepage URLs in pubspec.yaml.

1.0.1

• Changed license from MIT to BSD-3-Clause.

1.0.0

• Initial public release.
• Abstract ChatApi interface for platform-agnostic messaging.
• ChatMessage, ChatReceiver, ChatResponse, ChatSettings data models.
• Telegram implementation via TelegramChat with polling-based message reception.
• Support for text messages, photos, documents, audio, video, and voice attachments.
• ChatConfig and TelegramChatConfig for platform-specific configuration.

README.md

> Part of the Tom framework by al-the-bear. > © 2024–2026 Peter Nicolai Alexis Kyaw — BSD-3-Clause, see LICENSE.

Unified chat API abstraction for Telegram, WhatsApp, Signal, and other messaging platforms.

---

Overview

tom_chattools gives you one API to send and receive chat messages, regardless of the platform behind it. You describe a connection with ChatSettings, call ChatApi.connect(...), and from then on the same sendMessage / getMessages / onMessage surface works no matter which messenger you target.

• Platform-agnostic core. ChatApi, ChatMessage, ChatReceiver, and