@tanstack/cta-engine 0.10.0-alpha.21 → 0.10.0-alpha.25

package/dist/types/utils.d.ts

@@ -1,6 +1 @@
 export declare function sortObject(obj: Record<string, string>): Record<string, string>;
-export declare function jsSafeName(name: string): string;
-export declare function formatCommand({ command, args, }: {
-    command: string;
-    args: Array<string>;
-}): string;

package/dist/types.js

@@ -1,65 +1 @@
-import z from 'zod';
-export const AddOnBaseSchema = z.object({
-    id: z.string(),
-    name: z.string(),
-    description: z.string(),
-    author: z.string().optional(),
-    version: z.string().optional(),
-    link: z.string().optional(),
-    license: z.string().optional(),
-    warning: z.string().optional(),
-    type: z.enum(['add-on', 'example', 'starter', 'toolchain']),
-    command: z
-        .object({
-        command: z.string(),
-        args: z.array(z.string()).optional(),
-    })
-        .optional(),
-    routes: z
-        .array(z.object({
-        url: z.string().optional(),
-        name: z.string().optional(),
-        path: z.string(),
-        jsName: z.string(),
-    }))
-        .optional(),
-    packageAdditions: z
-        .object({
-        dependencies: z.record(z.string(), z.string()).optional(),
-        devDependencies: z.record(z.string(), z.string()).optional(),
-        scripts: z.record(z.string(), z.string()).optional(),
-    })
-        .optional(),
-    shadcnComponents: z.array(z.string()).optional(),
-    dependsOn: z.array(z.string()).optional(),
-    smallLogo: z.string().optional(),
-    logo: z.string().optional(),
-    addOnSpecialSteps: z.array(z.string()).optional(),
-    createSpecialSteps: z.array(z.string()).optional(),
-});
-export const StarterSchema = AddOnBaseSchema.extend({
-    framework: z.string(),
-    mode: z.string(),
-    typescript: z.boolean(),
-    tailwind: z.boolean(),
-    banner: z.string().optional(),
-});
-export const StarterCompiledSchema = StarterSchema.extend({
-    files: z.record(z.string(), z.string()),
-    deletedFiles: z.array(z.string()),
-});
-export const IntegrationSchema = z.object({
-    type: z.string(),
-    path: z.string(),
-    jsName: z.string(),
-});
-export const AddOnInfoSchema = AddOnBaseSchema.extend({
-    modes: z.array(z.string()),
-    integrations: z.array(IntegrationSchema).optional(),
-    phase: z.enum(['setup', 'add-on']),
-    readme: z.string().optional(),
-});
-export const AddOnCompiledSchema = AddOnInfoSchema.extend({
-    files: z.record(z.string(), z.string()),
-    deletedFiles: z.array(z.string()),
-});
+export {};

package/dist/utils.js

@@ -6,12 +6,3 @@ export function sortObject(obj) {
         return acc;
     }, {});
 }
-export function jsSafeName(name) {
-    return name
-        .split(/[^a-zA-Z0-9]/)
-        .map((part) => part.charAt(0).toUpperCase() + part.slice(1))
-        .join('');
-}
-export function formatCommand({ command, args, }) {
-    return `${command} ${args.join(' ')}`.trim();
-}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tanstack/cta-engine",
-  "version": "0.10.0-alpha.21",
+  "version": "0.10.0-alpha.25",
   "description": "Tanstack Application Builder Engine",
   "type": "module",
   "main": "./dist/index.js",
@@ -15,32 +15,35 @@
     "url": "https://github.com/sponsors/tannerlinsley"
   },
   "keywords": [
+    "react",
     "tanstack",
     "router",
-    "create-tsrouter-app"
+    "create-react-app"
   ],
   "author": "Jack Herrington <jherr@pobox.com>",
   "license": "MIT",
   "dependencies": {
+    "@clack/prompts": "^0.10.0",
+    "@modelcontextprotocol/sdk": "^1.6.0",
+    "chalk": "^5.4.1",
+    "commander": "^13.1.0",
     "ejs": "^3.1.10",
     "execa": "^9.5.2",
-    "ignore": "^7.0.3",
+    "express": "^4.21.2",
     "memfs": "^4.17.0",
-    "parse-gitignore": "^2.0.0",
     "prettier": "^3.5.0",
-    "rimraf": "^6.0.1",
     "zod": "^3.24.2"
   },
   "devDependencies": {
     "@tanstack/config": "^0.16.2",
     "@types/ejs": "^3.1.5",
+    "@types/express": "^5.0.0",
     "@types/node": "^22.13.4",
-    "@types/parse-gitignore": "^1.0.2",
-    "@vitest/coverage-v8": "3.1.1",
     "eslint": "^9.20.0",
+    "eslint-plugin-react-hooks": "^5.1.0",
+    "eslint-plugin-unused-imports": "^4.1.4",
     "typescript": "^5.6.3",
-    "vitest": "^3.0.8",
-    "vitest-fetch-mock": "^0.4.5"
+    "vitest": "^3.0.8"
   },
   "scripts": {}
 }

package/src/add-ons.ts

@@ -1,20 +1,100 @@
-import { loadRemoteAddOn } from './custom-add-ons/add-on.js'
+import { readFile } from 'node:fs/promises'
+import { existsSync, readdirSync, statSync } from 'node:fs'
+import { resolve } from 'node:path'
+import chalk from 'chalk'
 
-import type { AddOn, Framework, Mode } from './types.js'
+import { getTemplatesRoot } from './templates.js'
+import { DEFAULT_FRAMEWORK } from './constants.js'
+import { readFileHelper } from './file-helper.js'
 
-export function getAllAddOns(framework: Framework, mode: Mode): Array<AddOn> {
-  return framework.getAddOns().filter((a) => a.modes.includes(mode))
+import type { AddOn, CliOptions, Framework, TemplateOptions } 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] = readFileHelper(filePath)
+    }
+  }
+}
+
+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,
-  mode: Mode,
+  template: string,
   chosenAddOnIDs: Array<string>,
 ): Promise<Array<AddOn>> {
   const finalAddOnIDs = new Set(chosenAddOnIDs)
 
-  const addOns = getAllAddOns(framework, mode)
+  const addOns = await getAllAddOns(framework, template)
 
   for (const addOnID of finalAddOnIDs) {
     let addOn: AddOn | undefined
@@ -40,10 +120,46 @@ export async function finalizeAddOns(
   const finalAddOns = [...finalAddOnIDs].map(
     (id) => addOns.find((a) => a.id === id)!,
   )
-
   return finalAddOns
 }
 
+export async function listAddOns(
+  options: CliOptions,
+  {
+    forcedMode,
+    forcedAddOns = [],
+  }: {
+    forcedMode?: TemplateOptions
+    forcedAddOns?: Array<string>
+  },
+) {
+  let mode = forcedMode
+  if (!mode) {
+    if (options.template) {
+      mode =
+        options.template === 'file-router'
+          ? 'file-router'
+          : ('code-router' as TemplateOptions)
+    } else {
+      mode = 'code-router' as TemplateOptions
+    }
+  }
+  const addOns = await getAllAddOns(
+    options.framework || DEFAULT_FRAMEWORK,
+    mode,
+  )
+  for (const addOn of addOns.filter((a) => !forcedAddOns.includes(a.id))) {
+    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,186 @@
+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 { Framework, 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 as Framework,
+      json.mode as string,
+      [...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(),
+    name: 'create-tsrouter-app',
+  })
+  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,210 @@
+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,
+  Mode,
+  Options,
+  TemplateOptions,
+} from './types.js'
+
+export function cli({
+  name,
+  appName,
+  forcedMode,
+  forcedAddOns,
+}: {
+  name: string
+  appName: string
+  forcedMode?: Mode
+  forcedAddOns?: Array<string>
+}) {
+  const program = new Command()
+
+  program.name(name).description(`CLI to create a new ${appName} 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.argument('[project-name]', 'name of the project')
+
+  if (!forcedMode) {
+    program.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
+      },
+    )
+  }
+  program
+    .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('--overlay [url]', 'add an overlay from a URL', false)
+    .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('--interactive', 'interactive mode', false)
+    .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('--no-git', 'do not create a git repository')
+    .option(
+      '--target-dir <path>',
+      'the target directory for the application root',
+    )
+    .option('--mcp', 'run the MCP server', false)
+    .option('--mcp-sse', 'run the MCP server in SSE mode', false)
+
+  program.action(async (projectName: string, options: CliOptions) => {
+    if (options.listAddOns) {
+      await listAddOns(options, {
+        forcedMode: forcedMode as TemplateOptions,
+        forcedAddOns,
+      })
+    } else if (options.mcp || options.mcpSse) {
+      await runServer(!!options.mcpSse, {
+        forcedMode: forcedMode as TemplateOptions,
+        forcedAddOns,
+        appName,
+      })
+    } else {
+      try {
+        const cliOptions = {
+          projectName,
+          ...options,
+        } as CliOptions
+
+        if (forcedMode) {
+          cliOptions.template = forcedMode as TemplateOptions
+        }
+
+        let finalOptions: Options | undefined
+        if (cliOptions.interactive) {
+          cliOptions.addOns = true
+        } else {
+          finalOptions = await normalizeOptions(
+            cliOptions,
+            forcedMode,
+            forcedAddOns,
+          )
+        }
+
+        if (finalOptions) {
+          intro(`Creating a new ${appName} app in ${projectName}...`)
+        } else {
+          intro(`Let's configure your ${appName} application`)
+          finalOptions = await promptForOptions(cliOptions, {
+            forcedMode: forcedMode as TemplateOptions,
+            forcedAddOns,
+          })
+        }
+
+        await createApp(finalOptions!, {
+          environment: createDefaultEnvironment(),
+          cwd: options.targetDir || undefined,
+          name,
+          appName,
+        })
+      } catch (error) {
+        log.error(
+          error instanceof Error ? error.message : 'An unknown error occurred',
+        )
+        process.exit(1)
+      }
+    }
+  })
+
+  program.parse()
+}