@cortex-context/cli 0.0.5

package/dist/templates/skills/cortex-ingest/SKILL.md

@@ -0,0 +1,178 @@
+---
+name: cortex-ingest
+description: >
+  Skill de operações de manutenção do Cortex: health check, contagem de nós,
+  re-ingestão de dados e diagnóstico do grafo. Use quando o usuário quiser
+  verificar se o Cortex está saudável, forçar re-ingestão, ver quantos nós
+  existem, ou diagnosticar ingestão desatualizada.
+  Triggers: "re-ingerir cortex", "atualizar grafo cortex", "cortex health",
+  "quantos nós no cortex", "ingestão desatualizada", "forçar ingest",
+  "cortex está atualizado", "cortex out of date", "re-ingest cortex",
+  "refresh cortex", "rebuild cortex graph".
+---
+
+# Skill: Cortex Ingest — Operações e Manutenção
+
+## Propósito
+
+Verificar a saúde do Cortex, auditar contagens de nós, e forçar re-ingestão
+quando o grafo estiver desatualizado (após adicionar/remover specs, services,
+ou workflows do codebase).
+
+> **Configuração**: `CORTEX_URL` e `CORTEX_API_TOKEN` são definidos em
+> `.env` no diretório `mcp-servers/cortex/` do seu workspace.
+
+---
+
+## Quando Usar
+
+| Situação | Ação |
+|----------|------|
+| Verificar se Cortex está online | Health check |
+| Auditar contagem de nós por dimensão | `list_dimensions()` |
+| Grafo desatualizado após commits | Trigger re-ingest via curl |
+| Specs novas não aparecem no grafo | Re-ingest `spec` + verificar |
+| Novo Temporal Workflow não está no grafo | Re-ingest `temporal_workflow` |
+
+---
+
+## 1. Health Check
+
+Verifica se o Cortex está acessível e com Neo4j conectado.
+
+```bash
+curl -s "${CORTEX_URL}/health" \
+  -H "Authorization: Bearer $CORTEX_API_TOKEN"
+```
+
+Resposta esperada:
+```json
+{
+  "status": "healthy",
+  "neo4j": "connected",
+  "version": "1.1.0"
+}
+```
+
+Se `status != "healthy"` ou `neo4j != "connected"`, verificar os containers:
+
+```bash
+# Ver status dos containers
+docker compose -f /opt/cortex/docker-compose.yml ps
+
+# Ver logs do Cortex
+docker compose -f /opt/cortex/docker-compose.yml logs --tail=50 cortex
+
+# Reiniciar se parado
+docker compose -f /opt/cortex/docker-compose.yml up -d
+```
+
+> **Nota**: Se o Cortex está rodando em um host remoto, conecte via SSH antes de
+> executar os comandos acima. Consulte a documentação de deploy do seu ambiente.
+
+---
+
+## 2. Auditar Contagens via MCP
+
+Use `list_dimensions()` para ver o estado atual do grafo:
+
+```
+Tool: list_dimensions()
+```
+
+Resposta exemplo:
+```
+| dim_key           | node_label        | nós |
+|-------------------|------------------|-----|
+| spec              | Spec             | 45  |
+| service           | Service          | 5   |
+| temporal_workflow | TemporalWorkflow | 8   |
+```
+
+Se as contagens estiverem muito abaixo do esperado → grafo desatualizado → re-ingest.
+
+---
+
+## 3. Re-ingestão Manual
+
+### Via GitHub Actions (preferido)
+
+O workflow `.github/workflows/cortex-ingest.yml` é acionado automaticamente em:
+- Push para `develop`, `staging`, `main` nos repos com specs/services/workflows
+
+Para acionar manualmente:
+```bash
+gh workflow run cortex-ingest.yml \
+  --repo <seu-workspace-repo> \
+  --field dim_key=spec
+
+gh workflow run cortex-ingest.yml \
+  --repo <seu-workspace-repo> \
+  --field dim_key=service
+```
+
+### Via curl direto (quando GH Actions não é viável)
+
+O endpoint `POST /api/v1/ingest/{dim_key}` aciona a re-ingestão buscando os dados
+automaticamente das fontes configuradas (GitHub API, filesystem):
+
+```bash
+# Re-ingerir specs
+curl -X POST "${CORTEX_URL}/api/v1/ingest/spec" \
+  -H "Authorization: Bearer $CORTEX_API_TOKEN"
+
+# Re-ingerir services
+curl -X POST "${CORTEX_URL}/api/v1/ingest/service" \
+  -H "Authorization: Bearer $CORTEX_API_TOKEN"
+
+# Re-ingerir temporal workflows (se configurado)
+curl -X POST "${CORTEX_URL}/api/v1/ingest/temporal_workflow" \
+  -H "Authorization: Bearer $CORTEX_API_TOKEN"
+```
+
+> **Nota**: O body do POST é opcional — o servidor busca os dados automaticamente
+> conforme configurado em `cortex.config.yaml`.
+
+---
+
+## 4. Diagnóstico de Ingestão
+
+### Sintoma: spec nova não aparece na busca
+
+1. Verifique se o push foi para `develop`, `staging` ou `main` (outros branches não acionam)
+2. Verifique o status do workflow: `gh run list --workflow=cortex-ingest.yml`
+3. Se o workflow falhou, veja o log: `gh run view <run-id> --log`
+4. Se o workflow não foi acionado: acione manualmente (comando acima)
+
+### Sintoma: `list_dimensions` retorna dimensão com 0 nós
+
+1. Verifique se a dimensão está configurada em `cortex.config.yaml`
+2. Force re-ingestão via curl (seção 3)
+3. Verifique os logs do Cortex para erros de parsing/ingestão
+
+### Sintoma: Cortex retorna 503 ou 502
+
+1. Verifique se os containers estão rodando: `docker compose ps`
+2. Verifique Neo4j: `docker compose logs neo4j --tail=50`
+3. Verifique memória disponível: `docker stats`
+
+---
+
+## 5. Verificar API Token
+
+Se as chamadas retornam 401:
+1. Verifique `CORTEX_API_TOKEN` no `.env` do workspace: `cat mcp-servers/cortex/.env`
+2. Verifique se o token está correto no servidor: consulte sua configuração de deploy
+
+---
+
+## Referência Rápida
+
+| Ação | Comando |
+|------|---------|
+| Health check | `curl -s "${CORTEX_URL}/health"` |
+| Contar nós | MCP `list_dimensions()` |
+| Re-ingest specs | `gh workflow run cortex-ingest.yml --field dim_key=spec` |
+| Re-ingest services | `gh workflow run cortex-ingest.yml --field dim_key=service` |
+| Status Docker | `docker compose -f /opt/cortex/docker-compose.yml ps` |
+| Logs Docker | `docker compose -f /opt/cortex/docker-compose.yml logs --tail=100 cortex` |

package/dist/templates/skills/cortex-research/SKILL.md

@@ -0,0 +1,168 @@
+---
+name: cortex-research
+description: >
+  Skill de pesquisa no grafo de produto (Cortex). Use quando o usuário perguntar
+  sobre features existentes, specs, o que está implementado, o que afeta um serviço,
+  contexto de produto, histórico de decisões, ou antes de implementar qualquer
+  funcionalidade nova. Triggers: "quais features", "o que é a spec-NNN",
+  "pesquisar produto", "contexto do produto", "o que afeta o serviço", "specs existentes",
+  "quais repos são afetados", "features relacionadas a X", "já existe algo para Y".
+---
+
+# Skill: Cortex Research — Pesquisa de Produto
+
+## Propósito
+
+Consultar o **Cortex Product Knowledge Graph** para entender o produto antes de implementar
+features, planejar mudanças, ou responder perguntas sobre o que existe no sistema.
+
+**Regra obrigatória (Copilot Instructions, Regra 7)**: antes de planejar ou implementar
+qualquer feature, use esta skill para verificar specs existentes relacionadas.
+
+---
+
+## Quando Usar
+
+| Situação | Tool a chamar |
+|----------|---------------|
+| "O que existe para pagamentos?" | `query_product_context(keywords=["pagamento"])` |
+| "Quais features estão em andamento?" | `list_features(status="in-progress")` |
+| "Me fale sobre a spec-070" | `get_spec_context(spec_id="spec-070")` |
+| "Quais features afetam o BFF?" | `get_service_context(service_id="service-bff")` |
+| "Preciso implementar X, já existe?" | `query_product_context(keywords=["X"])` |
+| Visão geral do backlog | `list_features()` |
+
+---
+
+## Tools MCP Disponíveis
+
+### 1. `query_product_context` — Busca semântica por keywords
+
+Use para busca aberta quando não sabe o ID exato da spec.
+
+```
+Parâmetros:
+  keywords: list[str]  # ex: ["rateio", "pagamento", "pix"]
+  limit: int           # padrão 8, máximo 15
+
+Retorna: subgrafo ~500 tokens com specs relevantes + relações + repos afetados
+```
+
+**Quando usar**: primeiro passo em qualquer pesquisa de produto. Ideal para entender
+o contexto antes de planejar uma feature.
+
+**Exemplos de chamadas:**
+- `query_product_context(keywords=["auth", "google", "oauth"])` — specs de autenticação
+- `query_product_context(keywords=["notificacao", "push", "whatsapp"])` — specs de notificações
+- `query_product_context(keywords=["temporal", "workflow", "job"])` — specs de orquestração
+- `query_product_context(keywords=["rateio", "divisao", "financeiro"])` — specs financeiras
+
+---
+
+### 2. `list_features` — Lista specs por status
+
+Use para visão geral do produto ou backlog.
+
+```
+Parâmetros:
+  status?: "completed" | "in-progress" | "planned" | "todo"
+
+Retorna: lista agrupada por status com ID, título, repos
+```
+
+**Quando usar**: visão geral antes de propor uma nova feature, verificar se algo está
+em andamento antes de começar.
+
+---
+
+### 3. `get_spec_context` — Detalhe de uma spec específica
+
+Use quando souber o ID da spec (spec-NNN).
+
+```
+Parâmetros:
+  spec_id: str  # ex: "spec-070", "070" (normalizado automaticamente)
+
+Retorna: título, status, repos afetados, labels, summary, specs relacionadas (1-hop)
+```
+
+**Quando usar**: entender os detalhes e dependências de uma feature específica.
+
+---
+
+### 4. `get_service_context` — Specs que afetam um serviço
+
+Use para entender o impacto de features em um serviço específico.
+
+```
+Parâmetros:
+  service_id: str  # ex: "service-bff", "bff" (normalizado automaticamente)
+
+IDs disponíveis:
+  service-backend, service-bff, service-webview, service-admin,
+  service-android, service-ios, service-lambda, service-landing, service-cortex
+
+Retorna: stack, capabilities, porta/URL + todas as specs AFFECTS agrupadas por status
+```
+
+**Quando usar**: antes de implementar algo em um serviço, verificar quais features
+já tocam aquele serviço e podem criar conflito ou dependência.
+
+---
+
+## Fluxo Recomendado: Pesquisa Antes de Implementar
+
+```
+1. query_product_context(keywords=[tema, subtema])
+   → Entende o panorama das specs relacionadas
+
+2. get_service_context(service_id="service-X")  # se mudar um serviço específico
+   → Vê todas as specs que já afetam o serviço
+
+3. get_spec_context(spec_id="spec-NNN")  # para specs relevantes encontradas
+   → Lê os detalhes e dependências da spec
+
+4. list_features(status="in-progress")  # se quiser ver o que está ativo
+   → Evita criar conflito com trabalho em andamento
+```
+
+---
+
+## Encadeamento de Chamadas
+
+**Cenário: "Quero implementar autenticação com Apple Sign-In"**
+
+```
+1. query_product_context(keywords=["auth", "apple", "ios"])
+   → Encontra spec-058 (Apple Auth iOS), spec-068 (Social Auth Unification)
+
+2. get_spec_context(spec_id="spec-058")
+   → Vê que afeta service-ios, service-backend, service-webview
+
+3. get_service_context(service_id="service-backend")
+   → Confirma que spec-058 já existe e está "completed"
+   → Vê outras specs relacionadas ao backend
+
+→ Conclusão: Apple Auth já existe, implementar apenas se for extensão
+```
+
+**Cenário: "Qual o status do rateio por itens?"**
+
+```
+1. query_product_context(keywords=["rateio", "itens", "divisao"])
+   → Encontra spec-035, spec-040, spec-050
+
+2. get_spec_context(spec_id="spec-035")
+   → Status: completed, repos: [backend, bff, webview]
+```
+
+---
+
+## Output Format
+
+Quando apresentar resultados ao usuário:
+- Destaque o **ID + título** de cada spec encontrada
+- Mostre o **status** com ícones (✅ completed, 🚧 in-progress, 📋 planned, ⬜ todo)
+- Liste os **repos afetados** para o usuário saber onde implementar
+- Se encontrar specs relacionadas, **explique as dependências**
+- Termine com uma **recomendação** (implementar / estender / já existe)

package/package.json

@@ -0,0 +1,60 @@
+{
+  "name": "@cortex-context/cli",
+  "version": "0.0.5",
+  "description": "CLI to initialize and manage Cortex Context (Knowledge Graph) in any VS Code workspace",
+  "bin": {
+    "cortex-context": "./dist/index.js"
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "start": "node dist/index.js",
+    "lint": "eslint src --ext .ts",
+    "type-check": "tsc --noEmit",
+    "test": "vitest run --passWithNoTests",
+    "test:watch": "vitest",
+    "prepublishOnly": "npm run build"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.12.0",
+    "commander": "^12.1.0",
+    "prompts": "^2.4.2",
+    "chalk": "^5.3.0",
+    "ora": "^8.1.1",
+    "fs-extra": "^11.2.0",
+    "semver": "^7.6.3"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "@types/prompts": "^2.4.9",
+    "@types/fs-extra": "^11.0.4",
+    "@types/semver": "^7.5.8",
+    "typescript": "^5.5.0",
+    "tsup": "^8.3.0",
+    "vitest": "^2.1.0"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "keywords": [
+    "cortex",
+    "context",
+    "knowledge-graph",
+    "mcp",
+    "copilot",
+    "cli"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/rodrigoroldan/cli-cortex-context.git"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org"
+  }
+}