charisma-cli 0.1.2__py3-none-any.whl

charisma_cli/__init__.py

@@ -0,0 +1,3 @@
+"""charisma-cli: Stream allure results to Charisma in real time."""
+
+__version__ = "0.1.2"

charisma_cli/config.py

@@ -0,0 +1,86 @@
+"""Configuration dataclass with env var + CLI flag resolution."""
+
+import os
+from dataclasses import dataclass
+
+import click
+
+
+@dataclass
+class Config:
+    """Resolved configuration for charismactl.
+
+    Fields are populated via from_env() which merges CLI flag overrides
+    with environment variable fallbacks.
+    """
+
+    endpoint: str
+    token: str
+    project: str
+    results_dir: str
+    silent: bool
+    skip_too_big: bool
+    drain_timeout: int
+    build_id: str | None
+    commit_sha: str | None
+    branch: str | None
+
+    @classmethod
+    def from_env(
+        cls,
+        *,
+        endpoint: str | None = None,
+        token: str | None = None,
+        project: str | None = None,
+        results: str | None = None,
+        silent: bool = False,
+        skip_too_big: bool = False,
+        drain_timeout: int = 30,
+    ) -> "Config":
+        """Build Config by resolving CLI flags over environment variables.
+
+        Resolution order: CLI flag (if not None) > env var > default.
+
+        Args:
+            endpoint: --endpoint flag override
+            token: --token flag override
+            project: --project flag override
+            results: --results flag override
+            silent: --silent flag
+            skip_too_big: --skip-too-big flag
+            drain_timeout: drain timeout in seconds
+
+        Returns:
+            Fully resolved Config instance.
+
+        Raises:
+            click.UsageError: If required fields (endpoint, token) are missing.
+        """
+        resolved_endpoint = (endpoint or os.getenv("CHARISMA_ENDPOINT", "")).strip()
+        resolved_token = (token or os.getenv("CHARISMA_TOKEN", "")).strip()
+        resolved_project = (project or os.getenv("CHARISMA_PROJECT_ID", "")).strip()
+        resolved_results = results or os.getenv("CHARISMA_RESULTS", "allure-results")
+
+        if not resolved_endpoint:
+            raise click.UsageError(
+                "Missing required configuration: endpoint. "
+                "Set CHARISMA_ENDPOINT or pass --endpoint."
+            )
+        if not resolved_token:
+            raise click.UsageError(
+                "Missing required configuration: token. "
+                "Set CHARISMA_TOKEN or pass --token."
+            )
+
+        return cls(
+            endpoint=resolved_endpoint,
+            token=resolved_token,
+            project=resolved_project,
+            results_dir=resolved_results,
+            silent=silent,
+            skip_too_big=skip_too_big,
+            drain_timeout=drain_timeout,
+            build_id=os.getenv("BUILD_ID"),
+            commit_sha=os.getenv("COMMIT_SHA"),
+            branch=os.getenv("BRANCH"),
+        )

charisma_cli/main.py

@@ -0,0 +1,206 @@
+"""CLI entry point for charismactl."""
+
+import signal
+import sys
+from pathlib import Path
+from queue import PriorityQueue
+
+import click
+
+from charisma_cli import __version__
+from charisma_cli.config import Config
+from charisma_cli.models import FileEvent
+from charisma_cli.subprocess_mgr import SubprocessManager
+from charisma_cli.uploader import Uploader
+from charisma_cli.watcher import ResultsWatcher, classify_file
+
+
+@click.group()
+@click.version_option(version=__version__, prog_name="charismactl")
+def cli() -> None:
+    """Stream allure test results to Charisma in real time."""
+
+
+def _resolve_config(
+    endpoint: str | None,
+    token: str | None,
+    project: str,
+    results: str,
+    silent: bool,
+    skip_too_big: bool,
+) -> Config:
+    """Resolve CLI config from flags + env vars. Re-raises UsageError on failure."""
+    return Config.from_env(
+        endpoint=endpoint,
+        token=token,
+        project=project,
+        results=results,
+        silent=silent,
+        skip_too_big=skip_too_big,
+    )
+
+
+def _open_launch_or_exit(uploader: Uploader, config: Config) -> str:
+    """Open a launch, handling failure based on silent mode.
+
+    Returns:
+        The launch ID on success.
+
+    Exits:
+        sys.exit(1) if non-silent and launch open fails.
+        Returns empty string if silent and launch fails (caller must handle).
+    """
+    launch_id = uploader.open_launch()
+    if launch_id is None:
+        if config.silent:
+            return ""
+        click.echo("Error: Failed to open launch. Exiting.", err=True)
+        sys.exit(1)
+    return launch_id
+
+
+def _print_summary(uploader: Uploader) -> None:
+    """Print the upload summary to stdout."""
+    summary = uploader.summary
+    click.echo(
+        f"Summary: results_sent={summary.results_sent}, "
+        f"results_failed={summary.results_failed}, "
+        f"attachments_sent={summary.attachments_sent}, "
+        f"attachments_skipped={summary.attachments_skipped}, "
+        f"containers_sent={summary.containers_sent}"
+    )
+
+
+@cli.command()
+@click.option("--endpoint", envvar="CHARISMA_ENDPOINT", default=None, help="Charisma API endpoint.")
+@click.option("--token", envvar="CHARISMA_TOKEN", default=None, help="Bearer token.")
+@click.option("--results", envvar="CHARISMA_RESULTS", default="allure-results", help="Allure results directory.")
+@click.option("--project", envvar="CHARISMA_PROJECT_ID", required=True, help="Project alias.")
+@click.option("--silent", is_flag=True, default=False, help="Don't fail if upload errors occur.")
+@click.option("--skip-too-big", is_flag=True, default=False, help="Skip result files larger than 2MB.")
+@click.argument("command", nargs=-1, required=True)
+def watch(
+    endpoint: str | None,
+    token: str | None,
+    results: str,
+    project: str,
+    silent: bool,
+    skip_too_big: bool,
+    command: tuple[str, ...],
+) -> None:
+    """Watch allure-results and stream to Charisma while running COMMAND.
+
+    Usage: charismactl watch --project my-project -- pytest -n 4 tests/
+    """
+    config = _resolve_config(endpoint, token, project, results, silent, skip_too_big)
+
+    queue: PriorityQueue[FileEvent] = PriorityQueue()
+    uploader = Uploader(config, queue)
+    uploader.configure_logging()
+
+    # Open launch (Uploader owns the client)
+    launch_id = _open_launch_or_exit(uploader, config)
+    if not launch_id:
+        # Silent degradation — run subprocess without uploads
+        mgr = SubprocessManager()
+        mgr.spawn(command)
+        sys.exit(mgr.wait())
+
+    # Start watcher + uploader consumer
+    watcher = ResultsWatcher(config.results_dir, queue, config)
+    watcher.start()
+    uploader.start()
+
+    # Spawn subprocess with signal forwarding
+    mgr = SubprocessManager()
+
+    def _forward_signal(sig: int, _frame: object) -> None:
+        mgr.forward_signal(sig)
+
+    try:
+        signal.signal(signal.SIGTERM, _forward_signal)
+    except (OSError, ValueError):
+        pass
+    try:
+        signal.signal(signal.SIGINT, _forward_signal)
+    except (OSError, ValueError):
+        pass
+
+    mgr.spawn(command)
+    exit_code = mgr.wait()
+
+    # After subprocess exits (crash or normal): flush debouncing files and scan
+    # for anything the watcher missed entirely. This prevents data loss when
+    # parallel test workers write results in bursts just before crash.
+    watcher.flush_pending()
+    watcher.final_scan()
+
+    # Drain and close — stop watcher AFTER drain so all files are processed
+    uploader.drain(timeout=config.drain_timeout)
+    watcher.stop()
+    uploader.stop()
+
+    uploader.ensure_client()
+    uploader.close_launch()
+    if uploader._client is not None:
+        uploader._client.close()
+        uploader._client = None
+
+    _print_summary(uploader)
+    sys.exit(exit_code)
+
+
+@cli.command()
+@click.option("--endpoint", envvar="CHARISMA_ENDPOINT", default=None, help="Charisma API endpoint.")
+@click.option("--token", envvar="CHARISMA_TOKEN", default=None, help="Bearer token.")
+@click.option("--results", envvar="CHARISMA_RESULTS", default="allure-results", help="Allure results directory.")
+@click.option("--project", envvar="CHARISMA_PROJECT_ID", required=True, help="Project alias.")
+@click.option("--silent", is_flag=True, default=False, help="Don't fail if upload errors occur.")
+@click.option("--skip-too-big", is_flag=True, default=False, help="Skip result files larger than 2MB.")
+def upload(
+    endpoint: str | None,
+    token: str | None,
+    results: str,
+    project: str,
+    silent: bool,
+    skip_too_big: bool,
+) -> None:
+    """Upload completed allure-results to Charisma (post-execution).
+
+    Usage: charismactl upload --project my-project --results allure-results
+    """
+    config = _resolve_config(endpoint, token, project, results, silent, skip_too_big)
+
+    queue: PriorityQueue[FileEvent] = PriorityQueue()
+    uploader = Uploader(config, queue)
+    uploader.configure_logging()
+
+    # Open launch
+    launch_id = _open_launch_or_exit(uploader, config)
+    if not launch_id:
+        click.echo("Warning: Failed to open launch. No results uploaded.", err=True)
+        sys.exit(0)
+
+    # Scan existing results directory
+    results_path = Path(config.results_dir)
+    if not results_path.exists():
+        click.echo(f"Error: Results directory '{config.results_dir}' does not exist.", err=True)
+        sys.exit(1)
+
+    for filepath in sorted(results_path.iterdir()):
+        if filepath.is_file():
+            category = classify_file(filepath.name)
+            if category is not None:
+                queue.put(FileEvent(path=filepath, category=category))
+
+    # Process and drain
+    uploader.start()
+    uploader.drain(timeout=config.drain_timeout)
+    uploader.stop()
+
+    # Close launch
+    uploader.ensure_client()
+    uploader.close_launch()
+    uploader.stop()
+
+    _print_summary(uploader)

charisma_cli/models.py

@@ -0,0 +1,76 @@
+"""Dataclasses for internal file events, parsed results, and upload statistics."""
+
+from dataclasses import dataclass, field
+from enum import IntEnum
+from pathlib import Path
+
+
+class FileCategory(IntEnum):
+    """File classification with priority ordering."""
+
+    RESULT = 0
+    CONTAINER = 1
+    ATTACHMENT = 2
+
+
+@dataclass
+class FileEvent:
+    """A file detected by the watcher, ready for processing."""
+
+    path: Path
+    category: FileCategory
+
+    def __lt__(self, other: "FileEvent") -> bool:
+        """Priority queue ordering — results first."""
+        return self.category < other.category
+
+
+@dataclass
+class CharismaResult:
+    """A single test result in Charisma streaming API format."""
+
+    testId: str  # from Allure historyId (stable across reruns)
+    outcome: str  # passed | failed | broken | skipped
+    duration_ms: int  # stop - start
+    name: str | None = None  # short test name
+    full_name: str | None = None  # Allure fullName (fully-qualified)
+    error_message: str | None = None
+    stack_trace: str | None = None
+    labels: list[dict[str, str]] = field(default_factory=list)
+    parameters: list[dict[str, str]] = field(default_factory=list)
+    started_at: int | None = None  # epoch ms
+    ended_at: int | None = None  # epoch ms
+    uuid: str | None = None  # Allure UUID (for attachment linkage)
+
+
+@dataclass
+class AttachmentRef:
+    """Reference to an attachment file discovered in a result."""
+
+    source: str  # filename in allure-results/
+    name: str  # human-readable name
+    mime_type: str  # content-type
+    result_uuid: str  # owning result UUID
+
+
+@dataclass
+class ContainerData:
+    """Parsed container with fixture steps and child references."""
+
+    uuid: str
+    name: str
+    children: list[str]  # result UUIDs
+    befores: list[dict]  # fixture step dicts
+    afters: list[dict]  # fixture step dicts
+    received_at: float = 0.0  # time.monotonic() for timeout tracking
+
+
+@dataclass
+class UploadSummary:
+    """Exit report statistics."""
+
+    results_sent: int = 0
+    results_failed: int = 0
+    attachments_sent: int = 0
+    attachments_skipped: int = 0
+    containers_sent: int = 0

charisma_cli/parser.py

@@ -0,0 +1,175 @@
+"""Allure JSON → Charisma API format transformation.
+
+Parses Allure result and container JSON files into internal dataclasses
+for streaming to the Charisma ingestion API.
+"""
+
+import json
+import logging
+from pathlib import Path
+
+from charisma_cli.models import AttachmentRef, CharismaResult, ContainerData
+
+logger = logging.getLogger(__name__)
+
+
+def map_allure_status(status: str) -> str:
+    """Map Allure status string to Charisma outcome.
+
+    Known statuses pass through unchanged: passed, failed, broken, skipped.
+    Unknown statuses also pass through unchanged (defensive behavior).
+
+    Args:
+        status: Allure status string.
+
+    Returns:
+        Charisma outcome string.
+    """
+    return status
+
+
+def parse_result_file(path: Path) -> CharismaResult | None:
+    """Parse an Allure result JSON file into a CharismaResult.
+
+    Args:
+        path: Path to the Allure result JSON file.
+
+    Returns:
+        CharismaResult if parsing succeeds, None if the file is missing,
+        unreadable, malformed JSON, or missing required fields.
+    """
+    try:
+        text = path.read_text(encoding="utf-8")
+    except (OSError, FileNotFoundError):
+        logger.warning("Cannot read result file: %s", path)
+        return None
+
+    try:
+        data = json.loads(text)
+    except (json.JSONDecodeError, ValueError):
+        logger.warning("Malformed JSON in result file: %s", path)
+        return None
+
+    if not isinstance(data, dict):
+        logger.warning("Result file is not a JSON object: %s", path)
+        return None
+
+    # Required fields
+    uuid = data.get("uuid")
+    start = data.get("start")
+    stop = data.get("stop")
+
+    if uuid is None or start is None or stop is None:
+        logger.warning("Result file missing required fields (uuid/start/stop): %s", path)
+        return None
+
+    # testId: prefer historyId, fallback to fullName
+    history_id = data.get("historyId")
+    full_name = data.get("fullName")
+    test_id = history_id or full_name
+
+    if test_id is None:
+        logger.warning("Result file missing both historyId and fullName: %s", path)
+        return None
+
+    # Compute duration
+    duration_ms = stop - start
+
+    # Status mapping
+    status = data.get("status", "")
+    outcome = map_allure_status(status)
+
+    # Status details
+    status_details = data.get("statusDetails") or {}
+    error_message = status_details.get("message")
+    stack_trace = status_details.get("trace")
+
+    # Labels and parameters default to empty lists
+    labels = data.get("labels", [])
+    parameters = data.get("parameters", [])
+
+    return CharismaResult(
+        testId=test_id,
+        outcome=outcome,
+        duration_ms=duration_ms,
+        name=data.get("name"),
+        full_name=full_name,
+        error_message=error_message,
+        stack_trace=stack_trace,
+        labels=labels,
+        parameters=parameters,
+        started_at=start,
+        ended_at=stop,
+        uuid=uuid,
+    )
+
+
+def parse_container_file(path: Path) -> ContainerData | None:
+    """Parse an Allure container JSON file into a ContainerData.
+
+    Args:
+        path: Path to the Allure container JSON file.
+
+    Returns:
+        ContainerData if parsing succeeds, None if the file is missing,
+        unreadable, malformed JSON, or missing required uuid field.
+    """
+    try:
+        text = path.read_text(encoding="utf-8")
+    except (OSError, FileNotFoundError):
+        logger.warning("Cannot read container file: %s", path)
+        return None
+
+    try:
+        data = json.loads(text)
+    except (json.JSONDecodeError, ValueError):
+        logger.warning("Malformed JSON in container file: %s", path)
+        return None
+
+    if not isinstance(data, dict):
+        logger.warning("Container file is not a JSON object: %s", path)
+        return None
+
+    # Required field
+    uuid = data.get("uuid")
+    if uuid is None:
+        logger.warning("Container file missing required uuid: %s", path)
+        return None
+
+    return ContainerData(
+        uuid=uuid,
+        name=data.get("name", ""),
+        children=data.get("children", []),
+        befores=data.get("befores", []),
+        afters=data.get("afters", []),
+    )
+
+
+def extract_attachment_refs(result_data: dict, result_uuid: str) -> list[AttachmentRef]:
+    """Extract attachment references from an Allure result data dict.
+
+    Args:
+        result_data: The raw parsed Allure result JSON dict.
+        result_uuid: The UUID of the owning result (passed as argument,
+            not taken from result_data).
+
+    Returns:
+        List of AttachmentRef objects for each attachment in the result.
+    """
+    attachments = result_data.get("attachments")
+    if not attachments:
+        return []
+
+    refs: list[AttachmentRef] = []
+    for attachment in attachments:
+        source = attachment["source"]
+        refs.append(
+            AttachmentRef(
+                source=source,
+                name=attachment.get("name", source),
+                mime_type=attachment.get("type", "application/octet-stream"),
+                result_uuid=result_uuid,
+            )
+        )
+
+    return refs

charisma_cli/retry.py

@@ -0,0 +1,18 @@
+"""Exponential backoff utility and retryable HTTP status code constants."""
+
+RETRYABLE_STATUS_CODES = frozenset({429, 500, 502, 503, 504})
+MAX_RETRIES = 3
+
+
+def exponential_backoff(attempt: int, base: float = 1.0, factor: float = 2.0) -> float:
+    """Calculate retry delay using exponential backoff.
+
+    Args:
+        attempt: Zero-based attempt index (0, 1, 2, ...).
+        base: Base delay in seconds.
+        factor: Multiplicative factor per attempt.
+
+    Returns:
+        Delay in seconds: base * factor^attempt → 1s, 2s, 4s for defaults.
+    """
+    return base * (factor ** attempt)

charisma_cli/subprocess_mgr.py

@@ -0,0 +1,63 @@
+"""Subprocess spawning, signal forwarding, and exit code management."""
+
+import signal
+import subprocess
+import sys
+
+
+class SubprocessManager:
+    """Manages the lifecycle of a test subprocess.
+
+    Spawns the command, waits for completion, and forwards OS signals
+    (SIGINT, SIGTERM) to the child process.
+    """
+
+    def __init__(self) -> None:
+        self._process: subprocess.Popen | None = None
+
+    def spawn(self, command: tuple[str, ...]) -> None:
+        """Spawn the subprocess.
+
+        The child inherits stdout/stderr for transparent output pass-through.
+        stdin is not inherited to avoid issues in environments where stdin
+        is not a real file descriptor (e.g. pytest capture).
+
+        Args:
+            command: Command tuple to execute (e.g. ("pytest", "-n", "4")).
+        """
+        self._process = subprocess.Popen(
+            command,
+            stdout=None,  # inherit parent stdout
+            stderr=None,  # inherit parent stderr
+        )
+
+    def wait(self) -> int:
+        """Wait for the subprocess to terminate and return its exit code.
+
+        Returns:
+            The subprocess exit code, or 2 if no process was spawned.
+        """
+        if self._process is None:
+            return 2
+        self._process.wait()
+        return self._process.returncode
+
+    def forward_signal(self, sig: signal.Signals) -> None:
+        """Forward a signal to the child process.
+
+        On Windows, SIGTERM is implemented via process.terminate().
+        On POSIX, the signal is sent directly via os.kill.
+
+        Args:
+            sig: The signal to forward (e.g. signal.SIGTERM, signal.SIGINT).
+        """
+        if self._process is None:
+            return
+
+        if sys.platform == "win32":
+            # Windows doesn't support POSIX signals — use terminate/kill
+            if sig in (signal.SIGTERM, signal.SIGINT):
+                self._process.terminate()
+        else:
+            import os
+            os.kill(self._process.pid, sig)