common-qa-mcp 0.8.0 → 0.9.0

package/dist/adapters/simplifyqa/mapper.d.ts

@@ -70,8 +70,8 @@ export type BuildTestcasePayloadInputs = {
      *  `objectId` the adapter resolved before this call. `objectId` is null when the action does
      *  not need one. Ignored on manual saves. */
     stepResolutions?: Array<{
-        actionId: number;
-        objectId: number | null;
+        actionId: number | null;
+        objectId: number | null | undefined;
     }>;
 };
 /** Neutral Step.stepType → SQA `technologyType` on the step + `tcType` on the TC.

package/dist/adapters/simplifyqa/mapper.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"mapper.d.ts","sourceRoot":"","sources":["../../../src/adapters/simplifyqa/mapper.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"mapper.d.ts","sourceRoot":"","sources":["../../../src/adapters/simplifyqa/mapper.ts"],"names":[],"mappings":"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"}

package/dist/adapters/simplifyqa/mapper.js

@@ -109,6 +109,32 @@ 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',
 ]);
+/** Round-trip whitelist: raw backend fields we preserve verbatim on the neutral Step so save
+ *  re-emits control-flow / function / switch / api structure intact. Subset of the backend's
+ *  step joi allow-list (testcaseValidator.js:244-306) MINUS fields the mapper always computes
+ *  fresh (id, parentId, versionId, seq, actionId, objectId, description, expectedResult,
+ *  technologyType, projectId, moduleId, type, deleted, recordedParam, parameterIds,
+ *  objectParameterIds, browserType, stepLevelActions). Duplicated (not imported from adapter.ts)
+ *  to avoid a circular import — mapper is a leaf module. */
+const STEP_ROUND_TRIP_KEYS = [
+    'sharedFnProjectId', 'apiData', 'lastActiveTab', 'userstoryId',
+    'stepType', 'functionId', 'fnVersionId', 'sharedFnProjectName',
+    'parameterizedParamIds', 'attachments', 'compareFiles', 'compareFileType',
+    'deviceId', 'ignoreObject', 'captureScreenshot', 'screenshotEnabled',
+    'conditions', 'skipParamInReport', 'paramLoopduration', 'showGroups',
+    'isConditional', 'if', 'else', 'loop', 'isLoop', 'loopType', 'startFor', 'endFor',
+    'loopDuration', 'switchToAndroidData', 'switchToIOSData',
+    'isDebug', 'manualStepsTopreview', 'isMigrated', 'customFields',
+];
+function pickRoundTrip(s) {
+    const out = {};
+    if (!s || typeof s !== 'object')
+        return out;
+    for (const k of STEP_ROUND_TRIP_KEYS)
+        if (s[k] !== undefined)
+            out[k] = s[k];
+    return out;
+}
 /** 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
@@ -152,6 +178,29 @@ export function fromSqaStep(s, fallbackSeq) {
         objectId = str(s.object, 'id');
     }
     const objectName = s?.object && typeof s.object === 'object' ? str(s.object, 'name') : undefined;
+    // ponytail: preserve backend parameterIds so round-trip save doesn't wipe FK linkages that
+    // weren't derived from description ${tokens} (e.g. a "Go to URL" step with parameterIds:[841]
+    // even though the description has no token).
+    const sourceParameterIds = Array.isArray(s?.parameterIds)
+        ? s.parameterIds.filter((n) => typeof n === 'number' && Number.isFinite(n))
+        : [];
+    const sourceObjectParameterIds = Array.isArray(s?.objectParameterIds)
+        ? s.objectParameterIds.filter((n) => typeof n === 'number' && Number.isFinite(n))
+        : [];
+    // ponytail: preserve backend recordedParam as-is (id-keyed) so a save that doesn't touch values
+    // re-emits them intact. LLM patches via Step.recordedParam (name-keyed) override at save time.
+    const sourceRecordedParam = {};
+    if (s?.recordedParam && typeof s.recordedParam === 'object') {
+        for (const [k, v] of Object.entries(s.recordedParam)) {
+            if (typeof v === 'string')
+                sourceRecordedParam[k] = v;
+            else if (typeof v === 'number' || typeof v === 'boolean')
+                sourceRecordedParam[k] = String(v);
+        }
+    }
+    // ponytail: preserve every backend field that's on the joi allow-list but that the mapper
+    // doesn't recompute. This is what makes IF/FOR/WHILE/FUNCTION/SWITCH/API steps round-trip.
+    const sourceRaw = pickRoundTrip(s);
     const step = {
         n: seq,
         description,
@@ -159,6 +208,10 @@ export function fromSqaStep(s, fallbackSeq) {
         stepType,
         ...(sid ? { sourceId: sid } : {}),
         ...(expectedResult ? { expectedResult } : {}),
+        ...(sourceParameterIds.length ? { sourceParameterIds } : {}),
+        ...(sourceObjectParameterIds.length ? { sourceObjectParameterIds } : {}),
+        ...(Object.keys(sourceRecordedParam).length ? { sourceRecordedParam } : {}),
+        ...(Object.keys(sourceRaw).length ? { sourceRaw } : {}),
     };
     if (objectId && objectId.toLowerCase() !== 'null') {
         step.objectRef = { id: objectId, ...(objectName ? { name: objectName } : {}) };
@@ -252,6 +305,7 @@ export function toTestCase(doc) {
         steps,
         ...(versions.length ? { versions } : {}),
         ...(currentVersionId ? { currentVersionId } : {}),
+        ...(typeof doc?.updateVersion === 'number' ? { updateVersion: doc.updateVersion } : {}),
     };
 }
 /** Overwrite `tc.steps` with the mapped collection-endpoint rows when non-empty. */
@@ -670,6 +724,17 @@ export function deriveTcType(tc) {
 /** 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: [] };
+/** Locate the version entry the neutral TestCase currently points at, so update payloads carry
+ *  the REAL versionId (not `''`, which the backend interprets as "create a new version" —
+ *  see tcfn.service.js:233 — and produces the empty-steps-after-save symptom). Returns an empty
+ *  object when unresolved; callers then fall back to `id:''` (correct for CREATE). */
+function currentVersionFor(tc) {
+    const id = tc.currentVersionId;
+    if (!id || !Array.isArray(tc.versions))
+        return {};
+    const v = tc.versions.find((entry) => entry.id === id);
+    return v ? { id: v.id, name: v.name, ...(typeof v.updateVersion === 'number' ? { updateVersion: v.updateVersion } : {}) } : {};
+}
 /**
  * Assemble the `testcaseObj` payload for POST/PUT /tm/testcase (multipart). Branches on
  * `tc.category`: manual → `steps.manualSteps` (legacy behavior), automated → `steps.automationSteps`
@@ -691,30 +756,65 @@ export function buildTestcasePayload(inputs) {
  */
 function buildManualPayload(inputs) {
     const { projectId, moduleId, userstoryId, existingId, tc, paramIdByName } = inputs;
+    // ponytail: emit the same field set as the SQA UI payload, always — validators + $set on the
+    // backend depend on presence, even for empty defaults. Loader-mutator-saver semantics.
     const tcfnObj = {
         ...(existingId ? { id: Number.parseInt(existingId, 10) } : {}),
         name: tc.title ?? '',
+        userstoryId: userstoryId ?? null,
+        defectId: [],
+        suiteId: [],
+        description: tc.description ?? '',
         projectId,
-        moduleId,
-        ...(userstoryId != null ? { userstoryId } : {}),
-        obsolete: false,
-        ...(existingId ? { deleted: false } : {}),
         tcType: 'WEB',
         executionType: 'MANUAL',
+        obsolete: false,
+        linkedIssues: [],
+        moduleId,
+        prerequisite: tc.preconditions ?? '',
         customFields: {},
-        ...(tc.description ? { description: tc.description } : {}),
-        ...(tc.preconditions ? { prerequisite: tc.preconditions } : {}),
+        tags: [],
+        mailersList: EMPTY_MAILERS,
+        updateVersion: tc.updateVersion ?? 0,
+        ...(existingId ? { deleted: false } : {}),
     };
+    // On UPDATE, use the CURRENT version's real id/name/updateVersion so the backend updates
+    // that version row instead of minting a new one (empty `id` triggers create at tcfn.service.js:233).
+    const curVer = existingId ? currentVersionFor(tc) : {};
     const versionsDetails = {
-        name: 'v1.0',
-        id: '',
+        name: curVer.name ?? 'v1.0',
+        id: curVer.id ?? '',
+        syncONOFF: '',
+        manualStepsTopreview: false,
+        updateVersion: curVer.updateVersion ?? 0,
+        executionType: 'MANUAL',
+        reviewApproveStatus: '',
+        functionProjectIds: [projectId],
         ...(existingId ? { deleted: false } : {}),
     };
     const manualSteps = [];
     const steps = Array.isArray(tc.steps) ? tc.steps : [];
     steps.forEach((s, i) => {
         const desc = s.description ?? '';
+        const paramIds = [];
+        const recordedParam = {};
+        for (const name of extractParamNames(desc)) {
+            const id = paramIdByName.get(name);
+            if (id == null)
+                continue;
+            paramIds.push(id);
+            recordedParam[String(id)] = paramDefault(name, tc.data, undefined);
+        }
         const step = {
+            deleted: false,
+            // ponytail: pass through the backend step uuid on round-trip. Missing `id` sends every step
+            // down the backend's CREATE branch (tcfn.service.js:355), which mints a fresh uuid and
+            // orphans the original row — duplication instead of update.
+            ...(s.sourceId ? { id: s.sourceId } : {}),
+            // ponytail: same rationale as buildAutomationPayload — parentId + versionId are part of the
+            // update filter at tcfn.service.js:406; omitting them causes the upsert to insert an orphan.
+            ...(existingId ? { parentId: Number.parseInt(existingId, 10) } : {}),
+            ...(existingId && curVer.id ? { versionId: curVer.id } : {}),
             projectId,
             moduleId,
             type: 'TC',
@@ -723,20 +823,11 @@ function buildManualPayload(inputs) {
             description: desc,
             expectedResult: s.expectedResult ?? '',
             executionType: 'MANUAL',
+            // ponytail: always emit — matches UI payload shape. UI sends `[]`/`{}` on every step, backend
+            // joi validators + $set semantics assume presence.
+            parameterIds: paramIds,
+            recordedParam,
         };
-        const paramIds = [];
-        const recordedParam = {};
-        for (const name of extractParamNames(desc)) {
-            const id = paramIdByName.get(name);
-            if (id == null)
-                continue;
-            paramIds.push(id);
-            recordedParam[String(id)] = paramDefault(name, tc.data, undefined);
-        }
-        if (paramIds.length > 0) {
-            step['parameterIds'] = paramIds;
-            step['recordedParam'] = recordedParam;
-        }
         manualSteps.push(step);
     });
     return {
@@ -777,32 +868,42 @@ function buildAutomationPayload(inputs) {
             `tc.executionPlatform:{id:<deviceSerial>, name, technologyType:'${tcType}', type:'REAL_DEVICE'|'CLOUD_DEVICE'}. ` +
             `For Android, call mobile_list_devices to see the available devices.`);
     }
+    // ponytail: mirror the real UI payload field-for-field (see the working PUT captured on 2026-09-17
+    // for TC-635). Loader-mutator-saver semantics — always emit, empty defaults included.
     const tcfnObj = {
         ...(existingId ? { id: Number.parseInt(existingId, 10) } : {}),
         name: tc.title ?? '',
+        userstoryId: userstoryId ?? null,
+        defectId: [],
+        suiteId: [],
+        description: tc.description ?? '',
         projectId,
-        moduleId,
-        ...(userstoryId != null ? { userstoryId } : {}),
-        obsolete: false,
-        ...(existingId ? { deleted: false } : {}),
         tcType,
         executionType: 'AUTOMATION',
-        originalExecutinType: 'AUTOMATION',
+        obsolete: false,
+        linkedIssues: [],
+        moduleId,
+        prerequisite: tc.preconditions ?? '',
         customFields: {},
-        mailersList: EMPTY_MAILERS,
-        suiteId: [],
-        defectId: [],
         tags: [],
-        reviewApproveStatus: '',
+        mailersList: EMPTY_MAILERS,
+        originalExecutinType: 'AUTOMATION',
+        updateVersion: tc.updateVersion ?? 0,
+        ...(existingId ? { deleted: false } : {}),
         ...(tc.executionPlatform ? { executionPlatform: tc.executionPlatform } : {}),
-        ...(tc.description ? { description: tc.description } : {}),
-        ...(tc.preconditions ? { prerequisite: tc.preconditions } : {}),
     };
+    // On UPDATE, use the CURRENT version's real id/name/updateVersion so the backend updates
+    // that version row instead of minting a new one (empty `id` triggers create at tcfn.service.js:233,
+    // which orphans all saved steps under a fresh version and leaves the UI's view empty).
+    const curVer = existingId ? currentVersionFor(tc) : {};
     const versionsDetails = {
-        name: 'v1.0',
-        id: '',
+        name: curVer.name ?? 'v1.0',
+        id: curVer.id ?? '',
         syncONOFF: '',
+        manualStepsTopreview: false,
+        updateVersion: curVer.updateVersion ?? 0,
         executionType: 'AUTOMATION',
+        reviewApproveStatus: '',
         functionProjectIds: [projectId],
         ...(existingId ? { deleted: false } : {}),
     };
@@ -812,58 +913,150 @@ function buildAutomationPayload(inputs) {
         const desc = s.description ?? '';
         const technologyType = TECH_BY_STEPTYPE[s.stepType] ?? tcType;
         const resolution = stepResolutions?.[i];
-        if (!resolution) {
+        // ponytail: control-flow / function / switch / manual steps have a null-actionId slot from
+        // resolveAutomationSteps — they don't need action resolution to be valid.
+        const isControlFlow = s.stepType === 'control_flow' || s.stepType === 'function' || s.stepType === 'function_end' || s.stepType === 'switch' || s.stepType === 'manual';
+        if (!isControlFlow && !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))
+        // parameterIds + recordedParam resolution order:
+        //   1. Seed from backend-preserved sourceParameterIds / sourceRecordedParam (round-trip
+        //      intact — a save that doesn't touch anything re-emits the same values).
+        //   2. Description ${tokens}: register the param id + a DEFAULT value from tc.data. Never
+        //      overrides an already-seeded id — a token default must not wipe a real recorded value.
+        //   3. LLM patches (s.recordedParam, name-keyed): resolve name → id and OVERRIDE. This is
+        //      how "change the URL parameter to X" via tc_draft_update flows through to the wire.
+        const paramIds = [...(s.sourceParameterIds ?? [])];
+        const seenIds = new Set(paramIds);
+        const recordedParamOut = { ...(s.sourceRecordedParam ?? {}) };
+        const registerId = (id) => {
+            if (!seenIds.has(id)) {
+                paramIds.push(id);
+                seenIds.add(id);
+            }
+        };
+        const setValue = (id, value, override) => {
+            const key = String(id);
+            if (override || !(key in recordedParamOut))
+                recordedParamOut[key] = value;
+        };
+        const seenNames = new Set();
+        const addByName = (name, value, override) => {
+            if (seenNames.has(name))
                 return;
-            seen.add(name);
+            seenNames.add(name);
             const id = paramIdByName.get(name);
             if (id == null)
                 return;
-            paramIds.push(id);
+            registerId(id);
             if (value !== undefined)
-                recordedParamOut[String(id)] = value;
+                setValue(id, value, override);
         };
+        // Description tokens seed defaults but don't override
         for (const name of extractParamNames(desc))
-            addParam(name, tc.data?.[name] ?? s.value);
+            addByName(name, tc.data?.[name] ?? s.value, false);
+        // LLM patches override
         if (s.recordedParam) {
             for (const [name, value] of Object.entries(s.recordedParam))
-                addParam(name, value);
+                addByName(name, value, true);
+        }
+        const objectParamIds = [...(s.sourceObjectParameterIds ?? [])];
+        // ponytail: spread the round-tripped raw fields FIRST so control-flow / function / switch /
+        // api / attachments / conditions / loop / functionId / fnVersionId / apiData / etc. all
+        // survive. Explicit computed fields below override where they overlap.
+        const rawBase = (s.sourceRaw ?? {});
+        const rawStepType = typeof rawBase['stepType'] === 'string' ? rawBase['stepType'] : undefined;
+        // stepLevelActions: merge — keep any extra flags from source, our four win where they exist.
+        const rawSLA = rawBase['stepLevelActions'] ?? {};
+        // ponytail: wire stepType resolution ladder for FRESH steps (no sourceRaw):
+        //   1. Round-trip sourceRaw.stepType wins if present (IF/FOR/FUNCTION preserved from DB)
+        //   2. Function step → 'FUNCTION' | 'FUNCTION_END'
+        //   3. Control-flow step → uppercase(controlFlow.kind) (e.g. "IF", "FOR_START", "WHILE")
+        //   4. Everything else → 'NORMAL_STATEMENT'
+        // This is what makes `add_step({stepType: 'control_flow', controlFlow: {kind: 'IF'}})` and
+        // `add_step({stepType: 'function', functionCall: {testCaseId: '99'}})` actually work.
+        let wireStepType = rawStepType;
+        if (!wireStepType) {
+            if (s.stepType === 'function')
+                wireStepType = 'FUNCTION';
+            else if (s.stepType === 'function_end')
+                wireStepType = 'FUNCTION_END';
+            else if (s.stepType === 'control_flow' && s.controlFlow?.kind)
+                wireStepType = String(s.controlFlow.kind).toUpperCase();
+            else
+                wireStepType = 'NORMAL_STATEMENT';
         }
+        // FUNCTION step: derive functionId + fnVersionId from neutral functionCall when no sourceRaw
+        // (LLM authored a fresh function-call step via add_step).
+        const wireFunctionId = (typeof rawBase['functionId'] === 'number' ? rawBase['functionId'] : undefined)
+            ?? (s.functionCall?.testCaseId ? Number.parseInt(s.functionCall.testCaseId, 10) : undefined);
+        const wireFnVersionId = (typeof rawBase['fnVersionId'] === 'string' ? rawBase['fnVersionId'] : undefined)
+            ?? s.functionCall?.versionId;
+        const wireSharedFnProjectId = (typeof rawBase['sharedFnProjectId'] === 'number' ? rawBase['sharedFnProjectId'] : undefined)
+            ?? (s.functionCall?.sharedProjectId ? Number.parseInt(s.functionCall.sharedProjectId, 10) : undefined);
+        // Control-flow step: derive conditions.ifstring + loopDuration from neutral controlFlow.
+        const wireConditions = rawBase['conditions']
+            ?? (s.controlFlow?.conditionText ? { ifstring: s.controlFlow.conditionText, children: [] } : { ifstring: '', children: [] });
+        const wireLoopDuration = (typeof rawBase['loopDuration'] === 'number' ? rawBase['loopDuration'] : undefined)
+            ?? s.controlFlow?.maxIterations;
         const step = {
+            ...rawBase,
+            deleted: false,
+            // ponytail: pass through the backend step uuid on round-trip. Without `id`, every step
+            // routes to tcfn.service.js:355 CREATE branch, mints a new uuid, orphans the original row.
+            ...(s.sourceId ? { id: s.sourceId } : {}),
+            // ponytail: parentId + versionId REQUIRED on update — tcfn.service.js:406 builds the update
+            // filter `{id, customerId, projectId, parentId, type}` and without parentId it becomes
+            // `{parentId: undefined}` → misses the existing row → upsert inserts a new orphan step
+            // with no parentId. UI query `{parentId: tcId, versionId, deleted:false}` then finds nothing.
+            ...(existingId ? { parentId: Number.parseInt(existingId, 10) } : {}),
+            ...(existingId && curVer.id ? { versionId: curVer.id } : {}),
             projectId,
-            moduleId,
-            type: 'TC',
-            stepType: 'NORMAL_STATEMENT',
-            seq: i + 1,
+            // Only emit actionId/objectId for steps that resolve to an action (straight-line automation).
+            // Control-flow / function / switch steps have no action; the sourceRaw spread carries their
+            // functionId / conditions / loop instead.
+            ...(resolution && resolution.actionId != null
+                ? {
+                    actionId: resolution.actionId,
+                    // ponytail: undefined objectId means "preserve DB value" (existing step with no round-trip
+                    // objectRef.id). null is a valid emitted value (fresh step where the action doesn't need one).
+                    objectId: resolution.objectId === undefined ? null : resolution.objectId,
+                }
+                : {}),
+            // Round-tripped attachments (source) preserved via spread above; default to [] if fresh.
+            attachments: Array.isArray(rawBase['attachments']) ? rawBase['attachments'] : [],
+            conditions: wireConditions,
             description: desc,
-            expectedResult: s.expectedResult ?? '',
             executionType: 'AUTOMATION',
-            technologyType,
-            actionId: resolution.actionId,
-            objectId: resolution.objectId,
+            expectedResult: s.expectedResult ?? '',
+            loop: rawBase['loop'] ?? { loopType: 'for', loopIteration: null },
+            ...(wireLoopDuration !== undefined ? { loopDuration: wireLoopDuration } : {}),
+            moduleId,
+            // Function-call fields — emitted only for FUNCTION steps (rawBase spread already carries
+            // them for round-tripped functions; these derivations cover fresh add_step callers).
+            ...(wireFunctionId !== undefined && Number.isFinite(wireFunctionId) ? { functionId: wireFunctionId } : {}),
+            ...(wireFnVersionId ? { fnVersionId: wireFnVersionId } : {}),
+            ...(wireSharedFnProjectId !== undefined && Number.isFinite(wireSharedFnProjectId) ? { sharedFnProjectId: wireSharedFnProjectId } : {}),
+            objectParameterIds: objectParamIds,
+            // ponytail: always emit — matches UI payload shape. Sending `[]` / `{}` is how UI signals
+            // "this step has no params/values"; the joi validator + backend $set semantics assume presence.
             parameterIds: paramIds,
-            objectParameterIds: [],
             recordedParam: recordedParamOut,
-            attachments: [],
-            conditions: { ifstring: '', children: [] },
-            loop: { loopType: 'for', loopIteration: null },
+            seq: i + 1,
             stepLevelActions: {
-                skip: s.flags?.skip ?? false,
-                captureScreenshot: s.flags?.screenshot ?? false,
-                continueOnFailure: s.flags?.continueOnFailure ?? false,
-                skippedReport: false,
+                ...rawSLA,
+                skip: s.flags?.skip ?? rawSLA['skip'] ?? false,
+                captureScreenshot: s.flags?.screenshot ?? rawSLA['captureScreenshot'] ?? false,
+                continueOnFailure: s.flags?.continueOnFailure ?? rawSLA['continueOnFailure'] ?? false,
+                skippedReport: rawSLA['skippedReport'] ?? false,
             },
-            ...(technologyType === 'WEB' ? { browserType: s.browserType ?? 'CHROME' } : {}),
+            // Wire stepType: sourceRaw wins on round-trip; for fresh steps, translated from neutral
+            // stepType + controlFlow.kind + function marker (see wireStepType computation above).
+            stepType: wireStepType,
+            technologyType,
+            type: 'TC',
         };
         automationSteps.push(step);
     });