Skip to content

Gira – CLI-First Project Structure

A modern, CLI-first rewrite of Gira with a focus on agentic AI integration, Git-backed storage, and clean architecture. This project avoids early TUI/GUI complexity and emphasizes modular design, testability, and automation support.

📆 Suggested Project Structure

gira/
├── cli/                      # Typer command groups (ticket, epic, sprint, etc.)
│   ├── ticket.py
│   ├── epic.py
│   └── __init__.py
├── core/                     # File system + data manipulation logic
│   ├── ticket_manager.py
│   ├── epic_manager.py
│   ├── jira_mapper.py
│   └── config.py
├── models/                   # Pydantic models for tickets, config, etc.
│   ├── ticket.py
│   ├── epic.py
│   ├── config.py
│   └── base.py
├── services/                 # Jira client, validation, schema helpers
│   ├── jira_client.py
│   └── validator.py
tests/                        # Pytest suite
gira.py                       # Typer entry point

🧱 Tech Stack

Layer Tool / Library Purpose
CLI Typer Declarative CLI building
Output Rich Terminal tables, formatting, progress
Models Pydantic v1 Strongly typed ticket/config schemas
API Client httpx Jira REST API integration
Git I/O GitPython Git commits, status, hooks
JSON Schema jsonschema Validating external inputs and config
Jira SDK jira Jira Cloud/Server API wrapper
Serialization orjson High-performance JSON handling
Logging loguru Structured, colorized logging
Progress Bars tqdm Visual feedback for batch operations
Env Variables python-dotenv Environment-based secrets loading
Packaging Hatch or Poetry Dependency and version management
Testing Pytest, pytest-mock CLI and core logic unit/integration tests
Linting/Style Ruff, Black, isort, mypy, pre-commit Static analysis, formatting, and CI hygiene

📁 Key Directories

  • cli/ – Command-line interface groups, one file per entity (e.g. ticket.py)
  • core/ – Business logic and file I/O (move tickets, resolve status)
  • models/ – Shared Pydantic schemas across CLI and core
  • services/ – Integrations (e.g., Jira), validators, index builders
  • tests/ – Comprehensive test coverage using Pytest

⚙️ Planned Features (Phased)

  1. MVP CLI for ticket, epic, sprint management
  2. Git-integrated .gira/ filesystem tracker
  3. CLI commands with full --json and scriptable options
  4. Comments, attachments, backlog, board support
  5. Import/export from Jira via REST API
  6. Agentic CLI: AI-friendly I/O, machine-readable reports
  7. Optional: Web and TUI frontends later

🛠️ Example CLI Invocation

gira ticket create --title "Fix crash" --assignee alice --priority high
gira epic view EPIC-1 --json
gira jira import --project ACME

🔐 Git Recommendations

  • .gira/ should be Git-tracked except:

  • jira.config.json (add to .gitignore)

  • .index.json (optional, can be rebuilt)
  • .trash/ (up to team policy)

📦 Suggested Dependencies (pyproject.toml)

[tool.poetry.dependencies]
python = "^3.9"
typer = "^0.9"
rich = "^13.5"
pydantic = "^1.10"
httpx = "^0.27"
gitpython = "^3.1"
jira = "^3.10"
orjson = "^3.8"
loguru = "^0.7"
tqdm = "^4.65"
python-dotenv = "^1.0"
jsonschema = "^4.20"

[tool.poetry.dev-dependencies]
pytest = "^7.2"
pytest-mock = "^3.11"
black = "^24.4"
isort = "^5.12"
ruff = "^0.4"
pre-commit = "^2.21"
mypy = "^1.8"

🧪 Testing Strategy

  • Use pytest for all CLI, core, and integration logic
  • Organize tests by module: tests/test_ticket.py, tests/test_epic.py, etc.
  • Use Typer's CLI runner (CliRunner) to test CLI behavior with assertions

  • Include:

  • CLI command tests with output parsing

  • JSON output verification for --json flags
  • File system side effects (e.g., ticket creation)
  • Validation errors and edge cases
  • Use pytest-mock to mock Git, HTTPX, or file I/O as needed
  • Add CI integration with GitHub Actions or Hatch hooks

🧩 Modular Architecture (Long-Term)

To support long-term scalability and interface diversity, Gira will adopt a modular monorepo architecture:

gira/
├── cli/            # Typer CLI (primary dev interface)
├── tui/            # Optional terminal UI using Textual
├── web/            # Local FastAPI/Flask web UI alternative to TUI
├── mcp/            # Message-based command processor for AI agents
├── ai/             # Ollama/OpenAI-powered project manager and ticket generator
├── core/           # Shared file handling, Git ops, status logic
├── models/         # Shared Pydantic data models
├── services/       # Jira client, indexers, AI interface wrappers
├── tests/          # All unit/integration tests
pyproject.toml

Why modular?

  • Shared logic stays DRY and clean
  • CLI remains the truth, but other UIs and AI modules can evolve independently
  • Makes it easier to test, deploy, and reason about each interface or integration
  • Enables feature-parallelism (e.g., AI team can ship ticket auto-tagging while CLI evolves separately)

Future Optional Interfaces

  • ✅ gira tui for dashboards and non-linear workflows
  • ✅ gira web for stakeholders who prefer a browser
  • ✅ gira mcp for long-running AI integration via HTTP or socket
  • ✅ gira ai tools for summarization, ticket classification, etc.

🔍 Next Steps

*