@provartesting/provardx-cli 1.5.0-dev.2 → 1.5.0

package/lib/mcp/tools/nitroXTools.js

@@ -0,0 +1,823 @@
+/*
+ * Copyright (c) 2024 Provar Limited.
+ * All rights reserved.
+ * Licensed under the BSD 3-Clause license.
+ * For full license text, see LICENSE.md file in the repo root or https://opensource.org/licenses/BSD-3-Clause
+ */
+/* eslint-disable camelcase */
+import fs from 'node:fs';
+import path from 'node:path';
+import os from 'node:os';
+import { randomUUID } from 'node:crypto';
+import { fileURLToPath } from 'node:url';
+import { Ajv2020 } from 'ajv/dist/2020.js';
+import { z } from 'zod';
+import { assertPathAllowed, PathPolicyError } from '../security/pathPolicy.js';
+import { makeError, makeRequestId } from '../schemas/common.js';
+import { log } from '../logging/logger.js';
+function isObj(v) {
+    return typeof v === 'object' && v !== null && !Array.isArray(v);
+}
+// ── AJV Schema Validator ──────────────────────────────────────────────────────
+const RULES_DIR = path.join(path.dirname(fileURLToPath(import.meta.url)), '..', 'rules');
+let cachedFactComponentValidator;
+function getFactComponentValidator() {
+    if (cachedFactComponentValidator !== undefined)
+        return cachedFactComponentValidator;
+    const schemaPath = path.join(RULES_DIR, 'FactComponent.schema.json');
+    try {
+        // Fix known broken $ref in the bundled schema (#/defs/ → #/$defs/)
+        const patched = fs.readFileSync(schemaPath, 'utf-8').replace(/"#\/defs\//g, '"#/$defs/');
+        const schema = JSON.parse(patched);
+        const ajv = new Ajv2020({ allErrors: true, strict: false, validateFormats: false });
+        cachedFactComponentValidator = ajv.compile(schema);
+    }
+    catch (e) {
+        log('warn', 'provar_nitrox_validate: FactComponent schema unavailable, using hardcoded rules only', {
+            error: String(e),
+        });
+        cachedFactComponentValidator = null;
+    }
+    return cachedFactComponentValidator;
+}
+function ajvErrorToIssue(err) {
+    const keyword = err.keyword.replace(/([a-z])([A-Z])/g, '$1_$2').toUpperCase();
+    const instancePath = err.instancePath;
+    // For additionalProperties/required, instancePath points to the parent object;
+    // the actual property name is in err.params.
+    const params = err.params;
+    const extraProp = err.keyword === 'additionalProperties' ? params['additionalProperty'] : undefined;
+    const missingProp = err.keyword === 'required' ? params['missingProperty'] : undefined;
+    const leafProp = extraProp ?? missingProp;
+    const basePath = instancePath ? instancePath.replace(/^\//, '').replace(/\//g, '.') : 'root';
+    const appliesTo = leafProp ? (basePath === 'root' ? leafProp : `${basePath}.${leafProp}`) : basePath;
+    const pathParts = instancePath.split('/').filter(Boolean);
+    const severity = ['REQUIRED', 'TYPE'].includes(keyword) ? 'ERROR' : 'WARNING';
+    const issue = {
+        rule_id: `NX_SCHEMA_${keyword}`,
+        severity,
+        message: `Schema: ${instancePath || 'root'} — ${err.message ?? 'validation failed'}`,
+        applies_to: appliesTo,
+    };
+    issue.field = leafProp ?? (pathParts.length > 0 ? pathParts[pathParts.length - 1] : undefined);
+    return issue;
+}
+// ── Directory Utilities ───────────────────────────────────────────────────────
+const SKIP_DIRS = new Set(['node_modules', '.git']);
+/**
+ * Recursively walk directories looking for .testproject marker files.
+ * Skips node_modules, .git, and hidden dirs (names starting with '.').
+ */
+function findProvarProjects(roots, maxDepth) {
+    const projects = [];
+    function walk(dir, depth) {
+        if (depth > maxDepth)
+            return;
+        if (fs.existsSync(path.join(dir, '.testproject'))) {
+            projects.push(dir);
+            return; // don't recurse into a found project
+        }
+        let entries;
+        try {
+            entries = fs.readdirSync(dir, { withFileTypes: true });
+        }
+        catch {
+            return;
+        }
+        for (const entry of entries) {
+            if (!entry.isDirectory())
+                continue;
+            if (entry.name.startsWith('.') || SKIP_DIRS.has(entry.name))
+                continue;
+            walk(path.join(dir, entry.name), depth + 1);
+        }
+    }
+    for (const root of roots) {
+        try {
+            if (!fs.existsSync(root))
+                continue;
+            walk(root, 0);
+        }
+        catch {
+            // Root inaccessible — skip gracefully
+        }
+    }
+    return projects;
+}
+/** Collect all *.po.json files under a directory, recursively. */
+function collectPoJsonFiles(dir) {
+    const files = [];
+    function walk(d) {
+        let entries;
+        try {
+            entries = fs.readdirSync(d, { withFileTypes: true });
+        }
+        catch {
+            return;
+        }
+        for (const entry of entries) {
+            if (entry.isDirectory()) {
+                walk(path.join(d, entry.name));
+            }
+            else if (entry.isFile() && entry.name.endsWith('.po.json')) {
+                files.push(path.join(d, entry.name));
+            }
+        }
+    }
+    walk(dir);
+    return files;
+}
+// ── NitroX Validator ─────────────────────────────────────────────────────────
+const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+const VALID_COMPARISON_TYPES = ['equals', 'starts-with', 'contains'];
+const INTERACTION_NAME_RE = /^[A-Za-z0-9\s]*$/;
+/** Validate root-level scalar properties (NX001, NX002, NX003, NX010). */
+function validateRootProperties(obj, issues) {
+    // NX001: componentId must be present and a valid UUID
+    if (obj['componentId'] === undefined || obj['componentId'] === null) {
+        issues.push({
+            rule_id: 'NX001',
+            severity: 'ERROR',
+            message: 'componentId is required.',
+            applies_to: 'root',
+            field: 'componentId',
+        });
+    }
+    else if (typeof obj['componentId'] !== 'string' || !UUID_RE.test(obj['componentId'])) {
+        issues.push({
+            rule_id: 'NX001',
+            severity: 'ERROR',
+            message: `componentId must be a valid UUID, got: "${String(obj['componentId'])}".`,
+            applies_to: 'root',
+            field: 'componentId',
+        });
+    }
+    // NX002: Root (no parentId) requires name, type, pageStructureElement, fieldDetailsElement
+    const hasParentId = obj['parentId'] !== undefined && obj['parentId'] !== null;
+    if (!hasParentId) {
+        for (const field of ['name', 'type', 'pageStructureElement', 'fieldDetailsElement']) {
+            if (obj[field] === undefined || obj[field] === null) {
+                issues.push({
+                    rule_id: 'NX002',
+                    severity: 'ERROR',
+                    message: `Root component requires "${field}".`,
+                    applies_to: 'root',
+                    field,
+                    suggestion: `Add a "${field}" property to the root component object.`,
+                });
+            }
+        }
+    }
+    // NX003: tagName must not contain whitespace
+    if (typeof obj['tagName'] === 'string' && /\s/.test(obj['tagName'])) {
+        issues.push({
+            rule_id: 'NX003',
+            severity: 'ERROR',
+            message: 'tagName should not contain spaces.',
+            applies_to: 'root',
+            field: 'tagName',
+            suggestion: 'Remove whitespace from tagName.',
+        });
+    }
+    // NX010: bodyTagName (if present) must not contain whitespace
+    if (typeof obj['bodyTagName'] === 'string' && /\s/.test(obj['bodyTagName'])) {
+        issues.push({
+            rule_id: 'NX010',
+            severity: 'INFO',
+            message: 'bodyTagName should not contain spaces.',
+            applies_to: 'root',
+            field: 'bodyTagName',
+            suggestion: 'Remove whitespace from bodyTagName.',
+        });
+    }
+}
+/** Validate a parsed NitroX .po.json against hardcoded NX rules and the FactComponent JSON schema. */
+export function validateNitroXContent(obj, schemaOverride) {
+    const issues = [];
+    validateRootProperties(obj, issues);
+    if (Array.isArray(obj['parameters'])) {
+        for (const param of obj['parameters']) {
+            if (isObj(param))
+                validateParameter(param, 'root', issues);
+        }
+    }
+    if (Array.isArray(obj['interactions'])) {
+        for (const interaction of obj['interactions']) {
+            if (isObj(interaction))
+                validateInteraction(interaction, 'root', issues);
+        }
+    }
+    if (Array.isArray(obj['selectors'])) {
+        for (const sel of obj['selectors']) {
+            if (isObj(sel))
+                validateSelector(sel, issues);
+        }
+    }
+    if (Array.isArray(obj['elements'])) {
+        for (const el of obj['elements']) {
+            if (isObj(el))
+                validateElement(el, issues);
+        }
+    }
+    // AJV schema validation runs additively alongside NX001–NX010
+    const validator = schemaOverride === undefined ? getFactComponentValidator() : schemaOverride;
+    if (validator) {
+        validator(obj);
+        for (const err of validator.errors ?? []) {
+            issues.push(ajvErrorToIssue(err));
+        }
+    }
+    const errorCount = issues.filter((i) => i.severity === 'ERROR').length;
+    const warningCount = issues.filter((i) => i.severity === 'WARNING').length;
+    const infoCount = issues.filter((i) => i.severity === 'INFO').length;
+    const score = Math.max(0, 100 - 20 * errorCount - 5 * warningCount - 1 * infoCount);
+    return { valid: errorCount === 0, score, issue_count: issues.length, issues };
+}
+function validateElement(el, issues) {
+    // NX007: Element should have type
+    if (!el['type']) {
+        issues.push({
+            rule_id: 'NX007',
+            severity: 'WARNING',
+            message: 'Element is missing required "type".',
+            applies_to: 'element',
+            suggestion: 'Add a "type" field to the element (e.g. "content" or "component::UUID").',
+        });
+    }
+    if (Array.isArray(el['selectors'])) {
+        for (const sel of el['selectors']) {
+            if (isObj(sel))
+                validateSelector(sel, issues);
+        }
+    }
+    if (Array.isArray(el['interactions'])) {
+        for (const interaction of el['interactions']) {
+            if (isObj(interaction))
+                validateInteraction(interaction, 'element', issues);
+        }
+    }
+    if (Array.isArray(el['parameters'])) {
+        for (const param of el['parameters']) {
+            if (isObj(param))
+                validateParameter(param, 'element', issues);
+        }
+    }
+    if (Array.isArray(el['elements'])) {
+        for (const nested of el['elements']) {
+            if (isObj(nested))
+                validateElement(nested, issues);
+        }
+    }
+}
+function validateInteraction(interaction, context, issues) {
+    // NX004: required fields
+    for (const field of ['defaultInteraction', 'interactionType', 'name', 'testStepTitlePattern', 'title']) {
+        if (interaction[field] === undefined || interaction[field] === null) {
+            issues.push({
+                rule_id: 'NX004',
+                severity: 'ERROR',
+                message: `Interaction in ${context} missing required field "${field}".`,
+                applies_to: 'interaction',
+                field,
+            });
+        }
+    }
+    if (!Array.isArray(interaction['implementations']) || interaction['implementations'].length === 0) {
+        issues.push({
+            rule_id: 'NX004',
+            severity: 'ERROR',
+            message: `Interaction in ${context} must have at least one implementation.`,
+            applies_to: 'interaction',
+            field: 'implementations',
+        });
+    }
+    else {
+        for (const impl of interaction['implementations']) {
+            if (isObj(impl))
+                validateImplementation(impl, context, issues);
+        }
+    }
+    // NX009: name should match ^[A-Za-z0-9\s]*$
+    if (typeof interaction['name'] === 'string' && !INTERACTION_NAME_RE.test(interaction['name'])) {
+        issues.push({
+            rule_id: 'NX009',
+            severity: 'INFO',
+            message: `Interaction name "${interaction['name']}" should contain only alphanumeric characters and spaces.`,
+            applies_to: 'interaction',
+            field: 'name',
+            suggestion: 'Remove special characters from the interaction name.',
+        });
+    }
+}
+function validateImplementation(impl, context, issues) {
+    // NX005: must have javaScriptSnippet
+    if (!impl['javaScriptSnippet']) {
+        issues.push({
+            rule_id: 'NX005',
+            severity: 'ERROR',
+            message: `Implementation in ${context} missing required "javaScriptSnippet".`,
+            applies_to: 'implementation',
+            field: 'javaScriptSnippet',
+        });
+    }
+}
+function validateSelector(sel, issues) {
+    // NX006: must have xpath
+    if (!sel['xpath']) {
+        issues.push({
+            rule_id: 'NX006',
+            severity: 'ERROR',
+            message: 'Selector missing required "xpath".',
+            applies_to: 'selector',
+            field: 'xpath',
+            suggestion: 'Add an "xpath" property to the selector.',
+        });
+    }
+}
+function validateParameter(param, context, issues) {
+    // NX008: comparisonType must be one of valid enum values
+    if (param['comparisonType'] !== undefined && !VALID_COMPARISON_TYPES.includes(String(param['comparisonType']))) {
+        issues.push({
+            rule_id: 'NX008',
+            severity: 'WARNING',
+            message: `Parameter in ${context} has invalid comparisonType "${String(param['comparisonType'])}". Must be one of: ${VALID_COMPARISON_TYPES.join(', ')}.`,
+            applies_to: 'parameter',
+            field: 'comparisonType',
+            suggestion: `Use one of: ${VALID_COMPARISON_TYPES.join(', ')}`,
+        });
+    }
+}
+function buildNitroXJson(input) {
+    const result = {
+        componentId: randomUUID(),
+        name: input.name,
+        tagName: input.tag_name,
+        type: input.type,
+        pageStructureElement: input.page_structure_element,
+        fieldDetailsElement: input.field_details_element,
+    };
+    if (input.parameters && input.parameters.length > 0) {
+        result['parameters'] = input.parameters.map((p, i) => ({
+            name: p.name,
+            value: p.value,
+            ...(p.comparisonType !== undefined && { comparisonType: p.comparisonType }),
+            ...(p.default !== undefined && { default: p.default }),
+            index: i,
+        }));
+    }
+    if (input.elements && input.elements.length > 0) {
+        result['elements'] = input.elements.map((el) => buildElement(el));
+    }
+    return result;
+}
+function buildElement(el) {
+    const element = {
+        componentId: randomUUID(),
+        type: el.type_ref,
+        label: el.label,
+    };
+    if (el.tag_name) {
+        element['elementTagName'] = el.tag_name;
+    }
+    if (el.parameters && el.parameters.length > 0) {
+        element['parameters'] = el.parameters.map((p, i) => ({
+            name: p.name,
+            value: p.value,
+            ...(p.comparisonType !== undefined && { comparisonType: p.comparisonType }),
+            ...(p.default !== undefined && { default: p.default }),
+            index: i,
+        }));
+    }
+    if (el.selector_xpath) {
+        element['selectors'] = [{ xpath: el.selector_xpath }];
+    }
+    return element;
+}
+// ── RFC 7396 Merge-Patch ──────────────────────────────────────────────────────
+function applyMergePatch(target, patch) {
+    const result = { ...target };
+    for (const [key, value] of Object.entries(patch)) {
+        if (value === null) {
+            delete result[key];
+        }
+        else if (isObj(value) && isObj(result[key])) {
+            result[key] = applyMergePatch(result[key], value);
+        }
+        else {
+            result[key] = value;
+        }
+    }
+    return result;
+}
+// ── Tool Registrations ────────────────────────────────────────────────────────
+export function registerNitroXDiscover(server) {
+    server.registerTool('provar_nitrox_discover', {
+        title: 'Discover NitroX Components',
+        description: [
+            'Discover Provar projects containing NitroX (Hybrid Model) page objects.',
+            'Scans directories for .testproject marker files, then inventories nitroX/ and nitroXPackages/ directories.',
+            "NitroX is Provar's Hybrid Model for locators — component-based page objects for LWC,",
+            'Screen Flow, Industry Components, Experience Cloud, and HTML5 components.',
+            'Results provide file paths and package info for use with provar_nitrox_read, validate, and generate.',
+        ].join(' '),
+        inputSchema: {
+            search_roots: z
+                .array(z.string())
+                .optional()
+                .describe('Directories to scan (default: cwd; if empty, falls back to ~/git and ~/Provar)'),
+            max_depth: z
+                .number()
+                .int()
+                .min(1)
+                .max(20)
+                .default(6)
+                .describe('Maximum directory depth for .testproject search'),
+            include_packages: z
+                .boolean()
+                .default(true)
+                .describe('Include nitroXPackages/ package.json metadata in results'),
+        },
+    }, ({ search_roots, max_depth, include_packages }) => {
+        const requestId = makeRequestId();
+        log('info', 'provar_nitrox_discover', { requestId, search_roots, max_depth });
+        try {
+            let roots = search_roots && search_roots.length > 0 ? search_roots : [process.cwd()];
+            let projects = findProvarProjects(roots, max_depth);
+            // If no .testproject found in cwd, widen to home-dir defaults
+            if (projects.length === 0 && (!search_roots || search_roots.length === 0)) {
+                const fallbackRoots = [path.join(os.homedir(), 'git'), path.join(os.homedir(), 'Provar')];
+                const fallbackProjects = findProvarProjects(fallbackRoots, max_depth);
+                if (fallbackProjects.length > 0) {
+                    projects = fallbackProjects;
+                    roots = fallbackRoots;
+                }
+            }
+            const projectResults = projects.map((projectPath) => {
+                const nitroxDir = path.join(projectPath, 'nitroX');
+                const packagesDir = path.join(projectPath, 'nitroXPackages');
+                const hasNitrox = fs.existsSync(nitroxDir);
+                const hasPackages = fs.existsSync(packagesDir);
+                const nitroxFiles = hasNitrox ? collectPoJsonFiles(nitroxDir) : [];
+                let packages = [];
+                if (include_packages && hasPackages) {
+                    try {
+                        packages = fs
+                            .readdirSync(packagesDir, { withFileTypes: true })
+                            .filter((e) => e.isDirectory())
+                            .map((e) => {
+                            const pkgDir = path.join(packagesDir, e.name);
+                            const pkgJson = path.join(pkgDir, 'package.json');
+                            if (!fs.existsSync(pkgJson))
+                                return { path: pkgDir };
+                            try {
+                                const parsed = JSON.parse(fs.readFileSync(pkgJson, 'utf-8'));
+                                return { path: pkgDir, name: String(parsed['name'] ?? '') };
+                            }
+                            catch {
+                                return { path: pkgDir, error: 'invalid JSON' };
+                            }
+                        });
+                    }
+                    catch {
+                        // packagesDir inaccessible — return empty packages
+                    }
+                }
+                return {
+                    project_path: projectPath,
+                    nitrox_dir: hasNitrox ? nitroxDir : null,
+                    nitrox_file_count: nitroxFiles.length,
+                    nitrox_files: nitroxFiles,
+                    packages_dir: hasPackages ? packagesDir : null,
+                    packages,
+                };
+            });
+            const result = { requestId, projects: projectResults, searched_roots: roots };
+            return {
+                content: [{ type: 'text', text: JSON.stringify(result) }],
+                structuredContent: result,
+            };
+        }
+        catch (err) {
+            const error = err;
+            const errResult = makeError('DISCOVER_ERROR', error.message, requestId, false);
+            log('error', 'provar_nitrox_discover failed', { requestId, error: error.message });
+            return { isError: true, content: [{ type: 'text', text: JSON.stringify(errResult) }] };
+        }
+    });
+}
+export function registerNitroXRead(server, config) {
+    server.registerTool('provar_nitrox_read', {
+        title: 'Read NitroX Files',
+        description: [
+            'Read one or more NitroX .po.json (Hybrid Model page object) files and return their parsed content.',
+            'Use this to load examples before generating or validating.',
+            "Provide file_paths for specific files, or project_path to read all .po.json files from a project's nitroX/ directory.",
+        ].join(' '),
+        inputSchema: {
+            file_paths: z.array(z.string()).optional().describe('Specific .po.json file paths to read'),
+            project_path: z
+                .string()
+                .optional()
+                .describe('Provar project path — reads all .po.json files from nitroX/ directory'),
+            max_files: z
+                .number()
+                .int()
+                .min(1)
+                .max(100)
+                .default(20)
+                .describe('Maximum number of files to return (prevents context overflow)'),
+        },
+    }, ({ file_paths, project_path, max_files }) => {
+        const requestId = makeRequestId();
+        log('info', 'provar_nitrox_read', {
+            requestId,
+            file_count: file_paths?.length,
+            project_path,
+        });
+        try {
+            if (!file_paths?.length && !project_path) {
+                const err = makeError('MISSING_INPUT', 'Provide either file_paths or project_path.', requestId);
+                return { isError: true, content: [{ type: 'text', text: JSON.stringify(err) }] };
+            }
+            let targets = [];
+            if (file_paths?.length) {
+                targets = file_paths;
+            }
+            else if (project_path) {
+                assertPathAllowed(project_path, config.allowedPaths);
+                const resolved = path.resolve(project_path);
+                if (!fs.existsSync(resolved)) {
+                    const err = makeError('FILE_NOT_FOUND', `Project path not found: ${resolved}`, requestId);
+                    return { isError: true, content: [{ type: 'text', text: JSON.stringify(err) }] };
+                }
+                const nitroxDir = path.join(resolved, 'nitroX');
+                if (!fs.existsSync(nitroxDir)) {
+                    const err = makeError('FILE_NOT_FOUND', `No nitroX/ directory found in: ${resolved}`, requestId);
+                    return { isError: true, content: [{ type: 'text', text: JSON.stringify(err) }] };
+                }
+                targets = collectPoJsonFiles(nitroxDir);
+            }
+            const truncated = targets.length > max_files;
+            const toRead = targets.slice(0, max_files);
+            const files = toRead.map((filePath) => {
+                const resolved = path.resolve(filePath);
+                try {
+                    assertPathAllowed(resolved, config.allowedPaths);
+                }
+                catch (e) {
+                    const policyErr = e;
+                    return { file_path: resolved, error: policyErr.message, content: null, size_bytes: 0 };
+                }
+                if (!fs.existsSync(resolved)) {
+                    return { file_path: resolved, error: 'FILE_NOT_FOUND', content: null, size_bytes: 0 };
+                }
+                try {
+                    const raw = fs.readFileSync(resolved, 'utf-8');
+                    const content = JSON.parse(raw);
+                    return { file_path: resolved, content, size_bytes: raw.length };
+                }
+                catch {
+                    return { file_path: resolved, error: 'PARSE_ERROR', content: null, size_bytes: 0 };
+                }
+            });
+            const result = { requestId, files, truncated, total_found: targets.length };
+            return {
+                content: [{ type: 'text', text: JSON.stringify(result) }],
+                structuredContent: result,
+            };
+        }
+        catch (err) {
+            const error = err;
+            const errResult = makeError(error instanceof PathPolicyError ? error.code : 'READ_ERROR', error.message, requestId, false);
+            log('error', 'provar_nitrox_read failed', { requestId, error: error.message });
+            return { isError: true, content: [{ type: 'text', text: JSON.stringify(errResult) }] };
+        }
+    });
+}
+export function registerNitroXValidate(server, config) {
+    server.registerTool('provar_nitrox_validate', {
+        title: 'Validate NitroX Component',
+        description: [
+            'Validate a NitroX .po.json (Hybrid Model component page object) against schema rules.',
+            'Works for any NitroX-mapped component type: LWC, Screen Flow, Industry Components, Experience Cloud, HTML5.',
+            'Runs two validation passes sequentially: hardcoded semantic rules (NX001–NX010) then JSON schema validation (NX_SCHEMA_* rule IDs).',
+            'Schema issues catch structural errors not covered by NX rules: wrong property types, extra properties, enum violations.',
+            'Returns a quality score (0–100) and a combined list of issues with rule IDs, severity, and suggestions.',
+            'Score formula: 100 − (20 × errors) − (5 × warnings) − (1 × infos).',
+        ].join(' '),
+        inputSchema: {
+            content: z.string().optional().describe('JSON string of the .po.json content to validate'),
+            file_path: z.string().optional().describe('Path to a .po.json file to validate'),
+        },
+    }, ({ content, file_path }) => {
+        const requestId = makeRequestId();
+        log('info', 'provar_nitrox_validate', { requestId, has_content: !!content, file_path });
+        try {
+            let source = content;
+            if (!source && file_path) {
+                assertPathAllowed(file_path, config.allowedPaths);
+                const resolved = path.resolve(file_path);
+                if (!fs.existsSync(resolved)) {
+                    const err = makeError('FILE_NOT_FOUND', `File not found: ${resolved}`, requestId);
+                    return { isError: true, content: [{ type: 'text', text: JSON.stringify(err) }] };
+                }
+                source = fs.readFileSync(resolved, 'utf-8');
+            }
+            if (!source) {
+                const err = makeError('MISSING_INPUT', 'Provide either content or file_path.', requestId);
+                return { isError: true, content: [{ type: 'text', text: JSON.stringify(err) }] };
+            }
+            let parsed;
+            try {
+                parsed = JSON.parse(source);
+            }
+            catch {
+                const err = makeError('NX000', 'Invalid JSON: could not parse content.', requestId);
+                return { isError: true, content: [{ type: 'text', text: JSON.stringify(err) }] };
+            }
+            if (!isObj(parsed)) {
+                const err = makeError('NX000', 'Content must be a JSON object.', requestId);
+                return { isError: true, content: [{ type: 'text', text: JSON.stringify(err) }] };
+            }
+            const validation = validateNitroXContent(parsed);
+            const result = { requestId, ...validation };
+            return {
+                content: [{ type: 'text', text: JSON.stringify(result) }],
+                structuredContent: result,
+            };
+        }
+        catch (err) {
+            const error = err;
+            const errResult = makeError(error instanceof PathPolicyError ? error.code : 'VALIDATE_ERROR', error.message, requestId, false);
+            log('error', 'provar_nitrox_validate failed', { requestId, error: error.message });
+            return { isError: true, content: [{ type: 'text', text: JSON.stringify(errResult) }] };
+        }
+    });
+}
+const ParameterInputSchema = z.object({
+    name: z.string().describe('Parameter/qualifier name'),
+    value: z.string().describe('Parameter value'),
+    comparisonType: z.enum(['equals', 'starts-with', 'contains']).optional(),
+    default: z.boolean().optional().describe('Whether this is the default parameter value'),
+});
+const ElementInputSchema = z.object({
+    label: z.string().describe('Human-readable element label'),
+    type_ref: z.string().describe('Component type reference (e.g. "component::UUID" or "content")'),
+    tag_name: z.string().optional().describe('Optional HTML/LWC tag name override'),
+    parameters: z.array(ParameterInputSchema).optional(),
+    selector_xpath: z.string().optional().describe('XPath selector for this element'),
+});
+export function registerNitroXGenerate(server, config) {
+    server.registerTool('provar_nitrox_generate', {
+        title: 'Generate NitroX Components',
+        description: [
+            'Generate a new NitroX .po.json (Hybrid Model page object) from a component description.',
+            "Applicable to any component type supported by Provar's Hybrid Model:",
+            'LWC, Screen Flow, Industry Components, Experience Cloud, HTML5.',
+            'Read the provar-nitrox-component-catalog resource first to understand available component types,',
+            'tagName conventions, interaction titles, and attribute patterns from shipped base packages.',
+            'All componentId fields are assigned fresh UUIDs. Returns JSON content;',
+            'writes to disk only when dry_run=false.',
+        ].join(' '),
+        inputSchema: {
+            name: z.string().describe('Path-like component name, e.g. /com/force/myapp/ButtonComponent'),
+            tag_name: z.string().describe('LWC or HTML tag name, e.g. lightning-button or c-my-component'),
+            type: z.enum(['Block', 'Page']).default('Block').describe('Component type'),
+            page_structure_element: z.boolean().default(true).describe('Whether this is a page structure element'),
+            field_details_element: z.boolean().default(false).describe('Whether this is a field details element'),
+            parameters: z.array(ParameterInputSchema).optional().describe('Component parameters/qualifiers'),
+            elements: z.array(ElementInputSchema).optional().describe('Child elements'),
+            output_path: z.string().optional().describe('File path to write (requires dry_run=false)'),
+            overwrite: z.boolean().default(false).describe('Overwrite if output_path already exists'),
+            dry_run: z.boolean().default(true).describe('Return JSON without writing to disk (default)'),
+        },
+    }, (input) => {
+        const requestId = makeRequestId();
+        log('info', 'provar_nitrox_generate', { requestId, name: input.name, dry_run: input.dry_run });
+        try {
+            const generated = buildNitroXJson({
+                name: input.name,
+                tag_name: input.tag_name,
+                type: input.type,
+                page_structure_element: input.page_structure_element,
+                field_details_element: input.field_details_element,
+                parameters: input.parameters,
+                elements: input.elements,
+            });
+            const content = JSON.stringify(generated, null, 2);
+            let filePath;
+            let written = false;
+            if (input.output_path && !input.dry_run) {
+                filePath = path.resolve(input.output_path);
+                assertPathAllowed(filePath, config.allowedPaths);
+                if (fs.existsSync(filePath) && !input.overwrite) {
+                    const err = makeError('FILE_EXISTS', `File already exists: ${filePath}. Set overwrite=true to replace.`, requestId);
+                    return { isError: true, content: [{ type: 'text', text: JSON.stringify(err) }] };
+                }
+                fs.mkdirSync(path.dirname(filePath), { recursive: true });
+                fs.writeFileSync(filePath, content, 'utf-8');
+                written = true;
+                log('info', 'provar_nitrox_generate: wrote file', { requestId, filePath });
+            }
+            const result = { requestId, content, file_path: filePath, written, dry_run: input.dry_run };
+            return {
+                content: [{ type: 'text', text: JSON.stringify(result) }],
+                structuredContent: result,
+            };
+        }
+        catch (err) {
+            const error = err;
+            const errResult = makeError(error instanceof PathPolicyError ? error.code : error.code ?? 'GENERATE_ERROR', error.message, requestId, false);
+            log('error', 'provar_nitrox_generate failed', { requestId, error: error.message });
+            return { isError: true, content: [{ type: 'text', text: JSON.stringify(errResult) }] };
+        }
+    });
+}
+export function registerNitroXPatch(server, config) {
+    server.registerTool('provar_nitrox_patch', {
+        title: 'Patch NitroX Component',
+        description: [
+            'Apply a JSON merge-patch (RFC 7396) to an existing NitroX .po.json file.',
+            'Reads the file, merges the patch (null values remove keys, other values replace or recurse into objects),',
+            'optionally validates the merged result, and writes back.',
+            'Use dry_run=true (default) to preview the merged output without writing.',
+        ].join(' '),
+        inputSchema: {
+            file_path: z.string().describe('Path to the existing .po.json file to patch'),
+            patch: z
+                .record(z.unknown())
+                .describe('JSON merge-patch to apply (RFC 7396: null removes key, any other value replaces)'),
+            dry_run: z.boolean().default(true).describe('Return merged result without writing to disk (default)'),
+            validate_after: z
+                .boolean()
+                .default(true)
+                .describe('Run NX validation on merged result; blocks write if errors found'),
+        },
+    }, ({ file_path, patch, dry_run, validate_after }) => {
+        const requestId = makeRequestId();
+        log('info', 'provar_nitrox_patch', { requestId, file_path, dry_run });
+        try {
+            assertPathAllowed(file_path, config.allowedPaths);
+            const resolved = path.resolve(file_path);
+            if (!fs.existsSync(resolved)) {
+                const err = makeError('FILE_NOT_FOUND', `File not found: ${resolved}`, requestId);
+                return { isError: true, content: [{ type: 'text', text: JSON.stringify(err) }] };
+            }
+            let original;
+            try {
+                original = JSON.parse(fs.readFileSync(resolved, 'utf-8'));
+            }
+            catch {
+                const err = makeError('PARSE_ERROR', 'File contains invalid JSON.', requestId);
+                return { isError: true, content: [{ type: 'text', text: JSON.stringify(err) }] };
+            }
+            if (!isObj(original)) {
+                const err = makeError('PARSE_ERROR', 'File content must be a JSON object.', requestId);
+                return { isError: true, content: [{ type: 'text', text: JSON.stringify(err) }] };
+            }
+            const merged = applyMergePatch(original, patch);
+            const content = JSON.stringify(merged, null, 2);
+            let validation;
+            if (validate_after) {
+                validation = validateNitroXContent(merged);
+                if (!dry_run && !validation.valid) {
+                    const errCount = validation.issues.filter((i) => i.severity === 'ERROR').length;
+                    const err = makeError('VALIDATION_FAILED', `Patched content has ${errCount} error(s). Fix issues or set validate_after=false to skip.`, requestId, false, { validation });
+                    return { isError: true, content: [{ type: 'text', text: JSON.stringify(err) }] };
+                }
+            }
+            let written = false;
+            if (!dry_run) {
+                fs.writeFileSync(resolved, content, 'utf-8');
+                written = true;
+                log('info', 'provar_nitrox_patch: wrote file', { requestId, filePath: resolved });
+            }
+            const result = {
+                requestId,
+                content,
+                file_path: resolved,
+                written,
+                dry_run,
+                ...(validation !== undefined && { validation }),
+            };
+            return {
+                content: [{ type: 'text', text: JSON.stringify(result) }],
+                structuredContent: result,
+            };
+        }
+        catch (err) {
+            const error = err;
+            const errResult = makeError(error instanceof PathPolicyError ? error.code : error.code ?? 'PATCH_ERROR', error.message, requestId, false);
+            log('error', 'provar_nitrox_patch failed', { requestId, error: error.message });
+            return { isError: true, content: [{ type: 'text', text: JSON.stringify(errResult) }] };
+        }
+    });
+}
+export function registerAllNitroXTools(server, config) {
+    registerNitroXDiscover(server);
+    registerNitroXRead(server, config);
+    registerNitroXValidate(server, config);
+    registerNitroXGenerate(server, config);
+    registerNitroXPatch(server, config);
+}
+//# sourceMappingURL=nitroXTools.js.map