@toolstackhq/create-qa-patterns 1.0.13 → 1.0.15

package/lib/scaffold.js

@@ -0,0 +1,120 @@
+const fs = require('node:fs');
+const path = require('node:path');
+const { renderTemplateFile } = require('./metadata');
+
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+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 customizeProject(targetDirectory, template, options) {
+  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)) {
+    fs.writeFileSync(
+      packageJsonPath,
+      renderTemplateFile(template, 'package.json', targetDirectory, options),
+      'utf8'
+    );
+  }
+
+  if (fs.existsSync(packageLockPath)) {
+    fs.writeFileSync(
+      packageLockPath,
+      renderTemplateFile(
+        template,
+        'package-lock.json',
+        targetDirectory,
+        options
+      ),
+      'utf8'
+    );
+  }
+
+  if (!fs.existsSync(gitignorePath)) {
+    fs.writeFileSync(gitignorePath, options.defaultGitignore, 'utf8');
+  }
+}
+
+async function scaffoldProject(
+  template,
+  targetDirectory,
+  prerequisites,
+  options
+) {
+  const {
+    createLocalCredentials,
+    defaultGitignore,
+    getTemplateDirectory,
+    initializeGitRepository,
+    renderProgress,
+    toPackageName,
+    writeGeneratedLocalEnv
+  } = options;
+  const templateDirectory = getTemplateDirectory(template.id);
+
+  if (!fs.existsSync(templateDirectory)) {
+    throw new Error(`Template files are missing for "${template.id}".`);
+  }
+
+  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, {
+    defaultGitignore,
+    getTemplateDirectory,
+    toPackageName
+  });
+  renderProgress(3, steps.length, steps[2]);
+  await sleep(80);
+
+  if (prerequisites.git) {
+    initializeGitRepository(targetDirectory);
+  }
+
+  const localEnv = writeGeneratedLocalEnv(
+    targetDirectory,
+    template.id,
+    createLocalCredentials(targetDirectory)
+  );
+
+  renderProgress(4, steps.length, steps[3]);
+  await sleep(60);
+  process.stdout.write('\n');
+  return localEnv;
+}
+
+module.exports = {
+  scaffoldProject
+};

package/lib/templates.js

@@ -0,0 +1,40 @@
+const path = require('node:path');
+
+function createTemplateAliases(templates) {
+  return new Map(
+    templates.flatMap((template) => [
+      [template.id, template.id],
+      ...template.aliases.map((alias) => [alias, template.id])
+    ])
+  );
+}
+
+function resolveTemplate(templateAliases, value) {
+  return templateAliases.get(value);
+}
+
+function getTemplate(templates, templateId) {
+  return templates.find((template) => template.id === templateId);
+}
+
+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 getTemplateDirectory(rootDirectory, templateId) {
+  return path.resolve(rootDirectory, 'templates', templateId);
+}
+
+module.exports = {
+  createTemplateAliases,
+  getTemplate,
+  getTemplateDirectory,
+  resolveTemplate,
+  toPackageName
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@toolstackhq/create-qa-patterns",
-  "version": "1.0.13",
+  "version": "1.0.15",
   "description": "CLI for generating QA framework templates.",
   "license": "MIT",
   "repository": {
@@ -16,15 +16,17 @@
   },
   "files": [
     "index.js",
+    "lib",
     "templates",
     "README.md",
-    "LICENSE"
+    "LICENSE",
+    "tests"
   ],
   "bin": {
     "create-qa-patterns": "./index.js"
   },
   "scripts": {
     "start": "node ./index.js",
-    "test": "node ./index.js --help"
+    "test": "node --test ./tests/*.test.js"
   }
 }

package/templates/cypress-template/.env.example

@@ -1,5 +1,5 @@
 TEST_ENV=dev
 TEST_RUN_ID=local
 DEV_UI_BASE_URL=http://127.0.0.1:3000
-DEV_APP_USERNAME=tester
-DEV_APP_PASSWORD=Password123!
+DEV_APP_USERNAME=generate-a-local-username
+DEV_APP_PASSWORD=generate-a-local-password

package/templates/cypress-template/.github/workflows/cypress-tests.yml

@@ -17,7 +17,7 @@ jobs:
 
       - uses: actions/setup-node@v4
         with:
-          node-version: "20"
+          node-version: '20'
 
       - name: Install template dependencies
         working-directory: templates/cypress-template
@@ -35,7 +35,7 @@ jobs:
           working-directory: templates/cypress-template
           install: false
           start: npm run demo:ui
-          wait-on: "http://127.0.0.1:3000/health"
+          wait-on: 'http://127.0.0.1:3000/health'
           command: npm run cy:run
 
       - name: Upload Cypress artifacts

package/templates/cypress-template/README.md

@@ -13,6 +13,7 @@ This is a Cypress + TypeScript automation framework template for a small determi
 - [Reports and artifacts](#reports-and-artifacts)
 - [Add a new test](#add-a-new-test)
 - [Extend the framework](#extend-the-framework)
+- [Template upgrades](#template-upgrades)
 - [CI](#ci)
 
 ## Feature set
@@ -90,8 +91,7 @@ npm run report:allure
 Default local values:
 
 - UI base URL: `http://127.0.0.1:3000`
-- username: `tester`
-- password: `Password123!`
+- credentials: generated into local `.env` on first run
 
 ## Environment and secrets
 
@@ -111,7 +111,7 @@ Credentials resolve the same way:
 
 1. `DEV_APP_USERNAME` or `DEV_APP_PASSWORD`
 2. `APP_USERNAME` or `APP_PASSWORD`
-3. built-in defaults for the selected environment
+3. built-in empty defaults for the selected environment
 
 For local overrides, copy:
 
@@ -125,6 +125,8 @@ to:
 .env
 ```
 
+On the first local run, the template also creates a `.env` file with random demo credentials if one does not already exist.
+
 If you want to disable the bundled local demo app even in `dev`, use:
 
 ```bash
@@ -171,11 +173,14 @@ Keep the pattern simple:
 Example shape:
 
 ```ts
-it("does something", () => {
-  const dataFactory = new DataFactory("local");
+import { loadAppConfig } from '../support/app-config';
+
+it('does something', () => {
+  const appConfig = loadAppConfig();
+  const dataFactory = new DataFactory('local');
   const person = dataFactory.person();
 
-  cy.signIn("tester", "Password123!");
+  cy.signIn(appConfig.credentials.username, appConfig.credentials.password);
   cy.addPerson(person);
 });
 ```
@@ -197,6 +202,24 @@ Recommended rules:
 - use Cypress commands for workflows, not giant helper classes
 - keep the data layer generic until the project really needs domain-specific factories
 
+## Template upgrades
+
+This project includes a `.qa-patterns.json` metadata file so future CLI versions can compare the current project against the managed template baseline.
+
+Check for available safe updates:
+
+```bash
+npx -y @toolstackhq/create-qa-patterns upgrade check .
+```
+
+Apply only safe managed-file updates:
+
+```bash
+npx -y @toolstackhq/create-qa-patterns upgrade apply --safe .
+```
+
+The upgrade flow is conservative. It updates framework infrastructure such as config, scripts, workflows, and package metadata when those files are still unchanged from the generated baseline. If you changed a managed file yourself, the CLI reports a conflict instead of overwriting it.
+
 ## CI
 
 The included workflow lives at:

package/templates/cypress-template/allurerc.mjs

@@ -1,5 +1,5 @@
 export default {
-  name: "qa-patterns Cypress Template",
+  name: 'qa-patterns Cypress Template',
   plugins: {
     awesome: {
       options: {

package/templates/cypress-template/config/environments.ts

@@ -1,5 +1,5 @@
 // Defines the built-in environment defaults used when env vars are not provided.
-import type { TestEnvironment } from "./test-env";
+import type { TestEnvironment } from './test-env';
 
 type EnvironmentDefaults = {
   uiBaseUrl: string;
@@ -11,28 +11,30 @@ type EnvironmentDefaults = {
 
 const DEFAULTS: Record<TestEnvironment, EnvironmentDefaults> = {
   dev: {
-    uiBaseUrl: "http://127.0.0.1:3000",
+    uiBaseUrl: 'http://127.0.0.1:3000',
     credentials: {
-      username: "tester",
-      password: "Password123!"
+      username: '',
+      password: ''
     }
   },
   staging: {
-    uiBaseUrl: "https://staging-ui.example.internal",
+    uiBaseUrl: 'https://staging-ui.example.internal',
     credentials: {
-      username: "staging-user",
-      password: "replace-me"
+      username: '',
+      password: ''
     }
   },
   prod: {
-    uiBaseUrl: "https://ui.example.internal",
+    uiBaseUrl: 'https://ui.example.internal',
     credentials: {
-      username: "prod-user",
-      password: "replace-me"
+      username: '',
+      password: ''
     }
   }
 };
 
-export function getEnvironmentDefaults(testEnv: TestEnvironment): EnvironmentDefaults {
+export function getEnvironmentDefaults(
+  testEnv: TestEnvironment
+): EnvironmentDefaults {
   return DEFAULTS[testEnv];
 }

package/templates/cypress-template/config/runtime-config.ts

@@ -1,20 +1,23 @@
 // Builds the runtime configuration object that tests and fixtures consume.
-import path from "node:path";
+import path from 'node:path';
 
-import dotenv from "dotenv";
-import { z } from "zod";
+import dotenv from 'dotenv';
+import { z } from 'zod';
 
-import { getEnvironmentDefaults } from "./environments";
-import { EnvSecretProvider, SecretManager } from "./secret-manager";
-import { loadTestEnvironment } from "./test-env";
+import { getEnvironmentDefaults } from './environments';
+import { EnvSecretProvider, SecretManager } from './secret-manager';
+import { loadTestEnvironment } from './test-env';
 
 const environment = loadTestEnvironment();
 
-dotenv.config({ path: path.resolve(process.cwd(), ".env") });
-dotenv.config({ path: path.resolve(process.cwd(), `.env.${environment}`), override: true });
+dotenv.config({ path: path.resolve(process.cwd(), '.env') });
+dotenv.config({
+  path: path.resolve(process.cwd(), `.env.${environment}`),
+  override: true
+});
 
 const runtimeConfigSchema = z.object({
-  testEnv: z.enum(["dev", "staging", "prod"]),
+  testEnv: z.enum(['dev', 'staging', 'prod']),
   testRunId: z.string().min(1),
   uiBaseUrl: z.string().url(),
   credentials: z.object({
@@ -36,13 +39,15 @@ export function loadRuntimeConfig(): RuntimeConfig {
 
   return runtimeConfigSchema.parse({
     testEnv: environment,
-    testRunId: process.env.TEST_RUN_ID ?? "local",
+    testRunId: process.env.TEST_RUN_ID ?? 'local',
     uiBaseUrl,
     credentials: {
       username:
-        secretManager.getOptionalSecret("APP_USERNAME", environment) ?? defaults.credentials.username,
+        secretManager.getOptionalSecret('APP_USERNAME', environment) ??
+        defaults.credentials.username,
       password:
-        secretManager.getOptionalSecret("APP_PASSWORD", environment) ?? defaults.credentials.password
+        secretManager.getOptionalSecret('APP_PASSWORD', environment) ??
+        defaults.credentials.password
     }
   });
 }

package/templates/cypress-template/config/secret-manager.ts

@@ -1,5 +1,5 @@
 // Minimal secret abstraction so env-based secrets can later be replaced cleanly.
-import type { TestEnvironment } from "./test-env";
+import type { TestEnvironment } from './test-env';
 
 export interface SecretProvider {
   getSecret(key: string, testEnv: TestEnvironment): string | undefined;

package/templates/cypress-template/config/test-env.ts

@@ -1,9 +1,9 @@
-import { z } from "zod";
+import { z } from 'zod';
 
-export const testEnvironmentSchema = z.enum(["dev", "staging", "prod"]);
+export const testEnvironmentSchema = z.enum(['dev', 'staging', 'prod']);
 
 export type TestEnvironment = z.infer<typeof testEnvironmentSchema>;
 
 export function loadTestEnvironment(): TestEnvironment {
-  return testEnvironmentSchema.parse(process.env.TEST_ENV ?? "dev");
+  return testEnvironmentSchema.parse(process.env.TEST_ENV ?? 'dev');
 }

package/templates/cypress-template/cypress/e2e/ui-journey.cy.ts

@@ -1,21 +1,23 @@
 // Starter Cypress scenario that demonstrates the preferred spec style for this template.
-import { DataFactory } from "../support/data/data-factory";
-import { loadAppConfig } from "../support/app-config";
-import { peoplePage } from "../support/pages/people-page";
+import { DataFactory } from '../support/data/data-factory';
+import { loadAppConfig } from '../support/app-config';
+import { peoplePage } from '../support/pages/people-page';
 
-describe("UI starter journey", () => {
-  it("signs in and adds one person", () => {
+describe('UI starter journey', () => {
+  it('signs in and adds one person', () => {
     const appConfig = loadAppConfig();
     const dataFactory = new DataFactory(appConfig.testRunId);
     const person = dataFactory.person();
 
     cy.signIn(appConfig.credentials.username, appConfig.credentials.password);
-    peoplePage.welcomeMessage().should("contain", appConfig.credentials.username);
+    peoplePage
+      .welcomeMessage()
+      .should('contain', appConfig.credentials.username);
 
     cy.addPerson(person);
-    peoplePage.flashMessage().should("contain", "Person added");
-    peoplePage.nameCell(person.personId).should("have.text", person.name);
-    peoplePage.roleCell(person.personId).should("have.text", person.role);
-    peoplePage.emailCell(person.personId).should("have.text", person.email);
+    peoplePage.flashMessage().should('contain', 'Person added');
+    peoplePage.nameCell(person.personId).should('have.text', person.name);
+    peoplePage.roleCell(person.personId).should('have.text', person.role);
+    peoplePage.emailCell(person.personId).should('have.text', person.email);
   });
 });

package/templates/cypress-template/cypress/support/app-config.ts

@@ -11,14 +11,14 @@ export type AppConfig = {
 };
 
 export function loadAppConfig(): AppConfig {
-  const credentials = Cypress.env("credentials") as Credentials | undefined;
+  const credentials = Cypress.env('credentials') as Credentials | undefined;
 
   return {
-    testEnv: String(Cypress.env("testEnv") ?? "dev"),
-    testRunId: String(Cypress.env("testRunId") ?? "local"),
+    testEnv: String(Cypress.env('testEnv') ?? 'dev'),
+    testRunId: String(Cypress.env('testRunId') ?? 'local'),
     credentials: {
-      username: credentials?.username ?? "tester",
-      password: credentials?.password ?? "Password123!"
+      username: credentials?.username ?? '',
+      password: credentials?.password ?? ''
     }
   };
 }

package/templates/cypress-template/cypress/support/commands.ts

@@ -1,7 +1,7 @@
 // Registers the custom Cypress commands that the starter specs rely on.
-import type { PersonRecord } from "./data/data-factory";
-import { loginPage } from "./pages/login-page";
-import { peoplePage } from "./pages/people-page";
+import type { PersonRecord } from './data/data-factory';
+import { loginPage } from './pages/login-page';
+import { peoplePage } from './pages/people-page';
 
 declare global {
   namespace Cypress {
@@ -13,17 +13,17 @@ declare global {
   }
 }
 
-Cypress.Commands.add("getByTestId", (testId: string) => {
+Cypress.Commands.add('getByTestId', (testId: string) => {
   return cy.get(`[data-testid='${testId}']`);
 });
 
-Cypress.Commands.add("signIn", (username: string, password: string) => {
+Cypress.Commands.add('signIn', (username: string, password: string) => {
   loginPage.visit();
   loginPage.login(username, password);
-  peoplePage.heading().should("be.visible");
+  peoplePage.heading().should('be.visible');
 });
 
-Cypress.Commands.add("addPerson", (person: PersonRecord) => {
+Cypress.Commands.add('addPerson', (person: PersonRecord) => {
   peoplePage.addPerson(person);
 });
 

package/templates/cypress-template/cypress/support/data/data-factory.ts

@@ -1,6 +1,6 @@
 // Generic data builders that keep tests readable and deterministic.
-import { createSeededFaker } from "./seeded-faker";
-import { IdGenerator } from "./id-generator";
+import { createSeededFaker } from './seeded-faker';
+import { IdGenerator } from './id-generator';
 
 export type PersonRecord = {
   personId: string;
@@ -17,7 +17,7 @@ export class DataFactory {
   }
 
   person(overrides?: Partial<PersonRecord>): PersonRecord {
-    const personId = overrides?.personId ?? this.idGenerator.next("person");
+    const personId = overrides?.personId ?? this.idGenerator.next('person');
     const seededFaker = createSeededFaker(`${this.testRunId}:${personId}`);
     const firstName = seededFaker.person.firstName();
     const lastName = seededFaker.person.lastName();
@@ -27,7 +27,9 @@ export class DataFactory {
       personId,
       name,
       role: overrides?.role ?? seededFaker.person.jobTitle(),
-      email: overrides?.email ?? `${firstName}.${lastName}.${personId}@example.test`.toLowerCase(),
+      email:
+        overrides?.email ??
+        `${firstName}.${lastName}.${personId}@example.test`.toLowerCase(),
       ...overrides
     };
   }

package/templates/cypress-template/cypress/support/data/id-generator.ts

@@ -7,7 +7,7 @@ export class IdGenerator {
   next(prefix: string): string {
     const counter = (this.counters.get(prefix) ?? 0) + 1;
     this.counters.set(prefix, counter);
-    return `${prefix}-${this.runId}-${String(counter).padStart(4, "0")}`;
+    return `${prefix}-${this.runId}-${String(counter).padStart(4, '0')}`;
   }
 
   nextSequence(prefix: string): number {

package/templates/cypress-template/cypress/support/data/seeded-faker.ts

@@ -1,8 +1,8 @@
 // Seeded faker wrapper so generated values stay stable for a given run id.
-import { Faker, en } from "@faker-js/faker";
+import { Faker, en } from '@faker-js/faker';
 
 function hashSeed(value: string): number {
-  return value.split("").reduce((seed, character) => {
+  return value.split('').reduce((seed, character) => {
     return ((seed << 5) - seed + character.charCodeAt(0)) | 0;
   }, 0);
 }

package/templates/cypress-template/cypress/support/e2e.ts

@@ -1,2 +1,2 @@
-import "allure-cypress";
-import "./commands";
+import 'allure-cypress';
+import './commands';

package/templates/cypress-template/cypress/support/pages/login-page.ts

@@ -1,19 +1,19 @@
 // Page module for the login screen used by custom Cypress commands.
 export const loginPage = {
   visit(): Cypress.Chainable {
-    return cy.visit("/login");
+    return cy.visit('/login');
   },
 
   usernameInput(): Cypress.Chainable {
-    return cy.get("#username");
+    return cy.get('#username');
   },
 
   passwordInput(): Cypress.Chainable {
-    return cy.get("#password");
+    return cy.get('#password');
   },
 
   submitButton(): Cypress.Chainable {
-    return cy.contains("button", "Sign in");
+    return cy.contains('button', 'Sign in');
   },
 
   login(username: string, password: string): void {

package/templates/cypress-template/cypress/support/pages/people-page.ts

@@ -1,9 +1,9 @@
 // Page module for the people screen used in the starter Cypress journey.
-import type { PersonRecord } from "../data/data-factory";
+import type { PersonRecord } from '../data/data-factory';
 
 export const peoplePage = {
   heading(): Cypress.Chainable {
-    return cy.contains("h1", "People");
+    return cy.contains('h1', 'People');
   },
 
   welcomeMessage(): Cypress.Chainable {
@@ -15,23 +15,23 @@ export const peoplePage = {
   },
 
   personIdInput(): Cypress.Chainable {
-    return cy.get("#personId");
+    return cy.get('#personId');
   },
 
   nameInput(): Cypress.Chainable {
-    return cy.get("#name");
+    return cy.get('#name');
   },
 
   roleInput(): Cypress.Chainable {
-    return cy.get("#role");
+    return cy.get('#role');
   },
 
   emailInput(): Cypress.Chainable {
-    return cy.get("#email");
+    return cy.get('#email');
   },
 
   submitButton(): Cypress.Chainable {
-    return cy.contains("button", "Add person");
+    return cy.contains('button', 'Add person');
   },
 
   personRow(personId: string): Cypress.Chainable {
@@ -39,15 +39,15 @@ export const peoplePage = {
   },
 
   nameCell(personId: string): Cypress.Chainable {
-    return this.personRow(personId).find("td").eq(0);
+    return this.personRow(personId).find('td').eq(0);
   },
 
   roleCell(personId: string): Cypress.Chainable {
-    return this.personRow(personId).find("td").eq(1);
+    return this.personRow(personId).find('td').eq(1);
   },
 
   emailCell(personId: string): Cypress.Chainable {
-    return this.personRow(personId).find("td").eq(2);
+    return this.personRow(personId).find('td').eq(2);
   },
 
   addPerson(person: PersonRecord): void {