archforge-x 1.0.3 → 1.0.4

package/README.md

@@ -1,90 +1,190 @@
-# 🛡️ ArchForge X
+# ArchForge X
 
-**Enterprise Architecture Engine** for scaffolding, analyzing, and visualizing software architecture.
+A configuration-driven architecture engine for generating and enforcing production-grade project structures across multiple languages and frameworks.
 
-ArchForge X helps development teams maintain clean, consistent, and scalable codebases by enforcing architectural boundaries and providing intelligent scaffolding.
+## Why This Exists
 
-## 🚀 Features
+Modern software development often suffers from two primary issues: **setup fatigue** and **architecture drift**. Developers spend hours configuring boilerplate for logging, caching, and database layers, only for the project's architectural boundaries to erode over time as the team grows.
 
-- **🏗️ Intelligent Scaffolding**: Generate project structures for TypeScript, JavaScript, Python, and Go using patterns like Clean Architecture, DDD, and Hexagonal Architecture.
-- **🔍 Dependency Analysis**: Detect architectural violations and circular dependencies between layers.
-- **📊 Visual Graphs**: Generate high-resolution SVG dependency graphs to visualize your architecture.
-- **🛡️ Rule Enforcement**: Define custom architectural rules in `archforge.yaml` to ensure your team follows the intended design.
-- **✨ Interactive CLI**: A user-friendly wizard to get you started in seconds.
+ArchForge X solves this by moving architecture from "documentation" to "executable configuration." By defining your project's structure and rules in a central `archforge.yaml`, you ensure that every project starts with production-ready defaults and stays compliant throughout its lifecycle.
 
-## 📦 Installation
+## Key Features
+
+- **Config-Driven Generation**: Generate entire project skeletons from a single YAML definition.
+- **Architecture Enforcement**: Automatically validate naming conventions and import boundaries.
+- **Production-Ready Defaults**: Built-in support for structured logging, health checks, and global error handling.
+- **Multi-Stack Support**: Consistent patterns across Node.js, Python, and Go.
+- **Zero-Drift Sync**: Re-apply architectural rules to existing projects without losing custom logic.
+
+## Supported Capabilities
+
+- **Architectures**: Clean Architecture (DDD), Layered Architecture, MVC.
+- **Frameworks**: NestJS, Express, FastAPI, Django, Go Gin, Next.js.
+- **ORMs & Databases**: Prisma, SQLAlchemy, GORM, PostgreSQL, MySQL, SQLite, MongoDB.
+- **DevOps**: Automated Dockerfile and Docker Compose generation, GitHub Actions CI/CD workflows.
+
+## Installation
+
+Install ArchForge X globally via npm:
 
 ```bash
-npm install -g archforge-x
+npm install -g archforge
 ```
 
-## 🛠️ Usage
+## CLI Commands
+
+### init
+
+The `init` command starts an interactive wizard to bootstrap a new project.
 
-### 1. Initialize a Project
-Create a new architecture configuration file:
 ```bash
 archforge init
 ```
 
-### 2. Interactive Wizard (Recommended)
-Scaffold a new project with a guided setup:
+During initialization, you will select:
+- **Architecture Style**: Choose between Clean, Layered, or MVC.
+- **Framework**: Select your preferred backend or frontend framework.
+- **ORM & Database**: Configure your data persistence layer.
+- **Optional Modules**: Add Docker support, CI/CD workflows, Caching (Redis), and more.
+
+### sync
+
+The `sync` command re-applies the architectural rules defined in `archforge.yaml` to your project.
+
 ```bash
-archforge interactive
+archforge sync
 ```
 
-### 3. Analyze Dependencies
-Check your project for architectural violations:
+- **What it changes**: Updates configuration files, architecture guardrails (e.g., ESLint rules), and missing infrastructure layers.
+- **What it never changes**: Your business logic, use cases, or custom implementation files.
+
+### validate
+
+The `validate` command checks your project against the rules defined in `archforge.yaml`.
+
 ```bash
-archforge analyze
+archforge validate
 ```
 
-### 4. Visualize Architecture
-Generate an SVG graph of your project's layers:
+- **Validation**: Checks naming conventions, directory structure, and restricted import paths.
+- **Usage**: Used locally during development or in CI pipelines to prevent architectural violations.
+- **Behavior**: Returns a non-zero exit code on failure, making it ideal for blocking invalid PRs.
+
+### upgrade
+
+The `upgrade` command adds new production-grade features to an existing ArchForge project.
+
 ```bash
-archforge visualize -o architecture.svg
+archforge upgrade
 ```
 
-### 5. Deep Audit
-Get intelligent fix suggestions based on architectural principles:
+- **Purpose**: Safely introduces enhancements like new logging providers or health check endpoints without breaking existing code.
+
+### generate
+
+The `generate` command creates specific architectural components within an existing project.
+
 ```bash
-archforge audit
+archforge generate module user
 ```
 
-## ⚙️ Configuration (`archforge.yaml`)
+- **Usage**: Use this to quickly add new features, layers, or modules that follow the project's established patterns.
+- **Alias**: `create`
+
+### graph
 
-Define your layers and dependency rules:
+The `graph` command generates a visual representation of your project's architecture.
+
+```bash
+archforge graph
+```
+
+- **Output**: Generates an `architecture-graph.svg` file showing the relationships and dependencies between your project's layers.
+- **Alias**: `visualize`
+
+## Configuration (archforge.yaml)
+
+The `archforge.yaml` file is the single source of truth for your project's architecture. It defines the structure, naming conventions, and enforcement policies.
 
 ```yaml
-version: "1.0"
-name: "My Project Architecture"
-project:
-  name: "my-app"
-  root: "."
-
-metadata:
-  type: "clean"
-  language: "ts"
-  framework: "express"
-
-layers:
-  - name: "domain"
-    path: "src/domain"
-    description: "Core business logic"
-    forbiddenImports: ["infrastructure", "application"]
-
-  - name: "application"
-    path: "src/application"
-    allowedImports: ["domain"]
-
-  - name: "infrastructure"
-    path: "src/infrastructure"
-    allowedImports: ["domain", "application"]
+name: my-production-app
+architecture: clean
+framework: nestjs
+orm: prisma
+database: postgresql
+
+structure:
+  layers:
+    - name: domain
+      path: src/domain
+      canImport: []
+    - name: application
+      path: src/application
+      canImport: [domain]
+    - name: infrastructure
+      path: src/infrastructure
+      canImport: [domain, application]
+    - name: presentation
+      path: src/presentation
+      canImport: [domain, application]
+
+naming:
+  controllers: "{name}.controller.ts"
+  useCases: "{name}.use-case.ts"
+  repositories: "{name}.repository.ts"
+
+enforcement:
+  strictImports: true
+  namingConvention: pascalCase
 ```
 
-## 🤝 Contributing
+## Rule Enforcement & Verification
+
+ArchForge X enforces rules through a combination of static analysis and framework-specific configurations:
+
+1. **Local Enforcement**: During `sync`, ArchForge configures tools like ESLint with `import/no-restricted-paths` to provide real-time feedback in your IDE.
+2. **CI Verification**: Running `archforge validate` in your CI pipeline ensures that no code violating the architecture is merged.
+3. **Fixing Violations**: If a violation is detected (e.g., a Domain entity importing from Infrastructure), the CLI will provide a detailed report pointing to the offending file and rule.
+
+## Running the Project
+
+### Local Development
+
+```bash
+# Install dependencies
+npm install
+
+# Start in development mode with hot-reload
+npm run start:dev
+```
+
+### Docker-Based Development
+
+```bash
+# Build and start all services (App, Database, Redis)
+docker-compose up --build
+```
+
+### Environment Variables
+
+ArchForge generates a `.env.example` file. Copy it to `.env` and configure your secrets:
+- `PORT`: Server port (default: 3000)
+- `DATABASE_URL`: Connection string for your database.
+- `REDIS_URL`: Connection string for Redis caching.
+
+## Team & Company Usage
+
+ArchForge X is designed for engineering organizations to:
+- **Standardize**: Ensure every microservice or project follows the same structural patterns.
+- **Onboard**: New developers can navigate any project instantly because the structure is predictable.
+- **Scale**: Enforce best practices across hundreds of repositories without manual code reviews for "folder structure."
+
+## Design Philosophy
 
-Contributions are welcome! Please feel free to submit a Pull Request.
+- **Enforcement over Documentation**: Rules that aren't enforced will eventually be broken.
+- **Production-Ready by Default**: Every project starts with the scaffolding needed for a real-world deployment.
+- **Config-Driven Flexibility**: The tool adapts to your team's preferred patterns, not the other way around.
 
-## 📄 License
+## Contributing & License
 
-This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
+ArchForge X is open-source software licensed under the MIT License. Contributions are welcome via GitHub Pull Requests.

package/dist/generators/node/nestjs.js

@@ -53,7 +53,7 @@ class NestJSGenerator extends base_1.BaseGenerator {
                 "pino-http": "^8.3.3",
                 "zod": "^3.22.2",
                 "ioredis": "^5.3.2",
-                "class-validator": "^0.14.0",
+                "class-validator": "^0.14.3",
                 "class-transformer": "^0.5.1",
                 ...(options.orm === "prisma" ? { "@prisma/client": "^5.0.0" } : {})
             },

package/dist/index.js

@@ -6,7 +6,6 @@ Object.defineProperty(exports, "__esModule", { value: true });
 const commander_1 = require("commander");
 const chalk_1 = __importDefault(require("chalk"));
 const fs_1 = __importDefault(require("fs"));
-const init_1 = require("./cli/init");
 const interactive_1 = require("./cli/interactive");
 const sync_1 = require("./cli/commands/sync");
 const parser_1 = require("./core/architecture/parser");
@@ -27,16 +26,22 @@ const loadConfig = (configPath) => {
     return (0, parser_1.loadArchitecture)(configPath);
 };
 // --- COMMANDS ---
-program.addCommand(init_1.initCommand);
+program
+    .command("init")
+    .description("Initialize a new project with interactive wizard (Recommended)")
+    .action(async () => {
+    await (0, interactive_1.interactiveCLI)();
+});
 program
     .command("sync")
-    .description("Sync architecture with archforge.yaml and validate structure")
+    .description("Synchronize architecture with archforge.yaml and validate structure")
     .action(async () => {
     await (0, sync_1.syncCommand)();
 });
 program
     .command("generate")
-    .description("Scaffold a project based on architecture definition")
+    .alias("create")
+    .description("Scaffold a project or module based on architecture definition")
     .option("-c, --config <path>", "Path to yaml config", "archforge.yaml")
     .option("-m, --mode <mode>", "Generation mode: 'standard' or 'professional'", "professional")
     .action(async (options) => {
@@ -60,14 +65,15 @@ program
     }
 });
 program
-    .command("analyze")
-    .description("Static analysis of dependency graph against rules")
+    .command("validate")
+    .alias("check")
+    .description("Validate project structure and dependencies against rules")
     .option("-c, --config <path>", "Path to yaml config", "archforge.yaml")
     .option("--ignore-tests", "Exclude test files from analysis")
     .option("-o, --output <file>", "Export report to JSON/Markdown")
     .action((options) => {
     try {
-        console.log(chalk_1.default.cyan("🔍 Analyzing Dependencies..."));
+        console.log(chalk_1.default.cyan("🔍 Validating Architecture..."));
         const arch = loadConfig(options.config);
         const violations = (0, dependency_1.analyzeDependencies)(arch, {
             ignoreTests: options.ignoreTests,
@@ -78,13 +84,13 @@ program
             process.exit(1);
     }
     catch (err) {
-        console.error(chalk_1.default.red.bold("\n❌ Analysis Error:"), err.message);
+        console.error(chalk_1.default.red.bold("\n❌ Validation Error:"), err.message);
         process.exit(1);
     }
 });
 program
     .command("audit")
-    .description("Deep architectural audit with auto-fix suggestions")
+    .description("Perform a deep architectural audit with auto-fix suggestions")
     .option("-c, --config <path>", "Path to yaml config", "archforge.yaml")
     .option("-o, --output <file>", "Export audit results")
     .action((options) => {
@@ -100,8 +106,9 @@ program
     }
 });
 program
-    .command("visualize")
-    .description("Generate visual dependency graph (SVG)")
+    .command("graph")
+    .alias("visualize")
+    .description("Generate a visual dependency graph (SVG)")
     .option("-c, --config <path>", "Path to yaml config", "archforge.yaml")
     .option("-o, --output <file>", "Output file path", "architecture-graph.svg")
     .action(async (options) => {
@@ -115,10 +122,8 @@ program
         console.error(chalk_1.default.red.bold("\n❌ Visualization Error:"), err.message);
     }
 });
-program
-    .command("interactive", { isDefault: true })
-    .description("Interactive Wizard (Recommended)")
-    .action(async () => {
+// Set default command to init
+program.action(async () => {
     await (0, interactive_1.interactiveCLI)();
 });
 program.parse(process.argv);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "archforge-x",
-  "version": "1.0.3",
+  "version": "1.0.4",
   "description": "Enterprise Architecture Engine for scaffolding, analyzing, and visualizing software architecture.",
   "main": "dist/index.js",
   "bin": {

package/dist/cli/init.js

@@ -1,74 +0,0 @@
-"use strict";
-var __importDefault = (this && this.__importDefault) || function (mod) {
-    return (mod && mod.__esModule) ? mod : { "default": mod };
-};
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.initCommand = void 0;
-const commander_1 = require("commander");
-const fs_1 = __importDefault(require("fs"));
-const chalk_1 = __importDefault(require("chalk"));
-const path_1 = __importDefault(require("path"));
-exports.initCommand = new commander_1.Command("init")
-    .description("Initialize a new architecture configuration file (archforge.yaml)")
-    .action(() => {
-    const configPath = path_1.default.resolve(process.cwd(), "archforge.yaml");
-    // 1. Safety Check: Don't overwrite existing config
-    if (fs_1.default.existsSync(configPath)) {
-        console.log(chalk_1.default.yellow("⚠️  Configuration file 'archforge.yaml' already exists."));
-        console.log(chalk_1.default.gray(`   Path: ${configPath}`));
-        console.log(chalk_1.default.blue("   Run 'archforge analyze' or 'archforge generate' to use it."));
-        return;
-    }
-    const template = `
-version: "1.0"
-name: "Enterprise Architecture Config"
-project:
-  name: "my-awesome-project"
-  root: "."
-
-metadata:
-  type: "clean"        # Options: clean, ddd, hexagonal, layered
-  language: "ts"       # Options: ts, js, py, go
-  framework: "nestjs"  # Options: nestjs, express, django, flask, gin
-  version: "1.0.0"
-  modules:             # Optional modules to scaffold
-    - "auth"
-    - "docker"
-
-# Define your architecture layers and dependency rules here
-layers:
-  - name: "domain"
-    path: "src/domain"
-    description: "Core business logic and entities (Enterprise Rules)"
-    strict: true
-    forbiddenImports: ["infrastructure", "interface", "application"]
-
-  - name: "application"
-    path: "src/application"
-    description: "Use cases and application logic"
-    allowedImports: ["domain"]
-
-  - name: "infrastructure"
-    path: "src/infrastructure"
-    description: "External tools, databases, and third-party services"
-    allowedImports: ["domain", "application"]
-
-  - name: "interface"
-    path: "src/interface"
-    description: "Controllers, API endpoints, and Presenters"
-    allowedImports: ["application"]
-`.trim();
-    // 3. Write the file
-    try {
-        fs_1.default.writeFileSync(configPath, template, "utf-8");
-        console.log(chalk_1.default.green.bold("✅ Successfully initialized 'archforge.yaml'"));
-        console.log(chalk_1.default.white("   You can now customize the layers in the file."));
-        console.log(chalk_1.default.gray("\nNext steps:"));
-        console.log(chalk_1.default.cyan("   1. archforge generate"));
-        console.log(chalk_1.default.cyan("   2. archforge analyze"));
-    }
-    catch (err) {
-        console.error(chalk_1.default.red("❌ Failed to create configuration file:"), err.message);
-        process.exit(1);
-    }
-});