@kinotic-ai/kinotic-cli 1.0.0

package/dist/commands/initialize.js

@@ -0,0 +1,102 @@
+import { Command, Flags } from '@oclif/core';
+import fs from 'fs';
+import path from 'path';
+import chalk from 'chalk';
+import { input } from '@inquirer/prompts';
+import { isKinoticProject, saveKinoticProjectConfig } from '../internal/state/KinoticProjectConfigUtil.js';
+import { KinoticProjectConfig } from '@kinotic-ai/core';
+/**
+ * Validates the application name according to server requirements:
+ * - First character must be a letter
+ * - Can only contain letters, numbers, periods, underscores, or dashes
+ */
+function validateApplicationName(name) {
+    if (!name || name.length === 0) {
+        return 'Application name cannot be empty';
+    }
+    // First character must be a letter
+    if (!/^[a-zA-Z]/.test(name)) {
+        return 'Application name must start with a letter';
+    }
+    // Can only contain letters, numbers, periods, underscores, or dashes
+    if (!/^[a-zA-Z][a-zA-Z0-9._-]*$/.test(name)) {
+        return 'Application name can only contain letters, numbers, periods, underscores, or dashes';
+    }
+    return true;
+}
+export class Initialize extends Command {
+    static aliases = ['init'];
+    static description = 'This will initialize a new Kinotic Project for use with the Kinotic CLI.';
+    static examples = [
+        '$ kinotic initialize --application my.app --entities path/to/entities --generated path/to/services',
+        '$ kinotic init --application my.app --entities path/to/entities --generated path/to/services',
+        '$ kinotic init -a my.app -e path/to/entities -g path/to/services',
+    ];
+    static flags = {
+        application: Flags.string({ char: 'a', description: 'The name of the application you want to use', required: false }),
+        entities: Flags.string({ char: 'e', description: 'Path to the directory containing the Entity definitions', required: false }),
+        generated: Flags.string({ char: 'g', description: 'Path to the directory to write generated Services', required: false }),
+    };
+    async run() {
+        const { flags } = await this.parse(Initialize);
+        if (await isKinoticProject()) {
+            this.log(chalk.red('Error: ') + ' The working directory is already a Kinotic Project');
+            return;
+        }
+        // Prompt for missing values
+        let application = flags.application;
+        if (!application) {
+            application = await input({
+                message: 'What is the name of your application?',
+                validate: (input) => {
+                    if (input.trim() === '') {
+                        return 'Application name is required';
+                    }
+                    return validateApplicationName(input.trim());
+                }
+            });
+        }
+        else {
+            // Validate provided application name from flag
+            const validation = validateApplicationName(application);
+            if (validation !== true) {
+                this.error(validation);
+            }
+        }
+        let entitiesPath = flags.entities;
+        if (!entitiesPath) {
+            entitiesPath = await input({
+                message: 'Path to the directory containing Entity definitions:',
+                default: 'src/entities',
+                validate: (input) => input.trim() !== '' || 'Entities path is required'
+            });
+        }
+        let generatedPath = flags.generated;
+        if (!generatedPath) {
+            generatedPath = await input({
+                message: 'Path to the directory to write generated Services:',
+                default: 'src/generated',
+                validate: (input) => input.trim() !== '' || 'Generated path is required'
+            });
+        }
+        const entitiesAbsPath = path.resolve(entitiesPath);
+        const generatedAbsPath = path.resolve(generatedPath);
+        if (!fs.existsSync(entitiesAbsPath)) {
+            this.error(`Entities path does not exist: ${entitiesAbsPath}`);
+        }
+        if (!fs.existsSync(generatedAbsPath)) {
+            this.error(`Generated path does not exist: ${generatedAbsPath}`);
+        }
+        // Only use TypescriptProjectConfig for initialization
+        const configDir = path.resolve(process.cwd(), '.config');
+        const configObj = new KinoticProjectConfig();
+        // Don't set name - it will be loaded from package.json
+        configObj.application = application;
+        configObj.entitiesPaths = [entitiesPath];
+        configObj.generatedPath = generatedPath;
+        configObj.validate = false;
+        configObj.fileExtensionForImports = '.js';
+        await saveKinoticProjectConfig(configObj, configDir);
+        this.log(chalk.green('Success:') + ' Initialized Project');
+    }
+}

package/dist/commands/synchronize.d.ts

@@ -0,0 +1,17 @@
+import { Command } from '@oclif/core';
+export declare class Synchronize extends Command {
+    static aliases: string[];
+    static description: string;
+    static examples: string[];
+    static flags: {
+        server: import("@oclif/core/lib/interfaces/parser.js").OptionFlag<string | undefined, import("@oclif/core/lib/interfaces/parser.js").CustomOptions>;
+        publish: import("@oclif/core/lib/interfaces/parser.js").BooleanFlag<boolean>;
+        verbose: import("@oclif/core/lib/interfaces/parser.js").BooleanFlag<boolean>;
+        authHeaderFile: import("@oclif/core/lib/interfaces/parser.js").OptionFlag<string | undefined, import("@oclif/core/lib/interfaces/parser.js").CustomOptions>;
+        dryRun: import("@oclif/core/lib/interfaces/parser.js").BooleanFlag<boolean>;
+    };
+    run(): Promise<void>;
+    logVerbose(message: string | (() => string), verbose: boolean): void;
+    private synchronizeEntity;
+    private synchronizeNamedQueries;
+}

package/dist/commands/synchronize.js

@@ -0,0 +1,154 @@
+import { isKinoticProject, loadKinoticProjectConfig } from '../internal/state/KinoticProjectConfigUtil.js';
+import { Kinotic } from '@kinotic-ai/core';
+import { EntityDefinition, NamedQueriesDefinition, OsApiPlugin, Project, ProjectType } from '@kinotic-ai/os-api';
+import { Command, Flags } from '@oclif/core';
+import chalk from 'chalk';
+import { WebSocket } from 'ws';
+import { CodeGenerationService } from '../internal/CodeGenerationService.js';
+import { ProjectMigrationService } from '../internal/ProjectMigrationService.js';
+import { resolveServer } from '../internal/state/Environment.js';
+import { connectAndUpgradeSession } from '../internal/Utils.js';
+// This is required when running Kinotic from node
+Object.assign(global, { WebSocket });
+Kinotic.use(OsApiPlugin);
+export class Synchronize extends Command {
+    static aliases = ['sync'];
+    static description = 'Synchronize the local Entity definitions with the Kinotic Server';
+    static examples = [
+        '$ kinotic synchronize',
+        '$ kinotic sync',
+        '$ kinotic synchronize --server http://localhost:9090 --publish --verbose',
+        '$ kinotic sync -p -v -s http://localhost:9090'
+    ];
+    static flags = {
+        server: Flags.string({ char: 's', description: 'The Kinotic server to connect to' }),
+        publish: Flags.boolean({ char: 'p', description: 'Publish each Entity after save/update' }),
+        verbose: Flags.boolean({ char: 'v', description: 'Enable verbose logging' }),
+        authHeaderFile: Flags.string({ char: 'f', description: 'JSON File containing authentication headers', required: false }),
+        dryRun: Flags.boolean({ description: 'Dry run enables verbose logging and does not save any changes to the server' })
+    };
+    async run() {
+        const { flags } = await this.parse(Synchronize);
+        try {
+            if (!(await isKinoticProject())) {
+                this.error('The working directory is not a Kinotic Project');
+            }
+            const kinoticProjectConfig = await loadKinoticProjectConfig();
+            let serverUrl = '';
+            if (!flags.dryRun) {
+                const serverConfig = await resolveServer(this.config.configDir, flags.server);
+                serverUrl = serverConfig.url;
+            }
+            if (flags.dryRun || await connectAndUpgradeSession(serverUrl, this, flags.authHeaderFile)) {
+                try {
+                    let project = null;
+                    if (!flags.dryRun) {
+                        await Kinotic.applications.createApplicationIfNotExist(kinoticProjectConfig.application, '');
+                        project = new Project(null, kinoticProjectConfig.application, kinoticProjectConfig.name, kinoticProjectConfig.description);
+                        project.sourceOfTruth = ProjectType.TYPESCRIPT;
+                        project = await Kinotic.projects.createProjectIfNotExist(project);
+                    }
+                    const codeGenerationService = new CodeGenerationService(kinoticProjectConfig.application, kinoticProjectConfig.fileExtensionForImports, this);
+                    await codeGenerationService
+                        .generateAllEntities(kinoticProjectConfig, flags.verbose || flags.dryRun, async (entityInfo, services) => {
+                        // combine named queries from generated services
+                        const namedQueries = [];
+                        for (let serviceInfo of services) {
+                            namedQueries.push(...serviceInfo.namedQueries);
+                        }
+                        // We sync named queries first since currently the backend cache eviction logic is a little dumb
+                        // i.e. The cache eviction for the structure deletes the GraphQL schema
+                        //      This will evict the named query execution plan cache
+                        //      We want to make sure the GraphQL schema is updated after both these are updated and the structure below
+                        if (!flags.dryRun && namedQueries.length > 0) {
+                            await this.synchronizeNamedQueries(project.id, entityInfo.entity, namedQueries);
+                        }
+                        if (!flags.dryRun) {
+                            await this.synchronizeEntity(project.id, entityInfo.entity, flags.publish, flags.verbose);
+                        }
+                    });
+                    // Apply migrations after entity synchronization
+                    if (!flags.dryRun) {
+                        const migrationService = new ProjectMigrationService(this);
+                        await migrationService.applyMigrations(project.id, './migrations', flags.verbose);
+                    }
+                    this.log(`Synchronization Complete For application: ${kinoticProjectConfig.application}`);
+                }
+                catch (e) {
+                    if (e instanceof Error) {
+                        this.error(e.message);
+                    }
+                }
+            }
+            await Kinotic.disconnect();
+        }
+        catch (e) {
+            if (e instanceof Error) {
+                this.log(chalk.red('Error: ') + e.message);
+            }
+            else {
+                this.log(chalk.red('Error: ') + e);
+            }
+            await Kinotic.disconnect();
+        }
+        return;
+    }
+    logVerbose(message, verbose) {
+        if (verbose) {
+            if (typeof message === 'function') {
+                this.log(message());
+            }
+            else {
+                this.log(message);
+            }
+        }
+    }
+    async synchronizeEntity(projectId, entity, publish, verbose) {
+        const entityDefinitionService = Kinotic.entityDefinitions;
+        const application = entity.namespace;
+        const name = entity.name;
+        const structureId = (application + '.' + name).toLowerCase();
+        this.log(`Synchronizing Entity: ${application}.${name}`);
+        try {
+            let structure = await entityDefinitionService.findById(structureId);
+            if (structure) {
+                if (structure.published) {
+                    this.log(chalk.bold(`Entity ${chalk.blue(application + '.' + name)} is Published. ${chalk.yellow('(Supported Modifications: New Fields. Un-Publish for all other changes.)')}`));
+                }
+                // update existing entity
+                structure.entityDefinition = entity;
+                this.logVerbose(`Updating Entity: ${application}.${name}`, verbose);
+                structure = await entityDefinitionService.save(structure);
+            }
+            else {
+                structure = new EntityDefinition(application, projectId, name, entity);
+                this.logVerbose(`Creating Entity: ${application}.${name}`, verbose);
+                structure = await entityDefinitionService.create(structure);
+            }
+            // publish if we need to
+            if (!structure.published && publish && structure?.id) {
+                this.logVerbose(`Publishing Entity: ${application}.${name}`, verbose);
+                await entityDefinitionService.publish(structure.id);
+            }
+        }
+        catch (e) {
+            const message = e?.message || e;
+            this.log(chalk.red('Error') + ` Synchronizing Entity: ${structureId}, Exception: ${message}`);
+        }
+    }
+    async synchronizeNamedQueries(projectId, entity, namedQueries) {
+        const namedQueriesService = Kinotic.namedQueriesDefinitions;
+        const application = entity.namespace;
+        const structure = entity.name;
+        const id = (application + '.' + structure).toLowerCase();
+        this.log(`Synchronizing Named Queries for Entity: ${application}.${structure}`);
+        try {
+            const namedQueriesDefinition = new NamedQueriesDefinition(id, application, projectId, structure, namedQueries);
+            await namedQueriesService.save(namedQueriesDefinition);
+        }
+        catch (e) {
+            const message = e?.message || e;
+            this.log(chalk.red('Error') + ` Synchronizing Named Queries for Entity: ${id}, Exception: ${message}`);
+        }
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1 @@
+export { run } from '@oclif/core';

package/dist/index.js

@@ -0,0 +1 @@
+export { run } from '@oclif/core';

package/dist/internal/CodeGenerationService.d.ts

@@ -0,0 +1,24 @@
+import { KinoticProjectConfig } from '@kinotic-ai/core';
+import { Logger } from './Logger.js';
+import { EntityInfo, GeneratedServiceInfo } from './Utils.js';
+export type GeneratedEntityProcessor = (entityInfo: EntityInfo, serviceInfo: GeneratedServiceInfo[]) => Promise<void>;
+/**
+ * Helper service for generating code.s
+ */
+export declare class CodeGenerationService {
+    private readonly fileExtensionForImports;
+    private readonly logger;
+    private readonly engine;
+    private readonly tsMorphProject;
+    private readonly conversionContext;
+    constructor(application: string, fileExtensionForImports: string, logger: Logger);
+    generateAllEntities(projectConfig: KinoticProjectConfig, verbose: boolean, entityProcessor?: GeneratedEntityProcessor): Promise<void>;
+    private processEntities;
+    private generateEntityService;
+    /**
+     * Adds invocation logic to named queries and returns the {@link FunctionDefinition}s that define them.
+     */
+    private processNamedQueries;
+    private createC3TypeForReturnType;
+    private createStatementMapper;
+}

package/dist/internal/CodeGenerationService.js

@@ -0,0 +1,256 @@
+import { FunctionDefinition, ObjectC3Type } from '@kinotic-ai/idl';
+import fs from 'fs';
+import { Liquid } from 'liquidjs';
+import path from 'path';
+import { fileURLToPath } from 'url';
+import { PageableC3Type, PageC3Type } from '@kinotic-ai/os-api';
+import { createImportString } from './converter/codegen/StatementMapper.js';
+import { StatementMapperConversionState } from './converter/codegen/StatementMapperConversionState.js';
+import { StatementMapperConverterStrategy } from './converter/codegen/StatementMapperConverterStrategy.js';
+import { createConversionContext } from './converter/IConversionContext.js';
+import { tsDecoratorToC3Decorator } from './converter/typescript/ConverterUtils.js';
+import { TypescriptConversionState } from './converter/typescript/TypescriptConversionState.js';
+import { TypescriptConverterStrategy } from './converter/typescript/TypescriptConverterStrategy.js';
+import { convertAllEntities, createTsMorphProject, getRelativeImportPath, tryGetNodeModuleName, writeEntityJsonToFilesystem, writeGeneratedServiceInfoToFilesystem } from './Utils.js';
+import chalk from 'chalk';
+/**
+ * Helper service for generating code.s
+ */
+export class CodeGenerationService {
+    fileExtensionForImports;
+    logger;
+    engine;
+    tsMorphProject;
+    conversionContext;
+    constructor(application, fileExtensionForImports, logger) {
+        this.fileExtensionForImports = fileExtensionForImports;
+        this.logger = logger;
+        this.engine = new Liquid({
+            root: path.resolve(path.dirname(fileURLToPath(import.meta.url)), '../templates/'), // root for templates lookup
+            extname: '.liquid'
+        });
+        this.tsMorphProject = createTsMorphProject();
+        const state = new TypescriptConversionState(application);
+        state.shouldAddSourcePathToMetadata = false;
+        this.conversionContext = createConversionContext(new TypescriptConverterStrategy(state, logger));
+    }
+    async generateAllEntities(projectConfig, verbose, entityProcessor) {
+        for (const entitiesPath of projectConfig.entitiesPaths) {
+            const config = {
+                application: projectConfig.application,
+                entitiesPath: entitiesPath,
+                verbose: verbose,
+                logger: this.logger
+            };
+            await this.processEntities(config, projectConfig, entityProcessor);
+        }
+    }
+    async processEntities(config, projectConfig, entityProcessor) {
+        if (!fs.existsSync(config.entitiesPath)) {
+            throw new Error(`Entities path does not exist: ${config.entitiesPath}`);
+        }
+        const convertedEntities = convertAllEntities(config);
+        if (convertedEntities.length > 0) {
+            for (const entityInfo of convertedEntities) {
+                this.logger.logVerbose(`Generated Structure Mapping for ${entityInfo.entity.namespace}.${entityInfo.entity.name}`, config.verbose);
+                const generatedServices = [];
+                generatedServices.push(await this.generateEntityService(false, entityInfo, projectConfig));
+                if (entityInfo.multiTenantSelectionEnabled) {
+                    generatedServices.push(await this.generateEntityService(true, entityInfo, projectConfig));
+                }
+                if (config.verbose) {
+                    await writeEntityJsonToFilesystem(projectConfig.generatedPath, entityInfo.entity, this.logger);
+                    for (let generatedServiceInfo of generatedServices) {
+                        if (generatedServiceInfo.namedQueries.length > 0) {
+                            await writeGeneratedServiceInfoToFilesystem(projectConfig.generatedPath, generatedServiceInfo, this.logger);
+                        }
+                    }
+                }
+                if (entityProcessor) {
+                    await entityProcessor(entityInfo, generatedServices);
+                }
+            }
+        }
+        else {
+            this.logger.logVerbose(`No Entities found For namespace: ${config.application} and Entities Path: ${config.entitiesPath}`, config.verbose);
+        }
+    }
+    async generateEntityService(adminService, entityInfo, projectConfig) {
+        const adminPrefix = (adminService ? 'Admin' : '');
+        const fileExtensionForImports = this.fileExtensionForImports;
+        const generatedPath = projectConfig.generatedPath;
+        const baseEntityServicePath = path.resolve(generatedPath, 'generated', `Base${entityInfo.entity.name}${adminPrefix}EntityService.ts`);
+        const entityServicePath = path.resolve(generatedPath, `${entityInfo.entity.name}${adminPrefix}EntityService.ts`);
+        const entityName = entityInfo.entity.name;
+        const entityNamespace = entityInfo.entity.namespace;
+        const defaultExport = entityInfo.defaultExport;
+        const validate = projectConfig.validate;
+        let entityImportPath = tryGetNodeModuleName(entityInfo.exportedFromFile);
+        if (!entityImportPath) {
+            entityImportPath = getRelativeImportPath(baseEntityServicePath, entityInfo.exportedFromFile, fileExtensionForImports);
+        }
+        // We don't add validation logic to admin services since there are no save/update methods there
+        let statement = null;
+        let validationLogic = null;
+        if (!adminService) {
+            statement = this.createStatementMapper(entityInfo);
+            validationLogic = statement.toStatementString();
+        }
+        const importStatements = createImportString(statement, baseEntityServicePath, fileExtensionForImports) || '';
+        //  We always generate the base entity service. This way if our internal logic changes we can update it
+        fs.mkdirSync(path.dirname(baseEntityServicePath), { recursive: true });
+        const baseReadStream = await this.engine.renderFileToNodeStream(`Base${adminPrefix}EntityService`, {
+            entityName,
+            entityNamespace,
+            defaultExport,
+            entityImportPath,
+            validationLogic,
+            importStatements
+        });
+        let baseWriteStream = fs.createWriteStream(baseEntityServicePath);
+        baseReadStream.pipe(baseWriteStream);
+        //  we only generate if the file does not exist
+        let namedQueries = [];
+        if (!fs.existsSync(entityServicePath)) {
+            const readStream = await this.engine.renderFileToNodeStream(`${adminPrefix}EntityService`, {
+                entityName,
+                entityNamespace,
+                validate,
+                fileExtensionForImports
+            });
+            let writeStream = fs.createWriteStream(entityServicePath);
+            readStream.pipe(writeStream);
+        }
+        else {
+            // if it already exists we check if there are any named queries defined
+            namedQueries = await this.processNamedQueries(`${entityName}${adminPrefix}EntityService`, entityServicePath);
+        }
+        return {
+            entityServiceName: `${entityName}${adminPrefix}EntityService`,
+            namedQueries: namedQueries
+        };
+    }
+    /**
+     * Adds invocation logic to named queries and returns the {@link FunctionDefinition}s that define them.
+     */
+    async processNamedQueries(entityServiceName, entityServicePath) {
+        const namedQueries = [];
+        this.tsMorphProject.addSourceFileAtPath(entityServicePath);
+        const entityServiceSource = this.tsMorphProject.getSourceFile(entityServicePath);
+        // Currently we only support named queries when added to the generated entity service class
+        if (entityServiceSource) {
+            const serviceClass = entityServiceSource.getClass(entityServiceName);
+            if (serviceClass) {
+                // Convert all methods that have a @Query decorator to a C3 FunctionDefinition
+                // These will be used to define the named queries for the structure
+                for (const method of serviceClass?.getInstanceMethods()) {
+                    const queryDecorator = method.getDecorator('Query');
+                    if (queryDecorator) {
+                        const methodName = method.getName();
+                        const functionDefinition = new FunctionDefinition(methodName, [tsDecoratorToC3Decorator(queryDecorator)]);
+                        // TODO: add more generic decorator handling
+                        const policyDecorator = method.getDecorator('Policy');
+                        if (policyDecorator) {
+                            functionDefinition.addDecorator(tsDecoratorToC3Decorator(policyDecorator));
+                        }
+                        functionDefinition.returnType = this.createC3TypeForReturnType(method.getReturnType());
+                        // Find page parameter if any and store all parameter names for later
+                        const argNames = [];
+                        let pageableParameterName = null;
+                        const parameters = method.getParameters();
+                        for (let i = 0; i < parameters.length; i++) {
+                            let parameter = parameters[i];
+                            const parameterName = parameter.getName();
+                            const parameterTypeName = parameter.getType().getSymbol()?.getName();
+                            let parameterC3Type;
+                            if (parameterTypeName === 'Pageable'
+                                || parameterTypeName === 'OffsetPageable'
+                                || parameterTypeName === 'CursorPageable') {
+                                if (i > 0 && i < parameters.length - 1) {
+                                    this.logger.log(chalk.yellow(`It is best if Pageable is always the first or last parameter.`));
+                                }
+                                pageableParameterName = parameterName;
+                                parameterC3Type = new PageableC3Type();
+                            }
+                            else {
+                                argNames.push(parameterName);
+                                parameterC3Type = this.conversionContext.convert(parameter.getType());
+                            }
+                            functionDefinition.addParameter(parameterName, parameterC3Type);
+                        }
+                        // Code generated is similar to the following
+                        // const parameters = [
+                        //     {key: 'who', value: who},
+                        //     {key: 'howMany', value: howMany}
+                        // ]
+                        // return this.namedQuery('namedQueryTest', parameters)
+                        method.setBodyText(writer => {
+                            writer.writeLine('/** Autogenerated code, changes will be overwritten. **/');
+                            if (argNames.length > 0) {
+                                writer.writeLine('const parameters = [')
+                                    .indent(() => {
+                                    for (let i = 0; i < argNames.length; i++) {
+                                        let argName = argNames[i];
+                                        writer.write(`{key: '${argName}', value: ${argName}}`);
+                                        if (i != argNames.length - 1) {
+                                            writer.write(',');
+                                        }
+                                        writer.newLine();
+                                    }
+                                })
+                                    .writeLine(']');
+                            }
+                            if (pageableParameterName) {
+                                writer.writeLine(`return this.namedQueryPage('${methodName}', ${argNames.length > 0 ? 'parameters' : '[]'}, ${pageableParameterName})`);
+                            }
+                            else {
+                                writer.writeLine(`return this.namedQuery('${methodName}', ${argNames.length > 0 ? 'parameters' : '[]'})`);
+                            }
+                        });
+                        namedQueries.push(functionDefinition);
+                    }
+                }
+                await entityServiceSource.save();
+            }
+        }
+        return namedQueries;
+    }
+    createC3TypeForReturnType(returnType) {
+        let ret;
+        // All methods must return a Promise
+        if (returnType.getSymbol()?.getName() === 'Promise') {
+            let typeArguments = returnType.getTypeArguments();
+            if (typeArguments?.length !== 1) {
+                throw new Error('Promise must have exactly one type argument');
+            }
+            returnType = typeArguments[0];
+            // If a Page is being returned then use internal PageC3Type for simplicity
+            if (returnType.getSymbol()?.getName() === 'Page'
+                || returnType.getSymbol()?.getName() === 'IterablePage') {
+                typeArguments = returnType.getTypeArguments();
+                if (typeArguments?.length !== 1) {
+                    throw new Error('Page must have exactly one type argument');
+                }
+                const contentType = this.conversionContext.convert(typeArguments[0]);
+                if (contentType instanceof ObjectC3Type) {
+                    ret = new PageC3Type(contentType);
+                }
+                else {
+                    throw new Error('Only Object types are supported for Page content types');
+                }
+            }
+            else {
+                ret = this.conversionContext.convert(returnType);
+            }
+        }
+        else {
+            throw new Error('Only methods that return a Promise are supported for named queries');
+        }
+        return ret;
+    }
+    createStatementMapper(entityInfo) {
+        const state = new StatementMapperConversionState(entityInfo.entity.namespace);
+        const conversionContext = createConversionContext(new StatementMapperConverterStrategy(state, this.logger));
+        return conversionContext.convert(entityInfo.entity);
+    }
+}

package/dist/internal/Logger.d.ts

@@ -0,0 +1,27 @@
+import { PrettyPrintableError } from '@oclif/core/lib/errors';
+export type Logger = {
+    log: (message?: string, ...args: any[]) => void;
+    warn(input: string | Error): string | Error;
+    error(input: string | Error, options: {
+        code?: string;
+        exit: false;
+    } & PrettyPrintableError): void;
+    error(input: string | Error, options?: {
+        code?: string;
+        exit?: number;
+    } & PrettyPrintableError): never;
+    logVerbose(message: string | (() => string), verbose: boolean): void;
+};
+export declare class ConsoleLogger implements Logger {
+    log(message?: string, ...args: any[]): void;
+    warn(input: string | Error): string | Error;
+    error(input: string | Error, options: {
+        code?: string;
+        exit: false;
+    } & PrettyPrintableError): void;
+    error(input: string | Error, options?: {
+        code?: string;
+        exit?: number;
+    } & PrettyPrintableError): never;
+    logVerbose(message: string | (() => string), verbose: boolean): void;
+}

package/dist/internal/Logger.js

@@ -0,0 +1,35 @@
+export class ConsoleLogger {
+    log(message, ...args) {
+        console.log(message, ...args);
+    }
+    warn(input) {
+        const message = input instanceof Error ? input.message : input;
+        console.warn(message);
+        return input;
+    }
+    error(input, options) {
+        const message = input instanceof Error ? input.message : input;
+        console.error('Error:', message);
+        if (options) {
+            if (options.code) {
+                console.error('Code:', options.code);
+            }
+            if (options.ref) {
+                console.error('Reference:', options.ref);
+            }
+            if (options.suggestions && options.suggestions.length > 0) {
+                console.error('Suggestions:');
+                options.suggestions.forEach((suggestion) => console.error(`- ${suggestion}`));
+            }
+        }
+        if (options?.exit !== undefined && options.exit !== false) {
+            process.exit(typeof options.exit === 'number' ? options.exit : 1);
+        }
+    }
+    logVerbose(message, verbose) {
+        if (verbose) {
+            const output = typeof message === 'function' ? message() : message;
+            console.log(output);
+        }
+    }
+}

package/dist/internal/ProjectMigrationService.d.ts

@@ -0,0 +1,28 @@
+import { Logger } from './Logger.js';
+/**
+ * Internal service for loading and applying migrations from the local filesystem.
+ * Looks for migration files in a 'migrations' folder in the project root.
+ */
+export declare class ProjectMigrationService {
+    private readonly migrationService;
+    private readonly logger;
+    constructor(logger: Logger);
+    /**
+     * Loads migration files from the migrations directory and applies any new ones.
+     *
+     * @param projectId the project identifier to apply migrations to
+     * @param migrationsDir the directory containing migration files (defaults to './migrations')
+     * @param verbose whether to enable verbose logging
+     */
+    applyMigrations(projectId: string, migrationsDir?: string, verbose?: boolean): Promise<void>;
+    /**
+     * Loads only the migration files that need to be applied, checking everything in one pass.
+     */
+    private loadUnappliedMigrations;
+    /**
+     * Extracts the version number from a migration filename.
+     * Expected format: V{version}__{description}.sql
+     */
+    private extractVersionFromFilename;
+    private logVerbose;
+}