@qa-gentic/stlc-agents 1.0.7 → 1.0.9

package/README.md

@@ -32,12 +32,24 @@ A sixth server — **Playwright MCP** (`http://localhost:8931/mcp`) — drives a
 
 ## Install
 
+
 ```bash
 # 1. Install the CLI + npm package globally
 #    You will be prompted to choose your integration: ado / jira / both
 #    The choice is saved to ~/.qa-stlc/integration and reused by all subsequent commands.
 npm install -g @qa-gentic/stlc-agents
+```
 
+> **Note:** On most systems, the installer will prompt you to select your integration (ADO, Jira, or both) and then automatically run `qa-stlc init` and offer to scaffold a new project. If you do **not** see the prompt (for example, if npm skips postinstall for an already-installed package, or in some non-interactive environments), simply run:
+>
+> ```bash
+> qa-stlc init
+> qa-stlc scaffold
+> ```
+> 
+> This will perform the same setup steps as the postinstall script.
+
+```bash
 # 2. Bootstrap your project (installs Python agents, copies skills, writes MCP config)
 #    --integration overrides the saved preference; omit to reuse the choice from step 1.
 qa-stlc init --vscode --integration ado    # GitHub Copilot / VS Code — ADO pipeline

package/bin/postinstall.js

@@ -1,159 +1,99 @@
 #!/usr/bin/env node
 /**
- * postinstall.js — Auto-install Python MCP servers after  npm install -g
+ * postinstall.js — Auto-install Python MCP servers after npm install -g
  *
- * Asks the user which integration they need (ADO / Jira / Both) and installs
- * only the relevant Python agents.  In non-interactive (CI) environments the
- * prompt is skipped and the default (ado) is used.
+ * npm 7+ runs lifecycle scripts with stdout suppressed by default (background
+ * mode).  To guarantee output is always visible we write exclusively to
+ * stderr, which npm forwards to the terminal even in background mode.
  *
- * The chosen value is persisted to  ~/.qa-stlc/integration  so that
- * `qa-stlc init`, `qa-stlc mcp-config`, and `qa-stlc verify` all read it
- * without asking again.
+ * Interactive prompts (readline / TTY) require --foreground-scripts and are
+ * therefore NOT used here.  The user is instructed to run `qa-stlc init`
+ * in their project after install — that command IS interactive.
  */
 "use strict";
 
-const { spawnSync }   = require("child_process");
-const path            = require("path");
-const fs              = require("fs");
-const os              = require("os");
-const pickIntegration = require("../src/cli/prompt-integration");
-const pkg             = require("../package.json");
+// ── Route ALL output to stderr so it shows without --foreground-scripts ──────
+const _write = (msg) => process.stderr.write(msg + "\n");
+console.log   = _write;
+console.info  = _write;
+console.warn  = _write;
+console.error = _write;
+
+const { spawnSync } = require("child_process");
+const os  = require("os");
+const fs  = require("fs");
+const path = require("path");
+const pkg = require("../package.json");
 
 const C = {
   reset:  "\x1b[0m", bold:   "\x1b[1m",
   green:  "\x1b[32m", cyan:   "\x1b[36m",
-  yellow: "\x1b[33m", red:    "\x1b[31m", dim: "\x1b[2m",
+  yellow: "\x1b[33m", dim:    "\x1b[2m",
 };
 
 const b    = (s) => `${C.bold}${s}${C.reset}`;
 const ok   = (s) => console.log(`${C.green}✓${C.reset}  ${s}`);
 const info = (s) => console.log(`${C.cyan}→${C.reset}  ${s}`);
 const warn = (s) => console.log(`${C.yellow}⚠${C.reset}  ${s}`);
-const y    = (s) => `${C.yellow}${s}${C.reset}`;
 const d    = (s) => `${C.dim}${s}${C.reset}`;
 
-// Persistent preference file — shared with cmd-init / cmd-mcp-config / cmd-verify
-const PREF_DIR  = path.join(os.homedir(), ".qa-stlc");
-const PREF_FILE = path.join(PREF_DIR, "integration");
-
-function savePreference(value) {
-  try {
-    fs.mkdirSync(PREF_DIR, { recursive: true });
-    fs.writeFileSync(PREF_FILE, value, "utf8");
-  } catch (_) { /* non-fatal */ }
-}
-
 console.log(`\n${b("QA STLC Agents")} v${pkg.version} — post-install\n`);
 
-// ── Async main ───────────────────────────────────────────────────────────────
-(async () => {
-
-  // ── 1. Find Python ─────────────────────────────────────────────────────────
-  const pythonCandidates = ["python3", "python"];
-  let python = null;
-  for (const candidate of pythonCandidates) {
-    const r = spawnSync(candidate, ["--version"], { encoding: "utf8" });
-    if (r.status === 0) { python = candidate; break; }
-  }
-
-  if (!python) {
-    warn("Python not found — skipping pip install.");
-    warn("Run manually after installing Python 3.10+:");
-    warn("  pip install qa-gentic-stlc-agents");
-    printNextSteps("ado");
-    return;
-  }
-
-  // ── 2. Ask which integration ──────────────────────────────────────────────
-  const integration = await pickIntegration("ado");
-  savePreference(integration);
+// ── 1. Find Python ────────────────────────────────────────────────────────────
+const pythonCandidates = ["python3", "python"];
+let python = null;
+for (const candidate of pythonCandidates) {
+  const r = spawnSync(candidate, ["--version"], { encoding: "utf8" });
+  if (r.status === 0) { python = candidate; break; }
+}
 
-  // ── 3. pip install ────────────────────────────────────────────────────────
+if (!python) {
+  warn("Python not found — skipping pip install.");
+  warn("After installing Python 3.10+, run inside your project:");
+  warn("  pip install qa-gentic-stlc-agents");
+} else {
+  // ── 2. pip install (non-interactive, pipe output to stderr) ────────────────
   info("Installing qa-gentic-stlc-agents via pip…");
   const pip = spawnSync(
     python,
     ["-m", "pip", "install", "qa-gentic-stlc-agents", "--upgrade", "--quiet"],
-    { stdio: "inherit", encoding: "utf8" }
+    { stdio: ["ignore", "pipe", "pipe"], encoding: "utf8" }
   );
-
   if (pip.status === 0) {
     ok("qa-gentic-stlc-agents installed.");
   } else {
+    // Only surface pip output on failure
+    if (pip.stdout) process.stderr.write(pip.stdout);
+    if (pip.stderr) process.stderr.write(pip.stderr);
     warn("pip install failed. Run manually: pip install qa-gentic-stlc-agents");
   }
+}
 
+// ── 3. Print next-step instructions ──────────────────────────────────────────
+console.log(`
+${b("Next steps")} — run these inside your project root:
 
-  // ── 4. Run qa-stlc init automatically ─────────────────────────────────────
-  const { execSync } = require("child_process");
-  try {
-    console.log(`\n${C.cyan}→${C.reset} Running: qa-stlc init --integration ${integration}\n`);
-    execSync(`qa-stlc init --integration ${integration}`, { stdio: "inherit" });
-  } catch (e) {
-    warn("Failed to run qa-stlc init automatically. You can run it manually.");
-  }
+  ${b("1.")} Choose your integration and bootstrap:
+
+     ${C.cyan}qa-stlc init --vscode --integration ado${C.reset}   ${d("# VS Code / GitHub Copilot — Azure DevOps")}
+     ${C.cyan}qa-stlc init --vscode --integration jira${C.reset}  ${d("# VS Code / GitHub Copilot — Jira Cloud")}
+     ${C.cyan}qa-stlc init --vscode --integration both${C.reset}  ${d("# VS Code / GitHub Copilot — ADO + Jira")}
+     ${C.cyan}qa-stlc init --integration ado${C.reset}            ${d("# Claude Code — Azure DevOps")}
+
+     ${d("This installs skills, writes .vscode/mcp.json, and sets your integration.")}
+     ${d("Run it once; re-run any time to change integration.")}
+
+  ${b("2.")} Scaffold a new Playwright + Cucumber + TypeScript QA project:
+
+     ${C.cyan}qa-stlc scaffold --name my-qa-project${C.reset}
+
+  ${b("3.")} Start the Playwright browser server (keep running in a separate terminal):
+
+     ${C.cyan}npx @playwright/mcp@latest --port 8931${C.reset}
 
-  // ── 5. Prompt for scaffold ────────────────────────────────────────────────
-  const readline = require("readline");
-  const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
-  rl.question("Do you want to scaffold a new QA project now? (Y/n): ", (answer) => {
-    if (!answer.trim() || answer.trim().toLowerCase() === "y") {
-      try {
-        console.log(`\n${C.cyan}→${C.reset} Running: qa-stlc scaffold\n`);
-        execSync("qa-stlc scaffold", { stdio: "inherit" });
-      } catch (e) {
-        warn("Failed to run qa-stlc scaffold automatically. You can run it manually.");
-      }
-    }
-    // ── 6. Show Playwright MCP server command ───────────────────────────────
-    console.log(`\n# 4. Start the Playwright browser server (required for code generation)\n` +
-                `npx @playwright/mcp@latest --port 8931\n`);
-    rl.close();
-  });
-
-})();
-
-// ── Helpers ──────────────────────────────────────────────────────────────────
-
-function printNextSteps(integration) {
-  const initFlag = integration !== "ado" ? ` --integration ${integration}` : "";
-
-  const adoWorkflow = `
-  ${d("ADO pipeline:")}
-  ${d("1 →")} ${y("qa-test-case-manager")}     ${d("ADO work item → manual test cases")}
-  ${d("2 →")} ${y("qa-gherkin-generator")}     ${d("Epic / Feature / PBI → .feature file")}
-  ${d("3 →")} ${y("qa-playwright-generator")}  ${d("Gherkin + live browser → self-healing Playwright TypeScript")}
-  ${d("4 →")} ${y("qa-helix-writer")}          ${d("Generated files → Helix-QA project on disk")}`;
-
-  const jiraWorkflow = `
-  ${d("Jira pipeline:")}
-  ${d("1 →")} ${y("qa-jira-manager")}          ${d("Fetch Jira issue + analyse acceptance criteria")}
-  ${d("2 →")} ${y("qa-jira-manager")}          ${d("Generate test cases and create in Jira with 'is tested by' links")}
-  ${d("3 →")} ${y("qa-gherkin-generator")}     ${d("Generate Gherkin .feature file from Jira issue AC")}
-  ${d("4 →")} ${y("qa-playwright-generator")}  ${d("Gherkin + live browser → self-healing Playwright TypeScript")}
-  ${d("5 →")} ${y("qa-helix-writer")}          ${d("Generated files → Helix-QA project on disk")}
-  ${d("   Requires: JIRA_CLIENT_ID + JIRA_CLIENT_SECRET + JIRA_CLOUD_ID in .env")}`;
-
-  const workflow =
-      integration === "ado"  ? adoWorkflow
-    : integration === "jira" ? jiraWorkflow
-    :                          adoWorkflow + "\n" + jiraWorkflow;
-
-  console.log(`
-${b("Setup")} — run once in your project root:
-
-  ${C.cyan}qa-stlc init --vscode${initFlag}${C.reset}   ${d("# GitHub Copilot / VS Code")}
-  ${C.cyan}qa-stlc init${initFlag}${C.reset}             ${d("# Claude Code")}
-
-  ${d("Writes MCP config + installs skill files — then reload VS Code.")}
-
-${b("Start Playwright MCP")} ${d("(keep running in a separate terminal)")}:
-
-  ${C.cyan}npx @playwright/mcp@latest --port 8931${C.reset}
-
-${b("STLC Workflow")}:
-${workflow}
-
-${d("Change integration at any time:  qa-stlc init --integration <ado|jira|both>")}
 ${d("Docs: https://github.com/qa-gentic/stlc-agents")}
-`);
-}
+
+${d("  Tip: npm sometimes suppresses postinstall output for global packages.")}
+${d("       If you missed these instructions, run  qa-stlc  in your project.")}
+${d("       Or reinstall with: npm install -g --foreground-scripts @qa-gentic/stlc-agents")}
+`);

package/bin/qa-stlc.js

@@ -101,9 +101,43 @@ Quick Start (run once in your project root):
   $ npx @playwright/mcp@latest --port 8931
 `);
 
-program.parse(process.argv);
-
-// Show help if no command given
+// Show next-step instructions if invoked with no command.
+// This is the reliable fallback when npm suppresses postinstall output.
 if (!process.argv.slice(2).length) {
-  program.outputHelp();
-}
+  const C = {
+    reset: "\x1b[0m", bold: "\x1b[1m",
+    green: "\x1b[32m", cyan: "\x1b[36m", dim: "\x1b[2m",
+  };
+  const b = (s) => `${C.bold}${s}${C.reset}`;
+  const d = (s) => `${C.dim}${s}${C.reset}`;
+  console.log(`
+${b("QA STLC Agents")} v${pkg.version}
+
+${b("Next steps")} — run these inside your project root:
+
+  ${b("1.")} Choose your integration and bootstrap:
+
+     ${C.cyan}qa-stlc init --vscode --integration ado${C.reset}   ${d("# VS Code / GitHub Copilot — Azure DevOps")}
+     ${C.cyan}qa-stlc init --vscode --integration jira${C.reset}  ${d("# VS Code / GitHub Copilot — Jira Cloud")}
+     ${C.cyan}qa-stlc init --vscode --integration both${C.reset}  ${d("# VS Code / GitHub Copilot — ADO + Jira")}
+     ${C.cyan}qa-stlc init --integration ado${C.reset}            ${d("# Claude Code — Azure DevOps")}
+
+     ${d("Installs skills, writes MCP config, sets your integration.")}
+     ${d("Run once; re-run any time to change integration.")}
+
+  ${b("2.")} Scaffold a new Playwright + Cucumber + TypeScript QA project:
+
+     ${C.cyan}qa-stlc scaffold --name my-qa-project${C.reset}
+
+  ${b("3.")} Start the Playwright browser server (keep running in a separate terminal):
+
+     ${C.cyan}npx @playwright/mcp@latest --port 8931${C.reset}
+
+  Run ${b("qa-stlc --help")} for the full command reference.
+
+${d("Docs: https://github.com/qa-gentic/stlc-agents")}
+`);
+  process.exit(0);
+}
+
+program.parse(process.argv);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@qa-gentic/stlc-agents",
-  "version": "1.0.7",
+  "version": "1.0.9",
   "description": "QA STLC Agents — five MCP servers + skills for AI-powered test case, Gherkin, Playwright generation, and Helix-QA file writing against Azure DevOps and Jira Cloud. Full pipeline for both: fetch → test cases → Gherkin → Playwright → Helix-QA. Works with Claude Code, GitHub Copilot, Cursor, Windsurf.",
   "keywords": [
     "playwright",

package/src/cli/cmd-skills.js

@@ -35,7 +35,7 @@ function readIntegrationPrefSk() {
 }
 
 // Resolve the skills bundled with this npm package
-const PKG_ROOT    = path.resolve(__dirname, "..");
+const PKG_ROOT    = path.resolve(__dirname, "../..");
 const SKILLS_DIR  = path.join(PKG_ROOT, "skills");
 const BEHAVIOR_MD = path.join(SKILLS_DIR, "AGENT-BEHAVIOR.md");
 const AGENTS_DIR  = path.join(PKG_ROOT, ".github", "agents");
@@ -189,7 +189,7 @@ module.exports = async function skills(opts) {
 
   if (!fs.existsSync(SKILLS_DIR)) {
     console.error(`Skills directory not found: ${SKILLS_DIR}`);
-    console.error("Try reinstalling: npm install -g @qa-stlc/agents");
+    console.error("Try reinstalling: npm install -g @qa-gentic/stlc-agents");
     process.exit(1);
   }