refactor(tui): improve debug logging and error handling

- Add detailed debug logging throughout TUI launch process
- Implement proper error handling in startTUI function
- Add file existence check before reading theme storage
- Wrap render call in try-catch block
- Improve debug messages for better troubleshooting

Author: moazbuilds

src/cli/tui/app.tsx

@@ -58,22 +58,25 @@ export async function startTUI(
   knownMode?: "dark" | "light",
   initialToast?: InitialToast
 ): Promise<void> {
-  appDebug('[TUI] startTUI called, skipBackgroundDetection=%s', skipBackgroundDetection)
+  appDebug('[TUI] startTUI function entered')
+  appDebug('[TUI] skipBackgroundDetection=%s, knownMode=%s', skipBackgroundDetection, knownMode)
 
   // Priority: 1. Saved theme from KV, 2. Known mode, 3. Auto-detect
   appDebug('[TUI] Getting saved theme')
   const savedTheme = await getSavedTheme()
   appDebug('[TUI] savedTheme=%s', savedTheme)
 
+  appDebug('[TUI] Resolving mode')
   const mode = savedTheme
     ?? (skipBackgroundDetection && knownMode ? knownMode : null)
     ?? await getTerminalBackgroundColor()
   appDebug('[TUI] Resolved mode=%s', mode)
 
   // Wait for stdin to settle after background detection
   if (!skipBackgroundDetection) {
-    appDebug('[TUI] Waiting for stdin to settle')
+    appDebug('[TUI] Waiting for stdin to settle (100ms)')
     await new Promise((r) => setTimeout(r, 100))
+    appDebug('[TUI] stdin settled')
   }
 
   // Clear terminal before OpenTUI takes over
@@ -82,39 +85,50 @@ export async function startTUI(
     process.stdout.write('\x1b[2J\x1b[H\x1b[?25h')
   }
 
-  appDebug('[TUI] Starting OpenTUI render')
+  appDebug('[TUI] About to create render Promise')
   return new Promise<void>((resolve) => {
+    appDebug('[TUI] Inside Promise, creating VignetteEffect')
     const vignetteEffect = new VignetteEffect(0.35)
+    appDebug('[TUI] VignetteEffect created, calling render()')
 
-    render(
-      () => <Root mode={mode} initialToast={initialToast} onExit={() => {
-        appDebug('[TUI] onExit called, closing TUI')
-        closeTUILogger()
-        if (process.stdout.isTTY) {
-          process.stdout.write('\x1b[2J\x1b[H\x1b[?25h')
+    try {
+      render(
+        () => {
+          appDebug('[TUI] Root component render function called')
+          return <Root mode={mode} initialToast={initialToast} onExit={() => {
+            appDebug('[TUI] onExit called, closing TUI')
+            closeTUILogger()
+            if (process.stdout.isTTY) {
+              process.stdout.write('\x1b[2J\x1b[H\x1b[?25h')
+            }
+            resolve()
+          }} />
+        },
+        {
+          targetFps: 60,
+          gatherStats: false,
+          exitOnCtrlC: false,
+          useKittyKeyboard: { events: true },
+          useMouse: true,
+          postProcessFns: [
+            (buffer) => {
+              if (currentView === "workflow") return buffer
+              return vignetteEffect.apply(buffer)
+            },
+            (buffer) => {
+              if (currentView === "workflow") return buffer
+              return applyScanlines(buffer, 0.92, 2)
+            },
+          ],
         }
-        resolve()
-      }} />,
-      {
-        targetFps: 60,
-        gatherStats: false,
-        exitOnCtrlC: false,
-        useKittyKeyboard: { events: true },
-        useMouse: true,
-        postProcessFns: [
-          (buffer) => {
-            if (currentView === "workflow") return buffer
-            return vignetteEffect.apply(buffer)
-          },
-          (buffer) => {
-            if (currentView === "workflow") return buffer
-            return applyScanlines(buffer, 0.92, 2)
-          },
-        ],
-      }
-    )
+      )
+      appDebug('[TUI] render() call completed')
+    } catch (renderErr) {
+      appDebug('[TUI] render() error: %s', renderErr)
+      throw renderErr
+    }
 
-    appDebug('[TUI] Render started, initializing TUI logger in 200ms')
+    appDebug('[TUI] Setting up TUI logger timeout (200ms)')
     setTimeout(() => {
       appDebug('[TUI] Initializing TUI logger')
       initTUILogger()

src/cli/tui/launcher.ts

@@ -25,12 +25,22 @@ appDebug('[Launcher] isDev=%s', isDev);
 if (isDev) {
   appDebug('[Launcher] Loading OpenTUI preload');
   await import("@opentui/solid/preload")
+  appDebug('[Launcher] OpenTUI preload loaded');
 }
 
 // Dynamic import ensures app.js is loaded AFTER preload is registered (in dev)
 export async function startTUI() {
+  appDebug('[Launcher] startTUI() called');
   appDebug('[Launcher] Importing TUI app module');
-  const app = await import("./app.js");
-  appDebug('[Launcher] Starting TUI app');
-  return app.startTUI();
+  try {
+    const app = await import("./app.js");
+    appDebug('[Launcher] app.js imported successfully');
+    appDebug('[Launcher] Calling app.startTUI()');
+    const result = await app.startTUI();
+    appDebug('[Launcher] app.startTUI() returned');
+    return result;
+  } catch (err) {
+    appDebug('[Launcher] Error: %s', err);
+    throw err;
+  }
 }

src/cli/tui/utils/theme-storage.ts

@@ -6,19 +6,35 @@
 
 import { homedir } from "os"
 import path from "path"
+import { appDebug } from "../../../shared/logging/logger.js"
 
 /**
  * Read saved theme from KV file (if exists)
  */
 export async function getSavedTheme(): Promise<"dark" | "light" | null> {
+  appDebug('[ThemeStorage] getSavedTheme called')
   try {
     const kvPath = path.join(homedir(), ".codemachine", "state", "kv.json")
+    appDebug('[ThemeStorage] kvPath=%s', kvPath)
     const file = Bun.file(kvPath)
+
+    // Check if file exists before calling .json() - Bun crashes hard otherwise
+    const exists = await file.exists()
+    appDebug('[ThemeStorage] file exists=%s', exists)
+    if (!exists) {
+      appDebug('[ThemeStorage] File does not exist, returning null')
+      return null
+    }
+
     const data = await file.json() as { theme?: string }
+    appDebug('[ThemeStorage] data=%o', data)
     if (data.theme === "dark" || data.theme === "light") {
+      appDebug('[ThemeStorage] Returning saved theme=%s', data.theme)
       return data.theme
     }
-  } catch {
+    appDebug('[ThemeStorage] No valid theme in data, returning null')
+  } catch (err) {
+    appDebug('[ThemeStorage] Error reading theme: %s', err)
     // File doesn't exist or invalid
   }
   return null

src/runtime/cli-setup.ts

@@ -120,9 +120,11 @@ export async function runCodemachineCli(argv: string[] = process.argv): Promise<
     .option('-d, --dir <path>', 'Target workspace directory', process.cwd())
     .option('--spec <path>', 'Path to the planning specification file', DEFAULT_SPEC_PATH)
     .action(async (options) => {
+      appDebug('[CLI] Action handler entered');
       // Set CWD immediately (lightweight, no I/O)
       const cwd = options.dir || process.cwd();
       process.env.CODEMACHINE_CWD = cwd;
+      appDebug('[CLI] CWD set to %s', cwd);
 
       // Start background initialization (non-blocking, fire-and-forget)
       // This runs while TUI is visible and user is reading/thinking
@@ -134,10 +136,16 @@ export async function runCodemachineCli(argv: string[] = process.argv): Promise<
 
       // Launch TUI immediately - don't wait for background init
       // Import via launcher to scope SolidJS transform to TUI only
-      appDebug('[CLI] Launching TUI');
+      appDebug('[CLI] Importing TUI launcher');
       const { startTUI } = await import('../cli/tui/launcher.js');
-      await startTUI();
-      appDebug('[CLI] TUI exited');
+      appDebug('[CLI] TUI launcher imported, calling startTUI()');
+      try {
+        await startTUI();
+        appDebug('[CLI] TUI exited normally');
+      } catch (tuiError) {
+        appDebug('[CLI] TUI error: %s', tuiError);
+        throw tuiError;
+      }
     });
 
   // Lazy load CLI commands only if user uses subcommands