@opensaas/stack-core 0.21.0 → 0.23.0

package/src/fields/format-prisma-default.test.ts

@@ -0,0 +1,64 @@
+import { describe, it, expect } from 'vitest'
+import { formatPrismaDefault, type PrismaDefaultFieldType } from './format-prisma-default.js'
+
+describe('formatPrismaDefault', () => {
+  describe('table-driven serialisation', () => {
+    const cases: Array<{
+      name: string
+      value: unknown
+      fieldType: PrismaDefaultFieldType
+      expected: string | undefined
+    }> = [
+      // text
+      {
+        name: 'non-empty string',
+        value: 'PLEASE_UPDATE',
+        fieldType: 'text',
+        expected: '"PLEASE_UPDATE"',
+      },
+      { name: 'empty string', value: '', fieldType: 'text', expected: '""' },
+      {
+        name: 'string with embedded quotes',
+        value: 'say "hi"',
+        fieldType: 'text',
+        expected: '"say \\"hi\\""',
+      },
+      // integer
+      { name: 'integer', value: 3550, fieldType: 'integer', expected: '3550' },
+      { name: 'zero integer', value: 0, fieldType: 'integer', expected: '0' },
+      { name: 'negative integer', value: -7, fieldType: 'integer', expected: '-7' },
+      // json
+      { name: 'JSON array', value: [1, 2, 3, 4, 5], fieldType: 'json', expected: '"[1,2,3,4,5]"' },
+      {
+        name: 'JSON object',
+        value: { a: 1, b: 'two' },
+        fieldType: 'json',
+        expected: '"{\\"a\\":1,\\"b\\":\\"two\\"}"',
+      },
+      { name: 'empty array', value: [], fieldType: 'json', expected: '"[]"' },
+      { name: 'empty object', value: {}, fieldType: 'json', expected: '"{}"' },
+      // undefined → no default for every field type
+      { name: 'undefined text', value: undefined, fieldType: 'text', expected: undefined },
+      { name: 'undefined integer', value: undefined, fieldType: 'integer', expected: undefined },
+      { name: 'undefined json', value: undefined, fieldType: 'json', expected: undefined },
+    ]
+
+    it.each(cases)('serialises $name → $expected', ({ value, fieldType, expected }) => {
+      expect(formatPrismaDefault(value, fieldType)).toBe(expected)
+    })
+  })
+
+  it('produces canonical space-free JSON (no extra whitespace)', () => {
+    // Guards against pretty-printed JSON sneaking into the literal.
+    expect(formatPrismaDefault([1, 2, 3], 'json')).toBe('"[1,2,3]"')
+    expect(formatPrismaDefault({ nested: { x: [1] } }, 'json')).toBe(
+      '"{\\"nested\\":{\\"x\\":[1]}}"',
+    )
+  })
+
+  it('wraps a JSON string default in escaped quotes around the JSON text', () => {
+    // A string value under the json field type is itself valid JSON; it gets
+    // double-serialised: inner JSON.stringify("hi") = "\"hi\"", then wrapped.
+    expect(formatPrismaDefault('hi', 'json')).toBe('"\\"hi\\""')
+  })
+})

package/src/fields/format-prisma-default.ts

@@ -0,0 +1,67 @@
+/**
+ * Field types that {@link formatPrismaDefault} knows how to serialise.
+ *
+ * Kept narrow on purpose: only the scalar fields whose `defaultValue` maps to a
+ * Prisma `@default(...)` literal via this shared helper. Other fields (e.g.
+ * `checkbox`, `decimal`, `timestamp`) format their own defaults inline because
+ * their literal forms diverge (`@default(now())`, bare booleans, etc.).
+ */
+export type PrismaDefaultFieldType = 'text' | 'integer' | 'json'
+
+/**
+ * Serialise a field's `defaultValue` into the inner literal of a Prisma
+ * `@default(...)` attribute.
+ *
+ * Pure: no I/O, no field-builder coupling. Returns just the literal (the caller
+ * wraps it in `@default(...)`), so it composes with whatever modifier string a
+ * field builder assembles. Returns `undefined` when there is nothing to emit, so
+ * a field with no `defaultValue` produces no `@default(...)` at all.
+ *
+ * Serialisation rules (Keystone 6 compatible):
+ * - `integer` → bare numeric literal, e.g. `3550` → `@default(3550)`.
+ * - `text` → double-quoted string literal, e.g. `PLEASE_UPDATE` → `@default("PLEASE_UPDATE")`.
+ * - `json` → Keystone's JSON-literal form: `JSON.stringify` the value with no
+ *   extra whitespace, then wrap the result in escaped double quotes, e.g.
+ *   `[1,2,3,4,5]` → `@default("[1,2,3,4,5]")` and `[]` → `@default("[]")`.
+ *
+ * Nullability (the `?` modifier) is the caller's concern and is handled
+ * independently of the default — this function never touches it.
+ *
+ * @param value - The configured `defaultValue` (the field builder's `defaultValue`).
+ * @param fieldType - The field's discriminator, selecting the serialisation rule.
+ * @returns The literal to place inside `@default(...)`, or `undefined` when
+ *   `value` is `undefined` (no default to emit).
+ */
+export function formatPrismaDefault(
+  value: unknown,
+  fieldType: PrismaDefaultFieldType,
+): string | undefined {
+  if (value === undefined) {
+    return undefined
+  }
+
+  switch (fieldType) {
+    case 'integer':
+      // Bare numeric literal — Prisma expects no quotes for Int defaults.
+      return String(value)
+
+    case 'text':
+      // Double-quoted string literal. The value is escaped via JSON.stringify so
+      // embedded quotes/backslashes are handled correctly.
+      return JSON.stringify(String(value))
+
+    case 'json': {
+      // Keystone's JSON-literal form: canonical, space-free JSON.stringify of the
+      // value, then wrap the whole serialised string in escaped double quotes so
+      // Prisma stores the JSON text as the column default. The outer
+      // JSON.stringify produces the escaped, double-quoted wrapper.
+      const serialised = JSON.stringify(value)
+      // JSON.stringify can return undefined for unserialisable values (e.g. a
+      // function). Treat that as "no default" rather than emitting `@default()`.
+      if (serialised === undefined) {
+        return undefined
+      }
+      return JSON.stringify(serialised)
+    }
+  }
+}

package/src/fields/index.ts

@@ -16,6 +16,7 @@ import type {
   PrismaRelationResult,
 } from '../config/types.js'
 import { hashPassword, isHashedPassword, HashedPassword } from '../utils/password.js'
+import { formatPrismaDefault } from './format-prisma-default.js'
 
 // Field-config types live here, alongside the builders that produce them.
 // (The umbrella `FieldConfig` and authoring `BaseFieldConfig` stay on the root
@@ -33,6 +34,7 @@ export type {
   JsonField,
   VirtualField,
   PrismaRelationResult,
+  MultiColumnPrismaResult,
 } from '../config/types.js'
 
 /**
@@ -87,7 +89,12 @@ export function text<
 
       return !isRequired ? withMax.optional().nullable() : withMax
     },
-    getPrismaType: (_fieldName: string) => {
+    getPrismaType: (
+      _fieldName: string,
+      _provider?: string,
+      _listName?: string,
+      keystoneCompat?: boolean,
+    ) => {
       const validation = options?.validation
       const db = options?.db
       const isRequired = validation?.isRequired
@@ -104,6 +111,23 @@ export function text<
         modifiers += ` @db.${db.nativeType}`
       }
 
+      // Default value. An explicit `defaultValue` always wins. When none is set
+      // and Keystone-compat mode is on, a non-null text column gets Keystone's
+      // implicit empty-string default. Both go through formatPrismaDefault, so
+      // the empty-string literal (`""`) is produced the same way as any other
+      // text default. Independent of the nullable `?` modifier above — the
+      // default never overwrites nullability.
+      const defaultSource =
+        options?.defaultValue !== undefined
+          ? options.defaultValue
+          : keystoneCompat && !isNullable
+            ? ''
+            : undefined
+      const defaultLiteral = formatPrismaDefault(defaultSource, 'text')
+      if (defaultLiteral !== undefined) {
+        modifiers += ` @default(${defaultLiteral})`
+      }
+
       // Unique/index modifiers
       if (options?.isIndexed === 'unique') {
         modifiers += ' @unique'
@@ -182,6 +206,13 @@ export function integer<
         modifiers += ` @db.${db.nativeType}`
       }
 
+      // Default value if provided (bare numeric literal). Independent of the
+      // nullable `?` modifier above — the default never overwrites nullability.
+      const defaultLiteral = formatPrismaDefault(options?.defaultValue, 'integer')
+      if (defaultLiteral !== undefined) {
+        modifiers += ` @default(${defaultLiteral})`
+      }
+
       // Map modifier
       if (db?.map) {
         modifiers += ` @map("${db.map}")`
@@ -677,7 +708,6 @@ export function password<TTypeInfo extends import('../config/types.js').TypeInfo
       resolveInput: async ({ inputData, fieldKey }: { inputData: any; fieldKey: string }) => {
         // Skip if undefined or null (allows partial updates)
         const inputValue = inputData[fieldKey]
-        console.log('Password resolveInput called with value:', inputValue)
         if (inputValue === undefined || inputValue === null) {
           return inputValue
         }
@@ -823,21 +853,35 @@ export function select<
     },
     getPrismaType: (fieldName: string, _provider?: string, listName?: string) => {
       const isRequired = options.validation?.isRequired
+      const hasDefault = options.defaultValue !== undefined
+      // Nullability rules (Keystone parity):
+      //  - `db.isNullable` is an explicit override and always wins. Setting it
+      //    `true` forces the `?` even when a `defaultValue` is present.
+      //  - Otherwise a select is nullable only when it is neither required nor
+      //    carrying a default: a `defaultValue` makes the column NOT NULL (the
+      //    long-standing default behaviour). This mirrors the previous logic
+      //    where a present default overwrote the `?`.
+      // Nullability and the default are assembled independently with `+=`
+      // (mirroring text/integer) so the default never overwrites the `?`.
+      const isNullable = options.db?.isNullable ?? (!isRequired && !hasDefault)
       let modifiers = ''
 
+      // Optional modifier
+      if (isNullable) {
+        modifiers += '?'
+      }
+
       if (isNativeEnum) {
-        // Derive enum name from list name + field name in PascalCase
+        // Enum type name: explicit `db.enumName` wins, otherwise derive from
+        // list name + field name in PascalCase. The same name is used for the
+        // generated enum block (via `result.type`) and the column reference.
         const capitalizedField = fieldName.charAt(0).toUpperCase() + fieldName.slice(1)
-        const enumName = listName ? `${listName}${capitalizedField}` : capitalizedField
-
-        // Required fields don't get the ? modifier
-        if (!isRequired) {
-          modifiers = '?'
-        }
+        const derivedEnumName = listName ? `${listName}${capitalizedField}` : capitalizedField
+        const enumName = options.db?.enumName ?? derivedEnumName
 
         // Add default value if provided (no quotes for enum values)
-        if (options.defaultValue !== undefined) {
-          modifiers = ` @default(${options.defaultValue})`
+        if (hasDefault) {
+          modifiers += ` @default(${options.defaultValue})`
         }
 
         // Map modifier
@@ -854,14 +898,9 @@ export function select<
 
       // String type (default)
 
-      // Required fields don't get the ? modifier
-      if (!isRequired) {
-        modifiers = '?'
-      }
-
       // Add default value if provided
-      if (options.defaultValue !== undefined) {
-        modifiers = ` @default("${options.defaultValue}")`
+      if (hasDefault) {
+        modifiers += ` @default("${options.defaultValue}")`
       }
 
       // Map modifier
@@ -1300,6 +1339,14 @@ export function json<
         modifiers += ` @db.${db.nativeType}`
       }
 
+      // Default value if provided. Uses Keystone's JSON-literal form: canonical
+      // (space-free) JSON wrapped in escaped double quotes. Independent of the
+      // nullable `?` modifier above — the default never overwrites nullability.
+      const defaultLiteral = formatPrismaDefault(options?.defaultValue, 'json')
+      if (defaultLiteral !== undefined) {
+        modifiers += ` @default(${defaultLiteral})`
+      }
+
       // Map modifier
       if (db?.map) {
         modifiers += ` @map("${db.map}")`

package/src/fields/select.test.ts

@@ -52,6 +52,48 @@ describe('select field builder', () => {
       expect(result.modifiers).toBe(' @default("draft")')
     })
 
+    it('should emit NOT NULL (no ?) for optional string select with a default', () => {
+      const field = select({
+        options: [
+          { label: 'Draft', value: 'draft' },
+          { label: 'Published', value: 'published' },
+        ],
+        defaultValue: 'draft',
+      })
+
+      const result = field.getPrismaType!('status', 'sqlite', 'Post')
+      // Default behaviour: a present default makes the column NOT NULL
+      expect(result.modifiers).toBe(' @default("draft")')
+      expect(result.modifiers).not.toContain('?')
+    })
+
+    it('should force ? with db.isNullable even when a default is present (string)', () => {
+      const field = select({
+        options: [
+          { label: 'Draft', value: 'draft' },
+          { label: 'Published', value: 'published' },
+        ],
+        defaultValue: 'draft',
+        db: { isNullable: true },
+      })
+
+      const result = field.getPrismaType!('status', 'sqlite', 'Post')
+      expect(result.type).toBe('String')
+      expect(result.modifiers).toBe('? @default("draft")')
+    })
+
+    it('should keep ? from db.isNullable for a required string select with default', () => {
+      const field = select({
+        options: [{ label: 'Draft', value: 'draft' }],
+        defaultValue: 'draft',
+        validation: { isRequired: true },
+        db: { isNullable: true },
+      })
+
+      const result = field.getPrismaType!('status', 'sqlite', 'Post')
+      expect(result.modifiers).toBe('? @default("draft")')
+    })
+
     it('should generate union TypeScript type from options', () => {
       const field = select({
         options: [
@@ -205,6 +247,63 @@ describe('select field builder', () => {
       expect(result.modifiers).not.toContain('"')
     })
 
+    it('should emit NOT NULL (no ?) for optional enum select with a default', () => {
+      const field = select({
+        options: [
+          { label: 'Draft', value: 'draft' },
+          { label: 'Published', value: 'published' },
+        ],
+        db: { type: 'enum' },
+        defaultValue: 'draft',
+      })
+
+      const result = field.getPrismaType!('status', 'sqlite', 'Post')
+      expect(result.modifiers).toBe(' @default(draft)')
+      expect(result.modifiers).not.toContain('?')
+    })
+
+    it('should force ? with db.isNullable even when a default is present (enum)', () => {
+      const field = select({
+        options: [
+          { label: 'Draft', value: 'draft' },
+          { label: 'Published', value: 'published' },
+        ],
+        db: { type: 'enum', isNullable: true },
+        defaultValue: 'draft',
+      })
+
+      const result = field.getPrismaType!('status', 'sqlite', 'Post')
+      expect(result.type).toBe('PostStatus')
+      expect(result.modifiers).toBe('? @default(draft)')
+    })
+
+    it('should override the derived enum name with db.enumName', () => {
+      const field = select({
+        options: [
+          { label: 'Open', value: 'open' },
+          { label: 'Closed', value: 'closed' },
+        ],
+        db: { type: 'enum', enumName: 'AccountNoteStatusType' },
+      })
+
+      const result = field.getPrismaType!('status', 'sqlite', 'AccountNote')
+      // result.type drives both the enum block name and the column reference
+      expect(result.type).toBe('AccountNoteStatusType')
+      expect(result.enumValues).toEqual(['open', 'closed'])
+    })
+
+    it('should ignore db.enumName for string (non-enum) selects', () => {
+      const field = select({
+        options: [{ label: 'Open', value: 'open' }],
+        // enumName only applies to native-enum selects; string selects stay String
+        db: { enumName: 'ShouldBeIgnored' },
+      })
+
+      const result = field.getPrismaType!('status', 'sqlite', 'AccountNote')
+      expect(result.type).toBe('String')
+      expect(result.enumValues).toBeUndefined()
+    })
+
     it('should include @map modifier for enum field with map option', () => {
       const field = select({
         options: [{ label: 'Draft', value: 'draft' }],

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
@@ -235,24 +236,66 @@ export async function executeFieldResolveInputHooks(
     // Skip if field not in data
     if (!(fieldKey in result)) continue
 
-    // Skip if no hooks defined
-    if (!fieldConfig.hooks?.resolveInput) 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]
 
-    // 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
-    const transformedValue = 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])
-
-    // Create new object with updated field to avoid mutating the passed reference
-    result = { ...result, [fieldKey]: transformedValue }
+    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

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