tom_dcli_exec #

Analyzer-free D4rt REPL/CLI with full DCli shell-scripting bridges — the extensible base for building D4rt command-line tools.

Overview #

tom_dcli_exec is the DCli-equipped tier of the D4rt interpreter stack. It layers on top of tom_d4rt_exec (the analyzer-free mirror-AST interpreter) and adds:

• A complete set of generated DCli shell-scripting bridges so that D4rt scripts can call dcli, dcli_core, dcli_terminal, path, and related packages directly.
• A production-grade interactive REPL built around an abstract base class (D4rtReplBase) that downstream tools subclass to add their own bridge sets and commands.
• A cli global variable available inside every D4rt script, giving programmatic access to all REPL operations (evaluate, execute files, navigate sessions, introspect bridges, etc.).
• VS Code scripting-API integration via tom_vscode_scripting_api — connect to a running VS Code bridge and evaluate expressions or run scripts from within the REPL.
• Telegram/chat bot mode via tom_chattools — run the REPL as a long-lived Telegram bot server with configurable security, file transfer, conversation trail, and Copilot-chat forwarding.

Relation to tom_d4rt_dcli #

The workspace contains two parallel DCli-capable tools:

tom_dcli_exec is the preferred base for new tools that need fast startup and minimal dependencies. It carries the analyzer package only to drive tom_ast_generator's source-to-mirror-AST conversion; the interpreter itself never loads the analyzer at runtime.

Ecosystem position #

tom_ast_model
    └─ tom_d4rt_ast
           └─ tom_ast_generator      (source → mirror AST)
                  └─ tom_d4rt_exec   (analyzer-free interpreter)
                         └─ tom_dcli_exec   ← THIS PACKAGE
                                └─ tom_dartscript_bridges  (binary: d4rt)
                                └─ tom_build_cli           (binary: tom)

Installation #

Add to your pubspec.yaml:

dependencies:
  tom_dcli_exec: ^1.1.2

Or via the command line:

dart pub add tom_dcli_exec

Executable: dclie #

The package ships a single CLI binary entry-point at bin/dclie.dart named dclie (D4rt CLI Exec). After activating the package globally you can run it directly:

dart pub global activate tom_dcli_exec
dclie                          # start interactive REPL
dclie myscript.dart            # execute a Dart file and exit
dclie myscript.dcli            # execute a DCli replay file and exit
dclie "print('hello');"        # evaluate an expression and exit

Features #

DCli shell-scripting bridges #

All DCli shell functions (ask, confirm, delete, echo, fetch, find, head, menu, read, replace, run, tail, which, and more) are available as D4rt bridges generated from the real DCli source. Bridge coverage also includes:

• dcli_core — file system primitives (cat, copy, move, mkdir, touch, …)
• dcli_terminal — terminal control
• path — path manipulation utilities
• dart_console / console_markdown — formatted console output
• tom_chattools — Telegram chat integration types
• tom_vscode_scripting_api — VS Code bridge client

Bridges are registered with TomD4rtDcliBridge.register(d4rt) and the corresponding import block is injected automatically so D4rt scripts can use import 'package:dcli/dcli.dart'; without further setup.

Interactive REPL #

The REPL (DcliRepl, backed by D4rtReplBase) provides:

• Command history — persistent scrollback saved to ~/.tom/dcli/.history, pre-populated at startup; up to 500 lines retained.
• Named sessions — record all input to *.session.txt files; resume or replace them with -session <id> / -replace-session <id>.
• Multiline modes — .start-define, .start-script, .start-file, .start-execute, closed with .end. Inline shortcuts: exec <code> and exp <expr>.
• Replay files — .dcli and .replay.txt files executed via .load (with output) or .replay (silent). Pass a replay file as a positional argument to run-and-exit.
• Command aliases (defines) — define greet=print("Hello, $1!"); then @greet World. Supports $$ (entire args) and positional $1–$9.
• Directory navigation — cd, cwd, home, ls, sessions, plays, scripts, executes.
• Bridge introspection — classes, enums, methods, variables, imports, registered-* variants, info [query], --dump-configuration.
• Init source — auto-loads dcli_init_source.dart from the data directory at startup; override with -init-source <file> or skip with -no-init-source.
• stdin mode — echo 'return 5+6;' | dclie --stdin — bare expression, auto-wrapped in main(), exit code set to integer result.
• Test mode — -run-replay <file> -test [-output <file>] — executes a replay file and writes a structured test-result JSON for CI integration.
• CTRL-C handling — single press interrupts an in-progress await; double-press within 1 second exits the REPL.
• Console markdown — all output is processed through console_markdown so help text and error messages render with ANSI color tags (<cyan>, <yellow>, <red>, …).

VS Code integration (VSCodeIntegrationMixin) #

DcliRepl mixes in VSCodeIntegrationMixin, exposing these REPL commands:

Connection is lazy — the LazyVSCodeBridgeAdapter defers the TCP connection until the first command that actually needs it.

Telegram bot mode #

Start with --bot-mode [--bot-config <file>]. The TelegramBotServer (from src/bot_mode/) manages multiple simultaneous bot connections and routes each incoming Telegram message through:

1. Security validation (SecurityManager) — allow-list by user ID, command patterns, and path restrictions loaded from YAML config (BotModeConfig).
2. Message classification — explicit Copilot prompt (?-prefix), implicit Copilot prompt (ends with . / ? / --- or starts with TODO: / QUESTION:), or REPL command.
3. REPL execution — the command is processed exactly as if typed interactively.
4. Conversation trail — attachments and references accumulate in ConversationTrail; retrieve them with list-attachments, get-attachments <ids>, etc.
5. Output formatting — OutputFormatter converts ANSI console-markdown to Telegram MarkdownV2 via telegram_markdown.dart.

cli global variable #

Every D4rt script running inside this REPL can access the cli global, an instance of D4rtCliApi (implemented by D4rtCliController):

import 'package:tom_dcli_exec/tom_d4rt_cli_api.dart';

// Navigate
cli.cd('/my/project');
print(cli.cwd());

// Introspect
final all = cli.classes();
for (final c in all) {
  print('${c.name}: ${c.methods.length} methods');
}

// Evaluate
final result = await cli.eval('1 + 2');
print(result); // 3

// Replay a file silently, then check defines
await cli.replay('setup.dcli');
print(cli.defines());

The cli object exposes the full command surface: processPrompt, processPrompts, eval, execute, executeFile, file, script, load, replay, session, reset, multiline helpers (startDefine, startScript, startFile, startExecute, end), define management (define, undefine, defines, loadDefines, invokeDefine, expandDefine), directory operations (cd, cwd, home, ls, sessions, plays, scripts, executes), and introspection (classes, enums, methods, variables, imports, registeredClasses, etc.).

Test utilities #

verify(condition, message) and related helpers in src/api/cli_test_utils.dart are registered as D4rt bridges and available in scripts. Failures accumulate in verificationFailures for batch reporting at the end of a -test run.

Quick start — extending the REPL #

Subclass D4rtReplBase to create a tool with your own bridges:

import 'package:tom_dcli_exec/tom_dcli_exec.dart';

class MyRepl extends D4rtReplBase {
  @override
  String get toolName => 'MyTool';

  @override
  String get toolVersion => '1.0.0';

  @override
  void registerBridges(D4rt d4rt) {
    // Register the DCli bridges from this package
    TomD4rtDcliBridge.register(d4rt);
    // Register your own additional bridges here
  }

  @override
  String getImportBlock() {
    return getStdlibImports() + TomD4rtDcliBridge.getImportBlock();
  }

  @override
  String getBridgesHelp([D4rt? d4rt]) => 'My bridge help...';
}

Future<void> main(List<String> arguments) async {
  await MyRepl().run(arguments);
}

Override additional hooks as needed:

Mix in VSCodeIntegrationMixin to add VS Code commands without re-implementing them (see DcliRepl in lib/tom_dcli_exec.dart for the canonical example).

Architecture #

D4rtReplBase  (lib/src/cli/repl_base.dart)
  │
  ├─ ReplState              console + history + sessions + prompt rendering
  ├─ CliReplIntegration     wires D4rtCliController into the REPL loop
  ├─ PersistentHistory      ~/.tom/<tool>/.history  (dart_console scrollback)
  ├─ VSCodeIntegrationMixin lazy TCP bridge to VS Code (optional mixin)
  └─ BotMode/               TelegramBotServer + SecurityManager + ConversationTrail
         └─ tom_chattools   Telegram API client

D4rtCliController  (lib/src/api/cli_controller.dart)
  │  implements D4rtCliApi
  └─ no Console dependency — usable in scripts, tests, headless contexts

TomD4rtDcliBridge  (lib/dartscript.b.dart)
  │  generated by tom_d4rt_generator at build time
  ├─ DcliBridge              dcli + dcli_core + dcli_terminal bridges
  ├─ PathBridge              path bridges
  ├─ TomChattoolsBridge      tom_chattools bridges
  ├─ TomVscodeScriptingApiBridge  tom_vscode_scripting_api bridges
  └─ CliApiBridge            cli global + D4rtCliApi bridges

The REPL loop in D4rtReplBase.run() is wrapped in a runZonedGuarded zone that pipes all print() output through console_markdown, so ANSI color tags work transparently in every bridge and user script.

CLI reference #

dclie [options] [script.dart | replay.dcli | "expression"]

Positional Arguments
  dclie script.dart           Execute a Dart file and exit
  dclie replay.dcli           Execute replay file and exit
  dclie "expression"          Evaluate a Dart expression and exit

Options
  -h, --help                  Show help
  -v, --version               Show version
  --stdin                     Read and execute source from stdin
  -session <id>               Resume or start a named session
  -replace-session <id>       Delete existing session and start fresh
  -replay <file>              Replay a file before starting REPL
  -run-replay <file>          Execute replay file and exit
  -test                       Run replay in test mode (with -run-replay)
  -output <file>              Write test output to file (with -test)
  -list-sessions              List available sessions
  -init-source <file>         Use custom init source file
  -no-init-source             Do not load init source
  --dump-configuration        Dump registered bridges and configuration
  --debug                     Print init source and debug info
  --bot-mode                  Run as Telegram bot server
  --bot-config <file>         Bot mode configuration YAML file

Status #

Current release: 1.1.2 (first public release — 389 tests, 0 failures, 0 skips).

Source repository: https://github.com/al-the-bear/tom_d4rt/tree/main/tom_dcli_exec

Downstream packages that build on this base:

• tom_dartscript_bridges — adds Tom Framework bridges; compiles the d4rt binary.
• tom_build_cli — adds build tooling bridges; compiles the tom binary.