Make bin/setup fail fast, fail clearly, and stop dropping the dev DB

.devcontainer/post-create.sh

@@ -1,3 +1,4 @@
+#!/usr/bin/env bash
 RUBY_VERSION="$(cat .ruby-version | tr -d '\n')"
 
 # copy the file only if it doesn't already exist
@@ -11,4 +12,6 @@ if [ "$RUBY_VERSION" != "4.0.6" ]; then
 	echo "Ruby $RUBY_VERSION installed"
 fi
 
-bin/setup
+# --reset builds the development database from scratch. This is a brand new
+# container, so there is no local data to lose.
+bin/setup --reset

.github/workflows/shell_lint.yml

@@ -0,0 +1,80 @@
+name: Shell lint
+
+on:
+  push:
+    branches:
+      - main
+    paths:
+      - '**/*.sh'
+      - '**/*.bash'
+      - 'bin/**'
+      - 'docker/**'
+      - '.devcontainer/**'
+      - '.github/workflows/shell_lint.yml'
+  pull_request:
+    branches:
+      - main
+      - rfg-event-2025
+    paths:
+      - '**/*.sh'
+      - '**/*.bash'
+      - 'bin/**'
+      - 'docker/**'
+      - '.devcontainer/**'
+      - '.github/workflows/shell_lint.yml'
+
+jobs:
+  shellcheck:
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+
+      - name: Install shellcheck if the runner image lacks it
+        run: |
+          if ! command -v shellcheck > /dev/null 2>&1; then
+            sudo apt-get update
+            sudo apt-get install --no-install-recommends -y shellcheck
+          fi
+          shellcheck --version
+
+      - name: Shellcheck
+        # Many scripts here have no extension (bin/dev, docker/*), and bin/ also
+        # holds Ruby scripts, so select by shebang rather than by path.
+        #
+        # --severity=warning: the tree still has ~35 info/style findings, mostly
+        # SC2086 (unquoted variables) in bin/git_hooks and docker. Those are
+        # worth fixing, but gating on them today would mean rewriting scripts
+        # unrelated to whatever PR is being reviewed. Lower this as they get
+        # cleaned up.
+        run: |
+          set -eu
+
+          list=$(mktemp)
+          trap 'rm -f "$list"' EXIT
+
+          {
+            git ls-files -- '*.sh' '*.bash'
+            git ls-files | while IFS= read -r file; do
+              [ -f "$file" ] || continue
+              if head -n 1 "$file" |
+                  grep -qE '^#!.*[ /](bash|sh|dash|ksh)$'; then
+                printf '%s\n' "$file"
+              fi
+            done
+          } | sort -u > "$list"
+
+          count=$(wc -l < "$list" | tr -d '[:space:]')
+          if [ "$count" -eq 0 ]; then
+            echo "No shell scripts found -- check the discovery logic above."
+            exit 1
+          fi
+
+          echo "Checking $count shell scripts:"
+          sed 's/^/  /' "$list"
+          echo
+
+          xargs shellcheck --severity=warning -- < "$list"

CLAUDE.md

@@ -10,7 +10,7 @@ CASA is a Rails app used by CASA (Court Appointed Special Advocate) chapters to
 
 | Task | Command |
 |---|---|
-| One-time setup | `bin/setup` |
+| One-time setup | `bin/setup` (safe to re-run; `--reset` to rebuild the dev DB, `--skip-assets` to skip npm) |
 | Run app (web + JS/CSS watchers) | `bin/dev` then visit http://localhost:3000 |
 | Run full RSpec suite | `bin/rails spec` |
 | Run a single spec file | `bundle exec rspec spec/path/to/file_spec.rb` |

README.md

@@ -204,18 +204,34 @@ Run these commands before starting the installation process:
 </details>
 
 <details>
-<summary>bin/setup fails with a credentials error</summary>
+<summary>bin/setup says it cannot connect to postgres</summary>
 
-1. Open the `.env` file.
-2. Update `POSTGRES_USER` and `POSTGRES_PASSWORD` to match your PostgreSQL credentials.
-3. Run `bin/setup`
+`bin/setup` checks the database before doing anything slow, and prints the host, port
+and user it tried. Either postgres is not running, or the credentials in `.env` are
+wrong — update `POSTGRES_USER`, `POSTGRES_PASSWORD` and `DATABASE_HOST` to match your
+PostgreSQL setup and re-run `bin/setup`.
+</details>
+
+<details>
+<summary>I want to throw away my local data and start over</summary>
+
+Run `bin/setup --reset`. By default `bin/setup` preserves the development database;
+`--reset` drops, recreates and reseeds it.
 </details>
 
 ## Running the App / Verifying Installation
 1. `cd casa/`
 1. Run `bin/setup`
 1. Run `bin/dev` and visit http://localhost:3000/ to see the app running.
 
+`bin/setup` is safe to re-run — it preserves your development database. Options:
+
+| Flag | Effect |
+|---|---|
+| `--reset` | Drop, recreate and reseed the development database (destroys local data) |
+| `--skip-assets` | Skip `npm ci` and the JS/CSS builds |
+| `--help` | List the options |
+
 ### QA Environment
 
 A publicly accessible QA environment is available at **https://casa-qa.herokuapp.com/**. You can log in using the same seed credentials below — useful for exploring the app without any local setup.

bin/git_hooks/lint

@@ -32,10 +32,12 @@ case $diff_policy in
     ;;
 
   --unpushed)
-    if [ -z "$(git ls-remote --heads origin ${current_branch})" ]; then
-      changed_file_list=$(git diff --name-only HEAD~$(git cherry -v main ${current_branch} | wc -l) HEAD)
+    if [ -z "$(git ls-remote --heads origin "${current_branch}")" ]; then
+      # wc -l pads with whitespace on BSD/macOS, so strip it before interpolating.
+      unpushed_count=$(git cherry -v main "${current_branch}" | wc -l | tr -d '[:space:]')
+      changed_file_list=$(git diff --name-only "HEAD~${unpushed_count}" HEAD)
     else
-      changed_file_list=$(git diff --name-only origin/${current_branch}..HEAD)
+      changed_file_list=$(git diff --name-only "origin/${current_branch}..HEAD")
     fi
     ;;
 
@@ -55,7 +57,7 @@ lint_time=$(date +%s)
 if test $erb_changed_count -gt 0; then
   log info "Linting via erblint"
 
-  cd $repo_root/app
+  cd "$repo_root/app" || exit 1
 
   if ! [ -x "$(command -v bundle)" ]; then
     log error "Command bundle could not be found"
@@ -71,7 +73,7 @@ fi
 if test $factory_changed_count -gt 0; then
   log info "Linting via factory:lint"
 
-  cd $repo_root/app
+  cd "$repo_root/app" || exit 1
 
   if ! [ -x "$(command -v bundle)" ]; then
     log error "Command bundle could not be found"
@@ -87,7 +89,7 @@ fi
 if test $js_changed_count -gt 0; then
   log info "Linting javasript via standard"
 
-  cd $repo_root/app
+  cd "$repo_root/app" || exit 1
 
   if ! [ -x "$(command -v npm)" ]; then
     log error "Command npm could not be found"
@@ -103,7 +105,7 @@ fi
 if test $rb_changed_count -gt 0; then
   log info "Linting via standardrb"
 
-  cd $repo_root
+  cd "$repo_root" || exit 1
 
   if ! [ -x "$(command -v bundle)" ]; then
     log error "Command bundle could not be found"
@@ -116,7 +118,7 @@ if test $rb_changed_count -gt 0; then
   fi
 fi
 
-cd $repo_root
+cd "$repo_root" || exit 1
 for file in $(git diff --name-only); do
   last_modified_time=$(date -r $file +%s)
   if [ $last_modified_time -ge $lint_time ] ; then

bin/git_hooks/update-dependencies

@@ -28,7 +28,7 @@ fi
 
 log info "Checking javascript dependency status"
 
-if [ $(git diff HEAD@{1}..HEAD@{0} -- "package-lock.json" | wc -l) -gt 0 ] || [ $(git diff HEAD@{1}..HEAD@{0} -- "package.json" | wc -l) -gt 0 ]; then
+if ! git diff --quiet "HEAD@{1}..HEAD@{0}" -- package-lock.json package.json; then
   log info "Updating JavaScript dependencies"
   npm install
 fi