create-ng-tailwind 1.0.0 → 2.0.2

package/lib/utils/ai-config.js

@@ -0,0 +1,606 @@
+const fs = require("fs-extra");
+const path = require("path");
+
+/**
+ * AI Configuration Generator
+ *
+ * Strategy:
+ * Creates AI tool-specific configuration files only when explicitly selected
+ */
+
+// ==================== CLAUDE CONFIG ====================
+
+async function createClaudeConfig(projectPath, projectName) {
+  const claudeMd = `# ${projectName} - AI Assistant Guidelines
+
+This is an Angular project scaffolded with **create-ng-tailwind**, using **Angular 20+ and Tailwind CSS v4**.
+
+## 📁 Project Structure
+
+\`\`\`
+src/app/
+├── core/                  # Core application logic
+│   ├── services/          # Auth, API, Toast, Modal, Loading, Cache, Storage, i18n
+│   ├── guards/            # Route guards (auth, role-based)
+│   ├── interceptors/      # HTTP interceptors (auth, error, loading, caching)
+│   └── i18n/              # Translation services
+├── shared/                # Reusable shared code
+│   ├── components/        # Button, Card, Spinner, Toast, Modal
+│   ├── pipes/             # TimeAgo, Truncate, FileSize, SafeHtml
+│   ├── directives/        # ClickOutside, Tooltip
+│   └── models/            # TypeScript interfaces and types
+├── features/              # Feature modules
+│   ├── home/
+│   ├── about/
+│   ├── contact/
+│   └── auth/              # Login, Register, Forgot Password
+└── layout/                # Layout components
+    ├── header/            # Header with language switcher
+    ├── footer/
+    └── auth/              # Auth layout
+\`\`\`
+
+## 🛠 Technology Stack
+
+- **Framework:** Angular 20+ (Standalone Components)
+- **Styling:** Tailwind CSS v4 (PostCSS)
+- **State:** Angular Signals (reactive primitives)
+- **HTTP:** HttpClient with 4 Interceptors
+- **i18n:** @ngx-translate/core (English & Arabic with RTL)
+- **Forms:** Reactive Forms with validation
+- **Routing:** Angular Router with lazy loading
+- **Icons:** @ng-icons/heroicons
+- **Linting:** ESLint + Prettier + Husky
+
+## 🎯 Path Aliases (Use These!)
+
+- \`@core/*\` → \`src/app/core/*\`
+- \`@shared/*\` → \`src/app/shared/*\`
+- \`@features/*\` → \`src/app/features/*\`
+- \`@environments/*\` → \`src/environments/*\`
+
+## ⚡ HTTP Interceptors (Pre-configured)
+
+Interceptors run in this order:
+1. **authInterceptor** → Adds JWT Bearer token to requests
+2. **cachingInterceptor** → Caches GET requests (5min TTL)
+3. **loadingInterceptor** → Shows/hides loading indicator
+4. **errorInterceptor** → Handles errors globally + shows toast
+
+## 🧩 Available Services (Use These!)
+
+### ToastService
+\`\`\`typescript
+import { inject } from '@angular/core';
+import { ToastService } from '@core/services/toast.service';
+
+const toast = inject(ToastService);
+toast.success('Profile updated!');
+toast.error('Failed to save changes');
+toast.warning('Session expiring soon');
+toast.info('New message received');
+\`\`\`
+
+### ModalService
+\`\`\`typescript
+import { inject } from '@angular/core';
+import { ModalService } from '@core/services/modal.service';
+
+const modal = inject(ModalService);
+
+// Confirmation dialog
+const confirmed = await modal.confirm(
+  'Are you sure you want to delete this item?',
+  'Confirm Delete'
+);
+
+if (confirmed) {
+  // Proceed with deletion
+}
+
+// Alert dialog
+await modal.alert('Your session has expired', 'Session Timeout');
+\`\`\`
+
+### ApiService
+\`\`\`typescript
+import { inject } from '@angular/core';
+import { ApiService } from '@core/services/api.service';
+
+const api = inject(ApiService);
+
+// GET request
+api.get<User[]>('users').subscribe(users => {
+  console.log(users);
+});
+
+// POST request
+api.post<User>('users', userData).subscribe(newUser => {
+  console.log('Created:', newUser);
+});
+
+// PUT/DELETE also available
+\`\`\`
+
+### AuthService
+\`\`\`typescript
+import { inject } from '@angular/core';
+import { AuthService } from '@core/services/auth.service';
+
+const auth = inject(AuthService);
+
+// Login
+auth.login({ email, password }).subscribe({
+  next: () => router.navigate(['/dashboard']),
+  error: (err) => console.error(err)
+});
+
+// Check auth state (reactive)
+auth.isAuthenticated$.subscribe(isAuth => {
+  console.log('Authenticated:', isAuth);
+});
+
+// Logout
+auth.logout();
+\`\`\`
+
+### LoadingService
+\`\`\`typescript
+import { inject } from '@angular/core';
+import { LoadingService } from '@core/services/loading.service';
+
+const loading = inject(LoadingService);
+
+// In template (automatic with HTTP interceptor)
+@if (loading.isLoading()) {
+  <app-loading-spinner />
+}
+
+// Manual control (rarely needed)
+loading.show();
+// ... do work
+loading.hide();
+\`\`\`
+
+## 📝 Coding Patterns
+
+### Component Structure (Standalone)
+\`\`\`typescript
+import { Component, inject, signal } from '@angular/core';
+import { CommonModule } from '@angular/common';
+import { ToastService } from '@core/services/toast.service';
+
+@Component({
+  selector: 'app-example',
+  standalone: true,
+  imports: [CommonModule],
+  template: \`
+    <div class="p-6 bg-white rounded-lg shadow">
+      <h2 class="text-xl font-bold mb-4">{{ title() }}</h2>
+      <button
+        (click)="handleClick()"
+        class="px-4 py-2 bg-blue-500 text-white rounded hover:bg-blue-600">
+        Click Me ({{ count() }})
+      </button>
+    </div>
+  \`
+})
+export class ExampleComponent {
+  private toast = inject(ToastService);
+
+  // Use signals for reactive state
+  title = signal('Example Component');
+  count = signal(0);
+
+  handleClick(): void {
+    this.count.update(n => n + 1);
+    this.toast.success(\`Clicked \${this.count()} times\`);
+  }
+}
+\`\`\`
+
+### Service Creation
+\`\`\`typescript
+import { Injectable, inject, signal } from '@angular/core';
+import { ApiService } from '@core/services/api.service';
+
+interface Item {
+  id: string;
+  name: string;
+}
+
+@Injectable({ providedIn: 'root' })
+export class ItemService {
+  private api = inject(ApiService);
+
+  // Use signals for reactive state
+  items = signal<Item[]>([]);
+  loading = signal(false);
+
+  loadItems(): void {
+    this.loading.set(true);
+    this.api.get<Item[]>('items').subscribe({
+      next: (data) => {
+        this.items.set(data);
+        this.loading.set(false);
+      },
+      error: () => this.loading.set(false)
+    });
+  }
+}
+\`\`\`
+
+### Reactive Forms
+\`\`\`typescript
+import { Component, inject } from '@angular/core';
+import { FormBuilder, ReactiveFormsModule, Validators } from '@angular/forms';
+
+@Component({
+  selector: 'app-contact-form',
+  standalone: true,
+  imports: [ReactiveFormsModule],
+  template: \`
+    <form [formGroup]="form" (ngSubmit)="onSubmit()">
+      <input formControlName="email" class="border p-2 rounded" />
+      @if (form.get('email')?.invalid && form.get('email')?.touched) {
+        <span class="text-red-500 text-sm">Email is required</span>
+      }
+      <button type="submit" class="px-4 py-2 bg-blue-500 text-white rounded">
+        Submit
+      </button>
+    </form>
+  \`
+})
+export class ContactFormComponent {
+  private fb = inject(FormBuilder);
+
+  form = this.fb.group({
+    email: ['', [Validators.required, Validators.email]],
+    message: ['', [Validators.required, Validators.minLength(10)]]
+  });
+
+  onSubmit(): void {
+    if (this.form.valid) {
+      console.log(this.form.value);
+    } else {
+      Object.keys(this.form.controls).forEach(key => {
+        this.form.get(key)?.markAsTouched();
+      });
+    }
+  }
+}
+\`\`\`
+
+### Routing with Lazy Loading
+\`\`\`typescript
+import { Routes } from '@angular/router';
+import { authGuard } from '@core/guards/auth.guard';
+
+export const routes: Routes = [
+  {
+    path: '',
+    loadComponent: () => import('./features/home/home.component')
+      .then(c => c.HomeComponent)
+  },
+  {
+    path: 'dashboard',
+    loadComponent: () => import('./features/dashboard/dashboard.component')
+      .then(c => c.DashboardComponent),
+    canActivate: [authGuard]
+  }
+];
+\`\`\`
+
+## 🎨 Styling Guidelines
+
+**Always use Tailwind CSS classes. Do NOT write custom CSS.**
+
+Common patterns:
+\`\`\`html
+<!-- Layout -->
+<div class="container mx-auto px-4">
+<div class="flex items-center justify-between">
+<div class="grid grid-cols-1 md:grid-cols-2 lg:grid-cols-3 gap-4">
+
+<!-- Spacing -->
+<div class="p-4 mt-6 space-y-4">
+
+<!-- Colors -->
+<div class="bg-blue-500 text-white">
+<button class="bg-gray-100 hover:bg-gray-200 text-gray-900">
+
+<!-- Typography -->
+<h1 class="text-3xl font-bold">
+<p class="text-sm text-gray-600">
+
+<!-- Responsive -->
+<div class="hidden md:block">
+<div class="w-full md:w-1/2 lg:w-1/3">
+\`\`\`
+
+## 🌍 Internationalization (i18n)
+
+Support English and Arabic with RTL:
+
+**Add translations to both files:**
+- \`public/assets/i18n/en.json\`
+- \`public/assets/i18n/ar.json\`
+
+**In templates:**
+\`\`\`html
+<h1>{{ 'welcome.title' | translate }}</h1>
+<button>{{ 'common.save' | translate }}</button>
+\`\`\`
+
+**In components:**
+\`\`\`typescript
+import { inject } from '@angular/core';
+import { TranslateService } from '@ngx-translate/core';
+
+const translate = inject(TranslateService);
+const message = translate.instant('error.notFound');
+\`\`\`
+
+## ✅ Best Practices
+
+1. **Always use standalone components** (no NgModule)
+2. **Use inject() function** (not constructor injection)
+3. **Use signals for reactive state** (not BehaviorSubject unless needed)
+4. **Use existing services** before creating new ones
+5. **Use Tailwind CSS classes** (no custom CSS)
+6. **Use path aliases** (@core/, @shared/, @features/)
+7. **Use lazy loading** for all routes
+8. **Use Reactive Forms** (not template-driven)
+9. **Write unit tests** for services and components
+10. **Support RTL** for Arabic language
+
+## ❌ Don't Do This
+
+- ❌ Don't use NgModule (use standalone)
+- ❌ Don't use constructor injection (use inject())
+- ❌ Don't write custom CSS (use Tailwind)
+- ❌ Don't use \`any\` type (use proper TypeScript types)
+- ❌ Don't use \`src/assets/\` (use \`public/assets/\`)
+- ❌ Don't use HttpClient directly (use ApiService)
+- ❌ Don't create services that already exist
+- ❌ Don't use template-driven forms
+- ❌ Don't forget to add translations for new text
+
+## 📦 Available Pipes
+
+- \`truncate:50:true\` - Truncate text to 50 chars with word boundaries
+- \`translate\` - i18n translations (from @ngx-translate)
+
+## 📦 Available Directives
+
+- \`appClickOutside\` - Detect clicks outside element
+- \`appTooltip="text"\` - Show tooltip on hover
+
+## 🧪 Testing
+
+Write unit tests using Jasmine/Karma:
+\`\`\`typescript
+describe('ExampleComponent', () => {
+  let component: ExampleComponent;
+  let fixture: ComponentFixture<ExampleComponent>;
+
+  beforeEach(() => {
+    TestBed.configureTestingModule({
+      imports: [ExampleComponent]
+    });
+    fixture = TestBed.createComponent(ExampleComponent);
+    component = fixture.componentInstance;
+  });
+
+  it('should create', () => {
+    expect(component).toBeTruthy();
+  });
+});
+\`\`\`
+
+## 📚 Important Notes
+
+- Assets go in \`public/assets/\` (not \`src/assets/\`)
+- Tailwind v4 uses CSS imports: \`@import "tailwindcss";\`
+- PostCSS config is in \`.postcssrc.json\`
+- HTTP interceptors run automatically (no manual setup needed)
+- Loading state is automatic for HTTP requests
+- Error handling is automatic (shows toast notifications)
+
+---
+
+**Remember:** This is a production-ready starter. Use the existing infrastructure before creating new utilities!
+`;
+
+  // Create .claude directory if it doesn't exist
+  const claudeDir = path.join(projectPath, ".claude");
+  await fs.ensureDir(claudeDir);
+
+  // Write claude.md inside .claude folder
+  await fs.writeFile(path.join(claudeDir, "claude.md"), claudeMd);
+}
+
+// ==================== CURSOR-SPECIFIC CONFIG ====================
+
+async function createCursorConfig(projectPath, projectName) {
+  const cursorRules = `# ${projectName} - Cursor AI Rules
+
+## Quick Reference
+- Angular 20+ standalone components
+- Tailwind CSS v4 (use utility classes only)
+- inject() for DI (not constructors)
+- Signals for state (not BehaviorSubject)
+- Path aliases: @core/, @shared/, @features/, @environments/
+
+## Component Pattern
+\`\`\`typescript
+import { Component, inject, signal } from '@angular/core';
+import { CommonModule } from '@angular/common';
+
+@Component({
+  selector: 'app-name',
+  standalone: true,
+  imports: [CommonModule],
+  template: \`<div class="p-4">{{ text() }}</div>\`
+})
+export class NameComponent {
+  private service = inject(ServiceName);
+  text = signal('Hello');
+}
+\`\`\`
+
+## Available Services (Use These!)
+- **ToastService** - \`toast.success('Message')\`
+- **ModalService** - \`await modal.confirm('Message')\`
+- **ApiService** - \`api.get<Type>('endpoint')\`
+- **AuthService** - \`auth.login(credentials)\`
+- **LoadingService** - \`loading.isLoading()\`
+
+## HTTP Interceptors (Automatic)
+Auth → Cache → Loading → Error
+
+## Forms: Use Reactive Forms
+\`\`\`typescript
+form = inject(FormBuilder).group({
+  email: ['', [Validators.required, Validators.email]]
+});
+\`\`\`
+
+## Routing: Use Lazy Loading
+\`\`\`typescript
+{
+  path: 'feature',
+  loadComponent: () => import('./feature/feature.component')
+    .then(c => c.FeatureComponent)
+}
+\`\`\`
+
+## Styling: Tailwind Only
+Use: \`bg-blue-500 text-white p-4 rounded hover:bg-blue-600\`
+
+## i18n: Support English + Arabic
+Add keys to \`public/assets/i18n/en.json\` and \`ar.json\`
+
+## Don't
+- No NgModule
+- No constructor injection
+- No custom CSS
+- No \`any\` type
+- No \`src/assets/\` (use \`public/assets/\`)
+- No HttpClient directly (use ApiService)
+`;
+
+  await fs.writeFile(path.join(projectPath, ".cursorrules"), cursorRules);
+}
+
+// ==================== WINDSURF-SPECIFIC CONFIG ====================
+
+async function createWindsurfConfig(projectPath, projectName) {
+  const windsurfRules = `# ${projectName} - Windsurf AI Rules
+
+Angular 20+ | Tailwind CSS v4 | Standalone Components | Signals
+
+## Quick Patterns
+
+Component:
+\`\`\`typescript
+@Component({
+  selector: 'app-name',
+  standalone: true,
+  imports: [CommonModule],
+  template: \`<div class="p-4">{{ state() }}</div>\`
+})
+export class NameComponent {
+  private svc = inject(Service);
+  state = signal(value);
+}
+\`\`\`
+
+Show Toast:
+\`\`\`typescript
+inject(ToastService).success('Message');
+\`\`\`
+
+Open Modal:
+\`\`\`typescript
+await inject(ModalService).confirm('Message');
+\`\`\`
+
+API Call:
+\`\`\`typescript
+inject(ApiService).get<Type>('endpoint').subscribe(...);
+\`\`\`
+
+Form:
+\`\`\`typescript
+form = inject(FormBuilder).group({
+  field: ['', Validators.required]
+});
+\`\`\`
+
+## Path Aliases
+@core/ @shared/ @features/ @environments/
+
+## Services Available
+ToastService, ModalService, ApiService, AuthService, LoadingService, CacheService
+
+## HTTP Interceptors (Auto)
+Auth → Cache → Loading → Error
+
+## Styling
+Tailwind only: bg-blue-500 text-white p-4 rounded
+
+## i18n
+public/assets/i18n/en.json + ar.json
+
+## Don't
+No NgModule, No constructors, No custom CSS, No 'any', No src/assets
+`;
+
+  await fs.writeFile(path.join(projectPath, ".windsurfrules"), windsurfRules);
+}
+
+// ==================== MAIN EXPORT ====================
+
+/**
+ * Create AI configuration files
+ * Creates tool-specific configs only when explicitly selected
+ *
+ * @param {string} projectPath - Full path to the project
+ * @param {string} projectName - Name of the project
+ * @param {string[]} aiTools - Array of selected AI tools
+ */
+async function createAIConfigs(projectPath, projectName, aiTools) {
+  // Skip if user selected "none"
+  if (
+    !aiTools ||
+    aiTools.length === 0 ||
+    (aiTools.length === 1 && aiTools[0] === "none")
+  ) {
+    return;
+  }
+
+  console.log("\n🤖 Configuring AI tools...");
+
+  // Create tool-specific configs only if selected
+  if (aiTools.includes("claude")) {
+    await createClaudeConfig(projectPath, projectName);
+    console.log("  ✓ .claude/claude.md created");
+  }
+
+  if (aiTools.includes("cursor")) {
+    await createCursorConfig(projectPath, projectName);
+    console.log("  ✓ .cursorrules created");
+  }
+
+  if (aiTools.includes("windsurf")) {
+    await createWindsurfConfig(projectPath, projectName);
+    console.log("  ✓ .windsurfrules created");
+  }
+
+  console.log("✨ AI configuration complete!\n");
+}
+
+module.exports = {
+  createAIConfigs,
+};

package/lib/utils/constants.js

@@ -0,0 +1,14 @@
+const TEMPLATES = {
+  MINIMAL: "minimal",
+  STARTER: "starter",
+};
+
+const ANGULAR_VERSION = "latest";
+
+const TAILWIND_VERSION = "^4.0.0";
+
+module.exports = {
+  TEMPLATES,
+  ANGULAR_VERSION,
+  TAILWIND_VERSION,
+};

package/lib/utils/helpers.js

@@ -0,0 +1,60 @@
+const fs = require("fs-extra");
+const path = require("path");
+
+/**
+ * Validate project name
+ */
+function validateProjectName(name) {
+  if (!name || !name.trim()) {
+    return { valid: false, error: "Project name is required" };
+  }
+
+  if (!/^[a-z0-9-]+$/.test(name)) {
+    return {
+      valid: false,
+      error:
+        "Project name can only contain lowercase letters, numbers, and hyphens",
+    };
+  }
+
+  return { valid: true };
+}
+
+/**
+ * Check if directory exists
+ */
+async function directoryExists(dirPath) {
+  try {
+    const stats = await fs.stat(dirPath);
+    return stats.isDirectory();
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Ensure directory exists
+ */
+async function ensureDirectory(dirPath) {
+  await fs.ensureDir(dirPath);
+}
+
+/**
+ * Copy file with error handling
+ */
+async function safeCopy(src, dest) {
+  try {
+    await fs.copy(src, dest);
+    return true;
+  } catch (error) {
+    console.error(`Failed to copy ${src} to ${dest}:`, error.message);
+    return false;
+  }
+}
+
+module.exports = {
+  validateProjectName,
+  directoryExists,
+  ensureDirectory,
+  safeCopy,
+};