create-kokkoro 0.1.1 → 0.2.0

package/README.md

@@ -1,43 +1,48 @@
 # create-kokkoro
 
-Kokkoro QQ 机器人框架的项目创建工具。
+Kokkoro QQ 机器人框架的项目创建工具。按照终端提示填写配置，即可生成项目目录和启动文件。
 
-## 使用
+使用前需要安装 [Bun](https://bun.com/docs/installation)，它负责安装项目依赖和运行 Kokkoro。
 
-运行以下命令创建 Kokkoro 项目：
+## 创建项目
+
+在终端中进入准备存放项目的目录，运行：
 
 ```shell
 bun create kokkoro
 ```
 
-命令会创建项目目录、`plugins` 目录、`package.json`、`kokkoro.json` 和 `main.ts`。
+按照提示输入项目名称、服务端口、QQ 服务接入方式和机器人配置。直接按回车可使用默认项目名称 `kokkoro-app` 和端口 `3000`。
+
+本地开发可以选择 WebSocket。添加机器人时，需要填写从 QQ 开放平台获取的 AppID 和 ClientSecret。还没有机器人时，可以在“是否添加机器人”处选择“否”，以后再修改 `kokkoro.json`。具体操作见[快速上手](https://kokkoro.js.org/guide/quick-start)。
+
+## 启动项目
 
-如果项目目录不是空目录，创建将中止。使用 `--force` 或 `-f` 选项可以覆盖脚手架创建的同名文件，目录中的其他内容不受影响。
+创建完成后，进入生成的文件夹，安装依赖并启动服务。下面使用默认项目名称：
 
 ```shell
-bun create kokkoro --force
+cd kokkoro-app
+bun install
+bun start
 ```
 
-## 配置项目
+如果使用了其他名称，将 `kokkoro-app` 换成对应的文件夹名称。终端显示“服务已启动”后，说明 HTTP 服务已经运行。按 `Ctrl+C` 可以停止服务。
 
-命令会依次询问以下内容：
+## 项目文件
 
-1. 输入项目名称，默认值为 `kokkoro-app`。
-2. 输入服务端口，默认值为 `3000`。
-3. 选择 QQ 服务接入方式，可选 `WebSocket` 或 `WebHook`。
-4. 选择是否添加机器人。不添加机器人时，`kokkoro.json` 中的 `bots` 为空数组。
-5. 添加机器人时，输入机器人的 `AppID` 和 `ClientSecret`。
-6. 使用 `WebHook` 并添加机器人时，输入 WebHook 路径，默认值为 `/callback`。
+生成的项目包含以下内容：
 
-### 启动项目
+| 路径           | 用途                    |
+| -------------- | ----------------------- |
+| `kokkoro.json` | 保存机器人和服务配置    |
+| `main.ts`      | 启动 Kokkoro 的入口文件 |
+| `plugins/`     | 存放自己编写的插件      |
+| `package.json` | 声明项目依赖和启动命令  |
 
-创建完成后，进入项目目录并安装依赖：
+如果同名文件夹已经存在且不为空，创建过程会停止。需要覆盖已有模板文件时，可以运行 `bun create kokkoro --force`，其他文件会保留。覆盖范围见[创建项目](https://kokkoro.js.org/guide/cli#create-project)。
 
-```shell
-cd kokkoro-app
-
-bun install
-bun start
-```
+## 接下来
 
-将 `kokkoro-app` 替换为你输入的项目名称。
+- [配置文件](https://kokkoro.js.org/guide/config)，修改机器人凭证、端口和接入方式。
+- [编写第一个插件](https://kokkoro.js.org/develop/first-plugin)，为机器人添加功能。
+- [命令行工具](https://kokkoro.js.org/guide/cli)，使用 `kokkoro` 命令创建插件和启动项目。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-kokkoro",
-  "version": "0.1.1",
+  "version": "0.2.0",
   "description": "The project creation tool for the Kokkoro QQ bot framework.",
   "keywords": [
     "bot",

package/src/project.ts

@@ -1,4 +1,4 @@
-import { Glob, write } from 'bun';
+import { $, file, Glob, write } from 'bun';
 import { existsSync } from 'node:fs';
 import { mkdir } from 'node:fs/promises';
 import { basename, join, resolve } from 'node:path';
@@ -15,6 +15,15 @@ const MAIN = [
   '',
 ].join('\n');
 
+const PLUGIN = [
+  "import { useCommand } from '@kokkoro/core';",
+  '',
+  'export default () => {',
+  "  useCommand('/ping', () => 'pong');",
+  '};',
+  '',
+].join('\n');
+
 async function hasEntries(directory: string): Promise<boolean> {
   if (!existsSync(directory)) {
     return false;
@@ -24,8 +33,7 @@ async function hasEntries(directory: string): Promise<boolean> {
     dot: true,
     onlyFiles: false,
   });
-  const iterator = entries[Symbol.asyncIterator]();
-  const { done } = await iterator.next();
+  const { done } = await entries.next();
 
   return !done;
 }
@@ -100,7 +108,7 @@ function promptBots(protocol: Protocol) {
 
 /** 在指定目录创建 Kokkoro 项目。 */
 export async function createProject(directory: string, isForced = false): Promise<void> {
-  if ((await hasEntries(directory)) && !isForced) {
+  if (!isForced && (await hasEntries(directory))) {
     throw new Error(`目标目录不是空目录，如需继续，请使用 --force 选项覆盖模板文件\n${directory}`);
   }
   const port = promptPort();
@@ -116,7 +124,10 @@ export async function createProject(directory: string, isForced = false): Promis
       start: 'bun run main.ts',
     },
     dependencies: {
-      kokkoro: '^3.0.1',
+      kokkoro: '^3.0.3',
+    },
+    peerDependencies: {
+      typescript: '^6.0.3',
     },
     devEngines: {
       runtime: {
@@ -147,8 +158,43 @@ export async function createProject(directory: string, isForced = false): Promis
   console.log('\n项目创建完成，请依次运行以下命令：\n');
 
   if (directory !== '.') {
-    console.log(`  cd ${directory}`);
+    console.log(`  cd ${$.escape(resolve(directory))}`);
   }
   console.log('  bun install');
   console.log('  bun start');
 }
+
+/** 在当前 Kokkoro 项目中创建本地插件。 */
+export async function createPlugin(name: string, isForced = false): Promise<void> {
+  if (!/^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$/.test(name)) {
+    throw new Error('插件名称必须以小写字母开头，且只能包含小写字母、数字和连字符');
+  }
+
+  if (!(await file('kokkoro.json').exists())) {
+    throw new Error('当前目录不是 Kokkoro 项目，请先运行 init 命令');
+  }
+  const destination = join('plugins', name);
+
+  if (!isForced && (await hasEntries(destination))) {
+    throw new Error(`目标插件目录不是空目录，如需继续，请使用 --force 选项覆盖模板文件\n${destination}`);
+  }
+  const source = join(destination, 'src');
+  const manifest = {
+    name: `kokkoro-plugin-${name}`,
+    version: '0.0.0',
+    type: 'module',
+    files: ['src'],
+    exports: './src/index.ts',
+    peerDependencies: {
+      '@kokkoro/core': '^3.1.5',
+      typescript: '^6.0.3',
+    },
+  };
+
+  await Promise.all([
+    write(join(destination, 'package.json'), `${JSON.stringify(manifest, null, 2)}\n`),
+    write(join(source, 'index.ts'), PLUGIN),
+  ]);
+
+  console.log(`插件 ${name} 创建完成，请运行 bun i 同步工作区依赖`);
+}