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

package/README.md

@@ -1,3 +1,89 @@
-# Temporary Holding Version
+# @niping9542/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/admin-template](https://github.com/npora/admin-template)，默认 `main`，核心源码只维护一份。
+
+## 选择模板
+
+```sh
+npx @niping9542/create-nova-admin@latest
+```
+
+按提示输入项目名并选择：
+
+| 预设              | 内容                                                                                      |
+| ----------------- | ----------------------------------------------------------------------------------------- |
+| `starter`（默认） | 纯净后台，保留登录、布局、用户/部门/角色/菜单管理、权限、公共组件、多语言、主题和正式 SQL |
+| `worker`          | 纯净后台 + 独立 Worker 后端源码与 SQLite 迁移，后端菜单只引用核心页面                     |
+| `demo`            | 完整演示首页与示例页面、测试后端和展示站实现                                              |
+
+默认纯净版不生成 `examples/`、`workers/`、`deploy/`，也不保留相关依赖、构建插件和命令。Worker 版只额外生成后端，无需手动删除示例目录。完整演示需要网络访问测试 API，不使用本地 Mock。
+
+明确指定模板：
+
+```sh
+npx @niping9542/create-nova-admin@latest my-admin --preset starter
+npx @niping9542/create-nova-admin@latest my-worker --preset worker
+npx @niping9542/create-nova-admin@latest my-demo --preset demo
+```
+
+原 `--demo` 兼容为 `--preset demo`，不能与其他预设同时指定。`--yes` 或非交互终端不询问模板，默认 `starter`。
+
+## 启动
+
+需要 Node.js 22.12+（后端检查需 22.13+），使用生成项目 `packageManager` 指定版本的 pnpm。
+
+```sh
+cd my-admin
+pnpm install
+pnpm dev
+```
+
+纯净版与 Worker 版默认代理到 `http://localhost:8080`，先启动自己的后端，或在生成时使用 `--api-url https://api.example.com`，之后也可修改 `.env.development.local`。Worker 版先完成迁移、密钥和账号初始化，见生成的后端说明；生成器不自动创建资源、执行 SQL 或部署。
+
+完整演示无自定义 API 时使用生成器打印的 `pnpm dev:demo`；指定 `--api-url` 后使用 `pnpm dev`。API 前缀默认 `/api`，开发代理移除该前缀再转发。生产需要站点 API 转发，响应格式可在 `src/api/protocol/` 适配。
+
+[完整展示网站](https://admin-demo.npora.workers.dev)：账号 `admin`，密码 `123456`。此账号只用于展示站。
+
+## 目录与 SQL
+
+| 目录                   | 用途                                   |
+| ---------------------- | -------------------------------------- |
+| `src/`                 | 核心后台与权限管理                     |
+| `database/mysql/`      | 所有预设始终保留的正式表结构与基础授权 |
+| `public/`、`build/`    | 静态资源与公共构建配置                 |
+| `scripts/`、`tests/`   | 验证命令与回归测试                     |
+| `docs/`                | 与所选预设匹配的使用和接口说明         |
+| `workers/api/`         | Worker 与 demo 预设的独立后端          |
+| `examples/`、`deploy/` | 仅完整演示预设包含                     |
+
+在空 MySQL 数据库依次导入 `database/mysql/01-schema.sql`、`02-seed.sql`。正式 SQL 不包含测试账号，管理员及密码哈希由自己的后端初始化，与 Worker SQLite 迁移分开使用。
+
+## 选项
+
+| 选项                         | 用途                                            |
+| ---------------------------- | ----------------------------------------------- |
+| `[project-name]`             | 小写单级项目名，不接受路径                      |
+| `-y, --yes`                  | 无交互，缺省名称 `nova-admin-app`、缺省纯净版   |
+| `--preset <preset>`          | `starter`、`worker`、`demo`                     |
+| `--demo`                     | `--preset demo` 的快捷方式                      |
+| `--api-url <url>`            | HTTP/HTTPS 后端，不包含账号密码、查询参数或片段 |
+| `--ref <ref>`                | 模板分支/标签，须支持当前预设目录结构           |
+| `--template-dir <directory>` | 使用本地模板，不下载仓库                        |
+| `--version`、`--help`        | 版本和帮助                                      |
+
+目标已存在则失败，不覆盖已有内容。模板先在临时目录准备、校验再生成；失败清理本次创建的目录。本机配置、密钥、依赖、符号链接、构建缓存和 Git 历史不会复制。生成器不自动安装项目依赖或启动服务。
+
+## 维护
+
+```sh
+npm ci
+npm run check
+npm pack --dry-run
+node bin/index.js local-admin --yes --preset starter --template-dir ../admin-template
+```
+
+npm 包只包含生成器和说明；模板创建时获取。根模板的 `scaffold/` 保存少量差异文件，不进入生成结果。依赖变更后由模板维护者执行 `pnpm run update:presets`，防止纯净锁文件过期。
+
+模板仓库与 CLI 需配套提交和发布；本地修改不会更新已经发布的 npm 包。新预设选项需要在生成器新版发布后才可通过 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.4",
+  "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;
+}