feat(setup/runner): add bootstrap-linux-runner, bootstrap-macos-runner, install-docker, install-k8s-tools, install-cloud-clis, and runner-healthcheck with docs

Author: rudraditya21

docs/scripts/setup/runner/bootstrap-linux-runner.md

@@ -0,0 +1,72 @@
+# bootstrap-linux-runner.sh
+
+## Purpose
+Bootstrap a Linux runner with required tooling and baseline configuration for devops.scripts automation.
+
+## Location
+`setup/runner/bootstrap-linux-runner.sh`
+
+## Preconditions
+- Required tools: `bash`, package manager (`apt`/`dnf`/`yum`/`brew`), optional `sudo`
+- Required permissions: package install and system service privileges for full setup
+- Required environment variables: none
+
+## Arguments
+| Flag | Required | Default | Description |
+|------|----------|---------|-------------|
+| `--manager NAME` | No | `auto` | Package manager selector |
+| `--yes` | No | `false` | Non-interactive install mode |
+| `--dry-run` | No | `false` | Print actions without execution |
+| `--update-cache` | No | `false` | Refresh package metadata |
+| `--skip-docker` | No | `false` | Skip Docker setup |
+| `--skip-k8s` | No | `false` | Skip Kubernetes tool setup |
+| `--skip-cloud` | No | `false` | Skip cloud CLI setup |
+| `--skip-healthcheck` | No | `false` | Skip final runner healthcheck |
+
+## Scenarios
+- Happy path: full bootstrap succeeds and runner healthcheck passes.
+- Common operational path: run with selective `--skip-*` flags for targeted provisioning.
+- Failure path: missing package manager/sudo or downstream installer failure.
+- Recovery/rollback path: fix failing step and rerun bootstrap idempotently.
+
+## Usage
+```bash
+setup/runner/bootstrap-linux-runner.sh --yes --update-cache
+setup/runner/bootstrap-linux-runner.sh --manager apt --skip-cloud
+setup/runner/bootstrap-linux-runner.sh --dry-run
+```
+
+## Behavior
+- Main execution flow: calls setup/local and setup/runner installers + baseline configs + healthcheck.
+- Idempotency notes: orchestrator is rerunnable; underlying installers skip existing tools when possible.
+- Side effects: package installs, config updates, optional docker service enable/start.
+
+## Output
+- Standard output format: timestamped step logs.
+- Exit codes:
+  - `0` successful bootstrap
+  - non-zero from failing step
+  - `2` invalid arguments or unsupported OS
+
+## Failure Modes
+- Common errors and likely causes:
+  - not running on Linux
+  - package install failures/repository issues
+  - missing privileges for service or package operations
+- Recovery and rollback steps:
+  - rerun failed sub-script directly for diagnosis
+  - fix package repos/permissions
+  - rerun bootstrap with required flags
+
+## Security Notes
+- Secret handling: no secrets required by default.
+- Least-privilege requirements: use least privilege; elevate only for install/service actions.
+- Audit/logging expectations: preserve bootstrap logs in runner build artifacts.
+
+## Testing
+- Unit tests:
+  - flag parsing and skip logic
+- Integration tests:
+  - container/VM bootstrap validation on Linux distributions
+- Manual verification:
+  - run `setup/runner/runner-healthcheck.sh` after bootstrap

docs/scripts/setup/runner/bootstrap-macos-runner.md

@@ -0,0 +1,72 @@
+# bootstrap-macos-runner.sh
+
+## Purpose
+Bootstrap a macOS runner with required tooling and baseline configuration for devops.scripts automation.
+
+## Location
+`setup/runner/bootstrap-macos-runner.sh`
+
+## Preconditions
+- Required tools: `bash`, Homebrew (`brew`) or `--install-brew` path
+- Required permissions: package install permissions
+- Required environment variables: none
+
+## Arguments
+| Flag | Required | Default | Description |
+|------|----------|---------|-------------|
+| `--yes` | No | `false` | Non-interactive install mode |
+| `--dry-run` | No | `false` | Print actions without execution |
+| `--update-cache` | No | `false` | Refresh package metadata |
+| `--skip-docker` | No | `false` | Skip Docker installation |
+| `--skip-k8s` | No | `false` | Skip Kubernetes tool setup |
+| `--skip-cloud` | No | `false` | Skip cloud CLI setup |
+| `--skip-healthcheck` | No | `false` | Skip final runner healthcheck |
+| `--install-brew` | No | `false` | Install Homebrew if missing |
+
+## Scenarios
+- Happy path: Homebrew present, tools configured, healthcheck passes.
+- Common operational path: bootstrap managed macOS runners for CI jobs.
+- Failure path: Homebrew missing and `--install-brew` not provided, or install failures.
+- Recovery/rollback path: install Homebrew/dependencies and rerun.
+
+## Usage
+```bash
+setup/runner/bootstrap-macos-runner.sh --yes --update-cache
+setup/runner/bootstrap-macos-runner.sh --skip-cloud
+setup/runner/bootstrap-macos-runner.sh --dry-run --install-brew
+```
+
+## Behavior
+- Main execution flow: install base/local/runner tools and apply local configurations.
+- Idempotency notes: rerunnable orchestration with skip/installed checks.
+- Side effects: package installs, configuration file updates.
+
+## Output
+- Standard output format: timestamped step logs.
+- Exit codes:
+  - `0` successful bootstrap
+  - non-zero from failing step
+  - `2` invalid arguments or unsupported OS
+
+## Failure Modes
+- Common errors and likely causes:
+  - script run on non-macOS host
+  - Homebrew install/access issues
+  - sub-installer failure
+- Recovery and rollback steps:
+  - validate brew setup and network access
+  - rerun failing sub-script directly
+  - rerun bootstrap with corrected flags
+
+## Security Notes
+- Secret handling: no default secret requirements.
+- Least-privilege requirements: local user-level operations preferred.
+- Audit/logging expectations: retain bootstrap logs for runner provenance.
+
+## Testing
+- Unit tests:
+  - flag and step selection behavior
+- Integration tests:
+  - macOS CI runner bootstrap smoke test
+- Manual verification:
+  - run `setup/runner/runner-healthcheck.sh` post-bootstrap

docs/scripts/setup/runner/install-cloud-clis.md

@@ -0,0 +1,69 @@
+# install-cloud-clis.sh
+
+## Purpose
+Install cloud provider CLIs for AWS, GCP, and Azure operations on runners.
+
+## Location
+`setup/runner/install-cloud-clis.sh`
+
+## Preconditions
+- Required tools: `bash`, package manager, optional `sudo`
+- Required permissions: package installation privileges
+- Required environment variables: none
+
+## Arguments
+| Flag | Required | Default | Description |
+|------|----------|---------|-------------|
+| `--tools CSV` | No | `aws,gcloud,az` | Tool set to install |
+| `--tool NAME` | No | none | Add one tool (repeatable) |
+| `--manager NAME` | No | `auto` | `auto\|brew\|apt\|dnf\|yum` |
+| `--yes` | No | `false` | Non-interactive mode |
+| `--update-cache` | No | `false` | Refresh package metadata |
+| `--dry-run` | No | `false` | Print commands only |
+
+## Scenarios
+- Happy path: cloud CLIs installed and ready for auth/bootstrap.
+- Common operational path: install subset of provider CLIs for environment-specific runners.
+- Failure path: package repo lacks provider package or permissions are insufficient.
+- Recovery/rollback path: adjust manager/repository or install subset and rerun.
+
+## Usage
+```bash
+setup/runner/install-cloud-clis.sh --yes
+setup/runner/install-cloud-clis.sh --tools aws,gcloud
+setup/runner/install-cloud-clis.sh --tool az --dry-run
+```
+
+## Behavior
+- Main execution flow: parse tool list, map package names, install missing commands.
+- Idempotency notes: existing CLIs are skipped.
+- Side effects: package installation.
+
+## Output
+- Standard output format: timestamped install logs.
+- Exit codes:
+  - `0` all requested tools installed/present
+  - `1` one or more tools failed/unsupported
+  - `2` invalid arguments
+
+## Failure Modes
+- Common errors and likely causes:
+  - unsupported tool name
+  - package unavailable in configured repositories
+  - permission failures on install
+- Recovery and rollback steps:
+  - verify repositories and manager selection
+  - rerun with corrected tool list or permissions
+
+## Security Notes
+- Secret handling: no credentials handled during install.
+- Least-privilege requirements: elevate only during package operations.
+- Audit/logging expectations: installation actions should be logged in runner provisioning.
+
+## Testing
+- Unit tests:
+  - tool parsing/mapping validation
+- Integration tests:
+  - install flow on each supported package manager
+- Manual verification:
+  - `aws --version`, `gcloud --version`, `az version`

docs/scripts/setup/runner/install-docker.md

@@ -0,0 +1,70 @@
+# install-docker.sh
+
+## Purpose
+Install Docker and optionally start/enable the daemon on Linux runners.
+
+## Location
+`setup/runner/install-docker.sh`
+
+## Preconditions
+- Required tools: `bash`, package manager, optional `sudo`, optional `systemctl`
+- Required permissions: package install privileges; service management for daemon actions
+- Required environment variables: none
+
+## Arguments
+| Flag | Required | Default | Description |
+|------|----------|---------|-------------|
+| `--manager NAME` | No | `auto` | `auto\|brew\|apt\|dnf\|yum` |
+| `--yes` | No | `false` | Non-interactive install mode |
+| `--update-cache` | No | `false` | Refresh package metadata |
+| `--start-service` | No | `true` | Start/enable daemon on Linux |
+| `--no-start-service` | No | `false` | Skip daemon startup |
+| `--add-user-to-docker-group` | No | `false` | Add user to docker group (Linux) |
+| `--dry-run` | No | `false` | Print commands only |
+
+## Scenarios
+- Happy path: Docker installed and daemon started (Linux).
+- Common operational path: install binary only in immutable environments.
+- Failure path: missing package manager or insufficient privileges.
+- Recovery/rollback path: fix package/service permissions and rerun.
+
+## Usage
+```bash
+setup/runner/install-docker.sh --yes --update-cache
+setup/runner/install-docker.sh --manager apt --no-start-service
+setup/runner/install-docker.sh --add-user-to-docker-group
+```
+
+## Behavior
+- Main execution flow: detect manager, install package if needed, manage service/group options.
+- Idempotency notes: skip install when docker already exists.
+- Side effects: package install, daemon state changes, optional group membership changes.
+
+## Output
+- Standard output format: timestamped progress logs.
+- Exit codes:
+  - `0` success
+  - `1` install/runtime failure
+  - `2` invalid arguments
+
+## Failure Modes
+- Common errors and likely causes:
+  - unsupported manager selection
+  - package not found in repositories
+  - no permission for service/group updates
+- Recovery and rollback steps:
+  - verify repositories and package availability
+  - rerun with elevated privileges where required
+
+## Security Notes
+- Secret handling: none.
+- Least-privilege requirements: avoid unnecessary root usage outside install/service steps.
+- Audit/logging expectations: record daemon/group changes for compliance.
+
+## Testing
+- Unit tests:
+  - manager detection and option validation
+- Integration tests:
+  - install/start behavior on Linux/macOS test images
+- Manual verification:
+  - `docker --version` and `docker info`

docs/scripts/setup/runner/install-k8s-tools.md

@@ -0,0 +1,69 @@
+# install-k8s-tools.sh
+
+## Purpose
+Install core Kubernetes ecosystem CLIs required for cluster operations and CI automation.
+
+## Location
+`setup/runner/install-k8s-tools.sh`
+
+## Preconditions
+- Required tools: `bash`, package manager, optional `sudo`
+- Required permissions: package installation privileges
+- Required environment variables: none
+
+## Arguments
+| Flag | Required | Default | Description |
+|------|----------|---------|-------------|
+| `--tools CSV` | No | `kubectl,helm,kustomize,kind` | Tool set to install |
+| `--tool NAME` | No | none | Add one tool (repeatable) |
+| `--manager NAME` | No | `auto` | `auto\|brew\|apt\|dnf\|yum` |
+| `--yes` | No | `false` | Non-interactive mode |
+| `--update-cache` | No | `false` | Refresh package metadata |
+| `--dry-run` | No | `false` | Print commands only |
+
+## Scenarios
+- Happy path: requested Kubernetes tools installed successfully.
+- Common operational path: install only subset needed by specific runner pools.
+- Failure path: unsupported tool/manager mapping or install failure.
+- Recovery/rollback path: adjust tool list/manager and rerun.
+
+## Usage
+```bash
+setup/runner/install-k8s-tools.sh --yes
+setup/runner/install-k8s-tools.sh --tools kubectl,helm
+setup/runner/install-k8s-tools.sh --tool kind --tool kustomize --dry-run
+```
+
+## Behavior
+- Main execution flow: normalize tool list, map package names per manager, install missing tools.
+- Idempotency notes: skips tools already present.
+- Side effects: package installation.
+
+## Output
+- Standard output format: timestamped install logs.
+- Exit codes:
+  - `0` all requested tools installed/present
+  - `1` one or more tools failed/unsupported
+  - `2` invalid arguments
+
+## Failure Modes
+- Common errors and likely causes:
+  - unsupported tool name
+  - package unavailable in repo
+  - missing privileges for install
+- Recovery and rollback steps:
+  - fix tool names and manager mapping
+  - ensure repository availability
+
+## Security Notes
+- Secret handling: none.
+- Least-privilege requirements: elevate only for package operations.
+- Audit/logging expectations: capture install outcomes in bootstrap logs.
+
+## Testing
+- Unit tests:
+  - tool parsing and manager mapping
+- Integration tests:
+  - installation on supported package managers
+- Manual verification:
+  - `kubectl version --client`, `helm version`, `kind version`