qa-engineer 0.10.0 → 0.11.0

package/packages/engine/lib/report/theme/tokens.mjs

@@ -0,0 +1,137 @@
+// Design tokens for the report.
+//
+// One source for colour, type, and spacing, consumed twice: the stylesheet emits
+// them as custom properties, and the SVG charts read the JavaScript values directly
+// because an `<svg>` attribute cannot resolve `var(--sev-critical)` in every renderer
+// that matters (Safari's print path and most PDF engines drop it).
+//
+// So a severity has exactly one red, and a chart cannot drift from the badge beside
+// it. Adding a severity means adding it here, and the badge, the donut segment, and
+// the legend all learn about it at once.
+
+/**
+ * Severity is the report's primary signal, so it gets a full ramp rather than a
+ * single hex: a badge needs a readable foreground on a tinted chip, a chart needs a
+ * saturated fill, and dark mode needs both again at a different luminance.
+ */
+export const SEVERITY = Object.freeze({
+  critical: {
+    label: 'Critical',
+    rank: 0,
+    light: { fg: '#8a1c13', bg: '#fef3f2', border: '#fda29b', solid: '#d92d20' },
+    dark: { fg: '#ffbdb5', bg: 'rgba(217,45,32,.16)', border: 'rgba(253,162,155,.32)', solid: '#f97066' },
+    meaning: 'Blocks release. Data loss, a security hole, or a core flow that cannot be completed.',
+  },
+  high: {
+    label: 'High',
+    rank: 1,
+    light: { fg: '#b93815', bg: '#fff4ed', border: '#f9b98c', solid: '#ef6820' },
+    dark: { fg: '#ffc9a8', bg: 'rgba(239,104,32,.16)', border: 'rgba(249,185,140,.32)', solid: '#f38744' },
+    meaning: 'Fix before release. A user hits this on a normal path and the product does the wrong thing.',
+  },
+  medium: {
+    label: 'Medium',
+    rank: 2,
+    light: { fg: '#a15c07', bg: '#fffaeb', border: '#fedf89', solid: '#f79009' },
+    dark: { fg: '#fedf89', bg: 'rgba(247,144,9,.14)', border: 'rgba(254,223,137,.3)', solid: '#fdb022' },
+    meaning: 'Fix soon. Real but survivable — a workaround exists, or the path is less common.',
+  },
+  low: {
+    label: 'Low',
+    rank: 3,
+    light: { fg: '#3538cd', bg: '#eef4ff', border: '#b2ccff', solid: '#6172f3' },
+    dark: { fg: '#b2ccff', bg: 'rgba(97,114,243,.16)', border: 'rgba(178,204,255,.3)', solid: '#8098f9' },
+    meaning: 'Worth fixing. Polish, hygiene, or a measurement that needs confirming before it is acted on.',
+  },
+});
+
+/** Non-severity status colours: test outcomes, check results, page health. */
+export const STATUS = Object.freeze({
+  passed: { label: 'Passed', light: { fg: '#067647', bg: '#ecfdf3', solid: '#17b26a' }, dark: { fg: '#75e0a7', bg: 'rgba(23,178,106,.14)', solid: '#47cd89' } },
+  failed: { label: 'Failed', light: { fg: '#b42318', bg: '#fef3f2', solid: '#f04438' }, dark: { fg: '#fda29b', bg: 'rgba(240,68,56,.14)', solid: '#f97066' } },
+  blocked: { label: 'Blocked', light: { fg: '#b54708', bg: '#fffaeb', solid: '#f79009' }, dark: { fg: '#fedf89', bg: 'rgba(247,144,9,.14)', solid: '#fdb022' } },
+  skipped: { label: 'Skipped', light: { fg: '#475467', bg: '#f2f4f7', solid: '#98a2b3' }, dark: { fg: '#cdd5df', bg: 'rgba(152,162,179,.14)', solid: '#98a2b3' } },
+  neutral: { label: '—', light: { fg: '#475467', bg: '#f2f4f7', solid: '#98a2b3' }, dark: { fg: '#cdd5df', bg: 'rgba(152,162,179,.14)', solid: '#98a2b3' } },
+});
+
+/** The release decision, which owns the loudest surface on the page. */
+export const VERDICT = Object.freeze({
+  ship: { label: 'Ship it', tone: 'good', blurb: 'No release-blocking defects were found.' },
+  'ship-with-risks': { label: 'Ship with risks', tone: 'warn', blurb: 'Releasable, but known defects go out with it.' },
+  'do-not-ship': { label: 'Do not ship', tone: 'bad', blurb: 'At least one defect blocks release.' },
+  'insufficient-data': { label: 'Insufficient data', tone: 'muted', blurb: 'The run could not establish enough to judge.' },
+  // The four `classification` values, mapped onto the same surface so a result
+  // without an `executive` block still renders a verdict rather than a blank strip.
+  pass: { label: 'No defects found', tone: 'good', blurb: 'Nothing reportable was found in the areas covered.' },
+  'issues-found': { label: 'Issues found', tone: 'warn', blurb: 'Defects were found and are listed below.' },
+  blocked: { label: 'Blocked', tone: 'bad', blurb: 'The run could not complete.' },
+  ready: { label: 'Ready to ship', tone: 'good', blurb: 'Every gate the run checked is green.' },
+  'ready-with-risks': { label: 'Ready with risks', tone: 'warn', blurb: 'Releasable with known risks accepted.' },
+  'not-ready': { label: 'Not ready', tone: 'bad', blurb: 'A gate the run checked is red.' },
+});
+
+/** A score's band. Lighthouse taught every reader what 0–49 / 50–89 / 90+ means. */
+export function scoreBand(score) {
+  const value = Number(score);
+  if (!Number.isFinite(value)) return 'muted';
+  if (value >= 90) return 'good';
+  if (value >= 50) return 'warn';
+  return 'bad';
+}
+
+/** Tone colours, used by scores, verdict surfaces, and gauges. */
+export const TONE = Object.freeze({
+  good: { light: '#17b26a', dark: '#47cd89' },
+  warn: { light: '#f79009', dark: '#fdb022' },
+  bad: { light: '#f04438', dark: '#f97066' },
+  muted: { light: '#98a2b3', dark: '#98a2b3' },
+  accent: { light: '#5344e8', dark: '#9b8afb' },
+});
+
+/**
+ * The categorical ramp for charts that plot something other than severity — API
+ * timings, payload sizes, page health. Ordered for maximum separation between
+ * neighbours, and checked against both backgrounds.
+ */
+export const CATEGORICAL = Object.freeze([
+  '#5344e8', '#0ba5ec', '#17b26a', '#f79009', '#ee46bc', '#7a5af8', '#2ed3b7', '#f38744',
+]);
+
+/** Which colour a chart should use for `key`, in `mode` ('light' | 'dark'). */
+export function colourFor(key, mode = 'light') {
+  if (SEVERITY[key]) return SEVERITY[key][mode].solid;
+  if (STATUS[key]) return STATUS[key][mode].solid;
+  if (TONE[key]) return TONE[key][mode];
+  return TONE.muted[mode];
+}
+
+/** Severity keys, worst first — the order findings and legends are rendered in. */
+export const SEVERITY_ORDER = Object.freeze(
+  Object.keys(SEVERITY).sort((a, b) => SEVERITY[a].rank - SEVERITY[b].rank),
+);
+
+/**
+ * Core Web Vitals thresholds, as Google publishes them. Used to colour a metric tile
+ * and to decide whether a number is worth a reader's attention — a report that shows
+ * `LCP 4.1s` in the same grey as `TTFB 40ms` has buried the finding.
+ */
+export const VITALS = Object.freeze({
+  lcpMs: { label: 'LCP', full: 'Largest Contentful Paint', good: 2500, poor: 4000, unit: 'ms', plain: 'How long until the main content is visible' },
+  fcpMs: { label: 'FCP', full: 'First Contentful Paint', good: 1800, poor: 3000, unit: 'ms', plain: 'How long until anything is painted' },
+  ttfbMs: { label: 'TTFB', full: 'Time to First Byte', good: 800, poor: 1800, unit: 'ms', plain: 'How long the server took to start responding' },
+  inpMs: { label: 'INP', full: 'Interaction to Next Paint', good: 200, poor: 500, unit: 'ms', plain: 'How quickly the page responds to a click or tap' },
+  cls: { label: 'CLS', full: 'Cumulative Layout Shift', good: 0.1, poor: 0.25, unit: '', plain: 'How much the layout jumps while loading' },
+  longTaskMs: { label: 'Long tasks', full: 'Blocking main-thread time', good: 200, poor: 600, unit: 'ms', plain: 'Time the page spent unable to respond' },
+  domNodes: { label: 'DOM nodes', full: 'DOM size', good: 1500, poor: 3000, unit: '', plain: 'How large the rendered page is' },
+  jsHeapBytes: { label: 'JS heap', full: 'JavaScript heap used', good: 30e6, poor: 100e6, unit: 'bytes', plain: 'Memory the page is holding' },
+});
+
+/** 'good' | 'warn' | 'bad' for a vitals measurement, or 'muted' when unknown. */
+export function vitalBand(key, value) {
+  const spec = VITALS[key];
+  const number = Number(value);
+  if (!spec || !Number.isFinite(number)) return 'muted';
+  if (number <= spec.good) return 'good';
+  if (number <= spec.poor) return 'warn';
+  return 'bad';
+}

package/packages/engine/lib/report/version.mjs

@@ -0,0 +1,78 @@
+// The three versions a report is stamped with, and why there are three.
+//
+// A report outlives the code that made it. Someone opens a two-year-old QA report and
+// needs to know what they are looking at; someone else needs to re-render an archived
+// artifact and needs to know whether today's renderer still understands it. One
+// version number cannot answer both, because the three things move independently:
+//
+//   SCHEMA    the shape of the JSON an agent produces.
+//             Bumping it can break an old renderer. Major bump = breaking.
+//   THEME     the visual identity — colour, type, spacing, components.
+//             Bumping it changes how a report *looks*, never what it *says*.
+//   RENDERER  the code that turns schema into documents.
+//             Bumping it can change output for the same input; a fixed bug counts.
+//
+// A theme change must never require a schema bump, and a renderer fix must never
+// invalidate an archived artifact. Keeping them apart is what makes that true.
+//
+// ## The identity claim
+//
+// THEME_NAME is the part a reader recognises without being told — the thing that makes
+// a report from Claude Code and a report from Cursor look like the same document,
+// because they *are* the same document rendered by the same code. Changing it is a
+// deliberate act of rebranding, not a routine edit.
+
+/** The canonical report schema this renderer reads and this pack's skills emit. */
+export const SCHEMA_VERSION = '2.0';
+
+/** The visual identity. Bump the minor for refinements, the major for a redesign. */
+export const THEME_NAME = 'Enterprise';
+export const THEME_VERSION = '1.0';
+
+/** The rendering code itself. Bump on any change to the produced output. */
+export const RENDERER_VERSION = '1.0';
+
+/**
+ * Schema versions this renderer accepts.
+ *
+ * Listed rather than range-checked so that adding support for a version is a
+ * deliberate edit with a test behind it, and so an unknown future version fails with a
+ * message naming what *is* supported instead of rendering something half-understood.
+ */
+export const SUPPORTED_SCHEMA_VERSIONS = Object.freeze(['1.0', '1.1', '2.0']);
+
+/** The block stamped into every rendered document and every JSON export. */
+export function versionStamp() {
+  return Object.freeze({
+    schemaVersion: SCHEMA_VERSION,
+    themeName: THEME_NAME,
+    themeVersion: THEME_VERSION,
+    rendererVersion: RENDERER_VERSION,
+  });
+}
+
+/** "Enterprise v1.0 · renderer 1.0 · schema 2.0" — the one-line form for a footer. */
+export function versionLine() {
+  return `${THEME_NAME} v${THEME_VERSION} · renderer ${RENDERER_VERSION} · schema ${SCHEMA_VERSION}`;
+}
+
+/**
+ * The schema version a result declares, whichever contract it uses.
+ *
+ * A canonical report says so directly. A per-skill contract carries its version in
+ * `contract.version`, of which only major.minor is meaningful for compatibility — a
+ * patch bump to a contract has never changed its shape.
+ */
+export function schemaVersionOf(result) {
+  if (result?.schemaVersion) return String(result.schemaVersion);
+  const declared = result?.contract?.version;
+  if (!declared) return null;
+  const [major, minor] = String(declared).split('.');
+  return minor === undefined ? major : `${major}.${minor}`;
+}
+
+/** True when this renderer understands the result's schema version. */
+export function isSupportedSchema(result) {
+  const version = schemaVersionOf(result);
+  return version === null || SUPPORTED_SCHEMA_VERSIONS.includes(version);
+}

package/packages/engine/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@qa-engineer/engine",
-  "version": "0.9.2",
-  "description": "Deterministic QA analysis engine — zero dependencies, Node only",
+  "version": "0.11.0",
+  "description": "Deterministic QA analysis engine \u2014 zero dependencies, Node only",
   "license": "MIT",
   "private": true,
   "type": "module",

package/packages/installer/lib/agents/targets.mjs

@@ -0,0 +1,90 @@
+// Which agent directories an install writes to, for a given scope.
+//
+// Project installs keep the behaviour they always had: detect the hosts present in the
+// repository and write to each unique discovery directory. Global installs cannot work
+// that way — detection reads project markers, and there is no project — so they resolve
+// against the table of user-level directories instead, and say plainly which hosts they
+// could not serve.
+//
+// Keeping this out of `registry.mjs` matters: that file is the catalogue of *what hosts
+// exist*, checked against their documentation. This file is the policy for *where to
+// write*, which differs per scope. Mixing them is how the project-only assumption got
+// baked into the catalogue in the first place.
+
+import path from 'node:path';
+
+import { resolveInstallTargets, getAgent, AGENTS, UNKNOWN_AGENT_ID } from './registry.mjs';
+import { userSkillsDir, globalCapableAgents, projectOnlyAgents } from './user-level.mjs';
+
+/**
+ * Agent targets for a scope.
+ *
+ * A target is `{ id, name, tier, skillsDir, wrapperDir, wrapperFormat, detected, linkable }`
+ * where `skillsDir` is relative to the scope root. For a global scope that root is the
+ * user's home, so `.claude/skills` means `~/.claude/skills`.
+ */
+export function resolveScopeTargets(scope, { explicitIds = [], allAgents = false } = {}) {
+  if (scope.kind !== 'global') {
+    // Project and workspace both install into a directory tree the user controls, and
+    // detection works there. Workspace simply detects at the monorepo root.
+    return resolveInstallTargets(scope.root, explicitIds).map((agent) => ({
+      ...agent,
+      // A workspace shares its engine, so its skills can be linked; a project bundles.
+      linkable: scope.shareEngine,
+    }));
+  }
+
+  const wanted = allAgents
+    ? globalCapableAgents()
+    : explicitIds.length > 0
+      ? explicitIds
+      : globalCapableAgents();
+
+  const targets = [];
+  const seen = new Set();
+  for (const id of wanted) {
+    const agent = getAgent(id);
+    if (!agent) throw new Error(`unknown agent id: ${id}`);
+    const dir = userSkillsDir(id);
+    // Requested explicitly but unserviceable: skipped here and reported by the caller,
+    // rather than written to a path the host does not read.
+    if (!dir || seen.has(dir)) continue;
+    seen.add(dir);
+    targets.push({
+      ...agent,
+      skillsDir: dir,
+      // Wrappers are project-scoped by construction — a slash-command file lives beside
+      // the repository it serves — so a global install writes none.
+      wrapperFormat: null,
+      wrapperDir: null,
+      detected: false,
+      requested: explicitIds.includes(id),
+      linkable: true,
+    });
+  }
+
+  return targets;
+}
+
+/**
+ * Hosts a global install cannot serve, and why.
+ *
+ * Printed after a global install so the user learns it from the tool rather than from a
+ * slash command that never appears. Silence here is the failure mode this exists to
+ * prevent.
+ */
+export function describeUnservedAgents(scope, targets) {
+  if (scope.kind !== 'global') return [];
+  const served = new Set(targets.map((t) => t.id));
+  return projectOnlyAgents().filter((entry) => !served.has(entry.id));
+}
+
+/** Every agent id the installer knows, for `--help` and validation. */
+export function knownAgentIds() {
+  return AGENTS.map((a) => a.id).filter((id) => id !== UNKNOWN_AGENT_ID);
+}
+
+/** Absolute path of an agent's skills directory within a scope. */
+export function targetPath(scope, target) {
+  return path.join(scope.root, target.skillsDir);
+}

package/packages/installer/lib/agents/user-level.mjs

@@ -0,0 +1,80 @@
+// Where each agent looks for skills that belong to the *user* rather than to a project.
+//
+// This table is what makes a global install real. A machine-wide install is only useful
+// if the agent actually reads the place we put things, and there is no shared convention
+// — every host invented its own, and several have none at all.
+//
+// ## The rule this table follows
+//
+// A path appears here only when the host's own documentation says it reads it. Writing
+// skills to a guessed path is the worst failure this installer can produce: the files
+// are there, the install reports success, the agent never sees them, and the user
+// concludes the tool is broken. That is strictly worse than saying "this host has no
+// user-level path — install into the project", which is at least actionable.
+//
+// So `null` here is a real answer, carrying the reason. Adding a host later is one entry
+// in this table and nothing else.
+
+import path from 'node:path';
+
+// Paths are relative to the user's home directory, POSIX-style, and joined with the
+// platform separator at use. `os.homedir()` already resolves to %USERPROFILE% on Windows.
+export const USER_LEVEL = Object.freeze({
+  'claude-code': {
+    dir: '.claude/skills',
+    docs: 'https://code.claude.com/docs/en/skills',
+    note: 'Personal skills, read in every project.',
+  },
+  antigravity: {
+    dir: '.gemini/config/skills',
+    docs: 'https://antigravity.google/docs/skills',
+    note: 'Global skills directory, read alongside the workspace one.',
+  },
+
+  // No verified user-level skills directory. Each of these reads project-relative paths
+  // only, as far as their documentation states. A project install serves them today; if
+  // a host adds a user-level path, it becomes one entry above.
+  cursor: { dir: null, reason: 'reads .agents/skills and .cursor/skills per project; no documented user-level path' },
+  codex: { dir: null, reason: 'documents .agents/skills at cwd, parent, and repo root — all project-relative' },
+  opencode: { dir: null, reason: 'documents per-project skills; ~/.config/opencode holds commands, not skills' },
+  'gemini-cli': { dir: null, reason: 'no documented user-level skills path' },
+  'github-copilot': { dir: null, reason: 'prompt files are repository-scoped' },
+  kimi: { dir: null, reason: 'no documented user-level skills path' },
+  'agent-skills': {
+    dir: null,
+    reason: 'the shared Agent Skills path is project-relative by specification; there is no user-level equivalent',
+  },
+});
+
+/** The user-level skills directory for an agent, relative to home, or null. */
+export function userSkillsDir(agentId) {
+  return USER_LEVEL[agentId]?.dir ?? null;
+}
+
+/** Why an agent has no user-level directory, for an honest install report. */
+export function userLevelReason(agentId) {
+  return USER_LEVEL[agentId]?.reason ?? 'not a known agent';
+}
+
+/** Agent ids that can be served by a global install. */
+export function globalCapableAgents() {
+  return Object.keys(USER_LEVEL).filter((id) => USER_LEVEL[id].dir);
+}
+
+/** Agent ids that a global install cannot serve, with the reason for each. */
+export function projectOnlyAgents() {
+  return Object.keys(USER_LEVEL)
+    .filter((id) => !USER_LEVEL[id].dir)
+    .map((id) => ({ id, reason: USER_LEVEL[id].reason }));
+}
+
+/**
+ * The home-relative path of one skill for one agent.
+ *
+ * Returned POSIX-style because it becomes a lockfile entry, and a lockfile written on
+ * Windows has to be readable by the same installer on Linux.
+ */
+export function userSkillPath(agentId, skill) {
+  const dir = userSkillsDir(agentId);
+  return dir ? path.posix.join(dir, skill) : null;
+}

package/packages/installer/lib/cli/flags.mjs

@@ -19,6 +19,9 @@ export function parseCommonFlags(argv, { strict = true } = {}) {
     dryRun: false,
     help: false,
     project: null,
+    global: false,
+    workspace: false,
+    allAgents: false,
     agents: [],
     rest: /** @type {string[]} */ ([]),
   };
@@ -38,9 +41,24 @@ export function parseCommonFlags(argv, { strict = true } = {}) {
       const id = argv[++i];
       if (!id) throw usageError('--agent requires an id');
       flags.agents.push(id);
+    } else if (a === '--global' || a === '-g') {
+      flags.global = true;
+    } else if (a === '--workspace' || a === '-w') {
+      flags.workspace = true;
+    } else if (a === '--all-agents') {
+      flags.allAgents = true;
     } else if (a === '--project' || a === '-C') {
-      flags.project = argv[++i];
-      if (!flags.project) throw usageError('--project requires a path');
+      // `--project` doubles as a scope selector and as a path. Bare, it means "this
+      // directory"; with a value it names one. Requiring a path made `--project` alone
+      // an error while `--global` alone worked, which reads as an inconsistency rather
+      // than as a rule.
+      const next = argv[i + 1];
+      if (next && !next.startsWith('-')) {
+        flags.project = next;
+        i += 1;
+      } else {
+        flags.project = '.';
+      }
     } else if (strict) {
       throw usageError(`unknown option: ${a}`);
     } else {

package/packages/installer/lib/commands/doctor.mjs

@@ -3,7 +3,8 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import { EXIT, SHARED_SKILLS_DIR } from '../constants.mjs';
-import { resolveSourceRoot, resolveProjectRoot } from '../core/paths.mjs';
+import { resolveSourceRoot } from '../core/paths.mjs';
+import { resolveOperatingScope } from '../core/scope.mjs';
 import { VERSION, SPEC_REVISION } from '../version.mjs';
 import { AGENTS, resolveInstallTargets, listAgentIds } from '../agents/registry.mjs';
 import { packHasBundles, verifyEngine } from '../core/bundle.mjs';
@@ -35,7 +36,8 @@ Each failure includes an exact repair command.`);
     return EXIT.OK;
   }
 
-  const root = resolveProjectRoot(opts.project ?? process.cwd());
+  const scope = resolveOperatingScope(opts);
+  const root = scope.root;
   let source = null;
   try {
     source = resolveSourceRoot();
@@ -45,10 +47,10 @@ Each failure includes an exact repair command.`);
 
   const detected = AGENTS.filter((a) => a.detect(root)).map((a) => a.id);
   const targets = resolveInstallTargets(root, opts.agents).map((a) => a.id);
-  const lock = readLock(root);
+  const lock = readLock(root, scope.lockfile);
   const gitOk = hasGit(root);
   const scan = scanProject(root, opts.agents);
-  const validation = lock ? validateInstall(root) : null;
+  const validation = lock ? validateInstall(root, { scope }) : null;
 
   /** @type {Array<{ section: string, id: string, ok: boolean, message: string, hint?: string }>} */
   const checklist = [];