@abyrd9/harbor-cli 2.3.4 → 2.4.1

package/README.md

@@ -12,6 +12,7 @@ A CLI tool for managing local development services with ease. Harbor helps you o
 - 🖥️ **Tmux Integration**: Professional terminal multiplexing for service management
 - 📝 **Service Logging**: Stream service output to log files for monitoring and debugging
 - 🏷️ **Custom Session Names**: Configure unique tmux session names
+- 🤖 **AI Agent Integration**: Inter-pane communication lets AI agents observe and interact with services
 
 ## Installation
 
@@ -158,10 +159,23 @@ Store configuration directly in your `package.json`:
 |---------|-------------|
 | `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 launch` | Start all services in a tmux session (`-d` for headless) |
+| `harbor anchor` | Attach to a running Harbor session |
+| `harbor scuttle` | Stop all services and kill the session |
+| `harbor bearings` | Show status of running services |
 | `harbor --help` | Show comprehensive help with feature descriptions |
 | `harbor --version` | Show version information |
 
+### Inter-Pane Communication
+
+| Command | Description |
+|---------|-------------|
+| `harbor hail <service> "<cmd>"` | Send keystrokes to another service pane |
+| `harbor survey <service>` | Capture output from a service pane |
+| `harbor parley <service> "<cmd>"` | Execute command and capture response |
+| `harbor whoami` | Show current pane identity and access |
+| `harbor context` | Output full session context for AI agents |
+
 ### Command Options
 
 - `-p, --path <path>`: Specify project root path (defaults to `./`)
@@ -254,13 +268,95 @@ Enable logging to stream service output to files in `.harbor/`. This is particul
 - `maxLogLines`: Maximum lines to keep in log file (default: `1000`)
 
 **Log files are:**
-- Stored in `.harbor/` directory (automatically added to `.gitignore`)
+- Stored in `.harbor/` directory (add to `.gitignore` manually)
 - 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.
 
+### Inter-Pane Communication for AI Agents
+
+Harbor enables AI agents running in one pane to observe and interact with other services. This is powerful for AI-assisted development workflows where an agent needs to monitor logs, send commands to REPLs, or coordinate between services.
+
+#### Configuration
+
+Add `canAccess` to specify which services a pane can communicate with:
+
+```json
+{
+  "services": [
+    {
+      "name": "repl",
+      "path": "./backend",
+      "command": "bin/mycli"
+    },
+    {
+      "name": "agent",
+      "path": ".",
+      "command": "opencode",
+      "canAccess": ["repl", "web"]
+    },
+    {
+      "name": "web",
+      "path": "./frontend",
+      "command": "npm run dev"
+    }
+  ]
+}
+```
+
+#### Commands
+
+**Survey** - Capture output from another pane:
+```bash
+harbor survey repl --lines 50
+```
+
+**Hail** - Send keystrokes to another pane (fire-and-forget):
+```bash
+harbor hail repl "user query --email test@example.com"
+```
+
+**Parley** - Execute command and capture response (uses markers for clean output):
+```bash
+harbor parley repl "users" --timeout 5000
+```
+
+**Whoami** - Check current pane identity and access:
+```bash
+harbor whoami
+```
+
+**Context** - Get full session documentation (markdown, great for AI context):
+```bash
+harbor context
+```
+
+#### Access Control
+
+- Services can only access panes listed in their `canAccess` array
+- Commands run from outside tmux (external terminal) bypass access control
+- Access is enforced based on the `HARBOR_SERVICE` environment variable
+
+#### Environment Variables
+
+Each pane automatically receives these environment variables:
+- `HARBOR_SESSION` - Session name
+- `HARBOR_SOCKET` - Tmux socket name
+- `HARBOR_SERVICE` - Current service name
+- `HARBOR_WINDOW` - Window number
+
+#### Use Case: AI Agent Integration
+
+Add to your agent's instructions:
+
+```markdown
+When starting, run `harbor whoami` to check your harbor context.
+Use `harbor survey <service>` to observe other panes.
+Use `harbor parley <service> "<cmd>"` to interact with REPLs/CLIs.
+```
+
 ### Before/After Scripts
 Run custom scripts before and after your services start:
 

package/dist/index.js

@@ -2,13 +2,16 @@
 import { Command } from '@commander-js/extra-typings';
 import fs from 'node:fs';
 import path from 'node:path';
-import { spawn } from 'node:child_process';
+import { spawn, exec } from 'node:child_process';
 import { chmodSync } from 'node:fs';
 import { readFileSync } from 'node:fs';
 import { fileURLToPath } from 'node:url';
+import { promisify } from 'node:util';
+import { randomUUID } from 'node:crypto';
 import os from 'node:os';
 import readline from 'node:readline';
 import pc from 'picocolors';
+const execAsync = promisify(exec);
 // Colored output helpers
 const log = {
     error: (msg) => console.log(`${pc.red('✗')} ${msg}`),
@@ -175,6 +178,123 @@ async function checkDependencies() {
         throw new Error('Please install missing dependencies before continuing');
     }
 }
+// ─────────────────────────────────────────────────────────────
+// Inter-Pane Communication Functions
+// ─────────────────────────────────────────────────────────────
+const sleep = (ms) => new Promise(r => setTimeout(r, ms));
+function getSessionInfo() {
+    const sessionFile = path.join(process.cwd(), '.harbor', 'session.json');
+    if (!fs.existsSync(sessionFile))
+        return null;
+    try {
+        return JSON.parse(fs.readFileSync(sessionFile, 'utf-8'));
+    }
+    catch {
+        return null;
+    }
+}
+function checkAccess(target) {
+    const session = getSessionInfo();
+    if (!session) {
+        return { allowed: false, error: 'No harbor session running. Run "harbor launch" first.' };
+    }
+    const targetService = session.services[target];
+    if (!targetService) {
+        const available = Object.keys(session.services).join(', ');
+        return { allowed: false, error: `Unknown service: ${target}. Available services: ${available}` };
+    }
+    // If called from outside a harbor pane (no HARBOR_SERVICE env), allow access
+    const callerService = process.env.HARBOR_SERVICE;
+    if (!callerService) {
+        return { allowed: true };
+    }
+    // If called from within a harbor pane, check canAccess
+    const callerInfo = session.services[callerService];
+    if (!callerInfo) {
+        return { allowed: true }; // Caller not in session, allow
+    }
+    const canAccess = callerInfo.canAccess || [];
+    if (!canAccess.includes(target)) {
+        return {
+            allowed: false,
+            error: `Service "${callerService}" does not have access to "${target}". Add "${target}" to canAccess in your harbor config.`
+        };
+    }
+    return { allowed: true };
+}
+async function sendToPane(target, command) {
+    const session = getSessionInfo();
+    if (!session)
+        throw new Error('No harbor session running');
+    const service = session.services[target];
+    if (!service)
+        throw new Error(`Unknown service: ${target}`);
+    const tmuxCmd = `tmux -L ${session.socket}`;
+    const escaped = command.replace(/"/g, '\\"');
+    await execAsync(`${tmuxCmd} send-keys -t "${service.target}" "${escaped}" Enter`);
+}
+async function capturePane(target, lines = 500) {
+    const session = getSessionInfo();
+    if (!session)
+        throw new Error('No harbor session running');
+    const service = session.services[target];
+    if (!service)
+        throw new Error(`Unknown service: ${target}`);
+    const tmuxCmd = `tmux -L ${session.socket}`;
+    const { stdout } = await execAsync(`${tmuxCmd} capture-pane -t "${service.target}" -p -S -${lines}`);
+    return stdout;
+}
+async function execInPane(target, command, timeout = 3000) {
+    const session = getSessionInfo();
+    if (!session)
+        throw new Error('No harbor session running');
+    const service = session.services[target];
+    if (!service)
+        throw new Error(`Unknown service: ${target}`);
+    const tmuxCmd = `tmux -L ${session.socket}`;
+    const markerId = randomUUID().slice(0, 8);
+    const startMarker = `<<<HARBOR_START_${markerId}>>>`;
+    const endMarker = `<<<HARBOR_END_${markerId}>>>`;
+    // Send start marker
+    await execAsync(`${tmuxCmd} send-keys -t "${service.target}" "echo '${startMarker}'" Enter`);
+    await sleep(100);
+    // Send command
+    const escaped = command.replace(/'/g, "'\\''");
+    await execAsync(`${tmuxCmd} send-keys -t "${service.target}" '${escaped}' Enter`);
+    await sleep(timeout);
+    // Send end marker
+    await execAsync(`${tmuxCmd} send-keys -t "${service.target}" "echo '${endMarker}'" Enter`);
+    await sleep(200);
+    // Capture and extract
+    const { stdout } = await execAsync(`${tmuxCmd} capture-pane -t "${service.target}" -p -S -500`);
+    // Extract content between markers
+    const regex = new RegExp(`${escapeRegex(startMarker)}\\n([\\s\\S]*?)${escapeRegex(endMarker)}`);
+    const match = stdout.match(regex);
+    if (match) {
+        // Clean up the output
+        const rawOutput = match[1];
+        const lines = rawOutput.split('\n');
+        // Filter out the echoed command and prompts
+        const cleanedLines = lines.filter(line => {
+            const trimmed = line.trim();
+            if (!trimmed)
+                return false;
+            if (trimmed.includes(`echo '${startMarker}'`))
+                return false;
+            if (trimmed.includes(`echo '${endMarker}'`))
+                return false;
+            return true;
+        });
+        return cleanedLines.join('\n').trim() || '(no output)';
+    }
+    return stdout.trim() || '(no output)';
+}
+function escapeRegex(str) {
+    return str.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+// ─────────────────────────────────────────────────────────────
+// Configuration Prompts
+// ─────────────────────────────────────────────────────────────
 function promptConfigLocation() {
     const rl = readline.createInterface({
         input: process.stdin,
@@ -237,6 +357,15 @@ ${yellow('Commands:')}
   ${green('scuttle')}    Stop all services
   ${green('bearings')}   Show status of running services
 
+${yellow('Inter-Pane Communication:')}
+  ${green('hail')}       Send a command to another service pane
+  ${green('survey')}     Capture output from a service pane
+  ${green('parley')}     Execute command and capture response
+
+${yellow('Agent Awareness:')}
+  ${green('whoami')}     Show current pane identity and access
+  ${green('context')}    Output full session context (markdown)
+
 ${yellow('Quick Start:')}
   ${dim('$')} harbor dock            ${dim('# Create config')}
   ${dim('$')} harbor launch          ${dim('# Start services')}
@@ -435,6 +564,12 @@ program.command('scuttle')
         killSession.on('close', async (code) => {
             if (code === 0) {
                 log.success(`Harbor session ${pc.cyan(sessionName)} stopped`);
+                // Clean up session.json
+                const sessionFile = path.join(process.cwd(), '.harbor', 'session.json');
+                if (fs.existsSync(sessionFile)) {
+                    fs.unlinkSync(sessionFile);
+                    log.dim('   Cleaned up session metadata');
+                }
                 // Execute after scripts when session is killed
                 if (config.after && config.after.length > 0) {
                     try {
@@ -538,6 +673,196 @@ program.command('bearings')
         process.exit(1);
     }
 });
+// ─────────────────────────────────────────────────────────────
+// Inter-Pane Communication Commands
+// ─────────────────────────────────────────────────────────────
+program.command('hail')
+    .description('Send a command to another service pane')
+    .argument('<service>', 'Target service name')
+    .argument('<command>', 'Command to send')
+    .action(async (service, command) => {
+    try {
+        const access = checkAccess(service);
+        if (!access.allowed) {
+            log.error(access.error || 'Access denied');
+            process.exit(1);
+        }
+        await sendToPane(service, command);
+        log.success(`Hailed ${pc.cyan(service)}: ${pc.dim(command)}`);
+    }
+    catch (err) {
+        log.error(err instanceof Error ? err.message : 'Failed to hail service');
+        process.exit(1);
+    }
+});
+program.command('survey')
+    .description('Capture output from a service pane')
+    .argument('<service>', 'Target service name')
+    .option('-n, --lines <number>', 'Number of lines to capture', '500')
+    .action(async (service, options) => {
+    try {
+        const access = checkAccess(service);
+        if (!access.allowed) {
+            log.error(access.error || 'Access denied');
+            process.exit(1);
+        }
+        const output = await capturePane(service, parseInt(options.lines));
+        console.log(output);
+    }
+    catch (err) {
+        log.error(err instanceof Error ? err.message : 'Failed to survey service');
+        process.exit(1);
+    }
+});
+program.command('parley')
+    .description('Execute a command in a pane and capture the response')
+    .argument('<service>', 'Target service name')
+    .argument('<command>', 'Command to execute')
+    .option('-t, --timeout <ms>', 'Timeout in milliseconds', '3000')
+    .action(async (service, command, options) => {
+    try {
+        const access = checkAccess(service);
+        if (!access.allowed) {
+            log.error(access.error || 'Access denied');
+            process.exit(1);
+        }
+        const output = await execInPane(service, command, parseInt(options.timeout));
+        console.log(output);
+    }
+    catch (err) {
+        log.error(err instanceof Error ? err.message : 'Failed to parley with service');
+        process.exit(1);
+    }
+});
+program.command('whoami')
+    .description('Show current pane identity and session info')
+    .action(async () => {
+    const session = getSessionInfo();
+    const currentService = process.env.HARBOR_SERVICE;
+    if (!session) {
+        log.warn('Not in a harbor session');
+        log.dim('   No .harbor/session.json found');
+        process.exit(0);
+    }
+    const currentServiceInfo = currentService ? session.services[currentService] : null;
+    const canAccessList = currentServiceInfo?.canAccess || [];
+    log.header(`${pc.cyan('⚓')} Harbor Identity`);
+    log.plain('');
+    log.label('Session:', session.session);
+    log.label('Socket:', session.socket);
+    if (currentService && currentServiceInfo) {
+        log.label('You are:', `${pc.green(currentService)} (window ${currentServiceInfo.window})`);
+        if (canAccessList.length > 0) {
+            log.label('Can access:', canAccessList.map(s => pc.cyan(s)).join(', '));
+        }
+        else {
+            log.label('Can access:', pc.dim('(none configured)'));
+        }
+    }
+    else {
+        log.label('You are:', pc.dim('external (not in a harbor pane)'));
+        log.label('Can access:', pc.green('all services'));
+    }
+    log.plain('');
+    log.dim('   Run "harbor context" for full documentation');
+    log.dim('   Run "harbor bearings" to see all services');
+});
+program.command('context')
+    .description('Output session context for AI agents (markdown format)')
+    .action(async () => {
+    const session = getSessionInfo();
+    const currentService = process.env.HARBOR_SERVICE;
+    if (!session) {
+        console.log(`# Harbor Session
+
+No active harbor session found. Run \`harbor launch\` to start one.
+`);
+        process.exit(0);
+    }
+    const currentServiceInfo = currentService ? session.services[currentService] : null;
+    const canAccessList = currentServiceInfo?.canAccess || [];
+    let output = `# Harbor Session Context
+
+You are running inside a **harbor** tmux session, which orchestrates multiple development services.
+
+## Current Session
+- **Session**: ${session.session}
+- **Socket**: ${session.socket}
+- **Started**: ${session.startedAt}
+`;
+    if (currentService) {
+        output += `- **Your Pane**: ${currentService} (window ${currentServiceInfo?.window})
+`;
+    }
+    output += `
+## Available Services
+| Service | Window | You Can Access |
+|---------|--------|----------------|
+`;
+    for (const [name, info] of Object.entries(session.services)) {
+        const isCurrent = name === currentService;
+        const hasAccess = !currentService || canAccessList.includes(name) || name === currentService;
+        const accessIcon = isCurrent ? '(you)' : hasAccess ? '✓' : '✗';
+        output += `| ${name} | ${info.window} | ${accessIcon} |\n`;
+    }
+    output += `
+## Inter-Pane Communication Commands
+
+You can interact with other service panes using these commands:
+
+### \`harbor hail <service> "<command>"\`
+Send keystrokes to another pane (fire-and-forget).
+\`\`\`bash
+harbor hail repl "echo hello"
+\`\`\`
+
+### \`harbor survey <service> [--lines N]\`
+Capture the current output/scrollback from another pane.
+\`\`\`bash
+harbor survey web --lines 50
+\`\`\`
+
+### \`harbor parley <service> "<command>" [--timeout ms]\`
+Execute a command in another pane and capture the response.
+Uses markers to delimit output. Good for REPLs and CLIs.
+\`\`\`bash
+harbor parley repl "users" --timeout 3000
+\`\`\`
+
+## Access Control
+`;
+    if (currentService) {
+        if (canAccessList.length > 0) {
+            output += `Your service (${currentService}) can access: **${canAccessList.join(', ')}**
+
+To access other services, add them to \`canAccess\` in harbor.json and restart the session.
+`;
+        }
+        else {
+            output += `Your service (${currentService}) has no \`canAccess\` configured.
+
+Add services to \`canAccess\` in harbor.json to enable inter-pane communication:
+\`\`\`json
+{
+  "name": "${currentService}",
+  "canAccess": ["repl", "web"]
+}
+\`\`\`
+`;
+        }
+    }
+    else {
+        output += `You are running from outside the harbor session, so you have access to all services.
+`;
+    }
+    output += `
+## Other Useful Commands
+- \`harbor bearings\` - Show session status and running services
+- \`harbor anchor\` - Attach to the tmux session interactively
+- \`harbor scuttle\` - Stop all services
+`;
+    console.log(output);
+});
 program.parse();
 function fileExists(path) {
     return fs.existsSync(`${process.cwd()}/${path}`);
@@ -556,6 +881,7 @@ export function validateConfig(config) {
     if (!Array.isArray(config.services)) {
         return 'Services must be an array';
     }
+    const serviceNames = new Set(config.services.map(s => s.name));
     for (const service of config.services) {
         if (!service.name) {
             return 'Service name is required';
@@ -563,6 +889,17 @@ export function validateConfig(config) {
         if (!service.path) {
             return 'Service path is required';
         }
+        // Validate canAccess references
+        if (service.canAccess) {
+            for (const targetName of service.canAccess) {
+                if (!serviceNames.has(targetName)) {
+                    return `Service "${service.name}" has canAccess reference to unknown service "${targetName}"`;
+                }
+                if (targetName === service.name) {
+                    return `Service "${service.name}" cannot have canAccess reference to itself`;
+                }
+            }
+        }
     }
     // Validate before scripts
     if (config.before && !Array.isArray(config.before)) {
@@ -867,17 +1204,6 @@ function ensureLogSetup(config) {
     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() {

package/harbor.package-json.schema.json

@@ -38,6 +38,11 @@
                 "type": "integer",
                 "description": "Maximum number of lines to keep in the log file",
                 "minimum": 1
+              },
+              "canAccess": {
+                "type": "array",
+                "items": { "type": "string" },
+                "description": "Names of other services this pane can send commands to via hail/survey/parley"
               }
             },
             "additionalProperties": false

package/harbor.schema.json

@@ -38,6 +38,11 @@
             "type": "integer",
             "description": "Maximum number of lines to keep in the log file",
             "minimum": 1
+          },
+          "canAccess": {
+            "type": "array",
+            "items": { "type": "string" },
+            "description": "Names of other services this pane can send commands to via hail/survey/parley"
           }
         },
         "additionalProperties": false

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@abyrd9/harbor-cli",
-  "version": "2.3.4",
+  "version": "2.4.1",
   "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": {

package/scripts/dev.sh

@@ -149,23 +149,75 @@ while read service; do
     echo "Path: $path"
     echo "Command: $command"
     
+    # Build the environment export command for inter-pane communication
+    env_export="export HARBOR_SESSION='$session_name' HARBOR_SOCKET='$socket_name' HARBOR_SERVICE='$name' HARBOR_WINDOW=$window_index"
+    
     if [ "$log" = "true" ]; then
         log_file="$repo_root/.harbor/${session_name}-${name}.log"
         : > "$log_file"
         # Use pipe-pane to capture ALL terminal output (works with any program, no buffering issues)
         $tmux_cmd new-window -t "$session_name":$window_index -n "$name"
         $tmux_cmd pipe-pane -t "$session_name":$window_index "cat >> \"$log_file\""
-        $tmux_cmd send-keys -t "$session_name":$window_index "cd \"$path\" && $command" C-m
+        # Inject environment variables then run command
+        $tmux_cmd send-keys -t "$session_name":$window_index "$env_export && 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
         $tmux_cmd new-window -t "$session_name":$window_index -n "$name"
-        $tmux_cmd send-keys -t "$session_name":$window_index "cd \"$path\" && $command" C-m
+        # Inject environment variables then run command
+        $tmux_cmd send-keys -t "$session_name":$window_index "$env_export && cd \"$path\" && $command" C-m
     fi
     
     ((window_index++))
 done < <(get_harbor_config | jq -c '.services[]')
 
+# Generate session.json for inter-pane communication
+echo "Generating session metadata..."
+mkdir -p "$repo_root/.harbor"
+
+# Build the session JSON
+session_json=$(cat <<EOF
+{
+  "session": "$session_name",
+  "socket": "$socket_name",
+  "startedAt": "$(date -u +%Y-%m-%dT%H:%M:%SZ)",
+  "services": {
+EOF
+)
+
+# Add each service to the JSON
+first_service=true
+svc_window_index=1
+while read service; do
+    name=$(echo $service | jq -r '.name')
+    can_access=$(echo $service | jq -c '.canAccess // []')
+    
+    if [ "$first_service" = true ]; then
+        first_service=false
+    else
+        session_json+=","
+    fi
+    
+    session_json+=$(cat <<EOF
+
+    "$name": {
+      "window": $svc_window_index,
+      "target": "$session_name:$svc_window_index",
+      "canAccess": $can_access
+    }
+EOF
+)
+    
+    ((svc_window_index++))
+done < <(get_harbor_config | jq -c '.services[]')
+
+session_json+="
+  }
+}"
+
+echo "$session_json" > "$repo_root/.harbor/session.json"
+echo "Session metadata written to .harbor/session.json"
+
 # Bind 'Home' key to switch to the terminal window
 $tmux_cmd bind-key -n Home select-window -t :0