@stalfh233/omc-cli 0.0.0-stage → 0.4.10

package/dist/form-support.js

@@ -0,0 +1,821 @@
+import { wireCall, wireRows, WireError } from "./wire.js";
+import { ENDPOINTS } from "./endpoints.js";
+import { decodeJsonObjectColumn } from "./json-column.js";
+import { ToolRefusalError } from "./tool-types.js";
+import { FIELD_CONTROL_TYPES, SYSTEM_FIELD_CODES, fieldControlOptions, relationDisplayField, relationMappings, } from "./field-families.js";
+import { deriveControlOptions } from "./capability-shape.js";
+import { validateFormLayoutShape } from "./form-layout.js";
+/**
+ * Propagate each relation field's `options.mappings` into its form control so
+ * the form-fill carry is configured where the form renderer reads it. The
+ * field is the source of truth; only controls matching a field code with a
+ * relation mapping or display field are touched.
+ */
+export function propagateRelationOptions(attributesJson, fields) {
+    let attributes;
+    try {
+        attributes = JSON.parse(attributesJson);
+    }
+    catch {
+        return attributesJson;
+    }
+    for (const field of fields) {
+        if (!field.mappings && !field.displayField)
+            continue;
+        const control = attributes[field.code];
+        if (control && typeof control === "object" && control.options && typeof control.options === "object") {
+            if (field.mappings)
+                control.options.mappings = field.mappings;
+            if (field.displayField) {
+                control.options.displayField = field.displayField;
+                control.options.relativePropertyMatchCode = field.displayField;
+                // Ticket 61 / A4: the runtime resolves the displayed value from the
+                // CONTROL's relativePropertyCode, not just displayField — without it
+                // a field-level display-field change never reaches the running form.
+                control.options.relativePropertyCode = field.displayField;
+            }
+        }
+    }
+    return JSON.stringify(attributes);
+}
+export const propagateRelationMappings = propagateRelationOptions;
+/** Validate the JSON shape consumed by the Online JS HTML renderer. */
+export function validateHtmlRender(value, requirePlatformSkeleton = false) {
+    if (value === undefined || value === null)
+        return { ok: true, skipped: true };
+    if (typeof value !== "string" || value.trim() === "") {
+        return { ok: false, violations: [{ index: -1, problem: "html must be a non-empty JSON element array" }] };
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(value);
+    }
+    catch {
+        return { ok: false, violations: [{ index: -1, problem: "html must be valid JSON" }] };
+    }
+    if (!Array.isArray(parsed) || parsed.length === 0) {
+        return { ok: false, violations: [{ index: -1, problem: "html must be a non-empty JSON element array" }] };
+    }
+    const violations = [];
+    const ids = new Set();
+    parsed.forEach((element, index) => {
+        if (!element || typeof element !== "object" || Array.isArray(element)) {
+            violations.push({ index, problem: "element must be an object" });
+            return;
+        }
+        const record = element;
+        const tagNameInvalid = typeof record.tagName !== "string" || record.tagName.trim() === "";
+        const attrsInvalid = !Array.isArray(record.attrs);
+        if (tagNameInvalid || attrsInvalid)
+            violations.push({ index, problem: "tagName missing or attrs not an array" });
+        if (typeof record.id === "string")
+            ids.add(record.id);
+    });
+    if (requirePlatformSkeleton) {
+        for (const id of ["toolbar", "template", "beforeCustomScript", "customScript", "afterCustomScript"]) {
+            if (!ids.has(id))
+                violations.push({ index: -1, problem: `platform skeleton missing ${id}` });
+        }
+        if (!parsed.some((element) => element && typeof element === "object" && !Array.isArray(element) && element.tagName === "style")) {
+            violations.push({ index: -1, problem: "platform skeleton missing style" });
+        }
+    }
+    return violations.length === 0 ? { ok: true } : { ok: false, violations };
+}
+export function assertHtmlRender(value, details, requirePlatformSkeleton = false) {
+    const compat = validateHtmlRender(value, requirePlatformSkeleton);
+    if (!compat.ok) {
+        throw new ToolRefusalError({
+            status: "refused",
+            blocker: "form-html-render-invalid",
+            ...details,
+            htmlRenderCompat: compat,
+            message: "draftHtmlJson 未通过 Online JS HTML 渲染形状校验；拒绝写入/提拔，零 wire",
+        });
+    }
+}
+/**
+ * Ticket 69 — the org-selection discriminator per field property type
+ * (人员单选 50 / 人员多选 51 / 部门单选 60 / 部门多选 61 / 混合选人 5).
+ * `options.deptVisible` + `options.multi` are what the platform reads
+ * (BizPropertyTypeUpdateUtils.disposeUpdateType,
+ * DataModelInitUtils.updateSelectionType); the control type alone is not
+ * enough — a 人员单选 without deptVisible opened a department picker.
+ */
+export function orgSelectorDiscriminator(fieldType) {
+    switch (fieldType) {
+        case 50: return { deptVisible: "user", multi: "false" };
+        case 51: return { deptVisible: "user", multi: "true" };
+        case 60: return { deptVisible: "org", multi: "false" };
+        case 61: return { deptVisible: "org", multi: "true" };
+        case 5: return { deptVisible: "all", multi: "true" };
+        default: return undefined;
+    }
+}
+/**
+ * Ticket 69 — normalise every org-selection control in an existing draft to
+ * carry the discriminator, so a form drafted before the fix (or by the
+ * designer) is repaired on the next form.draft and works after re-publish.
+ */
+export function normalizeOrgSelectorControls(attributesJson, fields) {
+    let attributes;
+    try {
+        attributes = JSON.parse(attributesJson);
+    }
+    catch {
+        return attributesJson;
+    }
+    for (const field of fields) {
+        const discriminator = orgSelectorDiscriminator(field.type);
+        if (!discriminator)
+            continue;
+        const control = attributes[field.code];
+        if (!control || typeof control !== "object" || typeof control.options !== "object" || control.options === null)
+            continue;
+        const defaults = deriveControlOptions(field.type);
+        for (const [key, value] of Object.entries(defaults))
+            if (control.options[key] === undefined)
+                control.options[key] = value;
+        control.options.deptVisible = discriminator.deptVisible;
+        control.options.multi = discriminator.multi;
+        if (control.options.defaultValue === undefined)
+            control.options.defaultValue = [];
+        if (control.options.defaultValueType === undefined)
+            control.options.defaultValueType = "";
+        if (control.options.orgRoot === undefined)
+            control.options.orgRoot = [];
+        if (control.options.roles === undefined)
+            control.options.roles = "";
+        if (control.options.mappings === undefined)
+            control.options.mappings = "";
+        if (control.options.displayType === undefined)
+            control.options.displayType = "tag";
+        if (control.options.selectMode === undefined)
+            control.options.selectMode = "popup";
+    }
+    return JSON.stringify(attributes);
+}
+/**
+ * The form-interaction condition keys are FIELD-owned: the designer stores the
+ * condition on the field (field options) and the runtime renderer reads the
+ * COPY on the control (`control.options.requiredFormula` / `readonlyCondition`,
+ * live bundle 19497: `if(t.options.requiredFormula) u.required=...`).
+ *
+ * The scaffold copies them when it first builds a control, but a
+ * `form.draft`/`configure_form` WITHOUT `rebuild` keeps every existing control
+ * verbatim — so a later `field.update` that adds/changes a condition never
+ * reached an already-built form. Live bench20: the agent set the conditions
+ * AFTER the first configure_form, re-ran configure_form without rebuild, read
+ * `ok`, and the portal showed no condition. Sync the field-owned keys into the
+ * existing controls on EVERY draft write; keys absent on the field are left
+ * untouched, so a designer-only condition survives (never clobber).
+ */
+const FIELD_OWNED_CONTROL_KEYS = ["requiredFormula", "readonlyFormula", "readonlyCondition", "displayFormula", "optionsSet"];
+/**
+ * Repair relation child columns on an EXISTING child-table (201) control. The
+ * 2026-09-23 scaffold dropped `relativeCode/mappings/displayField` from child
+ * properties, so a WORK_SHEET child column was written with `schemaCode:""` and
+ * bizsheet/publish then failed 301015 "[列名]未选择关联模型" (BizFormController
+ * checkRelationCode requires options.schemaCode for column type 80/81/90).
+ * A non-rebuild draft keeps controls verbatim, so fill the missing relation keys
+ * in place from the model's subSchema — a designer-set non-empty schemaCode is
+ * never clobbered.
+ */
+export function repairChildTableRelationColumns(attributesJson, fields) {
+    let attributes;
+    try {
+        attributes = JSON.parse(attributesJson);
+    }
+    catch {
+        return attributesJson;
+    }
+    for (const field of fields) {
+        if (field.type !== 8 || !field.childProperties)
+            continue;
+        const control = attributes[field.code];
+        if (!control || !Array.isArray(control.columns))
+            continue;
+        for (const column of control.columns) {
+            const child = field.childProperties.find((entry) => entry.code === column.key);
+            if (!child || (child.type !== 9 && child.type !== 11) || !child.relativeCode)
+                continue;
+            const options = column.options && typeof column.options === "object" && !Array.isArray(column.options)
+                ? column.options
+                : (column.options = {});
+            if (typeof options.schemaCode === "string" && options.schemaCode.trim() !== "")
+                continue;
+            options.schemaCode = child.relativeCode;
+            options.queryCode = child.relativeCode;
+            if (options.displayField === undefined || options.displayField === "")
+                options.displayField = child.displayField ?? "name";
+            if (options.relativePropertyMatchCode === undefined || options.relativePropertyMatchCode === "")
+                options.relativePropertyMatchCode = child.displayField ?? "name";
+            if (options.mappings === undefined || options.mappings === "")
+                options.mappings = child.mappings ?? "";
+        }
+    }
+    return JSON.stringify(attributes);
+}
+export function syncFieldDerivedControlOptions(attributesJson, fields) {
+    let attributes;
+    try {
+        attributes = JSON.parse(attributesJson);
+    }
+    catch {
+        return attributesJson;
+    }
+    for (const field of fields) {
+        if (field.fieldOptions === undefined)
+            continue;
+        const control = attributes[field.code];
+        if (!control || typeof control !== "object" || typeof control.options !== "object" || control.options === null)
+            continue;
+        for (const key of FIELD_OWNED_CONTROL_KEYS) {
+            const value = field.fieldOptions[key];
+            if (value !== undefined)
+                control.options[key] = value;
+        }
+    }
+    return JSON.stringify(attributes);
+}
+/**
+ * Ticket 66 — a model's "redundant" fields are the carry-through targets of
+ * its relation mappings (`options.mappings[{source,target}]`): values auto-filled
+ * from the related model, not hand-entered. They must still be bound on the
+ * form; only their visibility is governed (form-design hidden when the model
+ * has no workflow, else per-workflow-node permissions).
+ */
+export function redundantFieldCodes(fields) {
+    const targets = new Set();
+    for (const field of fields) {
+        if (field.type !== 9 && field.type !== 11)
+            continue;
+        if (!field.mappings)
+            continue;
+        let parsed;
+        try {
+            parsed = JSON.parse(field.mappings);
+        }
+        catch {
+            continue;
+        }
+        if (!Array.isArray(parsed))
+            continue;
+        for (const entry of parsed) {
+            const target = entry?.target;
+            if (typeof target === "string" && target.trim())
+                targets.add(target.trim());
+        }
+    }
+    return targets;
+}
+/**
+ * Read a model's default form. CloudPivot answers errcode 302024
+ * ("表单不存在！") when the model has no form row yet — that is absence, not a
+ * failure, so callers get null and may create it.
+ */
+async function readFormOrNull(session, schemaCode, sheetCode) {
+    try {
+        const result = await wireCall(session, { path: ENDPOINTS.sheetGet, query: { schemaCode, sheetCode } });
+        return (result.data ?? null);
+    }
+    catch (error) {
+        if (error instanceof WireError && error.errcode === 302024)
+            return null;
+        throw error;
+    }
+}
+/**
+ * Create the default form row for a model that has none (bizsheet/create;
+ * sheetType 0 = BizFormType.DEFAULT_SHEET). A model created via bizmodels/create
+ * carries no form, so form.draft must materialise it before it can hold a
+ * draft layout. The subsequent scaffold+update writes the layout.
+ */
+async function createDefaultForm(session, schemaCode, sheetCode) {
+    await wireCall(session, {
+        path: ENDPOINTS.sheetCreate,
+        method: "POST",
+        body: {
+            schemaCode,
+            code: sheetCode,
+            name: sheetCode,
+            name_i18n: JSON.stringify({ "zh-CN": sheetCode, en: sheetCode }),
+            sheetType: 0,
+        },
+    });
+}
+/**
+ * Ticket 102 — families that occupy a full row (span 24) in real forms:
+ * long text and attachments are inherently wide (fwb evidence §rows:
+ * business rows are 1×24 long-text/attachment, 2×12 pairs of narrow fields).
+ * Every other business family packs two per row at span:12.
+ */
+function wideBusinessFamily(type) {
+    return type === 1 || type === 6 || type === 8;
+}
+/**
+ * Sheet201 form control for a CHILD_TABLE(8) field: the parent control carries
+ * the child columns as `columns`, each keyed by the parent field code. Control
+ * `options` is a plain OBJECT (like every other scaffold control — the runtime
+ * 8.6.34 renderer mutates `control.options.name_i18n` and throws
+ * "Cannot create property 'name_i18n' on string" if it is a JSON string).
+ * Child column keys are NEVER added to viewJson — only the parent key is a
+ * layout row.
+ */
+function childTableColumns(parentCode, children) {
+    return children.map((child) => ({
+        type: FIELD_CONTROL_TYPES[child.type] ?? 1,
+        width: "180",
+        key: child.code,
+        parentKey: parentCode,
+        // A relation child column (WORK_SHEET 9 / MULT_WORK_SHEET 11) is a WORK_SHEET
+        // form control (80/81) and MUST carry its target `schemaCode` — dropping it
+        // makes bizsheet/publish fail 301015 "[列名]未选择关联模型" (BizFormController
+        // checkRelationCode: WORK_SHEET = {80,81,90} require options.schemaCode).
+        options: fieldControlOptions(child.type, child.name, child.relativeCode, child.mappings, child.displayField ?? "name", child.fieldOptions),
+    }));
+}
+/**
+ * Keep the designer's non-structural control edits across a rebuild. The
+ * freshly scaffolded control owns its label and relation target keys (they must
+ * track the field metadata), but everything else the designer changed on the
+ * draft — carry `mappings`, `visible`, `labelVisible`, `span`, conditions — is
+ * layered back from the previous draft. Child-table (201) controls are skipped:
+ * their columns are regenerated from the model's subSchema.
+ */
+export function preserveDesignerControlOptions(next, previous) {
+    const STRUCTURAL = new Set(["name", "name_i18n", "schemaCode", "displayField", "queryCode", "relativePropertyMatchCode"]);
+    const preserved = [];
+    for (const [key, control] of Object.entries(next)) {
+        const fresh = control;
+        const prior = previous[key];
+        if (!prior || typeof prior !== "object")
+            continue;
+        if (fresh.type === 201 || prior.type === 201)
+            continue;
+        if (!fresh.options || typeof fresh.options !== "object" || Array.isArray(fresh.options))
+            continue;
+        if (!prior.options || typeof prior.options !== "object" || Array.isArray(prior.options))
+            continue;
+        const merged = { ...fresh.options };
+        for (const [optionKey, value] of Object.entries(prior.options)) {
+            if (STRUCTURAL.has(optionKey) || value === undefined)
+                continue;
+            merged[optionKey] = value;
+        }
+        fresh.options = merged;
+        preserved.push(key);
+    }
+    return preserved;
+}
+function childTableParentControl(field) {
+    return {
+        key: field.code,
+        type: 201,
+        options: {
+            name: field.name,
+            name_i18n: { "zh-CN": field.name, en: field.name },
+            visible: true,
+            labelVisible: true,
+            span: 24,
+            widgetType: "子表",
+            width: 150,
+            displayPosition: "right",
+            rows: 0,
+            editable: true,
+            importable: true,
+            exportable: true,
+            addable: true,
+            deletable: true,
+            copyAble: true,
+            clearRowAble: true,
+            showTotal: false,
+            presetButtonManage: "",
+            summary: "",
+        },
+        columns: childTableColumns(field.code, field.childProperties ?? []),
+    };
+}
+/**
+ * Build the designer-standard default-form scaffold (research §13): Title
+ * (203, named after the model, useDataTitle) + system row [creater(101),
+ * createdTime(104), sequenceNo(100)] + one group (200), followed by the
+ * business fields with their mapped controls, packed compactly (ticket 102:
+ * narrow fields two per row at span:12; wide families alone at span:24 —
+ * row totals never exceed 24). Relation controls carry the target schema
+ * from the field's relativeCode. Used only when the target default form's
+ * draft layout is empty.
+ */
+export function buildFormScaffold(fields, formName, hiddenCodes) {
+    const ts = Date.now();
+    const titleKey = `Title${ts}`;
+    const groupKey = `Group${ts}`;
+    const business = fields.filter((field) => !SYSTEM_FIELD_CODES.has(field.code) && FIELD_CONTROL_TYPES[field.type] && scaffoldControlConfigPresent(field));
+    const businessRows = [];
+    let pair = [];
+    for (const field of business) {
+        if (wideBusinessFamily(field.type)) {
+            // Flush any pending pair FIRST so the emitted row order always matches
+            // the field order (review finding: a wide family mid-pair used to jump
+            // the queue and reorder the layout).
+            if (pair.length > 0) {
+                businessRows.push(pair);
+                pair = [];
+            }
+            businessRows.push([field.code]);
+            continue;
+        }
+        pair.push(field.code);
+        if (pair.length === 2) {
+            businessRows.push(pair);
+            pair = [];
+        }
+    }
+    if (pair.length > 0)
+        businessRows.push(pair);
+    const rows = [[titleKey], ["creater", "createdTime", "sequenceNo"], [groupKey], ...businessRows];
+    const attributes = {
+        [titleKey]: { key: titleKey, type: 203, options: { name: formName, name_i18n: { en: formName, zh: formName }, visible: true, labelVisible: true, span: 24, labelAlign: "", style: "", tips: "", dataItemName: "", useDataTitle: true, styleInfo: { height: 1, bgColor: "#ffffff", bgImg: "", textAlign: "center", fontSize: 28, textColor: "#111218", blod: true, italic: false, textCss: "", textCssSwitch: false } } },
+        creater: { key: "creater", type: 101, options: { name: "创建人", name_i18n: "", visible: true, labelVisible: true, span: 8, labelAlign: "", style: "", tips: "", dataItemName: "", widgetType: "", dataItemType: "", mappings: "", verifyFormula: "", defaultValue: "" } },
+        createdTime: { key: "createdTime", type: 104, options: { name: "创建时间", name_i18n: "", visible: true, labelVisible: true, span: 8, labelAlign: "", style: "", tips: "", dataItemName: "", widgetType: "", dataItemType: "", format1: "YYYY-MM-DD HH:mm:ss", format: "YYYY-MM-DD HH:mm:ss", syncFormate: true, verifyFormula: "", defaultValue: "" } },
+        sequenceNo: { key: "sequenceNo", type: 100, options: { name: "单据号", name_i18n: "", visible: true, labelVisible: true, span: 8, labelAlign: "", style: "", tips: "", dataItemName: "", widgetType: "", dataItemType: "", seqNoSetting: [{ type: "UID", value: "aa860e64ff2e4f86851a661d663ae358" }], formPropertyType: 100, verifyFormula: "", displayFormula: "", defaultValue: "" } },
+        [groupKey]: { key: groupKey, type: 200, options: { name: "业务信息", tips: "", expand: true, align: "", style: "", styleInfo: { fontSize: 18, textColor: "#111218", blod: true, italic: false, textCss: "", textCssSwitch: false }, span: 24 } },
+    };
+    for (const field of business) {
+        if (field.type === 8) {
+            attributes[field.code] = childTableParentControl(field);
+            continue;
+        }
+        const control = { key: field.code, type: FIELD_CONTROL_TYPES[field.type], options: fieldControlOptions(field.type, field.name, field.relativeCode, field.mappings, field.displayField, field.fieldOptions) };
+        // Ticket 102: compact packing — narrow families span 12 (two per row),
+        // wide families keep the full 24.
+        control.options.span = wideBusinessFamily(field.type) ? 24 : 12;
+        // Ticket 66: a redundant (carry-through) field with no workflow to govern
+        // it per node is hidden in the form design; it stays bound so the carried
+        // value is still present on the form.
+        if (hiddenCodes?.has(field.code) && control.options && typeof control.options === "object") {
+            control.options.visible = false;
+        }
+        attributes[field.code] = control;
+    }
+    return { rows, attributes };
+}
+/**
+ * A control is only scaffolded when the family's strict configuration is
+ * present on the field. A FORMULA control without formulaConfig or a
+ * RELEVANCE_DATA control without relevanceField/referenceField would render an
+ * invalid control (admin validation refuses both), so such fields are skipped
+ * rather than bound with fabricated options.
+ */
+function scaffoldControlConfigPresent(field) {
+    if (field.type === 100)
+        return typeof field.fieldOptions?.formulaConfig === "string" && field.fieldOptions.formulaConfig.length > 0;
+    if (field.type === 16)
+        return typeof field.fieldOptions?.relevanceField === "string" && field.fieldOptions.relevanceField.length > 0 && typeof field.fieldOptions?.referenceField === "string" && field.fieldOptions.referenceField.length > 0;
+    if (field.type === 8)
+        return Array.isArray(field.childProperties) && field.childProperties.length > 0;
+    return true;
+}
+/**
+ * Ticket 74 — an explicitly provided layout string that parses to an empty
+ * array/object ("[]", "{}", whitespace variants). The platform designer's
+ * Save is NOT lossless: it clears draftViewJson to "[]" and
+ * draftAttributesJson to "{}", and promoting that draft loses every
+ * control. Writing such a value explicitly is refused unless the caller
+ * passes allowEmptyLayout:true.
+ */
+export function isEmptyLayoutJson(value) {
+    const trimmed = value.trim();
+    if (trimmed.length === 0)
+        return true;
+    try {
+        const parsed = JSON.parse(trimmed);
+        if (Array.isArray(parsed))
+            return parsed.length === 0;
+        if (parsed && typeof parsed === "object")
+            return Object.keys(parsed).length === 0;
+        return parsed === null;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Distribution-grade dry-lint for a CALLER-PROVIDED form layout (args, not the
+ * stored draft). These are the shapes that render fine on readback but blank
+ * the 8.6.34 page — the CLI refuses them before any wire call so a caller who
+ * never read the docs still cannot ship a broken form. Runs on ANY provided
+ * face (one-sided included), covering configure_form/apply_changes paths that
+ * do not pass through the `form.draft` write permission gate.
+ */
+export function assertCallerFormLayout(args) {
+    if (args.draftViewJson === undefined && args.draftAttributesJson === undefined)
+        return;
+    const parse = (value) => {
+        if (typeof value !== "string")
+            return undefined;
+        try {
+            return JSON.parse(value);
+        }
+        catch {
+            return undefined;
+        }
+    };
+    const violations = validateFormLayoutShape(parse(args.draftViewJson), parse(args.draftAttributesJson));
+    if (violations.length > 0) {
+        throw new ToolRefusalError({
+            status: "refused",
+            blocker: "form-layout-invalid",
+            schemaCode: args.schemaCode,
+            sheetCode: args.sheetCode,
+            validation: violations,
+            message: `调用方提供的表单布局形状非法（写前零 wire 拒绝）：${violations.map((v) => v.field ?? v.classification).join("、")}`,
+        });
+    }
+}
+/** Ticket 74 — control count on an attributes JSON face (0 when unparsable/absent). */
+function controlCount(face) {
+    if (typeof face !== "string")
+        return 0;
+    try {
+        const parsed = JSON.parse(face);
+        return parsed && typeof parsed === "object" ? Object.keys(parsed).length : 0;
+    }
+    catch {
+        return 0;
+    }
+}
+/**
+ * Shared form.draft write body — read the current sheet, compose a scaffold
+ * from published fields when the form is empty, and POST the proven payload
+ * to bizsheet/update. Used by the form.draft write tool AND by configure_form,
+ * so the high-level orchestrator never bypasses the scaffold.
+ */
+export async function executeFormDraftWrite(session, args) {
+    if (args.draftHtmlJson !== undefined) {
+        assertHtmlRender(args.draftHtmlJson, { schemaCode: args.schemaCode, sheetCode: args.sheetCode, face: "draftHtmlJson" });
+    }
+    // Caller-provided layouts get the distribution-grade shape gate (options
+    // objects, string viewJson cells, no child keys as rows) before any wire.
+    if (args.draftViewJson !== undefined || args.draftAttributesJson !== undefined)
+        assertCallerFormLayout(args);
+    // Ticket 74 — refuse CALLER-PROVIDED empty layouts before any wire call.
+    // The platform designer's Save clears draft faces to "[]"/"{}" (non-lossless);
+    // re-writing that shape explicitly is how the 13-control loss happened.
+    if (args.allowEmptyLayout !== true) {
+        const emptyFaces = [];
+        if (typeof args.draftViewJson === "string" && isEmptyLayoutJson(args.draftViewJson))
+            emptyFaces.push("draftViewJson");
+        if (typeof args.draftAttributesJson === "string" && isEmptyLayoutJson(args.draftAttributesJson))
+            emptyFaces.push("draftAttributesJson");
+        if (emptyFaces.length > 0) {
+            throw new ToolRefusalError({
+                status: "refused",
+                blocker: "form-empty-layout",
+                schemaCode: args.schemaCode,
+                sheetCode: args.sheetCode,
+                faces: emptyFaces,
+                message: `显式提供的 ${emptyFaces.join("、")} 是空布局（"[]"/"{}"）——平台设计器 Save 会把草稿清成该形态（非无损），照写会丢控件。若确要清空布局请显式传 allowEmptyLayout:true；若是设计器 Save 后的修复，先用表单版本历史（/api/api/app/bizsheet/history/list）取回完好版本原文再写回`,
+            });
+        }
+    }
+    // Ticket 48: an explicit fieldCodes selection shapes the scaffold — exactly
+    // those fields, in the given order. Validate against the published face
+    // BEFORE creating anything so an unknown code never writes a form row.
+    const wanted = args.fieldCodes;
+    let selectionUnknown;
+    if (wanted && args.draftAttributesJson === undefined) {
+        const rows = wireRows((await wireCall(session, { path: ENDPOINTS.fieldList, query: { schemaCode: args.schemaCode, isPublish: "true" } })).data);
+        const publishedCodes = new Set(rows.map((row) => String(row.code ?? row.propertyCode ?? "")));
+        selectionUnknown = wanted.filter((code) => !publishedCodes.has(code));
+    }
+    if (selectionUnknown && selectionUnknown.length > 0) {
+        throw new ToolRefusalError({
+            status: "refused",
+            blocker: "form-fieldcodes-unknown",
+            schemaCode: args.schemaCode,
+            fieldCodes: selectionUnknown,
+            message: `fieldCodes 引用了模型 ${args.schemaCode} 发布面上不存在的字段：${selectionUnknown.join("、")}；先 field.create + field.publish 这些字段，或修正 fieldCodes`,
+        });
+    }
+    // The default form may not exist yet on a freshly created model
+    // (bizmodels/create seeds no form) — create it, then scaffold into it.
+    let pre = await readFormOrNull(session, args.schemaCode, args.sheetCode);
+    if (pre === null) {
+        await createDefaultForm(session, args.schemaCode, args.sheetCode);
+        // Creation must be immediately authoritative before composing an update
+        // body; do not continue against an assumed/asynchronously visible form.
+        pre = await readFormOrNull(session, args.schemaCode, args.sheetCode);
+        if (pre === null)
+            throw new WireError("business", `form ${args.sheetCode} was created but is not readable`, 302024);
+    }
+    // Field-level relation mappings are the source of truth; read the published
+    // fields so the scaffold (or an existing draft) can carry them into the
+    // matching form control, where the form renderer reads them at fill time.
+    const publishedFields = args.draftAttributesJson === undefined
+        ? await Promise.all(wireRows((await wireCall(session, { path: ENDPOINTS.fieldList, query: { schemaCode: args.schemaCode, isPublish: "true" } })).data).map(async (row) => {
+            const type = Number(row.type ?? row.propertyType);
+            const relativeCode = row.relativeCode ? String(row.relativeCode) : undefined;
+            // fieldOptions face decode; policy: corrupt strings throw, objects accepted, missing → undefined.
+            const fieldOptions = decodeJsonObjectColumn(row.options, { invalid: "throw", array: "accept", object: "accept" });
+            let displayField;
+            if (relativeCode && (type === 9 || type === 11)) {
+                displayField = relationDisplayField(row.options);
+                if (!displayField) {
+                    const targetRows = wireRows((await wireCall(session, { path: ENDPOINTS.fieldList, query: { schemaCode: relativeCode, isPublish: "true" } })).data);
+                    const title = targetRows.find((target) => String(target.code ?? target.propertyCode) === "name" || target.name === "数据标题");
+                    displayField = title ? String(title.code ?? title.propertyCode) : "name";
+                }
+            }
+            const mappings = relationMappings(row.options);
+            // CHILD_TABLE(8): the child columns live on the row's subSchema; carry
+            // them onto the form control as Sheet201 columns.
+            const subSchema = type === 8 ? decodeJsonObjectColumn(row.subSchema, { invalid: "undefined", array: "reject", object: "accept" }) : undefined;
+            const rawChildren = subSchema && Array.isArray(subSchema.properties) ? subSchema.properties : undefined;
+            const childProperties = rawChildren
+                ?.filter((child) => child.defaultProperty !== true && !SYSTEM_FIELD_CODES.has(String(child.code ?? "")))
+                .map((child) => {
+                const childOptions = decodeJsonObjectColumn(child.options, { invalid: "undefined", array: "accept", object: "accept" });
+                const childType = Number(child.type ?? child.propertyType);
+                const childRelativeCode = child.relativeCode ? String(child.relativeCode) : undefined;
+                // Relation child columns MUST keep their target schema + carried
+                // mappings on the WORK_SHEET control, or bizsheet/publish answers
+                // 301015 (see childTableColumns).
+                const childMappings = relationMappings(child.options);
+                const childDisplayField = childRelativeCode && (childType === 9 || childType === 11) ? relationDisplayField(child.options) : undefined;
+                return {
+                    code: String(child.code ?? ""),
+                    name: String(child.name ?? child.code ?? ""),
+                    type: childType,
+                    ...(childRelativeCode ? { relativeCode: childRelativeCode } : {}),
+                    ...(childMappings ? { mappings: childMappings } : {}),
+                    ...(childDisplayField ? { displayField: childDisplayField } : {}),
+                    ...(childOptions ? { fieldOptions: childOptions } : {}),
+                };
+            })
+                .filter((child) => child.code.length > 0 && Number.isFinite(child.type));
+            return {
+                code: String(row.code ?? row.propertyCode),
+                name: String(row.name ?? row.code ?? ""),
+                type,
+                ...(relativeCode ? { relativeCode } : {}),
+                ...(mappings ? { mappings } : {}),
+                ...(displayField ? { displayField } : {}),
+                ...(fieldOptions ? { fieldOptions } : {}),
+                ...(childProperties && childProperties.length > 0 ? { childProperties } : {}),
+            };
+        }))
+        : [];
+    let view = args.draftViewJson ?? (pre ? pre.draftViewJson : undefined);
+    let attributes = args.draftAttributesJson ?? (pre ? pre.draftAttributesJson : undefined);
+    // Designer edits that live ONLY on the form draft (relation carry mappings,
+    // control visibility/width, label tweaks) are not derivable from field
+    // metadata. A rebuild re-scaffolds, so capture the previous draft first and
+    // layer those edits back on (see preserveDesignerControlOptions).
+    const previousAttributes = !args.rebuild || typeof pre?.draftAttributesJson !== "string"
+        ? undefined
+        : decodeJsonObjectColumn(pre.draftAttributesJson, { invalid: "undefined", array: "reject", object: "accept" });
+    // `rebuild: true` discards the existing draft layout and re-scaffolds from
+    // the published fields, so fields added after the form was first built (a
+    // child table, a new relation) land in the layout. The platform designer's
+    // draft is otherwise preserved verbatim.
+    if (args.rebuild === true && args.draftViewJson === undefined && args.draftAttributesJson === undefined) {
+        view = undefined;
+        attributes = undefined;
+    }
+    let rebuildPreservedControls = [];
+    if (typeof view !== "string" || typeof attributes !== "string") {
+        // Ticket 48: an explicit fieldCodes selection picks (and orders) the
+        // scaffolded business fields; omitted scaffolds every published field.
+        const scaffoldFields = wanted
+            ? wanted.map((code) => publishedFields.find((field) => field.code === code)).filter((field) => field !== undefined)
+            : publishedFields;
+        if (scaffoldFields.length === 0)
+            throw new WireError("business", "form draft requires published fields to scaffold (none found); create and publish fields first", 302020);
+        // Ticket 66: redundant (carry-through) fields stay bound. When the model
+        // has NO workflow, hide them in the form design (option 1); with a
+        // workflow, leave them visible so per-node propertyPermissions govern
+        // (option 2, preferred — configured on the workflow template's activities).
+        const redundant = redundantFieldCodes(scaffoldFields);
+        let hidden;
+        if (redundant.size > 0) {
+            const hasWorkflow = (await wireCall(session, { path: ENDPOINTS.workflowIsWorkflow, query: { schemaCode: args.schemaCode } })).data === true;
+            if (!hasWorkflow)
+                hidden = redundant;
+        }
+        const scaffold = buildFormScaffold(scaffoldFields, pre?.name ?? String(args.sheetCode), hidden);
+        if (previousAttributes)
+            rebuildPreservedControls = preserveDesignerControlOptions(scaffold.attributes, previousAttributes);
+        view = JSON.stringify(scaffold.rows);
+        attributes = JSON.stringify(scaffold.attributes);
+    }
+    if (args.draftAttributesJson === undefined && typeof attributes === "string") {
+        attributes = propagateRelationMappings(attributes, publishedFields);
+        // Ticket 69: repair/densify org-selection controls on the existing draft.
+        attributes = normalizeOrgSelectorControls(attributes, publishedFields);
+        // Repair relation child columns written before the childProperties fix
+        // (301015 "[列名]未选择关联模型").
+        attributes = repairChildTableRelationColumns(attributes, publishedFields);
+        // Field-owned form conditions (required/readonly/display) must reach the
+        // control even when the form already existed — a non-rebuild draft keeps
+        // controls verbatim, so a later field.update never propagated (bench20).
+        attributes = syncFieldDerivedControlOptions(attributes, publishedFields);
+    }
+    const payload = {
+        ...(pre ?? {}),
+        schemaCode: args.schemaCode,
+        code: args.sheetCode,
+        name: pre?.name ?? args.sheetCode,
+        sheetType: pre?.sheetType ?? 0,
+        published: false,
+        // Draft writes are full-row updates, but they must not destroy the
+        // currently published face. Publish promotion is a separate operation;
+        // preserving these columns keeps the published form usable if the draft
+        // write or a later publish fails.
+        publishedViewJson: pre?.publishedViewJson ?? null,
+        publishedAttributesJson: pre?.publishedAttributesJson ?? null,
+        publishedActionsJson: pre?.publishedActionsJson ?? null,
+        publishedHtmlJson: pre?.publishedHtmlJson ?? null,
+        draftViewJson: view,
+        draftAttributesJson: attributes,
+        ...(args.draftHtmlJson ? { draftHtmlJson: args.draftHtmlJson } : {}),
+    };
+    const performed = await wireCall(session, { path: ENDPOINTS.sheetUpdate, method: "POST", body: payload });
+    const readback = await wireCall(session, { path: ENDPOINTS.sheetGet, query: { schemaCode: args.schemaCode, sheetCode: args.sheetCode } });
+    const sheet = (readback.data ?? {});
+    return { performed: { errcode: performed.errcode }, readback: { hasDraft: sheet.existDraft === true || typeof sheet.draftViewJson === "string", ...(args.rebuild === true && previousAttributes ? { rebuildPreservedControls } : {}) } };
+}
+/**
+ * Shared form.publish write body — promotes the saved draft to published,
+ * promoting draft*Json → published*Json verbatim (including draftHtmlJson →
+ * publishedHtmlJson). Used by the form.publish write tool AND by configure_form
+ * AND by onlinejs.compose. Pass `force:true` to override the
+ * already-published skip (compose needs this because it may legitimately
+ * re-publish after the caller has already published once).
+ */
+export async function executeFormPublishWrite(session, args) {
+    // A publish promotes a saved draft. When the model has no form yet, or the
+    // form exists but holds no draft, materialise the draft first (form.draft
+    // creates the default form and scaffolds the published fields) so a single
+    // form.publish call is self-sufficient. A draft that already exists is left
+    // untouched — this only fills the gap.
+    let pre = await readFormOrNull(session, args.schemaCode, args.sheetCode);
+    const hasDraft = (sheet) => sheet !== null && typeof sheet.draftViewJson === "string" && typeof sheet.draftAttributesJson === "string";
+    if (!hasDraft(pre)) {
+        await executeFormDraftWrite(session, { schemaCode: args.schemaCode, sheetCode: args.sheetCode });
+        pre = await readFormOrNull(session, args.schemaCode, args.sheetCode);
+    }
+    if (!pre)
+        throw new WireError("business", `form ${args.sheetCode} not found`, 302024);
+    if (pre.draftHtmlJson !== "[]")
+        assertHtmlRender(pre.draftHtmlJson, { schemaCode: args.schemaCode, sheetCode: args.sheetCode, face: "draftHtmlJson" });
+    if (pre.published === true && args.force !== true)
+        return { performed: { skipped: "already-published" }, readback: { published: true } };
+    if (!hasDraft(pre))
+        throw new WireError("business", "form publish requires a saved draft (draftViewJson/draftAttributesJson)", 302020);
+    if (pre.draftHtmlJson !== "[]")
+        assertHtmlRender(pre.draftHtmlJson, { schemaCode: args.schemaCode, sheetCode: args.sheetCode, face: "draftHtmlJson" });
+    // Ticket 74 — degrade guard: refuse to promote a draft that carries FEWER
+    // controls than the already-published face. The platform designer's Save
+    // clears the draft faces to "[]"/"{}" (non-lossless); promoting that empty
+    // draft is exactly how the 13-control loss happened. Escape: allowDegrade:true.
+    if (args.allowDegrade !== true) {
+        const draftControls = controlCount(pre.draftAttributesJson);
+        const publishedControls = controlCount(pre.publishedAttributesJson);
+        if (draftControls < publishedControls) {
+            throw new ToolRefusalError({
+                status: "refused",
+                blocker: "form-publish-degrade",
+                schemaCode: args.schemaCode,
+                sheetCode: args.sheetCode,
+                draftControlCount: draftControls,
+                publishedControlCount: publishedControls,
+                message: `草稿面控件数（${draftControls}）少于已发布面（${publishedControls}）——拒绝降级提拔。平台设计器 Save 会清空草稿（非无损）；恢复路径是表单版本历史 /api/api/app/bizsheet/history/list 取回完好版本的 view/attributes 原文重写草稿后再发布。确要减少控件请显式传 allowDegrade:true`,
+            });
+        }
+    }
+    const payload = {
+        ...pre,
+        schemaCode: args.schemaCode,
+        code: args.sheetCode,
+        name: pre.name,
+        sheetType: pre.sheetType ?? 0,
+        published: false,
+        existDraft: false,
+        sendMessage: false,
+        publishRemarks: args.publishRemarks ?? "omc-mcp-form-publication",
+        publishedViewJson: pre.draftViewJson,
+        publishedAttributesJson: pre.draftAttributesJson,
+        publishedActionsJson: pre.draftActionsJson ?? "[]",
+        publishedHtmlJson: pre.draftHtmlJson ?? "{}",
+        draftViewJson: pre.draftViewJson,
+        draftAttributesJson: pre.draftAttributesJson,
+        ...(pre.draftActionsJson !== null && pre.draftActionsJson !== undefined ? { draftActionsJson: pre.draftActionsJson } : {}),
+        ...(pre.draftHtmlJson !== null && pre.draftHtmlJson !== undefined ? { draftHtmlJson: pre.draftHtmlJson } : {}),
+    };
+    const performed = await wireCall(session, { path: ENDPOINTS.sheetPublish, method: "POST", body: payload });
+    const readback = await wireCall(session, { path: ENDPOINTS.sheetGet, query: { schemaCode: args.schemaCode, sheetCode: args.sheetCode } });
+    const sheet = (readback.data ?? {});
+    return { performed: { errcode: performed.errcode }, readback: { published: sheet.published === true, publishedHtmlJsonPresent: typeof sheet.publishedHtmlJson === "string" } };
+}
+//# sourceMappingURL=form-support.js.map