qa-flowkit 0.4.0-alpha.0

package/.qa-ai/presets/manual-only.yaml

@@ -0,0 +1,65 @@
+version: 1
+project:
+  name: CHANGE_ME
+  repoMode: qa-design-only
+  qaTrack: quick
+  defaultLanguage: en
+  interfaceLanguage: en
+tools:
+  testManagement: testrail
+  issueTracker: none
+  documentation: markdown
+agents:
+  specialistMode: auto
+sources:
+  main: markdown
+knowledge:
+  enabled: false
+  sourcePath: ''
+  summaryPath: qa-ai-output/qa-knowledge-summary.md
+  decisionsPath: qa-ai-output/qa-init-decisions.md
+requirements:
+  requireOfficialRfId: true
+  allowInferredAcceptanceCriteria: true
+  requireApprovalForInferredCriteria: true
+gherkin:
+  language: en
+  oneScenarioPerFile: true
+  requireAcceptanceCriteria: true
+  manualTestsNeedFeatureFile: true
+  featurePath: features
+  tags:
+    required:
+      - priority
+      - type
+      - manual
+testrail:
+  enabled: true
+  projectName: CHANGE_ME
+  allowCreateSections: true
+  allowCreateCases: true
+  allowUpdateCases: approval-only
+  allowDeleteCases: never
+  mappingFile: qa-ai-output/test-management-mapping.json
+automation:
+  ui:
+    framework: none
+  api:
+    framework: none
+  strategy:
+    automateAllTechnicallyPossible: false
+    requireProposalBeforeImplementation: true
+    allowModifyExistingTests: approval-only
+testDesign:
+  systemPath: qa-ai-output/test-design-system.md
+  proposalPath: qa-ai-output/test-design-proposal.md
+traceability:
+  matrixPath: qa-ai-output/traceability-matrix.md
+approval:
+  beforeExternalWrite: true
+  beforeExistingFileModification: true
+  beforeTestRailSync: true
+  beforeJiraTaskCreation: true
+  beforePullRequest: true
+commands:
+  testQA: node .qa-ai/scripts/validate-features.mjs

package/.qa-ai/presets/selenium-jest-browserstack.yaml

@@ -0,0 +1,72 @@
+version: 1
+project:
+  name: CHANGE_ME
+  repoMode: qa-and-automation
+  qaTrack: standard
+  defaultLanguage: en
+  interfaceLanguage: en
+tools:
+  testManagement: testrail
+  issueTracker: jira
+  documentation: markdown
+agents:
+  specialistMode: auto
+sources:
+  main: jira
+knowledge:
+  enabled: false
+  sourcePath: ''
+  summaryPath: qa-ai-output/qa-knowledge-summary.md
+  decisionsPath: qa-ai-output/qa-init-decisions.md
+requirements:
+  requireOfficialRfId: true
+  allowInferredAcceptanceCriteria: true
+  requireApprovalForInferredCriteria: true
+gherkin:
+  language: en
+  oneScenarioPerFile: true
+  requireAcceptanceCriteria: true
+  manualTestsNeedFeatureFile: true
+  featurePath: features
+  tags:
+    required:
+      - priority
+      - type
+      - manual
+testrail:
+  enabled: true
+  projectName: CHANGE_ME
+  allowCreateSections: true
+  allowCreateCases: true
+  allowUpdateCases: approval-only
+  allowDeleteCases: never
+  mappingFile: qa-ai-output/test-management-mapping.json
+automation:
+  ui:
+    framework: selenium-jest-browserstack
+    specsPath: tests/selenium/specs
+    pageObjectsPath: tests/selenium/pageobjects
+  api:
+    framework: undecided
+    specsPath: tests/api/specs
+  strategy:
+    automateAllTechnicallyPossible: true
+    requireProposalBeforeImplementation: true
+    allowModifyExistingTests: approval-only
+testDesign:
+  systemPath: qa-ai-output/test-design-system.md
+  proposalPath: qa-ai-output/test-design-proposal.md
+traceability:
+  matrixPath: qa-ai-output/traceability-matrix.md
+release:
+  gatePath: qa-ai-output/release-gate.yaml
+approval:
+  beforeExternalWrite: true
+  beforeExistingFileModification: true
+  beforeTestRailSync: true
+  beforeJiraTaskCreation: true
+  beforePullRequest: true
+commands:
+  lint: npm run lint
+  testE2E: npm run test:e2e
+  testQA: npm run test:qa

package/.qa-ai/presets/webdriverio-playwright-api.yaml

@@ -0,0 +1,85 @@
+version: 1
+project:
+  name: CHANGE_ME
+  repoMode: qa-and-automation
+  qaTrack: standard
+  defaultLanguage: en
+  interfaceLanguage: en
+tools:
+  testManagement: testrail
+  issueTracker: jira
+  documentation: confluence
+agents:
+  specialistMode: auto
+sources:
+  main: jira
+  jira:
+    enabled: true
+    projectKey: CHANGE_ME
+    storyIsSourceOfTruth: true
+    readAttachments: true
+  confluence:
+    enabled: true
+  markdown:
+    enabled: true
+    paths:
+      - docs/PRD
+      - docs/RF
+knowledge:
+  enabled: false
+  sourcePath: ''
+  summaryPath: qa-ai-output/qa-knowledge-summary.md
+  decisionsPath: qa-ai-output/qa-init-decisions.md
+requirements:
+  requireOfficialRfId: true
+  allowInferredAcceptanceCriteria: true
+  requireApprovalForInferredCriteria: true
+gherkin:
+  language: en
+  oneScenarioPerFile: true
+  requireAcceptanceCriteria: true
+  manualTestsNeedFeatureFile: true
+  featurePath: features
+  tags:
+    required:
+      - priority
+      - type
+      - manual
+testrail:
+  enabled: true
+  projectName: CHANGE_ME
+  allowCreateSections: true
+  allowCreateCases: true
+  allowUpdateCases: approval-only
+  allowDeleteCases: never
+  mappingFile: qa-ai-output/test-management-mapping.json
+automation:
+  ui:
+    framework: webdriverio
+    specsPath: tests/wdio/specs
+    pageObjectsPath: tests/wdio/pageobjects
+  api:
+    framework: playwright-api
+    specsPath: tests/api/specs
+  strategy:
+    automateAllTechnicallyPossible: true
+    requireProposalBeforeImplementation: true
+    allowModifyExistingTests: approval-only
+traceability:
+  matrixPath: qa-ai-output/traceability-matrix.md
+testDesign:
+  systemPath: qa-ai-output/test-design-system.md
+  proposalPath: qa-ai-output/test-design-proposal.md
+release:
+  gatePath: qa-ai-output/release-gate.yaml
+approval:
+  beforeExternalWrite: true
+  beforeExistingFileModification: true
+  beforeTestRailSync: true
+  beforeJiraTaskCreation: true
+  beforePullRequest: true
+commands:
+  lint: npm run lint
+  testApi: npm run test:api
+  testE2E: npm run test:e2e
+  testQA: npm run test:qa

package/.qa-ai/rules/api-testing.rules.md

@@ -0,0 +1,7 @@
+# API Testing Rules
+
+- Use the API/integration framework configured in `qa-ai.config.yaml` (`automation.api.framework`).
+- Check existing API testing patterns before creating new ones.
+- Use clients, fixtures and schemas for maintainability.
+- Do not add dependencies without approval.
+- If API framework is `none`, `undecided` or missing, create a proposal and keep tests as manual/blocked until decided.

package/.qa-ai/rules/approval.rules.md

@@ -0,0 +1,8 @@
+# Approval Rules
+
+- Always present a detailed plan before modifying files.
+- Ask approval before external writes to configured tools.
+- Ask approval before modifying existing tests.
+- Never delete external test cases by default.
+- Never overwrite existing files unless explicitly approved.
+- Ask the user when ambiguity exists and offer options.

package/.qa-ai/rules/automation.rules.md

@@ -0,0 +1,7 @@
+# Automation Rules
+
+- Automate every test that is technically possible and valuable under current repo constraints.
+- Generate a technical proposal before writing code.
+- Do not modify existing tests without approval.
+- If tests cannot be executed, mark first execution as manual.
+- Create configured issue tracker task drafts for automatable tests that cannot be implemented now.

package/.qa-ai/rules/gherkin.rules.md

@@ -0,0 +1,12 @@
+# Gherkin Rules
+
+- Use the configured Gherkin language from `qa-ai.config.yaml` (`gherkin.language`): English (`en`) or Spanish (`es`).
+- Use English Gherkin keywords and `Acceptance Criteria:` for `en`.
+- Use Spanish Gherkin keywords and `Criterios de aceptación:` for `es`.
+- Spanish `.feature` files must include `# language: es`.
+- One `.feature` file per test case.
+- One configured scenario keyword per `.feature` file: `Scenario:` / `Scenario Outline:` for English or `Escenario:` / `Esquema del escenario:` for Spanish.
+- Include the configured acceptance criteria section after the Feature narrative.
+- Required tags: `@priority:`, `@type:`, `@manual:`.
+- Manual tests also require `.feature` files.
+- Unit tests are excluded.

package/.qa-ai/rules/testrail.rules.md

@@ -0,0 +1,10 @@
+# Test Management Rules
+
+- Use the configured test management tool from `qa-ai.config.yaml` (`tools.testManagement`).
+- Ask the user for the target project/suite when needed.
+- Search existing cases before proposing new cases.
+- Detect duplicates and potential overlaps.
+- Create new sections only after informing the user.
+- Create new cases only after approval.
+- Update existing cases only after explicit approval.
+- Delete or archive cases only after explicit approval and only if allowed by configuration.

package/.qa-ai/rules/webdriverio.rules.md

@@ -0,0 +1,9 @@
+# UI Automation Rules
+
+- Follow existing repository patterns.
+- Reuse page objects, helpers and fixtures when possible.
+- Create new page objects only when needed.
+- Use the UI/E2E framework configured in `qa-ai.config.yaml` (`automation.ui.framework`).
+- Do not change global framework config without approval.
+- Prefer stable selectors and accessibility attributes.
+- Keep tests isolated and deterministic.

package/.qa-ai/scripts/bootstrap-agent-adapters.mjs

@@ -0,0 +1,127 @@
+#!/usr/bin/env node
+import path from 'node:path';
+import {
+  commaList,
+  copyFileSafe,
+  ensureDir,
+  manifestEntry,
+  manifestPath,
+  parseArgs,
+  pathExists,
+  recordManifestEntries,
+  relativeTo,
+  logHeader
+} from './lib/utils.mjs';
+
+const cwd = process.cwd();
+const args = parseArgs(process.argv);
+const force = Boolean(args.force);
+const qaAiDir = path.join(cwd, '.qa-ai');
+
+const bootstrapMap = {
+  claude: {
+    source: '.qa-ai/adapters/claude/commands/qa-init.md',
+    target: '.claude/commands/qa-init.md',
+    command: '/qa-init'
+  },
+  opencode: {
+    source: '.qa-ai/adapters/opencode/commands/qa-init.md',
+    target: '.opencode/commands/qa-init.md',
+    command: '/qa-init'
+  }
+};
+
+function printHelp() {
+  console.log(`Usage: node .qa-ai/scripts/bootstrap-agent-adapters.mjs [options]
+
+Copies minimal root slash commands so Claude Code and OpenCode can run /qa-init
+after only the .qa-ai folder has been copied.
+
+Options:
+  --agents <list>  Comma-separated agents to bootstrap (default: claude,opencode)
+  --agent <name>   Repeatable single agent name
+  --force          Overwrite existing bootstrap command files
+  --help           Show this help
+
+Supported agents: ${Object.keys(bootstrapMap).join(', ')}
+`);
+}
+
+function selectedAgents() {
+  const requested = [...commaList(args.agents), ...commaList(args.agent)].map((name) => name.toLowerCase());
+  if (requested.length === 0 || requested.includes('all')) return Object.keys(bootstrapMap);
+  if (requested.includes('none')) return [];
+  return [...new Set(requested)];
+}
+
+async function main() {
+  if (args.help) {
+    printHelp();
+    return;
+  }
+
+  logHeader('QA FlowKit agent bootstrap');
+
+  if (!await pathExists(qaAiDir)) {
+    console.error('Missing .qa-ai folder. Copy it into the repository root first.');
+    process.exit(1);
+  }
+
+  const agents = selectedAgents();
+  const unknown = agents.filter((name) => !(name in bootstrapMap));
+  if (unknown.length > 0) {
+    console.error(`Unknown agent(s): ${unknown.join(', ')}`);
+    console.error(`Supported agents: ${Object.keys(bootstrapMap).join(', ')}`);
+    process.exit(1);
+  }
+
+  if (agents.length === 0) {
+    console.log('No agents selected.');
+    return;
+  }
+
+  const manifestEntries = [];
+
+  for (const name of agents) {
+    const bootstrap = bootstrapMap[name];
+    const source = path.join(cwd, bootstrap.source);
+    const target = path.join(cwd, bootstrap.target);
+
+    if (!await pathExists(source)) {
+      console.log(`[FAIL] ${name}: missing ${bootstrap.source}`);
+      continue;
+    }
+
+    const dirResult = await ensureDir(path.dirname(target));
+    if (dirResult.created) {
+      manifestEntries.push(await manifestEntry(cwd, dirResult.path, {
+        type: 'dir',
+        category: 'bootstrap',
+        source: `bootstrap:${name}`
+      }));
+    }
+
+    const result = await copyFileSafe(source, target, { force });
+    console.log(`${name}: ${result.copied ? 'copied ' : 'skipped'} ${relativeTo(cwd, result.path)}`);
+    if (result.copied) {
+      manifestEntries.push(await manifestEntry(cwd, result.path, {
+        type: 'file',
+        category: 'bootstrap',
+        source: `bootstrap:${name}`
+      }));
+    }
+  }
+
+  const manifest = await recordManifestEntries(cwd, manifestEntries);
+  if (manifest) console.log(`updated ${relativeTo(cwd, manifestPath(cwd))}`);
+
+  console.log('\nNext: open Claude Code or OpenCode in this repository and run:');
+  console.log('/qa-init');
+  console.log('\nAdvanced example for a manual-only QA setup:');
+  console.log('/qa-init --preset manual-only --adapters claude,opencode');
+}
+
+main().catch((error) => {
+  console.error(error);
+  process.exit(1);
+});

package/.qa-ai/scripts/clean.mjs

@@ -0,0 +1,243 @@
+#!/usr/bin/env node
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import {
+  hashFile,
+  loadInitManifest,
+  manifestRelativePath,
+  parseArgs,
+  pathExists,
+  resolveInsideCwd,
+  saveInitManifest,
+  logHeader
+} from './lib/utils.mjs';
+
+const cwd = process.cwd();
+const args = parseArgs(process.argv);
+const force = Boolean(args.force);
+const includeModified = Boolean(args['include-modified']);
+const pruneState = Boolean(args['prune-state']);
+
+function printHelp() {
+  console.log(`Usage: node .qa-ai/scripts/clean.mjs [options]
+
+Default behavior is a dry-run. Nothing is deleted unless --force is passed.
+
+Options:
+  --generated         Include generated non-adapter files and directories from init
+  --adapters          Include generated adapter files and adapter directories
+  --empty-dirs        Include tracked empty directories
+  --all               Include all tracked entries (default when no category is passed)
+  --force             Execute the cleanup plan
+  --include-modified  Also delete tracked files whose content changed since init
+  --prune-state       Remove .qa-ai/state/init-manifest.json when no entries remain
+  --help              Show this help
+
+Examples:
+  node .qa-ai/scripts/clean.mjs
+  node .qa-ai/scripts/clean.mjs --generated --force
+  node .qa-ai/scripts/clean.mjs --adapters --empty-dirs --force
+`);
+}
+
+function entryKey(entry) {
+  return `${entry.type}:${entry.path}`;
+}
+
+function selectedCategories() {
+  const explicit = Boolean(args.generated || args.adapters || args['empty-dirs'] || args.all);
+  return {
+    all: Boolean(args.all || !explicit),
+    generated: Boolean(args.generated),
+    adapters: Boolean(args.adapters),
+    emptyDirs: Boolean(args['empty-dirs'])
+  };
+}
+
+function shouldSelect(entry, categories) {
+  if (categories.all) return true;
+  if (entry.type === 'dir') {
+    if (categories.emptyDirs) return true;
+    if (categories.generated && entry.category === 'generated') return true;
+    if (categories.adapters && entry.category === 'adapter') return true;
+    return false;
+  }
+  if (categories.generated && entry.category === 'generated') return true;
+  if (categories.adapters && entry.category === 'adapter') return true;
+  return false;
+}
+
+function safeTarget(entry) {
+  if (!entry.path || path.isAbsolute(entry.path) || entry.path === '.') {
+    return { ok: false, reason: 'unsafe manifest path' };
+  }
+  if (entry.path === manifestRelativePath) {
+    return { ok: false, reason: 'manifest state is handled separately' };
+  }
+
+  const target = resolveInsideCwd(cwd, entry.path);
+  if (!target.inside || target.resolved === path.resolve(cwd)) {
+    return { ok: false, reason: 'path resolves outside repository root' };
+  }
+  return { ok: true, path: target.resolved };
+}
+
+async function planFile(entry) {
+  const target = safeTarget(entry);
+  if (!target.ok) return { entry, action: 'skip', reason: target.reason };
+  if (!await pathExists(target.path)) return { entry, action: 'missing', removeFromManifest: true };
+
+  const stat = await fs.lstat(target.path);
+  if (!stat.isFile()) return { entry, action: 'skip', reason: 'not a regular file' };
+
+  if (entry.sha256) {
+    const currentHash = await hashFile(target.path);
+    if (currentHash !== entry.sha256 && !includeModified) {
+      return { entry, action: 'skip', reason: 'modified since init' };
+    }
+  }
+
+  return {
+    entry,
+    action: force ? 'delete-file' : 'would-delete-file',
+    target: target.path,
+    removeFromManifest: force
+  };
+}
+
+async function planDirectory(entry, removalPaths) {
+  const target = safeTarget(entry);
+  if (!target.ok) return { entry, action: 'skip', reason: target.reason };
+  if (!await pathExists(target.path)) return { entry, action: 'missing', removeFromManifest: true };
+
+  const stat = await fs.lstat(target.path);
+  if (!stat.isDirectory()) return { entry, action: 'skip', reason: 'not a directory' };
+
+  const children = await fs.readdir(target.path);
+  const removableAfterTrackedChildren = children.every((child) => {
+    const childPath = `${entry.path.replace(/\/$/, '')}/${child}`;
+    return removalPaths.has(childPath);
+  });
+  if (children.length > 0 && !removableAfterTrackedChildren) {
+    return { entry, action: 'skip', reason: 'directory is not empty' };
+  }
+
+  return {
+    entry,
+    action: force ? 'remove-dir' : 'would-remove-dir',
+    target: target.path,
+    removeFromManifest: force
+  };
+}
+
+async function planEntries(entries) {
+  const files = entries.filter((entry) => entry.type === 'file');
+  const dirs = entries
+    .filter((entry) => entry.type === 'dir')
+    .sort((a, b) => b.path.length - a.path.length);
+  const planned = [];
+  const removalPaths = new Set();
+
+  for (const entry of files) {
+    const item = await planFile(entry);
+    planned.push(item);
+    if (item.removeFromManifest || item.action === 'would-delete-file') removalPaths.add(entry.path);
+  }
+  for (const entry of dirs) {
+    const item = await planDirectory(entry, removalPaths);
+    planned.push(item);
+    if (item.removeFromManifest || item.action === 'would-remove-dir') removalPaths.add(entry.path);
+  }
+
+  return planned;
+}
+
+async function executePlan(plan) {
+  for (const item of plan) {
+    if (item.action === 'delete-file') await fs.rm(item.target, { force: false });
+    if (item.action === 'remove-dir') await fs.rmdir(item.target);
+  }
+}
+
+function printPlan(plan) {
+  for (const item of plan) {
+    const label = item.action.toUpperCase().replaceAll('-', ' ');
+    const suffix = item.reason ? ` (${item.reason})` : '';
+    console.log(`[${label}] ${item.entry.path}${suffix}`);
+  }
+}
+
+function summarize(plan) {
+  const counts = new Map();
+  for (const item of plan) counts.set(item.action, (counts.get(item.action) || 0) + 1);
+  return [...counts.entries()]
+    .sort(([a], [b]) => a.localeCompare(b))
+    .map(([action, count]) => `${action}: ${count}`)
+    .join(', ');
+}
+
+async function pruneManifestState(manifestPath) {
+  if (!pruneState) return;
+  await fs.rm(manifestPath, { force: true });
+  try {
+    await fs.rmdir(path.dirname(manifestPath));
+  } catch {
+    // Keep the state directory when other files are present.
+  }
+}
+
+async function main() {
+  if (args.help) {
+    printHelp();
+    return;
+  }
+
+  logHeader('QA FlowKit clean');
+  const { exists, path: manifestPath, data: manifest } = await loadInitManifest(cwd);
+  if (!exists) {
+    console.log(`No init manifest found at ${manifestRelativePath}. Run init before clean can safely remove generated files.`);
+    return;
+  }
+
+  const categories = selectedCategories();
+  const selected = manifest.entries.filter((entry) => shouldSelect(entry, categories));
+  if (selected.length === 0) {
+    console.log('No matching manifest entries for the selected cleanup options.');
+    return;
+  }
+
+  console.log(force ? 'Mode: execute cleanup' : 'Mode: dry-run only');
+  if (includeModified) console.log('Modified tracked files are included because --include-modified was passed.');
+  console.log('');
+
+  const plan = await planEntries(selected);
+  printPlan(plan);
+  console.log(`\nSummary: ${summarize(plan) || 'nothing to do'}`);
+
+  if (!force) {
+    console.log('\nNo files were deleted. Re-run with --force to execute this plan.');
+    return;
+  }
+
+  await executePlan(plan);
+
+  const removeKeys = new Set(plan.filter((item) => item.removeFromManifest).map((item) => entryKey(item.entry)));
+  const remainingEntries = manifest.entries.filter((entry) => !removeKeys.has(entryKey(entry)));
+
+  if (remainingEntries.length === 0 && pruneState) {
+    await pruneManifestState(manifestPath);
+    console.log(`\nRemoved ${manifestRelativePath}.`);
+    return;
+  }
+
+  await saveInitManifest(cwd, {
+    ...manifest,
+    entries: remainingEntries
+  });
+  console.log(`\nUpdated ${manifestRelativePath}.`);
+}
+
+main().catch((error) => {
+  console.error(error);
+  process.exit(1);
+});