@tanstack/cta-engine 0.10.0-alpha.6

package/src/add-ons.ts

@@ -0,0 +1,145 @@
+import { readFile } from 'node:fs/promises'
+import { existsSync, readFileSync, readdirSync, statSync } from 'node:fs'
+import { resolve } from 'node:path'
+import chalk from 'chalk'
+import { getTemplatesRoot } from './templates.js'
+
+import { DEFAULT_FRAMEWORK } from './constants.js'
+import type { AddOn, CliOptions, Framework } from './types.js'
+
+function isDirectory(path: string): boolean {
+  return statSync(path).isDirectory()
+}
+
+function findFilesRecursively(path: string, files: Record<string, string>) {
+  const dirFiles = readdirSync(path)
+  for (const file of dirFiles) {
+    const filePath = resolve(path, file)
+    if (isDirectory(filePath)) {
+      findFilesRecursively(filePath, files)
+    } else {
+      files[filePath] = readFileSync(filePath, 'utf-8').toString()
+    }
+  }
+}
+
+export async function getAllAddOns(
+  framework: Framework,
+  template: string,
+): Promise<Array<AddOn>> {
+  const addOns: Array<AddOn> = []
+
+  for (const type of ['add-on', 'example']) {
+    const addOnsBase = resolve(getTemplatesRoot(), framework, type)
+
+    if (!existsSync(addOnsBase)) {
+      continue
+    }
+
+    for (const dir of await readdirSync(addOnsBase).filter((file) =>
+      isDirectory(resolve(addOnsBase, file)),
+    )) {
+      const filePath = resolve(addOnsBase, dir, 'info.json')
+      const fileContent = await readFile(filePath, 'utf-8')
+      const info = JSON.parse(fileContent)
+
+      if (!info.templates.includes(template)) {
+        continue
+      }
+
+      let packageAdditions: Record<string, string> = {}
+      if (existsSync(resolve(addOnsBase, dir, 'package.json'))) {
+        packageAdditions = JSON.parse(
+          await readFile(resolve(addOnsBase, dir, 'package.json'), 'utf-8'),
+        )
+      }
+
+      let readme: string | undefined
+      if (existsSync(resolve(addOnsBase, dir, 'README.md'))) {
+        readme = await readFile(resolve(addOnsBase, dir, 'README.md'), 'utf-8')
+      }
+
+      const absoluteFiles: Record<string, string> = {}
+      const assetsDir = resolve(addOnsBase, dir, 'assets')
+      if (existsSync(assetsDir)) {
+        await findFilesRecursively(assetsDir, absoluteFiles)
+      }
+      const files: Record<string, string> = {}
+      for (const file of Object.keys(absoluteFiles)) {
+        files[file.replace(assetsDir, '.')] = absoluteFiles[file]
+      }
+
+      addOns.push({
+        ...info,
+        id: dir,
+        type,
+        packageAdditions,
+        readme,
+        files,
+        deletedFiles: [],
+      })
+    }
+  }
+
+  return addOns
+}
+
+// Turn the list of chosen add-on IDs into a final list of add-ons by resolving dependencies
+export async function finalizeAddOns(
+  framework: Framework,
+  template: string,
+  chosenAddOnIDs: Array<string>,
+): Promise<Array<AddOn>> {
+  const finalAddOnIDs = new Set(chosenAddOnIDs)
+
+  const addOns = await getAllAddOns(framework, template)
+
+  for (const addOnID of finalAddOnIDs) {
+    let addOn: AddOn | undefined
+    const localAddOn = addOns.find((a) => a.id === addOnID)
+    if (localAddOn) {
+      addOn = loadAddOn(localAddOn)
+    } else if (addOnID.startsWith('http')) {
+      addOn = await loadRemoteAddOn(addOnID)
+      addOns.push(addOn)
+    } else {
+      throw new Error(`Add-on ${addOnID} not found`)
+    }
+
+    for (const dependsOn of addOn.dependsOn || []) {
+      const dep = addOns.find((a) => a.id === dependsOn)
+      if (!dep) {
+        throw new Error(`Dependency ${dependsOn} not found`)
+      }
+      finalAddOnIDs.add(dep.id)
+    }
+  }
+
+  const finalAddOns = [...finalAddOnIDs].map(
+    (id) => addOns.find((a) => a.id === id)!,
+  )
+  return finalAddOns
+}
+
+export async function listAddOns(options: CliOptions) {
+  const mode =
+    options.template === 'file-router' ? 'file-router' : 'code-router'
+  const addOns = await getAllAddOns(
+    options.framework || DEFAULT_FRAMEWORK,
+    mode,
+  )
+  for (const addOn of addOns) {
+    console.log(`${chalk.bold(addOn.id)}: ${addOn.description}`)
+  }
+}
+
+function loadAddOn(addOn: AddOn): AddOn {
+  return addOn
+}
+
+export async function loadRemoteAddOn(url: string): Promise<AddOn> {
+  const response = await fetch(url)
+  const fileContent = await response.json()
+  fileContent.id = url
+  return fileContent
+}

package/src/add.ts

@@ -0,0 +1,184 @@
+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 {
+  createDefaultEnvironment,
+  createMemoryEnvironment,
+} from './environment.js'
+import { createApp } from './create-app.js'
+import { finalizeAddOns } from './add-ons.js'
+import { sortObject } from './utils.js'
+import { readConfigFile, writeConfigFile } from './config-file.js'
+
+import type { PersistedOptions } from './config-file.js'
+
+import type { Options } from './types.js'
+
+function isDirectory(path: string) {
+  return statSync(path).isDirectory()
+}
+
+async function hasPendingGitChanges() {
+  const status = await execaSync('git', ['status', '--porcelain'])
+  return status.stdout.length > 0
+}
+
+async function createOptions(
+  json: PersistedOptions,
+  addOns: Array<string>,
+): Promise<Required<Options>> {
+  return {
+    ...json,
+    tailwind: true,
+    chosenAddOns: await finalizeAddOns(json.framework!, json.mode!, [
+      ...json.existingAddOns,
+      ...addOns,
+    ]),
+  } as Required<Options>
+}
+
+async function runCreateApp(options: Required<Options>) {
+  const { environment, output } = createMemoryEnvironment()
+  await createApp(options, {
+    silent: true,
+    environment,
+    cwd: process.cwd(),
+  })
+  return output
+}
+
+export async function add(
+  addOns: Array<string>,
+  {
+    silent = false,
+  }: {
+    silent?: boolean
+  } = {},
+) {
+  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.`)
+    return
+  }
+
+  if (!silent) {
+    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.`,
+    )
+    return
+  }
+
+  const newOptions = await createOptions(persistedOptions, addOns)
+
+  const output = await runCreateApp(newOptions)
+
+  const overwrittenFiles: Array<string> = []
+  const changedFiles: Array<string> = []
+  const contentMap = new Map<string, string>()
+  for (const file of Object.keys(output.files)) {
+    const relativeFile = file.replace(process.cwd(), '')
+    if (existsSync(file)) {
+      if (!isDirectory(file)) {
+        const contents = (await readFile(file)).toString()
+        if (
+          ['package.json', CONFIG_FILE].includes(basename(file)) ||
+          contents !== output.files[file]
+        ) {
+          overwrittenFiles.push(relativeFile)
+          contentMap.set(relativeFile, output.files[file])
+        }
+      }
+    } else {
+      changedFiles.push(relativeFile)
+      contentMap.set(relativeFile, output.files[file])
+    }
+  }
+
+  if (overwrittenFiles.length > 0 && !silent) {
+    log.warn(
+      `${chalk.yellow('The following will be overwritten:')}\n${overwrittenFiles.join('\n')}`,
+    )
+    const shouldContinue = await confirm({
+      message: 'Do you want to continue?',
+    })
+    if (isCancel(shouldContinue)) {
+      cancel('Operation cancelled.')
+      process.exit(0)
+    }
+  }
+
+  for (const file of [...changedFiles, ...overwrittenFiles]) {
+    const targetFile = `.${file}`
+    const fName = basename(file)
+    const contents = contentMap.get(file)!
+    if (fName === 'package.json') {
+      const currentJson = JSON.parse(
+        (await readFile(resolve(fName), 'utf-8')).toString(),
+      )
+      const newJson = JSON.parse(contents)
+
+      currentJson.scripts = newJson.scripts
+      currentJson.dependencies = sortObject({
+        ...currentJson.dependencies,
+        ...newJson.dependencies,
+      })
+      currentJson.devDependencies = sortObject({
+        ...currentJson.devDependencies,
+        ...newJson.devDependencies,
+      })
+
+      await writeFile(targetFile, JSON.stringify(currentJson, null, 2))
+    } else if (fName !== CONFIG_FILE) {
+      await mkdir(resolve(dirname(targetFile)), { recursive: true })
+      await writeFile(resolve(targetFile), contents)
+    }
+  }
+
+  // Handle commands
+  const originalOutput = await runCreateApp(
+    await createOptions(persistedOptions, []),
+  )
+  const originalCommands = new Set(
+    originalOutput.commands.map((c) => [c.command, ...c.args].join(' ')),
+  )
+  for (const command of output.commands) {
+    const commandString = [command.command, ...command.args].join(' ')
+    if (!originalCommands.has(commandString)) {
+      await execa(command.command, command.args)
+    }
+  }
+  const realEnvironment = createDefaultEnvironment()
+  writeConfigFile(realEnvironment, process.cwd(), newOptions)
+
+  const s = silent ? null : spinner()
+  s?.start(`Installing dependencies via ${newOptions.packageManager}...`)
+  await realEnvironment.execute(
+    newOptions.packageManager,
+    ['install'],
+    resolve(process.cwd()),
+  )
+  s?.stop(`Installed dependencies`)
+
+  if (!silent) {
+    outro('Add-ons added successfully!')
+  }
+}

package/src/cli.ts

@@ -0,0 +1,163 @@
+import { Command, InvalidArgumentError } from 'commander'
+import { intro, log } from '@clack/prompts'
+
+import { createApp } from './create-app.js'
+import { normalizeOptions, promptForOptions } from './options.js'
+import { SUPPORTED_PACKAGE_MANAGERS } from './package-manager.js'
+import { SUPPORTED_TOOLCHAINS } from './toolchain.js'
+
+import runServer from './mcp.js'
+import { listAddOns } from './add-ons.js'
+import { DEFAULT_FRAMEWORK, SUPPORTED_FRAMEWORKS } from './constants.js'
+// import { initAddOn } from './custom-add-on.js'
+
+import { createDefaultEnvironment } from './environment.js'
+// import { add } from './add.js'
+
+import type { PackageManager } from './package-manager.js'
+import type { ToolChain } from './toolchain.js'
+import type { CliOptions, Framework } from './types.js'
+
+export function cli() {
+  const program = new Command()
+
+  program
+    .name('create-tsrouter-app')
+    .description('CLI to create a new TanStack application')
+
+  // program
+  //   .command('add')
+  //   .argument('add-on', 'Name of the add-on (or add-ons separated by commas)')
+  //   .action(async (addOn: string) => {
+  //     await add(addOn.split(',').map((addon) => addon.trim()))
+  //   })
+
+  // program
+  //   .command('update-add-on')
+  //   .description('Create or update an add-on from the current project')
+  //   .action(async () => {
+  //     await initAddOn('add-on')
+  //   })
+
+  // program
+  //   .command('update-overlay')
+  //   .description('Create or update a project overlay from the current project')
+  //   .action(async () => {
+  //     await initAddOn('overlay')
+  //   })
+
+  program // 104 22
+    .argument('[project-name]', 'name of the project')
+    .option('--no-git', 'do not create a git repository')
+    .option('--target-dir <path>', 'the directory to create the project in')
+    .option<Framework>(
+      '--framework <type>',
+      'project framework (solid, react)',
+      (value) => {
+        if (!SUPPORTED_FRAMEWORKS.includes(value as Framework)) {
+          throw new InvalidArgumentError(
+            `Invalid framework: ${value}. Only the following are allowed: ${SUPPORTED_FRAMEWORKS.join(
+              ', ',
+            )}`,
+          )
+        }
+        return value as Framework
+      },
+      DEFAULT_FRAMEWORK,
+    )
+    .option<'typescript' | 'javascript' | 'file-router'>(
+      '--template <type>',
+      'project template (typescript, javascript, file-router)',
+      (value) => {
+        if (
+          value !== 'typescript' &&
+          value !== 'javascript' &&
+          value !== 'file-router'
+        ) {
+          throw new InvalidArgumentError(
+            `Invalid template: ${value}. Only the following are allowed: typescript, javascript, file-router`,
+          )
+        }
+        return value
+      },
+    )
+    .option<PackageManager>(
+      `--package-manager <${SUPPORTED_PACKAGE_MANAGERS.join('|')}>`,
+      `Explicitly tell the CLI to use this package manager`,
+      (value) => {
+        if (!SUPPORTED_PACKAGE_MANAGERS.includes(value as PackageManager)) {
+          throw new InvalidArgumentError(
+            `Invalid package manager: ${value}. The following are allowed: ${SUPPORTED_PACKAGE_MANAGERS.join(
+              ', ',
+            )}`,
+          )
+        }
+        return value as PackageManager
+      },
+    )
+    .option<ToolChain>(
+      `--toolchain <${SUPPORTED_TOOLCHAINS.join('|')}>`,
+      `Explicitly tell the CLI to use this toolchain`,
+      (value) => {
+        if (!SUPPORTED_TOOLCHAINS.includes(value as ToolChain)) {
+          throw new InvalidArgumentError(
+            `Invalid toolchain: ${value}. The following are allowed: ${SUPPORTED_TOOLCHAINS.join(
+              ', ',
+            )}`,
+          )
+        }
+        return value as ToolChain
+      },
+    )
+    .option('--tailwind', 'add Tailwind CSS', false)
+    .option<Array<string> | boolean>(
+      '--add-ons [...add-ons]',
+      'pick from a list of available add-ons (comma separated list)',
+      (value: string) => {
+        let addOns: Array<string> | boolean = !!value
+        if (typeof value === 'string') {
+          addOns = value.split(',').map((addon) => addon.trim())
+        }
+        return addOns
+      },
+    )
+    .option('--list-add-ons', 'list all available add-ons', false)
+    .option('--overlay [url]', 'add an overlay from a URL', false)
+    .option('--mcp', 'run the MCP server', false)
+    .option('--mcp-sse', 'run the MCP server in SSE mode', false)
+    .action(async (projectName: string, options: CliOptions) => {
+      if (options.listAddOns) {
+        await listAddOns(options)
+      } else if (options.mcp || options.mcpSse) {
+        await runServer(!!options.mcpSse)
+      } else {
+        try {
+          const cliOptions = {
+            projectName,
+            ...options,
+          } as CliOptions
+
+          let finalOptions = await normalizeOptions(cliOptions)
+          if (finalOptions) {
+            intro(`Creating a new TanStack app in ${projectName}...`)
+          } else {
+            intro("Let's configure your TanStack application")
+            finalOptions = await promptForOptions(cliOptions)
+          }
+          await createApp(finalOptions, {
+            environment: createDefaultEnvironment(),
+            cwd: options.targetDir || undefined,
+          })
+        } catch (error) {
+          log.error(
+            error instanceof Error
+              ? error.message
+              : 'An unknown error occurred',
+          )
+          process.exit(1)
+        }
+      }
+    })
+
+  program.parse()
+}

package/src/config-file.ts

@@ -0,0 +1,45 @@
+import { readFile } from 'node:fs/promises'
+import { resolve } from 'node:path'
+
+import { CONFIG_FILE } from './constants.js'
+
+import type { Environment, Options } from './types'
+
+export type PersistedOptions = Exclude<
+  Partial<Options>,
+  'addOns' | 'chosenAddOns'
+> & {
+  version: number
+  existingAddOns: Array<string>
+}
+
+export async function writeConfigFile(
+  environment: Environment,
+  targetDir: string,
+  options: Options,
+) {
+  const persistedOptions: PersistedOptions = {
+    ...options,
+    version: 1,
+    existingAddOns: options.chosenAddOns.map((addOn) => addOn.id),
+  }
+  delete persistedOptions.addOns
+  delete persistedOptions.chosenAddOns
+
+  await environment.writeFile(
+    resolve(targetDir, CONFIG_FILE),
+    JSON.stringify(persistedOptions, null, 2),
+  )
+}
+
+export async function readConfigFile(
+  targetDir: string,
+): Promise<PersistedOptions | null> {
+  try {
+    const configFile = resolve(targetDir, CONFIG_FILE)
+    const config = await readFile(configFile, 'utf8')
+    return JSON.parse(config)
+  } catch {
+    return null
+  }
+}

package/src/constants.ts

@@ -0,0 +1,9 @@
+import type { Framework } from './types.js'
+
+export const CODE_ROUTER = 'code-router'
+export const FILE_ROUTER = 'file-router'
+
+export const SUPPORTED_FRAMEWORKS: Array<Framework> = ['solid', 'react']
+export const DEFAULT_FRAMEWORK: Framework = 'react'
+
+export const CONFIG_FILE = '.cta.json'