@gravito/scaffold 3.0.0 → 3.0.1

package/dist/index.d.ts

@@ -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,44 @@ declare class ProfileResolver {
     isValidFeature(feature: string): boolean;
 }
 
+/**
+ * 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 +97,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 +234,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 +285,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 +321,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 +346,6 @@ declare class EnterpriseMvcGenerator extends BaseGenerator {
     private generateHomeController;
     private generateAuthMiddleware;
     private generateAppServiceProvider;
-    private generateRouteServiceProvider;
     private generateProvidersIndex;
     private generateDatabaseProvider;
     private generateMiddlewareProvider;
@@ -533,6 +363,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 +387,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 +512,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.
+ *
+ * @example
+ * ```typescript
+ * const engine = new Scaffold();
+ * const result = await engine.create({
+ *   name: 'new-app',
+ *   targetDir: '/path/to/app',
+ *   architecture: 'enterprise-mvc'
+ * });
+ * ```
  *
- * Provides a unified interface for generating project structures
- * with different architectural patterns.
+ * @public
+ * @since 3.0.0
  */
-
 declare class Scaffold {
     private templatesDir;
     private verbose;
@@ -586,7 +560,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 +571,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>;
     /**