@qatonic_innovations/qaios 0.1.0 → 0.1.2

package/README.md

@@ -0,0 +1,248 @@
+# QAIOS
+
+> **AI QA engineer in your terminal.** Designs, writes, runs, heals, and explores tests for web UI and APIs — with audit-grade traceability.
+
+[![npm version](https://img.shields.io/npm/v/@qatonic_innovations/qaios.svg)](https://www.npmjs.com/package/@qatonic_innovations/qaios)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://github.com/qatonic/qaios/blob/main/LICENSE)
+[![Node](https://img.shields.io/node/v/@qatonic_innovations/qaios.svg)](https://nodejs.org)
+
+QAIOS acts like a QA engineer on your team. Point it at a feature description or an OpenAPI spec; it produces a test design, generates Playwright code, runs the tests, classifies failures, heals broken locators, files defects, scans for accessibility issues, and keeps a hash-chained audit log of every decision.
+
+**Mental model: Claude Code, but for QA work instead of feature coding.**
+
+> **Status: early alpha (v0.1).** Core flows — `init`, `doctor`, test design
+> & generation, Playwright execution, self-healing, accessibility, and the
+> audit log — work today. Expect rough edges and please
+> [report issues](https://github.com/qatonic/qaios/issues). After installing,
+> a quick smoke test confirms everything resolves:
+>
+> ```bash
+> qaios --version
+> qaios --help
+> qaios doctor          # checks Node, API key, Playwright, config
+> ```
+
+---
+
+## Install
+
+```bash
+npm install -g @qatonic_innovations/qaios
+# or:  pnpm add -g @qatonic_innovations/qaios
+```
+
+The published package is `@qatonic_innovations/qaios`; the installed **command is `qaios`**.
+
+### Requirements
+
+- **Node.js 20 LTS recommended.** QAIOS bundles a native SQLite module
+  (better-sqlite3) for its local audit log; Node 20 LTS has the widest
+  prebuilt-binary coverage. Newer Node usually works but may need to compile
+  the binary (build tools + network access).
+- An **Anthropic API key** — get one at
+  [console.anthropic.com](https://console.anthropic.com/settings/keys), then
+  put it in your environment:
+  ```bash
+  export ANTHROPIC_API_KEY=sk-ant-...      # macOS/Linux
+  setx ANTHROPIC_API_KEY "sk-ant-..."      # Windows (open a NEW shell after)
+  ```
+  The key is read from the environment and **never written to disk** by QAIOS.
+- **Playwright** in your project, for `qaios run` / `snapshot` / `explore` / `a11y`:
+  ```bash
+  npm i -D @playwright/test && npx playwright install
+  ```
+  (`@playwright/test` is for `run`; `explore`/`a11y` use the `playwright`
+  package, which it pulls in.)
+- For `qaios a11y`, also: `npm i -D @axe-core/playwright`
+
+### Install troubleshooting
+
+If `qaios init` fails with a SQLite/native-binding error
+(`Could not load the native SQLite module`):
+
+- Confirm your Node version: `node -v` (prefer 20 LTS).
+- Rebuild the binary: `npm rebuild better-sqlite3` — or reinstall qaios.
+- Behind a proxy/firewall? The prebuilt binary is fetched from GitHub
+  release assets; allow that host, or install C/C++ build tools so it can
+  compile locally.
+
+`qaios doctor` will tell you exactly which check failed and what to run.
+
+---
+
+## 60-second quick start
+
+```bash
+cd my-app
+qaios init                       # creates .qaios/, QAIOS.md; detects Playwright
+qaios doctor                     # verify your environment is ready
+
+# Generate tests from plain English, then run them:
+qaios test "user can log in with email and password" --run
+```
+
+`qaios test` produces a DesignSpec, a Playwright spec, and a Page Object — then (`--run`) executes them. That's the core loop.
+
+```text
+workflow: 01JTZ1MV7Q8X3R2WFP9D5K8YRH
+
+▸ requirements.intake   ✓  (2 reqs,  confidence 0.85)
+▸ risk.score            ✓  (overall HIGH — touches PII)
+▸ design.web            ✓  (4 scenarios, confidence 0.84)
+▸ write.web             ✓  (1 spec, 4 tests, 1 page object)
+
+Generated:
+  tests/auth/login.spec.ts          (4 tests)
+  tests/auth/LoginPage.po.ts
+  .qaios/specs/01JTZ1…/DesignSpec.json
+
+Cost: 11,403 tokens · $0.06 (3 of 15 LLM calls used)
+```
+
+> **Gates:** on HIGH/CRITICAL-risk features QAIOS pauses for review. Approve interactively with `qaios review`, or pass `--yes` to auto-approve for a non-interactive run.
+
+---
+
+## What each command does
+
+| Command                                              | What it does                                                                                                                |
+| ---------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------- |
+| `qaios init [path]`                                  | Bootstrap a project: create `.qaios/`, `QAIOS.md`, run migrations.                                                          |
+| `qaios doctor`                                       | Health-check your environment (Node, API key, Playwright, config). `--json` for CI.                                         |
+| `qaios test <description>`                           | Design + generate tests from natural language. `--type api` for OpenAPI. `--run` to execute. `--yes` to auto-approve gates. |
+| `qaios run [pattern]`                                | Execute Playwright tests, classify failures (real / flaky / locator drift), auto-heal locator breaks, file defects.         |
+| `qaios fix [target]`                                 | Self-heal a broken locator. `--last-failure` to target the most recent failure, `--auto` to apply, `--dry-run` to preview.  |
+| `qaios explore <url>`                                | Time-boxed exploratory session against a live URL. `--duration <seconds>`, `--focus "<hint>"`.                              |
+| `qaios a11y <url>`                                   | Deterministic axe-core accessibility scan + AI triage. `--wcag-level A\|AA\|AAA`. Exits 1 on real violations (CI-gateable). |
+| `qaios snapshot capture\|check\|review`              | Visual regression: capture baselines, diff, and triage AI-classified diffs.                                                 |
+| `qaios review`                                       | Walk pending human-review gates and approve/reject; resumes the workflow.                                                   |
+| `qaios history [--verify]`                           | List workflows, inspect the audit log, and verify the hash chain.                                                           |
+| `qaios config get\|set\|show\|edit`                  | Read/write `.qaios/config.yaml` (schema-validated).                                                                         |
+| `qaios mcp list\|add\|remove\|enable\|disable\|test` | Manage MCP servers (GitHub, Jira, Slack, custom).                                                                           |
+
+Run `qaios <command> --help` for the full option list of any command.
+
+### Common workflows
+
+```bash
+# Generate API tests from an OpenAPI spec
+qaios test --type api --spec ./openapi.yaml "exercise the /orders endpoints"
+
+# Run a suite; QAIOS classifies failures and self-heals locator drift
+qaios run
+
+# Heal a specific broken test, previewing the patch first
+qaios fix tests/auth/login.spec.ts --last-failure --dry-run
+
+# Accessibility scan, gate CI on real WCAG violations
+qaios a11y https://staging.myapp.com --wcag-level AA
+
+# Exploratory testing with a focus hint
+qaios explore https://staging.myapp.com --duration 900 --focus "checkout flow"
+
+# Visual regression
+qaios snapshot capture        # baseline
+# ...change CSS...
+qaios snapshot check          # diff
+qaios snapshot review         # triage interactively
+```
+
+---
+
+## Configuration
+
+Config lives in `.qaios/config.yaml` (created by `qaios init`):
+
+```yaml
+version: 1
+mode: LITE # LITE | FULL | TRUST
+app:
+  baseUrl: https://staging.myapp.com
+llm:
+  provider: anthropic
+  apiKeyEnv: ANTHROPIC_API_KEY # key is read from env, never stored
+  maxLlmCallsPerWorkflow: 15
+  costAlertThresholdUsdCents: 50
+testing:
+  framework: playwright
+  testDir: tests
+  testIdAttribute: data-testid # e.g. set to 'data-test' for some apps
+  locatorPreference: [data-testid, role, text]
+gates:
+  autoExpireOnTimeout: abort # abort | auto_approve | auto_reject
+defects:
+  target: stdout # stdout | github | jira
+```
+
+`qaios config show` prints the resolved config; `qaios config set <key> <value>` validates against the schema before writing. **API keys are never written to config** — they come from environment variables.
+
+### Operating modes
+
+- **LITE** (default) — HIGH/CRITICAL risk pauses for review; routine work flows through.
+- **FULL** — every gate active, every AI decision reviewable.
+- **TRUST** — auto-approve when confidence > 0.85 and risk ≤ MEDIUM; CRITICAL still notifies.
+
+```bash
+qaios config set mode TRUST
+```
+
+---
+
+## Cost & privacy
+
+- All v0.1 skills use Claude Sonnet. A typical `qaios test` costs ~**$0.04–0.10**. Each workflow is capped (default `min(15 calls, $0.50)`, configurable) and aborts if exceeded.
+- **Local-first.** No telemetry, no phone-home. The only outbound traffic is (a) LLM calls to Anthropic with the prompts QAIOS builds, and (b) any MCP servers you configure. You bring your own API key; QAIOS does not proxy your requests. See [SECURITY.md](https://github.com/qatonic/qaios/blob/main/SECURITY.md) for exactly what's sent.
+
+---
+
+## Exit codes (for CI)
+
+Every command exits with a stable, documented code so you can gate pipelines:
+
+| Code  | Meaning                         | Example                                                                 |
+| ----- | ------------------------------- | ----------------------------------------------------------------------- |
+| `0`   | Success                         | tests generated; `doctor` all-green; `a11y` clean                       |
+| `1`   | User error / actionable failure | bad flag; `a11y` found real violations; `run` had failing tests         |
+| `2`   | Gate blocked (informational)    | a workflow paused for human review — run `qaios review` or pass `--yes` |
+| `3`   | Tool/dependency error           | Playwright or axe not installed; SQLite binding missing                 |
+| `4`   | LLM error                       | rate limit, timeout, or invalid API key                                 |
+| `5`   | Internal error                  | unexpected crash (re-run with `--debug` for a stack trace)              |
+| `130` | Cancelled                       | you pressed Ctrl+C                                                      |
+
+`qaios doctor --json` and `--json` on most commands emit machine-readable
+output for CI consumption.
+
+---
+
+## Documentation
+
+- [Getting Started](https://github.com/qatonic/qaios/blob/main/docs/getting-started.md) — first 15 minutes
+- [Commands Reference](https://github.com/qatonic/qaios/blob/main/docs/commands.md) — every CLI command
+- [Skills Reference](https://github.com/qatonic/qaios/blob/main/docs/skills-reference.md) — what each skill does
+- [MCP Servers](https://github.com/qatonic/qaios/blob/main/docs/mcp-servers.md) — adding integrations
+- A runnable end-to-end example lives in [`examples/live-saucedemo`](https://github.com/qatonic/qaios/tree/main/examples/live-saucedemo).
+
+---
+
+## Status & roadmap
+
+**v0.1 (now):** Web UI + API + visual regression + self-healing + exploratory + accessibility, as an open-source CLI. Early — feedback wanted.
+
+- **v0.2** — optional cloud sync + web dashboard
+- **v0.5** — mobile testing
+- **v0.7** — performance + security testing
+- **v1.0** — database testing, stable public API
+
+The roadmap is gated on real-world validation, not a calendar.
+
+---
+
+## Links
+
+- **Repository:** https://github.com/qatonic/qaios
+- **Report a bug:** https://github.com/qatonic/qaios/issues
+- **Discuss / request a feature:** https://github.com/qatonic/qaios/discussions
+
+## License
+
+[MIT](https://github.com/qatonic/qaios/blob/main/LICENSE). The CLI will always remain MIT; cloud features (v0.2+) ship under a separate license.

package/dist/a11y/scripts/axe-runner.mjs

@@ -19,6 +19,26 @@
 //   0 = success (even when violations were found)
 
 import { writeFileSync } from 'node:fs';
+import { createRequire } from 'node:module';
+import path from 'node:path';
+import { pathToFileURL } from 'node:url';
+
+// Resolve a package from the USER's project (process.cwd()), not from
+// where this script physically lives (inside QAIOS's install dir). With a
+// bare `import('playwright')`, Node resolves relative to THIS file — so a
+// globally-installed QAIOS can't see the user's locally-installed
+// playwright. Resolving via a require rooted at the project's package.json
+// (falling back to cwd) and importing the resolved file URL fixes that.
+const projectRequire = createRequire(path.join(process.cwd(), 'package.json'));
+// Resolve from the user's project, but import the BARE specifier so Node
+// honors the package's `exports` map (giving the proper ESM shape). We only
+// use require.resolve to (a) verify the package exists in the project and
+// (b) make the bare import resolvable, by importing the resolved entry and
+// reading a named property off it. Returns the live module namespace.
+const importFromProject = async (specifier) => {
+  const resolved = projectRequire.resolve(specifier); // throws if not installed
+  return import(pathToFileURL(resolved).href);
+};
 
 const url = process.env.QAIOS_AXE_URL;
 const out = process.env.QAIOS_AXE_OUTPUT;
@@ -36,8 +56,14 @@ if (!url || !out) {
 
 let chromium, AxeBuilder;
 try {
-  ({ chromium } = await import('playwright'));
-  ({ default: AxeBuilder } = await import('@axe-core/playwright'));
+  // Importing a CJS entry via file URL nests the package's exports under
+  // `default`; importing an ESM entry exposes them as named. Read from
+  // whichever is present so both layouts work.
+  const pw = await importFromProject('playwright');
+  chromium = pw.chromium ?? pw.default?.chromium;
+  const axe = await importFromProject('@axe-core/playwright');
+  AxeBuilder = axe.default ?? axe.AxeBuilder;
+  if (!chromium || !AxeBuilder) throw new Error('resolved module missing expected export');
 } catch (err) {
   process.stderr.write(
     `axe-runner: failed to load 'playwright' and '@axe-core/playwright' from the project — ` +

package/dist/healing/scripts/capture-page.mjs

@@ -12,6 +12,20 @@
 // via truncateHtmlSafe so the script stays decoupled from the budget.
 
 import { writeFileSync } from 'node:fs';
+import { createRequire } from 'node:module';
+import path from 'node:path';
+import { pathToFileURL } from 'node:url';
+
+// Resolve `playwright` from the USER's project (process.cwd()), not from
+// where this script lives inside QAIOS's install dir. A bare
+// `import('playwright')` resolves relative to THIS file, so a globally
+// installed QAIOS can't see the user's local playwright. See axe-runner.mjs
+// for the full rationale.
+const projectRequire = createRequire(path.join(process.cwd(), 'package.json'));
+const importFromProject = async (specifier) => {
+  const resolved = projectRequire.resolve(specifier); // throws if not installed
+  return import(pathToFileURL(resolved).href);
+};
 
 const url = process.env.QAIOS_CAPTURE_URL;
 const out = process.env.QAIOS_CAPTURE_OUTPUT;
@@ -27,7 +41,9 @@ if (!url || !out) {
 
 let chromium;
 try {
-  ({ chromium } = await import('playwright'));
+  const pw = await importFromProject('playwright');
+  chromium = pw.chromium ?? pw.default?.chromium;
+  if (!chromium) throw new Error('playwright resolved but has no chromium export');
 } catch (err) {
   process.stderr.write(
     `capture-page: failed to load 'playwright' from project — is it installed? ${err?.message ?? err}\n`,

package/dist/index.js

@@ -2,7 +2,7 @@
 import { useApp, useInput, Box, Text } from 'ink';
 import { useState } from 'react';
 import { jsx, jsxs } from 'react/jsx-runtime';
-import { readFileSync, existsSync, rmSync, mkdirSync, writeFileSync, statSync, mkdtempSync, copyFileSync, readdirSync } from 'fs';
+import { realpathSync, readFileSync, existsSync, rmSync, mkdirSync, writeFileSync, statSync, mkdtempSync, copyFileSync, readdirSync } from 'fs';
 import path12 from 'path';
 import { fileURLToPath } from 'url';
 import { Command, InvalidArgumentError } from 'commander';
@@ -2708,13 +2708,14 @@ function resolveSpawn(bin, args) {
   }
   return { bin: resolved, args };
 }
+var SUPPRESSED_WARNING_CODES = /* @__PURE__ */ new Set(["DEP0190", "DEP0040"]);
 var _filterInstalled = false;
 function installDeprecationWarningFilter() {
   if (_filterInstalled) return;
   _filterInstalled = true;
   process.removeAllListeners("warning");
   process.on("warning", (w) => {
-    if (w.code === "DEP0190") return;
+    if (w.code !== void 0 && SUPPRESSED_WARNING_CODES.has(w.code)) return;
     process.stderr.write(`(node:${process.pid}) ${w.name}: ${w.message}
 `);
     if (w.stack !== void 0) process.stderr.write(`${w.stack}
@@ -8547,6 +8548,18 @@ async function runExplore(opts) {
       }
     };
   }
+  if (opts.duration !== void 0) {
+    const d = opts.duration;
+    if (!Number.isFinite(d) || !Number.isInteger(d) || d < 60) {
+      return {
+        exitCode: ExitCode.USER_ERROR,
+        error: {
+          code: "qaios.explore.invalid_duration",
+          message: `--duration must be a whole number of seconds \u2265 60 (got ${String(d)}).`
+        }
+      };
+    }
+  }
   const config = loadConfig2(cwd);
   const memory = loadProjectMemory(cwd);
   const mode = opts.mode ?? config?.mode ?? "LITE";
@@ -9594,8 +9607,6 @@ function runInit(opts = {}) {
   if (existsSync(qaiosDir) && opts.force) {
     rmSync(qaiosDir, { recursive: true, force: true, maxRetries: 5, retryDelay: 100 });
   }
-  mkdirSync(qaiosDir, { recursive: true });
-  const filesWritten = [];
   const modeParse = Mode.safeParse(opts.mode ?? "LITE");
   if (!modeParse.success) {
     return {
@@ -9614,9 +9625,7 @@ function runInit(opts = {}) {
       testDir: opts.testDir ?? detection.testDir ?? "tests"
     }
   });
-  const configPath = path12.join(qaiosDir, "config.yaml");
-  writeFileSync(configPath, stringify(config), "utf-8");
-  filesWritten.push(path12.relative(cwd, configPath));
+  mkdirSync(qaiosDir, { recursive: true });
   const dbPath = path12.join(qaiosDir, "workflows.db");
   let migrations;
   try {
@@ -9624,16 +9633,33 @@ function runInit(opts = {}) {
     migrations = storage.runMigrations();
     storage.close();
   } catch (err) {
+    try {
+      rmSync(qaiosDir, { recursive: true, force: true, maxRetries: 3, retryDelay: 100 });
+    } catch {
+    }
+    const raw = err.message ?? String(err);
+    const isBindingError = /bindings file|was compiled against|NODE_MODULE_VERSION|\.node/i.test(
+      raw
+    );
+    const message = isBindingError ? `Could not load the native SQLite module (better-sqlite3). This usually means the prebuilt binary didn't download or doesn't match your Node version.
+  \u2022 Ensure you're on Node 20 LTS (run \`node -v\`).
+  \u2022 Reinstall to fetch/rebuild the binary: \`npm rebuild better-sqlite3\` (or reinstall qaios).
+  \u2022 Behind a proxy/firewall? The binary is fetched from GitHub releases \u2014 allow that, or install build tools so it can compile.
+Original error: ${raw}` : `Failed to initialise workflows.db: ${raw}`;
     return {
-      exitCode: ExitCode.INTERNAL,
+      exitCode: err instanceof StorageError ? ExitCode.INTERNAL : ExitCode.TOOL_ERROR,
       error: {
-        code: err instanceof StorageError ? err.code : "qaios.init.db_failed",
-        message: `Failed to initialise workflows.db: ${err.message}`
+        code: isBindingError ? "qaios.init.sqlite_binding_missing" : err instanceof StorageError ? err.code : "qaios.init.db_failed",
+        message
       },
       detection
     };
   }
+  const filesWritten = [];
   filesWritten.push(path12.relative(cwd, dbPath));
+  const configPath = path12.join(qaiosDir, "config.yaml");
+  writeFileSync(configPath, stringify(config), "utf-8");
+  filesWritten.push(path12.relative(cwd, configPath));
   const gitignorePath = path12.join(qaiosDir, ".gitignore");
   writeFileSync(gitignorePath, QAIOS_GITIGNORE, "utf-8");
   filesWritten.push(path12.relative(cwd, gitignorePath));
@@ -12015,13 +12041,19 @@ function formatDoctor(checks) {
   return lines.join("\n");
 }
 var invokedAsScript = (() => {
-  try {
-    const argv1 = process.argv[1];
-    if (!argv1) return false;
-    return path12.resolve(argv1) === fileURLToPath(import.meta.url);
-  } catch {
-    return false;
-  }
+  const argv1 = process.argv[1];
+  if (!argv1) return false;
+  const thisFile = fileURLToPath(import.meta.url);
+  const realOf = (p) => {
+    try {
+      return realpathSync(p);
+    } catch {
+      return path12.resolve(p);
+    }
+  };
+  if (realOf(argv1) === realOf(thisFile)) return true;
+  const invokedName = path12.basename(argv1).replace(/\.(js|mjs|cjs)$/, "");
+  return invokedName === "qaios";
 })();
 if (invokedAsScript) {
   installDeprecationWarningFilter();

package/dist/visual/scripts/capture-screenshot.mjs

@@ -18,6 +18,19 @@
 // used unconditionally for stability — same input → same PNG → same SHA.
 
 import { writeFileSync } from 'node:fs';
+import { createRequire } from 'node:module';
+import path from 'node:path';
+import { pathToFileURL } from 'node:url';
+
+// Resolve `playwright` from the USER's project (process.cwd()), not from
+// where this script lives in QAIOS's install dir. See axe-runner.mjs for
+// the full rationale (a bare import resolves relative to this file, so a
+// global QAIOS can't see the user's local playwright).
+const projectRequire = createRequire(path.join(process.cwd(), 'package.json'));
+const importFromProject = async (specifier) => {
+  const resolved = projectRequire.resolve(specifier);
+  return import(pathToFileURL(resolved).href);
+};
 
 const url = process.env.QAIOS_SCREENSHOT_URL;
 const out = process.env.QAIOS_SCREENSHOT_OUTPUT;
@@ -37,7 +50,9 @@ const fullPage = process.env.QAIOS_SCREENSHOT_FULL_PAGE !== '0';
 
 let chromium;
 try {
-  ({ chromium } = await import('playwright'));
+  const pw = await importFromProject('playwright');
+  chromium = pw.chromium ?? pw.default?.chromium;
+  if (!chromium) throw new Error('playwright resolved but has no chromium export');
 } catch (err) {
   process.stderr.write(
     `capture-screenshot: failed to load 'playwright' from project — is it installed? ${err?.message ?? err}\n`,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@qatonic_innovations/qaios",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "type": "module",
   "description": "AI QA engineer in your terminal — designs, writes, runs, heals, and explores tests for web UI and APIs with audit-grade traceability.",
   "license": "MIT",
@@ -65,10 +65,7 @@
     "@types/pixelmatch": "^5.2.6",
     "@types/pngjs": "^6.0.5",
     "@types/react": "^18.3.28",
-    "ink-testing-library": "^4.0.0",
-    "@qaios/runtime": "0.0.0",
-    "@qaios/skills": "0.0.0",
-    "@qaios/shared": "0.0.0"
+    "ink-testing-library": "^4.0.0"
   },
   "scripts": {
     "build": "tsup && node scripts/copy-templates.mjs && node scripts/copy-runtime-assets.mjs",