@devmed555/angular-clean-architecture-cli 0.0.1 → 0.0.3

package/README.md

@@ -1,183 +1,425 @@
-# CLI Documentation
+# Angular Clean Architecture CLI
 
-The CLI is an Nx generator designed to scaffold clean architecture features within the `sandbox` application.
+[![npm version](https://img.shields.io/npm/v/@devmed555/angular-clean-architecture-cli.svg)](https://www.npmjs.com/package/@devmed555/angular-clean-architecture-cli)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
-## Usage
+> 🚀 Scaffold Angular features following Clean Architecture principles with NgRx SignalStore.
 
-To generate a new feature, run:
+A powerful CLI that generates production-ready Angular features structured into **Domain**, **Infrastructure**, **Application**, and **UI** layers — keeping your codebase maintainable, testable, and scalable.
+
+---
+
+## 📦 Installation
+
+```bash
+# Global installation (recommended)
+npm install -g @devmed555/angular-clean-architecture-cli
+
+# Verify installation
+aca --version
+```
+
+### Prerequisites
+
+- **Node.js** v18+
+- **Angular** 16+ project
+- **@ngrx/signals** installed:
+  ```bash
+  npm install @ngrx/signals
+  ```
+
+---
+
+## ⚡ Quick Start
+
+```bash
+# Generate all features from feature-schema.json
+aca g feature
+
+# Generate a single feature with attributes
+aca g feature product --attributes="name:string,price:number"
+
+# Generate ALL core assets (auth, navbar, menu, theme, etc.)
+aca g core
+
+# Generate ALL shared components (button, card, input, etc.)
+aca g shared
+```
+
+---
+
+## 🛠️ Generators
+
+| Generator   | Command         | Description                                     |
+| ----------- | --------------- | ----------------------------------------------- |
+| **Feature** | `aca g feature` | Complete Clean Architecture feature (4 layers)  |
+| **Core**    | `aca g core`    | Core system assets (auth, guards, interceptors) |
+| **Shared**  | `aca g shared`  | Shared UI components & utilities                |
+
+---
+
+## 📁 Feature Generator
+
+Creates a complete Clean Architecture feature with 4 layers:
+
+```
+features/<name>/
+├── domain/model.ts           # Business entities & interfaces
+├── infrastructure/service.ts # HTTP service with CRUD operations
+├── application/store.ts      # NgRx SignalStore state management
+└── ui/component.ts           # Standalone Angular component
+```
+
+### Usage
 
 ```bash
-npm run generate:feature -- --name=<feature-name>
+# Interactive mode
+aca g feature
+
+# With name argument
+aca g feature product
 
-# Examples:
-npm run generate:feature -- --name=products
-npm run generate:feature -- --name=user-profile
-npm run generate:feature -- --name=shopping-cart
+# With inline attributes
+aca g feature product --attributes="name:string,price:number,inStock:boolean"
 
-# Interactive mode with prompts:
-npm run generate:feature:interactive
+# From blueprint file
+aca g feature --blueprint=./my-feature.json
 ```
 
-### Arguments
+### Options
+
+| Option         | Description                    | Example                                    |
+| -------------- | ------------------------------ | ------------------------------------------ |
+| `--attributes` | Define model properties inline | `--attributes="title:string,views:number"` |
+| `--blueprint`  | Use a JSON blueprint file      | `--blueprint=./order.json`                 |
+
+### Supported Types
+
+| Type      | Description                             |
+| --------- | --------------------------------------- |
+| `string`  | Text data                               |
+| `number`  | Numeric values                          |
+| `boolean` | True/false values                       |
+| `Date`    | Date/time values                        |
+| `any`     | Flexible type (use sparingly)           |
+| `Type[]`  | Arrays (e.g., `string[]`, `CartItem[]`) |
 
-| Argument | Description | Required |
-| --- | --- | --- |
-| `--name` | The name of the feature to generate (kebab-case recommended). | Yes |
+### Interactive Mode Example
 
-### Generated Structure
+```
+$ aca g feature
 
-The generator will create the following structure in `apps/sandbox/src/app/features/<name>`:
+? What is the name of the feature (singular)? product
+Let's add some attributes (property fields).
+? Enter attribute name (or press enter to finish): name
+? Select type: string
+? Enter attribute name (or press enter to finish): price
+? Select type: number
+? Enter attribute name (or press enter to finish): [Press Enter]
 
+✓ Generated feature "product" in src/app/features/products
 ```
-<feature-name>/
-├── domain/
-│   └── model.ts              # Business entities (PascalCase interfaces)
-├── infrastructure/
-│   └── service.ts            # HTTP services with CRUD operations
-├── application/
-│   └── store.ts              # NgRx SignalStore for state management
-└── ui/
-    └── component.ts          # Standalone Angular component with store injection
+
+---
+
+## 🔧 Core Generator
+
+Creates core system assets like authentication, guards, and interceptors.
+
+**Running without arguments generates ALL core assets automatically:**
+
+```bash
+# Generate ALL core assets (recommended)
+aca g core
+
+# Output:
+# 🚀 Generating ALL core assets: navbar, menu, theme-selector, language-selector, translate, auth...
+# ✓ Generated core navbar in apps/sandbox/src/app/core/navbar
+# ✓ Generated core menu in apps/sandbox/src/app/core/menu
+# ...
 ```
 
-### Naming Conventions
+### Generated Assets
+
+| Asset               | Description                              |
+| ------------------- | ---------------------------------------- |
+| `navbar`            | Top navigation bar                       |
+| `menu`              | Side navigation menu                     |
+| `theme-selector`    | Dark/light theme toggle                  |
+| `language-selector` | Language switcher component              |
+| `translate`         | i18n translation setup                   |
+| `auth`              | Authentication service with login/logout |
 
-The generator automatically handles naming:
-- **Input**: kebab-case (e.g., `user-profile`)
-- **Classes/Interfaces**: PascalCase (e.g., `UserProfileComponent`, `UserProfile`)
-- **Stores**: PascalCase with "Store" suffix (e.g., `UserProfileStore`)
-- **Services**: PascalCase with "Service" suffix (e.g., `UserProfileService`)
+### Generate Specific Asset
 
-### Example Generated Code
+```bash
+# Generate only a specific asset
+aca g core --type=navbar
+aca g core --type=auth
+aca g core --type=guard
+aca g core --type=interceptor
+```
 
-For `npm run generate:feature -- --name=product`:
+---
 
-**Domain Model** (`domain/model.ts`):
-```typescript
-export interface Product {
-  id: string;
-  createdAt: Date;
-  updatedAt: Date;
+## 🎨 Shared Generator
+
+Creates shared reusable components and utilities.
+
+**Running without arguments generates ALL shared UI components automatically:**
+
+```bash
+# Generate ALL shared UI components (recommended)
+aca g shared
+
+# Output:
+# 🚀 Generating standard shared UI components: button, card, input, icon, loader, confirm-dialog...
+# ✓ Generated shared ui "button" in apps/sandbox/src/app/shared/ui/button
+# ✓ Generated shared ui "card" in apps/sandbox/src/app/shared/ui/card
+# ...
+```
+
+### Generated Components
+
+| Component        | Description                   |
+| ---------------- | ----------------------------- |
+| `button`         | Reusable button component     |
+| `card`           | Card container component      |
+| `input`          | Form input component          |
+| `icon`           | Icon wrapper component        |
+| `loader`         | Loading spinner component     |
+| `confirm-dialog` | Confirmation dialog component |
+
+### Generate Specific Component
+
+```bash
+# Generate only a specific UI component
+aca g shared myButton --type=ui
+
+# Generate a utility module
+aca g shared format --type=util
+```
+
+---
+
+## 📋 Blueprint Mode
+
+For complex features with multiple related models, use a JSON blueprint file.
+
+### Blueprint Schema
+
+```json
+{
+  "name": "order",
+  "models": [
+    {
+      "name": "Order",
+      "attributes": [
+        { "name": "customerId", "type": "string" },
+        { "name": "total", "type": "number" },
+        { "name": "status", "type": "string" }
+      ]
+    },
+    {
+      "name": "OrderItem",
+      "attributes": [
+        { "name": "orderId", "type": "string" },
+        { "name": "productId", "type": "string" },
+        { "name": "quantity", "type": "number" }
+      ]
+    }
+  ]
 }
 ```
 
-**Infrastructure Service** (`infrastructure/service.ts`):
-```typescript
-@Injectable({ providedIn: 'root' })
-export class ProductService {
-  private readonly apiUrl = '/api/products';
-  
-  getAll(): Observable<Product[]> { ... }
-  getById(id: string): Observable<Product> { ... }
-  create(data: Omit<Product, 'id' | 'createdAt' | 'updatedAt'>): Observable<Product> { ... }
-  update(id: string, data: Partial<Product>): Observable<Product> { ... }
-  delete(id: string): Observable<void> { ... }
+### Generate from Blueprint
+
+```bash
+aca g feature --blueprint=./order-blueprint.json
+```
+
+### Example: E-Commerce Blueprint
+
+```json
+{
+  "name": "ecommerce",
+  "models": [
+    {
+      "name": "Product",
+      "attributes": [
+        { "name": "name", "type": "string" },
+        { "name": "price", "type": "number" },
+        { "name": "stock", "type": "number" },
+        { "name": "imageUrl", "type": "string" }
+      ]
+    },
+    {
+      "name": "Cart",
+      "attributes": [
+        { "name": "userId", "type": "string" },
+        { "name": "items", "type": "CartItem[]" },
+        { "name": "total", "type": "number" }
+      ]
+    }
+  ]
 }
 ```
 
-**Application Store** (`application/store.ts`):
-```typescript
-export const ProductStore = signalStore(
-  { providedIn: 'root' },
-  withState({ loading: false })
-);
-```
-
-**UI Component** (`ui/component.ts`):
-```typescript
-@Component({
-  selector: 'app-product-feature',
-  standalone: true,
-  imports: [CommonModule],
-  template: `
-    <div class="product-feature">
-      <h1>Product Feature</h1>
-      @if (store.loading()) {
-        <p>Loading...</p>
-      } @else {
-        <p>Ready to build your product feature!</p>
-      }
-    </div>
-  `,
-})
-export class ProductComponent {
-  protected readonly store = inject(ProductStore);
+---
+
+## 📂 Feature Schema (Batch Generation)
+
+The CLI automatically stores feature definitions in `feature-schema.json`. When you run `aca g feature` without arguments, it can batch-generate all features defined in this schema.
+
+### Schema Format
+
+```json
+{
+  "version": "1.0",
+  "lastUpdated": "2026-01-04T20:11:51.889Z",
+  "features": {
+    "product": {
+      "name": "product",
+      "attributes": [
+        { "name": "name", "type": "string" },
+        { "name": "price", "type": "number" }
+      ]
+    },
+    "book": {
+      "name": "book",
+      "attributes": [
+        { "name": "title", "type": "string" },
+        { "name": "author", "type": "string" }
+      ]
+    }
+  }
 }
 ```
 
-## Template Structure
+### Batch Generation
 
-Templates are located in `src/generators/clean-feature/files/`:
+```bash
+# Running without a name triggers batch generation from feature-schema.json
+aca g feature
 
+# Output:
+# 🚀 Found 4 features in feature-schema.json. Generating...
+# ✓ Generated feature "product" in src/app/features/products
+# ✓ Generated feature "book" in src/app/features/books
 ```
-files/
-├── application/
-│   └── store.ts.template       # SignalStore template
-├── domain/
-│   └── model.ts.template       # Interface template
-├── infrastructure/
-│   └── service.ts.template     # Service template with CRUD
-└── ui/
-    └── component.ts.template   # Component template with store
+
+---
+
+## 🏛️ Architecture Overview
+
+Generated features follow **Clean Architecture** (Hexagonal Architecture) principles:
+
+```
+┌─────────────────────────────────────────────────────────┐
+│                         UI Layer                         │
+│              (Components, Templates, Styles)             │
+├─────────────────────────────────────────────────────────┤
+│                    Application Layer                     │
+│              (NgRx SignalStore, Selectors)               │
+├─────────────────────────────────────────────────────────┤
+│                  Infrastructure Layer                    │
+│              (HTTP Services, API Clients)                │
+├─────────────────────────────────────────────────────────┤
+│                      Domain Layer                        │
+│          (Interfaces, Types, Business Rules)             │
+└─────────────────────────────────────────────────────────┘
+```
+
+### Dependency Flow
+
+```
+UI → Application → Infrastructure → Domain
+                        ↓
+                   External APIs
 ```
 
-Templates use EJS syntax:
-- `<%= name %>` - Original kebab-case feature name
-- `<%= pascalName %>` - PascalCase version of the name
+- **Domain**: Pure TypeScript, zero dependencies
+- **Infrastructure**: Depends on Domain
+- **Application**: Depends on Infrastructure + Domain
+- **UI**: Depends on Application
+
+---
 
-## Development
+## 💡 Best Practices
 
-### Build the CLI
+### ✅ Feature Naming
 
 ```bash
-npm run cli:build
+# Good (singular, kebab-case)
+aca g feature product
+aca g feature user-profile
+aca g feature order-item
+
+# Avoid
+aca g feature products      # Will become "productss"
+aca g feature UserProfile   # Use kebab-case
 ```
 
-### Test the CLI
+### ✅ Attribute Types
 
 ```bash
-npm run cli:test
+# Use appropriate TypeScript types
+--attributes="name:string,age:number,isActive:boolean,createdAt:Date,tags:string[]"
 ```
 
-### Lint the CLI
+### ✅ Blueprint Organization
+
+```
+project-root/
+├── blueprints/
+│   ├── user.json
+│   ├── product.json
+│   └── order.json
+└── src/
+```
+
+---
+
+## 🔗 Nx Workspace Integration
+
+When using within an Nx monorepo:
 
 ```bash
-npm run cli:lint
+# Generate feature using Nx
+nx g cli:feature product
+
+# Generate core assets
+nx g cli:core app --type=navbar
+
+# Generate shared components
+nx g cli:shared button --type=ui
 ```
 
-### Development Workflow
+---
+
+## 📚 Resources
+
+- [Architecture Documentation](https://github.com/MohamedBouattour/angular-clean-architecture/blob/main/ARCHITECTURE.md)
+- [Examples & Scenarios](./EXAMPLES.md)
+- [Roadmap](https://github.com/MohamedBouattour/angular-clean-architecture/blob/main/ROADMAP.md)
+- [GitHub Issues](https://github.com/MohamedBouattour/angular-clean-architecture/issues)
+
+---
 
-1. **Modify templates** in `src/generators/clean-feature/files/`
-2. **Update generator logic** in `generator.ts` if needed
-3. **Build**: `npm run cli:build`
-4. **Test**: Generate a feature with `npm run generate:feature -- --name=test`
-5. **Verify**: Check generated code in `apps/sandbox/src/app/features/test`
-6. **Clean up**: Delete test feature after verification
+## 🤝 Contributing
 
-### Adding New Template Variables
+1. Fork the repository
+2. Create your feature branch: `git checkout -b feature/amazing-feature`
+3. Commit your changes: `git commit -m 'Add amazing feature'`
+4. Push to the branch: `git push origin feature/amazing-feature`
+5. Open a Pull Request
 
-To add new template variables:
+---
 
-1. Update `generator.ts`:
-   ```typescript
-   generateFiles(tree, ..., targetPath, {
-     ...options,
-     name,
-     pascalName,
-     yourNewVariable: computeValue(name), // Add here
-     tmpl: '',
-   });
-   ```
+## 📝 License
 
-2. Use in templates:
-   ```typescript
-   // In any .template file
-   export class <%= yourNewVariable %>Something { }
-   ```
+MIT © [Mohamed Bouattour](https://github.com/MohamedBouattour)
 
-## Tips
+---
 
-- **Feature naming**: Use kebab-case for multi-word features (e.g., `user-profile`, not `userProfile`)
-- **Testing**: Always test generated code in the sandbox app
-- **Customization**: Modify templates to match your team's conventions
-- **Validation**: Consider adding name validation in `generator.ts` to prevent duplicates
+**Built with ❤️ for the Angular community**

package/bin/index.js

@@ -1,4 +1,102 @@
-#!/usr/bin/env node
+#!/usr/bin/env node
+const { spawn } = require('child_process');
+const path = require('path');
+const fs = require('fs');
+
+const args = process.argv.slice(2);
+
+function findWorkspaceRoot(dir) {
+  if (fs.existsSync(path.join(dir, 'nx.json')) || fs.existsSync(path.join(dir, 'package.json'))) {
+    if (fs.existsSync(path.join(dir, 'nx.json'))) {
+        return dir;
+    }
+  }
+  const parent = path.dirname(dir);
+  if (parent === dir) return null;
+  return findWorkspaceRoot(parent);
+}
+
+const root = findWorkspaceRoot(process.cwd());
+
+/**
+ * Executes an Nx generator command
+ * @param {string} generator - The generator name (e.g., 'feature', 'core', 'shared')
+ * @param {string[]} remainingArgs - Additional arguments to pass
+ */
+function runGenerator(generator, remainingArgs) {
+  const nxArgs = ['g', `cli:${generator}`];
+  
+  remainingArgs.forEach(arg => {
+    nxArgs.push(arg);
+  });
+  
+  console.log(`Executing: npx nx ${nxArgs.join(' ')}`);
+  
+  const child = spawn('npx', ['nx', ...nxArgs], {
+    stdio: 'inherit',
+    shell: true,
+    cwd: root || process.cwd(),
+  });
+  
+  child.on('exit', (code) => {
+    process.exit(code || 0);
+  });
+}
+
+// Parse commands
+if (args[0] === 'generate' || args[0] === 'g') {
+  const generatorType = args[1];
+  const remainingArgs = args.slice(2);
+  
+  // Parse name from positional argument
+  const nxArgs = [];
+  if (remainingArgs[0] && !remainingArgs[0].startsWith('-')) {
+    nxArgs.push(`--name=${remainingArgs[0]}`);
+    remainingArgs.shift();
+  }
+  
+  // Pass through all other flags
+  remainingArgs.forEach(arg => nxArgs.push(arg));
+  
+  switch (generatorType) {
+    case 'feature':
+    case 'f':
+      runGenerator('feature', nxArgs);
+      break;
+    case 'core':
+    case 'c':
+      runGenerator('core', nxArgs);
+      break;
+    case 'shared':
+    case 's':
+      runGenerator('shared', nxArgs);
+      break;
+    default:
+      console.log('\x1b[31m%s\x1b[0m', `Unknown generator: ${generatorType}`);
+      console.log('Available generators: feature (f), core (c), shared (s)');
+      process.exit(1);
+  }
+} else {
+  console.log('\x1b[36m%s\x1b[0m', 'Angular Clean Architecture CLI');
+  console.log('');
+  console.log('Usage:');
+  console.log('  aca generate <generator> [name] [options]');
+  console.log('  aca g <generator> [name] [options]');
+  console.log('');
+  console.log('Generators:');
+  console.log('  feature (f)   Generate a Clean Architecture feature');
+  console.log('  core (c)      Generate a core asset (auth, guard, interceptor, etc.)');
+  console.log('  shared (s)    Generate a shared component or utility');
+  console.log('');
+  console.log('Examples:');
+  console.log('  aca g feature products --attributes="name:string,price:number"');
+  console.log('  aca g core auth-service --type=service');
+  console.log('  aca g core app --type=navbar');
+  console.log('  aca g shared button --type=ui');
+  console.log('');
+  console.log('Run without options for interactive mode:');
+  console.log('  aca g feature');
+  console.log('  aca g core');
+  process.exit(0);
+}
 
-console.log("ACA CLI installed successfully!");
-console.log("To use the generator, run: nx g @devmed555/angular-clean-architecture-cli:clean-feature");

package/generators.json

@@ -1,9 +1,19 @@
-{
-  "generators": {
-    "clean-feature": {
-      "factory": "./src/generators/clean-feature/generator",
-      "schema": "./src/generators/clean-feature/schema.json",
-      "description": "clean-feature generator"
-    }
-  }
-}
+{
+  "generators": {
+    "feature": {
+      "factory": "./src/generators/feature/generator",
+      "schema": "./src/generators/feature/schema.json",
+      "description": "Generate a Clean Architecture feature with domain, infrastructure, application, and UI layers"
+    },
+    "shared": {
+      "factory": "./src/generators/shared/generator",
+      "schema": "./src/generators/shared/schema.json",
+      "description": "Generate a shared UI component or utility"
+    },
+    "core": {
+      "factory": "./src/generators/core/generator",
+      "schema": "./src/generators/core/schema.json",
+      "description": "Generate a core system asset (Auth, Guard, Interceptor, Service)"
+    }
+  }
+}