@opensaas/stack-cli 0.1.7 → 0.4.0

package/src/generator/types.ts

@@ -41,24 +41,96 @@ function isFieldOptional(field: FieldConfig): boolean {
 }
 
 /**
- * Generate TypeScript interface for a model
+ * Generate virtual fields type - only contains virtual fields
+ * This is intersected with Prisma's GetPayload to add virtual fields to query results
  */
-function generateModelType(listName: string, fields: Record<string, FieldConfig>): string {
+function generateVirtualFieldsType(listName: string, fields: Record<string, FieldConfig>): string {
   const lines: string[] = []
+  const virtualFields = Object.entries(fields).filter(([_, config]) => config.type === 'virtual')
 
-  lines.push(`export type ${listName} = {`)
+  lines.push(`/**`)
+  lines.push(` * Virtual fields for ${listName} - computed fields not in database`)
+  lines.push(` * These are added to query results via resolveOutput hooks`)
+  lines.push(` */`)
+  lines.push(`export type ${listName}VirtualFields = {`)
+
+  for (const [fieldName, fieldConfig] of virtualFields) {
+    const tsType = mapFieldTypeToTypeScript(fieldConfig)
+    if (!tsType) continue
+
+    const optional = isFieldOptional(fieldConfig)
+    const nullability = optional ? ' | null' : ''
+    lines.push(`  ${fieldName}: ${tsType}${nullability}`)
+  }
+
+  // If no virtual fields, make it an empty object
+  if (virtualFields.length === 0) {
+    lines.push('  // No virtual fields defined')
+  }
+
+  lines.push('}')
+
+  return lines.join('\n')
+}
+
+/**
+ * Generate transformed fields type - fields with resultExtension transformations
+ * This replaces Prisma's base types with transformed types (e.g., string -> HashedPassword)
+ */
+function generateTransformedFieldsType(
+  listName: string,
+  fields: Record<string, FieldConfig>,
+): string {
+  const lines: string[] = []
+  const transformedFields = Object.entries(fields).filter(([_, config]) => config.resultExtension)
+
+  lines.push(`/**`)
+  lines.push(` * Transformed fields for ${listName} - fields with resultExtension transformations`)
+  lines.push(` * These override Prisma's base types with transformed types via result extensions`)
+  lines.push(` */`)
+  lines.push(`export type ${listName}TransformedFields = {`)
+
+  for (const [fieldName, fieldConfig] of transformedFields) {
+    if (fieldConfig.resultExtension) {
+      const optional = isFieldOptional(fieldConfig)
+      const nullability = optional ? ' | undefined' : ''
+      lines.push(`  ${fieldName}: ${fieldConfig.resultExtension.outputType}${nullability}`)
+    }
+  }
+
+  // If no transformed fields, make it an empty object
+  if (transformedFields.length === 0) {
+    lines.push('  // No transformed fields defined')
+  }
+
+  lines.push('}')
+
+  return lines.join('\n')
+}
+
+/**
+ * Generate TypeScript Output type for a model (includes virtual fields)
+ * This is kept for backwards compatibility but CustomDB uses Prisma's GetPayload + VirtualFields
+ */
+function generateModelOutputType(listName: string, fields: Record<string, FieldConfig>): string {
+  const lines: string[] = []
+
+  lines.push(`export type ${listName}Output = {`)
   lines.push('  id: string')
 
   for (const [fieldName, fieldConfig] of Object.entries(fields)) {
+    // Skip virtual fields - they're in VirtualFields type
+    if (fieldConfig.type === 'virtual') continue
+
     if (fieldConfig.type === 'relationship') {
       const relField = fieldConfig as RelationshipField
       const [targetList] = relField.ref.split('.')
 
       if (relField.many) {
-        lines.push(`  ${fieldName}: ${targetList}[]`)
+        lines.push(`  ${fieldName}?: ${targetList}Output[]`) // Optional since only present with include
       } else {
         lines.push(`  ${fieldName}Id: string | null`)
-        lines.push(`  ${fieldName}: ${targetList} | null`)
+        lines.push(`  ${fieldName}?: ${targetList}Output | null`) // Optional since only present with include
       }
     } else {
       const tsType = mapFieldTypeToTypeScript(fieldConfig)
@@ -72,11 +144,18 @@ function generateModelType(listName: string, fields: Record<string, FieldConfig>
 
   lines.push('  createdAt: Date')
   lines.push('  updatedAt: Date')
-  lines.push('}')
+  lines.push('} & ' + listName + 'VirtualFields') // Include virtual fields
 
   return lines.join('\n')
 }
 
+/**
+ * Generate convenience type alias (List = ListOutput)
+ */
+function generateModelTypeAlias(listName: string): string {
+  return `export type ${listName} = ${listName}Output`
+}
+
 /**
  * Generate CreateInput type
  */
@@ -86,6 +165,12 @@ function generateCreateInputType(listName: string, fields: Record<string, FieldC
   lines.push(`export type ${listName}CreateInput = {`)
 
   for (const [fieldName, fieldConfig] of Object.entries(fields)) {
+    // Skip virtual fields - they don't accept input in create operations
+    // Virtual fields with resolveInput hooks handle side effects but don't store data
+    if (fieldConfig.virtual) {
+      continue
+    }
+
     if (fieldConfig.type === 'relationship') {
       const relField = fieldConfig as RelationshipField
 
@@ -118,6 +203,12 @@ function generateUpdateInputType(listName: string, fields: Record<string, FieldC
   lines.push(`export type ${listName}UpdateInput = {`)
 
   for (const [fieldName, fieldConfig] of Object.entries(fields)) {
+    // Virtual fields with resolveInput hooks can accept input for side effects
+    // but we still skip them in the input type since they don't store data
+    if (fieldConfig.virtual) {
+      continue
+    }
+
     if (fieldConfig.type === 'relationship') {
       const relField = fieldConfig as RelationshipField
 
@@ -170,19 +261,153 @@ function generateWhereInputType(listName: string, fields: Record<string, FieldCo
 }
 
 /**
- * Generate Context type with all operations
+ * Generate hook types that reference Prisma input types
  */
-function generateContextType(): string {
+function generateHookTypes(listName: string): string {
   const lines: string[] = []
 
-  lines.push('export type Context<TSession extends OpensaasSession = OpensaasSession> = {')
-  lines.push('  db: AccessControlledDB<PrismaClient>')
+  lines.push(`/**`)
+  lines.push(` * Hook types for ${listName} list`)
+  lines.push(` * Properly typed to use Prisma's generated input types`)
+  lines.push(` */`)
+  lines.push(`export type ${listName}Hooks = {`)
+  lines.push(`  resolveInput?: (args:`)
+  lines.push(`    | {`)
+  lines.push(`        operation: 'create'`)
+  lines.push(`        resolvedData: Prisma.${listName}CreateInput`)
+  lines.push(`        item: undefined`)
+  lines.push(`        context: import('@opensaas/stack-core').AccessContext`)
+  lines.push(`      }`)
+  lines.push(`    | {`)
+  lines.push(`        operation: 'update'`)
+  lines.push(`        resolvedData: Prisma.${listName}UpdateInput`)
+  lines.push(`        item: ${listName}`)
+  lines.push(`        context: import('@opensaas/stack-core').AccessContext`)
+  lines.push(`      }`)
+  lines.push(`  ) => Promise<Prisma.${listName}CreateInput | Prisma.${listName}UpdateInput>`)
+  lines.push(`  validateInput?: (args: {`)
+  lines.push(`    operation: 'create' | 'update'`)
+  lines.push(`    resolvedData: Prisma.${listName}CreateInput | Prisma.${listName}UpdateInput`)
+  lines.push(`    item?: ${listName}`)
+  lines.push(`    context: import('@opensaas/stack-core').AccessContext`)
+  lines.push(`    addValidationError: (msg: string) => void`)
+  lines.push(`  }) => Promise<void>`)
+  lines.push(`  beforeOperation?: (args: {`)
+  lines.push(`    operation: 'create' | 'update' | 'delete'`)
+  lines.push(`    resolvedData?: Prisma.${listName}CreateInput | Prisma.${listName}UpdateInput`)
+  lines.push(`    item?: ${listName}`)
+  lines.push(`    context: import('@opensaas/stack-core').AccessContext`)
+  lines.push(`  }) => Promise<void>`)
+  lines.push(`  afterOperation?: (args: {`)
+  lines.push(`    operation: 'create' | 'update' | 'delete'`)
+  lines.push(`    resolvedData?: Prisma.${listName}CreateInput | Prisma.${listName}UpdateInput`)
+  lines.push(`    item?: ${listName}`)
+  lines.push(`    context: import('@opensaas/stack-core').AccessContext`)
+  lines.push(`  }) => Promise<void>`)
+  lines.push(`}`)
+
+  return lines.join('\n')
+}
+
+/**
+ * Generate custom DB interface that uses Prisma's conditional types with virtual and transformed fields
+ * This leverages Prisma's GetPayload utility to get correct types based on select/include
+ */
+function generateCustomDBType(config: OpenSaasConfig): string {
+  const lines: string[] = []
+
+  // Generate list of db keys to omit from AccessControlledDB
+  const dbKeys = Object.keys(config.lists).map((listName) => {
+    const dbKey = listName.charAt(0).toLowerCase() + listName.slice(1)
+    return `'${dbKey}'`
+  })
+
+  lines.push('/**')
+  lines.push(
+    " * Custom DB type that uses Prisma's conditional types with virtual and transformed field support",
+  )
+  lines.push(
+    ' * Types change based on select/include - relationships only present when explicitly included',
+  )
+  lines.push(' * Virtual fields and transformed fields are added to the base model type')
+  lines.push(' */')
+  lines.push('export type CustomDB = Omit<AccessControlledDB<PrismaClient>, ')
+  lines.push(`  ${dbKeys.join(' | ')}`)
+  lines.push('> & {')
+
+  // For each list, create strongly-typed methods using Prisma's conditional types
+  for (const listName of Object.keys(config.lists)) {
+    const dbKey = listName.charAt(0).toLowerCase() + listName.slice(1) // camelCase
+
+    lines.push(`  ${dbKey}: {`)
+
+    // findUnique - generic to preserve Prisma's conditional return type
+    lines.push(`    findUnique: <T extends Prisma.${listName}FindUniqueArgs>(`)
+    lines.push(`      args: Prisma.SelectSubset<T, Prisma.${listName}FindUniqueArgs>`)
+    lines.push(
+      `    ) => Promise<(Omit<Prisma.${listName}GetPayload<T>, keyof ${listName}TransformedFields> & ${listName}TransformedFields & ${listName}VirtualFields) | null>`,
+    )
+
+    // findMany - generic to preserve Prisma's conditional return type
+    lines.push(`    findMany: <T extends Prisma.${listName}FindManyArgs>(`)
+    lines.push(`      args?: Prisma.SelectSubset<T, Prisma.${listName}FindManyArgs>`)
+    lines.push(
+      `    ) => Promise<Array<Omit<Prisma.${listName}GetPayload<T>, keyof ${listName}TransformedFields> & ${listName}TransformedFields & ${listName}VirtualFields>>`,
+    )
+
+    // create - generic to preserve Prisma's conditional return type
+    lines.push(`    create: <T extends Prisma.${listName}CreateArgs>(`)
+    lines.push(`      args: Prisma.SelectSubset<T, Prisma.${listName}CreateArgs>`)
+    lines.push(
+      `    ) => Promise<Omit<Prisma.${listName}GetPayload<T>, keyof ${listName}TransformedFields> & ${listName}TransformedFields & ${listName}VirtualFields>`,
+    )
+
+    // update - generic to preserve Prisma's conditional return type
+    lines.push(`    update: <T extends Prisma.${listName}UpdateArgs>(`)
+    lines.push(`      args: Prisma.SelectSubset<T, Prisma.${listName}UpdateArgs>`)
+    lines.push(
+      `    ) => Promise<(Omit<Prisma.${listName}GetPayload<T>, keyof ${listName}TransformedFields> & ${listName}TransformedFields & ${listName}VirtualFields) | null>`,
+    )
+
+    // delete - generic to preserve Prisma's conditional return type
+    lines.push(`    delete: <T extends Prisma.${listName}DeleteArgs>(`)
+    lines.push(`      args: Prisma.SelectSubset<T, Prisma.${listName}DeleteArgs>`)
+    lines.push(
+      `    ) => Promise<(Omit<Prisma.${listName}GetPayload<T>, keyof ${listName}TransformedFields> & ${listName}TransformedFields & ${listName}VirtualFields) | null>`,
+    )
+
+    // count - no changes to return type
+    lines.push(`    count: (args?: Prisma.${listName}CountArgs) => Promise<number>`)
+
+    lines.push(`  }`)
+  }
+
+  lines.push('}')
+
+  return lines.join('\n')
+}
+
+/**
+ * Generate Context type that is compatible with AccessContext
+ */
+function generateContextType(_config: OpenSaasConfig): string {
+  const lines: string[] = []
+
+  lines.push('/**')
+  lines.push(
+    ' * Context type compatible with AccessContext but with CustomDB for virtual field typing',
+  )
+  lines.push(
+    ' * Extends AccessContext and overrides db property to include virtual fields in output types',
+  )
+  lines.push(' */')
+  lines.push(
+    "export type Context<TSession extends OpensaasSession = OpensaasSession> = Omit<AccessContext<PrismaClient>, 'db' | 'session'> & {",
+  )
+  lines.push('  db: CustomDB')
   lines.push('  session: TSession')
-  lines.push('  prisma: PrismaClient')
-  lines.push('  storage: StorageUtils')
   lines.push('  serverAction: (props: ServerActionProps) => Promise<unknown>')
   lines.push('  sudo: () => Context<TSession>')
-  lines.push('  _isSudo: boolean')
   lines.push('}')
 
   return lines.join('\n')
@@ -249,9 +474,10 @@ export function generateTypes(config: OpenSaasConfig): string {
   // Add necessary imports
   // Use alias for Session to avoid conflicts if user has a list named "Session"
   lines.push(
-    "import type { Session as OpensaasSession, StorageUtils, ServerActionProps, AccessControlledDB } from '@opensaas/stack-core'",
+    "import type { Session as OpensaasSession, StorageUtils, ServerActionProps, AccessControlledDB, AccessContext } from '@opensaas/stack-core'",
   )
-  lines.push("import type { PrismaClient } from './prisma-client'")
+  lines.push("import type { PrismaClient, Prisma } from './prisma-client/client'")
+  lines.push("import type { PluginServices } from './plugin-types'")
 
   // Add field-specific imports
   const fieldImports = collectFieldImports(config)
@@ -265,7 +491,15 @@ export function generateTypes(config: OpenSaasConfig): string {
 
   // Generate types for each list
   for (const [listName, listConfig] of Object.entries(config.lists)) {
-    lines.push(generateModelType(listName, listConfig.fields))
+    // Generate VirtualFields type first (needed by Output type and CustomDB)
+    lines.push(generateVirtualFieldsType(listName, listConfig.fields))
+    lines.push('')
+    // Generate TransformedFields type (needed by CustomDB)
+    lines.push(generateTransformedFieldsType(listName, listConfig.fields))
+    lines.push('')
+    lines.push(generateModelOutputType(listName, listConfig.fields))
+    lines.push('')
+    lines.push(generateModelTypeAlias(listName))
     lines.push('')
     lines.push(generateCreateInputType(listName, listConfig.fields))
     lines.push('')
@@ -273,10 +507,16 @@ export function generateTypes(config: OpenSaasConfig): string {
     lines.push('')
     lines.push(generateWhereInputType(listName, listConfig.fields))
     lines.push('')
+    lines.push(generateHookTypes(listName))
+    lines.push('')
   }
 
+  // Generate CustomDB interface
+  lines.push(generateCustomDBType(config))
+  lines.push('')
+
   // Generate Context type
-  lines.push(generateContextType())
+  lines.push(generateContextType(config))
 
   return lines.join('\n')
 }

package/src/index.ts

@@ -4,6 +4,7 @@ import { Command } from 'commander'
 import { generateCommand } from './commands/generate.js'
 import { initCommand } from './commands/init.js'
 import { devCommand } from './commands/dev.js'
+import { createMCPCommand } from './commands/mcp.js'
 
 const program = new Command()
 
@@ -35,4 +36,7 @@ program
     await devCommand()
   })
 
+// Add MCP command group
+program.addCommand(createMCPCommand())
+
 program.parse()

package/src/mcp/lib/documentation-provider.ts

@@ -0,0 +1,203 @@
+/**
+ * Documentation provider - Fetches documentation from the hosted docs site
+ */
+
+import type { DocumentationLookup } from './types.js'
+
+interface SearchResult {
+  content: string
+  metadata: {
+    title?: string
+    slug?: string
+    section?: string
+  }
+  score: number
+}
+
+interface SearchResponse {
+  results: SearchResult[]
+  query: string
+  count: number
+}
+
+export class OpenSaasDocumentationProvider {
+  private readonly DOCS_API = 'https://stack.opensaas.au/api/search'
+  private cache = new Map<string, { data: DocumentationLookup; timestamp: number }>()
+  private readonly CACHE_TTL = 1000 * 60 * 30 // 30 minutes
+
+  // Topic mappings for user-friendly queries
+  private topicMappings: Record<string, string> = {
+    fields: 'field-types',
+    'field types': 'field-types',
+    'field type': 'field-types',
+    access: 'access-control',
+    'access control': 'access-control',
+    permissions: 'access-control',
+    auth: 'authentication',
+    authentication: 'authentication',
+    login: 'authentication',
+    'sign in': 'authentication',
+    hooks: 'hooks',
+    hook: 'hooks',
+    lifecycle: 'hooks',
+    plugins: 'plugin-system',
+    plugin: 'plugin-system',
+    rag: 'rag',
+    search: 'semantic-search',
+    'semantic search': 'semantic-search',
+    storage: 'file-storage',
+    files: 'file-storage',
+    upload: 'file-storage',
+    config: 'configuration',
+    configuration: 'configuration',
+    prisma: 'prisma-integration',
+    database: 'database-setup',
+    deployment: 'deployment',
+    deploy: 'deployment',
+  }
+
+  /**
+   * Search documentation by query
+   */
+  async searchDocs(query: string, limit = 5, minScore = 0.7): Promise<DocumentationLookup> {
+    const cacheKey = `search:${query}:${limit}:${minScore}`
+
+    // Check cache
+    const cached = this.cache.get(cacheKey)
+    if (cached && Date.now() - cached.timestamp < this.CACHE_TTL) {
+      return cached.data
+    }
+
+    try {
+      const response = await fetch(this.DOCS_API, {
+        method: 'POST',
+        headers: {
+          'Content-Type': 'application/json',
+        },
+        body: JSON.stringify({ query, limit, minScore }),
+      })
+
+      if (!response.ok) {
+        throw new Error(`Docs API error: ${response.statusText}`)
+      }
+
+      const data = (await response.json()) as SearchResponse
+
+      const docLookup: DocumentationLookup = {
+        topic: query,
+        content: this.formatSearchResults(data.results),
+        url: 'https://stack.opensaas.au/',
+        codeExamples: this.extractCodeExamples(data.results),
+        relatedTopics: this.extractRelatedTopics(data.results),
+      }
+
+      // Cache the result
+      this.cache.set(cacheKey, { data: docLookup, timestamp: Date.now() })
+
+      return docLookup
+    } catch (error) {
+      console.error('Error fetching documentation:', error)
+      return this.getFallbackDocs(query)
+    }
+  }
+
+  /**
+   * Get documentation for a specific topic
+   */
+  async getTopicDocs(topic: string): Promise<DocumentationLookup> {
+    // Normalize topic using mappings
+    const normalizedTopic = this.topicMappings[topic.toLowerCase()] || topic
+
+    return this.searchDocs(normalizedTopic, 3, 0.8)
+  }
+
+  /**
+   * Format search results into readable content
+   */
+  private formatSearchResults(results: SearchResult[]): string {
+    if (results.length === 0) {
+      return 'No documentation found for this query.'
+    }
+
+    return results
+      .map((result, index) => {
+        const title = result.metadata.title || `Section ${index + 1}`
+        const section = result.metadata.section || ''
+        const score = (result.score * 100).toFixed(0)
+
+        return `### ${title}${section ? ` (${section})` : ''} [Relevance: ${score}%]\n\n${result.content}\n`
+      })
+      .join('\n---\n\n')
+  }
+
+  /**
+   * Extract code examples from search results
+   */
+  private extractCodeExamples(results: SearchResult[]): string[] {
+    const codeExamples: string[] = []
+    const codeBlockRegex = /```[\s\S]*?```/g
+
+    for (const result of results) {
+      const matches = result.content.match(codeBlockRegex)
+      if (matches) {
+        codeExamples.push(...matches)
+      }
+    }
+
+    return codeExamples
+  }
+
+  /**
+   * Extract related topics from search results
+   */
+  private extractRelatedTopics(results: SearchResult[]): string[] {
+    const topics = new Set<string>()
+
+    for (const result of results) {
+      if (result.metadata.section) {
+        topics.add(result.metadata.section)
+      }
+    }
+
+    return Array.from(topics)
+  }
+
+  /**
+   * Fallback documentation when API is unavailable
+   */
+  private getFallbackDocs(query: string): DocumentationLookup {
+    return {
+      topic: query,
+      content: `Unable to fetch documentation from the docs site at this time.
+
+Please visit the OpenSaaS Stack documentation directly:
+https://stack.opensaas.au/
+
+For ${query}, you can also check:
+- GitHub repository: https://github.com/OpenSaasAU/stack
+- Example projects in the examples/ directory`,
+      url: 'https://stack.opensaas.au/',
+      codeExamples: [],
+      relatedTopics: [],
+    }
+  }
+
+  /**
+   * Clear expired cache entries
+   */
+  clearExpiredCache(): void {
+    const now = Date.now()
+    for (const [key, value] of this.cache.entries()) {
+      if (now - value.timestamp >= this.CACHE_TTL) {
+        this.cache.delete(key)
+      }
+    }
+  }
+
+  /**
+   * Clear all cache
+   */
+  clearCache(): void {
+    this.cache.clear()
+  }
+}