chore: refactoring the UI out of the engine

Author: jherr

packages/cta-cli/src/cli.ts

@@ -18,6 +18,8 @@ import { runMCPServer } from '@tanstack/cta-mcp'
 
 import { normalizeOptions, promptForOptions } from './options.js'
 
+import { createUIEnvironment } from './ui-environment.js'
+
 import type {
   Framework,
   Mode,
@@ -58,6 +60,8 @@ export function cli({
   forcedMode?: Mode
   forcedAddOns?: Array<string>
 }) {
+  const environment = createUIEnvironment()
+
   const program = new Command()
 
   program.name(name).description(`CLI to create a new ${appName} application`)
@@ -66,21 +70,27 @@ export function cli({
     .command('add')
     .argument('add-on', 'Name of the add-on (or add-ons separated by commas)')
     .action(async (addOn: string) => {
-      await addToApp(addOn.split(',').map((addon) => addon.trim()))
+      await addToApp(
+        addOn.split(',').map((addon) => addon.trim()),
+        {
+          silent: false,
+        },
+        environment,
+      )
     })
 
   program
     .command('update-add-on')
     .description('Create or update an add-on from the current project')
     .action(async () => {
-      await initAddOn('add-on')
+      await initAddOn('add-on', environment)
     })
 
   program
     .command('update-starter')
     .description('Create or update a project starter from the current project')
     .action(async () => {
-      await initAddOn('starter')
+      await initAddOn('starter', environment)
     })
 
   program.argument('[project-name]', 'name of the project')

packages/cta-cli/src/ui-environment.ts

@@ -0,0 +1,41 @@
+import { cancel, confirm, intro, isCancel, log, outro } from '@clack/prompts'
+import chalk from 'chalk'
+
+import { createDefaultEnvironment } from '@tanstack/cta-engine'
+
+import type { Environment } from '@tanstack/cta-engine'
+
+export function createUIEnvironment(): Environment {
+  const defaultEnvironment = createDefaultEnvironment()
+
+  return {
+    ...defaultEnvironment,
+    intro: (message: string) => {
+      intro(message)
+    },
+    outro: (message: string) => {
+      outro(message)
+    },
+    info: (title?: string, message?: string) => {
+      log.info(
+        `${title ? chalk.red(title) : ''}${message ? chalk.green(message) : ''}`,
+      )
+    },
+    error: (title?: string, message?: string) => {
+      log.error(`${title ? `${title}: ` : ''}${message}`)
+    },
+    warn: (title?: string, message?: string) => {
+      log.warn(`${title ? `${title}: ` : ''}${message}`)
+    },
+    confirm: async (message: string) => {
+      const shouldContinue = await confirm({
+        message,
+      })
+      if (isCancel(shouldContinue)) {
+        cancel('Operation cancelled.')
+        process.exit(0)
+      }
+      return shouldContinue
+    },
+  }
+}

packages/cta-engine/package.json

@@ -32,8 +32,6 @@
   "license": "MIT",
   "packageManager": "pnpm@9.15.5",
   "dependencies": {
-    "@clack/prompts": "^0.10.0",
-    "chalk": "^5.4.1",
     "ejs": "^3.1.10",
     "execa": "^9.5.2",
     "memfs": "^4.17.0",

packages/cta-engine/src/add.ts

@@ -1,17 +1,7 @@
 import { mkdir, readFile, writeFile } from 'node:fs/promises'
 import { existsSync, statSync } from 'node:fs'
 import { basename, dirname, resolve } from 'node:path'
-import chalk from 'chalk'
 import { execa, execaSync } from 'execa'
-import {
-  cancel,
-  confirm,
-  intro,
-  isCancel,
-  log,
-  outro,
-  spinner,
-} from '@clack/prompts'
 
 import { CONFIG_FILE } from './constants.js'
 import {
@@ -25,7 +15,7 @@ import { readConfigFile, writeConfigFile } from './config-file.js'
 
 import type { PersistedOptions } from './config-file.js'
 
-import type { Framework, Options } from './types.js'
+import type { Environment, Framework, Options } from './types.js'
 
 function isDirectory(path: string) {
   return statSync(path).isDirectory()
@@ -69,22 +59,25 @@ export async function addToApp(
   }: {
     silent?: boolean
   } = {},
+  environment: Environment,
 ) {
   const persistedOptions = await readConfigFile(process.cwd())
   if (!persistedOptions) {
-    console.error(`${chalk.red('There is no .cta.json file in your project.')}
-
-This is probably because this was created with an older version of create-tsrouter-app.`)
+    environment.error(
+      'There is no .cta.json file in your project.',
+      'This is probably because this was created with an older version of create-tsrouter-app.',
+    )
     return
   }
 
   if (!silent) {
-    intro(`Adding ${addOns.join(', ')} to the project...`)
+    environment.intro(`Adding ${addOns.join(', ')} to the project...`)
   }
 
   if (await hasPendingGitChanges()) {
-    log.error(
-      `${chalk.red('You have pending git changes.')} Please commit or stash them before adding add-ons.`,
+    environment.error(
+      'You have pending git changes.',
+      'Please commit or stash them before adding add-ons.',
     )
     return
   }
@@ -116,14 +109,12 @@ This is probably because this was created with an older version of create-tsrout
   }
 
   if (overwrittenFiles.length > 0 && !silent) {
-    log.warn(
-      `${chalk.yellow('The following will be overwritten:')}\n${overwrittenFiles.join('\n')}`,
+    environment.warn(
+      'The following will be overwritten:',
+      overwrittenFiles.join('\n'),
     )
-    const shouldContinue = await confirm({
-      message: 'Do you want to continue?',
-    })
-    if (isCancel(shouldContinue)) {
-      cancel('Operation cancelled.')
+    const shouldContinue = await environment.confirm('Do you want to continue?')
+    if (!shouldContinue) {
       process.exit(0)
     }
   }
@@ -171,7 +162,7 @@ This is probably because this was created with an older version of create-tsrout
   const realEnvironment = createDefaultEnvironment()
   writeConfigFile(realEnvironment, process.cwd(), newOptions)
 
-  const s = silent ? null : spinner()
+  const s = silent ? null : environment.spinner()
   s?.start(`Installing dependencies via ${newOptions.packageManager}...`)
   await realEnvironment.execute(
     newOptions.packageManager,
@@ -181,6 +172,6 @@ This is probably because this was created with an older version of create-tsrout
   s?.stop(`Installed dependencies`)
 
   if (!silent) {
-    outro('Add-ons added successfully!')
+    environment.outro('Add-ons added successfully!')
   }
 }

packages/cta-engine/src/create-app.ts

@@ -1,8 +1,6 @@
 import { basename, dirname, resolve } from 'node:path'
-import { log, outro, spinner } from '@clack/prompts'
 import { render } from 'ejs'
 import { format } from 'prettier'
-import chalk from 'chalk'
 
 import { getTemplatesRoot } from './templates.js'
 import { CODE_ROUTER, FILE_ROUTER } from './constants.js'
@@ -119,8 +117,7 @@ function createTemplateFile(
     try {
       content = render(content, templateValues)
     } catch (error) {
-      console.error(chalk.red(`EJS error in file ${file}`))
-      console.error(error)
+      environment.error(`EJS error in file ${file}`, error?.toString())
       process.exit(1)
     }
     const target = targetFileName ?? file.replace('.ejs', '')
@@ -338,7 +335,7 @@ export async function createApp(
 
     if (environment.exists(targetDir)) {
       if (!silent) {
-        log.error(`Directory "${options.projectName}" already exists`)
+        environment.error(`Directory "${options.projectName}" already exists`)
       }
       return
     }
@@ -507,7 +504,7 @@ export async function createApp(
   )
 
   // Copy all the asset files from the addons
-  const s = silent ? null : spinner()
+  const s = silent ? null : environment.spinner()
   for (const type of ['add-on', 'example']) {
     for (const phase of ['setup', 'add-on', 'example']) {
       for (const addOn of options.chosenAddOns.filter(
@@ -732,7 +729,10 @@ export async function createApp(
 
   if (warnings.length > 0) {
     if (!silent) {
-      log.warn(chalk.red(warnings.join('\n')))
+      environment.warn(
+        'The following will be overwritten:',
+        warnings.join('\n'),
+      )
     }
   }
 
@@ -782,7 +782,7 @@ export async function createApp(
   if (environment.getErrors().length) {
     errorStatement = `
 
-${chalk.red('Errors were encountered during this process:')}
+Errors were encountered during this process:
 
 ${environment.getErrors().join('\n')}`
   }
@@ -793,7 +793,7 @@ ${environment.getErrors().join('\n')}`
       startCommand = `deno ${isAddOnEnabled('start') ? 'task dev' : 'start'}`
     }
 
-    outro(`Your ${appName} app is ready in '${basename(targetDir)}'.
+    environment.outro(`Your ${appName} app is ready in '${basename(targetDir)}'.
 
 Use the following commands to start your app:
 % cd ${options.projectName}

packages/cta-engine/src/custom-add-on.ts

@@ -1,15 +1,14 @@
 import { readFile, readdir } from 'node:fs/promises'
 import { existsSync, mkdirSync, writeFileSync } from 'node:fs'
 import { basename, dirname, resolve } from 'node:path'
-import chalk from 'chalk'
 
 import { createMemoryEnvironment } from './environment.js'
 import { createApp } from './create-app.js'
 import { readConfigFile } from './config-file.js'
 import { finalizeAddOns } from './add-ons.js'
 import { readFileHelper } from './file-helper.js'
 
-import type { Framework, Options } from './types.js'
+import type { Environment, Framework, Options } from './types.js'
 import type { PersistedOptions } from './config-file.js'
 
 type AddOnMode = 'add-on' | 'starter'
@@ -163,32 +162,36 @@ async function compareFiles(
   }
 }
 
-export async function initAddOn(mode: AddOnMode) {
+export async function initAddOn(mode: AddOnMode, environment: Environment) {
   const persistedOptions = await readConfigFile(process.cwd())
   if (!persistedOptions) {
-    console.error(`${chalk.red('There is no .cta.json file in your project.')}
-
-This is probably because this was created with an older version of create-tsrouter-app.`)
+    environment.error(
+      'There is no .cta.json file in your project.',
+      `This is probably because this was created with an older version of create-tsrouter-app.`,
+    )
     return
   }
 
   if (mode === 'add-on') {
     if (persistedOptions.mode !== 'file-router') {
-      console.error(`${chalk.red('This project is not using file-router mode.')}
-
-To create an add-on, the project must be created with the file-router mode.`)
+      environment.error(
+        'This project is not using file-router mode.',
+        'To create an add-on, the project must be created with the file-router mode.',
+      )
       return
     }
     if (!persistedOptions.tailwind) {
-      console.error(`${chalk.red('This project is not using Tailwind CSS.')}
-
-To create an add-on, the project must be created with Tailwind CSS.`)
+      environment.error(
+        'This project is not using Tailwind CSS.',
+        'To create an add-on, the project must be created with Tailwind CSS.',
+      )
       return
     }
     if (!persistedOptions.typescript) {
-      console.error(`${chalk.red('This project is not using TypeScript.')}
-
-To create an add-on, the project must be created with TypeScript.`)
+      environment.error(
+        'This project is not using TypeScript.',
+        'To create an add-on, the project must be created with TypeScript.',
+      )
       return
     }
   }

packages/cta-engine/src/environment.ts

@@ -57,6 +57,17 @@ export function createDefaultEnvironment(): Environment {
       const stat = statSync(path)
       return stat.isDirectory()
     },
+
+    intro: () => {},
+    outro: () => {},
+    info: () => {},
+    error: () => {},
+    warn: () => {},
+    confirm: () => Promise.resolve(true),
+    spinner: () => ({
+      start: () => {},
+      stop: () => {},
+    }),
   }
 }
 

packages/cta-engine/src/index.ts

@@ -21,6 +21,7 @@ export { SUPPORTED_TOOLCHAINS, DEFAULT_TOOLCHAIN } from './toolchain.js'
 
 export type {
   AddOn,
+  Environment,
   Framework,
   Mode,
   Options,

packages/cta-engine/src/types.ts

@@ -23,11 +23,13 @@ export interface Options {
   starter?: AddOn | undefined
 }
 
-export type Environment = {
+type ProjectEnvironment = {
   startRun: () => void
   finishRun: () => void
   getErrors: () => Array<string>
+}
 
+type FileEnvironment = {
   appendFile: (path: string, contents: string) => Promise<void>
   copyFile: (from: string, to: string) => Promise<void>
   writeFile: (path: string, contents: string) => Promise<void>
@@ -40,6 +42,23 @@ export type Environment = {
   isDirectory: (path: string) => boolean
 }
 
+type UIEnvironment = {
+  intro: (message: string) => void
+  outro: (message: string) => void
+
+  info: (title?: string, message?: string) => void
+  error: (title?: string, message?: string) => void
+  warn: (title?: string, message?: string) => void
+
+  spinner: () => {
+    start: (message: string) => void
+    stop: (message: string) => void
+  }
+  confirm: (message: string) => Promise<boolean>
+}
+
+export type Environment = ProjectEnvironment & FileEnvironment & UIEnvironment
+
 type BooleanVariable = {
   name: string
   default: boolean