feat(logging): add app debug logging throughout TUI components

Add new appDebug logging function and integrate it across TUI components to track initialization and workflow execution. Pin @opentui/core version to exact 0.1.60 to prevent potential version mismatches.

The logging helps diagnose startup issues and track application flow, particularly during critical paths like workflow execution and component initialization. The version pinning ensures consistent behavior across environments.

Author: moazbuilds

bun.lock

@@ -69,7 +69,7 @@
   "dependencies": {
     "@clack/prompts": "^0.11.0",
     "@modelcontextprotocol/sdk": "^1.0.0",
-    "@opentui/core": "^0.1.60",
+    "@opentui/core": "0.1.60",
     "@opentui/solid": "^0.1.60",
     "chalk": "^5.6.2",
     "commander": "^14.0.1",

package.json

@@ -19,7 +19,7 @@ import { Workflow } from "@tui/routes/workflow"
 import { Onboard } from "@tui/routes/onboard"
 import { homedir } from "os"
 import { WorkflowEventBus, OnboardingService } from "../../workflows/events/index.js"
-import { debug, setDebugLogFile } from "../../shared/logging/logger.js"
+import { debug, setDebugLogFile, appDebug } from "../../shared/logging/logger.js"
 import { MonitoringCleanup } from "../../agents/monitoring/index.js"
 import path from "path"
 import { createRequire } from "node:module"
@@ -104,16 +104,19 @@ async function copyToSystemClipboard(text: string): Promise<void> {
 }
 
 export function App(props: { initialToast?: InitialToast }) {
+  appDebug('[AppShell] App component initializing')
   const dimensions = useTerminalDimensions()
   const themeCtx = useTheme()
   const session = useSession()
   const updateNotifier = useUpdateNotifier()
   const renderer = useRenderer()
   const toast = useToast()
   const kv = useKV()
+  appDebug('[AppShell] Hooks initialized')
 
   // Global error handler - any part of the app can emit 'app:error' to show a toast
   const handleAppError = (data: { message: string; duration?: number }) => {
+    appDebug('[AppShell] App error received: %s', data.message)
     toast.show({
       variant: "error",
       message: data.message,
@@ -143,15 +146,18 @@ export function App(props: { initialToast?: InitialToast }) {
   }
 
   const handleStartWorkflow = async () => {
+    appDebug('[AppShell] handleStartWorkflow called')
     const cwd = process.env.CODEMACHINE_CWD || process.cwd()
     const cmRoot = path.join(cwd, '.codemachine')
+    appDebug('[AppShell] cwd=%s, cmRoot=%s', cwd, cmRoot)
 
     // Initialize debug log file early (before onboarding) so all logs are captured
     const rawLogLevel = (process.env.LOG_LEVEL || '').trim().toLowerCase()
     const debugFlag = (process.env.DEBUG || '').trim().toLowerCase()
     const debugEnabled = rawLogLevel === 'debug' || (debugFlag !== '' && debugFlag !== '0' && debugFlag !== 'false')
     if (debugEnabled) {
       const debugLogPath = path.join(cwd, '.codemachine', 'logs', 'workflow-debug.log')
+      appDebug('[AppShell] Switching to workflow debug log: %s', debugLogPath)
       setDebugLogFile(debugLogPath)
     }
 
@@ -221,34 +227,41 @@ export function App(props: { initialToast?: InitialToast }) {
       }
     } catch (error) {
       // If template loading fails, proceed to workflow anyway
+      appDebug('[AppShell] Failed to check tracks/conditions: %s', error)
       console.error("Failed to check tracks/conditions:", error)
     }
 
     // No tracks/conditions or already selected - start workflow directly
+    appDebug('[AppShell] Starting workflow execution directly')
     startWorkflowExecution()
   }
 
   const startWorkflowExecution = () => {
+    appDebug('[AppShell] startWorkflowExecution called')
     const eventBus = new WorkflowEventBus()
     setWorkflowEventBus(eventBus)
     // @ts-expect-error - global export for workflow connection
     globalThis.__workflowEventBus = eventBus
 
     const cwd = process.env.CODEMACHINE_CWD || process.cwd()
     const specPath = path.join(cwd, '.codemachine', 'inputs', 'specifications.md')
+    appDebug('[AppShell] specPath=%s', specPath)
 
     pendingWorkflowStart = () => {
+      appDebug('[AppShell] Importing and running workflow')
       import("../../workflows/run.js").then(({ runWorkflow }) => {
         runWorkflow({ cwd, specificationPath: specPath }).catch((error) => {
           // Emit error event to show toast with actual error message
           const errorMsg = error instanceof Error ? error.message : String(error)
+          appDebug('[AppShell] Workflow error: %s', errorMsg)
           ;(process as NodeJS.EventEmitter).emit('app:error', { message: errorMsg })
         })
       })
     }
 
     currentView = "workflow"
     setView("workflow")
+    appDebug('[AppShell] View set to workflow')
   }
 
   const handleOnboardComplete = async (result: { projectName?: string; trackId?: string; conditions?: string[]; controllerAgentId?: string }) => {

src/cli/tui/app-shell.tsx

@@ -18,6 +18,7 @@ import { initTUILogger, closeTUILogger } from "@tui/shared/utils/tui-logger"
 import { getSavedTheme, getTerminalBackgroundColor } from "./utils"
 import { App, currentView } from "./app-shell"
 import { ErrorComponent } from "./components/error-boundary"
+import { appDebug } from "../../shared/logging/logger.js"
 
 export type InitialToast = {
   variant: "success" | "error" | "info" | "warning"
@@ -57,27 +58,37 @@ export async function startTUI(
   knownMode?: "dark" | "light",
   initialToast?: InitialToast
 ): Promise<void> {
+  appDebug('[TUI] startTUI called, skipBackgroundDetection=%s', skipBackgroundDetection)
+
   // 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)
+
   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')
     await new Promise((r) => setTimeout(r, 100))
   }
 
   // Clear terminal before OpenTUI takes over
   if (process.stdout.isTTY) {
+    appDebug('[TUI] Clearing terminal')
     process.stdout.write('\x1b[2J\x1b[H\x1b[?25h')
   }
 
+  appDebug('[TUI] Starting OpenTUI render')
   return new Promise<void>((resolve) => {
     const vignetteEffect = new VignetteEffect(0.35)
 
     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')
@@ -103,7 +114,9 @@ export async function startTUI(
       }
     )
 
+    appDebug('[TUI] Render started, initializing TUI logger in 200ms')
     setTimeout(() => {
+      appDebug('[TUI] Initializing TUI logger')
       initTUILogger()
     }, 200)
   })

src/cli/tui/app.tsx

@@ -16,15 +16,21 @@
  * to ensure the plugin is registered before any JSX files are parsed.
  */
 
+import { appDebug } from '../../shared/logging/logger.js';
+
 // Only load preload in dev mode (when running from source)
 // In production binaries, JSX is pre-transformed during build
 const isDev = import.meta.url.includes('/src/')
+appDebug('[Launcher] isDev=%s', isDev);
 if (isDev) {
+  appDebug('[Launcher] Loading OpenTUI preload');
   await import("@opentui/solid/preload")
 }
 
 // Dynamic import ensures app.js is loaded AFTER preload is registered (in dev)
 export async function startTUI() {
+  appDebug('[Launcher] Importing TUI app module');
   const app = await import("./app.js");
+  appDebug('[Launcher] Starting TUI app');
   return app.startTUI();
 }

src/cli/tui/launcher.ts

@@ -1,30 +1,54 @@
+// EARLY LOGGING SETUP - Initialize before anything else
+import * as path from 'node:path';
+import { setAppLogFile, appDebug } from '../shared/logging/logger.js';
+
+const earlyCwd = process.env.CODEMACHINE_CWD || process.cwd();
+const earlyLogLevel = (process.env.LOG_LEVEL || '').trim().toLowerCase();
+const earlyDebugFlag = (process.env.DEBUG || '').trim().toLowerCase();
+const earlyDebugEnabled = earlyLogLevel === 'debug' || (earlyDebugFlag !== '' && earlyDebugFlag !== '0' && earlyDebugFlag !== 'false');
+if (earlyDebugEnabled) {
+  const appDebugLogPath = path.join(earlyCwd, '.codemachine', 'logs', 'app-debug.log');
+  setAppLogFile(appDebugLogPath);
+}
+appDebug('[Boot] CLI module loading started');
+
 // ENSURE EMBEDDED RESOURCES EARLY (BEFORE IMPORTS)
 // This must run before any modules that might resolve the package root
+appDebug('[Boot] Importing embed module');
 import { ensure as ensureResources } from '../shared/runtime/embed.js';
 
+appDebug('[Boot] Ensuring embedded resources');
 const embeddedRoot = await ensureResources();
+appDebug('[Boot] embeddedRoot=%s', embeddedRoot);
 
 if (!embeddedRoot && !process.env.CODEMACHINE_INSTALL_DIR) {
   // Fallback to normal resolution if not embedded
+  appDebug('[Boot] Resolving package root (fallback)');
   const { resolvePackageRoot } = await import('../shared/runtime/root.js');
   try {
     const packageRoot = resolvePackageRoot(import.meta.url, 'cli-setup');
     process.env.CODEMACHINE_INSTALL_DIR = packageRoot;
-  } catch {
+    appDebug('[Boot] CODEMACHINE_INSTALL_DIR=%s', packageRoot);
+  } catch (err) {
+    appDebug('[Boot] Failed to resolve package root: %s', err);
     // Continue without setting
   }
 }
 
 // IMMEDIATE SPLASH - Only show for main TUI session
 // Skip splash for: subcommands, help flags, or version flags
+appDebug('[Boot] Checking splash screen conditions');
 const args = process.argv.slice(2);
+appDebug('[Boot] args=%o', args);
 const hasSubcommand = args.length > 0 && !args[0].startsWith('-');
 const hasHelpOrVersion = args.some(arg =>
   arg === '--help' || arg === '-h' || arg === '--version' || arg === '-V'
 );
 const shouldSkipSplash = hasSubcommand || hasHelpOrVersion;
+appDebug('[Boot] hasSubcommand=%s, hasHelpOrVersion=%s, shouldSkipSplash=%s', hasSubcommand, hasHelpOrVersion, shouldSkipSplash);
 
 if (process.stdout.isTTY && !shouldSkipSplash) {
+  appDebug('[Boot] Showing splash screen');
   const { rows = 24, columns = 80 } = process.stdout;
   const centerY = Math.floor(rows / 2);
   const centerX = Math.floor(columns / 2);
@@ -33,12 +57,14 @@ if (process.stdout.isTTY && !shouldSkipSplash) {
   process.stdout.write('\x1b[38;2;224;230;240mCode\x1b[1mMachine\x1b[0m');
   process.stdout.write(`\x1b[${centerY + 1};${centerX - 6}H`);
   process.stdout.write('\x1b[38;2;0;217;255m━━━━━━━━━━━━\x1b[0m');
+  appDebug('[Boot] Splash screen displayed');
 }
 
+appDebug('[Boot] Importing remaining modules');
 import { Command } from 'commander';
 import { existsSync, realpathSync } from 'node:fs';
 import { fileURLToPath } from 'node:url';
-import * as path from 'node:path';
+appDebug('[Boot] Imports complete');
 
 const DEFAULT_SPEC_PATH = '.codemachine/inputs/specifications.md';
 
@@ -51,6 +77,7 @@ async function initializeInBackground(cwd: string): Promise<void> {
 
   // Only bootstrap if .codemachine doesn't exist
   if (!existsSync(cmRoot)) {
+    appDebug('[Init] Bootstrapping workspace (first run)');
     // Lazy load bootstrap utilities (only on first run)
     const { bootstrapWorkspace } = await import('./services/workspace/index.js');
     const { resolvePackageRoot } = await import('../shared/runtime/root.js');
@@ -60,23 +87,31 @@ async function initializeInBackground(cwd: string): Promise<void> {
     const defaultTemplate = path.join(templatesDir, 'codemachine.workflow.js');
 
     await bootstrapWorkspace({ cwd, templatePath: defaultTemplate });
+    appDebug('[Init] Workspace bootstrapped');
   }
 
   // Lazy load and initialize engine registry
+  appDebug('[Init] Loading engine registry');
   const { registry } = await import('../infra/engines/index.js');
   const engines = registry.getAll();
 
   // Sync engine configs in background
+  appDebug('[Init] Syncing %d engine configs', engines.length);
   for (const engine of engines) {
     if (engine.syncConfig) {
       await engine.syncConfig();
     }
   }
+  appDebug('[Init] Background initialization complete');
 }
 
 export async function runCodemachineCli(argv: string[] = process.argv): Promise<void> {
+  appDebug('[CLI] runCodemachineCli started');
+
   // Import version from auto-generated version file (works in compiled binaries)
+  appDebug('[CLI] Importing version');
   const { VERSION } = await import('./version.js');
+  appDebug('[CLI] VERSION=%s', VERSION);
 
   const program = new Command()
     .name('codemachine')
@@ -91,53 +126,84 @@ export async function runCodemachineCli(argv: string[] = process.argv): Promise<
 
       // Start background initialization (non-blocking, fire-and-forget)
       // This runs while TUI is visible and user is reading/thinking
+      appDebug('[CLI] Starting background initialization');
       initializeInBackground(cwd).catch(err => {
+        appDebug('[CLI] Background init error: %s', err);
         console.error('[Background Init Error]', err);
       });
 
       // Launch TUI immediately - don't wait for background init
       // Import via launcher to scope SolidJS transform to TUI only
+      appDebug('[CLI] Launching TUI');
       const { startTUI } = await import('../cli/tui/launcher.js');
       await startTUI();
+      appDebug('[CLI] TUI exited');
     });
 
   // Lazy load CLI commands only if user uses subcommands
   if (argv.length > 2 && !argv[2].startsWith('-')) {
+    appDebug('[CLI] Loading subcommands');
     const { registerCli } = await import('../cli/index.js');
     await registerCli(program);
+    appDebug('[CLI] Subcommands registered');
   }
 
+  appDebug('[CLI] Parsing command line');
   await program.parseAsync(argv);
+  appDebug('[CLI] Command line parsed');
 }
 
+appDebug('[Boot] Checking shouldRunCli');
 const shouldRunCli = (() => {
   const entry = process.argv[1];
-  if (!entry) return false;
+  appDebug('[Boot] entry=%s', entry);
+  if (!entry) {
+    appDebug('[Boot] No entry, returning false');
+    return false;
+  }
 
   // For compiled binaries, Bun.main will be the binary itself
   if (typeof Bun !== 'undefined' && Bun.main) {
+    appDebug('[Boot] Checking Bun.main');
     try {
       const mainPath = fileURLToPath(Bun.main);
       const modulePath = fileURLToPath(import.meta.url);
-      if (mainPath === modulePath) return true;
-    } catch {
+      appDebug('[Boot] mainPath=%s, modulePath=%s', mainPath, modulePath);
+      if (mainPath === modulePath) {
+        appDebug('[Boot] Bun.main matches, returning true');
+        return true;
+      }
+    } catch (err) {
+      appDebug('[Boot] Bun.main check failed: %s', err);
       // Continue to other checks
     }
   }
 
   try {
     const resolvedEntry = realpathSync(entry);
     const modulePath = realpathSync(fileURLToPath(import.meta.url));
-    return resolvedEntry === modulePath;
-  } catch {
+    appDebug('[Boot] resolvedEntry=%s, modulePath=%s', resolvedEntry, modulePath);
+    const matches = resolvedEntry === modulePath;
+    appDebug('[Boot] realpathSync matches=%s', matches);
+    return matches;
+  } catch (err) {
+    appDebug('[Boot] realpathSync failed: %s, using fallback', err);
     // Fallback: if entry contains 'index' or 'codemachine', run CLI
-    return entry.includes('index') || entry.includes('codemachine');
+    const fallback = entry.includes('index') || entry.includes('codemachine');
+    appDebug('[Boot] fallback result=%s', fallback);
+    return fallback;
   }
 })();
 
+appDebug('[Boot] shouldRunCli=%s', shouldRunCli);
+
 if (shouldRunCli) {
+  appDebug('[Boot] Calling runCodemachineCli()');
   runCodemachineCli().catch((error) => {
+    appDebug('[Boot] runCodemachineCli error: %s', error);
     console.error(error);
     process.exitCode = 1;
   });
+} else {
+  appDebug('[Boot] CLI not run (shouldRunCli=false)');
 }