create-seedcord 0.0.1 → 0.1.0

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "create-seedcord",
   "type": "module",
-  "version": "0.0.1",
+  "version": "0.1.0",
   "description": "Scaffold a new seedcord bot project",
   "engines": {
     "node": ">=24.11"
@@ -14,32 +14,28 @@
     "url": "https://github.com/seedcord/seedcord.git",
     "directory": "cli/create-seedcord"
   },
-  "types": "./dist/index.d.mts",
-  "exports": {
-    ".": {
-      "import": {
-        "types": "./dist/index.d.mts",
-        "default": "./dist/index.mjs"
-      },
-      "require": {
-        "types": "./dist/index.d.cts",
-        "default": "./dist/index.cjs"
-      }
-    }
+  "seedcordDocs": {
+    "skip": true
   },
   "files": [
     "bin",
     "dist",
+    "templates",
     "package.json",
     "README.md",
     "LICENSE"
   ],
   "devDependencies": {
+    "@clack/prompts": "^1.7.0",
+    "discord.js": "^14.27.0",
+    "handlebars": "^4.7.9",
+    "package-manager-detector": "^1.8.0",
     "tsx": "^4.23.5",
     "typescript": "^6.0.3",
-    "@seedcord/cli-shared": "0.0.1",
+    "@seedcord/errors": "0.3.3",
     "@seedcord/eslint-config": "1.5.2",
     "@seedcord/tsconfig": "2.0.2",
+    "@seedcord/types": "0.8.2",
     "@seedcord/tsdown-config": "2.0.1",
     "@seedcord/vitest-config": "0.0.1"
   },
@@ -60,5 +56,5 @@
     "test:watch": "vitest dev",
     "coverage": "vitest run --coverage"
   },
-  "readme": "<p align=\"center\">\n  <picture>\n    <source media=\"(prefers-color-scheme: dark)\" srcset=\"https://cdn.seedcord.org/assets/wordmark-dark.webp\" />\n    <img src=\"https://cdn.seedcord.org/assets/wordmark-light.webp\" alt=\"seedcord\" width=\"440\" />\n  </picture>\n</p>\n\n# @seedcord/create-seedcord\n\nScaffold a new seedcord bot project\n\nPart of the [seedcord](https://github.com/seedcord/seedcord) framework. Until a major v1.0.0 release, expect breaking changes in minor versions.\n"
+  "readme": "<p align=\"center\">\n  <picture>\n    <source media=\"(prefers-color-scheme: dark)\" srcset=\"https://cdn.seedcord.org/assets/wordmark-dark.webp\" />\n    <img src=\"https://cdn.seedcord.org/assets/wordmark-light.webp\" alt=\"seedcord\" width=\"440\" />\n  </picture>\n</p>\n\n# create-seedcord\n\nScaffold a new seedcord bot project.\n\n## Usage\n\n```sh\npnpm create seedcord my-bot\nnpm create seedcord my-bot\nyarn create seedcord my-bot\n```\n\nIt asks where the project goes, how Discord reaches your bot, what the bot should react to, your bot token, and an accent color. Then it writes the project, installs, formats, generates your command types, and makes the first commit.\n\n## Flags\n\nEvery question has a flag. Pass them all to skip all questions. `--help` prints the list.\n\nnpm forwards flags to the package only after a `--`:\n\n```sh\nnpm create seedcord my-bot -- --transport gateway --capabilities reactions\npnpm create seedcord my-bot --transport gateway --capabilities reactions\n```\n\n`--no-install` and `--no-git` turn off those two steps.\n\nWith no terminal to ask on, it reads the flags alone. It names the flag that would supply any answer you left out.\n\n## What you get\n\nYou get a TypeScript project with one slash command, its handler, a sample event handler (if you picked `gateway`), `seedcord.config.ts`, eslint, prettier, and a `.env` listing every key the framework reads.\n\n`pnpm dev` starts it with hot reload. On the http transport it also opens a cloudflared tunnel and sets it up, and Discord posts interactions to that URL.\n\n## Docs\n\n- Guide: <https://guide.seedcord.org>\n- API reference: <https://docs.seedcord.org>\n\nPart of the [seedcord](https://github.com/seedcord/seedcord) framework. Until a major v1.0.0 release, expect breaking changes in minor versions.\n"
 }

package/templates/README.md.hbs

@@ -0,0 +1,62 @@
+# {{ projectName }}
+
+A Discord bot built with [seedcord](https://seedcord.org){{#if isGateway}} on the gateway transport{{else}} on the http transport{{/if}}.
+
+## Running it
+
+```sh
+{{ pm.run }} dev
+```
+
+That starts the dev server with hot reload{{#unless isGateway}} and opens a tunnel so Discord can reach your interactions endpoint{{/unless}}.
+
+## Scripts
+
+<!-- prettier-ignore-start -->
+
+| script | what it does |
+| --- | --- |
+| `{{ pm.run }} dev` | dev server with hot reload |
+| `{{ pm.run }} build` | compile to `dist/` |
+| `{{ pm.run }} start` | run the compiled build |
+| `{{ pm.run }} codegen` | regenerate `src/seedcord-gen.d.ts` |
+| `{{ pm.run }} lint` | eslint |
+| `{{ pm.run }} tc` | type-check |
+
+<!-- prettier-ignore-end -->
+
+Run `codegen` after you add a command or change its options. It writes the types behind `this.options`, and the generated file is committed.
+
+## Environment
+
+`.env` holds your secrets and is gitignored.
+
+<!-- prettier-ignore-start -->
+
+| key | required |
+| --- | --- |
+| `DISCORD_BOT_TOKEN` | yes |
+{{#unless isGateway}}
+| `DISCORD_PUBLIC_KEY` | yes |
+{{/unless}}
+| `UNKNOWN_EXCEPTION_WEBHOOK_URL` | no |
+| `HANDLED_EXCEPTION_WEBHOOK_URL` | no |
+| `ENV` | no, defaults to `development` |
+
+<!-- prettier-ignore-end -->
+
+The two webhook keys take Discord webhook URLs. Set them to get error reports posted to a channel.
+
+## Where things go
+
+- `src/commands/` holds command definitions, one class per command.
+- `src/handlers/` holds the code that runs when someone uses one.
+{{#if isGateway}}
+- `src/events/` holds event handlers for the things happening in a server.
+{{/if}}
+- `src/bot.ts` is the config.
+
+## Docs
+
+- Guide: <https://guide.seedcord.org>
+- API reference: <https://docs.seedcord.org>

package/templates/env.hbs

@@ -0,0 +1,13 @@
+# Your bot token, from the Bot page of your app in the Discord Developer Portal
+DISCORD_BOT_TOKEN={{ token }}
+{{#unless isGateway}}
+
+# Public key, from the General Information page of the same app
+DISCORD_PUBLIC_KEY={{ publicKey }}
+{{/unless}}
+
+# Discord webhooks the framework posts error reports to. Leave empty to skip reporting.
+UNKNOWN_EXCEPTION_WEBHOOK_URL=
+HANDLED_EXCEPTION_WEBHOOK_URL=
+
+ENV=development

package/templates/eslint.config.mjs.hbs

@@ -0,0 +1,8 @@
+import createConfig from '@seedcord/eslint-config';
+
+export default createConfig({
+    tsconfigRootDir: import.meta.dirname,
+    registerDiscordjsPlugin: true,
+    registerSeedcordPlugin: true,
+    generalIgnores: ['**/seedcord-gen.d.ts']
+});

package/templates/gitignore.hbs

@@ -0,0 +1,12 @@
+node_modules/
+dist/
+logs/
+*.log
+*.tsbuildinfo
+.eslintcache
+.seedcord/
+
+.env*
+!.env.example
+
+.DS_Store

package/templates/package.json.hbs

@@ -0,0 +1,19 @@
+{
+    "name": "{{ projectName }}",
+    "type": "module",
+    "version": "0.1.0",
+    "private": true,
+    "engines": {
+        "node": ">=24.11"
+    },
+    "scripts": {
+        "dev": "seedcord dev",
+        "build": "seedcord build",
+        "start": "node --enable-source-maps dist/index.mjs",
+        "codegen": "seedcord codegen",
+        "lint": "eslint 'src/**/*.ts' --cache",
+        "lint:fix": "eslint 'src/**/*.ts' --fix --cache",
+        "fmt": "prettier --write 'src/**/*.{ts,json,md}' --cache",
+        "tc": "tsc --noEmit"
+    }
+}

package/templates/prettier.config.mjs.hbs

@@ -0,0 +1,3 @@
+import { PRETTIER_CONFIG } from '@seedcord/eslint-config/prettier';
+
+export default PRETTIER_CONFIG;

package/templates/prettierignore.hbs

@@ -0,0 +1 @@
+seedcord-gen.d.ts

package/templates/seedcord.config.ts.hbs

@@ -0,0 +1,10 @@
+import { defineConfig } from 'seedcord';
+
+export default defineConfig({
+    root: './src',
+    instance: './bot.ts',
+    entry: './index.ts',
+    build: {
+        tsconfig: './tsconfig.build.json'
+    }
+});

package/templates/src/bot.ts.hbs

@@ -0,0 +1,44 @@
+import { resolve } from 'node:path';
+
+{{#if isGateway}}
+import { Seedcord } from '@seedcord/gateway';
+import { GatewayIntentBits{{#if partials}}, Partials{{/if}} } from 'discord.js';
+{{else}}
+import { Seedcord } from '@seedcord/http';
+{{/if}}
+import { Envapter } from 'envapt';
+
+Envapter.baseDir = resolve(import.meta.dirname, '..');
+
+export const seedcord = new Seedcord({
+    bot: {
+{{#if isGateway}}
+        clientOptions: {
+            intents: [
+{{#each intents}}
+                GatewayIntentBits.{{ this }}{{#unless @last}},{{/unless}}
+{{/each}}
+            ]{{#if partials}},
+            partials: [{{#each partials}}Partials.{{ this }}{{#unless @last}}, {{/unless}}{{/each}}]{{/if}}
+        },
+{{/if}}
+        interactions: {
+            path: resolve(import.meta.dirname, './handlers')
+        },
+        commands: {
+            path: resolve(import.meta.dirname, './commands')
+        }{{#if isGateway}},
+        events: {
+            path: resolve(import.meta.dirname, './events')
+        }{{/if}}
+    },
+    subscribers: {
+        path: null
+    },
+    botColor: '{{ botColor }}',
+    notifications: {
+        developerUsername: '{{ developerUsername }}'
+    }
+});
+
+export default seedcord;

package/templates/src/commands/Ping.ts.hbs

@@ -0,0 +1,13 @@
+import { BuilderComponent, RegisterCommand } from '{{ transportPackage }}';
+
+@RegisterCommand('global')
+export class Ping extends BuilderComponent<'command'> {
+    constructor() {
+        super('command');
+
+        this.instance
+            .setName('ping')
+            .setDescription('Check that the bot is answering')
+            .addBooleanOption((option) => option.setName('detailed').setDescription('Include process uptime'));
+    }
+}

package/templates/src/events/Mentioned.ts.hbs

@@ -0,0 +1,18 @@
+{{#if hasMessages}}
+import { EventHandler, Gated, IgnoreBots, RegisterEvent } from '{{ transportPackage }}';
+import { Events } from 'discord.js';
+
+@Gated(IgnoreBots)
+@RegisterEvent([Events.MessageCreate])
+export class Mentioned extends EventHandler<Events.MessageCreate> {
+    public async execute(): Promise<void> {
+        const [message] = this.event;
+        if (!message.inGuild()) return;
+
+        // discord sends the content of a message that mentions your app without the privileged intent
+        if (!message.mentions.users.has(message.client.user.id)) return;
+
+        await message.reply(`hey ${message.author.displayName}`);
+    }
+}
+{{/if}}

package/templates/src/events/Ready.ts.hbs

@@ -0,0 +1,16 @@
+{{#if isGateway}}
+{{#unless hasMessages}}
+import { EventHandler, RegisterEvent } from '{{ transportPackage }}';
+import { Events } from 'discord.js';
+
+@RegisterEvent([Events.ClientReady, { frequency: 'once' }])
+export class Ready extends EventHandler<Events.ClientReady> {
+    public async execute(): Promise<void> {
+        const [client] = this.event;
+        const application = await client.application.fetch();
+
+        this.logger.info(`${application.name} is in ${client.guilds.cache.size} servers`);
+    }
+}
+{{/unless}}
+{{/if}}

package/templates/src/handlers/Ping.ts.hbs

@@ -0,0 +1,15 @@
+import { SlashHandler, SlashRoute, timestampFromSnowflake } from '{{ transportPackage }}';
+
+@SlashRoute('ping')
+export class Ping extends SlashHandler<'ping'> {
+    public async execute(): Promise<void> {
+        const roundtrip = Date.now() - timestampFromSnowflake(this.event.id);
+        const lines = ['### Pong', `Roundtrip **${roundtrip}ms**`];
+
+        if (this.options.getBoolean('detailed')) {
+            lines.push(`Uptime **${Math.round(process.uptime())}s**`);
+        }
+
+        await this.reply(lines.join('\n'));
+    }
+}

package/templates/src/index.ts.hbs

@@ -0,0 +1,3 @@
+import seedcord from './bot';
+
+await seedcord.start();

package/templates/tsconfig.build.json.hbs

@@ -0,0 +1,11 @@
+{
+    "$schema": "https://json.schemastore.org/tsconfig",
+    "extends": "./tsconfig.json",
+    "compilerOptions": {
+        "rootDir": "./src",
+        "outDir": "./dist",
+        "noEmit": false
+    },
+    "include": ["src/**/*.ts"],
+    "exclude": ["node_modules", "dist"]
+}

package/templates/tsconfig.json.hbs

@@ -0,0 +1,10 @@
+{
+    "$schema": "https://json.schemastore.org/tsconfig",
+    "extends": "@seedcord/tsconfig/node",
+    "compilerOptions": {
+        "rootDir": "./",
+        "outDir": "./dist"
+    },
+    "include": ["src/**/*.ts", "seedcord.config.ts"],
+    "exclude": ["node_modules", "dist"]
+}

package/dist/index.cjs

@@ -1,8 +0,0 @@
-Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
-//#region src/index.ts
-/** Package version */
-const version = "0.0.1";
-
-//#endregion
-exports.version = version;
-//# sourceMappingURL=index.cjs.map

package/dist/index.cjs.map

@@ -1 +0,0 @@
-{"version":3,"file":"index.cjs","names":[],"sources":["../src/index.ts"],"sourcesContent":["/** Package version */\nexport const version = process.env.PACKAGE_VERSION ?? '0.0.0';\n"],"mappings":";;;AACA,MAAa"}

package/dist/index.d.cts

@@ -1 +0,0 @@
-export type * from './index.d.mts'

package/dist/index.d.mts

@@ -1,6 +0,0 @@
-//#region src/index.d.ts
-/** Package version */
-declare const version: string;
-//#endregion
-export { version };
-//# sourceMappingURL=index.d.mts.map