# Infra Review — Theseus

> Generated from `Cargo.toml`, `Cargo.lock`, `install.sh`, `.gitignore`, `README.md`, `docs/context/`.

---

## 1. Dependency Hygiene — B

**Evidence:** `Cargo.toml` lines 20–33 (13 direct deps), `Cargo.lock` (2555 lines total).

| Locked Version | Crate | Notes |
|---|---|---|
| 0.7.9 | axum | Current minor; recent |
| 1.52.3 | tokio | Current |
| 0.31.0 | rusqlite | Current 0.31 line |
| 0.12.28 | reqwest | Current |
| 1.0.228 | serde | Current |
| 0.5.2 | tower-http | 0.6.x available — slightly behind |
| 4.6.1 | clap | Current |

- **Cargo.lock is committed** — transitive deps are pinned.
- **No `cargo-deny`, `cargo-audit`, or `deny.toml`** — no automated vulnerability scanning for known CVEs in the supply chain.
- **No unused dependency bloat** — every dep maps to a documented purpose in `tech-stack.md`.
- `reqwest` pulls in native-tls and hyper ecosystem; acceptable for a CLI tool but worth auditing if binary size matters.

**Recommendations:**
- Add `cargo-deny` config (`deny.toml`) to enforce license policy and reject known-vulnerable crates.
- Run `cargo audit` periodically (or in CI once CI exists).

---

## 2. Build Reproducibility — B

**Evidence:** `Cargo.lock` committed; `install.sh` lines 14–15; no `rust-toolchain.toml`.

- `Cargo.lock` pins exact dependency versions — builds are deterministic given the same toolchain.
- `install.sh` does `cargo build --release` with `set -euo pipefail` — safe and correct.
- **No `rust-toolchain.toml`** — Rust version is unspecified. `README.md` says "Rust 1.75+" but nothing enforces it. An incompatible nightly or newer stable could break the build silently.
- **No Dockerfile** — no containerized reproducible build.
- `rusqlite` with `bundled` feature compiles SQLite from source, eliminating system lib variance. Good.

**Recommendations:**
- Add `rust-toolchain.toml` pinning a specific stable version (e.g., `1.78.0`).
- Consider a `Dockerfile` for air-gapped / CI reproducibility.

---

## 3. CI/CD — F

**Evidence:** `.github/workflows/` does not exist. No CI configuration files found anywhere in the repo.

- **Zero automation.** No lint (`cargo clippy`), no test (`cargo test`, `python3 tests/e2e_test.py`), no audit, no build verification on push or PR.
- E2E tests exist (`tests/e2e_test.py`, `e2e/run_all.sh`) but are manual-only.
- No artifact publishing, no release workflow.

**Recommendations (critical):**
- Add `.github/workflows/ci.yml`: `cargo fmt --check`, `cargo clippy`, `cargo test`, `cargo build --release`.
- Add a release workflow triggered on `v*` tags: build Linux/macOS binaries, publish to crates.io, create GitHub Release with artifacts.
- Cache `~/.cargo/registry`, `~/.cargo/git`, `target/` for build speed.

---

## 4. Environment Config — B+

**Evidence:** `deploy.md` lines 42–61; `src/lib.rs` (config resolution); `.gitignore` lines 2–6.

- **Secrets handling is correct:** CLI flags > env vars (`THESEUS_API_KEY`, `THESEUS_DEEPSEEK_API_KEY`) > config file. No secrets hardcoded.
- `.gitignore` excludes `theseus.toml`, `*.db`, `data/` — sensitive files won't be committed.
- Config resolution order (`./theseus.toml` → `~/.config/theseus/config.toml`) is documented.
- **API key is optional and open by default** — server logs a warning but binds without auth. Acceptable for a local pentest tool, but risky if exposed on a network.
- CORS defaults to `127.0.0.1:3080` only — safe default.

**Recommendations:**
- Consider failing closed (refuse to start without `--api-key`) when binding to `0.0.0.0`.
- Document env vars in README (currently only in `deploy.md`).

---

## 5. Documentation — A-

**Evidence:** `README.md` (428 lines), `docs/context/tech-stack.md`, `docs/context/deploy.md`, `README_CN.md` referenced.

- **README is excellent:** architecture diagram, quick start, full API table, node type reference, workflow examples, use cases, data safety notes.
- Bilingual (English + Chinese via `README_CN.md`).
- `docs/context/` provides deep technical detail: dependency rationale, deployment ops, file layout.
- E2E test instructions documented in `deploy.md`.

**Missing:**
- No `CONTRIBUTING.md` — contributors have no guidance on PRs, code style, or testing expectations.
- No `CHANGELOG.md` — users can't see what changed between versions.
- No inline API docs (no `///` doc comments surfaced via `cargo doc`).

**Recommendations:**
- Add `CONTRIBUTING.md` (code style, `cargo fmt`/`clippy` expectations, how to run E2E tests).
- Add `CHANGELOG.md` (even a simple one per release).

---

## 6. Release Process — C

**Evidence:** `Cargo.toml` version `0.2.1`; published on crates.io; `install.sh` for local install; no changelog, no CI release pipeline.

- **Versioning:** Semver (`0.2.1`) — correct.
- **Distribution:** `cargo install theseus` works (crates.io). `install.sh` for local builds. No pre-built binaries on GitHub Releases.
- **No changelog** — impossible to know what changed between 0.1.x and 0.2.x without reading git log.
- **No release automation** — publishing to crates.io is presumably manual (`cargo publish`).
- **No rollback guidance** — SQLite schema uses `CREATE TABLE IF NOT EXISTS` with no migration system. Downgrading the binary could leave orphaned schema. Documented only as "check `src/db.rs` before upgrading."

**Recommendations:**
- Add a GitHub Actions release workflow: tag → build binaries for linux-x86_64, macOS-x86_64, macOS-aarch64 → attach to GitHub Release → `cargo publish`.
- Start a `CHANGELOG.md`.
- Document a rollback procedure (binary downgrade + DB backup reminder).

---

## Summary

| Criterion | Score | Priority Fix |
|---|---|---|
| Dependency Hygiene | **B** | Add `cargo-deny` / `cargo-audit` |
| Build Reproducibility | **B** | Add `rust-toolchain.toml` |
| CI/CD | **F** | Add GitHub Actions (lint, test, build, release) |
| Environment Config | **B+** | Fail closed on `0.0.0.0` without auth |
| Documentation | **A-** | Add `CONTRIBUTING.md`, `CHANGELOG.md` |
| Release Process | **C** | Automate releases, add changelog |

**Overall: B-** — Solid fundamentals (locked deps, good docs, clean config) but **no CI at all** is the critical gap. Adding a basic GitHub Actions pipeline would lift the overall grade significantly.
