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

package/src/types.ts

@@ -1,61 +1,135 @@
 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 Integration = {
+  type: 'provider' | 'root-provider' | 'layout' | 'header-user'
+  path: string
+  jsName: 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<Integration>
+  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: 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
@@ -78,46 +152,3 @@ type StringVariable = {
 }
 
 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: Mode
-  framework: Framework
-  typescript: boolean
-  tailwind: boolean
-}

package/src/utils.ts

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

package/tests/add-ons.test.ts

@@ -0,0 +1,67 @@
+import { describe, expect, it } from 'vitest'
+
+import { finalizeAddOns, getAllAddOns } from '../src/add-ons.js'
+
+import type { AddOn, Framework } from '../src/types.js'
+
+describe('getAllAddOns', () => {
+  it('filter add-ons', () => {
+    const addOns = getAllAddOns(
+      {
+        id: 'react-cra',
+        getAddOns: () => [
+          {
+            id: 'add-on-1',
+            description: 'Add-on 1',
+            templates: ['file-router'],
+          } as AddOn,
+          {
+            id: 'add-on-2',
+            description: 'Add-on 2',
+            templates: ['code-router'],
+          } as AddOn,
+        ],
+      } as Framework,
+      'file-router',
+    )
+
+    expect(addOns.length).toEqual(1)
+    expect(addOns[0].id).toEqual('add-on-1')
+  })
+})
+
+describe('finalizeAddOns', () => {
+  it('should finalize add-ons', async () => {
+    const addOns = await finalizeAddOns(
+      {
+        id: 'react-cra',
+        getAddOns: () => [
+          {
+            id: 'add-on-1',
+            description: 'Add-on 1',
+            templates: ['file-router'],
+            dependsOn: ['add-on-2'],
+          } as AddOn,
+          {
+            id: 'add-on-2',
+            description: 'Add-on 2',
+            templates: ['file-router'],
+          } as AddOn,
+          {
+            id: 'add-on-3',
+            description: 'Add-on 3',
+            templates: ['file-router'],
+          } as AddOn,
+        ],
+      } as Framework,
+      'file-router',
+      ['add-on-1'],
+    )
+
+    expect(addOns.length).toEqual(2)
+    const addOnIds = addOns.map((a) => a.id)
+    expect(addOnIds.includes('add-on-1')).toEqual(true)
+    expect(addOnIds.includes('add-on-2')).toEqual(true)
+    expect(addOnIds.includes('add-on-3')).toEqual(false)
+  })
+})

package/tests/config-file.test.ts

@@ -0,0 +1,64 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest'
+import { fs, vol } from 'memfs'
+import { resolve } from 'node:path'
+
+import { readConfigFile, writeConfigFile } from '../src/config-file.js'
+import { CONFIG_FILE } from '../src/constants.js'
+
+import type { AddOn, Environment, Framework, Options } from '../src/types.js'
+
+vi.mock('node:fs', () => fs)
+vi.mock('node:fs/promises', () => fs.promises)
+
+beforeEach(() => {
+  vol.reset()
+})
+
+describe('writeConfigFile', () => {
+  it('should write the config file', async () => {
+    const options = {
+      framework: {
+        id: 'react-cra',
+        getAddOns: () => [],
+      } as unknown as Framework,
+      chosenAddOns: [
+        {
+          id: 'add-on-1',
+          description: 'Add-on 1',
+          templates: ['file-router'],
+        } as AddOn,
+      ],
+      addOns: [],
+    } as unknown as Options
+    const targetDir = 'test-dir'
+    const persistedOptions = {
+      version: 1,
+      framework: options.framework.id,
+      existingAddOns: options.chosenAddOns.map((addOn) => addOn.id),
+    }
+    const env = {
+      writeFile: (path, optionsString) => {
+        expect(path).toEqual(resolve(targetDir, CONFIG_FILE))
+        expect(optionsString).toEqual(JSON.stringify(persistedOptions, null, 2))
+      },
+    } as Environment
+    await writeConfigFile(env, targetDir, options)
+  })
+})
+
+describe('readConfigFile', () => {
+  it('should read the config file', async () => {
+    const persistedOptions = {
+      version: 1,
+      framework: 'react-cra',
+      existingAddOns: ['add-on-1'],
+    }
+    vol.mkdirSync('/test')
+    vol.writeFileSync(
+      resolve('/test', CONFIG_FILE),
+      JSON.stringify(persistedOptions, null, 2),
+    )
+    const config = await readConfigFile('/test')
+    expect(config).toEqual(persistedOptions)
+  })
+})

package/tests/create-app.test.ts

@@ -0,0 +1,144 @@
+import { resolve } from 'node:path'
+
+import { describe, expect, it } from 'vitest'
+
+import { createApp } from '../src/create-app.js'
+
+import { createMemoryEnvironment } from '../src/environment.js'
+import { FILE_ROUTER } from '../src/constants.js'
+import { AddOn, Options } from '../src/types.js'
+
+const simpleOptions = {
+  projectName: 'test',
+  framework: {
+    id: 'test',
+    name: 'Test',
+    basePackageJSON: {
+      scripts: {
+        dev: 'react-scripts start',
+      },
+    },
+    optionalPackages: {
+      typescript: {
+        devDependencies: {
+          typescript: '^5.0.0',
+        },
+      },
+      tailwindcss: {
+        dependencies: {
+          tailwindcss: '^3.0.0',
+        },
+      },
+      'file-router': {
+        dependencies: {
+          'file-router': '^1.0.0',
+        },
+      },
+    },
+    getFiles: () => ['./src/test.txt'],
+    getFileContents: () => 'Hello',
+  },
+  chosenAddOns: [],
+  packageManager: 'pnpm',
+  typescript: true,
+  tailwind: true,
+  mode: FILE_ROUTER,
+  variableValues: {},
+} as unknown as Options
+
+describe('createApp', () => {
+  it('should create an app', async () => {
+    const { environment, output } = createMemoryEnvironment()
+    await createApp(simpleOptions, {
+      silent: true,
+      environment,
+      name: 'Test',
+      cwd: '/',
+      appName: 'TanStack App',
+    })
+
+    expect(output.files['/src/test.txt']).toEqual('Hello')
+  })
+
+  it('should create an app - not silent', async () => {
+    const { environment, output } = createMemoryEnvironment()
+    await createApp(simpleOptions, {
+      silent: false,
+      environment,
+      name: 'Test',
+      cwd: '/foo/bar/baz',
+      appName: 'TanStack App',
+    })
+
+    const cwd = process.cwd()
+
+    expect(output.files[resolve(cwd, '/foo/bar/baz/src/test.txt')]).toEqual(
+      'Hello',
+    )
+  })
+
+  it('should create an app - with a starter', async () => {
+    const { environment, output } = createMemoryEnvironment()
+    await createApp(
+      {
+        ...simpleOptions,
+        starter: {
+          command: {
+            command: 'echo',
+            args: ['Hello'],
+          },
+          getFiles: () => ['./src/test2.txt'],
+          getFileContents: () => 'Hello-2',
+        } as unknown as AddOn,
+      },
+      {
+        silent: false,
+        environment,
+        name: 'Test',
+        cwd: '/',
+        appName: 'TanStack App',
+      },
+    )
+
+    expect(output.files['/src/test2.txt']).toEqual('Hello-2')
+    expect(output.commands.some(({ command }) => command === 'echo')).toBe(true)
+  })
+
+  it('should create an app - with a add-on', async () => {
+    const { environment, output } = createMemoryEnvironment()
+    await createApp(
+      {
+        ...simpleOptions,
+        git: true,
+        addOns: true,
+        chosenAddOns: [
+          {
+            type: 'add-on',
+            phase: 'add-on',
+            warning: 'This is a warning',
+            command: {
+              command: 'echo',
+              args: ['Hello'],
+            },
+            packageAdditions: {
+              dependencies: {},
+              devDependencies: {},
+            },
+            getFiles: () => ['./src/test2.txt', './public/foo.jpg'],
+            getFileContents: () => 'base64::aGVsbG8=',
+          } as unknown as AddOn,
+        ],
+      },
+      {
+        silent: false,
+        environment,
+        name: 'Test',
+        cwd: '/',
+        appName: 'TanStack App',
+      },
+    )
+
+    expect(output.files['/src/test2.txt']).toEqual('hello')
+    expect(output.commands.some(({ command }) => command === 'echo')).toBe(true)
+  })
+})

package/tests/environment.test.ts

@@ -0,0 +1,96 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest'
+import { fs, vol } from 'memfs'
+
+vi.mock('node:fs', () => fs)
+vi.mock('node:fs/promises', () => fs.promises)
+
+beforeEach(() => {
+  vol.reset()
+})
+
+import {
+  createMemoryEnvironment,
+  createDefaultEnvironment,
+} from '../src/environment.js'
+
+describe('createMemoryEnvironment', () => {
+  it('should handle basic file operations', async () => {
+    const { environment, output } = createMemoryEnvironment()
+
+    environment.startRun()
+
+    await environment.writeFile('/test.txt', 'test')
+
+    environment.deleteFile('/test.txt')
+    expect(environment.exists('/test.txt')).toBe(false)
+
+    await environment.writeFile('/test.txt', 'test')
+
+    environment.finishRun()
+
+    expect(output.files['/test.txt']).toEqual('test')
+  })
+
+  it('should track command execution', async () => {
+    const { environment, output } = createMemoryEnvironment()
+
+    environment.startRun()
+    await environment.execute('echo', ['test'], '')
+    environment.finishRun()
+
+    expect(output.commands.length).toEqual(1)
+    expect(output.commands[0].command).toEqual('echo')
+    expect(output.commands[0].args).toEqual(['test'])
+  })
+})
+
+describe('createDefaultEnvironment', () => {
+  it('should create a default environment', async () => {
+    const environment = createDefaultEnvironment()
+    expect(environment).toBeDefined()
+  })
+
+  it('should write to the file system', async () => {
+    const environment = createDefaultEnvironment()
+    environment.startRun()
+    await environment.writeFile('/test.txt', 'test')
+    await environment.appendFile('/test.txt', 'test2')
+    await environment.copyFile('/test.txt', '/test2.txt')
+    environment.finishRun()
+
+    expect(fs.readFileSync('/test.txt', 'utf8')).toEqual('testtest2')
+  })
+
+  it('should allow deletes', async () => {
+    const environment = createDefaultEnvironment()
+    await environment.writeFile('/test.txt', 'test')
+    expect(fs.readFileSync('/test.txt', 'utf8')).toEqual('test')
+    await environment.deleteFile('/test.txt')
+    expect(environment.exists('/test.txt')).toBe(false)
+  })
+
+  it('should record errors', async () => {
+    const environment = createDefaultEnvironment()
+    environment.startRun()
+    await environment.execute('command-that-does-not-exist', ['test'], '')
+    environment.finishRun()
+    expect(environment.getErrors()).toEqual([
+      'Command "command-that-does-not-exist test" did not run successfully. Please run this manually in your project.',
+    ])
+  })
+
+  it('should have UI methods', async () => {
+    const environment = createDefaultEnvironment()
+    environment.startRun()
+    environment.intro('test')
+    environment.outro('test')
+    environment.info('test')
+    environment.error('test')
+    environment.warn('test')
+    const s = environment.spinner()
+    s.start('foo')
+    s.stop('bar')
+    environment.finishRun()
+    expect(await environment.confirm('test')).toEqual(true)
+  })
+})

package/tests/file-helper.test.ts

@@ -0,0 +1,90 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest'
+import { fs, vol } from 'memfs'
+
+import {
+  findFilesRecursively,
+  isDirectory,
+  readFileHelper,
+  relativePath,
+} from '../src/file-helpers.js'
+
+vi.mock('node:fs', () => fs)
+vi.mock('node:fs/promises', () => fs.promises)
+
+beforeEach(() => {
+  vol.reset()
+})
+
+describe('relativePath', () => {
+  it('relative path with the same directory', () => {
+    expect(relativePath('src/utils.ts', 'src/index.ts')).toBe('./index.ts')
+  })
+  it('relative from a subdirectory', () => {
+    expect(relativePath('src/something/utils.ts', 'src/index.ts')).toBe(
+      '../index.ts',
+    )
+  })
+  it('relative to a subdirectory', () => {
+    expect(relativePath('src/utils.ts', 'src/something/index.ts')).toBe(
+      './something/index.ts',
+    )
+  })
+  it('same deep directory', () => {
+    expect(
+      relativePath('src/foo/bar/baz/utils.ts', 'src/foo/bar/baz/index.ts'),
+    ).toBe('./index.ts')
+  })
+  it('up several levels and down several levels', () => {
+    expect(relativePath('src/bar/baz/utils.ts', 'src/foo/bar/index.ts')).toBe(
+      '../../foo/bar/index.ts',
+    )
+  })
+  it('relative path with a different directory', () => {
+    expect(
+      relativePath(
+        './src/routes/__root.tsx.ejs',
+        'src/integrations/tanstack-query/layout.tsx',
+      ),
+    ).toBe('../integrations/tanstack-query/layout.tsx')
+  })
+})
+
+describe('readFileHelper', () => {
+  it('should read a file', async () => {
+    vol.mkdirSync('/src')
+    fs.writeFileSync('/src/test.txt', 'Hello')
+    expect(readFileHelper('/src/test.txt')).toBe('Hello')
+  })
+  it('should read a binary file', async () => {
+    vol.mkdirSync('/src')
+    fs.writeFileSync('/src/test.jpg', 'Hello')
+    expect(readFileHelper('/src/test.jpg')).toBe('base64::SGVsbG8=')
+  })
+})
+
+describe('isDirectory', () => {
+  it('should check on files and directories', () => {
+    vol.mkdirSync('/src')
+    fs.writeFileSync('/src/test.txt', 'Hello')
+    expect(isDirectory('/src/test.txt')).toBe(false)
+    expect(isDirectory('/src')).toBe(true)
+  })
+})
+
+describe('findFilesRecursively', () => {
+  it('find files recursively', () => {
+    vol.mkdirSync('/src/subdir/subdir2', { recursive: true })
+    fs.writeFileSync('/src/test.txt', 'Hello')
+    fs.writeFileSync('/src/subdir/test.txt', 'Hello')
+    fs.writeFileSync('/src/subdir/subdir2/test.txt', 'Hello')
+
+    const files = {}
+    findFilesRecursively('/src', files)
+
+    expect(Object.keys(files)).toEqual([
+      '/src/subdir/subdir2/test.txt',
+      '/src/subdir/test.txt',
+      '/src/test.txt',
+    ])
+  })
+})