create-chapter 0.2.2 → 0.2.3

package/LICENSE

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

package/dist/index.js

@@ -67,10 +67,13 @@ if (template === undefined) {
     p.cancel('No template found. Reinstall create-chapter and try again.');
     process.exit(1);
 }
+// The exact version, not a range: `create chapter@X` makes a project on
+// `chapterjs@X`, and the project only changes version when its developer
+// runs the command `chapterjs dev` gives them.
 await createProject({
     dir,
     template,
-    chapterjsVersion: `^${version}`,
+    chapterjsVersion: version,
     packageManager: pm,
 });
 p.log.success(`Project created in ${resolve(dir)}`);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-chapter",
-  "version": "0.2.2",
+  "version": "0.2.3",
   "license": "MIT",
   "repository": {
     "type": "git",

package/templates/community/.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/templates/community/_gitignore

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

package/templates/community/package.json

@@ -0,0 +1,23 @@
+{
+  "name": "community-bot",
+  "description": "Welcome messages, roles people pick, and weekly server stats",
+  "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/community/src/messages.ts

@@ -0,0 +1,49 @@
+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, and the default language for a task.
+export const en = language({
+  locale: 'en-US',
+  default: true,
+  texts: {
+    welcome: 'Welcome to {server}, {user}!',
+    goodbye: '{name} left. See you!',
+    pickRoles: 'Pick the roles you want:',
+    rolesPlaceholder: 'Your roles',
+    noRoles: 'You have none of these roles now.',
+    rolesUpdated: 'Your roles: {roles}.',
+    rolesMissing:
+      'These roles do not exist in this server yet: {roles}. Ask an admin to create them.',
+    statsTitle: 'A new week on {server}',
+    members: 'Members',
+    textChannels: 'Text channels',
+    voiceChannels: 'Voice channels',
+    roles: 'Roles',
+  },
+  commands: {
+    roles: { description: 'Picks the roles you want' },
+  },
+});
+
+export const fr = language({
+  locale: 'fr',
+  texts: {
+    welcome: 'Bienvenue sur {server}, {user} !',
+    goodbye: '{name} est parti. À bientôt !',
+    pickRoles: 'Choisissez vos rôles :',
+    rolesPlaceholder: 'Vos rôles',
+    noRoles: 'Vous n’avez plus aucun de ces rôles.',
+    rolesUpdated: 'Vos rôles : {roles}.',
+    rolesMissing:
+      'Ces rôles n’existent pas encore sur ce serveur : {roles}. Demandez à un admin de les créer.',
+    statsTitle: 'Une nouvelle semaine sur {server}',
+    members: 'Membres',
+    textChannels: 'Salons textuels',
+    voiceChannels: 'Salons vocaux',
+    roles: 'Rôles',
+  },
+  commands: {
+    roles: { description: 'Choisit les rôles que vous voulez' },
+  },
+});

package/templates/community/src/presence.ts

@@ -0,0 +1,6 @@
+import { presence } from 'chapterjs';
+
+// What the bot shows under its name.
+export default presence({
+  activity: { type: 'watching', name: 'over the server' },
+});

package/templates/community/src/roles/roles.ts

@@ -0,0 +1,60 @@
+import { command, select } from 'chapterjs';
+
+// The roles people may give themselves: change the list, and create them
+// in your server with the same names.
+const SELF_ROLES = ['Announcements', 'Events', 'Gaming'] as const;
+
+// /roles shows the menu, with what the person already has picked.
+export default command({
+  name: 'roles',
+  ephemeral: true,
+  async run({ interaction, member, t }) {
+    const mine = member.roles
+      .map(role => role.name)
+      .filter((name): name is (typeof SELF_ROLES)[number] =>
+        (SELF_ROLES as readonly string[]).includes(name)
+      );
+    await interaction.reply({
+      content: t('pickRoles'),
+      components: [pick({ defaults: mine })],
+    });
+  },
+});
+
+// A select menu is named by its export. `values` is what was picked, typed
+// from `options`; `min: 0` lets the person remove every role.
+export const pick = select({
+  placeholder: ({ t }) => t('rolesPlaceholder'),
+  options: SELF_ROLES,
+  min: 0,
+  max: SELF_ROLES.length,
+  async run({ interaction, values, member, guild, t }) {
+    const roles = [...guild.roles.values()];
+    const missing: string[] = [];
+    for (const name of SELF_ROLES) {
+      const role = roles.find(role => role.name === name);
+      if (!role) {
+        missing.push(name);
+        continue;
+      }
+      const wanted = values.includes(name);
+      if (wanted && !member.hasRole(role))
+        await member.addRole(role, 'Picked with /roles');
+      if (!wanted && member.hasRole(role))
+        await member.removeRole(role, 'Removed with /roles');
+    }
+    await interaction.update({
+      content:
+        values.length === 0
+          ? t('noRoles')
+          : t('rolesUpdated', { roles: values.join(', ') }),
+      components: [],
+    });
+    if (missing.length > 0) {
+      await interaction.followUp({
+        content: t('rolesMissing', { roles: missing.join(', ') }),
+        ephemeral: true,
+      });
+    }
+  },
+});

package/templates/community/src/stats/weekly.ts

@@ -0,0 +1,50 @@
+import { ChannelType, task } from 'chapterjs';
+import { communityChannel } from '../welcome/channel';
+
+// A task runs by itself: every Monday at 9:00, in the timezone given. The
+// name of the export is the name of the task. `t` is the default language.
+export const weekly = task({
+  cron: '0 9 * * 1',
+  timezone: 'Europe/Paris',
+  async run({ guilds, t }) {
+    for (const guild of guilds.values()) {
+      const channel = communityChannel(guild, 'general');
+      if (!channel) continue;
+      const channels = [...guild.channels.values()];
+      await channel.send({
+        embeds: [
+          {
+            title: t('statsTitle', { server: guild.name }),
+            color: 0xc026d3,
+            fields: [
+              {
+                name: t('members'),
+                value: String(guild.memberCount ?? '?'),
+                inline: true,
+              },
+              {
+                name: t('textChannels'),
+                value: String(
+                  channels.filter(c => c.type === ChannelType.GuildText).length
+                ),
+                inline: true,
+              },
+              {
+                name: t('voiceChannels'),
+                value: String(
+                  channels.filter(c => c.type === ChannelType.GuildVoice).length
+                ),
+                inline: true,
+              },
+              {
+                name: t('roles'),
+                value: String(guild.roles.size - 1),
+                inline: true,
+              },
+            ],
+          },
+        ],
+      });
+    }
+  },
+});

package/templates/community/src/welcome/channel.ts

@@ -0,0 +1,19 @@
+import type { Guild, TextChannel } from 'chapterjs';
+
+// Plain code, shared by the other files: the channel the bot writes in.
+// The one named like `name` when there is one, else the system channel of
+// the server (where Discord itself says who joined), else nothing.
+export function communityChannel(
+  guild: Guild,
+  name: string
+): TextChannel | null {
+  const channels = [...guild.channels.values()];
+  const named = channels.find(
+    channel => channel.isText() && channel.name === name
+  );
+  if (named?.isText()) return named;
+  const system = guild.systemChannelId
+    ? guild.channels.get(guild.systemChannelId)
+    : undefined;
+  return system?.isText() ? system : null;
+}

package/templates/community/src/welcome/welcome.ts

@@ -0,0 +1,37 @@
+import { embed, event, type GuildMember } from 'chapterjs';
+import { communityChannel } from './channel';
+
+// Runs when someone joins the server. It needs the Server Members Intent:
+// chapterjs dev tells you where to enable it the first time.
+export default event({
+  name: 'memberJoin',
+  async run({ member, guild, t }) {
+    const channel = communityChannel(guild, 'welcome');
+    if (!channel) return;
+    await channel.send({
+      content: t('welcome', { user: member.toString(), server: guild.name }),
+      embeds: [card(member)],
+    });
+  },
+});
+
+// Someone left. `member` is the member as it was, when the bot knew them;
+// `user` is always there.
+export const goodbye = event({
+  name: 'memberLeave',
+  async run({ user, member, guild, t }) {
+    const channel = communityChannel(guild, 'welcome');
+    if (!channel) return;
+    await channel.send(
+      t('goodbye', { name: member?.displayName ?? user.displayName })
+    );
+  },
+});
+
+// An embed is a function of what it shows, reusable from any file.
+export const card = embed((member: GuildMember) => ({
+  title: member.displayName,
+  description: `You are member #${member.guild.memberCount ?? '?'}.`,
+  thumbnail: { url: member.avatarURL() },
+  color: 0xc026d3,
+}));

package/templates/community/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/default/_gitignore

@@ -2,3 +2,4 @@ node_modules
 dist
 .env
 .chapterjs
+data

package/templates/default/package.json

@@ -1,6 +1,6 @@
 {
   "name": "chapter-bot",
-  "description": "A minimal bot, ready to grow",
+  "description": "A bot that starts: one event, ready to grow",
   "private": true,
   "type": "module",
   "scripts": {

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

@@ -1,8 +1,9 @@
 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.
+// Your bot is made of the files of src/: each one exports what it declares
+// with a function of 'chapterjs' (event, command, button, task...), and
+// chapterjs dev runs it. This one is an event: `name` says which, and types
+// what `run` receives. `ready` runs once, when the bot is connected.
 export default event({
   name: 'ready',
   run({ user, guilds }) {
@@ -10,25 +11,18 @@ export default event({
   },
 });
 
-// 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.
+// A command is a file like this one, anywhere in src/, with command():
 //
-// import { task } from 'chapterjs';
+// import { command } 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)`);
+// export default command({
+//   name: 'ping',
+//   description: 'Replies with Pong!',
+//   async run({ interaction }) {
+//     await interaction.reply('Pong!');
 //   },
 // });
 //
-// 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!');
-//   },
-// });
+// Save it, and /ping shows up in your test server. The other templates of
+// `pnpm create chapter` show tickets, music, moderation and a community
+// bot; the docs at https://www.chapterjs.org walk through everything.

package/templates/moderation/.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/templates/moderation/_gitignore

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

package/templates/moderation/package.json

@@ -0,0 +1,23 @@
+{
+  "name": "moderation-bot",
+  "description": "Timeouts, purge, slowmode, lock, and a log of every moderation action",
+  "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/moderation/src/moderation/channel.ts

@@ -0,0 +1,67 @@
+import { command } from 'chapterjs';
+
+// /slowmode sets how long people wait between two messages in the channel.
+// 0 removes it.
+export const slowmode = command({
+  name: 'slowmode',
+  permissions: ['ManageChannels'],
+  options: {
+    seconds: { type: 'integer', min: 0, max: 21600, required: true },
+  },
+  async run({ interaction, options, channel, member, t }) {
+    if (!channel.isText()) {
+      await interaction.reply({ content: t('notHere'), ephemeral: true });
+      return;
+    }
+    await channel.edit(
+      { rateLimitPerUser: options.seconds },
+      `By ${member.user.username}`
+    );
+    await interaction.reply(
+      options.seconds === 0
+        ? t('slowmodeOff')
+        : t('slowmodeOn', { count: options.seconds })
+    );
+  },
+});
+
+// /lock keeps everyone from writing in the channel, /unlock gives it back.
+// Both change the permissions of @everyone on the channel only.
+export const lock = command({
+  name: 'lock',
+  permissions: ['ManageChannels'],
+  options: {
+    reason: { type: 'string', maxLength: 200 },
+  },
+  async run({ interaction, options, channel, guild, member, t }) {
+    if (!channel.isText()) {
+      await interaction.reply({ content: t('notHere'), ephemeral: true });
+      return;
+    }
+    await channel.setPermissions(
+      guild.everyoneRole,
+      { deny: ['SendMessages', 'CreatePublicThreads', 'CreatePrivateThreads'] },
+      options.reason ?? `Locked by ${member.user.username}`
+    );
+    await interaction.reply(
+      t('locked', { reason: options.reason ?? t('noReason') })
+    );
+  },
+});
+
+export const unlock = command({
+  name: 'unlock',
+  permissions: ['ManageChannels'],
+  async run({ interaction, channel, guild, member, t }) {
+    if (!channel.isText()) {
+      await interaction.reply({ content: t('notHere'), ephemeral: true });
+      return;
+    }
+    // Deleting the overwrite gives @everyone back what the server says.
+    await channel.deletePermissions(
+      guild.everyoneRole,
+      `Unlocked by ${member.user.username}`
+    );
+    await interaction.reply(t('unlocked'));
+  },
+});

package/templates/moderation/src/moderation/log.ts

@@ -0,0 +1,37 @@
+import { AuditLogEvent, event } from 'chapterjs';
+
+// Every moderation action, whoever did it and however (a command of this
+// bot, another bot, the Discord app), reaches the audit log of the server.
+// This posts the ones below in the channel named mod-log. Discord only
+// sends the audit log to a bot with the View Audit Log permission.
+const ACTIONS: Partial<Record<number, string>> = {
+  [AuditLogEvent.MemberKick]: 'kicked',
+  [AuditLogEvent.MemberBanAdd]: 'banned',
+  [AuditLogEvent.MemberBanRemove]: 'unbanned',
+  [AuditLogEvent.MemberUpdate]: 'updated (timeout, nickname...)',
+  [AuditLogEvent.MessageBulkDelete]: 'purged messages in',
+  [AuditLogEvent.ChannelOverwriteUpdate]: 'changed the permissions of',
+  [AuditLogEvent.ChannelOverwriteCreate]: 'changed the permissions of',
+  [AuditLogEvent.ChannelOverwriteDelete]: 'changed the permissions of',
+};
+
+export default event({
+  name: 'auditLogEntryCreate',
+  async run({ entry, guild }) {
+    const action = ACTIONS[entry.actionType];
+    if (!action || !entry.userId) return;
+    const log = [...guild.channels.values()].find(
+      channel => channel.isText() && channel.name === 'mod-log'
+    );
+    if (!log?.isText()) return;
+    const who = `<@${entry.userId}>`;
+    const target = entry.targetId
+      ? guild.channels.has(entry.targetId)
+        ? `<#${entry.targetId}>`
+        : `<@${entry.targetId}>`
+      : 'something';
+    await log.send(
+      `🛡️ ${who} ${action} ${target}${entry.reason ? `: ${entry.reason}` : ''}`
+    );
+  },
+});