genexus-mcp 3.2.3 → 3.3.0

package/cli/lib/update-check.js

@@ -44,7 +44,10 @@ function readCache() {
     try {
         const raw = fs.readFileSync(getCacheFile(), 'utf8');
         const data = JSON.parse(raw);
-        if (data && typeof data === 'object') return data;
+        if (data && typeof data === 'object'
+            && (data.package === undefined || data.package === NPM_PACKAGE)
+            && (data.channel === undefined || validateChannel(data.channel))
+            && parseSemver(data.latestVersion)) return data;
     } catch {
     }
     return null;
@@ -54,7 +57,9 @@ function writeCache(data) {
     try {
         const file = getCacheFile();
         fs.mkdirSync(path.dirname(file), { recursive: true });
-        fs.writeFileSync(file, JSON.stringify(data), 'utf8');
+        const tmp = `${file}.tmp-${process.pid}-${Date.now()}`;
+        fs.writeFileSync(tmp, JSON.stringify({ package: NPM_PACKAGE, channel: 'latest', ...data }), 'utf8');
+        fs.renameSync(tmp, file);
     } catch {
     }
 }
@@ -65,22 +70,42 @@ function stripV(v) {
 
 function parseSemver(v) {
     const s = stripV(v);
-    const m = /^(\d+)\.(\d+)\.(\d+)/.exec(s);
+    const m = /^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-((?:0|[1-9A-Za-z-][0-9A-Za-z-]*)(?:\.(?:0|[1-9A-Za-z-][0-9A-Za-z-]*))*))?(?:\+([0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*))?$/.exec(s);
     if (!m) return null;
-    return [Number(m[1]), Number(m[2]), Number(m[3])];
+    return { valid: true, major: Number(m[1]), minor: Number(m[2]), patch: Number(m[3]),
+        prerelease: m[4] ? m[4].split('.') : [], build: m[5] ? m[5].split('.') : [] };
 }
 
 function compareSemver(a, b) {
     const pa = parseSemver(a);
     const pb = parseSemver(b);
-    if (!pa || !pb) return 0;
-    for (let i = 0; i < 3; i += 1) {
-        if (pa[i] > pb[i]) return 1;
-        if (pa[i] < pb[i]) return -1;
+    if (!pa || !pb) return null;
+    for (const key of ['major', 'minor', 'patch']) {
+        if (pa[key] > pb[key]) return 1;
+        if (pa[key] < pb[key]) return -1;
+    }
+    if (pa.prerelease.length === 0 && pb.prerelease.length > 0) return 1;
+    if (pa.prerelease.length > 0 && pb.prerelease.length === 0) return -1;
+    for (let i = 0; i < Math.max(pa.prerelease.length, pb.prerelease.length); i += 1) {
+        if (i >= pa.prerelease.length) return -1;
+        if (i >= pb.prerelease.length) return 1;
+        const left = pa.prerelease[i];
+        const right = pb.prerelease[i];
+        if (left === right) continue;
+        const leftNum = /^\d+$/.test(left);
+        const rightNum = /^\d+$/.test(right);
+        if (leftNum && rightNum) return Number(left) > Number(right) ? 1 : -1;
+        if (leftNum !== rightNum) return leftNum ? -1 : 1;
+        return left > right ? 1 : -1;
     }
     return 0;
 }
 
+function validateChannel(channel) {
+    const value = typeof channel === 'string' ? channel.trim() : '';
+    return /^[A-Za-z0-9][A-Za-z0-9._-]*$/.test(value) ? value : null;
+}
+
 function httpGetJson(url) {
     return new Promise((resolve) => {
         let req;
@@ -112,13 +137,14 @@ function httpGetJson(url) {
 // api.github.com. Falls back to the GitHub releases API only for the default
 // channel. The release URL is derived from the version (no API call needed).
 async function fetchLatestRelease(opts = {}) {
-    const channel = (opts && opts.channel) || 'latest';
+    const channel = validateChannel((opts && opts.channel) || 'latest');
+    if (!channel) return null;
 
     // 1. npm registry dist-tags (lightweight: just the tag → version map).
     const tags = await httpGetJson(`https://registry.npmjs.org/-/package/${NPM_PACKAGE}/dist-tags`);
     if (tags && typeof tags === 'object') {
         const v = stripV(tags[channel] || '');
-        if (v) return { latestVersion: v, releaseUrl: releaseUrlForVersion(v), source: 'npm' };
+        if (parseSemver(v)) return { latestVersion: v, releaseUrl: releaseUrlForVersion(v), source: 'npm' };
         // Channel not found on npm — for non-default channels, that's a definitive "no".
         if (channel !== 'latest') return null;
     }
@@ -128,7 +154,7 @@ async function fetchLatestRelease(opts = {}) {
         const rel = await httpGetJson(`https://api.github.com/repos/${REPO}/releases/latest`);
         if (rel && typeof rel === 'object') {
             const tag = stripV(rel.tag_name || '');
-            if (tag) {
+            if (parseSemver(tag)) {
                 const url = typeof rel.html_url === 'string' ? rel.html_url : releaseUrlForVersion(tag);
                 return { latestVersion: tag, releaseUrl: url, source: 'github' };
             }
@@ -157,7 +183,7 @@ function maybePrintCachedBanner(_opts) {
     const current = getPackageVersion();
     if (!current) return;
     const cache = readCache();
-    if (!cache || !cache.latestVersion) return;
+    if (!cache || !cache.latestVersion || (cache.channel && cache.channel !== 'latest')) return;
     if (compareSemver(cache.latestVersion, current) > 0) {
         try {
             process.stderr.write(formatBanner(current, cache.latestVersion, cache.releaseUrl || null));
@@ -253,27 +279,29 @@ function detectInstallMethod() {
 // The method-appropriate upgrade plan. `auto` means no manual install step is
 // needed (the npx launcher fetches @latest on the next client start).
 function upgradePlanFor(method, channel) {
-    const tag = channel && channel !== 'latest' ? `@${channel}` : '@latest';
+    const resolvedChannel = channel || 'latest';
+    const tag = resolvedChannel !== 'latest' ? `@${resolvedChannel}` : '@latest';
     if (method === 'npx-latest') {
         return {
             method,
+            channel: resolvedChannel,
             auto: true,
             steps: [
-                'Your clients launch via `npx genexus-mcp@latest`, which fetches the newest version on each start.',
-                'Just fully restart your AI client — it will pick up the new version automatically.'
+                `Your clients launch via \`npx ${NPM_PACKAGE}${tag}\`, which fetches the newest ${resolvedChannel} version on each start.`,
+                'Just fully restart your AI client — it will pick up the selected channel automatically.'
             ],
-            // --apply busts a stale npx cache so the next spawn is guaranteed fresh.
-            applyCommand: { exe: process.platform === 'win32' ? 'npm.cmd' : 'npm', args: ['cache', 'clean', '--force'] },
+            applyCommand: null,
             restartRequired: true
         };
     }
     if (method === 'fixed-path') {
         return {
             method,
+            channel: resolvedChannel,
             auto: false,
             steps: [
-                'Your install runs the gateway from a fixed path (corporate install).',
-                `Re-run the installer to update in place: ${INSTALL_ONE_LINER}`,
+                `Your install runs the gateway from a fixed path (corporate install); npm ${tag} will not update that artifact.`,
+                `Re-run the fixed-path installer for the resolved ${resolvedChannel} release artifact${resolvedChannel === 'latest' ? '' : ` from channel \`${resolvedChannel}\``}: ${INSTALL_ONE_LINER}`,
                 'Then fully restart your AI client.'
             ],
             applyCommand: null, // self-stage is a future enhancement; installer is the path
@@ -284,6 +312,7 @@ function upgradePlanFor(method, channel) {
         const tag = channel && channel !== 'latest' ? `@${channel}` : '@latest';
         return {
             method,
+            channel: resolvedChannel,
             auto: false,
             steps: [
                 'Antigravity launches the gateway executable bundled with the npm package, so each MCP handshake skips npx.',
@@ -297,6 +326,7 @@ function upgradePlanFor(method, channel) {
     // npm-global
     return {
         method: 'npm-global',
+        channel: resolvedChannel,
         auto: false,
         steps: [
             `Run: npm install -g ${NPM_PACKAGE}${tag}`,
@@ -307,23 +337,37 @@ function upgradePlanFor(method, channel) {
     };
 }
 
-function runCommand(exe, args) {
+function runCommand(exe, args, options = {}) {
     return new Promise((resolve) => {
         let child;
+        let settled = false;
+        const finish = (result) => { if (!settled) { settled = true; resolve(result); } };
         try {
             child = spawn(exe, args, { stdio: 'inherit', windowsHide: true });
         } catch (err) {
-            resolve({ ok: false, code: null, error: err && err.message ? err.message : 'spawn failed' });
+            finish({ ok: false, code: null, error: err && err.message ? err.message : 'spawn failed' });
             return;
         }
-        child.on('error', (err) => resolve({ ok: false, code: null, error: err && err.message ? err.message : 'spawn failed' }));
-        child.on('exit', (code) => resolve({ ok: code === 0, code }));
+        let timedOut = false;
+        const timeoutMs = Number.isFinite(options.timeoutMs) ? Math.max(1, options.timeoutMs) : 120000;
+        const timer = setTimeout(() => {
+            timedOut = true;
+            try { child.kill(); } catch { /* process may have exited */ }
+        }, timeoutMs);
+        child.on('error', (err) => { clearTimeout(timer); finish({ ok: false, code: null, error: err && err.message ? err.message : 'spawn failed', timedOut }); });
+        child.on('exit', (code, signal) => {
+            clearTimeout(timer);
+            finish({ ok: !timedOut && code === 0, code: timedOut ? -1 : code, signal: signal || null, timedOut });
+        });
     });
 }
 
 async function handleUpdate(options, ctx) {
     const opts = options || {};
-    const channel = opts.channel || 'latest';
+    const channel = validateChannel(opts.channel || 'latest');
+    if (!channel) {
+        return { exitCode: ctx.EXIT_CODES.USAGE, envelope: { error: { code: 'invalid_channel', message: 'Channel must contain only letters, numbers, dots, underscores, or hyphens.' } } };
+    }
     const current = getPackageVersion();
     const result = await fetchLatestRelease({ channel });
     const mismatches = detectClientExeDrift();
@@ -346,8 +390,13 @@ async function handleUpdate(options, ctx) {
         };
     }
 
-    writeCache({ checkedAt: Date.now(), latestVersion: result.latestVersion, releaseUrl: result.releaseUrl, source: result.source || null });
+    writeCache({ checkedAt: Date.now(), latestVersion: result.latestVersion, releaseUrl: result.releaseUrl, source: result.source || null, channel });
 
+    const currentSemver = parseSemver(current || '0.0.0');
+    const latestSemver = parseSemver(result.latestVersion);
+    if (!latestSemver || !currentSemver) {
+        return { exitCode: ctx.EXIT_CODES.OK, envelope: { ok: { current, latest: result.latestVersion, channel, updateAvailable: false, invalidVersion: true }, help: ['Could not compare versions because the installed or published version is invalid semver.'] } };
+    }
     const updateAvailable = compareSemver(result.latestVersion, current || '0.0.0') > 0;
     const plan = upgradePlanFor(install.method, channel);
 
@@ -433,5 +482,7 @@ module.exports = {
     getPackageVersion,
     detectInstallMethod,
     upgradePlanFor,
-    fetchLatestRelease
+    fetchLatestRelease,
+    validateChannel,
+    runCommand
 };

package/cli/run.test.js

@@ -6,7 +6,14 @@ const path = require('node:path');
 const os = require('node:os');
 const fs = require('node:fs');
 const { renderOutput } = require('./lib/output');
-const { compareSemver, detectInstallMethod, upgradePlanFor } = require('./lib/update-check');
+const {
+    compareSemver,
+    parseSemver,
+    validateChannel,
+    detectInstallMethod,
+    upgradePlanFor,
+    runCommand
+} = require('./lib/update-check');
 const {
     detectClientInstalled,
     readJsonFileSafe,
@@ -1727,12 +1734,37 @@ test('clients remove drops both OpenCode config shapes and legacy key', () => {
     fs.rmSync(tempRoot, { recursive: true, force: true });
 });
 
-test('compareSemver detects newer, older, equal versions', () => {
-    assert.equal(compareSemver('1.3.1', '1.3.0'), 1);
-    assert.equal(compareSemver('v1.4.0', '1.3.9'), 1);
-    assert.equal(compareSemver('1.3.0', '1.3.0'), 0);
-    assert.equal(compareSemver('1.2.9', '1.3.0'), -1);
-    assert.equal(compareSemver('garbage', '1.0.0'), 0);
+test('strict semver compares prerelease precedence and ignores build metadata', () => {
+    assert.deepEqual(parseSemver('v1.2.3-alpha.1+build.7'), {
+        valid: true, major: 1, minor: 2, patch: 3,
+        prerelease: ['alpha', '1'], build: ['build', '7']
+    });
+    assert.equal(compareSemver('1.0.0-alpha', '1.0.0-alpha.1'), -1);
+    assert.equal(compareSemver('1.0.0', '1.0.0-rc.1'), 1);
+    assert.equal(compareSemver('1.0.0+one', '1.0.0+two'), 0);
+});
+
+test('semver and channel validation are explicit for malformed input', () => {
+    assert.equal(parseSemver('1.2'), null);
+    assert.equal(parseSemver('1.2.3-01'), null);
+    assert.equal(compareSemver('garbage', '1.0.0'), null);
+    assert.equal(validateChannel('latest'), 'latest');
+    assert.equal(validateChannel('next-2026'), 'next-2026');
+    assert.equal(validateChannel('bad channel'), null);
+    assert.equal(validateChannel(''), null);
+});
+
+test('npx update plan does not use npm cache clean as an update', () => {
+    const plan = upgradePlanFor('npx-latest', 'latest');
+    assert.equal(plan.applyCommand, null);
+    assert.equal(plan.auto, true);
+});
+
+test('runCommand reports exit code and kills timed out child', async () => {
+    const result = await runCommand(process.execPath, ['-e', 'setTimeout(() => {}, 1000)'], { timeoutMs: 30 });
+    assert.equal(result.ok, false);
+    assert.equal(result.timedOut, true);
+    assert.equal(typeof result.code, 'number');
 });
 
 test('detectInstallMethod returns fixed-path when GENEXUS_MCP_GATEWAY_EXE is set', () => {
@@ -1748,6 +1780,25 @@ test('detectInstallMethod returns fixed-path when GENEXUS_MCP_GATEWAY_EXE is set
     }
 });
 
+test('upgradePlanFor carries the selected channel through every install method', () => {
+    const npx = upgradePlanFor('npx-latest', 'next');
+    assert.equal(npx.channel, 'next');
+    assert.match(npx.steps.join(' '), /npx genexus-mcp@next/);
+    assert.doesNotMatch(npx.steps.join(' '), /@latest/);
+
+    const npm = upgradePlanFor('npm-global', 'next');
+    assert.equal(npm.channel, 'next');
+    assert.deepEqual(npm.applyCommand.args, ['install', '-g', 'genexus-mcp@next']);
+
+    const fixed = upgradePlanFor('fixed-path', 'next');
+    assert.equal(fixed.channel, 'next');
+    assert.match(fixed.steps.join(' '), /next/);
+    assert.doesNotMatch(fixed.steps.join(' '), /npm @latest/);
+
+    const direct = upgradePlanFor('package-direct', 'next');
+    assert.equal(direct.channel, 'next');
+});
+
 test('upgradePlanFor encodes the per-method upgrade strategy', () => {
     const npx = upgradePlanFor('npx-latest', 'latest');
     assert.equal(npx.auto, true, 'npx@latest auto-updates on restart');

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "genexus-mcp",
-  "version": "3.2.3",
+  "version": "3.3.0",
   "mcpName": "io.github.lennix1337/genexus",
   "description": "GeneXus 17, GeneXus 18 MCP server — read, edit, and analyze Knowledge Base objects directly from Claude, Cursor, and other AI agents over the Model Context Protocol.",
   "keywords": [

package/publish/GxMcp.Gateway.deps.json

@@ -7,7 +7,7 @@
   "targets": {
     ".NETCoreApp,Version=v10.0": {},
     ".NETCoreApp,Version=v10.0/win-x64": {
-      "GxMcp.Gateway/3.2.3": {
+      "GxMcp.Gateway/3.3.0": {
         "dependencies": {
           "Newtonsoft.Json": "13.0.3",
           "System.Management": "10.0.5",
@@ -66,7 +66,7 @@
     }
   },
   "libraries": {
-    "GxMcp.Gateway/3.2.3": {
+    "GxMcp.Gateway/3.3.0": {
       "type": "project",
       "serviceable": false,
       "sha512": ""

package/publish/config.json

@@ -1,19 +1,19 @@
 {
+  "GatewayMode": "stdio-isolated",
   "Server": {
+    "EmitStructuredContent": false,
+    "McpStdio": true,
+    "WorkerIdleTimeoutMinutes": 5,
     "TerseResponses": true,
     "HttpPort": 0,
-    "WorkerIdleTimeoutMinutes": 5,
-    "SessionIdleTimeoutMinutes": 10,
-    "McpStdio": true,
-    "EmitStructuredContent": false
+    "SessionIdleTimeoutMinutes": 10
   },
   "ConfigSchemaVersion": 2,
-  "GatewayMode": "stdio-isolated",
-  "Environment": {
-    "ResolutionPolicy": "strict"
-  },
   "GeneXus": {
     "WorkerExecutable": "worker\\\\GxMcp.Worker.exe",
     "InstallationPath": "C:\\Program Files (x86)\\GeneXus\\GeneXus18"
+  },
+  "Environment": {
+    "ResolutionPolicy": "strict"
   }
 }

package/publish/gxmcp-manifest.json

@@ -1,9 +1,9 @@
 {
   "schemaVersion": "gxmcp-release-manifest/1",
-  "version": "3.2.3",
-  "sourceCommit": "0bcc6f37877d50044014a7f20fd6e9f7a0e1ae14",
+  "version": "3.3.0",
+  "sourceCommit": "6d2f307d10ca718c6dbec8682c0a1678eb90818b",
   "sourceCommitPolicy": "exact-tag",
-  "generatedAtUtc": "2026-09-10T20:43:41.1004001Z",
+  "generatedAtUtc": "2026-09-11T03:19:49.1965424Z",
   "runtime": {
     "gateway": "net10.0-windows",
     "worker": "net48-x86",
@@ -15,33 +15,28 @@
     "2026-07-28"
   ],
   "schema": "tool_definitions.json",
-  "schemaSha256": "19f5c0f9b52f2b387270819dea27d14423577518238e8fb8d4a1399ae515a093",
+  "schemaSha256": "5624f61d5e5cabd8cd1beb4f05aa1925735e407814aeafa17e860c1601dd867c",
   "provenance": "gxmcp-sbom.json",
   "artifacts": [
     {
       "path": "gxmcp-sbom.json",
       "size": 590,
-      "sha256": "aa7d53299198de5cc9dcd25c9f09c9e8181a508fe0492b5afabc175e49a7b4b8"
+      "sha256": "cdbc21566af312db105a3c964a9df0462dd2cf473f80efa21d8605307ea893a9"
     },
     {
       "path": "GxMcp.Gateway.exe",
       "size": 162304,
-      "sha256": "6d75af98c0b362070def957150d600fef4da61410c4d9114f200c70f1f389ea0"
-    },
-    {
-      "path": "nexus-ide.vsix",
-      "size": 1318670,
-      "sha256": "199d49959a1b5a5de20511a0b9a312955499d8c216fe66a4ed39c1f2e17d39ee"
+      "sha256": "e75f60b4cbd28abcaf15d4dd80f1e966b79f078b4155b29f035501686414837b"
     },
     {
       "path": "tool_definitions.json",
-      "size": 110245,
-      "sha256": "19f5c0f9b52f2b387270819dea27d14423577518238e8fb8d4a1399ae515a093"
+      "size": 111992,
+      "sha256": "5624f61d5e5cabd8cd1beb4f05aa1925735e407814aeafa17e860c1601dd867c"
     },
     {
       "path": "worker/GxMcp.Worker.exe",
-      "size": 3008512,
-      "sha256": "2f994a3cc389bc44d26cdee568a2ecc7c7a6dd9f13fc8f6c4d9d942d73158a3c"
+      "size": 3082240,
+      "sha256": "d66461633c93c8e82a957b15aca6706ac87a1ea6433ae6bc7c855d1180548e1b"
     }
   ]
 }

package/publish/gxmcp-sbom.json

@@ -1,20 +1,20 @@
 {
   "schemaVersion": "gxmcp-provenance/1",
-  "version": "3.2.3",
-  "sourceCommit": "0bcc6f37877d50044014a7f20fd6e9f7a0e1ae14",
+  "version": "3.3.0",
+  "sourceCommit": "6d2f307d10ca718c6dbec8682c0a1678eb90818b",
   "sourceCommitPolicy": "exact-tag",
   "components": [
     {
       "name": "genexus-mcp",
       "lockfile": "package-lock.json",
       "size": 39914,
-      "sha256": "d20a44b0c283f40e88defc129beb4aa217ea54080881ba9bbc6aa10990325928"
+      "sha256": "778573945c8e74dc124ea99ed313ea99ab45b44aa600977f8094afd18fa8b9af"
     },
     {
       "name": "nexus-ide",
       "lockfile": "src/nexus-ide/package-lock.json",
       "size": 274983,
-      "sha256": "5ac50a4c0a24fff98bb4dac35ffae1325f00dcd5f53bc5cb626b6d5c46f5a955"
+      "sha256": "ed6d742540a8e833f2c2ad5c51f46be23a97e2d80b892d71891f5f61f5f4728c"
     }
   ]
 }

package/publish/tool_definitions.json

@@ -48,7 +48,7 @@
   {"name":"genexus_transfer","description":"Real XPZ export/import over the SDK's IKnowledgeManagerService — dependency-aware, IDE Export/Import parity (NOT the filesystem copy genexus_io/kb_import do). action=export (targets[]+outputFile; includeDependencies=true exports transitive closure) | inspect (explore an .xpz, read-only) | import (apply into KB; dryRun defaults true=preview via ExploreExport; dryRun=false requires confirm=true).","inputSchema":{"type":"object","required":["action"],"properties":{"action":{"type":"string","enum":["export","inspect","import"],"description":"XPZ export, inspection, or import operation to perform."},"targets":{"type":"array","items":{"type":"string"},"description":"export: object names to export."},"outputFile":{"type":"string","description":"export: absolute .xpz output path."},"includeDependencies":{"type":"boolean","description":"export: compute transitive dependency closure (Calls, Tables) and export all referenced objects.","default":false},"file":{"type":"string","description":"inspect/import: absolute .xpz path."},"type":{"type":"string","description":"export: disambiguate object type."},"dryRun":{"type":"boolean","description":"import: true (default) previews; false applies (needs confirm)."},"confirm":{"type":"boolean","description":"import with dryRun=false: required."},"kb":{"type":"string","description":"KB alias."}},"examples":[{"action":"export","targets":["Customer"],"outputFile":"C:\\tmp\\cust.xpz"},{"action":"export","targets":["Customer"],"outputFile":"C:\\tmp\\cust_full.xpz","includeDependencies":true},{"action":"inspect","file":"C:\\tmp\\cust.xpz"}]},"annotations":{"readOnlyHint":false,"destructiveHint":true,"idempotentHint":false,"openWorldHint":false}},
   {"name":"genexus_deploy","description":"Deploy application over the SDK. action=list_targets (read-only, default) enumerates deployment target types (IDeploymentTargetService); action=deploy (destructive, confirm=true) runs IDeploymentService.Deploy(model).","inputSchema":{"type":"object","properties":{"action":{"type":"string","enum":["list_targets","deploy"],"description":"Deployment-target or deployment execution operation to perform."},"confirm":{"type":"boolean","description":"deploy: required (builds + ships the app)."},"kb":{"type":"string","description":"KB alias."}},"examples":[{"action":"list_targets"},{"action":"deploy","confirm":true}]},"annotations":{"readOnlyHint":false,"destructiveHint":true,"idempotentHint":false,"openWorldHint":false}},
   {"name":"genexus_generator_reference","description":"Native typed .NET generator references used by GxExternalReference. list and dry-run actions are read-only. add/remove validate a managed assembly when a path is supplied, require optimistic baseVersion for changes, save only the native GeneratorsPart, reread it, and restore the complete generator-property snapshot on verification failure. No lifecycle action runs implicitly.","inputSchema":{"type":"object","additionalProperties":false,"required":["action","environment","generator"],"properties":{"action":{"type":"string","enum":["list","dry_run_add","add","dry_run_remove","remove"],"description":"Typed .NET generator-reference operation to perform."},"environment":{"type":"string","description":"Active GeneXus Environment name; the tool never switches environments."},"generator":{"type":"string","description":"Generator display name, e.g. Default (.NET)."},"assembly":{"type":"string","description":"Assembly file name for add/remove, e.g. SpreadsheetLibrary.dll."},"assemblyPath":{"type":"string","description":"Absolute path or KB-relative path used to validate a managed assembly. Required for add unless found in a standard model/bin location."},"baseVersion":{"type":"string","description":"Optimistic token returned by list or a dry-run. Required for a real state change."},"dryRun":{"type":"boolean","default":false,"description":"Force add/remove to remain read-only."},"rollbackOnFailure":{"type":"boolean","default":true,"description":"Restore and verify the complete prior generator-property snapshot if save/reread diverges."},"kb":{"type":"string","description":"KB alias."}},"examples":[{"action":"list","environment":".Net Environment","generator":"Default (.NET)"},{"action":"dry_run_add","environment":".Net Environment","generator":"Default (.NET)","assembly":"SpreadsheetLibrary.dll","assemblyPath":"C:\\KBs\\Sample\\CSharpModel\\web\\bin\\SpreadsheetLibrary.dll"},{"action":"add","environment":".Net Environment","generator":"Default (.NET)","assembly":"SpreadsheetLibrary.dll","assemblyPath":"C:\\KBs\\Sample\\CSharpModel\\web\\bin\\SpreadsheetLibrary.dll","baseVersion":"sha256:<token>","rollbackOnFailure":true}]},"annotations":{"readOnlyHint":false,"destructiveHint":true,"idempotentHint":true,"openWorldHint":false}},
-  {"name":"genexus_wwp","description":"Typed WorkWithPlus action, tab, and grid edits with dryRun, optimistic concurrency, exact snapshots, post-save reread, projection verification, and rollback. No lifecycle operation is implicit. Settings: SDK tree and dryRun only; save refused until event isolation is certified.","inputSchema":{"type":"object","required":["action"],"properties":{"action":{"type":"string","enum":["list","add_action","update_action","move_action","remove_action","add_tab","move_tab","remove_tab","add_grid_attribute","settings_templates","settings_read","settings_edit"],"description":"WorkWithPlus action-group, tab, or grid-attribute operation to perform."},"name":{"type":"string","description":"Transaction, WebPanel, or WorkWithPlus<Object> host."},"group":{"type":"string","description":"Action group name. add_action creates it when absent; update/remove use it as a filter."},"actionName":{"type":"string","description":"Action name."},"attribute":{"type":"string","description":"add_grid_attribute: GeneXus Attribute name."},"caption":{"type":"string","description":"Action or grid-column caption."},"procedure":{"type":"string","description":"add/update: associated Procedure; existence is validated against the KB."},"selection":{"type":"string","enum":["single","multiple"],"description":"add/update: execution scope for grid actions."},"enabledWhen":{"type":"string","description":"Availability condition stored verbatim; expression semantics are not validated."},"icon":{"type":"string","description":"add/update: button icon."},"description":{"type":"string","description":"add/update: tooltip or description."},"confirm":{"type":"boolean","description":"Confirmation prompt; required to delete unless dryRun."},"buttonClass":{"type":"string","description":"add/update: theme button class."},"position":{"type":"integer","minimum":0,"description":"Zero-based action or tab index."},"toGroup":{"type":"string","description":"move_action: destination group (created when absent)."},"fromGroup":{"type":"string","description":"move_action: source group (optional; searched across groups when omitted)."},"dryRun":{"type":"boolean","description":"Return a typed diff and versionToken without mutation."},"controlName":{"type":"string","description":"Tab ControlName."},"title":{"type":"string","description":"add_tab: tab title."},"children":{"type":"array","description":"add_tab controls; flat children are wrapped in a responsive table.","items":{"$ref":"#/$defs/wwpControl"}},"baseVersion":{"type":"string","description":"Optimistic-concurrency token returned by dryRun/read."},"expectedVersion":{"type":"string","description":"Alias for baseVersion."},"versionToken":{"type":"string","description":"Backward-compatible alias for baseVersion."},"kb":{"type":"string","description":"KB alias."},"template":{"description":"Settings template catalog path or unique internal name.","type":"string"},"limit":{"type":"integer","minimum":0,"description":"Settings nodes per page; 0 reads all."},"guid":{"type":"string"},"nodePath":{"description":"Settings node path returned by settings_read.","type":"string"},"entityKey":{"type":"string"},"value":{"type":"string"},"property":{"description":"Exact SDK property name.","type":"string"},"offset":{"minimum":0,"type":"integer"}},"$defs":{"wwpControl":{"type":"object","required":["type"],"properties":{"type":{"type":"string","enum":["variable","userAction","table"]},"name":{"type":"string"},"caption":{"type":"string"},"description":{"type":"string"},"basicType":{"type":"string"},"length":{"type":"integer","minimum":1},"decimals":{"type":"integer","minimum":0},"controlType":{"type":"string"},"controlValues":{"type":"string"},"controlEmptyItem":{"type":"boolean"},"controlEmptyItemText":{"type":"string"},"columns":{"type":"integer","minimum":1},"themeClass":{"type":"string"},"children":{"type":"array","items":{"$ref":"#/$defs/wwpControl"}}},"additionalProperties":false}},"examples":[{"action":"list","name":"SampleOrderWW"},{"action":"add_action","name":"SampleOrderWW","group":"Operations","actionName":"Retry","procedure":"RetrySampleOrder","selection":"multiple","dryRun":true},{"action":"add_tab","name":"SamplePanel","controlName":"Details","title":"Details","children":[{"type":"variable","name":"Status","basicType":"VarChar","length":40},{"type":"userAction","name":"Refresh","caption":"Refresh"}],"dryRun":true},{"action":"add_grid_attribute","name":"SampleOrderWW","attribute":"SampleOrderStatus","caption":"Status","dryRun":true}]},"annotations":{"readOnlyHint":false,"destructiveHint":true,"idempotentHint":false,"openWorldHint":false}},
+  {"name":"genexus_wwp","description":"Typed WorkWithPlus action, tab, grid, and native structural edits with dryRun, optimistic concurrency, exact snapshots, post-save reread, projection verification, and rollback. No lifecycle operation is implicit. Settings: embedded and separate WWP templates, paged reads and exact table-class dryRun; saves remain blocked.","inputSchema":{"type":"object","required":["action"],"properties":{"action":{"type":"string","enum":["list","add_action","update_action","move_action","remove_action","add_tab","move_tab","remove_tab","add_grid_attribute","replace_web_component_with_user_action","settings_templates","settings_read","settings_edit"],"description":"WorkWithPlus action-group, tab, grid-attribute, or explicit native structural operation to perform."},"name":{"type":"string","description":"Transaction, WebPanel, or WorkWithPlus<Object> host."},"group":{"type":"string","description":"Action group name. add_action creates it when absent; update/remove use it as a filter."},"actionName":{"type":"string","description":"Action name."},"attribute":{"type":"string","description":"add_grid_attribute: GeneXus Attribute name."},"caption":{"type":"string","description":"Action caption. For a DropDownComponent pass the GeneXus expression used for the closed button, for example &Context.EmpresaDescricao."},"procedure":{"type":"string","description":"add/update: associated Procedure; existence is validated against the KB."},"selection":{"type":"string","enum":["single","multiple"],"description":"add/update: execution scope for grid actions."},"enabledWhen":{"type":"string","description":"Availability condition stored verbatim; expression semantics are not validated."},"icon":{"type":"string","description":"add/update: button icon."},"description":{"type":"string","description":"add/update: tooltip or description."},"confirm":{"type":"boolean","description":"Confirmation prompt; required to delete unless dryRun."},"buttonClass":{"type":"string","description":"add/update: theme button class."},"position":{"type":"integer","minimum":0,"description":"Zero-based action or tab index."},"toGroup":{"type":"string","description":"move_action: destination group (created when absent)."},"fromGroup":{"type":"string","description":"move_action: source group (optional; searched across groups when omitted)."},"dryRun":{"type":"boolean","description":"Return a typed diff and versionToken without mutation."},"controlName":{"type":"string","description":"Tab ControlName."},"title":{"type":"string","description":"add_tab: tab title."},"children":{"type":"array","description":"add_tab controls; flat children are wrapped in a responsive table.","items":{"$ref":"#/$defs/wwpControl"}},"sourceName":{"type":"string","description":"replace_web_component_with_user_action: existing WebComponent name."},"userActionName":{"type":"string","description":"replace_web_component_with_user_action: resulting UserAction name; defaults to sourceName."},"tablePath":{"type":"string","description":"replace_web_component_with_user_action: full breadcrumb including the source node, for example TableHeader > TableUserRole > EmpresaSelector."},"gxobject":{"type":"string","description":"replace_web_component_with_user_action: existing WebComponent Gxobject to retain; it must match the current node."},"controlType":{"type":"string","enum":["DropDownComponent"],"description":"replace_web_component_with_user_action: resulting UserAction ControlType."},"webComponentLoad":{"type":"string","enum":["On Web Panel load","On first click","On every click"],"description":"DropDownComponent load timing."},"trigger":{"type":"string","enum":["Click","Hover"],"description":"DropDownComponent trigger."},"baseVersion":{"type":"string","description":"Optimistic-concurrency token returned by dryRun/read."},"expectedVersion":{"type":"string","description":"Alias for baseVersion."},"versionToken":{"type":"string","description":"Backward-compatible alias for baseVersion."},"kb":{"type":"string","description":"KB alias."},"template":{"description":"Settings catalog path, wwp:<template-guid>, or unique template name.","type":"string"},"limit":{"type":"integer","minimum":0,"description":"Settings nodes per page; offset=0, limit=0 includes full separate-template XML."},"guid":{"type":"string","description":"Pattern Settings object GUID for settings_* actions."},"nodePath":{"description":"Settings node path returned by settings_read.","type":"string"},"entityKey":{"type":"string"},"value":{"type":"string"},"property":{"description":"Exact SDK property name.","type":"string"},"offset":{"minimum":0,"type":"integer"}},"$defs":{"wwpControl":{"type":"object","required":["type"],"properties":{"type":{"type":"string","enum":["variable","userAction","table"]},"name":{"type":"string"},"caption":{"type":"string"},"description":{"type":"string"},"basicType":{"type":"string"},"length":{"type":"integer","minimum":1},"decimals":{"type":"integer","minimum":0},"controlType":{"type":"string"},"controlValues":{"type":"string"},"controlEmptyItem":{"type":"boolean"},"controlEmptyItemText":{"type":"string"},"columns":{"type":"integer","minimum":1},"themeClass":{"type":"string"},"children":{"type":"array","items":{"$ref":"#/$defs/wwpControl"}}},"additionalProperties":false}},"examples":[{"action":"list","name":"SampleOrderWW"},{"action":"add_action","name":"SampleOrderWW","group":"Operations","actionName":"Retry","procedure":"RetrySampleOrder","selection":"multiple","dryRun":true},{"action":"add_tab","name":"SamplePanel","controlName":"Details","title":"Details","children":[{"type":"variable","name":"Status","basicType":"VarChar","length":40},{"type":"userAction","name":"Refresh","caption":"Refresh"}],"dryRun":true},{"action":"add_grid_attribute","name":"SampleOrderWW","attribute":"SampleOrderStatus","caption":"Status","dryRun":true},{"action":"replace_web_component_with_user_action","name":"WorkWithPlusWorkWithPlusMasterPage","sourceName":"EmpresaSelector","userActionName":"EmpresaSelector","tablePath":"TableHeader > TableUserRole > EmpresaSelector","gxobject":"WWP_MasterPageEmpresaSelectorWC","controlType":"DropDownComponent","caption":"&Context.EmpresaDescricao","webComponentLoad":"On every click","trigger":"Click","dryRun":true}]},"annotations":{"readOnlyHint":false,"destructiveHint":true,"idempotentHint":false,"openWorldHint":false}},
   {"name":"genexus_kb_diff","description":"Gateway-only filesystem comparison of two KB directories. Requires kbA and kbB aliases or paths; no active KB selection is used.","inputSchema":{"type":"object","required":["kbA","kbB"],"properties":{"kbA":{"type":"string"},"kbB":{"type":"string"}},"examples":[{"kbA":"development","kbB":"staging"}]},"annotations":{"readOnlyHint":true,"destructiveHint":false,"idempotentHint":true,"openWorldHint":false}},
   {"name":"genexus_kb_import","description":"Gateway-only filesystem copy of one object between two KB directories. Requires source and object identity; run lifecycle index afterwards.","inputSchema":{"type":"object","required":["from","name","type"],"properties":{"from":{"type":"string"},"name":{"type":"string"},"type":{"type":"string"},"to":{"type":"string"}},"examples":[{"from":"C:\\KBs\\source","to":"C:\\KBs\\target","name":"Customer","type":"Transaction"}]},"annotations":{"readOnlyHint":false,"destructiveHint":true,"idempotentHint":true,"openWorldHint":false}},
   {"name":"genexus_sandbox","description":"Gateway-only filesystem sandbox management; clone or remove a KB directory without SDK dispatch.","inputSchema":{"type":"object","required":["action","name"],"properties":{"action":{"type":"string","enum":["create","remove"]},"name":{"type":"string"},"from":{"type":"string"},"overwrite":{"type":"boolean"}},"examples":[{"action":"create","name":"probe","from":"C:\\KBs\\base"},{"action":"remove","name":"probe"}]},"annotations":{"readOnlyHint":false,"destructiveHint":true,"idempotentHint":true,"openWorldHint":false}},