@ds9-solutions/mcp 0.3.0 → 0.4.0

package/content/skills/driftorm/SKILL.md

@@ -1,249 +1,83 @@
 ---
 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.
+description: Convenções DS9 para persistência com Drift (banco type-safe para Dart e Flutter) em SQLite e Postgres — classe de banco e conexão, tabelas, queries, paginação, DAOs/repositórios com TaskEither, transações, migrations e testes. Preserva a estrutura já existente no projeto. Use ao criar, editar, revisar ou testar tabelas, queries, DAOs, repositórios, migrations ou a classe de banco em projetos que dependem de `drift`, ou quando pedirem "banco com Drift", "migration Drift" ou "persistência" em Dart/Flutter.
 ---
 
-# Drift best practices
+# Drift (persistência) — padrão DS9
 
-Baseado na documentação oficial: https://drift.simonbinder.eu (repositório simolus3/drift, `drift` 2.35.x).
+Skill agnóstica de projeto: vale para APIs/back-ends Dart e para apps Flutter, em **SQLite** e **Postgres**. Fonte oficial: https://drift.simonbinder.eu. Confirme a versão do `drift` no `pubspec.yaml` do projeto antes de assumir APIs.
 
-## Princípio central
+## Carregamento sob demanda
 
-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.
+Este arquivo traz só as regras inegociáveis e o roteamento. Use `list_skill_files` com `driftorm` e leia **apenas** o que a tarefa pedir com `get_skill_file`.
 
-## Setup
+## Estrutura existente vence
 
-| 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` |
+Se o projeto **já tem** classe de banco, tabelas, migrations ou repositórios, **mantenha a estrutura e o estilo dele** (pastas, nomes, migrations manuais, singleton etc.) e aplique as demais regras desta skill, **principalmente as de segurança**. O que esta skill descreve como padrão vale para código novo e projetos novos. Não refatore estrutura existente sem pedido explícito.
 
-- `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 inegociáveis
 
-## Regras
+1. **`TaskEither` em toda camada.** Repository, service e controller sempre retornam `TaskEither<Falha, T>` (`fpdart`), e o acesso ao banco é envolvido em `TaskEither.tryCatch`. Se `fpdart` não estiver instalado, avise que precisa estar para seguir o padrão DS9. Detalhes: `references/repositories-taskeither.md`.
+2. **A classe de banco nunca sai do repository.** Handlers, controllers e UI não a acessam; recebem repositórios/DAOs por injeção (middleware, construtor ou o mecanismo de DI do projeto).
+3. **Uma instância por arquivo/banco**, injetada. Abrir a mesma classe várias vezes sobre o mesmo arquivo quebra streams.
+4. **Segurança:** valores do usuário sempre como parâmetro (API tipada, `Variable`, `?`/`$1`); nunca concatene entrada em SQL. Credenciais vêm de ambiente/segredos, nunca do código. Mensagens ao cliente não expõem SQL nem a causa original.
+5. **Schema muda por migration versionada** e testada; incremente `schemaVersion`. O Drift não altera bancos existentes sozinho.
+6. **Rode o `build_runner`** após mudar tabelas, DAOs ou o annotation do banco.
+7. **Faça `await` em tudo dentro de `transaction`**; operações atômicas ficam em transação.
+8. **Paginação no padrão DS9:** `page`/`pageSize`, offset `(page - 1) * pageSize`, resposta com `items`, `total`, `page`, `pageSize`. Veja `references/queries-and-pagination.md`.
+9. **Defaults:** use `clientDefault` por padrão; use default no banco (`withDefault`) quando ele for parte legítima do schema (ex.: `gen_random_uuid()` no Postgres). Veja `references/tables-and-columns.md`.
+10. **Documente tudo que for público** com `///` (regra da skill `dart`).
 
-### Classe de banco
+## Roteamento: pergunta → arquivo
 
-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).
+| Preciso de… | Arquivo |
+|---|---|
+| Dependências, `build.yaml`, geração | `references/setup.md` |
+| Classe de banco, conexão, DI, fechar | `references/database-and-connection.md` |
+| Tabelas, colunas, defaults, FKs, índices, enums | `references/tables-and-columns.md` |
+| Select/insert/update/delete, joins, paginação, `watch` | `references/queries-and-pagination.md` |
+| Repository/DAO com `TaskEither` e port hexagonal | `references/repositories-taskeither.md` |
+| Transações | `references/transactions.md` |
+| Migrations (novas e em projetos existentes) | `references/migrations.md` |
+| Diferenças SQLite × Postgres | `references/dialects.md` |
+| Detalhes de Postgres | `postgres/connection.md`, `postgres/types-and-defaults.md`, `postgres/migrations.md` |
+| Detalhes de SQLite | `sqlite/connection.md`, `sqlite/types-and-pragmas.md` |
+| SQL em arquivos `.drift` (opcional) | `references/drift-files.md` |
+| Testes | `references/testing.md` |
+| Performance | `references/performance.md` |
+| Erros comuns | `references/anti-patterns.md` |
+| Revisão final | `references/checklist.md` |
 
-### Tabelas
+Exemplos (Dart, lazy): `examples/table.dart`, `examples/database.dart`, `examples/queries.dart`, `examples/repository_hex.dart`, `examples/pagination.dart`, `examples/migration_step_by_step.dart`, `examples/migration_manual.dart`, `examples/test.dart`, `examples/connection_postgres.dart`, `examples/connection_sqlite.dart`.
 
-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.
+## Dialeto
 
-### Consultas e escrita
+Descubra o dialeto pelo `pubspec.yaml`: `drift_postgres`/`postgres` → Postgres; `sqlite3`/`drift_flutter` → SQLite. Leia a pasta do dialeto correspondente. Em dúvida, pergunte.
 
-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()`.
+## Relação com outras skills
 
-### Organização
+- `dart`: estilo e tipagem (a exceção `TaskEither` está lá).
+- `hex-pattern-dart` / `dart-frog`: o port é do domínio; o repository com Drift o implementa.
+- `flutter`: uso do Drift em apps e testes de widget.
+- Agente `db-analyser`: auditoria de schema/migrations; `security-reviewer`: segurança.
 
-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.
+## Registro de atividade (obrigatório)
 
-### Transações
+Siga o **padrão de registro DS9** (o mesmo da skill `debugger`): ao aplicar esta skill em uma tarefa (banco, tabelas, queries, repositories, migrations), **registre na conversa, em tempo real, tudo o que consome contexto ou tokens**, em uma linha curta por item, antes ou logo depois da ação. O registro é só texto na resposta: **não grave arquivo de log**.
 
-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.
+| Tipo | Registre |
+|---|---|
+| Arquivo lido | caminho e trecho (`src/a.ts:10-60`) ou "inteiro" |
+| Skill/reference | `skill:<id>`, `get_skill_file <id> references/x.md` |
+| Busca | padrão e pasta (`grep "X" src/`) |
+| Comando | o comando e o tamanho aproximado da saída (curta/média/longa); saída longa é filtrada ou resumida |
+| Web/MCP | URL ou tool chamada (`Referência externa: <nome/link>` no fallback web) |
+| Subagente | nome e objetivo |
+| Log/stack colado | origem e tamanho aproximado |
+| Arquivo criado/alterado | caminho e motivo (`✏️ Criando: <caminho>` / `✏️ Atualizando: <caminho>`); só quando a alteração for permitida |
 
-### Migrations
+Formato: `📄 leitura · 🧩 skill · 🔎 busca · ⚙️ comando · 🌐 web/MCP · 🤖 subagente · ✏️ escrita`, por exemplo `📄 lib/orders/order_service.dart:30-90` ou `🧩 get_skill_file <id> references/x.md`.
 
-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.
+Registre também cada arquivo de `references/`, `examples/`, `postgres/` ou `sqlite/` consultado e o dialeto detectado.
 
-### 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`?
+Regras: leia o mínimo necessário (trechos em vez de arquivos inteiros, filtros em saídas de comando), não releia o que já leu e mascare segredos no registro. Ao final, inclua o resumo **"Consumo da tarefa"**: tabela com tipo, itens e observação, apontando o que foi mais caro e como reduzir.

package/content/skills/driftorm/examples/connection_postgres.dart

@@ -0,0 +1,25 @@
+// Caminho: lib/common/infra/database/connection_postgres.dart
+import 'dart:io';
+
+import 'package:drift/drift.dart';
+import 'package:drift_postgres/drift_postgres.dart';
+import 'package:postgres/postgres.dart' as pg;
+
+/// Abre a conexão Postgres a partir de variáveis de ambiente.
+QueryExecutor openPostgres() {
+  final env = Platform.environment;
+  final isProduction = env['APP_ENV'] == 'production';
+  return PgDatabase(
+    endpoint: pg.Endpoint(
+      host: env['DB_HOST']!,
+      port: int.tryParse(env['DB_PORT'] ?? '') ?? 5432,
+      database: env['DB_NAME']!,
+      username: env['DB_USER'],
+      password: env['DB_PASSWORD'],
+    ),
+    // TLS obrigatório em produção; desligado só em desenvolvimento local.
+    settings: pg.ConnectionSettings(
+      sslMode: isProduction ? pg.SslMode.require : pg.SslMode.disable,
+    ),
+  );
+}

package/content/skills/driftorm/examples/connection_sqlite.dart

@@ -0,0 +1,13 @@
+// Caminho: lib/common/infra/database/connection_sqlite.dart
+import 'dart:io';
+
+import 'package:drift/drift.dart';
+import 'package:drift/native.dart';
+
+/// Abre um SQLite em isolate (Dart puro). No Flutter, use `driftDatabase(...)`.
+QueryExecutor openSqlite(String path) {
+  return NativeDatabase.createInBackground(File(path));
+}
+
+/// Banco em memória para testes.
+QueryExecutor openInMemory() => NativeDatabase.memory();

package/content/skills/driftorm/examples/database.dart

@@ -0,0 +1,25 @@
+// Caminho: lib/common/infra/database/database.dart
+import 'package:drift/drift.dart';
+
+import 'tables/order_table.dart';
+
+part 'database.g.dart';
+
+/// Banco da aplicação. Instância única, injetada na raiz de composição.
+@DriftDatabase(tables: [OrderTable])
+class AppDatabase extends _$AppDatabase {
+  /// Cria o banco; [executor] permite injetar um banco em memória nos testes.
+  AppDatabase(QueryExecutor executor) : super(executor);
+
+  @override
+  int get schemaVersion => 1;
+
+  @override
+  MigrationStrategy get migration => MigrationStrategy(
+        onCreate: (m) => m.createAll(),
+        beforeOpen: (details) async {
+          // SQLite: ligue as FKs. Em Postgres, remova esta linha.
+          await customStatement('PRAGMA foreign_keys = ON');
+        },
+      );
+}

package/content/skills/driftorm/examples/migration_manual.dart

@@ -0,0 +1,24 @@
+// Migration manual (estilo comum em projetos existentes; mantenha-o se já usado).
+// DDL idempotente e SQL fixo, sem entrada externa.
+import 'package:drift/drift.dart';
+
+MigrationStrategy buildMigration(GeneratedDatabase db) {
+  return MigrationStrategy(
+    onCreate: (m) => m.createAll(),
+    onUpgrade: (m, from, to) async {
+      if (from < 2) {
+        await db.customStatement(
+          'ALTER TABLE order_table '
+          'ADD COLUMN IF NOT EXISTS deleted BOOLEAN NOT NULL DEFAULT FALSE',
+        );
+      }
+      if (from < 3) {
+        await db.customStatement(
+          'CREATE INDEX IF NOT EXISTS order_owner_idx '
+          'ON order_table (owner_id)',
+        );
+      }
+    },
+  );
+}
+// Lembre de incrementar `schemaVersion` junto com cada bloco `from < n`.

package/content/skills/driftorm/examples/migration_step_by_step.dart

@@ -0,0 +1,24 @@
+// Migration guiada (padrão DS9 para projetos novos).
+// Pré-requisito: `databases:` no build.yaml e `dart run drift_dev make-migrations`.
+import 'package:drift/drift.dart';
+
+import 'database.steps.dart';
+
+extension Migrations on GeneratedDatabase {
+  /// Usa `schema.*` (snapshot da versão), nunca as tabelas atuais da classe.
+  OnUpgrade get schemaUpgrade => stepByStep(
+        from1To2: (m, schema) async {
+          await m.addColumn(schema.orderTable, schema.orderTable.deleted);
+        },
+        from2To3: (m, schema) async {
+          await m.createIndex(schema.orderOwnerIdx);
+        },
+      );
+}
+
+// Na classe de banco:
+//   @override
+//   MigrationStrategy get migration => MigrationStrategy(
+//     onCreate: (m) => m.createAll(),
+//     onUpgrade: schemaUpgrade,
+//   );

package/content/skills/driftorm/examples/pagination.dart

@@ -0,0 +1,48 @@
+// Caminho: lib/orders/adapter/repository/order_repository.dart (trecho)
+// Paginação no padrão DS9: page/pageSize, offset (page - 1) * pageSize,
+// resposta com items/total/page/pageSize.
+import 'package:drift/drift.dart';
+import 'package:fpdart/fpdart.dart';
+
+TaskEither<BusinessException, PaginateResponse<Order>> listByOwner({
+  required String ownerId,
+  required PaginationRequest pagination,
+}) {
+  return TaskEither.tryCatch(
+    () async {
+      final page = pagination.page;
+      final pageSize = pagination.pageSize;
+      final offset = (page - 1) * pageSize;
+
+      final filter = _db.orderTable.ownerId.equals(ownerId) &
+          _db.orderTable.deleted.equals(false);
+
+      // Total sobre os mesmos filtros, sem limit.
+      final count = _db.orderTable.id.count();
+      final total = await (_db.selectOnly(_db.orderTable)
+            ..addColumns([count])
+            ..where(filter))
+          .map((r) => r.read(count) ?? 0)
+          .getSingle();
+
+      final rows = await (_db.select(_db.orderTable)
+            ..where((t) => filter)
+            ..orderBy([
+              (t) => OrderingTerm.desc(t.createdAt),
+              (t) => OrderingTerm.asc(t.id), // desempate estável
+            ])
+            ..limit(pageSize, offset: offset))
+          .get();
+
+      return PaginateResponse(
+        items: rows.map(_toModel).toList(),
+        total: total,
+        page: page,
+        pageSize: pageSize,
+      );
+    },
+    (e, s) => _failure('Falha ao listar pedidos.', e, s),
+  );
+}
+// Projeto existente que calcula o total com `base.get().then((r) => r.length)`:
+// mantenha o que ele já usa.

package/content/skills/driftorm/examples/queries.dart

@@ -0,0 +1,34 @@
+// Trecho: queries comuns dentro de um repository (cada uma em tryCatch).
+import 'package:drift/drift.dart';
+
+// Update parcial.
+Future<int> markDeleted(String id) {
+  return (_db.update(_db.orderTable)..where((t) => t.id.equals(id))).write(
+    OrderTableCompanion(
+      deleted: const Value(true),
+    ),
+  );
+}
+
+// Join tipado.
+Future<List<(OrderTableData, ItemTableData)>> withItems(String ownerId) async {
+  final query = _db.select(_db.orderTable).join([
+    innerJoin(_db.itemTable, _db.itemTable.orderId.equalsExp(_db.orderTable.id)),
+  ])
+    ..where(_db.orderTable.ownerId.equals(ownerId));
+  final rows = await query.get();
+  return rows
+      .map((r) => (r.readTable(_db.orderTable), r.readTable(_db.itemTable)))
+      .toList();
+}
+
+// SQL cru só quando necessário: sempre parametrizado.
+Future<int> incrementCounter(String key) async {
+  final row = await _db.customSelect(
+    r'INSERT INTO rate_limit_table ("key", count) VALUES ($1, 1) '
+    r'ON CONFLICT ("key") DO UPDATE SET count = rate_limit_table.count + 1 '
+    'RETURNING count',
+    variables: [Variable.withString(key)],
+  ).getSingle();
+  return row.read<int>('count');
+}

package/content/skills/driftorm/examples/repository_hex.dart

@@ -0,0 +1,63 @@
+// Caminho: lib/orders/adapter/repository/order_repository.dart
+// Implementa o port do domínio (hex-pattern-dart / dart-frog) com Drift.
+// Toda operação retorna TaskEither e o acesso ao banco fica em tryCatch.
+import 'dart:io';
+
+import 'package:drift/drift.dart';
+import 'package:fpdart/fpdart.dart';
+
+import '../../../common/exception/exceptions.dart';
+import '../../../common/infra/database/database.dart';
+import '../../domain/models/order.dart';
+import '../../domain/ports/order_repository_port.dart';
+
+/// Repository de pedidos sobre Drift.
+class OrderRepository implements OrderRepositoryPort {
+  /// Cria o repository com o [_db] injetado pela raiz de composição.
+  const OrderRepository(this._db);
+
+  final AppDatabase _db;
+
+  @override
+  TaskEither<BusinessException, Order?> findById(String id) {
+    return TaskEither.tryCatch(
+      () async {
+        final row = await (_db.select(_db.orderTable)
+              ..where((t) => t.id.equals(id) & t.deleted.equals(false)))
+            .getSingleOrNull();
+        return row == null ? null : _toModel(row);
+      },
+      (e, s) => _failure('Falha ao consultar o pedido.', e, s),
+    );
+  }
+
+  @override
+  TaskEither<BusinessException, Order> create({
+    required String ownerId,
+    required double total,
+  }) {
+    return TaskEither.tryCatch(
+      () async {
+        final row = await _db.into(_db.orderTable).insertReturning(
+              OrderTableCompanion.insert(ownerId: ownerId, total: total),
+            );
+        return _toModel(row);
+      },
+      (e, s) => _failure('Falha ao criar o pedido.', e, s),
+    );
+  }
+
+  // Converte a linha do Drift em modelo do domínio; nada de *Data fora daqui.
+  Order _toModel(OrderTableData row) =>
+      Order(id: row.id, ownerId: row.ownerId, total: row.total);
+
+  BusinessException _failure(String message, Object error, StackTrace stack) {
+    return BusinessException(
+      domainName: 'order',
+      statusCode: HttpStatus.internalServerError,
+      message: message,
+      error: error,
+      stackTrace: stack,
+    );
+  }
+}

package/content/skills/driftorm/examples/table.dart

@@ -0,0 +1,25 @@
+// Caminho: lib/common/infra/database/tables/order_table.dart
+import 'package:drift/drift.dart';
+
+/// Pedidos.
+class OrderTable extends Table {
+  /// Identificador UUID gerado pelo banco (Postgres).
+  /// Em SQLite/sem default no banco, use `clientDefault(() => uuid())`.
+  TextColumn get id =>
+      text().withDefault(const CustomExpression('gen_random_uuid()'))();
+
+  /// Dono do pedido.
+  TextColumn get ownerId => text()();
+
+  /// Valor total; a regra de negócio garante `>= 0`, o banco reforça.
+  RealColumn get total => real().check(total.isBiggerOrEqualValue(0))();
+
+  /// Indica exclusão lógica.
+  BoolColumn get deleted => boolean().withDefault(const Constant(false))();
+
+  /// Data de criação (calculada no app, sem exigir migration).
+  DateTimeColumn get createdAt => dateTime().clientDefault(DateTime.now)();
+
+  @override
+  Set<Column> get primaryKey => {id};
+}

package/content/skills/driftorm/examples/test.dart

@@ -0,0 +1,33 @@
+// Caminho: test/orders/adapter/repository/order_repository_test.dart
+import 'package:drift/native.dart';
+import 'package:test/test.dart';
+
+void main() {
+  late AppDatabase db;
+  late OrderRepository repository;
+
+  setUp(() {
+    db = AppDatabase(NativeDatabase.memory());
+    repository = OrderRepository(db);
+  });
+
+  tearDown(() => db.close());
+
+  test('create e findById retornam o pedido', () async {
+    final created = await repository.create(ownerId: 'u1', total: 10).run();
+    final id = created.getOrElse((_) => throw StateError('falhou')).id;
+
+    final found = await repository.findById(id).run();
+
+    expect(found.isRight(), isTrue);
+    expect(found.getOrElse((_) => null)?.ownerId, 'u1');
+  });
+
+  test('findById de id inexistente retorna Right(null)', () async {
+    final result = await repository.findById('nao-existe').run();
+
+    expect(result.getOrElse((_) => throw StateError('falhou')), isNull);
+  });
+}
+// Obs.: se a tabela usa gen_random_uuid() (Postgres), este teste em SQLite
+// precisa de clientDefault ou de Postgres real (integração).

package/content/skills/driftorm/postgres/connection.md

@@ -0,0 +1,9 @@
+# Postgres — conexão
+
+- Pacotes: `drift`, `postgres`, `drift_postgres`; `build.yaml` com `sql.dialects: [postgres]`.
+- Conexão com `PgDatabase(endpoint: ..., settings: ...)`; veja `examples/connection_postgres.dart`.
+- Host, porta, banco, usuário e senha vêm de variáveis de ambiente/segredos; nunca do código.
+- **SSL:** exija TLS em produção (`SslMode.require`/`verifyFull`); desabilite só em desenvolvimento local, decidido por variável de ambiente.
+- Uma instância de banco por processo; reutilize a conexão em vez de abrir uma por requisição. Para alta concorrência considere pool (`PgDatabase.withPool` quando disponível na versão do projeto; confirme na documentação).
+- Falha de conexão no startup deve abortar com mensagem clara (sem imprimir a senha).
+- Projeto existente com singleton global lido do ambiente na importação: mantenha; em código novo, prefira construir na raiz de composição.