@tanstack/cta-engine 0.10.0-alpha.14 → 0.10.0-alpha.16

package/dist/types/types.d.ts

@@ -1,51 +1,113 @@
 import type { CODE_ROUTER, FILE_ROUTER } from './constants.js';
 import type { PackageManager } from './package-manager.js';
-import type { ToolChain } from './toolchain.js';
-export type Framework = 'solid' | 'react';
 export type TemplateOptions = 'typescript' | 'javascript' | 'file-router';
+export type Mode = typeof CODE_ROUTER | typeof FILE_ROUTER;
+export type FileBundleHandler = {
+    getFiles: () => Promise<Array<string>>;
+    getFileContents: (path: string) => Promise<string>;
+};
+export type AddOnDefinition = {
+    id: string;
+    name: string;
+    description: string;
+    type: 'add-on' | 'example' | 'starter' | 'toolchain';
+    link: string;
+    templates: Array<string>;
+    routes?: Array<{
+        url: string;
+        name: string;
+        path: string;
+        jsName: string;
+    }>;
+    packageAdditions: {
+        dependencies?: Record<string, string>;
+        devDependencies?: Record<string, string>;
+        scripts?: Record<string, string>;
+    };
+    command?: {
+        command: string;
+        args?: Array<string>;
+    };
+    readme?: string;
+    phase: 'setup' | 'add-on';
+    shadcnComponents?: Array<string>;
+    warning?: string;
+    dependsOn?: Array<string>;
+    integrations?: Array<{
+        type: 'provider' | 'root-provider' | 'layout' | 'header-user';
+        path: string;
+        jsName: string;
+    }>;
+    variables?: Array<Variable>;
+    files?: Record<string, string>;
+    deletedFiles?: Array<string>;
+};
+export type StarterDefinition = AddOnDefinition & {
+    type: 'starter';
+    version: string;
+    author: string;
+    link: string;
+    license: string;
+    mode: Mode;
+    framework: string;
+    typescript: boolean;
+    tailwind: boolean;
+};
+export type AddOn = AddOnDefinition & FileBundleHandler;
+export type Starter = StarterDefinition & FileBundleHandler;
+export type FrameworkDefinition = {
+    id: string;
+    name: string;
+    description: string;
+    version: string;
+    baseDirectory: string;
+    addOnsDirectories: Array<string>;
+    examplesDirectory: string;
+};
+export type Framework = FrameworkDefinition & FileBundleHandler & {
+    basePackageJSON: Record<string, any>;
+    optionalPackages: Record<string, any>;
+    getAddOns: () => Array<AddOn>;
+};
 export interface Options {
     framework: Framework;
     projectName: string;
     typescript: boolean;
     tailwind: boolean;
     packageManager: PackageManager;
-    toolchain: ToolChain;
-    mode: typeof CODE_ROUTER | typeof FILE_ROUTER;
+    mode: Mode;
     addOns: boolean;
     chosenAddOns: Array<AddOn>;
     git: boolean;
     variableValues: Record<string, string | number | boolean>;
-    overlay?: AddOn | undefined;
-}
-export interface CliOptions {
-    template?: TemplateOptions;
-    framework?: Framework;
-    tailwind?: boolean;
-    packageManager?: PackageManager;
-    toolchain?: ToolChain;
-    projectName?: string;
-    git?: boolean;
-    addOns?: Array<string> | boolean;
-    listAddOns?: boolean;
-    mcp?: boolean;
-    mcpSse?: boolean;
-    overlay?: string;
-    targetDir?: string;
+    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>;
     execute: (command: string, args: Array<string>, cwd: string) => Promise<void>;
     deleteFile: (path: string) => Promise<void>;
-    readFile: (path: string, encoding?: BufferEncoding) => Promise<string>;
     exists: (path: string) => boolean;
-    readdir: (path: string) => Array<string>;
-    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;
@@ -65,44 +127,4 @@ type StringVariable = {
     type: 'string';
 };
 export type Variable = BooleanVariable | NumberVariable | StringVariable;
-export type AddOn = {
-    id: string;
-    name: string;
-    description: string;
-    type: 'add-on' | 'example' | 'overlay';
-    link: string;
-    templates: Array<string>;
-    routes: Array<{
-        url: string;
-        name: string;
-    }>;
-    packageAdditions: {
-        dependencies?: Record<string, string>;
-        devDependencies?: Record<string, string>;
-        scripts?: Record<string, string>;
-    };
-    command?: {
-        command: string;
-        args?: Array<string>;
-    };
-    readme?: string;
-    phase: 'setup' | 'add-on';
-    shadcnComponents?: Array<string>;
-    warning?: string;
-    dependsOn?: Array<string>;
-    variables?: Array<Variable>;
-    files?: Record<string, string>;
-    deletedFiles?: Array<string>;
-};
-export type Overlay = AddOn & {
-    type: 'overlay';
-    version: string;
-    author: string;
-    link: string;
-    license: string;
-    mode: typeof CODE_ROUTER | typeof FILE_ROUTER;
-    framework: Framework;
-    typescript: boolean;
-    tailwind: boolean;
-};
 export {};

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/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.10.0-alpha.14",
+  "version": "0.10.0-alpha.16",
   "description": "Tanstack Application Builder Engine",
   "type": "module",
   "main": "./dist/index.js",
@@ -15,33 +15,23 @@
     "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",
     "memfs": "^4.17.0",
-    "prettier": "^3.5.0",
-    "zod": "^3.24.2"
+    "prettier": "^3.5.0"
   },
   "devDependencies": {
     "@tanstack/config": "^0.16.2",
     "@types/ejs": "^3.1.5",
-    "@types/express": "^5.0.0",
     "@types/node": "^22.13.4",
     "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"
   },

package/src/add-ons.ts

@@ -1,89 +1,10 @@
-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 } from './types.js'
 
-import { getTemplatesRoot } from './templates.js'
-import { DEFAULT_FRAMEWORK } from './constants.js'
-import { readFileHelper } from './file-helper.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(
+export 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
+): Array<AddOn> {
+  return framework.getAddOns().filter((a) => a.templates.includes(template))
 }
 
 // Turn the list of chosen add-on IDs into a final list of add-ons by resolving dependencies
@@ -94,7 +15,7 @@ export async function finalizeAddOns(
 ): Promise<Array<AddOn>> {
   const finalAddOnIDs = new Set(chosenAddOnIDs)
 
-  const addOns = await getAllAddOns(framework, template)
+  const addOns = getAllAddOns(framework, template)
 
   for (const addOnID of finalAddOnIDs) {
     let addOn: AddOn | undefined
@@ -120,26 +41,8 @@ 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>
-  },
-) {
-  const addOns = await getAllAddOns(
-    options.framework || DEFAULT_FRAMEWORK,
-    forcedMode || options.template || 'typescript',
-  )
-  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 {
@@ -150,5 +53,9 @@ export async function loadRemoteAddOn(url: string): Promise<AddOn> {
   const response = await fetch(url)
   const fileContent = await response.json()
   fileContent.id = url
-  return fileContent
+  return {
+    ...fileContent,
+    getFiles: () => Promise.resolve(Object.keys(fileContent.files)),
+    getFileContents: (path: string) => Promise.resolve(fileContent.files[path]),
+  }
 }

package/src/{add.ts → add-to-app.ts}

@@ -1,32 +1,22 @@
 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 { finalizeAddOns } from './add-ons.js'
+import { getFrameworkById } from './frameworks.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 { sortObject } from './utils.js'
 
+import type { Environment, Options } from './types.js'
 import type { PersistedOptions } from './config-file.js'
 
-import type { Framework, Options } from './types.js'
-
 function isDirectory(path: string) {
   return statSync(path).isDirectory()
 }
@@ -40,14 +30,17 @@ async function createOptions(
   json: PersistedOptions,
   addOns: Array<string>,
 ): Promise<Required<Options>> {
+  const framework = getFrameworkById(json.framework)
+
   return {
     ...json,
+    framework,
     tailwind: true,
-    chosenAddOns: await finalizeAddOns(
-      json.framework as Framework,
-      json.mode as string,
-      [...json.existingAddOns, ...addOns],
-    ),
+    addOns: true,
+    chosenAddOns: await finalizeAddOns(framework!, json.mode as string, [
+      ...json.existingAddOns,
+      ...addOns,
+    ]),
   } as Required<Options>
 }
 
@@ -62,29 +55,32 @@ async function runCreateApp(options: Required<Options>) {
   return output
 }
 
-export async function add(
+export async function addToApp(
   addOns: Array<string>,
   {
     silent = false,
   }: {
     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 +112,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 +165,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 +175,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!')
   }
 }

package/src/config-file.ts

@@ -3,12 +3,13 @@ import { resolve } from 'node:path'
 
 import { CONFIG_FILE } from './constants.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'
 > & {
+  framework: string
   version: number
   existingAddOns: Array<string>
 }
@@ -18,13 +19,15 @@ export async function writeConfigFile(
   targetDir: string,
   options: Options,
 ) {
+  /* eslint-disable unused-imports/no-unused-vars */
+  const { addOns, chosenAddOns, framework, ...rest } = options
+  /* eslint-enable unused-imports/no-unused-vars */
   const persistedOptions: PersistedOptions = {
-    ...options,
+    ...rest,
     version: 1,
+    framework: options.framework.id,
     existingAddOns: options.chosenAddOns.map((addOn) => addOn.id),
   }
-  delete persistedOptions.addOns
-  delete persistedOptions.chosenAddOns
 
   await environment.writeFile(
     resolve(targetDir, CONFIG_FILE),
@@ -38,6 +41,9 @@ export async function readConfigFile(
   try {
     const configFile = resolve(targetDir, CONFIG_FILE)
     const config = await readFile(configFile, 'utf8')
+
+    // TODO: Look for old config files and convert them to the new format
+
     return JSON.parse(config)
   } catch {
     return null

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'