port-doctor-cli 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Port Doctor Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,266 @@
+# Port Doctor 🩺
+
+> Developer-first diagnostic, troubleshooting, and forensic CLI for local development ports.
+
+[![npm version](https://img.shields.io/npm/v/port-doctor-cli.svg?style=flat-square)](https://www.npmjs.com/package/port-doctor-cli)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg?style=flat-square)](LICENSE)
+
+**Port Doctor** answers the question every developer asks:  
+**`"Why won't my development server start?"`**
+
+It bridges low-level kernel sockets and opaque PIDs with rich developer workspace context: **Project Name, Git Repository, Branch, Dirty Status, Framework, Process Tree, and Uptime**.
+
+---
+
+## ⚡ Why Port Doctor?
+
+| Feature | `kill-port` | `fkill` | Raw `lsof` / `netstat` | **Port Doctor** |
+| :--- | :---: | :---: | :---: | :---: |
+| **Identifies Git Repo & Branch** | ❌ | ❌ | ❌ | **✅ Yes** |
+| **Identifies Web Framework / Database** | ❌ | ❌ | ❌ | **✅ Yes** |
+| **Shows Full Process Tree & CWD** | ❌ | ❌ | ❌ | **✅ Yes** |
+| **Safe Graceful Termination (SIGINT first)** | ❌ (blind kill -9) | ⚠️ Partial | ❌ | **✅ Yes** |
+| **PID Race Condition Protection** | ❌ | ❌ | ❌ | **✅ Yes** |
+| **Auto-Healing `run` Wrapper** | ❌ | ❌ | ❌ | **✅ Yes** |
+| **Redacts Passwords / Tokens in CLI** | ❌ | ❌ | ❌ | **✅ Yes** |
+| **Minimal Dependencies & Fast Startup** | ⚠️ | ❌ | ⚠️ | **✅ Yes** |
+
+---
+
+## 🚀 Quick Start
+
+Run directly with `npx` (using the `port-doctor-cli` package) — no global installation required:
+
+```bash
+npx port-doctor-cli
+```
+
+Or install globally to use the `port-doctor` command anywhere:
+
+```bash
+npm install -g port-doctor-cli
+```
+
+Once installed globally, you can run `port-doctor` directly:
+
+```bash
+port-doctor
+```
+
+---
+
+## 📖 Command Reference
+
+### 1. Default Overview: `port-doctor`
+Scans common development and database ports (`3000-3005, 5173-5175, 8000, 8080, 5432, 6379, 27017, ...`) and displays active services.
+
+```bash
+npx port-doctor-cli
+```
+
+```text
+PORT DOCTOR v1.0.0 — Local Port Forensics & Diagnostics
+
+PORT    STATUS    PROCESS       PID     PROJECT / SERVICE         UPTIME      
+──────────────────────────────────────────────────────────────────────────────
+3000    BUSY      node          8212    storefront-ui (Next.js)   2h 14m      
+5173    FREE      -             -       -                         -           
+6379    BUSY      redis-server  8121    Redis                     5h 30m      
+27017   FREE      -             -       -                         -           
+──────────────────────────────────────────────────────────────────────────────
+Scanned 18 ports • 2 occupied • 16 available
+```
+
+Scan custom port ranges:
+```bash
+npx port-doctor-cli --ports 3000,5173,8000-8080
+```
+
+---
+
+### 2. Forensic Diagnosis: `port-doctor why <port>`
+The signature command. Explains exactly what process, directory, Git branch, and service is holding a port.
+
+```bash
+npx port-doctor-cli why 3000
+```
+
+```text
+● PORT 3000 IS OCCUPIED
+
+Process
+  Name:     node
+  PID:      8212 (User: developer)
+  Command:  npm run dev
+  Uptime:   2h 14m
+  Memory:   148.5 MB
+
+Project
+  Name:     storefront-ui
+  Path:     /Users/developer/Projects/storefront-ui
+  Git:      storefront-ui
+  Branch:   feature/checkout-v2 [dirty: +3 files]
+
+Service / Framework
+  Type:     Next.js (web-framework)
+
+Process Tree
+  VS Code (PID 4102)
+  └─ zsh (PID 4210)
+    └─ npm (PID 8200)
+      └─ node (PID 8212)
+
+Listening on
+  127.0.0.1:3000 (TCP)
+
+Diagnosis
+  Port 3000 is occupied by Next.js (storefront-ui on branch 'feature/checkout-v2').
+
+Suggested Action
+  Run 'port-doctor free 3000' to safely release the port.
+```
+
+---
+
+### 3. Safe Release: `port-doctor free <port...>`
+Safely stops the process occupying a port. It first shows process and project details, attempts graceful `SIGINT` (Ctrl+C), then `SIGTERM`, and returns an error with instructions to use `--force` if the process resists graceful exit. It also verifies process identity immediately before sending kill signals to prevent PID race conditions.
+
+```bash
+# Safe interactive release with confirmation (SIGINT -> SIGTERM)
+npx port-doctor-cli free 3000
+
+# Release multiple ports
+npx port-doctor-cli free 3000 8080
+
+# Explicit force termination (SIGKILL) without confirmation
+npx port-doctor-cli free 3000 --force
+
+# Dry run mode (simulate what would happen)
+npx port-doctor-cli free 3000 --dry-run
+```
+
+*(Aliases: `kill`, `release`)*
+
+---
+
+### 4. Auto-Healing Runner: `port-doctor run "<command>"`
+Runs your development startup script. If the port is already occupied by a leftover process, it detects the conflict before starting and prompts you to safely release it gracefully before booting the dev server.
+
+```bash
+npx port-doctor-cli run "npm run dev"
+```
+
+```text
+⚠ Port 3000 is already in use.
+  Process: node (PID 8212)
+  Project: old-storefront (branch: staging)
+  Command: npm run dev
+
+How would you like to proceed?
+  1. Stop existing process gracefully and start
+  2. Cancel
+
+Enter your choice (1-2): 1
+
+Attempting graceful release of port 3000...
+✓ Port 3000 released.
+
+Starting: npm run dev
+```
+
+---
+
+### 5. Global `--json` Mode
+Outputs pure, machine-readable JSON across all commands for script automation and CI/CD pipelines.
+
+```bash
+npx port-doctor-cli why 3000 --json
+```
+
+```json
+{
+  "port": 3000,
+  "status": "busy",
+  "protocol": "tcp",
+  "address": "127.0.0.1",
+  "allAddresses": ["127.0.0.1", "::1"],
+  "pid": 8212,
+  "process": {
+    "pid": 8212,
+    "name": "node",
+    "command": "npm run dev",
+    "cwd": "/Users/developer/Projects/storefront-ui",
+    "uptimeSeconds": 8040,
+    "uptimeFormatted": "2h 14m"
+  },
+  "project": {
+    "name": "storefront-ui",
+    "rootDirectory": "/Users/developer/Projects/storefront-ui"
+  },
+  "git": {
+    "isGitRepo": true,
+    "repoName": "storefront-ui",
+    "branch": "feature/checkout-v2",
+    "isDirty": true,
+    "uncommittedFilesCount": 3
+  },
+  "framework": {
+    "name": "Next.js",
+    "category": "web-framework",
+    "confidence": "high"
+  },
+  "diagnosis": {
+    "type": "dev_server",
+    "severity": "warning",
+    "summary": "Port 3000 is occupied by Next.js (storefront-ui on branch 'feature/checkout-v2').",
+    "safeToFree": true
+  }
+}
+```
+
+For `port-doctor run "<command>" --json`, it executes a pre-flight port collision inspection and emits a structured `{ status: "ready" | "conflict", ... }` JSON payload without corrupting `stdout`.
+
+---
+
+## 💻 Programmatic Node.js API
+
+You can also use Port Doctor inside your own Node.js / TypeScript code:
+
+```typescript
+import { inspectPort, releasePort, scanDevPorts } from 'port-doctor-cli';
+
+// Inspect a specific port
+const info = await inspectPort(3000);
+if (info.status === 'busy') {
+  console.log(`Port 3000 is used by ${info.project?.name} (${info.framework?.name})`);
+}
+
+// Safely release a port
+const result = await releasePort(3000, { force: false });
+console.log(`Port released: ${result.success}`);
+
+// Scan active dev ports
+const devPorts = await scanDevPorts();
+```
+
+---
+
+## 🛡️ Security & Privacy
+
+- **Credential Redaction**: Passwords, API tokens, bearer keys, and database connection strings in process command lines are automatically masked before terminal display or JSON output.
+- **Command Execution**: `port-doctor run "<command>"` intentionally executes the user-supplied command through the platform shell. Internal process-management and diagnostic commands use structured argument execution instead of unnecessary shell interpolation.
+- **Graceful Shutdown & Verification**: Attempts graceful shutdown (`SIGINT` then `SIGTERM`) and verifies process identity before sending signals to prevent PID race conditions. Escalates to force-kill (`SIGKILL`) only upon explicit user request (`--force`).
+
+---
+
+## 🌐 Platform Support
+
+- **macOS** (Apple Silicon & Intel)
+- **Linux** (Ubuntu, Debian, Fedora, Arch, Alpine)
+- **Windows** (Windows 10, 11, Windows Server)
+
+---
+
+## 📄 License
+
+MIT © Port Doctor Contributors

package/bin/port-doctor.js

@@ -0,0 +1,8 @@
+#!/usr/bin/env node
+
+import { runCLI } from '../dist/cli/index.js';
+
+runCLI().catch((err) => {
+  console.error('\n✗ Unexpected Error:', err.message || err);
+  process.exit(1);
+});

package/dist/cli/commands/free.d.ts

@@ -0,0 +1,3 @@
+import { CLIArgs } from '../../types/index.js';
+export declare function handleFree(ports: number[], args: CLIArgs): Promise<void>;
+//# sourceMappingURL=free.d.ts.map

package/dist/cli/commands/free.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"free.d.ts","sourceRoot":"","sources":["../../../src/cli/commands/free.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,OAAO,EAAc,MAAM,sBAAsB,CAAC;AAO3D,wBAAsB,UAAU,CAAC,KAAK,EAAE,MAAM,EAAE,EAAE,IAAI,EAAE,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC,CA2H9E"}

package/dist/cli/commands/free.js

@@ -0,0 +1,120 @@
+import pc from 'picocolors';
+import { inspectPort } from '../../core/process/index.js';
+import { releasePort } from '../../core/lifecycle/index.js';
+import { formatFreeResult } from '../output/formatter.js';
+import { printJson } from '../output/json.js';
+import { askConfirmation } from '../prompts/confirm.js';
+export async function handleFree(ports, args) {
+    if (!ports || ports.length === 0) {
+        if (args.json) {
+            printJson({ status: 'error', error: 'No port specified to free.' });
+        }
+        else {
+            console.error(pc.red('\n✗ Error: Please specify at least one port to free (e.g. `port-doctor free 3000`).\n'));
+        }
+        process.exit(1);
+    }
+    const results = [];
+    for (const port of ports) {
+        if (isNaN(port) || port <= 0 || port > 65535) {
+            console.error(pc.red(`✗ Invalid port: ${port}`));
+            continue;
+        }
+        const info = await inspectPort(port, { deep: true });
+        if (info.status === 'free') {
+            const res = {
+                port,
+                pid: 0,
+                processName: 'none',
+                success: true,
+                method: 'none',
+                timeTakenMs: 0,
+            };
+            results.push(res);
+            if (!args.json) {
+                console.log(formatFreeResult(res));
+            }
+            continue;
+        }
+        // Dry run mode
+        if (args.dryRun) {
+            if (!args.json) {
+                console.log(pc.yellow(`[Dry Run] Would release port ${port} (PID ${info.pid} - ${info.process?.name || 'unknown'}, Project: ${info.project?.name || 'none'})`));
+            }
+            results.push({
+                port,
+                pid: info.pid || 0,
+                processName: info.process?.name || 'unknown',
+                projectName: info.project?.name,
+                success: true,
+                method: 'none',
+                timeTakenMs: 0,
+            });
+            continue;
+        }
+        // Safety protection: protect system processes and databases from accidental termination
+        if (info.diagnosis?.safeToFree === false && !args.force) {
+            const typeDesc = info.diagnosis.type === 'database' ? 'database' : 'system service';
+            const serviceName = info.framework?.name || info.process?.name || 'system process';
+            const reason = `Refusing to terminate ${serviceName} (PID ${info.pid}) on port ${port} because it is classified as a protected ${typeDesc}. Use 'port-doctor free ${port} --force' if you explicitly intend to terminate it.`;
+            if (!args.json) {
+                console.error(pc.red(`\n✗ Safety Protection: ${reason}\n`));
+            }
+            results.push({
+                port,
+                pid: info.pid || 0,
+                processName: info.process?.name || 'unknown',
+                projectName: info.project?.name,
+                success: false,
+                method: 'none',
+                timeTakenMs: 0,
+                error: reason,
+            });
+            continue;
+        }
+        // Confirmation prompt if not forced and in interactive terminal
+        if (!args.force && process.stdin.isTTY && !args.json) {
+            console.log('');
+            console.log(pc.bold(`Target: Port ${port}`));
+            console.log(`  Process: ${pc.bold(info.process?.name || 'unknown')} (PID ${info.pid})`);
+            if (info.project?.name) {
+                console.log(`  Project: ${pc.cyan(info.project.name)}${info.git?.branch ? ` (branch: ${info.git.branch})` : ''}`);
+            }
+            if (info.process?.fullCommand) {
+                console.log(`  Command: ${info.process.fullCommand}`);
+            }
+            const confirmed = await askConfirmation(`Are you sure you want to release port ${port}?`, false);
+            if (!confirmed) {
+                console.log(pc.yellow(`Aborted release for port ${port}.\n`));
+                results.push({
+                    port,
+                    pid: info.pid || 0,
+                    processName: info.process?.name || 'unknown',
+                    projectName: info.project?.name,
+                    success: false,
+                    method: 'none',
+                    timeTakenMs: 0,
+                    error: 'User cancelled operation.',
+                });
+                continue;
+            }
+        }
+        const onProgress = !args.json ? (msg) => console.log(pc.dim(`  ${msg}`)) : undefined;
+        const res = await releasePort(port, {
+            force: args.force,
+            timeoutMs: args.timeout,
+            onProgress,
+        });
+        results.push(res);
+        if (!args.json) {
+            console.log(formatFreeResult(res));
+        }
+    }
+    if (args.json) {
+        printJson({
+            status: results.every((r) => r.success) ? 'success' : 'partial_failure',
+            results,
+        });
+    }
+}
+//# sourceMappingURL=free.js.map

package/dist/cli/commands/free.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"free.js","sourceRoot":"","sources":["../../../src/cli/commands/free.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,YAAY,CAAC;AAE5B,OAAO,EAAE,WAAW,EAAE,MAAM,6BAA6B,CAAC;AAC1D,OAAO,EAAE,WAAW,EAAE,MAAM,+BAA+B,CAAC;AAC5D,OAAO,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAC1D,OAAO,EAAE,SAAS,EAAE,MAAM,mBAAmB,CAAC;AAC9C,OAAO,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AAExD,MAAM,CAAC,KAAK,UAAU,UAAU,CAAC,KAAe,EAAE,IAAa;IAC7D,IAAI,CAAC,KAAK,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACjC,IAAI,IAAI,CAAC,IAAI,EAAE,CAAC;YACd,SAAS,CAAC,EAAE,MAAM,EAAE,OAAO,EAAE,KAAK,EAAE,4BAA4B,EAAE,CAAC,CAAC;QACtE,CAAC;aAAM,CAAC;YACN,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC,GAAG,CAAC,uFAAuF,CAAC,CAAC,CAAC;QACjH,CAAC;QACD,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IAClB,CAAC;IAED,MAAM,OAAO,GAAiB,EAAE,CAAC;IAEjC,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;QACzB,IAAI,KAAK,CAAC,IAAI,CAAC,IAAI,IAAI,IAAI,CAAC,IAAI,IAAI,GAAG,KAAK,EAAE,CAAC;YAC7C,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC,GAAG,CAAC,mBAAmB,IAAI,EAAE,CAAC,CAAC,CAAC;YACjD,SAAS;QACX,CAAC;QAED,MAAM,IAAI,GAAG,MAAM,WAAW,CAAC,IAAI,EAAE,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC;QAErD,IAAI,IAAI,CAAC,MAAM,KAAK,MAAM,EAAE,CAAC;YAC3B,MAAM,GAAG,GAAe;gBACtB,IAAI;gBACJ,GAAG,EAAE,CAAC;gBACN,WAAW,EAAE,MAAM;gBACnB,OAAO,EAAE,IAAI;gBACb,MAAM,EAAE,MAAM;gBACd,WAAW,EAAE,CAAC;aACf,CAAC;YACF,OAAO,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;YAClB,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC;gBACf,OAAO,CAAC,GAAG,CAAC,gBAAgB,CAAC,GAAG,CAAC,CAAC,CAAC;YACrC,CAAC;YACD,SAAS;QACX,CAAC;QAED,eAAe;QACf,IAAI,IAAI,CAAC,MAAM,EAAE,CAAC;YAChB,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC;gBACf,OAAO,CAAC,GAAG,CAAC,EAAE,CAAC,MAAM,CAAC,gCAAgC,IAAI,SAAS,IAAI,CAAC,GAAG,MAAM,IAAI,CAAC,OAAO,EAAE,IAAI,IAAI,SAAS,cAAc,IAAI,CAAC,OAAO,EAAE,IAAI,IAAI,MAAM,GAAG,CAAC,CAAC,CAAC;YAClK,CAAC;YACD,OAAO,CAAC,IAAI,CAAC;gBACX,IAAI;gBACJ,GAAG,EAAE,IAAI,CAAC,GAAG,IAAI,CAAC;gBAClB,WAAW,EAAE,IAAI,CAAC,OAAO,EAAE,IAAI,IAAI,SAAS;gBAC5C,WAAW,EAAE,IAAI,CAAC,OAAO,EAAE,IAAI;gBAC/B,OAAO,EAAE,IAAI;gBACb,MAAM,EAAE,MAAM;gBACd,WAAW,EAAE,CAAC;aACf,CAAC,CAAC;YACH,SAAS;QACX,CAAC;QAED,wFAAwF;QACxF,IAAI,IAAI,CAAC,SAAS,EAAE,UAAU,KAAK,KAAK,IAAI,CAAC,IAAI,CAAC,KAAK,EAAE,CAAC;YACxD,MAAM,QAAQ,GAAG,IAAI,CAAC,SAAS,CAAC,IAAI,KAAK,UAAU,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC,gBAAgB,CAAC;YACpF,MAAM,WAAW,GAAG,IAAI,CAAC,SAAS,EAAE,IAAI,IAAI,IAAI,CAAC,OAAO,EAAE,IAAI,IAAI,gBAAgB,CAAC;YACnF,MAAM,MAAM,GAAG,yBAAyB,WAAW,SAAS,IAAI,CAAC,GAAG,aAAa,IAAI,4CAA4C,QAAQ,2BAA2B,IAAI,qDAAqD,CAAC;YAE9N,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC;gBACf,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC,GAAG,CAAC,0BAA0B,MAAM,IAAI,CAAC,CAAC,CAAC;YAC9D,CAAC;YACD,OAAO,CAAC,IAAI,CAAC;gBACX,IAAI;gBACJ,GAAG,EAAE,IAAI,CAAC,GAAG,IAAI,CAAC;gBAClB,WAAW,EAAE,IAAI,CAAC,OAAO,EAAE,IAAI,IAAI,SAAS;gBAC5C,WAAW,EAAE,IAAI,CAAC,OAAO,EAAE,IAAI;gBAC/B,OAAO,EAAE,KAAK;gBACd,MAAM,EAAE,MAAM;gBACd,WAAW,EAAE,CAAC;gBACd,KAAK,EAAE,MAAM;aACd,CAAC,CAAC;YACH,SAAS;QACX,CAAC;QAED,gEAAgE;QAChE,IAAI,CAAC,IAAI,CAAC,KAAK,IAAI,OAAO,CAAC,KAAK,CAAC,KAAK,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC;YACrD,OAAO,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;YAChB,OAAO,CAAC,GAAG,CAAC,EAAE,CAAC,IAAI,CAAC,gBAAgB,IAAI,EAAE,CAAC,CAAC,CAAC;YAC7C,OAAO,CAAC,GAAG,CAAC,cAAc,EAAE,CAAC,IAAI,CAAC,IAAI,CAAC,OAAO,EAAE,IAAI,IAAI,SAAS,CAAC,SAAS,IAAI,CAAC,GAAG,GAAG,CAAC,CAAC;YACxF,IAAI,IAAI,CAAC,OAAO,EAAE,IAAI,EAAE,CAAC;gBACvB,OAAO,CAAC,GAAG,CAAC,cAAc,EAAE,CAAC,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC,GAAG,EAAE,MAAM,CAAC,CAAC,CAAC,aAAa,IAAI,CAAC,GAAG,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;YACpH,CAAC;YACD,IAAI,IAAI,CAAC,OAAO,EAAE,WAAW,EAAE,CAAC;gBAC9B,OAAO,CAAC,GAAG,CAAC,cAAc,IAAI,CAAC,OAAO,CAAC,WAAW,EAAE,CAAC,CAAC;YACxD,CAAC;YAED,MAAM,SAAS,GAAG,MAAM,eAAe,CAAC,yCAAyC,IAAI,GAAG,EAAE,KAAK,CAAC,CAAC;YACjG,IAAI,CAAC,SAAS,EAAE,CAAC;gBACf,OAAO,CAAC,GAAG,CAAC,EAAE,CAAC,MAAM,CAAC,4BAA4B,IAAI,KAAK,CAAC,CAAC,CAAC;gBAC9D,OAAO,CAAC,IAAI,CAAC;oBACX,IAAI;oBACJ,GAAG,EAAE,IAAI,CAAC,GAAG,IAAI,CAAC;oBAClB,WAAW,EAAE,IAAI,CAAC,OAAO,EAAE,IAAI,IAAI,SAAS;oBAC5C,WAAW,EAAE,IAAI,CAAC,OAAO,EAAE,IAAI;oBAC/B,OAAO,EAAE,KAAK;oBACd,MAAM,EAAE,MAAM;oBACd,WAAW,EAAE,CAAC;oBACd,KAAK,EAAE,2BAA2B;iBACnC,CAAC,CAAC;gBACH,SAAS;YACX,CAAC;QACH,CAAC;QAED,MAAM,UAAU,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,GAAW,EAAE,EAAE,CAAC,OAAO,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,CAAC,KAAK,GAAG,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC;QAC7F,MAAM,GAAG,GAAG,MAAM,WAAW,CAAC,IAAI,EAAE;YAClC,KAAK,EAAE,IAAI,CAAC,KAAK;YACjB,SAAS,EAAE,IAAI,CAAC,OAAO;YACvB,UAAU;SACX,CAAC,CAAC;QAEH,OAAO,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;QAClB,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC;YACf,OAAO,CAAC,GAAG,CAAC,gBAAgB,CAAC,GAAG,CAAC,CAAC,CAAC;QACrC,CAAC;IACH,CAAC;IAED,IAAI,IAAI,CAAC,IAAI,EAAE,CAAC;QACd,SAAS,CAAC;YACR,MAAM,EAAE,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,iBAAiB;YACvE,OAAO;SACR,CAAC,CAAC;IACL,CAAC;AACH,CAAC"}

package/dist/cli/commands/overview.d.ts

@@ -0,0 +1,3 @@
+import { CLIArgs } from '../../types/index.js';
+export declare function handleOverview(args: CLIArgs): Promise<void>;
+//# sourceMappingURL=overview.d.ts.map

package/dist/cli/commands/overview.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"overview.d.ts","sourceRoot":"","sources":["../../../src/cli/commands/overview.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,sBAAsB,CAAC;AAK/C,wBAAsB,cAAc,CAAC,IAAI,EAAE,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC,CAgBjE"}

package/dist/cli/commands/overview.js

@@ -0,0 +1,19 @@
+import { scanDevPorts, parsePortList } from '../../core/scanner/index.js';
+import { formatOverviewTable } from '../output/formatter.js';
+import { printJson } from '../output/json.js';
+export async function handleOverview(args) {
+    const targetPorts = args.ports || parsePortList();
+    const results = await scanDevPorts(targetPorts);
+    if (args.json) {
+        printJson({
+            status: 'success',
+            totalScanned: results.length,
+            busyCount: results.filter((r) => r.status === 'busy').length,
+            freeCount: results.filter((r) => r.status === 'free').length,
+            ports: results,
+        });
+        return;
+    }
+    console.log(formatOverviewTable(results));
+}
+//# sourceMappingURL=overview.js.map

package/dist/cli/commands/overview.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"overview.js","sourceRoot":"","sources":["../../../src/cli/commands/overview.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,YAAY,EAAE,aAAa,EAAE,MAAM,6BAA6B,CAAC;AAC1E,OAAO,EAAE,mBAAmB,EAAE,MAAM,wBAAwB,CAAC;AAC7D,OAAO,EAAE,SAAS,EAAE,MAAM,mBAAmB,CAAC;AAE9C,MAAM,CAAC,KAAK,UAAU,cAAc,CAAC,IAAa;IAChD,MAAM,WAAW,GAAG,IAAI,CAAC,KAAK,IAAI,aAAa,EAAE,CAAC;IAClD,MAAM,OAAO,GAAG,MAAM,YAAY,CAAC,WAAW,CAAC,CAAC;IAEhD,IAAI,IAAI,CAAC,IAAI,EAAE,CAAC;QACd,SAAS,CAAC;YACR,MAAM,EAAE,SAAS;YACjB,YAAY,EAAE,OAAO,CAAC,MAAM;YAC5B,SAAS,EAAE,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,MAAM,KAAK,MAAM,CAAC,CAAC,MAAM;YAC5D,SAAS,EAAE,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,MAAM,KAAK,MAAM,CAAC,CAAC,MAAM;YAC5D,KAAK,EAAE,OAAO;SACf,CAAC,CAAC;QACH,OAAO;IACT,CAAC;IAED,OAAO,CAAC,GAAG,CAAC,mBAAmB,CAAC,OAAO,CAAC,CAAC,CAAC;AAC5C,CAAC"}

package/dist/cli/commands/run.d.ts

@@ -0,0 +1,4 @@
+import { CLIArgs } from '../../types/index.js';
+export declare function detectExpectedPort(command: string, cwd?: string): Promise<number | undefined>;
+export declare function handleRun(rawCommand: string, args: CLIArgs): Promise<void>;
+//# sourceMappingURL=run.d.ts.map

package/dist/cli/commands/run.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"run.d.ts","sourceRoot":"","sources":["../../../src/cli/commands/run.ts"],"names":[],"mappings":"AAIA,OAAO,EAAE,OAAO,EAAE,MAAM,sBAAsB,CAAC;AAM/C,wBAAsB,kBAAkB,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,SAAgB,GAAG,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAsC1G;AAED,wBAAsB,SAAS,CAAC,UAAU,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC,CAwFhF"}

package/dist/cli/commands/run.js

@@ -0,0 +1,133 @@
+import * as path from 'node:path';
+import * as fs from 'node:fs/promises';
+import { spawn } from 'node:child_process';
+import pc from 'picocolors';
+import { inspectPort } from '../../core/process/index.js';
+import { releasePort } from '../../core/lifecycle/index.js';
+import { printJson } from '../output/json.js';
+import { askChoice } from '../prompts/confirm.js';
+export async function detectExpectedPort(command, cwd = process.cwd()) {
+    // 1. Check command line flags like --port 3000 or -p 5173 or PORT=3000
+    const portFlagMatch = command.match(/(?:--port|-p)\s+(\d+)/i) || command.match(/PORT=(\d+)/i);
+    if (portFlagMatch) {
+        const p = parseInt(portFlagMatch[1], 10);
+        if (!isNaN(p) && p > 0 && p <= 65535)
+            return p;
+    }
+    // 2. Check .env, .env.local, .env.development in cwd
+    const envFiles = ['.env.local', '.env.development', '.env'];
+    for (const envFile of envFiles) {
+        try {
+            const content = await fs.readFile(path.join(cwd, envFile), 'utf8');
+            const match = content.match(/^PORT\s*=\s*(\d+)/m);
+            if (match) {
+                const p = parseInt(match[1], 10);
+                if (!isNaN(p) && p > 0 && p <= 65535)
+                    return p;
+            }
+        }
+        catch {
+            // ignore
+        }
+    }
+    // 3. Inspect package.json
+    try {
+        const pkgContent = await fs.readFile(path.join(cwd, 'package.json'), 'utf8');
+        const pkg = JSON.parse(pkgContent);
+        const allDeps = { ...pkg.dependencies, ...pkg.devDependencies };
+        if (allDeps['vite'])
+            return 5173;
+        if (allDeps['next'])
+            return 3000;
+        if (allDeps['astro'])
+            return 4321;
+        if (allDeps['@nestjs/core'] || allDeps['express'] || allDeps['fastify'])
+            return 3000;
+    }
+    catch {
+        // ignore
+    }
+    return undefined;
+}
+export async function handleRun(rawCommand, args) {
+    if (!rawCommand || !rawCommand.trim()) {
+        if (args.json) {
+            printJson({ status: 'error', error: 'No command specified for `run`.' });
+        }
+        else {
+            console.error(pc.red('\n✗ Error: Please specify a command to run (e.g. `port-doctor run "npm run dev"`).\n'));
+        }
+        process.exit(1);
+    }
+    const expectedPort = await detectExpectedPort(rawCommand);
+    if (expectedPort) {
+        const portInfo = await inspectPort(expectedPort, { deep: true });
+        if (portInfo.status === 'busy') {
+            if (args.json) {
+                printJson({
+                    status: 'conflict',
+                    message: `Port ${expectedPort} is already in use.`,
+                    port: expectedPort,
+                    occupyingProcess: portInfo.process,
+                    project: portInfo.project,
+                });
+                process.exit(1);
+            }
+            console.log('');
+            console.log(pc.yellow(pc.bold(`⚠ Port ${expectedPort} is already in use.`)));
+            console.log(`  Process: ${pc.bold(portInfo.process?.name || 'unknown')} (PID ${portInfo.pid})`);
+            if (portInfo.project?.name) {
+                console.log(`  Project: ${pc.cyan(portInfo.project.name)}${portInfo.git?.branch ? ` (branch: ${portInfo.git.branch})` : ''}`);
+            }
+            if (portInfo.process?.fullCommand) {
+                console.log(`  Command: ${portInfo.process.fullCommand}`);
+            }
+            const choices = [
+                `Stop existing process gracefully and start`,
+                `Cancel`,
+            ];
+            const choiceIdx = await askChoice('How would you like to proceed?', choices);
+            if (choiceIdx === 0) {
+                // Attempt graceful release ONLY
+                console.log(pc.dim(`\nAttempting graceful release of port ${expectedPort}...`));
+                const freeRes = await releasePort(expectedPort, { force: false });
+                if (!freeRes.success) {
+                    console.error(pc.red(`\n✗ Graceful stop failed (PID ${portInfo.pid} did not exit within timeout).`));
+                    console.error(`  To force-kill this process, run: ${pc.cyan(`port-doctor free ${expectedPort} --force`)}\n`);
+                    process.exit(1);
+                }
+                console.log(pc.green(`✓ Port ${expectedPort} released.`));
+            }
+            else {
+                console.log(pc.dim('Operation cancelled.'));
+                process.exit(0);
+            }
+        }
+    }
+    // Handle JSON preflight mode without corrupting stdout
+    if (args.json) {
+        printJson({
+            status: 'ready',
+            message: expectedPort ? `Port ${expectedPort} is available.` : 'Command pre-flight passed.',
+            port: expectedPort,
+            command: rawCommand,
+        });
+        return;
+    }
+    // Execute user command with inherited stdio
+    console.log(pc.cyan(`\nStarting: ${pc.bold(rawCommand)}\n`));
+    const child = spawn(rawCommand, {
+        shell: true,
+        stdio: 'inherit',
+        env: process.env,
+    });
+    child.on('exit', (code, signal) => {
+        if (signal) {
+            process.kill(process.pid, signal);
+        }
+        else {
+            process.exit(code || 0);
+        }
+    });
+}
+//# sourceMappingURL=run.js.map

package/dist/cli/commands/run.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"run.js","sourceRoot":"","sources":["../../../src/cli/commands/run.ts"],"names":[],"mappings":"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"}

package/dist/cli/commands/why.d.ts

@@ -0,0 +1,3 @@
+import { CLIArgs } from '../../types/index.js';
+export declare function handleWhy(port: number, args: CLIArgs): Promise<void>;
+//# sourceMappingURL=why.d.ts.map

package/dist/cli/commands/why.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"why.d.ts","sourceRoot":"","sources":["../../../src/cli/commands/why.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,sBAAsB,CAAC;AAK/C,wBAAsB,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC,CAqB1E"}

package/dist/cli/commands/why.js

@@ -0,0 +1,24 @@
+import { inspectPort } from '../../core/process/index.js';
+import { formatWhyReport } from '../output/formatter.js';
+import { printJson } from '../output/json.js';
+export async function handleWhy(port, args) {
+    if (isNaN(port) || port <= 0 || port > 65535) {
+        if (args.json) {
+            printJson({
+                status: 'error',
+                error: `Invalid port number: ${port}. Port must be an integer between 1 and 65535.`,
+            });
+        }
+        else {
+            console.error(`\n✗ Error: Invalid port number "${port}". Must be between 1 and 65535.\n`);
+        }
+        process.exit(1);
+    }
+    const info = await inspectPort(port, { deep: true });
+    if (args.json) {
+        printJson(info);
+        return;
+    }
+    console.log(formatWhyReport(info));
+}
+//# sourceMappingURL=why.js.map

package/dist/cli/commands/why.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"why.js","sourceRoot":"","sources":["../../../src/cli/commands/why.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,WAAW,EAAE,MAAM,6BAA6B,CAAC;AAC1D,OAAO,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC;AACzD,OAAO,EAAE,SAAS,EAAE,MAAM,mBAAmB,CAAC;AAE9C,MAAM,CAAC,KAAK,UAAU,SAAS,CAAC,IAAY,EAAE,IAAa;IACzD,IAAI,KAAK,CAAC,IAAI,CAAC,IAAI,IAAI,IAAI,CAAC,IAAI,IAAI,GAAG,KAAK,EAAE,CAAC;QAC7C,IAAI,IAAI,CAAC,IAAI,EAAE,CAAC;YACd,SAAS,CAAC;gBACR,MAAM,EAAE,OAAO;gBACf,KAAK,EAAE,wBAAwB,IAAI,gDAAgD;aACpF,CAAC,CAAC;QACL,CAAC;aAAM,CAAC;YACN,OAAO,CAAC,KAAK,CAAC,mCAAmC,IAAI,mCAAmC,CAAC,CAAC;QAC5F,CAAC;QACD,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IAClB,CAAC;IAED,MAAM,IAAI,GAAG,MAAM,WAAW,CAAC,IAAI,EAAE,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC;IAErD,IAAI,IAAI,CAAC,IAAI,EAAE,CAAC;QACd,SAAS,CAAC,IAAI,CAAC,CAAC;QAChB,OAAO;IACT,CAAC;IAED,OAAO,CAAC,GAAG,CAAC,eAAe,CAAC,IAAI,CAAC,CAAC,CAAC;AACrC,CAAC"}