tribunal-kit 9.0.0 → 9.0.1

package/dist/browser/sentinel.js

@@ -0,0 +1,202 @@
+'use strict';
+
+/**
+ * sentinel.js — Runtime Sentinel & Live Error Hunter
+ *
+ * Connects to a local dev server via headless Chrome, intercepts uncaught exceptions,
+ * React runtime errors, hydration mismatches, and failed API requests, mapping them
+ * to specific source file locations for automated diagnosis and fix verification.
+ */
+
+const path = require('path');
+const fs = require('fs');
+const { launchBrowser } = require('./launcher');
+const { CdpClient, createNewTab, closeTab } = require('./cdp');
+
+/**
+ * Parses stack trace string to find local source file references.
+ * @param {string} stackText
+ * @param {string} projectRoot
+ * @returns {Array<{ filePath: string, existsLocally: boolean, line: number, column: number, rawUrl: string }>}
+ */
+function extractSourceLocations(stackText, projectRoot = process.cwd()) {
+  if (!stackText) return [];
+  const locations = [];
+  const lines = stackText.split('\n');
+
+  const fileRegex = /(?:at\s+(?:.*?\s+)?\(?|webpack-internal:\/\/\/\.?\/)(https?:\/\/[^\/]+)?(\/[^\s:)]+):(\d+):(\d+)\)?/g;
+
+  for (const line of lines) {
+    let match;
+    while ((match = fileRegex.exec(line)) !== null) {
+      const rawPath = match[2];
+      const lineNum = parseInt(match[3], 10);
+      const colNum = parseInt(match[4], 10);
+
+      const cleaned = rawPath.replace(/^\/_next\/static\/chunks\//, '').replace(/^\/src\//, 'src/');
+      const candidates = [
+        path.resolve(projectRoot, cleaned),
+        path.resolve(projectRoot, rawPath.replace(/^\//, '')),
+      ];
+
+      let resolvedFile = null;
+      for (const cand of candidates) {
+        if (fs.existsSync(cand)) {
+          resolvedFile = cand;
+          break;
+        }
+      }
+
+      locations.push({
+        rawUrl: match[0],
+        filePath: resolvedFile || rawPath,
+        existsLocally: !!resolvedFile,
+        line: lineNum,
+        column: colNum,
+      });
+    }
+  }
+
+  return locations;
+}
+
+/**
+ * Captures live runtime errors, uncaught exceptions, and console errors from a web page.
+ * @param {string} url Target URL (e.g. http://localhost:3000)
+ * @param {object} options Options { timeoutMs, settleWaitMs }
+ * @returns {Promise<object>} Diagnostic report
+ */
+async function captureRuntimeErrors(url, options = {}) {
+  const browser = await launchBrowser();
+  let client = null;
+  let tab = null;
+
+  const exceptions = [];
+  const consoleErrors = [];
+  const networkFailures = [];
+
+  try {
+    tab = await createNewTab(browser.port);
+    client = new CdpClient();
+    await client.connect(tab.webSocketDebuggerUrl);
+    await client.initDomains();
+
+    client.on('Runtime.exceptionThrown', (params) => {
+      const details = params?.exceptionDetails;
+      if (!details) return;
+
+      const text = details.text || details.exception?.description || 'Uncaught exception';
+      const stack = details.stackTrace
+        ? details.stackTrace.callFrames
+            ?.map((f) => `    at ${f.functionName || '<anonymous>'} (${f.url}:${f.lineNumber}:${f.columnNumber})`)
+            .join('\n')
+        : details.exception?.description || '';
+
+      exceptions.push({
+        text,
+        url: details.url,
+        line: details.lineNumber,
+        column: details.columnNumber,
+        stack,
+        locations: extractSourceLocations(stack),
+      });
+    });
+
+    client.on('Console.messageAdded', (params) => {
+      const msg = params?.message;
+      if (msg && msg.level === 'error') {
+        consoleErrors.push({
+          level: msg.level,
+          text: msg.text,
+          url: msg.url,
+          line: msg.line,
+          column: msg.column,
+          locations: extractSourceLocations(msg.text + (msg.url ? `\n at ${msg.url}:${msg.line}:0` : '')),
+        });
+      }
+    });
+
+    client.on('Network.responseReceived', (params) => {
+      const res = params?.response;
+      if (res && res.status >= 400) {
+        networkFailures.push({
+          url: res.url,
+          status: res.status,
+          statusText: res.statusText,
+        });
+      }
+    });
+
+    const startTime = Date.now();
+    await client.navigate(url);
+    const settleWaitMs = options.settleWaitMs || 1000;
+    await new Promise((r) => setTimeout(r, settleWaitMs));
+
+    // Check for standard error overlays (Next.js, Vite, CRA)
+    const overlayInfo = await client.evaluate(`
+      (() => {
+        const nextOverlay = document.querySelector('nextjs-portal, [data-nextjs-dialog-overlay]');
+        const viteOverlay = document.querySelector('vite-error-overlay');
+        const reactOverlay = document.querySelector('iframe[srcdoc*="error"], #webpack-dev-server-client-overlay');
+
+        return {
+          hasOverlay: !!(nextOverlay || viteOverlay || reactOverlay),
+          overlayType: nextOverlay ? 'Next.js' : viteOverlay ? 'Vite' : reactOverlay ? 'Webpack/CRA' : null,
+          bodyText: (document.body ? document.body.innerText.slice(0, 500) : ''),
+        };
+      })()
+    `);
+
+    const totalIssues =
+      exceptions.length +
+      consoleErrors.length +
+      networkFailures.length +
+      (overlayInfo?.hasOverlay ? 1 : 0);
+
+    return {
+      url,
+      timestamp: new Date().toISOString(),
+      durationMs: Date.now() - startTime,
+      healthy: totalIssues === 0,
+      overlay: overlayInfo || { hasOverlay: false },
+      exceptions,
+      consoleErrors,
+      networkFailures,
+      summary: {
+        totalExceptions: exceptions.length,
+        totalConsoleErrors: consoleErrors.length,
+        totalNetworkFailures: networkFailures.length,
+        hasErrorOverlay: !!overlayInfo?.hasOverlay,
+      },
+    };
+  } finally {
+    if (client) client.close();
+    if (tab && browser) await closeTab(tab.id, browser.port);
+    await browser.close();
+  }
+}
+
+/**
+ * Re-navigates to target URL to verify whether runtime errors have cleared.
+ * @param {string} url
+ * @param {object} options
+ * @returns {Promise<{ isFixed: boolean, remainingIssues: number, report: object }>}
+ */
+async function verifyRuntimeFix(url, options = {}) {
+  const report = await captureRuntimeErrors(url, options);
+  const remaining =
+    report.summary.totalExceptions +
+    report.summary.totalConsoleErrors +
+    (report.overlay.hasOverlay ? 1 : 0);
+  return {
+    isFixed: remaining === 0,
+    remainingIssues: remaining,
+    report,
+  };
+}
+
+module.exports = {
+  extractSourceLocations,
+  captureRuntimeErrors,
+  verifyRuntimeFix,
+};

package/dist/browser/synapse.js

@@ -0,0 +1,251 @@
+'use strict';
+
+/**
+ * synapse.js — Component Synapse Engine for Tribunal-Kit
+ *
+ * Reverse-engineers live website elements into production-ready, typed React components.
+ * Computes exact CSSOM styles (geometry, color tokens, typography, elevation, transitions)
+ * and synthesizes clean TSX code adhering to Tribunal Kit's anti-slop design principles.
+ */
+
+const { launchBrowser } = require('./launcher');
+const { CdpClient, createNewTab, closeTab } = require('./cdp');
+
+/**
+ * Extracts computed styles and structure for an element on a live page.
+ * @param {string} url
+ * @param {string} selector
+ * @param {object} options
+ * @returns {Promise<object>}
+ */
+async function deconstructElement(url, selector, options = {}) {
+  const browser = await launchBrowser();
+  let client = null;
+  let tab = null;
+
+  try {
+    tab = await createNewTab(browser.port);
+    client = new CdpClient();
+    await client.connect(tab.webSocketDebuggerUrl);
+    await client.initDomains();
+
+    await client.navigate(url);
+    await new Promise(r => setTimeout(r, 600)); // Allow hydration and fonts to settle
+
+    const extracted = await client.evaluate(`
+      (() => {
+        const el = document.querySelector(${JSON.stringify(selector)});
+        if (!el) {
+          return { error: 'Element matching selector not found: ' + ${JSON.stringify(selector)} };
+        }
+
+        const cs = window.getComputedStyle(el);
+
+        const tagName = el.tagName.toLowerCase();
+        const text = el.innerText ? el.innerText.trim() : '';
+        const hasSvg = !!el.querySelector('svg');
+
+        // Extract clean computed properties
+        const styles = {
+          display: cs.display,
+          flexDirection: cs.flexDirection,
+          alignItems: cs.alignItems,
+          justifyContent: cs.justifyContent,
+          gap: cs.gap,
+          width: cs.width,
+          height: cs.height,
+          padding: cs.padding,
+          margin: cs.margin,
+          backgroundColor: cs.backgroundColor,
+          color: cs.color,
+          borderColor: cs.borderColor,
+          borderWidth: cs.borderWidth,
+          borderStyle: cs.borderStyle,
+          borderRadius: cs.borderRadius,
+          fontFamily: cs.fontFamily,
+          fontSize: cs.fontSize,
+          fontWeight: cs.fontWeight,
+          lineHeight: cs.lineHeight,
+          letterSpacing: cs.letterSpacing,
+          textAlign: cs.textAlign,
+          boxShadow: cs.boxShadow,
+          backdropFilter: cs.backdropFilter,
+          transition: cs.transition,
+          cursor: cs.cursor,
+          opacity: cs.opacity,
+        };
+
+        return {
+          tagName,
+          text,
+          hasSvg,
+          styles,
+        };
+      })()
+    `);
+
+    if (extracted.error) {
+      throw new Error(extracted.error);
+    }
+
+    const componentName = options.name || sanitizeComponentName(selector);
+    const tsxCode = synthesizeReactComponent(componentName, extracted, options);
+
+    return {
+      url,
+      selector,
+      componentName,
+      extracted,
+      code: tsxCode,
+    };
+  } finally {
+    if (client) client.close();
+    if (tab && browser) await closeTab(tab.id, browser.port);
+    await browser.close();
+  }
+}
+
+/**
+ * Converts a selector string into a PascalCase component name.
+ */
+function sanitizeComponentName(selector) {
+  const cleaned = selector.replace(/[^a-zA-Z0-9]/g, ' ');
+  const words = cleaned.trim().split(/\s+/).filter(Boolean);
+  if (words.length === 0) return 'CustomComponent';
+  return words.map(w => w[0].toUpperCase() + w.slice(1)).join('') + 'Component';
+}
+
+/**
+ * Maps computed CSS properties into clean Tailwind utility classes.
+ */
+function mapStylesToTailwind(styles) {
+  const classes = [];
+
+  // Display & Layout
+  if (styles.display === 'flex') {
+    classes.push('flex');
+    if (styles.flexDirection === 'column') classes.push('flex-col');
+    if (styles.alignItems === 'center') classes.push('items-center');
+    if (styles.justifyContent === 'center') classes.push('justify-center');
+    if (styles.justifyContent === 'space-between') classes.push('justify-between');
+  } else if (styles.display === 'inline-flex') {
+    classes.push('inline-flex', 'items-center', 'justify-center');
+  } else if (styles.display === 'grid') {
+    classes.push('grid');
+  }
+
+  // Border radius
+  const br = parseInt(styles.borderRadius, 10);
+  if (br >= 9999 || styles.borderRadius === '50%') classes.push('rounded-full');
+  else if (br >= 16) classes.push('rounded-2xl');
+  else if (br >= 12) classes.push('rounded-xl');
+  else if (br >= 8) classes.push('rounded-lg');
+  else if (br >= 6) classes.push('rounded-md');
+  else if (br >= 4) classes.push('rounded');
+
+  // Font weight
+  const fw = parseInt(styles.fontWeight, 10);
+  if (fw >= 700) classes.push('font-bold');
+  else if (fw >= 600) classes.push('font-semibold');
+  else if (fw >= 500) classes.push('font-medium');
+
+  // Cursor & Transitions
+  if (styles.cursor === 'pointer') {
+    classes.push('cursor-pointer', 'transition-all', 'duration-200', 'active:scale-[0.98]');
+  }
+
+  // Shadow
+  if (styles.boxShadow && styles.boxShadow !== 'none') {
+    classes.push('shadow-sm hover:shadow-md');
+  }
+
+  return classes.join(' ');
+}
+
+/**
+ * Synthesizes production-grade React + TypeScript component code.
+ */
+function synthesizeReactComponent(componentName, data, options = {}) {
+  const { tagName, text, styles } = data;
+  const twClasses = mapStylesToTailwind(styles);
+
+  const isButton = tagName === 'button' || styles.cursor === 'pointer';
+  const isInput = tagName === 'input';
+
+  if (isInput) {
+    return `import React from 'react';
+
+export interface ${componentName}Props extends React.InputHTMLAttributes<HTMLInputElement> {
+  label?: string;
+  error?: string;
+}
+
+export const ${componentName}: React.FC<${componentName}Props> = ({
+  label,
+  error,
+  className = '',
+  ...props
+}) => {
+  return (
+    <div className="flex flex-col gap-1.5 w-full">
+      {label && (
+        <label className="text-sm font-medium text-neutral-700 dark:text-neutral-300">
+          {label}
+        </label>
+      )}
+      <input
+        className={\`w-full px-3.5 py-2 text-sm rounded-lg border border-neutral-300 dark:border-neutral-700 bg-white dark:bg-neutral-900 text-neutral-900 dark:text-white placeholder:text-neutral-400 focus:outline-none focus:ring-2 focus:ring-neutral-400 dark:focus:ring-neutral-600 transition-all \${className}\`}
+        {...props}
+      />
+      {error && <span className="text-xs text-rose-500">{error}</span>}
+    </div>
+  );
+};
+
+export default ${componentName};
+`;
+  }
+
+  return `import React from 'react';
+
+export interface ${componentName}Props {
+  children?: React.ReactNode;
+  className?: string;
+  onClick?: () => void;
+  disabled?: boolean;
+}
+
+/**
+ * ${componentName}
+ * Deconstructed via Tribunal Kit Component Synapse.
+ */
+export const ${componentName}: React.FC<${componentName}Props> = ({
+  children = ${JSON.stringify(text || 'Click me')},
+  className = '',
+  onClick,
+  disabled = false,
+}) => {
+  return (
+    <${isButton ? 'button' : 'div'}
+      onClick={onClick}
+      disabled={disabled}
+      className={\`relative ${twClasses} px-4 py-2 text-sm font-medium border border-neutral-200 dark:border-neutral-800 bg-white dark:bg-neutral-900 text-neutral-900 dark:text-white hover:bg-neutral-50 dark:hover:bg-neutral-800/80 focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-neutral-400 disabled:opacity-50 disabled:pointer-events-none \${className}\`}
+      style={{
+        borderRadius: ${JSON.stringify(styles.borderRadius || '8px')},
+      }}
+    >
+      {children}
+    </${isButton ? 'button' : 'div'}>
+  );
+};
+
+export default ${componentName};
+`;
+}
+
+module.exports = {
+  deconstructElement,
+  mapStylesToTailwind,
+  synthesizeReactComponent,
+  sanitizeComponentName,
+};

package/dist/browser/trimmer.js

@@ -0,0 +1,210 @@
+'use strict';
+
+/**
+ * trimmer.js — High-Performance Token Pruning Engine for Tribunal-Kit
+ *
+ * Implements PinchTab's token-efficient htmltrim algorithm in Node.js.
+ * Strips scripts, styles, comments, SVG (with nested depth tracking), data URIs,
+ * and excess whitespace, then strictly truncates on UTF-8 rune boundaries to 4,000 bytes.
+ * Also converts raw HTML into a compact, accessible semantic markdown representation.
+ */
+
+const MAX_TRIMMED_BYTES = 4000;
+
+/**
+ * Strips scripts, styles, comments, SVG, and data URIs, then caps at maxBytes.
+ * @param {string} html
+ * @param {number} maxBytes
+ * @returns {string}
+ */
+function trimHTML(html, maxBytes = MAX_TRIMMED_BYTES) {
+  if (!html || typeof html !== 'string') return '';
+
+  // 1. Strip scripts, styles, comments
+  let cleaned = html
+    .replace(/<script\b[^>]*>([\s\S]*?)<\/script>/gi, '')
+    .replace(/<style\b[^>]*>([\s\S]*?)<\/style>/gi, '')
+    .replace(/<!--([\s\S]*?)-->/g, '');
+
+  // 2. Strip SVG with nested depth tracking (exact port of PinchTab's stripSVG)
+  cleaned = stripSVG(cleaned);
+
+  // 3. Strip long data URIs
+  cleaned = cleaned.replace(/(data:[a-z\d.+-]+\/[a-z\d.+-]+;base64,[A-Za-z\d+/=]{30,})/gi, '[data-uri]');
+
+  // 4. Collapse excess whitespace
+  cleaned = cleaned
+    .replace(/[ \t]+/g, ' ')
+    .replace(/\n{3,}/g, '\n\n');
+
+  // 5. Trim lines and filter empty
+  const lines = cleaned
+    .split('\n')
+    .map(line => line.trim())
+    .filter(Boolean);
+
+  const joined = lines.join('\n');
+
+  // 6. Truncate to exact UTF-8 byte boundary
+  return truncateUTF8Bytes(joined, maxBytes);
+}
+
+/**
+ * Strips SVG tags with depth tracking so nested SVG tags do not terminate prematurely.
+ * @param {string} html
+ * @returns {string}
+ */
+function stripSVG(html) {
+  const lower = html.toLowerCase();
+  let result = '';
+  let i = 0;
+
+  while (i < html.length) {
+    const start = lower.indexOf('<svg', i);
+    if (start === -1) {
+      result += html.slice(i);
+      break;
+    }
+
+    // Verify tag boundary
+    const boundaryChar = lower[start + 4];
+    if (boundaryChar && !/[\s>\/]/.test(boundaryChar)) {
+      // e.g. <svgIcon>, not an SVG tag
+      result += html.slice(i, start + 4);
+      i = start + 4;
+      continue;
+    }
+
+    result += html.slice(i, start);
+
+    // Find closing </svg> considering depth
+    let depth = 1;
+    let curr = start + 4;
+    let closed = false;
+
+    while (curr < html.length) {
+      const nextOpen = lower.indexOf('<svg', curr);
+      const nextClose = lower.indexOf('</svg>', curr);
+
+      if (nextClose === -1) break;
+
+      if (nextOpen !== -1 && nextOpen < nextClose && /[\s>\/]/.test(lower[nextOpen + 4] || '')) {
+        depth++;
+        curr = nextOpen + 4;
+      } else {
+        depth--;
+        curr = nextClose + 6;
+        if (depth === 0) {
+          i = curr;
+          closed = true;
+          break;
+        }
+      }
+    }
+
+    if (!closed) {
+      // Unterminated, append remainder
+      result += html.slice(start);
+      break;
+    }
+  }
+
+  return result;
+}
+
+/**
+ * Safely truncates a string so its UTF-8 byte representation does not exceed maxBytes.
+ * Guarantees no split characters or invalid multi-byte code units.
+ * @param {string} str
+ * @param {number} maxBytes
+ * @returns {string}
+ */
+function truncateUTF8Bytes(str, maxBytes) {
+  const buf = Buffer.from(str, 'utf8');
+  if (buf.length <= maxBytes) return str;
+
+  // Slice buffer to maxBytes and step backwards if we split a UTF-8 sequence
+  let end = maxBytes;
+  while (end > 0 && (buf[end] & 0xc0) === 0x80) {
+    end--;
+  }
+
+  return buf.slice(0, end).toString('utf8');
+}
+
+/**
+ * Extracts interactive elements and layout structure into a compact semantic markdown tree.
+ * @param {string} html
+ * @returns {string}
+ */
+function toSemanticMarkdown(html) {
+  const trimmed = trimHTML(html, 16000);
+
+  // Extract title
+  const titleMatch = trimmed.match(/<title[^>]*>(.*?)<\/title>/i);
+  const title = titleMatch ? titleMatch[1].trim() : 'Untitled Page';
+
+  const output = [`# ${title}\n`];
+
+  // Headings
+  const headingRegex = /<h([1-6])[^>]*>([\s\S]*?)<\/h\1>/gi;
+  let m;
+  while ((m = headingRegex.exec(trimmed)) !== null) {
+    const level = '#'.repeat(parseInt(m[1], 10));
+    const text = stripTags(m[2]).trim();
+    if (text) output.push(`${level} ${text}`);
+  }
+
+  // Interactive Elements: Buttons, Links, Inputs
+  output.push('\n### Interactive Elements:');
+
+  let ref = 1;
+  // Buttons
+  const buttonRegex = /<button[^>]*>([\s\S]*?)<\/button>/gi;
+  while ((m = buttonRegex.exec(trimmed)) !== null) {
+    const text = stripTags(m[1]).trim();
+    if (text) output.push(`- [Button #${ref++}] "${text}"`);
+  }
+
+  // Inputs
+  const inputRegex = /<input\b([^>]*)>/gi;
+  while ((m = inputRegex.exec(trimmed)) !== null) {
+    const attrs = m[1];
+    const typeMatch = attrs.match(/type=["']([^"']+)["']/i) || attrs.match(/type=([^"'\s]+)/i);
+    const nameMatch = attrs.match(/name=["']([^"']+)["']/i) || attrs.match(/name=([^"'\s]+)/i);
+    const placeholderMatch = attrs.match(/placeholder=["']([^"']+)["']/i) || attrs.match(/placeholder=([^"'\s]+)/i);
+    const type = typeMatch ? typeMatch[1] : 'text';
+    const desc = placeholderMatch ? `placeholder="${placeholderMatch[1]}"` : nameMatch ? `name="${nameMatch[1]}"` : type;
+    output.push(`- [Input #${ref++}] type="${type}" (${desc})`);
+  }
+
+  // Links (first 25 to preserve budget)
+  const linkRegex = /<a\b[^>]*href=["']([^"']*)["'][^>]*>([\s\S]*?)<\/a>/gi;
+  let linkCount = 0;
+  while ((m = linkRegex.exec(trimmed)) !== null && linkCount < 25) {
+    const href = m[1];
+    const text = stripTags(m[2]).trim();
+    if (text && !href.startsWith('#') && !href.startsWith('javascript:')) {
+      output.push(`- [Link #${ref++}] "${text}" -> ${href}`);
+      linkCount++;
+    }
+  }
+
+  const result = output.join('\n');
+  return truncateUTF8Bytes(result, MAX_TRIMMED_BYTES);
+}
+
+/**
+ * Helper to strip HTML tags
+ */
+function stripTags(str) {
+  return str.replace(/<[^>]*>/g, '').replace(/&nbsp;/g, ' ').replace(/&amp;/g, '&');
+}
+
+module.exports = {
+  MAX_TRIMMED_BYTES,
+  trimHTML,
+  stripSVG,
+  truncateUTF8Bytes,
+  toSemanticMarkdown,
+};