@keber/qa-framework 1.1.1 → 1.1.3

package/README.md

@@ -28,27 +28,38 @@ This framework was designed to be:
 
 ## Quick Start
 
-### Option A: Install from npm (recommended)
+### Install from npm
 
 ```bash
-npm install --save-dev github:keber/qa-framework
-npx qa-framework init
+npm install @keber/qa-framework
 ```
 
-### Option B: Clone directly (during early adoption)
+The postinstall script scaffolds the `qa/` structure automatically. No need to run `init` manually.
+
+### Using with an AI agent (GitHub Copilot, Claude, etc.)
+
+Use this prompt in your IDE agent chat:
+
+```
+Install @keber/qa-framework and set up the project following qa/AGENT-NEXT-STEPS.md
+```
+
+The install creates `qa/AGENT-NEXT-STEPS.md` with the exact steps the agent needs to complete the setup (optional integrations, module configuration, credentials, etc.).
+
+### Using manually (without an agent)
 
 ```bash
-# Clone into your project's tools directory or as a submodule
-git clone <this-repo> tools/qa-framework
-node tools/qa-framework/scripts/cli.js init
+npm install @keber/qa-framework
+# then read qa/AGENT-NEXT-STEPS.md for next steps
 ```
 
 The `init` command will:
 
 1. Create the `qa/` directory tree in your project root
-2. Copy all base templates into place
+2. Copy all base templates and agent instructions into place
 3. Create `qa/qa-framework.config.json` for project-specific settings
-4. Optionally set up Playwright and Azure DevOps integrations
+4. Create `.github/copilot-instructions.md` with QA agent behavior rules
+5. Create `qa/AGENT-NEXT-STEPS.md` with follow-up steps
 
 ---
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@keber/qa-framework",
-  "version": "1.1.1",
+  "version": "1.1.3",
   "description": "Reusable spec-driven QA framework for IDE-agent-assisted automated testing. Installable as an npm package. Provides structure, templates, agent instructions, and optional integrations for Playwright and Azure DevOps.",
   "keywords": [
     "qa",

package/scripts/init.js

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 /**
- * scripts/init.js — Scaffold qa/ folder structure from config
+ * scripts/init.js - Scaffold qa/ folder structure from config
  *
  * Usage:
  *   qa-framework init
@@ -52,7 +52,7 @@ if (explicitConfigPath) {
 } else {
   config = buildBootstrapConfig();
   configSource = 'generated defaults';
-  console.log('[qa-framework/init] No config file found. Bootstrapping with default config.');
+  process.stderr.write('[qa-framework/init] No config file found. Bootstrapping with default config.\n');
 }
 
 const qaRoot  = path.resolve(cwd, config.conventions?.qaRoot ?? 'qa');
@@ -60,7 +60,7 @@ const localConfigPath = path.join(qaRoot, 'qa-framework.config.json');
 
 // --skip-if-exists: bail out silently when qa/ is already initialised
 if (skipIfExists && fs.existsSync(localConfigPath)) {
-  console.log('[qa-framework/init] qa/ already initialised — skipping (postinstall).');
+  process.stderr.write('[qa-framework/init] qa/ already initialised - skipping (postinstall).\n');
   process.exit(0);
 }
 
@@ -69,11 +69,11 @@ if (!fs.existsSync(localConfigPath)) {
   fs.writeFileSync(localConfigPath, `${JSON.stringify(config, null, 2)}\n`, 'utf8');
   console.log(`  [created] ${path.relative(cwd, localConfigPath)}`);
 } else {
-  console.log(`  [exists]  ${path.relative(cwd, localConfigPath)} — skipped`);
+  console.log(`  [exists]  ${path.relative(cwd, localConfigPath)} - skipped`);
 }
 
-console.log(`[qa-framework/init] Scaffolding qa/ at: ${qaRoot}`);
-console.log(`[qa-framework/init] Using config source: ${configSource}`);
+process.stderr.write(`[qa-framework/init] Scaffolding qa/ at: ${qaRoot}\n`);
+process.stderr.write(`[qa-framework/init] Using config source: ${configSource}\n`);
 
 // --- Top-level folders ---
 const topLevelFolders = [
@@ -89,7 +89,7 @@ const topLevelFolders = [
 for (const folder of topLevelFolders) {
   const fullPath = path.join(qaRoot, folder);
   fs.mkdirSync(fullPath, { recursive: true });
-  console.log(`  [created] ${path.relative(process.cwd(), fullPath)}/`);
+  console.log(`  [created] ${path.relative(cwd, fullPath)}/`);
 }
 
 // --- Standards placeholder ---
@@ -140,9 +140,9 @@ for (const mod of modules) {
         } else {
           fs.writeFileSync(dest, `# ${specFile}\n\n> Auto-generated placeholder\n`, 'utf8');
         }
-        console.log(`  [created] ${path.relative(process.cwd(), dest)}`);
+        console.log(`  [created] ${path.relative(cwd, dest)}`);
       } else {
-        console.log(`  [exists]  ${path.relative(process.cwd(), dest)} — skipped`);
+        console.log(`  [exists]  ${path.relative(cwd, dest)} - skipped`);
       }
     }
 
@@ -152,7 +152,7 @@ for (const mod of modules) {
     const specTs = path.join(e2eDir, `${subKey}.spec.ts`);
     if (!fs.existsSync(specTs)) {
       fs.writeFileSync(specTs, specScaffold(mod.name, sub.name, moduleKey, subKey), 'utf8');
-      console.log(`  [created] ${path.relative(process.cwd(), specTs)}`);
+      console.log(`  [created] ${path.relative(cwd, specTs)}`);
     }
   }
 }
@@ -164,7 +164,7 @@ for (const file of ['playwright.config.ts', 'global-setup.ts', '.env.example', '
   const dest = path.join(automationDir, file);
   if (!fs.existsSync(dest)) {
     fs.copyFileSync(path.join(scaffoldSrc, file), dest);
-    console.log(`  [created] ${path.relative(process.cwd(), dest)}`);
+    console.log(`  [created] ${path.relative(cwd, dest)}`);
   }
 }
 const fixturesDir = path.join(automationDir, 'fixtures');
@@ -173,7 +173,7 @@ for (const file of ['auth.ts', 'test-helpers.ts']) {
   const dest = path.join(fixturesDir, file);
   if (!fs.existsSync(dest)) {
     fs.copyFileSync(path.join(scaffoldSrc, 'fixtures', file), dest);
-    console.log(`  [created] ${path.relative(process.cwd(), dest)}`);
+    console.log(`  [created] ${path.relative(cwd  , dest)}`);
   }
 }
 
@@ -247,9 +247,10 @@ This project uses \`@keber/qa-framework\` v${config.frameworkVersion ?? '1.0.0'}
 
 ## Agent behavior rules
 
+0. **On every conversation start:** check if \`qa/AGENT-NEXT-STEPS.md\` exists. If it does, read it and complete its steps before anything else.
 1. Before performing any QA task, read the relevant instruction file from \`qa/00-guides/\`
-2. Always save artifacts in the correct \`qa/\` subfolder — refer to \`qa/QA-STRUCTURE-GUIDE.md\`
-3. Never hardcode credentials — always use env vars and \`<PLACEHOLDER>\` in documentation
+2. Always save artifacts in the correct \`qa/\` subfolder - refer to \`qa/QA-STRUCTURE-GUIDE.md\`
+3. Never hardcode credentials - always use env vars and \`<PLACEHOLDER>\` in documentation
 4. Follow the naming conventions in \`qa/00-standards/naming-conventions.md\`
 5. Project QA config is at \`qa/qa-framework.config.json\`
 
@@ -268,12 +269,42 @@ This project uses \`@keber/qa-framework\` v${config.frameworkVersion ?? '1.0.0'}
 `;
 writeIfMissing(copilotInstrPath, copilotInstrContent);
 
-console.log('\n[qa-framework/init] Done!\n');
-console.log('Next steps:');
-console.log('  1. Copy qa/07-automation/.env.example to qa/07-automation/.env and fill in credentials');
-console.log('  2. Add qa/07-automation/.env and qa/07-automation/.auth/ to .gitignore');
-console.log('  3. Run: cd qa/07-automation && npm install && npx playwright install chromium');
-console.log('  4. Start filling in spec files with your module\'s real data');
+// --- AGENT-NEXT-STEPS.md — readable by the agent after install ---
+const nextStepsContent = `# ✅ @keber/qa-framework installed successfully
+
+> This file was generated automatically by the postinstall script.
+> Read it and follow the steps below, then delete this file.
+
+## What was scaffolded
+
+- \`qa/\` folder structure with spec templates and agent instructions
+- \`.github/copilot-instructions.md\` with QA agent behavior rules
+
+## Required next steps
+
+### 1. Configure your project modules
+Edit \`qa/qa-framework.config.json\` and add your project modules under the \`"modules"\` array.
+
+### 2. Optional integrations
+
+**Azure DevOps integration:**
+\`\`\`bash
+npm install @keber/ado-qa
+\`\`\`
+
+**Playwright automation:**
+\`\`\`bash
+npm install @playwright/test
+cd qa/07-automation && npm install && npx playwright install chromium
+\`\`\`
+
+### 3. Credentials
+- Copy \`qa/07-automation/.env.example\` → \`qa/07-automation/.env\` and fill in credentials
+- Add \`qa/07-automation/.env\` and \`qa/07-automation/.auth/\` to \`.gitignore\`
+`;
+const nextStepsPath = path.join(qaRoot, 'AGENT-NEXT-STEPS.md');
+fs.writeFileSync(nextStepsPath, nextStepsContent, 'utf8');
+console.log(`  [created] ${path.relative(cwd, nextStepsPath)}`);
 
 // -----------------------------------------------------------------------
 // Helpers
@@ -282,7 +313,7 @@ function writeIfMissing(filePath, content) {
   if (!fs.existsSync(filePath)) {
     fs.mkdirSync(path.dirname(filePath), { recursive: true });
     fs.writeFileSync(filePath, content, 'utf8');
-    console.log(`  [created] ${path.relative(process.cwd(), filePath)}`);
+    console.log(`  [created] ${path.relative(cwd, filePath)}`);
   }
 }