@ai-qa/workflow 2.0.11 → 2.0.13

package/qa-dashboard/routes/review.js

@@ -0,0 +1,114 @@
+const express = require('express');
+const router = express.Router();
+const pm = require('../services/project-manager');
+const path = require('path');
+const fs = require('fs');
+
+router.get('/', (req, res) => {
+  const projectId = req.query.project;
+  const project = projectId ? pm.get(projectId) : pm.getAll()[0];
+  if (!project) return res.redirect('/projects');
+
+  const bridge = pm.getBridge(project.id);
+  const allFiles = bridge.listAll();
+  const runDirs = bridge.getRunDirs();
+
+  const runs = runDirs.map(d => {
+    const result = bridge.getRunResult(d.name);
+    const healing = bridge.getHealingReport(d.name);
+    return {
+      id: d.name,
+      timestamp: d.name.replace('run-', '').replace(/-/g, ':').slice(0, 19),
+      success: result ? result.success : null,
+      duration: result ? result.duration : null,
+      testName: result ? result.test : 'Unknown',
+      failedCount: result && Array.isArray(result.failedTests) ? result.failedTests.length : 0,
+      passedCount: result && Array.isArray(result.passedTests) ? result.passedTests.length : 0,
+      healedCount: healing ? healing.totalHealed || 0 : 0,
+      hasReport: !!bridge.getFinalReport(d.name),
+    };
+  });
+
+  const latestRun = runs.length > 0 ? runs[0] : null;
+
+  const allDefects = [];
+  for (const d of runDirs) {
+    const result = bridge.getRunResult(d.name);
+    if (result && Array.isArray(result.failedTests)) {
+      for (const ft of result.failedTests) {
+        allDefects.push({
+          runId: d.name,
+          testName: typeof ft === 'string' ? ft : (ft.name || ft.test || 'Unknown'),
+          error: typeof ft === 'string' ? '' : (ft.error || ft.message || ''),
+          runTimestamp: d.name.replace('run-', '').replace(/-/g, ':').slice(0, 19),
+        });
+      }
+    }
+  }
+
+  const totalPassed = runs.reduce((s, r) => s + r.passedCount, 0);
+  const totalFailed = runs.reduce((s, r) => s + r.failedCount, 0);
+  const totalHealed = runs.reduce((s, r) => s + r.healedCount, 0);
+  const totalRuns = runs.length;
+
+  res.render('review', {
+    project,
+    stats: {
+      stories: allFiles.stories.length,
+      plans: allFiles.plans.length,
+      specs: allFiles.specs.length,
+      runs: totalRuns,
+      passed: totalPassed,
+      failed: totalFailed,
+      healed: totalHealed,
+    },
+    latestRun,
+    runs,
+    defects: allDefects,
+  });
+});
+
+router.get('/:runId', (req, res) => {
+  const projectId = req.query.project;
+  const project = projectId ? pm.get(projectId) : pm.getAll()[0];
+  if (!project) return res.redirect('/projects');
+
+  const bridge = pm.getBridge(project.id);
+  const runDirs = bridge.getRunDirs();
+  const runExists = runDirs.some(d => d.name === req.params.runId);
+  if (!runExists) return res.status(404).render('error', { message: 'Review: run not found' });
+
+  let result = bridge.getRunResult(req.params.runId);
+  if (!result) {
+    const outputPath = path.join(bridge.projectPath, 'test-results', req.params.runId, 'execution-output.json');
+    let outputText = 'No console output captured yet.';
+    if (fs.existsSync(outputPath)) {
+      try { outputText = fs.readFileSync(outputPath, 'utf-8'); } catch (err) {}
+    }
+    result = {
+      runId: req.params.runId,
+      success: null,
+      duration: null,
+      test: 'Running / In Progress...',
+      timestamp: new Date().toISOString(),
+      failedTests: [],
+      passedTests: [],
+      output: outputText,
+    };
+  }
+
+  const healing = bridge.getHealingReport(req.params.runId);
+  const report = bridge.getFinalReport(req.params.runId);
+
+  res.render('review', {
+    project,
+    run: {
+      id: req.params.runId,
+      result,
+      healing,
+      report,
+    },
+  });
+});
+
+module.exports = router;

package/qa-dashboard/views/layouts/main.ejs

@@ -17,6 +17,7 @@
         <a href="/projects">Projects</a>
         <a href="/stories">Stories</a>
         <a href="/runs">Runs</a>
+        <a href="/review">Review</a>
         <a href="/analytics">Analytics</a>
         <a href="/data">Test Data</a>
         <button onclick="location.reload()" class="btn-refresh" title="Refresh">↻</button>

package/qa-dashboard/views/review.ejs

@@ -0,0 +1,201 @@
+<% if (typeof run !== 'undefined') { %>
+  <%# ——— SINGLE RUN REVIEW ——— %>
+  <div class="page-header">
+    <div class="page-header-left">
+      <h1><%= project.name %> — Review</h1>
+      <p class="subtitle">Run: <%= run.id %></p>
+    </div>
+    <div class="page-header-right">
+      <a href="/review?project=<%= project.id %>" class="btn">&larr; Back to Overview</a>
+    </div>
+  </div>
+
+  <%# Run Summary %>
+  <div class="card">
+    <h3>Run Summary</h3>
+    <table class="table">
+      <tr><td>Status</td><td>
+        <% if (run.result.success === true) { %><span class="badge badge-success">Passed</span>
+        <% } else if (run.result.success === false) { %><span class="badge badge-danger">Failed</span>
+        <% } else { %><span class="badge badge-warning">In Progress</span><% } %>
+      </td></tr>
+      <tr><td>Duration</td><td><%= run.result.duration || '—' %></td></tr>
+      <tr><td>Test Suite</td><td><%= run.result.test || '—' %></td></tr>
+      <tr><td>Timestamp</td><td><%= run.result.timestamp ? new Date(run.result.timestamp).toLocaleString() : '—' %></td></tr>
+      <tr><td>Failures</td><td><%= Array.isArray(run.result.failedTests) ? run.result.failedTests.length : 0 %></td></tr>
+    </table>
+  </div>
+
+  <%# Test Results %>
+  <div class="card">
+    <h3>Test Results</h3>
+    <% if (Array.isArray(run.result.passedTests) && run.result.passedTests.length > 0) { %>
+      <h4>Passed (<%= run.result.passedTests.length %>)</h4>
+      <ul>
+        <% run.result.passedTests.forEach(function(t) { %>
+          <li style="color: var(--success)"><%= typeof t === 'string' ? t : (t.name || t.test || JSON.stringify(t)) %></li>
+        <% }); %>
+      </ul>
+    <% } %>
+    <% if (Array.isArray(run.result.failedTests) && run.result.failedTests.length > 0) { %>
+      <h4>Failed (<%= run.result.failedTests.length %>)</h4>
+      <% run.result.failedTests.forEach(function(ft) { %>
+        <div class="alert alert-error" style="margin-bottom: 8px;">
+          <strong><%= typeof ft === 'string' ? ft : (ft.name || ft.test || 'Unknown') %></strong>
+          <% if (typeof ft === 'object' && ft.error) { %>
+            <pre style="margin: 4px 0 0; font-size: 13px;"><%= ft.error %></pre>
+          <% } %>
+        </div>
+      <% }); %>
+    <% } %>
+    <% if ((!run.result.passedTests || run.result.passedTests.length === 0) && (!run.result.failedTests || run.result.failedTests.length === 0)) { %>
+      <p>No test results available.</p>
+    <% } %>
+  </div>
+
+  <%# Healing Report %>
+  <% if (run.healing) { %>
+  <div class="card">
+    <h3>Self-Healing Report</h3>
+    <table class="table">
+      <tr><td>Total Healed</td><td><%= run.healing.totalHealed || 0 %></td></tr>
+      <tr><td>Total Attempts</td><td><%= run.healing.totalAttempts || 0 %></td></tr>
+      <tr><td>Remaining Failures</td><td><%= run.healing.remainingFailures || 0 %></td></tr>
+    </table>
+    <% if (Array.isArray(run.healing.healedTests) && run.healing.healedTests.length > 0) { %>
+      <h4>Healed Tests</h4>
+      <% run.healing.healedTests.forEach(function(ht) { %>
+        <div class="card" style="margin-bottom: 8px; padding: 12px;">
+          <strong><%= ht.test || ht.name || 'Unknown' %></strong>
+          <% if (ht.originalSelector) { %><p>Original: <code><%= ht.originalSelector %></code></p><% } %>
+          <% if (ht.newSelector) { %><p>Healed: <code><%= ht.newSelector %></code></p><% } %>
+          <% if (ht.status) { %><span class="badge badge-success"><%= ht.status %></span><% } %>
+        </div>
+      <% }); %>
+    <% } %>
+  </div>
+  <% } %>
+
+  <%# Final Report %>
+  <% if (run.report) { %>
+  <div class="card">
+    <h3>Final Test Report</h3>
+    <div class="markdown-content"><%= run.report %></div>
+  </div>
+  <% } %>
+
+  <%# Console Output %>
+  <% if (run.result.output) { %>
+  <div class="card">
+    <h3>Console Output</h3>
+    <pre class="output-terminal"><%= run.result.output %></pre>
+  </div>
+  <% } %>
+
+<% } else { %>
+  <%# ——— PROJECT REVIEW OVERVIEW ——— %>
+  <div class="page-header">
+    <div class="page-header-left">
+      <h1><%= project.name %> — AI Review</h1>
+      <p class="subtitle">Read-only overview of AI-generated artifacts</p>
+    </div>
+    <div class="page-header-right">
+      <a href="/stories?project=<%= project.id %>" class="btn">View Stories</a>
+      <a href="/runs?project=<%= project.id %>" class="btn">View Runs</a>
+    </div>
+  </div>
+
+  <%# AI Activity Summary %>
+  <div class="stats-row">
+    <div class="stat-card"><span class="stat-number"><%= stats.stories %></span><span class="stat-label">Stories</span></div>
+    <div class="stat-card"><span class="stat-number"><%= stats.plans %></span><span class="stat-label">Test Plans</span></div>
+    <div class="stat-card"><span class="stat-number"><%= stats.specs %></span><span class="stat-label">Test Specs</span></div>
+    <div class="stat-card"><span class="stat-number"><%= stats.runs %></span><span class="stat-label">Runs</span></div>
+    <div class="stat-card"><span class="stat-number"><%= stats.passed %></span><span class="stat-label">Passed</span></div>
+    <div class="stat-card"><span class="stat-number"><%= stats.failed %></span><span class="stat-label">Failed</span></div>
+    <div class="stat-card"><span class="stat-number"><%= stats.healed %></span><span class="stat-label">Healed</span></div>
+  </div>
+
+  <%# Latest Run %>
+  <% if (latestRun) { %>
+  <div class="card">
+    <h3>Latest Run</h3>
+    <table class="table">
+      <tr>
+        <td>Status</td>
+        <td>
+          <% if (latestRun.success === true) { %><span class="badge badge-success">Passed</span>
+          <% } else if (latestRun.success === false) { %><span class="badge badge-danger">Failed</span>
+          <% } else { %><span class="badge badge-warning">Pending</span><% } %>
+        </td>
+      </tr>
+      <tr><td>Test Suite</td><td><%= latestRun.testName %></td></tr>
+      <tr><td>Duration</td><td><%= latestRun.duration || '—' %></td></tr>
+      <tr><td>Passed / Failed / Healed</td><td><%= latestRun.passedCount %> / <%= latestRun.failedCount %> / <%= latestRun.healedCount %></td></tr>
+      <tr><td>Timestamp</td><td><%= latestRun.timestamp %></td></tr>
+      <tr><td><a href="/review/<%= latestRun.id %>?project=<%= project.id %>" class="btn">View Details</a></td></tr>
+    </table>
+  </div>
+  <% } else { %>
+  <div class="alert alert-info">No runs executed yet.</div>
+  <% } %>
+
+  <%# Defects Found %>
+  <% if (defects.length > 0) { %>
+  <div class="card">
+    <h3>Defects Found (<%= defects.length %>)</h3>
+    <table class="table">
+      <thead><tr><th>Test</th><th>Run</th><th>Error</th></tr></thead>
+      <tbody>
+        <% defects.forEach(function(d) { %>
+          <tr>
+            <td><%= d.testName %></td>
+            <td><a href="/review/<%= d.runId %>?project=<%= project.id %>"><%= d.runTimestamp %></a></td>
+            <td><code><%= d.error ? d.error.slice(0, 120) : '—' %></code></td>
+          </tr>
+        <% }); %>
+      </tbody>
+    </table>
+  </div>
+  <% } else { %>
+  <div class="card">
+    <h3>Defects Found</h3>
+    <div class="alert alert-info">No defects found.</div>
+  </div>
+  <% } %>
+
+  <%# AI Timeline %>
+  <% if (runs.length > 0) { %>
+  <div class="card">
+    <h3>AI Activity Timeline</h3>
+    <table class="table">
+      <thead><tr><th>Run</th><th>Timestamp</th><th>Suite</th><th>Status</th><th>Duration</th><th>Passed</th><th>Failed</th><th>Healed</th></tr></thead>
+      <tbody>
+        <% runs.forEach(function(r) { %>
+          <tr>
+            <td><a href="/review/<%= r.id %>?project=<%= project.id %>"><%= r.id.slice(0, 20) %>&hellip;</a></td>
+            <td><%= r.timestamp %></td>
+            <td><%= r.testName %></td>
+            <td>
+              <% if (r.success === true) { %><span class="badge badge-success">Passed</span>
+              <% } else if (r.success === false) { %><span class="badge badge-danger">Failed</span>
+              <% } else { %><span class="badge badge-warning">Pending</span><% } %>
+            </td>
+            <td><%= r.duration || '—' %></td>
+            <td><%= r.passedCount %></td>
+            <td><%= r.failedCount %></td>
+            <td><%= r.healedCount %></td>
+          </tr>
+        <% }); %>
+      </tbody>
+    </table>
+  </div>
+  <% } %>
+
+<% } %>
+
+<style>
+.stat-card { cursor: default; }
+.table a { color: var(--brand); text-decoration: none; }
+.table a:hover { text-decoration: underline; }
+</style>

package/router.md

@@ -1,29 +1,109 @@
-# 🧠 AI QA Workflow - Agent Router (Core Engine)
-
-Tu es l'Intelligence Artificielle (Copilot, RooCode, Cursor,opencode, Antigravity, Gemini, etc.) assignée à ce projet d'automatisation QA.
-Ce projet contient plusieurs profils d'agents (dans `.github/agents/` ou `agents/`) et plusieurs instructions (dans `prompts/`).
-
-**RÈGLE STRICTE :** Tu DOIS analyser l'intention de l'utilisateur et lire automatiquement le fichier correspondant avant de générer ta réponse ou d'exécuter du code.
-
-## 🧭 Routage Automatique du Contexte
-
-### 1. Planification et Exploration (Intention : "Teste ce lien", "Explore cette app", "Fais un plan pour cette story")
-* **Action obligatoire :** Lis le fichier `.github/agents/playwright-test-planner.agent.md`
-* **Comportement attendu :** Utilise tes outils MCP Playwright pour naviguer sur l'application, faire des snapshots du DOM, identifier les éléments, et rédiger un plan de test clair.
-
-### 2. Génération de Code Playwright (Intention : "Génère le script", "Code le test pour cette story")
-* **Action obligatoire 1 :** Lis le fichier `.github/agents/playwright-test-generator.agent.md`
-* **Action obligatoire 2 :** Lis le fichier `prompts/QAe2eprompt.md` pour respecter les conventions du framework.
-* **Comportement attendu :** Rédige les fichiers `.spec.ts` dans le dossier `tests/`. Tu as l'interdiction d'halluciner (deviner) des sélecteurs CSS. Utilise tes outils MCP pour trouver les locators sémantiques exacts (`getByRole`, `getByText`) sur la page réelle.
-
-### 3. Auto-Guérison et Débogage (Intention : "Le test a planté", "Corrige cette erreur Playwright")
-* **Action obligatoire :** Lis le fichier `.github/agents/playwright-test-healer.agent.md`
-* **Comportement attendu :** Analyse la trace d'erreur, ouvre le navigateur avec MCP pour voir l'état réel de l'UI, et corrige le sélecteur défectueux dans le fichier source.
-
-### 4. Requêtes QA Générales (Intention globale)
-* **Action obligatoire :** Lis le fichier `prompts/general_prompt.md`
-
-## ⚠️ Directives Techniques
-* Ne demande jamais la permission de lire ces fichiers, fais-le silencieusement en arrière-plan.
-* Utilise toujours des sélecteurs Playwright robustes et sémantiques.
-* Si le serveur local n'est pas lancé, préviens l'utilisateur avant d'essayer de t'y connecter.
+# AI QA Engineer — Agent Router
+
+You are an **AI QA Engineer** assigned to this project.
+Your mission: transform user stories into tested, reliable software through structured QA.
+
+You have **Playwright MCP** (browser automation), **Applitools MCP** (visual testing), and **GitHub MCP** (version control) tools.
+
+---
+
+## Phase 0: Environment Check (Do This FIRST)
+
+When you first open this project, **automatically run this check and report to the user**:
+
+1. ✅ **Config**: Does `.qa-workflow.json` exist and have project name + URL configured?
+2. ✅ **Context**: Does `docs/application-context.md` exist with content?
+3. ✅ **Memory**: Does `.qa-context/` exist with pipeline.json, selectors.json, heal-history.json, traceability.json?
+4. ✅ **Auth**: Does `.auth/credentials.json` exist with login credentials? Is `.auth/storage-state.json` valid?
+4. ✅ **Playwright**: Is `@playwright/test` installed? (`npx playwright --version`)
+5. ✅ **Chromium**: Is Chromium installed? (`npx playwright install --dry-run chromium`)
+6. ✅ **MCP**: Is `@playwright/mcp` installed?
+7. ✅ **Directories**: Do `user-story/`, `specs/`, `tests/`, `test-results/` exist?
+8. ✅ **Dev server**: Is the app accessible at the configured URL?
+9. ✅ **Applitools**: Is `APPLITOOLS_API_KEY` env var set? (needed for visual testing)
+10. ✅ **GitHub**: Is `GITHUB_TOKEN` env var set? (needed for GitHub MCP)
+
+Present a clean summary:
+- **What's ready** ✅
+- **What's missing** ❌ (with commands to fix)
+- **What you need from the user** 📋 (user story, credentials, etc.)
+- Then **stop and wait** for the user to give you a user story or direction.
+
+**Do not skip this check.** The user needs to know what's missing before anything else.
+
+---
+
+## Phase 1-5: Workflow
+
+Once the user provides a user story or testing request, follow this workflow. **Every phase requires human approval before proceeding.**
+
+### Phase 1: Plan & Explore
+User says: *"Plan tests for this user story"*
+1. Read `.github/agents/playwright-test-planner.agent.md`
+2. Explore the app with Playwright MCP
+3. Write test plan to `specs/`
+4. **STOP** — present the plan to the user
+5. Wait for approval before continuing
+
+### Phase 2: Generate Tests
+User says: *"Generate tests from the plan"*
+1. Read `.github/agents/playwright-test-generator.agent.md`
+2. Read `prompts/QAe2eprompt.md` for conventions
+3. Write Playwright test files to `tests/`
+4. **STOP** — present the generated tests to the user
+5. Wait for approval before executing
+
+### Phase 3: Execute
+User says: *"Execute the tests"*
+1. User runs `npm run qa:execute` (or you suggest it)
+2. Check results — did they pass or fail?
+
+### Phase 4: Heal Failures
+If tests fail, user says: *"Fix the failing tests"*
+1. Read `.github/agents/playwright-test-healer.agent.md`
+2. Debug with Playwright MCP (`test_debug`, `browser_snapshot`, etc.)
+3. Present diagnosis to the user (root cause + proposed 1-3 line fix)
+4. **STOP** — wait for user to approve the fix
+5. Apply fix and re-run
+6. If still failing, mark `test.fixme()` and classify as defect
+
+### Phase 5: Report
+User says: *"Generate the report"*
+1. User runs `npm run qa:report` (or you suggest it)
+2. Present the report summary to the user
+
+---
+
+## ⛔ Human Supervision (Mandatory)
+
+| Phase | You do this | Then wait for approval |
+|-------|------------|----------------------|
+| Plan | Explore app, write plan | User reviews plan |
+| Generate | Write Playwright tests | User reviews code |
+| Execute | Run tests (or tell user to) | User checks results |
+| Heal | Diagnose failure, propose fix | User approves fix |
+| Report | Generate and present | User reviews |
+
+**You never proceed to the next phase without explicit user approval.**
+
+---
+
+## 🧭 Routing Quick Reference
+
+| User intent | Read this |
+|------------|-----------|
+| "Plan tests / Explore the app / Write a test plan" | `.github/agents/playwright-test-planner.agent.md` |
+| "Generate tests / Write test code / Create spec files" | `.github/agents/playwright-test-generator.agent.md` + `prompts/QAe2eprompt.md` |
+| "Fix failing tests / Debug / Heal" | `.github/agents/playwright-test-healer.agent.md` |
+| General QA requests | `prompts/general_prompt.md` |
+
+---
+
+## ⚠️ Technical Rules
+
+- Never hallucinate CSS selectors — use Playwright MCP to find real ones
+- Priority: `data-testid` > `aria-label` > `role` > `text` > `xpath` (last resort)
+- 1 fix attempt max per test. If still failing, it's a defect.
+- 1-3 line targeted edits only. No full file rewrites.
+- If the dev server isn't running, warn the user before trying to connect.
+- Token efficiency: keep responses focused and minimal.

package/scripts/auth-manager.js

@@ -0,0 +1,186 @@
+const path = require('path');
+const fs = require('fs');
+const { DIRS, ensureDir } = require('./utils');
+
+const AUTH_CONFIG_PATH = path.join(DIRS.qaContext, 'auth.json');
+const CREDENTIALS_PATH = path.join(DIRS.auth, 'credentials.json');
+const STORAGE_PATH = path.join(DIRS.auth, 'storage-state.json');
+
+function readJSON(filePath) {
+  if (!fs.existsSync(filePath)) return null;
+  try { return JSON.parse(fs.readFileSync(filePath, 'utf-8')); } catch { return null; }
+}
+
+function writeJSON(filePath, data) {
+  ensureDir(path.dirname(filePath));
+  fs.writeFileSync(filePath, JSON.stringify(data, null, 2), 'utf-8');
+}
+
+const auth = {
+
+  // ── Auth Config (.qa-context/auth.json) ──
+
+  getConfig() {
+    return readJSON(AUTH_CONFIG_PATH) || {
+      methods: [],
+      session: { storage_path: STORAGE_PATH, last_refreshed: null },
+    };
+  },
+
+  saveConfig(config) {
+    writeJSON(AUTH_CONFIG_PATH, config);
+  },
+
+  updateMethod(method) {
+    const config = this.getConfig();
+    const idx = config.methods.findIndex(m => m.id === method.id);
+    if (idx >= 0) config.methods[idx] = method;
+    else config.methods.push(method);
+    this.saveConfig(config);
+    return config;
+  },
+
+  hasMethod() {
+    const config = this.getConfig();
+    return config.methods.length > 0;
+  },
+
+  // ── Credentials (.auth/credentials.json) ──
+
+  saveCredentials(username, password, options = {}) {
+    const creds = { username, password, url: options.url || '', updated_at: new Date().toISOString() };
+    writeJSON(CREDENTIALS_PATH, creds);
+
+    const config = this.getConfig();
+    if (!config.methods.find(m => m.id === 'main-login')) {
+      this.updateMethod({
+        id: 'main-login',
+        type: 'form',
+        detected_at: new Date().toISOString(),
+        login_url: options.url || '/login',
+        fields: [
+          { name: 'username', selector: '', type: 'text' },
+          { name: 'password', selector: '', type: 'password' },
+        ],
+        submit: '',
+        success_indicator: '',
+        last_verified: new Date().toISOString(),
+        status: 'configured',
+      });
+    }
+
+    return creds;
+  },
+
+  getCredentials() {
+    return readJSON(CREDENTIALS_PATH) || null;
+  },
+
+  hasCredentials() {
+    return this.getCredentials() !== null;
+  },
+
+  clearCredentials() {
+    if (fs.existsSync(CREDENTIALS_PATH)) fs.unlinkSync(CREDENTIALS_PATH);
+    if (fs.existsSync(STORAGE_PATH)) fs.unlinkSync(STORAGE_PATH);
+  },
+
+  // ── Session (.auth/storage-state.json) ──
+
+  saveSession(page) {
+    throw new Error('saveSession requires Playwright page — use from AI agent or Playwright context');
+  },
+
+  getStorageStatePath() {
+    return STORAGE_PATH;
+  },
+
+  hasSession() {
+    return fs.existsSync(STORAGE_PATH);
+  },
+
+  clearSession() {
+    if (fs.existsSync(STORAGE_PATH)) fs.unlinkSync(STORAGE_PATH);
+  },
+
+  // ── Login Steps Generator ──
+
+  getLoginSteps(methodId) {
+    const config = this.getConfig();
+    const method = config.methods.find(m => m.id === (methodId || 'main-login'));
+    if (!method) return null;
+
+    const creds = this.getCredentials();
+    if (!creds) return null;
+
+    return {
+      url: method.login_url || creds.url || '/login',
+      fields: method.fields.map(f => ({
+        selector: f.selector,
+        value: f.name === 'username' || f.name === 'email' ? creds.username : creds.password,
+      })),
+      submit: method.submit,
+      success: method.success_indicator,
+    };
+  },
+
+  generateSetupCode() {
+    const config = this.getConfig();
+    const method = config.methods.find(m => m.id === 'main-login');
+    const creds = this.getCredentials();
+    if (!method || !creds) return null;
+
+    const storagePath = STORAGE_PATH.replace(/\\/g, '/');
+    const fields = method.fields.map(f => {
+      const val = f.name === 'username' || f.name === 'email' ? 'credentials.username' : 'credentials.password';
+      return `    await page.locator('${f.selector || ''}').fill(${val});`;
+    }).join('\n');
+
+    return `import { test as setup, expect } from '@playwright/test';
+import path from 'path';
+
+const AUTH_FILE = path.resolve(__dirname, '..', '${storagePath}');
+const CREDENTIALS = require('${CREDENTIALS_PATH.replace(/\\/g, '/')}');
+
+setup('authenticate', async ({ page }) => {
+  await page.goto('${method.login_url || creds.url || '/'}');
+${fields}
+  await page.locator('${method.submit || ''}').click();
+  await page.waitForURL('**${method.success_indicator || ''}**');
+  await page.context().storageState({ path: AUTH_FILE });
+});`;
+  },
+
+  // ── Auth Failure Detection ──
+
+  isAuthFailure(error) {
+    if (!error) return false;
+    const msg = typeof error === 'string' ? error : (error.message || error.error || '');
+    const patterns = [
+      'login', 'unauthorized', 'unauthenticated', '401', '403',
+      'session expired', 'invalid token', 'redirected to login',
+      'sign in', 'authentication required', 'credentials',
+    ];
+    return patterns.some(p => msg.toLowerCase().includes(p));
+  },
+
+  // ── Init ──
+
+  init() {
+    ensureDir(DIRS.auth);
+
+    if (!fs.existsSync(AUTH_CONFIG_PATH)) {
+      this.saveConfig({
+        methods: [],
+        session: { storage_path: STORAGE_PATH, last_refreshed: null },
+      });
+    }
+
+    const gitignorePath = path.join(DIRS.auth, '.gitignore');
+    if (!fs.existsSync(gitignorePath)) {
+      fs.writeFileSync(gitignorePath, '# Auth credentials and Playwright storage state\n*\n', 'utf-8');
+    }
+  },
+};
+
+module.exports = auth;