@toolstackhq/create-qa-patterns 1.0.13 → 1.0.15

package/index.js

@@ -1,492 +1,131 @@
 #!/usr/bin/env node
 
-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 COLOR_ENABLED = Boolean(process.stdout.isTTY) && !("NO_COLOR" in process.env);
-const DEFAULT_GITIGNORE = `node_modules/
-
-.env
-.env.*
-!.env.example
-
-.DS_Store
-*.log
-*.tgz
-.idea/
-.vscode/
-.nyc_output/
-coverage/
-dist/
-build/
-tmp/
-temp/
-downloads/
-cypress.env.json
-reports/
-cypress/screenshots/
-cypress/videos/
-reports/screenshots/
-reports/videos/
-allure-results/
-allure-report/
-test-results/
-playwright-report/
-`;
-
-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.",
-    defaultPackageName: "playwright-template",
-    demoAppsManagedByTemplate: true,
+const fs = require('node:fs');
+const path = require('node:path');
+const {
+  CLI_PACKAGE_VERSION,
+  DEFAULT_GITIGNORE,
+  DEFAULT_TEMPLATE,
+  MANAGED_FILE_PATTERNS,
+  METADATA_FILENAME,
+  MIN_NODE_VERSION,
+  TEMPLATE_CATALOG
+} = require('./lib/constants');
+const { parseCliOptions, resolveNonInteractiveArgs } = require('./lib/args');
+const {
+  analyzeUpgrade,
+  applySafeUpdates,
+  detectTemplateFromProject,
+  readProjectMetadata,
+  renderTemplateFile,
+  writeProjectMetadata
+} = require('./lib/metadata');
+const {
+  createLocalCredentials,
+  writeGeneratedLocalEnv
+} = require('./lib/local-env');
+const {
+  askQuestion,
+  askYesNo,
+  selectTemplateInteractively
+} = require('./lib/interactive');
+const {
+  assertSupportedNodeVersion,
+  createColors,
+  printHelp,
+  printNextSteps,
+  printPlaywrightInstallRecovery,
+  printPrerequisiteWarnings,
+  printSuccess,
+  printSummary,
+  printUpgradeReport
+} = require('./lib/output');
+const {
+  collectPrerequisites,
+  initializeGitRepository,
+  runCommand
+} = require('./lib/prereqs');
+const { scaffoldProject } = require('./lib/scaffold');
+const {
+  createTemplateAliases,
+  getTemplate,
+  getTemplateDirectory,
+  resolveTemplate,
+  toPackageName
+} = require('./lib/templates');
+
+const colors = createColors();
+const TEMPLATES = TEMPLATE_CATALOG.map((template) => {
+  if (template.id !== 'playwright-template') {
+    return template;
+  }
+
+  return {
+    ...template,
     setup: {
-      availability: "npx",
-      prompt: "Run npx playwright install now?",
-      summaryLabel: "Playwright browser install",
-      nextStep: "npx playwright install",
+      ...template.setup,
       run(targetDirectory) {
-        return runCommand("npx", ["playwright", "install"], targetDirectory);
+        return runCommand('npx', ['playwright', 'install'], targetDirectory);
       },
       recovery(targetDirectory) {
-        printPlaywrightInstallRecovery(targetDirectory);
+        printPlaywrightInstallRecovery(targetDirectory, colors);
       }
     }
-  },
-  {
-    id: "cypress-template",
-    aliases: ["cypress", "cy"],
-    label: "Cypress Template",
-    description: "TypeScript starter with Cypress e2e specs, custom commands, page modules, env-based config, CI, and a bundled demo app.",
-    defaultPackageName: "cypress-template",
-    demoAppsManagedByTemplate: true
-  }
-];
-
-const TEMPLATE_ALIASES = new Map(
-  TEMPLATES.flatMap((template) => [
-    [template.id, template.id],
-    ...template.aliases.map((alias) => [alias, template.id])
-  ])
-);
-
-function style(text, ...codes) {
-  if (!COLOR_ENABLED) {
-    return text;
-  }
-
-  return `\u001b[${codes.join(";")}m${text}\u001b[0m`;
-}
-
-const colors = {
-  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 printHelp() {
-  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]
-
-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
-
-Interactive mode:
-  When run without an explicit template, the CLI shows an interactive template picker.
-
-Supported templates:
-${supportedTemplates}
-`);
-}
-
-function parseCliOptions(args) {
-  const options = {
-    yes: false,
-    noInstall: false,
-    noSetup: false,
-    noTest: false,
-    templateName: null,
-    positionalArgs: []
   };
+});
 
-  for (let index = 0; index < args.length; index += 1) {
-    const arg = args[index];
-
-    switch (arg) {
-      case "--yes":
-        options.yes = true;
-        break;
-      case "--no-install":
-        options.noInstall = true;
-        break;
-      case "--no-setup":
-        options.noSetup = true;
-        break;
-      case "--no-test":
-        options.noTest = true;
-        break;
-      case "--template": {
-        const templateValue = args[index + 1];
-        if (!templateValue) {
-          throw new Error("Missing value for --template.");
-        }
-
-        const templateName = resolveTemplate(templateValue);
-        if (!templateName) {
-          throw new Error(
-            `Unsupported template "${templateValue}". Supported templates: ${TEMPLATES.map((template) => template.id).join(", ")}.`
-          );
-        }
-
-        options.templateName = templateName;
-        index += 1;
-        break;
-      }
-      default:
-        options.positionalArgs.push(arg);
-        break;
-    }
-  }
-
-  return options;
-}
-
-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 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;
-}
+const TEMPLATE_ALIASES = createTemplateAliases(TEMPLATES);
+const SUPPORTED_TEMPLATE_IDS = TEMPLATES.map((template) => template.id);
 
-function collectPrerequisites() {
+function createMetadataOptions() {
   return {
-    npm: commandExists("npm"),
-    npx: commandExists("npx"),
-    docker: commandExists("docker"),
-    git: commandExists("git")
+    cliPackageVersion: CLI_PACKAGE_VERSION,
+    defaultGitignore: DEFAULT_GITIGNORE,
+    getTemplateDirectory: (templateId) =>
+      getTemplateDirectory(__dirname, templateId),
+    managedPatterns: MANAGED_FILE_PATTERNS,
+    metadataFilename: METADATA_FILENAME,
+    toPackageName
   };
 }
 
-function printPrerequisiteWarnings(prerequisites) {
-  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 createLineInterface() {
-  return readline.createInterface({
-    input: process.stdin,
-    output: process.stdout
-  });
-}
-
 function createSummary(template, targetDirectory, generatedInCurrentDirectory) {
   return {
     template,
     targetDirectory,
+    targetRelativePath: path.relative(process.cwd(), targetDirectory) || '.',
     generatedInCurrentDirectory,
     demoAppsManagedByTemplate: Boolean(template.demoAppsManagedByTemplate),
-    gitInit: "not-run",
-    npmInstall: "not-run",
-    extraSetup: template.setup ? "not-run" : null,
-    testRun: "not-run"
+    localCredentials: null,
+    gitInit: 'not-run',
+    npmInstall: 'not-run',
+    extraSetup: template.setup ? 'not-run' : null,
+    testRun: 'not-run'
   };
 }
 
-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, options = {}) {
-  if (options.templateName) {
-    if (args.length > 1) {
-      throw new Error("Too many arguments. Run `create-qa-patterns --help` for usage.");
-    }
-
-    if (args.length === 0) {
-      return {
-        templateName: options.templateName,
-        targetDirectory: process.cwd(),
-        generatedInCurrentDirectory: true
-      };
-    }
-
-    return {
-      templateName: options.templateName,
-      targetDirectory: path.resolve(process.cwd(), args[0]),
-      generatedInCurrentDirectory: false
-    };
-  }
-
-  if (args.length === 0) {
-    return {
-      templateName: DEFAULT_TEMPLATE,
-      targetDirectory: process.cwd(),
-      generatedInCurrentDirectory: true
-    };
-  }
-
-  if (args.length === 1) {
-    const templateName = resolveTemplate(args[0]);
-
-    if (templateName) {
-      return {
-        templateName,
-        targetDirectory: process.cwd(),
-        generatedInCurrentDirectory: true
-      };
-    }
-
-    return {
-      templateName: DEFAULT_TEMPLATE,
-      targetDirectory: path.resolve(process.cwd(), args[0]),
-      generatedInCurrentDirectory: false
-    };
-  }
-
-  if (args.length === 2) {
-    const templateName = resolveTemplate(args[0]);
-
-    if (!templateName) {
-      throw new Error(
-        `Unsupported template "${args[0]}". Supported templates: ${TEMPLATES.map((template) => template.id).join(", ")}.`
-      );
-    }
-
-    return {
-      templateName,
-      targetDirectory: path.resolve(process.cwd(), args[1]),
-      generatedInCurrentDirectory: false
-    };
-  }
-
-  throw new Error("Too many arguments. Run `create-qa-patterns --help` for usage.");
-}
-
 async function resolveScaffoldArgs(args) {
-  const explicitTemplate = args[0] && resolveTemplate(args[0]);
+  const explicitTemplate =
+    args[0] && resolveTemplate(TEMPLATE_ALIASES, args[0]);
+  const nonInteractiveOptions = {
+    defaultTemplate: DEFAULT_TEMPLATE,
+    resolveTemplate: (value) => resolveTemplate(TEMPLATE_ALIASES, value),
+    supportedTemplateIds: SUPPORTED_TEMPLATE_IDS
+  };
 
   if (explicitTemplate) {
-    return resolveNonInteractiveArgs(args);
+    return resolveNonInteractiveArgs(args, nonInteractiveOptions);
   }
 
   if (!process.stdin.isTTY || !process.stdout.isTTY) {
-    return resolveNonInteractiveArgs(args);
+    return resolveNonInteractiveArgs(args, nonInteractiveOptions);
   }
 
-  const templateName = await selectTemplateInteractively();
-  const defaultTarget = args[0] ? args[0] : ".";
-  const targetAnswer = await askQuestion(`Target directory (${defaultTarget}): `);
+  const templateName = await selectTemplateInteractively(TEMPLATES);
+  const defaultTarget = args[0] ? args[0] : '.';
+  const targetAnswer = await askQuestion(
+    `Target directory (${defaultTarget}): `
+  );
   const targetValue = targetAnswer || defaultTarget;
   const targetDirectory = path.resolve(process.cwd(), targetValue);
 
@@ -497,256 +136,21 @@ async function resolveScaffoldArgs(args) {
   };
 }
 
-function ensureScaffoldTarget(targetDirectory) {
-  if (!fs.existsSync(targetDirectory)) {
-    fs.mkdirSync(targetDirectory, { recursive: true });
-    return;
-  }
-
-  const entries = fs
-    .readdirSync(targetDirectory)
-    .filter((entry) => ![".git", ".DS_Store"].includes(entry));
-
-  if (entries.length > 0) {
-    throw new Error(`Target directory is not empty: ${targetDirectory}`);
-  }
-}
-
-function toPackageName(targetDirectory, template) {
-  const baseName = path.basename(targetDirectory).toLowerCase();
-  const normalized = baseName
-    .replace(/[^a-z0-9-_]+/g, "-")
-    .replace(/^-+|-+$/g, "")
-    .replace(/-{2,}/g, "-");
-
-  return normalized || template.defaultPackageName || "qa-patterns-template";
-}
-
-function updateJsonFile(filePath, update) {
-  const current = JSON.parse(fs.readFileSync(filePath, "utf8"));
-  const next = update(current);
-  fs.writeFileSync(filePath, `${JSON.stringify(next, null, 2)}\n`, "utf8");
-}
-
-function customizeProject(targetDirectory, template) {
-  const packageName = toPackageName(targetDirectory, template);
-  const packageJsonPath = path.join(targetDirectory, "package.json");
-  const packageLockPath = path.join(targetDirectory, "package-lock.json");
-  const gitignorePath = path.join(targetDirectory, ".gitignore");
-
-  if (fs.existsSync(packageJsonPath)) {
-    updateJsonFile(packageJsonPath, (pkg) => ({
-      ...pkg,
-      name: packageName
-    }));
-  }
-
-  if (fs.existsSync(packageLockPath)) {
-    updateJsonFile(packageLockPath, (lock) => ({
-      ...lock,
-      name: packageName,
-      packages: lock.packages
-        ? {
-            ...lock.packages,
-            "": {
-              ...lock.packages[""],
-              name: packageName
-            }
-          }
-        : lock.packages
-    }));
-  }
-
-  if (!fs.existsSync(gitignorePath)) {
-    fs.writeFileSync(gitignorePath, DEFAULT_GITIGNORE, "utf8");
-  }
-}
-
-function initializeGitRepository(targetDirectory) {
-  if (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.");
-  }
-}
+let lastProgressLineLength = 0;
 
 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(template, targetDirectory, prerequisites) {
-  const templateName = template.id;
-  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, template);
-  renderProgress(3, steps.length, steps[2]);
-  await sleep(80);
-
-  if (prerequisites.git) {
-    initializeGitRepository(targetDirectory);
-  }
-
-  renderProgress(4, steps.length, steps[3]);
-  await sleep(60);
-  process.stdout.write("\n");
-}
-
-function getCommandName(base) {
-  if (process.platform === "win32") {
-    return `${base}.cmd`;
-  }
-
-  return base;
-}
-
-function printPlaywrightInstallRecovery(targetDirectory) {
-  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 ${path.relative(process.cwd(), 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 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(template, targetDirectory, generatedInCurrentDirectory) {
-  process.stdout.write(`\n${colors.green(colors.bold("Success"))}
-Generated ${template ? template.label : template.id} in ${targetDirectory}
-\n`);
-
-  if (!generatedInCurrentDirectory) {
-    process.stdout.write(`${colors.cyan("Change directory first:")}\n  cd ${path.relative(process.cwd(), targetDirectory) || "."}\n\n`);
-  }
-}
-
-function printNextSteps(summary) {
-  const steps = [];
-
-  if (!summary.generatedInCurrentDirectory) {
-    steps.push(`cd ${path.relative(process.cwd(), summary.targetDirectory) || "."}`);
-  }
-
-  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`);
-}
-
-function formatStatus(status) {
-  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 printSummary(summary) {
-  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)}\n`);
-  process.stdout.write(
-    `  Demo apps: ${summary.demoAppsManagedByTemplate ? "bundled and auto-started in dev when using default local URLs" : "external application required"}\n`
+  const bar = `${'='.repeat(filled)}${' '.repeat(empty)}`;
+  const percentage = `${Math.round((completed / total) * 100)}`.padStart(
+    3,
+    ' '
   );
-  process.stdout.write(`  npm install: ${formatStatus(summary.npmInstall)}\n`);
-  if (summary.template.setup) {
-    process.stdout.write(`  ${summary.template.setup.summaryLabel}: ${formatStatus(summary.extraSetup)}\n`);
-  }
-  process.stdout.write(`  npm test: ${formatStatus(summary.testRun)}\n`);
+  const line = `[${bar}] ${percentage}% ${label}`;
+  const paddingLength = Math.max(0, lastProgressLineLength - line.length);
+  process.stdout.write(`\r${line}${' '.repeat(paddingLength)}`);
+  lastProgressLineLength = line.length;
 }
 
 async function runPostGenerateActions(template, targetDirectory, summary) {
@@ -756,72 +160,171 @@ async function runPostGenerateActions(template, targetDirectory, summary) {
 
   if (prerequisites.npm) {
     if (options.noInstall) {
-      summary.npmInstall = "skipped";
+      summary.npmInstall = 'skipped';
     } else {
-      const shouldInstallDependencies = options.yes ? true : canPrompt ? await askYesNo("Run npm install now?", true) : false;
+      const shouldInstallDependencies = options.yes
+        ? true
+        : canPrompt
+          ? await askYesNo('Run npm install now?', true)
+          : false;
 
       if (shouldInstallDependencies) {
-        await runCommand("npm", ["install"], targetDirectory);
-        summary.npmInstall = "completed";
+        await runCommand('npm', ['install'], targetDirectory);
+        summary.npmInstall = 'completed';
       } else {
-        summary.npmInstall = canPrompt ? "skipped" : "not-run";
+        summary.npmInstall = canPrompt ? 'skipped' : 'not-run';
       }
     }
   } else {
-    process.stdout.write(`${colors.yellow("Skipping")} npm install prompt because npm is not available.\n`);
-    summary.npmInstall = "unavailable";
+    process.stdout.write(
+      `${colors.yellow('Skipping')} npm install prompt because npm is not available.\n`
+    );
+    summary.npmInstall = 'unavailable';
   }
 
   if (template.setup) {
     if (options.noSetup) {
-      summary.extraSetup = "skipped";
+      summary.extraSetup = 'skipped';
     } else if (prerequisites[template.setup.availability]) {
-      const shouldRunExtraSetup = options.yes ? true : canPrompt ? await askYesNo(template.setup.prompt, true) : false;
+      const shouldRunExtraSetup = options.yes
+        ? true
+        : canPrompt
+          ? await askYesNo(template.setup.prompt, true)
+          : false;
 
       if (shouldRunExtraSetup) {
         try {
           await template.setup.run(targetDirectory);
-          summary.extraSetup = "completed";
+          summary.extraSetup = 'completed';
         } catch (error) {
-          summary.extraSetup = "manual-recovery";
-          if (typeof template.setup.recovery === "function") {
+          summary.extraSetup = 'manual-recovery';
+          if (typeof template.setup.recovery === 'function') {
             template.setup.recovery(targetDirectory);
           }
 
-          const shouldContinue = await askYesNo("Continue without completing setup?", true);
+          const shouldContinue = await askYesNo(
+            'Continue without completing setup?',
+            true
+          );
 
           if (!shouldContinue) {
             throw error;
           }
         }
       } else {
-        summary.extraSetup = canPrompt ? "skipped" : "not-run";
+        summary.extraSetup = canPrompt ? 'skipped' : 'not-run';
       }
     } else {
       process.stdout.write(
-        `${colors.yellow("Skipping")} ${template.setup.summaryLabel.toLowerCase()} prompt because ${template.setup.availability} is not available.\n`
+        `${colors.yellow('Skipping')} ${template.setup.summaryLabel.toLowerCase()} prompt because ${template.setup.availability} is not available.\n`
       );
-      summary.extraSetup = "unavailable";
+      summary.extraSetup = 'unavailable';
     }
   }
 
   if (prerequisites.npm) {
     if (options.noTest) {
-      summary.testRun = "skipped";
+      summary.testRun = 'skipped';
     } else {
-      const shouldRunTests = options.yes ? true : canPrompt ? await askYesNo("Run npm test now?", false) : false;
+      const shouldRunTests = options.yes
+        ? true
+        : canPrompt
+          ? await askYesNo('Run npm test now?', false)
+          : false;
 
       if (shouldRunTests) {
-        await runCommand("npm", ["test"], targetDirectory);
-        summary.testRun = "completed";
+        await runCommand('npm', ['test'], targetDirectory);
+        summary.testRun = 'completed';
       } else {
-        summary.testRun = canPrompt ? "skipped" : "not-run";
+        summary.testRun = canPrompt ? 'skipped' : 'not-run';
       }
     }
   } else {
-    process.stdout.write(`${colors.yellow("Skipping")} npm test prompt because npm is not available.\n`);
-    summary.testRun = "unavailable";
+    process.stdout.write(
+      `${colors.yellow('Skipping')} npm test prompt because npm is not available.\n`
+    );
+    summary.testRun = 'unavailable';
+  }
+}
+
+function resolveUpgradeTarget(args) {
+  if (args.length > 1) {
+    throw new Error(
+      'Too many arguments for upgrade. Use `create-qa-patterns upgrade check [target-directory]`.'
+    );
+  }
+
+  return path.resolve(process.cwd(), args[0] || '.');
+}
+
+function runUpgradeCommand(rawArgs) {
+  const [subcommand = 'check', ...rest] = rawArgs;
+  const metadataOptions = createMetadataOptions();
+  const options = parseCliOptions(rest, {
+    resolveTemplate: (value) => resolveTemplate(TEMPLATE_ALIASES, value),
+    supportedTemplateIds: SUPPORTED_TEMPLATE_IDS
+  });
+  const targetDirectory = resolveUpgradeTarget(options.positionalArgs);
+  const metadata = readProjectMetadata(targetDirectory, METADATA_FILENAME);
+  const templateId =
+    metadata.template ||
+    detectTemplateFromProject(targetDirectory, METADATA_FILENAME);
+  const template = getTemplate(TEMPLATES, templateId);
+
+  if (!template) {
+    throw new Error(`Unsupported template "${templateId}".`);
+  }
+
+  const results = analyzeUpgrade(
+    template,
+    targetDirectory,
+    metadata,
+    metadataOptions
+  );
+
+  if (subcommand === 'check' || subcommand === 'report') {
+    printUpgradeReport(
+      targetDirectory,
+      metadata,
+      results,
+      CLI_PACKAGE_VERSION,
+      colors
+    );
+    return;
+  }
+
+  if (subcommand === 'apply') {
+    if (!options.safe) {
+      throw new Error(
+        'Upgrade apply requires --safe. Only safe managed-file updates are supported.'
+      );
+    }
+
+    printUpgradeReport(
+      targetDirectory,
+      metadata,
+      results,
+      CLI_PACKAGE_VERSION,
+      colors
+    );
+    const outcome = applySafeUpdates(
+      targetDirectory,
+      metadata,
+      results,
+      metadataOptions
+    );
+    process.stdout.write(`\n${colors.bold('Upgrade apply')}\n`);
+    process.stdout.write(`  Applied safe updates: ${outcome.appliedCount}\n`);
+    process.stdout.write(
+      `  Remaining conflicts: ${outcome.remainingConflicts}\n`
+    );
+    process.stdout.write('\n');
+    return;
   }
+
+  throw new Error(
+    `Unsupported upgrade command "${subcommand}". Use check, report, or apply --safe.`
+  );
 }
 
 async function main() {
@@ -829,32 +332,73 @@ async function main() {
 
   assertSupportedNodeVersion();
 
-  if (rawArgs.includes("--help") || rawArgs.includes("-h")) {
-    printHelp();
+  if (rawArgs[0] === 'upgrade') {
+    runUpgradeCommand(rawArgs.slice(1));
     return;
   }
 
-  const options = parseCliOptions(rawArgs);
+  if (rawArgs.includes('--help') || rawArgs.includes('-h')) {
+    printHelp(TEMPLATES, colors, DEFAULT_TEMPLATE);
+    return;
+  }
+
+  const metadataOptions = createMetadataOptions();
+  const options = parseCliOptions(rawArgs, {
+    resolveTemplate: (value) => resolveTemplate(TEMPLATE_ALIASES, value),
+    supportedTemplateIds: SUPPORTED_TEMPLATE_IDS
+  });
   const args = options.positionalArgs;
-  const { templateName, targetDirectory, generatedInCurrentDirectory } = options.templateName
-    ? resolveNonInteractiveArgs(args, options)
-    : await resolveScaffoldArgs(args);
-  const template = getTemplate(templateName);
+  const { templateName, targetDirectory, generatedInCurrentDirectory } =
+    options.templateName
+      ? resolveNonInteractiveArgs(args, {
+          ...options,
+          defaultTemplate: DEFAULT_TEMPLATE,
+          resolveTemplate: (value) => resolveTemplate(TEMPLATE_ALIASES, value),
+          supportedTemplateIds: SUPPORTED_TEMPLATE_IDS
+        })
+      : await resolveScaffoldArgs(args);
+  const template = getTemplate(TEMPLATES, templateName);
 
   if (!template) {
     throw new Error(`Unsupported template "${templateName}".`);
   }
 
   const prerequisites = collectPrerequisites();
-  const summary = createSummary(template, targetDirectory, generatedInCurrentDirectory);
+  const summary = createSummary(
+    template,
+    targetDirectory,
+    generatedInCurrentDirectory
+  );
   summary.options = options;
-  printPrerequisiteWarnings(prerequisites);
-  await scaffoldProject(template, targetDirectory, prerequisites);
-  summary.gitInit = prerequisites.git ? "completed" : "unavailable";
-  printSuccess(template, targetDirectory, generatedInCurrentDirectory);
+  printPrerequisiteWarnings(prerequisites, colors);
+  const localEnv = await scaffoldProject(
+    template,
+    targetDirectory,
+    prerequisites,
+    {
+      createLocalCredentials,
+      defaultGitignore: DEFAULT_GITIGNORE,
+      getTemplateDirectory: (templateId) =>
+        getTemplateDirectory(__dirname, templateId),
+      initializeGitRepository,
+      renderProgress,
+      toPackageName,
+      writeGeneratedLocalEnv
+    }
+  );
+  summary.localCredentials = localEnv.credentials;
+  writeProjectMetadata(template, targetDirectory, undefined, metadataOptions);
+  summary.gitInit = prerequisites.git ? 'completed' : 'unavailable';
+  printSuccess(template, targetDirectory, generatedInCurrentDirectory, colors);
   await runPostGenerateActions(template, targetDirectory, summary);
-  printSummary(summary);
-  printNextSteps(summary);
+  writeProjectMetadata(
+    template,
+    targetDirectory,
+    readProjectMetadata(targetDirectory, METADATA_FILENAME),
+    metadataOptions
+  );
+  printSummary(summary, colors);
+  printNextSteps(summary, colors);
 }
 
 main().catch((error) => {