tha-cli 0.0.0-stage → 0.1.0

package/tha/kit/request.ts

@@ -0,0 +1,30 @@
+/* THA 基线请求层
+ * 只做最朴素的 fetch 包装，让生成物在空项目里也能跑。
+ * 项目已有自己的请求层时，删掉这个文件、保持下面五个方法签名即可。
+ * 后端返回结构不同（例如有 { code, data } 外壳），只改这一个地方。
+ */
+
+async function call<T>(url: string, init?: RequestInit): Promise<T> {
+  const response = await fetch(url, {
+    headers: { 'Content-Type': 'application/json' },
+    ...init
+  })
+
+  if (!response.ok) {
+    throw new Error(`${response.status} ${response.statusText}`)
+  }
+
+  const text = await response.text()
+  return (text ? JSON.parse(text) : undefined) as T
+}
+
+export const request = {
+  list: <T>(base: string): Promise<T[]> => call<T[]>(base),
+  detail: <T>(id: number, base: string): Promise<T> => call<T>(`${base}/${id}`),
+  create: <T>(data: unknown, base: string): Promise<T> =>
+    call<T>(base, { method: 'POST', body: JSON.stringify(data) }),
+  update: <T>(id: number, data: unknown, base: string): Promise<T> =>
+    call<T>(`${base}/${id}`, { method: 'PUT', body: JSON.stringify(data) }),
+  remove: <T>(id: number, base: string): Promise<T> =>
+    call<T>(`${base}/${id}`, { method: 'DELETE' })
+}

package/tha/kit/transport.ts

@@ -0,0 +1,11 @@
+/* THA 基线提示层
+ * 生成物只调 toast(level, message)，不关心项目用哪套 UI 库。
+ * 项目已有提示层时，删掉这个文件、保持同样的导出签名即可。
+ */
+
+export type ToastLevel = 'info' | 'ok' | 'warn' | 'error'
+
+export function toast(level: ToastLevel, message: string): void {
+  if (level === 'error') console.error(`[tha] ${message}`)
+  else console.log(`[tha] ${message}`)
+}

package/tha/utils/args.mjs

@@ -0,0 +1,59 @@
+/**
+ * 极简参数解析：只支持 --key value、--key=value、--flag、-h。
+ * 不引入依赖，保证 CLI 本身可读、可测。
+ */
+export function parseArgs(argv, options = {}) {
+  const booleanFlags = new Set(options.boolean ?? [])
+  const valueFlags = new Set(options.value ?? [])
+  const flags = {}
+  const positional = []
+
+  for (let i = 0; i < argv.length; i += 1) {
+    const arg = argv[i]
+
+    if (arg === '--') {
+      positional.push(...argv.slice(i + 1))
+      break
+    }
+
+    if (arg === '-h') {
+      flags.help = true
+      continue
+    }
+
+    if (!arg.startsWith('--')) {
+      positional.push(arg)
+      continue
+    }
+
+    const [key, inlineValue] = arg.slice(2).split('=', 2)
+
+    if (booleanFlags.has(key)) {
+      if (inlineValue !== undefined) {
+        throw new Error(`--${key} 不接受值`)
+      }
+      flags[key] = true
+      continue
+    }
+
+    if (!valueFlags.has(key)) {
+      throw new Error(`未知参数 --${key}`)
+    }
+
+    const value = inlineValue ?? argv[i + 1]
+    if (value === undefined || (inlineValue === undefined && value.startsWith('--'))) {
+      throw new Error(`--${key} 需要一个值`)
+    }
+
+    flags[key] = value
+    if (inlineValue === undefined) i += 1
+  }
+
+  return { flags, positional }
+}
+
+export function requirePositional(positional, index, message) {
+  const value = positional[index]
+  if (!value) throw new Error(message)
+  return value
+}

package/tha/utils/compare.mjs

@@ -0,0 +1,38 @@
+import fs from 'node:fs'
+import path from 'node:path'
+import { generatedHeader, isGenerated, read, sha256 } from './files.mjs'
+
+/**
+ * 比较生成计划与磁盘现状
+ * @param plan   生成计划 [{ path, content }]
+ * @param root   项目根目录
+ * @param manual 已接手（不再生成）的文件路径集合
+ * @returns 带 status 的条目：add / update / edited / conflict / same / manual
+ */
+export function comparePlan(plan, root, manual = new Set()) {
+  return plan.map((file) => {
+    const target = path.join(root, file.path)
+
+    // 已接手的生成位：CLI 不再写，也不参与漂移判定（但护栏照查）
+    if (manual.has(file.path)) {
+      return { ...file, status: 'manual', target }
+    }
+
+    if (!fs.existsSync(target)) {
+      return { ...file, status: 'add', target }
+    }
+
+    const current = read(target)
+    if (current === file.content) {
+      return { ...file, status: 'same', target }
+    }
+
+    if (isGenerated(current)) {
+      const header = generatedHeader(current)
+      const intact = header && header.hash === sha256(header.body)
+      return { ...file, status: intact ? 'update' : 'edited', target }
+    }
+
+    return { ...file, status: 'conflict', target }
+  })
+}

package/tha/utils/files.mjs

@@ -0,0 +1,175 @@
+import crypto from 'node:crypto'
+import fs from 'node:fs'
+import path from 'node:path'
+
+export function toPosix(value) {
+  return value.split(path.sep).join('/')
+}
+
+export function absolute(root, relative) {
+  return path.join(root, relative)
+}
+
+export function relativePath(root, file) {
+  return toPosix(path.relative(root, file))
+}
+
+export function exists(file) {
+  return fs.existsSync(file)
+}
+
+export function read(file) {
+  return fs.readFileSync(file, 'utf8')
+}
+
+export function writeAtomic(file, content) {
+  fs.mkdirSync(path.dirname(file), { recursive: true })
+  const temp = `${file}.tha-${process.pid}.tmp`
+  fs.writeFileSync(temp, content, 'utf8')
+  fs.renameSync(temp, file)
+}
+
+/**
+ * 两阶段写入（事务）：先把所有内容落到临时文件，全部成功后再统一 rename 提交。
+ * 任一阶段失败都清理临时文件，原文件保持不动——不会出现"写到一半留半套"。
+ * @param entries 待写条目（每项需带 target 绝对路径 + content）
+ */
+export function writeAll(entries) {
+  const staged = []
+
+  try {
+    for (const entry of entries) {
+      fs.mkdirSync(path.dirname(entry.target), { recursive: true })
+      const temp = `${entry.target}.tha-${process.pid}.tmp`
+      fs.writeFileSync(temp, entry.content, 'utf8')
+      staged.push({ temp, target: entry.target })
+    }
+  } catch (error) {
+    cleanupStaged(staged)
+    throw error
+  }
+
+  for (const item of staged) fs.renameSync(item.temp, item.target)
+}
+
+function cleanupStaged(staged) {
+  for (const item of staged) {
+    try {
+      fs.unlinkSync(item.temp)
+    } catch {
+      // 临时文件可能没写成功；清理失败不影响原文件
+    }
+  }
+}
+
+export function removeFile(file) {
+  fs.rmSync(file, { force: true })
+}
+
+export function removeDir(dir) {
+  fs.rmSync(dir, { recursive: true, force: true })
+}
+
+/**
+ * 目录是否不存在或已空（删除后清理空壳目录用）
+ */
+export function isEmptyDir(dir) {
+  if (!fs.existsSync(dir)) return true
+  try {
+    return fs.readdirSync(dir).length === 0
+  } catch {
+    return false
+  }
+}
+
+/**
+ * 列出目录下的文件名（按扩展名过滤，可选）
+ */
+export function listFiles(dir, extension) {
+  if (!fs.existsSync(dir)) return []
+  return fs
+    .readdirSync(dir, { withFileTypes: true })
+    .filter((entry) => entry.isFile() && (!extension || entry.name.endsWith(extension)))
+    .map((entry) => entry.name)
+    .sort()
+}
+
+export function sha256(value) {
+  return crypto.createHash('sha256').update(value).digest('hex')
+}
+
+export function isGenerated(content) {
+  return content.startsWith('/* @tha-generated') || content.startsWith('<!-- @tha-generated')
+}
+
+export function splitGenerated(content) {
+  if (!isGenerated(content)) return null
+
+  const marker = content.startsWith('<!--') ? '-->\n' : '*/\n'
+  const end = content.indexOf(marker)
+  if (end < 0) return null
+
+  return {
+    header: content.slice(0, end + marker.length),
+    body: content.slice(end + marker.length)
+  }
+}
+
+export function generatedHeader(content) {
+  const split = splitGenerated(content)
+  if (!split) return null
+  const rawConfig = split.header.match(/config:\s*([A-Za-z0-9+/=]+)/)?.[1]
+  let config = null
+
+  if (rawConfig) {
+    try {
+      config = JSON.parse(Buffer.from(rawConfig, 'base64').toString('utf8'))
+    } catch {
+      config = null
+    }
+  }
+
+  return {
+    source: split.header.match(/source:\s*(.+)/)?.[1]?.trim() ?? '',
+    hash: split.header.match(/hash:\s*([a-f0-9]+)/)?.[1] ?? '',
+    config,
+    body: split.body
+  }
+}
+
+export function listDirectories(dir) {
+  if (!fs.existsSync(dir)) return []
+  return fs
+    .readdirSync(dir, { withFileTypes: true })
+    .filter((entry) => entry.isDirectory())
+    .map((entry) => entry.name)
+    .sort()
+}
+
+/**
+ * 递归收集目录下的文件（跳过 node_modules 与点开头目录）
+ * @param dir        起始目录（绝对路径）
+ * @param extensions 扩展名过滤，如 ['.ts', '.vue']；省略则收集全部
+ * @returns 文件的绝对路径列表（按路径排序）
+ */
+export function walkFiles(dir, extensions) {
+  if (!fs.existsSync(dir)) return []
+
+  const files = []
+
+  const visit = (current) => {
+    for (const entry of fs.readdirSync(current, { withFileTypes: true })) {
+      const full = path.join(current, entry.name)
+
+      if (entry.isDirectory()) {
+        if (entry.name === 'node_modules' || entry.name.startsWith('.')) continue
+        visit(full)
+      } else if (!extensions || extensions.some((ext) => entry.name.endsWith(ext))) {
+        files.push(full)
+      }
+    }
+  }
+
+  visit(dir)
+  return files.sort()
+}

package/tha/utils/format.mjs

@@ -0,0 +1,23 @@
+import { spawnSync } from 'node:child_process'
+import path from 'node:path'
+import { exists } from './files.mjs'
+
+/**
+ * 用项目自带的 Prettier 格式化刚写入的文件。
+ * 不硬依赖 Prettier：项目没装就跳过（返回 skipped），不影响生成结果。
+ * @param root 项目根目录
+ * @param files 刚写入的相对路径列表（相对 root）
+ * @returns { formatted, reason }：reason 为 '' / 'prettier-not-installed' / 'prettier-failed' / 'nothing'
+ */
+export function formatWritten(root, files) {
+  if (files.length === 0) return { formatted: false, reason: 'nothing' }
+
+  const bin = path.join(root, 'node_modules', '.bin', 'prettier')
+  if (!exists(bin)) return { formatted: false, reason: 'prettier-not-installed' }
+
+  const result = spawnSync(bin, ['--write', ...files], { cwd: root, stdio: 'ignore' })
+
+  return result.status === 0
+    ? { formatted: true, reason: '' }
+    : { formatted: false, reason: 'prettier-failed' }
+}

package/tha/utils/output.mjs

@@ -0,0 +1,79 @@
+import { glyph, ui } from './style.mjs'
+
+export function printHeader(cn, en) {
+  console.log('')
+  console.log(`  ${ui.heading(cn, en)}`)
+  console.log(`  ${ui.rule()}`)
+  console.log('')
+}
+
+export function printErrors(errors) {
+  if (errors.length === 0) return
+
+  console.error('')
+  console.error(`  ${ui.danger(glyph.err)} ${ui.label('配置有问题', 'Config problem')}`)
+
+  for (const error of errors) {
+    const where = error.path ? `${error.file} → ${error.path}` : error.file
+    console.error(`    ${ui.path(where)}`)
+    console.error(`    ${ui.muted(error.message)}`)
+  }
+}
+
+export function printDiff(entries, options = {}) {
+  const groups = [
+    { status: 'add', cn: '将新增', en: 'Will add', mark: glyph.add, paint: ui.success },
+    { status: 'update', cn: '将更新', en: 'Will update', mark: glyph.update, paint: ui.warning },
+    {
+      status: 'edited',
+      cn: '手动改过',
+      en: 'Edited by hand',
+      mark: glyph.warn,
+      paint: ui.danger,
+      hint: 'changed by hand, sync will not overwrite (这些文件被手动改过，tha sync 不覆盖)'
+    },
+    {
+      status: 'conflict',
+      cn: '不会覆盖',
+      en: 'Will not overwrite',
+      mark: glyph.warn,
+      paint: ui.danger,
+      hint: 'existing files not written by CLI (这些文件已存在，但不是 CLI 写的)'
+    },
+    { status: 'same', cn: '无变化', en: 'No change', mark: glyph.same, paint: ui.muted }
+  ]
+
+  if (options.header !== false) printHeader('文件预览', 'Diff')
+
+  let printed = 0
+
+  for (const group of groups) {
+    const items = entries.filter((entry) => entry.status === group.status)
+    if (items.length === 0) continue
+    printed += 1
+
+    console.log(`  ${ui.label(`${group.cn} ${items.length} 个`, `${group.en} ${items.length}`)}`)
+    if (group.hint) console.log(`    ${ui.muted(group.hint)}`)
+    for (const item of items) {
+      console.log(`    ${group.paint(group.mark)} ${ui.path(item.path)}`)
+    }
+    console.log('')
+  }
+
+  if (printed === 0) {
+    console.log(`  ${ui.muted('No changes (没有变化)')}`)
+  }
+}
+
+export function printNextSteps() {
+  const command = (name) => ui.command(name.padEnd(9))
+
+  console.log(`  ${ui.label('下一步', 'Next')}`)
+  console.log(
+    `    ${ui.arrow(command('tha sync'))}  ${ui.muted('generate 5 files (生成 5 个标准文件；模块入口缺失时补一个，之后归你写)')}`
+  )
+  console.log('')
+  console.log(`  ${ui.label('可选', 'Optional')}`)
+  console.log(`    ${ui.bullet(command('tha diff'))}  ${ui.muted('preview files (预览文件)')}`)
+  console.log(`    ${ui.bullet(command('tha check'))}  ${ui.muted('check config (检查配置)')}`)
+}

package/tha/utils/style.mjs

@@ -0,0 +1,147 @@
+/**
+ * CLI 样式层：颜色、符号、间距、主题都只在这里定义。
+ *
+ * 命令层不直接写 ANSI，也不自己拼“✓ / ✗”。
+ * 想换风格，只改这个文件；想临时关颜色，用 --no-color 或 NO_COLOR=1。
+ */
+
+const ANSI = {
+  reset: '\u001b[0m',
+  bold: '\u001b[1m',
+  dim: '\u001b[2m',
+  red: '\u001b[31m',
+  green: '\u001b[32m',
+  yellow: '\u001b[33m',
+  blue: '\u001b[34m',
+  magenta: '\u001b[35m',
+  cyan: '\u001b[36m',
+  gray: '\u001b[90m'
+}
+
+const THEMES = {
+  terminal: {
+    accent: ANSI.cyan,
+    success: ANSI.green,
+    warning: ANSI.yellow,
+    danger: ANSI.red,
+    path: ANSI.blue,
+    muted: ANSI.gray
+  },
+  plain: {
+    accent: '',
+    success: '',
+    warning: '',
+    danger: '',
+    path: '',
+    muted: ''
+  }
+}
+
+export const glyph = Object.freeze({
+  ok: '✓',
+  err: '✗',
+  warn: '!',
+  next: '→',
+  dot: '·',
+  add: '+',
+  update: '~',
+  same: '=',
+  bullet: '·'
+})
+
+const state = {
+  color: detectColor(),
+  theme: detectTheme()
+}
+
+export function configureStyle(options = {}) {
+  const envTheme = options.theme ?? process.env.THA_THEME
+  state.theme = THEMES[envTheme] ? envTheme : 'terminal'
+
+  if (options.noColor) {
+    state.color = false
+    return
+  }
+
+  if (options.color) {
+    state.color = true
+    return
+  }
+
+  if (state.theme === 'plain') {
+    state.color = false
+    return
+  }
+
+  state.color = detectColor()
+}
+
+export function getTheme() {
+  return state.theme
+}
+
+export function isColorEnabled() {
+  return state.color
+}
+
+export const ui = {
+  bold: (text) => paint(ANSI.bold, text),
+  dim: (text) => paint(ANSI.dim, text),
+  accent: (text) => paint(THEMES[state.theme].accent, text),
+  success: (text) => paint(THEMES[state.theme].success, text),
+  warning: (text) => paint(THEMES[state.theme].warning, text),
+  danger: (text) => paint(THEMES[state.theme].danger, text),
+  path: (text) => paint(THEMES[state.theme].path, text),
+  muted: (text) => paint(THEMES[state.theme].muted, text),
+  command: (text) => paint(ANSI.bold, paint(THEMES[state.theme].accent, text)),
+
+  /** "English (中文)"，英文加粗，中文弱化。 */
+  label(cn, en) {
+    return en ? `${paint(ANSI.bold, en)}${paint(THEMES[state.theme].muted, ` (${cn})`)}` : paint(ANSI.bold, cn)
+  },
+
+  /** 顶部品牌行：THA · Title (中文) */
+  heading(cn, en) {
+    const title = en ? paint(ANSI.bold, en) : paint(ANSI.bold, cn)
+    const suffix = en ? paint(THEMES[state.theme].muted, ` (${cn})`) : ''
+    return `${paint(THEMES[state.theme].accent, 'THA')} ${paint(THEMES[state.theme].muted, '·')} ${title}${suffix}`
+  },
+
+  rule(width = 34) {
+    return paint(THEMES[state.theme].muted, '─'.repeat(width))
+  },
+
+  ok(text) {
+    return `${paint(THEMES[state.theme].success, glyph.ok)} ${text}`
+  },
+  warn(text) {
+    return `${paint(THEMES[state.theme].warning, glyph.warn)} ${text}`
+  },
+  error(text) {
+    return `${paint(THEMES[state.theme].danger, glyph.err)} ${text}`
+  },
+  bullet(text) {
+    return `${paint(THEMES[state.theme].muted, glyph.bullet)} ${text}`
+  },
+  arrow(text) {
+    return `${paint(THEMES[state.theme].accent, glyph.next)} ${text}`
+  }
+}
+
+function paint(code, text) {
+  if (!state.color || !code) return text
+  return `${code}${text}${ANSI.reset}`
+}
+
+function detectTheme() {
+  const theme = process.env.THA_THEME
+  return THEMES[theme] ? theme : 'terminal'
+}
+
+function detectColor() {
+  if (process.env.THA_THEME === 'plain') return false
+  if (process.env.NO_COLOR) return false
+  if (process.env.FORCE_COLOR && process.env.FORCE_COLOR !== '0') return true
+  if (!process.stdout.isTTY) return false
+  return process.env.TERM !== 'dumb'
+}

package/tha/utils/ts.mjs

@@ -0,0 +1,73 @@
+// ============ typescript 按需加载：优先用项目自带的 ============
+// CLI 只用 ts 做语法解析（读 config 字面量、遍历 AST），不做类型检查、不编译。
+// 写成普通 dependencies，装 tha-cli 时 npm 自动带一份 5.x —— 用户不用自己装，
+// 也不用为了它降级自己项目的 typescript。运行时优先用项目里 API 齐全的那份（省磁盘），
+// 项目里是 7.x 这种不可用的，就退回 CLI 自带的那份。
+//
+// 用 Proxy 懒加载：import 阶段不碰 typescript，所以 `tha --help` 在任何环境里都能跑。
+
+import { createRequire } from 'node:module'
+import path from 'node:path'
+
+const requireFromProject = createRequire(path.join(process.cwd(), '__tha_resolve__.js'))
+const requireFromSelf = createRequire(import.meta.url)
+
+let real = null
+
+/** 7.x 重写了编译器 API，只剩 version 字段；这几个是 CLI 全流程的硬依赖 */
+const REQUIRED_APIS = ['createSourceFile', 'isObjectLiteralExpression', 'ScriptTarget', 'SyntaxKind']
+
+function isUsable(mod) {
+  return REQUIRED_APIS.every((key) => mod[key] !== undefined)
+}
+
+function load() {
+  let incompatible = null
+
+  for (const req of [requireFromProject, requireFromSelf]) {
+    let mod
+
+    try {
+      mod = req('typescript')
+    } catch {
+      // 这个位置没有，换下一个
+      continue
+    }
+
+    if (isUsable(mod)) return mod
+    incompatible = incompatible ?? mod
+  }
+
+  if (incompatible) {
+    throw new Error(
+      [
+        `项目里的 typescript 是 ${incompatible.version}，这个版本不可用（7.x 重写了编译器 API）。`,
+        '请装 5.x：npm i -D typescript@5',
+        `The installed typescript (${incompatible.version}) is not compatible. Install 5.x: npm i -D typescript@5`
+      ].join('\n')
+    )
+  }
+
+  throw new Error(
+    [
+      '找不到可用的 typescript。CLI 自带的那份（dependencies 里的 5.x）也没解析出来。',
+      '请重装 tha-cli：npm i -D tha-cli',
+      'Cannot resolve a usable "typescript". Reinstall tha-cli: npm i -D tha-cli'
+    ].join('\n')
+  )
+}
+
+export const ts = new Proxy(
+  {},
+  {
+    get(_target, property) {
+      if (!real) real = load()
+      const value = real[property]
+      return typeof value === 'function' ? value.bind(real) : value
+    },
+    has(_target, property) {
+      if (!real) real = load()
+      return property in real
+    }
+  }
+)