callman-mcp 0.1.0 → 0.2.0

package/dist-cjs/domain/scenario/build.js

@@ -1,45 +1,62 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.buildScenarioCreateBody = exports.buildScenarioGraph = exports.deepMerge = exports.scenarioInputSchema = exports.scenarioEnvironmentInputSchema = exports.scenarioEdgeInputSchema = exports.scenarioNodeInputSchema = exports.SCENARIO_NODE_TYPES = void 0;
+exports.buildScenarioCreateBody = exports.buildEnvironments = exports.buildScenarioGraph = exports.deepMerge = exports.scenarioInputSchema = exports.scenarioDbSettingsSchema = exports.scenarioDatasetSchema = exports.scenarioEnvironmentInputSchema = exports.scenarioEdgeInputSchema = exports.scenarioNodeInputSchema = exports.SCENARIO_NODE_TYPES = void 0;
 const callman_core_1 = require("callman-core");
 const zod_1 = require("zod");
 const errors_js_1 = require("../../client/errors.js");
 const ids_js_1 = require("../../lib/ids.js");
-const requestShape_js_1 = require("../requestShape.js");
+const strict_js_1 = require("../../lib/strict.js");
+const nodeConfig_js_1 = require("./nodeConfig.js");
 // From the COMPACT scenario a model writes to the backend's `POST /scenarios`
-// body. Node configs are deep-merged over core's canonical defaults for the
-// node type (the same defaults the builder and the AI assistant use), so a
-// partial config (`{ url, method }`) becomes a complete, runnable node; ids
-// are short and stable; missing positions are laid out in layers so the
-// graph opens tidy in the builder. The backend's zod schema stays the
-// arbiter of node config validity.
-exports.SCENARIO_NODE_TYPES = [...callman_core_1.SCENARIO_AI_REFERENCE_TYPES, "subscenario"];
-exports.scenarioNodeInputSchema = zod_1.z.object({
-    id: zod_1.z.string().min(1).max(64).optional(),
-    type: zod_1.z.string().min(1).max(40).describe(`Node type: ${exports.SCENARIO_NODE_TYPES.join(", ")} (see callman://docs/scenario-nodes)`),
-    label: zod_1.z.string().max(200).optional(),
-    config: zod_1.z.record(zod_1.z.unknown()).optional().describe("Type-specific config; merged over the node type's defaults"),
-    position: zod_1.z.object({ x: zod_1.z.number(), y: zod_1.z.number() }).optional(),
-});
-exports.scenarioEdgeInputSchema = zod_1.z.object({
+// body. A node's config is deep-merged over a BASE: the node's stored config
+// when a node with that id already exists (update / patch — so editing one
+// field never resets the rest), otherwise core's defaults for the type.
+// Ids are short and stable; missing positions are laid out in layers (stored
+// positions are kept). The backend's zod schema stays the arbiter of node
+// config validity; callman://docs/scenario-nodes documents every field.
+exports.SCENARIO_NODE_TYPES = callman_core_1.SCENARIO_NODE_REFERENCE_TYPES;
+// Output roots a label would shadow (warning, not an error).
+const SHADOWING_LABELS = new Set(["response", "lastResponse", "data", "env", "global", "globals", "db", "redis", "kafkaEvent", "kafkaevent"]);
+exports.scenarioNodeInputSchema = (0, strict_js_1.strictObject)({
+    id: zod_1.z.string().min(1).max(64).optional().describe("Stable id; generated (n1, n2…) when omitted. Reusing an existing id on update merges into that node"),
+    type: zod_1.z.string().min(1).max(40).describe(`Node type: ${exports.SCENARIO_NODE_TYPES.join(", ")} (callman://docs/scenario-nodes)`),
+    label: zod_1.z.string().max(200).optional().describe("Unique name; later nodes read its output as {{Label.path}}. Generated when omitted"),
+    config: zod_1.z.record(zod_1.z.unknown()).optional().describe("Type-specific config (callman://docs/scenario-nodes), merged over the stored node (same id) or the type's defaults"),
+    position: zod_1.z.object({ x: zod_1.z.number(), y: zod_1.z.number() }).strict().optional(),
+}, "node field");
+exports.scenarioEdgeInputSchema = (0, strict_js_1.strictObject)({
     id: zod_1.z.string().min(1).max(64).optional(),
     source: zod_1.z.string().min(1).max(64),
     target: zod_1.z.string().min(1).max(64),
-    type: zod_1.z.enum(["default", "yes", "no", "error"]).optional().describe("yes/no for condition branches, error for failure paths"),
-});
-exports.scenarioEnvironmentInputSchema = zod_1.z.object({
-    id: zod_1.z.string().min(1).max(64).optional(),
-    name: zod_1.z.string().min(1).max(200),
-    variables: zod_1.z.array(requestShape_js_1.kvSchema).max(500).default([]),
-});
-exports.scenarioInputSchema = zod_1.z.object({
-    name: zod_1.z.string().min(1).max(200),
+    type: zod_1.z.enum(["default", "yes", "no", "error"]).optional().describe("yes/no leave a condition node; error leaves any other node on failure"),
+}, "edge field");
+exports.scenarioEnvironmentInputSchema = (0, strict_js_1.strictObject)({
+    id: zod_1.z.string().min(1).max(200).optional(),
+    name: zod_1.z.string().trim().min(1).max(200),
+    variables: zod_1.z
+        .array((0, strict_js_1.strictObject)({ key: zod_1.z.string().trim().min(1).max(1000), value: zod_1.z.string().max(100_000).default(""), enabled: zod_1.z.boolean().optional() }, "variable field"))
+        .max(1000)
+        .default([]),
+}, "environment field");
+exports.scenarioDatasetSchema = (0, strict_js_1.strictObject)({
+    columns: zod_1.z.array(zod_1.z.string().max(200)).max(200),
+    rows: zod_1.z.array(zod_1.z.record(zod_1.z.string().max(100_000))).max(10_000).describe("Each row: column → value; nodes read {{data.<column>}}; the scenario runs once per row"),
+}, "dataset field")
+    .nullable()
+    .describe("Data-driven runs: the whole scenario runs once per row (null removes the dataset)");
+exports.scenarioDbSettingsSchema = (0, strict_js_1.strictObject)({ transactionMode: zod_1.z.enum(["none", "rollback", "commit"]).optional() }, "dbSettings field")
+    .nullable()
+    .describe('For db nodes with useSession: "rollback" wraps session DB work in BEGIN … ROLLBACK, "commit" commits on success, "none" keeps autocommit');
+exports.scenarioInputSchema = (0, strict_js_1.strictObject)({
+    name: zod_1.z.string().trim().min(1).max(200),
     description: zod_1.z.string().max(5000).optional(),
     priority: zod_1.z.enum(["critical", "high", "medium", "low"]).optional(),
     nodes: zod_1.z.array(exports.scenarioNodeInputSchema).min(1).max(1000),
     edges: zod_1.z.array(exports.scenarioEdgeInputSchema).max(2000).default([]),
-    environments: zod_1.z.array(exports.scenarioEnvironmentInputSchema).max(20).optional(),
-});
+    environments: zod_1.z.array(exports.scenarioEnvironmentInputSchema).max(100).optional(),
+    dataset: exports.scenarioDatasetSchema.optional(),
+    dbSettings: exports.scenarioDbSettingsSchema.optional(),
+}, "scenario field");
 const isRecord = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
 // Objects merge key by key; arrays and scalars from the override win whole.
 const deepMerge = (base, override) => {
@@ -52,35 +69,131 @@ const deepMerge = (base, override) => {
     return out;
 };
 exports.deepMerge = deepMerge;
-const buildScenarioGraph = (nodesInput, edgesInput) => {
-    const nextNodeId = (0, ids_js_1.sequentialIds)("n", nodesInput.map((node) => node.id).filter((id) => Boolean(id)));
+const labelBase = (type) => type
+    .split(/[-_]/)
+    .map((part) => part.charAt(0).toUpperCase() + part.slice(1))
+    .join("");
+// Labels of stored nodes nested in foreach / subscenario / scenario-ref bodies.
+const nestedLabels = (config) => {
+    const out = [];
+    for (const node of Array.isArray(config.nodes) ? config.nodes : []) {
+        if (!isRecord(node))
+            continue;
+        const data = isRecord(node.data) ? node.data : {};
+        if (typeof data.label === "string" && data.label)
+            out.push(data.label);
+        if (isRecord(data.config))
+            out.push(...nestedLabels(data.config));
+    }
+    return out;
+};
+const buildScenarioGraph = (nodesInput, edgesInput, options = {}) => {
+    const existingById = new Map((options.existing ?? []).map((node) => [node.id, node]));
+    const nextNodeId = (0, ids_js_1.sequentialIds)("n", [...nodesInput.map((node) => node.id).filter((id) => Boolean(id)), ...existingById.keys()]);
     const nextEdgeId = (0, ids_js_1.sequentialIds)("e", edgesInput.map((edge) => edge.id).filter((id) => Boolean(id)));
     const ids = nodesInput.map((node) => node.id ?? nextNodeId());
     const duplicate = ids.find((id, index) => ids.indexOf(id) !== index);
     if (duplicate)
         throw new errors_js_1.ToolInputError("SCENARIO_DUPLICATE_NODE_ID", `Duplicate node id "${duplicate}".`);
     const idSet = new Set(ids);
-    const nodes = nodesInput.map((node, index) => {
+    const warnings = [];
+    const problems = [];
+    const sent = new Map();
+    const built = nodesInput.map((node, index) => {
+        const id = ids[index];
         const type = node.type.trim();
         if (!exports.SCENARIO_NODE_TYPES.includes(type)) {
             throw new errors_js_1.ToolInputError("SCENARIO_UNKNOWN_NODE_TYPE", `Unknown scenario node type "${type}". Known: ${exports.SCENARIO_NODE_TYPES.join(", ")}.`);
         }
-        const defaults = (0, callman_core_1.defaultScenarioNodeConfig)(type);
-        const config = (0, exports.deepMerge)(defaults ?? {}, node.config ?? {});
+        const stored = existingById.get(id);
+        const sameNode = stored && stored.type === type ? stored : undefined;
+        if (type === "scenario-ref" && !sameNode) {
+            throw new errors_js_1.ToolInputError("SCENARIO_REF_READ_ONLY", `Node ${id}: scenario-ref nodes are created by linking a scenario in the desktop app; they can only be kept (send the stored node's id and type).`);
+        }
+        const base = sameNode?.data?.config ?? (0, callman_core_1.defaultScenarioNodeConfig)(type) ?? {};
+        const restored = sameNode ? (0, nodeConfig_js_1.restoreMasked)(node.config ?? {}, base) : (node.config ?? {});
+        const unwritable = (0, nodeConfig_js_1.findUnwritableValues)(restored, `${id}.config`);
+        if (unwritable.length > 0)
+            problems.push(...unwritable);
+        const normalized = (0, nodeConfig_js_1.normalizeNodeConfig)(type, restored);
+        warnings.push(...normalized.notes.map((note) => `${id}: ${note}`));
+        const missing = (0, nodeConfig_js_1.missingRequiredFields)(type, normalized.config, sameNode ? base : null);
+        if (missing.length > 0)
+            problems.push(`${id} (${type}) needs config.${missing.join(", config.")}`);
+        if (Object.keys(normalized.config).length > 0)
+            sent.set(id, normalized.config);
+        const config = (0, exports.deepMerge)(base, normalized.config);
         return {
-            id: ids[index],
+            id,
             type,
-            position: node.position ?? { x: 0, y: 0 },
-            data: { ...(node.label ? { label: node.label } : {}), config },
-            _positioned: Boolean(node.position),
+            label: node.label ?? sameNode?.data?.label ?? undefined,
+            position: node.position ?? sameNode?.position,
+            config,
+            // Label rules are enforced for what this call names or adds; a problem
+            // already in stored data only warns, so it never blocks an edit.
+            touched: node.label !== undefined || !sameNode || node.config !== undefined,
         };
     });
+    if (problems.length > 0) {
+        throw new errors_js_1.ToolInputError("SCENARIO_NODE_INVALID", `Fix these nodes: ${problems.join("; ")}. Masked values sent back unchanged keep the stored secret on update; otherwise pass real values or {{variables}}.`, { problems });
+    }
+    // Labels: generated when missing, unique across the whole scenario
+    // (nested bodies included), never reserved.
+    const taken = new Set();
+    for (const node of built) {
+        if (node.label)
+            taken.add(node.label);
+        for (const label of nestedLabels(node.config))
+            taken.add(label);
+    }
+    const counters = new Map();
+    for (const node of built) {
+        if (node.label)
+            continue;
+        const prefix = labelBase(node.type);
+        let n = counters.get(prefix) ?? 0;
+        let candidate;
+        do {
+            n += 1;
+            candidate = `${prefix}${n}`;
+        } while (taken.has(candidate));
+        counters.set(prefix, n);
+        node.label = candidate;
+        taken.add(candidate);
+    }
+    const seen = new Map();
+    const labelProblems = [];
+    const report = (message, touched) => {
+        if (touched)
+            labelProblems.push(message);
+        else
+            warnings.push(`Existing problem (not blocking): ${message}`);
+    };
+    for (const node of built) {
+        const label = node.label;
+        if ((0, callman_core_1.isReservedScenarioLabel)(label))
+            report(`"${label}" (${node.id}) is reserved — its output would be dropped`, node.touched);
+        const other = seen.get(label);
+        if (other)
+            report(`"${label}" is used by ${other.id} and ${node.id}`, node.touched || other.touched);
+        seen.set(label, { id: node.id, touched: node.touched });
+        for (const nested of nestedLabels(node.config)) {
+            const owner = seen.get(nested);
+            if (owner && owner.id !== node.id)
+                report(`"${nested}" is used by ${owner.id} and inside ${node.id}`, node.touched || owner.touched);
+        }
+        if (SHADOWING_LABELS.has(label) && node.touched)
+            warnings.push(`${node.id}: label "${label}" shadows a built-in root ({{${label}.…}}) — prefer another name`);
+    }
+    if (labelProblems.length > 0) {
+        throw new errors_js_1.ToolInputError("SCENARIO_LABEL_INVALID", `Labels must be unique and not reserved: ${labelProblems.join("; ")}.`);
+    }
     const edges = edgesInput.map((edge) => {
         for (const endpoint of [edge.source, edge.target]) {
             if (!idSet.has(endpoint))
                 throw new errors_js_1.ToolInputError("SCENARIO_EDGE_ENDPOINT_NOT_FOUND", `Edge references "${endpoint}" which is not a node id.`);
         }
-        return { id: edge.id ?? nextEdgeId(), source: edge.source, target: edge.target, ...(edge.type ? { type: edge.type } : {}) };
+        return { id: edge.id ?? nextEdgeId(), source: edge.source, target: edge.target, ...(edge.type && edge.type !== "default" ? { type: edge.type } : {}) };
     });
     // Layered positions for the nodes that have none: BFS from the sources.
     const incoming = new Map(ids.map((id) => [id, 0]));
@@ -103,38 +216,57 @@ const buildScenarioGraph = (nodesInput, edgesInput) => {
         }
     }
     const rowCounter = new Map();
-    const positioned = nodes.map((node) => {
-        if (node._positioned)
-            return node;
-        const layer = level.get(node.id) ?? 0;
-        const row = rowCounter.get(layer) ?? 0;
-        rowCounter.set(layer, row + 1);
-        return { ...node, position: { x: 80 + layer * 320, y: 80 + row * 170 } };
+    const nodes = built.map((node) => {
+        let position = node.position;
+        if (!position) {
+            const layer = level.get(node.id) ?? 0;
+            const row = rowCounter.get(layer) ?? 0;
+            rowCounter.set(layer, row + 1);
+            position = { x: 80 + layer * 320, y: 80 + row * 170 };
+        }
+        return { id: node.id, type: node.type, position, data: { label: node.label, config: node.config } };
     });
-    return {
-        nodes: positioned.map(({ _positioned, ...node }) => node),
-        edges,
-    };
+    return { nodes, edges, sent, warnings };
 };
 exports.buildScenarioGraph = buildScenarioGraph;
-const buildScenarioCreateBody = (input, folderId) => {
+// Environments: stored ids are kept by name so an edit does not orphan them;
+// a masked value sent back unchanged keeps the stored value.
+const buildEnvironments = (input, existing = []) => {
+    const nextEnvId = (0, ids_js_1.sequentialIds)("env", existing.map((environment) => environment.id));
+    return input.map((environment) => {
+        const stored = existing.find((entry) => entry.id === environment.id) ?? existing.find((entry) => entry.name.trim().toLowerCase() === environment.name.trim().toLowerCase());
+        const nextVarId = (0, ids_js_1.sequentialIds)("v", (stored?.variables ?? []).map((variable) => variable.id ?? ""));
+        const masked = [];
+        const variables = environment.variables.map((variable) => {
+            const previous = stored?.variables.find((entry) => entry.key === variable.key);
+            const value = (0, nodeConfig_js_1.restoreMasked)(variable.value, previous?.value);
+            if (value.startsWith("••••"))
+                masked.push(variable.key);
+            return { id: previous?.id ?? nextVarId(), key: variable.key, value, enabled: variable.enabled ?? previous?.enabled ?? true };
+        });
+        if (masked.length > 0) {
+            throw new errors_js_1.ToolInputError("MASKED_VALUE", `Environment "${environment.name}": masked values cannot be saved (${masked.join(", ")}). Send them back unchanged only for keys that already exist, or pass real values.`, { keys: masked });
+        }
+        return { id: environment.id ?? stored?.id ?? nextEnvId(), name: environment.name, variables };
+    });
+};
+exports.buildEnvironments = buildEnvironments;
+const buildScenarioCreateBody = (input, folderId, groupId) => {
     const graph = (0, exports.buildScenarioGraph)(input.nodes, input.edges);
-    const nextEnvId = (0, ids_js_1.sequentialIds)("env");
     return {
-        name: input.name.trim(),
-        ...(input.description ? { description: input.description } : {}),
-        ...(input.priority ? { priority: input.priority } : {}),
-        folderId,
-        nodes: graph.nodes,
-        edges: graph.edges,
-        environments: (input.environments ?? []).map((environment) => {
-            const nextVarId = (0, ids_js_1.sequentialIds)("v");
-            return {
-                id: environment.id ?? nextEnvId(),
-                name: environment.name,
-                variables: (0, requestShape_js_1.toRows)(environment.variables).map((row) => ({ id: nextVarId(), key: row.key, value: row.value, enabled: row.enabled ?? true })),
-            };
-        }),
+        graph,
+        body: {
+            name: input.name.trim(),
+            ...(input.description ? { description: input.description } : {}),
+            ...(input.priority ? { priority: input.priority } : {}),
+            folderId,
+            ...(groupId !== undefined ? { groupId } : {}),
+            nodes: graph.nodes,
+            edges: graph.edges,
+            environments: (0, exports.buildEnvironments)(input.environments ?? []),
+            ...(input.dataset !== undefined ? { dataset: input.dataset } : {}),
+            ...(input.dbSettings !== undefined ? { dbSettings: input.dbSettings } : {}),
+        },
     };
 };
 exports.buildScenarioCreateBody = buildScenarioCreateBody;

package/dist-cjs/domain/scenario/nodeConfig.js

@@ -0,0 +1,260 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.droppedPaths = exports.maskConfigInPlace = exports.restoreMasked = exports.findUnwritableValues = exports.missingRequiredFields = exports.normalizeNodeConfig = exports.translateRequestConfig = void 0;
+const callman_core_1 = require("callman-core");
+const mask_js_1 = require("../../lib/mask.js");
+// Node-config plumbing between the compact scenario a model writes and the
+// stored config the backend validates (callman://docs/scenario-nodes):
+//   * request shapes from the request tools ({ type: "bearer", token },
+//     body: {…}) are translated to the scenario form, so a request read with
+//     get_request can be dropped into a request node;
+//   * convenience fixes that the backend would otherwise reject or ignore
+//     (assertion rule ids, expert-mode conditions);
+//   * secrets masked IN PLACE for reading (same shape — writable back), and
+//     a masked value sent back unchanged restored from the stored config;
+//   * a diff of what was sent vs what the server stored, because the
+//     backend's node schemas silently strip unknown keys.
+const isRecord = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+let counter = 0;
+const newId = (prefix) => `${prefix}_${Date.now().toString(36)}${(counter++).toString(36)}`;
+// ── request / poll.request translation ────────────────────────────────
+const translateAuth = (auth) => {
+    if (!isRecord(auth))
+        return auth;
+    const type = auth.type === "apiKey" ? "apikey" : auth.type;
+    const out = { ...auth, type };
+    const move = (from, to) => {
+        if (from in out && !(to in out))
+            out[to] = out[from];
+        delete out[from];
+    };
+    if (type === "bearer")
+        move("token", "bearerToken");
+    if (type === "basic") {
+        move("username", "basicUsername");
+        move("password", "basicPassword");
+    }
+    if (type === "apikey") {
+        move("key", "apiKeyKey");
+        move("value", "apiKeyValue");
+        move("location", "apiKeyLocation");
+    }
+    if (type === "oauth2" && !isRecord(out.oauth2)) {
+        // Flat oauth2 fields (the request tools' shape) → nested, all ten keys.
+        const oauth2 = {};
+        for (const key of ["grantType", "tokenUrl", "clientId", "clientSecret", "scope", "username", "password", "refreshToken", "clientAuth", "audience"]) {
+            oauth2[key] = out[key] ?? (key === "grantType" ? "client_credentials" : key === "clientAuth" ? "body" : "");
+            delete out[key];
+        }
+        out.oauth2 = oauth2;
+    }
+    return out;
+};
+const RAW_LANGUAGES = new Set(["json", "xml", "text", "html"]);
+const translateBody = (body) => {
+    if (body === undefined)
+        return undefined;
+    if (body === null)
+        return { mode: "none" };
+    if (typeof body === "string") {
+        const state = (0, callman_core_1.inferBodyStateFromRaw)(body, []);
+        return { mode: "raw", raw: body, rawLanguage: state.rawLanguage ?? "text" };
+    }
+    if (isRecord(body) && typeof body.mode === "string") {
+        const out = { ...body };
+        if (out.mode === "json")
+            return { mode: "raw", raw: JSON.stringify(out.json ?? null, null, 2), rawLanguage: "json" };
+        if (out.mode === "raw" && typeof out.language === "string" && RAW_LANGUAGES.has(out.language) && out.rawLanguage === undefined) {
+            out.rawLanguage = out.language;
+            delete out.language;
+        }
+        if ((out.mode === "formdata" || out.mode === "urlencoded") && Array.isArray(out.entries) && out.formEntries === undefined) {
+            out.formEntries = out.entries;
+            delete out.entries;
+        }
+        return out;
+    }
+    // A bare JSON value — what get_request returns for JSON bodies.
+    return { mode: "raw", raw: JSON.stringify(body, null, 2), rawLanguage: "json" };
+};
+// get_request's `scripts: { preRequest, postResponse, tests }` → flat fields.
+const translateScripts = (config) => {
+    const scripts = config.scripts;
+    if (!isRecord(scripts))
+        return;
+    if (typeof scripts.preRequest === "string" && config.preRequestScript === undefined)
+        config.preRequestScript = scripts.preRequest;
+    if (typeof scripts.postResponse === "string" && config.postResponseScript === undefined)
+        config.postResponseScript = scripts.postResponse;
+    if (typeof scripts.tests === "string" && config.testsScript === undefined)
+        config.testsScript = scripts.tests;
+    delete config.scripts;
+};
+const translateRequestConfig = (config) => {
+    const out = { ...config };
+    if ("auth" in out)
+        out.auth = translateAuth(out.auth);
+    if ("body" in out)
+        out.body = translateBody(out.body);
+    translateScripts(out);
+    return out;
+};
+exports.translateRequestConfig = translateRequestConfig;
+// ── convenience fixes the backend would reject or ignore ──────────────
+const withRuleIds = (node) => {
+    if (!isRecord(node))
+        return node;
+    if (Array.isArray(node.children)) {
+        return { id: node.id ?? newId("g"), type: node.type ?? "group", ...node, children: node.children.map(withRuleIds) };
+    }
+    if ("left" in node && "operator" in node)
+        return { id: node.id ?? newId("r"), type: node.type ?? "rule", ...node };
+    return node;
+};
+const normalizeNodeConfig = (type, config) => {
+    const notes = [];
+    let out = { ...config };
+    if (type === "request")
+        out = (0, exports.translateRequestConfig)(out);
+    if (type === "poll" && isRecord(out.request))
+        out.request = (0, exports.translateRequestConfig)(out.request);
+    if (type === "condition" || type === "poll") {
+        const target = type === "poll" && isRecord(out.successCondition) ? { ...out.successCondition } : out;
+        if (typeof target.expertExpression === "string" && target.expertExpression.trim() && target.mode === undefined) {
+            target.mode = "expert";
+            notes.push("expertExpression given without mode — set mode: \"expert\" (builder mode ignores it)");
+        }
+        if (target.rootGroup !== undefined)
+            target.rootGroup = withRuleIds(target.rootGroup);
+        if (type === "poll" && isRecord(out.successCondition))
+            out.successCondition = target;
+    }
+    if (type === "assertion" && Array.isArray(out.checks)) {
+        out.checks = out.checks.map((check) => {
+            if (!isRecord(check))
+                return check;
+            const id = typeof check.id === "string" ? check.id : newId("c");
+            return { id, name: check.name ?? "", enabled: check.enabled ?? true, ...check, rule: withRuleIds(check.rule) };
+        });
+    }
+    return { config: out, notes };
+};
+exports.normalizeNodeConfig = normalizeNodeConfig;
+// ── what the model must supply (defaults are placeholders) ────────────
+const missingRequiredFields = (type, userConfig, base) => {
+    const has = (key) => {
+        const value = userConfig[key] ?? base?.[key];
+        return typeof value === "string" ? value.trim().length > 0 : Array.isArray(value) ? value.length > 0 : value !== undefined && value !== null;
+    };
+    const missing = [];
+    switch (type) {
+        case "request":
+            if (!has("url"))
+                missing.push("url");
+            break;
+        case "db":
+            // The default query is a placeholder (SELECT * FROM users …) — never run it by accident.
+            if (!(typeof userConfig.query === "string" && userConfig.query.trim()) && !(base && typeof base.query === "string" && base.query.trim()))
+                missing.push("query");
+            break;
+        case "ai":
+            if (!has("connectionId"))
+                missing.push("connectionId (list_connections type ai)");
+            break;
+        case "assertion":
+            if (!has("checks"))
+                missing.push("checks");
+            break;
+        default:
+            break;
+    }
+    return missing;
+};
+exports.missingRequiredFields = missingRequiredFields;
+// ── masked / clipped values ───────────────────────────────────────────
+const findUnwritableValues = (value, path = "config", out = []) => {
+    if (typeof value === "string" && (0, mask_js_1.isMasked)(value))
+        out.push(`${path} (masked ••••)`);
+    else if (Array.isArray(value))
+        value.forEach((item, index) => (0, exports.findUnwritableValues)(item, `${path}[${index}]`, out));
+    else if (isRecord(value)) {
+        if (value._truncated === true)
+            out.push(`${path} (clipped preview — read it with get_scenario node: <id>)`);
+        else
+            for (const [key, child] of Object.entries(value))
+                (0, exports.findUnwritableValues)(child, `${path}.${key}`, out);
+    }
+    return out;
+};
+exports.findUnwritableValues = findUnwritableValues;
+// A masked string equal to the mask of the stored value at the same path
+// means "keep what is stored".
+const restoreMasked = (value, stored) => {
+    if (typeof value === "string") {
+        return (0, mask_js_1.isMasked)(value) && typeof stored === "string" && stored && (0, mask_js_1.maskSecret)(stored) === value ? stored : value;
+    }
+    if (Array.isArray(value)) {
+        return value.map((item, index) => {
+            const storedItem = Array.isArray(stored)
+                ? (isRecord(item) && typeof item.key === "string" ? stored.find((entry) => isRecord(entry) && entry.key === item.key) : stored[index])
+                : undefined;
+            return (0, exports.restoreMasked)(item, storedItem);
+        });
+    }
+    if (isRecord(value)) {
+        return Object.fromEntries(Object.entries(value).map(([key, child]) => [key, (0, exports.restoreMasked)(child, isRecord(stored) ? stored[key] : undefined)]));
+    }
+    return value;
+};
+exports.restoreMasked = restoreMasked;
+// ── reading: mask secrets without changing the shape ─────────────────
+const SECRET_FIELDS = new Set([
+    "bearerToken",
+    "basicPassword",
+    "apiKeyValue",
+    "clientSecret",
+    "password",
+    "refreshToken",
+    "pfxBase64",
+    "keyPem",
+    "passphrase",
+    "secret",
+    "token",
+    "apiKey",
+]);
+const maskConfigInPlace = (value, keyName = "") => {
+    if (typeof value === "string")
+        return SECRET_FIELDS.has(keyName) && value && !value.startsWith("{{") ? (0, mask_js_1.maskSecret)(value) : value;
+    if (Array.isArray(value)) {
+        return value.map((item) => {
+            // Header rows: { key: "Authorization", value: "…" }.
+            if (isRecord(item) && typeof item.key === "string" && typeof item.value === "string" && (0, mask_js_1.isSensitiveHeader)(item.key) && item.value && !item.value.startsWith("{{")) {
+                return { ...item, value: (0, mask_js_1.maskSecret)(item.value) };
+            }
+            return (0, exports.maskConfigInPlace)(item);
+        });
+    }
+    if (isRecord(value))
+        return Object.fromEntries(Object.entries(value).map(([key, child]) => [key, (0, exports.maskConfigInPlace)(child, key)]));
+    return value;
+};
+exports.maskConfigInPlace = maskConfigInPlace;
+// ── sent vs stored ────────────────────────────────────────────────────
+// Keys present in what we sent but absent from what the server stored —
+// the backend's node schemas strip unknown keys without an error.
+const droppedPaths = (sent, stored, path = "") => {
+    if (!isRecord(sent))
+        return [];
+    if (!isRecord(stored))
+        return [];
+    const out = [];
+    for (const [key, value] of Object.entries(sent)) {
+        const here = path ? `${path}.${key}` : key;
+        if (!(key in stored))
+            out.push(here);
+        else if (isRecord(value))
+            out.push(...(0, exports.droppedPaths)(value, stored[key], here));
+    }
+    return out;
+};
+exports.droppedPaths = droppedPaths;