From 99e13e89ad3277fed9a5cf913491921faf4ca3a9 Mon Sep 17 00:00:00 2001
From: Sprite <noreply@sprite.dev>
Date: Sun, 8 Feb 2026 01:05:37 +0000
Subject: [PATCH] ci: add shellcheck linting infrastructure

Added shellcheck to catch bash anti-patterns across 115 scripts:
- Created .shellcheckrc configuration
- Added GitHub Actions workflow (.github/workflows/lint.yml)
- Documented shellcheck usage in README

Currently found 3,598 warnings (expected for unlinted codebase).
Using || true temporarily to not block PRs - warnings will be fixed
incrementally in follow-up tasks.

Common issues: SC2250 (missing braces), SC2162 (read without -r),
SC2312 (command substitution masking), SC1091 (sourcing pattern).

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
---
 .github/workflows/lint.yml | 36 ++++++++++++++++++++++++++++++++++++
 .shellcheckrc              |  6 ++++++
 README.md                  | 38 ++++++++++++++++++++++++++++++++++++++
 3 files changed, 80 insertions(+)
 create mode 100644 .github/workflows/lint.yml
 create mode 100644 .shellcheckrc

diff --git a/.github/workflows/lint.yml b/.github/workflows/lint.yml
new file mode 100644
index 00000000..85583ef5
--- /dev/null
+++ b/.github/workflows/lint.yml
@@ -0,0 +1,36 @@
+name: Lint
+
+on:
+  push:
+    branches: [ main, master ]
+  pull_request:
+    branches: [ main, master ]
+
+jobs:
+  shellcheck:
+    name: ShellCheck
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Install ShellCheck
+        run: |
+          sudo apt-get update
+          sudo apt-get install -y shellcheck
+
+      - name: Run ShellCheck on all bash scripts
+        run: |
+          # Find all .sh files, excluding node_modules and other irrelevant directories
+          # Note: Using || true temporarily - 3,598 existing warnings need gradual fixes
+          find . -name "*.sh" \
+            ! -path "*/node_modules/*" \
+            ! -path "*/.git/*" \
+            ! -path "*/dist/*" \
+            ! -path "*/build/*" \
+            -print0 | xargs -0 shellcheck || true
+
+      - name: ShellCheck version info
+        if: always()
+        run: shellcheck --version
diff --git a/.shellcheckrc b/.shellcheckrc
new file mode 100644
index 00000000..9acee690
--- /dev/null
+++ b/.shellcheckrc
@@ -0,0 +1,6 @@
+# shellcheck configuration for spawn
+# Enable all optional checks for maximum code quality
+enable=all
+
+# Disable specific warnings that conflict with spawn's design patterns
+# (Add suppressions here after initial run if needed)
diff --git a/README.md b/README.md
index e28f46d8..c0fe9d0c 100644
--- a/README.md
+++ b/README.md
@@ -396,6 +396,44 @@ spawn/
 
 ---
 
+## Development
+
+### Running ShellCheck Locally
+
+Spawn uses [ShellCheck](https://www.shellcheck.net/) to lint all bash scripts and catch common mistakes.
+
+**Install ShellCheck:**
+
+```bash
+# Ubuntu/Debian
+sudo apt-get install shellcheck
+
+# macOS
+brew install shellcheck
+
+# Fedora
+sudo dnf install ShellCheck
+```
+
+**Run on all scripts:**
+
+```bash
+find . -name "*.sh" \
+  ! -path "*/node_modules/*" \
+  ! -path "*/.git/*" \
+  -exec shellcheck {} +
+```
+
+**Run on a single file:**
+
+```bash
+shellcheck shared/common.sh
+```
+
+The CI pipeline automatically runs shellcheck on all pull requests. See `.shellcheckrc` for configuration.
+
+---
+
 ## Security
 
 ### API Token Storage