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

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

@@ -1,21 +1,24 @@
 # 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
-- `init`: non-overwriting project configuration and GitHub workflow generation.
-- Shared, strictly validated `.opsscript-gate.json` settings; explicit CLI/Action inputs win.
-- Docker-free `--dry-run` plans in text or JSON, including execution counts.
-- `minimal` and `ubuntu` distribution presets, repeatable exclusion globs and configurable discovery limit.
-- `--output` report artifacts, including failure reports; source/config overwrite protection.
-- Action inputs for configuration, presets, exclusions, preview and saved reports.
-- Chinese quickstart, configuration guide and Ubuntu/Alpine troubleshooting guide.
+- 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 now fails on overflow instead of silently testing only the first 20 scripts.
-- Discovery skips symlinks and non-files and rejects shebang prefix collisions.
-- CLI rejects non-positive limits and unsupported network modes before execution.
-- Default Action inputs no longer override a user's project configuration.
+- 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`.
@@ -31,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`).
@@ -45,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.
@@ -70,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.
 
@@ -104,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.5.0 → opsscript_gate-0.5.1}/PKG-INFO

@@ -1,7 +1,7 @@
 Metadata-Version: 2.5
 Name: opsscript-gate
-Version: 0.5.0
-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
@@ -30,7 +30,7 @@ Description-Content-Type: text/markdown
 
 [简体中文](README.zh-CN.md) · [Configuration](docs/configuration.md) · [Troubleshooting](docs/troubleshooting.md)
 
-> **ShellCheck tells you if your script looks portable. OpsScript Gate checks if it actually runs there.**
+> 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)
@@ -41,17 +41,17 @@ 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.
 
 ---
 
-## New in v0.5.0
+## Current release: v0.5.1
 
-Preview exactly what will run, keep local and CI settings together, and exclude test
-fixtures before executing scripts. These controls are included in v0.5.0. Projects on
-v0.4.1 and earlier do not include them.
+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
@@ -69,11 +69,14 @@ 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).
 
-## ⚡ 30-Second Quickstart
+## Quickstart
 
-### In GitHub Actions (Zero Config)
+### In GitHub Actions
 
-Drop this minimal workflow into `.github/workflows/shell-compat.yml`:
+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
@@ -84,15 +87,16 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v7
-      - uses: Mresyzz/opsscript-gate@v0.5.0
+      - uses: Mresyzz/opsscript-gate@v0.5.1
 ```
 
-> **Zero Config**: If `script-path` is omitted, OpsScript Gate automatically discovers shell scripts in your repository. Scripts run sequentially, with concurrent distribution checks for each script. Preview discovery before running unfamiliar repositories.
+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.5.0
+      - uses: Mresyzz/opsscript-gate@v0.5.1
         with:
           script-path: scripts/install.sh
           shell: auto
@@ -114,7 +118,7 @@ opsscript-gate run ./scripts/install.sh
 opsscript-gate run
 ```
 
-### Try a Real Failure in 30 Seconds
+### Example: package-manager mismatch
 
 Create `install.sh`:
 
@@ -141,23 +145,23 @@ Alpine 3.20      FAIL
 apt-get: not found
 ```
 
-The script is valid shell, but the runtime environment is incompatible. That is exactly the class of failure OpsScript Gate is designed to catch.
+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
@@ -176,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:
 
@@ -220,37 +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 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.
 
 <details>
 <summary><strong>View security boundaries and runtime hardening details</strong></summary>
 
-OpsScript Gate applies conservative, restricted container defaults when running scripts:
+The runner uses restricted container defaults:
 
 1. **Restricted Container Defaults**:
    - Containers run with `privileged=False`.
@@ -300,7 +305,7 @@ Use it when you want to know whether a shell script actually runs across the sup
 
 ---
 
-## 📦 Default Test Matrix
+## Default test matrix
 
 | Image | Distribution | Focus |
 | :--- | :--- | :--- |
@@ -313,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]
@@ -366,9 +371,9 @@ usage: opsscript-gate run [-h] [--matrix MATRIX] [-j JOBS] [--timeout TIMEOUT]
 Explicit CLI options override project settings. Explicit script paths bypass discovery
 and its exclusions. See [complete configuration semantics](docs/configuration.md).
 
-## 🌍 Real-World Usage
+## Downstream example
 
-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.
+[`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).
 
@@ -393,11 +398,9 @@ pytest -v
 
 ---
 
-## 💛 If OpsScript Gate Helps
-
-If OpsScript Gate catches a compatibility problem in one of your scripts, consider starring the repository so other shell and DevOps maintainers can find it too.
+## Feedback
 
-Bug reports, real-world compatibility cases, and pull requests are especially welcome.
+Please report compatibility cases, bugs, and pull requests in the issue tracker.
 
 ---
 

{opsscript_gate-0.5.0 → opsscript_gate-0.5.1}/README.md

@@ -2,7 +2,7 @@
 
 [简体中文](README.zh-CN.md) · [Configuration](docs/configuration.md) · [Troubleshooting](docs/troubleshooting.md)
 
-> **ShellCheck tells you if your script looks portable. OpsScript Gate checks if it actually runs there.**
+> 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)
@@ -13,17 +13,17 @@
 [![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.
 
 ---
 
-## New in v0.5.0
+## Current release: v0.5.1
 
-Preview exactly what will run, keep local and CI settings together, and exclude test
-fixtures before executing scripts. These controls are included in v0.5.0. Projects on
-v0.4.1 and earlier do not include them.
+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
@@ -41,11 +41,14 @@ 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).
 
-## ⚡ 30-Second Quickstart
+## Quickstart
 
-### In GitHub Actions (Zero Config)
+### In GitHub Actions
 
-Drop this minimal workflow into `.github/workflows/shell-compat.yml`:
+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
@@ -56,15 +59,16 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v7
-      - uses: Mresyzz/opsscript-gate@v0.5.0
+      - uses: Mresyzz/opsscript-gate@v0.5.1
 ```
 
-> **Zero Config**: If `script-path` is omitted, OpsScript Gate automatically discovers shell scripts in your repository. Scripts run sequentially, with concurrent distribution checks for each script. Preview discovery before running unfamiliar repositories.
+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.5.0
+      - uses: Mresyzz/opsscript-gate@v0.5.1
         with:
           script-path: scripts/install.sh
           shell: auto
@@ -86,7 +90,7 @@ opsscript-gate run ./scripts/install.sh
 opsscript-gate run
 ```
 
-### Try a Real Failure in 30 Seconds
+### Example: package-manager mismatch
 
 Create `install.sh`:
 
@@ -113,23 +117,23 @@ Alpine 3.20      FAIL
 apt-get: not found
 ```
 
-The script is valid shell, but the runtime environment is incompatible. That is exactly the class of failure OpsScript Gate is designed to catch.
+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
@@ -148,14 +152,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:
 
@@ -192,37 +196,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 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.
 
 <details>
 <summary><strong>View security boundaries and runtime hardening details</strong></summary>
 
-OpsScript Gate applies conservative, restricted container defaults when running scripts:
+The runner uses restricted container defaults:
 
 1. **Restricted Container Defaults**:
    - Containers run with `privileged=False`.
@@ -272,7 +277,7 @@ Use it when you want to know whether a shell script actually runs across the sup
 
 ---
 
-## 📦 Default Test Matrix
+## Default test matrix
 
 | Image | Distribution | Focus |
 | :--- | :--- | :--- |
@@ -285,7 +290,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]
@@ -338,9 +343,9 @@ usage: opsscript-gate run [-h] [--matrix MATRIX] [-j JOBS] [--timeout TIMEOUT]
 Explicit CLI options override project settings. Explicit script paths bypass discovery
 and its exclusions. See [complete configuration semantics](docs/configuration.md).
 
-## 🌍 Real-World Usage
+## Downstream example
 
-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.
+[`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).
 
@@ -365,11 +370,9 @@ pytest -v
 
 ---
 
-## 💛 If OpsScript Gate Helps
-
-If OpsScript Gate catches a compatibility problem in one of your scripts, consider starring the repository so other shell and DevOps maintainers can find it too.
+## Feedback
 
-Bug reports, real-world compatibility cases, and pull requests are especially welcome.
+Please report compatibility cases, bugs, and pull requests in the issue tracker.
 
 ---
 

{opsscript_gate-0.5.0 → opsscript_gate-0.5.1}/README.zh-CN.md

@@ -8,9 +8,9 @@ Bash 依赖、包管理器假设和交互式阻塞。它与 ShellCheck 互补。
 适合独立安装脚本、容器入口脚本和发布脚本。每次只挂载目标脚本，
 不挂载整个仓库；依赖其他仓库文件的脚本需要现有项目测试配合。
 
-## 试用本次 v0.5.0 更新
+## 当前版本 v0.5.1
 
-v0.5.0 已作为正式版本发布；如果你要从源码验证当前分支，也可以执行：
+v0.5.1 已作为正式版本发布；如果你要从源码验证当前分支，也可以执行：
 
 ```bash
 pip install -e .
@@ -25,7 +25,7 @@ opsscript-gate run --dry-run
 opsscript-gate run --format json --output reports/compatibility.json
 ```
 
-`init` 生成配置和 GitHub 工作流，不覆盖已有文件。工作流引用 `v0.5.0`。
+`init` 生成配置和 GitHub 工作流，不覆盖已有文件。工作流引用 `v0.5.1`。
 预览不需要 Docker；真实运行需要 Python 3.10+
 和可访问的 Linux Docker 引擎。
 

{opsscript_gate-0.5.0 → opsscript_gate-0.5.1}/action.yml

@@ -1,5 +1,5 @@
 name: 'OpsScript Gate'
-description: 'Run Linux shell scripts across Debian, Ubuntu and Alpine before release to catch runtime compatibility failures'
+description: 'Run Linux shell scripts in Debian, Ubuntu and Alpine containers to catch runtime compatibility failures before merge'
 author: 'Mresyzz'
 branding:
   icon: 'shield'

{opsscript_gate-0.5.0 → opsscript_gate-0.5.1}/docs/configuration.md

@@ -11,7 +11,7 @@ opsscript-gate run --dry-run
 ```
 
 `init` refuses to overwrite either `.opsscript-gate.json` or
-`.github/workflows/opsscript-gate.yml`. The generated workflow uses the v0.5.0 tag.
+`.github/workflows/opsscript-gate.yml`. The generated workflow uses the v0.5.1 tag.
 
 The generated config uses the two-image `minimal` preset, honors recognized shell
 shebangs, disables networking, and excludes `tests/*` and `examples/*`. Review these
@@ -90,7 +90,7 @@ The Action accepts matching `config`, `preset`, `max-scripts`, `dry-run`, and `o
 inputs; `exclude` is a multiline list. Omitted execution inputs preserve config values.
 
 ```yaml
-- uses: Mresyzz/opsscript-gate@v0.5.0
+- uses: Mresyzz/opsscript-gate@v0.5.1
   with:
     config: .opsscript-gate.json
     format: json

{opsscript_gate-0.5.0 → opsscript_gate-0.5.1}/examples/alpine-incompatibility/README.md

@@ -1,6 +1,7 @@
 # Alpine Incompatibility Example
 
-This example illustrates a common production issue: an ops script implicitly relies on `apt-get`, which works seamlessly on Debian and Ubuntu, but fails instantly on Alpine (which uses `apk`).
+This example shows a common portability issue: a script calls `apt-get`, which is
+available on Debian and Ubuntu but not on Alpine, where the package manager is `apk`.
 
 Static linters like ShellCheck usually cannot determine if `apt-get` exists on the target runtime system, but OpsScript Gate catches this immediately.
 

{opsscript_gate-0.5.0 → opsscript_gate-0.5.1}/examples/github-actions/README.md

@@ -1,5 +1,5 @@
 # GitHub Actions Integration Example
 
-This example demonstrates how to integrate OpsScript Gate into a production pull request pipeline.
+This example shows a GitHub Actions workflow for checking a shell script on pull requests.
 
-Copy `workflow.yml` into your repository at `.github/workflows/script-gate.yml` and point `script-path` to the script you want to validate.
+Copy `workflow.yml` into your repository at `.github/workflows/script-gate.yml` and point `script-path` to the script you want to validate. The example uses the current v0.5.1 Action release.

{opsscript_gate-0.5.0 → opsscript_gate-0.5.1}/examples/github-actions/workflow.yml

@@ -15,9 +15,11 @@ jobs:
     steps:
       - name: Checkout repository
         uses: actions/checkout@v7
+        with:
+          persist-credentials: false
 
       - name: Run OpsScript Gate
-        uses: Mresyzz/opsscript-gate@v0.3.0
+        uses: Mresyzz/opsscript-gate@v0.5.1
         with:
           script-path: 'scripts/deploy.sh'
           shell: auto

{opsscript_gate-0.5.0 → opsscript_gate-0.5.1}/pyproject.toml

@@ -4,8 +4,8 @@ build-backend = "hatchling.build"
 
 [project]
 name = "opsscript-gate"
-version = "0.5.0"
-description = "Run Linux shell scripts across Debian, Ubuntu and Alpine before release to catch runtime compatibility failures"
+version = "0.5.1"
+description = "Run Linux shell scripts in Debian, Ubuntu and Alpine containers to catch runtime compatibility failures before merge"
 readme = "README.md"
 license = { text = "MIT" }
 requires-python = ">=3.10"

{opsscript_gate-0.5.0 → opsscript_gate-0.5.1}/src/opsscript_gate/__init__.py

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

{opsscript_gate-0.5.0 → opsscript_gate-0.5.1}/src/opsscript_gate/config.py

@@ -63,7 +63,7 @@ jobs:
       - uses: actions/checkout@v7
         with:
           persist-credentials: false
-      - uses: Mresyzz/opsscript-gate@v0.5.0
+      - uses: Mresyzz/opsscript-gate@v0.5.1
         with:
           config: .opsscript-gate.json
 """,

opsscript_gate-0.5.0/docs/promotion/awesome-lists-pr.md

@@ -1,59 +0,0 @@
-# Awesome Lists 提交收录指南与 PR 模板
-
-提交至权威的 GitHub Awesome Lists 可以带来长尾的高权重自然流量和反向链接。以下为推荐提交的目标仓库与对应的建议提交内容。
-
----
-
-## 1. 目标仓库一: `sdras/awesome-actions`
-- **仓库地址**: https://github.com/sdras/awesome-actions
-- **推荐分类小节**: `Continuous Integration` 或 `Utility`
-- **PR 标题**:
-  ```text
-  Add OpsScript Gate to Continuous Integration section
-  ```
-- **添加的 Markdown 行**:
-  ```markdown
-  - [OpsScript Gate](https://github.com/Mresyzz/opsscript-gate) - Run shell scripts across Debian, Ubuntu, and Alpine containers to catch runtime compatibility failures.
-  ```
-
----
-
-## 2. 目标仓库二: `alebcay/awesome-shell`
-- **仓库地址**: https://github.com/alebcay/awesome-shell
-- **推荐分类小节**: `Testing` 或 `Continuous Integration`
-- **PR 标题**:
-  ```text
-  Add opsscript-gate to Testing section
-  ```
-- **添加的 Markdown 行**:
-  ```markdown
-  - [OpsScript Gate](https://github.com/Mresyzz/opsscript-gate) - Drop-in runtime compatibility gate for Linux shell scripts across multiple container distributions.
-  ```
-
----
-
-## 3. 目标仓库三: `uhub/awesome-devops`
-- **仓库地址**: https://github.com/uhub/awesome-devops
-- **推荐分类小节**: `CI/CD & Automation Tools`
-- **PR 标题**:
-  ```text
-  Add OpsScript Gate to CI/CD tools
-  ```
-- **添加的 Markdown 行**:
-  ```markdown
-  - [OpsScript Gate](https://github.com/Mresyzz/opsscript-gate) - Lightweight multi-distro container gate verifying shell script portability before release.
-  ```
-
----
-
-## 提交 PR 时的通用描述模板 (PR Body)
-
-```markdown
-### Summary
-
-This PR adds [OpsScript Gate](https://github.com/Mresyzz/opsscript-gate) to the list.
-
-- **What it does**: A lightweight GitHub Action & CLI that runs shell scripts across Debian, Ubuntu, and Alpine Docker containers to catch runtime compatibility failures (missing package managers, unhandled interactive prompts, missing interpreters) that static analysis cannot catch.
-- **License**: MIT
-- **Format compliance**: Formatted alphabetically and according to the repository contribution guidelines.
-```

opsscript_gate-0.5.0/docs/promotion/juejin-zhihu-article.md

@@ -1,144 +0,0 @@
-# 深度技术文章模版：掘金 / 知乎 / 微信公众号
-
-## 标题推荐
-- 主标题: **为什么 ShellCheck 检查全绿的 Shell 脚本，在 Alpine 容器里依然会挂？**
-- 副标题: **浅谈 Linux 跨发行版脚本兼容性陷阱与自动化容器门禁实践**
-
----
-
-## 正文大纲与精炼稿
-
-在云原生与容器化时代，许多开源项目或企业内部运维平台都会提供类似这样的一键部署脚本：
-
-```bash
-curl -fsSL https://example.com/install.sh | sh
-```
-
-为了保证脚本质量，大多数团队会在 CI（持续集成）流水线中引入业界公认的静态检查神级工具——**ShellCheck**。
-
-当 CI 中 ShellCheck 的绿色勾勾亮起，提示 `No issues detected` 时，大家通常都会长舒一口气，以为这个脚本可以在所有 Linux 机器上高枕无忧地运行了。
-
-然而，一旦有用户在 Alpine 容器、Debian-slim 精简镜像、或者嵌入式系统上执行该脚本时，事故往往随之而来。
-
----
-
-### 一、ShellCheck 的能力边界：静态 AST 与真实运行时的鸿沟
-
-ShellCheck 极其优秀，它能够通过静态语法分析（AST Parsing）帮我们捕获绝大多数常见的语法雷区：
-1. 变量未用双引号包裹导致的单词拆分与 Glob 扩展（`SC2086`）；
-2. 误用单括号 `[` 与双括号 `[[` 的 Bashism 语法（`SC3010`）；
-3. 管道子 Shell 中的变量丢失（`SC2031`）。
-
-**但是，ShellCheck 无法感知运行时环境（Runtime Environment）！**
-
-看下面这段极其常见的安装脚本片段：
-
-```bash
-#!/bin/sh
-set -e
-
-echo "正在更新软件包列表..."
-apt-get update -y
-apt-get install -y curl jq
-```
-
-如果你运行 `shellcheck script.sh`，报告必定是 **0 warnings, 0 errors**。  
-因为从 POSIX Shell 的语法层面来看，这段代码无可挑剔：
-- 声明了标准的 `#!/bin/sh`；
-- 使用了规范的变量与传参；
-- 没有使用任何未定义的保留语法。
-
-**但只要把它扔进 Alpine Linux 3.20 容器中执行，它会当场暴毙：**
-
-```text
-/tmp/target_script.sh: line 4: apt-get: not found
-```
-
-因为 Alpine Linux 采用的是轻量级的 `musl libc` 与 `BusyBox`，其内置的包管理器是 `apk`，根本没有 `apt-get`！
-
-除了包管理器缺失，还有更多静态检查无法覆盖的经典痛点：
-1. **解释器路径不存在**：脚本第一行写了 `#!/bin/bash`，但最小化镜像里只预装了 `/bin/sh`；
-2. **交互式挂死（Interactive Hang）**：脚本中某处调用命令忘记加 `-y`，或者第三方工具弹出了 `Press [Enter] to continue`，导致 CI 进程永久阻塞，直到流水线超时强杀；
-3. **CRLF 换行符假性失败**：Windows 贡献者提交的脚本携带 `\r\n`，在 Linux 容器中执行时莫名其妙报错 `\r: command not found`。
-
----
-
-### 二、传统多系统验证方式的繁重成本
-
-为了规避上述问题，许多成熟开源项目开始在 GitHub Actions 中搭建手写的 Docker Matrix：
-
-```yaml
-# 传统手写 Matrix 的配置开销
-strategy:
-  matrix:
-    distro: ['debian:12-slim', 'ubuntu:22.04', 'ubuntu:24.04', 'alpine:3.20']
-```
-
-但这样很快会遇到新的工程痛点：
-- 每个项目都要复制粘贴 50~80 行复杂的 Docker 挂载、权限配置、超时脚本；
-- 容器安全权限难以管控（一不小心挂载了敏感目录或赋予了特权）；
-- 当某个发行版挂掉时，开发者必须在几千行 Actions 日志中费力翻找到底哪一行报了 127。
-
----
-
-### 三、破局方案：轻量级跨发行版执行门禁 OpsScript Gate
-
-为了彻底解决“静态检查全绿但运行时依然挂”的痛点，同时免去手写复杂 Docker 流水线的负担，我们开源了轻量级门禁工具：**OpsScript Gate**。
-
-> **项目定位：**  
-> *"ShellCheck tells you if your script looks portable.  
-> OpsScript Gate checks if it actually runs there."*  
-> （ShellCheck 检查脚本看起来是否便携，OpsScript Gate 验证它在真实环境到底能不能跑通。）
-
-#### 核心设计考量
-
-1. **多发行版开箱即跑**：  
-   默认同时编排运行在主流基底上：
-   - `debian:12-slim`（Glibc + APT 最小基底）
-   - `ubuntu:22.04` / `ubuntu:24.04`（主流企业 LTS 基底）
-   - `alpine:3.20`（Musl + BusyBox + APK 极简基底）
-
-2. **绝对无特权沙箱与防挂死机制**：  
-   - 待测脚本强制以只读方式挂载（`:ro`）；
-   - 彻底丢弃全部内核权限（`cap_drop=["ALL"]`），禁止提权（`no-new-privileges`）；
-   - 标准输入重定向至 `</dev/null` 并注入 `DEBIAN_FRONTEND=noninteractive`。任何尝试等待用户输入的交互式命令立刻报错退出，杜绝 CI 挂死。
-
-3. **双重置信度的缺失命令智能诊断（v0.3.0）**：  
-   结合退出码 127 与严格的 Shell 来源报错正则特征，直接在输出表格和 GitHub Actions Step Summary 中指出具体原因：
-   ```text
-   +--------------------+----------+-----------+-------------------------------------+
-   | Distro             | Status   | Exit Code | Details                             |
-   +--------------------+----------+-----------+-------------------------------------+
-   | debian:12-slim     | PASS     | 0         | OK                                  |
-   | ubuntu:22.04       | PASS     | 0         | OK                                  |
-   | ubuntu:24.04       | PASS     | 0         | OK                                  |
-   | alpine:3.20        | FAIL     | 127       | command not found: apt-get          |
-   +--------------------+----------+-----------+-------------------------------------+
-   ```
-
-4. **极简接入，不到 10 秒**：  
-   本地 CLI：
-   ```bash
-   pip install opsscript-gate
-   opsscript-gate run ./scripts/deploy.sh
-   ```
-   GitHub Actions 中仅需 5 行：
-   ```yaml
-   - uses: actions/checkout@v7
-   - uses: Mresyzz/opsscript-gate@v0.3.0
-     with:
-       script-path: scripts/deploy.sh
-       shell: auto
-   ```
-
----
-
-### 四、总结
-
-静态检查与动态预演不是非此即彼的对立关系，而是**相互补充的纵深防御体系**：
-- 用 **ShellCheck** 守住代码规范、语法健全与变量转义的第一道防线；
-- 用 **OpsScript Gate** 守住真实多发行版容器环境、依赖命令与解释器可执行性的最终红线。
-
-- 项目地址：https://github.com/Mresyzz/opsscript-gate
-- PyPI：https://pypi.org/project/opsscript-gate/
-- 欢迎大家 Star 关注与交流讨论！

opsscript_gate-0.5.0/docs/promotion/reddit-devops.md

@@ -1,56 +0,0 @@
-# Reddit 社区推广指南与发帖模版
-
-## 1. 目标 Subreddit
-1. **r/devops** (重点，讨论 CI/CD 与自动化脚本质量)
-2. **r/bash** (讨论 Shell 脚本编写与跨平台兼容)
-3. **r/linuxadmin** (系统管理与运维实践)
-4. **r/githubactions** (GitHub Actions 用户群体)
-
----
-
-## 2. 标题 (Title 备选)
-- **选项 A (痛点直击型)**:
-  `ShellCheck said our script was portable. Alpine killed it instantly. So I built a 0-config container matrix gate.`
-- **选项 B (工具分享型)**:
-  `OpsScript Gate – A lightweight GitHub Action & CLI to test shell scripts across Debian, Ubuntu, and Alpine containers`
-
----
-
-## 3. 正文模版 (Post Body)
-
-```markdown
-Hi r/devops!
-
-Like many of you, I maintain bootstrap scripts (`install.sh`, `setup.sh`) that users run across various Linux distros.
-
-For a long time, we relied solely on **ShellCheck** in our CI pipeline. ShellCheck is fantastic for finding unquoted variables and syntax bugs, but it consistently missed environment-specific runtime issues:
-- Calling `apt-get` on Alpine Linux (which uses `apk`)
-- Requiring `/bin/bash` when the base container only has `/bin/sh`
-- A subtle subshell or flag behavior differences between Debian `dash` and Alpine `ash`
-- Scripts freezing the CI runner indefinitely on an unexpected `read -p` prompt
-
-Running full multi-machine matrices or writing custom Docker boilerplate for every repo became tedious, so I created **OpsScript Gate**:
-
-🔗 GitHub: https://github.com/Mresyzz/opsscript-gate
-📦 PyPI: `pip install opsscript-gate`
-
-### What it does:
-1. **Multi-Distro Execution**: Runs your script across `debian:12-slim`, `ubuntu:22.04`, `ubuntu:24.04`, and `alpine:3.20` in parallel or series.
-2. **Strict Security Defaults**: Unprivileged containers, all Linux capabilities dropped (`CAP_DROP=ALL`), read-only mount, and `no-new-privileges`.
-3. **Deadlock & Hang Prevention**: Automatically redirects stdin from `/dev/null` and enforces non-interactive environment variables, killing interactive prompts immediately.
-4. **Actionable Diagnostics**: Uses dual-signal detection (exit 127 + shell pattern matching) to identify missing commands directly in the summary table without requiring users to parse hundreds of lines of logs.
-5. **Drop-in CI Integration**: 5 lines of YAML in GitHub Actions:
-
-```yaml
-- uses: actions/checkout@v7
-- uses: Mresyzz/opsscript-gate@v0.3.0
-  with:
-    script-path: scripts/install.sh
-    shell: auto
-```
-
-Project positioning:
-> *"ShellCheck tells you if your script looks portable. OpsScript Gate checks if it actually runs there."*
-
-Feedback, issues, and contributions are very welcome! How do you currently guard against distro runtime breakages in your deployment scripts?
-```

opsscript_gate-0.5.0/docs/promotion/show-hn.md

@@ -1,67 +0,0 @@
-# Hacker News Show HN 推广指南与发帖模版
-
-## 1. 发布建议
-- **目标板块**: [Hacker News Show HN](https://news.ycombinator.com/showhn.html)
-- **黄金发布时间**:
-  - 北京时间: **周二至周四 晚上 21:00 ~ 23:00**
-  - 对应美西时间: 早上 06:00 ~ 08:00（美东 09:00 ~ 11:00，此时 HN 流量高峰开启）
-- **发帖建议**:
-  - 不要带营销色彩，HN 极客崇尚第一性原理、代码开源、架构简单、无废话。
-  - 发布后在首楼积极、专业地回复评论。
-
----
-
-## 2. 标题 (Title)
-```text
-Show HN: OpsScript Gate – ShellCheck passes, but will your script run on Alpine?
-```
-*(备选标题: Show HN: OpsScript Gate – Zero-config container matrix gate for shell scripts)*
-
----
-
-## 3. 正文 (URL / Text)
-*如果是发 Text Post (推荐)，直接粘贴以下内容；如果发 Link Post，将 URL 设为 `https://github.com/Mresyzz/opsscript-gate` 并在首楼回复以下内容:*
-
-```markdown
-Hey HN,
-
-We've all seen this happen: a team member writes an install.sh or bootstrap script, runs ShellCheck (0 warnings, valid POSIX syntax), and ships it.
-
-Then an issue arrives:
-"Script failed on Alpine Linux: line 4: apt-get: not found"
-(or "bash: not found", or a subtle dash vs ash incompatibility).
-
-Static analysis (like ShellCheck) is indispensable for quoting, AST validity, and detecting bashisms. But it cannot know whether the utilities, package managers, interpreters, or flags your script relies on actually exist inside minimal runtime environments.
-
-I built OpsScript Gate to solve this: https://github.com/Mresyzz/opsscript-gate
-
-What it does:
-- Runs your target script in isolated, unprivileged Docker containers across Debian 12, Ubuntu 22.04, Ubuntu 24.04, and Alpine 3.20.
-- Hardened container defaults: CAP_DROP=ALL, no-new-privileges, read-only script mounts, and stdin redirected from /dev/null so scripts can't deadlock CI on unhandled interactive prompts.
-- Extracts high-confidence failure diagnostics (e.g. requires exit code 127 + shell 'not found' pattern) to tell you exactly which command was missing without digging through logs.
-- Can be used locally via CLI (`pip install opsscript-gate`) or dropped into GitHub Actions in 5 lines of YAML:
-
-```yaml
-- uses: actions/checkout@v7
-- uses: Mresyzz/opsscript-gate@v0.3.0
-  with:
-    script-path: scripts/setup.sh
-    shell: auto
-```
-
-The positioning:
-"ShellCheck tells you if your script looks portable.
-OpsScript Gate checks if it actually runs there."
-
-It is fully open source (MIT). I'd love to hear your thoughts, feedback, and how you currently validate multi-distro shell scripts in CI!
-```
-
----
-
-## 4. 常见 HN 评论预设答疑 (Q&A Cheatsheet)
-
-- **Q: Why not just use Docker matrix in GitHub Actions directly?**
-  - **A**: Writing a custom matrix for every repository requires copying 50+ lines of workflow YAML, managing volume mounts, handling CRLF carriage returns from Windows contributors, setting timeouts, and parsing logs when a distro fails. OpsScript Gate packages all of this into a single self-contained action/CLI step with unified summary reporting.
-
-- **Q: Is it safe to run untrusted PR scripts?**
-  - **A**: OpsScript Gate runs containers with `privileged=False`, drops all Linux capabilities (`CAP_DROP=ALL`), sets `no-new-privileges:true`, and mounts the script as read-only (`:ro`). While Docker containerization is not a complete hypervisor sandbox, these defaults strictly limit attack surface during CI evaluation.

opsscript_gate-0.5.0/docs/promotion/v2ex-post.md

@@ -1,68 +0,0 @@
-# V2EX 中文技术社区发帖模版
-
-## 1. 发布建议
-- **节点**: [分享创造](https://v2ex.com/go/create) 或 [程序员](https://v2ex.com/go/programmer)
-- **时间**: 工作日上午 10:30 ~ 11:30 或 下午 14:30 ~ 15:30（摸鱼高峰期流量最大）
-
----
-
-## 2. 标题 (Title)
-```text
-为什么 ShellCheck 检查全绿的运维脚本，在 Alpine 容器里依然会挂？做了一个开源轻量预演门禁 OpsScript Gate
-```
-
----
-
-## 3. 正文模版 (Markdown)
-
-相信很多做运维、后端或写开源工具的朋友都写过类似 `curl -fsSL https://.../install.sh | bash` 的安装脚本。
-
-我们在本地 Ubuntu / Mac 下自测通过，CI 里配置了著名的静态检查工具 **ShellCheck**，代码一查全绿，0 warnings、0 errors。满心欢喜发版后，很快就会收到 Issue：
-- “在 Alpine Linux 下执行报错：`line 4: apt-get: not found`”
-- “精简容器镜像里没有 `/bin/bash`，只有 BusyBox `/bin/sh`，脚本直接退出”
-- “脚本里的某个命令突然在交互式等待输入，CI 流水线直接卡死直到超时”
-
-### 为什么 ShellCheck 检查全绿依然会挂？
-
-因为 ShellCheck 是**纯静态 AST 分析器**。它能帮你揪出未加引号的变量扩展、语法错误或 Bashism，但它**无法感知你的脚本运行在什么具体的系统基底上**。
-- 语法是标准的 POSIX，但调用的外部命令在 Alpine/Debian-slim 镜像里根本不存在；
-- 脚本里的 Shebang 声明了 `#!/bin/bash`，但目标系统只有 `dash` 或 `ash`。
-
-为此我做了一个轻量级、开箱即用的跨发行版自动化执行门禁：**OpsScript Gate**。
-
-- 🔗 **GitHub**: https://github.com/Mresyzz/opsscript-gate
-- 📦 **PyPI**: https://pypi.org/project/opsscript-gate/
-- 🏷️ **开源协议**: MIT
-
----
-
-### 它能做什么？
-
-1. **多发行版矩阵预演**：
-   默认在标准的 `debian:12-slim`、`ubuntu:22.04`、`ubuntu:24.04` 和 `alpine:3.20` 纯净容器中同时预演运行你的脚本。
-2. **严密的无特权安全沙箱**：
-   强制无特权（`privileged=False`）、剥离全部内核 Capabilities（`CAP_DROP=ALL`）、脚本文件只读挂载（`:ro`）、禁止提权（`no-new-privileges`）。
-3. **输入挂起断流防御**：
-   强制断开标准输入（`</dev/null`）并注入非交互环境变量。一旦脚本试图弹出交互式确认（如未加 `-y` 的安装命令），立即报错退出，绝不会挂死 CI。
-4. **缺失命令精准提取（v0.3.0 新特性）**：
-   自动识别退出码 127 与 Shell 报错特征，直接在终端表格与 GitHub Step Summary 中展示 `missing command: apt-get`，不用翻查海量执行日志。
-5. **极简接入**：
-   本地一行即可运行：
-   ```bash
-   pip install opsscript-gate
-   opsscript-gate run ./scripts/setup.sh
-   ```
-   GitHub Actions 中只需 5 行代码：
-   ```yaml
-   - uses: actions/checkout@v7
-   - uses: Mresyzz/opsscript-gate@v0.3.0
-     with:
-       script-path: scripts/setup.sh
-       shell: auto
-   ```
-
-项目的核心定位是：
-> **“ShellCheck tells you if your script looks portable. OpsScript Gate checks if it actually runs there.”**
-> （ShellCheck 验证脚本语法看起来是否便携，OpsScript Gate 验证它在真实环境里到底能不能跑起来。）
-
-欢迎大家 Star、试用或提意见，也期待与大家交流日常编写跨系统 Shell 脚本时的避坑经验！