@stalfh233/omc-cli 0.0.0-stage → 0.4.0

package/dist/lanes/app.js

@@ -0,0 +1,174 @@
+import { z } from "zod";
+import { ENDPOINTS } from "../endpoints.js";
+import { capabilityArg, environmentArg } from "../args.js";
+import { governedRead } from "../read.js";
+import { writeTool } from "../write.js";
+import { defineTool, ToolRefusalError } from "../tool-types.js";
+import { wireCall, wireRows } from "../wire.js";
+import { APP_LANE_CONTRACT } from "./app-contract.js";
+const APP_LANE = APP_LANE_CONTRACT.lane;
+const APP_TOOLS = APP_LANE_CONTRACT.tools;
+/**
+ * Portal visibility is group membership: the portal renders NAMED groups, and
+ * an app parked in the fallback group (`code === "all"`, case-insensitive) is
+ * not rendered. Expose the derived boolean so a readback can assert it instead
+ * of leaving the caller to infer it from `warning` (dogfood R3).
+ */
+function isFallbackGroup(group) {
+    return String(group?.code ?? "").toLowerCase() === "all";
+}
+export function registerAppLane(tools) {
+    tools.push(defineTool({
+        name: "app.list",
+        layer: "low",
+        kind: "read",
+        lane: APP_LANE,
+        scope: APP_TOOLS["app.list"].scope,
+        description: APP_TOOLS["app.list"].description,
+        inputSchema: { environment: environmentArg, capability: capabilityArg },
+        handler: async (ctx, args, self) => governedRead(ctx, self, args, async (session) => {
+            const applications = wireRows((await wireCall(session, { path: ENDPOINTS.applicationList, query: {} })).data).map((row) => ({
+                code: String(row.appCode ?? row.code),
+                name: row.appName ?? row.name,
+                groupId: row.groupId,
+            }));
+            return { applications };
+        }),
+    }));
+    writeTool(tools, "app.create", APP_LANE, APP_TOOLS["app.create"].scope, APP_TOOLS["app.create"].description, { code: z.string().min(1), name: z.string().min(1), groupId: z.string().optional() }, async (session, args) => {
+        const existing = wireRows((await wireCall(session, { path: ENDPOINTS.applicationList, query: {} })).data).find((row) => (row.appCode ?? row.code) === args.code);
+        if (existing)
+            throw new ToolRefusalError({ status: "refused", blocker: "app-create-duplicate", code: args.code, message: `应用 ${args.code} 已存在；拒绝重复 POST，不能用写后存在证明本次创建` });
+        let groupId = args.groupId;
+        let resolvedFrom = args.groupId ? "explicit" : undefined;
+        let warning;
+        let groups = [];
+        const readGroups = async () => wireRows((await wireCall(session, { path: ENDPOINTS.applicationGroupList, query: {} })).data);
+        if (!groupId) {
+            const configured = session.profile.applicationCode?.trim();
+            const apps = wireRows((await wireCall(session, { path: ENDPOINTS.applicationList, query: {} })).data);
+            const configuredApp = configured ? apps.find((row) => (row.appCode ?? row.code) === configured) : undefined;
+            if (configuredApp && typeof configuredApp.groupId === "string" && configuredApp.groupId) {
+                groupId = configuredApp.groupId;
+                resolvedFrom = "auto-configured-app-group";
+            }
+            else {
+                groups = await readGroups();
+                const withId = groups.filter((row) => typeof row.id === "string" && String(row.id));
+                // Prefer a named non-fallback group. The tenant normally has one (e.g.
+                // code=default); landing in the fallback group `all` makes the app
+                // portal-hidden, which the user cannot see and the create cannot undo
+                // without app.update.
+                const named = withId.find((row) => String(row.code ?? "").toLowerCase() !== "all");
+                const group = named ?? withId[0];
+                if (!group)
+                    throw new ToolRefusalError({
+                        status: "refused",
+                        blocker: "app-create-prerequisite-missing",
+                        preconditions: [{ code: "application-group-required", satisfied: false }],
+                        recovery: [{ code: "application-group-missing", action: "由管理侧创建应用分组后重新 discover_environment" }],
+                        message: "创建应用前置条件不满足：租户没有可用应用分组；零 create wire",
+                    });
+                groupId = String(group.id);
+                resolvedFrom = "auto-first-group";
+                const fallback = String(group.code ?? "").toLowerCase() === "all";
+                warning = fallback ? "resolved-to-fallback-group; portalHidden:true" : "resolved-to-first-group";
+            }
+        }
+        if (groups.length === 0)
+            groups = await readGroups();
+        const selectedGroup = groups.find((row) => String(row.id ?? "") === String(groupId));
+        if (!selectedGroup)
+            throw new ToolRefusalError({
+                status: "refused",
+                blocker: "app-create-prerequisite-missing",
+                groupId,
+                preconditions: [{ code: "application-group-required", satisfied: false, groupId }],
+                recovery: [{ code: "application-group-missing", action: "改用 discover_environment 返回的有效 groupId，或由管理侧修复分组" }],
+                message: `创建应用前置条件不满足：分组 ${String(groupId)} 无法解析；零 create wire`,
+            });
+        const performed = await wireCall(session, {
+            path: ENDPOINTS.applicationCreate,
+            method: "POST",
+            body: {
+                groupId,
+                code: args.code,
+                name: args.name,
+                name_i18n: JSON.stringify({ "zh-CN": args.name }),
+            },
+        });
+        const present = wireRows((await wireCall(session, { path: ENDPOINTS.applicationList, query: {} })).data).some((row) => (row.appCode ?? row.code) === args.code);
+        // Portal visibility is a DERIVED FACT (group membership), reported on
+        // every readback so a caller never has to infer it from `warning` and
+        // never reports `ok` while claiming visibility it did not verify.
+        const portalHidden = isFallbackGroup(selectedGroup);
+        return {
+            performed: { errcode: performed.errcode, groupId, resolvedFrom, selectedGroup: { id: selectedGroup.id, code: selectedGroup.code, name: selectedGroup.name } },
+            readback: {
+                present,
+                selectedGroup: { id: selectedGroup.id, code: selectedGroup.code, name: selectedGroup.name },
+                postconditions: { created: present, published: false, portalVisible: !portalHidden, portalHidden },
+                portalHidden,
+                ...(warning ? { warning } : {}),
+                publishBoundary: { inScope: false, nextAction: "publish-in-designer", reason: "app publish is outside the CLI configuration boundary" },
+                recovery: [{ code: "publish-in-designer", action: "在设计器发布应用并核对其位于具名分组；再做门户可见性验证" }],
+                note: "应用发布属边界外：建成后需人工在设计器发布并核对该分组，否则门户不可见",
+            },
+        };
+    });
+    writeTool(tools, "app.update", APP_LANE, APP_TOOLS["app.update"].scope, APP_TOOLS["app.update"].description, { code: z.string().min(1), groupId: z.string().min(1) }, async (session, args) => {
+        const record = (await wireCall(session, { path: ENDPOINTS.applicationGet, query: { appCode: args.code } })).data;
+        if (!record || (typeof record === "object" && Object.keys(record).length === 0))
+            return { performed: { skipped: "already-absent" }, readback: { absent: true } };
+        const previousGroupId = typeof record.groupId === "string" ? record.groupId : null;
+        const performed = await wireCall(session, {
+            path: ENDPOINTS.applicationUpdate,
+            method: "POST",
+            body: {
+                ...record,
+                groupId: args.groupId,
+                enabled: record.enabled,
+            },
+        });
+        // Two independent reads: apppackage/list rows carry `published` (and the
+        // group), while the whole-record `get` carries `enabled`. Merge them so
+        // the readback can assert portal visibility without a second caller round.
+        const listRow = wireRows((await wireCall(session, { path: ENDPOINTS.applicationList, query: {} })).data).find((row) => (row.appCode ?? row.code) === args.code);
+        const groupRow = wireRows((await wireCall(session, { path: ENDPOINTS.applicationGroupList, query: {} })).data).find((row) => String(row.id ?? "") === String(args.groupId));
+        const after = (await wireCall(session, { path: ENDPOINTS.applicationGet, query: { appCode: args.code } })).data;
+        const portalHiddenByGroup = groupRow === undefined || isFallbackGroup(groupRow);
+        // `groupChanged` must reflect a REAL change: comparing the stored value
+        // against the requested one — an update that lands on the same group is
+        // not a change, and reporting it as one made the flag untrustworthy
+        // (dogfood R3: groupChanged:true while previousGroupId === groupId).
+        const storedGroupId = typeof after?.groupId === "string" ? after.groupId : listRow?.groupId ?? null;
+        const groupChanged = String(storedGroupId ?? "") !== String(previousGroupId ?? "");
+        return {
+            performed: { errcode: performed.errcode, code: args.code, groupId: args.groupId, previousGroupId },
+            readback: {
+                present: listRow !== undefined || after !== null,
+                groupId: storedGroupId,
+                previousGroupId,
+                groupChanged,
+                groupCode: groupRow?.code ?? null,
+                published: listRow?.published === true,
+                portalHidden: portalHiddenByGroup,
+            },
+        };
+    });
+    writeTool(tools, "app.delete", APP_LANE, APP_TOOLS["app.delete"].scope, APP_TOOLS["app.delete"].description, { code: z.string().min(1) }, async (session, args) => {
+        const readApps = async () => wireRows((await wireCall(session, { path: ENDPOINTS.applicationList, query: {} })).data);
+        const target = (await readApps()).find((row) => (row.appCode ?? row.code) === args.code);
+        if (!target)
+            return { performed: { skipped: "already-absent" }, readback: { absent: true } };
+        const performed = await wireCall(session, { path: ENDPOINTS.applicationDelete, method: "POST", query: { appCode: args.code } });
+        let absent = false;
+        for (let attempt = 0; attempt < 12 && !absent; attempt += 1) {
+            if (attempt > 0)
+                await new Promise((resolve) => setTimeout(resolve, Math.min(1000 * attempt, 3000)));
+            absent = !(await readApps()).some((row) => (row.appCode ?? row.code) === args.code);
+        }
+        return { performed: { errcode: performed.errcode, code: args.code }, readback: { absent } };
+    });
+}
+//# sourceMappingURL=app.js.map

package/dist/lanes/apply-changes.js

@@ -0,0 +1,231 @@
+import { z } from "zod";
+import { randomUUID } from "node:crypto";
+import { confirmProductionArg, environmentArg, WRITE_PROTOCOL } from "../args.js";
+import { executePackage } from "../package.js";
+import { plannableArgs } from "../plan.js";
+import { isUncertainWireError, wireErrorKind, writeArtifact } from "../support.js";
+import { defineTool, parseToolInput, ToolInputError, ToolRefusalError } from "../tool-types.js";
+import { WireError } from "../wire.js";
+/**
+ * Ticket 58: the batch time budget. `startedAt` is the execution start (ms
+ * epoch); `budgetMs` undefined means no budget. Exported so the arithmetic is
+ * pinned by a unit test instead of a timing-sensitive S1 test.
+ */
+export function batchBudgetExceeded(startedAt, budgetMs, now) {
+    if (budgetMs === undefined)
+        return false;
+    return now - startedAt >= budgetMs;
+}
+/**
+ * The default whole-batch time budget (8 minutes), applied when the caller
+ * omits `totalTimeoutMs`. It MUST stay safely below the CLI's own call timeout:
+ * the omc CLI caps `--timeout-ms` at 600000 ms (10 min), and the 2026-09-14
+ * `eq_repair_record` incident was exactly the failure mode of a batch that
+ * outlives its caller — the caller abandoned at its timeout while the batch
+ * kept executing, and the agent's retry became a second writer in the same
+ * environment. Stopping at a bounded budget returns a clean `uncertain` +
+ * progressFile + resumeFromIndex while the caller is still listening.
+ */
+export const DEFAULT_BATCH_BUDGET_MS = 8 * 60 * 1000;
+function refuseBatch(blocker, message, extra = {}) {
+    return { status: "refused", blocker, message, ...extra };
+}
+export function registerApplyChangesLane(tools) {
+    // Registered LAST in tools.ts, so the array reference is the complete
+    // registry by the time any handler runs.
+    const siblings = tools;
+    tools.push(defineTool({
+        name: "apply_changes",
+        layer: "high",
+        kind: "write",
+        description: `批量写入：changes:[{tool,args}]（仅低层原子工具，configure_* 拒收）；一次权限检查、按序读回、首败即停；长批量回传 progressFile（totalTimeoutMs 设整批预算）。 ${WRITE_PROTOCOL}`,
+        inputSchema: {
+            environment: environmentArg,
+            changes: z
+                .array(z.object({ tool: z.string().min(1), args: z.record(z.string(), z.unknown()).default({}) }))
+                .min(1)
+                .describe("有序变更清单；每项 { tool: 既有低层写工具名, args: 其参数 }；整包共用一次审批"),
+            summary: z.string().optional().describe("可选的整体业务描述，进入审批卡片与返回的 summary"),
+            totalTimeoutMs: z.number().int().positive().optional().describe(`整批时间预算（毫秒，自执行开始计）；超预算即停并返回已完成步骤/progressFile，status:uncertain、blocker:batch-timeout-budget。缺省 ${8 * 60 * 1000}ms（低于 CLI 调用超时，保证调用方仍在监听时干净返回）；长批量建议显式设置并分批`),
+            confirmProduction: confirmProductionArg,
+            dryRun: z.boolean().optional().describe("true = 只返回整包预览（plan/actions + planFingerprint），零环境写入"),
+        },
+        handler: async (ctx, args) => {
+            const changes = args.changes;
+            // ---- 1. Structural validation (zero wire calls) --------------------
+            if (!Array.isArray(changes) || changes.length === 0)
+                return refuseBatch("apply-changes-invalid", "changes 必须是非空数组（每项 { tool, args }）");
+            const targets = new Map();
+            const normalizedChanges = [];
+            for (const change of changes) {
+                if (!(change.tool && typeof change.tool === "string"))
+                    return refuseBatch("apply-changes-invalid", "changes 每项必须包含 tool");
+                if (!targets.has(change.tool)) {
+                    const target = siblings.find((tool) => tool.name === change.tool);
+                    if (!target)
+                        return refuseBatch("apply-changes-unknown-tool", `changes 引用了不存在的工具 ${change.tool}`, { tool: change.tool });
+                    if (target.kind !== "write")
+                        return refuseBatch("apply-changes-tool-not-writable", `${change.tool} 不是写工具（changes 只接受写操作）`, { tool: change.tool });
+                    if (target.layer !== "low" || !target.writeExecute)
+                        return refuseBatch("apply-changes-tool-not-atomic", `${change.tool} 是高层预设（已是单调用包）；changes 只接受低层原子写工具`, { tool: change.tool });
+                    if (!target.lane || !target.scope)
+                        return refuseBatch("apply-changes-tool-not-atomic", `${change.tool} 缺少 lane/scope 声明，无法通过覆盖门`, { tool: change.tool });
+                    targets.set(change.tool, target);
+                }
+                try {
+                    normalizedChanges.push({ tool: change.tool, args: parseToolInput(targets.get(change.tool), change.args) });
+                }
+                catch (error) {
+                    if (error instanceof ToolInputError)
+                        return { ...error.payload, failedBeforeApproval: true, changeTool: change.tool };
+                    throw error;
+                }
+            }
+            // ---- 2. Semantic gates BEFORE the write permission gate (dry) ------
+            try {
+                for (const change of normalizedChanges)
+                    targets.get(change.tool).writePreflight?.(change.args);
+            }
+            catch (error) {
+                if (error instanceof ToolRefusalError)
+                    return { ...error.payload, failedBeforeApproval: true };
+                throw error;
+            }
+            // ---- 3. One plan, one fingerprint, per-action coverage ------------
+            const toolPhrase = (list) => {
+                const counts = new Map();
+                for (const change of list)
+                    counts.set(change.tool, (counts.get(change.tool) ?? 0) + 1);
+                return [...counts.entries()].map(([tool, count]) => (count > 1 ? `${tool}×${count}` : tool)).join("、");
+            };
+            const plan = {
+                environment: "",
+                environmentFingerprint: "",
+                summary: args.summary ?? `即将按序执行 ${normalizedChanges.length} 项变更（${toolPhrase(normalizedChanges)}）`,
+                actions: normalizedChanges.map((change) => ({ tool: change.tool, args: plannableArgs(change.tool, change.args) })),
+            };
+            const coverage = {
+                perAction: normalizedChanges.map((change) => {
+                    const target = targets.get(change.tool);
+                    return { lane: target.lane, scope: target.scope };
+                }),
+            };
+            return executePackage(ctx, plan, coverage, args, async (session) => {
+                const steps = [];
+                // Ticket 58: a recoverable handle for a long batch. Every step appends
+                // to one progress artifact, so a client-side timeout or a killed
+                // server still leaves the exact progress on disk.
+                const runId = randomUUID().slice(0, 8);
+                const startedAt = Date.now();
+                const budgetMs = args.totalTimeoutMs ?? DEFAULT_BATCH_BUDGET_MS;
+                const batchSummary = plan.summary;
+                const recordProgress = (status, upTo) => writeArtifact(ctx, `batch-progress-${runId}.json`, {
+                    runId,
+                    summary: batchSummary,
+                    startedAt,
+                    budgetMs: budgetMs ?? null,
+                    steps,
+                    nextIndex: upTo,
+                    status,
+                }).detailFile;
+                for (let index = 0; index < normalizedChanges.length; index += 1) {
+                    const change = normalizedChanges[index];
+                    const target = targets.get(change.tool);
+                    if (batchBudgetExceeded(startedAt, budgetMs, Date.now())) {
+                        const progressFile = recordProgress("STOPPED", steps.length);
+                        const stop = {
+                            status: "uncertain",
+                            steps,
+                            failedStep: { index, tool: change.tool },
+                            envelope: {
+                                blocker: "batch-timeout-budget",
+                                frozen: true,
+                                budgetMs,
+                                message: `已达整批预算 ${budgetMs}ms，在第 ${index + 1} 步（${change.tool}）前停止；已完成 ${steps.length} 项（其效果真实存在）。先读 progressFile 与只读发现确认进度，再决定是否续跑——绝不盲重试`,
+                                summary: `${args.summary ? `${args.summary}；` : ""}批量达预算停止于第 ${index + 1} 步前，已完成 ${steps.length} 项`,
+                                progressFile,
+                                // Ticket 81: structured recovery semantics — a timeout is NOT
+                                // failure; the server may have completed everything.
+                                nextAction: {
+                                    rule: "read-back-first",
+                                    steps: [
+                                        "读 progressFile：拿到已完成步骤清单（其效果真实存在于环境）",
+                                        "用只读发现核对每一步的权威面（discover_environment / 对应 lane 的 list/get 读回；写工具的 already-present/already-published 短路可安全复用）",
+                                        `仅对缺失步骤重新组包：从 failedStep.index=${index} 起，剔除读回确认已生效的项`,
+                                    ],
+                                    forbidden: "盲目整批重试——已完成步骤会重复执行或触发重复码拒绝（如 listview.create 303002）",
+                                    resumeFromIndex: index,
+                                },
+                            },
+                        };
+                        return stop;
+                    }
+                    try {
+                        const outcome = await target.writeExecute(session, change.args);
+                        steps.push({ step: change.tool, index, status: "ok", performed: outcome.performed, readback: outcome.readback });
+                        recordProgress("RUNNING", index + 1);
+                    }
+                    catch (error) {
+                        const failedStep = { index, tool: change.tool };
+                        if (isUncertainWireError(error)) {
+                            // Per-step transport/timeout: uncertain, frozen — never success.
+                            const progressFile = recordProgress("STOPPED", steps.length);
+                            const stop = {
+                                status: "uncertain",
+                                steps,
+                                failedStep,
+                                envelope: {
+                                    frozen: true,
+                                    reason: `wire-transport:${wireErrorKind(error)}`,
+                                    detail: error.message,
+                                    message: `第 ${index + 1} 步（${change.tool}）传输中断，写入结果无法判定；已冻结——先重新发现再决定重试，绝不假定为成功`,
+                                    summary: `${args.summary ? `${args.summary}；` : ""}批量在第 ${index + 1} 步（${change.tool}）中断，已完成 ${steps.length} 项，结果不确定`,
+                                    progressFile,
+                                    // Ticket 81: the interrupted step itself may have taken
+                                    // effect server-side — read back before any retry.
+                                    nextAction: {
+                                        rule: "read-back-first",
+                                        steps: [
+                                            "读 progressFile：拿到已完成步骤清单（其效果真实存在于环境）",
+                                            `先核对第 ${index + 1} 步（${change.tool}）本身是否已生效——超时≠失败，服务端可能已写入`,
+                                            "用只读发现核对每一步的权威面，仅对缺失步骤重新组包执行",
+                                        ],
+                                        forbidden: "盲目整批重试或假定中断步骤失败——重复执行会撞重复码（如 listview.create 303002）",
+                                        resumeFromIndex: index,
+                                    },
+                                },
+                            };
+                            return stop;
+                        }
+                        const envelope = error instanceof ToolRefusalError
+                            ? { ...error.payload }
+                            : error instanceof WireError
+                                ? { blocker: `wire-${error.kind}`, errcode: error.errcode, message: error.message }
+                                : { blocker: "apply-changes-step-failed", message: error.message };
+                        const progressFile = recordProgress("STOPPED", steps.length);
+                        const stop = {
+                            status: "refused",
+                            steps,
+                            failedStep,
+                            envelope: {
+                                ...envelope,
+                                message: `${typeof envelope.message === "string" ? envelope.message : "步骤失败"}；批量在第 ${index + 1} 步（${change.tool}）停止，后续步骤未执行；已完成步骤见 steps（其效果真实存在，需要善后时按 steps 清单处理）`,
+                                summary: `${args.summary ? `${args.summary}；` : ""}批量在第 ${index + 1} 步（${change.tool}）停止，已完成 ${steps.length} 项`,
+                                progressFile,
+                            },
+                        };
+                        return stop;
+                    }
+                }
+                const executedTools = [...new Set(normalizedChanges.map((change) => change.tool))];
+                const progressFile = recordProgress("DONE", steps.length);
+                return {
+                    steps,
+                    readback: { stepCount: steps.length, tools: executedTools, allStepsOk: steps.every((step) => step.status === "ok"), progressFile },
+                    summary: args.summary ?? `已按序完成 ${steps.length} 项变更（${toolPhrase(changes)}）`,
+                };
+            });
+        },
+    }));
+}
+//# sourceMappingURL=apply-changes.js.map