tha-cli 0.0.0-stage → 0.1.0

package/tha/cli.mjs

@@ -0,0 +1,116 @@
+import fs from 'node:fs'
+import path from 'node:path'
+import { runInit } from './commands/init.mjs'
+import { runCheck } from './commands/check.mjs'
+import { runDiff } from './commands/diff.mjs'
+import { runSync } from './commands/sync.mjs'
+import { runRemove } from './commands/remove.mjs'
+import { runAdopt } from './commands/adopt.mjs'
+import { configureStyle, ui } from './utils/style.mjs'
+
+const COMMANDS = {
+  init: runInit,
+  check: runCheck,
+  diff: runDiff,
+  sync: runSync,
+  remove: runRemove,
+  adopt: runAdopt
+}
+
+export async function run(argv) {
+  const { root, args, styleOptions } = extractRoot(argv)
+  configureStyle(styleOptions)
+
+  if (args.length === 0 || args[0] === '--help' || args[0] === '-h' || args[0] === 'help') {
+    printHelp()
+    return
+  }
+
+  const [command, ...rest] = args
+  const handler = COMMANDS[command]
+
+  if (!handler) {
+    throw new Error(`未知命令「${command}」。可用：${Object.keys(COMMANDS).join(' / ')}`)
+  }
+
+  if (!fs.existsSync(root)) {
+    throw new Error(`--root 目录不存在：${root}`)
+  }
+
+  await handler({ root, args: rest })
+}
+
+function extractRoot(argv) {
+  let root = process.cwd()
+  const args = []
+  const styleOptions = {}
+
+  for (let i = 0; i < argv.length; i += 1) {
+    const arg = argv[i]
+
+    if (arg === '--root') {
+      const value = argv[i + 1]
+      if (!value || value.startsWith('--')) throw new Error('--root 需要一个目录')
+      root = value
+      i += 1
+      continue
+    }
+
+    if (arg.startsWith('--root=')) {
+      root = arg.slice('--root='.length)
+      continue
+    }
+
+    if (arg === '--no-color') {
+      styleOptions.noColor = true
+      delete styleOptions.color
+      continue
+    }
+
+    if (arg === '--color') {
+      styleOptions.color = true
+      delete styleOptions.noColor
+      continue
+    }
+
+    args.push(arg)
+  }
+
+  return { root: path.resolve(root), args, styleOptions }
+}
+
+function printHelp() {
+  console.log('')
+  console.log(`  ${ui.heading('标准增删改查生成器', 'page generator')}`)
+  console.log(`  ${ui.rule(40)}`)
+  console.log('')
+  console.log(`  ${ui.label('用法', 'Usage')}`)
+  console.log(`    ${ui.command('tha init')} <模块> [--title 标题] [--path /页面地址] [--api /接口地址]`)
+  console.log(`    ${ui.command('tha check')} [--json] [--strict]`)
+  console.log(`    ${ui.command('tha diff')} [--json]`)
+  console.log(`    ${ui.command('tha sync')} [<模块> | --all] [--prune] [--force] [--dry-run] [--json]`)
+  console.log(`    ${ui.command('tha remove')} <模块> [--purge] [--dry-run] [--json]`)
+  console.log(`    ${ui.command('tha adopt')} [<文件...>] [--release] ${ui.muted('# 生成的文件改成自己维护')}`)
+  console.log('')
+  console.log(`  ${ui.label('例子', 'Examples')}`)
+  console.log(`    ${ui.muted('tha init doc --title 文档 --path /doc --api /docs')}`)
+  console.log(`    ${ui.muted('tha check')}`)
+  console.log(`    ${ui.muted('tha diff')}`)
+  console.log(`    ${ui.muted('tha sync doc          # 只同步一个模块')}`)
+  console.log(`    ${ui.muted('tha sync --all        # 同步全部模块')}`)
+  console.log(`    ${ui.muted('tha sync --all --prune # 顺带清理已删模块的残留')}`)
+  console.log(`    ${ui.muted('tha remove doc        # 删除模块（手写文件保留）')}`)
+  console.log(`    ${ui.muted('tha adopt src/api/doc.ts # 这个文件改成自己维护')}`)
+  console.log(`    ${ui.muted('tha adopt --release src/api/doc.ts')}`)
+  console.log('')
+  console.log(`  ${ui.label('说明', 'Notes')}`)
+  console.log(`    ${ui.bullet('reads config, never executes it (只读 config.ts，不会执行它)')}`)
+  console.log(`    ${ui.bullet('5 files, scaffold hub once (生成 5 个文件；新模块首次补模块入口，之后不覆盖)')}`)
+  console.log(`    ${ui.bullet('checks manual modules too (也检查手写模块：没 config 的按目录形状识别)')}`)
+  console.log(`    ${ui.bullet('list only (不带模块只列模块，不写文件)')}`)
+  console.log(`    ${ui.bullet('invalid config writes nothing (配置有误时不写任何文件)')}`)
+  console.log(`    ${ui.bullet('set project root (指定项目目录)')}`)
+  console.log(`    ${ui.bullet('disable color; THA_THEME=plain for plain text (关闭颜色；THA_THEME=plain 纯文本)')}`)
+  console.log(`    ${ui.bullet('force color when piped (被管道接管时也强制上色)')}`)
+  console.log('')
+}

package/tha/commands/adopt.mjs

@@ -0,0 +1,119 @@
+// ============ 生成位交接：adopt / release ============
+// adopt 只对「生成计划里存在的文件」生效 —— 它表达的是「这个生成位改由人维护」，
+// 不是「随便标一个文件」。交接后 CLI 不写、不比对漂移，但护栏照查。
+
+import path from 'node:path'
+import { loadProject } from '../config/project.mjs'
+import { adoptFiles, loadManifest, releaseFiles } from '../config/manifest.mjs'
+import { buildPlan } from '../generate/plan.mjs'
+import { parseArgs } from '../utils/args.mjs'
+import { printErrors, printHeader } from '../utils/output.mjs'
+import { toPosix } from '../utils/files.mjs'
+import { glyph, ui } from '../utils/style.mjs'
+
+export function runAdopt({ root, args }) {
+  // adopt 不写业务文件（只改 manifest），本来就不需要确认；--yes 接受但忽略，
+  // 免得和 sync / remove / init 的参数习惯不一致时报「未知参数」。
+  const { flags, positional } = parseArgs(args, { boolean: ['json', 'help', 'release', 'yes'] })
+
+  if (flags.help) {
+    printAdoptHelp()
+    return
+  }
+
+  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
+  }
+
+  const manifest = loadManifest(root)
+
+  // 不带参数：列出已接手的生成位
+  if (positional.length === 0) {
+    if (flags.json) {
+      console.log(JSON.stringify({ ok: true, manual: manifest.manual }, null, 2))
+      return
+    }
+
+    printHeader('改为自己维护', 'Adopt')
+    if (manifest.manual.length === 0) {
+      console.log(`  ${ui.muted(glyph.dot)} ${ui.label('还没有改成自己维护的文件', 'No hand-maintained files')}`)
+    } else {
+      for (const entry of manifest.manual) {
+        console.log(`    ${ui.path(entry)}`)
+      }
+    }
+    console.log('')
+    return
+  }
+
+  const wanted = positional.map((entry) => toPosix(path.relative(root, path.resolve(root, entry))))
+
+  if (flags.release) {
+    const removed = releaseFiles(root, wanted)
+    if (flags.json) {
+      console.log(JSON.stringify({ ok: true, released: removed }, null, 2))
+      return
+    }
+    printHeader('交回生成管理', 'Release')
+    for (const entry of removed) {
+      console.log(`  ${ui.success(glyph.ok)} ${ui.path(entry)}`)
+    }
+    if (removed.length === 0) {
+      console.log(`  ${ui.muted(glyph.dot)} ${ui.label('这些文件本来就不在交接清单里', 'Not in the manifest')}`)
+    }
+    console.log('')
+    return
+  }
+
+  const planPaths = new Set(buildPlan(project.domains, root, project.dirs).map((file) => file.path))
+  const unknown = wanted.filter((entry) => !planPaths.has(entry))
+
+  if (unknown.length > 0) {
+    throw new Error(
+      `这些文件不是 CLI 生成的，没法接手：${unknown.join(', ')}\n只接受构建期会生成的文件（用 tha diff 查看）`
+    )
+  }
+
+  const added = adoptFiles(root, wanted)
+
+  if (flags.json) {
+    console.log(JSON.stringify({ ok: true, adopted: added, kept: wanted.filter((e) => !added.includes(e)) }, null, 2))
+    return
+  }
+
+  printHeader('改成自己维护', 'Adopt')
+  for (const entry of wanted) {
+    const isNew = added.includes(entry)
+    const mark = isNew ? ui.success(glyph.ok) : ui.muted(glyph.dot)
+    console.log(`  ${mark} ${ui.path(entry)} ${isNew ? '' : ui.muted('(already in list)（已在清单里）')}`)
+  }
+  console.log('')
+  console.log(`  ${ui.muted('CLI 不再写这些文件；tha check 的分层规则照样会查它们')}`)
+  console.log(`  ${ui.muted('Release (改回生成管理): tha adopt <文件> --release')}`)
+  console.log('')
+}
+
+function printAdoptHelp() {
+  console.log('')
+  console.log(`  ${ui.heading('改为自己维护', 'adopt · take over generated files')}`)
+  console.log(`  ${ui.rule(50)}`)
+  console.log('')
+  console.log(`  ${ui.label('用法', 'Usage')}`)
+  console.log(`    ${ui.command('tha adopt')}                      ${ui.muted('# 列出改成自己维护的文件')}`)
+  console.log(`    ${ui.command('tha adopt')} <文件...>            ${ui.muted('# 改成自己维护（CLI 不再生成）')}`)
+  console.log(`    ${ui.command('tha adopt')} <文件...> --release  ${ui.muted('# 交回给 CLI 管理')}`)
+  console.log('')
+  console.log(`  ${ui.label('说明', 'Notes')}`)
+  console.log(`    ${ui.bullet('只接受 CLI 会生成的文件（用 tha diff 查看）')}`)
+  console.log(`    ${ui.bullet('改成自己维护后，不再算「被改过或有冲突」，但分层规则照样查')}`)
+  console.log(`    ${ui.bullet('清单写在 .tha/manifest.json，建议提交到版本库')}`)
+  console.log('')
+}

package/tha/commands/check.mjs

@@ -0,0 +1,226 @@
+import { loadProject } from '../config/project.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 { printErrors, printHeader } from '../utils/output.mjs'
+import { checkBoundaries } from '../verify/boundary.mjs'
+import { checkContracts } from '../verify/contract.mjs'
+import { checkOpenApiContracts } from '../verify/openapi.mjs'
+import { describeConfigured } from '../verify/scan.mjs'
+import { glyph, ui } from '../utils/style.mjs'
+
+export function runCheck({ root, args }) {
+  const { flags } = parseArgs(args, { boolean: ['json', 'help', 'strict'] })
+
+  if (flags.help) {
+    printCheckHelp()
+    return
+  }
+
+  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
+  }
+
+  // 两种模块一起检查：config 驱动的过完整契约，手写的只过中枢契约
+  const modules = [...describeConfigured(project.domains, root, project.dirs), ...project.manual]
+  // 纯手写项目（0 个 config 模块 + 有手写模块）：CLI 不托管任何文件，不比对漂移
+  const pureManual = project.domains.length === 0 && project.manual.length > 0
+  const entries = pureManual
+    ? []
+    : comparePlan(buildPlan(project.domains, root, project.dirs), root, manualPaths(root))
+  const adopted = entries.filter((entry) => entry.status === 'manual')
+  const missing = entries.filter((entry) => entry.status === 'add')
+  const drift = entries.filter((entry) => entry.status === 'update')
+  const edited = entries.filter((entry) => entry.status === 'edited')
+  const existing = entries.filter((entry) => entry.status === 'conflict')
+  const blocked = edited.length + existing.length
+  const contracts = [
+    ...checkContracts(modules, root, project.dirs),
+    ...checkOpenApiContracts(modules, root, project.dirs)
+  ]
+  const contractErrors = contracts.filter((item) => (item.level ?? 'error') === 'error')
+  const contractWarns = contracts.filter((item) => item.level === 'warn')
+  const guards = checkBoundaries(modules, root, project.dirs)
+  const guardErrors = guards.filter((item) => item.level === 'error')
+  const guardWarns = guards.filter((item) => item.level === 'warn')
+
+  // 契约违约、漂移、手改、护栏 error，都让 CI 红；warn 只在 --strict 时红
+  const failed =
+    drift.length > 0 ||
+    blocked > 0 ||
+    contractErrors.length > 0 ||
+    guardErrors.length > 0 ||
+    (flags.strict && (contractWarns.length > 0 || guardWarns.length > 0))
+
+  if (failed) process.exitCode = 1
+
+  if (flags.json) {
+    console.log(
+      JSON.stringify(
+        {
+          ok: !failed,
+          domains: project.domains.map((domain) => domain.name),
+          manual: project.manual.map((module) => module.name),
+          contracts,
+          guards,
+          adopted: adopted.map((entry) => entry.path),
+          missing: missing.map((entry) => entry.path),
+          drift: drift.map((entry) => entry.path),
+          edited: edited.map((entry) => entry.path),
+          conflicts: existing.map((entry) => entry.path)
+        },
+        null,
+        2
+      )
+    )
+    return
+  }
+
+  printHeader('配置检查', 'Check')
+  console.log(
+    `  ${ui.success(glyph.ok)} ${ui.label(
+      `配置没问题：${project.domains.length} 个模块，${project.manual.length} 个手写模块`,
+      `Config OK: ${project.domains.length} managed, ${project.manual.length} manual`
+    )}`
+  )
+
+  if (contracts.length > 0) {
+    console.log('')
+    if (contractErrors.length > 0) {
+      console.log(
+        `  ${ui.danger(glyph.err)} ${ui.label(
+          `有 ${contractErrors.length} 处对不上，${contractWarns.length} 处要确认`,
+          `${contractErrors.length} mismatch, ${contractWarns.length} warning`
+        )}`
+      )
+    } else {
+      console.log(
+        `  ${ui.warning(glyph.warn)} ${ui.label(
+          `有 ${contractWarns.length} 处要确认`,
+          `${contractWarns.length} warning`
+        )}`
+      )
+    }
+
+    for (const problem of contracts) {
+      const badge = (problem.level ?? 'error') === 'error' ? ui.danger(glyph.warn) : ui.warning(glyph.warn)
+      console.log(`    ${badge} ${ui.path(problem.file)}`)
+      console.log(`      ${ui.muted(problem.message)}`)
+    }
+  }
+
+  if (guards.length > 0) {
+    console.log('')
+    console.log(
+      `  ${ui.danger(glyph.err)} ${ui.label(
+        `分层规则被破坏：${guardErrors.length} 处错误、${guardWarns.length} 处提醒`,
+        `Layering rules broken: ${guardErrors.length} errors, ${guardWarns.length} warnings`
+      )}`
+    )
+    for (const item of guards) {
+      const badge = item.level === 'error' ? ui.danger(item.rule) : ui.warning(item.rule)
+      console.log(`    ${ui.path(`${item.file}:${item.line}`)} ${badge}`)
+      console.log(`      问题：${item.message}`)
+      if (item.note) console.log(`      ${ui.muted(item.note)}`)
+      console.log(`      应该：${item.fix}`)
+      console.log(`      ${ui.muted(`依据：${item.basis}`)}`)
+    }
+  }
+
+  if (blocked > 0) {
+    console.log('')
+    console.log(
+      `  ${ui.warning(glyph.warn)} ${ui.label(
+        'tha sync 会被这些已有文件挡住',
+        'tha sync is blocked by these files'
+      )}`
+    )
+
+    if (existing.length > 0) {
+      console.log(
+        `    ${ui.muted(`hand-written, kept as-is (${existing.length} 个手写文件，不是 CLI 生成，默认不覆盖)`)}`
+      )
+      for (const entry of existing) {
+        console.log(`      ${ui.danger(glyph.warn)} ${ui.path(entry.path)}`)
+      }
+    }
+    if (edited.length > 0) {
+      console.log(
+        `    ${ui.muted(`edited by hand, kept as-is (${edited.length} 个已有文件被手动改过，默认不覆盖)`)}`
+      )
+      for (const entry of edited) {
+        console.log(`      ${ui.danger(glyph.warn)} ${ui.path(entry.path)}`)
+      }
+    }
+    if (missing.length > 0) {
+      console.log(
+        `    ${ui.muted(`${missing.length} files not generated yet (还有 ${missing.length} 个文件没生成)`)}`
+      )
+    }
+
+    console.log(`    ${ui.bullet(`${ui.label('看是哪几个文件', 'Details')}: ${ui.command('tha diff')}`)}`)
+    console.log(`    ${ui.bullet(`${ui.label('强制重新生成', 'Overwrite')}: ${ui.command('tha sync --all --force')}`)}`)
+  } else if (missing.length > 0) {
+    console.log(
+      `  ${ui.muted(glyph.dot)} ${ui.label(
+        `还有 ${missing.length} 个文件没生成`,
+        `${missing.length} files not generated yet`
+      )} ${ui.muted('→ tha sync')}`
+    )
+  }
+
+  if (drift.length > 0) {
+    console.log('')
+    console.log(`  ${ui.warning(glyph.warn)} ${ui.label('这些文件需要更新', 'These files need updating')}`)
+    for (const entry of drift) {
+      console.log(`    ${ui.warning(glyph.warn)} ${ui.path(entry.path)}`)
+    }
+    console.log(`  ${ui.muted('Run (运行): tha sync --all')}`)
+  }
+
+  if (adopted.length > 0) {
+    console.log(
+      `  ${ui.muted(glyph.dot)} ${ui.label(
+        `${adopted.length} 个文件改成你自己维护了（不再自动生成，分层规则还会查）`,
+        `${adopted.length} files now hand-maintained`
+      )}`
+    )
+    for (const entry of adopted) {
+      console.log(`    ${ui.muted(entry.path)}`)
+    }
+  }
+
+  if (!failed) {
+    console.log(`  ${ui.success(glyph.ok)} ${ui.label('文件都是最新的，分层规则没被破坏', 'All files up to date, structure intact')}`)
+  }
+
+  console.log('')
+}
+
+function printCheckHelp() {
+  console.log('')
+  console.log(`  ${ui.heading('配置检查', 'check · validate config & guardrails')}`)
+  console.log(`  ${ui.rule(50)}`)
+  console.log('')
+  console.log(`  ${ui.label('用法', 'Usage')}`)
+  console.log(`    ${ui.command('tha check')} [--json] [--strict]`)
+  console.log('')
+  console.log(`  ${ui.label('说明', 'Notes')}`)
+  console.log(`    ${ui.bullet('检查必填/选填、不认识的配置项、重复地址、可选值、默认值')}`)
+  console.log(`    ${ui.bullet('配置和生成物对不对得上：模块入口在不在、动作挂没挂、页面文件齐不齐')}`)
+  console.log(`    ${ui.bullet('分层规则（谁不许 import 谁）：入口不许绕开动作、动作之间不许互引、页面不许直接调接口、状态文件不许发请求')}`)
+  console.log(`    ${ui.bullet('手写模块也检查（没有 config 的模块按目录形状识别，不参与生成）')}`)
+  console.log(`    ${ui.bullet('文件内容和配置不一致、文件不是 CLI 写的，都算不通过（退出码 1）')}`)
+  console.log(`    ${ui.bullet('warnings fail the run (--strict 警告也算失败)')}`)
+  console.log(`    ${ui.bullet('disable color (关闭颜色)')}`)
+  console.log('')
+}

package/tha/commands/diff.mjs

@@ -0,0 +1,70 @@
+import { loadProject } from '../config/project.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 { printDiff, printErrors } from '../utils/output.mjs'
+import { glyph, ui } from '../utils/style.mjs'
+
+export function runDiff({ root, args }) {
+  const { flags } = parseArgs(args, { boolean: ['json', 'help'] })
+
+  if (flags.help) {
+    printDiffHelp()
+    return
+  }
+
+  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
+  }
+
+  const entries = comparePlan(buildPlan(project.domains, root, project.dirs), root, manualPaths(root))
+
+  if (flags.json) {
+    console.log(
+      JSON.stringify(
+        {
+          ok: true,
+          files: entries.map((entry) => ({ path: entry.path, status: entry.status }))
+        },
+        null,
+        2
+      )
+    )
+    return
+  }
+
+  printDiff(entries)
+}
+
+function printDiffHelp() {
+  console.log('')
+  console.log(`  ${ui.heading('文件预览', 'diff · preview files')}`)
+  console.log(`  ${ui.rule(46)}`)
+  console.log('')
+  console.log(`  ${ui.label('用法', 'Usage')}`)
+  console.log(`    ${ui.command('tha diff')} [--json]`)
+  console.log('')
+  console.log(`  ${ui.label('状态', 'Status')}`)
+  console.log(`    ${ui.success(glyph.add)} ${ui.label('将新增', 'Will add')}`)
+  console.log(
+    `    ${ui.warning(glyph.update)} ${ui.label('将更新', 'Will update')} ${ui.muted('exists and will be updated (文件已存在，内容会更新)')}`
+  )
+  console.log(
+    `    ${ui.danger(glyph.warn)} ${ui.label('不会覆盖', 'Will not overwrite')} ${ui.muted('not generated by CLI (文件已存在，但不是 CLI 生成的)')}`
+  )
+  console.log(`    ${ui.muted(glyph.same)} ${ui.label('无变化', 'No change')}`)
+  console.log('')
+  console.log(`  ${ui.label('说明', 'Notes')}`)
+  console.log(`    ${ui.bullet('preview only (只显示结果，不写文件)')}`)
+  console.log(`    ${ui.bullet('disable color (关闭颜色)')}`)
+  console.log('')
+}