@gravito/scaffold 1.0.0-beta.1

package/dist/index.d.cts

@@ -0,0 +1,462 @@
+import Handlebars from 'handlebars';
+
+/**
+ * Architecture types supported by the scaffolding system.
+ */
+type ArchitectureType = 'enterprise-mvc' | 'clean' | 'ddd';
+/**
+ * Options for scaffolding a new project.
+ */
+interface ScaffoldOptions {
+    /**
+     * Project name
+     */
+    name: string;
+    /**
+     * Target directory (absolute path)
+     */
+    targetDir: string;
+    /**
+     * Architecture type
+     */
+    architecture: ArchitectureType;
+    /**
+     * Package manager to use
+     * @default 'bun'
+     */
+    packageManager?: 'bun' | 'npm' | 'yarn' | 'pnpm';
+    /**
+     * Whether to initialize git
+     * @default true
+     */
+    initGit?: boolean;
+    /**
+     * Whether to install dependencies
+     * @default true
+     */
+    installDeps?: boolean;
+    /**
+     * Additional context variables for templates
+     */
+    context?: Record<string, unknown>;
+}
+/**
+ * Result of scaffolding operation.
+ */
+interface ScaffoldResult {
+    success: boolean;
+    targetDir: string;
+    filesCreated: string[];
+    errors?: string[];
+}
+/**
+ * Directory structure node.
+ */
+interface DirectoryNode {
+    type: 'file' | 'directory';
+    name: string;
+    content?: string;
+    template?: string;
+    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;
+}
+
+/**
+ * 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 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>;
+    /**
+     * 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 .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;
+    /**
+     * 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;
+}
+
+/**
+ * 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
+ */
+
+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 generateBaseEntity;
+    private generateUserEntity;
+    private generateBaseValueObject;
+    private generateEmailValueObject;
+    private generateUserRepositoryInterface;
+    private generateDomainException;
+    private generateCreateUserUseCase;
+    private generateGetUserUseCase;
+    private generateUserDTO;
+    private generateMailServiceInterface;
+    private generateUserRepository;
+    private generateMailService;
+    private generateAppServiceProvider;
+    private generateRepositoryServiceProvider;
+    private generateUserController;
+    private generateApiRoutes;
+    private generateUserPresenter;
+    private generateBootstrap;
+    protected generateArchitectureDoc(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
+ */
+
+declare class DddGenerator extends BaseGenerator {
+    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 generateDomainEvent;
+    private generateAggregateRoot;
+    private generateEntity;
+    private generateValueObject;
+    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;
+}
+
+/**
+ * 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
+ */
+
+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 generateRouteServiceProvider;
+    private generateExceptionHandler;
+    private generateBootstrap;
+    private generateRoutes;
+    protected generateArchitectureDoc(context: GeneratorContext): string;
+}
+
+/**
+ * Scaffold - Main API for project scaffolding
+ *
+ * Provides a unified interface for generating project structures
+ * with different architectural patterns.
+ */
+
+declare class Scaffold {
+    private templatesDir;
+    private verbose;
+    constructor(options?: {
+        templatesDir?: string;
+        verbose?: boolean;
+    });
+    /**
+     * Get all available architecture types.
+     */
+    getArchitectureTypes(): Array<{
+        type: ArchitectureType;
+        name: string;
+        description: string;
+    }>;
+    /**
+     * Create a new project scaffold.
+     */
+    create(options: ScaffoldOptions): Promise<ScaffoldResult>;
+    /**
+     * Create a generator for the specified architecture.
+     */
+    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 { type ArchitectureType, BaseGenerator, CleanArchitectureGenerator, DddGenerator, EnterpriseMvcGenerator, type GeneratorConfig, type GeneratorContext, Scaffold, type ScaffoldOptions, type StubConfig, StubGenerator, type StubVariables };