@tanstack/cta-engine 0.10.0-alpha.6

package/src/options.ts

@@ -0,0 +1,359 @@
+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,
+): 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 (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,
+): 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) {
+    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 {
+    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,
+      cliOptions.addOns,
+    )
+    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.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.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) {
+      options.chosenAddOns = await finalizeAddOns(
+        options.framework,
+        options.mode,
+        [...selectedAddOns, ...selectedExamples],
+      )
+      options.tailwind = true
+    }
+  }
+
+  // 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'

package/src/types.ts

@@ -0,0 +1,119 @@
+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 interface Options {
+  framework: Framework
+  projectName: string
+  typescript: boolean
+  tailwind: boolean
+  packageManager: PackageManager
+  toolchain: ToolChain
+  mode: typeof CODE_ROUTER | typeof FILE_ROUTER
+  addOns: boolean
+  chosenAddOns: Array<AddOn>
+  git: boolean
+  variableValues: Record<string, string | number | boolean>
+  overlay?: AddOn | undefined
+}
+
+export interface CliOptions {
+  template?: 'typescript' | 'javascript' | 'file-router'
+  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
+}
+
+export type Environment = {
+  startRun: () => void
+  finishRun: () => void
+  getErrors: () => Array<string>
+
+  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 BooleanVariable = {
+  name: string
+  default: boolean
+  description: string
+  type: 'boolean'
+}
+
+type NumberVariable = {
+  name: string
+  default: number
+  description: string
+  type: 'number'
+}
+
+type StringVariable = {
+  name: string
+  default: string
+  description: string
+  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
+}

package/src/utils.ts

@@ -0,0 +1,10 @@
+export function sortObject(
+  obj: Record<string, string>,
+): Record<string, string> {
+  return Object.keys(obj)
+    .sort()
+    .reduce<Record<string, string>>((acc, key) => {
+      acc[key] = obj[key]
+      return acc
+    }, {})
+}

package/templates/react/add-on/clerk/README.md

@@ -0,0 +1,3 @@
+## Setting up Clerk
+
+- Set the `VITE_CLERK_PUBLISHABLE_KEY` in your `.env.local`.

package/templates/react/add-on/clerk/assets/_dot_env.local.append

@@ -0,0 +1,2 @@
+# Clerk configuration, get this key from your [Dashboard](https://clerk.com/dashboard).
+VITE_CLERK_PUBLISHABLE_KEY=

package/templates/react/add-on/clerk/assets/src/integrations/clerk/header-user.tsx

@@ -0,0 +1,19 @@
+import {
+  SignedIn,
+  SignInButton,
+  SignedOut,
+  UserButton,
+} from '@clerk/clerk-react'
+
+export default function HeaderUser() {
+  return (
+    <>
+      <SignedIn>
+        <UserButton />
+      </SignedIn>
+      <SignedOut>
+        <SignInButton />
+      </SignedOut>
+    </>
+  )
+}

package/templates/react/add-on/clerk/assets/src/integrations/clerk/provider.tsx

@@ -0,0 +1,18 @@
+import { ClerkProvider } from '@clerk/clerk-react'
+
+const PUBLISHABLE_KEY = import.meta.env.VITE_CLERK_PUBLISHABLE_KEY
+if (!PUBLISHABLE_KEY) {
+  throw new Error('Add your Clerk Publishable Key to the .env.local file')
+}
+
+export default function AppClerkProvider({
+  children,
+}: {
+  children: React.ReactNode
+}) {
+  return (
+    <ClerkProvider publishableKey={PUBLISHABLE_KEY} afterSignOutUrl="/">
+      {children}
+    </ClerkProvider>
+  )
+}

package/templates/react/add-on/clerk/assets/src/routes/demo.clerk.tsx

@@ -0,0 +1,20 @@
+import { createFileRoute } from '@tanstack/react-router'
+import { useUser } from '@clerk/clerk-react'
+
+export const Route = createFileRoute('/demo/clerk')({
+  component: App,
+})
+
+function App() {
+  const { isSignedIn, user, isLoaded } = useUser()
+
+  if (!isLoaded) {
+    return <div className="p-4">Loading...</div>
+  }
+
+  if (!isSignedIn) {
+    return <div className="p-4">Sign in to view this page</div>
+  }
+
+  return <div className="p-4">Hello {user.firstName}!</div>
+}

package/templates/react/add-on/clerk/info.json

@@ -0,0 +1,13 @@
+{
+  "name": "Clerk",
+  "description": "Add Clerk authentication to your application.",
+  "phase": "add-on",
+  "templates": ["file-router"],
+  "link": "https://clerk.com",
+  "routes": [
+    {
+      "url": "/demo/clerk",
+      "name": "Clerk"
+    }
+  ]
+}

package/templates/react/add-on/clerk/package.json

@@ -0,0 +1,5 @@
+{
+  "dependencies": {
+    "@clerk/clerk-react": "^5.22.13"
+  }
+}

package/templates/react/add-on/convex/README.md

@@ -0,0 +1,4 @@
+## Setting up Convex
+
+- Set the `VITE_CONVEX_URL` and `CONVEX_DEPLOYMENT` environment variables in your `.env.local`. (Or run `npx convex init` to set them automatically.)
+- Run `npx convex dev` to start the Convex server.