@toolstackhq/create-qa-patterns 1.0.14 → 1.0.15

package/lib/metadata.js

@@ -0,0 +1,329 @@
+const crypto = require('node:crypto');
+const fs = require('node:fs');
+const path = require('node:path');
+
+function sha256(content) {
+  return crypto.createHash('sha256').update(content).digest('hex');
+}
+
+function normalizePath(value) {
+  return value.split(path.sep).join('/');
+}
+
+function pathMatchesPattern(relativePath, pattern) {
+  if (pattern.endsWith('/**')) {
+    const prefix = pattern.slice(0, -3);
+    return relativePath === prefix || relativePath.startsWith(`${prefix}/`);
+  }
+
+  return relativePath === pattern;
+}
+
+function collectRelativeFiles(rootDirectory) {
+  const results = [];
+
+  function visit(currentDirectory) {
+    const entries = fs.readdirSync(currentDirectory, { withFileTypes: true });
+
+    for (const entry of entries) {
+      const absolutePath = path.join(currentDirectory, entry.name);
+      const relativePath = normalizePath(
+        path.relative(rootDirectory, absolutePath)
+      );
+
+      if (entry.isDirectory()) {
+        visit(absolutePath);
+      } else {
+        results.push(relativePath);
+      }
+    }
+  }
+
+  visit(rootDirectory);
+
+  return results.sort();
+}
+
+function isManagedFile(template, relativePath, managedPatterns) {
+  const patterns = [
+    ...managedPatterns.common,
+    ...(managedPatterns[template.id] || [])
+  ];
+  return patterns.some((pattern) => pathMatchesPattern(relativePath, pattern));
+}
+
+function transformTemplateFile(
+  relativePath,
+  content,
+  targetDirectory,
+  template,
+  toPackageName
+) {
+  const packageName = toPackageName(targetDirectory, template);
+
+  if (relativePath === 'package.json') {
+    const pkg = JSON.parse(content);
+    return `${JSON.stringify({ ...pkg, name: packageName }, null, 2)}\n`;
+  }
+
+  if (relativePath === 'package-lock.json') {
+    const lock = JSON.parse(content);
+    return `${JSON.stringify(
+      {
+        ...lock,
+        name: packageName,
+        packages: lock.packages
+          ? {
+              ...lock.packages,
+              '': {
+                ...lock.packages[''],
+                name: packageName
+              }
+            }
+          : lock.packages
+      },
+      null,
+      2
+    )}\n`;
+  }
+
+  return content;
+}
+
+function renderTemplateFile(template, relativePath, targetDirectory, options) {
+  const { defaultGitignore, getTemplateDirectory, toPackageName } = options;
+
+  if (relativePath === '.gitignore') {
+    const gitignorePath = path.join(
+      getTemplateDirectory(template.id),
+      '.gitignore'
+    );
+    const gitignoreContent = fs.existsSync(gitignorePath)
+      ? fs.readFileSync(gitignorePath, 'utf8')
+      : defaultGitignore;
+    return transformTemplateFile(
+      relativePath,
+      gitignoreContent,
+      targetDirectory,
+      template,
+      toPackageName
+    );
+  }
+
+  const sourcePath = path.join(getTemplateDirectory(template.id), relativePath);
+  const content = fs.readFileSync(sourcePath, 'utf8');
+  return transformTemplateFile(
+    relativePath,
+    content,
+    targetDirectory,
+    template,
+    toPackageName
+  );
+}
+
+function getManagedRelativePaths(template, options) {
+  const { getTemplateDirectory, managedPatterns, metadataFilename } = options;
+  const templateDirectory = getTemplateDirectory(template.id);
+  const templateFiles = collectRelativeFiles(templateDirectory).filter(
+    (relativePath) => isManagedFile(template, relativePath, managedPatterns)
+  );
+  const managedFiles = new Set(templateFiles);
+  managedFiles.add('.gitignore');
+  managedFiles.delete(metadataFilename);
+  return [...managedFiles].sort();
+}
+
+function getMetadataPath(targetDirectory, metadataFilename) {
+  return path.join(targetDirectory, metadataFilename);
+}
+
+function buildProjectMetadata(template, targetDirectory, options) {
+  const { cliPackageVersion, metadataFilename } = options;
+  const managedFiles = {};
+
+  for (const relativePath of getManagedRelativePaths(template, options)) {
+    const absolutePath = path.join(targetDirectory, relativePath);
+    if (!fs.existsSync(absolutePath)) {
+      continue;
+    }
+
+    managedFiles[relativePath] = {
+      baselineHash: sha256(fs.readFileSync(absolutePath, 'utf8'))
+    };
+  }
+
+  return {
+    schemaVersion: 1,
+    template: template.id,
+    templateVersion: cliPackageVersion,
+    packageName: options.toPackageName(targetDirectory, template),
+    generatedAt: new Date().toISOString(),
+    managedFiles,
+    metadataFilename
+  };
+}
+
+function writeProjectMetadata(
+  template,
+  targetDirectory,
+  existingMetadata,
+  options
+) {
+  const nextMetadata = buildProjectMetadata(template, targetDirectory, options);
+
+  if (existingMetadata) {
+    nextMetadata.generatedAt =
+      existingMetadata.generatedAt || nextMetadata.generatedAt;
+    nextMetadata.templateVersion =
+      existingMetadata.templateVersion || nextMetadata.templateVersion;
+  }
+
+  fs.writeFileSync(
+    getMetadataPath(targetDirectory, options.metadataFilename),
+    `${JSON.stringify(nextMetadata, null, 2)}\n`,
+    'utf8'
+  );
+  return nextMetadata;
+}
+
+function readProjectMetadata(targetDirectory, metadataFilename) {
+  const metadataPath = getMetadataPath(targetDirectory, metadataFilename);
+
+  if (!fs.existsSync(metadataPath)) {
+    throw new Error(`No ${metadataFilename} file found in ${targetDirectory}.`);
+  }
+
+  return JSON.parse(fs.readFileSync(metadataPath, 'utf8'));
+}
+
+function detectTemplateFromProject(targetDirectory, metadataFilename) {
+  const metadataPath = getMetadataPath(targetDirectory, metadataFilename);
+  if (fs.existsSync(metadataPath)) {
+    const metadata = JSON.parse(fs.readFileSync(metadataPath, 'utf8'));
+    return metadata.template;
+  }
+
+  if (fs.existsSync(path.join(targetDirectory, 'playwright.config.ts'))) {
+    return 'playwright-template';
+  }
+
+  if (fs.existsSync(path.join(targetDirectory, 'cypress.config.ts'))) {
+    return 'cypress-template';
+  }
+
+  if (fs.existsSync(path.join(targetDirectory, 'wdio.conf.ts'))) {
+    return 'wdio-template';
+  }
+
+  throw new Error(`Could not detect the template used for ${targetDirectory}.`);
+}
+
+function analyzeUpgrade(template, targetDirectory, metadata, options) {
+  const managedPaths = getManagedRelativePaths(template, options);
+  const results = [];
+
+  for (const relativePath of managedPaths) {
+    const absolutePath = path.join(targetDirectory, relativePath);
+    const latestContent = renderTemplateFile(
+      template,
+      relativePath,
+      targetDirectory,
+      options
+    );
+    const latestHash = sha256(latestContent);
+    const baselineHash =
+      metadata.managedFiles?.[relativePath]?.baselineHash || null;
+    const currentExists = fs.existsSync(absolutePath);
+    const currentHash = currentExists
+      ? sha256(fs.readFileSync(absolutePath, 'utf8'))
+      : null;
+
+    let status = 'up-to-date';
+
+    if (!baselineHash) {
+      if (!currentExists) {
+        status = 'new-file';
+      } else if (currentHash === latestHash) {
+        status = 'new-file';
+      } else {
+        status = 'conflict';
+      }
+    } else if (!currentExists) {
+      status = 'conflict';
+    } else if (currentHash === latestHash) {
+      status = 'up-to-date';
+    } else if (currentHash === baselineHash) {
+      status = 'safe-update';
+    } else {
+      status = 'conflict';
+    }
+
+    results.push({
+      relativePath,
+      status,
+      latestContent,
+      latestHash,
+      currentHash,
+      baselineHash,
+      currentExists
+    });
+  }
+
+  return results;
+}
+
+function applySafeUpdates(targetDirectory, metadata, results, options) {
+  const nextMetadata = {
+    ...metadata,
+    managedFiles: {
+      ...metadata.managedFiles
+    }
+  };
+
+  let appliedCount = 0;
+
+  for (const entry of results) {
+    if (!['safe-update', 'new-file'].includes(entry.status)) {
+      continue;
+    }
+
+    const absolutePath = path.join(targetDirectory, entry.relativePath);
+    fs.mkdirSync(path.dirname(absolutePath), { recursive: true });
+    fs.writeFileSync(absolutePath, entry.latestContent, 'utf8');
+    nextMetadata.managedFiles[entry.relativePath] = {
+      baselineHash: entry.latestHash
+    };
+    appliedCount += 1;
+  }
+
+  const remainingConflicts = results.filter(
+    (entry) => entry.status === 'conflict'
+  ).length;
+  if (remainingConflicts === 0) {
+    nextMetadata.templateVersion = options.cliPackageVersion;
+  }
+
+  fs.writeFileSync(
+    getMetadataPath(targetDirectory, options.metadataFilename),
+    `${JSON.stringify(nextMetadata, null, 2)}\n`,
+    'utf8'
+  );
+
+  return {
+    appliedCount,
+    remainingConflicts
+  };
+}
+
+module.exports = {
+  analyzeUpgrade,
+  applySafeUpdates,
+  buildProjectMetadata,
+  collectRelativeFiles,
+  detectTemplateFromProject,
+  getManagedRelativePaths,
+  readProjectMetadata,
+  renderTemplateFile,
+  sha256,
+  writeProjectMetadata
+};

package/lib/output.js

@@ -0,0 +1,326 @@
+const { MIN_NODE_VERSION } = require('./constants');
+
+function createColors(processObject = process) {
+  const colorEnabled =
+    Boolean(processObject.stdout?.isTTY) && !('NO_COLOR' in processObject.env);
+
+  function style(text, ...codes) {
+    if (!colorEnabled) {
+      return text;
+    }
+
+    return `\u001b[${codes.join(';')}m${text}\u001b[0m`;
+  }
+
+  return {
+    bold(text) {
+      return style(text, 1);
+    },
+    dim(text) {
+      return style(text, 2);
+    },
+    cyan(text) {
+      return style(text, 36);
+    },
+    green(text) {
+      return style(text, 32);
+    },
+    yellow(text) {
+      return style(text, 33);
+    },
+    red(text) {
+      return style(text, 31);
+    }
+  };
+}
+
+function parseNodeVersion(version) {
+  const normalized = version.replace(/^v/, '');
+  const [major = '0', minor = '0', patch = '0'] = normalized.split('.');
+
+  return {
+    major: Number.parseInt(major, 10),
+    minor: Number.parseInt(minor, 10),
+    patch: Number.parseInt(patch, 10)
+  };
+}
+
+function isNodeVersionSupported(version) {
+  if (version.major !== MIN_NODE_VERSION.major) {
+    return version.major > MIN_NODE_VERSION.major;
+  }
+
+  if (version.minor !== MIN_NODE_VERSION.minor) {
+    return version.minor > MIN_NODE_VERSION.minor;
+  }
+
+  return version.patch >= MIN_NODE_VERSION.patch;
+}
+
+function assertSupportedNodeVersion(processVersion = process.version) {
+  const currentVersion = parseNodeVersion(processVersion);
+
+  if (!isNodeVersionSupported(currentVersion)) {
+    throw new Error(
+      `Node ${MIN_NODE_VERSION.major}.${MIN_NODE_VERSION.minor}.${MIN_NODE_VERSION.patch}+ is required. Current version: ${processVersion}`
+    );
+  }
+}
+
+function printHelp(templates, colors, defaultTemplate) {
+  const supportedTemplates = templates
+    .map(
+      (template) =>
+        `  ${template.id}${template.aliases.length > 0 ? ` (${template.aliases.join(', ')})` : ''}`
+    )
+    .join('\n');
+
+  process.stdout.write(`${colors.bold('create-qa-patterns')}
+
+Usage:
+  create-qa-patterns
+  create-qa-patterns <target-directory>
+  create-qa-patterns <template> [target-directory]
+  create-qa-patterns --template <template> [target-directory]
+  create-qa-patterns upgrade check [target-directory]
+  create-qa-patterns upgrade apply --safe [target-directory]
+
+Options:
+  --yes          Accept all post-generate prompts
+  --no-install   Skip npm install
+  --no-setup     Skip template-specific setup such as Playwright browser install
+  --no-test      Skip npm test
+  --template     Explicitly choose a template without using positional arguments
+  --safe         Required with upgrade apply; only updates unchanged managed files
+
+Interactive mode:
+  When run without an explicit template, the CLI shows an interactive template picker.
+  Default template in non-interactive mode: ${defaultTemplate}
+
+Supported templates:
+${supportedTemplates}
+`);
+}
+
+function printPrerequisiteWarnings(prerequisites, colors) {
+  if (!prerequisites.npm) {
+    process.stdout.write(
+      `${colors.yellow('Warning:')} npm was not found. Automated install and test steps will be unavailable.\n`
+    );
+  }
+
+  if (!prerequisites.npx) {
+    process.stdout.write(
+      `${colors.yellow('Warning:')} npx was not found. Template setup steps that depend on npx will be unavailable.\n`
+    );
+  }
+
+  if (!prerequisites.docker) {
+    process.stdout.write(
+      `${colors.yellow('Warning:')} docker was not found. Docker-based template flows will not run until Docker is installed.\n`
+    );
+  }
+
+  if (!prerequisites.git) {
+    process.stdout.write(
+      `${colors.yellow('Warning:')} git was not found. The generated project cannot be initialized as a repository automatically.\n`
+    );
+  }
+
+  if (
+    !prerequisites.npm ||
+    !prerequisites.npx ||
+    !prerequisites.docker ||
+    !prerequisites.git
+  ) {
+    process.stdout.write('\n');
+  }
+}
+
+function printPlaywrightInstallRecovery(targetDirectory, colors) {
+  process.stdout.write(`
+${colors.yellow('Playwright browser installation did not complete.')}
+
+Common cause:
+  Missing OS packages required to run Playwright browsers.
+
+Recommended next steps:
+  cd ${targetDirectory}
+  sudo npx playwright install-deps
+  npx playwright install
+
+If you already know the missing package name, install it with your system package manager and then rerun:
+  npx playwright install
+
+The template was generated successfully. You can complete browser setup later.
+
+`);
+}
+
+function printSuccess(
+  template,
+  targetDirectory,
+  generatedInCurrentDirectory,
+  colors
+) {
+  process.stdout.write(`\n${colors.green(colors.bold('Success'))}
+Generated ${template.label} in ${targetDirectory}
+\n`);
+
+  if (!generatedInCurrentDirectory) {
+    process.stdout.write(
+      `${colors.cyan('Your shell stays in the original directory. To work in the generated project, run:')}\n  cd ${targetDirectory}\n\n`
+    );
+  }
+}
+
+function formatStatus(status, colors) {
+  switch (status) {
+    case 'completed':
+      return colors.green('completed');
+    case 'skipped':
+      return colors.dim('skipped');
+    case 'unavailable':
+      return colors.yellow('unavailable');
+    case 'manual-recovery':
+      return colors.yellow('manual recovery required');
+    default:
+      return colors.dim('not run');
+  }
+}
+
+function formatUpgradeStatus(status, colors) {
+  switch (status) {
+    case 'safe-update':
+      return colors.green('safe update available');
+    case 'new-file':
+      return colors.green('new managed file available');
+    case 'conflict':
+      return colors.yellow('manual review required');
+    default:
+      return colors.dim('up to date');
+  }
+}
+
+function printUpgradeReport(
+  targetDirectory,
+  metadata,
+  results,
+  cliPackageVersion,
+  colors
+) {
+  const safeCount = results.filter(
+    (entry) => entry.status === 'safe-update'
+  ).length;
+  const newCount = results.filter(
+    (entry) => entry.status === 'new-file'
+  ).length;
+  const conflictCount = results.filter(
+    (entry) => entry.status === 'conflict'
+  ).length;
+
+  process.stdout.write(`\n${colors.bold('Upgrade check')}\n`);
+  process.stdout.write(`  Target: ${targetDirectory}\n`);
+  process.stdout.write(`  Template: ${metadata.template}\n`);
+  process.stdout.write(
+    `  Current baseline version: ${metadata.templateVersion}\n`
+  );
+  process.stdout.write(`  CLI template version: ${cliPackageVersion}\n`);
+  process.stdout.write(`  Safe updates: ${safeCount}\n`);
+  process.stdout.write(`  New managed files: ${newCount}\n`);
+  process.stdout.write(`  Conflicts: ${conflictCount}\n\n`);
+
+  for (const entry of results) {
+    if (entry.status === 'up-to-date') {
+      continue;
+    }
+
+    process.stdout.write(
+      `  ${entry.relativePath}: ${formatUpgradeStatus(entry.status, colors)}\n`
+    );
+  }
+
+  if (safeCount === 0 && newCount === 0 && conflictCount === 0) {
+    process.stdout.write(
+      `${colors.green('Everything already matches the current managed template files.')}\n`
+    );
+  }
+
+  process.stdout.write('\n');
+}
+
+function printSummary(summary, colors) {
+  process.stdout.write(`\n${colors.bold('Summary')}\n`);
+  process.stdout.write(`  Template: ${summary.template.id}\n`);
+  process.stdout.write(`  Target: ${summary.targetDirectory}\n`);
+  process.stdout.write(
+    `  Git repository: ${formatStatus(summary.gitInit, colors)}\n`
+  );
+  process.stdout.write(
+    `  Demo apps: ${summary.demoAppsManagedByTemplate ? 'bundled and auto-started in dev when using default local URLs' : 'external application required'}\n`
+  );
+  if (summary.localCredentials) {
+    process.stdout.write(
+      `  Local credentials: ${summary.localCredentials.username} / ${summary.localCredentials.password}\n`
+    );
+  }
+  process.stdout.write(
+    `  npm install: ${formatStatus(summary.npmInstall, colors)}\n`
+  );
+  if (summary.template.setup) {
+    process.stdout.write(
+      `  ${summary.template.setup.summaryLabel}: ${formatStatus(summary.extraSetup, colors)}\n`
+    );
+  }
+  process.stdout.write(
+    `  npm test: ${formatStatus(summary.testRun, colors)}\n`
+  );
+}
+
+function printNextSteps(summary, colors) {
+  const steps = [];
+
+  if (!summary.generatedInCurrentDirectory) {
+    steps.push(`cd ${summary.targetRelativePath}`);
+  }
+
+  if (summary.npmInstall !== 'completed') {
+    steps.push('npm install');
+  }
+
+  if (summary.template.setup && summary.extraSetup !== 'completed') {
+    steps.push(summary.template.setup.nextStep);
+  }
+
+  if (summary.testRun !== 'completed') {
+    steps.push('npm test');
+  }
+
+  if (steps.length > 0) {
+    process.stdout.write(`${colors.cyan('Next steps:')}\n`);
+    for (const step of steps) {
+      process.stdout.write(`  ${step}\n`);
+    }
+    process.stdout.write('\n');
+  }
+
+  if (summary.demoAppsManagedByTemplate) {
+    process.stdout.write(
+      `${colors.yellow(colors.bold('Demo apps included:'))} sample tests run against bundled demo apps in local ${colors.bold('dev')}. Delete or replace ${colors.bold('demo-apps/')} if you do not want them.\n`
+    );
+  }
+
+  process.stdout.write(`${colors.green(colors.bold('Happy testing.'))}\n`);
+}
+
+module.exports = {
+  assertSupportedNodeVersion,
+  createColors,
+  printHelp,
+  printNextSteps,
+  printPlaywrightInstallRecovery,
+  printPrerequisiteWarnings,
+  printSuccess,
+  printSummary,
+  printUpgradeReport
+};

package/lib/prereqs.js

@@ -0,0 +1,72 @@
+const { spawn, spawnSync } = require('node:child_process');
+const path = require('node:path');
+
+function getCommandName(base) {
+  if (process.platform === 'win32') {
+    return `${base}.cmd`;
+  }
+
+  return base;
+}
+
+function commandExists(command) {
+  const result = spawnSync(getCommandName(command), ['--version'], {
+    stdio: 'ignore'
+  });
+
+  return !result.error && result.status === 0;
+}
+
+function collectPrerequisites() {
+  return {
+    npm: commandExists('npm'),
+    npx: commandExists('npx'),
+    docker: commandExists('docker'),
+    git: commandExists('git')
+  };
+}
+
+function initializeGitRepository(targetDirectory) {
+  if (require('node:fs').existsSync(path.join(targetDirectory, '.git'))) {
+    return;
+  }
+
+  const result = spawnSync(getCommandName('git'), ['init'], {
+    cwd: targetDirectory,
+    encoding: 'utf8'
+  });
+
+  if (result.status !== 0) {
+    throw new Error(result.stderr || 'git init failed.');
+  }
+}
+
+function runCommand(command, args, cwd) {
+  return new Promise((resolve, reject) => {
+    const child = spawn(getCommandName(command), args, {
+      cwd,
+      stdio: 'inherit'
+    });
+
+    child.on('close', (code) => {
+      if (code === 0) {
+        resolve();
+        return;
+      }
+
+      reject(
+        new Error(`${command} ${args.join(' ')} exited with code ${code}`)
+      );
+    });
+
+    child.on('error', reject);
+  });
+}
+
+module.exports = {
+  collectPrerequisites,
+  commandExists,
+  getCommandName,
+  initializeGitRepository,
+  runCommand
+};