@whanext/core 0.10.0 → 0.11.0

package/CHANGELOG.md

@@ -1,5 +1,15 @@
 # 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

package/README.md

@@ -566,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

package/dist/index.d.ts

@@ -438,6 +438,17 @@ declare class MessageService {
     text(chatId: string, text: string, mentions?: MentionTarget[]): Promise<SentMessage>;
 }
 
+interface CommandCatalogView {
+    readonly prefix: string;
+    readonly size: number;
+    catalog(options?: {
+        category?: string;
+        includeHidden?: boolean;
+    }): readonly RegisteredCommand[];
+    categories(): readonly string[];
+    has(path: string): boolean;
+    find(path: string): RegisteredCommand | undefined;
+}
 interface CommandRuntimeServices {
     messages: MessageService;
     media: MediaService;
@@ -466,6 +477,8 @@ interface CommandContext<Schema extends CommandOptionSchema = CommandOptionSchem
     readonly chat: CommandChatContext;
     readonly group: CommandGroupContext | undefined;
     readonly command: RegisteredCommand;
+    readonly commands: CommandCatalogView;
+    readonly prefix: string;
     readonly options: ParsedCommandOptions<Schema>;
     readonly args: ArgsParser;
     readonly locale: string | undefined;
@@ -584,6 +597,24 @@ declare function defineCommandGroup<const Group extends CommandGroupDefinition>(
 declare function defineCommands<const Commands extends readonly CommandDefinition[]>(...commands: Commands): Commands;
 declare function isCommandGroup(definition: CommandDefinition): definition is CommandGroupDefinition;
 
+interface CommandRegistrar {
+    command(definition: CommandDefinition): unknown;
+}
+interface LoadCommandsOptions {
+    extensions?: readonly string[];
+    recursive?: boolean;
+}
+interface LoadCommandsResult {
+    loaded: readonly string[];
+    skipped: readonly string[];
+    commands: readonly LoadedCommand[];
+}
+interface LoadedCommand {
+    name: string;
+    filePath: string;
+}
+declare function loadCommands(registrar: CommandRegistrar, dirPath: string | URL, options?: LoadCommandsOptions): Promise<LoadCommandsResult>;
+
 interface RouterOptions {
     prefix?: string;
     onError?: (error: WhaNextError, message: Message) => void | Promise<void>;
@@ -606,6 +637,7 @@ declare class CommandRouter {
     get prefix(): string;
     get size(): number;
     command(definition: CommandDefinition): this;
+    load(dirPath: string | URL, options?: LoadCommandsOptions): Promise<LoadCommandsResult>;
     use(middleware: CommandMiddleware): this;
     onError(handler: CommandErrorHandler): () => void;
     catalog(options?: CommandCatalogOptions): readonly RegisteredCommand[];
@@ -749,24 +781,6 @@ declare class MemoryCache implements CacheStore {
     stats(): Readonly<MemoryCacheStats>;
 }
 
-interface CommandRegistrar {
-    command(definition: CommandDefinition): unknown;
-}
-interface LoadCommandsOptions {
-    extensions?: readonly string[];
-    recursive?: boolean;
-}
-interface LoadCommandsResult {
-    loaded: readonly string[];
-    skipped: readonly string[];
-    commands: readonly LoadedCommand[];
-}
-interface LoadedCommand {
-    name: string;
-    filePath: string;
-}
-declare function loadCommands(registrar: CommandRegistrar, dirPath: string, options?: LoadCommandsOptions): Promise<LoadCommandsResult>;
-
 declare class SqliteMuteStore implements MuteStore {
     #private;
     constructor(path?: string);
@@ -777,4 +791,4 @@ declare class SqliteMuteStore implements MuteStore {
     close(): void;
 }
 
-export { type AddMuteOptions, type AddMuteResult, type AppEvents, type AppHealth, type AppHealthStatus, ArgsParser, type AudioContent, type BooleanOption, Browser, type CacheOptions, type CacheStore, type CallEvent, type CallStatus, type ChangeResult, type CommandCatalogOptions, type CommandChatContext, type CommandConcurrency, type CommandContext, type CommandCooldown, type CommandDefinition, type CommandErrorHandler, type CommandGroupContext, type CommandGroupDefinition, type CommandGuard, type CommandHelpOptions, type CommandHooks, type CommandLocalization, type CommandMetadata, type CommandMiddleware, type CommandOptionDefinition, type CommandOptionSchema, type CommandOptionValue, type CommandOptionValues, type CommandRegistrar, CommandRouter, type CommandRuntimeServices, type CommandScope, type ConcurrencyStrategy, type ConnectionState, type ConnectionUpdate, type CreateOptions, DeferredReply, type DownloadedMedia, type DurationOption, type EnumOption, type ExecutableCommandDefinition, type GroupAccess, type GroupAddressingMode, type GroupParticipant, type GroupParticipantAction, type GroupParticipantsChanged, type GroupRole, type GroupSnapshot, type GuardResult, type ImageContent, type InviteResult, type LoadCommandsOptions, type LoadCommandsResult, type LoadedCommand, type LogContext, type LogEntry, type LogFormat, type LogLevel, type LogWriter, Logger, type LoggerConfig, type LoggerOptions, type LoginOptions, type MediaKind, type MediaSource, type MemberActionState, MemoryCache, type MemoryCacheStats, type MentionTarget, type Message, type MessageContent, type MessageKey, type MessageMedia, type MuteChangeResult, type MuteEnforcement, type MuteOptions, type MuteRecord, MuteService, type MuteStore, type NumberOption, ParsedCommandOptions, type ParticipantUpdateResult, type PresenceState, type QuotedMessage, type ReconnectOptions, type RegisteredCommand, type RemoveMuteResult, type ReplyOptions, type RouterOptions, type SentMessage, SqliteMuteStore, type StickerContent, type StoredMute, type StringOption, type TextContent, User, type UserData, type UserOption, type VideoContent, WhaNextApp, WhaNextError, type WhaNextErrorCode, type WhatsAppProvider, create, defineCommand, defineCommandGroup, defineCommands, defineSubcommand, guards, isCommandGroup, loadCommands, option, toWhaNextError };
+export { type AddMuteOptions, type AddMuteResult, type AppEvents, type AppHealth, type AppHealthStatus, ArgsParser, type AudioContent, type BooleanOption, Browser, type CacheOptions, type CacheStore, type CallEvent, type CallStatus, type ChangeResult, type CommandCatalogOptions, type CommandCatalogView, type CommandChatContext, type CommandConcurrency, type CommandContext, type CommandCooldown, type CommandDefinition, type CommandErrorHandler, type CommandGroupContext, type CommandGroupDefinition, type CommandGuard, type CommandHelpOptions, type CommandHooks, type CommandLocalization, type CommandMetadata, type CommandMiddleware, type CommandOptionDefinition, type CommandOptionSchema, type CommandOptionValue, type CommandOptionValues, type CommandRegistrar, CommandRouter, type CommandRuntimeServices, type CommandScope, type ConcurrencyStrategy, type ConnectionState, type ConnectionUpdate, type CreateOptions, DeferredReply, type DownloadedMedia, type DurationOption, type EnumOption, type ExecutableCommandDefinition, type GroupAccess, type GroupAddressingMode, type GroupParticipant, type GroupParticipantAction, type GroupParticipantsChanged, type GroupRole, type GroupSnapshot, type GuardResult, type ImageContent, type InviteResult, type LoadCommandsOptions, type LoadCommandsResult, type LoadedCommand, type LogContext, type LogEntry, type LogFormat, type LogLevel, type LogWriter, Logger, type LoggerConfig, type LoggerOptions, type LoginOptions, type MediaKind, type MediaSource, type MemberActionState, MemoryCache, type MemoryCacheStats, type MentionTarget, type Message, type MessageContent, type MessageKey, type MessageMedia, type MuteChangeResult, type MuteEnforcement, type MuteOptions, type MuteRecord, MuteService, type MuteStore, type NumberOption, ParsedCommandOptions, type ParticipantUpdateResult, type PresenceState, type QuotedMessage, type ReconnectOptions, type RegisteredCommand, type RemoveMuteResult, type ReplyOptions, type RouterOptions, type SentMessage, SqliteMuteStore, type StickerContent, type StoredMute, type StringOption, type TextContent, User, type UserData, type UserOption, type VideoContent, WhaNextApp, WhaNextError, type WhaNextErrorCode, type WhatsAppProvider, create, defineCommand, defineCommandGroup, defineCommands, defineSubcommand, guards, isCommandGroup, loadCommands, option, toWhaNextError };

package/dist/index.js

@@ -395,6 +395,8 @@ var CommandContextImplementation = class {
   chat;
   group;
   command;
+  commands;
+  prefix;
   options;
   args;
   locale;
@@ -413,6 +415,8 @@ var CommandContextImplementation = class {
     this.user = options.message.sender;
     this.chat = { id: options.message.chatId, isGroup: options.message.isGroup };
     this.command = options.command;
+    this.commands = options.commands;
+    this.prefix = options.commands.prefix;
     this.options = options.options;
     this.args = options.args;
     this.locale = options.locale;
@@ -510,6 +514,85 @@ function normalizeContent(content) {
   return typeof content === "string" ? { text: content } : content;
 }
 
+// src/commands/load-commands.ts
+import { readdir } from "fs/promises";
+import path from "path";
+import { fileURLToPath, pathToFileURL } from "url";
+var DEFAULT_EXTENSIONS = [".js", ".mjs", ".cjs", ".ts", ".mts", ".cts"];
+async function loadCommands(registrar, dirPath, options = {}) {
+  const extensions = options.extensions ?? DEFAULT_EXTENSIONS;
+  const recursive = options.recursive ?? true;
+  const resolvedDirPath = dirPath instanceof URL ? fileURLToPath(dirPath) : dirPath;
+  const entries = await readEntries(resolvedDirPath, recursive);
+  const loaded = [];
+  const skipped = [];
+  const commands = [];
+  for (const filePath of entries) {
+    if (isDeclarationFile(filePath) || !extensions.includes(path.extname(filePath))) {
+      skipped.push(filePath);
+      continue;
+    }
+    const definitions = await importCommands(filePath);
+    for (const definition of definitions) {
+      registrar.command(definition);
+      commands.push({ name: definition.name, filePath });
+    }
+    loaded.push(filePath);
+  }
+  return { loaded, skipped, commands };
+}
+async function readEntries(dirPath, recursive) {
+  let dirents;
+  try {
+    dirents = await readdir(dirPath, { recursive, withFileTypes: true });
+  } catch (error) {
+    throw new WhaNextError("COMMAND_LOAD_FAILED", `Could not read the commands directory "${dirPath}".`, {
+      cause: error,
+      context: { dirPath }
+    });
+  }
+  return dirents.filter((dirent) => dirent.isFile()).map((dirent) => path.join(dirent.parentPath, dirent.name)).sort((left, right) => left.localeCompare(right));
+}
+async function importCommands(filePath) {
+  let module;
+  try {
+    module = await import(pathToFileURL(filePath).href);
+  } catch (error) {
+    throw new WhaNextError("COMMAND_LOAD_FAILED", `Could not import the command file "${filePath}".`, {
+      cause: error,
+      context: { filePath }
+    });
+  }
+  const definitions = [];
+  const seen = /* @__PURE__ */ new Set();
+  const exports = [
+    module.default,
+    ...Object.entries(module).filter(([name]) => name !== "default").map(([, value]) => value)
+  ];
+  for (const value of exports) {
+    const candidates = Array.isArray(value) ? value : [value];
+    for (const candidate of candidates) {
+      if (isCommandDefinition(candidate) && !seen.has(candidate)) {
+        seen.add(candidate);
+        definitions.push(candidate);
+      }
+    }
+  }
+  if (definitions.length === 0) {
+    throw new WhaNextError("COMMAND_LOAD_FAILED", `The file "${filePath}" does not export any valid commands.`, {
+      context: { filePath }
+    });
+  }
+  return definitions;
+}
+function isCommandDefinition(value) {
+  const candidate = value;
+  return typeof value === "object" && value !== null && typeof candidate.name === "string" && (typeof candidate.execute === "function" || Array.isArray(candidate.subcommands));
+}
+function isDeclarationFile(filePath) {
+  return /\.d\.(?:ts|mts|cts)$/.test(filePath);
+}
+
 // src/commands/options.ts
 var option = {
   string(definition) {
@@ -705,6 +788,9 @@ var CommandRouter = class {
     this.#definitions.add(definition);
     return this;
   }
+  load(dirPath, options = {}) {
+    return loadCommands(this, dirPath, options);
+  }
   use(middleware) {
     this.#globalMiddleware.push(middleware);
     return this;
@@ -778,6 +864,7 @@ _Nenhum comando dispon\xEDvel._`;
         options: new ParsedCommandOptions({}),
         args: new ArgsParser(tokens),
         services: this.#services,
+        commands: this,
         signal: new AbortController().signal,
         ...root.locale ? { locale: root.locale } : {}
       });
@@ -820,6 +907,7 @@ _Nenhum comando dispon\xEDvel._`;
             options: parsedOptions,
             args: legacyArgs,
             services: this.#services,
+            commands: this,
             signal,
             ...resolved.locale ? { locale: resolved.locale } : {}
           });
@@ -840,6 +928,7 @@ _Nenhum comando dispon\xEDvel._`;
         options: new ParsedCommandOptions({}),
         args: legacyArgs,
         services: this.#services,
+        commands: this,
         signal: new AbortController().signal,
         ...resolved.locale ? { locale: resolved.locale } : {}
       });
@@ -2890,81 +2979,6 @@ var guards = {
     return guard;
   }
 };
-
-// src/commands/load-commands.ts
-import { readdir } from "fs/promises";
-import path from "path";
-import { pathToFileURL } from "url";
-var DEFAULT_EXTENSIONS = [".js", ".mjs", ".cjs"];
-async function loadCommands(registrar, dirPath, options = {}) {
-  const extensions = options.extensions ?? DEFAULT_EXTENSIONS;
-  const recursive = options.recursive ?? true;
-  const entries = await readEntries(dirPath, recursive);
-  const loaded = [];
-  const skipped = [];
-  const commands = [];
-  for (const filePath of entries) {
-    if (!extensions.includes(path.extname(filePath))) {
-      skipped.push(filePath);
-      continue;
-    }
-    const definitions = await importCommands(filePath);
-    for (const definition of definitions) {
-      registrar.command(definition);
-      commands.push({ name: definition.name, filePath });
-    }
-    loaded.push(filePath);
-  }
-  return { loaded, skipped, commands };
-}
-async function readEntries(dirPath, recursive) {
-  let dirents;
-  try {
-    dirents = await readdir(dirPath, { recursive, withFileTypes: true });
-  } catch (error) {
-    throw new WhaNextError("COMMAND_LOAD_FAILED", `Could not read the commands directory "${dirPath}".`, {
-      cause: error,
-      context: { dirPath }
-    });
-  }
-  return dirents.filter((dirent) => dirent.isFile()).map((dirent) => path.join(dirent.parentPath, dirent.name)).sort((left, right) => left.localeCompare(right));
-}
-async function importCommands(filePath) {
-  let module;
-  try {
-    module = await import(pathToFileURL(filePath).href);
-  } catch (error) {
-    throw new WhaNextError("COMMAND_LOAD_FAILED", `Could not import the command file "${filePath}".`, {
-      cause: error,
-      context: { filePath }
-    });
-  }
-  const definitions = [];
-  const seen = /* @__PURE__ */ new Set();
-  const exports = [
-    module.default,
-    ...Object.entries(module).filter(([name]) => name !== "default").map(([, value]) => value)
-  ];
-  for (const value of exports) {
-    const candidates = Array.isArray(value) ? value : [value];
-    for (const candidate of candidates) {
-      if (isCommandDefinition(candidate) && !seen.has(candidate)) {
-        seen.add(candidate);
-        definitions.push(candidate);
-      }
-    }
-  }
-  if (definitions.length === 0) {
-    throw new WhaNextError("COMMAND_LOAD_FAILED", `The file "${filePath}" does not export any valid commands.`, {
-      context: { filePath }
-    });
-  }
-  return definitions;
-}
-function isCommandDefinition(value) {
-  const candidate = value;
-  return typeof value === "object" && value !== null && typeof candidate.name === "string" && (typeof candidate.execute === "function" || Array.isArray(candidate.subcommands));
-}
 export {
   ArgsParser,
   Browser,