tha-cli 0.0.0-stage → 0.1.0

package/tha/commands/sync.mjs

@@ -0,0 +1,826 @@
+import * as readline from 'node:readline/promises'
+import fs from 'node:fs'
+import path from 'node:path'
+import { stdin, stdout } from 'node:process'
+import { loadProject } from '../config/project.mjs'
+import { relPath, absPath } from '../config/paths.mjs'
+import { manualPaths } from '../config/manifest.mjs'
+import { buildPlan } from '../generate/plan.mjs'
+import { comparePlan } from '../utils/compare.mjs'
+import { parseArgs } from '../utils/args.mjs'
+import {
+  exists,
+  generatedHeader,
+  isGenerated,
+  isEmptyDir,
+  listDirectories,
+  listFiles,
+  read,
+  removeDir,
+  removeFile,
+  splitGenerated,
+  writeAll
+} from '../utils/files.mjs'
+import { formatWritten } from '../utils/format.mjs'
+import { printDiff, printErrors, printHeader } from '../utils/output.mjs'
+import { glyph, ui } from '../utils/style.mjs'
+
+// 全局生成物：不属于任何单个模块，由所有模块共同决定
+function globalFileSet(dirs) {
+  return new Set([
+    relPath(dirs, 'router', 'routes.generated.ts'),
+    relPath(dirs, 'layouts', 'menu.generated.ts')
+  ])
+}
+
+export async function runSync({ root, args }) {
+  const { flags, positional } = parseArgs(args, {
+    boolean: ['json', 'help', 'force', 'dry-run', 'yes', 'all', 'prune', 'no-format']
+  })
+
+  if (flags.help) {
+    printSyncHelp()
+    return
+  }
+
+  const moduleName = positional[0]?.trim()
+
+  if (flags.all && moduleName) {
+    throw new Error('--all and a module name are exclusive (--all 不能和模块名一起用)')
+  }
+
+  const project = loadProject(root)
+
+  if (project.errors.length > 0) {
+    if (flags.json) {
+      console.log(JSON.stringify({ ok: false, errors: project.errors }, null, 2))
+    } else {
+      printErrors(project.errors)
+    }
+    process.exitCode = 1
+    return
+  }
+
+  // --prune 隐含全量：先清理残留，再重新生成
+  if (flags.prune) flags.all = true
+
+  // 不带模块、也没 --all：只列模块，一个文件都不写
+  if (!moduleName && !flags.all) {
+    printModuleList(project.domains, flags)
+    return
+  }
+
+  const target = moduleName
+    ? project.domains.find((domain) => domain.name === moduleName)
+    : null
+
+  if (moduleName && !target) {
+    throw new Error(`没有模块「${moduleName}」。可用：${project.domains.map((domain) => domain.name).join(' / ')}`)
+  }
+
+  const allEntries = comparePlan(buildPlan(project.domains, root, project.dirs), root, manualPaths(root))
+  const entries = moduleName
+    ? allEntries.filter((entry) => isTargetFile(entry.path, moduleName, project.dirs))
+    : allEntries
+
+  const configChanges = target ? readConfigChanges(root, target) : null
+  const residue = flags.prune ? findResidue(root, project.domains, project.dirs) : []
+
+  if (flags['dry-run']) {
+    if (flags.json) {
+      console.log(
+        JSON.stringify(
+          {
+            ok: true,
+            dryRun: true,
+            mode: moduleName ? 'one' : 'all',
+            module: moduleName ?? null,
+            configChanges,
+            prune: residue.map((item) => item.rel),
+            skippedPreview: previewSkipped(entries, project.domains, moduleName, flags.force, project.dirs),
+            files: entries.map((entry) => ({ path: entry.path, status: entry.status }))
+          },
+          null,
+          2
+        )
+      )
+    } else {
+      if (residue.length > 0) printResidue(residue)
+      printChanges(configChanges, entries, {
+        skipped: previewSkipped(entries, project.domains, moduleName, flags.force, project.dirs)
+      })
+    }
+    return
+  }
+
+  // ---- 先用 prune 清掉「模块删了，生成物还留着」的残留 ----
+  let pruned = []
+
+  if (residue.length > 0) {
+    if (!flags.json) printResidue(residue)
+
+    if (!flags.yes && !flags.json) {
+      const ok = await confirm(`${residue.length} leftovers to delete, delete them too? (有 ${residue.length} 个文件该删了，一起删掉？) [y/N] `)
+      if (!ok) throw new Error('prune cancelled, nothing deleted (已取消，没有删除残留，本次也没有生成)')
+    }
+
+    for (const item of residue) {
+      if (item.kind === 'dir') removeDir(path.join(root, item.rel))
+      else removeFile(path.join(root, item.rel))
+    }
+    pruned = residue.map((item) => item.rel)
+
+    // 文件删了，空目录还留着（src/pages/tmp、domains/tmp2/executors）→ 一路清到最近的非空目录
+    for (const item of residue) {
+      pruneEmptyDirs(path.dirname(path.join(root, item.rel)), root)
+    }
+
+    if (!flags.json) {
+      console.log(`  ${ui.success(glyph.ok)} ${ui.label(`已删掉 ${pruned.length} 个残留文件`, `${pruned.length} leftovers removed`)}`)
+      console.log('')
+    }
+  }
+
+  // --prune 是「清理残留」的显式动作：模块目录已经空掉的，也一起收掉
+  // （上一次 prune 只删了文件、留下空壳的情况，这次不该再留着）
+  if (flags.prune) pruneEmptyModuleDirs(root, project.dirs)
+
+  // ---- 计算写入计划：全量按模块隔离，一个模块冲突不拖垮其他模块 ----
+  const plan = []
+  const skipped = []
+
+  if (moduleName) {
+    // 单模块：保持旧语义——这一模块（含全局文件）有冲突就整体停下
+    const blocked = entries.filter(isBlocked)
+
+    if (blocked.length > 0 && !flags.force) {
+      printBlockedJsonOrText(blocked, flags)
+      process.exitCode = 1
+      return
+    }
+
+    plan.push(...entries.filter((entry) => isWritable(entry) || (flags.force && isBlocked(entry))))
+  } else {
+    const { groups, globalEntries } = groupEntries(entries, project.domains, project.dirs)
+
+    for (const group of groups) {
+      const blocked = group.entries.filter(isBlocked)
+
+      if (blocked.length > 0 && !flags.force) {
+        skipped.push({ module: group.domain.name, blocked })
+        continue
+      }
+
+      plan.push(
+        ...group.entries.filter((entry) => isWritable(entry) || (flags.force && isBlocked(entry)))
+      )
+    }
+
+    const globalBlocked = globalEntries.filter(isBlocked)
+
+    if (globalBlocked.length > 0 && !flags.force) {
+      skipped.push({ module: '全局路由/菜单', blocked: globalBlocked })
+    } else {
+      plan.push(
+        ...globalEntries.filter((entry) => isWritable(entry) || (flags.force && isBlocked(entry)))
+      )
+    }
+  }
+
+  if (plan.length === 0 && skipped.length === 0 && pruned.length === 0) {
+    if (flags.json) {
+      console.log(JSON.stringify({ ok: true, written: [], pruned: [] }, null, 2))
+    } else {
+      console.log('')
+      console.log(`  ${ui.success(glyph.ok)} ${ui.label('文件都是最新的，没有需要生成的内容', 'All files are up to date')}`)
+      console.log('')
+    }
+    return
+  }
+
+  if (!flags.json) {
+    printChanges(configChanges, entries, { skipped })
+  }
+
+  if (!flags.yes && !flags.json) {
+    if (!stdin.isTTY) {
+      console.error('Not a terminal, nothing written. Add --yes to write. (现在不是终端，没写入。要写入请加 --yes。)')
+      process.exitCode = 1
+      return
+    }
+
+    const scope = moduleName ? `模块 ${moduleName}` : `全部模块（${project.domains.length} 个）`
+    const ok = await confirm(`\nWrite these changes to ${scope}? (把这些变化写进 ${scope}？) [y/N] `)
+    if (!ok) {
+      console.log('Cancelled, nothing written (prune already applied). (已取消，没有写入，残留清理已生效)')
+      return
+    }
+  }
+
+  // 事务写入：全部落临时文件后再统一提交，失败不留半套
+  writeAll(plan)
+
+  // 格式化：项目装了 Prettier 才做，没有就跳过（不硬依赖）
+  const format = flags['no-format']
+    ? { formatted: false, reason: 'disabled' }
+    : formatWritten(root, plan.map((entry) => entry.path))
+
+  if (flags.json) {
+    console.log(
+      JSON.stringify(
+        {
+          ok: skipped.length === 0,
+          mode: moduleName ? 'one' : 'all',
+          module: moduleName ?? null,
+          configChanges,
+          written: plan.map((entry) => entry.path),
+          pruned,
+          formatted: format.formatted,
+          skipped: skipped.map((group) => ({
+            module: group.module,
+            blocked: group.blocked.map((entry) => ({ path: entry.path, status: entry.status }))
+          }))
+        },
+        null,
+        2
+      )
+    )
+    if (skipped.length > 0) process.exitCode = 1
+    return
+  }
+
+  console.log('')
+  console.log(
+    `  ${ui.success(glyph.ok)} ${ui.label(
+      `已生成 ${plan.length} 个文件`,
+      `${plan.length} files generated`
+    )}`
+  )
+
+  if (skipped.length > 0) {
+    console.log(
+      `  ${ui.warning(glyph.warn)} ${ui.label(
+        `跳过 ${skipped.length} 组：有文件挡住，没覆盖`,
+        `${skipped.length} groups skipped: conflicts left untouched`
+      )}`
+    )
+    for (const group of skipped) {
+      console.log(`    ${ui.path(group.module)}`)
+      for (const entry of group.blocked) {
+        console.log(`      ${ui.danger(glyph.warn)} ${ui.path(entry.path)}`)
+      }
+    }
+    console.log(`  ${ui.muted('To overwrite (确认覆盖请运行): tha sync --all --force')}`)
+    process.exitCode = 1
+  }
+
+  if (format.reason === 'prettier-not-installed') {
+    console.log(`  ${ui.muted('prettier not installed, files written but not formatted (没装 Prettier，文件写了但没格式化)')}`)
+  } else if (format.reason === 'prettier-failed') {
+    console.log(`  ${ui.muted('prettier failed, files written but not formatted (Prettier 执行失败，文件写了但没格式化)')}`)
+  }
+
+  console.log('')
+}
+
+/**
+ * 不带模块时的「只列不写」：模块清单 + 下一步用法
+ * @param domains 已校验通过的模块
+ * @param flags   命令行开关（--json）
+ */
+function printModuleList(domains, flags) {
+  if (flags.json) {
+    console.log(
+      JSON.stringify(
+        {
+          ok: true,
+          mode: 'list',
+          modules: domains.map((domain) => ({
+            name: domain.name,
+            title: domain.title,
+            path: domain.path
+          }))
+        },
+        null,
+        2
+      )
+    )
+    return
+  }
+
+  printHeader('模块列表', 'Modules')
+
+  if (domains.length === 0) {
+    console.log(`  ${ui.muted('No modules yet (还没有模块)')}  ${ui.command('tha init <模块>')}`)
+    console.log('')
+    return
+  }
+
+  for (const domain of domains) {
+    console.log(`  ${ui.path(domain.name.padEnd(14))} ${ui.label(domain.title, domain.path)}`)
+  }
+
+  console.log('')
+  console.log(`  ${ui.muted('Nothing is written without a module (不带模块不会写文件)')}`)
+  console.log(`    ${ui.bullet(`${ui.command('tha sync <模块>')}  ${ui.muted('one module (只更新一个模块)')}`)}`)
+  console.log(`    ${ui.bullet(`${ui.command('tha sync --all')}  ${ui.muted('all modules (更新全部模块)')}`)}`)
+  console.log(`    ${ui.bullet(`${ui.command('tha sync --all --prune')}  ${ui.muted('remove leftovers (清理已删模块的残留)')}`)}`)
+  console.log('')
+}
+
+/**
+ * 找出「模块已删除、生成物还在」的残留（只认 CLI 写过的文件，手写文件不动）
+ * @param root    项目根
+ * @param domains 现存模块
+ * @returns [{ rel, kind: 'file' | 'dir' }]
+ */
+/**
+ * 从 dir 逐级向上删空目录，遇到非空或越出项目根就停。
+ * 只清 prune 留下的空壳，不碰任何还有文件的目录。
+ */
+function pruneEmptyDirs(dir, root) {
+  let current = dir
+
+  while (true) {
+    const rel = path.relative(root, current)
+    if (rel === '' || rel.startsWith('..') || path.isAbsolute(rel)) return
+    if (!isEmptyDir(current)) return
+    removeDir(current)
+    current = path.dirname(current)
+  }
+}
+
+/**
+ * 递归清掉生成物目录（api / stores / domains / views）里的空目录，只保顶层本身。
+ */
+function pruneEmptyModuleDirs(root, dirs) {
+  for (const key of ['api', 'stores', 'domains', 'views']) {
+    const base = path.join(root, dirs[key])
+    if (exists(base)) sweeping(base, true)
+  }
+
+  function sweeping(dir, keepSelf) {
+    for (const entry of listDirectories(dir)) sweeping(path.join(dir, entry), false)
+    if (!keepSelf && isEmptyDir(dir)) removeDir(dir)
+  }
+}
+
+function findResidue(root, domains, dirs) {
+  const known = new Set(domains.map((domain) => domain.name))
+  const residue = []
+  const pushFile = (rel) => {
+    const full = path.join(root, rel)
+    if (exists(full) && isGenerated(read(full))) residue.push({ rel, kind: 'file' })
+  }
+
+  for (const file of listFiles(absPath(root, dirs, 'api'), '.ts')) {
+    pushFile(relPath(dirs, 'api', file))
+  }
+
+  for (const dir of listDirectories(absPath(root, dirs, 'stores'))) {
+    if (known.has(dir)) continue
+    pushFile(relPath(dirs, 'stores', dir, 'index.ts'))
+  }
+
+  for (const dir of listDirectories(absPath(root, dirs, 'views'))) {
+    if (known.has(dir)) continue
+    for (const file of listFiles(absPath(root, dirs, 'views', dir), '.vue')) {
+      pushFile(relPath(dirs, 'views', dir, file))
+    }
+  }
+
+  for (const dir of listDirectories(absPath(root, dirs, 'domains'))) {
+    if (known.has(dir)) continue
+    const configRel = relPath(dirs, 'domains', dir, 'config.ts')
+    if (exists(path.join(root, configRel))) continue
+
+    // 只清「目录里全是生成物」的；含手写文件（中枢/自定义执行器）时，只清其中的生成物
+    const domainRel = relPath(dirs, 'domains', dir)
+    if (onlyGenerated(root, domainRel)) {
+      residue.push({ rel: domainRel, kind: 'dir' })
+    } else {
+      pushFile(relPath(dirs, 'domains', dir, 'context.ts'))
+      pushFile(relPath(dirs, 'domains', dir, 'executors/crud.generated.ts'))
+      pushFile(relPath(dirs, 'domains', dir, 'permissions.ts'))
+    }
+  }
+
+  // 过滤掉仍被现存模块引用的 api 文件（known 里没有名字的才可能是残留）
+  return residue.filter((item) => {
+    if (!item.rel.startsWith(`${dirs.api}/`)) return true
+    const name = item.rel.slice(dirs.api.length + 1).replace(/\.ts$/, '')
+    return !known.has(name)
+  })
+}
+
+/**
+ * 目录是否只含生成物（递归）：空目录也算
+ */
+function onlyGenerated(root, rel) {
+  const walk = (dir) => {
+    const entries = fs.readdirSync(dir, { withFileTypes: true })
+    for (const entry of entries) {
+      const full = path.join(dir, entry.name)
+      if (entry.isDirectory()) {
+        if (!walk(full)) return false
+        continue
+      }
+      if (!isGenerated(read(full))) return false
+    }
+    return true
+  }
+
+  return walk(path.join(root, rel))
+}
+
+/**
+ * dry-run 时的跳过预告：不写文件，但要先说清哪些模块会被冲突挡住
+ * @param entries   待比较的条目
+ * @param domains   全部模块
+ * @param moduleName 单模块名（有值时只算该模块）
+ * @param force     是否 --force（强制覆盖时不会有跳过）
+ */
+function previewSkipped(entries, domains, moduleName, force, dirs) {
+  if (force) return []
+
+  if (moduleName) {
+    const blocked = entries.filter(isBlocked)
+    return blocked.length > 0 ? [{ module: moduleName, blocked }] : []
+  }
+
+  const { groups, globalEntries } = groupEntries(entries, domains, dirs)
+  const skipped = []
+
+  for (const group of groups) {
+    const blocked = group.entries.filter(isBlocked)
+    if (blocked.length > 0) skipped.push({ module: group.domain.name, blocked })
+  }
+
+  const globalBlocked = globalEntries.filter(isBlocked)
+  if (globalBlocked.length > 0) {
+    skipped.push({ module: '全局路由/菜单', blocked: globalBlocked })
+  }
+
+  return skipped
+}
+
+function groupEntries(entries, domains, dirs) {
+  const globalFiles = globalFileSet(dirs)
+  const globalEntries = entries.filter((entry) => globalFiles.has(entry.path))
+  const groups = domains.map((domain) => ({
+    domain,
+    entries: entries.filter(
+      (entry) => !globalFiles.has(entry.path) && belongsToModule(entry.path, domain.name, dirs)
+    )
+  }))
+
+  return { groups, globalEntries }
+}
+
+function belongsToModule(file, name, dirs) {
+  return (
+    file === relPath(dirs, 'api', `${name}.ts`) ||
+    file.startsWith(`${relPath(dirs, 'stores', name)}/`) ||
+    file.startsWith(`${relPath(dirs, 'domains', name)}/`) ||
+    file.startsWith(`${relPath(dirs, 'views', name)}/`)
+  )
+}
+
+function isBlocked(entry) {
+  return entry.status === 'conflict' || entry.status === 'edited'
+}
+
+function isWritable(entry) {
+  return entry.status === 'add' || entry.status === 'update'
+}
+
+function printBlockedJsonOrText(blocked, flags) {
+  if (flags.json) {
+    console.log(
+      JSON.stringify(
+        {
+          ok: false,
+          blocked: blocked.map((entry) => ({ path: entry.path, status: entry.status }))
+        },
+        null,
+        2
+      )
+    )
+    return
+  }
+
+  printHeader('生成结果', 'Sync')
+  printBlocked(blocked)
+}
+
+function printResidue(residue) {
+  console.log('')
+  console.log(
+    `  ${ui.warning(glyph.warn)} ${ui.label(
+      `发现 ${residue.length} 个文件该删了（模块已经删掉，它的文件还在）`,
+      `${residue.length} leftovers found`
+    )}`
+  )
+  for (const item of residue) {
+    console.log(`    ${ui.danger(glyph.warn)} ${ui.path(item.rel)}`)
+  }
+  console.log('')
+}
+
+function printChanges(configChanges, entries, options = {}) {
+  printHeader('生成结果', 'Sync')
+
+  if (configChanges) {
+    printConfigChanges(configChanges)
+  }
+
+  printDiff(entries, { header: false })
+
+  const updates = entries.filter((entry) => entry.status === 'update')
+
+  if (updates.length > 0) {
+    console.log(`  ${ui.label('文件内容变化', 'File changes')}`)
+    for (const entry of updates) {
+      printFileDiff(entry)
+    }
+    console.log('')
+  }
+
+  if (options.skipped?.length > 0) {
+    console.log(
+      `  ${ui.warning(glyph.warn)} ${ui.label(
+        '这些模块会被跳过（有文件挡住）',
+        'These modules will be skipped (files in the way)'
+      )}`
+    )
+    for (const group of options.skipped) {
+      console.log(`    ${ui.path(group.module)}`)
+      for (const entry of group.blocked) {
+        console.log(`      ${ui.danger(glyph.warn)} ${ui.path(entry.path)}`)
+      }
+    }
+    console.log('')
+  }
+}
+
+function printConfigChanges(changes) {
+  console.log(`  ${ui.label('配置变化', 'Config changes')}`)
+
+  if (!changes.available) {
+    console.log(`    ${ui.muted('no previous config recorded, comparing files only (没有上次的配置记录，只能看文件变化)')}`)
+    console.log('')
+    return
+  }
+
+  if (changes.rows.length === 0) {
+    console.log(`    ${ui.muted('No config changes (配置没有变化)')}`)
+    console.log('')
+    return
+  }
+
+  for (const row of changes.rows) {
+    console.log(
+      `    ${ui.path(row.key)}: ${ui.danger(String(row.old))} → ${ui.success(String(row.new))}`
+    )
+  }
+  console.log('')
+}
+
+function printFileDiff(entry) {
+  const oldContent = read(entry.target)
+  const before = splitGenerated(oldContent)?.body ?? oldContent
+  const after = splitGenerated(entry.content)?.body ?? entry.content
+  const lines = lineDiff(before, after)
+  const visible = hunks(lines)
+
+  console.log(`    ${ui.warning(glyph.update)} ${ui.path(entry.path)}`)
+  if (visible.length === 0) {
+    console.log(`      ${ui.muted('config changed only (只是配置变了，生成的代码没变)')}`)
+  }
+  for (const line of visible) {
+    if (line.type === '@@') {
+      console.log(`      ${ui.muted('@@')}`)
+      continue
+    }
+
+    const mark = line.type === '+' ? '+' : line.type === '-' ? '-' : ' '
+    const paint =
+      line.type === '+' ? ui.success : line.type === '-' ? ui.danger : ui.muted
+    console.log(`      ${paint(`${mark} ${line.text}`)}`)
+  }
+  console.log('')
+}
+
+function printBlocked(blocked) {
+  console.error(`  ${ui.danger(glyph.err)} ${ui.label('没有覆盖', 'Not overwritten')}`)
+  console.error(`    ${ui.muted('These files need confirmation (这些文件需要你确认):')}`)
+
+  const edited = blocked.filter((entry) => entry.status === 'edited')
+  const existing = blocked.filter((entry) => entry.status === 'conflict')
+
+  if (existing.length > 0) {
+    console.error(`    ${ui.muted(`${existing.length} hand-written files, not generated by CLI (手写文件，不是 CLI 生成):`)}`)
+    for (const entry of existing) {
+      console.error(`      ${ui.danger(glyph.warn)} ${ui.path(entry.path)}`)
+    }
+  }
+  if (edited.length > 0) {
+    console.error(`    ${ui.muted(`${edited.length} files edited by hand (被手动修改过):`)}`)
+    for (const entry of edited) {
+      console.error(`      ${ui.danger(glyph.warn)} ${ui.path(entry.path)}`)
+    }
+  }
+
+  console.error(`  ${ui.muted('To overwrite (要覆盖请运行): tha sync --force')}`)
+  console.error(`  ${ui.muted('handwritten executors are untouched (executors/ 里的手写文件不会被改动)')}`)
+}
+
+async function confirm(question) {
+  const rl = readline.createInterface({ input: stdin, output: stdout })
+  try {
+    const answer = (await rl.question(question)).trim().toLowerCase()
+    return answer === 'y' || answer === 'yes'
+  } finally {
+    rl.close()
+  }
+}
+
+function readConfigChanges(root, target) {
+  const executorFile = path.join(
+    root,
+    'src',
+    'domains',
+    target.name,
+    'executors',
+    'crud.generated.ts'
+  )
+
+  let oldConfig = null
+  try {
+    const header = generatedHeader(read(executorFile))
+    oldConfig = header?.config ?? null
+  } catch {
+    oldConfig = null
+  }
+
+  if (!oldConfig) {
+    return { available: false, rows: [] }
+  }
+
+  return {
+    available: true,
+    rows: diffValues(oldConfig, snapshot(target))
+  }
+}
+
+function snapshot(domain) {
+  return {
+    name: domain.name,
+    title: domain.title,
+    path: domain.path,
+    api: domain.api,
+    fields: domain.fields,
+    list: domain.list,
+    crud: domain.crud,
+    permissions: domain.permissions
+  }
+}
+
+function diffValues(oldValue, newValue, prefix = '') {
+  const rows = []
+  const keys = new Set([
+    ...Object.keys(oldValue ?? {}),
+    ...Object.keys(newValue ?? {})
+  ])
+
+  for (const key of keys) {
+    const at = prefix ? `${prefix}.${key}` : key
+    const before = oldValue?.[key]
+    const after = newValue?.[key]
+
+    if (isObject(before) && isObject(after)) {
+      rows.push(...diffValues(before, after, at))
+      continue
+    }
+
+    if (JSON.stringify(before) !== JSON.stringify(after)) {
+      rows.push({
+        key: at,
+        old: display(before),
+        new: display(after)
+      })
+    }
+  }
+
+  return rows
+}
+
+function display(value) {
+  if (value === undefined) return '(无)'
+  if (typeof value === 'string') return JSON.stringify(value)
+  return JSON.stringify(value)
+}
+
+function isObject(value) {
+  return value !== null && typeof value === 'object' && !Array.isArray(value)
+}
+
+function hunks(lines, context = 2) {
+  const keep = new Set()
+
+  lines.forEach((line, index) => {
+    if (line.type === ' ') return
+    for (let i = Math.max(0, index - context); i <= Math.min(lines.length - 1, index + context); i += 1) {
+      keep.add(i)
+    }
+  })
+
+  if (keep.size === 0) return []
+
+  const result = []
+  let previous = -1
+
+  for (let i = 0; i < lines.length; i += 1) {
+    if (!keep.has(i)) continue
+    if (previous !== -1 && i > previous + 1) result.push({ type: '@@', text: '' })
+    result.push(lines[i])
+    previous = i
+  }
+
+  return result
+}
+
+function lineDiff(before, after) {
+  const a = before.split('\n')
+  const b = after.split('\n')
+  const dp = Array.from({ length: a.length + 1 }, () => new Array(b.length + 1).fill(0))
+
+  for (let i = a.length - 1; i >= 0; i -= 1) {
+    for (let j = b.length - 1; j >= 0; j -= 1) {
+      dp[i][j] = a[i] === b[j] ? dp[i + 1][j + 1] + 1 : Math.max(dp[i + 1][j], dp[i][j + 1])
+    }
+  }
+
+  const lines = []
+  let i = 0
+  let j = 0
+
+  while (i < a.length && j < b.length) {
+    if (a[i] === b[j]) {
+      lines.push({ type: ' ', text: a[i] })
+      i += 1
+      j += 1
+    } else if (dp[i + 1][j] >= dp[i][j + 1]) {
+      lines.push({ type: '-', text: a[i] })
+      i += 1
+    } else {
+      lines.push({ type: '+', text: b[j] })
+      j += 1
+    }
+  }
+
+  while (i < a.length) {
+    lines.push({ type: '-', text: a[i] })
+    i += 1
+  }
+  while (j < b.length) {
+    lines.push({ type: '+', text: b[j] })
+    j += 1
+  }
+
+  return lines
+}
+
+function isTargetFile(file, name, dirs) {
+  if (globalFileSet(dirs).has(file)) return true
+
+  return (
+    file.startsWith(`${relPath(dirs, 'api', name)}.`) ||
+    file.startsWith(`${relPath(dirs, 'stores', name)}/`) ||
+    file.startsWith(`${relPath(dirs, 'domains', name)}/`) ||
+    file.startsWith(`${relPath(dirs, 'views', name)}/`)
+  )
+}
+
+function printSyncHelp() {
+  console.log('')
+  console.log(`  ${ui.heading('生成结果', 'sync · generate pages')}`)
+  console.log(`  ${ui.rule(50)}`)
+  console.log('')
+  console.log(`  ${ui.label('用法', 'Usage')}`)
+  console.log(`    ${ui.command('tha sync')} ${ui.muted('list modules (只列模块，不写文件)')}`)
+  console.log(`    ${ui.command('tha sync <模块>')} [--force] [--dry-run] [--yes] [--json]`)
+  console.log(`    ${ui.command('tha sync --all')} [--force] [--prune] [--dry-run] [--yes] [--json]`)
+  console.log('')
+  console.log(`  ${ui.label('说明', 'Notes')}`)
+  console.log(`    ${ui.bullet('one module (指定模块：只更新该模块 + 全局路由/菜单)')}`)
+  console.log(`    ${ui.bullet('isolate modules (--all：更新全部模块；某个模块被挡住时只跳过它，不拖累其他)')}`)
+  console.log(`    ${ui.bullet('remove leftovers (--prune：清理「模块已删、生成物还在」的残留后再全量生成)')}`)
+  console.log(`    ${ui.bullet('generates 5 files: api, store, context, executors, view (生成 5 个文件：接口、状态、上下文、执行器、页面)')}`)
+  console.log(`    ${ui.bullet('模块入口 index.ts 缺失时补一个骨架；已有的不覆盖')}`)
+  console.log(`    ${ui.bullet('transactional writes (写入是事务的：任一失败不留半套文件)')}`)
+  console.log(`    ${ui.bullet('项目装了 Prettier 会自动格式化；--no-format 关闭')}`)
+  console.log(`    ${ui.bullet('--yes 跳过确认；--dry-run 只预览；--force 覆盖已有文件')}`)
+  console.log(`    ${ui.bullet('disable color (关闭颜色)')}`)
+  console.log('')
+}