@tanstack/cta-engine 0.10.0-alpha.10

package/src/mcp.ts

@@ -0,0 +1,254 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js'
+import { SSEServerTransport } from '@modelcontextprotocol/sdk/server/sse.js'
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js'
+import express from 'express'
+import { z } from 'zod'
+
+import { createApp } from './create-app.js'
+import { finalizeAddOns } from './add-ons.js'
+import { createDefaultEnvironment } from './environment.js'
+
+const server = new McpServer({
+  name: 'Demo',
+  version: '1.0.0',
+})
+
+const tanStackReactAddOns = [
+  {
+    id: 'clerk',
+    description: 'Enable authentication with Clerk',
+  },
+  {
+    id: 'convex',
+    description: 'Enable a database using Convex',
+  },
+  {
+    id: 'form',
+    description: 'Form handling library',
+  },
+  {
+    id: 'netlify',
+    description: 'Enable deployments to Netlify',
+  },
+  {
+    id: 'sentry',
+    description: 'Enable Sentry error tracking',
+  },
+  {
+    id: 'shadcn',
+    description: 'Enable integration of the Shadcn UI component library',
+  },
+  {
+    id: 'start',
+    description:
+      'Set this if you want a TanStack Start application that supports server functions or APIs',
+  },
+  {
+    id: 'tanstack-query',
+    description: 'Enable TanStack Query for data fetching',
+  },
+  {
+    id: 'store',
+    description: 'Enable the TanStack Store state management library',
+  },
+  {
+    id: 'tanchat',
+    description: 'Add an AI chatbot example to the application',
+  },
+]
+
+server.tool('listTanStackReactAddOns', {}, () => {
+  return {
+    content: [{ type: 'text', text: JSON.stringify(tanStackReactAddOns) }],
+  }
+})
+
+server.tool(
+  'createTanStackReactApplication',
+  {
+    projectName: z
+      .string()
+      .describe(
+        'The package.json module name of the application (will also be the directory name)',
+      ),
+    cwd: z.string().describe('The directory to create the application in'),
+    addOns: z
+      .array(
+        z.enum([
+          'clerk',
+          'convex',
+          'form',
+          'netlify',
+          'sentry',
+          'shadcn',
+          'start',
+          'store',
+          'tanstack-query',
+          'tanchat',
+        ]),
+      )
+      .describe('The IDs of the add-ons to install'),
+  },
+  async ({ projectName, addOns, cwd }) => {
+    try {
+      process.chdir(cwd)
+      const chosenAddOns = await finalizeAddOns(
+        'react',
+        'file-router',
+        addOns as unknown as Array<string>,
+      )
+      await createApp(
+        {
+          projectName: projectName.replace(/^\//, './'),
+          framework: 'react',
+          typescript: true,
+          tailwind: true,
+          packageManager: 'pnpm',
+          toolchain: 'none',
+          mode: 'file-router',
+          addOns: true,
+          chosenAddOns,
+          git: true,
+          variableValues: {},
+        },
+        {
+          silent: true,
+          environment: createDefaultEnvironment(),
+          name: 'create-tsrouter-app',
+        },
+      )
+      return {
+        content: [{ type: 'text', text: 'Application created successfully' }],
+      }
+    } catch (error) {
+      return {
+        content: [
+          { type: 'text', text: `Error creating application: ${error}` },
+        ],
+      }
+    }
+  },
+)
+
+const tanStackSolidAddOns = [
+  {
+    id: 'solid-ui',
+    description: 'Enable integration of the Solid UI component library',
+  },
+  {
+    id: 'form',
+    description: 'Form handling library',
+  },
+  {
+    id: 'sentry',
+    description: 'Enable Sentry error tracking',
+  },
+  {
+    id: 'store',
+    description: 'Enable the TanStack Store state management library',
+  },
+  {
+    id: 'tanstack-query',
+    description: 'Enable TanStack Query for data fetching',
+  },
+  {
+    id: 'tanchat',
+    description: 'Add an AI chatbot example to the application',
+  },
+]
+
+server.tool('listTanStackSolidAddOns', {}, () => {
+  return {
+    content: [{ type: 'text', text: JSON.stringify(tanStackSolidAddOns) }],
+  }
+})
+
+server.tool(
+  'createTanStackSolidApplication',
+  {
+    projectName: z
+      .string()
+      .describe(
+        'The package.json module name of the application (will also be the directory name)',
+      ),
+    cwd: z.string().describe('The directory to create the application in'),
+    addOns: z
+      .array(
+        z.enum([
+          'solid-ui',
+          'form',
+          'sentry',
+          'store',
+          'tanstack-query',
+          'tanchat',
+        ]),
+      )
+      .describe('The IDs of the add-ons to install'),
+  },
+  async ({ projectName, addOns, cwd }) => {
+    try {
+      process.chdir(cwd)
+      const chosenAddOns = await finalizeAddOns(
+        'solid',
+        'file-router',
+        addOns as unknown as Array<string>,
+      )
+      await createApp(
+        {
+          projectName: projectName.replace(/^\//, './'),
+          framework: 'solid',
+          typescript: true,
+          tailwind: true,
+          packageManager: 'pnpm',
+          toolchain: 'none',
+          mode: 'file-router',
+          addOns: true,
+          chosenAddOns,
+          git: true,
+          variableValues: {},
+        },
+        {
+          silent: true,
+          environment: createDefaultEnvironment(),
+          name: 'create-tsrouter-app',
+        },
+      )
+      return {
+        content: [{ type: 'text', text: 'Application created successfully' }],
+      }
+    } catch (error) {
+      return {
+        content: [
+          { type: 'text', text: `Error creating application: ${error}` },
+        ],
+      }
+    }
+  },
+)
+
+export default async function runServer(sse: boolean) {
+  if (sse) {
+    const app = express()
+
+    let transport: SSEServerTransport | null = null
+
+    app.get('/sse', (req, res) => {
+      transport = new SSEServerTransport('/messages', res)
+      server.connect(transport)
+    })
+
+    app.post('/messages', (req, res) => {
+      if (transport) {
+        transport.handlePostMessage(req, res)
+      }
+    })
+
+    const port = process.env.PORT || 8080
+    app.listen(port, () => {
+      console.log(`Server is running on port http://localhost:${port}/sse`)
+    })
+  } else {
+    const transport = new StdioServerTransport()
+    await server.connect(transport)
+  }
+}

package/src/options.ts

@@ -0,0 +1,392 @@
+import {
+  cancel,
+  confirm,
+  isCancel,
+  multiselect,
+  select,
+  text,
+} from '@clack/prompts'
+
+import {
+  DEFAULT_PACKAGE_MANAGER,
+  SUPPORTED_PACKAGE_MANAGERS,
+  getPackageManager,
+} from './package-manager.js'
+import { DEFAULT_TOOLCHAIN, SUPPORTED_TOOLCHAINS } from './toolchain.js'
+import { CODE_ROUTER, DEFAULT_FRAMEWORK, FILE_ROUTER } from './constants.js'
+import { finalizeAddOns, getAllAddOns, loadRemoteAddOn } from './add-ons.js'
+
+import type { AddOn, CliOptions, Options, Overlay, Variable } from './types.js'
+
+// If all CLI options are provided, use them directly
+export async function normalizeOptions(
+  cliOptions: CliOptions,
+  forcedAddOns?: Array<string>,
+): Promise<Options | undefined> {
+  // in some cases, if you use windows/powershell, the argument for addons
+  // if sepparated by comma is not really passed as an array, but as a string
+  // with spaces, We need to normalize this edge case.
+  if (Array.isArray(cliOptions.addOns) && cliOptions.addOns.length === 1) {
+    const parseSeparatedArgs = cliOptions.addOns[0].split(' ')
+    if (parseSeparatedArgs.length > 1) {
+      cliOptions.addOns = parseSeparatedArgs
+    }
+    if (forcedAddOns) {
+      cliOptions.addOns = [...cliOptions.addOns, ...forcedAddOns]
+    }
+  } else if (forcedAddOns) {
+    cliOptions.addOns = [...forcedAddOns]
+  }
+
+  if (cliOptions.projectName) {
+    let typescript =
+      cliOptions.template === 'typescript' ||
+      cliOptions.template === 'file-router' ||
+      cliOptions.framework === 'solid'
+
+    let tailwind = !!cliOptions.tailwind
+    if (cliOptions.framework === 'solid') {
+      tailwind = true
+    }
+
+    let mode: typeof FILE_ROUTER | typeof CODE_ROUTER =
+      cliOptions.template === 'file-router' ? FILE_ROUTER : CODE_ROUTER
+
+    const overlay = cliOptions.overlay
+      ? ((await loadRemoteAddOn(cliOptions.overlay)) as Overlay)
+      : undefined
+
+    if (overlay) {
+      tailwind = overlay.tailwind
+      typescript = overlay.typescript
+      cliOptions.framework = overlay.framework
+      mode = overlay.mode
+    }
+
+    let addOns = false
+    let chosenAddOns: Array<AddOn> = []
+    if (Array.isArray(cliOptions.addOns) || overlay?.dependsOn) {
+      addOns = true
+      let finalAddOns = [...(overlay?.dependsOn || [])]
+      if (cliOptions.addOns && Array.isArray(cliOptions.addOns)) {
+        finalAddOns = [...finalAddOns, ...cliOptions.addOns]
+      }
+      chosenAddOns = await finalizeAddOns(
+        cliOptions.framework || DEFAULT_FRAMEWORK,
+        cliOptions.template === 'file-router' ? FILE_ROUTER : CODE_ROUTER,
+        finalAddOns,
+      )
+      tailwind = true
+      typescript = true
+    }
+
+    return {
+      framework: cliOptions.framework || 'react',
+      projectName: cliOptions.projectName,
+      typescript,
+      tailwind,
+      packageManager:
+        cliOptions.packageManager ||
+        getPackageManager() ||
+        DEFAULT_PACKAGE_MANAGER,
+      toolchain: cliOptions.toolchain || DEFAULT_TOOLCHAIN,
+      mode,
+      git: !!cliOptions.git,
+      addOns,
+      chosenAddOns,
+      variableValues: {},
+      overlay,
+    }
+  }
+}
+
+async function collectVariables(
+  variables: Array<Variable>,
+): Promise<Record<string, string | number | boolean>> {
+  const responses: Record<string, string | number | boolean> = {}
+  for (const variable of variables) {
+    if (variable.type === 'string') {
+      const response = await text({
+        message: variable.description,
+        initialValue: variable.default,
+      })
+      if (isCancel(response)) {
+        cancel('Operation cancelled.')
+        process.exit(0)
+      }
+      responses[variable.name] = response
+    } else if (variable.type === 'number') {
+      const response = await text({
+        message: variable.description,
+        initialValue: variable.default.toString(),
+      })
+      if (isCancel(response)) {
+        cancel('Operation cancelled.')
+        process.exit(0)
+      }
+      responses[variable.name] = Number(response)
+    } else {
+      const response = await confirm({
+        message: variable.description,
+        initialValue: variable.default === true,
+      })
+      if (isCancel(response)) {
+        cancel('Operation cancelled.')
+        process.exit(0)
+      }
+      responses[variable.name] = response
+    }
+  }
+  return responses
+}
+
+export async function promptForOptions(
+  cliOptions: CliOptions,
+  {
+    forcedAddOns = [],
+    forcedMode,
+  }: {
+    forcedAddOns?: Array<string>
+    forcedMode?: 'typescript' | 'javascript' | 'file-router'
+  },
+): Promise<Required<Options>> {
+  const options = {} as Required<Options>
+
+  options.framework = cliOptions.framework || DEFAULT_FRAMEWORK
+  if (options.framework === 'solid') {
+    options.typescript = true
+    options.tailwind = true
+  }
+
+  if (cliOptions.addOns) {
+    options.typescript = true
+  }
+
+  if (!cliOptions.projectName) {
+    const value = await text({
+      message: 'What would you like to name your project?',
+      defaultValue: 'my-app',
+      validate(value) {
+        if (!value) {
+          return 'Please enter a name'
+        }
+      },
+    })
+    if (isCancel(value)) {
+      cancel('Operation cancelled.')
+      process.exit(0)
+    }
+    options.projectName = value
+  }
+
+  // Router type selection
+  if (!cliOptions.template && !forcedMode) {
+    const routerType = await select({
+      message: 'Select the router type:',
+      options: [
+        {
+          value: FILE_ROUTER,
+          label: 'File Router - File-based routing structure',
+        },
+        {
+          value: CODE_ROUTER,
+          label: 'Code Router - Traditional code-based routing',
+        },
+      ],
+      initialValue: FILE_ROUTER,
+    })
+    if (isCancel(routerType)) {
+      cancel('Operation cancelled.')
+      process.exit(0)
+    }
+    options.mode = routerType as typeof CODE_ROUTER | typeof FILE_ROUTER
+  } else if (forcedMode) {
+    options.mode = forcedMode === 'file-router' ? FILE_ROUTER : CODE_ROUTER
+    options.typescript = options.mode === FILE_ROUTER
+  } else {
+    options.mode =
+      cliOptions.template === 'file-router' ? FILE_ROUTER : CODE_ROUTER
+    if (options.mode === FILE_ROUTER) {
+      options.typescript = true
+    }
+  }
+
+  // TypeScript selection (if using Code Router)
+  if (!options.typescript) {
+    if (options.mode === CODE_ROUTER) {
+      const typescriptEnable = await confirm({
+        message: 'Would you like to use TypeScript?',
+        initialValue: true,
+      })
+      if (isCancel(typescriptEnable)) {
+        cancel('Operation cancelled.')
+        process.exit(0)
+      }
+      options.typescript = typescriptEnable
+    } else {
+      options.typescript = true
+    }
+  }
+
+  // Tailwind selection
+  if (!cliOptions.tailwind && options.framework === 'react') {
+    const tailwind = await confirm({
+      message: 'Would you like to use Tailwind CSS?',
+      initialValue: true,
+    })
+    if (isCancel(tailwind)) {
+      cancel('Operation cancelled.')
+      process.exit(0)
+    }
+    options.tailwind = tailwind
+  } else {
+    options.tailwind = options.framework === 'solid' || !!cliOptions.tailwind
+  }
+
+  // Package manager selection
+  if (cliOptions.packageManager === undefined) {
+    const detectedPackageManager = getPackageManager()
+    if (!detectedPackageManager) {
+      const pm = await select({
+        message: 'Select package manager:',
+        options: SUPPORTED_PACKAGE_MANAGERS.map((pm) => ({
+          value: pm,
+          label: pm,
+        })),
+        initialValue: DEFAULT_PACKAGE_MANAGER,
+      })
+      if (isCancel(pm)) {
+        cancel('Operation cancelled.')
+        process.exit(0)
+      }
+      options.packageManager = pm
+    } else {
+      options.packageManager = detectedPackageManager
+    }
+  } else {
+    options.packageManager = cliOptions.packageManager
+  }
+
+  // Toolchain selection
+  if (cliOptions.toolchain === undefined) {
+    const tc = await select({
+      message: 'Select toolchain',
+      options: SUPPORTED_TOOLCHAINS.map((tc) => ({
+        value: tc,
+        label: tc,
+      })),
+      initialValue: DEFAULT_TOOLCHAIN,
+    })
+    if (isCancel(tc)) {
+      cancel('Operation cancelled.')
+      process.exit(0)
+    }
+    options.toolchain = tc
+  } else {
+    options.toolchain = cliOptions.toolchain
+  }
+
+  options.chosenAddOns = []
+  if (Array.isArray(cliOptions.addOns)) {
+    options.chosenAddOns = await finalizeAddOns(
+      options.framework,
+      options.mode,
+      Array.from(new Set([...cliOptions.addOns, ...forcedAddOns])),
+    )
+    options.tailwind = true
+  } else if (cliOptions.addOns) {
+    // Select any add-ons
+    const allAddOns = await getAllAddOns(options.framework, options.mode)
+    const addOns = allAddOns.filter((addOn) => addOn.type === 'add-on')
+    let selectedAddOns: Array<string> = []
+    if (options.typescript && addOns.length > 0) {
+      const value = await multiselect({
+        message: 'What add-ons would you like for your project:',
+        options: addOns
+          .filter((addOn) => !forcedAddOns.includes(addOn.id))
+          .map((addOn) => ({
+            value: addOn.id,
+            label: addOn.name,
+            hint: addOn.description,
+          })),
+        required: false,
+      })
+
+      if (isCancel(value)) {
+        cancel('Operation cancelled.')
+        process.exit(0)
+      }
+      selectedAddOns = value
+    }
+
+    // Select any examples
+    let selectedExamples: Array<string> = []
+    const examples = allAddOns.filter((addOn) => addOn.type === 'example')
+    if (options.typescript && examples.length > 0) {
+      const value = await multiselect({
+        message: 'Would you like any examples?',
+        options: examples
+          .filter((addOn) => !forcedAddOns.includes(addOn.id))
+          .map((addOn) => ({
+            value: addOn.id,
+            label: addOn.name,
+            hint: addOn.description,
+          })),
+        required: false,
+      })
+
+      if (isCancel(value)) {
+        cancel('Operation cancelled.')
+        process.exit(0)
+      }
+      selectedExamples = value
+    }
+
+    if (
+      selectedAddOns.length > 0 ||
+      selectedExamples.length > 0 ||
+      forcedAddOns.length > 0
+    ) {
+      options.chosenAddOns = await finalizeAddOns(
+        options.framework,
+        options.mode,
+        Array.from(
+          new Set([...selectedAddOns, ...selectedExamples, ...forcedAddOns]),
+        ),
+      )
+      options.tailwind = true
+    }
+  } else if (forcedAddOns.length > 0) {
+    options.chosenAddOns = await finalizeAddOns(
+      options.framework,
+      options.mode,
+      forcedAddOns,
+    )
+  }
+
+  // Collect variables
+  const variables: Array<Variable> = []
+  for (const addOn of options.chosenAddOns) {
+    for (const variable of addOn.variables ?? []) {
+      variables.push(variable)
+    }
+  }
+  options.variableValues = await collectVariables(variables)
+
+  // Git selection
+  if (cliOptions.git === undefined) {
+    const git = await confirm({
+      message: 'Would you like to initialize a new git repository?',
+      initialValue: true,
+    })
+    if (isCancel(git)) {
+      cancel('Operation cancelled.')
+      process.exit(0)
+    }
+    options.git = git
+  } else {
+    options.git = !!cliOptions.git
+  }
+
+  return options
+}

package/src/package-manager.ts

@@ -0,0 +1,46 @@
+import type { Environment } from './types.js'
+
+export const SUPPORTED_PACKAGE_MANAGERS = [
+  'npm',
+  'yarn',
+  'pnpm',
+  'bun',
+  'deno',
+] as const
+export type PackageManager = (typeof SUPPORTED_PACKAGE_MANAGERS)[number]
+export const DEFAULT_PACKAGE_MANAGER: PackageManager = 'npm'
+
+export function getPackageManager(): PackageManager | undefined {
+  const userAgent = process.env.npm_config_user_agent
+
+  if (userAgent === undefined) {
+    return DEFAULT_PACKAGE_MANAGER
+  }
+
+  const packageManager = SUPPORTED_PACKAGE_MANAGERS.find((manager) =>
+    userAgent.startsWith(manager),
+  )
+
+  return packageManager
+}
+
+export function packageManagerExecute(
+  environment: Environment,
+  packagerManager: PackageManager,
+  pkg: string,
+  args: Array<string>,
+  cwd: string,
+) {
+  switch (packagerManager) {
+    case 'yarn':
+      return environment.execute('yarn', ['dlx', pkg, ...args], cwd)
+    case 'pnpm':
+      return environment.execute('pnpx', [pkg, ...args], cwd)
+    case 'bun':
+      return environment.execute('bunx', ['--bun', pkg, ...args], cwd)
+    case 'deno':
+      return environment.execute('deno', ['run', `npm:${pkg}`, ...args], cwd)
+    default:
+      return environment.execute('npx', [pkg, ...args], cwd)
+  }
+}

package/src/templates.ts

@@ -0,0 +1,7 @@
+import { dirname, join } from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+export function getTemplatesRoot() {
+  // Get the parent directory because the compiled code is in the dist folder
+  return join(dirname(dirname(fileURLToPath(import.meta.url))), 'templates')
+}

package/src/toolchain.ts

@@ -0,0 +1,7 @@
+export const SUPPORTED_TOOLCHAINS = [
+  'none',
+  'biome',
+  'eslint+prettier',
+] as const
+export type ToolChain = (typeof SUPPORTED_TOOLCHAINS)[number]
+export const DEFAULT_TOOLCHAIN: ToolChain = 'none'