Add Docker-based development environment with optimized CI

.github/workflows/checkshell.yml

@@ -8,11 +8,19 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v6
-      - run: docker run --rm -v "$(pwd)":/sh -w /sh mvdan/shfmt:v3 -sr -i 2 -l -w -ci .
+      - run: docker run --rm -v "$(pwd)":/work -w /work mvdan/shfmt:v3 -sr -i 2 -l -w -ci .
       - run: git diff --color --exit-code
 
   shellcheck:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v6
       - run: shellcheck *.sh
+
+  markdownlint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+      - uses: DavidAnson/markdownlint-cli2-action@v18
+        with:
+          globs: '*.md'

.pre-commit-config.yaml

@@ -1,21 +1,22 @@
 repos:
-  - repo: https://github.com/shellcheck-py/shellcheck-py
-    rev: v0.10.0.1
+  - repo: local
     hooks:
-      - id: shellcheck
+      - id: shellcheck-docker
+        name: shellcheck (Docker)
+        entry: bash -c 'docker run --rm -v "$(pwd)":/mnt koalaman/shellcheck:stable "$@"' bash
+        language: system
         types: [shell]
         files: \.(sh|bats)$
 
-  - repo: https://github.com/scop/pre-commit-shfmt
-    rev: v3.9.0-1
-    hooks:
-      - id: shfmt
-        args: [-sr, -i, '2', -w, -ci]
+      - id: shfmt-docker
+        name: shfmt (Docker)
+        entry: bash -c 'docker run --rm -v "$(pwd)":/work -w /work mvdan/shfmt:v3 -sr -i 2 -w -ci "$@"' bash
+        language: system
         types: [shell]
         files: \.(sh|bats)$
 
-  - repo: https://github.com/DavidAnson/markdownlint-cli2
-    rev: v0.15.0
-    hooks:
-      - id: markdownlint-cli2
+      - id: markdownlint-docker
+        name: markdownlint-cli2 (Docker)
+        entry: bash -c 'docker run --rm -v "$(pwd)":/work -w /work node:lts-alpine npx markdownlint-cli2 "$@"' bash
+        language: system
         types: [markdown]

AGENTS.md

@@ -90,6 +90,63 @@ Checks for new Node.js versions to build:
   - Quick start: `pre-commit install` then hooks run automatically on commit
 - **Branch Protection:** main branch requires passing checks and code owner review
 
+## Docker-Based Development
+
+All development tools run in official Docker containers. This approach requires only Docker; no local installation of shellcheck, shfmt, or Node.js needed.
+
+### Getting Started
+
+```bash
+# Run all linters
+make lint
+
+# Auto-fix formatting issues
+make format
+
+# See all available commands
+make help
+```
+
+### Makefile Targets
+
+The `Makefile` provides convenient targets for code quality checks:
+
+- `make lint` - Run all linters (shellcheck, shfmt, markdownlint)
+- `make format` - Auto-fix shell script formatting with shfmt
+- `make shellcheck` - Run shellcheck
+- `make shfmt` - Check shell script formatting
+- `make shfmt-fix` - Auto-fix shell formatting
+- `make markdown-lint` - Check markdown files
+- `make help` - Display all available targets
+
+### Pre-commit Hooks with Docker
+
+Pre-commit hooks are configured to run tools inside Docker containers for consistency:
+
+```bash
+pre-commit install  # Install hooks
+pre-commit run --all-files  # Run manually
+```
+
+Hooks automatically execute on commit using official Docker images. See [SETUP.md](./SETUP.md) for complete setup instructions.
+
+### For AI Agents
+
+To run development checks in an agent environment with only Docker available:
+
+```bash
+# Run all linters via Makefile
+make lint
+make format
+
+# Or run individual Docker commands
+docker run --rm -v "$(pwd)":/mnt koalaman/shellcheck:stable *.sh
+docker run --rm -v "$(pwd)":/work -w /work mvdan/shfmt:v3 -sr -i 2 -l -ci *.sh
+docker run --rm -v "$(pwd)":/work -w /work node:lts-alpine npx markdownlint-cli2 "*.md"
+```
+
+This approach requires only Docker to be installed in the agent's environment.
+
 ## Testing
 
 ### Unit Tests

Makefile

@@ -0,0 +1,28 @@
+.PHONY: help lint shellcheck shfmt shfmt-fix markdown-lint format
+
+export DOCKER_CLI_HINTS=false
+
+help:
+	@echo "Available targets:"
+	@echo "  lint              Run all linters (shellcheck, shfmt, markdownlint)"
+	@echo "  shellcheck        Run shellcheck"
+	@echo "  shfmt             Check shell script formatting"
+	@echo "  shfmt-fix         Auto-fix shell script formatting"
+	@echo "  markdown-lint     Check markdown files"
+	@echo "  format            Auto-format shell scripts (alias for shfmt-fix)"
+
+shellcheck:
+	docker run --rm -v "$$(pwd)":/mnt koalaman/shellcheck:stable *.sh
+
+shfmt:
+	docker run --rm -v "$$(pwd)":/work -w /work mvdan/shfmt:v3 -sr -i 2 -l -ci *.sh
+
+shfmt-fix:
+	docker run --rm -v "$$(pwd)":/work -w /work mvdan/shfmt:v3 -sr -i 2 -w -ci *.sh
+
+markdown-lint:
+	docker run --rm -v "$$(pwd)":/work -w /work node:lts-alpine sh -c "npx markdownlint-cli2 '*.md'"
+
+format: shfmt-fix
+
+lint: shellcheck shfmt markdown-lint