@opensaas/stack-core 0.20.1 → 0.22.0

package/src/fields/text-keystone-compat.test.ts

@@ -0,0 +1,126 @@
+import { describe, it, expect } from 'vitest'
+import { text, integer } from './index.js'
+
+/**
+ * Unit coverage for Keystone-compat mode on text() (issue #475).
+ *
+ * Keystone 6 gives every non-null text column an implicit empty-string default.
+ * The `keystoneCompat` flag (db.keystoneCompat) reaches text()'s getPrismaType as
+ * the 4th positional argument — the same way provider/listName already do — and
+ * emits `@default("")` for a non-null text column that has no explicit default.
+ *
+ * These tests pin the precise on/off/explicit-default/nullable/non-text matrix
+ * from the issue's acceptance criteria.
+ */
+describe('text() Keystone-compat empty-string default', () => {
+  const KEYSTONE_COMPAT = true
+
+  describe('with keystoneCompat ON', () => {
+    it('emits @default("") for a required (non-null) text field without an explicit default', () => {
+      const field = text({ validation: { isRequired: true } })
+
+      const result = field.getPrismaType!('name', 'sqlite', 'User', KEYSTONE_COMPAT)
+
+      expect(result.type).toBe('String')
+      expect(result.modifiers).toBe('@default("")')
+    })
+
+    it('emits @default("") for a non-null text field made non-null via db.isNullable: false', () => {
+      // Non-null at the DB level even though validation does not mark it required.
+      const field = text({ db: { isNullable: false } })
+
+      const result = field.getPrismaType!('phone', 'sqlite', 'User', KEYSTONE_COMPAT)
+
+      expect(result.modifiers).toBe('@default("")')
+    })
+
+    it('does NOT emit a default for a nullable text field', () => {
+      // Optional → nullable; Keystone-compat must leave it alone.
+      const field = text()
+
+      const result = field.getPrismaType!('bio', 'sqlite', 'User', KEYSTONE_COMPAT)
+
+      expect(result.modifiers).toBe('?')
+      expect(result.modifiers).not.toContain('@default')
+    })
+
+    it('does NOT emit a default for a text field made nullable via db.isNullable: true', () => {
+      // Required validation, but explicitly nullable at the DB level.
+      const field = text({ validation: { isRequired: true }, db: { isNullable: true } })
+
+      const result = field.getPrismaType!('note', 'sqlite', 'User', KEYSTONE_COMPAT)
+
+      expect(result.modifiers).toBe('?')
+      expect(result.modifiers).not.toContain('@default')
+    })
+
+    it('lets an explicit defaultValue win over the compat empty-string default', () => {
+      const field = text({ validation: { isRequired: true }, defaultValue: 'PLEASE_UPDATE' })
+
+      const result = field.getPrismaType!('status', 'sqlite', 'Account', KEYSTONE_COMPAT)
+
+      expect(result.modifiers).toBe('@default("PLEASE_UPDATE")')
+      expect(result.modifiers).not.toContain('@default("")')
+    })
+
+    it('honours an explicit empty-string defaultValue without double-emitting', () => {
+      const field = text({ validation: { isRequired: true }, defaultValue: '' })
+
+      const result = field.getPrismaType!('label', 'sqlite', 'Account', KEYSTONE_COMPAT)
+
+      // A single @default("") — the explicit default, not a duplicate.
+      expect(result.modifiers).toBe('@default("")')
+      expect(result.modifiers!.match(/@default/g)).toHaveLength(1)
+    })
+
+    it('places @default("") alongside other modifiers in the expected order', () => {
+      const field = text({
+        validation: { isRequired: true },
+        isIndexed: 'unique',
+        db: { nativeType: 'Text', map: 'full_name' },
+      })
+
+      const result = field.getPrismaType!('fullName', 'postgresql', 'User', KEYSTONE_COMPAT)
+
+      // nativeType → default → unique → map, matching the builder's modifier order.
+      expect(result.modifiers).toBe('@db.Text @default("") @unique @map("full_name")')
+    })
+  })
+
+  describe('with keystoneCompat OFF (default)', () => {
+    it('emits no default for a required text field when the flag is omitted', () => {
+      const field = text({ validation: { isRequired: true } })
+
+      const result = field.getPrismaType!('name', 'sqlite', 'User')
+
+      expect(result.modifiers).toBeUndefined()
+    })
+
+    it('emits no default for a required text field when the flag is explicitly false', () => {
+      const field = text({ validation: { isRequired: true } })
+
+      const result = field.getPrismaType!('name', 'sqlite', 'User', false)
+
+      expect(result.modifiers).toBeUndefined()
+    })
+
+    it('still honours an explicit defaultValue when the flag is off', () => {
+      const field = text({ validation: { isRequired: true }, defaultValue: 'PLEASE_UPDATE' })
+
+      const result = field.getPrismaType!('status', 'sqlite', 'Account', false)
+
+      expect(result.modifiers).toBe('@default("PLEASE_UPDATE")')
+    })
+  })
+
+  describe('non-text fields are unaffected by the flag', () => {
+    it('does not give a required integer field an empty-string default under keystoneCompat', () => {
+      const field = integer({ validation: { isRequired: true } })
+
+      const result = field.getPrismaType!('count', 'sqlite', 'Widget', KEYSTONE_COMPAT)
+
+      expect(result.type).toBe('Int')
+      expect(result.modifiers ?? '').not.toContain('@default')
+    })
+  })
+})

package/src/hooks/index.ts

@@ -2,6 +2,7 @@ import type { Hooks } from '../config/types.js'
 import type { AccessContext } from '../access/types.js'
 import type { FieldConfig } from '../config/types.js'
 import { validateWithZod } from '../validation/schema.js'
+import { checkFieldAccess } from '../access/field-access.js'
 
 /**
  * Validation error collection
@@ -213,6 +214,275 @@ export async function executeAfterOperation<
   await hooks.afterOperation(args as Parameters<typeof hooks.afterOperation>[0])
 }
 
+/**
+ * Execute field-level resolveInput hooks
+ * Allows fields to transform their input values before database write
+ */
+export async function executeFieldResolveInputHooks(
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  inputData: Record<string, any>,
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  resolvedData: Record<string, any>,
+  fields: Record<string, FieldConfig>,
+  operation: 'create' | 'update',
+  context: AccessContext,
+  listKey: string,
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  item?: any,
+): Promise<Record<string, unknown>> {
+  let result = { ...resolvedData }
+
+  for (const [fieldKey, fieldConfig] of Object.entries(fields)) {
+    // Skip if field not in data
+    if (!(fieldKey in result)) continue
+
+    // A field's resolveInput produces its resolved value; for most fields that
+    // value is stored back under the same key. Multi-column fields additionally
+    // split that value across their physical columns below.
+    let resolvedValue: unknown = result[fieldKey]
+
+    if (fieldConfig.hooks?.resolveInput) {
+      // Execute field hook
+      // Type assertion is safe here because hooks are typed correctly in field definitions
+      // and we're working with runtime values that match those types
+      resolvedValue = await fieldConfig.hooks.resolveInput({
+        listKey,
+        fieldKey,
+        operation,
+        inputData,
+        item,
+        resolvedData: { ...result }, // Pass a copy to avoid mutation affecting recorded args
+        context,
+      } as Parameters<typeof fieldConfig.hooks.resolveInput>[0])
+    } else if (!fieldConfig.splitColumns) {
+      // No resolveInput and not a multi-column field — nothing to do.
+      continue
+    }
+
+    if (fieldConfig.splitColumns) {
+      // Multi-column field (e.g. storage image()/file() in Keystone-parity
+      // mode): replace the single logical key with its per-part columns so the
+      // write payload targets the live columns instead of a single one.
+      //
+      // The split removes the logical key from the payload BEFORE the
+      // canonical writable-field filter (`filterWritableFields`) runs, and the
+      // raw per-part column keys are not in `fieldConfigs` — so that later
+      // filter cannot enforce this field's own write access. Enforce it HERE,
+      // using the canonical field-access evaluator with the SAME arguments the
+      // write pipeline uses. A single-column field denied by `update`/`create`
+      // is simply omitted from the write; a denied multi-column field must
+      // likewise contribute NONE of its per-part columns. (sudo bypasses via
+      // `checkFieldAccess`.)
+      const canWrite = await checkFieldAccess(fieldConfig.access, operation, {
+        session: context.session,
+        item,
+        context,
+        inputData,
+      })
+      if (!canWrite) {
+        // Denied: drop the logical key and write none of its columns — exactly
+        // as filterWritableFields drops a denied single-column field.
+        const next = { ...result }
+        delete next[fieldKey]
+        result = next
+        continue
+      }
+      const columns = fieldConfig.splitColumns(fieldKey, resolvedValue)
+      // Drop the logical key (it is not a real column) and merge the columns.
+      const next = { ...result, ...columns }
+      delete next[fieldKey]
+      result = next
+    } else {
+      // Create new object with updated field to avoid mutating the passed reference
+      result = { ...result, [fieldKey]: resolvedValue }
+    }
+  }
+
+  return result
+}
+
+/**
+ * Execute field-level validate hooks
+ * Allows fields to perform custom validation after resolveInput but before database write
+ */
+export async function executeFieldValidateHooks(
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  inputData: Record<string, any> | undefined,
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  resolvedData: Record<string, any> | undefined,
+  fields: Record<string, FieldConfig>,
+  operation: 'create' | 'update' | 'delete',
+  context: AccessContext,
+  listKey: string,
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  item?: any,
+): Promise<void> {
+  const errors: string[] = []
+  const fieldErrors: Record<string, string> = {}
+
+  const addValidationError = (fieldKey: string) => (msg: string) => {
+    errors.push(msg)
+    fieldErrors[fieldKey] = msg
+  }
+
+  for (const [fieldKey, fieldConfig] of Object.entries(fields)) {
+    // Support both 'validate' (new) and 'validateInput' (deprecated) for backwards compatibility
+    const validateHook = fieldConfig.hooks?.validate ?? fieldConfig.hooks?.validateInput
+    if (!validateHook) continue
+
+    // Execute field hook
+    // Type assertion is safe here because hooks are typed correctly in field definitions
+    if (operation === 'delete') {
+      await validateHook({
+        listKey,
+        fieldKey,
+        operation: 'delete',
+        item,
+        context,
+        addValidationError: addValidationError(fieldKey),
+      } as Parameters<typeof validateHook>[0])
+    } else if (operation === 'create') {
+      await validateHook({
+        listKey,
+        fieldKey,
+        operation: 'create',
+        inputData,
+        item: undefined,
+        resolvedData,
+        context,
+        addValidationError: addValidationError(fieldKey),
+      } as Parameters<typeof validateHook>[0])
+    } else {
+      // operation === 'update'
+      await validateHook({
+        listKey,
+        fieldKey,
+        operation: 'update',
+        inputData,
+        item,
+        resolvedData,
+        context,
+        addValidationError: addValidationError(fieldKey),
+      } as Parameters<typeof validateHook>[0])
+    }
+  }
+
+  if (errors.length > 0) {
+    throw new ValidationError(errors, fieldErrors)
+  }
+}
+
+/**
+ * Execute field-level beforeOperation hooks (side effects only)
+ * Allows fields to perform side effects before database write
+ */
+export async function executeFieldBeforeOperationHooks(
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  inputData: Record<string, any>,
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  resolvedData: Record<string, any>,
+  fields: Record<string, FieldConfig>,
+  operation: 'create' | 'update' | 'delete',
+  context: AccessContext,
+  listKey: string,
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  item?: any,
+): Promise<void> {
+  for (const [fieldKey, fieldConfig] of Object.entries(fields)) {
+    // Skip if no hooks defined
+    if (!fieldConfig.hooks?.beforeOperation) continue
+    // Skip if field not in data (for create/update)
+    if (operation !== 'delete' && !(fieldKey in resolvedData)) continue
+
+    // Execute field hook (side effects only, no return value used)
+    // Type assertion is safe here because hooks are typed correctly in field definitions
+    if (operation === 'delete') {
+      await fieldConfig.hooks.beforeOperation({
+        listKey,
+        fieldKey,
+        operation: 'delete',
+        item,
+        context,
+      } as Parameters<typeof fieldConfig.hooks.beforeOperation>[0])
+    } else if (operation === 'create') {
+      await fieldConfig.hooks.beforeOperation({
+        listKey,
+        fieldKey,
+        operation: 'create',
+        inputData,
+        resolvedData,
+        context,
+      } as Parameters<typeof fieldConfig.hooks.beforeOperation>[0])
+    } else {
+      // operation === 'update'
+      await fieldConfig.hooks.beforeOperation({
+        listKey,
+        fieldKey,
+        operation: 'update',
+        inputData,
+        item,
+        resolvedData,
+        context,
+      } as Parameters<typeof fieldConfig.hooks.beforeOperation>[0])
+    }
+  }
+}
+
+/**
+ * Execute field-level afterOperation hooks (side effects only)
+ * Allows fields to perform side effects after database operations
+ */
+export async function executeFieldAfterOperationHooks(
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  item: any,
+  inputData: Record<string, unknown> | undefined,
+  resolvedData: Record<string, unknown> | undefined,
+  fields: Record<string, FieldConfig>,
+  operation: 'create' | 'update' | 'delete',
+  context: AccessContext,
+  listKey: string,
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  originalItem?: any,
+): Promise<void> {
+  for (const [fieldKey, fieldConfig] of Object.entries(fields)) {
+    // Skip if no hooks defined
+    if (!fieldConfig.hooks?.afterOperation) continue
+
+    // Execute field hook (side effects only, no return value used)
+    if (operation === 'delete') {
+      await fieldConfig.hooks.afterOperation({
+        listKey,
+        fieldKey,
+        operation: 'delete',
+        originalItem,
+        context,
+      } as Parameters<typeof fieldConfig.hooks.afterOperation>[0])
+    } else if (operation === 'create') {
+      await fieldConfig.hooks.afterOperation({
+        listKey,
+        fieldKey,
+        operation: 'create',
+        inputData,
+        item,
+        resolvedData,
+        context,
+      } as Parameters<typeof fieldConfig.hooks.afterOperation>[0])
+    } else {
+      // operation === 'update'
+      await fieldConfig.hooks.afterOperation({
+        listKey,
+        fieldKey,
+        operation: 'update',
+        inputData,
+        originalItem,
+        item,
+        resolvedData,
+        context,
+      } as Parameters<typeof fieldConfig.hooks.afterOperation>[0])
+    }
+  }
+}
+
 /**
  * Validate field-level validation rules using Zod
  * Checks isRequired, length constraints, etc.

package/src/index.test.ts

@@ -0,0 +1,50 @@
+import { describe, it, expect, expectTypeOf } from 'vitest'
+// Import from the package root entry point exactly as the docs / CHANGELOG /
+// migrate-context-calls skill instruct consumers to. If the root `index.ts`
+// stops re-exporting the query API, this file fails to type-check / run,
+// preventing a silent regression (issue #496).
+import { defineFragment, runQuery, runQueryOne } from './index.js'
+import type { ResultOf, RelationSelector, QueryArgs } from './index.js'
+
+// ─────────────────────────────────────────────────────────────
+// Stand-in model type (mirrors a Prisma-generated type)
+// ─────────────────────────────────────────────────────────────
+
+type User = {
+  id: string
+  name: string
+  email: string
+}
+
+describe('@opensaas/stack-core root entry point — query API re-exports (issue #496)', () => {
+  it('re-exports the runtime query functions from the package root', () => {
+    expect(typeof defineFragment).toBe('function')
+    expect(typeof runQuery).toBe('function')
+    expect(typeof runQueryOne).toBe('function')
+  })
+
+  it('defineFragment imported from the root produces a usable fragment', () => {
+    const userFragment = defineFragment<User>()({ id: true, name: true } as const)
+
+    expect(userFragment._type).toBe('fragment')
+    expect(userFragment._fields).toEqual({ id: true, name: true })
+  })
+
+  it('exposes ResultOf as a usable type alias from the root', () => {
+    const userFragment = defineFragment<User>()({ id: true, name: true } as const)
+    expect(userFragment._type).toBe('fragment')
+
+    // Type-level assertion: ResultOf<typeof fragment> narrows to the selection.
+    expectTypeOf<ResultOf<typeof userFragment>>().toEqualTypeOf<{ id: string; name: string }>()
+  })
+
+  it('exposes QueryArgs and RelationSelector as usable types from the root', () => {
+    // Type-level usage — these annotations only compile if the types resolve
+    // from the root entry point.
+    const args: QueryArgs = { where: { id: 'abc' }, take: 5 }
+    expect(args.take).toBe(5)
+
+    const selector: RelationSelector<User> = defineFragment<User>()({ id: true } as const)
+    expectTypeOf(selector).not.toBeNever()
+  })
+})

package/src/index.ts

@@ -1,105 +1,58 @@
-// Config system
+// ───────────────────────────────────────────────────────────────
+// @opensaas/stack-core — consumer entry point
+//
+// The everyday surface for defining a config and using a context.
+//   • Field builders            → '@opensaas/stack-core/fields'
+//   • Plugin / field authoring  → '@opensaas/stack-core/extend'
+//   • MCP runtime               → '@opensaas/stack-core/mcp'
+// Internal plumbing lives on '@opensaas/stack-core/internal' (unstable).
+// ───────────────────────────────────────────────────────────────
+
+// Config builders
 export { config, list } from './config/index.js'
+
+// Config types a consumer annotates with.
+// Concrete field-config types (TextField, …) live on '@opensaas/stack-core/fields'
+// alongside their builders.
 export type {
   OpenSaasConfig,
+  OutputConfig,
   ListConfig,
+  DatabaseConfig,
   FieldConfig,
-  BaseFieldConfig,
-  TextField,
-  IntegerField,
-  CheckboxField,
-  TimestampField,
-  PasswordField,
-  SelectField,
-  RelationshipField,
-  JsonField,
-  VirtualField,
-  TypeDescriptor,
-  TypeInfo,
   OperationAccess,
-  Hooks,
-  FieldHooks,
-  FieldsWithTypeInfo,
-  DatabaseConfig,
-  SessionConfig,
-  UIConfig,
-  ThemeConfig,
-  ThemePreset,
-  ThemeColors,
-  McpConfig,
-  McpToolsConfig,
-  McpAuthConfig,
-  ListMcpConfig,
-  McpCustomTool,
-  FileMetadata,
-  ImageMetadata,
-  ImageTransformationResult,
-  // Plugin system types
-  Plugin,
-  PluginContext,
-  GeneratedFiles,
-  // List-level hook argument types
-  ResolveInputHookArgs,
-  ValidateHookArgs,
-  BeforeOperationHookArgs,
-  AfterOperationHookArgs,
-  // Field-level hook argument types
-  FieldResolveInputHookArgs,
-  FieldValidateHookArgs,
-  FieldBeforeOperationHookArgs,
-  FieldAfterOperationHookArgs,
-  FieldResolveOutputHookArgs,
 } from './config/index.js'
 
-// Access control
+// Access control — the types a consumer writes against
 export type {
   AccessControl,
   FieldAccess,
   Session,
   AccessContext,
   PrismaFilter,
-  AccessControlledDB,
-  StorageUtils,
-  AugmentedFindMany,
-  AugmentedFindUnique,
-  FindManyQueryArgs,
 } from './access/index.js'
 
-// Context
+// Context factory
 export { getContext } from './context/index.js'
-export type { PrismaClientLike } from './access/types.js'
-export type { ServerActionProps } from './context/index.js'
 
-// Utilities
-export {
-  getDbKey,
-  getUrlKey,
-  getListKeyFromUrl,
-  pascalToCamel,
-  pascalToKebab,
-  kebabToPascal,
-  kebabToCamel,
-} from './lib/case-utils.js'
+// Naming utilities (documented public helpers; used for URLs and db keys)
+export { getDbKey, getUrlKey, getListKeyFromUrl } from './lib/case-utils.js'
 
-// Hooks and validation
+// Validation error surfaced by write operations
 export { ValidationError } from './hooks/index.js'
-export { validateWithZod, generateZodSchema } from './validation/schema.js'
 
-// Password utilities
-export {
-  hashPassword,
-  comparePassword,
-  isHashedPassword,
-  HashedPassword,
-} from './utils/password.js'
+// Field self-containment validation — checks each field implements the
+// generation contract (getPrismaType / getTypeScriptType / getZodSchema, or
+// getPrismaRelation for relationships) so a misimplemented field fails early
+// with a clear per-field message instead of deep inside generation.
+export { validateFieldConfig, validateConfigFields } from './validation/field-config.js'
+export type { FieldConfigValidationError } from './validation/field-config.js'
 
-// Query utilities — fragment-based, type-safe query helpers
+// Fragment-based query API — composable, type-safe reads that mirror
+// Keystone's GraphQL fragments without a GraphQL runtime. The migration
+// guide, CHANGELOG, and migrate-context-calls skill all advertise importing
+// these from the root entry point. The internal runtime helpers (isFragment,
+// buildInclude, pickFields) and the Fragment/FieldSelection types stay off the
+// root surface — those live on '@opensaas/stack-core/internal'.
 export { defineFragment, runQuery, runQueryOne } from './query/index.js'
-export type {
-  Fragment,
-  FieldSelection,
-  ResultOf,
-  RelationSelector,
-  QueryArgs,
-  QueryRunnerContext,
-} from './query/index.js'
+export type { ResultOf, RelationSelector, QueryArgs } from './query/index.js'

package/src/internal.ts

@@ -0,0 +1,49 @@
+// ───────────────────────────────────────────────────────────────
+// @opensaas/stack-core/internal
+//
+// @internal — plumbing shared between the @opensaas/* packages and the
+// code emitted by the generator (`.opensaas/`). NOT a public API: these
+// exports carry NO semver guarantees and may change or disappear in any
+// release. Application authors should never import from this path; use
+// the root entry point, `/fields`, or `/extend` instead.
+// ───────────────────────────────────────────────────────────────
+
+// Runtime context internals consumed by generated `.opensaas/` code
+export type { ServerActionProps } from './context/index.js'
+export type {
+  PrismaClientLike,
+  AccessControlledDB,
+  StorageUtils,
+  AugmentedFindMany,
+  AugmentedFindUnique,
+  FindManyQueryArgs,
+} from './access/types.js'
+
+// Typed-query internals (Fragment/FieldSelection appear in generated types)
+export type { Fragment, FieldSelection } from './query/index.js'
+
+// Password hashing internals (the password field emits HashedPassword into generated types)
+export {
+  hashPassword,
+  comparePassword,
+  isHashedPassword,
+  HashedPassword,
+} from './utils/password.js'
+
+// Case conversion helpers used by sibling packages
+export { pascalToCamel, pascalToKebab, kebabToPascal, kebabToCamel } from './lib/case-utils.js'
+
+// Zod schema helpers used internally for validation
+export { validateWithZod, generateZodSchema } from './validation/schema.js'
+
+// Config-shape sub-types consumed by sibling packages (not part of the consumer surface)
+export type {
+  DatabaseConfig,
+  SessionConfig,
+  ThemeConfig,
+  ThemePreset,
+  ThemeColors,
+  FileMetadata,
+  ImageMetadata,
+  ImageTransformationResult,
+} from './config/index.js'

package/src/mcp/handler.ts

@@ -410,8 +410,6 @@ async function handleToolsCall(
   const toolName = params?.name
   const toolArgs = params?.arguments || {}
 
-  console.log('Handling tool call:', toolName, toolArgs)
-
   if (!toolName) {
     return new Response(
       JSON.stringify({