prompttest 1.3.4 → 1.4.0

package/dist/lib/adb-provisioner.d.ts

@@ -0,0 +1,55 @@
+/**
+ * @module adb-provisioner
+ * @description
+ * Zero-dependency hardware discovery and ADB provisioning engine.
+ * Automatically discovers, validates, and provisions Android Debug Bridge (ADB)
+ * binaries across Windows, macOS, and Linux without requiring full Android Studio installation.
+ */
+export interface AdbDiagnosticInfo {
+    binaryPath: string;
+    isAvailable: boolean;
+    version?: string;
+    source: 'PROMPTTEST_OVERRIDE' | 'BUNDLED_LOCAL' | 'SYSTEM_PATH' | 'ANDROID_HOME' | 'STANDALONE_CACHE' | 'STANDARD_SDK' | 'FALLBACK';
+}
+/**
+ * Discovers the absolute or executable path to the ADB binary on the host system.
+ * Evaluates candidate locations in strict order of reliability:
+ * 1. Environment override (`PROMPTTEST_ADB_PATH`)
+ * 2. Bundled / Adjacent platform-tools (next to executable, app bundle, or current cwd)
+ * 3. System PATH lookup
+ * 4. Android SDK environment variables (`ANDROID_HOME`, `ANDROID_SDK_ROOT`)
+ * 5. Standard platform installation paths
+ * 6. Standalone user cache (`~/.prompttest/platform-tools/adb`)
+ */
+export declare function getAdbBinary(): string;
+/**
+ * Checks whether the resolved ADB binary is executable and operational.
+ *
+ * @param customPath Optional custom binary path to verify.
+ */
+export declare function isAdbAvailable(customPath?: string): boolean;
+/**
+ * Returns full diagnostics about ADB availability and resolution origin.
+ */
+export declare function getAdbDiagnostics(): AdbDiagnosticInfo;
+/**
+ * Resets cached ADB path (useful for testing and runtime environment shifts).
+ */
+export declare function resetAdbCache(): void;
+/**
+ * Automatically downloads and provisions official platform-tools if ADB is missing.
+ */
+export declare function downloadPlatformToolsFallback(customDestDir?: string): Promise<string>;
+/**
+ * Prompts the user for explicit permission to download official platform-tools if ADB is missing.
+ * Automatically approved if --download-adb, -y, or --yes flag is present in process.argv.
+ */
+export declare function promptUserForAdbDownload(): Promise<boolean>;
+/**
+ * Asserts that ADB is available, prompting for user permission before automated provisioning if missing.
+ *
+ * @param options.skipPrompt If true, bypasses the user prompt (e.g. when --download-adb flag is passed).
+ */
+export declare function ensureAdbProvisioned(options?: {
+    skipPrompt?: boolean;
+}): Promise<string>;

package/dist/lib/adb.d.ts

@@ -19,6 +19,29 @@ export interface AndroidDevice {
     /** The product name of the device (optional) */
     product?: string;
 }
+export interface DeviceMetrics {
+    battery?: {
+        level?: number;
+        temperatureC?: number;
+        status?: string;
+    };
+    display?: {
+        width?: number;
+        height?: number;
+        density?: number;
+    };
+    memory?: {
+        pssKb?: number;
+        privateDirtyKb?: number;
+        nativeHeapKb?: number;
+    };
+    graphics?: {
+        framesRendered?: number;
+        jankyFrames?: number;
+        percentile90Ms?: number;
+    };
+}
+export declare function parseDeviceMetrics(batteryOutput: string, displayOutput: string, memoryOutput: string, graphicsOutput: string): DeviceMetrics;
 /**
  * AndroidDriver is responsible for executing ADB commands and handling device interactions.
  * It manages the default targeted device, executes shell commands, extracts device state,
@@ -323,6 +346,11 @@ export declare class AndroidDriver {
      * @throws An Error if the device IP cannot be detected.
      */
     disconnectWifi(target?: string): Promise<string>;
+    pairWifi(target: string, pairingCode: string): Promise<{
+        success: boolean;
+        message: string;
+    }>;
+    getDeviceMetrics(serial?: string): Promise<DeviceMetrics>;
     /**
      * Streams the Android events logcat buffer in real-time.
      * Used for detecting screen transitions via wm_on_resume_called events.

package/dist/lib/baseline.d.ts

@@ -2,19 +2,33 @@
  * Rectangular region on the screen to ignore during visual comparison.
  */
 export interface MaskRegion {
-    /** The starting horizontal pixel coordinate. */
+    /** The starting horizontal pixel coordinate or relative float (0.0 - 1.0). */
     x: number;
-    /** The starting vertical pixel coordinate. */
+    /** The starting vertical pixel coordinate or relative float (0.0 - 1.0). */
     y: number;
-    /** Width of the region in pixels. */
+    /** Width of the region in pixels or relative float (0.0 - 1.0). */
     width: number;
-    /** Height of the region in pixels. */
+    /** Height of the region in pixels or relative float (0.0 - 1.0). */
     height: number;
+    /** Optional human-readable label for the ignored region (e.g., 'Status Bar', 'Clock'). */
+    label?: string;
 }
+/**
+ * Predefined tolerance and sensitivity presets for visual comparison.
+ */
+export type MatchingMode = 'strict' | 'moderate' | 'relaxed';
+export declare const MATCHING_MODES: Record<MatchingMode, {
+    threshold: number;
+    pixelmatchThreshold: number;
+    label: string;
+    description: string;
+}>;
 /**
  * Options for configuring visual baseline comparisons.
  */
 export interface BaselineCompareOptions {
+    /** Matching preset mode ('strict', 'moderate', 'relaxed'). Defaults to 'moderate'. */
+    mode?: MatchingMode;
     /** Override the maximum allowed diffRatio (0.0 to 1.0) before failing. */
     threshold?: number;
     /** Array of bounding boxes to mask out (e.g. dynamic clocks, battery, animations). */
@@ -61,6 +75,24 @@ export declare class BaselineManager {
     constructor(baselineDir?: string, threshold?: number);
     private filePath;
     private diffFilePath;
+    private masksFilePath;
+    /**
+     * Retrieves saved mask regions for a specific test step.
+     *
+     * @param specName The name of the test specification.
+     * @param stepIndex The 0-based index of the step within the spec.
+     * @returns Array of MaskRegion bounding boxes.
+     */
+    getMasks(specName: string, stepIndex: number): Promise<MaskRegion[]>;
+    /**
+     * Persists mask regions to disk for a specific test step.
+     *
+     * @param specName The name of the test specification.
+     * @param stepIndex The 0-based index of the step within the spec.
+     * @param masks Array of MaskRegion bounding boxes.
+     * @returns The file path where masks were stored.
+     */
+    saveMasks(specName: string, stepIndex: number, masks: MaskRegion[]): Promise<string>;
     /**
      * Saves a new screenshot as the baseline reference for a specific test step.
      * Uses an atomic write (via a temp file) to prevent partial writes.
@@ -96,14 +128,30 @@ export declare class BaselineManager {
     private fitToCanvas;
     /**
      * Masks specified rectangular regions in-place by setting their RGBA values to 0.
+     * Supports both pixel coordinates and relative fractional coordinates (0.0 to 1.0).
      */
     private applyMasks;
+    /**
+     * Overwrites the golden baseline with the current screenshot or a provided buffer.
+     *
+     * @param specName The name of the test specification.
+     * @param stepIndex The 0-based index of the step within the spec.
+     * @param screenshot Optional replacement buffer; if omitted, copies current run screenshot.
+     */
+    approveBaseline(specName: string, stepIndex: number, screenshot?: Buffer): Promise<string>;
     /**
      * Deletes all saved baseline, current, and diff images for a given spec.
      *
      * @param specName The name of the test specification to clear baselines for.
      */
     clearBaselines(specName: string): Promise<void>;
+    /**
+     * Deletes all saved baseline, current, diff images, and masks for a single specific step.
+     *
+     * @param specName The name of the test specification.
+     * @param stepIndex The 1-based step index to delete.
+     */
+    deleteStepBaseline(specName: string, stepIndex: number): Promise<void>;
 }
 /**
  * A globally accessible singleton instance of BaselineManager.

package/dist/lib/dfs-engine.d.ts

@@ -25,6 +25,28 @@ export interface NavigationFrame {
     actionTaken?: string;
     timestamp: number;
 }
+/**
+ * Telemetry event emitted by the DFS engine while traversing the state graph.
+ * Consumed by the Studio Auto-Pilot tab through the live-server SSE stream.
+ */
+export interface DfsTelemetryEvent {
+    /** Event category: executor action, screen discovery, safety block, defect, or completion. */
+    type: 'action' | 'state_change' | 'safety_block' | 'crash' | 'done';
+    /** Plain-English description. Action descriptions are spec-compatible instructions. */
+    description: string;
+    /** Canonical semantic hash of the screen the event occurred on. */
+    screenHash?: string;
+    /** Human-readable screen title (domain path) used to label the state-graph node. */
+    screenTitle?: string;
+    /** DFS depth of the screen the event occurred on. */
+    depth?: number;
+    /** Number of interactive candidate elements catalogued on the screen. */
+    elementCount?: number;
+    /** Number of unique screens discovered so far. */
+    discoveredScreens?: number;
+    /** Number of interaction steps consumed so far. */
+    totalSteps?: number;
+}
 export interface DfsEngineOptions {
     packageName: string;
     serial?: string;
@@ -36,6 +58,12 @@ export interface DfsEngineOptions {
     safetyBlacklist?: readonly (string | RegExp)[];
     screenshotPolicy?: 'all' | 'state-change' | 'failure-only';
     skipAlreadyCrawled?: boolean;
+    /** Optional telemetry sink invoked for every traversal event (Studio Auto-Pilot SSE). */
+    onStep?: (event: DfsTelemetryEvent) => void;
+    /** Optional abort flag checked between steps to terminate traversal gracefully. */
+    abortSignal?: {
+        aborted: boolean;
+    };
 }
 /**
  * Universal Hierarchical State-Graph DFS Engine (Universal Exploration Engine).
@@ -55,7 +83,22 @@ export declare class HierarchicalDfsEngine {
     devDefectsList: string[];
     safetyHitList: string[];
     externalSkippedList: string[];
+    /** Telemetry listener registered for the active traversal session. */
+    private stepListener?;
+    /** Abort flag registered for the active traversal session. */
+    private abortFlag?;
     constructor(driver?: AndroidDriver, reporter?: QaReporter, memory?: MemoryEngine);
+    /**
+     * Emits a telemetry event to the registered listener, defaulting the live counters.
+     * Screen depth and element counts are back-filled from the state-graph ledger so the
+     * Studio Auto-Pilot graph renders real hierarchy instead of a flat staircase.
+     * Listener failures are swallowed so observability can never break traversal.
+     *
+     * @param event - The traversal event to broadcast.
+     */
+    private emitStep;
+    /** Returns true when the active session has been aborted by the caller. */
+    private isAborted;
     /**
      * Captures UI hierarchy globally, intercepting and triaging any development error consoles,
      * LogBox overlays, warnings, info toasts, or ANRs before returning a clean app hierarchy.

package/dist/lib/explorer.d.ts

@@ -3,6 +3,36 @@ import { type SafetyMode, type UiNode } from './crawler.js';
 import { SemanticFormFiller } from './form-filler.js';
 import { QaReporter } from './reporter.js';
 import { MemoryEngine } from './memory.js';
+/**
+ * Represents a single autonomous exploration event, emitted as the explorer acts.
+ * Used for Studio SSE streaming via the /api/explore/* endpoints.
+ */
+export interface ExploreEvent {
+    /** Type of event: action taken, state change, safety block, crash intercepted, session done, or error. */
+    type: 'action' | 'state_change' | 'safety_block' | 'crash' | 'done' | 'error';
+    /** Monotonic step counter within this session. */
+    stepNumber: number;
+    /** Human-readable description of the event. */
+    description: string;
+    /** MD5-prefix hash of the screen hierarchy at this moment (for state-graph nodes). */
+    screenHash?: string;
+    /** Optional human-readable title for the screen (domain path) used to label the state-graph node. */
+    screenTitle?: string;
+    /** Optional traversal depth of the screen this event occurred on (DFS nesting level). */
+    depth?: number;
+    /** Optional number of interactive candidate elements catalogued on the screen. */
+    elementCount?: number;
+    /** Total discovered unique screens so far. */
+    discoveredScreens?: number;
+    /** Duration of the action in milliseconds. */
+    durationMs?: number;
+    /** Total step budget consumed so far. */
+    totalSteps?: number;
+    /** Package being explored. */
+    packageName?: string;
+    /** Auto-generated spec lines (only present on 'done' event). */
+    generatedSpec?: string;
+}
 /**
  * Configuration options for the AutonomousExplorer.
  */
@@ -31,6 +61,20 @@ export interface ExplorerOptions {
     stepBudget?: number;
     /** Screenshot policy ('state-change', 'failure-only', 'all') (AX-16). Default is 'state-change'. */
     screenshots?: 'state-change' | 'failure-only' | 'all';
+    /** Whether to record entire exploration session to an MP4 video (Phase 26). Default is false. */
+    video?: boolean;
+    /**
+     * Optional callback fired after every significant exploration event.
+     * Used by live-server to SSE-stream progress to Studio Auto-Pilot tab.
+     */
+    onStep?: (event: ExploreEvent) => void;
+    /**
+     * Optional abort signal. When set, the explorer checks this flag between steps
+     * and terminates the session gracefully if it becomes true.
+     */
+    abortSignal?: {
+        aborted: boolean;
+    };
 }
 /**
  * AutonomousExplorer implements the heuristic mobile crawler.

package/dist/lib/feedback.d.ts

@@ -0,0 +1,35 @@
+/**
+ * @module feedback
+ * @description
+ * Direct in-CLI feedback and community suggestion portal for PromptTest.
+ * Collects user ratings, feature suggestions, or issue reports and generates
+ * 1-click pre-filled submissions to the public prompttest-community repository.
+ */
+export type FeedbackCategory = 'feature' | 'bug' | 'general';
+export interface FeedbackData {
+    rating?: number;
+    category: FeedbackCategory;
+    message: string;
+    author?: string;
+    environment?: string;
+}
+export interface FeedbackOptions {
+    input?: NodeJS.ReadableStream;
+    output?: NodeJS.WritableStream;
+    directMessage?: string;
+    category?: FeedbackCategory;
+}
+/**
+ * Constructs a pre-filled GitHub issue or discussion URL based on the feedback category.
+ *
+ * @param data - The user feedback payload.
+ * @returns The fully-encoded GitHub URL.
+ */
+export declare function buildFeedbackUrl(data: FeedbackData): string;
+/**
+ * Starts an interactive feedback collection session in the terminal.
+ *
+ * @param options - Stream and direct message options.
+ * @returns The generated pre-filled GitHub URL.
+ */
+export declare function startFeedbackSession(options?: FeedbackOptions): Promise<string>;

package/dist/lib/live-server.d.ts

@@ -8,6 +8,7 @@
  */
 import http from 'http';
 import { AuditStep, QaReportData } from './reporter.js';
+import { AndroidDriver } from './adb.js';
 export interface LiveServerOptions {
     /** The port number to listen on. Defaults to 4040 (or 0 for random available port). */
     port?: number;
@@ -15,10 +16,14 @@ export interface LiveServerOptions {
     host?: string;
     /** Directory where screenshots, recordings, and report artifacts are located. */
     outputDir?: string;
+    /** Directory containing test specifications. Defaults to process.cwd()/specs. */
+    specsDir?: string;
     /** Name of the test suite being executed. */
     suiteName?: string;
     /** Initial report data if available. */
     initialReport?: QaReportData;
+    /** Optional AndroidDriver instance for interactive device state and actions. */
+    driver?: AndroidDriver;
 }
 export interface LiveServerHandle {
     /** The underlying Node.js HTTP server instance. */

package/dist/lib/recorder.d.ts

@@ -23,6 +23,7 @@ export interface RecordedEvent {
  * into semantic PromptTest step instructions.
  */
 export declare class AutonomousRecorder {
+    onStep?: (step: string) => void;
     private driver;
     private deviceLock;
     private isRecording;
@@ -82,6 +83,29 @@ export declare class AutonomousRecorder {
      */
     private appendStep;
     private extractBrandSlug;
+    /**
+     * Starts an interactive real-time recording session on the target Android device.
+     * Automatically detects the active app, starts capturing gestures and key events,
+     * monitors screen transitions, and writes out a plain-text spec.
+     *
+     * @param outputSpecPath Optional file path to save the generated test spec to.
+     * @param serial Optional serial number of the target device to record from.
+     * @param options Additional recording configuration options.
+     * @returns A promise that resolves when the recording session concludes.
+     */
+    /**
+     * Starts a non-blocking recording session (used by both CLI and Live Server).
+     */
+    startSession(outputSpecPath?: string, serial?: string, options?: RecordOptions): Promise<void>;
+    /**
+     * Stops an active recording session, terminates background processes,
+     * releases device lock, and returns the recorded steps and file paths.
+     */
+    stopSession(): Promise<{
+        steps: string[];
+        specPath: string;
+        reportPath: string;
+    }>;
     /**
      * Starts an interactive real-time recording session on the target Android device.
      * Automatically detects the active app, starts capturing gestures and key events,

package/dist/lib/reporter.d.ts

@@ -31,6 +31,8 @@ export interface AuditStep {
     durationMs?: number;
     /** Relative path to the failure triage bundle directory if step failed. */
     triageBundle?: string;
+    /** Relative execution offset in milliseconds from start of run / video recording. */
+    videoOffsetMs?: number;
     /** Additional diagnostic data or context about the step. */
     details?: Record<string, unknown>;
 }

package/dist/lib/triage.d.ts

@@ -0,0 +1,50 @@
+/**
+ * @module triage
+ * @description
+ * Auto-crash triage and privacy-safe GitHub bug report link generator for PromptTest.
+ * Provides passive, zero-telemetry 1-click issue reporting when unexpected
+ * internal framework crashes or unhandled exceptions occur.
+ */
+export interface TriageOptions {
+    errorMessage: string;
+    stack?: string;
+    command?: string;
+    exitCode?: number;
+    repoUrl?: string;
+}
+export interface TriageContext {
+    command?: string;
+    exitCode?: number;
+}
+/**
+ * Sanitizes stack traces and error messages by stripping personal user directories
+ * (e.g. C:\Users\username\... or /Users/username/...) to protect developer privacy.
+ *
+ * @param trace - The raw stack trace or log string.
+ * @returns Sanitized string with user home directories replaced by '~'.
+ */
+export declare function sanitizeStackTrace(trace?: string): string;
+/**
+ * Distinguishes whether an error is an expected test failure (e.g., assertion failed,
+ * element not found timeout) or an unexpected internal framework/runtime crash
+ * (TypeError, process panic, unhandled exception).
+ *
+ * @param error - The caught error or rejection reason.
+ * @returns true if the error represents an unexpected framework crash.
+ */
+export declare function isFrameworkCrash(error: unknown): boolean;
+/**
+ * Builds a sanitized, length-bounded pre-filled GitHub issue URL matching
+ * the 1_bug_report.yml template in prompttest-community.
+ *
+ * @param options - Error context and command details.
+ * @returns The fully-encoded GitHub issue URL.
+ */
+export declare function buildIssueUrl(options: TriageOptions): string;
+/**
+ * Renders a polite, non-intrusive diagnostic crash triage box in the console.
+ *
+ * @param error - The caught crash error.
+ * @param context - Additional execution context (e.g. command run, exit code).
+ */
+export declare function displayCrashTriage(error: unknown, context?: TriageContext): void;

package/dist/lib/wizard.d.ts

@@ -0,0 +1,42 @@
+/**
+ * @module wizard
+ * @description
+ * Interactive guided CLI wizard for PromptTest.
+ * Auto-detects connected devices, identifies foreground apps, discovers existing
+ * test specifications, and guides developers through autonomous exploration,
+ * test recording, spec execution, and diagnostics with zero required CLI arguments.
+ */
+import { AndroidDriver, AndroidDevice } from './adb.js';
+import { PromptRunner } from './prompt-runner.js';
+export interface EnvironmentInfo {
+    device?: AndroidDevice;
+    serial?: string;
+    activePackage?: string;
+    isOnline: boolean;
+}
+export interface WizardOptions {
+    input?: NodeJS.ReadableStream;
+    output?: NodeJS.WritableStream;
+    driver?: AndroidDriver;
+    runner?: PromptRunner;
+}
+/**
+ * Automatically inspects ADB to detect online devices and active foreground application.
+ *
+ * @param driver - AndroidDriver instance to query.
+ * @returns Detected environment state.
+ */
+export declare function detectActiveEnvironment(driver?: AndroidDriver): Promise<EnvironmentInfo>;
+/**
+ * Scans the current workspace for existing plain-English test specs (*.txt, *.spec).
+ *
+ * @param baseDir - Root directory to search (defaults to process.cwd()).
+ * @returns Array of discovered relative spec paths.
+ */
+export declare function findExistingSpecs(baseDir?: string): string[];
+/**
+ * Starts the interactive guided CLI wizard.
+ *
+ * @param options - Configuration options for input/output streams and drivers.
+ */
+export declare function startInteractiveWizard(options?: WizardOptions): Promise<void>;

package/dist/lib/zip-util.d.ts

@@ -0,0 +1,36 @@
+/**
+ * @module zip-util
+ * @description
+ * Lightweight, zero-dependency ZIP archive generator built using Node.js native zlib.
+ * Generates standard PKZIP archives containing files with deflation compression.
+ */
+export interface ZipEntry {
+    name: string;
+    data: Buffer;
+    date?: Date;
+}
+/**
+ * Calculates a standard CRC32 checksum for a buffer.
+ */
+export declare function crc32(buf: Buffer): number;
+/**
+ * Converts a JS Date into standard MS-DOS format (16-bit time, 16-bit date).
+ */
+export declare function dosDateTime(d?: Date): {
+    time: number;
+    date: number;
+};
+/**
+ * Packs an array of ZipEntry files into a standard PKZIP buffer using Deflate compression.
+ *
+ * @param entries - Array of file entries with names and data buffers.
+ * @returns A Buffer containing the valid ZIP archive.
+ */
+export declare function createZipArchive(entries: ZipEntry[]): Buffer;
+/**
+ * Saves a list of entries as a ZIP file to disk.
+ *
+ * @param filePath - Target file path on disk.
+ * @param entries - Array of zip entries.
+ */
+export declare function writeZipFile(filePath: string, entries: ZipEntry[]): Promise<void>;

package/package.json

@@ -1,8 +1,16 @@
 {
   "name": "prompttest",
-  "version": "1.3.4",
+  "version": "1.4.0",
   "description": "Ultra-fast, zero-code autonomous mobile testing & visual QA brain for Android",
-  "license": "SEE LICENSE IN LICENSE",
+  "license": "BUSL-1.1",
+  "homepage": "https://github.com/shriramsingh/promptTest#readme",
+  "bugs": {
+    "url": "https://github.com/shriramsingh/promptTest/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/shriramsingh/promptTest.git"
+  },
   "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -13,6 +21,7 @@
     "dist",
     "README.md",
     "LICENSE",
+    "TERMS.md",
     "CONTRIBUTING.md",
     "SECURITY.md",
     "LICENSES.md",
@@ -36,6 +45,7 @@
     "explore:dev": "tsx bin/prompttest.ts explore --safety-mode=moderate",
     "explore:yollow": "tsx bin/prompttest.ts explore --safety-mode=disabled",
     "run": "tsx bin/prompttest.ts run",
+    "serve": "tsx bin/server.ts",
     "watch": "tsx bin/prompttest.ts watch",
     "record": "tsx bin/prompttest.ts record",
     "init-ci": "tsx bin/prompttest.ts init-ci",
@@ -45,6 +55,8 @@
     "test:student": "tsx bin/prompttest.ts run specs/coachconnect_student.txt host.exp.exponent",
     "audit": "npm audit --audit-level=high",
     "build": "node scripts/build.mjs",
+    "package:sea": "node scripts/package-sea.mjs",
+    "pack:verify": "node scripts/verify-pack.mjs",
     "prepare": "node -e \"if (fs.existsSync('scripts/build.mjs')) import('./scripts/build.mjs')\"",
     "prepublishOnly": "npm run typecheck && npm run build",
     "pack:check": "npm pack --dry-run",