feat: implement interactive o2switch cli

Author: MNametissa

.gitignore

@@ -0,0 +1,9 @@
+.venv/
+__pycache__/
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+.coverage
+*.egg-info/
+.env
+

README.md

@@ -2,12 +2,50 @@
 
 CLI interactif pour gerer domaines, sous-domaines cPanel et enregistrements DNS sur un hebergement o2switch/cPanel.
 
-## Specs
+## Installation
 
-Le pack de specifications projet est dans [`docs/specs/README.md`](docs/specs/README.md).
+```bash
+python3 -m venv .venv
+.venv/bin/python -m pip install -e '.[dev]'
+```
+
+## Configuration
 
 Convention de nommage:
 
 - binaire CLI: `o2switch-cli`
 - package Python: `o2switch_cli`
 - variables d'environnement: `O2SWITCH_CLI_*`
+
+Variables attendues:
+
+```bash
+export O2SWITCH_CLI_CPANEL_HOST=saule.o2switch.net
+export O2SWITCH_CLI_CPANEL_USER=mon_user
+export O2SWITCH_CLI_CPANEL_TOKEN=mon_token
+```
+
+## Usage
+
+```bash
+.venv/bin/o2switch-cli --help
+.venv/bin/o2switch-cli domains list
+.venv/bin/o2switch-cli dns upsert --host odoo-staging.ginutech.com --ip 203.0.113.25
+.venv/bin/o2switch-cli dns delete --host odoo-staging.ginutech.com --dry-run
+.venv/bin/o2switch-cli subdomains create --root ginutech.com --label odoo-staging --ip 203.0.113.25
+.venv/bin/o2switch-cli config show --json
+```
+
+Sans sous-commande, le binaire ouvre le mode interactif si le terminal est TTY.
+
+## Development
+
+```bash
+.venv/bin/ruff check .
+.venv/bin/ruff format .
+.venv/bin/pytest
+```
+
+## Specs
+
+Le pack de specifications projet est dans [`docs/specs/README.md`](docs/specs/README.md).

o2switch_cli/__init__.py

@@ -0,0 +1,3 @@
+__all__ = ["__version__"]
+
+__version__ = "0.1.0"

o2switch_cli/__main__.py

@@ -0,0 +1,4 @@
+from o2switch_cli.cli.main import run
+
+if __name__ == "__main__":
+    run()

o2switch_cli/cli/__init__.py

@@ -0,0 +1,3 @@
+from o2switch_cli.cli.main import app, run
+
+__all__ = ["app", "run"]

o2switch_cli/cli/config_cmd.py

@@ -0,0 +1,35 @@
+from __future__ import annotations
+
+import typer
+
+from o2switch_cli.cli.helpers import run_guarded
+from o2switch_cli.cli.ui import TerminalUI
+from o2switch_cli.config.settings import settings_summary
+
+app = typer.Typer(help="Inspect active configuration and API reachability.", rich_markup_mode="rich")
+
+
+@app.command("show")
+def show_config(ctx: typer.Context) -> None:
+    def action(app_context):
+        ui = TerminalUI(app_context.console, app_context.output_format)
+        ui.print_mapping("Active Configuration", settings_summary(app_context.settings))
+
+    run_guarded(ctx, action)
+
+
+@app.command("test")
+def test_config(ctx: typer.Context) -> None:
+    def action(app_context):
+        ui = TerminalUI(app_context.console, app_context.output_format)
+        domains = app_context.runtime().domains.list_domains()
+        ui.print_mapping(
+            "API Access",
+            {
+                "cpanel_host": app_context.settings.cpanel_host,
+                "cpanel_user": app_context.settings.cpanel_user,
+                "reachable_domains": len(domains),
+            },
+        )
+
+    run_guarded(ctx, action)

o2switch_cli/cli/context.py

@@ -0,0 +1,99 @@
+from __future__ import annotations
+
+import sys
+from dataclasses import dataclass, field
+
+import typer
+from rich.console import Console
+
+from o2switch_cli.config.settings import AppSettings
+from o2switch_cli.core.audit import AuditService
+from o2switch_cli.core.auth import ensure_credentials
+from o2switch_cli.core.cpanel_client import CpanelClient
+from o2switch_cli.core.dns_service import DNSService
+from o2switch_cli.core.domain_service import DomainService
+from o2switch_cli.core.errors import CliAppError
+from o2switch_cli.core.subdomain_service import SubdomainService
+from o2switch_cli.infra.resolver import DNSResolver
+
+
+@dataclass(slots=True)
+class RuntimeServices:
+    client: CpanelClient
+    domains: DomainService
+    dns: DNSService
+    subdomains: SubdomainService
+
+
+@dataclass(slots=True)
+class AppContext:
+    settings: AppSettings
+    output_format: str
+    dry_run: bool
+    force: bool
+    yes: bool
+    verbose: bool
+    verify_after_mutation: bool
+    allow_prompt: bool
+    console: Console = field(default_factory=lambda: Console())
+    _runtime: RuntimeServices | None = None
+
+    def runtime(self) -> RuntimeServices:
+        if self._runtime is None:
+            self.settings = ensure_credentials(self.settings, allow_prompt=self.allow_prompt)
+            client = CpanelClient.from_settings(self.settings)
+            audit = AuditService(
+                audit_log_path=self.settings.audit_log_path,
+                actor=self.settings.cpanel_user or "system",
+            )
+            domains = DomainService(client)
+            resolver = DNSResolver()
+            dns = DNSService(client, domains, resolver, audit)
+            subdomains = SubdomainService(
+                client,
+                domains,
+                dns,
+                audit,
+                self.settings.reserved_labels,
+            )
+            self._runtime = RuntimeServices(client=client, domains=domains, dns=dns, subdomains=subdomains)
+        return self._runtime
+
+    def shutdown(self) -> None:
+        if self._runtime is not None:
+            self._runtime.client.close()
+
+
+def build_context(
+    *,
+    settings: AppSettings,
+    json_output: bool,
+    dry_run: bool,
+    force: bool,
+    yes: bool,
+    verbose: bool,
+    no_verify: bool,
+) -> AppContext:
+    return AppContext(
+        settings=settings,
+        output_format="json" if json_output else settings.output_format,
+        dry_run=dry_run,
+        force=force,
+        yes=yes,
+        verbose=verbose,
+        verify_after_mutation=settings.verify_dns_after_mutation and not no_verify,
+        allow_prompt=sys.stdin.isatty() and not json_output,
+    )
+
+
+def get_app_context(ctx: typer.Context) -> AppContext:
+    if not isinstance(ctx.obj, AppContext):
+        raise RuntimeError("Application context was not initialized.")
+    return ctx.obj
+
+
+def raise_for_error(app_context: AppContext, error: CliAppError) -> None:
+    from o2switch_cli.cli.ui import TerminalUI
+
+    TerminalUI(app_context.console, app_context.output_format).print_error(error.to_envelope())
+    raise typer.Exit(error.exit_code)

o2switch_cli/cli/dns.py

@@ -0,0 +1,80 @@
+from __future__ import annotations
+
+import typer
+
+from o2switch_cli.cli.helpers import confirm_plan, run_guarded
+from o2switch_cli.cli.ui import TerminalUI
+
+app = typer.Typer(help="Search, upsert, delete, and verify DNS records.", rich_markup_mode="rich")
+
+
+@app.command("search")
+def search_dns(ctx: typer.Context, term: str) -> None:
+    def action(app_context):
+        ui = TerminalUI(app_context.console, app_context.output_format)
+        records = app_context.runtime().dns.search(term)
+        ui.print_records(records)
+
+    run_guarded(ctx, action)
+
+
+@app.command("upsert")
+def upsert_dns(
+    ctx: typer.Context,
+    host: str = typer.Option(..., "--host"),
+    ip: str = typer.Option(..., "--ip"),
+    ttl: int | None = typer.Option(None, "--ttl"),
+) -> None:
+    def action(app_context):
+        ui = TerminalUI(app_context.console, app_context.output_format)
+        effective_ttl = ttl or app_context.settings.default_ttl
+        zone, _, _, plan = app_context.runtime().dns.plan_upsert_a_record(
+            host, ip, effective_ttl, force=app_context.force
+        )
+        if not confirm_plan(app_context, ui, plan, zone=zone):
+            ui.print_info("Mutation cancelled.")
+            return
+        _, result = app_context.runtime().dns.upsert_a_record(
+            host,
+            ip,
+            effective_ttl,
+            dry_run=app_context.dry_run,
+            force=app_context.force,
+            verify=app_context.verify_after_mutation,
+        )
+        ui.print_result(result)
+
+    run_guarded(ctx, action)
+
+
+@app.command("delete")
+def delete_dns(ctx: typer.Context, host: str = typer.Option(..., "--host")) -> None:
+    def action(app_context):
+        ui = TerminalUI(app_context.console, app_context.output_format)
+        zone, _, _, plan = app_context.runtime().dns.plan_delete_a_record(host, force=app_context.force)
+        if not confirm_plan(app_context, ui, plan, zone=zone):
+            ui.print_info("Mutation cancelled.")
+            return
+        _, result = app_context.runtime().dns.delete_a_record(
+            host,
+            dry_run=app_context.dry_run,
+            force=app_context.force,
+            verify=app_context.verify_after_mutation,
+        )
+        ui.print_result(result)
+
+    run_guarded(ctx, action)
+
+
+@app.command("verify")
+def verify_dns(
+    ctx: typer.Context,
+    host: str = typer.Option(..., "--host"),
+    ip: str | None = typer.Option(None, "--ip"),
+) -> None:
+    def action(app_context):
+        ui = TerminalUI(app_context.console, app_context.output_format)
+        result = app_context.runtime().dns.verify_record(host, ip)
+        ui.print_result(result)
+
+    run_guarded(ctx, action)

o2switch_cli/cli/domains.py

@@ -0,0 +1,28 @@
+from __future__ import annotations
+
+import typer
+
+from o2switch_cli.cli.helpers import run_guarded
+from o2switch_cli.cli.ui import TerminalUI
+
+app = typer.Typer(help="List and search account domains.", rich_markup_mode="rich")
+
+
+@app.command("list")
+def list_domains(ctx: typer.Context) -> None:
+    def action(app_context):
+        ui = TerminalUI(app_context.console, app_context.output_format)
+        domains = app_context.runtime().domains.list_domains()
+        ui.print_domains(domains)
+
+    run_guarded(ctx, action)
+
+
+@app.command("search")
+def search_domains(ctx: typer.Context, term: str) -> None:
+    def action(app_context):
+        ui = TerminalUI(app_context.console, app_context.output_format)
+        domains = app_context.runtime().domains.search(term)
+        ui.print_domains(domains)
+
+    run_guarded(ctx, action)

o2switch_cli/cli/helpers.py

@@ -0,0 +1,34 @@
+from __future__ import annotations
+
+from collections.abc import Callable
+from typing import TypeVar
+
+import typer
+
+from o2switch_cli.cli.context import AppContext, get_app_context, raise_for_error
+from o2switch_cli.cli.ui import TerminalUI
+from o2switch_cli.core.errors import CliAppError, TransportAppError
+from o2switch_cli.core.models import MutationPlan, PlannedAction
+
+T = TypeVar("T")
+
+
+def run_guarded(ctx: typer.Context, action: Callable[[AppContext], T]) -> T:
+    app_context = get_app_context(ctx)
+    try:
+        return action(app_context)
+    except CliAppError as error:
+        raise_for_error(app_context, error)
+    except typer.Exit:
+        raise
+    except Exception as error:  # pragma: no cover
+        raise_for_error(app_context, TransportAppError("runtime", str(error)))
+    raise RuntimeError("unreachable")
+
+
+def confirm_plan(app_context: AppContext, ui: TerminalUI, plan: MutationPlan, *, zone: str | None = None) -> bool:
+    if ui.output_format != "json":
+        ui.print_plan(plan, zone=zone)
+    if app_context.dry_run or app_context.yes or plan.planned_action is PlannedAction.NOOP:
+        return True
+    return ui.confirm("Apply this change?")