@stalfh233/omc-cli 0.0.0-stage → 0.4.10

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Oh-My-CpAgent contributors
+
+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,293 @@
-# Temporary Holding Version
-
-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.
+# omc-cli
+
+把 CloudPivot 8.6 的配置能力封装为一个本地 **CLI**——受治理、失败即关闭（fail-closed），并以一份机器可读的覆盖清单为边界。
+
+- **一条 CLI 工具面**——高层编排（`configure_model` / `configure_form` /
+  `configure_rule` / `apply_changes` / `discover_environment` / `get_status`）与低层原子工具共用同一条管道。
+- **对话人门 + 环境写权限**——真正的人门在对话层：执行变更前先讲清草稿、资源、逐条改动与清理并等待明确批准；机器侧只有环境 profile 的 `writable` 开关。只读环境零 wire 拒绝，允许写入环境直接执行。
+- **生产是高危标签**——`production:true` 不再禁止写入；生产写必须在每笔参数中带 `confirmProduction:true`，结果和审计工件记录 `productionConfirmed:true`。
+- **不再有令牌审批**——删除 `approval.request`、HMAC/TTL/指纹令牌、`selfApprove`、`OMC_CLI_SELF_APPROVE`、`--yes` 和交互 y/N。保留 dry-run、覆盖门、版本族门、写租约、权威读回和不确定性冻结。
+- **覆盖清单边界**——随包内置的 M1 清单即契约；超出覆盖范围的调用会拒绝并引用清单条目。非 8.6 版本族（以及缺少版本证据）的写操作失败即关闭。
+- **写租约**——同一环境内的并发写会串行化（进程内）。
+- **本地 dry-lint**——写前零 wire 拒绝坏形状，而不是写到环境才发现：
+  **规则图**（路由必备 `points`/`routeCondition`/`matchType`、节点类型/取值枚举、
+  动态来源键位）、**业务编码**（模型 ≤26/字段 ≤28、lowerCamel|lower_snake、
+  拒绝平台保留字）、**表单布局**（span 白名单、行宽 ≤24、整行独占、控件覆盖率）、
+  字段族门。违规返回结构化 `validation`，不猜不改。
+- **规则图自动规范化**——线性图缺坐标或节点重叠时，工具自动铺成平台标准单列
+  （x=327、158×40、y=36/116/196…），缺失路由坐标按节点**边中点**推导，缺失
+  `routeCondition`/`matchType` 补 `true`/`ANY`；已可渲染的布局与分支图原样保留
+  ——调用方无需手算几何。
+- **方法论即可读**——`skills/` 下的方法论通过 `omc help <topic>` 按需读取；agent 不必去翻仓库文件。
+- **凭据零回显**——凭据（0600 存储或环境变量）不会出现在任何输出、产物或错误里。
+- **不确定性语义**——传输失败时冻结（`status: "uncertain", frozen: true`），
+  绝不伪造成功。
+
+## 快速开始
+
+```bash
+omc setup && omc doctor && omc commands --json
+```
+
+配置入口是 `omc setup`；不确定从哪开始读 `omc help omc-start-here`（任务→topic 路线），
+被拒或状态异常读 `omc help omc-refusals`（拒绝族的含义与下一步），
+写入治理读 `omc help omc-config-draft-review`。
+
+### 权威发现路线（静态/就绪分离）
+
+随包 `skills/` 是方法论 topic 的**权威**副本；下游 cpdocs 快照只是镜像，不得当作第二真相源。
+`help` / `commands` / `capabilities` 都返回同一份 `discovery` 投影（`authoritative`、
+`route`、`readiness`、`distributedMirror`）。
+
+```bash
+omc capabilities                                  # 能力 nickname/id/lane/aliases/tools/commands 一张表
+omc capability <id-or-alias> --executable         # 选中能力的完整执行包（离线，不接触环境）
+omc contract <lane-from-the-capability>           # wire 契约 + 该能力路由
+omc describe <tool-from-the-bundle>               # schema + recipe + 能力路由
+omc call discover_environment --env <env> --args '{}'   # 环境就绪（真实环境）
+```
+
+`commands --json` 是完整工具清单，每个 lane-bound 工具都带 `capability` 映射；
+`describe` 与 `contract` 重复所选能力路由，切换面不必再宽扫 topic 或契约。
+`omc eval:discovery-comparison` 输出相对 ticket 01 基线的调用数/字节数对比。
+
+## 工具面（90 个工具）
+
+| 类别 | 数量 | 说明 |
+|---|---|---|
+| 写工具 | 56 | 高层编排 4（`configure_*` + `apply_changes`）+ 低层原子写 52 |
+| 读工具 | 29 | `*.list` / `*.get` / `*.load` / `discover_environment` |
+| 治理/元工具 | 5 | `get_status`、`doctor`、`coverage.manifest`、`setup.*` |
+
+**全集与逐工具参数**：`omc commands --json`（name/lane/kind/requiredArgs/writeGate/timeout）、
+`omc describe <tool>`（完整 schema + 可运行示例）。大结果自动落到 `detailFile` 工件，
+只回计数/摘要；相同目标 fingerprint 的重复读返回 `unchanged`（带缓存命中信号）。
+
+### 治理 / 元工具（5）
+
+| 工具 | 作用 |
+|---|---|
+| `get_status` | 环境健康：连通性、登录、版本族、凭据库权限位、租约、覆盖摘要、写入姿态（`writable` / 是否生产 / 是否需 `confirmProduction` / 已移除配置键） |
+| `doctor` | 只报告的健康链：配置文件 → 凭据 → 登录 → 8.6 版本族兼容 → 环境指纹 |
+| `coverage.manifest` | 覆盖清单投影（能力基线的机器可读视图） |
+| `setup.start` | 配置引导入口：返回待填字段与当前非密值 |
+| `setup.commit` | 幂等提交环境配置（写 `omc.config.json` + 0600 凭据库），随后跑连通性+登录+版本族校验 |
+
+### 读工具（29）
+
+| 域（lane） | 工具 |
+|---|---|
+| 环境 `environment-governance` | `discover_environment`、`environment.fingerprint` |
+| 应用 `app-management` | `app.list` |
+| 数据字典 `dictionary-management` | `dictionary.list`、`dictionary.type`、`dictionary.names`、`dictionary.get`、`dictionary.records`、`dictionary.parent`、`dictionary.classes` |
+| 字段 `field-families` | `field.list` |
+| 表单 `form-publish-chain` | `form.get` |
+| 字段级规则 `G1-datarule` | `datarule.list` |
+| 业务规则 `B1-businessrule` | `rule.list`、`rule.get` |
+| 流程 / 待办 `W7-S29-greenfield` | `workflow.get_draft`、`workflow.get_published`、`workitem.list` |
+| 运行数据 `M2-runtime-data` | `data.list`、`data.load` |
+| 业务集成 `B2-registration` | `service.get`、`method.get`、`service.category.list`、`service.dbconnpool.list`、`service.adapter_config`、`service.table_list`、`service.table_sql`、`service.export`、`service.check` |
+
+## 能力总览（14 项）
+
+`omc capabilities` 的静态快照；跑 `omc capabilities` / `omc capability <id>` 取实时投影。
+「依赖」= `requires → precedes`，即能力之间的配置顺序。
+
+| 能力 | 标题 | lane | 覆盖 | intent | 依赖 |
+|---|---|---|---|---|---|
+| `environment` | 环境治理 | `environment-governance` | executable | none | - → - |
+| `app` | 应用 | `app-management` | executable | none | - → - |
+| `dictionary` | 数据字典 | `dictionary-management` | executable | none | - → - |
+| `model` | 业务模型 | `model-management` | executable | partial | - → field, workflow |
+| `field` | 字段（含子表） | `field-families` | executable | partial | model → form, listview, datarule, businessrule, data |
+| `form` | 默认表单 | `form-publish-chain` | executable | partial | field → onlinejs |
+| `listview` | 列表视图 | `W1-list-view` | partial | partial | field → - |
+| `datarule` | 字段级控件规则 | `G1-datarule` | partial | partial | field → - |
+| `businessrule` | 业务规则（图形引擎） | `B1-businessrule` | executable | partial | field → rule-lifecycle |
+| `rule-lifecycle` | 规则生命周期 | `S25-rule-lifecycle` | executable | none | businessrule → - |
+| `workflow` | 流程模板 | `W7-S29-greenfield` | executable | partial | model → - |
+| `onlinejs` | 表单在线 JS | `online-js` | executable | partial | form → - |
+| `bizservice` | 业务集成 | `B2-registration` | executable | partial | - → - |
+| `data` | 运行数据 | `M2-runtime-data` | executable | none | field → - |
+
+- **覆盖**：`executable` 全量可用；`partial` 有取证边界（见 `omc capability <id>` 的 notes）。
+- **intent**：`partial` 表示该能力可声明式（`omc intent`）覆盖一部分——通常 create/update；
+  `none` 表示只走 `omc call`。删除类、方法面、分类/连接池等仍走 `omc call` 逃生舱。
+
+## 写工具做什么
+
+写工具分三层用法，**全部走同一条受治理管道**。
+
+### 1. 高层编排（4 个，一次调用 = 一个变更包）
+
+| 工具 | 作用 |
+|---|---|
+| `configure_model` | 建模型 → 建 1..N 个字段 → 模型级 `field.publish`，`publishForm:true` 时再 `form.draft` + `form.publish`，一步到达**结构可用形态**。字段族门逐字段在写入前拒绝。 |
+| `configure_form` | 给模型配默认表单：`fieldCodes` 决定绑定哪些已发布字段（按序；省略=全量；未知 code 在建表前拒绝 `form-fieldcodes-unknown`），再发布。 |
+| `configure_rule` | 保存并启用一条业务规则（graph 规则引擎）——委托 `rule.save` 的 upsert + `rule.enable`。 |
+| `apply_changes` | **批量入口**：一次提交异构变更清单 `changes:[{tool,args}]`（只收低层原子写工具），按序执行、逐步权威读回、**首败即停**并报已完成步骤与失败点；每步传输超时按 `uncertain` 冻结。含**整批时间预算** `totalTimeoutMs`（缺省 8 分钟）：超预算即停并返回 `uncertain` + `progressFile` + `resumeFromIndex`，绝不盲重试。 |
+
+### 2. 低层原子写（52 个，按域）
+
+| 域（lane） | 工具 |
+|---|---|
+| 模型 `model-management` | `model.create`、`model.update`（应用树节点改名补丁：bizSchemaCode/id/name/parentId 四键必需，modelType 恒拒——类型创建时固化）、`model.setSummary`（数据标题/摘要模板）、`model.delete`、`model.deleteMany`（一次 `physically_delete` 请求批量删；逐目标引用预检、被引用整批拒绝零副作用、逐模型缺席轮询；跨应用自动解析 AppFunction id） |
+| 字段 `field-families` | `field.create`、`field.update`、`field.delete`、`field.publish`（模型级一次发布；发布后逐字段读 `bizproperty/get` 比对 name/propertyType，与草稿面不一致即拒绝——不只查发布列表存在性） |
+| 表单 `form-publish-chain` | `form.draft`、`form.publish` |
+| 字段级规则 `G1-datarule` | `datarule.create`、`datarule.update`、`datarule.delete` |
+| 业务规则图 `B1-businessrule` / `S25-rule-lifecycle` | `rule.save`、`rule.enable`、`rule.disable`、`rule.delete` |
+| 运行时数据 `M2-runtime-data` | `data.save`、`data.update`、`data.submit`、`data.delete` |
+| 流程 `W7-S29-greenfield` | `workflow.create`、`workflow.update`、`workflow.publish`、`workflow.bindRule`（支持 `ruleCodes[]` 一次绑多规则，MERGE 语义）、`workflow.delete` |
+| 在线脚本 `online-js` | `onlinejs.compose`（唯一工具；平台模板保真，SHA-256 读回）。后端的「在线开发」（`/api/api/programming` Java 源码）用二开扩展包，不在本 CLI 范围 |
+| 列表视图 `W1-list-view` | `listview.create`、`listview.configure`、`listview.delete`（列/排序/筛选字段引用可给 **propertyCode 或字段显示名**，唯一匹配自动解析，歧义或不存在则拒绝，不静默跳过） |
+| 应用 `app-management` | `app.create`、`app.update`、`app.delete` |
+| 数据字典 `dictionary-management` | `dictionary.save`（字典/记录 upsert，KEY_VALUE/TREE）、`dictionary.status`（启停字典或记录）、`dictionary.usage`（批量 `initialUsed`）、`dictionary.class.save`、`dictionary.class.delete` |
+| 后端服务注册 `B2-registration` | `service.register`、`service.update`、`service.delete`、`method.update`、`method.delete`、`method.test`、`service.import`、`service.category.create`、`service.category.update`、`service.category.delete`、`service.dbconnpool.create`、`service.dbconnpool.update`、`service.dbconnpool.delete` |
+
+### 3. 每个写调用都经过的治理管道
+
+```
+语义门（字段族 / 规则图 dry-lint / 业务编码 / 表单布局 / 各工具 preflight，零 wire 调用）
+  → 覆盖门（清单声明；超界拒绝并引用条目）
+  → 环境写入门（writable=false 拒绝；生产需 confirmProduction:true）
+  → 会话 + 版本族门（缺版本证据即关闭）
+  → dry-run / requestId 重放门
+  → 写租约（同环境串行）
+  → 执行 → 权威读回 → 交付工件（artifact）+ 中文人话 summary
+```
+
+> 人门在对话层，不在这条管道里：agent 必须先出草稿并取得用户明确批准，才发起
+> 下列任何写入。机器管道只执行 writable 与生产 confirmProduction 检查。
+
+- **计划与结果同源**：计划卡显示「即将…」，回执显示「已…」，由 `human-summary.ts`
+  同一来源按真实参数生成；空转写报「无变更：原因」，不假装有变更。
+- **完整性字段不被摘要替代**：`performed` / `readback` / `deliveryState` /
+  `artifactFingerprint` 始终在内，`summary` 是**并列新增**。
+- **失败即停**：批量在失败步停止，返回 `{status, steps(已完成), failedStep, blocker}`；
+  已完成步骤的效果真实存在，需善后时按 `steps` 清单处理。
+
+## 声明式意图面（omc intent）
+
+除 `omc call` 的一次一工具外，可用宣言式 YAML 描述一组变更，编译为**不可变 plan** 后再执行：
+
+```bash
+omc intent validate intent.yaml         # 离线语义校验（错误带 源行:列）
+omc intent plan intent.yaml --env <env> # 读基线 → 编译 → plan（planHash 复核对象）
+omc intent apply plan.json              # 基线 drift 门 + writable 检查 + 串行执行 + 默认读回等价确认
+omc intent readback intent.yaml --env <env>  # 解码回 intent 形状做等价校验
+```
+
+- 顶层 `models[]` / `services[]`；各能力声明式覆盖程度见「能力总览」的 intent 列（`partial` = 覆盖 create/update 等一部分）。
+- **plan 不可变**：apply 前 plan 被改一字节即拒（`intent-plan-tampered`），plan 后环境漂移即拒（`intent-baseline-drifted`，重跑 `intent plan`）。
+- 生产环境 apply 加 `--confirm-production`；`--dry-run` 预览，`--no-verify` 跳过最终读回等价确认。
+- 未声明式覆盖的操作（删除类、方法面、分类/连接池等）仍走 `omc call` 逃生舱。
+
+## 其它命令
+
+| 命令 | 作用 |
+|---|---|
+| `omc artifact get <id>` | 取回大读回的 `detailFile` 工件（0600，校验 sha256） |
+| `omc setup [--list\|--edit <env>\|--remove <env>]` | 命名环境的增删改查 |
+| `omc doctor [--environment <env>]` | 只报告的健康链 |
+| `omc bench [--live-sample] [--env <env>]` | 工具面/wire 面的双面埋点跑分（离线 fake 或 live 采样） |
+| `npm run eval:discovery-cost --workspace omc-cli` | 三组离线 discovery 成本基线（调用次数、stdout 字节、拒绝/重试、CloudPivot 写入） |
+
+## 覆盖边界
+
+- 随包 `coverage/m1-coverage-manifest-v1.json` 是能力契约；工具面受其约束，超界调用
+  拒绝并引用条目。
+- **永久不支持**：应用发布 / 环境级发布、CloudPivot 在线后端内联编码、
+  OCR/电子签字段族。
+- 后端逻辑来自二开扩展包，经受治理发布后经 `BizMethodMapping` 服务注册表消费。
+
+## 目录结构
+
+```
+coverage/   m1-coverage-manifest-v1.json（能力基线）
+skills/     12 篇方法论 topic —— 以 `omc help <topic>` 暴露（见「方法论 topics」）
+docs/       tool-surface-map.md —— 工具面地图
+src/        args/support/plan/read/write/package/context（治理管道）
+            lanes/（各域适配器）· fake/（离线夹具）
+```
+
+依赖 [`omc-core`](../omc-core)（能力契约、治理原语、wire 解码器——零 DSH 依赖，
+由 CI 强制）。
+
+## 在什么目录运行
+
+把本 CLI 当**工具**用，请在**独立、干净的项目目录**里运行，而不要放在 OMC 的
+研发仓库里。工具描述是自包含的（字段族、关联 `options`、规则 `nodeGraph`、
+工作流 `template`、`formData` 与写入治理都已在工具 schema 与描述里声明），
+因此只看到工具的 agent 不需要去读仓库文件。
+
+如果 agent 在 OMC 研发仓里启动，它可能读到只属于研发的产物——`.scratch/` 历史、
+`CONTEXT.md`、既有的业务域 spec 与驱动脚本——并误当成使用指引。请优先选择一个只包含本包与目标项目的目录。
+
+## 方法论 topics
+
+`skills/` 随包分发，用 `omc help <topic>` 读取（等价 `git help <concept>`）。
+首触路线与"任务→topic"映射见 `omc help omc-start-here`。
+
+| topic | 用途 |
+|---|---|
+| `omc-start-here` | 首触命令阶梯 + 任务→topic 路线（router） |
+| `omc-capabilities` | **能力总表**：每个能力能做哪些事、工具、recipe、边界（"能不能做 X"先读它） |
+| `omc-config-draft-review` | 写前草稿确认：对话人门协议（**任何写前必读**） |
+| `omc-five-piece-flow` | 治理变更五阶段：发现→草稿→权限→执行→读回清理 |
+| `omc-tool-selection` | 目标 → 工具：何时用高层编排、何时落到原子 |
+| `omc-refusals` | 拒绝/不确定族的含义与下一步（按族，不逐码） |
+| `omc-write-hazards` | 底层写面安全形状（表单/视图/按钮/子表/关联/规则/在线 JS） |
+| `omc-business-configuration` | 中文业务配置 runbook（需求维度 → 落地） |
+| `omc-requirement-analysis` | 模糊中文需求 → 平台无关的 Configuration Intent |
+| `omc-requirement-vocabulary` | 中文线索词 → 能力 lookup |
+| `omc-capability-scouting` | 覆盖清单之外的新能力如何诚实取证 |
+| `omc-acceptance-criteria` | 验收门：读回、交付态、零残留、反例基线 |
+| `omc-glossary` | 术语：环境指纹、覆盖清单、交付态、Void envelope、结果状态 |
+
+## npm 分发
+
+本包（`@stalfh233/omc-cli`，可执行命令仍是 `omc`）通过公共 npm registry 分发。`omc-core` 是 `omc-cli` 的内部依赖，发布时先发 `omc-core`，再发 `omc-cli`；两者版本保持一致。当前版本为 `0.4.10`，尚未宣称 `1.0.0` 稳定契约。
+
+### 使用已发布包
+
+```bash
+npm install -g @stalfh233/omc-cli@0.4.10
+omc setup
+omc doctor
+omc help omc-write-hazards
+omc help omc-business-configuration
+```
+
+### 发布新版本
+
+发布在开发机执行，必须先 `omc-core` 后 `omc-cli`，顺序不能反：
+
+```bash
+npm run verify
+npm publish --workspace packages/omc-core
+npm publish --workspace packages/omc-cli
+```
+
+`omc-core` 与 `omc-cli` 版本保持一致；发布前先用 `git tag vX.Y.Z` 记录该版本。新包首次发布进入 npm staged-publishing 审核队列，需维护者在 npmjs.com 用交互式 2FA 批准后真实版本才可见。
+
+### 版本策略
+
+- `0.2.x`：继续演进 CLI/覆盖清单/配置契约，允许新增能力和必要的行为修复。
+- `1.0.0`：等 CLI 面、intent 面、覆盖清单和分发安装流程稳定后再发布；发布前应增加迁移说明和兼容性检查。
+
+### 分发后自检
+
+新会话不需要依赖本仓库的 `AGENTS.md`。安装包内置 `skills/`，可通过以下命令发现和读取方法论：
+
+```bash
+omc commands --json
+omc help
+omc help omc-start-here
+omc help omc-write-hazards
+omc help omc-business-configuration
+omc help omc-refusals
+omc describe <tool>
+omc contract <lane>
+```
+
+CLI 自己执行 dry-lint、覆盖清单、writable/production confirmation、写租约和权威读回；浏览器不是常规验收步骤。