CHANGELOG.md

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

Shared analyzer-summary caching infrastructure reused by Tom code generators. It was extracted from `tom_reflection_generator` so multiple tools (reflection, d4rt bridges, ...) can share the same summary cache at `<workspace>/.tom/analyzer-cache/` and avoid rescanning stable dependencies on every run.

What it does

For a project with a resolved `pubspec.lock`, this library can:

1. Enumerate all dependencies with their exact versions and source types (`hosted`, `sdk`, `path`, `git`). 2. Decide which of them are *cacheable* (hosted pub.dev packages and SDK packages — their versions are stable). 3. Build a binary summary (`.sum`) for the Dart SDK (including Flutter `dart:ui` via `sky_engine/_embedder.yaml` when Flutter is on the path) and for each cacheable package, in topological order so that a package's summary can reference its dependencies' summaries. 4. Store all summaries under `<workspace>/.tom/analyzer-cache/` using the naming scheme `{package}@{version}.sum` and `sdk@{dart-version}.sum`. 5. Return the list of summary paths so callers can pass them to `AnalysisContextCollectionImpl(..., librarySummaryPaths: summaryPaths, sdkSummaryPath: sdkSummaryPath)` and skip re-analysing those packages from sources.

Public API

Import everything via the top-level library:

import 'package:tom_analyzer_shared/tom_analyzer_shared.dart';

Main types and functions:

• `PackageDependency`, `DependencySet` — resolved dependency metadata.
• `DependencyResolver` — parses `pubspec.lock`, resolves hosted and SDK

package locations. - `SummaryCacheManager` — reads and writes `.sum` files in the shared cache directory. - `SummaryGenerator` — generates the SDK summary and per-package summaries (topological order, progress callback, error aggregation). - `runSummaryCacheStage()` — convenience entry-point used by CLI tools. Resolves dependencies, generates what's missing, and returns a `SummaryCacheResult(summaryPaths, sdkSummaryPath)`.

Typical usage

final result = await runSummaryCacheStage(
  projectRoot,
  verbose: true,
);

final collection = AnalysisContextCollectionImpl(
  includedPaths: [projectRoot],
  sdkSummaryPath: result?.sdkSummaryPath,
  librarySummaryPaths: result?.summaryPaths ?? const [],
);

Both `tom_reflection_generator` and `tom_d4rt_generator` use this stage to share a single cache directory across runs.

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

Basic utilities for the TOM framework with minimal dependencies.

Features

• **TomBaseException** - Base exception class with UUID tracking and stack trace support

Getting Started

Add the package to your `pubspec.yaml`:

dependencies:
  tom_basics: ^1.0.0

Usage

Exception Handling

import 'package:tom_basics/tom_basics.dart';

// Create and throw a tracked exception
throw TomBaseException(
  'USER_NOT_FOUND',
  'The requested user could not be found',
  parameters: {'userId': userId},
);

// Catch and inspect
try {
  // ... operation that may fail
} on TomBaseException catch (e) {
  print('Error ${e.uuid}: ${e.key}');
  print('Message: ${e.defaultUserMessage}');
  e.printStackTrace();
}

Additional Information

This package provides foundational utilities that are used by other TOM framework packages, including:

• `tom_crypto` - Cryptographic utilities
• `tom_core_kernel` - Core kernel library

License

BSD-3-Clause - See [LICENSE](LICENSE) for details.

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

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

Features

• **Platform Detection** — `TomStandalonePlatformUtils` with detection for desktop, mobile, web, and individual OS platforms.
• **Console Output** — Markdown-formatted console output via `console_markdown`.
• **HTTP Client** — IO-based HTTP client for standalone Dart applications.
• Re-exports all of `tom_basics` for convenience.

Getting Started

dependencies:
  tom_basics_console: ^1.0.0

Usage

import 'package:tom_basics_console/tom_basics_console.dart';

final platform = TomStandalonePlatformUtils();
print('Is desktop: ${platform.isDesktop()}');
print('Is macOS: ${platform.isMacOs()}');

// Console-formatted output
platform.out('**Bold** and _italic_ text');

License

BSD-3-Clause — see [LICENSE](LICENSE) for details.

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

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

Features

• **HTTP Retry** — Automatic retry logic with configurable exponential backoff, max attempts, and retry conditions via `RetryConfig`.
• **Server Discovery** — Network-based server discovery for distributed Tom applications.

Getting Started

dependencies:
  tom_basics_network: ^1.0.0

Usage

import 'package:tom_basics_network/tom_basics_network.dart';

final config = RetryConfig(
  maxAttempts: 3,
  initialDelay: Duration(milliseconds: 500),
);

License

BSD-3-Clause — see [LICENSE](LICENSE) for details.

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.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

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

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

Features

• **Declarative tool definition** — `ToolDefinition`, `CommandDefinition`, `OptionDefinition` for structured CLI tools
• **Automatic help generation** — `--help`, `help <command>`, `help <topic>` with consistent formatting
• **Built-in traversal** — Project and git traversal with folder nature detection
• **Pipelines, macros, defines** — Multi-command tools get pipelines, runtime macros, and persistent defines automatically
• **Pipeline print prefix** — `print <message>` emits one resolved message without shell execution noise
• **Nested tool wiring** — Declarative integration of external tool binaries
• **Configuration loading** — `TomBuildConfig` for reading `buildkit.yaml` and `buildkit_master.yaml`
• **YAML utilities** — `yamlToMap()`, `yamlListToList()`, `toStringList()` for converting YAML nodes
• **Cross-platform symlink API** — `MkLinkExecutor` and dcli-backed `createSymLink()` integration for tool commands

Installation

dependencies:
  tom_build_base: ^2.6.0

Quick Start

import 'package:tom_build_base/tom_build_base.dart';

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

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

Configuration Format

Tom build tools use a two-tier configuration pattern:

buildkit_master.yaml (workspace root)

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

mytool:                       # tool-specific workspace defaults
  verbose: false

buildkit.yaml (inside a project)

mytool:
  verbose: true               # overrides workspace default

Pipeline Prefixes

Pipeline commands support these execution prefixes:

• `shell <cmd>` — execute a shell command
• `shell-scan <cmd>` — execute once per traversed project
• `stdin <cmd>` — execute with multiline stdin content
• `print <msg>` — print exactly once after placeholder resolution
• `{TOOL} <cmd>` — delegate to tool command execution

Documentation

• [build_base_user_guide.md](doc/build_base_user_guide.md) — Complete user guide with API reference
• [cli_tools_navigation.md](doc/cli_tools_navigation.md) — CLI navigation options and implementation guide

License

BSD 3-Clause License — see [LICENSE](LICENSE) for details.

Author: Alexis Kyaw ([LinkedIn](https://www.linkedin.com/in/nickmeinhold/))

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

A platform-agnostic chat API library for Dart that provides a unified interface for sending and receiving messages across different chat platforms.

Features

• **Abstract ChatAPI** - Platform-independent interface for chat operations
• **Telegram Support** - Full Telegram Bot API integration via televerse
• **Message Abstraction** - Unified `ChatMessage`, `ChatSender`, and `ChatResponse` classes
• **Streaming Updates** - Real-time message notifications via `onMessage` stream
• **Factory Pattern** - Create appropriate implementation via `ChatAPI.connect()`

Getting Started

Prerequisites

• Dart SDK 3.0 or higher
• A Telegram bot token (for Telegram integration)

Installation

Add `tom_chattools` to your `pubspec.yaml`:

dependencies:
  tom_chattools:
    path: ../path/to/tom_chattools  # Or use git reference

Telegram Setup

To connect to Telegram, you need a bot token from [@BotFather](https://t.me/BotFather).

Step 1: Create a Bot

1. Open Telegram and search for **@BotFather** (the official Telegram bot) 2. Start a conversation and send `/newbot` 3. Follow the prompts: - Choose a display name (e.g., "My Assistant") - Choose a username (must end in `bot`, e.g., `my_assistant_bot`) 4. BotFather will give you an API token like:

   123456789:ABCdefGHIjklMNOpqrsTUVwxyz

5. **Save this token securely** - it grants full access to your bot

Step 2: Get Your Chat ID

To send/receive messages from a specific chat, you need the chat ID:

**For personal chats:** 1. Message your bot first (search for its username in Telegram) 2. Run your bot with polling enabled (see example below) 3. Send a message to your bot 4. Check the `sender.id` in the received message - that's your chat ID

**Using a helper bot:** 1. Forward any message to [@userinfobot](https://t.me/userinfobot) 2. It will reply with your user ID (same as chat ID for 1:1 chats)

**For groups:** 1. Add your bot to the group 2. The group chat ID will appear in incoming messages (usually a negative number)

Step 3: Connect and Use

import 'package:tom_chattools/tom_chattools.dart';

void main() async {
  // Create configuration (just authentication)
  final config = TelegramChatConfig(
    token: 'YOUR_BOT_TOKEN',
    usePolling: true,        // Use long polling for updates
  );

  // Connect to Telegram
  final chat = await ChatAPI.connect(config);

  // Define who to communicate with
  final receiver = ChatReceiver.id('YOUR_CHAT_ID');

  // Send a message
  await chat.sendMessage(receiver, 'Hello from Dart!');

  // Listen for incoming messages
  chat.onMessage.listen((message) {
    print('Received: ${message.text} from ${message.sender.name}');
    
    // Echo back to the sender
    final sender = ChatReceiver.id(message.sender.id);
    chat.sendMessage(sender, 'You said: ${message.text}');
  });
}

Environment Variables (Recommended)

Store your token and chat ID securely using environment variables:

import 'dart:io';

final token = Platform.environment['TELEGRAM_BOT_TOKEN']!;
final chatId = Platform.environment['TELEGRAM_CHAT_ID']!;

final config = TelegramChatConfig(token: token, usePolling: true);
final receiver = ChatReceiver.id(chatId);

Set them in your shell:

export TELEGRAM_BOT_TOKEN="123456789:ABCdefGHIjklMNOpqrsTUVwxyz"
export TELEGRAM_CHAT_ID="987654321"

Usage Examples

Basic Send/Receive

final chat = await ChatAPI.connect(TelegramChatConfig(
  token: token,
  usePolling: true,
));

// Define the receiver
final receiver = ChatReceiver.id(chatId);

// Send a message to the receiver
await chat.sendMessage(receiver, 'Hello!');

// Get messages from that receiver
final response = await chat.getMessages(
  receiver,
  maxWait: Duration(seconds: 10),
);
for (final msg in response.messages) {
  print('${msg.sender.name}: ${msg.text}');
}

Message Types

chat.onMessage.listen((msg) {
  switch (msg.type) {
    case ChatMessageType.text:
      print('Text: ${msg.text}');
    case ChatMessageType.image:
      print('Received an image');
    case ChatMessageType.document:
      print('Received a document');
    default:
      print('Other: ${msg.type}');
  }
});

Send to Different Chats

// Send to a user by ID
await chat.sendMessage(ChatReceiver.id('123456789'), 'Hello user!');

// Send to a user by username
await chat.sendMessage(ChatReceiver.username('johndoe'), 'Hi John!');

// Send to a group
await chat.sendMessage(ChatReceiver.group('-100123456789'), 'Hello group!');

API Overview

Core Classes

Telegram Classes

Troubleshooting

"Conflict: terminated by other getUpdates request"

Only one polling connection can be active. Make sure: - You don't have another instance running - You stopped previous bot instances properly

Bot not receiving messages

1. Make sure you've messaged the bot first (bots can't initiate chats) 2. Check if polling is enabled: `usePolling: true` 3. Verify your token is correct

Getting chat/user IDs

Print incoming message details:

chat.onMessage.listen((msg) {
  print('Chat ID: ${msg.sender.id}');
  print('Message ID: ${msg.platformMessageId}');
});

Additional Information

• [Telegram Bot API Documentation](https://core.telegram.org/bots/api)
• [Televerse Package](https://pub.dev/packages/televerse) - underlying Telegram library
• [BotFather Commands](https://core.telegram.org/bots#6-botfather)

Bot Privacy Settings

By default, bots in groups only see messages that: - Start with `/` (commands) - Are replies to the bot - Mention the bot

To see all messages, disable privacy mode: 1. Go to @BotFather 2. Send `/setprivacy` 3. Choose your bot 4. Select "Disable"

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

Cryptographic utilities for secure authentication and data protection.

Features

• **JWT Tokens** - Token-based authentication with HMAC/RSA signing and encrypted payloads
• **Password Hashing** - Secure password storage using Argon2 algorithm
• **RSA Encryption** - Asymmetric encryption with OAEP padding and digital signatures
• **RSA Key Management** - Key generation, PEM parsing/encoding (PKCS#1 and PKCS#8)

Getting Started

Add the package to your `pubspec.yaml`:

dependencies:
  tom_crypto: ^1.0.0

Usage

Password Hashing

import 'package:tom_crypto/tom_crypto.dart';

// Hash a password
final (hash, spec) = TomPasswordHasher.hashPassword('userPassword123');

// Store both hash and spec in your database
await db.saveUser(passwordHash: hash, hashSpec: spec);

// Verify the password later
if (TomPasswordHasher.verifyPassword('userPassword123', hash, spec)) {
  print('Login successful!');
}

JWT Tokens

import 'package:tom_crypto/tom_crypto.dart';

// Server: Create a token
final token = TomServerJwtToken(
  {'userId': '123', 'role': 'admin'},
  encryptedData: {'permissions': ['read', 'write', 'delete']},
  expiresIn: Duration(hours: 24),
);
final jwtString = token.getJWT('my-auth-server');

// Client: Parse the token
final clientToken = TomClientJwtToken(jwtString);
print('User ID: ${clientToken.payload?['userId']}');
print('Permissions: ${clientToken.secretData?['permissions']}');

RSA Encryption

import 'package:tom_crypto/tom_crypto.dart';
import 'dart:convert';
import 'dart:typed_data';

// Generate keys
final secureRandom = RsaKeyHelper.getSecureRandom();
final keyPair = await RsaKeyHelper.computeRSAKeyPair(secureRandom);
final publicKey = keyPair.publicKey as RSAPublicKey;
final privateKey = keyPair.privateKey as RSAPrivateKey;

// Encrypt
final plaintext = utf8.encode('Secret message');
final encrypted = rsaEncrypt(publicKey, Uint8List.fromList(plaintext));

// Decrypt
final decrypted = rsaDecrypt(privateKey, encrypted);
final message = utf8.decode(decrypted);

Core Components

Additional Information

This package is part of the TOM Framework. It depends on: - `tom_basics` - Basic utilities including exception handling

License

BSD-3-Clause - See [LICENSE](LICENSE) for details.

crypto.md

Comprehensive cryptographic utilities for secure authentication and data protection.

Table of Contents

• [Overview](#overview)
• [Quick Start](#quick-start)
• [Core Components](#core-components)
• [JWT Tokens](#jwt-tokens)
• [Password Hashing](#password-hashing)
• [RSA Encryption](#rsa-encryption)
• [RSA Key Management](#rsa-key-management)
• [Usage Examples](#usage-examples)
• [Best Practices](#best-practices)
• [Error Handling](#error-handling)

---

Overview

The crypto module provides a complete set of cryptographic primitives for building secure applications:

---

Quick Start

Hash a Password

import 'package:tom_core/tom_core.dart';

// Hash a new password
final (hash, spec) = TomPasswordHasher.hashPassword('userPassword123');

// Store both hash and spec in your database
await db.saveUser(passwordHash: hash, hashSpec: spec);

// Later, verify the password
if (TomPasswordHasher.verifyPassword('userPassword123', hash, spec)) {
  print('Login successful!');
}

Create a JWT Token

import 'package:tom_core/tom_core.dart';

// Server: Create a token
final token = TomServerJwtToken(
  {'userId': '123', 'role': 'admin'},
  encryptedData: {'permissions': ['read', 'write', 'delete']},
  expiresIn: Duration(hours: 24),
);
final jwtString = token.getJWT('my-auth-server');

// Client: Parse the token
final clientToken = TomClientJwtToken(jwtString);
print('User ID: ${clientToken.payload?['userId']}');
print('Permissions: ${clientToken.secretData?['permissions']}');

Encrypt Data with RSA

import 'package:tom_core/tom_core.dart';
import 'dart:convert';

// Encrypt
final plaintext = utf8.encode('Secret message');
final encrypted = rsaEncrypt(publicKey, Uint8List.fromList(plaintext));

// Decrypt
final decrypted = rsaDecrypt(privateKey, encrypted);
final message = utf8.decode(decrypted);

---

Core Components

JWT Tokens

JWT (JSON Web Token) support for stateless authentication.

TomJwtConfiguration

Holds cryptographic keys and algorithms for JWT operations.

// Default configuration (development only!)
TomJwtConfiguration.defaultSignConfiguration;

// Custom configuration
final config = TomJwtConfiguration(
  SecretKey('my-production-secret'),
  JWTAlgorithm.HS256,
  productionPrivateKey,
  productionPublicKey,
  false, // Not a dummy configuration
);

**Supported Algorithms:** - HMAC: HS256, HS384, HS512 - RSA: RS256, RS384, RS512, PS256, PS384, PS512

TomServerJwtToken

Creates signed JWT tokens on the server.

final token = TomServerJwtToken(
  {'userId': '123'},              // Public claims
  encryptedData: {'secret': 'x'}, // RSA-encrypted claims
  expiresIn: Duration(hours: 2),  // Token lifetime
  notBefore: Duration(seconds: 0), // Validity delay
);

final jwt = token.getJWT('issuer-name');

TomClientJwtToken

Parses and decrypts JWT tokens on the client.

final token = TomClientJwtToken(jwtString);

// Access token properties
print(token.issuer);      // iss claim
print(token.subject);     // sub claim
print(token.payload);     // All public claims
print(token.secretData);  // Decrypted private claims

---

Password Hashing

Secure password hashing using the Argon2 algorithm.

Why Argon2?

• **Winner** of the Password Hashing Competition (2015)
• **Memory-hard**: Resists GPU/ASIC attacks
• **Configurable**: Tune for your security/performance needs

Hash Format

Passwords are stored in a dual-value format:

hash = "salt$hash"      // e.g., "a1b2c3$d4e5f6..."
spec = "Argon2;2i,13,4,65536,4,128"

The specification allows future algorithm changes without breaking existing hashes.

Configuration

Default parameters (adjustable via static fields):

TomPasswordHasher.globalSettingDefaultSaltLength = 16;  // 128-bit salt
TomPasswordHasher.globalSettingDefaultHashSpec = "Argon2;2i,13,4,65536,4,128";

Specification format: `Argon2;variant,version,iterations,memoryKB,lanes,keyLength`

---

RSA Encryption

Asymmetric encryption for data confidentiality and digital signatures.

Encryption/Decryption

Uses OAEP (Optimal Asymmetric Encryption Padding) for security:

// Encrypt with public key
final encrypted = rsaEncrypt(publicKey, plaintextBytes);

// Decrypt with private key
final decrypted = rsaDecrypt(privateKey, encrypted);

Digital Signatures

Uses SHA-256 for hashing before signing:

// Sign with private key
final signature = rsaSign(privateKey, dataBytes);

// Verify with public key
final isValid = rsaVerify(publicKey, dataBytes, signature);

---

RSA Key Management

Comprehensive RSA key handling via `RsaKeyHelper`.

Key Generation

// Generate a secure random source
final random = RsaKeyHelper.getSecureRandom();

// Generate 2048-bit key pair
final keyPair = await RsaKeyHelper.computeRSAKeyPair(random);
final publicKey = keyPair.publicKey as RSAPublicKey;
final privateKey = keyPair.privateKey as RSAPrivateKey;

PEM Parsing

Supports PKCS#1 and PKCS#8 formats:

final publicKey = RsaKeyHelper.parsePublicKeyFromPem('''
-----BEGIN PUBLIC KEY-----
MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8A...
-----END PUBLIC KEY-----
''');

final privateKey = RsaKeyHelper.parsePrivateKeyFromPem('''
-----BEGIN PRIVATE KEY-----
MIIEvQIBADANBgkqhkiG9w0BAQEFAASC...
-----END PRIVATE KEY-----
''');

PEM Encoding

final pemPublic = RsaKeyHelper.encodePublicKeyToPemPKCS1(publicKey);
final pemPrivate = RsaKeyHelper.encodePrivateKeyToPemPKCS1(privateKey);

---

Usage Examples

Complete Authentication Flow

// 1. User Registration
Future<void> registerUser(String email, String password) async {
  final (hash, spec) = TomPasswordHasher.hashPassword(password);
  await db.createUser(
    email: email,
    passwordHash: hash,
    hashSpec: spec,
  );
}

// 2. User Login
Future<String?> login(String email, String password) async {
  final user = await db.findUserByEmail(email);
  if (user == null) return null;
  
  if (!TomPasswordHasher.verifyPassword(
    password,
    user.passwordHash,
    user.hashSpec,
  )) {
    return null;
  }
  
  // Create JWT token
  final token = TomServerJwtToken(
    {'userId': user.id, 'email': user.email},
    encryptedData: {'roles': user.roles},
    expiresIn: Duration(hours: 24),
  );
  
  return token.getJWT('my-app');
}

// 3. Token Verification (Middleware)
Future<User?> authenticateRequest(String? authHeader) async {
  if (authHeader == null || !authHeader.startsWith('Bearer ')) {
    return null;
  }
  
  final token = TomClientJwtToken(authHeader.substring(7));
  final userId = token.payload?['userId'] as String?;
  
  if (userId == null) return null;
  
  return db.findUserById(userId);
}

Secure Data Exchange

// Sender: Encrypt and sign
Future<Map<String, String>> sendSecureMessage(
  String message,
  RSAPublicKey recipientPublicKey,
  RSAPrivateKey senderPrivateKey,
) async {
  final messageBytes = utf8.encode(message);
  
  // Encrypt with recipient's public key
  final encrypted = rsaEncrypt(recipientPublicKey, Uint8List.fromList(messageBytes));
  
  // Sign with sender's private key
  final signature = rsaSign(senderPrivateKey, Uint8List.fromList(messageBytes));
  
  return {
    'encrypted': base64Encode(encrypted),
    'signature': base64Encode(signature),
  };
}

// Recipient: Verify and decrypt
Future<String?> receiveSecureMessage(
  Map<String, String> data,
  RSAPrivateKey recipientPrivateKey,
  RSAPublicKey senderPublicKey,
) async {
  final encrypted = base64Decode(data['encrypted']!);
  final signature = base64Decode(data['signature']!);
  
  // Decrypt with recipient's private key
  final decrypted = rsaDecrypt(recipientPrivateKey, Uint8List.fromList(encrypted));
  
  // Verify sender's signature
  if (!rsaVerify(senderPublicKey, decrypted, Uint8List.fromList(signature))) {
    return null; // Signature invalid!
  }
  
  return utf8.decode(decrypted);
}

---

Best Practices

Key Management

1. **Never hardcode production keys** - Use environment variables or secure vaults 2. **Rotate keys regularly** - Implement key rotation policies 3. **Use separate keys** for different purposes (signing vs encryption) 4. **Protect private keys** - Store with restricted permissions

// ❌ Bad: Hardcoded key
final secretKey = SecretKey('my-secret');

// ✅ Good: Environment variable
final secretKey = SecretKey(Platform.environment['JWT_SECRET']!);

Password Hashing

1. **Always store the spec** alongside the hash for future algorithm changes 2. **Tune parameters** for your hardware (target 0.5-1 second hash time) 3. **Never use** MD5, SHA-1, or plain SHA-256 for passwords

// ❌ Bad: Hash without spec
db.saveUser(passwordHash: hash);

// ✅ Good: Hash with spec
db.saveUser(passwordHash: hash, hashSpec: spec);

JWT Tokens

1. **Set appropriate expiration** - Shorter for sensitive operations 2. **Use encrypted payloads** for sensitive data 3. **Validate all tokens** server-side 4. **Don't store sensitive data** in unencrypted claims

// ❌ Bad: Long-lived token with sensitive data in public claims
TomServerJwtToken(
  {'userId': '123', 'creditCard': '4111...'},
  expiresIn: Duration(days: 365),
);

// ✅ Good: Short-lived token with encrypted sensitive data
TomServerJwtToken(
  {'userId': '123'},
  encryptedData: {'creditCard': '4111...'},
  expiresIn: Duration(hours: 1),
);

---

Error Handling

TomJwtTokenException

Thrown for JWT-related errors:

try {
  final token = TomClientJwtToken(invalidJwtString);
} on TomJwtTokenException catch (e) {
  print('JWT Error: ${e.defaultUserMessage}');
  print('Error Key: ${e.key}');
}

Common error keys: - `jwt_token.error.decryption_failed` - Failed to decrypt encrypted payload

Password Hashing Errors

try {
  TomPasswordHasher.buildKeyDerivator('InvalidSpec');
} catch (e) {
  print('Invalid specification: $e');
}

RSA Signature Verification

Returns `false` instead of throwing for invalid signatures:

if (!rsaVerify(publicKey, data, signature)) {
  // Handle invalid signature
  throw SecurityException('Signature verification failed');
}

---

Module Structure

crypto/
├── crypto.md              # This documentation
├── jwt_token.dart         # JWT token handling
├── password_hashing.dart  # Argon2 password hashing
├── rsa_encryption.dart    # RSA encrypt/decrypt/sign/verify
└── rsa_tools.dart         # RSA key generation and PEM handling

---

Dependencies

This module depends on:

• **Little Things Module**: `TomException` for error handling
• **External**: `pointycastle` package for cryptographic operations

license.md

BSD 3-Clause License

Copyright (c) 2026, Various unknown authors from the internet and 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 release: non-destructive Markdown region merge built on

`tom_doc_specs`' insert-marker engine. - `MarkdownMerge.merge` refreshes `tom.managed.<key>` regions, preserves `tom.override.<key>` regions and all free text, and suppresses managed refresh when an override exists for the same key. - Helpers: `managedKeys`, `overrideKeys`, `managedBlock`, `overrideBlock`.

README.md

Non-destructive **Markdown region merge**: let a generator refresh designated regions of a Markdown file on every run *without clobbering hand-authored prose*. Built on `tom_doc_specs`' insert-marker engine (`InsertMarkerParser`/`InsertMarkerProcessor`) rather than a hand-written parser, so parsing stays AST-based and is shared with the rest of the Tom toolchain.

The model

A Markdown document is tokenised into **insert-marker regions** delimited by HTML comments (invisible in any Markdown preview). Each region carries a *variable*; this package gives the variable a meaning via a prefix:

> **Marker syntax note.** These markers reuse the existing > `tom_doc_specs` insert-marker grammar (`<!--$insert:VAR-->` / > `<!--$end-insert-->`, variable `[a-zA-Z][a-zA-Z0-9_.]+`). The behaviour > (managed-refresh / override-replace / free-text-preserve) is encoded in the > `tom.managed.` / `tom.override.` variable prefix. This is the reconciled form > of the `@tom:managed` / `@tom:override` concept from the website spec §6.2: > the engine could not parse the `@tom:` spelling, so the variable prefix > carries the same intent.

Usage

import 'package:tom_markdown_merge/tom_markdown_merge.dart';

const merge = MarkdownMerge();

// Refresh managed regions the generator currently owns:
final updated = merge.merge(currentMarkdown, {
  'overview': 'freshly generated overview prose',
  'summary': 'freshly generated summary',
});

// Inspect which keys a document declares:
final managed = merge.managedKeys(currentMarkdown);   // Set<String>
final overridden = merge.overrideKeys(currentMarkdown); // a generator should
                                                        // skip these keys

// Emit a fresh block (e.g. on first generation):
final block = merge.managedBlock('overview', 'first draft');

Rules in detail

• A **managed** region whose key is in the `generated` map **and is not

overridden** has its content replaced. - An **override** region is never touched. If both an override and a managed region exist for the same key, the override wins and the managed region is left as-is (not refreshed). - A managed key **absent** from the `generated` map is left as-is (the generator no longer owns it). - All free text and foreign `$insert:` regions are preserved verbatim. - Malformed markers (nested or unclosed) raise `FormatException` (propagated from the underlying parser) — merges fail loud rather than silently corrupt.

Constraints

• Marker keys must match the insert-marker variable grammar (`[a-zA-Z0-9_.]`).
• Region content must not itself contain insert markers (nesting is rejected).

Testing

dart test

CHANGELOG.md

1.0.0

• Initial release. `PackageScanner` walks a framework repo's direct-child Dart

packages and produces a `PackageInfo` per package: derived `ComponentStatus` (released → published → works → not_started), classified license token, version, description and external links. Built on `tom_build_base`'s `NatureDetector`. Tolerates packages without a `tom_project.yaml`. Extracted from the website's `gen_modules` generator (enterprise_flutter_web, spec §12 todo 7).

README.md

Scan a workspace's framework repos and, for each Dart package, derive a `PackageInfo`: its publication **status**, license token, version, description and external links. Built on [`tom_build_base`](../tom_build_base)'s `NatureDetector`.

Extracted from the website's `gen_modules` generator (`enterprise_flutter_web`, spec §12 todo 7) so that both the module-index generator and the status-report generator are thin users of one scanner.

Usage

import 'package:tom_package_scanner/tom_package_scanner.dart';

final scanner = PackageScanner(
  sourceRoot: '../..',                       // filesystem base
  pathPrefix: 'tom_agent_container/tom_ai',  // recorded in component paths
  locThreshold: 200,
);

// includedRepos are public by construction (the seed intersects with
// `gh repo list --visibility public`), so repoIsPublic is true for them.
final packages = scanner.scanRepo('d4rt', repoIsPublic: true);
for (final pkg in packages) {
  print('${pkg.sourcePath}: ${pkg.status.yamlValue} (${pkg.statusReason})');
}

Discovery is **one level deep**: the direct child folders of a repo that carry a `pubspec.yaml` are its packages (matching the license-audit convention). The result is sorted by folder name for stable, diff-friendly output.

Status ladder

`scanRepo` derives one of four `ComponentStatus` values (spec §4.2.1), checked top-to-bottom — the first match wins:

LOC counting walks `lib/**/*.dart`, skipping blank lines, full-line `//` comments, and generated files (`*.g.dart`, `*.freezed.dart`, `*.options.dart`).

> **`published` vs. `publish_to: none`.** A package marked `publish_to: none` > (e.g. an internal library that lives in a public repo) is **not** `published` > — it falls through to `works` / `not_started` on its `lib/` size. This is a > deliberate refinement of the spec §5.1 example, which classified a > `publish_to: none` package as published; "published" here means *a real pub > package*, which is the more useful signal for the public site.

License token

`PackageInfo.license` prefers a human-curated `tom_project.yaml license:`; when absent it classifies the package's `LICENSE` / `license.md` body via `classifyLicense` (body-driven, SPDX-or-closed vocabulary — the single source of truth, re-exported by the website's `tool/seed/license_classifier.dart`). Unrecognised or absent licenses yield `null`.

Display metrics

`PackageInfo.metrics` carries three **statically-measured** display metrics (spec §4.2.2) — the scanner runs no `dart test` and makes no process calls, so all three are counted directly off the source tree:

These are display-only and never feed status, **except** `loc`, which also drives the >200-line rule above. `gen_modules` writes them per component plus a summed module-level rollup; `gen_status_report` surfaces them as the LOC / Tests / Test LOC columns.

Tolerating a missing `tom_project.yaml`

Eight Dart packages in the included repos have no `tom_project.yaml`. The scanner synthesises their record from `pubspec.yaml` and the `LICENSE` body alone; `PackageInfo.hasProjectYaml` is `false` so callers can flag them.

Tests

dart test   # or: testkit :test

Fixture trees under `test/fixtures/` exercise each status branch (stub, real-`lib/`, public publishable, release marker) and the missing-`tom_project.yaml` case.

CHANGELOG.md

1.0.0

• Initial version.

README.md

A sample command-line application with an entrypoint in `bin/`, library code in `lib/`, and example unit test in `test/`.

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. Generic agentic building blocks extracted from

`tom_brain_substrate`: `CancellationToken` / `CancellationTokenSource`, `OperationCancelled`, `CloseGuard`, `buildUniqueById`, `textPreview`, `HttpDate`, and `YamlConfigReader`.

README.md

Generic, domain-free building blocks for agentic systems in the TOM framework. Everything here depends only on `tom_basics` (plus `yaml` / `yaml_edit` for the config read/write path and `crypto` for the content-hash convention) and is safe to reuse across the brain, the assistant, and any future agent runtime. The package is deliberately **`dart:io`-free**, so it stays usable from `dart:io`-forbidding consumers such as `tom_brain_shared`.

What lives here

Integration with `tom_basics` / `tom_core_*` (reuse vs own)

This package sits in the **lightweight tier**: it depends only on `tom_basics` and never on `tom_core_kernel` (which pulls `dart:io`, `tom_reflection`, `http`, and a SQL client). The table below records, per audited concern, whether the primitive is **reused** from `tom_basics` or **owned** here — and, where a heavier `tom_core_*` analogue exists, why it is not reused.

**Audit result (prototype-plan-2 item 7):** no divergent re-implementation of a `tom_core_kernel`-owned primitive was found. Logging is reused; clock and config helpers have no `tom_core_*` equivalent; the shutdown coordinator is a deliberate lightweight-tier alternative to the kernel's `dart:io`-coupled `TomShutdownCleanup`. The audited helpers (`CategoryLog`, `systemClock`, `AsyncShutdownCoordinator`, `YamlConfigReader`/`MapFieldReader`/`YamlConfigWriter`) keep their existing unit tests.

What does NOT live here

Anything brain- or domain-specific. The `sha256:<hex>` prompt-hash convention and the `BrainEventBus<E>` live in `tom_brain_shared`; retry / circuit-breaker transport policy lives in `tom_core_kernel`.

README.md

Extended VS Code bridge server with full Tom Framework D4rt bridges.

Overview

This project provides an alternative bridge server binary (`core_bs`) for the VS Code extension. While the base `tom_bs` (from `tom_vscode_bridge`) includes only DCli and VS Code API bridges, `core_bs` adds the complete Tom Framework bridge set via `tom_core_d4rt`:

• **tom_core_kernel** — Core framework types
• **tom_core_server** — Server-side components
• **tom_build** — Build system APIs
• **tom_dist_ledger** — Distributed ledger
• **tom_process_monitor** — Process monitoring
• **tom_basics** — Basic utilities
• **tom_reflection** — Reflection support

Usage

Configure the VS Code extension to use `core_bs` instead of `tom_bs` for full Tom Framework access in D4rt scripts.

Architecture

tom_core_bridge (bin/core_bs.dart)
├── tom_vscode_bridge       — Base bridge server + VS Code API bridges
│   ├── tom_d4rt_dcli       — DCli bridges
│   └── tom_vscode_scripting_api — VS Code API wrappers
└── tom_core_d4rt            — Tom Framework bridges
    ├── tom_core_kernel
    ├── tom_core_server
    ├── tom_build
    ├── tom_dist_ledger
    ├── tom_process_monitor
    ├── tom_basics
    └── tom_reflection

license.md

BSD 3-Clause License

Copyright (c) 2025-2026, Al The Bear / Alexis Kyaw

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

<!-- This README describes the package. If you publish this package to pub.dev, this README's contents appear on the landing page for your package.

For information about how to write a good package README, see the guide for [writing package pages](https://dart.dev/tools/pub/writing-package-pages).

For general information about developing packages, see the Dart guide for [creating packages](https://dart.dev/guides/libraries/create-packages) and the Flutter guide for [developing packages and plugins](https://flutter.dev/to/develop-packages). -->

TODO: Put a short description of the package here that helps potential users know whether this package might be useful for them.

Features

TODO: List what your package can do. Maybe include images, gifs, or videos.

Getting started

TODO: List prerequisites and provide or point to information on how to start using the package.

Usage

TODO: Include short and useful examples for package users. Add longer examples to `/example` folder.

const like = 'sample';

Additional information

TODO: Tell users more about the package: where to find more information, how to contribute to the package, how to file issues, what response they can expect from the package authors, and more.

build.md

To build the `tom_dartscript_bridges` (d4rt) tool, follow these steps:

1. **Build Prerequisites**: Ensure that `tom_d4rt_dcli` has been built first, as it contains the base bridges and VS Code integration required by this project. 2. **Delete generated files**: Delete all `*.g.dart` files in the project to ensure a clean build.

   find . -name "*.g.dart" -delete

3. **Generate bridges**: Run the build runner to generate the necessary target bridges.

   dart run build_runner build --delete-conflicting-outputs

4. **Compile**: Compile the tool using the workspace build tools.

d4rt_cli_api_design.md

**Quest:** cli_dartbridge **Date:** 2026-02-02 **Status:** Design Draft (Rev 3)

---

outer.d4rt

.load inner.d4rt print('after inner');

inner.d4rt

.start-script var x = 1; return x + 1; .end

The multiline state is per-context, so nested replays don't interfere:

class ExecutionContext { final String workingDirectory; final String? sourceFile; final bool silent;

// Each context has its own multiline state MultilineMode multilineMode = MultilineMode.none; final List<String> multilineBuffer = []; }

---

Execution Context Stack

Problem: Nested Replay and Directory Context

When replaying files, several context aspects must be managed:

1. **Working Directory**: Relative paths in a replay file should resolve from that file's location 2. **Nested Replays**: A replay file can trigger another replay via `.load` or `.replay` 3. **Multiline State**: Each replay context needs its own multiline buffer 4. **Error Unwinding**: On error, all context levels must unwind properly 5. **Session Recording**: Only top-level commands should record to session

Known Bug in Current Implementation

> **⚠️ BUG**: The current REPL implementation has a bug where multiline state is global, > not per-context. This can be triggered with `.replay`/`.load` commands that contain > multiline blocks. If a nested replay file starts a multiline block, it corrupts the > parent context's multiline state. > > **Example of bug trigger:** > ``` > # outer.d4rt > .start-script > var x = 1; > .load inner.d4rt # inner.d4rt also has .start-script > return x; > .end > ``` > > The implementation in this design fixes this bug by moving multiline state into > `ExecutionContext`, giving each nested execution its own isolated multiline buffer.

Solution: Execution Context Stack

/// Represents a single execution context in the stack.
class ExecutionContext {
  /// The working directory for this context.
  final String workingDirectory;
  
  /// The source file being executed (null for interactive).
  final String? sourceFile;
  
  /// Whether to record commands to session.
  final bool recordToSession;
  
  /// Whether output is suppressed.
  final bool silent;
  
  /// Multiline mode for this context.
  MultilineMode multilineMode = MultilineMode.none;
  
  /// Multiline buffer for this context.
  final List<String> multilineBuffer = [];
  
  /// Parent context (null for root).
  final ExecutionContext? parent;
}

/// Manages the execution context stack.
class ContextStack {
  final _stack = <ExecutionContext>[];
  
  /// Current context (top of stack).
  ExecutionContext get current => _stack.last;
  
  /// Push a new context for file execution.
  void push(ExecutionContext context) => _stack.add(context);
  
  /// Pop context after execution completes.
  ExecutionContext pop() => _stack.removeLast();
  
  /// Current working directory.
  String get cwd => current.workingDirectory;
  
  /// Whether currently in silent mode.
  bool get silent => current.silent;
  
  /// Depth of nesting (0 = interactive).
  int get depth => _stack.length - 1;
}

Execution Flow

1. User calls: cli.replay('setup.d4rt')
   └── Push context: { cwd: '/project', file: 'setup.d4rt', silent: false }
   
2. setup.d4rt line 5: .load libs/common.d4rt
   └── Push context: { cwd: '/project/libs', file: 'common.d4rt', silent: false }
   
3. common.d4rt completes
   └── Pop context → restore cwd to '/project'
   
4. setup.d4rt completes
   └── Pop context → restore original cwd

Directory Resolution Rules

String resolvePath(String path) {
  if (path.startsWith('/')) {
    // Absolute path - use as-is
    return path;
  } else if (path.startsWith('~/')) {
    // Home expansion
    return '${Platform.environment['HOME']}${path.substring(1)}';
  } else if (path == '-') {
    // Data directory shortcut
    return dataDirectory;
  } else {
    // Relative path - resolve from current context's cwd
    return '${contextStack.cwd}/$path';
  }
}

---

Session Recording

Rules for Session Recording

Implementation

Future<dynamic> processPrompt(String line, {bool? recordToSession}) async {
  final shouldRecord = recordToSession ?? 
    (contextStack.depth == 0 && currentSessionId != null);
  
  if (shouldRecord) {
    _appendToSessionFile(line);
  }
  
  return _executeCommand(line);
}

---

D4rt Stdlib Imports

Available Bridged Packages

The D4rt stdlib provides bridges for the following Dart core packages. These are registered during D4rt initialization and available in the REPL environment.

Key Classes for CLI API

The `CliRuntime` interface exposes these bridged classes:

// Directory.current is already bridged with getter/setter
print(Directory.current.path);        // Works in D4rt
Directory.current = Directory('/tmp'); // Works in D4rt

// Platform static getters are bridged
print(Platform.operatingSystem);       // Works in D4rt
print(Platform.environment['HOME']);   // Works in D4rt

// Process static methods are bridged
final result = await Process.run('ls', ['-la']);  // Works in D4rt

Init Source Considerations

The CLI should ensure these imports are available in the init source block so scripts can use them directly:

// Suggested init source imports (generated by getImportBlock()):
import 'dart:async';
import 'dart:io';
import 'dart:convert';
import 'dart:math';
import 'dart:collection';
import 'dart:typed_data';
// Note: dart:isolate may require special handling for sandboxed contexts

---

Global Variable Registration

Bridge Registration vs Initialization

The `cli` global follows a two-phase pattern:

1. **Registration**: Happens during bridge registration (early) 2. **Initialization**: Happens later when the REPL/CLI is ready with full context

This separation is necessary because: - Bridge registration happens before the REPL is fully configured - The `cli` API needs access to the D4rt instance AND the CLI controller - Some state (like data directory, session management) isn't available during registration

Export Barrel

// lib/tom_d4rt_cli_api.dart
/// Export barrel for D4rt CLI API.
/// 
/// This barrel exports all types needed for the `cli` global variable
/// and is used by the bridge generator.
library;

export 'src/api/cli_api.dart';
export 'src/api/cli_controller.dart';
export 'src/api/cli_state.dart';
export 'src/api/cli_exceptions.dart';
export 'src/api/cli_result_types.dart';
export 'src/api/cli_runtime.dart';
export 'src/api/execution_context.dart';

Build Configuration

In tom_d4rt_dcli/build.yaml

modules: - name: cli_api barrelFiles: - package:tom_d4rt_dcli/tom_d4rt_cli_api.dart barrelImport: package:tom_d4rt_dcli/tom_d4rt_cli_api.dart outputPath: lib/src/bridges/cli_api_bridge.dart

### Two-Phase Initialization

// Phase 1: Registration (during bridge init) // Creates a placeholder or uninitialized controller class CliGlobalHolder { D4rtCliController? _controller;

D4rtCliController get controller { if (_controller == null) { throw CliException('cli global not yet initialized. ' 'This happens when accessing cli before REPL startup.'); } return _controller!; }

void initialize(D4rtCliController controller) { _controller = controller; }

bool get isInitialized => _controller != null; }

// Register during bridge registration void registerBridges(D4rt d4rt) { TomD4rtDcliBridge.register(d4rt); // Register cli holder - not yet initialized d4rt.defineGlobal('cli', _cliHolder); }

// Phase 2: Initialization (during REPL startup) void initializeCli(D4rt d4rt, CliState state) { final controller = D4rtCliController(d4rt, state); _cliHolder.initialize(controller); }

// Called during REPL/CLI startup after bridge registration void registerBridges(D4rt d4rt) { TomD4rtDcliBridge.register(d4rt); initializeCliGlobal(d4rt); }

### Init Source Integration

// Generated in getImportBlock(): // import 'package:tom_d4rt_dcli/tom_d4rt_cli_api.dart';

// Available in D4rt scripts: void main() { cli.cd('/project'); cli.replay('setup.d4rt'); final allClasses = cli.classes(); }

---

Error Handling

Exception Types

/// Base exception for CLI operations.
class CliException implements Exception {
  final String message;
  final String? command;
  final StackTrace? stackTrace;
  
  CliException(this.message, {this.command, this.stackTrace});
  
  @override
  String toString() => command != null 
    ? 'CliException: $message (command: $command)'
    : 'CliException: $message';
}

/// File not found during execution.
class FileNotFoundException extends CliException {
  final String path;
  FileNotFoundException(this.path) : super('File not found: $path');
}

/// Directory not found during navigation.
class DirectoryNotFoundException extends CliException {
  final String path;
  DirectoryNotFoundException(this.path) : super('Directory not found: $path');
}

/// Error during code execution.
class ExecutionException extends CliException {
  ExecutionException(String message, {String? command, StackTrace? stackTrace})
    : super(message, command: command, stackTrace: stackTrace);
}

/// Error during replay.
class ReplayException extends CliException {
  final String file;
  final int line;
  final CliException cause;
  
  ReplayException(this.file, this.line, this.cause)
    : super('Error at $file:$line: ${cause.message}');
}

Error Propagation in Nested Replay

Future<int> replay(String path) async {
  final resolvedPath = resolvePath(path);
  final file = File(resolvedPath);
  
  if (!file.existsSync()) {
    throw FileNotFoundException(resolvedPath);
  }
  
  // Push context with its own multiline state
  contextStack.push(ExecutionContext(
    workingDirectory: file.parent.path,
    sourceFile: resolvedPath,
    silent: true, // replay is silent
  ));
  
  try {
    final lines = file.readAsLinesSync();
    var lineNumber = 0;
    
    for (final line in lines) {
      lineNumber++;
      if (line.trim().isEmpty || line.startsWith('#')) continue;
      
      try {
        await processPrompt(line, recordToSession: false);
      } catch (e) {
        if (e is CliException) {
          throw ReplayException(resolvedPath, lineNumber, e);
        }
        rethrow;
      }
    }
    
    return lineNumber;
  } finally {
    // Always restore context (including any incomplete multiline state)
    contextStack.pop();
  }
}

---

Result Types

/// Result of code execution.
class ExecuteResult {
  final bool success;
  final dynamic result;
  final String? error;
  final StackTrace? stackTrace;
  final int sourcesLoaded;
  
  const ExecuteResult({
    required this.success,
    this.result,
    this.error,
    this.stackTrace,
    this.sourcesLoaded = 1,
  });
}

/// Information about a class in the environment.
class ClassInfo {
  final String name;
  final String? importPath;
  final List<String> constructors;
  final List<String> methods;
  final List<String> getters;
  final List<String> setters;
  final List<String> staticMethods;
}

/// Information about an enum in the environment.
class EnumInfo {
  final String name;
  final String? importPath;
  final List<String> values;
}

/// Information about a method/function.
class MethodInfo {
  final String name;
  final String? importPath;
  final String signature;
  final bool isAsync;
}

/// Information about a variable.
class VariableInfo {
  final String name;
  final String type;
  final bool isFinal;
  final dynamic value;
}

/// Information about an import.
class ImportInfo {
  final String path;
  final List<String> classes;
  final List<String> enums;
  final List<String> functions;
  final List<String> variables;
}

/// Detailed symbol information.
class SymbolInfo {
  final String name;
  final SymbolKind kind;
  final String? documentation;
  final Map<String, dynamic> details;
}

enum SymbolKind { class_, enum_, method, variable, import }

---

Command to Method Mapping Table

---

Implementation Phases

Phase 1: Extract State (CliState)

• Create `CliState` class without Console dependency
• Include multiline state (mode, buffer)
• Move state fields from `ReplState` to `CliState`
• Keep `ReplState` as subclass adding Console

Phase 2: Extract Logic (D4rtCliController)

• Create `D4rtCliController` implementing `D4rtCliApi`
• Move command handlers from `D4rtReplBase`
• Replace print statements with return values
• Implement multiline handling in controller

Phase 3: Implement Context Stack

• Create `ExecutionContext` and `ContextStack`
• Move multiline state into context
• Refactor `replay()` and `execute()` to use stack
• Add proper error unwinding

Phase 4: Wire Up ReplBase

• Refactor `D4rtReplBase` to delegate to controller
• Add IO wrapper layer for terminal interaction
• Verify existing behavior preserved

Phase 5: Register Bridge

• Create export barrel `tom_d4rt_cli_api.dart`
• Add to bridge generator config
• Initialize `cli` global during startup

Phase 6: Testing

• Unit tests for controller (no terminal)
• Integration tests for replay/context
• Multiline tests across replay boundaries
• E2E tests in D4rt REPL

---

Files to Create/Modify

New Files (in `lib/src/api/`)

Export Barrel

Files to Modify

---

File Extensions

Extension Mapping by Tool

Notes on Extensions

1. **`*.d4rt` and `*.dcli`** are the new standard extensions for replay files: - D4rt looks for `*.d4rt` files in the `plays` command - DCli looks for `*.dcli` files in the `plays` command - Both can be executed with `.replay` or `.load` - The content format is identical (one command per line)

2. **`*.d4rt.dart`** replaces `*.exec.dart`: - Used for executable Dart source files - Listed by the `executes` command - Executed with `.execute <file>` - The `.dart` suffix ensures IDE support for syntax highlighting

3. **Cross-tool compatibility**: - `*.dcli` files CAN be run in d4rt, but may have issues if they contain commands with special meaning in d4rt but not in dcli - `*.d4rt` files should NOT be run in dcli if they use d4rt-specific features

API Method Considerations

The listing methods should filter by the appropriate extensions:

// In D4rt:
List<String> plays() => _listFiles('*.d4rt');
List<String> executes() => _listFiles('*.d4rt.dart');

// In DCli:
List<String> plays() => _listFiles('*.dcli');
List<String> executes() => _listFiles('*.d4rt.dart'); // Same as D4rt

---

Backward Compatibility

• All existing REPL commands work unchanged
• Session files remain compatible
• Replay files remain compatible (including multiline blocks)
• Old `*.replay.txt` files still work (but new files should use `*.d4rt`/`*.dcli`)
• Old `*.exec.dart` files still work (but new files should use `*.d4rt.dart`)
• `D4rtReplBase` API unchanged for subclasses

---

Open Questions

1. **Should `cli.replay()` in a script record to session?** Decision: No by default, but allow `recordToSession: true` parameter.

2. **Should `cli` be available in fresh `execute()` contexts?** Decision: Yes, `cli` is always available as it's registered as a bridge.

3. **How to handle infinite recursion in replay?** Decision: Maximum nesting depth (50 levels), throw on exceed.

4. **Incomplete multiline at end of replay file?** Decision: Throw error - multiline block must be closed with `.end`.

testing.md

This document explains how to test D4rt and DCli tools using replay files and the built-in verification system.

Run a test file in test mode

d4rt mytest.d4rt -test

Run with output to a file

d4rt mytest.d4rt -test -output=test_results.txt

Alternative syntax

d4rt -run-replay mytest.d4rt -test -output=results.txt

### Test Mode Behavior

When running in test mode:

1. Commands are executed silently (no normal output)
2. All verification failures are collected
3. A test report is generated showing:
   - File executed
   - Start/end timestamps
   - Number of lines executed
   - Verification failures (if any)
   - Final PASSED/FAILED status
4. Exit code is 0 for PASSED, 1 for FAILED

### Running All Tests

A script is provided to run all replay tests in the `test/replay` directory, including compatibility tests for DCli:

From the project root

./test/replay/run_tests.sh

This script will:
1. Find all `*.d4rt` files in `test/replay`
2. Run each test using the local `d4rt` tool
3. Find all `*.dcli` files in the `tom_d4rt_dcli` project (for compatibility verification)
4. Store results in `test/results`
5. Report overall PASSED/FAILED status

Verification Functions

The following verification functions are available in D4rt/DCli scripts:

Basic Verification

// Verify a boolean condition
verify(count > 0, 'Count should be positive');
verify(result == expected, 'Result mismatch');

Equality Checks

// Verify two values are equal
verifyEquals(result, 42, 'Result should be 42');
verifyEquals(name, 'test');  // Message is optional

Null Checks

// Verify value is not null
verifyNotNull(result, 'Result should not be null');

// Verify value is null
verifyNull(error, 'Error should be null');

String Verification

// Verify string contains substring
verifyContains(output, 'success', 'Output should contain success');

// Verify string matches pattern
verifyMatches(email, r'^[\w.]+@[\w.]+$', 'Invalid email format');

List Verification

// Verify list is not empty
verifyNotEmpty(results, 'Results should not be empty');

// Verify list has specific length
verifyLength(items, 3, 'Should have exactly 3 items');

Exception Verification

// Verify that code throws an exception
verifyThrows(() => divide(1, 0), 'Division by zero should throw');

Test Summary

// Print a summary of all verifications
testSummary();  // Returns true if all passed

Writing Test Files

Example Test File (mytest.d4rt)

// Test file for D4rt CLI functionality
// Run with: d4rt mytest.d4rt -test

// Define a helper function
int add(int a, int b) => a + b;

// Test the function
verify(add(2, 3) == 5, 'add(2, 3) should equal 5');
verifyEquals(add(0, 0), 0, 'add(0, 0) should equal 0');
verifyEquals(add(-1, 1), 0);

// Test string operations
var greeting = 'Hello, World!';
verifyContains(greeting, 'Hello', 'Should contain Hello');
verifyMatches(greeting, r'^\w+,\s+\w+!$', 'Should match greeting pattern');

// Print summary (optional in test mode, but useful for manual runs)
testSummary();

Multi-line Test Blocks

You can use `.start-execute` and `.end` for isolated test blocks:

// Main test file
var counter = 0;

// This block runs in a fresh environment
.start-execute
var x = 10;
verify(x == 10, 'x should be 10');
.end

// counter is still 0 here (not affected by execute block)
verify(counter == 0, 'counter should be unaffected');

Use `.start-file` for blocks that run in the current environment:

// Main test file
var sharedValue = 0;

.start-file
sharedValue = 42;
verify(sharedValue == 42, 'sharedValue should be set');
.end

// sharedValue is now 42
verify(sharedValue == 42, 'sharedValue persists');

Test Output Format

When running in test mode, the output looks like:

Test Mode: /path/to/mytest.d4rt
Started: 2026-02-02T15:30:00.000Z

Lines executed: 25

Result: PASSED
Completed: 2026-02-02T15:30:01.234Z

With failures:

Test Mode: /path/to/mytest.d4rt
Started: 2026-02-02T15:30:00.000Z

Lines executed: 25

VERIFICATION FAILURES (2):
  - add(2, 3) should equal 5
  - Should contain Hello

Result: FAILED
Completed: 2026-02-02T15:30:01.234Z

CI/CD Integration

Exit Codes

• `0` - All tests passed
• `1` - One or more tests failed or an error occurred

GitHub Actions Example

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      
      - name: Setup Dart
        uses: dart-lang/setup-dart@v1
        
      - name: Run D4rt Tests
        run: |
          d4rt tests/test_basic.d4rt -test -output=results/basic.txt
          d4rt tests/test_advanced.d4rt -test -output=results/advanced.txt
          
      - name: Upload Test Results
        if: always()
        uses: actions/upload-artifact@v3
        with:
          name: test-results
          path: results/

Best Practices

1. **One assertion per verification** - Makes failures easier to diagnose 2. **Descriptive error messages** - Include expected vs actual values 3. **Group related tests** - Use comments to organize test sections 4. **Use `.start-execute` for isolation** - When tests shouldn't affect each other 5. **Run `testSummary()` at the end** - For manual test runs 6. **Check exit codes in CI** - Fail builds on test failures

Debugging Tests

For more detailed output during development:

Run with debug mode

DEBUG=true d4rt mytest.d4rt -test

Run without test mode to see all output

d4rt mytest.d4rt

See Also

• `.help test` - In-REPL help for test commands
• `verify --help` - Documentation for verify functions
• `info verify` - Shows verify function signature in REPL

license.md

Copyright (c) 2024-2026 Peter Nicolai Alexis Kyaw. All rights reserved.

This code is proprietary and confidential. Unauthorized copying, modification,
distribution, or use of this software, via any medium, is strictly prohibited.

For licensing inquiries, find me on LinkedIn under "Alexis Kyaw".

CHANGELOG.md

1.0.0

• Initial version.

README.md

<!-- This README describes the package. If you publish this package to pub.dev, this README's contents appear on the landing page for your package.

For information about how to write a good package README, see the guide for [writing package pages](https://dart.dev/tools/pub/writing-package-pages).

For general information about developing packages, see the Dart guide for [creating packages](https://dart.dev/guides/libraries/create-packages) and the Flutter guide for [developing packages and plugins](https://flutter.dev/to/develop-packages). -->

TODO: Put a short description of the package here that helps potential users know whether this package might be useful for them.

Features

TODO: List what your package can do. Maybe include images, gifs, or videos.

Getting started

TODO: List prerequisites and provide or point to information on how to start using the package.

Usage

TODO: Include short and useful examples for package users. Add longer examples to `/example` folder.

const like = 'sample';

Additional information

TODO: Tell users more about the package: where to find more information, how to contribute to the package, how to file issues, what response they can expect from the package authors, and more.

review_findings.md

Date: 10 January 2026

Critical Issues

Code Quality Issues

Documentation Issues

Structure Issues

Potential Improvements

1. **Fix broken test and example**: Replace `Awesome` references with actual tom_core_flutter classes 2. **Add `publish_to: none`**: Clarify this is a private package 3. **Update README.md**: Write actual documentation for the package 4. **Export missing files**: Add `authentication.dart` to barrel exports 5. **Clean up dead code**: Remove unused `_onChange` in `tom_fields.dart` 6. **Clean up empty directories**: Remove `iding/` or add placeholder readme 7. **Consider removing placeholder modules**: Camera, localstorage, preferences, qrcode are empty 8. **Add local _copilot_guidelines**: If this package has specific patterns

Dependency Review

Current dependencies appear appropriate: - `flutter` - Required for Flutter widgets - `tom_core` - Core framework (path dependency is correct for monorepo) - `cupertino_icons` - May not be needed if not using Cupertino widgets - `fetch_client` - HTTP client for web platform - `timezone_to_country` - Timezone utilities - `web` - Web platform APIs

**Potential cleanup**: Verify `cupertino_icons` is actually used in any widget code.

license.md

Copyright (c) 2024-2026 Peter Nicolai Alexis Kyaw. All rights reserved.

This code is proprietary and confidential. Unauthorized copying, modification,
distribution, or use of this software, via any medium, is strictly prohibited.

For licensing inquiries, find me on LinkedIn under "Alexis Kyaw".

CHANGELOG.md

1.0.0

• Initial version.

README.md

<!-- This README describes the package. If you publish this package to pub.dev, this README's contents appear on the landing page for your package.

For information about how to write a good package README, see the guide for [writing package pages](https://dart.dev/tools/pub/writing-package-pages).

For general information about developing packages, see the Dart guide for [creating packages](https://dart.dev/guides/libraries/create-packages) and the Flutter guide for [developing packages and plugins](https://flutter.dev/to/develop-packages). -->

TODO: Put a short description of the package here that helps potential users know whether this package might be useful for them.

Features

TODO: List what your package can do. Maybe include images, gifs, or videos.

Getting started

TODO: List prerequisites and provide or point to information on how to start using the package.

Usage

TODO: Include short and useful examples for package users. Add longer examples to `/example` folder.

const like = 'sample';

Additional information

TODO: Tell users more about the package: where to find more information, how to contribute to the package, how to file issues, what response they can expect from the package authors, and more.

beanlocator.md

The Tom Bean Locator System provides a lightweight dependency injection container that uses Dart reflection to automatically discover, instantiate, and wire service beans. It supports environment-specific and platform-specific bean implementations for flexible configuration.

Table of Contents

• [Tom Bean Locator System](#tom-bean-locator-system)
• [Table of Contents](#table-of-contents)
• [Overview](#overview)
• [How It Works](#how-it-works)
• [Quick Start](#quick-start)
• [Complete Initialization Sequence](#complete-initialization-sequence)
• [Basic Bean Registration and Resolution](#basic-bean-registration-and-resolution)
• [Declaring Bean Dependencies](#declaring-bean-dependencies)
• [Core Components](#core-components)
• [TomBean](#tombean)
• [Resolution by Type](#resolution-by-type)
• [Resolution by Name](#resolution-by-name)
• [Callable Syntax](#callable-syntax)
• [TomComponent](#tomcomponent)
• [Bean Registration](#bean-registration)
• [Concrete Type Beans](#concrete-type-beans)
• [Interface-Based Beans](#interface-based-beans)
• [Named Beans](#named-beans)
• [Optional Typed Beans Registration](#optional-typed-beans-registration)
• [Environment and Platform Beans](#environment-and-platform-beans)
• [Environment-Specific Beans](#environment-specific-beans)
• [Platform-Specific Beans](#platform-specific-beans)
• [Implementation Resolution](#implementation-resolution)
• [Error Handling](#error-handling)
• [TomBeanLocatorException](#tombeanlocatorexception)
• [Common Error Keys](#common-error-keys)
• [Best Practices](#best-practices)
• [1. Initialize in Correct Sequence](#1-initialize-in-correct-sequence)
• [2. Prefer Interfaces](#2-prefer-interfaces)
• [3. Store Bean References](#3-store-bean-references)
• [4. Use Specific Environments](#4-use-specific-environments)
• [5. No Bean-Resultion in Constructors](#5-no-bean-resultion-in-constructors)
• [6. For Client/Flutter Apps: Use Environment-Specific main\_xxx.dart Files](#6-for-clientflutter-apps-use-environment-specific-main_xxxdart-files)

Overview

The bean locator system consists of several key components:

1. **`TomBean<T>`**: A generic handle for accessing dependency-injected beans with lazy resolution by type or name.

2. **`TomComponent`**: An annotation to mark classes as beans, optionally specifying the interface they implement.

The bean locator integrates with the [Runtime Module](../runtime/runtime.md) for environment and platform configuration:

• **`TomEnvironment`**: Configuration for runtime environments (dev, test, prod) with hierarchy support
• **`TomPlatform`**: Configuration for target platforms (iOS, Android, Web, etc.)
• **`TomRuntime`**: Central manager for current environment and platform state

How It Works

1. Classes are annotated with `@tomReflector` and `@TomComponent` 2. At startup, `initializeBeanContext()` scans annotated classes via reflection 3. Beans are instantiated and registered in the global context 4. Components request beans via `TomBean<T>().get()` 5. The locator resolves the best-matching implementation based on type, environment, and platform

Quick Start

Complete Initialization Sequence

The bean context requires the runtime system to be initialized first. Here's the complete sequence:

import 'package:tom_core/tom_core.dart';

// Define environments
const environmentProd = TomEnvironment('prod');
const environmentDev = TomEnvironment('dev', parent: environmentProd, isDevelopment: true);

void initializeRuntime() {
  TomRuntime.addEnvironment(environmentProd);
  TomRuntime.addEnvironment(environmentDev);
  TomRuntime.setRootEnvironment(environmentProd);
  TomRuntime.setCurrentEnvironment(
    TomPlatformUtils.current.getTomEnvVars()["env"], 
    "prod",
  );
  TomRuntime.getCurrentEnvironment().initialize();
  TomRuntime.initializePlatform();
}

// Application main
void main() {
  // 1. Set environment variable (before anything else)
  //    for standalone/server envVar will contain the actual environment 
  //    valuesm so there should be no need to do this
  TomPlatformUtils.envVars["env"] = "dev"; 
  
  // 2. Set platform utilities using the predefined constants/field
  //    for standalone/server application use serverPlatformUtils which are defined
  //    if you import tom_server.dart
  TomPlatformUtils.setCurrentPlatform(clientPlatformUtils);

  
  // 3. Initialize reflection
  initializeReflection();
  
  // 4. Initialize runtime (sets environment and platform)
  initializeRuntime();
  
  // 5. Initialize bean context (AFTER runtime is ready)
  initializeBeanContext();
  
  // 6. Now beans can be resolved
  final userService = TomBean<UserService>().get();
  runApp(MyApp());
}

Basic Bean Registration and Resolution

import 'package:tom_core/tom_core.dart';

// 1. Define a service interface
abstract class UserService {
  User getUser(int id);
}

// 2. Implement the service (annotate with reflector and component)
@tomReflector
@TomComponent(UserService)
class UserServiceImpl implements UserService {
  @override
  User getUser(int id) => User(id: id, name: 'User $id');
}

// 3. After initialization (see above), resolve and use the bean
void useService() {
  final userService = TomBean<UserService>().get();
  final user = userService.getUser(42);
  print('Got user: ${user.name}');
}

Declaring Bean Dependencies

Services can declare dependencies on other beans using `TomBean<T>` fields:

@tomReflector
@TomComponent(OrderService)
class OrderServiceImpl implements OrderService {
  // Dependencies are declared as TomBean fields
  TomBean<UserService> userService = TomBean();
  TomBean<PaymentService> paymentService = TomBean();
  TomBean<InventoryService> inventoryService = TomBean();
  
  // Named bean dependency
  TomBean<DatabaseConnection> database = TomBean.fromName("primaryDb");
  
  @override
  Order createOrder(int userId, List<Item> items) {
    // Dependencies are resolved lazily on first access
    final user = userService().getUser(userId);
    paymentService().charge(user, calculateTotal(items));
    inventoryService().reserve(items);
    return Order(user: user, items: items);
  }
}

Core Components

TomBean

`TomBean<T>` is the primary interface for accessing beans from the container.

Resolution by Type

// Create a handle (does not resolve immediately)
final TomBean<UserService> userServiceBean = TomBean();

// Resolution happens on first access
final userService = userServiceBean.get();

Resolution by Name

// Register a named bean
TomBean.withName('mainConfig', AppConfig(host: 'localhost'));

// Resolve by name
final config = TomBean<AppConfig>.fromName('mainConfig').get();

Callable Syntax

TomBean supports callable syntax for concise access:

final TomBean<UserService> userService = TomBean();
final user = userService().getUser(123);  // Equivalent to .get().getUser(123)

TomComponent

The `@TomComponent` annotation marks a class as a bean:

// Concrete type (registered by its own type)
@tomReflector
@tomComponent  // Uses TomNoInterface
class ConfigService { ... }

// Interface-based (registered by interface type)
@tomReflector
@TomComponent(UserService)
class UserServiceImpl implements UserService { ... }

Bean Registration

Concrete Type Beans

Beans without an interface are registered by their concrete type:

@tomReflector
@tomComponent
class LoggingService {
  void log(String message) => print('[LOG] $message');
}

// Resolve by concrete type
final logger = TomBean<LoggingService>().get();

Interface-Based Beans

Beans with interfaces are registered by the interface type:

abstract class CacheService {
  void put(String key, Object value);
  Object? get(String key);
}

@tomReflector
@TomComponent(CacheService)
class MemoryCacheService implements CacheService {
  final _cache = <String, Object>{};
  @override
  void put(String key, Object value) => _cache[key] = value;
  @override
  Object? get(String key) => _cache[key];
}

// Resolve by interface
final cache = TomBean<CacheService>().get();

Named Beans

Register and resolve beans by name:

// Register
TomBean.withName('primaryDb', DatabaseConnection(host: 'primary.db'));
TomBean.withName('replicaDb', DatabaseConnection(host: 'replica.db'));

// Resolve
final primaryDb = TomBean<DatabaseConnection>.fromName('primaryDb').get();
final replicaDb = TomBean<DatabaseConnection>.fromName('replicaDb').get();

Optional Typed Beans Registration

To resolve to service instances that are not marked with @tomReflector/@tomComponent, you can register beans by type:

// Register, for example in platform initialization, environment initialization...
TomBean.withType(MyService, MyServiceImplementation());

...

// Resolve
final myService = TomBean<MyService>.get();

Note: these manual registrations take precedence over annotated components and can be used to override the hardcoded service setup for test, e.g. to inject mock bean implementations.

Environment and Platform Beans

The bean locator integrates with `TomEnvironment` and `TomPlatform` from the [Runtime Module](../runtime/runtime.md) to select different bean implementations based on the current context.

> **Note**: For detailed documentation on `TomEnvironment`, `TomPlatform`, and `TomRuntime`, see the [Runtime Module Documentation](../runtime/runtime.md).

Environment-Specific Beans

@tomReflector
@TomComponent(EmailService)
@TomEnvironment('production')
class SmtpEmailService implements EmailService { ... }

@tomReflector
@TomComponent(EmailService)
@TomEnvironment('development', isDevelopment: true)
class ConsoleEmailService implements EmailService { ... }

@tomReflector
@TomComponent(EmailService)
@TomEnvironment('test', isTest: true)
class MockEmailService implements EmailService { ... }

Platform-Specific Beans

@tomReflector
@TomComponent(StorageService)
@platformIos
class IosStorageService implements StorageService { ... }

@tomReflector
@TomComponent(StorageService)
@platformAndroid
class AndroidStorageService implements StorageService { ... }

@tomReflector
@TomComponent(StorageService)
@platformWeb
class WebStorageService implements StorageService { ... }

Implementation Resolution

When multiple implementations exist for an interface, the locator selects based on:

1. **Exact Match**: Both environment AND platform match current runtime 2. **Platform Match**: Platform matches, no environment constraint 3. **Environment Match**: Environment matches, no platform constraint 4. **Default**: No environment or platform constraints

// Default implementation (no constraints)
@tomReflector
@TomComponent(PaymentService)
class DefaultPaymentService implements PaymentService { ... }

// Platform-specific (selected on iOS)
@tomReflector
@TomComponent(PaymentService)
@platformIos
class ApplePayService implements PaymentService { ... }

// Environment-specific (selected in production)
@tomReflector
@TomComponent(PaymentService)
@TomEnvironment('production')
class StripePaymentService implements PaymentService { ... }

// Exact match (selected on iOS in production)
@tomReflector
@TomComponent(PaymentService)
@platformIos
@TomEnvironment('production')
class IosProductionPaymentService implements PaymentService { ... }

Error Handling

TomBeanLocatorException

All bean locator errors throw `TomBeanLocatorException`:

try {
  final service = TomBean<NonExistentService>().get();
} on TomBeanLocatorException catch (e) {
  print('Error key: ${e.key}');
  print('Message: ${e.defaultUserMessage}');
}

Common Error Keys

Best Practices

1. Initialize in Correct Sequence

The initialization order is critical:

void main() {
  // 1. Set environment variables FIRST
  TomPlatformUtils.envVars["env"] = "dev";
  
  // 2. Set platform utilities
  TomPlatformUtils.setCurrentPlatform(myPlatformUtils);
  
  // 3. Initialize reflection
  initializeReflection();
  
  // 4. Initialize runtime
  initializeRuntime();
  
  // 5. Initialize bean context LAST (requires runtime to be ready)
  initializeBeanContext();
  
  runApp(MyApp());
}

2. Prefer Interfaces

Use interface-based registration for testability:

// Good: Interface-based, easy to mock
@TomComponent(UserRepository)
class SqlUserRepository implements UserRepository { ... }

// Less flexible: Concrete type only
@tomComponent
class SqlUserRepository { ... }

3. Store Bean References

For frequently accessed beans, store the handle:

// Class field
class MyController {
  final _userService = TomBean<UserService>();
  
  void doSomething() {
    // Efficient: Resolution cached after first call
    _userService().performAction();
  }
}

4. Use Specific Environments

Create environment hierarchies for configuration:

// Base configuration
const baseEnv = TomEnvironment('base');

// Environment-specific overrides
const devEnv = TomEnvironment('dev', parent: baseEnv, isDevelopment: true);
const prodEnv = TomEnvironment('prod', parent: baseEnv);

5. No Bean-Resultion in Constructors

The bean locator uses lazy resolution, but circular dependencies during construction will fail:

// Avoid: ServiceA constructor calls TomBean<ServiceB>().get()
//        while ServiceB constructor calls TomBean<ServiceA>().get()

// Better: Never use any TomBean-based component inside of any of the constructors 
// of the beans. All TomBean-components must have a simple no-args constructor!
//

6. For Client/Flutter Apps: Use Environment-Specific main_xxx.dart Files

To avoid changes to the code for deployment it is most convenient to have separate files for each environment which prepares the environment setting and then call the main()-method of the actual main.dart-File:

import 'package:tom_core/tom_core.dart';
import 'main.dart' as app;


// Application main
void main() {
  // 1. Set environment variable (before anything else)
  TomPlatformUtils.envVars["env"] = "dev"; 

  // here you can also set other values (e.g. default user/password for dev-environment)
  
  app.main();

}

---

Dependencies

This module depends on:

• **Runtime Module**: `TomEnvironment` and `TomPlatform` for environment and platform-specific bean selection
• **Reflection Module**: For bean discovery and instantiation via reflection

context.md

The Tom Execution Context System provides zone-based context propagation for passing request-scoped values through synchronous and asynchronous call chains without explicit parameter passing.

Table of Contents

• [Overview](#overview)
• [Quick Start](#quick-start)
• [Core Components](#core-components)
• [TomExecutionContext](#tomexecutioncontext)
• [TomContextEntry](#tomcontextentry)
• [TomContextProviders](#tomcontextproviders)
• [Context Propagation](#context-propagation)
• [Context Composition](#context-composition)
• [Default Context](#default-context)
• [Best Practices](#best-practices)

Overview

The context system consists of three main components:

1. **`TomExecutionContext`**: Container for context entries that runs code in a Dart Zone with those values available.

2. **`TomContextEntry<T>`**: A typed wrapper for a function that provides a context value.

3. **`TomContextProviders`**: Static methods that extract common values from the current zone's `TomPrincipal`.

How It Works

1. Create a `TomExecutionContext` with named entries 2. Call `runInContext()` or `runInContextAsync()` with your code 3. Inside that code, use `getFromCurrentZone<T>()` to retrieve values 4. Context flows automatically through async boundaries

Quick Start

import 'package:tom_core/tom_core.dart';

void main() {
  // Create a context with custom values
  final context = TomExecutionContext({
    'requestId': TomContextEntry<String>(() => 'req-12345'),
    'userId': TomContextEntry<int>(() => 42),
  });

  // Run code within the context
  context.runInContext(() {
    processRequest();
  });
}

void processRequest() {
  // Access context from anywhere in the zone
  final ctx = getFromCurrentZone<TomExecutionContext>();
  final requestId = ctx?.contextMap['requestId']?.contextFunction();
  print('Processing request: $requestId');
}

Core Components

TomExecutionContext

The main context container that stores named entries and runs code in a zone.

Creating a Context

// Empty context
final context = TomExecutionContext({});

// With entries
final context = TomExecutionContext({
  'tenant': TomContextEntry<String>(() => 'acme-corp'),
  'user': TomContextEntry<User>(() => currentUser),
});

// With parent context (entries are inherited)
final childContext = TomExecutionContext(
  {'childKey': TomContextEntry(() => 'value')},
  parentContext: parentContext,
);

Getting Context Entries

// Get entry by name with type checking
final entry = context.getEntry<String>('tenant');
final value = entry?.value;  // Access via value getter

// Static method to get value from current zone
final userId = TomExecutionContext.getValueFromCurrentZone<String>('userId');

Modifying a Context

final context = TomExecutionContext({});

// Add entries
context.add('locale', TomContextEntry<String>(() => 'en-US'));

// Merge another context
final otherContext = TomExecutionContext({'theme': TomContextEntry(() => 'dark')});
context.combineWith(otherContext);

// Clear all entries
context.clear();

Running Code in Context

// Synchronous
final result = context.runInContext(() {
  return computeValue();
});

// Asynchronous
final result = await context.runInContextAsync(() async {
  return await fetchData();
});

// With additional zone values
context.runInContext(() {
  // Custom zone values available
}, zoneValues: {'customKey': 'customValue'});

TomContextEntry

A typed wrapper for lazy value providers.

Creating Entries

// Static value
final entry = TomContextEntry<String>(() => 'constant-value');

// Dynamic value (computed each access)
final entry = TomContextEntry<DateTime>(() => DateTime.now());

Accessing Values

// Via contextFunction (original method)
final value = entry.contextFunction();

// Via value getter (recommended)
final value = entry.value;

// Via call operator (shortest)
final value = entry();

// Via ~ operator (alternative)
final value = ~entry;

// Value from another zone value
final entry = TomContextEntry<String>(() {
  return getFromCurrentZone<TomPrincipal>()?.organization ?? 'default';
});

TomContextProviders

Static methods for extracting common values from `TomPrincipal`:

// Organization/tenant info
TomContextProviders.getOrganization()  // Returns 'default' if no principal
TomContextProviders.getApplication()
TomContextProviders.getProcess()

// Server locale
TomContextProviders.getLanguage()      // Returns 'en' if no principal
TomContextProviders.getCountry()       // Returns 'XX' if no principal
TomContextProviders.getTimezone()      // Returns 'utc' if no principal

// Client locale
TomContextProviders.getClientLanguage()
TomContextProviders.getClientCountry()
TomContextProviders.getClientTimezone()

Context Propagation

Context values automatically propagate through async boundaries:

final context = TomExecutionContext({
  'traceId': TomContextEntry<String>(() => generateTraceId()),
});

await context.runInContextAsync(() async {
  // TraceId available here
  await step1();
  
  // Still available after await
  await step2();
  
  // And in nested async calls
  await step3();
});

Future<void> step1() async {
  final ctx = getFromCurrentZone<TomExecutionContext>();
  // TraceId still accessible
}

Context Composition

Contexts can be nested, with inner contexts overriding outer values:

final tenantContext = TomExecutionContext({
  'tenant': TomContextEntry<String>(() => 'acme'),
});

final userContext = TomExecutionContext({
  'user': TomContextEntry<String>(() => 'john'),
});

final requestContext = TomExecutionContext({
  'requestId': TomContextEntry<String>(() => 'req-123'),
  'tenant': TomContextEntry<String>(() => 'override-tenant'),
});

tenantContext.runInContext(() {
  // tenant = 'acme'
  
  userContext.runInContext(() {
    // tenant = 'acme', user = 'john'
    
    requestContext.runInContext(() {
      // tenant = 'override-tenant', user = 'john', requestId = 'req-123'
    });
  });
});

Default Context

The `tomExecutionContext` global provides a pre-configured context with standard providers:

// Pre-configured entries:
// - organization, application, process
// - language, country, timezone
// - clientLanguage, clientCountry, clientTimezone

tomExecutionContext.runInContext(() {
  // All standard context values available
  final org = TomContextProviders.getOrganization();
  final lang = TomContextProviders.getLanguage();
});

Best Practices

1. Use Type-Safe Entries

Always specify the type parameter for type safety:

// Good
TomContextEntry<String>(() => 'value')
TomContextEntry<User>(() => currentUser)

// Avoid
TomContextEntry(() => 'value')  // Type inferred as dynamic

2. Handle Missing Context

Always check for null when retrieving context:

final ctx = getFromCurrentZone<TomExecutionContext>();
if (ctx == null) {
  // Handle case where code runs outside context
  return defaultValue;
}

3. Create Context Once

Create contexts at request boundaries, not inside loops:

// Good: Create once per request
void handleRequest(Request req) {
  final context = TomExecutionContext({
    'requestId': TomContextEntry(() => req.id),
  });
  
  context.runInContext(() => processRequest(req));
}

// Avoid: Creating context in inner loops

4. Use Async Version for Async Code

Use `runInContextAsync` for async code to ensure proper zone handling:

// Good
await context.runInContextAsync(() async {
  await asyncOperation();
});

// May have issues
context.runInContext(() {
  asyncOperation();  // Zone might not propagate correctly
});

5. Document Context Dependencies

Document which context values your functions expect:

/// Processes the order.
/// 
/// Requires the following context entries:
/// - `userId`: The current user's ID
/// - `tenantId`: The tenant identifier
Future<void> processOrder(Order order) async {
  final ctx = getFromCurrentZone<TomExecutionContext>()!;
  final userId = ctx.contextMap['userId']!.contextFunction();
  // ...
}

---

Dependencies

This module depends on:

• **Little Things Module**: Zone utilities for context propagation
• **Security Module**: `TomPrincipal` for authenticated user context

http_connection.md

The HTTP Connection module provides a comprehensive infrastructure for making HTTP requests from client applications to remote servers. It offers type-safe API definitions, configurable HTTP clients, and automatic serialization/deserialization.

Table of Contents

• [Overview](#overview)
• [Quick Start](#quick-start)
• [Core Components](#core-components)
• [Architecture](#architecture)
• [Best Practices](#best-practices)
• [Dependencies](#dependencies)

---

Overview

This module consists of several interconnected components:

Quick Start

1. Configure the Remote Context

First, set up where your application should send requests:

import 'package:tom_core/tom_core.dart';

void main() {
  // Set the remote server context (do this once at app startup)
  TomClientRemoteContext.setCurrent(
    TomClientRemoteContext(
      Uri.parse('https://api.example.com'),
    ),
  );
}

2. Define Your API

Create type-safe API definitions:

final userApi = TomApi(
  id: 'users',
  name: 'User Management API',
  uri: '/api/v1/users',
  endpoints: [
    TomApiEndpoint<UserResponse, CreateUserRequest>(
      id: 'create',
      uri: '/create',
      method: TomHttpMethod.post,
      consumes: TomMimeType.json,
      produces: TomMimeType.json,
    ),
    TomApiEndpoint<UserResponse, void>(
      id: 'getById',
      uri: '/{id}',
      method: TomHttpMethod.get,
    ),
  ],
);

// Register the API globally
TomRemoteApis.registerApi(userApi);

3. Execute Requests

Use `TomServerEndpoint` for type-safe request execution:

// Create the endpoint executor
final endpoint = TomServerEndpoint.createApiServerEndpoint<
  CreateUserRequest,
  UserResponse
>(userApi['create']);

// Execute the request
final request = CreateUserRequest(name: 'John Doe', email: 'john@example.com');
final (response, error) = await endpoint.send(request);

if (error?.hasError ?? false) {
  print('Error: ${error!.statusCode} - ${error.reasonPhrase}');
} else {
  print('Created user: ${response.id}');
}

Core Components

TomRemoteApis

A singleton registry for managing all API definitions in your application.

// Register an API
TomRemoteApis.registerApi(myApi);

// Retrieve by ID
final api = TomRemoteApis.getApiById('myApi');

// Or use bracket notation with global accessor
final endpoint = tomRemoteApis['myApi']['endpoint'];

TomApi

Represents a collection of related endpoints under a common base URI.

final api = TomApi(
  id: 'orders',
  name: 'Order API',
  uri: '/api/v1/orders',
  requestEncoding: utf8,
  responseEncoding: utf8,
  endpoints: [...],
);

TomApiEndpoint

Defines a single API endpoint with full configuration:

TomApiEndpoint<OrderResponse, CreateOrderRequest>(
  id: 'createOrder',
  uri: '/create',
  method: TomHttpMethod.post,
  consumes: TomMimeType.json,
  produces: TomMimeType.json,
  includeBearerAuthentication: true,
  followRedirects: false,
  requestHeaders: {'X-Custom-Header': 'value'},
)

TomHttpMethod

Predefined HTTP methods:

TomMimeType

Common MIME types for request/response content:

TomMimeType.json        // application/json
TomMimeType.html        // text/html
TomMimeType.plainText   // text/plain
TomMimeType.xml         // application/xml
TomMimeType.pdf         // application/pdf
TomMimeType.urlEncoded  // application/x-www-form-urlencoded
TomMimeType.multipartFormData  // multipart/form-data

TomServerChannel

Manages HTTP client connections with pooling:

final channel = TomServerChannel('api.example.com', 443);

// Prepare and execute a call
final call = channel.prepareCall(specs);
call.send(load);
final response = await call.readAsString(utf8);

// Close when done
channel.close();

TomServerCall

Low-level HTTP request handling with abort support:

final call = TomServerCall(client, specs);

// Send the request
call.send(TomServerCallLoad(
  stringBody: jsonEncode(data),
  contentType: 'application/json',
));

// Read the response
final bytes = await call.read();
final text = await call.readAsString(utf8);

// Or abort if needed
call.abort();

Usage Examples

Making a GET Request

final channel = TomServerChannel('api.example.com', 443);
final specs = TomServerCallSpecs(
  'GET',
  Uri.parse('https://api.example.com/users/123'),
  headers: {'Accept': 'application/json'},
);

final call = channel.prepareCall(specs);
call.send(TomServerCallLoad());
final response = await call.readAsString(utf8);
channel.close();

Making a POST Request with JSON Body

final specs = TomServerCallSpecs(
  'POST',
  Uri.parse('https://api.example.com/users'),
  headers: {'Content-Type': 'application/json'},
);

final call = TomServerCall(client, specs);
call.send(TomServerCallLoad(
  stringBody: '{"name": "John", "email": "john@example.com"}',
  contentType: 'application/json',
  encoding: utf8,
));

final statusCode = await call.getResponseStatusCode();
final body = await call.readAsString(utf8);

Using Form Data

final call = TomServerCall(client, specs);
call.send(TomServerCallLoad(
  bodyFields: {
    'username': 'john',
    'password': 'secret',
  },
));

Handling Errors

final (response, error) = await endpoint.send(request);

if (error != null && error.hasError) {
  switch (error.statusCode) {
    case 400:
      print('Bad request: ${error.response}');
      break;
    case 401:
      print('Unauthorized - token expired?');
      break;
    case 404:
      print('Resource not found');
      break;
    case 500:
      print('Server error: ${error.reasonPhrase}');
      break;
    default:
      print('Error ${error.statusCode}: ${error.response}');
  }
}

Custom HTTP Client Factory

class MyCustomClientFactory extends TomHttpClientFactory {
  @override
  Client getClient() {
    // Return your custom client (e.g., with interceptors)
    return MyCustomClient();
  }
}

// Set globally
TomHttpClientFactory.setGlobalHttpClientFactory(MyCustomClientFactory());

Separate Authentication Server

TomClientRemoteContext.setCurrent(
  TomClientRemoteContext(
    Uri.parse('https://api.example.com'),      // Main API
    Uri.parse('https://auth.example.com'),     // Auth server
  ),
);

Best Practices

1. Initialize Early

Set up `TomClientRemoteContext` as early as possible in your application lifecycle, typically in `main()`.

2. Register APIs Once

Register all your API definitions during app initialization:

void initializeApis() {
  TomRemoteApis.registerApi(userApi);
  TomRemoteApis.registerApi(orderApi);
  TomRemoteApis.registerApi(productApi);
}

3. Handle All Error Cases

Always check for errors after API calls:

final (response, error) = await endpoint.send(request);
if (error?.hasError ?? false) {
  // Handle error appropriately
  return;
}
// Process successful response

4. Close Channels When Done

If you create `TomServerChannel` instances manually, close them when finished:

final channel = TomServerChannel('api.example.com', 443);
try {
  // Use channel...
} finally {
  channel.close();
}

5. Use Type-Safe Endpoints

Prefer `TomServerEndpoint.createApiServerEndpoint` over manual HTTP calls for type safety and automatic serialization.

6. Configure Timeouts

Use appropriate timeouts for your use case to prevent hanging requests.

7. Secure Authentication

Bearer tokens are automatically included by default. Disable with `includeBearerAuthentication: false` for public endpoints:

TomApiEndpoint<PublicData, void>(
  id: 'publicEndpoint',
  method: TomHttpMethod.get,
  includeBearerAuthentication: false,  // No auth needed
)

Architecture

┌─────────────────────────────────────────────────────────────┐
│                      Application                             │
├─────────────────────────────────────────────────────────────┤
│  TomRemoteApis                                               │
│  ├── TomApi (users)                                          │
│  │   ├── TomApiEndpoint (create)                            │
│  │   └── TomApiEndpoint (getById)                           │
│  └── TomApi (orders)                                         │
│      └── TomApiEndpoint (list)                              │
├─────────────────────────────────────────────────────────────┤
│  TomServerEndpoint<Request, Response>                        │
│  └── Type-safe request/response handling                     │
├─────────────────────────────────────────────────────────────┤
│  TomServerChannel                                            │
│  └── TomHttpClientFactory                                    │
├─────────────────────────────────────────────────────────────┤
│  TomServerCall                                               │
│  └── Low-level HTTP operations                               │
├─────────────────────────────────────────────────────────────┤
│  TomClientRemoteContext                                      │
│  └── Server URI configuration                                │
└─────────────────────────────────────────────────────────────┘

---

Dependencies

This module depends on:

• **Little Things Module**: `TomException` base class for error handling
• **Security Module**: `TomBearerAuthentication` for authentication
• **Reflection Module**: `TomReflectionInfo` for JSON serialization support
• **Runtime Module**: Platform utilities for HTTP client creation

isolate_pooling.md

The isolate pooling module provides a robust framework for managing Dart isolates, enabling parallel processing and concurrent task execution in Dart and Flutter applications.

Table of Contents

• [Overview](#overview)
• [Quick Start](#quick-start)
• [Core Components](#core-components)
• [Best Practices](#best-practices)
• [Dependencies](#dependencies)

---

Overview

Dart isolates are independent execution contexts with their own memory space. While this provides true parallelism, managing isolate lifecycle and communication can be complex. This module abstracts away the complexity while providing:

• **Worker Isolates**: Spawn and manage isolated execution contexts
• **Bidirectional Communication**: Send commands to workers and receive responses
• **Command Pattern**: Execute commands as self-contained objects
• **Executor Pattern**: Register handlers to process incoming messages
• **Worker Pools**: Manage multiple workers with automatic load distribution

Quick Start

1. Create a Worker Context

final context = TomWorkerContext(
  TomEnvironment.development,
  TomPlatform.mobile,
  [],
  'Worker', // Name prefix for isolates
);

2. Spawn a Worker

final worker = await TomWorker.spawn(
  TomWorker.startRemoteIsolate,
  context,
);

3. Execute Commands

// Using TomCommand
class ComputeCommand extends TomCommand {
  final int value;
  ComputeCommand(this.value);

  @override
  Future<Object?> execute() async {
    return computeIntensive(value);
  }
}

final result = await worker.executeCommand(ComputeCommand(42));

4. Clean Up

worker.close();

Core Components

TomWorker

The main class for managing worker isolates. Handles spawning, communication, and lifecycle management.

Static Methods (for use in worker isolates)

TomWorkerContext

Configuration context for initializing worker isolates.

class MyWorkerContext extends TomWorkerContext {
  MyWorkerContext() : super(
    TomEnvironment.development,
    TomPlatform.mobile,
    [],
    'MyWorker',
  );

  @override
  Future<bool> initializeIsolate() async {
    // Called in the new isolate (static context)
    await setupResources();
    return true;
  }

  @override
  Future<bool> initializeWorker(TomWorker worker) async {
    // Called on the TomWorker instance
    worker.sendExecutorToIsolate(MyExecutor());
    return true;
  }
}

TomExecutor

Base class for command handlers. Register multiple executors to handle different command types.

class DataProcessorExecutor extends TomExecutor {
  @override
  Object execute(Object command) {
    if (command is ProcessDataCommand) {
      return processData(command.data);
    }
    return TomExecutor.noResult; // Let next executor handle it
  }
}

// Register executor
TomWorker.executors.add(DataProcessorExecutor());

TomCommand

Base class for self-executing commands that encapsulate both data and behavior.

class CalculateHashCommand extends TomCommand {
  final String input;
  CalculateHashCommand(this.input);

  @override
  Future<Object?> execute() async {
    return sha256.convert(utf8.encode(input)).toString();
  }
}

TomWorkerPool

Manages a pool of workers for automatic load distribution.

// Create pool
final pool = await TomWorkerPool.withSize(4, context);

// Execute commands (automatically distributed)
final results = await Future.wait([
  pool.execute(command1),
  pool.execute(command2),
  pool.execute(command3),
  pool.execute(command4),
]);

Architecture

┌──────────────────────────────────────────────────────────────┐
│                       Main Isolate                           │
│  ┌────────────────┐  ┌────────────────┐  ┌────────────────┐  │
│  │   TomWorker    │  │   TomWorker    │  │   TomWorker    │  │
│  │   (instance)   │  │   (instance)   │  │   (instance)   │  │
│  └───────┬────────┘  └───────┬────────┘  └───────┬────────┘  │
└──────────┼───────────────────┼───────────────────┼───────────┘
           │ SendPort          │ SendPort          │ SendPort
           ▼                   ▼                   ▼
┌──────────────────┐  ┌──────────────────┐  ┌──────────────────┐
│  Worker Isolate  │  │  Worker Isolate  │  │  Worker Isolate  │
│  ┌────────────┐  │  │  ┌────────────┐  │  │  ┌────────────┐  │
│  │ Executors  │  │  │  │ Executors  │  │  │  │ Executors  │  │
│  └────────────┘  │  │  └────────────┘  │  │  └────────────┘  │
└──────────────────┘  └──────────────────┘  └──────────────────┘

Usage Examples

Example 1: CPU-Intensive Computation

class FibonacciCommand extends TomCommand {
  final int n;
  FibonacciCommand(this.n);

  @override
  Future<Object?> execute() async {
    return _fibonacci(n);
  }

  int _fibonacci(int n) {
    if (n <= 1) return n;
    return _fibonacci(n - 1) + _fibonacci(n - 2);
  }
}

// Execute in worker to avoid blocking UI
final result = await worker.executeCommand(FibonacciCommand(40));

Example 2: Parallel Image Processing

final pool = await TomWorkerPool.withSize(4, context);

final images = ['image1.png', 'image2.png', 'image3.png', 'image4.png'];

final processedImages = await Future.wait(
  images.map((path) => pool.execute(ProcessImageCommand(path))),
);

Example 3: Bidirectional Communication

// In worker isolate - request data from main isolate
class FetchConfigExecutor extends TomExecutor {
  @override
  Object execute(Object command) {
    if (command is NeedsConfigCommand) {
      // Request config from main isolate
      return TomWorker.executeInCreator(GetConfigCommand());
    }
    return TomExecutor.noResult;
  }
}

Example 4: Custom Worker Context

class DatabaseWorkerContext extends TomWorkerContext {
  final String connectionString;

  DatabaseWorkerContext(this.connectionString) : super(
    TomEnvironment.production,
    TomPlatform.server,
    [],
    'DB',
  );

  @override
  Future<bool> initializeIsolate() async {
    // Initialize database connection in the isolate
    await Database.connect(connectionString);
    return true;
  }
}

Best Practices

1. Choose the Right Pattern

2. Pool Sizing

• For CPU-bound tasks: `Platform.numberOfProcessors` workers
• For I/O-bound tasks: More workers may be beneficial
• Consider memory overhead per isolate

3. Error Handling

try {
  final result = await worker.executeCommand(command);
} on RemoteError catch (e) {
  // Handle errors from the worker isolate
  print('Worker error: $e');
}

4. Avoid Common Pitfalls

• **Don't share mutable state**: Isolates have separate memory
• **Keep messages serializable**: Objects must be sendable across isolate boundaries
• **Clean up resources**: Always call `close()` when done with workers
• **Handle worker failures**: Implement health checks for long-running pools

5. Logging Considerations

When using logging in workers that delegate to a logging isolate, avoid logging within `sendToCreator()` to prevent stack overflow. Use `print()` for debugging in such cases.

API Reference

See the source code documentation in [tom_worker.dart](tom_worker.dart) for detailed API reference.

---

Dependencies

This module depends on:

• **Runtime Module**: `TomEnvironment` and `TomPlatform` for worker context configuration
• **Logging Module**: For logging within worker isolates

json.md

This module provides utilities for working with JSON data structures in Dart, including deep merging of maps, tree traversal with processing, path-based access, and pretty printing.

Table of Contents

• [Overview](#overview)
• [Quick Start](#quick-start)
• [Core Components](#core-components)
• [Best Practices](#best-practices)
• [Dependencies](#dependencies)

---

Overview

The JSON utilities module consists of two main files:

Quick Start

Pretty Printing JSON

import 'package:tom_core/src/tombase/json/pretty_json.dart';

// Format JSON for readability
final compact = '{"name":"MyApp","config":{"port":8080,"debug":true}}';
print(prettyJson(compact));
// Output:
// {
//   "name": "MyApp",
//   "config": {
//     "port": 8080,
//     "debug": true
//   }
// }

// Single-line formatted (for logging)
print(prettyJsonLine(compact));
// Output: { "name": "MyApp", "config": { "port": 8080, "debug": true } }

Merging Configuration Maps

import 'package:tom_core/src/tombase/json/map_merge_and_process.dart';

// Base configuration
final base = {
  'database': {
    'host': 'localhost',
    'port': 5432,
    'pool': {'min': 5, 'max': 20}
  },
  'features': ['auth', 'logging']
};

// Environment-specific overrides
final production = {
  'database': {
    'host': 'db.production.com',
    'pool': {'max': 100}
  },
  'features': ['auth', 'logging', 'metrics', 'tracing']
};

// Merge production overrides into base
mergeMapsOneSided(base, production);

// Result:
// {
//   'database': {
//     'host': 'db.production.com',  // overridden
//     'port': 5432,                  // preserved
//     'pool': {'min': 5, 'max': 100} // nested merge
//   },
//   'features': ['auth', 'logging', 'metrics', 'tracing']  // extended
// }

Core Components

Map Merge and Process (`map_merge_and_process.dart`)

`mergeMapsOneSided(base, override)`

Performs a deep merge of two maps, modifying `base` in-place.

**Merge Behavior:** - **Nested maps**: Merged recursively - **Arrays**: Elements merged by index; longer arrays append extra elements - **Primitives**: Override values replace base values - **New keys**: Added to base

`traverseAndProcess(tree, test, processor)`

Recursively walks a tree and transforms string values matching a condition.

final config = {
  'apiUrl': '${BASE_URL}/api',
  'wsUrl': '${BASE_URL}/ws',
  'name': 'MyApp'  // Won't match, left unchanged
};

traverseAndProcess(
  config,
  (s) => s.contains(r'${BASE_URL}'),
  (s) => s.replaceAll(r'${BASE_URL}', 'https://api.example.com'),
);
// config['apiUrl'] == 'https://api.example.com/api'

`traverseAndCreate(tree, nameTest, creator)`

Traverses a tree and invokes a callback for keys matching a pattern, allowing insertion of new nodes.

`getPathFromTree(baseTree, path, name)`

Navigates to a nested location using dot-separated paths.

final config = {
  'services': {
    'database': {
      'primary': {'host': 'db1.local', 'port': 5432}
    }
  }
};

final primary = getPathFromTree(config, 'services.database.primary', 'result');
// Returns: {'host': 'db1.local', 'port': 5432}

`getObjectFromTree(baseTree, path)`

Similar to `getPathFromTree` but returns the raw value (not wrapped).

final port = getObjectFromTree(config, 'services.database.primary.port');
// Returns: 5432

`processTree(tree, provider)`

Processes profile-based references in configuration trees.

Keys matching the pattern `keyName@path@profileName` are resolved using the provider function.

**Value Directives:** - `"..."` - Spread resolved data into current map - `"@"` - Replace with value at same key from resolved data - Other - Replace with entire resolved structure

`makeCleanJsonMap(map)`

Creates a sanitized copy containing only JSON-compatible types (String, int, double, bool, Map, List).

final dirty = {
  'name': 'App',
  'created': DateTime.now(),  // Not JSON-compatible
  'port': 8080
};

final clean = makeCleanJsonMap(dirty);
// clean == {'name': 'App', 'port': 8080}

Pretty JSON (`pretty_json.dart`)

`prettyJson(json)`

Formats a compact JSON string with indentation (2 spaces).

`prettyJsonLine(json)`

Formats JSON but collapses to a single line (useful for logging).

Usage Examples

Configuration Layering

A common pattern is to layer configurations from multiple sources:

// Load base configuration
final baseConfig = loadJsonFile('config/base.json');

// Load environment-specific overrides
final envConfig = loadJsonFile('config/${environment}.json');

// Load local developer overrides (if exists)
final localConfig = loadJsonFile('config/local.json');

// Merge in order of precedence
mergeMapsOneSided(baseConfig, envConfig);
mergeMapsOneSided(baseConfig, localConfig);

// baseConfig now contains fully merged configuration

Environment Variable Substitution

Replace placeholders with environment variables:

traverseAndProcess(
  config,
  (value) => value.startsWith(r'${') && value.endsWith('}'),
  (value) {
    final varName = value.substring(2, value.length - 1);
    return Platform.environment[varName] ?? value;
  },
);

Debugging API Responses

try {
  final response = await http.get(apiUrl);
  logger.debug('Response: ${prettyJson(response.body)}');
} catch (e) {
  logger.error('Failed to fetch: $e');
}

Best Practices

1. Immutability Consideration

`mergeMapsOneSided` modifies the base map in-place. If you need to preserve the original:

final merged = Map<String, dynamic>.from(baseConfig);
mergeMapsOneSided(merged, overrides);

2. Error Handling for Paths

Path-based access throws exceptions for invalid paths. Handle appropriately:

try {
  final value = getObjectFromTree(config, 'path.to.value');
} catch (e) {
  // Path doesn't exist, use default
  final value = defaultValue;
}

3. Type Safety

When working with dynamic maps, validate types before use:

final port = getObjectFromTree(config, 'database.port');
if (port is int) {
  connectToDatabase(port);
} else {
  throw ConfigurationError('database.port must be an integer');
}

4. JSON Sanitization

Always sanitize maps before JSON encoding if they may contain non-JSON types:

final safeData = makeCleanJsonMap(possiblyDirtyMap);
final jsonString = jsonEncode(safeData);

---

Dependencies

This module has no internal Tom dependencies. It uses:

• **dart:convert**: Built-in JSON encoding/decoding

little_things.md

Core utility functions for exception handling, zone management, stack trace processing, and data formatting.

Table of Contents

• [Overview](#overview)
• [Quick Start](#quick-start)
• [Core Components](#core-components)
• [Best Practices](#best-practices)
• [Dependencies](#dependencies)

---

Overview

The `little_things` module provides a collection of small but essential utilities used throughout the tom_core framework. It includes:

Quick Start

Import the Module

import 'package:tom_core/src/tombase/little_things/little_things.dart';
import 'package:tom_core/src/tombase/little_things/exception_base.dart';
import 'package:tom_core/src/tombase/little_things/formatting.dart';

Basic Exception Handling

// Throw a tracked exception
throw TomException(
  'USER_NOT_FOUND',
  'The requested user could not be found',
  parameters: {'userId': '12345'},
);

// Catch and handle
try {
  await fetchUser(id);
} on TomException catch (e) {
  log.error('Error ${e.uuid}: ${e.key}');
  e.printStackTrace(5); // Print top 5 frames
}

Core Components

TomException

A structured exception class that provides:

• **UUID Tracking**: Every exception gets a unique identifier
• **Request Correlation**: Link exceptions to specific requests via `requestUuid`
• **Timestamps**: Know exactly when the error occurred
• **Stack Traces**: Formatted traces stored for inspection
• **Auto Logging**: Optionally log exceptions automatically

TomException(
  'ERROR_KEY',           // Programmatic error code
  'User-friendly message',
  parameters: {...},     // Debug context
  requestUuid: reqId,    // Request correlation
  autoLog: true,         // Log immediately
  rootException: orig,   // Wrap original error
);

Zone Utilities

Access typed values from the current Dart zone without threading parameters:

// Store values in zone
runZoned(
  () => handleRequest(),
  zoneValues: {
    RequestContext: context,
    AppConfig: config,
  },
);

// Later, retrieve them anywhere in the call chain
final context = getFromCurrentZone<RequestContext>();
final config = getFromCurrentZone<AppConfig>();

Checked Execution

Transform errors with context-aware wrappers:

// Async version
final data = await runChecked(
  () => httpClient.get(url),
  (error, stack) => NetworkException(
    'Request to $url failed',
    originalError: error,
  ),
);

// Sync version
final config = runCheckedSync(
  () => parseConfig(json),
  (error, stack) => ConfigException('Invalid format', error),
);

Stack Trace Processing

Format and filter stack traces for readable output:

// Get as string
final trace = tomGetStackTrace(stackTrace, 10);  // Top 10 frames

// Get as list
final frames = tomGetStackTraceAsList(stackTrace);

// Get both at once
final (traceStr, framesList) = tomGetStackTraceAsTuple();

// Print directly to log
tomPrintStackTrace(stackTrace, message: 'Error occurred', depth: 5);

Time Zone Formatting

Convert minute offsets to ISO 8601 format:

convertMinutesToUtcOffset(0);     // "Z"
convertMinutesToUtcOffset(330);   // "+05:30" (IST)
convertMinutesToUtcOffset(-300);  // "-05:00" (EST)

Usage Examples

Complete Error Handling Pattern

Future<User> getUser(String id) async {
  return await runChecked(
    () async {
      final response = await api.fetchUser(id);
      if (response.statusCode == 404) {
        throw TomException(
          'USER_NOT_FOUND',
          'User not found',
          parameters: {'userId': id},
        );
      }
      return User.fromJson(response.body);
    },
    (error, stack) => TomException(
      'USER_FETCH_ERROR',
      'Failed to fetch user',
      rootException: error,
      stack: stack,
      parameters: {'userId': id},
      autoLog: true,
    ),
  );
}

Request Context with Zones

Future<void> handleRequest(HttpRequest request) async {
  final context = RequestContext(
    requestId: generateUuid(),
    timestamp: DateTime.now(),
  );

  await runZoned(
    () async {
      try {
        await processRequest(request);
      } on TomException catch (e) {
        // Exception automatically has access to context
        final ctx = getFromCurrentZone<RequestContext>();
        e.requestUuid = ctx?.requestId;
        rethrow;
      }
    },
    zoneValues: {RequestContext: context},
  );
}

Best Practices

Exception Keys

Use consistent, uppercase, underscore-separated keys:

// Good
'USER_NOT_FOUND'
'VALIDATION_ERROR'
'DATABASE_CONNECTION_FAILED'

// Avoid
'user not found'
'Error123'
'userNotFound'

Parameter Usage

Include relevant debugging context in parameters:

throw TomException(
  'VALIDATION_ERROR',
  'Invalid email format',
  parameters: {
    'field': 'email',
    'value': userInput,
    'pattern': emailRegex.pattern,
  },
);

Stack Trace Depth

Use appropriate depth for context without noise:

• **5-10 frames**: Typical for most debugging
• **-1 (all)**: For critical errors needing full context
• **1-3 frames**: For quick location identification

Auto Logging

Enable for unexpected/critical errors:

// Enable for unexpected errors
throw TomException('CRITICAL_ERROR', 'msg', autoLog: true);

// Disable for expected/handled errors
throw TomException('VALIDATION_ERROR', 'msg', autoLog: false);

---

Dependencies

This module has no internal Tom dependencies. It is a foundational module used by:

• **Logging Module**: For log levels and output configuration
• **HTTP Connection Module**: For `TomServerCallError` integration

logging.md

A flexible, configurable logging framework for Dart applications with support for multiple log levels, custom outputs, isolate-based logging, and remote log collection.

Table of Contents

• [Overview](#overview)
• [Quick Start](#quick-start)
• [Core Components](#core-components)
• [Best Practices](#best-practices)
• [Configuration Reference](#configuration-reference)
• [Dependencies](#dependencies)

---

Overview

The TomBase logging system provides:

• **Multiple Log Levels**: From trace (most verbose) to fatal (most severe)
• **Bitwise Level Composition**: Combine or exclude levels using `+` and `-` operators
• **Per-Class/Method Customization**: Set different log levels for specific code locations
• **Pluggable Outputs**: Console, remote server, isolate-based, or custom implementations
• **Multi-Isolate Support**: Centralized logging across all application isolates
• **Remote Logging**: Send logs to a centralized server for analysis

Quick Start

Basic Usage

import 'package:tom_core/src/tombase/logging/logging.dart';

void main() {
  // Use the global logger instance
  tomLog.info('Application started');
  tomLog.debug('Debug information');
  tomLog.error('Something went wrong');
  tomLog.warn('This might be a problem');
}

Configure Log Level

// Set to development mode (most verbose)
tomLog.setLogLevel(TomLogLevel.development);

// Set to production mode (info, warn, errors, status)
tomLog.setLogLevel(TomLogLevel.production);

// Set by name (useful for config files)
tomLog.setLogLevelByName('DEVELOPMENT');

Core Components

TomLogLevel

Represents logging levels as bit patterns, enabling flexible level composition.

Individual Levels (in order of verbosity)

Compound Levels

Level Composition

// Combine levels
var myLevel = TomLogLevel.info + TomLogLevel.error;

// Remove a level
var quieter = TomLogLevel.production - TomLogLevel.info;

// Check if a level matches
if (currentLevel.matches(TomLogLevel.debug)) {
  // This level is included
}

TomLogger

The main logger class providing structured logging capabilities.

Logging Methods

tomLog.trace('Entering function processData');    // Most verbose
tomLog.debug('Variable x = $x');                   // Debug info
tomLog.traffic('HTTP GET /api/users');             // Network traffic
tomLog.info('Server started on port 8080');        // General info
tomLog.warn('Config file not found, using defaults');
tomLog.status('Database migration complete');      // Status updates
tomLog.error('Failed to connect to database');     // Errors
tomLog.severe('Critical subsystem failure');       // Severe errors
tomLog.fatal('Unrecoverable error, shutting down'); // Fatal errors

Temporary Level Changes

// Temporarily increase verbosity for debugging
tomLog.pushLogLevel(TomLogLevel.trace);
debugComplexOperation();
tomLog.popLogLevel(); // Restore previous level

Per-Class/Method Levels

// Set level for a specific class
tomLog.addNameLevel('DatabaseService', TomLogLevel.trace);

// Set level for a specific method
tomLog.addNameLevel('ApiClient.sendRequest', TomLogLevel.debug);

// Remove custom level
tomLog.removeNameLevel('DatabaseService');

// Bulk configuration from string pattern
tomLog.setLogLevelExceptions('MyClass=DEBUG,ApiClient=TRACE');

TomLogOutput

Abstract base class for log output implementations.

Built-in Implementations

• **TomConsoleLogOutput**: Outputs to stdout/stderr (default)
• **TomRemoteLogOutput**: Sends logs to a remote server
• **TomIsolateLogOutput**: Routes logs through a dedicated logging isolate
• **TomCreatorLogOutput**: Routes worker isolate logs to main isolate

Custom Output

class FileLogOutput extends TomLogOutput {
  final File logFile;
  
  FileLogOutput(this.logFile);
  
  @override
  void output(
    TomLogLevel loggerLevel,
    TomLogLevel logLevel,
    String level,
    Object message,
    String isolateName,
    DateTime timeStamp, [
    String? origin,
  ]) {
    if (logLevel.matches(loggerLevel)) {
      logFile.writeAsStringSync(
        '$timeStamp $level ${convertToString(message)}\n',
        mode: FileMode.append,
      );
    }
  }
}

// Use custom output
tomLog.logOutput = FileLogOutput(File('app.log'));

Usage Examples

Application Startup

void main() async {
  // Configure logging based on environment
  if (isProduction) {
    tomLog.setLogLevel(TomLogLevel.production);
  } else {
    tomLog.setLogLevel(TomLogLevel.development);
  }
  
  tomLog.status('Application starting...');
  
  try {
    await initializeApp();
    tomLog.info('Application initialized successfully');
  } catch (e) {
    tomLog.fatal('Failed to initialize: $e');
    exit(1);
  }
}

Remote Logging

import 'package:tom_core/src/tombase/logging/remote_logoutput.dart';

void setupRemoteLogging() {
  // Configure sender identification
  TomRemoteLogMessage.globalSettingSenderId = 'frontend-01';
  
  // Set up remote endpoint
  TomRemoteLogOutput.remoteEndpoint = TomServerEndpoint<
      TomRemoteLogMessage, TomRemoteLogResult>(
    baseUrl: 'https://logs.example.com',
    path: '/api/logs',
  );
  
  // Activate remote logging
  tomLog.logOutput = TomRemoteLogOutput();
}

Multi-Isolate Logging

import 'package:tom_core/src/tombase/logging/logging_isolate.dart';

void main() async {
  // Main isolate: Start isolated logging
  await TomIsolateLogging.startIsolatedLogging(args);
  
  // All logs now route through the logging isolate
  tomLog.info('This goes through the logging isolate');
}

// In worker isolate initialization
void initWorker() {
  // Route logs back to main isolate
  TomIsolateLogging.startLoggingToCreator();
  tomLog.info('Worker started');
}

Custom Loggable Objects

class User implements TomLoggable {
  final String id;
  final String name;
  final String email;
  
  User(this.id, this.name, this.email);
  
  @override
  String get logRepresentation => 'User($id, $name)';
}

// Usage
final user = User('123', 'John', 'john@example.com');
tomLog.info(user); // Logs: "User(123, John)"

Delayed/Function Logging

class User implements TomLoggable {
  final String id;
  final String name;
  final String email;
  
  User(this.id, this.name, this.email);
  
  @override
  String get logRepresentation => 'User($id, $name)';
}

// Usage
final user = User('123', 'John', 'john@example.com');

tomLog.trace(() => 'Created user: $user'); // Will only be executed if the log level includes TRACE

Best Practices

1. Use Appropriate Log Levels

// ✓ Good
tomLog.trace('Entering processItems with ${items.length} items');
tomLog.debug('Processing item: ${item.id}');
tomLog.info('Processed ${count} items successfully');
tomLog.warn('Item ${id} has missing optional field');
tomLog.error('Failed to process item ${id}: $error');

// ✗ Avoid
tomLog.info('Debug: x = $x');  // Use debug() for debug info
tomLog.error('Warning: ...');   // Use warn() for warnings

2. Use Lazy Evaluation for Expensive Messages

// ✓ Good - message only constructed if debug is enabled
tomLog.debug(() => 'Complex object: ${expensiveToString(obj)}');

// ✗ Avoid - always constructs the string
tomLog.debug('Complex object: ${expensiveToString(obj)}');

3. Configure Levels Per Environment

void configureLogging(Environment env) {
  switch (env) {
    case Environment.development:
      tomLog.setLogLevel(TomLogLevel.development);
      break;
    case Environment.staging:
      tomLog.setLogLevel(TomLogLevel.extended);
      break;
    case Environment.production:
      tomLog.setLogLevel(TomLogLevel.production);
      break;
  }
}

4. Use Status for Important Lifecycle Events

tomLog.status('Server starting on port $port');
tomLog.status('Database connected');
tomLog.status('Shutting down gracefully');

5. Disable Stack Analysis in Production

// Improves performance in high-volume logging
if (isProduction) {
  TomLogger.globalSettingDetermineCaller = false;
}

Configuration Reference

Global Settings

Console Output Settings

File Structure

logging/
├── logging.dart           # Core logging system
├── logging_isolate.dart   # Multi-isolate support
├── remote_logoutput.dart  # Remote logging client
├── remote_logserver.dart  # Remote logging server
└── logging.md             # This documentation

---

Dependencies

This module depends on:

• **Little Things Module**: `TomException` for error handling and zone utilities
• **HTTP Connection Module**: For remote logging endpoints

observable.md

The Tom Observable System implements the Observer pattern to enable reactive data binding in Dart applications. It provides observable wrapper types for primitives, collections, and complex objects with automatic change notification and propagation.

Table of Contents

• [Overview](#overview)
• [Quick Start](#quick-start)
• [Core Components](#core-components)
• [TomObservable](#tomobservable)
• [TomObserver](#tomobserver)
• [TomFunctionObserver](#tomfunctionobserver)
• [Operators](#operators)
• [Observable Primitives](#observable-primitives)
• [Non-Nullable Types](#non-nullable-types)
• [Nullable Types](#nullable-types)
• [DateTime and Timezone Types](#datetime-and-timezone-types)
• [Basic DateTime](#basic-datetime)
• [Timezone-Aware Types](#timezone-aware-types)
• [Range Types](#range-types)
• [TomClass (Observable Objects)](#tomclass-observable-objects)
• [TomList (Observable Lists)](#tomlist-observable-lists)
• [TomMap (Observable Maps)](#tommap-observable-maps)
• [Muting Notifications](#muting-notifications)
• [Error Handling](#error-handling)
• [Class Hierarchy](#class-hierarchy)
• [Best Practices](#best-practices)
• [Dependencies](#dependencies)

Overview

The observable system consists of two main components:

1. **`tom_observable.dart`**: Base classes for the Observer pattern (`TomObservable`, `TomObserver`, `TomFunctionObserver`)

2. **`tom_observable_objects.dart`**: Observable wrapper types including primitives (`TomString`, `TomInt`, etc.), collections (`TomList`, `TomMap`), and complex objects (`TomClass`)

Why Use Observables?

• **Reactive Data Binding**: UI components can automatically update when data changes
• **Change Propagation**: Nested objects propagate changes to parent containers
• **Batch Updates**: Mute notifications during bulk changes for better performance
• **Memory Safe**: Uses `WeakReference` to prevent memory leaks from observers
• **JSON Integration**: Seamless serialization/deserialization with the reflection system

Quick Start

1. Basic Observable Value

import 'package:tom_core/tom_core.dart';

// Create an observable string
final name = TomString("John");

// Subscribe to changes using >> operator
name >> (obs) => print("Name changed to: ${~name}");

// Set value using | operator - triggers notification
name | "Jane";  // Prints: "Name changed to: Jane"

// Get value using ~ operator
print(~name);  // Prints: "Jane"

2. Observable Class

@tomReflector
class Person extends TomClass {
  TomString name = TomString("");
  TomInt age = TomInt(0);
  TomBool isActive = TomBool(true);
}

void main() {
  final person = Person();
  
  // Subscribe to any changes in the Person
  person >> (obs) => print("Person changed!");
  
  // Set values - triggers notification
  person.name | "Alice";  // Prints: "Person changed!"
  person.age | 25;        // Prints: "Person changed!"
  
  // Get values
  print("Name: ${~person.name}");  // Prints: "Name: Alice"
  print("Age: ${~person.age}");    // Prints: "Age: 25"
}

3. Observable Collections

// Observable list
final names = TomList<TomString>();
names >> (obs) => print("List changed!");

names.add(TomString("Alice"));  // Prints: "List changed!"
names.add(TomString("Bob"));    // Prints: "List changed!"

// Changes to elements also notify the list
names[0] | "Alicia";  // Prints: "List changed!"

// Observable map
final scores = TomMap<String, TomInt>();
scores >> (obs) => print("Scores changed!");

scores["alice"] = TomInt(100);  // Prints: "Scores changed!"
scores["alice"]! | 95;          // Prints: "Scores changed!"

Core Components

TomObservable

The foundation of the observer pattern. Any class that needs to notify others of changes should extend `TomObservable`.

class Counter extends TomObservable {
  int _count = 0;
  
  int get count => _count;
  
  void increment() {
    _count++;
    notifyObservers();  // Notify all registered observers
  }
  
  void reset() {
    _count = 0;
    notifyObservers("reset");  // Optional message
  }
}

Properties

Methods

Memory Management

`TomObservable` uses `WeakReference` for storing observers. This means: - Observers that are garbage-collected are automatically cleaned up - No need to manually remove observers in most cases - Prevents memory leaks in long-running applications

void setupObserver() {
  final counter = Counter();
  
  // This observer will be cleaned up when it goes out of scope
  final observer = CounterObserver();
  counter.addObserver(observer);
}
// When observer is garbage collected, counter automatically removes it

TomObserver

An abstract interface for objects that want to observe changes in a `TomObservable`.

class CounterDisplay implements TomObserver<Counter> {
  int _lastSeenValue = 0;
  
  @override
  void onNotify(Counter observable) {
    _lastSeenValue = observable.count;
    print('Counter is now: $_lastSeenValue');
  }
}

void main() {
  final counter = Counter();
  final display = CounterDisplay();
  
  counter.addObserver(display);
  
  counter.increment();  // Prints: "Counter is now: 1"
  counter.increment();  // Prints: "Counter is now: 2"
}

Type Parameter

The type parameter `T extends TomObservable` specifies what type of observable this observer can observe. This provides type safety:

// This observer can only observe Counter objects
class CounterObserver implements TomObserver<Counter> {
  @override
  void onNotify(Counter observable) {
    print('Counter: ${observable.count}');
  }
}

// This observer can observe any TomObservable
class GenericObserver implements TomObserver<TomObservable> {
  @override
  void onNotify(TomObservable observable) {
    print('Something changed!');
  }
}

TomFunctionObserver

A wrapper that allows using a callback function as a `TomObserver`. This is what enables the `>>` operator syntax.

// These are equivalent:
counter >> (obs) => print('Changed!');

// Manually creating a TomFunctionObserver:
final observer = TomFunctionObserver<Counter>((obs) => print('Changed!'));
counter.addObserver(observer);

Keeping References

The `>>` operator returns the `TomFunctionObserver` so you can keep a reference and later remove it:

final counter = Counter();

// Keep the reference
final observer = counter >> (obs) => print('Changed!');

// Later, remove the observer
counter.removeObserver(observer);

Operators

The observable system uses custom operators for a clean, expressive API:

Operator Examples

final name = TomString("Hello");

// Get value - three equivalent ways
String value1 = ~name;          // Using ~ operator
String value2 = name();         // Using () operator  
String value3 = name.get();     // Using get() method

// Set value
name | "World";                 // Sets value and notifies observers
name.set("World");              // Equivalent using method

// Subscribe to changes
name >> (obs) => print("Changed to: ${~name}");

// Combined example
final counter = TomInt(0);
counter >> (obs) => print("Counter: ${~counter}");
counter | (~counter + 1);  // Increment: Prints "Counter: 1"
counter | (~counter + 1);  // Increment: Prints "Counter: 2"

Observable Primitives

TomObject&lt;T&gt; (Base Class)

All observable types extend `TomObject<T>`, which provides:

abstract class TomObject<T> extends TomObservable {
  T _value;
  
  // Core methods
  T get();                    // Get current value
  T call();                   // Get current value (call operator)
  T set(T value);             // Set value and notify
  T? getOrNull();             // Get value or null
  bool get isNull;            // Check if value is null
  
  // Operators
  T operator ~();             // Get value (prefix)
  T operator |(T value);      // Set value
  TomFunctionObserver<...> operator >>(Function callback);  // Subscribe
}

Non-Nullable Types

// Creating observable primitives
final name = TomString("John");
final age = TomInt(30);
final salary = TomDouble(50000.0);
final isActive = TomBool(true);
final createdAt = TomDateTime(DateTime.now());

// Using them
print(~name);              // "John"
print(~age);               // 30
print(~salary);            // 50000.0
print(~isActive);          // true
print(~createdAt);         // 2024-01-15 10:30:00.000

// Modifying
name | "Jane";
age | 31;
salary | 55000.0;
isActive | false;
createdAt | DateTime(2025, 1, 1);

Nullable Types

// Nullable types can hold null values
final middleName = TomNString(null);
final score = TomNInt(null);

// Check for null
if (middleName.isNull) {
  print("No middle name");
}

// Safe access
String? name = middleName.getOrNull();
int? scoreValue = score.getOrNull();

// Set to a value or back to null
middleName | "Robert";
middleName | null;  // Back to null

DateTime and Timezone Types

Basic DateTime

`TomDateTime` and `TomNDateTime` wrap standard Dart `DateTime` objects:

final timestamp = TomDateTime(DateTime.now());
final nullableDate = TomNDateTime(null);

// Serialize to string (ISO 8601 format)
String serialized = (~timestamp).toIso8601String();

// The serialization prefix is @!@
print(TomDateTime.serializationPrefix);  // "@!@"

Timezone-Aware Types

For applications requiring timezone support, use the `TomZoned*` types:

// Create timezone-aware observable
final meetingTime = TomOZonedDateTime(TomZonedDateTime(
  year: 2024,
  month: 6,
  day: 15,
  hour: 14,
  minute: 30,
  timezone: TomTimezone.fromName('America/New_York'),
));

// Subscribe to changes
meetingTime >> (obs) => print("Meeting time changed!");

// Get the value
TomZonedDateTime time = ~meetingTime;
print(time.timezone.name);  // "America/New_York"
print(time.hour);           // 14

Nullable Timezone Types

final deadline = TomNOZonedDateTime(null);

// Check if set
if (deadline.isNull) {
  print("No deadline set");
}

// Set a value
deadline | TomZonedDateTime(
  year: 2024, month: 12, day: 31,
  hour: 23, minute: 59,
  timezone: TomTimezone.utc,
);

// Set from serialized string
deadline.setByString("@X@2024-12-31T23:59:00.000Z_Z_UTC ");

Range Types

For representing date/time ranges, use the range types which extend `TomClass`:

@tomReflector
class Event extends TomClass {
  TomString name = TomString("");
  TomDateTimeRange duration = TomDateTimeRange();
}

final event = Event();
event.name | "Conference";

// Set range values
event.duration.startDateTime | TomZonedDateTime(
  year: 2024, month: 6, day: 15, hour: 9, minute: 0,
  timezone: TomTimezone.utc,
);
event.duration.endDateTime | TomZonedDateTime(
  year: 2024, month: 6, day: 17, hour: 17, minute: 0,
  timezone: TomTimezone.utc,
);

// Subscribe to event changes (includes range changes)
event >> (obs) => print("Event modified!");

TomClass (Observable Objects)

`TomClass` is a powerful base class for creating observable domain objects with automatic member observation and JSON serialization.

Basic Usage

@tomReflector
class Person extends TomClass {
  TomString name = TomString("");
  TomInt age = TomInt(0);
  TomNString email = TomNString(null);
  TomBool isActive = TomBool(true);
}

void main() {
  final person = Person();
  
  // Observe any change to the person
  int notifyCount = 0;
  person >> (obs) => notifyCount++;
  
  // Set individual fields
  person.name | "Alice";
  person.age | 30;
  person.email | "alice@example.com";
  
  print(notifyCount);  // 3 - one notification per change
  
  // Get all values as a map
  Map<String, dynamic> values = person.getValues();
  print(values);  // {name: Alice, age: 30, email: alice@example.com, isActive: true}
}

Automatic Member Registration

When a `TomClass` is instantiated, it uses reflection to: 1. Discover all `TomObject` fields 2. Register itself as an observer on each field 3. Propagate changes from any field to observers of the `TomClass`

@tomReflector
class Address extends TomClass {
  TomString street = TomString("");
  TomString city = TomString("");
  TomString zipCode = TomString("");
}

@tomReflector
class Customer extends TomClass {
  TomString name = TomString("");
  Address address = Address();  // Nested TomClass
}

void main() {
  final customer = Customer();
  
  // Observe customer - gets notified for nested changes too!
  customer >> (obs) => print("Customer changed!");
  
  customer.name | "Acme Corp";        // Prints: "Customer changed!"
  customer.address.city | "New York"; // Prints: "Customer changed!"
}

Key Methods

Bulk Updates with setValues

final person = Person();

// Set multiple values at once
person.setValues({
  'name': 'Bob',
  'age': 25,
  'email': 'bob@example.com',
  'isActive': false,
});

print(~person.name);     // "Bob"
print(~person.age);      // 25
print(~person.email);    // "bob@example.com"
print(~person.isActive); // false

JSON Serialization

final person = Person();
person.name | "Charlie";
person.age | 35;

// Serialize to JSON
Map<String, dynamic> jsonMap = person.toJson();
print(jsonMap);  // {name: Charlie, age: 35, email: null, isActive: true}

// Deserialize from JSON
final person2 = Person();
person2.fromJson('{"name": "Diana", "age": 28}');
print(~person2.name);  // "Diana"
print(~person2.age);   // 28

TomList (Observable Lists)

`TomList<E>` is an observable list that notifies observers when: - Elements are added, removed, or replaced - Any contained element changes (if the element is a `TomObject`)

Creating TomList

// Empty list
final names = TomList<TomString>();

// From existing TomList
final names2 = TomList.from(names);
final names3 = TomList.of(names);

// From standard List
final names4 = TomList.ofList([TomString("Alice"), TomString("Bob")]);

List Operations

final items = TomList<TomInt>();

// Add elements
items.add(TomInt(10));
items.addAll([TomInt(20), TomInt(30)]);
items.insert(0, TomInt(5));

// Access elements
print(~items[0]);     // 5
print(items.length);  // 4
print(items.first);   // TomInt(5)
print(items.last);    // TomInt(30)

// Modify elements
items[0] | 100;       // Set via operator
items[0] = TomInt(1); // Replace element

// Remove elements
items.removeAt(0);
items.removeLast();
items.remove(TomInt(20));
items.clear();

// Iteration
for (final item in items) {
  print(~item);
}

// Functional operations
final doubled = items.map((e) => TomInt(~e * 2));
final filtered = items.where((e) => ~e > 10);

Concatenation

final list1 = TomList<TomInt>();
list1.addAll([TomInt(1), TomInt(2)]);

final list2 = TomList<TomInt>();
list2.addAll([TomInt(3), TomInt(4)]);

// Concatenate using + operator
final combined = list1 + list2;  // [1, 2, 3, 4]

Element Change Propagation

@tomReflector
class Task extends TomClass {
  TomString title = TomString("");
  TomBool completed = TomBool(false);
}

final tasks = TomList<Task>();
int listNotifications = 0;
tasks >> (obs) => listNotifications++;

// Add a task
tasks.add(Task()..title | "Buy groceries");
print(listNotifications);  // 1

// Modify the task's title - list is notified!
tasks[0].title | "Buy organic groceries";
print(listNotifications);  // 2

// Mark as completed - list is notified again!
tasks[0].completed | true;
print(listNotifications);  // 3

TomMap (Observable Maps)

`TomMap<K, V>` is an observable map that notifies observers when: - Entries are added, removed, or replaced - Any contained value changes (if the value is a `TomObject`)

Creating TomMap

// Empty map
final scores = TomMap<String, TomInt>();

// From existing TomMap
final scores2 = TomMap.from(scores);
final scores3 = TomMap.of(scores);

// From standard Map
final scores4 = TomMap.ofMap({
  'alice': TomInt(100),
  'bob': TomInt(85),
});

Map Operations

final config = TomMap<String, TomString>();

// Add entries
config['host'] = TomString('localhost');
config['port'] = TomString('8080');
config.addAll({
  'protocol': TomString('https'),
  'path': TomString('/api'),
});

// Access entries
print(~config['host']!);     // "localhost"
print(config.length);         // 4
print(config.keys);           // (host, port, protocol, path)
print(config.containsKey('host'));  // true

// Modify values
config['host']! | 'example.com';

// Remove entries
config.remove('path');
config.removeWhere((k, v) => ~v == 'https');
config.clear();

// Iteration
config.forEach((key, value) {
  print('$key: ${~value}');
});

Merging Maps

final map1 = TomMap<String, TomInt>();
map1['a'] = TomInt(1);
map1['b'] = TomInt(2);

final map2 = TomMap<String, TomInt>();
map2['c'] = TomInt(3);
map2['d'] = TomInt(4);

// Merge using + operator
final merged = map1 + map2;  // {a: 1, b: 2, c: 3, d: 4}

Value Change Propagation

@tomReflector
class User extends TomClass {
  TomString name = TomString("");
  TomInt score = TomInt(0);
}

final users = TomMap<String, User>();
int mapNotifications = 0;
users >> (obs) => mapNotifications++;

// Add a user
users['alice'] = User()..name | "Alice";
print(mapNotifications);  // 1

// Modify the user's score - map is notified!
users['alice']!.score | 100;
print(mapNotifications);  // 2

Restriction: Cannot Replace Entire Map

Unlike regular maps, you cannot replace the entire contents at once using `set()`:

final map = TomMap<String, TomInt>();

// This throws TomObservableException
// map.set({'a': TomInt(1)});  // ✗ Not allowed

// Instead, clear and add new entries
map.clear();
map.addAll({'a': TomInt(1)});  // ✓ OK

Muting Notifications

When making multiple changes, you may want to suppress notifications until all changes are complete. This is called "muting".

Basic Muting

final person = Person();
int notifications = 0;
person >> (obs) => notifications++;

// Without muting: 3 notifications
person.name | "Alice";
person.age | 30;
person.email | "alice@example.com";
print(notifications);  // 3

// With muting: 1 notification
notifications = 0;
person.mute();
person.name | "Bob";
person.age | 25;
person.email | "bob@example.com";
person.unmute();  // Triggers single notification
print(notifications);  // 1

How Muting Works

1. `mute()` sets an internal flag and records the object as "dirty" when changes occur 2. While muted, `notifyObservers()` does not send notifications 3. `unmute()` checks if the object became dirty during muting 4. If dirty, a single notification is sent

Nested Muting

For `TomClass`, `TomList`, and `TomMap`, muting propagates to children:

@tomReflector
class Order extends TomClass {
  TomString orderId = TomString("");
  TomList<OrderItem> items = TomList();
  TomDouble total = TomDouble(0.0);
}

final order = Order();
int notifications = 0;
order >> (obs) => notifications++;

order.mute();

// All these changes are batched
order.orderId | "ORD-001";
order.items.add(OrderItem()..name | "Widget");
order.items.add(OrderItem()..name | "Gadget");
order.total | 99.99;

order.unmute();  // Single notification for all changes
print(notifications);  // 1

Try-Finally Pattern

Always use try-finally to ensure unmute is called:

void performBatchUpdate(Person person) {
  person.mute();
  try {
    person.name | "Updated Name";
    person.age | 30;
    // ... more updates
  } finally {
    person.unmute();  // Always called, even if exception occurs
  }
}

Error Handling

The system throws `TomObservableException` for observable-related errors:

try {
  final map = TomMap<String, TomInt>();
  map.set({'key': TomInt(1)});  // Not allowed
} on TomObservableException catch (e) {
  print('Error key: ${e.key}');
  print('Message: ${e.defaultUserMessage}');
}

Common Error Keys

Class Hierarchy

TomObserver<T> (interface)
├── TomFunctionObserver<T>  — Wraps callback functions as observers
├── TomClass                — Observes its own members
├── TomList<E>              — Observes its elements
└── TomMap<K, V>            — Observes its values

TomObservable (base class)
└── TomObject<T>
    ├── TomString, TomInt, TomDouble, TomBool, TomDateTime
    ├── TomNString, TomNInt, TomNDouble, TomNBool, TomNDateTime
    ├── TomOTimezoned<TZ>
    │   ├── TomOZonedTime, TomOZonedDate, TomOZonedDateTime
    │   └── TomNOTimezoned<TZ>
    │       └── TomNOZonedTime, TomNOZonedDate, TomNOZonedDateTime
    ├── TomClass (also implements TomObserver)
    │   ├── TomDateRange, TomTimeRange, TomDateTimeRange
    │   └── (user-defined domain objects)
    ├── TomList<E> (also implements TomObserver, List<E>)
    └── TomMap<K, V> (also implements TomObserver, Map<K, V>)

Best Practices

1. Use Operators for Clean Code

Prefer operators over method calls for readability:

// ✓ Clean and idiomatic
name | "John";
String value = ~name;
name >> (obs) => print("Changed!");

// ✗ More verbose (but equivalent)
name.set("John");
String value = name.get();
name.addObserver(TomFunctionObserver((obs) => print("Changed!")));

2. Mute During Batch Updates

Always mute when making multiple changes:

void updatePerson(Person person, Map<String, dynamic> data) {
  person.mute();
  try {
    if (data['name'] != null) person.name | data['name'];
    if (data['age'] != null) person.age | data['age'];
    if (data['email'] != null) person.email | data['email'];
  } finally {
    person.unmute();
  }
}

3. Initialize Fields with Default Values

Always provide default values for `TomClass` fields:

@tomReflector
class Person extends TomClass {
  TomString name = TomString("");          // ✓ Good
  TomInt age = TomInt(0);                  // ✓ Good
  TomNString email = TomNString(null);     // ✓ Good for nullable
  TomList<Task> tasks = TomList();         // ✓ Good for collections
}

4. Use Typed TomList and TomMap

Always specify type parameters for type safety:

// ✓ Good - type safe
TomList<TomString> names = TomList<TomString>();
TomMap<String, TomInt> scores = TomMap<String, TomInt>();

// ✗ Avoid dynamic types
TomList<dynamic> items = TomList<dynamic>();

5. Keep Observer References if Needed Later

If you need to remove an observer later, keep the reference:

class MyWidget {
  late TomFunctionObserver<TomObservable> _observer;
  final Person _person;
  
  MyWidget(this._person) {
    _observer = _person >> (obs) => _onPersonChanged();
  }
  
  void dispose() {
    _person.removeObserver(_observer);
  }
  
  void _onPersonChanged() {
    // Handle change
  }
}

6. Annotate Classes with @tomReflector

All `TomClass` subclasses must be annotated for reflection to work:

@tomReflector  // ✓ Required
class Customer extends TomClass {
  TomString name = TomString("");
  Address address = Address();  // Address must also be annotated!
}

@tomReflector  // ✓ Required for nested class
class Address extends TomClass {
  TomString city = TomString("");
}

Dependencies

The observable system depends on:

• **Reflection Module**: `@tomReflector` annotation for `TomClass` reflection
• **Timezoned Module**: `TomTimezoned`, `TomZonedDate`, `TomZonedTime`, `TomZonedDateTime`
• **Little Things Module**: Base `TomException` class for `TomObservableException`

observable_short_reference.md

This document describes the **Observer/Observable architecture** of the Tom framework, which implements the Observer pattern to enable reactive data binding. The architecture consists of two main files:

• `tom_observable.dart` — Base classes for the Observer pattern
• `tom_observable_objects.dart` — Observable wrapper types for values

---

Base Classes (`tom_observable.dart`)

`TomObservable`

The foundation of the observer pattern. Any class that needs to notify others of changes should extend `TomObservable`.

**Key Features:** - Maintains a list of observers using `WeakReference` to prevent memory leaks - Supports muting/unmuting notifications for batch updates - Automatically cleans up garbage-collected observers

**Properties:** - `isMuted` — Returns `true` if notifications are currently muted

**Methods:** | Method | Description | |--------|-------------| | `addObserver(TomObserver)` | Registers an observer to receive notifications | | `removeObserver(TomObserver)` | Unregisters an observer | | `notifyObservers([message])` | Notifies all registered observers of a change | | `mute()` | Temporarily suppresses notifications | | `unmute()` | Resumes notifications (triggers if dirty) |

**Operators:** | Operator | Description | |----------|-------------| | `observable >> callback` | Adds a callback function as an observer (returns `TomFunctionObserver`) |

**Example:**

class Counter extends TomObservable {
  int _count = 0;
  
  void increment() {
    _count++;
    notifyObservers();
  }
}

---

`TomObserver<T extends TomObservable>`

An abstract interface for objects that want to observe changes in a `TomObservable`.

**Methods:** | Method | Description | |--------|-------------| | `onNotify(T observable)` | Called when the observed object changes |

**Example:**

class CounterDisplay implements TomObserver<Counter> {
  @override
  void onNotify(Counter counter) {
    print('Counter changed!');
  }
}

final counter = Counter();
final display = CounterDisplay();
counter.addObserver(display);
counter.increment(); // Prints: "Counter changed!"

---

`TomFunctionObserver<T extends TomObservable>`

A wrapper that allows using a callback function as a `TomObserver`. This enables the `>>` operator syntax.

**Example:**

final counter = Counter();
counter >> (obs) => print('Changed!'); // Uses TomFunctionObserver internally

---

Observable Wrapper Types (`tom_observable_objects.dart`)

These types extend `TomObservable` and wrap values, automatically notifying observers when values change.

`TomObservableException`

Custom exception class for observable-related errors, extending `TomException`.

`TomObject<T>` (Base Class)

The generic observable wrapper that all other types extend.

**Key Features:** - **Value storage**: Internal `_value` of type `T` - **Operator overloads**: - `~obj` — get value (prefix operator) - `obj()` — get value (call operator) - `obj | newValue` — set value and notify observers - `obj >> callback` — observe changes (inherited from `TomObservable`) - **Nullable access**: `getOrNull()`, `isNull` property - **Observer integration**: Automatically notifies observers on value changes via `set()`

**Core Methods:** - `T get()` — returns the current value - `T call()` — returns the current value (call operator) - `T set(T value)` — sets the value and notifies observers - `T? getOrNull()` — returns value or null if unset - `bool get isNull` — checks if value is null

---

Primitive Wrappers

---

Nullable Primitive Wrappers

---

Timezone-Aware Date/Time Types

Non-Nullable

**Common Methods:** - `setByString(String s)` — sets the value by parsing a serialized string - `getSerializationPrefix()` — returns the serialization prefix for this type

Nullable

Nullable types deserialize to `null` when the serialized string has only the prefix with no value.

---

Range Types

All range types extend `TomClass` and their members are automatically registered for observation via reflection.

---

`TomClass` (Complex Observable Object)

A powerful base class for creating observable domain objects with automatic member observation and JSON serialization.

**Key Features:**

Automatic Member Registration

• Uses reflection to discover all `TomObject` fields
• Members are automatically registered and observed in the constructor
• `getMembers()` — returns a map of all registered `TomObject` members

Self-Observation

• `startSelfObservation()` — registers this class as observer on all members (called automatically)
• Implements `TomObserver` interface
• Changes to any member notify the parent `TomClass`

Value Operations

• `setValues(Map<String, dynamic>)` — bulk update multiple fields
• `setOrMergeValues(Map<String, dynamic>)` — update or merge with existing values
• `getValues()` — returns all registered members as a `Map<String, dynamic>`

JSON Serialization

• `toJson()` — serializes object to JSON-compatible Map (calls `getValues()`)
• `fromJson(String json)` — deserializes from JSON string
• Uses `@tomReflector` annotation for reflection support

---

`TomList<E extends TomObject>`

An observable list implementation that automatically observes all contained elements.

**Key Features:** - Implements the full `List<E>` interface - Uses `@tomReflector` annotation for reflection - Automatically observes all contained elements - Notifies observers on any list modification

**Constructors:** - `TomList()` — creates empty list - `TomList.from(TomList<E>)` — creates from existing TomList - `TomList.of(TomList<E>)` — creates copy of existing TomList - `TomList.ofList(List<E>)` — creates from standard List

**Observer Management:** - `_attachTo(Iterable<E>)` — adds this list as observer to all elements - `_detachFrom(Iterable<E>)` — removes this list as observer from elements

**All Standard List Operations:** - `add()`, `addAll()`, `insert()`, `insertAll()` - `remove()`, `removeAt()`, `removeLast()`, `removeRange()`, `removeWhere()` - `clear()`, `sort()`, `shuffle()` - `operator []`, `operator []=` - `operator +` — concatenates two TomLists - Iterable methods: `map()`, `where()`, `fold()`, `expand()`, etc.

**Static Methods:** - `TomList.castFrom<S, E>()` — casts list element types

---

`TomMap<K, V extends TomObject>`

An observable map implementation that automatically observes all contained values.

**Key Features:** - Provides full Map interface - Uses `@tomReflector` annotation for reflection - Automatically observes all values (not keys) - Notifies observers on any map modification

**Constructors:** - `TomMap()` — creates empty map - `TomMap.from(TomMap<K, V>)` — creates from existing TomMap - `TomMap.of(TomMap<K, V>)` — creates copy of existing TomMap - `TomMap.ofMap(Map<K, V>)` — creates from standard Map

**Restrictions:** - `set()` throws `TomObservableException` — cannot replace entire map, only individual elements

**Observer Management:** - `_attachTo(Iterable<V>)` — adds this map as observer to all values - `_detachFrom(Iterable<V>)` — removes this map as observer from values

**All Standard Map Operations:** - `operator []`, `operator []=` - `operator +` — merges two TomMaps - `add()`, `addAll()`, `addEntries()` - `remove()`, `removeWhere()`, `clear()` - `update()`, `updateAll()`, `putIfAbsent()` - `containsKey()`, `containsValue()` - `keys`, `values`, `entries`, `length`, `isEmpty`, `isNotEmpty` - `forEach()`, `map()`, `cast()`

**Static Methods:** - `TomMap.castFrom<K, V, K2, V2>()` — casts map key/value types

---

Design Patterns Used

1. **Observer Pattern**: All types extend `TomObservable` and implement `TomObserver` 2. **Decorator Pattern**: Wraps primitive types with observable behavior 3. **Composite Pattern**: `TomClass`, `TomList`, `TomMap` observe their children 4. **Reflection Pattern**: `TomClass` uses reflection to auto-discover and register members

---

Class Hierarchy

TomObserver<T> (interface)
├── TomFunctionObserver<T>  — Wraps callback functions as observers
├── TomClass                — Observes its own members
├── TomList<E>              — Observes its elements
└── TomMap<K, V>            — Observes its values

TomObservable (base class)
└── TomObject<T>
    ├── TomString, TomInt, TomDouble, TomBool, TomDateTime
    ├── TomNString, TomNInt, TomNDouble, TomNBool, TomNDateTime
    ├── TomOTimezoned<TZ>
    │   ├── TomOZonedTime, TomOZonedDate, TomOZonedDateTime
    │   └── TomNOTimezoned<TZ>
    │       └── TomNOZonedTime, TomNOZonedDate, TomNOZonedDateTime
    ├── TomClass (also implements TomObserver)
    │   ├── TomDateRange, TomTimeRange, TomDateTimeRange
    │   └── (user-defined domain objects)
    ├── TomList<E> (also implements TomObserver)
    └── TomMap<K, V> (also implements TomObserver)

---

Usage Example

// Primitive wrapper with observation
final name = TomString("John");
name >> (observable) => print("Name changed!"); // Subscribe to changes
name | "Jane"; // Set value and trigger observer

// Check for null values
final nullable = TomNString(null);
if (nullable.isNull) {
  print("Value is null");
}
String? maybeValue = nullable.getOrNull();

// Complex observable object - members are registered automatically via reflection
@tomReflector
class Person extends TomClass {
  final name = TomString("");
  final age = TomInt(0);
}

// Observable list
final people = TomList<Person>();
people.add(Person());
people >> (observable) => print("List changed!"); // Subscribe to changes

// Observable map
final lookup = TomMap<String, Person>();
lookup["john"] = Person();

---

Dependencies

• `reflection.dart` — `@tomReflector` annotation and reflection utilities
• `date_timestamp.dart` — `TomTimezoned`, `TomZonedDate`, `TomZonedTime`, `TomZonedDateTime`
• `tom_exception.dart` — base exception class

reflection.md

The Tom Reflection System provides runtime reflection capabilities for Dart classes, enabling JSON serialization/deserialization without code generation for each model class. It uses the `reflection` package to achieve this while maintaining type safety.

Table of Contents

• [Overview](#overview)
• [Quick Start](#quick-start)
• [Core Components](#core-components)
• [Annotations](#annotations)
• [Instance Creation](#instance-creation)
• [Deserialization (JSON to Object)](#deserialization-json-to-object)
• [Serialization (Object to JSON)](#serialization-object-to-json)
• [Supported Types](#supported-types)
• [Working with Collections](#working-with-collections)
• [Working with Nested Objects](#working-with-nested-objects)
• [Debug Logging](#debug-logging)
• [Error Handling](#error-handling)
• [Best Practices](#best-practices)
• [Build Configuration](#build-configuration)

Overview

The reflection system consists of three main components:

1. **`TomReflector`**: A configured `Reflection` subclass that provides the capabilities needed for reflection.

2. **`TomReflectionInfo`**: The main class providing reflection operations like instance creation, value setting, and value getting.

3. **`tomReflector` / `tomReflectionInfo`**: Global instances for convenient access.

Why Use Reflection?

• **No per-model code generation**: Unlike `json_serializable`, you don't need to generate

code for each model class. - **Dynamic JSON handling**: Parse JSON into objects without knowing the structure at compile time. - **Observable integration**: Seamlessly works with `TomClass` observable objects.

Quick Start

1. Annotate Your Class

import 'package:tom_core/tom_core.dart';

@tomReflector
class Person {
  String name = '';
  int age = 0;
  String? email;
}

2. Initialize Reflection

In your main entry point, call the generated initialization function:

import 'my_file.reflection.dart';

void main() {
  initializeReflection();
  
  // Now you can use reflection
}

3. Use Reflection

// Create an instance
final person = tomReflectionInfo.createInstance<Person>(DbPersonImpl);

// Or: final person = tomReflectionInfo.createInstance(DbPersonImpl) as Person;

// Set values from JSON
tomReflectionInfo.setValues(person, {
  'name': 'John Doe',
  'age': 30,
  'email': 'john@example.com',
});

// Get values as JSON
final json = tomReflectionInfo.getValues(person);
print(json); // {name: John Doe, age: 30, email: john@example.com}

// Convert to JSON string
final jsonString = tomReflectionInfo.convertToJsonString(person);
print(jsonString); // {"name":"John Doe","age":30,"email":"john@example.com"}

Core Components

TomReflector

The `TomReflector` class extends `Reflection` and is configured with the necessary capabilities for reflection operations:

class TomReflector extends Reflection {
  const TomReflector()
    : super.fromList(const [
        invokingCapability,          // Call methods and constructors
        typingCapability,            // Access type information
        typeRelationsCapability,     // Navigate class hierarchies
        reflectedTypeCapability,     // Get actual Dart Type objects
        typeAnnotationDeepQuantifyCapability,
        typeAnnotationQuantifyCapability,
        metadataCapability,          // Access annotations
        superclassQuantifyCapability, // Access superclass information
      ]);
}

TomReflectionInfo

The main class for reflection operations. Key methods:

Global Instances

Two global instances are provided for convenience:

/// The reflector annotation - use this to annotate classes
const TomReflector tomReflector = TomReflector();

/// The reflection operations instance
TomReflectionInfo tomReflectionInfo = TomReflectionInfo(tomReflector);

Annotations

@tomReflector

Use this annotation on any class that needs reflection support:

@tomReflector
class MyModel {
  String field1 = '';
  int field2 = 0;
}

**Important**: Only classes annotated with `@tomReflector` will be available for reflection at runtime.

Instance Creation

Create Empty Instance

// Using type parameter
final person = tomReflectionInfo.createInstance<Person>();

// Using Type object
final person = tomReflectionInfo.createInstance(Person);

Create from JSON

// Get the class mirror first
final mirror = tomReflector.reflectType(Person) as ClassMirror;

// Create from Map
final person = tomReflectionInfo.createInstanceFromJson<Person>(
  mirror,
  {'name': 'John', 'age': 30},
);

// Create from JSON string
final person = tomReflectionInfo.createInstanceFromJsonString<Person>(
  mirror,
  '{"name": "John", "age": 30}',
);

Deserialization (JSON to Object)

Basic Usage

final person = Person();
tomReflectionInfo.setValues(person, {
  'name': 'Alice',
  'age': 25,
});

From JSON String

final person = Person();
tomReflectionInfo.convertFromJsonString(person, '{"name": "Alice", "age": 25}');

TomClass Integration

If your class extends `TomClass`, `setValues` automatically delegates to `TomClass.setValues()` for proper observable handling:

@tomReflector
class Person extends TomClass {
  TomString name = TomString('');
  TomInt age = TomInt(0);
}

final person = Person();
tomReflectionInfo.setValues(person, {'name': 'Alice', 'age': 25});
// Observable fields are updated via their setByString methods

Serialization (Object to JSON)

Get Values as Map

final person = Person()
  ..name = 'John'
  ..age = 30;

final values = tomReflectionInfo.getValues(person);
// {name: 'John', age: 30}

Get Values as JSON String

final jsonString = tomReflectionInfo.convertToJsonString(person);
// '{"name":"John","age":30}'

Custom Serialization

If your class has a `jsonEncode` getter, it will be used instead of reflection:

@tomReflector
class CustomPerson {
  String name = '';
  int age = 0;
  
  Map<String, Object?> get jsonEncode => {
    'fullName': name,  // Custom key name
    'years': age,      // Custom key name
  };
}

Supported Types

Primitive Types

The following types are handled directly:

• `int` / `int?`
• `double` / `double?`
• `bool` / `bool?`
• `String` / `String?`
• `null`

DateTime Types

The following DateTime types are automatically serialized/deserialized:

• `DateTime` - ISO 8601 string format
• `TomZonedDate` - Custom date with timezone
• `TomZonedTime` - Custom time with timezone
• `TomZonedDateTime` - Custom datetime with timezone

Collection Types

**Lists:** - `List<String>`, `List<String?>` - `List<int>`, `List<int?>` - `List<double>`, `List<double?>` - `List<bool>`, `List<bool?>` - `List<DateTime>`, `List<DateTime?>` - `List<TomZonedDate>`, `List<TomZonedTime>`, `List<TomZonedDateTime>` - `List<MyClass>` (where MyClass is annotated)

**Maps:** - `Map<String, dynamic>`, `Map<String, Object?>` - `Map<String, String>`, `Map<String, String?>` - `Map<String, int>`, `Map<String, int?>` - `Map<String, double>`, `Map<String, double?>` - `Map<String, bool>`, `Map<String, bool?>` - `Map<String, DateTime>`, `Map<String, DateTime?>` - `Map<String, MyClass>` (where MyClass is annotated)

Working with Collections

Lists of Objects

@tomReflector
class Order {
  String orderId = '';
  List<OrderItem> items = [];
}

@tomReflector
class OrderItem {
  String productId = '';
  int quantity = 0;
}

// Deserialize
final order = Order();
tomReflectionInfo.setValues(order, {
  'orderId': 'ORD-001',
  'items': [
    {'productId': 'PROD-1', 'quantity': 2},
    {'productId': 'PROD-2', 'quantity': 1},
  ],
});

**Important**: List fields can be nullable but the reflection system populates the existing list (or map) rather than creating a new one, if one exists.

Maps of Objects

@tomReflector
class Catalog {
  Map<String, Product> products = {}; 
}

@tomReflector
class Product {
  String name = '';
  double price = 0.0;
}

// Deserialize
final catalog = Catalog();
tomReflectionInfo.setValues(catalog, {
  'products': {
    'SKU001': {'name': 'Widget', 'price': 9.99},
    'SKU002': {'name': 'Gadget', 'price': 19.99},
  },
});

**Important**: Only Maps with String keys are supported.

Working with Nested Objects

Basic Nesting

@tomReflector
class Customer {
  String name = '';
  Address address = Address();  // Initialize nested object!
}

@tomReflector
class Address {
  String street = '';
  String city = '';
  String zipCode = '';
}

// Deserialize - nested object is populated, not replaced
final customer = Customer();
tomReflectionInfo.setValues(customer, {
  'name': 'John Doe',
  'address': {
    'street': '123 Main St',
    'city': 'New York',
    'zipCode': '10001',
  },
});

Deep Nesting

The system handles arbitrarily deep nesting:

@tomReflector
class Company {
  String name = '';
  List<Department> departments = [];
}

@tomReflector
class Department {
  String name = '';
  List<Employee> employees = [];
}

@tomReflector
class Employee {
  String name = '';
  Address address = Address();
}

Debug Logging

Three debug switches are available for troubleshooting:

// Log type resolution information
TomReflectionInfo.debugSwitchLogReflectionDetailsTypes = true;

// Log class member information
TomReflectionInfo.debugSwitchLogReflectionDetailsMembers = true;

// Log value setting/getting operations
TomReflectionInfo.debugSwitchLogReflectionDetailsValues = true;

Debug Report

For detailed class structure information:

final person = Person();
tomReflectionInfo.reportReflectObject(person);

This prints: - All declarations (fields, methods, constructors) - Instance members with types - Superclass hierarchy

Error Handling

The system throws `TomReflectorException` for reflection errors:

try {
  final instance = tomReflectionInfo.createInstance<UnknownClass>();
} on TomReflectorException catch (e) {
  print('Error key: ${e.key}');
  print('Message: ${e.defaultUserMessage}');
}

Common Error Keys

Best Practices

1. Initialize All Fields

Always initialize fields with default values:

@tomReflector
class Person {
  String name = '';           // ✓ Good
  int age = 0;                // ✓ Good
  List<String> tags = [];     // ✓ Good - empty list
  Address address = Address(); // ✓ Good - initialized nested object
}

2. Use Non-Final Fields

Reflection can only set non-final, non-static, non-private fields:

@tomReflector
class Person {
  String name = '';           // ✓ Can be set via reflection
  final String id = '';       // ✗ Cannot be set (final)
  static String type = '';    // ✗ Cannot be set (static)
  String _internal = '';      // ✗ Cannot be set (private)
}

3. Annotate All Related Classes

All classes in your object graph must be annotated:

@tomReflector  // ✓ Required
class Order {
  Customer customer = Customer();  // Customer must also be annotated!
}

@tomReflector  // ✓ Required
class Customer {
  String name = '';
}

4. Handle Nullable Fields Carefully

For nullable nested objects, check for null in your code:

@tomReflector
class Person {
  String name = '';
  Address? address;  // May be null
}

// In JSON, if address is null or missing, the field remains null

Build Configuration

build.yaml

Configure the reflection builder in your `build.yaml`:

targets:
  $default:
    builders:
      reflection_builder:
        generate_for:
          - lib/**.dart           # All library files
          - test/**_test.dart     # Test files
          - example/**/**.dart    # Example files
        options:
          formatted: true

Running the Builder

Generate reflection code with:

dart run build_runner build

Or for continuous generation during development:

dart run build_runner watch

Generated Files

For each file containing annotated classes, a `.reflection.dart` file is generated:

my_models.dart
my_models.reflection.dart  ← Generated

Import and call `initializeReflection()` from the generated file:

import 'my_models.reflection.dart';

void main() {
  initializeReflection();
  // ...
}

Type Resolution

For working with generic collection types, helper methods are available:

Get List Element Type

List<Person> people = [];
final elementMirror = tomReflectionInfo.singleElementType(people);
// elementMirror is the ClassMirror for Person

Get Map Value Type

Map<String, Person> peopleMap = {};
final valueMirror = tomReflectionInfo.mapValueElementType(peopleMap);
// valueMirror is the ClassMirror for Person

These are useful when dynamically creating instances for collection elements.

---

Dependencies

This module depends on:

• **External**: `reflection` package for runtime reflection capabilities
• **Observable Module**: Integration with `TomClass` observable objects

resources.md

The Resources module provides singleton-based resource management for applications, enabling centralized access to text resources (localized strings, UI labels) and configuration values (settings, feature flags).

Table of Contents

• [Overview](#overview)
• [Quick Start](#quick-start)
• [Core Components](#core-components)
• [Best Practices](#best-practices)
• [Dependencies](#dependencies)

---

Overview

The module consists of two main providers:

Both providers share similar patterns: - **Singleton access** for application-wide resource sharing - **Hierarchical key access** using dot notation (e.g., `'app.settings.theme'`) - **Lazy initialization** with optional loader functions - **Fallback behavior** returning the key when a resource is not found

Quick Start

1. Set Up Text Resources

import 'package:tom_core/src/tombase/resources/tom_resource_provider.dart';

// Option A: Define a loader function (recommended for JSON assets)
TomTextResourceProvider.loader = () => {
  'app': {
    'title': 'My Application',
    'version': '1.0.0',
  },
  'messages': {
    'welcome': 'Welcome to the app!',
    'goodbye': 'See you later!',
  },
};

// Option B: Create from an existing map
final provider = TomTextResourceProvider.from({
  'greeting': 'Hello, World!',
});
TomTextResourceProvider.setAppResourceProvider(provider);

2. Access Text Resources

// Get the singleton instance
final resources = TomTextResourceProvider.getAppResources();

// Retrieve text values
String title = resources.getText('app.title');           // 'My Application'
String welcome = resources.getText('messages.welcome');  // 'Welcome to the app!'

// Check if a resource exists
if (resources.exists('messages.optional')) {
  showMessage(resources.getText('messages.optional'));
}

// Missing resources return the key itself
String missing = resources.getText('unknown.key');       // 'unknown.key'

3. Set Up Configuration

// Define configuration loader
TomConfigResourceProvider.loader = () => {
  'api': {
    'baseUrl': 'https://api.example.com',
    'timeout': 30000,
  },
  'features': {
    'darkMode': true,
    'analytics': false,
    'maxItems': 100,
  },
};

4. Access Configuration

final config = TomConfigResourceProvider.getAppConfig();

// Retrieve typed configuration values
String apiUrl = config.getText('api.baseUrl') as String;   // 'https://api.example.com'
int timeout = config.getText('api.timeout') as int;        // 30000
bool darkMode = config.getText('features.darkMode') as bool; // true

// Check if configuration exists
if (config.exists('features.experimental')) {
  enableExperimentalFeatures();
}

5. Easy client integration

Use a simple extension like this to make text resources and configuration available anywhere

import 'package:tom_core/tom_core.dart';
import '../sample_app_state.dart';

extension TomResourceExtension on Object {
  String Function(String) get t =>
      TomTextResourceProvider.getAppResources().getText;
  bool Function(String) get translationExists =>
      TomTextResourceProvider.getAppResources().exists;
  Object Function(String) get c =>
      TomConfigResourceProvider.getAppConfig().getText;
  bool Function(String) get configExists =>
      TomConfigResourceProvider.getAppConfig().exists;

  //TODO: add method to get configuration as int, double and bool
}

You find this file in the UAM sample application.

Core Components

TomTextResourceProvider

A singleton provider for text-based resources.

Static Members

Constructors

Instance Methods

TomConfigResourceProvider

A singleton provider for configuration values of any type.

Static Members

Constructors

Instance Methods

Usage Examples

Loading Resources from JSON Assets

import 'dart:convert';
import 'package:flutter/services.dart';

Future<void> initializeResources() async {
  // Load text resources from assets
  TomTextResourceProvider.loader = () {
    final jsonString = await rootBundle.loadString('assets/strings.json');
    return jsonDecode(jsonString) as Map<String, dynamic>;
  };
  
  // Load configuration from assets
  TomConfigResourceProvider.loader = () {
    final jsonString = await rootBundle.loadString('assets/config.json');
    return jsonDecode(jsonString) as Map<String, dynamic>;
  };
}

Environment-Specific Configuration

void setupEnvironment(String environment) {
  final configs = {
    'dev': {
      'api': {'baseUrl': 'https://dev.api.example.com', 'debug': true},
    },
    'prod': {
      'api': {'baseUrl': 'https://api.example.com', 'debug': false},
    },
  };
  
  TomConfigResourceProvider.setAppConfigProvider(
    TomConfigResourceProvider.from(configs[environment]!),
  );
}

Localization Support

class LocalizationService {
  void setLocale(String locale) {
    final localizedStrings = loadStringsForLocale(locale);
    TomTextResourceProvider.setAppResourceProvider(
      TomTextResourceProvider.from(localizedStrings),
    );
  }
  
  String translate(String key) {
    return TomTextResourceProvider.getAppResources().getText(key);
  }
}

Feature Flags

class FeatureFlags {
  static bool isEnabled(String feature) {
    final config = TomConfigResourceProvider.getAppConfig();
    if (config.exists('features.$feature')) {
      return config.getText('features.$feature') as bool;
    }
    return false;
  }
}

// Usage
if (FeatureFlags.isEnabled('newCheckout')) {
  showNewCheckoutFlow();
} else {
  showLegacyCheckoutFlow();
}

Best Practices

1. Initialize Early

Set up resource providers during application initialization, before any UI code attempts to access resources:

void main() async {
  WidgetsFlutterBinding.ensureInitialized();
  
  // Initialize resources first
  await initializeResources();
  
  runApp(MyApp());
}

2. Use Hierarchical Keys

Organize resources with meaningful hierarchical keys for better maintainability:

// Good: Organized hierarchy
'screens.home.title'
'screens.home.welcomeMessage'
'errors.network.timeout'
'errors.network.noConnection'

// Avoid: Flat, unclear keys
'homeTitle'
'welcomeMsg'
'timeoutError'

3. Handle Missing Resources Gracefully

The providers return the key when a resource is not found. Use this for debugging but handle missing resources appropriately in production:

String getRequiredText(String key) {
  final resources = TomTextResourceProvider.getAppResources();
  final value = resources.getText(key);
  
  if (value == key) {
    // Log missing resource in development
    assert(() {
      print('Warning: Missing resource key: $key');
      return true;
    }());
  }
  
  return value;
}

4. Type Safety for Configuration

Cast configuration values to their expected types and handle type mismatches:

T getConfig<T>(String key, T defaultValue) {
  final config = TomConfigResourceProvider.getAppConfig();
  
  if (!config.exists(key)) {
    return defaultValue;
  }
  
  final value = config.getText(key);
  if (value is T) {
    return value;
  }
  
  return defaultValue;
}

// Usage
final timeout = getConfig<int>('api.timeout', 5000);
final debugMode = getConfig<bool>('debug.enabled', false);

5. Avoid Reloading in Production

The singleton pattern means resources are loaded once. If you need to update resources at runtime (e.g., for locale changes), explicitly set a new provider:

void updateLocale(String newLocale) {
  final newResources = loadResourcesForLocale(newLocale);
  TomTextResourceProvider.setAppResourceProvider(
    TomTextResourceProvider.from(newResources),
  );
}

Architecture Notes

Singleton Pattern

Both providers use the singleton pattern with lazy initialization. The first call to `getAppResources()` or `getAppConfig()` creates the instance, which is then reused for all subsequent calls.

Hierarchical Access

Resources support dot-notation access (e.g., `'app.settings.theme'`) through the `getObjectFromTree` function from the JSON utilities module. This allows for organized, nested resource structures.

---

Dependencies

This module depends on:

• **JSON Module**: `getObjectFromTree` function for hierarchical key access

runtime.md

The Tom Runtime System provides platform-neutral abstractions and runtime configuration for cross-platform Dart and Flutter applications. It enables code to run seamlessly across web, mobile, and desktop environments while managing environment and platform-specific behavior for dependency injection.

Table of Contents

• [Overview](#overview)
• [Quick Start](#quick-start)
• [Core Components](#core-components)
• [TomPlatformUtils](#tomplatformutils)
• [TomEnvironment](#tomenvironment)
• [TomPlatform](#tomplatform)
• [TomRuntime](#tomruntime)
• [Initialization Sequence](#initialization-sequence)
• [Environment Configuration](#environment-configuration)
• [Platform Configuration](#platform-configuration)
• [Integration with Bean Context](#integration-with-bean-context)
• [Best Practices](#best-practices)
• [See Also](#see-also)

Overview

The runtime module solves the challenge of writing platform-agnostic code by providing:

• **Platform Detection** - Determine the current execution environment
• **Console Output** - Unified logging and output across platforms
• **HTTP Client Factory** - Platform-appropriate HTTP client creation
• **Environment Variables** - Cross-platform configuration management
• **Environment Configuration** - Runtime environments (dev, test, prod) with hierarchy support
• **Platform Configuration** - Target platforms (iOS, Android, Web, etc.) for bean selection

The module consists of two main files:

1. **`platform_neutral.dart`**: Platform abstraction classes (`TomPlatformUtils`, `TomFallbackPlatformUtils`) 2. **`platform_environment_runtime.dart`**: Runtime configuration (`TomEnvironment`, `TomPlatform`, `TomRuntime`)

Quick Start

The runtime system must be initialized in a specific sequence before the bean context can be used. Here's the typical initialization pattern used in production applications:

1. Set Environment Variables

Before any initialization, configure the environment variables that control which environment will be selected:

void main(List<String> args) async {
  // Set environment variables (e.g., from command line, config files, etc.)
  TomPlatformUtils.envVars["env"] = "dev";
  TomPlatformUtils.envVars["useRemoteLogging"] = "false";
  
  // Continue with initialization
  await MyApplication.main(args);
}

2. Define Environments in a Separate File

Create a runtime definition file that defines your environment hierarchy:

// runtime_definition.dart

const environmentProd = TomEnvironment(
  'prod',
  initializer: initializeProd,
); // Root environment

const environmentInt = TomEnvironment(
  'int',
  parent: environmentProd,
  isTest: true,
  initializer: initializeInt,
);

const environmentDev = TomEnvironment(
  'dev',
  parent: environmentProd,
  isDevelopment: true,
  isTest: true,
  initializer: initializeDev,
);

3. Create the initializeRuntime Function

The `initializeRuntime()` function sets up the complete runtime state:

void initializeRuntime() {
  // 1. Register all environments
  TomRuntime.addEnvironment(environmentProd);
  TomRuntime.addEnvironment(environmentInt);
  TomRuntime.addEnvironment(environmentDev);

  // 2. Set root environment (ultimate fallback)
  TomRuntime.setRootEnvironment(environmentProd);

  // 3. Set current environment from envVars (with fallback)
  TomRuntime.setCurrentEnvironment(
    TomPlatformUtils.current.getTomEnvVars()["env"], 
    "prod", // fallback if env var not set
  );

  // 4. Run the environment initializer
  TomRuntime.getCurrentEnvironment().initialize();

  // 5. Initialize platform detection
  TomRuntime.initializePlatform();

  // 6. Log the current state
  tomLog.info(TomRuntime.printReport());
}

4. Application Main Sequence

The complete initialization sequence in your application:

class MyApplication {
  static Future<int> main(List<String> args) async {
    // 1. Set platform utilities (MUST be first)
    TomPlatformUtils.setCurrentPlatform(clientPlatformUtils); // or standalonePlatformUtils
    
    // 2. Initialize reflection (if using reflection)
    initializeReflection();
    
    // 3. Initialize runtime (environments + platform)
    initializeRuntime();
    
    // 4. Initialize bean context (AFTER runtime is ready)
    initializeBeanContext();
    
    // 5. Start application
    runApp(Application());
    return 0;
  }
}

Core Components

TomPlatformUtils

The main abstract class that defines the platform utilities contract. Set this first during application startup.

// Set the platform implementation at application start
TomPlatformUtils.setCurrentPlatform(MyPlatformUtils());

// Access environment variables
TomPlatformUtils.envVars["myKey"] = "myValue";

// Get the current platform implementation
final platform = TomPlatformUtils.current;

TomEnvironment

Environments define runtime configurations for different deployment contexts. They support hierarchy (parent environments) and initialization functions.

// Define environments with a hierarchy
const prodEnv = TomEnvironment('production', initializer: initProd);
const devEnv = TomEnvironment(
  'development', 
  parent: prodEnv,
  isDevelopment: true,
  initializer: initDev,
);

TomPlatform

Platforms represent target runtime environments. They are used for platform-specific bean selection via the `@TomPlatform` annotation.

// Built-in platform constants
platformWeb      // Web browsers
platformMacos    // macOS desktop
platformWindows  // Windows desktop
platformLinux    // Linux desktop
platformAndroid  // Android devices
platformIos      // iOS devices
platformFuchsia  // Fuchsia OS

// Register a platform initializer
platformAndroid.setInitializer((platform, env) {
  // Initialize Android-specific resources
});

TomRuntime

Central manager for runtime state. Manages the global state for environments and platforms.

Initialization Sequence

The initialization sequence is critical for the runtime and bean context to work correctly. Here is the complete order:

┌─────────────────────────────────────────────────────────────────┐
│ 1. Set environment variables (TomPlatformUtils.envVars)         │
│    ↓                                                            │
│ 2. Set platform utilities (TomPlatformUtils.setCurrentPlatform) │
│    ↓                                                            │
│ 3. Initialize reflection (initializeReflection)               │
│    ↓                                                            │
│ 4. Initialize runtime (initializeRuntime)                       │
│    ├─ Add environments (TomRuntime.addEnvironment)              │
│    ├─ Set root environment (TomRuntime.setRootEnvironment)      │
│    ├─ Set current environment (TomRuntime.setCurrentEnvironment)│
│    ├─ Call initializer (getCurrentEnvironment().initialize())   │
│    └─ Initialize platform (TomRuntime.initializePlatform)       │
│    ↓                                                            │
│ 5. Initialize bean context (initializeBeanContext)              │
│    ↓                                                            │
│ 6. Application is ready                                         │
└─────────────────────────────────────────────────────────────────┘

Why This Order Matters

1. **Environment variables first**: The `env` variable determines which environment to select 2. **Platform utilities before runtime**: `TomRuntime.initializePlatform()` uses `TomPlatformUtils.current` to detect the platform 3. **Reflection before runtime**: Environment initializers may use reflection 4. **Runtime before bean context**: The bean context uses `TomRuntime.getCurrentEnvironment()` and `TomRuntime.getCurrentPlatform()` to select beans

Environment Configuration

Environment Hierarchy

Environments can form a hierarchy for configuration inheritance:

const baseEnv = TomEnvironment('base');
const devEnv = TomEnvironment('dev', parent: baseEnv, isDevelopment: true);
const localDevEnv = TomEnvironment('local-dev', parent: devEnv);

// Get hierarchy (root to current)
TomRuntime.setCurrentEnvironment('local-dev');
final hierarchy = TomRuntime.getEnvironmentHierarchy();
// Returns: [baseEnv, devEnv, localDevEnv]

Environment Initializers

Initializers are functions that configure environment-specific settings:

void initializeDev(TomEnvironment env) {
  // Set log levels for development
  tomLog.setLogLevel(TomLogLevel.development);
  
  // Configure log levels per module
  tomLog.addNameLevel("TomBean", TomLogLevel.still);
  tomLog.addNameLevel("TomReflectionInfo", TomLogLevel.still);
  
  // Set remote API endpoints
  TomClientRemoteContext.setCurrent(
    TomClientRemoteContext(Uri.parse("http://localhost:9080/")),
  );
}

void initializeProd(TomEnvironment env) {
  tomLog.setLogLevel(TomLogLevel.production);
  
  TomClientRemoteContext.setCurrent(
    TomClientRemoteContext(Uri.parse("https://api.myapp.com/")),
  );
}

Environment Constants

Platform Configuration

Platform Initialization

Platforms can have initializers that run when the platform is activated:

// Register custom initializer
platformAndroid.setInitializer((platform, env) {
  // Initialize Android-specific resources
});

// This is called by TomRuntime.initializePlatform()

Platform Detection

`TomRuntime.initializePlatform()` automatically detects the current platform using `TomPlatformUtils`:

// After initializePlatform() is called:
final platform = TomRuntime.getCurrentPlatform();
print('Running on: ${platform?.name}'); // e.g., "macos", "android", "web"

Integration with Bean Context

The runtime system is designed to work with the bean context for dependency injection. When `initializeBeanContext()` is called, it uses the current runtime state to select the appropriate bean implementations.

Platform-Specific Beans

@tomReflector
@TomComponent(StorageService)
@platformIos
class IosStorageService implements StorageService { ... }

@tomReflector
@TomComponent(StorageService)
@platformAndroid
class AndroidStorageService implements StorageService { ... }

@tomReflector
@TomComponent(StorageService)
class DefaultStorageService implements StorageService { ... }

Environment-Specific Beans

@tomReflector
@TomComponent(LoggingService)
@TomEnvironment("dev", isDevelopment: true)
class DevLoggingService implements LoggingService { ... }

@tomReflector
@TomComponent(LoggingService)
class ProductionLoggingService implements LoggingService { ... }

Bean Resolution Priority

When `TomBean<T>.get()` is called, beans are selected with this priority:

1. **Exact match**: Both environment AND platform match 2. **Platform match**: Platform matches, no environment constraint 3. **Environment match**: Environment matches, no platform constraint 4. **Default**: No environment or platform constraints

Best Practices

1. Define Environments as Constants

Use `const` for environment definitions to enable compile-time checking:

const environmentProd = TomEnvironment('prod', initializer: initProd);
const environmentDev = TomEnvironment('dev', parent: environmentProd, isDevelopment: true);

2. Use Environment Variables for Environment Selection

Don't hardcode the environment; use environment variables:

// ❌ Avoid
TomRuntime.setCurrentEnvironment("dev");

// ✅ Prefer
TomRuntime.setCurrentEnvironment(
  TomPlatformUtils.current.getTomEnvVars()["env"],
  "prod", // fallback
);

3. Create a Centralized initializeRuntime Function

Keep all runtime initialization in one place for clarity:

// runtime_definition.dart
void initializeRuntime() {
  TomRuntime.addEnvironment(environmentProd);
  TomRuntime.addEnvironment(environmentDev);
  TomRuntime.setRootEnvironment(environmentProd);
  TomRuntime.setCurrentEnvironment(
    TomPlatformUtils.current.getTomEnvVars()["env"],
    "prod",
  );
  TomRuntime.getCurrentEnvironment().initialize();
  TomRuntime.initializePlatform();
  tomLog.info(TomRuntime.printReport());
}

4. Use Separate Files for Environment Initialization

Keep environment-specific logic in separate files for maintainability:

lib/
├── main_dev.dart           # Sets envVars["env"] = "dev"
├── main_prod.dart          # Sets envVars["env"] = "prod"
├── runtime_definition.dart # Defines environments and initializeRuntime()
└── environment_init.dart   # Contains initializeDev(), initializeProd(), etc.

5. Handle Worker Isolates

When spawning worker isolates, pass the environment and platform:

class MyWorkerContext extends TomWorkerContext {
  MyWorkerContext(
    TomEnvironment tomEnvironment,
    TomPlatform tomPlatform,
    List<String> args,
    String namePrefix,
  ) : super(tomEnvironment, tomPlatform, args, namePrefix);

  @override
  Future<bool> initializeIsolate() async {
    TomPlatformUtils.setCurrentPlatform(myPlatformUtils);
    initializeReflection();
    initializeRuntime();
    // ... continue initialization
    return true;
  }
}

File Structure

runtime/
├── platform_neutral.dart              # Platform abstraction classes
├── platform_environment_runtime.dart  # Environment, Platform, Runtime classes
└── runtime.md                         # This documentation file

---

Dependencies

This module has no internal Tom dependencies. It is a foundational module used by:

• **Bean Locator Module**: For environment and platform-specific bean selection
• **Logging Module**: For platform-aware logging
• **HTTP Connection Module**: For platform-specific HTTP client creation

security.md

The security module provides a comprehensive authentication and authorization system for the Tom framework. It supports multiple authorization paradigms and integrates seamlessly with JWT-based bearer token authentication.

Table of Contents

• [Overview](#overview)
• [Quick Start](#quick-start)
• [Core Components](#core-components)
• [Authentication](#authentication)
• [Authorization](#authorization)
• [Access Control](#access-control)
• [Usage Examples](#usage-examples)
• [Best Practices](#best-practices)

---

Overview

The security module consists of four main files:

Key Concepts

• **User**: Basic identity information (name, email, etc.)
• **Principal**: Authenticated session with full context
• **ACI (Access Control Information)**: Roles, groups, entitlements, resource keys
• **CLI (Client Limits Information)**: Quotas and feature flags

---

Quick Start

1. Set Up Authentication

import 'package:tom_core/security.dart';

// Create authentication request
var message = TomAuthenticationMessage()
  ..userName = 'john.doe'
  ..password = 'secret'
  ..application = 'myapp';

// Send to server and get result
var result = await authService.authenticate(message);

// Store tokens on success
if (result.error.isEmpty) {
  TomBearerAuthentication.setTokens(
    result.authenticationToken,
    result.authorizationToken,
  );
}

2. Access Current User

// Get the authenticated principal
var principal = TomBearerAuthentication.getPrincipal();

// Access user info
print('Hello, ${principal.user.firstname}!');
print('Roles: ${principal.aci.roles}');

3. Protect Resources

// Using access control annotations
@TomRoleAccess(['admin'])
void adminOnly() {
  // Only admins can access this
}

// Using resource key protection
var email = tomProtect(user.email, '[hidden]', 'user.email');

---

Core Components

Authentication

TomAuthenticationMessage

The request DTO sent from client to server for authentication:

var message = TomAuthenticationMessage()
  ..userName = 'admin'
  ..password = 'P@ssw0rd!'
  ..application = 'web-portal'
  ..clientLanguage = 'en'
  ..clientCountry = 'US';

TomAuthenticationResult

The response DTO from the server:

if (result.error.isNotEmpty) {
  // Authentication failed
  showError(result.error);
} else if (result.requires2FA) {
  // Need two-factor authentication
  show2FADialog(result.twoFactorType);
} else {
  // Success - tokens are ready
  useTokens(result.authenticationToken, result.authorizationToken);
}

Authorization