dev3000 0.0.130 → 0.0.134

package/dist/dev-environment.js

@@ -10,9 +10,9 @@ import { ScreencastManager } from "./screencast-manager.js";
 import { NextJsErrorDetector, OutputProcessor, StandardLogParser } from "./services/parsers/index.js";
 import { DevTUI } from "./tui-interface.js";
 import { formatMcpConfigTargets, MCP_CONFIG_TARGETS } from "./utils/mcp-configs.js";
-import { getProjectDisplayName, getProjectName } from "./utils/project-name.js";
+import { getProjectDir, getProjectDisplayName, getProjectName } from "./utils/project-name.js";
 import { formatTimestamp } from "./utils/timestamp.js";
-import { checkForUpdates } from "./utils/version-check.js";
+import { checkForUpdates, performUpgradeAsync } from "./utils/version-check.js";
 // MCP names
 const MCP_NAMES = {
     DEV3000: "dev3000",
@@ -41,6 +41,66 @@ export const ORPHANED_PROCESS_CLEANUP_PATTERNS = [
 function hasVercelProject() {
     return existsSync(join(process.cwd(), ".vercel"));
 }
+/**
+ * Gracefully terminate a process by first trying SIGTERM, waiting for graceful
+ * shutdown, then falling back to SIGKILL if needed.
+ *
+ * This is important for processes like Next.js dev server that need to clean up
+ * resources (like .next/dev/lock) before exiting.
+ *
+ * @param options - Kill options including PID and optional overrides for testing
+ * @returns Result indicating how the process was terminated
+ */
+export async function gracefulKillProcess(options) {
+    const { pid, gracePeriodMs = 500, killFn = (p, s) => process.kill(p, s), delayFn = (ms) => new Promise((resolve) => setTimeout(resolve, ms)), debugLog = () => { } } = options;
+    const result = {
+        terminated: false,
+        graceful: false,
+        forcedKill: false
+    };
+    // Try process group first (negative PID), fall back to direct PID
+    const pgid = -pid;
+    // Step 1: Send SIGTERM for graceful shutdown
+    debugLog(`Sending SIGTERM to process group ${pgid} (PID: ${pid})`);
+    try {
+        killFn(pgid, "SIGTERM");
+    }
+    catch {
+        // Process group may not exist, try direct kill
+        try {
+            killFn(pid, "SIGTERM");
+        }
+        catch {
+            // Process may already be dead
+            debugLog(`Process ${pid} not found for SIGTERM`);
+            return result;
+        }
+    }
+    // Step 2: Wait for graceful shutdown
+    await delayFn(gracePeriodMs);
+    // Step 3: Check if process is still running
+    try {
+        // Signal 0 checks if process exists without killing it
+        killFn(pid, 0);
+        // Process still running, need to force kill
+        debugLog(`Process still running after SIGTERM, sending SIGKILL`);
+        try {
+            killFn(pgid, "SIGKILL");
+        }
+        catch {
+            killFn(pid, "SIGKILL");
+        }
+        result.terminated = true;
+        result.forcedKill = true;
+    }
+    catch {
+        // Process already dead - graceful shutdown succeeded
+        debugLog(`Process terminated gracefully after SIGTERM`);
+        result.terminated = true;
+        result.graceful = true;
+    }
+    return result;
+}
 class Logger {
     logFile;
     tail;
@@ -436,7 +496,11 @@ async function ensureCursorMcpServers(mcpPort, _appPort, _enableChromeDevtools)
 }
 /**
  * Ensure MCP server configurations are added to project's opencode.json
- * OpenCode uses a different structure: "mcp" instead of "mcpServers" and "type": "local" for stdio servers
+ * OpenCode uses a different structure: "mcp" instead of "mcpServers"
+ *
+ * IMPORTANT: OpenCode has issues with "type": "remote" for HTTP MCP servers.
+ * The workaround is to use "type": "local" with mcp-remote package to proxy requests.
+ * See: https://github.com/sst/opencode/issues/1595
  */
 async function ensureOpenCodeMcpServers(mcpPort, _appPort, _enableChromeDevtools) {
     try {
@@ -454,30 +518,43 @@ async function ensureOpenCodeMcpServers(mcpPort, _appPort, _enableChromeDevtools
         if (!settings.mcp) {
             settings.mcp = {};
         }
-        let added = false;
-        // Add dev3000 MCP server - use npx with mcp-client to connect to HTTP server
-        // NOTE: dev3000 now acts as an MCP orchestrator/gateway that internally
-        // spawns and connects to chrome-devtools-mcp and next-devtools-mcp as stdio processes
-        if (!settings.mcp[MCP_NAMES.DEV3000]) {
-            settings.mcp[MCP_NAMES.DEV3000] = {
-                type: "remote",
-                url: `http://localhost:${mcpPort}/mcp`,
-                enabled: true
-            };
-            added = true;
-        }
-        // Add Vercel MCP if this is a Vercel project (.vercel directory exists)
-        // Vercel MCP uses OAuth authentication handled by the client (OpenCode)
-        if (hasVercelProject() && !settings.mcp[MCP_NAMES.VERCEL]) {
-            settings.mcp[MCP_NAMES.VERCEL] = {
+        let changed = false;
+        // Always update dev3000 MCP server config to ensure correct format
+        // Try simple remote type first - no OAuth needed for local dev3000
+        const expectedDev3000Config = {
+            type: "remote",
+            url: `http://localhost:${mcpPort}/mcp`,
+            enabled: true
+        };
+        const currentDev3000 = settings.mcp[MCP_NAMES.DEV3000];
+        if (!currentDev3000 ||
+            currentDev3000.type !== expectedDev3000Config.type ||
+            currentDev3000.url !== expectedDev3000Config.url) {
+            settings.mcp[MCP_NAMES.DEV3000] = expectedDev3000Config;
+            changed = true;
+        }
+        // Always update Vercel MCP if this is a Vercel project (.vercel directory exists)
+        // Vercel MCP requires OAuth, so use OpenCode's native remote type with oauth: {}
+        // This triggers OpenCode's built-in OAuth flow instead of mcp-remote
+        // See: https://github.com/sst/opencode/issues/5444
+        if (hasVercelProject()) {
+            const expectedVercelConfig = {
                 type: "remote",
                 url: VERCEL_MCP_URL,
+                oauth: {},
                 enabled: true
             };
-            added = true;
+            const currentVercel = settings.mcp[MCP_NAMES.VERCEL];
+            if (!currentVercel ||
+                currentVercel.type !== expectedVercelConfig.type ||
+                currentVercel.url !== expectedVercelConfig.url ||
+                !currentVercel.oauth) {
+                settings.mcp[MCP_NAMES.VERCEL] = expectedVercelConfig;
+                changed = true;
+            }
         }
-        // Write if we added anything
-        if (added) {
+        // Write if we changed anything
+        if (changed) {
             writeFileSync(settingsPath, `${JSON.stringify(settings, null, 2)}\n`, "utf-8");
         }
     }
@@ -521,8 +598,8 @@ async function ensureD3kSkill() {
 export function createPersistentLogFile() {
     // Get unique project name
     const projectName = getProjectName();
-    // Use ~/.d3k/logs directory for persistent, accessible logs
-    const logBaseDir = join(homedir(), ".d3k", "logs");
+    // Use ~/.d3k/{projectName}/logs directory for persistent, accessible logs
+    const logBaseDir = join(getProjectDir(), "logs");
     try {
         if (!existsSync(logBaseDir)) {
             mkdirSync(logBaseDir, { recursive: true });
@@ -539,12 +616,12 @@ export function createPersistentLogFile() {
     }
 }
 // Write session info for MCP server to discover
-function writeSessionInfo(projectName, logFilePath, appPort, mcpPort, cdpUrl, chromePids, serverCommand, framework) {
-    const sessionDir = join(homedir(), ".d3k");
+function writeSessionInfo(projectName, logFilePath, appPort, mcpPort, cdpUrl, chromePids, serverCommand, framework, serverPid) {
+    const projectDir = getProjectDir();
     try {
-        // Create ~/.d3k directory if it doesn't exist
-        if (!existsSync(sessionDir)) {
-            mkdirSync(sessionDir, { recursive: true });
+        // Create project directory if it doesn't exist
+        if (!existsSync(projectDir)) {
+            mkdirSync(projectDir, { recursive: true });
         }
         // Session file contains project info
         const sessionInfo = {
@@ -558,10 +635,11 @@ function writeSessionInfo(projectName, logFilePath, appPort, mcpPort, cdpUrl, ch
             cwd: process.cwd(),
             chromePids: chromePids || [],
             serverCommand: serverCommand || null,
-            framework: framework || null
+            framework: framework || null,
+            serverPid: serverPid || null
         };
-        // Write session file - use project name as filename for easy lookup
-        const sessionFile = join(sessionDir, `${projectName}.json`);
+        // Write session file in project directory
+        const sessionFile = join(projectDir, "session.json");
         writeFileSync(sessionFile, JSON.stringify(sessionInfo, null, 2));
     }
     catch (error) {
@@ -571,8 +649,7 @@ function writeSessionInfo(projectName, logFilePath, appPort, mcpPort, cdpUrl, ch
 }
 // Get Chrome PIDs for this instance
 function getSessionChromePids(projectName) {
-    const sessionDir = join(homedir(), ".d3k");
-    const sessionFile = join(sessionDir, `${projectName}.json`);
+    const sessionFile = join(homedir(), ".d3k", projectName, "session.json");
     try {
         if (existsSync(sessionFile)) {
             const sessionInfo = JSON.parse(readFileSync(sessionFile, "utf8"));
@@ -584,23 +661,45 @@ function getSessionChromePids(projectName) {
     }
     return [];
 }
-function createLogFileInDir(baseDir, projectName) {
-    // Create timestamp
-    const timestamp = new Date().toISOString().replace(/[:.]/g, "-");
-    // Create log file path
-    const logFileName = `${projectName}-${timestamp}.log`;
+// Get server PID for this instance
+function getSessionServerPid(projectName) {
+    const sessionFile = join(homedir(), ".d3k", projectName, "session.json");
+    try {
+        if (existsSync(sessionFile)) {
+            const sessionInfo = JSON.parse(readFileSync(sessionFile, "utf8"));
+            return sessionInfo.serverPid || null;
+        }
+    }
+    catch (_error) {
+        // Non-fatal - return null
+    }
+    return null;
+}
+function createLogFileInDir(baseDir, _projectName) {
+    // Create short timestamp: MMDD-HHmmss (e.g., 0106-171301)
+    const now = new Date();
+    const timestamp = [
+        String(now.getMonth() + 1).padStart(2, "0"),
+        String(now.getDate()).padStart(2, "0"),
+        "-",
+        String(now.getHours()).padStart(2, "0"),
+        String(now.getMinutes()).padStart(2, "0"),
+        String(now.getSeconds()).padStart(2, "0")
+    ].join("");
+    // Create log file path (project name already in directory path)
+    const logFileName = `${timestamp}.log`;
     const logFilePath = join(baseDir, logFileName);
-    // Prune old logs for this project (keep only 10 most recent)
-    pruneOldLogs(baseDir, projectName);
+    // Prune old logs (keep only 10 most recent)
+    pruneOldLogs(baseDir);
     // Create the log file
     writeFileSync(logFilePath, "");
     return logFilePath;
 }
-function pruneOldLogs(baseDir, projectName) {
+function pruneOldLogs(baseDir) {
     try {
-        // Find all log files for this project
+        // Find all log files in directory
         const files = readdirSync(baseDir)
-            .filter((file) => file.startsWith(`${projectName}-`) && file.endsWith(".log"))
+            .filter((file) => file.endsWith(".log"))
             .map((file) => ({
             name: file,
             path: join(baseDir, file),
@@ -620,8 +719,8 @@ function pruneOldLogs(baseDir, projectName) {
             }
         }
     }
-    catch (error) {
-        console.warn(chalk.yellow(`⚠️ Could not prune logs: ${error}`));
+    catch (_error) {
+        // Silently ignore prune errors
     }
 }
 export class DevEnvironment {
@@ -657,9 +756,20 @@ export class DevEnvironment {
         this.disabledMcpConfigSet = new Set(this.options.disabledMcpConfigs);
         this.logger = new Logger(options.logFile, options.tail || false, options.dateTimeFormat || "local");
         this.outputProcessor = new OutputProcessor(new StandardLogParser(), new NextJsErrorDetector());
-        // Set up MCP server public directory for web-accessible screenshots
-        const currentFile = fileURLToPath(import.meta.url);
-        const packageRoot = dirname(dirname(currentFile));
+        // Detect if running from compiled binary
+        const execPath = process.execPath;
+        const isCompiledBinary = execPath.includes("@d3k/darwin-") || execPath.includes("d3k-darwin-") || execPath.endsWith("/dev3000");
+        let packageRoot;
+        if (isCompiledBinary) {
+            // For compiled binaries: bin/dev3000 -> package root
+            const binDir = dirname(execPath);
+            packageRoot = dirname(binDir);
+        }
+        else {
+            // Normal install: dist/dev-environment.js -> package root
+            const currentFile = fileURLToPath(import.meta.url);
+            packageRoot = dirname(dirname(currentFile));
+        }
         // Always use MCP server's public directory for screenshots to ensure they're web-accessible
         // and avoid permission issues with /var/log paths
         this.screenshotDir = join(packageRoot, "mcp-server", "public", "screenshots");
@@ -668,30 +778,36 @@ export class DevEnvironment {
         this.pidFile = join(tmpdir(), `dev3000-${projectName}.pid`);
         this.lockFile = join(tmpdir(), `dev3000-${projectName}.lock`);
         this.mcpPublicDir = join(packageRoot, "mcp-server", "public", "screenshots");
-        // Read version from package.json for startup message
+        // Read version - for compiled binaries, use injected version; otherwise read from package.json
         this.version = "0.0.0";
-        try {
-            const packageJsonPath = join(packageRoot, "package.json");
-            const packageJson = JSON.parse(readFileSync(packageJsonPath, "utf8"));
-            this.version = packageJson.version;
-            // Use git to detect if we're in the dev3000 source repository
+        // Check for compile-time injected version first
+        if (typeof __D3K_VERSION__ !== "undefined") {
+            this.version = __D3K_VERSION__;
+        }
+        else {
             try {
-                const { execSync } = require("child_process");
-                const gitRemote = execSync("git remote get-url origin 2>/dev/null", {
-                    cwd: packageRoot,
-                    encoding: "utf8"
-                }).trim();
-                if (gitRemote.includes("vercel-labs/dev3000") && !this.version.includes("canary")) {
-                    this.version += "-local";
+                const packageJsonPath = join(packageRoot, "package.json");
+                const packageJson = JSON.parse(readFileSync(packageJsonPath, "utf8"));
+                this.version = packageJson.version;
+                // Use git to detect if we're in the dev3000 source repository
+                try {
+                    const { execSync } = require("child_process");
+                    const gitRemote = execSync("git remote get-url origin 2>/dev/null", {
+                        cwd: packageRoot,
+                        encoding: "utf8"
+                    }).trim();
+                    if (gitRemote.includes("vercel-labs/dev3000") && !this.version.includes("canary")) {
+                        this.version += "-local";
+                    }
+                }
+                catch {
+                    // Not in git repo or no git - use version as-is
                 }
             }
-            catch {
-                // Not in git repo or no git - use version as-is
+            catch (_error) {
+                // Use fallback version
             }
         }
-        catch (_error) {
-            // Use fallback version
-        }
         // Initialize spinner for clean output management (only if not in TUI mode)
         this.spinner = ora({
             text: "Initializing...",
@@ -809,7 +925,7 @@ export class DevEnvironment {
                 this.debugLog(`Waiting ${waitTime}ms for port ${this.options.mcpPort} to be released...`);
                 await new Promise((resolve) => setTimeout(resolve, waitTime));
                 // Check if port is now free
-                const available = await isPortAvailable(this.options.mcpPort.toString());
+                const available = await isPortAvailable(this.options.mcpPort?.toString() ?? "");
                 if (available) {
                     this.debugLog(`Port ${this.options.mcpPort} released successfully`);
                     return;
@@ -929,14 +1045,26 @@ export class DevEnvironment {
                 serversOnly: this.options.serversOnly,
                 version: this.version,
                 projectName: projectDisplayName,
-                updateAvailable: null // Will be updated async
+                updateInfo: null // Will be updated async after auto-upgrade
             });
             await this.tui.start();
-            // Update TUI with version check result (non-blocking)
-            updateCheckPromise.then((versionInfo) => {
+            // Auto-upgrade if update available (non-blocking)
+            updateCheckPromise.then(async (versionInfo) => {
                 if (versionInfo?.updateAvailable && versionInfo.latestVersion && this.tui) {
-                    this.debugLog(`Update available: ${versionInfo.currentVersion} -> ${versionInfo.latestVersion}`);
-                    this.tui.updateUpdateAvailable({ latestVersion: versionInfo.latestVersion });
+                    this.debugLog(`Update available: ${versionInfo.currentVersion} -> ${versionInfo.latestVersion}, auto-upgrading...`);
+                    // Perform upgrade in background
+                    const result = await performUpgradeAsync();
+                    if (result.success) {
+                        const newVersion = result.newVersion || versionInfo.latestVersion;
+                        this.debugLog(`Auto-upgrade successful: ${newVersion}`);
+                        // Show "Updated to vX.X.X" message (auto-hides after 10s)
+                        this.tui.updateUpdateInfo({ type: "updated", newVersion });
+                    }
+                    else {
+                        // Upgrade failed - show update available instead
+                        this.debugLog(`Auto-upgrade failed: ${result.error}, showing update available`);
+                        this.tui.updateUpdateInfo({ type: "available", latestVersion: versionInfo.latestVersion });
+                    }
                 }
             });
             // Check ports in background after TUI is visible
@@ -973,7 +1101,7 @@ export class DevEnvironment {
             if (!serverStarted) {
                 await this.tui.updateStatus("❌ Server failed to start");
                 console.error(chalk.red("\n❌ Your app server failed to start after 30 seconds."));
-                console.error(chalk.yellow(`Check the logs at ~/.d3k/logs/${getProjectName()}-d3k.log for errors.`));
+                console.error(chalk.yellow(`Check the logs at ~/.d3k/${getProjectName()}/logs/ for errors.`));
                 console.error(chalk.yellow("Exiting without launching browser."));
                 process.exit(1);
             }
@@ -1008,7 +1136,7 @@ export class DevEnvironment {
             // Write session info for MCP server discovery (include CDP URL if browser monitoring was started)
             const cdpUrl = this.cdpMonitor?.getCdpUrl() || null;
             const chromePids = this.cdpMonitor?.getChromePids() || [];
-            writeSessionInfo(projectName, this.options.logFile, this.options.port, this.options.mcpPort, cdpUrl, chromePids, this.options.serverCommand, this.options.framework);
+            writeSessionInfo(projectName, this.options.logFile, this.options.port, this.options.mcpPort, cdpUrl, chromePids, this.options.serverCommand, this.options.framework, this.serverProcess?.pid);
             // Clear status - ready!
             await this.tui.updateStatus(null);
         }
@@ -1036,7 +1164,7 @@ export class DevEnvironment {
             if (!serverStarted) {
                 this.spinner.fail("Server failed to start");
                 console.error(chalk.red("\n❌ Your app server failed to start after 30 seconds."));
-                console.error(chalk.yellow(`Check the logs at ~/.d3k/logs/${getProjectName()}-d3k.log for errors.`));
+                console.error(chalk.yellow(`Check the logs at ~/.d3k/${getProjectName()}/logs/ for errors.`));
                 console.error(chalk.yellow("Exiting without launching browser."));
                 process.exit(1);
             }
@@ -1071,7 +1199,7 @@ export class DevEnvironment {
             // Include CDP URL if browser monitoring was started
             const cdpUrl = this.cdpMonitor?.getCdpUrl() || null;
             const chromePids = this.cdpMonitor?.getChromePids() || [];
-            writeSessionInfo(projectName, this.options.logFile, this.options.port, this.options.mcpPort, cdpUrl, chromePids, this.options.serverCommand, this.options.framework);
+            writeSessionInfo(projectName, this.options.logFile, this.options.port, this.options.mcpPort, cdpUrl, chromePids, this.options.serverCommand, this.options.framework, this.serverProcess?.pid);
             // Complete startup with success message only in non-TUI mode
             this.spinner.succeed("Development environment ready!");
             // Regular console output (when TUI is disabled with --no-tui)
@@ -1084,12 +1212,21 @@ export class DevEnvironment {
                 console.log(chalk.cyan("🖥️  Servers-only mode - use Chrome extension for browser monitoring"));
             }
             console.log(chalk.cyan("\nUse Ctrl-C to stop.\n"));
-            // Check for updates in non-TUI mode (non-blocking)
+            // Auto-upgrade in non-TUI mode (non-blocking)
             checkForUpdates()
-                .then((versionInfo) => {
+                .then(async (versionInfo) => {
                 if (versionInfo?.updateAvailable && versionInfo.latestVersion) {
-                    console.log(chalk.yellow(`\n↑ Update available: v${versionInfo.currentVersion} → v${versionInfo.latestVersion}`));
-                    console.log(chalk.gray(`  Run 'd3k upgrade' to update\n`));
+                    this.debugLog(`Update available: ${versionInfo.currentVersion} -> ${versionInfo.latestVersion}, auto-upgrading...`);
+                    const result = await performUpgradeAsync();
+                    if (result.success) {
+                        const newVersion = result.newVersion || versionInfo.latestVersion;
+                        console.log(chalk.green(`\n✓ Updated to v${newVersion}`));
+                    }
+                    else {
+                        // Upgrade failed - show update available
+                        console.log(chalk.yellow(`\n↑ Update available: v${versionInfo.currentVersion} → v${versionInfo.latestVersion}`));
+                        console.log(chalk.gray(`  Run 'd3k upgrade' to update\n`));
+                    }
                 }
             })
                 .catch(() => {
@@ -1263,7 +1400,7 @@ export class DevEnvironment {
             const cdpUrl = this.cdpMonitor?.getCdpUrl();
             const chromePids = this.cdpMonitor?.getChromePids() || [];
             if (cdpUrl || chromePids.length > 0) {
-                writeSessionInfo(projectName, this.options.logFile, this.options.port, this.options.mcpPort, cdpUrl || undefined, chromePids, this.options.serverCommand);
+                writeSessionInfo(projectName, this.options.logFile, this.options.port, this.options.mcpPort, cdpUrl || undefined, chromePids, this.options.serverCommand, this.options.framework, this.serverProcess?.pid);
                 this.debugLog(`Updated session info with new port: ${this.options.port}`);
             }
             // Update TUI header with new port
@@ -1315,11 +1452,11 @@ export class DevEnvironment {
         }
         // Always write to d3k debug log file (even when not in debug mode)
         try {
-            const debugLogDir = join(homedir(), ".d3k");
-            if (!existsSync(debugLogDir)) {
-                mkdirSync(debugLogDir, { recursive: true });
+            const projectDir = getProjectDir();
+            if (!existsSync(projectDir)) {
+                mkdirSync(projectDir, { recursive: true });
             }
-            const debugLogFile = join(debugLogDir, "d3k.log");
+            const debugLogFile = join(projectDir, "debug.log");
             const logEntry = `[${timestamp}] [DEBUG] ${message}\n`;
             appendFileSync(debugLogFile, logEntry);
         }
@@ -1352,14 +1489,58 @@ export class DevEnvironment {
             console.log(chalk.yellow(`💡 Check logs for details: ${this.options.logFile}`));
         }
     }
+    checkForCommonIssues() {
+        try {
+            if (!existsSync(this.options.logFile))
+                return;
+            const logContent = readFileSync(this.options.logFile, "utf8");
+            // Check for Next.js lock file issue (this fix also kills the process holding the port)
+            if (logContent.includes("Unable to acquire lock") && logContent.includes(".next/dev/lock")) {
+                console.log(chalk.yellow("\n💡 Detected Next.js lock file issue!"));
+                console.log(chalk.white("   Another Next.js dev server may be running or crashed without cleanup."));
+                console.log(chalk.white("   To fix, run:"));
+                console.log(chalk.cyan("   rm -f .next/dev/lock && pkill -f 'next dev'"));
+                return; // pkill also fixes the port-in-use issue, so skip that check
+            }
+            // Check for port in use (only if not a Next.js lock issue)
+            const portInUseMatch = logContent.match(/Port (\d+) is in use by process (\d+)/);
+            if (portInUseMatch) {
+                const [, port, pid] = portInUseMatch;
+                console.log(chalk.yellow(`\n💡 Port ${port} was already in use by process ${pid}`));
+                console.log(chalk.white("   To kill that process, run:"));
+                console.log(chalk.cyan(`   kill -9 ${pid}`));
+            }
+        }
+        catch {
+            // Ignore errors reading log file
+        }
+    }
     async startMcpServer() {
         this.debugLog("Starting MCP server setup");
         // Note: MCP server cleanup now happens earlier in checkPortsAvailable()
         // to ensure the port is free before we check availability
         // Get the path to our bundled MCP server
-        const currentFile = fileURLToPath(import.meta.url);
-        const packageRoot = dirname(dirname(currentFile)); // Go up from dist/ to package root
-        let mcpServerPath = join(packageRoot, "mcp-server");
+        // Handle both normal npm install and compiled binary cases
+        let mcpServerPath;
+        // Check if we're running from a compiled binary
+        // Compiled binaries have process.execPath pointing to the binary itself
+        const execPath = process.execPath;
+        const isCompiledBinary = execPath.includes("@d3k/darwin-") || execPath.includes("d3k-darwin-") || execPath.endsWith("/dev3000");
+        if (isCompiledBinary) {
+            // For compiled binaries, mcp-server is a sibling to the bin directory
+            // Structure: packages/d3k-darwin-arm64/bin/dev3000 -> packages/d3k-darwin-arm64/mcp-server
+            const binDir = dirname(execPath);
+            const packageDir = dirname(binDir);
+            mcpServerPath = join(packageDir, "mcp-server");
+            this.debugLog(`Compiled binary detected, MCP server path: ${mcpServerPath}`);
+        }
+        else {
+            // Normal npm install - mcp-server is in the package root
+            const currentFile = fileURLToPath(import.meta.url);
+            const packageRoot = dirname(dirname(currentFile)); // Go up from dist/ to package root
+            mcpServerPath = join(packageRoot, "mcp-server");
+            this.debugLog(`Standard install detected, MCP server path: ${mcpServerPath}`);
+        }
         this.debugLog(`Initial MCP server path: ${mcpServerPath}`);
         // For pnpm global installs, resolve symlinks to get the real path
         if (existsSync(mcpServerPath)) {
@@ -1790,13 +1971,12 @@ export class DevEnvironment {
     }
     initializeD3KLog() {
         try {
-            const debugLogDir = join(homedir(), ".d3k", "logs");
-            if (!existsSync(debugLogDir)) {
-                mkdirSync(debugLogDir, { recursive: true });
+            const projectDir = getProjectDir();
+            if (!existsSync(projectDir)) {
+                mkdirSync(projectDir, { recursive: true });
             }
-            // Create project-specific D3K log file and clear it for new session
-            const projectName = getProjectName();
-            const d3kLogFile = join(debugLogDir, `${projectName}-d3k.log`);
+            // Create D3K log file and clear it for new session
+            const d3kLogFile = join(projectDir, "d3k.log");
             writeFileSync(d3kLogFile, "");
         }
         catch {
@@ -1809,13 +1989,11 @@ export class DevEnvironment {
         const timestamp = formatTimestamp(new Date(), this.options.dateTimeFormat || "local");
         const logEntry = `[${timestamp}] [D3K] ${message}\n`;
         try {
-            const debugLogDir = join(homedir(), ".d3k", "logs");
-            if (!existsSync(debugLogDir)) {
-                mkdirSync(debugLogDir, { recursive: true });
+            const projectDir = getProjectDir();
+            if (!existsSync(projectDir)) {
+                mkdirSync(projectDir, { recursive: true });
             }
-            // Create project-specific D3K log file to avoid confusion between multiple instances
-            const projectName = getProjectName();
-            const d3kLogFile = join(debugLogDir, `${projectName}-d3k.log`);
+            const d3kLogFile = join(projectDir, "d3k.log");
             appendFileSync(d3kLogFile, logEntry);
         }
         catch {
@@ -1881,7 +2059,7 @@ export class DevEnvironment {
             }
             // Always write session info after CDP monitoring starts - this is critical for
             // sandbox environments where external tools poll for the cdpUrl in the session file
-            writeSessionInfo(projectName, this.options.logFile, this.options.port, this.options.mcpPort, cdpUrl || undefined, chromePids, this.options.serverCommand);
+            writeSessionInfo(projectName, this.options.logFile, this.options.port, this.options.mcpPort, cdpUrl || undefined, chromePids, this.options.serverCommand, this.options.framework, this.serverProcess?.pid);
             this.debugLog(`Updated session info with CDP URL: ${cdpUrl}, Chrome PIDs: [${chromePids.join(", ")}]`);
             this.logger.log("browser", `[CDP] Session info written with cdpUrl: ${cdpUrl ? "available" : "null"}`);
             // Navigate to the app
@@ -1905,10 +2083,12 @@ export class DevEnvironment {
             await this.screencastManager.stop();
             this.screencastManager = null;
         }
+        // Read server PID from session file BEFORE deleting it (needed for cleanup)
+        const projectName = getProjectName();
+        const savedServerPid = getSessionServerPid(projectName);
         // Clean up session file
         try {
-            const projectName = getProjectName();
-            const sessionFile = join(homedir(), ".d3k", `${projectName}.json`);
+            const sessionFile = join(homedir(), ".d3k", projectName, "session.json");
             if (existsSync(sessionFile)) {
                 unlinkSync(sessionFile);
             }
@@ -1954,6 +2134,24 @@ export class DevEnvironment {
         // Kill app server only (MCP server remains as singleton)
         console.log(chalk.cyan("🔄 Killing app server..."));
         await killPortProcess(this.options.port, "your app server");
+        // Kill server process and its children using the saved PID (from before session file was deleted)
+        if (!isInSandbox() && savedServerPid) {
+            try {
+                const { spawnSync } = await import("child_process");
+                // Kill all child processes of the server
+                spawnSync("pkill", ["-P", savedServerPid.toString()], { stdio: "ignore" });
+                // Kill the server process itself
+                try {
+                    process.kill(savedServerPid, "SIGKILL");
+                }
+                catch {
+                    // Process may already be dead
+                }
+            }
+            catch {
+                // Ignore pkill errors
+            }
+        }
         // Shutdown CDP monitor if it was started
         if (this.cdpMonitor) {
             try {
@@ -1966,8 +2164,10 @@ export class DevEnvironment {
             }
         }
         console.log(chalk.red(`❌ ${this.options.commandName} exited due to server failure`));
-        const projectName = getProjectName();
-        console.log(chalk.yellow(`Check the logs at ~/.d3k/logs/${projectName}-d3k.log for errors. Feeling like helping? Run dev3000 --debug and file an issue at https://github.com/vercel-labs/dev3000/issues`));
+        // Show recent log entries to help diagnose the issue
+        this.showRecentLogs();
+        // Check for common issues and provide specific guidance
+        this.checkForCommonIssues();
         process.exit(1);
     }
     setupCleanupHandlers() {
@@ -2038,16 +2238,32 @@ export class DevEnvironment {
                 process.exit(1);
             });
         });
+        // Handle SIGHUP (sent by tmux when session/pane is killed)
+        process.on("SIGHUP", () => {
+            this.debugLog("SIGHUP received (tmux session closing)");
+            if (this.isShuttingDown)
+                return;
+            this.isShuttingDown = true;
+            this.handleShutdown()
+                .then(() => {
+                process.exit(0);
+            })
+                .catch(() => {
+                process.exit(1);
+            });
+        });
     }
     async handleShutdown() {
         // Stop health monitoring
         this.stopHealthCheck();
         // Release the lock file
         this.releaseLock();
+        // Read server PID from session file BEFORE deleting it (needed for cleanup)
+        const projectName = getProjectName();
+        const savedServerPid = getSessionServerPid(projectName);
         // Clean up session file
         try {
-            const projectName = getProjectName();
-            const sessionFile = join(homedir(), ".d3k", `${projectName}.json`);
+            const sessionFile = join(homedir(), ".d3k", projectName, "session.json");
             if (existsSync(sessionFile)) {
                 unlinkSync(sessionFile);
             }
@@ -2176,12 +2392,15 @@ export class DevEnvironment {
         // Next.js's next-server and webpack workers) are also killed.
         if (this.serverProcess?.pid) {
             try {
-                // Negative PID kills the entire process group
-                const pgid = -this.serverProcess.pid;
-                this.debugLog(`Killing process group ${pgid} (server PID: ${this.serverProcess.pid})`);
-                process.kill(pgid, "SIGKILL");
-                if (!this.options.tui) {
-                    console.log(chalk.green(`✅ Killed server process group (PID: ${this.serverProcess.pid})`));
+                // Use graceful kill: SIGTERM first, wait, then SIGKILL if needed
+                // This allows Next.js to clean up .next/dev/lock before terminating
+                const result = await gracefulKillProcess({
+                    pid: this.serverProcess.pid,
+                    debugLog: (msg) => this.debugLog(msg)
+                });
+                if (!this.options.tui && result.terminated) {
+                    const method = result.graceful ? "gracefully" : "forcefully";
+                    console.log(chalk.green(`✅ Killed server process group ${method} (PID: ${this.serverProcess.pid})`));
                 }
             }
             catch (error) {
@@ -2195,9 +2414,24 @@ export class DevEnvironment {
         await new Promise((resolve) => setTimeout(resolve, 100));
         // Double-check: try to kill any remaining processes on the app port
         try {
-            const { spawn } = await import("child_process");
-            spawn("sh", ["-c", `pkill -f ":${this.options.port}"`], { stdio: "ignore" });
+            const { spawnSync } = await import("child_process");
+            // Kill by port
+            spawnSync("sh", ["-c", `pkill -f ":${this.options.port}"`], { stdio: "ignore" });
             this.debugLog(`Sent pkill signal for port ${this.options.port}`);
+            // Kill server process and its children using the saved PID (from before session file was deleted)
+            if (savedServerPid) {
+                // Kill all child processes of the server
+                spawnSync("pkill", ["-P", savedServerPid.toString()], { stdio: "ignore" });
+                this.debugLog(`Killed children of server PID ${savedServerPid}`);
+                // Kill the server process itself
+                try {
+                    process.kill(savedServerPid, "SIGKILL");
+                    this.debugLog(`Killed server PID ${savedServerPid}`);
+                }
+                catch {
+                    // Process may already be dead
+                }
+            }
         }
         catch {
             // Ignore pkill errors