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

package/template/tools/scaffold/init.mjs

@@ -0,0 +1,419 @@
+import { createServer } from 'vite'
+import { z } from 'zod'
+import { lstat, readFile } from 'node:fs/promises'
+import path from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { fnCommitFileReplacementTransaction } from './workspace-transaction.mjs'
+
+const strCurrentDirectory = path.dirname(fileURLToPath(import.meta.url))
+const strDefaultProjectRoot = path.resolve(strCurrentDirectory, '../..')
+const arrTargetDefinitions = [
+  {
+    strConfigKey: 'package',
+    strRelativePath: 'package.json',
+  },
+  {
+    strConfigKey: 'runtimeConfig',
+    strRelativePath: 'public/runtime-config.json',
+  },
+  {
+    strConfigKey: 'apiServices',
+    strRelativePath: 'src/api/config/services.json',
+  },
+]
+
+const objPackageNamePattern =
+  /^(?:@[a-z0-9][a-z0-9._-]*\/)?[a-z0-9][a-z0-9._-]*$/
+const objServiceNamePattern = /^[a-z][a-z0-9-]*$/
+const objEnvironmentNamePattern = /^VITE_[A-Z0-9_]+$/
+
+const objPackageInitializationSchema = z
+  .object({
+    name: z.string().trim().min(1).max(214).regex(objPackageNamePattern),
+    description: z.string().trim().min(1).max(300),
+    version: z
+      .string()
+      .trim()
+      .regex(/^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)$/)
+      .optional(),
+  })
+  .strict()
+
+const objApiServiceSchema = z
+  .object({
+    name: z.string().trim().regex(objServiceNamePattern),
+    baseUrlEnv: z
+      .string()
+      .trim()
+      .regex(objEnvironmentNamePattern)
+      .default('VITE_API_BASE_URL'),
+    openapiPath: z.string().trim().startsWith('/'),
+  })
+  .strict()
+
+const objInitializationSchema = z
+  .object({
+    nSchemaVersion: z.literal(1),
+    package: objPackageInitializationSchema,
+    runtimeConfig: z.unknown(),
+    apiServices: z.array(objApiServiceSchema).min(1),
+  })
+  .strict()
+  .superRefine((objConfig, objContext) => {
+    const objNames = new Set()
+    objConfig.apiServices.forEach((objService, nIndex) => {
+      if (objNames.has(objService.name)) {
+        objContext.addIssue({
+          code: 'custom',
+          message: `API 服务名重复：${objService.name}`,
+          path: ['apiServices', nIndex, 'name'],
+        })
+      }
+      objNames.add(objService.name)
+    })
+  })
+
+class ScaffoldInitializationError extends Error {
+  constructor(strCode, strMessage) {
+    super(strMessage)
+    this.name = 'ScaffoldInitializationError'
+    this.strCode = strCode
+  }
+}
+
+const fnFormatIssues = (arrIssues) =>
+  arrIssues
+    .map(
+      (objIssue) => `${objIssue.path.join('.') || 'root'}: ${objIssue.message}`
+    )
+    .join('; ')
+
+const fnReadJson = async (strFilePath, strCode) => {
+  try {
+    return JSON.parse(await readFile(strFilePath, 'utf8'))
+  } catch (objError) {
+    const strReason =
+      objError instanceof Error ? ` 原因：${objError.message}` : ''
+    throw new ScaffoldInitializationError(
+      strCode,
+      `无法读取有效 JSON：${strFilePath}。${strReason}`
+    )
+  }
+}
+
+const fnAssertRegularTarget = async (strProjectRoot, strRelativePath) => {
+  const strTargetPath = path.resolve(strProjectRoot, strRelativePath)
+  const strRelativeTarget = path.relative(strProjectRoot, strTargetPath)
+  if (
+    strRelativeTarget.startsWith('..') ||
+    path.isAbsolute(strRelativeTarget)
+  ) {
+    throw new ScaffoldInitializationError(
+      'SCAFFOLD_INIT_TARGET_INVALID',
+      `目标文件超出项目目录：${strRelativePath}。`
+    )
+  }
+
+  let objStats
+  try {
+    objStats = await lstat(strTargetPath)
+  } catch (objError) {
+    const strReason =
+      objError instanceof Error ? ` 原因：${objError.message}` : ''
+    throw new ScaffoldInitializationError(
+      'SCAFFOLD_INIT_TARGET_INVALID',
+      `初始化目标不存在：${strRelativePath}。${strReason}`
+    )
+  }
+  if (!objStats.isFile() || objStats.isSymbolicLink()) {
+    throw new ScaffoldInitializationError(
+      'SCAFFOLD_INIT_TARGET_INVALID',
+      `初始化目标必须是普通文件且不能是符号链接：${strRelativePath}。`
+    )
+  }
+  return { nMode: objStats.mode, strTargetPath }
+}
+
+const fnValidateRuntimeConfig = async (objRuntimeConfig) => {
+  let objViteServer
+  try {
+    objViteServer = await createServer({
+      appType: 'custom',
+      configFile: false,
+      logLevel: 'silent',
+      root: strDefaultProjectRoot,
+      server: { middlewareMode: true },
+    })
+    const { fnParseRuntimeConfig } = await objViteServer.ssrLoadModule(
+      '/src/config/runtimeConfig.ts'
+    )
+    return fnParseRuntimeConfig(objRuntimeConfig)
+  } catch (objError) {
+    throw new ScaffoldInitializationError(
+      'SCAFFOLD_INIT_CONFIG_INVALID',
+      objError instanceof Error
+        ? objError.message
+        : 'runtimeConfig 不符合运行时配置契约。'
+    )
+  } finally {
+    await objViteServer?.close()
+  }
+}
+
+const fnValidateInitializationConfig = async (objInput) => {
+  const objResult = objInitializationSchema.safeParse(objInput)
+  if (!objResult.success) {
+    throw new ScaffoldInitializationError(
+      'SCAFFOLD_INIT_CONFIG_INVALID',
+      `初始化配置不符合契约：${fnFormatIssues(objResult.error.issues)}`
+    )
+  }
+
+  return {
+    ...objResult.data,
+    runtimeConfig: await fnValidateRuntimeConfig(objResult.data.runtimeConfig),
+  }
+}
+
+const fnIsEqual = (objBefore, objAfter) =>
+  JSON.stringify(objBefore) === JSON.stringify(objAfter)
+
+const fnCollectChangedPaths = (objBefore, objAfter, strPrefix = '') => {
+  if (fnIsEqual(objBefore, objAfter)) return []
+  if (
+    objBefore === null ||
+    objAfter === null ||
+    typeof objBefore !== 'object' ||
+    typeof objAfter !== 'object' ||
+    Array.isArray(objBefore) !== Array.isArray(objAfter)
+  ) {
+    return [strPrefix || 'root']
+  }
+
+  const arrKeys = Array.from(
+    new Set([...Object.keys(objBefore), ...Object.keys(objAfter)])
+  ).sort()
+  return arrKeys.flatMap((strKey) => {
+    const strPath = Array.isArray(objAfter)
+      ? `${strPrefix}[${strKey}]`
+      : strPrefix
+        ? `${strPrefix}.${strKey}`
+        : strKey
+    return fnCollectChangedPaths(objBefore[strKey], objAfter[strKey], strPath)
+  })
+}
+
+const fnSerializeJson = (objValue) => `${JSON.stringify(objValue, null, 2)}\n`
+
+const fnCreateTargetPlans = async (strProjectRoot, objConfig) => {
+  const arrPlans = []
+  for (const objDefinition of arrTargetDefinitions) {
+    const { nMode, strTargetPath } = await fnAssertRegularTarget(
+      strProjectRoot,
+      objDefinition.strRelativePath
+    )
+    const objBefore = await fnReadJson(
+      strTargetPath,
+      'SCAFFOLD_INIT_TARGET_INVALID'
+    )
+    let objAfter
+    if (objDefinition.strConfigKey === 'package') {
+      objAfter = {
+        ...objBefore,
+        name: objConfig.package.name,
+        description: objConfig.package.description,
+        ...(objConfig.package.version
+          ? { version: objConfig.package.version }
+          : {}),
+      }
+    } else {
+      objAfter = objConfig[objDefinition.strConfigKey]
+    }
+
+    arrPlans.push({
+      arrChangedPaths: fnCollectChangedPaths(objBefore, objAfter),
+      nMode,
+      strContent: fnSerializeJson(objAfter),
+      strRelativePath: objDefinition.strRelativePath,
+      strTargetPath,
+    })
+  }
+  return arrPlans
+}
+
+const fnWriteTransaction = async (arrPlans) => {
+  const arrChangedPlans = arrPlans.filter(
+    (objPlan) => objPlan.arrChangedPaths.length > 0
+  )
+  await fnCommitFileReplacementTransaction({
+    arrPlans: arrChangedPlans,
+    fnCreateError: (objError) =>
+      new ScaffoldInitializationError(
+        'SCAFFOLD_INIT_WRITE_FAILED',
+        objError instanceof Error
+          ? `写入失败并已回滚：${objError.message}`
+          : '写入失败并已回滚。'
+      ),
+    strTransactionName: 'scaffold-init',
+  })
+}
+
+/**
+ * 根据严格初始化清单生成三个稳定配置文件；默认只返回预览，写入必须显式开启。
+ */
+export async function fnInitializeScaffold({
+  bWrite = false,
+  strConfigPath,
+  strProjectRoot = strDefaultProjectRoot,
+}) {
+  if (!strConfigPath) {
+    throw new ScaffoldInitializationError(
+      'SCAFFOLD_INIT_ARGUMENT_INVALID',
+      '缺少 --config <path>。'
+    )
+  }
+
+  const strResolvedProjectRoot = path.resolve(strProjectRoot)
+  const strResolvedConfigPath = path.resolve(strConfigPath)
+  const objInput = await fnReadJson(
+    strResolvedConfigPath,
+    'SCAFFOLD_INIT_CONFIG_INVALID'
+  )
+  const objConfig = await fnValidateInitializationConfig(objInput)
+  const arrPlans = await fnCreateTargetPlans(strResolvedProjectRoot, objConfig)
+  if (bWrite) await fnWriteTransaction(arrPlans)
+
+  return {
+    arrTargets: arrPlans.map((objPlan) => ({
+      arrChangedPaths: objPlan.arrChangedPaths,
+      bChanged: objPlan.arrChangedPaths.length > 0,
+      strRelativePath: objPlan.strRelativePath,
+    })),
+    bWrite,
+  }
+}
+
+const fnParseArguments = (arrArguments) => {
+  let bHelp = false
+  let bWrite = false
+  let strConfigPath
+
+  for (let nIndex = 0; nIndex < arrArguments.length; nIndex += 1) {
+    const strArgument = arrArguments[nIndex]
+    if (strArgument === '--' && nIndex === 0) continue
+    if (strArgument === '--help') {
+      bHelp = true
+      continue
+    }
+    if (strArgument === '--write') {
+      if (bWrite) {
+        throw new ScaffoldInitializationError(
+          'SCAFFOLD_INIT_ARGUMENT_INVALID',
+          '--write 不能重复声明。'
+        )
+      }
+      bWrite = true
+      continue
+    }
+    if (strArgument === '--config') {
+      if (strConfigPath) {
+        throw new ScaffoldInitializationError(
+          'SCAFFOLD_INIT_ARGUMENT_INVALID',
+          '--config 不能重复声明。'
+        )
+      }
+      const strValue = arrArguments[nIndex + 1]
+      if (!strValue || strValue.startsWith('--')) {
+        throw new ScaffoldInitializationError(
+          'SCAFFOLD_INIT_ARGUMENT_INVALID',
+          '--config 必须提供文件路径。'
+        )
+      }
+      strConfigPath = strValue
+      nIndex += 1
+      continue
+    }
+    throw new ScaffoldInitializationError(
+      'SCAFFOLD_INIT_ARGUMENT_INVALID',
+      `不支持参数 ${strArgument}。`
+    )
+  }
+
+  if (bHelp && (bWrite || strConfigPath)) {
+    throw new ScaffoldInitializationError(
+      'SCAFFOLD_INIT_ARGUMENT_INVALID',
+      '--help 不能与其他参数组合。'
+    )
+  }
+  return { bHelp, bWrite, strConfigPath }
+}
+
+const fnPrintUsage = () => {
+  process.stdout.write(
+    [
+      '用法：',
+      '  pnpm scaffold:init --config <path>',
+      '  pnpm scaffold:init --config <path> --write',
+      '',
+      '默认只预览；只有 --write 会更新 package.json 的项目元数据、runtime-config.json 和 API 服务清单。',
+      '',
+    ].join('\n')
+  )
+}
+
+const fnPrintResult = (objResult) => {
+  const strMode = objResult.bWrite ? 'WRITE' : 'PREVIEW'
+  for (const objTarget of objResult.arrTargets) {
+    if (!objTarget.bChanged) {
+      process.stdout.write(
+        `[${strMode}] UNCHANGED ${objTarget.strRelativePath}\n`
+      )
+      continue
+    }
+    process.stdout.write(
+      `[${strMode}] ${objResult.bWrite ? 'UPDATED' : 'UPDATE'} ${objTarget.strRelativePath}\n`
+    )
+    process.stdout.write(
+      `          字段：${objTarget.arrChangedPaths.join(', ')}\n`
+    )
+  }
+
+  const nChanges = objResult.arrTargets.filter(
+    (objTarget) => objTarget.bChanged
+  ).length
+  if (objResult.bWrite) {
+    process.stdout.write(`\n脚手架初始化完成：更新 ${nChanges} 个文件。\n`)
+    process.stdout.write('下一步：执行 pnpm scaffold:check --strict。\n')
+  } else {
+    process.stdout.write(`\n脚手架初始化预览：${nChanges} 个文件将更新。\n`)
+    process.stdout.write('确认后追加 --write；当前没有修改任何文件。\n')
+  }
+}
+
+const fnRunCli = async () => {
+  try {
+    const objArguments = fnParseArguments(process.argv.slice(2))
+    if (objArguments.bHelp) {
+      fnPrintUsage()
+      return
+    }
+    const objResult = await fnInitializeScaffold({
+      bWrite: objArguments.bWrite,
+      strConfigPath: objArguments.strConfigPath,
+    })
+    fnPrintResult(objResult)
+  } catch (objError) {
+    const strCode =
+      objError instanceof ScaffoldInitializationError
+        ? objError.strCode
+        : 'SCAFFOLD_INIT_FAILED'
+    const strMessage =
+      objError instanceof Error ? objError.message : '脚手架初始化失败。'
+    process.stderr.write(`[ERROR] ${strCode} ${strMessage}\n`)
+    process.exitCode = 1
+  }
+}
+
+if (path.resolve(process.argv[1] ?? '') === fileURLToPath(import.meta.url)) {
+  await fnRunCli()
+}

package/template/tools/scaffold/lockfile.mjs

@@ -0,0 +1,193 @@
+const objDependencyLinePattern =
+  /^ {6}(?:'(?<strQuotedName>[^']+)'|(?<strPlainName>[^:]+)):\s*$/
+const objOverrideLinePattern =
+  /^ {2}(?:'(?<strQuotedName>[^']+)'|(?<strPlainName>[^:]+)):\s+.+$/
+
+const fnFindTopLevelSection = (arrLines, strHeader) => {
+  const nSectionStart = arrLines.indexOf(strHeader)
+  if (nSectionStart < 0) return undefined
+
+  let nSectionEnd = nSectionStart + 1
+  while (nSectionEnd < arrLines.length && !/^\S/.test(arrLines[nSectionEnd])) {
+    nSectionEnd += 1
+  }
+  return { nSectionEnd, nSectionStart }
+}
+
+const fnFindRootDependencySection = (arrLines) => {
+  const nImporterStart = arrLines.indexOf('  .:')
+  if (nImporterStart < 0) return undefined
+
+  const nSectionStart = arrLines.indexOf(
+    '    dependencies:',
+    nImporterStart + 1
+  )
+  if (nSectionStart < 0) return undefined
+
+  let nSectionEnd = nSectionStart + 1
+  while (
+    nSectionEnd < arrLines.length &&
+    !/^ {4}\S/.test(arrLines[nSectionEnd]) &&
+    !/^ {2}\S/.test(arrLines[nSectionEnd]) &&
+    !/^\S/.test(arrLines[nSectionEnd])
+  ) {
+    nSectionEnd += 1
+  }
+  return { nSectionEnd, nSectionStart }
+}
+
+const fnReadDependencyBlocks = (arrLines, objSection) => {
+  const arrBlocks = []
+  for (
+    let nIndex = objSection.nSectionStart + 1;
+    nIndex < objSection.nSectionEnd;
+    nIndex += 1
+  ) {
+    const objMatch = arrLines[nIndex].match(objDependencyLinePattern)
+    if (!objMatch) continue
+
+    let nBlockEnd = nIndex + 1
+    while (
+      nBlockEnd < objSection.nSectionEnd &&
+      !objDependencyLinePattern.test(arrLines[nBlockEnd])
+    ) {
+      nBlockEnd += 1
+    }
+    arrBlocks.push({
+      arrLines: arrLines.slice(nIndex, nBlockEnd),
+      strName:
+        objMatch.groups?.strQuotedName ?? objMatch.groups?.strPlainName ?? '',
+    })
+    nIndex = nBlockEnd - 1
+  }
+  return arrBlocks
+}
+
+const fnReplaceDependencyBlocks = (strLockfile, fnSelectBlocks) => {
+  const bHasFinalNewline = strLockfile.endsWith('\n')
+  const arrLines = strLockfile.split('\n')
+  if (bHasFinalNewline) arrLines.pop()
+  const objSection = fnFindRootDependencySection(arrLines)
+  if (!objSection) return strLockfile
+
+  const arrBlocks = fnSelectBlocks(fnReadDependencyBlocks(arrLines, objSection))
+  const arrNextLines = [
+    ...arrLines.slice(0, objSection.nSectionStart + 1),
+    ...arrBlocks.flatMap((objBlock) => objBlock.arrLines),
+    ...arrLines.slice(objSection.nSectionEnd),
+  ]
+  return `${arrNextLines.join('\n')}${bHasFinalNewline ? '\n' : ''}`
+}
+
+const fnReadOverrideLines = (arrLines, objSection) =>
+  arrLines
+    .slice(objSection.nSectionStart + 1, objSection.nSectionEnd)
+    .map((strLine) => {
+      const objMatch = strLine.match(objOverrideLinePattern)
+      return objMatch
+        ? {
+            strLine,
+            strName:
+              objMatch.groups?.strQuotedName ??
+              objMatch.groups?.strPlainName ??
+              '',
+          }
+        : undefined
+    })
+    .filter(Boolean)
+
+const fnReplaceOverrideLines = (strLockfile, fnSelectLines) => {
+  const bHasFinalNewline = strLockfile.endsWith('\n')
+  const arrLines = strLockfile.split('\n')
+  if (bHasFinalNewline) arrLines.pop()
+  const objSection = fnFindTopLevelSection(arrLines, 'overrides:')
+  if (!objSection) return strLockfile
+
+  const arrNextOverrideLines = fnSelectLines(
+    fnReadOverrideLines(arrLines, objSection)
+  )
+  const arrNextLines = [
+    ...arrLines.slice(0, objSection.nSectionStart + 1),
+    ...arrNextOverrideLines.map(({ strLine }) => strLine),
+    ...arrLines.slice(objSection.nSectionEnd),
+  ]
+  return `${arrNextLines.join('\n')}${bHasFinalNewline ? '\n' : ''}`
+}
+
+/** 仅裁剪根 importer 的可选依赖，保留解析快照以维持版本可复现。 */
+export const fnPruneLockfileDependencies = (
+  strLockfile,
+  objRemovedDependencies,
+  objRemovedOverrides = new Set()
+) => {
+  const strPrunedDependencies = fnReplaceDependencyBlocks(
+    strLockfile,
+    (arrBlocks) =>
+      arrBlocks.filter(
+        (objBlock) => !objRemovedDependencies.has(objBlock.strName)
+      )
+  )
+  return fnReplaceOverrideLines(strPrunedDependencies, (arrLines) =>
+    arrLines.filter((objLine) => !objRemovedOverrides.has(objLine.strName))
+  )
+}
+
+/** 从同版本完整模板恢复能力依赖的锁定条目。 */
+export const fnRestoreLockfileDependencies = (
+  strTargetLockfile,
+  strTemplateLockfile,
+  objRestoredDependencies,
+  objRestoredOverrides = new Set()
+) => {
+  const arrTargetLines = strTargetLockfile.split('\n')
+  const objTargetSection = fnFindRootDependencySection(arrTargetLines)
+  const arrTemplateLines = strTemplateLockfile.split('\n')
+  const objTemplateSection = fnFindRootDependencySection(arrTemplateLines)
+  if (!objTargetSection || !objTemplateSection) return strTargetLockfile
+
+  const arrTemplateBlocks = fnReadDependencyBlocks(
+    arrTemplateLines,
+    objTemplateSection
+  )
+  const strRestoredDependencies = fnReplaceDependencyBlocks(
+    strTargetLockfile,
+    (arrTargetBlocks) => {
+      const objTargetNames = new Set(
+        arrTargetBlocks.map((objBlock) => objBlock.strName)
+      )
+      return [
+        ...arrTargetBlocks,
+        ...arrTemplateBlocks.filter(
+          (objBlock) =>
+            objRestoredDependencies.has(objBlock.strName) &&
+            !objTargetNames.has(objBlock.strName)
+        ),
+      ]
+    }
+  )
+  const objTemplateOverrideSection = fnFindTopLevelSection(
+    arrTemplateLines,
+    'overrides:'
+  )
+  if (!objTemplateOverrideSection) return strRestoredDependencies
+  const arrTemplateOverrideLines = fnReadOverrideLines(
+    arrTemplateLines,
+    objTemplateOverrideSection
+  )
+  return fnReplaceOverrideLines(
+    strRestoredDependencies,
+    (arrTargetOverrides) => {
+      const objTargetNames = new Set(
+        arrTargetOverrides.map((objOverride) => objOverride.strName)
+      )
+      return [
+        ...arrTargetOverrides,
+        ...arrTemplateOverrideLines.filter(
+          (objOverride) =>
+            objRestoredOverrides.has(objOverride.strName) &&
+            !objTargetNames.has(objOverride.strName)
+        ),
+      ]
+    }
+  )
+}

package/template/tools/scaffold/templates/feature/index.ts

@@ -0,0 +1,19 @@
+export {
+  useTemplateRecordDetail,
+  useTemplateRecordList,
+  useUpdateTemplateRecord,
+} from './queries'
+export { fnCreateTemplateRecordFeature } from './repository'
+export type {
+  IConnectedTemplateRecordSource,
+  ICreateTemplateRecordFeatureOptions,
+  ITemplateRecord,
+  ITemplateRecordChanges,
+  ITemplateRecordFeature,
+  ITemplateRecordListInput,
+  ITemplateRecordPage,
+  ITemplateRecordUpdateCommand,
+  IUseTemplateRecordDetailOptions,
+  IUseTemplateRecordListOptions,
+  IUseUpdateTemplateRecordOptions,
+} from './types'