@gravito/scaffold 4.1.0 → 4.1.2

package/dist/index.d.cts

@@ -0,0 +1,924 @@
+import Handlebars from 'handlebars';
+
+/**
+ * Supported project profiles defining the set of included orbits and default drivers.
+ *
+ * @public
+ * @since 3.0.0
+ */
+type ProfileType = 'core' | 'scale' | 'enterprise';
+/**
+ * Resolved configuration for a project profile.
+ *
+ * @public
+ * @since 3.0.0
+ */
+interface ProfileConfig {
+    /** Map of default service drivers. */
+    drivers: {
+        database: string;
+        cache: string;
+        queue: string;
+        storage: string;
+        session: string;
+    };
+    /** List of enabled features and orbits. */
+    features: string[];
+    /** Workers configuration level for job queue system */
+    workers?: 'basic' | 'advanced' | 'production';
+}
+/**
+ * ProfileResolver manages the resolution of project profiles and feature add-ons.
+ *
+ * It maps high-level profiles (Core, Scale, Enterprise) to specific sets of
+ * service drivers and orbits, and handles the conditional inclusion of
+ * additional features.
+ *
+ * @public
+ * @since 3.0.0
+ */
+declare class ProfileResolver {
+    private static readonly DEFAULTS;
+    resolve(profile?: ProfileType, withFeatures?: string[]): ProfileConfig;
+    private applyFeature;
+    /**
+     * Validator for profile names
+     */
+    isValidProfile(profile: string): profile is ProfileType;
+    /**
+     * Validator for feature names
+     */
+    isValidFeature(feature: string): boolean;
+}
+
+/**
+ * package.json 結構
+ */
+interface PackageJson {
+    name?: string;
+    version?: string;
+    dependencies?: Record<string, string>;
+    devDependencies?: Record<string, string>;
+    [key: string]: unknown;
+}
+/**
+ * 驗證結果
+ */
+interface ValidationResult {
+    /** 是否通過驗證 */
+    valid: boolean;
+    /** 錯誤訊息列表 (阻塞性問題) */
+    errors: string[];
+    /** 警告訊息列表 (非阻塞性問題) */
+    warnings: string[];
+}
+/**
+ * 依賴驗證器
+ *
+ * 負責驗證 Profile 配置的依賴完整性，包括：
+ * - Driver 必需的 packages
+ * - Feature 之間的衝突
+ * - Feature 的依賴關係
+ *
+ * @example
+ * ```typescript
+ * const validator = new DependencyValidator()
+ * const result = validator.validate(profileConfig, packageJson)
+ *
+ * if (!result.valid) {
+ *   console.error('依賴驗證失敗:', result.errors)
+ * }
+ * ```
+ *
+ * @since 3.1.0
+ * @public
+ */
+declare class DependencyValidator {
+    /**
+     * Driver 到 Package 的映射規則
+     */
+    private static readonly DRIVER_DEPENDENCIES;
+    /**
+     * Feature 衝突規則
+     */
+    private static readonly CONFLICTS;
+    /**
+     * Feature 依賴映射
+     */
+    private static readonly FEATURE_DEPENDENCIES;
+    /**
+     * 驗證 Profile 配置
+     *
+     * @param config - Profile 配置
+     * @param packageJson - 專案的 package.json 內容
+     * @returns 驗證結果
+     */
+    validate(config: ProfileConfig, packageJson: PackageJson): ValidationResult;
+    /**
+     * 驗證 driver 依賴
+     */
+    private validateDriverDependencies;
+    /**
+     * 驗證 feature 衝突
+     */
+    private validateFeatureConflicts;
+    /**
+     * 驗證 feature 依賴
+     */
+    private validateFeatureDependencies;
+    /**
+     * 檢查 package.json 是否包含指定 package
+     */
+    private hasPackage;
+    /**
+     * 建議安裝缺失的依賴
+     *
+     * @param result - 驗證結果
+     * @returns 安裝命令建議
+     */
+    static suggestInstallCommand(result: ValidationResult): string | null;
+}
+
+/**
+ * Represents the results of an environment detection scan.
+ *
+ * @public
+ * @since 3.0.0
+ */
+interface DetectedEnvironment {
+    /** The detected cloud or hosting platform. */
+    platform: 'aws' | 'gcp' | 'azure' | 'k8s' | 'vercel' | 'netlify' | 'unknown';
+    /** The project profile most suitable for this environment. */
+    suggestedProfile: ProfileType;
+    /** The degree of certainty in the detection. */
+    confidence: 'high' | 'medium' | 'low';
+    /** The reason or heuristic used for the detection. */
+    reason: string;
+}
+/**
+ * EnvironmentDetector inspects environment variables to identify the hosting platform.
+ *
+ * It uses these heuristics to suggest the most appropriate project profile
+ * (Core, Scale, or Enterprise) for the current environment.
+ *
+ * @public
+ * @since 3.0.0
+ */
+declare class EnvironmentDetector {
+    detect(): DetectedEnvironment;
+}
+
+/**
+ * FileMerger handles the intelligent merging of file contents during scaffolding.
+ *
+ * It understands different file formats (JSON, ENV) and applies appropriate
+ * merging strategies instead of simple overwriting.
+ *
+ * @public
+ * @since 3.0.0
+ */
+declare class FileMerger {
+    /**
+     * Merge content of two files based on their type.
+     */
+    merge(fileName: string, baseContent: string, overlayContent: string): string;
+    private mergeJson;
+    private mergeEnv;
+}
+
+/**
+ * Architecture patterns supported by the scaffolding engine.
+ *
+ * @public
+ * @since 3.0.0
+ */
+type ArchitectureType = 'enterprise-mvc' | 'clean' | 'ddd' | 'satellite' | 'action-domain' | 'standalone-engine';
+/**
+ * Configuration options for creating a new project via Scaffold.
+ *
+ * @public
+ * @since 3.0.0
+ */
+interface ScaffoldOptions {
+    /** The name of the new project (e.g., 'my-api'). */
+    name: string;
+    /** Absolute path where the project files should be generated. */
+    targetDir: string;
+    /** The primary architectural pattern to apply. */
+    architecture: ArchitectureType;
+    /** For DDD architecture: the module template type. @default 'simple' */
+    dddModuleType?: 'simple' | 'advanced' | 'cqrs-query';
+    /** Preferred package manager for dependency installation. @default 'bun' */
+    packageManager?: 'bun' | 'npm' | 'yarn' | 'pnpm';
+    /** Whether to run `git init` in the target directory. @default true */
+    initGit?: boolean;
+    /** Whether to automatically run `install` after file generation. @default true */
+    installDeps?: boolean;
+    /** If true, includes the Spectrum observability dashboard in the scaffolded app. */
+    withSpectrum?: boolean;
+    /** Internal flag for official Gravito satellite projects. */
+    isInternal?: boolean;
+    /** Selected project profile determining the set of included orbits/packages. */
+    profile?: 'core' | 'scale' | 'enterprise';
+    /** List of additional feature orbits to include (e.g., 'redis', 'queue', 'otel'). */
+    features?: string[];
+    /** Additional template variables to be used during file generation. */
+    context?: Record<string, unknown>;
+}
+/**
+ * The outcome of a scaffolding operation.
+ *
+ * @public
+ * @since 3.0.0
+ */
+interface ScaffoldResult {
+    /** True if the operation completed without fatal errors. */
+    success: boolean;
+    /** The absolute path where the project was created. */
+    targetDir: string;
+    /** List of relative file paths that were successfully generated. */
+    filesCreated: string[];
+    /** Any non-fatal error messages encountered during generation. */
+    errors?: string[];
+}
+/**
+ * Represents a node in the project file structure blueprint.
+ *
+ * Used to define the skeleton of a new project before generation.
+ *
+ * @public
+ * @since 3.0.0
+ */
+interface DirectoryNode {
+    /** The type of node (file vs folder). */
+    type: 'file' | 'directory';
+    /** The name of the file or directory. */
+    name: string;
+    /** Literal string content if this is a file node. */
+    content?: string;
+    /** The name or path of a template to use for this file's content. */
+    template?: string;
+    /** Nested nodes if this is a directory. */
+    children?: DirectoryNode[];
+}
+
+declare class TemplateManager {
+    private stubGenerator;
+    constructor(templatesDir: string);
+    render(template: string, context: Record<string, unknown>): string;
+    applyOverlay(sourceDir: string, targetDir: string, context: Record<string, unknown>, fileMerger: FileMerger, log?: (msg: string) => void): Promise<string[]>;
+}
+
+/**
+ * BaseGenerator - Abstract base class for architecture generators.
+ */
+
+interface GeneratorContext {
+    name: string;
+    namePascalCase: string;
+    nameCamelCase: string;
+    nameSnakeCase: string;
+    nameKebabCase: string;
+    targetDir: string;
+    architecture: ArchitectureType;
+    packageManager: 'bun' | 'npm' | 'yarn' | 'pnpm';
+    year: string;
+    date: string;
+    [key: string]: unknown;
+}
+interface GeneratorConfig {
+    templatesDir: string;
+    verbose?: boolean;
+}
+declare abstract class BaseGenerator {
+    protected config: GeneratorConfig;
+    protected templateManager: TemplateManager;
+    protected fileMerger: FileMerger;
+    protected filesCreated: string[];
+    protected context: GeneratorContext | null;
+    constructor(config: GeneratorConfig);
+    abstract get architectureType(): ArchitectureType;
+    abstract get displayName(): string;
+    abstract get description(): string;
+    abstract getDirectoryStructure(context: GeneratorContext): DirectoryNode[];
+    generate(context: GeneratorContext): Promise<string[]>;
+    protected createStructure(basePath: string, nodes: DirectoryNode[], context: GeneratorContext): Promise<void>;
+    protected generateCommonFiles(context: GeneratorContext): Promise<void>;
+    protected generateFileFromTemplate(tplDir: string, tplName: string, targetName: string, context: GeneratorContext): Promise<void>;
+    protected generateSkills(context: GeneratorContext): Promise<void>;
+    protected applyOverlays(context: GeneratorContext): Promise<void>;
+    protected applyFeatureOverlays(context: GeneratorContext): Promise<void>;
+    protected copyOverlayDirectory(sourceDir: string, context: GeneratorContext): Promise<void>;
+    protected writeFile(basePath: string, relativePath: string, content: string): Promise<void>;
+    protected generatePackageJson(context: GeneratorContext): string;
+    protected abstract generateArchitectureDoc(context: GeneratorContext): string;
+    protected generateCheckScripts(context: GeneratorContext): Promise<void>;
+    protected log(message: string): void;
+    static createContext(name: string, targetDir: string, architecture: ArchitectureType, packageManager?: 'bun' | 'npm' | 'yarn' | 'pnpm', extra?: Record<string, unknown>): GeneratorContext;
+}
+
+/**
+ * CleanArchitectureGenerator - Clean Architecture Generator
+ *
+ * Generates a structure following Uncle Bob's Clean Architecture:
+ * - Domain: Entities, Value Objects, Interfaces (pure business logic)
+ * - Application: Use Cases, DTOs
+ * - Infrastructure: Database, External Services
+ * - Interface: HTTP Controllers, Presenters
+ */
+
+/**
+ * CleanArchitectureGenerator implements Uncle Bob's Clean Architecture pattern.
+ *
+ * It generates a strictly layered structure including Domain, Application,
+ * Infrastructure, and Interface layers, ensuring business logic is isolated
+ * from framework and external dependencies.
+ *
+ * @public
+ * @since 3.0.0
+ */
+declare class CleanArchitectureGenerator extends BaseGenerator {
+    get architectureType(): "clean";
+    get displayName(): string;
+    get description(): string;
+    getDirectoryStructure(context: GeneratorContext): DirectoryNode[];
+    private generateAppConfig;
+    private generateDatabaseConfig;
+    private generateAuthConfig;
+    private generateCacheConfig;
+    private generateLoggingConfig;
+    private generateUserEntity;
+    private generateEmailValueObject;
+    private generateUserRepositoryInterface;
+    private generateCreateUserUseCase;
+    private generateGetUserUseCase;
+    private generateUserDTO;
+    private generateMailServiceInterface;
+    private generateUserRepository;
+    private generateMailService;
+    private generateAppServiceProvider;
+    private generateRepositoryServiceProvider;
+    private generateProvidersIndex;
+    private generateMiddlewareProvider;
+    private generateRouteProvider;
+    private generateUserController;
+    private generateApiRoutes;
+    private generateUserPresenter;
+    private generateBootstrap;
+    protected generateArchitectureDoc(context: GeneratorContext): string;
+    protected generatePackageJson(context: GeneratorContext): string;
+}
+
+/**
+ * DddGenerator - Domain-Driven Design Architecture Generator
+ *
+ * Generates a DDD structure with:
+ * - Bounded Contexts (e.g., Ordering, Catalog, Identity)
+ * - Shared Kernel for cross-context concerns
+ * - Each context has Domain, Application, Infrastructure, UserInterface layers
+ */
+
+/**
+ * DDD Module Type options
+ * - simple: Basic CRUD structure
+ * - advanced: Complete Event Sourcing with Aggregates, Events, EventStore, and EventApplier
+ * - cqrs-query: CQRS Query Side with Read Models, Event Projectors, Query Services
+ */
+type DddModuleType = 'simple' | 'advanced' | 'cqrs-query';
+/**
+ * DddGenerator implements the full Domain-Driven Design (DDD) architectural pattern.
+ *
+ * It generates a sophisticated structure including Bounded Contexts, Aggregates,
+ * Value Objects, Domain Events, and a Shared Kernel. It is ideal for complex
+ * enterprise applications with rich business logic.
+ *
+ * Supports multiple module templates:
+ * - **simple**: Basic DDD structure with CRUD operations
+ * - **advanced**: Complete Event Sourcing with Aggregate Roots, Domain Events, EventStore
+ * - **cqrs-query**: CQRS read-side with Event Projectors and denormalized Read Models
+ *
+ * @public
+ * @since 3.0.0
+ */
+declare class DddGenerator extends BaseGenerator {
+    private moduleGenerator;
+    private advancedModuleGenerator;
+    private cqrsQueryModuleGenerator;
+    private sharedKernelGenerator;
+    private bootstrapGenerator;
+    private moduleType;
+    constructor(config: GeneratorConfig);
+    /**
+     * Set the module type for generated modules
+     * @param type - 'simple' for basic CRUD, 'advanced' for Event Sourcing, 'cqrs-query' for CQRS Read Side
+     * @default 'simple'
+     */
+    setModuleType(type: DddModuleType): void;
+    get architectureType(): "ddd";
+    get displayName(): string;
+    get description(): string;
+    getDirectoryStructure(context: GeneratorContext): DirectoryNode[];
+    /**
+     * Get the active module generator type
+     */
+    private getModuleGenerator;
+    /**
+     * Override package.json for DDD architecture (uses main.ts instead of bootstrap.ts)
+     */
+    protected generatePackageJson(context: GeneratorContext): string;
+    protected generateArchitectureDoc(context: GeneratorContext): string;
+}
+
+/**
+ * AdvancedModuleGenerator - 進階 DDD 模組生成器（Event Sourcing）
+ *
+ * 為 Bounded Context 生成完整的 Event Sourcing 架構：
+ * - Aggregate Root（聚合根）
+ * - Domain Events（領域事件，支援版本管理）
+ * - Event Store（InMemory + Database 實現）
+ * - EventApplier（純函式事件應用）
+ * - EventDeserializer（事件反序列化）
+ * - 自動化的測試框架
+ *
+ * 使用場景：
+ * ```bash
+ * bun run scaffold Payment --type advanced
+ * # 生成完整的 Payment 模組，包含 Event Sourcing 支援
+ * ```
+ */
+
+declare class AdvancedModuleGenerator {
+    /**
+     * 生成進階 DDD 模組結構（Event Sourcing）
+     *
+     * 生成檔案：
+     * - Domain/AggregateRoots/{Name}.ts
+     * - Domain/Events/{Name}*Event.ts（3 個事件示例）
+     * - Domain/Services/{Name}EventApplier.ts
+     * - Domain/Repositories/I{Name}EventStore.ts
+     * - Domain/ValueObjects/{Name}Status.ts
+     * - Infrastructure/EventStore/InMemory{Name}EventStore.ts
+     * - Infrastructure/EventStore/Database{Name}EventStore.ts
+     * - Infrastructure/EventStore/{Name}EventDeserializer.ts
+     * - Application/Services/Create{Name}Service.ts
+     * - 完整的測試框架
+     */
+    generate(moduleName: string, _context: GeneratorContext): DirectoryNode;
+    private generateAggregateRoot;
+    private generateEvent;
+    private generateStatusValueObject;
+    private generateIdValueObject;
+    private generateEventApplier;
+    private generateEventStoreInterface;
+    private generateInMemoryEventStore;
+    private generateDatabaseEventStore;
+    private generateEventDeserializer;
+    private generateApplicationService;
+    private generateDTO;
+    private generateController;
+    private generateRoutes;
+    private generateModuleIndex;
+    private toKebabCase;
+    private toSnakeCase;
+}
+
+/**
+ * CQRSQueryModuleGenerator - CQRS 查詢側模組生成器
+ *
+ * 為查詢側（讀端）生成完整的 CQRS 架構：
+ * - Read Model（讀模型，查詢優化的數據結構）
+ * - Event Projector（事件投影器，將事件轉化為讀模型）
+ * - Query Service（查詢服務，提供查詢接口）
+ * - Event Subscriber（事件訂閱器，監聽並投影事件）
+ * - HTTP Controllers（查詢端點）
+ *
+ * 與 Phase 2a AdvancedModuleGenerator 配合使用：
+ * - Phase 2a: 寫側（事件溯源）
+ * - Phase 2b: 讀側（CQRS 投影） ← 本生成器
+ *
+ * 使用場景：
+ * ```bash
+ * bun run scaffold WalletBalance --type cqrs-query
+ * # 生成完整的查詢模組，訂閱來自 PSC 模組的事件
+ *
+ * bun run scaffold MemberStats --type cqrs-query
+ * # 生成會員統計查詢模組，訂閱來自 MOC 模組的事件
+ * ```
+ */
+
+interface CQRSQueryConfig {
+    moduleName: string;
+    modulePrefix?: string;
+    description?: string;
+    readModel: {
+        fields: FieldDefinition[];
+        primaryKey: string;
+        indexes?: string[];
+    };
+    events: {
+        subscribedEvents: EventMapping[];
+    };
+    queries?: {
+        methods: QueryMethodDefinition[];
+    };
+    cache?: {
+        enabled: boolean;
+        ttl?: number;
+    };
+}
+interface FieldDefinition {
+    name: string;
+    type: 'string' | 'number' | 'boolean' | 'date' | 'decimal';
+    description?: string;
+    indexed?: boolean;
+}
+interface EventMapping {
+    eventType: string;
+    eventClass: string;
+    handlerMethod: string;
+    updates: FieldUpdate[];
+}
+interface FieldUpdate {
+    fieldName: string;
+    operation: 'set' | 'add' | 'increment';
+}
+interface QueryMethodDefinition {
+    name: string;
+    parameters: QueryParameter[];
+    returnType: string;
+    description?: string;
+}
+interface QueryParameter {
+    name: string;
+    type: string;
+    required?: boolean;
+}
+/**
+ * CQRS 查詢側模組生成器
+ * 生成完整的查詢端（讀側）模組架構
+ */
+declare class CQRSQueryModuleGenerator {
+    /**
+     * 生成 CQRS 查詢側模組結構
+     *
+     * 生成檔案：
+     * - Domain/ReadModels/{Name}ReadModel.ts
+     * - Domain/Projectors/{Name}EventProjector.ts
+     * - Application/Services/Query{Name}Service.ts
+     * - Application/DTOs/{Name}ReadDTO.ts
+     * - Infrastructure/Subscribers/{Name}ProjectionSubscriber.ts
+     * - Infrastructure/Cache/{Name}ReadModelCache.ts
+     * - Presentation/Controllers/{Name}QueryController.ts
+     * - index.ts
+     *
+     * @param moduleName - 模組名稱（例：'Wallet'）
+     * @param _context - 生成器上下文（當前未使用，預留供未來擴展）
+     * @returns 模組目錄結構
+     */
+    generate(moduleName: string, _context: GeneratorContext): DirectoryNode;
+    /**
+     * 生成讀模型檔案
+     */
+    private generateReadModel;
+    /**
+     * 生成事件投影器檔案
+     */
+    private generateProjector;
+    /**
+     * 生成查詢服務檔案
+     */
+    private generateQueryService;
+    /**
+     * 生成查詢 DTO 檔案
+     */
+    private generateQueryDTO;
+    /**
+     * 生成倉庫介面
+     */
+    private generateRepositoryInterface;
+    /**
+     * 生成倉庫實現
+     */
+    private generateRepositoryImplementation;
+    /**
+     * 生成事件訂閱器
+     */
+    private generateSubscriber;
+    /**
+     * 生成快取層
+     */
+    private generateCache;
+    /**
+     * 生成 HTTP 控制器
+     */
+    private generateController;
+    /**
+     * 生成路由檔案
+     */
+    private generateRoutes;
+    /**
+     * 生成模組索引檔案
+     */
+    private generateIndex;
+    /**
+     * 將字符串轉換為 kebab-case
+     */
+    private toKebabCase;
+    /**
+     * 將字符串轉換為 snake_case
+     */
+    private toSnakeCase;
+}
+
+/**
+ * EnterpriseMvcGenerator - Enterprise MVC Architecture Generator
+ *
+ * Generates a Laravel-inspired MVC structure with:
+ * - Controllers for HTTP handling
+ * - Services for business logic
+ * - Repositories for data persistence
+ * - Http/Kernel for middleware management
+ */
+
+/**
+ * EnterpriseMvcGenerator implements a Laravel-inspired MVC architectural pattern.
+ *
+ * It generates a pragmatic, robust structure with Controllers, Services,
+ * Repositories, and Service Providers. It is the recommended architecture
+ * for most web applications and APIs.
+ *
+ * @public
+ * @since 3.0.0
+ */
+declare class EnterpriseMvcGenerator extends BaseGenerator {
+    get architectureType(): "enterprise-mvc";
+    get displayName(): string;
+    get description(): string;
+    getDirectoryStructure(context: GeneratorContext): DirectoryNode[];
+    private generateAppConfig;
+    private generateDatabaseConfig;
+    private generateAuthConfig;
+    private generateCacheConfig;
+    private generateLoggingConfig;
+    private generateHttpKernel;
+    private generateBaseController;
+    private generateHomeController;
+    private generateAuthMiddleware;
+    private generateAppServiceProvider;
+    private generateProvidersIndex;
+    private generateDatabaseProvider;
+    private generateMiddlewareProvider;
+    private generateRouteProvider;
+    private generateExceptionHandler;
+    private generateBootstrap;
+    private generateRoutes;
+    protected generateArchitectureDoc(context: GeneratorContext): string;
+}
+
+/**
+ * SatelliteGenerator - Scaffolds Gravito Satellites (Plugins)
+ *
+ * Implements DDD + Clean Architecture for plugins with built-in
+ * Dogfooding support (pre-configured with Gravito modules).
+ */
+
+/**
+ * SatelliteGenerator scaffolds modular plug-and-play extensions for Gravito.
+ *
+ * It follows a strict DDD and Clean Architecture pattern to ensure that
+ * satellites remain decoupled from the core framework and other satellites.
+ *
+ * @public
+ * @since 3.0.0
+ */
+declare class SatelliteGenerator extends BaseGenerator {
+    get architectureType(): "satellite";
+    get displayName(): string;
+    get description(): string;
+    getDirectoryStructure(context: GeneratorContext): DirectoryNode[];
+    private generateIdValueObject;
+    private generateAggregate;
+    private generateCreatedEvent;
+    private generateRepositoryInterface;
+    private generateUseCase;
+    private generateAtlasRepository;
+    private generateUnitTest;
+    private generateIntegrationTest;
+    private generateController;
+    private generateEntryPoint;
+    private generateManifest;
+    protected generatePackageJson(context: GeneratorContext): string;
+    protected generateArchitectureDoc(context: GeneratorContext): string;
+}
+
+/**
+ * StubGenerator - Abstract template processor for generating code files.
+ *
+ * Provides a flexible system for processing stub templates with Handlebars,
+ * enabling extensible code generation for any file type.
+ *
+ * @example
+ * ```typescript
+ * const generator = new StubGenerator({
+ *   stubsDir: './stubs',
+ *   outputDir: './src',
+ * });
+ *
+ * await generator.generate('controller.stub', 'Controllers/UserController.ts', {
+ *   name: 'User',
+ *   namespace: 'App\\Controllers',
+ * });
+ * ```
+ */
+
+/**
+ * Variables passed to stub templates during processing.
+ *
+ * @public
+ * @since 3.0.0
+ */
+interface StubVariables {
+    [key: string]: unknown;
+}
+/**
+ * Configuration for the `StubGenerator`.
+ *
+ * @public
+ * @since 3.0.0
+ */
+interface StubConfig {
+    /** Directory containing the raw stub templates. */
+    stubsDir: string;
+    /** Root directory for all generated files. */
+    outputDir: string;
+    /** Default variables available to all templates. */
+    defaultVariables?: StubVariables;
+    /** Optional custom Handlebars helper implementations. */
+    helpers?: Record<string, Handlebars.HelperDelegate>;
+}
+/**
+ * StubGenerator processes template stubs using the Handlebars engine.
+ *
+ * It provides a rich set of built-in helpers for string manipulation
+ * (camelCase, PascalCase, etc.) and handles file reading and writing.
+ *
+ * @public
+ * @since 3.0.0
+ */
+declare class StubGenerator {
+    private config;
+    private handlebars;
+    constructor(config: StubConfig);
+    /**
+     * Register built-in Handlebars helpers.
+     */
+    private registerBuiltinHelpers;
+    /**
+     * Generate a file from a stub template.
+     *
+     * @param stubName - Name of the stub file (relative to stubsDir)
+     * @param outputPath - Output path (relative to outputDir)
+     * @param variables - Template variables
+     * @returns Path to the generated file
+     */
+    generate(stubName: string, outputPath: string, variables?: StubVariables): Promise<string>;
+    /**
+     * Generate multiple files from a stub template.
+     *
+     * @param stubName - Name of the stub file
+     * @param outputs - Array of [outputPath, variables] tuples
+     * @returns Array of generated file paths
+     */
+    generateMany(stubName: string, outputs: [string, StubVariables][]): Promise<string[]>;
+    /**
+     * Render a template string directly.
+     *
+     * @param template - Template string
+     * @param variables - Template variables
+     * @returns Rendered content
+     */
+    render(template: string, variables?: StubVariables): string;
+    /**
+     * Register a custom Handlebars helper.
+     *
+     * @param name - Helper name
+     * @param helper - Helper function
+     */
+    registerHelper(name: string, helper: Handlebars.HelperDelegate): void;
+    /**
+     * Register a Handlebars partial.
+     *
+     * @param name - Partial name
+     * @param partial - Partial template string
+     */
+    registerPartial(name: string, partial: string): void;
+}
+
+/**
+ * Represents the structure of a `gravito.lock.json` file.
+ *
+ * @public
+ * @since 3.0.0
+ */
+interface LockFile {
+    /** Information about the selected project profile. */
+    profile: {
+        name: ProfileType;
+        version: string;
+    };
+    /** List of enabled features and orbits. */
+    features: string[];
+    /** Selected default drivers for various services. */
+    drivers: {
+        database: string;
+        cache: string;
+        queue: string;
+        storage: string;
+        session: string;
+    };
+    /** Metadata about the template used for generation. */
+    manifest: {
+        template: string;
+        version: string;
+    };
+    /** ISO timestamp when the project was scaffolded. */
+    createdAt: string;
+}
+/**
+ * LockGenerator creates the `gravito.lock.json` file during scaffolding.
+ *
+ * This file records the architectural choices and feature set of the project,
+ * allowing the CLI to perform consistent upgrades and feature injections later.
+ *
+ * @public
+ * @since 3.0.0
+ */
+declare class LockGenerator {
+    generate(profileName: ProfileType, config: ProfileConfig, templateName?: string, templateVersion?: string): string;
+}
+
+/**
+ * Scaffold is the primary engine for generating Gravito project structures.
+ *
+ * It orchestrates dynamic template generation, architecture patterns,
+ * profile resolution, and environment setup.
+ *
+ * @example
+ * ```typescript
+ * const engine = new Scaffold();
+ * const result = await engine.create({
+ *   name: 'new-app',
+ *   targetDir: '/path/to/app',
+ *   architecture: 'enterprise-mvc'
+ * });
+ * ```
+ *
+ * @public
+ * @since 3.0.0
+ */
+declare class Scaffold {
+    private templatesDir;
+    private verbose;
+    private static readonly packageDir;
+    constructor(options?: {
+        templatesDir?: string;
+        verbose?: boolean;
+    });
+    /**
+     * Returns a list of all architectural patterns supported by the engine,
+     * along with human-readable names and descriptions.
+     *
+     * @returns {Array<{type: ArchitectureType, name: string, description: string}>}
+     */
+    getArchitectureTypes(): Array<{
+        type: ArchitectureType;
+        name: string;
+        description: string;
+    }>;
+    /**
+     * Orchestrates the complete project generation lifecycle.
+     * This includes directory creation, file layout, profile resolution,
+     * dependency mapping, and optional post-install hooks.
+     *
+     * @param {ScaffoldOptions} options - Detailed configuration for the new project.
+     * @returns {Promise<ScaffoldResult>}
+     */
+    create(options: ScaffoldOptions): Promise<ScaffoldResult>;
+    /**
+     * Create a generator for the specified architecture with options.
+     * @param options - Scaffold options including architecture type and module type for DDD
+     */
+    private createGenerator;
+    /**
+     * Generate a single module (for DDD bounded context).
+     */
+    generateModule(_targetDir: string, _moduleName: string, _options?: {
+        architecture?: ArchitectureType;
+    }): Promise<ScaffoldResult>;
+    /**
+     * Generate a service provider.
+     */
+    generateProvider(_targetDir: string, _providerName: string): Promise<ScaffoldResult>;
+}
+
+export { AdvancedModuleGenerator, type ArchitectureType, BaseGenerator, type CQRSQueryConfig, CQRSQueryModuleGenerator, CleanArchitectureGenerator, DddGenerator, type DddModuleType, DependencyValidator, type DetectedEnvironment, EnterpriseMvcGenerator, EnvironmentDetector, FileMerger, type GeneratorConfig, type GeneratorContext, type LockFile, LockGenerator, type PackageJson, type ProfileConfig, ProfileResolver, type ProfileType, SatelliteGenerator, Scaffold, type ScaffoldOptions, type StubConfig, StubGenerator, type StubVariables, type ValidationResult };