@tanstack/cta-engine 0.10.0-alpha.21 → 0.10.0-alpha.25

package/src/package-manager.ts

@@ -24,94 +24,23 @@ export function getPackageManager(): PackageManager | undefined {
   return packageManager
 }
 
-export function getPackageManagerScriptCommand(
-  packagerManager: PackageManager,
-  args: Array<string> = [],
-) {
-  switch (packagerManager) {
-    case 'yarn':
-      return { command: 'yarn', args: ['run', ...args] }
-    case 'pnpm':
-      return { command: 'pnpm', args: [...args] }
-    case 'bun':
-      return { command: 'bunx', args: ['--bun', 'run', ...args] }
-    case 'deno':
-      return { command: 'deno', args: ['task', ...args] }
-    default:
-      return { command: 'npm', args: ['run', ...args] }
-  }
-}
-
-export function getPackageManagerExecuteCommand(
+export function packageManagerExecute(
+  environment: Environment,
   packagerManager: PackageManager,
   pkg: string,
-  args: Array<string> = [],
+  args: Array<string>,
+  cwd: string,
 ) {
   switch (packagerManager) {
     case 'yarn':
-      return { command: 'yarn', args: ['dlx', pkg, ...args] }
+      return environment.execute('yarn', ['dlx', pkg, ...args], cwd)
     case 'pnpm':
-      return { command: 'pnpx', args: [pkg, ...args] }
+      return environment.execute('pnpx', [pkg, ...args], cwd)
     case 'bun':
-      return { command: 'bunx', args: ['--bun', pkg, ...args] }
+      return environment.execute('bunx', ['--bun', pkg, ...args], cwd)
     case 'deno':
-      return { command: 'deno', args: ['run', `npm:${pkg}`, ...args] }
+      return environment.execute('deno', ['run', `npm:${pkg}`, ...args], cwd)
     default:
-      return { command: 'npx', args: [pkg, ...args] }
+      return environment.execute('npx', [pkg, ...args], cwd)
   }
 }
-
-export function getPackageManagerInstallCommand(
-  packagerManager: PackageManager,
-  pkg?: string,
-  isDev: boolean = false,
-) {
-  if (pkg) {
-    switch (packagerManager) {
-      case 'yarn':
-      case 'pnpm':
-        return {
-          command: packagerManager,
-          args: ['add', pkg, isDev ? '--dev' : ''],
-        }
-      default:
-        return {
-          command: packagerManager,
-          args: ['install', pkg, isDev ? '-D' : ''],
-        }
-    }
-  } else {
-    return {
-      command: packagerManager,
-      args: ['install'],
-    }
-  }
-}
-
-export function packageManagerInstall(
-  environment: Environment,
-  cwd: string,
-  packagerManager: PackageManager,
-  pkg?: string,
-) {
-  const { command, args: commandArgs } = getPackageManagerInstallCommand(
-    packagerManager,
-    pkg,
-  )
-  return environment.execute(command, commandArgs, cwd)
-}
-
-export function packageManagerExecute(
-  environment: Environment,
-  cwd: string,
-  packagerManager: PackageManager,
-  pkg: string,
-  args: Array<string>,
-) {
-  const { command, args: commandArgs } = getPackageManagerExecuteCommand(
-    packagerManager,
-    pkg,
-    args,
-  )
-  return environment.execute(command, commandArgs, 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

@@ -1,212 +1,124 @@
-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 Mode = typeof CODE_ROUTER | typeof FILE_ROUTER
-
-export type StatusStepType =
-  | 'file'
-  | 'command'
-  | 'info'
-  | 'package-manager'
-  | 'other'
-
-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 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 type Framework = 'solid' | 'react'
 
-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 TemplateOptions = 'typescript' | 'javascript' | 'file-router'
 
-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 type Mode = typeof CODE_ROUTER | typeof FILE_ROUTER
 
 export interface Options {
-  projectName: string
-  targetDir: string
-
   framework: Framework
-  mode: Mode
-
+  projectName: string
   typescript: boolean
   tailwind: boolean
-
   packageManager: PackageManager
-  git: boolean
-
+  toolchain: ToolChain
+  mode: Mode
+  addOns: boolean
   chosenAddOns: Array<AddOn>
-  starter?: Starter | undefined
+  git: boolean
+  variableValues: Record<string, string | number | boolean>
+  overlay?: AddOn | undefined
 }
 
-export type SerializedOptions = Omit<
-  Options,
-  'chosenAddOns' | 'starter' | 'framework'
-> & {
-  chosenAddOns: Array<string>
-  starter?: string | undefined
-  framework: string
+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
 }
 
-type ProjectEnvironment = {
+export type Environment = {
   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>
-  writeFileBase64: (path: string, base64Contents: string) => Promise<void>
-  execute: (
-    command: string,
-    args: Array<string>,
-    cwd: string,
-  ) => Promise<{ stdout: string }>
+  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
-  readFile: (path: string) => Promise<string>
-  readdir: (path: string) => Promise<Array<string>>
-  rimraf: (path: string) => Promise<void>
 }
 
-export type StatusEvent = {
-  id: string
-  type: StatusStepType
-  message: string
-}
-export type StopEvent = {
-  id: string
+type BooleanVariable = {
+  name: string
+  default: boolean
+  description: string
+  type: 'boolean'
 }
 
-type UIEnvironment = {
-  appName: string
-
-  startStep: (info: {
-    id: string
-    type: StatusStepType
-    message: string
-  }) => void
-  finishStep: (id: string, finalMessage: string) => void
+type NumberVariable = {
+  name: string
+  default: number
+  description: string
+  type: 'number'
+}
 
-  intro: (message: string) => void
-  outro: (message: string) => void
+type StringVariable = {
+  name: string
+  default: string
+  description: string
+  type: 'string'
+}
 
-  info: (title?: string, message?: string) => void
-  error: (title?: string, message?: string) => void
-  warn: (title?: string, message?: string) => void
+export type Variable = BooleanVariable | NumberVariable | StringVariable
 
-  spinner: () => {
-    start: (message: string) => void
-    stop: (message: 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>
   }
-  confirm: (message: string) => Promise<boolean>
+  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 Environment = ProjectEnvironment & FileEnvironment & UIEnvironment
+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,20 +8,3 @@ 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/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](dashboard.clerk.com)
+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.

package/templates/react/add-on/convex/assets/_dot_cursorrules.append

@@ -0,0 +1,93 @@
+This document serves as some special instructions when working with Convex.
+
+# Schemas
+
+When designing the schema please see this page on built in System fields and data types available: https://docs.convex.dev/database/types
+
+Here are some specifics that are often mishandled:
+
+## v (https://docs.convex.dev/api/modules/values#v)
+
+The validator builder.
+
+This builder allows you to build validators for Convex values.
+
+Validators can be used in schema definitions and as input validators for Convex functions.
+
+Type declaration
+Name	Type
+id	<TableName>(tableName: TableName) => VId<GenericId<TableName>, "required">
+null	() => VNull<null, "required">
+number	() => VFloat64<number, "required">
+float64	() => VFloat64<number, "required">
+bigint	() => VInt64<bigint, "required">
+int64	() => VInt64<bigint, "required">
+boolean	() => VBoolean<boolean, "required">
+string	() => VString<string, "required">
+bytes	() => VBytes<ArrayBuffer, "required">
+literal	<T>(literal: T) => VLiteral<T, "required">
+array	<T>(element: T) => VArray<T["type"][], T, "required">
+object	<T>(fields: T) => VObject<Expand<{ [Property in string | number | symbol]?: Exclude<Infer<T[Property]>, undefined> } & { [Property in string | number | symbol]: Infer<T[Property]> }>, T, "required", { [Property in string | number | symbol]: Property | `${Property & string}.${T[Property]["fieldPaths"]}` }[keyof T] & string>
+record	<Key, Value>(keys: Key, values: Value) => VRecord<Record<Infer<Key>, Value["type"]>, Key, Value, "required", string>
+union	<T>(...members: T) => VUnion<T[number]["type"], T, "required", T[number]["fieldPaths"]>
+any	() => VAny<any, "required", string>
+optional	<T>(value: T) => VOptional<T>
+
+## System fields (https://docs.convex.dev/database/types#system-fields)
+
+Every document in Convex has two automatically-generated system fields:
+
+_id: The document ID of the document.
+_creationTime: The time this document was created, in milliseconds since the Unix epoch.
+
+You do not need to add indices as these are added automatically.
+
+## Example Schema
+
+This is an example of a well crafted schema.
+
+```ts
+import { defineSchema, defineTable } from "convex/server";
+import { v } from "convex/values";
+
+export default defineSchema(
+  {
+    users: defineTable({
+      name: v.string(),
+    }),
+    
+    sessions: defineTable({
+      userId: v.id("users"),
+      sessionId: v.string(),
+    }).index("sessionId", ["sessionId"]),
+    
+    threads: defineTable({
+      uuid: v.string(),
+      summary: v.optional(v.string()),
+      summarizer: v.optional(v.id("_scheduled_functions")),
+    }).index("uuid", ["uuid"]),
+
+    messages: defineTable({
+      message: v.string(),
+      threadId: v.id("threads"),
+      author: v.union(
+        v.object({
+          role: v.literal("system"),
+        }),
+        v.object({
+          role: v.literal("assistant"),
+          context: v.array(v.id("messages")),
+          model: v.optional(v.string()),
+        }),
+        v.object({
+          role: v.literal("user"),
+          userId: v.id("users"),
+        }),
+      ),
+    })
+      .index("threadId", ["threadId"]),
+  },
+);
+```
+
+Sourced from: https://github.com/PatrickJS/awesome-cursorrules/blob/main/rules/convex-cursorrules-prompt-file/.cursorrules

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

@@ -0,0 +1,3 @@
+# Convex configuration, get this URL from your [Dashboard](dashboard.convex.dev)
+CONVEX_DEPLOYMENT=
+VITE_CONVEX_URL=

package/templates/react/add-on/convex/assets/convex/products.ts

@@ -0,0 +1,8 @@
+import { query } from "./_generated/server";
+
+export const get = query({
+  args: {},
+  handler: async (ctx) => {
+    return await ctx.db.query("products").collect();
+  },
+});

package/templates/react/add-on/convex/assets/convex/schema.ts

@@ -0,0 +1,10 @@
+import { defineSchema, defineTable } from "convex/server";
+import { v } from "convex/values";
+
+export default defineSchema({
+  products: defineTable({
+    title: v.string(),
+    imageId: v.string(),
+    price: v.number(),
+  }),
+});

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

@@ -0,0 +1,20 @@
+import { ConvexProvider } from 'convex/react'
+import { ConvexQueryClient } from '@convex-dev/react-query'
+
+const CONVEX_URL = (import.meta as any).env.VITE_CONVEX_URL
+if (!CONVEX_URL) {
+  console.error('missing envar CONVEX_URL')
+}
+const convexQueryClient = new ConvexQueryClient(CONVEX_URL)
+
+export default function AppConvexProvider({
+  children,
+}: {
+  children: React.ReactNode
+}) {
+  return (
+    <ConvexProvider client={convexQueryClient.convexClient}>
+      {children}
+    </ConvexProvider>
+  )
+}