chapterjs 0.2.2 → 0.3.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Quentin Truffy
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

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/cluster.d.ts

@@ -1,3 +1,4 @@
+import type { StoreBackend } from '../store/backend.js';
 import { type IdentifyGate } from '../gateway/identify-queue.js';
 /** How many shards one process runs when nothing else is asked. */
 export declare const SHARDS_PER_PROCESS = 4;
@@ -50,6 +51,8 @@ export interface ClusterOptions {
     signal: AbortSignal;
     /** Shows a line printed by one of the processes. */
     write: (line: string) => void;
+    /** Where the data of the stores is: this process keeps it for the others. */
+    stores: StoreBackend;
     /** Every process is connected, for the first time. */
     onReady: (info: {
         guilds: number;

package/dist/cli/cluster.js

@@ -9,6 +9,7 @@
 // identify. A setup on several machines would give each process another
 // `IdentifyGate`, and nothing else here would change.
 // https://docs.discord.com/developers/events/gateway#sharding
+import { serveStores, } from '../store/ipc-backend.js';
 import { fork } from 'node:child_process';
 import { availableParallelism } from 'node:os';
 import { createInterface } from 'node:readline';
@@ -134,8 +135,10 @@ export async function runCluster(options) {
         for (const stream of [child.stdout, child.stderr]) {
             createInterface({ input: stream }).on('line', line => options.write(`[${index + 1}] ${line}`));
         }
+        const stores = serveStores(options.stores, reply => tell(child, reply));
         child.on('message', (message) => {
-            if (message.type === 'identify') {
+            stores(message);
+            if (message.type !== 'store' && message.type === 'identify') {
                 void gate.wait(message.shard).then(() => {
                     tell(child, { type: 'identify', id: message.id });
                 });

package/dist/cli/dev.js

@@ -255,6 +255,7 @@ export async function dev(options) {
         assets.close();
         memory.stop();
         await bot?.close();
+        await project.closeStores();
         if (code === 0)
             log.success('Disconnected');
         return code;
@@ -265,6 +266,7 @@ export async function dev(options) {
         assets.close();
         memory.stop();
         await bot?.close();
+        await project.closeStores();
         if (signal.aborted)
             return 0;
         explain(error, log);

package/dist/cli/project.d.ts

@@ -1,5 +1,7 @@
 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 LoadedPresence } from '../presence/declaration.js';
 import { type DeclaredCommand, type DeclaredLanguage } from '../messages/declaration.js';
 import { type LoadedMessages } from '../messages/translate.js';
@@ -7,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';
@@ -26,8 +30,26 @@ export interface ProjectOptions {
      * Without it, the files of `src` are read on every load.
      */
     joinsVoice?: boolean;
+    /**
+     * 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.
+     */
+    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 {
@@ -55,6 +77,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 store, with where it is declared. */
+export interface StoreEntry {
+    file: string;
+    export: string;
+    store: LoadedStore;
+}
 /** What a bot of the project is connected with. */
 export interface ConnectOptions {
     token: string;
@@ -82,6 +110,9 @@ export interface Project {
     readonly commands: ReadonlyMap<string, CommandEntry>;
     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;
     /** The presence declared, or `null` without one. */
     readonly presence: LoadedPresence | null;
     /** The languages of the project, assembled, or `null` without any. */
@@ -123,10 +154,17 @@ 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;
     };
+    /** Writes what the stores still have to write. Nothing is kept after this. */
+    closeStores(): Promise<void>;
 }
 /** Whether the folder is a project: it has a `src` folder. */
 export declare function hasSources(cwd: string, log: Log): Promise<boolean>;

package/dist/cli/project.js

@@ -15,11 +15,14 @@ import { findConflicts } from '../commands/tree.js';
 import { componentDeclaration, findDuplicates, } from '../components/declaration.js';
 import { ComponentRouter } from '../components/router.js';
 import { taskDeclaration } from '../tasks/declaration.js';
+import { storeDeclaration } from '../store/declaration.js';
+import { setStoreBackend } from '../store/backend.js';
+import { DATA_FOLDER, FileStoreBackend } from '../store/file-backend.js';
 import { DEFAULT_PRESENCE, presenceDeclaration, } from '../presence/declaration.js';
 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';
@@ -64,6 +67,7 @@ export const DECLARATIONS = [
     commandDeclaration,
     componentDeclaration,
     taskDeclaration,
+    storeDeclaration,
     presenceDeclaration,
     languageDeclaration,
 ];
@@ -72,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. */
@@ -117,6 +121,9 @@ export function createProject(options) {
     const { cwd, log } = options;
     // Where `asset()` reads the files of the project from.
     setPublicDir(cwd);
+    // Where the stores keep their data, for every store of the process.
+    const storeBackend = options.stores ?? new FileStoreBackend(join(cwd, DATA_FOLDER));
+    setStoreBackend(storeBackend);
     const report = (failure) => {
         const where = locate(failure.error, cwd);
         log.error(`${where ? `${where.file}:${where.line}` : siteName(failure)} ${messageOf(failure.error)}`);
@@ -142,6 +149,7 @@ export function createProject(options) {
     let commands = new Map();
     let components = new Map();
     let tasks = new Map();
+    let stores = new Map();
     let presence = null;
     /** The files the presence was declared in, to keep it when they break. */
     let presenceFiles = new Set();
@@ -171,6 +179,10 @@ export function createProject(options) {
         get tasks() {
             return tasks;
         },
+        get stores() {
+            return stores;
+        },
+        storeBackend,
         get presence() {
             return presence;
         },
@@ -201,11 +213,12 @@ export function createProject(options) {
             // then read, kind by kind.
             const sources = built ? { modules: built, failed: [] } : await loadSources(cwd);
             const read = (declaration) => readDeclarations(sources.modules, declaration);
-            const [eventItems, commandItems, componentItems, taskItems, presenceItems, languageItems,] = [
+            const [eventItems, commandItems, componentItems, taskItems, storeItems, presenceItems, languageItems,] = [
                 read(eventDeclaration),
                 read(commandDeclaration),
                 read(componentDeclaration),
                 read(taskDeclaration),
+                read(storeDeclaration),
                 read(presenceDeclaration),
                 read(languageDeclaration),
             ];
@@ -259,6 +272,15 @@ export function createProject(options) {
             ], entry => entry.task.name, 'task');
             tasks = new Map(sameTask.valid.map(entry => [keyOf(entry), entry]));
             scheduler.set(tasks.values());
+            // Two stores with one name would share one file: the later is left out.
+            const sameStore = sameNames([
+                ...next(stores, storeItems, item => ({
+                    file: item.file,
+                    export: item.export,
+                    store: item.value,
+                })).values(),
+            ], entry => entry.store.name, 'store');
+            stores = new Map(sameStore.valid.map(entry => [keyOf(entry), entry]));
             // One presence. A second one is left out.
             const [first, ...extra] = presenceItems.loaded;
             if (first)
@@ -346,11 +368,17 @@ export function createProject(options) {
                 ...commandItems.failed,
                 ...componentItems.failed,
                 ...taskItems.failed,
+                ...storeItems.failed,
                 ...presenceItems.failed,
                 ...languageItems.failed,
                 ...badTexts,
                 ...twice,
-                ...[...conflicts, ...unique.conflicts, ...sameTask.conflicts].map(({ file, export: exported, message }) => ({
+                ...[
+                    ...conflicts,
+                    ...unique.conflicts,
+                    ...sameTask.conflicts,
+                    ...sameStore.conflicts,
+                ].map(({ file, export: exported, message }) => ({
                     file,
                     export: exported,
                     error: new TypeError(message),
@@ -375,6 +403,7 @@ export function createProject(options) {
                     ? [count(components.size, 'component', 'components')]
                     : []),
                 ...(tasks.size > 0 ? [count(tasks.size, 'task', 'tasks')] : []),
+                ...(stores.size > 0 ? [count(stores.size, 'store', 'stores')] : []),
                 ...(presence ? ['a presence'] : []),
                 ...(messages
                     ? [
@@ -387,11 +416,15 @@ export function createProject(options) {
             commands.size === 0 &&
             components.size === 0 &&
             tasks.size === 0 &&
+            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({
@@ -419,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) {
@@ -488,8 +524,13 @@ 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(),
         watchMemory: current => watchMemory({
             cache: () => current()?.ctx.cache,
             onTightened: ({ members, forgotten }, { used, limit }) => log.info(`Memory was getting full (${megabytes(used)} of ${megabytes(limit)}): the bot now remembers ${members} members per server at most, and forgot ${forgotten} members and users it had not seen for the longest. Nothing changes for your code.`),

package/dist/cli/start.js

@@ -1,6 +1,7 @@
 // `chapterjs start`: runs for everyone the bot `chapterjs build` prepared.
 // Nothing is reloaded, commands are registered for every server, and a
 // large bot is spread over several processes by itself.
+import { IpcStoreBackend } from '../store/ipc-backend.js';
 import { registerCommands } from '../commands/register.js';
 import { buildCommands } from '../commands/tree.js';
 import { GLOBAL_REQUESTS_PER_SECOND } from '../discord/api.js';
@@ -54,6 +55,19 @@ export async function start(options) {
         log,
         built: files,
         joinsVoice: built.info.voice === true,
+        // A process started by another keeps no data: the first one does, for
+        // all of them.
+        ...(assignment
+            ? {
+                stores: new IpcStoreBackend({
+                    send: message => {
+                        if (process.connected)
+                            process.send?.(message);
+                    },
+                    on: listener => process.on('message', listener),
+                }),
+            }
+            : {}),
         ...(options.deferAfter === undefined
             ? {}
             : { deferAfter: options.deferAfter }),
@@ -132,14 +146,17 @@ export async function start(options) {
             signal,
             identifyInterval,
             write: options.write,
+            stores: project.storeBackend,
             onReady: ({ user, guilds }) => online(user, guilds),
             onRestart: (index, why) => log.warn(`Process ${index + 1} of ${processes} stopped by itself (${why}): starting it again. Its servers are back in a moment.`),
         });
+        await project.closeStores();
         if (code === 0)
             log.success('Disconnected');
         return code;
     }
     catch (error) {
+        await project.closeStores();
         if (signal.aborted)
             return 0;
         explain(error, log);
@@ -168,6 +185,7 @@ async function run(project, connection, stopped, connected, { tasks = true } = {
         project.stopTasks();
         memory.stop();
         await bot?.close();
+        await project.closeStores();
     }
 }
 /** The whole bot in this process. */

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>;