@opensaas/stack-core 0.1.5 → 0.1.7

package/src/config/types.ts

@@ -212,6 +212,27 @@ export type BaseFieldConfig<TInput = any, TOutput = TInput> = {
     type: string
     optional: boolean
   }
+  /**
+   * Get TypeScript imports needed for this field's type
+   * @returns Array of import statements needed for the generated types file
+   */
+  getTypeScriptImports?: () => Array<{
+    /**
+     * The type/value names to import
+     * e.g., ['StoredEmbedding', 'EmbeddingMetadata']
+     */
+    names: string[]
+    /**
+     * The module to import from
+     * e.g., '@opensaas/stack-rag'
+     */
+    from: string
+    /**
+     * Whether this is a type-only import
+     * @default true
+     */
+    typeOnly?: boolean
+  }>
 }
 
 export type TextField = BaseFieldConfig<string, string> & {
@@ -712,6 +733,121 @@ export interface ImageTransformationResult {
 
 export type StorageConfig = Record<string, { type: string; [key: string]: unknown }>
 
+/**
+ * Plugin system types
+ */
+
+/**
+ * Files generated by the core generators
+ * Plugins can modify these during afterGenerate hooks
+ */
+export type GeneratedFiles = {
+  prismaSchema: string
+  types: string
+  context: string
+  [key: string]: string // Allow plugins to add custom generated files
+}
+
+/**
+ * Context provided to plugins during initialization
+ * Provides helpers for safely modifying config
+ */
+export type PluginContext = {
+  /**
+   * Current config state (read-only)
+   * Plugins should use helper methods to modify config, not mutate directly
+   */
+  readonly config: OpenSaasConfig
+
+  /**
+   * Add a new list to the config
+   * Throws error if list already exists (unless merge strategy used)
+   */
+  addList: (name: string, listConfig: ListConfig) => void
+
+  /**
+   * Extend an existing list with additional fields, hooks, or access control
+   * Deep merges fields, hooks, and access control
+   * Throws error if list doesn't exist
+   */
+  extendList: (
+    name: string,
+    extension: {
+      fields?: Record<string, FieldConfig>
+      hooks?: Hooks
+      access?: {
+        operation?: OperationAccess
+      }
+      mcp?: ListMcpConfig
+    },
+  ) => void
+
+  /**
+   * Register a field type globally
+   * Useful for third-party field packages
+   */
+  registerFieldType?: (type: string, builder: (options?: unknown) => BaseFieldConfig) => void
+
+  /**
+   * Register a custom MCP tool
+   * Tools are added to the global MCP server
+   */
+  registerMcpTool?: (tool: McpCustomTool) => void
+
+  /**
+   * Store plugin-specific data in config for runtime access
+   * Prefixed with plugin name to avoid conflicts
+   */
+  setPluginData: <T>(pluginName: string, data: T) => void
+}
+
+/**
+ * Plugin definition
+ * Plugins can extend config, inject lists, add hooks, and participate in generation lifecycle
+ */
+export type Plugin = {
+  /**
+   * Unique plugin name (used for dependency resolution and data storage)
+   */
+  name: string
+
+  /**
+   * Plugin version (semantic versioning)
+   */
+  version?: string
+
+  /**
+   * Dependencies on other plugins (by name)
+   * Ensures plugins execute in correct order
+   */
+  dependencies?: string[]
+
+  /**
+   * Main initialization hook
+   * Called during config processing to extend or modify configuration
+   */
+  init: (context: PluginContext) => void | Promise<void>
+
+  /**
+   * Optional: Modify config before Prisma schema generation
+   * Useful for programmatic config transformations
+   */
+  beforeGenerate?: (config: OpenSaasConfig) => OpenSaasConfig | Promise<OpenSaasConfig>
+
+  /**
+   * Optional: Post-process generated files
+   * Allows plugins to modify Prisma schema, types, or add custom generated files
+   */
+  afterGenerate?: (files: GeneratedFiles) => GeneratedFiles | Promise<GeneratedFiles>
+
+  /**
+   * Optional: Provide runtime services
+   * Called when creating context to provide plugin-specific services
+   * Return value is stored in context.plugins[pluginName]
+   */
+  runtime?: (context: import('../access/types.js').AccessContext) => unknown
+}
+
 /**
  * Main configuration type
  */
@@ -734,4 +870,15 @@ export type OpenSaasConfig = {
    * @default ".opensaas"
    */
   opensaasPath?: string
+  /**
+   * Plugins to extend the stack
+   * Executed in array order (or dependency order if dependencies specified)
+   */
+  plugins?: Plugin[]
+  /**
+   * Plugin-specific data storage
+   * Keyed by plugin name, used for runtime configuration
+   * @internal
+   */
+  _pluginData?: Record<string, unknown>
 }

package/src/context/index.ts

@@ -146,12 +146,23 @@ export function getContext<
   prisma: TPrisma,
   session: Session,
   storage?: StorageUtils,
+  _isSudo: boolean = false,
 ): {
   db: AccessControlledDB<TPrisma>
   session: Session
   prisma: TPrisma
   storage: StorageUtils
   serverAction: (props: ServerActionProps) => Promise<unknown>
+  _isSudo: boolean
+  sudo: () => {
+    db: AccessControlledDB<TPrisma>
+    session: Session
+    prisma: TPrisma
+    storage: StorageUtils
+    serverAction: (props: ServerActionProps) => Promise<unknown>
+    sudo: () => unknown
+    _isSudo: boolean
+  }
 } {
   // Initialize db object - will be populated with access-controlled operations
   // Type is intentionally broad to allow dynamic model access
@@ -185,6 +196,7 @@ export function getContext<
         )
       },
     },
+    _isSudo,
   }
 
   // Create access-controlled operations for each list
@@ -226,12 +238,20 @@ export function getContext<
     return null
   }
 
+  // Sudo function - creates a new context that bypasses access control
+  // but still executes all hooks and validation
+  function sudo() {
+    return getContext(config, prisma, session, context.storage, true)
+  }
+
   return {
     db: db as AccessControlledDB<TPrisma>,
     session,
     prisma,
     storage: context.storage,
     serverAction,
+    sudo,
+    _isSudo,
   }
 }
 
@@ -242,25 +262,29 @@ function createFindUnique<TPrisma extends PrismaClientLike>(
   listName: string,
   listConfig: ListConfig,
   prisma: TPrisma,
-  context: AccessContext,
+  context: AccessContext<TPrisma>,
   config: OpenSaasConfig,
 ) {
   return async (args: { where: { id: string }; include?: Record<string, unknown> }) => {
-    // Check query access
-    const queryAccess = listConfig.access?.operation?.query
-    const accessResult = await checkAccess(queryAccess, {
-      session: context.session,
-      context,
-    })
+    // Check query access (skip if sudo mode)
+    let where: Record<string, unknown> = args.where
+    if (!context._isSudo) {
+      const queryAccess = listConfig.access?.operation?.query
+      const accessResult = await checkAccess(queryAccess, {
+        session: context.session,
+        context,
+      })
 
-    if (accessResult === false) {
-      return null
-    }
+      if (accessResult === false) {
+        return null
+      }
 
-    // Merge access filter with where clause
-    const where = mergeFilters(args.where, accessResult)
-    if (where === null) {
-      return null
+      // Merge access filter with where clause
+      const mergedWhere = mergeFilters(args.where, accessResult)
+      if (mergedWhere === null) {
+        return null
+      }
+      where = mergedWhere
     }
 
     // Build include with access control filters
@@ -290,12 +314,13 @@ function createFindUnique<TPrisma extends PrismaClientLike>(
     }
 
     // Filter readable fields and apply resolveOutput hooks (including nested relationships)
+    // Pass sudo flag through context to skip field-level access checks
     const filtered = await filterReadableFields(
       item,
       listConfig.fields,
       {
         session: context.session,
-        context,
+        context: { ...context, _isSudo: context._isSudo },
       },
       config,
       0,
@@ -323,7 +348,7 @@ function createFindMany<TPrisma extends PrismaClientLike>(
   listName: string,
   listConfig: ListConfig,
   prisma: TPrisma,
-  context: AccessContext,
+  context: AccessContext<TPrisma>,
   config: OpenSaasConfig,
 ) {
   return async (args?: {
@@ -332,21 +357,25 @@ function createFindMany<TPrisma extends PrismaClientLike>(
     skip?: number
     include?: Record<string, unknown>
   }) => {
-    // Check query access
-    const queryAccess = listConfig.access?.operation?.query
-    const accessResult = await checkAccess(queryAccess, {
-      session: context.session,
-      context,
-    })
+    // Check query access (skip if sudo mode)
+    let where: Record<string, unknown> | undefined = args?.where
+    if (!context._isSudo) {
+      const queryAccess = listConfig.access?.operation?.query
+      const accessResult = await checkAccess(queryAccess, {
+        session: context.session,
+        context,
+      })
 
-    if (accessResult === false) {
-      return []
-    }
+      if (accessResult === false) {
+        return []
+      }
 
-    // Merge access filter with where clause
-    const where = mergeFilters(args?.where, accessResult)
-    if (where === null) {
-      return []
+      // Merge access filter with where clause
+      const mergedWhere = mergeFilters(args?.where, accessResult)
+      if (mergedWhere === null) {
+        return []
+      }
+      where = mergedWhere
     }
 
     // Build include with access control filters
@@ -374,6 +403,7 @@ function createFindMany<TPrisma extends PrismaClientLike>(
     })
 
     // Filter readable fields for each item and apply resolveOutput hooks (including nested relationships)
+    // Pass sudo flag through context to skip field-level access checks
     const filtered = await Promise.all(
       items.map((item: Record<string, unknown>) =>
         filterReadableFields(
@@ -381,7 +411,7 @@ function createFindMany<TPrisma extends PrismaClientLike>(
           listConfig.fields,
           {
             session: context.session,
-            context,
+            context: { ...context, _isSudo: context._isSudo },
           },
           config,
           0,
@@ -415,19 +445,21 @@ function createCreate<TPrisma extends PrismaClientLike>(
   listName: string,
   listConfig: ListConfig,
   prisma: TPrisma,
-  context: AccessContext,
+  context: AccessContext<TPrisma>,
   config: OpenSaasConfig,
 ) {
   return async (args: { data: Record<string, unknown> }) => {
-    // 1. Check create access
-    const createAccess = listConfig.access?.operation?.create
-    const accessResult = await checkAccess(createAccess, {
-      session: context.session,
-      context,
-    })
+    // 1. Check create access (skip if sudo mode)
+    if (!context._isSudo) {
+      const createAccess = listConfig.access?.operation?.create
+      const accessResult = await checkAccess(createAccess, {
+        session: context.session,
+        context,
+      })
 
-    if (accessResult === false) {
-      return null
+      if (accessResult === false) {
+        return null
+      }
     }
 
     // 2. Execute list-level resolveInput hook
@@ -459,10 +491,10 @@ function createCreate<TPrisma extends PrismaClientLike>(
       throw new ValidationError(validation.errors, validation.fieldErrors)
     }
 
-    // 5. Filter writable fields (field-level access control)
+    // 5. Filter writable fields (field-level access control, skip if sudo mode)
     const filteredData = await filterWritableFields(resolvedData, listConfig.fields, 'create', {
       session: context.session,
-      context,
+      context: { ...context, _isSudo: context._isSudo },
     })
 
     // 5.5. Process nested relationship operations
@@ -509,12 +541,13 @@ function createCreate<TPrisma extends PrismaClientLike>(
     )
 
     // 11. Filter readable fields and apply resolveOutput hooks (including nested relationships)
+    // Pass sudo flag through context to skip field-level access checks
     const filtered = await filterReadableFields(
       item,
       listConfig.fields,
       {
         session: context.session,
-        context,
+        context: { ...context, _isSudo: context._isSudo },
       },
       config,
       0,
@@ -532,7 +565,7 @@ function createUpdate<TPrisma extends PrismaClientLike>(
   listName: string,
   listConfig: ListConfig,
   prisma: TPrisma,
-  context: AccessContext,
+  context: AccessContext<TPrisma>,
   config: OpenSaasConfig,
 ) {
   return async (args: { where: { id: string }; data: Record<string, unknown> }) => {
@@ -548,27 +581,29 @@ function createUpdate<TPrisma extends PrismaClientLike>(
       return null
     }
 
-    // 2. Check update access
-    const updateAccess = listConfig.access?.operation?.update
-    const accessResult = await checkAccess(updateAccess, {
-      session: context.session,
-      item,
-      context,
-    })
-
-    if (accessResult === false) {
-      return null
-    }
-
-    // If access returns a filter, check if item matches
-    if (typeof accessResult === 'object') {
-      const matchesFilter = await model.findFirst({
-        where: mergeFilters(args.where, accessResult),
+    // 2. Check update access (skip if sudo mode)
+    if (!context._isSudo) {
+      const updateAccess = listConfig.access?.operation?.update
+      const accessResult = await checkAccess(updateAccess, {
+        session: context.session,
+        item,
+        context,
       })
 
-      if (!matchesFilter) {
+      if (accessResult === false) {
         return null
       }
+
+      // If access returns a filter, check if item matches
+      if (typeof accessResult === 'object') {
+        const matchesFilter = await model.findFirst({
+          where: mergeFilters(args.where, accessResult),
+        })
+
+        if (!matchesFilter) {
+          return null
+        }
+      }
     }
 
     // 3. Execute list-level resolveInput hook
@@ -603,11 +638,11 @@ function createUpdate<TPrisma extends PrismaClientLike>(
       throw new ValidationError(validation.errors, validation.fieldErrors)
     }
 
-    // 6. Filter writable fields (field-level access control)
+    // 6. Filter writable fields (field-level access control, skip if sudo mode)
     const filteredData = await filterWritableFields(resolvedData, listConfig.fields, 'update', {
       session: context.session,
       item,
-      context,
+      context: { ...context, _isSudo: context._isSudo },
     })
 
     // 6.5. Process nested relationship operations
@@ -660,12 +695,13 @@ function createUpdate<TPrisma extends PrismaClientLike>(
     )
 
     // 12. Filter readable fields and apply resolveOutput hooks (including nested relationships)
+    // Pass sudo flag through context to skip field-level access checks
     const filtered = await filterReadableFields(
       updated,
       listConfig.fields,
       {
         session: context.session,
-        context,
+        context: { ...context, _isSudo: context._isSudo },
       },
       config,
       0,
@@ -683,7 +719,7 @@ function createDelete<TPrisma extends PrismaClientLike>(
   listName: string,
   listConfig: ListConfig,
   prisma: TPrisma,
-  context: AccessContext,
+  context: AccessContext<TPrisma>,
 ) {
   return async (args: { where: { id: string } }) => {
     // 1. Fetch the item to pass to access control and hooks
@@ -698,27 +734,29 @@ function createDelete<TPrisma extends PrismaClientLike>(
       return null
     }
 
-    // 2. Check delete access
-    const deleteAccess = listConfig.access?.operation?.delete
-    const accessResult = await checkAccess(deleteAccess, {
-      session: context.session,
-      item,
-      context,
-    })
-
-    if (accessResult === false) {
-      return null
-    }
-
-    // If access returns a filter, check if item matches
-    if (typeof accessResult === 'object') {
-      const matchesFilter = await model.findFirst({
-        where: mergeFilters(args.where, accessResult),
+    // 2. Check delete access (skip if sudo mode)
+    if (!context._isSudo) {
+      const deleteAccess = listConfig.access?.operation?.delete
+      const accessResult = await checkAccess(deleteAccess, {
+        session: context.session,
+        item,
+        context,
       })
 
-      if (!matchesFilter) {
+      if (accessResult === false) {
         return null
       }
+
+      // If access returns a filter, check if item matches
+      if (typeof accessResult === 'object') {
+        const matchesFilter = await model.findFirst({
+          where: mergeFilters(args.where, accessResult),
+        })
+
+        if (!matchesFilter) {
+          return null
+        }
+      }
     }
 
     // 3. Execute field-level beforeOperation hooks (side effects only)
@@ -764,24 +802,28 @@ function createCount<TPrisma extends PrismaClientLike>(
   listName: string,
   listConfig: ListConfig,
   prisma: TPrisma,
-  context: AccessContext,
+  context: AccessContext<TPrisma>,
 ) {
   return async (args?: { where?: Record<string, unknown> }) => {
-    // Check query access
-    const queryAccess = listConfig.access?.operation?.query
-    const accessResult = await checkAccess(queryAccess, {
-      session: context.session,
-      context,
-    })
+    // Check query access (skip if sudo mode)
+    let where: Record<string, unknown> | undefined = args?.where
+    if (!context._isSudo) {
+      const queryAccess = listConfig.access?.operation?.query
+      const accessResult = await checkAccess(queryAccess, {
+        session: context.session,
+        context,
+      })
 
-    if (accessResult === false) {
-      return 0
-    }
+      if (accessResult === false) {
+        return 0
+      }
 
-    // Merge access filter with where clause
-    const where = mergeFilters(args?.where, accessResult)
-    if (where === null) {
-      return 0
+      // Merge access filter with where clause
+      const mergedWhere = mergeFilters(args?.where, accessResult)
+      if (mergedWhere === null) {
+        return 0
+      }
+      where = mergedWhere
     }
 
     // Execute count

package/src/index.ts

@@ -24,6 +24,10 @@ export type {
   FileMetadata,
   ImageMetadata,
   ImageTransformationResult,
+  // Plugin system types
+  Plugin,
+  PluginContext,
+  GeneratedFiles,
 } from './config/index.js'
 
 // Access control

package/src/mcp/handler.ts

@@ -32,7 +32,7 @@ import type { McpSession, McpSessionProvider } from './types.js'
 export function createMcpHandlers(options: {
   config: OpenSaasConfig
   getSession: McpSessionProvider
-  getContext: (session?: { userId: string }) => AccessContext
+  getContext: (session?: { userId: string }) => Promise<AccessContext>
 }): {
   GET: (req: Request) => Promise<Response>
   POST: (req: Request) => Promise<Response>
@@ -403,7 +403,7 @@ async function handleToolsCall(
   params: any,
   session: McpSession,
   config: OpenSaasConfig,
-  getContext: (session?: { userId: string }) => AccessContext,
+  getContext: (session?: { userId: string }) => Promise<AccessContext>,
   id?: number | string,
 ): Promise<Response> {
   const toolName = params?.name
@@ -447,11 +447,11 @@ async function handleCrudTool(
   args: any,
   session: McpSession,
   config: OpenSaasConfig,
-  getContext: (session?: { userId: string }) => AccessContext,
+  getContext: (session?: { userId: string }) => Promise<AccessContext>,
   id?: number | string,
 ): Promise<Response> {
   // Create context with user session
-  const context = getContext({ userId: session.userId })
+  const context = await getContext({ userId: session.userId })
 
   try {
     // eslint-disable-next-line @typescript-eslint/no-explicit-any -- Result type varies by Prisma operation
@@ -530,7 +530,7 @@ async function handleCustomTool(
   args: any,
   session: McpSession,
   config: OpenSaasConfig,
-  getContext: (session?: { userId: string }) => AccessContext,
+  getContext: (session?: { userId: string }) => Promise<AccessContext>,
   id?: number | string,
 ): Promise<Response> {
   // Find custom tool in config
@@ -538,7 +538,7 @@ async function handleCustomTool(
     const customTool = listConfig.mcp?.customTools?.find((t) => t.name === toolName)
 
     if (customTool) {
-      const context = getContext({ userId: session.userId })
+      const context = await getContext({ userId: session.userId })
 
       try {
         const result = await customTool.handler({