@ds9-solutions/mcp 0.1.0 → 0.3.0

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));
+    };
+  };
+}

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

@@ -0,0 +1,75 @@
+// Caminho: lib/orders/adapter/controllers/order_controller.dart
+import 'dart:io';
+
+import 'package:dart_frog/dart_frog.dart';
+import 'package:fpdart/fpdart.dart';
+
+import '../../../common/exception/exceptions.dart';
+import '../../domain/services/order_service.dart';
+import '../dtos/order_dtos.dart';
+
+/// Adapta HTTP para o domínio; recebido pronto via `context.read`.
+class OrderController {
+  /// Cria o controller com o [_service] injetado pelo middleware.
+  const OrderController(this._service);
+
+  final OrderService _service;
+
+  /// POST /orders — cria um pedido para o usuário autenticado.
+  TaskEither<ClientException, OrderResponse> create(
+    RequestContext context,
+    String requesterId,
+  ) {
+    return TaskEither<ClientException, Object?>.tryCatch(
+      () => context.request.json(),
+      (_, __) => const ClientException(
+        statusCode: HttpStatus.badRequest,
+        message: 'Body JSON inválido.',
+      ),
+    )
+        .flatMap(_toDto)
+        .flatMap(
+          (dto) => _service
+              .create(ownerId: requesterId, total: dto.total!)
+              .mapLeft(_toClient),
+        )
+        .map(OrderResponse.fromDomain);
+  }
+
+  /// GET /orders/:id — retorna um pedido do usuário autenticado.
+  TaskEither<ClientException, OrderResponse> getById(
+    String id,
+    String requesterId,
+  ) {
+    return _service
+        .getOwnedById(id: id, requesterId: requesterId)
+        .mapLeft(_toClient)
+        .map(OrderResponse.fromDomain);
+  }
+
+  TaskEither<ClientException, CreateOrderRequest> _toDto(Object? json) {
+    if (json is! Map<String, Object?>) {
+      return TaskEither.left(const ClientException(
+        statusCode: HttpStatus.badRequest,
+        message: 'O body deve ser um objeto JSON.',
+      ));
+    }
+    final dto = CreateOrderRequest.fromJson(json);
+    final errors = dto.validate();
+    return errors.isEmpty
+        ? TaskEither.right(dto)
+        : TaskEither.left(ClientException(
+            statusCode: HttpStatus.badRequest,
+            message: errors.join(' '),
+          ));
+  }
+
+  ClientException _toClient(BusinessException failure) {
+    return ClientException(
+      statusCode: failure.statusCode,
+      message: failure.statusCode >= 500
+          ? 'Erro interno. Tente novamente.'
+          : failure.message,
+    );
+  }
+}

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

@@ -0,0 +1,41 @@
+// Caminho: lib/orders/adapter/dtos/order_dtos.dart (um DTO por arquivo em projetos reais)
+import '../../domain/models/order.dart';
+
+/// Entrada de criação de pedido.
+class CreateOrderRequest {
+  /// Cria a requisição com o [total] informado.
+  const CreateOrderRequest({required this.total});
+
+  /// Converte o JSON recebido; campos ausentes ou inválidos ficam `null`.
+  factory CreateOrderRequest.fromJson(Map<String, Object?> json) {
+    final total = json['total'];
+    return CreateOrderRequest(total: total is num ? total.toDouble() : null);
+  }
+
+  /// Valor total informado pelo cliente.
+  final double? total;
+
+  /// Retorna as mensagens de validação de formato; vazio quando válido.
+  List<String> validate() => [
+        if (total == null) 'O campo "total" é obrigatório e numérico.',
+      ];
+}
+
+/// Saída pública de um pedido.
+class OrderResponse {
+  /// Cria a resposta.
+  const OrderResponse({required this.id, required this.total});
+
+  /// Constrói a resposta a partir do modelo de domínio.
+  factory OrderResponse.fromDomain(Order order) =>
+      OrderResponse(id: order.id, total: order.total);
+
+  /// Identificador do pedido.
+  final String id;
+
+  /// Valor total do pedido.
+  final double total;
+
+  /// Serializa para JSON.
+  Map<String, Object?> toJson() => {'id': id, 'total': total};
+}

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

@@ -0,0 +1,35 @@
+// Caminho: lib/common/http/error_response.dart
+import 'dart:io';
+
+import 'package:dart_frog/dart_frog.dart';
+
+import '../exception/exceptions.dart';
+
+/// Converte falhas das camadas no formato único de erro da API.
+abstract final class ErrorResponse {
+  /// Resposta para uma [ClientException].
+  static Response fromClient(ClientException failure) =>
+      _json(failure.statusCode, failure.message);
+
+  /// Resposta para uma [MiddlewareException].
+  static Response fromMiddleware(MiddlewareException failure) =>
+      _json(failure.statusCode, failure.message);
+
+  static Response _json(int statusCode, String message) {
+    return Response.json(
+      statusCode: statusCode,
+      body: {
+        'error': {'code': _codeFor(statusCode), 'message': message},
+      },
+    );
+  }
+
+  static String _codeFor(int statusCode) => switch (statusCode) {
+        HttpStatus.badRequest => 'bad_request',
+        HttpStatus.unauthorized => 'unauthorized',
+        HttpStatus.forbidden => 'forbidden',
+        HttpStatus.notFound => 'not_found',
+        HttpStatus.methodNotAllowed => 'method_not_allowed',
+        _ => statusCode >= 500 ? 'internal_error' : 'error',
+      };
+}

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

@@ -0,0 +1,60 @@
+// Caminho: lib/common/exception/exceptions.dart
+// Camadas de erro fixas do padrão DS9.
+
+/// Falha de regra de negócio ou de persistência (services e repositories).
+class BusinessException implements Exception {
+  /// Cria uma falha de negócio.
+  const BusinessException({
+    required this.domainName,
+    required this.statusCode,
+    required this.message,
+    required this.error,
+    required this.stackTrace,
+  });
+
+  /// Contexto de negócio onde a falha ocorreu (ex.: `order`).
+  final String domainName;
+
+  /// Código HTTP associado à falha.
+  final int statusCode;
+
+  /// Mensagem segura para o cliente.
+  final String message;
+
+  /// Causa original; nunca deve ser enviada ao cliente.
+  final Object error;
+
+  /// Stack trace original, usado apenas em log.
+  final StackTrace stackTrace;
+}
+
+/// Falha de entrada ou acesso, exposta pelo controller ao cliente.
+class ClientException implements Exception {
+  /// Cria uma falha de cliente.
+  const ClientException({required this.statusCode, required this.message});
+
+  /// Código HTTP da resposta.
+  final int statusCode;
+
+  /// Mensagem segura para o cliente.
+  final String message;
+}
+
+/// Falha ocorrida em um middleware (autenticação, autorização, rate limit).
+class MiddlewareException implements Exception {
+  /// Cria uma falha de middleware.
+  const MiddlewareException({
+    required this.statusCode,
+    required this.message,
+    this.stackTrace,
+  });
+
+  /// Código HTTP da resposta.
+  final int statusCode;
+
+  /// Mensagem segura para o cliente.
+  final String message;
+
+  /// Stack trace original, usado apenas em log.
+  final StackTrace? stackTrace;
+}

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

@@ -0,0 +1,34 @@
+// Caminho: routes/api/orders/_middleware.dart
+// Composição do contexto: ÚNICO lugar onde service/repository/controller são criados.
+import 'package:dart_frog/dart_frog.dart';
+import 'package:my_api/orders/adapter/controllers/order_controller.dart';
+import 'package:my_api/orders/adapter/repository/order_repository.dart';
+import 'package:my_api/orders/domain/ports/order_repository_port.dart';
+import 'package:my_api/orders/domain/services/order_service.dart';
+
+OrderRepositoryPort? _repository;
+OrderService? _service;
+OrderController? _controller;
+
+/// Provê o controller de pedidos para as rotas deste ramo.
+///
+/// Quem depende vem primeiro: controller → service → repository.
+/// O `OrderDataSource` é provido por um middleware acima (ex.: `routes/_middleware.dart`).
+Handler middleware(Handler handler) {
+  return handler
+      .use(
+        provider<OrderController>(
+          (context) => _controller ??= OrderController(context.read<OrderService>()),
+        ),
+      )
+      .use(
+        provider<OrderService>(
+          (context) => _service ??= OrderService(context.read<OrderRepositoryPort>()),
+        ),
+      )
+      .use(
+        provider<OrderRepositoryPort>(
+          (context) => _repository ??= OrderRepository(context.read<OrderDataSource>()),
+        ),
+      );
+}

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

@@ -0,0 +1,20 @@
+// Caminho: lib/orders/domain/models/order.dart
+import 'package:equatable/equatable.dart';
+
+/// Pedido do domínio; não conhece HTTP, DTO nem persistência.
+class Order extends Equatable {
+  /// Cria um pedido.
+  const Order({required this.id, required this.ownerId, required this.total});
+
+  /// Identificador único do pedido.
+  final String id;
+
+  /// Identificador do usuário dono do pedido.
+  final String ownerId;
+
+  /// Valor total do pedido.
+  final double total;
+
+  @override
+  List<Object?> get props => [id, ownerId, total];
+}

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

@@ -0,0 +1,17 @@
+// Caminho: lib/orders/domain/ports/order_repository_port.dart
+import 'package:fpdart/fpdart.dart';
+
+import '../../../common/exception/exceptions.dart';
+import '../models/order.dart';
+
+/// Contrato de acesso a pedidos exigido pelo domínio.
+abstract interface class OrderRepositoryPort {
+  /// Busca o pedido [id]; o `Right` é `null` quando não existe.
+  TaskEither<BusinessException, Order?> findById(String id);
+
+  /// Persiste um novo pedido do usuário [ownerId] com o valor [total].
+  TaskEither<BusinessException, Order> create({
+    required String ownerId,
+    required double total,
+  });
+}

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

@@ -0,0 +1,56 @@
+// Caminho: lib/orders/adapter/repository/order_repository.dart
+// Agnóstico de persistência: o acesso real fica atrás de [OrderDataSource],
+// implementado conforme a skill de persistência do projeto.
+import 'dart:io';
+
+import 'package:fpdart/fpdart.dart';
+
+import '../../../common/exception/exceptions.dart';
+import '../../domain/models/order.dart';
+import '../../domain/ports/order_repository_port.dart';
+
+/// Fonte de dados de pedidos (adapter de infraestrutura).
+abstract interface class OrderDataSource {
+  /// Lê o pedido [id]; retorna `null` se não existir.
+  Future<Order?> read(String id);
+
+  /// Grava um pedido e retorna o registro criado.
+  Future<Order> insert({required String ownerId, required double total});
+}
+
+/// Implementa o port de pedidos sobre uma [OrderDataSource].
+class OrderRepository implements OrderRepositoryPort {
+  /// Cria o repository com a [_dataSource] injetada pelo middleware.
+  const OrderRepository(this._dataSource);
+
+  final OrderDataSource _dataSource;
+
+  @override
+  TaskEither<BusinessException, Order?> findById(String id) {
+    return TaskEither.tryCatch(
+      () => _dataSource.read(id),
+      (error, stackTrace) => _failure('Falha ao consultar o pedido.', error, stackTrace),
+    );
+  }
+
+  @override
+  TaskEither<BusinessException, Order> create({
+    required String ownerId,
+    required double total,
+  }) {
+    return TaskEither.tryCatch(
+      () => _dataSource.insert(ownerId: ownerId, total: total),
+      (error, stackTrace) => _failure('Falha ao criar o pedido.', error, stackTrace),
+    );
+  }
+
+  BusinessException _failure(String message, Object error, StackTrace stackTrace) {
+    return BusinessException(
+      domainName: 'order',
+      statusCode: HttpStatus.internalServerError,
+      message: message,
+      error: error,
+      stackTrace: stackTrace,
+    );
+  }
+}

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

@@ -0,0 +1,25 @@
+// Caminho: routes/api/orders/index.dart  ->  /api/orders
+// Rotas dentro de routes/ importam via `package:` (fora de lib/ não há import relativo).
+import 'dart:io';
+
+import 'package:dart_frog/dart_frog.dart';
+import 'package:my_api/common/http/error_response.dart';
+import 'package:my_api/common/middleware/auth_middleware.dart';
+import 'package:my_api/orders/adapter/controllers/order_controller.dart';
+
+/// Despacha o método HTTP; sem regra de negócio nem dependências instanciadas.
+Future<Response> onRequest(RequestContext context) async {
+  final controller = context.read<OrderController>();
+  final user = context.read<AuthenticatedUser>();
+
+  switch (context.request.method) {
+    case HttpMethod.post:
+      final result = await controller.create(context, user.id).run();
+      return result.match(
+        ErrorResponse.fromClient,
+        (order) => Response.json(statusCode: HttpStatus.created, body: order.toJson()),
+      );
+    case _:
+      return Response(statusCode: HttpStatus.methodNotAllowed);
+  }
+}

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

@@ -0,0 +1,24 @@
+// Caminho: routes/api/orders/[id].dart  ->  /api/orders/:id
+import 'dart:io';
+
+import 'package:dart_frog/dart_frog.dart';
+import 'package:my_api/common/http/error_response.dart';
+import 'package:my_api/common/middleware/auth_middleware.dart';
+import 'package:my_api/orders/adapter/controllers/order_controller.dart';
+
+/// O parâmetro de caminho chega como argumento posicional [id].
+Future<Response> onRequest(RequestContext context, String id) async {
+  final controller = context.read<OrderController>();
+  final user = context.read<AuthenticatedUser>();
+
+  switch (context.request.method) {
+    case HttpMethod.get:
+      final result = await controller.getById(id, user.id).run();
+      return result.match(
+        ErrorResponse.fromClient,
+        (order) => Response.json(body: order.toJson()),
+      );
+    case _:
+      return Response(statusCode: HttpStatus.methodNotAllowed);
+  }
+}