Imported from wst7/tam (
AGENTS.md). Install upstream withnpx skills add wst7/tam. Copyright stays with the author.
AGENTS.md
Single-crate Rust CLI project. A lightweight terminal-based project/task manager with both CLI and interactive TUI modes.
Build & Run
cargo build
cargo run -- <args> # e.g. cargo run -- project list
cargo run -- -i # interactive TUI mode
Test
Tests are inline inside src/ files (e.g. src/config.rs, src/db.rs). There is no tests/ directory — it is excluded in Cargo.toml.
cargo test
Lint / Format
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:
./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; decides betweeninteractive_mode()andcommand_mode()cli.rs: clap command/flag definitions (subcommands:project,task,config)commands/: CLI command implementations (project.rs,task.rs,config.rs)app.rs: TUI state machine (ratatui + crossterm)ui/: TUI rendering widgetsservices/: business logic layerdb.rs: SQLite connection (rusqlite, bundled feature)sql.rs: raw SQL constants (tables use soft-delete viais_deleted)config.rs: TOML config persisted in~/.tam/tam.config.tomltheme.rs: light/dark theme for TUIlogs.rs:log4rsrolling-file logger
Data & Config
All runtime state lives under ~/.tam/:
| File | Purpose |
|---|---|
~/.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
projectandtasktables useis_deleted BOOLEAN DEFAULT 0plus triggers forupdatedtimestamps. Do notDELETE FROMdirectly. - Chinese UI text: interactive-mode popup/tip messages are in Chinese; keep them consistent.
- Schema changes: edit
src/sql.rs, then ensuredb.rs::init_db()includes any newCREATE ... IF NOT EXISTSstatements. - License: dual MIT OR Apache-2.0.
CI & Distribution
.github/workflows/release.ymlis auto-generated bycargo-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.
