@notis_ai/cli 0.2.0-beta.156.1 → 0.2.0-beta.157.1

package/src/runtime/agent-browser.js

@@ -227,6 +227,7 @@ export async function runHarnessRoute({
   sessionName,
   timeoutMs = 10_000,
   snapshotPath = null,
+  designViewports = DEFAULT_DESIGN_VIEWPORTS,
 }) {
   const opened = await runAgentBrowser(['--session', sessionName, 'open', url], {
     timeoutMs: Math.min(Math.max(timeoutMs, 5000), 30_000),
@@ -283,14 +284,33 @@ export async function runHarnessRoute({
   }
 
   const timedOut = !harness.mounted && Date.now() >= deadline;
+  const runtimeCalls = Array.isArray(harness.runtimeCalls) ? harness.runtimeCalls : [];
+
+  // Design assertions only mean something on a mounted route. Loading
+  // placeholders are excused while a runtime call is still in flight.
+  let design = [];
+  let designToolError = null;
+  if (harness.mounted && Array.isArray(designViewports) && designViewports.length > 0) {
+    await delay(500);
+    const pending = runtimeCalls.some((call) => call && call.ok == null);
+    const collected = await collectDesignFindings(sessionName, {
+      viewports: designViewports,
+      skipLoadingCheck: pending,
+    });
+    design = collected.findings;
+    designToolError = collected.tool_error;
+  }
+
   return {
     mounted: Boolean(harness.mounted),
     renderStarted: Boolean(harness.renderStarted),
     errors: Array.isArray(harness.errors) ? harness.errors : [],
-    runtimeCalls: Array.isArray(harness.runtimeCalls) ? harness.runtimeCalls : [],
+    runtimeCalls,
     snapshotPath: savedSnapshotPath,
     timed_out: timedOut,
     tool_error: null,
+    design,
+    design_tool_error: designToolError,
     raw: harness,
   };
 }
@@ -408,6 +428,8 @@ export async function captureHarnessScreenshot({
 
   // Let the route settle (async data, resize transitions) before the capture.
   await delay(500);
+  const designResult = await evalDesignAssertions(sessionName, { viewport: 'capture' });
+  const design = Array.isArray(designResult) ? designResult : [];
 
   mkdirSync(dirname(screenshotPath), { recursive: true });
   const screenshotArgs = ['--session', sessionName, 'screenshot'];
@@ -446,6 +468,7 @@ export async function captureHarnessScreenshot({
   }
 
   return {
+    design,
     ok: true,
     mounted: true,
     screenshotPath,
@@ -462,3 +485,148 @@ export async function closeAgentBrowserSession(sessionName) {
   });
   return result.exitCode === 0;
 }
+
+// ---------------------------------------------------------------------------
+// Runtime design assertions.
+//
+// The static design lint (app-boundary-validator.js) catches banned class
+// names. This script runs in the mounted harness page and catches what a
+// regex cannot: a bordered box nested in a bordered box across files, tinted
+// panels stacked three deep, text that computes below 12px, horizontal
+// overflow at a phone width, and loading placeholders that outlive the data.
+// Palette colors are deliberately not checked here: at runtime a token and a
+// hardcoded hue resolve to the same RGB, so that stays with the static lint.
+// ---------------------------------------------------------------------------
+export const DESIGN_ASSERTIONS_MARKER = '__notisDesignAssertions';
+
+export const DESIGN_ASSERTIONS_SCRIPT = `(() => {
+  /* ${DESIGN_ASSERTIONS_MARKER} */
+  const root = document.getElementById('root') || document.body;
+  const out = [];
+  const seen = new Set();
+  const push = (kind, el, extra) => {
+    const cls = String(el.className && el.className.baseVal !== undefined ? el.className.baseVal : el.className || '').trim().slice(0, 80);
+    const text = (el.textContent || '').trim().replace(/\\s+/g, ' ').slice(0, 60);
+    const snippet = el.tagName.toLowerCase() + (cls ? '.' + cls.split(/\\s+/).slice(0, 6).join('.') : '') + (text ? ' "' + text + '"' : '');
+    const key = kind + '|' + snippet;
+    if (seen.has(key)) return;
+    seen.add(key);
+    out.push(Object.assign({ kind, snippet }, extra || {}));
+  };
+  const controls = new Set(['INPUT', 'SELECT', 'TEXTAREA', 'BUTTON', 'A', 'SUMMARY']);
+  const isControl = (el) => controls.has(el.tagName) || /^(button|checkbox|switch|radio|combobox|textbox|tab|menuitem)$/.test(el.getAttribute('role') || '');
+  const visible = (el) => { const r = el.getBoundingClientRect(); return r.width > 0 && r.height > 0; };
+  const isBox = (el) => {
+    const cs = getComputedStyle(el);
+    if (!['borderTopWidth', 'borderRightWidth', 'borderBottomWidth', 'borderLeftWidth'].every((k) => parseFloat(cs[k]) > 0)) return false;
+    if (/rgba\\(\\d+, \\d+, \\d+, 0\\)|transparent/.test(cs.borderTopColor)) return false;
+    const r = el.getBoundingClientRect();
+    return r.width > 40 && r.height > 20;
+  };
+  const bg = (el) => getComputedStyle(el).backgroundColor;
+  const transparent = (c) => !c || c === 'transparent' || /rgba\\(\\d+, \\d+, \\d+, 0\\)/.test(c);
+  const isPanel = (el) => {
+    if (transparent(bg(el))) return false;
+    if (parseFloat(getComputedStyle(el).borderRadius) <= 0) return false;
+    const r = el.getBoundingClientRect();
+    return r.width > 160 && r.height > 48;
+  };
+  const all = Array.from(root.querySelectorAll('*'));
+  for (const el of all) {
+    if (el.id === 'harness-status' || !visible(el) || isControl(el)) continue;
+    if (isBox(el)) {
+      let p = el.parentElement; let depth = 0;
+      while (p && p !== root && depth < 6) { if (!isControl(p) && isBox(p)) { push('nested_border_box', el); break; } p = p.parentElement; depth += 1; }
+    }
+    if (isPanel(el)) {
+      let p = el.parentElement; let panels = 0;
+      while (p && p !== root) { if (isPanel(p)) panels += 1; p = p.parentElement; }
+      if (panels >= 2) push('nested_tinted_panel', el, { depth: panels + 1 });
+    }
+  }
+  const walker = document.createTreeWalker(root, NodeFilter.SHOW_TEXT);
+  let node;
+  while ((node = walker.nextNode())) {
+    const text = (node.textContent || '').trim();
+    if (!text) continue;
+    const el = node.parentElement;
+    if (!el || el.closest('#harness-status') || !visible(el)) continue;
+    const size = parseFloat(getComputedStyle(el).fontSize);
+    if (size > 0 && size < 12) push('text_below_12px', el, { font_size: size });
+    if (/^Loading(\\.{3}|\\u2026)?(\\s|$)/.test(text)) push('loading_placeholder_after_mount', el);
+  }
+  if (root.querySelector('[data-notis-content-skeleton]')) push('loading_placeholder_after_mount', root.querySelector('[data-notis-content-skeleton]'));
+  const doc = document.documentElement;
+  if (doc.scrollWidth > doc.clientWidth + 1) out.push({ kind: 'horizontal_overflow', snippet: 'document', scroll_width: doc.scrollWidth, client_width: doc.clientWidth });
+  return JSON.stringify(out.slice(0, 40));
+})()`;
+
+export const DEFAULT_DESIGN_VIEWPORTS = [
+  { name: 'desktop', width: 1280, height: 900 },
+  { name: 'mobile', width: 390, height: 844 },
+];
+
+const DESIGN_KIND_MESSAGES = {
+  nested_border_box: 'a bordered box sits inside another bordered box',
+  nested_tinted_panel: 'tinted panels are nested three deep',
+  text_below_12px: 'visible text renders below 12px',
+  loading_placeholder_after_mount: 'a loading placeholder is still visible after the route mounted with its data',
+  horizontal_overflow: 'the page overflows horizontally',
+};
+
+export function describeDesignFinding(finding) {
+  const base = DESIGN_KIND_MESSAGES[finding.kind] || finding.kind;
+  const where = finding.viewport ? ` at ${finding.viewport}` : '';
+  const detail = finding.snippet && finding.snippet !== 'document' ? `: ${finding.snippet}` : '';
+  return `${base}${where}${detail}`;
+}
+
+/**
+ * Evaluate the design assertions in the current page. Returns an array of
+ * findings, or `{ tool_error }` when agent-browser could not run the script.
+ */
+export async function evalDesignAssertions(sessionName, { viewport = null, timeoutMs = 8000 } = {}) {
+  const result = await runAgentBrowser(
+    ['--session', sessionName, '--json', 'eval', DESIGN_ASSERTIONS_SCRIPT],
+    { timeoutMs },
+  );
+  if (result.exitCode !== 0) {
+    return { tool_error: commandError('design_eval', result) };
+  }
+  try {
+    const payload = parseAgentBrowserJson(result.stdout);
+    const raw = payload?.data?.result ?? payload?.result ?? payload?.data ?? null;
+    const value = typeof raw === 'string' ? JSON.parse(raw) : raw;
+    if (!Array.isArray(value)) throw new Error('Design evaluation did not return a findings array.');
+    return value.map((finding) => ({ ...finding, viewport: viewport || finding.viewport || null }));
+  } catch (error) {
+    return { tool_error: { phase: 'design_eval_parse', message: error.message } };
+  }
+}
+
+/**
+ * Run every requested viewport. Missing browser checks are incomplete proof,
+ * not a passing design result, even when static source lint passed.
+ */
+export async function collectDesignFindings(sessionName, { viewports = DEFAULT_DESIGN_VIEWPORTS, settleMs = 350, skipLoadingCheck = false } = {}) {
+  const findings = [];
+  let toolError = null;
+  for (const viewport of viewports) {
+    const applied = await setViewport(sessionName, viewport.width, viewport.height);
+    if (!applied) {
+      toolError ||= { phase: 'design_viewport', message: `Could not set ${viewport.name} viewport.` };
+      continue;
+    }
+    await delay(settleMs);
+    const result = await evalDesignAssertions(sessionName, { viewport: viewport.name });
+    if (Array.isArray(result)) {
+      for (const finding of result) {
+        if (skipLoadingCheck && finding.kind === 'loading_placeholder_after_mount') continue;
+        findings.push(finding);
+      }
+    } else if (!toolError) {
+      toolError = result.tool_error;
+    }
+  }
+  return { findings, tool_error: toolError };
+}

package/src/runtime/app-boundary-validator.js

@@ -181,3 +181,224 @@ export function validateArtifactBoundary(files) {
     );
   }
 }
+
+// ---------------------------------------------------------------------------
+// Design rules
+//
+// The portal boundary rules above keep an app inside its surface. The design
+// rules below keep it looking like a native, flat Notis page: no bordered
+// boxes around items, no dividers, no palette colors, no eyebrows, no loading
+// text. They are path-scoped, report line numbers, and only ever run on the
+// app's own source files (never on the bundled artifact, where every
+// dependency legitimately contains the word "border").
+//
+// The only override is an inline directive on the same line or the line
+// before the match:
+//   // notis-design-allow: <rule-id> <reason of at least N characters>
+// Allowed matches are reported with `allowed: true` so they stay visible.
+// ---------------------------------------------------------------------------
+
+export const DESIGN_RULES_PATH_CANDIDATES = [
+  resolve(moduleDir, '../../../../server/config/notis_app_design_rules.json'),
+  resolve(moduleDir, '../../config/notis_app_design_rules.json'),
+];
+
+export function resolveDesignRulesPath() {
+  for (const candidate of DESIGN_RULES_PATH_CANDIDATES) {
+    if (existsSync(candidate)) {
+      return candidate;
+    }
+  }
+  return DESIGN_RULES_PATH_CANDIDATES[DESIGN_RULES_PATH_CANDIDATES.length - 1];
+}
+
+const DEFAULT_DESIGN_EXTENSIONS = ['.js', '.jsx', '.ts', '.tsx', '.css'];
+
+function globToRegExp(glob) {
+  let source = '';
+  for (let index = 0; index < glob.length; index += 1) {
+    const char = glob[index];
+    if (char === '*') {
+      if (glob[index + 1] === '*') {
+        index += 1;
+        if (glob[index + 1] === '/') {
+          index += 1;
+          source += '(?:.*/)?';
+        } else {
+          source += '.*';
+        }
+      } else {
+        source += '[^/]*';
+      }
+    } else if (char === '?') {
+      source += '[^/]';
+    } else {
+      source += char.replace(/[.+^${}()|[\]\\]/g, '\\$&');
+    }
+  }
+  return new RegExp(`^${source}$`);
+}
+
+function matchesAny(relPath, globs) {
+  return (globs || []).some((glob) => globToRegExp(glob).test(relPath));
+}
+
+let compiledDesignRules = null;
+
+export function loadDesignRules({ rulesPath = resolveDesignRulesPath() } = {}) {
+  let payload = null;
+  try {
+    const parsed = JSON.parse(readFileSync(rulesPath, 'utf-8'));
+    if (parsed && typeof parsed === 'object' && !Array.isArray(parsed)) {
+      payload = parsed;
+    }
+  } catch (error) {
+    process.stderr.write(
+      `Warning: could not load Notis app design rules (${error.message}); skipping design checks.\n`,
+    );
+  }
+  if (!payload) {
+    return { include: [], exclude: [], extensions: DEFAULT_DESIGN_EXTENSIONS, rules: [], allowDirective: 'notis-design-allow', allowReasonMinLength: 12 };
+  }
+  return {
+    include: Array.isArray(payload.include) ? payload.include : ['app/**', 'components/**'],
+    exclude: Array.isArray(payload.exclude) ? payload.exclude : [],
+    extensions: Array.isArray(payload.extensions) ? payload.extensions : DEFAULT_DESIGN_EXTENSIONS,
+    allowDirective: typeof payload.allow_directive === 'string' ? payload.allow_directive : 'notis-design-allow',
+    allowReasonMinLength: Number.isInteger(payload.allow_reason_min_length) ? payload.allow_reason_min_length : 12,
+    rules: (Array.isArray(payload.rules) ? payload.rules : []).map((rule) => ({
+      id: rule.id,
+      severity: rule.severity === 'warn' ? 'warn' : 'error',
+      scope: rule.scope === 'file' ? 'file' : 'line',
+      regex: new RegExp(rule.pattern, rule.scope === 'file' ? '' : 'gm'),
+      message: rule.message,
+      include: Array.isArray(rule.include) ? rule.include : null,
+      exclude: Array.isArray(rule.exclude) ? rule.exclude : [],
+    })),
+  };
+}
+
+function getCompiledDesignRules() {
+  if (!compiledDesignRules) {
+    compiledDesignRules = loadDesignRules();
+  }
+  return compiledDesignRules;
+}
+
+function lineNumberAt(content, index) {
+  let line = 1;
+  for (let cursor = 0; cursor < index; cursor += 1) {
+    if (content.charCodeAt(cursor) === 10) line += 1;
+  }
+  return line;
+}
+
+function findAllowDirective(lines, lineNumber, ruleId, directive) {
+  const pattern = new RegExp(`${directive}:\\s*${ruleId.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}\\b\\s*(.*)$`);
+  for (const candidate of [lines[lineNumber - 1], lines[lineNumber - 2]]) {
+    if (typeof candidate !== 'string') continue;
+    const match = candidate.match(pattern);
+    if (match) {
+      return match[1].replace(/\*\/\s*}?\s*$/, '').replace(/-->\s*$/, '').trim();
+    }
+  }
+  return null;
+}
+
+export function collectDesignViolationsForFile(relPath, content, config = getCompiledDesignRules()) {
+  const normalized = relPath.split('\\').join('/');
+  if (!config.extensions.includes(extname(normalized))) return [];
+  if (!matchesAny(normalized, config.include)) return [];
+  if (matchesAny(normalized, config.exclude)) return [];
+
+  const lines = content.split('\n');
+  const violations = [];
+  for (const rule of config.rules) {
+    if (rule.include && !matchesAny(normalized, rule.include)) continue;
+    if (matchesAny(normalized, rule.exclude)) continue;
+
+    const matches = [];
+    if (rule.scope === 'file') {
+      const match = rule.regex.exec(content);
+      if (match) matches.push(match.index);
+    } else {
+      rule.regex.lastIndex = 0;
+      let match;
+      while ((match = rule.regex.exec(content)) !== null) {
+        matches.push(match.index);
+        if (match[0].length === 0) rule.regex.lastIndex += 1;
+      }
+    }
+
+    const seenLines = new Set();
+    for (const index of matches) {
+      const line = lineNumberAt(content, index);
+      if (seenLines.has(line)) continue;
+      seenLines.add(line);
+      const reason = findAllowDirective(lines, line, rule.id, config.allowDirective);
+      const allowed = reason !== null && reason.length >= config.allowReasonMinLength;
+      violations.push({
+        file: normalized,
+        line,
+        ruleId: rule.id,
+        severity: allowed ? 'warn' : rule.severity,
+        message: reason !== null && !allowed
+          ? `${rule.message} (a notis-design-allow directive needs a reason of at least ${config.allowReasonMinLength} characters)`
+          : rule.message,
+        allowed,
+        reason: allowed ? reason : null,
+      });
+    }
+  }
+  return violations;
+}
+
+export function collectProjectDesignViolations(projectDir, config = getCompiledDesignRules()) {
+  const files = [];
+  collectProjectFiles(projectDir, projectDir, files);
+  return files.flatMap((file) => collectDesignViolationsForFile(file.relPath, file.content, config));
+}
+
+export function collectSourceDesignViolations(files, config = getCompiledDesignRules()) {
+  return Object.entries(files).flatMap(([relPath, rawContent]) => {
+    const content = Buffer.isBuffer(rawContent)
+      ? rawContent.toString('utf-8')
+      : typeof rawContent === 'string'
+        ? rawContent
+        : String(rawContent ?? '');
+    return collectDesignViolationsForFile(relPath, content, config);
+  });
+}
+
+export function formatDesignViolation(violation) {
+  const prefix = violation.allowed ? 'allowed' : violation.severity;
+  const suffix = violation.allowed ? ` (${violation.reason})` : '';
+  return `${violation.file}:${violation.line} [${violation.ruleId}] ${prefix}: ${violation.message}${suffix}`;
+}
+
+/**
+ * Enforce the design rules on an app's source tree.
+ *
+ * Returns every violation (allowed ones included) so callers can print
+ * warnings. When `enforce` is true (build, verify, screenshot, deploy) any
+ * unallowed error-severity violation aborts with a usage error that lists the
+ * exact file and line to fix. Dev servers pass `enforce: false` so a
+ * half-edited page still reloads.
+ */
+export function validateProjectDesign(projectDir, { enforce = true, log = null } = {}) {
+  const violations = collectProjectDesignViolations(projectDir);
+  const blocking = violations.filter((violation) => !violation.allowed && violation.severity === 'error');
+  const nonBlocking = violations.filter((violation) => !blocking.includes(violation));
+  if (typeof log === 'function') {
+    for (const violation of nonBlocking) log(`[design] ${formatDesignViolation(violation)}`);
+    if (!enforce) for (const violation of blocking) log(`[design] ${formatDesignViolation(violation)}`);
+  }
+  if (enforce && blocking.length > 0) {
+    throw usageError(
+      `Project violates the Notis app design bar (${blocking.length} issue${blocking.length === 1 ? '' : 's'}). `
+      + 'Fix each line below; the only override is an inline "// notis-design-allow: <rule-id> <reason>" comment on the line before.\n'
+      + blocking.map((violation) => `  - ${formatDesignViolation(violation)}`).join('\n'),
+    );
+  }
+  return violations;
+}