semacli 0.1.2__tar.gz

semacli-0.1.2/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 lduchosal
+
+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.

semacli-0.1.2/PKG-INFO

@@ -0,0 +1,200 @@
+Metadata-Version: 2.1
+Name: semacli
+Version: 0.1.2
+Summary: A CLI tool to manage Semaphore UI (ansible-semaphore) via HTTP REST API
+Keywords: semaphore,ansible,cli,api,devops
+Author-Email: lduchosal <lduchosal@github.com>
+License: MIT
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: System Administrators
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: System :: Systems Administration
+Project-URL: Homepage, https://github.com/lduchosal/semacli
+Project-URL: Bug Reports, https://github.com/lduchosal/semacli/issues
+Project-URL: Source, https://github.com/lduchosal/semacli
+Project-URL: Documentation, https://github.com/lduchosal/semacli/blob/main/README.md
+Requires-Python: >=3.10
+Requires-Dist: click<9.0,>=8.0
+Description-Content-Type: text/markdown
+
+# semacli
+
+[![PyPI version](https://img.shields.io/pypi/v/semacli.svg)](https://pypi.org/project/semacli/)
+[![Python versions](https://img.shields.io/pypi/pyversions/semacli.svg)](https://pypi.org/project/semacli/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Build](https://github.com/lduchosal/semacli/actions/workflows/python-package.yml/badge.svg)](https://github.com/lduchosal/semacli/actions/workflows/python-package.yml)
+[![Publish](https://github.com/lduchosal/semacli/actions/workflows/python-publish.yml/badge.svg)](https://github.com/lduchosal/semacli/actions/workflows/python-publish.yml)
+[![codecov](https://codecov.io/gh/lduchosal/semacli/branch/main/graph/badge.svg)](https://codecov.io/gh/lduchosal/semacli)
+[![Docstring coverage](./interrogate_badge.svg)](./interrogate_badge.svg)
+[![Quality Gate Status](https://sonarcloud.io/api/project_badges/measure?project=lduchosal_semacli&metric=alert_status)](https://sonarcloud.io/summary/new_code?id=lduchosal_semacli)
+[![Maintainability Rating](https://sonarcloud.io/api/project_badges/measure?project=lduchosal_semacli&metric=sqale_rating)](https://sonarcloud.io/summary/new_code?id=lduchosal_semacli)
+[![Reliability Rating](https://sonarcloud.io/api/project_badges/measure?project=lduchosal_semacli&metric=reliability_rating)](https://sonarcloud.io/summary/new_code?id=lduchosal_semacli)
+[![Security Rating](https://sonarcloud.io/api/project_badges/measure?project=lduchosal_semacli&metric=security_rating)](https://sonarcloud.io/summary/new_code?id=lduchosal_semacli)
+[![Bugs](https://sonarcloud.io/api/project_badges/measure?project=lduchosal_semacli&metric=bugs)](https://sonarcloud.io/summary/new_code?id=lduchosal_semacli)
+[![Vulnerabilities](https://sonarcloud.io/api/project_badges/measure?project=lduchosal_semacli&metric=vulnerabilities)](https://sonarcloud.io/summary/new_code?id=lduchosal_semacli)
+[![Code Smells](https://sonarcloud.io/api/project_badges/measure?project=lduchosal_semacli&metric=code_smells)](https://sonarcloud.io/summary/new_code?id=lduchosal_semacli)
+[![Technical Debt](https://sonarcloud.io/api/project_badges/measure?project=lduchosal_semacli&metric=sqale_index)](https://sonarcloud.io/summary/new_code?id=lduchosal_semacli)
+
+A CLI tool to manage [Semaphore UI](https://semaphoreui.com) (ansible-semaphore) via its HTTP REST API.
+
+Designed for LLM/agent and automation use — deterministic commands, JSON output, exit codes.
+
+## Features
+
+- List projects, templates, inventories, environments
+- Launch and monitor tasks
+- Read task output
+- JSON output support
+- Bearer-token authentication (User Settings → API Tokens)
+
+## Installation
+
+```bash
+# From PyPI
+pip install semacli
+
+# From source
+pip install git+https://github.com/lduchosal/semacli.git
+
+# Development
+git clone https://github.com/lduchosal/semacli.git
+cd semacli
+pdm install
+```
+
+## Quick Start
+
+### Configuration
+
+Create `semacli.ini` in the current directory or `~/.semacli.ini`:
+
+```ini
+[semaphore]
+url = https://monitor.example.com/semaphore
+project = 1
+
+[auth]
+method = bearer_token
+bearer_token = your-api-token-here
+
+[settings]
+timeout = 30
+verify_ssl = true
+```
+
+Get a bearer token from the Semaphore UI: **User Settings → API Tokens → Create**.
+
+### Basic Usage
+
+```bash
+# Ping the API
+semacli ping
+
+# List projects
+semacli projects
+
+# (more commands wired in as the CLI grows)
+```
+
+## Output Options
+
+```bash
+# JSON output
+semacli projects --json
+
+# Verbose debugging
+semacli projects -v
+semacli projects -vv
+semacli projects -vvv
+```
+
+## Configuration Options
+
+### Authentication Methods
+
+#### Bearer token (recommended)
+
+```ini
+[semaphore]
+url = https://monitor.example.com/semaphore
+
+[auth]
+method = bearer_token
+bearer_token = your-api-token
+```
+
+#### Bearer token from environment variable
+
+```ini
+[semaphore]
+url = https://monitor.example.com/semaphore
+
+[auth]
+method = env_var
+env_var = SEMAPHORE_TOKEN
+```
+
+## Exit Codes
+
+| Code | Meaning |
+|------|---------|
+| 0 | Success |
+| 1 | General error |
+| 2 | Configuration error |
+| 3 | Authentication error |
+| 4 | API error |
+| 5 | Not found |
+
+## Development
+
+```bash
+# Clone and setup
+git clone https://github.com/lduchosal/semacli.git
+cd semacli
+pdm install -G dev
+
+# Run tests
+pdm test
+
+# Lint and format
+pdm lint
+pdm format
+
+# Type check
+pdm typecheck
+
+# Build
+pdm build
+```
+
+## Architecture
+
+```
+semacli/
+├── cli/                    # Click CLI interface
+│   ├── commands/           # Individual commands
+│   ├── decorators.py       # Common CLI options
+│   └── handlers.py         # Error handlers
+├── core/                   # Core business logic
+│   ├── client.py           # Semaphore HTTP client
+│   ├── config.py           # Configuration
+│   ├── exceptions.py       # Custom exceptions
+│   └── models.py           # Data models
+└── services/               # Business services
+```
+
+See [ARCHITECTURE.md](ARCHITECTURE.md) for the wiki classification map used by `ken wiki groom`.
+
+## License
+
+MIT License - see [LICENSE](LICENSE) for details.
+
+## Related Projects
+
+- [nagioscli](https://github.com/lduchosal/nagioscli) - sibling CLI for Nagios Core (model project)

semacli-0.1.2/README.md

@@ -0,0 +1,175 @@
+# semacli
+
+[![PyPI version](https://img.shields.io/pypi/v/semacli.svg)](https://pypi.org/project/semacli/)
+[![Python versions](https://img.shields.io/pypi/pyversions/semacli.svg)](https://pypi.org/project/semacli/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Build](https://github.com/lduchosal/semacli/actions/workflows/python-package.yml/badge.svg)](https://github.com/lduchosal/semacli/actions/workflows/python-package.yml)
+[![Publish](https://github.com/lduchosal/semacli/actions/workflows/python-publish.yml/badge.svg)](https://github.com/lduchosal/semacli/actions/workflows/python-publish.yml)
+[![codecov](https://codecov.io/gh/lduchosal/semacli/branch/main/graph/badge.svg)](https://codecov.io/gh/lduchosal/semacli)
+[![Docstring coverage](./interrogate_badge.svg)](./interrogate_badge.svg)
+[![Quality Gate Status](https://sonarcloud.io/api/project_badges/measure?project=lduchosal_semacli&metric=alert_status)](https://sonarcloud.io/summary/new_code?id=lduchosal_semacli)
+[![Maintainability Rating](https://sonarcloud.io/api/project_badges/measure?project=lduchosal_semacli&metric=sqale_rating)](https://sonarcloud.io/summary/new_code?id=lduchosal_semacli)
+[![Reliability Rating](https://sonarcloud.io/api/project_badges/measure?project=lduchosal_semacli&metric=reliability_rating)](https://sonarcloud.io/summary/new_code?id=lduchosal_semacli)
+[![Security Rating](https://sonarcloud.io/api/project_badges/measure?project=lduchosal_semacli&metric=security_rating)](https://sonarcloud.io/summary/new_code?id=lduchosal_semacli)
+[![Bugs](https://sonarcloud.io/api/project_badges/measure?project=lduchosal_semacli&metric=bugs)](https://sonarcloud.io/summary/new_code?id=lduchosal_semacli)
+[![Vulnerabilities](https://sonarcloud.io/api/project_badges/measure?project=lduchosal_semacli&metric=vulnerabilities)](https://sonarcloud.io/summary/new_code?id=lduchosal_semacli)
+[![Code Smells](https://sonarcloud.io/api/project_badges/measure?project=lduchosal_semacli&metric=code_smells)](https://sonarcloud.io/summary/new_code?id=lduchosal_semacli)
+[![Technical Debt](https://sonarcloud.io/api/project_badges/measure?project=lduchosal_semacli&metric=sqale_index)](https://sonarcloud.io/summary/new_code?id=lduchosal_semacli)
+
+A CLI tool to manage [Semaphore UI](https://semaphoreui.com) (ansible-semaphore) via its HTTP REST API.
+
+Designed for LLM/agent and automation use — deterministic commands, JSON output, exit codes.
+
+## Features
+
+- List projects, templates, inventories, environments
+- Launch and monitor tasks
+- Read task output
+- JSON output support
+- Bearer-token authentication (User Settings → API Tokens)
+
+## Installation
+
+```bash
+# From PyPI
+pip install semacli
+
+# From source
+pip install git+https://github.com/lduchosal/semacli.git
+
+# Development
+git clone https://github.com/lduchosal/semacli.git
+cd semacli
+pdm install
+```
+
+## Quick Start
+
+### Configuration
+
+Create `semacli.ini` in the current directory or `~/.semacli.ini`:
+
+```ini
+[semaphore]
+url = https://monitor.example.com/semaphore
+project = 1
+
+[auth]
+method = bearer_token
+bearer_token = your-api-token-here
+
+[settings]
+timeout = 30
+verify_ssl = true
+```
+
+Get a bearer token from the Semaphore UI: **User Settings → API Tokens → Create**.
+
+### Basic Usage
+
+```bash
+# Ping the API
+semacli ping
+
+# List projects
+semacli projects
+
+# (more commands wired in as the CLI grows)
+```
+
+## Output Options
+
+```bash
+# JSON output
+semacli projects --json
+
+# Verbose debugging
+semacli projects -v
+semacli projects -vv
+semacli projects -vvv
+```
+
+## Configuration Options
+
+### Authentication Methods
+
+#### Bearer token (recommended)
+
+```ini
+[semaphore]
+url = https://monitor.example.com/semaphore
+
+[auth]
+method = bearer_token
+bearer_token = your-api-token
+```
+
+#### Bearer token from environment variable
+
+```ini
+[semaphore]
+url = https://monitor.example.com/semaphore
+
+[auth]
+method = env_var
+env_var = SEMAPHORE_TOKEN
+```
+
+## Exit Codes
+
+| Code | Meaning |
+|------|---------|
+| 0 | Success |
+| 1 | General error |
+| 2 | Configuration error |
+| 3 | Authentication error |
+| 4 | API error |
+| 5 | Not found |
+
+## Development
+
+```bash
+# Clone and setup
+git clone https://github.com/lduchosal/semacli.git
+cd semacli
+pdm install -G dev
+
+# Run tests
+pdm test
+
+# Lint and format
+pdm lint
+pdm format
+
+# Type check
+pdm typecheck
+
+# Build
+pdm build
+```
+
+## Architecture
+
+```
+semacli/
+├── cli/                    # Click CLI interface
+│   ├── commands/           # Individual commands
+│   ├── decorators.py       # Common CLI options
+│   └── handlers.py         # Error handlers
+├── core/                   # Core business logic
+│   ├── client.py           # Semaphore HTTP client
+│   ├── config.py           # Configuration
+│   ├── exceptions.py       # Custom exceptions
+│   └── models.py           # Data models
+└── services/               # Business services
+```
+
+See [ARCHITECTURE.md](ARCHITECTURE.md) for the wiki classification map used by `ken wiki groom`.
+
+## License
+
+MIT License - see [LICENSE](LICENSE) for details.
+
+## Related Projects
+
+- [nagioscli](https://github.com/lduchosal/nagioscli) - sibling CLI for Nagios Core (model project)

semacli-0.1.2/pyproject.toml

@@ -0,0 +1,178 @@
+[build-system]
+requires = [
+    "pdm-backend",
+]
+build-backend = "pdm.backend"
+
+[project]
+name = "semacli"
+dynamic = []
+authors = [
+    { name = "lduchosal", email = "lduchosal@github.com" },
+]
+description = "A CLI tool to manage Semaphore UI (ansible-semaphore) via HTTP REST API"
+readme = "README.md"
+requires-python = ">=3.10"
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: System Administrators",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: System :: Systems Administration",
+]
+keywords = [
+    "semaphore",
+    "ansible",
+    "cli",
+    "api",
+    "devops",
+]
+dependencies = [
+    "click>=8.0,<9.0",
+]
+version = "0.1.2"
+
+[project.license]
+text = "MIT"
+
+[project.urls]
+Homepage = "https://github.com/lduchosal/semacli"
+"Bug Reports" = "https://github.com/lduchosal/semacli/issues"
+Source = "https://github.com/lduchosal/semacli"
+Documentation = "https://github.com/lduchosal/semacli/blob/main/README.md"
+
+[project.scripts]
+semacli = "semacli.cli:main"
+
+[tool.pdm]
+distribution = true
+
+[tool.pdm.dev-dependencies]
+dev = [
+    "pytest>=6.0",
+    "pytest-cov>=2.0",
+    "black>=21.0",
+    "mypy>=0.800",
+    "ruff>=0.1.0",
+    "pdm>=2.0.0",
+    "pdm-bump",
+    "interrogate>=1.7.0",
+]
+
+[tool.pdm.version]
+source = "file"
+path = "semacli/__init__.py"
+
+[tool.pdm.scripts]
+format = "ruff format"
+typecheck = "mypy semacli/"
+build = "python -m build"
+install = "pdm install"
+install-dev = "pdm install -G dev"
+clihelp = "semacli --help"
+test = "env PYTHONPATH=src python -m pytest tests/ -v --cov=semacli --cov-report=term-missing"
+test-quick = "env PYTHONPATH=src python -m pytest tests/ --tb=no -q"
+test-unit = "env PYTHONPATH=src python -m pytest tests/unit/ -v"
+test-integration = "env PYTHONPATH=src python -m pytest tests/integration/ -v"
+test-cov = "env PYTHONPATH=src python -m pytest tests/ -v --cov=semacli --cov-report=html --cov-report=term-missing"
+lint = "ruff check semacli/ tests/"
+lint-fix = "ruff check --fix semacli/ tests/"
+format-check = "black --check semacli/ tests/"
+interrogate = "interrogate semacli/"
+test-cov-xml = "env PYTHONPATH=src python -m pytest tests/ --cov=semacli --cov-report=xml --cov-report=term --cov-fail-under=80"
+check = [
+    "lint",
+    "format-check",
+    "typecheck",
+    "test",
+]
+clean = "rm -rf .coverage htmlcov/ .pytest_cache/ __pycache__/ semacli/__pycache__/"
+version-patch = "pdm bump patch"
+version-minor = "pdm bump minor"
+version-major = "pdm bump major"
+
+[tool.pdm.scripts.cli]
+composite = [
+    "clihelp",
+]
+
+[tool.pdm.scripts.all]
+composite = [
+    "install",
+    "format",
+    "build",
+    "test",
+    "cli",
+]
+
+[tool.black]
+line-length = 100
+target-version = [
+    "py310",
+]
+
+[tool.mypy]
+python_version = "3.10"
+warn_return_any = true
+warn_unused_configs = true
+disallow_untyped_defs = true
+disallow_incomplete_defs = true
+check_untyped_defs = true
+disallow_untyped_decorators = false
+no_implicit_optional = true
+warn_redundant_casts = true
+warn_unused_ignores = true
+warn_no_return = true
+warn_unreachable = true
+strict_equality = true
+ignore_missing_imports = true
+
+[tool.pytest.ini_options]
+testpaths = [
+    "tests",
+]
+python_files = "test_*.py"
+python_classes = "Test*"
+python_functions = "test_*"
+addopts = "-v"
+
+[tool.pdm-bump]
+version-files = [
+    "semacli/__init__.py:__version__",
+]
+
+[tool.ruff]
+line-length = 100
+target-version = "py310"
+
+[tool.ruff.lint]
+select = [
+    "E",
+    "F",
+    "W",
+    "I",
+    "UP",
+    "B",
+    "C4",
+]
+ignore = [
+    "E501",
+]
+
+[tool.interrogate]
+fail-under = 0
+ignore-init-method = true
+ignore-init-module = true
+exclude = [
+    "tests",
+    "docs",
+    "build",
+    "dist",
+]
+generate-badge = "."
+badge-format = "svg"

semacli-0.1.2/semacli/__init__.py

@@ -0,0 +1,5 @@
+"""semacli - A CLI tool to manage Semaphore UI via HTTP REST API."""
+
+__version__ = "0.1.2"
+__author__ = "lduchosal"
+__email__ = "lduchosal@github.com"

semacli-0.1.2/semacli/__main__.py

@@ -0,0 +1,6 @@
+"""Main entry point for semacli."""
+
+from semacli.cli import main
+
+if __name__ == "__main__":
+    main()

semacli-0.1.2/semacli/cli/__init__.py

@@ -0,0 +1,17 @@
+"""CLI module for semacli."""
+
+import click
+
+from semacli import __version__
+
+from .commands import register_all_commands
+
+
+@click.group()
+@click.version_option(version=__version__, prog_name="semacli")
+def main() -> None:
+    """Semaphore CLI - Manage Semaphore UI via HTTP REST API."""
+    pass
+
+
+register_all_commands(main)

semacli-0.1.2/semacli/cli/commands/__init__.py

@@ -0,0 +1,12 @@
+"""Commands package for CLI."""
+
+from typing import Any
+
+from .ping import register_ping_commands
+from .projects import register_projects_commands
+
+
+def register_all_commands(main_group: Any) -> None:
+    """Register all commands with the main CLI group."""
+    register_ping_commands(main_group)
+    register_projects_commands(main_group)

semacli-0.1.2/semacli/cli/commands/ping.py

@@ -0,0 +1,44 @@
+"""Ping command for CLI."""
+
+import json
+from typing import Any
+
+import click
+
+from semacli.core.client import SemaphoreClient
+from semacli.core.config import load_config
+
+from ..decorators import common_options, output_options
+from ..handlers import OutputFormatter, handle_error
+
+
+def register_ping_commands(main_group: Any) -> None:
+    """Register ping commands with the main CLI group."""
+
+    @main_group.command("ping")
+    @common_options
+    @output_options
+    def ping_cmd(
+        config: str,
+        verbose: int,
+        output_json: bool,
+        quiet: bool,
+    ) -> None:
+        """Ping the Semaphore API (GET /api/ping)."""
+        try:
+            cfg = load_config(config)
+            client = SemaphoreClient(cfg, verbose=verbose)
+
+            OutputFormatter.format_verbose(f"Pinging {cfg.url}", verbose)
+
+            pong = client.ping()
+
+            if output_json:
+                click.echo(json.dumps({"ping": pong}))
+            elif quiet:
+                pass
+            else:
+                click.echo(pong)
+
+        except Exception as e:
+            handle_error(e, verbose)

semacli-0.1.2/semacli/cli/commands/projects.py

@@ -0,0 +1,62 @@
+"""Projects command for CLI."""
+
+import json
+from typing import Any
+
+import click
+
+from semacli.core.client import SemaphoreClient
+from semacli.core.config import load_config
+from semacli.core.models import Project
+
+from ..decorators import common_options, output_options
+from ..handlers import OutputFormatter, handle_error
+
+
+def _emit_projects_json(projects: list[Project]) -> None:
+    output = [
+        {"id": p.id, "name": p.name, "created": p.created}
+        for p in projects
+    ]
+    click.echo(json.dumps(output, indent=2))
+
+
+def _emit_projects_text(projects: list[Project]) -> None:
+    if not projects:
+        click.echo("No projects found")
+        return
+    for p in projects:
+        click.echo(f"{p.id:>4}  {p.name}")
+    click.echo(f"\nTotal: {len(projects)} project(s)")
+
+
+def register_projects_commands(main_group: Any) -> None:
+    """Register projects commands with the main CLI group."""
+
+    @main_group.command("projects")
+    @common_options
+    @output_options
+    def projects_cmd(
+        config: str,
+        verbose: int,
+        output_json: bool,
+        quiet: bool,
+    ) -> None:
+        """List all Semaphore projects."""
+        try:
+            cfg = load_config(config)
+            client = SemaphoreClient(cfg, verbose=verbose)
+
+            OutputFormatter.format_verbose(f"Listing projects from {cfg.url}", verbose)
+
+            projects = client.get_projects()
+
+            if output_json:
+                _emit_projects_json(projects)
+            elif quiet:
+                pass
+            else:
+                _emit_projects_text(projects)
+
+        except Exception as e:
+            handle_error(e, verbose)

semacli-0.1.2/semacli/cli/decorators.py

@@ -0,0 +1,24 @@
+"""CLI decorators for semacli."""
+
+from collections.abc import Callable
+from typing import Any
+
+import click
+
+
+def common_options(func: Callable[..., Any]) -> Callable[..., Any]:
+    """Decorator for common CLI options."""
+    func = click.option(
+        "-c", "--config", default="semacli.ini", help="Configuration file path"
+    )(func)
+    func = click.option("-v", "--verbose", count=True, help="Increase verbosity")(func)
+
+    return func
+
+
+def output_options(func: Callable[..., Any]) -> Callable[..., Any]:
+    """Decorator for output format options."""
+    func = click.option("--json", "output_json", is_flag=True, help="Output as JSON")(func)
+    func = click.option("-q", "--quiet", is_flag=True, help="Minimal output")(func)
+
+    return func

semacli-0.1.2/semacli/cli/handlers.py

@@ -0,0 +1,53 @@
+"""Error handlers and formatters for click CLI."""
+
+import sys
+from typing import NoReturn
+
+import click
+
+from semacli.core.exceptions import (
+    AuthenticationError,
+    ConfigurationError,
+    NotFoundError,
+    SemaphoreAPIError,
+)
+
+
+def handle_error(error: Exception, verbose: int = 0) -> NoReturn:
+    """Handle exceptions and exit with appropriate code.
+
+    Exit codes:
+        1 - General error
+        2 - Configuration error
+        3 - Authentication error
+        4 - API error
+        5 - Not found
+    """
+    if verbose >= 1:
+        click.echo(f"DEBUG: {type(error).__name__}: {error}", err=True)
+
+    if isinstance(error, ConfigurationError):
+        click.echo(f"Configuration error: {error}", err=True)
+        sys.exit(2)
+    elif isinstance(error, AuthenticationError):
+        click.echo(f"Authentication error: {error}", err=True)
+        sys.exit(3)
+    elif isinstance(error, SemaphoreAPIError):
+        click.echo(f"API error: {error}", err=True)
+        sys.exit(4)
+    elif isinstance(error, NotFoundError):
+        click.echo(f"Not found: {error}", err=True)
+        sys.exit(5)
+    else:
+        click.echo(f"Error: {error}", err=True)
+        sys.exit(1)
+
+
+class OutputFormatter:
+    """Output formatters for different verbosity levels."""
+
+    @staticmethod
+    def format_verbose(message: str, verbose_level: int, min_level: int = 1) -> None:
+        """Print message if verbosity is high enough."""
+        if verbose_level >= min_level:
+            click.echo(f"DEBUG: {message}", err=True)

semacli-0.1.2/semacli/core/__init__.py

@@ -0,0 +1 @@
+"""Core module for semacli."""

semacli-0.1.2/semacli/core/client.py

@@ -0,0 +1,127 @@
+"""Semaphore HTTP API client."""
+
+import json
+import ssl
+import urllib.error
+import urllib.parse
+import urllib.request
+from typing import Any
+
+from .config import SemaphoreConfig
+from .exceptions import AuthenticationError, NotFoundError, SemaphoreAPIError
+from .models import Project
+
+
+class SemaphoreClient:
+    """HTTP client for Semaphore UI REST API."""
+
+    def __init__(self, config: SemaphoreConfig, verbose: int = 0) -> None:
+        self.config = config
+        self.verbose = verbose
+        self._opener: urllib.request.OpenerDirector | None = None
+
+    def _get_opener(self) -> urllib.request.OpenerDirector:
+        """Get or create HTTP opener with SSL handling."""
+        if self._opener is None:
+            handlers: list[urllib.request.BaseHandler] = []
+
+            if not self.config.verify_ssl:
+                # Opt-in insecure mode for self-signed certs.
+                ssl_context = ssl.create_default_context()
+                ssl_context.check_hostname = False  # NOSONAR: explicit user opt-in via verify_ssl=False
+                ssl_context.verify_mode = ssl.CERT_NONE  # NOSONAR: explicit user opt-in via verify_ssl=False
+                handlers.append(urllib.request.HTTPSHandler(context=ssl_context))
+
+            self._opener = urllib.request.build_opener(*handlers)
+
+        return self._opener
+
+    def _build_request(
+        self,
+        endpoint: str,
+        method: str = "GET",
+        params: dict[str, str] | None = None,
+        body: dict[str, Any] | None = None,
+        require_auth: bool = True,
+    ) -> urllib.request.Request:
+        url = f"{self.config.url}/api/{endpoint.lstrip('/')}"
+        if params:
+            url = f"{url}?{urllib.parse.urlencode(params)}"
+
+        if self.verbose >= 2:
+            print(f"DEBUG: {method} {url}")
+
+        data: bytes | None = None
+        request = urllib.request.Request(url, method=method)
+
+        if body is not None:
+            data = json.dumps(body).encode("utf-8")
+            request.add_header("Content-Type", "application/json")
+            request.data = data
+
+        if require_auth:
+            if not self.config.bearer_token:
+                raise AuthenticationError("No bearer_token configured")
+            request.add_header("Authorization", f"Bearer {self.config.bearer_token}")
+
+        request.add_header("Accept", "application/json")
+        return request
+
+    def _request(
+        self,
+        endpoint: str,
+        method: str = "GET",
+        params: dict[str, str] | None = None,
+        body: dict[str, Any] | None = None,
+        require_auth: bool = True,
+    ) -> Any:
+        """Make HTTP request to Semaphore API and return parsed JSON (or raw text)."""
+        request = self._build_request(endpoint, method, params, body, require_auth)
+
+        try:
+            response = self._get_opener().open(request, timeout=self.config.timeout)
+            content = response.read().decode("utf-8")
+
+            if self.verbose >= 3:
+                print(f"DEBUG: Response: {content[:500]}")
+
+            if not content:
+                return None
+            try:
+                return json.loads(content)
+            except json.JSONDecodeError:
+                return content
+
+        except urllib.error.HTTPError as e:
+            if e.code in (401, 403):
+                raise AuthenticationError(f"HTTP {e.code}: {e.reason}") from e
+            if e.code == 404:
+                raise NotFoundError(f"HTTP 404: {endpoint}") from e
+            raise SemaphoreAPIError(f"HTTP {e.code}: {e.reason}") from e
+        except urllib.error.URLError as e:
+            raise SemaphoreAPIError(f"Connection error: {e.reason}") from e
+
+    def ping(self) -> str:
+        """GET /api/ping — does not require authentication."""
+        result = self._request("ping", require_auth=False)
+        if isinstance(result, str):
+            return result.strip()
+        return str(result)
+
+    def get_projects(self) -> list[Project]:
+        """GET /api/projects — list all projects visible to the token."""
+        data = self._request("projects")
+        if not isinstance(data, list):
+            raise SemaphoreAPIError("Unexpected response format for /projects")
+        return [self._parse_project(item) for item in data]
+
+    @staticmethod
+    def _parse_project(data: dict[str, Any]) -> Project:
+        return Project(
+            id=int(data.get("id", 0)),
+            name=str(data.get("name", "")),
+            created=str(data.get("created", "")),
+            alert=bool(data.get("alert", False)),
+            alert_chat=str(data.get("alert_chat", "")),
+            max_parallel_tasks=int(data.get("max_parallel_tasks", 0)),
+        )

semacli-0.1.2/semacli/core/config.py

@@ -0,0 +1,111 @@
+"""Configuration management for semacli."""
+
+import configparser
+import os
+from dataclasses import dataclass
+from pathlib import Path
+
+from .exceptions import ConfigurationError
+
+
+@dataclass
+class SemaphoreConfig:
+    """Semaphore connection configuration."""
+
+    url: str
+    bearer_token: str | None = None
+    project: int | None = None
+    timeout: int = 30
+    verify_ssl: bool = True
+
+
+def load_config(config_path: str = "semacli.ini") -> SemaphoreConfig:
+    """Load configuration from file.
+
+    Raises:
+        ConfigurationError: If configuration is invalid
+    """
+    config = configparser.ConfigParser(interpolation=None)
+
+    config_file = _find_config_file(config_path)
+
+    if not config_file or not os.path.exists(config_file):
+        raise ConfigurationError(f"Configuration file not found: {config_path}")
+
+    config.read(config_file)
+
+    return _parse_config(config)
+
+
+def _find_config_file(config_path: str) -> str | None:
+    """Find configuration file in standard locations.
+
+    Search order:
+    1. Absolute path (if provided)
+    2. Current directory
+    3. User home directory (~/.semacli.ini)
+    4. /usr/local/etc/semacli.ini
+    """
+    if os.path.isabs(config_path):
+        return config_path
+
+    current_dir = Path.cwd() / config_path
+    if current_dir.exists():
+        return str(current_dir)
+
+    home_dir = Path.home() / f".{config_path}"
+    if home_dir.exists():
+        return str(home_dir)
+
+    system_config = Path("/usr/local/etc") / config_path
+    if system_config.exists():
+        return str(system_config)
+
+    return config_path
+
+
+def _parse_config(config: configparser.ConfigParser) -> SemaphoreConfig:
+    """Parse configuration into SemaphoreConfig object."""
+    if "semaphore" not in config:
+        raise ConfigurationError("Missing [semaphore] section in configuration")
+
+    sema_section = config["semaphore"]
+
+    url = sema_section.get("url")
+    if not url:
+        raise ConfigurationError("Missing 'url' in [semaphore] section")
+
+    project_raw = sema_section.get("project")
+    project = int(project_raw) if project_raw else None
+
+    bearer_token: str | None = None
+
+    if "auth" in config:
+        auth_section = config["auth"]
+        method = auth_section.get("method", "bearer_token")
+
+        if method == "bearer_token":
+            bearer_token = auth_section.get("bearer_token")
+        elif method == "env_var":
+            env_var = auth_section.get("env_var", "SEMAPHORE_TOKEN")
+            bearer_token = os.environ.get(env_var)
+        else:
+            raise ConfigurationError(f"Unknown auth method: {method}")
+    else:
+        bearer_token = sema_section.get("bearer_token")
+
+    timeout = 30
+    verify_ssl = True
+
+    if "settings" in config:
+        settings_section = config["settings"]
+        timeout = settings_section.getint("timeout", 30)
+        verify_ssl = settings_section.getboolean("verify_ssl", True)
+
+    return SemaphoreConfig(
+        url=url.rstrip("/"),
+        bearer_token=bearer_token,
+        project=project,
+        timeout=timeout,
+        verify_ssl=verify_ssl,
+    )

semacli-0.1.2/semacli/core/exceptions.py

@@ -0,0 +1,31 @@
+"""Custom exceptions for semacli."""
+
+
+class SemaCliError(Exception):
+    """Base exception for semacli."""
+
+    pass
+
+
+class ConfigurationError(SemaCliError):
+    """Raised when there's a configuration error."""
+
+    pass
+
+
+class AuthenticationError(SemaCliError):
+    """Raised when there's an authentication error."""
+
+    pass
+
+
+class SemaphoreAPIError(SemaCliError):
+    """Raised when there's an error with the Semaphore API."""
+
+    pass
+
+
+class NotFoundError(SemaCliError):
+    """Raised when a resource is not found."""
+
+    pass

semacli-0.1.2/semacli/core/models.py

@@ -0,0 +1,69 @@
+"""Data models for semacli."""
+
+from dataclasses import dataclass
+
+
+@dataclass
+class Project:
+    """A Semaphore project."""
+
+    id: int
+    name: str
+    created: str = ""
+    alert: bool = False
+    alert_chat: str = ""
+    max_parallel_tasks: int = 0
+
+
+@dataclass
+class Template:
+    """A Semaphore task template."""
+
+    id: int
+    project_id: int
+    name: str
+    playbook: str = ""
+    inventory_id: int = 0
+    repository_id: int = 0
+    environment_id: int = 0
+    description: str = ""
+
+
+@dataclass
+class Task:
+    """A Semaphore task (a run of a template)."""
+
+    id: int
+    template_id: int
+    status: str = ""
+    debug: bool = False
+    dry_run: bool = False
+    playbook: str = ""
+    environment: str = ""
+    created: str = ""
+    start: str = ""
+    end: str = ""
+
+
+@dataclass
+class Inventory:
+    """A Semaphore inventory."""
+
+    id: int
+    project_id: int
+    name: str
+    type: str = ""
+    inventory: str = ""
+    ssh_key_id: int = 0
+    become_key_id: int = 0
+
+
+@dataclass
+class Environment:
+    """A Semaphore environment (extra vars + secrets)."""
+
+    id: int
+    project_id: int
+    name: str
+    password: str = ""
+    json: str = ""

semacli-0.1.2/semacli/services/__init__.py

@@ -0,0 +1 @@
+"""Services module for semacli."""

semacli-0.1.2/tests/unit/test_config.py

@@ -0,0 +1,84 @@
+"""Tests for semacli.core.config."""
+
+import textwrap
+from pathlib import Path
+
+import pytest
+
+from semacli.core.config import SemaphoreConfig, load_config
+from semacli.core.exceptions import ConfigurationError
+
+
+def _write_ini(tmp_path: Path, body: str) -> Path:
+    path = tmp_path / "semacli.ini"
+    path.write_text(textwrap.dedent(body).lstrip())
+    return path
+
+
+class TestLoadConfig:
+    def test_missing_file_raises(self, tmp_path: Path) -> None:
+        with pytest.raises(ConfigurationError):
+            load_config(str(tmp_path / "nope.ini"))
+
+    def test_bearer_token_method(self, tmp_path: Path) -> None:
+        ini = _write_ini(
+            tmp_path,
+            """
+            [semaphore]
+            url = https://semaphore.example/
+
+            [auth]
+            method = bearer_token
+            bearer_token = abc123
+
+            [settings]
+            timeout = 42
+            verify_ssl = false
+            """,
+        )
+        cfg = load_config(str(ini))
+        assert isinstance(cfg, SemaphoreConfig)
+        assert cfg.url == "https://semaphore.example"
+        assert cfg.bearer_token == "abc123"
+        assert cfg.timeout == 42
+        assert cfg.verify_ssl is False
+
+    def test_env_var_method(self, tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> None:
+        monkeypatch.setenv("SEMA_TOKEN_X", "from-env")
+        ini = _write_ini(
+            tmp_path,
+            """
+            [semaphore]
+            url = https://semaphore.example
+
+            [auth]
+            method = env_var
+            env_var = SEMA_TOKEN_X
+            """,
+        )
+        cfg = load_config(str(ini))
+        assert cfg.bearer_token == "from-env"
+
+    def test_missing_url_raises(self, tmp_path: Path) -> None:
+        ini = _write_ini(
+            tmp_path,
+            """
+            [semaphore]
+            project = 1
+            """,
+        )
+        with pytest.raises(ConfigurationError):
+            load_config(str(ini))
+
+    def test_project_parsed_as_int(self, tmp_path: Path) -> None:
+        ini = _write_ini(
+            tmp_path,
+            """
+            [semaphore]
+            url = https://semaphore.example
+            project = 7
+            bearer_token = t
+            """,
+        )
+        cfg = load_config(str(ini))
+        assert cfg.project == 7