fix(scripts): improve env loading in bun wrapper and add --help to dev.sh

- Unset env vars before sourcing to ensure file values take precedence
- Add quotes around APP_URL assignment for consistency
- Add --help flag showing usage, services, logs, and examples

Author: brandonkachen

.bin/bun

@@ -202,34 +202,40 @@ check_env_setup() {
     echo "" >&2
 }
 
-# Load project env files to ensure correct precedence
-# .env.development.local must be sourced last to override any inherited env vars
-load_project_env() {
-    # Source env files with auto-export
-    # Order matters: .env.local first, then .env.development.local overrides
-    set -a
-    
-    # Only source .env.local when running from subdirectory
-    # (Bun loads it natively when at project root)
-    if [ "$PROJECT_ROOT" != "$CALLING_DIR" ] && [ -f "$ENV_LOCAL_FILE" ]; then
-        # shellcheck disable=SC1090
-        source "$ENV_LOCAL_FILE"
+# Clear inherited env vars that would conflict with .env file values
+# Bun loads .env files natively, but inherited shell variables take precedence.
+# We unset variables defined in our env files so Bun can set fresh values.
+clear_inherited_env_vars() {
+    # Unset variables from .env.local so Bun can load fresh values
+    if [ -f "$ENV_LOCAL_FILE" ]; then
+        while IFS='=' read -r key _; do
+            # Skip comments and empty lines
+            case "$key" in
+                '#'*|'') continue ;;
+            esac
+            # Remove any 'export ' prefix
+            key="${key#export }"
+            unset "$key" 2>/dev/null || true
+        done < "$ENV_LOCAL_FILE"
     fi
 
-    # Always source .env.development.local to ensure worktree overrides
-    # take precedence over any inherited shell environment variables
+    # Unset variables from .env.development.local
     if [ -f "$ENV_DEVELOPMENT_LOCAL_FILE" ]; then
-        # shellcheck disable=SC1090
-        source "$ENV_DEVELOPMENT_LOCAL_FILE"
+        while IFS='=' read -r key _; do
+            case "$key" in
+                '#'*|'') continue ;;
+            esac
+            key="${key#export }"
+            unset "$key" 2>/dev/null || true
+        done < "$ENV_DEVELOPMENT_LOCAL_FILE"
     fi
-    
-    set +a
 }
 
 run_bun() {
     create_env_symlinks
     check_env_setup
-    load_project_env
+    clear_inherited_env_vars
+    # Bun natively loads .env files in the correct precedence order
     exec "$REAL_BUN" "$@"
 }
 

scripts/dev.sh

@@ -3,6 +3,48 @@
 
 set -e
 
+# =============================================================================
+# Help
+# =============================================================================
+
+show_help() {
+    cat << EOF
+Usage: $(basename "$0") [OPTIONS] [-- CLI_ARGS...]
+
+Starts the Codebuff development environment including database, web server,
+and CLI.
+
+Options:
+  -h, --help    Show this help message and exit
+
+Services Started:
+  db            PostgreSQL database (via Docker)
+  studio        Drizzle Studio for database inspection
+  web           Next.js web server (in tmux session 'codebuff-web')
+  cli           Codebuff CLI (foreground, interactive)
+
+Logs:
+  All service logs are written to: debug/console/
+    - db.log      Database startup logs
+    - studio.log  Drizzle Studio logs
+    - sdk.log     SDK build logs
+    - web.log     Web server logs
+
+Examples:
+  $(basename "$0")              # Start dev environment
+  $(basename "$0") --help       # Show this help
+  $(basename "$0") -- --debug   # Pass --debug flag to CLI
+
+To attach to web server logs:
+  tmux attach -t codebuff-web
+EOF
+}
+
+if [[ "$1" == "-h" || "$1" == "--help" ]]; then
+    show_help
+    exit 0
+fi
+
 # =============================================================================
 # Configuration
 # =============================================================================
@@ -11,6 +53,7 @@ SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 PROJECT_ROOT="$(dirname "$SCRIPT_DIR")"
 LOG_DIR="$PROJECT_ROOT/debug/console"
 BUN="$PROJECT_ROOT/.bin/bun"
+APP_URL="$NEXT_PUBLIC_CODEBUFF_APP_URL"
 
 export PATH="$PROJECT_ROOT/.bin:$PATH"
 mkdir -p "$LOG_DIR"
@@ -92,7 +135,7 @@ else
     tmux new-session -d -s codebuff-web "cd $PROJECT_ROOT && $BUN --cwd web dev 2>&1 | sed -l 's/\x1b\[[0-9;]*m//g' | tee $LOG_DIR/web.log"
 fi
 
-wait_for "web" "curl -sf ${NEXT_PUBLIC_CODEBUFF_APP_URL}/api/healthz"
+wait_for "web" "curl -sf ${APP_URL}/api/healthz"
 
 # 4. CLI (foreground - user interaction)
 echo ""