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

{opsscript_gate-0.4.1 → opsscript_gate-0.5.1}/.github/workflows/test.yml

@@ -8,7 +8,11 @@ on:
 
 jobs:
   test:
-    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        os: [ubuntu-latest, windows-latest]
+        python: ['3.10', '3.12']
+    runs-on: ${{ matrix.os }}
     steps:
       - name: Checkout Code
         uses: actions/checkout@v7
@@ -16,7 +20,7 @@ jobs:
       - name: Set up Python
         uses: actions/setup-python@v7
         with:
-          python-version: '3.12'
+          python-version: ${{ matrix.python }}
 
       - name: Install Dependencies
         run: |
@@ -50,3 +54,12 @@ jobs:
       - name: Run Docker Integration Tests
         run: |
           pytest -v -m integration
+
+      - name: Exercise the local composite Action
+        uses: ./
+        with:
+          script-path: tests/fixtures/pass_basic.sh
+          preset: minimal
+          network: none
+          output: action-report.json
+          format: json

{opsscript_gate-0.4.1 → opsscript_gate-0.5.1}/CHANGELOG.md

@@ -1,5 +1,31 @@
 # Changelog
 
+## [0.5.1] - 2026-09-30
+
+### Changed
+- Published the current README and examples with the v0.5.1 Action tag.
+- Updated package and Action metadata to describe the supported container matrix and runtime compatibility check.
+
+## [0.5.0] - 2026-09-24
+
+### Added
+- Added `opsscript-gate init` to create a config file and GitHub workflow without replacing existing files.
+- Added `.opsscript-gate.json` with CLI and Action overrides.
+- Added `--dry-run`, `minimal` and `ubuntu` presets, exclusion globs, and `--output` reports.
+- Added configuration, Chinese quickstart, and Ubuntu/Alpine troubleshooting documentation.
+
+### Fixed
+- Discovery stops at the first candidate beyond the configured limit instead of silently ignoring files.
+- Discovery skips symlinks and non-files and checks shebangs without prefix matches.
+- CLI validates limits and network modes before execution.
+- Empty Action inputs no longer override project configuration.
+
+### Migration
+- Repositories with more than 20 discovered scripts must exclude unwanted scripts or raise `max_scripts`.
+- Auto-discovery no longer follows file symlinks; explicit script paths remain supported.
+- Default settings without a configuration file remain compatible with v0.4.1 and earlier.
+- Generated workflows use the v0.5.0 release tag.
+
 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/),
@@ -8,8 +34,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ## [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.
+- Bounded container log capture with a 256 KiB rolling buffer and 500-line tail.
+- Neutralized untrusted container logs beginning with `::` before they reach GitHub Actions.
 - **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`).
@@ -22,15 +48,15 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ## [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.
+- Line-level GitHub Actions annotations with script paths and line numbers.
 - **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:
+- Distro-aware remediation hints for common mismatches, including:
   - 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.
+- Updated the GitHub Actions Step Summary with a compatibility table and a Markdown result block.
 - **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.
@@ -47,7 +73,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### 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.
+- Missing-command classification requires exit code 127 and matching shell output.
 - 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.
 
@@ -81,7 +107,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ### 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.
+- Ensured asset URLs in `README.md` render correctly on PyPI.
 
 ---
 

{opsscript_gate-0.4.1 → opsscript_gate-0.5.1}/PKG-INFO

@@ -1,7 +1,7 @@
 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
+Version: 0.5.1
+Summary: Run Linux shell scripts in Debian, Ubuntu and Alpine containers to catch runtime compatibility failures before merge
 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
@@ -26,9 +26,11 @@ Provides-Extra: test
 Requires-Dist: pytest>=8.0.0; extra == 'test'
 Description-Content-Type: text/markdown
 
-# OpsScript Gate
+# OpsScript Gate — shell script compatibility testing
 
-> **ShellCheck tells you if your script looks portable. OpsScript Gate checks if it actually runs there.**
+[简体中文](README.zh-CN.md) · [Configuration](docs/configuration.md) · [Troubleshooting](docs/troubleshooting.md)
+
+> ShellCheck analyzes shell syntax. OpsScript Gate executes scripts in Linux containers.
 
 [![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)
@@ -39,15 +41,42 @@ Description-Content-Type: text/markdown
 [![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.
+**OpsScript Gate** is a runtime compatibility checker for Linux shell scripts. It executes scripts inside unprivileged Debian, Ubuntu, and Alpine containers, catching environment-specific failures, missing interpreters, and package-manager assumptions that static analysis cannot detect.
+
+It is designed for shell testing, portable shell validation, Bash/POSIX compatibility checks, and cross-distro CI where syntax-only tooling is not enough.
 
 ---
 
-## ⚡ 30-Second Quickstart
+## Current release: v0.5.1
+
+The current release includes a project config file, a dry-run plan, presets, exclusions,
+and saved reports. These controls were introduced in v0.5.0; projects on v0.4.1 and
+earlier do not include them.
+
+```bash
+opsscript-gate init
+opsscript-gate run --dry-run
+opsscript-gate run --format json --output reports/compatibility.json
+```
 
-### In GitHub Actions (Zero Config)
+`init` creates `.opsscript-gate.json` and a GitHub Actions workflow without replacing
+existing files. Review its exclusions (`tests/*`, `examples/*`) and offline network
+default before running. No Docker is required for `init` or `--dry-run`.
 
-Drop this minimal workflow into `.github/workflows/shell-compat.yml`:
+Useful for standalone installers, container entrypoints and release scripts that
+must work on both GNU/Linux and Alpine/BusyBox. Each script runs independently;
+repository files, sibling scripts and project dependencies are **not** mounted.
+See [configuration and migration](docs/configuration.md) and
+[why a shell script works on Ubuntu but fails on Alpine](docs/troubleshooting.md).
+
+## Quickstart
+
+### In GitHub Actions
+
+Add this workflow to `.github/workflows/shell-compat.yml`:
+
+You can copy the maintained example from [`examples/github-actions/workflow.yml`](examples/github-actions/workflow.yml)
+and change the `script-path`, or use the minimal workflow below.
 
 ```yaml
 name: Shell Compatibility Gate
@@ -58,15 +87,16 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v7
-      - uses: Mresyzz/opsscript-gate@v0.4.1
+      - uses: Mresyzz/opsscript-gate@v0.5.1
 ```
 
-> **Zero Config**: If `script-path` is omitted, OpsScript Gate automatically discovers shell scripts in your repository and tests them concurrently!
+If `script-path` is omitted, the action discovers shell scripts in the repository.
+Use `opsscript-gate run --dry-run` to inspect the selection before running it.
 
 Or test a specific script with custom execution modes:
 
 ```yaml
-      - uses: Mresyzz/opsscript-gate@v0.4.1
+      - uses: Mresyzz/opsscript-gate@v0.5.1
         with:
           script-path: scripts/install.sh
           shell: auto
@@ -88,21 +118,50 @@ opsscript-gate run ./scripts/install.sh
 opsscript-gate run
 ```
 
+### Example: package-manager mismatch
+
+Create `install.sh`:
+
+```sh
+#!/bin/sh
+set -e
+apt-get --version
+```
+
+Then run:
+
+```bash
+opsscript-gate run ./install.sh
+```
+
+A typical result across the default matrix looks like this:
+
+```text
+Debian 12        PASS
+Ubuntu 22.04     PASS
+Ubuntu 24.04     PASS
+Alpine 3.20      FAIL
+
+apt-get: not found
+```
+
+The script is valid shell, but it assumes a command that is not present in Alpine.
+
 ---
 
-## 🎯 Reviewer-First Experience: What It Produces
+## CI output
 
-Every run of OpsScript Gate generates clean, actionable feedback right where developers and reviewers need it:
+The action reports failures in two places:
 
-### 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:
+### GitHub annotations
+Failures include the script path, line number, distribution, and a short diagnostic:
 
 ```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`:
+### Step summary
+The action also writes a markdown matrix to `$GITHUB_STEP_SUMMARY`:
 
 ```markdown
 ## 🛡️ OpsScript Gate Compatibility Report
@@ -121,14 +180,14 @@ A beautifully formatted markdown summary is automatically posted to `$GITHUB_STE
 | `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>
+<summary><b>Markdown result</b></summary>
 ...
 </details>
 ```
 
 ---
 
-## 🔍 Example: What Static Analysis Misses
+## Example: runtime behavior that static analysis misses
 
 Consider this clean deployment script:
 
@@ -165,34 +224,38 @@ Failed Distributions - Output Snippets (last 15 lines):
 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 it failed:** Alpine uses `apk`, not `apt-get`. The report includes the missing command and its line number.
 
 ---
 
-## 🛡️ Why OpsScript Gate?
+## Scope compared with other checks
 
-### OpsScript Gate vs ShellCheck vs Custom CI Matrix
+### OpsScript Gate compared with ShellCheck and a 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 |
+| **Restricted 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 |
+| **Line-Level Annotations & Hints** | **Built-in** | 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.
+ShellCheck checks shell syntax and common mistakes. OpsScript Gate runs the script in
+real distributions. A custom CI matrix can do the same job, but each repository must
+maintain its own images, mounts, timeouts, and report handling.
 
 ---
 
-## 🔒 Security Boundaries & Hardened Isolation
+## Security boundaries and container 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 is a runtime compatibility testing tool, **not a security sandbox for hostile or fully untrusted code**. Containers still share the host kernel, so target scripts should be treated accordingly.
 
-OpsScript Gate applies conservative, restricted container defaults when running scripts:
+<details>
+<summary><strong>View security boundaries and runtime hardening details</strong></summary>
+
+The runner uses restricted container defaults:
 
 1. **Restricted Container Defaults**:
    - Containers run with `privileged=False`.
@@ -208,25 +271,41 @@ OpsScript Gate applies conservative, restricted container defaults when running
 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.
+   - Injects `DEBIAN_FRONTEND=noninteractive` and `CI=true`. Interactive prompts (`read -p`) fail 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.
+   - Captures container logs using a rolling byte buffer capped at 256 KiB (`MAX_CAPTURED_LOG_BYTES`) and a 500-line tail limit (`MAX_LOG_TAIL_LINES`) to reduce memory-exhaustion risk from runaway output.
 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.
+   - 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 protect Step Summary output contexts.
 8. **Command Injection Defense**:
-   - OpsScript Gate's own annotations (`::error`) apply strict percent-encoding for all properties and message bodies, preventing workflow command injection.
+   - OpsScript Gate's own annotations (`::error`) apply strict percent-encoding for workflow-command fields and message bodies.
 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.
+   - Stream-normalizes CRLF in 64 KiB chunks 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.
 
+For the complete supported-version policy and vulnerability reporting guidance, see [SECURITY.md](SECURITY.md).
+
+</details>
+
+### When NOT to use OpsScript Gate
+
+OpsScript Gate is intentionally focused on Linux shell runtime compatibility. It is not designed for:
+
+- executing hostile or fully untrusted third-party scripts
+- kernel-level or privileged behavior testing
+- replacing full integration or end-to-end test suites
+- validating macOS or Windows behavior
+- proving that a script is secure
+
+Use it when you want to know whether a shell script actually runs across the supported Linux distributions.
+
 ---
 
-## 📦 Default Test Matrix
+## Default test matrix
 
 | Image | Distribution | Focus |
 | :--- | :--- | :--- |
@@ -239,7 +318,7 @@ Customize the matrix at any time via `--matrix` or Action input `matrix`.
 
 ---
 
-## 🛠️ CLI Reference
+## CLI reference
 
 ```text
 usage: opsscript-gate run [-h] [--matrix MATRIX] [-j JOBS] [--timeout TIMEOUT]
@@ -276,9 +355,25 @@ usage: opsscript-gate run [-h] [--matrix MATRIX] [-j JOBS] [--timeout TIMEOUT]
 
 ---
 
-## 🐶 Dogfooding
+### v0.5.0 project controls
+
+| Option | Purpose |
+| :--- | :--- |
+| `init` | Generate configuration and a GitHub workflow without overwriting files |
+| `--dry-run` | Preview selected scripts, images and total executions without Docker |
+| `--config PATH` | Load a specific JSON configuration file |
+| `--preset minimal` | Debian + Alpine (two container runs per script) |
+| `--preset ubuntu` | Ubuntu 22.04 + 24.04 |
+| `--exclude 'tests/*'` | Exclude a repository-relative glob; repeatable |
+| `--max-scripts 50` | Raise the default discovery limit of 20; overflow is an error |
+| `--output report.json` | Save the selected output format, including failed test reports |
+
+Explicit CLI options override project settings. Explicit script paths bypass discovery
+and its exclusions. See [complete configuration semantics](docs/configuration.md).
 
-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.
+## Downstream example
+
+[`Mresyzz/linux-dev-bootstrap`](https://github.com/Mresyzz/linux-dev-bootstrap) contains a workflow that validates `install.sh` across the default Debian, Ubuntu, and Alpine matrix.
 
 See the downstream workflow: [`.github/workflows/test.yml`](https://github.com/Mresyzz/linux-dev-bootstrap/blob/main/.github/workflows/test.yml).
 
@@ -303,6 +398,12 @@ pytest -v
 
 ---
 
+## Feedback
+
+Please report compatibility cases, bugs, and pull requests in the issue tracker.
+
+---
+
 ## 📄 License
 
 OpsScript Gate is licensed under the [MIT License](LICENSE).