@opensaas/stack-cli 0.1.6 → 0.3.0

package/src/generator/plugin-types.ts

@@ -0,0 +1,147 @@
+import type { OpenSaasConfig } from '@opensaas/stack-core'
+import * as fs from 'fs'
+import * as path from 'path'
+
+/**
+ * Generate TypeScript declaration for plugin data types
+ * Creates type-safe access to config._pluginData
+ */
+function generatePluginDataInterface(config: OpenSaasConfig): string {
+  const lines: string[] = []
+
+  lines.push('/**')
+  lines.push(' * Plugin data storage types')
+  lines.push(' * Provides type-safe access to config._pluginData')
+  lines.push(' */')
+  lines.push('export interface PluginData {')
+
+  // Check if we have plugin data types to generate
+  if (config._pluginData && Object.keys(config._pluginData).length > 0) {
+    for (const pluginName of Object.keys(config._pluginData)) {
+      // Skip internal keys
+      if (pluginName.startsWith('__')) continue
+
+      // For each plugin, we'll add a Record<string, unknown> entry
+      // TODO: In the future, plugins could export their data types for proper typing
+      lines.push(`  ${pluginName}?: Record<string, unknown>`)
+    }
+  }
+
+  lines.push('}')
+
+  return lines.join('\n')
+}
+
+/**
+ * Generate TypeScript declaration for plugin runtime services
+ * Creates type-safe access to context.plugins
+ */
+function generatePluginServicesInterface(config: OpenSaasConfig): string {
+  const lines: string[] = []
+  const imports: string[] = []
+
+  // Check if we have plugins with runtime functions
+  const pluginsWithRuntime = (config._plugins || config.plugins || []).filter((p) => p.runtime)
+
+  // Collect imports from plugins that provide runtime service types
+  if (pluginsWithRuntime.length > 0) {
+    for (const plugin of pluginsWithRuntime) {
+      if (plugin.runtimeServiceTypes) {
+        imports.push(plugin.runtimeServiceTypes.import)
+      }
+    }
+  }
+
+  // Add imports at the top if any exist
+  if (imports.length > 0) {
+    lines.push(...imports)
+    lines.push('')
+  }
+
+  lines.push('/**')
+  lines.push(' * Plugin runtime services')
+  lines.push(' * Provides type-safe access to context.plugins')
+  lines.push(' * Extends Record to allow compatibility with base AccessContext type')
+  lines.push(' */')
+  lines.push(
+    'export interface PluginServices extends Record<string, Record<string, any> | undefined> {',
+  )
+
+  if (pluginsWithRuntime.length > 0) {
+    for (const plugin of pluginsWithRuntime) {
+      if (plugin.runtimeServiceTypes) {
+        // Use typed runtime service from plugin
+        lines.push(`  ${plugin.name}?: ${plugin.runtimeServiceTypes.typeName}`)
+      } else {
+        // Fallback to Record<string, any> for plugins without type metadata
+        lines.push(`  ${plugin.name}?: Record<string, any>`)
+      }
+    }
+  }
+
+  lines.push('}')
+
+  return lines.join('\n')
+}
+
+/**
+ * Generate module augmentation for OpenSaaS core types
+ * Note: We cannot augment _pluginData or plugins properties directly due to type constraints
+ * Instead, users should cast to PluginServices when accessing context.plugins
+ */
+function generateModuleAugmentation(): string {
+  const lines: string[] = []
+
+  lines.push('')
+  lines.push('/**')
+  lines.push(' * Declare this module to make interfaces available globally')
+  lines.push(' * Import this file to get typed plugin access')
+  lines.push(' */')
+  lines.push('declare global {')
+  lines.push('  // Plugin types are available as PluginServices interface')
+  lines.push('}')
+
+  return lines.join('\n')
+}
+
+/**
+ * Generate complete plugin types file
+ */
+export function generatePluginTypes(config: OpenSaasConfig): string {
+  const lines: string[] = []
+
+  // Add header comment
+  lines.push('/**')
+  lines.push(' * Generated plugin types from OpenSaas configuration')
+  lines.push(' * DO NOT EDIT - This file is automatically generated')
+  lines.push(' *')
+  lines.push(' * This file provides type-safe access to:')
+  lines.push(' * - config._pluginData - Plugin configuration data')
+  lines.push(' * - context.plugins - Plugin runtime services')
+  lines.push(' */')
+  lines.push('')
+
+  // Generate interfaces
+  lines.push(generatePluginDataInterface(config))
+  lines.push(generatePluginServicesInterface(config))
+
+  // Generate module augmentation
+  lines.push(generateModuleAugmentation())
+
+  return lines.join('\n')
+}
+
+/**
+ * Write plugin types to file
+ */
+export function writePluginTypes(config: OpenSaasConfig, outputPath: string): void {
+  const pluginTypes = generatePluginTypes(config)
+
+  // Ensure directory exists
+  const dir = path.dirname(outputPath)
+  if (!fs.existsSync(dir)) {
+    fs.mkdirSync(dir, { recursive: true })
+  }
+
+  fs.writeFileSync(outputPath, pluginTypes, 'utf-8')
+}

package/src/generator/prisma-config.ts

@@ -0,0 +1,46 @@
+import type { OpenSaasConfig } from '@opensaas/stack-core'
+import * as fs from 'fs'
+import * as path from 'path'
+
+/**
+ * Generate Prisma config file for CLI commands
+ *
+ * Prisma 7 requires a prisma.config.ts file at the project root for CLI commands
+ * like `prisma db push` and `prisma migrate dev`. This is separate from the
+ * runtime configuration (which uses adapters in opensaas.config.ts).
+ *
+ * The CLI config provides the database URL for schema operations, while the
+ * runtime config provides adapters for actual query execution.
+ */
+export function generatePrismaConfig(_config: OpenSaasConfig): string {
+  const lines: string[] = []
+
+  // Import dotenv for environment variable loading
+  lines.push("import 'dotenv/config'")
+  lines.push("import { defineConfig, env } from 'prisma/config'")
+  lines.push('')
+  lines.push('export default defineConfig({')
+  lines.push("  schema: 'prisma/schema.prisma',")
+  lines.push('  datasource: {')
+  lines.push("    url: env('DATABASE_URL'),")
+  lines.push('  },')
+  lines.push('})')
+  lines.push('')
+
+  return lines.join('\n')
+}
+
+/**
+ * Write Prisma config to file
+ */
+export function writePrismaConfig(config: OpenSaasConfig, outputPath: string): void {
+  const prismaConfig = generatePrismaConfig(config)
+
+  // Ensure directory exists
+  const dir = path.dirname(outputPath)
+  if (!fs.existsSync(dir)) {
+    fs.mkdirSync(dir, { recursive: true })
+  }
+
+  fs.writeFileSync(outputPath, prismaConfig, 'utf-8')
+}

package/src/generator/prisma.test.ts

@@ -9,7 +9,6 @@ describe('Prisma Schema Generator', () => {
       const config: OpenSaasConfig = {
         db: {
           provider: 'sqlite',
-          url: 'file:./dev.db',
         },
         lists: {},
       }
@@ -23,7 +22,6 @@ describe('Prisma Schema Generator', () => {
       const config: OpenSaasConfig = {
         db: {
           provider: 'sqlite',
-          url: 'file:./dev.db',
         },
         opensaasPath: '.custom-path',
         lists: {},
@@ -38,7 +36,6 @@ describe('Prisma Schema Generator', () => {
       const config: OpenSaasConfig = {
         db: {
           provider: 'sqlite',
-          url: 'file:./dev.db',
         },
         lists: {
           User: {
@@ -60,7 +57,6 @@ describe('Prisma Schema Generator', () => {
       const config: OpenSaasConfig = {
         db: {
           provider: 'sqlite',
-          url: 'file:./dev.db',
         },
         lists: {
           Post: {
@@ -81,7 +77,6 @@ describe('Prisma Schema Generator', () => {
       const config: OpenSaasConfig = {
         db: {
           provider: 'sqlite',
-          url: 'file:./dev.db',
         },
         lists: {
           Post: {
@@ -102,7 +97,6 @@ describe('Prisma Schema Generator', () => {
       const config: OpenSaasConfig = {
         db: {
           provider: 'sqlite',
-          url: 'file:./dev.db',
         },
         lists: {
           User: {
@@ -128,7 +122,6 @@ describe('Prisma Schema Generator', () => {
       const config: OpenSaasConfig = {
         db: {
           provider: 'sqlite',
-          url: 'file:./dev.db',
         },
         lists: {
           User: {
@@ -154,7 +147,6 @@ describe('Prisma Schema Generator', () => {
       const config: OpenSaasConfig = {
         db: {
           provider: 'postgresql',
-          url: process.env.DATABASE_URL || 'postgresql://localhost:5432/db',
         },
         lists: {
           User: {
@@ -184,7 +176,6 @@ describe('Prisma Schema Generator', () => {
       const config: OpenSaasConfig = {
         db: {
           provider: 'sqlite',
-          url: 'file:./dev.db',
         },
         lists: {
           User: {
@@ -206,7 +197,6 @@ describe('Prisma Schema Generator', () => {
       const config: OpenSaasConfig = {
         db: {
           provider: 'sqlite',
-          url: 'file:./dev.db',
         },
         lists: {},
       }

package/src/generator/prisma.ts

@@ -66,13 +66,12 @@ export function generatePrismaSchema(config: OpenSaasConfig): string {
 
   // Generator and datasource
   lines.push('generator client {')
-  lines.push('  provider = "prisma-client-js"')
+  lines.push('  provider = "prisma-client"')
   lines.push(`  output   = "../${opensaasPath}/prisma-client"`)
   lines.push('}')
   lines.push('')
   lines.push('datasource db {')
   lines.push(`  provider = "${config.db.provider}"`)
-  lines.push('  url      = env("DATABASE_URL")')
   lines.push('}')
   lines.push('')
 

package/src/generator/types.test.ts

@@ -9,7 +9,6 @@ describe('Types Generator', () => {
       const config: OpenSaasConfig = {
         db: {
           provider: 'sqlite',
-          url: 'file:./dev.db',
         },
         lists: {
           User: {
@@ -30,7 +29,6 @@ describe('Types Generator', () => {
       const config: OpenSaasConfig = {
         db: {
           provider: 'sqlite',
-          url: 'file:./dev.db',
         },
         lists: {
           Post: {
@@ -51,7 +49,6 @@ describe('Types Generator', () => {
       const config: OpenSaasConfig = {
         db: {
           provider: 'sqlite',
-          url: 'file:./dev.db',
         },
         lists: {
           Post: {
@@ -72,7 +69,6 @@ describe('Types Generator', () => {
       const config: OpenSaasConfig = {
         db: {
           provider: 'sqlite',
-          url: 'file:./dev.db',
         },
         lists: {
           User: {
@@ -92,7 +88,6 @@ describe('Types Generator', () => {
       const config: OpenSaasConfig = {
         db: {
           provider: 'sqlite',
-          url: 'file:./dev.db',
         },
         lists: {
           User: {
@@ -112,7 +107,6 @@ describe('Types Generator', () => {
       const config: OpenSaasConfig = {
         db: {
           provider: 'sqlite',
-          url: 'file:./dev.db',
         },
         lists: {
           User: {
@@ -139,7 +133,6 @@ describe('Types Generator', () => {
       const config: OpenSaasConfig = {
         db: {
           provider: 'sqlite',
-          url: 'file:./dev.db',
         },
         lists: {
           Post: {
@@ -165,7 +158,6 @@ describe('Types Generator', () => {
       const config: OpenSaasConfig = {
         db: {
           provider: 'sqlite',
-          url: 'file:./dev.db',
         },
         lists: {
           Post: {
@@ -191,7 +183,6 @@ describe('Types Generator', () => {
       const config: OpenSaasConfig = {
         db: {
           provider: 'sqlite',
-          url: 'file:./dev.db',
         },
         lists: {
           User: {
@@ -221,7 +212,6 @@ describe('Types Generator', () => {
       const config: OpenSaasConfig = {
         db: {
           provider: 'sqlite',
-          url: 'file:./dev.db',
         },
         lists: {
           Product: {
@@ -243,7 +233,6 @@ describe('Types Generator', () => {
       const config: OpenSaasConfig = {
         db: {
           provider: 'sqlite',
-          url: 'file:./dev.db',
         },
         lists: {
           Post: {
@@ -265,7 +254,6 @@ describe('Types Generator', () => {
       const config: OpenSaasConfig = {
         db: {
           provider: 'sqlite',
-          url: 'file:./dev.db',
         },
         lists: {},
       }

package/src/generator/types.ts

@@ -169,6 +169,55 @@ function generateWhereInputType(listName: string, fields: Record<string, FieldCo
   return lines.join('\n')
 }
 
+/**
+ * Generate hook types that reference Prisma input types
+ */
+function generateHookTypes(listName: string): string {
+  const lines: string[] = []
+
+  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 Context type with all operations
  */
@@ -180,7 +229,10 @@ function generateContextType(): string {
   lines.push('  session: TSession')
   lines.push('  prisma: PrismaClient')
   lines.push('  storage: StorageUtils')
+  lines.push('  plugins: PluginServices')
   lines.push('  serverAction: (props: ServerActionProps) => Promise<unknown>')
+  lines.push('  sudo: () => Context<TSession>')
+  lines.push('  _isSudo: boolean')
   lines.push('}')
 
   return lines.join('\n')
@@ -249,7 +301,8 @@ export function generateTypes(config: OpenSaasConfig): string {
   lines.push(
     "import type { Session as OpensaasSession, StorageUtils, ServerActionProps, AccessControlledDB } 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)
@@ -271,6 +324,8 @@ export function generateTypes(config: OpenSaasConfig): string {
     lines.push('')
     lines.push(generateWhereInputType(listName, listConfig.fields))
     lines.push('')
+    lines.push(generateHookTypes(listName))
+    lines.push('')
   }
 
   // Generate Context type

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()
+  }
+}