qa-intelligence 1.1.2 → 1.1.4

package/README.md

@@ -12,135 +12,48 @@ The intelligence engine for Playwright CI pipelines — install it into any proj
 
 Use it **without the framework template** — install the package into your existing app repo.
 
-**Recommended layout:** create a `playwright/` subfolder at the repo root and keep all E2E tooling there, separate from your main app code. Full step-by-step guide (folder layout, `Dockerfile`, CI path changes): **[qa-intelligence-framework README](https://github.com/ardithaqi/qa-intelligence-framework#add-to-an-existing-project-npm-package)**.
 
 ---
 
-## Install
+## Quick start
 
-Run inside your `playwright/` folder (or your Playwright project root if tests already live there):
+Run from your **repo root** (not inside `playwright/`). You do **not** need a `playwright/` folder beforehand — `init` creates it.
 
 ```bash
+npx qa-intelligence init
 cd playwright
-npm install qa-intelligence @playwright/test
+cp .env.example .env   # set BASE_URL
+npm install            # installs qa-intelligence + @playwright/test (see playwright/package.json)
+npx playwright install
 ```
 
-npm automatically installs peer dependencies (`typescript`, `@types/node`) — no separate dev-deps step needed.
+`init` scaffolds:
 
----
-
-## Setup
-
-All paths below are relative to `playwright/` when using the recommended subfolder layout.
-
-### 1. Environment (`.env`)
-
-```env
-BASE_URL=https://your-app.example.com
-HEADLESS=true
-PW_WORKERS=2
-PW_RETRIES=1
-```
-
-### 2. `tsconfig.json` (TypeScript projects)
-
-```json
-{
-  "compilerOptions": {
-    "target": "ES2022",
-    "module": "Node16",
-    "moduleResolution": "Node16",
-    "strict": true,
-    "esModuleInterop": true,
-    "types": ["node"],
-    "skipLibCheck": true
-  },
-  "include": ["tests/**/*", "playwright.config.ts"]
-}
-```
-
-> `module` and `moduleResolution` must both be `"Node16"` so TypeScript resolves the package `exports` map.
+- `playwright/` — `.env.example`, `package.json`, `tsconfig.json`, `playwright.config.ts`, example test
+- `.github/workflows/qa-intelligence.yml` — PR diff, history, and comment (skip with `--no-ci`)
 
-### 3. `playwright.config.ts`
+**Then:** add `OPENAI_API_KEY` to GitHub secrets and set `BASE_URL` in the workflow file.
 
-```ts
-import { defineConfig } from "@playwright/test";
-import { env } from "qa-intelligence/config/env";
-
-export default defineConfig({
-  testDir: "./tests",
-  retries: env.PW_RETRIES,
-  workers: env.PW_WORKERS,
-  globalSetup: require.resolve("qa-intelligence/playwright/globalSetup"),
-  globalTeardown: require.resolve("qa-intelligence/playwright/globalTeardown"),
-  use: {
-    baseURL: env.BASE_URL,
-    headless: env.HEADLESS,
-    trace: "on-first-retry",
-    screenshot: "only-on-failure",
-    video: "retain-on-failure",
-  },
-});
-```
-
-### 4. Write tests
-
-Always import `test` from the package — **not** directly from Playwright:
+**Tests** — always import from the package, not Playwright directly:
 
 ```ts
 import { test, expect } from "qa-intelligence/playwright";
-
-test("user can login", async ({ page }) => {
-  await page.goto("/");
-  await expect(page).toHaveTitle(/My App/);
-});
-```
-
-Optional helpers:
-
-```ts
-import { step } from "qa-intelligence/playwright/steps";
-import { BasePage } from "qa-intelligence/playwright/basePage";
 ```
 
-### 5. What you provide
+### `init` options
 
-| You write | Package provides |
-|-----------|------------------|
-| `playwright/tests/` | Test hooks, artifact capture |
-| `playwright/.env` | Env validation |
-| `playwright/playwright.config.ts` | `globalSetup`, `globalTeardown`, AI teardown |
-| `playwright/Dockerfile` | — (copy from [framework](https://github.com/ardithaqi/qa-intelligence-framework/blob/master/Dockerfile)) |
-| `.github/workflows/ci.yml` | `qa-intelligence-diff`, `qa-intelligence-history`, `qa-intelligence-comment` |
-| Page objects (optional) | `BasePage`, `step()` |
+By default, `init` skips any file that already exists so it won't overwrite your work.
 
----
-
-## CI setup (GitHub Actions)
-
-Copy [`.github/workflows/ci.yml`](https://github.com/ardithaqi/qa-intelligence-framework/blob/master/.github/workflows/ci.yml) and [`Dockerfile`](https://github.com/ardithaqi/qa-intelligence-framework/blob/master/Dockerfile) from the framework repo.
-
-When using the `playwright/` subfolder layout, apply the CI path changes documented in the [framework adoption guide](https://github.com/ardithaqi/qa-intelligence-framework#add-to-an-existing-project-npm-package) (`working-directory: playwright`, artifact paths, etc.).
-
-The workflow includes:
-
-- Docker test execution
-- Artifact upload on every run
-- Baseline download from `main` on pull requests
-- `qa-intelligence-diff`, `qa-intelligence-history`, `qa-intelligence-comment`
-- PR blocking on new non-flaky failures
-
-Then update:
-
-- `BASE_URL` in the `docker run` step
-- GitHub secrets (see below)
+| Flag | What it does |
+|------|----------------|
+| `--no-ci` | Only scaffold `playwright/` (config, env, tests). Does **not** create `.github/workflows/qa-intelligence.yml`. Use this if you already have CI or use GitLab/Jenkins. |
+| `--force` | Overwrite existing scaffold files. Use when re-running `init` and you want a fresh copy from the templates. |
 
-### Required GitHub secrets
-
-- `OPENAI_API_KEY` — enables AI failure analysis in teardown
-- `TEST_USERNAME` / `TEST_PASSWORD` — if your tests need credentials
-
-Set `AI_ANALYSIS=true` in CI when running tests inside Docker.
+```bash
+npx qa-intelligence init              # playwright/ + GitHub workflow
+npx qa-intelligence init --no-ci      # playwright/ only
+npx qa-intelligence init --force      # overwrite files that already exist
+```
 
 ---
 
@@ -155,20 +68,21 @@ Set `AI_ANALYSIS=true` in CI when running tests inside Docker.
 
 ---
 
-## CLI tools
+## CLI
 
 | Command | Purpose |
 |---------|---------|
+| `qa-intelligence init` | Scaffold project files |
 | `qa-intelligence-diff` | Compare baseline vs current failures |
-| `qa-intelligence-history` | Add recurrence tracking |
-| `qa-intelligence-comment` | Post/update PR summary comment |
+| `qa-intelligence-history` | Recurrence tracking |
+| `qa-intelligence-comment` | Post/update PR summary |
 
 ---
 
 ## Package exports
 
-| Import path | What it gives you |
-|-------------|-------------------|
+| Import | What you get |
+|--------|--------------|
 | `qa-intelligence/playwright` | `test`, `expect`, `env` |
 | `qa-intelligence/playwright/globalSetup` | Artifact run setup |
 | `qa-intelligence/playwright/globalTeardown` | AI failure analysis |
@@ -178,19 +92,11 @@ Set `AI_ANALYSIS=true` in CI when running tests inside Docker.
 
 ---
 
-## Alternative: use the full template
-
-If you prefer a ready-made project with examples, Docker, and CI pre-wired:
-
-**[qa-intelligence-framework](https://github.com/ardithaqi/qa-intelligence-framework)** — click "Use this template".
-
-The template uses this package under the hood.
-
----
+## Full template (optional)
 
-## Author
+Prefer a ready-made project with Docker, example tests, and CI pre-wired? Use the **[qa-intelligence-framework](https://github.com/ardithaqi/qa-intelligence-framework)** template — click "Use this template".
 
-Built as the intelligence engine behind QA automation — Playwright hooks, AI failure analysis, and PR-aware CI. If you use this package, consider leaving a star or linking back—contributions are welcome.
+For adding to an existing repo with a `playwright/` subfolder, see the [framework adoption guide](https://github.com/ardithaqi/qa-intelligence-framework#add-to-an-existing-project-npm-package) (`Dockerfile`, CI path changes).
 
 ---
 

package/dist/cli/history.js

@@ -10,42 +10,8 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 Object.defineProperty(exports, "__esModule", { value: true });
 const fs_1 = __importDefault(require("fs"));
 const path_1 = __importDefault(require("path"));
-const failureIdentity_1 = require("../lib/failureIdentity");
+const history_1 = require("../lib/history");
 const HISTORY_PATH = ".cache/failure-history.json";
-const MAX_RUNS = 20;
-function failureKey(f) {
-    return (0, failureIdentity_1.failureDiffKey)(f.file, f.failure_type);
-}
-function loadHistory() {
-    if (!fs_1.default.existsSync(HISTORY_PATH))
-        return { runs: [] };
-    try {
-        const data = JSON.parse(fs_1.default.readFileSync(HISTORY_PATH, "utf8"));
-        return Array.isArray(data.runs) ? { runs: data.runs } : { runs: [] };
-    }
-    catch {
-        return { runs: [] };
-    }
-}
-function enrichFailures(failures, history, currentKeys) {
-    const runsIncludingThis = [...history.runs];
-    const thisRun = {
-        sha: process.env.GITHUB_SHA ?? "",
-        timestamp: new Date().toISOString(),
-        failureKeys: [...currentKeys],
-    };
-    runsIncludingThis.push(thisRun);
-    return failures.map((f) => {
-        const key = failureKey(f);
-        const enriched = { ...f };
-        const runsWithThis = runsIncludingThis.filter((r) => r.failureKeys.includes(key));
-        if (runsWithThis.length > 0) {
-            enriched.occurrence_count = runsWithThis.length;
-            enriched.first_seen = runsWithThis[0].timestamp;
-        }
-        return enriched;
-    });
-}
 function main() {
     const diffPath = "failure-diff.json";
     if (!fs_1.default.existsSync(diffPath)) {
@@ -54,17 +20,17 @@ function main() {
     }
     const diff = JSON.parse(fs_1.default.readFileSync(diffPath, "utf8"));
     const { newFailures, unchangedFailures, fixedFailures } = diff;
-    const currentKeys = new Set();
-    for (const f of [...newFailures, ...unchangedFailures]) {
-        currentKeys.add(failureKey(f));
-    }
-    const history = loadHistory();
-    const enrichedNew = enrichFailures(newFailures, history, currentKeys);
-    const enrichedUnchanged = enrichFailures(unchangedFailures, history, currentKeys);
-    const enrichedFixed = enrichFailures(fixedFailures, history, currentKeys);
-    const updatedHistory = {
-        runs: [...history.runs, { sha: process.env.GITHUB_SHA ?? "", timestamp: new Date().toISOString(), failureKeys: [...currentKeys] }].slice(-MAX_RUNS),
+    const currentKeys = (0, history_1.collectCurrentKeys)([...newFailures, ...unchangedFailures]);
+    const history = (0, history_1.loadHistory)(HISTORY_PATH);
+    const thisRun = {
+        sha: process.env.GITHUB_SHA ?? "",
+        timestamp: new Date().toISOString(),
+        failureKeys: [...currentKeys],
     };
+    const enrichedNew = (0, history_1.enrichFailures)(newFailures, history, thisRun);
+    const enrichedUnchanged = (0, history_1.enrichFailures)(unchangedFailures, history, thisRun);
+    const enrichedFixed = (0, history_1.enrichFailures)(fixedFailures, history, thisRun);
+    const updatedHistory = (0, history_1.appendHistoryRun)(history, thisRun);
     fs_1.default.mkdirSync(path_1.default.dirname(HISTORY_PATH), { recursive: true });
     fs_1.default.writeFileSync(HISTORY_PATH, JSON.stringify(updatedHistory, null, 2));
     const result = {

package/dist/cli/index.js

@@ -1,5 +1,38 @@
 #!/usr/bin/env node
 "use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
 Object.defineProperty(exports, "__esModule", { value: true });
 const child_process_1 = require("child_process");
 function getArg(name) {
@@ -9,6 +42,12 @@ function getArg(name) {
     return process.argv[idx + 1];
 }
 async function main() {
+    const subcommand = process.argv[2];
+    if (subcommand === "init") {
+        const { main: runInit } = await Promise.resolve().then(() => __importStar(require("./init")));
+        await runInit();
+        return;
+    }
     const baseline = getArg("baseline") ?? "baseline-artifacts";
     const current = getArg("current") ?? "artifacts";
     const repo = getArg("repo");

package/dist/cli/init.d.ts

@@ -0,0 +1,10 @@
+#!/usr/bin/env node
+export declare function runInit(options?: {
+    root?: string;
+    force?: boolean;
+    withCi?: boolean;
+}): {
+    written: string[];
+    skipped: string[];
+};
+export declare function main(): Promise<void>;

package/dist/cli/init.js

@@ -0,0 +1,99 @@
+#!/usr/bin/env node
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runInit = runInit;
+exports.main = main;
+const fs_1 = __importDefault(require("fs"));
+const path_1 = __importDefault(require("path"));
+const PLAYWRIGHT_SCAFFOLD = [
+    { template: "playwright/.env.example", dest: "playwright/.env.example" },
+    { template: "playwright/tsconfig.json", dest: "playwright/tsconfig.json" },
+    {
+        template: "playwright/playwright.config.ts",
+        dest: "playwright/playwright.config.ts",
+    },
+    { template: "playwright/package.json", dest: "playwright/package.json" },
+    {
+        template: "playwright/tests/example.spec.ts",
+        dest: "playwright/tests/example.spec.ts",
+    },
+];
+const CI_SCAFFOLD = [
+    {
+        template: "github/workflows/qa-intelligence.yml",
+        dest: ".github/workflows/qa-intelligence.yml",
+    },
+];
+function hasFlag(name) {
+    return process.argv.includes(`--${name}`);
+}
+function templatesDir() {
+    return path_1.default.join(__dirname, "..", "..", "templates");
+}
+function copyScaffold(root, entries, force) {
+    const written = [];
+    const skipped = [];
+    const sourceRoot = templatesDir();
+    for (const { template, dest } of entries) {
+        const source = path_1.default.join(sourceRoot, template);
+        const target = path_1.default.join(root, dest);
+        if (!fs_1.default.existsSync(source)) {
+            throw new Error(`Missing template: ${template}`);
+        }
+        if (fs_1.default.existsSync(target) && !force) {
+            skipped.push(dest);
+            continue;
+        }
+        fs_1.default.mkdirSync(path_1.default.dirname(target), { recursive: true });
+        fs_1.default.copyFileSync(source, target);
+        written.push(dest);
+    }
+    return { written, skipped };
+}
+function runInit(options) {
+    const root = path_1.default.resolve(options?.root ?? process.cwd());
+    const force = options?.force ?? false;
+    const withCi = options?.withCi ?? true;
+    const entries = [...PLAYWRIGHT_SCAFFOLD];
+    if (withCi) {
+        entries.push(...CI_SCAFFOLD);
+    }
+    return copyScaffold(root, entries, force);
+}
+async function main() {
+    const force = hasFlag("force");
+    const noCi = hasFlag("no-ci");
+    console.log("Scaffolding qa-intelligence in:", process.cwd());
+    const { written, skipped } = runInit({
+        force,
+        withCi: !noCi,
+    });
+    for (const file of written) {
+        console.log(`  created ${file}`);
+    }
+    for (const file of skipped) {
+        console.log(`  skipped ${file} (exists — use --force to overwrite)`);
+    }
+    if (written.length === 0 && skipped.length > 0) {
+        console.log("\nNothing new was written.");
+        return;
+    }
+    console.log("\nNext steps:");
+    console.log("  1. cd playwright && cp .env.example .env  # set BASE_URL");
+    console.log("  2. cd playwright && npm install");
+    console.log("  3. npx playwright install");
+    console.log("  4. Add OPENAI_API_KEY to GitHub repo secrets (for CI)");
+    if (!noCi) {
+        console.log("  5. Update BASE_URL in .github/workflows/qa-intelligence.yml");
+    }
+    console.log("  6. Write tests — import from qa-intelligence/playwright");
+}
+if (require.main === module) {
+    main().catch((e) => {
+        console.error(e);
+        process.exit(1);
+    });
+}

package/dist/lib/history.d.ts

@@ -0,0 +1,26 @@
+export declare const MAX_RUNS = 20;
+export interface Failure {
+    file: string;
+    line: number;
+    failure_type: string;
+    severity: string;
+    confidence: number;
+    is_flaky_suspected?: boolean;
+}
+export interface EnrichedFailure extends Failure {
+    first_seen?: string;
+    occurrence_count?: number;
+}
+export interface RunRecord {
+    sha: string;
+    timestamp: string;
+    failureKeys: string[];
+}
+export interface History {
+    runs: RunRecord[];
+}
+export declare function failureKey(f: Failure): string;
+export declare function loadHistory(historyPath: string): History;
+export declare function enrichFailures(failures: Failure[], history: History, thisRun: RunRecord): EnrichedFailure[];
+export declare function appendHistoryRun(history: History, run: RunRecord, maxRuns?: number): History;
+export declare function collectCurrentKeys(failures: Failure[]): Set<string>;

package/dist/lib/history.js

@@ -0,0 +1,53 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MAX_RUNS = void 0;
+exports.failureKey = failureKey;
+exports.loadHistory = loadHistory;
+exports.enrichFailures = enrichFailures;
+exports.appendHistoryRun = appendHistoryRun;
+exports.collectCurrentKeys = collectCurrentKeys;
+const fs_1 = __importDefault(require("fs"));
+const failureIdentity_1 = require("./failureIdentity");
+exports.MAX_RUNS = 20;
+function failureKey(f) {
+    return (0, failureIdentity_1.failureDiffKey)(f.file, f.failure_type);
+}
+function loadHistory(historyPath) {
+    if (!fs_1.default.existsSync(historyPath))
+        return { runs: [] };
+    try {
+        const data = JSON.parse(fs_1.default.readFileSync(historyPath, "utf8"));
+        return Array.isArray(data.runs) ? { runs: data.runs } : { runs: [] };
+    }
+    catch {
+        return { runs: [] };
+    }
+}
+function enrichFailures(failures, history, thisRun) {
+    const runsIncludingThis = [...history.runs, thisRun];
+    return failures.map((f) => {
+        const key = failureKey(f);
+        const enriched = { ...f };
+        const runsWithThis = runsIncludingThis.filter((r) => r.failureKeys.includes(key));
+        if (runsWithThis.length > 0) {
+            enriched.occurrence_count = runsWithThis.length;
+            enriched.first_seen = runsWithThis[0].timestamp;
+        }
+        return enriched;
+    });
+}
+function appendHistoryRun(history, run, maxRuns = exports.MAX_RUNS) {
+    return {
+        runs: [...history.runs, run].slice(-maxRuns),
+    };
+}
+function collectCurrentKeys(failures) {
+    const keys = new Set();
+    for (const f of failures) {
+        keys.add(failureKey(f));
+    }
+    return keys;
+}

package/package.json

@@ -1,86 +1,89 @@
-{
-    "name": "qa-intelligence",
-    "version": "1.1.2",
-    "engines": {
-        "node": ">=18"
-    },
-    "publishConfig": {
-        "access": "public"
-    },
-    "description": "CI intelligence engine for test pipelines. Detects regressions, flaky tests, and failure lifecycle in pull requests.",
-    "keywords": [
-        "ci",
-        "qa",
-        "test-automation",
-        "playwright",
-        "regression-detection",
-        "flaky-tests",
-        "qa-intelligence"
-    ],
-    "license": "MIT",
-    "repository": {
-        "type": "git",
-        "url": "git+https://github.com/ardithaqi/qa-intelligence.git"
-    },
-    "type": "commonjs",
-    "main": "dist/index.js",
-    "exports": {
-        "./playwright": {
-            "types": "./dist/playwright/baseTest.d.ts",
-            "default": "./dist/playwright/baseTest.js"
-        },
-        "./playwright/globalSetup": {
-            "types": "./dist/playwright/globalSetup.d.ts",
-            "default": "./dist/playwright/globalSetup.js"
-        },
-        "./playwright/globalTeardown": {
-            "types": "./dist/playwright/globalTeardown.d.ts",
-            "default": "./dist/playwright/globalTeardown.js"
-        },
-        "./playwright/basePage": {
-            "types": "./dist/playwright/basePage.d.ts",
-            "default": "./dist/playwright/basePage.js"
-        },
-        "./playwright/steps": {
-            "types": "./dist/playwright/steps.d.ts",
-            "default": "./dist/playwright/steps.js"
-        },
-        "./config/env": {
-            "types": "./dist/config/env.d.ts",
-            "default": "./dist/config/env.js"
-        }
-    },
-    "peerDependencies": {
-        "@playwright/test": ">=1.40.0",
-        "typescript": ">=5.0.0",
-        "@types/node": ">=18.0.0"
-    },
-    "bin": {
-        "qa-intelligence": "dist/cli/index.js",
-        "qa-intelligence-diff": "dist/cli/diff.js",
-        "qa-intelligence-history": "dist/cli/history.js",
-        "qa-intelligence-comment": "dist/cli/postComment.js"
-    },
-    "scripts": {
-        "build": "tsc -p tsconfig.json",
-        "prepare": "npm run build",
-        "dev:diff": "ts-node src/cli/diff.ts --baseline baseline-artifacts --current artifacts --out failure-diff.json",
-        "dev:comment": "ts-node src/cli/postComment.ts --diff failure-diff.json --repo owner/repo --pr 1 --token TOKEN"
-    },
-    "dependencies": {
-        "@octokit/rest": "^22.0.1",
-        "dotenv": "^17.3.1",
-        "openai": "^6.29.0",
-        "zod": "^4.3.6"
-    },
-    "devDependencies": {
-        "@playwright/test": "^1.58.2",
-        "@types/node": "^22.0.0",
-        "ts-node": "^10.9.2",
-        "tsx": "^4.21.0",
-        "typescript": "^5.9.3"
-    },
-    "files": [
-        "dist"
-    ]
-}
+{
+    "name": "qa-intelligence",
+    "version": "1.1.4",
+    "engines": {
+        "node": ">=18"
+    },
+    "publishConfig": {
+        "access": "public"
+    },
+    "description": "CI intelligence engine for test pipelines. Detects regressions, flaky tests, and failure lifecycle in pull requests.",
+    "keywords": [
+        "ci",
+        "qa",
+        "test-automation",
+        "playwright",
+        "regression-detection",
+        "flaky-tests",
+        "qa-intelligence"
+    ],
+    "license": "MIT",
+    "repository": {
+        "type": "git",
+        "url": "git+https://github.com/ardithaqi/qa-intelligence.git"
+    },
+    "type": "commonjs",
+    "main": "dist/index.js",
+    "exports": {
+        "./playwright": {
+            "types": "./dist/playwright/baseTest.d.ts",
+            "default": "./dist/playwright/baseTest.js"
+        },
+        "./playwright/globalSetup": {
+            "types": "./dist/playwright/globalSetup.d.ts",
+            "default": "./dist/playwright/globalSetup.js"
+        },
+        "./playwright/globalTeardown": {
+            "types": "./dist/playwright/globalTeardown.d.ts",
+            "default": "./dist/playwright/globalTeardown.js"
+        },
+        "./playwright/basePage": {
+            "types": "./dist/playwright/basePage.d.ts",
+            "default": "./dist/playwright/basePage.js"
+        },
+        "./playwright/steps": {
+            "types": "./dist/playwright/steps.d.ts",
+            "default": "./dist/playwright/steps.js"
+        },
+        "./config/env": {
+            "types": "./dist/config/env.d.ts",
+            "default": "./dist/config/env.js"
+        }
+    },
+    "peerDependencies": {
+        "@playwright/test": ">=1.40.0",
+        "typescript": ">=5.0.0",
+        "@types/node": ">=18.0.0"
+    },
+    "bin": {
+        "qa-intelligence": "dist/cli/index.js",
+        "qa-intelligence-init": "dist/cli/init.js",
+        "qa-intelligence-diff": "dist/cli/diff.js",
+        "qa-intelligence-history": "dist/cli/history.js",
+        "qa-intelligence-comment": "dist/cli/postComment.js"
+    },
+    "scripts": {
+        "build": "tsc -p tsconfig.json",
+        "test": "tsx --test src/**/*.test.ts",
+        "prepare": "npm run build",
+        "dev:diff": "ts-node src/cli/diff.ts --baseline baseline-artifacts --current artifacts --out failure-diff.json",
+        "dev:comment": "ts-node src/cli/postComment.ts --diff failure-diff.json --repo owner/repo --pr 1 --token TOKEN"
+    },
+    "dependencies": {
+        "@octokit/rest": "^22.0.1",
+        "dotenv": "^17.3.1",
+        "openai": "^6.29.0",
+        "zod": "^4.3.6"
+    },
+    "devDependencies": {
+        "@playwright/test": "^1.58.2",
+        "@types/node": "^22.0.0",
+        "ts-node": "^10.9.2",
+        "tsx": "^4.21.0",
+        "typescript": "^5.9.3"
+    },
+    "files": [
+        "dist",
+        "templates"
+    ]
+}

package/templates/github/workflows/qa-intelligence.yml

@@ -0,0 +1,129 @@
+name: QA Intelligence CI
+
+on:
+  push:
+    branches: [main, master]
+  pull_request:
+    branches: [main, master]
+
+permissions:
+  contents: read
+  actions: read
+  issues: write
+  pull-requests: write
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    defaults:
+      run:
+        working-directory: playwright
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 20
+
+      - name: Install dependencies
+        run: npm install
+
+      - name: Install Playwright browsers
+        run: npx playwright install --with-deps chromium
+
+      - name: Clean artifacts
+        if: always()
+        run: rm -rf artifacts
+
+      - name: Run Playwright tests
+        env:
+          OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}
+          AI_ANALYSIS: true
+          BASE_URL: https://your-app.example.com
+          HEADLESS: true
+          PW_WORKERS: 2
+          PW_RETRIES: 1
+          TEST_USERNAME: ${{ secrets.TEST_USERNAME }}
+          TEST_PASSWORD: ${{ secrets.TEST_PASSWORD }}
+        run: |
+          set +e
+          npx playwright test
+          EXIT=$?
+          if [ "$GITHUB_EVENT_NAME" = "pull_request" ]; then exit 0; fi
+          exit $EXIT
+
+      - name: Upload Playwright HTML report
+        if: always()
+        uses: actions/upload-artifact@v4
+        with:
+          name: playwright-report
+          path: playwright/playwright-report/
+
+      - name: Upload AI failure artifacts
+        if: always()
+        uses: actions/upload-artifact@v4
+        with:
+          name: ai-failure-artifacts
+          path: playwright/artifacts/
+
+      - name: Parse AI failure reports
+        if: always()
+        run: |
+          echo "Parsing AI failure reports..."
+          if [ -d "artifacts" ]; then
+            find artifacts -name "ai.txt" | while read file; do
+              echo "-----"
+              echo "File: $file"
+              json=$(awk '/^{/{flag=1} flag' "$file")
+              echo "$json" | jq .
+            done
+          else
+            echo "No artifacts directory found."
+          fi
+
+      - name: Download baseline artifacts from main
+        if: always() && github.event_name == 'pull_request'
+        uses: dawidd6/action-download-artifact@v6
+        with:
+          workflow: qa-intelligence.yml
+          branch: ${{ github.base_ref }}
+          name: ai-failure-artifacts
+          path: baseline-artifacts
+          if_no_artifact_found: warn
+
+      - name: Debug baseline contents
+        if: always() && github.event_name == 'pull_request'
+        run: |
+          echo "Baseline:"
+          ls -la ../baseline-artifacts || true
+          echo "Current:"
+          ls -la artifacts || true
+
+      - name: Compute failure diff
+        if: always() && github.event_name == 'pull_request'
+        run: npx qa-intelligence-diff --baseline ../baseline-artifacts --current artifacts
+
+      - name: Restore failure history cache
+        if: always() && github.event_name == 'pull_request'
+        uses: actions/cache@v4
+        with:
+          path: playwright/.cache
+          key: failure-history-${{ github.repository }}-${{ github.sha }}
+          restore-keys: |
+            failure-history-${{ github.repository }}-
+
+      - name: Update failure history (recurrence)
+        if: always() && github.event_name == 'pull_request'
+        run: npx qa-intelligence-history
+
+      - name: Comment PR with AI summary
+        if: always() && github.event_name == 'pull_request'
+        env:
+          GITHUB_TOKEN: ${{ github.token }}
+        run: |
+          npx qa-intelligence-comment \
+            --diff failure-diff.json \
+            --repo ${{ github.repository }} \
+            --pr ${{ github.event.pull_request.number }} \
+            --token $GITHUB_TOKEN

package/templates/playwright/.env.example

@@ -0,0 +1,8 @@
+BASE_URL=https://your-app.example.com
+HEADLESS=true
+PW_WORKERS=2
+PW_RETRIES=1
+
+# Optional — enable AI failure analysis in teardown
+# OPENAI_API_KEY=sk-...
+# AI_ANALYSIS=true

package/templates/playwright/package.json

@@ -0,0 +1,11 @@
+{
+  "name": "e2e-tests",
+  "private": true,
+  "scripts": {
+    "test": "playwright test"
+  },
+  "dependencies": {
+    "@playwright/test": "^1.58.0",
+    "qa-intelligence": "^1.1.4"
+  }
+}

package/templates/playwright/playwright.config.ts

@@ -0,0 +1,18 @@
+import { defineConfig } from "@playwright/test";
+import { env } from "qa-intelligence/config/env";
+
+export default defineConfig({
+  testDir: "./tests",
+  retries: env.PW_RETRIES,
+  workers: env.PW_WORKERS,
+  globalSetup: require.resolve("qa-intelligence/playwright/globalSetup"),
+  globalTeardown: require.resolve("qa-intelligence/playwright/globalTeardown"),
+  use: {
+    baseURL: env.BASE_URL,
+    headless: env.HEADLESS,
+    trace: "on-first-retry",
+    screenshot: "only-on-failure",
+    video: "retain-on-failure",
+  },
+  reporter: [["html", { open: "never" }]],
+});

package/templates/playwright/tests/example.spec.ts

@@ -0,0 +1,6 @@
+import { test, expect } from "qa-intelligence/playwright";
+
+test("example — replace with your first test", async ({ page }) => {
+  await page.goto("/");
+  await expect(page).toHaveTitle(/.*/);
+});

package/templates/playwright/tsconfig.json

@@ -0,0 +1,12 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "Node16",
+    "moduleResolution": "Node16",
+    "strict": true,
+    "esModuleInterop": true,
+    "types": ["node"],
+    "skipLibCheck": true
+  },
+  "include": ["tests/**/*", "playwright.config.ts"]
+}