@quazardous/qdadm 2.16.0 → 2.16.1

package/dist/node/gen/schema.d.ts

@@ -0,0 +1,195 @@
+/**
+ * Unified Schema Types
+ *
+ * Core contracts that abstract differences between OpenAPI, Pydantic, and manual schema sources.
+ * These types provide a common format for entity and field definitions that can be used
+ * by connectors (schema sources) and generators (code output).
+ *
+ * @module gen/schema
+ */
+/**
+ * Field Type Enumeration
+ *
+ * Unified field types that abstract source-specific types (OpenAPI string/integer,
+ * Pydantic str/int, etc.) into a common set.
+ */
+export type UnifiedFieldType = 'text' | 'number' | 'boolean' | 'date' | 'datetime' | 'email' | 'url' | 'uuid' | 'array' | 'object';
+/**
+ * Reference Definition
+ *
+ * Describes a relation to another entity for foreign key fields.
+ */
+export interface UnifiedFieldReference {
+    /** Target entity name (e.g., 'users', 'categories') */
+    entity: string;
+    /** Field to display as label (e.g., 'name', 'title') */
+    labelField?: string;
+}
+/**
+ * Unified Field Schema
+ *
+ * Common field definition that abstracts OpenAPI property, Pydantic field, or manual definition.
+ * Connectors transform their source-specific formats into this common shape.
+ *
+ * @example
+ * // Simple text field
+ * const nameField: UnifiedFieldSchema = {
+ *   name: 'name',
+ *   type: 'text',
+ *   label: 'Full Name',
+ *   required: true
+ * }
+ *
+ * @example
+ * // Enum field with options
+ * const statusField: UnifiedFieldSchema = {
+ *   name: 'status',
+ *   type: 'text',
+ *   label: 'Status',
+ *   enum: ['draft', 'published', 'archived'],
+ *   default: 'draft'
+ * }
+ *
+ * @example
+ * // Foreign key with reference
+ * const authorField: UnifiedFieldSchema = {
+ *   name: 'author_id',
+ *   type: 'number',
+ *   label: 'Author',
+ *   reference: {
+ *     entity: 'users',
+ *     labelField: 'username'
+ *   }
+ * }
+ */
+export interface UnifiedFieldSchema {
+    /** Field name (e.g., 'email', 'created_at') */
+    name: string;
+    /** Unified field type */
+    type: UnifiedFieldType;
+    /** Human-readable label (e.g., 'Email Address') */
+    label?: string;
+    /** Whether field is required (default: false) */
+    required?: boolean;
+    /** Whether field is read-only (default: false) */
+    readOnly?: boolean;
+    /** Whether field should be hidden in UI (default: false) */
+    hidden?: boolean;
+    /** Original format hint from source (e.g., 'date-time', 'uri', 'email') */
+    format?: string;
+    /** Allowed values for enumeration fields */
+    enum?: string[];
+    /** Default value for the field */
+    default?: unknown;
+    /** Relation to another entity */
+    reference?: UnifiedFieldReference;
+    /** Project-specific extensions */
+    extensions?: Record<string, unknown>;
+    /** Field display order */
+    order?: number;
+    /** Additional properties */
+    [key: string]: unknown;
+}
+/**
+ * Unified Entity Schema
+ *
+ * Common entity definition that abstracts OpenAPI path/schema, Pydantic model, or manual definition.
+ * This is the primary contract between schema sources (connectors) and consumers (generators, runtime).
+ *
+ * @example
+ * // Complete entity schema
+ * const usersSchema: UnifiedEntitySchema = {
+ *   name: 'users',
+ *   endpoint: '/api/users',
+ *   label: 'User',
+ *   labelPlural: 'Users',
+ *   labelField: 'username',
+ *   routePrefix: 'user',
+ *   idField: 'id',
+ *   readOnly: false,
+ *   fields: {
+ *     id: { name: 'id', type: 'number', readOnly: true },
+ *     username: { name: 'username', type: 'text', required: true },
+ *     email: { name: 'email', type: 'email', required: true },
+ *     created_at: { name: 'created_at', type: 'datetime', readOnly: true }
+ *   }
+ * }
+ */
+export interface UnifiedEntitySchema {
+    /** Entity name, typically plural lowercase (e.g., 'users', 'blog_posts') */
+    name: string;
+    /** API endpoint path (e.g., '/users', '/api/v1/posts') */
+    endpoint: string;
+    /** Human-readable singular label (e.g., 'User', 'Blog Post') */
+    label?: string;
+    /** Human-readable plural label (e.g., 'Users', 'Blog Posts') */
+    labelPlural?: string;
+    /** Field used as display label (e.g., 'name', 'title') */
+    labelField?: string;
+    /** Route prefix for admin UI (e.g., 'user', 'blog-post') */
+    routePrefix?: string;
+    /** Primary key field name (default: 'id') */
+    idField?: string;
+    /** Whether entity is read-only (no create/update/delete) */
+    readOnly?: boolean;
+    /** Field definitions keyed by field name */
+    fields: Record<string, UnifiedFieldSchema>;
+    /** Project-specific extensions */
+    extensions?: Record<string, unknown>;
+}
+/**
+ * Valid field types for UnifiedFieldSchema
+ *
+ * Used for validation and documentation. Maps to common UI input types:
+ * - text: Single-line text input
+ * - number: Numeric input
+ * - boolean: Checkbox/toggle
+ * - date: Date picker (date only)
+ * - datetime: Date-time picker
+ * - email: Email input with validation
+ * - url: URL input with validation
+ * - uuid: UUID text input
+ * - array: Multi-value field (tags, list)
+ * - object: Nested object (JSON editor or subform)
+ */
+export declare const UNIFIED_FIELD_TYPES: readonly ["text", "number", "boolean", "date", "datetime", "email", "url", "uuid", "array", "object"];
+/**
+ * Check if a type is a valid UnifiedFieldType
+ *
+ * @param type - Type to validate
+ * @returns True if valid
+ *
+ * @example
+ * isValidFieldType('text')     // true
+ * isValidFieldType('string')   // false (OpenAPI type, not unified)
+ */
+export declare function isValidFieldType(type: string): type is UnifiedFieldType;
+/**
+ * Create a minimal field schema with defaults
+ *
+ * @param name - Field name
+ * @param type - Field type
+ * @param overrides - Additional field properties
+ * @returns Complete field schema
+ *
+ * @example
+ * const field = createFieldSchema('email', 'email', { required: true })
+ * // { name: 'email', type: 'email', required: true }
+ */
+export declare function createFieldSchema(name: string, type: UnifiedFieldType, overrides?: Partial<UnifiedFieldSchema>): UnifiedFieldSchema;
+/**
+ * Create a minimal entity schema with defaults
+ *
+ * @param name - Entity name
+ * @param endpoint - API endpoint
+ * @param fields - Field definitions
+ * @param overrides - Additional entity properties
+ * @returns Complete entity schema
+ *
+ * @example
+ * const schema = createEntitySchema('users', '/api/users', {
+ *   id: createFieldSchema('id', 'number', { readOnly: true }),
+ *   name: createFieldSchema('name', 'text', { required: true })
+ * })
+ */
+export declare function createEntitySchema(name: string, endpoint: string, fields: Record<string, UnifiedFieldSchema>, overrides?: Partial<UnifiedEntitySchema>): UnifiedEntitySchema;

package/dist/node/gen/schema.js

@@ -0,0 +1,91 @@
+/**
+ * Unified Schema Types
+ *
+ * Core contracts that abstract differences between OpenAPI, Pydantic, and manual schema sources.
+ * These types provide a common format for entity and field definitions that can be used
+ * by connectors (schema sources) and generators (code output).
+ *
+ * @module gen/schema
+ */
+/**
+ * Valid field types for UnifiedFieldSchema
+ *
+ * Used for validation and documentation. Maps to common UI input types:
+ * - text: Single-line text input
+ * - number: Numeric input
+ * - boolean: Checkbox/toggle
+ * - date: Date picker (date only)
+ * - datetime: Date-time picker
+ * - email: Email input with validation
+ * - url: URL input with validation
+ * - uuid: UUID text input
+ * - array: Multi-value field (tags, list)
+ * - object: Nested object (JSON editor or subform)
+ */
+export const UNIFIED_FIELD_TYPES = [
+    'text',
+    'number',
+    'boolean',
+    'date',
+    'datetime',
+    'email',
+    'url',
+    'uuid',
+    'array',
+    'object',
+];
+/**
+ * Check if a type is a valid UnifiedFieldType
+ *
+ * @param type - Type to validate
+ * @returns True if valid
+ *
+ * @example
+ * isValidFieldType('text')     // true
+ * isValidFieldType('string')   // false (OpenAPI type, not unified)
+ */
+export function isValidFieldType(type) {
+    return UNIFIED_FIELD_TYPES.includes(type);
+}
+/**
+ * Create a minimal field schema with defaults
+ *
+ * @param name - Field name
+ * @param type - Field type
+ * @param overrides - Additional field properties
+ * @returns Complete field schema
+ *
+ * @example
+ * const field = createFieldSchema('email', 'email', { required: true })
+ * // { name: 'email', type: 'email', required: true }
+ */
+export function createFieldSchema(name, type, overrides = {}) {
+    return {
+        name,
+        type,
+        ...overrides,
+    };
+}
+/**
+ * Create a minimal entity schema with defaults
+ *
+ * @param name - Entity name
+ * @param endpoint - API endpoint
+ * @param fields - Field definitions
+ * @param overrides - Additional entity properties
+ * @returns Complete entity schema
+ *
+ * @example
+ * const schema = createEntitySchema('users', '/api/users', {
+ *   id: createFieldSchema('id', 'number', { readOnly: true }),
+ *   name: createFieldSchema('name', 'text', { required: true })
+ * })
+ */
+export function createEntitySchema(name, endpoint, fields, overrides = {}) {
+    return {
+        name,
+        endpoint,
+        fields,
+        ...overrides,
+    };
+}

package/dist/node/gen/vite-plugin.d.ts

@@ -0,0 +1,64 @@
+/**
+ * Vite Plugin for qdadm EntityManager Generation
+ *
+ * Integrates generateManagers with Vite's build pipeline, triggering
+ * entity manager file generation during the buildStart hook.
+ *
+ * @experimental Undocumented build-time entry. Prefer the programmatic
+ * `generateManagers` entry (`@quazardous/qdadm/gen`), which is stable — see
+ * docs/API_STABILITY.md.
+ *
+ * @module gen/vite-plugin
+ */
+import type { Plugin } from 'vite';
+/**
+ * Plugin options for qdadmGen
+ */
+export interface QdadmGenOptions {
+    /** Path to qdadm config file (default: 'qdadm.config.js') */
+    config?: string;
+    /** Override output directory for generated files */
+    output?: string;
+}
+/**
+ * Vite plugin for generating EntityManager files at build time
+ *
+ * Loads the qdadm configuration file and calls generateManagers during
+ * Vite's buildStart hook. Supports both ESM and CommonJS config files.
+ *
+ * @param options - Plugin options
+ * @returns Vite plugin object
+ *
+ * @example
+ * ```ts
+ * // vite.config.js
+ * import { defineConfig } from 'vite'
+ * import { qdadmGen } from '@quazardous/qdadm/gen/vite-plugin'
+ *
+ * export default defineConfig({
+ *   plugins: [
+ *     qdadmGen({
+ *       config: './qdadm.config.js',
+ *       output: 'src/generated/managers/'
+ *     })
+ *   ]
+ * })
+ * ```
+ *
+ * @example
+ * ```ts
+ * // qdadm.config.js
+ * export default {
+ *   output: 'src/generated/managers/',
+ *   entities: {
+ *     users: {
+ *       schema: { name: 'users', fields: { id: { type: 'integer' } } },
+ *       endpoint: '/api/users',
+ *       storageImport: '@quazardous/qdadm',
+ *       storageClass: 'ApiStorage'
+ *     }
+ *   }
+ * }
+ * ```
+ */
+export declare function qdadmGen(options?: QdadmGenOptions): Plugin;

package/dist/node/gen/vite-plugin.js

@@ -0,0 +1,99 @@
+/**
+ * Vite Plugin for qdadm EntityManager Generation
+ *
+ * Integrates generateManagers with Vite's build pipeline, triggering
+ * entity manager file generation during the buildStart hook.
+ *
+ * @experimental Undocumented build-time entry. Prefer the programmatic
+ * `generateManagers` entry (`@quazardous/qdadm/gen`), which is stable — see
+ * docs/API_STABILITY.md.
+ *
+ * @module gen/vite-plugin
+ */
+// Explicit .js extension: this module is compiled for Node (#1895), and Node
+// ESM will not resolve an extensionless relative import. TypeScript maps the
+// .js specifier back to the .ts source, so the bundler path is unaffected.
+import { generateManagers } from './generateManagers.js';
+import { pathToFileURL } from 'node:url';
+import { resolve } from 'node:path';
+/**
+ * Vite plugin for generating EntityManager files at build time
+ *
+ * Loads the qdadm configuration file and calls generateManagers during
+ * Vite's buildStart hook. Supports both ESM and CommonJS config files.
+ *
+ * @param options - Plugin options
+ * @returns Vite plugin object
+ *
+ * @example
+ * ```ts
+ * // vite.config.js
+ * import { defineConfig } from 'vite'
+ * import { qdadmGen } from '@quazardous/qdadm/gen/vite-plugin'
+ *
+ * export default defineConfig({
+ *   plugins: [
+ *     qdadmGen({
+ *       config: './qdadm.config.js',
+ *       output: 'src/generated/managers/'
+ *     })
+ *   ]
+ * })
+ * ```
+ *
+ * @example
+ * ```ts
+ * // qdadm.config.js
+ * export default {
+ *   output: 'src/generated/managers/',
+ *   entities: {
+ *     users: {
+ *       schema: { name: 'users', fields: { id: { type: 'integer' } } },
+ *       endpoint: '/api/users',
+ *       storageImport: '@quazardous/qdadm',
+ *       storageClass: 'ApiStorage'
+ *     }
+ *   }
+ * }
+ * ```
+ */
+export function qdadmGen(options = {}) {
+    const configPath = options.config || 'qdadm.config.js';
+    return {
+        name: 'qdadm-gen',
+        async buildStart() {
+            try {
+                // Resolve config path relative to cwd
+                const resolvedConfigPath = resolve(process.cwd(), configPath);
+                // Load config file dynamically
+                const configUrl = pathToFileURL(resolvedConfigPath).href;
+                const configModule = (await import(configUrl));
+                const loadedConfig = configModule.default || configModule;
+                // Validate loaded config
+                if (!loadedConfig || typeof loadedConfig !== 'object') {
+                    throw new Error(`Invalid qdadm config at '${configPath}': must export an object`);
+                }
+                if (!loadedConfig.entities) {
+                    throw new Error(`Invalid qdadm config at '${configPath}': missing 'entities' property`);
+                }
+                // Merge plugin options with config (plugin options take precedence)
+                const mergedConfig = {
+                    ...loadedConfig,
+                    ...(options.output && { output: options.output }),
+                };
+                // Generate managers
+                const generatedFiles = await generateManagers(mergedConfig);
+                // Log results
+                console.log(`[qdadm-gen] Generated ${generatedFiles.length} manager file(s)`);
+                for (const file of generatedFiles) {
+                    console.log(`  - ${file}`);
+                }
+            }
+            catch (error) {
+                // Wrap error with plugin context for clearer messages
+                const message = error instanceof Error ? error.message : String(error);
+                throw new Error(`[qdadm-gen] Failed to generate managers: ${message}`);
+            }
+        },
+    };
+}

package/dist/node/vite/qdadmDebugPlugin.d.ts

@@ -0,0 +1,60 @@
+/**
+ * qdadm Vite dev plugin — exposes the running app's DebugBridge over HTTP.
+ *
+ * Endpoints (default prefix `/__qdadm`):
+ *   GET  /__qdadm/                    — index of endpoints + cache stats
+ *   GET  /__qdadm/sessions            — list of connected client sessions
+ *   GET  /__qdadm/describe.json       — bridge.describe() (manifests)
+ *   GET  /__qdadm/snapshot.json       — bridge.dump() (live state)
+ *   POST /__qdadm/call                — body {collector, action, args?}
+ *
+ * Session selection: every browser tab that loads the app gets a fresh
+ * session id (uuid in the injected client). All endpoints accept a
+ * `?session=<id|latest>` query param. Default is `latest` (the most recently
+ * active session).
+ *
+ * Wire-up: the plugin injects a small ESM script via `transformIndexHtml`.
+ * That inline script lives in Vite's HMR pipeline (so `import.meta.hot`
+ * works), polls for `window.__qdadm.debug.bridge`, then pushes describe +
+ * snapshot on every reactive tick. The plugin caches per-session payloads
+ * in memory; GETs are served from cache (no round-trip needed).
+ *
+ * `call` is always request-response — it mutates state in the live page.
+ *
+ * Cache responses include `X-Qdadm-Stale-Ms`, `X-Qdadm-Source: cache|live`,
+ * and `X-Qdadm-Session: <id>` headers.
+ */
+import type { Plugin } from 'vite';
+/** Typed page-side queries (#1398) — served by the injected client. */
+export type DebugQueryType = 'describe' | 'dump' | 'call' | 'sessionInfo' | 'routes' | 'entityState' | 'entityCall' | 'storageDump' | 'bootlog' | 'recentSignals';
+/** Broker surface exposed to sibling plugins via `plugin.api` (#1398). */
+export interface QdadmDebugPluginApi {
+    /** Send a typed query to the page and await its reply. */
+    ask: (type: DebugQueryType, payload?: unknown, sessionId?: string) => Promise<unknown>;
+    /** Resolve a session param ('latest' or id) to a live session, if any. */
+    pickSession: (sessionParam: string | null) => {
+        id: string;
+        lastSeenAt: number;
+        meta: Record<string, unknown>;
+    } | null;
+    listSessions: () => Array<{
+        id: string;
+        firstSeenAt: number;
+        lastSeenAt: number;
+        ageMs: number;
+        hasDescribe: boolean;
+        hasSnapshot: boolean;
+        meta: Record<string, unknown>;
+    }>;
+    prefix: string;
+}
+export interface QdadmDebugPluginOptions {
+    /** URL prefix (default '/__qdadm') */
+    prefix?: string;
+    /** Request timeout ms for live fallback (default 3000) */
+    timeoutMs?: number;
+    /** Drop sessions inactive for this many ms (default 10 min) */
+    sessionTtlMs?: number;
+}
+export declare function qdadmDebugPlugin(options?: QdadmDebugPluginOptions): Plugin;
+export default qdadmDebugPlugin;