@abyrd9/harbor-cli 1.1.0 → 2.0.0

package/README.md

@@ -10,9 +10,14 @@ 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
 
 ## Installation
 
+```bash
+bun add -g @abyrd9/harbor-cli
+```
+
 ```bash
 npm install -g @abyrd9/harbor-cli
 ```
@@ -60,12 +65,15 @@ Create a dedicated configuration file:
     {
       "name": "frontend",
       "path": "./vite-frontend",
-      "command": "npm run dev"
+      "command": "npm run dev",
+      "log": true
     },
     {
       "name": "api",
       "path": "./go-api",
-      "command": "go run ."
+      "command": "go run .",
+      "log": true,
+      "maxLogLines": 500
     },
     {
       "name": "database",
@@ -202,6 +210,42 @@ Override auto-detected commands by editing your configuration:
 }
 ```
 
+### Service Logging for AI Agents
+
+Enable logging to stream service output to files in `.harbor/`. This is particularly useful when working with AI coding assistants (like Opencode, Codex, or Claude) that can read log files to understand what's happening in your services.
+
+```json
+{
+  "services": [
+    {
+      "name": "api",
+      "path": "./api",
+      "command": "go run .",
+      "log": true,
+      "maxLogLines": 500
+    },
+    {
+      "name": "frontend",
+      "path": "./frontend", 
+      "command": "npm run dev",
+      "log": true
+    }
+  ]
+}
+```
+
+**Options:**
+- `log`: `true` to enable logging (default: `false`)
+- `maxLogLines`: Maximum lines to keep in log file (default: `1000`)
+
+**Log files are:**
+- Stored in `.harbor/` directory (automatically added to `.gitignore`)
+- Named `{session}-{service}.log` (e.g., `local-dev-test-api.log`)
+- Automatically trimmed to prevent unbounded growth
+- Stripped of ANSI escape codes for clean, readable output
+
+**Use case:** Point your AI assistant to the `.harbor/` folder so it can monitor service logs, spot errors, and understand runtime behavior while helping you develop.
+
 ### Before/After Scripts
 Run custom scripts before and after your services start:
 

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) {
@@ -387,6 +511,7 @@ async function runServices() {
         console.error('Error reading config:', err);
         process.exit(1);
     }
+    ensureLogSetup(config);
     // Execute before scripts
     try {
         await execute(config.before || [], 'before');
@@ -424,6 +549,27 @@ async function runServices() {
         });
     });
 }
+function ensureLogSetup(config) {
+    const shouldLog = config.services.some((service) => service.log);
+    if (!shouldLog) {
+        return;
+    }
+    const harborDir = path.join(process.cwd(), '.harbor');
+    if (!fs.existsSync(harborDir)) {
+        fs.mkdirSync(harborDir, { recursive: true });
+    }
+    const gitignorePath = path.join(process.cwd(), '.gitignore');
+    if (!fs.existsSync(gitignorePath)) {
+        return;
+    }
+    const gitignore = fs.readFileSync(gitignorePath, 'utf-8');
+    if (gitignore.includes('.harbor')) {
+        return;
+    }
+    const needsNewline = gitignore.length > 0 && !gitignore.endsWith('\n');
+    const entry = `${needsNewline ? '\n' : ''}.harbor/\n`;
+    fs.appendFileSync(gitignorePath, entry, 'utf-8');
+}
 // Get the package root directory
 function getPackageRoot() {
     const __filename = fileURLToPath(import.meta.url);

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@abyrd9/harbor-cli",
-  "version": "1.1.0",
-  "description": "A CLI tool for managing simple local development services with tmux sessions",
+  "version": "2.0.0",
+  "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"
@@ -12,7 +12,7 @@
   ],
   "scripts": {
     "check": "bunx npm-check -u",
-    "build": "tsc",
+    "build": "bunx tsc",
     "prepare": "bun run build",
     "start": "bun dist/index.js",
     "harbor": "bun dist/index.js",
@@ -49,14 +49,18 @@
   "harbor": {
     "services": [
       {
-        "name": "vite-project",
-        "path": "test-services/vite-project",
-        "command": "npm run dev"
+        "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 ."
+        "command": "go run .",
+        "log": true,
+        "maxLogLines": 500
       }
     ]
   }

package/scripts/dev.sh

@@ -6,6 +6,26 @@ if tmux has-session -t local-dev-test 2>/dev/null; then
     tmux kill-session -t local-dev-test
 fi
 
+session_name="local-dev-test"
+repo_root="$(pwd)"
+max_log_lines=1000
+log_pids=()
+
+cleanup_logs() {
+    for pid in "${log_pids[@]}"; do
+        kill "$pid" 2>/dev/null
+    done
+}
+
+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
+}
+
+trap cleanup_logs EXIT
+
 # Function to get harbor config
 get_harbor_config() {
     if [ -f "harbor.json" ]; then
@@ -18,7 +38,7 @@ get_harbor_config() {
 }
 
 # Start a new tmux session named 'local-dev-test' and rename the initial window
-tmux new-session -d -s local-dev-test
+tmux new-session -d -s "$session_name"
 
 # Set tmux options
 tmux set-option -g prefix C-a
@@ -77,31 +97,51 @@ tmux set-option -g 'status-format[0]' ''
 
 # Create a new window for the interactive shell
 echo "Creating window for interactive shell"
-tmux rename-window -t local-dev-test:0 'Terminal'
+tmux rename-window -t "$session_name":0 'Terminal'
 
 window_index=1  # Start from index 1
 
+if get_harbor_config | jq -e '.services[] | select(.log == true)' >/dev/null 2>&1; then
+    mkdir -p "$repo_root/.harbor"
+    rm -f "$repo_root/.harbor/${session_name}-"*.log
+fi
+
 # Create windows dynamically based on harbor config
-get_harbor_config | jq -c '.services[]' | while read service; do
+while read service; do
     name=$(echo $service | jq -r '.name')
     path=$(echo $service | jq -r '.path')
     command=$(echo $service | jq -r '.command')
+    log=$(echo $service | jq -r '.log // false')
+    service_max_lines=$(echo $service | jq -r '.maxLogLines // empty')
+    
+    # Use service-specific maxLogLines or fall back to default
+    effective_max_lines="${service_max_lines:-$max_log_lines}"
     
     echo "Creating window for service: $name"
     echo "Path: $path"
     echo "Command: $command"
     
-    tmux new-window -t local-dev-test:$window_index -n "$name"
-    tmux send-keys -t local-dev-test:$window_index "cd $path && $command" C-m
+    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"
+        # Start background process to trim logs if they get too large
+        start_log_trim "$log_file" "$effective_max_lines"
+    else
+        tmux new-window -t "$session_name":$window_index -n "$name"
+        tmux send-keys -t "$session_name":$window_index "cd \"$path\" && $command" C-m
+    fi
     
     ((window_index++))
-done
+done < <(get_harbor_config | jq -c '.services[]')
 
 # Bind 'Home' key to switch to the terminal window
 tmux bind-key -n Home select-window -t :0
 
 # Select the terminal window
-tmux select-window -t local-dev-test:0
+tmux select-window -t "$session_name":0
 
 # Attach to the tmux session
-tmux attach-session -t local-dev-test
+tmux attach-session -t "$session_name"