create-chapter 0.1.2 → 0.2.0

package/dist/choose.js

@@ -0,0 +1,27 @@
+import * as p from '@clack/prompts';
+/**
+ * A select menu that never asks a question with only one answer: when a single
+ * choice can be picked, it is taken right away and the user is told why.
+ * Returns `undefined` when no choice can be picked, and the cancel symbol when
+ * the user presses Ctrl+C or Esc.
+ */
+export async function choose({ message, choices, initialValue, onlyChoice, }) {
+    const enabled = choices.filter(choice => !choice.disabled);
+    const [first] = enabled;
+    if (!first)
+        return undefined;
+    if (enabled.length === 1) {
+        p.log.info(onlyChoice(first.value));
+        return first.value;
+    }
+    // clack's option type can't be resolved for a generic `Value`, so the menu is
+    // typed with `string`: it only ever returns one of `choices`.
+    const picked = await p.select({
+        message,
+        initialValue: enabled.some(choice => choice.value === initialValue)
+            ? initialValue
+            : first.value,
+        options: choices,
+    });
+    return picked;
+}

package/dist/index.js

@@ -1,163 +1,96 @@
 #!/usr/bin/env node
 import * as p from '@clack/prompts';
-import { spawn } from 'node:child_process';
-import { cpSync, existsSync, readdirSync, readFileSync, renameSync, writeFileSync, } from 'node:fs';
-import path from 'node:path';
-import { fileURLToPath } from 'node:url';
-const TEMPLATE_DIR = fileURLToPath(new URL('../template', import.meta.url));
-const OWN_VERSION = JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8')).version;
-const DEFAULT_NAME = 'my-chapter-app';
-const RENAME_FILES = {
-    _gitignore: '.gitignore',
-};
-const PACKAGE_MANAGERS = ['pnpm', 'npm', 'yarn', 'bun'];
-function exitIfCancelled(value) {
+import { readFileSync } from 'node:fs';
+import { relative, resolve } from 'node:path';
+import { detectPackageManager, install, installedVersions, packageManagers, runScript, } from './package-manager.js';
+import { choose } from './choose.js';
+import { createProject, validateTargetDir } from './project.js';
+import { listTemplates } from './templates.js';
+import { nodeTooOld } from './node-version.js';
+/** Stops cleanly when the user presses Ctrl+C or Esc on a prompt. */
+function orExit(value) {
     if (p.isCancel(value)) {
-        p.cancel('Operation cancelled.');
+        p.cancel('Cancelled, nothing was created.');
         process.exit(0);
     }
     return value;
 }
-function toValidPackageName(name) {
-    return name
-        .trim()
-        .toLowerCase()
-        .replace(/\s+/g, '-')
-        .replace(/^[._]/, '')
-        .replace(/[^a-z0-9-~]+/g, '-');
-}
-function isEmptyDir(dir) {
-    if (!existsSync(dir))
-        return true;
-    // We tolerate .git to be able to do `git init` before `pnpm create chapter .`
-    return readdirSync(dir).every(f => f === '.git');
+// create-chapter and chapterjs are always released with the same version.
+const { version } = JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8'));
+p.intro(`Create a ChapterJS bot (v${version})`);
+const tooOld = nodeTooOld();
+if (tooOld) {
+    p.cancel(tooOld);
+    process.exit(1);
 }
-function validateDir(value) {
-    const dir = (value ?? '').trim() || DEFAULT_NAME;
-    if (!isEmptyDir(path.resolve(dir))) {
-        return dir === '.'
-            ? 'The current directory is not empty'
-            : `The directory "${dir}" already exists and is not empty`;
-    }
-    return undefined;
+// Started now so it runs while the user answers the first question.
+const versionsCheck = installedVersions();
+// `pnpm create chapter my-bot` skips the first question when the folder is valid.
+const argDir = process.argv[2];
+const argError = argDir === undefined ? undefined : validateTargetDir(argDir);
+if (argError)
+    p.log.warn(argError);
+const dir = argDir !== undefined && argError === undefined
+    ? argDir.trim()
+    : orExit(await p.text({
+        message: 'Where should the project be created? (. for the current folder)',
+        placeholder: 'my-bot',
+        defaultValue: 'my-bot',
+        validate: value => validateTargetDir(value || 'my-bot'),
+    })).trim();
+const versions = await versionsCheck;
+const pm = orExit(await choose({
+    message: 'Which package manager do you want to use?',
+    initialValue: detectPackageManager(),
+    choices: packageManagers.map(value => {
+        const version = versions[value];
+        return version === undefined
+            ? { value, label: `${value} (not installed)`, disabled: true }
+            : { value, hint: `v${version}` };
+    }),
+    onlyChoice: value => `Using ${value}, the only package manager installed`,
+}));
+if (pm === undefined) {
+    p.cancel(`No package manager found. Install one of ${packageManagers.join(', ')}, then run this command again.`);
+    process.exit(1);
 }
-function detectPackageManager() {
-    const agent = process.env.npm_config_user_agent ?? '';
-    return PACKAGE_MANAGERS.find(pm => agent.startsWith(`${pm}/`));
+const templates = await listTemplates();
+const template = orExit(await choose({
+    message: 'Which template do you want to start from?',
+    choices: templates.map(({ name, description }) => ({
+        value: name,
+        hint: description,
+    })),
+    onlyChoice: value => `Using the ${value} template`,
+}));
+if (template === undefined) {
+    p.cancel('No template found. Reinstall create-chapter and try again.');
+    process.exit(1);
 }
-function install(pm, cwd) {
-    const log = p.taskLog({
-        title: `Installing dependencies with ${pm}`,
-        limit: 8,
-    });
-    return new Promise((resolve, reject) => {
-        const child = spawn(pm, ['install'], {
-            cwd,
-            stdio: ['ignore', 'pipe', 'pipe'],
-            // Windows: pnpm/npm are .cmd
-            shell: process.platform === 'win32',
-        });
-        // Ctrl+C during install: stop the child before exiting
-        const onSigint = () => {
-            child.kill('SIGINT');
-            log.error('Installation cancelled.');
-            process.exit(130);
-        };
-        process.once('SIGINT', onSigint);
-        // raw: keep the chunks as-is (line breaks included)
-        const onData = (chunk) => log.message(chunk.toString(), { raw: true });
-        child.stdout.on('data', onData);
-        child.stderr.on('data', onData);
-        child.on('error', err => {
-            process.off('SIGINT', onSigint);
-            log.error(`Could not run ${pm}: ${err.message}`);
-            reject(err);
-        });
-        child.on('close', code => {
-            process.off('SIGINT', onSigint);
-            if (code === 0) {
-                log.success('Dependencies installed');
-                resolve();
-            }
-            else {
-                log.error(`${pm} install failed (code ${code})`, { showLog: true });
-                reject(new Error(`${pm} install failed (code ${code})`));
-            }
-        });
-    });
+await createProject({
+    dir,
+    template,
+    chapterjsVersion: `^${version}`,
+    packageManager: pm,
+});
+p.log.success(`Project created in ${resolve(dir)}`);
+const spinner = p.spinner();
+spinner.start(`Installing dependencies with ${pm}`);
+const result = await install(pm, dir);
+if (result.ok) {
+    spinner.stop(`Dependencies installed with ${pm}`);
 }
-async function main() {
-    const args = process.argv.slice(2);
-    const noInstall = args.includes('--no-install');
-    const argDir = args.find(arg => !arg.startsWith('--'));
-    const interactive = p.isTTY(process.stdout) && !p.isCI();
-    let projectDir;
-    if (argDir && !validateDir(argDir)) {
-        projectDir = argDir;
-    }
-    else {
-        if (argDir)
-            p.log.warn(validateDir(argDir));
-        const answer = exitIfCancelled(await p.text({
-            message: 'What is the name of your project? (. for the current directory)',
-            placeholder: DEFAULT_NAME,
-            defaultValue: DEFAULT_NAME,
-            validate: validateDir,
-        }));
-        projectDir = answer.trim() || DEFAULT_NAME;
-    }
-    const targetDir = path.resolve(projectDir);
-    const isCurrentDir = targetDir === process.cwd();
-    // "." -> current directory
-    const packageName = toValidPackageName(path.basename(targetDir));
-    const s = p.spinner();
-    s.start('Copying template');
-    cpSync(TEMPLATE_DIR, targetDir, { recursive: true });
-    for (const [from, to] of Object.entries(RENAME_FILES)) {
-        const src = path.join(targetDir, from);
-        if (existsSync(src))
-            renameSync(src, path.join(targetDir, to));
-    }
-    const pkgPath = path.join(targetDir, 'package.json');
-    const pkg = JSON.parse(readFileSync(pkgPath, 'utf8'));
-    pkg.name = packageName;
-    // The template depends on `workspace:*` inside the monorepo; chapterjs and
-    // create-chapter are released together, so pin the same version.
-    pkg.dependencies.chapterjs = `^${OWN_VERSION}`;
-    writeFileSync(pkgPath, JSON.stringify(pkg, null, 2) + '\n');
-    s.stop(`Project "${packageName}" created in ${targetDir}`);
-    let pm = detectPackageManager();
-    if (!pm && interactive) {
-        pm = exitIfCancelled(await p.select({
-            message: 'Which package manager do you want to use?',
-            options: PACKAGE_MANAGERS.map(value => ({ value, label: value })),
-            initialValue: 'pnpm',
-        }));
-    }
-    pm ??= 'pnpm';
-    let shouldInstall = !noInstall;
-    if (shouldInstall && interactive) {
-        shouldInstall = exitIfCancelled(await p.confirm({ message: `Install dependencies with ${pm}?` }));
-    }
-    let installed = false;
-    if (shouldInstall) {
-        try {
-            await install(pm, targetDir);
-            installed = true;
-        }
-        catch {
-            // Error already shown by the task log
-        }
-    }
-    const steps = [
-        ...(isCurrentDir ? [] : [`cd ${projectDir}`]),
-        ...(installed ? [] : [`${pm} install`]),
-        `${pm === 'npm' ? 'npm run' : pm} dev`,
-    ];
-    p.note(steps.join('\n'), 'Next steps');
-    p.outro('Happy dev!');
+else {
+    spinner.error(`The dependencies could not be installed with ${pm}`);
+    if (result.output)
+        p.log.message(result.output);
 }
-main().catch(err => {
-    p.log.error(err instanceof Error ? err.message : String(err));
-    process.exit(1);
-});
+const cd = relative(process.cwd(), resolve(dir));
+const steps = [
+    ...(cd ? [`cd ${cd.includes(' ') ? `"${cd}"` : cd}`] : []),
+    ...(result.ok ? [] : [`${pm} install`]),
+    'Copy .env.example to .env and fill in BOT_TOKEN and DEV_GUILD_ID',
+    runScript(pm, 'dev'),
+];
+p.note(steps.join('\n'), 'Next steps');
+p.outro('Happy building!');

package/dist/node-version.js

@@ -0,0 +1,13 @@
+/** The oldest Node.js a ChapterJS bot runs on, as `engines` says. */
+export const MINIMUM_NODE = 24;
+/**
+ * What to tell the person when this Node.js is older than ChapterJS needs,
+ * or `null` when it is recent enough: refused before creating anything,
+ * since the bot could not run.
+ */
+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.`;
+}

package/dist/package-manager.js

@@ -0,0 +1,59 @@
+import { spawn } from 'node:child_process';
+import { tmpdir } from 'node:os';
+/** In menu order: pnpm, the one ChapterJS itself uses, comes first. */
+export const packageManagers = ['pnpm', 'npm', 'yarn', 'bun'];
+/**
+ * The package manager that launched `create chapter`, read from the user agent
+ * it sets (e.g. `pnpm/11.0.0 npm/? node/v24.0.0 darwin arm64`).
+ */
+export function detectPackageManager() {
+    const name = process.env.npm_config_user_agent?.split('/')[0];
+    return packageManagers.find(pm => pm === name) ?? 'pnpm';
+}
+/**
+ * The installed version of each package manager, or `undefined` when it isn't
+ * installed. All are checked at once, so this takes as long as the slowest one.
+ */
+export async function installedVersions() {
+    const versions = await Promise.all(packageManagers.map(pm => new Promise(resolve => {
+        let output = '';
+        const child = spawn(pm, ['--version'], {
+            // Outside the current folder: a `packageManager` field in a parent
+            // package.json makes corepack refuse to run any other manager.
+            cwd: tmpdir(),
+            // Corepack must never stop to ask before downloading a manager.
+            env: { ...process.env, COREPACK_ENABLE_DOWNLOAD_PROMPT: '0' },
+            shell: process.platform === 'win32',
+            stdio: ['ignore', 'pipe', 'ignore'],
+        });
+        child.stdout.on('data', (chunk) => (output += chunk));
+        child.on('error', () => resolve(undefined));
+        child.on('close', code => resolve(code === 0 ? output.trim() || undefined : undefined));
+    })));
+    return Object.fromEntries(packageManagers.map((pm, i) => [pm, versions[i]]));
+}
+/** The command that runs a package.json script, e.g. `pnpm dev` or `npm run dev`. */
+export function runScript(pm, script) {
+    return pm === 'npm' ? `npm run ${script}` : `${pm} ${script}`;
+}
+/** Runs `<pm> install` in `cwd`, capturing the output instead of printing it. */
+export function install(pm, cwd) {
+    return new Promise(resolve => {
+        let output = '';
+        const child = spawn(pm, ['install'], {
+            cwd,
+            // Package managers are `.cmd` shims on Windows, which only a shell can run.
+            shell: process.platform === 'win32',
+            stdio: ['ignore', 'pipe', 'pipe'],
+        });
+        child.stdout.on('data', (chunk) => (output += chunk));
+        child.stderr.on('data', (chunk) => (output += chunk));
+        child.on('error', (error) => {
+            const reason = error.code === 'ENOENT'
+                ? `${pm} is not installed on this computer.`
+                : error.message;
+            resolve({ ok: false, output: reason });
+        });
+        child.on('close', code => resolve({ ok: code === 0, output: output.trim() }));
+    });
+}

package/dist/project.js

@@ -0,0 +1,82 @@
+import { existsSync, readdirSync, statSync } from 'node:fs';
+import { cp, mkdir, readFile, rename, writeFile } from 'node:fs/promises';
+import { basename, join, resolve } from 'node:path';
+import { templatesDir } from './templates.js';
+/** Files that don't make a folder "used": a project can still be created there. */
+const ignoredFiles = new Set([
+    '.git',
+    '.DS_Store',
+    'Thumbs.db',
+    '.idea',
+    '.vscode',
+]);
+/** Returns why `input` can't hold a new project, or `undefined` when it can. */
+export function validateTargetDir(input) {
+    const dir = input?.trim();
+    if (!dir)
+        return 'Type a folder name, or . to use the current folder.';
+    const path = resolve(dir);
+    if (!existsSync(path))
+        return undefined;
+    if (!statSync(path).isDirectory())
+        return `${dir} is a file, not a folder. Pick another name.`;
+    const used = readdirSync(path).some(file => !ignoredFiles.has(file));
+    if (used) {
+        return path === process.cwd()
+            ? 'The current folder is not empty. Type a name to create a new folder instead.'
+            : `The folder ${dir} is not empty. Pick another name.`;
+    }
+    return undefined;
+}
+/** A valid npm package name from a folder name, e.g. `Mon Bot Été` → `mon-bot-ete`. */
+export function toPackageName(dir) {
+    const name = basename(resolve(dir))
+        // `é` → `e`: split letters from their accents, then drop the accents.
+        .normalize('NFD')
+        .replace(/\p{Diacritic}/gu, '')
+        .toLowerCase()
+        .replace(/[^a-z0-9-~._]+/g, '-')
+        .replace(/-{2,}/g, '-')
+        // npm names can't start with `.` or `_`, and 214 characters is the maximum.
+        .replace(/^[-._]+/, '')
+        .slice(0, 214)
+        .replace(/[-.]+$/, '');
+    return name || 'chapter-bot';
+}
+/**
+ * What pnpm needs to install a project whose framework comes with esbuild
+ * (which `chapterjs build` compiles the bot with). esbuild has an install
+ * script it does not need; pnpm refuses to go on until the project says whether that
+ * script may run. It may not: no script of a dependency runs.
+ * `allowBuilds` is read by pnpm 11, `ignoredBuiltDependencies` by pnpm 10.
+ */
+export const PNPM_WORKSPACE = `# esbuild works without its install script: pnpm is told not to run it.
+allowBuilds:
+  esbuild: false
+ignoredBuiltDependencies:
+  - esbuild
+`;
+/** Copies the template into `dir` and names the project after its folder. */
+export async function createProject({ dir, template, chapterjsVersion, packageManager, templatesRoot = templatesDir, }) {
+    const root = resolve(dir);
+    await cp(join(templatesRoot, template), root, { recursive: true });
+    // Where the files the bot sends go (`asset()`): git and npm keep no empty
+    // folder, so no template can ship it; every project gets it here.
+    await mkdir(join(root, 'public'), { recursive: true });
+    // npm strips `.gitignore` from published packages, so templates ship it as `_gitignore`.
+    const gitignore = join(root, '_gitignore');
+    if (existsSync(gitignore))
+        await rename(gitignore, join(root, '.gitignore'));
+    const pkgPath = join(root, 'package.json');
+    const pkg = JSON.parse(await readFile(pkgPath, 'utf8'));
+    pkg.name = toPackageName(dir);
+    // The template's description is for the menu, not for the user's bot.
+    delete pkg.description;
+    pkg.dependencies = { ...pkg.dependencies, chapterjs: chapterjsVersion };
+    await writeFile(pkgPath, JSON.stringify(pkg, null, 2) + '\n');
+    // Only for the package manager that reads it: nothing to explain to the
+    // others.
+    if (packageManager === 'pnpm') {
+        await writeFile(join(root, 'pnpm-workspace.yaml'), PNPM_WORKSPACE);
+    }
+}

package/dist/templates.js

@@ -0,0 +1,31 @@
+import { existsSync } from 'node:fs';
+import { readdir, readFile } from 'node:fs/promises';
+import { fileURLToPath } from 'node:url';
+import { join } from 'node:path';
+/** `templates/` ships next to `dist/` in the published package. */
+export const templatesDir = fileURLToPath(new URL('../templates/', import.meta.url));
+/**
+ * Every folder of `templates/` with a package.json is a template: adding one
+ * needs no code change.
+ */
+export async function listTemplates(dir = templatesDir) {
+    const entries = await readdir(dir, { withFileTypes: true });
+    const templates = await Promise.all(entries
+        .filter(entry => entry.isDirectory())
+        .map(async (entry) => {
+        const pkgPath = join(dir, entry.name, 'package.json');
+        if (!existsSync(pkgPath))
+            return undefined;
+        const pkg = JSON.parse(await readFile(pkgPath, 'utf8'));
+        const description = typeof pkg.description === 'string' ? pkg.description : undefined;
+        return { name: entry.name, description };
+    }));
+    // `default` first, so it is the preselected choice.
+    return templates
+        .filter(template => template !== undefined)
+        .sort((a, b) => a.name === 'default'
+        ? -1
+        : b.name === 'default'
+            ? 1
+            : a.name.localeCompare(b.name));
+}

package/package.json

@@ -1,24 +1,41 @@
 {
   "name": "create-chapter",
-  "version": "0.1.2",
+  "version": "0.2.0",
   "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/chapterjs/chapterjs.git",
+    "directory": "packages/create-chapter"
+  },
+  "homepage": "https://chapterjs.dev",
+  "bugs": "https://github.com/chapterjs/chapterjs/issues",
   "type": "module",
   "bin": {
     "create-chapter": "./dist/index.js"
   },
   "files": [
     "dist",
-    "template"
+    "templates"
   ],
   "devDependencies": {
+    "@chapterjs/test-utils": "0.0.0",
     "@types/node": "^24.0.0",
-    "typescript": "^7.0.2"
+    "@vitest/coverage-v8": "^5.0.3",
+    "typescript": "^7.0.2",
+    "vitest": "^5.0.3"
   },
   "dependencies": {
     "@clack/prompts": "^1.8.1"
   },
+  "engines": {
+    "node": ">=24"
+  },
   "scripts": {
     "build": "tsc",
-    "dev": "tsc --watch"
+    "dev": "tsc --watch",
+    "check-types": "tsc --noEmit && tsc -p test",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "coverage": "vitest run --coverage"
   }
 }

package/templates/default/.env.example

@@ -0,0 +1,4 @@
+# Your bot token: https://discord.com/developers/applications → your app → Bot → Reset Token
+BOT_TOKEN=
+# The ID of the server used by `chapterjs dev` (right-click the server → Copy Server ID)
+DEV_GUILD_ID=

package/{template → templates/default}/_gitignore

@@ -1,3 +1,4 @@
 node_modules
+dist
 .env
-.DS_Store
+.chapterjs

package/templates/default/package.json

@@ -0,0 +1,23 @@
+{
+  "name": "chapter-bot",
+  "description": "A minimal bot, ready to grow",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "dev": "chapterjs dev",
+    "start": "chapterjs start",
+    "build": "chapterjs build",
+    "typecheck": "tsc -b",
+    "postinstall": "chapterjs sync"
+  },
+  "dependencies": {
+    "chapterjs": "latest"
+  },
+  "devDependencies": {
+    "@types/node": "^24.0.0",
+    "typescript": "^7.0.2"
+  },
+  "engines": {
+    "node": ">=24"
+  }
+}

package/templates/default/src/(moderation)/ban.ts

@@ -0,0 +1,49 @@
+import { button, command } from 'chapterjs';
+import { canPunish } from './checks';
+
+// A folder is only a folder: `(moderation)` groups what moderation needs,
+// and the framework reads what these files export, wherever they are.
+// /ban asks for a confirmation, then bans. The command and its button live
+// in the same file: the button is named by its export (`confirmBan`), and
+// `who: 'author'` keeps it for the person who used the command.
+export default command({
+  name: 'ban',
+  permissions: ['BanMembers'],
+  ephemeral: true,
+  options: {
+    target: { type: 'user', required: true },
+    reason: { type: 'string' },
+    days: { type: 'integer', min: 0, max: 7 },
+  },
+  async run({ interaction, options, member, guild, t }) {
+    const target = guild.members.get(options.target.id);
+    if (target && !canPunish(member, target)) {
+      await interaction.reply(t('cannotPunish', { user: target.displayName }));
+      return;
+    }
+    await interaction.reply({
+      content: t('ban.confirm', { user: options.target.username }),
+      components: [
+        confirmBan({
+          userId: options.target.id,
+          days: options.days ?? 0,
+          reason: options.reason ?? '',
+        }),
+      ],
+    });
+  },
+});
+
+export const confirmBan = button({
+  label: ({ t }) => t('ban.yes'),
+  style: 'danger',
+  who: 'author',
+  data: { userId: 'string', days: 'number', reason: 'string' },
+  async run({ interaction, data, guild, user, t }) {
+    await guild.ban(data.userId, {
+      reason: data.reason || t('ban.defaultReason', { by: user.username }),
+      deleteMessageSeconds: data.days * 86_400,
+    });
+    await interaction.update({ content: t('ban.done'), components: [] });
+  },
+});

package/templates/default/src/(moderation)/checks.ts

@@ -0,0 +1,19 @@
+import type { GuildMember } from 'chapterjs';
+
+// Shared code: this file declares nothing, the commands import it. Nothing
+// survives a restart: a real bot keeps its warnings in a database.
+export function canPunish(by: GuildMember, target: GuildMember): boolean {
+  return by.highestRole.position > target.highestRole.position;
+}
+
+const warnings = new Map<string, number>();
+
+export function addWarning(userId: string): number {
+  const count = (warnings.get(userId) ?? 0) + 1;
+  warnings.set(userId, count);
+  return count;
+}
+
+export function warningsOf(userId: string): number {
+  return warnings.get(userId) ?? 0;
+}

package/templates/default/src/(moderation)/kick.ts

@@ -0,0 +1,27 @@
+import { command } from 'chapterjs';
+
+// /kick: the texts come from the language files, like every command here.
+import { canPunish } from './checks';
+
+export default command({
+  name: 'kick',
+  permissions: ['KickMembers'],
+  ephemeral: true,
+  options: {
+    target: { type: 'user', required: true },
+    reason: { type: 'string' },
+  },
+  async run({ interaction, options, member, guild, t }) {
+    const target = guild.members.get(options.target.id);
+    if (!target) {
+      await interaction.reply(t('notHere', { user: options.target.username }));
+      return;
+    }
+    if (!canPunish(member, target)) {
+      await interaction.reply(t('cannotPunish', { user: target.displayName }));
+      return;
+    }
+    await target.kick(options.reason);
+    await interaction.reply(t('kick.done', { user: target.displayName }));
+  },
+});

package/templates/default/src/(moderation)/messages.ts

@@ -0,0 +1,81 @@
+import { language } from 'chapterjs';
+
+// A language may be declared in several places: these texts are added to the
+// en-US and fr of src/messages/, next to the commands that use them. What
+// says `default: true` there decides for the whole language.
+export const en = language({
+  locale: 'en-US',
+  texts: {
+    cannotPunish: 'You can not act on {user}: their role is above yours.',
+    notHere: '{user} is not in this server.',
+    'ban.confirm': 'Ban {user}?',
+    'ban.yes': 'Ban',
+    'ban.defaultReason': 'Banned by {by}',
+    'ban.done': 'Banned.',
+    'kick.done': '{user} was kicked.',
+    'warn.added': '{user} now has {count} warning(s).',
+    // A plural: one form per quantity, picked by `count`.
+    'warn.count': {
+      one: '{user} has {count} warning.',
+      other: '{user} has {count} warnings.',
+    },
+  },
+  // What Discord shows of these commands: their descriptions live here too.
+  commands: {
+    ban: {
+      description: 'Bans a member, after a confirmation',
+      options: {
+        target: { description: 'Who to ban' },
+        reason: { description: 'Why' },
+        days: { description: 'Days of messages to delete' },
+      },
+    },
+    kick: {
+      description: 'Kicks a member',
+      options: {
+        target: { description: 'Who to kick' },
+        reason: { description: 'Why' },
+      },
+    },
+    'warn add': {
+      description: 'Warns a member',
+      options: {
+        target: { description: 'Who to warn' },
+        reason: { description: 'Why' },
+      },
+    },
+    'warn list': {
+      description: 'Counts the warnings of a member',
+      options: { target: { description: 'Whose warnings' } },
+    },
+  },
+});
+
+export const fr = language({
+  locale: 'fr',
+  texts: {
+    cannotPunish:
+      'Vous ne pouvez pas agir sur {user} : son rôle est au-dessus du vôtre.',
+    notHere: '{user} n’est pas sur ce serveur.',
+    'ban.confirm': 'Bannir {user} ?',
+    'ban.yes': 'Bannir',
+    'ban.defaultReason': 'Banni par {by}',
+    'ban.done': 'Banni.',
+    'kick.done': '{user} a été expulsé.',
+    'warn.added': '{user} a maintenant {count} avertissement(s).',
+    'warn.count': {
+      one: '{user} a {count} avertissement.',
+      other: '{user} a {count} avertissements.',
+    },
+  },
+  commands: {
+    // A command can be renamed in a language too: /bannir for French users.
+    ban: {
+      name: 'bannir',
+      description: 'Bannit un membre, après confirmation',
+    },
+    kick: { name: 'expulser', description: 'Expulse un membre' },
+    'warn add': { description: 'Avertit un membre' },
+    'warn list': { description: 'Compte les avertissements d’un membre' },
+  },
+});

package/templates/default/src/(moderation)/warn.ts

@@ -0,0 +1,42 @@
+import { command, event } from 'chapterjs';
+import { addWarning, warningsOf } from './checks';
+
+// Two subcommands in one file: /warn add and /warn list. A subcommand is a
+// matter of `name`, not of folder.
+export const add = command({
+  name: 'warn add',
+  permissions: ['ModerateMembers'],
+  options: {
+    target: { type: 'user', required: true },
+    reason: { type: 'string', required: true },
+  },
+  async run({ interaction, options, t }) {
+    const count = addWarning(options.target.id);
+    await interaction.reply(
+      t('warn.added', { user: options.target.username, count })
+    );
+  },
+});
+
+export const list = command({
+  name: 'warn list',
+  permissions: ['ModerateMembers'],
+  ephemeral: true,
+  options: { target: { type: 'user', required: true } },
+  async run({ interaction, options, t }) {
+    await interaction.reply(
+      t('warn.count', {
+        user: options.target.username,
+        count: warningsOf(options.target.id),
+      })
+    );
+  },
+});
+
+// The event that goes with moderation, next to the commands it follows.
+export const logged = event({
+  name: 'banAdd',
+  run({ user, guild }) {
+    console.log(`${user.username} was banned from ${guild.name}`);
+  },
+});

package/templates/default/src/commands/hello.ts

@@ -0,0 +1,23 @@
+import { asset, command } from 'chapterjs';
+
+// /hello joins your voice channel and plays public/hello.ogg. An Opus file
+// (.ogg, .webm) plays as it is; an .mp3 or a link needs ffmpeg installed.
+export default command({
+  name: 'hello',
+  async run({ interaction, member, t }) {
+    const channel = member.voiceChannel;
+    if (!channel) {
+      await interaction.reply({ content: t('joinVoice'), ephemeral: true });
+      return;
+    }
+    // Answer first: a command has 3 seconds, joining takes a moment.
+    await interaction.reply(t('hello', { channel: channel.name }));
+    const voice = await channel.join();
+    // Whatever happens while it plays, the bot leaves after.
+    try {
+      await voice.play(asset('hello.ogg'));
+    } finally {
+      await voice.leave();
+    }
+  },
+});

package/templates/default/src/commands/ping.ts

@@ -0,0 +1,55 @@
+import { button, command } from 'chapterjs';
+
+// A command is declared with command() and exported: `name` is what people
+// type after the /. Where the file is and what it is called are up to you:
+// this one could live anywhere in src/.
+export default command({
+  name: 'ping',
+  // Only the person sees the answer, so `t` speaks their language.
+  ephemeral: true,
+  async run({ interaction, t }) {
+    // The button below, with the data it carries, and a text of
+    // src/messages/ in the language of who will read the answer.
+    await interaction.reply({
+      content: t('pong'),
+      components: [again({ count: 1 })],
+    });
+  },
+});
+
+// A button is declared with button() and exported: the name of the export
+// (here `again`) is what tells which one was clicked, you never write an
+// id. `data` is what the button carries from one click to the next.
+export const again = button({
+  label: 'Again',
+  data: { count: 'number' },
+  async run({ interaction, data, t }) {
+    const count = data.count + 1;
+    // Changes the message the button is on, instead of sending a new one.
+    await interaction.update({
+      content: t('again', { count }),
+      components: [again({ count })],
+    });
+  },
+});
+
+// A command can ask for options, typed for you in `run`, suggest values
+// while the person types, and make each person wait between two uses:
+//
+// export const hello = command({
+//   name: 'hello',
+//   description: 'Says hello to someone',
+//   cooldown: '10s',
+//   options: {
+//     who: { type: 'user', description: 'Who to greet', required: true },
+//     greeting: { type: 'string', description: 'How to greet' },
+//   },
+//   autocomplete: {
+//     // Called while the person types in "greeting", with what they typed.
+//     greeting: ({ value }) =>
+//       ['Hello', 'Hi', 'Hey'].filter(word => word.startsWith(value)),
+//   },
+//   async run({ interaction, options }) {
+//     await interaction.reply(`${options.greeting ?? 'Hello'} ${options.who}!`);
+//   },
+// });

package/templates/default/src/commands/play.ts

@@ -0,0 +1,41 @@
+import { command } from 'chapterjs';
+
+// /play plays a song in your voice channel: a file you send with the
+// command, or a link to an audio file or a stream. play() takes both.
+export default command({
+  name: 'play',
+  options: {
+    file: { type: 'attachment' },
+    url: { type: 'string' },
+  },
+  async run({ interaction, member, options, t }) {
+    const { file, url } = options;
+    const song = file ?? url;
+    if (
+      !song ||
+      (file && !file.contentType?.startsWith('audio/')) ||
+      (url && !/^https?:\/\//.test(url))
+    ) {
+      await interaction.reply({ content: t('nothingToPlay'), ephemeral: true });
+      return;
+    }
+    const channel = member.voiceChannel;
+    if (!channel) {
+      await interaction.reply({ content: t('joinVoice'), ephemeral: true });
+      return;
+    }
+    const name = file?.filename ?? url ?? '';
+    await interaction.reply(
+      t('playing', { song: name, channel: channel.name })
+    );
+    // Joining the channel the bot is already in changes nothing, and a new
+    // play() replaces what was playing.
+    const voice = await channel.join();
+    // Whatever happens while it plays, the bot leaves after.
+    try {
+      await voice.play(song);
+    } finally {
+      await voice.leave();
+    }
+  },
+});

package/templates/default/src/events/ready.ts

@@ -0,0 +1,34 @@
+import { event } from 'chapterjs';
+
+// An event is declared with event() and exported: `name` is the event, and
+// it types what `run` receives. This one runs once, when your bot is
+// connected. A file may declare several events, commands or buttons.
+export default event({
+  name: 'ready',
+  run({ user, guilds }) {
+    console.log(`${user.username} is online in ${guilds.size} server(s)`);
+  },
+});
+
+// Something to do by itself, every so often or at given times, is a task:
+// the name of its export is the name of the task.
+//
+// import { task } from 'chapterjs';
+//
+// export const report = task({
+//   cron: '0 9 * * 1', // every Monday at 9:00
+//   async run({ guilds }) {
+//     console.log(`A new week in ${guilds.size} server(s)`);
+//   },
+// });
+//
+// To react to something else, declare another event. For example, one that
+// answers "Pong!" to "!ping" (reading messages needs the Message Content
+// intent: `chapterjs dev` tells you how to enable it):
+//
+// export const pong = event({
+//   name: 'messageCreate',
+//   async run({ message }) {
+//     if (message.content === '!ping') await message.reply('Pong!');
+//   },
+// });

package/templates/default/src/events/wave.ts

@@ -0,0 +1,14 @@
+import { event } from 'chapterjs';
+
+// Runs every time someone adds a reaction to a message of your server.
+// Reactions of bots, yours included, are left out: when yours waves back
+// below, this does not run again. Other events work the same way:
+// voiceJoin, pollVoteAdd, banAdd... (see the list of events in the docs).
+export default event({
+  name: 'reactionAdd',
+  async run({ emoji, channel, messageId }) {
+    if (emoji.name !== '👋') return;
+    const message = await channel.fetchMessage(messageId);
+    await message.react('👋');
+  },
+});

package/templates/default/src/messages/en-US.ts

@@ -0,0 +1,36 @@
+import { language } from 'chapterjs';
+
+// A language is declared with language(): `locale` says which one. Each
+// function of your project receives `t`, which picks the language of who
+// will read the message: t('pong'), t('again', { count }).
+export default language({
+  locale: 'en-US',
+  // The language used when the one of a person or of a server is not here.
+  default: true,
+  texts: {
+    pong: 'Pong! in en-US',
+    again: 'Pong in en-US ! ×{count}',
+    joinVoice: 'Join a voice channel first, then ask again.',
+    hello: 'Coming to {channel}!',
+    nothingToPlay:
+      'Send an audio file (.mp3, .ogg...) or a link starting with https://.',
+    playing: 'Playing {song} in {channel}.',
+  },
+  // What Discord shows of each command, by its name: its description, and
+  // the ones of its options. A command described here has none in its file.
+  commands: {
+    ping: {
+      description: 'Replies with Pong!',
+    },
+    hello: {
+      description: 'Says hello in your voice channel',
+    },
+    play: {
+      description: 'Plays a song in your voice channel',
+      options: {
+        file: { description: 'A song to play' },
+        url: { description: 'Or the link of a song or a stream' },
+      },
+    },
+  },
+});

package/templates/default/src/messages/fr.ts

@@ -0,0 +1,37 @@
+import { language } from 'chapterjs';
+
+// Every language has the texts of the default one, with the same
+// {placeholders}: a missing one is reported when the file loads.
+export default language({
+  locale: 'fr',
+  texts: {
+    pong: 'Pong! en fr',
+    again: 'Pong en fr ! ×{count}',
+    joinVoice: 'Rejoignez d’abord un salon vocal, puis redemandez.',
+    hello: 'J’arrive dans {channel} !',
+    nothingToPlay:
+      'Envoyez un fichier audio (.mp3, .ogg...) ou un lien qui commence par https://.',
+    playing: 'Lecture de {song} dans {channel}.',
+  },
+  // What the bot answers by itself can be translated too, phrase by phrase:
+  //
+  // framework: {
+  //   command: 'commande',
+  //   failed: "Quelque chose s'est mal passé avec cette {what}.",
+  // },
+  commands: {
+    ping: {
+      description: 'Répond avec Pong !',
+    },
+    hello: {
+      description: 'Dit bonjour dans votre salon vocal',
+    },
+    play: {
+      description: 'Joue une musique dans votre salon vocal',
+      options: {
+        file: { description: 'Une musique à jouer' },
+        url: { description: 'Ou le lien d’une musique ou d’un flux' },
+      },
+    },
+  },
+});

package/templates/default/src/presence.ts

@@ -0,0 +1,8 @@
+import { presence } from 'chapterjs';
+
+// What your bot shows under its name: its status, and what it is doing.
+// Save this file and chapterjs dev changes it at once.
+export default presence({
+  status: 'online',
+  activity: { type: 'playing', name: 'with ChapterJS' },
+});

package/templates/default/tsconfig.json

@@ -0,0 +1,20 @@
+{
+  "compilerOptions": {
+    "target": "ESNext",
+    "module": "Preserve",
+    "moduleResolution": "Bundler",
+    "allowImportingTsExtensions": true,
+    "erasableSyntaxOnly": true,
+    "verbatimModuleSyntax": true,
+    "noEmit": true,
+    "strict": true,
+    "skipLibCheck": true,
+    "types": ["node"]
+  },
+  "files": [],
+  "references": [
+    {
+      "path": "./.chapterjs"
+    }
+  ]
+}

package/template/.env.example

@@ -1,5 +0,0 @@
-# Required — Discord Developer Portal > your application > Bot > Token
-BOT_TOKEN=<YOUR_BOT_TOKEN>
-
-# Required — Discord > right-click your dev server > Copy Server ID
-DEV_GUILD_ID=<YOUR_DEV_GUILD_ID>

package/template/package.json

@@ -1,17 +0,0 @@
-{
-  "name": "my-chapter-app",
-  "version": "0.1.0",
-  "private": true,
-  "type": "module",
-  "scripts": {
-    "dev": "chapterjs dev",
-    "build": "chapterjs build"
-  },
-  "dependencies": {
-    "chapterjs": "workspace:*"
-  },
-  "devDependencies": {
-    "@types/node": "^24.0.0",
-    "typescript": "^7.0.2"
-  }
-}

package/template/src/components/buttons/sayHi.ts

@@ -1,28 +0,0 @@
-import { defineButton } from 'chapterjs';
-
-// A button that handles its own clicks: they don't reach interactionCreate.
-// Its custom_id is generated from this file's path. Send it with
-// `components: [SayHi]`, or change it where it's used:
-// `new SayHi({ label: 'Hello', style: 'success' })`.
-export default defineButton({
-  label: 'Say hi',
-  emoji: '👋',
-  async handler({ interaction, user }) {
-    await interaction.reply({
-      content: `Hi ${user}! Only you can see this message.`,
-      ephemeral: true,
-    });
-  },
-});
-
-// Buttons can carry data, given back to the handler:
-//
-// export default defineButton<{ roleId: string }>({
-//   label: 'Get the role',
-//   async handler({ interaction, member, data }) {
-//     await member?.addRole(data.roleId);
-//     await interaction.reply({ content: 'Done!', ephemeral: true });
-//   },
-// });
-//
-// message.reply({ components: [new GetRole({ data: { roleId: '…' } })] });

package/template/src/events/interactionCreate.ts

@@ -1,11 +0,0 @@
-import { defineEvent } from 'chapterjs';
-
-// Slash commands, and components whose custom_id you wrote yourself. Clicks
-// on components of src/components/ go to their own handler instead.
-// Answer within 3 seconds, or call `interaction.defer()` first and
-// `interaction.editReply()` later.
-export default defineEvent(async ({ interaction }) => {
-  if (interaction.commandName === 'ping') {
-    await interaction.reply({ content: 'Pong!', ephemeral: true });
-  }
-});

package/template/src/events/messageCreate.ts

@@ -1,25 +0,0 @@
-import { defineEvent } from 'chapterjs';
-import SayHi from '../components/buttons/sayHi.ts';
-
-// Mention the bot: it reacts and replies with a button (src/components/buttons/sayHi.ts).
-// Messages from bots are ignored, unless you add allowBots: true.
-export default defineEvent(async ({ message, client }) => {
-  if (!message.mentions.some(user => user.id === client.user?.id)) return;
-
-  await message.react('👋');
-  await message.reply({
-    content: `Hi ${message.author.displayName}!`,
-    mention: false,
-    components: [SayHi],
-  });
-});
-
-// Without the privileged MessageContent intent, `message.content` is empty
-// except in DMs and messages mentioning the bot. To read every message:
-//
-// export default defineEvent({
-//   intents: ['MessageContent'],
-//   async handler({ message }) {
-//     if (message.content === '!ping') await message.reply('Pong!');
-//   },
-// });

package/template/src/events/messageDelete.ts

@@ -1,6 +0,0 @@
-import { defineEvent } from 'chapterjs';
-
-// Discord only sends ids: the deleted message's content is gone.
-export default defineEvent(({ messageId, channel }) => {
-  console.log(`Message ${messageId} deleted in ${channel}`);
-});

package/template/src/events/messageReactionAdd.ts

@@ -1,12 +0,0 @@
-import { defineEvent } from 'chapterjs';
-
-export default defineEvent(async ({ reaction, client }) => {
-  if (reaction.userId === client.user?.id) return;
-  const name = reaction.member?.displayName ?? reaction.userId;
-  console.log(`${name} reacted ${reaction} in ${reaction.channel}`);
-
-  // Reaction roles: give a role when reacting on a given message
-  // if (reaction.messageId === ROLES_MESSAGE_ID && reaction.emoji.name === '🎮') {
-  //   await reaction.member?.addRole(GAMER_ROLE_ID);
-  // }
-});

package/template/src/events/ready.ts

@@ -1,24 +0,0 @@
-import { defineEvent } from 'chapterjs';
-
-// Each file in src/events/ handles the Discord event it is named after
-// (messageCreate.ts, guildMemberAdd.ts…), reloaded on save. Several handlers
-// for one event go in a folder: src/events/messageCreate/*.ts. Files and
-// folders starting with _ are ignored, for shared code.
-// The gateway intents each event needs are requested automatically.
-//
-// Handlers receive what the event is about: { user, guilds } here,
-// { message, channel } in messageCreate, { interaction } in
-// interactionCreate… plus `client` and the raw `data` sent by Discord.
-export default defineEvent(({ user, guilds }) => {
-  console.log(`${user.displayName} is ready in ${guilds.length} server(s)`);
-});
-
-// Some events need a privileged intent, enabled in the Developer Portal
-// (Bot > Privileged Gateway Intents), otherwise the bot can't connect:
-//
-// src/events/guildMemberAdd.ts — GuildMembers intent:
-//
-// export default defineEvent(async ({ member, client }) => {
-//   await member.addRole(MEMBER_ROLE_ID, 'New member');
-//   await client.channel(WELCOME_CHANNEL_ID).send(`Welcome ${member}! 👋`);
-// });

package/template/src/presence.ts

@@ -1,35 +0,0 @@
-import { definePresence } from 'chapterjs';
-
-// Status and activity shown on the bot's profile, reloaded on save.
-export default definePresence({
-  status: 'online', // 'online' | 'idle' | 'dnd' | 'invisible'
-  // 'playing' | 'listening' | 'watching' | 'competing' | 'streaming' (+ url),
-  // or a plain string for a custom status: activity: 'Coding 🚀'
-  activity: { type: 'playing', name: 'with ChapterJS' },
-});
-
-// Rotation, each step shown for its own duration (minimum 5s):
-//
-// export default definePresence([
-//   { duration: 5_000, status: 'online', activity: 'Hello everyone 👋' },
-//   { duration: 10_000, status: 'dnd', activity: { type: 'watching', name: 'the server' } },
-// ]);
-
-// Dynamic presence, e.g. a rotation stored in a database. It is reloaded
-// after each full rotation, or right away when `watch` calls `refresh`
-// (you can also call `refreshPresence()` from anywhere in your bot):
-//
-// export default definePresence({
-//   async presence({ client }) {
-//     const rows = await db.presence.findMany();
-//     return rows.map((row) => ({
-//       duration: row.duration,
-//       status: row.status, // 'online' | 'idle' | 'dnd' | 'invisible'
-//       activity: row.message,
-//     }));
-//   },
-//   watch(refresh) {
-//     const unsubscribe = db.onPresenceChange(refresh);
-//     return unsubscribe;
-//   },
-// });

package/template/tsconfig.json

@@ -1,15 +0,0 @@
-{
-  "compilerOptions": {
-    "target": "ES2022",
-    "module": "NodeNext",
-    "moduleResolution": "NodeNext",
-    "strict": true,
-    "outDir": "dist",
-    "rootDir": "src",
-    "skipLibCheck": true,
-    "rewriteRelativeImportExtensions": true,
-    "erasableSyntaxOnly": true,
-    "types": ["node"]
-  },
-  "include": ["src"]
-}