chapterjs 0.2.3 → 0.3.0

package/README.md

@@ -0,0 +1,65 @@
+# ChapterJS
+
+**The Discord framework: ultra simple, but ultra customizable.**
+
+Drop files into `src/`, and the `chapterjs` CLI does everything else: the connection, the intents, the registration of commands, hot reload, sharding and several processes for large bots. Everything you write is typed end to end, without a single type to write.
+
+```bash
+pnpm create chapterjs my-bot
+```
+
+📖 Documentation, in English and in French: **[chapterjs.org](https://www.chapterjs.org)**
+
+## A file is what it exports
+
+```ts
+// src/commands/hello.ts
+import { command } from 'chapterjs';
+
+export default command({
+  name: 'hello',
+  description: 'Says hello to someone',
+  cooldown: '10s',
+  options: {
+    who: { type: 'user', description: 'Who to greet', required: true },
+  },
+  async run({ interaction, options }) {
+    // options.who is a User: typed from the options above.
+    await interaction.reply(`Hello ${options.who}!`);
+  },
+});
+```
+
+The framework loads every file of `src/`, wherever it is and whatever it is called, and runs what the files export: `command()`, `event()`, `button()`, `select()`, `modal()`, `embed()`, `task()`, `store()`, `presence()`, `language()`. The folders are yours to organise with.
+
+## What it does
+
+- **Slash commands** with typed options, choices, autocomplete, permissions, cooldowns and translations.
+- **Events**: the intents follow from the files you write, privileged ones included, with a direct link when one must be enabled.
+- **Components**: buttons, select menus, forms and embeds, with typed `data` carried in the message and no id to write.
+- **Tasks**: every so often or with a cron, in the timezone you choose.
+- **Storage**: `store<Warning[]>({ expires: '30d' })` keeps data from one restart to the next, per server, typed, in a JSON file written for you.
+- **Translated messages**: `t('welcome', { name })` speaks the language of who will read it.
+- **Voice**: join a channel and play a file, an attachment or a link, end-to-end encrypted (DAVE).
+- **Tests**: `chapterjs test` runs the bot against a Discord in memory, no token needed: every file is used once by itself, then your scenarios (`scenario('ping answers Pong', async bot => { … })`) say what the bot should answer.
+
+## Four commands
+
+- `chapterjs dev` runs the bot on a test server and reloads each file when you save it. A broken file is reported with its line and never stops the bot.
+- `chapterjs test` checks the bot without Discord, with nothing written and with your scenarios.
+- `chapterjs build` checks every file and the types, then compiles the bot into one JavaScript file.
+- `chapterjs start` runs it in production, on several processes when the bot is large.
+
+Nothing to install to run a bot: the framework only uses what Node has (Node 24 or later). Discord's rate limits, payload sizes and reconnections are handled for you.
+
+## Versions
+
+`chapterjs`, `create-chapterjs` and `create-chapter` are always released with the same version, and follow [semantic versioning](https://semver.org): what a bot's files use (the functions exported by `chapterjs`, their options, what your functions receive, the files and env vars of a project, the CLI commands) only changes in a major version. A new feature comes in a minor one, a fix in a patch. The [changelog](https://www.chapterjs.org/changelog) says what each version brings, and `chapterjs dev` tells you when a new one is out.
+
+## Contributing
+
+The source, the issues and the documentation live in [github.com/chapterjs/chapterjs](https://github.com/chapterjs/chapterjs). Read [CONTRIBUTING.md](https://github.com/chapterjs/chapterjs/blob/master/CONTRIBUTING.md) to get started.
+
+## License
+
+[MIT](./LICENSE)

package/dist/cli/cli.js

@@ -7,6 +7,7 @@ import { writeTypes } from './project.js';
 import { createLog } from './log.js';
 import { nodeTooOld } from './node-version.js';
 import { start } from './start.js';
+import { test } from './test.js';
 const { version } = JSON.parse(readFileSync(new URL('../../package.json', import.meta.url), 'utf8'));
 const USAGE = `Usage: chapterjs <command>
 
@@ -14,6 +15,7 @@ Commands:
   dev     Run your bot on your dev server and reload it when you save a file
   build   Check your bot and prepare it for production
   start   Run for everyone the bot that was built
+  test    Check your bot without Discord: every file once, then your scenarios
   sync    Write the types of your project (dev does it too)
 
 Options of start:
@@ -29,19 +31,40 @@ if (tooOld) {
 const [command, ...rest] = process.argv.slice(2);
 /**
  * Ctrl+C and a stop asked by the system both end the session cleanly, so
- * the bot goes offline at once. A second one does not wait.
+ * the bot goes offline at once. A second one, pressed while the first is
+ * still being handled, does not wait.
+ *
+ * One Ctrl+C reaches the bot twice when a package manager runs it (`pnpm
+ * dev`): once from the terminal, which signals every process of the
+ * foreground group, and once forwarded by the package manager. Two signals
+ * within a second are that one Ctrl+C, not a second one.
  */
 function stopSignal() {
     const controller = new AbortController();
+    let askedAt = 0;
     for (const name of ['SIGINT', 'SIGTERM']) {
         process.on(name, () => {
-            if (controller.signal.aborted)
-                process.exit(1);
+            const now = Date.now();
+            if (controller.signal.aborted) {
+                if (now - askedAt >= 1000)
+                    process.exit(1);
+                return;
+            }
+            askedAt = now;
             controller.abort();
         });
     }
     return controller.signal;
 }
+/**
+ * Ends the process once everything printed has reached the terminal. When
+ * the output is a pipe (`pnpm test` puts one between itself and the
+ * command), writes are asynchronous on macOS and Windows: `process.exit()`
+ * right after the last line would cut it.
+ */
+function exit() {
+    process.stdout.write('', () => process.exit());
+}
 /** `--processes 4` or `--processes=4`; `null` when it is not a count. */
 function readProcesses(args) {
     const index = args.findIndex(arg => arg === '--processes' || arg.startsWith('--processes='));
@@ -66,7 +89,7 @@ if (command === 'dev') {
         signal: controller.signal,
     });
     // Nothing may keep the process alive once the bot is disconnected.
-    process.exit();
+    exit();
 }
 else if (command === 'start') {
     const processes = readProcesses(rest);
@@ -91,7 +114,7 @@ else if (command === 'start') {
             script: process.argv[1],
             args: ['start'],
         });
-        process.exit();
+        exit();
     }
 }
 else if (command === 'sync') {
@@ -108,7 +131,19 @@ else if (command === undefined || command === '--help' || command === '-h') {
 }
 else if (command === 'build') {
     process.exitCode = await build({ cwd: process.cwd(), version, log });
-    process.exit();
+    exit();
+}
+else if (command === 'test') {
+    // How long a scenario may take: only tests shorten it.
+    const scenarioTimeout = Number(process.env.CHAPTERJS_SCENARIO_TIMEOUT);
+    process.exitCode = await test({
+        cwd: process.cwd(),
+        version,
+        log,
+        ...(scenarioTimeout > 0 ? { scenarioTimeout } : {}),
+        progress: process.stdout.isTTY === true,
+    });
+    exit();
 }
 else {
     log.error(`"${command}" is not a command.\n${USAGE}`);

package/dist/cli/project.d.ts

@@ -9,6 +9,8 @@ import type { Locale } from '../discord/types/common.js';
 import { type TaskEntry } from '../tasks/scheduler.js';
 import { type Bot, type BotOptions } from '../core/bot.js';
 import { type GatewayIntentName } from '../discord/intents.js';
+import type { GatewayDispatchEventName } from '../discord/types/gateway-events.js';
+import type { RawInteraction } from '../discord/types/interaction.js';
 import { type LoadedEvent } from '../events/router.js';
 import { type BuiltFile, type Declaration, type FailedFile } from '../loader/loader.js';
 import type { Log } from './log.js';
@@ -36,6 +38,18 @@ export interface ProjectOptions {
     stores?: StoreBackend;
     /** Only tests change this. */
     deferAfter?: number;
+    /**
+     * Told what the bot is doing with the files, and when it is done with
+     * it: what `chapterjs test` waits for. Nothing of the bot waits.
+     */
+    observe?: ProjectObserver;
+}
+/** What `chapterjs test` watches of a running project. */
+export interface ProjectObserver {
+    /** An interaction was given to the files; `done` once they answered it. */
+    interaction?(raw: RawInteraction, done: Promise<void>): void;
+    /** A gateway event was given to the files; `done` once they handled it. */
+    event?(event: GatewayDispatchEventName, data: unknown, done: Promise<void>): void;
 }
 /** What the types of a project are written from, once its files ran. */
 export interface TypesInfo {
@@ -140,6 +154,11 @@ export interface Project {
     startTasks(current: () => Bot | null): void;
     /** Stops the tasks: nothing runs after this. */
     stopTasks(): void;
+    /**
+     * Runs one task now, as the scheduler would when its time comes, with
+     * the bot given. Resolves once it is done; an error is reported.
+     */
+    runTask(entry: TaskEntry, bot: Bot, now?: Date): Promise<void>;
     /** Looks after the memory of the bot `current` returns. */
     watchMemory(current: () => Bot | null): {
         stop(): void;

package/dist/cli/project.js

@@ -22,7 +22,7 @@ import { DEFAULT_PRESENCE, presenceDeclaration, } from '../presence/declaration.
 import { assembleMessages, commandsDeclarations, languageDeclaration, languageDefaultsDeclaration, messagesDeclarations, scanLanguages, } from '../messages/declaration.js';
 import { translation } from '../messages/translate.js';
 import { translateCommand, unknownCommands } from '../messages/commands.js';
-import { TimerScheduler, } from '../tasks/scheduler.js';
+import { runTask, TimerScheduler, } from '../tasks/scheduler.js';
 import { createBot } from '../core/bot.js';
 import { watchMemory } from '../core/memory.js';
 import { GatewayIntent } from '../discord/intents.js';
@@ -76,7 +76,7 @@ export async function hasSources(cwd, log) {
     if ((await stat(join(cwd, 'src')).catch(() => null))?.isDirectory()) {
         return true;
     }
-    log.error('There is no src folder here.\nRun this command in the folder of your bot (the one with package.json), or create a project with "pnpm create chapter".');
+    log.error('There is no src folder here.\nRun this command in the folder of your bot (the one with package.json), or create a project with "pnpm create chapterjs".');
     return false;
 }
 /** The intents that only bring what happens in private messages. */
@@ -419,9 +419,12 @@ export function createProject(options) {
             stores.size === 0 &&
             presence === null &&
             messages === null,
-        filesNeeding: intent => [...events.values()]
-            .filter(({ event }) => (intentsOf(event) & GatewayIntent[intent]) !== 0)
-            .map(({ file }) => file),
+        // A file declaring several events that need the intent is named once.
+        filesNeeding: intent => [
+            ...new Set([...events.values()]
+                .filter(({ event }) => (intentsOf(event) & GatewayIntent[intent]) !== 0)
+                .map(({ file }) => file)),
+        ],
         intents: (privateEvents = true) => neededIntents() & (privateEvents ? ~0 : ~PRIVATE_INTENTS),
         async connect(connection) {
             const created = createBot({
@@ -449,14 +452,17 @@ export function createProject(options) {
                 },
                 beforeDispatch: (event, data) => router.before(created.ctx, event, data),
                 onDispatch(event, data, info) {
-                    router.dispatch(created.ctx, event, data, {
+                    const handled = router.dispatch(created.ctx, event, data, {
                         joined: info.joined,
                         before: info.before,
                     });
+                    options.observe?.event?.(event, data, handled);
                     if (event === 'INTERACTION_CREATE') {
                         const interaction = data;
-                        commandRouter.dispatch(created.ctx, interaction);
-                        componentRouter.dispatch(created.ctx, interaction);
+                        const answered = commandRouter.dispatch(created.ctx, interaction) ??
+                            componentRouter.dispatch(created.ctx, interaction) ??
+                            Promise.resolve();
+                        options.observe?.interaction?.(interaction, answered);
                     }
                 },
                 onEvent(event) {
@@ -518,6 +524,10 @@ export function createProject(options) {
             });
         },
         stopTasks: () => scheduler.stop(),
+        runTask(entry, bot, now = new Date()) {
+            const user = bot.ctx.cache.users.get(bot.ctx.self.userId);
+            return runTask(entry, { user, guilds: bot.ctx.cache.guilds, ...translation(bot.ctx, null) }, now, reporter.onError);
+        },
         // The bot looks after its own memory: it remembers less before memory
         // is full, and only speaks up when it can't give up anything more.
         closeStores: () => storeBackend.close(),

package/dist/cli/test.d.ts

@@ -0,0 +1,29 @@
+import type { Log } from './log.js';
+export interface TestOptions {
+    /** The folder of the project. */
+    cwd: string;
+    /** The version of the framework. */
+    version: string;
+    log: Log;
+    /** How long a scenario may take, in milliseconds. Default: 10 s. */
+    scenarioTimeout?: number;
+    /**
+     * Whether a person is watching a terminal: the check in progress is then
+     * shown, case by case, and replaced by its result once done.
+     */
+    progress?: boolean;
+}
+/**
+ * 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,
+ * those lines are erased and its result takes their place, so a report
+ * that passed reads as if nothing had moved. When nobody is watching (the
+ * output is not a terminal), nothing is shown meanwhile.
+ */
+export declare function checkProgress(enabled: boolean, log: Pick<Log, 'reload'>, write: (text: string) => void): {
+    start(title: string): void;
+    step(label: string): void;
+    clear(): void;
+};
+/** Resolves with the exit code of the process. */
+export declare function test(options: TestOptions): Promise<number>;