qa-deck-backend 1.0.0

package/.env.example

@@ -0,0 +1,6 @@
+# QA Deck Backend — Environment Config
+# Copy this to .env and fill in your values
+
+# Server port (default: 3747)
+# This is the only environment variable currently read by server.js.
+PORT=3747

package/README.md

@@ -0,0 +1,126 @@
+# QA Deck — Backend API
+
+Local Node.js backend for the QA Deck Chrome extension.
+
+It provides:
+- AI generation endpoints used by the extension
+- disk-backed project storage
+- a Playwright-powered recorder
+- static dashboard pages for projects and recording
+
+The server entry point is `server.js`.
+
+## Start
+
+In a clean checkout, install dependencies first:
+
+```bash
+npm install
+npm start
+# or
+./start.sh
+```
+
+Server starts on `http://localhost:3747`.
+
+## Endpoints
+
+| Method | Path | Description |
+|--------|------|-------------|
+| GET | `/api/health` | Health check and project count |
+| POST | `/api/generate-tests` | Generate test cases from extracted page data |
+| POST | `/api/generate-script` | Generate automation scripts |
+| POST | `/api/save-project` | Save a project to disk |
+| GET | `/api/projects` | List saved projects |
+| GET | `/api/projects/:id` | Fetch a specific project |
+| POST | `/api/generate-cicd` | Generate CI/CD starter files |
+| POST | `/api/record/start` | Start a recorder session |
+| GET | `/api/record/sessions` | List recorder sessions |
+| GET | `/api/proxy` | Proxy a page into the recorder dashboard |
+
+## Request format
+
+### POST /api/generate-tests
+
+```json
+{
+  "pageData": { "...": "From the extension content script" },
+  "apiKey": "provider-specific key"
+}
+```
+
+### POST /api/generate-script
+
+```json
+{
+  "testCases": [],
+  "pageData": {},
+  "framework": "selenium-python | selenium-java | playwright-python | playwright-typescript",
+  "apiKey": "provider-specific key"
+}
+```
+
+## Architecture
+
+```text
+Extension                     Backend                    Provider API
+   |                             |                           |
+   |- SCAN_PAGE ---------------> | not involved              |
+   |                             |                           |
+   |- GENERATE_TESTS ----------> | POST /api/generate-tests  |
+   |                             |-------------------------->|
+   |                             |<--------------------------|
+   |<----------------------------| { testCases: [...] }      |
+   |                             |                           |
+   |- GENERATE_SCRIPT ---------> | POST /api/generate-script |
+   |                             |-------------------------->|
+   |                             |<--------------------------|
+   |<----------------------------| { scripts: {...} }        |
+   |                             |                           |
+   |- RECORD / CI-CD ----------> | local-only routes         |
+```
+
+If the backend is offline, the extension falls back to direct browser-side provider calls for test generation, script generation, and local project storage. Recorder features remain backend-only.
+
+## Offline / Fallback mode
+
+When the backend is unreachable:
+- generation calls are made directly from the extension service worker
+- projects are saved in `chrome.storage.local` instead of disk
+- the side panel shows `Direct API mode`
+- recorder and dashboard features are unavailable
+
+## Projects storage
+
+Projects are saved as JSON files in `./projects/`:
+
+```text
+projects/
+  abc123.json
+  def456.json
+```
+
+## Rate limiting
+
+The current code allows up to 300 requests/minute per non-local IP and skips rate limiting for localhost recorder traffic. If you change that behavior, update this document at the same time.
+
+## Port
+
+Default:
+
+```bash
+PORT=3747 npm start
+```
+
+Override:
+
+```bash
+PORT=4000 npm start
+```
+
+## Notes for contributors
+
+- `package.json` includes convenience scripts for `start` and `dev`
+- `.env.example` documents only the environment variables currently used by the server
+- `playwright` is required for recorder functionality
+- generated project files and `node_modules/` should not be treated as source files

package/bin/cli.js

@@ -0,0 +1,36 @@
+#!/usr/bin/env node
+
+const { execSync, spawn } = require("child_process");
+const path = require("path");
+const fs = require("fs");
+
+const serverPath = path.join(__dirname, "..", "server.js");
+
+// Check if Playwright Chromium is installed, install if not
+function ensurePlaywright() {
+  try {
+    const cacheDir = path.join(require("os").homedir(), ".cache", "ms-playwright");
+    const hasChromium = fs.existsSync(cacheDir) &&
+      fs.readdirSync(cacheDir).some(d => d.startsWith("chromium"));
+    if (!hasChromium) {
+      console.log("Installing Playwright browser (first run only)...");
+      execSync("npx playwright install chromium", { stdio: "inherit" });
+    }
+  } catch {
+    // Non-fatal — server will show error when Capture is used
+  }
+}
+
+ensurePlaywright();
+
+console.log("\n🚀 QA Deck Backend starting...");
+console.log("   Keep this Terminal window open while using Capture.\n");
+
+const server = spawn("node", [serverPath], { stdio: "inherit" });
+
+server.on("exit", (code) => process.exit(code ?? 0));
+
+process.on("SIGINT", () => {
+  server.kill("SIGINT");
+  process.exit(0);
+});