@quazardous/qdadm 2.4.5 → 2.6.0

package/README.md

@@ -137,6 +137,8 @@ This is the canonical Vite/Webpack pattern for Vue plugin singletons. The `file:
 
 Installing qdadm from npm (`@quazardous/qdadm@^1.19.3`) doesn't have this issue: the published tarball ships no `node_modules/`, so peers always resolve from the host. The trap is specific to `file:` / `workspace:` links onto a package that lives inside another monorepo.
 
+One more caveat: qdadm ships TypeScript sources, so with a `file:` link your `vue-tsc` / lint / test counters measure qdadm's **working tree**, not a released version. Any local qdadm edit moves your numbers with zero change on your side — don't calibrate quality ratchets or CI thresholds against a linked checkout; pin them to the published package your CI actually installs.
+
 ## License
 
 MIT

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@quazardous/qdadm",
-  "version": "2.4.5",
+  "version": "2.6.0",
   "description": "Vue 3 framework for admin dashboards with PrimeVue",
   "author": "quazardous",
   "license": "MIT",

package/src/components/editors/VanillaJsonEditor.vue

@@ -22,7 +22,13 @@ type JsonValue = Record<string, unknown> | unknown[] | string | null
 
 interface Props {
   modelValue?: JsonValue
-  mode?: Mode
+  /**
+   * Editor mode. String literals are accepted (#1253) so consumers never
+   * need to import the `Mode` enum from vanilla-jsoneditor (which is not
+   * a direct dependency of theirs); `Mode` itself is re-exported from
+   * '@quazardous/qdadm/editors' for those who want it.
+   */
+  mode?: Mode | 'tree' | 'text' | 'table'
   height?: string
   readOnly?: boolean
   mainMenuBar?: boolean
@@ -40,7 +46,7 @@ interface Props {
 
 const props = withDefaults(defineProps<Props>(), {
   modelValue: () => ({}),
-  mode: 'tree' as Mode,
+  mode: 'tree',
   height: '400px',
   readOnly: false,
   mainMenuBar: true,
@@ -100,7 +106,7 @@ onMounted(() => {
     target: containerRef.value,
     props: {
       content,
-      mode: props.mode,
+      mode: props.mode as Mode,
       readOnly: props.readOnly,
       mainMenuBar: props.mainMenuBar,
       navigationBar: props.navigationBar,
@@ -161,9 +167,9 @@ watch(() => props.modelValue, (newVal: JsonValue | undefined) => {
 }, { deep: true })
 
 // Watch mode changes
-watch(() => props.mode, (newMode: Mode | undefined) => {
+watch(() => props.mode, (newMode) => {
   if (editor && newMode) {
-    editor.updateProps({ mode: newMode })
+    editor.updateProps({ mode: newMode as Mode })
   }
 })
 

package/src/composables/useListPage.ts

@@ -35,6 +35,7 @@ import { useEntityItemPage, type ParentConfig, type UseEntityItemPageReturn } fr
 import { useActiveStack } from '../chain/useActiveStack.js'
 import { useI18n } from '../i18n/useI18n'
 import { formatDateOnly } from '../utils/formatters'
+import { humanizeFieldName } from '../utils/humanize'
 
 // Import types from dedicated types file
 import type {
@@ -260,26 +261,47 @@ export function useListPage<T = unknown>(config: UseListPageOptions<T>): UseList
   // when the i18n bundle has no translation for the field.
   const columnInlineHeaders = new Map<string, string | undefined>()
 
+  // One-shot per entity+field (#1255): the catalog winning over an explicit
+  // header is by design, but it must never happen silently — the day a key
+  // appears, the page author learns which inline header it shadows.
+  const warnedHeaderShadows = new Set<string>()
+  function warnHeaderShadow(field: string, i18nValue: string, explicit: string | undefined): void {
+    if (explicit === undefined || explicit === i18nValue) return
+    const key = `${entity}.${field}`
+    if (warnedHeaderShadows.has(key)) return
+    warnedHeaderShadows.add(key)
+    console.warn(
+      `[qdadm] column '${field}' (${entity}): i18n key entities.${entity}.fields.${field} ` +
+        `("${i18nValue}") shadows explicit header ("${explicit}") — the catalog wins by design; ` +
+        `drop the inline header or remove the key.`
+    )
+  }
+
   /**
-   * Resolve a column header: i18n hit on entities.{entity}.fields.{field} wins,
+   * Resolve a column header: i18n hit on entities.{entity}.fields.{field} wins
+   * (the inline `header` is the no-key fallback, not an absolute override),
    * otherwise the inline `header` option, otherwise a capitalized field name.
    */
   function resolveColumnHeader(field: string, inline?: string): string {
     if (entity && kernelI18n) {
       const trace = kernelI18n.resolve(`entities.${entity}.fields.${field}`)
-      if (trace.hit) return trace.result
+      if (trace.hit) {
+        warnHeaderShadow(field, trace.result, inline)
+        return trace.result
+      }
     }
     return inline || field.charAt(0).toUpperCase() + field.slice(1)
   }
 
   function addColumn(field: string, columnConfig: Partial<ColumnConfig> = {}): void {
     columnInlineHeaders.set(field, columnConfig.header)
+    // Resolved header LAST so the catalog wins at registration too (#1255) —
+    // previously the inline header survived until the first locale change
+    // flipped it to the i18n value, silently and inconsistently.
     columnsMap.value.set(field, {
       field,
-      header: resolveColumnHeader(field, columnConfig.header),
       ...columnConfig,
-      // Re-apply resolved header after spread so it wins over a stale inline.
-      ...(columnConfig.header ? {} : { header: resolveColumnHeader(field) }),
+      header: resolveColumnHeader(field, columnConfig.header),
     })
   }
 
@@ -294,6 +316,57 @@ export function useListPage<T = unknown>(config: UseListPageOptions<T>): UseList
     }
   })
 
+  /**
+   * Template-side column binding helper (#1255): spread onto a PrimeVue
+   * `<Column>` so `field` + `header` come from one source instead of being
+   * retyped in every list template:
+   *
+   * ```html
+   * <Column v-bind="list.column('botUuid')" sortable>
+   *   <template #body="{ data }">...</template>
+   * </Column>
+   * ```
+   *
+   * Header resolution: i18n key (`entities.{entity}.fields.{field}`) >
+   * `overrides.header` > inline header given to `addColumn` >
+   * `manager.fields[name].label` > humanized field name.
+   *
+   * NOTE the precedence truth (#1255): an inline `header` is the fallback
+   * used when no i18n key exists — NOT an absolute override. The catalog
+   * wins by design (or a hardcoded header would pin the column to one
+   * language); to pin a header, don't create the key. When a key shadows
+   * an explicit header with a different value, a one-shot dev warning
+   * announces it instead of letting the header change silently.
+   *
+   * Pure read — it never registers into columnsMap, so calling it during
+   * render is safe.
+   */
+  function column(name: string, overrides: Partial<ColumnConfig> = {}): ColumnConfig {
+    // Depend on the locale so headers re-render on locale change.
+    void i18nLocale.value
+
+    let header: string | undefined
+    if (entity && kernelI18n) {
+      const trace = kernelI18n.resolve(`entities.${entity}.fields.${name}`)
+      if (trace.hit) {
+        header = trace.result
+        // Both explicit sources are checked: per-call override AND the
+        // inline header registered via addColumn (values compared — a key
+        // that merely copies the header stays silent).
+        warnHeaderShadow(name, trace.result, overrides.header ?? columnInlineHeaders.get(name))
+      }
+    }
+    const fieldConfig = manager.getFieldConfig(name) as { label?: string } | null | undefined
+    header ??=
+      overrides.header ??
+      columnInlineHeaders.get(name) ??
+      fieldConfig?.label ??
+      humanizeFieldName(name)
+
+    const registered = columnsMap.value.get(name)
+    return { ...registered, ...overrides, field: name, header }
+  }
+
   function removeColumn(field: string): void {
     columnsMap.value.delete(field)
   }
@@ -1111,6 +1184,7 @@ export function useListPage<T = unknown>(config: UseListPageOptions<T>): UseList
 
     // Columns
     columns,
+    column,
     addColumn,
     removeColumn,
     updateColumn,

package/src/composables/useListPage.types.ts

@@ -61,6 +61,11 @@ export interface ConfirmService {
  */
 export interface ColumnConfig {
   field: string
+  /**
+   * Column header. When an i18n key `entities.{entity}.fields.{field}`
+   * exists, the catalog WINS — an inline header is the no-key fallback,
+   * not an absolute override (#1255). To pin a header, don't create the key.
+   */
   header?: string
   sortable?: boolean
   style?: string
@@ -347,6 +352,8 @@ export interface UseListPageReturn<T = unknown> {
 
   // Columns
   columns: ComputedRef<ColumnConfig[]>
+  /** v-bind column binding helper (#1255): field + header from one source */
+  column: (name: string, overrides?: Partial<ColumnConfig>) => ColumnConfig
   addColumn: (field: string, config?: Partial<ColumnConfig>) => void
   removeColumn: (field: string) => void
   updateColumn: (field: string, updates: Partial<ColumnConfig>) => void

package/src/editors/index.ts

@@ -10,3 +10,8 @@
 
 export { default as VanillaJsonEditor } from '../components/editors/VanillaJsonEditor.vue'
 export { default as JsonStructuredField } from '../components/editors/JsonStructuredField.vue'
+
+// Re-export the mode enum so consumers who want it don't need to depend on
+// vanilla-jsoneditor directly (#1253). String literals ('tree' | 'text' |
+// 'table') are accepted by VanillaJsonEditor's `mode` prop anyway.
+export { Mode } from 'vanilla-jsoneditor'

package/src/entity/EntityManager.interface.ts

@@ -13,6 +13,15 @@
  *
  * All interfaces accept an optional generic parameter `T` (default: `unknown`)
  * that flows through to method signatures for typed entity data.
+ *
+ * ## Optionality contract (#1253)
+ *
+ * These views describe the IMPLEMENTER'S MINIMUM, not a mirror of the
+ * EntityManager class. A member is REQUIRED iff qdadm's own composables
+ * call it unguarded (or capability coherence demands it — e.g. the four
+ * can* permission checks travel together). A member stays OPTIONAL only
+ * when it is a genuine capability a minimal manager-like need not carry;
+ * the reason is documented inline. `?` means "conditional", never "lazy".
  */
 
 import type { EntityBadge } from './EntityManager.types'
@@ -32,6 +41,9 @@ export interface EntityManagerBase<T = unknown> {
   labelField?: string | ((entity: T) => string)
   readOnly?: boolean
   getEntityLabel: (data: T) => string
+  // Optional BY DESIGN (#1253): part of the badge/severity presentation
+  // capability; call sites guard (e.g. useEntityItemShowPage checks
+  // `if (!manager.getEntityBadges)`).
   getEntityBadges?: (data: T) => Array<{ label: string; severity?: string }>
 }
 
@@ -41,7 +53,10 @@ export interface EntityManagerBase<T = unknown> {
  * Permission checks — used by guards, list pages, forms.
  */
 export interface EntityManagerPermissions<T = unknown> {
-  canRead?: (entity?: T) => boolean
+  // The four checks are ONE capability — a manager-like answering canUpdate
+  // but not canRead is not a smaller contract, it's an incoherent one. The
+  // `?` on canRead was a #1191 leftover (#1253).
+  canRead: (entity?: T) => boolean
   canCreate: () => boolean
   canUpdate: (entity?: T) => boolean
   canDelete: (entity?: T) => boolean
@@ -55,11 +70,18 @@ export interface EntityManagerPermissions<T = unknown> {
 export interface EntityManagerRead<T = unknown> extends EntityManagerBase<T>, EntityManagerPermissions<T> {
   get: (id: string | number, context?: unknown) => Promise<T>
   list: (params?: unknown, context?: unknown) => Promise<{ items: T[]; total?: number; fromCache?: boolean; [key: string]: unknown }>
-  query?: (params?: unknown, options?: { routingContext?: unknown }) => Promise<{ items: T[]; total?: number; fromCache?: boolean; [key: string]: unknown }>
+  // query/invalidateCache/getFieldConfig are required since #1253: they are
+  // unconditionally implemented on the class (prototype-applied) and called
+  // unguarded by list pages — the `?` was a #1191 leftover that forced
+  // consumer-side casts on base methods.
+  query: (params?: unknown, options?: { routingContext?: unknown }) => Promise<{ items: T[]; total?: number; fromCache?: boolean; [key: string]: unknown }>
   delete: (id: string | number, context?: unknown) => Promise<void>
   request: (method: string, path: string, options?: { data?: unknown }) => Promise<unknown>
-  invalidateCache?: () => void
-  localFilterThreshold?: number
+  invalidateCache: () => void
+  /** Field config lookup — read-side too since list column binding (#1255) */
+  getFieldConfig: (name: string) => unknown | null
+  /** Config-carrying property: always present on the class, VALUE nullable */
+  localFilterThreshold?: number | null
 }
 
 // ─── CRUD ────────────────────────────────────────────────────────────────────
@@ -71,11 +93,14 @@ export interface EntityManagerCrud<T = unknown> extends EntityManagerRead<T> {
   fields?: Record<string, unknown> | unknown[]
   getInitialData: () => Record<string, unknown>
   getFormFields: () => Array<{ name: string; [key: string]: unknown }>
-  getFieldConfig: (name: string) => unknown | null
+  // getFieldConfig inherited (required) from EntityManagerRead since #1253
   resolveReferenceOptions: (fieldName: string) => Promise<unknown[]>
   create: (data: unknown, context?: unknown) => Promise<T>
   update: (id: string | number, data: unknown, context?: unknown) => Promise<T>
   patch: (id: string | number, data: unknown, context?: unknown) => Promise<T>
+  // Optional BY DESIGN (#1253): the severity/badge presentation capability —
+  // a minimal manager-like need not carry it; every qdadm call site guards
+  // (`?.` or truthiness). The canonical class always provides it.
   hasSeverityMap?: (field: string) => boolean
   getSeverity?: (field: string, value: string | number, defaultSeverity?: string) => string
   getSeverityDescriptor?: (field: string, value: string | number, defaultSeverity?: string) => { severity: string; icon?: string; label?: string }

package/src/entity/EntityManager.ts

@@ -34,6 +34,8 @@ import type { NullSortMode } from '../query/clientFilter'
 
 // Re-export public types from types file
 export type {
+  StorageResolution,
+  ResolvedStorage,
   RoutingContext,
   PresaveContext,
   PostsaveContext,

package/src/gen/connectors/OpenAPIConnector.test.js

@@ -1,4 +1,4 @@
-import { describe, it, expect } from 'vitest'
+import { describe, it, expect, vi } from 'vitest'
 import { OpenAPIConnector } from './OpenAPIConnector'
 import sampleSpec from './__fixtures__/sample-openapi.json'
 
@@ -584,6 +584,258 @@ describe('OpenAPIConnector', () => {
 
       expect(result.warnings.some(w => w.code === 'UNRESOLVED_REF')).toBe(true)
     })
+
+    describe('EMPTY_OBJECT_SCHEMA detection (#1240)', () => {
+      // Build a spec with a single tasks entity whose `payload` field uses
+      // the given schema node.
+      function specWithPayload(payloadSchema) {
+        return {
+          openapi: '3.0.0',
+          paths: {
+            '/api/tasks/{id}': {
+              get: {
+                responses: {
+                  '200': {
+                    content: {
+                      'application/json': {
+                        schema: {
+                          type: 'object',
+                          properties: {
+                            data: {
+                              type: 'object',
+                              properties: {
+                                id: { type: 'string' },
+                                payload: payloadSchema
+                              }
+                            }
+                          }
+                        }
+                      }
+                    }
+                  }
+                }
+              }
+            }
+          }
+        }
+      }
+
+      function warningsFor(payloadSchema) {
+        const connector = new OpenAPIConnector()
+        const result = connector.parseWithWarnings(specWithPayload(payloadSchema))
+        return result.warnings.filter(w => w.code === 'EMPTY_OBJECT_SCHEMA')
+      }
+
+      it('warns on a bare object schema (no properties, no additionalProperties)', () => {
+        const warnings = warningsFor({ type: 'object' })
+        expect(warnings).toHaveLength(1)
+        expect(warnings[0].path).toBe('/api/tasks/{id}#payload')
+        expect(warnings[0].message).toContain('additionalProperties: true')
+      })
+
+      it('warns when properties is present but empty', () => {
+        expect(warningsFor({ type: 'object', properties: {} })).toHaveLength(1)
+      })
+
+      it('does not warn when additionalProperties is true', () => {
+        expect(warningsFor({ type: 'object', additionalProperties: true })).toHaveLength(0)
+      })
+
+      it('does not warn when additionalProperties is a sub-schema', () => {
+        expect(
+          warningsFor({ type: 'object', additionalProperties: { type: 'string' } })
+        ).toHaveLength(0)
+      })
+
+      it('does not warn when the object declares properties', () => {
+        expect(
+          warningsFor({ type: 'object', properties: { targets: { type: 'array' } } })
+        ).toHaveLength(0)
+      })
+
+      it('does not warn on composition schemas (oneOf/anyOf/allOf)', () => {
+        expect(
+          warningsFor({ type: 'object', oneOf: [{ type: 'object', properties: { a: { type: 'string' } } }] })
+        ).toHaveLength(0)
+        expect(
+          warningsFor({ type: 'object', allOf: [{ type: 'object', properties: { a: { type: 'string' } } }] })
+        ).toHaveLength(0)
+      })
+
+      it('does not warn on non-object types', () => {
+        expect(warningsFor({ type: 'string' })).toHaveLength(0)
+      })
+
+      it('still generates the field as a usable object type', () => {
+        const connector = new OpenAPIConnector()
+        const { schemas } = connector.parseWithWarnings(specWithPayload({ type: 'object' }))
+        const tasks = schemas.find(e => e.name === 'tasks')
+        expect(tasks.fields.payload).toBeDefined()
+        expect(tasks.fields.payload.type).toBe('object')
+      })
+
+      it('parse() logs collected warnings to console.warn', () => {
+        const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {})
+        try {
+          const connector = new OpenAPIConnector()
+          connector.parse(specWithPayload({ type: 'object' }))
+          const calls = warnSpy.mock.calls.map(args => args.join(' '))
+          expect(calls.some(line => line.includes('EMPTY') || line.includes('additionalProperties'))).toBe(true)
+          expect(calls.some(line => line.includes('/api/tasks/{id}#payload'))).toBe(true)
+        } finally {
+          warnSpy.mockRestore()
+        }
+      })
+    })
+  })
+
+  describe('inference options (#1255)', () => {
+    // /api/bots: GET item + POST with a partial body; lastSeen/uuid are
+    // response-only, name is writable, status declares readOnly in-schema.
+    const botsSpec = {
+      openapi: '3.0.0',
+      paths: {
+        '/api/bots/{id}': {
+          get: {
+            responses: {
+              '200': {
+                content: {
+                  'application/json': {
+                    schema: {
+                      type: 'object',
+                      properties: {
+                        data: {
+                          type: 'object',
+                          properties: {
+                            uuid: { type: 'string', format: 'uuid' },
+                            name: { type: 'string' },
+                            lastSeen: { type: 'string', format: 'date-time' },
+                            status: { type: 'string', readOnly: true },
+                            notes: { type: 'string', description: 'Operator notes' }
+                          }
+                        }
+                      }
+                    }
+                  }
+                }
+              }
+            }
+          }
+        },
+        '/api/bots': {
+          post: {
+            requestBody: {
+              content: {
+                'application/json': {
+                  schema: {
+                    type: 'object',
+                    properties: {
+                      name: { type: 'string' },
+                      notes: { type: 'string', description: 'Operator notes' }
+                    }
+                  }
+                }
+              }
+            },
+            responses: {
+              '200': {
+                content: {
+                  'application/json': {
+                    schema: { type: 'object', properties: { data: { type: 'object', properties: { uuid: { type: 'string' } } } } }
+                  }
+                }
+              }
+            }
+          }
+        }
+      }
+    }
+
+    // Read-only entity: no write operation at all
+    const logsSpec = {
+      openapi: '3.0.0',
+      paths: {
+        '/api/logs': {
+          get: {
+            responses: {
+              '200': {
+                content: {
+                  'application/json': {
+                    schema: {
+                      type: 'object',
+                      properties: {
+                        data: {
+                          type: 'array',
+                          items: {
+                            type: 'object',
+                            properties: {
+                              id: { type: 'string' },
+                              message: { type: 'string' }
+                            }
+                          }
+                        }
+                      }
+                    }
+                  }
+                }
+              }
+            }
+          }
+        }
+      }
+    }
+
+    describe('inferLabels', () => {
+      it('is off by default (label only from description)', () => {
+        const connector = new OpenAPIConnector()
+        const bots = connector.parse(botsSpec).find(e => e.name === 'bots')
+
+        expect(bots.fields.lastSeen.label).toBeUndefined()
+        expect(bots.fields.notes.label).toBe('Operator notes')
+      })
+
+      it('humanizes field names when enabled and description is absent', () => {
+        const connector = new OpenAPIConnector({ inferLabels: 'humanize' })
+        const bots = connector.parse(botsSpec).find(e => e.name === 'bots')
+
+        expect(bots.fields.lastSeen.label).toBe('Last Seen')
+        expect(bots.fields.uuid.label).toBe('Uuid')
+        // description still wins
+        expect(bots.fields.notes.label).toBe('Operator notes')
+      })
+    })
+
+    describe('inferReadOnly', () => {
+      it('is off by default (readOnly only from schema)', () => {
+        const connector = new OpenAPIConnector()
+        const bots = connector.parse(botsSpec).find(e => e.name === 'bots')
+
+        expect(bots.fields.lastSeen.readOnly).toBe(false)
+        expect(bots.fields.status.readOnly).toBe(true)
+      })
+
+      it('marks response-only fields readOnly when enabled', () => {
+        const connector = new OpenAPIConnector({ inferReadOnly: true })
+        const bots = connector.parse(botsSpec).find(e => e.name === 'bots')
+
+        // never in a request body → inferred readOnly
+        expect(bots.fields.uuid.readOnly).toBe(true)
+        expect(bots.fields.lastSeen.readOnly).toBe(true)
+        // present in the POST body → stays writable
+        expect(bots.fields.name.readOnly).toBe(false)
+        expect(bots.fields.notes.readOnly).toBe(false)
+        // schema-declared readOnly preserved
+        expect(bots.fields.status.readOnly).toBe(true)
+      })
+
+      it('marks every field readOnly for entities without write operations', () => {
+        const connector = new OpenAPIConnector({ inferReadOnly: true })
+        const logs = connector.parse(logsSpec).find(e => e.name === 'logs')
+
+        expect(logs.fields.id.readOnly).toBe(true)
+        expect(logs.fields.message.readOnly).toBe(true)
+      })
+    })
   })
 
   describe('extensions option', () => {

package/src/gen/connectors/OpenAPIConnector.ts

@@ -9,6 +9,7 @@
 
 import { BaseConnector, type ConnectorOptions, type ParseResult, type ParseWarning } from './BaseConnector'
 import { getDefaultType, type CustomMappings } from '../FieldMapper'
+import { humanizeFieldName } from '../../utils/humanize'
 import type { UnifiedEntitySchema, UnifiedFieldSchema, UnifiedFieldType } from '../schema'
 
 /**
@@ -48,6 +49,19 @@ export interface OpenAPIConnectorOptions extends ConnectorOptions {
   operationFilter?: OperationFilter | null
   /** Custom type mappings for FieldMapper */
   customMappings?: CustomMappings
+  /**
+   * Infer a label from the field name when the schema has no `description`
+   * (#1255): 'humanize' turns `botUuid` into "Bot Uuid". Opt-in — it changes
+   * generated output. Default: off (label only from `description`).
+   */
+  inferLabels?: 'humanize' | false
+  /**
+   * Infer `readOnly` from operation shape (#1255): a field that appears in
+   * responses but in no request-body schema is marked `readOnly: true`
+   * (an entity with no write operations gets all fields readOnly). Opt-in —
+   * it changes generated output. Schema-declared `readOnly` always wins.
+   */
+  inferReadOnly?: boolean
 }
 
 /**
@@ -64,6 +78,8 @@ interface EntityWorkingData {
   rawSchema: OpenAPISchema | null
   /** Extracted fields */
   fields: Map<string, UnifiedFieldSchema>
+  /** Field names seen in request-body schemas (for readOnly inference, #1255) */
+  requestFields: Set<string>
 }
 
 /**
@@ -173,6 +189,12 @@ export class OpenAPIConnector extends BaseConnector {
   /** Custom type mappings */
   customMappings: CustomMappings
 
+  /** Label inference mode (#1255) */
+  inferLabels: 'humanize' | false
+
+  /** Whether to infer readOnly from operation shape (#1255) */
+  inferReadOnly: boolean
+
   /**
    * Create a new OpenAPI connector
    *
@@ -185,6 +207,8 @@ export class OpenAPIConnector extends BaseConnector {
     this.dataWrapper = options.dataWrapper ?? 'data'
     this.operationFilter = options.operationFilter || null
     this.customMappings = options.customMappings || {}
+    this.inferLabels = options.inferLabels ?? false
+    this.inferReadOnly = options.inferReadOnly ?? false
   }
 
   /**
@@ -201,10 +225,11 @@ export class OpenAPIConnector extends BaseConnector {
    * })
    */
   parse(source: unknown): UnifiedEntitySchema[] {
-    const spec = source as OpenAPISpec
-    this._validateSource(spec)
-    const entities = this._extractEntities(spec)
-    return Array.from(entities.values())
+    const { schemas, warnings } = this.parseWithWarnings(source)
+    for (const warning of warnings) {
+      console.warn(`⚠ [${this.name}] ${warning.path}: ${warning.message}`)
+    }
+    return schemas
   }
 
   /**
@@ -267,6 +292,7 @@ export class OpenAPIConnector extends BaseConnector {
           idField: null,
           rawSchema: null,
           fields: new Map(),
+          requestFields: new Set(),
         })
       }
 
@@ -371,6 +397,8 @@ export class OpenAPIConnector extends BaseConnector {
         const requestSchema = this._extractRequestSchema(op, spec)
         if (requestSchema) {
           this._extractFields(requestSchema, entity.fields, spec, warnings, path)
+          // Track writable field names for readOnly inference (#1255)
+          this._collectFieldNames(requestSchema, spec, entity.requestFields)
         }
       }
     }
@@ -565,6 +593,20 @@ export class OpenAPIConnector extends BaseConnector {
         continue
       }
 
+      // Bare object schema: no contract at all. fast-json-stringify (Fastify)
+      // serializes such a field to `{}` at runtime, stripping every key (#1240).
+      if (this._isBareObjectSchema(resolvedSchema)) {
+        warnings.push({
+          path: `${sourcePath}#${fieldName}`,
+          message:
+            `object schema has no \`properties\` and \`additionalProperties\` is not set. ` +
+            `Under Fastify (fast-json-stringify) this serializes to \`{}\` at runtime ` +
+            `and the generated field type is unusable. ` +
+            `For a free-form JSON blob, declare \`additionalProperties: true\`.`,
+          code: 'EMPTY_OBJECT_SCHEMA',
+        })
+      }
+
       // Use FieldMapper for type conversion
       const type = getDefaultType(resolvedSchema, this.customMappings)
 
@@ -578,6 +620,8 @@ export class OpenAPIConnector extends BaseConnector {
       // Add optional properties
       if (resolvedSchema.description) {
         field.label = resolvedSchema.description
+      } else if (this.inferLabels === 'humanize') {
+        field.label = humanizeFieldName(fieldName)
       }
       if (resolvedSchema.format) {
         field.format = resolvedSchema.format
@@ -604,6 +648,57 @@ export class OpenAPIConnector extends BaseConnector {
     }
   }
 
+  /**
+   * Collect field names from a schema the same way _extractFields names them
+   * (top-level + one-level-nested dotted keys). Used to track which fields
+   * appear in request bodies, for readOnly inference (#1255).
+   *
+   * @private
+   * @param schema - JSON Schema object
+   * @param spec - Full spec for ref resolution
+   * @param into - Set collecting the names
+   * @param prefix - Prefix for nested field names
+   */
+  private _collectFieldNames(
+    schema: OpenAPISchema,
+    spec: OpenAPISpec,
+    into: Set<string>,
+    prefix: string = ''
+  ): void {
+    if (!schema || !schema.properties) return
+
+    for (const [name, propSchema] of Object.entries(schema.properties)) {
+      const fieldName = prefix ? `${prefix}.${name}` : name
+      into.add(fieldName)
+
+      const resolvedSchema = propSchema.$ref ? this._resolveRef(propSchema.$ref, spec) : propSchema
+      if (resolvedSchema?.type === 'object' && resolvedSchema.properties && !prefix) {
+        this._collectFieldNames(resolvedSchema, spec, into, fieldName)
+      }
+    }
+  }
+
+  /**
+   * Detect a "bare" object schema: type object with no properties, no
+   * additionalProperties contract, and no composition/reference that could
+   * supply one. Such a schema is the quasi-always-footgun case (#1240) —
+   * objects with `properties`, a sub-schema `additionalProperties`, `$ref`
+   * or oneOf/anyOf/allOf are deliberately excluded.
+   *
+   * @private
+   * @param schema - Resolved property schema
+   * @returns True if the schema is a contract-less object
+   */
+  private _isBareObjectSchema(schema: OpenAPISchema): boolean {
+    if (schema.type !== 'object') return false
+    if (schema.properties && Object.keys(schema.properties).length > 0) return false
+    const additionalProperties = schema.additionalProperties
+    if (additionalProperties === true) return false
+    if (additionalProperties && typeof additionalProperties === 'object') return false
+    if (schema.$ref || schema.oneOf || schema.anyOf || schema.allOf) return false
+    return true
+  }
+
   /**
    * Merge field info from secondary source into primary
    *
@@ -667,6 +762,17 @@ export class OpenAPIConnector extends BaseConnector {
     const schemas: Map<string, UnifiedEntitySchema> = new Map()
 
     for (const [name, data] of entityData) {
+      // readOnly inference (#1255): a field never seen in a request body is
+      // not writable through this API. Entities without write operations end
+      // up with every field readOnly. Schema-declared readOnly is preserved.
+      if (this.inferReadOnly) {
+        for (const field of data.fields.values()) {
+          if (!field.readOnly && !data.requestFields.has(field.name)) {
+            field.readOnly = true
+          }
+        }
+      }
+
       const schema: UnifiedEntitySchema = {
         name: data.name,
         endpoint: data.endpoint,

package/src/gen/generateManagers.test.js

@@ -436,6 +436,84 @@ describe('generateManagers', () => {
     })
   })
 
+  describe('baseClass option (#1253)', () => {
+    function entityConfig(extra = {}) {
+      return {
+        schema: {
+          name: 'users',
+          endpoint: '/users',
+          fields: {
+            id: { name: 'id', type: 'number' },
+            name: { name: 'name', type: 'text', required: true }
+          }
+        },
+        endpoint: '/users',
+        storageImport: '@quazardous/qdadm',
+        storageClass: 'ApiStorage',
+        ...extra
+      }
+    }
+
+    it('class mode extends the global baseClass and imports it', async () => {
+      await generateManagers({
+        output: testOutputDir,
+        classMode: true,
+        baseClass: { import: '@/managers/SkyEntityManager', name: 'SkyEntityManager' },
+        entities: { users: entityConfig() }
+      })
+
+      const content = await readFile(join(testOutputDir, 'users.ts'), 'utf-8')
+      expect(content).toContain("import { SkyEntityManager } from '@/managers/SkyEntityManager'")
+      expect(content).toContain('extends SkyEntityManager<UsersEntity>')
+      expect(content).not.toContain("import { EntityManager } from '@quazardous/qdadm'")
+      // Options/record types still come from qdadm
+      expect(content).toContain("import type { EntityRecord, EntityManagerOptions } from '@quazardous/qdadm'")
+    })
+
+    it('instance mode instantiates the baseClass', async () => {
+      await generateManagers({
+        output: testOutputDir,
+        baseClass: { import: './base', name: 'MyBase' },
+        entities: { users: entityConfig() }
+      })
+
+      const content = await readFile(join(testOutputDir, 'usersManager.ts'), 'utf-8')
+      expect(content).toContain("import { MyBase } from './base'")
+      expect(content).toContain('new MyBase<UsersEntity>(')
+      expect(content).not.toContain('new EntityManager<UsersEntity>(')
+    })
+
+    it('per-entity baseClass overrides the global one', async () => {
+      await generateManagers({
+        output: testOutputDir,
+        classMode: true,
+        baseClass: { import: './globalBase', name: 'GlobalBase' },
+        entities: {
+          users: entityConfig({
+            baseClass: { import: './localBase', name: 'LocalBase' }
+          })
+        }
+      })
+
+      const content = await readFile(join(testOutputDir, 'users.ts'), 'utf-8')
+      expect(content).toContain("import { LocalBase } from './localBase'")
+      expect(content).toContain('extends LocalBase<UsersEntity>')
+      expect(content).not.toContain('GlobalBase')
+    })
+
+    it('defaults to EntityManager when no baseClass is given', async () => {
+      await generateManagers({
+        output: testOutputDir,
+        classMode: true,
+        entities: { users: entityConfig() }
+      })
+
+      const content = await readFile(join(testOutputDir, 'users.ts'), 'utf-8')
+      expect(content).toContain("import { EntityManager } from '@quazardous/qdadm'")
+      expect(content).toContain('extends EntityManager<UsersEntity>')
+    })
+  })
+
   describe('default output directory', () => {
     it('uses default output when not specified', async () => {
       // This test would write to actual src/generated/managers/

package/src/gen/generateManagers.ts

@@ -22,6 +22,21 @@ import type { EntityDecorator } from './decorators'
  */
 const DEFAULT_OUTPUT_DIR = 'src/generated/managers/'
 
+/**
+ * Custom base class for generated managers (#1253).
+ *
+ * The class MUST extend EntityManager, stay generic over the entity type
+ * and pass constructor options through — the generated code does
+ * `class Generated<X>Manager extends <name><XEntity>` and calls
+ * `super({ ...schema options, storage, ...options })`.
+ */
+export interface GenerateManagersBaseClass {
+  /** Import specifier (e.g. '@/managers/SkyEntityManager') */
+  import: string
+  /** Exported class name (e.g. 'SkyEntityManager') */
+  name: string
+}
+
 /**
  * Entity configuration for generation
  */
@@ -40,6 +55,8 @@ export interface GenerateManagersEntityConfig {
   decorators?: EntityDecorator
   /** Generate class instead of instance (for extension) */
   classMode?: boolean
+  /** Base class for this entity's generated manager (overrides global) */
+  baseClass?: GenerateManagersBaseClass
 }
 
 /**
@@ -50,6 +67,8 @@ export interface GenerateManagersConfig {
   output?: string
   /** Generate classes instead of instances (for extension pattern) */
   classMode?: boolean
+  /** Base class for all generated managers (default: EntityManager) */
+  baseClass?: GenerateManagersBaseClass
   /** Entity configurations keyed by entity name */
   entities: Record<string, GenerateManagersEntityConfig>
 }
@@ -175,12 +194,19 @@ function serializeValue(value: unknown, indent: number = 0): string {
 function generateManagerSource(
   entityName: string,
   entityConfig: GenerateManagersEntityConfig,
-  globalOptions: { classMode?: boolean } = {}
+  globalOptions: { classMode?: boolean; baseClass?: GenerateManagersBaseClass } = {}
 ): string {
   const { schema, endpoint, storageImport, storageClass, storageOptions = {}, decorators } = entityConfig
   const classMode = entityConfig.classMode ?? globalOptions.classMode ?? false
   const className = toPascalCase(entityName)
 
+  // Custom base class (#1253): per-entity wins over global, default EntityManager.
+  const baseClass = entityConfig.baseClass ?? globalOptions.baseClass
+  const baseName = baseClass?.name ?? 'EntityManager'
+  const baseImport = baseClass
+    ? `import { ${baseClass.name} } from '${baseClass.import}'`
+    : `import { EntityManager } from '@quazardous/qdadm'`
+
   // Build storage options object
   const fullStorageOptions: Record<string, unknown> = {
     endpoint,
@@ -240,7 +266,7 @@ function generateManagerSource(
  * Endpoint: ${endpoint}
  */
 
-import { EntityManager } from '@quazardous/qdadm'
+${baseImport}
 import type { EntityRecord, EntityManagerOptions } from '@quazardous/qdadm'
 import { ${storageClass} } from '${storageImport}'
 
@@ -249,9 +275,9 @@ ${entityInterface}
 /**
  * Generated base manager for ${entityName}
  *
- * @extends EntityManager
+ * @extends ${baseName}
  */
-export class Generated${className}Manager extends EntityManager<${className}Entity> {
+export class Generated${className}Manager extends ${baseName}<${className}Entity> {
   constructor(options: Partial<EntityManagerOptions<${className}Entity>> = {}) {
     super({
       ...${serializeValue(managerOptions, 2)},
@@ -274,7 +300,7 @@ export class Generated${className}Manager extends EntityManager<${className}Enti
  * Endpoint: ${endpoint}
  */
 
-import { EntityManager } from '@quazardous/qdadm'
+${baseImport}
 import type { EntityRecord } from '@quazardous/qdadm'
 import { ${storageClass} } from '${storageImport}'
 
@@ -295,7 +321,7 @@ const storageOptions = ${serializeValue(fullStorageOptions, 0)}
  *
  * Provides CRUD operations for ${entityName} entity.
  */
-export const ${entityName}Manager = new EntityManager<${className}Entity>({
+export const ${entityName}Manager = new ${baseName}<${className}Entity>({
   ...${serializeValue(managerOptions, 0)},
   storage: new ${storageClass}<${className}Entity>(storageOptions)
 })
@@ -349,7 +375,7 @@ export async function generateManagers(config: GenerateManagersConfig): Promise<
   }
 
   const outputDir = config.output || DEFAULT_OUTPUT_DIR
-  const globalOptions = { classMode: config.classMode ?? false }
+  const globalOptions = { classMode: config.classMode ?? false, baseClass: config.baseClass }
   const generatedFiles: string[] = []
 
   // Validate each entity config

package/src/gen/index.ts

@@ -63,4 +63,5 @@ export {
   generateEntityInterface,
   type GenerateManagersConfig,
   type GenerateManagersEntityConfig,
+  type GenerateManagersBaseClass,
 } from './generateManagers'

package/src/index.ts

@@ -96,6 +96,8 @@ export {
   type SeverityMapValue,
   type SeverityMap,
   type RoutingContext,
+  type StorageResolution,
+  type ResolvedStorage,
   type PresaveContext,
   type PostsaveContext,
   type PredeleteContext,
@@ -104,6 +106,17 @@ export {
   type CacheInfo,
 } from './entity/EntityManager'
 
+// Structural manager/orchestrator views (#1253) — the implementer's minimum
+// that composables consume; import these to type manager-likes and test doubles.
+export type {
+  EntityManagerBase,
+  EntityManagerPermissions,
+  EntityManagerRead,
+  EntityManagerCrud,
+  EntityManagerLike,
+  OrchestratorLike,
+} from './entity/EntityManager.interface'
+
 // Re-export core entity types
 export type {
   EntityRecord,
@@ -150,6 +163,30 @@ export type {
 // ════════════════════════════════════════════════════════════════════════════
 export * from './orchestrator/index'
 
+/**
+ * Typed manager registry (#1253) — augment it from your app to make
+ * `getManager()` / `useEntity()` return your concrete EntityManager
+ * subclasses instead of `EntityManager<EntityRecord>`:
+ *
+ * ```ts
+ * declare module '@quazardous/qdadm' {
+ *   interface QdadmManagerRegistry {
+ *     bots: BotsManager
+ *     botPools: BotPoolsManager
+ *   }
+ * }
+ * ```
+ *
+ * Entity names not declared here keep the current fallback behavior.
+ *
+ * NOTE: deliberately declared in this file (not re-exported from a
+ * sub-module) — TypeScript module augmentation does not merge through
+ * re-export aliases, and consumers augment '@quazardous/qdadm', which
+ * resolves here.
+ */
+// eslint-disable-next-line @typescript-eslint/no-empty-object-type
+export interface QdadmManagerRegistry {}
+
 // ════════════════════════════════════════════════════════════════════════════
 // COMPOSABLES (excluding types that conflict with other modules)
 // ════════════════════════════════════════════════════════════════════════════

package/src/orchestrator/useOrchestrator.ts

@@ -16,13 +16,24 @@ import { inject } from 'vue'
 import type { Orchestrator } from './Orchestrator'
 import type { EntityManager } from '../entity/EntityManager'
 import type { EntityRecord } from '../types'
+// Type-only circular import: QdadmManagerRegistry must live in the package
+// entry (module augmentation does not merge through re-export aliases).
+import type { QdadmManagerRegistry } from '../index'
 
 /**
  * Return type for useOrchestrator
+ *
+ * `getManager` resolves through the consumer-augmentable
+ * QdadmManagerRegistry first (#1253): a declared entity name returns its
+ * concrete manager subclass; anything else falls back to the historical
+ * `EntityManager<T>` signature.
  */
 export interface UseOrchestratorReturn {
   orchestrator: Orchestrator
-  getManager: <T extends EntityRecord = EntityRecord>(name: string) => EntityManager<T>
+  getManager: {
+    <K extends keyof QdadmManagerRegistry>(name: K): QdadmManagerRegistry[K]
+    <T extends EntityRecord = EntityRecord>(name: string): EntityManager<T>
+  }
   hasManager: (name: string) => boolean
 }
 
@@ -46,8 +57,10 @@ export function useOrchestrator(): UseOrchestratorReturn {
    * Get an EntityManager by name
    * @param name - Entity name
    */
-  function getManager<T extends EntityRecord = EntityRecord>(name: string): EntityManager<T> {
-    return orchestrator.get(name) as EntityManager<T>
+  function getManager<K extends keyof QdadmManagerRegistry>(name: K): QdadmManagerRegistry[K]
+  function getManager<T extends EntityRecord = EntityRecord>(name: string): EntityManager<T>
+  function getManager(name: string): unknown {
+    return orchestrator.get(name)
   }
 
   /**
@@ -74,7 +87,9 @@ export function useOrchestrator(): UseOrchestratorReturn {
  * const { items } = await users.list()
  * ```
  */
-export function useEntity<T extends EntityRecord = EntityRecord>(name: string): EntityManager<T> {
+export function useEntity<K extends keyof QdadmManagerRegistry>(name: K): QdadmManagerRegistry[K]
+export function useEntity<T extends EntityRecord = EntityRecord>(name: string): EntityManager<T>
+export function useEntity(name: string): unknown {
   const { getManager } = useOrchestrator()
-  return getManager<T>(name)
+  return getManager(name)
 }

package/src/utils/humanize.ts

@@ -0,0 +1,26 @@
+/**
+ * Field-name humanization (#1255)
+ *
+ * Turns machine field names into presentable labels:
+ *   'botUuid'      → 'Bot Uuid'
+ *   'created_at'   → 'Created At'
+ *   'filter.botId' → 'Filter Bot Id'
+ *
+ * Shared by the list column binding helper (useListPage.column()) and the
+ * OpenAPI connector's opt-in label inference — dependency-free so the gen
+ * side (node) can import it too.
+ */
+
+/**
+ * Humanize a field name: split camelCase, snake_case, kebab-case and dotted
+ * segments into words, then capitalize each word.
+ */
+export function humanizeFieldName(field: string): string {
+  return field
+    .replace(/([a-z0-9])([A-Z])/g, '$1 $2')
+    .replace(/[_\-.]+/g, ' ')
+    .trim()
+    .split(/\s+/)
+    .map((word) => word.charAt(0).toUpperCase() + word.slice(1))
+    .join(' ')
+}

package/src/utils/index.ts

@@ -21,6 +21,9 @@ export {
 // Error formatting
 export { formatFetchError, type FetchErrorLike } from './errors'
 
+// Field-name humanization
+export { humanizeFieldName } from './humanize'
+
 // Transformers
 export {
   toKeyValueArray,