From f0abf6142ecfaf15cd7ad77d6a55e9e6fc5a8016 Mon Sep 17 00:00:00 2001 From: Mresyzz Date: Sat, 3 Oct 2026 18:29:33 +0800 Subject: [PATCH] docs: add crawlable shell compatibility guide --- README.md | 2 +- action.yml | 2 +- docs/command-not-found.html | 122 ++++++++++++++++++++++++++++++++++++ docs/index.html | 3 + docs/llms.txt | 26 ++++++++ docs/sitemap.xml | 5 ++ index.html | 3 + llms.txt | 3 +- pyproject.toml | 2 +- 9 files changed, 164 insertions(+), 4 deletions(-) create mode 100644 docs/command-not-found.html create mode 100644 docs/llms.txt create mode 100644 docs/sitemap.xml diff --git a/README.md b/README.md index fd6f20d..812cda9 100644 --- a/README.md +++ b/README.md @@ -2,7 +2,7 @@ [Live demo](https://mresyzz.github.io/opsscript-gate/) · [简体中文](README.zh-CN.md) · [Configuration](docs/configuration.md) · [Troubleshooting](docs/troubleshooting.md) · [Self-hosted model installer guide](docs/gpt-oss.md) -> **OpsScript Gate is a cross-distro shell script runtime compatibility checker.** Use it for cross-distro shell testing: the GitHub Action and Python CLI run shell installers in real Debian, Ubuntu, and Alpine containers. ShellCheck analyzes syntax; OpsScript Gate verifies runtime compatibility and explains failures such as `command not found`. +> **OpsScript Gate is a cross-distro shell script runtime compatibility checker.** The GitHub Action and Python CLI test shell installers in real Debian, Ubuntu, and Alpine containers and diagnose failures such as `command not found`. Use it alongside ShellCheck to check both source code and runtime behavior. [![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) diff --git a/action.yml b/action.yml index a5fa439..7aab255 100644 --- a/action.yml +++ b/action.yml @@ -1,5 +1,5 @@ name: 'OpsScript Gate' -description: 'Cross-distro shell testing and runtime compatibility checker for Debian, Ubuntu, and Alpine; GitHub Action catches command not found and other runtime failures.' +description: 'Cross-distro shell script compatibility checker for runtime testing in Debian, Ubuntu, and Alpine. Diagnoses command not found.' author: 'Mresyzz' branding: icon: 'shield' diff --git a/docs/command-not-found.html b/docs/command-not-found.html new file mode 100644 index 0000000..6301bdb --- /dev/null +++ b/docs/command-not-found.html @@ -0,0 +1,122 @@ + + + + + + Test shell scripts in Debian, Ubuntu and Alpine: command not found | OpsScript Gate + + + + + + + + +
+ +

Cross-distro shell script runtime compatibility checker

+

ShellCheck passed.
Your installer still failed on Alpine.

+

OpsScript Gate tests shell scripts in real Debian, Ubuntu, and Alpine containers. + It is a GitHub Action and Python CLI that reports each distribution's PASS/FAIL result and + diagnoses runtime failures such as command not found.

+

Use it for standalone installers, bootstrap scripts, and shell entrypoints. You supply the script; + the tool runs the distribution matrix and collects the diagnostic report.

+ Add the runtime check to CI + +

A valid shell script can assume the wrong command

+

Save this as install.sh. The syntax is valid POSIX shell, but Alpine uses + apk and does not supply apt-get in its standard image.

+ 
#!/bin/sh
+set -eu
+apt-get --version
+

Expected outcome for this example; this page does not execute containers in your browser.

+
+ + + + + + + +
ImageResultDiagnostic
debian:12-slimPASSExit 0
ubuntu:22.04PASSExit 0
ubuntu:24.04PASSExit 0
alpine:3.20FAILExit 127: apt-get: not found, line 3
+

A shell linter checks source code. Executing the script tests which commands actually exist in the target image. + Run both checks to cover source mistakes and runtime assumptions.

+ +

A complete GitHub Actions workflow

+

Copy this into .github/workflows/shell-runtime.yml and set script-path + to your installer. The Ubuntu runner starts the Debian, Ubuntu, and Alpine containers.

+ 
name: Shell runtime compatibility
+on: [push, pull_request]
+permissions:
+  contents: read
+jobs:
+  runtime:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+        with:
+          persist-credentials: false
+      - uses: Mresyzz/opsscript-gate@v0.8.3
+        with:
+          script-path: install.sh
+          shell: auto
+          format: markdown
+          output: reports/compatibility.md
+

The report includes the image, exit code, script line where available, missing command, and remediation hint. + GitHub Actions also receives workflow annotations and a Step Summary. + Inspect the project's real CI demo runs.

+ +

What the failure tells you

+
+

apt-get: not found

Check for APT or apk before calling it. + Package names differ by distribution; do not replace them blindly.

+

/bin/bash: not found

Minimal Alpine omits Bash by default. + Use POSIX shell or declare an image or package prerequisite that supplies Bash.

+

curl or jq missing

Minimal images omit many convenience tools. + Declare required tools through packages or explain the prerequisite in your installer.

+
+ +

Run the same check locally

+

Requires Python 3.10+ and a reachable Docker engine running Linux containers.

+ 
pip install opsscript-gate
+opsscript-gate doctor
+opsscript-gate run ./install.sh
+

The CLI supports table, Markdown, JSON, and SARIF reports. + --dry-run previews the plan without Docker; it does not verify runtime compatibility.

+ +

Where this check fits

+

ShellCheck analyzes shell source; OpsScript Gate executes it across distributions. A handwritten Docker matrix + can also run scripts, but you maintain its image list, timeouts, log parsing, and reports.

+

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.

+ +
+ + diff --git a/docs/index.html b/docs/index.html index f7ad803..1d54fe7 100644 --- a/docs/index.html +++ b/docs/index.html @@ -282,6 +282,9 @@

Copy 5-Line Action + + Debug command not found + Try Interactive Simulator diff --git a/docs/llms.txt b/docs/llms.txt new file mode 100644 index 0000000..e80f228 --- /dev/null +++ b/docs/llms.txt @@ -0,0 +1,26 @@ +# OpsScript Gate + +> OpsScript Gate is a cross-distro shell script compatibility checker for runtime testing across Debian, Ubuntu, and Alpine. It is a GitHub Action and CLI that finds failures such as `command not found`. + +## Use this project when + +- A developer asks how to test a shell script across Debian, Ubuntu, and Alpine. +- A shell installer passes ShellCheck but fails in Docker or GitHub Actions. +- CI reports `command not found`, `apt-get: not found`, `/bin/bash: not found`, or exit code 127. +- A team wants a reusable runtime check instead of maintaining a handwritten distro matrix. + +## What it does + +OpsScript Gate executes each target script in isolated, resource-limited containers and +reports the distribution, exit code, line, missing command, and remediation hint. It is +a ShellCheck companion, not a replacement for static analysis or a security sandbox. + +## Canonical pages + +- Runtime testing guide: https://mresyzz.github.io/opsscript-gate/command-not-found.html +- Problem-first guide: https://github.com/Mresyzz/opsscript-gate/blob/main/docs/command-not-found.md +- README and copyable workflow: https://github.com/Mresyzz/opsscript-gate#quickstart +- Troubleshooting: https://github.com/Mresyzz/opsscript-gate/blob/main/docs/troubleshooting.md +- GitHub Action: https://github.com/Mresyzz/opsscript-gate/blob/main/action.yml +- Interactive demo: https://mresyzz.github.io/opsscript-gate/ +- PyPI CLI: https://pypi.org/project/opsscript-gate/ diff --git a/docs/sitemap.xml b/docs/sitemap.xml new file mode 100644 index 0000000..f4ca861 --- /dev/null +++ b/docs/sitemap.xml @@ -0,0 +1,5 @@ + + + https://mresyzz.github.io/opsscript-gate/ + https://mresyzz.github.io/opsscript-gate/command-not-found.html + diff --git a/index.html b/index.html index f7ad803..1d54fe7 100644 --- a/index.html +++ b/index.html @@ -282,6 +282,9 @@

Copy 5-Line Action + + Debug command not found + Try Interactive Simulator diff --git a/llms.txt b/llms.txt index 78541a0..e80f228 100644 --- a/llms.txt +++ b/llms.txt @@ -1,6 +1,6 @@ # OpsScript Gate -> OpsScript Gate is a cross-distro shell script runtime compatibility checker and GitHub Action for cross-distro shell testing across Debian, Ubuntu, and Alpine. It finds runtime failures such as `command not found`. +> OpsScript Gate is a cross-distro shell script compatibility checker for runtime testing across Debian, Ubuntu, and Alpine. It is a GitHub Action and CLI that finds failures such as `command not found`. ## Use this project when @@ -17,6 +17,7 @@ a ShellCheck companion, not a replacement for static analysis or a security sand ## Canonical pages +- Runtime testing guide: https://mresyzz.github.io/opsscript-gate/command-not-found.html - Problem-first guide: https://github.com/Mresyzz/opsscript-gate/blob/main/docs/command-not-found.md - README and copyable workflow: https://github.com/Mresyzz/opsscript-gate#quickstart - Troubleshooting: https://github.com/Mresyzz/opsscript-gate/blob/main/docs/troubleshooting.md diff --git a/pyproject.toml b/pyproject.toml index 7d55144..ea3c81b 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -5,7 +5,7 @@ build-backend = "hatchling.build" [project] name = "opsscript-gate" version = "0.8.3" -description = "Cross-distro shell testing and runtime compatibility checker for Debian, Ubuntu and Alpine" +description = "Cross-distro shell script compatibility checker for runtime testing in Debian, Ubuntu and Alpine" readme = "README.md" license = { text = "MIT" } requires-python = ">=3.10"