common-qa-mcp 0.3.0 → 0.4.1

package/dist/adapters/simplifyqa/mapper.js

@@ -13,6 +13,15 @@ export function pickArray(n, ...keys) {
     }
     return Array.isArray(n) ? n : [];
 }
+/** Hang `totalCount` off a mapped array as a side-band prop — SQA search responses expose it
+ *  at the top level as `totalCount` (with `total`/`totalRecords` as tolerant fallbacks). Undefined
+ *  when the raw response omits it (callers show `rows.length` as the total in that case). */
+export function withTotal(rows, raw) {
+    const t = raw?.totalCount ?? raw?.total ?? raw?.totalRecords;
+    if (typeof t === 'number')
+        rows.totalCount = t;
+    return rows;
+}
 export function str(n, ...keys) {
     if (n == null)
         return undefined;
@@ -33,6 +42,31 @@ export function numericId(id) {
     const m = id.match(/(\d+)/);
     return m ? m[1] : id;
 }
+/** Map raw `tcfn_version` rows → neutral `TcVersion[]`. Shared between TC (versions inlined on
+ *  the `/tm/testcase/getById` doc) and FN (versions come from `/tm/function/version/:id/:pid`).
+ *  `currentVersionId` stamps `isCurrent:true` on the matching entry — pass undefined if unknown. */
+export function toVersionEntries(rawVersions, currentVersionId) {
+    return (Array.isArray(rawVersions) ? rawVersions : [])
+        .map((v) => {
+        const vid = str(v, 'id', '_id');
+        if (!vid)
+            return null;
+        const name = str(v, 'name') ?? vid;
+        const entry = { id: vid, name };
+        if (typeof v?.updateVersion === 'number')
+            entry.updateVersion = v.updateVersion;
+        const rev = str(v, 'reviewApproveStatus');
+        if (rev)
+            entry.reviewApproveStatus = rev;
+        const ex = str(v, 'executionType');
+        if (ex)
+            entry.executionType = ex;
+        if (currentVersionId && vid === currentVersionId)
+            entry.isCurrent = true;
+        return entry;
+    })
+        .filter((v) => v !== null);
+}
 /** SQA priority is UPPERCASE on the wire; neutral is lowercase. Unknown → 'medium'. */
 export function mapPriority(p) {
     const s = typeof p === 'string' ? p.toLowerCase() : '';
@@ -47,19 +81,69 @@ export function mapPriority(p) {
 // Both use the same field names, so ONE mapper covers both. See adapter.ts
 // getTestCase for the read strategy (collection wins; inline is a fallback).
 // ---------------------------------------------------------------------------
+export const STEP_BLOCK_END_TYPES = new Set([
+    'ELSE', 'ELSE_IF', 'IF_END', 'FOR_END', 'WHILE', 'WHILE_END', 'ITERATOR_END',
+    'LOOP_ITERATION_END', 'FUNCTION_END',
+]);
+export const STEP_LOOP_START_TYPES = new Set([
+    'FOR_START', 'WHILE_START', 'ITERATOR_START', 'LOOP_ITERATION_START', 'DO',
+]);
+// SQA raw `stepType` → neutral Step.stepType + Step.controlFlow.kind. Enumerated from the
+// backend's own union (tcfn.service.js:2176 stepTypeMapping + validators). Everything not in
+// SIMPLE / CF_KINDS falls through as a plain automation step.
+const SIMPLE_STEP_KINDS = {
+    NORMAL_STATEMENT: 'web',
+    API: 'api',
+    COMPARE: 'compare',
+};
+const CF_KINDS = new Set([
+    'IF', 'ELSE', 'ELSE_IF', 'IF_END',
+    'WHILE_START', 'WHILE', 'WHILE_END',
+    'DO', 'DO_WHILE',
+    'FOR_START', 'FOR_END', 'LOOP',
+    'ITERATOR_START', 'ITERATOR_END',
+    'LOOP_ITERATION_START', 'LOOP_ITERATION_END',
+]);
+const SWITCH_KINDS = new Set([
+    'SWITCH_TO_API', 'SWITCH_TO_DB', 'SWITCH_TO_WEB', 'SWITCH_TO_MAINFRAME',
+    'SWITCH_TO_DESKTOP', 'SWITCH_TO_SAP', 'SWITCH_TO_IOS', 'SWITCH_TO_ANDROID',
+]);
+/** Squash a step's `recordedParam: { <paramId>: value }` map into a single readable cell
+ *  ("packageName=us.zoom, activity=..."). Names would be nicer than ids, but the id→name
+ *  resolution requires the project parameter dictionary — deferred; the raw id is unambiguous
+ *  and keeps this pure. */
+function formatRecordedParam(rp) {
+    if (!rp || typeof rp !== 'object')
+        return undefined;
+    const entries = Object.entries(rp).filter(([, v]) => v != null && v !== '');
+    if (!entries.length)
+        return undefined;
+    return entries.map(([k, v]) => `${k}=${String(v)}`).join(', ');
+}
 export function fromSqaStep(s, fallbackSeq) {
     const sid = str(s, 'id', '_id', 'stepId');
     const description = s?.description ?? '';
     const expectedResult = s?.expectedResult ?? undefined;
     const actionType = str(s, 'actionId', 'actionType') ?? '';
     const seq = typeof s?.seq === 'number' ? s.seq : fallbackSeq;
-    // SQA `executionType` is "MANUAL" for manual steps in a manual (or DUO) TC and "AUTOMATION"
-    // otherwise. Angular's step-card routing branches on 'manual' vs anything-else, so a manual
-    // step should really land as stepType:'manual' or the row renders as an empty automation card.
-    // ponytail: `Step['stepType']` on main does not yet include 'manual' — that addition is queued
-    // by the in-flight tc-edit branch. Until it lands, default to 'web' here (matches the Java
-    // toTestCase inline path's current behavior). Upgrade this line the day 'manual' is on the enum.
-    const stepType = 'web';
+    const rawStepType = String(s?.stepType ?? '').toUpperCase();
+    // Neutral stepType routing. Manual TCs have executionType:'MANUAL' at the STEP level — that's
+    // the only reliable signal for the neutral 'manual' bucket (validators show `executionType`
+    // is a per-step string). Otherwise SIMPLE_STEP_KINDS wins, then CF, then FUNCTION, then a
+    // safe automation fallback.
+    let stepType = 'web';
+    if (str(s, 'executionType')?.toUpperCase() === 'MANUAL')
+        stepType = 'manual';
+    else if (SIMPLE_STEP_KINDS[rawStepType])
+        stepType = SIMPLE_STEP_KINDS[rawStepType];
+    else if (rawStepType === 'FUNCTION')
+        stepType = 'function';
+    else if (rawStepType === 'FUNCTION_END')
+        stepType = 'function_end';
+    else if (CF_KINDS.has(rawStepType))
+        stepType = 'control_flow';
+    else if (SWITCH_KINDS.has(rawStepType))
+        stepType = 'switch';
     // Object linkage: SQA stores it as either scalar `objectId` OR nested `object.id`.
     // Preserving the FK is what lets tc_heal / object_update_locators find the shared object.
     let objectId = str(s, 'objectId');
@@ -78,6 +162,38 @@ export function fromSqaStep(s, fallbackSeq) {
     if (objectId && objectId.toLowerCase() !== 'null') {
         step.objectRef = { id: objectId, ...(objectName ? { name: objectName } : {}) };
     }
+    // Control-flow: keep the RAW SQA kind on controlFlow.kind so the renderer can label it exactly
+    // as the UI does. `conditions.ifstring` is the human-readable expression the SQA UI shows in the
+    // condition column — carry it into conditionText.
+    if (stepType === 'control_flow' || stepType === 'function_end') {
+        const conditionText = str(s?.conditions, 'ifstring');
+        step.controlFlow = {
+            kind: rawStepType === 'FUNCTION_END' ? 'FUNCTION_END' : rawStepType,
+            ...(conditionText ? { conditionText } : {}),
+            ...(typeof s?.loopDuration === 'number' ? { maxIterations: s.loopDuration } : {}),
+        };
+    }
+    // FUNCTION step — carry every field the ROUND-TRIP save + a human render need. Backend
+    // sends functionId as a number, fnVersionId as a string uuid; the neutral surface is string.
+    if (stepType === 'function') {
+        const fnId = str(s, 'functionId');
+        const fnVersion = str(s, 'fnVersionId');
+        const sharedProject = str(s, 'sharedFnProjectId');
+        const sharedName = str(s, 'sharedFnProjectName');
+        if (fnId) {
+            step.functionCall = {
+                testCaseId: fnId,
+                ...(fnVersion ? { versionId: fnVersion } : {}),
+                ...(sharedProject ? { sharedProjectId: sharedProject } : {}),
+                ...(sharedName ? { testCaseName: sharedName } : {}),
+            };
+        }
+    }
+    // Value column: prefer recordedParam summary (concrete values) → falls through to parameterIds
+    // which surface as `${name}` tokens in the description already.
+    const recordedSummary = formatRecordedParam(s?.recordedParam);
+    if (recordedSummary)
+        step.value = recordedSummary;
     return step;
 }
 // ---------------------------------------------------------------------------
@@ -112,6 +228,14 @@ export function toTestCase(doc) {
             rawSteps = stepsNode;
     }
     const steps = rawSteps.map((s, i) => fromSqaStep(s, i + 1));
+    // Versions: `/tm/testcase/getById` hangs a `versions[]` array on the doc (tcfn.service.js:1489),
+    // one entry per non-deleted tcfn_version. Current-version resolution mirrors the FE:
+    // `versionId` / `selectedVersionId` on the doc wins, else the doc's `versionsDetails.id`.
+    const currentVersionId = str(doc, 'versionId', 'selectedVersionId') ??
+        (doc?.versionsDetails && typeof doc.versionsDetails === 'object'
+            ? str(doc.versionsDetails, 'id', '_id', 'versionId')
+            : undefined);
+    const versions = toVersionEntries(Array.isArray(doc?.versions) ? doc.versions : [], currentVersionId);
     return {
         ...(id ? { id } : {}),
         title: str(doc, 'name', 'title') ?? '',
@@ -123,6 +247,8 @@ export function toTestCase(doc) {
         ...(userstoryId ? { storyRef: userstoryId } : {}),
         ...(moduleId ? { folderOrModule: moduleId } : {}),
         steps,
+        ...(versions.length ? { versions } : {}),
+        ...(currentVersionId ? { currentVersionId } : {}),
     };
 }
 /** Overwrite `tc.steps` with the mapped collection-endpoint rows when non-empty. */
@@ -132,18 +258,57 @@ export function applyCollectionSteps(tc, rows) {
     const mapped = rows.map((s, i) => fromSqaStep(s, i + 1));
     return { ...tc, steps: mapped };
 }
+// ---------------------------------------------------------------------------
+// Functions (reusable). Same `tcfnObj` collection as TCs — type='FN' instead of 'TC'.
+// Payload shape overlaps with TCs (id/code/name/description/executionType/status), plus
+// `fnType` (WEB/API/ANDROID/IOS) in place of `tcType`.
+// ---------------------------------------------------------------------------
+export function toFunctionSummary(row) {
+    const id = str(row, 'id', '_id', 'functionId') ?? '';
+    const code = str(row, 'code');
+    const name = str(row, 'name', 'title') ?? '';
+    const description = str(row, 'description');
+    const fnType = str(row, 'fnType', 'tcType');
+    const executionType = str(row, 'executionType');
+    const status = str(row, 'reviewApproveStatus', 'status');
+    const stepCount = typeof row?.stepCount === 'number' ? row.stepCount : undefined;
+    return {
+        id,
+        ...(code ? { code } : {}),
+        name,
+        ...(description ? { description } : {}),
+        ...(fnType ? { fnType } : {}),
+        ...(executionType ? { executionType } : {}),
+        ...(status ? { status } : {}),
+        ...(stepCount !== undefined ? { stepCount } : {}),
+    };
+}
+/** Full function doc → neutral QaFunction. Steps are attached separately by the adapter (fetched
+ *  from /tm/function/steps, same collection endpoint TCs use — just type='FN'). */
+export function toFunction(row) {
+    const summary = toFunctionSummary(row);
+    return { ...summary, steps: [] };
+}
 export function toTcSummary(row) {
     const id = str(row, 'id', '_id', 'testcaseId') ?? '';
+    const code = str(row, 'code');
     const title = str(row, 'name', 'title') ?? '';
     const priority = (str(row, 'priority') ?? 'medium').toLowerCase();
     const status = str(row, 'status');
     const stepCount = typeof row?.stepCount === 'number' ? row.stepCount : undefined;
+    const technologyType = str(row, 'tcType');
+    const executionType = str(row, 'executionType');
+    const obsolete = typeof row?.obsolete === 'boolean' ? row.obsolete : undefined;
     return {
         id,
+        ...(code ? { code } : {}),
         title,
         priority,
         ...(status ? { status } : {}),
         ...(stepCount !== undefined ? { stepCount } : {}),
+        ...(technologyType ? { technologyType } : {}),
+        ...(executionType ? { executionType } : {}),
+        ...(obsolete !== undefined ? { obsolete } : {}),
     };
 }
 // ---------------------------------------------------------------------------
@@ -153,7 +318,13 @@ export function toSuiteSummary(row) {
     const id = str(row, 'id', '_id', 'suiteId') ?? '';
     const name = str(row, 'name', 'suiteName') ?? '';
     const memberCount = Array.isArray(row?.testCases) ? row.testCases.length : undefined;
-    return { id, name, ...(memberCount !== undefined ? { memberCount } : {}) };
+    const suiteType = str(row, 'suiteType');
+    return {
+        id,
+        name,
+        ...(memberCount !== undefined ? { memberCount } : {}),
+        ...(suiteType ? { suiteType } : {}),
+    };
 }
 export function toSuite(doc) {
     const id = str(doc, 'id', '_id', 'suiteId');
@@ -188,6 +359,56 @@ export function toStorySummary(row) {
         ...(priority ? { priority } : {}),
     };
 }
+export function toDefectSummary(row) {
+    const id = str(row, 'id', '_id') ?? '';
+    const code = str(row, 'code');
+    const title = str(row, 'name', 'title') ?? '';
+    const state = str(row, 'state', 'status');
+    const severity = str(row, 'severity');
+    const priority = str(row, 'priority');
+    // `ownerId` is an ARRAY on the defect row (a defect can have several assignees) — see
+    // defect-interface.ts `ownerId: number[]` — unlike the single-value `ownerId` on stories/testcases.
+    const assignedTo = Array.isArray(row?.ownerId)
+        ? row.ownerId.map((v) => String(v ?? '')).filter((v) => v.length > 0)
+        : undefined;
+    const tcIds = Array.isArray(row?.selectedTestCase)
+        ? row.selectedTestCase
+            .map((tc) => (typeof tc === 'object' ? str(tc, 'testcaseId') : String(tc ?? '')))
+            .filter((v) => !!v)
+        : undefined;
+    return {
+        id,
+        ...(code ? { code } : {}),
+        title,
+        ...(state ? { state } : {}),
+        ...(severity ? { severity } : {}),
+        ...(priority ? { priority } : {}),
+        ...(assignedTo?.length ? { assignedTo } : {}),
+        ...(tcIds?.length ? { tcIds } : {}),
+    };
+}
+/** Maps a `/pm/task/search` row (see `Itask` in sqa-ui) to the neutral shape. `ownerId` is an array
+ *  on the task row, same as on a defect. */
+export function toTaskSummary(row) {
+    const id = str(row, 'id', '_id') ?? '';
+    const code = str(row, 'code');
+    const title = str(row, 'name', 'title') ?? '';
+    const state = str(row, 'state', 'status');
+    const priority = str(row, 'priority');
+    const assignedTo = Array.isArray(row?.ownerId)
+        ? row.ownerId.map((v) => String(v ?? '')).filter((v) => v.length > 0)
+        : undefined;
+    const defectId = typeof row?.defectId === 'number' && row.defectId > 0 ? String(row.defectId) : undefined;
+    return {
+        id,
+        ...(code ? { code } : {}),
+        title,
+        ...(state ? { state } : {}),
+        ...(priority ? { priority } : {}),
+        ...(assignedTo?.length ? { assignedTo } : {}),
+        ...(defectId ? { defectId } : {}),
+    };
+}
 export function toStory(doc) {
     const base = toStorySummary(doc);
     const description = str(doc, 'description', 'storyDescription');
@@ -208,6 +429,70 @@ export function toStory(doc) {
     };
 }
 // ---------------------------------------------------------------------------
+// Epics (`pm/epic`) and features (`pm/feature`). Business keys come back as
+// `code` (EP_XXX / FT_XXX); numeric doc id is `id` (with `_id` as fallback).
+// ---------------------------------------------------------------------------
+export function toEpicSummary(row) {
+    const id = str(row, 'id', '_id', 'epicId') ?? '';
+    const key = str(row, 'code', 'key');
+    const name = str(row, 'name', 'epicName') ?? '';
+    const state = str(row, 'state', 'status');
+    return {
+        id,
+        ...(key ? { key } : {}),
+        name,
+        ...(state ? { state } : {}),
+    };
+}
+export function toEpic(doc) {
+    const base = toEpicSummary(doc);
+    const description = str(doc, 'description');
+    const plannedStartDate = str(doc, 'plannedStartDate');
+    const plannedEndDate = str(doc, 'plannedEndDate');
+    const rawEffort = doc?.estimatedEffort;
+    const rawOwner = doc?.ownerId;
+    return {
+        ...base,
+        ...(description ? { description } : {}),
+        ...(typeof rawEffort === 'number' ? { estimatedEffort: rawEffort } : {}),
+        ...(typeof rawOwner === 'number' ? { ownerId: rawOwner } : {}),
+        ...(plannedStartDate ? { plannedStartDate } : {}),
+        ...(plannedEndDate ? { plannedEndDate } : {}),
+    };
+}
+export function toFeatureSummary(row) {
+    const id = str(row, 'id', '_id', 'featureId') ?? '';
+    const key = str(row, 'code', 'key');
+    const name = str(row, 'name', 'featureName') ?? '';
+    const state = str(row, 'state', 'status');
+    const priority = str(row, 'priority');
+    const epicId = str(row, 'epicId');
+    return {
+        id,
+        ...(key ? { key } : {}),
+        name,
+        ...(state ? { state } : {}),
+        ...(priority ? { priority } : {}),
+        ...(epicId ? { epicId } : {}),
+    };
+}
+export function toFeature(doc) {
+    const base = toFeatureSummary(doc);
+    const description = str(doc, 'description');
+    const plannedStartDate = str(doc, 'plannedStartDate');
+    const plannedEndDate = str(doc, 'plannedEndDate');
+    const rawEffort = doc?.estimatedEffort;
+    const rawOwner = doc?.ownerId;
+    return {
+        ...base,
+        ...(description ? { description } : {}),
+        ...(typeof rawEffort === 'number' ? { estimatedEffort: rawEffort } : {}),
+        ...(typeof rawOwner === 'number' ? { ownerId: rawOwner } : {}),
+        ...(plannedStartDate ? { plannedStartDate } : {}),
+        ...(plannedEndDate ? { plannedEndDate } : {}),
+    };
+}
+// ---------------------------------------------------------------------------
 // Modules, releases, sprints.
 // ---------------------------------------------------------------------------
 export function toModuleSummary(row) {
@@ -264,7 +549,7 @@ export function toObject(doc) {
         value: String(a.value),
         ...(a.unique === true ? { unique: true } : {}),
     }));
-    const name = str(doc, 'description', 'disname', 'placeholder') ?? '';
+    const name = str(doc, 'disname', 'description', 'placeholder') ?? '';
     const objectType = str(doc, 'technology');
     return {
         ...(id ? { id } : {}),
@@ -307,19 +592,50 @@ export function paramDefault(name, data, stepValue) {
         return String(data[name] ?? '');
     return stepValue ?? '';
 }
+/** Neutral Step.stepType → SQA `technologyType` on the step + `tcType` on the TC.
+ *  Exported so the adapter's per-step resolver keys the action catalog by the same technology
+ *  labels the mapper writes into the step. */
+export const TECH_BY_STEPTYPE = {
+    web: 'WEB',
+    android: 'ANDROID',
+    api: 'API',
+    database: 'DATABASE',
+    mainframe: 'MAINFRAME',
+};
+/** Pick the tcType from the first step whose stepType we recognize as an automation technology.
+ *  Falls back to WEB — matches the SQA UI's default when the user starts a fresh automation TC. */
+export function deriveTcType(tc) {
+    for (const s of tc.steps ?? []) {
+        const tech = TECH_BY_STEPTYPE[s.stepType];
+        if (tech)
+            return tech;
+    }
+    return 'WEB';
+}
+/** SQA-empty `mailersList` shape — the frontend and joi validator expect the three arrays, not
+ *  a bare `{}`. Verified against the real create payload for TC-584. */
+const EMPTY_MAILERS = { users: [], nonUsers: [], groups: [] };
 /**
- * Assemble the `testcaseObj` payload for POST/PUT /tm/testcase (multipart). Mirrors Java's
- * `buildTestcasePayload` exactly on wire shape:
+ * Assemble the `testcaseObj` payload for POST/PUT /tm/testcase (multipart). Branches on
+ * `tc.category`: manual → `steps.manualSteps` (legacy behavior), automated → `steps.automationSteps`
+ * with resolved actionId/objectId/parameterIds. See `buildManualPayload` and
+ * `buildAutomationPayload` below for the per-branch shapes; both share the wrapper.
+ */
+export function buildTestcasePayload(inputs) {
+    return inputs.tc.category === 'automated'
+        ? buildAutomationPayload(inputs)
+        : buildManualPayload(inputs);
+}
+/**
+ * Manual TC payload. Mirrors Java's `buildTestcasePayload` exactly on wire shape:
  *   - `tcfnObj` — TC-level meta. `deleted` is required on UPDATE and rejected on CREATE.
  *   - `versionsDetails` — a minimal `{name:'v1.0', id:''}` stub matches what the SQA UI sends
  *     for a fresh TC; UPDATE also carries `deleted:false` because the validator requires it.
- *   - `steps.manualSteps` — one entry per neutral step; `automationSteps` is emitted empty
- *     because this common-mcp save is the manual-authoring flow (agent handles automation).
- *   - Every step gets `parameterIds[]` for the `${name}` tokens in its description, so the UI's
- *     ID-based dropdown lookup resolves them.
+ *   - `steps.manualSteps` — one entry per neutral step; `automationSteps` is emitted empty.
+ *   - Every step gets `parameterIds[]` for the `${name}` tokens in its description.
  */
-export function buildTestcasePayload(inputs) {
-    const { projectId, moduleId, userstoryId, existingId, tc, paramIdByName, operation } = inputs;
+function buildManualPayload(inputs) {
+    const { projectId, moduleId, userstoryId, existingId, tc, paramIdByName } = inputs;
     const tcfnObj = {
         ...(existingId ? { id: Number.parseInt(existingId, 10) } : {}),
         name: tc.title ?? '',
@@ -354,20 +670,153 @@ export function buildTestcasePayload(inputs) {
             executionType: 'MANUAL',
         };
         const paramIds = [];
+        const recordedParam = {};
         for (const name of extractParamNames(desc)) {
             const id = paramIdByName.get(name);
-            if (id != null)
-                paramIds.push(id);
+            if (id == null)
+                continue;
+            paramIds.push(id);
+            recordedParam[String(id)] = paramDefault(name, tc.data, undefined);
         }
-        if (paramIds.length > 0)
+        if (paramIds.length > 0) {
             step['parameterIds'] = paramIds;
+            step['recordedParam'] = recordedParam;
+        }
         manualSteps.push(step);
     });
     return {
         tcfnObj,
         versionsDetails,
         steps: { automationSteps: [], manualSteps },
-        operation,
+        operation: 'TC',
+        type: 'TC',
+    };
+}
+/**
+ * Automation TC payload. Mirrors the shape observed on a saved SQA automation TC (TC-584, WEB +
+ * ANDROID validation samples):
+ *   - `tcfnObj.executionType: 'AUTOMATION'` + `originalExecutinType: 'AUTOMATION'`.
+ *   - `tcfnObj.tcType` derived from the first automation step's `stepType` (web / android / …).
+ *   - `tcfnObj.executionPlatform` — WEB defaults to Chrome server-side (omitted here), non-WEB
+ *     REQUIRES `tc.executionPlatform` from the caller (device serial + name).
+ *   - `steps.automationSteps[]` — one entry per neutral step. Each carries the resolved
+ *     `actionId` (numeric FK to the SQA `action` collection) + `objectId` (numeric FK to the
+ *     shared `object` collection, or null when the action doesn't need one) + `parameterIds` +
+ *     `recordedParam:{<id>:value}` (drives the default iteration on save).
+ *   - Always-present step defaults (`conditions`, `loop`, `stepLevelActions`, `attachments`)
+ *     are emitted every time — the joi validator + backend read these unconditionally on
+ *     execution, and the sample confirms they're present on simple straight-line steps too.
+ *
+ * Straight-line only in this cut — FUNCTION / IF / FOR / WHILE / API / SWITCH are ponytail-
+ * deferred to a follow-up (need a real control-flow sample to validate the `conditions.children[]`
+ * shape end-to-end).
+ */
+function buildAutomationPayload(inputs) {
+    const { projectId, moduleId, userstoryId, existingId, tc, paramIdByName, stepResolutions } = inputs;
+    const tcType = deriveTcType(tc);
+    // WEB: backend auto-defaults executionPlatform to Chrome (tcfn.service.js:206-213), so omit
+    // when the caller didn't supply one. Non-WEB: refuse the save early rather than land a broken
+    // TC — the backend doesn't default a real device for us.
+    if (tcType !== 'WEB' && !tc.executionPlatform) {
+        throw new Error(`Automation TC "${tc.title}" needs \`executionPlatform\` for tcType=${tcType} — set ` +
+            `tc.executionPlatform:{id:<deviceSerial>, name, technologyType:'${tcType}', type:'REAL_DEVICE'|'CLOUD_DEVICE'}. ` +
+            `For Android, call android_list_devices to see the available devices.`);
+    }
+    const tcfnObj = {
+        ...(existingId ? { id: Number.parseInt(existingId, 10) } : {}),
+        name: tc.title ?? '',
+        projectId,
+        moduleId,
+        ...(userstoryId != null ? { userstoryId } : {}),
+        obsolete: false,
+        ...(existingId ? { deleted: false } : {}),
+        tcType,
+        executionType: 'AUTOMATION',
+        originalExecutinType: 'AUTOMATION',
+        customFields: {},
+        mailersList: EMPTY_MAILERS,
+        suiteId: [],
+        defectId: [],
+        tags: [],
+        reviewApproveStatus: '',
+        ...(tc.executionPlatform ? { executionPlatform: tc.executionPlatform } : {}),
+        ...(tc.description ? { description: tc.description } : {}),
+        ...(tc.preconditions ? { prerequisite: tc.preconditions } : {}),
+    };
+    const versionsDetails = {
+        name: 'v1.0',
+        id: '',
+        syncONOFF: '',
+        executionType: 'AUTOMATION',
+        functionProjectIds: [projectId],
+        ...(existingId ? { deleted: false } : {}),
+    };
+    const automationSteps = [];
+    const steps = Array.isArray(tc.steps) ? tc.steps : [];
+    steps.forEach((s, i) => {
+        const desc = s.description ?? '';
+        const technologyType = TECH_BY_STEPTYPE[s.stepType] ?? tcType;
+        const resolution = stepResolutions?.[i];
+        if (!resolution) {
+            throw new Error(`Automation TC "${tc.title}" step ${i + 1}: missing action resolution — the adapter did ` +
+                'not resolve `actionId` for this step. Check that the neutral Step.actionType maps to a ' +
+                'known SQA action for this technology.');
+        }
+        // parameterIds: union of description ${tokens} + keys of step.recordedParam. `recordedParam`
+        // on the wire is keyed by NUMERIC paramId (JSON keys → strings), NOT by name.
+        const paramIds = [];
+        const recordedParamOut = {};
+        const seen = new Set();
+        const addParam = (name, value) => {
+            if (seen.has(name))
+                return;
+            seen.add(name);
+            const id = paramIdByName.get(name);
+            if (id == null)
+                return;
+            paramIds.push(id);
+            if (value !== undefined)
+                recordedParamOut[String(id)] = value;
+        };
+        for (const name of extractParamNames(desc))
+            addParam(name, tc.data?.[name] ?? s.value);
+        if (s.recordedParam) {
+            for (const [name, value] of Object.entries(s.recordedParam))
+                addParam(name, value);
+        }
+        const step = {
+            projectId,
+            moduleId,
+            type: 'TC',
+            stepType: 'NORMAL_STATEMENT',
+            seq: i + 1,
+            description: desc,
+            expectedResult: s.expectedResult ?? '',
+            executionType: 'AUTOMATION',
+            technologyType,
+            actionId: resolution.actionId,
+            objectId: resolution.objectId,
+            parameterIds: paramIds,
+            objectParameterIds: [],
+            recordedParam: recordedParamOut,
+            attachments: [],
+            conditions: { ifstring: '', children: [] },
+            loop: { loopType: 'for', loopIteration: null },
+            stepLevelActions: {
+                skip: s.flags?.skip ?? false,
+                captureScreenshot: s.flags?.screenshot ?? false,
+                continueOnFailure: s.flags?.continueOnFailure ?? false,
+                skippedReport: false,
+            },
+            ...(technologyType === 'WEB' ? { browserType: s.browserType ?? 'CHROME' } : {}),
+        };
+        automationSteps.push(step);
+    });
+    return {
+        tcfnObj,
+        versionsDetails,
+        steps: { automationSteps, manualSteps: [] },
+        operation: 'TC',
         type: 'TC',
     };
 }