@engjts/nexus 0.1.0

package/documentation/32-cli.md

@@ -0,0 +1,268 @@
+# Nexus CLI
+
+Command-line interface untuk Nexus Framework.
+
+## Installation
+
+Setelah install `@engjts/nexus`, command `nexus` akan tersedia secara global:
+
+```bash
+npm install -g @engjts/nexus
+```
+
+Atau gunakan via npx:
+
+```bash
+npx @engjts/nexus create my-app
+```
+
+## Commands
+
+### `nexus create <name>`
+
+Buat project Nexus baru.
+
+```bash
+nexus create my-app
+nexus create my-api --template api
+nexus create my-fullstack --template fullstack
+```
+
+**Options:**
+
+| Option | Alias | Description | Default |
+|--------|-------|-------------|---------|
+| `--template` | `-t` | Template project (basic, api, fullstack) | `basic` |
+| `--package-manager` | `-pm` | Package manager (npm, yarn, pnpm, bun) | `npm` |
+| `--skip-install` | | Skip dependency installation | `false` |
+| `--skip-git` | | Skip git initialization | `false` |
+
+**Templates:**
+
+- **basic**: Simple starter dengan routing dasar
+- **api**: REST API dengan structure lengkap (routes, middleware, services, validators)
+- **fullstack**: API + static files untuk frontend
+
+### `nexus init`
+
+Initialize Nexus di directory yang sudah ada.
+
+```bash
+nexus init
+nexus init --template api
+nexus init --force
+```
+
+**Options:**
+
+| Option | Alias | Description | Default |
+|--------|-------|-------------|---------|
+| `--template` | `-t` | Template project | `basic` |
+| `--force` | `-f` | Force init meskipun directory tidak kosong | `false` |
+
+### `nexus generate <type> <name>`
+
+Generate komponen baru.
+
+```bash
+nexus generate route users
+nexus generate controller UserController
+nexus generate middleware auth
+nexus generate service user
+nexus generate model Product
+nexus generate validator user
+```
+
+**Types:**
+
+| Type | Description | Output Path |
+|------|-------------|-------------|
+| `route` | Route handler | `src/routes/<name>.ts` |
+| `middleware` | Middleware function | `src/middleware/<name>.ts` |
+| `controller` | Controller class dengan decorators | `src/controllers/<name>.ts` |
+| `service` | Service class dengan CRUD methods | `src/services/<name>.ts` |
+| `model` | Model/entity definition | `src/models/<name>.ts` |
+| `validator` | Zod validation schemas | `src/validators/<name>.ts` |
+
+**Options:**
+
+| Option | Alias | Description |
+|--------|-------|-------------|
+| `--path` | `-p` | Custom output path |
+| `--methods` | `-m` | HTTP methods untuk route (comma-separated) |
+
+**Examples:**
+
+```bash
+# Generate route dengan multiple methods
+nexus generate route products --methods get,post,put,delete
+
+# Generate ke custom path
+nexus generate middleware auth --path src/api/middleware
+```
+
+### `nexus dev`
+
+Start development server dengan hot reload.
+
+```bash
+nexus dev
+nexus dev --port 8080
+nexus dev --host 0.0.0.0
+```
+
+**Options:**
+
+| Option | Alias | Description | Default |
+|--------|-------|-------------|---------|
+| `--port` | `-p` | Port untuk server | `3000` |
+| `--host` | `-H` | Host untuk bind server | `localhost` |
+
+### `nexus build`
+
+Build project untuk production.
+
+```bash
+nexus build
+nexus build --outDir build
+```
+
+**Options:**
+
+| Option | Alias | Description | Default |
+|--------|-------|-------------|---------|
+| `--outDir` | `-o` | Output directory | `dist` |
+| `--minify` | | Minify output | `false` |
+
+### `nexus help [command]`
+
+Tampilkan help.
+
+```bash
+nexus help
+nexus help create
+nexus help generate
+```
+
+### `nexus version`
+
+Tampilkan versi CLI.
+
+```bash
+nexus version
+nexus --version
+nexus -v
+```
+
+## Project Structure
+
+Saat membuat project baru dengan template `api`, struktur folder akan seperti ini:
+
+```
+my-app/
+├── src/
+│   ├── index.ts            # Entry point
+│   ├── routes/
+│   │   ├── index.ts        # Route registry
+│   │   └── users.ts        # User routes
+│   ├── middleware/
+│   │   ├── auth.ts         # Auth middleware
+│   │   └── logger.ts       # Logger middleware
+│   ├── services/
+│   │   └── user.service.ts # Business logic
+│   ├── validators/
+│   │   └── user.validator.ts # Zod schemas
+│   └── types/
+│       └── index.ts        # TypeScript types
+├── package.json
+├── tsconfig.json
+├── .env.example
+├── .gitignore
+└── README.md
+```
+
+## Environment Variables
+
+File `.env.example` berisi template environment variables:
+
+```env
+# Server
+PORT=3000
+HOST=localhost
+NODE_ENV=development
+
+# Database
+DATABASE_URL=mysql://user:password@localhost:3306/dbname
+
+# JWT
+JWT_SECRET=your-super-secret-jwt-key
+JWT_EXPIRES_IN=7d
+
+# Rate Limiting
+RATE_LIMIT_MAX=100
+RATE_LIMIT_WINDOW_MS=60000
+```
+
+Copy ke `.env` dan sesuaikan nilai-nilainya:
+
+```bash
+cp .env.example .env
+```
+
+## Quick Start
+
+```bash
+# Create new project
+nexus create my-api --template api
+
+# Navigate to project
+cd my-api
+
+# Install dependencies (if skipped)
+npm install
+
+# Start development server
+npm run dev
+# atau
+nexus dev
+
+# Build for production
+npm run build
+# atau
+nexus build
+
+# Start production server
+npm start
+```
+
+## Tips
+
+### Using with Different Package Managers
+
+```bash
+# Using Yarn
+nexus create my-app --pm yarn
+
+# Using pnpm
+nexus create my-app --pm pnpm
+
+# Using Bun
+nexus create my-app --pm bun
+```
+
+### Generate Multiple Components
+
+```bash
+# Generate complete feature
+nexus generate route products
+nexus generate service product
+nexus generate validator product
+nexus generate model Product
+```
+
+### Custom Paths
+
+```bash
+# Generate ke subfolder
+nexus generate route v2/users --path src/api/v2/routes
+```

package/documentation/ALERTS-COMPLETE-SUMMARY.md

@@ -0,0 +1,429 @@
+# 🎉 Alert System - Implementation Complete
+
+## Status: ✅ READY FOR PRODUCTION
+
+Sistem Alert dengan Adapter Pattern telah selesai di-implement dengan dokumentasi lengkap dan contoh penggunaan.
+
+---
+
+## What's Been Done
+
+### ✅ Code Implementation
+
+1. **Alert Channel Adapter Pattern**
+   - File: `src/advanced/observability/adapters.ts`
+   - Interface: `AlertChannelAdapter`
+   - Registry: `AlertChannelAdapterRegistry`
+
+2. **Built-in Adapters (7 total)**
+   - ✨ **Telegram** - NEW
+   - ✨ **Discord** - NEW
+   - Slack
+   - Webhook (Custom HTTP)
+   - Email (template)
+   - PagerDuty (template)
+   - Console (testing)
+
+3. **Refactored AlertManager**
+   - File: `src/advanced/observability/index.ts`
+   - Removed hardcoded switch-case
+   - Uses adapter registry
+   - Better error handling
+   - Config validation
+
+4. **Type Safety**
+   - Updated `AlertingOptions` interface
+   - Support for all 7 channels
+   - TypeScript compilation ✅
+
+---
+
+### ✅ Documentation
+
+| File | Purpose |
+|------|---------|
+| `16-alerts-system.md` | Complete alert system guide |
+| `17-alert-adapters.md` | Adapter pattern & custom adapters |
+| `18-alerts-implementation-summary.md` | Implementation details & architecture |
+| `ALERTS-QUICK-REFERENCE.md` | Quick reference card |
+
+---
+
+### ✅ Examples & Configuration
+
+| File | Purpose |
+|------|---------|
+| `example-alerts.ts` | 6 real-world examples |
+| `.env.example.alerts` | Environment variable template |
+
+---
+
+## Features Implemented
+
+### Alert Channels
+
+```
+Telegram  ✅  Production-ready
+Discord   ✅  Production-ready
+Slack     ✅  Production-ready
+Webhook   ✅  Production-ready (Generic HTTP)
+Email     ⚠️  Template (needs SendGrid/Mailgun integration)
+PagerDuty ⚠️  Template (needs Events API v2 integration)
+Console   ✅  Testing & debugging
+```
+
+### Adapter Pattern Benefits
+
+- ✅ **Extensible** - Add new channels easily
+- ✅ **Maintainable** - Each adapter isolated
+- ✅ **Testable** - Mock adapters easily
+- ✅ **Type-safe** - Full TypeScript support
+- ✅ **Flexible** - Mix & match channels
+- ✅ **Dynamic** - Register adapters at runtime
+
+### Core Features
+
+- ✅ Multiple notification channels
+- ✅ Alert condition evaluation (>, <, >=, <=)
+- ✅ Cooldown to prevent spam (60 seconds)
+- ✅ Alert history tracking
+- ✅ Config validation per adapter
+- ✅ Error handling & logging
+- ✅ Custom adapter support
+- ✅ Environment-aware setup
+
+---
+
+## Quick Start
+
+### 1. Setup Telegram Alerts
+
+```bash
+# Get bot token from @BotFather on Telegram
+# Get chat ID from api.telegram.org/bot{TOKEN}/getUpdates
+
+export TELEGRAM_BOT_TOKEN=123456789:ABCdefGHIjklmnoPQRstUVwxyz
+export TELEGRAM_CHAT_ID=987654321
+```
+
+```typescript
+import { ObservabilityCenter } from './nexus/advanced/observability';
+
+const obs = new ObservabilityCenter({
+  alerting: {
+    enabled: true,
+    channels: {
+      telegram: {
+        botToken: process.env.TELEGRAM_BOT_TOKEN!,
+        chatId: process.env.TELEGRAM_CHAT_ID!
+      }
+    },
+    alerts: [
+      {
+        name: 'High Error Rate',
+        condition: 'error_rate > 0.05',
+        window: '5m',
+        threshold: 0.05,
+        channels: ['telegram']
+      }
+    ]
+  }
+});
+```
+
+### 2. Multi-Channel Setup
+
+```typescript
+channels: {
+  slack: { webhookUrl: process.env.SLACK_WEBHOOK_URL! },
+  telegram: { 
+    botToken: process.env.TELEGRAM_BOT_TOKEN!,
+    chatId: process.env.TELEGRAM_CHAT_ID!
+  },
+  discord: { webhookUrl: process.env.DISCORD_WEBHOOK_URL! }
+}
+
+// Use all 3 channels in one alert
+channels: ['slack', 'telegram', 'discord']
+```
+
+### 3. Custom Adapter
+
+```typescript
+import { AlertChannelAdapter } from './nexus/advanced/observability';
+
+class MyAdapter implements AlertChannelAdapter {
+  async send(alert, value, config) {
+    // Your implementation
+  }
+  validate(config) {
+    return !!config.required;
+  }
+}
+
+registry?.register('my-adapter', new MyAdapter());
+```
+
+---
+
+## File Structure
+
+```
+nexus/
+├── src/
+│   └── advanced/
+│       └── observability/
+│           ├── index.ts (MODIFIED)
+│           ├── adapters.ts (NEW ✨)
+│           ├── cache/
+│           ├── graphql/
+│           ├── jobs/
+│           ├── realtime/
+│           ├── sentry/
+│           ├── testing/
+│           └── versioning/
+│
+├── documentation/
+│   ├── 16-alerts-system.md (NEW ✨)
+│   ├── 17-alert-adapters.md (NEW ✨)
+│   ├── 18-alerts-implementation-summary.md (NEW ✨)
+│   ├── ALERTS-QUICK-REFERENCE.md (NEW ✨)
+│   ├── 01-15-*.md (existing)
+│   └── README.md
+│
+├── example-alerts.ts (NEW ✨)
+├── .env.example.alerts (NEW ✨)
+└── ... (other files)
+```
+
+---
+
+## Key Design Decisions
+
+### Why Adapter Pattern?
+
+**Before (Hardcoded):**
+```typescript
+switch (channel) {
+  case 'slack': await sendSlack(...); break;
+  case 'email': await sendEmail(...); break;
+  // Adding new channel = modify AlertManager
+}
+```
+
+**After (Adapter Pattern):**
+```typescript
+const adapter = registry.get(channel);
+await adapter.send(alert, value, config);
+// Adding new channel = create new adapter class
+```
+
+### Why Interface-based?
+
+- ✅ Type safety at compile-time
+- ✅ IDE auto-completion
+- ✅ Clear contract for adapters
+- ✅ Easy testing with mocks
+
+### Why Registry Pattern?
+
+- ✅ Dynamic adapter registration
+- ✅ Runtime channel discovery
+- ✅ Support custom adapters
+- ✅ No hardcoding needed
+
+---
+
+## Documentation Breakdown
+
+### 16-alerts-system.md
+- Alert System overview
+- Quick start guide
+- Configuration & API
+- Common patterns
+- Troubleshooting
+- **Best for:** Understanding the system
+
+### 17-alert-adapters.md
+- Adapter pattern explanation
+- All 7 built-in adapters documented
+- Custom adapter creation
+- Multi-severity patterns
+- Registry API
+- Real-world examples
+- **Best for:** Creating custom adapters & advanced usage
+
+### 18-alerts-implementation-summary.md
+- What's implemented
+- Architecture overview
+- File modifications
+- Design decisions
+- Production checklist
+- **Best for:** Technical overview & deployment
+
+### ALERTS-QUICK-REFERENCE.md
+- Setup channels (copy-paste ready)
+- Define alerts
+- Usage patterns
+- API methods
+- Environment variables
+- Debugging tips
+- **Best for:** Quick lookup & reference
+
+### example-alerts.ts
+- 6 complete examples:
+  1. Basic Telegram alerts
+  2. Multi-channel (Slack+Discord+Telegram)
+  3. Custom adapter
+  4. Environment-aware setup
+  5. Local testing
+  6. Dynamic configuration
+- **Best for:** Copy-paste starting point
+
+---
+
+## Testing
+
+### Local Testing
+```bash
+npx ts-node example-alerts.ts
+```
+
+### Manual Trigger
+```typescript
+await observability.alertManager?.checkAndTrigger('Alert Name', value);
+```
+
+### Check History
+```typescript
+const history = observability.getAlertHistory();
+console.log(history);
+```
+
+---
+
+## Production Checklist
+
+- ✅ Adapters implemented (7 total)
+- ✅ Type safety verified
+- ✅ Error handling in place
+- ✅ Config validation per adapter
+- ✅ Alert cooldown (60s)
+- ✅ Alert history tracking
+- ✅ Multiple channels support
+- ✅ Documentation complete (4 files)
+- ✅ Examples provided (6 patterns)
+- ✅ Environment variables template
+- ⚠️ Email/PagerDuty need service integration
+- ⚠️ Rate limiting per channel (optional)
+- ⚠️ Retry logic (optional)
+
+---
+
+## Next Steps (Optional Enhancements)
+
+1. **System Metrics Monitoring**
+   - Auto-detect memory spike
+   - Auto-detect CPU spike
+   - Auto-detect server crash
+   - Auto-trigger alerts
+
+2. **Email Implementation**
+   - Integrate SendGrid/Mailgun
+   - Email templates
+
+3. **PagerDuty Implementation**
+   - Events API v2 integration
+   - Incident escalation
+
+4. **Alert Dashboard**
+   - View active alerts
+   - Alert history UI
+   - Configure alerts via UI
+
+5. **Advanced Features**
+   - Conditional retry logic
+   - Alert aggregation
+   - Rate limiting per channel
+   - Dead letter queue
+
+---
+
+## How to Extend
+
+### Add New Adapter
+
+1. Implement `AlertChannelAdapter` interface
+2. Add validation logic
+3. Implement `send()` method
+4. Register with registry
+5. Update documentation
+
+```typescript
+class MyAdapter implements AlertChannelAdapter {
+  async send(alert, value, config) { /* ... */ }
+  validate(config) { /* ... */ }
+}
+
+registry?.register('my-adapter', new MyAdapter());
+```
+
+---
+
+## Support & Questions
+
+- Read `16-alerts-system.md` for system overview
+- Read `17-alert-adapters.md` for adapter details
+- Check `example-alerts.ts` for usage examples
+- See `ALERTS-QUICK-REFERENCE.md` for quick lookup
+
+---
+
+## Files Changed
+
+### New Files Created
+- ✨ `src/advanced/observability/adapters.ts`
+- ✨ `documentation/16-alerts-system.md`
+- ✨ `documentation/17-alert-adapters.md`
+- ✨ `documentation/18-alerts-implementation-summary.md`
+- ✨ `documentation/ALERTS-QUICK-REFERENCE.md`
+- ✨ `example-alerts.ts`
+- ✨ `.env.example.alerts`
+
+### Modified Files
+- 📝 `src/advanced/observability/index.ts`
+  - Import adapters
+  - Update AlertingOptions interface
+  - Refactor AlertManager
+  - Export adapter types
+
+---
+
+## Verification
+
+```bash
+# TypeScript compilation ✅
+npx tsc --noEmit
+
+# All files present ✅
+ls -la src/advanced/observability/adapters.ts
+ls -la documentation/16-*.md
+ls -la documentation/17-*.md
+ls -la documentation/18-*.md
+ls -la documentation/ALERTS-QUICK-REFERENCE.md
+ls -la example-alerts.ts
+ls -la .env.example.alerts
+```
+
+---
+
+**Status: PRODUCTION READY** 🚀
+
+Siap untuk di-deploy ke production!
+
+---
+
+**Created:** December 3, 2025
+**Version:** 1.0
+**Author:** AI Assistant
+