@toolstackhq/create-qa-patterns 1.0.1 → 1.0.3

package/README.md

@@ -29,3 +29,24 @@ create-qa-patterns playwright-template my-project
 ## Supported templates
 
 - `playwright-template`
+
+## Interactive flow
+
+When run in a terminal, the CLI shows:
+
+- a template picker with keyboard selection
+- short template descriptions
+- scaffold progress while files are generated
+- optional post-generate actions for:
+  - `npm install`
+  - `npx playwright install`
+  - `npm test`
+
+## Prerequisite checks
+
+The CLI checks:
+
+- required Node.js version
+- `npm` availability for install and test actions
+- `npx` availability for Playwright browser installation
+- `docker` availability and warns if it is missing

package/index.js

@@ -2,8 +2,15 @@
 
 const fs = require("node:fs");
 const path = require("node:path");
+const readline = require("node:readline");
+const { spawn, spawnSync } = require("node:child_process");
 
 const DEFAULT_TEMPLATE = "playwright-template";
+const MIN_NODE_VERSION = {
+  major: 18,
+  minor: 18,
+  patch: 0
+};
 const DEFAULT_GITIGNORE = `node_modules/
 
 .env
@@ -16,11 +23,22 @@ allure-report/
 test-results/
 playwright-report/
 `;
-const TEMPLATE_ALIASES = new Map([
-  ["playwright", DEFAULT_TEMPLATE],
-  ["pw", DEFAULT_TEMPLATE],
-  [DEFAULT_TEMPLATE, DEFAULT_TEMPLATE]
-]);
+
+const TEMPLATES = [
+  {
+    id: DEFAULT_TEMPLATE,
+    aliases: ["playwright", "pw"],
+    label: "Playwright Template",
+    description: "TypeScript starter with page objects, fixtures, multi-environment config, reporting, linting, CI and Docker."
+  }
+];
+
+const TEMPLATE_ALIASES = new Map(
+  TEMPLATES.flatMap((template) => [
+    [template.id, template.id],
+    ...template.aliases.map((alias) => [alias, template.id])
+  ])
+);
 
 function printHelp() {
   process.stdout.write(`create-qa-patterns
@@ -30,6 +48,9 @@ Usage:
   create-qa-patterns <target-directory>
   create-qa-patterns <template> [target-directory]
 
+Interactive mode:
+  When run without an explicit template, the CLI shows an interactive template picker.
+
 Supported templates:
   playwright-template
   playwright
@@ -37,11 +58,209 @@ Supported templates:
 `);
 }
 
+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() {
+  const currentVersion = parseNodeVersion(process.version);
+
+  if (!isNodeVersionSupported(currentVersion)) {
+    throw new Error(
+      `Node ${MIN_NODE_VERSION.major}.${MIN_NODE_VERSION.minor}.${MIN_NODE_VERSION.patch}+ is required. Current version: ${process.version}`
+    );
+  }
+}
+
 function resolveTemplate(value) {
   return TEMPLATE_ALIASES.get(value);
 }
 
-function resolveScaffoldArgs(args) {
+function getTemplate(templateId) {
+  return TEMPLATES.find((template) => template.id === templateId);
+}
+
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+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")
+  };
+}
+
+function printPrerequisiteWarnings(prerequisites) {
+  if (!prerequisites.npm) {
+    process.stdout.write("Warning: npm was not found. Automated install and test steps will be unavailable.\n");
+  }
+
+  if (!prerequisites.npx) {
+    process.stdout.write("Warning: npx was not found. Playwright browser installation will be unavailable.\n");
+  }
+
+  if (!prerequisites.docker) {
+    process.stdout.write("Warning: docker was not found. Docker-based template flows will not run until Docker is installed.\n");
+  }
+
+  if (!prerequisites.npm || !prerequisites.npx || !prerequisites.docker) {
+    process.stdout.write("\n");
+  }
+}
+
+function createLineInterface() {
+  return readline.createInterface({
+    input: process.stdin,
+    output: process.stdout
+  });
+}
+
+function askQuestion(prompt) {
+  const lineInterface = createLineInterface();
+
+  return new Promise((resolve) => {
+    lineInterface.question(prompt, (answer) => {
+      lineInterface.close();
+      resolve(answer.trim());
+    });
+  });
+}
+
+async function askYesNo(prompt, defaultValue = true) {
+  const suffix = defaultValue ? " [Y/n] " : " [y/N] ";
+
+  while (true) {
+    const answer = (await askQuestion(`${prompt}${suffix}`)).toLowerCase();
+
+    if (!answer) {
+      return defaultValue;
+    }
+
+    if (["y", "yes"].includes(answer)) {
+      return true;
+    }
+
+    if (["n", "no"].includes(answer)) {
+      return false;
+    }
+
+    process.stdout.write("Please answer yes or no.\n");
+  }
+}
+
+async function selectTemplateInteractively() {
+  if (!process.stdin.isTTY || !process.stdout.isTTY) {
+    return DEFAULT_TEMPLATE;
+  }
+
+  readline.emitKeypressEvents(process.stdin);
+
+  if (typeof process.stdin.setRawMode === "function") {
+    process.stdin.setRawMode(true);
+  }
+
+  let selectedIndex = 0;
+  let renderedLines = 0;
+
+  const render = () => {
+    if (renderedLines > 0) {
+      readline.moveCursor(process.stdout, 0, -renderedLines);
+      readline.clearScreenDown(process.stdout);
+    }
+
+    const lines = [
+      "Select a template",
+      "Use ↑/↓ to choose and press Enter to continue.",
+      ""
+    ];
+
+    for (let index = 0; index < TEMPLATES.length; index += 1) {
+      const template = TEMPLATES[index];
+      const marker = index === selectedIndex ? ">" : " ";
+      lines.push(`${marker} ${template.label}`);
+      lines.push(`  ${template.description}`);
+      lines.push("");
+    }
+
+    renderedLines = lines.length;
+    process.stdout.write(`${lines.join("\n")}\n`);
+  };
+
+  render();
+
+  return new Promise((resolve) => {
+    const handleKeypress = (_, key) => {
+      if (!key) {
+        return;
+      }
+
+      if (key.name === "up") {
+        selectedIndex = (selectedIndex - 1 + TEMPLATES.length) % TEMPLATES.length;
+        render();
+        return;
+      }
+
+      if (key.name === "down") {
+        selectedIndex = (selectedIndex + 1) % TEMPLATES.length;
+        render();
+        return;
+      }
+
+      if (key.name === "return") {
+        process.stdin.off("keypress", handleKeypress);
+        if (typeof process.stdin.setRawMode === "function") {
+          process.stdin.setRawMode(false);
+        }
+        readline.clearScreenDown(process.stdout);
+        process.stdout.write(`Selected: ${TEMPLATES[selectedIndex].label}\n\n`);
+        resolve(TEMPLATES[selectedIndex].id);
+        return;
+      }
+
+      if (key.ctrl && key.name === "c") {
+        process.stdin.off("keypress", handleKeypress);
+        if (typeof process.stdin.setRawMode === "function") {
+          process.stdin.setRawMode(false);
+        }
+        process.stdout.write("\n");
+        process.exit(1);
+      }
+    };
+
+    process.stdin.on("keypress", handleKeypress);
+  });
+}
+
+function resolveNonInteractiveArgs(args) {
   if (args.length === 0) {
     return {
       templateName: DEFAULT_TEMPLATE,
@@ -52,6 +271,7 @@ function resolveScaffoldArgs(args) {
 
   if (args.length === 1) {
     const templateName = resolveTemplate(args[0]);
+
     if (templateName) {
       return {
         templateName,
@@ -69,6 +289,7 @@ function resolveScaffoldArgs(args) {
 
   if (args.length === 2) {
     const templateName = resolveTemplate(args[0]);
+
     if (!templateName) {
       throw new Error(`Unsupported template "${args[0]}". Use "playwright-template".`);
     }
@@ -83,6 +304,30 @@ function resolveScaffoldArgs(args) {
   throw new Error("Too many arguments. Run `create-qa-patterns --help` for usage.");
 }
 
+async function resolveScaffoldArgs(args) {
+  const explicitTemplate = args[0] && resolveTemplate(args[0]);
+
+  if (explicitTemplate) {
+    return resolveNonInteractiveArgs(args);
+  }
+
+  if (!process.stdin.isTTY || !process.stdout.isTTY) {
+    return resolveNonInteractiveArgs(args);
+  }
+
+  const templateName = await selectTemplateInteractively();
+  const defaultTarget = args[0] ? args[0] : ".";
+  const targetAnswer = await askQuestion(`Target directory (${defaultTarget}): `);
+  const targetValue = targetAnswer || defaultTarget;
+  const targetDirectory = path.resolve(process.cwd(), targetValue);
+
+  return {
+    templateName,
+    targetDirectory,
+    generatedInCurrentDirectory: targetDirectory === process.cwd()
+  };
+}
+
 function ensureScaffoldTarget(targetDirectory) {
   if (!fs.existsSync(targetDirectory)) {
     fs.mkdirSync(targetDirectory, { recursive: true });
@@ -148,52 +393,159 @@ function customizeProject(targetDirectory) {
   }
 }
 
-function scaffoldProject(templateName, targetDirectory) {
+function renderProgress(completed, total, label) {
+  const width = 24;
+  const filled = Math.round((completed / total) * width);
+  const empty = width - filled;
+  const bar = `${"=".repeat(filled)}${" ".repeat(empty)}`;
+  const percentage = `${Math.round((completed / total) * 100)}`.padStart(3, " ");
+  process.stdout.write(`\r[${bar}] ${percentage}% ${label}`);
+}
+
+async function scaffoldProject(templateName, targetDirectory) {
   const templateDirectory = path.resolve(__dirname, "templates", templateName);
 
   if (!fs.existsSync(templateDirectory)) {
     throw new Error(`Template files are missing for "${templateName}".`);
   }
 
+  const steps = [
+    "Validating target directory",
+    "Copying template files",
+    "Customizing project files",
+    "Finalizing scaffold"
+  ];
+
+  renderProgress(0, steps.length, "Preparing scaffold");
   ensureScaffoldTarget(targetDirectory);
+  await sleep(60);
+
+  renderProgress(1, steps.length, steps[0]);
+  await sleep(80);
+
   fs.cpSync(templateDirectory, targetDirectory, { recursive: true });
+  renderProgress(2, steps.length, steps[1]);
+  await sleep(80);
+
   customizeProject(targetDirectory);
+  renderProgress(3, steps.length, steps[2]);
+  await sleep(80);
+
+  renderProgress(4, steps.length, steps[3]);
+  await sleep(60);
+  process.stdout.write("\n");
 }
 
-function printNextSteps(targetDirectory, generatedInCurrentDirectory) {
-  process.stdout.write(`Generated ${DEFAULT_TEMPLATE} in ${targetDirectory}
+function getCommandName(base) {
+  if (process.platform === "win32") {
+    return `${base}.cmd`;
+  }
 
-Next steps:
-`);
+  return base;
+}
+
+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);
+  });
+}
+
+function printSuccess(templateName, targetDirectory, generatedInCurrentDirectory) {
+  const template = getTemplate(templateName);
+
+  process.stdout.write(`\nSuccess
+Generated ${template ? template.label : templateName} in ${targetDirectory}
+\n`);
 
   if (!generatedInCurrentDirectory) {
-    process.stdout.write(`  cd ${path.relative(process.cwd(), targetDirectory) || "."}
-`);
+    process.stdout.write(`Change directory first:\n  cd ${path.relative(process.cwd(), targetDirectory) || "."}\n\n`);
   }
+}
 
-  process.stdout.write(`  npm install
-  npx playwright install
-  npm test
-`);
+function printNextSteps(targetDirectory, generatedInCurrentDirectory) {
+  process.stdout.write("Next steps:\n");
+
+  if (!generatedInCurrentDirectory) {
+    process.stdout.write(`  cd ${path.relative(process.cwd(), targetDirectory) || "."}\n`);
+  }
+
+  process.stdout.write("  npm install\n");
+  process.stdout.write("  npx playwright install\n");
+  process.stdout.write("  npm test\n");
 }
 
-function main() {
+async function runPostGenerateActions(targetDirectory) {
+  if (!process.stdin.isTTY || !process.stdout.isTTY) {
+    return;
+  }
+
+  const prerequisites = collectPrerequisites();
+
+  if (prerequisites.npm) {
+    const shouldInstallDependencies = await askYesNo("Run npm install now?", true);
+
+    if (shouldInstallDependencies) {
+      await runCommand("npm", ["install"], targetDirectory);
+    }
+  } else {
+    process.stdout.write("Skipping npm install prompt because npm is not available.\n");
+  }
+
+  if (prerequisites.npx) {
+    const shouldInstallPlaywright = await askYesNo("Run npx playwright install now?", true);
+
+    if (shouldInstallPlaywright) {
+      await runCommand("npx", ["playwright", "install"], targetDirectory);
+    }
+  } else {
+    process.stdout.write("Skipping Playwright browser install prompt because npx is not available.\n");
+  }
+
+  if (prerequisites.npm) {
+    const shouldRunTests = await askYesNo("Run npm test now?", false);
+
+    if (shouldRunTests) {
+      await runCommand("npm", ["test"], targetDirectory);
+    }
+  } else {
+    process.stdout.write("Skipping npm test prompt because npm is not available.\n");
+  }
+}
+
+async function main() {
   const args = process.argv.slice(2);
 
+  assertSupportedNodeVersion();
+
   if (args.includes("--help") || args.includes("-h")) {
     printHelp();
     return;
   }
 
-  const { templateName, targetDirectory, generatedInCurrentDirectory } = resolveScaffoldArgs(args);
-  scaffoldProject(templateName, targetDirectory);
+  const { templateName, targetDirectory, generatedInCurrentDirectory } = await resolveScaffoldArgs(args);
+  printPrerequisiteWarnings(collectPrerequisites());
+  await scaffoldProject(templateName, targetDirectory);
+  printSuccess(templateName, targetDirectory, generatedInCurrentDirectory);
+  await runPostGenerateActions(targetDirectory);
   printNextSteps(targetDirectory, generatedInCurrentDirectory);
 }
 
-try {
-  main();
-} catch (error) {
+main().catch((error) => {
   const message = error instanceof Error ? error.message : String(error);
   process.stderr.write(`${message}\n`);
   process.exit(1);
-}
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@toolstackhq/create-qa-patterns",
-  "version": "1.0.1",
+  "version": "1.0.3",
   "description": "CLI for generating QA framework templates.",
   "license": "MIT",
   "repository": {