@whanext/core 0.8.0 → 0.11.0

package/CHANGELOG.md

@@ -1,7 +1,59 @@
 # Changelog
 
+
+## 0.11.0 - Command discovery
+
+- `CommandRouter.load()` carrega diretórios de comandos diretamente pelo router.
+- `loadCommands()` agora aceita `URL` além de caminhos em string.
+- Autoload reconhece `.ts`, `.mts` e `.cts` por padrão, além de JavaScript.
+- `CommandContext` agora expõe `ctx.commands` (catálogo somente-leitura) e `ctx.prefix`.
+- Menus e comandos de ajuda podem consultar o catálogo sem factory ou referência global ao app.
+- Mantém compatibilidade com `defineCommand`, `defineCommands`, `defineSubcommand` e `defineCommandGroup`.
+
 Todas as mudanças relevantes do projeto serão registradas neste arquivo.
 
+## 0.10.0
+
+### Adicionado
+
+- `CommandContext`, uma interação enriquecida que continua compatível com o modelo `Message` legado.
+- `ctx.reply()`, `ctx.defer()`, `ctx.edit()`, `ctx.react()`, `ctx.unreact()`, `ctx.delete()` e respostas com exclusão programada.
+- `option.string`, `number`, `boolean`, `enum`, `user` e `duration`, com inferência de tipos, obrigatoriedade e validações.
+- `defineCommandGroup()` e `defineSubcommand()` para comandos como `&grupo abrir` e `&grupo fechar`.
+- Guards reutilizáveis para grupo, privado, admin, bot admin e regras customizadas.
+- Middleware global e por comando, além de hooks `beforeExecute`, `afterExecute` e `onError`.
+- Cooldown por usuário, chat, usuário+chat ou global, com limpeza automática de entradas expiradas.
+- Controle de concorrência com estratégias `parallel`, `reject`, `queue` e `replace`.
+- `app.commands`, catálogo consultável, categorias, busca e help gerado por metadados.
+- Localizações de nome, aliases e descrição sem duplicar definições.
+- Códigos de erro `COMMAND_COOLDOWN` e `COMMAND_BUSY`.
+
+### Compatibilidade
+
+- `app.router()` continua retornando o mesmo router disponível em `app.commands`.
+- `onlyGroup`, `onlyPrivate`, `onlyAdmin` e `botMustBeAdmin` continuam suportados.
+- Comandos legados com `execute(message, args)` continuam funcionando sem alteração.
+- `loadCommands()` agora também reconhece grupos de comandos.
+
+## 0.9.0
+
+### Alterado
+
+- Baileys atualizado de `7.0.0-rc13` para `7.0.0-rc14`.
+- O provider agora fornece `cachedGroupMetadata` ao Baileys, evitando consultas redundantes ao WhatsApp no fan-out de mensagens em grupos.
+- O cache interno usado pelo envio possui TTL, LRU limitado, deduplicação de buscas concorrentes e proteção contra a reinserção de resultados invalidados durante uma busca.
+- `MemoryCache` agora promove corretamente chaves sobrescritas na ordem LRU.
+
+### Adicionado
+
+- `MemoryCache.stats()` para observar hits, misses, sets, evictions e expirations.
+- `MemoryCache.prune()` para remover entradas expiradas de forma explícita.
+
+### Compatibilidade
+
+- Nenhuma alteração é necessária nos comandos ou na API pública existente.
+- Sessões criadas pela v0.8 continuam compatíveis; o auth state multifile do Baileys 7 já persiste as chaves de LID, device list e TC token exigidas pela migração.
+
 ## 0.8.0
 
 ### Adicionado

package/README.md

@@ -401,6 +401,137 @@ const app = await create({
 
 ## Comandos
 
+O sistema moderno usa um contexto semelhante às interactions do Discord. `ctx` contém a mensagem normalizada, usuário, chat, grupo, services, options, sinal de cancelamento e helpers de resposta.
+
+```ts
+import {
+  defineCommand,
+  guards,
+  option,
+} from '@whanext/core';
+
+app.commands.command(
+  defineCommand({
+    name: 'ban',
+    aliases: ['banir'],
+    description: 'Remove um membro do grupo.',
+    category: 'moderação',
+
+    guards: [
+      guards.group(),
+      guards.userAdmin(),
+      guards.botAdmin(),
+    ],
+
+    options: {
+      user: option.user({
+        description: 'Usuário que será removido.',
+        required: true,
+      }),
+      reason: option.string({
+        description: 'Motivo da remoção.',
+        rest: true,
+      }),
+    },
+
+    cooldown: {
+      durationMs: 5_000,
+      scope: 'user-chat',
+    },
+
+    concurrency: {
+      scope: 'chat',
+      max: 1,
+      strategy: 'queue',
+    },
+
+    async execute(ctx) {
+      const user = ctx.options.user('user');
+      const reason = ctx.options.string('reason') ?? 'Não informado';
+      const deferred = await ctx.defer('⏳ _Processando banimento..._');
+      const result = await ctx.members.remove(ctx.chatId, user);
+
+      await deferred.edit(
+        result.changed
+          ? `🔨 *Usuário banido*\n\n${user.mention} foi removido.\n• *Motivo:* ${reason}`
+          : `⚠️ O usuário não está mais no grupo.`,
+      );
+    },
+  }),
+);
+```
+
+### Subcomandos
+
+```ts
+import {
+  defineCommandGroup,
+  defineSubcommand,
+  guards,
+} from '@whanext/core';
+
+app.commands.command(defineCommandGroup({
+  name: 'grupo',
+  aliases: ['group'],
+  description: 'Gerencia o grupo.',
+  category: 'grupos',
+  guards: [guards.group(), guards.userAdmin(), guards.botAdmin()],
+
+  subcommands: [
+    defineSubcommand({
+      name: 'abrir',
+      aliases: ['open'],
+      description: 'Abre o grupo.',
+      async execute(ctx) {
+        await ctx.groups.open(ctx.chatId);
+        await ctx.reply('🔓 *Grupo aberto*');
+      },
+    }),
+    defineSubcommand({
+      name: 'fechar',
+      aliases: ['close'],
+      description: 'Fecha o grupo.',
+      async execute(ctx) {
+        await ctx.groups.close(ctx.chatId);
+        await ctx.reply('🔒 *Grupo fechado*');
+      },
+    }),
+  ],
+}));
+```
+
+Isso aceita `&grupo abrir`, `&group open`, `&grupo fechar` e `&group close` sem duplicar lógica.
+
+### Middleware e erros
+
+```ts
+app.commands.use(async (ctx, next) => {
+  const startedAt = performance.now();
+  await next();
+  app.logger.debug('Command completed', {
+    command: ctx.command.path.join(' '),
+    durationMs: performance.now() - startedAt,
+  });
+});
+
+app.commands.onError(async (ctx, error) => {
+  if (error.code === 'COMMAND_COOLDOWN') {
+    await ctx.reply('⏱️ Aguarde um pouco antes de usar novamente.');
+    return;
+  }
+
+  await ctx.reply('⚠️ *Não foi possível concluir*');
+});
+```
+
+`app.commands.catalog()`, `categories()`, `find()`, `has()` e `values()` expõem a coleção registrada. `app.commands.help(ctx, { category: 'moderação' })` gera a ajuda usando descrição, usage, opções e visibilidade dos comandos.
+
+Detalhes completos estão em [Comandos modernos](./docs/commands-v0.10.md).
+
+### API legada
+
+Comandos existentes continuam válidos:
+
 ```ts
 app.router().command(
   defineCommand({
@@ -435,81 +566,83 @@ Restrições disponíveis:
 
 `ArgsParser` possui `string`, `number`, `boolean`, `enum`, `user`, `duration`, `peek`, `skip` e `rest`. `args.user()` retorna `User`, nunca uma string crua.
 
-### Carregando comandos de uma pasta
+### Descoberta automática de comandos
 
-`loadCommands` importa e registra todos os comandos de um diretório, sem precisar listar cada arquivo manualmente. Um arquivo pode conter um ou vários comandos:
+A forma recomendada agora é deixar cada arquivo de comando autossuficiente e pedir ao próprio router para descobrir a árvore inteira. Não é necessário manter `index.ts` por pasta nem um arquivo central de imports:
 
 ```ts
-import { loadCommands } from '@whanext/core';
+const app = await create({ prefix: '&' });
 
-await loadCommands(app.router(), './commands');
+await app.commands.load(new URL('./commands/', import.meta.url));
 ```
 
-Para um comando por arquivo, continue usando `defineCommand` normalmente:
+O mesmo código funciona em desenvolvimento TypeScript (com um runtime/loader como `tsx`) e depois do build: o loader reconhece `.ts`, `.mts`, `.cts`, `.js`, `.mjs` e `.cjs` por padrão. O diretório é percorrido recursivamente.
 
-```ts
-// commands/ping.js
-export default defineCommand({
-  name: 'ping',
-  description: 'Responde pong.',
-  async execute(message) {
-    await app.message.reply(message, 'pong');
-  },
-});
+```text
+src/commands/
+├── admin/
+│   ├── ban.ts
+│   ├── mute.ts
+│   └── warn.ts
+├── group/
+│   ├── access.ts
+│   └── pin.ts
+└── general/
+    ├── menu.ts
+    └── profile.ts
 ```
 
-Para manter comandos relacionados juntos, use `defineCommands`. Esse é o formato recomendado para módulos com vários comandos:
+Um arquivo pode exportar um comando:
 
 ```ts
-// commands/moderation.ts
-import { defineCommand, defineCommands } from '@whanext/core';
-
-const mute = defineCommand({
-  name: 'mute',
-  description: 'Silencia um membro.',
-  async execute(message, args) {
-    // ...
-  },
-});
-
-const unmute = defineCommand({
-  name: 'unmute',
-  description: 'Remove o silêncio de um membro.',
-  async execute(message, args) {
-    // ...
+export default defineCommand({
+  name: 'ping',
+  description: 'Responde pong.',
+  async execute(ctx) {
+    await ctx.reply('pong');
   },
 });
-
-export default defineCommands(mute, unmute);
 ```
 
-Vários exports nomeados também são descobertos automaticamente:
+Ou vários comandos relacionados no mesmo módulo:
 
 ```ts
 export const mute = defineCommand({ /* ... */ });
 export const unmute = defineCommand({ /* ... */ });
 ```
 
-Exports auxiliares, como constantes e metadados, são ignorados quando o módulo contém ao menos um comando válido. Se o mesmo objeto de comando aparecer em uma coleção e em um export nomeado, ele será registrado apenas uma vez.
+Também é possível exportar uma coleção com `defineCommands(...)`. Exports auxiliares são ignorados quando o módulo contém pelo menos um comando válido, e o mesmo objeto não é registrado duas vezes.
 
-Por padrão, `loadCommands` procura arquivos `.js`, `.mjs` e `.cjs`, incluindo subpastas. Extensões como `.ts` não são carregadas por padrão, já que o `import()` dinâmico depende de um loader do TypeScript já estar ativo no processo (`tsx`, `ts-node` ou similar); habilite explicitamente quando esse loader existir:
+Para menus dinâmicos, `CommandContext` expõe uma visão somente-leitura do catálogo e o prefixo atual:
 
 ```ts
-await loadCommands(app.router(), './commands', { extensions: ['.ts'] });
+export default defineCommand({
+  name: 'menu',
+  description: 'Mostra os comandos.',
+  async execute(ctx) {
+    const commands = ctx.commands.catalog({ category: 'administração' });
+    const lines = commands.map((command) =>
+      `${ctx.prefix}${command.path.join(' ')} — ${command.definition.description}`,
+    );
+
+    await ctx.reply(lines.join('\n'));
+  },
+});
 ```
 
-`loadCommands` também aceita qualquer objeto com um método `command()`, não apenas o router retornado por `app.router()`.
+`ctx.commands` fornece `catalog()`, `categories()`, `find()`, `has()`, `size` e `prefix`; ele não expõe detalhes internos do provider.
 
-O retorno informa os arquivos carregados e ignorados, além de cada comando registrado:
+Se for necessário controlar extensões ou recursão:
 
 ```ts
-const result = await loadCommands(app.router(), './commands');
-
-console.log(result.loaded);   // arquivos importados
-console.log(result.skipped);  // extensões não habilitadas
-console.log(result.commands); // { name, filePath }[]
+await app.commands.load(new URL('./commands/', import.meta.url), {
+  recursive: true,
+  extensions: ['.ts'],
+});
 ```
 
+`loadCommands(registrar, directory, options)` continua disponível como API de baixo nível para registradores customizados. O retorno contém arquivos carregados/ignorados e os comandos descobertos.
+
 ## Cache externo
 
 ```ts
@@ -524,12 +657,33 @@ const app = await create({
 
 O cache padrão vive na instância do app, usa LRU limitado e elimina entradas expiradas durante as leituras. Consultas simultâneas dos mesmos metadados são agrupadas em uma única chamada ao WhatsApp. Eventos e mutações de grupo invalidam automaticamente entradas relacionadas.
 
+Os mesmos metadados também alimentam internamente o `cachedGroupMetadata` do Baileys. Em grupos já aquecidos, isso remove a consulta de metadados do caminho de envio; mensagens continuam aguardando somente criptografia, upload quando houver mídia e confirmação da rede.
+
+Para observar um `MemoryCache` criado diretamente:
+
+```ts
+import { MemoryCache } from '@whanext/core';
+
+const cache = new MemoryCache({ maxEntries: 5_000 });
+
+console.log(cache.stats());
+cache.prune();
+```
+
+`stats()` informa `size`, `maxEntries`, `hits`, `misses`, `sets`, `evictions` e `expirations`.
+
+Para uma única instância, o cache padrão é suficiente mesmo com muitos grupos, desde que `memoryMaxEntries` seja dimensionado. Em várias instâncias/processos, use um `CacheStore` distribuído para o cache público; cada conexão mantém ainda um L1 local limitado para o caminho criptográfico do Baileys. Não compartilhe uma mesma sessão ativa entre processos.
+
 O cache interno de mensagens mantém até 1.000 mensagens por padrão para replies, reenvios do provider e downloads de mídia. Ajuste quando necessário:
 
 ```ts
 const app = await create({ messageCacheSize: 2_000 });
 ```
 
+Não há delay artificial no envio. Presença é enviada diretamente e previews de alta qualidade permanecem desativados no provider; mídias ainda dependem do tempo de leitura, criptografia e upload ao WhatsApp.
+
+Para limites, dimensionamento e decisões de produção, consulte [Desempenho e escala](./docs/performance-and-scale.md).
+
 ## Presença
 
 ```ts