AGENTS.md

# AGENTS.md

## Build System

- **CMake** with **Unix Makefiles** generator on **Linux** (GCC 14.2.0 via `/usr/bin/g++`)
- C++ standard: **C++20**
- Presets defined in `CMakePresets.json`

### Setup (first time)

```bash
git submodule update --init --recursive
```

System dependencies must be installed before building:
- `spdlog` (e.g., `sudo apt install libspdlog-dev` on Debian/Ubuntu)
- `fmt` (e.g., `sudo apt install libfmt-dev` on Debian/Ubuntu)
- `OpenSSL` (e.g., `sudo apt install libssl-dev` on Debian/Ubuntu)

### Build commands

```bash
# Configure
cmake --preset default

# Build
cmake --build --preset debug

# Run the app
./build/src/my_app

# Run the DeepSeek chat CLI
./build/src/deepseek

# Run via custom target (like cargo run)
cmake --build --preset debug --target run
```

### Tests

Tests use the **doctest** framework (submodule at `third_party/doctest/`).

```bash
# Build & run all tests
cmake --build --preset debug
cd build && ctest --output-on-failure
```

Available test targets:
- `test_math_utils` — tests for `math_utils` (via `doctest::doctest_with_main`)
- `test_read_lines` — read-line utilities (via `doctest::doctest_with_main`, includes `learn_unique_ptr.cpp`)
- `test_deepseek_chat` — tests for `deepseek_chat` (via `doctest::doctest_with_main`)

## Code Style

- **4-space indent**, LF line endings, UTF-8, trailing whitespace trimmed — see `.editorconfig`
- **clang-format**: Microsoft-based style with **left pointer alignment** (`int* p`), see `.clang-format`
- `.gitattributes` forces LF line endings for all files

## Dependencies

| Dependency     | Type         | CMake Target                              |
| -------------- | ------------ | ----------------------------------------- |
| cpp-httplib    | submodule    | `cpp_httplib` (INTERFACE, OpenSSL enabled)|
| doctest        | submodule    | `doctest::doctest_with_main` / `doctest`  |
| nlohmann_json  | submodule    | `nlohmann_json::nlohmann_json`            |
| spdlog         | system       | `spdlog::spdlog`                          |
| fmt            | system       | `fmt::fmt` (provided via spdlog or system)|
| OpenSSL        | system       | `OpenSSL::SSL`, `OpenSSL::Crypto`         |

## Architecture

```
learn-cpp/
├── src/
│   ├── CMakeLists.txt          — builds my_app + libraries
│   ├── main.cpp                — entrypoint, uses spdlog + http_utils + math_utils
│   ├── math_utils.h/.cpp       — utility library (e.g. add function)
│   ├── http_utils.h/.cpp       — HTTP utility library (uses cpp-httplib)
│   ├── deepseek_chat.h/.cpp    — DeepSeek chat API client (uses cpp-httplib + nlohmann_json)
│   ├── deepseek.cpp            — standalone DeepSeek chat CLI entrypoint
│   └── learn_unique_ptr.cpp    — shared source compiled into test_read_lines
├── tests/
│   ├── CMakeLists.txt          — test targets using doctest
│   ├── test_math_utils.cpp     — tests for math_utils
│   ├── test_read_lines.cpp     — tests for read-line logic
│   └── test_deepseek_chat.cpp  — tests for deepseek_chat
├── third_party/
│   ├── CMakeLists.txt          — aggregates all submodules, manages dependencies
│   ├── cpp-httplib/            — header-only HTTP library (INTERFACE, with OpenSSL)
│   ├── doctest/                — header-only test framework
│   └── nlohmann_json/          — JSON library (header-only, upstream CMake)
├── CMakeLists.txt              — root build file
└── CMakePresets.json           — GCC 14.2.0 debug preset
```

- Build output goes to `build/` (gitignored)
- `compile_commands.json` is generated at `build/compile_commands.json`

## Custom Targets

| Target | Description |
|--------|-------------|
| `run`  | Builds & runs `my_app` (類似 `cargo run`) |

## Plan Mode

When exiting Plan mode, auto-save the plan to `.opencode/plans/<YYYY-MM-DD>-<short-title>.md`.
Create the `.opencode/plans/` directory if it does not exist. The plan file should contain the
goal, approach, and steps planned, suitable for resuming the task later.

## Git Automation

### One-command commit & push

Invoke via **Chat** — type any of the following:

| Input | Effect |
|-------|--------|
| `git-push` | Auto: stage all → generate Conventional Commit message → commit → push |
| `/git-push` | Same, via explicit prompt invocation |
| `推送到 GitHub` / `git commit` | Natural language triggers also recognized |

### What it does

1. `git add -A` — stages **all** changes (new, modified, deleted)
2. Checks for staged changes — exits cleanly if nothing to commit
3. Reads the full diff and analyzes what changed
4. Generates a **Conventional Commit** message (e.g. `feat:` / `fix:` / `refactor:` / `cleanup:`)
5. `git commit -m "<message>"` + `git push`
6. Reports back with commit hash, message, and branch

### Design decisions

- **No external API**: Commit message is generated by the Copilot Agent itself from the diff — no API key needed
- **No confirmation prompt**: Full workflow runs on a single command — trust the automation
- **No empty commits**: Skips gracefully if there are no changes
- **Conventional Commits**: Structured, standardized messages (`feat:`, `fix:`, `chore:`, etc.)
- **Prompt file**: `.github/prompts/git-push.prompt.md`