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

package/templates/.cursor/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
+

package/templates/.cursor/utils/task-manager/interface.md

@@ -0,0 +1,248 @@
+# 📐 Interface ITaskManager
+
+## 🎯 Propósito
+
+Define o contrato que todos os adapters de gerenciadores de tarefas devem implementar, garantindo consistência e permitindo troca transparente de provedores.
+
+---
+
+## 📋 Interface Completa
+
+```typescript
+/**
+ * Interface abstrata para gerenciadores de tarefas.
+ * Todos os adapters (ClickUp, Asana, Linear) devem implementar esta interface.
+ */
+interface ITaskManager {
+  // ═══════════════════════════════════════════════════════════════════════════
+  // IDENTIFICAÇÃO
+  // ═══════════════════════════════════════════════════════════════════════════
+  
+  /**
+   * Nome do provedor: 'clickup' | 'asana' | 'linear' | 'none'
+   */
+  readonly provider: TaskManagerProvider;
+  
+  /**
+   * Indica se o provedor está configurado corretamente
+   */
+  readonly isConfigured: boolean;
+  
+  // ═══════════════════════════════════════════════════════════════════════════
+  // CRUD DE TASKS
+  // ═══════════════════════════════════════════════════════════════════════════
+  
+  /**
+   * Cria uma nova task no gerenciador.
+   * @param input - Dados da task a criar
+   * @returns Task criada com ID e URL
+   */
+  createTask(input: CreateTaskInput): Promise<TaskOutput>;
+  
+  /**
+   * Obtém detalhes de uma task existente.
+   * @param taskId - ID da task no provedor
+   * @returns Task completa com todos os detalhes
+   */
+  getTask(taskId: string): Promise<TaskOutput>;
+  
+  /**
+   * Atualiza uma task existente.
+   * @param taskId - ID da task
+   * @param updates - Campos a atualizar (parcial)
+   * @returns Task atualizada
+   */
+  updateTask(taskId: string, updates: UpdateTaskInput): Promise<TaskOutput>;
+  
+  /**
+   * Remove uma task.
+   * @param taskId - ID da task
+   * @returns true se removida com sucesso
+   */
+  deleteTask(taskId: string): Promise<boolean>;
+  
+  // ═══════════════════════════════════════════════════════════════════════════
+  // SUBTASKS
+  // ═══════════════════════════════════════════════════════════════════════════
+  
+  /**
+   * Cria uma subtask vinculada a uma task pai.
+   * @param parentId - ID da task pai
+   * @param input - Dados da subtask
+   * @returns Subtask criada
+   */
+  createSubtask(parentId: string, input: CreateTaskInput): Promise<TaskOutput>;
+  
+  /**
+   * Lista todas as subtasks de uma task.
+   * @param parentId - ID da task pai
+   * @returns Array de subtasks
+   */
+  getSubtasks(parentId: string): Promise<TaskOutput[]>;
+  
+  // ═══════════════════════════════════════════════════════════════════════════
+  // COMENTÁRIOS
+  // ═══════════════════════════════════════════════════════════════════════════
+  
+  /**
+   * Adiciona um comentário a uma task.
+   * @param taskId - ID da task
+   * @param comment - Texto do comentário
+   * @returns Comentário criado
+   */
+  addComment(taskId: string, comment: string): Promise<CommentOutput>;
+  
+  /**
+   * Lista comentários de uma task.
+   * @param taskId - ID da task
+   * @returns Array de comentários
+   */
+  getComments(taskId: string): Promise<CommentOutput[]>;
+  
+  // ═══════════════════════════════════════════════════════════════════════════
+  // STATUS
+  // ═══════════════════════════════════════════════════════════════════════════
+  
+  /**
+   * Atualiza o status de uma task.
+   * @param taskId - ID da task
+   * @param status - Novo status (mapeado internamente pelo adapter)
+   * @returns Task atualizada
+   */
+  updateStatus(taskId: string, status: TaskStatus): Promise<TaskOutput>;
+  
+  // ═══════════════════════════════════════════════════════════════════════════
+  // BUSCA
+  // ═══════════════════════════════════════════════════════════════════════════
+  
+  /**
+   * Busca tasks com filtros.
+   * @param query - Critérios de busca
+   * @returns Array de tasks que correspondem aos critérios
+   */
+  searchTasks(query: SearchQuery): Promise<TaskOutput[]>;
+  
+  // ═══════════════════════════════════════════════════════════════════════════
+  // PROJETOS/LISTAS
+  // ═══════════════════════════════════════════════════════════════════════════
+  
+  /**
+   * Lista projetos/listas disponíveis.
+   * @returns Array de projetos
+   */
+  getProjectList(): Promise<ProjectOutput[]>;
+  
+  /**
+   * Obtém detalhes de um projeto.
+   * @param projectId - ID do projeto
+   * @returns Projeto com detalhes
+   */
+  getProject(projectId: string): Promise<ProjectOutput>;
+  
+  // ═══════════════════════════════════════════════════════════════════════════
+  // VALIDAÇÃO
+  // ═══════════════════════════════════════════════════════════════════════════
+  
+  /**
+   * Valida se um ID de task é válido para este provedor.
+   * @param taskId - ID a validar
+   * @returns true se o formato é válido
+   */
+  validateTaskId(taskId: string): boolean;
+  
+  /**
+   * Detecta o provedor de origem de um ID de task.
+   * @param taskId - ID da task
+   * @returns Nome do provedor ou null se desconhecido
+   */
+  getProviderFromTaskId(taskId: string): TaskManagerProvider | null;
+}
+```
+
+---
+
+## 📊 Métodos por Categoria
+
+| Categoria | Métodos | Descrição |
+|-----------|---------|-----------|
+| **Identificação** | `provider`, `isConfigured` | Informações do adapter |
+| **CRUD Tasks** | `createTask`, `getTask`, `updateTask`, `deleteTask` | Operações básicas |
+| **Subtasks** | `createSubtask`, `getSubtasks` | Hierarquia de tasks |
+| **Comentários** | `addComment`, `getComments` | Documentação e discussão |
+| **Status** | `updateStatus` | Workflow |
+| **Busca** | `searchTasks` | Localização de tasks |
+| **Projetos** | `getProjectList`, `getProject` | Navegação |
+| **Validação** | `validateTaskId`, `getProviderFromTaskId` | Compatibilidade |
+
+---
+
+## 🔄 Mapeamento por Provedor
+
+### Status
+
+| Interface | ClickUp | Asana | Linear |
+|-----------|---------|-------|--------|
+| `backlog` | "backlog" | - | "backlog" |
+| `todo` | "to do" | - | "todo" |
+| `in_progress` | "in progress" | - | "in_progress" |
+| `done` | "done" | completed: true | "done" |
+| `closed` | "closed" | completed: true | "canceled" |
+
+### Prioridade
+
+| Interface | ClickUp | Asana | Linear |
+|-----------|---------|-------|--------|
+| `urgent` | 1 | - | 1 |
+| `high` | 2 | - | 2 |
+| `normal` | 3 | - | 3 |
+| `low` | 4 | - | 4 |
+
+---
+
+## 🧪 Exemplo de Uso
+
+```typescript
+// Obter adapter
+const taskManager = getTaskManager();
+
+// Verificar configuração
+if (!taskManager.isConfigured) {
+  console.warn('⚠️ Provedor não configurado. Execute /meta/setup-integration');
+  return;
+}
+
+// Criar task
+const task = await taskManager.createTask({
+  name: 'Implementar feature X',
+  description: 'Descrição detalhada...',
+  priority: 'high',
+  tags: ['feature', 'v2']
+});
+
+console.log(`✅ Task criada: ${task.url}`);
+
+// Criar subtask
+const subtask = await taskManager.createSubtask(task.id, {
+  name: 'Fase 1: Setup'
+});
+
+// Adicionar comentário
+await taskManager.addComment(task.id, '🚀 Desenvolvimento iniciado!');
+
+// Atualizar status
+await taskManager.updateStatus(subtask.id, 'in_progress');
+```
+
+---
+
+## 📚 Referências
+
+- [Tipos Compartilhados](./types.md)
+- [Factory](./factory.md)
+- [Adapters](./adapters/)
+
+---
+
+**Versão**: 1.0.0
+**Criado em**: 2025-11-24
+