131 lines
7.0 KiB
Markdown
131 lines
7.0 KiB
Markdown
# cl-cli — Project-specific development guidelines
|
||
|
||
This document captures project-specific knowledge to help advanced contributors work efficiently on this repository. It focuses on practical, non-obvious details (build, configuration, testing, and development tips) specific to this codebase.
|
||
|
||
## 1. Build and configuration
|
||
|
||
- Rust workspace/binaries
|
||
- Single crate with two binaries defined in `Cargo.toml`:
|
||
- `cl-cli` → `src/main.rs`: the CLI entrypoint.
|
||
- `webext` → `src/webext.rs`: a Native Messaging host used by the browser extension.
|
||
- Library module tree under `src/lib.rs` exposes common code to both binaries.
|
||
- Toolchain: stable Rust; CI uses dtolnay/rust-toolchain@stable.
|
||
- Dependencies and async runtime
|
||
- Async via `tokio` (features: `rt`, `rt-multi-thread`, `macros`). Both binaries use `#[tokio::main]`.
|
||
- HTTP via `reqwest`; serialization via `serde`/`serde_json`; configuration via `toml`.
|
||
- Build
|
||
- Standard build works without extra flags:
|
||
- `cargo build` (debug) or `cargo build --release` (optimized).
|
||
- Individual binaries:
|
||
- `cargo build --bin cl-cli`
|
||
- `cargo build --bin webext`
|
||
- The web extension host (`webext`) is a regular Rust binary; it is not bundled by NPM tooling.
|
||
- Configuration file
|
||
- Expected location by default: `$HOME/.config/cl-cli/config.toml`.
|
||
- The CLI allows overriding the path via `--config <PATH>`; the webext host always reads the default path.
|
||
- Template: `config.toml.dist`. Minimal fields:
|
||
- `[[gitlab]] { token, domain }`
|
||
- `[[gitea]] { token, domain }`
|
||
- `[openproject] { token, base_url }`
|
||
- Example of initial setup (copy the dist and edit):
|
||
```bash
|
||
mkdir -p "$HOME/.config/cl-cli"
|
||
cp config.toml.dist "$HOME/.config/cl-cli/config.toml"
|
||
$EDITOR "$HOME/.config/cl-cli/config.toml"
|
||
```
|
||
- Error surface: parsing and IO errors are surfaced as `GeneralError`; the CLI will print and exit non‑zero, the `webext` host will return an error payload.
|
||
- Local OpenProject for development
|
||
- `docker-compose.yaml` provides a local OpenProject (13.x) at `http://localhost:8080` with persisted volumes under `.docker-data/`.
|
||
|
||
## 2. Testing
|
||
|
||
- Test types present
|
||
- Unit tests live alongside code under `#[cfg(test)]` modules (e.g., `src/gitea/issue.rs`, `src/webext.rs`, `src/planning/utils.rs`).
|
||
- Integration tests can be placed under `tests/`. The crate exposes internal modules via `src/lib.rs` for integration testing.
|
||
- Running tests
|
||
- `cargo test` runs unit and integration tests. CI also runs `cargo test` on every push/PR.
|
||
- Tests are pure and do not require network or external services; avoid adding network‑bound tests.
|
||
- Adding new tests
|
||
- Prefer unit tests near the logic being tested. For integration coverage across modules, place files under `tests/` and use public items from `cl_cli`.
|
||
- Keep tests deterministic: no real HTTP calls; if needed, mock boundaries at the client layer.
|
||
- Example integration test (verified locally during preparation)
|
||
- Minimal example using a pure helper. Create `tests/example_gitea_url.rs`:
|
||
```rust
|
||
use url::Url;
|
||
|
||
#[test]
|
||
fn converts_gitea_issue_html_url_to_api_url() {
|
||
// Pure transformation; no network
|
||
let input = Url::parse("https://gitea.champs-libres.be/champs-libres/test/issues/1").unwrap();
|
||
let out = cl_cli::gitea::issue::issue_html_url_to_api(&input).unwrap();
|
||
assert_eq!(
|
||
out.as_str(),
|
||
"https://gitea.champs-libres.be/api/v1/repos/champs-libres/test/issues/1"
|
||
);
|
||
}
|
||
```
|
||
- Run it with `cargo test`. Remove the file if it was only created as a demo.
|
||
|
||
## 3. CLI usage tips (project‑specific)
|
||
|
||
- `cl-cli planning i2work <gitlab_issue_url> <openproject_project_identifier>` creates an OpenProject work package from a GitLab issue.
|
||
- The OpenProject project identifier is the short slug in URLs, e.g. `chill` in `.../projects/chill/...`.
|
||
- The command uses tokens from the configuration file to authenticate to GitLab and OpenProject.
|
||
- Example:
|
||
```bash
|
||
cl-cli planning i2work \
|
||
https://gitlab.com/Chill-Projet/chill-bundles/-/issues/240 \
|
||
chill
|
||
```
|
||
- `cl-cli test` invokes a debug routine (see `src/debug.rs`) primarily for local diagnostics.
|
||
|
||
## 4. Web extension native host (`webext`)
|
||
|
||
- Purpose: acts as a Native Messaging host for a browser extension under `web-extension/`.
|
||
- Protocol: communicates via stdin/stdout using 4‑byte length‑prefixed JSON messages.
|
||
- Input `serde` enum is tagged with `type`; currently supports `{"type":"Issue2Work", ...}`.
|
||
- Output is tagged with `result` (`Ok` or `Error`) and contains `data` when successful.
|
||
- Business flow: the host reads config from `$HOME/.config/cl-cli/config.toml`, translates the input into `Issue2Work` CLI arguments, delegates to `planning::issue2work::handle_issue2work`, and returns the created work package URL.
|
||
- Testing the transport: see unit tests in `src/webext.rs` that exercise message framing and deserialization.
|
||
|
||
## 5. Code style and architectural notes
|
||
|
||
- Module layout
|
||
- Public library facade (`src/lib.rs`) re‑exports internal modules for reuse by both binaries and tests.
|
||
- Planning features under `src/planning/` with a trait (`Issue2WorkActionTrait`) and concrete actions per platform.
|
||
- Git providers (`src/gitlab`, `src/gitea`) and OpenProject client live in dedicated modules.
|
||
- Error handling
|
||
- Unified lightweight `GeneralError` encapsulates user‑facing messages; conversions from `reqwest::Error` and header errors are provided.
|
||
- Data parsing
|
||
- Input/Output types rely on `serde` with explicit tagging for clarity and forward compatibility.
|
||
- Concurrency
|
||
- All async entrypoints are `#[tokio::main]`; downstream async functions return `impl Future` to stay generic and testable.
|
||
- External calls
|
||
- Wrap external service interactions behind client modules; this eases mocking in tests and keeps pure helpers (like URL mappers) easily testable.
|
||
|
||
## 6. Continuous Integration
|
||
|
||
- `.gitea/workflows/release/check.yaml` performs:
|
||
- Checkout → install stable toolchain → `cargo build` → `cargo test`.
|
||
- Release job (see `.gitea/workflows/release/build-and-release.yaml`) builds release artifacts for distribution.
|
||
|
||
## 7. Troubleshooting / gotchas (project‑specific)
|
||
|
||
- Config path
|
||
- The CLI accepts `--config`, but the webext host reads the default path only. Ensure `$HOME/.config/cl-cli/config.toml` exists when using the browser integration.
|
||
- Tokens scope
|
||
- Ensure personal access tokens for GitLab and OpenProject have sufficient scopes for reading issues and creating work packages respectively.
|
||
- Locale/URLs
|
||
- `Issue2Work` requires the OpenProject project identifier (slug), not its display name.
|
||
- HTTP environment
|
||
- `reqwest` honors proxy vars (`HTTP_PROXY`, `HTTPS_PROXY`) if present; be aware for corporate environments.
|
||
|
||
## 8. Commands quick reference
|
||
|
||
- Build: `cargo build --release`
|
||
- Run CLI: `cargo run --bin cl-cli -- <args>`
|
||
- Run webext host directly for dev: `cargo run --bin webext`
|
||
- Tests: `cargo test`
|
||
- Linting: `cargo clippy` (not enforced in CI but recommended)
|
||
|