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

{opsscript_gate-0.3.0 → opsscript_gate-0.4.1}/.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.1/CHANGELOG.md

@@ -0,0 +1,114 @@
+# Changelog
+
+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.1] - 2026-09-19
+
+### Fixed & Hardened
+- **Bounded container log capture**: Stream-captures container logs using an immediate rolling byte buffer capped at 256 KiB (`MAX_CAPTURED_LOG_BYTES`) and tail limited to 500 lines (`MAX_LOG_TAIL_LINES`), bounding retained container log data to reduce memory-exhaustion risk from runaway output.
+- **Workflow command neutralization**: Neutralizes untrusted container logs starting with `::` into `[container] ::` to prevent malicious scripts from forging GitHub Actions workflow commands in Runner consoles, while keeping OpsScript Gate's own annotations intact.
+- **Terminal ANSI and control character sanitization**: Strips ANSI escape sequences (CSI, OSC, 2-byte escapes), removes dangerous C0 control characters and DEL, and normalizes CRLF and standalone carriage returns (`\r`) to defeat terminal line overwrite and status spoofing, while preserving printable Unicode.
+- **Context-sensitive Markdown and HTML injection defense**: Implemented dedicated escaping (`escape_inline_code`, `escape_markdown_text`, `escape_markdown_table_cell`, `escape_html_text`, `format_safe_code_fence`) to prevent table cell tearing, HTML container breakout (`</details>`), premature code fence closure, and structural Markdown injection from runtime-derived values.
+- **Bounded streaming script preparation**: Stream-normalizes CRLF in bounded 64 KiB chunks (`SCRIPT_READ_CHUNK_SIZE`), properly handling boundary-split CRLF while preserving lone CR bytes without whole-file memory allocation. Bounded shebang parsing to 4096 bytes (`MAX_SHEBANG_BYTES`).
+- **Parallel matrix script preparation deduplication**: Pre-normalizes scripts once before parallel matrix execution, sharing the prepared file read-only across worker threads and centralizing cleanup to eliminate file locking and race conditions on Windows.
+- **Shebang evaluation refactoring**: Deduplicated shebang resolution across `shebang` and `auto` modes via `_resolve_shell_command`.
+- **Regression test coverage**: Added extensive adversarial and edge-case tests covering oversized streams, boundary splits, workflow spoofing, Markdown injections, and error branches.
+
+---
+
+## [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
+- Strip complete ANSI CSI and OSC escape sequences from diagnostic text instead of leaving escape-sequence residue.
+- Ensure diagnostic `max_length` includes the trailing ellipsis when truncation occurs.
+- Add regression coverage for ANSI sanitization and truncation edge cases.
+
+---
+
+## [0.2.0] - 2026-09-18
+
+### Added
+- Explicit shell execution modes (`--shell posix|shebang|auto`) in CLI and GitHub Action.
+  - `posix` (default): Strictly executes with `/bin/sh`, ignoring any script shebang to verify portability against minimal POSIX environments.
+  - `shebang`: Strictly honors recognized shebang interpreters (`sh`, `bash`, `/usr/bin/env`). Fails immediately with clear diagnostics if missing, malformed, or unsupported.
+  - `auto`: Uses recognized shebang when present; safely falls back to `/bin/sh` if no shebang is present; rejects unsupported/malformed shebangs without silent fallback.
+- Exact interpreter-path preservation using fixed trusted container command constants (`SUPPORTED_SHEBANG_COMMANDS`), preventing `$PATH` resolution from masking missing paths like `/usr/bin/bash`.
+- Hardened GitHub Action input passing via step-level environment variables to eliminate shell injection risks.
+- Dedicated Docker integration test job in GitHub Actions workflow verifying real container behaviors (including bash missing on Alpine 3.20).
+- Sanitized shebang error diagnostics against control character injection and multiline pollution.
+
+---
+
+## [0.1.2] - 2026-09-18
+
+### Added
+- Configured PyPI Trusted Publishing via GitHub Actions OIDC (`pypa/gh-action-pypi-publish`).
+- Added full PyPI package metadata, classifiers, and project URLs to `pyproject.toml`.
+- Ensured absolute asset URLs in `README.md` for seamless PyPI rendering.
+
+---
+
+## [0.1.1] - 2026-09-18
+
+### Added
+- Created `examples/` directory showcasing basic setup, Alpine package manager incompatibility, and interactive hang prevention.
+- Added GitHub Issue templates for bug reports, feature requests, and distribution support requests.
+- Added `CONTRIBUTING.md`, `SECURITY.md`, and `ROADMAP.md`.
+- Enforced `security_opt=["no-new-privileges:true"]` on all container executions.
+
+### Fixed
+- Upgraded GitHub Actions dependencies to `actions/checkout@v7` and `actions/setup-python@v7` (Node 24 runtime).
+- Fixed secret referencing syntax in release workflow to ensure reliable binary asset uploads.
+
+---
+
+## [0.1.0] - 2026-09-18
+
+### Added
+- Initial MVP release of `opsscript-gate`.
+- CLI entrypoint (`opsscript-gate run <script_path>`).
+- Unprivileged container isolation engine supporting `debian:12-slim`, `ubuntu:22.04`, `ubuntu:24.04`, and `alpine:3.20`.
+- Safe read-only script mounting (`:ro`).
+- Hard per-container timeout with forced `SIGKILL` and cleanup.
+- Stdin disconnection (`</dev/null`) and non-interactive environment enforcement.
+- Windows CRLF line-ending normalization defense.
+- Unified ASCII table, GitHub Actions Step Summary Markdown, and JSON reporting formats.
+- Composite GitHub Action published to Marketplace.
+- Unit and integration test suite.

opsscript_gate-0.4.1/PKG-INFO

@@ -0,0 +1,308 @@
+Metadata-Version: 2.5
+Name: opsscript-gate
+Version: 0.4.1
+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.1
+```
+
+> **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.1
+        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. **Bounded Output & Memory Protection**:
+   - Captures container logs using an immediate rolling byte buffer capped at 256 KiB (`MAX_CAPTURED_LOG_BYTES`) and tail limited to 500 lines (`MAX_LOG_TAIL_LINES`), which bounds retained container log data to reduce memory-exhaustion risk.
+7. **Untrusted Log Neutralization & Terminal Defense**:
+   - Neutralizes line-leading workflow commands (`[container] ::`) to prevent forged GitHub Actions annotations in CI runners.
+   - Strips ANSI escape sequences and dangerous C0 control characters, and normalizes carriage returns (`\r`) to defeat terminal line overwrite spoofing.
+   - Employs context-sensitive escaping (`escape_inline_code`, `escape_markdown_text`, `escape_markdown_table_cell`, `escape_html_text`, `format_safe_code_fence`) to prevent Step Summary layout disruptions.
+8. **Command Injection Defense**:
+   - OpsScript Gate's own annotations (`::error`) apply strict percent-encoding for all properties and message bodies, preventing workflow command injection.
+9. **Bounded Streaming CRLF & Shebang Defense**:
+   - Stream-normalizes carriage returns in 64 KiB chunks, preserving lone CR bytes and bounds shebang parsing to 4096 bytes without whole-file memory allocation.
+   - Pre-normalizes scripts once before parallel matrix runs, sharing a read-only prepared path across worker threads.
+
+---
+
+## 📦 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).