appium-uiwatchers-plugin 1.0.0 → 1.0.1

package/lib/utils.js

@@ -0,0 +1,33 @@
+/**
+ * Utility functions for UI Watchers Plugin
+ */
+/**
+ * W3C WebDriver Element Identifier key
+ * This is the standard key used in W3C WebDriver protocol to identify elements
+ */
+export const W3C_ELEMENT_KEY = 'element-6066-11e4-a52e-4f735466cecf';
+/**
+ * Extract element ID from element object
+ * Handles W3C format, JSONWP format, and direct string IDs
+ *
+ * @param element - Element object or string ID
+ * @returns The element ID string, or undefined if not found
+ */
+export function extractElementId(element) {
+    if (!element)
+        return undefined;
+    // Direct string ID
+    if (typeof element === 'string') {
+        return element;
+    }
+    // W3C format
+    if (element[W3C_ELEMENT_KEY]) {
+        return element[W3C_ELEMENT_KEY];
+    }
+    // JSONWP format
+    if (element.ELEMENT) {
+        return element.ELEMENT;
+    }
+    return undefined;
+}
+//# sourceMappingURL=utils.js.map

package/lib/utils.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"utils.js","sourceRoot":"","sources":["../src/utils.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH;;;GAGG;AACH,MAAM,CAAC,MAAM,eAAe,GAAG,qCAAqC,CAAC;AAUrE;;;;;;GAMG;AACH,MAAM,UAAU,gBAAgB,CAC9B,OAAkD;IAElD,IAAI,CAAC,OAAO;QAAE,OAAO,SAAS,CAAC;IAE/B,mBAAmB;IACnB,IAAI,OAAO,OAAO,KAAK,QAAQ,EAAE,CAAC;QAChC,OAAO,OAAO,CAAC;IACjB,CAAC;IAED,aAAa;IACb,IAAI,OAAO,CAAC,eAAe,CAAC,EAAE,CAAC;QAC7B,OAAO,OAAO,CAAC,eAAe,CAAC,CAAC;IAClC,CAAC;IAED,gBAAgB;IAChB,IAAI,OAAO,CAAC,OAAO,EAAE,CAAC;QACpB,OAAO,OAAO,CAAC,OAAO,CAAC;IACzB,CAAC;IAED,OAAO,SAAS,CAAC;AACnB,CAAC"}

package/lib/validators.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Validation functions for UI Watcher registration parameters
+ */
+/**
+ * Validates a locator object
+ * @param locator - The locator to validate
+ * @param fieldName - Name of the field for error messages
+ * @throws Error if locator is invalid
+ */
+export declare function validateLocator(locator: any, fieldName: string): void;
+/**
+ * Validates all watcher registration parameters
+ * @param params - Watcher registration parameters
+ * @param maxDurationMs - Maximum allowed duration in milliseconds
+ * @throws Error if any validation rule fails
+ */
+export declare function validateWatcherParams(params: any, maxDurationMs: number): void;
+//# sourceMappingURL=validators.d.ts.map

package/lib/validators.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"validators.d.ts","sourceRoot":"","sources":["../src/validators.ts"],"names":[],"mappings":"AAAA;;GAEG;AAiBH;;;;;GAKG;AACH,wBAAgB,eAAe,CAAC,OAAO,EAAE,GAAG,EAAE,SAAS,EAAE,MAAM,GAAG,IAAI,CA6BrE;AAED;;;;;GAKG;AACH,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,GAAG,EAAE,aAAa,EAAE,MAAM,GAAG,IAAI,CAoE9E"}

package/lib/validators.js

@@ -0,0 +1,112 @@
+/**
+ * Validation functions for UI Watcher registration parameters
+ */
+/**
+ * Valid Appium locator strategies
+ */
+const VALID_LOCATOR_STRATEGIES = [
+    'id',
+    'accessibility id',
+    'class name',
+    'xpath',
+    'name',
+    '-android uiautomator',
+    '-ios predicate string',
+    '-ios class chain',
+    'css selector',
+];
+/**
+ * Validates a locator object
+ * @param locator - The locator to validate
+ * @param fieldName - Name of the field for error messages
+ * @throws Error if locator is invalid
+ */
+export function validateLocator(locator, fieldName) {
+    // Check if locator exists
+    if (!locator || typeof locator !== 'object') {
+        throw new Error(`${fieldName} is required`);
+    }
+    // Check if 'using' field exists and is a string
+    if (!locator.using) {
+        throw new Error(`'using' is mandatory for ${fieldName}`);
+    }
+    if (typeof locator.using !== 'string') {
+        throw new Error(`'using' must be string for ${fieldName} `);
+    }
+    // Check if 'value' field exists and is a string
+    if (!locator.value) {
+        throw new Error(`'value' is mandatory for ${fieldName}`);
+    }
+    if (typeof locator.value !== 'string') {
+        throw new Error(`'value' must be string for ${fieldName} `);
+    }
+    // Validate locator strategy (case-insensitive)
+    const strategy = locator.using.toLowerCase();
+    if (!VALID_LOCATOR_STRATEGIES.includes(strategy)) {
+        throw new Error(`Invalid locator strategy for ${fieldName}`);
+    }
+}
+/**
+ * Validates all watcher registration parameters
+ * @param params - Watcher registration parameters
+ * @param maxDurationMs - Maximum allowed duration in milliseconds
+ * @throws Error if any validation rule fails
+ */
+export function validateWatcherParams(params, maxDurationMs) {
+    // Check if params exists
+    if (!params || typeof params !== 'object') {
+        throw new Error('Invalid watcher parameters');
+    }
+    // Validate required field: name
+    if (!params.name) {
+        throw new Error('UIWatcher name is required');
+    }
+    if (typeof params.name !== 'string') {
+        throw new Error('UIWatcher name must be string type');
+    }
+    if (params.name.trim() === '') {
+        throw new Error('UIWatcher name is empty');
+    }
+    // Validate required field: referenceLocator
+    if (!params.referenceLocator) {
+        throw new Error('UIWatcher referenceLocator is required');
+    }
+    validateLocator(params.referenceLocator, 'referenceLocator');
+    // Validate required field: actionLocator
+    if (!params.actionLocator) {
+        throw new Error('UIWatcher actionLocator is required');
+    }
+    validateLocator(params.actionLocator, 'actionLocator');
+    // Validate required field: duration
+    if (params.duration === undefined || params.duration === null) {
+        throw new Error('UIWatcher duration is required');
+    }
+    if (typeof params.duration !== 'number' || params.duration <= 0) {
+        throw new Error('UIWatcher duration must be a positive number');
+    }
+    if (params.duration > maxDurationMs) {
+        throw new Error(`UIWatcher duration must be ≤ ${maxDurationMs / 1000} seconds`);
+    }
+    // Validate optional field: priority (if provided)
+    if (params.priority !== undefined && params.priority !== null) {
+        if (typeof params.priority !== 'number') {
+            throw new Error('UIWatcher priority must be a number');
+        }
+    }
+    // Validate optional field: stopOnFound (if provided)
+    if (params.stopOnFound !== undefined && params.stopOnFound !== null) {
+        if (typeof params.stopOnFound !== 'boolean') {
+            throw new Error('UIWatcher stopOnFound must be a boolean');
+        }
+    }
+    // Validate optional field: cooldownMs (if provided)
+    if (params.cooldownMs !== undefined && params.cooldownMs !== null) {
+        if (typeof params.cooldownMs !== 'number') {
+            throw new Error('UIWatcher cooldownMs must be a number');
+        }
+        if (params.cooldownMs < 0) {
+            throw new Error('UIWatcher cooldownMs must be ≥ 0');
+        }
+    }
+}
+//# sourceMappingURL=validators.js.map

package/lib/validators.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"validators.js","sourceRoot":"","sources":["../src/validators.ts"],"names":[],"mappings":"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"}

package/lib/watcher-checker.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Core watcher checking algorithm
+ */
+import type { WatcherStore } from './watcher-store.js';
+/**
+ * Check all active watchers and execute actions for matching elements
+ * @param driver - Appium driver instance
+ * @param store - Watcher store instance
+ * @returns true if at least one watcher was successfully triggered, false otherwise
+ */
+export declare function checkWatchers(driver: any, store: WatcherStore): Promise<boolean>;
+//# sourceMappingURL=watcher-checker.d.ts.map

package/lib/watcher-checker.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"watcher-checker.d.ts","sourceRoot":"","sources":["../src/watcher-checker.ts"],"names":[],"mappings":"AAAA;;GAEG;AAKH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAIvD;;;;;GAKG;AACH,wBAAsB,aAAa,CAAC,MAAM,EAAE,GAAG,EAAE,KAAK,EAAE,YAAY,GAAG,OAAO,CAAC,OAAO,CAAC,CA+FtF"}

package/lib/watcher-checker.js

@@ -0,0 +1,88 @@
+/**
+ * Core watcher checking algorithm
+ */
+/* global setTimeout */
+import { logger } from '@appium/support';
+const log = logger.getLogger('AppiumUIWatchers');
+/**
+ * Check all active watchers and execute actions for matching elements
+ * @param driver - Appium driver instance
+ * @param store - Watcher store instance
+ * @returns true if at least one watcher was successfully triggered, false otherwise
+ */
+export async function checkWatchers(driver, store) {
+    // Track if any watcher was triggered
+    let watcherTriggered = false;
+    // Check if watchers are globally disabled
+    if (!store.isEnabled()) {
+        log.debug('[UIWatchers] Watcher checking is disabled, skipping');
+        return false;
+    }
+    // Get active, sorted watchers (by priority desc, then FIFO)
+    const watchers = store.getSortedWatchers();
+    // Early return if no active watchers
+    if (watchers.length === 0) {
+        log.debug('[UIWatchers] No active watchers to check');
+        return false;
+    }
+    log.debug(`[UIWatchers] Checking ${watchers.length} active watchers`);
+    // Check each watcher in priority order
+    for (const watcher of watchers) {
+        // Skip inactive watchers (marked inactive by stopOnFound)
+        if (watcher.status === 'inactive') {
+            log.debug(`[UIWatchers] Skipping inactive watcher '${watcher.name}'`);
+            continue;
+        }
+        log.debug(`[UIWatchers] Checking watcher '${watcher.name}' (priority=${watcher.priority})`);
+        try {
+            // Try to find the reference element
+            try {
+                await driver.findElement(watcher.referenceLocator.using, watcher.referenceLocator.value);
+            }
+            catch {
+                // Reference element not found - continue to next watcher
+                log.debug(`[UIWatchers] Watcher '${watcher.name}': Reference element not found`);
+                continue;
+            }
+            // Reference element found
+            log.debug(`[UIWatchers] Watcher '${watcher.name}': Reference element found`);
+            // Try to find and click the action element
+            try {
+                const actionElement = await driver.findElement(watcher.actionLocator.using, watcher.actionLocator.value);
+                // Click the action element
+                await driver.click(actionElement.ELEMENT || actionElement);
+                // Action click succeeded
+                log.info(`[UIWatchers] UIWatcher '${watcher.name}' triggered successfully`);
+                watcherTriggered = true;
+                // Update trigger statistics
+                store.incrementTriggerCount(watcher.name);
+                // Mark as inactive if stopOnFound is true
+                if (watcher.stopOnFound) {
+                    store.markInactive(watcher.name);
+                    log.debug(`[UIWatchers] Watcher '${watcher.name}' marked inactive (stopOnFound=true)`);
+                }
+                // Execute cooldown wait if configured
+                if (watcher.cooldownMs > 0) {
+                    log.debug(`[UIWatchers] Watcher '${watcher.name}': Executing cooldown wait (${watcher.cooldownMs}ms)`);
+                    await new Promise((resolve) => setTimeout(resolve, watcher.cooldownMs));
+                    log.debug(`[UIWatchers] Watcher '${watcher.name}': Cooldown complete`);
+                }
+            }
+            catch (clickError) {
+                // Action click failed
+                log.warn(`[UIWatchers] UIWatcher '${watcher.name}' action click failed: ${clickError.message}`);
+                // Continue to next watcher (don't execute cooldown or mark inactive)
+                continue;
+            }
+        }
+        catch (error) {
+            // Unexpected error during watcher checking
+            log.error(`[UIWatchers] Unexpected error checking watcher '${watcher.name}': ${error.message}`);
+            // Continue to next watcher
+            continue;
+        }
+    }
+    log.debug(`[UIWatchers] Watcher checking complete (triggered=${watcherTriggered})`);
+    return watcherTriggered;
+}
+//# sourceMappingURL=watcher-checker.js.map

package/lib/watcher-checker.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"watcher-checker.js","sourceRoot":"","sources":["../src/watcher-checker.ts"],"names":[],"mappings":"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"}

package/lib/watcher-store.d.ts

@@ -0,0 +1,91 @@
+/**
+ * WatcherStore - In-memory storage for registered UI watchers
+ */
+import type { WatcherState, UIWatcher } from './types.js';
+import type { PluginConfig } from './config.js';
+/**
+ * WatcherStore manages the lifecycle and state of all registered UI watchers
+ */
+export declare class WatcherStore {
+    /** Internal storage for watchers (keyed by watcher name) */
+    private watchers;
+    /** Global enable/disable flag for watcher checking */
+    private enabled;
+    /** Plugin configuration */
+    private config;
+    constructor(config: Required<PluginConfig>);
+    /**
+     * Get the plugin configuration
+     * @returns The plugin configuration
+     */
+    getConfig(): Required<PluginConfig>;
+    /**
+     * Add a new watcher to the store
+     * @param watcher - Watcher registration parameters
+     * @returns The created watcher state
+     * @throws Error if validation fails
+     */
+    add(watcher: UIWatcher): WatcherState;
+    /**
+     * Remove a watcher by name
+     * @param name - Name of the watcher to remove
+     * @returns True if watcher was removed, false if not found
+     */
+    remove(name: string): boolean;
+    /**
+     * Get a watcher by name
+     * @param name - Name of the watcher to retrieve
+     * @returns The watcher state, or undefined if not found
+     */
+    get(name: string): WatcherState | undefined;
+    /**
+     * Get all watchers (including expired ones)
+     * @returns Array of all watchers
+     */
+    list(): WatcherState[];
+    /**
+     * Get only active (non-expired) watchers
+     * Automatically removes expired watchers from storage
+     * @returns Array of active watchers
+     */
+    getActiveWatchers(): WatcherState[];
+    /**
+     * Get active watchers sorted by priority (descending) and registration time (FIFO)
+     * @returns Array of sorted active watchers
+     */
+    getSortedWatchers(): WatcherState[];
+    /**
+     * Clear all watchers from the store
+     * @returns Number of watchers removed
+     */
+    clear(): number;
+    /**
+     * Mark a watcher as inactive (used for stopOnFound)
+     * @param name - Name of the watcher to mark inactive
+     */
+    markInactive(name: string): void;
+    /**
+     * Increment the trigger count for a watcher
+     * @param name - Name of the watcher
+     */
+    incrementTriggerCount(name: string): void;
+    /**
+     * Update the last triggered timestamp for a watcher
+     * @param name - Name of the watcher
+     */
+    updateLastTriggered(name: string): void;
+    /**
+     * Disable watcher checking globally
+     */
+    disable(): void;
+    /**
+     * Enable watcher checking globally
+     */
+    enable(): void;
+    /**
+     * Check if watcher checking is enabled
+     * @returns True if enabled, false otherwise
+     */
+    isEnabled(): boolean;
+}
+//# sourceMappingURL=watcher-store.d.ts.map

package/lib/watcher-store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"watcher-store.d.ts","sourceRoot":"","sources":["../src/watcher-store.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAC1D,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAEhD;;GAEG;AACH,qBAAa,YAAY;IACvB,4DAA4D;IAC5D,OAAO,CAAC,QAAQ,CAA4B;IAE5C,sDAAsD;IACtD,OAAO,CAAC,OAAO,CAAU;IAEzB,2BAA2B;IAC3B,OAAO,CAAC,MAAM,CAAyB;gBAE3B,MAAM,EAAE,QAAQ,CAAC,YAAY,CAAC;IAM1C;;;OAGG;IACH,SAAS,IAAI,QAAQ,CAAC,YAAY,CAAC;IAInC;;;;;OAKG;IACH,GAAG,CAAC,OAAO,EAAE,SAAS,GAAG,YAAY;IAiCrC;;;;OAIG;IACH,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO;IAI7B;;;;OAIG;IACH,GAAG,CAAC,IAAI,EAAE,MAAM,GAAG,YAAY,GAAG,SAAS;IAI3C;;;OAGG;IACH,IAAI,IAAI,YAAY,EAAE;IAItB;;;;OAIG;IACH,iBAAiB,IAAI,YAAY,EAAE;IAsBnC;;;OAGG;IACH,iBAAiB,IAAI,YAAY,EAAE;IAcnC;;;OAGG;IACH,KAAK,IAAI,MAAM;IAMf;;;OAGG;IACH,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI;IAOhC;;;OAGG;IACH,qBAAqB,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI;IAQzC;;;OAGG;IACH,mBAAmB,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI;IAOvC;;OAEG;IACH,OAAO,IAAI,IAAI;IAIf;;OAEG;IACH,MAAM,IAAI,IAAI;IAId;;;OAGG;IACH,SAAS,IAAI,OAAO;CAGrB"}

package/lib/watcher-store.js

@@ -0,0 +1,177 @@
+/**
+ * WatcherStore - In-memory storage for registered UI watchers
+ */
+/**
+ * WatcherStore manages the lifecycle and state of all registered UI watchers
+ */
+export class WatcherStore {
+    constructor(config) {
+        this.watchers = new Map();
+        this.enabled = true;
+        this.config = config;
+    }
+    /**
+     * Get the plugin configuration
+     * @returns The plugin configuration
+     */
+    getConfig() {
+        return this.config;
+    }
+    /**
+     * Add a new watcher to the store
+     * @param watcher - Watcher registration parameters
+     * @returns The created watcher state
+     * @throws Error if validation fails
+     */
+    add(watcher) {
+        // Check for duplicate name
+        if (this.watchers.has(watcher.name)) {
+            throw new Error(`UIWatcher with name '${watcher.name}' already exists`);
+        }
+        // Check maximum watcher limit (count only non-expired watchers)
+        const activeCount = this.getActiveWatchers().length;
+        if (activeCount >= this.config.maxWatchers) {
+            throw new Error(`Maximum ${this.config.maxWatchers} UI watchers allowed per session`);
+        }
+        // Create watcher state with computed fields
+        const now = Date.now();
+        const watcherState = {
+            name: watcher.name,
+            priority: watcher.priority ?? 0,
+            referenceLocator: watcher.referenceLocator,
+            actionLocator: watcher.actionLocator,
+            duration: watcher.duration,
+            stopOnFound: watcher.stopOnFound ?? false,
+            cooldownMs: watcher.cooldownMs ?? 0,
+            registeredAt: now,
+            expiresAt: now + watcher.duration,
+            status: 'active',
+            triggerCount: 0,
+            lastTriggeredAt: null,
+        };
+        this.watchers.set(watcher.name, watcherState);
+        return watcherState;
+    }
+    /**
+     * Remove a watcher by name
+     * @param name - Name of the watcher to remove
+     * @returns True if watcher was removed, false if not found
+     */
+    remove(name) {
+        return this.watchers.delete(name);
+    }
+    /**
+     * Get a watcher by name
+     * @param name - Name of the watcher to retrieve
+     * @returns The watcher state, or undefined if not found
+     */
+    get(name) {
+        return this.watchers.get(name);
+    }
+    /**
+     * Get all watchers (including expired ones)
+     * @returns Array of all watchers
+     */
+    list() {
+        return Array.from(this.watchers.values());
+    }
+    /**
+     * Get only active (non-expired) watchers
+     * Automatically removes expired watchers from storage
+     * @returns Array of active watchers
+     */
+    getActiveWatchers() {
+        const now = Date.now();
+        const activeWatchers = [];
+        const expiredNames = [];
+        // Identify active and expired watchers
+        for (const [name, watcher] of this.watchers.entries()) {
+            if (now >= watcher.expiresAt) {
+                expiredNames.push(name);
+            }
+            else {
+                activeWatchers.push(watcher);
+            }
+        }
+        // Remove expired watchers
+        for (const name of expiredNames) {
+            this.watchers.delete(name);
+        }
+        return activeWatchers;
+    }
+    /**
+     * Get active watchers sorted by priority (descending) and registration time (FIFO)
+     * @returns Array of sorted active watchers
+     */
+    getSortedWatchers() {
+        const activeWatchers = this.getActiveWatchers();
+        return activeWatchers.sort((a, b) => {
+            // Sort by priority descending (higher priority first)
+            if (a.priority !== b.priority) {
+                return b.priority - a.priority;
+            }
+            // If priority is the same, sort by registration time ascending (FIFO)
+            return a.registeredAt - b.registeredAt;
+        });
+    }
+    /**
+     * Clear all watchers from the store
+     * @returns Number of watchers removed
+     */
+    clear() {
+        const count = this.watchers.size;
+        this.watchers.clear();
+        return count;
+    }
+    /**
+     * Mark a watcher as inactive (used for stopOnFound)
+     * @param name - Name of the watcher to mark inactive
+     */
+    markInactive(name) {
+        const watcher = this.watchers.get(name);
+        if (watcher) {
+            watcher.status = 'inactive';
+        }
+    }
+    /**
+     * Increment the trigger count for a watcher
+     * @param name - Name of the watcher
+     */
+    incrementTriggerCount(name) {
+        const watcher = this.watchers.get(name);
+        if (watcher) {
+            watcher.triggerCount++;
+            watcher.lastTriggeredAt = Date.now();
+        }
+    }
+    /**
+     * Update the last triggered timestamp for a watcher
+     * @param name - Name of the watcher
+     */
+    updateLastTriggered(name) {
+        const watcher = this.watchers.get(name);
+        if (watcher) {
+            watcher.lastTriggeredAt = Date.now();
+        }
+    }
+    /**
+     * Disable watcher checking globally
+     */
+    disable() {
+        this.enabled = false;
+    }
+    /**
+     * Enable watcher checking globally
+     */
+    enable() {
+        this.enabled = true;
+    }
+    /**
+     * Check if watcher checking is enabled
+     * @returns True if enabled, false otherwise
+     */
+    isEnabled() {
+        return this.enabled;
+    }
+}
+//# sourceMappingURL=watcher-store.js.map

package/lib/watcher-store.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"watcher-store.js","sourceRoot":"","sources":["../src/watcher-store.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,9 +1,12 @@
 {
   "name": "appium-uiwatchers-plugin",
-  "version": "1.0.0",
+  "version": "1.0.1",
   "type": "module",
   "main": "./lib/plugin.js",
   "types": "./lib/plugin.d.ts",
+  "files": [
+    "lib"
+  ],
   "scripts": {
     "build": "tsc",
     "watch": "tsc --watch",

package/.c8rc.json

@@ -1,12 +0,0 @@
-{
-  "all": true,
-  "include": ["lib/**/*.js"],
-  "exclude": ["test/**", "**/*.spec.js", "**/*.test.js", "**/*.e2e.spec.cjs", "lib/types.js"],
-  "reporter": ["text", "html", "lcov"],
-  "report-dir": "./coverage",
-  "check-coverage": true,
-  "lines": 80,
-  "statements": 80,
-  "functions": 80,
-  "branches": 80
-}

package/.github/workflows/npm-publish.yml

@@ -1,28 +0,0 @@
-name: Publish to NPM
-
-on:
-  release:
-    types: [published]
-
-jobs:
-  publish:
-    runs-on: ubuntu-latest
-    permissions:
-      contents: read
-      id-token: write
-    steps:
-      - uses: actions/checkout@v4
-
-      - uses: actions/setup-node@v4
-        with:
-          node-version: '20.x'
-          registry-url: 'https://registry.npmjs.org'
-
-      - name: Install latest npm
-        run: npm install -g npm@latest
-
-      - name: Install dependencies
-        run: npm ci
-
-      - name: Publish to npm
-        run: npm publish --provenance --access public

package/.husky/pre-commit

@@ -1,4 +0,0 @@
-#!/usr/bin/env sh
-. "$(dirname -- "$0")/_/husky.sh"
-
-npx lint-staged

package/.lintstagedrc.json

@@ -1,4 +0,0 @@
-{
-  "*.{ts,js}": ["eslint --fix", "prettier --write"],
-  "*.{json,md}": ["prettier --write"]
-}

package/.mocharc.json

@@ -1,10 +0,0 @@
-{
-  "require": ["@appium/support/build/lib/env"],
-  "timeout": 20000,
-  "slow": 10000,
-  "reporter": "spec",
-  "color": true,
-  "recursive": true,
-  "exit": true,
-  "spec": ["test/unit/**/*.spec.js", "test/integration/**/*.spec.js", "test/e2e/**/*.e2e.spec.cjs"]
-}

package/.prettierignore

@@ -1,6 +0,0 @@
-node_modules
-lib
-coverage
-*.log
-.nyc_output
-package-lock.json