@zintrust/core 0.1.28 → 0.1.30

package/src/cli/scaffolding/ServiceScaffolder.js

@@ -0,0 +1,390 @@
+/**
+ * ServiceScaffolder - Generate microservices within a project
+ * Creates service structure with controllers, models, routes, and config
+ */
+import { FileGenerator } from '../scaffolding/FileGenerator.js';
+import { Logger } from '../../config/logger.js';
+import * as path from '../../node-singletons/path.js';
+/**
+ * ServiceScaffolder generates microservices with all necessary files
+ */
+/**
+ * Validate service options
+ */
+export function validateOptions(options) {
+    const errors = [];
+    if (options.name === undefined || options.name.trim().length === 0) {
+        errors.push('Service name is required');
+    }
+    if (options.name !== undefined && !/^[a-z]+$/.test(options.name)) {
+        errors.push('Service name must contain only lowercase letters');
+    }
+    if (options.port !== undefined && (options.port < 1024 || options.port > 65535)) {
+        errors.push('Port must be between 1024 and 65535');
+    }
+    if (options.domain !== undefined && !/^[a-z]+$/.test(options.domain)) {
+        errors.push('Domain must contain only lowercase letters');
+    }
+    return {
+        valid: errors.length === 0,
+        errors,
+    };
+}
+/**
+ * Get service path
+ */
+export function getServicePath(projectRoot, options) {
+    const domain = options.domain ?? 'default';
+    return path.join(projectRoot, 'src', 'services', domain, options.name);
+}
+/**
+ * Generate service structure
+ */
+// eslint-disable-next-line @typescript-eslint/promise-function-async
+export function scaffold(projectRoot, options) {
+    try {
+        // Validate options
+        const validation = validateOptions(options);
+        if (!validation.valid) {
+            return Promise.resolve({
+                success: false,
+                serviceName: options.name,
+                servicePath: '',
+                filesCreated: [],
+                message: `Validation failed: ${validation.errors.join(', ')}`,
+            });
+        }
+        const servicePath = getServicePath(projectRoot, options);
+        // Check if service already exists
+        if (FileGenerator.directoryExists(servicePath)) {
+            return Promise.resolve({
+                success: false,
+                serviceName: options.name,
+                servicePath,
+                filesCreated: [],
+                message: `Service '${options.name}' already exists at ${servicePath}`,
+            });
+        }
+        createServiceDirectories(servicePath);
+        const filesCreated = createServiceFiles(servicePath, options);
+        return Promise.resolve({
+            success: true,
+            serviceName: options.name,
+            servicePath,
+            filesCreated,
+            message: `Service '${options.name}' scaffolded successfully`,
+        });
+    }
+    catch (error) {
+        Logger.error('Service scaffolding failed', error);
+        return Promise.resolve({
+            success: false,
+            serviceName: options.name,
+            servicePath: '',
+            filesCreated: [],
+            message: error.message,
+        });
+    }
+}
+/**
+ * Create service directory structure
+ */
+function createServiceDirectories(servicePath) {
+    const dirs = [
+        'src/controllers',
+        'src/models',
+        'src/services',
+        'src/middleware',
+        'src/migrations',
+        'src/factories',
+        'routes',
+    ];
+    for (const dir of dirs) {
+        FileGenerator.createDirectory(path.join(servicePath, dir));
+    }
+    Logger.info('✅ Created service directories');
+}
+/**
+ * Create initial service files
+ */
+function createServiceFiles(servicePath, options) {
+    const files = [
+        { path: 'service.config.json', content: generateServiceConfig(options) },
+        { path: 'src/index.ts', content: generateServiceIndex(options) },
+        { path: 'routes/api.ts', content: generateServiceRoutes(options) },
+        { path: 'src/controllers/ExampleController.ts', content: generateExampleController(options) },
+        { path: 'src/models/Example.ts', content: generateExampleModel(options) },
+        { path: '.env', content: generateServiceEnv(options) },
+        { path: 'src/middleware/index.ts', content: '// Service middleware exports\nexport {};\n' },
+        { path: 'README.md', content: generateServiceReadme(options) },
+    ];
+    const created = [];
+    for (const file of files) {
+        const fullPath = path.join(servicePath, file.path);
+        FileGenerator.writeFile(fullPath, file.content);
+        created.push(fullPath);
+    }
+    return created;
+}
+/**
+ * Generate service.config.json content
+ */
+function generateServiceConfig(options) {
+    const port = options.port ?? 3001;
+    const config = {
+        name: options.name,
+        domain: options.domain ?? 'default',
+        port,
+        version: '1.0.0',
+        description: `${options.name} microservice`,
+        database: {
+            isolation: options.database ?? 'shared',
+            migrations: options.withMigration !== false,
+        },
+        auth: {
+            strategy: options.auth ?? 'api-key',
+        },
+        tracing: {
+            enabled: true,
+            samplingRate: 1,
+        },
+    };
+    return JSON.stringify(config, null, 2);
+}
+/**
+ * Generate service index.ts
+ */
+function generateServiceIndex(options) {
+    return `/**
+ * ${options.name} Service - Entry Point
+ * Port: ${options.port ?? 3001}
+ * Database: ${options.database ?? 'shared'}
+ * Auth: ${options.auth ?? 'api-key'}
+ */
+
+import { Application, Server } from '../../index.js';
+import { Logger } from '../../config/logger';
+import { Env } from '../../config/env';
+import { esmDirname } from '../../common/index';
+import * as path from '../../node-singletons/path';
+
+const __dirname = esmDirname(import.meta.url);
+const port = Env.getInt('${options.name?.toUpperCase()}_PORT', ${options.port ?? 3001});
+
+async function start(): Promise<void> {
+  const app = Application.create(path.join(__dirname, '..'));
+  await app.boot();
+
+  const server = Server.create(app, port);
+  await server.listen();
+
+  Logger.info(\`${options.name} service running on port \${port}\`);
+}
+
+await start();
+`;
+}
+/**
+ * Generate service routes
+ */
+function generateServiceRoutes(options) {
+    return `/**
+ * ${options.name} Service Routes
+ */
+
+import { Router, type IRouter } from '../../index.js';
+
+export function registerRoutes(router: IRouter): void {
+  // Example route
+  Router.get(
+    router,
+    '/',
+    (_req, res) => {
+    res.json({ message: '${options.name} service' });
+    },
+    {
+      meta: {
+        summary: 'Service root',
+        tags: ['Service'],
+        responseStatus: 200,
+      },
+    }
+  );
+}
+`;
+}
+/**
+ * Generate example controller
+ */
+function generateExampleController(options) {
+    const className = `${options.name.charAt(0).toUpperCase()}${options.name.slice(1)}Controller`;
+    return `/**
+ * Example Controller for ${options.name} Service
+ */
+
+import { type IRequest, type IResponse, Controller } from '../../index.js';
+
+const controller = Object.freeze({
+  ...Controller,
+
+  /**
+   * List all items
+   */
+  async index(_req: IRequest, res: IResponse): Promise<void> {
+    res.json({ data: [] });
+  },
+
+  /**
+   * Create new item
+   */
+  async store(_req: IRequest, res: IResponse): Promise<void> {
+    res.setStatus(201).json({ created: true });
+  },
+
+  /**
+   * Get item by ID
+   */
+  async show(req: IRequest, res: IResponse): Promise<void> {
+    const { id } = req.getParams();
+    res.json({ id });
+  },
+
+  /**
+   * Update item
+   */
+  async update(req: IRequest, res: IResponse): Promise<void> {
+    const { id } = req.getParams();
+    res.json({ updated: true, id });
+  },
+
+  /**
+   * Delete item
+   */
+  async destroy(req: IRequest, res: IResponse): Promise<void> {
+    const { id } = req.getParams();
+    res.json({ deleted: true, id });
+  },
+};
+
+export type ${className}Api = typeof controller;
+
+export const ${className} = Object.freeze({
+  create(): ${className}Api {
+    return controller;
+  },
+});
+
+export default ${className};
+`;
+}
+/**
+ * Generate example model
+ */
+function generateExampleModel(options) {
+    return `/**
+ * Example Model for ${options.name} Service
+ */
+
+import { Model } from '../../index.js';
+
+export const Example = Model.define({
+  table: '${options.name}',
+  fillable: ['name', 'description'],
+  timestamps: true,
+  casts: {},
+}, {
+  // Define relationships here
+  // async user(model: IModel) { return model.belongsTo(User); }
+});
+`;
+}
+/**
+ * Generate service .env file
+ */
+function generateServiceEnv(options) {
+    return `# ${options.name} Service Configuration
+
+# Service Port
+${options.name?.toUpperCase()}_PORT=${options.port ?? 3001}
+
+# Database
+DATABASE_CONNECTION=${options.database === 'isolated' ? 'postgresql' : 'shared'}
+${options.database === 'isolated' ? `${options.name?.toUpperCase()}_DB_HOST=localhost\n${options.name?.toUpperCase()}_DB_DATABASE=${options.name}\n${options.name?.toUpperCase()}_DB_USER=postgres\n${options.name?.toUpperCase()}_DB_PASSWORD=postgres` : ''}
+
+# Authentication
+SERVICE_AUTH_STRATEGY=${options.auth ?? 'api-key'}
+SERVICE_AUTH_KEY=your-auth-key-here
+
+# Tracing
+SERVICE_TRACING_ENABLED=true
+SERVICE_TRACING_SAMPLING_RATE=1.0
+
+# Logging
+LOG_LEVEL=info
+`;
+}
+/**
+ * Get service configuration details
+ */
+function getServiceConfig(options) {
+    return {
+        domain: options.domain ?? 'default',
+        port: options.port ?? 3001,
+        database: options.database ?? 'shared',
+        auth: options.auth ?? 'api-key',
+        dbDescription: options.database === 'isolated'
+            ? 'This service uses an isolated database instance.'
+            : 'This service uses a shared database with schema isolation.',
+    };
+}
+/**
+ * Generate service README
+ */
+function generateServiceReadme(options) {
+    const config = getServiceConfig(options);
+    return `# ${options.name} Service
+
+Microservice for ${config.domain} domain.
+
+## Configuration
+
+- **Port**: ${config.port}
+- **Database**: ${config.database}
+- **Auth**: ${config.auth}
+
+## Getting Started
+
+\`\`\`bash
+# Start service
+npm start
+
+# Run tests
+npm test
+
+# Run migrations
+npm run migrate
+\`\`\`
+
+## Environment Variables
+
+See \`.env\` file for configuration options.
+
+## API Endpoints
+
+- \`GET /health\` - Health check
+- \`GET /\` - Service info
+
+## Database
+
+${config.dbDescription}
+
+## Authentication
+
+Uses \`${config.auth}\` authentication strategy.
+`;
+}
+export const ServiceScaffolder = Object.freeze({
+    validateOptions,
+    getServicePath,
+    scaffold,
+});

package/src/cli/scaffolding/TemplateEngine.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Template Engine
+ * Handles template rendering with variable substitution
+ * Sealed namespace with immutable template rendering methods
+ */
+export interface TemplateVariables {
+    [key: string]: string | number | boolean | undefined;
+}
+export interface Template {
+    name: string;
+    description: string;
+    files: TemplateFile[];
+    directories: string[];
+}
+/**
+ * A file that will be copied from a template source into the generated project.
+ * `path`   -> destination path in the generated project
+ * `source` -> template file path (relative to the template root directory)
+ */
+export interface TemplateFile {
+    path: string;
+    source: string;
+    isTemplate?: boolean;
+}
+/**
+ * TemplateEngine namespace - sealed for immutability
+ */
+export declare const TemplateEngine: Readonly<{
+    render: (content: string, variables: TemplateVariables) => string;
+    renderContent: (content: string, variables: TemplateVariables) => string;
+    renderPath: (content: string, variables: TemplateVariables) => string;
+    mergeVariables: (custom: TemplateVariables, defaults: TemplateVariables) => TemplateVariables;
+    hasVariables: (content: string) => boolean;
+    extractVariables: (content: string) => string[];
+}>;
+/**
+ * Built-in template definitions (file-based; no inline contents)
+ *
+ * `source` paths are relative to your template root directory (wherever the CLI loader reads from).
+ */
+export declare const BUILT_IN_TEMPLATES: Record<string, Template>;
+//# sourceMappingURL=TemplateEngine.d.ts.map

package/src/cli/scaffolding/TemplateEngine.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"TemplateEngine.d.ts","sourceRoot":"","sources":["../../../../src/cli/scaffolding/TemplateEngine.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,MAAM,WAAW,iBAAiB;IAChC,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,SAAS,CAAC;CACtD;AAED,MAAM,WAAW,QAAQ;IACvB,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,KAAK,EAAE,YAAY,EAAE,CAAC;IACtB,WAAW,EAAE,MAAM,EAAE,CAAC;CACvB;AAED;;;;GAIG;AACH,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,CAAC;IACf,UAAU,CAAC,EAAE,OAAO,CAAC;CACtB;AAmDD;;GAEG;AACH,eAAO,MAAM,cAAc;sBAjDM,MAAM,aAAa,iBAAiB,KAAG,MAAM;6BAA7C,MAAM,aAAa,iBAAiB,KAAG,MAAM;0BAA7C,MAAM,aAAa,iBAAiB,KAAG,MAAM;6BAiBpE,iBAAiB,YACf,iBAAiB,KAC1B,iBAAiB;4BASmB,MAAM,KAAG,OAAO;gCASZ,MAAM,KAAG,MAAM,EAAE;EAmB1D,CAAC;AAEH;;;;GAIG;AACH,eAAO,MAAM,kBAAkB,EAAE,MAAM,CAAC,MAAM,EAAE,QAAQ,CA8CvD,CAAC"}

package/src/cli/scaffolding/TemplateEngine.js

@@ -0,0 +1,107 @@
+/**
+ * Template Engine
+ * Handles template rendering with variable substitution
+ * Sealed namespace with immutable template rendering methods
+ */
+/**
+ * Render template content with variables
+ */
+const renderTemplate = (content, variables) => {
+    let result = content;
+    for (const [key, value] of Object.entries(variables)) {
+        if (value === undefined || value === null)
+            continue;
+        const regex = new RegExp(String.raw `{{\s*${key}\s*}}`, 'g');
+        result = result.replace(regex, String(value));
+    }
+    return result;
+};
+/**
+ * Get template variables with default values
+ */
+const mergeTemplateVariables = (custom, defaults) => {
+    return { ...defaults, ...custom };
+};
+/**
+ * Check if content contains template variables
+ * Uses a non-backtracking pattern to prevent ReDoS vulnerability (S5852)
+ * Limits variable name length to 255 characters as a practical constraint
+ */
+const hasTemplateVariables = (content) => {
+    return /\{\{[^}]{1,255}\}\}/.test(content);
+};
+/**
+ * Extract variable names from content
+ * Uses a non-backtracking pattern to prevent ReDoS vulnerability (S5852)
+ * Limits variable name length to 255 characters as a practical constraint
+ */
+const extractTemplateVariables = (content) => {
+    const matches = content.match(/\{\{([^}]{1,255})\}\}/g);
+    if (matches === null)
+        return [];
+    return matches
+        .map((match) => match.replaceAll(/\{\{|\}\}/g, '').trim())
+        .filter((v, i, arr) => arr.indexOf(v) === i); // Unique
+};
+/**
+ * TemplateEngine namespace - sealed for immutability
+ */
+export const TemplateEngine = Object.freeze({
+    render: renderTemplate,
+    renderContent: renderTemplate,
+    renderPath: renderTemplate,
+    mergeVariables: mergeTemplateVariables,
+    hasVariables: hasTemplateVariables,
+    extractVariables: extractTemplateVariables,
+});
+/**
+ * Built-in template definitions (file-based; no inline contents)
+ *
+ * `source` paths are relative to your template root directory (wherever the CLI loader reads from).
+ */
+export const BUILT_IN_TEMPLATES = {
+    basic: {
+        name: 'basic',
+        description: 'Basic ZinTrust application',
+        directories: [
+            'src',
+            'app/Models',
+            'app/Controllers',
+            'routes',
+            'tests/unit',
+            'tests/integration',
+            'database/migrations',
+            'database/seeders',
+        ],
+        files: [
+            { path: 'package.json', source: 'basic/package.json', isTemplate: true },
+            { path: '.env.example', source: 'basic/.env.example', isTemplate: true },
+            { path: 'tsconfig.json', source: 'basic/tsconfig.json' },
+            { path: '.gitignore', source: 'basic/.gitignore' },
+            { path: 'README.md', source: 'basic/README.md', isTemplate: true },
+            { path: 'src/index.ts', source: 'basic/src/index.ts' },
+            { path: 'routes/api.ts', source: 'basic/routes/api.ts', isTemplate: true },
+        ],
+    },
+    api: {
+        name: 'api',
+        description: 'RESTful API with microservices support',
+        directories: [
+            'src',
+            'app/Models',
+            'app/Controllers',
+            'app/Services',
+            'routes',
+            'tests/unit',
+            'tests/integration',
+            'database/migrations',
+            'database/seeders',
+            'services',
+        ],
+        files: [
+            { path: 'package.json', source: 'api/package.json', isTemplate: true },
+            { path: '.env.example', source: 'api/.env.example', isTemplate: true },
+            { path: 'README.md', source: 'api/README.md', isTemplate: true },
+        ],
+    },
+};

package/src/cli/scaffolding/TemplateGenerator.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Template Generator
+ * Scaffolds mail and notification markdown templates into the application source.
+ *
+ * Notes:
+ * - Generates into application folders (default: src/mail/markdown and src/notification/markdown)
+ * - Uses FileGenerator for consistent file I/O + logging
+ */
+export type MailTemplateCategory = 'auth' | 'transactional' | 'notifications';
+export type NotificationChannel = 'mail' | 'sms' | 'slack' | 'discord';
+export interface MailTemplateScaffoldOptions {
+    name: string;
+    category: MailTemplateCategory;
+    variables: string[];
+    copyright: string;
+    projectRoot: string;
+    overwrite?: boolean;
+}
+export interface NotificationTemplateScaffoldOptions {
+    name: string;
+    channels: NotificationChannel[];
+    variables: string[];
+    copyright: string;
+    projectRoot: string;
+    smsVariant?: 'short' | 'none';
+    overwrite?: boolean;
+}
+export interface TemplateScaffoldResult {
+    success: boolean;
+    filePath: string;
+    message: string;
+}
+export declare const TemplateGenerator: Readonly<{
+    validateTemplateName(name: string): void;
+    parseVariablesCsv(csv: string | undefined): string[];
+    scaffoldMailMarkdownTemplate(options: MailTemplateScaffoldOptions): TemplateScaffoldResult;
+    scaffoldNotificationMarkdownTemplate(options: NotificationTemplateScaffoldOptions): TemplateScaffoldResult;
+    ensureDirectories(projectRoot: string): void;
+}>;
+//# sourceMappingURL=TemplateGenerator.d.ts.map

package/src/cli/scaffolding/TemplateGenerator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"TemplateGenerator.d.ts","sourceRoot":"","sources":["../../../../src/cli/scaffolding/TemplateGenerator.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAOH,MAAM,MAAM,oBAAoB,GAAG,MAAM,GAAG,eAAe,GAAG,eAAe,CAAC;AAC9E,MAAM,MAAM,mBAAmB,GAAG,MAAM,GAAG,KAAK,GAAG,OAAO,GAAG,SAAS,CAAC;AAEvE,MAAM,WAAW,2BAA2B;IAC1C,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,oBAAoB,CAAC;IAC/B,SAAS,EAAE,MAAM,EAAE,CAAC;IACpB,SAAS,EAAE,MAAM,CAAC;IAClB,WAAW,EAAE,MAAM,CAAC;IACpB,SAAS,CAAC,EAAE,OAAO,CAAC;CACrB;AAED,MAAM,WAAW,mCAAmC;IAClD,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,mBAAmB,EAAE,CAAC;IAChC,SAAS,EAAE,MAAM,EAAE,CAAC;IACpB,SAAS,EAAE,MAAM,CAAC;IAClB,WAAW,EAAE,MAAM,CAAC;IACpB,UAAU,CAAC,EAAE,OAAO,GAAG,MAAM,CAAC;IAC9B,SAAS,CAAC,EAAE,OAAO,CAAC;CACrB;AAED,MAAM,WAAW,sBAAsB;IACrC,OAAO,EAAE,OAAO,CAAC;IACjB,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,MAAM,CAAC;CACjB;AAYD,eAAO,MAAM,iBAAiB;+BACD,MAAM,GAAG,IAAI;2BAejB,MAAM,GAAG,SAAS,GAAG,MAAM,EAAE;0CAKd,2BAA2B,GAAG,sBAAsB;kDAqC/E,mCAAmC,GAC3C,sBAAsB;mCAqCM,MAAM,GAAG,IAAI;EAY5C,CAAC"}