@provartesting/provardx-cli 1.5.0 → 1.5.1

package/lib/mcp/tools/testPlanValidate.js

@@ -8,7 +8,30 @@
 import { z } from 'zod';
 import { makeError, makeRequestId } from '../schemas/common.js';
 import { log } from '../logging/logger.js';
-import { validatePlan, buildHierarchySummary } from './hierarchyValidate.js';
+import { applyDetailLevel } from '../utils/detailLevel.js';
+import { calcCompletenessScore, calcNextAction } from '../utils/validationScore.js';
+import { validatePlan, buildHierarchySummary, } from './hierarchyValidate.js';
+import { desc } from './descHelper.js';
+function countSuiteViolations(suite) {
+    let total = suite.violations.length;
+    for (const tc of suite.test_cases) {
+        total += tc.issues.length + tc.best_practices_violations.length;
+    }
+    for (const child of suite.test_suites) {
+        total += countSuiteViolations(child);
+    }
+    return total;
+}
+function countAllPlanViolations(result) {
+    let total = result.violations.length;
+    for (const suite of result.test_suites) {
+        total += countSuiteViolations(suite);
+    }
+    for (const tc of result.test_cases) {
+        total += tc.issues.length + tc.best_practices_violations.length;
+    }
+    return total;
+}
 // ── Zod schemas ───────────────────────────────────────────────────────────────
 const testCaseSchema = z
     .object({
@@ -60,29 +83,48 @@ const metadataSchema = z
 })
     .optional()
     .describe('Plan completeness metadata — these fields are configured in the Provar Quality Hub app, not in local project files');
+const PLAN_VALIDATE_SUMMARY_FIELDS = [
+    'requestId',
+    'name',
+    'quality_score',
+    'summary',
+    'completeness_score',
+    'recommended_next_action',
+];
 export function registerTestPlanValidate(server) {
     server.registerTool('provar_testplan_validate', {
         title: 'Validate Test Plan',
-        description: 'Validate a Provar test plan: checks for empty plans, duplicate suite names, oversized plans (>20 suites), plan completeness (objectives, scope, methodology, environments, acceptance criteria, test data strategy, risk assessment), and naming consistency. Recursively validates child suites and test cases. Returns quality score, plan-level violations, and full hierarchy results.',
+        description: desc('Validate a Provar test plan: checks for empty plans, duplicate suite names, oversized plans (>20 suites), plan completeness (objectives, scope, methodology, environments, acceptance criteria, test data strategy, risk assessment), and naming consistency. Recursively validates child suites and test cases. Returns quality score, plan-level violations, and full hierarchy results. Use completeness_score and recommended_next_action to determine whether to continue iterating.', 'Validate a Provar test plan: naming, size, completeness, per-suite quality; stop signal via completeness_score.'),
         inputSchema: {
-            plan_name: z.string().describe('Name of the test plan'),
-            test_suites: z.array(suiteSchema).optional().describe('Test suites belonging to this plan'),
-            test_cases: z.array(testCaseSchema).optional().describe('Test cases directly in this plan (not in a suite)'),
+            plan_name: z.string().describe(desc('Name of the test plan', 'string')),
+            test_suites: z
+                .array(suiteSchema)
+                .optional()
+                .describe(desc('Test suites belonging to this plan', 'object[], optional')),
+            test_cases: z
+                .array(testCaseSchema)
+                .optional()
+                .describe(desc('Test cases directly in this plan (not in a suite)', 'object[], optional')),
             test_suite_count: z
                 .number()
                 .int()
                 .min(0)
                 .optional()
-                .describe('Explicit suite count for size check (overrides counting test_suites)'),
+                .describe(desc('Explicit suite count for size check (overrides counting test_suites)', 'int ≥0, optional')),
             metadata: metadataSchema,
             quality_threshold: z
                 .number()
                 .min(0)
                 .max(100)
                 .optional()
-                .describe('Minimum quality score for a test case to be considered valid (default: 80)'),
+                .describe(desc('Minimum quality score for a test case to be considered valid (default: 80)', 'number 0–100, optional')),
+            detail: z
+                .enum(['summary', 'standard', 'full'])
+                .optional()
+                .default('standard')
+                .describe(desc('Response verbosity. "summary": name, scores, and stop signal only. "standard"/"full": full violations and hierarchy results (default).', 'enum summary|standard|full, optional; default standard')),
         },
-    }, ({ plan_name, test_suites, test_cases, test_suite_count, metadata, quality_threshold }) => {
+    }, ({ plan_name, test_suites, test_cases, test_suite_count, metadata, quality_threshold, detail }) => {
         const requestId = makeRequestId();
         log('info', 'provar_testplan_validate', { requestId, plan_name });
         try {
@@ -96,10 +138,21 @@ export function registerTestPlanValidate(server) {
             };
             const result = validatePlan(input, threshold);
             const summary = buildHierarchySummary(result);
-            const response = { requestId, ...result, summary };
+            const completeness_score = calcCompletenessScore(summary.test_cases_valid, summary.total_test_cases);
+            const remainingViolations = countAllPlanViolations(result);
+            const recommended_next_action = calcNextAction(completeness_score, false, remainingViolations);
+            const response = {
+                requestId,
+                completeness_score,
+                recommended_next_action,
+                ...result,
+                summary,
+            };
+            const detailLevel = (detail ?? 'standard');
+            const finalResponse = applyDetailLevel(response, detailLevel, PLAN_VALIDATE_SUMMARY_FIELDS);
             return {
-                content: [{ type: 'text', text: JSON.stringify(response) }],
-                structuredContent: response,
+                content: [{ type: 'text', text: JSON.stringify(finalResponse) }],
+                structuredContent: finalResponse,
             };
         }
         catch (err) {

package/lib/mcp/tools/testPlanValidate.js.map

@@ -1 +1 @@
-{"version":3,"file":"testPlanValidate.js","sourceRoot":"","sources":["../../../src/mcp/tools/testPlanValidate.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"testPlanValidate.js","sourceRoot":"","sources":["../../../src/mcp/tools/testPlanValidate.ts"],"names":[],"mappings":"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"}

package/lib/mcp/tools/testSuiteValidate.js

@@ -8,7 +8,22 @@
 import { z } from 'zod';
 import { makeError, makeRequestId } from '../schemas/common.js';
 import { log } from '../logging/logger.js';
+import { applyDetailLevel } from '../utils/detailLevel.js';
+import { calcCompletenessScore, calcNextAction } from '../utils/validationScore.js';
+import { generateRunId, saveRun, hasAnyRun, loadBaselineViolations, computeDiff, computeContextHash, resolveValidationDir, } from '../utils/validationDiff.js';
 import { validateSuite, buildHierarchySummary } from './hierarchyValidate.js';
+import { desc } from './descHelper.js';
+function collectAllViolations(result) {
+    const all = [...result.violations];
+    for (const tc of result.test_cases) {
+        all.push(...tc.issues);
+        all.push(...tc.best_practices_violations);
+    }
+    for (const child of result.test_suites) {
+        all.push(...collectAllViolations(child));
+    }
+    return all;
+}
 // ── Zod schemas ───────────────────────────────────────────────────────────────
 const testCaseSchema = z
     .object({
@@ -35,31 +50,55 @@ const childSuiteSchema = z.object({
     test_suites: z.array(innerSuiteSchema).optional().describe('Nested child suites (one level deep)'),
     test_case_count: z.number().int().min(0).optional().describe('Explicit test case count for size check'),
 });
+const SUITE_VALIDATE_SUMMARY_FIELDS = [
+    'requestId',
+    'name',
+    'quality_score',
+    'summary',
+    'run_id',
+    'completeness_score',
+    'recommended_next_action',
+];
+function suiteStorageDir() {
+    return resolveValidationDir('testsuite');
+}
 export function registerTestSuiteValidate(server) {
     server.registerTool('provar_testsuite_validate', {
         title: 'Validate Test Suite',
-        description: 'Validate a Provar test suite: checks for empty suites, duplicate names, oversized suites (>75 tests), and naming convention consistency. Recursively validates child suites and individual test case XML. Returns quality score, suite-level violations, and per-test-case results.',
+        description: desc('Validate a Provar test suite: checks for empty suites, duplicate names, oversized suites (>75 tests), and naming convention consistency. Recursively validates child suites and individual test case XML. Returns quality score, suite-level violations, and per-test-case results. Every response includes run_id — pass it as baseline_run_id in the next call to receive only new/resolved violations.', 'Validate a Provar test suite: naming, size, duplicates, per-test-case quality; run_id for diff.'),
         inputSchema: {
-            suite_name: z.string().describe('Name of the test suite'),
-            test_cases: z.array(testCaseSchema).optional().describe('Test cases directly in this suite'),
+            suite_name: z.string().describe(desc('Name of the test suite', 'string')),
+            test_cases: z
+                .array(testCaseSchema)
+                .optional()
+                .describe(desc('Test cases directly in this suite', 'object[], optional')),
             child_suites: z
                 .array(childSuiteSchema)
                 .optional()
-                .describe('Child test suites (supports up to 2 levels of nesting)'),
+                .describe(desc('Child test suites (supports up to 2 levels of nesting)', 'object[], optional')),
             test_case_count: z
                 .number()
                 .int()
                 .min(0)
                 .optional()
-                .describe('Explicit total test case count for size check (overrides counting test_cases)'),
+                .describe(desc('Explicit total test case count for size check (overrides counting test_cases)', 'int ≥0, optional')),
             quality_threshold: z
                 .number()
                 .min(0)
                 .max(100)
                 .optional()
-                .describe('Minimum quality score for a test case to be considered valid (default: 80)'),
+                .describe(desc('Minimum quality score for a test case to be considered valid (default: 80)', 'number 0–100, optional')),
+            detail: z
+                .enum(['summary', 'standard', 'full'])
+                .optional()
+                .default('standard')
+                .describe(desc('Response verbosity. "summary": name, scores, and stop signal only. "standard"/"full": full violations and per-test-case results (default).', 'enum summary|standard|full, optional; default standard')),
+            baseline_run_id: z
+                .string()
+                .optional()
+                .describe(desc('run_id from a previous call. When provided, returns only violations that are new or resolved since that run: { added, resolved, unchanged_count, run_id }. If not found, returns error BASELINE_NOT_FOUND.', 'string, optional; prev run_id for diff response')),
         },
-    }, ({ suite_name, test_cases, child_suites, test_case_count, quality_threshold }) => {
+    }, ({ suite_name, test_cases, child_suites, test_case_count, quality_threshold, detail, baseline_run_id }) => {
         const requestId = makeRequestId();
         log('info', 'provar_testsuite_validate', { requestId, suite_name });
         try {
@@ -72,10 +111,60 @@ export function registerTestSuiteValidate(server) {
             };
             const result = validateSuite(input, threshold);
             const summary = buildHierarchySummary(result);
-            const response = { requestId, ...result, summary };
+            const storageDir = suiteStorageDir();
+            const contextHash = computeContextHash('suite', suite_name);
+            const runId = generateRunId(suite_name);
+            const currentViolations = collectAllViolations(result);
+            // Load baseline BEFORE saving to prevent eviction of the requested baseline
+            const baseline = baseline_run_id !== undefined && baseline_run_id !== ''
+                ? loadBaselineViolations(storageDir, baseline_run_id, contextHash)
+                : null;
+            const hasBaseline = hasAnyRun(storageDir);
+            try {
+                saveRun(storageDir, runId, currentViolations, contextHash);
+            }
+            catch (saveErr) {
+                log('warn', 'provar_testsuite_validate: could not save run for diff', {
+                    requestId,
+                    error: saveErr.message,
+                });
+            }
+            // Diff mode
+            if (baseline_run_id !== undefined && baseline_run_id !== '') {
+                if (!baseline) {
+                    const errResult = makeError('BASELINE_NOT_FOUND', 'Baseline run not found. Run validation without baseline_run_id first to establish a baseline.', requestId, false, { suggestion: 'Run provar_testsuite_validate without baseline_run_id first to establish a baseline.' });
+                    return { isError: true, content: [{ type: 'text', text: JSON.stringify(errResult) }] };
+                }
+                const diff = computeDiff(baseline, currentViolations);
+                const completeness_score = calcCompletenessScore(summary.test_cases_valid, summary.total_test_cases);
+                const recommended_next_action = calcNextAction(completeness_score, true, currentViolations.length);
+                const diffResponse = {
+                    requestId,
+                    run_id: runId,
+                    ...diff,
+                    completeness_score,
+                    recommended_next_action,
+                };
+                return {
+                    content: [{ type: 'text', text: JSON.stringify(diffResponse) }],
+                    structuredContent: diffResponse,
+                };
+            }
+            const completeness_score = calcCompletenessScore(summary.test_cases_valid, summary.total_test_cases);
+            const recommended_next_action = calcNextAction(completeness_score, hasBaseline, currentViolations.length);
+            const response = {
+                requestId,
+                run_id: runId,
+                completeness_score,
+                recommended_next_action,
+                ...result,
+                summary,
+            };
+            const detailLevel = (detail ?? 'standard');
+            const finalResponse = applyDetailLevel(response, detailLevel, SUITE_VALIDATE_SUMMARY_FIELDS);
             return {
-                content: [{ type: 'text', text: JSON.stringify(response) }],
-                structuredContent: response,
+                content: [{ type: 'text', text: JSON.stringify(finalResponse) }],
+                structuredContent: finalResponse,
             };
         }
         catch (err) {

package/lib/mcp/tools/testSuiteValidate.js.map

@@ -1 +1 @@
-{"version":3,"file":"testSuiteValidate.js","sourceRoot":"","sources":["../../../src/mcp/tools/testSuiteValidate.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"testSuiteValidate.js","sourceRoot":"","sources":["../../../src/mcp/tools/testSuiteValidate.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,8BAA8B;AAC9B,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,OAAO,EAAE,SAAS,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AAChE,OAAO,EAAE,GAAG,EAAE,MAAM,sBAAsB,CAAC;AAC3C,OAAO,EAAE,gBAAgB,EAAoB,MAAM,yBAAyB,CAAC;AAC7E,OAAO,EAAE,qBAAqB,EAAE,cAAc,EAAE,MAAM,6BAA6B,CAAC;AACpF,OAAO,EACL,aAAa,EACb,OAAO,EACP,SAAS,EACT,sBAAsB,EACtB,WAAW,EACX,kBAAkB,EAClB,oBAAoB,GAErB,MAAM,4BAA4B,CAAC;AACpC,OAAO,EAAE,aAAa,EAAE,qBAAqB,EAAyC,MAAM,wBAAwB,CAAC;AACrH,OAAO,EAAE,IAAI,EAAE,MAAM,iBAAiB,CAAC;AAEvC,SAAS,oBAAoB,CAAC,MAAmB;IAC/C,MAAM,GAAG,GAAwB,CAAC,GAAI,MAAM,CAAC,UAA6C,CAAC,CAAC;IAC5F,KAAK,MAAM,EAAE,IAAI,MAAM,CAAC,UAAU,EAAE,CAAC;QACnC,GAAG,CAAC,IAAI,CAAC,GAAI,EAAE,CAAC,MAAyC,CAAC,CAAC;QAC3D,GAAG,CAAC,IAAI,CAAC,GAAI,EAAE,CAAC,yBAA4D,CAAC,CAAC;IAChF,CAAC;IACD,KAAK,MAAM,KAAK,IAAI,MAAM,CAAC,WAAW,EAAE,CAAC;QACvC,GAAG,CAAC,IAAI,CAAC,GAAG,oBAAoB,CAAC,KAAK,CAAC,CAAC,CAAC;IAC3C,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC;AAED,iFAAiF;AAEjF,MAAM,cAAc,GAAG,CAAC;KACrB,MAAM,CAAC;IACN,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,kDAAkD,CAAC;IAC7E,WAAW,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,wCAAwC,CAAC;IACrF,GAAG,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,yDAAyD,CAAC;CAC/F,CAAC;KACD,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,WAAW,KAAK,SAAS,IAAI,CAAC,CAAC,GAAG,KAAK,SAAS,EAAE;IACjE,OAAO,EAAE,4CAA4C;CACtD,CAAC,CAAC;AAEL,MAAM,gBAAgB,GAAG,CAAC,CAAC,MAAM,CAAC;IAChC,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,kBAAkB,CAAC;IAC7C,UAAU,EAAE,CAAC,CAAC,KAAK,CAAC,cAAc,CAAC,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,gCAAgC,CAAC;IACzF,eAAe,EAAE,CAAC;SACf,MAAM,EAAE;SACR,GAAG,EAAE;SACL,GAAG,CAAC,CAAC,CAAC;SACN,QAAQ,EAAE;SACV,QAAQ,CAAC,0DAA0D,CAAC;CACxE,CAAC,CAAC;AAEH,MAAM,gBAAgB,GAAG,CAAC,CAAC,MAAM,CAAC;IAChC,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,kBAAkB,CAAC;IAC7C,UAAU,EAAE,CAAC,CAAC,KAAK,CAAC,cAAc,CAAC,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,0BAA0B,CAAC;IACnF,WAAW,EAAE,CAAC,CAAC,KAAK,CAAC,gBAAgB,CAAC,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,sCAAsC,CAAC;IAClG,eAAe,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,yCAAyC,CAAC;CACxG,CAAC,CAAC;AAEH,MAAM,6BAA6B,GAAG;IACpC,WAAW;IACX,MAAM;IACN,eAAe;IACf,SAAS;IACT,QAAQ;IACR,oBAAoB;IACpB,yBAAyB;CAC1B,CAAC;AAEF,SAAS,eAAe;IACtB,OAAO,oBAAoB,CAAC,WAAW,CAAC,CAAC;AAC3C,CAAC;AAED,MAAM,UAAU,yBAAyB,CAAC,MAAiB;IACzD,MAAM,CAAC,YAAY,CACjB,2BAA2B,EAC3B;QACE,KAAK,EAAE,qBAAqB;QAC5B,WAAW,EAAE,IAAI,CACf,2YAA2Y,EAC3Y,iGAAiG,CAClG;QACD,WAAW,EAAE;YACX,UAAU,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,IAAI,CAAC,wBAAwB,EAAE,QAAQ,CAAC,CAAC;YACzE,UAAU,EAAE,CAAC;iBACV,KAAK,CAAC,cAAc,CAAC;iBACrB,QAAQ,EAAE;iBACV,QAAQ,CAAC,IAAI,CAAC,mCAAmC,EAAE,oBAAoB,CAAC,CAAC;YAC5E,YAAY,EAAE,CAAC;iBACZ,KAAK,CAAC,gBAAgB,CAAC;iBACvB,QAAQ,EAAE;iBACV,QAAQ,CAAC,IAAI,CAAC,wDAAwD,EAAE,oBAAoB,CAAC,CAAC;YACjG,eAAe,EAAE,CAAC;iBACf,MAAM,EAAE;iBACR,GAAG,EAAE;iBACL,GAAG,CAAC,CAAC,CAAC;iBACN,QAAQ,EAAE;iBACV,QAAQ,CACP,IAAI,CAAC,+EAA+E,EAAE,kBAAkB,CAAC,CAC1G;YACH,iBAAiB,EAAE,CAAC;iBACjB,MAAM,EAAE;iBACR,GAAG,CAAC,CAAC,CAAC;iBACN,GAAG,CAAC,GAAG,CAAC;iBACR,QAAQ,EAAE;iBACV,QAAQ,CACP,IAAI,CAAC,4EAA4E,EAAE,wBAAwB,CAAC,CAC7G;YACH,MAAM,EAAE,CAAC;iBACN,IAAI,CAAC,CAAC,SAAS,EAAE,UAAU,EAAE,MAAM,CAAC,CAAC;iBACrC,QAAQ,EAAE;iBACV,OAAO,CAAC,UAAU,CAAC;iBACnB,QAAQ,CACP,IAAI,CACF,4IAA4I,EAC5I,wDAAwD,CACzD,CACF;YACH,eAAe,EAAE,CAAC;iBACf,MAAM,EAAE;iBACR,QAAQ,EAAE;iBACV,QAAQ,CACP,IAAI,CACF,4MAA4M,EAC5M,iDAAiD,CAClD,CACF;SACJ;KACF,EACD,CAAC,EAAE,UAAU,EAAE,UAAU,EAAE,YAAY,EAAE,eAAe,EAAE,iBAAiB,EAAE,MAAM,EAAE,eAAe,EAAE,EAAE,EAAE;QACxG,MAAM,SAAS,GAAG,aAAa,EAAE,CAAC;QAClC,GAAG,CAAC,MAAM,EAAE,2BAA2B,EAAE,EAAE,SAAS,EAAE,UAAU,EAAE,CAAC,CAAC;QAEpE,IAAI,CAAC;YACH,MAAM,SAAS,GAAG,iBAAiB,IAAI,EAAE,CAAC;YAC1C,MAAM,KAAK,GAAmB;gBAC5B,IAAI,EAAE,UAAU;gBAChB,UAAU,EAAE,UAAU,IAAI,EAAE;gBAC5B,WAAW,EAAE,CAAC,YAAY,IAAI,EAAE,CAAqB;gBACrD,eAAe;aAChB,CAAC;YAEF,MAAM,MAAM,GAAG,aAAa,CAAC,KAAK,EAAE,SAAS,CAAC,CAAC;YAC/C,MAAM,OAAO,GAAG,qBAAqB,CAAC,MAAM,CAAC,CAAC;YAE9C,MAAM,UAAU,GAAG,eAAe,EAAE,CAAC;YACrC,MAAM,WAAW,GAAG,kBAAkB,CAAC,OAAO,EAAE,UAAU,CAAC,CAAC;YAC5D,MAAM,KAAK,GAAG,aAAa,CAAC,UAAU,CAAC,CAAC;YACxC,MAAM,iBAAiB,GAAG,oBAAoB,CAAC,MAAM,CAAC,CAAC;YAEvD,4EAA4E;YAC5E,MAAM,QAAQ,GACZ,eAAe,KAAK,SAAS,IAAI,eAAe,KAAK,EAAE;gBACrD,CAAC,CAAC,sBAAsB,CAAC,UAAU,EAAE,eAAe,EAAE,WAAW,CAAC;gBAClE,CAAC,CAAC,IAAI,CAAC;YAEX,MAAM,WAAW,GAAG,SAAS,CAAC,UAAU,CAAC,CAAC;YAE1C,IAAI,CAAC;gBACH,OAAO,CAAC,UAAU,EAAE,KAAK,EAAE,iBAAiB,EAAE,WAAW,CAAC,CAAC;YAC7D,CAAC;YAAC,OAAO,OAAO,EAAE,CAAC;gBACjB,GAAG,CAAC,MAAM,EAAE,wDAAwD,EAAE;oBACpE,SAAS;oBACT,KAAK,EAAG,OAAiB,CAAC,OAAO;iBAClC,CAAC,CAAC;YACL,CAAC;YAED,YAAY;YACZ,IAAI,eAAe,KAAK,SAAS,IAAI,eAAe,KAAK,EAAE,EAAE,CAAC;gBAC5D,IAAI,CAAC,QAAQ,EAAE,CAAC;oBACd,MAAM,SAAS,GAAG,SAAS,CACzB,oBAAoB,EACpB,+FAA+F,EAC/F,SAAS,EACT,KAAK,EACL,EAAE,UAAU,EAAE,sFAAsF,EAAE,CACvG,CAAC;oBACF,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,MAAe,EAAE,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,SAAS,CAAC,EAAE,CAAC,EAAE,CAAC;gBAClG,CAAC;gBACD,MAAM,IAAI,GAAG,WAAW,CAAC,QAAQ,EAAE,iBAAiB,CAAC,CAAC;gBACtD,MAAM,kBAAkB,GAAG,qBAAqB,CAAC,OAAO,CAAC,gBAAgB,EAAE,OAAO,CAAC,gBAAgB,CAAC,CAAC;gBACrG,MAAM,uBAAuB,GAAG,cAAc,CAAC,kBAAkB,EAAE,IAAI,EAAE,iBAAiB,CAAC,MAAM,CAAC,CAAC;gBACnG,MAAM,YAAY,GAAG;oBACnB,SAAS;oBACT,MAAM,EAAE,KAAK;oBACb,GAAG,IAAI;oBACP,kBAAkB;oBAClB,uBAAuB;iBACxB,CAAC;gBACF,OAAO;oBACL,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,MAAe,EAAE,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,YAAY,CAAC,EAAE,CAAC;oBACxE,iBAAiB,EAAE,YAAY;iBAChC,CAAC;YACJ,CAAC;YAED,MAAM,kBAAkB,GAAG,qBAAqB,CAAC,OAAO,CAAC,gBAAgB,EAAE,OAAO,CAAC,gBAAgB,CAAC,CAAC;YACrG,MAAM,uBAAuB,GAAG,cAAc,CAAC,kBAAkB,EAAE,WAAW,EAAE,iBAAiB,CAAC,MAAM,CAAC,CAAC;YAE1G,MAAM,QAAQ,GAAG;gBACf,SAAS;gBACT,MAAM,EAAE,KAAK;gBACb,kBAAkB;gBAClB,uBAAuB;gBACvB,GAAG,MAAM;gBACT,OAAO;aACR,CAAC;YAEF,MAAM,WAAW,GAAG,CAAC,MAAM,IAAI,UAAU,CAAgB,CAAC;YAC1D,MAAM,aAAa,GAAG,gBAAgB,CAAC,QAAQ,EAAE,WAAW,EAAE,6BAA6B,CAAC,CAAC;YAE7F,OAAO;gBACL,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,MAAe,EAAE,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,aAAa,CAAC,EAAE,CAAC;gBACzE,iBAAiB,EAAE,aAAa;aACjC,CAAC;QACJ,CAAC;QAAC,OAAO,GAAY,EAAE,CAAC;YACtB,MAAM,KAAK,GAAG,GAAY,CAAC;YAC3B,MAAM,SAAS,GAAG,SAAS,CAAC,gBAAgB,EAAE,KAAK,CAAC,OAAO,EAAE,SAAS,EAAE,KAAK,CAAC,CAAC;YAC/E,GAAG,CAAC,OAAO,EAAE,kCAAkC,EAAE,EAAE,SAAS,EAAE,KAAK,EAAE,KAAK,CAAC,OAAO,EAAE,CAAC,CAAC;YACtF,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,MAAe,EAAE,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,SAAS,CAAC,EAAE,CAAC,EAAE,CAAC;QAClG,CAAC;IACH,CAAC,CACF,CAAC;AACJ,CAAC"}

package/lib/mcp/utils/detailLevel.d.ts

@@ -0,0 +1,9 @@
+export type DetailLevel = 'summary' | 'standard' | 'full';
+/**
+ * Shape a structured response object according to the requested detail level.
+ *
+ * - `summary`  — retain only the keys listed in summaryFields
+ * - `standard` — return data unchanged (the existing default response shape)
+ * - `full`     — return data unchanged (callers expand gated fields before calling)
+ */
+export declare function applyDetailLevel(data: Record<string, unknown>, level: DetailLevel, summaryFields: string[]): Record<string, unknown>;

package/lib/mcp/utils/detailLevel.js

@@ -0,0 +1,20 @@
+/*
+ * 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
+ */
+/**
+ * Shape a structured response object according to the requested detail level.
+ *
+ * - `summary`  — retain only the keys listed in summaryFields
+ * - `standard` — return data unchanged (the existing default response shape)
+ * - `full`     — return data unchanged (callers expand gated fields before calling)
+ */
+export function applyDetailLevel(data, level, summaryFields) {
+    if (level === 'summary') {
+        return Object.fromEntries(Object.entries(data).filter(([k]) => summaryFields.includes(k)));
+    }
+    return data;
+}
+//# sourceMappingURL=detailLevel.js.map

package/lib/mcp/utils/detailLevel.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"detailLevel.js","sourceRoot":"","sources":["../../../src/mcp/utils/detailLevel.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAIH;;;;;;GAMG;AACH,MAAM,UAAU,gBAAgB,CAC9B,IAA6B,EAC7B,KAAkB,EAClB,aAAuB;IAEvB,IAAI,KAAK,KAAK,SAAS,EAAE,CAAC;QACxB,OAAO,MAAM,CAAC,WAAW,CAAC,MAAM,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,aAAa,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;IAC7F,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC"}

package/lib/mcp/utils/fieldMask.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Mask an object (or array of objects) to retain only the specified fields.
+ *
+ * - Top-level keys: `"name"` keeps only the `name` property
+ * - Dot notation:   `"steps.action"` keeps the `steps` array but only `action` within each element
+ * - Unknown field names are silently ignored — never an error
+ * - Arrays: masking is applied to every element
+ *
+ * @param obj    Source object or array (typed as unknown; cast internally, never through any)
+ * @param fields Parsed field list — each entry is a dot-path string
+ */
+export declare function maskFields(obj: unknown, fields: string[]): unknown;
+/**
+ * Parse a comma-separated fields string into a trimmed, non-empty field list.
+ * Returns null when the string is absent or blank (caller should skip masking).
+ */
+export declare function parseFieldsParam(fields: string | undefined): string[] | null;

package/lib/mcp/utils/fieldMask.js

@@ -0,0 +1,75 @@
+/*
+ * 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
+ */
+/**
+ * Mask an object (or array of objects) to retain only the specified fields.
+ *
+ * - Top-level keys: `"name"` keeps only the `name` property
+ * - Dot notation:   `"steps.action"` keeps the `steps` array but only `action` within each element
+ * - Unknown field names are silently ignored — never an error
+ * - Arrays: masking is applied to every element
+ *
+ * @param obj    Source object or array (typed as unknown; cast internally, never through any)
+ * @param fields Parsed field list — each entry is a dot-path string
+ */
+export function maskFields(obj, fields) {
+    if (Array.isArray(obj)) {
+        return obj.map((item) => maskFields(item, fields));
+    }
+    if (obj === null || typeof obj !== 'object') {
+        return obj;
+    }
+    const source = obj;
+    // Group fields: topLevelKeys contains every key to retain.
+    // dotFields[key] holds the sub-paths to drill into for that key.
+    const topLevelKeys = new Set();
+    const dotFields = {};
+    for (const field of fields) {
+        const dotIdx = field.indexOf('.');
+        if (dotIdx === -1) {
+            topLevelKeys.add(field);
+        }
+        else {
+            const top = field.slice(0, dotIdx);
+            const rest = field.slice(dotIdx + 1);
+            topLevelKeys.add(top);
+            if (!dotFields[top])
+                dotFields[top] = [];
+            dotFields[top].push(rest);
+        }
+    }
+    const result = {};
+    for (const key of topLevelKeys) {
+        if (!(key in source))
+            continue; // silently ignore unknown fields
+        const subPaths = dotFields[key];
+        if (subPaths) {
+            const val = source[key];
+            // Dot-path into a primitive can't be narrowed; omit rather than leak the whole value.
+            if (Array.isArray(val) || (val !== null && typeof val === 'object')) {
+                result[key] = maskFields(val, subPaths);
+            }
+        }
+        else {
+            result[key] = source[key];
+        }
+    }
+    return result;
+}
+/**
+ * Parse a comma-separated fields string into a trimmed, non-empty field list.
+ * Returns null when the string is absent or blank (caller should skip masking).
+ */
+export function parseFieldsParam(fields) {
+    if (!fields)
+        return null;
+    const parsed = fields
+        .split(',')
+        .map((f) => f.trim())
+        .filter(Boolean);
+    return parsed.length > 0 ? parsed : null;
+}
+//# sourceMappingURL=fieldMask.js.map

package/lib/mcp/utils/fieldMask.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"fieldMask.js","sourceRoot":"","sources":["../../../src/mcp/utils/fieldMask.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH;;;;;;;;;;GAUG;AACH,MAAM,UAAU,UAAU,CAAC,GAAY,EAAE,MAAgB;IACvD,IAAI,KAAK,CAAC,OAAO,CAAC,GAAG,CAAC,EAAE,CAAC;QACvB,OAAO,GAAG,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,UAAU,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC,CAAC;IACrD,CAAC;IAED,IAAI,GAAG,KAAK,IAAI,IAAI,OAAO,GAAG,KAAK,QAAQ,EAAE,CAAC;QAC5C,OAAO,GAAG,CAAC;IACb,CAAC;IAED,MAAM,MAAM,GAAG,GAA8B,CAAC;IAE9C,2DAA2D;IAC3D,iEAAiE;IACjE,MAAM,YAAY,GAAG,IAAI,GAAG,EAAU,CAAC;IACvC,MAAM,SAAS,GAA6B,EAAE,CAAC;IAE/C,KAAK,MAAM,KAAK,IAAI,MAAM,EAAE,CAAC;QAC3B,MAAM,MAAM,GAAG,KAAK,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC;QAClC,IAAI,MAAM,KAAK,CAAC,CAAC,EAAE,CAAC;YAClB,YAAY,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC;QAC1B,CAAC;aAAM,CAAC;YACN,MAAM,GAAG,GAAG,KAAK,CAAC,KAAK,CAAC,CAAC,EAAE,MAAM,CAAC,CAAC;YACnC,MAAM,IAAI,GAAG,KAAK,CAAC,KAAK,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC;YACrC,YAAY,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;YACtB,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC;gBAAE,SAAS,CAAC,GAAG,CAAC,GAAG,EAAE,CAAC;YACzC,SAAS,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QAC5B,CAAC;IACH,CAAC;IAED,MAAM,MAAM,GAA4B,EAAE,CAAC;IAC3C,KAAK,MAAM,GAAG,IAAI,YAAY,EAAE,CAAC;QAC/B,IAAI,CAAC,CAAC,GAAG,IAAI,MAAM,CAAC;YAAE,SAAS,CAAC,iCAAiC;QACjE,MAAM,QAAQ,GAAG,SAAS,CAAC,GAAG,CAAC,CAAC;QAChC,IAAI,QAAQ,EAAE,CAAC;YACb,MAAM,GAAG,GAAG,MAAM,CAAC,GAAG,CAAC,CAAC;YACxB,sFAAsF;YACtF,IAAI,KAAK,CAAC,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,GAAG,KAAK,IAAI,IAAI,OAAO,GAAG,KAAK,QAAQ,CAAC,EAAE,CAAC;gBACpE,MAAM,CAAC,GAAG,CAAC,GAAG,UAAU,CAAC,GAAG,EAAE,QAAQ,CAAC,CAAC;YAC1C,CAAC;QACH,CAAC;aAAM,CAAC;YACN,MAAM,CAAC,GAAG,CAAC,GAAG,MAAM,CAAC,GAAG,CAAC,CAAC;QAC5B,CAAC;IACH,CAAC;IAED,OAAO,MAAM,CAAC;AAChB,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,gBAAgB,CAAC,MAA0B;IACzD,IAAI,CAAC,MAAM;QAAE,OAAO,IAAI,CAAC;IACzB,MAAM,MAAM,GAAG,MAAM;SAClB,KAAK,CAAC,GAAG,CAAC;SACV,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC;SACpB,MAAM,CAAC,OAAO,CAAC,CAAC;IACnB,OAAO,MAAM,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,IAAI,CAAC;AAC3C,CAAC"}

package/lib/mcp/utils/tokenMeta.d.ts

@@ -0,0 +1,40 @@
+type ContentItem = {
+    type: 'text';
+    text: string;
+};
+export interface ToolResult {
+    content: ContentItem[];
+    structuredContent?: Record<string, unknown>;
+    isError?: boolean;
+}
+interface ToolExtra {
+    sessionId?: string;
+}
+export type AnyToolCallback = (args: Record<string, unknown>, extra: ToolExtra) => ToolResult | Promise<ToolResult>;
+interface SessionEntry {
+    calls: number;
+    totalEstimatedTokens: number;
+}
+export type DepthGuardState = Map<string, SessionEntry>;
+export declare function createDepthGuardState(): DepthGuardState;
+/**
+ * Wraps a tool handler to enforce a per-session call budget.
+ * Once `limit` calls have been made for a session, every further call returns
+ * TOOL_BUDGET_EXCEEDED without invoking the underlying handler.
+ * Callers without a sessionId (stdio transports — Claude Desktop, Cursor, etc.)
+ * share a single 'anon' bucket so the budget actually limits runaway tool use;
+ * giving each anon call a fresh UUID would defeat the purpose of the guard.
+ * `provardx_ping` is excluded from wrapping at the call site in server.ts.
+ */
+export declare function wrapWithDepthGuard(toolName: string, handler: AnyToolCallback, state: DepthGuardState, limit: number): AnyToolCallback;
+export declare function estimateTokens(payload: unknown): number;
+/**
+ * Appends a `_meta` key to `structuredContent` when PROVAR_MCP_EMIT_TOKEN_META=true.
+ * The `content[0].text` string is intentionally left unchanged — LLMs read that
+ * field, so including meta there would waste tokens on observability data.
+ *
+ * @param sessionTotalTokens - Cumulative estimated tokens for the session,
+ * included only on TOOL_BUDGET_EXCEEDED errors.
+ */
+export declare function attachMeta(response: ToolResult, toolName: string, detailLevel: string, sessionTotalTokens?: number): ToolResult;
+export {};

package/lib/mcp/utils/tokenMeta.js

@@ -0,0 +1,90 @@
+/*
+ * 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
+ */
+const MAX_SESSIONS = 1000;
+export function createDepthGuardState() {
+    return new Map();
+}
+function getOrCreateEntry(state, sessionId) {
+    if (!state.has(sessionId)) {
+        if (state.size >= MAX_SESSIONS) {
+            const oldest = state.keys().next().value;
+            if (oldest !== undefined)
+                state.delete(oldest);
+        }
+        state.set(sessionId, { calls: 0, totalEstimatedTokens: 0 });
+    }
+    // Non-null guaranteed by the set above or pre-existing entry.
+    return state.get(sessionId);
+}
+/**
+ * Wraps a tool handler to enforce a per-session call budget.
+ * Once `limit` calls have been made for a session, every further call returns
+ * TOOL_BUDGET_EXCEEDED without invoking the underlying handler.
+ * Callers without a sessionId (stdio transports — Claude Desktop, Cursor, etc.)
+ * share a single 'anon' bucket so the budget actually limits runaway tool use;
+ * giving each anon call a fresh UUID would defeat the purpose of the guard.
+ * `provardx_ping` is excluded from wrapping at the call site in server.ts.
+ */
+export function wrapWithDepthGuard(toolName, handler, state, limit) {
+    return async (args, extra) => {
+        const sessionId = extra.sessionId ?? 'anon';
+        const entry = getOrCreateEntry(state, sessionId);
+        if (entry.calls >= limit) {
+            const payload = {
+                error: 'TOOL_BUDGET_EXCEEDED',
+                callsMade: entry.calls,
+                limit,
+                suggestion: 'Summarize progress and return control to the user.',
+            };
+            const response = {
+                isError: true,
+                content: [{ type: 'text', text: JSON.stringify(payload) }],
+                structuredContent: payload,
+            };
+            return attachMeta(response, toolName, 'standard', entry.totalEstimatedTokens);
+        }
+        entry.calls++;
+        const result = await handler(args, extra);
+        if (process.env['PROVAR_MCP_EMIT_TOKEN_META'] === 'true') {
+            entry.totalEstimatedTokens += estimateTokens(result);
+        }
+        const detailLevel = typeof args['detail'] === 'string' ? args['detail'] : 'standard';
+        return attachMeta(result, toolName, detailLevel);
+    };
+}
+// --------------------------------------------------------------------------- //
+// PDX-475 — Token meta attachment (PROVAR_MCP_EMIT_TOKEN_META)
+// --------------------------------------------------------------------------- //
+export function estimateTokens(payload) {
+    return Math.ceil(JSON.stringify(payload).length / 4);
+}
+/**
+ * Appends a `_meta` key to `structuredContent` when PROVAR_MCP_EMIT_TOKEN_META=true.
+ * The `content[0].text` string is intentionally left unchanged — LLMs read that
+ * field, so including meta there would waste tokens on observability data.
+ *
+ * @param sessionTotalTokens - Cumulative estimated tokens for the session,
+ * included only on TOOL_BUDGET_EXCEEDED errors.
+ */
+export function attachMeta(response, toolName, detailLevel, sessionTotalTokens) {
+    if (process.env['PROVAR_MCP_EMIT_TOKEN_META'] !== 'true')
+        return response;
+    const meta = {
+        tool: toolName,
+        detailLevel,
+        estimatedTokens: estimateTokens(response),
+    };
+    if (sessionTotalTokens !== undefined) {
+        meta['sessionTotalEstimatedTokens'] = sessionTotalTokens;
+    }
+    const existing = response.structuredContent ?? {};
+    return {
+        ...response,
+        structuredContent: { ...existing, _meta: meta },
+    };
+}
+//# sourceMappingURL=tokenMeta.js.map

package/lib/mcp/utils/tokenMeta.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tokenMeta.js","sourceRoot":"","sources":["../../../src/mcp/utils/tokenMeta.ts"],"names":[],"mappings":"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"}