@qatonic_innovations/qaios 0.1.1 → 0.1.2

package/README.md

@@ -10,6 +10,18 @@ QAIOS acts like a QA engineer on your team. Point it at a feature description or
 
 **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
@@ -23,18 +35,39 @@ The published package is `@qatonic_innovations/qaios`; the installed **command i
 
 ### Requirements
 
-- **Node.js 20 LTS or newer**
-- An **Anthropic API key** in your environment:
+- **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 (new shell after)
+  setx ANTHROPIC_API_KEY "sk-ant-..."      # Windows (open a NEW shell after)
   ```
-- **Playwright** in your project, for `qaios run` / `snapshot` / `a11y`:
+  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
@@ -158,7 +191,26 @@ 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.
+- **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.
 
 ---
 

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.1",
+  "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/shared": "0.0.0",
-    "@qaios/skills": "0.0.0"
+    "ink-testing-library": "^4.0.0"
   },
   "scripts": {
     "build": "tsup && node scripts/copy-templates.mjs && node scripts/copy-runtime-assets.mjs",