@onion-ai/cli 1.0.0-beta.1

package/framework/utils/task-manager/detector.md

@@ -0,0 +1,299 @@
+# 🔍 Provider Detector - Task Manager
+
+## 🎯 Purpose
+
+Detects and validates the configured task management provider, and identifies the origin of task IDs to ensure compatibility.
+
+---
+
+## 📋 Main Functions
+
+### detectProvider()
+
+```typescript
+/**
+ * Detects the configured provider via environment variables.
+ * @returns Active provider configuration
+ */
+function detectProvider(): ProviderConfig {
+  const provider = (process.env.TASK_MANAGER_PROVIDER ||
+    'none') as TaskManagerProvider;
+
+  const configs: Record<TaskManagerProvider, ProviderConfig> = {
+    clickup: {
+      provider: 'clickup',
+      isConfigured: !!process.env.CLICKUP_API_TOKEN,
+      requiredEnvVars: ['CLICKUP_API_TOKEN'],
+      optionalEnvVars: ['CLICKUP_WORKSPACE_ID', 'CLICKUP_DEFAULT_LIST_ID'],
+      errorMessage: !process.env.CLICKUP_API_TOKEN
+        ? '❌ CLICKUP_API_TOKEN not configured. Run /meta/setup-integration'
+        : undefined,
+    },
+
+    asana: {
+      provider: 'asana',
+      isConfigured: !!process.env.ASANA_ACCESS_TOKEN,
+      requiredEnvVars: ['ASANA_ACCESS_TOKEN'],
+      optionalEnvVars: ['ASANA_WORKSPACE_ID', 'ASANA_DEFAULT_PROJECT_ID'],
+      errorMessage: !process.env.ASANA_ACCESS_TOKEN
+        ? '❌ ASANA_ACCESS_TOKEN not configured. Run /meta/setup-integration'
+        : undefined,
+    },
+
+    linear: {
+      provider: 'linear',
+      isConfigured: !!process.env.LINEAR_API_KEY,
+      requiredEnvVars: ['LINEAR_API_KEY'],
+      optionalEnvVars: ['LINEAR_TEAM_ID'],
+      errorMessage: !process.env.LINEAR_API_KEY
+        ? '❌ LINEAR_API_KEY not configured. Run /meta/setup-integration'
+        : undefined,
+    },
+
+    none: {
+      provider: 'none',
+      isConfigured: true, // Always "configured" as it's the fallback
+      requiredEnvVars: [],
+      optionalEnvVars: [],
+      errorMessage: undefined,
+    },
+  };
+
+  return configs[provider] || configs.none;
+}
+```
+
+---
+
+### detectProviderFromTaskId()
+
+```typescript
+/**
+ * Detects the source provider based on task ID format.
+ * @param taskId - Task ID to analyze
+ * @returns Detected provider or null if format is unknown
+ */
+function detectProviderFromTaskId(taskId: string): TaskManagerProvider | null {
+  if (!taskId || typeof taskId !== 'string') {
+    return null;
+  }
+
+  const trimmedId = taskId.trim();
+
+  // ═══════════════════════════════════════════════════════════════════════════
+  // CLICKUP
+  // Format: alphanumeric, 9 characters (e.g., 86adfe9eb, abc123def)
+  // ═══════════════════════════════════════════════════════════════════════════
+  if (/^[a-z0-9]{9}$/i.test(trimmedId)) {
+    return 'clickup';
+  }
+
+  // ═══════════════════════════════════════════════════════════════════════════
+  // ASANA
+  // Format: numeric, 16+ digits (e.g., 1234567890123456)
+  // ═══════════════════════════════════════════════════════════════════════════
+  if (/^\d{15,}$/.test(trimmedId)) {
+    return 'asana';
+  }
+
+  // ═══════════════════════════════════════════════════════════════════════════
+  // LINEAR
+  // Formats:
+  //   - Prefix + number: ABC-123, PROJ-456
+  //   - UUID: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
+  // ═══════════════════════════════════════════════════════════════════════════
+  if (/^[A-Z]+-\d+$/.test(trimmedId)) {
+    return 'linear';
+  }
+  if (
+    /^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$/i.test(
+      trimmedId,
+    )
+  ) {
+    return 'linear';
+  }
+
+  // ═══════════════════════════════════════════════════════════════════════════
+  // LOCAL (generated by NoProviderAdapter)
+  // Format: local-timestamp (e.g., local-1732456789012)
+  // ═══════════════════════════════════════════════════════════════════════════
+  if (/^local-\d+$/.test(trimmedId)) {
+    return 'none';
+  }
+
+  // Unknown format
+  return null;
+}
+```
+
+---
+
+### validateProviderMatch()
+
+```typescript
+/**
+ * Validates if a task ID is compatible with the configured provider.
+ * @param taskId - Task ID to validate
+ * @param currentProvider - Currently configured provider
+ * @returns Validation result with possible warning
+ */
+function validateProviderMatch(
+  taskId: string,
+  currentProvider: TaskManagerProvider,
+): ValidationResult {
+  const detectedProvider = detectProviderFromTaskId(taskId);
+
+  // Unknown format - assume valid
+  if (!detectedProvider) {
+    return {
+      valid: true,
+      warning: null,
+      detectedProvider: null,
+    };
+  }
+
+  // 'none' provider accepts any ID (offline mode)
+  if (currentProvider === 'none') {
+    return {
+      valid: true,
+      warning:
+        `ℹ️ Task ID "${taskId}" detected as ${detectedProvider}, ` +
+        `but no provider is configured. Operating in local mode.`,
+      detectedProvider,
+    };
+  }
+
+  // Different providers - incompatibility
+  if (detectedProvider !== currentProvider) {
+    return {
+      valid: false,
+      warning:
+        `⚠️ INCOMPATIBILITY DETECTED\n` +
+        `━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\n` +
+        `Task ID: "${taskId}"\n` +
+        `Detected provider: ${detectedProvider}\n` +
+        `Configured provider: ${currentProvider}\n\n` +
+        `💡 Suggested actions:\n` +
+        `   1. Change TASK_MANAGER_PROVIDER to '${detectedProvider}' in .env\n` +
+        `   2. Or clear the current session and create a new task\n` +
+        `   3. Run /meta/setup-integration to reconfigure`,
+      detectedProvider,
+    };
+  }
+
+  // All OK
+  return {
+    valid: true,
+    warning: null,
+    detectedProvider,
+  };
+}
+```
+
+---
+
+### checkProviderConfiguration()
+
+```typescript
+/**
+ * Checks the complete provider configuration.
+ * @returns Object with status and messages
+ */
+function checkProviderConfiguration(): {
+  provider: TaskManagerProvider;
+  isConfigured: boolean;
+  missingVars: string[];
+  optionalVars: { name: string; set: boolean }[];
+  message: string;
+} {
+  const config = detectProvider();
+
+  const missingVars = config.requiredEnvVars.filter(
+    (varName) => !process.env[varName],
+  );
+
+  const optionalVars = config.optionalEnvVars.map((varName) => ({
+    name: varName,
+    set: !!process.env[varName],
+  }));
+
+  let message: string;
+
+  if (config.provider === 'none') {
+    message =
+      `ℹ️ No task manager configured.\n` +
+      `Commands will work in offline mode.\n` +
+      `Run /meta/setup-integration to configure.`;
+  } else if (!config.isConfigured) {
+    message =
+      `❌ ${config.provider.toUpperCase()} selected but not configured.\n` +
+      `Missing variables: ${missingVars.join(', ')}\n` +
+      `Run /meta/setup-integration to configure.`;
+  } else {
+    const optionalStatus = optionalVars
+      .map((v) => `   ${v.set ? '✅' : '⚪'} ${v.name}`)
+      .join('\n');
+
+    message =
+      `✅ ${config.provider.toUpperCase()} configured correctly.\n` +
+      `Optional variables:\n${optionalStatus}`;
+  }
+
+  return {
+    provider: config.provider,
+    isConfigured: config.isConfigured,
+    missingVars,
+    optionalVars,
+    message,
+  };
+}
+```
+
+---
+
+## 📊 ID Format Table
+
+| Provider      | Format               | Regex           | Example            |
+| ------------- | -------------------- | --------------- | ------------------ |
+| ClickUp       | 9 alphanumeric chars | `^[a-z0-9]{9}$` | `86adfe9eb`        |
+| Asana         | 15+ digits           | `^\d{15,}$`     | `1234567890123456` |
+| Linear (ID)   | PREFIX-NUMBER        | `^[A-Z]+-\d+$`  | `DEV-123`          |
+| Linear (UUID) | UUID v4              | UUID regex      | `a1b2c3d4-...`     |
+| Local         | local-timestamp      | `^local-\d+$`   | `local-1732456789` |
+
+---
+
+## 🧪 Usage Examples
+
+```typescript
+// Detect configured provider
+const config = detectProvider();
+console.log(`Provider: ${config.provider}`);
+console.log(`Configured: ${config.isConfigured}`);
+
+// Validate task ID
+const taskId = '86adfe9eb';
+const currentProvider = 'asana';
+const validation = validateProviderMatch(taskId, currentProvider);
+
+if (!validation.valid) {
+  console.warn(validation.warning);
+  // Ask the user what to do
+}
+
+// Check complete configuration
+const status = checkProviderConfiguration();
+console.log(status.message);
+```
+
+---
+
+## 📚 References
+
+- [Types](./types.md) - Type definitions
+- [Factory](./factory.md) - Adapter creation
+
+---
+
+**Version**: 1.0.0
+**Created**: 2025-11-24

package/framework/utils/task-manager/factory.md

@@ -0,0 +1,363 @@
+# 🏭 Factory - Task Manager
+
+## 🎯 Propósito
+
+Fornece uma factory para instanciar o adapter correto baseado na configuração do ambiente, abstraindo a criação e permitindo uso simplificado nos comandos.
+
+---
+
+## 📋 Função Principal
+
+### getTaskManager()
+
+```typescript
+/**
+ * Retorna uma instância do TaskManager configurado.
+ * Baseado em TASK_MANAGER_PROVIDER no .env
+ * 
+ * @param options - Opções de configuração (opcional)
+ * @returns Instância do adapter apropriado
+ * 
+ * @example
+ * const tm = getTaskManager();
+ * const task = await tm.createTask({ name: 'Nova Task' });
+ */
+function getTaskManager(options?: FactoryOptions): ITaskManager {
+  const config = detectProvider();
+  
+  // Log de debug (se habilitado)
+  if (options?.debug) {
+    console.log(`[TaskManager] Provider: ${config.provider}`);
+    console.log(`[TaskManager] Configured: ${config.isConfigured}`);
+  }
+  
+  // Se não está configurado, decidir comportamento
+  if (!config.isConfigured) {
+    if (options?.throwOnMisconfigured) {
+      throw new Error(config.errorMessage || 'Provider not configured');
+    }
+    
+    // Aviso e fallback para NoProviderAdapter
+    console.warn(`⚠️ ${config.errorMessage}`);
+    console.warn(`💡 Continuando em modo offline...`);
+    return new NoProviderAdapter();
+  }
+  
+  // Instanciar adapter apropriado
+  switch (config.provider) {
+    case 'clickup':
+      return new ClickUpAdapter({
+        apiToken: process.env.CLICKUP_API_TOKEN!,
+        workspaceId: process.env.CLICKUP_WORKSPACE_ID,
+        defaultListId: process.env.CLICKUP_DEFAULT_LIST_ID
+      });
+      
+    case 'asana':
+      return new AsanaAdapter({
+        accessToken: process.env.ASANA_ACCESS_TOKEN!,
+        workspaceId: process.env.ASANA_WORKSPACE_ID,
+        defaultProjectId: process.env.ASANA_DEFAULT_PROJECT_ID
+      });
+      
+    case 'linear':
+      return new LinearAdapter({
+        apiKey: process.env.LINEAR_API_KEY!,
+        teamId: process.env.LINEAR_TEAM_ID
+      });
+      
+    case 'none':
+    default:
+      return new NoProviderAdapter();
+  }
+}
+```
+
+---
+
+## ⚙️ Tipos da Factory
+
+```typescript
+/**
+ * Opções para a factory.
+ */
+interface FactoryOptions {
+  /** Habilita logs de debug */
+  debug?: boolean;
+  
+  /** Lança erro se provedor não configurado (ao invés de fallback) */
+  throwOnMisconfigured?: boolean;
+  
+  /** Força um provedor específico (ignora .env) */
+  forceProvider?: TaskManagerProvider;
+}
+
+/**
+ * Configuração para ClickUp Adapter.
+ */
+interface ClickUpAdapterConfig {
+  apiToken: string;
+  workspaceId?: string;
+  defaultListId?: string;
+}
+
+/**
+ * Configuração para Asana Adapter.
+ */
+interface AsanaAdapterConfig {
+  accessToken: string;
+  workspaceId?: string;
+  defaultProjectId?: string;
+}
+
+/**
+ * Configuração para Linear Adapter.
+ */
+interface LinearAdapterConfig {
+  apiKey: string;
+  teamId?: string;
+}
+```
+
+---
+
+## 🔄 Funções Auxiliares
+
+### getTaskManagerOrFail()
+
+```typescript
+/**
+ * Versão da factory que lança erro se não configurado.
+ * Útil para comandos que REQUEREM um provedor.
+ * 
+ * @throws Error se provedor não configurado
+ */
+function getTaskManagerOrFail(): ITaskManager {
+  return getTaskManager({ throwOnMisconfigured: true });
+}
+```
+
+### getTaskManagerWithWarning()
+
+```typescript
+/**
+ * Versão da factory que mostra warning formatado.
+ * Útil para comandos que podem funcionar sem provedor.
+ * 
+ * @returns Adapter + flag indicando se está em modo offline
+ */
+function getTaskManagerWithWarning(): {
+  taskManager: ITaskManager;
+  isOffline: boolean;
+  warning?: string;
+} {
+  const config = detectProvider();
+  const taskManager = getTaskManager();
+  
+  if (config.provider === 'none' || !config.isConfigured) {
+    return {
+      taskManager,
+      isOffline: true,
+      warning: `⚠️ MODO OFFLINE ATIVADO
+━━━━━━━━━━━━━━━━━━━━━━━━
+Nenhum gerenciador de tarefas configurado.
+
+Funcionalidades disponíveis:
+  ✅ Criar documentos locais
+  ✅ Gerar estrutura de sessão
+  ❌ Sincronizar com ClickUp/Asana/Linear
+  ❌ Atualizar status de tasks
+
+💡 Para habilitar sincronização:
+   Execute /meta/setup-integration
+━━━━━━━━━━━━━━━━━━━━━━━━`
+    };
+  }
+  
+  return {
+    taskManager,
+    isOffline: false
+  };
+}
+```
+
+---
+
+## 📊 Classe Base NoProviderAdapter
+
+```typescript
+/**
+ * Adapter de fallback quando nenhum provedor está configurado.
+ * Permite operações locais e gera IDs locais.
+ */
+class NoProviderAdapter implements ITaskManager {
+  readonly provider: TaskManagerProvider = 'none';
+  readonly isConfigured: boolean = false;
+  
+  async createTask(input: CreateTaskInput): Promise<TaskOutput> {
+    console.warn('⚠️ Criando task LOCAL (não sincronizada)');
+    
+    const localId = `local-${Date.now()}`;
+    
+    return {
+      id: localId,
+      provider: 'none',
+      name: input.name,
+      description: input.description || '',
+      status: 'todo',
+      url: '',  // Sem URL pois é local
+      createdAt: new Date().toISOString(),
+      updatedAt: new Date().toISOString(),
+      assignees: [],
+      tags: input.tags || [],
+      dueDate: input.dueDate,
+      priority: input.priority
+    };
+  }
+  
+  async getTask(taskId: string): Promise<TaskOutput> {
+    console.warn(`⚠️ getTask('${taskId}') - Operando em modo offline`);
+    throw new Error('Operação não disponível em modo offline');
+  }
+  
+  async updateTask(taskId: string, updates: UpdateTaskInput): Promise<TaskOutput> {
+    console.warn(`⚠️ updateTask('${taskId}') - Operando em modo offline`);
+    throw new Error('Operação não disponível em modo offline');
+  }
+  
+  async deleteTask(taskId: string): Promise<boolean> {
+    console.warn(`⚠️ deleteTask('${taskId}') - Operando em modo offline`);
+    return false;
+  }
+  
+  async createSubtask(parentId: string, input: CreateTaskInput): Promise<TaskOutput> {
+    console.warn('⚠️ Criando subtask LOCAL (não sincronizada)');
+    
+    const localId = `local-${Date.now()}-sub`;
+    
+    return {
+      id: localId,
+      provider: 'none',
+      name: input.name,
+      description: input.description || '',
+      status: 'todo',
+      url: '',
+      createdAt: new Date().toISOString(),
+      updatedAt: new Date().toISOString(),
+      assignees: [],
+      tags: input.tags || [],
+      parent: parentId
+    };
+  }
+  
+  async getSubtasks(parentId: string): Promise<TaskOutput[]> {
+    console.warn(`⚠️ getSubtasks('${parentId}') - Operando em modo offline`);
+    return [];
+  }
+  
+  async addComment(taskId: string, comment: string): Promise<CommentOutput> {
+    console.warn(`⚠️ addComment('${taskId}') - Operando em modo offline`);
+    
+    return {
+      id: `local-comment-${Date.now()}`,
+      text: comment,
+      author: { id: 'local', name: 'Local User' },
+      createdAt: new Date().toISOString()
+    };
+  }
+  
+  async getComments(taskId: string): Promise<CommentOutput[]> {
+    return [];
+  }
+  
+  async updateStatus(taskId: string, status: TaskStatus): Promise<TaskOutput> {
+    console.warn(`⚠️ updateStatus('${taskId}', '${status}') - Operando em modo offline`);
+    throw new Error('Operação não disponível em modo offline');
+  }
+  
+  async searchTasks(query: SearchQuery): Promise<TaskOutput[]> {
+    console.warn('⚠️ searchTasks() - Operando em modo offline');
+    return [];
+  }
+  
+  async getProjectList(): Promise<ProjectOutput[]> {
+    return [];
+  }
+  
+  async getProject(projectId: string): Promise<ProjectOutput> {
+    throw new Error('Operação não disponível em modo offline');
+  }
+  
+  validateTaskId(taskId: string): boolean {
+    return /^local-\d+(-sub)?$/.test(taskId);
+  }
+  
+  getProviderFromTaskId(taskId: string): TaskManagerProvider | null {
+    return detectProviderFromTaskId(taskId);
+  }
+}
+```
+
+---
+
+## 🧪 Exemplos de Uso
+
+### Uso Básico
+
+```typescript
+// Obter adapter configurado
+const taskManager = getTaskManager();
+
+// Verificar se está online
+if (taskManager.isConfigured) {
+  const task = await taskManager.createTask({
+    name: 'Minha Task',
+    description: 'Descrição'
+  });
+  console.log(`✅ Task criada: ${task.url}`);
+} else {
+  console.log('⚠️ Modo offline - task não será sincronizada');
+}
+```
+
+### Uso com Validação
+
+```typescript
+// Requer provedor configurado
+try {
+  const taskManager = getTaskManagerOrFail();
+  await taskManager.updateStatus(taskId, 'done');
+} catch (error) {
+  console.error('❌ Provedor não configurado');
+  // Sugerir /meta/setup-integration
+}
+```
+
+### Uso com Warning
+
+```typescript
+// Mostrar warning se offline
+const { taskManager, isOffline, warning } = getTaskManagerWithWarning();
+
+if (isOffline) {
+  console.log(warning);
+}
+
+// Continuar com funcionalidade limitada
+const task = await taskManager.createTask({
+  name: 'Task pode ser local'
+});
+```
+
+---
+
+## 📚 Referências
+
+- [Interface ITaskManager](./interface.md)
+- [Detector](./detector.md)
+- [Adapters](./adapters/)
+
+---
+
+**Versão**: 1.0.0
+**Criado em**: 2025-11-24
+