mono/packages/kbot/docs/cpp-todos.md

KBot C++ Port Plan (WIP Scaffolding)

This document outlines the scaffolding steps to port the TypeScript kbot implementation (both AI tools and the project runner) over to the C++ polymech-cli application.

1. CLI Scaffolding (main.cpp & cmd_kbot)

The C++ port will introduce a new kbot subcommand tree loosely mimicking the existing TypeScript entry points (zod_schema.ts).

• Target Files:
  • src/main.cpp (Register the command)
  • src/cmd_kbot.h (Declarations & Options Structs)
  • src/cmd_kbot.cpp (Implementation)

Subcommand ai

This command replaces the standard OptionsSchema from zod_schema.ts.

• Using CLI::App* ai_cmd = kbot_cmd->add_subcommand("ai", "Run KBot AI workflows");
• Arguments to Map via CLI11:
  • --path (default .)
  • --prompt (string)
  • --output (string)
  • --dst (string)
  • --append (enum: concat, merge, replace)
  • --wrap (enum: meta, none)
  • --each (Glob pattern / list / JSON)
  • --disable, --disableTools, --tools
  • --include, --exclude, --globExtension
  • --model, --router, --mode (enum: completion, tools, assistant, responses, custom)
  • Flags: --stream, --dry, --alt
  • Advanced: --baseURL, --config, --dump, --preferences, --logs, --env

Subcommand run

This command replaces commons/src/lib/run.ts which spawns debug configurations.

• Using CLI::App* run_cmd = kbot_cmd->add_subcommand("run", "Run a launch.json configuration");
• Arguments to Map:
  • --config (default default)
  • --dry (flag)
  • --list (flag)
  • --projectPath (default process.cwd())
  • --logFilePath (default log-configuration.json)

2. Multithreading & Execution Pattern

Referencing cmd_gridsearch.h, the port will leverage tf::Taskflow and tf::Executor along with moodycamel::ConcurrentQueue for processing parallel tasks (like running a prompt against multiple items via --each).

• Architecture Details:
  1. Config Loading: Read preferences/configs (using tomlplusplus or rapidjson).
  2. Globbing / Resolution: Resolve paths using --include/--exclude/--each.
  3. Task Queueing: For every item resolved by --each, queue a task.
  4. Task Execution (Stubbed): The concurrent thread handles creating the LLM request.
  5. Streaming / Output: Results stream back (or are written to --dst), potentially emitting events over an IPC channel or to stdout depending on daemon mode setups.

3. Testing Setup

We'll replicate the testing approach found in tests/ utilizing Catch2 for BDD/TDD styled tests.

• Target Files:
  • tests/test_cmd_kbot.cpp
  • tests/test_kbot_run.cpp
• Cases to cover:
  • Validation of CLI argument defaults against zod_schema.ts.
  • Behavior of kbot run --list correctly interpreting a mock .vscode/launch.json.
  • Dry run of the --each pipeline ensuring tasks get initialized properly.

Next Steps (Scaffolding Phase)

1. Add cmd_kbot.h/cpp with the CLI schema variables.
2. Hook up the subcommands in main.cpp.
3. Stub the execution functions (run_cmd_kbot_ai and run_cmd_kbot_run) just to print out the parsed JSON representing the state.
4. Add the targets to CMakeLists.txt and verify the build passes.
5. Create initial Catch2 tests just to ensure the flags parse correctly without crashing.