qualia-framework 4.4.0 → 5.1.0

package/skills/qualia-polish-loop/scripts/playwright-capture.mjs

@@ -0,0 +1,197 @@
+#!/usr/bin/env node
+/**
+ * playwright-capture.mjs — screenshot capture for the visual-polish loop.
+ *
+ * Prefers Playwright when the package is import-resolvable (project has it as a
+ * dep, or the user ran `npm i -g playwright`). Falls back to driving a cached
+ * Chromium / Google Chrome binary directly via `--headless=new --screenshot`.
+ * Either path produces equivalent PNG output for the vision evaluator.
+ *
+ * Usage:
+ *   node playwright-capture.mjs --url http://localhost:3000 --out /tmp/qpl-1
+ *   node playwright-capture.mjs --url http://localhost:3000 --viewports 375,768,1440 --out /tmp/qpl-1 --wait 1500
+ *
+ * Output (one PNG per viewport, in --out):
+ *   mobile-375.png  tablet-768.png  desktop-1440.png
+ *
+ * Stdout: a JSON envelope with per-capture status. Exit 0 on full success,
+ * 1 if any viewport failed, 2 on invocation error.
+ */
+
+import { existsSync, mkdirSync, statSync, readdirSync } from "node:fs";
+import { join } from "node:path";
+import { spawnSync } from "node:child_process";
+import { argv, exit } from "node:process";
+import { homedir } from "node:os";
+
+// ── Arg parsing ──────────────────────────────────────────────────────────
+function parseArgs() {
+  const args = { url: null, out: null, viewports: [375, 768, 1440], wait: 1500 };
+  for (let i = 2; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === "--url" && argv[i + 1]) args.url = argv[++i];
+    else if (a === "--out" && argv[i + 1]) args.out = argv[++i];
+    else if (a === "--viewports" && argv[i + 1]) {
+      args.viewports = argv[++i].split(",").map((s) => parseInt(s, 10)).filter((n) => Number.isFinite(n) && n > 0);
+    } else if (a === "--wait" && argv[i + 1]) args.wait = parseInt(argv[++i], 10);
+    else if (a === "--help" || a === "-h") {
+      console.log(`playwright-capture.mjs — Screenshot capture for /qualia-polish-loop
+
+Usage:
+  node playwright-capture.mjs --url <url> --out <dir> [--viewports 375,768,1440] [--wait 1500]
+
+Backend selection (auto):
+  1. Playwright   — import('playwright') if installed
+  2. Chromium     — ~/.cache/ms-playwright/chromium-*/chrome-linux64/chrome
+  3. Google Chrome — google-chrome on PATH
+  4. Chromium     — chromium on PATH`);
+      exit(0);
+    }
+  }
+  if (!args.url) { console.error("--url is required"); exit(2); }
+  if (!args.out) { console.error("--out is required"); exit(2); }
+  return args;
+}
+
+// ── Viewport name mapping ────────────────────────────────────────────────
+function viewportName(width) {
+  if (width <= 480) return "mobile";
+  if (width <= 900) return "tablet";
+  return "desktop";
+}
+function viewportHeight(width) {
+  if (width <= 480) return 812;
+  if (width <= 900) return 1024;
+  return 900;
+}
+
+// ── Backend: Playwright (preferred when available) ──────────────────────
+async function captureViaPlaywright(args) {
+  let chromium;
+  try {
+    ({ chromium } = await import("playwright"));
+  } catch {
+    try { ({ chromium } = await import("playwright-core")); } catch { return null; }
+  }
+  const results = [];
+  let browser = null;
+  try {
+    browser = await chromium.launch({ headless: true });
+    for (const width of args.viewports) {
+      const name = viewportName(width);
+      const height = viewportHeight(width);
+      const file = join(args.out, `${name}-${width}.png`);
+      try {
+        const ctx = await browser.newContext({ viewport: { width, height }, deviceScaleFactor: 1 });
+        const page = await ctx.newPage();
+        await page.goto(args.url, { waitUntil: "networkidle", timeout: 30000 });
+        if (args.wait > 0) await page.waitForTimeout(args.wait);
+        await page.screenshot({ path: file, fullPage: false });
+        await ctx.close();
+        results.push({ viewport: name, width, height, file, ok: true, backend: "playwright" });
+      } catch (err) {
+        results.push({ viewport: name, width, height, file, ok: false, backend: "playwright", error: err.message });
+      }
+    }
+  } finally {
+    if (browser) await browser.close();
+  }
+  return results;
+}
+
+// ── Backend: Chrome/Chromium headless via spawn ─────────────────────────
+function findChromeBinary() {
+  // 1. Playwright cached chromium (newest first)
+  try {
+    const pwCache = join(homedir(), ".cache", "ms-playwright");
+    if (existsSync(pwCache)) {
+      const dirs = readdirSync(pwCache)
+        .filter((d) => d.startsWith("chromium-"))
+        .sort((a, b) => parseInt(b.split("-")[1], 10) - parseInt(a.split("-")[1], 10));
+      for (const d of dirs) {
+        for (const sub of ["chrome-linux64/chrome", "chrome-linux/chrome", "chrome-mac/Chromium.app/Contents/MacOS/Chromium", "chrome-win/chrome.exe"]) {
+          const p = join(pwCache, d, sub);
+          if (existsSync(p)) return p;
+        }
+      }
+    }
+  } catch {}
+
+  // 2. PATH lookups
+  for (const cmd of ["google-chrome", "chromium", "chromium-browser", "chrome"]) {
+    const r = spawnSync("which", [cmd], { encoding: "utf8" });
+    if (r.status === 0 && r.stdout) return r.stdout.trim();
+  }
+  return null;
+}
+
+function captureViaChromeBinary(args, binary) {
+  const results = [];
+  for (const width of args.viewports) {
+    const name = viewportName(width);
+    const height = viewportHeight(width);
+    const file = join(args.out, `${name}-${width}.png`);
+    const flags = [
+      "--headless=new",
+      "--no-sandbox",
+      "--disable-gpu",
+      "--disable-dev-shm-usage",
+      "--hide-scrollbars",
+      `--window-size=${width},${height}`,
+      `--screenshot=${file}`,
+      `--virtual-time-budget=${Math.max(args.wait + 1000, 3000)}`,
+      args.url,
+    ];
+    const r = spawnSync(binary, flags, { encoding: "utf8", timeout: 30000 });
+    let ok = r.status === 0 && existsSync(file);
+    let size = 0;
+    if (ok) {
+      try { size = statSync(file).size; } catch { ok = false; }
+      if (size < 100) ok = false; // empty/zero PNG → treat as failure
+    }
+    results.push({
+      viewport: name, width, height, file, ok,
+      backend: "chrome-binary", binary,
+      ...(ok ? {} : { error: r.stderr ? r.stderr.split("\n").slice(0, 3).join(" / ") : `exit ${r.status}` }),
+    });
+  }
+  return results;
+}
+
+// ── Main ─────────────────────────────────────────────────────────────────
+async function main() {
+  const args = parseArgs();
+  if (!existsSync(args.out)) mkdirSync(args.out, { recursive: true });
+
+  let captures = await captureViaPlaywright(args);
+  let backendUsed = "playwright";
+  if (captures === null) {
+    const bin = findChromeBinary();
+    if (!bin) {
+      console.error(JSON.stringify({
+        ok: false,
+        error: "no_browser_backend",
+        hint: "Install Playwright (`npm i playwright && npx playwright install chromium`) or ensure google-chrome / chromium is on PATH.",
+      }, null, 2));
+      exit(2);
+    }
+    captures = captureViaChromeBinary(args, bin);
+    backendUsed = "chrome-binary";
+  }
+
+  const failed = captures.filter((c) => !c.ok).length;
+  console.log(JSON.stringify({
+    url: args.url,
+    output_dir: args.out,
+    backend: backendUsed,
+    captures,
+    total: captures.length,
+    failed,
+  }, null, 2));
+  exit(failed > 0 ? 1 : 0);
+}
+
+main().catch((e) => {
+  console.error(JSON.stringify({ ok: false, error: e.message, stack: e.stack }, null, 2));
+  exit(2);
+});

package/skills/qualia-polish-loop/scripts/score.mjs

@@ -0,0 +1,176 @@
+#!/usr/bin/env node
+/**
+ * score.mjs -- Qualia visual-polish loop scoring utility.
+ *
+ * Takes a JSON object with 8 dimension scores and computes pass/fail
+ * per the design rubric formula from rules/design-rubric.md.
+ *
+ * Usage:
+ *   echo '{"typography":3,"color":2,"spatial":3,"layout":3,"shadow":3,"motion":3,"microcopy":3,"container":3}' | node score.mjs
+ *   node score.mjs --file scores.json
+ *   node score.mjs --scores '{"typography":4,"color":3,...}'
+ *
+ * Output (JSON):
+ *   { total, avg, pass, failing: [{dim, score}], verdict }
+ *
+ * Exit codes:
+ *   0  all dimensions >= 3 (pass)
+ *   1  one or more dimensions < 3 (fail)
+ *   2  invocation error
+ */
+
+import { readFileSync } from "node:fs";
+import { argv, stdin, exit } from "node:process";
+
+const DIMENSIONS = [
+  "typography",
+  "color",
+  "spatial",
+  "layout",
+  "shadow",
+  "motion",
+  "microcopy",
+  "container",
+];
+
+const DIMENSION_ALIASES = {
+  "color cohesion": "color",
+  "color_cohesion": "color",
+  "spatial rhythm": "spatial",
+  "spatial_rhythm": "spatial",
+  "layout originality": "layout",
+  "layout_originality": "layout",
+  "shadow & depth": "shadow",
+  "shadow_depth": "shadow",
+  "shadow & depth hierarchy": "shadow",
+  "motion intent": "motion",
+  "motion_intent": "motion",
+  "microcopy specificity": "microcopy",
+  "microcopy_specificity": "microcopy",
+  "container depth": "container",
+  "container_depth": "container",
+  "container depth & nesting": "container",
+};
+
+function normalizeKey(key) {
+  const lower = key.toLowerCase().trim();
+  return DIMENSION_ALIASES[lower] || lower;
+}
+
+function parseScores(raw) {
+  if (typeof raw === "string") {
+    try {
+      raw = JSON.parse(raw);
+    } catch (e) {
+      console.error(`Invalid JSON: ${e.message}`);
+      exit(2);
+    }
+  }
+
+  const scores = {};
+  for (const [key, value] of Object.entries(raw)) {
+    const normalized = normalizeKey(key);
+    if (DIMENSIONS.includes(normalized)) {
+      const num = parseInt(value, 10);
+      if (num < 1 || num > 5 || isNaN(num)) {
+        console.error(`Invalid score for ${key}: ${value} (must be 1-5)`);
+        exit(2);
+      }
+      scores[normalized] = num;
+    }
+  }
+
+  // Validate all dimensions present
+  const missing = DIMENSIONS.filter((d) => !(d in scores));
+  if (missing.length > 0) {
+    console.error(`Missing dimensions: ${missing.join(", ")}`);
+    exit(2);
+  }
+
+  return scores;
+}
+
+function computeResult(scores) {
+  const dims = DIMENSIONS.map((d) => scores[d]);
+  const total = dims.reduce((a, b) => a + b, 0);
+  const avg = +(total / dims.length).toFixed(2);
+  const failing = DIMENSIONS.filter((d) => scores[d] < 3).map((d) => ({
+    dim: d,
+    score: scores[d],
+  }));
+  const pass = failing.length === 0;
+
+  let verdict;
+  if (pass) {
+    verdict = "SUCCESS";
+  } else if (failing.some((f) => f.score === 1)) {
+    verdict = "CRITICAL_FAIL";
+  } else {
+    verdict = "FAIL";
+  }
+
+  return {
+    scores,
+    total,
+    max: 40,
+    avg,
+    pass,
+    failing,
+    verdict,
+  };
+}
+
+// -- CLI entry point --
+
+async function main() {
+  let input = null;
+
+  // Parse args
+  for (let i = 2; i < argv.length; i++) {
+    if (argv[i] === "--file" && argv[i + 1]) {
+      try {
+        input = readFileSync(argv[i + 1], "utf8");
+      } catch (e) {
+        console.error(`Cannot read file: ${e.message}`);
+        exit(2);
+      }
+      i++;
+    } else if (argv[i] === "--scores" && argv[i + 1]) {
+      input = argv[i + 1];
+      i++;
+    } else if (argv[i] === "--help" || argv[i] === "-h") {
+      console.log(`score.mjs -- Qualia visual-polish loop scoring utility
+
+Usage:
+  echo '{"typography":3,...}' | node score.mjs
+  node score.mjs --file scores.json
+  node score.mjs --scores '{"typography":4,...}'
+
+Dimensions: ${DIMENSIONS.join(", ")}
+Each scored 1-5. All must be >= 3 to pass.`);
+      exit(0);
+    }
+  }
+
+  // Read from stdin if no explicit input
+  if (!input) {
+    const chunks = [];
+    for await (const chunk of stdin) {
+      chunks.push(chunk);
+    }
+    input = Buffer.concat(chunks).toString("utf8").trim();
+  }
+
+  if (!input) {
+    console.error("No input provided. Use --file, --scores, or pipe JSON to stdin.");
+    exit(2);
+  }
+
+  const scores = parseScores(input);
+  const result = computeResult(scores);
+
+  console.log(JSON.stringify(result, null, 2));
+  exit(result.pass ? 0 : 1);
+}
+
+main();