chapterjs 0.1.2 → 0.2.0

package/dist/cli/dev.js

@@ -1,206 +1,261 @@
-import { handleComponentInteraction, loadComponents, watchComponents, } from '../components.js';
-import { Gateway, GatewayCloseError } from '../discord/gateway.js';
-import { GatewayCloseCodes } from '../discord/constants.js';
-import { EventRouter, eventIntents, filesMissingMessageContent, loadEvents, privilegedIntentsUsage, watchEvents, } from '../events.js';
-import { loadPresence, startPresenceLoop, watchPresence } from '../presence.js';
-import { describeRuntimeError } from '../utils/modules.js';
-/** Returns false when there is no `.env` file. */
-function loadEnv() {
-    try {
-        process.loadEnvFile('.env');
-        return true;
-    }
-    catch (error) {
-        if (error.code !== 'ENOENT')
-            throw error;
-        return false;
-    }
-}
-/** The Bot page of the app in the Developer Portal, where the token and privileged intents are. */
-const botPage = (applicationId) => applicationId
-    ? `https://discord.com/developers/applications/${applicationId}/bot`
-    : 'https://discord.com/developers/applications > your application > Bot';
-const errorMessage = (error) => error instanceof Error ? error.message : String(error);
-function summarizeEvents(events) {
-    const counts = new Map();
-    for (const event of events)
-        counts.set(event.name, (counts.get(event.name) ?? 0) + 1);
-    return [...counts]
-        .map(([name, count]) => (count > 1 ? `${name} ×${count}` : name))
-        .join(', ');
-}
-let lastMessageContentNote = '';
-/** Explains it once per set of files, not on every reload. */
-function noteMessageContent(events, applicationId) {
-    const files = filesMissingMessageContent(events);
-    const key = files.join(',');
-    if (key === lastMessageContentNote)
-        return;
-    lastMessageContentNote = key;
-    if (files.length === 0)
-        return;
-    console.log(`ℹ ${files.join(', ')}: message.content is empty, except in DMs and in messages that mention the bot.\n` +
-        `  Nothing to do if that's enough for you. To read the text of every message, add\n` +
-        `  intents: ['MessageContent'] to defineEvent, then enable "Message Content Intent" in\n` +
-        `  ${botPage(applicationId)} (Privileged Gateway Intents).`);
-}
-/** After a reload error: the bot keeps the file's previous version. */
-const KEPT = '\n  Until you fix it, the bot keeps the last working version of this file, if any.';
-const COPY_GUILD_ID_HELP = 'To get it: Discord > User Settings > Advanced > enable Developer Mode, then right-click your server > Copy Server ID.';
-export async function dev() {
-    const hasEnvFile = loadEnv();
-    if (!hasEnvFile && !process.env.BOT_TOKEN) {
-        throw new Error(`No .env file in ${process.cwd()}.\n` +
-            '  Copy .env.example to .env, then fill in BOT_TOKEN and DEV_GUILD_ID.');
-    }
-    const token = process.env.BOT_TOKEN?.trim();
-    if (!token) {
-        throw new Error('BOT_TOKEN is missing from your .env file.\n' +
-            `  To get it: ${botPage(null)} > Reset Token.`);
-    }
-    if (token.startsWith('<')) {
-        throw new Error(`BOT_TOKEN still has the example value ${token}: replace it in your .env file with your bot's token.\n` +
-            `  To get it: ${botPage(null)} > Reset Token.`);
-    }
-    const devGuildId = process.env.DEV_GUILD_ID?.trim();
-    if (!devGuildId) {
-        throw new Error('DEV_GUILD_ID is missing from your .env file: it is the ID of the server where you test your bot.\n' +
-            `  ${COPY_GUILD_ID_HELP}`);
-    }
-    // https://docs.discord.com/developers/reference#snowflakes
-    if (!/^\d{17,20}$/.test(devGuildId)) {
-        throw new Error(`DEV_GUILD_ID "${devGuildId}" in your .env file is not a server ID (a number of 17 to 20 digits).\n` +
-            `  ${COPY_GUILD_ID_HELP}`);
+// `chapterjs dev`: runs the bot of the current folder against its dev
+// 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 { withoutGlobalTwins } from '../commands/twins.js';
+import { configure } from '../core/memory.js';
+import { GetGlobalApplicationCommands } from '../discord/endpoints.js';
+import { EVENTS } from '../events/registry.js';
+import { limitsFor } from '../events/router.js';
+import { enableProjectLoader, nextGeneration } from '../loader/hot.js';
+import { siteName } from '../loader/loader.js';
+import { messageOf } from '../loader/locate.js';
+import { watchPublic } from '../assets/public.js';
+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';
+/** Runs until stopped. Resolves with the exit code of the process. */
+export async function dev(options) {
+    const { cwd, log, signal } = options;
+    // 1. What the project must have before anything is tried.
+    const read = await readDevEnv(cwd, options.env);
+    if ('problems' in read) {
+        for (const problem of read.problems)
+            log.error(problem);
+        return 1;
     }
-    let presence = await loadPresence();
-    const loaded = await loadEvents();
-    const components = await loadComponents();
-    const loadErrors = [...loaded.errors, ...components.errors];
-    if (loadErrors.length > 0)
-        throw new Error(loadErrors.join('\n✗ '));
-    let events = loaded.events;
-    const gateway = new Gateway({
+    const { token, devGuildId } = read.env;
+    const src = join(cwd, 'src');
+    if (!(await hasSources(cwd, log)))
+        return 1;
+    // 2. The files of the project.
+    const project = createProject({
+        cwd,
+        version: options.version,
+        log,
+        ...(options.deferAfter === undefined
+            ? {}
+            : { deferAfter: options.deferAfter }),
+    });
+    await writeTypes(cwd);
+    enableProjectLoader(src, { reload: true });
+    // Taken before loading: what is saved from now on must be reloaded.
+    const loaded = snapshotFolder(src);
+    for (const failure of await project.load())
+        project.report(failure);
+    // 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());
+    // 3. What Discord must agree with before connecting.
+    const apiUrl = options.env.CHAPTERJS_API_URL;
+    const rest = new RestClient({
         token,
-        devGuildId,
-        dev: true,
-        presence: presence?.initial,
-        intents: eventIntents(events),
+        version: options.version,
+        ...(apiUrl ? { baseUrl: apiUrl } : {}),
     });
-    const { client } = gateway;
-    const onHandlerError = (file, error) => console.error(`✗ ${file}: ${describeRuntimeError(error)}`);
-    const router = new EventRouter(client, events, onHandlerError);
-    // Clicks on components of src/components/ go to their handler, not to interactionCreate
-    router.intercept = (event, data) => event === 'INTERACTION_CREATE' &&
-        handleComponentInteraction(client, data, onHandlerError);
-    gateway.on('dispatch', router.dispatch);
-    gateway.on('warning', (message) => console.warn(`⚠ ${message}`));
-    /** Intents known to work, kept while a reload tries new ones. */
-    let fallbackIntents = null;
-    /** Intents Discord refused after a reload, not retried until restart (identifies are limited per day). */
-    let refusedIntents = null;
-    gateway.on('ready', () => (fallbackIntents = null));
-    gateway.on('fatal', (error) => {
-        const disallowed = error instanceof GatewayCloseError &&
-            error.code === GatewayCloseCodes.DisallowedIntents;
-        const usage = disallowed ? privilegedIntentsUsage(events) : [];
-        console.error(`✗ ${error.message}`);
-        if (usage.length > 0) {
-            console.error(`  Requested by: ${usage.join(', ')}\n` +
-                `  Enable them in ${botPage(gateway.applicationId)} (Privileged Gateway Intents),\n` +
-                '  or remove them from your code.');
-        }
-        if (disallowed && fallbackIntents !== null) {
-            // Added by a reload: keep the bot running with the previous intents
-            console.error("  The bot keeps running without them, but the events that need them won't be received.\n" +
-                '  Restart chapterjs dev once they are enabled.');
-            refusedIntents = gateway.intents;
-            gateway.setIntents(fallbackIntents);
-            fallbackIntents = null;
-            gateway.login().catch(error => {
-                console.error(`✗ ${errorMessage(error)}`);
-                process.exit(1);
-            });
-            return;
-        }
-        process.exit(1);
+    const preflight = {
+        rest,
+        log,
+        interactive: options.interactive,
+        pollInterval: options.pollInterval ?? 3000,
+        signal,
+    };
+    let bot = null;
+    let watcher = null;
+    // The files of public/ are listed in the types: a file added or removed
+    // is offered (or not) by the editor at once.
+    const assets = watchPublic(cwd, () => {
+        writeTypes(cwd, project.typesInfo())
+            .then(written => {
+            if (written > 0)
+                log.reload('public/ changed: types updated');
+        })
+            .catch(() => { });
     });
-    gateway.on('resumed', () => console.log('↻ Reconnected to Discord'));
-    if (process.env.CHAPTER_DEBUG) {
-        gateway.on('dispatch', (event) => console.log(`← event ${event}`));
-        gateway.on('presenceUpdate', (presence) => console.log(`→ presence sent: ${presence.status} ${JSON.stringify(presence.activities)}`));
-    }
-    const shutdown = async () => {
-        await gateway.destroy();
-        process.exit(0);
+    const memory = project.watchMemory(() => bot);
+    // Resolved with the exit code when something ends the command: asked for
+    // from the very start, so nothing that happens early is lost.
+    let fatal;
+    const ended = new Promise(resolve => (fatal = resolve));
+    /** The intents of the current connection. */
+    let connectedIntents = 0;
+    const connect = async (known) => {
+        const application = known ?? (await fetchApplication(rest));
+        const intents = project.intents(false);
+        await ensurePrivilegedIntents(preflight, application, intents, project.filesNeeding);
+        const created = await project.connect({
+            token,
+            apiUrl,
+            // The dev bot only sees its dev server, and nothing outside servers:
+            // another process can run the same bot for everyone else, and what
+            // happens in private is answered by that one.
+            guildFilter: id => id === devGuildId,
+            privateEvents: false,
+            onFatal: failed => {
+                if (bot === failed)
+                    fatal(1);
+            },
+        });
+        connectedIntents = intents;
+        return created;
     };
-    process.once('SIGINT', shutdown);
-    process.once('SIGTERM', shutdown);
-    console.log('Connecting to Discord...');
-    const user = await gateway.login();
-    if (!gateway.guildIds.has(devGuildId)) {
-        await gateway.destroy();
-        // https://docs.discord.com/developers/topics/oauth2#bot-authorization-flow
-        const invite = new URL('https://discord.com/oauth2/authorize');
-        invite.searchParams.set('client_id', gateway.applicationId);
-        invite.searchParams.set('scope', 'bot applications.commands');
-        invite.searchParams.set('integration_type', '0'); // GUILD_INSTALL
-        invite.searchParams.set('guild_id', devGuildId);
-        invite.searchParams.set('disable_guild_select', 'true');
-        throw new Error(`${user.username} is not in your dev server ${devGuildId} (DEV_GUILD_ID) yet. Open this link to add it:\n  ${invite}\n\n` +
-            `  You need the "Manage Server" permission on this server, otherwise Discord won't let you continue.\n` +
-            `  Ask the server owner to open the link, or use a server you own as DEV_GUILD_ID.`);
+    try {
+        const application = await fetchApplication(rest);
+        const guild = await ensureInDevGuild(preflight, application.id, devGuildId);
+        bot = await connect(application);
+        // What the bot already has for everyone (a bot in production with the
+        // same token): asked once, so the dev server does not show it twice.
+        const global = await rest
+            .request(GetGlobalApplicationCommands, [application.id], {
+            query: { with_localizations: true },
+        })
+            .catch(() => []);
+        /** The commands shown twice, already said. */
+        const saidTwice = new Set();
+        /**
+         * Tells Discord the commands of the project, on the dev server only:
+         * they show up there at once. Nothing is sent when they did not change.
+         */
+        const syncCommands = async () => {
+            const { kept, changed } = withoutGlobalTwins(buildCommands([...project.commands.values()], { guild: true }), global);
+            for (const name of changed) {
+                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.`);
+            }
+            try {
+                return await registerCommands({
+                    rest,
+                    projectDir: cwd,
+                    applicationId: application.id,
+                    guildId: devGuildId,
+                    commands: kept,
+                });
+            }
+            catch (error) {
+                // The bot keeps running with the commands Discord already has.
+                log.error(`Discord refused the commands of your project: ${messageOf(error)}`);
+                return false;
+            }
+        };
+        const self = bot.ctx.cache.users.get(bot.ctx.self.userId);
+        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());
+        project.ready(bot);
+        // Tasks follow the bot through reconnections: they read the current one.
+        project.startTasks(() => 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.
+        const noted = new Set();
+        const notePrivateOnly = () => {
+            const note = (file, what) => {
+                if (noted.has(file))
+                    return;
+                noted.add(file);
+                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));
+            }
+            for (const entry of project.events.values()) {
+                const { event } = entry;
+                if (EVENTS[event.name].options &&
+                    event.options.where === 'dm') {
+                    note(siteName(entry), `this ${event.name} event`);
+                }
+            }
+            for (const entry of project.components.values()) {
+                const { component } = entry;
+                if (component.kind !== 'embed' && component.where === 'dm') {
+                    note(siteName(entry), `the ${component.kind} ${component.name}`);
+                }
+            }
+        };
+        notePrivateOnly();
+        // 4. Every save reloads the project. Watching starts right away; the
+        // first thing done is to tell Discord the commands.
+        let reloading = syncCommands().then(updated => {
+            if (updated)
+                log.success(`Commands updated on ${guild.name}`);
+        });
+        watcher = watchFolder(src, () => {
+            reloading = reloading
+                .then(async () => {
+                const started = performance.now();
+                nextGeneration();
+                const failures = await project.load();
+                for (const failure of failures)
+                    project.report(failure);
+                notePrivateOnly();
+                if (bot) {
+                    configure(bot.ctx.cache, limitsFor(project.events.values()));
+                    if (project.applyPresence(bot))
+                        log.reload('Presence updated');
+                }
+                // A language that appeared or went: `t` is typed from it. A
+                // command described in its file, or no longer: the languages
+                // offer it, or not.
+                if ((await writeTypes(cwd, project.typesInfo())) > 0)
+                    log.reload('Types updated');
+                const intents = project.intents(false);
+                if ((intents & ~connectedIntents) !== 0 && bot) {
+                    // Intents are given when connecting: new ones need a new session.
+                    log.reload(`Your files now need more from Discord (${describeIntents(intents & ~connectedIntents)}): reconnecting...`);
+                    const previous = bot;
+                    bot = null;
+                    await previous.close();
+                    bot = await connect();
+                    log.success(`Reconnected, ${project.summary()}`);
+                    if (await syncCommands())
+                        log.reload('Commands updated on Discord');
+                    return;
+                }
+                const ms = Math.max(1, Math.round(performance.now() - started));
+                const updated = await syncCommands();
+                if (failures.length === 0)
+                    log.reload(`Reloaded in ${ms} ms, ${project.summary()}`);
+                else {
+                    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');
+            })
+                .catch(error => {
+                if (!signal.aborted)
+                    explain(error, log);
+                fatal(1);
+            });
+        }, { loaded });
+        // 5. Until the user stops it, or Discord refuses the bot for good.
+        if (signal.aborted)
+            fatal(0);
+        signal.addEventListener('abort', () => fatal(0), { once: true });
+        const code = await ended;
+        await reloading.catch(() => { });
+        project.stopTasks();
+        watcher.close();
+        assets.close();
+        memory.stop();
+        await bot?.close();
+        if (code === 0)
+            log.success('Disconnected');
+        return code;
     }
-    console.log(`✓ Logged in as ${user.username} (${user.id})`);
-    console.log(`  Listening to server ${devGuildId} (DEV_GUILD_ID)`);
-    if (events.length > 0)
-        console.log(`  Events: ${summarizeEvents(events)}`);
-    if (components.ids.length > 0) {
-        console.log(`  Components: ${components.ids.join(', ')}`);
+    catch (error) {
+        project.stopTasks();
+        watcher?.close();
+        assets.close();
+        memory.stop();
+        await bot?.close();
+        if (signal.aborted)
+            return 0;
+        explain(error, log);
+        return 1;
     }
-    noteMessageContent(events, gateway.applicationId);
-    router.start();
-    watchComponents(async () => {
-        const result = await loadComponents();
-        for (const error of result.errors)
-            console.error(`✗ ${error}${KEPT}`);
-        console.log(`↻ src/components reloaded${result.ids.length > 0 ? ` (${result.ids.join(', ')})` : ''}`);
-    });
-    watchEvents(async () => {
-        const result = await loadEvents(process.cwd(), events);
-        for (const error of result.errors)
-            console.error(`✗ ${error}${KEPT}`);
-        events = result.events;
-        router.setEvents(events);
-        const intents = eventIntents(events);
-        if (intents !== gateway.intents && intents !== refusedIntents) {
-            console.log('↻ Intents changed: reconnecting to Discord');
-            fallbackIntents ??= gateway.intents;
-            gateway.setIntents(intents);
-        }
-        console.log(`↻ src/events reloaded${events.length > 0 ? ` (${summarizeEvents(events)})` : ''}`);
-        noteMessageContent(events, gateway.applicationId);
-    });
-    const presenceLogger = {
-        error: (error) => console.error(`✗ src/presence: ${errorMessage(error)}`),
-        warn: (message) => console.warn(`⚠ src/presence: ${message}`),
-    };
-    let stopPresenceLoop = presence
-        ? startPresenceLoop(gateway, presence, presenceLogger)
-        : null;
-    watchPresence(async () => {
-        try {
-            presence = await loadPresence();
-            stopPresenceLoop?.();
-            stopPresenceLoop = null;
-            if (presence)
-                stopPresenceLoop = startPresenceLoop(gateway, presence, presenceLogger);
-            else
-                gateway.setPresence({});
-            console.log('↻ src/presence reloaded');
-        }
-        catch (error) {
-            // Keep the bot running with the previous presence until the file is fixed
-            console.error(`✗ ${errorMessage(error)}${KEPT}`);
-        }
-    });
 }

package/dist/cli/env.d.ts

@@ -0,0 +1,31 @@
+export interface DevEnv {
+    token: string;
+    devGuildId: string;
+}
+/** 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;
+}
+/**
+ * Reads what `chapterjs dev` needs from the `.env` file of the project (the
+ * real environment wins when a value is set in both). Returns every problem
+ * at once, each one saying how to fix it.
+ */
+export declare function readDevEnv(projectDir: string, processEnv: Record<string, string | undefined>): Promise<{
+    env: DevEnv;
+} | {
+    problems: string[];
+}>;
+/**
+ * Reads what `chapterjs start` needs. In production the values often come
+ * from the host and not from a file: only the token is needed. The dev
+ * server is optional: when it is known, production leaves it to
+ * `chapterjs dev`.
+ */
+export declare function readStartEnv(projectDir: string, processEnv: Record<string, string | undefined>): Promise<{
+    env: StartEnv;
+} | {
+    problems: string[];
+}>;

package/dist/cli/env.js

@@ -0,0 +1,93 @@
+import { readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { parseEnv } from 'node:util';
+import { isSnowflake } from '../discord/snowflake.js';
+/**
+ * Values people leave in a `.env` copied from an example. Whole values only:
+ * a real token may start with any letters.
+ */
+const PLACEHOLDER = /^(?:(?:your|my)[-_ ]?(?:bot[-_ ]?)?token(?:[-_ ]?here)?|x{3,}|todo|token|changeme|change-me|<.*>|\.{3})$/i;
+/** The `.env` file of a project, with the real environment on top. */
+async function readEnv(projectDir, processEnv) {
+    let file = {};
+    let hasFile = true;
+    try {
+        file = parseEnv(await readFile(join(projectDir, '.env'), 'utf8'));
+    }
+    catch (error) {
+        if (error.code !== 'ENOENT')
+            throw error;
+        hasFile = false;
+    }
+    return {
+        read: name => (processEnv[name] ?? file[name] ?? '').trim(),
+        hasFile,
+    };
+}
+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) {
+    if (token === '' || PLACEHOLDER.test(token)) {
+        return `${where}: BOT_TOKEN is ${token === '' ? 'empty' : 'still the example value'}.\n${TOKEN_HELP}`;
+    }
+    if (/\s/.test(token)) {
+        return `${where}: BOT_TOKEN contains a space, so it is not a whole token.\nCopy it again from https://discord.com/developers/applications → your application → Bot → Reset Token.`;
+    }
+    return null;
+}
+/**
+ * Reads what `chapterjs dev` needs from the `.env` file of the project (the
+ * real environment wins when a value is set in both). Returns every problem
+ * at once, each one saying how to fix it.
+ */
+export async function readDevEnv(projectDir, processEnv) {
+    const { read, hasFile } = await readEnv(projectDir, processEnv);
+    const token = read('BOT_TOKEN').replace(/^Bot\s+/i, '');
+    const devGuildId = read('DEV_GUILD_ID');
+    const problems = [];
+    if (!hasFile && token === '' && devGuildId === '') {
+        return {
+            problems: [
+                'There is no .env file in this folder.\nCopy .env.example to .env, then fill in BOT_TOKEN and DEV_GUILD_ID.',
+            ],
+        };
+    }
+    const wrongToken = tokenProblem(token, '.env');
+    if (wrongToken)
+        problems.push(wrongToken);
+    if (devGuildId === '') {
+        problems.push(`.env: DEV_GUILD_ID is empty.\nIn Discord, right-click your test server → Copy Server ID (enable Settings → Advanced → Developer Mode to see it).`);
+    }
+    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 } };
+}
+/**
+ * Reads what `chapterjs start` needs. In production the values often come
+ * from the host and not from a file: only the token is needed. The dev
+ * server is optional: when it is known, production leaves it to
+ * `chapterjs dev`.
+ */
+export async function readStartEnv(projectDir, processEnv) {
+    const { read, hasFile } = await readEnv(projectDir, processEnv);
+    const token = read('BOT_TOKEN').replace(/^Bot\s+/i, '');
+    const devGuildId = read('DEV_GUILD_ID');
+    if (!hasFile && token === '') {
+        return {
+            problems: [
+                `BOT_TOKEN is not set.\nGive it to the bot the way your host does it (its "environment variables" or "secrets"), or in a .env file in this folder.\n${TOKEN_HELP}`,
+            ],
+        };
+    }
+    const problems = [];
+    const wrongToken = tokenProblem(token, hasFile ? '.env' : 'Environment');
+    if (wrongToken)
+        problems.push(wrongToken);
+    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
+        ? { problems }
+        : { env: { token, devGuildId: devGuildId === '' ? null : devGuildId } };
+}

package/dist/cli/log.d.ts

@@ -0,0 +1,13 @@
+export interface Log {
+    /** `✓` something worked. */
+    success(message: string): void;
+    /** `ℹ` something worth knowing. */
+    info(message: string): void;
+    /** `↻` a reload or a reconnection. */
+    reload(message: string): void;
+    /** `⚠` something to look at, that does not stop the bot. */
+    warn(message: string): void;
+    /** `✗` something failed: what happened, then what to do. */
+    error(message: string): void;
+}
+export declare function createLog(write: (line: string) => void, colors: boolean): Log;

package/dist/cli/log.js

@@ -0,0 +1,17 @@
+// Everything the CLI prints goes through here: one symbol per kind of
+// message, colors only when a person is reading.
+const CODES = { green: 32, blue: 34, yellow: 33, red: 31 };
+export function createLog(write, colors) {
+    const line = (symbol, color, message) => {
+        const shown = colors ? `\x1b[${CODES[color]}m${symbol}\x1b[0m` : symbol;
+        // Following lines are aligned under the first one.
+        write(`${shown} ${message.split('\n').join('\n  ')}`);
+    };
+    return {
+        success: message => line('✓', 'green', message),
+        info: message => line('ℹ', 'blue', message),
+        reload: message => line('↻', 'blue', message),
+        warn: message => line('⚠', 'yellow', message),
+        error: message => line('✗', 'red', message),
+    };
+}

package/dist/cli/node-version.d.ts

@@ -0,0 +1,8 @@
+/** The oldest Node.js ChapterJS runs on, as `engines` says in package.json. */
+export declare const MINIMUM_NODE = 24;
+/**
+ * What to tell the developer when this Node.js is older than ChapterJS
+ * needs, or `null` when it is recent enough. `engines` is only a warning
+ * when installing, which npm does not even show: this is what refuses.
+ */
+export declare function nodeTooOld(version?: string): string | null;

package/dist/cli/node-version.js

@@ -0,0 +1,13 @@
+/** The oldest Node.js ChapterJS runs on, as `engines` says in package.json. */
+export const MINIMUM_NODE = 24;
+/**
+ * What to tell the developer when this Node.js is older than ChapterJS
+ * needs, or `null` when it is recent enough. `engines` is only a warning
+ * when installing, which npm does not even show: this is what refuses.
+ */
+export function nodeTooOld(version = process.versions.node) {
+    const major = Number(version.split('.')[0]);
+    if (major >= MINIMUM_NODE)
+        return null;
+    return `ChapterJS needs Node.js ${MINIMUM_NODE} or newer, and this is Node.js ${version}. Install the LTS version from https://nodejs.org, then run the command again.`;
+}