hyperi-ci 1.0.18__py3-none-any.whl

hyperi_ci/__init__.py

@@ -0,0 +1,11 @@
+# Project:   HyperI CI
+# File:      src/hyperi_ci/__init__.py
+# Purpose:   Package root for hyperi-ci CLI tool
+#
+# License:   Proprietary — HYPERI PTY LIMITED
+# Copyright: (c) 2026 HYPERI PTY LIMITED
+"""HyperI CI/CD CLI tool — multi-language build, test, and publish automation."""
+
+from importlib.metadata import version
+
+__version__ = version("hyperi-ci")

hyperi_ci/cli.py

@@ -0,0 +1,264 @@
+# Project:   HyperI CI
+# File:      src/hyperi_ci/cli.py
+# Purpose:   CLI entry point for hyperi-ci tool (Typer via hyperi-pylib)
+#
+# License:   Proprietary — HYPERI PTY LIMITED
+# Copyright: (c) 2026 HYPERI PTY LIMITED
+"""CLI entry point for HyperI CI.
+
+Usage:
+    hyperi-ci run <stage>       Run a CI stage (setup, quality, test, build, publish)
+    hyperi-ci init              Initialise project (config, Makefile, workflow)
+    hyperi-ci detect            Detect project language
+    hyperi-ci config            Show merged configuration
+    hyperi-ci trigger           Trigger a GitHub Actions workflow run
+    hyperi-ci watch [RUN_ID]    Watch a GitHub Actions run to completion
+    hyperi-ci logs [RUN_ID]     Fetch and filter GitHub Actions run logs
+    hyperi-ci --version         Show version
+"""
+
+from __future__ import annotations
+
+import json
+import sys
+from pathlib import Path
+from typing import Annotated
+
+import typer
+
+from hyperi_ci import __version__
+from hyperi_ci.config import load_config
+from hyperi_ci.detect import detect_language
+from hyperi_ci.dispatch import VALID_STAGES, run_stage
+
+app = typer.Typer(
+    name="hyperi-ci",
+    help="HyperI CI — polyglot CI/CD tool",
+    no_args_is_help=True,
+)
+
+
+def _version_callback(value: bool) -> None:
+    if value:
+        typer.echo(f"hyperi-ci {__version__}")
+        raise typer.Exit()
+
+
+@app.callback()
+def _main(
+    version: Annotated[
+        bool,
+        typer.Option(
+            "--version",
+            "-V",
+            help="Show version and exit",
+            callback=_version_callback,
+            is_eager=True,
+        ),
+    ] = False,
+) -> None:
+    """HyperI CI — polyglot CI/CD tool."""
+
+
+@app.command()
+def run(
+    stage: Annotated[str, typer.Argument(help="Stage to run")],
+    project_dir: Annotated[
+        str | None,
+        typer.Option("--project-dir", "-C", help="Project root directory"),
+    ] = None,
+) -> None:
+    """Run a CI stage (setup, quality, test, build, publish)."""
+    if stage not in VALID_STAGES:
+        typer.echo(f"Invalid stage: {stage}", err=True)
+        typer.echo(f"Valid stages: {', '.join(VALID_STAGES)}", err=True)
+        raise typer.Exit(1)
+
+    dir_path = Path(project_dir) if project_dir else None
+    rc = run_stage(stage, project_dir=dir_path)
+    raise typer.Exit(rc)
+
+
+@app.command()
+def init(
+    project_dir: Annotated[
+        str | None,
+        typer.Option("--project-dir", "-C", help="Project root directory"),
+    ] = None,
+    language: Annotated[
+        str | None,
+        typer.Option("--language", "-l", help="Override detected language"),
+    ] = None,
+    force: Annotated[
+        bool,
+        typer.Option("--force", "-f", help="Overwrite existing files"),
+    ] = False,
+) -> None:
+    """Initialise a project for hyperi-ci (generates config, Makefile, workflow)."""
+    from hyperi_ci.init import init_project
+
+    dir_path = Path(project_dir) if project_dir else Path.cwd()
+    rc = init_project(dir_path, language=language, force=force)
+    raise typer.Exit(rc)
+
+
+@app.command()
+def detect(
+    project_dir: Annotated[
+        str | None,
+        typer.Option("--project-dir", "-C", help="Project root directory"),
+    ] = None,
+) -> None:
+    """Detect project language."""
+    dir_path = Path(project_dir) if project_dir else None
+    language = detect_language(dir_path)
+    if language:
+        typer.echo(language)
+    else:
+        typer.echo("unknown", err=True)
+        raise typer.Exit(1)
+
+
+@app.command()
+def config(
+    project_dir: Annotated[
+        str | None,
+        typer.Option("--project-dir", "-C", help="Project root directory"),
+    ] = None,
+) -> None:
+    """Show merged configuration."""
+    dir_path = Path(project_dir) if project_dir else None
+    cfg = load_config(reload=True, project_dir=dir_path)
+    typer.echo(json.dumps(cfg._raw, indent=2, default=str))
+
+
+@app.command()
+def migrate(
+    project_dir: Annotated[
+        str | None,
+        typer.Option("--project-dir", "-C", help="Project root directory"),
+    ] = None,
+    language: Annotated[
+        str | None,
+        typer.Option("--language", "-l", help="Override detected language"),
+    ] = None,
+    dry_run: Annotated[
+        bool,
+        typer.Option("--dry-run", "-n", help="Show what would be done"),
+    ] = False,
+) -> None:
+    """Migrate a project from old ci/ submodule to hyperi-ci."""
+    from hyperi_ci.migrate import migrate_project
+
+    dir_path = Path(project_dir) if project_dir else Path.cwd()
+    rc = migrate_project(dir_path, language=language, dry_run=dry_run)
+    raise typer.Exit(rc)
+
+
+@app.command()
+def trigger(
+    workflow: Annotated[
+        str,
+        typer.Option("--workflow", "-w", help="Workflow filename"),
+    ] = "ci.yml",
+    ref: Annotated[
+        str | None,
+        typer.Option("--ref", "-r", help="Branch or tag to run on"),
+    ] = None,
+    watch_run: Annotated[
+        bool,
+        typer.Option("--watch", help="Watch run to completion after triggering"),
+    ] = False,
+    timeout: Annotated[
+        int,
+        typer.Option("--timeout", "-t", help="Timeout in seconds"),
+    ] = 1800,
+    interval: Annotated[
+        int,
+        typer.Option("--interval", "-i", help="Poll interval in seconds"),
+    ] = 30,
+) -> None:
+    """Trigger a GitHub Actions workflow run."""
+    from hyperi_ci.trigger import trigger_workflow
+
+    rc = trigger_workflow(
+        workflow=workflow,
+        ref=ref,
+        watch=watch_run,
+        timeout=timeout,
+        interval=interval,
+    )
+    raise typer.Exit(rc)
+
+
+@app.command()
+def watch(
+    run_id: Annotated[
+        str | None,
+        typer.Argument(help="Run ID (auto-detects latest if omitted)"),
+    ] = None,
+    timeout: Annotated[
+        int,
+        typer.Option("--timeout", "-t", help="Timeout in seconds"),
+    ] = 1800,
+    interval: Annotated[
+        int,
+        typer.Option("--interval", "-i", help="Initial poll interval in seconds"),
+    ] = 30,
+) -> None:
+    """Watch a GitHub Actions run to completion."""
+    from hyperi_ci.watch import watch_run
+
+    rc = watch_run(run_id=run_id, timeout=timeout, interval=interval)
+    raise typer.Exit(rc)
+
+
+@app.command()
+def logs(
+    run_id: Annotated[
+        str | None,
+        typer.Argument(help="Run ID (auto-detects latest if omitted)"),
+    ] = None,
+    job: Annotated[
+        str | None,
+        typer.Option("--job", "-j", help="Filter by job name (substring)"),
+    ] = None,
+    step: Annotated[
+        str | None,
+        typer.Option("--step", "-s", help="Filter by step name (substring)"),
+    ] = None,
+    grep: Annotated[
+        str | None,
+        typer.Option("--grep", "-g", help="Filter lines by pattern"),
+    ] = None,
+    tail: Annotated[
+        int | None,
+        typer.Option("--tail", "-n", help="Show last N lines"),
+    ] = None,
+    failed: Annotated[
+        bool,
+        typer.Option("--failed", help="Show only failed job logs"),
+    ] = False,
+) -> None:
+    """Fetch and filter GitHub Actions run logs."""
+    from hyperi_ci.logs import fetch_logs
+
+    rc = fetch_logs(
+        run_id=run_id,
+        job_filter=job,
+        step_filter=step,
+        grep_pattern=grep,
+        tail_lines=tail,
+        failed_only=failed,
+    )
+    raise typer.Exit(rc)
+
+
+def main() -> int:
+    """CLI entry point."""
+    app()
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

hyperi_ci/common.py

@@ -0,0 +1,294 @@
+# Project:   HyperI CI
+# File:      src/hyperi_ci/common.py
+# Purpose:   Shared utilities for CI scripts (output, subprocess, exclusions)
+#
+# License:   Proprietary — HYPERI PTY LIMITED
+# Copyright: (c) 2026 HYPERI PTY LIMITED
+"""Shared utilities for HyperI CI.
+
+Uses hyperi-pylib logger for structured output with automatic environment
+detection (GitHub Actions workflow commands, Solarized terminal, plain CI).
+"""
+
+from __future__ import annotations
+
+import os
+import subprocess
+import sys
+from collections.abc import Iterator
+from contextlib import contextmanager
+from pathlib import Path
+from typing import Any
+
+from hyperi_pylib.logger import logger
+
+# Initialise logger for CI use (auto-detects GH Actions, CI, terminal)
+from hyperi_pylib.logger import setup as _setup_logger
+
+_setup_logger(ci_mode=None, mask_sensitive=True)
+
+
+def is_ci() -> bool:
+    """Detect if running in a CI/runner environment."""
+    return any(
+        os.environ.get(v)
+        for v in ("CI", "GITHUB_ACTIONS", "GITLAB_CI", "JENKINS_URL", "BUILDKITE")
+    )
+
+
+def is_github_actions() -> bool:
+    """Detect if running in GitHub Actions specifically."""
+    return bool(os.environ.get("GITHUB_ACTIONS"))
+
+
+def is_interactive() -> bool:
+    """Detect if running in an interactive terminal (supports colours)."""
+    if not sys.stderr.isatty():
+        return False
+    term = os.environ.get("TERM", "")
+    if term == "dumb" or not term:
+        return False
+    if is_ci():
+        return False
+    return True
+
+
+def is_macos() -> bool:
+    """Detect if running on macOS."""
+    return sys.platform == "darwin"
+
+
+def is_linux() -> bool:
+    """Detect if running on Linux."""
+    return sys.platform.startswith("linux")
+
+
+def info(msg: str) -> None:
+    """Info message — delegates to hyperi-pylib logger."""
+    logger.info(msg)
+
+
+def success(msg: str) -> None:
+    """Success message — delegates to hyperi-pylib logger."""
+    logger.success(msg)
+
+
+def warn(msg: str) -> None:
+    """Warning — delegates to hyperi-pylib logger."""
+    logger.warning(msg)
+
+
+def error(msg: str) -> None:
+    """Error — delegates to hyperi-pylib logger."""
+    logger.error(msg)
+
+
+def fatal(msg: str) -> None:
+    """Fatal error — log and exit with code 1."""
+    logger.critical(msg)
+    sys.exit(1)
+
+
+@contextmanager
+def group(title: str) -> Iterator[None]:
+    """Collapsible group in GH Actions logs. No-op elsewhere."""
+    if is_github_actions():
+        print(f"::group::{title}")
+    try:
+        yield
+    finally:
+        if is_github_actions():
+            print("::endgroup::")
+
+
+def set_output(name: str, value: str) -> None:
+    """Set a GH Actions step output parameter via GITHUB_OUTPUT file."""
+    output_file = os.environ.get("GITHUB_OUTPUT")
+    if output_file:
+        with open(output_file, "a") as f:
+            f.write(f"{name}={value}\n")
+
+
+def set_env(name: str, value: str) -> None:
+    """Set a GH Actions environment variable via GITHUB_ENV file."""
+    env_file = os.environ.get("GITHUB_ENV")
+    if env_file:
+        with open(env_file, "a") as f:
+            f.write(f"{name}={value}\n")
+
+
+def mask(value: str) -> None:
+    """Mask a value in GH Actions logs."""
+    if is_github_actions():
+        print(f"::add-mask::{value}")
+
+
+def run_cmd(
+    cmd: list[str],
+    *,
+    check: bool = True,
+    capture: bool = False,
+    cwd: str | Path | None = None,
+    env: dict[str, str] | None = None,
+) -> subprocess.CompletedProcess[str]:
+    """Run a subprocess with consistent error handling.
+
+    Args:
+        cmd: Command as list of strings.
+        check: Raise CalledProcessError on non-zero exit.
+        capture: Capture stdout/stderr instead of passing through.
+        cwd: Working directory.
+        env: Additional env vars (merged with os.environ).
+
+    Returns:
+        CompletedProcess with text output.
+    """
+    run_env = None
+    if env:
+        run_env = {**os.environ, **env}
+
+    return subprocess.run(
+        cmd,
+        check=check,
+        capture_output=capture,
+        text=True,
+        cwd=cwd,
+        env=run_env,
+    )
+
+
+def verify_publish(
+    url: str,
+    *,
+    auth: tuple[str, str] | None = None,
+    max_retries: int = 5,
+    retry_delay: int = 10,
+    label: str = "",
+) -> bool:
+    """Verify a published artifact is reachable via HTTP HEAD with retries.
+
+    JFrog Artifactory has indexing lag — a just-published artifact may return
+    404 for several seconds. This retries with delay to account for that.
+
+    Args:
+        url: Full URL to HEAD-check.
+        auth: Optional (username, password) tuple for basic auth.
+        max_retries: Maximum number of attempts.
+        retry_delay: Seconds to wait between retries.
+        label: Human-readable label for log messages.
+
+    Returns:
+        True if the artifact was found (HTTP 200), False otherwise.
+    """
+    import time
+
+    display = label or url.rsplit("/", 1)[-1]
+
+    for attempt in range(1, max_retries + 1):
+        cmd = ["curl", "-sS", "-o", "/dev/null", "-w", "%{http_code}", "--head"]
+        if auth:
+            cmd.extend(["-u", f"{auth[0]}:{auth[1]}"])
+        cmd.append(url)
+
+        result = subprocess.run(cmd, capture_output=True, text=True)
+        http_code = result.stdout.strip()
+
+        if http_code == "200":
+            success(f"  Verified: {display}")
+            return True
+
+        if attempt < max_retries:
+            info(
+                f"  Attempt {attempt}/{max_retries}: {display} "
+                f"not found (HTTP {http_code}), retrying in {retry_delay}s..."
+            )
+            time.sleep(retry_delay)
+
+    error(f"  Verification failed: {display} not found after {max_retries} attempts")
+    return False
+
+
+# Common directories to exclude from quality checks
+_COMMON_EXCLUDES = [
+    ".venv",
+    "venv",
+    "env",
+    ".env",
+    "virtualenv",
+    ".virtualenv",
+    "__pycache__",
+    ".pytest_cache",
+    ".mypy_cache",
+    ".ruff_cache",
+    ".hypothesis",
+    "*.egg-info",
+    ".eggs",
+    "dist",
+    "build",
+    "wheelhouse",
+    ".tox",
+    ".nox",
+    ".git",
+    ".github",
+    "node_modules",
+    ".npm",
+    ".yarn",
+    ".pnpm-store",
+    ".next",
+    ".nuxt",
+    ".output",
+    ".svelte-kit",
+    "target",
+    "vendor",
+    ".idea",
+    ".vscode",
+    ".vs",
+    "htmlcov",
+    "coverage",
+    ".coverage",
+    ".nyc_output",
+    "_build",
+    "site",
+    ".cache",
+    ".tmp",
+    "tmp",
+    ".temp",
+    "temp",
+]
+
+
+def get_exclude_dirs(config_raw: dict[str, Any] | None = None) -> list[str]:
+    """Get directories to exclude from quality checks.
+
+    Combines:
+      1. Git submodule paths (from .gitmodules)
+      2. ci/ and ai/ (always)
+      3. Common directories (.venv, node_modules, target, etc.)
+      4. Custom paths from quality.exclude_paths config
+    """
+    excludes: list[str] = []
+
+    gitmodules = Path(".gitmodules")
+    if gitmodules.exists():
+        for line in gitmodules.read_text().splitlines():
+            if "path" in line and "=" in line:
+                path = line.split("=", 1)[1].strip()
+                if path and Path(path).is_dir():
+                    excludes.append(path)
+
+    for submod in ("ci", "ai"):
+        if Path(submod).is_dir() and submod not in excludes:
+            excludes.append(submod)
+
+    for dirname in _COMMON_EXCLUDES:
+        if Path(dirname).exists() and dirname not in excludes:
+            excludes.append(dirname)
+
+    if config_raw:
+        custom = config_raw.get("quality", {}).get("exclude_paths", [])
+        if isinstance(custom, list):
+            for path in custom:
+                if path and Path(path).is_dir() and path not in excludes:
+                    excludes.append(path)
+
+    return excludes