assuremind 1.0.0

package/CONTRIBUTING.md

@@ -0,0 +1,254 @@
+# Contributing to Assuremind
+
+This guide covers how to build, test, and publish the package from source.
+
+---
+
+## Prerequisites
+
+| Tool | Version |
+|------|---------|
+| Node.js | >= 18 |
+| npm | >= 9 |
+| Git | any recent |
+
+---
+
+## Clone and Install
+
+```bash
+git clone https://github.com/your-org/assuremind.git
+cd assuremind
+npm install
+```
+
+Install the UI dependencies separately:
+
+```bash
+cd ui && npm install && cd ..
+```
+
+---
+
+## Project Structure
+
+```
+assuremind/
+├── src/
+│   ├── cli/          # CLI entry point and commands (init, run, generate, …)
+│   ├── engine/       # Test runner, executor, self-healing, Allure reporter
+│   ├── ai/           # Smart router, provider adapters, prompts, code cache
+│   ├── storage/      # File-based JSON stores (suites, cases, results, healing)
+│   ├── server/       # Fastify API server + WebSocket
+│   ├── types/        # Zod schemas and TypeScript types
+│   └── utils/        # Shared utilities (errors, logger, hash, sanitize, env)
+├── ui/               # React 18 + Vite + TailwindCSS Studio front-end
+│   └── src/
+│       ├── api/      # Typed API client
+│       ├── components/
+│       ├── hooks/
+│       └── pages/    # Dashboard, TestEditor, Reports, Healing, …
+├── templates/        # Files copied into user projects on `init`
+├── tests/
+│   ├── unit/         # Pure unit tests (no I/O, fast)
+│   └── integration/  # CLI and server integration tests
+├── tsup.config.ts    # Library bundler config
+└── vitest.config.ts  # Test runner config
+```
+
+---
+
+## Build Commands
+
+### Build everything (library + UI)
+
+```bash
+npm run build
+```
+
+This runs two steps in order:
+
+**1. Build the TypeScript library:**
+
+```bash
+npm run build:lib
+```
+
+Uses `tsup` to compile `src/` → `dist/`. Outputs:
+- `dist/index.js` / `dist/index.mjs` — CJS + ESM entry points
+- `dist/index.d.ts` — TypeScript declarations
+- `dist/cli/index.js` — CLI binary (referenced by `bin.assuremind` in package.json)
+
+**2. Build the React UI:**
+
+```bash
+npm run build:ui
+```
+
+Runs `vite build` inside `ui/`. Output goes to `ui/dist/`. The Fastify server serves this at runtime via `@fastify/static`.
+
+---
+
+## Development Mode
+
+Watch for TypeScript changes and recompile the library:
+
+```bash
+npm run dev
+```
+
+Watch and hot-reload the Studio UI (requires `npm run dev` running in parallel):
+
+```bash
+npm run dev:ui
+```
+
+---
+
+## Testing
+
+Run the full test suite:
+
+```bash
+npm test
+```
+
+Run with coverage report:
+
+```bash
+npm run test:coverage
+```
+
+Run in watch mode during development:
+
+```bash
+npm run test:watch
+```
+
+### Test organisation
+
+| Directory | Purpose | Speed |
+|-----------|---------|-------|
+| `tests/unit/` | Individual functions and classes | ~5 ms/test |
+| `tests/integration/` | CLI commands, server HTTP routes | ~50–300 ms/test |
+
+**Coverage target:** > 80% statements.
+
+Engine files (`src/engine/`) and AI provider adapters (`src/ai/providers/`) are excluded from coverage thresholds because they require live Playwright browsers and API keys respectively.
+
+---
+
+## Linting and Formatting
+
+```bash
+npm run lint          # ESLint (TypeScript-aware)
+npm run lint:fix      # Auto-fix lint issues
+npm run format        # Prettier
+npm run typecheck     # tsc --noEmit (no output, just type errors)
+```
+
+---
+
+## Adding a New AI Provider
+
+1. Create `src/ai/providers/<name>.ts` implementing the `AIProvider` interface from `src/types/ai.ts`.
+2. Register it in `src/ai/router.ts` → `createProvider()` switch.
+3. Add the required env vars to `templates/env.example`.
+4. Add validation in `src/utils/env.ts` → `PROVIDER_ENV` map.
+5. Update `docs/GETTING-STARTED.md` with the new provider block.
+
+---
+
+## Releasing a New Version
+
+This package is distributed via private GitHub repository (not npm registry).
+
+### Steps to release
+
+```bash
+# 1. Update version in package.json
+#    e.g., "version": "1.1.0"
+
+# 2. Build and verify
+npm run build
+npm test
+
+# 3. Commit and tag
+git add -A
+git commit -m "release: v1.1.0"
+git tag v1.1.0
+
+# 4. Push
+git push origin main
+git push origin v1.1.0
+```
+
+### Versioning
+
+Follow [Semantic Versioning](https://semver.org):
+
+| Change | Version bump | Example |
+|--------|-------------|---------|
+| Bug fixes | Patch | `1.0.0` → `1.0.1` |
+| New features (backwards compatible) | Minor | `1.0.0` → `1.1.0` |
+| Breaking changes | Major | `1.0.0` → `2.0.0` |
+
+### Consumer installation
+
+```bash
+npm install git+https://github.com/<org>/assuremind.git#v1.1.0
+```
+
+---
+
+## Architecture Notes
+
+### Storage model
+
+Everything is stored as plain JSON files in the user's project directory — no database required. Structure after `init`:
+
+```
+<project>/
+├── tests/
+│   └── <suite-slug>/
+│       ├── suite.json
+│       └── <case-slug>.test.json
+├── variables/
+│   ├── global.json
+│   ├── dev.env.json
+│   ├── staging.env.json
+│   └── prod.env.json
+├── results/
+│   ├── runs/
+│   │   └── <runId>.json
+│   ├── screenshots/
+│   ├── videos/
+│   ├── traces/
+│   ├── reports/
+│   └── healing/
+└── autotest.config.json   # written by writeConfig()
+```
+
+Suite and case file names are derived from the `name` field via `toSlug()` (lowercased, alphanumeric + hyphens). This means **the directory/file name is the URL parameter** used in Studio API routes — not the UUID stored inside the JSON.
+
+### Self-healing cascade
+
+When a test step fails, the engine tries up to 6 healing levels in order:
+
+| Level | Strategy |
+|-------|---------|
+| 1 | Smart Retry — wait + retry with backoff |
+| 2 | AI Regeneration — AI rewrites Playwright code |
+| 3 | Multi-Selector — try alternate selectors (ID, text, role, aria) |
+| 4 | Visual/SoM — screenshot + AI visual analysis |
+| 5 | Decompose — break step into smaller sub-actions |
+| 6 | Manual — flag for human review |
+
+Healed steps are saved as `pending` events in `results/healing/pending.json` for human review via `npx assuremind apply-healing` or the Studio Healing page.
+
+### AI cost optimisation
+
+1. **Template engine** — recognises common patterns (navigate, click, fill, etc.) and uses zero-cost templates.
+2. **Code cache** — SHA-based cache keyed on `(normalised instruction, url pattern)`. Cache persists to `results/code-cache.json`.
+3. **Complexity classifier** — routes simple steps to cheap/fast models (tiered mode) and complex steps to capable models.
+4. **Batch generation** — multiple empty steps sent in one API call.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Deepak Hiremath
+
+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 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/README.md

@@ -0,0 +1,367 @@
+# Assuremind Studio
+
+**AI-powered codeless UI & API automation framework**
+
+---
+
+## Features
+
+- **Zero coding required** — describe test steps in plain English, AI generates Playwright code
+- **Three suite types** — **UI** (Playwright browser automation), **API** (HTTP tests), and **Audit** (Playwright + Lighthouse non-functional checks)
+- **Audit suites** — run full Playwright automation with built-in Lighthouse scoring for Performance, Accessibility, and SEO; mark individual steps as Lighthouse checkpoints with the `⚡ Audit` flag
+- **Device emulation** — emulate real mobile and tablet devices (iPhone 15 Pro, Pixel 7, iPad Pro, Galaxy S9+ and more) using Playwright's built-in device descriptors; configurable from the Studio UI or via `--device` CLI flag
+- **Self-healing** — when a selector breaks, AI regenerates it automatically (6-level cascade)
+- **Multi-AI-provider** — Anthropic, OpenAI, Google Gemini, Groq, DeepSeek, Together, Qwen, Perplexity, Ollama, AWS Bedrock, Azure OpenAI, custom endpoints
+- **Studio UI** — browser-based test editor, run dashboard, healing review, reports
+- **Git Control Center** — branch management, AI commit messages, conflict resolution from the UI
+- **Environment management** — switch between dev, stage, test, prod with per-environment base URLs
+- **Cost-optimised** — template engine + code cache minimise API calls; AI only runs when genuinely needed
+- **CI-ready** — `npx assuremind run --all --ci` integrates with any pipeline; supports `--device` for mobile CI runs
+- **File-based storage** — plain JSON, fully Git-friendly, no database
+
+---
+
+## Quick Start
+
+```bash
+npm init -y
+npm install git+https://github.com/<org>/assuremind.git
+npx assuremind init        # creates folders, config, installs Playwright browsers
+npx assuremind studio      # opens web UI at http://localhost:4400
+```
+
+---
+
+## Installation
+
+```bash
+# From private GitHub repo
+npm install git+https://github.com/<org>/assuremind.git
+
+# Or a specific version
+npm install git+https://github.com/<org>/assuremind.git#v1.0.0
+```
+
+Node.js >= 18 is required.
+
+---
+
+## Configuration
+
+After `npx assuremind init`, edit `.env` with your AI provider:
+
+```bash
+# .env — choose one provider block
+
+# Anthropic (Claude)
+AI_PROVIDER=anthropic
+ANTHROPIC_API_KEY=sk-ant-...
+ANTHROPIC_MODEL=claude-sonnet-4-20250514   # optional
+
+# OpenAI (GPT)
+AI_PROVIDER=openai
+OPENAI_API_KEY=sk-...
+OPENAI_MODEL=gpt-4o                        # optional
+
+# Google (Gemini)
+AI_PROVIDER=google
+GOOGLE_API_KEY=AIza...
+GOOGLE_MODEL=gemini-2.5-flash              # optional
+
+# Groq (fast inference)
+AI_PROVIDER=groq
+GROQ_API_KEY=gsk_...
+GROQ_MODEL=llama-3.3-70b-versatile         # optional
+
+# DeepSeek
+AI_PROVIDER=deepseek
+DEEPSEEK_API_KEY=sk-...
+
+# Together AI
+AI_PROVIDER=together
+TOGETHER_API_KEY=...
+
+# Perplexity
+AI_PROVIDER=perplexity
+PERPLEXITY_API_KEY=pplx-...
+
+# Qwen (Alibaba)
+AI_PROVIDER=qwen
+QWEN_API_KEY=...
+
+# Ollama (local)
+AI_PROVIDER=ollama
+OLLAMA_BASE_URL=http://localhost:11434     # optional
+OLLAMA_MODEL=llama3.3                      # optional
+
+# AWS Bedrock
+AI_PROVIDER=bedrock
+AWS_ACCESS_KEY_ID=...
+AWS_SECRET_ACCESS_KEY=...
+AWS_REGION=us-east-1
+
+# Azure OpenAI
+AI_PROVIDER=azure-openai
+AZURE_OPENAI_API_KEY=...
+AZURE_OPENAI_ENDPOINT=https://my-resource.openai.azure.com
+AZURE_OPENAI_DEPLOYMENT=my-deployment
+
+# Custom OpenAI-compatible endpoint
+AI_PROVIDER=custom
+CUSTOM_API_KEY=...
+CUSTOM_BASE_URL=https://my-endpoint.com/v1
+CUSTOM_MODEL=my-model
+```
+
+Edit `autotest.config.ts` for test execution settings (base URL, browsers, timeouts, healing, etc.). Or use the **Settings** page in Studio to configure everything from the browser.
+
+---
+
+## CLI Commands
+
+### `npx assuremind init`
+
+Initialises a project — creates folders, `.env`, config files, and installs Playwright browsers.
+
+```bash
+npx assuremind init
+npx assuremind init --skip-playwright   # skip browser installation
+```
+
+### `npx assuremind studio`
+
+Starts the web UI at `http://localhost:4400`.
+
+```bash
+npx assuremind studio
+npx assuremind studio --port 5000
+npx assuremind studio --no-open        # don't auto-open browser
+```
+
+### `npx assuremind run`
+
+Runs tests from the command line. Filters are combinable with AND logic.
+
+```bash
+# Run everything
+npx assuremind run --all
+
+# Filter by suite type
+npx assuremind run --type ui
+npx assuremind run --type api
+npx assuremind run --type audit
+
+# Run a suite (case-insensitive partial match)
+npx assuremind run --suite "Login Tests"
+
+# Run by tag
+npx assuremind run --tag smoke
+
+# Run a single test (case-insensitive partial match)
+npx assuremind run --test "User can log in with valid credentials"
+
+# Combine filters
+npx assuremind run --type audit --tag regression
+npx assuremind run --suite "Orange HRM" --tag smoke
+npx assuremind run --type audit --test "Login Page"
+
+# Device emulation (mobile/tablet)
+npx assuremind run --all --device "iPhone 15 Pro" --browser chromium
+npx assuremind run --tag smoke --device "Pixel 7" --browser chromium
+npx assuremind run --all --device "iPad Pro 11" --browser webkit
+
+# With options
+npx assuremind run --all \
+  --browser chromium firefox \
+  --parallel 4 \
+  --headed \
+  --ci \
+  --no-healing \
+  --reporter allure json
+```
+
+| Flag | Description |
+|------|-------------|
+| `--all` | Run every suite |
+| `--type <type>` | Filter by suite type: `ui`, `api`, or `audit` |
+| `--suite <name>` | Run suites whose name contains `<name>` |
+| `--tag <tag>` | Run all cases with this tag |
+| `--test <name>` | Run cases whose name contains `<name>` |
+| `--browser <list>` | Browsers: `chromium` `firefox` `webkit` |
+| `--device <name>` | Emulate a device (e.g. `"iPhone 15 Pro"`, `"Pixel 7"`, `"iPad Pro 11"`) |
+| `--env <name>` | Variable environment: `dev` `staging` `prod` |
+| `--parallel <n>` | Concurrent workers |
+| `--headed` | Show browser window |
+| `--ci` | CI mode — minimal output, exit code reflects pass/fail |
+| `--no-healing` | Disable self-healing for this run |
+| `--reporter <list>` | `allure` `html` `json` |
+
+### `npx assuremind generate`
+
+Generates a test suite from a plain-English user story using AI.
+
+```bash
+npx assuremind generate \
+  --story "User logs in with valid credentials and sees the dashboard"
+
+npx assuremind generate \
+  --story-file ./stories/checkout.txt \
+  --suite "Checkout Flow" \
+  --output ./tests
+```
+
+### `npx assuremind apply-healing`
+
+Reviews and applies self-healing suggestions to test files.
+
+```bash
+# Interactive review
+npx assuremind apply-healing
+
+# Accept all pending heals without prompting
+npx assuremind apply-healing --yes
+
+# Load from a specific report file
+npx assuremind apply-healing --from results/healing/healing-report-<runId>.json
+```
+
+### `npx assuremind validate`
+
+Validates your config, environment variables, and test files.
+
+### `npx assuremind doctor`
+
+Checks system requirements, AI provider connectivity, and configuration health.
+
+---
+
+## Project Structure
+
+After `init`, your project looks like:
+
+```
+my-project/
+├── autotest.config.ts     # TypeScript config (human-readable)
+├── autotest.config.json   # JSON config (used at runtime)
+├── .env                   # AI provider credentials (gitignored)
+├── tests/
+│   ├── <suite-id>/        # UI and API suites
+│   │   ├── suite.json
+│   │   └── <case-id>.test.json
+│   └── audit/             # Audit suites (Lighthouse)
+│       ├── suite.json
+│       └── <case-id>.test.json
+├── variables/
+│   ├── global.json        # Available in all tests as {{VAR_NAME}}
+│   ├── dev.env.json
+│   ├── staging.env.json
+│   └── prod.env.json
+├── results/
+│   ├── runs/              # Run result JSON files
+│   ├── healing/           # Self-healing event store
+│   ├── screenshots/
+│   ├── videos/
+│   ├── traces/
+│   └── reports/
+└── fixtures/
+    ├── auth/
+    └── data/
+```
+
+---
+
+## Studio UI
+
+Open `http://localhost:4400` after running `npx assuremind studio`.
+
+| Page | Description |
+|------|-------------|
+| **Dashboard** | Run health overview, live progress, recent results |
+| **Smart Tests** | Paste a user story or Jira link, AI creates a full test suite |
+| **Test Editor** | 3-level editor: suites → cases → steps, with AI code generation |
+| **Run Config** | Configure and launch runs from the browser |
+| **Reports** | Run history, pass/fail drill-down, Lighthouse score tabs (⚡ Speed, ♿ A11y, 🔍 SEO) for Audit suites, Allure report link |
+| **Variables** | Manage `{{VARIABLE_NAME}}` tokens across all tests |
+| **Self-Healing** | Review and accept/reject AI-generated fixes |
+| **Settings** | Environment management, browsers, healing, capture settings |
+| **Git Control Center** | Branch management, AI commit messages, push/pull, conflict resolution |
+
+---
+
+## Self-Healing
+
+When a test step fails, Assuremind attempts up to 6 healing levels before marking the step as failed:
+
+| Level | Strategy | AI Cost |
+|-------|----------|---------|
+| 1 | Smart Retry — wait + retry with backoff | None |
+| 2 | AI Regeneration — AI rewrites the Playwright code | Yes |
+| 3 | Multi-Selector — try alternate selectors (ID, text, role, aria) | Yes |
+| 4 | Visual/SoM — screenshot + AI visual analysis | Yes |
+| 5 | Decompose — break step into smaller sub-actions | Yes |
+| 6 | Manual — flag for human review | None |
+
+AI healing costs are tracked against a configurable daily budget (`healing.dailyBudget` in USD). Healed steps are saved as **pending events** for your review — run `npx assuremind apply-healing` or visit the Self-Healing page in Studio to accept or reject each fix.
+
+---
+
+## Variables
+
+Use `{{VARIABLE_NAME}}` tokens in step instructions. Variables are resolved at run time from your variable files:
+
+```json
+// variables/global.json
+{
+  "BASE_URL": "http://localhost:3000",
+  "ADMIN_EMAIL": "admin@example.com"
+}
+```
+
+Step instruction: `Navigate to {{BASE_URL}}/login and enter {{ADMIN_EMAIL}}`
+
+Secret variables (marked with `"secret": true`) are masked in logs and reports.
+
+---
+
+## CI/CD Integration
+
+```yaml
+# GitHub Actions example
+- name: Run tests
+  env:
+    AI_PROVIDER: anthropic
+    ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
+  run: |
+    npx assuremind run --all --ci --no-healing
+```
+
+Exit code `0` = all tests passed, `1` = at least one test failed.
+
+---
+
+## Security
+
+- Generated Playwright code runs inside a sandboxed `new Function('page', 'context', 'expect', code)` — only `page`, `context`, and `expect` are available
+- Secret variables are never sent to AI providers, never logged, never included in reports
+- All generated code is validated against a forbidden-pattern list before execution
+- Atomic file writes prevent partially-written results on crash
+
+---
+
+## Tiered AI Mode (Cost Optimisation)
+
+Enable tiered mode to use a cheaper/faster model for simple steps and a more capable model for complex ones:
+
+```bash
+AI_TIERED_ENABLED=true
+AI_TIERED_FAST_PROVIDER=groq
+AI_TIERED_FAST_MODEL=llama-3.1-8b-instant
+```
+
+The smart router also applies (in order): template pattern matching → code cache lookup → batch generation → fast model → primary model.
+
+---
+
+## License
+
+MIT