@misterzik/espressojs 3.3.4 → 3.3.5

package/CHANGELOG.md

@@ -2,6 +2,58 @@
 
 All notable changes to EspressoJS will be documented in this file.
 
+## [3.3.5] - 2024-12-25
+
+### Fixed
+- **Critical**: CLI process management - added `process.stdin.resume()` to keep parent process alive
+- Server now stays running properly when using `node cli run`
+- Event loop properly maintained for child process management
+
+### Added
+- Comprehensive CLI usage documentation (docs/CLI-USAGE.md)
+- `start:watch` npm script for auto-restart with nodemon
+- `dev:watch` npm script for development with auto-restart
+- `validate` npm script for configuration validation
+- Detailed process management documentation
+
+### Changed
+- Enhanced signal handling (SIGINT/SIGTERM) for graceful shutdown
+- Improved CLI process lifecycle management
+- Updated README with npm scripts section and process management explanation
+
+### Dependencies
+- Added nodemon ^3.0.2 as devDependency for development auto-restart
+
+## [3.3.4] - 2024-12-24
+
+### Added
+- Modern landing page UI with gradient background and glassmorphism design
+- Feature showcase grid with 6 interactive cards
+- Animated coffee icon with floating effect
+- Call-to-action buttons for GitHub and npm
+- Version badge display on landing page
+- Responsive design for mobile and tablet devices
+- Comprehensive CLI usage documentation (docs/CLI-USAGE.md)
+- `start:watch` and `dev:watch` npm scripts for auto-restart with nodemon
+- `validate` npm script for config validation
+
+### Changed
+- Completely redesigned public/index.html with modern aesthetics
+- Enhanced CLI output with emoji indicators and cleaner formatting
+- Improved CLI startup banner with better information display
+- Updated demo/public/index.html to match new design
+- Updated demo/config.json with new schema (publicDirectory, timeout, retries)
+- Updated demo/espresso.js to use APIManager instead of direct axios
+
+### Fixed
+- **Critical**: CLI process now stays alive after spawning server using `process.stdin.resume()`
+- Server startup process properly maintains event loop
+- Better signal handling (SIGINT/SIGTERM) for graceful shutdown
+- CLI no longer exits prematurely when running `node cli run`
+
+### Dependencies
+- Added nodemon ^3.0.2 as devDependency for development auto-restart
+
 ## [3.3.3] - 2024-12-24
 
 ### Fixed

package/README.md

@@ -112,9 +112,15 @@ node cli show
 # Run the server
 node cli run
 
+# Run with auto-restart (development)
+npm run start:watch
+
 # Update environment settings
 node cli env --instance=production --port=3000
 
+# Validate configuration
+node cli validate
+
 # Initialize new config
 node cli init
 
@@ -128,6 +134,37 @@ node cli version
 node cli --help
 ```
 
+### npm Scripts
+
+EspressoJS provides convenient npm scripts for common tasks:
+
+```bash
+# Start server
+npm start                    # Start with current config
+npm run start:watch          # Start with auto-restart (nodemon)
+
+# Development
+npm run dev                  # Start in development mode
+npm run dev:watch            # Dev mode with auto-restart
+
+# Production
+npm run prod                 # Start in production mode
+
+# Configuration
+npm run show                 # Display current config
+npm run validate             # Validate config.json
+```
+
+**Process Management:**
+
+The CLI uses a parent-child process model to keep your server running:
+- Parent process (CLI) manages the server lifecycle
+- Child process runs the Express application
+- `process.stdin.resume()` keeps the event loop active
+- Press `CTRL+C` for graceful shutdown
+
+For more details, see [CLI Usage Documentation](./docs/CLI-USAGE.md).
+
 ## 📁 Project Structure
 
 ```

package/docs/CLI-USAGE.md

@@ -0,0 +1,369 @@
+# EspressoJS CLI Usage Guide
+
+## Overview
+
+The EspressoJS CLI provides a powerful command-line interface for managing your Express server. This guide covers all available commands and best practices.
+
+## Installation
+
+```bash
+npm install @misterzik/espressojs
+```
+
+## Available Commands
+
+### `run` - Start the Server
+
+Starts the Express server with the current configuration.
+
+```bash
+node cli run
+```
+
+**How it works:**
+- The CLI spawns a child process running `index.js`
+- The parent CLI process stays alive to manage the child
+- Press `CTRL+C` to gracefully shut down the server
+
+**npm scripts:**
+```bash
+npm start              # Start with current config
+npm run start:watch    # Start with auto-restart on file changes (nodemon)
+```
+
+### `show` - Display Configuration
+
+Shows the current configuration from `config.json`.
+
+```bash
+node cli show
+```
+
+### `env` - Update Environment Settings
+
+Modify the instance type or port number.
+
+```bash
+# Change instance
+node cli env --instance=production
+
+# Change port
+node cli env --port=3000
+
+# Change both
+node cli env --instance=production --port=3000
+```
+
+### `validate` - Validate Configuration
+
+Validates your `config.json` against the schema.
+
+```bash
+node cli validate
+```
+
+### `init` - Initialize Configuration
+
+Creates a new `config.json` file with default settings.
+
+```bash
+node cli init
+
+# Force overwrite existing config
+node cli init --force
+```
+
+### `version` - Show Version
+
+Displays the EspressoJS version.
+
+```bash
+node cli version
+```
+
+## Process Management
+
+### Why the CLI Stays Alive
+
+The CLI uses a parent-child process model:
+
+1. **Parent Process (CLI)**: Manages the server lifecycle
+2. **Child Process (Server)**: Runs the Express application
+
+The parent process must stay alive to:
+- Keep the child process running
+- Handle graceful shutdown signals
+- Monitor server health
+- Provide process management
+
+**Technical Implementation:**
+```javascript
+// The CLI keeps the process alive using:
+process.stdin.resume();  // Prevents event loop from exiting
+
+// Signal handlers ensure graceful shutdown:
+process.on('SIGINT', () => {
+  child.kill('SIGINT');
+});
+```
+
+### Development vs Production
+
+**Development (with auto-restart):**
+```bash
+npm run dev:watch
+# or
+npm run start:watch
+```
+
+Uses `nodemon` to automatically restart the server when files change.
+
+**Production (stable):**
+```bash
+npm start
+# or
+node cli run
+```
+
+Runs the server without auto-restart for stability.
+
+## npm Scripts Reference
+
+| Script | Command | Description |
+|--------|---------|-------------|
+| `start` | `node cli run` | Start server with current config |
+| `start:watch` | `nodemon cli run` | Start with auto-restart |
+| `dev` | Set dev config + run | Start in development mode |
+| `dev:watch` | Set dev config + nodemon | Dev mode with auto-restart |
+| `global` | Set global config + run | Start in global mode |
+| `prod` | Set prod config + run | Start in production mode |
+| `show` | `node cli show` | Display configuration |
+| `validate` | `node cli validate` | Validate config.json |
+
+## Troubleshooting
+
+### Server Exits Immediately
+
+**Problem:** Server starts but exits right away.
+
+**Solution:** This is now fixed in v3.3.4+. The CLI uses `process.stdin.resume()` to keep the process alive.
+
+**If still experiencing issues:**
+```bash
+# Option 1: Use nodemon
+npm run start:watch
+
+# Option 2: Run server directly (bypasses CLI)
+node index.js
+```
+
+### Port Already in Use
+
+**Problem:** `EADDRINUSE` error.
+
+**Solution:**
+```bash
+# Change the port
+node cli env --port=3001
+node cli run
+```
+
+### Configuration Not Found
+
+**Problem:** `config.json` missing.
+
+**Solution:**
+```bash
+# Create new config
+node cli init
+```
+
+### Process Won't Stop
+
+**Problem:** Server doesn't respond to `CTRL+C`.
+
+**Solution:**
+```bash
+# Force kill (find process ID first)
+ps aux | grep node
+kill -9 <PID>
+
+# Or on Windows
+tasklist | findstr node
+taskkill /F /PID <PID>
+```
+
+## Best Practices
+
+### 1. Use npm Scripts
+
+Instead of running CLI commands directly, use npm scripts:
+
+```bash
+# Good
+npm start
+
+# Also good, but more verbose
+node cli run
+```
+
+### 2. Development Workflow
+
+```bash
+# Initial setup
+npm install
+node cli init
+
+# Start development
+npm run dev:watch
+
+# Test production config
+npm run prod
+```
+
+### 3. Environment-Specific Configs
+
+Create separate config files:
+- `config.development.json`
+- `config.production.json`
+- `config.test.json`
+
+Load them based on `NODE_ENV`:
+```javascript
+const env = process.env.NODE_ENV || 'development';
+const config = require(`./config.${env}.json`);
+```
+
+### 4. Process Managers for Production
+
+For production deployments, use a process manager:
+
+**PM2:**
+```bash
+npm install -g pm2
+pm2 start cli.js --name "espresso-app" -- run
+pm2 save
+pm2 startup
+```
+
+**Forever:**
+```bash
+npm install -g forever
+forever start cli.js run
+```
+
+**Docker:**
+```dockerfile
+FROM node:18-alpine
+WORKDIR /app
+COPY package*.json ./
+RUN npm ci --only=production
+COPY . .
+CMD ["node", "cli", "run"]
+```
+
+## Advanced Usage
+
+### Custom CLI Scripts
+
+You can extend the CLI in your own project:
+
+```javascript
+// custom-cli.js
+const { spawn } = require('child_process');
+
+// Custom command
+if (process.argv[2] === 'custom') {
+  console.log('Running custom command...');
+  // Your custom logic
+}
+
+// Fall back to EspressoJS CLI
+require('@misterzik/espressojs/cli');
+```
+
+### Programmatic Usage
+
+Use EspressoJS programmatically without the CLI:
+
+```javascript
+const app = require('@misterzik/espressojs');
+const config = require('@misterzik/espressojs/server');
+
+// Your custom setup
+app.use('/custom', (req, res) => {
+  res.json({ message: 'Custom route' });
+});
+
+// Start server
+const PORT = config.port || 3000;
+app.listen(PORT, () => {
+  console.log(`Server running on port ${PORT}`);
+});
+```
+
+## Signal Handling
+
+The CLI properly handles system signals:
+
+| Signal | Behavior |
+|--------|----------|
+| `SIGINT` | Graceful shutdown (CTRL+C) |
+| `SIGTERM` | Graceful shutdown (kill command) |
+| `SIGKILL` | Immediate termination (cannot be caught) |
+
+**Graceful Shutdown Process:**
+1. Signal received by CLI
+2. CLI forwards signal to child process
+3. Server closes HTTP connections
+4. MongoDB connections closed (if enabled)
+5. Process exits with appropriate code
+
+## FAQ
+
+**Q: Why use the CLI instead of running `index.js` directly?**
+
+A: The CLI provides:
+- Configuration management
+- Environment switching
+- Validation
+- Better error messages
+- Process management
+
+**Q: Can I use the CLI in production?**
+
+A: Yes, but consider using a process manager (PM2, Forever) for:
+- Auto-restart on crashes
+- Load balancing
+- Log management
+- Monitoring
+
+**Q: Does the CLI work on Windows?**
+
+A: Yes, the CLI is cross-platform and works on Windows, macOS, and Linux.
+
+**Q: How do I debug the CLI?**
+
+A: Use Node.js debugging:
+```bash
+node --inspect cli run
+```
+
+Then open Chrome DevTools at `chrome://inspect`.
+
+## Support
+
+- **GitHub Issues**: https://github.com/misterzik/Espresso.js/issues
+- **npm Package**: https://www.npmjs.com/package/@misterzik/espressojs
+- **Documentation**: https://github.com/misterzik/Espresso.js
+
+## Version History
+
+- **v3.3.4**: Fixed CLI process management with `process.stdin.resume()`
+- **v3.3.3**: Enhanced CLI output with emoji indicators
+- **v3.3.2**: Improved error handling
+- **v3.3.1**: Added multiple API support
+
+---
+
+**Happy coding with EspressoJS!** ☕

package/package.json

@@ -1,15 +1,18 @@
 {
     "name": "@misterzik/espressojs",
-    "version": "3.3.4",
+    "version": "3.3.5",
     "description": "EspressoJS Introducing Espresso.JS, your ultimate Express configuration starting point and boilerplate. With its simplicity and lack of opinionation, EspressoJS offers plug-and-play configurations built on top of Express.",
     "main": "index.js",
     "scripts": {
         "test": "echo \"Error: no test specified\"",
         "start": "node cli run",
+        "start:watch": "nodemon cli run",
         "dev": "node cli env --instance=development --port=8080 && node cli run",
+        "dev:watch": "node cli env --instance=development --port=8080 && nodemon cli run",
         "global": "node cli env --instance=global --port=8081 && node cli run",
         "prod": "node cli env --instance=production --port=80 && node cli run",
         "show": "node cli show",
+        "validate": "node cli validate",
         "build-dev": "webpack --mode development",
         "build-prod": "webpack --mode production"
     },
@@ -60,7 +63,8 @@
         "@babel/core": "^7.23.7",
         "@babel/preset-env": "^7.23.7",
         "amd-define-factory-patcher-loader": "^1.0.0",
-        "babel-loader": "^9.1.3"
+        "babel-loader": "^9.1.3",
+        "nodemon": "^3.0.2"
     },
     "engines": {
         "node": ">= 0.10.0"

package/server/utils/espresso-cli.js

@@ -76,7 +76,7 @@ function runCommand() {
       process.exit(code || 0);
     });
 
-    // Keep the CLI process alive
+    // Keep the CLI process alive by handling signals
     process.on('SIGINT', () => {
       console.log('\nShutting down server...');
       child.kill('SIGINT');
@@ -85,6 +85,10 @@ function runCommand() {
     process.on('SIGTERM', () => {
       child.kill('SIGTERM');
     });
+
+    // Prevent the process from exiting by keeping stdin open
+    // This ensures the CLI stays alive as long as the child process is running
+    process.stdin.resume();
   }
 }