install-script-generator

# Install Script Generator Generate robust, cross-platform installation scripts that users can run with a **single bash command** via GitHub raw URLs. This SKILL.md is a lean index — long templates and tables live under `references/` to protect the agent's context budget. ## When to Use - The user asks for a `curl | bash` one-liner for their project. - A repo needs a `install.sh` that auto-detects OS, arch, and package manager. - A Python/Go/Node/Rust module should be installable in one command from a fresh machine. Skip this skill for Dockerfiles, CI/CD pipelines, or one-off local shell scripts. ## Prerequisites - The repo has a known `<owner>/<repo>` (check `git remote -v`) and a default branch. - The target software's build system is identifiable (`Makefile`, `package.json`, `setup.py`, `Cargo.toml`, `go.mod`, etc.). - `python3` is available locally for the helper scripts under `scripts/`. If `python3` is missing, skip each helper-script step, record it as `not run (python3 not found)`, and continue; the run then ends `PARTIAL`. ## Reference Files (read on demand to save tokens) | File | When to read | |------|--------------| | `references/install-template.md` | When generating `install.sh` — full bash template with detection helpers, dependency installer, and main entry point | | `references/readme-snippet.md` | When updating the README — copy-paste install block plus URL format notes | | `references/edge-cases.md` | When handling unusual OS/sudo/path scenarios and writing step reports | | `references/final-report.md` | When writing the final report — the four parts, status rules, outcome table, examples, reader checks | | `scripts/env_explorer.py` | Local environment probe (OS, arch, package managers, sudo) | | `scripts/plan_generator.py` | Generates `installation_plan.yaml` from env + target | | `scripts/executor.py` | Dry-runs `installation_plan.yaml` with rollback, before Phase 3 generation | | `scripts/doc_generator.py` | Renders user-facing `USAGE_GUIDE.md` | Do not inline these contents into the conversation; link to them to preserve the context window. ## Repo Sync Before Edits (mandatory) Run this once, before Phase 1. Before creating, updating, or deleting files in an existing repo, sync the current branch with remote: ```bash branch="$(git rev-parse --abbrev-ref HEAD)" git fetch origin git pull --rebase origin "$branch" ``` If the working tree is dirty, `git stash push -u -m pre-sync` first, sync, then `git stash pop`. If `origin` is missing or rebase/stash conflicts occur, stop and ask the user before continuing. ## Workflow A **fix attempt** is one edit followed by a rerun of the failed check. Stop after 3 fix attempts on the same check, record the check as failed, and continue to the next phase. To **stop with `BLOCKED`**, skip the remaining phases and print the final report. ### Phase 1 — Exploration 1. Identify the target software/module/tool. If the user did not name it and the repo holds more than one buildable project, ask which one. 2. Inspect the repo for build files (`Makefile`, `package.json`, `setup.py`, `Cargo.toml`, `go.mod`, ...). 3. Record the install method: the package name, if the target is published in a package manager, or the build-and-copy commands from its build file. If neither exists, ask the user. If the user gives no install method, stop with `BLOCKED`. 4. List dependencies the software needs to build and run. 5. Run `git remote get-url origin` to read `<owner>/<repo>`. 6. Run `git symbolic-ref --short refs/remotes/origin/HEAD` and strip `origin/` to read the default branch. 7. If step 5 or step 6 fails, ask the user for the value. If the user gives no answer, stop with `BLOCKED`. 8. Run `python3 scripts/env_explorer.py` to capture OS, arch, package managers, shell, and sudo availability into `env_info.json`. ### Phase 2 — Planning 1. Order the dependencies so each one installs before anything that needs it. 2. For each dependency, note the `command -v <dep>` check `install.sh` uses to skip one that is already installed. 3. Run `python3 scripts/plan_generator.py --target "<name>" --env-file env_info.json --deps <dep1> <dep2> ...` (dependencies from step 1, space-separated; omit `--deps` only if there are none) to emit `installation_plan.yaml`. 4. If the target is not published in the detected package manager, edit the `Install <name>` step in `installation_plan.yaml`: set `command`, `verify`, and `rollback` to the commands `install_<tool>` will run. 5. Replace every `# TODO` placeholder in the plan. Add a step for each dependency that `plan_generator.py` warned it left out. 6. Run `python3 scripts/executor.py --plan installation_plan.yaml --dry-run`. 7. Check the dry run: it exits 0, its last summary line starts `DRY RUN:`, stderr has no `placeholder command` warning, the steps follow the step 1 order, and every `Install ...` step has a non-null `rollback`. The package-manager check and final verify steps carry `rollback: null` by design. If a check fails, fix the plan and rerun step 6. The dry run skips execution, so it checks the plan's shape, not that installation or rollback actually works. ### Phase 3 — Generation (primary output) If `install.sh` already exists at the repo root, show the user the planned changes and ask before overwriting it. If the user declines, stop with `BLOCKED`. Generate `install.sh` at the repo root using `references/install-template.md`. The template contains four sections you compose: 1. Header + colour helpers (`info`, `ok`, `warn`, `err`, `die`). 2. Detection helpers (`detect_os`, `detect_arch`, `detect_package_manager`, `need_sudo`). 3. `install_deps` switch covering apt/dnf/yum/pacman/brew/zypper. 4. `install_<tool>` (customised per target), `verify_installation`, and `main`. Read `references/install-template.md` for the exact code; do not paste it into chat. If Windows support is needed, also generate `install.ps1` (one-liner: `irm <raw_url> | iex`). Then check the script. If a check fails, fix `install.sh` and rerun that check: 1. `bash -n install.sh` exits 0. 2. `grep -nE '<owner>|<repo>|<branch>|<software_name>|<Software Name>|install_<tool>' install.sh` prints nothing. 3. If `shellcheck` is on PATH, `shellcheck -S error install.sh` exits 0. Otherwise record `shellcheck not run (not on PATH)`. Do not run `install.sh` on the user's machine: it installs software and may call `sudo`. Run it only when the user asks for a local run or approves a disposable container. When it runs, its last line must be `[ OK ] Installation complete!`. ### Phase 4 — Documentation 1. Insert the install block from `references/readme-snippet.md` into the project README, substituting `<owner>/<repo>/<branch>`. If the repo has no README, create `README.md` holding only that block. 2. Run `python3 scripts/doc_generator.py --target "<name>" --plan installation_plan.yaml` to emit `USAGE_GUIDE.md`. 3. Run `grep -n "raw.githubusercontent.com/<owner>/<repo>/<branch>/install.sh" <README>` with the real values; it must print one or more lines. 4. If `git ls-tree --name-only origin/<branch> install.sh` prints `install.sh`, run `curl -fsSI <raw-url>` and record the HTTP status. Otherwise record `raw URL not live until install.sh is pushed`. 5. Print the final report. ## Final Report Print it once, as plain text in the chat, after the last Step Completion Report. Four parts, in order: `Result:` (status, target, one-liner), `Evidence:` (only checks that ran, with results), `Uncertainty:` (untested behavior, including `install.sh was not executed`), and `Decision:` (the approval needed, or `No approval needed.`, then the push and cleanup actions). Read `references/final-report.md` for each part's contents, the outcome table, and examples. Apply the first status rule that matches: 1. `BLOCKED — <reason>` — `install.sh` was not written. 2. `PARTIAL — <reason>` — `install.sh` was written, and a required check failed or did not run: `bash -n`, the placeholder `grep`, `shellcheck -S error` (when on PATH), the Phase 2 dry run, the README one-liner, `USAGE_GUIDE.md`, or an approved run of `install.sh` that did not end with `[ OK ] Installation complete!`. 3. `COMPLETE` — every required check passed. `COMPLETE` does not mean `install.sh` ran. ## Output Files | File | Description | |------|-------------| | `install.sh` | Primary output — standalone installer for `curl \| bash` | | `install.ps1` | Optional Windows PowerShell installer | | `USAGE_GUIDE.md` | User-facing docs | | `env_info.json` | Local environment probe (working file) | | `installation_plan.yaml` | Ordered install steps (working file) | | `install_report.md` | Dry-run report from `executor.py` (working file) | The three working files hold this machine's home path and `PATH`. Do not commit them unless the user asks; list them under `Decision:` for cleanup. ## Acceptance Criteria - `install.sh` exists at repo root, starts with `#!/usr/bin/env bash` and `set -euo pipefail`, and passes the three Phase 3 checks. - Auto-detects OS, architecture, and package manager; exits non-zero with a clear message on unsupported targets. - Handles `sudo` gracefully (root, sudo, or fail-fast). - Verifies the installation at the end (`command -v $TOOL_NAME` plus `--version` when available). - README contains a `curl -sSL ... | bash` one-liner that points at the raw GitHub URL for `<owner>/<repo>/<branch>`. - When `install.sh` runs successfully, its last line is `[ OK ] Installation complete!`. - The final report opens with `Result:` and a status from the rules above, and meets the four reader checks in `references/final-report.md`: result findable, facts apart from assumptions, claims traceable, next decision clear. ## Edge Cases See `references/edge-cases.md` for the full list. Highlights: - **Unsupported OS / architecture** — `die` with the detected value; user sees what failed. - **No package manager** — `install_deps` aborts with `Unsupported package manager 'unknown'`. - **No sudo** — `need_sudo` exits with `Requires root. Run as root or install sudo.` - **Windows native** — generate `install.ps1` separately; `install.sh` warns under MSYS/Cygwin. - **Script in subdirectory** — adjust the raw URL path; note it in the README snippet. - **Target not in a package manager** — edit its plan step (Phase 2 step 4) and write `install_<tool>` from the build file. ## Step Completion Reports After each phase, emit a `◆` block with `√`/`×` checks and a `Result: PASS | FAIL | PARTIAL` line; the format and per-phase checks are in `references/edge-cases.md`. ## Expected Output The final report for a complete run (full example in `references/final-report.md`): ```text Result: COMPLETE — mytool installer curl -sSL https://raw.githubusercontent.com/owner/mytool/main/install.sh | bash Evidence: bash -n install.sh: exit 0; placeholder grep: no matches; shellcheck -S error: exit 0 executor.py --dry-run: "DRY RUN: 5 step(s) listed for mytool; nothing was executed." Uncertainty: install.sh was not executed. Raw URL not live until install.sh is pushed to main. Decision: No approval needed. Remaining action: commit and push install.sh; delete the three working files. ``` When a user later runs the one-liner, the script's banner ends: ``` [INFO] OS: linux | Arch: x86_64 | Package Manager: apt [ OK ] Dependencies installed [ OK ] mytool 1.2.0 installed [ OK ] Installation complete! ```