chapterjs 0.2.0 → 0.2.1

package/dist/cli/dev.js

@@ -17,6 +17,7 @@ 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 { checkForUpdate, describeUpdate } from './update-check.js';
 /** Runs until stopped. Resolves with the exit code of the process. */
 export async function dev(options) {
     const { cwd, log, signal } = options;
@@ -31,6 +32,13 @@ export async function dev(options) {
     const src = join(cwd, 'src');
     if (!(await hasSources(cwd, log)))
         return 1;
+    // 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({
+        cwd,
+        version: options.version,
+        env: options.env,
+    });
     // 2. The files of the project.
     const project = createProject({
         cwd,
@@ -178,6 +186,10 @@ export async function dev(options) {
             }
         };
         notePrivateOnly();
+        update.then(found => {
+            if (found && !signal.aborted)
+                log.info(describeUpdate(found));
+        });
         // 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 => {

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}`;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "chapterjs",
-  "version": "0.2.0",
+  "version": "0.2.1",
   "description": "The Discord framework",
   "type": "module",
   "license": "MIT",