gridsum-vue3-pc 1.0.0

package/CHANGELOG.md

@@ -0,0 +1,19 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [1.0.0] - YYYY-MM-DD
+
+### Added
+- Initial release
+- CLI scaffolding tool with interactive and non-interactive modes
+- Base template with local login, user/role/permission management
+- SSO template with redirect-based authentication
+- CI/CD templates for GitHub Actions, GitLab CI, Jenkins
+- Docker build support
+- i18n (zh-CN / en) support
+- ESLint + Prettier + Stylelint + Commitlint code quality setup
+- Vitest + Playwright test setup

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 zhang.kun
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,88 @@
+# gridsum-vue3-pc
+
+快速生成基于 Vue3 + Vite + TypeScript 的企业级 PC 端项目
+
+## 功能特性
+
+- 🔧 CI/CD：GitHub Actions、GitLab CI、Jenkins
+- 🎯 代码规范：ESLint + Prettier + Stylelint + Commitlint
+- 🧪 测试：Vitest + Playwright
+- 🛡️ 类型安全：Zod 环境变量校验 + TypeScript 严格模式
+- 🐳 Docker 生产部署就绪
+- 🌐 国际化：中英文支持
+
+## 技术栈
+
+Vue 3.5 + Vite 5 + TypeScript 5.5 + Pinia + Vue Router 4 + Element Plus + Axios + Zod
+
+## 环境要求
+
+- Node.js >= 18
+
+## 快速开始
+
+```bash
+# npx 直接使用
+npx gridsum-vue3-pc
+
+# 或使用简写
+gsvue
+```
+
+## 命令行选项
+
+| 选项 | 说明 | 默认值 |
+|------|------|--------|
+| `--name <name>` | 项目名称 | vue3-project |
+| `--title <title>` | 项目标题 | Vue3 PC Template |
+| `--cicd <type>` | CI/CD 类型 (github / gitlab / jenkins) | 无 |
+| `--force` | 强制覆盖已存在目录 | false |
+| `--auto-start` | 创建后自动启动开发服务器 | false |
+| `--no-auto-install` | 跳过依赖安装 | false |
+| `--no-git` | 跳过 git 初始化 | false |
+
+## 项目结构
+
+```
+my-project/
+├── src/
+│   ├── assets/        # 静态资源
+│   ├── components/    # 公共组件
+│   ├── directives/    # 全局指令 (v-permission)
+│   ├── locales/       # 国际化
+│   ├── router/        # 路由
+│   ├── services/      # 网络请求 (Axios 封装)
+│   ├── store/         # 状态管理 (Pinia)
+│   ├── views/         # 页面
+│   │   └── error/     # 错误页面 (403/404/500)
+│   ├── composables/   # 组合式函数
+│   ├── env.ts         # 环境变量校验 (Zod)
+│   ├── main.ts        # 入口文件
+│   └── env.d.ts       # TypeScript 环境声明
+├── mock/              # Mock 数据
+├── tests/             # 测试
+├── Dockerfile         # Docker 配置
+├── nginx.conf         # Nginx 配置
+└── vite.config.ts     # Vite 配置
+```
+
+## 生成项目后
+
+```bash
+cd my-project
+npm run dev      # 启动开发服务器 (默认 3000 端口)
+npm run build    # 构建生产版本 (含 TypeScript 类型检查)
+npm run lint     # 代码检查
+npm run test     # 运行测试
+```
+
+## Docker 部署
+
+```bash
+docker build -t my-project .
+docker run -p 80:80 my-project
+```
+
+## 许可证
+
+[MIT](LICENSE)

package/bin/create-vue3-pc.mjs

@@ -0,0 +1,545 @@
+#!/usr/bin/env node
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import spawn from 'cross-spawn';
+import mri from 'mri';
+import * as prompts from '@clack/prompts';
+import pc from 'picocolors';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const { version: CLI_VERSION } = JSON.parse(
+  fs.readFileSync(new URL('../package.json', import.meta.url), 'utf-8')
+);
+
+const MIN_NODE_VERSION = 18;
+const DEFAULT_NAME = 'vue3-project';
+
+const TEMPLATES = {
+  base: path.join(__dirname, '../template/base'),
+  ts: path.join(__dirname, '../template/ts'),
+  cicd: {
+    github: path.join(__dirname, '../template/cicd-github'),
+    gitlab: path.join(__dirname, '../template/cicd-gitlab'),
+    jenkins: path.join(__dirname, '../template/cicd-jenkins'),
+  }
+};
+
+const VALID_CICD = ['none', 'github', 'gitlab', 'jenkins'];
+
+const DIR_NAME_RE = /^[a-zA-Z0-9-_]+$/;
+
+const helpMessage = `
+${pc.bold(pc.cyan('gridsum-vue3-pc'))} ${pc.dim(`v${CLI_VERSION}`)}
+
+${pc.bold('Usage:')}
+  ${pc.green('npx gridsum-vue3-pc')} ${pc.dim('[directory]')}
+  ${pc.green('gsvue')} ${pc.dim('[directory]')}
+
+${pc.bold('Options:')}
+  -n, --name <name>         Project name
+  -t, --title <title>       Project title
+  -c, --cicd <type>         CI/CD type ${pc.dim('(github, gitlab, jenkins, none)')}
+  -f, --force               Force overwrite if directory exists
+  --auto-start              Auto start dev server after creation
+  --no-auto-install         Skip automatic dependency installation
+  --no-interactive          Run in non-interactive mode
+  --no-git                  Skip git initialization
+  -h, --help                Display this message
+  -v, --version             Display version number
+
+${pc.bold('Examples:')}
+  ${pc.dim('# Interactive mode')}
+  ${pc.green('npx gridsum-vue3-pc')}
+
+  ${pc.dim('# Create with options')}
+  ${pc.green('gsvue my-project')} ${pc.yellow('--title "My Project"')}
+
+  ${pc.dim('# Non-interactive mode')}
+  ${pc.green('gsvue my-app')} ${pc.yellow('--no-interactive --name my-app --title "My App"')}
+`;
+
+const SPINNER_FRAMES = process.platform === 'win32'
+  ? ['-', '\\', '|', '/']
+  : ['⠋', '⠙', '⠹', '⠸', '⠼', '⠴', '⠦', '⠧', '⠇', '⠏'];
+
+function formatTargetDir(targetDir) {
+  const dir = targetDir.trim().replace(/\/+$/g, '');
+  if (/[<>:"\\|?*\x00-\x1f]/.test(dir) || dir.includes('..') || dir.includes('/') || dir.includes('\\')) {
+    return '';
+  }
+  return dir;
+}
+
+function isValidPackageName(name) {
+  return /^(?:@[a-z\d\-*~][a-z\d\-*._~]*\/)?[a-z\d\-~][a-z\d\-._~]*$/.test(name);
+}
+
+function toValidPackageName(name) {
+  return name
+    .trim()
+    .toLowerCase()
+    .replace(/\s+/g, '-')
+    .replace(/^[._]/, '')
+    .replace(/[^a-z\d\-~]+/g, '-');
+}
+
+function isEmpty(dir) {
+  if (!fs.existsSync(dir)) return true;
+  const files = fs.readdirSync(dir);
+  return files.length === 0 || (files.length === 1 && files[0] === '.git');
+}
+
+function emptyDir(dir) {
+  if (!fs.existsSync(dir)) return;
+  for (const file of fs.readdirSync(dir)) {
+    if (file === '.git') continue;
+    const target = path.resolve(dir, file);
+    const namespaced = target.length > 260 ? path.toNamespacedPath(target) : target;
+    fs.rmSync(namespaced, { recursive: true, force: true });
+  }
+}
+
+function copyDir(srcDir, destDir) {
+  if (!fs.existsSync(srcDir)) {
+    throw new Error(`Template directory not found: ${srcDir}`);
+  }
+  fs.mkdirSync(destDir, { recursive: true });
+  for (const file of fs.readdirSync(srcDir)) {
+    const srcFile = path.resolve(srcDir, file);
+    const destFile = path.resolve(destDir, file);
+    const stat = fs.statSync(srcFile);
+    if (stat.isDirectory()) {
+      copyDir(srcFile, destFile);
+    } else {
+      fs.copyFileSync(srcFile, destFile);
+    }
+  }
+}
+
+function detectPackageManager() {
+  const userAgent = process.env.npm_config_user_agent;
+  if (!userAgent) return 'npm';
+
+  if (userAgent.startsWith('pnpm')) return 'pnpm';
+  if (userAgent.startsWith('yarn')) return 'yarn';
+  if (userAgent.startsWith('bun')) return 'bun';
+  return 'npm';
+}
+
+function getInstallCommand(pkgManager) {
+  const args = pkgManager === 'yarn' ? [pkgManager] : [pkgManager, 'install'];
+  if (pkgManager === 'npm') args.push('--legacy-peer-deps');
+  return args;
+}
+
+function getRunCommand(pkgManager, script) {
+  switch (pkgManager) {
+    case 'yarn':
+    case 'pnpm':
+    case 'bun':
+      return [pkgManager, script];
+    default:
+      return [pkgManager, 'run', script];
+  }
+}
+
+function runCommand(command, options = {}) {
+  const [cmd, ...args] = command;
+  const result = spawn.sync(cmd, args, {
+    ...options,
+    stdio: 'inherit',
+  });
+
+  if (result.status != null && result.status > 0) {
+    process.exit(result.status);
+  }
+
+  if (result.error) {
+    console.error(`\n${pc.red('Error:')} ${result.error.message}\n`);
+    process.exit(1);
+  }
+}
+
+function runCommandAsync(command, options = {}) {
+  const [cmd, ...args] = command;
+  return new Promise((resolve, reject) => {
+    const child = spawn(cmd, args, {
+      stdio: ['ignore', 'pipe', 'pipe'],
+      windowsHide: false,
+      ...options,
+    });
+
+    let stderr = '';
+    child.stderr.on('data', (chunk) => { stderr += chunk.toString(); });
+
+    let i = 0;
+    const timer = setInterval(() => {
+      process.stdout.write(`\r${pc.cyan(SPINNER_FRAMES[i])} Installing dependencies...`);
+      i = (i + 1) % SPINNER_FRAMES.length;
+    }, 100);
+
+    child.on('close', (code) => {
+      clearInterval(timer);
+      process.stdout.write('\r\x1b[K');
+      if (code !== null && code > 0) {
+        if (stderr) process.stderr.write(stderr);
+        reject(new Error(`exit code ${code}`));
+      } else {
+        resolve();
+      }
+    });
+    child.on('error', (err) => {
+      clearInterval(timer);
+      process.stdout.write('\r\x1b[K');
+      if (stderr) process.stderr.write(stderr);
+      reject(err);
+    });
+  });
+}
+
+function tryGitInit(root) {
+  try {
+    spawn.sync('git', ['init'], { cwd: root, stdio: 'ignore' });
+    spawn.sync('git', ['add', '.'], { cwd: root, stdio: 'ignore' });
+    spawn.sync('git', ['commit', '-m', 'Initial project scaffolded by gridsum-vue3-pc'], {
+      cwd: root,
+      stdio: 'ignore',
+    });
+  } catch {
+    // git init is best-effort
+  }
+}
+
+function checkNodeVersion() {
+  const version = parseInt(process.version.slice(1).split('.')[0]);
+  if (version < MIN_NODE_VERSION) {
+    console.error(`
+${pc.red('Error:')} Node.js version ${pc.yellow(process.version)} is not supported.
+${pc.dim(`Minimum required: ${MIN_NODE_VERSION}.x+`)}
+
+Please upgrade Node.js:
+  ${pc.cyan('https://nodejs.org/')}
+`);
+    process.exit(1);
+  }
+}
+
+function parseArgs() {
+  const argv = mri(process.argv.slice(2), {
+    boolean: ['help', 'version', 'force', 'auto-start', 'no-interactive', 'no-auto-install', 'no-git'],
+    string: ['name', 'title', 'cicd'],
+    alias: {
+      h: 'help',
+      v: 'version',
+      n: 'name',
+      t: 'title',
+      c: 'cicd',
+      f: 'force',
+    },
+  });
+
+  argv._targetDir = argv._[0];
+  argv.interactive = !argv['no-interactive'];
+  argv.autoInstall = argv['no-auto-install'] ? false : undefined;
+
+  return argv;
+}
+
+function scaffoldProject(root, answers, packageName) {
+  fs.mkdirSync(root, { recursive: true });
+
+  copyDir(TEMPLATES.base, root);
+  copyDir(TEMPLATES.ts, root);
+
+  if (answers.cicd !== 'none') {
+    const cicdDir = TEMPLATES.cicd[answers.cicd];
+    if (!cicdDir || !fs.existsSync(cicdDir)) {
+      throw new Error(`CI/CD template "${answers.cicd}" not found at expected path: ${cicdDir}`);
+    }
+    copyDir(cicdDir, root);
+  }
+
+  const pkgPath = path.join(root, 'package.json');
+  if (fs.existsSync(pkgPath)) {
+    const pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf-8'));
+    pkg.name = packageName;
+    fs.writeFileSync(pkgPath, JSON.stringify(pkg, null, 2) + '\n');
+  }
+
+  ['.env', '.env.production'].forEach(file => {
+    const filePath = path.join(root, file);
+    if (fs.existsSync(filePath)) {
+      let content = fs.readFileSync(filePath, 'utf-8');
+      content = content.replace(/VITE_APP_TITLE=.*/, `VITE_APP_TITLE=${answers.title}`);
+      fs.writeFileSync(filePath, content);
+    }
+  });
+
+  const indexPath = path.join(root, 'index.html');
+  if (fs.existsSync(indexPath)) {
+    let content = fs.readFileSync(indexPath, 'utf-8');
+    content = content.replace(/<title>[^<]*<\/title>/, `<title>${answers.title}</title>`);
+    fs.writeFileSync(indexPath, content);
+  }
+}
+
+function validateOptions(options) {
+  const errors = [];
+
+  if (options.name && !DIR_NAME_RE.test(options.name)) {
+    errors.push('Project name must contain only letters, numbers, dash and underscore');
+  }
+
+  if (options.cicd && !VALID_CICD.includes(options.cicd)) {
+    errors.push(`Invalid cicd "${options.cicd}". Valid: ${VALID_CICD.join(', ')}`);
+  }
+
+  return errors;
+}
+
+async function main() {
+  checkNodeVersion();
+
+  const argv = parseArgs();
+
+  if (argv.help) {
+    console.log(helpMessage);
+    process.exit(0);
+  }
+
+  if (argv.version) {
+    console.log(`v${CLI_VERSION}`);
+    process.exit(0);
+  }
+
+  const validationErrors = validateOptions(argv);
+  if (validationErrors.length > 0) {
+    console.error(`\n${pc.red('Validation errors:')}`);
+    validationErrors.forEach(err => console.error(`  ${pc.red('•')} ${err}`));
+    console.error(`\nRun with ${pc.cyan('--help')} for usage information\n`);
+    process.exit(1);
+  }
+
+  const isInteractive = argv.interactive && process.stdin.isTTY;
+  const pkgManager = detectPackageManager();
+
+  const cancel = (exitCode = 0) => {
+    prompts.cancel('Operation cancelled');
+    process.exit(exitCode);
+  };
+
+  let targetDir = argv._targetDir ? formatTargetDir(argv._targetDir) : undefined;
+
+  if (targetDir === '') {
+    console.error(`\n${pc.red('Error:')} Invalid directory name "${argv._targetDir}"\n`);
+    process.exit(1);
+  }
+
+  if (!targetDir) {
+    if (isInteractive) {
+      const result = await prompts.text({
+        message: 'Project name:',
+        defaultValue: DEFAULT_NAME,
+        placeholder: DEFAULT_NAME,
+        validate: (value) => {
+          const dir = formatTargetDir(value);
+          if (!dir || dir.length === 0) {
+            return 'Project name cannot be empty';
+          }
+          if (!DIR_NAME_RE.test(dir)) {
+            return 'Only letters, numbers, dash and underscore allowed';
+          }
+        },
+      });
+      if (prompts.isCancel(result)) return cancel();
+      targetDir = formatTargetDir(result);
+    } else {
+      targetDir = DEFAULT_NAME;
+    }
+  }
+
+  const root = path.join(process.cwd(), targetDir);
+
+  if (fs.existsSync(root) && !isEmpty(root)) {
+    let action = argv.force ? 'overwrite' : undefined;
+
+    if (!action) {
+      if (isInteractive) {
+        const result = await prompts.select({
+          message: `Target directory "${targetDir}" is not empty. Please choose how to proceed:`,
+          options: [
+            { label: 'Cancel operation', value: 'cancel' },
+            { label: 'Remove existing files and continue', value: 'overwrite' },
+            { label: 'Ignore files and continue', value: 'ignore' },
+          ],
+        });
+        if (prompts.isCancel(result)) return cancel();
+        action = result;
+      } else {
+        action = 'cancel';
+      }
+    }
+
+    switch (action) {
+      case 'overwrite':
+        emptyDir(root);
+        break;
+      case 'ignore':
+        break;
+      case 'cancel': {
+        const exitCode = argv.interactive ? 0 : 1;
+        return cancel(exitCode);
+      }
+    }
+  }
+
+  let packageName = path.basename(path.resolve(root));
+  if (!isValidPackageName(packageName)) {
+    if (isInteractive) {
+      const result = await prompts.text({
+        message: 'Package name:',
+        defaultValue: toValidPackageName(packageName),
+        placeholder: toValidPackageName(packageName),
+        validate: (value) => {
+          if (value && !isValidPackageName(value)) {
+            return 'Invalid package.json name (must match: @scope/name or name)';
+          }
+        },
+      });
+      if (prompts.isCancel(result)) return cancel();
+      packageName = result;
+    } else {
+      packageName = toValidPackageName(packageName);
+    }
+  }
+
+  let answers = {
+    name: targetDir,
+    title: argv.title || 'Vue3 PC Template',
+    cicd: argv.cicd || 'none',
+  };
+
+  if (argv.title && !/^[a-zA-Z0-9_\-\u4e00-\u9fa5 ]+$/.test(argv.title)) {
+    console.error(`\n${pc.red('Error:')} Project title contains invalid characters\n`);
+    process.exit(1);
+  }
+
+  if (isInteractive) {
+    const title = await prompts.text({
+      message: 'Project title:',
+      defaultValue: answers.title,
+      placeholder: 'Vue3 PC Template',
+    });
+    if (prompts.isCancel(title)) return cancel();
+    answers.title = title;
+
+    const cicd = await prompts.select({
+      message: 'Select CI/CD:',
+      options: [
+        { label: 'None', value: 'none' },
+        { label: 'GitHub Actions', value: 'github' },
+        { label: 'GitLab CI', value: 'gitlab' },
+        { label: 'Jenkins', value: 'jenkins' },
+      ],
+      initialValue: answers.cicd,
+    });
+    if (prompts.isCancel(cicd)) return cancel();
+    answers.cicd = cicd;
+  }
+
+  const s = isInteractive ? prompts.spinner() : null;
+  if (s) {
+    s.start('Scaffolding project...');
+  } else {
+    prompts.log.step('Scaffolding project...');
+  }
+
+  try {
+    scaffoldProject(root, answers, packageName);
+  } catch (e) {
+    if (s) s.stop(pc.red('Scaffolding failed'));
+    console.error(`\n${pc.red('Error:')} ${e.message}\n`);
+    process.exit(1);
+  }
+
+  if (s) {
+    s.stop('Project created successfully!');
+  } else {
+    prompts.log.success('Project created successfully!');
+  }
+
+  let autoInstall = argv.autoInstall;
+  if (autoInstall === undefined && isInteractive) {
+    const result = await prompts.confirm({
+      message: `Install dependencies with ${pkgManager}?`,
+      initialValue: true,
+    });
+    if (prompts.isCancel(result)) return cancel();
+    autoInstall = result;
+  }
+
+  if (autoInstall && !process.env._CREATE_VUE3_PC_TEST) {
+    try {
+      await runCommandAsync(getInstallCommand(pkgManager), { cwd: root });
+      process.stdout.write(`\r\x1b[K${pc.green('✓')} Dependencies installed!\n`);
+    } catch (e) {
+      process.stdout.write(`\r\x1b[K${pc.red('✗')} Installation failed\n`);
+      console.error(`  ${pc.dim('You can retry manually:')}`);
+      console.error(`  ${pc.cyan(`cd ${targetDir} && ${pkgManager} install${pkgManager === 'npm' ? ' --legacy-peer-deps' : ''}`)}\n`);
+    }
+  }
+
+  if (!argv['no-git'] && !process.env._CREATE_VUE3_PC_TEST) {
+    tryGitInit(root);
+  }
+
+  let autoStart = argv['auto-start'];
+  if (autoStart === undefined && isInteractive) {
+    const result = await prompts.confirm({
+      message: 'Start dev server now?',
+      initialValue: false,
+    });
+    if (prompts.isCancel(result)) return cancel();
+    autoStart = result;
+  }
+
+  if (autoStart) {
+    prompts.log.step(`Starting dev server... (press ${pc.bold('Ctrl+C')} to stop)`);
+    if (process.env._CREATE_VUE3_PC_TEST) {
+      prompts.log.info('Dev server started (skipped in test)');
+    } else {
+      runCommand(getRunCommand(pkgManager, 'dev'), { cwd: root });
+      return;
+    }
+  }
+
+  const cdProjectName = path.relative(process.cwd(), root);
+  let doneMessage = '';
+
+  if (root !== process.cwd()) {
+    doneMessage += `\n  ${pc.bold(pc.cyan('cd'))} ${cdProjectName.includes(' ') ? `"${cdProjectName}"` : cdProjectName}`;
+  }
+
+  if (!autoInstall) {
+    doneMessage += `\n  ${pc.bold(pc.cyan(pkgManager))} ${pkgManager === 'yarn' ? '' : 'install '}${pc.dim('--legacy-peer-deps')}`;
+  }
+
+  doneMessage += `\n  ${pc.bold(pc.cyan(pkgManager))} ${pkgManager === 'yarn' ? 'dev' : 'run dev'}`;
+
+  prompts.outro(`${pc.green('Done!')} Now run:${doneMessage}`);
+
+  console.log(`
+${pc.dim('Available commands:')}
+  ${pkgManager} ${pkgManager === 'yarn' ? 'dev' : 'run dev'}        ${pc.dim('- Start dev server')}
+  ${pkgManager} ${pkgManager === 'yarn' ? 'build' : 'run build'}      ${pc.dim('- Build for production')}
+  ${pkgManager} ${pkgManager === 'yarn' ? 'lint' : 'run lint'}       ${pc.dim('- Lint code')}
+  ${pkgManager} ${pkgManager === 'yarn' ? 'test' : 'run test'}       ${pc.dim('- Run tests')}
+`);
+}
+
+main().catch((e) => {
+  console.error(`\n${pc.red('Error:')} ${e?.message || String(e)}\n`);
+  process.exit(1);
+});