yuzuha 0.1.4 → 0.1.7

package/CHANGELOG.md

@@ -21,6 +21,52 @@ documentos. Veja a [política completa](VERSIONING.md).
 
 </details>
 
+## v0.1.7 · 23/10/2026
+
+Loops controláveis, comparadores de arrays, regex isolada, decimais exatos e busca pela CLI, com o conteúdo preparado na 0.1.6. Esta atualização da biblioteca Yuzuha foi preparada em 23/10/2026 (v0.1.7).
+
+- `yuzuha functions --search <termo>` filtra nomes, aliases e descrições por trecho, sem distinguir maiúsculas e minúsculas. Aceita `$` inicial e combina com categoria, JSON, exportação de catálogo e filtros de plugins, preservando a ordem dos resultados.
+- Buscas sem resultados encerram com sucesso e retornam uma mensagem no terminal ou uma lista vazia em JSON. Termos vazios, ausentes ou repetidos são recusados; categorias desconhecidas continuam sendo erros.
+- Consultas paginadas de variáveis por prefixo, com TTL e cursor; índice SQLite derivado do snapshot e invalidado por trigger. Streaming UTF-8 em scripts, com backpressure, controle de loop e cancelamento.
+- `yuzuha/images` adiciona transformação opcional de PNG/JPEG/WebP com Sharp em processos limitados e canceláveis. `ctx.sendStream` lê anexos com orçamento e prazo antes do upload de bytes exigido pelo SDK.
+- Auditoria de integrações documenta configuração de shards já suportada pelo core, gerenciamento externo de processos e ausência de contratos para componentes/comandos de aplicação.
+- Tarefas aceitam prioridade persistida; `globalConcurrency` coordena claims no store compartilhado, preservando o limite local.
+- **18 funções novas**, totalizando **306**: `guildFeatures`, `leaveGuild`, `while`, `break`, `continue`, `arraySortWith`, `sortLeft`, `sortRight`, `regexTest`, `regexMatch`, `regexReplace`, `decimal`, `decimalCompare`, `decimalRound`, `queryVars`, `httpStream`, `httpChunk` e `httpChunkIndex`.
+- `ctx.guildFeatures()` copia as features do servidor; `ctx.leaveGuild()` só permite a saída solicitada pelo dono do servidor, com a mesma autorização nos scripts. Ports customizados antigos continuam válidos; ausência do recurso retorna `NATIVE_UNAVAILABLE`.
+- Loops restauram o contexto ao sair; `break` e `continue` atravessam `$try` e afetam o corpo do loop mais próximo. Comparadores usam ordenação estável e orçamento compartilhado. Decimais retornam texto e usam até 1000 dígitos, sem perda por `Number`.
+- Regex roda em workers limitados, com cancelamento, prazo e limites de entrada, correspondências e saída. O worker é incluído no tarball e não executa JavaScript fornecido pelo script.
+- Inclui as otimizações de dispatch, runtime e estado, as APIs nativas de música, a integração Lavalink v4 e a ponte de áudio descritas na entrada 0.1.6. SDK 3.3.0, schema 2 e imports anteriores permanecem compatíveis.
+- Erros do gateway e de shards chegam aos hooks `onError`/`onLog` mesmo sem listeners do usuário. Os listeners padrão permanecem ativos durante o encerramento e preservam os listeners de clients injetados.
+- O parser salta trechos de texto comum mantendo offsets, escapes e diagnósticos. A limpeza de `$httpStream` não bloqueia o comando quando a fonte deixa o cancelamento pendente.
+- Biblioteca e CLI voltam à raiz do repositório, com instalação npm, guias Markdown e exemplos incluídos no pacote. O site fica arquivado para uma etapa futura.
+
+## v0.1.6 · 22/10/2026
+
+Dispatch, argumentos, runtime e leituras de estado mais rápidos, com ferramentas nativas para música e integração Lavalink v4. Esta atualização da biblioteca Yuzuha foi preparada em 22/10/2026 (v0.1.6).
+
+- Deduplicação usa uma fila circular de 10000 entradas; mensagens ignoradas seguem um caminho curto. Prefixos estáticos são reaproveitados, o sinal de encerramento é compartilhado e serviços, mapas de argumentos e variáveis do contexto são criados sob demanda.
+- Registro individual de comandos valida conflitos antes de inserir, sem copiar todo o catálogo. Carga e recarga continuam atômicas. Argumentos simples usam tokenização por trechos; o caminho de aspas/apóstrofos evita inspecionar repetidamente a palavra em construção. Escapes, flags e erros de entrada são preservados.
+- Parser acumula trechos de texto; evaluator evita promises para literais e resolve funções com cache fraco por AST. A validação continua ativa para ASTs externos ou editados, com ordem, tipos, guards, orçamento e falhas parciais preservados.
+- Leituras pontuais em memória e JSON copiam somente o valor solicitado e respeitam TTL e ordenação das transações. Stores próprios conservam o caminho anterior; `readVariable` é uma capacidade opcional. SQLite reutiliza statements sem alterar schema, WAL ou validação antes do commit.
+- `yuzuha/music` entrega cliente Lavalink v4 com REST/WebSocket autenticados, retomada de sessão, reconexão limitada, cancelamento, limite de respostas/requisições, cache LRU com orçamento de bytes e compartilhamento de buscas simultâneas.
+- Gerenciador de música com distribuição de novos players entre nodes disponíveis, filas limitadas por servidor, avanço automático, loop, pause, skip, stop, seek, volume e filtros. Controles e eventos são serializados; falhas de PATCH preservam as faixas pendentes.
+- Sessões Lavalink perdidas são reconstruídas com concorrência limitada, posição, pausa, filtros e renovação de voz. Sessões retomadas preservam a reprodução; eventos aguardam a confirmação do handshake. Respostas antigas não alteram a fila.
+- Filas permitem remover, mover, embaralhar e consultar páginas sem copiar todo o catálogo. Controles pendentes são limitados por player; eventos de fim mantêm capacidade reservada. Nodes consideram CPU, players e frames ao distribuir carga; saídas pelo plugin ignoram os contadores de voz Discord, evitando perda falsa no balanceamento.
+- Buscas com signals distintos compartilham a requisição, com cancelamento por chamada e aborto quando todos desistem. Decode de faixas/lotes e diagnósticos de cache/rede completam a API; parsing de flags evita mapas e objetos temporários por valor.
+- `FluxerVoice` carrega `@fluxerjs/voice` opcionalmente para áudio WebM/Opus nativo. `ctx.voice` e `ctx.music` recebem serviços configurados e participam do encerramento.
+- `FluxerLavalinkBridge` e o plugin `yuzuha-audio` conectam a saída Opus do Lavalink 4.2.2 ao SDK do Fluxer. Mantêm uma publicação entre faixas, pausa, seek e filtros; transmissão incremental, limites, cancelamento e reconexão liberam os recursos por servidor. A integração local usa áudio e decoder reais, com publicação LiveKit simulada.
+- `MockMusicBackend`, `mockTrack`, exemplo offline, guia de música e benchmarks adicionais acompanham a versão. Relatórios anteriores/atuais e método estão em [BENCHMARKS.md](docs/BENCHMARKS.md). SDK 3.3.0, schema 2 e 288 funções de script permanecem compatíveis.
+
+## v0.1.5 · 22/10/2026
+
+Subcomandos e flags tipadas, ajuda derivada das definições e testes nativos com relógio controlável, com projetos gerados prontos para compartilhar. Esta atualização da biblioteca Yuzuha foi preparada em 22/10/2026 (v0.1.5).
+
+- Comandos aceitam árvores de subcomandos e flags com inferência de tipos, aliases, valores entre aspas e separador `--`. As restrições dos grupos são preservadas na execução dos filhos.
+- Ajuda detalha argumentos, flags, escolhas, valores padrão, exemplos e subcomandos. Erros de entrada incluem o uso esperado; metadados também ficam disponíveis no JSON de `check`.
+- `createTestBot`, em `yuzuha/testing`, reúne transporte, recursos simulados, estado isolado, mensagens, erros e resultados. O relógio controlável permite verificar cooldown, TTL e tarefas sem aguardar tempo real; o descarte aguarda o encerramento.
+- `init` usa dependência npm por padrão; `--local` seleciona a instalação local explicitamente. Projetos JS/TS incluem teste offline de exemplo e `npm test`.
+- SDK permanece em 3.3.0 e o catálogo mantém 288 funções. Os contratos e exemplos novos são compartilhados com a documentação e a validação do pacote instalado.
+
 ## v0.1.4 · 22/10/2026
 
 Eventos em scripts, cron com fuso, HTTP em streaming e ferramentas de manutenção e testes offline, com autorização compartilhada nos recursos. Esta atualização da biblioteca Yuzuha foi preparada em 22/10/2026 (v0.1.4).

package/README.md

@@ -1,157 +1,198 @@
 # Yuzuha
 
-Framework para bots do Fluxer: a ergonomia que falta no Fluxer.js, com comandos
-tipados, guards, estado, moderação, agendamentos e testes offline. Function mode
-(scripts no estilo ForgeScript) é opcional. Versão **0.1.4**.
+Framework TypeScript para bots do [Fluxer](https://fluxer.app), com comandos
+tipados em JavaScript/TypeScript e uma linguagem opcional de scripts.
+Os dois modos compartilham permissões, moderação, estado e recursos.
 
-```ts
-import { arg, defineCommand, Yuzuha } from 'yuzuha';
+O Yuzuha usa **Fluxer.js 3.3.0**. Você continua tendo acesso ao client original
+por `bot.client` e aos exports do SDK em `yuzuha/sdk`.
 
-const bot = new Yuzuha({ name: 'meu-bot', prefix: '!' });
+[0.1.7](CHANGELOG.md) · Node **22.13+** · ESM · [MIT](LICENSE)
 
-bot.command(defineCommand({
-  name: 'ban',
-  description: 'Bane um membro e registra um caso.',
-  args: {
-    membro: arg.user().required(),
-    motivo: arg.text().rest(),
-  },
-  async run(ctx) {
-    const caso = await ctx.mod.ban(ctx.args.get('membro'), {
-      reason: ctx.args.get('motivo') ?? '',
-    });
-    await ctx.reply(`Membro banido. Caso #${caso.id}.`);
-  },
-}));
+[Começar](#começar) · [Comandos](#escrever-comandos) · [Recursos](#recursos) · [Testes](#testar-sem-token) · [Documentação](#documentação)
+
+## Começar
+
+### Criar um bot
+
+```sh
+npx yuzuha@0.1.7 init ./meu-bot --ts
+cd meu-bot
+npm install
+npm run check
+npm run typecheck
+npm test
+cp .env.example .env
+```
 
-await bot.login();
+Preencha `FLUXER_BOT_TOKEN` no `.env` e inicie o bot:
+
+```sh
+npm run dev
 ```
 
-Uso: `!ban @membro spam no chat`. `ctx.mod.ban` verifica permissões e hierarquia,
-executa o banimento e registra o caso. O token vem de `FLUXER_BOT_TOKEN`.
-`bot.client` continua sendo o client real do Fluxer.js.
+O projeto inclui três comandos, configuração e um teste offline. Para JavaScript,
+troque `--ts` por `--js` e omita `typecheck`. Acrescente `--functions` ao `init`
+para incluir um comando de exemplo com scripts.
 
-## O que o Yuzuha adiciona ao Fluxer.js
+`npm run check`, `npm run typecheck` e `npm test` validam o projeto sem conectar o bot.
+`npm run dev` conecta e recarrega os arquivos de comando ao editar;
+`npm start` executa sem recarga automática.
 
-- Comandos com prefixos, aliases, argumentos tipados, cooldowns e permissões.
-- Guards, middleware, plugins, eventos tipados e recarga de comandos sem reiniciar.
-- Moderação compartilhada (ban, kick, timeout, unban) com casos por servidor.
-- Recursos prontos: usuários, cargos, canais, mensagens, convites, webhooks,
-  emojis, stickers, threads e fóruns, incluindo reações, membros de threads,
-  posição de cargos/canais e categorias.
-- Estado em memória, JSON ou SQLite, com transações e variáveis por escopo.
-- Agendamentos persistentes com cron, fuso IANA, concorrência e retry com jitter.
-- HTTP textual/binário, streaming e multipart, com limites e políticas por comando.
-- `MockTransport`, `mockResources` e `MemoryStore` para testar sem token.
-- Transações entre chaves, agendamentos editáveis com pausa/retry e apelidos com autorização compartilhada.
-- Limpeza de expirados, estatísticas e backup/restauração versionados com simulação.
-- `doctor`, lint JSON, cenários offline, catálogos de plugins e extensão VS Code.
-- SDK `@fluxerjs/core` **3.3.0** reexportado em `yuzuha/sdk`, sem esconder o original.
+### Usar em um projeto existente
 
-Não é um fork do Fluxer.js nem um wrapper de todos os métodos do SDK. O que não
-estiver no framework continua acessível por `bot.client` e pelos tipos originais.
+```sh
+npm install yuzuha@0.1.7
+```
 
-## Function mode (opcional)
+Use `"type": "module"` no `package.json`. O [guia inicial](docs/QUICKSTART.md)
+mostra como configurar o bot e carregar comandos.
 
-Quem preferir a sintaxe curta do ForgeScript pode usar `yuzuha/functions`. O
-runtime é ativado quando um comando com `code` ou um evento de script é registrado.
+## Escrever comandos
+
+Salve **uma das versões** abaixo em `commands/eco.ts` (`.js` para JavaScript).
+Ambas respondem a `!eco Olá, Yuzuha!` com `Olá, Yuzuha!`.
+
+### JavaScript / TypeScript
 
 ```ts
-import { script } from 'yuzuha/functions';
-import { Yuzuha } from 'yuzuha';
+import { arg, defineCommand } from 'yuzuha';
 
-const bot = new Yuzuha({ prefix: '!' });
+export default defineCommand({
+  name: 'eco',
+  description: 'Repete o texto informado.',
+  args: { texto: arg.text().rest().required() },
+  async run(ctx) {
+    await ctx.reply(ctx.args.get('texto'));
+  },
+});
+```
+
+Schemas `arg.*` inferem os tipos de argumentos e flags. Você também pode declarar
+subcomandos, checks e middleware. O [guia nativo](docs/NATIVE.md) cobre esses
+contratos, eventos, moderação e persistência.
+
+### Function mode do Yuzuha
+
+```ts
+import { script } from 'yuzuha/functions';
 
-bot.command(script({
-  name: 'ban',
-  code: '$modBan[$mentioned[1];$messageSlice[1]]$reply[Membro banido. Caso #$caseID.]',
-}));
+export default script({
+  name: 'eco',
+  description: 'Repete o texto informado.',
+  code: '$reply[$messageSlice[0]]',
+});
 ```
 
-Os dois modos compartilham guards, estado, moderação e recursos. São
-**288 funções** com referência gerada, ou use `bot.enableFunctions()` para
-pré-carregar o runtime.
+O function mode tem **306 funções** para mensagens, guards, moderação, variáveis,
+JSON, arrays, loops, eventos e agendamentos. O runtime é ativado ao registrar um
+comando com `code` ou um evento de script.
 
-`bot.scriptEvent()` registra scripts para entrada/saída de membros, edição/exclusão
-de mensagens e reações. O contexto preserva os dados disponíveis do evento e exige
-um canal real para enviar respostas. Veja [eventos](docs/EVENTS.md).
+As funções seguem as assinaturas e regras do runtime do Yuzuha. Consulte a
+[linguagem](docs/LANGUAGE.md), as [assinaturas das funções](docs/FUNCTIONS.md)
+e a [cobertura](docs/PARITY.md).
 
-## Instalar pelo npm
+## Recursos
 
-Requer Node **22.13 ou mais recente**. O pacote é ESM; use `"type": "module"`
-no `package.json` do seu projeto.
+| Área | O que está disponível |
+|---|---|
+| Comandos | Prefixos, aliases, subcomandos, argumentos e flags tipadas, cooldowns e ajuda gerada dos metadados |
+| Extensões | Plugins, eventos, checks, middleware e recarga atômica de comandos |
+| Moderação | Ban, kick, timeout, unban e moderação de voz, com permissões, hierarquia e casos por servidor |
+| Fluxer | Usuários, membros, cargos, canais, mensagens, reações, anexos, threads, convites, webhooks e expressões |
+| Dados | Memória, JSON e SQLite; TTL, transações, limpeza e backup/restauração com simulação |
+| Agendamentos | Tarefas persistentes, cron, fusos IANA, pausa/retomada, histórico e retry |
+| HTTP | Texto, bytes, streaming e multipart, com limites, cancelamento e políticas por comando |
+| Música | Lavalink v4 com plugin e ponte de áudio para Fluxer, recuperação, filas editáveis, loop, seek, volume e filtros |
+| Desenvolvimento | CLI, autocomplete e diagnósticos no VS Code, mocks e relógio controlável para testes |
 
-```sh
-npm install yuzuha@0.1.4
-```
+## Testar sem token
 
-Para gerar um bot novo:
+O scaffold já inclui um teste executável com `npm test`. Para testar o comando
+`eco` acima, crie `test/eco.test.ts` (`.js` para JavaScript):
 
-```sh
-npx yuzuha@0.1.4 init ./meu-bot --ts
-cd meu-bot
-npm install yuzuha@0.1.4
-npm run check
-npm run typecheck
-cp .env.example .env
+```ts
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { createTestBot } from 'yuzuha/testing';
+import eco from '../commands/eco.js';
+
+test('eco responde com o texto informado', async t => {
+  const fixture = createTestBot({ commands: [eco] });
+  t.after(() => fixture.destroy());
+
+  assert.equal(await fixture.send('!eco Olá, Yuzuha!'), 'success');
+  assert.equal(fixture.messages.at(-1)?.payload.content, 'Olá, Yuzuha!');
+});
 ```
 
-`init` aponta inicialmente para a instalação que o executou. O `npm install`
-acima troca essa referência local pela versão do registro, permitindo mover e
-compartilhar o projeto. Para JavaScript, use `--js` e omita `typecheck`.
-Para acrescentar um exemplo de script, use `--functions`.
+`createTestBot` usa transporte e recursos simulados, com estado isolado. O relógio
+controlável permite testar cooldown, TTL e tarefas sem aguardar tempo real.
+Veja fixtures, stores e cenários na [documentação de testes](docs/TESTING.md).
+
+## CLI
+
+Execute estes comandos no diretório do seu bot:
+
+| Comando | Uso |
+|---|---|
+| `npx yuzuha check` | Validar configuração e comandos sem login |
+| `npx yuzuha doctor` | Diagnosticar ambiente, configuração e store |
+| `npx yuzuha lint commands --json` | Analisar scripts sem importar módulos |
+| `npx yuzuha functions --category moderation` | Consultar funções e assinaturas |
+| `npx yuzuha functions --search mensagem` | Buscar funções por nome, alias ou descrição |
+| `npx yuzuha editor` | Encontrar a extensão VS Code incluída no pacote |
+
+`check` importa configurações e comandos JS/TS de confiança; a verificação de
+tipos é feita por `npm run typecheck`. A [referência da CLI](docs/CLI.md) também cobre
+catálogos de plugins, cenários offline e manutenção de dados.
+
+## Documentação
 
-Preencha `FLUXER_BOT_TOKEN` no `.env` e execute `npm run dev`.
+O [índice completo](docs/README.md) reúne os guias e as referências.
 
-## Desenvolver a biblioteca localmente
+| Quero… | Ler |
+|---|---|
+| Criar e configurar um bot | [Guia inicial](docs/QUICKSTART.md) |
+| Programar em JS/TS | [Guia nativo](docs/NATIVE.md), [framework](docs/FRAMEWORK.md) e [API](docs/API.md) |
+| Criar um bot de música | [Lavalink, filas e voz Fluxer](docs/MUSIC.md) |
+| Medir performance | [Benchmarks e comparações com a 0.1.5](docs/BENCHMARKS.md) |
+| Escrever scripts `$...` | [Linguagem](docs/LANGUAGE.md) e [referência de funções](docs/FUNCTIONS.md) |
+| Copiar exemplos | [Receitas](docs/COOKBOOK.md) e [código de exemplo](examples) |
+| Usar o editor ou diagnosticar um erro | [VS Code](docs/EDITOR.md) e [problemas comuns](docs/TROUBLESHOOTING.md) |
+| Entender a cobertura | [Paridade](docs/PARITY.md) e [funções ausentes](docs/FUNCTION-GAPS.md) |
+| Conferir mudanças e validação | [Changelog](CHANGELOG.md), [versionamento](VERSIONING.md) e [evidências](docs/VALIDATION.md) |
+
+## Desenvolver a biblioteca
+
+Na cópia do repositório:
 
 ```sh
-cd ~/Projects/yuzuha
+git clone https://github.com/horizzon3507/yuzuha.git
+cd yuzuha
 npm ci
-npm run build
-node dist/cli.js init ~/Projects/meu-bot --ts
-cd ~/Projects/meu-bot
-npm install
 npm run check
-npm run typecheck
-cp .env.example .env
+npm run smoke:package
 ```
 
-O scaffold desse fluxo usa a biblioteca local. O
-[guia inicial](docs/QUICKSTART.md) explica instalação e configuração.
-
-## Experimentar sem token
+Para experimentar os exemplos offline:
 
 ```sh
 npx tsx examples/offline.ts
 npx tsx examples/function-mode.ts
-node dist/cli.js check examples/yuzuha.config.js --json
-node dist/cli.js functions --category moderation
 ```
 
-Os exemplos usam `MockTransport`; nenhuma ação chega ao Fluxer. `check` importa
-config e comandos JS/TS de confiança, valida os scripts e não chama `login`.
-Ele não substitui o typecheck do TypeScript.
+Para gerar um bot que use sua instalação local da biblioteca:
 
-## Documentação
+```sh
+node dist/cli.js init ../meu-bot-local --ts --local
+```
 
-Comece pelo [índice da documentação](docs/README.md).
+O `init` usa a dependência npm por padrão; `--local` aponta para a instalação
+que executa a CLI. Veja [contribuição](CONTRIBUTING.md) para as regras de código
+e as verificações do projeto.
 
-| Preciso de… | Documento |
-|---|---|
-| Criar meu primeiro bot JS ou TS | [Guia inicial](docs/QUICKSTART.md) |
-| Programar comandos, eventos e plugins | [Guia nativo JS/TS](docs/NATIVE.md) |
-| Escrever scripts `$...` | [Function mode](docs/LANGUAGE.md) e [referência](docs/FUNCTIONS.md) |
-| Saber quais funções de script existem | [Lacunas auditadas](docs/FUNCTION-GAPS.md) |
-| Usar comandos, contexto e extensões | [Framework](docs/FRAMEWORK.md) e [API](docs/API.md) |
-| Copiar exemplos completos | [Receitas](docs/COOKBOOK.md) |
-| Usar a linha de comando | [CLI](docs/CLI.md) |
-| Entender módulos e dependências | [Arquitetura](docs/ARCHITECTURE.md) |
-| Escolher persistência e tratar falhas | [Estado e execução](docs/STORAGE.md) |
-| Diagnosticar ou testar | [Problemas comuns](docs/TROUBLESHOOTING.md) e [testes](docs/TESTING.md) |
-| Usar autocomplete e diagnóstico offline | [Editor e doctor](docs/EDITOR.md) |
-| Medir dispatch, runtime e memória | [Benchmarks](docs/BENCHMARKS.md) |
-| Ver evidência local | [Validação](docs/VALIDATION.md) |
-
-As mudanças estão no [changelog](CHANGELOG.md); a política de versões está em
-[VERSIONING.md](VERSIONING.md). Leia [CONTRIBUTING.md](CONTRIBUTING.md) para contribuir.
+Transformações opcionais de imagens e entrada de anexos por stream estão em
+[IMAGES.md](docs/IMAGES.md); consultas por prefixo e cursor em
+[STORAGE.md](docs/STORAGE.md), e limites das integrações em
+[INTEGRATIONS.md](docs/INTEGRATIONS.md).

package/VERSIONING.md

@@ -1,16 +1,16 @@
 # Versionamento
 
 O Yuzuha aplica o formato Hory ao histórico e usa **SemVer simples** no pacote.
-A versão desta atualização é **0.1.4**.
+A versão desta atualização é **0.1.7**.
 
 ## Pacote e histórico
 
 | Lugar | Formato nesta versão |
 |---|---|
-| `package.json` e raiz do `package-lock.json` | `0.1.4` |
-| Pacote npm e saída de `yuzuha --version` | `0.1.4` |
-| Título do changelog | `## v0.1.4 · 22/10/2026` |
-| Eventual tag Git | `v0.1.4` |
+| `package.json` e entrada raiz de `package-lock.json` | `0.1.7` |
+| Pacote npm e saída de `yuzuha --version` | `0.1.7` |
+| Título do changelog | `## v0.1.7 · 23/10/2026` |
+| Eventual tag Git | `v0.1.7` |
 
 O SDK e a CLI pertencem ao mesmo pacote. Para bibliotecas, a convenção Hory mantém
 SemVer sem `m`, sem seções por superfície e sem sufixos de canal.
@@ -30,7 +30,7 @@ estivermos em `0.x`. Ao chegar a `1.0.0`, mudanças incompatíveis exigem major;
 novas funcionalidades compatíveis, minor; correções compatíveis, patch.
 
 Os exports públicos são `yuzuha`, `yuzuha/functions`, `yuzuha/sdk`,
-`yuzuha/testing` e `yuzuha/tooling`. A organização interna de `src/` não cria estabilidade de deep
+`yuzuha/testing`, `yuzuha/tooling`, `yuzuha/music` e `yuzuha/images`. A organização interna de `src/` não cria estabilidade de deep
 imports. Schema persistido,
 gramática e funções documentadas também fazem parte da compatibilidade.
 
@@ -40,6 +40,59 @@ gerado por `init` pertence ao consumidor e não precisa acompanhar a biblioteca.
 
 ## Preparar uma atualização
 
+### Migrar para 0.1.7
+
+A distribuição 0.1.7 inclui o conteúdo preparado na 0.1.6 e acrescenta
+`yuzuha functions --search <termo>`. A busca combina com os filtros e formatos
+existentes sem alterar imports anteriores, schema 2 ou SDK 3.3.0.
+A linguagem recebe 18 funções, chegando a 306. `GuildInfo.features` e
+`UsersResources.leaveGuild` são opcionais para preservar recursos customizados;
+os novos auxiliares do contexto recusam recursos ausentes explicitamente.
+O port `Store.queryVariables` também é opcional; memória/JSON mantêm fallback
+por snapshot. SQLite cria um índice derivado automaticamente na primeira consulta,
+sem alterar schema 2. Prioridade padrão é zero e capacidade compartilhada só é
+ativada com `globalConcurrency`. `yuzuha/images` requer instalar Sharp; o restante
+da biblioteca continua independente dele. Não há mudanças obrigatórias nos bots
+existentes.
+As instruções da 0.1.6 abaixo continuam aplicáveis ao atualizar da 0.1.5.
+
+### Migrar para 0.1.6
+
+Imports, schema 2, SDK 3.3.0 e 288 funções permanecem disponíveis. Os serviços do
+contexto e seus mapas são inicializados sob demanda; as referências devolvidas
+continuam estáveis por contexto. Mensagens ignoradas não criam uma execução.
+O sinal de cancelamento pode ser compartilhado entre comandos do mesmo bot;
+não dependa de sua identidade para correlacionar execuções: use `executionID`.
+
+`Store.readVariable` é opcional e deve retornar uma cópia isolada, respeitar a
+ordenação das transações e avaliar o callback de relógio `now` dentro da leitura,
+após aguardar operações anteriores. `undefined` indica
+ausente/expirado; `null` continua sendo um valor JSON válido. Não há migração de
+disco. SQLite conserva validação do estado completo antes de cada commit.
+
+`yuzuha/music` é um import adicional. Configure `music`/`voice` explicitamente;
+o bot encerra os serviços fornecidos e o chamador fecha os nodes Lavalink.
+`@fluxerjs/voice` é um peer opcional carregado em `join`. Para áudio Lavalink no
+Fluxer, configure `FluxerLavalinkBridge` e instale o plugin `yuzuha-audio` fornecido
+pelo Yuzuha no servidor; veja [MUSIC.md](docs/MUSIC.md).
+Não há wrappers de música no function mode nesta versão.
+
+Benchmarks agora exigem a versão exata do Node e o mesmo modo de GC, suíte e
+carga. Relatórios de outro runtime devem ser executados novamente antes de comparar.
+
+### Migrar para 0.1.5
+
+Imports, argumentos posicionais e comandos existentes continuam disponíveis.
+Flags são interpretadas somente em comandos que as declaram. Grupos de
+subcomandos não declaram argumentos ou flags próprios; a folha define sua entrada.
+Permissões, checks, middleware e demais restrições dos grupos continuam valendo
+nos filhos. Veja o contrato em [NATIVE.md](docs/NATIVE.md).
+
+O scaffold agora declara a versão npm do Yuzuha. Para desenvolver contra a
+instalação que executa a CLI, use `init --local`. Projetos já gerados conservam
+suas dependências; a atualização não reescreve projetos consumidores.
+O schema de persistência permanece em 2 e o SDK em 3.3.0.
+
 ### Migrar para 0.1.4
 
 O schema persistido continua em 2. Cron, timezone, missedRun e retryJitter são
@@ -120,7 +173,7 @@ externos para idempotência. Veja [NATIVE.md](docs/NATIVE.md) e
 
 ### Procedimento
 
-1. Atualize manifest e lockfile para a mesma versão.
+1. Atualize `package.json` e regenere `package-lock.json` para a mesma versão.
 2. Acrescente a entrada no [CHANGELOG.md](CHANGELOG.md), com data real e mudanças verificáveis.
 3. Atualize migração, cobertura e documentação quando o contrato mudar.
 4. Rode `npm run check` e `npm run smoke:package` e registre a evidência.

package/benchmarks/compare.mjs

@@ -2,17 +2,23 @@ export function compareReports(current, baseline) {
   for (const field of ['platform', 'arch', 'cpu']) {
     if (current[field] !== baseline[field]) throw new Error(`Baseline incompatível: ${field}.`);
   }
-  if (current.node.split('.')[0] !== baseline.node?.split('.')[0]) throw new Error('Baseline incompatível: versão principal do Node.');
+  if (current.node !== baseline.node) throw new Error('Baseline incompatível: versão exata do Node.');
+  if (current.suite !== baseline.suite) throw new Error('Baseline incompatível: suíte.');
+  if (baseline.gc !== undefined && current.gc !== baseline.gc) throw new Error('Baseline incompatível: GC explícito.');
   for (const field of ['iterations', 'samples', 'concurrency']) {
     if (current.config[field] !== baseline.config?.[field]) throw new Error(`Baseline incompatível: ${field}.`);
   }
-  for (const field of ['catalogSize', 'payloadSize', 'soakRounds']) {
+  for (const field of ['catalogSize', 'payloadSize', 'soakRounds', 'stateKeys', 'queueSize', 'pageSize', 'fanout', 'warmup']) {
     if (baseline.config?.[field] !== undefined && current.config[field] !== baseline.config[field]) throw new Error(`Baseline incompatível: ${field}.`);
   }
   if (!Array.isArray(baseline.results)) throw new Error('Baseline sem resultados.');
   return current.results.map(row => {
     const previous = baseline.results.find(item => item.name === row.name);
     if (!previous) return { name: row.name, status: 'new' };
+    for (const field of ['iterations', 'unitsPerOperation']) {
+      if (previous[field] !== undefined && row[field] !== previous[field]) throw new Error(`Baseline incompatível: ${row.name}.${field}.`);
+    }
+    if (!(row.operationsPerSecond > 0) || !Number.isFinite(row.operationsPerSecond)) throw new Error(`Medição atual inválida: ${row.name}.`);
     if (!(previous.operationsPerSecond > 0) || !Number.isFinite(previous.operationsPerSecond)) throw new Error(`Baseline inválida: ${row.name}.`);
     const throughputChangePercent = (row.operationsPerSecond / previous.operationsPerSecond - 1) * 100;
     return { name: row.name, status: 'compared', throughputChangePercent,

package/benchmarks/parser.mjs

@@ -0,0 +1,66 @@
+import assert from 'node:assert/strict';
+import { performance } from 'node:perf_hooks';
+import { cpus, platform, arch } from 'node:os';
+import { readFile } from 'node:fs/promises';
+import { createHash } from 'node:crypto';
+import { resolve } from 'node:path';
+import { pathToFileURL } from 'node:url';
+
+const modules = { current: new URL('../dist/scripting/parser.js', import.meta.url) };
+for (let index = 2; index < process.argv.length; index += 2) {
+  const key = { '--parser-module': 'current', '--baseline-module': 'baseline' }[process.argv[index]];
+  const value = process.argv[index + 1];
+  if (!key || !value || value.startsWith('--')) throw new Error('Uso: node benchmarks/parser.mjs [--parser-module caminho] [--baseline-module caminho]');
+  modules[key] = pathToFileURL(resolve(value));
+}
+const implementations = {};
+for (const [label, url] of Object.entries(modules)) implementations[label] = {
+  parse: (await import(url)).parse,
+  sourceHash: createHash('sha256').update(await readFile(url)).digest('hex'),
+};
+const iterations = 20_000, warmup = 2000, samples = 9, differentialCases = 20_000;
+const cases = {
+  plain: 'a'.repeat(8000),
+  interpolated: `prefix ${'abc '.repeat(100)}$name suffix ${'xyz '.repeat(100)}`,
+  short: '$reply[Olá $username!]',
+  dense: '$f[a;b;$g[c]]'.repeat(20),
+};
+const outcome = (parse, source) => {
+  try { return parse(source); }
+  catch (error) { return { code: error.code, offset: error.offset, message: error.message }; }
+};
+if (implementations.baseline) {
+  const alphabet = ['a', '$', '[', ']', ';', '\\', 'é', '\n', '1'];
+  for (let seed = 0; seed < differentialCases; seed++) {
+    let state = seed + 1, source = '';
+    for (let index = 0; index < 50; index++) {
+      state = (Math.imul(state, 1664525) + 1013904223) >>> 0;
+      source += alphabet[state % alphabet.length];
+    }
+    assert.deepEqual(outcome(implementations.current.parse, source), outcome(implementations.baseline.parse, source), source);
+  }
+}
+const results = [];
+for (const [name, source] of Object.entries(cases)) {
+  if (implementations.baseline) assert.deepEqual(implementations.current.parse(source), implementations.baseline.parse(source));
+  const times = Object.fromEntries(Object.keys(implementations).map(label => [label, []]));
+  for (let sample = 0; sample < samples; sample++) {
+    const entries = Object.entries(implementations);
+    if (sample % 2) entries.reverse();
+    for (const [label, { parse }] of entries) {
+      for (let index = 0; index < warmup; index++) parse(source);
+      const start = performance.now();
+      for (let index = 0; index < iterations; index++) parse(source);
+      times[label].push(performance.now() - start);
+    }
+  }
+  for (const [implementation, samplesMs] of Object.entries(times)) {
+    const sorted = [...samplesMs].sort((a, b) => a - b);
+    results.push({ name, implementation, characters: source.length, iterations, medianMs: sorted[Math.floor(samples / 2)], samplesMs });
+  }
+}
+console.log(JSON.stringify({ suite: 'parser', date: new Date().toISOString(), node: process.versions.node,
+  platform: platform(), arch: arch(), cpu: cpus()[0]?.model, warmup, samples,
+  differentialCases: implementations.baseline ? differentialCases : 0,
+  modules: Object.fromEntries(Object.entries(implementations).map(([label, entry]) => [label, { path: modules[label].href, sourceHash: entry.sourceHash }])),
+  results }, null, 2));