prompttest 1.3.0

package/CONTRIBUTING.md

@@ -0,0 +1,80 @@
+# Contributing to PromptTest
+
+Thank you for your interest in contributing to **PromptTest**!
+
+PromptTest is an ultra-fast, zero-code autonomous mobile testing & visual QA brain designed for Android. We welcome contributions from the community.
+
+---
+
+## 🚀 Getting Started
+
+1. **Fork and Clone the Repository**:
+
+   ```bash
+   git clone https://github.com/<your-username>/prompttest.git
+   cd prompttest
+   ```
+
+2. **Install Dependencies**:
+
+   ```bash
+   npm install
+   ```
+
+3. **Verify Build**:
+
+   ```bash
+   npm run build
+   ```
+
+4. **Connect an Android Device or Emulator**:
+   Ensure `adb` is in your system PATH and run:
+   ```bash
+   npm run devices
+   ```
+
+---
+
+## 🛠 Project Structure
+
+- `bin/prompttest.ts`: CLI entry point and command router (`run`, `explore`, `status`, `devices`).
+- `lib/adb.ts`: High-performance ADB driver for fast XML hierarchy dumping, input dispatching, and screenshot capture.
+- `lib/prompt-runner.ts`: Core test execution engine with expectation-driven polling, auto-scroll triage, and collision disambiguation.
+- `lib/patterns.ts`: Plain-English DSL parser and step tokenizers.
+- `lib/memory.ts`: Persistent autonomous knowledge engine and fast-forward cache.
+- `lib/dictionary.ts`: Standard UI component vocabulary and intent mapping heuristics.
+- `lib/crawler.ts` & `lib/explorer.ts`: Autonomous screen exploration and dynamic component graph discovery.
+- `lib/reporter.ts`: Markdown & JSON QA test report generator with visual blackbox capture.
+- `specs/`: Sample test spec files written in plain English.
+
+---
+
+## 📝 Adding New Prompt Grammar / Verbs
+
+If you want to introduce a new plain-English command:
+
+1. Update `PromptStepType` and parser regex in [`lib/patterns.ts`](lib/patterns.ts).
+2. Add execution handler in `PromptRunner.executeStep()` inside [`lib/prompt-runner.ts`](lib/prompt-runner.ts).
+3. Add corresponding unit or integration tests in `specs/`.
+
+---
+
+## 🧪 Testing Guidelines
+
+Before opening a pull request:
+
+1. Ensure TypeScript compiles with zero errors:
+   ```bash
+   npm run build
+   ```
+2. Test against a connected Android device or emulator:
+   ```bash
+   npm run test:teacher
+   ```
+3. Keep code modular, universal (no hardcoded application-specific coordinates or package IDs), and well-documented.
+
+---
+
+## 📄 Code of Conduct & Licensing
+
+By contributing, you agree that your contributions will be licensed under the project's [MIT License](LICENSE).

package/LICENSE

@@ -0,0 +1,36 @@
+Business Source License 1.1
+
+Parameters
+
+Licensor:
+PromptTest (Shriram Singh)
+
+Licensed Work:
+PromptTest (including its command-line interface, autonomous state-graph exploration engine,
+heuristic gesture systems, and programmatic SDK), in source code, binary, and bundled distribution forms.
+
+Additional Use Grant:
+You may use the Licensed Work free of charge for:
+1. Non-commercial, educational, academic, and open-source purposes.
+2. Personal and evaluation use.
+3. Internal software testing within organizations that have an annual gross revenue of less
+   than $100,000 USD (or equivalent) and fewer than 10 employees.
+
+Commercial License Requirement:
+Any use within organizations exceeding the revenue or employee threshold, any use by testing
+agencies providing commercial QA services to third-party clients, or any deployment into production
+commercial CI/CD pipelines requires a commercial license from the Licensor.
+
+Hosting & Managed Service Restriction:
+You may not provide the Licensed Work, whether modified or unmodified, as a hosted service,
+managed QA service, or cloud testing platform to third parties without prior written consent.
+
+Change Date:
+2030-09-14
+
+Change License:
+Apache License, Version 2.0
+
+Notice:
+For commercial licensing inquiries, enterprise agreements, or custom SLAs, contact:
+PromptTest (https://github.com/shriramsingh/promptTest)

package/LICENSES.md

@@ -0,0 +1,81 @@
+# Open Source Software Licenses & Bill of Materials (SBOM)
+
+PromptTest is licensed under the [Business Source License 1.1 (BSL 1.1)](LICENSE).
+
+This document catalogs third-party dependencies utilized by PromptTest, their licenses, and compliance attestations.
+
+---
+
+## License Compliance Attestation
+
+- **Zero Copyleft / Zero GPL**: PromptTest does **not** link against or distribute any code licensed under GPL, LGPL, AGPL, or other reciprocal copyleft licenses.
+- **Enterprise Friendly**: All runtime dependencies use widely accepted permissive licenses (MIT, ISC, Apache-2.0), making PromptTest safe for commercial and proprietary enterprise deployments.
+
+---
+
+## Production Runtime Dependencies
+
+| Package        | Version  | License | Primary Purpose                                | Home / Repository                    |
+| :------------- | :------- | :------ | :--------------------------------------------- | :----------------------------------- |
+| **chalk**      | `^5.3.0` | MIT     | Terminal colorization and CLI styling          | https://github.com/chalk/chalk       |
+| **pixelmatch** | `^7.2.0` | ISC     | Visual pixel-by-pixel regression image diffing | https://github.com/mapbox/pixelmatch |
+| **pngjs**      | `^7.0.0` | MIT     | PNG image encoding and decoding                | https://github.com/lukeapage/pngjs   |
+
+---
+
+## Development & Build Dependencies
+
+| Package                 | Version    | License    | Purpose                               |
+| :---------------------- | :--------- | :--------- | :------------------------------------ |
+| **typescript**          | `^5.7.2`   | Apache-2.0 | Static type checking and compiler     |
+| **vitest**              | `^5.0.0`   | MIT        | Fast unit and integration test runner |
+| **eslint**              | `^10.10.0` | MIT        | Code quality and lint analysis        |
+| **prettier**            | `^3.9.6`   | MIT        | Opinionated code formatter            |
+| **tsx**                 | `^4.19.2`  | MIT        | TypeScript execution engine           |
+| **@vitest/coverage-v8** | `^5.0.0`   | MIT        | V8 code coverage provider             |
+| **typescript-eslint**   | `^8.70.0`  | MIT        | TypeScript ESLint tooling             |
+| **@types/node**         | `^22.10.2` | MIT        | Node.js TypeScript definitions        |
+| **@types/pixelmatch**   | `^5.2.6`   | MIT        | Pixelmatch TypeScript definitions     |
+| **@types/pngjs**        | `^6.0.5`   | MIT        | PNGjs TypeScript definitions          |
+
+---
+
+## Full License Texts
+
+### MIT License
+
+```text
+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.
+```
+
+### ISC License
+
+```text
+Permission to use, copy, modify, and/or distribute this software for any
+purpose with or without fee is hereby granted, provided that the above
+copyright notice and this permission notice appear in all copies.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
+WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
+MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
+ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
+WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
+ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
+OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
+```

package/README.md

@@ -0,0 +1,402 @@
+# ⚡ PromptTest
+
+> **Ultra-fast, zero-code autonomous mobile testing & visual QA brain for Android.**
+
+[![TypeScript](https://img.shields.io/badge/TypeScript-5.7-blue.svg)](https://www.typescriptlang.org/)
+[![Node.js](https://img.shields.io/badge/Node.js-18%2B-green.svg)](https://nodejs.org/)
+[![Android ADB](https://img.shields.io/badge/Android-ADB%20Native-orange.svg)](https://developer.android.com/tools/adb)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+
+**PromptTest** allows QA engineers, developers, and autonomous agents to test Android applications using **plain-English natural language scripts**. It eliminates heavy frameworks like Appium, Selenium, or WebDriver in favor of high-performance native ADB streams, expectation-driven polling, and a self-learning autonomous memory engine.
+
+📚 **[Read the Full User Manual (docs/USER_MANUAL.md)](docs/USER_MANUAL.md)** • 🎯 **[Mode Expectations & Limits (docs/MODE_EXPECTATIONS.md)](docs/MODE_EXPECTATIONS.md)** • 🌐 **[Interactive Web Manual (docs/index.html)](docs/index.html)** • 🏛 **[System Architecture (docs/ARCHITECTURE.md)](docs/ARCHITECTURE.md)**
+
+> ⚠️ **Honest expectations:** PromptTest is a fast UI‑tree automation engine over ADB. It excels on standard, accessibility‑exposed screens (React Native, Expo, Flutter, Native/Compose); fully‑drawn games/canvas and unlabeled icon‑only controls are platform‑limited. See **[docs/MODE_EXPECTATIONS.md](docs/MODE_EXPECTATIONS.md)** for exactly what each mode can and cannot do.
+
+---
+
+## 🌟 Why PromptTest?
+
+- 📝 **Plain-English Test Scripts**: Write tests in human language without writing selectors, XPath, or glue code.
+- ⚡ **Sub-Second per-step Execution**: Direct native ADB hierarchy streaming and dynamic expectation polling (no blind `sleep()` timeouts).
+- 🧠 **Autonomous Knowledge Engine**: Remembers element mappings, accessibility descriptors, and screen transitions to fast-forward future test runs.
+- 🌐 **Universal Across Frameworks**: Works on React Native, Expo, Flutter, Native Android (Kotlin/Java), and Jetpack Compose — for standard, accessibility-exposed UI (games/canvas are platform-limited).
+- 🛡 **Smart Pre-Fail Triage**: Automatically resolves modal dialog collisions, auto-scrolls when elements are below the fold, and handles Android gesture insets.
+- 📸 **Failure-Only Blackbox Diagnostics**: Keeps test runs ultra-fast and lightweight while capturing high-resolution visual evidence and actionable diffs upon assertion failures.
+
+---
+
+## 🚀 Quick Start
+
+### Prerequisites
+
+1. **Node.js 18.0.0+** (Required for ES2022 features, native module resolution, and Unicode property escapes `\p{Extended_Pictographic}`).
+2. **Android ADB** installed and accessible in your system `PATH`.
+3. An Android device or emulator with **USB Debugging** enabled.
+4. _Language Support_: The default seed dictionary covers English mobile UI interactions. Applications localized in other languages work via direct label matching or custom specifications.
+
+### Installation
+
+```bash
+# Clone the repository
+git clone https://github.com/<your-username>/prompttest.git
+cd prompttest
+
+# Install dependencies
+npm install
+
+# Build TypeScript
+npm run build
+```
+
+### Connect Your Device
+
+```bash
+# Verify device connection
+npm run devices
+```
+
+---
+
+## ✍️ Writing Plain-English Tests
+
+Test specs are simple text files containing numbered steps written in conversational English.
+
+### Example Spec (`specs/login_and_dashboard.txt`)
+
+```text
+# 1. Authentication
+1. Type 'ramesh@coachconnect.app' into 'Email Address'
+2. Type 'Teacher@1234' into 'Password'
+3. Tap 'Sign In'
+4. Wait 3s
+
+# 2. Dashboard Verification
+5. Verify 'Apex Coaching Academy' is visible
+6. Verify 'Dr. Ramesh Sharma' is visible
+7. Verify 'My Batches' is visible
+
+# 3. Batches Module
+8. Tap 'Batches'
+9. Verify 'Batches & Schedules' is visible
+10. Tap 'Grade 10 Mathematics'
+11. Verify 'Weekly Schedule' is visible
+12. Press back
+
+# 4. Sign Out Flow
+13. Tap 'Profile'
+14. Tap 'Sign Out'
+15. Tap 'Sign Out'
+16. Verify 'Welcome Back' is visible
+```
+
+---
+
+## 📖 Plain-English & AST Syntax Reference
+
+### Primitive Actions & UI Interactions
+
+| Action             | Example Syntax                        | Description                                                       |
+| :----------------- | :------------------------------------ | :---------------------------------------------------------------- |
+| **Type / Input**   | `Type 'user@domain.com' into 'Email'` | Clears existing text and types the value into the matching input. |
+| **Tap / Click**    | `Tap 'Sign In'`                       | Clicks button, tab, link, or icon with exact boundary resolution. |
+| **Long Press**     | `Long press 'Student Card'`           | Long presses an element for 1000ms.                               |
+| **Verify Visible** | `Verify 'Dashboard' is visible`       | Polls until the text or accessibility label appears on screen.    |
+| **Verify State**   | `Verify 'Submit' is disabled`         | Verifies element enablement state (`enabled` / `disabled`).       |
+| **Press Back**     | `Press back`                          | Emits Android system `KEYCODE_BACK`.                              |
+| **Scroll / Swipe** | `Scroll down` or `Scroll up`          | Proportional responsive swipe along the screen viewport.          |
+| **Relative Tap**   | `Tap 'Delete' next to 'Rohan Gupta'`  | Disambiguates duplicate elements using spatial proximity.         |
+| **Wait**           | `Wait 3s` or `Wait 1500ms`            | Pauses execution for custom animation delays.                     |
+
+### Flow Control, Subflows & Programmatic Logic
+
+| Feature             | Example Syntax                             | Description                                            |
+| :------------------ | :----------------------------------------- | :----------------------------------------------------- |
+| **Conditional**     | `IF 'Promo' is visible ... ELSE ... ENDIF` | Executes branch based on live element presence.        |
+| **Loop**            | `LOOP 3 ... ENDLOOP`                       | Repeats child step block N times.                      |
+| **Wait Until**      | `WAIT_UNTIL 'Ready' is visible (10s)`      | Explicit polling wait with max timeout budget.         |
+| **Subflow Include** | `#include <specs/login.txt>`               | Inlines modular specs with circular dependency guards. |
+| **Variables**       | `SET $token = 'xyz'`                       | Sets local variable for interpolation (`$token`).      |
+| **Sandboxed JS**    | `RUN_JS return { status: 200 }`            | Executes deterministic JavaScript expressions.         |
+
+### Data-Driven Testing & Dynamic Generators
+
+Embed inline JSON datasets using `#!data` or load via CSV/JSON:
+
+```text
+#!data [
+  {"user": "Alice", "email": "$random.email"},
+  {"user": "Bob",   "email": "$random.email"}
+]
+1. Type '$user' into 'Username'
+2. Type '$email' into 'Email'
+```
+
+**Supported Generators**:
+
+- Synthetic Data: `$random.firstName`, `$random.lastName`, `$random.email`, `$random.phone`, `$random.string(8)`
+- Sequences & UUIDs: `$seq.id`, `$uuid`
+- Date & Time: `$date.now`, `$date.iso`, `$date.format('YYYY-MM-DD')`
+- Math Evaluation: `$calc($count + 1)`
+
+### Integration Assertions & Device State
+
+```text
+# OTP & API Verification
+1. CAPTURE OTP from SMS into $code
+2. Type '$code' into 'Verification Code'
+3. API GET 'https://api.example.com/user/profile' EXPECT status 200
+4. VERIFY EMAIL to 'test@domain.com' subject 'Welcome'
+
+# Device Simulation
+5. Set network to offline
+6. Set battery level to 20
+```
+
+---
+
+## 🖥 CLI Usage
+
+### Run a Test Spec
+
+```bash
+# Run a test script against an app package
+npx prompttest run specs/my_suite.txt host.exp.exponent
+
+# Run with full visual screenshots on every step
+npx prompttest run specs/my_suite.txt host.exp.exponent --screenshots all
+
+# Run data-driven iterations
+npx prompttest run specs/checkout.txt host.exp.exponent --iterations 5 --only-row 2
+
+# Run against a managed device pool with concurrency leasing
+npx prompttest run specs/suite.txt host.exp.exponent --device-pool emulator-5554,emulator-5556 --device-timeout-secs 30
+```
+
+### CLI Flags Reference
+
+| Flag                                     | Description                                                                 |
+| :--------------------------------------- | :-------------------------------------------------------------------------- |
+| `--fresh`                                | Force-stops and restarts target app before test begins.                     |
+| `--device-pool <d1,d2>`                  | Executes against the first available device from pool using atomic locking. |
+| `--device-timeout-secs <n>`              | Maximum seconds to wait for a free device lock (default: 60s).              |
+| `--iterations <n>`                       | Executes spec across N dynamic data iterations.                             |
+| `--only-row <n>`                         | Filters execution to a specific 1-indexed data row.                         |
+| `--continue` / `--continue-on-failure`   | Continues running remaining steps after failure instead of fast-failing.    |
+| `--screenshots <all\|failure\|none>`     | Controls screenshot capture policy (default: `failure`).                    |
+| `--save-baseline` / `--update-baselines` | Saves gold reference baseline images for visual regression.                 |
+| `--compare-baseline`                     | Compares execution screens against reference baseline.                      |
+| `--baseline-threshold <n>`               | Sets allowable perceptual diff tolerance (e.g. 0.02 = 2%).                  |
+| `--format <html,json,junit,markdown>`    | Comma-separated output report formats.                                      |
+| `-s <serial>`                            | Targets a specific connected device serial.                                 |
+| `--version` / `-v`                       | Prints current PromptTest version.                                          |
+
+### Other Commands
+
+```bash
+# Connect to a device wirelessly over Wi-Fi
+npx prompttest wifi 192.168.1.50
+
+# Disconnect wireless device
+npx prompttest disconnect
+
+# Interactive record-and-play session
+npx prompttest record specs/login.txt
+
+# Inspect foreground app and active components on screen
+npx prompttest status
+
+# Run comprehensive environment and ADB readiness diagnostics
+npx prompttest doctor
+
+# Start interactive live REPL sandbox for prototyping test steps
+npx prompttest repl
+
+# Merge multi-device test results and generate Atto-inspired release confidence dashboard
+npx prompttest merge-reports output
+
+# Automatically crawl and map the app (Autonomous State-Graph Crawler v3)
+npx prompttest explore host.exp.exponent
+
+# Run autonomous crawl with strict safety policy and custom domain blacklist
+npx prompttest explore host.exp.exponent --safety-mode=strict --safety-blacklist="Transfer,Revoke,Publish"
+
+# Deep exploration with custom screen/step budgets and lazy failure-only screenshots
+npx prompttest explore host.exp.exponent --max-screens=30 --step-budget=60 --screenshots=failure-only
+
+# View learned component aliases & confidence
+npx prompttest memory host.exp.exponent
+
+# Generate GitHub Actions CI workflow
+npx prompttest init-ci
+```
+
+### Autonomous Exploration Flags (`explore`)
+
+| Flag                       | Default        | Description                                                                                                        | Example                            |
+| :------------------------- | :------------- | :----------------------------------------------------------------------------------------------------------------- | :--------------------------------- |
+| `--safety-mode=<mode>`     | `strict`       | Policy level: `strict` (all deletions blocked), `moderate` (drafts permitted), `interactive` (prompts), `disabled` | `--safety-mode=moderate`           |
+| `--safety-blacklist="..."` | `[]`           | Comma-separated custom keywords to protect as destructive actions                                                  | `--safety-blacklist="Revoke,Wipe"` |
+| `--max-screens=N`          | `20`           | Maximum unique screen states to discover and index                                                                 | `--max-screens=50`                 |
+| `--max-depth=N`            | `3`            | Maximum recursion depth for nested screen diving                                                                   | `--max-depth=5`                    |
+| `--step-budget=N`          | `40`           | Total interaction steps before completing exploration                                                              | `--step-budget=100`                |
+| `--screenshots=<mode>`     | `state-change` | Image capture policy: `state-change`, `failure-only`, or `all`                                                     | `--screenshots=failure-only`       |
+| `-s <serial>`              | auto           | Target specific connected device serial                                                                            | `-s GEVKDEUWOJWC89OR`              |
+
+### CLI Execution Flags (`run`)
+
+| Flag             | Description                                                  | Example                                          |
+| :--------------- | :----------------------------------------------------------- | :----------------------------------------------- |
+| `--dry-run`      | Validates and parses spec steps with 0 device execution      | `prompttest run specs/flow.txt --dry-run`        |
+| `--list-steps`   | Prints a formatted table of all parsed steps in the spec     | `prompttest run specs/flow.txt --list-steps`     |
+| `--only=<range>` | Executes only specific step numbers or ranges (e.g. `2-5,8`) | `prompttest run specs/flow.txt --only="1-3,5"`   |
+| `--tags=<tags>`  | Filters execution by tags declared via `# @tag: <name>`      | `prompttest run specs/flow.txt --tags="smoke"`   |
+| `--json`         | Outputs machine-readable run summary JSON to stdout          | `prompttest run specs/flow.txt --json`           |
+| `--benchmark`    | Profiles and logs execution duration for each step           | `prompttest run specs/flow.txt --benchmark`      |
+| `--watch`        | Watches spec file for changes and re-executes automatically  | `prompttest run specs/flow.txt --watch`          |
+| `--fresh`        | Force-stops and restarts target app before execution         | `prompttest run specs/flow.txt --fresh`          |
+| `--all-devices`  | Concurrently executes spec across all connected devices      | `prompttest run specs/flow.txt --all-devices`    |
+| `--continue`     | Continues executing remaining steps if a step fails          | `prompttest run specs/flow.txt --continue`       |
+| `--var:K=V`      | Injects runtime variable overrides into the test context     | `prompttest run specs/flow.txt --var:USER=Alice` |
+
+---
+
+## 🐳 Docker Container Deployment
+
+PromptTest is fully containerized with Android platform-tools and headless runtime support:
+
+```bash
+# Build Docker image
+docker build -t prompttest .
+
+# Run test spec inside container sharing host ADB daemon
+docker run --rm --net=host \
+  -v $(pwd)/specs:/app/specs \
+  -v $(pwd)/output:/app/output \
+  prompttest run specs/my_suite.txt com.example.app
+```
+
+---
+
+## 🏗 Architecture & Execution Pipeline
+
+```mermaid
+flowchart TD
+    A[Plain-English Spec .txt] --> B[DSL Parser & Tokenizer]
+    B --> C[PromptRunner Engine]
+    C --> D{Expectation Poller}
+    D -->|Match Found| E[ADB Fast Native Driver]
+    D -->|Not Found| F[Pre-Fail Triage / Auto-Scroll]
+    F -->|Recovered| E
+    F -->|Failed| G[Diagnostic Blackbox Snapshot]
+    E --> H[Screen Execution & Settle]
+    H --> I[Autonomous Knowledge Memory Engine]
+    I --> J[Markdown & JSON QA Reports]
+```
+
+### Key Components
+
+1. **High-Performance ADB Driver (`lib/adb.ts`)**: Native process streaming for zero-latency screen hierarchy dumps and coordinate dispatching.
+2. **Dynamic Expectation Poller (`lib/prompt-runner.ts`)**: Instant 0ms cache pass when screens match, dynamically polling for state transitions without rigid sleep constants.
+3. **Autonomous Knowledge Engine (`lib/memory.ts`)**: Persists successful UI mappings into `memory/<package>.json` to accelerate future runs.
+4. **Visual QA Sentinel (`lib/crawler.ts`)**: Scans for layout overflow, overlapping views, and unlabelled accessibility nodes.
+
+---
+
+## 📊 Real-World Verification Benchmarks
+
+Tested and verified against live physical Android devices running complex multi-role enterprise apps (React Native / Expo):
+
+| Test Suite             | Total Steps | Passed | Failed | Pass Rate | Execution Time |
+| :--------------------- | :---------: | :----: | :----: | :-------: | :------------: |
+| **Teacher Role Suite** |     36      |   36   |   0    | **100%**  |     64.0s      |
+| **Student Role Suite** |     24      |   24   |   0    | **100%**  |     44.6s      |
+| **Total Benchmark**    |   **60**    | **60** | **0**  | **100%**  |   **108.6s**   |
+
+---
+
+## 📁 Repository Structure
+
+```text
+prompttest/
+├── bin/
+│   └── prompttest.ts        # CLI Entrypoint & Argument Router
+├── constants/
+│   └── commands.ts          # ADB Commands & Keycode Constants
+├── docs/
+│   ├── ACTION_ITEMS.md        # Working fix backlog (Phase 23 findings)
+│   ├── MODE_EXPECTATIONS.md   # Realistic capabilities, limits & boundaries per mode
+│   ├── ARCHITECTURE.md      # System Architecture & Design
+│   ├── USER_MANUAL.md       # Comprehensive User Guide
+│   ├── adr/                 # Architecture Decision Records
+│   └── IMPLEMENTATION_PLAN.md
+├── lib/
+│   ├── adb.ts               # ADB Interface & Streaming Driver
+│   ├── baseline.ts          # Visual Baseline Diffing & Masking
+│   ├── checkpoint.ts        # Test Progress Checkpointing
+│   ├── config.ts            # Configuration Constants
+│   ├── crawler.ts           # Visual Defect Detection & Screen Crawling
+│   ├── data-loader.ts       # Data-Driven Iterations & Dynamic Generators
+│   ├── dictionary.ts        # UI Taxonomy & Intent Dictionary
+│   ├── explorer.ts          # Autonomous Exploration Graph
+│   ├── form-filler.ts       # Smart Form Filling Engine
+│   ├── live-monitor.ts      # Real-Time Event Streaming Server
+│   ├── lock.ts              # File-Locking Device Leasing Mutex
+│   ├── logger.ts            # Structured Logging
+│   ├── memory.ts            # Persistent Knowledge & Fast-Forward Engine
+│   ├── patterns.ts          # Plain-English Grammar Parser
+│   ├── prompt-runner.ts     # Orchestration Engine (<1000 lines)
+│   ├── recorder.ts          # Autonomous Record & Replay
+│   ├── reporter.ts          # Multi-Format Report Generator (HTML/JSON/JUnit)
+│   ├── runner-utils.ts      # AST Parsing, Modular Includes, Diagnostic Errors
+│   └── step-handlers.ts     # Decoupled Step Execution Handlers
+├── memory/                  # Autonomous Learned Knowledge Mappings
+├── output/                  # Generated Test Reports & Artifacts
+├── specs/                   # Plain-English Test Specification Files
+├── tests/                   # Vitest Automated Test Suites
+├── index.ts                 # Programmatic API Entrypoint
+├── package.json
+├── tsconfig.json
+├── CONTRIBUTING.md
+├── LICENSE
+└── README.md
+```
+
+---
+
+## 💻 Programmatic SDK & Cross-Platform Drivers
+
+You can use PromptTest programmatically within your own Node.js scripts using the unified `DriverInterface`:
+
+```typescript
+import { createPromptRunner, createAndroidDriver, createIosDriver } from 'prompttest';
+
+// 🤖 Android Native Execution
+const androidDriver = createAndroidDriver('DEVICE_SERIAL');
+const androidRunner = createPromptRunner(androidDriver);
+const androidReport = await androidRunner.runSpec('specs/login.txt', 'com.example.app');
+
+// 🍎 iOS Execution (Simulator or Physical Device)
+const iosDriver = createIosDriver({ udid: 'SIMULATOR_UDID', bundleId: 'com.example.app' });
+const iosRunner = createPromptRunner(iosDriver);
+const iosReport = await iosRunner.runSpec('specs/login.txt', 'com.example.app');
+```
+
+---
+
+## ⚙️ Environment Variables
+
+- `LOG_LEVEL`: Controls the verbosity of logs. Set to `DEBUG`, `INFO`, `WARN`, `ERROR`, or `SILENT`.
+- `PROMPTTEST_DATA`: Overrides the default directory for PromptTest artifacts, memory, and outputs.
+
+---
+
+## 🤝 Contributing
+
+Contributions, bug reports, and feature requests are welcome! Please check out [CONTRIBUTING.md](CONTRIBUTING.md) to get started.
+
+---
+
+## 📄 License
+
+This project is open source and available under the [MIT License](LICENSE).

package/SECURITY.md

@@ -0,0 +1,56 @@
+# Security & Compliance Policy
+
+PromptTest is built with enterprise security, local execution privacy, and data isolation at its foundation.
+
+---
+
+## 1. Local-First Architecture Guarantee
+
+- **Zero Telemetry**: PromptTest does **not** collect, phone-home, or transmit usage metrics, telemetry, crash reports, or device serials to external cloud servers.
+- **Offline By Default**: Core test execution, OCR/UI parsing, accessibility hierarchy processing, and self-healing memory operate 100% locally via ADB and offline deterministic heuristics.
+- **Opt-in AI**: External LLM providers (OpenAI, Anthropic) are strictly opt-in and disabled by default. When enabled, only stripped element text fragments necessary for intent matching are transmitted; full app memory or credential payloads are never forwarded. Local model inference (e.g. Ollama via `PROMPTTEST_AI_BASE_URL`) is fully supported for air-gapped environments.
+
+---
+
+## 2. Reporting Vulnerabilities
+
+If you discover a security vulnerability within PromptTest or its dependencies, please disclose it responsibly.
+
+- **Security Contact**: Email security reports privately to `security@prompttest.dev` (or open a confidential security advisory on GitHub).
+- **Response SLA**:
+  - Initial acknowledgment: within **24 hours**.
+  - Triage and impact assessment: within **72 hours**.
+  - Remediation patch release: within **7 days** for critical/high vulnerabilities.
+- **Public Disclosure**: We kindly ask that you do not disclose the vulnerability publicly until a patch has been published.
+
+---
+
+## 3. Secret & Credential Handling Best Practices
+
+When writing PromptTest specifications and configuring CI/CD pipelines:
+
+1. **Never Hardcode Secrets in Specs**:
+   Use runtime variables (`--var:KEY=VAL`) or environment variables instead of hardcoding API keys, OTP codes, or passwords directly in `.txt` test files.
+   ```bash
+   npx prompttest run specs/login.txt --var:USER=$TEST_USER --var:PASS=$TEST_PASS
+   ```
+2. **Sanitize Data-Driven Test Fixtures**:
+   Store data files in `.gitignore` if they contain sensitive real-world records. Ensure `test-data.json` and credentials are never checked into version control.
+3. **Automated Secret Masking**:
+   PromptTest automatically masks input values targeting elements associated with passwords, PINs, auth tokens, or private secrets in execution logs and HTML reports.
+
+---
+
+## 4. Execution Sandboxing
+
+- **JavaScript Execution**: Custom JS hooks (`run js: ...`) execute in an isolated V8 context without direct access to Node.js `child_process`, `fs`, or network APIs.
+- **ADB Boundaries**: ADB execution is strictly scoped to test automation verbs (`shell input`, `shell uiautomator`, `shell am`, `shell pm`). Arbitrary device shell injection is prohibited.
+- **Concurrency Mutex**: Device-level file locking ensures concurrent test jobs cannot collide, cross-contaminate device states, or intercept parallel device streams.
+
+---
+
+## 5. Dependency & Supply Chain Security
+
+- **Strict Audit Gate**: CI enforces `npm audit --audit-level=high` on every pull request and build.
+- **Zero Copyleft**: All runtime dependencies are strictly licensed under permissive open-source licenses (MIT / ISC / Apache-2.0).
+- **Minimal Surface**: Production dependencies are strictly minimized (`chalk`, `pixelmatch`, `pngjs`) to minimize supply chain exposure.

package/dist/bin/prompttest.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};