@onion-architect-ai/cli 4.1.0-beta.1 → 4.1.0-beta.3

package/templates/.cursor/docs/templates/reference-template.md

@@ -0,0 +1,522 @@
+# [Título da Documentação de Referência]
+
+**Tipo:** [API Reference | CLI Reference | Configuration Reference | Schema Reference]  
+**Versão:** [Versão atual]  
+**Última atualização:** [Data]  
+**Status:** [Stable | Beta | Experimental | Deprecated]
+
+---
+
+## 📋 **Overview**
+
+[Descrição concisa do que esta referência documenta]
+
+### **Key Features**
+- [Feature principal 1]
+- [Feature principal 2]
+- [Feature principal 3]
+
+### **Quick Access**
+- 🚀 **[Most Common Use Cases](#common-use-cases)**
+- 📚 **[Complete API List](#complete-reference)**
+- 🔍 **[Search & Filter](#search)**
+- ⚡ **[Quick Examples](#examples)**
+
+---
+
+## 🚀 **Common Use Cases**
+
+### **Use Case 1: [Nome do caso de uso]**
+```typescript
+// Exemplo prático do caso de uso mais comum
+const example = await commonAction({
+  param1: 'value',
+  param2: true
+});
+```
+
+### **Use Case 2: [Nome do caso de uso]**
+```bash
+# Comando CLI mais comum
+command-name --param=value --flag
+```
+
+### **Use Case 3: [Nome do caso de uso]**
+```yaml
+# Configuração mais comum
+common_setting: value
+nested:
+  setting: true
+```
+
+---
+
+## 📚 **Complete Reference**
+
+### **Category 1: [Nome da categoria]**
+
+#### **Function/Command/Setting 1**
+
+**Syntax:**
+```typescript
+functionName(param1: Type1, param2?: Type2): ReturnType
+```
+
+**Parameters:**
+| Parameter | Type | Required | Default | Description |
+|-----------|------|----------|---------|-------------|
+| `param1` | `string` | ✅ | - | [Descrição detalhada do parâmetro] |
+| `param2` | `boolean` | ❌ | `false` | [Descrição detalhada do parâmetro] |
+
+**Returns:**
+| Type | Description |
+|------|-------------|
+| `Promise<ReturnType>` | [Descrição do que é retornado] |
+
+**Example:**
+```typescript
+const result = await functionName('example', true);
+console.log(result); // Expected output
+```
+
+**Error Handling:**
+```typescript
+try {
+  const result = await functionName('invalid');
+} catch (error) {
+  // Error types and handling
+  if (error instanceof ValidationError) {
+    // Handle validation error
+  }
+}
+```
+
+---
+
+#### **Function/Command/Setting 2**
+
+[Continue o padrão...]
+
+### **Category 2: [Nome da categoria]**
+
+[Continue organizando por categorias...]
+
+---
+
+## 🔍 **Search & Filter**
+
+### **By Type**
+- **[Functions](#functions)** - All available functions
+- **[Properties](#properties)** - Configuration properties  
+- **[Events](#events)** - Event types and handlers
+- **[Types](#types)** - TypeScript interfaces and types
+
+### **By Status**
+- **[Stable](#stable)** - Production ready
+- **[Beta](#beta)** - Feature complete, may change
+- **[Experimental](#experimental)** - In development
+- **[Deprecated](#deprecated)** - Being phased out
+
+### **Alphabetical Index**
+- [A](#a) | [B](#b) | [C](#c) | [D](#d) | [E](#e) | [F](#f) | [G](#g) | [H](#h) | [I](#i) | [J](#j) | [K](#k) | [L](#l) | [M](#m)
+- [N](#n) | [O](#o) | [P](#p) | [Q](#q) | [R](#r) | [S](#s) | [T](#t) | [U](#u) | [V](#v) | [W](#w) | [X](#x) | [Y](#y) | [Z](#z)
+
+---
+
+## ⚡ **Examples**
+
+### **Basic Examples**
+
+#### **Example 1: Simple Usage**
+```typescript
+// Basic example with minimal configuration
+import { SimpleFunction } from '@library/module';
+
+const result = await SimpleFunction({
+  required: 'value'
+});
+```
+
+#### **Example 2: Advanced Usage**
+```typescript
+// Advanced example with full configuration
+import { AdvancedFunction, Config } from '@library/module';
+
+const config: Config = {
+  advanced: true,
+  options: {
+    timeout: 5000,
+    retries: 3
+  }
+};
+
+const result = await AdvancedFunction(config);
+```
+
+### **Real-World Examples**
+
+#### **Example 3: Production Pattern**
+```typescript
+// Real-world production usage
+import { ProductionPattern } from '@library/module';
+
+class MyService {
+  private pattern: ProductionPattern;
+  
+  constructor() {
+    this.pattern = new ProductionPattern({
+      env: process.env.NODE_ENV,
+      config: this.loadConfig()
+    });
+  }
+  
+  async processData(data: unknown) {
+    return this.pattern.process(data);
+  }
+}
+```
+
+### **Integration Examples**
+
+#### **Example 4: With Other Libraries**
+```typescript
+// Integration with popular libraries
+import { Library } from '@library/module';
+import { OtherLib } from 'other-library';
+
+const combined = new Library({
+  adapter: new OtherLib.Adapter({
+    // Configuration
+  })
+});
+```
+
+---
+
+## 🛠️ **Configuration**
+
+### **Configuration Schema**
+
+```typescript
+interface Configuration {
+  /** Core settings */
+  core: {
+    /** [Required] Application name */
+    name: string;
+    /** [Optional] Debug mode */
+    debug?: boolean;
+    /** [Optional] Environment */
+    env?: 'development' | 'production' | 'test';
+  };
+  
+  /** Feature flags */
+  features?: {
+    /** Enable experimental features */
+    experimental?: boolean;
+    /** Enable beta features */
+    beta?: boolean;
+  };
+  
+  /** Performance settings */
+  performance?: {
+    /** Timeout in milliseconds */
+    timeout?: number;
+    /** Max retry attempts */
+    retries?: number;
+    /** Enable caching */
+    cache?: boolean;
+  };
+}
+```
+
+### **Environment Variables**
+
+| Variable | Type | Default | Description |
+|----------|------|---------|-------------|
+| `APP_NAME` | `string` | - | Application name (required) |
+| `DEBUG` | `boolean` | `false` | Enable debug logging |
+| `NODE_ENV` | `string` | `development` | Runtime environment |
+| `API_TIMEOUT` | `number` | `5000` | API timeout in milliseconds |
+
+### **Configuration Files**
+
+#### **package.json**
+```json
+{
+  "config": {
+    "library": {
+      "enabled": true,
+      "options": {
+        "feature1": true,
+        "feature2": false
+      }
+    }
+  }
+}
+```
+
+#### **Config File (.libraryrc)**
+```yaml
+core:
+  name: "my-app"
+  debug: false
+  env: "production"
+
+features:
+  experimental: false
+  beta: true
+
+performance:
+  timeout: 10000
+  retries: 3
+  cache: true
+```
+
+---
+
+## 🔄 **Lifecycle & Events**
+
+### **Event Types**
+
+```typescript
+interface EventMap {
+  'init': InitEvent;
+  'ready': ReadyEvent;
+  'error': ErrorEvent;
+  'complete': CompleteEvent;
+}
+
+interface InitEvent {
+  timestamp: Date;
+  config: Configuration;
+}
+
+interface ErrorEvent {
+  error: Error;
+  context: string;
+  recoverable: boolean;
+}
+```
+
+### **Event Handling**
+
+```typescript
+import { EventEmitter } from '@library/module';
+
+const emitter = new EventEmitter();
+
+// Listen to events
+emitter.on('init', (event: InitEvent) => {
+  console.log('Initialized at:', event.timestamp);
+});
+
+emitter.on('error', (event: ErrorEvent) => {
+  if (event.recoverable) {
+    // Handle recoverable error
+  } else {
+    // Handle fatal error
+  }
+});
+```
+
+---
+
+## 🚨 **Error Handling**
+
+### **Error Types**
+
+```typescript
+class ValidationError extends Error {
+  constructor(field: string, value: unknown) {
+    super(`Invalid value for ${field}: ${value}`);
+    this.name = 'ValidationError';
+  }
+}
+
+class TimeoutError extends Error {
+  constructor(operation: string, timeout: number) {
+    super(`Operation ${operation} timed out after ${timeout}ms`);
+    this.name = 'TimeoutError';
+  }
+}
+
+class ConfigurationError extends Error {
+  constructor(message: string) {
+    super(`Configuration error: ${message}`);
+    this.name = 'ConfigurationError';
+  }
+}
+```
+
+### **Error Codes**
+
+| Code | Error | Description | Resolution |
+|------|-------|-------------|------------|
+| `E001` | `ValidationError` | Invalid input parameter | Check parameter types and values |
+| `E002` | `TimeoutError` | Operation timed out | Increase timeout or check network |
+| `E003` | `ConfigurationError` | Invalid configuration | Review configuration schema |
+| `E004` | `AuthenticationError` | Authentication failed | Check credentials |
+
+---
+
+## 📊 **TypeScript Types**
+
+### **Core Types**
+
+```typescript
+// Main interfaces
+export interface MainInterface {
+  id: string;
+  name: string;
+  config: ConfigObject;
+  status: Status;
+}
+
+// Utility types
+export type Status = 'idle' | 'loading' | 'success' | 'error';
+export type ConfigObject = Record<string, unknown>;
+
+// Generic types
+export interface ApiResponse<T> {
+  data: T;
+  status: number;
+  message: string;
+}
+
+// Function types
+export type AsyncFunction<T, R> = (input: T) => Promise<R>;
+export type EventHandler<T> = (event: T) => void;
+```
+
+### **Advanced Types**
+
+```typescript
+// Conditional types
+export type ConditionalType<T> = T extends string ? StringHandler : NumberHandler;
+
+// Mapped types
+export type PartialConfig<T> = {
+  [K in keyof T]?: T[K];
+};
+
+// Template literal types
+export type EventName<T extends string> = `on${Capitalize<T>}`;
+```
+
+---
+
+## 🔧 **Migration Guides**
+
+### **Version 2.0 → 3.0**
+
+#### **Breaking Changes**
+- `oldFunction()` → `newFunction()` - Parameter order changed
+- `ConfigInterface` → `NewConfigInterface` - Added required field
+
+#### **Migration Steps**
+1. **Update function calls:**
+   ```typescript
+   // Before
+   oldFunction(param1, param2);
+   
+   // After  
+   newFunction({ param1, param2 });
+   ```
+
+2. **Update configuration:**
+   ```typescript
+   // Before
+   const config: ConfigInterface = {
+     setting: true
+   };
+   
+   // After
+   const config: NewConfigInterface = {
+     setting: true,
+     newRequired: 'value'
+   };
+   ```
+
+### **Deprecation Notices**
+
+| Feature | Deprecated In | Removed In | Alternative |
+|---------|---------------|------------|-------------|
+| `oldFunction` | v2.5.0 | v3.0.0 | Use `newFunction` |
+| `legacy.config` | v2.8.0 | v3.0.0 | Use `modern.config` |
+
+---
+
+## 🧪 **Testing**
+
+### **Test Utilities**
+
+```typescript
+import { createTestInstance, mockConfig } from '@library/testing';
+
+describe('Library Tests', () => {
+  it('should work with mock config', async () => {
+    const instance = createTestInstance(mockConfig);
+    const result = await instance.process('test');
+    expect(result).toBeDefined();
+  });
+});
+```
+
+### **Mock Examples**
+
+```typescript
+// Mock implementation
+const mockLibrary = {
+  process: jest.fn().mockResolvedValue('mocked result'),
+  configure: jest.fn(),
+};
+
+// Test with mock
+jest.mock('@library/module', () => mockLibrary);
+```
+
+---
+
+## 🔗 **Related Documentation**
+
+### **Core Documentation**
+- [Getting Started Guide](../02-quick-start.md)
+- [Configuration Guide](../52-configuration.md)
+- [Troubleshooting](../42-troubleshooting.md)
+
+### **Advanced Topics**
+- [Custom Plugins](./advanced/plugins.md)
+- [Performance Optimization](./advanced/performance.md)
+- [Security Considerations](./advanced/security.md)
+
+### **External Resources**
+- [Official Documentation](https://external-docs.com)
+- [Community Examples](https://github.com/community/examples)
+- [Blog Posts & Tutorials](https://blog.library.com)
+
+---
+
+## 📈 **Performance Considerations**
+
+### **Best Practices**
+- ✅ **Cache frequently used data**
+- ✅ **Use async/await for I/O operations** 
+- ✅ **Implement proper error boundaries**
+- ❌ **Don't block the event loop**
+- ❌ **Avoid synchronous file operations**
+
+### **Benchmarks**
+
+| Operation | Time (avg) | Memory | Notes |
+|-----------|------------|--------|-------|
+| Simple query | ~50ms | 10MB | Typical usage |
+| Complex operation | ~200ms | 50MB | Heavy computation |
+| Batch processing | ~500ms | 100MB | 1000 items |
+
+---
+
+**📅 Created:** [Date]  
+**👤 Maintainer:** [Name and contact]  
+**🔄 Last Updated:** [Date]  
+**📋 Version:** [Version]  
+**🔗 Changelog:** [Link to changelog]