@tantawowa/hosanna-tools 3.2.0 → 3.3.0

package/dist/support-tools/mcp-server/tools.js

@@ -67,6 +67,11 @@ const token_tracker_js_1 = require("./token-tracker.js");
 const roku_deploy_tool_js_1 = require("./roku-deploy-tool.js");
 const cv_recording_manager_js_1 = require("./cv-recording-manager.js");
 const cv_diagnostic_engine_js_1 = require("./cv-diagnostic-engine.js");
+function normalizeToolLimit(limit, defaultLimit) {
+    return typeof limit === 'number' && Number.isFinite(limit) && limit > 0
+        ? Math.floor(limit)
+        : defaultLimit;
+}
 // Test recordings storage directory for the current app/project workspace.
 const RECORDINGS_DIR = (0, test_runner_js_1.getRecordingsDir)();
 /**
@@ -74,6 +79,323 @@ const RECORDINGS_DIR = (0, test_runner_js_1.getRecordingsDir)();
  * 12s keeps worst-case wall clock under ~40s for the default three commands; use include_collection_view:false for ~24s max.
  */
 const GET_STATE_COMMAND_TIMEOUT_MS = 3000;
+function parseScrollJankValue(value) {
+    if (value === 'true') {
+        return true;
+    }
+    if (value === 'false') {
+        return false;
+    }
+    if (value !== '' && /^-?\d+(\.\d+)?$/.test(value)) {
+        return Number(value);
+    }
+    return value;
+}
+function parseScrollJankDetails(details) {
+    const fields = {};
+    for (const token of details.split(/\s+/)) {
+        const separatorIndex = token.indexOf('=');
+        if (separatorIndex <= 0) {
+            continue;
+        }
+        fields[token.slice(0, separatorIndex)] = parseScrollJankValue(token.slice(separatorIndex + 1));
+    }
+    return fields;
+}
+function parseScrollJankLog(log) {
+    var _a;
+    const rawData = (_a = log.data) !== null && _a !== void 0 ? _a : {};
+    const nestedData = rawData.data && typeof rawData.data === 'object' && !Array.isArray(rawData.data)
+        ? rawData.data
+        : undefined;
+    const data = (nestedData === null || nestedData === void 0 ? void 0 : nestedData.source) === 'scroll-jank' ? nestedData : rawData;
+    const source = data.source;
+    const dataEvent = typeof data.event === 'string' ? data.event : undefined;
+    const dataDetails = typeof data.details === 'string' ? data.details : undefined;
+    const dataFields = data.fields && typeof data.fields === 'object' && !Array.isArray(data.fields)
+        ? data.fields
+        : undefined;
+    if (source === 'scroll-jank' && dataEvent) {
+        const details = dataDetails !== null && dataDetails !== void 0 ? dataDetails : '';
+        return {
+            timestamp: log.timestamp,
+            time: new Date(log.timestamp).toISOString(),
+            appId: log.appId,
+            level: log.level,
+            event: dataEvent,
+            details,
+            fields: dataFields !== null && dataFields !== void 0 ? dataFields : parseScrollJankDetails(details),
+            message: log.message,
+        };
+    }
+    const marker = '[SCROLL-JANK] ';
+    const markerIndex = log.message.indexOf(marker);
+    if (markerIndex < 0) {
+        return undefined;
+    }
+    const line = log.message.slice(markerIndex + marker.length);
+    const firstSpace = line.indexOf(' ');
+    const event = firstSpace >= 0 ? line.slice(0, firstSpace) : line;
+    if (!/^[a-z0-9-]+$/i.test(event)) {
+        return undefined;
+    }
+    const details = firstSpace >= 0 ? line.slice(firstSpace + 1) : '';
+    return {
+        timestamp: log.timestamp,
+        time: new Date(log.timestamp).toISOString(),
+        appId: log.appId,
+        level: log.level,
+        event,
+        details,
+        fields: parseScrollJankDetails(details),
+        message: log.message,
+    };
+}
+function summarizeScrollJankEvents(events) {
+    var _a, _b, _c, _d, _e, _f;
+    var _g;
+    const byEvent = {};
+    const durationsByEvent = {};
+    const rowCounts = {};
+    const durationsByRow = {};
+    for (const event of events) {
+        byEvent[event.event] = ((_a = byEvent[event.event]) !== null && _a !== void 0 ? _a : 0) + 1;
+        const duration = event.fields.durationMs;
+        if (typeof duration === 'number') {
+            ((_b = durationsByEvent[_g = event.event]) !== null && _b !== void 0 ? _b : (durationsByEvent[_g] = [])).push(duration);
+        }
+        const rowIndex = event.fields.rowIndex;
+        if (typeof rowIndex === 'number') {
+            const key = String(rowIndex);
+            rowCounts[key] = ((_c = rowCounts[key]) !== null && _c !== void 0 ? _c : 0) + 1;
+            if (typeof duration === 'number') {
+                ((_d = durationsByRow[key]) !== null && _d !== void 0 ? _d : (durationsByRow[key] = [])).push(duration);
+            }
+        }
+    }
+    const summarizeDurations = (durations) => {
+        var _a, _b;
+        const sorted = [...durations].sort((a, b) => a - b);
+        const sum = sorted.reduce((acc, value) => acc + value, 0);
+        const percentile = (p) => { var _a; return (_a = sorted[Math.min(sorted.length - 1, Math.floor((sorted.length - 1) * p))]) !== null && _a !== void 0 ? _a : 0; };
+        return {
+            count: sorted.length,
+            min: (_a = sorted[0]) !== null && _a !== void 0 ? _a : 0,
+            p50: percentile(0.5),
+            p95: percentile(0.95),
+            max: (_b = sorted[sorted.length - 1]) !== null && _b !== void 0 ? _b : 0,
+            avg: sorted.length ? Number((sum / sorted.length).toFixed(2)) : 0,
+        };
+    };
+    const durationSummary = Object.fromEntries(Object.entries(durationsByEvent).map(([event, durations]) => [event, summarizeDurations(durations)]));
+    const rowDurationSummary = Object.fromEntries(Object.entries(durationsByRow).map(([row, durations]) => [row, summarizeDurations(durations)]));
+    const slowest = events
+        .filter((event) => typeof event.fields.durationMs === 'number')
+        .sort((a, b) => (Number(b.fields.durationMs) || 0) - (Number(a.fields.durationMs) || 0))
+        .slice(0, 20);
+    return {
+        total: events.length,
+        firstTimestamp: (_e = events[0]) === null || _e === void 0 ? void 0 : _e.time,
+        lastTimestamp: (_f = events[events.length - 1]) === null || _f === void 0 ? void 0 : _f.time,
+        byEvent,
+        durationSummary,
+        rowCounts,
+        rowDurationSummary,
+        slowest,
+    };
+}
+function markdownTable(headers, rows) {
+    if (rows.length === 0) {
+        return '_No rows._';
+    }
+    const escapeCell = (value) => String(value !== null && value !== void 0 ? value : '').replace(/\|/g, '\\|').replace(/\n/g, ' ');
+    return [
+        `| ${headers.map(escapeCell).join(' | ')} |`,
+        `| ${headers.map(() => '---').join(' | ')} |`,
+        ...rows.map((row) => `| ${row.map(escapeCell).join(' | ')} |`),
+    ].join('\n');
+}
+function formatScrollJankMs(value) {
+    return typeof value === 'number' ? `${value}ms` : '';
+}
+function classifyScrollJankDuration(durationMs) {
+    if (typeof durationMs !== 'number') {
+        return '';
+    }
+    if (durationMs >= 100) {
+        return 'SEVERE';
+    }
+    if (durationMs >= 33) {
+        return 'BAD';
+    }
+    if (durationMs >= 16) {
+        return 'WARN';
+    }
+    return 'OK';
+}
+function getScrollJankRowKey(fields) {
+    const rowIndex = fields.rowIndex;
+    return typeof rowIndex === 'number' ? String(rowIndex) : undefined;
+}
+function getScrollJankRowLabel(fields) {
+    for (const key of ['rowLabel', 'rowTitle', 'rowId']) {
+        const value = fields[key];
+        if (typeof value === 'string' && value.length > 0) {
+            return value;
+        }
+    }
+    return '';
+}
+function renderScrollJankTopSuspects(summary, events) {
+    var _a, _b, _c, _d, _e, _f, _g;
+    const suspects = [];
+    const slowest = summary.slowest[0];
+    if (slowest) {
+        suspects.push(`${classifyScrollJankDuration(slowest.fields.durationMs)}: worst event is ${slowest.event} at ${formatScrollJankMs(slowest.fields.durationMs)}${typeof slowest.fields.targetRow === 'number' ? ` targeting row ${slowest.fields.targetRow}` : ''}.`);
+    }
+    const calcEvents = events.filter((entry) => entry.event === 'calculate-visible-cells-end');
+    const slowCalc = calcEvents
+        .filter((entry) => typeof entry.fields.durationMs === 'number')
+        .sort((a, b) => Number(b.fields.durationMs) - Number(a.fields.durationMs))[0];
+    if (slowCalc) {
+        const row = getScrollJankRowKey(slowCalc.fields);
+        const label = getScrollJankRowLabel(slowCalc.fields);
+        suspects.push(`${classifyScrollJankDuration(slowCalc.fields.durationMs)}: slowest visible-cell calculation took ${formatScrollJankMs(slowCalc.fields.durationMs)} on row ${row !== null && row !== void 0 ? row : '?'}${label ? ` (${label})` : ''}; new=${String((_a = slowCalc.fields.new) !== null && _a !== void 0 ? _a : '')}, reused=${String((_b = slowCalc.fields.reused) !== null && _b !== void 0 ? _b : '')}, rendered=${String((_c = slowCalc.fields.rendered) !== null && _c !== void 0 ? _c : '')}.`);
+    }
+    const coldRows = calcEvents
+        .filter((entry) => { var _a; return typeof entry.fields.new === 'number' && Number(entry.fields.new) > 0 && Number((_a = entry.fields.reused) !== null && _a !== void 0 ? _a : 0) === 0; })
+        .sort((a, b) => { var _a, _b; return Number((_a = b.fields.durationMs) !== null && _a !== void 0 ? _a : 0) - Number((_b = a.fields.durationMs) !== null && _b !== void 0 ? _b : 0); })
+        .slice(0, 3);
+    for (const entry of coldRows) {
+        const row = getScrollJankRowKey(entry.fields);
+        const label = getScrollJankRowLabel(entry.fields);
+        suspects.push(`${classifyScrollJankDuration(entry.fields.durationMs)}: cold row work on row ${row !== null && row !== void 0 ? row : '?'}${label ? ` (${label})` : ''}; created ${String(entry.fields.new)} cells, reused ${String((_d = entry.fields.reused) !== null && _d !== void 0 ? _d : 0)}, duration ${formatScrollJankMs(entry.fields.durationMs)}.`);
+    }
+    const fragmentMax = (_f = (_e = summary.durationSummary['fragment-add-end']) === null || _e === void 0 ? void 0 : _e.max) !== null && _f !== void 0 ? _f : (_g = summary.durationSummary['fragment-create-end']) === null || _g === void 0 ? void 0 : _g.max;
+    if (typeof fragmentMax === 'number') {
+        suspects.push(`${classifyScrollJankDuration(fragmentMax)}: fragment add/create max is ${formatScrollJankMs(fragmentMax)}.`);
+    }
+    else {
+        suspects.push('OK: no fragment add/create duration hotspot was captured in this window.');
+    }
+    return suspects;
+}
+function renderScrollJankTelemetryReport(summary, events, options) {
+    var _a, _b, _c;
+    const durationRows = Object.entries(summary.durationSummary)
+        .sort(([, a], [, b]) => b.max - a.max)
+        .slice(0, 15)
+        .map(([name, stats]) => [
+        classifyScrollJankDuration(stats.max),
+        name,
+        stats.count,
+        formatScrollJankMs(stats.p50),
+        formatScrollJankMs(stats.p95),
+        formatScrollJankMs(stats.max),
+        formatScrollJankMs(stats.avg),
+    ]);
+    const eventRows = Object.entries(summary.byEvent)
+        .sort(([, a], [, b]) => b - a)
+        .slice(0, 20)
+        .map(([name, count]) => [name, count]);
+    const rowRows = Object.entries(summary.rowDurationSummary)
+        .sort(([, a], [, b]) => b.max - a.max)
+        .slice(0, 15)
+        .map(([row, stats]) => {
+        var _a;
+        return [
+            classifyScrollJankDuration(stats.max),
+            row,
+            (_a = summary.rowCounts[row]) !== null && _a !== void 0 ? _a : 0,
+            stats.count,
+            formatScrollJankMs(stats.p50),
+            formatScrollJankMs(stats.p95),
+            formatScrollJankMs(stats.max),
+            formatScrollJankMs(stats.avg),
+        ];
+    });
+    const slowestRows = summary.slowest.slice(0, 20).map((entry) => [
+        classifyScrollJankDuration(entry.fields.durationMs),
+        new Date(entry.timestamp).toISOString().slice(11, 23),
+        entry.event,
+        formatScrollJankMs(entry.fields.durationMs),
+        entry.fields.rowIndex,
+        getScrollJankRowLabel(entry.fields),
+        entry.fields.cellIndex,
+        entry.fields.targetRow,
+        entry.fields.new,
+        entry.fields.reused,
+        entry.fields.rendered,
+        entry.fields.virtualY,
+        entry.fields.targetY,
+    ]);
+    const rowWorkRows = events
+        .filter((entry) => entry.event === 'calculate-visible-cells-end')
+        .sort((a, b) => { var _a, _b; return Number((_a = b.fields.durationMs) !== null && _a !== void 0 ? _a : 0) - Number((_b = a.fields.durationMs) !== null && _b !== void 0 ? _b : 0); })
+        .slice(0, 20)
+        .map((entry) => {
+        var _a, _b;
+        return [
+            classifyScrollJankDuration(entry.fields.durationMs),
+            entry.fields.rowIndex,
+            getScrollJankRowLabel(entry.fields),
+            formatScrollJankMs(entry.fields.durationMs),
+            entry.fields.existingCells,
+            entry.fields.configured,
+            entry.fields.new,
+            entry.fields.reused,
+            entry.fields.removed,
+            entry.fields.rendered,
+            Number((_a = entry.fields.new) !== null && _a !== void 0 ? _a : 0) > 0 && Number((_b = entry.fields.reused) !== null && _b !== void 0 ? _b : 0) === 0 ? 'cold row' : '',
+        ];
+    });
+    const clearVerdict = summary.slowest.length === 0
+        ? 'No duration-bearing scroll-jank events were captured.'
+        : `Worst event: ${summary.slowest[0].event} at ${formatScrollJankMs(summary.slowest[0].fields.durationMs)} (${classifyScrollJankDuration(summary.slowest[0].fields.durationMs)}).`;
+    const suspects = renderScrollJankTopSuspects(summary, events);
+    const sequenceLines = ((_a = options.sequence) === null || _a === void 0 ? void 0 : _a.length)
+        ? ['## Sequence', markdownTable(['step'], options.sequence.map((step) => [step])), '']
+        : [];
+    const title = options.format === 'table' ? 'Scroll-Jank Telemetry Report' : '# Scroll-Jank Telemetry Report';
+    return [
+        title,
+        '',
+        `App: ${(_b = options.appId) !== null && _b !== void 0 ? _b : 'all apps'}`,
+        `Filter: ${(_c = options.event) !== null && _c !== void 0 ? _c : 'all events'}`,
+        `Returned events: ${events.length} / requested limit ${options.limit}`,
+        `Window: ${summary.firstTimestamp ? `${summary.firstTimestamp} -> ${summary.lastTimestamp}` : 'empty'}`,
+        `Verdict hint: ${clearVerdict}`,
+        '',
+        '## Severity Legend',
+        markdownTable(['severity', 'duration', 'meaning'], [
+            ['OK', '< 16ms', 'fits inside one 60fps frame'],
+            ['WARN', '16-32ms', 'misses one frame or is close to doing so'],
+            ['BAD', '33-99ms', 'visible jank; two or more frames at 60fps'],
+            ['SEVERE', '>= 100ms', 'major hitch likely visible to users'],
+        ]),
+        '',
+        ...sequenceLines,
+        '## Top Suspects',
+        suspects.length ? suspects.map((suspect) => `- ${suspect}`).join('\n') : '_No suspects._',
+        '',
+        '## Duration Hotspots',
+        markdownTable(['severity', 'event', 'count', 'p50', 'p95', 'max', 'avg'], durationRows),
+        '',
+        '## Slowest Events',
+        markdownTable(['severity', 'time', 'event', 'duration', 'row', 'rowLabel', 'cell', 'targetRow', 'new', 'reused', 'rendered', 'virtualY', 'targetY'], slowestRows),
+        '',
+        '## Visible Cell Work',
+        markdownTable(['severity', 'row', 'rowLabel', 'duration', 'existingCells', 'configured', 'new', 'reused', 'removed', 'rendered', 'note'], rowWorkRows),
+        '',
+        '## Row Hotspots',
+        markdownTable(['severity', 'row', 'events', 'timedEvents', 'p50', 'p95', 'max', 'avg'], rowRows),
+        '',
+        '## Event Counts',
+        markdownTable(['event', 'count'], eventRows),
+        '',
+        'Use `format: "json"` when you need the raw event payloads for scripts or deeper diffing.',
+    ].join('\n');
+}
 /**
  * Build a tool response and track token usage.
  */
@@ -5897,7 +6219,7 @@ If the app has more than one CollectionView, pass collection_view_hid from get_c
         sinceMs: zod_1.z.number().optional().describe('Only logs from the last N milliseconds'),
         sessionId: zod_1.z.string().optional().describe('Filter by debug session ID (matches data.sid field)'),
     }, async ({ appId, level, limit = 100, sinceMs, sessionId }) => {
-        const logs = client.getAppLogs({ level, sinceMs, limit, sessionId, appId });
+        const logs = await client.getAllAppLogs({ level, sinceMs, limit, sessionId, appId });
         if (logs.length === 0) {
             return {
                 content: [{ type: 'text', text: sessionId ? `No app logs matching session "${sessionId}".` : 'No app logs captured yet.' }],
@@ -5925,7 +6247,20 @@ If the app has more than one CollectionView, pass collection_view_hid from get_c
         caseSensitive: zod_1.z.boolean().optional().describe('Case-sensitive search (default: false)'),
         limit: zod_1.z.number().optional().describe('Maximum results (default: 50)'),
     }, async ({ pattern, appId, caseSensitive = false, limit = 50 }) => {
-        const matches = client.searchAppLogs(pattern, caseSensitive, appId).slice(-limit);
+        const flags = caseSensitive ? '' : 'i';
+        let regex;
+        try {
+            regex = new RegExp(pattern, flags);
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            return {
+                content: [{ type: 'text', text: `Invalid regex pattern "${pattern}": ${message}` }],
+            };
+        }
+        const resultLimit = normalizeToolLimit(limit, 50);
+        const logs = await client.getAllAppLogs({ appId, limit: resultLimit * 3 });
+        const matches = logs.filter(l => regex.test(l.message) || regex.test(l.raw)).slice(-resultLimit);
         if (matches.length === 0) {
             return {
                 content: [{ type: 'text', text: `No app logs matching "${pattern}"` }],
@@ -5944,10 +6279,72 @@ If the app has more than one CollectionView, pass collection_view_hid from get_c
                 }],
         };
     });
+    server.tool('get_scroll_jank_telemetry', 'Get structured scroll-jank telemetry emitted by Hosanna UI through remote.log(). Use after driving CollectionView scrolling to identify fragment churn, cell recalculation, SG add/remove, and animation duration hotspots.', {
+        appId: zod_1.z.string().optional().describe('Filter telemetry to a specific app by appId'),
+        sinceMs: zod_1.z.number().optional().describe('Only include telemetry from the last N milliseconds'),
+        limit: zod_1.z.number().optional().describe('Maximum number of raw telemetry events to return (default: 500)'),
+        event: zod_1.z.string().optional().describe('Optional exact event name filter, e.g. calculate-visible-cells-end'),
+        clear: zod_1.z.boolean().optional().describe('Clear app logs for the app after reading telemetry (default: false)'),
+        sequence: zod_1.z.array(zod_1.z.string()).optional().describe('Optional human-readable key sequence steps to include in table/markdown reports'),
+        format: zod_1.z.enum(['table', 'markdown', 'json', 'summary']).optional()
+            .describe('Output format: "table" or "markdown" for human review, "json" for raw events, or "summary" for concise text (default: table)'),
+    }, async ({ appId, sinceMs, limit = 500, event, clear = false, sequence, format = 'table' }) => {
+        const resultLimit = normalizeToolLimit(limit, 500);
+        const logs = await client.getAllAppLogs({ sinceMs, limit: resultLimit * 3, appId });
+        let events = logs
+            .map(parseScrollJankLog)
+            .filter((entry) => entry !== undefined);
+        if (event) {
+            events = events.filter((entry) => entry.event === event);
+        }
+        events = events.slice(-resultLimit);
+        const summary = summarizeScrollJankEvents(events);
+        if (clear) {
+            await client.clearAllAppLogs(appId);
+        }
+        if (format === 'summary') {
+            const durationLines = Object.entries(summary.durationSummary)
+                .sort(([, a], [, b]) => b.max - a.max)
+                .slice(0, 12)
+                .map(([name, stats]) => `${name}: count=${stats.count} p50=${stats.p50}ms p95=${stats.p95}ms max=${stats.max}ms avg=${stats.avg}ms`);
+            const eventLines = Object.entries(summary.byEvent)
+                .sort(([, a], [, b]) => b - a)
+                .slice(0, 20)
+                .map(([name, count]) => `${name}: ${count}`);
+            const slowestLines = summary.slowest.slice(0, 10).map((entry) => {
+                const row = typeof entry.fields.rowIndex === 'number' ? ` row=${entry.fields.rowIndex}` : '';
+                const cell = typeof entry.fields.cellIndex === 'number' ? ` cell=${entry.fields.cellIndex}` : '';
+                return `${entry.event}: ${String(entry.fields.durationMs)}ms${row}${cell} ${entry.details}`;
+            });
+            return tracked('get_scroll_jank_telemetry', [
+                `Scroll-jank telemetry: ${summary.total} event(s)`,
+                summary.firstTimestamp ? `Window: ${summary.firstTimestamp} -> ${summary.lastTimestamp}` : 'Window: empty',
+                '',
+                'Event counts:',
+                eventLines.length ? eventLines.join('\n') : '(none)',
+                '',
+                'Duration hotspots:',
+                durationLines.length ? durationLines.join('\n') : '(none)',
+                '',
+                'Slowest events:',
+                slowestLines.length ? slowestLines.join('\n') : '(none)',
+            ].join('\n'));
+        }
+        if (format === 'table' || format === 'markdown') {
+            return tracked('get_scroll_jank_telemetry', renderScrollJankTelemetryReport(summary, events, {
+                appId,
+                event,
+                limit,
+                format,
+                sequence,
+            }));
+        }
+        return tracked('get_scroll_jank_telemetry', JSON.stringify({ summary, events }, null, 2));
+    });
     server.tool('clear_app_logs', 'Clear the buffered app logs. Pass appId to clear logs for a single app only.', {
         appId: zod_1.z.string().optional().describe('Clear logs only for this appId (clears all if omitted)'),
     }, async ({ appId }) => {
-        client.clearAppLogs(appId);
+        await client.clearAllAppLogs(appId);
         return {
             content: [{ type: 'text', text: appId ? `App log buffer cleared for "${appId}".` : 'App log buffer cleared.' }],
         };