prompttest-mobile 1.5.1

package/README.md

@@ -0,0 +1,526 @@
+# ⚡ PromptTest Mobile
+
+> **Ultra-fast, zero-code autonomous mobile testing & visual QA brain for Android & iOS.**  
+> The zero-setup, zero-instrumentation alternative to Appium & Detox for React Native, Expo, Flutter, and Native Android.
+
+[![npm version](https://img.shields.io/npm/v/prompttest-mobile.svg?color=cb3837)](https://www.npmjs.com/package/prompttest-mobile)
+[![License: BSL 1.1](https://img.shields.io/badge/License-BSL%201.1-blue.svg)](#-license)
+[![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)
+[![TypeScript](https://img.shields.io/badge/TypeScript-5.7-blue.svg)](https://www.typescriptlang.org/)
+
+> [!NOTE]
+> **Looking for the Python LLM prompt evaluator?** That project is [`decodingchris/prompttest`](https://github.com/decodingchris/prompttest).  
+> **This is PromptTest Mobile** — the autonomous mobile application QA and visual regression testing engine for native Android & iOS mobile applications. Available on NPM as [`prompttest-mobile`](https://www.npmjs.com/package/prompttest-mobile) and [`prompttest`](https://www.npmjs.com/package/prompttest).
+
+**PromptTest Mobile** enables QA engineers, mobile developers, and autonomous agents to test Android applications using **plain-English natural language scripts**. It completely bypasses heavy server frameworks (Appium, Selenium, WebDriver) in favor of high-speed native ADB streams, expectation-driven polling, and an autonomous state-graph exploration engine.
+
+---
+
+### 🖥️ Prefer a Visual Desktop IDE? Try PromptTest Studio
+
+If you prefer an intuitive desktop application over the command line, check out **[PromptTest Studio](https://shriramsingh.github.io/prompttest-studio-site/)**:
+- 📱 **Real-Time Device Mirroring**: Low-latency screen streaming with instant click, drag, and hardware navigation.
+- 🎯 **Visual Element Inspector**: Point and click to inspect native views with instant auto-generated plain-English assertions.
+- 📸 **Visual Regression & Exclude Masks**: Pixel-level baseline comparisons with draggable exclude masks for dynamic areas (clocks, battery, banners).
+- 🚀 **100% Local-First & Air-Gapped**: Runs entirely on your machine over local ADB with zero cloud dependencies.
+
+👉 **[Download PromptTest Studio for Windows](https://shriramsingh.github.io/prompttest-studio-site/downloads.html)** *(macOS & Linux coming soon)*
+
+---
+
+### 📑 Quick Navigation
+
+- [🖥️ PromptTest Studio (Desktop IDE)](#️-prefer-a-visual-desktop-ide-try-prompttest-studio)
+- [🚀 Quick Start & CLI Workflows](#-quick-start--cli-workflows)
+- [📂 Outputs, Reports & Screenshots](#-outputs-reports--screenshots)
+- [✍️ Writing Plain-English Tests](#️-writing-plain-english-tests)
+- [📖 Syntax Reference](#-syntax-reference)
+- [🛠 CLI Command Reference](#-cli-command-reference)
+- [🎯 Mode Expectations & Limits](#-mode-expectations--limits)
+- [💻 Programmatic TypeScript SDK](#-programmatic-typescript-sdk)
+- [🐳 Docker Deployment](#-docker-container-deployment)
+- [📊 Real-Device Benchmarks](#-proven-real-device-benchmarks)
+- [📄 License](#-license)
+
+---
+
+## 🌟 Why PromptTest?
+
+- 📝 **Plain-English Test Scripts**: Write tests in human language without writing fragile XPath selectors or boilerplate glue code.
+- ⚡ **Zero-Setup & Zero-Instrumentation**: Connects directly over native ADB (USB or Wi-Fi). No SDKs, test dependencies, or code modifications required in your target app.
+- 🤖 **Autonomous State-Graph DFS Explorer**: Crawls apps autonomously, detects bottom-tab navigation hubs, traverses nested screens, and automatically triages defects without human intervention.
+- 💡 **Dynamic Self-Healing Locators**: Resilient heuristic matching automatically adapts to changing dynamic counts (e.g. auto-resolving `"Present (2)"` to `"Present (5)"`).
+- 🛡 **Built-In Safety Engine**: Guards production and staging apps by blocking destructive actions (e.g., `"Delete Account"`, `"Discard Changes"`) during autonomous crawls.
+- 📊 **Standalone HTML & JUnit Reports**: Generates executive test reports with failure-only visual screenshots and actionable error diffs.
+- 🌐 **Built for Modern Mobile Frameworks**: Native support for **React Native**, **Expo**, **Flutter**, and Native Android (Jetpack Compose / Views).
+
+---
+
+## 🚀 Quick Start & CLI Workflows
+
+### Prerequisites
+
+- **Node.js 18.0.0+**
+- **Android ADB** installed and accessible in your system `PATH`
+- An Android device (USB or Wi-Fi) or emulator with **USB Debugging** enabled
+
+### Install in Your Mobile Project
+
+You can run PromptTest instantly with `npx` or install it as a dev dependency:
+
+```bash
+# In your React Native, Expo, Flutter, or Android project:
+npm install --save-dev prompttest
+```
+
+> **⚖️ Licensing note**: PromptTest is source-available under **BSL 1.1** — free for personal, educational, open-source, and small-team use (< $100k revenue _and_ < 10 employees). Larger organizations and commercial QA agencies need a [commercial license](#-license). It converts to Apache 2.0 in 2030. See [License](#-license).
+
+---
+
+### 5 Core CLI Workflows
+
+#### 1. Environment Diagnostic Check
+
+Before running tests, verify your ADB connectivity, connected devices, and permissions:
+
+```bash
+npx prompttest doctor
+```
+
+#### 2. Zero-Code Autonomous Exploration (AI App Crawl)
+
+Crawl bottom tabs, lists, and forms automatically to discover bugs, crashes, or React Native red-screens without writing a single line of test code:
+
+```bash
+npx prompttest explore com.yourcompany.app
+```
+
+_Tip: `explore` is its own top-level command. Pass `--max-screens=30` or `--safety-mode=strict` to customize._
+
+#### 3. Interactive Record & Replay
+
+Record your natural interactions on a physical phone directly into a reusable test spec:
+
+```bash
+npx prompttest record specs/login.txt
+```
+
+- Tap buttons and type in input fields on your phone; PromptTest auto-generates conversational English test steps.
+- **Append mode**: Add `--append` to add more steps to an existing spec without overwriting.
+- **Safety backup**: If the target file already exists, PromptTest automatically creates a `.bak` backup before modifying.
+
+#### 4. Run Plain-English Test Specs
+
+Execute test specifications with fail-fast validation and locator self-healing:
+
+```bash
+npx prompttest run specs/login.txt com.yourcompany.app
+```
+
+Power flags:
+
+- `--heal`: Automatically self-heal altered counts and dynamic locators.
+- `--video`: Record an MP4 video of the execution session.
+- `--screenshots`: Capture high-resolution visual evidence at every step.
+- `--fresh`: Cold-restart the target app before execution begins.
+- `--embed-screenshots`: Embed screenshots directly into a standalone, shareable HTML report.
+
+#### 5. Interactive Live REPL Playground
+
+Experiment with commands live in your terminal against your connected device:
+
+```bash
+npx prompttest repl com.yourcompany.app
+```
+
+---
+
+### ⚠️ CLI Command Disambiguation Table
+
+To avoid common syntax errors, remember that `explore`, `record`, and `repl` are **standalone commands**:
+
+| Goal                          | ✅ Correct CLI Command                | ❌ Common Mistake            |
+| :---------------------------- | :------------------------------------ | :--------------------------- |
+| **Autonomous App Crawling**   | `npx prompttest explore <pkg>`        | `npx prompttest run explore` |
+| **Record from Phone Touches** | `npx prompttest record <spec.txt>`    | `npx prompttest run record`  |
+| **Run Existing Spec File**    | `npx prompttest run <spec.txt> [pkg]` | `npx prompttest <spec.txt>`  |
+| **Interactive Live Terminal** | `npx prompttest repl [pkg]`           | `npx prompttest run repl`    |
+| **Diagnostic Health Check**   | `npx prompttest doctor`               | `npx prompttest run doctor`  |
+
+---
+
+### 📦 Recommended `package.json` Scripts
+
+Add these convenient shortcuts to your project's `package.json`:
+
+```json
+"scripts": {
+  "test:mobile": "prompttest run specs/smoke.txt com.yourcompany.app --heal",
+  "test:explore": "prompttest explore com.yourcompany.app --max-screens=25",
+  "test:record": "prompttest record specs/new_flow.txt",
+  "test:doctor": "prompttest doctor"
+}
+```
+
+---
+
+## 📂 Outputs, Reports & Screenshots
+
+Whenever PromptTest runs (`run`, `explore`, or `record`), all outputs are automatically organized inside an **`output/`** folder at your project root:
+
+```
+your-mobile-project/
+├── node_modules/
+├── specs/
+│   └── login.txt
+├── output/                               <-- 📂 Created automatically
+│   ├── login-report.html                 <-- 🌐 Interactive visual HTML report
+│   ├── login-junit.xml                   <-- 🤖 CI/CD JUnit test results
+│   ├── login-report.md                   <-- 📝 Markdown summary for PR comments
+│   ├── login-results.json                <-- 📊 Structured raw JSON execution metrics
+│   ├── step_1_tap_sign_in.png            <-- 📸 High-res visual screenshots
+│   ├── login-recording.mp4               <-- 🎥 Full MP4 video (when using --video)
+│   └── screenshots/                      <-- 📸 Screen transition photos from record sessions
+```
+
+### Viewing & Sharing Reports:
+
+- **Interactive HTML Dashboard (`output/<spec>-report.html`)**: Double-click to open in any browser. Features step-by-step audit timelines, latency timings, and failure triage bundles.
+- **CI/CD Integration (`output/<spec>-junit.xml`)**: Standard JUnit format natively recognized by GitHub Actions, GitLab CI, Jenkins, and CircleCI.
+- **Zero-Dependency Sharing (`--embed-screenshots`)**: Generates a single standalone HTML report with all images inlined via Base64 data URIs. Email or Slack it directly to teammates without missing image links!
+
+---
+
+## ✍️ Writing Plain-English Tests
+
+Test specifications are simple text files containing numbered steps written in conversational English.
+
+### Example Spec (`specs/login_and_dashboard.txt`)
+
+```text
+# 1. Authentication Flow
+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 & Navigation
+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
+```
+
+### Run the Spec:
+
+```bash
+npx prompttest run specs/login_and_dashboard.txt com.yourcompany.app
+```
+
+---
+
+## 📖 Syntax Reference
+
+| Category          | Command Syntax                           | Description                                                         |
+| :---------------- | :--------------------------------------- | :------------------------------------------------------------------ |
+| **Tap / Click**   | `Tap 'Sign In'`                          | Taps button, icon, link, or tab matching label or text.             |
+| **Input Fields**  | `Type 'user@test.com' into 'Email'`      | Auto-focuses field, clears existing text, and enters string safely. |
+| **Assertions**    | `Verify 'Dashboard' is visible`          | Polls until the element appears on screen (sub-second resolution).  |
+| **Absence Check** | `Verify 'Loading...' is not visible`     | Confirms an element, dialog, or spinner has dismissed.              |
+| **Spatial Tap**   | `Tap 'Delete' next to 'Order #12'`       | Disambiguates duplicate elements using directional proximity.       |
+| **Gestures**      | `Scroll down`, `Scroll up`, `Swipe left` | Performs viewport-proportional touch flings.                        |
+| **Hardware Keys** | `Press back`, `Press home`               | Dispatches physical Android keycodes (`KEYCODE_BACK`, etc.).        |
+| **Delays**        | `Wait 2s` or `Wait 1500ms`               | Pauses execution for custom animation settling.                     |
+| **Conditionals**  | `Tap 'Dismiss' (if present)`             | Executes step only if element exists, without failing the suite.    |
+| **Generators**    | `$random.email`, `$date.now`, `$uuid`    | Inlines dynamic synthetic data into input fields.                   |
+
+---
+
+## 🛠 CLI Command Reference
+
+### Primary Execution Modes
+
+```bash
+# 1. Deterministic Spec Runner
+npx prompttest run specs/flow.txt <package>
+
+# Cold-restart app before suite begins
+npx prompttest run specs/flow.txt <package> --fresh
+
+# Capture high-resolution visual screenshots on every step
+npx prompttest run specs/flow.txt <package> --screenshots
+
+# Dry-run validation (checks syntax without touching device)
+npx prompttest run specs/flow.txt --dry-run
+
+# Display formatted table of parsed steps
+npx prompttest run specs/flow.txt --list-steps
+
+# Run data-driven iterations
+npx prompttest run specs/flow.txt <package> --iterations 5
+
+# Run against a managed device pool with concurrency leasing
+npx prompttest run specs/flow.txt <package> --device-pool emulator-5554,emulator-5556
+
+# Visual regression testing against gold baseline images
+npx prompttest run specs/flow.txt --save-baseline
+npx prompttest run specs/flow.txt --compare-baseline --baseline-threshold=0.02
+```
+
+### Autonomous State-Graph Explorer (`explore`)
+
+```bash
+# Autonomous exploration with Strict safety policy
+npx prompttest explore <package>
+
+# Set custom screen discovery and step interaction limits
+npx prompttest explore <package> --max-screens=30 --step-budget=60
+
+# Protect custom sensitive action keywords from being clicked
+npx prompttest explore <package> --safety-blacklist="Wipe,Revoke,Transfer"
+```
+
+### Interactive Record & Replay (`record`)
+
+```bash
+# Record gestures, taps, and inputs directly on device into a spec
+npx prompttest record specs/recorded_flow.txt
+```
+
+### Device Management & Wi-Fi Debugging
+
+```bash
+# List all connected devices, emulators, and serial numbers
+npx prompttest devices
+
+# Connect to physical device wirelessly over Wi-Fi
+npx prompttest wifi 192.168.1.50
+
+# Inspect active screen hierarchy and detected components
+npx prompttest status
+
+# Run comprehensive environment diagnostic check
+npx prompttest doctor
+
+# View offline learned component memory graph
+npx prompttest memory <package>
+```
+
+---
+
+## 🎯 Platform Support, Expectations & Boundaries
+
+To maintain honest expectations, here is what PromptTest currently supports, what is under active development, and its architectural boundaries:
+
+| Platform / Framework               |        Supported?        | Notes                                                                  |
+| :--------------------------------- | :----------------------: | :--------------------------------------------------------------------- |
+| **Android (Physical & Emulators)** | **✅ Production Ready**  | React Native, Expo, Flutter, Native Views, Jetpack Compose.            |
+| **iOS / iPhone & iPad**            | **🚧 Under Development** | Native iOS engine is in active development; not supported in v1.3.x.   |
+| **Websites / Desktop Browsers**    |   **❌ Not Supported**   | Dedicated strictly to mobile apps. For web, use Playwright or Cypress. |
+| **Standard UI Hierarchy**          |       **✅ Full**        | Operates 100% via native ADB hierarchy stream (`uiautomator dump`).    |
+| **Self-Healing Dynamic Locators**  |       **✅ Full**        | Auto-resolves modified counts and labels dynamically via `--heal`.     |
+| **Bottom-Tab Discovery**           |       **✅ Full**        | Explores hubs, nested master-detail views, and backtracks cleanly.     |
+| **Game Engines & Canvas**          |   **⚠️ Not Supported**   | Fully custom OpenGL/Vulkan/Unity games lack accessible UI nodes.       |
+| **Biometrics / OS Dialogs**        |      **⚠️ Limited**      | System-level biometric prompts require hardware-level mocks.           |
+
+---
+
+## ⚠️ Common Pitfalls & How to Solve Them
+
+### 1. Hardware Back Button Minimizing the App
+
+- **What happens**: Running `Press back` while on the app's root dashboard or home tab tells the Android OS to minimize or exit the app.
+- **How to solve it**:
+  - In specs, tap the in-app back icon/button (e.g. `Tap 'Back'` or `Tap '<'`) instead of the hardware key on top-level screens.
+  - In autonomous exploration (`explore`), PromptTest's built-in **Package Jail Guard** automatically detects if the app was backgrounded and restores it.
+  - Add the `--fresh` flag when running specs to cold-start your app cleanly before tests.
+
+### 2. Android OS Permission Dialogs ("Allow Notifications / Location")
+
+- **What happens**: System dialogs belong to Android OS (`com.android.permissioncontroller`), not your app, and can appear unexpectedly on new installs.
+- **How to solve it**:
+  - Use conditional handling in your spec:
+    ```text
+    Tap 'While using the app' (if present)
+    Tap 'Allow' (if present)
+    ```
+  - Or auto-grant permissions via ADB before running tests:
+    ```bash
+    adb shell pm grant com.yourcompany.app android.permission.POST_NOTIFICATIONS
+    ```
+
+### 3. Off-Screen Items in Long Lists (FlatList / RecyclerView)
+
+- **What happens**: Mobile frameworks only render visible items on screen to save memory. Elements located further down the page are not in the hierarchy yet.
+- **How to solve it**:
+  - Scroll before tapping:
+    ```text
+    Scroll down
+    Verify 'Save Changes' is visible
+    Tap 'Save Changes'
+    ```
+
+### 4. Layout Animations & Shimmer Settling
+
+- **What happens**: Tapping an element during a layout animation or skeleton fade-in can cause touch coordinates to miss while elements shift.
+- **How to solve it**:
+  - Add a brief settling pause: `Wait 500ms` or assert an anchor element first: `Verify 'Dashboard' is visible`.
+  - Disable animations on test devices to run tests 2x faster:
+    ```bash
+    adb shell settings put global window_animation_scale 0
+    adb shell settings put global transition_animation_scale 0
+    adb shell settings put global animator_duration_scale 0
+    ```
+
+### 5. WebViews & In-App Browsers (OAuth & Payment Gateways)
+
+- **What happens**: In-app web pages (like Google Sign-In or Stripe) expose rendered text to ADB, but not internal HTML DOM tags or CSS selectors.
+- **How to solve it**:
+  - Use plain text matching (`Tap 'Sign in with Google'`). Deep DOM selector manipulation inside WebViews is not supported.
+
+### 6. Multiple Devices Connected
+
+- **What happens**: If a physical phone and an emulator are both plugged in, ADB doesn't know which one to target.
+- **How to solve it**:
+  - Target a specific device serial using `--serial`:
+    ```bash
+    npx prompttest run specs/login.txt com.app --serial=emulator-5554
+    ```
+
+---
+
+## 💡 Pro-Tips & Best Practices
+
+### 1. The "Record & Refine" Workflow
+
+- `prompttest record` captures your natural physical device interactions and generates plain-English test steps in real time—scaffolding 90% of your test boilerplate in seconds.
+- **QA Best Practice**: After recording, do a quick 30-second review of the generated `.txt` spec to fine-tune timings or add custom `Verify` assertions.
+- Preview without touching your device:
+  ```bash
+  npx prompttest run specs/flow.txt --dry-run
+  ```
+
+### 2. Deterministic Clean States (`--fresh`)
+
+- Prevent "already-logged-in" test pollution by adding `--fresh` to cold-start the target app before execution:
+  ```bash
+  npx prompttest run specs/login.txt com.yourcompany.app --fresh
+  ```
+
+### 3. Zero-Maintenance Dynamic Badges (`--heal`)
+
+- When notification badges or counts change dynamically (e.g. `'Cart (1)'` vs `'Cart (3)'`), pass `--heal` to allow PromptTest's heuristic engine to self-heal the locator without failing.
+
+### 4. Device & Screen Resolution Agnostic Portability
+
+- PromptTest binds interactions to semantic accessibility labels and proportional gestures—not fragile hardware pixel coordinates. Specs recorded on a phone seamlessly run on foldables and tablets.
+
+### 5. 🛡️ Enterprise Safety Guardrails & Custom Blacklists
+
+Autonomous exploration is safe by default, but enterprise applications often have company-specific sensitive keywords (e.g. _"Deactivate"_, _"Transfer Funds"_, _"Revoke Access"_).
+
+- **Default Protection**: PromptTest automatically detects and blocks destructive actions like `"Delete"`, `"Wipe"`, `"Remove"`, and `"Discard Changes"`.
+- **Add Your Own Sensitive Keywords**: You can supply your own custom blocked keywords to run **alongside** the defaults:
+  ```bash
+  # Via CLI flag:
+  npx prompttest explore com.yourcompany.app --safety-blacklist="Transfer,Deactivate,Revoke,Unsubscribe"
+  ```
+- **Or configure once in `.prompttestrc.json`**:
+  ```json
+  {
+    "safety": {
+      "mode": "strict",
+      "customBlacklist": ["Transfer", "Deactivate", "Revoke", "Unsubscribe"]
+    }
+  }
+  ```
+
+---
+
+## 💻 Programmatic TypeScript SDK
+
+PromptTest exports a full programmatic SDK for embedding into Node.js test runners or custom CI scripts:
+
+```typescript
+import { createPromptRunner, createAndroidDriver } from 'prompttest';
+
+// Initialize native ADB driver for connected device
+const driver = createAndroidDriver('DEVICE_SERIAL');
+const runner = createPromptRunner(driver);
+
+// Execute spec and retrieve structured execution report
+const report = await runner.runSpec('specs/login.txt', 'com.example.app', {
+  fresh: true,
+  screenshots: 'failure-only',
+});
+
+console.log(`Execution complete: ${report.passedSteps}/${report.totalSteps} passed.`);
+```
+
+---
+
+## 🐳 Docker Container Deployment
+
+PromptTest is containerized with Android platform-tools and headless runtime support:
+
+```bash
+# Build container image
+docker build -t prompttest .
+
+# Execute 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/flow.txt com.example.app
+```
+
+---
+
+## 📊 Proven Real-Device Benchmarks
+
+Tested and verified against live physical Android devices running complex multi-role enterprise apps:
+
+| Test Suite                        | Total Steps | Passed | Failed | Pass Rate | Execution Time |
+| :-------------------------------- | :---------: | :----: | :----: | :-------: | :------------: |
+| **CoachConnect Enterprise Suite** |     52      |   52   |   0    | **100%**  |     47.8s      |
+| **Govindam Multilingual Suite**   |      8      |   8    |   0    | **100%**  |     35.1s      |
+| **Calculator Operations Suite**   |      5      |   5    |   0    | **100%**  |     19.6s      |
+| **Automated Vitest Test Matrix**  |     294     |  294   |   0    | **100%**  |     14.8s      |
+
+_For deep architectural details and driver design, see `docs/ARCHITECTURE.md` included in the package._
+
+---
+
+## 📄 License
+
+PromptTest is licensed under the **Business Source License 1.1 (BSL 1.1)**, and automatically converts to the permissive **Apache License 2.0** on the Change Date: **September 14, 2030**.
+
+**✅ Free to use — no license required for:**
+
+- Personal, educational, academic, and open-source projects
+- Evaluation use
+- Internal software testing within organizations that have **both** under $100,000 USD in annual gross revenue **and** fewer than 10 employees
+
+**💼 Commercial license required for:**
+
+- Use within organizations exceeding either of the free-tier thresholds (revenue **or** headcount)
+- Testing agencies providing commercial QA services to third-party clients
+- Deployment into production commercial CI/CD pipelines
+- Offering PromptTest (modified or unmodified) as a hosted or managed QA/cloud testing service
+
+See the full [LICENSE](./LICENSE) and [Terms & Conditions](./TERMS.md) for exact terms.
+
+Commercial inquiries and enterprise licensing: `jairam.singh9@gmail.com` or open an issue at [github.com/shriramsingh/prompttest-community](https://github.com/shriramsingh/prompttest-community/issues).

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.