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

{opsscript_gate-0.2.1 → 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.4.0/.github/workflows/release.yml

@@ -0,0 +1,213 @@
+name: Build and Release
+
+on:
+  push:
+    branches:
+      - main
+    tags:
+      - 'v*'
+  workflow_dispatch:
+
+concurrency:
+  group: opsscript-gate-release
+  cancel-in-progress: false
+  queue: max
+
+permissions:
+  contents: read
+
+jobs:
+  test:
+    name: Run Test Suite
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout Code
+        uses: actions/checkout@v7
+
+      - name: Set up Python
+        uses: actions/setup-python@v7
+        with:
+          python-version: '3.12'
+
+      - name: Install Dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e .[test]
+
+      - name: Run Tests
+        run: |
+          pytest -v -m "not integration"
+
+  integration:
+    name: Docker Integration Tests
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout Code
+        uses: actions/checkout@v7
+
+      - name: Set up Python
+        uses: actions/setup-python@v7
+        with:
+          python-version: '3.12'
+
+      - name: Install Dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e .[test]
+
+      - name: Verify Docker Available
+        run: docker version
+
+      - name: Run Docker Integration Tests
+        run: |
+          pytest -v -m integration
+
+  build:
+    name: Build Distribution Packages
+    needs: [test, integration]
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    outputs:
+      is_new_release: ${{ steps.release-check.outputs.is_new_release }}
+      should_tag: ${{ steps.release-check.outputs.should_tag }}
+      release_tag: ${{ steps.release-check.outputs.release_tag }}
+    steps:
+      - name: Checkout Code
+        uses: actions/checkout@v7
+        with:
+          fetch-depth: 0
+
+      - name: Set up Python
+        uses: actions/setup-python@v7
+        with:
+          python-version: '3.12'
+
+      - name: Determine Release Readiness
+        id: release-check
+        shell: bash
+        run: |
+          set -euo pipefail
+
+          TOML_VERSION=$(python -c "import tomllib; f=open('pyproject.toml', 'rb'); print(tomllib.load(f)['project']['version'])")
+          INIT_VERSION=$(python -c "import sys; sys.path.insert(0, 'src'); import opsscript_gate; print(opsscript_gate.__version__)")
+
+          echo "pyproject.toml version: $TOML_VERSION"
+          echo "opsscript_gate version: $INIT_VERSION"
+
+          if [ "$TOML_VERSION" != "$INIT_VERSION" ]; then
+            echo "::error::Version mismatch: pyproject.toml ($TOML_VERSION) != __init__.py ($INIT_VERSION)"
+            exit 1
+          fi
+
+          TARGET_TAG="v$TOML_VERSION"
+          echo "Target release tag: $TARGET_TAG"
+          echo "Triggering ref: ${{ github.ref }}"
+          echo "Triggering SHA: ${{ github.sha }}"
+          echo "Triggering event: ${{ github.event_name }}"
+
+          IS_NEW_RELEASE="false"
+          SHOULD_TAG="false"
+
+          if [[ "${{ github.ref }}" =~ ^refs/tags/v ]]; then
+            TAG_VERSION="${GITHUB_REF_NAME#v}"
+            echo "Triggered via explicit Git tag: $GITHUB_REF_NAME (version: $TAG_VERSION)"
+            if [ "$TAG_VERSION" != "$TOML_VERSION" ]; then
+              echo "::error::Tag mismatch: Git tag $GITHUB_REF_NAME does not match project version $TOML_VERSION"
+              exit 1
+            fi
+            IS_NEW_RELEASE="true"
+            SHOULD_TAG="false"
+          elif [ "${{ github.ref }}" = "refs/heads/main" ]; then
+            if git rev-parse -q --verify "refs/tags/$TARGET_TAG" >/dev/null; then
+              TAG_SHA=$(git rev-list -n 1 "$TARGET_TAG")
+              echo "Tag $TARGET_TAG already exists, pointing to commit: $TAG_SHA"
+              if [ "$TAG_SHA" = "${{ github.sha }}" ]; then
+                echo "Tag $TARGET_TAG points to current commit (${{ github.sha }}). Treating as retry/resume of release."
+                IS_NEW_RELEASE="true"
+                SHOULD_TAG="false"
+              else
+                echo "Tag $TARGET_TAG was released from earlier commit ($TAG_SHA != ${{ github.sha }}). Skipping release."
+                IS_NEW_RELEASE="false"
+                SHOULD_TAG="false"
+              fi
+            else
+              echo "Target tag $TARGET_TAG does not exist. Scheduling new release for commit ${{ github.sha }}."
+              IS_NEW_RELEASE="true"
+              SHOULD_TAG="true"
+            fi
+          else
+            echo "Workflow triggered on unsupported ref (${{ github.ref }}). Release is strictly prohibited."
+            IS_NEW_RELEASE="false"
+            SHOULD_TAG="false"
+          fi
+
+          echo "is_new_release=$IS_NEW_RELEASE" >> "$GITHUB_OUTPUT"
+          echo "should_tag=$SHOULD_TAG" >> "$GITHUB_OUTPUT"
+          echo "release_tag=$TARGET_TAG" >> "$GITHUB_OUTPUT"
+
+      - name: Install build tools
+        if: steps.release-check.outputs.is_new_release == 'true'
+        run: |
+          python -m pip install --upgrade pip
+          pip install build twine
+
+      - name: Build sdist and wheel
+        if: steps.release-check.outputs.is_new_release == 'true'
+        run: |
+          python -m build
+
+      - name: Verify Package Metadata
+        if: steps.release-check.outputs.is_new_release == 'true'
+        run: |
+          python -m twine check dist/*
+
+      - name: Upload dist artifacts
+        if: steps.release-check.outputs.is_new_release == 'true'
+        uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+          retention-days: 7
+
+      - name: Create and push Git tag
+        if: steps.release-check.outputs.is_new_release == 'true' && steps.release-check.outputs.should_tag == 'true'
+        shell: bash
+        run: |
+          TARGET_TAG="${{ steps.release-check.outputs.release_tag }}"
+          echo "Creating and pushing Git tag: $TARGET_TAG pointing to commit $GITHUB_SHA"
+          git config user.name "github-actions[bot]"
+          git config user.email "github-actions[bot]@users.noreply.github.com"
+          git tag "$TARGET_TAG" "$GITHUB_SHA"
+          git push origin "$TARGET_TAG"
+
+      - name: Create GitHub Release and Upload Assets
+        uses: softprops/action-gh-release@v3
+        if: steps.release-check.outputs.is_new_release == 'true'
+        with:
+          tag_name: ${{ steps.release-check.outputs.release_tag }}
+          target_commitish: ${{ github.sha }}
+          files: dist/*
+          generate_release_notes: true
+
+  publish-pypi:
+    name: Publish to PyPI via OIDC
+    needs: [test, build]
+    if: needs.build.outputs.is_new_release == 'true'
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/opsscript-gate
+    permissions:
+      id-token: write
+    steps:
+      - name: Download dist artifacts
+        uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist
+
+      - name: Publish package distributions to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          packages-dir: dist/

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

@@ -5,6 +5,40 @@ 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
+- Structured runtime failure diagnostics: detect common "command not found" failures across Linux distributions (Alpine/BusyBox ash, Debian/Ubuntu dash, Bash, and missing interpreter paths).
+- High-confidence dual-signal classification: requires exit code 127 and matching shell output to produce a `missing_command` diagnostic.
+- Additive `diagnostic` field in JSON report format (`SingleResult.to_dict()`) providing structured diagnostic information (backward-compatible for consumers tolerating additional fields).
+- Enhanced terminal table formatting and GitHub Actions Step Summary showing clear failure causes in the summary overview.
+
+---
+
 ## [0.2.1] - 2026-09-19
 
 ### Fixed

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).