opsscript-gate 0.9.0__tar.gz → 0.9.2__tar.gz

opsscript_gate-0.9.2/.ai/v0.9.2_issues_report.md

@@ -0,0 +1,90 @@
+# OpsScript Gate 本地 v0.9.2 代码审查、缺陷排查与修复报告
+
+**审查与修复时间**：2026-10-05  
+**基准分支**：`codex/v0.9.2-hardening`  
+**测试套件状态**：`pytest` 177 项测试全量通过（165 passed, 12 skipped, 0 failures）
+
+---
+
+## 概述
+
+针对本地 `0.9.2` 版本在近期提交（`6260a74` 到 `cae3fbe`）及后续排查中发现的所有缺陷，进行了地毯式分析与代码修复。所有发现的问题均已完成第一性原理剖析、修复并配齐自动化回归测试。
+
+---
+
+## 本轮新发现的问题与修复记录
+
+### 1. `discovery.py` 中 `_is_ignored_path` 误将前导 `./` 路径判定为忽略项
+* **文件位置**：`src/opsscript_gate/discovery.py`
+* **问题成因**：
+  `_is_ignored_path` 将路径按 `/` 切分后遍历每个 `part`，直接使用 `part.startswith(".")`。当路径是以 `./` 开头（例如 `./scripts/install.sh` 或 `./run.sh`）时，首个 `part` 为单个点 `.`，`'.'.startswith(".")` 恒为 `True`，导致合法脚本被错误判定为忽略项。
+* **修复方案**：
+  在切分前先剥离前导 `./`，并将 `part in (".", "..")` 显式排除在隐藏目录判断之外。
+* **测试用例**：
+  新增 `tests/test_runner.py::test_is_ignored_path_dot_slash_and_hidden`。
+
+---
+
+### 2. `runner.py` 中 `_is_wait_timeout_error` 无法识别嵌套异常原因链
+* **文件位置**：`src/opsscript_gate/runner.py`
+* **问题成因**：
+  Docker SDK (urllib3 / requests) 发生超时异常时，常将底层的 `ReadTimeout` 或 `SocketTimeout` 包装在 `requests.exceptions.ConnectionError` 或顶层异常中。原函数只检查了外层异常类名，导致被包装的真实超时被误报为通信崩溃（`DistroStatus.ERROR`），且未能触发超时强杀逻辑。
+* **修复方案**：
+  在 `_is_wait_timeout_error` 中遍历 `__cause__` 与 `__context__` 异常链，全面识别深层超时错误。
+* **测试用例**：
+  新增 `tests/test_runner.py::test_is_wait_timeout_error_cause_chain`。
+
+---
+
+### 3. `cli.py` 中 `--output` 指定已有目录时缺乏前置拦截
+* **文件位置**：`src/opsscript_gate/cli.py`
+* **问题成因**：
+  若用户误将已存在的目录传给 `--output`（例如 `--output reports/` 或 `--output .`），原逻辑在跑完所有耗时的容器矩阵测试后，才在 `publish_output` 中因 `write_text` 抛出 `IsADirectoryError` 或 `PermissionError`，严重浪费时间。
+* **修复方案**：
+  在执行矩阵前增加 `if output_path.is_dir(): sys.stderr.write("Error: output must name a file, not an existing directory\n"); return 1` 提前拦截。
+* **测试用例**：
+  新增 `tests/test_runner.py::test_cli_output_rejects_existing_directory_early`。
+
+---
+
+### 4. `remediation.py` 扩充跨发行版包管理器互踩诊断规则
+* **文件位置**：`src/opsscript_gate/remediation.py`
+* **问题成因**：
+  此前仅包含 Debian/Ubuntu（apt）与 Alpine（apk）的双向匹配。当脚本在 Debian/Ubuntu/Alpine 上尝试调用 `yum` 或 `dnf`，或者在 Fedora/CentOS/RHEL 系列镜像上调用 `apt`/`apk` 时，系统只能报通用缺失错误，缺乏精准指引。
+* **修复方案**：
+  新增 `_match_debian_ubuntu_yum`、`_match_alpine_yum`、`_match_rhel_fedora_apt` 匹配器及专属修复建议。
+* **测试用例**：
+  新增 `tests/test_runner.py::test_remediation_enterprise_distro_package_rules`。
+
+---
+
+### 5. `runner.py` 中保护 `container.reload()` 避免网络抖动覆盖已取得的状态码
+* **文件位置**：`src/opsscript_gate/runner.py`
+* **问题成因**：
+  在容器执行完毕后，`container.wait()` 已返回了包含 `StatusCode` 的字典，但随后的 `container.reload()` 调用缺乏异常防护。一旦容器刚好在退出瞬间发生通信抖动，会导致原本已成功完成的测试异常崩溃。
+* **修复方案**：
+  为 `container.reload()` 增加 `try-except` 防护，优先并安全地使用已拿到的有效退出码。
+
+---
+
+### 6. `remediation.py` 中 `curl`/`wget` 绝对路径匹配与最小容器缺失 `sudo` 修复规则
+* **文件位置**：`src/opsscript_gate/remediation.py`
+* **问题成因**：
+  1. `_match_curl` 与 `_match_wget` 仅检查了命令名完全等于 `curl` / `wget`，当脚本使用 `/usr/bin/curl`、`/bin/curl` 等绝对路径调用时，无法匹配到建议规则。
+  2. 最小化 Linux 容器镜像（Debian slim、Ubuntu、Alpine 等）默认不带 `sudo`，且容器通常本身即为 root 权限。当运维脚本带有 `sudo` 时会报 `sudo: not found`，此前缺乏专属修复建议。
+* **修复方案**：
+  提取命令路径中的 basename 统一进行匹配，并新增 `_match_sudo` 规则与针对性修复建议。
+* **测试用例**：
+  新增 `tests/test_runner.py::test_remediation_curl_wget_path_and_sudo`。
+
+---
+
+## 历史排查问题的闭环确认（已在近期提交中合入）
+
+1. **`reporter.py` 中 `_sarif_path` 绝对路径转换**：已在 Commit `6a830e4` 中引入 `os.path.relpath` 与防止 `../` 逃逸的处理。
+2. **`discovery.py` 中 `discover_scripts` 过滤隐藏文件**：已在 Commit `9618874` 中过滤了 `filename.startswith(".")`。
+3. **`action.yml` 中 `dry-run` 大小写敏感**：已在 Commit `03b30ab` 中使用 `tr '[:upper:]' '[:lower:]'` 规整。
+4. **`cli.py` 中 `publish_output` 写文件失败吞没 stdout**：已在 Commit `03b30ab` 中调整为先打印控制台输出再写文件。
+5. **`runner.py` 中多轮执行代表性结果选择**：已在 Commit `6a830e4` 中优化为优先保留具备 `diagnostic` 的结果。
+6. **Docker 引擎模式检查**：已在 Commit `0b8a202` 中通过 `client.info()` 校验 `OSType == "linux"`。
+7. **资源上限守卫**：已在 Commit `cae3fbe`, `13f0730`, `373d5a0` 中为 `matrix`（最多32个）、`timeout`（最多3600秒）、`repeat`（最多20次）增加上限校验。

{opsscript_gate-0.9.0 → opsscript_gate-0.9.2}/.github/workflow-templates/opsscript-gate.yml

@@ -25,7 +25,7 @@ jobs:
           persist-credentials: false
 
       - name: Run OpsScript Gate
-        uses: Mresyzz/opsscript-gate@v0.8.3
+        uses: Mresyzz/opsscript-gate@v0.9.2
         with:
           shell: auto
           network: none

{opsscript_gate-0.9.0 → opsscript_gate-0.9.2}/.github/workflows/release.yml

@@ -123,17 +123,12 @@ jobs:
               TAG_SHA=$(git rev-list -n 1 "$TARGET_TAG")
               echo "Tag $TARGET_TAG already exists, pointing to commit: $TAG_SHA"
               if [ "$TAG_SHA" = "${{ github.sha }}" ]; then
-                echo "Tag $TARGET_TAG points to current commit (${{ github.sha }}). Treating as retry/resume of release."
-                IS_NEW_RELEASE="true"
-                SHOULD_TAG="false"
+                echo "Tag $TARGET_TAG already points to the current commit. The tag workflow owns release publication."
               else
                 echo "Tag $TARGET_TAG was released from earlier commit ($TAG_SHA != ${{ github.sha }}). Skipping release."
-                IS_NEW_RELEASE="false"
-                SHOULD_TAG="false"
               fi
             else
-              echo "Target tag $TARGET_TAG does not exist. Scheduling new release for commit ${{ github.sha }}."
-              IS_NEW_RELEASE="true"
+              echo "Target tag $TARGET_TAG does not exist. Creating it and handing publication to the tag workflow."
               SHOULD_TAG="true"
             fi
           else
@@ -171,7 +166,7 @@ jobs:
           retention-days: 7
 
       - name: Create and push Git tag
-        if: steps.release-check.outputs.is_new_release == 'true' && steps.release-check.outputs.should_tag == 'true'
+        if: steps.release-check.outputs.should_tag == 'true'
         shell: bash
         run: |
           TARGET_TAG="${{ steps.release-check.outputs.release_tag }}"

{opsscript_gate-0.9.0 → opsscript_gate-0.9.2}/CHANGELOG.md

@@ -1,5 +1,35 @@
 # Changelog
 
+## [0.9.2] - Unreleased
+
+### Fixed
+- Hardened SARIF, Markdown, terminal, and machine-readable output handling.
+- Prevented false package-setup errors, stale Docker wait results, hard-link overwrites, and unbounded log copies.
+- Added BOM-aware discovery, Windows exclusion normalization, bounded concurrency, and runtime option validation.
+- Added a one-CPU container limit and bounded Docker log rotation, while keeping disposable container filesystems writable for installers.
+- Normalized SARIF paths, preserved actionable repeat-run diagnostics, skipped hidden auto-discovered files, and kept terminal reports visible when file output fails.
+- Fixed release workflow tag handoff so a `main` push cannot publish the same version twice.
+- Made `doctor` reject Docker's Windows-container mode before Linux image checks begin.
+- Added problem-first FAQ content, structured data, canonical URLs, and AI-readable answers for runtime compatibility searches.
+- Bounded repeat runs to 20 attempts per distribution to prevent accidental unbounded container work and result retention.
+- Bounded per-container timeouts to one hour so fallback polling cannot wait indefinitely on an extreme configuration.
+- Bounded custom matrices to 32 images so a single configuration cannot create unbounded container work.
+- Fixed `_is_ignored_path` in script discovery to avoid misclassifying paths with leading `./` as ignored.
+- Traversed exception cause chains in `_is_wait_timeout_error` to reliably identify nested Docker wait timeouts.
+- Protected container reload against network jitter to preserve valid exit codes.
+- Added early validation for CLI `--output` to reject existing directories before executing test matrices.
+- Expanded cross-distro package manager diagnostics and added remediation for path-qualified curl/wget and missing sudo.
+- Refreshed active workflow templates, examples, and documentation to `v0.9.2`.
+
+## [0.9.1] - 2026-10-03
+
+### Fixed
+- Normalized discovery exclusions so top-level paths match with or without `./`.
+- Made SARIF output conform to the 2.1.0 result schema.
+- Failed closed when Docker omitted an exit code and separated package setup errors from script failures.
+- Validated project configuration in `doctor` and handled UTF-8 BOM scripts.
+- Distinguished Docker wait API errors from genuine execution timeouts.
+
 ## [0.9.0] - 2026-10-03
 
 ### Added

{opsscript_gate-0.9.0 → opsscript_gate-0.9.2}/CITATION.cff

@@ -5,8 +5,7 @@ type: software
 authors:
   - family-names: Mresyzz
     given-names: Mresy
-version: 0.9.0
-date-released: 2026-10-02
+version: 0.9.2
 repository-code: https://github.com/Mresyzz/opsscript-gate
 url: https://github.com/Mresyzz/opsscript-gate
 license: MIT

{opsscript_gate-0.9.0 → opsscript_gate-0.9.2}/PKG-INFO

@@ -1,7 +1,7 @@
 Metadata-Version: 2.5
 Name: opsscript-gate
-Version: 0.9.0
-Summary: Cross-distro shell script compatibility checker for runtime testing in Debian, Ubuntu and Alpine
+Version: 0.9.2
+Summary: Cross-distro shell script compatibility and portability checker for Debian, Ubuntu, and Alpine. Runs real containers to diagnose command not found.
 Project-URL: Homepage, https://mresyzz.github.io/opsscript-gate/
 Project-URL: Demo, https://mresyzz.github.io/opsscript-gate/
 Project-URL: Repository, https://github.com/Mresyzz/opsscript-gate
@@ -12,7 +12,7 @@ Project-URL: Troubleshooting, https://github.com/Mresyzz/opsscript-gate/blob/mai
 Author: Mresyzz
 License: MIT
 License-File: LICENSE
-Keywords: alpine,apk,apt-get,bashisms,bootstrap,busybox,ci,command-not-found,compatibility,cross-distro,debian,devops,docker,github-actions,installer,installer-testing,linux,portable-shell,posix,runtime-compatibility,shell,shell-portability,shell-script-testing,shellcheck,shellcheck-alternative,testing,ubuntu
+Keywords: alpine,apk,apt-get,bashisms,bootstrap,busybox,ci,command-not-found,compatibility,cross-distro,debian,devops,distribution-compatibility,docker,github-actions,installer,installer-testing,linux,portable-shell,posix,real-container-testing,runtime-compatibility,shell,shell-portability,shell-runtime,shell-script-testing,shellcheck,shellcheck-alternative,testing,ubuntu
 Classifier: Development Status :: 4 - Beta
 Classifier: Intended Audience :: Developers
 Classifier: Intended Audience :: System Administrators
@@ -26,6 +26,7 @@ Classifier: Topic :: System :: Systems Administration
 Requires-Python: >=3.10
 Requires-Dist: docker>=7.0.0
 Provides-Extra: test
+Requires-Dist: markdown-it-py>=3.0.0; extra == 'test'
 Requires-Dist: pytest>=8.0.0; extra == 'test'
 Description-Content-Type: text/markdown
 
@@ -79,7 +80,7 @@ apt-get --version
 Run it locally with `opsscript-gate run ./install.sh`, or add the following step to CI:
 
 ```yaml
-- uses: Mresyzz/opsscript-gate@v0.9.0
+- uses: Mresyzz/opsscript-gate@v0.9.2
   with:
     script-path: install.sh
 ```
@@ -88,7 +89,7 @@ The result identifies the failing distribution, exit code, line, missing command
 
 ---
 
-## Current release: v0.9.0
+## Current version: v0.9.2 (local candidate)
 
 The current release includes a project config file, a dry-run plan, presets, exclusions,
 saved reports, changed-script selection for pull requests, and repeat runs for detecting
@@ -142,7 +143,7 @@ jobs:
       - uses: actions/checkout@v7
         with:
           persist-credentials: false
-      - uses: Mresyzz/opsscript-gate@v0.9.0
+      - uses: Mresyzz/opsscript-gate@v0.9.2
 ```
 
 This zero-configuration form discovers shell scripts in the repository. Use
@@ -153,7 +154,7 @@ repository has a single installer. For self-hosted model installers, see the
 Or test a specific script with custom execution modes:
 
 ```yaml
-      - uses: Mresyzz/opsscript-gate@v0.9.0
+      - uses: Mresyzz/opsscript-gate@v0.9.2
         with:
           script-path: scripts/install.sh
           shell: auto
@@ -187,7 +188,7 @@ unrelated scripts:
         with:
           persist-credentials: false
           fetch-depth: 0
-      - uses: Mresyzz/opsscript-gate@v0.9.0
+      - uses: Mresyzz/opsscript-gate@v0.9.2
         with:
           changed-since: ${{ github.event.pull_request.base.sha }}
           preset: minimal
@@ -199,8 +200,8 @@ container. The same selection can be previewed locally with
 
 ### Detect intermittent runtime failures
 
-Use `--repeat N` when a script sometimes passes and sometimes fails in CI. OpsScript
-Gate runs each distribution N times and reports `FLAKY` when the same distribution has
+Use `--repeat N` when a script sometimes passes and sometimes fails in CI. Values from
+1 through 20 are accepted. OpsScript Gate runs each distribution N times and reports `FLAKY` when the same distribution has
 both passing and failing attempts. The JSON, Markdown, SARIF, annotations, and step
 summary include the attempt counts so a retry cannot silently turn an unstable script
 green.
@@ -278,7 +279,7 @@ Use `sarif` when the result should appear in GitHub Code Scanning or another
 SARIF-compatible viewer. Upload it explicitly with the official upload action:
 
 ```yaml
-- uses: Mresyzz/opsscript-gate@v0.9.0
+- uses: Mresyzz/opsscript-gate@v0.9.2
   with:
     script-path: scripts/install.sh
     format: sarif
@@ -373,9 +374,11 @@ The runner uses restricted container defaults:
 2. **Resource Constraints**:
    - Memory limits enforced per container (`--mem-limit`, default: `256m`).
    - Process caps enforced to prevent fork bombs (`--pids-limit`, default: `128`).
+   - CPU is capped at one host CPU per container and Docker's JSON log driver rotates logs.
    - 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`.
+   - The disposable container root remains writable so installers can create files during a real run.
    - 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`).
@@ -448,8 +451,8 @@ usage: opsscript-gate run [-h] [--matrix MATRIX] [-j JOBS] [--timeout TIMEOUT]
 | :--- | :--- | :--- | :--- |
 | `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 |
+| `--matrix` | String | `debian:12-slim,ubuntu:22.04,ubuntu:24.04,alpine:3.20` | Comma-separated list of Docker images (maximum `32`) |
+| `--timeout` | Integer | `60` | Hard timeout per container in seconds (maximum `3600`) |
 | `--format` | Choice | `table` | Output format: `table`, `markdown`, `json`, or `sarif` |
 | `--shell` | Choice | `posix` | Execution mode: `posix` (default), `shebang`, or `auto` |
 | `--mem-limit` | String | `256m` | Memory limit per container (e.g. `256m`, `512m`) |

{opsscript_gate-0.9.0 → opsscript_gate-0.9.2}/README.md

@@ -48,7 +48,7 @@ apt-get --version
 Run it locally with `opsscript-gate run ./install.sh`, or add the following step to CI:
 
 ```yaml
-- uses: Mresyzz/opsscript-gate@v0.9.0
+- uses: Mresyzz/opsscript-gate@v0.9.2
   with:
     script-path: install.sh
 ```
@@ -57,7 +57,7 @@ The result identifies the failing distribution, exit code, line, missing command
 
 ---
 
-## Current release: v0.9.0
+## Current version: v0.9.2 (local candidate)
 
 The current release includes a project config file, a dry-run plan, presets, exclusions,
 saved reports, changed-script selection for pull requests, and repeat runs for detecting
@@ -111,7 +111,7 @@ jobs:
       - uses: actions/checkout@v7
         with:
           persist-credentials: false
-      - uses: Mresyzz/opsscript-gate@v0.9.0
+      - uses: Mresyzz/opsscript-gate@v0.9.2
 ```
 
 This zero-configuration form discovers shell scripts in the repository. Use
@@ -122,7 +122,7 @@ repository has a single installer. For self-hosted model installers, see the
 Or test a specific script with custom execution modes:
 
 ```yaml
-      - uses: Mresyzz/opsscript-gate@v0.9.0
+      - uses: Mresyzz/opsscript-gate@v0.9.2
         with:
           script-path: scripts/install.sh
           shell: auto
@@ -156,7 +156,7 @@ unrelated scripts:
         with:
           persist-credentials: false
           fetch-depth: 0
-      - uses: Mresyzz/opsscript-gate@v0.9.0
+      - uses: Mresyzz/opsscript-gate@v0.9.2
         with:
           changed-since: ${{ github.event.pull_request.base.sha }}
           preset: minimal
@@ -168,8 +168,8 @@ container. The same selection can be previewed locally with
 
 ### Detect intermittent runtime failures
 
-Use `--repeat N` when a script sometimes passes and sometimes fails in CI. OpsScript
-Gate runs each distribution N times and reports `FLAKY` when the same distribution has
+Use `--repeat N` when a script sometimes passes and sometimes fails in CI. Values from
+1 through 20 are accepted. OpsScript Gate runs each distribution N times and reports `FLAKY` when the same distribution has
 both passing and failing attempts. The JSON, Markdown, SARIF, annotations, and step
 summary include the attempt counts so a retry cannot silently turn an unstable script
 green.
@@ -247,7 +247,7 @@ Use `sarif` when the result should appear in GitHub Code Scanning or another
 SARIF-compatible viewer. Upload it explicitly with the official upload action:
 
 ```yaml
-- uses: Mresyzz/opsscript-gate@v0.9.0
+- uses: Mresyzz/opsscript-gate@v0.9.2
   with:
     script-path: scripts/install.sh
     format: sarif
@@ -342,9 +342,11 @@ The runner uses restricted container defaults:
 2. **Resource Constraints**:
    - Memory limits enforced per container (`--mem-limit`, default: `256m`).
    - Process caps enforced to prevent fork bombs (`--pids-limit`, default: `128`).
+   - CPU is capped at one host CPU per container and Docker's JSON log driver rotates logs.
    - 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`.
+   - The disposable container root remains writable so installers can create files during a real run.
    - 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`).
@@ -417,8 +419,8 @@ usage: opsscript-gate run [-h] [--matrix MATRIX] [-j JOBS] [--timeout TIMEOUT]
 | :--- | :--- | :--- | :--- |
 | `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 |
+| `--matrix` | String | `debian:12-slim,ubuntu:22.04,ubuntu:24.04,alpine:3.20` | Comma-separated list of Docker images (maximum `32`) |
+| `--timeout` | Integer | `60` | Hard timeout per container in seconds (maximum `3600`) |
 | `--format` | Choice | `table` | Output format: `table`, `markdown`, `json`, or `sarif` |
 | `--shell` | Choice | `posix` | Execution mode: `posix` (default), `shebang`, or `auto` |
 | `--mem-limit` | String | `256m` | Memory limit per container (e.g. `256m`, `512m`) |

{opsscript_gate-0.9.0 → opsscript_gate-0.9.2}/README.zh-CN.md

@@ -17,9 +17,9 @@ Bash 依赖、包管理器假设和交互式阻塞。它与 ShellCheck 互补。
 
 也可以直接打开 [OpsScript Gate 在线演示](https://mresyzz.github.io/opsscript-gate/)，先查看 ShellCheck 与运行时验证的差异，再复制 workflow 到自己的仓库。
 
-## 当前版本 v0.9.0
+## 当前版本 v0.9.2
 
-v0.9.0 已作为正式版本发布；如果你要从源码验证当前分支，也可以执行：
+v0.9.2 是当前本地候选版本；如果你要从源码验证当前分支，也可以执行：
 
 ```bash
 pip install -e .
@@ -35,7 +35,7 @@ opsscript-gate run --dry-run
 opsscript-gate run --format json --output reports/compatibility.json
 ```
 
-`init` 生成配置和 GitHub 工作流，不覆盖已有文件。工作流引用 `v0.9.0`。
+`init` 生成配置和 GitHub 工作流，不覆盖已有文件。工作流引用 `v0.9.2`。
 预览不需要 Docker；真实运行需要 Python 3.10+
 和可访问的 Linux Docker 引擎。
 `opsscript-gate doctor` 可以在真实运行前检查 Python 和 Docker。
@@ -74,7 +74,7 @@ Docker daemon 和可选的项目配置。
 - uses: actions/checkout@v7
   with:
     fetch-depth: 0
-- uses: Mresyzz/opsscript-gate@v0.9.0
+- uses: Mresyzz/opsscript-gate@v0.9.2
   with:
     changed-since: ${{ github.event.pull_request.base.sha }}
     preset: minimal

{opsscript_gate-0.9.0 → opsscript_gate-0.9.2}/action.yml

@@ -1,5 +1,5 @@
 name: 'OpsScript Gate'
-description: 'Cross-distro shell script compatibility checker for runtime testing in Debian, Ubuntu, and Alpine. Diagnoses command not found.'
+description: 'Cross-distro shell script compatibility and portability checker for Debian, Ubuntu, and Alpine. Runs real containers to diagnose command not found.'
 author: 'Mresyzz'
 branding:
   icon: 'shield'
@@ -11,7 +11,7 @@ inputs:
     required: false
     default: ''
   matrix:
-    description: 'Comma-separated container images to test (e.g. debian:12-slim,ubuntu:22.04,ubuntu:24.04,alpine:3.20)'
+    description: 'Comma-separated container images to test (maximum: 32; e.g. debian:12-slim,ubuntu:22.04,ubuntu:24.04,alpine:3.20)'
     required: false
     default: ''
   jobs:
@@ -19,11 +19,11 @@ inputs:
     required: false
     default: ''
   timeout:
-    description: 'Hard timeout in seconds per container (default: 60)'
+    description: 'Hard timeout in seconds per container (default: 60, maximum: 3600)'
     required: false
     default: ''
   repeat:
-    description: 'Repeat each distribution run to detect flaky runtime behavior (default: 1)'
+    description: 'Repeat each distribution run to detect flaky runtime behavior (default: 1, maximum: 20)'
     required: false
     default: ''
   format:
@@ -139,9 +139,10 @@ runs:
           pattern="${pattern%$'\r'}"
           [ -z "$pattern" ] || ARGS+=("--exclude" "$pattern")
         done <<< "$INPUT_EXCLUDE"
-        if [ "$INPUT_DRY_RUN" = "true" ]; then
+        DRY_RUN_VALUE="$(printf '%s' "$INPUT_DRY_RUN" | tr '[:upper:]' '[:lower:]')"
+        if [ "$DRY_RUN_VALUE" = "true" ]; then
           ARGS+=("--dry-run")
-        elif [ "$INPUT_DRY_RUN" != "false" ]; then
+        elif [ "$DRY_RUN_VALUE" != "false" ]; then
           echo "dry-run must be true or false" >&2
           exit 1
         fi

{opsscript_gate-0.9.0 → opsscript_gate-0.9.2}/demo.html

@@ -232,7 +232,7 @@
             OpsScript Gate
           </span>
           <span class="font-mono text-[11px] px-1.5 py-0.5 rounded bg-[var(--surface-muted)] text-[var(--text-muted)] border border-[var(--border-light)]">
-            v0.9.0
+            v0.9.2
           </span>
         </div>
       </div>
@@ -367,7 +367,7 @@
         <div class="panel-card p-4 flex flex-col justify-between space-y-3">
           <div class="space-y-2.5">
             <div class="flex items-center justify-between border-b border-[var(--border-light)] pb-2">
-              <span class="font-mono text-xs font-medium text-[var(--text-muted)]">OpsScript Gate Runtime (v0.9.0)</span>
+              <span class="font-mono text-xs font-medium text-[var(--text-muted)]">OpsScript Gate Runtime (v0.9.2)</span>
               <span id="ops-status" class="font-mono text-xs font-semibold px-2 py-0.5 rounded border">
                 1 DISTRO FAILED
               </span>
@@ -536,7 +536,7 @@
     <span class="font-semibold text-[var(--text-hero)]">steps:</span>
       - <span class="font-semibold text-[var(--text-hero)]">uses:</span> actions/checkout@v4
       - <span class="font-semibold text-[var(--text-hero)]">name:</span> Validate scripts across distributions
-        <span class="font-semibold text-[var(--brand)]">uses:</span> Mresyzz/opsscript-gate@v0.9.0
+        <span class="font-semibold text-[var(--brand)]">uses:</span> Mresyzz/opsscript-gate@v0.9.2
         <span class="font-semibold text-[var(--text-hero)]">with:</span>
           <span class="text-[var(--text-body)]">script-path:</span> ./install.sh
           <span class="text-[var(--text-body)]">shell:</span> auto
@@ -604,7 +604,7 @@ jobs:
     steps:
       - uses: actions/checkout@v4
       - name: Validate scripts across distributions
-        uses: Mresyzz/opsscript-gate@v0.9.0
+        uses: Mresyzz/opsscript-gate@v0.9.2
         with:
           script-path: ./install.sh
           shell: auto

{opsscript_gate-0.9.0 → opsscript_gate-0.9.2}/docs/command-not-found.html

@@ -5,6 +5,61 @@
   <meta name="viewport" content="width=device-width, initial-scale=1">
   <title>Test shell scripts in Debian, Ubuntu and Alpine: command not found | OpsScript Gate</title>
   <meta name="description" content="Test a shell installer in real Debian, Ubuntu and Alpine containers. Diagnose command not found, exit code 127 and missing Bash with OpsScript Gate, a GitHub Action and CLI.">
+  <script type="application/ld+json">
+  {
+    "@context": "https://schema.org",
+    "@type": "SoftwareApplication",
+    "name": "OpsScript Gate",
+    "applicationCategory": "DeveloperApplication",
+    "operatingSystem": "Linux",
+    "description": "Run shell scripts in real Debian, Ubuntu, and Alpine containers to diagnose command not found and cross-distro runtime failures.",
+    "url": "https://mresyzz.github.io/opsscript-gate/command-not-found.html",
+    "codeRepository": "https://github.com/Mresyzz/opsscript-gate",
+    "downloadUrl": "https://pypi.org/project/opsscript-gate/",
+    "isAccessibleForFree": true,
+    "license": "https://opensource.org/licenses/MIT"
+  }
+  </script>
+  <script type="application/ld+json">
+  {
+    "@context": "https://schema.org",
+    "@type": "FAQPage",
+    "mainEntity": [
+      {
+        "@type": "Question",
+        "name": "How do I test a shell script on Debian, Ubuntu, and Alpine?",
+        "acceptedAnswer": {
+          "@type": "Answer",
+          "text": "Add the OpsScript Gate GitHub Action or install the Python CLI, then run the script in real Debian, Ubuntu, and Alpine containers. The report shows the failing image, exit code, line, and missing command."
+        }
+      },
+      {
+        "@type": "Question",
+        "name": "Why can ShellCheck pass while a shell installer still fails with command not found?",
+        "acceptedAnswer": {
+          "@type": "Answer",
+          "text": "ShellCheck analyzes shell source and syntax. It does not know which binaries are installed in the runtime image. OpsScript Gate executes the script so missing commands and package-manager assumptions appear in the target distribution."
+        }
+      },
+      {
+        "@type": "Question",
+        "name": "How do I diagnose apt-get not found on Alpine?",
+        "acceptedAnswer": {
+          "@type": "Answer",
+          "text": "Alpine normally uses apk rather than apt-get. Run the installer across the matrix and branch on the package manager or document a distribution-specific prerequisite."
+        }
+      },
+      {
+        "@type": "Question",
+        "name": "Can I run the cross-distro shell check without GitHub Actions?",
+        "acceptedAnswer": {
+          "@type": "Answer",
+          "text": "Yes. Install opsscript-gate from PyPI, ensure a Docker engine running Linux containers is reachable, and run opsscript-gate run ./install.sh."
+        }
+      }
+    ]
+  }
+  </script>
   <link rel="canonical" href="https://mresyzz.github.io/opsscript-gate/command-not-found.html">
   <meta property="og:title" content="ShellCheck passed. Does your installer run on Alpine?">
   <meta property="og:description" content="A reproducible shell runtime compatibility check for Debian, Ubuntu and Alpine, with a copyable GitHub Actions workflow.">
@@ -79,7 +134,7 @@ jobs:
       - uses: actions/checkout@v7
         with:
           persist-credentials: false
-      - uses: Mresyzz/opsscript-gate@v0.9.0
+      - uses: Mresyzz/opsscript-gate@v0.9.2
         with:
           script-path: install.sh
           shell: auto
@@ -113,6 +168,20 @@ opsscript-gate run ./install.sh</code></pre>
   <p>OpsScript Gate mounts each script independently. Sibling files and repository dependencies are not mounted.
     These are distribution user-space tests in containers, not separate Linux kernels or full-machine tests.
     Passing checks do not prove security or replace project integration tests.</p>
+
+  <h2 id="faq">Frequently asked questions</h2>
+  <h3>How do I test a shell script on Debian, Ubuntu, and Alpine?</h3>
+  <p>Add the GitHub Action or install the CLI, then run the script in real containers for each distribution.
+    The report identifies the failing image, exit code, line, and missing command.</p>
+  <h3>Why can ShellCheck pass while the installer still fails?</h3>
+  <p>ShellCheck analyzes source and syntax. It cannot know which binaries are installed in the image that
+    executes the script. Runtime execution exposes missing commands and package-manager assumptions.</p>
+  <h3>How do I diagnose <code>apt-get: not found</code> on Alpine?</h3>
+  <p>Alpine normally uses <code>apk</code>. Detect the available package manager or document a distribution-specific
+    prerequisite instead of assuming Debian's APT exists everywhere.</p>
+  <h3>Can I run the check without GitHub Actions?</h3>
+  <p>Yes. Install <code>opsscript-gate</code> from PyPI, make sure a Docker engine running Linux containers is
+    reachable, and run <code>opsscript-gate run ./install.sh</code>.</p>
   <footer>Read the <a href="https://github.com/Mresyzz/opsscript-gate/blob/main/docs/configuration.md">configuration guide</a>,
     <a href="https://github.com/Mresyzz/opsscript-gate/blob/main/docs/troubleshooting.md">troubleshooting</a>,
     or <a href="https://github.com/Mresyzz/opsscript-gate/blob/main/SECURITY.md">security boundaries</a>.

{opsscript_gate-0.9.0 → opsscript_gate-0.9.2}/docs/command-not-found.md

@@ -25,7 +25,7 @@ jobs:
       - uses: actions/checkout@v7
         with:
           persist-credentials: false
-      - uses: Mresyzz/opsscript-gate@v0.9.0
+      - uses: Mresyzz/opsscript-gate@v0.9.2
         with:
           script-path: scripts/install.sh
           shell: auto
@@ -117,3 +117,27 @@ run in the Linux environments we support?**
 
 See the [Alpine incompatibility example](../examples/alpine-incompatibility/README.md),
 [troubleshooting guide](troubleshooting.md), or the [interactive demo](https://mresyzz.github.io/opsscript-gate/).
+
+## Frequently asked questions
+
+### How do I test a shell script on Debian, Ubuntu, and Alpine?
+
+Add the OpsScript Gate GitHub Action or install the CLI, then run the script in real
+containers for each distribution. The report identifies the failing image, exit code,
+line, and missing command.
+
+### Why can ShellCheck pass while the installer still fails?
+
+ShellCheck analyzes source and syntax. It cannot know which binaries are installed in
+the image that executes the script. Runtime execution exposes missing commands and
+package-manager assumptions.
+
+### How do I diagnose `apt-get: not found` on Alpine?
+
+Alpine normally uses `apk`. Detect the available package manager or document a
+distribution-specific prerequisite instead of assuming Debian's APT exists everywhere.
+
+### Can I run the check without GitHub Actions?
+
+Yes. Install `opsscript-gate` from PyPI, make sure a Docker engine running Linux
+containers is reachable, and run `opsscript-gate run ./install.sh`.