refactor: extract renderTUI into src/cli/tui/render-tui.ts

Break the circular import between cli.ts and command handlers by moving
renderTUI, RenderTUIOptions, and alt-screen helpers into their own module.
Command handlers now import from tui/render-tui instead of ../../cli.

Author: Hweinstock

src/cli/cli.ts

@@ -26,145 +26,21 @@ import { registerTraces } from './commands/traces';
 import { registerUpdate } from './commands/update';
 import { registerValidate } from './commands/validate';
 import { PACKAGE_VERSION } from './constants';
+import { printPostCommandNotices, printTelemetryNotice } from './notices';
 import { ALL_PRIMITIVES } from './primitives';
 import { TelemetryClientAccessor } from './telemetry';
-import { App, type InitialRoute } from './tui/App';
+import { renderTUI, setupAltScreenCleanup } from './tui';
 import { LayoutProvider } from './tui/context';
 import { COMMAND_DESCRIPTIONS } from './tui/copy';
-import { clearExitAction, getExitAction } from './tui/exit-action';
 import { clearExitMessage, getExitMessage } from './tui/exit-message';
 import { requireTTY } from './tui/guards';
 import { CommandListScreen } from './tui/screens/home';
 import { getCommandsForUI } from './tui/utils';
-import { type UpdateCheckResult, checkForUpdate, printUpdateNotification } from './update-notifier';
+import { checkForUpdate } from './update-notifier';
 import { Command } from '@commander-js/extra-typings';
 import { render } from 'ink';
 import React from 'react';
 
-// ANSI escape sequences
-const ENTER_ALT_SCREEN = '\x1B[?1049h\x1B[H';
-const EXIT_ALT_SCREEN = '\x1B[?1049l';
-const SHOW_CURSOR = '\x1B[?25h';
-
-// Track if we're in alternate screen mode
-let inAltScreen = false;
-
-/**
- * Global terminal cleanup - ensures cursor is always restored on exit.
- * Registered once at startup, catches all exit scenarios.
- */
-function setupGlobalCleanup() {
-  const cleanup = () => {
-    if (inAltScreen) {
-      process.stdout.write(EXIT_ALT_SCREEN);
-    }
-    process.stdout.write(SHOW_CURSOR);
-  };
-
-  process.on('exit', cleanup);
-  process.on('SIGINT', () => {
-    cleanup();
-    process.exit(0);
-  });
-  process.on('SIGTERM', () => {
-    cleanup();
-    process.exit(0);
-  });
-}
-
-function printTelemetryNotice(): void {
-  const yellow = '\x1b[33m';
-  const reset = '\x1b[0m';
-  process.stderr.write(
-    [
-      '',
-      `${yellow}The AgentCore CLI will soon begin collecting aggregated, anonymous usage`,
-      'analytics to help improve the tool.',
-      'To opt out:          agentcore telemetry disable',
-      `To learn more:       agentcore telemetry --help${reset}`,
-      '',
-      '',
-    ].join('\n')
-  );
-}
-
-function printPostCommandNotices(isFirstRun: boolean, updateCheck: Promise<UpdateCheckResult | null>): Promise<void> {
-  if (isFirstRun) {
-    printTelemetryNotice();
-  }
-  return updateCheck.then(result => {
-    if (result?.updateAvailable) {
-      printUpdateNotification(result);
-    }
-  });
-}
-
-export interface RenderTUIOptions {
-  /** Route to navigate to on launch. If omitted, shows the default home/help screen. */
-  initialRoute?: InitialRoute;
-  /** Promise that resolves with update check result. Used to print update notifications on exit. Default: Promise.resolve(null) */
-  updateCheck?: Promise<UpdateCheckResult | null>;
-  /** Whether this is the first time the CLI has been run. Shows telemetry notice on exit. Default: false */
-  isFirstRun?: boolean;
-  /** Control whether TUI is rendered inline or in alternate screen. Default: true */
-  enterAltScreen?: boolean;
-  /** Behavior when pressing escape/back. 'help' navigates to the help screen, 'exit' exits the app. Default: 'help' */
-  actionOnBack?: 'help' | 'exit';
-  /** Whether the TUI is running in full interactive mode. When false, screens auto-exit after success. Default: true */
-  isInteractive?: boolean;
-}
-
-/**
- * Render the TUI in alternate screen buffer mode.
- * This is the entrypoint for TUI operations
- */
-export async function renderTUI(options: RenderTUIOptions = {}) {
-  const {
-    initialRoute,
-    updateCheck = Promise.resolve(null),
-    isFirstRun = false,
-    enterAltScreen = true,
-    actionOnBack = 'help',
-    isInteractive = true,
-  } = options;
-  await TelemetryClientAccessor.init(initialRoute?.name ?? 'tui', 'tui');
-  if (enterAltScreen) {
-    inAltScreen = true;
-    process.stdout.write(ENTER_ALT_SCREEN);
-  }
-
-  const { waitUntilExit } = render(React.createElement(App, { initialRoute, actionOnBack, isInteractive }));
-
-  await waitUntilExit();
-
-  if (inAltScreen) {
-    inAltScreen = false;
-    process.stdout.write(EXIT_ALT_SCREEN);
-    process.stdout.write(SHOW_CURSOR);
-  }
-
-  await TelemetryClientAccessor.shutdown();
-
-  // Check if the TUI requested a post-exit action (e.g., launch browser dev mode)
-  const action = getExitAction();
-  clearExitAction();
-
-  if (action?.type === 'dev') {
-    const { launchBrowserDev } = await import('./commands/dev/browser-mode');
-    await launchBrowserDev();
-    return;
-  }
-
-  // Print any exit message set by screens (e.g., after successful project creation)
-  const exitMessage = getExitMessage();
-  if (exitMessage) {
-    console.log(exitMessage);
-    clearExitMessage();
-  }
-
-  await printPostCommandNotices(isFirstRun, updateCheck);
-}
-
 function renderHelp(program: Command): void {
   const commands = getCommandsForUI(program);
   render(React.createElement(LayoutProvider, null, React.createElement(CommandListScreen, { commands })));
@@ -245,7 +121,7 @@ export function registerCommands(program: Command) {
 
 export const main = async (argv: string[]) => {
   // Register global cleanup handlers once at startup
-  setupGlobalCleanup();
+  setupAltScreenCleanup();
 
   // Generate installationId on first run and show telemetry notice
   const { created: isFirstRun } = await getOrCreateInstallationId();

src/cli/commands/add/command.tsx

@@ -1,6 +1,6 @@
-import { renderTUI } from '../../cli';
 import { COMMAND_DESCRIPTIONS } from '../../tui/copy';
 import { requireProject, requireTTY } from '../../tui/guards';
+import { renderTUI } from '../../tui';
 import type { Command } from '@commander-js/extra-typings';
 
 export function registerAdd(program: Command): Command {

src/cli/commands/create/command.tsx

@@ -8,7 +8,6 @@ import type {
   TargetLanguage,
 } from '../../../schema';
 import { LIFECYCLE_TIMEOUT_MAX, LIFECYCLE_TIMEOUT_MIN } from '../../../schema';
-import { renderTUI } from '../../cli';
 import { getErrorMessage } from '../../errors';
 import { runCliCommand } from '../../telemetry/cli-command-run.js';
 import {
@@ -24,6 +23,7 @@ import {
 } from '../../telemetry/schemas/common-shapes.js';
 import { COMMAND_DESCRIPTIONS } from '../../tui/copy';
 import { requireTTY } from '../../tui/guards';
+import { renderTUI } from '../../tui';
 import { parseCommaSeparatedList } from '../shared/vpc-utils';
 import { type ProgressCallback, createProject, createProjectWithAgent, getDryRunInfo } from './action';
 import type { CreateOptions } from './types';

src/cli/commands/deploy/command.tsx

@@ -1,9 +1,9 @@
 import { ConfigIO, serializeResult } from '../../../lib';
-import { renderTUI } from '../../cli';
 import { getErrorMessage } from '../../errors';
 import { withCommandRunTelemetry } from '../../telemetry/cli-command-run.js';
 import { COMMAND_DESCRIPTIONS } from '../../tui/copy';
 import { requireProject, requireTTY } from '../../tui/guards';
+import { renderTUI } from '../../tui';
 import { handleDeploy } from './actions';
 import type { DeployOptions, DeployResult } from './types';
 import { DEFAULT_DEPLOY_ATTRS, computeDeployAttrs } from './utils';

src/cli/commands/invoke/command.tsx

@@ -1,10 +1,10 @@
 import { ValidationError, serializeResult } from '../../../lib';
-import { renderTUI } from '../../cli';
 import { getErrorMessage } from '../../errors';
 import { withCommandRunTelemetry } from '../../telemetry/cli-command-run.js';
 import { AgentProtocol, AuthType, standardize } from '../../telemetry/schemas/common-shapes.js';
 import { COMMAND_DESCRIPTIONS } from '../../tui/copy';
 import { requireProject, requireTTY } from '../../tui/guards';
+import { renderTUI } from '../../tui';
 import { parseHeaderFlags } from '../shared/header-utils';
 import { type InvokeContext, handleInvoke, loadInvokeConfig } from './action';
 import { resolvePrompt } from './resolve-prompt';

src/cli/commands/remove/command.tsx

@@ -1,9 +1,9 @@
 import { ConfigIO, serializeResult, toError } from '../../../lib';
-import { renderTUI } from '../../cli';
 import { getErrorMessage } from '../../errors';
 import { runCliCommand } from '../../telemetry/cli-command-run.js';
 import { COMMAND_DESCRIPTIONS } from '../../tui/copy';
 import { requireProject, requireTTY } from '../../tui/guards';
+import { renderTUI } from '../../tui';
 import type { RemoveAllOptions, RemoveResult } from './types';
 import { validateRemoveAllOptions } from './validate';
 import type { Command } from '@commander-js/extra-typings';

src/cli/notices.ts

@@ -0,0 +1,31 @@
+import { type UpdateCheckResult, printUpdateNotification } from './update-notifier';
+
+export function printTelemetryNotice(): void {
+  const yellow = '\x1b[33m';
+  const reset = '\x1b[0m';
+  process.stderr.write(
+    [
+      '',
+      `${yellow}The AgentCore CLI will soon begin collecting aggregated, anonymous usage`,
+      'analytics to help improve the tool.',
+      'To opt out:          agentcore telemetry disable',
+      `To learn more:       agentcore telemetry --help${reset}`,
+      '',
+      '',
+    ].join('\n')
+  );
+}
+
+export function printPostCommandNotices(
+  isFirstRun: boolean,
+  updateCheck: Promise<UpdateCheckResult | null>
+): Promise<void> {
+  if (isFirstRun) {
+    printTelemetryNotice();
+  }
+  return updateCheck.then(result => {
+    if (result?.updateAvailable) {
+      printUpdateNotification(result);
+    }
+  });
+}

src/cli/tui/App.tsx

@@ -28,8 +28,7 @@ import { getCommandsForUI } from './utils/commands';
 import { useApp } from 'ink';
 import React, { useState } from 'react';
 
-// Capture cwd once at app initialization
-const cwd = getWorkingDirectory();
+// cwd is captured inside AppContent to avoid calling getWorkingDirectory at import time
 
 type Route =
   | { name: 'home' }
@@ -78,6 +77,7 @@ function AppContent({
   isInteractive?: boolean;
 }) {
   const { exit } = useApp();
+  const cwd = getWorkingDirectory();
   // Start on help screen if project exists (show commands), otherwise home (show Quick Start)
   const inProject = projectExists();
   const wrongDirProjectRoot = getProjectRootMismatch();

src/cli/tui/index.ts

@@ -1,5 +1,6 @@
 export { App } from './App';
 export * from './components';
 export * from './hooks';
+export * from './render';
 export * from './screens';
 export * from './utils';

src/cli/tui/render.ts

@@ -0,0 +1,103 @@
+import { printPostCommandNotices } from '../notices';
+import { TelemetryClientAccessor } from '../telemetry';
+import { type UpdateCheckResult } from '../update-notifier';
+import { App, type InitialRoute } from './App';
+import { clearExitAction, getExitAction } from './exit-action';
+import { clearExitMessage, getExitMessage } from './exit-message';
+import { render } from 'ink';
+import React from 'react';
+
+const ENTER_ALT_SCREEN = '\x1B[?1049h\x1B[H';
+const EXIT_ALT_SCREEN = '\x1B[?1049l';
+const SHOW_CURSOR = '\x1B[?25h';
+
+let inAltScreen = false;
+
+export interface RenderTUIOptions {
+  /** Route to navigate to on launch. If omitted, shows the default home/help screen. */
+  initialRoute?: InitialRoute;
+  /** Promise that resolves with update check result. Used to print update notifications on exit. Default: Promise.resolve(null) */
+  updateCheck?: Promise<UpdateCheckResult | null>;
+  /** Whether this is the first time the CLI has been run. Shows telemetry notice on exit. Default: false */
+  isFirstRun?: boolean;
+  /** Control whether TUI is rendered inline or in alternate screen. Default: true */
+  enterAltScreen?: boolean;
+  /** Behavior when pressing escape/back. 'help' navigates to the help screen, 'exit' exits the app. Default: 'help' */
+  actionOnBack?: 'help' | 'exit';
+  /** Whether the TUI is running in full interactive mode. When false, screens auto-exit after success. Default: true */
+  isInteractive?: boolean;
+}
+
+/**
+ * Render the TUI in alternate screen buffer mode.
+ * This is the entrypoint for all TUI operations.
+ */
+export async function renderTUI(options: RenderTUIOptions = {}) {
+  const {
+    initialRoute,
+    updateCheck = Promise.resolve(null),
+    isFirstRun = false,
+    enterAltScreen: useAltScreen = true,
+    actionOnBack = 'help',
+    isInteractive = true,
+  } = options;
+  await TelemetryClientAccessor.init(initialRoute?.name ?? 'tui', 'tui');
+  if (useAltScreen) {
+    inAltScreen = true;
+    process.stdout.write(ENTER_ALT_SCREEN);
+  }
+
+  const { waitUntilExit } = render(React.createElement(App, { initialRoute, actionOnBack, isInteractive }));
+
+  await waitUntilExit();
+
+  if (inAltScreen) {
+    inAltScreen = false;
+    process.stdout.write(EXIT_ALT_SCREEN);
+    process.stdout.write(SHOW_CURSOR);
+  }
+
+  await TelemetryClientAccessor.shutdown();
+
+  // Check if the TUI requested a post-exit action (e.g., launch browser dev mode)
+  const action = getExitAction();
+  clearExitAction();
+
+  if (action?.type === 'dev') {
+    const { launchBrowserDev } = await import('../commands/dev/browser-mode');
+    await launchBrowserDev();
+    return;
+  }
+
+  // Print any exit message set by screens (e.g., after successful project creation)
+  const exitMessage = getExitMessage();
+  if (exitMessage) {
+    console.log(exitMessage);
+    clearExitMessage();
+  }
+
+  await printPostCommandNotices(isFirstRun, updateCheck);
+}
+
+/**
+ * Cleanup handler for alternate screen on process signals.
+ * Call once at startup.
+ */
+export function setupAltScreenCleanup() {
+  const cleanup = () => {
+    if (inAltScreen) {
+      process.stdout.write(EXIT_ALT_SCREEN);
+    }
+    process.stdout.write(SHOW_CURSOR);
+  };
+
+  process.on('exit', cleanup);
+  process.on('SIGINT', () => {
+    cleanup();
+    process.exit(0);
+  });
+  process.on('SIGTERM', () => {
+    cleanup();
+    process.exit(0);
+  });
+}