Redesign an existing website to make it better. Built on top of impeccable.
88%
Does it follow best practices?
Run evals on this skill
Adds up to 20 points to the overall score
Low
Low-risk findings worth noting
/**
* qa/lib.mjs — shared helpers for the stardust:qa read-only checkers.
*
* Everything here is side-effect-free except writeJSON/ensureDir, which only
* ever target the QA output directory. No module in this skill mutates site
* content, DA documents, or repo code.
*/
import { readFileSync, writeFileSync, mkdirSync, existsSync } from 'node:fs';
import { join, dirname } from 'node:path';
import { fileURLToPath } from 'node:url';
// The shared rules (contracts.mjs) live beside browser.mjs in the master skill's scripts dir — the plugin tree or the
// Setup step 7 copy — resolved here once and re-exported, so the checks keep importing them from ../lib.mjs.
const CONTRACTS = ['../../stardust/scripts/contracts.mjs', '../stardust/contracts.mjs']
.map((p) => new URL(p, import.meta.url)).find((u) => existsSync(u));
if (!CONTRACTS) throw new Error('qa/lib.mjs: contracts.mjs not found (looked in ../../stardust/scripts/ and ../stardust/). Copy the master skill\'s scripts dir to stardust/scripts/stardust/ (skills/stardust/SKILL.md § Setup).');
const C = await import(CONTRACTS.href);
const { QA_CHROME_PATHS } = C;
export const { listingKey, listingUrl, deliveredUrl, pathKey, isMetaBlock, widgetLinks, AI_EXCLUDE_DEFAULT, loadSibling } = C;
export function arg(name, fallback = null) {
const i = process.argv.indexOf(`--${name}`);
return i !== -1 && process.argv[i + 1] !== undefined ? process.argv[i + 1] : fallback;
}
export function flag(name) { return process.argv.includes(`--${name}`); }
export const STARDUST_VERSION = (() => {
try {
const here = dirname(fileURLToPath(import.meta.url));
const pj = JSON.parse(readFileSync(join(here, '..', '..', '..', '.claude-plugin', 'plugin.json'), 'utf8'));
return pj.version || '0.0.0';
} catch { return '0.0.0'; }
})();
export function provenance(script, input) {
return {
writtenBy: `stardust:qa/${script}`,
stardustVersion: STARDUST_VERSION,
writtenAt: new Date().toISOString(),
againstInput: input,
};
}
export function ensureDir(dir) { mkdirSync(dir, { recursive: true }); }
export function readJSON(file, fallback = undefined) {
try { return JSON.parse(readFileSync(file, 'utf8')); } catch { return fallback; }
}
export function writeJSON(file, obj) {
ensureDir(dirname(file));
writeFileSync(file, `${JSON.stringify(obj, null, 2)}\n`);
}
/* ---------------------------------------------------------------- fetch -- */
const UA = 'stardust-qa/1.0 (+read-only site QA)';
/**
* Fetch a URL with timeout + one retry. redirect: 'manual' callers get the
* Location back instead of the followed body.
*/
/* ---------------------------------------------------------- site auth -- */
// Protected origins (access allow-list + site secret) 401 every unauthenticated
// probe. The header is sent to the BASE origin only — never to third parties,
// whose CORS checks would turn a credentialed request into a false failure.
let ORIGIN_AUTH = null;
export function setOriginAuth(base, headerValue) { ORIGIN_AUTH = base && headerValue ? { origin: new URL(base).origin, value: headerValue } : null; }
export function originAuthFor(url) {
if (!ORIGIN_AUTH || ORIGIN_AUTH.origin === 'null') return null;
try { return new URL(url).origin === ORIGIN_AUTH.origin ? ORIGIN_AUTH.value : null; } catch { return null; }
}
/** browser side: attach the auth header to base-origin requests of a Playwright context (route filter, never extraHTTPHeaders) */
export async function attachOriginAuth(context) {
if (!ORIGIN_AUTH || ORIGIN_AUTH.origin === 'null') return;
const { attachOriginAuth: attach } = await frontDoor();
await attach(context, ORIGIN_AUTH.origin, ORIGIN_AUTH.value);
}
/** `--auth-header "token …"` or `--token-env NAME` (process.env, then a cwd `.env`); default env name SITE_TOKEN */
export function resolveAuthHeader() {
const direct = arg('auth-header'); if (direct) return direct;
const name = arg('token-env') || 'SITE_TOKEN';
let v = process.env[name];
if (!v && existsSync('.env')) v = (readFileSync('.env', 'utf8').match(new RegExp(`^${name}=(.*)$`, 'm')) || [])[1];
if (!v) return null;
v = v.trim().replace(/^["']|["']$/g, '');
return /^(token|bearer) /i.test(v) ? v : `token ${v}`;
}
export async function fetchUrl(url, { redirect = 'follow', method = 'GET', timeoutMs = 20000, retries = 1, binary = false } = {}) {
for (let attempt = 0; ; attempt += 1) {
const ctl = new AbortController();
const timer = setTimeout(() => ctl.abort(), timeoutMs);
try {
const auth = originAuthFor(url);
const res = await fetch(url, { method, redirect, signal: ctl.signal, headers: { 'user-agent': UA, ...(auth ? { authorization: auth } : {}) } });
const bytes = binary && method !== 'HEAD' ? Buffer.from(await res.arrayBuffer()) : undefined;
const body = method === 'HEAD' || binary ? '' : await res.text();
clearTimeout(timer);
return {
ok: res.ok,
...(bytes ? { bytes } : {}),
status: res.status,
headers: Object.fromEntries(res.headers.entries()),
location: res.headers.get('location'),
url: res.url,
body,
};
} catch (e) {
clearTimeout(timer);
if (attempt >= retries) return { ok: false, status: 0, headers: {}, location: null, url, body: '', error: e.message };
await new Promise((r) => setTimeout(r, 1000 * (attempt + 1)));
}
}
}
/**
* Shared page-fetch cache for one sweep: routing, content, metadata, and links
* each visit every page, so without this a fleet is fetched ~3× (full HTML)
* plus 2× (.plain.html). Only plain GET+follow requests are cached (probes —
* HEAD, redirect:'manual' — have distinct semantics and bypass it); network
* failures (status 0) are not cached so a transient error can't poison later
* checks. Stores in-flight promises, so concurrent callers share one request.
*/
export function createPageCache(maxEntries = 4096) {
const cache = new Map(); // url -> Promise<fetchUrl result>
const cachedFetch = (url, opts = {}) => {
const cacheable = (!opts.method || opts.method === 'GET')
&& (!opts.redirect || opts.redirect === 'follow');
if (!cacheable) return fetchUrl(url, opts);
if (cache.has(url)) return cache.get(url);
const p = fetchUrl(url, opts).then((res) => {
if (res.status === 0 || cache.size > maxEntries) cache.delete(url);
return res;
});
cache.set(url, p);
return p;
};
return cachedFetch;
}
/** Tiny concurrency limiter: run tasks (thunks) with at most n in flight. */
export async function pMap(items, fn, n = 6) {
const results = new Array(items.length);
let next = 0;
async function worker() {
for (;;) {
const i = next; next += 1;
if (i >= items.length) return;
results[i] = await fn(items[i], i);
}
}
await Promise.all(Array.from({ length: Math.min(n, items.length) }, worker));
return results;
}
/* ----------------------------------------------------------------- html -- */
export function stripTags(html) {
return html
.replace(/<script[\s\S]*?<\/script>/gi, ' ')
.replace(/<style[\s\S]*?<\/style>/gi, ' ')
.replace(/<[^>]+>/g, ' ')
.replace(/ /g, ' ')
.replace(/&/g, '&').replace(/</g, '<').replace(/>/g, '>')
.replace(/&#x([0-9a-f]+);/gi, (_, h) => String.fromCodePoint(parseInt(h, 16)))
.replace(/&#(\d+);/g, (_, d) => String.fromCodePoint(Number(d)))
.replace(/&[a-z]+;/gi, ' ')
.replace(/\s+/g, ' ')
.trim();
}
/** Decode HTML entities in an attribute value (hrefs/content carry & etc.). */
export function decodeAttr(s) {
return (s || '')
.replace(/&#x([0-9a-f]+);/gi, (_, h) => String.fromCodePoint(parseInt(h, 16)))
.replace(/&#(\d+);/g, (_, d) => String.fromCodePoint(Number(d)))
.replace(/&/g, '&').replace(/</g, '<').replace(/>/g, '>')
.replace(/"/g, '"').replace(/'|'/g, "'");
}
/** Normalize text for containment comparisons: lowercase, alphanumerics only. */
export function normText(s) {
return s.toLowerCase().normalize('NFKD')
.replace(/[‘’]/g, "'").replace(/[“”]/g, '"')
.replace(/[^a-z0-9']+/g, ' ')
.replace(/\s+/g, ' ')
.trim();
}
/** Extract `<p>…</p>` inner texts in order (tags stripped). */
export function paragraphTexts(html) {
return [...html.matchAll(/<p[^>]*>([\s\S]*?)<\/p>/gi)].map((m) => stripTags(m[1]));
}
/** Delivered path → live URL. '/' maps to the site root. */
export function pageUrl(base, path) {
return `${base.replace(/\/$/, '')}${path === '/' ? '/' : path}`;
}
export function plainUrl(base, path) {
const b = base.replace(/\/$/, '');
return path.endsWith('/') ? `${b}${path}index.plain.html` : `${b}${path}.plain.html`;
}
export function pathSlug(path) {
return path === '/' ? 'index' : path.replace(/^\//, '').replace(/\//g, '__');
}
/* ------------------------------------------------------------- findings -- */
/**
* Finding shape (schemas/qa-report.schema.json):
* check one of routing|content|templates|rendered|visual|metadata|links|a11y|perf
* id stable machine id within the check, e.g. "missing-canonical"
* severity error | warn | info
* path delivered path the finding is about ('' = fleet-level)
* message one-line human statement
* evidence optional free-form object (urls, counts, excerpts, file refs)
*/
export function finding(check, id, severity, path, message, evidence = undefined) {
const f = { check, id, severity, path, message };
if (evidence !== undefined) f.evidence = evidence;
return f;
}
/* ------------------------------------------------------------ allowlist -- */
/**
* Allowlist entries (schemas/qa-allowlist.schema.json):
* { check, id?, path?, messagePattern?, reason, addedAt? }
* A finding is allowlisted when every provided field matches:
* check: exact or '*'; id: exact or '*'; path: exact or prefix ending in '*';
* messagePattern: JS regex tested against message.
* Allowlisted findings stay in the report (allowlisted: true) — they are
* documented non-defects, not deleted evidence.
*/
export function loadAllowlist(file) {
const doc = readJSON(file, null);
if (!doc) return [];
return Array.isArray(doc) ? doc : (doc.entries || []);
}
function pathMatches(pattern, path) {
if (pattern === undefined || pattern === null) return true;
if (pattern.endsWith('*')) return path.startsWith(pattern.slice(0, -1));
return pattern === path;
}
export function applyAllowlist(findings, entries) {
for (const f of findings) {
const hit = entries.find((e) => (e.check === '*' || e.check === f.check)
&& (e.id === undefined || e.id === '*' || e.id === f.id)
&& pathMatches(e.path, f.path)
&& (e.messagePattern === undefined || new RegExp(e.messagePattern, 'i').test(f.message)));
if (hit) { f.allowlisted = true; f.allowlistReason = hit.reason || ''; }
}
return findings;
}
/* ------------------------------------------------------------ playwright -- */
// The browser front door (stardust/scripts/browser.mjs), resolved once. A check that needs a browser and cannot
// find it throws, like a missing playwright: the orchestrator records the crash, links.mjs reports "unverified".
const BROWSER = ['../../stardust/scripts/browser.mjs', '../stardust/browser.mjs']
.map((p) => new URL(p, import.meta.url)).find((u) => existsSync(u));
function frontDoor() {
if (!BROWSER) throw new Error('qa/lib.mjs: browser.mjs not found (looked in ../../stardust/scripts/ and ../stardust/). Copy the master skill\'s scripts dir to stardust/scripts/stardust/ (skills/stardust/SKILL.md § Setup).');
return import(BROWSER.href);
}
const viaFrontDoor = (name) => async (...args) => (await frontDoor())[name](...args);
export const loadPlaywright = viaFrontDoor('loadPlaywright');
export const openBrowser = viaFrontDoor('openBrowser');
export const newContext = viaFrontDoor('newContext');
export const newPage = viaFrontDoor('newPage');
export const goto = viaFrontDoor('goto');
/* ------------------------------------------------------------- inventory -- */
/**
* Build the page inventory (the fleet the checks sweep). Sources, merged:
* --paths-file <txt> one delivered path per line
* --template-map <json> stardust/template-map.json ({templates:{t:{urls:[]}}})
* sitemap.xml at --base always fetched when base is set (also used for parity findings)
* Fragments (default lib/kinds.mjs QA_CHROME_PATHS: nav/footer) are tracked separately: they are delivered
* documents but not pages (no h1/metadata expectations).
*/
export async function buildInventory({ base, pathsFile, templateMap, fragments = QA_CHROME_PATHS, mergeSitemap = true }) {
const pages = new Map(); // path -> {path, sources:[], template}
// path is the key (no trailing slash); url is where EDS serves the page: a folder index at /x/, which a source
// listing it with its slash tells (/x 404s on a plain EDS site) — lib/paths.mjs listingKey / listingUrl
const add = (path, source, template) => {
const p = listingKey(path);
if (!pages.has(p)) pages.set(p, { path: p, url: p, sources: [], template: template || null });
const row = pages.get(p);
if (listingUrl(path) !== p) row.url = listingUrl(path);
if (!row.sources.includes(source)) row.sources.push(source);
if (template && !row.template) row.template = template;
};
if (pathsFile && existsSync(pathsFile)) {
for (const line of readFileSync(pathsFile, 'utf8').split('\n')) {
const t = line.trim();
if (t && !t.startsWith('#')) add(t.startsWith('/') ? t : `/${t}`, 'paths-file');
}
}
if (templateMap && existsSync(templateMap)) {
const doc = readJSON(templateMap, {});
for (const [tname, t] of Object.entries(doc.templates || {})) {
for (const u of t.urls || []) add(u, 'template-map', tname);
}
}
let sitemapPaths = null;
if (base) {
const res = await fetchUrl(`${base.replace(/\/$/, '')}/sitemap.xml`);
if (res.ok) {
sitemapPaths = [...res.body.matchAll(/<loc>\s*([^<\s]+)\s*<\/loc>/g)]
.map((m) => { try { return listingKey(new URL(m[1]).pathname); } catch { return null; } })
.filter(Boolean);
if (mergeSitemap) for (const p of sitemapPaths) if (!fragments.includes(p)) add(p, 'sitemap');
}
}
return {
pages: [...pages.values()].sort((a, b) => a.path.localeCompare(b.path)),
sitemapPaths, // null = sitemap unavailable
fragments,
};
}.tessl-plugin
skills
audit
reference
deploy
reference
scripts
test
diff
direct
dynamics
extract
migrate
prepare-migration
prototype
assets
motion
fixtures
reference
qa
replica
reference
scripts
test
reskin
rollout
spec
stardust
uplift
reference