docs : Make Echo seamless to run locally

[naaa760]

Problem

• echo was difficult to run locally - users had to manually set up Docker, PostgreSQL, environment variables, and run multiple database commands. The setup process was complex and error-prone.

Solution

Created an automated setup script that handles everything automatically, making Echo work locally with just 3 commands.

Changes

New Files:

• scripts/setup-local.sh - Automated local development setup script
• LOCAL_DEVELOPMENT.md - Comprehensive local development guide

Modified Files:

• README.md - Added simple local development quick start
• packages/app/control/README.md - Updated setup instructions with Docker requirements
• package.json - Added "setup": "./scripts/setup-local.sh" script

What the setup script does:

• Checks prerequisites (Node.js 18+, pnpm, Docker)
• Installs dependencies
• Creates all required .env files
• Starts PostgreSQL container
• Runs database migrations
• Provides clear error messages and success feedback

fix: #597

[vercel]

@naaa760 is attempting to deploy a commit to the Merit Systems Team on Vercel.

A member of the Team first needs to authorize it.

[vercel]

Additional Suggestion:

The AUTH_SECRET generation check is too lenient - it considers an empty AUTH_SECRET= as "already set" and skips generation, leaving developers with an invalid empty secret that will break authentication.

View Details

📝 Patch Details

diff --git a/packages/app/control/scripts/setup.sh b/packages/app/control/scripts/setup.sh
index c7e3e89b..c64ea8b7 100755
--- a/packages/app/control/scripts/setup.sh
+++ b/packages/app/control/scripts/setup.sh
@@ -1,7 +1,7 @@
 #!/bin/bash
 
 # Check if .env file exists and if AUTH_SECRET is already set
-if [ -f .env ] && grep -q "^AUTH_SECRET=" .env; then
+if [ -f .env ] && grep -qE "^AUTH_SECRET=.+" .env; then
     echo "AUTH_SECRET already exists in .env file. Skipping generation."
 else
     echo "Generating AUTH_SECRET..."

Analysis

AUTH_SECRET generation check allows empty values, breaking authentication

What fails: packages/app/control/scripts/setup.sh line 4 uses pattern ^AUTH_SECRET= which matches empty AUTH_SECRET= entries, causing setup to skip secret generation when AUTH_SECRET exists but has no value

How to reproduce:

# 1. Copy .env.example (contains AUTH_SECRET=)
# 2. Run setup-local.sh flow:
cd packages/app/control && grep -q "^AUTH_SECRET=." .env || echo "calls pnpm local-setup"
# setup.sh checks: grep -q "^AUTH_SECRET=" .env && echo "skips generation"

Result: AUTH_SECRET remains empty (AUTH_SECRET=), causing env validation errors at runtime since src/env.ts requires AUTH_SECRET: z.string()

Expected: setup.sh should only skip generation when AUTH_SECRET has an actual value, matching setup-local.sh behavior which uses ^AUTH_SECRET=. pattern