@tanstack/cta-engine 0.14.3 → 0.15.0

package/src/registry.ts

@@ -0,0 +1,92 @@
+import { loadRemoteAddOn } from './custom-add-ons/add-on.js'
+import { loadStarter } from './custom-add-ons/starter.js'
+
+import type { AddOn, Mode, Starter } from './types'
+
+export type Registry = {
+  starters: Array<{
+    name: string
+    description: string
+    url: string
+    banner?: string
+    mode: Mode
+    framework: string
+  }>
+  'add-ons': Array<{
+    name: string
+    description: string
+    url: string
+    modes: Array<Mode>
+    framework: string
+  }>
+}
+
+function absolutizeUrl(originalUrl: string, relativeUrl: string) {
+  if (relativeUrl.startsWith('http') || relativeUrl.startsWith('https')) {
+    return relativeUrl
+  }
+  const baseUrl = originalUrl.replace(/registry.json$/, '')
+  return `${baseUrl}${relativeUrl.replace(/^\.\//, '')}`
+}
+
+export async function getRawRegistry(
+  registryUrl?: string,
+): Promise<Registry | undefined> {
+  const regUrl = registryUrl || process.env.CTA_REGISTRY
+  if (regUrl) {
+    const registry = (await fetch(regUrl).then((res) => res.json())) as Registry
+    for (const addOn of registry['add-ons']) {
+      addOn.url = absolutizeUrl(regUrl, addOn.url)
+    }
+    for (const starter of registry.starters) {
+      starter.url = absolutizeUrl(regUrl, starter.url)
+      if (starter.banner) {
+        starter.banner = absolutizeUrl(regUrl, starter.banner)
+      }
+    }
+    return registry
+  }
+}
+
+async function getAddOns(registry: Registry): Promise<Array<AddOn>> {
+  const addOns: Array<AddOn> = []
+  for (const addOnInfo of registry['add-ons']) {
+    const addOn = await loadRemoteAddOn(addOnInfo.url)
+    addOns.push(addOn)
+  }
+  return addOns
+}
+
+export async function getRegistryAddOns(
+  registryUrl?: string,
+): Promise<Array<AddOn>> {
+  const registry = await getRawRegistry(registryUrl)
+  return registry ? await getAddOns(registry) : []
+}
+
+async function getStarters(registry: Registry): Promise<Array<Starter>> {
+  const starters: Array<Starter> = []
+  for (const starterInfo of registry.starters) {
+    const starter = await loadStarter(starterInfo.url)
+    starters.push(starter)
+  }
+  return starters
+}
+
+export async function getRegistryStarters(
+  registryUrl?: string,
+): Promise<Array<Starter>> {
+  const registry = await getRawRegistry(registryUrl)
+  return registry ? await getStarters(registry) : []
+}
+
+export async function getRegistry(registryUrl?: string): Promise<{
+  addOns: Array<AddOn>
+  starters: Array<Starter>
+}> {
+  const registry = await getRawRegistry(registryUrl)
+  return {
+    addOns: registry ? await getAddOns(registry) : [],
+    starters: registry ? await getStarters(registry) : [],
+  }
+}

package/src/special-steps/index.ts

@@ -0,0 +1,36 @@
+import { rimrafNodeModules } from './rimraf-node-modules.js'
+
+import type { Environment, Options } from '../types.js'
+
+const specialStepsLookup: Record<
+  string,
+  (environment: Environment, options: Options) => Promise<void>
+> = {
+  'rimraf-node-modules': rimrafNodeModules,
+}
+
+export async function runSpecialSteps(
+  environment: Environment,
+  options: Options,
+  specialSteps: Array<string>,
+) {
+  if (specialSteps.length) {
+    environment.startStep({
+      id: 'special-steps',
+      type: 'command',
+      message: 'Removing node_modules...',
+    })
+
+    for (const step of specialSteps) {
+      const stepFunction = specialStepsLookup[step]
+      /* eslint-disable @typescript-eslint/no-unnecessary-condition */
+      if (stepFunction) {
+        await stepFunction(environment, options)
+      } else {
+        environment.error(`Special step ${step} not found`)
+      }
+    }
+
+    environment.finishStep('special-steps', 'Special steps complete')
+  }
+}

package/src/special-steps/rimraf-node-modules.ts

@@ -0,0 +1,25 @@
+import { resolve } from 'node:path'
+
+import type { Environment, Options } from '../types.js'
+
+const lockFiles = ['package-lock.json', 'yarn.lock', 'pnpm-lock.yaml']
+
+export async function rimrafNodeModules(
+  environment: Environment,
+  options: Options,
+) {
+  environment.startStep({
+    id: 'special-steps',
+    type: 'command',
+    message: 'Removing node_modules...',
+  })
+
+  await environment.rimraf(resolve(options.targetDir, 'node_modules'))
+
+  for (const lockFile of lockFiles) {
+    const lockFilePath = resolve(options.targetDir, lockFile)
+    if (environment.exists(lockFilePath)) {
+      await environment.deleteFile(lockFilePath)
+    }
+  }
+}

package/src/template-file.ts

@@ -0,0 +1,150 @@
+import { resolve, sep } from 'node:path'
+import { render } from 'ejs'
+import { format } from 'prettier'
+
+import { CODE_ROUTER, FILE_ROUTER } from './constants.js'
+import { formatCommand } from './utils.js'
+import {
+  getPackageManagerInstallCommand,
+  getPackageManagerScriptCommand,
+} from './package-manager.js'
+import { relativePath } from './file-helpers.js'
+
+import type { AddOn, Environment, Options } from './types.js'
+
+function convertDotFilesAndPaths(path: string) {
+  return path
+    .split(sep)
+    .map((segment) => segment.replace(/^_dot_/, '.'))
+    .join(sep)
+}
+
+export function createTemplateFile(environment: Environment, options: Options) {
+  function getPackageManagerAddScript(
+    packageName: string,
+    isDev: boolean = false,
+  ) {
+    return formatCommand(
+      getPackageManagerInstallCommand(
+        options.packageManager,
+        packageName,
+        isDev,
+      ),
+    )
+  }
+  function getPackageManagerRunScript(
+    scriptName: string,
+    args: Array<string> = [],
+  ) {
+    return formatCommand(
+      getPackageManagerScriptCommand(options.packageManager, [
+        scriptName,
+        ...args,
+      ]),
+    )
+  }
+
+  class IgnoreFileError extends Error {
+    constructor() {
+      super('ignoreFile')
+      this.name = 'IgnoreFileError'
+    }
+  }
+
+  const integrations: Array<Required<AddOn>['integrations'][number]> = []
+  for (const addOn of options.chosenAddOns) {
+    if (addOn.integrations) {
+      for (const integration of addOn.integrations) {
+        integrations.push(integration)
+      }
+    }
+  }
+
+  const routes: Array<Required<AddOn>['routes'][number]> = []
+  for (const addOn of options.chosenAddOns) {
+    if (addOn.routes) {
+      routes.push(...addOn.routes)
+    }
+  }
+
+  const addOnEnabled = options.chosenAddOns.reduce<Record<string, boolean>>(
+    (acc, addOn) => {
+      acc[addOn.id] = true
+      return acc
+    },
+    {},
+  )
+
+  return async function templateFile(file: string, content: string) {
+    const templateValues = {
+      packageManager: options.packageManager,
+      projectName: options.projectName,
+      typescript: options.typescript,
+      tailwind: options.tailwind,
+      js: options.typescript ? 'ts' : 'js',
+      jsx: options.typescript ? 'tsx' : 'jsx',
+      fileRouter: options.mode === FILE_ROUTER,
+      codeRouter: options.mode === CODE_ROUTER,
+      addOnEnabled,
+      addOns: options.chosenAddOns,
+      integrations,
+      routes,
+
+      getPackageManagerAddScript,
+      getPackageManagerRunScript,
+
+      relativePath: (path: string) => relativePath(file, path),
+
+      ignoreFile: () => {
+        throw new IgnoreFileError()
+      },
+    }
+
+    let ignoreFile = false
+
+    if (file.endsWith('.ejs')) {
+      try {
+        content = render(content, templateValues)
+      } catch (error) {
+        if (error instanceof IgnoreFileError) {
+          ignoreFile = true
+        } else {
+          console.error(file, error)
+          environment.error(`EJS error in file ${file}`, error?.toString())
+          process.exit(1)
+        }
+      }
+    }
+
+    if (ignoreFile) {
+      return
+    }
+
+    let target = convertDotFilesAndPaths(file.replace('.ejs', ''))
+
+    let append = false
+    if (target.endsWith('.append')) {
+      append = true
+      target = target.replace('.append', '')
+    }
+
+    if (target.endsWith('.ts') || target.endsWith('.tsx')) {
+      content = await format(content, {
+        semi: false,
+        singleQuote: true,
+        trailingComma: 'all',
+        parser: 'typescript',
+      })
+    }
+
+    if (!options.typescript) {
+      target = target.replace(/\.tsx$/, '.jsx').replace(/\.ts$/, '.js')
+    }
+
+    if (append) {
+      await environment.appendFile(resolve(options.targetDir, target), content)
+    } else {
+      await environment.writeFile(resolve(options.targetDir, target), content)
+    }
+  }
+}

package/src/types.ts

@@ -1,124 +1,212 @@
+import z from 'zod'
+
 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 Mode = typeof CODE_ROUTER | typeof FILE_ROUTER
+
+export type StatusStepType =
+  | 'file'
+  | 'command'
+  | 'info'
+  | 'package-manager'
+  | 'other'
 
-export type TemplateOptions = 'typescript' | 'javascript' | 'file-router'
+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 type Mode = typeof CODE_ROUTER | typeof FILE_ROUTER
+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 type Integration = z.infer<typeof IntegrationSchema>
+
+export type AddOnBase = z.infer<typeof AddOnBaseSchema>
+
+export type StarterInfo = z.infer<typeof StarterSchema>
+
+export type StarterCompiled = z.infer<typeof StarterCompiledSchema>
+
+export type AddOnInfo = z.infer<typeof AddOnInfoSchema>
+
+export type AddOnCompiled = z.infer<typeof AddOnCompiledSchema>
+
+export type FileBundleHandler = {
+  getFiles: () => Promise<Array<string>>
+  getFileContents: (path: string) => Promise<string>
+  getDeletedFiles: () => Promise<Array<string>>
+}
+
+export type AddOn = AddOnInfo & FileBundleHandler
+
+export type Starter = StarterCompiled & 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
+  targetDir: string
+
+  framework: Framework
+  mode: Mode
+
   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
+
+  chosenAddOns: Array<AddOn>
+  starter?: Starter | 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
-  interactive?: boolean
+export type SerializedOptions = Omit<
+  Options,
+  'chosenAddOns' | 'starter' | 'framework'
+> & {
+  chosenAddOns: Array<string>
+  starter?: string | undefined
+  framework: string
 }
 
-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>
+  writeFileBase64: (path: string, base64Contents: string) => Promise<void>
+  execute: (
+    command: string,
+    args: Array<string>,
+    cwd: string,
+  ) => Promise<{ stdout: string }>
   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
+  readFile: (path: string) => Promise<string>
+  readdir: (path: string) => Promise<Array<string>>
+  rimraf: (path: string) => Promise<void>
 }
 
-type BooleanVariable = {
-  name: string
-  default: boolean
-  description: string
-  type: 'boolean'
+export type StatusEvent = {
+  id: string
+  type: StatusStepType
+  message: string
 }
-
-type NumberVariable = {
-  name: string
-  default: number
-  description: string
-  type: 'number'
+export type StopEvent = {
+  id: string
 }
 
-type StringVariable = {
-  name: string
-  default: string
-  description: string
-  type: 'string'
-}
+type UIEnvironment = {
+  appName: string
 
-export type Variable = BooleanVariable | NumberVariable | StringVariable
+  startStep: (info: {
+    id: string
+    type: StatusStepType
+    message: string
+  }) => void
+  finishStep: (id: string, finalMessage: string) => void
 
-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>
+  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
   }
-  readme?: string
-  phase: 'setup' | 'add-on'
-  shadcnComponents?: Array<string>
-  warning?: string
-  dependsOn?: Array<string>
-  variables?: Array<Variable>
-
-  files?: Record<string, string>
-  deletedFiles?: Array<string>
+  confirm: (message: string) => Promise<boolean>
 }
 
-export type Overlay = AddOn & {
-  type: 'overlay'
-  version: string
-  author: string
-  link: string
-  license: string
-  mode: Mode
-  framework: Framework
-  typescript: boolean
-  tailwind: boolean
-}
+export type Environment = ProjectEnvironment & FileEnvironment & UIEnvironment

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',
+            modes: ['file-router'],
+          } as AddOn,
+          {
+            id: 'add-on-2',
+            description: 'Add-on 2',
+            modes: ['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',
+            modes: ['file-router'],
+            dependsOn: ['add-on-2'],
+          } as AddOn,
+          {
+            id: 'add-on-2',
+            description: 'Add-on 2',
+            modes: ['file-router'],
+          } as AddOn,
+          {
+            id: 'add-on-3',
+            description: 'Add-on 3',
+            modes: ['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)
+  })
+})