tha-cli 0.0.0-stage → 0.1.0

package/ARCHITECTURE.md

@@ -0,0 +1,193 @@
+# THA 架构设计
+
+> 本文讲**为什么这么设计**：要解决什么、靠什么结构解决、代价是什么。
+> 怎么安装、`config.ts` 怎么写、命令怎么用，见 [README.md](./README.md)。
+> 每条约束的原话在 `tha/verify/rules.mjs`，本文引用的都是那里的 `basis`。
+
+---
+
+## 1. 要解决的问题
+
+前端业务模块的腐化不是某一处写错，而是**每一处单看都合理、堆起来就不可维护**。典型的五种症状：
+
+| 症状 | 后果 |
+|---|---|
+| 页面直接调接口 | 接口一改，页面跟着改 |
+| 状态层里发请求 | 状态和 IO 搅在一起，没法单独测 |
+| 执行器互相 import | 改一个用例，炸三个 |
+| 执行器绕开上下文自己拿依赖 | 依赖关系散落各处，换实现要全局搜 |
+| 一个模块被创建多份 | 「私人大脑」，状态不同步 |
+
+共同点是：靠 code review 抓不住，只能靠结构。所以 THA 不从「写代码的规范」入手，而是**先把一个业务模块的形状定死**。
+
+---
+
+## 2. 一个模块的形状
+
+```
+view      表达意图，不碰实现
+  ↓
+hub       单例，只分发，不写逻辑
+  ↓
+executor  用例，依赖全部从 ctx 来
+  ↓
+step      被第二个用例复用时才下沉
+```
+
+| 层 | 职责 | 不做什么 |
+|---|---|---|
+| view 页面 | 调中枢的动作、读状态 | 不调接口、不建实例、不碰执行器内部 |
+| hub 中枢 | 模块级单例；把动作挂上去 | 不写业务逻辑，不 import `steps/` |
+| executor 执行器 | 写用例，依赖全部走 ctx | 不 import 网络层/状态层/路由，不互相 import |
+| step 零件 | 被多个执行器复用的函数 | 不预判未来，只有一个使用者时不下沉 |
+| context | 提供 state / api / ui / run / can | 不写业务判断 |
+
+形状固定之后，**「这段逻辑该放哪」就不再需要讨论**：有副作用的 IO 进执行器，被复用的纯步骤进步骤，页面只表达意图。
+
+---
+
+## 3. 四条结构决定
+
+### 3.1 中枢只分发
+
+> 「中枢只做分发：把意图交给执行器；禁止直接依赖执行器内部步骤」（HUB-01）
+
+入口一旦开始写逻辑，就会长成上帝对象：先是一个 `if`，然后是一次请求，最后整个模块的业务都堆在 `index.ts` 里。所以中枢只做两件事：**单例缓存、挂载动作**。控制类逻辑（比如中断当前任务）也必须放进执行器，不许写在入口。
+
+### 3.2 执行器只认 ctx
+
+> 「执行器只认 ctx：网络走 ctx.api，状态走 ctx.state」（EXE-02）
+
+生成器的 `context.ts` 提供五样东西：
+
+```ts
+interface Context {
+  state     // 状态
+  api       // 网络
+  ui        // toast
+  run       // 统一的 pending / error / finally 包装
+  can       // 权限判定，入口和页面按钮共用
+}
+```
+
+这是**最小集**，不够就往 `context.ts` 里加——加在上下文，不加在执行器里。好处是：换实现只改一处；写用例测试时塞一个假 ctx 就能跑，不用起 store 和网络。
+
+### 3.3 执行器互不引用
+
+> 「执行器之间互不引用：共用逻辑下沉成零件，用例顺序留在各自执行器里」（EXE-01）
+
+两个用例要共用一段逻辑，正确做法是抽到 `steps/`，不是 A import B。执行器之间的横向引用会形成网，而不是树——网的改动影响范围算不出来。
+
+### 3.4 零件按需下沉，不预判
+
+> 「零件是「同一段步骤被第二个用例用到」才下沉的；只有一个使用者是过度设计」（STEP-01）
+
+这是全套规则里唯一**反对抽象**的一条，而且是 warn 不是 error。它防的是「我先抽个工具函数，以后肯定用得上」——过度设计比重复更贵，因为重复看得见，过度设计看不见。
+
+---
+
+## 4. 依赖方向必须单向
+
+```
+view → hub → executor → step
+              ↑
+        ctx 提供一切外部能力
+```
+
+配套两条边界：
+
+- **状态层只存状态，不发请求**（STORE-01）。请求属于用例，状态只负责被写入。
+- **传输层只上报不越权**（UTIL-01）。错误总线只管把错误抛上来，不决定怎么展示、不感知业务模块。
+
+单向依赖的价值不是「好看」，是**改动影响范围可预测**：改 `steps/` 只影响调用它的执行器，改 `utils/` 不影响任何业务判断。
+
+---
+
+## 5. 边界不靠人记，靠工具查
+
+架构约束写在文档里，没人会读；写成可执行的检查，才有约束力。三个机制：
+
+### 5.1 规则表与判断逻辑分离
+
+`tha/verify/rules.mjs` 只放「说给人听的话」——`id` / `level` / `title` / `basis` / `fix`；
+判断逻辑在 `tha/verify/boundary.mjs`。改文案不动逻辑，改逻辑不动文案。
+
+### 5.2 每条规则带 `basis`
+
+`basis` 直接引用架构原话。输出违规时，能回溯到「哪条约束被破了」，而不是「工具说不行」。
+
+违规条目按这个形状输出：
+
+```
+src/domains/doc/index.ts:1  HUB-03
+  问题：模块入口不是单例，被重复创建
+  没找到缓存的实例（每次调用都会新建一个）
+  应该：在模块顶层用 let 缓存：if (!module) module = createXxxModule()
+  依据：每个领域全局唯一实例，视图不能各造一个「私人大脑」
+```
+
+### 5.3 `import type` 一律放行
+
+类型不构成运行时依赖。只查值导入，规则才不至于因噎废食。
+
+---
+
+## 6. 生成与检查分离
+
+| | 管什么 | 不管什么 |
+|---|---|---|
+| 产线（sync） | 标准形态：`config.ts` → 5 个文件 + 注册表 | 不生成业务逻辑 |
+| 护栏（check） | 所有代码，包括完全手写的模块 | 不替你改代码 |
+
+`adopt` 的语义最能说明这个分工：**放弃「写」，不放弃「管」**。文件交给人之后，生成器退出，但分层规则照样查。这样「生成」和「约束」就是两件可以独立演进的事——生成器可以不管某个文件，但架构约束不能有盲区。
+
+---
+
+## 7. 配置面收窄
+
+`config.ts` 顶层只有 9 个键，多写一个直接报错，当次一个文件都不生成。
+
+逻辑：**配置项每多一个，生成器要处理的组合就翻一倍，边界就越难守**。宁可让人在代码里写，也不让配置去表达——代码里的复杂度是局部的，配置里的复杂度是全局的。
+
+---
+
+## 8. 代价
+
+说清楚取舍的另一面：
+
+1. **只覆盖标准 CRUD**。工作流、嵌套表单、自定义布局仍然人写，工具只保证不覆盖、不误报。
+2. **小模块显得重**。一个简单模块也要 5~6 个文件，抽象成本前置了。
+3. **有学习曲线**。得先理解 hub / executor / step / ctx 四层语义才能顺畅写。
+4. **原型阶段会变慢**。强约束要求先想清楚形状再动手。
+5. **生成物是复制不是引用**。CLI 升级后，项目里已有的基线组件不会自动更新。
+
+所以它的定位不是「通用代码生成器」，而是：**让一个人写业务的时候，不需要记架构**。约束由工具承担，人只负责业务本身。
+
+---
+
+## 9. 规则索引
+
+| id | 级别 | 约束原话（`basis`） |
+|---|---|---|
+| HUB-01 | error | 中枢只做分发：把意图交给执行器；禁止直接依赖执行器内部步骤 |
+| HUB-03 | warn | 每个领域全局唯一实例，视图不能各造一个「私人大脑」 |
+| EXE-01 | error | 执行器之间互不引用：共用逻辑下沉成零件，用例顺序留在各自执行器里 |
+| EXE-02 | error | 执行器只认 ctx：网络走 ctx.api，状态走 ctx.state |
+| EXE-03 | error | 执行器只认 ctx：日志 / 时钟 / 流 / 鉴权走 ctx.ports，判定走 ctx.errors |
+| STEP-01 | warn | 零件是「同一段步骤被第二个用例用到」才下沉的；只有一个使用者是过度设计 |
+| VIEW-01 | error | 视图只表达意图：动作走域中枢，数据直读状态层 |
+| VIEW-02 | error | 每个领域全局唯一实例：视图只能经 useXxxModule() 取，不能自己 create |
+| STORE-01 | error | 状态层只存状态，不发请求 |
+| UTIL-01 | error | 传输层只上报不越权：不感知业务模块，不做展示 |
+
+规则真源：[`tha/verify/rules.mjs`](./tha/verify/rules.mjs)　判断逻辑：[`tha/verify/boundary.mjs`](./tha/verify/boundary.mjs)
+
+`EXE-03` 提到的 `ctx.ports` / `ctx.errors` 是架构原话里的完整形态；生成器当前的 `context.ts` 只给最小集（`state` / `api` / `ui` / `run` / `can`），需要时按 3.2 往上下文里加。
+
+---
+
+## 10. 相关文档
+
+- [README.md](./README.md)——安装、命令、`config.ts` 全量配置项、契约与退出码
+- `tha/generate/domain/`——每一类生成物的模板，是「形状」的可执行版本
+- `tha/verify/rules.mjs`——规则真源，改架构先改这里

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 温强
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,409 @@
-# Temporary Holding Version
+# tha-cli
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+THA 架构的构建期工具。两副面孔：**产线负责生成，护栏负责守边界。**
+
+- **产线**：读 `domains/<域>/config.ts`，生成标准文件（基线 5 个，按 `pages` 追加详情 / 表单）和全局注册表。
+- **护栏**：没有 `config.ts` 的手写模块，不生成，只按层查边界。
+- **自带基线**：`init` 顺手补齐生成物要 import 的组件和工具，空项目也能直接跑。
+
+产物不依赖 `tha`：上线后可以把它从 `devDependencies` 删掉。
+
+设计思想、取舍与代价见 [ARCHITECTURE.md](./ARCHITECTURE.md)；本文只讲怎么用。
+
+---
+
+## THA 架构
+
+分层，依赖只能向下：
+
+```
+views       页面    只调中枢，不碰网络层和执行器内部
+domains     领域    中枢（单例，只挂动作）→ 执行器（用例）→ 零件（被复用的函数）
+stores      状态    只管状态和原子更新，不发请求
+api         网络    请求和类型
+utils       基础    纯函数、远端传输
+```
+
+一个领域只有一个入口：
+
+- **中枢** `index.ts` 对外只暴露 `useXxxModule()`，模块级单例，重复创建即违规。
+- **执行器** 写用例，依赖全部走 `context.ts` 注入，不直接 import 网络层、状态层、路由。
+- **零件** 是被多个执行器复用的函数，只被一个执行器用时不算零件。
+
+这套约束的目的很单一：业务写在一处，边界由工具守，不靠人记。
+
+为什么这么切分、每条约束的原话和代价，见 [ARCHITECTURE.md](./ARCHITECTURE.md)。
+
+---
+
+## tha-cli 做什么
+
+| 模式 | 输入 | 产物 |
+|---|---|---|
+| 产线 | `config.ts` | 标准 CRUD 的 api / store / context / 执行器 / 页面 / 路由 / 菜单 |
+| 护栏 | 任意源码 | 违规清单（10 条边界规则 + 契约比对） |
+
+它不生成业务逻辑。`config.ts` 声明「这个模块有哪些字段、开哪些动作」，工具把标准部分铺好；复杂逻辑仍然人写，写在自定义执行器里，工具不覆盖。
+
+---
+
+## 安装
+
+```bash
+npm i -D tha-cli
+npx tha-cli check
+```
+
+前置条件：
+
+- **TypeScript 项目**（`.ts` / `.vue`）。纯 JS 项目不支持——模块靠 `config.ts` 识别，生成物也全是 TS。
+- 不需要自己装 `typescript`。CLI 自带一份 5.x，只用于解析源码（读 `config.ts`、遍历 AST），不参与你项目的构建——你项目里用 5.x 还是 7.x 都不影响它。
+
+---
+
+## 快速开始
+
+```bash
+tha init doc        # 建 config 模板，不生成代码
+# 编辑 src/domains/doc/config.ts
+tha sync            # 生成 5 个文件；中枢缺失时补一次骨架
+tha check           # 检查：配置 + 契约 + 护栏 + 漂移
+```
+
+CI：
+
+```bash
+tha check            # 有 error 即非零退出
+tha check --strict   # 警告也算失败
+tha check --json     # 机器可消费
+```
+
+---
+
+## 命令
+
+| 命令 | 作用 |
+|---|---|
+| `tha init <域>` | 建 config 模板 + 补齐基线（`--bare` 只写 config） |
+| `tha sync [<域>]` | 生成 / 更新标准 CRUD 与注册表；补一次中枢骨架 |
+| `tha check` | 只检查不写：配置 + 契约（响应与请求体）+ 护栏 + 漂移 |
+| `tha diff` | 显示将要发生的文件变化 |
+| `tha remove <域>` | 删模块：生成物清掉，手写文件保留；保留的文件若还引用已删生成物会明确报出来 |
+| `tha adopt <文件...>` | 这个文件以后你自己维护：不再自动生成，但分层规则照样查 |
+| `tha adopt <文件...> --release` | 交回生成管理 |
+
+参数按用途分组：
+
+- 初始化：`--bare`（不补基线）、`--config`（写目录映射示例）
+- 写盘：`--all`、`--force`、`--yes`（非交互确认；`adopt` 接受但忽略，它只改清单）、`--prune`（含清空目录）、`--dry-run`
+- 检查：`--strict`、`--json`
+- 定位：`--root`
+- 交接：`--release`
+
+非交互环境（脚本 / CI）不加 `--yes` 不会写盘。
+
+---
+
+## 一个标准域的文件
+
+```
+<domains>/<域>/
+├── config.ts                  手写：唯一真源
+├── index.ts                   手写：中枢（单例 + 只挂载动作；缺失时补骨架）
+├── permissions.ts             按需生成：权限码 + canXxx 骨架（声明了权限码才有）
+├── context.ts                 生成：DI + can
+├── executors/
+│   ├── crud.generated.ts      生成：refresh / load / create / update / remove（按 crud 裁剪）
+│   └── <用例>.ts              手写：自定义用例（可选）
+└── steps/                     手写：被多个用例复用的零件（可选）
+
+<api>/<域>.ts                  生成：类型 + CRUD 接口（按 crud 裁剪）
+<stores>/<域>/index.ts         生成：状态 + 原子更新（按 crud 裁剪）
+<views>/<域>/Index.vue         生成：列表页
+<views>/<域>/Detail.vue        pages 含 detail 时生成
+<views>/<域>/Form.vue          pages 含 form 时生成
+
+<router>/routes.generated.ts   全局生成
+<layouts>/menu.generated.ts    全局生成
+```
+
+`<domains>` / `<api>` / `<views>` 是目录映射的键，默认 `src/domains`、`src/api`、`src/views`（见「目录映射」）。
+
+中枢骨架带单例，视图只调 `useXxxModule()`：
+
+```ts
+let docModule: DocModule | null = null
+
+export function useDocModule(): DocModule {
+  if (!docModule) docModule = createDocModule()
+  return docModule
+}
+
+// 内部工厂不导出：视图拿不到第二份
+function createDocModule(ctx = createDocContext()): DocModule { ... }
+```
+
+---
+
+## 配置项：一个 config 的完整形状
+
+`tha init doc` 生成的骨架只开最基本的：
+
+```ts
+export const docConfig = {
+  name: 'doc',                    // 内部名：目录、action、变量名都从它推
+  title: '文档',                  // 显示名：菜单、页面标题
+  path: '/doc',                   // 浏览器地址
+  api: { base: '/docs' },         // 接口前缀
+  fields: {
+    title: { label: '标题', type: 'string', required: true, search: true }
+  },
+  pages: ['list', 'detail'],
+  list: {},
+  crud: {},
+  permissions: {}
+}
+```
+
+可选项都填上：
+
+```ts
+export const docConfig = {
+  name: 'doc',
+  title: '文档',
+  path: '/doc',
+
+  api: {
+    base: '/docs',
+    contract: 'docs/openapi.json'        // 填了才做字段比对
+  },
+
+  fields: {
+    title:       { label: '标题', type: 'string', required: true, search: true },
+    summary:     { label: '摘要', type: 'text' },
+    wordCount:   { label: '字数', type: 'number', list: true, search: true },
+    published:   { label: '已发布', type: 'boolean', default: false },
+    status: {
+      label: '状态',
+      type: 'enum',
+      default: 'draft',
+      search: true,
+      options: [
+        { label: '草稿', value: 'draft', color: 'gray' },
+        { label: '已发布', value: 'published', color: 'ok' },
+        { label: '已下线', value: 'offline', color: 'warn' }
+      ]
+    },
+    publishedAt: { label: '发布时间', type: 'datetime', list: true },
+    createdAt:   { label: '创建日期', type: 'date', readonly: true }
+  },
+
+  pages: ['list', 'detail', 'form'],
+  list: { pageSize: 50, orderBy: 'createdAt', order: 'desc' },
+  crud: { create: true, update: true, remove: false },
+  permissions: { view: 'doc:view', create: 'doc:create', update: 'doc:update' }
+}
+```
+
+### 顶层配置
+
+| 键 | 必填 | 取值 | 默认 | 说明 |
+|---|---|---|---|---|
+| `name` | 是 | 小驼峰，如 `doc` / `userProfile` | — | 内部名，决定目录、action 名 |
+| `title` | 是 | 非空字符串 | — | 显示名 |
+| `path` | 是 | `/doc` 或 `/sys/doc`，不能带尾斜杠 | — | 页面地址 |
+| `api.base` | 是 | `/docs`，不能带尾斜杠 | — | 接口前缀 |
+| `api.contract` | 否 | 项目内 `.json` / `.yaml` / `.yml` 相对路径 | 无 | OpenAPI 文件，填了才比对字段 |
+| `fields` | 是 | 对象，至少一个字段 | — | 字段声明 |
+| `pages` | 否 | `list` / `detail` / `form` 的数组 | `['list','detail']` | 要生成哪几个页面 |
+| `list.pageSize` | 否 | 1–100 的整数 | `20` | 每页条数 |
+| `list.orderBy` | 否 | `fields` 里声明过的字段名 | 无 | 列表默认按这个字段排序 |
+| `list.order` | 否 | `asc` / `desc` | `desc` | 和 `orderBy` 一起写 |
+| `crud` | 否 | `create` / `update` / `remove` 布尔 | 全 `true` | 关掉的动作整条链都不生成 |
+| `permissions` | 否 | `view` / `create` / `update` / `remove` 权限码 | `{}` | 非空才生成 `permissions.ts` |
+
+顶层**只有这 9 个键**，多写一个直接报「不认识的配置项」，一个文件都不会写。
+
+### 字段配置
+
+| 键 | 必填 | 取值 | 默认 | 说明 |
+|---|---|---|---|---|
+| `label` | 是 | 非空字符串 | — | 列表列头、表单项标签 |
+| `type` | 是 | `string` / `text` / `number` / `boolean` / `enum` / `date` / `datetime` | — | `text` 是长文本 |
+| `required` | 否 | 布尔 | `false` | 必填校验 + 契约比对用 |
+| `list` | 否 | 布尔 | `true` | 是否出现在列表列（写 `false` 才关） |
+| `form` | 否 | 布尔 | `true` | 是否出现在表单（写 `false` 才关） |
+| `search` | 否 | 布尔 | `false` | 是否可搜索 |
+| `readonly` | 否 | 布尔 | `false` | 只读：不出现在表单，只在详情/列表显示 |
+| `options` | `enum` 时必填 | `[{ label, value, color }]` | — | `color` 取 `gray` / `ok` / `warn` / `red` / `blue` |
+| `default` | 否 | 与类型匹配的值 | 无 | `enum` 的 `default` 必须在 `options` 的 value 里 |
+
+`id` 由 CLI 生成，**不要在 `fields` 里写 `id`**。
+
+### 会直接报错的写法
+
+| 写法 | 报什么 |
+|---|---|
+| 顶层多一个键（如 `filters`、`templates`） | 不认识的配置项；该次 `sync` 一个文件都不写 |
+| 字段名叫 `id`，或 `Title` 这种大写开头 | 字段名必须小写开头 |
+| `readonly: true` 同时 `form: true` | 只读字段不能进表单 |
+| `search: true` 用在 `text` / `boolean` | 只有 string / enum / number / date / datetime 可搜索 |
+| `enum` 没写 `options`，或 `default` 不在 `options` 里 | 枚举字段必须给非空 options；default 必须在其中 |
+| `pages` 里没有 `list`，或同一页写两遍 | list 必须保留（列表页是入口）；重复的页面要删掉 |
+| `pages` 含 `form` 但 `crud` 全关 | form 页需要 create 或 update 至少开一个 |
+| `name: 'views'` 这种撞目录名的 | 不能使用保留名（api / stores / domains / views / router / layouts / components / utils） |
+| `list.pageSize: 0` 或 `500` | 必须是 1–100 的整数 |
+| `list.orderBy` 指向 `fields` 里没有的字段，或 enum / boolean | 排序字段必须已声明，且类型可排序 |
+| 只写 `list.order` 不写 `orderBy`，或 `order` 不是 asc / desc | order 要和 orderBy 一起写；只支持 asc、desc |
+
+### 常见组合
+
+```ts
+pages: ['list']                                        // 只要列表
+crud: { create: false, update: false, remove: false }  // 只读模块
+pages: ['list', 'form']                                 // 不要详情，只在列表 + 表单页
+permissions: { view: 'doc:view', update: 'doc:update' } // 只声明用得上的权限码
+api: { base: '/docs', contract: 'docs/openapi.json' }   // 接后端契约比对
+```
+
+---
+
+## 目录映射：不想放 src/ 就改这里
+
+项目根建 `tha.config.json`：
+
+```json
+{ "dirs": { "views": "src/pages", "stores": "src/model", "api": "src/services", "utils": "src/shared" } }
+```
+
+可用键：`domains` / `views` / `stores` / `api` / `router` / `layouts` / `components` / `utils`。
+不写就用默认值；写错（绝对路径、`..`、未知键）直接报错，一个文件都不生成。
+生成代码里的 import 会自动跟着改（`src/services` → `@/services`）。
+
+`tha init <域> --config` 会写一份全默认值的示例，改完删掉即回默认。
+
+---
+
+## 所有权：四种文件，四种命运
+
+| 所有权 | 怎么识别 | sync | check |
+|---|---|---|---|
+| generated | 有 `@tha-generated` 生成头，hash 对得上 | 可以更新 | 照常查边界 |
+| handwritten | 没有生成头，且不在交接清单 | 永不覆盖 | 提示，照常查边界 |
+| adopted | 在 `.tha/manifest.json` 的 `manual` 里 | 永不覆盖、不比对漂移 | 不算失败，照常查边界 |
+| edited | 有生成头但 hash 对不上 | 拒绝，除非 `--force` | 报 drift |
+
+`adopt` 只接受构建期会生成的文件（用 `tha diff` 查看）。清单写在
+`.tha/manifest.json`，建议提交到版本库。
+
+**adopt 的语义**：工具放弃「写」，不放弃「管」。
+
+---
+
+## 护栏：10 条边界规则
+
+规则唯一真源在 `tha/verify/rules.mjs`，每条带 `id` / `level` / `basis`（架构原话）/ `fix`。
+
+| id | 级别 | 判据 |
+|---|---|---|
+| HUB-01 | error | 中枢直接 import `./steps/*` |
+| HUB-03 | warn | 中枢不是模块级单例 |
+| EXE-01 | error | 执行器之间互相 import |
+| EXE-02 | error | 执行器 / 零件值导入网络层、状态层、路由 |
+| EXE-03 | error | 执行器 / 零件值导入 `@/utils/*`（纯函数白名单除外） |
+| STEP-01 | warn | 零件只被 0 或 1 个执行器使用 |
+| VIEW-01 | error | 视图值导入网络层 / 传输层 / 执行器内部 |
+| VIEW-02 | error | 视图直接 `createXxxModule()`，绕开单例 |
+| STORE-01 | error | 状态层 import 网络层 |
+| UTIL-01 | error | 基础设施 import UI 库或业务模块 |
+
+约定：
+
+- `import type` 一律放行（类型不构成运行时依赖）。
+- 检查**按层扫**：`views/`、`stores/`、`utils/` 全局一遍，`domains/<域>/` 按模块。
+- 手写模块靠目录形状识别：有 `index.ts` / `executors/` / `context.ts`，但没有 `config.ts`。
+- `PURE_UTILS` 白名单在 `rules.mjs` 里声明，不再靠 eslint 注释豁免。
+
+---
+
+## 契约与权限：声明了就得真生效
+
+这两项最容易出现「配置写了、产物有、但那件事没发生」，所以检查口径要明确。
+
+**字段契约**对两个方向都比（`api.contract` 指向的 OpenAPI，`.json` / `.yaml` / `.yml` 都认）：
+
+| 方向 | 取自 | 级别 |
+|---|---|---|
+| 响应：config 字段后端没有 | GET 200 / POST 201 的 schema（`{code,data}` 包装自动解一层） | error |
+| 响应：类型不一致 | 同上 | error |
+| 响应：`format` / 必填 / 后端多字段 | 同上 | warn |
+| 请求体：表单会提交的字段（`form !== false`）后端不收 | POST 请求体 → `create`；PUT / PATCH → `update` | error |
+| 请求体：类型不一致 | 同上 | error |
+| 请求体：后端必填、config 里没有可提交字段 | 同上 | error |
+| 请求体：后端有可选字段 config 没声明 | 同上 | warn |
+| 契约里没写请求体 | — | 一条 warn，跳过，不逐字段误报 |
+
+**权限守卫**：`permissions` 非空的模块，执行器里必须至少有**一处** `can(...)` 判断（注释不算）。一处都没有 → error，提示「声明了 permissions，但执行器里没有任何 can(...) 判断」。
+
+这条专门兜 `adopt`：生成模板里本来每个动作前都有 `ctx.can('view')`，一旦这个文件交给手写，生成器不再管它，只有这条检查还能发现「权限被悄悄删了」。
+
+---
+
+## 退出码
+
+`drift` / 手写冲突 / 契约失败（响应或请求体）/ 权限守卫缺失 / 护栏 error 任一存在 → `1`；
+`--strict` 时契约与护栏的 warn 也算失败。
+
+---
+
+## 注意事项
+
+实际用起来会踩到的几条：
+
+1. **只覆盖标准 CRUD**。列表 / 详情 / 表单、增删改查、搜索分页是标准形态；工作流、嵌套表单、自定义布局这类复杂模块仍然人写，工具只保证不覆盖、不误报。
+2. **自带组件是复制，不是引用**。`init` / `sync` 会把 `ThaCrudPage.vue` 等基线复制进项目。之后 CLI 升级，项目里那份**不会自动更新**：新能力（比如 `list.orderBy`）在老项目里不生效。要么删掉该文件重新 `sync`，要么手动把改动抄过去。
+3. **`list.orderBy` 只排前端**。它是 `ThaCrudPage` 的本地排序，不会给后端接口加 query 参数。要后端排序，那是接口契约的事。
+4. **`api.contract` 的 YAML 解析依赖 `yaml` 包**，随 CLI 一起装，不需要单独安装。
+5. **`config.ts` 顶层只有 9 个键**。多写一个直接报错，该次 `sync` 一个文件都不写。收窄配置面是有意的，否则守不住边界。
+6. **非交互不写盘**。脚本里不加 `--yes`，`sync` / `remove` 只打印计划。
+7. **adopt 是放弃写、不放弃管**。文件交给你之后，工具不再生成它，但分层规则照样查。
+
+---
+
+## 开发
+
+```bash
+node test/guard.test.mjs     # 造 10 种违规，断言 10/10 命中 + 退出码 1
+node test/snapshot.test.mjs  # 固定配置 → 与 test/snapshots/ 逐字节比对（--update 重记）
+node test/openapi.test.mjs   # 契约比对：方言、YAML、请求体方向
+```
+
+目录：
+
+```
+tha/
+├── cli.mjs              入口分发
+├── commands/            init / sync / check / diff / remove / adopt
+├── kit/                 自带页面与基线（ThaCrudPage / ThaDetail / ThaForm / request / transport）
+├── config/              paths（目录映射）、project（config + 手写模块）、manifest（交接清单）
+├── generate/            plan + 模板（api、store、context、executors、entry、detail、form、permissions）
+├── verify/              rules（规则真源）、ast、boundary、contract、openapi、scan
+└── utils/               files / compare / output / style / format
+test/                    guard.test.mjs、snapshot.test.mjs、openapi.test.mjs、snapshots/
+```
+
+---
+
+## 发布
+
+```bash
+npm test                 # guard + snapshot + openapi 三套
+npm pack --dry-run       # 看会打进包里哪些文件
+npm publish
+```
+
+包里只带 `tha.mjs` + `tha/` + `README.md` + `ARCHITECTURE.md`（`LICENSE` 由 npm 自动带上）；`test/` 与 `snapshots/` 不进包，`typescript` 也不进包——它写在 `dependencies` 里，安装时由 npm 单独下载。
+
+`typescript` 是普通依赖（`^5`），不参与你项目的构建。运行时先找项目里的那份（API 齐全才用），不齐就退回 CLI 自带的那份；两边都不能用时才报错，不会静默跳过检查。
+
+包名 `tha-cli` 若在 npm 上已被占用，改 `package.json` 的 `name` 再发；命令名由 `bin` 决定，仍然是 `tha`。

package/package.json

@@ -1,6 +1,44 @@
 {
   "name": "tha-cli",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "THA 架构的构建期工具：产线生成标准增删改查，护栏守住分层边界。",
+  "type": "module",
+  "author": "温强 <373601967@qq.com>",
+  "repository": {
+    "type": "git",
+    "url": "git+https://gitee.com/JonnyWen6699/tha-cli.git"
+  },
+  "homepage": "https://gitee.com/JonnyWen6699/tha-cli#readme",
+  "bugs": {
+    "url": "https://gitee.com/JonnyWen6699/tha-cli/issues"
+  },
+  "bin": {
+    "tha": "tha.mjs"
+  },
+  "files": [
+    "tha.mjs",
+    "tha",
+    "README.md",
+    "ARCHITECTURE.md"
+  ],
+  "engines": {
+    "node": ">=18.17"
+  },
+  "scripts": {
+    "test": "node test/guard.test.mjs && node test/snapshot.test.mjs && node test/openapi.test.mjs",
+    "snapshot": "node test/snapshot.test.mjs --update"
+  },
+  "keywords": [
+    "tha",
+    "codegen",
+    "architecture",
+    "boundary",
+    "vue",
+    "cli"
+  ],
+  "license": "MIT",
+  "dependencies": {
+    "typescript": "^5",
+    "yaml": "^2.9.1"
+  }
+}