create-koishi-ce 1.0.0

package/lib/bin.d.ts

@@ -0,0 +1 @@
+export {}

package/lib/bin.mjs

@@ -0,0 +1,13 @@
+#!/usr/bin/env bun
+import { r as start } from "./src-D9XdTOrE.mjs";
+//#region src/bin.ts
+/**
+* create-koishi-ce 的 CLI 可执行入口：shebang 由 rolldown 原样保留到
+* lib/bin.mjs，package.json 的 bin 字段指向它（范式同 @koishi-ce/scripts）。
+*/
+start().catch((err) => {
+	console.error(err);
+	process.exitCode = 1;
+});
+//#endregion
+export {};

package/lib/index.d.ts

@@ -0,0 +1,31 @@
+//#region src/index.d.ts
+/**
+ * 模板项目的 package.json（改写目标）：只需要类型化本流程触碰的字段，
+ * 其余字段经 index signature 原样保留。
+ */
+interface Manifest {
+  name?: string;
+  private?: boolean;
+  version?: string;
+  workspaces?: unknown;
+  devDependencies?: unknown;
+  [key: string]: unknown;
+}
+/**
+ * 探测后续安装/启动使用的包管理器（Bun-first）：yarn / pnpm 用户跟随其
+ * 生态习惯；其余场景（npm、bun 及探测不到 user-agent）一律走 bun——
+ * 本 CLI 自身以 bun 为运行时（bin shebang），能执行即已具备 bun 环境。
+ */
+declare function detectAgent(): string;
+/**
+ * 改写模板的 package.json（纯函数，导出供单测）：替换项目名、标记
+ * private、版本归零。
+ */
+declare function renderManifest(source: Manifest, project: string, prod: boolean): string;
+/**
+ * CLI 主流程：--help 打印用法后即返回；否则依次执行
+ * 项目名询问 → prepare（目录准备）→ scaffold（模板解包）→ initGit → install。
+ */
+declare function start(): Promise<void>;
+//#endregion
+export { Manifest, detectAgent, renderManifest, start };

package/lib/index.mjs

@@ -0,0 +1,2 @@
+import { n as renderManifest, r as start, t as detectAgent } from "./src-D9XdTOrE.mjs";
+export { detectAgent, renderManifest, start };

package/lib/src-D9XdTOrE.mjs

@@ -0,0 +1,312 @@
+import { spawnSync } from "node:child_process";
+import { existsSync, mkdirSync, readFileSync, readdirSync, rmSync, writeFileSync } from "node:fs";
+import { basename, join, relative } from "node:path";
+import { Readable } from "node:stream";
+import getRegistry from "get-registry";
+import kleur from "kleur";
+import prompts from "prompts";
+import { extract } from "tar";
+import parse from "yargs-parser";
+//#endregion
+//#region src/index.ts
+/**
+* create-koishi-ce 脚手架（npm 包名 create-koishi-ce，目录名为
+* apps/koishi-create，二者不一致是历史遗留，以目录名为准）。
+*
+* 通过 `bunx create-koishi-ce [name]`（npx 亦可）交互式创建 Koishi 机器人
+* 应用项目：确定项目名 → 准备目标目录 → 从 npm registry 下载模板包（默认
+* @koishijs/boilerplate，刻意沿用上游官方模板以保持与上游插件生态一致）
+* 并解包 → 改写 package.json → 按需初始化 git → 询问是否立即安装依赖并
+* 启动。CLI 可执行入口在 src/bin.ts（构建产物 lib/bin.mjs，bin 字段指向
+* 它）；本文件只承载主流程与可单测的纯函数（范式对齐 @koishi-ce/scripts）。
+*/
+const { version } = {
+	name: "create-koishi-ce",
+	description: "Setup a Koishi application",
+	version: "1.0.0",
+	type: "module",
+	main: "./lib/index.mjs",
+	module: "./lib/index.mjs",
+	types: "./lib/index.d.ts",
+	bin: { "create-koishi-ce": "./lib/bin.mjs" },
+	files: ["lib", "src"],
+	contributors: ["Shigma <shigma10826@gmail.com>", "Oppenheymu <oppenheymu@gmail.com>"],
+	license: "MIT",
+	repository: {
+		"type": "git",
+		"url": "git+https://github.com/Koishi-CE/koishi.git",
+		"directory": "apps/koishi-create"
+	},
+	bugs: { "url": "https://github.com/Koishi-CE/koishi/issues" },
+	homepage: "https://koishi.chat",
+	scripts: { "build": "tsdown" },
+	keywords: [
+		"bot",
+		"chatbot",
+		"koishi",
+		"discord",
+		"telegram",
+		"create",
+		"scaffold",
+		"template",
+		"generator",
+		"boilerplate"
+	],
+	devDependencies: {
+		"@types/prompts": "^2.4.9",
+		"@types/yargs-parser": "^21.0.3"
+	},
+	dependencies: {
+		"get-registry": "^1.1.0",
+		"kleur": "^4.1.5",
+		"prompts": "^2.4.2",
+		"tar": "^7.5.22",
+		"yargs-parser": "^22.0.0"
+	},
+	exports: {
+		".": {
+			"source": "./src/index.ts",
+			"types": "./lib/index.d.ts",
+			"import": "./lib/index.mjs",
+			"default": "./lib/index.mjs"
+		},
+		"./package.json": "./package.json"
+	}
+};
+/** fetch 请求非 2xx 时抛出的错误，携带 HTTP 状态码与状态文本 */
+var HttpError = class extends Error {
+	status;
+	statusText;
+	constructor(status, statusText) {
+		super(`HTTP ${status} ${statusText}`);
+		this.status = status;
+		this.statusText = statusText;
+	}
+};
+const argv = parse(process.argv.slice(2), { alias: {
+	ref: ["r"],
+	forced: ["f"],
+	git: ["g"],
+	prod: ["p"],
+	template: ["t"],
+	yes: ["y"],
+	help: ["h"]
+} });
+/** 项目目录名（rootDir 的最后一段，写入生成项目的 package.json 的 name） */
+let project;
+/** 目标目录的绝对路径（由用户输入的项目名拼接 cwd 得到） */
+let rootDir;
+const cwd = process.cwd();
+/**
+* 探测后续安装/启动使用的包管理器（Bun-first）：yarn / pnpm 用户跟随其
+* 生态习惯；其余场景（npm、bun 及探测不到 user-agent）一律走 bun——
+* 本 CLI 自身以 bun 为运行时（bin shebang），能执行即已具备 bun 环境。
+*/
+function detectAgent() {
+	const ua = process.env["npm_config_user_agent"] ?? "";
+	if (ua.startsWith("yarn")) return "yarn";
+	if (ua.startsWith("pnpm")) return "pnpm";
+	return "bun";
+}
+/** 静默执行命令探测其是否可用（如 git --version），失败即视为不可用 */
+function supports(command) {
+	return spawnSync(command[0] ?? "", command.slice(1), { stdio: "ignore" }).status === 0;
+}
+/** 读 git 全局配置单项（读不到 → 空串） */
+function gitConfig(key) {
+	const res = spawnSync("git", [
+		"config",
+		"--get",
+		key
+	], { encoding: "utf8" });
+	return res.status === 0 ? res.stdout?.trim() ?? "" : "";
+}
+/**
+* 获取项目名：优先取第一个位置参数，否则交互式询问（默认 koishi-app）。
+* 用户取消或输入为空时直接退出（不强行兜底默认值）。
+*/
+async function getName() {
+	if (argv._[0]) return `${argv._[0]}`;
+	const trimmed = (await prompts({
+		type: "text",
+		name: "name",
+		message: "项目名：",
+		initial: "koishi-app"
+	})).name?.trim();
+	if (!trimmed) process.exit(0);
+	return trimmed;
+}
+/** 递归清空目录内容（目录本身保留）。 */
+function emptyDir(root) {
+	for (const file of readdirSync(root)) rmSync(join(root, file), {
+		recursive: true,
+		force: true
+	});
+}
+/** 交互式确认框：返回用户是否选择了「是」（取消视为否） */
+async function confirm(message) {
+	return (await prompts({
+		type: "confirm",
+		name: "yes",
+		initial: true,
+		message
+	})).yes === true;
+}
+/**
+* 准备目标目录：不存在则创建；已存在且非空时，未指定 --forced / --yes
+* 会先提示目录非空并询问是否清空后继续，用户拒绝则直接退出。
+*/
+async function prepare() {
+	if (!existsSync(rootDir)) {
+		mkdirSync(rootDir, { recursive: true });
+		return;
+	}
+	if (!readdirSync(rootDir).length) return;
+	if (!argv.forced && !argv.yes) {
+		console.log(kleur.yellow(`  目标目录 "${project}" 非空。`));
+		if (!await confirm("清空现有文件并继续？")) process.exit(0);
+	}
+	emptyDir(rootDir);
+}
+/**
+* 改写模板的 package.json（纯函数，导出供单测）：替换项目名、标记
+* private、版本归零。
+*/
+function renderManifest(source, project, prod) {
+	const meta = { ...source };
+	meta["name"] = project;
+	meta["private"] = true;
+	meta["version"] = "0.0.0";
+	if (prod) {
+		delete meta["workspaces"];
+		delete meta["devDependencies"];
+	}
+	return `${JSON.stringify(meta, null, 2)}\n`;
+}
+/** 把改写结果写回生成项目的 package.json */
+function writePackageJson() {
+	const filename = join(rootDir, "package.json");
+	const meta = JSON.parse(readFileSync(filename, "utf8"));
+	writeFileSync(filename, renderManifest(meta, project, argv.prod === true));
+}
+/**
+* 模板下载与解包的主流程：
+* 1. 确定 npm registry（--registry 参数 > 本机 npm 配置 > 官方源）；
+* 2. 拉取模板包元数据，按 dist-tags 解析目标版本（--ref，默认 latest）；
+* 3. 流式下载 tarball 并解包到目标目录（strip: 1 去掉包根目录层级），
+*    网络错误统一以 HttpError 提示后退出；
+* 4. 最后改写 package.json。
+*/
+async function scaffold() {
+	console.log(kleur.dim("  正在 ") + project + kleur.dim(" 中生成项目 ..."));
+	const registry = (argv.registry || await getRegistry() || "https://registry.npmjs.org").replace(/\/$/, "");
+	console.log(kleur.dim(`  使用 registry：${registry}\n`));
+	const template = argv.template || "@koishijs/boilerplate";
+	const ref = argv.ref || "latest";
+	try {
+		const metaRes = await fetch(`${registry}/${template}`);
+		if (!metaRes.ok) throw new HttpError(metaRes.status, metaRes.statusText);
+		const remote = await metaRes.json();
+		const version = remote["dist-tags"][ref];
+		const url = version === void 0 ? void 0 : remote.versions[version]?.dist?.tarball;
+		if (url === void 0) throw new HttpError(404, `模板 ${template}@${ref} 不存在`);
+		const tarballRes = await fetch(url);
+		const body = tarballRes.body;
+		if (!tarballRes.ok || !body) throw new HttpError(tarballRes.status, tarballRes.statusText);
+		await new Promise((resolve, reject) => {
+			Readable.fromWeb(body).pipe(extract({
+				cwd: rootDir,
+				newer: true,
+				strip: 1
+			})).on("finish", resolve).on("error", reject);
+		});
+	} catch (err) {
+		if (!(err instanceof HttpError)) throw err;
+		console.log(`${kleur.red("error")} 请求失败：HTTP ${err.status} ${err.statusText}`);
+		process.exit(1);
+	}
+	writePackageJson();
+	console.log(kleur.green("  完成。\n"));
+}
+/**
+* 初始化 git 仓库：仅在显式传入 --git 且本机装有 git 时执行，分支名取
+* git 的 init.defaultBranch（未配置则 main）。
+*/
+async function initGit() {
+	if (!argv.git || !supports(["git", "--version"])) return;
+	const branch = gitConfig("init.defaultBranch") || "main";
+	spawnSync("git", [
+		"init",
+		"-b",
+		branch
+	], {
+		stdio: "ignore",
+		cwd: rootDir
+	});
+	console.log(kleur.green(`  已初始化 git 仓库（分支 ${branch}）。\n`));
+}
+/**
+* 收尾交互：询问是否立即安装依赖并启动，包管理器由 detectAgent()
+* Bun-first 探测；用户拒绝时打印后续手动安装与启动的命令。
+*/
+async function install() {
+	if (argv.yes) return;
+	const agent = detectAgent();
+	const startArgs = agent === "yarn" ? ["start"] : ["run", "start"];
+	if (await confirm("现在安装依赖并启动吗？")) {
+		if (spawnSync(agent, ["install"], {
+			stdio: "inherit",
+			cwd: rootDir
+		}).status !== 0) {
+			console.log(kleur.red("  依赖安装失败，请检查上方日志。"));
+			return;
+		}
+		spawnSync(agent, startArgs, {
+			stdio: "inherit",
+			cwd: rootDir
+		});
+	} else {
+		console.log(kleur.dim("  稍后可以这样启动：\n"));
+		if (rootDir !== cwd) {
+			const related = relative(cwd, rootDir);
+			console.log(kleur.blue(`  cd ${kleur.bold(related)}`));
+		}
+		console.log(kleur.blue(`  ${agent === "yarn" ? "yarn" : `${agent} install`}`));
+		console.log(kleur.blue(`  ${agent === "yarn" ? "yarn" : `${agent} run`} start`));
+		console.log();
+	}
+}
+/**
+* CLI 主流程：--help 打印用法后即返回；否则依次执行
+* 项目名询问 → prepare（目录准备）→ scaffold（模板解包）→ initGit → install。
+*/
+async function start() {
+	if (argv.help) {
+		console.log(`
+  用法：create-koishi-ce [名称] [选项]
+
+  选项：
+    -t, --template <名称>   模板包名（默认 @koishijs/boilerplate）
+    -r, --ref <引用>        模板版本引用（默认 latest）
+    -f, --forced            强制清空目标目录
+    -g, --git               初始化 git 仓库
+        --registry <地址>   指定 npm registry（如 https://registry.npmmirror.com）
+    -p, --prod              生产模式（移除 devDependencies 与 workspaces）
+    -y, --yes               跳过全部询问
+    -h, --help              显示本帮助
+`);
+		return;
+	}
+	console.log();
+	console.log(`  ${kleur.bold("Create Koishi")}  ${kleur.blue(`v${version}`)}`);
+	console.log();
+	const name = await getName();
+	rootDir = join(cwd, name);
+	project = basename(rootDir);
+	await prepare();
+	await scaffold();
+	await initGit();
+	await install();
+}
+//#endregion
+export { renderManifest as n, start as r, detectAgent as t };

package/package.json

@@ -0,0 +1,65 @@
+{
+	"name": "create-koishi-ce",
+	"description": "Setup a Koishi application",
+	"version": "1.0.0",
+	"type": "module",
+	"main": "./lib/index.mjs",
+	"module": "./lib/index.mjs",
+	"types": "./lib/index.d.ts",
+	"bin": {
+		"create-koishi-ce": "./lib/bin.mjs"
+	},
+	"files": [
+		"lib",
+		"src"
+	],
+	"contributors": [
+		"Shigma <shigma10826@gmail.com>",
+		"Oppenheymu <oppenheymu@gmail.com>"
+	],
+	"license": "MIT",
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/Koishi-CE/koishi.git",
+		"directory": "apps/koishi-create"
+	},
+	"bugs": {
+		"url": "https://github.com/Koishi-CE/koishi/issues"
+	},
+	"homepage": "https://koishi.chat",
+	"scripts": {
+		"build": "tsdown"
+	},
+	"keywords": [
+		"bot",
+		"chatbot",
+		"koishi",
+		"discord",
+		"telegram",
+		"create",
+		"scaffold",
+		"template",
+		"generator",
+		"boilerplate"
+	],
+	"devDependencies": {
+		"@types/prompts": "^2.4.9",
+		"@types/yargs-parser": "^21.0.3"
+	},
+	"dependencies": {
+		"get-registry": "^1.1.0",
+		"kleur": "^4.1.5",
+		"prompts": "^2.4.2",
+		"tar": "^7.5.22",
+		"yargs-parser": "^22.0.0"
+	},
+	"exports": {
+		".": {
+			"source": "./src/index.ts",
+			"types": "./lib/index.d.ts",
+			"import": "./lib/index.mjs",
+			"default": "./lib/index.mjs"
+		},
+		"./package.json": "./package.json"
+	}
+}

package/src/__tests__/manifest.test.ts

@@ -0,0 +1,44 @@
+import { expect, test } from "bun:test";
+import { detectAgent, type Manifest, renderManifest } from "../index.ts";
+
+test("renderManifest 基础改写：替换项目名、标记 private、版本归零", () => {
+	const source: Manifest = {
+		name: "@koishijs/boilerplate",
+		version: "1.0.0",
+		workspaces: ["koishi-app/*"],
+		scripts: { start: "koishi start" },
+	};
+	const output = JSON.parse(renderManifest(source, "my-app", false));
+	expect(output.name).toBe("my-app");
+	expect(output.private).toBe(true);
+	expect(output.version).toBe("0.0.0");
+	// 未触碰的字段原样保留
+	expect(output.scripts).toEqual({ start: "koishi start" });
+	expect(output.workspaces).toEqual(["koishi-app/*"]);
+	// 与模板一致的两空格缩进 + 结尾换行
+	expect(renderManifest(source, "my-app", false).endsWith("}\n")).toBe(true);
+});
+
+test("renderManifest prod 模式：删除 workspaces 与 devDependencies", () => {
+	const source: Manifest = {
+		name: "@koishijs/boilerplate",
+		workspaces: ["koishi-app/*"],
+		devDependencies: { koishi: "^4.18.11" },
+	};
+	const output = JSON.parse(renderManifest(source, "my-app", true));
+	expect(output.name).toBe("my-app");
+	expect("workspaces" in output).toBe(false);
+	expect("devDependencies" in output).toBe(false);
+});
+
+test("detectAgent：yarn / pnpm 跟随探测，其余一律 bun", () => {
+	const key = "npm_config_user_agent";
+	process.env[key] = "npm/10.9.2 node/v22.14.0 x64 workspaces/false";
+	expect(detectAgent()).toBe("bun");
+	process.env[key] = "yarn/1.22.22 npm/? node/v22.14.0 x64";
+	expect(detectAgent()).toBe("yarn");
+	process.env[key] = "pnpm/10.12.1 npm/? node/v22.14.0 x64";
+	expect(detectAgent()).toBe("pnpm");
+	delete process.env[key];
+	expect(detectAgent()).toBe("bun");
+});

package/src/bin.ts

@@ -0,0 +1,11 @@
+#!/usr/bin/env bun
+/**
+ * create-koishi-ce 的 CLI 可执行入口：shebang 由 rolldown 原样保留到
+ * lib/bin.mjs，package.json 的 bin 字段指向它（范式同 @koishi-ce/scripts）。
+ */
+import { start } from "./index.ts";
+
+start().catch((err) => {
+	console.error(err);
+	process.exitCode = 1;
+});

package/src/index.ts

@@ -0,0 +1,349 @@
+/**
+ * create-koishi-ce 脚手架（npm 包名 create-koishi-ce，目录名为
+ * apps/koishi-create，二者不一致是历史遗留，以目录名为准）。
+ *
+ * 通过 `bunx create-koishi-ce [name]`（npx 亦可）交互式创建 Koishi 机器人
+ * 应用项目：确定项目名 → 准备目标目录 → 从 npm registry 下载模板包（默认
+ * @koishijs/boilerplate，刻意沿用上游官方模板以保持与上游插件生态一致）
+ * 并解包 → 改写 package.json → 按需初始化 git → 询问是否立即安装依赖并
+ * 启动。CLI 可执行入口在 src/bin.ts（构建产物 lib/bin.mjs，bin 字段指向
+ * 它）；本文件只承载主流程与可单测的纯函数（范式对齐 @koishi-ce/scripts）。
+ */
+import { spawnSync } from "node:child_process";
+import {
+	existsSync,
+	mkdirSync,
+	readdirSync,
+	readFileSync,
+	rmSync,
+	writeFileSync,
+} from "node:fs";
+import { basename, join, relative } from "node:path";
+import { Readable } from "node:stream";
+import type { ReadableStream as NodeWebReadableStream } from "node:stream/web";
+import getRegistry from "get-registry";
+import kleur from "kleur";
+import prompts from "prompts";
+import { extract } from "tar";
+import parse from "yargs-parser";
+import pkg from "../package.json" with { type: "json" };
+
+const { version } = pkg;
+
+/** CLI 参数（yargs-parser 解析，别名映射见 bin 帮助文本） */
+interface Args {
+	_: Array<string | number>;
+	registry?: string;
+	ref?: string;
+	forced?: boolean;
+	git?: boolean;
+	prod?: boolean;
+	template?: string;
+	yes?: boolean;
+	help?: boolean;
+}
+
+/**
+ * 模板项目的 package.json（改写目标）：只需要类型化本流程触碰的字段，
+ * 其余字段经 index signature 原样保留。
+ */
+export interface Manifest {
+	name?: string;
+	private?: boolean;
+	version?: string;
+	workspaces?: unknown;
+	devDependencies?: unknown;
+	[key: string]: unknown;
+}
+
+/** registry 包元数据中本流程消费的字段 */
+interface RegistryMeta {
+	"dist-tags": Record<string, string>;
+	versions: Record<string, { dist?: { tarball?: string } }>;
+}
+
+/** fetch 请求非 2xx 时抛出的错误，携带 HTTP 状态码与状态文本 */
+class HttpError extends Error {
+	status: number;
+	statusText: string;
+	constructor(status: number, statusText: string) {
+		super(`HTTP ${status} ${statusText}`);
+		this.status = status;
+		this.statusText = statusText;
+	}
+}
+
+// 命令行参数（顶层解析；无副作用，单测导入本文件不会触发主流程）
+const argv = parse(process.argv.slice(2), {
+	alias: {
+		ref: ["r"],
+		forced: ["f"],
+		git: ["g"],
+		prod: ["p"],
+		template: ["t"],
+		yes: ["y"],
+		help: ["h"],
+	},
+}) as Args;
+
+/** 项目目录名（rootDir 的最后一段，写入生成项目的 package.json 的 name） */
+let project: string;
+/** 目标目录的绝对路径（由用户输入的项目名拼接 cwd 得到） */
+let rootDir: string;
+
+// 执行脚手架时所在的工作目录，作为项目目录的基准
+const cwd = process.cwd();
+
+/**
+ * 探测后续安装/启动使用的包管理器（Bun-first）：yarn / pnpm 用户跟随其
+ * 生态习惯；其余场景（npm、bun 及探测不到 user-agent）一律走 bun——
+ * 本 CLI 自身以 bun 为运行时（bin shebang），能执行即已具备 bun 环境。
+ */
+export function detectAgent(): string {
+	const ua = process.env["npm_config_user_agent"] ?? "";
+	if (ua.startsWith("yarn")) return "yarn";
+	if (ua.startsWith("pnpm")) return "pnpm";
+	return "bun";
+}
+
+/** 静默执行命令探测其是否可用（如 git --version），失败即视为不可用 */
+function supports(command: readonly string[]) {
+	return (
+		spawnSync(command[0] ?? "", command.slice(1), { stdio: "ignore" })
+			.status === 0
+	);
+}
+
+/** 读 git 全局配置单项（读不到 → 空串） */
+function gitConfig(key: string): string {
+	const res = spawnSync("git", ["config", "--get", key], { encoding: "utf8" });
+	return res.status === 0 ? (res.stdout?.trim() ?? "") : "";
+}
+
+/**
+ * 获取项目名：优先取第一个位置参数，否则交互式询问（默认 koishi-app）。
+ * 用户取消或输入为空时直接退出（不强行兜底默认值）。
+ */
+async function getName(): Promise<string> {
+	if (argv._[0]) return `${argv._[0]}`;
+	const answer = (await prompts({
+		type: "text",
+		name: "name",
+		message: "项目名：",
+		initial: "koishi-app",
+	})) as { name?: string };
+	const trimmed = answer.name?.trim();
+	if (!trimmed) process.exit(0);
+	return trimmed;
+}
+
+/** 递归清空目录内容（目录本身保留）。 */
+function emptyDir(root: string) {
+	for (const file of readdirSync(root)) {
+		rmSync(join(root, file), { recursive: true, force: true });
+	}
+}
+
+/** 交互式确认框：返回用户是否选择了「是」（取消视为否） */
+async function confirm(message: string) {
+	const answer = (await prompts({
+		type: "confirm",
+		name: "yes",
+		initial: true,
+		message,
+	})) as { yes?: boolean };
+	return answer.yes === true;
+}
+
+/**
+ * 准备目标目录：不存在则创建；已存在且非空时，未指定 --forced / --yes
+ * 会先提示目录非空并询问是否清空后继续，用户拒绝则直接退出。
+ */
+async function prepare() {
+	if (!existsSync(rootDir)) {
+		mkdirSync(rootDir, { recursive: true });
+		return;
+	}
+
+	const files = readdirSync(rootDir);
+	if (!files.length) return;
+
+	if (!argv.forced && !argv.yes) {
+		console.log(kleur.yellow(`  目标目录 "${project}" 非空。`));
+		const yes = await confirm("清空现有文件并继续？");
+		if (!yes) process.exit(0);
+	}
+
+	emptyDir(rootDir);
+}
+
+/**
+ * 改写模板的 package.json（纯函数，导出供单测）：替换项目名、标记
+ * private、版本归零。
+ */
+export function renderManifest(
+	source: Manifest,
+	project: string,
+	prod: boolean,
+): string {
+	const meta: Manifest = { ...source };
+	meta["name"] = project;
+	meta["private"] = true;
+	meta["version"] = "0.0.0";
+	if (prod) {
+		// https://github.com/koishijs/koishi/issues/994
+		// 生产模式不借助 NODE_ENV 或 --production 标志，
+		// 而是直接删掉 devDependencies 与 workspaces 字段。
+		delete meta["workspaces"];
+		delete meta["devDependencies"];
+	}
+	return `${JSON.stringify(meta, null, 2)}\n`;
+}
+
+/** 把改写结果写回生成项目的 package.json */
+function writePackageJson() {
+	const filename = join(rootDir, "package.json");
+	const meta = JSON.parse(readFileSync(filename, "utf8")) as Manifest;
+	writeFileSync(filename, renderManifest(meta, project, argv.prod === true));
+}
+
+/**
+ * 模板下载与解包的主流程：
+ * 1. 确定 npm registry（--registry 参数 > 本机 npm 配置 > 官方源）；
+ * 2. 拉取模板包元数据，按 dist-tags 解析目标版本（--ref，默认 latest）；
+ * 3. 流式下载 tarball 并解包到目标目录（strip: 1 去掉包根目录层级），
+ *    网络错误统一以 HttpError 提示后退出；
+ * 4. 最后改写 package.json。
+ */
+async function scaffold() {
+	console.log(kleur.dim("  正在 ") + project + kleur.dim(" 中生成项目 ..."));
+
+	const registry = (
+		argv.registry ||
+		(await getRegistry()) ||
+		"https://registry.npmjs.org"
+	).replace(/\/$/, "");
+	console.log(kleur.dim(`  使用 registry：${registry}\n`));
+	const template = argv.template || "@koishijs/boilerplate";
+	const ref = argv.ref || "latest";
+
+	try {
+		const metaRes = await fetch(`${registry}/${template}`);
+		if (!metaRes.ok) throw new HttpError(metaRes.status, metaRes.statusText);
+		const remote = (await metaRes.json()) as RegistryMeta;
+		const version = remote["dist-tags"][ref];
+		const url =
+			version === undefined
+				? undefined
+				: remote.versions[version]?.dist?.tarball;
+		if (url === undefined) {
+			throw new HttpError(404, `模板 ${template}@${ref} 不存在`);
+		}
+		const tarballRes = await fetch(url);
+		const body = tarballRes.body;
+		if (!tarballRes.ok || !body) {
+			throw new HttpError(tarballRes.status, tarballRes.statusText);
+		}
+
+		await new Promise<void>((resolve, reject) => {
+			Readable.fromWeb(body as unknown as NodeWebReadableStream)
+				.pipe(extract({ cwd: rootDir, newer: true, strip: 1 }))
+				.on("finish", resolve)
+				.on("error", reject);
+		});
+	} catch (err) {
+		if (!(err instanceof HttpError)) throw err;
+		console.log(
+			`${kleur.red("error")} 请求失败：HTTP ${err.status} ${err.statusText}`,
+		);
+		process.exit(1);
+	}
+
+	writePackageJson();
+
+	console.log(kleur.green("  完成。\n"));
+}
+
+/**
+ * 初始化 git 仓库：仅在显式传入 --git 且本机装有 git 时执行，分支名取
+ * git 的 init.defaultBranch（未配置则 main）。
+ */
+async function initGit() {
+	if (!argv.git || !supports(["git", "--version"])) return;
+	const branch = gitConfig("init.defaultBranch") || "main";
+	spawnSync("git", ["init", "-b", branch], { stdio: "ignore", cwd: rootDir });
+	console.log(kleur.green(`  已初始化 git 仓库（分支 ${branch}）。\n`));
+}
+
+/**
+ * 收尾交互：询问是否立即安装依赖并启动，包管理器由 detectAgent()
+ * Bun-first 探测；用户拒绝时打印后续手动安装与启动的命令。
+ */
+async function install() {
+	// 指定 -y 时跳过依赖安装（供 CI 等需要静默生成的场景）
+	if (argv.yes) return;
+
+	const agent = detectAgent();
+	const startArgs = agent === "yarn" ? ["start"] : ["run", "start"];
+	const yes = await confirm("现在安装依赖并启动吗？");
+	if (yes) {
+		const installed = spawnSync(agent, ["install"], {
+			stdio: "inherit",
+			cwd: rootDir,
+		});
+		if (installed.status !== 0) {
+			console.log(kleur.red("  依赖安装失败，请检查上方日志。"));
+			return;
+		}
+		spawnSync(agent, startArgs, { stdio: "inherit", cwd: rootDir });
+	} else {
+		console.log(kleur.dim("  稍后可以这样启动：\n"));
+		if (rootDir !== cwd) {
+			const related = relative(cwd, rootDir);
+			console.log(kleur.blue(`  cd ${kleur.bold(related)}`));
+		}
+		console.log(
+			kleur.blue(`  ${agent === "yarn" ? "yarn" : `${agent} install`}`),
+		);
+		console.log(
+			kleur.blue(`  ${agent === "yarn" ? "yarn" : `${agent} run`} start`),
+		);
+		console.log();
+	}
+}
+
+/**
+ * CLI 主流程：--help 打印用法后即返回；否则依次执行
+ * 项目名询问 → prepare（目录准备）→ scaffold（模板解包）→ initGit → install。
+ */
+export async function start() {
+	if (argv.help) {
+		console.log(`
+  用法：create-koishi-ce [名称] [选项]
+
+  选项：
+    -t, --template <名称>   模板包名（默认 @koishijs/boilerplate）
+    -r, --ref <引用>        模板版本引用（默认 latest）
+    -f, --forced            强制清空目标目录
+    -g, --git               初始化 git 仓库
+        --registry <地址>   指定 npm registry（如 https://registry.npmmirror.com）
+    -p, --prod              生产模式（移除 devDependencies 与 workspaces）
+    -y, --yes               跳过全部询问
+    -h, --help              显示本帮助
+`);
+		return;
+	}
+
+	console.log();
+	console.log(`  ${kleur.bold("Create Koishi")}  ${kleur.blue(`v${version}`)}`);
+	console.log();
+
+	const name = await getName();
+	rootDir = join(cwd, name);
+	project = basename(rootDir);
+
+	await prepare();
+	await scaffold();
+	await initGit();
+	await install();
+}