chapterjs 0.1.4 → 0.2.1

package/dist/cli/project.js

@@ -6,64 +6,66 @@ import { stat } from 'node:fs/promises';
 import { join } from 'node:path';
 import { setPublicDir } from '../assets/asset.js';
 import { listPublic, publicDeclarations } from '../assets/public.js';
-import { eventTypedFolders } from '../events/types.js';
 import { MissingForEvent } from '../events/registry.js';
 import { sourcesJoinVoice } from '../voice/usage.js';
 import { writeGenerated } from '../loader/generated.js';
-import { commandsConvention } from '../commands/convention.js';
+import { commandDeclaration, scanCommands } from '../commands/declaration.js';
 import { CommandRouter } from '../commands/router.js';
 import { findConflicts } from '../commands/tree.js';
-import { componentsConvention, findDuplicates, } from '../components/convention.js';
+import { componentDeclaration, findDuplicates, } from '../components/declaration.js';
 import { ComponentRouter } from '../components/router.js';
-import { tasksConvention } from '../tasks/convention.js';
-import { DEFAULT_PRESENCE, presenceConvention, } from '../presence/convention.js';
-import { assembleMessages, commandsDeclarations, languagesConvention, languageTypedFolders, messagesDeclarations, } from '../messages/convention.js';
+import { taskDeclaration } from '../tasks/declaration.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 { createBot } from '../core/bot.js';
 import { watchMemory } from '../core/memory.js';
 import { GatewayIntent } from '../discord/intents.js';
-import { eventsConvention } from '../events/convention.js';
+import { eventDeclaration } from '../events/declaration.js';
 import { EventRouter, intentsFor, intentsOf, limitsFor, } from '../events/router.js';
 import { GatewayFatalError, SessionLimitError } from '../gateway/errors.js';
-import { listFolder, loadBuilt, loadFolder, } from '../loader/loader.js';
+import { loadSources, readDeclarations, siteName, } from '../loader/loader.js';
 import { locate, messageOf } from '../loader/locate.js';
 import { DiscordApiError, DiscordUnavailableError, InvalidTokenError, } from '../rest/errors.js';
 import { PreflightFailure } from './preflight.js';
 /**
- * Writes the types of a project (`.chapterjs/`): one project per typed
- * folder (every event, every language file), and what every file gets,
- * like the files of `public/`. With the commands and the languages as
- * they loaded, a language file only offers the ones without `description`
- * in their file, `t` is typed from the default language and `default:
- * true` is refused in every file when another one says it (`defaults`,
- * the files that do); without them (`sync`, which runs nothing),
- * every command is offered and the first language file types `t`.
+ * Writes the types of a project (`.chapterjs/`): what the project adds to
+ * 'chapterjs', like the files of `public/`, its languages and its
+ * commands. With the project as it loaded (`info`), a language only
+ * offers the commands without `description`, `t` is typed from the
+ * default language and `default: true` is refused in every language that
+ * says it when another one does; without it (`sync`, which runs nothing),
+ * the commands and the languages are found by reading the files, every
+ * command is offered, and the first language or the one that says
+ * `default: true` types `t`.
  * @returns how many files were written
  */
-export async function writeTypes(cwd, commands, messages, defaults = []) {
-    const [files, languageFiles, commandFiles] = await Promise.all([
+export async function writeTypes(cwd, info) {
+    const [files, found, names] = await Promise.all([
         listPublic(cwd),
-        listFolder(cwd, languagesConvention),
-        listFolder(cwd, commandsConvention),
+        info ? null : scanLanguages(cwd),
+        info ? null : scanCommands(cwd),
     ]);
-    return writeGenerated(cwd, [...eventTypedFolders(), ...languageTypedFolders(languageFiles, defaults)], publicDeclarations(files) +
-        messagesDeclarations(languageFiles, messages ? messages.files.get(messages.default) : undefined), 
-    // Only language files use it, and they are in the main project.
-    commandsDeclarations(commandFiles.map(({ file }) => ({
-        file,
-        described: commands?.get(file)?.command.described ?? false,
-    }))));
+    const languages = info ? info.languages : found.languages;
+    const defaultLocale = info ? info.defaultLocale : found.defaultLocale;
+    const commands = info
+        ? info.commands
+        : names.map(name => ({ name, described: false }));
+    return writeGenerated(cwd, publicDeclarations(files) +
+        messagesDeclarations(languages, defaultLocale) +
+        languageDefaultsDeclaration(info?.languageDefaults ?? []) +
+        commandsDeclarations(commands));
 }
-/** The conventional folders of a project: one per feature. */
-export const CONVENTIONS = [
-    eventsConvention,
-    commandsConvention,
-    componentsConvention,
-    tasksConvention,
-    presenceConvention,
-    languagesConvention,
+/** The kinds of declarations a project is made of: one per feature. */
+export const DECLARATIONS = [
+    eventDeclaration,
+    commandDeclaration,
+    componentDeclaration,
+    taskDeclaration,
+    presenceDeclaration,
+    languageDeclaration,
 ];
 /** Whether the folder is a project: it has a `src` folder. */
 export async function hasSources(cwd, log) {
@@ -79,13 +81,45 @@ const PRIVATE_INTENTS = GatewayIntent.DirectMessages |
     GatewayIntent.DirectMessageTyping |
     GatewayIntent.DirectMessagePolls;
 const megabytes = (bytes) => `${Math.round(bytes / 1024 / 1024)} MB`;
+/** What tells one declaration from another: its file and its export. */
+const keyOf = (site) => `${site.file}#${site.export}`;
+/**
+ * Two declarations with the same name, where the name is the export's
+ * (a task): the later one is left out, with a message saying so.
+ */
+function sameNames(entries, nameOf, what) {
+    const seen = new Map();
+    const conflicts = [];
+    const valid = [...entries]
+        .sort((a, b) => a.file === b.file
+        ? a.export < b.export
+            ? -1
+            : 1
+        : a.file < b.file
+            ? -1
+            : 1)
+        .filter(entry => {
+        const first = seen.get(nameOf(entry));
+        if (!first) {
+            seen.set(nameOf(entry), entry);
+            return true;
+        }
+        conflicts.push({
+            file: entry.file,
+            export: entry.export,
+            message: `There is already a ${what} named ${nameOf(entry)}, in ${first.file}: the name of the export is the name of the ${what}, so rename one of them.`,
+        });
+        return false;
+    });
+    return { valid, conflicts };
+}
 export function createProject(options) {
     const { cwd, log } = options;
     // Where `asset()` reads the files of the project from.
     setPublicDir(cwd);
-    const report = ({ file, error }) => {
-        const where = locate(error, cwd);
-        log.error(`${where ? `${where.file}:${where.line}` : file} ${messageOf(error)}`);
+    const report = (failure) => {
+        const where = locate(failure.error, cwd);
+        log.error(`${where ? `${where.file}:${where.line}` : siteName(failure)} ${messageOf(failure.error)}`);
     };
     const router = new EventRouter((file, error) => report({ file, error }), (event, error) => {
         const missing = error instanceof MissingForEvent ? error : null;
@@ -109,11 +143,13 @@ export function createProject(options) {
     let components = new Map();
     let tasks = new Map();
     let presence = null;
+    /** The files the presence was declared in, to keep it when they break. */
+    let presenceFiles = new Set();
     // Joining voice needs the bot's own voice state, sent with an intent.
     let voice = options.joinsVoice ?? false;
     const neededIntents = () => intentsFor(events.values()) | (voice ? GatewayIntent.GuildVoiceStates : 0);
     let messages = null;
-    /** The last version of each language file that loaded. */
+    /** The last version of each language that loaded. */
     let languages = new Map();
     let languageDefaults = [];
     /** The bot running the files now, to give it what a reload changes. */
@@ -141,107 +177,134 @@ export function createProject(options) {
         get messages() {
             return messages;
         },
-        get languageDefaults() {
-            return languageDefaults;
-        },
+        typesInfo: () => ({
+            languages: [...languages.values()].map(entry => ({
+                file: entry.file,
+                export: entry.export,
+                name: entry.name,
+                locale: entry.language.locale,
+            })),
+            ...(messages ? { defaultLocale: messages.default } : {}),
+            languageDefaults,
+            commands: [...commands.values()].map(({ command }) => ({
+                name: command.path.join(' '),
+                described: command.described,
+            })),
+        }),
         report,
         async load() {
             const { built } = options;
             if (options.joinsVoice === undefined) {
                 voice = await sourcesJoinVoice(cwd);
             }
-            const [eventFiles, commandFiles, componentFiles, taskFiles, presenceFiles, messageFiles,] = await Promise.all(built
-                ? [
-                    loadBuilt(eventsConvention, built),
-                    loadBuilt(commandsConvention, built),
-                    loadBuilt(componentsConvention, built),
-                    loadBuilt(tasksConvention, built),
-                    loadBuilt(presenceConvention, built),
-                    loadBuilt(languagesConvention, built),
-                ]
-                : [
-                    loadFolder(cwd, eventsConvention),
-                    loadFolder(cwd, commandsConvention),
-                    loadFolder(cwd, componentsConvention),
-                    loadFolder(cwd, tasksConvention),
-                    loadFolder(cwd, presenceConvention),
-                    loadFolder(cwd, languagesConvention),
-                ]);
-            const nextEvents = new Map();
-            for (const { file, value } of eventFiles.loaded) {
-                nextEvents.set(file, { file, event: value });
-            }
-            for (const { file } of eventFiles.failed) {
-                const previous = events.get(file);
-                if (previous)
-                    nextEvents.set(file, previous);
-            }
-            events = nextEvents;
+            // Every file of src/ runs (or ran, in a build); what each exports is
+            // 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,] = [
+                read(eventDeclaration),
+                read(commandDeclaration),
+                read(componentDeclaration),
+                read(taskDeclaration),
+                read(presenceDeclaration),
+                read(languageDeclaration),
+            ];
+            const broken = new Set(sources.failed.map(({ file }) => file));
+            /**
+             * The next version of a kind: what loaded now, plus the last good
+             * version of what failed (an export that can't be read, or a file
+             * that can't run at all).
+             */
+            const next = (previous, items, make) => {
+                const result = new Map();
+                for (const item of items.loaded)
+                    result.set(keyOf(item), make(item));
+                const failedKeys = new Set(items.failed.map(({ file, export: exported }) => keyOf({ file, export: exported ?? 'default' })));
+                for (const [key, entry] of previous) {
+                    if (failedKeys.has(key) || broken.has(entry.file)) {
+                        result.set(key, entry);
+                    }
+                }
+                return result;
+            };
+            events = next(events, eventItems, item => ({
+                file: item.file,
+                export: item.export,
+                event: item.value,
+            }));
             router.set(events.values());
-            const entries = commandFiles.loaded.map(({ file, value }) => ({ file, command: value }));
-            for (const { file } of commandFiles.failed) {
-                const previous = commands.get(file);
-                if (previous)
-                    entries.push(previous);
-            }
-            const { valid, conflicts } = findConflicts(entries);
-            commands = new Map(valid.map(entry => [entry.file, entry]));
-            const pieces = componentFiles.loaded.map(({ file, value }) => ({ file, component: value }));
-            for (const { file } of componentFiles.failed) {
-                const previous = components.get(file);
-                if (previous)
-                    pieces.push(previous);
-            }
-            const unique = findDuplicates(pieces);
-            components = new Map(unique.valid.map(entry => [entry.file, entry]));
+            const { valid, conflicts } = findConflicts([
+                ...next(commands, commandItems, item => ({
+                    file: item.file,
+                    export: item.export,
+                    command: item.value,
+                })).values(),
+            ]);
+            commands = new Map(valid.map(entry => [keyOf(entry), entry]));
+            const unique = findDuplicates([
+                ...next(components, componentItems, item => ({
+                    file: item.file,
+                    export: item.export,
+                    component: item.value,
+                })).values(),
+            ]);
+            components = new Map(unique.valid.map(entry => [keyOf(entry), entry]));
             componentRouter.set(components.values());
-            const nextTasks = new Map();
-            for (const { file, value } of taskFiles.loaded) {
-                nextTasks.set(file, { file, task: value });
-            }
-            for (const { file } of taskFiles.failed) {
-                const previous = tasks.get(file);
-                if (previous)
-                    nextTasks.set(file, previous);
-            }
-            tasks = nextTasks;
+            const sameTask = sameNames([
+                ...next(tasks, taskItems, item => ({
+                    file: item.file,
+                    export: item.export,
+                    task: item.value,
+                })).values(),
+            ], entry => entry.task.name, 'task');
+            tasks = new Map(sameTask.valid.map(entry => [keyOf(entry), entry]));
             scheduler.set(tasks.values());
-            // One presence file. A second one (another extension) is left out.
-            const [first, ...extra] = presenceFiles.loaded;
+            // One presence. A second one is left out.
+            const [first, ...extra] = presenceItems.loaded;
             if (first)
                 presence = first.value;
-            else if (presenceFiles.failed.length === 0)
+            else if (presenceItems.failed.length === 0 &&
+                ![...broken].some(file => presenceFiles.has(file))) {
                 presence = null;
-            const twice = extra.map(({ file }) => ({
-                file,
-                error: new TypeError(`There are two presence files: ${first.file} is used, keep only one.`),
-            }));
-            const nextLanguages = new Map();
-            for (const { file, value } of messageFiles.loaded) {
-                nextLanguages.set(file, { file, language: value });
-            }
-            for (const { file } of messageFiles.failed) {
-                const previous = languages.get(file);
-                if (previous)
-                    nextLanguages.set(file, previous);
             }
-            // What the files say now, before a file is put back to its last good
-            // version: two files saying default: true are both underlined.
+            presenceFiles = new Set(presenceItems.loaded.map(({ file }) => file));
+            const twice = extra.map(item => ({
+                file: item.file,
+                export: item.export,
+                error: new TypeError(`There are two presences: the one of ${siteName(first)} is used, keep only one.`),
+            }));
+            const nextLanguages = next(languages, languageItems, item => ({
+                file: item.file,
+                export: item.export,
+                name: item.name,
+                language: item.value,
+            }));
+            // What the files say now, before a declaration is put back to its
+            // last good version: two languages saying default: true are both
+            // underlined.
             languageDefaults = [...nextLanguages.values()]
                 .filter(({ language }) => language.isDefault)
-                .map(({ file }) => file);
+                .map(({ language }) => language.locale);
             const previousLanguages = languages;
             languages = nextLanguages;
             let assembled = assembleMessages([...languages.values()]);
             // A language that no longer matches the others keeps its last version
-            // that did, like a file that no longer loads.
-            const restored = assembled.failed.filter(({ file }) => {
-                const previous = previousLanguages.get(file);
-                return previous !== undefined && previous !== languages.get(file);
+            // that did, like a declaration that no longer loads.
+            const restored = assembled.failed.filter(failure => {
+                const key = keyOf({
+                    file: failure.file,
+                    export: failure.export ?? 'default',
+                });
+                const previous = previousLanguages.get(key);
+                return previous !== undefined && previous !== languages.get(key);
             });
             if (restored.length > 0) {
-                for (const { file } of restored) {
-                    languages.set(file, previousLanguages.get(file));
+                for (const failure of restored) {
+                    const key = keyOf({
+                        file: failure.file,
+                        export: failure.export ?? 'default',
+                    });
+                    languages.set(key, previousLanguages.get(key));
                 }
                 const again = assembleMessages([...languages.values()]);
                 assembled = {
@@ -260,34 +323,36 @@ export function createProject(options) {
             // be described is left out.
             const badTexts = [...assembled.failed];
             if (messages) {
-                const paths = new Set([...commands.values()].map(entry => entry.command.path.join('/')));
-                for (const { file, path } of unknownCommands(messages, paths)) {
+                const names = new Set([...commands.values()].map(entry => entry.command.path.join(' ')));
+                for (const { file, path } of unknownCommands(messages, names)) {
                     badTexts.push({
                         file,
-                        error: new TypeError(`"commands" translates "${path}", which is not a command of this project${paths.size > 0 ? ` (its commands are: ${[...paths].join(', ')})` : ''}. The key is the path of the command file, like 'ping' or 'mod/ban'.`),
+                        error: new TypeError(`"commands" translates "${path}", which is not a command of this project${names.size > 0 ? ` (its commands are: ${[...names].join(', ')})` : ''}. The key is the name of the command, like 'ping' or 'mod ban'.`),
                     });
                 }
             }
-            for (const [file, entry] of commands) {
-                const { command, failed } = translateCommand(file, entry.command, messages);
+            for (const [key, entry] of commands) {
+                const { command, failed } = translateCommand(siteName(entry), entry.command, messages);
                 badTexts.push(...failed);
                 if (command)
-                    commands.set(file, { ...entry, command });
+                    commands.set(key, { ...entry, command });
                 else
-                    commands.delete(file);
+                    commands.delete(key);
             }
             commandRouter.set(commands.values());
             return [
-                ...eventFiles.failed,
-                ...commandFiles.failed,
-                ...componentFiles.failed,
-                ...taskFiles.failed,
-                ...presenceFiles.failed,
-                ...messageFiles.failed,
+                ...sources.failed,
+                ...eventItems.failed,
+                ...commandItems.failed,
+                ...componentItems.failed,
+                ...taskItems.failed,
+                ...presenceItems.failed,
+                ...languageItems.failed,
                 ...badTexts,
                 ...twice,
-                ...[...conflicts, ...unique.conflicts].map(({ file, message }) => ({
+                ...[...conflicts, ...unique.conflicts, ...sameTask.conflicts].map(({ file, export: exported, message }) => ({
                     file,
+                    export: exported,
                     error: new TypeError(message),
                 })),
             ];
@@ -299,7 +364,7 @@ export function createProject(options) {
                 tasks.size === 0 &&
                 presence === null &&
                 messages === null) {
-                return 'Nothing to run yet: add a file in src/commands/ or in a folder like src/events/messageCreate/';
+                return "Nothing to run yet: export a command or an event from a file of src/, like export default command({ name: 'ping', ... })";
             }
             return `${[
                 ...(commands.size > 0

package/dist/cli/update-check.d.ts

@@ -0,0 +1,42 @@
+export declare const CHANGELOG_URL = "https://www.chapterjs.org/changelog";
+export interface UpdateCheckOptions {
+    /** The folder of the project. */
+    cwd: string;
+    /** The version of the framework that runs. */
+    version: string;
+    env: Record<string, string | undefined>;
+    /** Only tests change these. */
+    registryUrl?: string;
+    timeout?: number;
+    now?: () => number;
+}
+/** A version newer than the one that runs. */
+export interface Update {
+    current: string;
+    latest: string;
+    /** What to type to install it, with the package manager of the project. */
+    command: string;
+}
+/**
+ * The command that updates `chapterjs` in a project: with the package
+ * manager its lockfile belongs to, else the one that started the command
+ * (`pnpm dev` sets `npm_config_user_agent`), else npm, which every
+ * machine with Node has.
+ */
+export declare function updateCommand(cwd: string, env: Record<string, string | undefined>): string;
+/**
+ * Whether `latest` is a newer version than `current`. Only the three
+ * numbers count: `1.0.0-beta.2` and `1.0.0` are not told apart, so a
+ * prerelease never says to install the final version it precedes.
+ */
+export declare function isNewer(latest: string, current: string): boolean;
+/**
+ * Whether a newer `chapterjs` is published. The registry is asked at most
+ * once a day (`.chapterjs/cache/update.json` keeps the answer), with a
+ * short timeout, and never throws: without network, or when the registry
+ * does not answer, there is nothing to say. Resolves with the update to
+ * install, or `null` when the bot runs the latest version.
+ */
+export declare function checkForUpdate(options: UpdateCheckOptions): Promise<Update | null>;
+/** The line that tells the developer about an update. */
+export declare function describeUpdate(update: Update): string;

package/dist/cli/update-check.js

@@ -0,0 +1,125 @@
+// Whether a newer chapterjs is published, and the command that installs it:
+// told where the developer starts their bot, so nobody has to watch npm.
+import { existsSync } from 'node:fs';
+import { mkdir, readFile, writeFile } from 'node:fs/promises';
+import { dirname, join } from 'node:path';
+/** Where the package is published. */
+const NPM_REGISTRY = 'https://registry.npmjs.org';
+/** Asked once a day: a version is not published more often. */
+const CHECK_EVERY = 24 * 60 * 60 * 1000;
+/** A registry that does not answer must never hold the bot. */
+const DEFAULT_TIMEOUT = 5000;
+export const CHANGELOG_URL = 'https://www.chapterjs.org/changelog';
+const PACKAGE_MANAGERS = ['pnpm', 'npm', 'yarn', 'bun'];
+/** The lockfiles each package manager writes next to `package.json`. */
+const LOCKFILES = {
+    pnpm: ['pnpm-lock.yaml'],
+    npm: ['package-lock.json', 'npm-shrinkwrap.json'],
+    yarn: ['yarn.lock'],
+    bun: ['bun.lock', 'bun.lockb'],
+};
+/** What installs the latest version with each package manager. */
+const COMMANDS = {
+    pnpm: 'pnpm update chapterjs --latest',
+    npm: 'npm install chapterjs@latest',
+    yarn: 'yarn add chapterjs@latest',
+    bun: 'bun add chapterjs@latest',
+};
+/**
+ * The command that updates `chapterjs` in a project: with the package
+ * manager its lockfile belongs to, else the one that started the command
+ * (`pnpm dev` sets `npm_config_user_agent`), else npm, which every
+ * machine with Node has.
+ */
+export function updateCommand(cwd, env) {
+    const fromLockfile = PACKAGE_MANAGERS.find(pm => LOCKFILES[pm].some(name => existsSync(join(cwd, name))));
+    const agent = env.npm_config_user_agent?.split('/')[0];
+    const fromAgent = PACKAGE_MANAGERS.find(pm => pm === agent);
+    return COMMANDS[fromLockfile ?? fromAgent ?? 'npm'];
+}
+/** `1.2.3`, with or without a prerelease suffix, as numbers. */
+function parseVersion(version) {
+    const match = /^v?(\d+)\.(\d+)\.(\d+)(?:[-+].*)?$/.exec(version.trim());
+    return match ? [Number(match[1]), Number(match[2]), Number(match[3])] : null;
+}
+/**
+ * Whether `latest` is a newer version than `current`. Only the three
+ * numbers count: `1.0.0-beta.2` and `1.0.0` are not told apart, so a
+ * prerelease never says to install the final version it precedes.
+ */
+export function isNewer(latest, current) {
+    const a = parseVersion(latest);
+    const b = parseVersion(current);
+    if (!a || !b)
+        return false;
+    for (let i = 0; i < 3; i++) {
+        if (a[i] !== b[i])
+            return a[i] > b[i];
+    }
+    return false;
+}
+/** The version the registry publishes as `latest`, or `null`. */
+async function fetchLatest(registryUrl, timeout) {
+    try {
+        const response = await fetch(`${registryUrl}/chapterjs/latest`, {
+            headers: { accept: 'application/json' },
+            signal: AbortSignal.timeout(timeout),
+        });
+        if (!response.ok)
+            return null;
+        const { version } = (await response.json());
+        return typeof version === 'string' && parseVersion(version)
+            ? version
+            : null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Whether a newer `chapterjs` is published. The registry is asked at most
+ * once a day (`.chapterjs/cache/update.json` keeps the answer), with a
+ * short timeout, and never throws: without network, or when the registry
+ * does not answer, there is nothing to say. Resolves with the update to
+ * install, or `null` when the bot runs the latest version.
+ */
+export async function checkForUpdate(options) {
+    const { cwd, version, env } = options;
+    const now = options.now ?? Date.now;
+    const file = join(cwd, '.chapterjs', 'cache', 'update.json');
+    const cached = await readFile(file, 'utf8')
+        .then((text) => {
+        const value = JSON.parse(text);
+        return value &&
+            typeof value.checked === 'number' &&
+            typeof value.latest === 'string'
+            ? { checked: value.checked, latest: value.latest }
+            : null;
+    })
+        .catch(() => null);
+    let latest;
+    if (cached && now() - cached.checked < CHECK_EVERY) {
+        latest = cached.latest;
+    }
+    else {
+        latest = await fetchLatest(options.registryUrl ?? env.CHAPTERJS_REGISTRY_URL ?? NPM_REGISTRY, options.timeout ?? DEFAULT_TIMEOUT);
+        if (latest) {
+            // A folder or a disk that can't be written changes nothing: the
+            // registry is asked again next time.
+            await mkdir(dirname(file), { recursive: true })
+                .then(() => writeFile(file, JSON.stringify({ checked: now(), latest })))
+                .catch(() => { });
+        }
+        else {
+            // Yesterday's answer is better than none.
+            latest = cached?.latest ?? null;
+        }
+    }
+    if (!latest || !isNewer(latest, version))
+        return null;
+    return { current: version, latest, command: updateCommand(cwd, env) };
+}
+/** The line that tells the developer about an update. */
+export function describeUpdate(update) {
+    return `A new version of chapterjs is out: ${update.latest} (you have ${update.current}). To update, run:\n${update.command}\nWhat changed: ${CHANGELOG_URL}`;
+}