Complete startup automation and external access fixes

.gitignore

@@ -56,4 +56,11 @@ logs/
 
 # Cache
 .cache/
-.parcel-cache/
+.parcel-cache/
+
+# TypeScript
+*.tsbuildinfo
+tsconfig.tsbuildinfo
+
+# Prisma
+prisma/dev.db

README.md

@@ -44,25 +44,82 @@ GraphDone is built on the belief that:
 
 ## Quick Start
 
-### One-Command Setup
+### Prerequisites
+
+GraphDone requires:
+- **Node.js 18+** - JavaScript runtime (our setup script can install this automatically)
+- **Docker** - For running PostgreSQL database ([Install Docker](https://docs.docker.com/get-docker/))
+- **Git** - For version control (usually pre-installed)
+
+### One Command to Rule Them All
 
 ```bash
-git clone https://github.com/your-org/graphdone.git
-cd graphdone
-./tools/setup.sh
-./tools/run.sh
+git clone https://github.com/GraphDone/GraphDone-Core.git
+cd GraphDone-Core
+./start
 ```
 
-Visit http://localhost:3000 to see the working application!
+That's it! The script will automatically:
+- Check prerequisites and offer to install Node.js if needed
+- Install all dependencies
+- Set up your environment  
+- Start the database
+- Build the packages
+- Launch the development servers
+
+Visit **http://localhost:3127** when you see the "GraphDone is Ready!" message.
+
+> 💡 **Don't have Node.js?** No problem! The setup script will detect this and offer to install Node.js 18 for you using nvm (Node Version Manager).
 
 ### What You Get
 
-- 🌐 **Web Application**: Full graph visualization and collaboration interface
-- 🔗 **GraphQL API**: Complete backend with real-time subscriptions  
+- 🌐 **Web Application**: http://localhost:3127 - Full graph visualization and collaboration interface
+- 🔗 **GraphQL API**: http://localhost:4127/graphql - Complete backend with real-time subscriptions  
+- 🩺 **Health Check**: http://localhost:4127/health - Service status monitoring
 - 🗄️ **Database**: PostgreSQL with graph-optimized schema
-- 🐳 **Docker Setup**: Development and production containers
+- 🐳 **Docker Setup**: Development and production containers ready to go
 - 🧪 **Testing**: Comprehensive test suite with coverage reporting
 
+### Alternative Quick Commands
+
+```bash
+# Minimal launcher (less verbose)
+./launch.sh
+
+# Manual control (advanced users)
+./tools/setup.sh  # One-time setup
+./tools/run.sh    # Start development servers
+```
+
+### Troubleshooting
+
+**Docker Permission Denied?**
+```bash
+# Fix Docker permissions (then restart terminal)
+sudo usermod -aG docker $USER
+newgrp docker
+
+# Or run the setup with sudo assistance
+./start  # Will offer to use sudo automatically
+```
+
+**Node.js Missing?**
+```bash
+./start  # Will offer to install Node.js 18 automatically
+```
+
+**Port Already in Use?**
+```bash
+./tools/cleanup.sh  # Kill any hanging processes
+./start             # Try starting again
+```
+
+**Cannot Find Module Errors?**
+```bash
+./tools/fix-workspace.sh  # Fix workspace dependencies
+./start                   # Try starting again
+```
+
 ## Core Concepts
 
 ### Graph Structure
@@ -96,7 +153,7 @@ GraphDone is built for and by teams who think differently. We welcome contributi
 - Performance for large graphs
 
 **Get Started:**
-1. Run `./tools/setup.sh && ./tools/run.sh` to see the system working
+1. Run `./start` to see the system working locally
 2. Read our [philosophy](./docs/philosophy.md) and [architecture](./docs/guides/architecture-overview.md)
 3. Pick an area that excites you and matches your skills
 4. Join discussions in GitHub Issues and pull requests

deployment/docker-compose.yml

@@ -1,5 +1,3 @@
-version: '3.8'
-
 services:
   postgres:
     image: postgres:15-alpine
@@ -37,10 +35,10 @@ services:
     environment:
       - NODE_ENV=production
       - DATABASE_URL=postgresql://graphdone:graphdone_password@postgres:5432/graphdone
-      - PORT=4000
-      - CORS_ORIGIN=http://localhost:3000
+      - PORT=4127
+      - CORS_ORIGIN=http://localhost:3127
     ports:
-      - "4000:4000"
+      - "4127:4127"
     depends_on:
       postgres:
         condition: service_healthy
@@ -59,10 +57,10 @@ services:
       context: ..
       dockerfile: packages/web/Dockerfile
     environment:
-      - VITE_GRAPHQL_URL=http://localhost:4000/graphql
-      - VITE_GRAPHQL_WS_URL=ws://localhost:4000/graphql
+      - VITE_GRAPHQL_URL=http://localhost:4127/graphql
+      - VITE_GRAPHQL_WS_URL=ws://localhost:4127/graphql
     ports:
-      - "3000:3000"
+      - "3127:3127"
     depends_on:
       - server
     volumes:

launch.sh

@@ -0,0 +1,26 @@
+#!/bin/bash
+
+# GraphDone Simple Launcher
+# Super quick way to start GraphDone
+
+echo "🚀 GraphDone Quick Start"
+echo "========================"
+echo ""
+
+# Quick check for dependencies
+if ! command -v node &> /dev/null || ! command -v docker &> /dev/null; then
+    echo "❌ Missing dependencies. Please ensure Node.js and Docker are installed."
+    exit 1
+fi
+
+# Run setup if needed, then start
+if [ ! -f "packages/server/.env" ]; then
+    echo "⚡ Running quick setup..."
+    ./tools/setup.sh
+fi
+
+echo "🎯 Starting development servers..."
+./tools/run.sh
+
+echo ""
+echo "✅ GraphDone is running at http://localhost:3000"

packages/web/package.json

@@ -6,7 +6,7 @@
   "scripts": {
     "dev": "npm run kill-port && vite",
     "dev:force": "vite",
-    "kill-port": "lsof -ti:${PORT:-3000} | xargs -r kill || true",
+    "kill-port": "lsof -ti:${PORT:-3127} | xargs -r kill -9 || true",
     "build": "tsc && vite build",
     "preview": "vite preview",
     "test": "vitest",

packages/web/vite.config.ts

@@ -1,6 +1,7 @@
 import { defineConfig } from 'vite';
 import react from '@vitejs/plugin-react';
 import { resolve } from 'path';
+import { hostname } from 'os';
 
 export default defineConfig({
   plugins: [react()],
@@ -11,11 +12,13 @@ export default defineConfig({
     }
   },
   server: {
-    port: Number(process.env.PORT) || 3000,
+    host: '0.0.0.0', // Listen on all interfaces for external access
+    port: Number(process.env.PORT) || 3127,
     strictPort: true, // Exit if port is already in use instead of trying next available
+    allowedHosts: ['localhost', hostname(), '*.local', '.tailscale'], // Auto-detect hostname + common patterns
     proxy: {
       '/graphql': {
-        target: 'http://localhost:4000',
+        target: 'http://localhost:4127',
         changeOrigin: true
       }
     }

start

@@ -0,0 +1,141 @@
+#!/bin/bash
+
+# GraphDone Quick Launcher
+# The easiest way to get GraphDone running
+
+set -e
+
+# Colors for better output
+RED='\033[0;31m'
+GREEN='\033[0;32m'
+BLUE='\033[0;34m'
+YELLOW='\033[1;33m'
+PURPLE='\033[0;35m'
+CYAN='\033[0;36m'
+NC='\033[0m' # No Color
+
+# Clear screen for a clean start
+clear
+
+echo -e "${PURPLE}"
+echo "╔══════════════════════════════════════════════════════════════╗"
+echo "║                                                              ║"
+echo "║                     🌐 GraphDone 🌐                          ║"
+echo "║                                                              ║"
+echo "║           Graph-native project management system             ║"
+echo "║                                                              ║"
+echo "╚══════════════════════════════════════════════════════════════╝"
+echo -e "${NC}"
+
+# Function to ensure Node.js is available (same as in run.sh)
+ensure_nodejs() {
+    # If node/npm not found, try to source nvm
+    if ! command -v node &> /dev/null || ! command -v npm &> /dev/null; then
+        echo -e "${YELLOW}⚠️  Node.js/npm not found in PATH, attempting to load from nvm...${NC}"
+
+        # Try to load nvm
+        export NVM_DIR="$HOME/.nvm"
+        if [ -s "$NVM_DIR/nvm.sh" ]; then
+            source "$NVM_DIR/nvm.sh"
+            if [ -s "$NVM_DIR/bash_completion" ]; then
+                source "$NVM_DIR/bash_completion"
+            fi
+
+            # Use the latest installed version or 18
+            if nvm list | grep -q "v18"; then
+                nvm use 18
+            else
+                nvm use node
+            fi
+
+            echo -e "${GREEN}✅ Loaded Node.js from nvm: $(node --version)${NC}"
+        else
+            echo -e "${RED}❌ Node.js not found and nvm not available.${NC}"
+            echo "Please restart your terminal or run:"
+            echo "  source ~/.bashrc  # or ~/.zshrc"
+            echo "  ./start"
+            exit 1
+        fi
+    fi
+}
+
+echo -e "${CYAN}Welcome to GraphDone! This script will get you up and running quickly.${NC}"
+echo ""
+
+# Ensure Node.js is available
+ensure_nodejs
+
+# Check if setup or workspace repair is needed
+setup_needed=false
+workspace_repair_needed=false
+
+if [ ! -f "packages/server/.env" ] || [ ! -f "packages/web/.env" ]; then
+    setup_needed=true
+fi
+
+# Check if workspace dependencies are broken
+if [ ! -f "packages/core/dist/index.js" ] || [ ! -L "node_modules/@graphdone/core" ] || [ ! -f "node_modules/.prisma/client/index.js" ]; then
+    workspace_repair_needed=true
+fi
+
+# Run setup if needed
+if [ "$setup_needed" = true ]; then
+    echo -e "${YELLOW}🔧 First time setup detected...${NC}"
+    echo ""
+    echo -e "${BLUE}Running initial setup (this may take a few minutes):${NC}"
+    echo "  • Installing dependencies"
+    echo "  • Setting up environment variables"
+    echo "  • Starting database"
+    echo "  • Running migrations"
+    echo "  • Building packages"
+    echo ""
+
+    ./tools/setup.sh
+
+    echo ""
+    echo -e "${GREEN}✅ Setup complete!${NC}"
+    echo ""
+elif [ "$workspace_repair_needed" = true ]; then
+    echo -e "${YELLOW}🔧 Workspace dependencies need repair...${NC}"
+    echo ""
+    echo -e "${BLUE}Fixing workspace dependencies:${NC}"
+    echo "  • Rebuilding core package"
+    echo "  • Generating Prisma client"
+    echo "  • Ensuring workspace links"
+    echo ""
+
+    # Quick workspace repair (less aggressive than full setup)
+    echo -e "${CYAN}📦 Installing dependencies...${NC}"
+    npm install
+
+    echo -e "${CYAN}🏗️  Building core package...${NC}"
+    (cd packages/core && npm run build)
+
+    echo -e "${CYAN}🔧 Generating Prisma client...${NC}"
+    (cd packages/server && npx prisma generate)
+
+    # Verify the fix worked
+    if [ -f "packages/core/dist/index.js" ] && [ -L "node_modules/@graphdone/core" ]; then
+        echo ""
+        echo -e "${GREEN}✅ Workspace repair complete!${NC}"
+        echo ""
+    else
+        echo ""
+        echo -e "${RED}❌ Workspace repair failed. Running full setup...${NC}"
+        echo ""
+        ./tools/setup.sh
+    fi
+fi
+
+echo -e "${BLUE}🚀 Starting GraphDone development environment...${NC}"
+echo ""
+
+# Start the development environment
+if ! ./tools/run.sh; then
+    echo ""
+    echo -e "${YELLOW}⚠️  If you see 'command not found' errors:${NC}"
+    echo "   1. Restart your terminal"
+    echo "   2. Or run: source ~/.bashrc (or ~/.zshrc)"
+    echo "   3. Then try: ./start again"
+    echo ""
+fi

tools/cleanup.sh

@@ -0,0 +1,41 @@
+#!/bin/bash
+
+# GraphDone Cleanup Script
+# Kills any processes running on GraphDone's ports
+
+echo "🧹 Cleaning up GraphDone processes..."
+
+# Function to kill processes on a specific port
+kill_port() {
+    local port=$1
+    local pids=$(lsof -ti:$port 2>/dev/null)
+
+    if [ -n "$pids" ]; then
+        echo "🔄 Killing processes on port $port: $pids"
+        echo "$pids" | xargs kill -9 2>/dev/null || true
+        sleep 1
+
+        # Check if any processes are still running
+        local remaining=$(lsof -ti:$port 2>/dev/null)
+        if [ -n "$remaining" ]; then
+            echo "⚠️  Some processes on port $port are still running: $remaining"
+        else
+            echo "✅ Port $port is now free"
+        fi
+    else
+        echo "✅ Port $port is already free"
+    fi
+}
+
+# Clean up GraphDone ports
+kill_port 3127  # Web server
+kill_port 4127  # GraphQL API
+
+# Also kill any npm/node processes that might be hanging
+echo "🔄 Cleaning up any hanging npm/node processes..."
+pkill -f "npm run dev" 2>/dev/null || true
+pkill -f "vite" 2>/dev/null || true
+pkill -f "tsx watch" 2>/dev/null || true
+
+echo ""
+echo "✅ Cleanup complete! You can now run ./start again."