create-swdg-frontend 0.1.7 → 0.2.0

package/lib/scaffold.js

@@ -0,0 +1,118 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { spawn } from 'node:child_process';
+import { TEMPLATE_DIR } from './constants.js';
+import { applyGisIntegration, removeGisIntegration } from './gis.js';
+import { writeProjectManifest } from './manifest.js';
+
+export async function pathExists(p) {
+  try {
+    await fs.access(p);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+async function isDirEmpty(p) {
+  try {
+    return (await fs.readdir(p)).length === 0;
+  } catch {
+    return true;
+  }
+}
+
+export async function copyTemplate(destDir, { forceEmpty = false } = {}) {
+  if (await pathExists(destDir)) {
+    const empty = await isDirEmpty(destDir);
+    if (!empty && !forceEmpty) {
+      throw new Error('TARGET_NOT_EMPTY');
+    }
+    await fs.rm(destDir, { recursive: true, force: true });
+  }
+  await fs.mkdir(destDir, { recursive: true });
+  await fs.cp(TEMPLATE_DIR, destDir, { recursive: true });
+}
+
+export async function updatePackageName(destDir, name) {
+  const pkgPath = path.join(destDir, 'package.json');
+  const pkg = JSON.parse(await fs.readFile(pkgPath, 'utf8'));
+  pkg.name = name;
+  await fs.writeFile(pkgPath, JSON.stringify(pkg, null, 2) + '\n', 'utf8');
+}
+
+export async function updateIndexTitle(destDir, title) {
+  const indexPath = path.join(destDir, 'index.html');
+  try {
+    const html = await fs.readFile(indexPath, 'utf8');
+    const next = html.replace(
+      /<title>.*?<\/title>/i,
+      `<title>${title}</title>`
+    );
+    await fs.writeFile(indexPath, next, 'utf8');
+  } catch {
+    // ignore
+  }
+}
+
+export async function runInstall(destDir, pm) {
+  const child = spawn(pm, ['install'], { cwd: destDir, stdio: 'inherit' });
+  await new Promise((resolve, reject) => {
+    child.on('exit', (code) => {
+      if (code === 0) resolve();
+      else reject(new Error(`${pm} install failed with code ${code}`));
+    });
+  });
+}
+
+export async function initGit(destDir) {
+  const child = spawn('git', ['init'], { cwd: destDir, stdio: 'inherit' });
+  await new Promise((resolve, reject) => {
+    child.on('exit', (code) => {
+      if (code === 0) resolve();
+      else reject(new Error(`git init failed with code ${code}`));
+    });
+  });
+}
+
+export async function verifyProject(destDir, pm) {
+  const child = spawn(pm, ['run', 'typecheck'], {
+    cwd: destDir,
+    stdio: 'inherit',
+  });
+  await new Promise((resolve, reject) => {
+    child.on('exit', (code) => {
+      if (code === 0) resolve();
+      else reject(new Error('Post-scaffold typecheck failed'));
+    });
+  });
+}
+
+export async function applyFeatures(destDir, { gis }) {
+  if (gis) {
+    await applyGisIntegration(destDir);
+  } else {
+    await removeGisIntegration(destDir);
+  }
+}
+
+export async function finalizeProject(destDir, context) {
+  await writeProjectManifest(destDir, {
+    features: { gis: context.gis },
+    packageManager: context.pm,
+  });
+}
+
+/** 供 CLI 与集成测试复用的创建流程（不含 install / git / verify） */
+export async function createProject(
+  destDir,
+  { projectName, gis, pm = 'pnpm' }
+) {
+  await copyTemplate(destDir);
+  await updatePackageName(destDir, projectName);
+  await updateIndexTitle(destDir, projectName);
+  await applyFeatures(destDir, { gis });
+  await finalizeProject(destDir, { gis, pm });
+}
+
+export { TEMPLATE_DIR };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-swdg-frontend",
-  "version": "0.1.7",
+  "version": "0.2.0",
   "description": "Scaffold a new SWDG frontend project",
   "type": "module",
   "bin": {
@@ -8,11 +8,15 @@
   },
   "files": [
     "bin",
+    "lib",
+    "stubs",
+    "scripts",
     "template"
   ],
   "scripts": {
     "sync-template": "node scripts/sync-template.js",
-    "prepublishOnly": "node scripts/sync-template.js"
+    "validate-template": "node scripts/validate-template.mjs",
+    "prepublishOnly": "node scripts/sync-template.js && node scripts/validate-template.mjs"
   },
   "engines": {
     "node": ">=18"

package/scripts/sync-template.js

@@ -0,0 +1,120 @@
+#!/usr/bin/env node
+import fs from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+import { spawn } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+
+const DEFAULT_REPO = 'http://10.20.124.70/bim/frontend-framework.git';
+const repo = process.env.TEMPLATE_REPO || DEFAULT_REPO;
+const localSource = process.env.TEMPLATE_DIR;
+const autoLocalSource = path.resolve(__dirname, '../..');
+const branch = process.env.TEMPLATE_BRANCH || 'main';
+const templateDir = path.resolve(__dirname, '../template');
+
+const excludes = new Set([
+  '.git',
+  'node_modules',
+  'dist',
+  '.DS_Store',
+  '.cursor',
+  '.vscode',
+  'create-swdg',
+  'create-frontend-framework',
+  'swdg',
+  'package-lock.json',
+  'pnpm-lock.yaml',
+  'openapi-generator-cli.jar',
+  'tsconfig.tsbuildinfo',
+  'auto-imports.d.ts',
+  'components.d.ts',
+  '_tmp-swdg-test',
+  'my-app',
+  'public/Cesium1.119',
+]);
+
+function run(cmd, args, options = {}) {
+  return new Promise((resolve, reject) => {
+    const child = spawn(cmd, args, { stdio: 'inherit', ...options });
+    child.on('exit', (code) => {
+      if (code === 0) resolve();
+      else
+        reject(new Error(`${cmd} ${args.join(' ')} failed with code ${code}`));
+    });
+  });
+}
+
+async function pathExists(targetPath) {
+  try {
+    await fs.access(targetPath);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+async function copyDir(src, dest) {
+  const entries = await fs.readdir(src, { withFileTypes: true });
+  await fs.mkdir(dest, { recursive: true });
+
+  for (const entry of entries) {
+    if (excludes.has(entry.name)) continue;
+    const from = path.join(src, entry.name);
+    const to = path.join(dest, entry.name);
+
+    if (entry.isDirectory()) {
+      await copyDir(from, to);
+    } else if (entry.isSymbolicLink()) {
+      const link = await fs.readlink(from);
+      await fs.symlink(link, to);
+    } else {
+      await fs.copyFile(from, to);
+    }
+  }
+}
+
+async function main() {
+  const tempRoot = await fs.mkdtemp(path.join(os.tmpdir(), 'swdg-template-'));
+  const tempRepo = path.join(tempRoot, 'repo');
+
+  if (
+    localSource ||
+    (await pathExists(path.join(autoLocalSource, 'package.json')))
+  ) {
+    const absLocal = localSource ? path.resolve(localSource) : autoLocalSource;
+    console.log(`Syncing template from local path: ${absLocal}`);
+    await fs.rm(templateDir, { recursive: true, force: true });
+    await fs.mkdir(templateDir, { recursive: true });
+    await copyDir(absLocal, templateDir);
+    console.log('Template synced.');
+    return;
+  }
+
+  console.log(`Cloning template from ${repo} (${branch})...`);
+  await run('git', [
+    'clone',
+    '--depth',
+    '1',
+    '--branch',
+    branch,
+    repo,
+    tempRepo,
+  ]);
+
+  await fs.rm(templateDir, { recursive: true, force: true });
+  await fs.mkdir(templateDir, { recursive: true });
+
+  console.log('Syncing template...');
+  await copyDir(tempRepo, templateDir);
+
+  await fs.rm(tempRoot, { recursive: true, force: true });
+  console.log('Template synced.');
+}
+
+main().catch((err) => {
+  console.error(err?.message ?? err);
+  process.exit(1);
+});

package/scripts/validate-template.mjs

@@ -0,0 +1,74 @@
+#!/usr/bin/env node
+/**
+ * 校验 create-swdg/template 可 install / typecheck / build。
+ * 在 create-swdg 包内自包含，供 prepublishOnly 与 monorepo test:template 使用。
+ */
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { spawn } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+
+const packageRoot = path.resolve(
+  path.dirname(fileURLToPath(import.meta.url)),
+  '..'
+);
+const templateDir = path.join(packageRoot, 'template');
+
+function run(cmd, args, cwd, env = process.env) {
+  return new Promise((resolve, reject) => {
+    const child = spawn(cmd, args, {
+      cwd,
+      stdio: 'inherit',
+      shell: true,
+      env,
+    });
+    child.on('exit', (code) => {
+      if (code === 0) resolve();
+      else reject(new Error(`${cmd} ${args.join(' ')} exited ${code}`));
+    });
+  });
+}
+
+async function assertTemplateLayout() {
+  const required = [
+    'package.json',
+    'vite.config.ts',
+    'src/main.ts',
+    'src/router/index.ts',
+    'src/views/index.vue',
+    'docs/ONBOARDING.md',
+  ];
+  for (const rel of required) {
+    try {
+      await fs.access(path.join(templateDir, rel));
+    } catch {
+      throw new Error(`template missing required file: ${rel}`);
+    }
+  }
+}
+
+async function main() {
+  console.log('\n▶ validate-template\n');
+  console.log(`  template: ${templateDir}`);
+
+  await assertTemplateLayout();
+
+  console.log('  · pnpm install');
+  await run('pnpm', ['install'], templateDir);
+
+  console.log('  · typecheck');
+  await run('pnpm', ['run', 'typecheck'], templateDir);
+
+  console.log('  · production build');
+  await run('pnpm', ['run', 'build'], templateDir, {
+    ...process.env,
+    VITE_FEATURE_GIS: 'true',
+  });
+
+  console.log('\n✓ validate-template passed\n');
+}
+
+main().catch((err) => {
+  console.error(`\n✗ validate-template failed: ${err.message}\n`);
+  process.exit(1);
+});

package/stubs/tsconfig.node.json

@@ -0,0 +1,11 @@
+{
+  "compilerOptions": {
+    "composite": true,
+    "skipLibCheck": true,
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "allowSyntheticDefaultImports": true,
+    "strict": true
+  },
+  "include": ["vite.config.ts"]
+}

package/stubs/types-env.d.ts

@@ -0,0 +1,9 @@
+/// <reference types="vite/client" />
+
+interface ImportMetaEnv {
+  readonly VITE_DEMO_PROXY_TARGET?: string;
+}
+
+interface ImportMeta {
+  readonly env: ImportMetaEnv;
+}

package/stubs/vite.config.ts

@@ -0,0 +1,64 @@
+import { defineConfig, loadEnv } from 'vite';
+import vue from '@vitejs/plugin-vue';
+import AutoImport from 'unplugin-auto-import/vite';
+import Components from 'unplugin-vue-components/vite';
+import copyPlugin from 'rollup-plugin-copy';
+import path from 'path';
+
+export default defineConfig(({ mode }) => {
+  const env = loadEnv(mode, process.cwd(), '');
+
+  return {
+    base: './',
+    build: {
+      sourcemap: true,
+      emptyOutDir: false,
+      rollupOptions: {
+        plugins: [
+          copyPlugin({
+            targets: [{ src: 'src/assets/**/*', dest: 'dist/assets' }],
+          }),
+        ],
+      },
+      outDir: 'dist',
+      assetsDir: 'assets',
+    },
+    plugins: [vue(), AutoImport({}), Components({})],
+    resolve: {
+      alias: {
+        '@': path.resolve(__dirname, './src'),
+        '@assets': path.resolve(__dirname, './src/assets'),
+        '@style': path.resolve(__dirname, './src/styles'),
+        '@stores': path.resolve(__dirname, './src/stores'),
+        '@components': path.resolve(__dirname, './src/components'),
+        '@utils': path.resolve(__dirname, './src/utils'),
+        '@api': path.resolve(__dirname, './src/api'),
+        '@types': path.resolve(__dirname, './types'),
+        '@views': path.resolve(__dirname, './src/views'),
+        '@composables': path.resolve(__dirname, './src/utils/composables'),
+        '@router': path.resolve(__dirname, './src/router'),
+        '@directive': path.resolve(__dirname, './src/directive'),
+        '@layout': path.resolve(__dirname, './src/layout'),
+        '@interface': path.resolve(__dirname, './interface'),
+      },
+    },
+    css: {
+      preprocessorOptions: {
+        less: {
+          javascriptEnabled: true,
+        },
+      },
+    },
+    server: {
+      host: '0.0.0.0',
+      port: 3000,
+      open: true,
+      proxy: {
+        '/demo': {
+          target: env.VITE_DEMO_PROXY_TARGET,
+          changeOrigin: true,
+        },
+      },
+    },
+  };
+});

package/template/.env.example

@@ -0,0 +1,6 @@
+# 复制为 .env 后按需修改
+VITE_DEMO_PROXY_TARGET=http://127.0.0.1:8888
+
+# 模板默认含 Cesium；脚手架 --no-gis 会移除此行
+VITE_FEATURE_GIS=true
+# VITE_CESIUM_ION_ACCESS_TOKEN=

package/template/.github/workflows/ci.yml

@@ -0,0 +1,23 @@
+name: CI
+
+on:
+  push:
+    branches: [main, master]
+  pull_request:
+    branches: [main, master]
+
+jobs:
+  release-gate:
+    runs-on: ubuntu-latest
+    timeout-minutes: 30
+    steps:
+      - uses: actions/checkout@v4
+      - uses: pnpm/action-setup@v4
+        with:
+          version: 9
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 22
+          cache: pnpm
+      - run: pnpm install --frozen-lockfile
+      - run: pnpm test:ci

package/template/.github/workflows/release.yml

@@ -0,0 +1,69 @@
+name: Release to npm
+
+on:
+  push:
+    tags:
+      - 'v[0-9]+.[0-9]+.[0-9]+'
+
+permissions:
+  contents: read
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    timeout-minutes: 45
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Resolve version from tag
+        id: meta
+        run: |
+          TAG="${GITHUB_REF_NAME}"
+          VERSION="${TAG#v}"
+          if ! echo "$VERSION" | grep -Eq '^[0-9]+\.[0-9]+\.[0-9]+$'; then
+            echo "Invalid tag: $TAG (expected vX.Y.Z)"
+            exit 1
+          fi
+          echo "version=$VERSION" >> "$GITHUB_OUTPUT"
+          echo "Publishing version: $VERSION"
+
+      - uses: pnpm/action-setup@v4
+        with:
+          version: 9
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 22
+          cache: pnpm
+
+      - name: Align package versions
+        run: node scripts/set-release-version.mjs "${{ steps.meta.outputs.version }}"
+
+      - name: Install dependencies
+        run: pnpm install --frozen-lockfile
+
+      - name: Release test pipeline
+        run: pnpm test:ci
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 22
+          registry-url: https://registry.npmjs.org
+
+      - name: Publish create-swdg-frontend
+        working-directory: create-swdg
+        run: npm publish --access public
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
+
+      - name: Publish swdg
+        working-directory: swdg
+        run: npm publish --access public
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
+
+      - name: Summary
+        run: |
+          echo "Published create-swdg-frontend@${{ steps.meta.outputs.version }}"
+          echo "Published swdg@${{ steps.meta.outputs.version }}"

package/template/.stylelintrc.json

@@ -1,6 +1,12 @@
 {
   "extends": ["stylelint-config-standard", "stylelint-config-recommended-vue"],
   "rules": {
-    "no-empty-source": null
+    "no-empty-source": null,
+    "selector-class-pattern": [
+      "^([a-z][a-z0-9]*(-[a-z0-9]+)*)(__([a-z][a-z0-9]*(-[a-z0-9]+)*))*(-{1,2}([a-z][a-z0-9]*(-[a-z0-9]+)*))*?$",
+      {
+        "message": "Use kebab-case or BEM (block__element--modifier)"
+      }
+    ]
   }
 }

package/template/README.md

@@ -1,36 +1,99 @@
-# Frontend Framework (Vue 3 + TypeScript + Vite)
+# SWDG Frontend Framework
 
-面向小型开发团队的通用前端框架模板，提供清晰目录、可复用示例、统一配置与约定。
+面向团队的 **Vue 3 + TypeScript + Vite** 标准模板与脚手架（`create-swdg`）。
+
+设计参考 Google / Meta / Microsoft 内部生成器常见模式：
+
+- **薄 CLI、厚模板**：逻辑在模板仓库迭代，CLI 只做拷贝与特性裁剪
+- **Feature flags**：重型能力（GIS）默认关闭，按需 opt-in
+- **示例与业务分离**：`src/views/examples/` 仅 dev 路由，生产自动剔除
+- **可验证**：创建后可跑 `typecheck`；模板发布前 `validate-template`
+- **可追溯**：生成 `.swdg/manifest.json` 记录创建参数
+
+## 如何使用本项目
+
+**完整说明（环境、路由、接口、GIS、构建）** → **[docs/ONBOARDING.md](docs/ONBOARDING.md)**
+
+```bash
+pnpm install
+cp .env.example .env   # 含 VITE_FEATURE_GIS、代理地址
+pnpm dev               # http://localhost:3000 ，改 .env 后需重启
+```
+
+| 你想做的事   | 怎么做                                                                 |
+| ------------ | ---------------------------------------------------------------------- |
+| 跑起来看效果 | 首页 `/#/` → 开发示例卡片 → Cesium / Store 示例                        |
+| 加一个新页面 | `src/views/模块名/index.vue` → 自动得到 `/#/模块名`                    |
+| 调后端接口   | `src/api/` + 开发代理 `/demo` → `VITE_DEMO_PROXY_TARGET`               |
+| 开三维地图   | `.env` 设 `VITE_FEATURE_GIS=true`，用 `CesiumViewer` 或 `createViewer` |
+| 提交前检查   | `pnpm verify`                                                          |
+
+维护模板 / 发 npm → [docs/MAINTAINER.md](docs/MAINTAINER.md) · 测试门禁 → [docs/TESTING.md](docs/TESTING.md)
+
+## 创建新项目（脚手架）
+
+```bash
+pnpm create swdg my-app
+# 或
+npx create-swdg-frontend my-app
+```
+
+交互会询问：项目名、**是否 GIS（默认否）**、是否安装依赖、是否 Git、是否 typecheck 校验。
+
+```bash
+# 非 GIS 项目（推荐多数后台类应用）
+pnpm create swdg my-app --no-gis --install
+
+# GIS 项目
+pnpm create swdg my-app --gis --install
+```
 
 ## 目录结构
 
-project
-├── interface/ # 📝 业务模型接口定义
-├── public/ # 🌐 公共资源，打包会直接打进根目录
-├── src
-│ ├── api/ # 🔌 请求后端接口
-│ ├── assets/ # 🖼 静态资源
-│ ├── components/ # 🧩 公共基础组件
-│ ├── directive/ # ⚡ 全局指令
-│ ├── layout/ # 📐 布局组件
-│ ├── router/ # 🛣 路由配置
-│ ├── stores/ # 🗄 全局状态管理
-│ ├── styles/ # 🎨 全局样式
-│ ├── utils/ # 🛠 工具类
-│ └── views/ # 📄 业务页面
-├── tests/ # 🧪 测试目录
-│ ├── unit/ # 单元测试（Vitest）
-│ ├── e2e/ # E2E 测试
-│ ├── setup.ts # 测试环境配置
-│ └── utils/ # 测试工具函数
-├── types/ # 📋 全局类型声明
-├── vitest.config.ts # 🧪 Vitest 配置
-└── package.json
-
-## 示例说明
-
-- `src/api/`：`modules/demo.ts` 演示接口调用
-- `src/stores/`：`useCounter.ts` 演示 Pinia Store
-- `src/directive/`：`focus.ts` 演示自定义指令
-- `src/layout/`：`BasicLayout.vue` 演示布局壳
-- `src/views/Test`：演示使用 store + api + composable
+```
+src/
+├── api/           # 接口
+├── components/    # 公共组件
+├── layout/
+├── router/        # 约定式路由（views 下文件即路由）
+├── stores/
+├── utils/
+├── views/         # 业务页面
+│   └── examples/  # 开发示例（生产构建剔除）
+interface/
+types/
+docs/
+```
+
+## Cesium / GIS（可选特性）
+
+启用后包含：`cesium`、`vite-plugin-static-copy`、开发中间件、`/#/examples/cesium`。
+
+- 底图：OpenStreetMap（无需 Ion token）
+- 可选：`VITE_CESIUM_ION_ACCESS_TOKEN`
+
+```ts
+import { createViewer } from '@utils/cesium';
+```
+
+## 维护者与发布
+
+见 [docs/MAINTAINER.md](docs/MAINTAINER.md)。
+
+```bash
+pnpm verify                              # 本地质量门禁
+cd create-swdg && pnpm sync-template     # 同步模板
+cd create-swdg && node scripts/validate-template.mjs
+```
+
+## 脚本
+
+| 命令             | 说明                                 |
+| ---------------- | ------------------------------------ |
+| `pnpm dev`       | 开发                                 |
+| `pnpm build`     | 构建                                 |
+| `pnpm typecheck` | TS 检查                              |
+| `pnpm verify`    | typecheck + lint（日常）             |
+| `pnpm test:ci`   | 发布门禁（全量，见 docs/TESTING.md） |
+| `pnpm gen:api`   | OpenAPI 生成                         |
+| `pnpm release`   | 先跑 test:ci，再发布 npm 包          |

package/template/auto-imports.d.ts

@@ -0,0 +1,10 @@
+/* eslint-disable */
+/* prettier-ignore */
+// @ts-nocheck
+// noinspection JSUnusedGlobalSymbols
+// Generated by unplugin-auto-import
+// biome-ignore lint: disable
+export {}
+declare global {
+
+}