opsscript-gate 0.1.2__py3-none-any.whl

opsscript_gate/__init__.py

@@ -0,0 +1,4 @@
+"""OpsScript Gate: Lightweight cross-distro compatibility pre-check for Linux ops scripts."""
+
+__version__ = "0.1.2"
+__all__ = ["__version__"]

opsscript_gate/cli.py

@@ -0,0 +1,129 @@
+from __future__ import annotations
+
+import argparse
+import os
+import sys
+
+from opsscript_gate import __version__
+from opsscript_gate.reporter import (
+    format_github_summary,
+    format_json,
+    format_terminal_table,
+    write_github_step_summary,
+)
+from opsscript_gate.runner import (
+    DEFAULT_MATRIX,
+    DEFAULT_TIMEOUT,
+    DockerDaemonError,
+    run_matrix,
+)
+
+
+def build_parser() -> argparse.ArgumentParser:
+    """Build the command-line argument parser."""
+    parser = argparse.ArgumentParser(
+        prog="opsscript-gate",
+        description="Lightweight unprivileged container cross-distro compatibility pre-check for Linux ops scripts.",
+    )
+    parser.add_argument(
+        "--version",
+        action="version",
+        version=f"%(prog)s {__version__}",
+    )
+
+    subparsers = parser.add_subparsers(dest="command", help="Available subcommands")
+
+    # 'run' subcommand
+    run_parser = subparsers.add_parser(
+        "run",
+        help="Run cross-distro compatibility validation on a shell script",
+    )
+    run_parser.add_argument(
+        "script_path",
+        type=str,
+        help="Path to the target shell script to validate",
+    )
+    run_parser.add_argument(
+        "--matrix",
+        type=str,
+        default=None,
+        help=(
+            "Comma-separated list of container images to test against. "
+            f"Defaults to: {','.join(DEFAULT_MATRIX)}"
+        ),
+    )
+    run_parser.add_argument(
+        "--timeout",
+        type=int,
+        default=DEFAULT_TIMEOUT,
+        help=f"Hard timeout in seconds per container (default: {DEFAULT_TIMEOUT}s)",
+    )
+    run_parser.add_argument(
+        "--format",
+        choices=["table", "markdown", "json"],
+        default="table",
+        help="Output report format: 'table' (default ASCII), 'markdown', or 'json'",
+    )
+
+    return parser
+
+
+def parse_matrix_argument(matrix_raw: str | None) -> list[str]:
+    """Parse comma-separated matrix string into a list of image names."""
+    if not matrix_raw:
+        return DEFAULT_MATRIX
+    images = [img.strip() for img in matrix_raw.split(",") if img.strip()]
+    return images if images else DEFAULT_MATRIX
+
+
+def main(argv: list[str] | None = None) -> int:
+    """Main CLI entrypoint."""
+    parser = build_parser()
+    args = parser.parse_args(argv)
+
+    if not args.command:
+        parser.print_help()
+        return 1
+
+    if args.command == "run":
+        script_path = args.script_path
+        if not os.path.isfile(script_path):
+            sys.stderr.write(f"Error: Script file not found: {script_path}\n")
+            return 1
+
+        matrix = parse_matrix_argument(args.matrix)
+
+        try:
+            report = run_matrix(
+                script_path=script_path,
+                matrix=matrix,
+                timeout=args.timeout,
+            )
+        except DockerDaemonError as err:
+            sys.stderr.write(f"Docker Error: {err}\n")
+            return 1
+        except Exception as err:
+            sys.stderr.write(f"Unexpected Error: {err}\n")
+            return 1
+
+        # Format report output
+        if args.format == "json":
+            output = format_json(report)
+        elif args.format == "markdown":
+            output = format_github_summary(report)
+        else:
+            output = format_terminal_table(report)
+
+        print(output)
+
+        # Automatic GitHub Actions Step Summary injection
+        write_github_step_summary(report)
+
+        # Exit code convention: 0 for all pass, 1 for any failure/timeout/error
+        return 0 if report.all_passed else 1
+
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

opsscript_gate/models.py

@@ -0,0 +1,55 @@
+from __future__ import annotations
+
+from dataclasses import asdict, dataclass, field
+from enum import Enum
+from typing import Any
+
+
+class DistroStatus(str, Enum):
+    """Execution status for a specific Linux distribution."""
+    PASS = "PASS"
+    FAIL = "FAIL"
+    TIMED_OUT = "TIMED_OUT"
+    ERROR = "ERROR"
+
+
+@dataclass
+class SingleResult:
+    """Execution result for a single Linux distribution."""
+    distro: str
+    status: DistroStatus
+    exit_code: int | None
+    duration: float
+    output_snippet: str = ""
+    error_message: str | None = None
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "distro": self.distro,
+            "status": self.status.value,
+            "exit_code": self.exit_code,
+            "duration": round(self.duration, 3),
+            "output_snippet": self.output_snippet,
+            "error_message": self.error_message,
+        }
+
+
+@dataclass
+class RunReport:
+    """Consolidated report across all tested distributions."""
+    results: list[SingleResult] = field(default_factory=list)
+    total_duration: float = 0.0
+    all_passed: bool = True
+
+    def __post_init__(self) -> None:
+        if self.results:
+            self.all_passed = all(r.status == DistroStatus.PASS for r in self.results)
+        else:
+            self.all_passed = True
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "results": [r.to_dict() for r in self.results],
+            "total_duration": round(self.total_duration, 3),
+            "all_passed": self.all_passed,
+        }

opsscript_gate/reporter.py

@@ -0,0 +1,158 @@
+from __future__ import annotations
+
+import json
+import os
+from opsscript_gate.models import DistroStatus, RunReport, SingleResult
+
+
+def format_terminal_table(report: RunReport) -> str:
+    """Format the report as a clean, aligned ASCII terminal table."""
+    headers = ["Distro", "Status", "Exit Code", "Duration", "Details"]
+
+    rows: list[list[str]] = []
+    for r in report.results:
+        exit_code_str = str(r.exit_code) if r.exit_code is not None else "-"
+        duration_str = f"{r.duration:.2f}s"
+
+        if r.status == DistroStatus.PASS:
+            detail = "OK"
+        elif r.error_message:
+            detail = r.error_message
+        else:
+            detail = "-"
+
+        rows.append([
+            r.distro,
+            r.status.value,
+            exit_code_str,
+            duration_str,
+            detail,
+        ])
+
+    col_widths = [len(h) for h in headers]
+    for row in rows:
+        for i, val in enumerate(row):
+            if len(val) > col_widths[i]:
+                col_widths[i] = len(val)
+
+    # Upper bound for detail column to keep terminal tidy
+    max_detail_width = 50
+    if col_widths[4] > max_detail_width:
+        col_widths[4] = max_detail_width
+
+    def format_row(values: list[str]) -> str:
+        formatted_vals = []
+        for i, v in enumerate(values):
+            w = col_widths[i]
+            if len(v) > w:
+                truncated = v[: w - 3] + "..."
+                formatted_vals.append(truncated.ljust(w))
+            else:
+                formatted_vals.append(v.ljust(w))
+        return "| " + " | ".join(formatted_vals) + " |"
+
+    sep_line = "+-" + "-+-".join("-" * w for w in col_widths) + "-+"
+
+    lines = [
+        sep_line,
+        format_row(headers),
+        sep_line,
+    ]
+    for row in rows:
+        lines.append(format_row(row))
+    lines.append(sep_line)
+
+    status_str = "PASSED" if report.all_passed else "FAILED"
+    lines.append(
+        f"Total duration: {report.total_duration:.2f}s | Result: {status_str}"
+    )
+
+    # Append output snippets for failing/timed out distros
+    failed_results = [r for r in report.results if r.status != DistroStatus.PASS and r.output_snippet]
+    if failed_results:
+        lines.append("\n" + "=" * 60)
+        lines.append("Failed Distributions - Output Snippets (last 15 lines):")
+        lines.append("=" * 60)
+        for r in failed_results:
+            lines.append(f"\n--- [{r.distro}] ({r.status.value}) ---")
+            lines.append(r.output_snippet)
+
+    return "\n".join(lines)
+
+
+def format_github_summary(report: RunReport) -> str:
+    """Format the report as GitHub-flavored Markdown for Actions Step Summary."""
+    overall_badge = "✅ **ALL PASSED**" if report.all_passed else "❌ **CHECKS FAILED**"
+
+    lines = [
+        "## 🛡️ OpsScript Gate Compatibility Report",
+        "",
+        f"**Overall Status**: {overall_badge}  ",
+        f"**Total Duration**: `{report.total_duration:.2f}s`  ",
+        f"**Total Tested**: `{len(report.results)}`",
+        "",
+        "| Distro | Status | Exit Code | Duration | Message |",
+        "| :--- | :---: | :---: | :---: | :--- |",
+    ]
+
+    for r in report.results:
+        if r.status == DistroStatus.PASS:
+            status_icon = "✅ PASS"
+        elif r.status == DistroStatus.FAIL:
+            status_icon = "❌ FAIL"
+        elif r.status == DistroStatus.TIMED_OUT:
+            status_icon = "⏱️ TIMED_OUT"
+        else:
+            status_icon = "⚠️ ERROR"
+
+        exit_code_str = f"`{r.exit_code}`" if r.exit_code is not None else "`N/A`"
+        duration_str = f"`{r.duration:.2f}s`"
+        msg = r.error_message or "-"
+        msg_escaped = msg.replace("|", "\\|")
+
+        lines.append(
+            f"| `{r.distro}` | {status_icon} | {exit_code_str} | {duration_str} | {msg_escaped} |"
+        )
+
+    lines.append("")
+
+    # Expandable details for any failures or timeouts
+    failures = [r for r in report.results if r.status != DistroStatus.PASS]
+    if failures:
+        lines.append("### 🔍 Failure Diagnostic Logs")
+        for r in failures:
+            lines.append(f"<details><summary><b>[{r.status.value}] {r.distro}</b></summary>")
+            lines.append("")
+            if r.error_message:
+                lines.append(f"> **Error:** {r.error_message}")
+                lines.append("")
+            if r.output_snippet:
+                lines.append("```text")
+                lines.append(r.output_snippet)
+                lines.append("```")
+            else:
+                lines.append("*No output captured.*")
+            lines.append("</details>")
+            lines.append("")
+
+    return "\n".join(lines)
+
+
+def format_json(report: RunReport) -> str:
+    """Format the report as structured JSON."""
+    return json.dumps(report.to_dict(), indent=2, ensure_ascii=False)
+
+
+def write_github_step_summary(report: RunReport) -> bool:
+    """Write markdown report to $GITHUB_STEP_SUMMARY if present in environment."""
+    summary_path = os.environ.get("GITHUB_STEP_SUMMARY")
+    if not summary_path:
+        return False
+
+    try:
+        markdown_content = format_github_summary(report)
+        with open(summary_path, "a", encoding="utf-8") as f:
+            f.write("\n" + markdown_content + "\n")
+        return True
+    except Exception:
+        return False

opsscript_gate/runner.py

@@ -0,0 +1,292 @@
+from __future__ import annotations
+
+import os
+import tempfile
+import time
+from typing import Sequence
+
+import docker
+from docker.errors import DockerException, ImageNotFound
+
+from opsscript_gate.models import DistroStatus, RunReport, SingleResult
+
+DEFAULT_MATRIX: list[str] = [
+    "debian:12-slim",
+    "ubuntu:22.04",
+    "ubuntu:24.04",
+    "alpine:3.20",
+]
+
+DEFAULT_TIMEOUT: int = 60
+SNIPPET_LINE_LIMIT: int = 15
+
+
+class DockerDaemonError(RuntimeError):
+    """Raised when the Docker daemon is unreachable or not running."""
+    pass
+
+
+def get_docker_client() -> docker.DockerClient:
+    """Connect to the Docker daemon with clear human-readable error handling."""
+    try:
+        client = docker.from_env()
+        client.ping()
+        return client
+    except DockerException as exc:
+        raise DockerDaemonError(
+            f"Cannot connect to Docker daemon: {exc}. "
+            "Please ensure Docker is installed, running, and accessible."
+        ) from exc
+    except Exception as exc:
+        raise DockerDaemonError(
+            f"Unexpected error connecting to Docker daemon: {exc}."
+        ) from exc
+
+
+def extract_snippet(output: str, max_lines: int = SNIPPET_LINE_LIMIT) -> str:
+    """Extract the last max_lines of output."""
+    if not output:
+        return ""
+    lines = output.strip().splitlines()
+    if len(lines) <= max_lines:
+        return "\n".join(lines)
+    return "\n".join(lines[-max_lines:])
+
+
+def normalize_host_path_for_docker(path: str) -> str:
+    """Format path to be safe for Docker volume mounting on both Windows and POSIX."""
+    abs_path = os.path.abspath(path)
+    # On Windows, Docker client handles forward slashes cleanly without colon misparsing
+    return abs_path.replace("\\", "/")
+
+
+def prepare_script(script_path: str) -> tuple[str, tempfile.NamedTemporaryFile | None]:
+    """
+    Check and normalize line endings (CRLF -> LF) to defend against
+    '\\r: command not found' errors in Linux containers (especially Alpine).
+    Returns (path_to_mount, temp_file_or_none).
+    """
+    abs_path = os.path.abspath(script_path)
+    with open(abs_path, "rb") as f:
+        content = f.read()
+
+    if b"\r\n" in content:
+        # Normalize CRLF to LF in a temporary file
+        temp_file = tempfile.NamedTemporaryFile(delete=False, suffix=".sh")
+        temp_file.write(content.replace(b"\r\n", b"\n"))
+        temp_file.flush()
+        temp_file.close()
+        return temp_file.name, temp_file
+
+    return abs_path, None
+
+
+def run_on_distro(
+    client: docker.DockerClient,
+    script_path: str,
+    distro: str,
+    timeout: int = DEFAULT_TIMEOUT,
+    poll_interval: float = 0.1,
+) -> SingleResult:
+    """
+    Run a target script inside an unprivileged, non-interactive container.
+    Strictly uses /bin/sh for 100% compatibility with Alpine, Debian, and Ubuntu.
+    """
+    abs_script = os.path.abspath(script_path)
+    if not os.path.isfile(abs_script):
+        return SingleResult(
+            distro=distro,
+            status=DistroStatus.ERROR,
+            exit_code=None,
+            duration=0.0,
+            output_snippet="",
+            error_message=f"Target script does not exist: {abs_script}",
+        )
+
+    # Line-ending defense & Windows-safe path preparation
+    temp_file = None
+    try:
+        mount_src, temp_file = prepare_script(abs_script)
+    except Exception as exc:
+        return SingleResult(
+            distro=distro,
+            status=DistroStatus.ERROR,
+            exit_code=None,
+            duration=0.0,
+            output_snippet="",
+            error_message=f"Failed to read/prepare script: {exc}",
+        )
+
+    safe_mount_src = normalize_host_path_for_docker(mount_src)
+
+    # Security: Strict unprivileged options and read-only mount
+    volumes = {
+        safe_mount_src: {
+            "bind": "/tmp/target_script.sh",
+            "mode": "ro",
+        }
+    }
+    environment = {
+        "DEBIAN_FRONTEND": "noninteractive",
+        "CI": "true",
+    }
+    # Red-line rule: strictly /bin/sh (never hardcode /bin/bash for Alpine compatibility)
+    # Redirect stdin from /dev/null to defend against interactive hangs
+    command = ["/bin/sh", "-c", "/bin/sh /tmp/target_script.sh </dev/null"]
+
+    container = None
+    start_time = time.perf_counter()
+
+    try:
+        try:
+            container = client.containers.create(
+                image=distro,
+                command=command,
+                volumes=volumes,
+                environment=environment,
+                stdin_open=False,
+                tty=False,
+                privileged=False,
+                cap_drop=["ALL"],
+                security_opt=["no-new-privileges:true"],
+                network_mode="bridge",
+                detach=True,
+            )
+        except ImageNotFound:
+            client.images.pull(distro)
+            container = client.containers.create(
+                image=distro,
+                command=command,
+                volumes=volumes,
+                environment=environment,
+                stdin_open=False,
+                tty=False,
+                privileged=False,
+                cap_drop=["ALL"],
+                security_opt=["no-new-privileges:true"],
+                network_mode="bridge",
+                detach=True,
+            )
+
+        container.start()
+
+        # Hard timeout monitoring with container.kill()
+        timed_out = False
+        while True:
+            elapsed = time.perf_counter() - start_time
+            if elapsed >= timeout:
+                timed_out = True
+                try:
+                    container.kill()
+                except Exception:
+                    pass
+                break
+
+            container.reload()
+            status_str = container.status.lower()
+            if status_str in ("exited", "dead", "stopped"):
+                break
+
+            time.sleep(poll_interval)
+
+        duration = time.perf_counter() - start_time
+
+        # Retrieve container logs
+        try:
+            raw_logs = container.logs(stdout=True, stderr=True)
+            output = raw_logs.decode("utf-8", errors="replace") if isinstance(raw_logs, bytes) else str(raw_logs)
+        except Exception:
+            output = ""
+
+        if timed_out:
+            return SingleResult(
+                distro=distro,
+                status=DistroStatus.TIMED_OUT,
+                exit_code=None,
+                duration=duration,
+                output_snippet=extract_snippet(output),
+                error_message=f"Execution timed out after {timeout} seconds (container killed)",
+            )
+
+        container.reload()
+        state = getattr(container, "attrs", {}).get("State", {})
+        exit_code = state.get("ExitCode")
+
+        if exit_code is None:
+            exit_code = 0 if container.status == "exited" else 1
+
+        if exit_code == 0:
+            return SingleResult(
+                distro=distro,
+                status=DistroStatus.PASS,
+                exit_code=0,
+                duration=duration,
+                output_snippet=extract_snippet(output) if output.strip() else "",
+                error_message=None,
+            )
+        else:
+            return SingleResult(
+                distro=distro,
+                status=DistroStatus.FAIL,
+                exit_code=exit_code,
+                duration=duration,
+                output_snippet=extract_snippet(output),
+                error_message=f"Script failed with non-zero exit code: {exit_code}",
+            )
+
+    except Exception as exc:
+        duration = time.perf_counter() - start_time
+        return SingleResult(
+            distro=distro,
+            status=DistroStatus.ERROR,
+            exit_code=None,
+            duration=duration,
+            output_snippet="",
+            error_message=f"Container execution error: {exc}",
+        )
+    finally:
+        # Zero-zombie guarantee: always remove container
+        if container is not None:
+            try:
+                container.remove(force=True)
+            except Exception:
+                pass
+        # Clean up temporary CRLF normalized file if created
+        if temp_file is not None:
+            try:
+                if os.path.exists(temp_file.name):
+                    os.remove(temp_file.name)
+            except Exception:
+                pass
+
+
+def run_matrix(
+    script_path: str,
+    matrix: Sequence[str] | None = None,
+    timeout: int = DEFAULT_TIMEOUT,
+    client: docker.DockerClient | None = None,
+) -> RunReport:
+    """Run the compatibility check across all specified Linux distributions."""
+    distro_list = list(matrix) if matrix else DEFAULT_MATRIX
+    docker_client = client or get_docker_client()
+
+    start_total = time.perf_counter()
+    results: list[SingleResult] = []
+
+    for distro in distro_list:
+        res = run_on_distro(
+            client=docker_client,
+            script_path=script_path,
+            distro=distro,
+            timeout=timeout,
+        )
+        results.append(res)
+
+    total_duration = time.perf_counter() - start_total
+    all_passed = all(r.status == DistroStatus.PASS for r in results) if results else True
+
+    return RunReport(
+        results=results,
+        total_duration=total_duration,
+        all_passed=all_passed,
+    )

opsscript_gate-0.1.2.dist-info/METADATA

@@ -0,0 +1,246 @@
+Metadata-Version: 2.5
+Name: opsscript-gate
+Version: 0.1.2
+Summary: Run Linux shell scripts across Debian, Ubuntu and Alpine before release to catch runtime compatibility failures
+Project-URL: Homepage, https://github.com/Mresyzz/opsscript-gate
+Project-URL: Repository, https://github.com/Mresyzz/opsscript-gate
+Project-URL: Issues, https://github.com/Mresyzz/opsscript-gate/issues
+Project-URL: Changelog, https://github.com/Mresyzz/opsscript-gate/blob/main/CHANGELOG.md
+Author: Mresyzz
+License: MIT
+License-File: LICENSE
+Keywords: ci,compatibility,cross-distro,devops,docker,github-actions,linux,posix,shell,testing
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: System Administrators
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Testing
+Classifier: Topic :: System :: Systems Administration
+Requires-Python: >=3.10
+Requires-Dist: docker>=7.0.0
+Provides-Extra: test
+Requires-Dist: pytest>=8.0.0; extra == 'test'
+Description-Content-Type: text/markdown
+
+# OpsScript Gate
+
+> **ShellCheck tells you if your script looks portable. OpsScript Gate checks if it actually runs there.**
+
+[![CI](https://github.com/Mresyzz/opsscript-gate/actions/workflows/test.yml/badge.svg)](https://github.com/Mresyzz/opsscript-gate/actions/workflows/test.yml)
+[![Demo](https://github.com/Mresyzz/opsscript-gate/actions/workflows/demo.yml/badge.svg)](https://github.com/Mresyzz/opsscript-gate/actions/workflows/demo.yml)
+[![GitHub Marketplace](https://img.shields.io/badge/Marketplace-OpsScript%20Gate-blue?logo=github&color=2088FF)](https://github.com/marketplace/actions/opsscript-gate)
+[![Release](https://img.shields.io/github/v/release/Mresyzz/opsscript-gate?color=green)](https://github.com/Mresyzz/opsscript-gate/releases)
+[![Python Version](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Supported Distros](https://img.shields.io/badge/matrix-Debian%20%7C%20Ubuntu%20%7C%20Alpine-orange.svg)](#default-test-matrix)
+
+**OpsScript Gate** is a drop-in runtime compatibility gate for Linux shell scripts. It executes your shell scripts inside isolated Debian, Ubuntu, and Alpine containers before release, catching environment-specific runtime failures that static analysis cannot detect.
+
+<p align="center">
+  <img src="https://raw.githubusercontent.com/Mresyzz/opsscript-gate/main/.github/assets/social-preview.png" alt="OpsScript Gate Terminal Preview" width="800">
+</p>
+
+---
+
+## Quickstart
+
+### In GitHub Actions
+
+Add one step to your pull request workflow (`.github/workflows/gate.yml`):
+
+```yaml
+- name: Verify Shell Script Portability
+  uses: Mresyzz/opsscript-gate@v0.1.1
+  with:
+    script-path: scripts/setup.sh
+```
+
+### In Local Terminal (CLI)
+
+Requires Python 3.10+ and a local Docker engine:
+
+```bash
+# Install directly from GitHub
+pip install git+https://github.com/Mresyzz/opsscript-gate.git
+
+# Run compatibility gate against your script
+opsscript-gate run ./scripts/setup.sh
+```
+
+---
+
+## Example: What Static Analysis Misses
+
+Consider this deployment script:
+
+```bash
+#!/bin/sh
+set -e
+echo "Fetching package information..."
+apt-get --version
+```
+
+Running `shellcheck` reports **0 errors, 0 warnings** because the syntax is valid POSIX shell.
+
+However, when verified with **OpsScript Gate**:
+
+```text
++--------------------+----------+-----------+----------------------------------------------------+
+| Distro             | Status   | Exit Code | Details                                            |
++--------------------+----------+-----------+----------------------------------------------------+
+| debian:12-slim     | PASS     | 0         | OK                                                 |
+| ubuntu:22.04       | PASS     | 0         | OK                                                 |
+| ubuntu:24.04       | PASS     | 0         | OK                                                 |
+| alpine:3.20        | FAIL     | 127       | Script failed with non-zero exit code: 127         |
++--------------------+----------+-----------+----------------------------------------------------+
+Result: FAILED
+
+============================================================
+Failed Distributions - Output Snippets (last 15 lines):
+============================================================
+
+--- [alpine:3.20] (FAIL) ---
+/tmp/target_script.sh: line 4: apt-get: not found
+```
+
+*Example output; timing values omitted because they vary by host and image cache state.*
+
+**Why it failed:** Alpine Linux is musl/BusyBox-based and uses `apk`, not `apt-get`. OpsScript Gate catches the missing utility (`exit code 127`) during test execution, before the script is deployed.
+
+---
+
+## Why OpsScript Gate?
+
+### OpsScript Gate vs ShellCheck vs Custom CI Matrix
+
+| Capability | OpsScript Gate | ShellCheck | Handwritten CI Matrix |
+| :--- | :---: | :---: | :---: |
+| **Runtime execution** | **Yes** | No (Static AST only) | Yes |
+| **Real distro environments** | **Yes (Debian, Ubuntu, Alpine)** | No | Yes |
+| **Preconfigured defaults** | **Yes** | Yes | Requires custom workflow configuration |
+| **Safe container defaults** | **Built-in (`ro`, `cap_drop`, `kill`)** | N/A | User-defined |
+| **Anti-hang stdin protection** | **Built-in (`</dev/null`, noninteractive)** | No | User-defined |
+| **Unified summary & diagnostics** | **Built-in (ASCII + Step Summary)** | Static warnings | User-defined |
+
+- **ShellCheck** is indispensable for static analysis (syntax, quoting, SC warnings). OpsScript Gate complements it by testing actual execution behavior in real distributions.
+- **Handwritten CI Matrix** requires maintaining complex Docker configurations, volume mounts, timeout guards, and log parsers across every project. OpsScript Gate packages this into a single check.
+
+---
+
+## Security Boundaries
+
+OpsScript Gate uses conservative container defaults when running scripts:
+
+1. **Unprivileged by Design**:
+   - Containers run with `privileged=False`.
+   - All Linux capabilities are dropped: `cap_drop=["ALL"]`.
+   - Privilege escalation is disabled: `security_opt=["no-new-privileges:true"]`.
+2. **Read-Only Target Mount**:
+   - The tested script is mounted read-only (`:ro`) at `/tmp/target_script.sh`.
+   - OpsScript Gate does not mount additional host filesystem paths into the test container.
+3. **Anti-Hang Deadlock Defense**:
+   - Disables TTY and stdin (`stdin_open=False`, `tty=False`).
+   - Redirects execution: `/bin/sh -c "/bin/sh /tmp/target_script.sh </dev/null"`.
+   - Injects `DEBIAN_FRONTEND=noninteractive` and `CI=true`.
+   - Any script prompting for user input (`read -p`) fails immediately instead of blocking the CI runner.
+4. **Timeout & Container Cleanup**:
+   - Enforces a configurable timeout (default: 60s). Timed-out containers are sent `SIGKILL` and marked `TIMED_OUT`.
+   - Container removal is attempted from a `finally` block during normal Python execution paths, including failures and timeouts.
+5. **Windows CRLF Defense**:
+   - Automatically detects and normalizes carriage returns (`\r\n` -> `\n`) before container execution, preventing false `\r: command not found` errors.
+6. **POSIX-oriented `/bin/sh` Baseline**:
+   - Containers invoke `/bin/sh` directly, catching undeclared Bashism syntax (e.g. bash arrays, `[[ ... ]]`) that break in lightweight Alpine environments.
+
+---
+
+## Default Test Matrix
+
+| Image | Distribution | Focus |
+| :--- | :--- | :--- |
+| `debian:12-slim` | Debian 12 (Bookworm) | Minimal glibc + APT base |
+| `ubuntu:22.04` | Ubuntu 22.04 LTS (Jammy) | Enterprise long-term support baseline |
+| `ubuntu:24.04` | Ubuntu 24.04 LTS (Noble) | Modern glibc, updated coreutils & defaults |
+| `alpine:3.20` | Alpine Linux 3.20 | Minimal musl libc + BusyBox (strict POSIX test) |
+
+You can customize the matrix at any time via `--matrix` or Action input `matrix`.
+
+---
+
+## CLI Reference
+
+```text
+usage: opsscript-gate run [-h] [--matrix MATRIX] [--timeout TIMEOUT]
+                          [--format {table,markdown,json}]
+                          script_path
+```
+
+| Parameter | Type | Default | Description |
+| :--- | :--- | :--- | :--- |
+| `script_path` | Positional | *Required* | Path to target shell script |
+| `--matrix` | String | `debian:12-slim,ubuntu:22.04,ubuntu:24.04,alpine:3.20` | Comma-separated list of Docker images |
+| `--timeout` | Integer | `60` | Hard timeout per container in seconds |
+| `--format` | Choice | `table` | Output format: `table`, `markdown`, or `json` |
+| `--version` | Flag | - | Show version number |
+| `-h, --help` | Flag | - | Show argument help |
+
+### Exit Code Convention
+- **`0`**: All distributions passed (`PASS`).
+- **`1`**: At least one distribution failed (`FAIL`), timed out (`TIMED_OUT`), or errored (`ERROR`).
+
+---
+
+## Examples
+
+Check out the [examples/](examples/) directory for self-contained, runnable scenarios:
+
+- [`examples/basic/`](examples/basic/): A clean POSIX script that passes across all distributions.
+- [`examples/alpine-incompatibility/`](examples/alpine-incompatibility/): Demonstrates catching implicit Debian/Ubuntu dependencies (e.g. `apt-get`).
+- [`examples/interactive-hang/`](examples/interactive-hang/): Demonstrates how unhandled `read` prompts fail immediately instead of hanging.
+- [`examples/github-actions/`](examples/github-actions/): Ready-to-copy production pull request workflow.
+
+---
+
+## Development & Testing
+
+The test suite uses Docker SDK mocking to ensure fast unit tests without needing a local daemon:
+
+```bash
+# Clone and install with test dependencies
+git clone https://github.com/Mresyzz/opsscript-gate.git
+cd opsscript-gate
+pip install -e .[test]
+
+# Run unit tests (mocked)
+pytest -v -m "not integration"
+
+# Run integration tests (Requires Docker daemon)
+pytest -v
+```
+
+---
+
+## Roadmap
+
+See [ROADMAP.md](ROADMAP.md) for planned capabilities, including:
+- Shebang-aware execution modes (`--shell auto|posix|shebang`)
+- Container resource limits (`--mem-limit`, `--pids-limit`)
+- Configurable network isolation (`--network none|bridge`)
+- Parallel matrix execution
+
+---
+
+## Contributing & Security
+
+- **Contributing**: Please review [CONTRIBUTING.md](CONTRIBUTING.md) for pull request guidelines and security boundaries.
+- **Security Policy**: Read [SECURITY.md](SECURITY.md) to report vulnerabilities responsibly.
+- **Changelog**: See [CHANGELOG.md](CHANGELOG.md) for release history.
+
+---
+
+## License
+
+OpsScript Gate is licensed under the [MIT License](LICENSE).

opsscript_gate-0.1.2.dist-info/RECORD

@@ -0,0 +1,10 @@
+opsscript_gate/__init__.py,sha256=z8TNBn2dtWcnTqic6vze5QJulzkp0cRD7LM0ZUmiVf0,143
+opsscript_gate/cli.py,sha256=T5pUn38uHrL3aGgM15mrgh9c7reJfJHwFdk1KzpYHTk,3617
+opsscript_gate/models.py,sha256=uy_KwPYq9yOhgZmgn6XQeNKQ8dJ8JTfW7wuXh04S2vk,1537
+opsscript_gate/reporter.py,sha256=CtoGd21Ue4BLkZS4caIL3_zzFHA1jJc9sqo_eiwkFbM,5292
+opsscript_gate/runner.py,sha256=kteqsVJTSBMoM5aj6moP-Ych-H6-8VdH3RZbpYk3RVo,9223
+opsscript_gate-0.1.2.dist-info/METADATA,sha256=IzPh5eLTxRFxvZMyeMMUsN5mjeyJRAH49uwQfEOHXLE,10774
+opsscript_gate-0.1.2.dist-info/WHEEL,sha256=THafob7ofN-NsuMN7Mg4qZyHaQI7KkD-QlcQatYhXPo,87
+opsscript_gate-0.1.2.dist-info/entry_points.txt,sha256=rJgpiXse5cCM3KCRbcVOhInoVLxpLfP3XKn0x79yMr4,59
+opsscript_gate-0.1.2.dist-info/licenses/LICENSE,sha256=4Xo4yBr2jDq8iOccGx2to60KI5fjGNxbIKoes6AoSmo,1084
+opsscript_gate-0.1.2.dist-info/RECORD,,

opsscript_gate-0.1.2.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.3
+Root-Is-Purelib: true
+Tag: py3-none-any

opsscript_gate-0.1.2.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+opsscript-gate = opsscript_gate.cli:main

opsscript_gate-0.1.2.dist-info/licenses/LICENSE

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