qa-engineer 0.9.0

package/packages/installer/lib/core/schema-validate.mjs

@@ -0,0 +1,142 @@
+// A dependency-free validator for the JSON Schema subset this project uses.
+// It is the JavaScript twin of the Python contract validator in
+// shared/analysis/lib/qa_analysis/contracts.py: same supported subset, same
+// semantics, so a document that passes one passes the other. That promise is
+// tested, not asserted — tests/parity/validator-cases.json runs through both.
+//
+// Anything outside the subset is a programming error in the schema, reported
+// rather than silently ignored. `allOf`/`if`/`then`/`else` are in the subset
+// because the pack's safety invariants are cross-field implications.
+
+// Keep in sync with SUPPORTED_KEYWORDS in
+// shared/analysis/lib/qa_analysis/contracts.py and the table in
+// docs/skills/output-contracts.md (checked by scripts/check-spec-code-sync.mjs).
+const SUPPORTED = new Set([
+  '$schema', '$id', 'title', 'description', 'type', 'properties', 'required',
+  'additionalProperties', 'items', 'enum', 'const', 'pattern', 'minimum',
+  'maximum', 'minItems', 'maxItems', 'minLength', 'maxLength', 'default',
+  'examples', 'format', 'allOf', 'if', 'then', 'else',
+]);
+
+// RFC 3339 date-time — the same rule as the Python twin.
+const DATE_TIME = /^\d{4}-\d{2}-\d{2}[Tt]\d{2}:\d{2}:\d{2}(\.\d+)?([Zz]|[+-]\d{2}:\d{2})$/;
+
+function typeOf(value) {
+  if (value === null) return 'null';
+  if (Array.isArray(value)) return 'array';
+  if (Number.isInteger(value)) return 'integer';
+  return typeof value; // string | number | boolean | object
+}
+
+function matchesType(value, type) {
+  if (type === 'integer') return Number.isInteger(value) && typeof value !== 'boolean';
+  if (type === 'number') return typeof value === 'number';
+  if (type === 'object') return value !== null && typeof value === 'object' && !Array.isArray(value);
+  if (type === 'array') return Array.isArray(value);
+  return typeOf(value) === type;
+}
+
+/** True when value satisfies schema; used for if/then branch selection. */
+function satisfies(value, schema) {
+  const probe = [];
+  validateNode(value, schema, '', probe);
+  return probe.length === 0;
+}
+
+function validateNode(value, schema, pointer, errors) {
+  for (const key of Object.keys(schema)) {
+    if (!SUPPORTED.has(key)) {
+      errors.push(`${pointer || '/'}: schema uses unsupported keyword "${key}"`);
+    }
+  }
+
+  if (schema.type) {
+    const types = Array.isArray(schema.type) ? schema.type : [schema.type];
+    if (!types.some((t) => matchesType(value, t))) {
+      errors.push(`${pointer || '/'}: expected ${types.join(' | ')}, got ${typeOf(value)}`);
+      return; // further checks assume the type held
+    }
+  }
+
+  if (Object.prototype.hasOwnProperty.call(schema, 'const') && JSON.stringify(value) !== JSON.stringify(schema.const)) {
+    errors.push(`${pointer || '/'}: must equal ${JSON.stringify(schema.const)}`);
+  }
+
+  if (schema.enum && !schema.enum.some((option) => JSON.stringify(option) === JSON.stringify(value))) {
+    errors.push(`${pointer || '/'}: ${JSON.stringify(value)} is not one of ${JSON.stringify(schema.enum)}`);
+  }
+
+  if (typeof value === 'string') {
+    if (schema.pattern && !new RegExp(schema.pattern).test(value)) {
+      errors.push(`${pointer || '/'}: "${value}" does not match /${schema.pattern}/`);
+    }
+    if (schema.format === 'date-time' && !DATE_TIME.test(value)) {
+      errors.push(`${pointer || '/'}: "${value}" is not a valid date-time`);
+    }
+    if (schema.minLength != null && value.length < schema.minLength) {
+      errors.push(`${pointer || '/'}: shorter than minLength ${schema.minLength}`);
+    }
+    if (schema.maxLength != null && value.length > schema.maxLength) {
+      errors.push(`${pointer || '/'}: longer than maxLength ${schema.maxLength}`);
+    }
+  }
+
+  if (typeof value === 'number') {
+    if (schema.minimum != null && value < schema.minimum) {
+      errors.push(`${pointer || '/'}: ${value} is below minimum ${schema.minimum}`);
+    }
+    if (schema.maximum != null && value > schema.maximum) {
+      errors.push(`${pointer || '/'}: ${value} is above maximum ${schema.maximum}`);
+    }
+  }
+
+  if (Array.isArray(value)) {
+    if (schema.minItems != null && value.length < schema.minItems) {
+      errors.push(`${pointer || '/'}: has ${value.length} items, needs at least ${schema.minItems}`);
+    }
+    if (schema.maxItems != null && value.length > schema.maxItems) {
+      errors.push(`${pointer || '/'}: has ${value.length} items, allows at most ${schema.maxItems}`);
+    }
+    if (schema.items) {
+      value.forEach((item, index) => validateNode(item, schema.items, `${pointer}/${index}`, errors));
+    }
+  }
+
+  if (matchesType(value, 'object') && (schema.properties || schema.required || schema.additionalProperties === false)) {
+    const properties = schema.properties ?? {};
+    for (const name of schema.required ?? []) {
+      if (!Object.prototype.hasOwnProperty.call(value, name)) {
+        errors.push(`${pointer || '/'}: missing required property "${name}"`);
+      }
+    }
+    for (const [name, child] of Object.entries(value)) {
+      if (properties[name]) {
+        validateNode(child, properties[name], `${pointer}/${name}`, errors);
+      } else if (schema.additionalProperties === false) {
+        errors.push(`${pointer || '/'}: unexpected property "${name}"`);
+      }
+    }
+  }
+
+  // Applicators last: the invariant layer. `additionalProperties` deliberately
+  // does not see properties introduced by these subschemas (JSON Schema
+  // 2020-12 rule, matching the Python twin).
+  for (const sub of schema.allOf ?? []) {
+    validateNode(value, sub, pointer, errors);
+  }
+
+  if (Object.prototype.hasOwnProperty.call(schema, 'if')) {
+    const branch = satisfies(value, schema.if) ? schema.then : schema.else;
+    if (branch != null) validateNode(value, branch, pointer, errors);
+  }
+}
+
+/** Validate `value` against `schema`; returns an array of error strings (empty = valid). */
+export function validate(value, schema) {
+  const errors = [];
+  validateNode(value, schema, '', errors);
+  return errors;
+}
+
+/** The supported keyword subset, exported so tooling can assert parity. */
+export const SUPPORTED_KEYWORDS = Object.freeze([...SUPPORTED].sort());

package/packages/installer/lib/core/skill-meta.mjs

@@ -0,0 +1,75 @@
+// Reading the handful of frontmatter fields the installer needs from a
+// SKILL.md: name, description, and the optional argument-hint. Parses the same
+// restricted YAML subset the skill specification allows (plain scalars, folded
+// ">-"/">" blocks, one flat metadata map). Self-contained so the installer can
+// publish without the repository's dev tooling.
+
+import fs from 'node:fs';
+
+function stripQuotes(value) {
+  if ((value.startsWith('"') && value.endsWith('"')) || (value.startsWith("'") && value.endsWith("'"))) {
+    return value.slice(1, -1);
+  }
+  return value;
+}
+
+/** Parse a SKILL.md string; returns { name, description, argumentHint } or throws. */
+export function parseSkillMeta(text) {
+  const lines = text.split('\n');
+  if (lines[0] !== '---') throw new Error('SKILL.md frontmatter must open with "---"');
+  let end = -1;
+  for (let i = 1; i < lines.length; i += 1) {
+    if (lines[i] === '---') {
+      end = i;
+      break;
+    }
+  }
+  if (end === -1) throw new Error('SKILL.md frontmatter is not closed');
+
+  const data = {};
+  let i = 1;
+  while (i < end) {
+    const line = lines[i];
+    if (line.trim() === '') {
+      i += 1;
+      continue;
+    }
+    const top = line.match(/^([A-Za-z][A-Za-z0-9-]*):(?:[ \t]+(.*))?$/);
+    if (!top) {
+      i += 1;
+      continue;
+    }
+    const key = top[1];
+    const raw = (top[2] ?? '').trim();
+    i += 1;
+    if (raw === '>-' || raw === '>') {
+      const parts = [];
+      while (i < end && (lines[i].startsWith('  ') || lines[i].trim() === '')) {
+        if (lines[i].trim() !== '') parts.push(lines[i].trim());
+        i += 1;
+      }
+      data[key] = parts.join(' ');
+    } else if (raw === '' && key === 'metadata') {
+      while (i < end && /^ {2}\S/.test(lines[i])) i += 1; // skip the metadata map; not needed here
+    } else if (raw !== '') {
+      data[key] = stripQuotes(raw);
+    }
+  }
+  return {
+    name: data.name,
+    description: data.description ?? '',
+    argumentHint: data['argument-hint'] ?? null,
+  };
+}
+
+export function readSkillMeta(skillMdPath) {
+  return parseSkillMeta(fs.readFileSync(skillMdPath, 'utf8'));
+}
+
+/** A single-line summary for a wrapper: first sentence, whitespace-collapsed, capped. */
+export function oneLineDescription(description, cap = 220) {
+  const collapsed = description.replace(/\s+/g, ' ').trim();
+  const firstSentence = collapsed.match(/^(.*?\.)(\s|$)/);
+  const text = firstSentence ? firstSentence[1] : collapsed;
+  return text.length > cap ? `${text.slice(0, cap - 1).trimEnd()}…` : text;
+}

package/packages/installer/lib/core/validate-install.mjs

@@ -0,0 +1,152 @@
+// Post-install validation shared by install, onboard, self-test, and doctor.
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { LOCKFILE, SHARED_SKILLS_DIR, CLAUDE_SKILLS_DIR } from '../constants.mjs';
+import { readLock } from './lockfile.mjs';
+import { hashFile } from './hash.mjs';
+import { findPython, verifyImports, packHasBundles } from './bundle.mjs';
+import { BUNDLE_DEST, BUNDLE_MANIFEST, bundlePackagesForSkill } from './manifest.mjs';
+
+/**
+ * @typedef {{ id: string, ok: boolean, hard: boolean, message: string, hint?: string }} CheckResult
+ */
+
+/**
+ * Validate an installed project. Does not throw — returns structured checks.
+ * @param {string} projectRoot
+ * @returns {{ ok: boolean, checks: CheckResult[] }}
+ */
+export function validateInstall(projectRoot) {
+  /** @type {CheckResult[]} */
+  const checks = [];
+
+  const lock = readLock(projectRoot);
+  if (!lock) {
+    checks.push({
+      id: 'lockfile',
+      ok: false,
+      hard: true,
+      message: `${LOCKFILE} missing`,
+      hint: 'run: qa install',
+    });
+    return { ok: false, checks };
+  }
+
+  checks.push({
+    id: 'lockfile',
+    ok: true,
+    hard: true,
+    message: `${LOCKFILE} present (${lock.files.length} files, pack ${lock.pack?.version ?? '?'})`,
+  });
+
+  let drift = 0;
+  for (const entry of lock.files) {
+    const abs = path.join(projectRoot, entry.path);
+    if (!fs.existsSync(abs)) {
+      drift += 1;
+      continue;
+    }
+    if (hashFile(abs) !== entry.sha256) drift += 1;
+  }
+  checks.push({
+    id: 'integrity',
+    ok: drift === 0,
+    hard: true,
+    message: drift === 0 ? 'all installed files match lockfile hashes' : `${drift} file(s) missing or drifted`,
+    hint: drift === 0 ? undefined : 'run: qa repair',
+  });
+
+  const skillDirs = [SHARED_SKILLS_DIR, CLAUDE_SKILLS_DIR]
+    .map((d) => path.join(projectRoot, d))
+    .filter((d) => fs.existsSync(d));
+
+  let skillCount = 0;
+  let contractCount = 0;
+  for (const dir of skillDirs) {
+    for (const name of fs.readdirSync(dir)) {
+      const skillMd = path.join(dir, name, 'SKILL.md');
+      if (fs.existsSync(skillMd)) skillCount += 1;
+      const contracts = path.join(dir, name, 'contracts');
+      if (fs.existsSync(contracts)) {
+        contractCount += fs.readdirSync(contracts).filter((f) => f.endsWith('.json')).length;
+      }
+    }
+  }
+
+  checks.push({
+    id: 'skills',
+    ok: skillCount > 0,
+    hard: true,
+    message: skillCount > 0 ? `${skillCount} skill(s) installed` : 'no skills found under discovery paths',
+    hint: skillCount > 0 ? undefined : 'run: qa install',
+  });
+
+  checks.push({
+    id: 'contracts',
+    ok: contractCount > 0,
+    hard: false,
+    message:
+      contractCount > 0
+        ? `${contractCount} contract schema(s) present`
+        : 'no contract schemas found (optional for minimal installs)',
+  });
+
+  if (packHasBundles()) {
+    const bundledSkill = Object.keys(BUNDLE_MANIFEST)[0];
+    let libDir = null;
+    for (const base of [SHARED_SKILLS_DIR, CLAUDE_SKILLS_DIR]) {
+      const candidate = path.join(projectRoot, base, bundledSkill, BUNDLE_DEST);
+      if (fs.existsSync(candidate)) {
+        libDir = candidate;
+        break;
+      }
+    }
+
+    const bundleOk = Boolean(libDir);
+    checks.push({
+      id: 'engine',
+      ok: bundleOk,
+      hard: true,
+      message: bundleOk
+        ? `deterministic engine bundled under ${path.relative(projectRoot, libDir)}`
+        : 'deterministic engine bundle missing',
+      hint: bundleOk ? undefined : 'run: qa repair',
+    });
+
+    const python = findPython();
+    if (bundleOk && python) {
+      const packages = bundlePackagesForSkill(bundledSkill);
+      const result = verifyImports({ pythonBin: python.bin, libDir, packages });
+      checks.push({
+        id: 'python-imports',
+        ok: result.ok,
+        hard: false,
+        message: result.ok
+          ? `Python imports OK (${python.bin} ${python.version})`
+          : `Python import check failed: ${result.stderr || 'unknown error'}`,
+        hint: result.ok ? undefined : 'install Python 3.8+ or run: qa doctor',
+      });
+    } else if (bundleOk && !python) {
+      checks.push({
+        id: 'python-imports',
+        ok: false,
+        hard: false,
+        message: 'Python not found — analysis engine import check skipped',
+        hint: 'install Python 3.8+ for full diagnostics',
+      });
+    }
+  }
+
+  const major = Number(process.versions.node.split('.')[0]);
+  checks.push({
+    id: 'node',
+    ok: major >= 18,
+    hard: true,
+    message: `Node ${process.version}`,
+    hint: major >= 18 ? undefined : 'upgrade to Node.js 18.18+',
+  });
+
+  const ok = checks.filter((c) => c.hard).every((c) => c.ok);
+  return { ok, checks };
+}

package/packages/installer/lib/core/wrappers.mjs

@@ -0,0 +1,91 @@
+// Generating per-agent invocation wrappers. A wrapper is a thin companion file
+// that gives an agent a slash command mapping to a skill, for agents whose
+// slash ergonomics need one. Per ADR-0002 a wrapper is rendered from skill
+// frontmatter ALONE, contains no knowledge, and is at most 15 lines. Agents
+// that invoke skills natively (Claude Code, Codex CLI, Cursor) get no wrapper.
+
+import { GENERATED_MARKER } from '../constants.mjs';
+import { oneLineDescription } from './skill-meta.mjs';
+
+const MAX_WRAPPER_LINES = 15;
+
+// YAML/TOML-safe double-quoted string.
+function quote(value) {
+  return `"${value.replace(/\\/g, '\\\\').replace(/"/g, '\\"')}"`;
+}
+
+// Each renderer forwards the user's trailing text using the target agent's own
+// documented argument convention, resolving open question #4 (trailing args)
+// for the agents that need a wrapper.
+const RENDERERS = {
+  // Gemini CLI custom command (TOML). {{args}} injects the trailing text.
+  'command-toml': (name, desc) => ({
+    filename: `${name}.toml`,
+    content:
+      `# ${GENERATED_MARKER}\n` +
+      `description = ${quote(desc)}\n` +
+      'prompt = """\n' +
+      `Apply the ${name} skill from the QA Automation Pack skills, following its procedure.\n` +
+      'Treat the following as the user request:\n\n' +
+      '{{args}}\n' +
+      '"""\n',
+  }),
+
+  // OpenCode custom command (Markdown). $ARGUMENTS injects the trailing text.
+  'command-md': (name, desc) => ({
+    filename: `${name}.md`,
+    content:
+      '---\n' +
+      `description: ${quote(desc)}\n` +
+      '---\n' +
+      `<!-- ${GENERATED_MARKER} -->\n\n` +
+      `Apply the \`${name}\` skill from the QA Automation Pack to the request below, following its procedure.\n\n` +
+      '$ARGUMENTS\n',
+  }),
+
+  // GitHub Copilot prompt file. Copilot supplies the chat request as context.
+  'prompt-md': (name, desc) => ({
+    filename: `${name}.prompt.md`,
+    content:
+      '---\n' +
+      `description: ${quote(desc)}\n` +
+      '---\n' +
+      `<!-- ${GENERATED_MARKER} -->\n\n` +
+      `Apply the \`${name}\` skill from the QA Automation Pack to the current request, following its procedure.\n`,
+  }),
+
+  // Antigravity workflow (Markdown). Format is not yet verified against primary
+  // documentation (ADR-0002 open question #3), so this is generated only on
+  // explicit opt-in; the default is auto-activation.
+  'workflow-md': (name, desc) => ({
+    filename: `${name}.md`,
+    content:
+      '---\n' +
+      `description: ${quote(desc)}\n` +
+      '---\n' +
+      `<!-- ${GENERATED_MARKER} -->\n\n` +
+      `Apply the \`${name}\` skill from the QA Automation Pack to the request below, following its procedure.\n\n` +
+      '$ARGUMENTS\n',
+  }),
+};
+
+export function supportsFormat(format) {
+  return Object.prototype.hasOwnProperty.call(RENDERERS, format);
+}
+
+/**
+ * Render one wrapper. Returns { filename, content }. Throws if the result would
+ * exceed the 15-line ceiling — a guard against a wrapper accreting knowledge.
+ */
+export function renderWrapper(format, meta) {
+  const render = RENDERERS[format];
+  if (!render) throw new Error(`unknown wrapper format: ${format}`);
+  const out = render(meta.name, oneLineDescription(meta.description));
+  const lines = out.content.replace(/\n$/, '').split('\n').length;
+  if (lines > MAX_WRAPPER_LINES) {
+    throw new Error(`wrapper for ${meta.name} is ${lines} lines (max ${MAX_WRAPPER_LINES})`);
+  }
+  return out;
+}
+
+export { MAX_WRAPPER_LINES };

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

@@ -0,0 +1,54 @@
+// Detect OS, shell, git, and package manager for a project root.
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { spawnSync } from 'node:child_process';
+import os from 'node:os';
+
+function hasGit(root) {
+  if (fs.existsSync(path.join(root, '.git'))) return true;
+  const probe = spawnSync('git', ['rev-parse', '--is-inside-work-tree'], {
+    cwd: root,
+    encoding: 'utf8',
+  });
+  return probe.status === 0 && (probe.stdout || '').trim() === 'true';
+}
+
+function detectPackageManager(root) {
+  if (fs.existsSync(path.join(root, 'pnpm-lock.yaml'))) return 'pnpm';
+  if (fs.existsSync(path.join(root, 'yarn.lock'))) return 'yarn';
+  if (fs.existsSync(path.join(root, 'bun.lockb')) || fs.existsSync(path.join(root, 'bun.lock'))) {
+    return 'bun';
+  }
+  if (fs.existsSync(path.join(root, 'package-lock.json'))) return 'npm';
+  if (fs.existsSync(path.join(root, 'package.json'))) return 'npm';
+  return null;
+}
+
+function detectShell() {
+  const shell = process.env.SHELL || process.env.ComSpec || '';
+  if (!shell) return null;
+  return path.basename(shell);
+}
+
+/**
+ * @param {string} projectRoot
+ * @returns {{
+ *   os: string,
+ *   platform: NodeJS.Platform,
+ *   shell: string|null,
+ *   git: boolean,
+ *   packageManager: string|null,
+ *   node: string,
+ * }}
+ */
+export function detectEnvironment(projectRoot) {
+  return {
+    os: `${os.type()} ${os.release()}`,
+    platform: process.platform,
+    shell: detectShell(),
+    git: hasGit(projectRoot),
+    packageManager: detectPackageManager(projectRoot),
+    node: process.version,
+  };
+}

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

@@ -0,0 +1,94 @@
+// Detect test frameworks and languages. Framework identity comes from the
+// canonical registry (shared/frameworks/registry.json) — do not hard-code
+// framework lists here.
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { listFrameworks } from '../../../../shared/frameworks/registry.mjs';
+
+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 hasConfigPrefix(root, prefixes) {
+  if (!prefixes.length || !fs.existsSync(root)) return false;
+  const entries = fs.readdirSync(root);
+  return prefixes.some((prefix) => entries.some((name) => name.startsWith(prefix)));
+}
+
+function hasPythonMarkers(root) {
+  return anyExists(root, [
+    'requirements.txt',
+    'pyproject.toml',
+    'setup.py',
+    'Pipfile',
+    'pytest.ini',
+  ]);
+}
+
+function detectOne(root, fw, deps) {
+  const d = fw.detection;
+  if (d.configFiles.length && anyExists(root, d.configFiles)) return true;
+  if (d.configPrefixes.length && hasConfigPrefix(root, d.configPrefixes)) return true;
+  if (d.dependencies.some((name) => deps.has(name))) return true;
+  if (d.directories.some((dir) => fs.existsSync(path.join(root, dir)))) return true;
+  return false;
+}
+
+/**
+ * @param {string} projectRoot
+ * @returns {{
+ *   frameworks: string[],
+ *   languages: string[],
+ *   details: Record<string, boolean>,
+ * }}
+ */
+export function detectFrameworks(projectRoot) {
+  const pkg = readPackageJson(projectRoot);
+  const deps = depsOf(pkg);
+  const registry = listFrameworks().filter((f) => f.supportLevel !== 'Planning');
+
+  /** @type {Record<string, boolean>} */
+  const details = {};
+  const frameworks = [];
+  for (const fw of registry) {
+    const hit = detectOne(projectRoot, fw, deps);
+    details[fw.id] = hit;
+    if (hit) frameworks.push(fw.id);
+  }
+
+  const typescript =
+    anyExists(projectRoot, ['tsconfig.json', 'tsconfig.base.json']) || deps.has('typescript');
+  const javascript = Boolean(pkg) || anyExists(projectRoot, ['jsconfig.json']);
+  const python = hasPythonMarkers(projectRoot);
+
+  const languages = [];
+  if (typescript) languages.push('typescript');
+  else if (javascript) languages.push('javascript');
+  if (python) languages.push('python');
+
+  details.typescript = typescript;
+  details.javascript = javascript;
+  details.python = python;
+
+  return { frameworks, languages, details };
+}