@niping9542/create-nova-admin 0.0.0-stage → 1.0.5

package/README.md

@@ -1,3 +1,263 @@
-# Temporary Holding Version
+# Create Nova Admin
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+使用命令行创建 Vue 3 + TypeScript + Element Plus + Pinia 后台管理项目，请求使用 `@npora/request`，多语言使用 Vue I18n，并同步 Element Plus、Day.js 与页面日期格式。
+
+npm 包名：`@niping9542/create-nova-admin`；[生成器源码](https://github.com/ni9542/create-nova-admin)。生成器从 [Npora Admin Template](https://github.com/npora/admin-template) 获取模板，默认使用 `main` 分支，按所选预设生成项目文件。
+
+## 在线演示
+
+[打开 Npora Admin 展示网站](https://admin-demo.npora.workers.dev)
+
+| 账号    | 密码     |
+| ------- | -------- |
+| `admin` | `123456` |
+
+以上账号仅用于在线演示和默认测试 API。纯净版、自己部署的后端和正式 SQL 不会自动获得这个账号。
+
+## 环境要求
+
+- 创建项目和开发前端：Node.js 22.12.0 或更高版本。
+- 检查 Worker 后端：Node.js 22.13.0 或更高版本。
+- 生成项目后，使用其 `package.json` 中 `packageManager` 指定的 pnpm 版本。
+- 在线创建需要能够访问 npm 和 GitHub；完整演示的默认测试 API 也需要网络。
+
+## 创建项目
+
+### 交互选择
+
+```sh
+npx @niping9542/create-nova-admin@latest
+```
+
+按提示输入项目名，选择模板。直接回车使用默认纯净版：
+
+```text
+选择模板：
+  1. 纯净后台（默认）
+  2. 后台 + Worker 后端
+  3. 完整演示
+```
+
+### 三个模板的区别
+
+| 内容                             | `starter` 纯净版 | `worker` 后端版 | `demo` 完整演示 |
+| -------------------------------- | ---------------- | --------------- | --------------- |
+| 登录页、后台布局、导航与标签页   | 保留             | 保留            | 保留            |
+| 首页                             | 核心首页         | 核心首页        | 美化演示首页    |
+| 用户、部门、角色、菜单及权限管理 | 保留             | 保留            | 保留            |
+| 个人中心、公共组件、主题和多语言 | 保留             | 保留            | 保留            |
+| 请求封装与前端 API 定义          | 保留             | 保留            | 保留            |
+| 正式 MySQL 权限 SQL              | 保留             | 保留            | 保留            |
+| Worker 后端源码与 SQLite 迁移    | 不生成           | 生成            | 生成            |
+| 表格、表单、下载、缓存等示例页面 | 不生成           | 不生成          | 生成            |
+| 展示站部署辅助                   | 不生成           | 不生成          | 生成            |
+
+**纯净版包含登录页和首页，也保留完整的核心后台功能。** 它不附带 Worker 后端、示例页面和展示站部署工具，相关依赖、插件和命令也不生成。
+
+所有预设使用真实 HTTP 请求，不附带本地 Mock。纯净版的登录流程、动态菜单和系统管理数据需要对接使用者自己的后端；Worker 版提供可独立部署的后端源码，但需要先初始化并运行后端。完整演示默认连接现有测试 API。
+
+### 创建纯净版
+
+```sh
+npx @niping9542/create-nova-admin@latest my-admin --preset starter
+cd my-admin
+pnpm install
+pnpm dev
+```
+
+开发地址默认 `http://localhost:3000`，端口被占用时以终端打印的地址为准。登录页面可以正常打开；完成真实登录并进入首页，需要可用的后端认证接口。
+
+### 创建 Worker 版
+
+```sh
+npx @niping9542/create-nova-admin@latest my-worker --preset worker
+cd my-worker
+pnpm install
+pnpm dev
+```
+
+该预设在纯净版基础上增加 `workers/api/`，后端菜单仅引用核心页面。按生成项目中的 `workers/api/README.md` 完成数据库迁移、密钥与账号初始化，并配置可访问的后端地址。
+
+`pnpm dev` 只启动前端，不会自动启动或部署 Worker。根目录的 `pnpm run check:backend` 用于检查后端构建与测试。
+
+### 创建完整演示
+
+```sh
+npx @niping9542/create-nova-admin@latest my-demo --preset demo
+cd my-demo
+pnpm install
+pnpm dev:demo
+```
+
+兼容快捷选项：
+
+```sh
+npx @niping9542/create-nova-admin@latest my-demo --demo
+```
+
+完整演示默认使用测试 API，可使用前面的演示账号。`--demo` 等同于 `--preset demo`，不能同时指定其他预设。
+
+## 接入自己的后端
+
+在创建时指定接口地址：
+
+```sh
+npx @niping9542/create-nova-admin@latest my-admin --preset starter --api-url https://api.example.com
+```
+
+也可以创建后修改生成项目中的 `.env.development.local`：
+
+```dotenv
+VITE_API_URL=https://api.example.com
+```
+
+修改后重启开发服务。默认 API 前缀为 `/api`，开发代理会移除该前缀后转发给后端。此地址只配置开发代理；生产环境需要由站点服务器将 `/api` 转发到实际后端。
+
+前端 API 定义位于生成项目的 `src/api/`，接口契约见其中的 `docs/api.md`；后端响应格式有差异时，集中调整 `src/api/protocol/`。
+
+完整演示指定自定义 API 后，生成器会写入接口地址并启用演示页面，此时使用打印的 `pnpm dev` 命令启动：
+
+```sh
+npx @niping9542/create-nova-admin@latest my-demo --preset demo --api-url https://api.example.com
+```
+
+## 生成项目的目录
+
+以下是创建后的后台项目目录，不是本生成器仓库的目录。
+
+| 目录              | 用途                                                       | 包含的预设       |
+| ----------------- | ---------------------------------------------------------- | ---------------- |
+| `src/`            | 登录、首页、布局、权限、系统管理、状态管理、请求与公共组件 | 全部             |
+| `public/`         | 网站图标等原样输出的静态资源                               | 全部             |
+| `build/`          | 公共构建配置和启动加载层                                   | 全部             |
+| `database/mysql/` | 正式权限表结构与基础授权 SQL                               | 全部             |
+| `scripts/`        | 所选预设需要的开发与检查工具                               | 全部             |
+| `tests/`          | 前端核心回归与测试辅助                                     | 全部             |
+| `docs/`           | 与所选预设匹配的目录、开发、接口和权限说明                 | 全部             |
+| `workers/api/`    | 独立后端源码、SQLite 迁移、初始化脚本及测试                | `worker`、`demo` |
+| `examples/`       | 演示首页、示例页面、统计 API 与示例测试                    | `demo`           |
+| `deploy/`         | 展示站部署辅助                                             | `demo`           |
+
+生成器按预设准备文件，使用者无需先删除 Worker 或演示目录。`node_modules/` 和 `dist/` 等安装、构建产物在本机生成，不随模板复制。
+
+### 正式权限 SQL
+
+所有预设都保留以下文件，在空 MySQL 数据库中按顺序导入：
+
+1. `database/mysql/01-schema.sql`：用户、部门、角色、菜单及关联表，包含索引与约束。
+2. `database/mysql/02-seed.sql`：基础部门、角色、系统管理菜单、按钮权限和授权关系。
+
+使用方法见生成项目的 `database/mysql/README.md`。正式 SQL 不包含演示账号，不替使用者选择密码哈希算法；管理员账号由实际后端初始化。Worker 使用独立的 SQLite 迁移，不能把 MySQL 脚本当作 Worker 迁移执行。
+
+### 常用命令
+
+在生成的后台项目根目录执行：
+
+| 命令                      | 用途                                   | 包含的预设       |
+| ------------------------- | -------------------------------------- | ---------------- |
+| `pnpm dev`                | 启动前端，按所选预设与本机配置加载页面 | 全部             |
+| `pnpm build`              | 类型检查并构建到 `dist/`               | 全部             |
+| `pnpm preview`            | 预览构建产物，API 转发仍需自行提供     | 全部             |
+| `pnpm run check`          | 格式、类型与核心回归检查               | 全部             |
+| `pnpm run check:backend`  | 后端构建与回归检查                     | `worker`、`demo` |
+| `pnpm dev:demo`           | 启动完整演示，默认连接测试 API         | `demo`           |
+| `pnpm build:demo`         | 类型检查并构建完整演示                 | `demo`           |
+| `pnpm run check:examples` | 示例页面与路由检查                     | `demo`           |
+| `pnpm run check:all`      | 完整演示仓库回归检查                   | `demo`           |
+
+## 命令行选项
+
+```sh
+npx @niping9542/create-nova-admin@latest --help
+```
+
+| 选项                         | 说明                                                                       |
+| ---------------------------- | -------------------------------------------------------------------------- |
+| `[project-name]`             | 当前目录下的单级项目名，使用小写字母、数字、连字符、下划线或点，不接受路径 |
+| `-y, --yes`                  | 无交互创建；未指定名称时使用 `nova-admin-app`，未指定预设时使用 `starter`  |
+| `--preset <preset>`          | 指定 `starter`、`worker` 或 `demo`                                         |
+| `--demo`                     | `--preset demo` 的快捷方式                                                 |
+| `--api-url <url>`            | 自定义 HTTP/HTTPS 后端地址，不接受账号密码、查询参数或片段                 |
+| `--ref <ref>`                | 模板分支或标签，默认 `main`；目标版本须支持当前预设结构                    |
+| `--template-dir <directory>` | 使用本地模板目录，跳过远程模板下载                                         |
+| `-V, --version`              | 显示生成器版本                                                             |
+| `-h, --help`                 | 显示帮助                                                                   |
+
+例如，无交互创建默认纯净版：
+
+```sh
+npx @niping9542/create-nova-admin@latest my-admin --yes
+```
+
+`--yes` 可以与 `--preset worker` 或 `--preset demo` 一起使用。非交互终端不会询问模板，未指定预设时使用纯净版；项目名仍须明确提供，或使用 `--yes` 采用默认名称。
+
+已存在的目标目录会导致创建失败，不会被覆盖。生成器不自动安装项目依赖、启动后端、执行 SQL 或部署网站，也不会复制模板中的 Git 历史、本机配置、密钥目录及符号链接。
+
+## 维护生成器
+
+以下操作在本仓库 `create-nova-admin` 中执行。
+
+### 本仓库结构
+
+| 路径                    | 用途                                               |
+| ----------------------- | -------------------------------------------------- |
+| `bin/index.js`          | CLI 入口，处理项目名称、模板选择、参数和提示       |
+| `src/create-project.js` | 模板获取、输入校验、本机配置写入及创建失败后的清理 |
+| `src/presets.js`        | 三种预设的文件组合、依赖快照校验及文档选择         |
+| `tests/`                | 参数、预设、目录保护和创建流程的回归测试           |
+| `package.json`          | npm 包信息、命令入口、依赖与发布文件清单           |
+| `package-lock.json`     | 生成器自身依赖的 npm 锁文件                        |
+| `README.md`             | GitHub 与 npm 展示的使用说明                       |
+
+npm 包只包含 CLI 入口、生成逻辑、包信息和本说明，不把后台模板源码打进 npm 包。模板在创建项目时获取。
+
+### 本机检查
+
+```sh
+npm ci
+npm run check
+npm pack --dry-run
+```
+
+如果后台模板和生成器放在同一父目录，可通过本地模板验证：
+
+```sh
+node bin/index.js local-admin --yes --preset starter --template-dir ../admin-template
+```
+
+本地模板也必须是包含当前预设差异文件的完整模板仓库。
+
+### 更新模板与发布
+
+- 只修改后台页面或公共组件时，提交并推送 `admin-template` 的模板分支；之后新创建的项目会获取对应分支内容，已经生成的项目不会自动更新。
+- 修改生成器逻辑或本仓库 README 后，需要发布新的 npm 版本，才能更新 npm 用户拿到的生成器及包说明。
+- 修改模板依赖或核心命令后，在 `admin-template` 执行 `pnpm run update:presets`，同步并提交纯净版依赖和锁文件快照。
+
+生成器采用手动发布。在本仓库执行：
+
+```sh
+npm version patch --no-git-tag-version
+npm run check
+npm pack --dry-run
+```
+
+将本次改动及同步更新的 `package.json`、`package-lock.json` 提交并推送 Git，确认 npm 登录账号具有发布权限后执行：
+
+```sh
+npm whoami --registry=https://registry.npmjs.org/
+npm publish --access public --registry=https://registry.npmjs.org/
+```
+
+如果登录失效，先执行 `npm login --auth-type=web --registry=https://registry.npmjs.org/`，按终端提示完成认证。
+
+发布后检查公开版本：
+
+```sh
+npm view @niping9542/create-nova-admin version dist-tags --json --registry=https://registry.npmjs.org/
+```
+
+发布命令提示仍在处理时，稍后再查询公开版本。Git 提交和推送不会自动发布 npm，已经发布的版本不能覆盖；重新发布修改后的内容需要递增版本号。
+
+## 许可证
+
+MIT

package/bin/index.js

@@ -0,0 +1,116 @@
+#!/usr/bin/env node
+
+import { Command } from 'commander';
+import { createInterface } from 'node:readline/promises';
+import { readFile } from 'node:fs/promises';
+import ora from 'ora';
+import chalk from 'chalk';
+import { createProject } from '../src/create-project.js';
+import { PRESETS, resolvePreset } from '../src/presets.js';
+
+const pkg = JSON.parse(
+  await readFile(new URL('../package.json', import.meta.url), 'utf8')
+);
+const program = new Command();
+
+program
+  .name('create-nova-admin')
+  .version(pkg.version)
+  .description('创建 Vue 3 + TypeScript + Element Plus + Pinia 后台项目')
+  .argument('[project-name]', '项目名称，例如 my-admin')
+  .option('-y, --yes', '无交互创建；未指定名称时使用 nova-admin-app')
+  .option('--preset <preset>', '模板：starter（默认）、worker、demo')
+  .option('--demo', '完整演示模板，等同 --preset demo')
+  .option('--api-url <url>', '配置自己的 HTTP 后端地址')
+  .option('--ref <ref>', '模板分支或标签', 'main')
+  .option('--template-dir <directory>', '从本地模板创建，供离线开发和验证')
+  .action(async (projectName, options) => {
+    let preset = options.preset;
+    if (!projectName && !options.yes && !process.stdin.isTTY)
+      throw new Error('请提供项目名称，或使用 --yes 采用默认名称。');
+    if (
+      process.stdin.isTTY &&
+      !options.yes &&
+      (!projectName || (!preset && !options.demo))
+    ) {
+      const prompt = createInterface({
+        input: process.stdin,
+        output: process.stdout
+      });
+      try {
+        if (!projectName)
+          projectName =
+            (await prompt.question('项目名称 (nova-admin-app): ')).trim() ||
+            'nova-admin-app';
+        if (!preset && !options.demo) {
+          console.log(
+            '选择模板：\n  1. 纯净后台（默认）\n  2. 后台 + Worker 后端\n  3. 完整演示'
+          );
+          while (!preset) {
+            const answer =
+              (await prompt.question('请选择 (1): ')).trim() || '1';
+            preset = {
+              1: 'starter',
+              2: 'worker',
+              3: 'demo',
+              starter: 'starter',
+              worker: 'worker',
+              demo: 'demo'
+            }[answer];
+            if (!preset) console.log('请输入 1、2、3 或模板名称。');
+          }
+        }
+      } finally {
+        prompt.close();
+      }
+    }
+    projectName ||= 'nova-admin-app';
+    preset = resolvePreset(preset, options.demo);
+    const spinner = ora(
+      options.templateDir ? '正在准备本地模板…' : '正在获取 Npora Admin 模板…'
+    ).start();
+    try {
+      const project = await createProject({
+        projectName,
+        ...options,
+        preset,
+        apiURL: options.apiUrl
+      });
+      spinner.succeed('项目已创建');
+      console.log(
+        chalk.green(
+          `\n${project.projectName} 初始化完成（${project.presetLabel}）。`
+        )
+      );
+      console.log(
+        `\n  cd ${project.projectName}\n  pnpm install\n  ${project.startCommand}\n`
+      );
+      console.log(`包管理器版本：${project.packageManager}`);
+      if (project.demo)
+        console.log('展示需要网络。演示账号：admin，密码：123456。');
+      else
+        console.log(
+          '请先启动自己的后端，或修改 .env.development.local 中的 VITE_API_URL。'
+        );
+      console.log('正式权限 SQL：database/mysql/01-schema.sql → 02-seed.sql。');
+      if (project.preset === 'worker')
+        console.log(
+          '后端源码：workers/api/；先迁移数据库并初始化账号，再配置自己的 API 地址。'
+        );
+      console.log(
+        `已生成${PRESETS[project.preset]}所需文件，无需手动删除演示目录。`
+      );
+    } catch (error) {
+      spinner.fail('项目创建失败');
+      throw error;
+    }
+  });
+
+try {
+  await program.parseAsync(process.argv);
+} catch (error) {
+  console.error(
+    chalk.red(error.message || '创建失败，请检查模板和网络后重试。')
+  );
+  process.exitCode = 1;
+}

package/package.json

@@ -1,6 +1,39 @@
 {
   "name": "@niping9542/create-nova-admin",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "1.0.5",
+  "description": "Npora Admin 后台脚手架生成器：核心模式、独立展示与正式权限 SQL",
+  "type": "module",
+  "bin": {
+    "create-nova-admin": "bin/index.js"
+  },
+  "keywords": [
+    "vue",
+    "admin",
+    "cli",
+    "scaffolding",
+    "nova"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "author": "niping9542",
+  "license": "MIT",
+  "dependencies": {
+    "chalk": "^5.3.0",
+    "commander": "^12.1.0",
+    "giget": "^3.3.0",
+    "ora": "^8.0.1"
+  },
+  "engines": {
+    "node": ">=22.12.0"
+  },
+  "scripts": {
+    "test": "node --test tests/cli.test.mjs tests/create-project.test.mjs",
+    "check": "node --check bin/index.js && node --check src/create-project.js && npm test"
+  },
+  "files": [
+    "bin/",
+    "src/",
+    "README.md"
+  ]
+}

package/src/create-project.js

@@ -0,0 +1,228 @@
+import {
+  cp,
+  lstat,
+  mkdir,
+  mkdtemp,
+  readFile,
+  rm,
+  writeFile
+} from 'node:fs/promises';
+import path from 'node:path';
+import { tmpdir } from 'node:os';
+import { downloadTemplate } from 'giget';
+import { composePreset, PRESETS, resolvePreset } from './presets.js';
+
+export const TEMPLATE_REPOSITORY = 'github:npora/admin-template';
+
+export function validateProjectName(name) {
+  if (
+    typeof name !== 'string' ||
+    name.length > 214 ||
+    !/^[a-z0-9][a-z0-9._-]*$/.test(name) ||
+    ['node_modules', 'favicon.ico'].includes(name) ||
+    /^(con|prn|aux|nul|com[1-9]|lpt[1-9])(?:\.|$)/i.test(name)
+  ) {
+    throw new Error(
+      '项目名请使用小写字母、数字、连字符、下划线或点，不能是路径或保留名称。'
+    );
+  }
+  return name;
+}
+
+export function normalizeApiURL(value) {
+  let url;
+  try {
+    url = new URL(value);
+  } catch {
+    throw new Error('后端地址必须是完整的 http:// 或 https:// URL。');
+  }
+  if (
+    !['http:', 'https:'].includes(url.protocol) ||
+    url.username ||
+    url.password ||
+    url.search ||
+    url.hash
+  ) {
+    throw new Error(
+      '后端地址只支持 HTTP/HTTPS，不能包含账号、密码、查询参数或片段。'
+    );
+  }
+  return url.toString().replace(/\/$/, '');
+}
+
+const excluded = new Set([
+  '.git',
+  '.agents',
+  '.codex',
+  '.aws',
+  '.idea',
+  'node_modules',
+  'dist',
+  'dist-ssr',
+  '.cloudflare',
+  '.wrangler',
+  'coverage',
+  '.pnpm-store',
+  '.DS_Store',
+  'report.html'
+]);
+
+async function copyTemplate(source, destination) {
+  await cp(source, destination, {
+    recursive: true,
+    force: false,
+    errorOnExist: true,
+    filter: async (entry) => {
+      const name = path.basename(entry);
+      return (
+        !excluded.has(name) &&
+        !name.endsWith('.local') &&
+        !name.endsWith('.log') &&
+        !(await lstat(entry)).isSymbolicLink()
+      );
+    }
+  });
+}
+
+async function validateTemplate(directory) {
+  const required = [
+    'src/main.ts',
+    'database/mysql/01-schema.sql',
+    'database/mysql/02-seed.sql',
+    'build/optional-examples.ts',
+    'scripts/demo.mjs',
+    'scaffold/metadata.json',
+    'scaffold/demo/README.md',
+    'scaffold/core/package.json',
+    'scaffold/core/pnpm-lock.yaml',
+    'scaffold/core/vite.config.ts',
+    'scaffold/core/src/router/extensions.ts',
+    'scaffold/worker/workers/api/src/config/pages.mjs',
+    'scaffold/worker/workers/api/migrations/0002_seed.sql'
+  ];
+  for (const file of required) {
+    try {
+      if (!(await lstat(path.join(directory, file))).isFile())
+        throw new Error();
+    } catch {
+      throw new Error(
+        `模板缺少 ${file}，请使用已完成核心/展示分离的新版本模板。`
+      );
+    }
+  }
+  const pkg = JSON.parse(
+    await readFile(path.join(directory, 'package.json'), 'utf8')
+  );
+  if (
+    !pkg.scripts?.dev ||
+    !pkg.scripts?.['dev:demo'] ||
+    !pkg.packageManager?.startsWith('pnpm@')
+  ) {
+    throw new Error('模板缺少当前 pnpm 开发或展示命令。');
+  }
+  return pkg;
+}
+
+export async function createProject({
+  projectName,
+  cwd = process.cwd(),
+  demo = false,
+  preset,
+  apiURL,
+  ref = 'main',
+  templateDir,
+  download = downloadTemplate
+}) {
+  validateProjectName(projectName);
+  const selected = resolvePreset(preset, demo);
+  demo = selected === 'demo';
+  if (
+    !/^[a-zA-Z0-9][a-zA-Z0-9._/-]*$/.test(ref) ||
+    ref.includes('..') ||
+    ref.includes('//') ||
+    ref.endsWith('/')
+  ) {
+    throw new Error('模板版本必须是有效的分支或标签名称。');
+  }
+  const backend = apiURL === undefined ? undefined : normalizeApiURL(apiURL);
+  const target = path.resolve(cwd, projectName);
+  try {
+    await lstat(target);
+    throw new Error(
+      `目录 ${projectName} 已存在，请换一个项目名；不会覆盖已有内容。`
+    );
+  } catch (error) {
+    if (error.code !== 'ENOENT') throw error;
+  }
+
+  const temporary = await mkdtemp(path.join(tmpdir(), 'create-nova-admin-'));
+  const prepared = path.join(temporary, 'prepared');
+  let created = false;
+  try {
+    if (templateDir) {
+      const source = path.resolve(cwd, templateDir);
+      if (!(await lstat(source)).isDirectory())
+        throw new Error('本地模板必须是目录。');
+      const relative = path.relative(source, temporary);
+      if (
+        !relative ||
+        (!relative.startsWith(`..${path.sep}`) &&
+          relative !== '..' &&
+          !path.isAbsolute(relative))
+      ) {
+        throw new Error('本地模板不能包含生成器的临时工作目录。');
+      }
+      await copyTemplate(source, prepared);
+    } else {
+      const downloaded = path.join(temporary, 'downloaded');
+      await download(`${TEMPLATE_REPOSITORY}#${ref}`, {
+        dir: downloaded,
+        force: false,
+        registry: false
+      });
+      await copyTemplate(downloaded, prepared);
+    }
+    const original = await validateTemplate(prepared);
+    const pkg = await composePreset(prepared, selected, original);
+    pkg.name = projectName;
+    pkg.private = true;
+    await writeFile(
+      path.join(prepared, 'package.json'),
+      `${JSON.stringify(pkg, null, 2)}\n`
+    );
+    const config = [
+      '# 此文件只用于本机开发，不提交版本控制。',
+      ...(demo ? ['VITE_DEMO_ENABLED=true'] : []),
+      ...(!demo || backend
+        ? [`VITE_API_URL=${backend || 'http://localhost:8080'}`]
+        : []),
+      ''
+    ].join('\n');
+    await writeFile(path.join(prepared, '.env.development.local'), config, {
+      mode: 0o600
+    });
+
+    // 独占创建目标：下载期间出现同名目录时也不覆盖。
+    await mkdir(target);
+    created = true;
+    await copyTemplate(prepared, target);
+    // 本机环境只由生成器写入，不从模板源继承。
+    await writeFile(path.join(target, '.env.development.local'), config, {
+      mode: 0o600
+    });
+    return {
+      directory: target,
+      projectName,
+      demo,
+      preset: selected,
+      presetLabel: PRESETS[selected],
+      startCommand: demo && !backend ? 'pnpm dev:demo' : 'pnpm dev',
+      packageManager: pkg.packageManager
+    };
+  } catch (error) {
+    if (created) await rm(target, { recursive: true, force: true });
+    throw error;
+  } finally {
+    await rm(temporary, { recursive: true, force: true });
+  }
+}

package/src/presets.js

@@ -0,0 +1,133 @@
+import { cp, readFile, readdir, rm, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+import { createHash } from 'node:crypto';
+
+export const PRESETS = {
+  starter: '纯净后台',
+  worker: '后台 + Worker 后端',
+  demo: '完整演示'
+};
+
+export function resolvePreset(preset, demo = false) {
+  const selected = preset ?? (demo ? 'demo' : 'starter');
+  if (!Object.hasOwn(PRESETS, selected))
+    throw new Error('模板仅支持 starter、worker、demo。');
+  if (demo && selected !== 'demo')
+    throw new Error('--demo 不能与其他 --preset 同时使用。');
+  return selected;
+}
+
+const removeCore = [
+  'examples',
+  'deploy',
+  'cloudflare.config.ts',
+  'tsconfig.demo.json',
+  'build/optional-examples.ts',
+  'src/types/examples.d.ts',
+  'scripts/demo.mjs',
+  'scripts/check-backend.mjs',
+  'scripts/check-standalone.mjs'
+];
+
+// Compose data files only; never execute scripts from a downloaded template.
+export async function composePreset(directory, preset, original) {
+  const overlays = path.join(directory, 'scaffold');
+  if (preset !== 'demo') {
+    const metadata = JSON.parse(
+      await readFile(path.join(overlays, 'metadata.json'), 'utf8')
+    );
+    const sourceLockHash = createHash('sha256')
+      .update(await readFile(path.join(directory, 'pnpm-lock.yaml')))
+      .digest('hex');
+    if (metadata.version !== 1 || metadata.sourceLockHash !== sourceLockHash)
+      throw new Error(
+        '模板的纯净版锁文件快照已过期，请维护者运行 pnpm run update:presets。'
+      );
+    const core = JSON.parse(
+      await readFile(path.join(overlays, 'core/package.json'), 'utf8')
+    );
+    const expected = { ...original.devDependencies };
+    delete expected['@cloudflare/vite-plugin'];
+    delete expected.cf;
+    const equal = (a, b) =>
+      JSON.stringify(Object.entries(a ?? {}).sort()) ===
+      JSON.stringify(Object.entries(b ?? {}).sort());
+    if (
+      !equal(core.dependencies, original.dependencies) ||
+      !equal(core.devDependencies, expected) ||
+      core.packageManager !== original.packageManager ||
+      Object.entries(core.scripts).some(
+        ([key, value]) => value !== original.scripts[key]
+      )
+    )
+      throw new Error(
+        '模板的纯净版依赖快照已过期，请维护者运行 pnpm run update:presets。'
+      );
+    for (const entry of removeCore)
+      await rm(path.join(directory, entry), { recursive: true, force: true });
+    if (preset === 'starter')
+      await rm(path.join(directory, 'workers'), {
+        recursive: true,
+        force: true
+      });
+    // Keep common contracts, replace repository-specific usage documentation.
+    for (const entry of await readdir(path.join(directory, 'docs'))) {
+      if (
+        !['api.md', 'rbac.md', 'i18n.md', 'deployment.md', 'database'].includes(
+          entry
+        )
+      )
+        await rm(path.join(directory, 'docs', entry), {
+          recursive: true,
+          force: true
+        });
+    }
+    await cp(path.join(overlays, 'core'), directory, {
+      recursive: true,
+      force: true
+    });
+    if (preset === 'worker') {
+      await cp(path.join(overlays, 'worker'), directory, {
+        recursive: true,
+        force: true
+      });
+      await rm(path.join(directory, 'workers/api/integration'), {
+        recursive: true,
+        force: true
+      });
+      core.scripts['check:backend'] =
+        'pnpm --dir workers/api run build && pnpm --dir workers/api test';
+      await writeFile(
+        path.join(directory, 'package.json'),
+        JSON.stringify(core, null, 2) + '\n'
+      );
+      await writeFile(
+        path.join(directory, 'README.md'),
+        '\n## 已选择 Worker 后端\n\n项目包含 `workers/api/`，使用前先完成数据库迁移和账号初始化，再配置自己的 API 地址。`pnpm run check:backend` 检查后端。见 [后端说明](workers/api/README.md)。\n',
+        { flag: 'a' }
+      );
+    }
+  }
+  if (preset === 'demo')
+    await cp(path.join(overlays, 'demo'), directory, {
+      recursive: true,
+      force: true
+    });
+  for (const entry of [
+    'scripts/update-presets.mjs',
+    'scripts/check-presets.mjs'
+  ]) {
+    await rm(path.join(directory, entry), { force: true });
+  }
+  await rm(overlays, { recursive: true, force: true });
+  const pkg = JSON.parse(
+    await readFile(path.join(directory, 'package.json'), 'utf8')
+  );
+  delete pkg.scripts['update:presets'];
+  delete pkg.scripts['check:presets'];
+  await writeFile(
+    path.join(directory, 'package.json'),
+    JSON.stringify(pkg, null, 2) + '\n'
+  );
+  return pkg;
+}