opsscript-gate 0.9.1__tar.gz → 0.9.4__tar.gz

{opsscript_gate-0.9.1 → opsscript_gate-0.9.4}/.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.1 → opsscript_gate-0.9.4}/.github/workflows/release.yml

@@ -123,16 +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 }}."
+              echo "Target tag $TARGET_TAG does not exist. Creating tag and publishing release."
               IS_NEW_RELEASE="true"
               SHOULD_TAG="true"
             fi
@@ -171,7 +167,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.1 → opsscript_gate-0.9.4}/.gitignore

@@ -50,3 +50,4 @@ venv.bak/
 *~
 .DS_Store
 Thumbs.db
+.ai/

{opsscript_gate-0.9.1 → opsscript_gate-0.9.4}/CHANGELOG.md

@@ -1,5 +1,48 @@
 # Changelog
 
+## [0.9.4] - 2026-10-11
+
+### Fixed
+- Fixed release workflow publishing deadlock where `main` pushes skipped distribution package builds and release creation due to GITHUB_TOKEN tag events not triggering new workflows.
+- Unified command path extraction in remediation rules to ensure full-path commands (e.g. `/usr/bin/apt-get`, `/sbin/apk`, `/bin/yum`, `/usr/local/bin/bash`) accurately match package manager and shell hints.
+- Added native RHEL/Fedora/CentOS package mappings in `COMMON_COMMAND_PACKAGES` to prevent fallback to invalid Debian package names.
+- Added native container package pre-installation support for `dnf`, `microdnf`, and `yum` in `runner._wrap_with_package_setup`.
+- Fixed `RunReport` and `MultiScriptReport` `__post_init__` to preserve explicitly passed `all_passed=False` when result collections are empty.
+- Supported bare directory exclusions (e.g. `tests` or `tests/`) in `_matches_exclude` to match both directories and all contained files.
+
+## [0.9.3] - 2026-10-11
+
+### Added
+- Added cross-distribution package name mapping and actionable remediation suggestions (`apt-get`, `apk`, `dnf`) for common missing operations commands (`curl`, `wget`, `jq`, `git`, `tar`, `python3`, `pip`, `sudo`, `make`, `gcc`, etc.).
+- Extended `FailureDiagnostic` and SARIF output with structured `suggested_package` property.
+
+### Fixed
+- Fixed unreadable shell script candidate misclassification during discovery.
+- Ensured temporary script files are safely cleaned up during distribution preparation errors.
+- Added preflight validation to reject directory and missing script paths before creating worker threads.
+- Enforced consistent POSIX LF line endings in report output files across platforms.
+
+## [0.9.2] - 2026-10-05
+
+### 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

{opsscript_gate-0.9.1 → opsscript_gate-0.9.4}/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.1 → opsscript_gate-0.9.4}/PKG-INFO

@@ -1,7 +1,7 @@
 Metadata-Version: 2.5
 Name: opsscript-gate
-Version: 0.9.1
-Summary: Cross-distro shell script compatibility checker for runtime testing in Debian, Ubuntu and Alpine
+Version: 0.9.4
+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.1
+- 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.1
+## 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.1
+      - 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.1
+      - 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.1
+      - 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.1
+- 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.1 → opsscript_gate-0.9.4}/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.1
+- 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.1
+## 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.1
+      - 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.1
+      - 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.1
+      - 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.1
+- 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.1 → opsscript_gate-0.9.4}/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.1 → opsscript_gate-0.9.4}/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.1 → opsscript_gate-0.9.4}/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.1 → opsscript_gate-0.9.4}/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.1 → opsscript_gate-0.9.4}/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`.

{opsscript_gate-0.9.1 → opsscript_gate-0.9.4}/docs/configuration.md

@@ -12,7 +12,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.9.0 tag.
+`.github/workflows/opsscript-gate.yml`. The generated workflow uses the v0.9.2 tag.
 
 `doctor` checks Python and Docker connectivity without executing repository scripts.
 Use `opsscript-gate doctor --format json` when collecting a support report.
@@ -53,7 +53,7 @@ names to install inside each test container before the target script runs. The
 runner uses `apt-get` for Debian/Ubuntu images and `apk` for Alpine images. It
 accepts package names only, never shell commands, and requires `network: bridge`.
 The default is an empty list, so existing networking settings and execution remain unchanged.
-`repeat` runs each distribution more than once and reports `FLAKY` when at least one
+`repeat` runs each distribution more than once (up to 20 attempts) and reports `FLAKY` when at least one
 attempt passes and another fails. Keep it at `1` for the normal fast gate; use `3` or
 `5` while investigating intermittent CI failures.
 
@@ -109,7 +109,7 @@ For pull requests, set `changed-since` to the base commit and fetch full Git his
 - 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
@@ -119,7 +119,7 @@ The Action passes when no changed shell scripts are selected. This keeps unrelat
 documentation or application changes from starting container jobs.
 
 ```yaml
-- uses: Mresyzz/opsscript-gate@v0.9.0
+- uses: Mresyzz/opsscript-gate@v0.9.2
   with:
     config: .opsscript-gate.json
     format: json
@@ -146,3 +146,6 @@ offline networking and a smaller matrix. Existing users do not need to run `init
 
 The intentional breaking corrections are that discovery overflow now fails and
 symlinked files are no longer automatically selected. Preview discovery after upgrading.
+
+`timeout` is the hard limit per container in seconds. It must be between 1 and 3600.
+Custom `matrix` values may contain up to 32 container images.

{opsscript_gate-0.9.1 → opsscript_gate-0.9.4}/docs/gpt-oss.md

@@ -33,7 +33,7 @@ jobs:
           fetch-depth: 0
           persist-credentials: false
 
-      - 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