@stalfh233/omc-cli 0.6.3 → 0.6.5

package/dist/support.js

@@ -118,6 +118,18 @@ export function applicationScopeHint(scope, noun) {
     }
     return `本次只扫描了应用 ${scope.code}（source=${scope.source}）——零命中只代表该应用没有${noun}；跨应用请先 app.list 取 applicationCode。`;
 }
+/**
+ * T4（GitLab #17）：同一条作用域事实，但**非零结果也返回**。调用方看到
+ * 「只有 3 个模型」时无从判断是租户就这么少、还是被应用边界裁掉了；
+ * model.list 之前只在零命中时才说作用域，于是这个裁剪完全不可见。
+ */
+export function applicationScopeNotice(scope) {
+    const count = scope.applicationCount ?? 1;
+    const where = scope.source === "first-tenant-application" && count > 1
+        ? `租户首个应用「${scope.code}」（租户共 ${count} 个应用）`
+        : `应用「${scope.code}」`;
+    return `本次只在${where}内扫描（source=${scope.source}）——结果被应用边界裁剪，不代表租户全集；跨应用先 app.list 取 applicationCode 再传 applicationCode。`;
+}
 export function flattenTreeRows(rows) {
     const flat = [];
     const visit = (row) => {

package/dist/tool-types.js

@@ -50,6 +50,23 @@ const KEY_SYNONYMS = Object.freeze({
     code: ["schemaCode", "sheetCode", "workflowCode"],
     ruleCode: ["code"],
 });
+/**
+ * r25 沙盒实证（2026-11-04）：探针给 `configure_form` 传了 `publish:true`，
+ * 得到「未知键 publish。最接近的合法键：publish→（无相近键）」——写面 fail-closed
+ * 是对的，但**意图没被接住**：配置与发布本来就是两步，用户真正要的是
+ * `form.publish`。同类还有「配完字段就发布」（`field.publish`）与
+ * 「配完列表视图」（无需发布）。这里按工具给出可执行的两步指引，
+ * 比「无相近键」有用得多；代价是探针少花一轮（21→22 实测）。
+ */
+const TWO_STEP_GUIDANCE = Object.freeze({
+    configure_form: Object.freeze({
+        publish: "表单的配置与发布是两步：本工具只写草稿，发布用 `omc call form.publish --args '{\"schemaCode\":\"<模型>\",\"sheetCode\":\"<槽位>\"}'`（也可在本工具的成功回执后紧接着跑）。",
+        publishNow: "同上：本工具不负责发布，用 `omc call form.publish`。",
+    }),
+    configure_model: Object.freeze({
+        publish: "模型/字段的配置与发布是两步：字段建好后用 `omc call field.publish --args '{\"schemaCode\":\"<模型>\"}'` 发布；模型本身不需要单独发布。",
+    }),
+});
 /**
  * Per-tool input aliases: a synonym the caller may send INSTEAD of the canonical
  * key. Applied in `parseToolInput` BEFORE validation (fill canonical from an
@@ -152,11 +169,17 @@ export function parseToolInput(tool, input) {
         const unknown = Object.keys(normalized).filter((key) => !schemaKeys.has(key));
         if (unknown.length > 0) {
             const suggestions = unknown.map((key) => `${key}→${closestSchemaKey(key, schemaKeys) ?? "（无相近键，omc describe <tool> 看参数表）"}`);
+            // r25 实证：`publish→（无相近键）` 等于没说——配置与发布是两步，用户要的是
+            // 另一个工具。有语义指引时优先给可执行的下一步。
+            const twoStep = unknown
+                .map((key) => TWO_STEP_GUIDANCE[tool.name]?.[key])
+                .filter((hint) => typeof hint === "string" && hint.length > 0);
             throw new ToolInputError({
                 status: "error",
                 blocker: "tool-input-unknown-keys",
                 tool: tool.name,
-                message: `写面工具不接受未知键（会被静默丢弃）：${unknown.join("、")}。最接近的合法键：${suggestions.join("；")}。参数表：omc describe ${tool.name}`,
+                message: `写面工具不接受未知键（会被静默丢弃）：${unknown.join("、")}。${twoStep.length > 0 ? twoStep.join(" ") : `最接近的合法键：${suggestions.join("；")}。参数表：omc describe ${tool.name}`}`,
+                ...(twoStep.length > 0 ? { nextCommand: `omc describe ${tool.name}` } : {}),
                 issues: unknown.map((key) => ({ path: [key], code: "unrecognized_key", message: `unknown key; closest: ${closestSchemaKey(key, schemaKeys) ?? "none"}` })),
             });
         }
@@ -164,12 +187,30 @@ export function parseToolInput(tool, input) {
     const result = z.object(tool.inputSchema).safeParse(normalized);
     if (result.success)
         return result.data;
+    // T3（GitLab #17，2026-11-04）：封闭取值此前只能靠报错试出来（`dir:"desc"`
+    // → zod 原生 "Expected 'ASC' | 'DESC'"，而 filter op 的枚举又只在拒绝文案里）。
+    // 把「这个参数到底收哪些值」直接放进错误信封：zod 的 invalid_enum_value 自带
+    // options；schema 表达不了的（paramEnums 声明的 filter.op）用声明值兜底。
+    const acceptedValues = {};
+    for (const issue of result.error.issues) {
+        const path = issue.path.join(".") || "args";
+        const options = issue.options;
+        if (issue.code === "invalid_enum_value" && Array.isArray(options) && options.length > 0)
+            acceptedValues[path] = options.map((value) => String(value));
+    }
+    for (const [key, values] of Object.entries(tool.paramEnums ?? {})) {
+        if (acceptedValues[key] === undefined)
+            acceptedValues[key] = values.split("|");
+    }
+    const firstPath = result.error.issues[0]?.path.join(".") || undefined;
     throw new ToolInputError({
         status: "error",
         blocker: "tool-input-invalid",
         tool: tool.name,
         message: result.error.issues.map((issue) => `${issue.path.join(".") || "args"}: ${issue.message}${keyRenameHint(issue.path, normalized, tool) ?? ""}`).join("; "),
         issues: result.error.issues.map((issue) => ({ path: issue.path, code: issue.code, message: issue.message, ...(keyRenameHint(issue.path, normalized, tool) ? { hint: keyRenameHint(issue.path, normalized, tool) } : {}) })),
+        ...(Object.keys(acceptedValues).length > 0 ? { acceptedValues } : {}),
+        ...(firstPath !== undefined ? { nextCommand: `omc describe ${tool.name} --param ${firstPath.split(".")[0]}` } : {}),
     });
 }
 //# sourceMappingURL=tool-types.js.map

package/dist/wire.js

@@ -10,13 +10,21 @@ export class WireError extends Error {
     kind;
     errcode;
     diagnostic;
+    hint;
     constructor(kind, message, errcode, 
     /** Round-2 T-06: diagnosable context for malformed/http-status envelopes. */
-    diagnostic) {
+    diagnostic, 
+    /**
+     * P1-4（GitLab #18）：调用方可在抛出前附加一条**不改判定**的排查提示
+     * （例如「同一 schemaCode 去掉 filter 能读 → 是过滤形状问题」）。信封照实
+     * 保留 wire-business/errcode，只多一行可执行线索。
+     */
+    hint) {
         super(message);
         this.kind = kind;
         this.errcode = errcode;
         this.diagnostic = diagnostic;
+        this.hint = hint;
     }
 }
 /** Redact common secret keys and truncate — the malformed-envelope preview must be safe to log. */

package/dist/write.js

@@ -34,7 +34,7 @@ import { WireError } from "./wire.js";
  * → session → version-family gate (fail closed without evidence) → production
  * confirmation → write lease → execute with authoritative readback.
  */
-async function governedWrite(ctx, tool, args, execute, dryRunPayload) {
+async function governedWrite(ctx, tool, args, execute, dryRunPayload, readOnlyEscape) {
     const requestFingerprint = args.requestId ? sha256({ requestId: args.requestId, args: plannableArgsRaw(args) }) : undefined;
     // The shared admission owns the gate sequence; this face only supplies its
     // plan and its dry-run / replay payload shapes.
@@ -43,6 +43,8 @@ async function governedWrite(ctx, tool, args, execute, dryRunPayload) {
         confirmProduction: args.confirmProduction,
         dryRun: args.dryRun,
         capability: args.capability,
+        args,
+        ...(readOnlyEscape !== undefined ? { readOnlyEscape } : {}),
         coverage: { lane: args.capability ?? tool.lane, scope: tool.scope ?? "" },
         plan: (session) => planFor(ctx, args.environment, tool.name, args),
         // A face may supply a session-aware dry-run projection (e.g. model.delete's
@@ -53,7 +55,7 @@ async function governedWrite(ctx, tool, args, execute, dryRunPayload) {
     });
     if (outcome.kind === "settled")
         return outcome.result;
-    const { session, plan, productionConfirmed } = outcome.admission;
+    const { session, plan, productionConfirmed, readOnlyEscape: readOnlyEscapeNote } = outcome.admission;
     return ctx.lease.run(session.environmentName, `${tool.name}:${randomUUID().slice(0, 8)}`, async () => {
         // Rollback before-capture: the pre-write state of the declared target is
         // fetched INSIDE the lease (serialized with the write itself) and stored
@@ -180,7 +182,7 @@ async function governedWrite(ctx, tool, args, execute, dryRunPayload) {
             });
             rollbackRef = { seq: entry.seq, hint: `omc rollback plan ${entry.seq}（--env ${entry.environment}）` };
         }
-        return { status: "ok", deliveryState, performed, readback, ...(readbackWarning ? { readbackWarning } : {}), ...(steps !== undefined ? { steps } : {}), ...(halfSuccess !== undefined ? { halfSuccess } : {}), ...(args.requestId ? { requestId: args.requestId, idempotency: idempotencyDeclaration(tool.name) } : {}), ...(productionConfirmed ? { productionConfirmed: true } : {}), ...(rollbackRef ? { rollback: rollbackRef } : {}), summary: writeSummary(tool.name, args, { performed, readback }, "done"), detailFile: artifactRef.detailFile, detailSha256: artifactRef.detailSha256, artifactFingerprint: artifactRef.detailSha256 };
+        return { status: "ok", deliveryState, ...(readOnlyEscapeNote !== undefined ? { readOnlyEscape: readOnlyEscapeNote } : {}), performed, readback, ...(readbackWarning ? { readbackWarning } : {}), ...(steps !== undefined ? { steps } : {}), ...(halfSuccess !== undefined ? { halfSuccess } : {}), ...(args.requestId ? { requestId: args.requestId, idempotency: idempotencyDeclaration(tool.name) } : {}), ...(productionConfirmed ? { productionConfirmed: true } : {}), ...(rollbackRef ? { rollback: rollbackRef } : {}), summary: writeSummary(tool.name, args, { performed, readback }, "done"), detailFile: artifactRef.detailFile, detailSha256: artifactRef.detailSha256, artifactFingerprint: artifactRef.detailSha256 };
     });
 }
 /**
@@ -223,7 +225,7 @@ function findCompleted(root, requestId, tool, environment, requestFingerprint) {
     return undefined;
 }
 /** Low-level write registration factory: shared by every lane adapter. */
-export function writeTool(tools, name, lane, scope, description, inputSchema, execute, preflight, dryRunPayload, rollback) {
+export function writeTool(tools, name, lane, scope, description, inputSchema, execute, preflight, dryRunPayload, rollback, readOnlyEscape) {
     const rawExecute = execute;
     const semanticGate = (args) => {
         if (name === "field.create")
@@ -280,7 +282,7 @@ export function writeTool(tools, name, lane, scope, description, inputSchema, ex
             inputSchema: { environment: environmentArg, capability: capabilityArg, confirmProduction: confirmProductionArg, requestId: z.string().min(1).optional(), dryRun: z.boolean().optional(), ...inputSchema },
             handler: async (ctx, args, self) => {
                 semanticGate(args);
-                return governedWrite(ctx, self, args, (session) => rawExecute(session, args), dryRunPayload);
+                return governedWrite(ctx, self, args, (session) => rawExecute(session, args), dryRunPayload, readOnlyEscape);
             },
         }),
         // Ticket 46: the batch entry drives the SAME executor/gates, so a batch

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stalfh233/omc-cli",
-  "version": "0.6.3",
+  "version": "0.6.5",
   "description": "CloudPivot 8.6 configuration capability CLI — governed, fail-closed, coverage-manifest bounded.",
   "type": "module",
   "bin": {
@@ -52,9 +52,9 @@
     "access": "public"
   },
   "dependencies": {
-    "@stalfh233/omc-fake-platform": "0.6.3",
+    "@stalfh233/omc-fake-platform": "0.6.5",
     "commander": "14.0.3",
-    "omc-core": "0.6.3",
+    "omc-core": "0.6.5",
     "proper-lockfile": "4.1.2",
     "write-file-atomic": "6.0.0",
     "zod": "^3.23.8",

package/skills/omc-start-here.md

@@ -12,7 +12,7 @@ be treated as a second source. Read this, then follow the topics it names.
 
 ## 最小路径（先读这段就能开始）
 
-0. **调用与检索（跨平台）**：`omc call ... --args '<json>'` 的内联 JSON 在 Windows PowerShell 下因引号转义不可靠——**PS 环境优先 `--args-file <path>`**（把 JSON 写临时文件再引用；解析失败的报错里也有此提示）。读命令输出默认把中文转义为 `\uXXXX`（防乱码）——**对输出做内容检索前先加 `--utf8`（单次明文）或先解 JSON，"grep 搜不到中文"≠"没有配置"**（静默假阴性坑）。stdout 恒为纯 JSON、人读进度在 stderr——脚本解析勿 `2>&1` 合流。
+0. **调用与检索（跨平台）**：`omc call ... --args '<json>'` 的内联 JSON 在 Windows PowerShell 下因引号转义不可靠——**PS 环境优先 `--args-file <path>`**（把 JSON 写临时文件再引用；解析失败的报错里也有此提示）。读命令输出默认把中文转义为 `\uXXXX`（防乱码）——**这是有意为之**：stdout 恒为「恰好一个合法 JSON envelope」，在任何代码页下都能被 `JSON.parse`/`ConvertFrom-Json` 还原（GitLab #17 T2 实证：曾让 `--utf8` 关掉转义，GBK 管道把信封结构解码坏、`ConvertFrom-Json` 中途失败）。`--utf8` 只让**人类诊断文本**（stderr/散文）按 UTF-8 原文输出；要连 stdout 也是中文明文，必须先让管道按 UTF-8 解码（`chcp 65001`）——只设 `OMC_ASCII_STDOUT=0` 是关写出端转义、不改管道解码，在 cp936 管道下会把信封解码坏。对输出做内容检索时**先解 JSON 再检索**（或 `--jq` 取值），"grep 搜不到中文"≠"没有配置"（静默假阴性坑）。stdout 恒为纯 JSON、人读进度在 stderr——脚本解析勿 `2>&1` 合流。
 
 0. **拼装器优先（高频写面一条命令）**：整模型建模（模型+N 字段+子表+发布+表单）`omc model-scaffold`；**存量模型加字段（建→发布→重建表单→列表加列）`omc field-add`**；字段计算 `omc compute`；条件→动作 `omc rule-when`；线性审批流 `omc approval-flow`；表单默认值 `omc form-default`；存量盘点 `data.list all:true`——命中这些形态先看 `--help`，比 recipe 手拼省 10+ 轮。
 0c. **清理一个模型用 `omc model-purge --code <x> [--purge-instances] --apply`**——按依赖倒序（实例 → 模型级联带走流程/视图/字段/表单），**不要手工逐层删**：删部门/字段留下缓存或孤儿，会让后续调用出现「假 40009 / 假孤儿 / 全局待办 50000」这类幽灵故障（r12–r14 三次实测）。若返回 `unremovableInstances`（业务对象已删的停滞实例，平台 `delete_instance` NPE），按返回的 `maintainerAction` 让维护者清 `biz_workflow_instance`；**不要改用 model.delete 硬来**。