@ds9-solutions/mcp 0.3.0 → 0.5.0

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

@@ -0,0 +1,11 @@
+# Postgres — migrations
+
+- Projeto novo: fluxo guiado (`make-migrations` + `stepByStep`) em `references/migrations.md`.
+- **Projeto existente com migrations manuais** (`if (from < n)` + `customStatement`): mantenha o estilo, aplique as regras abaixo.
+- DDL idempotente: `CREATE TABLE IF NOT EXISTS`, `ADD COLUMN IF NOT EXISTS`, `CREATE INDEX IF NOT EXISTS`.
+- Postgres suporta DDL transacional: agrupe a migration em uma transação para que falha parcial faça rollback.
+- Adicionar coluna `NOT NULL` em tabela com dados: adicione nullable (ou com default), preencha, depois imponha `NOT NULL`.
+- Índices grandes em produção: `CREATE INDEX CONCURRENTLY` não roda em transação; trate fora da migration do app.
+- Nunca interpole entrada externa em DDL; use só literais fixos.
+- Mantenha `schemaVersion` incrementado a cada bloco; `beforeOpen` não deve alterar schema.
+- Em produção, prefira rodar migrations em um passo controlado (deploy/CI) a rodar em cada instância no startup, quando houver várias réplicas.

package/content/skills/driftorm/postgres/types-and-defaults.md

@@ -0,0 +1,10 @@
+# Postgres — tipos e defaults
+
+- **UUID:** `text().withDefault(const CustomExpression('gen_random_uuid()'))()` é legítimo (default no banco; vale para inserts fora do app). Alternativa: `clientDefault` gerando uuid em Dart. Mantenha o que o projeto usa.
+- **Timestamps:** `dateTime().withDefault(currentDateAndTime)()` ou `CustomExpression('now()')`. Prefira `timestamptz` quando o tipo fizer parte do schema (via `drift_postgres`, `PgTypes.timestampWithTimezone`).
+- **Enums:** `textEnum<T>()` (legível e resistente a reordenação); enum nativo do Postgres só com tipo customizado.
+- **JSON:** `jsonb` via `drift_postgres` quando precisar consultar dentro do JSON.
+- **Upsert:** `insertOnConflictUpdate`/`onConflict` da API tipada; para casos avançados `customSelect('INSERT ... ON CONFLICT (...) DO UPDATE ... RETURNING ...', variables: [...])` com `$1`, `$2` ou `Variable`.
+- **FK sem índice:** o Postgres não indexa automaticamente o lado filho; crie índice quando filtrar/joinear por ela.
+- **Nomes:** o Drift converte `camelCase` em `snake_case` nas colunas; em SQL cru use o nome snake_case e o nome da tabela gerado.
+- Sempre parametrize valores; nunca interpole strings em SQL.

package/content/skills/driftorm/references/anti-patterns.md

@@ -0,0 +1,20 @@
+# Erros comuns
+
+Se o projeto já faz algo desta lista **por convenção própria estável** (ex.: singleton global lido do ambiente, contagem por `get().length`), mantenha e apenas sinalize como sugestão — não como defeito.
+
+| Erro | Correção |
+|---|---|
+| Concatenar entrada do usuário em SQL | Parâmetros (`Variable`, `:nome`, API tipada) |
+| Repository retorna `Future` ou lança exceção | `TaskEither` + `tryCatch` |
+| Classe de banco usada em controller/UI | Injetar repository/DAO |
+| Abrir a mesma classe de banco várias vezes | Instância única injetada |
+| Mudar tabela sem migration/`schemaVersion` | Migration versionada |
+| Migration `stepByStep` usando tabelas atuais | Usar `schema.*` |
+| Query sem `await` dentro de `transaction` | `await` em tudo |
+| `getSingle` onde a linha pode não existir | `getSingleOrNull` |
+| Listar sem paginar/ordenar | Paginação + `orderBy` estável |
+| FK no SQLite sem `PRAGMA foreign_keys = ON` | Ligar no `beforeOpen` |
+| Devolver `*Data`/`Companion` para o domínio | Mapear para modelo do domínio |
+| Expor `error.toString()`/SQL ao cliente | Mensagem genérica; causa só em log |
+| Credenciais fixas no código | Variáveis de ambiente/segredos |
+| Esquecer o `build_runner` | Rodar após mudar tabelas/DAOs |

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

@@ -0,0 +1,17 @@
+# Checklist de revisão
+
+- [ ] `fpdart` instalado; repository/service/controller retornam `TaskEither` e o banco está dentro de `TaskEither.tryCatch`?
+- [ ] Estrutura existente do projeto preservada (pastas, migrations, singleton)?
+- [ ] Classe de banco só dentro do repository/DAO, injetada; instância única?
+- [ ] Nenhuma entrada do usuário concatenada em SQL; credenciais fora do código?
+- [ ] Mensagem ao cliente sem SQL/causa original?
+- [ ] Mudou schema? `schemaVersion` incrementado e migration escrita/testada?
+- [ ] Mudou tabela/DAO/annotation? `build_runner` rodado?
+- [ ] Defaults escolhidos corretamente (`clientDefault` × default no banco)?
+- [ ] FKs com `onDelete` definido; SQLite com `PRAGMA foreign_keys = ON`?
+- [ ] Listas paginadas (`page`/`pageSize`, `items/total/page/pageSize`) e ordenadas?
+- [ ] Toda chamada em `transaction` com `await`?
+- [ ] `getSingle` só onde a linha certamente existe?
+- [ ] Testes com banco em memória; `close()` no `tearDown`?
+- [ ] Dialeto correto (`build.yaml`, conexão, tipos)?
+- [ ] Docs `///` nas APIs públicas?

package/content/skills/driftorm/references/database-and-connection.md

@@ -0,0 +1,22 @@
+# Classe de banco e conexão
+
+## Classe de banco
+
+- Uma `@DriftDatabase(tables: [...], daos: [...])` que estende `_$NomeDatabase`, com `part 'arquivo.g.dart';`.
+- O construtor aceita um `QueryExecutor?` opcional para injetar banco em memória nos testes: `AppDatabase([QueryExecutor? e]) : super(e ?? _open());`.
+- Pragmas e seed vão em `beforeOpen` (roda a cada abertura); condicione o seed com `details.wasCreated`.
+- Feche com `await db.close()` no fim do ciclo de vida (testes, shutdown do servidor).
+
+## Instância única e DI
+
+- Uma instância por arquivo/banco. O mecanismo de DI é o do projeto: middleware (Dart Frog), construtor/factory, ou o container que o app já usa. Esta skill não impõe nenhum.
+- Quem constrói o banco é a **raiz de composição** (ponto de entrada/middleware). Repositories recebem a classe de banco pelo construtor.
+- **Projeto existente com singleton global** (ex.: `final db = AppDb(openConnection())` lido de variáveis de ambiente na importação): mantenha o padrão, não o trate como erro. Em código novo, prefira criar a instância na raiz de composição, o que facilita testes.
+
+## Conexão fora da thread principal
+
+- Flutter: `driftDatabase(name: ...)` (`drift_flutter`).
+- Dart puro SQLite: `NativeDatabase.createInBackground(File(...))`.
+- Postgres: `PgDatabase(...)`; veja `postgres/connection.md`.
+
+Detalhes por dialeto: `sqlite/connection.md`, `postgres/connection.md`. Exemplos: `examples/database.dart`, `examples/connection_sqlite.dart`, `examples/connection_postgres.dart`.

package/content/skills/driftorm/references/dialects.md

@@ -0,0 +1,17 @@
+# SQLite × Postgres
+
+Os dois dialetos têm o mesmo peso. Identifique o do projeto (`pubspec.yaml`) e leia a pasta correspondente.
+
+| Tema | SQLite | Postgres |
+|---|---|---|
+| Pacotes | `sqlite3` / `drift_flutter` | `postgres`, `drift_postgres` |
+| Conexão | arquivo local, isolate | rede, credenciais, SSL (`postgres/connection.md`) |
+| `build.yaml` | padrão | `sql.dialects: [postgres]` |
+| FKs | desligadas; `PRAGMA foreign_keys = ON` | sempre ativas |
+| Tipos | tipagem dinâmica; `DateTime` inteiro/texto | tipos fortes; `timestamptz`, `uuid`, `jsonb` (`postgres/types-and-defaults.md`) |
+| Defaults no banco | `currentDateAndTime`, `Constant` | também `gen_random_uuid()`, `now()` |
+| Migrations | `ALTER TABLE` limitado (recriar tabela) | `ALTER TABLE` rico; DDL transacional (`postgres/migrations.md`) |
+| Concorrência | um escritor; WAL | multiusuário; pool/locks |
+| Testes | `NativeDatabase.memory()` | SQLite em memória p/ lógica geral; Postgres real (container) quando usar recursos do dialeto |
+
+Código portável: evite SQL cru específico de dialeto no repository sem necessidade; quando usar, isole e comente.

package/content/skills/driftorm/references/drift-files.md

@@ -0,0 +1,20 @@
+# Arquivos `.drift` (opcional)
+
+Modo SQL-first do Drift: tabelas e queries escritas em SQL num arquivo `.drift`; o gerador **valida o SQL em tempo de build** e gera métodos Dart tipados.
+
+## Quando usar
+
+- Queries complexas (CTE, agregações, SQL específico) em que a API Dart fica verbosa.
+- Preferível a `customSelect` quando precisar de SQL, pois é checado na compilação.
+
+## Quando não usar
+
+- Projeto existente que declara tudo em Dart: mantenha. Não misture estilos sem necessidade.
+- CRUD simples: a API tipada basta.
+
+## Como
+
+- Inclua os arquivos em `@DriftDatabase(include: {'queries.drift'})`.
+- Nomeie cada query (`findByOwner: SELECT * FROM orders WHERE owner_id = :ownerId;`); parâmetros nomeados evitam concatenação.
+- Em Postgres, o dialeto precisa estar em `build.yaml` (`references/setup.md`).
+- O repository chama o método gerado dentro de `TaskEither.tryCatch`, como qualquer outro acesso.

package/content/skills/driftorm/references/migrations.md

@@ -0,0 +1,26 @@
+# Migrations
+
+## Aviso: projeto existente
+
+Se o projeto **já tem** migrations (manuais, `if (from < n)`, `customStatement`, sem snapshots), **mantenha o estilo dele**: não migre para `stepByStep`/`make-migrations` sem pedido. Aplique as demais regras, em especial segurança e idempotência. O fluxo abaixo é o padrão DS9 para **projetos novos**.
+
+## Regras gerais (qualquer estilo)
+
+- Mudou o schema → incremente `schemaVersion` e escreva a migration. O Drift não altera bancos existentes.
+- DDL idempotente quando possível (`IF NOT EXISTS`, `ADD COLUMN IF NOT EXISTS` em Postgres).
+- Migration nunca apaga dados sem backup/confirmação explícita; renomear = criar + copiar + remover.
+- SQL em `customStatement` é fixo (sem entrada do usuário).
+- Evite queries de dados em callbacks de migration, salvo após o schema chegar ao estado esperado.
+- `beforeOpen`: pragmas e seed; use `details.wasCreated`/`details.hadUpgrade`. Não coloque lógica pesada.
+- Teste a migração partindo de um banco da versão anterior.
+
+## Padrão DS9 para projetos novos: guiado
+
+1. Registre o banco em `databases:` no `build.yaml` e rode `dart run drift_dev make-migrations` **antes** da primeira mudança (salva o schema inicial em `drift_schemas/`).
+2. A cada mudança: incremente `schemaVersion`, rode `make-migrations` de novo e escreva o passo `fromXToY`.
+3. Escreva com `stepByStep(from1To2: ..., from2To3: ...)` usando o `schema` recebido, **nunca** as tabelas atuais da classe. Extraia para um getter de extensão em `GeneratedDatabase`.
+4. Rode os testes de migration gerados (`test/drift/`) e versione `drift_schemas/`.
+
+Exemplos: `examples/migration_step_by_step.dart` (guiado), `examples/migration_manual.dart` (estilo manual de projetos existentes).
+
+Postgres: `postgres/migrations.md`.

package/content/skills/driftorm/references/performance.md

@@ -0,0 +1,10 @@
+# Performance
+
+- Índices em colunas muito filtradas/ordenadas e em FKs consultadas (`@TableIndex`).
+- Pagine sempre listas que podem crescer; ordene de forma estável.
+- Evite N+1: não faça uma query por item de um loop; use join ou `isIn` com lista de ids.
+- Use `batch((b) { b.insertAll(...); })` para muitos inserts.
+- Prefira `count()` a carregar linhas só para contar (quando o projeto permitir).
+- `watch()` só onde a UI precisa de reatividade; cada stream mantém uma query viva.
+- Selecione apenas colunas necessárias em listas grandes (`addColumns`/`selectOnly`).
+- Postgres: use `EXPLAIN ANALYZE` em queries lentas; considere índices parciais e pool de conexões.

package/content/skills/driftorm/references/queries-and-pagination.md

@@ -0,0 +1,46 @@
+# Queries e paginação
+
+## API
+
+- Prefira a API tipada (`select`, `into`, `update`, `delete`, joins) a SQL cru.
+- SQL cru (`customSelect`/`customStatement`) só quando necessário (ex.: upsert `ON CONFLICT ... RETURNING`); sempre com `variables:` parametrizadas; `customSelect` precisa de `readsFrom` para funcionar com `watch`.
+- Insert: `Companion.insert(...)` (só campos sem default são obrigatórios). Update parcial: `Companion(campo: Value(x))`.
+- `get()` para leitura única; `watch()` para UI reativa (já emite o valor atual; não combine com `get()`).
+- `getSingle()` lança se não houver exatamente uma linha; para ausência válida use `getSingleOrNull()`.
+- Join: `select(a).join([innerJoin(b, b.id.equalsExp(a.bId))])`; leia com `row.readTable(a)`.
+- Ordene sempre que paginar, com desempate estável (ex.: `createdAt` e depois `id`).
+
+## Paginação (padrão DS9)
+
+Entrada e saída:
+
+```dart
+/// Pedido de paginação.
+class PaginationRequest {
+  const PaginationRequest({required this.page, required this.pageSize});
+  final int page;      // base 1
+  final int pageSize;
+}
+
+/// Resultado paginado.
+class PaginateResponse<T> {
+  PaginateResponse({required this.items, required this.total, required this.page, required this.pageSize});
+  final List<T> items;
+  final int total;
+  final int page;
+  final int pageSize;
+  int get totalPages => (total / pageSize).ceil();
+}
+```
+
+- Defaults ao ler a query string: `page = 1`, `pageSize = 10`.
+- Offset: `(page - 1) * pageSize`; `limit(pageSize, offset: offset)`.
+- Total: consulta da mesma base de filtros, sem `limit`. O padrão do projeto de referência calcula o total carregando as linhas (`base.get().then((r) => r.length)`); prefira, quando o projeto permitir, `count()` (`table.id.count()` com `addColumns`) para não trazer todas as linhas. **Em projeto existente, mantenha o que ele já usa.**
+- Valide e limite `page >= 1` e `pageSize` entre 1 e um máximo (ex.: 100) na borda (controller/DTO) para evitar consultas gigantes.
+- O repository devolve `TaskEither<BusinessException, PaginateResponse<T>>`.
+
+Exemplo: `examples/pagination.dart`.
+
+## Agregações
+
+- `table.id.count()`, `sum()`, `avg()`, `max()`, `min()` com `addColumns([...])` e `groupBy`. Filtros condicionais com `Expression.and`/`where`.

package/content/skills/driftorm/references/repositories-taskeither.md

@@ -0,0 +1,29 @@
+# Repository / DAO com `TaskEither`
+
+## Regra
+
+Toda camada (controller, service, repository) retorna `TaskEither<Falha, T>`. No repository, a falha é `BusinessException` (camada de erro de persistência/negócio, veja `hex-pattern-dart`/`dart-frog`).
+
+- Envolva **todo** acesso ao banco em `TaskEither.tryCatch(() async {...}, (error, stackTrace) => BusinessException(...))`.
+- Nunca deixe `Future` com exceção sair do repository; nunca converta falha em sucesso vazio.
+- O `.run()` acontece só na borda (rota/handler/UI).
+- A causa original (`error`, `stackTrace`) vai só para log; a mensagem ao cliente é genérica.
+- Entidade ausente: modele no tipo (`Order?` no `Right`) e deixe o service decidir (404), em vez de lançar.
+
+## Port × repository
+
+- O **port** (`OrderRepositoryPort`) fica no domínio, sem import de `drift`.
+- O **repository** (`OrderRepository implements OrderRepositoryPort`) fica no adapter e usa a classe de banco injetada.
+- Converta linhas do Drift em **modelos do domínio** dentro do repository; não vaze `*Data`/`Companion` para fora.
+
+## DAO × repository
+
+- Com DAOs (`@DriftAccessor`), o repository delega ao DAO dentro do `tryCatch`; o DAO retorna `Future`/`Stream` (camada interna de acesso).
+- Sem DAOs (comum em projetos existentes), o repository usa a classe de banco direto. Mantenha o que o projeto usa.
+- Streams (`watch`) em apps Flutter: o repository expõe `Stream` apenas quando a camada de UI precisa reagir; as operações pontuais continuam `TaskEither`.
+
+## Transação dentro do repository
+
+Veja `references/transactions.md`: a transação inteira fica dentro de um único `tryCatch`.
+
+Exemplos: `examples/repository_hex.dart`, `examples/pagination.dart`.

package/content/skills/driftorm/references/setup.md

@@ -0,0 +1,37 @@
+# Setup e geração de código
+
+## Dependências
+
+| Alvo | `dependencies` | `dev_dependencies` |
+|---|---|---|
+| Flutter (SQLite) | `drift`, `drift_flutter`, `path_provider` | `drift_dev`, `build_runner` |
+| Dart puro (SQLite) | `drift`, `sqlite3` | `drift_dev`, `build_runner` |
+| Dart puro (Postgres) | `drift`, `postgres`, `drift_postgres` | `drift_dev`, `build_runner` |
+| Todos (padrão DS9) | `fpdart` | — |
+
+- `fpdart` é obrigatório no padrão DS9 (`TaskEither`). Se não estiver instalado, avise e peça para instalar.
+- Mantenha as versões já usadas pelo projeto; só sugira upgrade se pedido.
+
+## Geração
+
+- Uma vez: `dart run build_runner build`.
+- Em desenvolvimento: `dart run build_runner watch`.
+- Se houver conflito de saídas: `dart run build_runner build --delete-conflicting-outputs`.
+- Versione ou não os `*.g.dart` conforme a convenção do projeto; não mude isso por conta própria.
+
+## `build.yaml`
+
+```yaml
+targets:
+  $default:
+    builders:
+      drift_dev:
+        options:
+          # Postgres: gera SQL do dialeto correto.
+          sql:
+            dialects: [postgres]   # SQLite: [sqlite]
+```
+
+- Por padrão o gerador só emite SQL de SQLite; em Postgres, declare o dialeto.
+- Para projetos novos em SQLite, considere `store_date_time_values_as_text: true` (ISO-8601 com fuso). Em projeto existente, **não mude**: altera a leitura dos dados já gravados.
+- Para migrations guiadas, registre o banco em `databases:` (veja `references/migrations.md`).

package/content/skills/driftorm/references/tables-and-columns.md

@@ -0,0 +1,43 @@
+# Tabelas e colunas
+
+- Tabela = classe que estende `Table`; colunas como `late final campo = tipo()();` (parênteses finais obrigatórios) ou `TextColumn get campo => text()();`. Siga o estilo já usado no projeto.
+- Colunas são não-nulas por padrão; use `.nullable()` só quando `null` tiver significado de domínio.
+- Documente a tabela e cada coluna com `///`.
+
+## Chave primária
+
+- Inteiro: `integer().autoIncrement()()`.
+- Outros casos: sobrescreva `Set<Column> get primaryKey => {id};` (só com `=>` e literal de set).
+- UUID: gere no cliente (`clientDefault`) ou no banco (veja defaults).
+
+## Defaults: cliente × banco
+
+| Situação | Use |
+|---|---|
+| Valor calculado em Dart (`DateTime.now`, uuid do app), sem exigir migration | `clientDefault(() => ...)` — padrão para código novo |
+| Default que é **parte do schema** e deve valer também para inserts fora do app (SQL, outros serviços) | `withDefault(...)` — ex.: `gen_random_uuid()`, `currentDateAndTime`, `Constant(false)` |
+| Projeto existente já usa `withDefault` | mantenha |
+
+`withDefault` altera o schema (exige migration ao adicionar/mudar); `clientDefault` não. Não há conflito: escolha pelo critério acima. Em Postgres, `gen_random_uuid()` no banco é legítimo (`postgres/types-and-defaults.md`).
+
+## Chaves estrangeiras
+
+- `.references(Tabela, #coluna, onDelete: KeyAction.cascade)`; defina `onDelete` conscientemente (`cascade`, `setNull`, `restrict`).
+- Auto-referência (`replyFrom` → mesma tabela) é permitida; use `@ReferenceName` quando houver mais de uma FK para a mesma tabela.
+- SQLite: FKs vêm desligadas; ligue com `PRAGMA foreign_keys = ON` no `beforeOpen`.
+
+## Integridade e índices
+
+- `.unique()`, `uniqueKeys` para unicidade composta, `.check(expr)` para validação (prefira `check` a `withLength`, que só valida em Dart).
+- `@TableIndex(name: ..., columns: {#col})` para colunas muito filtradas. PK, `unique` e FK já têm índice (no Postgres a FK **não** cria índice automático no lado filho; indexe se filtrar por ela).
+
+## Enums e tipos próprios
+
+- `intEnum<T>()` ou `textEnum<T>()`; ou `TypeConverter`. Prefira `textEnum` quando a ordem do enum pode mudar (inteiro quebra ao reordenar).
+
+## Reuso
+
+- Mixins de tabela para colunas comuns (`id`, `createdAt`, `deletedAt`).
+- Soft delete: coluna `deleted` + `deletedAt`; filtre nas queries do repository, não na UI.
+
+Exemplo: `examples/table.dart`.

package/content/skills/driftorm/references/testing.md

@@ -0,0 +1,12 @@
+# Testes
+
+- Repositories/DAOs: banco em memória — `AppDatabase(NativeDatabase.memory())`; abra no `setUp`, feche no `tearDown`.
+- Flutter widget tests: `DatabaseConnection(NativeDatabase.memory(), closeStreamsSynchronously: true)`.
+- Repository retorna `TaskEither`: execute com `.run()` e inspecione o `Either` (`isRight()`, `match`).
+- Cubra: caminho feliz, ausência (`null`), violação de unicidade/FK (vira `Left(BusinessException)`), paginação (página 1, última, vazia), transação com rollback.
+- Services: use um fake do **port** (sem Drift); o Drift só aparece nos testes do repository.
+- Migrations: use os testes gerados por `make-migrations` (`test/drift/`); em estilo manual, crie banco na versão anterior, rode a migration e verifique o schema/dados.
+- Postgres: lógica genérica pode rodar em SQLite em memória; recursos do dialeto (`gen_random_uuid`, `jsonb`, `ON CONFLICT`) exigem Postgres real (container) em teste de integração.
+- Delegue a escrita/execução ao agente `test-writer`.
+
+Exemplo: `examples/test.dart`.

package/content/skills/driftorm/references/transactions.md

@@ -0,0 +1,23 @@
+# Transações
+
+- Operações atômicas vão em `transaction(() async { ... })`.
+- Faça `await` em **todas** as chamadas dentro da transação. Query sem `await` pode rodar após o fechamento e causar perda de dados ou crash. Não agende timers que usem o banco dentro dela.
+- Streams criados fora da transação só notificam no commit; não escute fora um stream criado dentro.
+- Se a transação lançar, ela faz rollback. No repository, envolva a transação inteira em um único `TaskEither.tryCatch`, para que a falha vire `Left(BusinessException)`.
+- Evite chamadas de rede dentro da transação (segura conexão e locks).
+- Em Postgres, transações longas seguram locks; mantenha curtas. Isolation level e `SELECT ... FOR UPDATE` exigem SQL cru parametrizado (`postgres/types-and-defaults.md`).
+
+```dart
+TaskEither<BusinessException, void> moveItems(String from, String to) =>
+    TaskEither.tryCatch(
+      () => _db.transaction(() async {
+        await (_db.update(_db.itemTable)..where((t) => t.listId.equals(from)))
+            .write(ItemTableCompanion(listId: Value(to)));
+        await (_db.delete(_db.listTable)..where((t) => t.id.equals(from))).go();
+      }),
+      (e, s) => BusinessException(
+        domainName: 'list', statusCode: 500, message: 'Falha ao mover itens.',
+        error: e, stackTrace: s,
+      ),
+    );
+```

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

@@ -0,0 +1,11 @@
+# SQLite — conexão
+
+- Flutter: `driftDatabase(name: 'app', native: DriftNativeOptions(databaseDirectory: getApplicationSupportDirectory))` (`drift_flutter`).
+- Dart puro: `NativeDatabase.createInBackground(File(path))` — roda em isolate, fora da thread principal.
+- Testes: `NativeDatabase.memory()`.
+- Ligue FKs no `beforeOpen`: `await customStatement('PRAGMA foreign_keys = ON');`.
+- Considere WAL (`PRAGMA journal_mode = WAL`) para leitura concorrente em apps com muita escrita.
+- Uma instância por arquivo; várias instâncias sobre o mesmo arquivo quebram streams.
+- Web: requer configuração específica (WASM); siga a documentação oficial.
+
+Exemplo: `examples/connection_sqlite.dart`.

package/content/skills/driftorm/sqlite/types-and-pragmas.md

@@ -0,0 +1,9 @@
+# SQLite — tipos e pragmas
+
+- **DateTime:** por padrão é inteiro Unix (segundos, sem fuso). Em projeto **novo**, considere `store_date_time_values_as_text: true` (ISO-8601). Em projeto existente, **não mude**.
+- **Tipagem dinâmica:** o SQLite aceita valor de tipo diferente; confie na API tipada do Drift, não em SQL cru.
+- **Defaults:** `clientDefault` por padrão; `withDefault(currentDateAndTime)`/`Constant(...)` quando o default for parte do schema.
+- **ALTER TABLE limitado:** renomear/remover/alterar coluna pode exigir recriar a tabela; no fluxo guiado, `m.alterTable(TableMigration(...))`.
+- **Pragmas** em `beforeOpen`: `foreign_keys = ON`; opcional `journal_mode = WAL`.
+- **Concorrência:** um escritor por vez; mantenha transações curtas.
+- **Chave primária:** `integer().autoIncrement()()` é o caso comum.

package/content/skills/flutter/SKILL.md

@@ -417,3 +417,22 @@ void main() {
 - Testes no Flutter: https://docs.flutter.dev/testing/overview
 - Effective Dart: https://dart.dev/effective-dart
 - Skills oficiais do Flutter: https://github.com/flutter/skills
+
+## Registro de atividade (obrigatório)
+
+Siga o **padrão de registro DS9** (o mesmo da skill `debugger`): ao aplicar estas diretrizes em uma tarefa (features, providers, services, views, testes), **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**.
+
+| 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 |
+
+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`.
+
+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/hex-pattern-dart/SKILL.md

@@ -81,3 +81,24 @@ Use `list_skill_files` e `get_skill_file` com `skill: hex-pattern-dart`.
 | Árvore de pastas de exemplo | `examples/structure-tree.md` |
 | Port (`<Papel>Port`), service e adapters (pseudocódigo) | `examples/port.md`, `examples/service.md`, `examples/adapter-in.md`, `examples/adapter-out.md` |
 | Hierarquia de exceções | `examples/errors.md` |
+
+## Registro de atividade (obrigatório)
+
+Siga o **padrão de registro DS9** (o mesmo da skill `debugger`): ao aplicar este padrão em uma tarefa (camadas, ports, adapters, erros), **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**.
+
+| 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 |
+
+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`.
+
+Registre também cada arquivo de `references/` ou `examples/` consultado.
+
+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/hex-pattern-dart/examples/adapter-in.md

@@ -8,13 +8,12 @@ class OrderController
 
   OrderController(this._service)
 
-  Task<Response> getById(Context context, String id)
+  TaskEither<ClientException, OrderResponse> getById(Context context, String id)
     return _service.getById(id, context.requesterId)
       .mapLeft(toClientException)                  // BusinessException -> ClientException
-      .match(
-        (client) => Response(status: client.statusCode, body: client.message),
-        (order)  => Response.ok(OrderResponse.from(order)),
-      )
+      .map(OrderResponse.from)                     // modelo -> DTO
+
+// A rota (borda) executa .run() e converte Left/Right em Response.
 
 toClientException(BusinessException e)
   safe = e.statusCode >= 500 ? "Erro interno" : e.message   // 5xx genérico

package/content/skills/hex-pattern-dart/references/persistence.md

@@ -1,6 +1,6 @@
 # Persistência agnóstica
 
-O padrão não prescreve banco nem ORM. Para a tecnologia do projeto, consulte a skill correspondente via `list_skills`/`recommend_for_task` e preserve o que já existe.
+O padrão não prescreve banco nem ORM. Para a tecnologia do projeto, consulte a skill correspondente via `list_skills`/`recommend_for_task` (ex.: `driftorm` para Drift) e preserve o que já existe.
 
 ## Contrato
 
@@ -18,6 +18,6 @@ O padrão não prescreve banco nem ORM. Para a tecnologia do projeto, consulte a
 
 1. Toda chamada de I/O dentro de `TaskEither.tryCatch`.
 2. Falha vira `BusinessException` com mensagem segura.
-3. "Não encontrado" é resultado explícito (`left` com status adequado ou `Option`), nunca `null` implícito.
+3. "Não encontrado" é resultado explícito (`left` com status adequado, `Option` ou tipo anulável explícito no `Right`), nunca `null` implícito.
 4. Transação: abra no adapter; o service expõe a operação de negócio completa, sem conhecer a transação.
 5. Migrations seguem a skill de persistência do projeto e não alteram estrutura existente sem pedido.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ds9-solutions/mcp",
-  "version": "0.3.0",
+  "version": "0.5.0",
   "description": "Servidor MCP da DS9: expõe skills e subagentes oficiais para qualquer IDE/LLM com suporte a MCP",
   "type": "module",
   "license": "UNLICENSED",

package/content/skills/docker/SKILL.md

@@ -1,104 +0,0 @@
----
-name: docker
-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 Node.js e seus serviços de apoio (MySQL, etc.) nos projetos da empresa.
-
-## Dockerfile multi-stage (obrigatório)
-
-Toda aplicação Node.js usa build multi-stage: uma etapa de build (com devDependencies e compilação TypeScript) e uma etapa final enxuta só com o necessário para rodar.
-
-```dockerfile
-# ---- deps & build ----
-FROM node:20-alpine AS build
-WORKDIR /app
-COPY package.json package-lock.json ./
-RUN npm ci
-COPY . .
-RUN npm run build
-
-# ---- runtime ----
-FROM node:20-alpine AS runtime
-WORKDIR /app
-ENV NODE_ENV=production
-COPY package.json package-lock.json ./
-RUN npm ci --omit=dev
-COPY --from=build /app/dist ./dist
-USER node
-EXPOSE 3000
-CMD ["node", "dist/main.js"]
-```
-
-Regras obrigatórias:
-
-- Usar imagem base fixada por tag específica (ex.: `node:20-alpine`), nunca `latest`.
-- `npm ci` (não `npm install`) para builds reprodutíveis a partir do `package-lock.json`.
-- A imagem final **não** contém devDependencies, código-fonte TypeScript, nem ferramentas de build — só `dist/` (ou equivalente) e `node_modules` de produção.
-- Rodar como usuário não-root (`USER node`, já disponível na imagem oficial), nunca `root` em produção.
-- `.dockerignore` sempre presente, excluindo `node_modules`, `.git`, `.env*`, arquivos de teste e artefatos locais.
-
-## 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 (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.
-
-## docker-compose para ambiente local
-
-- Um serviço por responsabilidade (`app`, `mysql`, eventual `redis`/fila), nunca múltiplos processos no mesmo container.
-- Serviço de banco (`mysql`) usa volume nomeado para persistir dados entre restarts (`volumes: db_data:/var/lib/mysql`) e `healthcheck` para que a aplicação só suba depois do banco pronto (`depends_on: condition: service_healthy`).
-- Exemplo mínimo:
-
-```yaml
-services:
-  app:
-    build: .
-    env_file: .env
-    ports: ["3000:3000"]
-    depends_on:
-      mysql:
-        condition: service_healthy
-
-  mysql:
-    image: mysql:8.0
-    environment:
-      MYSQL_DATABASE: app_db
-    volumes: ["db_data:/var/lib/mysql"]
-    healthcheck:
-      test: ["CMD", "mysqladmin", "ping", "-h", "localhost"]
-      interval: 5s
-      timeout: 5s
-      retries: 10
-
-volumes:
-  db_data:
-```
-
-## Tamanho e cache de imagem
-
-- Ordene as instruções do Dockerfile das que mudam menos (dependências) para as que mudam mais (código-fonte), copiando `package.json`/`package-lock.json` antes do restante do código para aproveitar cache de camadas do `npm ci`.
-- Prefira imagens `-alpine`/`-slim` para reduzir superfície de ataque e tamanho, validando compatibilidade de dependências nativas (ex.: pacotes com binários compilados) antes de adotar.
-
-## Segurança de imagem
-
-- Rode scan de vulnerabilidade (ex.: `docker scout`/Trivy, conforme ferramenta padrão do CI da empresa) na imagem final antes de publicar em produção.
-- Nunca exponha a porta de debug/inspeção do Node (`--inspect`) em imagens de produção.
-- Fixe versões de imagens base por tag (idealmente com digest) para builds reprodutíveis e auditáveis.
-
-## Checklist ao criar/revisar Dockerfile/compose
-
-1. Build é multi-stage e a imagem final não tem devDependencies/código-fonte?
-2. Container roda como usuário não-root?
-3. Nenhum segredo está hardcoded no Dockerfile ou no compose versionado?
-4. `.dockerignore` existe e exclui `node_modules`, `.git`, `.env*`?
-5. Serviços dependentes (banco) têm `healthcheck` e `depends_on` configurados corretamente?
-
-## Não fazer
-
-- Não usar `FROM node:latest` ou qualquer tag flutuante em produção.
-- Não rodar o processo da aplicação como `root`.
-- Não commitar `.env` com valores reais nem copiá-lo para dentro da imagem.
-- Não usar `npm install` no build de imagem (usar `npm ci`).