@stalfh233/omc-cli 0.4.41 → 0.4.42

package/dist/rollback.js

@@ -0,0 +1,178 @@
+import { existsSync, readFileSync } from "node:fs";
+import { basename } from "node:path";
+import { ConfigStore, defaultPaths } from "./config-store.js";
+import { SessionManager } from "./session-manager.js";
+import { makeToolContext, buildToolRegistry } from "./tools.js";
+import { runToolCall } from "./call.js";
+import { readJournal, resolveJournalEntry, laterWritesOnTarget } from "./journal.js";
+import { canonicalForVerify, deepDiff } from "./rollback-spec.js";
+import { sha256 } from "./support.js";
+import { emitTransportResult } from "./command-transport.js";
+/** Pure runtime assembly: an injected context (tests) or the default one. */
+function runtime(context) {
+    return context ?? makeToolContext({ sessions: new SessionManager(new ConfigStore(defaultPaths())) });
+}
+function resolvedEnvironment(environment) {
+    return new ConfigStore(defaultPaths()).resolveEnvironment(environment).name;
+}
+function loadArtifact(entry) {
+    if (!existsSync(entry.artifactFile))
+        throw new Error(`journal 指向的 artifact 不存在：${basename(entry.artifactFile)}（本机边界：journal 与快照不跨机器迁移）`);
+    return JSON.parse(readFileSync(entry.artifactFile, "utf8"));
+}
+function findSpec(toolName) {
+    const tool = buildToolRegistry().find((definition) => definition.name === toolName);
+    if (!tool)
+        throw new Error(`journal 记录的工具 ${toolName} 已不在当前注册表中`);
+    if (!tool.rollback)
+        throw new Error(`工具 ${toolName} 未声明回滚能力（旧 journal 记录）`);
+    return { tool: tool.name, spec: tool.rollback };
+}
+export async function listRollback(options, context) {
+    const ctx = runtime(context);
+    const environment = resolvedEnvironment(options.environment);
+    let entries = readJournal(environment, ctx.artifactsDir);
+    if (options.target)
+        entries = entries.filter((entry) => entry.target.includes(options.target));
+    if (options.tool)
+        entries = entries.filter((entry) => entry.tool === options.tool || entry.tool.startsWith(`${options.tool}.`));
+    const limit = options.limit ? Number(options.limit) : 40;
+    const timeline = [...entries].reverse().slice(0, Number.isSafeInteger(limit) && limit > 0 ? limit : 40);
+    return {
+        status: "ok",
+        environment,
+        journalFile: `.omc/journal/${environment}.ndjson（随本项目 artifacts 目录，本机边界：不跨机器）`,
+        entries: timeline.length,
+        writes: timeline.map((entry) => ({
+            seq: entry.seq,
+            ts: entry.ts,
+            tool: entry.tool,
+            target: entry.target,
+            rollbackable: entry.rollbackable,
+            ...(entry.note ? { note: entry.note } : {}),
+            artifact: basename(entry.artifactFile),
+        })),
+        hint: "omc rollback plan <seq> 预览恢复（不写）；omc rollback apply <seq> 执行恢复",
+    };
+}
+async function buildPlan(ref, environmentOption, context) {
+    const ctx = runtime(context);
+    const environment = resolvedEnvironment(environmentOption);
+    const entry = resolveJournalEntry(environment, ref, ctx.artifactsDir);
+    if (!entry)
+        throw new Error(`journal（${environment}）中找不到 ${ref}：先 omc rollback list 核对 seq`);
+    const unrollbackable = (reason) => ({
+        entry,
+        spec: findSpec(entry.tool).spec,
+        before: undefined,
+        artifactArgs: {},
+        context: ctx,
+        plan: { environmentMatch: true, diff: { changes: [], total: 0 }, laterWrites: [], inverse: { kind: "irreversible", reason } },
+    });
+    if (!entry.rollbackable)
+        return unrollbackable(entry.note ?? "该写的 before 快照捕获失败，无法回滚");
+    const artifact = loadArtifact(entry);
+    const { spec } = findSpec(entry.tool);
+    const artifactArgs = (artifact.args ?? {});
+    const before = artifact.before ?? null;
+    // Environment fingerprint gate: the restore replays real writes, so the
+    // environment must be the SAME one the journal line was recorded against.
+    const session = await ctx.sessions.session(environment);
+    const currentFingerprint = session.environmentFingerprint();
+    if (currentFingerprint !== entry.environmentFingerprint)
+        throw new Error(`环境指纹已变化（记录 ${entry.environmentFingerprint.slice(0, 8)}… 当前 ${currentFingerprint.slice(0, 8)}…）：底层环境不是写入时的环境，拒绝回滚；请人工核对`);
+    const current = await spec.read(session, artifactArgs);
+    const laterWrites = laterWritesOnTarget(environment, ctx.artifactsDir, entry.seq, entry.target);
+    return {
+        entry,
+        spec,
+        before,
+        artifactArgs,
+        context: ctx,
+        plan: {
+            environmentMatch: true,
+            currentFingerprint,
+            diff: deepDiff(before, current),
+            laterWrites,
+            inverse: spec.inverse({ before, args: artifactArgs, readback: (artifact.readback ?? {}) }),
+        },
+    };
+}
+export async function planRollback(ref, options, context) {
+    const loaded = await buildPlan(ref, options.environment, context);
+    const { entry, plan } = loaded;
+    return {
+        status: "ok",
+        rollbackOf: { seq: entry.seq, tool: entry.tool, target: entry.target, ts: entry.ts },
+        diff: { changedPaths: plan.diff.changes, total: plan.diff.total },
+        ...(plan.laterWrites.length > 0
+            ? { warning: `该目标在此写之后还有 ${plan.laterWrites.length} 次写（seq ${plan.laterWrites.map((w) => w.seq).join(", ")}）；本次回滚会用 before 参数覆盖这些后续变更`, laterWrites: plan.laterWrites.map((w) => ({ seq: w.seq, tool: w.tool, ts: w.ts })) }
+            : {}),
+        inverse: plan.inverse.kind === "calls"
+            ? {
+                kind: "calls",
+                count: plan.inverse.calls.length,
+                ...(plan.inverse.notes ? { notes: plan.inverse.notes } : {}),
+                script: plan.inverse.calls.map((call) => JSON.stringify({ tool: call.tool, args: { ...call.args, environment: entry.environment } })),
+            }
+            : { kind: "irreversible", reason: plan.inverse.reason, ...(plan.inverse.partial ? { partial: plan.inverse.partial } : {}) },
+        hint: "预览不写入；确认后 omc rollback apply <seq>（恢复走完整写闸门，回滚本身也会记 journal，可再回滚）",
+    };
+}
+export async function applyRollback(ref, options, context) {
+    const loaded = await buildPlan(ref, options.environment, context);
+    const { entry, plan, spec, artifactArgs, before, context: ctx } = loaded;
+    if (plan.inverse.kind !== "calls" || plan.inverse.calls.length === 0)
+        return {
+            status: plan.inverse.kind === "irreversible" ? "irreversible" : "ok",
+            rollbackOf: { seq: entry.seq, tool: entry.tool, target: entry.target },
+            inverse: plan.inverse,
+            message: plan.inverse.kind === "irreversible" ? plan.inverse.reason : "无可执行恢复调用",
+        };
+    const results = [];
+    for (const [index, call] of plan.inverse.calls.entries()) {
+        const { exitCode, result } = await runToolCall(call.tool, {
+            args: { ...call.args, environment: entry.environment, ...(options.confirmProduction ? { confirmProduction: true } : {}) },
+            requestId: `omc-rollback-${entry.seq}-${index + 1}`,
+            context: ctx,
+            print: () => undefined,
+        });
+        results.push({ tool: call.tool, exitCode, status: result.status, ...(result.deliveryState ? { deliveryState: result.deliveryState } : {}), ...(result.summary ? { summary: result.summary } : {}) });
+        if (exitCode !== 0)
+            return { status: "stopped", rollbackOf: { seq: entry.seq, tool: entry.tool }, step: index + 1, results, message: `恢复调用 ${call.tool} 未成功（status=${result.status}）；已执行的调用已各自记 journal，可对已完成步骤再 plan` };
+    }
+    // Authoritative verify: re-read the target and compare against the
+    // canonicalized before. "restored" tolerates the write pipeline
+    // EXPLICITIFYING platform defaults the bare auto-draft left absent
+    // (sheetCode backfill, designer-default permittedAction, canonical key
+    // order) — any CHANGED or DROPPED value is a mismatch.
+    const session = await ctx.sessions.session(entry.environment);
+    const restored = await spec.read(session, artifactArgs);
+    const beforeSha = before === null ? null : sha256(canonicalForVerify(before));
+    const restoredSha = restored === null ? null : sha256(canonicalForVerify(restored));
+    let verify;
+    if (beforeSha === restoredSha)
+        verify = "restored";
+    else {
+        const residual = deepDiff(canonicalForVerify(before), canonicalForVerify(restored));
+        verify = residual.changes.every((change) => change.before === "<absent>") ? "restored" : "mismatch";
+    }
+    return {
+        status: "ok",
+        rollbackOf: { seq: entry.seq, tool: entry.tool, target: entry.target },
+        calls: results,
+        verify,
+        ...(verify === "mismatch" ? { beforeSha, restoredSha, message: "恢复调用已完成但读回与 before 存在值冲突（非默认显式化）：立即人工核对目标现态（omc rollback plan <seq> 的 diff 可复看差异）" } : {}),
+        hint: "本次恢复的每次调用都走了完整写闸门并已记 journal；恢复本身可再回滚（rollback plan <新 seq>）",
+    };
+}
+export async function cmdRollbackList(options, transport) {
+    return emitTransportResult(await listRollback(options), transport);
+}
+export async function cmdRollbackPlan(ref, options, transport) {
+    return emitTransportResult(await planRollback(ref, options), transport);
+}
+export async function cmdRollbackApply(ref, options, transport) {
+    return emitTransportResult(await applyRollback(ref, options), transport);
+}
+//# sourceMappingURL=rollback.js.map

package/dist/write.js

@@ -16,6 +16,7 @@ import { isPackageStopOutcome } from "./package.js";
 import { writeSummary } from "./human-summary.js";
 import { planFor } from "./plan.js";
 import { isUncertainWireError, sha256, wireErrorKind, writeArtifact } from "./support.js";
+import { appendJournalEntry } from "./journal.js";
 import { capabilityArg, confirmProductionArg, environmentArg, WRITE_PROTOCOL } from "./args.js";
 import { plannableArgsRaw } from "./plan.js";
 import { defineTool, ToolRefusalError } from "./tool-types.js";
@@ -54,6 +55,21 @@ async function governedWrite(ctx, tool, args, execute, dryRunPayload) {
         return outcome.result;
     const { session, plan, productionConfirmed } = 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
+        // in the artifact. A failed pre-read must never block the wanted write —
+        // the journal line then records rollbackable:false with the reason.
+        let rollbackBefore = undefined;
+        let rollbackCaptureError;
+        if (tool.rollback) {
+            try {
+                rollbackBefore = await tool.rollback.read(session, args);
+            }
+            catch (error) {
+                rollbackBefore = undefined;
+                rollbackCaptureError = error instanceof Error ? error.message : String(error);
+            }
+        }
         let executed;
         try {
             executed = await execute(session);
@@ -106,11 +122,41 @@ async function governedWrite(ctx, tool, args, execute, dryRunPayload) {
             readback,
             ...(steps !== undefined ? { steps } : {}),
             ...(productionConfirmed ? { productionConfirmed: true } : {}),
+            ...(tool.rollback
+                ? {
+                    rollback: {
+                        target: tool.rollback.target(args),
+                        beforeSha: rollbackBefore === null ? null : rollbackBefore === undefined ? null : sha256(rollbackBefore),
+                        ...(rollbackCaptureError ? { captureError: rollbackCaptureError } : {}),
+                    },
+                    args: plannableArgsRaw(args),
+                    ...(rollbackBefore !== undefined ? { before: rollbackBefore } : {}),
+                }
+                : {}),
             deliveryState: "DELIVERED",
             recordedAt: new Date().toISOString(),
         };
         const artifactRef = writeArtifact(ctx, `${tool.name}-${randomUUID().slice(0, 8)}.json`, artifact);
-        return { status: "ok", deliveryState: "DELIVERED", performed, readback, ...(steps !== undefined ? { steps } : {}), ...(args.requestId ? { requestId: args.requestId, idempotency: idempotencyDeclaration(tool.name) } : {}), ...(productionConfirmed ? { productionConfirmed: true } : {}), summary: writeSummary(tool.name, args, { performed, readback }, "done"), detailFile: artifactRef.detailFile, detailSha256: artifactRef.detailSha256, artifactFingerprint: artifactRef.detailSha256 };
+        // Journal AFTER the artifact is durable: one append-only line per
+        // delivered governed config write, feeding `omc rollback list/plan/apply`.
+        let rollbackRef;
+        if (tool.rollback) {
+            const entry = appendJournalEntry(ctx.artifactsDir, {
+                v: 1,
+                environment: session.environmentName,
+                environmentFingerprint: session.environmentFingerprint(),
+                tool: tool.name,
+                target: tool.rollback.target(args),
+                beforeSha: artifact.rollback.beforeSha,
+                rollbackable: rollbackBefore !== undefined && !rollbackCaptureError,
+                ...(rollbackCaptureError ? { note: `before-capture failed: ${rollbackCaptureError}` } : {}),
+                artifactFile: artifactRef.detailFile,
+                artifactId: artifactRef.detailFile.split("/").pop()?.replace(/\.json$/, "") ?? "",
+                artifactSha: artifactRef.detailSha256,
+            });
+            rollbackRef = { seq: entry.seq, hint: `omc rollback plan ${entry.seq}（--env ${entry.environment}）` };
+        }
+        return { status: "ok", deliveryState: "DELIVERED", performed, readback, ...(steps !== undefined ? { steps } : {}), ...(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 };
     });
 }
 function idempotencyDeclaration(tool) {
@@ -138,7 +184,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) {
+export function writeTool(tools, name, lane, scope, description, inputSchema, execute, preflight, dryRunPayload, rollback) {
     const rawExecute = execute;
     const semanticGate = (args) => {
         if (name === "field.create")
@@ -193,6 +239,7 @@ export function writeTool(tools, name, lane, scope, description, inputSchema, ex
         // step can never bypass its lane's readback or semantic refusal.
         writeExecute: rawExecute,
         writePreflight: semanticGate,
+        ...(rollback ? { rollback } : {}),
     });
 }
 //# sourceMappingURL=write.js.map

package/package.json

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

package/skills/omc-business-configuration.md

@@ -153,10 +153,12 @@ rules:
 - 审批节点：通常 `visible:true, editable:false, required:false`。
 - 不需要展示的字段明确 `visible:false`。
 
-**怎么配**（没有单独的权限工具，别把「找不到入口」当不支持→假阻塞）：`workflow.get_draft --full` 读节点正文，改目标
-`ParticipantActivity.propertyPermissions[]`（`{propertyCode, visible, editable, required, subPropertyPermissions}`——`summary` 无需配，工具自动补 `true`），
-用 `workflow.update` 原样回写，再 `workflow.publish`。（`summary:true` 才进运行时 `activitySummaries`，工具已自动处理；
+**怎么配**（没有单独的权限工具，别把「找不到入口」当不支持→假阻塞）：**增量即可**——`workflow.update` 直接发
+`activities:[{activityCode, propertyPermissions:[{propertyCode, visible, editable, required, subPropertyPermissions}]}]`
+（**type 可省**：activityCode 命中草稿节点时类型/名称继承草稿、code 稳定不铸 `_2`；不必先读 `get_draft --full` 整回写。
+`summary` 无需配，工具自动补 `true`），改完 `workflow.publish`。（`summary:true` 才进运行时 `activitySummaries`，工具已自动处理；
 否则 `form/load` 的 `formPermission.dataPermissions` 回退默认，读不到你的 `editable:false`）；子表列用 `subPropertyPermissions`。
+**子表属性本身不可设 `required:true`**（接口接受但设计器节点字段配置不支持——工具拒 `workflow-child-table-not-required`）：子表整行只配 visible/editable，字段级必填配到子表内部字段。**新增节点用语义 code**（如 `approval_finance`），不要给 `ActivityN` 加 `_1/_2` 后缀；改名才会铸新码（平台不能原地改名）。**子表操作按钮与驳回默认已由工具自动补齐**：填写节点自动配 `buttonPermission.childTableBtns`（每子表 新增/删除/导入/导出 启用、批量编辑禁用），`permittedAction` 按设计器默认归一（填写人不可驳回自己 `showReject:false`；审批节点驳回回发起 `rejectToStart:true`）——显式传 `permittedAction`/`buttonPermission` 可覆盖。
 验收用 `npm run test:live-permission` + **非管理员参与者**（管理员会被后端强制 `e:true` 掩盖）。
 
 声明式流程（intent）的 `workflow.template` 用 **`activities` + `routes`**（不是 `nodes`/`edges`）：活动 `{id, type: START|END|PARTICIPANT|…, participant?}`，路由 `{preNode, postNode}` 必须指向已声明活动 code；`workflow.update` 只从 `activities` 读节点，写 `nodes` 会在 apply 时 `rules[0] references an unknown activity`（validate 会提前拦）。
@@ -238,7 +240,7 @@ BIZ_ACTION：
 - 直接执行规则：`useLocation: ROW` + `operateType: WITH_OUT_VIEW`。
 - `WITH_VIEW` 是打开表单。
 - FLOW 按钮需要 workflowCode；CLI 会补安全的 actionConfig。
-- **在线 JS 分两条**：本 CLI 只做**发布与回读**——用 `onlinejs.compose` 把已定稿的 `source` 组合进平台 skeleton 的 `customScript` 再 publish，回读 `publishedHtmlJson`+SHA-256。**脚本内容的编写/增量合并不在本 CLI**：若当前项目自带在线 JS 编写规范（例如其 `.cpdocs`/技能或项目文档），遵循它；否则向用户/设计者索取已定稿的 `source`。不要在 omc 侧手写或臆造 JS 逻辑。
+- **在线 JS 分两条**：本 CLI 只做**读写与发布**——**读现存脚本用 `onlinejs.get`**（抽 customScript innerHTML 原文+SHA-256，不必拉 form.get --full 六份 JSON；据此决定 replace 还是默认 INCREMENTAL 并入），用 `onlinejs.compose` 把已定稿的 `source` 组合进平台 skeleton 的 `customScript` 再 publish，回读 `publishedHtmlJson`+SHA-256。**脚本内容的编写/增量合并不在本 CLI**：若当前项目自带在线 JS 编写规范（例如其 `.cpdocs`/技能或项目文档），遵循它；否则向用户/设计者索取已定稿的 `source`。不要在 omc 侧手写或臆造 JS 逻辑。
 
 ## 运行验收与清理
 

package/skills/omc-capabilities.md

@@ -144,9 +144,9 @@ only the section for the capability you need —
 
 ## 表单在线 JS `onlinejs`
 
-- **能做哪些事**：表单在线 JS 的 compose 六元素骨架、`draftHtmlJson.customScript`、发布与 SHA-256 回读（脚本**编写**不在 CLI 范围，遵循项目在线 JS 规范或向用户索取定稿 source）。
-- **工具**：`onlinejs.compose`
-- **边界 / 陷阱**：仅表单在线 JS；后端在线开发（`/api/api/programming` Java 源码）用二开扩展包，不在 CLI 范围。
+- **能做哪些事**：表单在线 JS 的 compose 六元素骨架、`draftHtmlJson.customScript`、发布与 SHA-256 回读；**读现存脚本**（`onlinejs.get` 抽 customScript innerHTML 原文+SHA-256，不必拉 form.get --full 六份 JSON）（脚本**编写**不在 CLI 范围，遵循项目在线 JS 规范或向用户索取定稿 source）。
+- **工具**：`onlinejs.get`、`onlinejs.compose`
+- **边界 / 陷阱**：仅表单在线 JS；后端在线开发（`/api/api/programming` Java 源码）用二开扩展包，不在 CLI 范围。INCREMENTAL 合并对同内容重发幂等；同头注释的整文件修订会被拒（`onlinejs-revision-replace-required`），走 `onlinejs.get` 取回 → 改 → `replace:true`。
 
 ## 业务集成 `bizservice`
 

package/skills/omc-write-hazards.md

@@ -30,6 +30,7 @@ omc help omc-write-hazards
 - 有映射时传非空 JSON 数组字符串，并在 draft/published 两面读回。
 - **运行时写关联值是另一种形状**（`data.save`/`data.update` 的 formData）：单选关联（`propertyType 9`）传 **id 字符串或 `{ id }`**，传**数组会稳定 50000**；多选关联（11）才用数组；**人员/组织（50/51/60/61）传 `[{"id","type","name"}]`，`type` 必填**（缺它稳定 50000）——`type` 是 UnitType 索引：**用户=3、部门=1**。用错形状只会拿到一个不透明的 50000。
 - **`mappings` 由表单运行时在用户选择时套用**，服务端 `data.save` **不会**自动回填映射目标字段。API 侧要自己写被映射字段，否则读回为空——别把它误判成“映射配置失败”。
+- **关联映射的事实源在字段行 `options.mappings`，不在表单控件属性**（真机 2026-10-14 实证：改表单 attributes 里的映射会被平台按字段重算覆盖、回读不生效）。改映射走：`field.update` 按完整 options 提交（只改 mappings，其余键原值保留）→ `field.publish` → `form.draft`（**rebuild:false**，保留现有布局与在线JS）重存 → `form.publish` → 回读核对。**别用 field.update 的 cascadeRepublish 刷已带自定义布局/在线JS 的表单**（它会 rebuild 脚手架）。
 - **运行时写值的最小形状**（组合出错只会得到一个不透明的 `50000`/NPE，逐一最小化再合）：单选关联(9) → id 字符串 `"<id>"`；**人员/组织(50/51/60/61) → `[{"id":"<id>","type":3,"name":"<名>"}]`，`type` 必填且为整数**（缺/非整数 → `BizField.parseFromClient` 拆箱 NPE→50000；用户=3、部门=1）；日期(3) → 字符串 `"2026-09-30 10:00:00"`；子表(8) → 行对象数组 `[{"<子列code>":<值>, ...}]`。先各写一条最小行通过，再组合。
 - **DATE(3) 字段的 `options.format` 必须是平台大写枚举**（`YYYY-MM-DD`、`YYYY-MM-DD HH:mm:ss`、`YYYY年MM月DD日`…），**不是 Java 的 `yyyy-MM-dd`**：平台 `DateBizField` 按字面比较，Java 写法能创建字段但**首次运行时 save 稳定 `50000`（`不支持的format`）**（2026-09-30 R5 实测）。`field.create`/`intent` 会就地拒绝非枚举值。