@gv-sh/specgen-app 0.3.1 → 0.5.0

package/README.md

@@ -1,6 +1,6 @@
 # SpecGen App - Complete Platform
 
-[![Version](https://img.shields.io/badge/version-0.3.1-blue.svg)](https://github.com/gv-sh/specgen-app)
+[![Version](https://img.shields.io/badge/version-0.5.0-blue.svg)](https://github.com/gv-sh/specgen-app)
 
 A unified deployment package for the SpecGen speculative fiction generator platform.
 
@@ -12,6 +12,42 @@ A unified deployment package for the SpecGen speculative fiction generator platf
 
 ## Quick Start
 
+### Using NPX (Recommended)
+
+```bash
+# Create and enter your project directory
+mkdir specgen-project
+cd specgen-project
+
+# Run setup directly with npx
+npx @gv-sh/specgen-app setup
+
+# Start in development mode
+npx @gv-sh/specgen-app dev
+
+# Or start in production mode
+npx @gv-sh/specgen-app production
+```
+
+### Low Memory Mode for Small Servers
+
+If you're deploying on a small EC2 instance or any server with limited RAM:
+
+```bash
+# First, add swap space to prevent out-of-memory errors
+sudo fallocate -l 2G /swapfile
+sudo chmod 600 /swapfile
+sudo mkswap /swapfile
+sudo swapon /swapfile
+echo '/swapfile none swap sw 0 0' | sudo tee -a /etc/fstab
+
+# Then use the low-memory versions of the commands
+npx @gv-sh/specgen-app setup-low-memory
+npx @gv-sh/specgen-app production-low-memory
+```
+
+### Using NPM Scripts
+
 1. **Setup**:
    ```bash
    npm run setup
@@ -38,7 +74,7 @@ A unified deployment package for the SpecGen speculative fiction generator platf
 
 ## Deployment Options
 
-### Option 1: Quick NPM Deployment to Remote Server
+### Option 1: Quick NPX Deployment to Remote Server
 
 If you have SSH access to a server (like an EC2 instance), this is the fastest way to deploy:
 
@@ -60,33 +96,39 @@ If you have SSH access to a server (like an EC2 instance), this is the fastest w
 
 4. **Install and run SpecGen**:
    ```bash
-   # Install globally
-   sudo npm install -g @gv-sh/specgen-app
+   # Add swap space to prevent out-of-memory errors
+   sudo fallocate -l 2G /swapfile
+   sudo chmod 600 /swapfile
+   sudo mkswap /swapfile
+   sudo swapon /swapfile
+   echo '/swapfile none swap sw 0 0' | sudo tee -a /etc/fstab
    
    # Create and enter project directory
    mkdir specgen
    cd specgen
    
-   # Run the setup
-   npx @gv-sh/specgen-app setup
+   # Run the setup with low memory optimization
+   npx @gv-sh/specgen-app setup-low-memory
    
-   # Start in production mode
-   npx @gv-sh/specgen-app production
+   # Start in production mode with low memory optimization
+   npx @gv-sh/specgen-app production-low-memory
    ```
 
 5. **Keep the service running with PM2** (recommended):
    ```bash
    sudo npm install -g pm2
-   pm2 start "npx @gv-sh/specgen-app production" --name "specgen"
+   # Use the low-memory production mode with PM2
+   pm2 start "npx @gv-sh/specgen-app production-low-memory" --name "specgen"
    pm2 startup
    pm2 save
    ```
 
 6. **Access your application**:
-   - User Interface: http://your-server-ip:3000
-   - Admin Interface: http://your-server-ip:3000/admin
+   - User Interface: http://your-server-ip:3002
+   - Admin Interface: http://your-server-ip:3001
+   - API: http://your-server-ip:3000
 
-### Option 2: NPM Package Deployment (Detailed)
+### Option 2: Global NPM Package Deployment
 
 #### Local Machine Deployment
 
@@ -103,13 +145,13 @@ If you have SSH access to a server (like an EC2 instance), this is the fastest w
 
 3. **Initialize and setup**:
    ```bash
-   npx @gv-sh/specgen-app setup
+   specgen-app setup
    ```
    During setup, you'll be prompted to enter your OpenAI API key.
 
 4. **Start the application**:
-   - Development mode: `npx @gv-sh/specgen-app dev`
-   - Production mode: `npx @gv-sh/specgen-app production`
+   - Development mode: `specgen-app dev`
+   - Production mode: `specgen-app production`
 
 #### Remote Server Deployment
 
@@ -130,19 +172,19 @@ If you have SSH access to a server (like an EC2 instance), this is the fastest w
    cd specgen
    ```
 
-4. **Install SpecGen**:
+4. **Install SpecGen globally**:
    ```bash
-   npm install @gv-sh/specgen-app
+   npm install -g @gv-sh/specgen-app
    ```
 
 5. **Setup the application**:
    ```bash
-   npx @gv-sh/specgen-app setup
+   specgen-app setup
    ```
 
 6. **Start in production mode**:
    ```bash
-   npx @gv-sh/specgen-app production
+   specgen-app production
    ```
 
 ### Option 3: Manual Deployment
@@ -172,13 +214,22 @@ sudo ./deploy.sh
 
 ## Management Commands
 
-When using NPM global installation:
+When using NPX or global installation:
 ```bash
 # Check status
-npx @gv-sh/specgen-app status
+npx @gv-sh/specgen-app deploy:status
+# or when installed globally
+specgen-app deploy:status
 
 # Stop services
-npx @gv-sh/specgen-app stop
+npx @gv-sh/specgen-app deploy:stop
+# or
+specgen-app deploy:stop
+
+# Restart services
+npx @gv-sh/specgen-app deploy:restart
+# or
+specgen-app deploy:restart
 
 # Update to latest version
 npm update -g @gv-sh/specgen-app
@@ -202,14 +253,34 @@ npm run deploy:status
 npm run deploy:backup
 ```
 
+## Available Commands
+
+The following commands are available when using `npx @gv-sh/specgen-app` or `specgen-app` (if installed globally):
+
+- `setup` - Set up the SpecGen application
+- `setup-low-memory` - Set up the SpecGen application with memory optimizations
+- `production` - Run the application in production mode
+- `production-low-memory` - Run the application in production mode with memory optimizations
+- `dev` - Run the application in development mode
+- `deploy` - Deploy the application
+- `deploy:stop` - Stop the deployed application
+- `deploy:restart` - Restart the deployed application
+- `deploy:update` - Update the deployed application
+- `deploy:status` - Check the status of the deployed application
+- `deploy:backup` - Create a backup of the deployed application
+- `troubleshoot` - Run troubleshooting checks
+
 ## Troubleshooting
 
 If you encounter issues:
 
 ```bash
-# For global NPM installation
+# Using npx
 npx @gv-sh/specgen-app troubleshoot
 
+# Using global installation
+specgen-app troubleshoot
+
 # For repository installation
 npm run troubleshoot
 ```

package/bin/cli.js

@@ -0,0 +1,89 @@
+#!/usr/bin/env node
+
+const { execSync } = require('child_process');
+const path = require('path');
+const fs = require('fs');
+
+// Find the root directory of the package
+const findPackageRoot = () => {
+  // When installed as a dependency, the package will be in node_modules/@gv-sh/specgen-app
+  // When running directly from the package, we're already at the root
+  const packageJsonPath = path.resolve(__dirname, '../package.json');
+  
+  if (fs.existsSync(packageJsonPath)) {
+    return path.dirname(packageJsonPath);
+  }
+  
+  throw new Error('Could not locate package root directory');
+};
+
+const runScript = (scriptName) => {
+  try {
+    const packageRoot = findPackageRoot();
+    process.chdir(packageRoot);
+    
+    console.log(`📦 Running ${scriptName} script...`);
+    execSync(`npm run ${scriptName}`, { stdio: 'inherit' });
+    
+    console.log(`✅ ${scriptName} completed successfully`);
+  } catch (error) {
+    console.error(`❌ Error during ${scriptName}:`, error.message);
+    process.exit(1);
+  }
+};
+
+const command = process.argv[2];
+
+switch (command) {
+  case 'setup':
+    runScript('setup');
+    break;
+  case 'setup-low-memory':
+    runScript('setup-low-memory');
+    break;
+  case 'production':
+    runScript('production');
+    break;
+  case 'production-low-memory':
+    runScript('production-low-memory');
+    break;
+  case 'dev':
+    runScript('dev');
+    break;
+  case 'deploy':
+    runScript('deploy');
+    break;
+  case 'deploy:stop':
+    runScript('deploy:stop');
+    break;
+  case 'deploy:restart':
+    runScript('deploy:restart');
+    break;
+  case 'deploy:update':
+    runScript('deploy:update');
+    break;
+  case 'deploy:status':
+    runScript('deploy:status');
+    break;
+  case 'deploy:backup':
+    runScript('deploy:backup');
+    break;
+  case 'troubleshoot':
+    runScript('troubleshoot');
+    break;
+  default:
+    console.log('Usage: specgen-app <command>');
+    console.log('\nAvailable commands:');
+    console.log('  setup           - Set up the SpecGen application');
+  console.log('  setup-low-memory - Set up the SpecGen application with memory optimizations');
+    console.log('  production      - Run the application in production mode');
+  console.log('  production-low-memory - Run the application in production mode with memory optimizations');
+    console.log('  dev             - Run the application in development mode');
+    console.log('  deploy          - Deploy the application');
+    console.log('  deploy:stop     - Stop the deployed application');
+    console.log('  deploy:restart  - Restart the deployed application');
+    console.log('  deploy:update   - Update the deployed application');
+    console.log('  deploy:status   - Check the status of the deployed application');
+    console.log('  deploy:backup   - Create a backup of the deployed application');
+    console.log('  troubleshoot    - Run troubleshooting checks');
+}

package/index.js

@@ -0,0 +1,14 @@
+// This file makes the package importable
+// The main functionality is provided through the CLI
+
+module.exports = {
+  version: require('./package.json').version,
+  description: 'SpecGen Application Package',
+  
+  // Export script paths for programmatic access
+  scripts: {
+    setup: require.resolve('./scripts/setup.sh'),
+    dev: require.resolve('./scripts/dev.sh'),
+    production: require.resolve('./scripts/production.sh')
+  }
+};

package/package.json

@@ -1,14 +1,19 @@
 {
   "name": "@gv-sh/specgen-app",
-  "version": "0.3.1",
+  "version": "0.5.0",
   "description": "Complete SpecGen application with server, admin, and user interfaces",
   "main": "index.js",
+  "bin": {
+    "specgen-app": "./bin/cli.js"
+  },
   "scripts": {
     "setup": "chmod +x scripts/setup.sh && ./scripts/setup.sh",
+    "setup-low-memory": "chmod +x scripts/setup-low-memory.sh && ./scripts/setup-low-memory.sh",
     "dev": "chmod +x scripts/dev.sh && ./scripts/dev.sh",
     "build": "cd admin && npm run build && cd ../user && npm run build",
     "start": "cd server && npm start",
     "production": "chmod +x scripts/production.sh && ./scripts/production.sh",
+    "production-low-memory": "chmod +x scripts/production-low-memory.sh && ./scripts/production-low-memory.sh",
     "make-executable": "chmod +x scripts/make-executable.sh && ./scripts/make-executable.sh",
     "deploy": "chmod +x scripts/deploy.sh && ./scripts/deploy.sh",
     "deploy:stop": "chmod +x scripts/stop.sh && ./scripts/stop.sh",
@@ -16,7 +21,8 @@
     "deploy:update": "chmod +x scripts/update.sh && ./scripts/update.sh",
     "deploy:status": "chmod +x scripts/status.sh && ./scripts/status.sh",
     "deploy:backup": "chmod +x scripts/backup.sh && ./scripts/backup.sh",
-    "troubleshoot": "chmod +x scripts/troubleshoot.sh && ./scripts/troubleshoot.sh"
+    "troubleshoot": "chmod +x scripts/troubleshoot.sh && ./scripts/troubleshoot.sh",
+    "postinstall": "chmod +x bin/cli.js"
   },
   "dependencies": {
     "@gv-sh/specgen-server": "0.9.0",

package/scripts/make-executable.sh

@@ -1,6 +1,16 @@
 #!/bin/bash
 
-# Make all scripts executable
-chmod +x scripts/*.sh
+# SpecGen Package Deployment Script
+echo "📦 Making files executable..."
 
-echo "✅ All scripts are now executable"
+# Make all shell scripts executable
+find scripts -name "*.sh" -exec chmod +x {} \;
+
+# Make CLI executable
+chmod +x bin/cli.js
+
+# Make sure the low memory scripts are executable
+chmod +x scripts/setup-low-memory.sh
+chmod +x scripts/production-low-memory.sh
+
+echo "✅ All scripts are now executable"

package/scripts/production-low-memory.sh

@@ -0,0 +1,119 @@
+#!/bin/bash
+
+# SpecGen Production Script - Low Memory Version
+set -e
+
+echo "🚀 Starting SpecGen in production mode (Low Memory)..."
+
+# Function to check if port is available
+check_port() {
+    local port=$1
+    if lsof -Pi :$port -sTCP:LISTEN -t >/dev/null 2>&1; then
+        return 1  # Port in use
+    else
+        return 0  # Port available
+    fi
+}
+
+# Verify OpenAI API key
+if [ -f "server/.env" ]; then
+    # In CI mode, skip API key validation
+    if [ "$CI" = "true" ]; then
+        echo "CI mode detected - skipping API key validation"
+    elif grep -q "OPENAI_API_KEY=your_openai_api_key_here" server/.env; then
+        echo "⚠️ No OpenAI API key detected!"
+        echo "Enter your OpenAI API key: "
+        read -r OPENAI_KEY
+        
+        if [ -z "$OPENAI_KEY" ]; then
+            echo "❌ No API key provided. Cannot start in production mode."
+            exit 1
+        else
+            # Update the API key in the .env file
+            sed -i.bak "s/OPENAI_API_KEY=.*/OPENAI_API_KEY=$OPENAI_KEY/" server/.env
+            rm -f server/.env.bak
+            echo "✅ API key updated in server/.env"
+        fi
+    fi
+else
+    echo "❌ server/.env file not found. Run 'npm run setup' first."
+    exit 1
+fi
+
+# Verify directories exist
+for dir in server admin user; do
+    if [ ! -d "$dir" ]; then
+        echo "❌ $dir directory not found. Run 'npm run setup' first."
+        exit 1
+    fi
+done
+
+# Make sure node_modules exist in the server directory
+if [ ! -d "server/node_modules" ]; then
+    echo "Installing server dependencies..."
+    cd server
+    # Create a .npmrc file that ignores engine requirements
+    echo "engine-strict=false" > .npmrc
+    npm install --no-fund --no-audit --production --maxsockets=2 --loglevel=warn
+    cd ..
+fi
+
+# Set production environment
+export NODE_ENV=production
+
+# Check if we need to build
+if [ ! -d "admin/build" ] || [ ! -d "user/build" ]; then
+    echo "Building web interfaces (optimized mode)..."
+    
+    # Admin build
+    if [ ! -d "admin/build" ]; then
+        echo "Building admin..."
+        cd admin
+        echo "engine-strict=false" > .npmrc
+        # Install only production dependencies
+        npm install --no-fund --no-audit --production --maxsockets=2 --loglevel=warn
+        # Set environment for smaller build
+        export GENERATE_SOURCEMAP=false
+        export SKIP_PREFLIGHT_CHECK=true
+        npm run build
+        cd ..
+    fi
+    
+    # User build
+    if [ ! -d "user/build" ]; then
+        echo "Building user..."
+        cd user
+        echo "engine-strict=false" > .npmrc
+        # Install only production dependencies
+        npm install --no-fund --no-audit --production --maxsockets=2 --loglevel=warn
+        # Set environment for smaller build
+        export GENERATE_SOURCEMAP=false
+        export SKIP_PREFLIGHT_CHECK=true
+        npm run build
+        cd ..
+    fi
+fi
+
+# Create production-ready .env for server
+cat > server/.env.production << EOF
+$(cat server/.env)
+NODE_ENV=production
+EOF
+
+# Kill existing processes on required ports if needed
+echo "Checking ports..."
+for port in 3000 3001 3002; do
+    if ! check_port $port; then
+        echo "Port $port is in use. Attempting to free it..."
+        lsof -ti:$port | xargs kill -9 2>/dev/null || true
+        sleep 1
+    fi
+done
+
+# Start production server
+echo "Starting production server..."
+if [ "$CI" = "true" ]; then
+    echo "CI mode detected - skipping server start"
+else
+    cd server && NODE_ENV=production npm start
+fi

package/scripts/setup-low-memory.sh

@@ -0,0 +1,203 @@
+#!/bin/bash
+
+# SpecGen Low-Memory Setup Script
+set -e
+
+echo "🚀 Setting up SpecGen App (Low Memory Mode)..."
+
+# Check Node.js
+if ! command -v npm &> /dev/null; then
+    echo "❌ npm not found. Please install Node.js from https://nodejs.org/"
+    exit 1
+fi
+
+# Function to safely remove directories with permission handling
+safe_remove() {
+    if [ -d "$1" ]; then
+        echo "Removing $1..."
+        chmod -R u+w "$1" 2>/dev/null || true
+        rm -rf "$1" 2>/dev/null || true
+        # If still exists, try with sudo
+        if [ -d "$1" ]; then
+            echo "Using elevated permissions to remove $1..."
+            sudo rm -rf "$1" 2>/dev/null || true
+        fi
+    fi
+}
+
+# Clean existing directories with proper permission handling
+echo "Cleaning existing directories..."
+safe_remove "server"
+safe_remove "admin" 
+safe_remove "user"
+rm -f *.tgz package 2>/dev/null || true
+
+# Install dependencies one at a time with reduced memory usage
+echo "📦 Installing dependencies (low memory mode)..."
+npm install --no-fund --no-audit --ignore-scripts --production=false --maxsockets=2 --loglevel=warn
+
+# Create a .npmrc file that ignores engine requirements
+echo "engine-strict=false" > .npmrc
+
+# Download npm packages one at a time
+echo "📦 Downloading packages..."
+npm pack @gv-sh/specgen-server --loglevel=warn
+npm pack @gv-sh/specgen-admin --loglevel=warn
+npm pack @gv-sh/specgen-user --loglevel=warn
+
+# Extract packages
+echo "📁 Extracting packages..."
+
+# Extract server
+if [ -f "gv-sh-specgen-server-"*.tgz ]; then
+    echo "Extracting server..."
+    tar -xzf gv-sh-specgen-server-*.tgz
+    mv package server
+    rm gv-sh-specgen-server-*.tgz
+fi
+
+# Extract admin
+if [ -f "gv-sh-specgen-admin-"*.tgz ]; then
+    echo "Extracting admin..."
+    tar -xzf gv-sh-specgen-admin-*.tgz
+    mv package admin
+    rm gv-sh-specgen-admin-*.tgz
+fi
+
+# Extract user
+if [ -f "gv-sh-specgen-user-"*.tgz ]; then
+    echo "Extracting user..."
+    tar -xzf gv-sh-specgen-user-*.tgz
+    mv package user
+    rm gv-sh-specgen-user-*.tgz
+fi
+
+# Patch package.json files to fix React scripts
+echo "🔧 Patching package scripts..."
+
+# Fix user package start script
+if [ -f "user/package.json" ]; then
+    echo "Fixing user package start script..."
+    # Replace the start script to use react-scripts instead of missing scripts/start.js
+    sed -i.bak 's|"start": "cross-env PORT=3002 REACT_APP_API_URL=http://localhost:3000 node scripts/start.js"|"start": "cross-env PORT=3002 REACT_APP_API_URL=http://localhost:3000 react-scripts start"|g' user/package.json
+    rm -f user/package.json.bak
+fi
+
+# Fix admin package start script if needed
+if [ -f "admin/package.json" ]; then
+    echo "Checking admin package start script..."
+    # Check if admin has similar issue
+    if grep -q "node scripts/start.js" admin/package.json; then
+        echo "Fixing admin package start script..."
+        sed -i.bak 's|node scripts/start.js|react-scripts start|g' admin/package.json
+        rm -f admin/package.json.bak
+    fi
+fi
+
+# Create .npmrc files with engine-strict=false in each directory
+echo "Creating .npmrc files to ignore engine requirements..."
+for dir in server admin user; do
+  if [ -d "$dir" ]; then
+    echo "engine-strict=false" > "$dir/.npmrc"
+  fi
+done
+
+# Install dependencies for each component with memory optimizations
+echo "📚 Installing dependencies (low memory mode)..."
+for dir in server admin user; do
+    if [ -d "$dir" ]; then
+        echo "Installing $dir dependencies..."
+        (cd "$dir" && npm install --no-fund --no-audit --ignore-scripts --loglevel=warn --production=false --maxsockets=2 --force --omit=dev)
+    else
+        echo "⚠️  Warning: $dir directory not found"
+    fi
+done
+
+# Setup environment files
+echo "🔧 Setting up environment files..."
+
+# Server .env
+if [ ! -f server/.env ] || [ "$CI" = "true" ]; then
+    # If in CI mode, use a dummy key
+    if [ "$CI" = "true" ]; then
+        # If in CI environment and .env already exists, just use it
+        if [ -f server/.env ]; then
+            echo "Using existing .env file for CI environment"
+        else
+            # Create a CI .env file
+            cat > server/.env << EOF
+OPENAI_API_KEY=sk-test1234
+NODE_ENV=test
+PORT=3000
+EOF
+            echo "Created test .env file for CI environment"
+        fi
+        KEY_PROVIDED=true
+    else
+        # Normal interactive mode
+        # Prompt for OpenAI API key
+        echo "To use SpecGen, you need an OpenAI API key."
+        echo "Enter your OpenAI API key (or press enter to set it later): "
+        read -r OPENAI_KEY
+        
+        # If key is provided, use it, otherwise use placeholder
+        if [ -z "$OPENAI_KEY" ]; then
+            OPENAI_KEY="your_openai_api_key_here"
+            KEY_PROVIDED=false
+        else
+            KEY_PROVIDED=true
+        fi
+        
+        cat > server/.env << EOF
+# OpenAI API key
+OPENAI_API_KEY=$OPENAI_KEY
+NODE_ENV=development
+PORT=3000
+EOF
+        
+        if [ "$KEY_PROVIDED" = true ]; then
+            echo "✅ OpenAI API key saved to server/.env"
+        else
+            echo "⚠️ No OpenAI API key provided. You'll need to add it later to server/.env"
+        fi
+    fi
+fi
+
+# Admin .env.development  
+if [ -d admin ]; then
+    cat > admin/.env.development << 'EOF'
+REACT_APP_API_URL=http://localhost:3000
+PORT=3001
+SKIP_PREFLIGHT_CHECK=true
+GENERATE_SOURCEMAP=false
+EOF
+fi
+
+# User .env.development
+if [ -d user ]; then
+    cat > user/.env.development << 'EOF'
+REACT_APP_API_URL=http://localhost:3000  
+PORT=3002
+SKIP_PREFLIGHT_CHECK=true
+GENERATE_SOURCEMAP=false
+EOF
+fi
+
+echo "✅ Low-memory setup complete!"
+echo ""
+echo "Next steps:"
+if [ "$KEY_PROVIDED" = false ]; then
+    echo "1. Add your OpenAI API key to server/.env"
+    echo "2. Use 'npm run dev' to start all services"
+else
+    echo "1. Use 'npm run dev' to start all services"
+fi
+echo ""
+echo "If you're deploying on a low-memory system, we recommend:"
+echo "1. npm run build (to create optimized bundles)"
+echo "2. npm run production (to start in production mode)"
+echo ""
+echo "Access URLs:"
+echo "  🌐 User Interface: http://localhost:3002"
+echo "  ⚙️  Admin Interface: http://localhost:3001"  
+echo "  🔧 API: http://localhost:3000"