@qatonic_innovations/qaios 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 QATONIC
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/QAIOS.md.template

@@ -0,0 +1,70 @@
+# QAIOS Project Memory
+
+> Auto-generated by `qaios init`. Hand-edit this file as your project grows —
+> QAIOS reads it before every skill invocation and uses it to bias test design,
+> writing, and classification toward your conventions.
+
+## Project Overview
+
+{{projectName}}
+
+<!-- Replace with a few sentences about what this app does, who uses it, and
+     what "working correctly" means at a high level. -->
+
+## Stack
+
+- **Frontend:** {{stack}}
+- **Backend:** <add your backend>
+- **Database:** <add your database>
+- **Test framework:** {{testFramework}}
+
+## Test Conventions
+
+- **Test directory:** `{{testDir}}/`
+- **Spec naming:** `<feature>.spec.ts`
+- **Locator preference:** `data-testid` > `role` > `text`
+- **Avoid:** CSS class selectors (volatile), absolute XPath, locators based on
+  generated styles or transient classes
+- **Test-id attribute:** Playwright's `getByTestId()` resolves `data-testid` by
+  default. If your app uses a different attribute (e.g. `data-test`, `data-qa`),
+  set `testing.testIdAttribute` in `.qaios/config.yaml` so generated specs find
+  your elements — otherwise every `getByTestId` locator times out.
+
+## Risk Hotspots
+
+<!-- Modules / flows that warrant heavy testing. QAIOS escalates risk on
+     anything touching these areas. Examples below; replace with yours. -->
+
+- Authentication flow (PII, lockout logic)
+- Payment processing (idempotency, webhooks)
+- File uploads (size limits, MIME validation)
+
+## Domain Oracles
+
+<!-- What "correct" means for your specific app. Concrete, observable
+     post-conditions QAIOS can assert against. -->
+
+- A successful login: redirect to `/dashboard`, session cookie set, user email
+  visible in nav
+- A successful payment: order in `confirmed` state, email sent, audit trail
+  entry written
+
+## Test Data
+
+- **Seed script:** `<path/to/seed-script>`
+- **Test users:** see `<fixtures path>`
+- **PII rule:** never use real emails — always `*@qaios.test`
+
+## CI Context
+
+- **Runs on:** <e.g. GitHub Actions, ubuntu-latest>
+- **Env file:** `<path/to/staging.env>`
+- **Quarantine policy:** flaky tests auto-skip after 3 consecutive failures,
+  re-evaluated weekly
+
+## Known Flakiness
+
+<!-- Document specific known-flaky tests or routes. QAIOS uses this to bias
+     classification away from labelling these as real failures. -->
+
+- _(none yet — add here as patterns emerge)_

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

@@ -0,0 +1,82 @@
+#!/usr/bin/env node
+// axe-runner.mjs — deterministic accessibility scan for `qaios a11y`.
+//
+// Runs in the USER's project (cwd) so it can dynamic-import their
+// installed `@axe-core/playwright` + `playwright` packages — QAIOS
+// bundles neither. Reads inputs from env vars:
+//   QAIOS_AXE_URL          — target URL (required)
+//   QAIOS_AXE_OUTPUT       — output path for the findings JSON (required)
+//   QAIOS_AXE_TIMEOUT_MS   — navigation timeout (default 30_000)
+//   QAIOS_AXE_TAGS         — comma-separated axe tags (default wcag2a,wcag2aa)
+//   QAIOS_AXE_WAIT_UNTIL   — load|domcontentloaded|networkidle (default 'domcontentloaded')
+//
+// Emits axe-core's findings (violations + incomplete, each tagged with a
+// `kind`: 'violation' | 'incomplete' | 'best_practice') as the
+// deterministic source of truth. Exit codes mirror capture-page.mjs:
+//   2 = missing env vars
+//   3 = @axe-core/playwright or playwright not installed
+//   4 = navigation / scan error
+//   0 = success (even when violations were found)
+
+import { writeFileSync } from 'node:fs';
+
+const url = process.env.QAIOS_AXE_URL;
+const out = process.env.QAIOS_AXE_OUTPUT;
+const timeoutMs = Number.parseInt(process.env.QAIOS_AXE_TIMEOUT_MS ?? '30000', 10);
+const waitUntil = process.env.QAIOS_AXE_WAIT_UNTIL ?? 'domcontentloaded';
+const tags = (process.env.QAIOS_AXE_TAGS ?? 'wcag2a,wcag2aa')
+  .split(',')
+  .map((t) => t.trim())
+  .filter((t) => t.length > 0);
+
+if (!url || !out) {
+  process.stderr.write('axe-runner: QAIOS_AXE_URL and QAIOS_AXE_OUTPUT env vars are required\n');
+  process.exit(2);
+}
+
+let chromium, AxeBuilder;
+try {
+  ({ chromium } = await import('playwright'));
+  ({ default: AxeBuilder } = await import('@axe-core/playwright'));
+} catch (err) {
+  process.stderr.write(
+    `axe-runner: failed to load 'playwright' and '@axe-core/playwright' from the project — ` +
+      `install them with \`npm i -D @axe-core/playwright\` (which pulls playwright). ` +
+      `${err?.message ?? err}\n`,
+  );
+  process.exit(3);
+}
+
+const browser = await chromium.launch({ headless: true });
+try {
+  const context = await browser.newContext();
+  const page = await context.newPage();
+  await page.goto(url, { timeout: timeoutMs, waitUntil });
+
+  const builder = new AxeBuilder({ page });
+  if (tags.length > 0) builder.withTags(tags);
+  const results = await builder.analyze();
+
+  // axe buckets its findings (https://github.com/dequelabs/axe-core docs):
+  //   violations — undeniable WCAG defects (must fix).
+  //   incomplete — needs manual review (axe couldn't be certain, e.g.
+  //                contrast behind a background image).
+  // A rule is a "best practice" (recommendation, not a WCAG break) when
+  // its tags include 'best-practice'. We tag each finding with `kind` so
+  // the QAIOS side can gate on real violations only and label the rest.
+  const isBestPractice = (v) => Array.isArray(v.tags) && v.tags.includes('best-practice');
+  const tag = (arr, fallbackKind) =>
+    (arr ?? []).map((v) => ({ ...v, kind: isBestPractice(v) ? 'best_practice' : fallbackKind }));
+
+  const findings = [
+    ...tag(results.violations, 'violation'),
+    ...tag(results.incomplete, 'incomplete'),
+  ];
+
+  writeFileSync(out, JSON.stringify({ url, findings }), 'utf-8');
+} catch (err) {
+  process.stderr.write(`axe-runner: ${err?.message ?? err}\n`);
+  process.exit(4);
+} finally {
+  await browser.close();
+}

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

@@ -0,0 +1,56 @@
+#!/usr/bin/env node
+// capture-page.mjs — Playwright headless page capture for qaios fix.
+//
+// Runs in the USER's project (cwd) so it can dynamic-import their
+// installed `playwright` package. Reads inputs from env vars:
+//   QAIOS_CAPTURE_URL          — target URL (required)
+//   QAIOS_CAPTURE_OUTPUT       — output path for {url, html, accessibilityTree} JSON (required)
+//   QAIOS_CAPTURE_TIMEOUT_MS   — navigation timeout (default 10_000)
+//   QAIOS_CAPTURE_WAIT_UNTIL   — load|domcontentloaded|networkidle (default 'domcontentloaded')
+//
+// Emits the full HTML; truncation to 50KB happens on the QAIOS side
+// via truncateHtmlSafe so the script stays decoupled from the budget.
+
+import { writeFileSync } from 'node:fs';
+
+const url = process.env.QAIOS_CAPTURE_URL;
+const out = process.env.QAIOS_CAPTURE_OUTPUT;
+const timeoutMs = Number.parseInt(process.env.QAIOS_CAPTURE_TIMEOUT_MS ?? '10000', 10);
+const waitUntil = process.env.QAIOS_CAPTURE_WAIT_UNTIL ?? 'domcontentloaded';
+
+if (!url || !out) {
+  process.stderr.write(
+    'capture-page: QAIOS_CAPTURE_URL and QAIOS_CAPTURE_OUTPUT env vars are required\n',
+  );
+  process.exit(2);
+}
+
+let chromium;
+try {
+  ({ chromium } = await import('playwright'));
+} catch (err) {
+  process.stderr.write(
+    `capture-page: failed to load 'playwright' from project — is it installed? ${err?.message ?? err}\n`,
+  );
+  process.exit(3);
+}
+
+const browser = await chromium.launch({ headless: true });
+try {
+  const context = await browser.newContext();
+  const page = await context.newPage();
+  await page.goto(url, { timeout: timeoutMs, waitUntil });
+  const html = await page.content();
+  let accessibilityTree = null;
+  try {
+    accessibilityTree = await page.accessibility.snapshot();
+  } catch {
+    /* accessibility snapshot is best-effort */
+  }
+  writeFileSync(out, JSON.stringify({ url, html, accessibilityTree }), 'utf-8');
+} catch (err) {
+  process.stderr.write(`capture-page: ${err?.message ?? err}\n`);
+  process.exit(4);
+} finally {
+  await browser.close();
+}

package/dist/index.d.ts

@@ -0,0 +1,17 @@
+import { Command } from 'commander';
+
+type CheckStatus = 'ok' | 'warn' | 'fail' | 'skip';
+interface DoctorCheck {
+    name: string;
+    status: CheckStatus;
+    detail: string;
+}
+
+/**
+ * Build the Commander program. Exported so tests can introspect the parser
+ * without spawning a subprocess.
+ */
+declare function buildProgram(): Command;
+declare function formatDoctor(checks: DoctorCheck[]): string;
+
+export { buildProgram, formatDoctor };