@abyrd9/harbor-cli 2.0.1 → 2.1.0

package/README.md

@@ -1,6 +1,6 @@
 # Harbor CLI
 
-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.
+A CLI tool for managing local development services with ease. Harbor helps you orchestrate multiple development services in a tmux session, perfect for microservices and polyglot projects.
 
 ## ✨ Features
 
@@ -10,7 +10,8 @@ A CLI tool for managing local development services with ease. Harbor helps you o
 - 🔄 **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
-- 🤖 **AI Agent Friendly**: Stream service logs to files for AI coding assistants to monitor
+- 📝 **Service Logging**: Stream service output to log files for monitoring and debugging
+- 🏷️ **Custom Session Names**: Configure unique tmux session names
 
 ## Installation
 
@@ -63,22 +64,33 @@ Create a dedicated configuration file:
 {
   "services": [
     {
-      "name": "frontend",
-      "path": "./vite-frontend",
+      "name": "database",
+      "path": "./db",
+      "preStage": {
+        "command": "docker-compose up -d postgres",
+        "wait": 5,
+        "timeout": 60
+      },
       "command": "npm run dev",
-      "log": true
+      "log": true,
+      "maxLogLines": 500
     },
     {
       "name": "api",
       "path": "./go-api",
+      "preStage": {
+        "command": "go mod download",
+        "wait": 2
+      },
       "command": "go run .",
       "log": true,
       "maxLogLines": 500
     },
     {
-      "name": "database",
-      "path": "./db",
-      "command": "docker-compose up"
+      "name": "frontend",
+      "path": "./vite-frontend",
+      "command": "npm run dev",
+      "log": true
     }
   ],
   "before": [
@@ -96,7 +108,8 @@ Create a dedicated configuration file:
       "path": "./",
       "command": "echo 'Development environment ready!'"
     }
-  ]
+  ],
+  "sessionName": "my-project-dev"
 }
 ```
 
@@ -137,14 +150,16 @@ Store configuration directly in your `package.json`:
 }
 ```
 
+
+
 ## Commands
 
 | 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 dock` | Initialize Harbor config by auto-discovering services in your project |
+| `harbor moor` | Scan for and add new services to your existing Harbor configuration |
+| `harbor launch` | Start all services in a tmux session with pre-stage commands |
+| `harbor --help` | Show comprehensive help with feature descriptions |
 | `harbor --version` | Show version information |
 
 ### Command Options

package/dist/index.js

@@ -7,6 +7,7 @@ import { chmodSync } from 'node:fs';
 import { readFileSync } from 'node:fs';
 import { fileURLToPath } from 'node:url';
 import os from 'node:os';
+import readline from 'node:readline';
 // Read version from package.json
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = path.dirname(__filename);
@@ -160,6 +161,35 @@ async function checkDependencies() {
         throw new Error('Please install missing dependencies before continuing');
     }
 }
+function promptConfigLocation() {
+    const rl = readline.createInterface({
+        input: process.stdin,
+        output: process.stdout,
+    });
+    return new Promise((resolve) => {
+        console.log('\nFound package.json. Where would you like to store harbor config?');
+        console.log('  1. package.json (keeps everything in one place)');
+        console.log('  2. harbor.json (separate config file, auto-IntelliSense)\n');
+        const ask = () => {
+            rl.question('Enter choice (1 or 2): ', (answer) => {
+                const choice = answer.trim();
+                if (choice === '1') {
+                    rl.close();
+                    resolve('package.json');
+                }
+                else if (choice === '2') {
+                    rl.close();
+                    resolve('harbor.json');
+                }
+                else {
+                    console.log('Please enter 1 or 2');
+                    ask();
+                }
+            });
+        };
+        ask();
+    });
+}
 const possibleProjectFiles = [
     'package.json', // Node.js projects
     'go.mod', // Go projects
@@ -176,12 +206,19 @@ program
     .description(`A CLI tool for managing your project's local development services
 
 Harbor helps you manage multiple local development services with ease.
-It provides a simple way to configure and run your services in tmux sessions.
+It provides a simple way to configure and run your services in a tmux session.
+
+Features:
+  ✅ Automatic service discovery for Node.js, Go, Rust, Python, PHP, Java
+  ✅ Pre-stage commands for setup before main service starts  
+  ✅ Configurable tmux session names
+  ✅ Service logging with file output for monitoring and debugging
+  ✅ Before/after script execution
 
 Available Commands:
-  dock      Initialize a new Harbor project
-  moor      Add new services to your configuration
-  launch    Start all services in tmux sessions`)
+  dock      Initialize a new Harbor project by scanning directories
+  moor      Add new services to existing Harbor configuration  
+  launch    Start all services in a tmux session with pre-stage commands`)
     .version(packageJson.version)
     .action(async () => await checkDependencies())
     .addHelpCommand(false);
@@ -190,10 +227,7 @@ if (process.argv.length <= 2) {
     program.help();
 }
 program.command('dock')
-    .description(`Prepares your development environment by creating a harbor configuration file
-- harbor.json configuration file (or harbor field in package.json)
-	
-This is typically the first command you'll run in a new project.`)
+    .description('Initialize Harbor config by auto-discovering services in your project')
     .option('-p, --path <path>', 'The path to the root of your project', './')
     .action(async (options) => {
     try {
@@ -214,7 +248,7 @@ This is typically the first command you'll run in a new project.`)
     }
 });
 program.command('moor')
-    .description('Add new services to your harbor configuration')
+    .description('Scan for and add new services to your existing Harbor configuration')
     .option('-p, --path <path>', 'The path to the root of your project', './')
     .action(async (options) => {
     try {
@@ -233,9 +267,7 @@ program.command('moor')
     }
 });
 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.`)
+    .description('Start all services in a tmux session with pre-stage commands')
     .action(async () => {
     try {
         await checkDependencies();
@@ -250,7 +282,7 @@ program.parse();
 function fileExists(path) {
     return fs.existsSync(`${process.cwd()}/${path}`);
 }
-function isProjectDirectory(dirPath) {
+export function isProjectDirectory(dirPath) {
     return possibleProjectFiles.some(file => {
         try {
             return fs.existsSync(path.join(process.cwd(), dirPath, file));
@@ -260,7 +292,7 @@ function isProjectDirectory(dirPath) {
         }
     });
 }
-function validateConfig(config) {
+export function validateConfig(config) {
     if (!Array.isArray(config.services)) {
         return 'Services must be an array';
     }
@@ -323,28 +355,21 @@ async function generateDevFile(dirPath) {
                 const packageData = await fs.promises.readFile('package.json', 'utf-8');
                 const packageJson = JSON.parse(packageData);
                 if (packageJson.harbor) {
+                    // Existing harbor config in package.json, use it
                     config = packageJson.harbor;
                     writeToPackageJson = true;
                     console.log('Found existing harbor config in package.json, scanning for new services...');
                 }
-                else if (fileExists('package.json')) {
-                    // If package.json exists but no harbor config, use it
-                    writeToPackageJson = true;
-                    config = {
-                        services: [],
-                        before: [],
-                        after: [],
-                    };
-                    console.log('Creating new harbor config in package.json...');
-                }
                 else {
-                    // No package.json, create harbor.json
+                    // package.json exists but no harbor config - ask user where to store it
+                    const choice = await promptConfigLocation();
+                    writeToPackageJson = choice === 'package.json';
                     config = {
                         services: [],
                         before: [],
                         after: [],
                     };
-                    console.log('Creating new harbor.json...');
+                    console.log(`Creating new harbor config in ${choice}...`);
                 }
             }
             catch (err) {
@@ -404,10 +429,22 @@ async function generateDevFile(dirPath) {
             packageJson.harbor = config;
             await fs.promises.writeFile('package.json', JSON.stringify(packageJson, null, 2), 'utf-8');
             console.log('\npackage.json updated successfully with harbor configuration');
+            console.log('\n💡 Tip: To enable IntelliSense for the harbor config in package.json,');
+            console.log('   add this to your .vscode/settings.json:');
+            console.log('   {');
+            console.log('     "json.schemas": [{');
+            console.log('       "fileMatch": ["package.json"],');
+            console.log('       "url": "https://raw.githubusercontent.com/Abyrd9/harbor-cli/main/harbor.package-json.schema.json"');
+            console.log('     }]');
+            console.log('   }');
         }
         else {
-            // Write to harbor.json
-            await fs.promises.writeFile('harbor.json', JSON.stringify(config, null, 2), 'utf-8');
+            // Write to harbor.json with $schema for IntelliSense
+            const configWithSchema = {
+                $schema: 'https://raw.githubusercontent.com/Abyrd9/harbor-cli/main/harbor.schema.json',
+                ...config,
+            };
+            await fs.promises.writeFile('harbor.json', JSON.stringify(configWithSchema, null, 2), 'utf-8');
             console.log('\nharbor.json created successfully');
         }
         console.log('\nImportant:');

package/harbor.package-json.schema.json

@@ -0,0 +1,96 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://raw.githubusercontent.com/Abyrd9/harbor-cli/main/harbor.package-json.schema.json",
+  "title": "Harbor Configuration in package.json",
+  "description": "Schema extension for the 'harbor' property in package.json",
+  "type": "object",
+  "properties": {
+    "harbor": {
+      "type": "object",
+      "description": "Harbor CLI configuration for orchestrating local development services",
+      "required": ["services"],
+      "properties": {
+        "services": {
+          "type": "array",
+          "description": "List of development services to run",
+          "items": {
+            "type": "object",
+            "required": ["name", "path"],
+            "properties": {
+              "name": {
+                "type": "string",
+                "description": "Display name for the service (shown in the terminal UI)"
+              },
+              "path": {
+                "type": "string",
+                "description": "Relative path to the service directory from the project root"
+              },
+              "command": {
+                "type": "string",
+                "description": "Command to start the service (e.g., 'bun run dev', 'go run .')"
+              },
+              "log": {
+                "type": "boolean",
+                "description": "Whether to log output to a file in .harbor/logs/",
+                "default": false
+              },
+              "maxLogLines": {
+                "type": "integer",
+                "description": "Maximum number of lines to keep in the log file",
+                "minimum": 1
+              }
+            },
+            "additionalProperties": false
+          }
+        },
+        "sessionName": {
+          "type": "string",
+          "description": "Custom name for tmux session (default: local-dev-test)",
+          "pattern": "^[a-zA-Z0-9_-]+$"
+        },
+        "before": {
+          "type": "array",
+          "description": "Scripts to run before starting services",
+          "items": {
+            "type": "object",
+            "required": ["path", "command"],
+            "properties": {
+              "path": {
+                "type": "string",
+                "description": "Relative path to run the command from"
+              },
+              "command": {
+                "type": "string",
+                "description": "Command to execute"
+              }
+            },
+            "additionalProperties": false
+          }
+        },
+        "after": {
+          "type": "array",
+          "description": "Scripts to run after all services stop",
+          "items": {
+            "type": "object",
+            "required": ["path", "command"],
+            "properties": {
+              "path": {
+                "type": "string",
+                "description": "Relative path to run the command from"
+              },
+              "command": {
+                "type": "string",
+                "description": "Command to execute"
+              }
+            },
+            "additionalProperties": false
+          }
+        }
+      },
+      "additionalProperties": false
+    }
+  }
+}
+
+
+

package/harbor.schema.json

@@ -0,0 +1,92 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://raw.githubusercontent.com/Abyrd9/harbor-cli/main/harbor.schema.json",
+  "title": "Harbor Configuration",
+  "description": "Configuration schema for Harbor CLI - a tool for running multiple development services",
+  "type": "object",
+  "required": ["services"],
+  "properties": {
+    "$schema": {
+      "type": "string",
+      "description": "JSON Schema reference for IDE IntelliSense"
+    },
+    "services": {
+      "type": "array",
+      "description": "List of development services to run",
+      "items": {
+        "type": "object",
+        "required": ["name", "path"],
+        "properties": {
+          "name": {
+            "type": "string",
+            "description": "Display name for the service (shown in the terminal UI)"
+          },
+          "path": {
+            "type": "string",
+            "description": "Relative path to the service directory from the project root"
+          },
+          "command": {
+            "type": "string",
+            "description": "Command to start the service (e.g., 'bun run dev', 'go run .')"
+          },
+          "log": {
+            "type": "boolean",
+            "description": "Whether to log output to a file in .harbor/logs/",
+            "default": false
+          },
+          "maxLogLines": {
+            "type": "integer",
+            "description": "Maximum number of lines to keep in the log file",
+            "minimum": 1
+          }
+        },
+        "additionalProperties": false
+      }
+    },
+    "sessionName": {
+      "type": "string",
+      "description": "Custom name for the tmux session (default: local-dev-test)",
+      "pattern": "^[a-zA-Z0-9_-]+$"
+    },
+    "before": {
+      "type": "array",
+      "description": "Scripts to run before starting services",
+      "items": {
+        "type": "object",
+        "required": ["path", "command"],
+        "properties": {
+          "path": {
+            "type": "string",
+            "description": "Relative path to run the command from"
+          },
+          "command": {
+            "type": "string",
+            "description": "Command to execute"
+          }
+        },
+        "additionalProperties": false
+      }
+    },
+    "after": {
+      "type": "array",
+      "description": "Scripts to run after all services stop",
+      "items": {
+        "type": "object",
+        "required": ["path", "command"],
+        "properties": {
+          "path": {
+            "type": "string",
+            "description": "Relative path to run the command from"
+          },
+          "command": {
+            "type": "string",
+            "description": "Command to execute"
+          }
+        },
+        "additionalProperties": false
+      }
+    }
+  },
+  "additionalProperties": false
+}
+

package/package.json

@@ -1,14 +1,16 @@
 {
   "name": "@abyrd9/harbor-cli",
-  "version": "2.0.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.",
+  "version": "2.1.0",
+  "description": "A CLI tool for orchestrating local development services in a tmux session. Perfect for microservices and polyglot projects with automatic service discovery and before/after script support.",
   "type": "module",
   "bin": {
     "harbor": "dist/index.js"
   },
   "files": [
     "dist",
-    "scripts"
+    "scripts",
+    "harbor.schema.json",
+    "harbor.package-json.schema.json"
   ],
   "scripts": {
     "check": "bunx npm-check -u",
@@ -16,6 +18,8 @@
     "prepare": "bun run build",
     "start": "bun dist/index.js",
     "harbor": "bun dist/index.js",
+    "test": "vitest",
+    "test:watch": "vitest --watch",
     "release": "bash release.sh"
   },
   "keywords": [
@@ -43,25 +47,8 @@
   "devDependencies": {
     "@types/node": "^24.0.3",
     "bun-types": "latest",
-    "typescript": "^5.8.3"
+    "typescript": "^5.8.3",
+    "vitest": "^4.0.16"
   },
-  "main": "index.js",
-  "harbor": {
-    "services": [
-      {
-        "name": "web",
-        "path": "test-services/web",
-        "command": "bun run dev",
-        "log": true,
-        "maxLogLines": 500
-      },
-      {
-        "name": "go-api",
-        "path": "test-services/go-api",
-        "command": "go run .",
-        "log": true,
-        "maxLogLines": 500
-      }
-    ]
-  }
+  "main": "index.js"
 }

package/scripts/dev.sh

@@ -20,8 +20,20 @@ cleanup_logs() {
 start_log_trim() {
     local log_file="$1"
     local max_lines="$2"
-    # Run trimmer inside tmux so it survives script exit
-    tmux send-keys -t "$session_name":0 "( while true; do sleep 5; if [ -f \"$log_file\" ]; then lines=\$(wc -l < \"$log_file\"); if [ \"\$lines\" -gt $max_lines ]; then tail -n $max_lines \"$log_file\" > \"${log_file}.tmp\" && mv \"${log_file}.tmp\" \"$log_file\"; fi; fi; done ) &" C-m
+    # Start background log trimmer process
+    {
+        while true; do
+            sleep 5
+            if [ -f "$log_file" ]; then
+                lines=$(wc -l < "$log_file")
+                if [ "$lines" -gt $max_lines ]; then
+                    tail -n $max_lines "$log_file" > "${log_file}.tmp" && \
+                    cat "${log_file}.tmp" > "$log_file" && \
+                    rm "${log_file}.tmp"
+                fi
+            fi
+        done
+    } &
 }
 
 trap cleanup_logs EXIT
@@ -72,15 +84,15 @@ tmux bind-key -T copy-mode-vi v send-keys -X begin-selection
 tmux bind-key -T copy-mode-vi y send-keys -X copy-selection-and-cancel
 tmux bind-key -T copy-mode-vi MouseDragEnd1Pane send-keys -X copy-pipe-and-cancel "pbcopy"
 
-# Set easier window navigation shortcuts
-tmux bind-key -n Left select-window -t :-
-tmux bind-key -n Right select-window -t :+
+# Set easier window navigation shortcuts (Shift+Left/Right to switch windows)
+tmux bind-key -n S-Left select-window -t :-
+tmux bind-key -n S-Right select-window -t :+
 
 # Configure status bar
 tmux set-option -g status-position top
 tmux set-option -g status-style bg="#1c1917",fg="#a8a29e"
 tmux set-option -g status-left ""
-tmux set-option -g status-right "#[fg=#a8a29e]Close with ctrl+q · #[fg=white]%H:%M#[default]"
+tmux set-option -g status-right "#[fg=#a8a29e]shift+←/→ switch · ctrl+q close · #[fg=white]%H:%M#[default]"
 tmux set-window-option -g window-status-current-format "\
 #[fg=#6366f1, bg=#1c1917] →
 #[fg=#6366f1, bg=#1c1917, bold] #W
@@ -124,9 +136,10 @@ while read service; do
     if [ "$log" = "true" ]; then
         log_file="$repo_root/.harbor/${session_name}-${name}.log"
         : > "$log_file"
-        # Run command directly (not via send-keys) to avoid shell echo
-        # Strip ANSI escape sequences and control chars before writing to log file
-        tmux new-window -t "$session_name":$window_index -n "$name" "cd \"$path\" && $command 2>&1 | sed -u 's/\\x1b\\[[0-9;]*[mGKHJ]//g' | tee -a \"$log_file\"; exec bash"
+        # Use pipe-pane to capture ALL terminal output (works with any program, no buffering issues)
+        tmux new-window -t "$session_name":$window_index -n "$name"
+        tmux pipe-pane -t "$session_name":$window_index "cat >> \"$log_file\""
+        tmux send-keys -t "$session_name":$window_index "cd \"$path\" && $command" C-m
         # Start background process to trim logs if they get too large
         start_log_trim "$log_file" "$effective_max_lines"
     else