create-chapterjs 0.4.0 → 0.5.0

package/README.md

@@ -24,7 +24,7 @@ bun create chapterjs my-bot
 
 - **The folder**, when it is not given: `.` is the current folder, which must be new or empty.
 - **The package manager**, among those installed on your machine: the one you ran the command with is preselected.
-- **A template**: `default` is one file, the `ready` event, and the [tutorial](https://www.chapterjs.org/tutorial) starts from it. The others are complete bots to start from or to read: `tickets` (support tickets in private threads), `music` (a player with a queue and buttons), `community` (welcome cards, roles people pick, weekly stats) and `moderation` (timeouts, purge, slowmode, lock, and a log of every action).
+- **A template**: `default` is one file, the `ready` event, and the [tutorial](https://www.chapterjs.org/tutorial) starts from it. The others are complete bots to start from or to read: `tickets` (support tickets in private threads), `music` (a player with a queue and buttons), `community` (welcome cards, roles people pick, weekly stats), `moderation` (timeouts, purge, slowmode, lock, and a log of every action) and `games` (a quiz against the clock, duels with buttons, menu commands, a presence that takes turns).
 
 A question with only one possible answer is not asked: its answer is shown with `ℹ`. Node 24 or later is needed, and the command says so at once when it is older.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-chapterjs",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "Creates a ChapterJS Discord bot: pnpm create chapterjs",
   "keywords": [
     "discord",

package/templates/games/.env.example

@@ -0,0 +1,7 @@
+# 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=
+# Only for stores declared with storage: 'redis' (https://www.chapterjs.org/storage#in-redis)
+# REDIS_URL=redis://localhost:6379
+# REDIS_PASSWORD=

package/templates/games/_gitignore

@@ -0,0 +1,5 @@
+node_modules
+dist
+.env
+.chapterjs
+data

package/templates/games/package.json

@@ -0,0 +1,24 @@
+{
+  "name": "games-bot",
+  "description": "A quiz against the clock, duels with buttons, menu commands and a presence that takes turns",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "dev": "chapterjs dev",
+    "start": "chapterjs start",
+    "build": "chapterjs build",
+    "test": "chapterjs test",
+    "typecheck": "tsc -b",
+    "postinstall": "chapterjs sync"
+  },
+  "dependencies": {
+    "chapterjs": "latest"
+  },
+  "devDependencies": {
+    "@types/node": "^24.0.0",
+    "typescript": "^7.0.2"
+  },
+  "engines": {
+    "node": ">=24"
+  }
+}

package/templates/games/src/duel/duel.ts

@@ -0,0 +1,84 @@
+import { button, command, userMention } from 'chapterjs';
+import type { CommandInteraction, Translator, User } from 'chapterjs';
+
+// Buttons with no `run`: nothing runs them but `waitForClick()` below. Once
+// nothing waits for them, a click tells the person they are not available.
+export const accept = button({
+  label: ({ t }) => t('duelAccept'),
+  style: 'success',
+});
+export const decline = button({
+  label: ({ t }) => t('duelDecline'),
+  style: 'secondary',
+});
+
+/** A roll of a six-sided die. */
+const roll = (): number => Math.floor(Math.random() * 6) + 1;
+
+/**
+ * Challenges someone: they have a minute to accept with a button, then
+ * both roll a die. Shared by `/duel` and the menu of a message.
+ */
+async function challenge(
+  interaction: CommandInteraction,
+  t: Translator,
+  user: User,
+  opponent: User
+): Promise<void> {
+  if (opponent.id === user.id || opponent.bot) {
+    await interaction.reply({ content: t('duelNobody'), ephemeral: true });
+    return;
+  }
+  const asked = await interaction.reply({
+    content: t('duelAsk', {
+      opponent: userMention(opponent.id),
+      user: user.username,
+    }),
+    components: [accept, decline],
+  });
+  const click = await asked.waitForClick({ from: opponent, within: '1m' });
+  if (!click) {
+    await interaction.edit({
+      content: t('duelExpired', { opponent: opponent.username }),
+      components: [],
+    });
+    return;
+  }
+  if (click.is(decline)) {
+    await click.interaction.update({
+      content: t('duelDeclined', { opponent: opponent.username }),
+      components: [],
+    });
+    return;
+  }
+  const mine = roll();
+  const theirs = roll();
+  const result =
+    mine === theirs
+      ? t('duelDraw')
+      : t('duelWinner', {
+          user: mine > theirs ? user.username : opponent.username,
+        });
+  await click.interaction.update({
+    content: `${t('duelRolls', { user: user.username, mine, opponent: opponent.username, theirs })}\n${result}`,
+    components: [],
+  });
+}
+
+// `/duel @someone`.
+export const duel = command({
+  name: 'duel',
+  options: { opponent: { type: 'user', required: true } },
+  run: ({ interaction, options, user, t }) =>
+    challenge(interaction, t, user, options.opponent),
+});
+
+// The same from the menu of a message (right click, Apps): the author of
+// the message is challenged. `type: 'message'` gives `run` the message.
+export const challengeAuthor = command({
+  type: 'message',
+  name: 'Challenge to a duel',
+  locales: { fr: { name: 'Défier en duel' } },
+  run: ({ interaction, message, user, t }) =>
+    challenge(interaction, t, user, message.author),
+});

package/templates/games/src/games.test.ts

@@ -0,0 +1,67 @@
+import { scenario } from 'chapterjs/test';
+import { challengeAuthor, duel } from './duel/duel';
+import { quizScore } from './quiz/score-menu';
+import { scores, start } from './quiz/quiz';
+
+// `chapterjs test` runs these against a Discord in memory: no token, no
+// server. While a function waits (`waitForMessage()`, `waitForClick()`),
+// what the test does next is what it waits for; `bot.endWaits()` ends
+// every wait as if its time was up.
+export default [
+  scenario('the first right answer of the quiz wins a point', async bot => {
+    const alice = bot.member('alice');
+    (await bot.use(start)).says('First to answer in 30 seconds wins!');
+    await bot.say('no idea', { by: bot.member('bob') });
+    // The question is picked at random: every answer, until the bot speaks.
+    for (const answer of ['Paris', '8', 'Jupiter', '1969', 'H2O']) {
+      await bot.say(answer, { by: alice });
+      if (bot.channel('general').last!.fromBot) break;
+    }
+    bot.channel('general').last!.says('alice found it, 1 point now.');
+    (await bot.use(scores)).hasEmbed('Best players');
+    (await bot.use(quizScore, { on: alice }))
+      .isEphemeral()
+      .says('alice has 1 point, rank 1 on this server.');
+  }),
+
+  scenario('nobody finds it in time', async bot => {
+    await bot.use(start);
+    await bot.endWaits();
+    bot.channel('general').last!.says('Time is up!');
+    (await bot.use(scores)).isEphemeral().says('Nobody has a point yet');
+  }),
+
+  scenario('a duel is accepted by who was challenged only', async bot => {
+    const alice = bot.member('alice');
+    const bob = bot.member('bob');
+    const asked = await bot.use(duel, { opponent: bob }, { by: alice });
+    asked.says('challenges you to a duel').hasButton('Accept');
+    (await bot.click(asked.button('Accept'), { by: bot.member('carol') })).says(
+      'not available'
+    );
+    const fought = await bot.click(asked.button('Accept'), { by: bob });
+    fought.says('🎲 alice rolls').hasNoComponent();
+  }),
+
+  scenario('a duel can be declined, or never answered', async bot => {
+    const bob = bot.member('bob');
+    const asked = await bot.use(duel, { opponent: bob });
+    (await bot.click(asked.button('Decline'), { by: bob })).says(
+      'bob declined the duel.'
+    );
+    const again = await bot.use(duel, { opponent: bob });
+    await bot.endWaits();
+    again.says('bob did not answer: no duel.');
+  }),
+
+  scenario('the author of a message is challenged from its menu', async bot => {
+    const said = await bot.say('I am the best', { by: bot.member('dave') });
+    // The menu of a message passes its author to the duel.
+    const asked = await bot.use(challengeAuthor, { on: said });
+    const dave = bot.member('dave');
+    asked.says(`<@${dave.id}>`).says('challenges you to a duel');
+    (await bot.use(duel, { opponent: bot.someone }))
+      .isEphemeral()
+      .says('not yourself');
+  }),
+];

package/templates/games/src/messages.ts

@@ -0,0 +1,105 @@
+import { language } from 'chapterjs';
+
+// The texts of the bot, one language() per language. `t` picks the one of
+// who will read the message: the person for a private answer, the server
+// otherwise. `commands` is what Discord shows of each slash command; menu
+// commands translate their name in their own file.
+export const en = language({
+  locale: 'en-US',
+  default: true,
+  texts: {
+    presenceAnswers: {
+      one: '{count} answer found',
+      other: '{count} answers found',
+    },
+    presenceServers: { one: '{count} server', other: '{count} servers' },
+    quizAsk: '❓ {question} First to answer in 30 seconds wins!',
+    quizNobody: 'Time is up! The answer was {answer}.',
+    quizWin: {
+      one: '🎉 {user} found it, {count} point now.',
+      other: '🎉 {user} found it, {count} points now.',
+    },
+    questionCapital: 'What is the capital of France?',
+    questionPlanets: 'How many planets are there in the solar system?',
+    questionLargest: 'What is the largest planet of the solar system?',
+    questionMoon: 'In what year did people first walk on the Moon?',
+    questionWater: 'What is the chemical formula of water?',
+    scoresTitle: 'Best players',
+    scoresEmpty: 'Nobody has a point yet: try /quiz start.',
+    scoreOf: {
+      one: '{user} has {count} point, rank {rank} on this server.',
+      other: '{user} has {count} points, rank {rank} on this server.',
+    },
+    scoreNone: '{user} has no point yet.',
+    duelAccept: 'Accept',
+    duelDecline: 'Decline',
+    duelNobody: 'Challenge someone else: not yourself, and not a bot.',
+    duelAsk:
+      '⚔️ {opponent}, {user} challenges you to a duel! You have a minute.',
+    duelExpired: '{opponent} did not answer: no duel.',
+    duelDeclined: '{opponent} declined the duel.',
+    duelRolls: '🎲 {user} rolls {mine}, {opponent} rolls {theirs}.',
+    duelWinner: '{user} wins!',
+    duelDraw: 'A draw!',
+  },
+  commands: {
+    'quiz start': {
+      description: 'Asks a question: the first right answer wins',
+    },
+    'quiz scores': { description: 'The best players of the server' },
+    duel: {
+      description: 'Challenges someone to a dice duel',
+      options: { opponent: { description: 'Who to challenge' } },
+    },
+  },
+});
+
+export const fr = language({
+  locale: 'fr',
+  texts: {
+    presenceAnswers: {
+      one: '{count} réponse trouvée',
+      other: '{count} réponses trouvées',
+    },
+    presenceServers: { one: '{count} serveur', other: '{count} serveurs' },
+    quizAsk:
+      '❓ {question} La première bonne réponse dans les 30 secondes gagne !',
+    quizNobody: 'Temps écoulé ! La réponse était {answer}.',
+    quizWin: {
+      one: '🎉 {user} a trouvé, {count} point maintenant.',
+      other: '🎉 {user} a trouvé, {count} points maintenant.',
+    },
+    questionCapital: 'Quelle est la capitale de la France ?',
+    questionPlanets: 'Combien de planètes compte le système solaire ?',
+    questionLargest: 'Quelle est la plus grande planète du système solaire ?',
+    questionMoon:
+      'En quelle année a-t-on marché sur la Lune pour la première fois ?',
+    questionWater: 'Quelle est la formule chimique de l’eau ?',
+    scoresTitle: 'Meilleurs joueurs',
+    scoresEmpty: 'Personne n’a encore de point : essayez /quiz start.',
+    scoreOf: {
+      one: '{user} a {count} point, {rank}e sur ce serveur.',
+      other: '{user} a {count} points, {rank}e sur ce serveur.',
+    },
+    scoreNone: '{user} n’a encore aucun point.',
+    duelAccept: 'Accepter',
+    duelDecline: 'Refuser',
+    duelNobody: 'Défiez quelqu’un d’autre : pas vous-même, ni un bot.',
+    duelAsk: '⚔️ {opponent}, {user} vous défie en duel ! Vous avez une minute.',
+    duelExpired: '{opponent} n’a pas répondu : pas de duel.',
+    duelDeclined: '{opponent} a refusé le duel.',
+    duelRolls: '🎲 {user} fait {mine}, {opponent} fait {theirs}.',
+    duelWinner: '{user} gagne !',
+    duelDraw: 'Égalité !',
+  },
+  commands: {
+    'quiz start': {
+      description: 'Pose une question : la première bonne réponse gagne',
+    },
+    'quiz scores': { description: 'Les meilleurs joueurs du serveur' },
+    duel: {
+      description: 'Défie quelqu’un en duel de dés',
+      options: { opponent: { description: 'Qui défier' } },
+    },
+  },
+});

package/templates/games/src/presence.ts

@@ -0,0 +1,23 @@
+import { presence } from 'chapterjs';
+import { answered } from './quiz/scores';
+
+// What the bot shows under its name: three activities in turn, each for
+// its `for`. A `name` can be a function: it runs each time its activity is
+// shown, with `guilds` (the servers of the bot) and `t` (the texts in the
+// default language).
+export default presence({
+  activities: [
+    { type: 'playing', name: '/quiz start', for: '30s' },
+    {
+      type: 'watching',
+      name: async ({ t }) =>
+        t('presenceAnswers', { count: (await answered.get('total')) ?? 0 }),
+      for: '30s',
+    },
+    {
+      type: 'competing',
+      name: ({ t, guilds }) => t('presenceServers', { count: guilds }),
+      for: '30s',
+    },
+  ],
+});

package/templates/games/src/quiz/questions.ts

@@ -0,0 +1,9 @@
+// The questions of the quiz: what is asked (a key of the language files),
+// what counts as the answer, and the answer shown when nobody found it.
+export const QUESTIONS = [
+  { text: 'questionCapital', answer: /^paris$/i, shown: 'Paris' },
+  { text: 'questionPlanets', answer: /^(8|eight|huit)$/i, shown: '8' },
+  { text: 'questionLargest', answer: /^jupiter$/i, shown: 'Jupiter' },
+  { text: 'questionMoon', answer: /^1969$/, shown: '1969' },
+  { text: 'questionWater', answer: /^h2o$/i, shown: 'H2O' },
+] as const;

package/templates/games/src/quiz/quiz.ts

@@ -0,0 +1,47 @@
+import { command, userMention } from 'chapterjs';
+import { QUESTIONS } from './questions';
+import { answered, quizScores } from './scores';
+
+// `/quiz start`: a question to the channel, and the first right answer
+// wins a point. `waitForMessage()` resolves with that message, or `null`
+// after 30 seconds. One quiz at a time per channel: the cooldown.
+export const start = command({
+  name: 'quiz start',
+  cooldown: { channel: '30s' },
+  async run({ interaction, channel, t }) {
+    const question = QUESTIONS[Math.floor(Math.random() * QUESTIONS.length)]!;
+    await interaction.reply(t('quizAsk', { question: t(question.text) }));
+    const winner = await channel.waitForMessage({
+      matches: message => question.answer.test(message.content.trim()),
+      within: '30s',
+    });
+    if (!winner) {
+      await channel.send(t('quizNobody', { answer: question.shown }));
+      return;
+    }
+    const points = await quizScores.add(winner.author.id, 1);
+    await answered.increment('total');
+    await winner.reply(
+      t('quizWin', { user: winner.author.username, count: points })
+    );
+  },
+});
+
+// `/quiz scores`: the best players of the server.
+export const scores = command({
+  name: 'quiz scores',
+  async run({ interaction, t }) {
+    const best = await quizScores.top(10);
+    if (best.length === 0) {
+      await interaction.reply({ content: t('scoresEmpty'), ephemeral: true });
+      return;
+    }
+    // In an embed, a mention shows the name and notifies nobody.
+    const lines = best.map(
+      (entry, index) => `${index + 1}. ${userMention(entry.id)}: ${entry.score}`
+    );
+    await interaction.reply({
+      embeds: [{ title: t('scoresTitle'), description: lines.join('\n') }],
+    });
+  },
+});

package/templates/games/src/quiz/score-menu.ts

@@ -0,0 +1,21 @@
+import { command } from 'chapterjs';
+import { quizScores } from './scores';
+
+// A menu command: right click someone, Apps, "Quiz score". `type: 'user'`
+// puts it in the menu of a person, and `run` receives them as `target`.
+// Its name is translated here: language files only describe slash commands.
+export const quizScore = command({
+  type: 'user',
+  name: 'Quiz score',
+  locales: { fr: { name: 'Score au quiz' } },
+  ephemeral: true,
+  async run({ interaction, target, t }) {
+    const points = await quizScores.score(target.id);
+    const rank = await quizScores.rankOf(target.id);
+    await interaction.reply(
+      points === undefined || rank === undefined
+        ? t('scoreNone', { user: target.username })
+        : t('scoreOf', { user: target.username, count: points, rank })
+    );
+  },
+});

package/templates/games/src/quiz/scores.ts

@@ -0,0 +1,7 @@
+import { ranking, store } from 'chapterjs';
+
+// One point per right answer, per server, always in order.
+export const quizScores = ranking();
+
+// How many answers were found, for the whole bot: what the presence shows.
+export const answered = store<number>({ scope: 'global' });

package/templates/games/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/templates/moderation/src/moderation/messages.ts

@@ -9,6 +9,7 @@ export const en = language({
   texts: {
     cantModerate:
       'You can not moderate {user}: their highest role is above yours.',
+    notMember: '{user} is not in this server.',
     timedOut: '{user} is timed out until {until}. Reason: {reason}',
     noReason: 'none given',
     notTimedOut: '{user} is not timed out.',
@@ -82,6 +83,7 @@ export const fr = language({
   texts: {
     cantModerate:
       'Vous ne pouvez pas modérer {user} : son rôle le plus haut est au-dessus du vôtre.',
+    notMember: '{user} n’est pas sur ce serveur.',
     timedOut:
       '{user} est exclu temporairement jusqu’à {until}. Raison : {reason}',
     noReason: 'aucune',

package/templates/moderation/src/moderation/moderation.test.ts

@@ -31,7 +31,7 @@ export default [
     async bot => {
       const alice = bot.member('alice');
       const refused = await bot.use(timeout, { user: alice, duration: 5 });
-      refused.isEphemeral().says('ModerateMembers');
+      refused.isEphemeral().says('Moderate Members');
 
       const by = { by: bot.member('mod', mod) };
       const owner = await bot.use(
@@ -41,6 +41,12 @@ export default [
       );
       owner.isEphemeral().says('You can not moderate');
 
+      // Someone who left is no member any more.
+      const gone = await bot.join('gone');
+      await bot.leave(gone);
+      const left = await bot.use(timeout, { user: gone, duration: 5 }, by);
+      left.isEphemeral().says('is not in this server');
+
       const done = await bot.use(timeout, { user: alice, duration: 60 }, by);
       done.says('is timed out');
       assert.equal(alice.timedOut, true);

package/templates/moderation/src/moderation/timeout.ts

@@ -30,7 +30,15 @@ export default command({
     reason: { type: 'string', maxLength: 200 },
   },
   async run({ interaction, options, guild, member, t }) {
-    const target = await guild.fetchMember(options.user);
+    // Someone who left, or never joined, is no member: Discord says so.
+    const target = await guild.fetchMember(options.user).catch(() => null);
+    if (!target) {
+      await interaction.reply({
+        content: t('notMember', { user: options.user.toString() }),
+        ephemeral: true,
+      });
+      return;
+    }
     if (!canModerate(target, member)) {
       await interaction.reply({
         content: t('cantModerate', { user: target.toString() }),
@@ -60,7 +68,14 @@ export const untimeout = command({
     user: { type: 'user', required: true },
   },
   async run({ interaction, options, guild, member, t }) {
-    const target = await guild.fetchMember(options.user);
+    const target = await guild.fetchMember(options.user).catch(() => null);
+    if (!target) {
+      await interaction.reply({
+        content: t('notMember', { user: options.user.toString() }),
+        ephemeral: true,
+      });
+      return;
+    }
     // The same rule as /timeout: nobody lifts what someone above them set.
     if (!canModerate(target, member)) {
       await interaction.reply({

package/templates/tickets/src/tickets/tickets.test.ts

@@ -8,7 +8,7 @@ import panel, { open } from './panel';
 export default [
   scenario('the panel is posted by the staff only', async bot => {
     const refused = await bot.use(panel);
-    refused.isEphemeral().says('ManageThreads');
+    refused.isEphemeral().says('Manage Threads');
 
     const staff = bot.member('staff', { permissions: ['ManageThreads'] });
     const reply = await bot.use(panel, {}, { by: staff });