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

package/templates/.cursor/utils/task-manager/adapters/linear.md

@@ -0,0 +1,421 @@
+# 🟣 Linear Adapter (Stub)
+
+## 🎯 Propósito
+
+Stub documentado para implementação futura do `ITaskManager` para Linear.
+
+> ⚠️ **STUB**: Este adapter contém apenas a estrutura e documentação. A implementação completa requer desenvolvimento adicional.
+
+---
+
+## 📋 Configuração
+
+### Variáveis de Ambiente
+
+```bash
+# Obrigatória
+LINEAR_API_KEY=lin_api_xxxxx
+
+# Opcionais
+LINEAR_TEAM_ID=xxxxx-xxxxx-xxxxx  # Team padrão
+```
+
+### Obter Token
+
+1. Acesse Linear → Settings → API → Personal API Keys
+2. Clique em "Create key"
+3. Copie o token e adicione ao `.env`
+
+---
+
+## 📊 API do Linear
+
+### Endpoint
+
+```
+https://api.linear.app/graphql
+```
+
+### Autenticação
+
+```bash
+Authorization: Bearer {LINEAR_API_KEY}
+Content-Type: application/json
+```
+
+---
+
+## 🔧 Implementação (Stub)
+
+```typescript
+/**
+ * Adapter Linear implementando ITaskManager.
+ * 
+ * ⚠️ STUB: Métodos retornam notImplemented() por padrão.
+ * Para implementação completa, usar Linear GraphQL API.
+ */
+class LinearAdapter implements ITaskManager {
+  readonly provider: TaskManagerProvider = 'linear';
+  readonly isConfigured: boolean;
+  
+  private apiKey: string;
+  private teamId?: string;
+  
+  constructor(config: LinearAdapterConfig) {
+    this.apiKey = config.apiKey;
+    this.teamId = config.teamId;
+    this.isConfigured = !!this.apiKey;
+  }
+  
+  // ═══════════════════════════════════════════════════════════════════════════
+  // CRUD DE TASKS (ISSUES)
+  // ═══════════════════════════════════════════════════════════════════════════
+  
+  async createTask(input: CreateTaskInput): Promise<TaskOutput> {
+    return this.notImplemented('createTask');
+    
+    // TODO: Implementar usando GraphQL mutation
+    // mutation IssueCreate($input: IssueCreateInput!) {
+    //   issueCreate(input: $input) {
+    //     success
+    //     issue {
+    //       id
+    //       identifier
+    //       title
+    //       url
+    //     }
+    //   }
+    // }
+  }
+  
+  async getTask(taskId: string): Promise<TaskOutput> {
+    return this.notImplemented('getTask');
+    
+    // TODO: Implementar usando GraphQL query
+    // query Issue($id: String!) {
+    //   issue(id: $id) {
+    //     id
+    //     identifier
+    //     title
+    //     description
+    //     state { name }
+    //     priority
+    //     url
+    //   }
+    // }
+  }
+  
+  async updateTask(taskId: string, updates: UpdateTaskInput): Promise<TaskOutput> {
+    return this.notImplemented('updateTask');
+    
+    // TODO: Implementar usando GraphQL mutation
+    // mutation IssueUpdate($id: String!, $input: IssueUpdateInput!) {
+    //   issueUpdate(id: $id, input: $input) {
+    //     success
+    //     issue { id title }
+    //   }
+    // }
+  }
+  
+  async deleteTask(taskId: string): Promise<boolean> {
+    console.warn('⚠️ Linear.deleteTask() não implementado');
+    return false;
+    
+    // TODO: Linear usa archive ao invés de delete
+    // mutation IssueArchive($id: String!) {
+    //   issueArchive(id: $id) { success }
+    // }
+  }
+  
+  // ═══════════════════════════════════════════════════════════════════════════
+  // SUBTASKS (SUB-ISSUES)
+  // ═══════════════════════════════════════════════════════════════════════════
+  
+  async createSubtask(parentId: string, input: CreateTaskInput): Promise<TaskOutput> {
+    return this.notImplemented('createSubtask');
+    
+    // TODO: Usar parentId no mutation
+    // mutation IssueCreate($input: IssueCreateInput!) {
+    //   issueCreate(input: { ...input, parentId: $parentId }) { ... }
+    // }
+  }
+  
+  async getSubtasks(parentId: string): Promise<TaskOutput[]> {
+    console.warn('⚠️ Linear.getSubtasks() não implementado');
+    return [];
+    
+    // TODO: Query children
+    // query Issue($id: String!) {
+    //   issue(id: $id) {
+    //     children { nodes { id title } }
+    //   }
+    // }
+  }
+  
+  // ═══════════════════════════════════════════════════════════════════════════
+  // COMENTÁRIOS
+  // ═══════════════════════════════════════════════════════════════════════════
+  
+  async addComment(taskId: string, comment: string): Promise<CommentOutput> {
+    return this.notImplemented('addComment');
+    
+    // TODO: Mutation CommentCreate
+    // mutation CommentCreate($input: CommentCreateInput!) {
+    //   commentCreate(input: { issueId: $taskId, body: $comment }) {
+    //     success
+    //     comment { id body }
+    //   }
+    // }
+  }
+  
+  async getComments(taskId: string): Promise<CommentOutput[]> {
+    console.warn('⚠️ Linear.getComments() não implementado');
+    return [];
+    
+    // TODO: Query comments
+    // query Issue($id: String!) {
+    //   issue(id: $id) {
+    //     comments { nodes { id body user { name } } }
+    //   }
+    // }
+  }
+  
+  // ═══════════════════════════════════════════════════════════════════════════
+  // STATUS
+  // ═══════════════════════════════════════════════════════════════════════════
+  
+  async updateStatus(taskId: string, status: TaskStatus): Promise<TaskOutput> {
+    return this.notImplemented('updateStatus');
+    
+    // TODO: Mapear status para stateId do Linear
+    // mutation IssueUpdate($id: String!, $input: IssueUpdateInput!) {
+    //   issueUpdate(id: $id, input: { stateId: $stateId }) { ... }
+    // }
+  }
+  
+  // ═══════════════════════════════════════════════════════════════════════════
+  // BUSCA
+  // ═══════════════════════════════════════════════════════════════════════════
+  
+  async searchTasks(query: SearchQuery): Promise<TaskOutput[]> {
+    console.warn('⚠️ Linear.searchTasks() não implementado');
+    return [];
+    
+    // TODO: Query issues com filtro
+    // query Issues($filter: IssueFilter) {
+    //   issues(filter: $filter) {
+    //     nodes { id identifier title }
+    //   }
+    // }
+  }
+  
+  // ═══════════════════════════════════════════════════════════════════════════
+  // PROJETOS (TEAMS/PROJECTS)
+  // ═══════════════════════════════════════════════════════════════════════════
+  
+  async getProjectList(): Promise<ProjectOutput[]> {
+    console.warn('⚠️ Linear.getProjectList() não implementado');
+    return [];
+    
+    // TODO: Query teams ou projects
+    // query Teams {
+    //   teams { nodes { id name } }
+    // }
+  }
+  
+  async getProject(projectId: string): Promise<ProjectOutput> {
+    return this.notImplemented('getProject');
+    
+    // TODO: Query team ou project
+    // query Team($id: String!) {
+    //   team(id: $id) { id name description }
+    // }
+  }
+  
+  // ═══════════════════════════════════════════════════════════════════════════
+  // VALIDAÇÃO
+  // ═══════════════════════════════════════════════════════════════════════════
+  
+  validateTaskId(taskId: string): boolean {
+    // Linear IDs: 
+    // - Identifier format: ABC-123
+    // - UUID format: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
+    return /^[A-Z]+-\d+$/.test(taskId) || 
+           /^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$/i.test(taskId);
+  }
+  
+  getProviderFromTaskId(taskId: string): TaskManagerProvider | null {
+    return this.validateTaskId(taskId) ? 'linear' : null;
+  }
+  
+  // ═══════════════════════════════════════════════════════════════════════════
+  // HELPERS
+  // ═══════════════════════════════════════════════════════════════════════════
+  
+  private notImplemented(method: string): never {
+    throw new Error(
+      `❌ Linear.${method}() não implementado.\n` +
+      `💡 Este é um adapter STUB. Para implementação completa:\n` +
+      `   1. Consulte a documentação: https://developers.linear.app/\n` +
+      `   2. Implemente o método usando GraphQL API\n` +
+      `   3. Teste com sua conta Linear`
+    );
+  }
+  
+  /**
+   * Helper para fazer requisições GraphQL ao Linear.
+   * Use este método ao implementar os métodos acima.
+   */
+  private async graphql<T>(query: string, variables?: Record<string, any>): Promise<T> {
+    const response = await fetch('https://api.linear.app/graphql', {
+      method: 'POST',
+      headers: {
+        'Authorization': `Bearer ${this.apiKey}`,
+        'Content-Type': 'application/json'
+      },
+      body: JSON.stringify({ query, variables })
+    });
+    
+    if (!response.ok) {
+      throw new Error(`Linear API error: ${response.statusText}`);
+    }
+    
+    const result = await response.json();
+    
+    if (result.errors) {
+      throw new Error(`Linear GraphQL error: ${result.errors[0].message}`);
+    }
+    
+    return result.data;
+  }
+}
+```
+
+---
+
+## 📊 Mapeamento de Conceitos
+
+| Interface | Linear |
+|-----------|--------|
+| `project` | Team ou Project |
+| `task` | Issue |
+| `subtask` | Sub-issue (child) |
+| `status` | State (workflow) |
+| `comment` | Comment |
+
+---
+
+## 🔄 Status Mapping (Exemplo)
+
+| Interface | Linear State |
+|-----------|--------------|
+| `backlog` | Backlog |
+| `todo` | Todo |
+| `in_progress` | In Progress |
+| `review` | In Review |
+| `done` | Done |
+| `canceled` | Canceled |
+
+> ⚠️ Os estados do Linear são customizáveis por team. O mapeamento real depende da configuração do workspace.
+
+---
+
+## 📚 Referências para Implementação
+
+### GraphQL Queries Úteis
+
+#### Listar Issues
+
+```graphql
+query Issues($teamId: String!, $first: Int) {
+  team(id: $teamId) {
+    issues(first: $first) {
+      nodes {
+        id
+        identifier
+        title
+        description
+        state { name color }
+        priority
+        url
+        createdAt
+        updatedAt
+      }
+    }
+  }
+}
+```
+
+#### Criar Issue
+
+```graphql
+mutation IssueCreate($input: IssueCreateInput!) {
+  issueCreate(input: $input) {
+    success
+    issue {
+      id
+      identifier
+      title
+      url
+    }
+  }
+}
+```
+
+#### Atualizar Issue
+
+```graphql
+mutation IssueUpdate($id: String!, $input: IssueUpdateInput!) {
+  issueUpdate(id: $id, input: $input) {
+    success
+    issue {
+      id
+      title
+      state { name }
+    }
+  }
+}
+```
+
+---
+
+## 🚀 Como Implementar
+
+1. **Configurar ambiente**
+   ```bash
+   LINEAR_API_KEY=lin_api_xxxxx
+   LINEAR_TEAM_ID=xxxxx
+   ```
+
+2. **Testar conexão**
+   ```typescript
+   const adapter = new LinearAdapter({ apiKey: process.env.LINEAR_API_KEY });
+   const teams = await adapter.graphql(`query { teams { nodes { id name } } }`);
+   ```
+
+3. **Implementar métodos**
+   - Começar por `createTask` e `getTask`
+   - Adicionar `updateTask` e `updateStatus`
+   - Implementar `addComment` e `getComments`
+   - Por último, `searchTasks` e `getProjectList`
+
+4. **Testar com comandos**
+   ```bash
+   TASK_MANAGER_PROVIDER=linear
+   ```
+
+---
+
+## 📚 Referências
+
+- [Linear API Docs](https://developers.linear.app/)
+- [Linear GraphQL Explorer](https://linear.app/graphql)
+- [Interface ITaskManager](../interface.md)
+- [Types](../types.md)
+
+---
+
+**Versão**: 1.0.0 (Stub)
+**Criado em**: 2025-11-24
+**Status**: 📝 Documentado, aguardando implementação
+

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

@@ -0,0 +1,290 @@
+# 🔍 Detector de Provedor - Task Manager
+
+## 🎯 Propósito
+
+Detecta e valida o provedor de gerenciamento de tarefas configurado, além de identificar a origem de IDs de tasks para garantir compatibilidade.
+
+---
+
+## 📋 Funções Principais
+
+### detectProvider()
+
+```typescript
+/**
+ * Detecta o provedor configurado via variáveis de ambiente.
+ * @returns Configuração do provedor ativo
+ */
+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 não configurado. Execute /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 não configurado. Execute /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 não configurado. Execute /meta/setup-integration'
+        : undefined
+    },
+    
+    none: {
+      provider: 'none',
+      isConfigured: true,  // Sempre "configurado" pois é o fallback
+      requiredEnvVars: [],
+      optionalEnvVars: [],
+      errorMessage: undefined
+    }
+  };
+  
+  return configs[provider] || configs.none;
+}
+```
+
+---
+
+### detectProviderFromTaskId()
+
+```typescript
+/**
+ * Detecta o provedor de origem baseado no formato do ID da task.
+ * @param taskId - ID da task a analisar
+ * @returns Provedor detectado ou null se formato desconhecido
+ */
+function detectProviderFromTaskId(taskId: string): TaskManagerProvider | null {
+  if (!taskId || typeof taskId !== 'string') {
+    return null;
+  }
+  
+  const trimmedId = taskId.trim();
+  
+  // ═══════════════════════════════════════════════════════════════════════════
+  // CLICKUP
+  // Formato: alfanumérico, 9 caracteres (ex: 86adfe9eb, abc123def)
+  // ═══════════════════════════════════════════════════════════════════════════
+  if (/^[a-z0-9]{9}$/i.test(trimmedId)) {
+    return 'clickup';
+  }
+  
+  // ═══════════════════════════════════════════════════════════════════════════
+  // ASANA
+  // Formato: numérico, 16+ dígitos (ex: 1234567890123456)
+  // ═══════════════════════════════════════════════════════════════════════════
+  if (/^\d{15,}$/.test(trimmedId)) {
+    return 'asana';
+  }
+  
+  // ═══════════════════════════════════════════════════════════════════════════
+  // LINEAR
+  // Formatos:
+  //   - Prefixo + número: 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 (gerado pelo NoProviderAdapter)
+  // Formato: local-timestamp (ex: local-1732456789012)
+  // ═══════════════════════════════════════════════════════════════════════════
+  if (/^local-\d+$/.test(trimmedId)) {
+    return 'none';
+  }
+  
+  // Formato desconhecido
+  return null;
+}
+```
+
+---
+
+### validateProviderMatch()
+
+```typescript
+/**
+ * Valida se um ID de task é compatível com o provedor configurado.
+ * @param taskId - ID da task a validar
+ * @param currentProvider - Provedor atualmente configurado
+ * @returns Resultado da validação com possível warning
+ */
+function validateProviderMatch(
+  taskId: string, 
+  currentProvider: TaskManagerProvider
+): ValidationResult {
+  const detectedProvider = detectProviderFromTaskId(taskId);
+  
+  // Formato desconhecido - assumir válido
+  if (!detectedProvider) {
+    return { 
+      valid: true, 
+      warning: null,
+      detectedProvider: null
+    };
+  }
+  
+  // Provedor 'none' aceita qualquer ID (modo offline)
+  if (currentProvider === 'none') {
+    return {
+      valid: true,
+      warning: `ℹ️ Task ID "${taskId}" detectado como ${detectedProvider}, ` +
+               `mas nenhum provedor está configurado. Operando em modo local.`,
+      detectedProvider
+    };
+  }
+  
+  // Provedores diferentes - incompatibilidade
+  if (detectedProvider !== currentProvider) {
+    return {
+      valid: false,
+      warning: `⚠️ INCOMPATIBILIDADE DETECTADA\n` +
+               `━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\n` +
+               `Task ID: "${taskId}"\n` +
+               `Provedor detectado: ${detectedProvider}\n` +
+               `Provedor configurado: ${currentProvider}\n\n` +
+               `💡 Ações sugeridas:\n` +
+               `   1. Altere TASK_MANAGER_PROVIDER para '${detectedProvider}' no .env\n` +
+               `   2. Ou limpe a sessão atual e crie uma nova task\n` +
+               `   3. Execute /meta/setup-integration para reconfigurar`,
+      detectedProvider
+    };
+  }
+  
+  // Tudo OK
+  return { 
+    valid: true, 
+    warning: null,
+    detectedProvider 
+  };
+}
+```
+
+---
+
+### checkProviderConfiguration()
+
+```typescript
+/**
+ * Verifica a configuração completa do provedor.
+ * @returns Objeto com status e mensagens
+ */
+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 = `ℹ️ Nenhum gerenciador de tarefas configurado.\n` +
+              `Comandos funcionarão em modo offline.\n` +
+              `Execute /meta/setup-integration para configurar.`;
+  } else if (!config.isConfigured) {
+    message = `❌ ${config.provider.toUpperCase()} selecionado mas não configurado.\n` +
+              `Variáveis faltando: ${missingVars.join(', ')}\n` +
+              `Execute /meta/setup-integration para configurar.`;
+  } else {
+    const optionalStatus = optionalVars
+      .map(v => `   ${v.set ? '✅' : '⚪'} ${v.name}`)
+      .join('\n');
+    
+    message = `✅ ${config.provider.toUpperCase()} configurado corretamente.\n` +
+              `Variáveis opcionais:\n${optionalStatus}`;
+  }
+  
+  return {
+    provider: config.provider,
+    isConfigured: config.isConfigured,
+    missingVars,
+    optionalVars,
+    message
+  };
+}
+```
+
+---
+
+## 📊 Tabela de Formatos de ID
+
+| Provedor | Formato | Regex | Exemplo |
+|----------|---------|-------|---------|
+| ClickUp | 9 chars alfanuméricos | `^[a-z0-9]{9}$` | `86adfe9eb` |
+| Asana | 15+ dígitos | `^\d{15,}$` | `1234567890123456` |
+| Linear (ID) | PREFIXO-NUMERO | `^[A-Z]+-\d+$` | `DEV-123` |
+| Linear (UUID) | UUID v4 | UUID regex | `a1b2c3d4-...` |
+| Local | local-timestamp | `^local-\d+$` | `local-1732456789` |
+
+---
+
+## 🧪 Exemplos de Uso
+
+```typescript
+// Detectar provedor configurado
+const config = detectProvider();
+console.log(`Provedor: ${config.provider}`);
+console.log(`Configurado: ${config.isConfigured}`);
+
+// Validar ID de task
+const taskId = '86adfe9eb';
+const currentProvider = 'asana';
+const validation = validateProviderMatch(taskId, currentProvider);
+
+if (!validation.valid) {
+  console.warn(validation.warning);
+  // Perguntar ao usuário o que fazer
+}
+
+// Verificar configuração completa
+const status = checkProviderConfiguration();
+console.log(status.message);
+```
+
+---
+
+## 📚 Referências
+
+- [Types](./types.md) - Definições de tipos
+- [Factory](./factory.md) - Criação de adapters
+
+---
+
+**Versão**: 1.0.0
+**Criado em**: 2025-11-24
+