opsscript-gate 0.3.0__tar.gz → 0.4.0__tar.gz

{opsscript_gate-0.3.0 → opsscript_gate-0.4.0}/.github/workflows/demo.yml

@@ -3,6 +3,8 @@ name: Demo Shell Script Compatibility Gate
 on:
   push:
     branches: [ main ]
+  pull_request:
+    branches: [ main ]
   workflow_dispatch:
 
 jobs:

{opsscript_gate-0.3.0 → opsscript_gate-0.4.0}/CHANGELOG.md

@@ -5,6 +5,30 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.4.0] - 2026-09-19
+
+### Added
+- **High-confidence line-level GitHub Actions annotations**: Emits inline `::error` annotations with exact script line numbers directly on pull request file diffs.
+- **Workflow command injection defense**: Strictly escapes parameters (`%`, `\r`, `\n`, `:`, `,`) and message bodies (`%`, `\r`, `\n`) to eliminate command injection from unclassified container logs.
+- **Conservative distro-aware remediation hints**: Suggests testable, high-confidence remediation recommendations (`RemediationRule`) with conservative phrasing (`normally`, `may`, `consider`), covering:
+  - Alpine package manager mismatches (`apt`/`apt-get` -> `apk`)
+  - Debian/Ubuntu package manager mismatches (`apk` -> `apt-get`)
+  - Alpine minimal missing Bash (`bash` -> consider POSIX sh or installing bash)
+  - Missing network prerequisites (`curl`, `wget`)
+  - Missing shebang interpreter paths.
+- **Re-engineered Compatibility Card**: Overhauled GitHub Actions Step Summary with an instant 5-second triage table and an expandable copy-pasteable Markdown snippet ready for PR descriptions and Issue comments.
+- **Parallel matrix execution (`--jobs` / `jobs`)**: Concurrently runs container checks using `ThreadPoolExecutor` (defaults to `min(2, matrix_size)`), strictly preserving matrix output order and ensuring reliable container cleanup.
+- **Hardened container resource limits**: Added `--mem-limit` (default: 256m) and `--pids-limit` (default: 128) flags and Action inputs to prevent runaway resource exhaustion.
+- **Configurable network isolation (`--network`)**: Supports `--network bridge` (default) and `--network none` for offline script execution.
+- **Zero-config repository script auto-discovery**: Running `opsscript-gate run` without arguments automatically discovers and validates shell scripts in the repository, ignoring directories like `.git`, `node_modules`, and `.venv`, capped at 20 scripts and 1 MB per file.
+- **Multi-script test consolidation (`MultiScriptReport`)**: Supports aggregate reporting and Step Summary cards when multiple scripts are evaluated in a single run.
+
+### Changed
+- **Action initialization performance**: Removed redundant `pip install --upgrade pip` step in composite `action.yml` to minimize Action startup latency.
+- **Flexible Action inputs**: Made `script-path` optional in `action.yml` (triggers auto-discovery if omitted); added inputs `jobs`, `mem-limit`, `pids-limit`, and `network`.
+
+---
+
 ## [0.3.0] - 2026-09-19
 
 ### Added

opsscript_gate-0.4.0/PKG-INFO

@@ -0,0 +1,301 @@
+Metadata-Version: 2.5
+Name: opsscript-gate
+Version: 0.4.0
+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)
+[![PyPI](https://img.shields.io/pypi/v/opsscript-gate)](https://pypi.org/project/opsscript-gate/)
+[![Python Versions](https://img.shields.io/pypi/pyversions/opsscript-gate)](https://pypi.org/project/opsscript-gate/)
+[![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)
+[![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 scripts inside unprivileged Debian, Ubuntu, and Alpine containers before merge, catching environment-specific runtime failures, missing interpreters, and package-manager assumptions that static analysis cannot detect.
+
+---
+
+## ⚡ 30-Second Quickstart
+
+### In GitHub Actions (Zero Config)
+
+Drop this minimal workflow into `.github/workflows/shell-compat.yml`:
+
+```yaml
+name: Shell Compatibility Gate
+on: [pull_request, push]
+
+jobs:
+  compat:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+      - uses: Mresyzz/opsscript-gate@v0.4.0
+```
+
+> **Zero Config**: If `script-path` is omitted, OpsScript Gate automatically discovers shell scripts in your repository and tests them concurrently!
+
+Or test a specific script with custom execution modes:
+
+```yaml
+      - uses: Mresyzz/opsscript-gate@v0.4.0
+        with:
+          script-path: scripts/install.sh
+          shell: auto
+          jobs: 4
+```
+
+### In Local Terminal (CLI)
+
+Requires Python 3.10+ and a running local Docker engine:
+
+```bash
+# Install from PyPI
+pip install opsscript-gate
+
+# Run against a specific script
+opsscript-gate run ./scripts/install.sh
+
+# Or auto-discover scripts across your repository
+opsscript-gate run
+```
+
+---
+
+## 🎯 Reviewer-First Experience: What It Produces
+
+Every run of OpsScript Gate generates clean, actionable feedback right where developers and reviewers need it:
+
+### 1. Line-Level GitHub Annotations
+When a failure occurs, OpsScript Gate flags the exact script line on your Pull Request's **Files Changed** view with high-confidence diagnostics and conservative remediation hints:
+
+```text
+::error file=scripts/setup.sh,line=4,title=OpsScript Gate: [alpine:3.20] command not found: apt-get::command not found: apt-get — Alpine normally uses apk instead of apt-get.
+```
+
+### 2. GitHub Step Summary Compatibility Card
+A beautifully formatted markdown summary is automatically posted to `$GITHUB_STEP_SUMMARY`:
+
+```markdown
+## 🛡️ OpsScript Gate Compatibility Report
+
+**Target Script**: `scripts/setup.sh`  
+**Status**: ❌ **CHECKS FAILED (3/4 Passed)**  
+**Total Duration**: `1.24s`
+
+### 📊 Compatibility Matrix
+
+| Distribution | Status | Exit Code | Time | Diagnostic & Recommendation |
+| :--- | :---: | :---: | :---: | :--- |
+| `debian:12-slim` | ✅ PASS | `0` | `0.42s` | OK |
+| `ubuntu:22.04` | ✅ PASS | `0` | `0.38s` | OK |
+| `ubuntu:24.04` | ✅ PASS | `0` | `0.35s` | OK |
+| `alpine:3.20` | ❌ FAIL | `127` | `0.19s` | ⚠️ Missing command: `apt-get` (line 4)<br>💡 *Alpine normally uses apk instead of apt-get.* |
+
+<details>
+<summary>📋 <b>Copyable Markdown (Click to expand & copy to PR / Issue)</b></summary>
+...
+</details>
+```
+
+---
+
+## 🔍 Example: What Static Analysis Misses
+
+Consider this clean 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 syntactically valid POSIX shell.
+
+However, when verified with **OpsScript Gate**:
+
+```text
++----------------+----------+-----------+----------+------------------------------------+
+| Distro         | Status   | Exit Code | Duration | Details                            |
++----------------+----------+-----------+----------+------------------------------------+
+| debian:12-slim | PASS     | 0         | 0.42s    | OK                                 |
+| ubuntu:22.04   | PASS     | 0         | 0.38s    | OK                                 |
+| ubuntu:24.04   | PASS     | 0         | 0.35s    | OK                                 |
+| alpine:3.20    | FAIL     | 127       | 0.19s    | command not found: apt-get (line 4)|
++----------------+----------+-----------+----------+------------------------------------+
+Total duration: 0.58s | Result: FAILED
+
+Remediation Recommendations:
+  * [alpine:3.20] Alpine normally uses apk instead of apt-get.
+
+============================================================
+Failed Distributions - Output Snippets (last 15 lines):
+============================================================
+
+--- [alpine:3.20] (FAIL) ---
+sh: line 4: apt-get: not found
+```
+
+**Why it failed:** Alpine Linux is musl/BusyBox-based and uses `apk`, not `apt-get`. OpsScript Gate catches the missing command (`exit code 127`) and gives you the exact line number and conservative remediation hint before deployment.
+
+---
+
+## 🛡️ 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 |
+| **Hardened container defaults** | **Built-in (`ro`, `cap_drop`, resource limits)** | N/A | User-defined |
+| **Anti-hang stdin protection** | **Built-in (`</dev/null`, noninteractive)** | No | User-defined |
+| **Line-Level Annotations & Hints** | **Built-in (Zero config)** | Static warnings | User-defined |
+| **Parallel Matrix Execution** | **Built-in (`--jobs`)** | N/A | Manual matrix config |
+
+- **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 & Hardened Isolation
+
+OpsScript Gate is not a security sandbox for untrusted code. Containers may run as the image's default user, and Docker containers still share the host kernel.
+
+OpsScript Gate applies conservative, restricted container defaults when running scripts:
+
+1. **Restricted Container Defaults**:
+   - Containers run with `privileged=False`.
+   - All Linux capabilities are dropped: `cap_drop=["ALL"]`.
+   - Privilege escalation is disabled: `security_opt=["no-new-privileges:true"]`.
+2. **Resource Constraints**:
+   - Memory limits enforced per container (`--mem-limit`, default: `256m`).
+   - Process caps enforced to prevent fork bombs (`--pids-limit`, default: `128`).
+   - Network isolation configurable (`--network bridge` or `--network none`).
+3. **Read-Only Target Mount**:
+   - The tested script is mounted read-only (`:ro`) at `/tmp/target_script.sh`.
+   - No host directories or sensitive sockets are mounted into test containers.
+4. **Anti-Hang Deadlock Defense**:
+   - Disables TTY and stdin (`stdin_open=False`, `tty=False`).
+   - Disconnects standard input: `/bin/sh -c "... /tmp/target_script.sh </dev/null"`.
+   - Injects `DEBIAN_FRONTEND=noninteractive` and `CI=true`. Interactive prompts (`read -p`) fail immediately instead of hanging CI runners.
+5. **Hard Timeout & Container Cleanup**:
+   - Enforces configurable timeout (default: 60s). Timed-out containers are sent `SIGKILL` and marked `TIMED_OUT`.
+   - Container removal is attempted from a `finally` block in normal, failure, and timeout execution paths.
+6. **Command Injection Defense**:
+   - Workflow commands (`::error`) apply strict percent-encoding for all properties and message bodies, preventing unclassified container logs from injecting GitHub Actions workflow commands.
+7. **Windows CRLF Defense**:
+   - Automatically detects and normalizes carriage returns (`\r\n` -> `\n`) before container execution, preventing false `\r: command not found` errors.
+
+---
+
+## 📦 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 /bin/sh environment |
+
+Customize the matrix at any time via `--matrix` or Action input `matrix`.
+
+---
+
+## 🛠️ CLI Reference
+
+```text
+usage: opsscript-gate run [-h] [--matrix MATRIX] [-j JOBS] [--timeout TIMEOUT]
+                          [--format {table,markdown,json}]
+                          [--shell {posix,shebang,auto}]
+                          [--mem-limit MEM_LIMIT] [--pids-limit PIDS_LIMIT]
+                          [--network NETWORK]
+                          [script_path]
+```
+
+| Parameter | Type | Default | Description |
+| :--- | :--- | :--- | :--- |
+| `script_path` | Positional | *Optional* | Path to target shell script (auto-discovers if omitted) |
+| `-j, --jobs` | Integer | `min(2, size)` | Number of concurrent container jobs |
+| `--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` |
+| `--shell` | Choice | `posix` | Execution mode: `posix` (default), `shebang`, or `auto` |
+| `--mem-limit` | String | `256m` | Memory limit per container (e.g. `256m`, `512m`) |
+| `--pids-limit`| Integer | `128` | Maximum number of processes per container |
+| `--network` | Choice | `bridge` | Container network mode: `bridge` or `none` |
+| `--version` | Flag | - | Show version number |
+| `-h, --help` | Flag | - | Show argument help |
+
+### Shell Execution Modes (`--shell`)
+
+- **`posix`** (default): Strictly executes with `/bin/sh`, ignoring any script shebang to verify portability against minimal POSIX environments (including Alpine BusyBox).
+- **`shebang`**: Strictly honors the interpreter specified in the script's shebang (`#!/bin/sh`, `#!/bin/bash`, `#!/usr/bin/sh`, `#!/usr/bin/bash`, `#!/usr/bin/env sh`, `#!/usr/bin/env bash`). Fails immediately if shebang is missing, malformed, or unsupported.
+- **`auto`**: Honors recognized shebangs if present; safely falls back to `/bin/sh` if no shebang is present.
+
+### Exit Code Convention
+- **`0`**: All tested scripts and distributions passed (`PASS`).
+- **`1`**: At least one distribution failed (`FAIL`), timed out (`TIMED_OUT`), or errored (`ERROR`).
+
+---
+
+## 🐶 Dogfooding
+
+OpsScript Gate is actively used in [`Mresyzz/linux-dev-bootstrap`](https://github.com/Mresyzz/linux-dev-bootstrap) to validate `install.sh` across the default Debian, Ubuntu, and Alpine matrix in GitHub Actions.
+
+See the downstream workflow: [`.github/workflows/test.yml`](https://github.com/Mresyzz/linux-dev-bootstrap/blob/main/.github/workflows/test.yml).
+
+---
+
+## 🧪 Development & Testing
+
+```bash
+# Clone repository
+git clone https://github.com/Mresyzz/opsscript-gate.git
+cd opsscript-gate
+
+# Install in editable mode with test dependencies
+pip install -e .[test]
+
+# Run unit tests (Mocked, no Docker daemon required)
+pytest -v -m "not integration"
+
+# Run integration tests (Requires local Docker daemon)
+pytest -v
+```
+
+---
+
+## 📄 License
+
+OpsScript Gate is licensed under the [MIT License](LICENSE).

opsscript_gate-0.4.0/README.md

@@ -0,0 +1,273 @@
+# 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)
+[![PyPI](https://img.shields.io/pypi/v/opsscript-gate)](https://pypi.org/project/opsscript-gate/)
+[![Python Versions](https://img.shields.io/pypi/pyversions/opsscript-gate)](https://pypi.org/project/opsscript-gate/)
+[![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)
+[![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 scripts inside unprivileged Debian, Ubuntu, and Alpine containers before merge, catching environment-specific runtime failures, missing interpreters, and package-manager assumptions that static analysis cannot detect.
+
+---
+
+## ⚡ 30-Second Quickstart
+
+### In GitHub Actions (Zero Config)
+
+Drop this minimal workflow into `.github/workflows/shell-compat.yml`:
+
+```yaml
+name: Shell Compatibility Gate
+on: [pull_request, push]
+
+jobs:
+  compat:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+      - uses: Mresyzz/opsscript-gate@v0.4.0
+```
+
+> **Zero Config**: If `script-path` is omitted, OpsScript Gate automatically discovers shell scripts in your repository and tests them concurrently!
+
+Or test a specific script with custom execution modes:
+
+```yaml
+      - uses: Mresyzz/opsscript-gate@v0.4.0
+        with:
+          script-path: scripts/install.sh
+          shell: auto
+          jobs: 4
+```
+
+### In Local Terminal (CLI)
+
+Requires Python 3.10+ and a running local Docker engine:
+
+```bash
+# Install from PyPI
+pip install opsscript-gate
+
+# Run against a specific script
+opsscript-gate run ./scripts/install.sh
+
+# Or auto-discover scripts across your repository
+opsscript-gate run
+```
+
+---
+
+## 🎯 Reviewer-First Experience: What It Produces
+
+Every run of OpsScript Gate generates clean, actionable feedback right where developers and reviewers need it:
+
+### 1. Line-Level GitHub Annotations
+When a failure occurs, OpsScript Gate flags the exact script line on your Pull Request's **Files Changed** view with high-confidence diagnostics and conservative remediation hints:
+
+```text
+::error file=scripts/setup.sh,line=4,title=OpsScript Gate: [alpine:3.20] command not found: apt-get::command not found: apt-get — Alpine normally uses apk instead of apt-get.
+```
+
+### 2. GitHub Step Summary Compatibility Card
+A beautifully formatted markdown summary is automatically posted to `$GITHUB_STEP_SUMMARY`:
+
+```markdown
+## 🛡️ OpsScript Gate Compatibility Report
+
+**Target Script**: `scripts/setup.sh`  
+**Status**: ❌ **CHECKS FAILED (3/4 Passed)**  
+**Total Duration**: `1.24s`
+
+### 📊 Compatibility Matrix
+
+| Distribution | Status | Exit Code | Time | Diagnostic & Recommendation |
+| :--- | :---: | :---: | :---: | :--- |
+| `debian:12-slim` | ✅ PASS | `0` | `0.42s` | OK |
+| `ubuntu:22.04` | ✅ PASS | `0` | `0.38s` | OK |
+| `ubuntu:24.04` | ✅ PASS | `0` | `0.35s` | OK |
+| `alpine:3.20` | ❌ FAIL | `127` | `0.19s` | ⚠️ Missing command: `apt-get` (line 4)<br>💡 *Alpine normally uses apk instead of apt-get.* |
+
+<details>
+<summary>📋 <b>Copyable Markdown (Click to expand & copy to PR / Issue)</b></summary>
+...
+</details>
+```
+
+---
+
+## 🔍 Example: What Static Analysis Misses
+
+Consider this clean 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 syntactically valid POSIX shell.
+
+However, when verified with **OpsScript Gate**:
+
+```text
++----------------+----------+-----------+----------+------------------------------------+
+| Distro         | Status   | Exit Code | Duration | Details                            |
++----------------+----------+-----------+----------+------------------------------------+
+| debian:12-slim | PASS     | 0         | 0.42s    | OK                                 |
+| ubuntu:22.04   | PASS     | 0         | 0.38s    | OK                                 |
+| ubuntu:24.04   | PASS     | 0         | 0.35s    | OK                                 |
+| alpine:3.20    | FAIL     | 127       | 0.19s    | command not found: apt-get (line 4)|
++----------------+----------+-----------+----------+------------------------------------+
+Total duration: 0.58s | Result: FAILED
+
+Remediation Recommendations:
+  * [alpine:3.20] Alpine normally uses apk instead of apt-get.
+
+============================================================
+Failed Distributions - Output Snippets (last 15 lines):
+============================================================
+
+--- [alpine:3.20] (FAIL) ---
+sh: line 4: apt-get: not found
+```
+
+**Why it failed:** Alpine Linux is musl/BusyBox-based and uses `apk`, not `apt-get`. OpsScript Gate catches the missing command (`exit code 127`) and gives you the exact line number and conservative remediation hint before deployment.
+
+---
+
+## 🛡️ 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 |
+| **Hardened container defaults** | **Built-in (`ro`, `cap_drop`, resource limits)** | N/A | User-defined |
+| **Anti-hang stdin protection** | **Built-in (`</dev/null`, noninteractive)** | No | User-defined |
+| **Line-Level Annotations & Hints** | **Built-in (Zero config)** | Static warnings | User-defined |
+| **Parallel Matrix Execution** | **Built-in (`--jobs`)** | N/A | Manual matrix config |
+
+- **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 & Hardened Isolation
+
+OpsScript Gate is not a security sandbox for untrusted code. Containers may run as the image's default user, and Docker containers still share the host kernel.
+
+OpsScript Gate applies conservative, restricted container defaults when running scripts:
+
+1. **Restricted Container Defaults**:
+   - Containers run with `privileged=False`.
+   - All Linux capabilities are dropped: `cap_drop=["ALL"]`.
+   - Privilege escalation is disabled: `security_opt=["no-new-privileges:true"]`.
+2. **Resource Constraints**:
+   - Memory limits enforced per container (`--mem-limit`, default: `256m`).
+   - Process caps enforced to prevent fork bombs (`--pids-limit`, default: `128`).
+   - Network isolation configurable (`--network bridge` or `--network none`).
+3. **Read-Only Target Mount**:
+   - The tested script is mounted read-only (`:ro`) at `/tmp/target_script.sh`.
+   - No host directories or sensitive sockets are mounted into test containers.
+4. **Anti-Hang Deadlock Defense**:
+   - Disables TTY and stdin (`stdin_open=False`, `tty=False`).
+   - Disconnects standard input: `/bin/sh -c "... /tmp/target_script.sh </dev/null"`.
+   - Injects `DEBIAN_FRONTEND=noninteractive` and `CI=true`. Interactive prompts (`read -p`) fail immediately instead of hanging CI runners.
+5. **Hard Timeout & Container Cleanup**:
+   - Enforces configurable timeout (default: 60s). Timed-out containers are sent `SIGKILL` and marked `TIMED_OUT`.
+   - Container removal is attempted from a `finally` block in normal, failure, and timeout execution paths.
+6. **Command Injection Defense**:
+   - Workflow commands (`::error`) apply strict percent-encoding for all properties and message bodies, preventing unclassified container logs from injecting GitHub Actions workflow commands.
+7. **Windows CRLF Defense**:
+   - Automatically detects and normalizes carriage returns (`\r\n` -> `\n`) before container execution, preventing false `\r: command not found` errors.
+
+---
+
+## 📦 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 /bin/sh environment |
+
+Customize the matrix at any time via `--matrix` or Action input `matrix`.
+
+---
+
+## 🛠️ CLI Reference
+
+```text
+usage: opsscript-gate run [-h] [--matrix MATRIX] [-j JOBS] [--timeout TIMEOUT]
+                          [--format {table,markdown,json}]
+                          [--shell {posix,shebang,auto}]
+                          [--mem-limit MEM_LIMIT] [--pids-limit PIDS_LIMIT]
+                          [--network NETWORK]
+                          [script_path]
+```
+
+| Parameter | Type | Default | Description |
+| :--- | :--- | :--- | :--- |
+| `script_path` | Positional | *Optional* | Path to target shell script (auto-discovers if omitted) |
+| `-j, --jobs` | Integer | `min(2, size)` | Number of concurrent container jobs |
+| `--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` |
+| `--shell` | Choice | `posix` | Execution mode: `posix` (default), `shebang`, or `auto` |
+| `--mem-limit` | String | `256m` | Memory limit per container (e.g. `256m`, `512m`) |
+| `--pids-limit`| Integer | `128` | Maximum number of processes per container |
+| `--network` | Choice | `bridge` | Container network mode: `bridge` or `none` |
+| `--version` | Flag | - | Show version number |
+| `-h, --help` | Flag | - | Show argument help |
+
+### Shell Execution Modes (`--shell`)
+
+- **`posix`** (default): Strictly executes with `/bin/sh`, ignoring any script shebang to verify portability against minimal POSIX environments (including Alpine BusyBox).
+- **`shebang`**: Strictly honors the interpreter specified in the script's shebang (`#!/bin/sh`, `#!/bin/bash`, `#!/usr/bin/sh`, `#!/usr/bin/bash`, `#!/usr/bin/env sh`, `#!/usr/bin/env bash`). Fails immediately if shebang is missing, malformed, or unsupported.
+- **`auto`**: Honors recognized shebangs if present; safely falls back to `/bin/sh` if no shebang is present.
+
+### Exit Code Convention
+- **`0`**: All tested scripts and distributions passed (`PASS`).
+- **`1`**: At least one distribution failed (`FAIL`), timed out (`TIMED_OUT`), or errored (`ERROR`).
+
+---
+
+## 🐶 Dogfooding
+
+OpsScript Gate is actively used in [`Mresyzz/linux-dev-bootstrap`](https://github.com/Mresyzz/linux-dev-bootstrap) to validate `install.sh` across the default Debian, Ubuntu, and Alpine matrix in GitHub Actions.
+
+See the downstream workflow: [`.github/workflows/test.yml`](https://github.com/Mresyzz/linux-dev-bootstrap/blob/main/.github/workflows/test.yml).
+
+---
+
+## 🧪 Development & Testing
+
+```bash
+# Clone repository
+git clone https://github.com/Mresyzz/opsscript-gate.git
+cd opsscript-gate
+
+# Install in editable mode with test dependencies
+pip install -e .[test]
+
+# Run unit tests (Mocked, no Docker daemon required)
+pytest -v -m "not integration"
+
+# Run integration tests (Requires local Docker daemon)
+pytest -v
+```
+
+---
+
+## 📄 License
+
+OpsScript Gate is licensed under the [MIT License](LICENSE).

opsscript_gate-0.4.0/ROADMAP.md

@@ -0,0 +1,44 @@
+# OpsScript Gate Roadmap
+
+This roadmap tracks features delivered in recent releases and areas under consideration for future versions.
+
+---
+
+## Delivered in v0.4.0
+
+- [x] **High-confidence Line-level GitHub Actions Annotations**: Emits safe `::error` annotations linking failure lines directly on pull request file diffs.
+- [x] **Distro-aware Remediation Hints**: Conservative, testable hints for Alpine vs Debian package managers, missing bash interpreters, and core utilities.
+- [x] **Interactive Compatibility Card & Copyable Summary**: Rich GitHub Actions Step Summary table with copy-pasteable Markdown snippets for PR/Issue triage.
+- [x] **Parallel Matrix Execution (`--jobs` / `jobs`)**: Concurrent multi-container testing via `ThreadPoolExecutor` with strict matrix order preservation.
+- [x] **Hardened Resource Limits**: Added `--mem-limit` (default: 256m) and `--pids-limit` (default: 128) container controls.
+- [x] **Configurable Network Isolation (`--network none|bridge`)**: Run scripts offline when network access is not required.
+- [x] **Zero-Config Script Auto-Discovery**: Automatically discovers candidate shell scripts in repository root when `script_path` is omitted.
+- [x] **Composite Action Initialization Optimization**: Stripped redundant pip upgrade steps for rapid Action startup.
+
+---
+
+## Delivered in v0.2.0 - v0.3.0
+
+- [x] **Structured Runtime Failure Diagnostics**: Detects "command not found" errors with exit code 127 validation (v0.3.0).
+- [x] **Shebang-aware execution (`--shell shebang | auto`)**: Parses and honors recognized shebang forms (`sh`, `bash`) across distributions using fixed trusted container commands (v0.2.0).
+- [x] **Explicit POSIX mode (`--shell posix`)**: Retains `/bin/sh` baseline across all containers to verify strict POSIX portability (v0.2.0).
+
+---
+
+## Planned for Future Releases (v0.5.0+)
+
+### 1. Matrix & Distribution Presets
+- [ ] **RPM-based distributions**: Evaluate support for Enterprise Linux baselines (e.g. Rocky Linux 9, AlmaLinux, Fedora).
+- [ ] **Matrix presets**: Predefined profiles (e.g. `--preset minimal`, `--preset enterprise`, `--preset all`).
+
+### 2. Performance & Caching
+- [ ] **Docker image pre-pull & caching action**: Optional helper step to leverage GitHub Actions cache for test container base images.
+
+### 3. Pre-run Setup Hooks
+- [ ] **Script prerequisites hook**: Declarative environment setup (e.g. install custom apt packages before testing the target script).
+
+---
+
+## Suggestions & Feedback
+
+To propose an addition or share feedback on priorities, open a [Feature Request](https://github.com/Mresyzz/opsscript-gate/issues/new?template=feature_request.yml) on GitHub.