@tanstack/cta-engine 0.14.3 → 0.15.0

package/dist/types/utils.d.ts

@@ -1 +1,6 @@
 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 +1,65 @@
-export {};
+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()),
+});

package/dist/utils.js

@@ -6,3 +6,12 @@ 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.14.3",
+  "version": "0.15.0",
   "description": "Tanstack Application Builder Engine",
   "type": "module",
   "main": "./dist/index.js",
@@ -15,35 +15,32 @@
     "url": "https://github.com/sponsors/tannerlinsley"
   },
   "keywords": [
-    "react",
     "tanstack",
     "router",
-    "create-react-app"
+    "create-tsrouter-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",
-    "express": "^4.21.2",
+    "ignore": "^7.0.3",
     "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": "^3.0.8",
+    "vitest-fetch-mock": "^0.4.5"
   },
   "scripts": {}
 }

package/src/add-ons.ts

@@ -1,100 +1,20 @@
-import { readFile } from 'node:fs/promises'
-import { existsSync, readdirSync, statSync } from 'node:fs'
-import { resolve } from 'node:path'
-import chalk from 'chalk'
+import { loadRemoteAddOn } from './custom-add-ons/add-on.js'
 
-import { getTemplatesRoot } from './templates.js'
-import { DEFAULT_FRAMEWORK } from './constants.js'
-import { readFileHelper } from './file-helper.js'
+import type { AddOn, Framework, Mode } from './types.js'
 
-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
+export function getAllAddOns(framework: Framework, mode: Mode): Array<AddOn> {
+  return framework.getAddOns().filter((a) => a.modes.includes(mode))
 }
 
 // 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,
+  mode: Mode,
   chosenAddOnIDs: Array<string>,
 ): Promise<Array<AddOn>> {
   const finalAddOnIDs = new Set(chosenAddOnIDs)
 
-  const addOns = await getAllAddOns(framework, template)
+  const addOns = getAllAddOns(framework, mode)
 
   for (const addOnID of finalAddOnIDs) {
     let addOn: AddOn | undefined
@@ -120,46 +40,10 @@ 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}`)
-  }
+  return finalAddOns
 }
 
 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-to-app.ts

@@ -0,0 +1,276 @@
+import { basename, resolve } from 'node:path'
+
+import { CONFIG_FILE } from './constants.js'
+import { finalizeAddOns } from './add-ons.js'
+import { getFrameworkById } from './frameworks.js'
+import { createMemoryEnvironment } from './environment.js'
+import { createApp } from './create-app.js'
+import {
+  readConfigFileFromEnvironment,
+  writeConfigFileToEnvironment,
+} from './config-file.js'
+import { formatCommand } from './utils.js'
+import { packageManagerInstall } from './package-manager.js'
+import {
+  isBase64,
+  recursivelyGatherFilesFromEnvironment,
+} from './file-helpers.js'
+import { mergePackageJSON } from './package-json.js'
+import { runSpecialSteps } from './special-steps/index.js'
+import { loadStarter } from './custom-add-ons/starter.js'
+
+import type { Environment, Mode, Options } from './types.js'
+import type { PersistedOptions } from './config-file.js'
+
+export async function hasPendingGitChanges(
+  environment: Environment,
+  cwd: string,
+) {
+  const { stdout } = await environment.execute(
+    'git',
+    ['status', '--porcelain'],
+    cwd,
+  )
+  return stdout.length > 0
+}
+
+async function createOptions(
+  json: PersistedOptions,
+  addOns: Array<string>,
+  targetDir: string,
+): Promise<Options> {
+  const framework = getFrameworkById(json.framework)
+
+  const starter = json.starter ? await loadStarter(json.starter) : undefined
+
+  return {
+    ...json,
+    framework,
+    tailwind: true,
+    addOns: true,
+    chosenAddOns: await finalizeAddOns(framework!, json.mode as Mode, [
+      ...json.chosenAddOns,
+      ...addOns,
+    ]),
+    targetDir,
+    starter,
+  } as Options
+}
+
+async function runCreateApp(options: Required<Options>) {
+  const { environment, output } = createMemoryEnvironment(options.targetDir)
+  await createApp(environment, options)
+  return output
+}
+
+export async function getCurrentConfiguration(
+  environment: Environment,
+  cwd: string,
+) {
+  const persistedOptions = await readConfigFileFromEnvironment(environment, cwd)
+  if (!persistedOptions) {
+    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 undefined
+  }
+
+  return persistedOptions
+}
+
+export async function writeFiles(
+  environment: Environment,
+  cwd: string,
+  output: {
+    files: Record<string, string>
+    deletedFiles: Array<string>
+  },
+  forced: boolean,
+) {
+  const currentFiles = await recursivelyGatherFilesFromEnvironment(
+    environment,
+    cwd,
+    false,
+  )
+
+  const overwrittenFiles: Array<string> = []
+  const changedFiles: Array<string> = []
+  for (const file of Object.keys(output.files)) {
+    const relativeFile = file.replace(cwd, '')
+    if (currentFiles[relativeFile]) {
+      if (currentFiles[relativeFile] !== output.files[file]) {
+        overwrittenFiles.push(relativeFile)
+      }
+    } else {
+      changedFiles.push(relativeFile)
+    }
+  }
+
+  if (!forced && overwrittenFiles.length) {
+    environment.warn(
+      'The following will be overwritten',
+      [...overwrittenFiles, ...output.deletedFiles].join('\n'),
+    )
+    const shouldContinue = await environment.confirm('Do you want to continue?')
+    if (!shouldContinue) {
+      throw new Error('User cancelled')
+    }
+  }
+
+  for (const file of output.deletedFiles) {
+    if (environment.exists(resolve(cwd, file))) {
+      await environment.deleteFile(resolve(cwd, file))
+    }
+  }
+
+  environment.startStep({
+    id: 'write-files',
+    type: 'file',
+    message: 'Writing add-on files...',
+  })
+
+  for (const file of [...changedFiles, ...overwrittenFiles]) {
+    const fName = basename(file)
+    const contents = output.files[file]
+    if (fName === 'package.json') {
+      const currentJson = JSON.parse(
+        await environment.readFile(resolve(cwd, file)),
+      )
+      const newJSON = mergePackageJSON(currentJson, JSON.parse(contents))
+      environment.writeFile(
+        resolve(cwd, file),
+        JSON.stringify(newJSON, null, 2),
+      )
+    } else if (fName !== CONFIG_FILE) {
+      if (isBase64(contents)) {
+        await environment.writeFileBase64(resolve(cwd, file), contents)
+      } else {
+        await environment.writeFile(resolve(cwd, file), contents)
+      }
+    }
+  }
+
+  environment.finishStep('write-files', 'Add-on files written')
+}
+
+export async function runNewCommands(
+  environment: Environment,
+  originalOptions: PersistedOptions,
+  cwd: string,
+  output: {
+    commands: Array<{
+      command: string
+      args: Array<string>
+    }>
+  },
+) {
+  const originalOutput = await runCreateApp({
+    ...(await createOptions(originalOptions, [], cwd)),
+  } as Required<Options>)
+
+  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)) {
+      environment.startStep({
+        id: 'run-commands',
+        type: 'command',
+        message: `Running ${formatCommand({ command: command.command, args: command.args })}...`,
+      })
+      await environment.execute(command.command, command.args, cwd)
+      environment.finishStep('run-commands', 'Setup commands complete')
+    }
+  }
+}
+
+export async function addToApp(
+  environment: Environment,
+  addOns: Array<string>,
+  cwd: string,
+  options?: {
+    forced?: boolean
+  },
+) {
+  const persistedOptions = await getCurrentConfiguration(environment, cwd)
+  if (!persistedOptions) {
+    return
+  }
+
+  if (!options?.forced && (await hasPendingGitChanges(environment, cwd))) {
+    environment.error(
+      'You have pending git changes.',
+      'Please commit or stash them before adding add-ons.',
+    )
+    return
+  }
+
+  environment.intro(`Adding ${addOns.join(', ')} to the project...`)
+  environment.startStep({
+    id: 'processing-new-app-setup',
+    type: 'file',
+    message: 'Processing new app setup...',
+  })
+
+  const newOptions = await createOptions(persistedOptions, addOns, cwd)
+
+  const output = await runCreateApp({
+    ...newOptions,
+    targetDir: cwd,
+  } as Required<Options>)
+
+  await writeFiles(environment, cwd, output, !!options?.forced)
+
+  environment.finishStep(
+    'processing-new-app-setup',
+    'Application files written',
+  )
+
+  // Run any special steps for the new add-ons
+
+  const specialSteps = new Set<string>([])
+  for (const addOn of newOptions.chosenAddOns) {
+    for (const step of addOn.addOnSpecialSteps || []) {
+      if (addOns.includes(addOn.id)) {
+        specialSteps.add(step)
+      }
+    }
+  }
+  if (specialSteps.size) {
+    await runSpecialSteps(environment, newOptions, Array.from(specialSteps))
+  }
+
+  // Install dependencies
+
+  environment.startStep({
+    id: 'install-dependencies',
+    type: 'package-manager',
+    message: `Installing dependencies via ${newOptions.packageManager}...`,
+  })
+  const s = environment.spinner()
+  s.start(`Installing dependencies via ${newOptions.packageManager}...`)
+  await packageManagerInstall(
+    environment,
+    newOptions.targetDir,
+    newOptions.packageManager,
+  )
+  s.stop(`Installed dependencies`)
+  environment.finishStep('install-dependencies', 'Dependencies installed')
+
+  // Handle new commands
+
+  await runNewCommands(environment, persistedOptions, cwd, output)
+
+  environment.startStep({
+    id: 'write-config-file',
+    type: 'file',
+    message: 'Writing config file...',
+  })
+  writeConfigFileToEnvironment(environment, newOptions)
+  environment.finishStep('write-config-file', 'Config file written')
+
+  environment.outro(`Add-ons ${addOns.join(', ')} added!`)
+}

package/src/config-file.ts

@@ -1,45 +1,76 @@
-import { readFile } from 'node:fs/promises'
 import { resolve } from 'node:path'
 
 import { CONFIG_FILE } from './constants.js'
+import { createDefaultEnvironment } from './environment.js'
 
-import type { Environment, Options } from './types'
+import type { Environment, Options } from './types.js'
 
-export type PersistedOptions = Exclude<
+export type PersistedOptions = Omit<
   Partial<Options>,
-  'addOns' | 'chosenAddOns'
+  'addOns' | 'chosenAddOns' | 'framework' | 'starter' | 'targetDir'
 > & {
+  framework: string
   version: number
-  existingAddOns: Array<string>
+  chosenAddOns: Array<string>
+  starter?: string
 }
 
-export async function writeConfigFile(
-  environment: Environment,
-  targetDir: string,
-  options: Options,
-) {
-  const persistedOptions: PersistedOptions = {
-    ...options,
+function createPersistedOptions(options: Options): PersistedOptions {
+  /* eslint-disable unused-imports/no-unused-vars */
+  const { chosenAddOns, framework, targetDir, ...rest } = options
+  /* eslint-enable unused-imports/no-unused-vars */
+  return {
+    ...rest,
     version: 1,
-    existingAddOns: options.chosenAddOns.map((addOn) => addOn.id),
+    framework: options.framework.id,
+    chosenAddOns: options.chosenAddOns.map((addOn) => addOn.id),
+    starter: options.starter?.id ?? undefined,
   }
-  delete persistedOptions.addOns
-  delete persistedOptions.chosenAddOns
+}
 
+export async function writeConfigFileToEnvironment(
+  environment: Environment,
+  options: Options,
+) {
   await environment.writeFile(
-    resolve(targetDir, CONFIG_FILE),
-    JSON.stringify(persistedOptions, null, 2),
+    resolve(options.targetDir, CONFIG_FILE),
+    JSON.stringify(createPersistedOptions(options), null, 2),
   )
 }
 
-export async function readConfigFile(
+export async function readConfigFileFromEnvironment(
+  environment: Environment,
   targetDir: string,
 ): Promise<PersistedOptions | null> {
   try {
     const configFile = resolve(targetDir, CONFIG_FILE)
-    const config = await readFile(configFile, 'utf8')
-    return JSON.parse(config)
+    const config = await environment.readFile(configFile)
+
+    const originalJSON = JSON.parse(config)
+
+    // Look for markers out outdated config files and upgrade the format on the fly (it will be written in the updated version after we add add-ons)
+    if (originalJSON.existingAddOns) {
+      if (originalJSON.framework === 'react') {
+        originalJSON.framework = 'react-cra'
+      }
+      originalJSON.chosenAddOns = originalJSON.existingAddOns
+      delete originalJSON.existingAddOns
+      delete originalJSON.addOns
+      if (originalJSON.toolchain && originalJSON.toolchain !== 'none') {
+        originalJSON.chosenAddOns.push(originalJSON.toolchain)
+      }
+      delete originalJSON.toolchain
+      delete originalJSON.variableValues
+    }
+
+    return originalJSON
   } catch {
     return null
   }
 }
+
+export async function readConfigFile(
+  targetDir: string,
+): Promise<PersistedOptions | null> {
+  return readConfigFileFromEnvironment(createDefaultEnvironment(), targetDir)
+}

package/src/constants.ts

@@ -1,9 +1,4 @@
-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'