← Files AICtrlARCHIVED FILE

skills/ux-testing/scripts/server.cjs

22.5 KB · Nov 21, 2026 · 12:23 UTC

↓ Download file

See the change to this file →

// UX usability harness: one Playwright browser context per tester session, driven over local HTTP.
// Testers only see the page's accessibility tree (ariaSnapshot) and act by visible name, so the
// harness doubles as an accessible-name check.
//
// Run:   UX_TARGET=<file-or-url> node server.cjs      (needs Playwright with Chromium; see SKILL.md)
// Env:
//   UX_TARGET        file path or URL to open (required)
//   UX_PORT          harness port (default 3917). Clients must use the same UX_PORT.
//   UX_OUT           output directory for actions.jsonl and screenshots (default: a new temp dir outside
//                    the repository; the path is printed at start-up)
//   UX_VIEWPORT      default viewport as WIDTHxHEIGHT (default 1440x900); "open --viewport" overrides it
//   UX_HIDE_CSS      CSS injected on open to hide prototype chrome users would not see,
//                    e.g. '.dev-toolbar,.design-notes{display:none!important}'
//   UX_SCENARIO_SEL  selector of a <select> that jumps a prototype to a named state on "open <scenario>"
//   UX_SETUP         path to a .cjs module exporting async (page, context) => {} run after navigation
//                    (e.g. sign in to a test account)
//   UX_STORAGE_STATE Playwright storageState JSON for an already signed-in context
//   UX_VERIFY_TOKEN  optional verify token of your choice (>= 32 chars); when set it is not printed
//
// Access control: every request needs the per-run token that the server writes to
// $TMPDIR/ux-harness-<uid>/<port>.token, inside a directory only this user can open (0700); ux.cjs
// reads it. The verify-only "eval" action needs a second token that the harness never writes to disk: set it
// yourself as UX_VERIFY_TOKEN (>= 32 chars) in the server's environment, or the server generates one and prints
// it once (then any captured stdout holds a copy). Pass the same value to verify.cjs as UX_VERIFY_TOKEN.
// Operator-only actions need the verify token too: eval, close, errors, open with a scenario or viewport, and
// re-opening a live session id. Both tokens keep tester agents, which are only given ux.cjs, to the tester commands; they are not a defence
// against other processes running as your user. Requests carrying an Origin or Referer header (i.e. sent by a
// browser) and requests for another Host are rejected.
// Typed text is never written to the log (testers may type credentials).
const crypto = require('crypto');
const fs = require('fs');
const http = require('http');
const os = require('os');
const path = require('path');
const { loadPlaywright, tokenFile, resolveTarget: resolve, namedFields } = require('./common.cjs');

const { chromium } = loadPlaywright();
const PORT = Number(process.env.UX_PORT || 3917);
const TARGET = process.env.UX_TARGET;
if (!TARGET) {
  console.error('UX_TARGET is required (file path or URL)');
  process.exit(1);
}
const TARGET_URL = /^https?:\/\//.test(TARGET) ? TARGET : 'file://' + path.resolve(TARGET);
const OUT = process.env.UX_OUT || fs.mkdtempSync(path.join(os.tmpdir(), 'ux-run-'));
const LOG = path.join(OUT, 'actions.jsonl');
const SHOTS = path.join(OUT, 'shots');
const SETUP = process.env.UX_SETUP ? require(path.resolve(process.env.UX_SETUP)) : null;
const MAX_BODY = 1024 * 1024;
const ACTION_TIMEOUT_MS = 4000;
fs.mkdirSync(SHOTS, { recursive: true });

const MAX_SESSIONS = 32;
const uid = typeof process.getuid === 'function' ? process.getuid() : null;
// A private, per-user directory: a fixed name in the shared tmpdir could be pre-planted as a symlink.
const TOKEN_FILE = tokenFile(PORT);
const TOKEN_DIR = path.dirname(TOKEN_FILE);
fs.mkdirSync(TOKEN_DIR, { recursive: true, mode: 0o700 });
const dirStat = fs.lstatSync(TOKEN_DIR);
if (!dirStat.isDirectory() || dirStat.isSymbolicLink() || (uid !== null && dirStat.uid !== uid) || (dirStat.mode & 0o077) !== 0) {
  console.error(`ERROR: ${TOKEN_DIR} must be a directory owned by you with mode 0700. Remove it and start again.`);
  process.exit(1);
}
const TOKEN = crypto.randomBytes(24).toString('hex');
// The operator may choose the verify token (UX_VERIFY_TOKEN in the server's environment), so it is never printed.
// Otherwise one is generated and printed once; anything that captures the server's stdout then holds a copy.
const VERIFY_TOKEN_GIVEN = Boolean(process.env.UX_VERIFY_TOKEN);
if (VERIFY_TOKEN_GIVEN && process.env.UX_VERIFY_TOKEN.length < 32) {
  console.error('UX_VERIFY_TOKEN must be at least 32 characters (e.g. 24 random bytes as hex).');
  process.exit(1);
}
const VERIFY_TOKEN = VERIFY_TOKEN_GIVEN ? process.env.UX_VERIFY_TOKEN : crypto.randomBytes(24).toString('hex');

// Constant-time comparison without leaking the length: compare fixed-size digests.
function tokenMatches(given, expected) {
  const a = crypto.createHash('sha256').update(String(given || '')).digest();
  const b = crypto.createHash('sha256').update(expected).digest();
  return crypto.timingSafeEqual(a, b);
}

function validViewport(v) {
  if (!v) return null;
  const ok = (n) => Number.isInteger(n) && n >= 320 && n <= 3840;
  if (!ok(v.width) || !ok(v.height)) throw new Error('viewport must be WIDTHxHEIGHT between 320 and 3840');
  return { width: v.width, height: v.height };
}

let DEFAULT_VIEWPORT = { width: 1440, height: 900 };
if (process.env.UX_VIEWPORT) {
  const m = /^(\d+)x(\d+)$/.exec(process.env.UX_VIEWPORT);
  try {
    if (!m) throw new Error();
    DEFAULT_VIEWPORT = validViewport({ width: Number(m[1]), height: Number(m[2]) });
  } catch {
    console.error('UX_VIEWPORT must be WIDTHxHEIGHT between 320 and 3840, e.g. 1366x768');
    process.exit(1);
  }
}

let browser;
const sessions = new Map(); // live sessions only: an entry is removed when its browser context closes
let opening = 0; // new session ids whose open is in flight, counted against MAX_SESSIONS

async function open(id, scenario, viewport) {
  if (scenario && !process.env.UX_SCENARIO_SEL) throw new Error(`scenario "${scenario}" given but UX_SCENARIO_SEL is not configured`);
  const vp = validViewport(viewport) || DEFAULT_VIEWPORT;
  // Reserve the slot synchronously, so concurrent opens of new ids cannot pass the check together.
  const isNew = !sessions.has(id);
  if (isNew && sessions.size + opening >= MAX_SESSIONS) throw new Error(`too many open sessions (${MAX_SESSIONS}); close finished sessions ("close") or restart the harness between batches`);
  if (isNew) opening++;
  let ctx;
  try {
    ctx = await browser.newContext({
      viewport: vp,
      ...(process.env.UX_STORAGE_STATE ? { storageState: process.env.UX_STORAGE_STATE } : {}),
    });
  } catch (e) {
    if (isNew) opening--;
    throw e;
  }
  ctx.setDefaultTimeout(ACTION_TIMEOUT_MS);
  const errors = [];
  let page;
  try {
    page = await ctx.newPage();
    page.on('pageerror', (e) => errors.push(e.message));
    await page.goto(TARGET_URL, { timeout: 30000 });
    if (SETUP) await SETUP(page, ctx);
    if (scenario) await page.selectOption(process.env.UX_SCENARIO_SEL, scenario);
    if (process.env.UX_HIDE_CSS) await page.addStyleTag({ content: process.env.UX_HIDE_CSS });
    await page.waitForTimeout(500);
  } catch (e) {
    if (isNew) opening--;
    await ctx.close().catch(() => {});
    throw e;
  }
  if (isNew) opening--;
  // Swap only after the new session is fully ready, then close the old one. The get and set run in
  // one synchronous step, so of two overlapping opens the later one always closes the earlier one.
  const previous = sessions.get(id);
  const entry = { ctx, page, errors };
  sessions.set(id, entry);
  // Free the slot when this context goes away (closed, replaced, or the browser crashed).
  ctx.on('close', () => { if (sessions.get(id) === entry) sessions.delete(id); });
  if (previous) await previous.ctx.close().catch(() => {});
  return 'Opened the app. Use "snapshot" to see the page.';
}

// What was actually clicked, so the tester and the log both see it.
async function nameOf(loc) {
  return loc
    .evaluate((el) => (el.getAttribute('aria-label') || (el.labels && el.labels[0] ? el.labels[0].innerText : '') || el.innerText || el.textContent || '').trim().replace(/\s+/g, ' ').slice(0, 120))
    .catch(() => '');
}

async function snapshot(page) {
  let snap = await page.locator('body').ariaSnapshot();
  if (snap.length > 14000) snap = snap.slice(0, 14000) + '\n… (truncated; narrow down by navigating)';
  return snap;
}

const HELP = 'Use snapshot, click, type, select, press, wait, screenshot.';

async function run(s, action, args) {
  const { page } = s;
  switch (action) {
    case 'snapshot':
      return snapshot(page);
    case 'click': {
      const r = await resolve(page, args.join(' '));
      if (!r) return `ERROR: nothing visible matches "${args.join(' ')}". Take a snapshot and use a name you can see.`;
      if (r.error) return r.error;
      await r.loc.scrollIntoViewIfNeeded().catch(() => {});
      const clicked = await nameOf(r.loc);
      await r.loc.click();
      await page.waitForTimeout(800);
      s.lastClicked = clicked;
      return `Clicked "${clicked}".` + r.note;
    }
    case 'select': {
      const [field, ...rest] = args;
      if (!field || rest.length === 0) return 'ERROR: select needs a quoted label and an option, e.g. select "Status" Ready';
      const boxes = page.getByRole('combobox', { name: field }).filter({ visible: true });
      const n = await boxes.count();
      if (!n) return `ERROR: nothing visible matches field "${field}". Take a snapshot and use a label you can see.`;
      await boxes.first().selectOption({ label: rest.join(' ') });
      await page.waitForTimeout(500);
      return 'Selected.' + (n > 1 ? ` (${n} fields named "${field}"; used the first.)` : '');
    }
    case 'type': {
      const words = [...args];
      let field = null;
      let enter = false;
      if (words[0] === '--field') {
        if (!words[1]) return 'ERROR: --field needs a quoted label, e.g. type --field "Title" New title';
        field = words[1];
        words.splice(0, 2);
      }
      if (words[words.length - 1] === '--enter') { enter = true; words.pop(); }
      if (!words.join(' ').trim()) return 'ERROR: type needs text, e.g. type Hello --enter or type --field "Title" New title';
      // Text-entry roles: textbox, searchbox (<input type="search">) and combobox (editable combo). See namedFields.
      // Exact accessible name first, substring only as a fallback (locate()'s ladder): a field named exactly
      // "<label>" must win even when another field's name merely contains the label, so DOM order cannot
      // retarget the text between roles that both substring-match.
      const exactNamed = field ? namedFields(page, field, true) : null;
      const named = !field ? null : ((await exactNamed.count()) ? exactNamed : namedFields(page, field));
      const n = named ? await named.count() : 0;
      if (field && !n) return `ERROR: nothing visible matches field "${field}". Take a snapshot and use a label you can see.`;
      // The chat box is a textarea; only fall back to single-line inputs (e.g. a search field) when there is none.
      // Picking by DOM order breaks when the chat panel sits before the page content.
      const inputs = page.locator('input[type="text"]:visible, input[type="search"]:visible, input:not([type]):visible');
      const box = field
        ? named.first()
        : ((await page.locator('textarea:visible').count()) ? page.locator('textarea:visible').last() : inputs.last());
      if (!field && !(await box.count())) return 'ERROR: there is no visible text box. Use type --field "<label>" with a label you can see.';
      await box.fill(words.join(' '));
      if (enter) { await box.press('Enter'); await page.waitForTimeout(900); }
      return (enter ? 'Typed and sent.' : 'Typed.') + (n > 1 ? ` (${n} fields named "${field}"; used the first.)` : '');
    }
    case 'press':
      if (!args[0]) return 'ERROR: press needs a key, e.g. press Escape';
      await page.keyboard.press(args[0]);
      await page.waitForTimeout(500);
      return 'Pressed.';
    case 'wait': {
      if (args[0] !== undefined && !/^\d+$/.test(args[0])) return 'ERROR: wait needs milliseconds as a number, e.g. wait 3000';
      const ms = args[0] === undefined ? 1000 : Number(args[0]);
      await page.waitForTimeout(Math.min(ms, 8000));
      return 'Waited.';
    }
    case 'screenshot': {
      const f = path.join(SHOTS, `${Date.now()}.png`);
      await page.screenshot({ path: f });
      return f;
    }
    default:
      return `ERROR: unknown action "${action}". ${HELP}`;
  }
}

// Never persist typed text: it can contain credentials entered during sign-in.
// Only actions whose arguments are never secret are logged verbatim; "type" keeps its --enter flag, and its
// --field label only when the command succeeded (the label then matched a visible text-entry field: textbox,
// searchbox or editable combobox, so it is page text; a failed "type --field hunter2" may be a secret typed
// where the label goes). Anything else (an unknown or misspelled action, e.g. "type " or "Type") is fully redacted.
const LOGGED_ARGS = new Set(['snapshot', 'click', 'select', 'press', 'wait', 'screenshot', 'open', 'close', 'errors', 'eval']);
function redactArgs(action, args, ok) {
  if (!Array.isArray(args) || args.length === 0) return args;
  if (typeof action === 'string' && LOGGED_ARGS.has(action)) return args;
  if (typeof action !== 'string' || action.trim().toLowerCase() !== 'type') return ['<redacted>'];
  const out = [];
  const words = [...args];
  if (words[0] === '--field') out.push('--field', ok === true && words[1] ? words[1] : '<redacted>');
  const enter = words[words.length - 1] === '--enter';
  out.push('<redacted>');
  if (enter) out.push('--enter');
  return out;
}

// A logging failure (a full disk, the output directory removed mid-round) must not take down the harness and
// every open session with it: warn on stderr and keep serving.
let logNeedsNewline = false;
// True only if a failed write left the log ending without a newline (a zero-byte failure leaves nothing to repair).
function logEndsMidLine() {
  try {
    const size = fs.statSync(LOG).size; if (!size) return false;
    const fd = fs.openSync(LOG, 'r'); const b = Buffer.alloc(1);
    try { fs.readSync(fd, b, 0, 1, size - 1); } finally { fs.closeSync(fd); }
    return b[0] !== 0x0a;
  } catch { return false; }
}
let logWarned = false;
function logLine(entry) {
  try {
    const safe = { ...entry, args: redactArgs(entry.action, entry.args, entry.ok) };
    // After a failed append the log may end in a partial line; start on a fresh line so it cannot merge with this record.
    fs.appendFileSync(LOG, (logNeedsNewline ? '\n' : '') + JSON.stringify({ t: Date.now(), ...safe }) + '\n');
    logWarned = false;
    logNeedsNewline = false;
  } catch (e) {
    logNeedsNewline = logEndsMidLine();
    if (!logWarned) console.error(`WARNING: could not write the action log ${LOG} (${e.code || e.message}); actions are not being recorded, but the harness keeps serving.`);
    logWarned = true;
  }
}

function reply(res, status, text) {
  try {
    res.statusCode = status;
    res.end(String(text));
  } catch { /* client went away */ }
}

(async () => {
  try {
    browser = await chromium.launch();
  } catch (e) {
    console.error(`ERROR: could not start Chromium (${String(e.message).split('\n')[0]}). Run \`npx playwright install chromium\`.`);
    process.exit(3);
  }
  const server = http.createServer((req, res) => {
    // CLI clients consume literal text, including page labels and exception messages.
    // Declare it before any auth/body checks so every response has the same MIME boundary.
    res.setHeader('Content-Type', 'text/plain; charset=utf-8');
    res.setHeader('X-Content-Type-Options', 'nosniff');
    req.on('error', () => {}); // a client reset must not take down the harness
    const host = String(req.headers.host || '');
    if (req.headers.origin || req.headers.referer || (host !== `127.0.0.1:${PORT}` && host !== `localhost:${PORT}`)) {
      reply(res, 403, 'ERROR: forbidden');
      req.resume();
      return;
    }
    if (!tokenMatches(req.headers['x-ux-token'], TOKEN)) {
      reply(res, 401, 'ERROR: missing or wrong harness token (run the client from the same machine as the server)');
      req.resume();
      return;
    }
    let body = '';
    let tooLarge = false;
    req.on('data', (c) => {
      if (tooLarge) return;
      body += c;
      if (body.length > MAX_BODY) {
        tooLarge = true;
        res.statusCode = 413;
        res.setHeader('Connection', 'close');
        res.end('ERROR: request too large', () => req.destroy()); // destroy only after the reply is flushed
      }
    });
    req.on('end', async () => {
      if (tooLarge) return;
      let out;
      let parsed = {};
      try {
        parsed = JSON.parse(body || '{}');
        if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) { parsed = {}; throw new Error('request must be a JSON object'); }
        const { session, action, args = [], scenario, expr, viewport } = parsed;
        // Operator-only actions (eval, close, errors, open with a scenario or viewport, re-opening a live session)
        // need the verify token, which tester agents never get; they share only the harness token.
        const operator = tokenMatches(req.headers['x-ux-verify-token'], VERIFY_TOKEN);
        const needOperator = (what) => { if (!operator) throw new Error(`${what} is operator-only (needs UX_VERIFY_TOKEN)`); };
        if (typeof session !== 'string' || !/^[\w.-]{1,64}$/.test(session)) throw new Error('session must be 1-64 letters, digits, "_", "-" or "."');
        if (!Array.isArray(args) || args.some((a) => typeof a !== 'string')) throw new Error('args must be a list of strings');
        if (scenario !== undefined && typeof scenario !== 'string') throw new Error('scenario must be a string');
        if (expr !== undefined && typeof expr !== 'string') throw new Error('expr must be a string');
        if (typeof action !== 'string') throw new Error('action must be a string');
        const extra = {};
        if (action === 'open') {
          if (scenario || viewport) needOperator('open with a scenario or viewport');
          if (sessions.has(session) && !operator) throw new Error(`session "${session}" is already open: use snapshot, or pick a new session id`);
          if (scenario) extra.scenario = scenario;
          if (viewport) extra.viewport = viewport;
          out = await open(session, scenario, viewport);
        } else if (action === 'eval') {
          // Verification only: needs the separate verify token, never given to testers.
          if (!operator) throw new Error('forbidden');
          const s = sessions.get(session);
          if (!s) throw new Error(`No session "${session}"`);
          if (!expr) throw new Error('eval needs an expression');
          const value = await s.page.evaluate(expr);
          // A check that returns nothing asserted nothing; never let it read as a pass.
          if (value === undefined) throw new Error('the check returned undefined; make the expression return a value');
          out = JSON.stringify(value);
          // Log the check and a true/false/number/null result; a richer value can hold page secrets (cookies,
          // storage, typed input), so only its type and size are logged. verify.cjs still prints the full value.
          extra.expr = expr.slice(0, 500);
          extra.result = value === null || ['boolean', 'number'].includes(typeof value)
            ? out
            : `<${Array.isArray(value) ? 'array' : typeof value} of ${String(out).length} chars, not logged>`;
        } else if (action === 'close') {
          // Operator: close a finished session and free its slot.
          needOperator('close');
          const s = sessions.get(session);
          if (!s) throw new Error(`No session "${session}"`);
          sessions.delete(session);
          await s.ctx.close().catch(() => {});
          out = 'Closed.';
        } else if (action === 'errors') {
          needOperator('errors');
          const s = sessions.get(session);
          if (!s) throw new Error(`No session "${session}"`);
          out = JSON.stringify(s.errors);
        } else {
          const s = sessions.get(session);
          if (!s) throw new Error('No session. Run "open" first.');
          s.lastClicked = undefined;
          out = await run(s, action, args);
          if (s.lastClicked !== undefined) parsed.clicked = s.lastClicked;
        }
        logLine({ session, action, args, ok: !String(out).startsWith('ERROR'), ...extra, ...(parsed.clicked !== undefined ? { clicked: parsed.clicked } : {}) });
      } catch (e) {
        out = 'ERROR: ' + String(e.message).split('\n')[0];
        // Keep the keys even for a malformed request, so every row can be attributed.
        const str = (v, dflt) => (typeof v === 'string' ? v.slice(0, 64) : dflt);
        logLine({ session: str(parsed.session, '(malformed)'), action: str(parsed.action, '(unknown)'), args: Array.isArray(parsed.args) ? parsed.args : [], ok: false, error: out });
      }
      reply(res, 200, out);
    });
  });
  server.on('clientError', (err, socket) => {
    try {
      socket.end('HTTP/1.1 400 Bad Request\r\nContent-Type: text/plain; charset=utf-8\r\nX-Content-Type-Options: nosniff\r\nConnection: close\r\nContent-Length: 0\r\n\r\n');
    } catch { /* ignore */ }
  });
  // A failed bind (e.g. a harness already on this port) exits without touching that harness's token file.
  server.on('error', (e) => {
    console.error('ERROR: ' + e.message);
    process.exit(1);
  });
  server.listen(PORT, '127.0.0.1', () => {
    // Never follow a link planted at the token path: remove any stale file we own, then create exclusively.
    try {
      const st = fs.lstatSync(TOKEN_FILE);
      if (!st.isFile() || (uid !== null && st.uid !== uid)) {
        console.error(`ERROR: ${TOKEN_FILE} exists and is not a regular file you own. Remove it and start again.`);
        process.exit(1);
      }
      fs.unlinkSync(TOKEN_FILE); // left by a harness that was killed before it could clean up
    } catch (e) {
      if (e.code !== 'ENOENT') throw e;
    }
    const fd = fs.openSync(TOKEN_FILE, fs.constants.O_WRONLY | fs.constants.O_CREAT | fs.constants.O_EXCL | (fs.constants.O_NOFOLLOW || 0), 0o600);
    fs.writeSync(fd, TOKEN);
    fs.closeSync(fd);
    process.on('exit', () => {
      try { fs.unlinkSync(TOKEN_FILE); } catch { /* already gone */ }
    });
    for (const sig of ['SIGINT', 'SIGTERM']) process.on(sig, () => process.exit(0));
    console.log(`ux harness on ${PORT} → ${TARGET_URL}\noutput: ${OUT}`);
    if (VERIFY_TOKEN_GIVEN) console.log('verify token: the UX_VERIFY_TOKEN you set (not printed)');
    else console.log(`verify token (operator only; pass to verify.cjs as UX_VERIFY_TOKEN, never to testers; set UX_VERIFY_TOKEN yourself to keep it out of captured output): ${VERIFY_TOKEN}`);
  });
})();

SHA-256: 215f43c3b5fcac8e3f9c8f583eff388d27b731cdd814ef421da93bbd569cbff3