@memberjunction/database-designer-actions 0.0.1 → 5.32.0

package/src/__tests__/validate-entity-schema.action.test.ts

@@ -0,0 +1,243 @@
+import { describe, it, expect, beforeEach, vi } from 'vitest';
+import type { RunActionParams } from '@memberjunction/actions-base';
+
+// ─── Hoisted mock state ──────────────────────────────────────────────────────
+
+const mockState = vi.hoisted(() => ({
+    authorizations: [] as { Name: string; UserCanExecute: () => boolean }[],
+    validationResult: {
+        Valid: true,
+        Errors: [] as string[],
+        Warnings: [] as string[],
+    },
+}));
+
+// ─── Mock all external dependencies ─────────────────────────────────────────
+
+vi.mock('@memberjunction/core', () => ({
+    Metadata: vi.fn().mockImplementation(function(this: unknown) {
+        return { Authorizations: mockState.authorizations };
+    }),
+    AuthorizationEvaluator: vi.fn().mockImplementation(function(this: unknown) {
+        return {
+            UserCanExecuteWithAncestors: vi.fn().mockImplementation(
+                (auth: { UserCanExecute?: () => boolean }) => auth?.UserCanExecute?.() ?? false
+            ),
+        };
+    }),
+    LogError: vi.fn(),
+    UserInfo: vi.fn(),
+}));
+
+vi.mock('@memberjunction/database-designer-core', () => ({
+    DatabaseSchemaValidationService: vi.fn().mockImplementation(function(this: unknown) {
+        return {
+            validate: vi.fn().mockImplementation(async () => mockState.validationResult),
+        };
+    }),
+    AUTHORIZATIONS: {
+        CREATE_IN_UDT_SCHEMA: 'Create in UDT Schema',
+        CREATE_IN_CUSTOM_SCHEMA: 'Create in Custom Schema',
+        MODIFY_OWN_ENTITIES: 'Modify Own Entities',
+        MODIFY_ANY_UDT_ENTITIES: 'Modify Any UDT Entities',
+    },
+    UDT_SCHEMA_NAME: '__mj_UDT',
+    DatabaseDesignerPipelineExecutor: {},
+}));
+
+vi.mock('@memberjunction/global', () => ({
+    RegisterClass: () => (_target: unknown) => _target,
+    LogError: vi.fn(),
+}));
+
+vi.mock('@memberjunction/actions', () => ({
+    BaseAction: class BaseAction {},
+}));
+
+vi.mock('@memberjunction/schema-engine', () => ({}));
+
+// ─── Import after mocks ──────────────────────────────────────────────────────
+
+import { ValidateEntitySchemaAction } from '../actions/validate-entity-schema.action.js';
+import { AUTHORIZATIONS } from '@memberjunction/database-designer-core';
+
+// ─── Test helpers ─────────────────────────────────────────────────────────────
+
+const CONTEXT_USER = { ID: 'user-1', Email: 'test@example.com' } as ReturnType<typeof vi.fn>;
+
+const VALID_TABLE_DEFINITION = {
+    SchemaName: '__mj_UDT',
+    TableName: 'ProjectMilestones',
+    EntityName: 'Project Milestones',
+    Description: 'Milestones for projects',
+    Columns: [{ Name: 'Title', Type: 'string', IsNullable: false }],
+};
+
+function makeParams(overrides: {
+    tableDefinition?: unknown;
+    modificationType?: string;
+    contextUser?: unknown;
+} = {}): RunActionParams {
+    const params: { Name: string; Type: string; Value: unknown }[] = [];
+
+    const td = overrides.tableDefinition !== undefined
+        ? overrides.tableDefinition
+        : VALID_TABLE_DEFINITION;
+    if (td !== null) {
+        params.push({ Name: 'TableDefinition', Type: 'Input', Value: td });
+    }
+
+    if (overrides.modificationType) {
+        params.push({ Name: 'ModificationType', Type: 'Input', Value: overrides.modificationType });
+    }
+
+    return {
+        Params: params,
+        ContextUser: (overrides.contextUser ?? CONTEXT_USER) as ReturnType<typeof vi.fn>,
+    } as unknown as RunActionParams;
+}
+
+// Access protected InternalRunAction for testing (standard MJ action test pattern)
+type TestableAction = {
+    InternalRunAction(params: RunActionParams): Promise<import('@memberjunction/actions-base').ActionResultSimple>;
+};
+
+function makeAction(): TestableAction {
+    return new ValidateEntitySchemaAction() as unknown as TestableAction;
+}
+
+const AUTH_CREATE_UDT = { Name: AUTHORIZATIONS.CREATE_IN_UDT_SCHEMA, UserCanExecute: () => true };
+
+// ─── Tests ───────────────────────────────────────────────────────────────────
+
+describe('ValidateEntitySchemaAction', () => {
+    beforeEach(() => {
+        mockState.authorizations = [];
+        mockState.validationResult = { Valid: true, Errors: [], Warnings: [] };
+    });
+
+    describe('parameter validation', () => {
+        it('returns MISSING_PARAMETER when TableDefinition is absent', async () => {
+            const action = makeAction();
+            const result = await action.InternalRunAction(makeParams({ tableDefinition: null }));
+
+            expect(result.Success).toBe(false);
+            expect(result.ResultCode).toBe('MISSING_PARAMETER');
+        });
+
+        it('returns INVALID_TABLE_DEFINITION when TableDefinition is not a valid object', async () => {
+            const action = makeAction();
+            const result = await action.InternalRunAction(makeParams({ tableDefinition: '{bad json}' }));
+
+            expect(result.Success).toBe(false);
+            expect(result.ResultCode).toBe('INVALID_TABLE_DEFINITION');
+        });
+    });
+
+    describe('authorization', () => {
+        it('returns UNAUTHORIZED when contextUser lacks the required auth', async () => {
+            // authorizations stays [] — no auth configured → access denied
+            const action = makeAction();
+            const result = await action.InternalRunAction(makeParams());
+
+            expect(result.Success).toBe(false);
+            expect(result.ResultCode).toBe('UNAUTHORIZED');
+        });
+
+        it('proceeds to validation when user holds the required authorization', async () => {
+            mockState.authorizations = [AUTH_CREATE_UDT];
+            const action = makeAction();
+            const result = await action.InternalRunAction(makeParams());
+
+            // Auth passed — result code is from validation, not auth
+            expect(result.ResultCode).not.toBe('UNAUTHORIZED');
+        });
+    });
+
+    describe('validation outcomes', () => {
+        it('returns VALIDATION_PASSED (Success=true) when the definition is valid', async () => {
+            mockState.authorizations = [AUTH_CREATE_UDT];
+            mockState.validationResult = { Valid: true, Errors: [], Warnings: [] };
+
+            const action = makeAction();
+            const result = await action.InternalRunAction(makeParams());
+
+            expect(result.Success).toBe(true);
+            expect(result.ResultCode).toBe('VALIDATION_PASSED');
+        });
+
+        it('returns VALIDATION_FAILED (Success=true) when the definition has errors', async () => {
+            mockState.authorizations = [AUTH_CREATE_UDT];
+            mockState.validationResult = {
+                Valid: false,
+                Errors: ['Schema dbo is protected'],
+                Warnings: [],
+            };
+
+            const action = makeAction();
+            const result = await action.InternalRunAction(makeParams());
+
+            // Success=true because the action itself succeeded (validation is the output)
+            expect(result.Success).toBe(true);
+            expect(result.ResultCode).toBe('VALIDATION_FAILED');
+            expect(result.Message).toContain('Schema dbo is protected');
+        });
+
+        it('writes ValidationResult as an output param', async () => {
+            mockState.authorizations = [AUTH_CREATE_UDT];
+            mockState.validationResult = { Valid: true, Errors: [], Warnings: ['Minor advisory'] };
+
+            const params = makeParams();
+            const action = makeAction();
+            await action.InternalRunAction(params);
+
+            const outputParam = params.Params.find(p => p.Name === 'ValidationResult');
+            expect(outputParam).toBeDefined();
+            expect(outputParam?.Value).toMatchObject({
+                Valid: true,
+                Warnings: ['Minor advisory'],
+            });
+        });
+
+        it('writes ValidationResult output even when validation fails', async () => {
+            mockState.authorizations = [AUTH_CREATE_UDT];
+            mockState.validationResult = {
+                Valid: false,
+                Errors: ['Reserved column ID'],
+                Warnings: [],
+            };
+
+            const params = makeParams();
+            const action = makeAction();
+            await action.InternalRunAction(params);
+
+            const outputParam = params.Params.find(p => p.Name === 'ValidationResult');
+            expect(outputParam?.Value).toMatchObject({
+                Valid: false,
+                Errors: ['Reserved column ID'],
+            });
+        });
+    });
+
+    describe('ModificationType routing', () => {
+        it('defaults to create modification type when ModificationType is absent', async () => {
+            // __mj_UDT schema → CREATE_IN_UDT_SCHEMA auth required
+            mockState.authorizations = [AUTH_CREATE_UDT];
+            const action = makeAction();
+            const result = await action.InternalRunAction(makeParams());
+
+            expect(result.ResultCode).toBe('VALIDATION_PASSED');
+        });
+
+        it('uses MODIFY_OWN_ENTITIES auth when ModificationType is alter', async () => {
+            mockState.authorizations = [{
+                Name: AUTHORIZATIONS.MODIFY_OWN_ENTITIES,
+                UserCanExecute: () => true,
+            }];
+            const action = makeAction();
+            const result = await action.InternalRunAction(makeParams({ modificationType: 'alter' }));
+
+            expect(result.ResultCode).not.toBe('UNAUTHORIZED');
+        });
+    });
+});

package/src/actions/base-database-designer.action.ts

@@ -0,0 +1,210 @@
+/**
+ * @module base-database-designer.action
+ * @description Abstract base for all Database Designer actions.
+ *
+ * Provides common parameter extraction, authorization checking, and result
+ * building so that each concrete action stays thin and focused.  All the
+ * shared logic lives here; concrete actions only implement `InternalRunAction`.
+ */
+
+import { BaseAction } from '@memberjunction/actions';
+import type { ActionResultSimple, RunActionParams } from '@memberjunction/actions-base';
+import { AuthorizationEvaluator, Metadata, UserInfo, LogError } from '@memberjunction/core';
+import type { TableDefinition } from '@memberjunction/schema-engine';
+
+import {
+    DatabaseDesignerPipelineExecutor,
+    type PipelineExecutionOptions,
+    AUTHORIZATIONS,
+    UDT_SCHEMA_NAME,
+    type PipelineExecutionResult,
+} from '@memberjunction/database-designer-core';
+
+// ─── Public API ───────────────────────────────────────────────────────────────
+
+export abstract class BaseDatabaseDesignerAction extends BaseAction {
+
+    // ─── Param extraction ────────────────────────────────────────────────
+
+    /**
+     * Extract and parse the `TableDefinition` param (JSON object or string).
+     * Returns `{ error }` on missing/malformed input, `{ td }` on success.
+     */
+    protected getTableDefinitionParam(
+        params: RunActionParams
+    ): { td?: TableDefinition; error?: ActionResultSimple } {
+        const param = this.findParam(params, 'TableDefinition');
+        if (!param?.Value) {
+            return {
+                error: this.missing('TableDefinition', 'A complete TableDefinition object is required.'),
+            };
+        }
+
+        const raw = param.Value;
+        const td = typeof raw === 'string' ? this.tryParse(raw) : raw as TableDefinition;
+        if (!td || typeof td !== 'object') {
+            return {
+                error: {
+                    Success: false,
+                    ResultCode: 'INVALID_TABLE_DEFINITION',
+                    Message: 'TableDefinition must be a valid JSON object.',
+                },
+            };
+        }
+
+        return { td: td as TableDefinition };
+    }
+
+    /** Extract the `ModificationType` param ('create' | 'alter'). Defaults to 'create'. */
+    protected getModificationTypeParam(params: RunActionParams): 'create' | 'alter' {
+        const v = this.findParam(params, 'ModificationType')?.Value;
+        return v === 'alter' ? 'alter' : 'create';
+    }
+
+    /** Extract a boolean param by name with a fallback default. */
+    protected getBoolParam(params: RunActionParams, name: string, defaultValue: boolean): boolean {
+        const v = this.findParam(params, name)?.Value;
+        if (v === undefined || v === null) return defaultValue;
+        const s = String(v).trim().toLowerCase();
+        if (s === 'true' || s === '1' || s === 'yes') return true;
+        if (s === 'false' || s === '0' || s === 'no') return false;
+        return defaultValue;
+    }
+
+    /** Extract a string param by name, returning undefined when absent. */
+    protected getStringParam(params: RunActionParams, name: string): string | undefined {
+        const v = this.findParam(params, name)?.Value;
+        if (v === undefined || v === null) return undefined;
+        const s = String(v).trim();
+        return s.length > 0 ? s : undefined;
+    }
+
+    /** Append an output param to the params array so callers can read results. */
+    protected addOutputParam(params: RunActionParams, name: string, value: unknown): void {
+        params.Params.push({ Name: name, Type: 'Output', Value: value });
+    }
+
+    // ─── Authorization ────────────────────────────────────────────────────
+
+    /**
+     * Check that the contextUser holds the authorization required for the
+     * requested operation type.  Returns an error string on failure, null on success.
+     */
+    protected async checkAuthorization(
+        tableDefinition: TableDefinition,
+        modificationType: 'create' | 'alter',
+        contextUser: UserInfo
+    ): Promise<string | null> {
+        const authName = this.resolveAuthorizationName(tableDefinition, modificationType);
+        const md = new Metadata(); // global-provider-ok: MJAPI server-side, single-provider deployment
+        const auth = md.Authorizations.find(a => a.Name === authName);
+
+        if (!auth) {
+            return `Authorization '${authName}' is not configured in this system.`;
+        }
+
+        const evaluator = new AuthorizationEvaluator();
+        if (!evaluator.UserCanExecuteWithAncestors(auth, contextUser, md.Authorizations)) {
+            return `User does not have the '${authName}' authorization required for this operation.`;
+        }
+
+        return null;
+    }
+
+    /** Map operation to its minimum required authorization name. */
+    private resolveAuthorizationName(
+        tableDefinition: TableDefinition,
+        modificationType: 'create' | 'alter'
+    ): string {
+        if (modificationType === 'alter') {
+            return AUTHORIZATIONS.MODIFY_OWN_ENTITIES;
+        }
+        return tableDefinition.SchemaName.toLowerCase() === UDT_SCHEMA_NAME.toLowerCase()
+            ? AUTHORIZATIONS.CREATE_IN_UDT_SCHEMA
+            : AUTHORIZATIONS.CREATE_IN_CUSTOM_SCHEMA;
+    }
+
+    // ─── Pipeline options ─────────────────────────────────────────────────
+
+    /** Build PipelineExecutionOptions from action params. */
+    protected buildPipelineOptions(
+        params: RunActionParams,
+        source: string
+    ): PipelineExecutionOptions {
+        return {
+            SkipGitCommit: this.getBoolParam(params, 'SkipGitCommit', false),
+            SkipRestart: this.getBoolParam(params, 'SkipRestart', false),
+            Source: source,
+        };
+    }
+
+    // ─── Result building ─────────────────────────────────────────────────
+
+    /**
+     * Map a PipelineExecutionResult to ActionResultSimple and populate output
+     * params so workflow engines can read EntityID, EntityName, etc.
+     */
+    protected buildPipelineResult(
+        execResult: PipelineExecutionResult,
+        params: RunActionParams
+    ): ActionResultSimple {
+        if (execResult.Success) {
+            this.addOutputParam(params, 'EntityID', execResult.EntityID ?? null);
+            this.addOutputParam(params, 'EntityName', execResult.EntityName ?? null);
+            this.addOutputParam(params, 'SchemaName', execResult.SchemaName ?? null);
+            this.addOutputParam(params, 'TableName', execResult.TableName ?? null);
+            this.addOutputParam(params, 'PipelineSteps', execResult.PipelineSteps ?? []);
+            return {
+                Success: true,
+                ResultCode: 'SUCCESS',
+                Message: `Entity '${execResult.EntityName ?? execResult.TableName}' created/modified successfully.`,
+            };
+        }
+
+        this.addOutputParam(params, 'PipelineSteps', execResult.PipelineSteps ?? []);
+        return {
+            Success: false,
+            ResultCode: 'PIPELINE_FAILED',
+            Message: execResult.ErrorMessage ?? 'Pipeline execution failed without an error message.',
+        };
+    }
+
+    /** Common error handler for unexpected exceptions. */
+    protected handleUnexpected(error: unknown, operation: string): ActionResultSimple {
+        const msg = error instanceof Error ? error.message : String(error);
+        LogError(`DatabaseDesigner action '${operation}' threw: ${msg}`);
+        return {
+            Success: false,
+            ResultCode: 'UNEXPECTED_ERROR',
+            Message: `Unexpected error during ${operation}: ${msg}`,
+        };
+    }
+
+    // ─── Private helpers ──────────────────────────────────────────────────
+
+    private findParam(params: RunActionParams, name: string) {
+        return params.Params.find(
+            p => p.Name.trim().toLowerCase() === name.toLowerCase()
+        );
+    }
+
+    private tryParse(raw: string): unknown | null {
+        try {
+            return JSON.parse(raw);
+        } catch {
+            return null;
+        }
+    }
+
+    private missing(paramName: string, hint: string): ActionResultSimple {
+        return {
+            Success: false,
+            ResultCode: 'MISSING_PARAMETER',
+            Message: `Parameter '${paramName}' is required. ${hint}`,
+        };
+    }
+}
+
+// Re-export the shared executor so callers that import from this module can
+// access it without an extra import — actions are the primary consumers.
+export { DatabaseDesignerPipelineExecutor };

package/src/actions/create-entity.action.ts

@@ -0,0 +1,66 @@
+/**
+ * @module create-entity.action
+ * @description Action that creates a new MemberJunction entity from a
+ * TableDefinition.  Validates authorization then delegates to the shared RSU
+ * pipeline executor.
+ *
+ * Intended callers:
+ *  - Agent Manager's Planning Designer sub-agent
+ *  - Any agent with the 'Create in UDT Schema' or 'Create in Custom Schema' auth
+ *  - Workflow engines / low-code builders
+ *
+ * This action does NOT run the full conversational Database Designer flow.
+ * Callers must supply a pre-formed TableDefinition.
+ */
+
+import { RegisterClass } from '@memberjunction/global';
+import { BaseAction } from '@memberjunction/actions';
+import type { ActionResultSimple, RunActionParams } from '@memberjunction/actions-base';
+
+import { DatabaseDesignerPipelineExecutor, UDT_SETTINGS } from '@memberjunction/database-designer-core';
+
+import { BaseDatabaseDesignerAction } from './base-database-designer.action.js';
+
+// ─── Registration ─────────────────────────────────────────────────────────────
+
+/**
+ * Creates a new MemberJunction entity from a fully-formed `TableDefinition`.
+ *
+ * Input params:
+ *  - `TableDefinition` (required) — JSON object conforming to the schema-engine
+ *    `TableDefinition` interface.
+ *  - `SkipGitCommit` (optional, default false) — skip creating a migration git commit.
+ *  - `SkipRestart` (optional, default false) — skip restarting MJAPI after the pipeline.
+ *
+ * Output params written on success:
+ *  - `EntityID`       — MJ entity UUID.
+ *  - `EntityName`     — Human-readable entity name.
+ *  - `SchemaName`     — Database schema.
+ *  - `TableName`      — Physical table name.
+ *  - `PipelineSteps`  — Array of step summaries from RuntimeSchemaManager.
+ */
+@RegisterClass(BaseAction, 'Create Entity')
+export class CreateEntityAction extends BaseDatabaseDesignerAction {
+    protected async InternalRunAction(params: RunActionParams): Promise<ActionResultSimple> {
+        try {
+            const { td, error: tdError } = this.getTableDefinitionParam(params);
+            if (tdError) return tdError;
+
+            const authError = await this.checkAuthorization(td!, 'create', params.ContextUser);
+            if (authError) {
+                return { Success: false, ResultCode: 'UNAUTHORIZED', Message: authError };
+            }
+
+            const options = this.buildPipelineOptions(params, UDT_SETTINGS.SOURCE_DATABASE_DESIGNER);
+            const execResult = await DatabaseDesignerPipelineExecutor.CreateEntity(
+                td!,
+                params.ContextUser,
+                options
+            );
+
+            return this.buildPipelineResult(execResult, params);
+        } catch (err) {
+            return this.handleUnexpected(err, 'Create Entity');
+        }
+    }
+}

package/src/actions/describe-entity.action.ts

@@ -0,0 +1,160 @@
+/**
+ * @module describe-entity.action
+ * @description Returns detailed column-level metadata for a given entity.
+ *
+ * Useful for agents that need to inspect an existing entity before deciding
+ * whether to modify it, or for display in the Database Designer UI.
+ */
+
+import { RegisterClass, UUIDsEqual } from '@memberjunction/global';
+import { BaseAction } from '@memberjunction/actions';
+import type { ActionResultSimple, RunActionParams } from '@memberjunction/actions-base';
+import { RunView, Metadata } from '@memberjunction/core';
+
+import { escapeSqlLiteral } from '@memberjunction/database-designer-core';
+
+import { BaseDatabaseDesignerAction } from './base-database-designer.action.js';
+
+// ─── Types ────────────────────────────────────────────────────────────────────
+
+interface ColumnInfo {
+    Name: string;
+    Type: string;
+    IsNullable: boolean;
+    MaxLength: number | null;
+    Description: string | null;
+    IsRequired: boolean;
+}
+
+interface EntityInfo {
+    EntityID: string;
+    EntityName: string;
+    SchemaName: string;
+    TableName: string;
+    Description: string | null;
+    Columns: ColumnInfo[];
+}
+
+// ─── Registration ─────────────────────────────────────────────────────────────
+
+/**
+ * Describes a MemberJunction entity including all its columns.
+ *
+ * Input params — supply exactly one identifier:
+ *  - `EntityID`   — The entity UUID.
+ *  - `EntityName` — The human-readable entity name (e.g. "Project Milestones").
+ *  - `TableName`  — The physical table name.  Optionally combine with
+ *                   `SchemaName` to narrow by schema.
+ *
+ * Output params:
+ *  - `EntityInfo` — Full EntityInfo object (see above) or null if not found.
+ */
+@RegisterClass(BaseAction, 'Describe Entity')
+export class DescribeEntityAction extends BaseDatabaseDesignerAction {
+    protected async InternalRunAction(params: RunActionParams): Promise<ActionResultSimple> {
+        try {
+            const entityID = this.getStringParam(params, 'EntityID');
+            const entityName = this.getStringParam(params, 'EntityName');
+            const tableName = this.getStringParam(params, 'TableName');
+            const schemaName = this.getStringParam(params, 'SchemaName');
+
+            if (!entityID && !entityName && !tableName) {
+                return {
+                    Success: false,
+                    ResultCode: 'MISSING_PARAMETER',
+                    Message: 'Provide at least one of: EntityID, EntityName, or TableName.',
+                };
+            }
+
+            const entityInfo = await this.findEntity(entityID, entityName, tableName, schemaName, params);
+
+            if (!entityInfo) {
+                this.addOutputParam(params, 'EntityInfo', null);
+                return {
+                    Success: false,
+                    ResultCode: 'ENTITY_NOT_FOUND',
+                    Message: 'No entity was found matching the provided identifiers.',
+                };
+            }
+
+            this.addOutputParam(params, 'EntityInfo', entityInfo);
+            return {
+                Success: true,
+                ResultCode: 'SUCCESS',
+                Message: `Entity '${entityInfo.EntityName}' found with ${entityInfo.Columns.length} column(s).`,
+            };
+        } catch (err) {
+            return this.handleUnexpected(err, 'Describe Entity');
+        }
+    }
+
+    // ─── Private helpers ──────────────────────────────────────────────────
+
+    /** Resolve the entity using whichever identifier the caller supplied. */
+    private async findEntity(
+        entityID: string | undefined,
+        entityName: string | undefined,
+        tableName: string | undefined,
+        schemaName: string | undefined,
+        params: RunActionParams
+    ): Promise<EntityInfo | null> {
+        const md = new Metadata(); // global-provider-ok: MJAPI server-side, single-provider deployment
+
+        // Fast path: look up by ID or name in the in-memory metadata cache.
+        let entity = entityID
+            ? md.Entities.find(e => UUIDsEqual(e.ID, entityID))
+            : entityName
+            ? md.Entities.find(e => e.Name.toLowerCase() === entityName.toLowerCase())
+            : md.Entities.find(
+                e =>
+                    e.BaseTable.toLowerCase() === (tableName ?? '').toLowerCase() &&
+                    (!schemaName || (e.SchemaName ?? '').toLowerCase() === schemaName.toLowerCase())
+            );
+
+        if (!entity) return null;
+
+        // Load columns from Entity Fields via RunView.
+        const columns = await this.loadEntityColumns(entity.ID, params);
+        return {
+            EntityID: entity.ID,
+            EntityName: entity.Name,
+            SchemaName: entity.SchemaName ?? '',
+            TableName: entity.BaseTable ?? '',
+            Description: entity.Description ?? null,
+            Columns: columns,
+        };
+    }
+
+    /** Load column definitions for a given entity ID. */
+    private async loadEntityColumns(
+        entityID: string,
+        params: RunActionParams
+    ): Promise<ColumnInfo[]> {
+        const rv = new RunView();
+        const result = await rv.RunView<{
+            Name: string;
+            Type: string;
+            AllowsNull: boolean;
+            MaxLength: number | null;
+            Description: string | null;
+            IsRequired: boolean;
+        }>({
+            EntityName: 'MJ: Entity Fields',
+            ExtraFilter: `EntityID = '${escapeSqlLiteral(entityID)}'`,
+            Fields: ['Name', 'Type', 'AllowsNull', 'MaxLength', 'Description', 'IsRequired'],
+            OrderBy: 'Sequence ASC',
+            ResultType: 'simple',
+        }, params.ContextUser);
+
+        if (!result.Success) return [];
+
+        return result.Results.map(f => ({
+            Name: f.Name,
+            Type: f.Type,
+            IsNullable: f.AllowsNull,
+            MaxLength: f.MaxLength,
+            Description: f.Description,
+            IsRequired: f.IsRequired,
+        }));
+    }
+}