chapterjs 0.4.0 → 0.5.0

package/dist/cli/start.js

@@ -58,7 +58,7 @@ export async function start(options) {
         version: options.version,
         log,
         built: files,
-        joinsVoice: built.info.voice === true,
+        uses: built.info.uses ?? {},
         stores: {
             // A process started by another keeps no file: the first one does,
             // for all of them.
@@ -144,12 +144,19 @@ export async function start(options) {
             throw new SessionLimitError(plan.shards, limit.remaining, limit.reset_after);
         }
         const processes = planProcesses(plan.shards, options.processes);
+        if (options.processes !== undefined && processes < options.processes) {
+            log.info(`--processes ${options.processes} asks for more processes than your bot has shards (${plan.shards}): each process runs one at least, so it runs in ${processes === 1 ? '1 process' : `${processes} processes`}. Discord gives a bot more shards as it joins more servers.`);
+        }
         const online = (user, guilds) => {
             const split = [
                 ...(plan.shards > 1 ? [`${plan.shards} shards`] : []),
                 ...(processes > 1 ? [`${processes} processes`] : []),
             ].join(', ');
             log.success(`Online as ${user} in ${guilds} ${guilds === 1 ? 'server' : 'servers'}${split ? ` (${split})` : ''}`);
+            // A bot only in its dev server would read "in 0 servers".
+            if (devGuildId) {
+                log.info('The dev server (DEV_GUILD_ID) is not counted: chapterjs start leaves it to chapterjs dev, and answers nothing there.');
+            }
             log.info(`Intents computed from your files: ${describeIntents(intents)}`);
             (project.isEmpty() ? log.info : log.success)(project.summary());
             const kept = describeRedisStores(project, redis);
@@ -202,6 +209,8 @@ async function run(project, connection, stopped, connected, { tasks = true } = {
         // A task runs once for the whole bot: in one process only.
         if (tasks)
             project.startTasks(() => bot);
+        // The presence is shown by every process, on its own shards.
+        project.startPresence(() => bot);
         return await Promise.race([
             stopped.then(() => 'stopped'),
             refused,
@@ -209,6 +218,7 @@ async function run(project, connection, stopped, connected, { tasks = true } = {
     }
     finally {
         project.stopTasks();
+        project.stopPresence();
         memory.stop();
         await bot?.close();
         await project.closeStores();

package/dist/cli/test.js

@@ -15,7 +15,7 @@ import { captureLog, Observer, Session } from '../testing/harness.js';
 import { scenarioDeclaration, } from '../testing/scenario.js';
 import { smokeChecks } from '../testing/smoke.js';
 import { World } from '../testing/world.js';
-import { createProject, hasSources, writeTypes, } from './project.js';
+import { createProject, hasSources, reportLooseRejections, writeTypes, } from './project.js';
 /**
  * What a terminal shows while a file is tested: `↻ Testing src/close.ts`,
  * then one line per thing and case as it is tried. Once the file is done,
@@ -66,6 +66,8 @@ function where(error, cwd) {
     return found ? `${found.file}:${found.line} ` : '';
 }
 /** Runs the whole project in a fresh world; `close` ends it. */
+/** What join() says in the Discord in memory, where nothing plays. */
+const VOICE_NOT_SIMULATED = 'Voice is not simulated by chapterjs test yet: the bot can not join a voice channel here.';
 async function startSession(project, observer, stores) {
     stores.reset();
     observer.reset();
@@ -77,6 +79,7 @@ async function startSession(project, observer, stores) {
             token: 'test-token',
             apiUrl: world.discord.url,
             privateEvents: true,
+            voiceUnavailable: VOICE_NOT_SIMULATED,
             onFatal: () => { },
         });
     }
@@ -153,14 +156,19 @@ export async function test(options) {
         return 1;
     const src = join(cwd, 'src');
     const output = quiet();
+    const stops = [];
     try {
-        return await run(options, src, output);
+        return await run(options, src, output, stop => stops.push(stop));
     }
     finally {
+        for (const stop of stops)
+            stop();
         output.restore();
     }
 }
-async function run(options, src, output) {
+async function run(options, src, output, 
+/** What to undo when the run ends. */
+onEnd) {
     const { cwd } = options;
     // The report, written while what the files print is kept out of it.
     const log = {
@@ -173,6 +181,9 @@ async function run(options, src, output) {
     // 1. The files of the project, every one of them running.
     enableProjectLoader(src, { reload: false });
     const capture = captureLog();
+    // A promise of the files that nobody awaited fails the check or the
+    // scenario it belongs to, as dev says it, instead of ending the run.
+    onEnd(reportLooseRejections(cwd, capture.log));
     const observer = new Observer();
     const stores = new MemoryStoreBackend();
     const project = createProject({
@@ -210,13 +221,23 @@ async function run(options, src, output) {
         // has one line per file: what was checked in it only shows when
         // something failed.
         const { checks, notSimulated } = smokeChecks(project);
-        const smoke = await startSession(project, observer, stores);
+        const smoke = {
+            current: await startSession(project, observer, stores),
+            /** Whether a case ran on the current world: the next gets a new one. */
+            used: false,
+            async restart() {
+                await this.current.close();
+                this.current = await startSession(project, observer, stores);
+            },
+        };
+        /** The checks whose files join voice, which is not played here. */
+        const voiceSkipped = [];
         const progress = checkProgress(options.progress === true, log, text => output.report(() => process.stdout.write(text)));
         try {
             // The ready event runs first, as it does online; its result is
             // reported with the file it comes from.
-            project.ready(smoke.session.bot);
-            await smoke.session.settle();
+            project.ready(smoke.current.session.bot);
+            await smoke.current.session.settle();
             const atStart = problems(capture.take());
             const readyPrinted = output.take();
             const readyFiles = [
@@ -251,8 +272,10 @@ async function run(options, src, output) {
                 }
                 for (const check of own) {
                     progress.step(check.subject);
-                    const result = await runCheck(check, smoke.session, capture, cwd, label => progress.step(`${check.subject}, ${label}`));
+                    const result = await runCheck(check, smoke, capture, cwd, label => progress.step(`${check.subject}, ${label}`));
                     const wrote = output.take();
+                    if (result.notSimulated)
+                        voiceSkipped.push(`${check.subject} (${file})`);
                     if (result.failed.length === 0)
                         passed++;
                     else {
@@ -285,7 +308,10 @@ async function run(options, src, output) {
             }
         }
         finally {
-            await smoke.close();
+            await smoke.current.close();
+        }
+        if (voiceSkipped.length > 0) {
+            log.info(`Voice is not played in memory, so what comes after join() was not run for: ${voiceSkipped.join(', ')}. Try it on your server with chapterjs dev.`);
         }
         if (notSimulated.length > 0) {
             log.info(`${notSimulated.length === 1 ? 'An event is' : 'Some events are'} not simulated yet, so ${notSimulated.length === 1 ? 'its file was' : 'their files were'} not run: ${notSimulated.join(', ')}.`);
@@ -387,34 +413,100 @@ function report(failure, cwd, log) {
     const found = locate(failure.error, cwd);
     log.error(`${found ? `${found.file}:${found.line}` : siteName(failure)} ${messageOf(failure.error)}`);
 }
-/** Runs the cases of a check, one after the other, in the same world. */
-async function runCheck(check, session, capture, cwd, onCase = () => { }) {
+/**
+ * How long a case of a check may go without any answer: Discord gives an
+ * interaction 3 s, and the framework defers by itself after 2.
+ */
+const ANSWER_WITHIN = 5000;
+/**
+ * How long a case may take in all once every interaction it started was
+ * answered: a deferred answer may come later, as it may online.
+ */
+const FINISH_WITHIN = 30_000;
+/**
+ * Runs the cases of a check, one after the other, in the same world. A case
+ * still running when its time is up is abandoned with the world it ran in:
+ * the next case gets a fresh one, so what the abandoned case does later is
+ * never taken for what the next one did.
+ */
+async function runCheck(check, smoke, capture, cwd, onCase = () => { }) {
     const failed = [];
     const warnings = [];
+    let notSimulated = false;
     for (const one of check.cases) {
         onCase(one.label);
+        // Every case on a server as it was: a /ban used on someone must not
+        // leave the next case without them.
+        if (smoke.used)
+            await smoke.restart();
+        smoke.used = true;
         capture.take();
+        const { session } = smoke.current;
+        const before = new Set(session.world.interactions.values());
+        const running = Promise.resolve().then(() => one.run(session));
         let thrown = null;
-        try {
-            await withTimeout(one.run(session), 5000, 'the bot did not answer within 5 s');
-        }
-        catch (error) {
+        let abandoned = false;
+        const fail = (error) => {
             thrown =
                 error instanceof TestFailure
                     ? error.message
                     : `${where(error, cwd)}${messageOf(error)}`;
+        };
+        let outcome = await within(running, ANSWER_WITHIN);
+        if (outcome.late) {
+            const unanswered = [...session.world.interactions.values()].some(record => !before.has(record) && record.callbacks.length === 0);
+            if (unanswered) {
+                thrown = `the bot did not answer within ${ANSWER_WITHIN / 1000} s`;
+                abandoned = true;
+            }
+            else {
+                outcome = await within(running, FINISH_WITHIN - ANSWER_WITHIN);
+                if (outcome.late) {
+                    thrown = `it did not finish within ${FINISH_WITHIN / 1000} s: is something waiting for what never comes?`;
+                    abandoned = true;
+                }
+            }
         }
+        if (!outcome.late && outcome.failed)
+            fail(outcome.error);
         const captured = problems(capture.take());
         const messages = [...(thrown ? [thrown] : []), ...captured.failures];
-        if (messages.length > 0) {
+        // Voice is not played in memory: a case that only failed there is not
+        // the file's fault, it was not run to its end.
+        if (messages.length > 0 &&
+            messages.every(message => message.includes(VOICE_NOT_SIMULATED))) {
+            notSimulated = true;
+        }
+        else if (messages.length > 0) {
             failed.push({ label: one.label, message: messages.join('; ') });
         }
         for (const warning of captured.warnings) {
             if (!warnings.includes(warning))
                 warnings.push(warning);
         }
+        if (abandoned)
+            running.catch(() => { });
+    }
+    return { failed, warnings, notSimulated };
+}
+/** Whether `promise` settled within `ms`, and how. */
+async function within(promise, ms) {
+    let timer;
+    try {
+        return await Promise.race([
+            promise.then(() => ({ late: false, failed: false }), (error) => ({
+                late: false,
+                failed: true,
+                error,
+            })),
+            new Promise(resolve => {
+                timer = setTimeout(() => resolve({ late: true }), ms);
+            }),
+        ]);
+    }
+    finally {
+        clearTimeout(timer);
     }
-    return { failed, warnings };
 }
 /** Loads the test files and reads their scenarios; what fails is reported. */
 async function loadScenarios(files, cwd, log) {

package/dist/commands/command.d.ts

@@ -5,7 +5,7 @@ import type { Channel, DMChannel, GuildTextBasedChannel } from '../structures/ch
 import type { Guild } from '../structures/guild.js';
 import type { DmCommandInteraction, GuildCommandInteraction, PrivateCommandInteraction } from '../structures/interaction.js';
 import type { GuildMember } from '../structures/member.js';
-import type { Attachment } from '../structures/message.js';
+import type { Attachment, DmMessage, GuildMessage, PrivateMessage } from '../structures/message.js';
 import type { Role } from '../structures/role.js';
 import type { User } from '../structures/user.js';
 import type { TranslationContext } from '../messages/messages.js';
@@ -270,6 +270,121 @@ export type CommandContext<Options extends CommandOptions = CommandOptions, Wher
     /** Who used the command. */
     user: User;
 } & TranslationContext & (Where extends 'guild' ? CommandInGuild : Where extends 'dm' ? CommandInDm : CommandInGuild | CommandInPrivate);
+/**
+ * What a menu command is used on, in the menu people open with a right
+ * click (or a long press): a message (`'message'`) or a person
+ * (`'user'`).
+ * @see https://docs.discord.com/developers/interactions/application-commands#application-command-object-application-command-types
+ */
+export type MenuType = 'message' | 'user';
+/** What a menu command receives about what it was used on, in a server. */
+type MenuTargetInGuild<Type extends MenuType> = Type extends 'user' ? {
+    /** The person the menu was used on. */
+    target: User;
+    /**
+     * That person as a member of the server, or `null` when they are not
+     * in it (any more).
+     */
+    targetMember: GuildMember | null;
+} : {
+    /** The message the menu was used on. */
+    message: GuildMessage;
+};
+/**
+ * What a menu command receives about what it was used on, in a private
+ * message with the bot.
+ */
+type MenuTargetInPrivate<Type extends MenuType> = Type extends 'user' ? {
+    /** The person the menu was used on. */
+    target: User;
+    /** No server: no member. */
+    targetMember: null;
+} : {
+    /** The message the menu was used on. */
+    message: PrivateMessage;
+};
+/** The same, for a menu command only used in private messages. */
+type MenuTargetInDm<Type extends MenuType> = Type extends 'user' ? {
+    /** The person the menu was used on. */
+    target: User;
+} : {
+    /** The message the menu was used on. */
+    message: DmMessage;
+};
+/**
+ * What the `run` function of a menu command receives: what it was used on
+ * (`message`, or `target` and `targetMember`), who used it, and the place,
+ * which follows `where` like the one of a slash command.
+ */
+export type MenuContext<Type extends MenuType = 'message', Where extends CommandWhere = 'guild'> = {
+    /** Who used the menu. */
+    user: User;
+} & TranslationContext & (Where extends 'guild' ? CommandInGuild & MenuTargetInGuild<Type> : Where extends 'dm' ? CommandInDm & MenuTargetInDm<Type> : (CommandInGuild & MenuTargetInGuild<Type>) | (CommandInPrivate & MenuTargetInPrivate<Type>));
+/** The translation of a menu command in one language: its name. */
+export interface MenuTranslation {
+    /** The name shown in the menu in that language (1-32 characters). */
+    name?: string;
+}
+/** The translations of a menu command, by language. */
+export type MenuLocales = {
+    readonly [Language in Locale]?: MenuTranslation;
+};
+/**
+ * What a file gives to `command()` for a menu command: one used on a
+ * message or a person, from the menu of a right click. It has no
+ * description and no options: what it receives is what it was used on.
+ */
+export interface MenuConfig<Type extends MenuType = 'message', Where extends CommandWhere = 'guild'> {
+    /**
+     * What the command is used on: `'message'` (a right click on a message)
+     * or `'user'` (a right click on a person).
+     */
+    type: Type;
+    /**
+     * What the menu shows (1-32 characters): capitals and spaces are fine,
+     * like `'Report message'`.
+     */
+    name: string;
+    /**
+     * The name in other languages: Discord shows each person the name of
+     * their language.
+     * @see https://docs.discord.com/developers/interactions/application-commands#localization
+     */
+    locales?: MenuLocales;
+    /**
+     * The permissions a member needs to use the command. Server admins can
+     * change who sees it in the server settings.
+     */
+    permissions?: readonly PermissionName[];
+    /**
+     * Where the command can be used: `'guild'` (in servers, the default),
+     * `'dm'` (in private messages with the bot) or `'both'`. What `run`
+     * receives follows it.
+     */
+    where?: Where;
+    /** Only show the command in age-restricted channels. */
+    nsfw?: boolean;
+    /** Make the answers of the command only visible to who used it. */
+    ephemeral?: boolean;
+    /**
+     * How long to wait before the command can be used again: `'10s'` for
+     * each person, or `{ user, channel, guild }` for each place.
+     */
+    cooldown?: Cooldown;
+    /** A menu command has no description: Discord only shows its name. */
+    description?: never;
+    /** A menu command has no options: it receives what it was used on. */
+    options?: never;
+    /** A menu command has no options to suggest values for. */
+    autocomplete?: never;
+    /** What to do when someone uses the command. */
+    run: (context: MenuContext<Type, Where>) => unknown;
+}
+/** What `command()` returns for a menu command. */
+export interface MenuDeclaration<Type extends MenuType = MenuType, Where extends CommandWhere = CommandWhere> {
+    /** What the file gave to `command()`, not checked yet. */
+    readonly config: MenuConfig<Type, Where>;
+}
 /**
  * The name of a slash command: lowercase letters, digits, `-` and `_`, 32
  * characters at most (`'ping'`). A subcommand is written with its parents,
@@ -330,6 +445,11 @@ export interface CommandConfig<Options extends CommandOptions = CommandOptions,
      * uses it too soon gets a private answer saying when they can.
      */
     cooldown?: Cooldown;
+    /**
+     * Leave it out for a slash command. `'message'` or `'user'` makes a menu
+     * command instead, used with a right click on a message or a person.
+     */
+    type?: undefined;
     /** What to do when someone uses the command. */
     run: (context: CommandContext<Options, Where>) => unknown;
 }
@@ -339,8 +459,10 @@ export interface CommandDeclaration<Options extends CommandOptions = CommandOpti
     readonly config: CommandConfig<Options, Where>;
 }
 /**
- * Declares a slash command. Export the result from any file of `src/`:
- * `name` is what people type after the `/` (`'mod ban'` for `/mod ban`).
+ * Declares a command. Export the result from any file of `src/`.
+ *
+ * A slash command: `name` is what people type after the `/` (`'mod ban'`
+ * for `/mod ban`).
  *
  * ```ts
  * import { command } from 'chapterjs';
@@ -353,8 +475,21 @@ export interface CommandDeclaration<Options extends CommandOptions = CommandOpti
  *   },
  * });
  * ```
+ *
+ * A menu command, with `type`: used with a right click on a message
+ * (`'message'`) or on a person (`'user'`), `name` being what the menu shows.
+ *
+ * ```ts
+ * export const quote = command({
+ *   type: 'message',
+ *   name: 'Quote',
+ *   async run({ interaction, message }) {
+ *     await interaction.reply(`> ${message.content}`);
+ *   },
+ * });
+ * ```
  */
-export declare function command<const Options extends CommandOptions = {}, const Where extends CommandWhere = 'guild'>(config: CommandConfig<Options, Where>): CommandDeclaration<Options, Where>;
+export declare function command<const Options extends CommandOptions = {}, const Where extends CommandWhere = 'guild', const Type extends MenuType | undefined = undefined>(config: Type extends MenuType ? MenuConfig<Type, Where> : CommandConfig<Options, Where>): Type extends MenuType ? MenuDeclaration<Type, Where> : CommandDeclaration<Options, Where>;
 /** Whether a value was made by `command()`. */
-export declare function isCommandDeclaration(value: unknown): value is CommandDeclaration;
+export declare function isCommandDeclaration(value: unknown): value is CommandDeclaration | MenuDeclaration;
 export {};

package/dist/commands/command.js

@@ -2,8 +2,10 @@
 // make the options a command declares typed in its `run` function.
 const BRAND = Symbol.for('chapterjs.command');
 /**
- * Declares a slash command. Export the result from any file of `src/`:
- * `name` is what people type after the `/` (`'mod ban'` for `/mod ban`).
+ * Declares a command. Export the result from any file of `src/`.
+ *
+ * A slash command: `name` is what people type after the `/` (`'mod ban'`
+ * for `/mod ban`).
  *
  * ```ts
  * import { command } from 'chapterjs';
@@ -16,6 +18,19 @@ const BRAND = Symbol.for('chapterjs.command');
  *   },
  * });
  * ```
+ *
+ * A menu command, with `type`: used with a right click on a message
+ * (`'message'`) or on a person (`'user'`), `name` being what the menu shows.
+ *
+ * ```ts
+ * export const quote = command({
+ *   type: 'message',
+ *   name: 'Quote',
+ *   async run({ interaction, message }) {
+ *     await interaction.reply(`> ${message.content}`);
+ *   },
+ * });
+ * ```
  */
 export function command(config) {
     return Object.freeze({ [BRAND]: true, config });

package/dist/commands/declaration.d.ts

@@ -1,7 +1,13 @@
 import { Locale } from '../discord/types/common.js';
 import { type CooldownLimits } from '../interactions/cooldown.js';
 import { type Declaration } from '../loader/loader.js';
-import { type AutocompleteContext, type CommandContext, type CommandOption, type CommandWhere, type Suggestion } from './command.js';
+import { type AutocompleteContext, type CommandContext, type CommandOption, type CommandWhere, type MenuType, type Suggestion } from './command.js';
+/**
+ * The kinds of commands: a slash command, or a menu command used on a
+ * message or a person.
+ * @see https://docs.discord.com/developers/interactions/application-commands#application-command-object-application-command-types
+ */
+export type CommandType = 'slash' | MenuType;
 /** A name or a description in other languages, as Discord takes them. */
 export type Localizations = Readonly<Partial<Record<Locale, string>>>;
 /** The translations of one option, checked. */
@@ -20,12 +26,17 @@ export type LoadedOption = CommandOption & {
 export type AutocompleteFunction = (context: AutocompleteContext) => readonly Suggestion[] | Promise<readonly Suggestion[]>;
 /** A command, checked: what the rest of the feature works with. */
 export interface LoadedCommand {
+    /** A slash command, or a menu command used on a message or a person. */
+    readonly type: CommandType;
     /** The name and description of the command in other languages. */
     readonly names: Localizations;
     readonly descriptions: Localizations;
     /** The translations of the options, by option name. */
     readonly optionLocales: Readonly<Record<string, OptionLocales>>;
-    /** `['mod', 'ban']` for `name: 'mod ban'`: `/mod ban`. */
+    /**
+     * `['mod', 'ban']` for `name: 'mod ban'`: `/mod ban`. A menu command has
+     * one name, spaces included: `['Report message']`.
+     */
     readonly path: readonly string[];
     /**
      * Whether the file gives its own texts (`description`, `locales`). When
@@ -64,8 +75,9 @@ export declare function readCommandName(name: unknown): string[];
 /**
  * A slash command, declared anywhere in `src/` with `command()`: `name` is
  * what people type after the `/`, with its parents for a subcommand
- * (`'mod ban'` is `/mod ban`, `'mod roles add'` is `/mod roles add`). A
- * file may declare several.
+ * (`'mod ban'` is `/mod ban`, `'mod roles add'` is `/mod roles add`). With
+ * a `type`, a menu command, used on a message or a person. A file may
+ * declare several.
  */
 export declare const commandDeclaration: Declaration<LoadedCommand>;
 /**
@@ -73,5 +85,6 @@ export declare const commandDeclaration: Declaration<LoadedCommand>;
  * files: a text search for `command({ name: '...' })`. Approximate on
  * purpose, for `sync`, which runs nothing: `dev` and `build` then write
  * the exact ones. Whether a command is described is not known: none is.
+ * Menu commands are left out: their texts are always in their file.
  */
 export declare function scanCommands(cwd: string): Promise<string[]>;