@ds9-solutions/mcp 0.1.0 → 0.2.0

package/content/skills/dart-frog/references/layers.md

@@ -0,0 +1,43 @@
+# Dart Frog — Responsabilidade por camada (referência)
+
+Complementa a seção 3 do `SKILL.md`. Exemplos: `examples/`.
+
+## Route (`routes/**`)
+
+Faz: `switch` no método HTTP, `context.read<Controller>()`, `.run()` do `TaskEither`, converte `Left`/`Right` em `Response`, `case _` com 405.
+Não faz: regra de negócio, query, SDK, instanciar dependência, ler body (isso é do controller).
+
+## Controller (`adapter/controllers`)
+
+Faz: lê body/query/path/providers do `RequestContext` recebido **por chamada**, converte para DTO e valida formato, chama o service, converte modelo → DTO, converte `BusinessException` em `ClientException`.
+Retorna `TaskEither<ClientException, T>`. Não acessa banco, não tem regra de negócio, não monta `Response`.
+O controller é um objeto **provido por middleware** com o service no construtor; o `RequestContext` entra como parâmetro dos métodos.
+
+## Service (`domain/services`)
+
+Faz: regras de negócio, autorização de domínio (ex.: o pedido pertence ao usuário), composição de ports com `flatMap`/`map`.
+Retorna `TaskEither<BusinessException, T>`. Recebe ports no construtor (`final`), não conhece HTTP, headers, `RequestContext`, SDK ou persistência, não instancia dependências.
+
+## Port (`domain/ports`)
+
+`abstract interface class` pequeno e focado. Assinaturas só com modelos de domínio e tipos simples (nunca DTO, `RequestContext`, `Response`, tipos de ORM ou SDK). Retorna `TaskEither<BusinessException, T>`.
+
+## Repository (`adapter/repository`)
+
+Implementa o port, acessa a persistência (via adapter/fonte de dados), mapeia linha → modelo, envolve cada acesso em `TaskEither.tryCatch` convertendo a causa em `BusinessException`. Sem regra de negócio ou de autorização. A tecnologia concreta é decidida pela skill de persistência do projeto.
+
+## DTO (`adapter/dtos`)
+
+Entrada: `fromJson` + `validate()` (formato). Saída: `fromDomain` + `toJson()`. Nome indica a operação (`CreateOrderRequest`, `OrderResponse`).
+
+## Model (`domain/models`)
+
+Classes imutáveis (`final`, `const`), sem conhecer DTO ou persistência. Invariantes validadas na criação quando possível.
+
+## Middleware
+
+Autentica, compõe providers, encerra com `MiddlewareException`. Não substitui a cadeia controller → service → repository nem contém regra de negócio.
+
+## Comunicação entre contextos
+
+Um contexto consome outro via port ou service público, nunca via repository concreto; sem dependência circular.

package/content/skills/dart-frog/references/middlewares-di.md

@@ -0,0 +1,45 @@
+# Dart Frog — Middlewares e injeção de dependência (referência)
+
+Complementa a seção 7 do `SKILL.md`. Exemplos: `examples/middleware_composition.dart`, `auth_middleware.dart`.
+
+## Regra
+
+A composição de dependências acontece **somente** em `routes/**/_middleware.dart`, com `provider<T>`; a leitura é `context.read<T>()`. Nunca instancie service, repository ou controller no handler, nem use service locator.
+
+## Um `_middleware.dart` por diretório
+
+Exporta `Handler middleware(Handler handler)` e vale para a pasta e subpastas. Encadeie com `handler.use(...)`.
+
+## Ordem de resolução
+
+A resolução é de baixo para cima: se `B` depende de `A`, declare `.use(B).use(A)`. Exemplo: controller → service → repository.
+
+## Cache
+
+`provider` é lazy e recria o valor a cada leitura. Para instâncias compartilhadas ou caras, faça cache em variável privada do arquivo: `_service ??= OrderService(...)`.
+
+## Distribuição por nível
+
+| Middleware | Provê |
+|---|---|
+| `routes/_middleware.dart` | CORS, infraestrutura compartilhada (conexão, configuração, rate limit) |
+| `routes/api/_middleware.dart` | autenticação, usuário autenticado |
+| `routes/admin/_middleware.dart` | autenticação + verificação de papel administrativo |
+| `routes/<grupo>/<recurso>/_middleware.dart` | controller/service/repository do recurso |
+
+Cada middleware específico provê só o necessário ao seu ramo.
+
+## Autenticação
+
+Middleware valida credenciais por um **port** (ex.: `TokenVerifierPort`), provê o usuário e encerra com `MiddlewareException` (`401`/`403`) quando inválido. Credenciais e chaves vêm do ambiente, nunca do código.
+
+## Proibido
+
+- Regra de negócio em middleware (inclusive verificar dono do recurso): isso é do service.
+- Ler parâmetro de caminho por posição (`pathSegments[n]`) em middleware: frágil e acoplado à URL. Receba o `id` na rota e valide no service.
+- `context.read` em models, ports, services e repositories.
+- Segundo ponto de composição fora de `_middleware.dart`.
+
+## Variáveis de ambiente
+
+Leia `Platform.environment` em um ponto único (`common/environment`) e proveja a configuração. `String.fromEnvironment` não funciona no Dart Frog.

package/content/skills/dart-frog/references/project-structure.md

@@ -0,0 +1,67 @@
+# Dart Frog — Estrutura de projeto (referência)
+
+Complementa a seção 2 do `SKILL.md`.
+
+## Árvore completa
+
+```text
+<projeto>/
+├── routes/
+│   ├── _middleware.dart              # raiz: CORS, infraestrutura compartilhada, rate limit
+│   ├── index.dart                    # GET /
+│   ├── public/                       # sem autenticação
+│   │   └── _middleware.dart
+│   ├── api/                          # usuários autenticados
+│   │   ├── _middleware.dart          # autenticação (provê o usuário)
+│   │   └── orders/
+│   │       ├── _middleware.dart      # composição do contexto
+│   │       ├── index.dart            # /api/orders
+│   │       └── [id].dart             # /api/orders/:id
+│   └── admin/                        # operações administrativas
+│       └── _middleware.dart          # autenticação + papel administrativo
+├── lib/
+│   ├── orders/                       # um contexto de negócio
+│   │   ├── domain/
+│   │   │   ├── models/               # entidades e valores
+│   │   │   ├── ports/                # contratos (abstract interface class)
+│   │   │   └── services/             # regras de negócio
+│   │   └── adapter/
+│   │       ├── controllers/          # HTTP -> domínio
+│   │       ├── dtos/                 # entrada e saída da API
+│   │       └── repository/           # domínio -> persistência
+│   └── common/
+│       ├── exception/                # BusinessException, ClientException, MiddlewareException
+│       ├── http/                     # formato de erro, helpers de resposta
+│       ├── middleware/               # auth, CORS, rate limit reutilizáveis
+│       ├── environment/              # leitura única de variáveis de ambiente
+│       ├── logger/
+│       └── models/                   # paginação e tipos compartilhados
+├── test/                             # espelha lib/ e routes/
+├── main.dart                         # só init() e run()
+├── pubspec.yaml
+└── analysis_options.yaml
+```
+
+## Variações permitidas
+
+- `application/use_case/` dentro de um contexto, **só** quando houver orquestração entre vários services/ports. Não crie por antecipação.
+- `adapter/<integração>/` (e-mail, mensageria, storage) para SDKs externos, sempre atrás de um port.
+- Infraestrutura de persistência compartilhada em `common/infra/` (detalhes na skill de persistência do projeto).
+- Não crie pasta `mappers/` por antecipação: o mapeamento fica no repository (linha → modelo) e no controller/DTO (modelo → DTO).
+
+## Nomenclatura de arquivos
+
+`snake_case.dart` com sufixo do papel: `_model`, `_dto`, `_service`, `_service_port`, `_repository`, `_repository_port`, `_controller`, `_middleware`, `_use_case`. Demais regras: skill `dart`.
+
+## Grupos de rota
+
+| Grupo | Pasta | Middleware |
+|---|---|---|
+| Base | `routes/index.dart` | raiz |
+| Pública | `routes/public/**` | rate limit, sem autenticação |
+| Autenticada | `routes/api/**` | autenticação, provê o usuário |
+| Administrativa | `routes/admin/**` | autenticação + papel administrativo |
+
+## Imports
+
+Dentro de `lib/`, use imports relativos (skill `dart`). Em `routes/`, `main.dart` e `test/` use `package:<nome_do_pacote>/...`.

package/content/skills/dart-frog/references/routing.md

@@ -0,0 +1,53 @@
+# Dart Frog — Rotas (referência)
+
+Complementa a seção 6 do `SKILL.md`. Exemplos: `examples/route_collection.dart`, `route_item.dart`.
+
+## Convenções do roteador
+
+- Uma rota = um arquivo em `routes/` que exporta `onRequest(RequestContext context, ...)`. `index.dart` mapeia para a pasta.
+- Rota dinâmica: `[id].dart` ou pasta `[id]/`; cada parâmetro vira argumento `String` posicional, na ordem do caminho.
+- Wildcard `[...rest].dart` deve ser o único arquivo da pasta.
+- Não coexistam `routes/api.dart` e `routes/api/index.dart` (conflito no build).
+- Handler assíncrono retorna `Future<Response>`.
+
+## 405 obrigatório
+
+Todo handler despacha por método e termina com o caso padrão:
+
+```dart
+switch (context.request.method) {
+  case HttpMethod.get:
+    // ...
+  case _:
+    return Response(statusCode: HttpStatus.methodNotAllowed);
+}
+```
+
+Rotas inexistentes (caminho não encontrado) são tratadas pelo próprio Dart Frog com 404; o 405 cobre método não suportado em uma rota existente.
+
+## Request e Response
+
+- O body só pode ser lido uma vez (`body()`, `json()` ou `formData()`); a leitura é do controller.
+- `json()` devolve `dynamic`: valide e converta para DTO tipado; payload inválido responde 400.
+- `formData()` lança `StateError` se o content-type não for de formulário: verifique antes.
+- Sucesso: `Response.json(body: ...)`; criação: `201`; use `HttpStatus` em vez de números.
+- Listagens mantêm o formato adotado pelo endpoint (lista direta ou objeto com dados e metadados).
+
+## Paginação
+
+Parâmetros `page` e `pageSize` na query, lidos no controller; o repository devolve itens, total, página e tamanho; o service só propaga. Defina um tipo compartilhado em `common/models` e mantenha o padrão em todos os endpoints.
+
+## CLI
+
+- `dart pub global activate dart_frog_cli` instala a CLI.
+- `dart_frog create <nome>`, `dart_frog dev` (hot reload; `--port`), `dart_frog build` (build de produção em `build/`, com Dockerfile).
+- `dart_frog new route "/caminho"` e `dart_frog new middleware "/caminho"`: prefira a CLI a criar à mão.
+- Versões da CLI e do pacote `dart_frog` devem ser compatíveis.
+
+## Estáticos
+
+Arquivos estáticos ficam em `public/` na raiz; não repita nomes existentes em `routes/`.
+
+## Ciclo de vida
+
+`main.dart` define só `init()` (execução única no start) e `run()` (entrypoint customizado; roda a cada hot reload). Não compõe services.

package/content/skills/dart-frog/references/testing.md

@@ -0,0 +1,24 @@
+# Dart Frog — Testes (referência)
+
+Complementa a seção 9 do `SKILL.md`. Exemplos: `examples/service_test.dart`, `route_test.dart`. Para criar e executar, use o agente `test-writer`.
+
+## Estrutura
+
+`test/` espelha `lib/` e `routes/` (ex.: `test/orders/domain/services/order_service_test.dart`, `test/routes/api/orders/index_test.dart`). Ferramentas: `package:test` e `package:mocktail`.
+
+## O que testar
+
+| Alvo | Como | Cobrir |
+|---|---|---|
+| Service | fake/mock do port, sem banco real | cada regra de negócio, `Left` com status correto e `Right` |
+| Controller | service mockado e `RequestContext` mockado | entrada válida, body inválido, validação, `Left`→`ClientException`, `Right` |
+| Repository | integração separada, quando houver persistência real | mapeamento e conversão de falha em `BusinessException` |
+| Rota | `RequestContext` mockado, handler como função | cada método suportado **e o 405** |
+| Middleware | `Handler` interno stubado | provê o valor; encerra com 401/403 |
+
+## Dicas
+
+- Mocke o `RequestContext` e faça stub de `context.request` (com `Request.get/post/delete` reais) e de `context.read<T>()`.
+- Verifique `Either` com `result.isLeft()`, `result.getLeft()`, `result.getRight()`.
+- Sem serviços externos reais em testes unitários.
+- Toda regra de negócio nova tem teste no service.

package/content/skills/docker/SKILL.md

@@ -1,11 +1,11 @@
 ---
 name: docker
-description: Diretrizes de containerização Docker para projetos NestJS/Node.js da DS9 — Dockerfile multi-stage, docker-compose para ambiente local, segurança de imagem e variáveis de ambiente. Use ao criar/revisar `Dockerfile`, `docker-compose.yml`, ou quando o usuário pedir "containerizar", "imagem Docker" ou "subir ambiente local".
+description: Diretrizes de containerização Docker para projetos Node.js da DS9 — Dockerfile multi-stage, docker-compose para ambiente local, segurança de imagem e variáveis de ambiente. Use ao criar/revisar `Dockerfile`, `docker-compose.yml`, ou quando o usuário pedir "containerizar", "imagem Docker" ou "subir ambiente local".
 ---
 
 # Docker — Diretrizes DS9
 
-Convenções para containerizar aplicações NestJS/Node.js e seus serviços de apoio (MySQL, etc.) nos projetos da empresa.
+Convenções para containerizar aplicações Node.js e seus serviços de apoio (MySQL, etc.) nos projetos da empresa.
 
 ## Dockerfile multi-stage (obrigatório)
 
@@ -42,7 +42,7 @@ Regras obrigatórias:
 
 ## Variáveis de ambiente e segredos
 
-- Nenhum segredo (senha de banco, JWT secret, API key) é copiado para dentro da imagem ou escrito em `ENV` no Dockerfile. Segredos entram em runtime via variáveis de ambiente/secret manager do orquestrador (ver skill `nestjs` para `ConfigService`).
+- Nenhum segredo (senha de banco, JWT secret, API key) é copiado para dentro da imagem ou escrito em `ENV` no Dockerfile. Segredos entram em runtime via variáveis de ambiente/secret manager do orquestrador (use o mecanismo de configuração do projeto).
 - `.env` usado em desenvolvimento local nunca é commitado (deve estar no `.gitignore`) nem copiado para a imagem (`.dockerignore`).
 - `docker-compose.yml` de desenvolvimento pode referenciar um `.env` local via `env_file`, mas o arquivo de exemplo versionado é `.env.example` sem valores reais.
 

package/content/skills/driftorm/SKILL.md

@@ -0,0 +1,249 @@
+---
+name: driftorm
+description: Convenções e boas práticas do Drift, a biblioteca de banco de dados type-safe para Dart e Flutter (SQLite e Postgres). Use ao criar, editar, revisar ou testar tabelas, consultas, DAOs, migrations ou a classe de banco em projetos que dependem de drift.
+---
+
+# Drift best practices
+
+Baseado na documentação oficial: https://drift.simonbinder.eu (repositório simolus3/drift, `drift` 2.35.x).
+
+## Princípio central
+
+O Drift gera código a partir do schema que você declara. O schema é a fonte da verdade: tabelas em Dart (ou SQL em arquivos `.drift`), uma classe de banco central e o `build_runner` gerando o resto. Toda mudança de schema é uma migration versionada e testada.
+
+## Setup
+
+| Alvo | Dependências | Dev dependencies |
+|---|---|---|
+| Flutter | `drift`, `drift_flutter`, `path_provider` | `drift_dev`, `build_runner` |
+| Dart (SQLite) | `drift`, `sqlite3` | `drift_dev`, `build_runner` |
+| Dart (Postgres) | `drift`, `postgres`, `drift_postgres` | `drift_dev`, `build_runner` |
+
+- `dart run build_runner build` gera o código uma vez. Durante o desenvolvimento, use `dart run build_runner watch`.
+- Para Postgres, configure `sql: dialects: [postgres]` no `build.yaml`. Por padrão o gerador só emite SQL de SQLite.
+
+## Regras
+
+### Classe de banco
+
+1. **Uma classe `@DriftDatabase(tables: [...], daos: [...])`** que estende `_$NomeDatabase`, com `part 'arquivo.g.dart';`.
+2. **O construtor aceita um `QueryExecutor` opcional**: `AppDatabase([QueryExecutor? e]) : super(e ?? _openConnection());`. Isso permite injetar um banco em memória nos testes.
+3. **Use uma única instância (singleton) por arquivo de banco.** Abrir a mesma classe várias vezes sobre o mesmo arquivo quebra os streams e gera aviso em runtime. Forneça a instância por DI (Riverpod, get_it, provider).
+4. **Abra a conexão fora da thread principal.** No Flutter, use `driftDatabase(name: ...)`, do `drift_flutter`. Em Dart puro, use `NativeDatabase.createInBackground(File(...))`. Ambos rodam o SQLite em isolate.
+5. **Feche com `await db.close()`** no fim do ciclo de vida (testes, shutdown do servidor).
+
+### Tabelas
+
+6. **Uma tabela é uma classe que estende `Table`**, com colunas declaradas como `late final campo = tipo()();`. Os parênteses finais são obrigatórios.
+7. **Colunas são não-nulas por padrão.** Use `.nullable()` só quando `null` tiver significado de domínio.
+8. **Chave primária:** `integer().autoIncrement()()` para o caso comum. Para outros casos, sobrescreva `Set<Column> get primaryKey => {...}` (só com `=>` e literal de set).
+9. **Prefira `clientDefault()` a `withDefault()`.** O `clientDefault` é calculado em Dart e não exige migration. O `withDefault` altera o schema.
+10. **Chaves estrangeiras com `.references(Tabela, #coluna, onDelete: ...)`.** No SQLite elas vêm desligadas, então ative com `PRAGMA foreign_keys = ON` no `beforeOpen`.
+11. **Garanta integridade no schema:** `.unique()`, `uniqueKeys` para unicidade composta, `.check(expr)` para validação. Prefira `check` a `withLength`, que só valida em Dart.
+12. **Crie índices com `@TableIndex(name: ..., columns: {#col})`** para colunas muito filtradas. Chave primária, `unique` e alvo de FK já têm índice.
+13. **Em projeto novo, armazene `DateTime` como texto ISO-8601** com `store_date_time_values_as_text: true` no `build.yaml`. O padrão é timestamp Unix em segundos, sem fuso e sem frações.
+14. **Reaproveite colunas comuns** (`id`, `createdAt`) com mixins de tabela.
+15. **Enums e tipos próprios** usam `intEnum<T>()`, `textEnum<T>()` ou `TypeConverter`, em vez de conversão manual espalhada pelo código.
+16. **Rode o gerador de novo** sempre que mudar tabelas, DAOs ou o annotation do banco.
+
+### Consultas e escrita
+
+17. **Insira com `Companion.insert(...)`**, que torna obrigatórios só os campos sem default. Para atualização parcial, use `Companion(campo: Value(x))`.
+18. **Use a API tipada** (`select`, `into`, `update`, `delete`, joins, manager) antes de SQL cru. Quando precisar de SQL, prefira arquivos `.drift`, que o gerador valida em tempo de build. `customSelect` fica como último recurso e precisa de `readsFrom` para funcionar com `watch`.
+19. **`get()` para leitura única e `watch()` para UI reativa.** O stream já emite o valor atual ao ser escutado, então não combine `get()` com `watch()`.
+20. **`getSingle()` lança erro se não houver exatamente uma linha.** Quando a ausência é um caso válido, use `getSingleOrNull()` ou `watchSingleOrNull()`.
+
+### Organização
+
+21. **Separe as consultas por domínio em DAOs:** `@DriftAccessor(tables: [...])` estendendo `DatabaseAccessor<AppDatabase>` com o mixin gerado. Registre os DAOs em `daos:` no `@DriftDatabase`.
+22. **Não exponha a classe de banco para a UI ou para os handlers.** Exponha DAOs ou repositórios que retornam modelos e streams.
+
+### Transações
+
+23. **Operações que precisam ser atômicas vão em `transaction(() async { ... })`.**
+24. **Faça `await` em todas as chamadas dentro da transação.** Query sem `await` pode rodar depois do fechamento e causar perda de dados ou crash. Não agende timers que usem o banco dentro da transação.
+25. **Streams criados fora da transação só são notificados no commit.** Não escute fora da transação um stream criado dentro dela.
+
+### Migrations
+
+26. **Toda mudança de schema exige incrementar o `schemaVersion` e escrever uma migration.** O Drift não altera bancos existentes sozinho.
+27. **Use o fluxo guiado `make-migrations`.** Registre o banco em `databases:` no `build.yaml` e rode `dart run drift_dev make-migrations` **antes** da primeira mudança, para salvar o schema inicial. Depois, a cada mudança, incremente a versão e rode o comando de novo.
+28. **Escreva as migrations com `stepByStep(from1To2: ..., from2To3: ...)`**, usando o `schema` recebido e nunca as tabelas atuais da classe. Extraia o `stepByStep` para um getter de extensão em `GeneratedDatabase`, para não referenciar o schema atual por acidente.
+29. **Rode os testes de migration gerados** (em `test/drift/`) e versione a pasta `drift_schemas/` no Git.
+30. **Evite consultas dentro de callbacks de migration.** Se precisar, rode-as só depois de o schema chegar ao estado que elas esperam.
+31. **Pragmas e seed vão no `beforeOpen`**, que roda a cada abertura. Use `details.wasCreated` e `details.hadUpgrade` para condicionar o seed.
+
+### Testes
+
+32. **Teste com `NativeDatabase.memory()`**, abrindo no `setUp` e fechando no `tearDown`. Em widget tests do Flutter, envolva com `DatabaseConnection(..., closeStreamsSynchronously: true)`.
+
+## Exemplos
+
+### Tabelas, banco e conexão (Flutter)
+
+```dart
+// lib/database/database.dart
+import 'package:drift/drift.dart';
+import 'package:drift_flutter/drift_flutter.dart';
+import 'package:path_provider/path_provider.dart';
+
+import 'database.steps.dart';
+
+part 'database.g.dart';
+
+mixin AutoIncrementingPrimaryKey on Table {
+  late final id = integer().autoIncrement()();
+}
+
+class Categories extends Table with AutoIncrementingPrimaryKey {
+  late final name = text().unique()();
+}
+
+@TableIndex(name: 'todo_category', columns: {#category})
+class TodoItems extends Table with AutoIncrementingPrimaryKey {
+  // Coluna que se referencia no check precisa de tipo explícito.
+  late final Column<String> title =
+      text().check(title.length.isBiggerThanValue(0))();
+  late final done = boolean().clientDefault(() => false)();
+  late final category = integer()
+      .nullable()
+      .references(Categories, #id, onDelete: KeyAction.setNull)();
+  late final createdAt = dateTime().clientDefault(DateTime.now)();
+}
+
+@DriftDatabase(tables: [Categories, TodoItems], daos: [TodosDao])
+class AppDatabase extends _$AppDatabase {
+  AppDatabase([QueryExecutor? executor]) : super(executor ?? _openConnection());
+
+  @override
+  int get schemaVersion => 2;
+
+  @override
+  MigrationStrategy get migration => MigrationStrategy(
+        onUpgrade: _schemaUpgrade,
+        beforeOpen: (details) async {
+          await customStatement('PRAGMA foreign_keys = ON');
+        },
+      );
+
+  static QueryExecutor _openConnection() {
+    return driftDatabase(
+      name: 'app_database',
+      native: const DriftNativeOptions(
+        databaseDirectory: getApplicationSupportDirectory,
+      ),
+    );
+  }
+}
+
+extension Migrations on GeneratedDatabase {
+  OnUpgrade get _schemaUpgrade => stepByStep(
+        from1To2: (m, schema) async {
+          await m.createTable(schema.categories);
+          await m.addColumn(schema.todoItems, schema.todoItems.category);
+        },
+      );
+}
+```
+
+### DAO com stream e transação
+
+```dart
+// lib/database/todos_dao.dart
+import 'package:drift/drift.dart';
+
+import 'database.dart';
+
+part 'todos_dao.g.dart';
+
+@DriftAccessor(tables: [TodoItems, Categories])
+class TodosDao extends DatabaseAccessor<AppDatabase> with _$TodosDaoMixin {
+  TodosDao(super.attachedDatabase);
+
+  Stream<List<TodoItem>> watchPending() {
+    return (select(todoItems)
+          ..where((t) => t.done.equals(false))
+          ..orderBy([(t) => OrderingTerm.desc(t.createdAt)]))
+        .watch();
+  }
+
+  Future<int> add(String title) {
+    return into(todoItems).insert(TodoItemsCompanion.insert(title: title));
+  }
+
+  Future<void> deleteCategory(int categoryId) {
+    return transaction(() async {
+      await (update(todoItems)..where((t) => t.category.equals(categoryId)))
+          .write(const TodoItemsCompanion(category: Value(null)));
+      await (delete(categories)..where((c) => c.id.equals(categoryId))).go();
+    });
+  }
+}
+```
+
+### Conexão Postgres (backend Dart)
+
+```dart
+import 'dart:io';
+
+import 'package:drift_postgres/drift_postgres.dart';
+import 'package:postgres/postgres.dart' as pg;
+
+QueryExecutor openPostgres() {
+  final env = Platform.environment;
+  return PgDatabase(
+    endpoint: pg.Endpoint(
+      host: env['DB_HOST']!,
+      database: env['DB_NAME']!,
+      username: env['DB_USER'],
+      password: env['DB_PASSWORD'],
+    ),
+  );
+}
+```
+
+### Teste
+
+```dart
+import 'package:drift/drift.dart';
+import 'package:drift/native.dart';
+import 'package:test/test.dart';
+
+import 'package:my_app/database/database.dart';
+
+void main() {
+  late AppDatabase db;
+
+  setUp(() {
+    db = AppDatabase(
+      DatabaseConnection(
+        NativeDatabase.memory(),
+        closeStreamsSynchronously: true,
+      ),
+    );
+  });
+
+  tearDown(() => db.close());
+
+  test('watchPending emite o item recém-criado', () async {
+    final stream = db.todosDao.watchPending();
+    await db.todosDao.add('Escrever testes');
+
+    final items = await stream.first;
+    expect(items.map((t) => t.title), contains('Escrever testes'));
+  });
+}
+```
+
+## Checklist de revisão
+
+- [ ] Mudou tabela, DAO ou annotation? O `build_runner` foi rodado de novo?
+- [ ] Mudou o schema? O `schemaVersion` foi incrementado, o `make-migrations` foi rodado e existe um passo `fromXToY` testado?
+- [ ] A migration usa `schema.*` e não as tabelas atuais da classe?
+- [ ] Existe uma única instância do banco, injetada por DI?
+- [ ] A conexão usa `driftDatabase` ou `createInBackground`?
+- [ ] FKs no SQLite têm `PRAGMA foreign_keys = ON`?
+- [ ] Toda chamada dentro de `transaction` tem `await`?
+- [ ] Defaults usam `clientDefault`, salvo quando o default precisa estar no schema?
+- [ ] `getSingle` é usado só onde a linha certamente existe?
+- [ ] Os testes usam `NativeDatabase.memory()` e fecham o banco no `tearDown`?