create-react-admin-template 0.0.0-stage → 0.1.0

package/template/tools/scaffold/create-project.mjs

@@ -0,0 +1,482 @@
+#!/usr/bin/env node
+
+import { execFile } from 'node:child_process'
+import { realpathSync } from 'node:fs'
+import {
+  access,
+  cp,
+  mkdir,
+  readdir,
+  readFile,
+  rename,
+  rm,
+  rmdir,
+  writeFile,
+} from 'node:fs/promises'
+import path from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { promisify } from 'node:util'
+import { fnPruneLockfileDependencies } from './lockfile.mjs'
+
+const fnExecFile = promisify(execFile)
+const strCurrentDirectory = path.dirname(fileURLToPath(import.meta.url))
+const strDefaultTemplateRoot = path.resolve(strCurrentDirectory, '../..')
+const arrExcludedRootEntries = new Set([
+  '.artifacts',
+  '.claude',
+  '.eslintcache',
+  '.git',
+  '.gitnexus',
+  '.gstack',
+  '.scaffold-state.json',
+  '.tanstack',
+  'AGENTS.md',
+  'CLAUDE.md',
+  'dist',
+  'node_modules',
+  'packages',
+])
+const arrExcludedRelativePaths = new Set(['.husky/_'])
+const arrExcludedFileNames = new Set(['.DS_Store'])
+const arrGeneratorPaths = [
+  'tests/unit/config/scaffoldProject.test.mjs',
+  'tests/unit/config/npmPackage.test.mjs',
+  'tools/scaffold/add-capability.mjs',
+  'tools/scaffold/capability-catalog.json',
+  'tools/scaffold/create-project.mjs',
+  'tools/scaffold/lockfile.mjs',
+]
+
+class ScaffoldCreateError extends Error {
+  constructor(strCode, strMessage) {
+    super(strMessage)
+    this.name = 'ScaffoldCreateError'
+    this.strCode = strCode
+  }
+}
+
+const fnReadJson = async (strFilePath) => {
+  try {
+    return JSON.parse(await readFile(strFilePath, 'utf8'))
+  } catch (objError) {
+    throw new ScaffoldCreateError(
+      'SCAFFOLD_CREATE_SOURCE_INVALID',
+      `无法读取模板文件 ${strFilePath}：${objError instanceof Error ? objError.message : '未知错误'}`
+    )
+  }
+}
+
+const fnSerializeJson = (objValue) => `${JSON.stringify(objValue, null, 2)}\n`
+
+const fnFormatJson = (objValue) => fnSerializeJson(objValue)
+
+const fnPruneLockfile = async (
+  strProjectRoot,
+  objRemovedDependencies,
+  objRemovedOverrides
+) => {
+  const strLockfilePath = path.join(strProjectRoot, 'pnpm-lock.yaml')
+  const strLockfile = await readFile(strLockfilePath, 'utf8')
+  await writeFile(
+    strLockfilePath,
+    fnPruneLockfileDependencies(
+      strLockfile,
+      objRemovedDependencies,
+      objRemovedOverrides
+    )
+  )
+}
+
+const fnIsInside = (strParentPath, strCandidatePath) => {
+  const strRelativePath = path.relative(strParentPath, strCandidatePath)
+  return (
+    strRelativePath === '' ||
+    (!strRelativePath.startsWith('..') && !path.isAbsolute(strRelativePath))
+  )
+}
+
+const fnAssertTargetAvailable = async (strTemplateRoot, strTargetRoot) => {
+  if (fnIsInside(strTemplateRoot, strTargetRoot)) {
+    throw new ScaffoldCreateError(
+      'SCAFFOLD_CREATE_TARGET_INVALID',
+      '目标目录不能位于模板源码目录内部。'
+    )
+  }
+  try {
+    await access(strTargetRoot)
+    throw new ScaffoldCreateError(
+      'SCAFFOLD_CREATE_TARGET_EXISTS',
+      `目标目录已存在：${strTargetRoot}`
+    )
+  } catch (objError) {
+    if (objError instanceof ScaffoldCreateError) throw objError
+  }
+}
+
+const fnReadCatalog = async (strTemplateRoot) => {
+  const objCatalog = await fnReadJson(
+    path.join(strTemplateRoot, 'tools/scaffold/capability-catalog.json')
+  )
+  if (
+    objCatalog.nSchemaVersion !== 1 ||
+    !objCatalog.objProfiles ||
+    !objCatalog.objCapabilities
+  ) {
+    throw new ScaffoldCreateError(
+      'SCAFFOLD_CREATE_SOURCE_INVALID',
+      '能力清单版本或结构无效。'
+    )
+  }
+  return objCatalog
+}
+
+/** 本地生成与 npm 打包共用模板复制边界，不包含维护包与构建产物。 */
+export const fnCopyTemplate = async (strTemplateRoot, strStagingRoot) => {
+  await cp(strTemplateRoot, strStagingRoot, {
+    recursive: true,
+    filter: (strSourcePath) => {
+      const strRelativePath = path.relative(strTemplateRoot, strSourcePath)
+      if (!strRelativePath) return true
+      const strRootEntry = strRelativePath.split(path.sep)[0]
+      const strPortableRelativePath = strRelativePath.split(path.sep).join('/')
+      return (
+        !arrExcludedRootEntries.has(strRootEntry) &&
+        !arrExcludedRelativePaths.has(strPortableRelativePath) &&
+        !arrExcludedFileNames.has(path.basename(strSourcePath))
+      )
+    },
+  })
+}
+
+const fnPruneEmptyDirectories = async (strRootPath) => {
+  const fnPruneDirectory = async (strDirectoryPath) => {
+    const arrEntries = await readdir(strDirectoryPath, { withFileTypes: true })
+    await Promise.all(
+      arrEntries
+        .filter((objEntry) => objEntry.isDirectory())
+        .map((objEntry) =>
+          fnPruneDirectory(path.join(strDirectoryPath, objEntry.name))
+        )
+    )
+    if ((await readdir(strDirectoryPath)).length === 0) {
+      await rmdir(strDirectoryPath)
+    }
+  }
+
+  const arrRootEntries = await readdir(strRootPath, { withFileTypes: true })
+  await Promise.all(
+    arrRootEntries
+      .filter((objEntry) => objEntry.isDirectory())
+      .map((objEntry) =>
+        fnPruneDirectory(path.join(strRootPath, objEntry.name))
+      )
+  )
+}
+
+const fnRemovePaths = async (strProjectRoot, arrRelativePaths) => {
+  await Promise.all(
+    arrRelativePaths.map((strRelativePath) =>
+      rm(path.join(strProjectRoot, strRelativePath), {
+        force: true,
+        recursive: true,
+      })
+    )
+  )
+}
+
+const fnRestorePackagedDotfiles = async (strProjectRoot) => {
+  try {
+    await rename(
+      path.join(strProjectRoot, 'gitignore'),
+      path.join(strProjectRoot, '.gitignore')
+    )
+  } catch (objError) {
+    if (objError?.code !== 'ENOENT') throw objError
+  }
+}
+
+const fnUpdatePackage = async (
+  strProjectRoot,
+  arrInactiveCapabilities,
+  objCapabilities
+) => {
+  const strPackagePath = path.join(strProjectRoot, 'package.json')
+  const objPackage = await fnReadJson(strPackagePath)
+  for (const strCapability of arrInactiveCapabilities) {
+    const objCapability = objCapabilities[strCapability]
+    for (const strDependency of Object.keys(objCapability.objDependencies)) {
+      delete objPackage.dependencies?.[strDependency]
+    }
+    for (const strPackageName of Object.keys(
+      objCapability.objPnpm?.allowedDeprecatedVersions ?? {}
+    )) {
+      delete objPackage.pnpm?.allowedDeprecatedVersions?.[strPackageName]
+    }
+    for (const strOverride of Object.keys(
+      objCapability.objPnpm?.overrides ?? {}
+    )) {
+      delete objPackage.pnpm?.overrides?.[strOverride]
+    }
+  }
+  if (
+    objPackage.pnpm?.allowedDeprecatedVersions &&
+    Object.keys(objPackage.pnpm.allowedDeprecatedVersions).length === 0
+  ) {
+    delete objPackage.pnpm.allowedDeprecatedVersions
+  }
+  delete objPackage.scripts?.['scaffold:add']
+  delete objPackage.scripts?.['scaffold:create']
+  await writeFile(
+    strPackagePath,
+    await fnFormatJson(objPackage, strPackagePath)
+  )
+}
+
+const fnUpdateComponentGovernance = async (
+  strProjectRoot,
+  arrInactiveCapabilities,
+  objCapabilities
+) => {
+  const strManifestPath = path.join(
+    strProjectRoot,
+    'tools/component-governance/manifest.json'
+  )
+  const objManifest = await fnReadJson(strManifestPath)
+  const objRemovedComponents = new Set(
+    arrInactiveCapabilities.flatMap(
+      (strCapability) => objCapabilities[strCapability].arrGovernedComponents
+    )
+  )
+  const objRemovedPackages = new Set(
+    arrInactiveCapabilities.flatMap(
+      (strCapability) => objCapabilities[strCapability].arrGovernedPackages
+    )
+  )
+  objManifest.components = objManifest.components.filter(
+    (objComponent) => !objRemovedComponents.has(objComponent.name)
+  )
+  objManifest.thirdParty = objManifest.thirdParty.filter(
+    (objPackage) => !objRemovedPackages.has(objPackage.packageName)
+  )
+  await writeFile(
+    strManifestPath,
+    await fnFormatJson(objManifest, strManifestPath)
+  )
+}
+
+const fnInstallDependencies = async (strProjectRoot) => {
+  try {
+    await fnExecFile('pnpm', ['install'], {
+      cwd: strProjectRoot,
+      maxBuffer: 10 * 1024 * 1024,
+    })
+  } catch (objError) {
+    throw new ScaffoldCreateError(
+      'SCAFFOLD_CREATE_INSTALL_FAILED',
+      `依赖安装失败：${objError instanceof Error ? objError.message : '未知错误'}`
+    )
+  }
+}
+
+/** 从完整能力源创建一个 core 或 full 项目。 */
+export async function fnCreateScaffoldProject({
+  bInstall = true,
+  strProfile = 'core',
+  strTargetRoot,
+  strTemplateRoot = strDefaultTemplateRoot,
+}) {
+  if (!strTargetRoot) {
+    throw new ScaffoldCreateError(
+      'SCAFFOLD_CREATE_ARGUMENT_INVALID',
+      '缺少目标目录。'
+    )
+  }
+  const strResolvedTemplateRoot = path.resolve(strTemplateRoot)
+  const strResolvedTargetRoot = path.resolve(strTargetRoot)
+  await fnAssertTargetAvailable(strResolvedTemplateRoot, strResolvedTargetRoot)
+  const objCatalog = await fnReadCatalog(strResolvedTemplateRoot)
+  const arrActiveCapabilities = objCatalog.objProfiles[strProfile]
+  if (!arrActiveCapabilities) {
+    throw new ScaffoldCreateError(
+      'SCAFFOLD_CREATE_PROFILE_INVALID',
+      `不支持生成档位 ${strProfile}。`
+    )
+  }
+  const objActiveCapabilities = new Set(arrActiveCapabilities)
+  const arrInactiveCapabilities = Object.keys(
+    objCatalog.objCapabilities
+  ).filter((strCapability) => !objActiveCapabilities.has(strCapability))
+  const objRemovedDependencies = new Set(
+    arrInactiveCapabilities.flatMap((strCapability) =>
+      Object.keys(objCatalog.objCapabilities[strCapability].objDependencies)
+    )
+  )
+  const objRemovedOverrides = new Set(
+    arrInactiveCapabilities.flatMap((strCapability) =>
+      Object.keys(
+        objCatalog.objCapabilities[strCapability].objPnpm?.overrides ?? {}
+      )
+    )
+  )
+  const strStagingRoot = `${strResolvedTargetRoot}.scaffold-create-${process.pid}`
+
+  try {
+    await fnCopyTemplate(strResolvedTemplateRoot, strStagingRoot)
+    await fnRestorePackagedDotfiles(strStagingRoot)
+    await fnRemovePaths(
+      strStagingRoot,
+      arrInactiveCapabilities.flatMap(
+        (strCapability) => objCatalog.objCapabilities[strCapability].arrPaths
+      )
+    )
+    await fnRemovePaths(strStagingRoot, arrGeneratorPaths)
+    await fnUpdatePackage(
+      strStagingRoot,
+      arrInactiveCapabilities,
+      objCatalog.objCapabilities
+    )
+    await fnPruneLockfile(
+      strStagingRoot,
+      objRemovedDependencies,
+      objRemovedOverrides
+    )
+    await fnUpdateComponentGovernance(
+      strStagingRoot,
+      arrInactiveCapabilities,
+      objCatalog.objCapabilities
+    )
+    const objTemplateState = await fnReadJson(
+      path.join(strStagingRoot, 'scaffold.template.json')
+    )
+    await writeFile(
+      path.join(strStagingRoot, '.scaffold-state.json'),
+      await fnFormatJson(
+        {
+          nSchemaVersion: 1,
+          strProfile,
+          strTemplateId: objTemplateState.strTemplateId,
+          strTemplateVersion: objTemplateState.strAppliedVersion,
+          arrActiveCapabilities,
+        },
+        path.join(strStagingRoot, '.scaffold-state.json')
+      )
+    )
+    await fnPruneEmptyDirectories(strStagingRoot)
+    if (bInstall) await fnInstallDependencies(strStagingRoot)
+    await mkdir(path.dirname(strResolvedTargetRoot), { recursive: true })
+    await rename(strStagingRoot, strResolvedTargetRoot)
+  } catch (objError) {
+    await rm(strStagingRoot, { force: true, recursive: true })
+    if (objError instanceof ScaffoldCreateError) throw objError
+    throw new ScaffoldCreateError(
+      'SCAFFOLD_CREATE_FAILED',
+      objError instanceof Error ? objError.message : '项目生成失败。'
+    )
+  }
+
+  return {
+    arrActiveCapabilities,
+    bInstall,
+    strProfile,
+    strTargetRoot: strResolvedTargetRoot,
+  }
+}
+
+const fnParseArguments = (arrArguments) => {
+  let bHelp = false
+  let bInstall = true
+  let strProfile = 'core'
+  let strTargetRoot
+
+  for (let nIndex = 0; nIndex < arrArguments.length; nIndex += 1) {
+    const strArgument = arrArguments[nIndex]
+    if (strArgument === '--' && nIndex === 0) continue
+    if (strArgument === '--help' || strArgument === '-h') {
+      bHelp = true
+      continue
+    }
+    if (strArgument === '--skip-install') {
+      bInstall = false
+      continue
+    }
+    if (strArgument === '--profile' || strArgument === '--target') {
+      const strValue = arrArguments[nIndex + 1]
+      if (!strValue || strValue.startsWith('--')) {
+        throw new ScaffoldCreateError(
+          'SCAFFOLD_CREATE_ARGUMENT_INVALID',
+          `${strArgument} 必须提供值。`
+        )
+      }
+      if (strArgument === '--profile') strProfile = strValue
+      else strTargetRoot = strValue
+      nIndex += 1
+      continue
+    }
+    if (!strArgument.startsWith('-') && !strTargetRoot) {
+      strTargetRoot = strArgument
+      continue
+    }
+    throw new ScaffoldCreateError(
+      'SCAFFOLD_CREATE_ARGUMENT_INVALID',
+      `不支持参数 ${strArgument}。`
+    )
+  }
+  return { bHelp, bInstall, strProfile, strTargetRoot }
+}
+
+const fnPrintUsage = () => {
+  process.stdout.write(
+    [
+      '用法：',
+      '  pnpm create react-admin-template@latest <目录>',
+      '  pnpm create react-admin-template@latest <目录> --profile full',
+      '  pnpm dlx create-react-admin-template@latest <目录>',
+      '  pnpm scaffold:create --target <目录>',
+      '  pnpm scaffold:create --target <目录> --profile full',
+      '',
+      '默认生成 core 项目并安装依赖；使用 --skip-install 可跳过安装。',
+      '',
+    ].join('\n')
+  )
+}
+
+export const fnRunCli = async () => {
+  try {
+    const objArguments = fnParseArguments(process.argv.slice(2))
+    if (objArguments.bHelp) {
+      fnPrintUsage()
+      return
+    }
+    const objResult = await fnCreateScaffoldProject(objArguments)
+    process.stdout.write(
+      `[PASS] SCAFFOLD_CREATED ${objResult.strProfile} 项目已创建：${objResult.strTargetRoot}\n`
+    )
+    if (!objResult.bInstall) {
+      process.stdout.write('下一步：进入目标目录执行 pnpm install。\n')
+    }
+  } catch (objError) {
+    const strCode =
+      objError instanceof ScaffoldCreateError
+        ? objError.strCode
+        : 'SCAFFOLD_CREATE_FAILED'
+    const strMessage =
+      objError instanceof Error ? objError.message : '项目生成失败。'
+    process.stderr.write(`[ERROR] ${strCode} ${strMessage}\n`)
+    process.exitCode = 1
+  }
+}
+
+const fnIsDirectExecution = () => {
+  try {
+    return (
+      realpathSync(process.argv[1] ?? '') ===
+      realpathSync(fileURLToPath(import.meta.url))
+    )
+  } catch {
+    return false
+  }
+}
+
+if (fnIsDirectExecution()) {
+  await fnRunCli()
+}

package/template/tools/scaffold/init.example.json

@@ -0,0 +1,64 @@
+{
+  "nSchemaVersion": 1,
+  "package": {
+    "name": "acme-operations-admin",
+    "description": "Acme 运营管理控制台",
+    "version": "0.1.0"
+  },
+  "runtimeConfig": {
+    "nSchemaVersion": 1,
+    "app": {
+      "strBrandId": "acme-operations",
+      "strTitle": "Acme Operations",
+      "strDescription": "Acme 运营管理控制台",
+      "strLogoPath": "logo.svg",
+      "strDarkLogoPath": "logo.svg",
+      "strFaviconPath": "favicon.ico",
+      "objTheme": {
+        "objLight": {
+          "strPrimaryColor": "#4068d5",
+          "strPrimaryForegroundColor": "#ffffff",
+          "strSecondaryColor": "#49beff",
+          "strSecondaryForegroundColor": "#102a43",
+          "strBrowserThemeColor": "#ffffff"
+        },
+        "objDark": {
+          "strPrimaryColor": "#8aadff",
+          "strPrimaryForegroundColor": "#0f172a",
+          "strSecondaryColor": "#49beff",
+          "strSecondaryForegroundColor": "#102a43",
+          "strBrowserThemeColor": "#000000"
+        }
+      },
+      "strStorageNamespace": "acme-operations-admin",
+      "strMode": "connected"
+    },
+    "api": {
+      "strBaseUrl": ""
+    },
+    "auth": {
+      "strAudience": "acme-operations-api",
+      "strClientId": "acme-operations-web",
+      "strScope": "openid profile offline_access",
+      "strSessionStorage": "memory",
+      "strSignInPath": "/api/v1/auth/login",
+      "strRefreshPath": "/api/v1/auth/refresh",
+      "strSignOutPath": "/api/v1/auth/logout"
+    },
+    "locale": {
+      "strLocale": "zh-CN",
+      "strTimeZone": "Asia/Shanghai"
+    },
+    "observability": {
+      "bEnabled": false,
+      "strEnvironment": "local"
+    }
+  },
+  "apiServices": [
+    {
+      "name": "operations",
+      "baseUrlEnv": "VITE_API_BASE_URL",
+      "openapiPath": "/swagger/openapi.json"
+    }
+  ]
+}