# AGENTS.md
Single-crate Rust CLI project. A lightweight terminal-based project/task manager with both CLI and interactive TUI modes.
## Build & Run
```bash
cargo build
cargo run -- <args> # e.g. cargo run -- project list
cargo run -- -i # interactive TUI mode
```
## Test
Unit tests are **inline** inside `src/` files (e.g. `src/config.rs`, `src/db.rs` migration tests); integration tests live in `tests/cli.rs` (human CLI) and `tests/agent.rs` (JSON/MCP/leases/migration) and inject a temporary `HOME`, so the real `~/.tam` is never touched (`tests/` is only excluded from packaging in `Cargo.toml`).
```bash
cargo test
node --test dsh-plugin/test/*.test.mjs # DSH plugin; requires cargo build
```
## Lint / Format
```bash
cargo fmt --check
cargo clippy
```
`rustfmt.toml` enforces Unix newlines and shorthand init/try syntax.
## Release Workflow
Do not bump versions manually. Use the provided scripts:
```bash
./release.sh # bumps patch, updates CHANGELOG, creates git tag
```
This runs `cargo release patch --no-verify --no-publish --execute`, which triggers the `git-cliff` pre-release hook (`release.toml`) to regenerate `CHANGELOG.md`. Then `cargo-dist` CI builds cross-platform artifacts and publishes to crates.io, npm, Homebrew, and GitHub Releases.
If you need a minor/major bump, edit `release.sh` or run `cargo release minor/major` directly with the same flags.
### Changelog
Generated by `git-cliff` (`cliff.toml`) from conventional commits. Do not hand-edit `CHANGELOG.md` headings — they are overwritten on release.
## Architecture
- `main.rs`: entrypoint; parse first, then dispatch (interactive / command / `mcp`), JSON vs human output
- `cli.rs`: clap command/flag definitions (subcommands: `project`, `task`, `status`, `mcp`, `config`; global `--json/--project/--agent`)
- `agent.rs`: agent contract (JSON envelope, `Ctx`, typed `AgentError`, Task/Event/Project views)
- `mcp.rs`: MCP stdio server (`tam mcp`, JSON-RPC 2.0, 12 tools)
- `commands/`: CLI command implementations (`project.rs`, `task.rs`, `config.rs`, `agent.rs` = shared JSON/MCP operations)
- `app.rs`: TUI state machine (ratatui + crossterm)
- `ui/`: TUI rendering widgets
- `services/`: business logic layer
- `db.rs`: SQLite connection (`rusqlite`, bundled feature), runtime pragmas (WAL/busy_timeout/foreign_keys) and additive schema migrations (`PRAGMA user_version`)
- `sql.rs`: raw SQL constants (tables use soft-delete via `is_deleted`)
- `config.rs`: TOML config persisted in `~/.tam/tam.config.toml`
- `theme.rs`: light/dark theme for TUI
- `logs.rs`: `log4rs` rolling-file logger
- `dsh-plugin/`: installable DSH bundle (`@wst7/dsh-tam`) wrapping the JSON CLI as 14 native tools plus a left-sidebar visual panel; `lib/core.js`/`lib/http.js` are plain-Node testable, `index.js` is the host adapter, `client.js` is a prebuilt browser bundle
## Data & Config
All runtime state lives under `~/.tam/`:
| `~/.tam/tam.config.toml` | Theme, current project, DB/log paths |
| `~/.tam/tam.db3` | SQLite database (projects + tasks) |
| `~/.tam/logs/tam.log` | Rolling logs (10 MB trigger, 5 backups) |
The app auto-creates `~/.tam` on first run. Config is loaded via `once_cell::Lazy`; any load failure causes an immediate `std::process::exit(1)`.
## Key Conventions
- **Soft deletes**: both `project` and `task` tables use `is_deleted BOOLEAN DEFAULT 0` plus triggers for `updated` timestamps. Do not `DELETE FROM` directly.
- **Chinese UI text**: interactive-mode popup/tip messages are in Chinese; keep them consistent.
- **Schema changes**: edit `src/sql.rs`, then ensure `db.rs::init_db()` includes any new `CREATE ... IF NOT EXISTS` statements.
- **License**: dual MIT OR Apache-2.0.
## CI & Distribution
- `.github/workflows/release.yml` is auto-generated by `cargo-dist`. Do not edit manually unless you know the dist schema.
- `.github/workflows/publish-crates.yml`: publishes to crates.io after the dist host job succeeds.
- `dist-workspace.toml`: dist targets include macOS (x86_64, aarch64), Linux (gnu/musl), and Windows (MSVC). Installers: shell, PowerShell, npm, Homebrew, MSI.