@gravito/scaffold 3.2.0 → 4.1.0

package/package.json

@@ -1,6 +1,7 @@
 {
   "name": "@gravito/scaffold",
-  "version": "3.2.0",
+  "sideEffects": false,
+  "version": "4.1.0",
   "description": "Project scaffolding engine for Gravito - Generate enterprise-grade architecture templates",
   "type": "module",
   "main": "dist/index.js",
@@ -15,6 +16,7 @@
   },
   "scripts": {
     "build": "bun run build.ts",
+    "build:dts": "bun run build.ts --dts-only",
     "dev": "bun run --watch src/index.ts",
     "test": "bun test --timeout=10000",
     "typecheck": "bun tsc -p tsconfig.json --noEmit --skipLibCheck",
@@ -35,12 +37,13 @@
     "handlebars": "^4.7.8"
   },
   "devDependencies": {
+    "@gravito/core": "workspace:*",
     "tsup": "^8.5.1",
     "typescript": "^5.9.3",
     "bun-types": "latest"
   },
   "peerDependencies": {
-    "@gravito/core": "^1.6.1"
+    "@gravito/core": "^2.0.0"
   },
   "author": "Carl Lee <carllee0520@gmail.com>",
   "license": "MIT",

package/dist/index.d.cts

@@ -1,686 +0,0 @@
-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[];
-}
-/**
- * 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;
-    /** 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[];
-    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
- */
-
-/**
- * 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[];
-    /**
-     * Override package.json for DDD architecture (uses main.ts instead of bootstrap.ts)
-     */
-    protected generatePackageJson(context: GeneratorContext): string;
-    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
- */
-
-/**
- * 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 generateEntity;
-    private generateRepositoryInterface;
-    private generateUseCase;
-    private generateAtlasRepository;
-    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;
-    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.
-     */
-    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, 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 };