swipium 1.0.0

package/dist/version.js

@@ -0,0 +1,62 @@
+// Single source of truth for the Swipium version and the public v1 tool surface. Used by the
+// server identity, qa_doctor / qa_start_session, qa_capabilities, and `swipium verify`.
+export const SWIPIUM_VERSION = '1.0.0';
+export const TOOL_NAMES = [
+    'qa_agent_brief',
+    'qa_capabilities',
+    'qa_test_this',
+    'qa_job_status',
+    'qa_status',
+    'qa_explain_blocker',
+    'qa_continue_from_blocker',
+    'qa_get_artifact',
+    'qa_doctor',
+    'qa_start_session',
+    'qa_detect_context',
+    'qa_plan',
+    'qa_prepare_target',
+    'qa_prepare_ios_target',
+    'qa_ios',
+    'qa_wda',
+    'qa_snapshot',
+    'qa_act',
+    'qa_clear_overlay',
+    'qa_check_health',
+    'qa_screenshot',
+    'qa_note',
+    'qa_assert_visual',
+    'qa_smoke',
+    'qa_explore',
+    'qa_report',
+    'qa_app_map_build',
+    'qa_app_map_read',
+    'qa_app_map_query',
+    'qa_app_map_feature_scope',
+    'qa_app_map_validate',
+    'qa_flow_check',
+    'qa_flow_run',
+    'qa_flow_generate',
+    'qa_suite_generate',
+    'qa_suite_compile',
+    'qa_testcase_generate',
+    'qa_first_run_plan',
+    'qa_first_run_continue',
+    'qa_automation_plan',
+    'qa_automation_generate',
+    'qa_automation_validate',
+];
+export const TOOL_COUNT = TOOL_NAMES.length;
+export const TOOL_NAME_SET = new Set(TOOL_NAMES);
+/** MCP prompts (reusable workflow templates) — PHASE3-PLAN §3.3. */
+export const PROMPT_NAMES = [
+    'swipium_setup_check',
+    'swipium_full_smoke',
+    'swipium_bug_repro',
+    'swipium_convert_run_to_flow',
+];
+export const PROMPT_COUNT = PROMPT_NAMES.length;
+/** Shown when a client may be running an older build than what's installed on disk. */
+export const STALE_CLIENT_HINT = `Swipium v${SWIPIUM_VERSION} exposes ${TOOL_COUNT} tools + ${PROMPT_COUNT} prompts. If your MCP client lists fewer ` +
+    `(e.g. qa_test_this / qa_plan / qa_flow_run / qa_ios missing), it is running a server ` +
+    `spawned before the upgrade. Restart the client to reload Swipium.`;
+//# sourceMappingURL=version.js.map

package/dist/version.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"version.js","sourceRoot":"","sources":["../src/version.ts"],"names":[],"mappings":"AAAA,6FAA6F;AAC7F,wFAAwF;AAExF,MAAM,CAAC,MAAM,eAAe,GAAG,OAAO,CAAC;AAEvC,MAAM,CAAC,MAAM,UAAU,GAAG;IACxB,gBAAgB;IAChB,iBAAiB;IACjB,cAAc;IACd,eAAe;IACf,WAAW;IACX,oBAAoB;IACpB,0BAA0B;IAC1B,iBAAiB;IACjB,WAAW;IACX,kBAAkB;IAClB,mBAAmB;IACnB,SAAS;IACT,mBAAmB;IACnB,uBAAuB;IACvB,QAAQ;IACR,QAAQ;IACR,aAAa;IACb,QAAQ;IACR,kBAAkB;IAClB,iBAAiB;IACjB,eAAe;IACf,SAAS;IACT,kBAAkB;IAClB,UAAU;IACV,YAAY;IACZ,WAAW;IACX,kBAAkB;IAClB,iBAAiB;IACjB,kBAAkB;IAClB,0BAA0B;IAC1B,qBAAqB;IACrB,eAAe;IACf,aAAa;IACb,kBAAkB;IAClB,mBAAmB;IACnB,kBAAkB;IAClB,sBAAsB;IACtB,mBAAmB;IACnB,uBAAuB;IACvB,oBAAoB;IACpB,wBAAwB;IACxB,wBAAwB;CAChB,CAAC;AAEX,MAAM,CAAC,MAAM,UAAU,GAAG,UAAU,CAAC,MAAM,CAAC;AAC5C,MAAM,CAAC,MAAM,aAAa,GAAwB,IAAI,GAAG,CAAC,UAAU,CAAC,CAAC;AAEtE,oEAAoE;AACpE,MAAM,CAAC,MAAM,YAAY,GAAG;IAC1B,qBAAqB;IACrB,oBAAoB;IACpB,mBAAmB;IACnB,6BAA6B;CACrB,CAAC;AAEX,MAAM,CAAC,MAAM,YAAY,GAAG,YAAY,CAAC,MAAM,CAAC;AAEhD,uFAAuF;AACvF,MAAM,CAAC,MAAM,iBAAiB,GAC5B,YAAY,eAAe,YAAY,UAAU,YAAY,YAAY,2CAA2C;IACpH,uFAAuF;IACvF,mEAAmE,CAAC"}

package/dist/visual/ocr.js

@@ -0,0 +1,72 @@
+import { rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { loadProjectConfig } from '../cli/scan.js';
+import { captureCoordinateSpace, toDevicePoint } from '../lib/coordSpace.js';
+import { maskScreenshotForProvider, runVisualProvider } from './provider.js';
+export function configuredOcrCommand(root) {
+    const cfg = loadProjectConfig(root)?.ocrCommand;
+    return cfg ?? process.env.SWIPIUM_OCR_CMD;
+}
+export function parseOcrOutput(stdout) {
+    const trimmed = stdout.trim();
+    if (!trimmed)
+        return { text: '', regions: [] };
+    try {
+        const json = JSON.parse(trimmed);
+        const arr = Array.isArray(json) ? json : Array.isArray(json?.regions) ? json.regions : [];
+        const regions = arr
+            .map((r) => r)
+            .filter((r) => typeof r.text === 'string' && typeof r.confidence === 'number' && !!r.bbox && typeof r.bbox.x === 'number' && typeof r.bbox.y === 'number' && typeof r.bbox.width === 'number' && typeof r.bbox.height === 'number')
+            .map((r) => ({ ...r, coordinateSpace: 'screenshot_px' }));
+        const text = typeof json?.text === 'string' ? json.text : regions.map((r) => r.text).join('\n');
+        return { text, regions };
+    }
+    catch {
+        return { text: trimmed, regions: [] };
+    }
+}
+export async function runOcr(driver, root, command) {
+    const png = await driver.screenshot();
+    const coordinateSpace = await captureCoordinateSpace(driver, png);
+    const imgPath = join(tmpdir(), `swipium-ocr-${Date.now()}.png`);
+    const cleanup = [imgPath];
+    try {
+        writeFileSync(imgPath, png);
+        const masking = await maskScreenshotForProvider(root, imgPath, { task: 'ocr' });
+        cleanup.push(...masking.tempPaths);
+        const { resolved, result } = await runVisualProvider(command, { image: masking.imagePath }, {
+            task: 'ocr',
+            imagePath: masking.imagePath,
+            coordinateSpace,
+            masking: { providerConfigured: masking.providerConfigured, masksApplied: masking.masksApplied },
+        }, 30000);
+        return {
+            ...parseOcrOutput(result.stdout),
+            coordinateSpace,
+            provider: { io: resolved.io, argv: resolved.argv },
+            masking: { providerConfigured: masking.providerConfigured, masksApplied: masking.masksApplied },
+        };
+    }
+    finally {
+        for (const path of cleanup) {
+            try {
+                rmSync(path, { force: true });
+            }
+            catch {
+                // best-effort cleanup
+            }
+        }
+    }
+}
+export function findOcrRegion(result, query, minConfidence = 0.8) {
+    const q = query.toLowerCase();
+    const region = result.regions
+        .filter((r) => r.confidence >= minConfidence && r.text.toLowerCase().includes(q))
+        .sort((a, b) => b.confidence - a.confidence)[0];
+    if (!region)
+        return null;
+    const center = { x: region.bbox.x + region.bbox.width / 2, y: region.bbox.y + region.bbox.height / 2 };
+    return { region, devicePoint: toDevicePoint(result.coordinateSpace, center.x, center.y) };
+}
+//# sourceMappingURL=ocr.js.map

package/dist/visual/ocr.js.map

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

package/dist/visual/provider.js

@@ -0,0 +1,75 @@
+import { existsSync, rmSync } from 'node:fs';
+import { join } from 'node:path';
+import { tmpdir } from 'node:os';
+import { loadProjectConfig } from '../cli/scan.js';
+import { resolveCommandTemplate } from '../lib/commandTemplate.js';
+import { assertNoGitScope, run } from '../lib/spawn.js';
+function isProviderObject(value) {
+    return !!value && typeof value === 'object' && !Array.isArray(value) && ('command' in value);
+}
+export function resolveVisualProvider(command, vars, defaultTimeoutMs) {
+    const raw = isProviderObject(command) ? command.command : command;
+    const resolved = resolveCommandTemplate(raw, vars);
+    assertNoGitScope(resolved.command, resolved.args);
+    const io = isProviderObject(command) && command.io === 'json' ? 'json' : 'argv';
+    const timeoutMs = isProviderObject(command) && Number.isFinite(command.timeoutMs) && command.timeoutMs > 0 ? Math.floor(command.timeoutMs) : defaultTimeoutMs;
+    return { ...resolved, io, timeoutMs };
+}
+export async function runVisualProvider(command, vars, payload, defaultTimeoutMs) {
+    const resolved = resolveVisualProvider(command, vars, defaultTimeoutMs);
+    const input = resolved.io === 'json' ? JSON.stringify({ schema: 'swipium.visual.provider.v1', ...payload }) + '\n' : undefined;
+    const result = await run(resolved.command, resolved.args, { timeoutMs: resolved.timeoutMs, input });
+    return { resolved, result };
+}
+export function configuredMaskCommand(root) {
+    const cfg = loadProjectConfig(root)?.visualMaskCommand;
+    return cfg ?? process.env.SWIPIUM_VISUAL_MASK_CMD;
+}
+export function resolveMaskProvider(root) {
+    const command = configuredMaskCommand(root);
+    return command ? resolveVisualProvider(command, { image: '<screenshot>', output: '<masked-screenshot>' }, 30000) : null;
+}
+export async function maskScreenshotForProvider(root, imagePath, context) {
+    const command = configuredMaskCommand(root);
+    if (!command)
+        return { imagePath, tempPaths: [], masksApplied: [], providerConfigured: false };
+    const outputPath = join(tmpdir(), `swipium-masked-${Date.now()}.png`);
+    const { result } = await runVisualProvider(command, { image: imagePath, output: outputPath }, {
+        task: 'mask_screenshot',
+        imagePath,
+        outputPath,
+        context,
+    }, 30000);
+    let parsed = {};
+    try {
+        parsed = JSON.parse(result.stdout.trim());
+    }
+    catch {
+        parsed = {};
+    }
+    const produced = typeof parsed.imagePath === 'string' && parsed.imagePath.trim() ? parsed.imagePath : outputPath;
+    if (!existsSync(produced)) {
+        rmSync(outputPath, { force: true });
+        throw new Error('visualMaskCommand did not produce a masked imagePath or output file');
+    }
+    const masksApplied = Array.isArray(parsed.masksApplied) ? parsed.masksApplied.filter((v) => typeof v === 'string') : ['external_mask'];
+    return { imagePath: produced, tempPaths: produced === imagePath ? [] : [produced], masksApplied, providerConfigured: true };
+}
+export function boundedProviderObject(value, redact, maxChars = 8000) {
+    const raw = redact(JSON.stringify(value)) ?? '{}';
+    const bounded = raw.length > maxChars ? raw.slice(0, maxChars) : raw;
+    try {
+        const parsed = JSON.parse(bounded);
+        if (raw.length > maxChars)
+            parsed.truncated = true;
+        return parsed;
+    }
+    catch {
+        return { text: bounded, truncated: raw.length > maxChars };
+    }
+}
+export function boundedText(value, redact, maxChars = 8000) {
+    const safe = redact(value) ?? '';
+    return { text: safe.slice(0, maxChars), truncated: safe.length > maxChars };
+}
+//# sourceMappingURL=provider.js.map

package/dist/visual/provider.js.map

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

package/docs/README.md

@@ -0,0 +1,19 @@
+# Swipium Docs
+
+This directory contains public v1 documentation for the Swipium MCP server.
+
+## Index
+
+- [MCP Server](mcp-server.md): server setup, client configuration, and agent integration.
+- [Tool Reference](tools.md): public v1 MCP tools grouped by workflow.
+
+## Scope
+
+Swipium v1 is simulator-only:
+
+- Android Emulator.
+- iOS Simulator.
+- Local MCP stdio server.
+- Local artifacts and app-map memory.
+
+Real devices, Jira integration, external ticket workflows, cloud execution, and certification are outside the public v1 scope.

package/docs/mcp-server.md

@@ -0,0 +1,135 @@
+# MCP Server
+
+Swipium runs as a local stdio MCP server. The MCP client starts the process and sends tool calls over stdin and stdout.
+
+## Requirements
+
+- Node.js 20 or newer.
+- A mobile app repository as the MCP `cwd`.
+- Android Studio for Android Emulator workflows.
+- Xcode for iOS Simulator workflows.
+
+## Server Command
+
+No global install:
+
+```jsonc
+{s
+  "mcpServers": {
+    "swipium": {
+      "command": "npx",
+      "args": ["-y", "swipium"],
+      "cwd": "/absolute/path/to/your/mobile-app",
+      "timeout": 600000
+    }
+  }
+}
+```
+
+Global install:
+
+```jsonc
+{
+  "mcpServers": {
+    "swipium": {
+      "command": "swipium",
+      "args": [],
+      "cwd": "/absolute/path/to/your/mobile-app",
+      "timeout": 600000
+    }
+  }
+}
+```
+
+## Claude Code
+
+```bash
+npm install -g swipium
+swipium init claude --apply --scope project
+```
+
+No global install:
+
+```bash
+claude mcp add swipium --scope project -- npx -y swipium
+```
+
+## Gemini CLI
+
+```bash
+npm install -g swipium
+swipium init gemini --apply
+```
+
+No global install:
+
+```bash
+gemini mcp add swipium npx -y swipium
+```
+
+## Codex
+
+```bash
+npm install -g swipium
+swipium init codex --apply
+```
+
+Manual config:
+
+```toml
+[mcp_servers.swipium]
+command = "npx"
+args = ["-y", "swipium"]
+cwd = "/absolute/path/to/your/mobile-app"
+```
+
+## Verification
+
+Run:
+
+```bash
+swipium verify
+```
+
+Then, inside the MCP client, call:
+
+```text
+qa_doctor
+qa_capabilities
+```
+
+Expected v1 tool count: 42.
+
+If the client lists fewer tools, restart the MCP client. MCP clients often keep an old server process alive after package upgrades.
+
+## Artifacts
+
+Swipium stores evidence as local artifacts and returns `swipium://` URIs. Use:
+
+- `qa_get_artifact` to read an artifact by URI.
+- `qa_report` to generate report artifacts.
+- `qa_screenshot` to capture screenshot artifacts.
+- `qa_app_map_read` to read app-map sections.
+
+Images default to metadata through `qa_get_artifact`. Request inline mode only when pixels are needed.
+
+## Consent
+
+Swipium requests consent before high-impact local actions such as:
+
+- Booting a simulator when required by the plan.
+- Installing external app artifacts.
+- Writing generated automation into a project directory.
+- Running mutating flow steps.
+
+The consent result includes a `consentId`. Re-call the same tool with `approve: true` and that `consentId` to continue.
+
+## Simulator Scope
+
+Public v1 supports:
+
+- Android Emulator.
+- iOS Simulator.
+- Optional WebDriverAgent for structured iOS simulator automation.
+
+Public v1 does not support real-device execution.

package/docs/tools.md

@@ -0,0 +1,130 @@
+# Tool Reference
+
+Swipium v1 exposes 42 public MCP tools. The intended default entry point is `qa_test_this`.
+
+## Start
+
+Use these tools to orient the agent, start autopilot work, poll jobs, handle blockers, and fetch artifacts.
+
+| Tool | What it does | Use when |
+| --- | --- | --- |
+| `qa_agent_brief` | Returns the recommended orchestration rules for agents. | The agent needs the correct first call, polling behavior, report behavior, or blocker handling rules. |
+| `qa_capabilities` | Lists the public v1 tool surface grouped by purpose. | The agent or user needs to discover available Swipium capabilities. |
+| `qa_test_this` | Autopilot for "test it": resolves the project, finds or builds an artifact, prepares a simulator, runs smoke or exploration, reports results, and can generate suite output. | The user gives a low-context request such as "test this app". |
+| `qa_job_status` | Polls a long-running job started by `qa_test_this` or prepare tools. | A tool returns a `jobId` with status `running`. |
+| `qa_status` | Returns compact session status and recommended next action. | The agent needs to recover context during a session. |
+| `qa_explain_blocker` | Explains a typed blocker, likely owner, and recovery path. | A run stops with a blocker and the user needs a concise explanation. |
+| `qa_continue_from_blocker` | Resumes after user input and registers secret values for redaction. | A blocker asks for credentials, OTP, target choice, or approval data. |
+| `qa_get_artifact` | Fetches artifact metadata or contents by `swipium://` URI. | A report, screenshot, dump, log, or generated file must be read. |
+
+## Setup
+
+Use these tools to verify the local environment, create sessions, and prepare simulator targets.
+
+| Tool | What it does | Use when |
+| --- | --- | --- |
+| `qa_doctor` | Checks Node, Android tooling, emulator availability, AVDs, and stale-client symptoms. | Before the first run or when setup fails. |
+| `qa_start_session` | Opens a project QA session with budget, response mode, fixtures, and sensitive mode. | Running lower-level tools directly instead of `qa_test_this`. |
+| `qa_detect_context` | Detects framework, project readiness, artifacts, devices, and likely blockers. | The agent needs a preflight view before selecting a path. |
+| `qa_plan` | Produces a safe workflow plan before acting. | The user asks for a plan or the agent needs a low-risk next step. |
+| `qa_prepare_target` | Prepares an Android Emulator target, installs or launches an APK, and binds the session. | Testing Android on an emulator. |
+| `qa_prepare_ios_target` | Boots an iOS Simulator, installs a simulator `.app` when provided, launches a bundle id, and reports visual or WDA mode. | Testing iOS on a simulator. |
+| `qa_ios` | Runs iOS Simulator lifecycle operations such as boot, install, launch, screenshot, logs, privacy reset, and erase. | Direct iOS simulator control is needed. |
+| `qa_wda` | Checks, builds, or starts WebDriverAgent for structured iOS simulator automation. | iOS needs structured UI tree access instead of visual-only checks. |
+
+## Drive
+
+Use these tools to observe the UI, act on it, collect evidence, and record results.
+
+| Tool | What it does | Use when |
+| --- | --- | --- |
+| `qa_snapshot` | Captures compact structured UI elements where the backend supports it. | The agent needs selectors, visible text, or UI state. |
+| `qa_act` | Taps, types, clears, swipes, scrolls, presses keys, opens URLs, waits, and observes after action. | The agent needs to drive the app step by step. |
+| `qa_clear_overlay` | Attempts to dismiss common overlays blocking a target. | Popups, permissions, modals, or sheets block the next action. |
+| `qa_check_health` | Checks foreground app status, crash signals, ANR, error boundaries, and native health. | The agent needs to distinguish app bugs from environment issues. |
+| `qa_screenshot` | Captures a screenshot artifact with coordinate-space metadata. | Visual evidence is required. |
+| `qa_note` | Records a structured QA outcome in the session. | The agent needs to log pass, fail, blocked, skipped, or finding details. |
+| `qa_assert_visual` | Captures a visual assertion with evidence. | The agent needs to document that a visual condition is true or false. |
+
+## Run
+
+Use these tools to run broader QA workflows and produce reports.
+
+| Tool | What it does | Use when |
+| --- | --- | --- |
+| `qa_smoke` | Runs launch smoke, baseline health, screenshot evidence, and saved flows. | The app is prepared and the agent needs a deterministic smoke pass. |
+| `qa_explore` | Performs bounded guided exploration, builds a screen graph, and records evidence. | The agent needs to discover reachable workflows or collect runtime app-map data. |
+| `qa_report` | Generates a session report with findings, blockers, evidence, mutations, workarounds, and next actions. | A run should be summarized or exported. |
+
+## App Map
+
+Use these tools to build and read Swipium's durable app knowledge map.
+
+| Tool | What it does | Use when |
+| --- | --- | --- |
+| `qa_app_map_build` | Builds or updates the app map from static analysis and runtime observations. | The project needs durable QA memory. |
+| `qa_app_map_read` | Reads compact app-map sections such as features, screens, auth, automation, or test suite. | The agent needs app context without flooding the transcript. |
+| `qa_app_map_query` | Searches features, screens, tests, and code links with ranked results. | The user asks about a feature, screen, or test surface. |
+| `qa_app_map_feature_scope` | Resolves a feature query or feature id into focused testing scope and recommended plan. | The agent needs to test a specific feature. |
+| `qa_app_map_validate` | Validates schema, provenance, links, duplicate ids, impossible states, and stale fingerprints. | The map must be trusted before feature-focused testing. |
+
+## Flows and Suites
+
+Use these tools to create, validate, run, and compile reusable test assets.
+
+| Tool | What it does | Use when |
+| --- | --- | --- |
+| `qa_flow_check` | Parses and statically validates a Swipium flow. | A flow file should be checked before execution. |
+| `qa_flow_run` | Executes a Swipium flow against a prepared simulator session. | A saved flow needs to run against the app. |
+| `qa_flow_generate` | Generates a flow from recorded actions. | A manual or exploratory run should become a reusable flow. |
+| `qa_suite_generate` | Generates a POM-style suite from recorded behavior. | The run should become a structured test suite. |
+| `qa_suite_compile` | Compiles a generated suite into runnable Swipium flows. | A generated suite needs executable flow output. |
+| `qa_testcase_generate` | Generates test-case documentation from recorded behavior. | The run should produce human-readable test cases and steps. |
+
+## First Run
+
+Use these tools for login, account creation, onboarding, permissions, OTP, and paywall screens.
+
+| Tool | What it does | Use when |
+| --- | --- | --- |
+| `qa_first_run_plan` | Classifies the current first-run screen and creates a safe plan without acting. | The agent reaches login, signup, onboarding, permission, OTP, paywall, or home screens. |
+| `qa_first_run_continue` | Executes bounded first-run steps with safe generated data when allowed and stops at gates. | The plan can safely proceed in a test or staging environment. |
+
+## Automation
+
+Use these tools to generate and validate automation code from Swipium evidence.
+
+| Tool | What it does | Use when |
+| --- | --- | --- |
+| `qa_automation_plan` | Plans generated JS, TS, or Python Appium automation from project profile and recorded actions. | The user asks to automate the tested behavior. |
+| `qa_automation_generate` | Generates an Appium POM suite from recorded actions and validates it. | The run should produce automation code. |
+| `qa_automation_validate` | Validates generated automation code without a device. | Generated files need checks for secrets, durability, capabilities, syntax, and empty files. |
+
+## Recommended Entry Points
+
+| User intent | First tool |
+| --- | --- |
+| "Test it" | `qa_test_this` |
+| "Check setup" | `qa_doctor` |
+| "Start a manual run" | `qa_start_session` |
+| "Launch Android" | `qa_prepare_target` |
+| "Launch iOS" | `qa_prepare_ios_target` |
+| "Smoke test" | `qa_smoke` |
+| "Explore the app" | `qa_explore` |
+| "Generate report" | `qa_report` |
+| "Read app memory" | `qa_app_map_read` |
+| "Create a flow" | `qa_flow_generate` |
+| "Generate automation" | `qa_automation_plan` |
+
+## Extension Pattern
+
+When adding tools in future releases, document each tool with:
+
+- Name.
+- Group.
+- What it does.
+- When to use it.
+- Main inputs.
+- Main outputs.
+- Scope limits.
+- Consent or mutation behavior.

package/package.json

@@ -0,0 +1,70 @@
+{
+  "name": "swipium",
+  "version": "1.0.0",
+  "private": false,
+  "description": "Swipium MCP server for simulator-based mobile QA workflows, evidence capture, app maps, and generated test suites.",
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "mobile-testing",
+    "qa-automation",
+    "android-emulator",
+    "ios-simulator",
+    "appium",
+    "ai-agents",
+    "test-automation",
+    "e2e-testing",
+    "react-native-testing",
+    "flutter-testing",
+    "app-map",
+    "test-suites",
+    "developer-tools"
+  ],
+  "license": "MIT",
+  "type": "module",
+  "bin": {
+    "swipium": "dist/index.js"
+  },
+  "files": [
+    "dist",
+    "docs"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/geropalombo/swipium.git"
+  },
+  "bugs": {
+    "url": "https://github.com/geropalombo/swipium/issues"
+  },
+  "homepage": "https://github.com/geropalombo/swipium",
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc && chmod +x dist/index.js",
+    "dev": "tsc -w",
+    "start": "node dist/index.js",
+    "verify": "npm run build && node dist/index.js verify",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "audit:prod": "npm audit --omit=dev --audit-level=moderate",
+    "release:check": "npm run typecheck && npm test && npm run audit:prod && npm pack --dry-run",
+    "prepack": "npm run build",
+    "prepublishOnly": "npm run build",
+    "inspector": "npm run build && npx @modelcontextprotocol/inspector node dist/index.js"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.19.1",
+    "fast-xml-parser": "^5.8.0",
+    "yaml": "^2.9.0",
+    "zod": "^3.25.76"
+  },
+  "devDependencies": {
+    "@types/node": "^22.10.2",
+    "typescript": "^5.7.2",
+    "vitest": "^4.1.7"
+  }
+}