@abyrd9/harbor-cli 1.0.0 → 1.1.0

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

@@ -148,6 +148,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 +208,8 @@ async function generateDevFile(dirPath) {
                     writeToPackageJson = true;
                     config = {
                         services: [],
+                        before: [],
+                        after: [],
                     };
                     console.log('Creating new harbor config in package.json...');
                 }
@@ -185,6 +217,8 @@ async function generateDevFile(dirPath) {
                     // No package.json, create harbor.json
                     config = {
                         services: [],
+                        before: [],
+                        after: [],
                     };
                     console.log('Creating new harbor.json...');
                 }
@@ -296,6 +330,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 +387,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 +407,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,6 +1,6 @@
 {
   "name": "@abyrd9/harbor-cli",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "description": "A CLI tool for managing simple local development services with tmux sessions",
   "type": "module",
   "bin": {
@@ -38,12 +38,12 @@
     "node": ">=18.0.0"
   },
   "dependencies": {
-    "@commander-js/extra-typings": "^13.1.0"
+    "@commander-js/extra-typings": "^14.0.0"
   },
   "devDependencies": {
-    "@types/node": "^22.13.1",
+    "@types/node": "^24.0.3",
     "bun-types": "latest",
-    "typescript": "^5.7.3"
+    "typescript": "^5.8.3"
   },
   "main": "index.js",
   "harbor": {