@abyrd9/harbor-cli 1.0.1 → 1.1.1

package/README.md

@@ -1,47 +1,58 @@
 # Harbor CLI
 
-A CLI tool for those small side projects that only run a few services. Harbor allows you to:
+A CLI tool for managing local development services with ease. Harbor helps you orchestrate multiple development services in tmux sessions, perfect for microservices and polyglot projects.
 
-1. 🛠️ Define your services in a configuration file
-2. 🚀 Launch your services in a tmux session
+## ✨ Features
+
+- 🛠️ **Automatic Service Discovery**: Detects project types and suggests appropriate commands
+- 📁 **Flexible Configuration**: Store config in `harbor.json` or `package.json`
+- 🚀 **One-Command Launch**: Start all services with a single command
+- 🔄 **Dependency Management**: Automatically checks for required system dependencies
+- 🎯 **Multi-Language Support**: Works with Node.js, Go, Rust, Python, PHP, Java, and more
+- 🖥️ **Tmux Integration**: Professional terminal multiplexing for service management
 
 ## Installation
 
 ```bash
-npm i -g @abyrd9/harbor-cli
+npm install -g @abyrd9/harbor-cli
 ```
 
 ## Prerequisites
 
-Before using Harbor, make sure you have the following installed:
+Harbor automatically checks for these required dependencies:
+
+- **[tmux](https://github.com/tmux/tmux/wiki/Installing)** - Terminal multiplexer for managing services
+- **[jq](https://stedolan.github.io/jq/download/)** - JSON processor for service management
 
-- [tmux](https://github.com/tmux/tmux/wiki/Installing) (for terminal multiplexing)
-- [jq](https://stedolan.github.io/jq/download/) (for JSON processing within tmux)
+If missing, Harbor will provide installation instructions.
 
 ## Quick Start
 
-1. Initialize your development environment:
-```bash
-harbor dock
-```
+1. **Initialize your project**:
+   ```bash
+   harbor dock
+   ```
+   This scans your directory structure and creates a harbor configuration.
 
-2. Add new services to your configuration:
-```bash
-harbor moor
-```
+2. **Add more services** (optional):
+   ```bash
+   harbor moor
+   ```
+   Scans for new services and adds them to your configuration.
 
-3. Launch your services:
-```bash
-harbor launch
-```
+3. **Launch all services**:
+   ```bash
+   harbor launch
+   ```
+   Starts all configured services in organized tmux windows.
 
 ## Configuration
 
-Harbor uses a configuration file to manage your services:
+Harbor supports two configuration formats:
 
-### harbor.json
+### Option 1: harbor.json
 
-Contains your service configurations that are used to launch the services:
+Create a dedicated configuration file:
 
 ```json
 {
@@ -57,34 +68,234 @@ Contains your service configurations that are used to launch the services:
       "command": "go run ."
     },
     {
-      "name": "dashboard",
-      "path": "./vite-frontend",
-      "command": "npx drizzle-kit studio"
+      "name": "database",
+      "path": "./db",
+      "command": "docker-compose up"
+    }
+  ],
+  "before": [
+    {
+      "path": "./",
+      "command": "echo 'Starting development environment...' && docker-compose up -d"
+    },
+    {
+      "path": "./scripts",
+      "command": "./setup-dev.sh"
+    }
+  ],
+  "after": [
+    {
+      "path": "./",
+      "command": "echo 'Development environment ready!'"
     }
   ]
 }
 ```
 
+### Option 2: package.json
+
+Store configuration directly in your `package.json`:
+
+```json
+{
+  "name": "my-project",
+  "version": "1.0.0",
+  "harbor": {
+    "services": [
+      {
+        "name": "frontend",
+        "path": "./frontend",
+        "command": "npm run dev"
+      },
+      {
+        "name": "api",
+        "path": "./api",
+        "command": "go run main.go"
+      }
+    ],
+    "before": [
+      {
+        "path": "./",
+        "command": "docker-compose up -d database"
+      }
+    ],
+    "after": [
+      {
+        "path": "./",
+        "command": "echo 'All services are running!'"
+      }
+    ]
+  }
+}
+```
+
 ## Commands
 
-- `harbor dock`: Generate a new harbor.json file
-- `harbor moor`: Add new services to your harbor.json file
-- `harbor launch`: Start all services defined in your harbor.json file in a tmux session
+| Command | Description |
+|---------|-------------|
+| `harbor dock` | Initialize harbor configuration by scanning project directories |
+| `harbor moor` | Scan for and add new services to existing configuration |
+| `harbor launch` | Start all services in tmux sessions |
+| `harbor --help` | Show help and available commands |
+| `harbor --version` | Show version information |
+
+### Command Options
+
+- `-p, --path <path>`: Specify project root path (defaults to `./`)
+
+## Supported Project Types
+
+Harbor automatically detects and configures services for:
+
+- **Node.js**: `package.json` → `npm run dev`
+- **Go**: `go.mod` → `go run .`
+- **Rust**: `Cargo.toml` → `cargo run`
+- **Python**: `requirements.txt` → `python app.py`
+- **PHP**: `composer.json` → `php artisan serve`
+- **Java**: `pom.xml`/`build.gradle` → `mvn spring-boot:run` or `./gradlew bootRun`
+
+## How It Works
+
+1. **Service Discovery**: Harbor scans your directory for folders containing project files
+2. **Command Detection**: Based on project type, suggests appropriate development commands
+3. **Configuration Generation**: Creates/updates harbor config with discovered services
+4. **Tmux Session**: Launches each service in its own tmux window with proper working directories
+5. **Process Management**: All services run independently with proper I/O handling
 
-## Terminal Multiplexer
+## Terminal Multiplexer (Tmux)
 
-Harbor uses tmux for managing your services. Some useful shortcuts:
+Harbor uses tmux for professional service management. Essential shortcuts:
 
-- `Ctrl+a d`: Detach from session
-- `Ctrl+a c`: Create new window
-- `Ctrl+a n`: Next window
-- `Ctrl+a p`: Previous window
-- `Ctrl+q`: Quit session
+### Session Management
+- `Ctrl+a d` - Detach from session (services continue running)
+- `Ctrl+a :attach` - Reattach to session
+- `Ctrl+a &` - Kill current window
+- `Ctrl+a ?` - Show all keybindings
+
+### Window Navigation
+- `Ctrl+a c` - Create new window
+- `Ctrl+a n` - Next window
+- `Ctrl+a p` - Previous window
+- `Ctrl+a 0-9` - Jump to window number
+- `Ctrl+a w` - List all windows
+
+### Pane Management
+- `Ctrl+a %` - Split window vertically
+- `Ctrl+a "` - Split window horizontally
+- `Ctrl+a →/←/↑/↓` - Navigate between panes
+- `Ctrl+a x` - Close current pane
+
+## Advanced Usage
+
+### Custom Commands
+Override auto-detected commands by editing your configuration:
+
+```json
+{
+  "services": [
+    {
+      "name": "custom-service",
+      "path": "./my-service",
+      "command": "custom-command --with-flags"
+    }
+  ]
+}
+```
+
+### Before/After Scripts
+Run custom scripts before and after your services start:
+
+```json
+{
+  "before": [
+    {
+      "path": "./infrastructure",
+      "command": "docker-compose up -d"
+    },
+    {
+      "path": "./",
+      "command": "npm run setup:dev"
+    }
+  ],
+  "after": [
+    {
+      "path": "./",
+      "command": "npm run seed:database"
+    },
+    {
+      "path": "./scripts",
+      "command": "./notify-dev-ready.sh"
+    }
+  ]
+}
+```
+
+**Execution Flow:**
+1. **Before scripts** run sequentially before services start
+2. Services launch in tmux windows
+3. **After scripts** run sequentially after services are ready
+
+**Use Cases:**
+- Set up databases or infrastructure
+- Run database migrations or seeds
+- Send notifications when environment is ready
+- Clean up temporary files
+- Run integration tests
+
+### Selective Launch
+Currently launches all services. Future versions may support selective service launching.
+
+### Environment Variables
+Services inherit your shell environment. Use `.env` files or export variables before running `harbor launch`.
+
+## Troubleshooting
+
+### Common Issues
+
+1. **"Missing required dependencies"**
+   - Install tmux and jq as indicated in the error message
+
+2. **"No harbor configuration found"**
+   - Run `harbor dock` to initialize configuration
+   - Ensure you're in the correct project directory
+
+3. **Services not starting**
+   - Check that commands are correct in your harbor configuration
+   - Verify project dependencies are installed in each service directory
+   - Check tmux windows for error messages
+
+4. **Tmux not responding**
+   - Try `tmux kill-session -t harbor` to clean up
+   - Restart with `harbor launch`
+
+## Examples
+
+### Monorepo Setup
+```
+my-project/
+├── frontend/     (package.json)
+├── backend/      (go.mod)
+├── database/     (docker-compose.yml)
+└── harbor.json
+```
+
+### Polyglot Microservices
+```
+services/
+├── auth-service/     (Node.js)
+├── user-service/     (Go)
+├── payment-service/  (Python)
+└── notification-service/ (Rust)
+```
 
 ## Contributing
 
-Contributions are welcome! Please feel free to submit a Pull Request.
+Contributions are welcome! Please feel free to:
+
+- Report bugs and request features via GitHub Issues
+- Submit pull requests for improvements
+- Help improve documentation
 
 ## License
 
-MIT
+MIT - See LICENSE file for details

package/dist/index.js

@@ -6,6 +6,7 @@ import { spawn } from 'node:child_process';
 import { chmodSync } from 'node:fs';
 import { readFileSync } from 'node:fs';
 import { fileURLToPath } from 'node:url';
+import os from 'node:os';
 // Read version from package.json
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = path.dirname(__filename);
@@ -24,8 +25,107 @@ const requiredDependencies = [
         requiredFor: 'JSON processing in service management',
     },
 ];
+function detectOS() {
+    const platform = os.platform();
+    const arch = os.arch();
+    const isWindows = platform === 'win32';
+    const isMac = platform === 'darwin';
+    const isLinux = platform === 'linux';
+    // Check if running in WSL
+    let isWSL = false;
+    if (isLinux) {
+        try {
+            const release = fs.readFileSync('/proc/version', 'utf-8');
+            isWSL = release.toLowerCase().includes('microsoft') || release.toLowerCase().includes('wsl');
+        }
+        catch {
+            // If we can't read /proc/version, assume not WSL
+        }
+    }
+    return {
+        platform,
+        arch,
+        isWindows,
+        isMac,
+        isLinux,
+        isWSL,
+    };
+}
+function getInstallInstructions(dependency, osInfo) {
+    const instructions = [];
+    if (dependency === 'tmux') {
+        if (osInfo.isMac) {
+            instructions.push('🍎 macOS:');
+            instructions.push('  • Using Homebrew: brew install tmux');
+            instructions.push('  • Using MacPorts: sudo port install tmux');
+            instructions.push('  • Manual: https://github.com/tmux/tmux/wiki/Installing');
+        }
+        else if (osInfo.isLinux) {
+            if (osInfo.isWSL) {
+                instructions.push('🐧 WSL/Linux:');
+                instructions.push('  • Ubuntu/Debian: sudo apt update && sudo apt install tmux');
+                instructions.push('  • CentOS/RHEL: sudo yum install tmux');
+                instructions.push('  • Fedora: sudo dnf install tmux');
+                instructions.push('  • Arch: sudo pacman -S tmux');
+                instructions.push('  • openSUSE: sudo zypper install tmux');
+            }
+            else {
+                instructions.push('🐧 Linux:');
+                instructions.push('  • Ubuntu/Debian: sudo apt update && sudo apt install tmux');
+                instructions.push('  • CentOS/RHEL: sudo yum install tmux');
+                instructions.push('  • Fedora: sudo dnf install tmux');
+                instructions.push('  • Arch: sudo pacman -S tmux');
+                instructions.push('  • openSUSE: sudo zypper install tmux');
+            }
+        }
+        else if (osInfo.isWindows) {
+            instructions.push('🪟 Windows:');
+            instructions.push('  • Using Chocolatey: choco install tmux');
+            instructions.push('  • Using Scoop: scoop install tmux');
+            instructions.push('  • Using WSL: Install in WSL and use from there');
+            instructions.push('  • Manual: https://github.com/tmux/tmux/wiki/Installing');
+        }
+    }
+    else if (dependency === 'jq') {
+        if (osInfo.isMac) {
+            instructions.push('🍎 macOS:');
+            instructions.push('  • Using Homebrew: brew install jq');
+            instructions.push('  • Using MacPorts: sudo port install jq');
+            instructions.push('  • Using Fink: fink install jq');
+            instructions.push('  • Manual: https://jqlang.org/download/');
+        }
+        else if (osInfo.isLinux) {
+            if (osInfo.isWSL) {
+                instructions.push('🐧 WSL/Linux:');
+                instructions.push('  • Ubuntu/Debian: sudo apt update && sudo apt install jq');
+                instructions.push('  • CentOS/RHEL: sudo yum install jq');
+                instructions.push('  • Fedora: sudo dnf install jq');
+                instructions.push('  • Arch: sudo pacman -S jq');
+                instructions.push('  • openSUSE: sudo zypper install jq');
+            }
+            else {
+                instructions.push('🐧 Linux:');
+                instructions.push('  • Ubuntu/Debian: sudo apt update && sudo apt install jq');
+                instructions.push('  • CentOS/RHEL: sudo yum install jq');
+                instructions.push('  • Fedora: sudo dnf install jq');
+                instructions.push('  • Arch: sudo pacman -S jq');
+                instructions.push('  • openSUSE: sudo zypper install jq');
+            }
+        }
+        else if (osInfo.isWindows) {
+            instructions.push('🪟 Windows:');
+            instructions.push('  • Using winget: winget install jqlang.jq');
+            instructions.push('  • Using Chocolatey: choco install jq');
+            instructions.push('  • Using Scoop: scoop install jq');
+            instructions.push('  • Using WSL: Install in WSL and use from there');
+            instructions.push('  • Manual: https://jqlang.org/download/');
+        }
+    }
+    return instructions;
+}
 async function checkDependencies() {
     const missingDeps = [];
+    const osInfo = detectOS();
     for (const dep of requiredDependencies) {
         try {
             await new Promise((resolve, reject) => {
@@ -44,10 +144,19 @@ async function checkDependencies() {
     }
     if (missingDeps.length > 0) {
         console.log('❌ Missing required dependencies:');
+        console.log(`\n🖥️  Detected OS: ${osInfo.platform} ${osInfo.arch}${osInfo.isWSL ? ' (WSL)' : ''}`);
         for (const dep of missingDeps) {
-            console.log(`\n${dep.name} (required for ${dep.requiredFor})`);
-            console.log(`Install instructions: ${dep.installMsg}`);
+            console.log(`\n📦 ${dep.name} (required for ${dep.requiredFor})`);
+            const instructions = getInstallInstructions(dep.name, osInfo);
+            if (instructions.length > 0) {
+                console.log('   Installation options:');
+                instructions.forEach(instruction => console.log(instruction));
+            }
+            else {
+                console.log(`   General instructions: ${dep.installMsg}`);
+            }
         }
+        console.log('\n💡 After installing the dependencies, run Harbor again.');
         throw new Error('Please install missing dependencies before continuing');
     }
 }
@@ -88,6 +197,7 @@ This is typically the first command you'll run in a new project.`)
     .option('-p, --path <path>', 'The path to the root of your project', './')
     .action(async (options) => {
     try {
+        await checkDependencies();
         const configExists = checkHasHarborConfig();
         if (configExists) {
             console.log('❌ Error: Harbor project already initialized');
@@ -107,20 +217,34 @@ program.command('moor')
     .description('Add new services to your harbor configuration')
     .option('-p, --path <path>', 'The path to the root of your project', './')
     .action(async (options) => {
-    if (!checkHasHarborConfig()) {
-        console.log('❌ No harbor configuration found');
-        console.log('\nTo initialize a new Harbor project, please use:');
-        console.log('  harbor dock');
+    try {
+        await checkDependencies();
+        if (!checkHasHarborConfig()) {
+            console.log('❌ No harbor configuration found');
+            console.log('\nTo initialize a new Harbor project, please use:');
+            console.log('  harbor dock');
+            process.exit(1);
+        }
+        await generateDevFile(options.path);
+    }
+    catch (err) {
+        console.log('❌ Error:', err instanceof Error ? err.message : 'Unknown error');
         process.exit(1);
     }
-    await generateDevFile(options.path);
 });
 program.command('launch')
     .description(`Launch your services in the harbor terminal multiplexer (Using tmux)
 
 Note: This command will stop any active Caddy processes, including those from other Harbor projects.`)
     .action(async () => {
-    await runServices();
+    try {
+        await checkDependencies();
+        await runServices();
+    }
+    catch (err) {
+        console.log('❌ Error:', err instanceof Error ? err.message : 'Unknown error');
+        process.exit(1);
+    }
 });
 program.parse();
 function fileExists(path) {
@@ -148,6 +272,36 @@ function validateConfig(config) {
             return 'Service path is required';
         }
     }
+    // Validate before scripts
+    if (config.before && !Array.isArray(config.before)) {
+        return 'Before scripts must be an array';
+    }
+    if (config.before) {
+        for (let i = 0; i < config.before.length; i++) {
+            const script = config.before[i];
+            if (!script.path) {
+                return `Before script ${i} must have a path`;
+            }
+            if (!script.command) {
+                return `Before script ${i} must have a command`;
+            }
+        }
+    }
+    // Validate after scripts
+    if (config.after && !Array.isArray(config.after)) {
+        return 'After scripts must be an array';
+    }
+    if (config.after) {
+        for (let i = 0; i < config.after.length; i++) {
+            const script = config.after[i];
+            if (!script.path) {
+                return `After script ${i} must have a path`;
+            }
+            if (!script.command) {
+                return `After script ${i} must have a command`;
+            }
+        }
+    }
     return null;
 }
 async function generateDevFile(dirPath) {
@@ -178,6 +332,8 @@ async function generateDevFile(dirPath) {
                     writeToPackageJson = true;
                     config = {
                         services: [],
+                        before: [],
+                        after: [],
                     };
                     console.log('Creating new harbor config in package.json...');
                 }
@@ -185,6 +341,8 @@ async function generateDevFile(dirPath) {
                     // No package.json, create harbor.json
                     config = {
                         services: [],
+                        before: [],
+                        after: [],
                     };
                     console.log('Creating new harbor.json...');
                 }
@@ -296,6 +454,41 @@ async function readHarborConfig() {
     }
     throw new Error('No harbor configuration found in harbor.json or package.json');
 }
+async function execute(scripts, scriptType) {
+    if (!scripts || scripts.length === 0) {
+        return;
+    }
+    console.log(`\n🚀 Executing ${scriptType} scripts...`);
+    for (let i = 0; i < scripts.length; i++) {
+        const script = scripts[i];
+        console.log(`\n📋 Running ${scriptType} script ${i + 1}/${scripts.length}: ${script.command}`);
+        console.log(`   📁 In directory: ${script.path}`);
+        try {
+            await new Promise((resolve, reject) => {
+                const process = spawn('sh', ['-c', `cd "${script.path}" && ${script.command}`], {
+                    stdio: 'inherit',
+                });
+                process.on('close', (code) => {
+                    if (code === 0) {
+                        console.log(`✅ ${scriptType} script ${i + 1} completed successfully`);
+                        resolve(null);
+                    }
+                    else {
+                        reject(new Error(`${scriptType} script ${i + 1} exited with code ${code}`));
+                    }
+                });
+                process.on('error', (err) => {
+                    reject(new Error(`${scriptType} script ${i + 1} failed: ${err.message}`));
+                });
+            });
+        }
+        catch (err) {
+            console.error(`❌ Error executing ${scriptType} script ${i + 1}:`, err instanceof Error ? err.message : 'Unknown error');
+            throw err;
+        }
+    }
+    console.log(`\n✅ All ${scriptType} scripts completed successfully`);
+}
 async function runServices() {
     const hasHarborConfig = checkHasHarborConfig();
     if (!hasHarborConfig) {
@@ -318,6 +511,14 @@ async function runServices() {
         console.error('Error reading config:', err);
         process.exit(1);
     }
+    // Execute before scripts
+    try {
+        await execute(config.before || [], 'before');
+    }
+    catch (err) {
+        console.error('❌ Before scripts failed, aborting launch');
+        process.exit(1);
+    }
     // Ensure scripts exist and are executable
     await ensureScriptsExist();
     // Execute the script directly using spawn to handle I/O streams
@@ -330,12 +531,20 @@ async function runServices() {
             console.error(`Error running dev.sh: ${err}`);
             process.exit(1);
         });
-        command.on('close', (code) => {
+        command.on('close', async (code) => {
             if (code !== 0) {
                 console.error(`dev.sh exited with code ${code}`);
                 process.exit(1);
             }
-            resolve();
+            // Execute after scripts
+            try {
+                await execute(config.after || [], 'after');
+                resolve();
+            }
+            catch (err) {
+                console.error('❌ After scripts failed');
+                process.exit(1);
+            }
         });
     });
 }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@abyrd9/harbor-cli",
-  "version": "1.0.1",
-  "description": "A CLI tool for managing simple local development services with tmux sessions",
+  "version": "1.1.1",
+  "description": "A CLI tool for orchestrating local development services in tmux sessions. Perfect for microservices and polyglot projects with automatic service discovery and before/after script support.",
   "type": "module",
   "bin": {
     "harbor": "dist/index.js"