first commmit

Author: armiiller

.github/workflows/ci.yml

@@ -0,0 +1,91 @@
+name: CI
+
+on:
+  push:
+    branches:
+      - main
+  pull_request:
+    branches:
+      - main
+
+jobs:
+  build-and-publish:
+    runs-on: ${{ matrix.os }}
+    strategy:
+      matrix:
+        os: [ubuntu-latest, windows-latest]
+      fail-fast: false  # Continue even if one OS fails
+
+    steps:
+      # Checkout the repository
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      # Set up Python
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.13.2'
+
+      # Install pyenv dependencies (Ubuntu only)
+      - name: Install pyenv dependencies (Ubuntu)
+        if: matrix.os == 'ubuntu-latest'
+        run: |
+          sudo apt-get update
+          sudo apt-get install -y build-essential libssl-dev zlib1g-dev libbz2-dev \
+            libreadline-dev libsqlite3-dev curl libncurses5-dev libncursesw5-dev \
+            xz-utils libffi-dev liblzma-dev python3-openssl
+
+      # Install dependencies
+      - name: Install project dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install -r requirements.txt
+          pip install pyinstaller
+
+      # Run tests (placeholder—uncomment and adjust when tests are added)
+      # - name: Run tests
+      #   run: |
+      #     pip install pytest
+      #     pytest tests/
+
+      # Build the executable with PyInstaller
+      - name: Build executable
+        run: |
+          pyinstaller pagertree.spec
+          if [ "${{ matrix.os }}" = "ubuntu-latest" ]; then
+            mv dist/pagertree dist/pagertree-linux
+          elif [ "${{ matrix.os }}" = "windows-latest" ]; then
+            mv dist/pagertree.exe dist/pagertree-windows.exe
+          fi
+        shell: bash  # Use bash for consistent scripting across OSes
+
+      # Version the build (using git tag or commit SHA)
+      - name: Set version
+        id: version
+        run: |
+          VERSION=$(git describe --tags --always --dirty)
+          echo "VERSION=$VERSION" >> $GITHUB_ENV
+        shell: bash
+
+      # Upload artifact
+      - name: Upload executable
+        uses: actions/upload-artifact@v4
+        with:
+          name: pagertree-${{ matrix.os == 'ubuntu-latest' && 'linux' || 'windows' }}-${{ env.VERSION }}
+          path: dist/pagertree-${{ matrix.os == 'ubuntu-latest' && 'linux' || 'windows' }}${{ matrix.os == 'windows-latest' && '.exe' || '' }}
+
+      # Publish to GitHub Releases (only on push to main)
+      - name: Create Release
+        if: github.event_name == 'push' && github.ref == 'refs/heads/main'
+        uses: softprops/action-gh-release@v2
+        with:
+          tag_name: ${{ env.VERSION }}
+          name: Release ${{ env.VERSION }}
+          draft: false
+          prerelease: false
+          files: |
+            dist/pagertree-linux
+            dist/pagertree-windows.exe
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

.gitignore

@@ -0,0 +1,48 @@
+# Python-specific
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+build/
+dist/
+*.egg-info/
+*.egg
+pip_log.txt
+
+# Virtual environment
+venv/
+env/
+.venv/
+
+# Environment variables (from our .env suggestion)
+.env
+
+# PyInstaller (if you package it as an executable, as mentioned earlier)
+*.spec
+dist/
+build/
+
+# IDEs and editors
+.idea/
+.vscode/
+*.sublime-project
+*.sublime-workspace
+
+# OS-specific
+.DS_Store
+Thumbs.db
+
+# Logs and temporary files
+*.log
+*.tmp
+*.bak
+
+# Project-specific caches or local data (if you add caching later)
+*.cache
+cache/
+
+# Coverage and testing (if you add tests later)
+.coverage
+coverage.xml
+htmlcov/

README.md

@@ -0,0 +1,10 @@
+# PagerTree CLI
+
+A command-line interface (CLI) tool for interacting with the PagerTree API. This tool allows users to manage alerts and other resources in PagerTree directly from the terminal. Built with Python and `click`, it supports nested commands, pagination, and table-formatted output.
+
+## Features
+- Manage PagerTree alerts (`alerts create`, `alerts list`, `alerts show`).
+- Pagination support with `--limit`, `--offset`, and `--all` options.
+- Pretty table output using `tabulate`.
+- Environment variable configuration with `.env` file support.
+- Extensible design with dynamic command registration.

api.py

@@ -0,0 +1,35 @@
+import requests
+from config import API_KEY, BASE_URL
+
+def api_create_alert(title, description):
+    """Create a new alert in PagerTree."""
+    headers = {"Authorization": f"Bearer {API_KEY}", "Content-Type": "application/json"}
+    payload = {
+        "title": title,
+        "description": description,
+    }
+    response = requests.post(f"{BASE_URL}/alerts", json=payload, headers=headers)
+    response.raise_for_status()  # Raise an error for bad responses
+    return response.json()
+
+def api_list_alerts(limit=10, offset=0):
+    """List all alerts in PagerTree."""
+    headers = {"Authorization": f"Bearer {API_KEY}"}
+    params = {"limit": limit, "offset": offset}  # Adjust based on API docs
+    response = requests.get(f"{BASE_URL}/alerts", headers=headers, params=params)
+    response.raise_for_status()
+    data = response.json()
+    return {
+      "data": data.get("data", []),  # List of incidents
+      "total": data.get("total_count", 0),  # Total number of incidents
+      "has_more": data.get("has_more", False),  # Boolean indicating if there are more incidents
+      "limit": limit,
+      "offset": offset
+    }
+
+def api_show_alert(alert_id):
+    """Fetch a single alert by ID from PagerTree."""
+    headers = {"Authorization": f"Bearer {API_KEY}"}
+    response = requests.get(f"{BASE_URL}/alerts/{alert_id}", headers=headers)
+    response.raise_for_status()
+    return response.json()

commands/alerts.py

@@ -0,0 +1,54 @@
+import click
+from api import api_create_alert, api_list_alerts, api_show_alert
+from utils import display_paginated_results, handle_api_error, format_item_details
+
+@click.group()
+def alerts():
+    """Commands for managing PagerTree alerts."""
+    pass
+
+@alerts.command(name="create")
+@click.option("--title", required=True, help="Title of the alert")
+@click.option("--description", help="Description of the alert")
+def create_alert_cmd(title, description):
+    """Create a new alert in PagerTree."""
+    try:
+        result = api_create_alert(title, description or "No description provided")
+        click.echo(f"Alert created successfully: {result.get('id')}")
+    except Exception as e:
+        click.echo(f"Error creating alert: {str(e)}", err=True)
+
+@alerts.command(name="list")
+@click.option("--limit", default=10, type=click.IntRange(1, 100), help="Number of alerts per page")
+@click.option("--offset", default=0, type=click.IntRange(0), help="Starting point for pagination")
+def list_alerts_cmd(limit, offset):
+    """List alerts in PagerTree with pagination."""
+    try:
+        result = api_list_alerts(limit=limit, offset=offset)
+        alerts_list = result["data"]
+        total = result["total"]
+        # Prepare table data
+        headers = ["ID", "Title", "Status"]
+        table_data = [[alert.get("tiny_id"), alert.get("title"), alert.get("status")] for alert in alerts_list]
+        display_paginated_results(alerts_list, total, limit, offset, "alert", headers, table_data)
+    except Exception as e:
+        handle_api_error(e, action="listing alerts")
+
+@alerts.command(name="show")
+@click.argument("alert_id", required=True)
+def show_alert_cmd(alert_id):
+    """Show details of a specific alert in PagerTree."""
+    try:
+        alert = api_show_alert(alert_id)
+        fields = {
+            "id": "Alert ID",
+            "title": "Title",
+            "description": "Description",
+            "status": "Status",
+            "created_at": "Created At"
+        }
+        format_item_details(alert, fields)
+    except requests.exceptions.HTTPError as e:
+        click.echo(f"Error fetching alert: {e.response.status_code} - {e.response.reason}", err=True)
+    except Exception as e:
+        handle_api_error(e, "showing alert")

config.py

@@ -0,0 +1,9 @@
+import os
+from dotenv import load_dotenv
+
+# Load .env file if it exists (useful for development)
+load_dotenv()
+
+# Configuration variables from environment variables
+API_KEY = os.getenv("PAGERTREE_API_KEY", "your-default-api-key-here")
+BASE_URL = os.getenv("PAGERTREE_BASE_URL", "https://api.pagertree.com/api/v4")

pagertree.py

@@ -0,0 +1,21 @@
+#!/usr/bin/env python
+
+import click
+import os
+import importlib
+import pkgutil
+
+@click.group()
+def cli():
+    """PagerTree CLI Tool - Manage alerts from the command line."""
+    pass
+
+# Dynamically register all command groups from the 'commands' package
+commands_dir = os.path.join(os.path.dirname(__file__), "commands")
+for _, module_name, _ in pkgutil.iter_modules([commands_dir]):
+    module = importlib.import_module(f"commands.{module_name}")
+    if hasattr(module, module_name):  # Check if the module has a group with the same name
+        cli.add_command(getattr(module, module_name))
+
+if __name__ == "__main__":
+    cli()

requirements.txt

@@ -0,0 +1,13 @@
+altgraph==0.17.4
+certifi==2025.1.31
+charset-normalizer==3.4.1
+click==8.1.8
+idna==3.10
+packaging==24.2
+pyinstaller==6.12.0
+pyinstaller-hooks-contrib==2025.2
+python-dotenv==1.1.0
+requests==2.32.3
+setuptools==78.1.0
+tabulate==0.9.0
+urllib3==2.3.0

utils.py

@@ -0,0 +1,24 @@
+import click
+import requests
+from tabulate import tabulate
+
+def display_paginated_results(items, total, limit, offset, item_type="item", table_headers=None, table_data=None):
+    """Display a paginated list of items with consistent formatting."""
+    click.echo(f"Showing {len(items)} of {total} {item_type}s (offset: {offset}, limit: {limit})")
+    if table_headers and table_data:
+        click.echo(tabulate(table_data, headers=table_headers, tablefmt="github"))
+    if offset + limit < total:
+        click.echo(f"More {item_type}s available. Use --offset {offset + limit} to see next page.")
+
+def handle_api_error(e, action="performing action"):
+    """Handle API errors with consistent messaging."""
+    if isinstance(e, requests.exceptions.HTTPError):
+        click.echo(f"Error {action}: {e.response.status_code} - {e.response.reason}", err=True)
+    else:
+        click.echo(f"Error {action}: {str(e)}", err=True)
+
+def format_item_details(item, fields):
+    """Format and display item details from a dict with specified fields."""
+    for field_name, display_name in fields.items():
+        value = item.get(field_name, "N/A")
+        click.echo(f"{display_name}: {value}")