@abyrd9/harbor-cli 2.1.1 → 2.3.0

package/dist/index.js

@@ -151,7 +151,7 @@ async function checkDependencies() {
             const instructions = getInstallInstructions(dep.name, osInfo);
             if (instructions.length > 0) {
                 console.log('   Installation options:');
-                instructions.forEach(instruction => console.log(instruction));
+                instructions.forEach(instruction => { console.log(instruction); });
             }
             else {
                 console.log(`   General instructions: ${dep.installMsg}`);
@@ -203,22 +203,35 @@ const possibleProjectFiles = [
 const program = new Command();
 program
     .name('harbor')
-    .description(`A CLI tool for managing your project's local development services
+    .description(`A CLI tool for orchestrating multiple local development services in tmux.
 
-Harbor helps you manage multiple local development services with ease.
-It provides a simple way to configure and run your services in a tmux session.
+WHAT IT DOES:
+  Harbor manages multiple services (APIs, frontends, databases) in a single tmux 
+  session. It auto-discovers projects, starts them together, and provides logging.
 
-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
+REQUIREMENTS:
+  - tmux (terminal multiplexer)
+  - jq (JSON processor)
 
-Available Commands:
-  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`)
+TYPICAL WORKFLOW:
+  1. harbor dock          # First time: scan and create harbor.json config
+  2. harbor launch        # Start all services in interactive tmux session
+     harbor launch -d     # Or start in headless/background mode
+  3. harbor bearings      # Check status of running services
+  4. harbor anchor        # Attach to running session (if headless)
+  5. harbor scuttle       # Stop all services when done
+
+CONFIGURATION:
+  Config is stored in harbor.json or package.json under "harbor" key.
+  Services can specify: name, path, command, log (boolean), maxLogLines.
+
+COMMANDS:
+  dock      Create new harbor.json by scanning for projects (package.json, go.mod, etc.)
+  moor      Add newly discovered services to existing config
+  launch    Start all configured services (use -d/--headless for background mode)
+  bearings  Show status: running services, session info, log file locations
+  anchor    Attach terminal to a running Harbor tmux session
+  scuttle   Stop all services by killing the tmux session`)
     .version(packageJson.version)
     .action(async () => await checkDependencies())
     .addHelpCommand(false);
@@ -227,8 +240,21 @@ if (process.argv.length <= 2) {
     program.help();
 }
 program.command('dock')
-    .description('Initialize Harbor config by auto-discovering services in your project')
-    .option('-p, --path <path>', 'The path to the root of your project', './')
+    .description(`Initialize a new Harbor project by scanning directories for services.
+
+WHEN TO USE: Run this first in a new project that has no harbor.json yet.
+
+WHAT IT DOES:
+  - Scans subdirectories for project files (package.json, go.mod, Cargo.toml, etc.)
+  - Creates harbor.json with discovered services
+  - Auto-detects run commands (npm run dev, go run ., etc.)
+
+PREREQUISITES: No existing harbor.json or harbor config in package.json.
+
+EXAMPLE:
+  harbor dock              # Scan current directory
+  harbor dock -p ./apps    # Scan specific subdirectory`)
+    .option('-p, --path <path>', 'Directory to scan for service projects (scans subdirectories)', './')
     .action(async (options) => {
     try {
         await checkDependencies();
@@ -248,8 +274,21 @@ program.command('dock')
     }
 });
 program.command('moor')
-    .description('Scan for and add new services to your existing Harbor configuration')
-    .option('-p, --path <path>', 'The path to the root of your project', './')
+    .description(`Add newly discovered services to an existing Harbor configuration.
+
+WHEN TO USE: Run when you've added new service directories to your project.
+
+WHAT IT DOES:
+  - Scans for new project directories not already in config
+  - Adds them to existing harbor.json or package.json harbor config
+  - Skips directories already configured
+
+PREREQUISITES: Existing harbor.json or harbor config in package.json (run 'dock' first).
+
+EXAMPLE:
+  harbor moor              # Scan and add new services
+  harbor moor -p ./apps    # Scan specific subdirectory for new services`)
+    .option('-p, --path <path>', 'Directory to scan for new service projects', './')
     .action(async (options) => {
     try {
         await checkDependencies();
@@ -267,11 +306,225 @@ program.command('moor')
     }
 });
 program.command('launch')
-    .description('Start all services in a tmux session with pre-stage commands')
-    .action(async () => {
+    .description(`Start all configured services in a tmux session.
+
+WHEN TO USE: Run to start your development environment.
+
+WHAT IT DOES:
+  - Kills any existing Harbor tmux session
+  - Runs 'before' scripts if configured
+  - Creates tmux session with a window per service
+  - Starts each service with its configured command
+  - Enables logging to .harbor/*.log if log:true in config
+  - Runs 'after' scripts when session ends
+
+MODES:
+  Interactive (default): Opens tmux session, use Shift+Left/Right to switch tabs
+  Headless (-d/--headless): Runs in background, use 'anchor' to attach later
+
+PREREQUISITES: harbor.json or harbor config in package.json.
+
+EXAMPLES:
+  harbor launch            # Start and attach to tmux session
+  harbor launch -d         # Start in background (headless mode)
+  harbor launch --headless # Same as -d
+  harbor launch --name my-session # Use custom session name`)
+    .option('-d, --detach', 'Run in background without attaching (headless mode). Use "anchor" to attach later.')
+    .option('--headless', 'Alias for --detach')
+    .option('--name <name>', 'Override tmux session name from config')
+    .action(async (options) => {
     try {
         await checkDependencies();
-        await runServices();
+        await runServices({ detach: options.detach || options.headless, name: options.name });
+    }
+    catch (err) {
+        console.log('❌ Error:', err instanceof Error ? err.message : 'Unknown error');
+        process.exit(1);
+    }
+});
+program.command('anchor')
+    .description(`Attach your terminal to a running Harbor tmux session.
+
+WHEN TO USE: After starting services with 'launch -d' (headless mode).
+
+WHAT IT DOES:
+  - Checks if a Harbor tmux session is running
+  - Attaches your terminal to it
+  - You can then switch between service tabs with Shift+Left/Right
+  - Press Ctrl+q to kill session, or detach with Ctrl+b then d
+
+PREREQUISITES: Services must be running (started with 'harbor launch').
+
+EXAMPLE:
+  harbor launch -d   # Start in background
+  harbor anchor      # Attach to see the services`)
+    .action(async () => {
+    try {
+        const config = await readHarborConfig();
+        const sessionName = config.sessionName || 'harbor';
+        // Check if session exists
+        const checkSession = spawn('tmux', ['has-session', '-t', sessionName], {
+            stdio: 'pipe',
+        });
+        await new Promise((resolve) => {
+            checkSession.on('close', (code) => {
+                if (code !== 0) {
+                    console.log(`❌ No running Harbor session found (looking for: ${sessionName})`);
+                    console.log('\nTo start services, run:');
+                    console.log('  harbor launch');
+                    process.exit(1);
+                }
+                resolve();
+            });
+        });
+        // Attach to the session
+        const attach = spawn('tmux', ['attach-session', '-t', sessionName], {
+            stdio: 'inherit',
+        });
+        attach.on('close', (code) => {
+            process.exit(code || 0);
+        });
+    }
+    catch (err) {
+        console.log('❌ Error:', err instanceof Error ? err.message : 'Unknown error');
+        process.exit(1);
+    }
+});
+program.command('scuttle')
+    .description(`Stop all running Harbor services by killing the tmux session.
+
+WHEN TO USE: When you want to stop all services and free up resources.
+
+WHAT IT DOES:
+  - Finds the running Harbor tmux session
+  - Kills the entire session (all service windows)
+  - All services stop immediately
+
+SAFE TO RUN: If no session is running, it simply reports that and exits cleanly.
+
+EXAMPLE:
+  harbor scuttle   # Stop all services`)
+    .action(async () => {
+    try {
+        const config = await readHarborConfig();
+        const sessionName = config.sessionName || 'harbor';
+        // Check if session exists
+        const checkSession = spawn('tmux', ['has-session', '-t', sessionName], {
+            stdio: 'pipe',
+        });
+        const sessionExists = await new Promise((resolve) => {
+            checkSession.on('close', (code) => {
+                resolve(code === 0);
+            });
+        });
+        if (!sessionExists) {
+            console.log(`ℹ️  No running Harbor session found (looking for: ${sessionName})`);
+            process.exit(0);
+        }
+        // Kill the session
+        const killSession = spawn('tmux', ['kill-session', '-t', sessionName], {
+            stdio: 'inherit',
+        });
+        killSession.on('close', (code) => {
+            if (code === 0) {
+                console.log(`✅ Harbor session '${sessionName}' stopped`);
+            }
+            else {
+                console.log('❌ Failed to stop Harbor session');
+            }
+            process.exit(code || 0);
+        });
+    }
+    catch (err) {
+        console.log('❌ Error:', err instanceof Error ? err.message : 'Unknown error');
+        process.exit(1);
+    }
+});
+program.command('bearings')
+    .description(`Show status of running Harbor services and session information.
+
+WHEN TO USE: To check if services are running, especially in headless mode.
+
+WHAT IT SHOWS:
+  - Session name and running status
+  - List of service windows (with 📄 indicator if logging enabled)
+  - Log file paths and sizes
+  - Available commands (anchor, scuttle)
+
+OUTPUT EXAMPLE:
+  ⚓ Harbor Status
+     Session:  harbor
+     Status:   Running ✓
+     Services: [0] Terminal, [1] web 📄, [2] api 📄
+     Logs:     .harbor/harbor-web.log (1.2 KB)
+
+SAFE TO RUN: Works whether services are running or not.
+
+EXAMPLE:
+  harbor bearings   # Check what's running`)
+    .action(async () => {
+    try {
+        const config = await readHarborConfig();
+        const sessionName = config.sessionName || 'harbor';
+        // Check if session exists
+        const checkSession = spawn('tmux', ['has-session', '-t', sessionName], {
+            stdio: 'pipe',
+        });
+        const sessionExists = await new Promise((resolve) => {
+            checkSession.on('close', (code) => {
+                resolve(code === 0);
+            });
+        });
+        if (!sessionExists) {
+            console.log(`\n⚓ Harbor Status\n`);
+            console.log(`   Session:  ${sessionName}`);
+            console.log(`   Status:   Not running\n`);
+            console.log(`   To start services, run:`);
+            console.log(`     harbor launch         # interactive mode`);
+            console.log(`     harbor launch -d      # headless mode\n`);
+            process.exit(0);
+        }
+        // Get list of windows (services)
+        const listWindows = spawn('tmux', ['list-windows', '-t', sessionName, '-F', '#{window_index}|#{window_name}|#{pane_current_command}'], {
+            stdio: ['pipe', 'pipe', 'pipe'],
+        });
+        let windowOutput = '';
+        listWindows.stdout.on('data', (data) => {
+            windowOutput += data.toString();
+        });
+        await new Promise((resolve) => {
+            listWindows.on('close', () => resolve());
+        });
+        const windows = windowOutput.trim().split('\n').filter(Boolean);
+        console.log(`\n⚓ Harbor Status\n`);
+        console.log(`   Session:  ${sessionName}`);
+        console.log(`   Status:   Running ✓`);
+        console.log(`   Windows:  ${windows.length}\n`);
+        console.log(`   Services:`);
+        for (const window of windows) {
+            const [index, name, cmd] = window.split('|');
+            const logFile = `.harbor/${sessionName}-${name}.log`;
+            const hasLog = fs.existsSync(path.join(process.cwd(), logFile));
+            const logIndicator = hasLog ? ` 📄` : '';
+            console.log(`     [${index}] ${name}${logIndicator}`);
+        }
+        // Check for log files
+        const harborDir = path.join(process.cwd(), '.harbor');
+        if (fs.existsSync(harborDir)) {
+            const logFiles = fs.readdirSync(harborDir).filter(f => f.endsWith('.log'));
+            if (logFiles.length > 0) {
+                console.log(`\n   Logs:`);
+                for (const logFile of logFiles) {
+                    const logPath = path.join(harborDir, logFile);
+                    const stats = fs.statSync(logPath);
+                    const sizeKB = (stats.size / 1024).toFixed(1);
+                    console.log(`     .harbor/${logFile} (${sizeKB} KB)`);
+                }
+            }
+        }
+        console.log(`\n   Commands:`);
+        console.log(`     harbor anchor   - Anchor to the session`);
+        console.log(`     harbor scuttle  - Stop all services\n`);
     }
     catch (err) {
         console.log('❌ Error:', err instanceof Error ? err.message : 'Unknown error');
@@ -526,7 +779,7 @@ async function execute(scripts, scriptType) {
     }
     console.log(`\n✅ All ${scriptType} scripts completed successfully`);
 }
-async function runServices() {
+async function runServices(options = {}) {
     const hasHarborConfig = checkHasHarborConfig();
     if (!hasHarborConfig) {
         console.log('❌ No harbor configuration found');
@@ -553,7 +806,7 @@ async function runServices() {
     try {
         await execute(config.before || [], 'before');
     }
-    catch (err) {
+    catch {
         console.error('❌ Before scripts failed, aborting launch');
         process.exit(1);
     }
@@ -561,10 +814,16 @@ async function runServices() {
     await ensureScriptsExist();
     // Execute the script directly using spawn to handle I/O streams
     const scriptPath = path.join(getScriptsDir(), 'dev.sh');
+    const env = {
+        ...process.env,
+        HARBOR_DETACH: options.detach ? '1' : '0',
+        HARBOR_SESSION_NAME: options.name || '',
+    };
     const command = spawn('bash', [scriptPath], {
         stdio: 'inherit', // This will pipe stdin/stdout/stderr to the parent process
+        env,
     });
-    return new Promise((resolve, reject) => {
+    return new Promise((resolve) => {
         command.on('error', (err) => {
             console.error(`Error running dev.sh: ${err}`);
             process.exit(1);
@@ -579,7 +838,7 @@ async function runServices() {
                 await execute(config.after || [], 'after');
                 resolve();
             }
-            catch (err) {
+            catch {
                 console.error('❌ After scripts failed');
                 process.exit(1);
             }

package/harbor.package-json.schema.json

@@ -95,3 +95,5 @@
 
 
 
+
+

package/package.json

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

package/scripts/dev.sh

@@ -1,12 +1,24 @@
 #!/bin/bash
 
+# Function to get harbor config
+get_harbor_config() {
+    if [ -f "harbor.json" ]; then
+        cat harbor.json
+    elif [ -f "package.json" ]; then
+        jq '.harbor' package.json
+    else
+        echo "{}"
+    fi
+}
+
+# Get session name from env, config, or use default
+session_name="${HARBOR_SESSION_NAME:-$(get_harbor_config | jq -r '.sessionName // "harbor"')}"
+
 # Check if the session already exists and kill it
-if tmux has-session -t local-dev-test 2>/dev/null; then
-    echo "Killing existing tmux session 'local-dev-test'"
-    tmux kill-session -t local-dev-test
+if tmux has-session -t "$session_name" 2>/dev/null; then
+    echo "Killing existing tmux session '$session_name'"
+    tmux kill-session -t "$session_name"
 fi
-
-session_name="local-dev-test"
 repo_root="$(pwd)"
 max_log_lines=1000
 log_pids=()
@@ -38,18 +50,7 @@ start_log_trim() {
 
 trap cleanup_logs EXIT
 
-# Function to get harbor config
-get_harbor_config() {
-    if [ -f "harbor.json" ]; then
-        cat harbor.json
-    elif [ -f "package.json" ]; then
-        jq '.harbor' package.json
-    else
-        echo "{}"
-    fi
-}
-
-# Start a new tmux session named 'local-dev-test' and rename the initial window
+# Start a new tmux session and rename the initial window
 tmux new-session -d -s "$session_name"
 
 # Set tmux options
@@ -98,11 +99,11 @@ tmux set-option -g status-style bg="#1c1917",fg="#a8a29e"
 tmux set-option -g status-left ""
 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
+#[fg=#6366f1, bg=#1c1917] →\
+#[fg=#6366f1, bg=#1c1917, bold] #W\
 #[fg=#6366f1, bg=#1c1917]  "
 tmux set-window-option -g window-status-format "\
-#[fg=#a8a29e, bg=#1c1917]  
+#[fg=#a8a29e, bg=#1c1917]  \
 #[fg=#a8a29e, bg=#1c1917] #W \
 #[fg=#a8a29e, bg=#1c1917] "
 
@@ -160,5 +161,23 @@ tmux bind-key -n Home select-window -t :0
 # Select the terminal window
 tmux select-window -t "$session_name":0
 
-# Attach to the tmux session
-tmux attach-session -t "$session_name"
+# Attach to the tmux session (unless running in detached/headless mode)
+if [ "${HARBOR_DETACH:-0}" = "1" ]; then
+    echo ""
+    echo "🚀 Harbor services started in detached mode"
+    echo ""
+    echo "   Session: $session_name"
+    echo "   Services: $((window_index - 1))"
+    echo ""
+    echo "   Commands:"
+    echo "     harbor anchor  - Anchor to the tmux session"
+    echo "     harbor scuttle - Scuttle all services"
+    echo ""
+    if get_harbor_config | jq -e '.services[] | select(.log == true)' >/dev/null 2>&1; then
+        echo "   Logs:"
+        echo "     tail -f .harbor/${session_name}-<service>.log"
+        echo ""
+    fi
+else
+    tmux attach-session -t "$session_name"
+fi