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

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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tanstack/cta-engine",
-  "version": "0.10.0-alpha.19",
+  "version": "0.10.0-alpha.21",
   "description": "Tanstack Application Builder Engine",
   "type": "module",
   "main": "./dist/index.js",
@@ -24,17 +24,23 @@
   "dependencies": {
     "ejs": "^3.1.10",
     "execa": "^9.5.2",
+    "ignore": "^7.0.3",
     "memfs": "^4.17.0",
-    "prettier": "^3.5.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/node": "^22.13.4",
+    "@types/parse-gitignore": "^1.0.2",
     "@vitest/coverage-v8": "3.1.1",
     "eslint": "^9.20.0",
     "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,21 +1,20 @@
-import type { AddOn, Framework } from './types.js'
+import { loadRemoteAddOn } from './custom-add-ons/add-on.js'
 
-export function getAllAddOns(
-  framework: Framework,
-  template: string,
-): Array<AddOn> {
-  return framework.getAddOns().filter((a) => a.templates.includes(template))
+import type { AddOn, Framework, Mode } from './types.js'
+
+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 = getAllAddOns(framework, template)
+  const addOns = getAllAddOns(framework, mode)
 
   for (const addOnID of finalAddOnIDs) {
     let addOn: AddOn | undefined
@@ -48,14 +47,3 @@ export async function finalizeAddOns(
 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,
-    getFiles: () => Promise.resolve(Object.keys(fileContent.files)),
-    getFileContents: (path: string) => Promise.resolve(fileContent.files[path]),
-  }
-}

package/src/add-to-app.ts

@@ -1,180 +1,274 @@
-import { mkdir, readFile, writeFile } from 'node:fs/promises'
-import { existsSync, statSync } from 'node:fs'
-import { basename, dirname, resolve } from 'node:path'
-import { execa, execaSync } from 'execa'
+import { basename, resolve } from 'node:path'
 
 import { CONFIG_FILE } from './constants.js'
 import { finalizeAddOns } from './add-ons.js'
 import { getFrameworkById } from './frameworks.js'
-import {
-  createDefaultEnvironment,
-  createMemoryEnvironment,
-} from './environment.js'
+import { createMemoryEnvironment } from './environment.js'
 import { createApp } from './create-app.js'
-import { readConfigFile, writeConfigFile } from './config-file.js'
-import { sortObject } from './utils.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 type { Environment, Options } from './types.js'
+import type { Environment, Mode, Options } from './types.js'
 import type { PersistedOptions } from './config-file.js'
 
-function isDirectory(path: string) {
-  return statSync(path).isDirectory()
-}
-
-async function hasPendingGitChanges() {
-  const status = await execaSync('git', ['status', '--porcelain'])
-  return status.stdout.length > 0
+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>,
-): Promise<Required<Options>> {
+  targetDir: string,
+): Promise<Options> {
   const framework = getFrameworkById(json.framework)
 
+  // TODO: Load the starter
+
   return {
     ...json,
     framework,
     tailwind: true,
     addOns: true,
-    chosenAddOns: await finalizeAddOns(framework!, json.mode as string, [
+    chosenAddOns: await finalizeAddOns(framework!, json.mode as Mode, [
       ...json.existingAddOns,
       ...addOns,
     ]),
-  } as Required<Options>
+    targetDir,
+  } as Options
 }
 
 async function runCreateApp(options: Required<Options>) {
-  const { environment, output } = createMemoryEnvironment()
-  await createApp(options, {
-    silent: true,
-    environment,
-    cwd: process.cwd(),
-    name: 'create-tsrouter-app',
-  })
+  const { environment, output } = createMemoryEnvironment(options.targetDir)
+  await createApp(environment, options)
   return output
 }
 
-export async function addToApp(
-  addOns: Array<string>,
-  {
-    silent = false,
-  }: {
-    silent?: boolean
-  } = {},
+export async function getCurrentConfiguration(
   environment: Environment,
+  cwd: string,
 ) {
-  const persistedOptions = await readConfigFile(process.cwd())
+  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
-  }
-
-  if (!silent) {
-    environment.intro(`Adding ${addOns.join(', ')} to the project...`)
-  }
-
-  if (await hasPendingGitChanges()) {
-    environment.error(
-      'You have pending git changes.',
-      'Please commit or stash them before adding add-ons.',
-    )
-    return
+    return undefined
   }
 
-  const newOptions = await createOptions(persistedOptions, addOns)
+  return persistedOptions
+}
 
-  const output = await runCreateApp(newOptions)
+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> = []
-  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])
-        }
+    const relativeFile = file.replace(cwd, '')
+    if (currentFiles[relativeFile]) {
+      if (currentFiles[relativeFile] !== output.files[file]) {
+        overwrittenFiles.push(relativeFile)
       }
     } else {
       changedFiles.push(relativeFile)
-      contentMap.set(relativeFile, output.files[file])
     }
   }
 
-  if (overwrittenFiles.length > 0 && !silent) {
+  if (!forced && overwrittenFiles.length) {
     environment.warn(
-      'The following will be overwritten:',
-      overwrittenFiles.join('\n'),
+      'The following will be overwritten',
+      [...overwrittenFiles, ...output.deletedFiles].join('\n'),
     )
     const shouldContinue = await environment.confirm('Do you want to continue?')
     if (!shouldContinue) {
-      process.exit(0)
+      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 targetFile = `.${file}`
     const fName = basename(file)
-    const contents = contentMap.get(file)!
+    const contents = output.files[file]
     if (fName === 'package.json') {
       const currentJson = JSON.parse(
-        (await readFile(resolve(fName), 'utf-8')).toString(),
+        await environment.readFile(resolve(cwd, file)),
+      )
+      const newJSON = mergePackageJSON(currentJson, JSON.parse(contents))
+      environment.writeFile(
+        resolve(cwd, file),
+        JSON.stringify(newJSON, null, 2),
       )
-      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)
+      if (isBase64(contents)) {
+        await environment.writeFileBase64(resolve(cwd, file), contents)
+      } else {
+        await environment.writeFile(resolve(cwd, file), contents)
+      }
     }
   }
 
-  // Handle commands
-  const originalOutput = await runCreateApp(
-    await createOptions(persistedOptions, []),
-  )
+  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)) {
-      await execa(command.command, command.args)
+      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')
     }
   }
-  const realEnvironment = createDefaultEnvironment()
-  writeConfigFile(realEnvironment, process.cwd(), newOptions)
+}
 
-  const s = silent ? null : environment.spinner()
-  s?.start(`Installing dependencies via ${newOptions.packageManager}...`)
-  await realEnvironment.execute(
-    newOptions.packageManager,
-    ['install'],
-    resolve(process.cwd()),
+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',
   )
-  s?.stop(`Installed dependencies`)
 
-  if (!silent) {
-    environment.outro('Add-ons added successfully!')
+  // 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 added successfully!')
 }

package/src/config-file.ts

@@ -1,4 +1,3 @@
-import { readFile } from 'node:fs/promises'
 import { resolve } from 'node:path'
 
 import { CONFIG_FILE } from './constants.js'
@@ -7,40 +6,44 @@ import type { Environment, Options } from './types.js'
 
 export type PersistedOptions = Omit<
   Partial<Options>,
-  'addOns' | 'chosenAddOns' | 'framework'
+  'addOns' | 'chosenAddOns' | 'framework' | 'starter' | 'targetDir'
 > & {
   framework: string
   version: number
   existingAddOns: Array<string>
+  starter?: string
 }
 
-export async function writeConfigFile(
-  environment: Environment,
-  targetDir: string,
-  options: Options,
-) {
+function createPersistedOptions(options: Options): PersistedOptions {
   /* eslint-disable unused-imports/no-unused-vars */
-  const { addOns, chosenAddOns, framework, ...rest } = options
+  const { chosenAddOns, framework, targetDir, ...rest } = options
   /* eslint-enable unused-imports/no-unused-vars */
-  const persistedOptions: PersistedOptions = {
+  return {
     ...rest,
     version: 1,
     framework: options.framework.id,
     existingAddOns: options.chosenAddOns.map((addOn) => addOn.id),
+    starter: options.starter?.id ?? undefined,
   }
+}
 
+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')
+    const config = await environment.readFile(configFile)
 
     // TODO: Look for old config files and convert them to the new format