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