common-qa-mcp 0.8.0 → 0.9.0

package/dist/adapters/simplifyqa/adapter.js

@@ -65,13 +65,17 @@ function normalizeFormula(doc, projectId) {
         parameters: params,
     };
 }
-/** SQA per-step status → neutral step status. */
+/** SQA per-step status → neutral step status. Matches RunState terminals ('passed'/'failed'/
+ *  'skipped'/'stopped') so the same icon/formatting logic works for top-level state AND per-step
+ *  rows (run.tools.ts:180 keys off these values — the earlier 'pass'/'fail' names left every
+ *  step icon defaulting to '•'). Non-terminal SQA states (INFO, INPROGRESS, NOTEXECUTED) pass
+ *  through lowercased so the tool can still surface them as diagnostic text. */
 function mapStepStatus(s) {
     switch (s.toUpperCase()) {
-        case 'PASSED': return 'pass';
-        case 'FAILED': return 'fail';
-        case 'SKIPPED': return 'skip';
-        case 'STOPPED': return 'stop';
+        case 'PASSED': return 'passed';
+        case 'FAILED': return 'failed';
+        case 'SKIPPED': return 'skipped';
+        case 'STOPPED': return 'stopped';
         default: return s.toLowerCase();
     }
 }
@@ -227,6 +231,9 @@ export class SimplifyQaAdapter {
          *  Keyed by `${technologyType}::${lowerCaseName}` so the same action name across two techs
          *  (e.g. "click" for WEB + ANDROID) resolves to the right numeric id. */
         this.actionCatalogCache = null;
+        /** Populated by actionCatalog() on each fetch. Surfaced in resolveAutomationSteps error messages
+         *  so a user hitting "no SQA action named X" can see what the fetch actually returned. */
+        this.actionCatalogFetchDiag = 'never fetched';
         // ---------------------------------------------------------------------- Objects (read + delete)
         // list/create/delete now go direct REST (same /tm/object base getObject already uses), mirroring
         // the testcase/suite search + soft-delete convention.
@@ -254,6 +261,18 @@ export class SimplifyQaAdapter {
             ...(this.cfg.projectId ? { 'x-project-id': this.cfg.projectId } : {}),
         };
     }
+    /** Public session context for MCP viewer/recorder windows that need to authenticate the sqa-ui
+     *  they load. cfg itself stays private; this getter is the one seam through which tc_edit_open
+     *  and record tools can forward token + baseUrl + projectId to Electron without asking the LLM. */
+    getSessionContext() {
+        // Constructor already rejected missing baseUrl (~line 265), so `!` is safe here.
+        return {
+            token: this.cfg.token,
+            baseUrl: this.cfg.baseUrl,
+            ...(this.cfg.projectId ? { projectId: this.cfg.projectId } : {}),
+            ...(this.cfg.userId ? { userId: this.cfg.userId } : {}),
+        };
+    }
     requireProjectId() {
         if (!this.cfg.projectId)
             throw new Error(NEEDS_PROJECT);
@@ -470,7 +489,11 @@ export class SimplifyQaAdapter {
         // Overlay currentVersionId to the resolved one and flip isCurrent flags on versions[]. Apply
         // even when rows are empty — a caller who pinned versionId still expects the header + versions[]
         // to reflect that choice (a legitimately-empty version shouldn't fall back to the TC's default).
-        const resolvedVer = versionId ?? tc.currentVersionId;
+        // ponytail: mirror fetchStepsCollection's resolution ladder — the raw doc from /tm/testcase/getById
+        // does NOT include a top-level versionId, only a `versions[]` array. Without the versions[0] fallback,
+        // tc.currentVersionId stays undefined → tc_save emits versionsDetails.id:"" → backend mints a
+        // phantom version and orphans the saved steps.
+        const resolvedVer = versionId ?? tc.currentVersionId ?? (Array.isArray(tc.versions) ? tc.versions[0]?.id : undefined);
         const patched = { ...withSteps, ...(resolvedVer ? { currentVersionId: resolvedVer } : {}) };
         if (resolvedVer && patched.versions?.length) {
             patched.versions = patched.versions.map((v) => ({ ...v, isCurrent: v.id === resolvedVer }));
@@ -997,15 +1020,41 @@ export class SimplifyQaAdapter {
         return str(rows[0], 'id', '_id', 'featureId') ?? ref;
     }
     // ---------------------------------------------------------------------- Modules, releases, sprints
+    /** Pages internally until the server returns a short page (or the total is reached) — the tool
+     *  has no limit/offset of its own and always wants the WHOLE project tree; `searchBody`'s default
+     *  page size (100) previously truncated any project with more modules than that silently. */
     async listModules() {
         const projectId = this.requireProjectId();
-        const body = this.searchBody([
-            { column: 'projectId', value: projectId },
-            { column: 'deleted', value: false },
-        ], { selectFields: ['id', 'code', 'name', 'parentId', 'isRoot', 'childIds'] });
-        const raw = await this.http.postJson('/pm/module/search', body);
-        const rows = pickArray(raw, 'data', 'content', 'modules');
-        return withTotal(rows.map(toModuleSummary), raw);
+        const PAGE = 100;
+        const SAFETY_CAP = 5000;
+        const rows = [];
+        let totalCount;
+        let startIndex = 0;
+        for (;;) {
+            const body = this.searchBody([
+                { column: 'projectId', value: projectId },
+                { column: 'deleted', value: false },
+            ], { selectFields: ['id', 'code', 'name', 'parentId', 'isRoot', 'childIds'], startIndex, limit: PAGE });
+            const raw = await this.http.postJson('/pm/module/search', body);
+            const page = pickArray(raw, 'data', 'content', 'modules');
+            if (totalCount === undefined) {
+                const t = raw?.totalCount ?? raw?.total ?? raw?.totalRecords;
+                if (typeof t === 'number')
+                    totalCount = t;
+            }
+            rows.push(...page);
+            if (page.length < PAGE)
+                break;
+            if (rows.length >= SAFETY_CAP)
+                break;
+            if (totalCount !== undefined && rows.length >= totalCount)
+                break;
+            startIndex += PAGE;
+        }
+        const mapped = rows.map(toModuleSummary);
+        if (totalCount !== undefined)
+            mapped.totalCount = totalCount;
+        return mapped;
     }
     /** GET /pm/module/:id — server returns an array; empty array → NotFound. */
     async getModule(id) {
@@ -1208,23 +1257,73 @@ export class SimplifyQaAdapter {
         // reaches that branch after emptyIds.push).
         return { dryRun: false, deleted: true, dependencies: [], hasBlockers: false };
     }
+    /** `list_releases` has no limit/offset of its own — it always wants the WHOLE visible set — so
+     *  page internally past `searchBody`'s default 100 instead of silently truncating (same fix as
+     *  listModules). */
     async listReleases(q) {
         const fields = [{ column: 'deleted', value: false }];
         if (q.scope === 'project')
             fields.push({ column: 'projectIds', value: this.requireProjectId() });
-        const body = this.searchBody(fields);
-        const raw = await this.http.postJson('/pm/release/search', body);
-        const rows = pickArray(raw, 'data', 'content', 'releases');
-        return withTotal(rows.map(toReleaseSummary), raw);
+        const PAGE = 100;
+        const SAFETY_CAP = 5000;
+        const rows = [];
+        let totalCount;
+        let startIndex = 0;
+        for (;;) {
+            const body = this.searchBody(fields, { startIndex, limit: PAGE });
+            const raw = await this.http.postJson('/pm/release/search', body);
+            const page = pickArray(raw, 'data', 'content', 'releases');
+            if (totalCount === undefined) {
+                const t = raw?.totalCount ?? raw?.total ?? raw?.totalRecords;
+                if (typeof t === 'number')
+                    totalCount = t;
+            }
+            rows.push(...page);
+            if (page.length < PAGE)
+                break;
+            if (rows.length >= SAFETY_CAP)
+                break;
+            if (totalCount !== undefined && rows.length >= totalCount)
+                break;
+            startIndex += PAGE;
+        }
+        const mapped = rows.map(toReleaseSummary);
+        if (totalCount !== undefined)
+            mapped.totalCount = totalCount;
+        return mapped;
     }
+    /** Same unconditional-pagination fix as listReleases — `list_sprints` has no limit/offset either. */
     async listSprints(q) {
         const fields = [{ column: 'deleted', value: false }];
         if (q.releaseId)
             fields.push({ column: 'releaseId', value: Number.parseInt(q.releaseId, 10) });
-        const body = this.searchBody(fields);
-        const raw = await this.http.postJson('/pm/sprint/search', body);
-        const rows = pickArray(raw, 'data', 'content', 'sprints');
-        return withTotal(rows.map(toSprintSummary), raw);
+        const PAGE = 100;
+        const SAFETY_CAP = 5000;
+        const rows = [];
+        let totalCount;
+        let startIndex = 0;
+        for (;;) {
+            const body = this.searchBody(fields, { startIndex, limit: PAGE });
+            const raw = await this.http.postJson('/pm/sprint/search', body);
+            const page = pickArray(raw, 'data', 'content', 'sprints');
+            if (totalCount === undefined) {
+                const t = raw?.totalCount ?? raw?.total ?? raw?.totalRecords;
+                if (typeof t === 'number')
+                    totalCount = t;
+            }
+            rows.push(...page);
+            if (page.length < PAGE)
+                break;
+            if (rows.length >= SAFETY_CAP)
+                break;
+            if (totalCount !== undefined && rows.length >= totalCount)
+                break;
+            startIndex += PAGE;
+        }
+        const mapped = rows.map(toSprintSummary);
+        if (totalCount !== undefined)
+            mapped.totalCount = totalCount;
+        return mapped;
     }
     /** POST /pm/users/search — the customer's users (router mounted at `/pm/users`, plural — see
      *  project-management/express-app.js:181). Backend auto-scopes non-admin callers to users in
@@ -2317,8 +2416,10 @@ export class SimplifyQaAdapter {
             return this.actionCatalogCache;
         const projectId = this.requireProjectId();
         this.actionCatalogCache = (async () => {
-            // `projectId in [0, projectId]` — 0 is the customer-wide default catalog, projectId is the
-            // per-project overrides layered on top. Same filter the SQA UI uses (steps.model.ts:59).
+            // Use the SAME filter the SQA UI uses (mobile-app/angular/.../steps.model.ts:59):
+            // {projectId: {$in:[0, projectId]}}. Removing it caused /tm/action/search to return 0 rows in
+            // practice — the backend endpoint apparently requires it as-is despite server-side resolvers
+            // using only {customerId, deleted:false}. Keep the UI's filter to stay compatible.
             const body = {
                 searchFields: [
                     { column: 'deleted', value: false },
@@ -2330,12 +2431,25 @@ export class SimplifyQaAdapter {
             };
             const raw = await this.http.postJson('/tm/action/search', body);
             const rows = pickArray(raw, 'data', 'content', 'actions');
+            // Capture diagnostic snapshot so downstream errors can surface WHY the fetch returned 0 rows.
+            try {
+                const topKeys = raw && typeof raw === 'object' ? Object.keys(raw).slice(0, 10).join(',') : typeof raw;
+                const totalCount = raw?.totalCount ?? raw?.total ?? 'n/a';
+                const firstRowKeys = rows[0] && typeof rows[0] === 'object' ? Object.keys(rows[0]).slice(0, 12).join(',') : 'no-rows';
+                this.actionCatalogFetchDiag = `rows.length=${rows.length} totalCount=${totalCount} raw.keys=[${topKeys}] firstRowKeys=[${firstRowKeys}] projectId=${projectId}`;
+            }
+            catch { /* diagnostic must not throw */ }
             const map = new Map();
             for (const row of rows) {
                 const idStr = str(row, 'id', '_id', 'actionId');
                 const name = str(row, 'name');
-                const tech = str(row, 'technology');
-                if (!idStr || !name || !tech)
+                // Diagnostic proved action rows have NO top-level `technology` field
+                // (firstRowKeys=[id,name,objectRequired,objectTemplate]). SQA UI derives tech by looking up
+                // objectTemplate → object_templates.name — we don't (would need a second fetch). Just require
+                // id; drop the tech-in-key and let names collide across techs. Round-trip lookups (by numeric
+                // id) are unaffected. Model-authored by-name lookups get whichever action registered last for
+                // that name — good enough until cross-tech name collisions actually bite.
+                if (!idStr)
                     continue;
                 const id = Number.parseInt(idStr, 10);
                 if (!Number.isFinite(id))
@@ -2345,14 +2459,17 @@ export class SimplifyQaAdapter {
                 const objectTemplate = typeof otRaw === 'number' ? otRaw
                     : typeof otRaw === 'string' && /^\d+$/.test(otRaw) ? Number.parseInt(otRaw, 10)
                         : undefined;
-                // Prefer the higher-priority project override when the same (tech, name) has both a
-                // default and a project row: last write wins if we sort defaults first. Backend returns
-                // whichever ordering; we resolve determinism by preferring a non-zero projectId row.
-                const key = `${tech.toUpperCase()}::${name.toLowerCase()}`;
-                const prev = map.get(key);
-                const isProjectOverride = typeof row?.projectId === 'number' && row.projectId !== 0;
-                if (!prev || isProjectOverride)
-                    map.set(key, { id, objectRequired, objectTemplate });
+                const entry = { id, objectRequired, ...(objectTemplate !== undefined ? { objectTemplate } : {}) };
+                // Name-only key for by-name lookups (may collide across techs — see comment above).
+                if (name) {
+                    const key = name.toLowerCase();
+                    const prev = map.get(key);
+                    const isProjectOverride = typeof row?.projectId === 'number' && row.projectId !== 0;
+                    if (!prev || isProjectOverride)
+                        map.set(key, entry);
+                }
+                // Id-keyed entry so numeric-actionType round-trip lookups are O(1) instead of a scan.
+                map.set(`id::${id}`, entry);
             }
             return map;
         })().catch((e) => { this.actionCatalogCache = null; throw e; });
@@ -2409,27 +2526,106 @@ export class SimplifyQaAdapter {
     async resolveAutomationSteps(projectId, moduleId, tc) {
         const catalog = await this.actionCatalog();
         const steps = Array.isArray(tc.steps) ? tc.steps : [];
+        // ponytail: objectId can be `undefined` here to mean "don't emit — preserve the backend value".
+        // Used when an existing step (sourceId set) has no round-trip objectRef.id, e.g. because it was
+        // recorded before objectRequired was flipped on the action. Emitting null would $set-clobber the DB.
+        // actionId also nullable for control-flow / function / switch / function_end — those steps don't
+        // have an action; buildAutomationPayload omits action/object emit when actionId is null.
         const out = [];
         for (let i = 0; i < steps.length; i++) {
             const s = steps[i];
+            // ponytail: control-flow / function / switch / function_end steps have no action to resolve.
+            // Push a null-actionId slot so index alignment survives; mapper checks and skips action/object
+            // emit for these. Without this, IF/FOR/WHILE/FUNCTION steps throw "missing actionType" on save.
+            if (s.stepType === 'control_flow' || s.stepType === 'function' || s.stepType === 'function_end' || s.stepType === 'switch' || s.stepType === 'manual') {
+                out.push({ actionId: null, objectId: null });
+                continue;
+            }
             const tech = (TECH_BY_STEPTYPE[s.stepType] ?? deriveTcType(tc)).toUpperCase();
             const name = (s.actionType ?? '').trim();
             if (!name) {
                 throw new Error(`Automation step ${i + 1} ("${s.description}"): missing actionType — the neutral Step.actionType must name an SQA action (e.g. "Click", "Type Text", "Launch Application").`);
             }
-            const meta = catalog.get(`${tech}::${name.toLowerCase()}`);
+            // Round-trip support: a TC hydrated via getTestCase carries actionType = String(actionId), so
+            // on save we may see a numeric string here. Catalog is dual-keyed: `id::N` for round-trip,
+            // `<lowercase name>` for model-authored by-name lookups. Tech is not in the key because
+            // action rows have no top-level `technology` field (SQA UI resolves via objectTemplate lookup).
+            const isNumericId = /^\d+$/.test(name);
+            let meta = isNumericId
+                ? catalog.get(`id::${Number.parseInt(name, 10)}`)
+                : catalog.get(name.toLowerCase());
+            // Fallback: if the by-id scan misses (action created in a different project and thus not in
+            // the UI's projectId-filtered catalog), fetch it directly via GET /tm/action/:id. Only tries
+            // for numeric-id lookups — model-authored name lookups have no id to fetch.
+            let fallbackDiag = '';
+            if (!meta && isNumericId) {
+                try {
+                    const raw = await this.http.getJson(`/tm/action/${Number.parseInt(name, 10)}`);
+                    const row = raw?.data && typeof raw.data === 'object' ? raw.data
+                        : Array.isArray(raw?.data) ? raw.data[0]
+                            : Array.isArray(raw) ? raw[0]
+                                : raw;
+                    const idStr = str(row, 'id', '_id', 'actionId');
+                    // ponytail: no `technology` gate. Catalog builder proved action rows have no top-level
+                    // technology field (see comment at ~line 2357); requiring it here made the fallback
+                    // never succeed — every cross-project action id threw "no SQA action named X".
+                    if (idStr) {
+                        const otRaw = row?.objectTemplate;
+                        const objectTemplate = typeof otRaw === 'number' ? otRaw
+                            : typeof otRaw === 'string' && /^\d+$/.test(otRaw) ? Number.parseInt(otRaw, 10)
+                                : undefined;
+                        meta = {
+                            id: Number.parseInt(idStr, 10),
+                            objectRequired: row?.objectRequired === true,
+                            ...(objectTemplate !== undefined ? { objectTemplate } : {}),
+                        };
+                    }
+                    else {
+                        fallbackDiag = ` [GET /tm/action/${name} returned no usable row (idStr=null). Raw keys: ${row && typeof row === 'object' ? Object.keys(row).join(',') : typeof row}]`;
+                    }
+                }
+                catch (e) {
+                    fallbackDiag = ` [GET /tm/action/${name} failed: ${e.message}]`;
+                }
+            }
             if (!meta) {
-                throw new Error(`Automation step ${i + 1}: no SQA action named "${name}" for technology ${tech}. Check the action catalog in the SQA UI.`);
+                throw new Error(`Automation step ${i + 1}: no SQA action named "${name}" for technology ${tech}. Catalog size=${catalog.size}, numericId=${isNumericId}. FetchDiag: ${this.actionCatalogFetchDiag}.${fallbackDiag}`);
             }
             let objectId = null;
             if (meta.objectRequired) {
-                if (!s.objectRef || !s.objectRef.name || !(s.objectRef.locators?.length)) {
-                    throw new Error(`Automation step ${i + 1} ("${name}"): action requires an object but Step.objectRef is missing name/locators. Provide objectRef:{name, locators:[{name, value}]}.`);
+                // Resolution ladder (first match wins):
+                //   1. objectRef.id set → use directly (round-trip OR LLM referencing a known object)
+                //   2. sourceId set but no objectRef.id → preserve DB value (existing step, backend may
+                //      have null historically; emitting anything would $set-clobber)
+                //   3. objectRef.name only (no locators) → project-scoped name lookup (LLM added a step
+                //      referencing an existing Object Repository entry by name — mirrors UI dropdown)
+                //   4. objectRef.name + locators → get-or-create via createObjectSeq (recorder path)
+                //   5. nothing usable → throw with the three-option error so the caller can pick
+                const roundTripId = s.objectRef?.id ? Number.parseInt(String(s.objectRef.id), 10) : NaN;
+                if (Number.isFinite(roundTripId)) {
+                    objectId = roundTripId;
+                }
+                else if (s.sourceId) {
+                    objectId = undefined;
+                }
+                else if (s.objectRef?.name && !(s.objectRef.locators?.length)) {
+                    const found = await this.findObjectIdByName(projectId, s.objectRef.name);
+                    if (found != null) {
+                        objectId = found;
+                    }
+                    else {
+                        throw new Error(`Automation step ${i + 1} ("${name}"): no object named "${s.objectRef.name}" found in this project. Either pass objectRef.id to reuse an existing one, or add objectRef.locators:[{name, value}, ...] to create a new object with that name.`);
+                    }
                 }
-                if (meta.objectTemplate == null) {
-                    throw new Error(`Automation step ${i + 1} ("${name}"): action ${meta.id} has no objectTemplate — cannot create/reuse an object without knowing which template it belongs to.`);
+                else if (s.objectRef?.name && s.objectRef.locators?.length) {
+                    if (meta.objectTemplate == null) {
+                        throw new Error(`Automation step ${i + 1} ("${name}"): action ${meta.id} has no objectTemplate — cannot create/reuse an object without knowing which template it belongs to.`);
+                    }
+                    objectId = await this.resolveObjectId(s.objectRef, projectId, moduleId, tech, meta.objectTemplate);
+                }
+                else {
+                    throw new Error(`Automation step ${i + 1} ("${name}"): action requires an object but Step.objectRef is missing. Provide objectRef:{id} to reuse a known one, objectRef:{name} to look one up by name in the project, or objectRef:{name, locators:[{name, value}]} to create a new one.`);
                 }
-                objectId = await this.resolveObjectId(s.objectRef, projectId, moduleId, tech, meta.objectTemplate);
             }
             out.push({ actionId: meta.id, objectId });
         }
@@ -2458,6 +2654,28 @@ export class SimplifyQaAdapter {
         }
         return null;
     }
+    /** Case-insensitive project-scoped lookup of an existing object by `disname` (the UI's Name).
+     *  Lets tc_draft_update pass `objectRef:{name}` for an already-defined object without also
+     *  supplying locators — mirrors what a user picking from the Object Repository dropdown does. */
+    async findObjectIdByName(projectId, name) {
+        const body = this.searchBody([
+            { column: 'disname', value: name },
+            { column: 'projectId', value: projectId },
+            { column: 'deleted', value: false },
+        ], { startIndex: 0, limit: 10 });
+        body['searchFields'][0]['ignorecase'] = true;
+        const raw = await this.http.postJson('/tm/object/search', body);
+        const rows = pickArray(raw, 'data', 'content', 'objects');
+        for (const row of rows) {
+            const rowName = str(row, 'disname');
+            if (rowName?.toLowerCase() === name.toLowerCase()) {
+                const id = str(row, 'id', '_id');
+                if (id)
+                    return Number.parseInt(id, 10);
+            }
+        }
+        return null;
+    }
     async getOrCreateParameter(projectId, moduleId, name, defaultValue) {
         const existing = await this.findParameterId(projectId, name);
         if (existing != null)
@@ -2629,6 +2847,25 @@ export class SimplifyQaAdapter {
             doc = doc.length > 0 ? doc[0] : {};
         return doc && typeof doc === 'object' ? doc : {};
     }
+    /** Mirrors sqa-ui `buildExecutionPlatform` (suites.component.ts:779) so MCP-added TCs save with
+     *  the same per-row platform the UI would set — otherwise the suite trips the "select execution
+     *  platform" warning at run time. Special types self-identify; WEB falls back to Chrome so
+     *  suite_run doesn't send `platform: []`; mobile with no bound device stays empty (UI does same). */
+    buildExecutionPlatformForEntry(raw, tcType) {
+        const special = new Set(['API', 'MAINFRAME', 'SAP', 'DESKTOP', 'DATABASE']);
+        if (special.has(tcType)) {
+            const p = { id: tcType, name: tcType, technologyType: tcType, type: 'NONE' };
+            return { LOCAL: p, REMOTE: { ...p }, CLOUD: { ...p } };
+        }
+        const own = raw?.['executionPlatform'];
+        if (own && typeof own === 'object' && own.id) {
+            return { LOCAL: own, REMOTE: {}, CLOUD: {} };
+        }
+        if (tcType === 'WEB') {
+            return { LOCAL: { id: 'CHROME', name: 'Chrome', technologyType: 'WEB', type: 'NONE' }, REMOTE: {}, CLOUD: {} };
+        }
+        return { LOCAL: {}, REMOTE: {}, CLOUD: {} };
+    }
     /** Assemble the strict allow-listed suite entry for an ADD op. Required fields per the SQA
      *  validator: testcaseId, code, seq (set by the caller), version, versionId, tcType. */
     async buildSuiteEntryFromTestcase(tcNum) {
@@ -2651,7 +2888,7 @@ export class SimplifyQaAdapter {
             ...(raw?.projectId !== undefined ? { projectId: raw.projectId } : {}),
             version: versionName ?? 'v1.0',
             versionId: versionId ?? '',
-            executionPlatform: { LOCAL: {}, REMOTE: {}, CLOUD: {} },
+            executionPlatform: this.buildExecutionPlatformForEntry(raw, tcType),
         };
     }
     async resolveObjectTemplateId(technology) {
@@ -2888,7 +3125,19 @@ export class SimplifyQaAdapter {
     }
     // ---------------------------------------------------------------------- Actions catalog
     async actionsCatalog(platform) {
-        return this.requireHop('actions_catalog').actionsCatalog(platform);
+        // Build from the live backend catalog (already cached per-connection). Each entry gets its
+        // numeric id + objectRequired flag so callers can round-trip actionType ↔ actionId. Ignores
+        // `platform` — action rows carry no top-level technology; tech disambiguation is a follow-up
+        // (would need an object_templates lookup). Skips the `id::N` reverse-lookup keys.
+        void platform;
+        const catalog = await this.actionCatalog();
+        const defs = [];
+        for (const [key, meta] of catalog) {
+            if (key.startsWith('id::'))
+                continue; // reverse-lookup entry — already covered by name key
+            defs.push({ actionType: key, platform: 'unknown', id: meta.id, objectRequired: meta.objectRequired });
+        }
+        return defs;
     }
     // ---------------------------------------------------------------------- Testdata generation  [Step 3]
     /** Fetch the default (template) iteration row for a TC. Fills gaps from the raw TC:
@@ -3194,7 +3443,24 @@ export class SimplifyQaAdapter {
             executionId, executionRunId, parentId, projectId,
         });
         const rawSteps = Array.isArray(stepsResp?.data) ? stepsResp.data : [];
-        return rawSteps.map((s) => {
+        // Backend logs control-flow markers as INFO rows with `description: null` (see
+        // executionStepResult.service.js insertLoopIterationStart/insertFunctionEnd/… — the same
+        // executionRunId carries LOOP_ITERATION_START/END, FUNCTION_START/END, FUNCTION_ITERATION_*,
+        // WHILE_START/END alongside the real action rows). Left in, they fill the text response
+        // with blank `• step N:  (info)` lines that hide the actual failing step. Filter here so
+        // stepResults contains only debuggable rows.
+        const NOISE_STEP_TYPES = new Set([
+            'LOOP_ITERATION_START', 'LOOP_ITERATION_END',
+            'FUNCTION_START', 'FUNCTION_END',
+            'FUNCTION_ITERATION_START', 'FUNCTION_ITERATION_END',
+            'FOR_START', 'FOR_END', 'WHILE_START', 'WHILE_END',
+            'ITERATOR_START', 'ITERATOR_END', 'DO',
+        ]);
+        const filtered = rawSteps.filter((s) => {
+            const st = String(s?.stepType ?? '').toUpperCase();
+            return !NOISE_STEP_TYPES.has(st);
+        });
+        return filtered.map((s) => {
             const step = {
                 n: typeof s?.seq === 'number' ? s.seq : 0,
                 description: String(s?.description ?? ''),
@@ -3264,15 +3530,15 @@ export class SimplifyQaAdapter {
             reportUrl: `${base}/user/reports/reports-page?type=TESTCASE&parentId=${parentId}&id=${runIdNum}&projectId=${projectId}`,
         };
     }
-    /** Most recent execution runId for a SUITE — same `/exec/execution/search` the /reports UI's
-     *  current-executions view drives, filtered to `type=SUITE` + this suite's numeric id, sorted by
-     *  id desc, limit 1. Returns the numeric run id (what `getRun` accepts), or null if the suite has
-     *  never been executed. */
-    async getLatestSuiteRun(suiteId) {
+    /** Most recent execution runId for a SUITE or TC — same `/exec/execution/search` the /reports UI's
+     *  current-executions view drives, filtered by `type` + the entity's numeric id, sorted id desc,
+     *  limit 1. `childExecution:false` + the `parentExecutionCopy nor` clause together drop suite-child
+     *  TC rows, so a TC lookup returns its LATEST STANDALONE run, not the child spawned inside a suite. */
+    async getLatestRunFor(type, id) {
         const projectId = this.requireProjectId();
-        const suiteNum = Number.parseInt(numericId(suiteId), 10);
-        if (!Number.isFinite(suiteNum))
-            throw new Error(`getLatestSuiteRun: invalid suiteId ${suiteId}.`);
+        const num = Number.parseInt(numericId(id), 10);
+        if (!Number.isFinite(num))
+            throw new Error(`getLatestRunFor(${type}): invalid id ${id}.`);
         // Hand-rolled payload — searchBody doesn't emit `sort` or `operator` keys the /reports search wants.
         const body = {
             searchFields: [
@@ -3281,16 +3547,83 @@ export class SimplifyQaAdapter {
                 { column: 'projectId', value: projectId, regEx: false },
                 { column: 'childExecution', value: false },
                 { column: 'parentExecutionCopy', value: true, operator: 'nor' },
-                { column: 'type', value: 'SUITE', regEx: false },
-                { column: 'executionTypeId', value: suiteNum, regEx: false },
+                { column: 'type', value: type, regEx: false },
+                { column: 'executionTypeId', value: num, regEx: false },
             ],
             startIndex: 0,
             limit: 1,
         };
         const raw = await this.http.postJson('/exec/execution/search', body);
         const rows = pickArray(raw, 'data', 'content', 'executions');
-        const runId = str(rows[0], 'id', '_id');
-        return runId ?? null;
+        return str(rows[0], 'id', '_id') ?? null;
+    }
+    async getLatestSuiteRun(suiteId) { return this.getLatestRunFor('SUITE', suiteId); }
+    async getLatestTestcaseRun(tcId) { return this.getLatestRunFor('TC', tcId); }
+    /** Top-N recent runs — one HTTP call, same standalone-only filters as `getLatestRunFor`. For each
+     *  SUITE row the exec doc's `executionItems[]` already carries per-TC status, so the tally is
+     *  computed inline (no extra call per run). TC rows omit the tally counters. Sorted newest-first
+     *  by `id` (execution ids are monotonic). Bounded — callers should cap `limit` at the tool layer
+     *  so a runaway request can't pull thousands of rows. */
+    async listRecentRuns(type, id, limit) {
+        const projectId = this.requireProjectId();
+        const num = Number.parseInt(numericId(id), 10);
+        if (!Number.isFinite(num))
+            throw new Error(`listRecentRuns(${type}): invalid id ${id}.`);
+        const base = (this.cfg.baseUrl ?? '').replace(/\/+$/, '');
+        const body = {
+            searchFields: [
+                { column: 'id', sort: 'dsc' },
+                { column: 'deleted', value: false },
+                { column: 'projectId', value: projectId, regEx: false },
+                { column: 'childExecution', value: false },
+                { column: 'parentExecutionCopy', value: true, operator: 'nor' },
+                { column: 'type', value: type, regEx: false },
+                { column: 'executionTypeId', value: num, regEx: false },
+            ],
+            startIndex: 0,
+            limit,
+        };
+        const raw = await this.http.postJson('/exec/execution/search', body);
+        const rows = pickArray(raw, 'data', 'content', 'executions');
+        return rows.map((r) => {
+            const runId = str(r, 'id', '_id') ?? '';
+            const runIdNum = Number.parseInt(runId, 10);
+            const summary = {
+                runId,
+                state: mapRunState(str(r, 'status') ?? ''),
+            };
+            const startedAt = str(r, 'startTime', 'createdAt');
+            const endedAt = str(r, 'endTime');
+            if (startedAt)
+                summary.startedAt = startedAt;
+            if (endedAt)
+                summary.endedAt = endedAt;
+            if (Number.isFinite(runIdNum)) {
+                const entityNum = Number(r?.executionTypeId ?? num);
+                summary.reportUrl = `${base}/user/reports/reports-page?type=${type === 'SUITE' ? 'SUITE' : 'TESTCASE'}&parentId=${entityNum}&id=${runIdNum}&projectId=${projectId}`;
+            }
+            if (type === 'SUITE') {
+                const items = Array.isArray(r?.executionItems) ? r.executionItems : [];
+                let passed = 0, failed = 0, skipped = 0, notExecuted = 0;
+                for (const it of items) {
+                    const s = String(it?.status ?? '').toUpperCase();
+                    if (s === 'PASSED')
+                        passed++;
+                    else if (s === 'FAILED')
+                        failed++;
+                    else if (s === 'SKIPPED')
+                        skipped++;
+                    else if (s === 'NOTEXECUTED')
+                        notExecuted++;
+                }
+                summary.totalTestCases = items.length;
+                summary.passed = passed;
+                summary.failed = failed;
+                summary.skipped = skipped;
+                summary.notExecuted = notExecuted;
+            }
+            return summary;
+        });
     }
     /** Targeted name lookup for a single project by numeric id — the whole-list `listProjects`
      *  is paged (default 100) and API-key scoping can hide the selected project, which left
@@ -3314,11 +3647,10 @@ export class SimplifyQaAdapter {
     // SUITE runs are not yet ported and still hop (or error clearly).
     async startRun(target, opts) {
         const projectId = this.requireProjectId();
+        if (target.suiteId && !target.tcId) {
+            return this.startSuiteRun(target.suiteId, opts);
+        }
         if (!target.tcId) {
-            if (target.suiteId) {
-                throw new Error('startRun: SUITE runs are not yet ported to direct REST — set QA_MCP_URL so common-mcp ' +
-                    'can hop to the SimplifyQA agent for suite dispatch, or run a single TC.');
-            }
             throw new Error('startRun: target.tcId (or target.suiteId) is required.');
         }
         const tcId = target.tcId;
@@ -3486,11 +3818,201 @@ export class SimplifyQaAdapter {
         const executionId = Number.parseInt(numericId(runId), 10);
         if (!Number.isFinite(executionId))
             throw new Error(`stopRun: invalid runId ${runId}.`);
-        await this.http.postJson('/exec/execution/stopExecution', {
+        // Mirror sqa-ui reports.component.ts:2041-2054: cloud-parallel needs a dedicated killType so
+        // the backend fans the Redis kill out to every child agent (executions/…/execution.service.js
+        // :4610-4657). Plain STOP_EXECUTION only pushes to the parent's agentId, leaving cloud-parallel
+        // child VMs running even though their DB rows read FAILED.
+        const doc = await this.fetchExecDoc(executionId, projectId);
+        const mode = String(doc?.mode ?? '').toUpperCase();
+        const style = String(doc?.executionStyle ?? '').toUpperCase();
+        const killType = mode === 'CLOUD' && style === 'PARALLEL' ? 'STOP_EXECUTION_PARALLEL_CLOUD' : 'STOP_EXECUTION';
+        await this.http.postJson('/exec/execution/stopExecution', { projectId, executionId, killType });
+    }
+    /** SUITE dispatch. Mirrors `startRun` above (which handles TC) — same `/exec/execution` endpoint,
+     *  same LOCAL-agent fast-fail, same project-name / environment resolution. What differs is on the
+     *  wire: `type: 'SUITE'`, `executionType` sourced from `suite.suiteType`, `mode` defaulting to
+     *  `suite.executionType`, a populated `globalConfiguration` block, and one `executionItems` entry
+     *  PER member — each carrying the suite row's persisted `versionId` / `stepId` / `platform` / `seq`
+     *  (NOT a re-derived random step id). See sqa-ui execution-popup-modal.component.ts:621-1105 SU
+     *  branch for the authoritative UI builder; every field below traces back to a line there. */
+    async startSuiteRun(suiteId, opts) {
+        const projectId = this.requireProjectId();
+        const suiteNum = Number.parseInt(numericId(suiteId), 10);
+        if (!Number.isFinite(suiteNum))
+            throw new Error(`startRun: could not resolve numeric id for ${suiteId}.`);
+        const rawSuite = await this.fetchRawSuite(suiteId);
+        if (!rawSuite || Object.keys(rawSuite).length === 0) {
+            throw new Error(`startRun: suite ${suiteId} not found.`);
+        }
+        // Effective mode: caller pick wins (matches our tool's cascade UX); fall back to the suite doc's
+        // stored `executionType`, which the UI reads unconditionally (execution-popup-modal.ts:668).
+        const mode = (opts.mode ?? String(rawSuite.executionType ?? 'LOCAL')).toUpperCase();
+        if (mode === 'LOCAL' && !(await this.probeLocalAgent())) {
+            throw new Error(`startRun (LOCAL): SimplifyQA desktop agent is not reachable at ` +
+                `${this.cfg.url ?? '(no agent URL configured — set QA_MCP_URL)'}. Start the desktop ` +
+                `agent, then try again. Use mode:'cloud' to run on a cloud runner instead — it does not ` +
+                `need the desktop agent.`);
+        }
+        const projectName = await this.lookupProjectName(projectId);
+        if (!projectName) {
+            throw new Error(`startRun: could not resolve project name for projectId=${projectId}. ` +
+                `The token may not have read access to this project.`);
+        }
+        const env = await this.resolveEnvironment(projectId, opts.environment);
+        const suiteType = String(rawSuite.suiteType ?? 'AUTOMATION').toUpperCase();
+        // Build one executionItems entry per suite row, in suite order. Silently skip rows whose TC no
+        // longer exists (matches UI :880 `if (!data) return;`). Every item uses the suite row's stored
+        // versionId + stepId + per-mode platform — regenerating any of those splits step correlation
+        // and breaks the agent's iteration join. Missing platform for a row is not an error here (UI
+        // sends `[]`) — the agent tolerates it for MANUAL suites; AUTOMATION suites without a saved
+        // platform were misconfigured upstream and would fail regardless.
+        const members = Array.isArray(rawSuite.testCases) ? rawSuite.testCases : [];
+        const executionItems = [];
+        let seqCounter = 0;
+        for (const row of members) {
+            seqCounter++;
+            const memberTcId = row?.testcaseId;
+            if (memberTcId === undefined || memberTcId === null)
+                continue;
+            let rawTc;
+            try {
+                rawTc = await this.fetchRawTestcase(String(memberTcId));
+            }
+            catch {
+                continue;
+            }
+            if (!rawTc || Object.keys(rawTc).length === 0)
+                continue;
+            const tcType = String(str(rawTc, 'tcType') ?? 'WEB').toUpperCase();
+            const versions = Array.isArray(rawTc?.versions) ? rawTc.versions : [];
+            const rowVersionId = row?.versionId ?? row?.version;
+            const versionMatch = rowVersionId
+                ? versions.find((v) => str(v, 'id', '_id') === String(rowVersionId) || str(v, 'name') === String(rowVersionId))
+                : undefined;
+            const versionId = str(versionMatch, 'id', '_id') ?? (rowVersionId !== undefined ? String(rowVersionId) : '');
+            const versionName = str(versionMatch, 'name') ?? str(rawTc, 'versionName', 'selectedVersionName') ?? 'v1.0';
+            // Per-mode platform from the suite row. UI reads `data1.executionPlatform[mode]` (:882-965);
+            // when saved, it's a single object → wrap in `[obj]`; if the row didn't save one for this
+            // mode, send `[]` and let the backend reject/accept per its own rules.
+            const savedPlatform = row?.executionPlatform?.[mode];
+            let platform = [];
+            if (savedPlatform && typeof savedPlatform === 'object') {
+                const p = {
+                    name: savedPlatform.name,
+                    id: savedPlatform.id ?? savedPlatform.name,
+                    technologyType: String(savedPlatform.technologyType ?? tcType).toUpperCase(),
+                    type: savedPlatform.type ?? 'NONE',
+                };
+                if (savedPlatform.cloudDeviceType)
+                    p['cloudDeviceType'] = savedPlatform.cloudDeviceType;
+                if (savedPlatform.osVersion)
+                    p['osVersion'] = savedPlatform.osVersion;
+                platform = [p];
+            }
+            else if (['API', 'MAINFRAME', 'SAP', 'DESKTOP', 'DATABASE'].includes(tcType)) {
+                platform = [{ name: tcType, id: tcType, technologyType: tcType, type: 'NONE' }];
+            }
+            const moduleIdNum = typeof rawTc?.moduleId === 'number' ? rawTc.moduleId : 0;
+            let moduleName = '';
+            if (moduleIdNum > 0) {
+                try {
+                    const body = this.searchBody([{ column: 'id', value: moduleIdNum }, { column: 'deleted', value: false }], { selectFields: ['id', 'name'], limit: 1 });
+                    const raw = await this.http.postJson('/pm/module/search', body);
+                    const rows = pickArray(raw, 'data', 'content', 'modules');
+                    moduleName = str(rows[0], 'name') ?? '';
+                }
+                catch { /* leave empty */ }
+            }
+            executionItems.push({
+                id: typeof rawTc?.id === 'number' ? rawTc.id : Number.parseInt(numericId(String(memberTcId)), 10),
+                name: str(rawTc, 'name', 'title') ?? '',
+                description: str(rawTc, 'description') ?? '',
+                versionId,
+                versionName,
+                seq: typeof row?.seq === 'number' ? row.seq : seqCounter,
+                stepId: row?.stepId ?? '', // MUST come from the suite row, never regenerated
+                stepCount: -1, // suite items send -1 (TC sends 0)
+                technologyType: tcType,
+                type: 'TC', // every item is 'TC'; suite-ness lives at top-level type
+                platform,
+                projectId,
+                projectName,
+                configuration: {},
+                iterationsSelected: [],
+                moduleId: moduleIdNum,
+                userstoryId: typeof rawTc?.userstoryId === 'number' ? rawTc.userstoryId : 0,
+                tags: Array.isArray(rawTc?.tags) ? rawTc.tags : [],
+                code: str(rawTc, 'code') ?? '',
+                prerequisite: str(rawTc, 'prerequisite', 'preconditions') ?? '',
+                moduleName,
+                userstoryName: '',
+            });
+        }
+        if (executionItems.length === 0) {
+            throw new Error(`startRun: suite ${suiteId} has no runnable test cases (all members were deleted, ` +
+                `unreadable, or filtered out).`);
+        }
+        // agentId derivation (mirrors UI :677). LOCAL always uses this machine's agent; REMOTE/CLOUD
+        // pin the suite doc's saved `agentId` (or null when the suite wasn't pinned). CLOUD_AGENT
+        // fallback (:771-774) promotes `cloudType` to 'SQA'.
+        let agentId;
+        if (mode === 'LOCAL') {
+            agentId = await this.resolveLocalAgentId(opts.agentId);
+        }
+        else if (mode === 'REMOTE') {
+            const preferred = opts.agentId ?? (typeof rawSuite.agentId === 'string' ? rawSuite.agentId : undefined);
+            agentId = preferred ? await this.resolveRemoteAgentId(preferred) : null;
+        }
+        else {
+            agentId = typeof rawSuite.agentId === 'string' && rawSuite.agentId.length > 0 ? rawSuite.agentId : null;
+        }
+        let cloudType = mode === 'CLOUD' ? 'VM' : 'NONE';
+        if (!agentId && typeof rawSuite.cloudAgentId === 'string' && rawSuite.cloudAgentId.length > 0) {
+            agentId = rawSuite.cloudAgentId;
+            cloudType = 'SQA';
+        }
+        const gc = rawSuite.globalConfiguration ?? {};
+        const body = {
             projectId,
-            executionId,
-            killType: 'STOP_EXECUTION',
-        });
+            environmentType: env,
+            executionStyle: (opts.strategy ?? 'serial').toUpperCase(),
+            executionOS: this.detectExecutionOS(),
+            executionTypeId: suiteNum,
+            executionTypeName: str(rawSuite, 'name') ?? '',
+            executionTypeCode: str(rawSuite, 'code') ?? '',
+            mailersList: rawSuite.mailersList ?? {},
+            cloudType,
+            mode,
+            executionCategory: 'EXECUTION',
+            releaseId: opts.releaseId ? Number.parseInt(opts.releaseId, 10) || 0 : 0,
+            iterationId: opts.sprintId ? Number.parseInt(opts.sprintId, 10) || 0 : 0,
+            executionTime: '',
+            status: 'INPROGRESS',
+            iterationsSelected: [],
+            result: '',
+            globalConfiguration: {
+                TERMINATE_ON_FAIL: opts.terminateOnFailure ?? gc.TERMINATE_ON_FAIL ?? false,
+                NEW_BROWSER_SESSION: gc.NEW_BROWSER_SESSION ?? false,
+                RE_EXECUTION_COUNT: gc.RE_EXECUTION_COUNT ?? 0,
+                RE_EXECUTION_TYPE: gc.RE_EXECUTION_TYPE ?? 'AFTER_TESTCASE',
+                MINIMUM_CONTAINER_COUNT: gc.MINIMUM_CONTAINER_COUNT ?? 1,
+                MAXIMUM_CONTAINER_COUNT: opts.maxConcurrent ?? gc.MAXIMUM_CONTAINER_COUNT ?? 5,
+            },
+            isRecordingEnabled: false,
+            offset: -(new Date().getTimezoneOffset()),
+            type: 'SUITE',
+            executionType: suiteType,
+            agentId,
+            executionItems,
+        };
+        const resp = await this.http.postJson('/exec/execution', body);
+        const d = resp?.data ?? resp;
+        const runId = str(d, 'id', 'executionId', '_id') ??
+            (typeof d?.id === 'number' ? String(d.id) : undefined) ??
+            (typeof d?.executionId === 'number' ? String(d.executionId) : undefined);
+        if (!runId)
+            throw new Error('startRun: backend accepted suite trigger but returned no run id.');
+        return { runId };
     }
     /** GET the agent /mcp with a 1s timeout. Any HTTP response (incl. 4xx from an MCP server rejecting
      *  a naked GET) proves the process is up; connect/DNS/timeout errors mean it is down. Replaces