@gravito/scaffold 3.0.0 → 3.1.0

package/dist/index.d.cts

@@ -1,7 +1,20 @@
 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;
@@ -9,8 +22,19 @@ interface ProfileConfig {
         storage: string;
         session: string;
     };
+    /** List of enabled features and orbits. */
     features: string[];
 }
+/**
+ * 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;
@@ -25,16 +49,132 @@ declare class ProfileResolver {
     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.
@@ -45,356 +185,130 @@ declare class FileMerger {
 }
 
 /**
- * Architecture types supported by the scaffolding system.
+ * Architecture patterns supported by the scaffolding engine.
+ *
+ * @public
+ * @since 3.0.0
  */
 type ArchitectureType = 'enterprise-mvc' | 'clean' | 'ddd' | 'satellite' | 'action-domain' | 'standalone-engine';
 /**
- * Options for scaffolding a new project.
+ * Configuration options for creating a new project via Scaffold.
+ *
+ * @public
+ * @since 3.0.0
  */
 interface ScaffoldOptions {
-    /**
-     * Project name
-     */
+    /** The name of the new project (e.g., 'my-api'). */
     name: string;
-    /**
-     * Target directory (absolute path)
-     */
+    /** Absolute path where the project files should be generated. */
     targetDir: string;
-    /**
-     * Architecture type
-     */
+    /** The primary architectural pattern to apply. */
     architecture: ArchitectureType;
-    /**
-     * Package manager to use
-     * @default 'bun'
-     */
+    /** Preferred package manager for dependency installation. @default 'bun' */
     packageManager?: 'bun' | 'npm' | 'yarn' | 'pnpm';
-    /**
-     * Whether to initialize git
-     * @default true
-     */
+    /** Whether to run `git init` in the target directory. @default true */
     initGit?: boolean;
-    /**
-     * Whether to install dependencies
-     * @default true
-     */
+    /** Whether to automatically run `install` after file generation. @default true */
     installDeps?: boolean;
-    /**
-     * Whether to include Spectrum debug dashboard
-     * @default false
-     */
+    /** If true, includes the Spectrum observability dashboard in the scaffolded app. */
     withSpectrum?: boolean;
-    /**
-     * Whether this is an internal official satellite
-     * @default false
-     */
+    /** Internal flag for official Gravito satellite projects. */
     isInternal?: boolean;
-    /**
-     * Profile preset (Core, Scale, Enterprise)
-     * @default 'core'
-     */
+    /** Selected project profile determining the set of included orbits/packages. */
     profile?: 'core' | 'scale' | 'enterprise';
-    /**
-     * Feature add-ons (e.g. 'redis', 'queue', 'otel')
-     */
+    /** List of additional feature orbits to include (e.g., 'redis', 'queue', 'otel'). */
     features?: string[];
-    /**
-     * Additional context variables for templates
-     */
+    /** Additional template variables to be used during file generation. */
     context?: Record<string, unknown>;
 }
 /**
- * Result of scaffolding operation.
+ * 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[];
 }
 /**
- * Directory structure node.
+ * 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[];
 }
 
-/**
- * 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.
- */
-interface StubVariables {
-    [key: string]: unknown;
-}
-/**
- * Configuration for StubGenerator.
- */
-interface StubConfig {
-    /**
-     * Directory containing stub templates
-     */
-    stubsDir: string;
-    /**
-     * Output directory for generated files
-     */
-    outputDir: string;
-    /**
-     * Default variables applied to all templates
-     */
-    defaultVariables?: StubVariables;
-    /**
-     * Custom Handlebars helpers
-     */
-    helpers?: Record<string, Handlebars.HelperDelegate>;
-}
-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;
+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.
- *
- * Provides common functionality for generating project structures,
- * including directory creation, file generation, and context management.
  */
 
-/**
- * Context passed to generators during scaffolding.
- */
 interface GeneratorContext {
-    /**
-     * Project name
-     */
     name: string;
-    /**
-     * Project name in various cases
-     */
     namePascalCase: string;
     nameCamelCase: string;
     nameSnakeCase: string;
     nameKebabCase: string;
-    /**
-     * Target directory
-     */
     targetDir: string;
-    /**
-     * Architecture type
-     */
     architecture: ArchitectureType;
-    /**
-     * Package manager
-     */
     packageManager: 'bun' | 'npm' | 'yarn' | 'pnpm';
-    /**
-     * Current year (for license headers)
-     */
     year: string;
-    /**
-     * Current date
-     */
     date: string;
-    /**
-     * Additional custom context
-     */
     [key: string]: unknown;
 }
-/**
- * Configuration for generators.
- */
 interface GeneratorConfig {
-    /**
-     * Directory containing stub templates
-     */
     templatesDir: string;
-    /**
-     * Verbose logging
-     */
     verbose?: boolean;
 }
-/**
- * Abstract base class for architecture generators.
- */
 declare abstract class BaseGenerator {
     protected config: GeneratorConfig;
-    protected stubGenerator: StubGenerator;
+    protected templateManager: TemplateManager;
     protected fileMerger: FileMerger;
     protected filesCreated: string[];
     constructor(config: GeneratorConfig);
-    /**
-     * Get the architecture type this generator handles.
-     */
     abstract get architectureType(): ArchitectureType;
-    /**
-     * Get the display name for this architecture.
-     */
     abstract get displayName(): string;
-    /**
-     * Get the description for this architecture.
-     */
     abstract get description(): string;
-    /**
-     * Get the directory structure for this architecture.
-     */
     abstract getDirectoryStructure(context: GeneratorContext): DirectoryNode[];
-    /**
-     * Generate the project scaffold.
-     *
-     * @param context - Generator context
-     * @returns Array of created file paths
-     */
     generate(context: GeneratorContext): Promise<string[]>;
-    /**
-     * Create directory structure recursively.
-     */
     protected createStructure(basePath: string, nodes: DirectoryNode[], context: GeneratorContext): Promise<void>;
-    /**
-     * Generate common files (package.json, .env, etc.)
-     */
     protected generateCommonFiles(context: GeneratorContext): Promise<void>;
-    /**
-     * Copy AI Skills to the project
-     */
+    protected generateFileFromTemplate(tplDir: string, tplName: string, targetName: string, context: GeneratorContext): Promise<void>;
     protected generateSkills(context: GeneratorContext): Promise<void>;
-    /**
-     * Apply profile-specific overlays
-     */
     protected applyOverlays(context: GeneratorContext): Promise<void>;
-    /**
-     * Apply feature-specific overlays
-     */
     protected applyFeatureOverlays(context: GeneratorContext): Promise<void>;
-    /**
-     * Helper to copy/merge an overlay directory into the target
-     */
     protected copyOverlayDirectory(sourceDir: string, context: GeneratorContext): Promise<void>;
-    /**
-     * Write a file and track it.
-     */
     protected writeFile(basePath: string, relativePath: string, content: string): Promise<void>;
-    /**
-     * Generate package.json content.
-     */
     protected generatePackageJson(context: GeneratorContext): string;
-    /**
-     * Generate Dockerfile content.
-     */
-    protected generateDockerfile(context: GeneratorContext): string;
-    /**
-     * Generate .dockerignore content.
-     */
-    protected generateDockerIgnore(): string;
-    /**
-     * Generate .env.example content.
-     */
-    protected generateEnvExample(context: GeneratorContext): string;
-    /**
-     * Generate .gitignore content.
-     */
-    protected generateGitignore(): string;
-    /**
-     * Generate tsconfig.json content.
-     */
-    protected generateTsConfig(): string;
-    /**
-     * Generate ARCHITECTURE.md content.
-     * Override in subclasses for architecture-specific docs.
-     */
     protected abstract generateArchitectureDoc(context: GeneratorContext): string;
-    /**
-     * Generate check scripts for project validation.
-     */
     protected generateCheckScripts(context: GeneratorContext): Promise<void>;
-    /**
-     * Generate check-dependencies.ts script content.
-     */
-    protected generateCheckDependenciesScript(): string;
-    /**
-     * Generate check.sh script content.
-     */
-    protected generateCheckShellScript(): string;
-    /**
-     * Generate pre-commit.sh script content.
-     */
-    protected generatePreCommitScript(): string;
-    /**
-     * Generate CHECK_SYSTEM.md documentation.
-     */
-    protected generateCheckSystemDoc(context: GeneratorContext): string;
-    /**
-     * Log a message if verbose mode is enabled.
-     */
     protected log(message: string): void;
-    /**
-     * Create generator context from options.
-     */
     static createContext(name: string, targetDir: string, architecture: ArchitectureType, packageManager?: 'bun' | 'npm' | 'yarn' | 'pnpm', extra?: Record<string, unknown>): GeneratorContext;
 }
 
@@ -408,6 +322,16 @@ declare abstract class BaseGenerator {
  * - 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;
@@ -449,44 +373,29 @@ declare class CleanArchitectureGenerator extends BaseGenerator {
  * - Each context has Domain, Application, Infrastructure, UserInterface layers
  */
 
+/**
+ * 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.
+ *
+ * @public
+ * @since 3.0.0
+ */
 declare class DddGenerator extends BaseGenerator {
+    private moduleGenerator;
+    private sharedKernelGenerator;
+    private bootstrapGenerator;
+    constructor(config: GeneratorConfig);
     get architectureType(): "ddd";
     get displayName(): string;
     get description(): string;
     getDirectoryStructure(context: GeneratorContext): DirectoryNode[];
-    private generateBootstrapDirectory;
-    private generateShared;
-    private generateModule;
-    private generateBootstrapApp;
-    private generateProvidersRegistry;
-    private generateEventsRegistry;
-    private generateRoutesRegistry;
-    private generateMainEntry;
-    private generateModulesConfig;
-    private generateModuleServiceProvider;
     /**
      * Override package.json for DDD architecture (uses main.ts instead of bootstrap.ts)
      */
     protected generatePackageJson(context: GeneratorContext): string;
-    private generateAppConfig;
-    private generateDatabaseConfig;
-    private generateCacheConfig;
-    private generateLoggingConfig;
-    private generateIdValueObject;
-    private generateMoneyValueObject;
-    private generateEmailValueObject;
-    private generateEventDispatcher;
-    private generateAggregate;
-    private generateAggregateStatus;
-    private generateCreatedEvent;
-    private generateRepositoryInterface;
-    private generateCommand;
-    private generateCommandHandler;
-    private generateQuery;
-    private generateQueryHandler;
-    private generateDTO;
-    private generateRepository;
-    private generateExceptionHandler;
     protected generateArchitectureDoc(context: GeneratorContext): string;
 }
 
@@ -500,6 +409,16 @@ declare class DddGenerator extends BaseGenerator {
  * - 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;
@@ -515,7 +434,6 @@ declare class EnterpriseMvcGenerator extends BaseGenerator {
     private generateHomeController;
     private generateAuthMiddleware;
     private generateAppServiceProvider;
-    private generateRouteServiceProvider;
     private generateProvidersIndex;
     private generateDatabaseProvider;
     private generateMiddlewareProvider;
@@ -533,6 +451,15 @@ declare class EnterpriseMvcGenerator extends BaseGenerator {
  * 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;
@@ -548,12 +475,124 @@ declare class SatelliteGenerator extends BaseGenerator {
     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;
@@ -561,23 +600,46 @@ interface LockFile {
         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 - Main API for project scaffolding
+ * Scaffold is the primary engine for generating Gravito project structures.
+ *
+ * It orchestrates dynamic template generation, architecture patterns,
+ * profile resolution, and environment setup.
  *
- * Provides a unified interface for generating project structures
- * with different architectural patterns.
+ * @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;
@@ -586,7 +648,10 @@ declare class Scaffold {
         verbose?: boolean;
     });
     /**
-     * Get all available architecture types.
+     * 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;
@@ -594,7 +659,12 @@ declare class Scaffold {
         description: string;
     }>;
     /**
-     * Create a new project scaffold.
+     * 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>;
     /**
@@ -613,4 +683,4 @@ declare class Scaffold {
     generateProvider(_targetDir: string, _providerName: string): Promise<ScaffoldResult>;
 }
 
-export { type ArchitectureType, BaseGenerator, CleanArchitectureGenerator, DddGenerator, type DetectedEnvironment, EnterpriseMvcGenerator, EnvironmentDetector, FileMerger, type GeneratorConfig, type GeneratorContext, type LockFile, LockGenerator, type ProfileConfig, ProfileResolver, type ProfileType, SatelliteGenerator, Scaffold, type ScaffoldOptions, type StubConfig, StubGenerator, type StubVariables };
+export { type ArchitectureType, BaseGenerator, CleanArchitectureGenerator, DddGenerator, 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 };