chapterjs 0.3.0 → 0.5.0

package/README.md

@@ -30,15 +30,17 @@ export default command({
 });
 ```
 
-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.
+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()`, `ranking()`, `presence()`, `language()`. The folders are yours to organise with.
 
 ## What it does
 
-- **Slash commands** with typed options, choices, autocomplete, permissions, cooldowns and translations.
+- **Slash commands** with typed options, choices, autocomplete, permissions, cooldowns and translations, and **menu commands** on the right click of a message or a person.
 - **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.
+- **Waiting for an answer**: `await channel.waitForMessage({ matches: 'paris', within: '30s' })`, a click or a reaction, right where your function asked.
 - **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.
+- **Presence**: one activity, or several in turn, with texts computed when shown.
+- **Storage**: `store<Warning[]>({ expires: '30d' })` keeps data from one restart to the next, per server, typed, in a JSON file written for you, or in Redis with `storage: 'redis'` and a `REDIS_URL`; `ranking()` keeps a score per member in order, for leaderboards.
 - **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.

package/dist/assets/public.js

@@ -4,7 +4,7 @@
 import { existsSync, watch } from 'node:fs';
 import { readdir } from 'node:fs/promises';
 import { join, relative, sep } from 'node:path';
-import { watchFolder } from '../loader/watch.js';
+import { snapshotFolder, watchFolder } from '../loader/watch.js';
 /** The folder, at the root of the project. */
 export const PUBLIC_FOLDER = 'public';
 /**
@@ -69,9 +69,9 @@ export function watchPublic(projectDir, onChange) {
     const appeared = () => {
         if (inner)
             return;
-        // The folder was not there: what it has by the time it is watched
-        // (files copied with it, or written right after) is all new.
-        watchInside(Promise.resolve(''));
+        // The folder was not there: what it has now (files copied with it) is
+        // told at once, and what is written after it by the watch.
+        watchInside(snapshotFolder(root));
         if (!inner)
             return;
         outer?.close();

package/dist/cli/build.d.ts

@@ -1,4 +1,5 @@
 import { type BuiltFile } from '../loader/loader.js';
+import { type FoundUses } from '../loader/usage.js';
 import type { Log } from './log.js';
 /** Where the build of a project is, from its folder. */
 export declare const buildDir: (cwd: string) => string;
@@ -12,8 +13,11 @@ export interface BuildInfo {
     sources: string;
     commands: number;
     events: number;
-    /** Whether the files join voice channels (an intent to ask for). */
-    voice: boolean;
+    /**
+     * What the files do that only their code shows, with the files doing it
+     * (`CODE_USES`: intents to ask for).
+     */
+    uses: FoundUses;
 }
 /** One value for everything in a folder: it changes when a file does. */
 export declare function fingerprint(dir: string): Promise<string>;

package/dist/cli/build.js

@@ -14,8 +14,9 @@ import { join, relative, sep } from 'node:path';
 import { pathToFileURL } from 'node:url';
 import { enableProjectLoader } from '../loader/hot.js';
 import { listSources } from '../loader/loader.js';
-import { sourcesJoinVoice } from '../voice/usage.js';
-import { createProject, hasSources, writeTypes } from './project.js';
+import { scanUses } from '../loader/usage.js';
+import { MemoryStoreBackend } from '../store/memory-backend.js';
+import { CODE_USES, createProject, hasSources, writeTypes } from './project.js';
 /** Where the build of a project is, from its folder. */
 export const buildDir = (cwd) => join(cwd, '.chapterjs', 'build');
 /** The file the whole bot is compiled into, in the build. */
@@ -105,7 +106,18 @@ export async function build(options) {
     };
     // 1. Every file must run, one by one: each says what is wrong with it.
     enableProjectLoader(src, { reload: false });
-    const sources = createProject({ cwd, version: options.version, log });
+    // The files run once and keep nothing: a store, wherever it says it
+    // keeps its data, has nowhere to go (so a build needs no Redis).
+    const nothing = {
+        file: new MemoryStoreBackend(),
+        redis: new MemoryStoreBackend(),
+    };
+    const sources = createProject({
+        cwd,
+        version: options.version,
+        log,
+        stores: nothing,
+    });
     const failures = await sources.load();
     // 2. Types: what the editor underlines, for the whole project. Written
     // once the files ran, so a language only offers the commands they do
@@ -181,6 +193,7 @@ export async function build(options) {
         version: options.version,
         log,
         built: await loadBundle(cwd),
+        stores: nothing,
     });
     const broken = await built.load();
     if (broken.length > 0) {
@@ -193,7 +206,7 @@ export async function build(options) {
         sources: await fingerprint(src),
         commands: built.commands.size,
         events: built.events.size,
-        voice: await sourcesJoinVoice(cwd),
+        uses: await scanUses(cwd, CODE_USES),
     };
     await writeFile(join(out, 'build.json'), JSON.stringify(info, null, 2));
     if (built.isEmpty())

package/dist/cli/dev.js

@@ -2,7 +2,7 @@
 // server, and reloads every file of the project when it is saved.
 import { join } from 'node:path';
 import { registerCommands } from '../commands/register.js';
-import { buildCommands, commandName, privateOnly } from '../commands/tree.js';
+import { buildCommands, capitalize, describeCommand, privateOnly, } from '../commands/tree.js';
 import { withoutGlobalTwins } from '../commands/twins.js';
 import { configure } from '../core/memory.js';
 import { GetGlobalApplicationCommands } from '../discord/endpoints.js';
@@ -16,7 +16,9 @@ import { snapshotFolder, watchFolder } from '../loader/watch.js';
 import { RestClient } from '../rest/rest.js';
 import { readDevEnv } from './env.js';
 import { describeIntents, ensureInDevGuild, ensurePrivilegedIntents, fetchApplication, } from './preflight.js';
-import { createProject, explain, hasSources, writeTypes } from './project.js';
+import { createProject, explain, hasSources, reportLooseRejections, writeTypes, } from './project.js';
+import { checkRedis, describeRedisStores, redisStores } from './redis.js';
+import { DEV_PREFIX } from '../store/redis-backend.js';
 import { checkForUpdate, describeUpdate } from './update-check.js';
 /** Runs until stopped. Resolves with the exit code of the process. */
 export async function dev(options) {
@@ -30,8 +32,16 @@ export async function dev(options) {
     }
     const { token, devGuildId } = read.env;
     const src = join(cwd, 'src');
+    // Every key written from here starts with `dev:`: a Redis shared with
+    // production, which the docs advise against, is never mixed up.
+    const redis = read.env.redis
+        ? redisStores(read.env.redis, log, { prefix: DEV_PREFIX })
+        : null;
     if (!(await hasSources(cwd, log)))
         return 1;
+    // A promise of the files left alone is an error of the file, not the end
+    // of the bot.
+    const loose = reportLooseRejections(cwd, log);
     // Asked now, said once the bot is online: the registry answers while the
     // files load and Discord is checked, so nobody waits for it.
     const update = checkForUpdate({
@@ -44,6 +54,7 @@ export async function dev(options) {
         cwd,
         version: options.version,
         log,
+        ...(redis ? { stores: { redis } } : {}),
         ...(options.deferAfter === undefined
             ? {}
             : { deferAfter: options.deferAfter }),
@@ -57,6 +68,12 @@ export async function dev(options) {
     // Now that the files ran, a language only offers the commands they do
     // not describe, and `t` is typed from the default language.
     await writeTypes(cwd, project.typesInfo());
+    // A store kept in Redis needs it now, not when someone uses the bot.
+    if (!(await checkRedis(project, redis, log))) {
+        await project.closeStores();
+        return 1;
+    }
+    let redisLine = describeRedisStores(project, redis);
     // 3. What Discord must agree with before connecting.
     const apiUrl = options.env.CHAPTERJS_API_URL;
     const rest = new RestClient({
@@ -133,7 +150,7 @@ export async function dev(options) {
                 if (saidTwice.has(name))
                     continue;
                 saidTwice.add(name);
-                log.info(`/${name} is not the same here as in production, so ${guild.name} shows it twice: yours, and the one everyone has. It is shown once again when production runs your version.`);
+                log.info(`${capitalize(name)} is not the same here as in production, so ${guild.name} shows it twice: yours, and the one everyone has. It is shown once again when production runs your version.`);
             }
             try {
                 return await registerCommands({
@@ -154,9 +171,12 @@ export async function dev(options) {
         log.success(`Connected to ${guild.name} as ${self.username}`);
         log.info(`Intents computed from your files: ${describeIntents(connectedIntents)}`);
         (project.isEmpty() ? log.info : log.success)(project.summary());
+        if (redisLine)
+            log.info(redisLine);
         project.ready(bot);
         // Tasks follow the bot through reconnections: they read the current one.
         project.startTasks(() => bot);
+        project.startPresence(() => bot);
         // Said once per file: what only happens in private messages can't be
         // tried here. Discord only offers the commands of a server in that
         // server, and private messages are answered by the bot in production.
@@ -169,7 +189,7 @@ export async function dev(options) {
                 log.info(`${file} ${what} only works in private messages, and chapterjs dev only runs your bot in ${guild.name}. Try it with chapterjs start.`);
             };
             for (const entry of privateOnly([...project.commands.values()])) {
-                note(siteName(entry), commandName(entry.command.path));
+                note(siteName(entry), describeCommand(entry.command));
             }
             for (const entry of project.events.values()) {
                 const { event } = entry;
@@ -215,6 +235,13 @@ export async function dev(options) {
                 // offer it, or not.
                 if ((await writeTypes(cwd, project.typesInfo())) > 0)
                     log.reload('Types updated');
+                // A store moved to Redis, or out of it, is said once.
+                const kept = describeRedisStores(project, redis);
+                if (kept !== redisLine) {
+                    redisLine = kept;
+                    if (kept)
+                        log.info(kept);
+                }
                 const intents = project.intents(false);
                 if ((intents & ~connectedIntents) !== 0 && bot) {
                     // Intents are given when connecting: new ones need a new session.
@@ -225,7 +252,7 @@ export async function dev(options) {
                     bot = await connect();
                     log.success(`Reconnected, ${project.summary()}`);
                     if (await syncCommands())
-                        log.reload('Commands updated on Discord');
+                        log.reload(`Commands updated on ${guild.name}`);
                     return;
                 }
                 const ms = Math.max(1, Math.round(performance.now() - started));
@@ -236,7 +263,7 @@ export async function dev(options) {
                     log.warn(`Reloaded with ${failures.length === 1 ? 'an error' : `${failures.length} errors`}: ${failures.length === 1 ? 'that file keeps' : 'those files keep'} running ${failures.length === 1 ? 'its' : 'their'} last working version`);
                 }
                 if (updated)
-                    log.reload('Commands updated on Discord');
+                    log.reload(`Commands updated on ${guild.name}`);
             })
                 .catch(error => {
                 if (!signal.aborted)
@@ -251,22 +278,26 @@ export async function dev(options) {
         const code = await ended;
         await reloading.catch(() => { });
         project.stopTasks();
+        project.stopPresence();
         watcher.close();
         assets.close();
         memory.stop();
         await bot?.close();
         await project.closeStores();
+        loose();
         if (code === 0)
             log.success('Disconnected');
         return code;
     }
     catch (error) {
         project.stopTasks();
+        project.stopPresence();
         watcher?.close();
         assets.close();
         memory.stop();
         await bot?.close();
         await project.closeStores();
+        loose();
         if (signal.aborted)
             return 0;
         explain(error, log);

package/dist/cli/env.d.ts

@@ -1,12 +1,17 @@
+import { type RedisAddress } from '../redis/url.js';
 export interface DevEnv {
     token: string;
     devGuildId: string;
+    /** Where the stores with `storage: 'redis'` go, when `REDIS_URL` is set. */
+    redis: RedisAddress | null;
 }
 /** What `chapterjs start` runs with. */
 export interface StartEnv {
     token: string;
     /** The dev server, when the project has one: production leaves it alone. */
     devGuildId: string | null;
+    /** Where the stores with `storage: 'redis'` go, when `REDIS_URL` is set. */
+    redis: RedisAddress | null;
 }
 /**
  * Reads what `chapterjs dev` needs from the `.env` file of the project (the

package/dist/cli/env.js

@@ -2,6 +2,7 @@ import { readFile } from 'node:fs/promises';
 import { join } from 'node:path';
 import { parseEnv } from 'node:util';
 import { isSnowflake } from '../discord/snowflake.js';
+import { parseRedisUrl } from '../redis/url.js';
 /**
  * Values people leave in a `.env` copied from an example. Whole values only:
  * a real token may start with any letters.
@@ -24,6 +25,27 @@ async function readEnv(projectDir, processEnv) {
         hasFile,
     };
 }
+/**
+ * `REDIS_URL` and `REDIS_PASSWORD`, when they are there: nothing is needed
+ * unless a store asks for Redis, which the files say once they loaded.
+ */
+function redisProblem(read, where) {
+    const url = read('REDIS_URL');
+    const password = read('REDIS_PASSWORD');
+    if (url === '') {
+        if (password !== '') {
+            return {
+                problem: `${where}: REDIS_PASSWORD is set, but REDIS_URL is not.\nAdd REDIS_URL, the address of your Redis (like redis://localhost:6379), or remove REDIS_PASSWORD.`,
+            };
+        }
+        return { redis: null };
+    }
+    const parsed = parseRedisUrl(url, password);
+    if ('problem' in parsed) {
+        return { problem: `${where}: REDIS_URL ${parsed.problem}` };
+    }
+    return { redis: parsed.address };
+}
 const TOKEN_HELP = 'Copy the token of your bot from https://discord.com/developers/applications → your application → Bot → Reset Token.';
 /** What is wrong with a token, if anything. */
 function tokenProblem(token, where) {
@@ -61,7 +83,12 @@ export async function readDevEnv(projectDir, processEnv) {
     else if (!isSnowflake(devGuildId)) {
         problems.push(`.env: DEV_GUILD_ID is "${devGuildId}", which is not a server ID (an ID only has digits).\nIn Discord, right-click your test server → Copy Server ID.`);
     }
-    return problems.length > 0 ? { problems } : { env: { token, devGuildId } };
+    const redis = redisProblem(read, '.env');
+    if ('problem' in redis)
+        problems.push(redis.problem);
+    return problems.length > 0 || 'problem' in redis
+        ? { problems }
+        : { env: { token, devGuildId, redis: redis.redis } };
 }
 /**
  * Reads what `chapterjs start` needs. In production the values often come
@@ -87,7 +114,16 @@ export async function readStartEnv(projectDir, processEnv) {
     if (devGuildId !== '' && !isSnowflake(devGuildId)) {
         problems.push(`DEV_GUILD_ID is "${devGuildId}", which is not a server ID (an ID only has digits).\nRemove it, or copy it again: in Discord, right-click your test server → Copy Server ID.`);
     }
-    return problems.length > 0
+    const redis = redisProblem(read, hasFile ? '.env' : 'Environment');
+    if ('problem' in redis)
+        problems.push(redis.problem);
+    return problems.length > 0 || 'problem' in redis
         ? { problems }
-        : { env: { token, devGuildId: devGuildId === '' ? null : devGuildId } };
+        : {
+            env: {
+                token,
+                devGuildId: devGuildId === '' ? null : devGuildId,
+                redis: redis.redis,
+            },
+        };
 }

package/dist/cli/project.d.ts

@@ -1,7 +1,10 @@
+import { type WaitWatcher } from '../waiting/waiters.js';
+import { type FoundUses } from '../loader/usage.js';
 import { type CommandEntry } from '../commands/tree.js';
 import { type ComponentEntry } from '../components/router.js';
 import { type LoadedStore } from '../store/declaration.js';
-import { type StoreBackend } from '../store/backend.js';
+import { type LoadedRanking } from '../ranking/declaration.js';
+import { type StoreBackend, type StoreStorage } from '../store/backend.js';
 import { type LoadedPresence } from '../presence/declaration.js';
 import { type DeclaredCommand, type DeclaredLanguage } from '../messages/declaration.js';
 import { type LoadedMessages } from '../messages/translate.js';
@@ -26,16 +29,19 @@ export interface ProjectOptions {
      */
     built?: readonly BuiltFile[];
     /**
-     * Whether the files join voice channels, as `chapterjs build` found.
+     * What the files do that only their code shows (`CODE_USES`: joining
+     * voice, waiting for messages or reactions), as `chapterjs build` found.
      * Without it, the files of `src` are read on every load.
      */
-    joinsVoice?: boolean;
+    uses?: FoundUses;
     /**
-     * Where the stores of the project keep their data. A file per store in
-     * the `data/` folder of the project by default; the first process of a
-     * cluster, through IPC, for the other processes.
+     * Where the stores of the project keep their data, by storage. `file`: a
+     * file per store in the `data/` folder of the project by default, the
+     * first process of a cluster through IPC for the other processes.
+     * `redis`: what the CLI made of `REDIS_URL`; without one, a store that
+     * asks for Redis is reported and left out.
      */
-    stores?: StoreBackend;
+    stores?: Partial<Record<StoreStorage, StoreBackend>>;
     /** Only tests change this. */
     deferAfter?: number;
     /**
@@ -50,6 +56,11 @@ export interface ProjectObserver {
     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;
+    /**
+     * Told when a run of the files starts and stops waiting for what comes
+     * next (`waitForMessage()`...): its `done` waits for the test to act.
+     */
+    waits?: WaitWatcher;
 }
 /** What the types of a project are written from, once its files ran. */
 export interface TypesInfo {
@@ -77,6 +88,12 @@ export interface TypesInfo {
 export declare function writeTypes(cwd: string, info?: TypesInfo): Promise<number>;
 /** The kinds of declarations a project is made of: one per feature. */
 export declare const DECLARATIONS: readonly Declaration<unknown>[];
+/** A ranking, with where it is declared. */
+export interface RankingEntry {
+    file: string;
+    export: string;
+    ranking: LoadedRanking;
+}
 /** A store, with where it is declared. */
 export interface StoreEntry {
     file: string;
@@ -97,6 +114,8 @@ export interface ConnectOptions {
     globalLimit?: number | undefined;
     /** Only tests change this. */
     identifyInterval?: number | undefined;
+    /** Where nothing can play (`chapterjs test`): what `join()` says at once. */
+    voiceUnavailable?: string | undefined;
     /** Discord refused the bot for good. */
     onFatal: (bot: Bot) => void;
 }
@@ -111,8 +130,14 @@ export interface Project {
     readonly components: ReadonlyMap<string, ComponentEntry>;
     readonly tasks: ReadonlyMap<string, TaskEntry>;
     readonly stores: ReadonlyMap<string, StoreEntry>;
-    /** Where the stores keep their data: what a cluster serves to its other processes. */
-    readonly storeBackend: StoreBackend;
+    readonly rankings: ReadonlyMap<string, RankingEntry>;
+    /** Where the stores keep their data, by storage: what a cluster serves to its other processes. */
+    readonly storeBackends: ReadonlyMap<StoreStorage, StoreBackend>;
+    /** What is kept in Redis: the names of the stores and of the rankings, sorted. */
+    redisStores(): {
+        stores: string[];
+        rankings: string[];
+    };
     /** The presence declared, or `null` without one. */
     readonly presence: LoadedPresence | null;
     /** The languages of the project, assembled, or `null` without any. */
@@ -147,6 +172,20 @@ export interface Project {
      * change since the bot was given one.
      */
     applyPresence(bot: Bot): boolean;
+    /**
+     * Shows the activities of the presence in turn on the bot `current`
+     * returns, and runs its functions when their time comes.
+     */
+    startPresence(current: () => Bot | null): void;
+    /** Stops the presence: nothing of it runs after this. */
+    stopPresence(): void;
+    /** The file of the presence, or `null` without one. */
+    readonly presenceFile: string | null;
+    /**
+     * Runs every function of the presence once (the list, then each text),
+     * as the rotation would, with the bot given. What goes wrong is reported.
+     */
+    runPresence(bot: Bot): Promise<void>;
     /**
      * Starts the tasks of the project, with the bot `current` returns (none
      * while it reconnects). Only one process of a bot runs them.
@@ -166,6 +205,19 @@ export interface Project {
     /** Writes what the stores still have to write. Nothing is kept after this. */
     closeStores(): Promise<void>;
 }
+/**
+ * What the files may do that only their code shows, each with the intents
+ * it needs: read in `src/` (dev, at every load) or kept by the build.
+ */
+export declare const CODE_USES: readonly [import("../loader/usage.js").CodeUse, import("../loader/usage.js").CodeUse, import("../loader/usage.js").CodeUse];
+/**
+ * A promise of the files that nobody waited for (`store.set()` without
+ * `await`, in a `run` that is not `async`) rejects with nobody to tell:
+ * Node would stop the bot. Reported instead, with the file and the line,
+ * and what to write. A rejection from outside the files stays what it is:
+ * a bug of the framework, loud. Returns what stops watching.
+ */
+export declare function reportLooseRejections(cwd: string, log: Log): () => void;
 /** Whether the folder is a project: it has a `src` folder. */
 export declare function hasSources(cwd: string, log: Log): Promise<boolean>;
 export declare function createProject(options: ProjectOptions): Project;