create-swdg-frontend 0.1.6 → 0.2.0

package/README.md

@@ -1,29 +1,47 @@
 # create-swdg-frontend
 
-Scaffold a new project from the SWDG frontend template.
+从 SWDG 模板生成新项目。CLI 仅负责拷贝与 **feature flags** 裁剪；业务约定在 `template/` 内维护。
 
-## Usage
+## 使用
 
 ```bash
-pnpm create swdg-frontend my-app
-# or
+pnpm create swdg my-app
+# 或
 pnpm dlx create-swdg-frontend my-app
 ```
 
-## Sync template
+### 常用参数
+
+| 参数 | 说明 |
+|------|------|
+| `--no-gis` | 不引入 Cesium（默认交互也为否） |
+| `--gis` | 启用 GIS 依赖与示例 |
+| `--no-install` | 跳过安装 |
+| `--verify` | 安装后执行 `typecheck` |
+| `--git` | `git init` |
+
+生成项目包含 `.swdg/manifest.json` 记录创建选项。
+
+## 维护（模板负责人）
 
 ```bash
+# 从 monorepo 根目录同步
 pnpm run sync-template
+
+# 发布前校验 template 能 typecheck
+pnpm run validate-template
 ```
 
-You can override the template repo and branch:
+`prepublishOnly` 会自动 sync + validate。
 
-```bash
-TEMPLATE_REPO=http://10.20.124.70/bim/frontend-framework.git TEMPLATE_BRANCH=main pnpm run sync-template
-```
+环境变量：
 
-You can also sync from a local template directory:
+- `TEMPLATE_DIR` — 本地模板路径  
+- `TEMPLATE_REPO` / `TEMPLATE_BRANCH` — 远程 git 同步  
 
-```bash
-TEMPLATE_DIR="/Users/inupedia/Side Projects/frontend-framework" pnpm run sync-template
-```
+## 包内容
+
+- `bin/` — 入口  
+- `lib/` — CLI 模块（prompts、gis、manifest、scaffold）  
+- `stubs/` — 无 GIS 时的 vite/tsconfig/env 替身  
+- `template/` — 同步后的完整项目  

package/bin/index.js

@@ -1,248 +1,7 @@
 #!/usr/bin/env node
-import fs from 'node:fs/promises';
-import path from 'node:path';
-import { fileURLToPath } from 'node:url';
-import { spawn } from 'node:child_process';
-import readline from 'node:readline/promises';
+import { run } from '../lib/cli.js';
 
-const argv = process.argv.slice(2);
-
-let pm = 'pnpm';
-let targetDir;
-let shouldInstall;
-let shouldInitGit;
-let shouldIncludeGis;
-const flags = new Set();
-
-for (let i = 0; i < argv.length; i += 1) {
-  const arg = argv[i];
-  if (arg === '--pm') {
-    pm = argv[i + 1] ?? pm;
-    i += 1;
-    continue;
-  }
-  if (arg.startsWith('--pm=')) {
-    pm = arg.slice('--pm='.length) || pm;
-    continue;
-  }
-  if (arg === '--install') {
-    shouldInstall = true;
-    continue;
-  }
-  if (arg === '--no-install') {
-    shouldInstall = false;
-    continue;
-  }
-  if (arg === '--git') {
-    shouldInitGit = true;
-    continue;
-  }
-  if (arg === '--no-git') {
-    shouldInitGit = false;
-    continue;
-  }
-  if (arg === '--gis') {
-    shouldIncludeGis = true;
-    continue;
-  }
-  if (arg === '--no-gis') {
-    shouldIncludeGis = false;
-    continue;
-  }
-  if (arg.startsWith('-')) {
-    flags.add(arg);
-    continue;
-  }
-  if (!targetDir) targetDir = arg;
-}
-
-if (flags.has('--help') || flags.has('-h')) {
-  console.log(
-    `\nUsage: pnpm create swdg [project-name] [--install|--no-install] [--git|--no-git] [--gis|--no-gis] [--pm pnpm|npm|yarn]\n`
-  );
-  process.exit(0);
-}
-
-const __filename = fileURLToPath(import.meta.url);
-const __dirname = path.dirname(__filename);
-const templateDir = path.resolve(__dirname, '../template');
-let destDir;
-
-function isValidPackageName(name) {
-  if (!name) return false;
-  if (name.startsWith('@')) return false;
-  if (name.length > 214) return false;
-  return /^[a-z0-9][a-z0-9._-]*$/.test(name);
-}
-
-async function resolveTargetDir() {
-  if (targetDir) {
-    if (!isValidPackageName(targetDir)) {
-      console.error(
-        'Invalid project name. Use lowercase letters, numbers, dots, dashes or underscores.'
-      );
-      process.exit(1);
-    }
-    return targetDir;
-  }
-  const rl = readline.createInterface({
-    input: process.stdin,
-    output: process.stdout,
-  });
-  let name = '';
-  while (!isValidPackageName(name)) {
-    const answer = await rl.question('Project name (my-app): ');
-    name = answer.trim() || 'my-app';
-    if (!isValidPackageName(name)) {
-      console.log(
-        'Invalid project name. Use lowercase letters, numbers, dots, dashes or underscores.'
-      );
-    }
-  }
-  rl.close();
-  return name;
-}
-
-async function resolveGisChoice() {
-  if (shouldIncludeGis === true) return true;
-  if (shouldIncludeGis === false) return false;
-  const rl = readline.createInterface({
-    input: process.stdin,
-    output: process.stdout,
-  });
-  const answer = await rl.question('Include GIS (Cesium) assets? (Y/n): ');
-  rl.close();
-  if (!answer.trim()) return true;
-  return /^y(es)?$/i.test(answer.trim());
-}
-
-async function pathExists(p) {
-  try {
-    await fs.access(p);
-    return true;
-  } catch {
-    return false;
-  }
-}
-
-async function isDirEmpty(p) {
-  try {
-    const entries = await fs.readdir(p);
-    return entries.length === 0;
-  } catch {
-    return true;
-  }
-}
-
-async function copyTemplate() {
-  if (await pathExists(destDir)) {
-    const empty = await isDirEmpty(destDir);
-    if (!empty) {
-      const rl = readline.createInterface({
-        input: process.stdin,
-        output: process.stdout,
-      });
-      const answer = await rl.question(
-        `Target directory is not empty. Remove and continue? (y/N): `
-      );
-      rl.close();
-      if (!/^y(es)?$/i.test(answer.trim())) {
-        console.error('Aborted.');
-        process.exit(1);
-      }
-      await fs.rm(destDir, { recursive: true, force: true });
-      await fs.mkdir(destDir, { recursive: true });
-    }
-  } else {
-    await fs.mkdir(destDir, { recursive: true });
-  }
-
-  await fs.cp(templateDir, destDir, { recursive: true });
-}
-
-async function updatePackageName() {
-  const pkgPath = path.join(destDir, 'package.json');
-  const raw = await fs.readFile(pkgPath, 'utf8');
-  const pkg = JSON.parse(raw);
-  pkg.name = path.basename(destDir);
-  await fs.writeFile(pkgPath, JSON.stringify(pkg, null, 2) + '\n', 'utf8');
-}
-
-async function updateIndexTitle() {
-  const indexPath = path.join(destDir, 'index.html');
-  try {
-    const html = await fs.readFile(indexPath, 'utf8');
-    const title = path.basename(destDir);
-    const next = html.replace(
-      /<title>.*?<\/title>/i,
-      `<title>${title}</title>`
-    );
-    await fs.writeFile(indexPath, next, 'utf8');
-  } catch {
-    // Ignore if index.html does not exist
-  }
-}
-
-async function removeGisAssets() {
-  const gisDir = path.join(destDir, 'public', 'Cesium1.119');
-  await fs.rm(gisDir, { recursive: true, force: true });
-}
-
-async function runInstall() {
-  const cmd = pm || 'pnpm';
-  const child = spawn(cmd, ['install'], {
-    cwd: destDir,
-    stdio: 'inherit',
-  });
-  await new Promise((resolve, reject) => {
-    child.on('exit', (code) => {
-      if (code === 0) resolve();
-      else reject(new Error(`${cmd} install failed with code ${code}`));
-    });
-  });
-}
-
-async function initGit() {
-  await new Promise((resolve, reject) => {
-    const child = spawn('git', ['init'], {
-      cwd: destDir,
-      stdio: 'inherit',
-    });
-    child.on('exit', (code) => {
-      if (code === 0) resolve();
-      else reject(new Error(`git init failed with code ${code}`));
-    });
-  });
-}
-
-try {
-  targetDir = await resolveTargetDir();
-  destDir = path.resolve(process.cwd(), targetDir);
-  await copyTemplate();
-  await updatePackageName();
-  await updateIndexTitle();
-
-  const includeGis = await resolveGisChoice();
-  if (!includeGis) {
-    await removeGisAssets();
-  }
-
-  if (shouldInitGit === true) {
-    await initGit();
-  }
-
-  if (
-    shouldInstall === true ||
-    (shouldInstall !== false && flags.has('--install'))
-  ) {
-    await runInstall();
-  }
-
-  console.log(`\nProject created at ${destDir}`);
-  console.log(
-    `\nNext steps:\n  cd ${targetDir}\n  ${pm} install\n  ${pm} run dev\n`
-  );
-} catch (err) {
+run(process.argv.slice(2)).catch((err) => {
   console.error(err?.message ?? err);
   process.exit(1);
-}
+});

package/lib/argv.js

@@ -0,0 +1,43 @@
+/** @param {string[]} argv process.argv slice after node & script */
+export function parseArgv(argv) {
+  const flags = new Set();
+  let pm = 'pnpm';
+  let targetDir;
+  let shouldInstall;
+  let shouldInitGit;
+  let shouldIncludeGis;
+  let shouldVerify;
+
+  for (let i = 0; i < argv.length; i += 1) {
+    const arg = argv[i];
+    if (arg === '--pm') {
+      pm = argv[i + 1] ?? pm;
+      i += 1;
+      continue;
+    }
+    if (arg.startsWith('--pm=')) {
+      pm = arg.slice('--pm='.length) || pm;
+      continue;
+    }
+    if (arg === '--install') shouldInstall = true;
+    else if (arg === '--no-install') shouldInstall = false;
+    else if (arg === '--git') shouldInitGit = true;
+    else if (arg === '--no-git') shouldInitGit = false;
+    else if (arg === '--gis') shouldIncludeGis = true;
+    else if (arg === '--no-gis') shouldIncludeGis = false;
+    else if (arg === '--verify') shouldVerify = true;
+    else if (arg === '--no-verify') shouldVerify = false;
+    else if (arg.startsWith('-')) flags.add(arg);
+    else if (!targetDir) targetDir = arg;
+  }
+
+  return {
+    flags,
+    pm,
+    targetDir,
+    shouldInstall,
+    shouldInitGit,
+    shouldIncludeGis,
+    shouldVerify,
+  };
+}

package/lib/cli.js

@@ -0,0 +1,141 @@
+import readline from 'node:readline/promises';
+import path from 'node:path';
+import { FEATURES } from './constants.js';
+import { promptLine, resolveProjectName } from './prompts.js';
+import {
+  applyFeatures,
+  copyTemplate,
+  finalizeProject,
+  initGit,
+  runInstall,
+  updateIndexTitle,
+  updatePackageName,
+  verifyProject,
+} from './scaffold.js';
+import { parseArgv } from './argv.js';
+
+function printHelp() {
+  console.log(`
+Usage: pnpm create swdg [project-name] [options]
+
+大厂式脚手架：薄 CLI + 厚模板 + 可选特性（feature flags）
+
+交互（未传 flag 时）:
+  - 项目名称
+  - 是否启用 GIS（Cesium）— 默认否，按需开启
+  - 是否现在安装依赖 — 默认是
+  - 是否初始化 Git — 默认否
+  - 是否运行 typecheck 校验 — 默认是
+
+Options:
+  --gis / --no-gis          三维地图能力（npm + 示例页）
+  --install / --no-install  安装依赖
+  --git / --no-git          git init
+  --verify / --no-verify    创建后执行 pnpm typecheck
+  --pm pnpm|npm|yarn
+`);
+}
+
+async function confirmOverwrite(_destDir) {
+  const rl = readline.createInterface({
+    input: process.stdin,
+    output: process.stdout,
+  });
+  const answer = await rl.question(
+    'Target directory is not empty. Remove and continue? (y/N): '
+  );
+  rl.close();
+  return /^y(es)?$/i.test(answer.trim());
+}
+
+async function resolveGisChoice(shouldIncludeGis) {
+  if (shouldIncludeGis === true) return true;
+  if (shouldIncludeGis === false) return false;
+  return promptLine(
+    `是否启用 ${FEATURES.gis.label}？[y/N]: `,
+    FEATURES.gis.defaultEnabled
+  );
+}
+
+export async function run(argv) {
+  const parsed = parseArgv(argv);
+  if (parsed.flags.has('--help') || parsed.flags.has('-h')) {
+    printHelp();
+    return;
+  }
+
+  const projectName = await resolveProjectName(parsed.targetDir);
+  const includeGis = await resolveGisChoice(parsed.shouldIncludeGis);
+  const installDeps =
+    parsed.shouldInstall === true
+      ? true
+      : parsed.shouldInstall === false
+        ? false
+        : await promptLine('是否现在安装依赖？(Y/n): ', true);
+  const initGitRepo =
+    parsed.shouldInitGit === true
+      ? true
+      : parsed.shouldInitGit === false
+        ? false
+        : await promptLine('是否初始化 Git 仓库？(y/N): ', false);
+  const runVerify =
+    parsed.shouldVerify === true
+      ? true
+      : parsed.shouldVerify === false
+        ? false
+        : await promptLine('创建后运行 typecheck 校验？(Y/n): ', true);
+
+  const destDir = path.resolve(process.cwd(), projectName);
+
+  console.log('\n── SWDG 创建摘要 ──');
+  console.log(`  项目: ${projectName}`);
+  console.log(`  GIS:  ${includeGis ? '启用' : '关闭'}`);
+  console.log(`  安装: ${installDeps ? '是' : '否'}`);
+  console.log(`  Git:  ${initGitRepo ? '是' : '否'}`);
+  console.log(`  校验: ${runVerify ? 'typecheck' : '跳过'}`);
+  console.log('──────────────────\n');
+
+  try {
+    await copyTemplate(destDir);
+  } catch (err) {
+    if (err.message === 'TARGET_NOT_EMPTY') {
+      if (!(await confirmOverwrite(destDir))) {
+        console.error('Aborted.');
+        process.exit(1);
+      }
+      await copyTemplate(destDir, { forceEmpty: true });
+    } else {
+      throw err;
+    }
+  }
+
+  await updatePackageName(destDir, projectName);
+  await updateIndexTitle(destDir, projectName);
+  await applyFeatures(destDir, { gis: includeGis });
+  await finalizeProject(destDir, { gis: includeGis, pm: parsed.pm });
+
+  if (initGitRepo) await initGit(destDir);
+  if (installDeps) {
+    console.log(`\nInstalling dependencies (${parsed.pm})…\n`);
+    await runInstall(destDir, parsed.pm);
+  }
+  if (runVerify && installDeps) {
+    console.log('\nRunning post-scaffold verification (typecheck)…\n');
+    await verifyProject(destDir, parsed.pm);
+  }
+
+  console.log(`\n✓ Project ready: ${destDir}`);
+  console.log(`  Manifest: .swdg/manifest.json`);
+  console.log(`  Onboarding: docs/ONBOARDING.md`);
+  if (!installDeps) {
+    console.log(
+      `\n  cd ${projectName} && ${parsed.pm} install && ${parsed.pm} run dev`
+    );
+  } else {
+    console.log(`\n  cd ${projectName} && ${parsed.pm} run dev`);
+  }
+  if (includeGis) {
+    console.log('  GIS demo: /#/examples/cesium');
+  }
+  console.log('  Examples (dev): /#/examples/test');
+}

package/lib/constants.js

@@ -0,0 +1,24 @@
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+
+export const PACKAGE_ROOT = path.resolve(__dirname, '..');
+export const TEMPLATE_DIR = path.join(PACKAGE_ROOT, 'template');
+export const STUBS_DIR = path.join(PACKAGE_ROOT, 'stubs');
+export const SCAFFOLD_VERSION = '0.2.0';
+
+/** 可选特性：重型依赖默认关闭，创建时 opt-in */
+export const FEATURES = {
+  gis: {
+    id: 'gis',
+    label: 'GIS（Cesium 三维地图）',
+    defaultEnabled: false,
+    paths: [
+      'scripts/vite-plugin-cesium-dev.ts',
+      'src/utils/cesium',
+      'src/components/CesiumViewer',
+      'src/views/examples/cesium',
+    ],
+  },
+};

package/lib/gis.js

@@ -0,0 +1,92 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { FEATURES, STUBS_DIR } from './constants.js';
+
+const { paths: GIS_PATHS } = FEATURES.gis;
+
+async function removePathIfExists(destDir, relativePath) {
+  await fs.rm(path.join(destDir, relativePath), {
+    recursive: true,
+    force: true,
+  });
+}
+
+async function patchPackageWithoutGis(destDir) {
+  const pkgPath = path.join(destDir, 'package.json');
+  const pkg = JSON.parse(await fs.readFile(pkgPath, 'utf8'));
+  if (pkg.dependencies) delete pkg.dependencies.cesium;
+  if (pkg.devDependencies)
+    delete pkg.devDependencies['vite-plugin-static-copy'];
+  await fs.writeFile(pkgPath, JSON.stringify(pkg, null, 2) + '\n', 'utf8');
+}
+
+async function patchReadmeWithoutGis(destDir) {
+  const readmePath = path.join(destDir, 'README.md');
+  try {
+    let content = await fs.readFile(readmePath, 'utf8');
+    content = content.replace(/\n## Cesium[\s\S]*?(?=\n## )/, '\n');
+    await fs.writeFile(readmePath, content, 'utf8');
+  } catch {
+    // ignore
+  }
+}
+
+async function applyNoGisStubs(destDir) {
+  const pairs = [
+    ['vite.config.ts', 'vite.config.ts'],
+    ['tsconfig.node.json', 'tsconfig.node.json'],
+    ['types-env.d.ts', path.join('types', 'env.d.ts')],
+  ];
+  for (const [stubName, destRel] of pairs) {
+    await fs.copyFile(
+      path.join(STUBS_DIR, stubName),
+      path.join(destDir, destRel)
+    );
+  }
+}
+
+async function upsertEnvFeature(destDir, enabled) {
+  const envExample = path.join(destDir, '.env.example');
+  let content;
+  try {
+    content = await fs.readFile(envExample, 'utf8');
+  } catch {
+    content = 'VITE_DEMO_PROXY_TARGET=http://127.0.0.1:8888\n\n';
+  }
+
+  const line = 'VITE_FEATURE_GIS=true';
+  if (enabled) {
+    if (!content.includes('VITE_FEATURE_GIS')) {
+      content += `\n# GIS (Cesium)\n${line}\n`;
+    }
+  } else {
+    content = content
+      .replace(/\n?# GIS \(Cesium\)[\s\S]*?VITE_FEATURE_GIS=true\n?/g, '\n')
+      .replace(/\n?VITE_FEATURE_GIS=true\n?/g, '\n');
+  }
+  await fs.writeFile(envExample, content, 'utf8');
+
+  const envPath = path.join(destDir, '.env');
+  if (enabled) {
+    const envBody = `VITE_DEMO_PROXY_TARGET=http://127.0.0.1:8888\n${line}\n`;
+    try {
+      await fs.access(envPath);
+    } catch {
+      await fs.writeFile(envPath, envBody, 'utf8');
+    }
+  }
+}
+
+export async function applyGisIntegration(destDir) {
+  await upsertEnvFeature(destDir, true);
+}
+
+export async function removeGisIntegration(destDir) {
+  for (const relativePath of GIS_PATHS) {
+    await removePathIfExists(destDir, relativePath);
+  }
+  await patchPackageWithoutGis(destDir);
+  await patchReadmeWithoutGis(destDir);
+  await applyNoGisStubs(destDir);
+  await upsertEnvFeature(destDir, false);
+}

package/lib/manifest.js

@@ -0,0 +1,23 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { SCAFFOLD_VERSION } from './constants.js';
+
+export async function writeProjectManifest(destDir, options) {
+  const manifestDir = path.join(destDir, '.swdg');
+  await fs.mkdir(manifestDir, { recursive: true });
+
+  const manifest = {
+    schemaVersion: 1,
+    generator: 'create-swdg-frontend',
+    generatorVersion: SCAFFOLD_VERSION,
+    createdAt: new Date().toISOString(),
+    features: options.features,
+    packageManager: options.packageManager,
+  };
+
+  await fs.writeFile(
+    path.join(manifestDir, 'manifest.json'),
+    JSON.stringify(manifest, null, 2) + '\n',
+    'utf8'
+  );
+}

package/lib/prompts.js

@@ -0,0 +1,55 @@
+import readline from 'node:readline/promises';
+
+export function parseYesNo(answer, defaultYes = true) {
+  const trimmed = answer.trim();
+  if (!trimmed) return defaultYes;
+  if (/^y(es)?$/i.test(trimmed)) return true;
+  if (/^n(o)?$/i.test(trimmed)) return false;
+  return defaultYes;
+}
+
+function createInterface() {
+  return readline.createInterface({
+    input: process.stdin,
+    output: process.stdout,
+  });
+}
+
+export async function promptLine(question, defaultYes = true) {
+  const rl = createInterface();
+  const answer = await rl.question(question);
+  rl.close();
+  return parseYesNo(answer, defaultYes);
+}
+
+export function isValidPackageName(name) {
+  if (!name) return false;
+  if (name.startsWith('@')) return false;
+  if (name.length > 214) return false;
+  return /^[a-z0-9][a-z0-9._-]*$/.test(name);
+}
+
+export async function resolveProjectName(argvName) {
+  if (argvName) {
+    if (!isValidPackageName(argvName)) {
+      throw new Error(
+        'Invalid project name. Use lowercase letters, numbers, dots, dashes or underscores.'
+      );
+    }
+    return argvName;
+  }
+
+  const rl = createInterface();
+  let name = '';
+  while (!isValidPackageName(name)) {
+    const answer = await rl.question('Project name (my-app): ');
+    name = answer.trim() || 'my-app';
+    if (!isValidPackageName(name)) {
+      console.log(
+        'Invalid project name. Use lowercase letters, numbers, dots, dashes or underscores.'
+      );
+    }
+  }
+  rl.close();
+  return name;
+}