tha-cli 0.0.0-stage → 0.1.0

package/tha/config/schema.mjs

@@ -0,0 +1,306 @@
+import { validateFields } from './field.mjs'
+import {
+  API_KEYS,
+  API_RE,
+  CRUD_KEYS,
+  DEFAULT_PAGES,
+  LIST_KEYS,
+  NAME_RE,
+  PAGE_NAMES,
+  PATH_RE,
+  PERMISSION_KEYS,
+  RESERVED_NAMES,
+  SORT_TYPES,
+  TOP_KEYS,
+  error,
+  isPlainObject
+} from './rules.mjs'
+
+export { API_RE, NAME_RE, PATH_RE, normalizeUrlPath } from './rules.mjs'
+
+export function validateProject(configs) {
+  const errors = []
+  const domains = []
+  const names = new Map()
+  const paths = new Map()
+  const apis = new Map()
+
+  for (const parsed of configs) {
+    const file = parsed.relativeFile
+    const raw = parsed.value
+    const before = errors.length
+
+    if (!isPlainObject(raw)) {
+      error(errors, file, '', 'config 必须是一个对象')
+      continue
+    }
+
+    for (const key of Object.keys(raw)) {
+      if (!TOP_KEYS.has(key)) {
+        error(
+          errors,
+          file,
+          key,
+          '不认识的配置项；只支持 name/title/path/api/fields/list/crud/permissions/pages'
+        )
+      }
+    }
+
+    const name = raw.name
+    if (typeof name !== 'string' || !NAME_RE.test(name)) {
+      error(errors, file, 'name', '必须以小写字母开头（允许小驼峰），例如 doc、userProfile')
+    } else {
+      if (RESERVED_NAMES.has(name)) {
+        error(errors, file, 'name', `不能使用保留名 ${name}`)
+      }
+      if (name !== parsed.dirName) {
+        error(errors, file, 'name', `必须和目录名 ${parsed.dirName} 一致`)
+      }
+      if (names.has(name)) {
+        error(errors, file, 'name', `模块名重复，已被 ${names.get(name)} 使用`)
+      } else {
+        names.set(name, file)
+      }
+    }
+
+    const title = raw.title
+    if (typeof title !== 'string' || !title.trim()) {
+      error(errors, file, 'title', '必须是非空字符串')
+    }
+
+    const routePath = raw.path
+    if (typeof routePath !== 'string' || !PATH_RE.test(routePath)) {
+      error(errors, file, 'path', '必须以 / 开头，例如 /doc 或 /system/doc')
+    } else if (paths.has(routePath)) {
+      error(errors, file, 'path', `页面地址重复，已被 ${paths.get(routePath)} 使用`)
+    } else {
+      paths.set(routePath, file)
+    }
+
+    if (!isPlainObject(raw.api)) {
+      error(errors, file, 'api', '必须是对象，例如 { base: "/docs" }')
+    } else {
+      for (const key of Object.keys(raw.api)) {
+        if (!API_KEYS.has(key)) {
+          error(errors, file, `api.${key}`, '不认识的配置项；只支持 base、contract')
+        }
+      }
+      const base = raw.api.base
+      if (typeof base !== 'string' || !API_RE.test(base)) {
+        error(errors, file, 'api.base', '必须以 / 开头，例如 /docs')
+      } else if (apis.has(base)) {
+        error(errors, file, 'api.base', `接口地址重复，已被 ${apis.get(base)} 使用`)
+      } else {
+        apis.set(base, file)
+      }
+    }
+
+    const fields = validateFields(errors, file, raw.fields)
+    const list = validateList(errors, file, raw.list, fields)
+    const crud = validateCrud(errors, file, raw.crud)
+    const permissions = validatePermissions(errors, file, raw.permissions)
+    const pages = validatePages(errors, file, raw.pages, crud)
+    const contract = validateContract(errors, file, raw.api?.contract)
+
+    if (crud && permissions) {
+      if (!crud.create && permissions.create) {
+        error(errors, file, 'permissions.create', 'crud.create 已关闭，不要再声明 create 权限')
+      }
+      if (!crud.update && permissions.update) {
+        error(errors, file, 'permissions.update', 'crud.update 已关闭，不要再声明 update 权限')
+      }
+      if (!crud.remove && permissions.remove) {
+        error(errors, file, 'permissions.remove', 'crud.remove 已关闭，不要再声明 remove 权限')
+      }
+    }
+
+    if (fields && crud) {
+      const listFields = Object.values(fields).filter((field) => field.list)
+      const formFields = Object.values(fields).filter((field) => field.form && !field.readonly)
+
+      if (listFields.length === 0) {
+        error(errors, file, 'fields', '至少有一个字段出现在列表里')
+      }
+
+      if ((crud.create || crud.update) && formFields.length === 0) {
+        error(errors, file, 'fields', '开启新增/编辑时，至少有一个可写字段出现在表单里')
+      }
+    }
+
+    if (errors.length !== before) continue
+
+    domains.push({
+      ...parsed,
+      name,
+      title,
+      path: routePath,
+      api: { base: raw.api.base, ...(contract ? { contract } : {}) },
+      fields,
+      list,
+      crud,
+      permissions,
+      pages
+    })
+  }
+
+  return {
+    domains: errors.length === 0 ? domains : [],
+    errors
+  }
+}
+
+function validatePages(errors, file, value, crud) {
+  if (value === undefined) return [...DEFAULT_PAGES]
+
+  if (!Array.isArray(value)) {
+    error(errors, file, 'pages', '必须是数组，例如 ["list", "detail"]')
+    return null
+  }
+
+  if (value.length === 0) {
+    error(errors, file, 'pages', '至少包含 list')
+    return null
+  }
+
+  const pages = []
+
+  for (const item of value) {
+    if (typeof item !== 'string' || !PAGE_NAMES.has(item)) {
+      error(errors, file, 'pages', `只支持 list、detail、form，收到 ${JSON.stringify(item)}`)
+      continue
+    }
+    if (pages.includes(item)) {
+      error(errors, file, 'pages', `重复的页面：${item}`)
+      continue
+    }
+    pages.push(item)
+  }
+
+  if (!pages.includes('list')) {
+    error(errors, file, 'pages', 'list 必须保留（列表页是入口）')
+  }
+
+  if (crud && pages.includes('form') && !crud.create && !crud.update) {
+    error(errors, file, 'pages', 'form 页需要 create 或 update 至少开一个')
+  }
+
+  return pages.length > 0 ? pages : null
+}
+
+function validateContract(errors, file, value) {
+  if (value === undefined) return undefined
+
+  if (typeof value !== 'string' || !value.trim()) {
+    error(errors, file, 'api.contract', '必须是相对项目根的文件路径，例如 "docs/openapi.json"')
+    return undefined
+  }
+
+  const normalized = value.trim().replace(/\\/g, '/')
+
+  if (normalized.startsWith('/') || normalized.split('/').some((part) => part === '..')) {
+    error(errors, file, 'api.contract', '必须是项目内相对路径，不能写绝对路径或 ..')
+    return undefined
+  }
+
+  if (!/\.(json|ya?ml)$/i.test(normalized)) {
+    error(errors, file, 'api.contract', '只支持 .json / .yaml / .yml 格式的 OpenAPI 文件')
+    return undefined
+  }
+
+  return normalized
+}
+
+function validateList(errors, file, value, fields) {
+  if (value === undefined) return { pageSize: 20 }
+  if (!isPlainObject(value)) {
+    error(errors, file, 'list', '必须是对象，例如 { pageSize: 20 }')
+    return null
+  }
+
+  for (const key of Object.keys(value)) {
+    if (!LIST_KEYS.has(key)) {
+      error(errors, file, `list.${key}`, '不认识的配置项；只支持 pageSize、orderBy、order')
+    }
+  }
+
+  const pageSize = value.pageSize ?? 20
+  if (!Number.isInteger(pageSize) || pageSize < 1 || pageSize > 100) {
+    error(errors, file, 'list.pageSize', '必须是 1–100 的整数')
+    return null
+  }
+
+  const result = { pageSize }
+  const orderBy = value.orderBy
+
+  if (orderBy !== undefined) {
+    if (typeof orderBy !== 'string' || !orderBy.trim()) {
+      error(errors, file, 'list.orderBy', '必须是非空字符串，例如 "createdAt"')
+    } else if (fields && !fields[orderBy]) {
+      error(errors, file, 'list.orderBy', `字段 ${orderBy} 没有在 fields 里声明`)
+    } else if (fields && !SORT_TYPES.has(fields[orderBy].type)) {
+      error(
+        errors,
+        file,
+        'list.orderBy',
+        `${orderBy} 的类型是 ${fields[orderBy].type}，不能排序；能排序的类型：${[...SORT_TYPES].join('、')}`
+      )
+    } else {
+      result.orderBy = orderBy
+    }
+  }
+
+  const order = value.order
+  if (order !== undefined) {
+    if (orderBy === undefined) {
+      error(errors, file, 'list.order', 'order 要和 orderBy 一起写')
+    } else if (order !== 'asc' && order !== 'desc') {
+      error(errors, file, 'list.order', '只支持 asc、desc')
+    } else {
+      result.order = order
+    }
+  }
+
+  return result
+}
+
+function validateCrud(errors, file, value) {
+  if (value === undefined) return { create: true, update: true, remove: true }
+  if (!isPlainObject(value)) {
+    error(errors, file, 'crud', '必须是对象，例如 { create: true, update: true, remove: true }')
+    return null
+  }
+
+  for (const key of Object.keys(value)) {
+    if (!CRUD_KEYS.has(key)) error(errors, file, `crud.${key}`, '不认识的配置项；只支持 create/update/remove')
+    else if (typeof value[key] !== 'boolean') error(errors, file, `crud.${key}`, '必须是 boolean')
+  }
+
+  return {
+    create: value.create !== false,
+    update: value.update !== false,
+    remove: value.remove !== false
+  }
+}
+
+function validatePermissions(errors, file, value) {
+  if (value === undefined) return undefined
+  if (!isPlainObject(value)) {
+    error(errors, file, 'permissions', '必须是对象，例如 { view: "doc:view" }')
+    return null
+  }
+
+  const permissions = {}
+  for (const key of Object.keys(value)) {
+    if (!PERMISSION_KEYS.has(key)) {
+      error(errors, file, `permissions.${key}`, '不认识的配置项；只支持 view/create/update/remove')
+      continue
+    }
+    if (typeof value[key] !== 'string' || !value[key].trim()) {
+      error(errors, file, `permissions.${key}`, '必须是非空字符串')
+      continue
+    }
+    permissions[key] = value[key].trim()
+  }
+
+  return permissions
+}

package/tha/config/template.mjs

@@ -0,0 +1,78 @@
+import { quote } from '../generate/names.mjs'
+
+export function renderInitConfig({ name, title, path, apiBase }) {
+  const exportName = `${name}Config`
+
+  return `/**
+ * THA 模块配置 · ${name}
+ *
+ * 必填：name / title / path / api.base / fields
+ * 选填：pages / list / crud / permissions / api.contract
+ *
+ * 流程：
+ *   tha init ${name} -> 改这里 -> tha sync
+ *   可选：tha diff 预览，tha check 做 CI 检查。
+ *
+ * 规则：
+ * - 这里只描述标准增删改查，不写函数、组件、HTML、请求
+ * - 自定义功能放 domains/${name}/executors/，手写文件不加 .generated 后缀
+ * - 不认识的配置项会报错，一个文件都不会写
+ * - 结构由 tha check 检查；类型见下面注释
+ */
+export const ${exportName} = {
+  // ===== 1. 基本信息（必填）=====
+  name: ${quote(name)},
+  title: ${quote(title)},
+
+  // ===== 2. 页面地址（必填）=====
+  // path 是浏览器里的页面地址，可自定义；内部名称默认用 name。
+  path: ${quote(path)},
+
+  // ===== 3. 接口（必填）=====
+  api: {
+    base: ${quote(apiBase)},
+    // 选填：项目里的 OpenAPI 文件（相对路径，扩展名 .json / .yaml / .yml）。
+    // 填了之后 tha check 会拿它和 fields 比对，报字段缺失与类型不一致。
+    // contract: 'docs/openapi.json'
+  },
+
+  // ===== 4. 字段（必填，至少一个）=====
+  // 类型：string | text | number | boolean | enum | date | datetime
+  // 选填：required / list / form / search / readonly
+  // 类型是 enum 时，必须给 options；default 必须在 options 里。
+  fields: {
+    title: {
+      label: '标题',
+      type: 'string',
+      required: true,
+      search: true
+    }
+  },
+
+  // ===== 5. 页面（选填）=====
+  // 默认：['list', 'detail']
+  // list 必留；detail 生成详情页；form 生成新增/编辑表单页。
+  // form 要求 create 或 update 至少开一个。
+  pages: ['list', 'detail'],
+
+  // ===== 6. 列表（选填）=====
+  // 默认：{ pageSize: 20 }，范围 1–100。
+  // 排序：orderBy 写字段名，order 写 asc / desc（默认 desc）。
+  // 例：{ pageSize: 20, orderBy: 'createdAt', order: 'desc' }
+  list: {},
+
+  // ===== 7. 操作（选填）=====
+  // 默认全开：{ create: true, update: true, remove: true }
+  // 关掉的动作会真裁掉：接口方法、执行器、store 的 pending key、页面按钮一起消失。
+  // 只读示例：{ create: false, update: false, remove: false }
+  crud: {},
+
+  // ===== 8. 权限（选填）=====
+  // 默认 {}，不生成权限文件。
+  // 需要时填写：{ view: '${name}:view', create: '${name}:create', update: '${name}:update', remove: '${name}:remove' }
+  // 填了之后生成 permissions.ts，执行器在每个写动作前判断 can(action)；
+  // permissions.ts 里的 canXxx 是骨架，接到项目自己的权限来源即可。
+  permissions: {}
+}
+`
+}

package/tha/generate/domain/api.mjs

@@ -0,0 +1,67 @@
+// ============ 网络层模板 ============
+// crud 关掉的能力不生成对应方法；pages 要详情/表单才生成 detail。
+
+import { fieldTsType, pascal } from '../names.mjs'
+import { importSpec } from '../../config/paths.mjs'
+
+export function apiBody(domain, dirs) {
+  const type = pascal(domain.name)
+  const baseConst = `${domain.name}ApiBase`
+  const apiModule = importSpec(dirs, 'api', domain.name)
+  const entries = Object.entries(domain.fields)
+  const writable = entries.filter(([, field]) => !field.readonly)
+  const { create, update, remove } = domain.crud
+  const needDetail = domain.pages.includes('detail') || domain.pages.includes('form')
+
+  const docFields = entries
+    .map(([key, field]) => `  ${key}: ${fieldTsType(field)}`)
+    .join('\n')
+
+  const writableType = `{
+${writable
+  .map(([key, field]) => `  ${key}${field.required ? '' : '?'}: ${fieldTsType(field)}`)
+  .join('\n')}
+}`
+
+  const types = [`export interface ${type} {
+  id: number
+${docFields}
+}`]
+
+  if (create) types.push(`export type ${type}Create = ${writableType}`)
+  if (update) types.push(`export type ${type}Update = Partial<${writableType}>`)
+
+  const methods = [`  list: () => request.list<${type}>(${baseConst})`]
+
+  if (needDetail) {
+    methods.push(`  detail: (id: number) => request.detail<${type}>(id, ${baseConst})`)
+  }
+  if (create) {
+    methods.push(`  create: (data: ${type}Create) => request.create<${type}>(data, ${baseConst})`)
+  }
+  if (update) {
+    methods.push(
+      `  update: (id: number, data: ${type}Update) => request.update<${type}>(id, data, ${baseConst})`
+    )
+  }
+  if (remove) {
+    methods.push(`  remove: (id: number) => request.remove(id, ${baseConst})`)
+  }
+
+  const notes = []
+  if (!create) notes.push('create 未开启')
+  if (!update) notes.push('update 未开启')
+  if (!remove) notes.push('remove 未开启')
+
+  return `import { request } from '${importSpec(dirs, 'utils', 'request')}'
+
+/* 网络层：类型 + 增删改查接口。字段来自 config，不需要手写。${notes.length > 0 ? `\n * 已关闭：${notes.join('、')}` : ''} */
+${types.join('\n\n')}
+
+export const ${baseConst} = '${domain.api.base}'
+
+export const ${domain.name}Api = {
+${methods.join(',\n')}
+}
+`
+}

package/tha/generate/domain/context.mjs

@@ -0,0 +1,76 @@
+// ============ 上下文模板 ============
+// 权限落地的地方：ctx.can(action) 是执行器入口与页面按钮共用的唯一判据。
+// 声明了 permissions 就引模块自己的 permissions.ts（骨架只补一次，归人维护）；
+// 没声明就恒为 true，不生成多余文件。
+
+import { pascal } from '../names.mjs'
+import { importSpec } from '../../config/paths.mjs'
+
+export function contextBody(domain, dirs) {
+  const type = pascal(domain.name)
+  const apiModule = importSpec(dirs, 'api', domain.name)
+  const storeModule = importSpec(dirs, 'stores', domain.name)
+  const { create, update, remove } = domain.crud
+  const hasPermissions = Boolean(domain.permissions && Object.keys(domain.permissions).length > 0)
+
+  const actions = [
+    'view',
+    ...(create ? ['create'] : []),
+    ...(update ? ['update'] : []),
+    ...(remove ? ['remove'] : [])
+  ]
+  const actionType = actions.map((action) => `'${action}'`).join(' | ')
+
+  const permissionImport = hasPermissions
+    ? `import { can${type} } from './permissions'\n`
+    : ''
+
+  const canImpl = hasPermissions
+    ? `can: (action) => can${type}(action)`
+    : 'can: () => true'
+
+  return `import { ${domain.name}Api } from '${apiModule}'
+import { use${type}Store, type PendingKey } from '${storeModule}'
+import { toast } from '${importSpec(dirs, 'utils', 'transport')}'
+${permissionImport}
+/** 本模块可判定的动作（跟着 crud 开关走） */
+export type ${type}Action = ${actionType}
+
+/* 上下文：本模块统一的依赖入口；业务执行只依赖 ctx。 */
+export interface ${type}Context {
+  state: ReturnType<typeof use${type}Store>
+  api: typeof ${domain.name}Api
+  ui: {
+    toast: typeof toast
+  }
+  run: <T>(key: PendingKey, task: () => Promise<T>) => Promise<T | undefined>
+  /** 权限判定：执行器入口与页面按钮共用 */
+  can: (action: ${type}Action) => boolean
+}
+
+export function create${type}Context(): ${type}Context {
+  const state = use${type}Store()
+
+  return {
+    state,
+    api: ${domain.name}Api,
+    ui: { toast },
+    ${canImpl},
+    async run<T>(key: PendingKey, task: () => Promise<T>): Promise<T | undefined> {
+      state.setPending(key, true)
+      state.setError(null)
+      try {
+        return await task()
+      } catch (err) {
+        const message = err instanceof Error ? err.message : String(err)
+        state.setError(message)
+        toast('error', message)
+        return undefined
+      } finally {
+        state.setPending(key, false)
+      }
+    }
+  }
+}
+`
+}

package/tha/generate/domain/detail.mjs

@@ -0,0 +1,35 @@
+// ============ 详情页模板 ============
+// pages 含 detail 才生成。id 从路由参数拿，找不到就走中枢的 load 拉一次。
+
+import { pascal } from '../names.mjs'
+import { importSpec } from '../../config/paths.mjs'
+
+export function detailBody(domain, dirs) {
+  const type = pascal(domain.name)
+  const kitDetail = importSpec(dirs, 'components', 'tha/ThaDetail.vue')
+  const config = importSpec(dirs, 'domains', domain.name, 'config')
+  const hub = importSpec(dirs, 'domains', domain.name)
+  const store = importSpec(dirs, 'stores', domain.name)
+
+  return `<script setup lang="ts">
+import { useRoute } from 'vue-router'
+import ThaDetail from '${kitDetail}'
+import { ${domain.name}Config } from '${config}'
+import { use${type}Module } from '${hub}'
+import { use${type}Store } from '${store}'
+
+const route = useRoute()
+const actions = use${type}Module()
+const store = use${type}Store()
+</script>
+
+<template>
+  <ThaDetail
+    :config="${domain.name}Config"
+    :actions="actions"
+    :store="store"
+    :id="Number(route.params.id)"
+  />
+</template>
+`
+}

package/tha/generate/domain/entry.mjs

@@ -0,0 +1,91 @@
+// ============ 中枢骨架模板 ============
+// 只补一次：存在之后归模块所有，sync 不再覆盖。
+// 两条硬约束：内部工厂不导出（防绕开单例）、动作集合跟着 crud 走。
+
+import { pascal } from '../names.mjs'
+import { importSpec } from '../../config/paths.mjs'
+
+export function entryBody(domain, dirs) {
+  const type = pascal(domain.name)
+  const apiModule = importSpec(dirs, 'api', domain.name)
+  const { create, update, remove } = domain.crud
+
+  const needDetail = domain.pages.includes('detail') || domain.pages.includes('form')
+  const executorNames = ['refresh' + type]
+  if (needDetail) executorNames.push('load' + type)
+  if (create) executorNames.push('create' + type)
+  if (update) executorNames.push('update' + type)
+  if (remove) executorNames.push('remove' + type)
+
+  const apiTypeImports = []
+  if (needDetail) apiTypeImports.push(type)
+  if (create) apiTypeImports.push(`${type}Create`)
+  if (update) apiTypeImports.push(`${type}Update`)
+
+  const imports = [
+    `import { create${type}Context, type ${type}Context } from './context'`,
+    `import type { ${type}Action } from './context'`,
+    `import { ${executorNames.join(', ')} } from './executors/crud.generated'`
+  ]
+
+  if (apiTypeImports.length > 0) {
+    imports.push(`import type { ${apiTypeImports.join(', ')} } from '${apiModule}'`)
+  }
+
+  const members = ['refresh: () => Promise<boolean>']
+  const wire = ['refresh: (): Promise<boolean> => refresh' + type + '(ctx)']
+  const moduleMembers = ['refresh', 'can']
+
+  if (needDetail) {
+    members.push(`load: (id: number) => Promise<${type} | undefined>`)
+    wire.push(`load: (id: number): Promise<${type} | undefined> => load${type}(id, ctx)`)
+    moduleMembers.push('load')
+  }
+
+  if (create) {
+    members.push(`create: (input: ${type}Create) => Promise<boolean>`)
+    wire.push(`create: (input: ${type}Create): Promise<boolean> => create${type}(input, ctx)`)
+    moduleMembers.push('create')
+  }
+  if (update) {
+    members.push(`update: (input: { id: number; data: ${type}Update }) => Promise<boolean>`)
+    wire.push(
+      `update: (input: { id: number; data: ${type}Update }): Promise<boolean> => update${type}(input, ctx)`
+    )
+    moduleMembers.push('update')
+  }
+  if (remove) {
+    members.push('remove: (id: number) => Promise<boolean>')
+    wire.push(`remove: (id: number): Promise<boolean> => remove${type}(id, ctx)`)
+    moduleMembers.push('remove')
+  }
+
+  members.push('can: (action: ' + type + 'Action) => boolean')
+  wire.push('can: (action: ' + type + 'Action): boolean => ctx.can(action)')
+
+  return `${imports.join('\n')}
+
+export interface ${type}Module {
+${members.map((member) => `  ${member}`).join('\n')}
+}
+
+let ${domain.name}Module: ${type}Module | null = null
+
+/**
+ * 中枢单例：视图调动作的唯一入口（全局唯一实例，视图不能各造一个私人大脑）
+ * @returns 模块级唯一的 ${type}Module
+ */
+export function use${type}Module(): ${type}Module {
+  if (!${domain.name}Module) ${domain.name}Module = create${type}Module()
+  return ${domain.name}Module
+}
+
+/* 中枢：这里只生成一次脚手架，之后归模块所有，sync 不再覆盖。
+ * 只挂载动作，不判断、不 await、不调接口；不导出，避免视图绕开单例。 */
+function create${type}Module(ctx: ${type}Context = create${type}Context()): ${type}Module {
+  return {
+${wire.map((line) => `    ${line}`).join(',\n')}
+  }
+}
+`
+}