appium-mcp 1.72.16 → 1.74.0

package/CHANGELOG.md

@@ -1,3 +1,15 @@
+## [1.74.0](https://github.com/appium/appium-mcp/compare/v1.73.0...v1.74.0) (2026-05-16)
+
+### Features
+
+* **embeddings:** cache vector embeddings and ship warm cache ([#335](https://github.com/appium/appium-mcp/issues/335)) ([52c8fd3](https://github.com/appium/appium-mcp/commit/52c8fd326a7e67f2769a10e00c9c5516bd86e0bf))
+
+## [1.73.0](https://github.com/appium/appium-mcp/compare/v1.72.16...v1.73.0) (2026-05-14)
+
+### Features
+
+* **rag:** upgrade to BGE-small-v1.5 + add retrieval eval harness ([#334](https://github.com/appium/appium-mcp/issues/334)) ([bcfe254](https://github.com/appium/appium-mcp/commit/bcfe2542e2f270d0a2fe314c64e7c54e752933ff))
+
 ## [1.72.16](https://github.com/appium/appium-mcp/compare/v1.72.15...v1.72.16) (2026-05-14)
 
 ### Bug Fixes

package/dist/scripts/eval-documentation-rag.d.ts

@@ -0,0 +1,23 @@
+/**
+ * RAG retrieval eval harness for the Appium documentation tool.
+ *
+ * Usage (after `npm run build`):
+ *   node dist/scripts/eval-documentation-rag.js [--quiet] [--save] [--top-chunks=N]
+ *
+ * What it does:
+ *   1. Loads the eval dataset (src/scripts/rag-eval-dataset.json).
+ *   2. For each query, calls the existing queryVectorStore() with `topChunks`
+ *      chunks (default 30), dedupes by source (preserving rank), and matches
+ *      the resulting source list against expectedSources.
+ *   3. Reports Recall@{1,3,5,10} and MRR, broken down by difficulty.
+ *   4. Persists results to src/scripts/eval-results/<ISO>.json plus a
+ *      `latest.json` so successive runs can be diffed.
+ *
+ * Notes:
+ *   - The first run after a server restart pays the embedding cold start
+ *     (~30-60s for the current corpus).
+ *   - Match strategy: a retrieved source matches an expected source if its
+ *     `relativePath` ends with the expected path (case-sensitive).
+ */
+export {};
+//# sourceMappingURL=eval-documentation-rag.d.ts.map

package/dist/scripts/eval-documentation-rag.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"eval-documentation-rag.d.ts","sourceRoot":"","sources":["../../src/scripts/eval-documentation-rag.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG"}

package/dist/scripts/eval-documentation-rag.js

@@ -0,0 +1,212 @@
+/**
+ * RAG retrieval eval harness for the Appium documentation tool.
+ *
+ * Usage (after `npm run build`):
+ *   node dist/scripts/eval-documentation-rag.js [--quiet] [--save] [--top-chunks=N]
+ *
+ * What it does:
+ *   1. Loads the eval dataset (src/scripts/rag-eval-dataset.json).
+ *   2. For each query, calls the existing queryVectorStore() with `topChunks`
+ *      chunks (default 30), dedupes by source (preserving rank), and matches
+ *      the resulting source list against expectedSources.
+ *   3. Reports Recall@{1,3,5,10} and MRR, broken down by difficulty.
+ *   4. Persists results to src/scripts/eval-results/<ISO>.json plus a
+ *      `latest.json` so successive runs can be diffed.
+ *
+ * Notes:
+ *   - The first run after a server restart pays the embedding cold start
+ *     (~30-60s for the current corpus).
+ *   - Match strategy: a retrieved source matches an expected source if its
+ *     `relativePath` ends with the expected path (case-sensitive).
+ */
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { queryVectorStore } from '../tools/documentation/simple-pdf-indexer.js';
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+const args = new Set(process.argv.slice(2));
+const QUIET = args.has('--quiet');
+const NO_SAVE = !args.has('--save');
+const topChunksArg = process.argv.find((a) => a.startsWith('--top-chunks='));
+const TOP_CHUNKS = topChunksArg ? Number(topChunksArg.split('=')[1]) : 30;
+function resolveDatasetPath() {
+    // When compiled, this file lives in dist/scripts/. We look for the dataset
+    // beside it first (copy-docs build step), then fall back to src/scripts/.
+    const candidates = [
+        path.resolve(__dirname, 'rag-eval-dataset.json'),
+        path.resolve(__dirname, '../../src/scripts/rag-eval-dataset.json'),
+    ];
+    for (const p of candidates) {
+        if (fs.existsSync(p)) {
+            return p;
+        }
+    }
+    throw new Error(`Could not find rag-eval-dataset.json in any of: ${candidates.join(', ')}`);
+}
+function resolveResultsDir() {
+    // Always write results into the source tree so they're easy to diff/commit.
+    const candidates = [
+        path.resolve(__dirname, '../../src/scripts/eval-results'),
+        path.resolve(__dirname, 'eval-results'),
+    ];
+    const dir = candidates[0];
+    fs.mkdirSync(dir, { recursive: true });
+    return dir;
+}
+function matches(retrievedRelPath, expected) {
+    return retrievedRelPath === expected || retrievedRelPath.endsWith(expected);
+}
+function dedupeBySource(chunks) {
+    const seen = new Set();
+    const ordered = [];
+    for (const c of chunks) {
+        const src = c.relativePath;
+        if (!src || seen.has(src)) {
+            continue;
+        }
+        seen.add(src);
+        ordered.push(src);
+    }
+    return ordered;
+}
+function evalQuery(retrievedSources, expectedSources) {
+    for (let i = 0; i < retrievedSources.length; i++) {
+        const hit = expectedSources.find((e) => matches(retrievedSources[i], e));
+        if (hit) {
+            return { matchedAtRank: i + 1, matchedSource: retrievedSources[i] };
+        }
+    }
+    return { matchedAtRank: null, matchedSource: null };
+}
+function aggregate(results) {
+    if (results.length === 0) {
+        return {
+            count: 0,
+            recallAt1: 0,
+            recallAt3: 0,
+            recallAt5: 0,
+            recallAt10: 0,
+            mrr: 0,
+        };
+    }
+    const n = results.length;
+    const sum = (k) => results.reduce((acc, r) => acc + r[k], 0);
+    return {
+        count: n,
+        recallAt1: sum('recallAt1') / n,
+        recallAt3: sum('recallAt3') / n,
+        recallAt5: sum('recallAt5') / n,
+        recallAt10: sum('recallAt10') / n,
+        mrr: sum('reciprocalRank') / n,
+    };
+}
+function fmt(n) {
+    return n.toFixed(3);
+}
+function rankStr(rank) {
+    return rank === null ? ' - ' : String(rank).padStart(3, ' ');
+}
+function printPerQueryTable(results) {
+    const rows = results.map((r) => ({
+        id: r.id,
+        diff: r.difficulty,
+        rank: rankStr(r.matchedAtRank),
+        query: r.query.length > 56 ? r.query.slice(0, 53) + '...' : r.query,
+        matched: r.matchedSource ?? '(none of expected found in top results)',
+    }));
+    const widths = {
+        id: 4,
+        diff: 7,
+        rank: 4,
+        query: Math.max(...rows.map((r) => r.query.length), 5),
+        matched: Math.max(...rows.map((r) => r.matched.length), 7),
+    };
+    const header = `${'id'.padEnd(widths.id)} | ${'diff'.padEnd(widths.diff)} | ${'rank'.padStart(widths.rank)} | ${'query'.padEnd(widths.query)} | matched`;
+    const sep = '-'.repeat(header.length + 10);
+    console.log(sep);
+    console.log(header);
+    console.log(sep);
+    for (const r of rows) {
+        console.log(`${r.id.padEnd(widths.id)} | ${r.diff.padEnd(widths.diff)} | ${r.rank.padStart(widths.rank)} | ${r.query.padEnd(widths.query)} | ${r.matched}`);
+    }
+    console.log(sep);
+}
+function printAggregate(label, m) {
+    const tag = `${label} (n=${m.count})`.padEnd(20);
+    console.log(`${tag}  R@1=${fmt(m.recallAt1)}  R@3=${fmt(m.recallAt3)}  R@5=${fmt(m.recallAt5)}  R@10=${fmt(m.recallAt10)}  MRR=${fmt(m.mrr)}`);
+}
+async function runEval() {
+    const datasetPath = resolveDatasetPath();
+    const dataset = JSON.parse(fs.readFileSync(datasetPath, 'utf-8'));
+    if (!QUIET) {
+        console.log(`\n=== Appium RAG eval ===`);
+        console.log(`Dataset: ${datasetPath}`);
+        console.log(`Queries: ${dataset.queries.length}   |   topChunks: ${TOP_CHUNKS}   |   match: endsWith\n`);
+    }
+    const perQuery = [];
+    for (const q of dataset.queries) {
+        const docs = await queryVectorStore(q.query, TOP_CHUNKS);
+        const retrievedSources = dedupeBySource(docs.map((d) => ({
+            relativePath: d.metadata?.relativePath ??
+                d.metadata?.filename ??
+                d.metadata?.source,
+        })));
+        const { matchedAtRank, matchedSource } = evalQuery(retrievedSources, q.expectedSources);
+        perQuery.push({
+            id: q.id,
+            query: q.query,
+            difficulty: q.difficulty,
+            category: q.category,
+            expectedSources: q.expectedSources,
+            retrievedSources,
+            matchedAtRank,
+            matchedSource,
+            recallAt1: matchedAtRank !== null && matchedAtRank <= 1 ? 1 : 0,
+            recallAt3: matchedAtRank !== null && matchedAtRank <= 3 ? 1 : 0,
+            recallAt5: matchedAtRank !== null && matchedAtRank <= 5 ? 1 : 0,
+            recallAt10: matchedAtRank !== null && matchedAtRank <= 10 ? 1 : 0,
+            reciprocalRank: matchedAtRank !== null ? 1 / matchedAtRank : 0,
+        });
+    }
+    if (!QUIET) {
+        printPerQueryTable(perQuery);
+    }
+    const overall = aggregate(perQuery);
+    const byDifficulty = {};
+    for (const d of ['easy', 'medium', 'vague']) {
+        byDifficulty[d] = aggregate(perQuery.filter((r) => r.difficulty === d));
+    }
+    console.log('');
+    printAggregate('overall', overall);
+    for (const d of ['easy', 'medium', 'vague']) {
+        printAggregate(d, byDifficulty[d]);
+    }
+    console.log('');
+    if (!NO_SAVE) {
+        const run = {
+            timestamp: new Date().toISOString(),
+            datasetVersion: dataset.version,
+            topChunks: TOP_CHUNKS,
+            overall,
+            byDifficulty,
+            perQuery,
+        };
+        const dir = resolveResultsDir();
+        const stamp = run.timestamp.replace(/[:.]/g, '-');
+        const outPath = path.join(dir, `${stamp}.json`);
+        const latestPath = path.join(dir, 'latest.json');
+        fs.writeFileSync(outPath, JSON.stringify(run, null, 2));
+        fs.writeFileSync(latestPath, JSON.stringify(run, null, 2));
+        console.log(`Saved: ${path.relative(process.cwd(), outPath)}`);
+        console.log(`       ${path.relative(process.cwd(), latestPath)}\n`);
+    }
+}
+try {
+    await runEval();
+}
+catch (err) {
+    console.error('Eval failed:', err);
+    process.exit(1);
+}
+//# sourceMappingURL=eval-documentation-rag.js.map

package/dist/scripts/eval-documentation-rag.js.map

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

package/dist/scripts/generate-embeddings-cache.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Generate the embeddings cache for the currently configured model.
+ *
+ * Idempotent: if a valid cache already exists for the current model and the
+ * fingerprint matches documents.json, this exits quickly. Otherwise it
+ * embeds all chunks and writes the cache.
+ *
+ * Intended for the maintainer release flow:
+ *   npm run build && npm run generate-cache
+ * to ensure the published tarball ships a warm cache for the default model.
+ */
+export {};
+//# sourceMappingURL=generate-embeddings-cache.d.ts.map

package/dist/scripts/generate-embeddings-cache.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"generate-embeddings-cache.d.ts","sourceRoot":"","sources":["../../src/scripts/generate-embeddings-cache.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG"}

package/dist/scripts/generate-embeddings-cache.js

@@ -0,0 +1,24 @@
+/**
+ * Generate the embeddings cache for the currently configured model.
+ *
+ * Idempotent: if a valid cache already exists for the current model and the
+ * fingerprint matches documents.json, this exits quickly. Otherwise it
+ * embeds all chunks and writes the cache.
+ *
+ * Intended for the maintainer release flow:
+ *   npm run build && npm run generate-cache
+ * to ensure the published tarball ships a warm cache for the default model.
+ */
+import { queryVectorStore } from '../tools/documentation/simple-pdf-indexer.js';
+const start = Date.now();
+try {
+    // A single query forces the cold-start path inside queryVectorStore, which
+    // checks the cache and embeds+saves on miss. We don't care about results.
+    await queryVectorStore('warmup', 1);
+    console.log(`Embeddings cache ready (${Date.now() - start}ms)`);
+}
+catch (err) {
+    console.error('Failed to generate embeddings cache:', err);
+    process.exit(1);
+}
+//# sourceMappingURL=generate-embeddings-cache.js.map

package/dist/scripts/generate-embeddings-cache.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"generate-embeddings-cache.js","sourceRoot":"","sources":["../../src/scripts/generate-embeddings-cache.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,EAAE,gBAAgB,EAAE,MAAM,8CAA8C,CAAC;AAEhF,MAAM,KAAK,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;AACzB,IAAI,CAAC;IACH,2EAA2E;IAC3E,0EAA0E;IAC1E,MAAM,gBAAgB,CAAC,QAAQ,EAAE,CAAC,CAAC,CAAC;IACpC,OAAO,CAAC,GAAG,CAAC,2BAA2B,IAAI,CAAC,GAAG,EAAE,GAAG,KAAK,KAAK,CAAC,CAAC;AAClE,CAAC;AAAC,OAAO,GAAG,EAAE,CAAC;IACb,OAAO,CAAC,KAAK,CAAC,sCAAsC,EAAE,GAAG,CAAC,CAAC;IAC3D,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;AAClB,CAAC"}

package/dist/scripts/rag-eval-dataset.json

@@ -0,0 +1,218 @@
+{
+  "version": 1,
+  "description": "Realistic user queries for the Appium documentation RAG tool. Each query maps to one or more source files that should appear in the retrieved sources (substring match against the chunk's relativePath metadata). Difficulty buckets: easy (specific terms that should be near-trivial to retrieve), medium (real-world phrasing), vague (natural human phrasing with less direct cues).",
+  "matchMode": "endsWith",
+  "queries": [
+    {
+      "id": "q01",
+      "query": "How do I install Appium?",
+      "expectedSources": ["appium/quickstart/install.md"],
+      "difficulty": "easy",
+      "category": "setup"
+    },
+    {
+      "id": "q02",
+      "query": "What capabilities does the XCUITest driver support?",
+      "expectedSources": ["appium-xcuitest-driver/reference/capabilities.md"],
+      "difficulty": "easy",
+      "category": "capabilities"
+    },
+    {
+      "id": "q03",
+      "query": "how to run iOS tests in parallel",
+      "expectedSources": ["appium-xcuitest-driver/guides/parallel-tests.md"],
+      "difficulty": "easy",
+      "category": "ios"
+    },
+    {
+      "id": "q04",
+      "query": "push and pull files from an iOS device",
+      "expectedSources": ["appium-xcuitest-driver/guides/file-transfer.md"],
+      "difficulty": "easy",
+      "category": "ios"
+    },
+    {
+      "id": "q05",
+      "query": "read and write the clipboard on iOS",
+      "expectedSources": ["appium-xcuitest-driver/guides/clipboard.md"],
+      "difficulty": "easy",
+      "category": "ios"
+    },
+    {
+      "id": "q06",
+      "query": "what locator strategies are supported by XCUITest",
+      "expectedSources": [
+        "appium-xcuitest-driver/reference/locator-strategies.md"
+      ],
+      "difficulty": "easy",
+      "category": "locators"
+    },
+    {
+      "id": "q07",
+      "query": "how do I use iOS predicate strings to find elements",
+      "expectedSources": ["appium-xcuitest-driver/reference/ios-predicate.md"],
+      "difficulty": "easy",
+      "category": "locators"
+    },
+    {
+      "id": "q08",
+      "query": "uiautomator2 driver capabilities",
+      "expectedSources": ["appium-uiautomator2-driver/capability-sets.md"],
+      "difficulty": "easy",
+      "category": "android"
+    },
+    {
+      "id": "q09",
+      "query": "Appium server command line arguments",
+      "expectedSources": ["appium/cli/args.md"],
+      "difficulty": "easy",
+      "category": "cli"
+    },
+    {
+      "id": "q10",
+      "query": "install a root certificate on an iOS device",
+      "expectedSources": [
+        "appium-xcuitest-driver/guides/install-certificate.md"
+      ],
+      "difficulty": "easy",
+      "category": "ios"
+    },
+
+    {
+      "id": "q11",
+      "query": "I'm new to Appium, where should I start?",
+      "expectedSources": [
+        "appium/quickstart/index.md",
+        "appium/intro/index.md",
+        "appium/quickstart/requirements.md"
+      ],
+      "difficulty": "medium",
+      "category": "intro"
+    },
+    {
+      "id": "q12",
+      "query": "which driver should I use to automate android",
+      "expectedSources": [
+        "appium/quickstart/uiauto2-driver.md",
+        "appium/intro/drivers.md",
+        "appium/ecosystem/drivers.md"
+      ],
+      "difficulty": "medium",
+      "category": "android"
+    },
+    {
+      "id": "q13",
+      "query": "how do I switch to a webview in an iOS hybrid app",
+      "expectedSources": [
+        "appium-xcuitest-driver/guides/hybrid.md",
+        "appium/guides/context.md"
+      ],
+      "difficulty": "medium",
+      "category": "hybrid"
+    },
+    {
+      "id": "q14",
+      "query": "how to set up code signing for real iPhone testing",
+      "expectedSources": [
+        "appium-xcuitest-driver/preparation/real-device-config.md",
+        "appium-xcuitest-driver/preparation/prov-profile-basic-auto.md",
+        "appium-xcuitest-driver/preparation/prov-profile-basic-manual.md"
+      ],
+      "difficulty": "medium",
+      "category": "ios-real-device"
+    },
+    {
+      "id": "q15",
+      "query": "swipe gesture on android",
+      "expectedSources": [
+        "appium-uiautomator2-driver/android-mobile-gestures.md"
+      ],
+      "difficulty": "medium",
+      "category": "gestures"
+    },
+    {
+      "id": "q16",
+      "query": "running tests against an .aab Android App Bundle",
+      "expectedSources": ["appium-uiautomator2-driver/android-appbundle.md"],
+      "difficulty": "medium",
+      "category": "android"
+    },
+    {
+      "id": "q17",
+      "query": "differences between Appium 1 and Appium 2",
+      "expectedSources": ["appium/guides/migrating-1-to-2.md"],
+      "difficulty": "medium",
+      "category": "migration"
+    },
+    {
+      "id": "q18",
+      "query": "enable Touch ID in an iOS simulator test",
+      "expectedSources": ["appium-xcuitest-driver/guides/touch-id.md"],
+      "difficulty": "medium",
+      "category": "ios"
+    },
+    {
+      "id": "q19",
+      "query": "use a custom WebDriverAgent server",
+      "expectedSources": [
+        "appium-xcuitest-driver/guides/wda-custom-server.md",
+        "appium-xcuitest-driver/guides/run-prebuilt-wda.md"
+      ],
+      "difficulty": "medium",
+      "category": "wda"
+    },
+    {
+      "id": "q20",
+      "query": "setting up Appium on a CI server",
+      "expectedSources": ["appium-xcuitest-driver/guides/ci-setup.md"],
+      "difficulty": "medium",
+      "category": "ci"
+    },
+
+    {
+      "id": "q21",
+      "query": "my tests are super slow on iOS, what's going on",
+      "expectedSources": [
+        "appium-xcuitest-driver/guides/wda-slowness.md",
+        "appium-xcuitest-driver/guides/troubleshooting.md"
+      ],
+      "difficulty": "vague",
+      "category": "troubleshooting"
+    },
+    {
+      "id": "q22",
+      "query": "appium can't find my button",
+      "expectedSources": [
+        "appium-xcuitest-driver/guides/elements-lookup-troubleshooting.md",
+        "appium-xcuitest-driver/reference/locator-strategies.md"
+      ],
+      "difficulty": "vague",
+      "category": "troubleshooting"
+    },
+    {
+      "id": "q23",
+      "query": "I switched xcode versions and now nothing works",
+      "expectedSources": [
+        "appium-xcuitest-driver/guides/multiple-xcode-versions.md"
+      ],
+      "difficulty": "vague",
+      "category": "troubleshooting"
+    },
+    {
+      "id": "q24",
+      "query": "can I reuse a WebDriverAgent that's already running",
+      "expectedSources": [
+        "appium-xcuitest-driver/guides/attach-to-running-wda.md"
+      ],
+      "difficulty": "vague",
+      "category": "wda"
+    },
+    {
+      "id": "q25",
+      "query": "show me how to write a test in python",
+      "expectedSources": ["appium/quickstart/test-py.md"],
+      "difficulty": "vague",
+      "category": "clients"
+    }
+  ]
+}

package/dist/tests/__mocks__/@appium/support.d.ts

@@ -38,6 +38,24 @@ export declare const zip: {
     readEntries: (_zipPath: string, _handler: unknown) => Promise<void>;
     toArchive: (_dstPath: string, _src?: unknown, _opts?: unknown) => Promise<void>;
 };
+/**
+ * Minimal `fs` mock that delegates to node:fs/promises so test code touching
+ * the real filesystem continues to work.
+ */
+export declare const fs: {
+    exists: (p: string) => Promise<boolean>;
+    readdir: (p: string) => Promise<string[]>;
+    stat: (p: string) => Promise<import("node:fs").Stats>;
+    readFile: (p: string, encoding?: BufferEncoding) => Promise<string | NonSharedBuffer>;
+    writeFile: (p: string, data: string | Buffer) => Promise<void>;
+    unlink: (p: string) => Promise<void>;
+    rename: (from: string, to: string) => Promise<void>;
+    mkdir: (p: string, opts?: {
+        recursive?: boolean;
+    }) => Promise<string | undefined>;
+    mkdirp: (p: string) => Promise<string | undefined>;
+    mv: (from: string, to: string) => Promise<void>;
+};
 declare const _default: {
     logger: {
         getLogger: (_name: string) => {
@@ -62,6 +80,20 @@ declare const _default: {
         readEntries: (_zipPath: string, _handler: unknown) => Promise<void>;
         toArchive: (_dstPath: string, _src?: unknown, _opts?: unknown) => Promise<void>;
     };
+    fs: {
+        exists: (p: string) => Promise<boolean>;
+        readdir: (p: string) => Promise<string[]>;
+        stat: (p: string) => Promise<import("node:fs").Stats>;
+        readFile: (p: string, encoding?: BufferEncoding) => Promise<string | NonSharedBuffer>;
+        writeFile: (p: string, data: string | Buffer) => Promise<void>;
+        unlink: (p: string) => Promise<void>;
+        rename: (from: string, to: string) => Promise<void>;
+        mkdir: (p: string, opts?: {
+            recursive?: boolean;
+        }) => Promise<string | undefined>;
+        mkdirp: (p: string) => Promise<string | undefined>;
+        mv: (from: string, to: string) => Promise<void>;
+    };
 };
 export default _default;
 //# sourceMappingURL=support.d.ts.map

package/dist/tests/__mocks__/@appium/support.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"support.d.ts","sourceRoot":"","sources":["../../../../src/tests/__mocks__/@appium/support.ts"],"names":[],"mappings":"AAGA,eAAO,MAAM,MAAM;uBACE,MAAM;0BAIH,MAAM,YAAY,GAAG,EAAE;yBAGxB,MAAM,YAAY,GAAG,EAAE;yBAGvB,MAAM,YAAY,GAAG,EAAE;0BAGtB,MAAM,YAAY,GAAG,EAAE;0BAGvB,MAAM,YAAY,GAAG,EAAE;;CAI9C,CAAC;AAEF;;;;;;GAMG;AAEH,MAAM,MAAM,iBAAiB,GAAG;IAC9B,WAAW,EAAE,KAAK,CAAC,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;IACrC,YAAY,EAAE,MAAM,OAAO,CAAC,MAAM,CAAC,CAAC;IACpC,MAAM,EAAE,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,KAAK,iBAAiB,CAAC;IACpD,IAAI,EAAE,CAAC,KAAK,CAAC,EAAE,OAAO,KAAK,iBAAiB,CAAC;IAC7C,QAAQ,EAAE,MAAM,OAAO,CAAC,MAAM,CAAC,CAAC;IAChC,KAAK,EAAE,MAAM,IAAI,CAAC;CACnB,CAAC;AAEF,6EAA6E;AAC7E,eAAO,MAAM,iBAAiB,EAAE,iBAkB/B,CAAC;AAEF,eAAO,MAAM,SAAS;yBACC,QAAQ,MAAM;CACpC,CAAC;AAEF,eAAO,MAAM,GAAG;+BAEA,MAAM,YACR,MAAM,UACR,OAAO;CAIlB,CAAC;AAEF,eAAO,MAAM,KAAK;iCACmB,MAAM;CAC1C,CAAC;AAEF,eAAO,MAAM,GAAG;6BACiB,MAAM,YAAY,MAAM,UAAU,OAAO;4BAG1C,MAAM,YAAY,OAAO;0BAG3B,MAAM,SAAS,OAAO,UAAU,OAAO;CAGpE,CAAC;;;2BAxFmB,MAAM;8BAIH,MAAM,YAAY,GAAG,EAAE;6BAGxB,MAAM,YAAY,GAAG,EAAE;6BAGvB,MAAM,YAAY,GAAG,EAAE;8BAGtB,MAAM,YAAY,GAAG,EAAE;8BAGvB,MAAM,YAAY,GAAG,EAAE;;;;6BA6CxB,QAAQ,MAAM;;;mCAKrB,MAAM,YACR,MAAM,UACR,OAAO;;;qCAOkB,MAAM;;;iCAIV,MAAM,YAAY,MAAM,UAAU,OAAO;gCAG1C,MAAM,YAAY,OAAO;8BAG3B,MAAM,SAAS,OAAO,UAAU,OAAO;;;AAMrE,wBAME"}
+{"version":3,"file":"support.d.ts","sourceRoot":"","sources":["../../../../src/tests/__mocks__/@appium/support.ts"],"names":[],"mappings":"AAKA,eAAO,MAAM,MAAM;uBACE,MAAM;0BAIH,MAAM,YAAY,GAAG,EAAE;yBAGxB,MAAM,YAAY,GAAG,EAAE;yBAGvB,MAAM,YAAY,GAAG,EAAE;0BAGtB,MAAM,YAAY,GAAG,EAAE;0BAGvB,MAAM,YAAY,GAAG,EAAE;;CAI9C,CAAC;AAEF;;;;;;GAMG;AAEH,MAAM,MAAM,iBAAiB,GAAG;IAC9B,WAAW,EAAE,KAAK,CAAC,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;IACrC,YAAY,EAAE,MAAM,OAAO,CAAC,MAAM,CAAC,CAAC;IACpC,MAAM,EAAE,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,KAAK,iBAAiB,CAAC;IACpD,IAAI,EAAE,CAAC,KAAK,CAAC,EAAE,OAAO,KAAK,iBAAiB,CAAC;IAC7C,QAAQ,EAAE,MAAM,OAAO,CAAC,MAAM,CAAC,CAAC;IAChC,KAAK,EAAE,MAAM,IAAI,CAAC;CACnB,CAAC;AAEF,6EAA6E;AAC7E,eAAO,MAAM,iBAAiB,EAAE,iBAkB/B,CAAC;AAEF,eAAO,MAAM,SAAS;yBACC,QAAQ,MAAM;CACpC,CAAC;AAEF,eAAO,MAAM,GAAG;+BAEA,MAAM,YACR,MAAM,UACR,OAAO;CAIlB,CAAC;AAEF,eAAO,MAAM,KAAK;iCACmB,MAAM;CAC1C,CAAC;AAEF,eAAO,MAAM,GAAG;6BACiB,MAAM,YAAY,MAAM,UAAU,OAAO;4BAG1C,MAAM,YAAY,OAAO;0BAG3B,MAAM,SAAS,OAAO,UAAU,OAAO;CAGpE,CAAC;AAEF;;;GAGG;AACH,eAAO,MAAM,EAAE;gBACK,MAAM;iBACX,MAAM;cACT,MAAM;kBACF,MAAM,aAAa,cAAc;mBAEhC,MAAM,QAAQ,MAAM,GAAG,MAAM;gBAEhC,MAAM;mBACH,MAAM,MAAM,MAAM;eACtB,MAAM,SAAS;QAAE,SAAS,CAAC,EAAE,OAAO,CAAA;KAAE;gBAErC,MAAM;eACD,MAAM,MAAM,MAAM;CAGpC,CAAC;;;2BA9GmB,MAAM;8BAIH,MAAM,YAAY,GAAG,EAAE;6BAGxB,MAAM,YAAY,GAAG,EAAE;6BAGvB,MAAM,YAAY,GAAG,EAAE;8BAGtB,MAAM,YAAY,GAAG,EAAE;8BAGvB,MAAM,YAAY,GAAG,EAAE;;;;6BA6CxB,QAAQ,MAAM;;;mCAKrB,MAAM,YACR,MAAM,UACR,OAAO;;;qCAOkB,MAAM;;;iCAIV,MAAM,YAAY,MAAM,UAAU,OAAO;gCAG1C,MAAM,YAAY,OAAO;8BAG3B,MAAM,SAAS,OAAO,UAAU,OAAO;;;oBAUjD,MAAM;qBACX,MAAM;kBACT,MAAM;sBACF,MAAM,aAAa,cAAc;uBAEhC,MAAM,QAAQ,MAAM,GAAG,MAAM;oBAEhC,MAAM;uBACH,MAAM,MAAM,MAAM;mBACtB,MAAM,SAAS;YAAE,SAAS,CAAC,EAAE,OAAO,CAAA;SAAE;oBAErC,MAAM;mBACD,MAAM,MAAM,MAAM;;;AAMrC,wBAOE"}

package/dist/tests/__mocks__/@appium/support.js

@@ -1,5 +1,6 @@
 // Mock @appium/support for Jest tests
 // This avoids the ESM/CommonJS mismatch with uuid dependency
+import { promises as fsPromises, existsSync } from 'node:fs';
 export const logger = {
     getLogger: (_name) => 
     // Simple logger implementation for tests
@@ -63,6 +64,24 @@ export const zip = {
         // Silent in tests by default
     },
 };
+/**
+ * Minimal `fs` mock that delegates to node:fs/promises so test code touching
+ * the real filesystem continues to work.
+ */
+export const fs = {
+    exists: async (p) => existsSync(p),
+    readdir: (p) => fsPromises.readdir(p),
+    stat: (p) => fsPromises.stat(p),
+    readFile: (p, encoding) => fsPromises.readFile(p, encoding),
+    writeFile: (p, data) => fsPromises.writeFile(p, data),
+    unlink: (p) => fsPromises.unlink(p),
+    rename: (from, to) => fsPromises.rename(from, to),
+    mkdir: (p, opts) => fsPromises.mkdir(p, opts),
+    mkdirp: (p) => fsPromises.mkdir(p, { recursive: true }),
+    mv: async (from, to) => {
+        await fsPromises.rename(from, to);
+    },
+};
 // Export other commonly used utilities from @appium/support if needed
 export default {
     logger,
@@ -70,5 +89,6 @@ export default {
     net,
     plist,
     zip,
+    fs,
 };
 //# sourceMappingURL=support.js.map

package/dist/tests/__mocks__/@appium/support.js.map

@@ -1 +1 @@
-{"version":3,"file":"support.js","sourceRoot":"","sources":["../../../../src/tests/__mocks__/@appium/support.ts"],"names":[],"mappings":"AAAA,sCAAsC;AACtC,6DAA6D;AAE7D,MAAM,CAAC,MAAM,MAAM,GAAG;IACpB,SAAS,EAAE,CAAC,KAAa,EAAE,EAAE;IAC3B,yCAAyC;IACzC,kDAAkD;IAClD,CAAC;QACC,KAAK,EAAE,CAAC,QAAgB,EAAE,GAAG,KAAY,EAAE,EAAE;YAC3C,6BAA6B;QAC/B,CAAC;QACD,IAAI,EAAE,CAAC,QAAgB,EAAE,GAAG,KAAY,EAAE,EAAE;YAC1C,6BAA6B;QAC/B,CAAC;QACD,IAAI,EAAE,CAAC,QAAgB,EAAE,GAAG,KAAY,EAAE,EAAE;YAC1C,6BAA6B;QAC/B,CAAC;QACD,KAAK,EAAE,CAAC,QAAgB,EAAE,GAAG,KAAY,EAAE,EAAE;YAC3C,6BAA6B;QAC/B,CAAC;QACD,KAAK,EAAE,CAAC,QAAgB,EAAE,GAAG,KAAY,EAAE,EAAE;YAC3C,6BAA6B;QAC/B,CAAC;KACF,CAAC;CACL,CAAC;AAmBF,6EAA6E;AAC7E,MAAM,CAAC,MAAM,iBAAiB,GAAsB;IAClD,WAAW,EAAE,EAAE;IACf,YAAY,EAAE,GAAG,EAAE,CAAC,OAAO,CAAC,OAAO,CAAC,MAAM,CAAC,IAAI,CAAC,uBAAuB,CAAC,CAAC;IACzE,MAAM,CAAC,CAAS,EAAE,CAAS;QACzB,IAAI,CAAC,WAAW,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC;QAC9B,OAAO,IAAI,CAAC;IACd,CAAC;IACD,IAAI,CAAC,KAAe;QAClB,OAAO,IAAI,CAAC;IACd,CAAC;IACD,QAAQ;QACN,OAAO,IAAI,CAAC,YAAY,EAAE,CAAC;IAC7B,CAAC;IACD,KAAK;QACH,IAAI,CAAC,WAAW,GAAG,EAAE,CAAC;QACtB,IAAI,CAAC,YAAY,GAAG,GAAG,EAAE,CACvB,OAAO,CAAC,OAAO,CAAC,MAAM,CAAC,IAAI,CAAC,uBAAuB,CAAC,CAAC,CAAC;IAC1D,CAAC;CACF,CAAC;AAEF,MAAM,CAAC,MAAM,SAAS,GAAG;IACvB,YAAY,EAAE,GAAG,EAAE,CAAC,CAAC,MAAc,EAAE,EAAE,CAAC,iBAAiB;CAC1D,CAAC;AAEF,MAAM,CAAC,MAAM,GAAG,GAAG;IACjB,YAAY,EAAE,KAAK,EACjB,UAAkB,EAClB,QAAgB,EAChB,KAAe,EACf,EAAE;QACF,6BAA6B;IAC/B,CAAC;CACF,CAAC;AAEF,MAAM,CAAC,MAAM,KAAK,GAAG;IACnB,cAAc,EAAE,KAAK,EAAE,UAAkB,EAAE,EAAE,CAAC,CAAC,EAAE,CAAC;CACnD,CAAC;AAEF,MAAM,CAAC,MAAM,GAAG,GAAG;IACjB,YAAY,EAAE,KAAK,EAAE,QAAgB,EAAE,QAAgB,EAAE,KAAe,EAAE,EAAE;QAC1E,6BAA6B;IAC/B,CAAC;IACD,WAAW,EAAE,KAAK,EAAE,QAAgB,EAAE,QAAiB,EAAE,EAAE;QACzD,6BAA6B;IAC/B,CAAC;IACD,SAAS,EAAE,KAAK,EAAE,QAAgB,EAAE,IAAc,EAAE,KAAe,EAAE,EAAE;QACrE,6BAA6B;IAC/B,CAAC;CACF,CAAC;AAEF,sEAAsE;AACtE,eAAe;IACb,MAAM;IACN,SAAS;IACT,GAAG;IACH,KAAK;IACL,GAAG;CACJ,CAAC"}
+{"version":3,"file":"support.js","sourceRoot":"","sources":["../../../../src/tests/__mocks__/@appium/support.ts"],"names":[],"mappings":"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"}