@ds9-solutions/mcp 0.1.0 → 0.2.0

package/content/skills/dart/SKILL.md

@@ -0,0 +1,139 @@
+---
+name: dart
+description: Convenções da linguagem Dart da DS9 — orientação a objetos como abordagem padrão, nomenclatura oficial do Dart (Effective Dart), documentação com `///`, null safety, tratamento de erros, análise estática, formatação e testes. Use ao escrever ou revisar qualquer código Dart (CLI, servidor, pacote ou app Flutter), definir classes/tipos, nomear arquivos e identificadores, documentar código, ou quando o usuário pedir "boas práticas Dart", "padrão Dart", "nomenclatura Dart" ou "documentar com ///".
+---
+
+# Dart — Diretrizes DS9
+
+Convenções da **linguagem Dart**, válidas para qualquer projeto (CLI, servidor, pacote ou aplicativo). Regras específicas de Flutter (widgets, estado, UI) não fazem parte desta skill. Base: guia oficial *Effective Dart*, documentação do Dart e as skills Dart do projeto `lazy_forge` (`.agents/skills`). Em caso de dúvida sobre versão da linguagem, confirme a versão do SDK no `pubspec.yaml` antes de usar recursos novos.
+
+## 1. Orientação a objetos como padrão
+
+O código Dart da DS9 é **orientado a objetos**. Modele o domínio com classes e deixe o comportamento junto dos dados.
+
+- **Comportamento em métodos, não em funções soltas:** lógica de negócio vive em classes (entidades, serviços, casos de uso). Funções de nível superior ficam restritas a `main()` e a pequenos utilitários verdadeiramente genéricos e sem estado; mesmo estes, prefira como métodos estáticos de uma classe coesa ou como `extension`.
+- **Encapsulamento:** campos privados (`_campo`) com acesso por getters/métodos; exponha o mínimo necessário. Estado interno nunca é alterado de fora da classe.
+- **Imutabilidade por padrão:** campos `final`, construtores `const` quando possível, e novas instâncias (`copyWith`/métodos que retornam um novo objeto) em vez de mutação onde o domínio pedir.
+- **Composição sobre herança:** injete dependências pelo construtor (como `abstract interface class` ou `abstract class`) e componha objetos; use herança só para relação "é um" genuína.
+- **Polimorfismo no lugar de `if`/`switch` por tipo:** variação de comportamento vai em subclasses/implementações, não em cadeias de `is`/`switch` espalhadas. Use `sealed class` para famílias fechadas de tipos; `switch` exaustivo sobre elas é aceitável quando o comportamento não pertence ao tipo (ex.: decodificar dados externos).
+- **Contratos explícitos:** dependências externas (banco, rede, relógio) atrás de uma interface (`abstract interface class`), para troca e teste.
+
+### Evite o estilo funcional como abordagem principal
+
+Dart é multiparadigma, mas aqui o padrão é objetos. Isso **não** proíbe os recursos idiomáticos da linguagem; proíbe construir a arquitetura em torno de funções.
+
+- Evite pipelines longos e encadeados (`map().where().fold().expand()...`) que escondem regra de negócio; se passar de 2 ou 3 etapas, extraia para um método nomeado ou use um laço `for` claro.
+- Evite passar funções/closures como mecanismo principal de extensão (callbacks em cascata, funções de ordem superior como "estratégia"); prefira um objeto com método bem nomeado.
+- Evite funções que retornam funções, currying e composição de funções; evite tipos como `Function` solto (use `typedef` ou interface quando um callback for inevitável).
+- Evite `Either`/`Result` genéricos e estilos monádicos criados à mão quando exceção tipada ou um tipo de resultado `sealed` do domínio resolve de forma mais legível. **Exceção:** em projetos que seguem as skills `hex-pattern-dart`, `dart-frog` ou `flutter`, o `TaskEither` do `fpdart` (com `TaskEither.tryCatch`, `map`, `flatMap`, `mapLeft`) é o padrão obrigatório nos contratos entre camadas; ele não se estende ao domínio e aos models, que continuam orientados a objetos.
+- Aceitável e idiomático: `for` com `collection-if`/`collection-for` em literais, `map`/`where`/`toList` simples (1 a 2 etapas), `async`/`await`, callbacks exigidos por APIs de terceiros e a composição de `TaskEither` conforme essas skills.
+
+## 2. Nomenclatura (Effective Dart)
+
+| Elemento | Convenção | Exemplo |
+|---|---|---|
+| Classes, enums, mixins, extensions, typedefs, parâmetros de tipo | `UpperCamelCase` | `OrderService`, `PaymentStatus`, `T` |
+| Variáveis, parâmetros, campos, métodos, funções, getters | `lowerCamelCase` | `totalPrice`, `findById()` |
+| **Constantes** (incl. `const`/`static const`/valores de enum) | `lowerCamelCase` (**não** `SCREAMING_CAPS`) | `defaultTimeout`, `maxRetries` |
+| Pacotes, diretórios, arquivos, prefixos de import | `lowercase_with_underscores` | `order_service.dart`, `import '...' as http_client;` |
+| Membros e tipos privados da biblioteca | prefixo `_` | `_cache`, `_OrderMapper` |
+
+Regras adicionais:
+
+- **Arquivo = classe principal:** `UserRepository` fica em `user_repository.dart`. Uma classe pública principal por arquivo; testes em `<nome>_test.dart`.
+- **Siglas:** com mais de duas letras, capitalize como palavra (`HttpClient`, `JsonParser`, `UserId`); com duas letras, mantenha maiúsculas (`IOSink`).
+- **Sem prefixos/sufixos de tipo:** não use `I` para interfaces (`IUserRepository`), notação húngara, nem `k` em constantes (`kTimeout`).
+- **Booleanos** com nome afirmativo: `isEmpty`, `hasPermission`, `canRetry`; evite negações (`isNotValid`).
+- **Métodos** começam com verbo (`calculateTotal`, `save`); **getters e propriedades** são substantivos, sem prefixo `get` (`total`, não `getTotal`).
+- **Nomes descritivos:** sem abreviações obscuras nem nomes de uma letra fora de laços/lambdas curtos; o nome expressa intenção, não implementação.
+- **Variáveis não usadas:** use `_` (wildcard) em vez de nomes sem uso.
+- **Ordem em arquivos:** `dart:` → `package:` → relativos, cada grupo em ordem alfabética; prefira imports relativos dentro de `lib/` do próprio pacote, exceto quando a skill do framework definir outro padrão (a `flutter` usa `package:`).
+
+## 3. Documentação e comentários (`///`)
+
+**Regra de inclusão:** toda declaração **pública** (biblioteca, classe, enum, mixin, extension, construtor nomeado relevante, método, função, getter/setter, campo e constante) **deve** ter comentário de documentação com `///`. Declarações privadas só precisam quando a lógica não for óbvia. Código novo sem `///` nas declarações públicas é pendência de review.
+
+- Use **sempre `///`**, em linhas consecutivas; **nunca** `/** ... */`. Use `//` apenas para comentários de implementação internos, explicando o **porquê**, nunca o óbvio.
+- **Primeira linha:** uma frase única e resumida, terminada em ponto, seguida de uma linha `///` vazia antes do restante. Uma linha totalmente em branco (sem `///`) encerra o comentário.
+- **Abertura por tipo de membro:** propriedades/getters com sintagma nominal (`/// O raio da esfera.`); booleanos com "Se"/"Whether" no idioma do projeto (`/// Se a conexão está ativa.`); métodos com verbo na 3ª pessoa (`/// Inicializa o banco.`).
+- **Sem redundância:** não repita a assinatura nem o nome ("Esta classe é...", "O método foo faz...").
+- **Sem tags estilo Javadoc** (`@param`, `@return`, `@throws`): descreva parâmetros, retorno e exceções em prosa, referenciando parâmetros com `[nome]`.
+- **Links:** use colchetes para símbolos no escopo (`[Order]`, `[Order.total]`, sem parênteses); construtor sem nome como `[Order.new]`; crases para palavras-chave e literais (`` `null` ``, `` `true` ``). Blocos de código com a linguagem (` ```dart `).
+- **Posição:** o comentário `///` vem **antes** das anotações (`@override` etc.).
+- **Herança e pares getter/setter:** não duplique documentação em `@override` sem mudança de comportamento; em par getter/setter, documente só o getter.
+- **Idioma:** siga o idioma já usado no projeto, de forma consistente.
+- Valide com `dart analyze` (referências entre colchetes resolvidas) e, opcionalmente, `dart doc`.
+
+```dart
+// Evitar
+/**
+ * Busca o pedido.
+ * @param id identificador
+ * @return o pedido
+ */
+Order find(String id) { ... }
+
+// Preferir
+/// Busca o pedido pelo [id].
+///
+/// Lança [OrderNotFoundException] se não existir pedido com esse identificador.
+Order findById(String id) { ... }
+```
+
+## 4. Construtores e classes
+
+- Prefira **parâmetros iniciais** (`this.campo`) e `super.parametro` a atribuições manuais; use `required` em parâmetros nomeados obrigatórios.
+- Construtores `const` em classes imutáveis; `factory` para validação/cache e para criar a partir de dados externos (`fromJson`).
+- **Invariantes no construtor/factory:** estado inválido não pode existir; valide e lance exceção de domínio.
+- **Primary constructors** (declarar campos no cabeçalho da classe): disponíveis só a partir do Dart 3.13 (experimental no 3.12, via flag). Use **somente se o SDK do projeto suportar**; caso contrário, use construtores tradicionais. Não migre código existente apenas por isso.
+- Use `sealed`, `final`, `base` e `interface` para controlar quem pode estender ou implementar uma classe, quando a API for pública.
+
+## 5. Null safety e tipos
+
+- Nada de `dynamic` em código novo; tipos explícitos em APIs públicas, em genéricos (`List<Order>`) e em retornos.
+- Evite `!` (asserção de nulo); prefira promoção de tipo, `?.`, `??` ou tratar o nulo. `late` só quando a inicialização estiver garantida antes do uso.
+- Prefira `final` a `var` quando o valor não muda; evite `as` sem garantia do tipo em tempo de execução.
+- **Pattern matching e records** (Dart 3): use para decodificar dados externos (JSON) e `switch` exaustivo em `sealed`; não use para o que um `is` simples, um acesso a propriedade ou uma comparação booleana resolvem. Dados malformados devem falhar com erro explícito (`FormatException`), nunca ser descartados em silêncio.
+
+## 6. Tratamento de erros
+
+- Falhas recuperáveis: **`Exception` tipada do domínio** (`class OrderNotFoundException implements Exception`), nunca `throw 'texto'` nem lançar `Exception` genérica. Em projetos `hex-pattern-dart`/`dart-frog`, as falhas trafegam como `Left` de `TaskEither` com as exceções por camada definidas em `hex-pattern-dart` (em Flutter, siga a skill `flutter`) (`BusinessException`, `ClientException`, `MiddlewareException`).
+- **Nunca capture `Error`** (nem `TypeError`, `ArgumentError`, etc.): indicam bugs de programação. Capture tipos específicos; não use `catch (e)` amplo sem relançar.
+- Use `rethrow` para propagar preservando o stack trace; não engula exceções em silêncio nem registre dados sensíveis.
+- Mensagens de erro expostas a usuários não vazam detalhes internos.
+
+## 7. Assincronismo
+
+- `async`/`await` em vez de encadear `.then()`; sempre aguarde (`await`) ou trate explicitamente os `Future`s (sem "fire-and-forget" acidental).
+- Libere recursos (`close`/`cancel`/`dispose`) em `try/finally`; cancele subscriptions e controllers de `Stream`.
+- Não bloqueie o isolate principal com trabalho pesado síncrono; use isolates quando necessário.
+
+## 8. Qualidade, formatação e testes
+
+- **Análise estática:** `analysis_options.yaml` na raiz do pacote com um conjunto base (`package:lints/recommended.yaml` ou `package:flutter_lints/flutter.yaml`) e `strict-casts`, `strict-inference` e `strict-raw-types` ativos. Exclua só código gerado (`**/*.g.dart`).
+- Rode `dart analyze` e corrija os avisos; use `dart fix --apply` para correções mecânicas (revise com `--dry-run`) e `dart format .` antes de commitar. Suprima diagnósticos (`// ignore:`) só com justificativa e no menor escopo.
+- **Testes:** `package:test` (ou `flutter_test` em Flutter), arquivos em `test/` espelhando `lib/` com sufixo `_test.dart`; `group()` por funcionalidade, `setUp()`/`tearDown()` para preparo, `expect()` com matchers; dependências externas isoladas por interface/mocks. Para criar e executar testes, use o agente `test-writer`.
+
+## 9. Checklist de review
+
+- [ ] Regra de negócio está em classes, sem funções soltas nem cadeias funcionais longas?
+- [ ] Toda declaração pública tem `///` no formato da seção 3?
+- [ ] Nomes seguem a tabela da seção 2 (inclusive constantes em `lowerCamelCase` e arquivos em `snake_case`)?
+- [ ] Sem `dynamic`, `!` desnecessário ou `catch` de `Error`?
+- [ ] Campos `final`, encapsulamento e construtores `const` onde cabem?
+- [ ] `dart analyze` limpo, `dart format` aplicado e testes cobrindo o comportamento novo?
+
+## 10. Arquivos complementares
+
+Em caso de dúvida, consulte (via `list_skill_files` / `get_skill_file` com `skill="dart"`; ou direto na pasta `dart/`, se o host não tiver as tools):
+
+- `examples/` — código de referência: `entity.dart`, `repository.dart`, `error_handling.dart`, `order_test.dart`. Use quando precisar de um exemplo de entidade, contrato/caso de uso, erros ou teste.
+- `references/` — `naming.md` (nomenclatura), `documentation.md` (`///`), `checklist.md` (review detalhado).
+
+## Não fazer
+
+- Não usar `/** ... */` nem tags `@param`/`@return`/`@throws`.
+- Não usar `SCREAMING_CAPS`, prefixo `I`, `k` ou notação húngara.
+- Não criar funções de nível superior com regra de negócio nem pipelines funcionais extensos (exceto a composição de `TaskEither` exigida pelas skills `hex-pattern-dart`, `dart-frog` e `flutter`).
+- Não declarar `dynamic`, `Function` solto ou `throw` de strings.
+- Não duplicar regras de outras skills; para testes, ver o agente `test-writer`.

package/content/skills/dart/examples/entity.dart

@@ -0,0 +1,37 @@
+/// Exemplo: entidade imutável, encapsulada e documentada com `///`.
+library;
+
+/// Status possíveis de um [Order].
+enum OrderStatus {
+  /// Pedido criado e ainda não pago.
+  pending,
+
+  /// Pedido pago.
+  paid,
+}
+
+/// Pedido do domínio, com invariantes validadas na criação.
+class Order {
+  /// Cria um pedido.
+  ///
+  /// Lança [ArgumentError] se [id] estiver vazio ou [total] for negativo.
+  Order({required this.id, required this.total, this.status = OrderStatus.pending}) {
+    if (id.isEmpty) throw ArgumentError.value(id, 'id', 'não pode ser vazio');
+    if (total < 0) throw ArgumentError.value(total, 'total', 'não pode ser negativo');
+  }
+
+  /// Identificador único do pedido.
+  final String id;
+
+  /// Valor total do pedido.
+  final double total;
+
+  /// Situação atual do pedido.
+  final OrderStatus status;
+
+  /// Se o pedido já foi pago.
+  bool get isPaid => status == OrderStatus.paid;
+
+  /// Retorna uma cópia deste pedido já marcada como paga.
+  Order markAsPaid() => Order(id: id, total: total, status: OrderStatus.paid);
+}

package/content/skills/dart/examples/error_handling.dart

@@ -0,0 +1,36 @@
+/// Exemplo: exceções tipadas e tratamento sem engolir erros.
+library;
+
+/// Falha ao decodificar dados externos.
+class InvalidPayloadException implements Exception {
+  /// Cria a exceção com a [message] explicando o problema.
+  const InvalidPayloadException(this.message);
+
+  /// Descrição do problema, segura para exibir.
+  final String message;
+
+  @override
+  String toString() => 'InvalidPayloadException: $message';
+}
+
+/// Lê um valor numérico de um payload externo.
+class PayloadReader {
+  /// Lê o campo `amount` de [json].
+  ///
+  /// Lança [InvalidPayloadException] se ele não existir ou não for numérico.
+  double readAmount(Map<String, Object?> json) {
+    return switch (json['amount']) {
+      final num amount => amount.toDouble(),
+      _ => throw const InvalidPayloadException('campo "amount" ausente ou inválido'),
+    };
+  }
+
+  /// Lê o valor e propaga falhas de domínio preservando o stack trace.
+  double readOrRethrow(Map<String, Object?> json) {
+    try {
+      return readAmount(json);
+    } on InvalidPayloadException {
+      rethrow; // nunca `catch (e)` amplo nem captura de `Error`
+    }
+  }
+}

package/content/skills/dart/examples/order_test.dart

@@ -0,0 +1,34 @@
+/// Exemplo: teste unitário com `group`, `setUp` e `expect`.
+///
+/// Em um projeto real o arquivo fica em `test/`, espelhando `lib/`.
+library;
+
+import 'package:test/test.dart';
+
+import 'entity.dart';
+import 'repository.dart';
+
+void main() {
+  group('PayOrder', () {
+    late InMemoryOrderRepository repository;
+    late PayOrder useCase;
+
+    setUp(() {
+      repository = InMemoryOrderRepository();
+      useCase = PayOrder(repository);
+    });
+
+    test('marca o pedido como pago e persiste', () async {
+      await repository.save(Order(id: '1', total: 10));
+
+      final paid = await useCase.execute('1');
+
+      expect(paid.isPaid, isTrue);
+      expect((await repository.findById('1'))!.isPaid, isTrue);
+    });
+
+    test('lança OrderNotFoundException quando o pedido não existe', () {
+      expect(() => useCase.execute('x'), throwsA(isA<OrderNotFoundException>()));
+    });
+  });
+}

package/content/skills/dart/examples/repository.dart

@@ -0,0 +1,57 @@
+/// Exemplo: contrato (porta) e implementação, com dependência injetada.
+library;
+
+import 'entity.dart';
+
+/// Contrato de persistência de pedidos.
+abstract interface class OrderRepository {
+  /// Busca o pedido pelo [id]; retorna `null` se não existir.
+  Future<Order?> findById(String id);
+
+  /// Salva o [order].
+  Future<void> save(Order order);
+}
+
+/// Implementação em memória, útil em testes.
+class InMemoryOrderRepository implements OrderRepository {
+  final Map<String, Order> _orders = {};
+
+  @override
+  Future<Order?> findById(String id) async => _orders[id];
+
+  @override
+  Future<void> save(Order order) async {
+    _orders[order.id] = order;
+  }
+}
+
+/// Caso de uso: paga um pedido existente.
+class PayOrder {
+  /// Cria o caso de uso com o [repository] injetado.
+  PayOrder(this._repository);
+
+  final OrderRepository _repository;
+
+  /// Marca como pago o pedido [id].
+  ///
+  /// Lança [OrderNotFoundException] se o pedido não existir.
+  Future<Order> execute(String id) async {
+    final order = await _repository.findById(id);
+    if (order == null) throw OrderNotFoundException(id);
+    final paid = order.markAsPaid();
+    await _repository.save(paid);
+    return paid;
+  }
+}
+
+/// Erro de domínio: pedido não encontrado.
+class OrderNotFoundException implements Exception {
+  /// Cria a exceção para o pedido [id].
+  const OrderNotFoundException(this.id);
+
+  /// Identificador procurado.
+  final String id;
+
+  @override
+  String toString() => 'Pedido não encontrado: $id';
+}

package/content/skills/dart/references/checklist.md

@@ -0,0 +1,12 @@
+# Dart — Checklist de review detalhado
+
+- [ ] Regra de negócio em classes; sem funções soltas nem pipelines longos.
+- [ ] Dependências externas atrás de `abstract interface class`, injetadas no construtor.
+- [ ] Campos `final`, construtores `const` onde couber, estado privado encapsulado.
+- [ ] Toda declaração pública com `///` (sem `/** */`, sem `@param`).
+- [ ] Nomes: `UpperCamelCase` (tipos), `lowerCamelCase` (membros e constantes), `snake_case` (arquivos).
+- [ ] Sem `dynamic`, `!` desnecessário, `Function` solto ou `throw` de string.
+- [ ] Sem `catch` de `Error`; `rethrow` preserva o stack trace.
+- [ ] `Future`s aguardados; recursos liberados em `try/finally`.
+- [ ] `dart analyze` limpo, `dart format` aplicado.
+- [ ] Testes em `test/` espelhando `lib/`, com `group`/`setUp`/`expect`.

package/content/skills/dart/references/documentation.md

@@ -0,0 +1,26 @@
+# Dart — Documentação com `///` (referência detalhada)
+
+Complementa a seção 3 do `SKILL.md`.
+
+## Modelo
+
+```dart
+/// Calcula o total do pedido.
+///
+/// Soma os itens de [items] e aplica [discount] (entre 0 e 1).
+/// Lança [ArgumentError] se [discount] estiver fora do intervalo.
+double calculateTotal(List<Item> items, {double discount = 0}) { ... }
+```
+
+## Regras rápidas
+
+- Primeira linha: frase única, terminada em ponto; depois linha `///` vazia.
+- Propriedade: sintagma nominal. Booleano: "Se ...". Método: verbo na 3ª pessoa.
+- Sem `@param`/`@return`; use prosa e `[nome]`.
+- `///` antes de `@override` e outras anotações.
+- Par getter/setter: documente só o getter.
+- Não documente `@override` sem mudança de comportamento.
+
+## Validação
+
+`dart analyze` resolve referências entre colchetes; `dart doc` gera a documentação.

package/content/skills/dart/references/naming.md

@@ -0,0 +1,27 @@
+# Dart — Nomenclatura (referência detalhada)
+
+Complementa a seção 2 do `SKILL.md`.
+
+## Certo x errado
+
+| Evitar | Preferir | Motivo |
+|---|---|---|
+| `MAX_RETRIES`, `kMaxRetries` | `maxRetries` | Constantes usam `lowerCamelCase` |
+| `IUserRepository` | `UserRepository` | Sem prefixo `I` |
+| `UserRepository.dart` | `user_repository.dart` | Arquivos em `snake_case` |
+| `getTotal()` | `total` (getter) | Propriedade é substantivo, sem `get` |
+| `isNotValid` | `isValid` | Booleano afirmativo |
+| `HTTPClient` | `HttpClient` | Siglas com mais de 2 letras viram palavra |
+| `data`, `tmp`, `x` | `orderTotals` | Nome expressa intenção |
+
+## Ordem de imports
+
+1. `dart:`
+2. `package:`
+3. relativos
+
+Cada grupo em ordem alfabética, separado por linha em branco.
+
+## Privacidade
+
+O prefixo `_` torna o membro privado à **biblioteca** (arquivo), não à classe.

package/content/skills/dart-frog/SKILL.md

@@ -0,0 +1,208 @@
+---
+name: dart-frog
+description: Diretrizes DS9 para backends com Dart Frog em arquitetura hexagonal (domain/adapter por contexto) — rotas finas com 405 obrigatório, injeção de dependência exclusivamente por middleware, `fpdart` com `TaskEither`/`TaskEither.tryCatch` como retorno entre camadas e exceções por camada (BusinessException, ClientException, MiddlewareException). Persistência é agnóstica (use a skill de persistência do projeto). Use ao criar, editar, revisar ou testar rotas, `_middleware.dart`, controllers, services, ports, repositories ou DTOs em um projeto Dart Frog (pasta `routes/`, comandos `dart_frog dev/build`), ou quando o usuário pedir "backend Dart", "API Dart Frog" ou "arquitetura hexagonal em Dart".
+---
+
+# Dart Frog — Diretrizes DS9
+
+Padrão DS9 para APIs em **Dart Frog** com **arquitetura hexagonal** (ports & adapters), organizada por contexto de negócio. Complementa as skills `dart` (nomenclatura, `///`, OOP, null safety) e `hex-pattern-dart` (camadas, ports/adapters, erros): siga as três. A persistência é **agnóstica** aqui; para o banco/ORM do projeto, consulte a skill de persistência correspondente (`list_skills` / `recommend_for_task`).
+
+## 0. Pré-requisitos (verifique antes de gerar código)
+
+1. Confirme no `pubspec.yaml` do projeto as dependências `dart_frog` e **`fpdart`**.
+2. **Se `fpdart` não estiver instalado, informe ao usuário que ele é obrigatório para seguir o padrão DS9** e peça autorização para instalar (`dart pub add fpdart`). Não gere código fora do padrão para contornar a ausência.
+3. Use as versões já fixadas no `pubspec.yaml`; não atualize dependências sem pedido explícito.
+4. Preserve a estrutura existente em projetos pré-existentes; aplique o padrão integralmente em código novo e no que for explicitamente solicitado, sem refatorar o restante.
+
+## 1. Regras inegociáveis
+
+1. **`fpdart` + `TaskEither`:** todo contrato de camada (port, service, repository, controller) que pode falhar **retorna `TaskEither<Falha, T>`**, e a operação assíncrona é envolvida com **`TaskEither.tryCatch`**. Nunca lance exceção para fora de uma camada nem converta falha em sucesso vazio.
+2. **Injeção só por middleware:** dependências são compostas em `_middleware.dart` com `provider<T>` e lidas com `context.read<T>()`. Nada de instanciar service/repository/controller no handler, sem service locator, sem singleton global fora do middleware.
+3. **405 sempre:** todo handler faz `switch` em `context.request.method` e termina com `case _: return Response(statusCode: HttpStatus.methodNotAllowed);`.
+4. **Camadas de erro fixas:** `BusinessException` (service/repository), `ClientException` (controller), `MiddlewareException` (middleware). Nomes e responsabilidades não mudam entre projetos.
+5. **Persistência agnóstica:** o domínio só conhece **ports**; o acesso a dados fica em `adapter/repository`, sem citar ORM/driver nesta skill.
+
+## 2. Estrutura
+
+```text
+<projeto>/
+├── routes/                    # roteador (arquivos = rotas); só despacho HTTP
+│   ├── _middleware.dart       # raiz: CORS, infraestrutura compartilhada
+│   ├── api/_middleware.dart   # autenticação do grupo
+│   └── api/orders/
+│       ├── _middleware.dart   # composição do contexto (providers)
+│       ├── index.dart         # /api/orders
+│       └── [id].dart          # /api/orders/:id
+├── lib/
+│   ├── <contexto>/
+│   │   ├── domain/{models,ports,services}/
+│   │   └── adapter/{controllers,dtos,repository}/
+│   └── common/{exception,http,middleware,environment,logger,models}/
+├── test/                      # espelha lib/ e routes/
+└── main.dart                  # só init() e run()
+```
+
+Estrutura completa e variações (`application/use_case`, adapters de integração): `references/project-structure.md`.
+
+## 3. Camadas e regra de dependência
+
+| Camada | Responsabilidade | Retorno | Falha |
+|---|---|---|---|
+| `routes/**` | despachar método HTTP, ler `controller` do contexto, converter resultado em `Response` | `Future<Response>` | converte `Left` em JSON de erro |
+| `adapter/controllers` | ler body/query/path, validar formato (DTO), chamar service, converter modelo → DTO | `TaskEither<ClientException, T>` | `ClientException` |
+| `domain/services` | regras de negócio, autorização de domínio, composição de ports | `TaskEither<BusinessException, T>` | `BusinessException` |
+| `domain/ports` | contratos (`abstract interface class`) | `TaskEither<BusinessException, T>` | `BusinessException` |
+| `adapter/repository` | implementa o port e acessa a persistência | `TaskEither<BusinessException, T>` | `BusinessException` |
+| `middlewares` | autenticar, compor providers, encerrar com erro | `Handler` | `MiddlewareException` |
+
+Dependências apontam para dentro: `routes → controller → service → port ← repository`.
+
+- `domain/` **nunca** importa `dart_frog`, SDK, driver/ORM, `adapter/`, `RequestContext` nem `Response`. Pode importar `fpdart`, `equatable`, `json_annotation` e `common/exception`.
+- Contextos se comunicam por **port ou service público**, nunca pelo repository concreto de outro contexto, sem dependência circular.
+- Mapeamento: linha de banco → modelo no repository; modelo → DTO no controller/DTO. Modelos de domínio não conhecem DTOs nem classes geradas.
+
+Detalhes e responsabilidades por camada: `references/layers.md`.
+
+## 4. `TaskEither` e `tryCatch`
+
+```dart
+// repository: toda chamada que pode falhar entra em tryCatch
+TaskEither<BusinessException, Order?> findById(String id) {
+  return TaskEither.tryCatch(
+    () => _dataSource.findById(id),
+    (error, stackTrace) => BusinessException(
+      domainName: 'order',
+      statusCode: HttpStatus.internalServerError,
+      message: 'Falha ao consultar o pedido.',
+      error: error,
+      stackTrace: stackTrace,
+    ),
+  );
+}
+
+// service: compõe com flatMap/map/mapLeft; regra inválida vira TaskEither.left
+TaskEither<BusinessException, Order> getById(String id) =>
+    _repository.findById(id).flatMap(
+          (order) => order == null
+              ? TaskEither.left(_notFound(id))
+              : TaskEither.right(order),
+        );
+```
+
+- Prefira `TaskEither.tryCatch`, `map`, `flatMap`, `mapLeft`; execute (`.run()`) **só na rota**.
+- Não use `Exception` genérica como falha; não capture `Error`; não use `catch (_)` amplo.
+- Encadeamentos de `TaskEither` são a exceção funcional aceita da skill `dart`; fora desse contrato, continue em OOP.
+
+Guia completo: `references/fpdart-taskeither.md`.
+
+## 5. Erros por camada
+
+| Tipo | Camada | Campos |
+|---|---|---|
+| `BusinessException` | service, repository | `domainName`, `statusCode`, `message` (seguro para o cliente), `error` (causa original, nunca exposta), `stackTrace` |
+| `ClientException` | controller | `statusCode`, `message` |
+| `MiddlewareException` | middleware | `statusCode`, `message`, `stackTrace?` |
+
+- O controller converte `BusinessException` em `ClientException` preservando o `statusCode`; para `5xx`, use mensagem genérica.
+- Formato único de erro: `{"error": {"code": "...", "message": "..."}}`.
+- **Nunca** envie stack trace, SQL, causa original (`error`), caminho de arquivo ou detalhe de SDK ao cliente; registre no log sem dados sensíveis.
+
+Status HTTP, formato e exemplos: `references/error-handling.md`.
+
+## 6. Rotas (sempre 405)
+
+```dart
+Future<Response> onRequest(RequestContext context) async {
+  final controller = context.read<OrderController>();
+
+  switch (context.request.method) {
+    case HttpMethod.post:
+      final result = await controller.create(context).run();
+      return result.match(
+        ErrorResponse.fromClient,
+        (order) => Response.json(statusCode: HttpStatus.created, body: order.toJson()),
+      );
+    case _:
+      return Response(statusCode: HttpStatus.methodNotAllowed);
+  }
+}
+```
+
+- Rota fina: sem regra de negócio, query, SDK ou instanciação de dependência.
+- `index.dart` para o recurso, `[id].dart` para parâmetro (`onRequest(RequestContext context, String id)`); sem conflito entre `api.dart` e `api/index.dart`.
+- Use `HttpStatus` de `dart:io` em vez de números mágicos.
+
+Convenções do roteador, CLI e catálogo de grupos: `references/routing.md`.
+
+## 7. Injeção de dependência por middleware
+
+```dart
+// routes/api/orders/_middleware.dart
+OrderRepositoryPort? _repository;
+OrderService? _service;
+OrderController? _controller;
+
+Handler middleware(Handler handler) {
+  return handler
+      .use(provider<OrderController>((c) => _controller ??= OrderController(c.read<OrderService>())))
+      .use(provider<OrderService>((c) => _service ??= OrderService(c.read<OrderRepositoryPort>())))
+      .use(provider<OrderRepositoryPort>((c) => _repository ??= OrderRepository(c.read<OrderDataSource>())));
+}
+```
+
+- Construtores recebem **ports/interfaces**; campos `final`.
+- A resolução é de baixo para cima: se `B` depende de `A`, declare `.use(B).use(A)`.
+- `provider` recria o valor a cada leitura; para recursos caros, faça cache em variável privada (`??=`).
+- Infraestrutura compartilhada (conexão, configuração, rate limit) é provida no middleware raiz.
+- Middleware **não** contém regra de negócio nem lê parâmetros de caminho por posição; autorização de recurso fica no service.
+- Nunca `context.read` em models, ports, services ou repositories.
+
+Composição por grupo, autenticação e ordem: `references/middlewares-di.md`.
+
+## 8. Configuração, segurança e geração de código
+
+- Variáveis de ambiente lidas em um ponto único (`common/environment`); nunca hardcodar segredos nem logar tokens ou dados pessoais. `String.fromEnvironment` não funciona no Dart Frog (use `Platform.environment`).
+- Validação de formato no controller/DTO; de regra de negócio no service; falhas de persistência no repository.
+- Nunca confie em `uid`, papel ou perfil enviados pelo cliente sem validar no servidor.
+- Arquivos gerados (`*.g.dart`) não são editados à mão; regenere com `dart run build_runner build --delete-conflicting-outputs`.
+- `main.dart` só define `init()`/`run()`; não compõe services.
+
+## 9. Testes
+
+- Service: fake/mock do port, sem banco real. Controller: entrada válida, inválida, `Right` e `Left` com status correto. Rota: `RequestContext` mockado, cobrindo os métodos suportados **e o 405**. Para criar/executar testes, use o agente `test-writer`.
+- Estrutura em `test/` espelhando `lib/` e `routes/`. Detalhes: `references/testing.md`.
+
+## 10. Checklist de review
+
+- [ ] `fpdart` instalado; contratos retornam `TaskEither` com `tryCatch` nas operações que falham?
+- [ ] Rota fina, com `case _` retornando 405?
+- [ ] Dependências compostas só em `_middleware.dart`, nada instanciado no handler?
+- [ ] `BusinessException` / `ClientException` / `MiddlewareException` nas camadas certas, sem vazar causa interna?
+- [ ] `domain/` sem Dart Frog, SDK ou persistência concreta?
+- [ ] Segredos e dados pessoais fora do código e dos logs; testes cobrindo regra nova e o 405?
+
+Checklist detalhado: `references/checklist.md`.
+
+## Não fazer
+
+- Não instanciar service/repository/controller na rota ou usar service locator.
+- Não retornar `Future` simples, `throw` ou `Exception` genérica nos contratos das camadas.
+- Não colocar regra de negócio em rota, controller ou middleware.
+- Não omitir o 405; não expor stack trace, SQL ou mensagens de SDK.
+- Não referenciar ORM/driver no domínio nem nesta skill.
+
+## 11. Arquivos complementares (leitura sob demanda)
+
+Leia só o necessário (`list_skill_files` / `get_skill_file` com `skill="dart-frog"`; ou direto em `dart-frog/` sem as tools).
+
+| Dúvida | Arquivo |
+|---|---|
+| Árvore de pastas, variações | `references/project-structure.md` |
+| O que cada camada faz e não faz | `references/layers.md` |
+| `TaskEither`, `tryCatch`, instalação do `fpdart` | `references/fpdart-taskeither.md` |
+| Exceções, status e formato de erro | `references/error-handling.md` |
+| Rotas, 405, CLI, grupos | `references/routing.md` |
+| Middlewares, providers e autenticação | `references/middlewares-di.md` |
+| Testes | `references/testing.md` |
+| Checklist de review | `references/checklist.md` |
+| Exemplos de código (exceções, model, port, service, repository, DTO, controller, middlewares, rotas, testes) | `examples/` |

package/content/skills/dart-frog/examples/auth_middleware.dart

@@ -0,0 +1,50 @@
+// Caminho: lib/common/middleware/auth_middleware.dart
+// Autentica a requisição e provê o usuário; falhas são MiddlewareException.
+import 'dart:io';
+
+import 'package:dart_frog/dart_frog.dart';
+
+import '../exception/exceptions.dart';
+import '../http/error_response.dart';
+
+/// Usuário autenticado disponibilizado aos handlers.
+class AuthenticatedUser {
+  /// Cria o usuário autenticado.
+  const AuthenticatedUser({required this.id});
+
+  /// Identificador do usuário.
+  final String id;
+}
+
+/// Port de verificação de credenciais (a implementação é um adapter).
+abstract interface class TokenVerifierPort {
+  /// Retorna o usuário do [token] ou `null` se inválido.
+  Future<AuthenticatedUser?> verify(String token);
+}
+
+/// Exige `Authorization: Bearer <token>` e provê [AuthenticatedUser].
+Middleware authMiddleware() {
+  return (handler) {
+    return (context) async {
+      final header = context.request.headers[HttpHeaders.authorizationHeader];
+      if (header == null || !header.startsWith('Bearer ')) {
+        return ErrorResponse.fromMiddleware(const MiddlewareException(
+          statusCode: HttpStatus.unauthorized,
+          message: 'Credenciais ausentes.',
+        ));
+      }
+
+      final user = await context
+          .read<TokenVerifierPort>()
+          .verify(header.substring('Bearer '.length));
+      if (user == null) {
+        return ErrorResponse.fromMiddleware(const MiddlewareException(
+          statusCode: HttpStatus.unauthorized,
+          message: 'Credenciais inválidas.',
+        ));
+      }
+
+      return handler(context.provide<AuthenticatedUser>(() => user));
+    };
+  };
+}