qa-engineer 0.9.0

package/packages/installer/lib/detect/project.mjs

@@ -0,0 +1,126 @@
+// Detect project characteristics: GraphQL, REST, Docker, CI, monorepo, React.
+
+import fs from 'node:fs';
+import path from 'node:path';
+
+function readPackageJson(root) {
+  const p = path.join(root, 'package.json');
+  if (!fs.existsSync(p)) return null;
+  try {
+    return JSON.parse(fs.readFileSync(p, 'utf8'));
+  } catch {
+    return null;
+  }
+}
+
+function depsOf(pkg) {
+  if (!pkg) return new Set();
+  return new Set([
+    ...Object.keys(pkg.dependencies ?? {}),
+    ...Object.keys(pkg.devDependencies ?? {}),
+    ...Object.keys(pkg.peerDependencies ?? {}),
+  ]);
+}
+
+function anyExists(root, names) {
+  return names.some((n) => fs.existsSync(path.join(root, n)));
+}
+
+function hasGraphqlFiles(root) {
+  try {
+    const entries = fs.readdirSync(root);
+    if (entries.some((n) => n.endsWith('.graphql') || n.endsWith('.gql'))) return true;
+  } catch {
+    /* ignore */
+  }
+  return anyExists(root, ['schema.graphql', 'schema.gql']);
+}
+
+function isMonorepo(root) {
+  return anyExists(root, [
+    'pnpm-workspace.yaml',
+    'lerna.json',
+    'nx.json',
+    'turbo.json',
+    'rush.json',
+  ]);
+}
+
+function hasDocker(root) {
+  return anyExists(root, [
+    'Dockerfile',
+    'Dockerfile.dev',
+    'docker-compose.yml',
+    'docker-compose.yaml',
+    'compose.yml',
+  ]);
+}
+
+function hasGithubActions(root) {
+  const dir = path.join(root, '.github', 'workflows');
+  if (!fs.existsSync(dir)) return false;
+  try {
+    return fs.readdirSync(dir).some((f) => f.endsWith('.yml') || f.endsWith('.yaml'));
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * @param {string} projectRoot
+ * @returns {{
+ *   name: string,
+ *   graphql: boolean,
+ *   rest: boolean,
+ *   docker: boolean,
+ *   githubActions: boolean,
+ *   monorepo: boolean,
+ *   react: boolean,
+ *   features: string[],
+ * }}
+ */
+export function detectProject(projectRoot) {
+  const pkg = readPackageJson(projectRoot);
+  const deps = depsOf(pkg);
+  const name = pkg?.name || path.basename(projectRoot);
+
+  const graphql =
+    hasGraphqlFiles(projectRoot) ||
+    deps.has('graphql') ||
+    deps.has('@apollo/client') ||
+    deps.has('apollo-server') ||
+    deps.has('@nestjs/graphql');
+
+  const rest =
+    deps.has('express') ||
+    deps.has('fastify') ||
+    deps.has('@nestjs/core') ||
+    deps.has('hono') ||
+    deps.has('koa') ||
+    anyExists(projectRoot, ['openapi.yaml', 'openapi.yml', 'swagger.yaml', 'swagger.json']);
+
+  const react =
+    deps.has('react') || deps.has('next') || deps.has('@angular/core') || deps.has('vue');
+  const docker = hasDocker(projectRoot);
+  const githubActions = hasGithubActions(projectRoot);
+  const monorepo = isMonorepo(projectRoot);
+
+  const features = [];
+  if (react) features.push('ui');
+  if (graphql) features.push('graphql');
+  if (rest) features.push('rest');
+  if (docker) features.push('docker');
+  if (githubActions) features.push('github-actions');
+  if (monorepo) features.push('monorepo');
+
+  return {
+    name,
+    graphql,
+    rest,
+    docker,
+    githubActions,
+    monorepo,
+    react,
+    features,
+  };
+}

package/packages/installer/lib/detect/recommend.mjs

@@ -0,0 +1,85 @@
+// Map environment detections to recommended pack capabilities (existing skills only).
+
+/**
+ * @param {{
+ *   frameworks: string[],
+ *   languages: string[],
+ *   project: { graphql: boolean, rest: boolean, react: boolean },
+ *   agents: string[],
+ * }} scan
+ * @returns {Array<{ id: string, label: string, reason: string, recommended: boolean }>}
+ */
+export function recommendCapabilities(scan) {
+  const hasPw = scan.frameworks.includes('playwright');
+  const hasAnyFw = scan.frameworks.length > 0;
+  const { graphql, rest, react } = scan.project;
+
+  /** @type {Array<{ id: string, label: string, reason: string, recommended: boolean }>} */
+  const items = [
+    {
+      id: 'skills',
+      label: 'QA Skills',
+      reason: 'Installs /qa-* Agent Skills into your coding assistant',
+      recommended: true,
+    },
+    {
+      id: 'playwright',
+      label: 'Playwright Integration',
+      reason: hasPw
+        ? 'Playwright detected — live run and generate are Production-ready'
+        : 'No Playwright yet — /qa-generate can bootstrap a suite when you are ready',
+      recommended: hasPw || !hasAnyFw,
+    },
+    {
+      id: 'repo-analysis',
+      label: 'Repository Analysis',
+      reason: '/qa-init profiles the project for every later command',
+      recommended: true,
+    },
+    {
+      id: 'ui-bugs',
+      label: 'UI Bug Detection',
+      reason: react
+        ? 'UI stack detected — /qa-explore and /qa-audit cover live pages'
+        : 'Use /qa-explore against any URL for product QA',
+      recommended: react || hasPw,
+    },
+    {
+      id: 'api',
+      label: 'API Validation',
+      reason: rest
+        ? 'REST stack detected — /qa-api validates HTTP behavior'
+        : 'Available via /qa-api when you have API tests or OpenAPI',
+      recommended: rest,
+    },
+    {
+      id: 'graphql',
+      label: 'GraphQL Validation',
+      reason: graphql
+        ? 'GraphQL detected — /qa-api covers GraphQL operations'
+        : 'Enable when GraphQL appears in the project',
+      recommended: graphql,
+    },
+    {
+      id: 'generation',
+      label: 'Test Generation',
+      reason: hasPw
+        ? 'Extend or bootstrap Playwright suites with /qa-generate'
+        : 'Bootstrap Playwright automation with /qa-generate',
+      recommended: true,
+    },
+    {
+      id: 'engine',
+      label: 'Deterministic Engine',
+      reason: 'Bundles analysis/diagnostics libraries used by debug, fix, and report',
+      recommended: true,
+    },
+  ];
+
+  return items;
+}
+
+/** Capabilities that should always be installed (the full skill pack). */
+export function alwaysInstallIds() {
+  return ['skills', 'engine', 'repo-analysis', 'generation'];
+}

package/packages/installer/lib/detect/scan.mjs

@@ -0,0 +1,48 @@
+// Full project scan: agents + environment + frameworks + project + recommendations.
+
+import path from 'node:path';
+import { AGENTS, resolveInstallTargets } from '../agents/registry.mjs';
+import { detectEnvironment } from './environment.mjs';
+import { detectFrameworks } from './frameworks.mjs';
+import { detectProject } from './project.mjs';
+import { recommendCapabilities } from './recommend.mjs';
+
+/**
+ * @param {string} projectRoot
+ * @param {string[]} [explicitAgentIds]
+ */
+export function scanProject(projectRoot, explicitAgentIds = []) {
+  const root = path.resolve(projectRoot);
+  const environment = detectEnvironment(root);
+  const frameworks = detectFrameworks(root);
+  const project = detectProject(root);
+  const detectedAgents = AGENTS.filter((a) => a.detect(root)).map((a) => ({
+    id: a.id,
+    name: a.name,
+  }));
+  const installTargets = resolveInstallTargets(root, explicitAgentIds).map((a) => ({
+    id: a.id,
+    name: a.name,
+    skillsDir: a.skillsDir,
+  }));
+
+  const recommendations = recommendCapabilities({
+    frameworks: frameworks.frameworks,
+    languages: frameworks.languages,
+    project,
+    agents: detectedAgents.map((a) => a.id),
+  });
+
+  return {
+    projectRoot: root,
+    projectName: project.name,
+    environment,
+    frameworks: frameworks.frameworks,
+    languages: frameworks.languages,
+    frameworkDetails: frameworks.details,
+    project,
+    detectedAgents,
+    installTargets,
+    recommendations,
+  };
+}

package/packages/installer/lib/ui/progress.mjs

@@ -0,0 +1,32 @@
+// Install progress step labels for the polished install experience.
+
+export const INSTALL_STEPS = [
+  { id: 'skills', label: 'Installing skills' },
+  { id: 'knowledge', label: 'Synchronizing shared knowledge' },
+  { id: 'engine', label: 'Bundling deterministic engine' },
+  { id: 'contracts', label: 'Validating contracts' },
+  { id: 'eval', label: 'Installing evaluation platform' },
+  { id: 'config', label: 'Configuration complete' },
+];
+
+/**
+ * Run labeled progress steps around an async install body.
+ * @param {{ start: Function, stop: Function, message?: Function }} spinner
+ * @param {(step: { id: string, label: string }) => Promise<void>|void} [onStep]
+ */
+export async function runProgressSteps(spinner, onStep) {
+  for (const step of INSTALL_STEPS) {
+    spinner.message?.(step.label);
+    spinner.start?.(step.label);
+    if (onStep) await onStep(step);
+    spinner.stop?.(step.label);
+  }
+}
+
+/** Simple text progress bar for non-Clack contexts. */
+export function progressBar(done, total, width = 18) {
+  const ratio = total === 0 ? 1 : Math.min(1, done / total);
+  const filled = Math.round(ratio * width);
+  const bar = `${'█'.repeat(filled)}${'░'.repeat(width - filled)}`;
+  return `${bar} ${Math.round(ratio * 100)}%`;
+}

package/packages/installer/lib/ui/theme.mjs

@@ -0,0 +1,81 @@
+// Clack-based UX helpers. Human progress stays on stderr; machine JSON on stdout.
+
+import * as p from '@clack/prompts';
+import { createLogger } from '../core/logger.mjs';
+
+export function isCancel(value) {
+  return p.isCancel(value);
+}
+
+export function createUi({ quiet = false, json = false } = {}) {
+  const log = createLogger({
+    level: quiet || json ? 'error' : process.env.QA_LOG_LEVEL || 'info',
+  });
+
+  return {
+    log,
+    intro(message = 'Welcome to QA Automation Pack') {
+      if (quiet || json) return;
+      p.intro(message);
+    },
+    outro(message) {
+      if (quiet || json) return;
+      p.outro(message);
+    },
+    note(message, title) {
+      if (quiet || json) return;
+      p.note(message, title);
+    },
+    logLine(message) {
+      if (quiet || json) return;
+      p.log.step(message);
+    },
+    success(message) {
+      if (quiet || json) return;
+      p.log.success(message);
+    },
+    warn(message) {
+      if (quiet || json) return;
+      p.log.warn(message);
+    },
+    error(message) {
+      if (!json) p.log.error(message);
+      else log.error(message);
+    },
+    async confirm(message, { initialValue = true } = {}) {
+      return p.confirm({ message, initialValue });
+    },
+    async multiselect(message, options, { required = true } = {}) {
+      return p.multiselect({
+        message,
+        options,
+        required,
+      });
+    },
+    async text(message, opts = {}) {
+      return p.text({ message, ...opts });
+    },
+    spinner() {
+      if (quiet || json) {
+        return {
+          start() {},
+          stop() {},
+          message() {},
+        };
+      }
+      return p.spinner();
+    },
+    cancel(message = 'Installation cancelled.') {
+      if (!quiet && !json) p.cancel(message);
+    },
+  };
+}
+
+/** Format a QaError (or generic Error) for end users — no stack unless debug. */
+export function formatUserError(error, { debug = false } = {}) {
+  const lines = [];
+  lines.push(error?.message || String(error));
+  if (error?.hint) lines.push(`Next step: ${error.hint}`);
+  if (debug && error?.stack) lines.push(error.stack);
+  return lines.join('\n');
+}

package/packages/installer/lib/version.mjs

@@ -0,0 +1,47 @@
+// Single source of truth for the pack version the installer reports and writes
+// into lockfiles. Read from a package.json at runtime so the two can never
+// drift. Works on any Node 18+ without JSON import attributes.
+//
+// Two layouts must both work, and one of them used to fail silently:
+//
+//   repository   packages/installer/lib/version.mjs -> ../package.json
+//   published    the same relative path, IF packages/installer/package.json is
+//                in the `files` allowlist — it was not, so the published CLI
+//                reported 0.0.0 and wrote 0.0.0 into every lockfile.
+//
+// Both candidates are now tried, and an unresolvable version is loudly wrong
+// (`0.0.0-unknown`) rather than plausibly wrong. `scripts/release/validate-release.mjs`
+// asserts the manifest actually ships, so this fallback should never be reached.
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const here = path.dirname(fileURLToPath(import.meta.url));
+
+const MANIFEST_CANDIDATES = [
+  // The workspace member's own manifest.
+  path.join(here, '..', 'package.json'),
+  // The pack root manifest — always present in a published tarball.
+  path.join(here, '..', '..', '..', 'package.json'),
+];
+
+function readVersion() {
+  for (const manifest of MANIFEST_CANDIDATES) {
+    try {
+      const version = JSON.parse(fs.readFileSync(manifest, 'utf8')).version;
+      if (typeof version === 'string' && version.length > 0) return version;
+    } catch {
+      /* try the next candidate */
+    }
+  }
+  return '0.0.0-unknown';
+}
+
+export const VERSION = readVersion();
+
+// The Agent Skills specification revision this pack validated against. The
+// specification is a living document without formal releases; this records the
+// revision each install was made against so `verify` and support can reason
+// about it. Bump when the pack is re-validated against a newer revision.
+export const SPEC_REVISION = '2026-07';

package/packages/installer/package.json

@@ -0,0 +1,28 @@
+{
+  "name": "@qa-engineer/installer",
+  "version": "0.9.0",
+  "description": "The qa-engineer installer: agent detection, copy-based install, lockfile integrity, and wrapper generation.",
+  "license": "MIT",
+  "type": "module",
+  "exports": {
+    ".": "./bin/qa.mjs"
+  },
+  "bin": {
+    "qa": "bin/qa.mjs"
+  },
+  "engines": {
+    "node": ">=18.18.0"
+  },
+  "files": [
+    "bin",
+    "lib",
+    "schemas",
+    "README.md"
+  ],
+  "dependencies": {
+    "@clack/prompts": "^0.11.0"
+  },
+  "scripts": {
+    "test": "node --test test"
+  }
+}

package/packages/installer/schemas/qa-lock.schema.json

@@ -0,0 +1,89 @@
+{
+  "$schema": "https://json-schema.org/draft-07/schema#",
+  "$id": "urn:qa-pack:config:qa-lock:1",
+  "title": "QA Automation Pack install lockfile",
+  "description": "qa-lock.json records exactly what was installed and a hash per file, so an install can be verified, updated, or removed without guessing. Written by the installer; not hand-edited.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["lockfileVersion", "pack", "installer", "generatedAt", "agents", "files"],
+  "properties": {
+    "lockfileVersion": {
+      "type": "integer",
+      "const": 1
+    },
+    "pack": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["name", "version", "specRevision"],
+      "properties": {
+        "name": { "type": "string" },
+        "version": { "type": "string", "pattern": "^\\d+\\.\\d+\\.\\d+" },
+        "specRevision": { "type": "string" }
+      }
+    },
+    "installer": {
+      "type": "string",
+      "pattern": "^\\d+\\.\\d+\\.\\d+"
+    },
+    "generatedAt": {
+      "type": "string",
+      "format": "date-time"
+    },
+    "agents": {
+      "type": "array",
+      "minItems": 1,
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["id", "name", "tier"],
+        "properties": {
+          "id": { "type": "string", "pattern": "^[a-z][a-z0-9-]*$" },
+          "name": { "type": "string" },
+          "tier": {
+            "type": ["integer", "null"],
+            "minimum": 1,
+            "maximum": 2,
+            "description": "Support tier, or null when the host is unknown — the shared Agent Skills path was installed without identifying a product."
+          },
+          "skillsDir": { "type": "string" },
+          "detected": {
+            "type": "boolean",
+            "description": "True only when project markers identified this host. False when it was requested explicitly or stands in as the unknown-agent path. Optional for lockfiles written before this field existed."
+          }
+        }
+      }
+    },
+    "files": {
+      "type": "array",
+      "description": "Every file the installer wrote, each with the hash it wrote, so verify detects drift and uninstall removes exactly these.",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["path", "sha256", "bytes", "owner"],
+        "properties": {
+          "path": {
+            "type": "string",
+            "minLength": 1,
+            "description": "Project-relative POSIX path. Must not be absolute and must not contain a '..' segment: a lockfile travels with a cloned repository, and uninstall deletes what it lists.",
+            "pattern": "^(?!/)(?!.*(^|/)\\.\\.($|/)).+$"
+          },
+          "sha256": { "type": "string", "pattern": "^[0-9a-f]{64}$" },
+          "bytes": { "type": "integer", "minimum": 0 },
+          "owner": { "type": "string", "enum": ["skill", "wrapper", "config"] },
+          "skill": { "type": "string" },
+          "agent": { "type": "string" }
+        }
+      }
+    },
+    "summary": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "skills": { "type": "integer", "minimum": 0 },
+        "files": { "type": "integer", "minimum": 0 },
+        "wrappers": { "type": "integer", "minimum": 0 },
+        "directories": { "type": "integer", "minimum": 0 }
+      }
+    }
+  }
+}

package/packages/installer/schemas/qa.config.schema.json

@@ -0,0 +1,91 @@
+{
+  "$schema": "https://json-schema.org/draft-07/schema#",
+  "$id": "urn:qa-pack:config:qa-config:1",
+  "title": "QA Automation Pack project configuration",
+  "description": "The optional qa.config.json written at a project root. Every field has a documented default; the file exists only to override those defaults. See docs/architecture/ADR-0015-configuration-contract.md.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["version"],
+  "properties": {
+    "version": {
+      "type": "integer",
+      "const": 1,
+      "description": "Configuration contract major version. Bumped only by a breaking change to this schema."
+    },
+    "frameworks": {
+      "type": "object",
+      "additionalProperties": false,
+      "description": "Test-framework preferences. Advisory hints the skills read; they never override what a repository actually contains.",
+      "properties": {
+        "preferred": {
+          "type": "string",
+          "enum": ["playwright", "selenium", "cypress", "webdriverio"],
+          "description": "Framework to prefer when a project has none yet, or when detection is ambiguous."
+        }
+      }
+    },
+    "browser": {
+      "type": "object",
+      "additionalProperties": false,
+      "description": "Default browser preferences for execution and audit skills.",
+      "properties": {
+        "default": {
+          "type": "string",
+          "enum": ["chromium", "firefox", "webkit", "chrome", "edge"],
+          "description": "Browser used when a command does not name one. Defaults to chromium."
+        }
+      }
+    },
+    "output": {
+      "type": "object",
+      "additionalProperties": false,
+      "description": "Where skills write machine-readable results and evidence.",
+      "properties": {
+        "directory": {
+          "type": "string",
+          "minLength": 1,
+          "description": "Artifact output directory, relative to the project root. Defaults to qa-artifacts."
+        }
+      }
+    },
+    "logging": {
+      "type": "object",
+      "additionalProperties": false,
+      "description": "Verbosity of the installer CLI and skill progress reporting.",
+      "properties": {
+        "level": {
+          "type": "string",
+          "enum": ["silent", "error", "warn", "info", "debug"],
+          "description": "Minimum level to emit. Defaults to info."
+        }
+      }
+    },
+    "telemetry": {
+      "type": "object",
+      "additionalProperties": false,
+      "description": "Reserved. The pack implements no telemetry sink and transmits nothing (see SECURITY.md); this field exists only so that any future, opt-in telemetry is off by contract.",
+      "properties": {
+        "enabled": {
+          "type": "boolean",
+          "description": "Always defaults to false. No code path currently reads a true value to transmit anything."
+        }
+      }
+    },
+    "plugins": {
+      "type": "array",
+      "description": "Reserved for future third-party knowledge or framework plugins. Currently unused; declared plugins are ignored with a warning.",
+      "items": {
+        "type": "string",
+        "minLength": 1
+      }
+    },
+    "agents": {
+      "type": "array",
+      "description": "Explicit list of agent ids to install for. When omitted, the installer auto-detects. Values must be known agent ids (see qa doctor).",
+      "items": {
+        "type": "string",
+        "pattern": "^[a-z][a-z0-9-]*$"
+      }
+    }
+  }
+}

package/shared/analysis/lib/qa_analysis/__init__.py

@@ -0,0 +1,11 @@
+"""qa_analysis — the pack's deterministic analysis core.
+
+Framework-agnostic tooling shared by every diagnostic skill: redaction,
+the evidence and finding model, the failure taxonomy, artifact discovery,
+format parsers (JUnit, HAR), contract validation, and the diff guard.
+
+Standard library only. Knows nothing about any test framework; framework
+specifics live in shared/frameworks/<name>/lib and depend on this package.
+"""
+
+__version__ = "0.1.0"

package/shared/analysis/lib/qa_analysis/branding.json

@@ -0,0 +1,9 @@
+{
+  "$comment": "The single source of truth for product attribution in human-readable reports. Every renderer reads this file; no branding string is hardcoded anywhere else in the repository, and scripts/check-branding.mjs fails if one appears. Changing the footer means editing this file only.",
+  "projectName": "QA Automation Pack",
+  "tagline": "AI-First Deterministic QA Engineering Platform",
+  "author": "Abisheik",
+  "website": "https://abisheik.dev",
+  "attributionPrefix": "Powered by",
+  "authorPrefix": "Designed & Developed by"
+}