tam

Imported from wst7/tam (AGENTS.md). Install upstream with npx 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 between interactive_mode() and command_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 widgets
• services/: business logic layer
• db.rs: SQLite connection (rusqlite, bundled feature)
• 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

Data & Config

All runtime state lives under ~/.tam/:

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.