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

package/lib/mcp/update/updateChecker.js

@@ -0,0 +1,228 @@
+/*
+ * 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
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import os from 'node:os';
+import { fileURLToPath } from 'node:url';
+import { spawnSync } from 'node:child_process';
+import { createRequire } from 'node:module';
+import { log } from '../logging/logger.js';
+const requireJson = createRequire(import.meta.url);
+const CURRENT_SERVER_VERSION = requireJson('../../../package.json').version;
+const UPDATE_TTL_MS = 4 * 60 * 60 * 1000;
+const UPDATE_GRACE_MS = 48 * 60 * 60 * 1000;
+const SPAWN_OPTS = {
+    stdio: ['ignore', 'pipe', 'pipe'],
+    timeout: 30000,
+    shell: process.platform === 'win32',
+    maxBuffer: 10 * 1024 * 1024,
+};
+const SEMVER_RE = /^\d+\.\d+\.\d+(-[a-zA-Z0-9.]+)?$/;
+function cacheDir() {
+    const provarHome = process.env['PROVAR_HOME'] ?? path.join(os.homedir(), 'Provar');
+    return path.join(provarHome, '.cache');
+}
+function cacheFile() {
+    return path.join(cacheDir(), '.mcp-update-cache.json');
+}
+// Derives the dist-tag channel from the current version's prerelease identifier.
+// '1.5.0-beta.10' → 'beta', '1.5.0' → 'latest'
+// Same-channel assumption: we fetch dist-tags.{channel} and compare within that channel.
+// Cross-label comparison (e.g. beta vs rc) is explicitly out of scope.
+export function deriveChannel(version) {
+    const hyphen = version.indexOf('-');
+    if (hyphen === -1)
+        return 'latest';
+    return version.slice(hyphen + 1).split('.')[0] ?? 'latest';
+}
+export function isNewer(current, latest) {
+    if (current === latest)
+        return false;
+    if (!SEMVER_RE.test(latest))
+        return false;
+    const split = (v) => {
+        const [main, pre = ''] = v.split('-');
+        const [major, minor, patch] = (main ?? '').split('.').map(Number);
+        // Infinity for stable versions so stable is always newer than any prerelease
+        const preN = pre ? parseInt(pre.split('.').pop() ?? '0', 10) : Infinity;
+        return [major, minor, patch, preN];
+    };
+    const [cm, cn, cp, cpN] = split(current);
+    const [lm, ln, lp, lpN] = split(latest);
+    for (const [c, l] of [
+        [cm, lm],
+        [cn, ln],
+        [cp, lp],
+        [cpN, lpN],
+    ]) {
+        if (l > c)
+            return true;
+        if (l < c)
+            return false;
+    }
+    return false;
+}
+export function detectInstallMethod() {
+    const modulePath = fileURLToPath(import.meta.url);
+    const sfDataDirs = [
+        path.join('.local', 'share', 'sf'),
+        path.join('AppData', 'Local', 'sf'),
+        path.join('AppData', 'Roaming', 'sf'),
+        path.join('.local', 'share', 'sfdx'),
+    ];
+    if (sfDataDirs.some((d) => modulePath.includes(d)))
+        return 'sf-plugin';
+    if (modulePath.includes('node_modules'))
+        return 'npm-global';
+    return 'linked';
+}
+function readUpdateCache() {
+    try {
+        const raw = fs.readFileSync(cacheFile(), 'utf-8');
+        return JSON.parse(raw);
+    }
+    catch {
+        return null;
+    }
+}
+function writeUpdateCache(entry) {
+    try {
+        fs.mkdirSync(cacheDir(), { recursive: true });
+        const file = cacheFile();
+        fs.writeFileSync(file, JSON.stringify(entry, null, 2), { encoding: 'utf-8', mode: 0o600 });
+        try {
+            fs.chmodSync(file, 0o600);
+        }
+        catch {
+            // best effort
+        }
+    }
+    catch (err) {
+        log('warn', 'updateChecker: failed to write cache', { error: String(err) });
+    }
+}
+function buildUpdateCommand(latestVersion) {
+    const method = detectInstallMethod();
+    if (method === 'npm-global') {
+        return 'npm install -g @provartesting/provardx-cli@' + latestVersion;
+    }
+    return 'sf plugins install @provartesting/provardx-cli@' + latestVersion;
+}
+function resultFromCache(cached, currentVersion) {
+    const updateAvailable = cached.latestVersion ? isNewer(currentVersion, cached.latestVersion) : false;
+    const updateCommand = updateAvailable && cached.latestVersion ? buildUpdateCommand(cached.latestVersion) : null;
+    return { currentVersion, latestVersion: cached.latestVersion, updateAvailable, updateCommand, fromCache: true };
+}
+async function fetchLatestVersion(channel) {
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), 5000);
+    try {
+        const resp = await fetch('https://registry.npmjs.org/@provartesting/provardx-cli', {
+            signal: controller.signal,
+            headers: { Accept: 'application/json' },
+        });
+        if (!resp.ok) {
+            log('warn', 'updateChecker: registry returned non-200', { status: resp.status });
+            return null;
+        }
+        const data = (await resp.json());
+        const distTags = data['dist-tags'];
+        const candidate = distTags?.[channel];
+        if (!candidate) {
+            log('warn', 'updateChecker: dist-tag not found in registry', { channel });
+            return null;
+        }
+        if (!SEMVER_RE.test(candidate)) {
+            log('warn', 'updateChecker: registry returned invalid semver', { candidate });
+            return null;
+        }
+        return candidate;
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+function applyAutoUpdate(latestVersion) {
+    const method = detectInstallMethod();
+    if (method === 'linked') {
+        process.stderr.write('[provar-mcp] Auto-update skipped: running from development link. Install manually:\n' +
+            '  sf plugins install @provartesting/provardx-cli@' +
+            latestVersion +
+            '\n');
+        return;
+    }
+    const args = method === 'sf-plugin'
+        ? ['plugins', 'install', '@provartesting/provardx-cli@' + latestVersion]
+        : ['install', '-g', '@provartesting/provardx-cli@' + latestVersion];
+    const cmd = method === 'sf-plugin' ? 'sf' : 'npm';
+    log('info', 'updateChecker: running auto-update', { cmd, args });
+    const result = spawnSync(cmd, args, SPAWN_OPTS);
+    if (result.error != null || result.status !== 0 || result.signal != null) {
+        const detail = result.stderr?.toString().trim() ?? '';
+        log('error', 'updateChecker: auto-update failed', { status: result.status, signal: result.signal, detail });
+    }
+    else {
+        process.stderr.write('[provar-mcp] Updated to ' + latestVersion + '. Restart your MCP connection to use the new version.\n');
+        process.exit(0);
+    }
+}
+export async function checkForUpdate(opts) {
+    const currentVersion = CURRENT_SERVER_VERSION;
+    const earlyExit = {
+        currentVersion,
+        latestVersion: null,
+        updateAvailable: false,
+        updateCommand: null,
+        fromCache: false,
+    };
+    if (process.env.NODE_ENV === 'test')
+        return earlyExit;
+    if (process.env['PROVAR_NO_UPDATE_CHECK'])
+        return earlyExit;
+    if (opts.noUpdateCheck)
+        return earlyExit;
+    const channel = deriveChannel(currentVersion);
+    const cached = readUpdateCache();
+    if (cached != null &&
+        cached.channel === channel &&
+        cached.currentVersion === currentVersion &&
+        Date.now() - cached.checkedAt < UPDATE_TTL_MS) {
+        log('info', 'updateChecker: cache hit', { channel, latestVersion: cached.latestVersion, fromCache: true });
+        return resultFromCache(cached, currentVersion);
+    }
+    let latestVersion = null;
+    try {
+        latestVersion = await fetchLatestVersion(channel);
+    }
+    catch (err) {
+        const errMsg = err instanceof Error ? err.message : String(err);
+        log('warn', 'updateChecker: registry fetch failed', { error: errMsg });
+        if (cached != null && Date.now() - cached.checkedAt < UPDATE_GRACE_MS) {
+            return resultFromCache(cached, currentVersion);
+        }
+        return earlyExit;
+    }
+    writeUpdateCache({ checkedAt: Date.now(), currentVersion, latestVersion, channel });
+    const updateAvailable = latestVersion ? isNewer(currentVersion, latestVersion) : false;
+    const updateCommand = updateAvailable && latestVersion ? buildUpdateCommand(latestVersion) : null;
+    if (updateAvailable && latestVersion) {
+        process.stderr.write('[provar-mcp] Update available: ' +
+            latestVersion +
+            ' (current: ' +
+            currentVersion +
+            ')\n' +
+            '  Run: ' +
+            (updateCommand ?? '') +
+            '\n');
+        log('info', 'updateChecker: update available', { currentVersion, latestVersion, updateCommand });
+        if (opts.autoUpdate) {
+            applyAutoUpdate(latestVersion);
+        }
+    }
+    return { currentVersion, latestVersion, updateAvailable, updateCommand, fromCache: false };
+}
+//# sourceMappingURL=updateChecker.js.map

package/lib/mcp/update/updateChecker.js.map

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

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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"}

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

@@ -0,0 +1,57 @@
+export type DiffableViolation = Record<string, unknown>;
+export interface DiffResult {
+    added: DiffableViolation[];
+    resolved: DiffableViolation[];
+    unchanged_count: number;
+    run_id: string;
+}
+/**
+ * Compute a stable 8-char context hash for a tool + context pair. Used to
+ * scope baseline run lookups so that a run_id from context A cannot be diffed
+ * against context B (different project, different suite, different file).
+ */
+export declare function computeContextHash(toolTag: string, context: string): string;
+/**
+ * Resolve the validation storage root for a given tool subdir. Honors the
+ * PROVAR_MCP_VALIDATION_DIR env var when set; otherwise falls back to
+ * `~/.provardx/validation/<subdir>`. The env override is useful for restricted
+ * CI/dev environments where the home directory is read-only or shared.
+ */
+export declare function resolveValidationDir(subdir: string): string;
+/** Generate a run ID from a context string (e.g. project path or suite name). */
+export declare function generateRunId(context: string): string;
+/**
+ * Check whether any prior runs exist in the given storage directory.
+ * Used by calcNextAction to determine the first-run heuristic.
+ */
+export declare function hasAnyRun(storageDir: string): boolean;
+/**
+ * Save the current violations as a new run in the storage directory.
+ * Caps the index at MAX_RUNS by evicting the oldest entry when full.
+ * Returns the generated run_id.
+ *
+ * When `contextHash` is provided, it is recorded alongside the run so that
+ * `loadBaselineViolations` can reject a baseline_run_id whose context does
+ * not match the calling context (prevents cross-context diffs).
+ */
+export declare function saveRun(storageDir: string, runId: string, violations: DiffableViolation[], contextHash?: string): string;
+/**
+ * Load the violations array for a given baseline run ID.
+ * Returns null if the run is not found in the index (BASELINE_NOT_FOUND).
+ * The filename is looked up from the index only — the run_id itself is never
+ * used to construct a file path, preventing path traversal.
+ *
+ * When `expectedContextHash` is provided, the record's `context_hash` must
+ * match. Records without a `context_hash` (written by older versions before
+ * H3) are treated as a mismatch and are effectively retired within one or
+ * two new runs as the FIFO cap evicts them. This guard prevents diffing a
+ * baseline from a different file/suite/project against the current context.
+ */
+export declare function loadBaselineViolations(storageDir: string, baselineRunId: string, expectedContextHash?: string): DiffableViolation[] | null;
+/**
+ * Compute the diff between a baseline and current violations array.
+ * Uses (rule_id + applies_to + full message) as the unique key.
+ * Duplicate violations (same key, multiple occurrences) are treated as
+ * distinct entries — each occurrence is counted separately (multiset semantics).
+ */
+export declare function computeDiff(baseline: DiffableViolation[], current: DiffableViolation[]): Omit<DiffResult, 'run_id'>;