colenio-jira-cli 0.1.2__py3-none-any.whl

colenio_jira_cli-0.1.2.dist-info/METADATA

@@ -0,0 +1,184 @@
+Metadata-Version: 2.4
+Name: colenio-jira-cli
+Version: 0.1.2
+Summary: Modular Jira CLI tool for issue listing, filtering, and management
+Author-email: Colenio <dev@colenio.com>
+License-Expression: MIT
+License-File: LICENSE
+Requires-Python: >=3.11
+Requires-Dist: click>=8.1.0
+Requires-Dist: jira>=3.8.0
+Requires-Dist: pydantic>=2.0.0
+Requires-Dist: python-dotenv>=1.0.0
+Requires-Dist: rich>=13.0.0
+Requires-Dist: tabulate>=0.9.0
+Provides-Extra: dev
+Requires-Dist: black>=24.0.0; extra == 'dev'
+Requires-Dist: pytest>=8.0.0; extra == 'dev'
+Requires-Dist: ruff>=0.2.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# Jira CLI
+
+> Modular, class-based Jira command-line tool for issue listing, searching, and management.
+
+## Features
+
+- **List issues** by project with optional filtering (status, assignee, labels)
+- **Search** with custom JQL queries
+- **Find** issues by text in summary/description
+- **View** issue details with comments
+- **Assign** issues to users
+- **Transition** issues to new status
+- **Multiple output formats**: table, JSON, CSV, Markdown
+- **dotenv support**: Load credentials from `.env` or `local.env` in CWD or parent directories
+
+## Installation
+
+### Via uv (local development)
+
+```bash
+cd colenio/tools/jira-cli
+uv sync
+uv run jira-cli list --help
+```
+
+### Via uvx (remote/published)
+
+```bash
+uvx colenio-jira-cli list --project PROJ
+```
+
+## Setup
+
+Create a `.env` or `local.env` file in your working directory:
+
+```bash
+# Required
+JIRA_URL=https://company.atlassian.net
+JIRA_EMAIL=user@example.com
+JIRA_API_TOKEN=your_api_token_here
+
+# Optional
+JIRA_PROJECT=PROJ      # Default project for list/find
+JIRA_PROJECT_KEY=PROJ  # Backward-compatible fallback
+```
+
+### Getting your Jira API Token
+
+1. Log in to your Jira Cloud instance
+2. Go to Account Settings → Security
+3. Click "Create API Token"
+4. Copy the token and save to `.env`
+
+## Usage
+
+### List issues
+
+```bash
+# Basic listing
+jira-cli list --project PROJ
+
+# With filters
+jira-cli list --project PROJ --status "In Progress" --assignee "john@example.com"
+
+# With custom JQL
+jira-cli list --project PROJ --jql 'priority = High'
+
+# Different output formats
+jira-cli list --project PROJ --format json
+jira-cli list --project PROJ --format csv > issues.csv
+jira-cli list --project PROJ --format md
+```
+
+### Search with JQL
+
+```bash
+jira-cli search 'project = PROJ AND status = "To Do" AND assignee is EMPTY'
+jira-cli search 'text ~ "urgent"' --format json
+```
+
+### Find by text
+
+```bash
+jira-cli find --project PROJ "database migration"
+jira-cli find --project PROJ "performance issue" --max-results 100
+```
+
+### View issue details
+
+```bash
+jira-cli view PROJ-123
+jira-cli view PROJ-456 --comments
+```
+
+### Assign issue
+
+```bash
+jira-cli assign PROJ-789 john@example.com
+```
+
+### Transition issue
+
+```bash
+jira-cli transition PROJ-999 "In Progress" --comment "Starting work"
+jira-cli transition PROJ-999 "Done"
+```
+
+## Architecture
+
+- **`client.py`**: `JiraClient` class for REST API calls, auth, and endpoints
+- **`query.py`**: `JiraQuery` class for JQL building and search logic
+- **`render.py`**: `JiraRenderer` class for output formatting (table, JSON, CSV, Markdown)
+- **`models.py`**: Pydantic models for Jira structures (`JiraIssue`, `JiraSearchResult`, `IssueRow`)
+- **`dotenv.py`**: `DotEnv` class for robust `.env`/`local.env` loading
+- **`cli.py`**: Click CLI commands (list, search, find, view, assign, transition)
+
+All code uses proper classes, no helper functions. Follows informix-migration patterns.
+
+## Development
+
+```bash
+# Install dev dependencies
+uv sync --all-groups
+
+# Run tests
+uv run pytest
+
+# Format and lint
+uv run black jira_cli
+uv run ruff check jira_cli
+```
+
+## Distribution
+
+This tool is designed for publishing via uvx (like `helmrelease-verifier`):
+
+1. Push to GitHub at `colenio/jira-cli`
+2. Configure PyPI Trusted Publisher for this repository
+3. Tag with version: `git tag v0.1.0` and push tag (`git push origin v0.1.0`)
+4. GitHub Action `.github/workflows/release.yml` builds, tests, and publishes to PyPI
+5. Package can be invoked anywhere with: `uvx colenio-jira-cli list --project PROJ`
+
+## PowerShell Integration
+
+Add to `$PROFILE` (e.g., via dotfiles/aliases.ps1):
+
+```powershell
+function jira-cli {
+    uvx colenio-jira-cli @args
+}
+
+# Or use directly
+alias jira = 'uvx colenio-jira-cli'
+```
+
+Then:
+
+```powershell
+jira list --project PROJ
+```
+
+## License
+
+MIT

colenio_jira_cli-0.1.2.dist-info/RECORD

@@ -0,0 +1,12 @@
+jira_cli/__init__.py,sha256=a7vK6K4Hr0zG6rFSo9htjiWEze3W2eoCZJfnrdBEToo,123
+jira_cli/cli.py,sha256=hYmEeOhqbz6dILdPq0xLI3TxsiN3qQG_7jSeyQ2lcWE,9490
+jira_cli/client.py,sha256=ChBaM7WX7n9rtGLDu6d4mTX5M_KCL3VpoeWpy-zP8N4,4407
+jira_cli/dotenv.py,sha256=SUZlUwLlLkywTUdCQOK3iC6uhf4uwlqCa8CGvc0_xdw,3091
+jira_cli/models.py,sha256=eubkzuVyEHIqX_ukQNSqdbRh74rx9cnzq-jREjch1QE,2762
+jira_cli/query.py,sha256=ojVtgHFJNeICCpXoRUcokOTLnVBpVaRuyc1hj6nKGWg,3078
+jira_cli/render.py,sha256=VyKw2YpLUluw_24x1avxFPaa1zr79ivzD4yUMcXj-xQ,2551
+colenio_jira_cli-0.1.2.dist-info/METADATA,sha256=ZdoHS3NkXxZumYlXfm1autFMWipTgIhIzUVIQCz7w4A,4393
+colenio_jira_cli-0.1.2.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
+colenio_jira_cli-0.1.2.dist-info/entry_points.txt,sha256=cpetCgBWsefHQDZPMS5bK4LydGi8ViZDZjhDB3hlGYw,47
+colenio_jira_cli-0.1.2.dist-info/licenses/LICENSE,sha256=SDjwwYevDcHcjk3RCRfWv2HJuny_pK6VzFfqTZ_HW3o,1064
+colenio_jira_cli-0.1.2.dist-info/RECORD,,

colenio_jira_cli-0.1.2.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.30.1
+Root-Is-Purelib: true
+Tag: py3-none-any

colenio_jira_cli-0.1.2.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+jira-cli = jira_cli.cli:main

colenio_jira_cli-0.1.2.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Colenio
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

jira_cli/__init__.py

@@ -0,0 +1,4 @@
+"""Jira CLI — modular command-line interface for Jira issue management."""
+
+__version__ = "0.1.2"
+__author__ = "Colenio"

jira_cli/cli.py

@@ -0,0 +1,262 @@
+"""Click CLI commands."""
+
+import os
+from typing import Optional
+
+import click
+
+from .client import JiraClient
+from .dotenv import DotEnv
+from .query import JiraQuery
+from .render import JiraRenderer
+
+
+@click.group()
+@click.version_option(version="0.1.0")
+def cli():
+    """Modular Jira CLI — list, search, view, and manage Jira issues."""
+    pass
+
+
+def _get_jira_client(base_url: Optional[str] = None, email: Optional[str] = None, api_token: Optional[str] = None) -> JiraClient:
+    """Load Jira credentials from env/dotenv and create client."""
+    # Load from .env or local.env first (local.env takes precedence)
+    env = DotEnv(verbose=False)
+    env.load()
+
+    # Allow override via parameters or env
+    base_url = base_url or os.environ.get("JIRA_URL") or os.environ.get("JIRA_BASE_URL")
+    email = email or os.environ.get("JIRA_EMAIL") or os.environ.get("JIRA_USER")
+    api_token = api_token or os.environ.get("JIRA_API_TOKEN") or os.environ.get("JIRA_TOKEN")
+
+    if not all([base_url, email, api_token]):
+        missing = []
+        if not base_url:
+            missing.append("JIRA_URL or JIRA_BASE_URL")
+        if not email:
+            missing.append("JIRA_EMAIL or JIRA_USER")
+        if not api_token:
+            missing.append("JIRA_API_TOKEN or JIRA_TOKEN")
+        
+        click.echo(f"❌ Missing: {', '.join(missing)}", err=True)
+        click.echo("Configure in .env or local.env in CWD or parent directories:", err=True)
+        click.echo("  JIRA_URL=https://company.atlassian.net", err=True)
+        click.echo("  JIRA_EMAIL=user@example.com", err=True)
+        click.echo("  JIRA_API_TOKEN=your_api_token", err=True)
+        raise SystemExit(1)
+
+    return JiraClient(base_url=base_url, email=email, api_token=api_token)
+
+
+def _resolve_project(project: Optional[str]) -> str:
+    """Resolve project key from option or env (JIRA_PROJECT/JIRA_PROJECT_KEY)."""
+    resolved = project or os.environ.get("JIRA_PROJECT") or os.environ.get("JIRA_PROJECT_KEY")
+    if not resolved:
+        click.echo("❌ Missing project key. Use --project or set JIRA_PROJECT in local.env/.env", err=True)
+        raise SystemExit(1)
+    return resolved
+
+
+@cli.command(name="list")
+@click.option("--project", "-p", default="", help="Jira project key (e.g. PROJ); defaults to JIRA_PROJECT/JIRA_PROJECT_KEY")
+@click.option("--status", "-s", default="", help="Filter by status (e.g. 'To Do')")
+@click.option("--assignee", "-a", default="", help="Filter by assignee")
+@click.option("--label", "-l", default="", help="Filter by label")
+@click.option("--jql", default="", help="Additional JQL conditions (AND appended)")
+@click.option("--max-results", type=int, default=50, show_default=True, help="Max issues to return")
+@click.option("--format", type=click.Choice(["table", "json", "csv", "md"]), default="table", help="Output format")
+def list_issues(project: str, status: str, assignee: str, label: str, jql: str, max_results: int, format: str):
+    """List issues in a project with optional filters."""
+    try:
+        client = _get_jira_client()
+        query = JiraQuery(client)
+        renderer = JiraRenderer()
+        project_key = _resolve_project(project)
+
+        rows = query.search_project(
+            project_key=project_key,
+            status=status or None,
+            assignee=assignee or None,
+            label=label or None,
+            jql_extra=jql or None,
+            max_results=max_results,
+        )
+
+        if format == "table":
+            renderer.table(rows, title=f"Issues in {project_key}")
+        elif format == "json":
+            output = renderer.json(rows)
+            renderer.print(output)
+        elif format == "csv":
+            output = renderer.csv(rows)
+            renderer.print(output)
+        elif format == "md":
+            output = renderer.markdown(rows)
+            renderer.print(output)
+
+    except SystemExit:
+        raise
+    except Exception as e:
+        click.echo(f"❌ Error: {e}", err=True)
+        raise SystemExit(1)
+
+
+@cli.command(name="search")
+@click.argument("jql")
+@click.option("--max-results", type=int, default=50, show_default=True)
+@click.option("--format", type=click.Choice(["table", "json", "csv", "md"]), default="table")
+def search(jql: str, max_results: int, format: str):
+    """Search issues using custom JQL."""
+    try:
+        client = _get_jira_client()
+        query = JiraQuery(client)
+        renderer = JiraRenderer()
+
+        rows = query.search_custom_jql(jql, max_results=max_results)
+
+        if format == "table":
+            renderer.table(rows, title="Search Results")
+        elif format == "json":
+            output = renderer.json(rows)
+            renderer.print(output)
+        elif format == "csv":
+            output = renderer.csv(rows)
+            renderer.print(output)
+        elif format == "md":
+            output = renderer.markdown(rows)
+            renderer.print(output)
+
+    except SystemExit:
+        raise
+    except Exception as e:
+        click.echo(f"❌ Error: {e}", err=True)
+        raise SystemExit(1)
+
+
+@cli.command(name="find")
+@click.option("--project", "-p", default="", help="Jira project key; defaults to JIRA_PROJECT/JIRA_PROJECT_KEY")
+@click.argument("text")
+@click.option("--max-results", type=int, default=50, show_default=True)
+@click.option("--format", type=click.Choice(["table", "json", "csv"]), default="table")
+def find(project: str, text: str, max_results: int, format: str):
+    """Find issues by text in summary/description."""
+    try:
+        client = _get_jira_client()
+        query = JiraQuery(client)
+        renderer = JiraRenderer()
+        project_key = _resolve_project(project)
+
+        rows = query.find_by_text(project_key, text, max_results=max_results)
+
+        if format == "table":
+            renderer.table(rows, title=f"Search for '{text}' in {project_key}")
+        elif format == "json":
+            output = renderer.json(rows)
+            renderer.print(output)
+        elif format == "csv":
+            output = renderer.csv(rows)
+            renderer.print(output)
+
+    except SystemExit:
+        raise
+    except Exception as e:
+        click.echo(f"❌ Error: {e}", err=True)
+        raise SystemExit(1)
+
+
+@cli.command(name="view")
+@click.argument("key")
+@click.option("--comments", is_flag=True, help="Include issue comments")
+def view(key: str, comments: bool):
+    """View issue details."""
+    try:
+        client = _get_jira_client()
+        issue = client.get_issue(
+            key,
+            fields=["key", "summary", "description", "status", "priority", "assignee", "labels", "comment"],
+        )
+
+        fields = issue.get("fields", {})
+        
+        click.echo(f"\n📌 {issue['key']}: {fields.get('summary', 'N/A')}\n")
+        click.echo(f"  Status:      {fields.get('status', {}).get('name', 'N/A')}")
+        click.echo(f"  Priority:    {fields.get('priority', {}).get('name', 'N/A')}")
+        assignee = fields.get("assignee")
+        click.echo(f"  Assignee:    {assignee.get('displayName', 'Unassigned') if assignee else 'Unassigned'}")
+        labels = fields.get("labels", [])
+        click.echo(f"  Labels:      {', '.join(labels) if labels else 'None'}")
+        
+        description = fields.get("description")
+        if description:
+            click.echo(f"\n📝 Description:")
+            if isinstance(description, dict):  # Rich text format
+                click.echo("  (Rich text format)")
+            else:
+                click.echo(f"  {description}")
+
+        if comments:
+            comments_list = fields.get("comment", {}).get("comments", [])
+            if comments_list:
+                click.echo(f"\n💬 Comments ({len(comments_list)}):")
+                for c in comments_list:
+                    author = c.get("author", {}).get("displayName", "Unknown")
+                    body = c.get("body", {})
+                    if isinstance(body, dict):
+                        click.echo(f"  @{author}: (Rich text)")
+                    else:
+                        click.echo(f"  @{author}: {body}")
+            else:
+                click.echo("\n💬 No comments")
+
+        click.echo()
+
+    except SystemExit:
+        raise
+    except Exception as e:
+        click.echo(f"❌ Error: {e}", err=True)
+        raise SystemExit(1)
+
+
+@cli.command(name="assign")
+@click.argument("key")
+@click.argument("assignee")
+@click.option("--comment", default="", help="Optional transition comment")
+def assign_issue(key: str, assignee: str, comment: str):
+    """Assign issue to user."""
+    try:
+        client = _get_jira_client()
+        client.assign_issue(key, assignee)
+        click.echo(f"✅ Assigned {key} to {assignee}")
+
+    except SystemExit:
+        raise
+    except Exception as e:
+        click.echo(f"❌ Error: {e}", err=True)
+        raise SystemExit(1)
+
+
+@cli.command(name="transition")
+@click.argument("key")
+@click.argument("transition_id")
+@click.option("--comment", default="", help="Optional transition comment")
+def transition(key: str, transition_id: str, comment: str):
+    """Transition issue to new status."""
+    try:
+        client = _get_jira_client()
+        client.transition_issue(key, transition_id, comment=comment or None)
+        click.echo(f"✅ Transitioned {key} to {transition_id}")
+
+    except SystemExit:
+        raise
+    except Exception as e:
+        click.echo(f"❌ Error: {e}", err=True)
+        raise SystemExit(1)
+
+
+def main():
+    """Main entry point."""
+    cli()
+
+
+if __name__ == "__main__":
+    main()

jira_cli/client.py

@@ -0,0 +1,141 @@
+"""Jira API client."""
+
+from typing import Optional
+
+from jira import JIRA
+
+from .models import JiraSearchResult
+
+
+class JiraClient:
+    """Client wrapper around the official jira Python library."""
+
+    def __init__(self, base_url: str, email: str, api_token: str, dry_run: bool = False, timeout: int = 30):
+        """
+        Initialize Jira client.
+        
+        Args:
+            base_url: Jira instance URL (e.g. https://company.atlassian.net)
+            email: Jira user email
+            api_token: Jira API token (from Account Settings → Security)
+            dry_run: If True, only print requests without executing
+            timeout: Request timeout in seconds
+        """
+        self.base_url = base_url.rstrip("/")
+        self.email = email
+        self.api_token = api_token
+        self.dry_run = dry_run
+        self.timeout = timeout
+        self._jira = JIRA(
+            server=self.base_url,
+            basic_auth=(self.email, self.api_token),
+            options={"rest_api_version": "3"},
+            timeout=self.timeout,
+        )
+
+    def search(
+        self,
+        jql: str,
+        fields: Optional[list[str]] = None,
+        start_at: int = 0,
+        max_results: int = 50,
+        expand: Optional[list[str]] = None,
+    ) -> JiraSearchResult:
+        """
+        Search issues using JQL via official client.
+        
+        Args:
+            jql: JQL query string
+            fields: List of fields to return (e.g. ['key', 'summary', 'status'])
+            start_at: Start index for pagination
+            max_results: Max issues to return (max 100 for API limit)
+            expand: List of fields to expand (e.g. 'changelog')
+        
+        Returns:
+            JiraSearchResult with issues list
+        """
+        if self.dry_run:
+            print(f"[dry-run] POST /search/jql | JQL={jql} | start_at={start_at} | max_results={max_results}")
+            return JiraSearchResult(issues=[], total=0)
+
+        raw = self._jira.search_issues(
+            jql_str=jql,
+            startAt=start_at,
+            maxResults=max_results,
+            fields=fields if fields else None,
+            expand=",".join(expand) if expand else None,
+            json_result=True,
+            use_post=True,
+        )
+
+        return JiraSearchResult(**raw)
+
+    def get_issue(self, key: str, fields: Optional[list[str]] = None, expand: Optional[list[str]] = None) -> dict:
+        """
+        Fetch single issue by key.
+        
+        Args:
+            key: Issue key (e.g. 'JIRA-123')
+            fields: List of fields to return
+            expand: List of fields to expand
+        
+        Returns:
+            Issue dict
+        """
+        if self.dry_run:
+            print(f"[dry-run] GET /issues/{key}")
+            return {}
+
+        issue = self._jira.issue(
+            key,
+            fields=fields if fields else None,
+            expand=",".join(expand) if expand else None,
+        )
+        return issue.raw
+
+    def get_issue_comments(self, key: str, expand_changelog: bool = False) -> list[dict]:
+        """
+        Fetch comments for an issue.
+        
+        Args:
+            key: Issue key
+            expand_changelog: Include changelog details
+        
+        Returns:
+            List of comment dicts
+        """
+        if self.dry_run:
+            print(f"[dry-run] GET /issues/{key}/comments")
+            return []
+
+        comments = self._jira.comments(key)
+        return [c.raw for c in comments]
+
+    def transition_issue(self, key: str, transition_id: str, comment: Optional[str] = None) -> None:
+        """
+        Transition issue to new status.
+        
+        Args:
+            key: Issue key
+            transition_id: Transition ID (e.g. 'In Progress', 'Done')
+            comment: Optional comment to add
+        """
+        if self.dry_run:
+            print(f"[dry-run] POST /issues/{key}/transitions | transition={transition_id}")
+            return
+
+        self._jira.transition_issue(key, transition_id, comment=comment or None)
+
+    def assign_issue(self, key: str, assignee_key: str) -> None:
+        """
+        Assign issue to user.
+        
+        Args:
+            key: Issue key
+            assignee_key: User key or email
+        """
+        if self.dry_run:
+            print(f"[dry-run] PUT /issues/{key} | assignee={assignee_key}")
+            return
+
+        self._jira.assign_issue(key, assignee_key)

jira_cli/dotenv.py

@@ -0,0 +1,83 @@
+"""DotEnv handling — robust loading from CWD/.env or local.env."""
+
+import os
+from pathlib import Path
+
+
+class DotEnv:
+    """Load environment variables from .env or local.env in CWD or parent directories."""
+
+    def __init__(self, search_up: int = 3, verbose: bool = False):
+        """
+        Args:
+            search_up: How many parent directories to search up for .env/local.env
+            verbose: Print debug info when loading env files
+        """
+        self.search_up = search_up
+        self.verbose = verbose
+        self._loaded_from = None
+
+    def load(self) -> dict[str, str]:
+        """
+        Load from .env or local.env in CWD or parent directories.
+        Tries: CWD/local.env → CWD/.env → parent/local.env → parent/.env (up to search_up levels)
+        
+        Returns dict of loaded variables (also sets in os.environ).
+        """
+        cwd = Path.cwd()
+        candidates = []
+
+        # Build candidate list: current and parent dirs, prioritizing local.env
+        for level in range(self.search_up + 1):
+            target_dir = cwd
+            for _ in range(level):
+                target_dir = target_dir.parent
+                if target_dir == target_dir.parent:  # Reached filesystem root
+                    break
+
+            # local.env first, then .env
+            candidates.append(target_dir / "local.env")
+            candidates.append(target_dir / ".env")
+
+        loaded = {}
+        for candidate in candidates:
+            if candidate.exists() and candidate.is_file():
+                self._load_file(candidate)
+                with open(candidate, "r", encoding="utf-8") as f:
+                    for line in f:
+                        line = line.strip()
+                        if not line or line.startswith("#"):
+                            continue
+                        if "=" in line:
+                            key, val = line.split("=", 1)
+                            key = key.strip()
+                            val = val.strip()
+                            loaded[key] = val
+                            os.environ[key] = val
+                
+                self._loaded_from = candidate
+                if self.verbose:
+                    print(f"[dotenv] Loaded from {self._loaded_from}")
+                return loaded
+
+        if self.verbose:
+            print("[dotenv] No .env/local.env found")
+
+        return loaded
+
+    def _load_file(self, path: Path) -> None:
+        """Load single env file into os.environ."""
+        if self.verbose:
+            print(f"[dotenv] Reading {path}")
+
+    def get(self, key: str, default: str = "") -> str:
+        """Get env variable (from loaded or os.environ)."""
+        return os.environ.get(key, default)
+
+    def require(self, *keys: str) -> dict[str, str]:
+        """Get multiple required env variables. Raise if any missing."""
+        missing = [k for k in keys if not os.environ.get(k)]
+        if missing:
+            raise ValueError(f"Missing required environment variables: {', '.join(missing)}")
+        
+        return {k: os.environ[k] for k in keys}

jira_cli/models.py

@@ -0,0 +1,108 @@
+"""Pydantic models for Jira API responses."""
+
+from datetime import datetime
+from typing import Optional
+
+from pydantic import BaseModel, Field
+
+
+class JiraUser(BaseModel):
+    """Jira user representation."""
+
+    key: str
+    display_name: str = Field(alias="displayName")
+    email: Optional[str] = None
+    avatar_url: Optional[str] = Field(None, alias="avatarUrls")
+
+    class Config:
+        populate_by_name = True
+
+
+class JiraIssueField(BaseModel):
+    """Jira issue field (stripped down)."""
+
+    summary: str
+    status: Optional[dict | str] = None
+    priority: Optional[dict | str] = None
+    assignee: Optional[dict] = None
+    reporter: Optional[dict] = None
+    labels: list[str] = []
+    created: Optional[str] = None
+    updated: Optional[str] = None
+    description: Optional[str] = None
+
+    class Config:
+        extra = "allow"
+
+
+class JiraIssue(BaseModel):
+    """Complete Jira issue."""
+
+    key: str
+    fields: JiraIssueField
+
+    class Config:
+        extra = "allow"
+
+
+class JiraSearchResult(BaseModel):
+    """Response from Jira search endpoint."""
+
+    issues: list[JiraIssue] = []
+    total: int = 0
+    max_results: int = Field(0, alias="maxResults")
+    start_at: int = Field(0, alias="startAt")
+    next_page_token: Optional[str] = Field(None, alias="nextPageToken")
+
+    class Config:
+        populate_by_name = True
+
+
+class IssueRow(BaseModel):
+    """Flattened issue for table/csv output."""
+
+    key: str
+    summary: str
+    status: str = ""
+    priority: str = ""
+    assignee: str = ""
+    updated: str = ""
+    labels: str = ""
+
+    @staticmethod
+    def from_jira_issue(issue: JiraIssue) -> "IssueRow":
+        """Convert Jira issue to flattened row."""
+        fields = issue.fields
+
+        status = ""
+        if isinstance(fields.status, dict):
+            status = fields.status.get("name", "")
+        elif isinstance(fields.status, str):
+            status = fields.status
+
+        priority = ""
+        if isinstance(fields.priority, dict):
+            priority = fields.priority.get("name", "")
+        elif isinstance(fields.priority, str):
+            priority = fields.priority
+
+        assignee = ""
+        if fields.assignee:
+            assignee = (
+                fields.assignee.get("displayName")
+                or fields.assignee.get("name")
+                or fields.assignee.get("accountId")
+                or fields.assignee.get("key", "")
+            )
+        
+        labels = ", ".join(fields.labels) if fields.labels else ""
+        
+        return IssueRow(
+            key=issue.key,
+            summary=fields.summary,
+            status=status,
+            priority=priority,
+            assignee=assignee,
+            updated=fields.updated or "",
+            labels=labels,
+        )

jira_cli/query.py

@@ -0,0 +1,95 @@
+"""JQL query builder and search logic."""
+
+from typing import Optional
+
+from .client import JiraClient
+from .models import IssueRow
+
+
+class JiraQuery:
+    """Build and execute JQL queries."""
+
+    def __init__(self, client: JiraClient):
+        self.client = client
+
+    def search_project(
+        self,
+        project_key: str,
+        status: Optional[str] = None,
+        assignee: Optional[str] = None,
+        label: Optional[str] = None,
+        jql_extra: Optional[str] = None,
+        fields: Optional[list[str]] = None,
+        max_results: int = 50,
+    ) -> list[IssueRow]:
+        """
+        Search issues in a project with optional filters.
+        
+        Args:
+            project_key: Jira project key
+            status: Filter by status (e.g. 'To Do', 'In Progress')
+            assignee: Filter by assignee
+            label: Filter by label
+            jql_extra: Additional JQL conditions (AND appended)
+            fields: Specific fields to fetch
+            max_results: Max results to return
+        
+        Returns:
+            List of IssueRow (flattened for output)
+        """
+        conditions = [f"project = {project_key}"]
+
+        if status:
+            conditions.append(f"status = '{status}'")
+        if assignee:
+            conditions.append(f"assignee = '{assignee}'")
+        if label:
+            conditions.append(f"labels = {label}")
+        if jql_extra:
+            conditions.append(jql_extra)
+
+        jql = " AND ".join(conditions)
+
+        # Default fields to fetch
+        if not fields:
+            fields = ["key", "summary", "status", "priority", "assignee", "updated", "labels"]
+
+        result = self.client.search(jql, fields=fields, max_results=max_results)
+
+        return [IssueRow.from_jira_issue(issue) for issue in result.issues]
+
+    def search_custom_jql(self, jql: str, fields: Optional[list[str]] = None, max_results: int = 50) -> list[IssueRow]:
+        """
+        Execute custom JQL query.
+        
+        Args:
+            jql: Full JQL query string
+            fields: Specific fields to fetch
+            max_results: Max results
+        
+        Returns:
+            List of IssueRow
+        """
+        if not fields:
+            fields = ["key", "summary", "status", "priority", "assignee", "updated", "labels"]
+
+        result = self.client.search(jql, fields=fields, max_results=max_results)
+        return [IssueRow.from_jira_issue(issue) for issue in result.issues]
+
+    def find_by_text(
+        self, project_key: str, text: str, fields: Optional[list[str]] = None, max_results: int = 50
+    ) -> list[IssueRow]:
+        """
+        Search issues by summary/description text.
+        
+        Args:
+            project_key: Project key
+            text: Search text
+            fields: Specific fields to fetch
+            max_results: Max results
+        
+        Returns:
+            List of IssueRow
+        """
+        jql = f'project = {project_key} AND (summary ~ "{text}" OR description ~ "{text}")'
+        return self.search_custom_jql(jql, fields=fields, max_results=max_results)

jira_cli/render.py

@@ -0,0 +1,83 @@
+"""Output rendering (table, JSON, CSV, Markdown)."""
+
+import csv
+import io
+import json
+from typing import Optional
+
+from rich.console import Console
+from rich.table import Table
+
+from .models import IssueRow
+
+
+class JiraRenderer:
+    """Render Jira data in multiple formats."""
+
+    def __init__(self, console: Optional[Console] = None):
+        self.console = console or Console()
+
+    def table(self, rows: list[IssueRow], title: Optional[str] = None) -> None:
+        """Render as rich table."""
+        if not rows:
+            self.console.print("[yellow]No issues found.[/yellow]")
+            return
+
+        t = Table(title=title)
+        t.add_column("Key", style="cyan")
+        t.add_column("Summary", style="white")
+        t.add_column("Status", style="green")
+        t.add_column("Priority", style="yellow")
+        t.add_column("Assignee")
+        t.add_column("Updated", style="dim")
+
+        for row in rows:
+            t.add_row(
+                row.key,
+                row.summary[:70] + "..." if len(row.summary) > 70 else row.summary,
+                row.status,
+                row.priority,
+                row.assignee,
+                row.updated[:10] if row.updated else "",
+            )
+
+        self.console.print(t)
+        self.console.print(f"[green]✓ {len(rows)} issue(s)[/green]")
+
+    def json(self, rows: list[IssueRow]) -> str:
+        """Render as JSON."""
+        data = [row.model_dump() for row in rows]
+        return json.dumps(data, indent=2)
+
+    def csv(self, rows: list[IssueRow]) -> str:
+        """Render as CSV."""
+        if not rows:
+            return ""
+
+        output = io.StringIO()
+        writer = csv.DictWriter(output, fieldnames=rows[0].model_fields.keys())
+        writer.writeheader()
+        for row in rows:
+            writer.writerow(row.model_dump())
+
+        return output.getvalue()
+
+    def markdown(self, rows: list[IssueRow]) -> str:
+        """Render as Markdown table."""
+        if not rows:
+            return "No issues found.\n"
+
+        lines = [
+            "| Key | Summary | Status | Priority | Assignee |",
+            "|-----|---------|--------|----------|----------|",
+        ]
+
+        for row in rows:
+            summary = row.summary.replace("|", "\\|")[:70]
+            lines.append(f"| {row.key} | {summary} | {row.status} | {row.priority} | {row.assignee} |")
+
+        return "\n".join(lines) + "\n"
+
+    def print(self, output: str) -> None:
+        """Print raw output (for JSON/CSV/Markdown)."""
+        self.console.print(output, highlight=False)