@testspectra/cli 1.0.0

package/CLI_IMPLEMENTATION_PLAN.md

@@ -0,0 +1,369 @@
+# TestSpectra CLI (`@testspectra/cli`) Implementation Plan
+
+## 1. Overview
+The TestSpectra CLI provides a zero-config, command-line interface for running Web and Mobile (Android/iOS) test suites using the shared Rust core runner (`core/test-runner` and `core/device-manager`).
+
+The CLI configuration strictly adheres to the backend `ProjectConfig` and `ConfigData` schema (`backend/src/models/project_config.rs` and `src/services/project-config-service.ts`).
+
+---
+
+## 2. Architecture
+
+```
+                       ┌─────────────────────────────────┐
+                       │    TypeScript CLI (`cli/`)       │
+                       │  (commander / inquirer / ora)   │
+                       └────────────────┬────────────────┘
+                                        │
+                       ┌────────────────┴────────────────┐
+                       ▼                                 ▼
+              Local Execution                   Remote Execution
+       ┌─────────────────────────────┐   ┌─────────────────────────────┐
+       │ NAPI-RS / Subprocess Bridge │   │   HTTP REST API Client      │
+       │ to core/test-runner (Rust)  │   │   to Backend API Server     │
+       └──────────────┬──────────────┘   └──────────────┬──────────────┘
+                      │                                 │
+                      ▼                                 ▼
+          ┌───────────────────────┐         ┌───────────────────────┐
+          │ core/test-runner      │         │ Backend API           │
+          │ (Rust Engine)         │         │ (PostgreSQL + Engine) │
+          └───────────────────────┘         └───────────────────────┘
+```
+
+---
+
+## 3. Package & File Structure
+
+```
+testspectra-source/
+└── cli/
+    ├── README.md
+    ├── CLI_IMPLEMENTATION_PLAN.md    <-- This Plan
+    ├── package.json
+    ├── tsconfig.json
+    ├── bin/
+    │   └── testspectra.js
+    └── src/
+        ├── index.ts                  # Main entrypoint & Commander setup
+        ├── config/
+        │   ├── schema.ts             # Exact ConfigData & ProjectConfig TypeScript types
+        │   └── loader.ts             # Config resolution (file vs remote vs CLI flags)
+        ├── commands/
+        │   ├── init.ts               # Generate default testspectra.config.json
+        │   ├── run.ts                # Execute test cases/suites
+        │   ├── devices.ts            # List connected Android/iOS/Web devices
+        │   └── doctor.ts             # System diagnostic check (ADB, Appium, Java, Browsers)
+        ├── runner/
+        │   ├── bridge.ts             # Interface to Rust core runner binary/NAPI
+        │   └── reporter.ts           # Spec, JSON, & JUnit XML reporters
+        └── api/
+            └── client.ts             # REST client for sync with backend project config
+```
+
+---
+
+## 4. Configuration Schema (`cli/src/config/schema.ts`)
+
+Matches `backend/src/models/project_config.rs` and `src/services/project-config-service.ts`:
+
+```typescript
+export interface WebConfig {
+  baseUrl: string;
+  maxConcurrentSessions: string;
+  headlessMode: boolean;
+  implicitWait: string;
+  pageLoadTimeout: string;
+  scriptTimeout: string;
+  parallelizationMode: "testcase" | "suite";
+}
+
+export interface AndroidConfig {
+  appiumServer: string;
+  platformName: string;
+  platformVersion: string;
+  deviceName: string;
+  automationName: string;
+  appPackage: string;
+  appActivity: string;
+  autoGrantPermissions: boolean;
+  noReset: boolean;
+  implicitWait: string;
+  parallelizationMode: "testcase" | "suite";
+}
+
+export interface IosConfig {
+  appiumServer: string;
+  platformName: string;
+  platformVersion: string;
+  deviceName: string;
+  automationName: string;
+  bundleId: string;
+  udid: string;
+  xcodeOrgId: string;
+  xcodeSigningId: string;
+  autoAcceptAlerts: boolean;
+  noReset: boolean;
+  implicitWait: string;
+  parallelizationMode: "testcase" | "suite";
+}
+
+export interface ConfigData {
+  webConfig: WebConfig;
+  browsers: Array<{
+    id: string;
+    type: string;
+    mobileEmulation: boolean;
+    deviceName?: string;
+    width?: string;
+    height?: string;
+  }>;
+  androidConfig: AndroidConfig;
+  iosConfig: IosConfig;
+  loadConfig: {
+    virtualUsers: string;
+    duration: string;
+  };
+  loadStages: Array<{
+    id: string;
+    duration: string;
+    targetVUs: string;
+  }>;
+  thresholds: Array<{
+    id: string;
+    metricType: string;
+    maxValue: string;
+  }>;
+  executionConfig?: {
+    networkMonitoringEnabled: boolean;
+    fastResponseTime: string;
+    normalResponseTime: string;
+    monitoredDomains?: Array<{ domain: string; enabled: boolean }>;
+    environmentVariables?: Array<{ key: string; value: string }>;
+  };
+}
+
+export interface ProjectConfig {
+  project_id: string;
+  config_data: ConfigData;
+  updated_at?: string;
+}
+```
+
+---
+
+## 5. Key CLI Commands & Features
+
+| Command | Arguments / Flags | Description |
+|---|---|---|
+| `testspectra init` | `--force` | Generate default `testspectra.config.json` adhering to `ConfigData`. |
+| `testspectra doctor` | `--fix` | Diagnostic check for ADB, Appium, Chrome, Java, Node. |
+| `testspectra devices` | `--target <android\|ios\|web>` | List connected devices & available browsers. |
+| `testspectra run` | `<path>` `--target <target>` `--remote` `--project-id <id>` | Run test cases/suites via local config or remote backend config. |
+
+---
+
+## 6. Execution Flow & Driver Management
+
+1. **Base Directory Resolution (`app_data_path`):**
+   - CLI sets `RunnerContext.app_data_path` to `./.testspectra` inside the target project root (overridable via `--workdir`).
+   - Driver cache automatically lands in `./.testspectra/driver_cache`.
+   - Desktop Tauri app uses OS AppSupport (`~/Library/Application Support/...`), while CLI isolates everything inside project `.testspectra`.
+
+2. **Initialization:** CLI resolves config via local `testspectra.config.json` or fetches `ProjectConfig` from backend.
+3. **Environment Validation:** Verifies Appium / ADB readiness using `core/device-manager`.
+4. **Execution & Driver Auto-Recovery:**
+   - Pass resolved `ConfigData` JSON + test files payload into `core/test-runner` Rust engine via NAPI bridge or subprocess IPC stream.
+   - `core/test-runner` automatically monitors for Chromedriver download failures, wipes `./.testspectra/driver_cache`, and retries once transparently.
+5. **Reporting:** Stream real-time logs and output JUnit / Spec formatted result.
+
+---
+
+## 7. Refactoring Plan: Moving Shared Core Features from `src-tauri` to `core/`
+
+To avoid code duplication and support CLI/Server environments natively, the following features will be refactored from `src-tauri` into the shared `core` workspace:
+
+### A. ADB Wireless & Pairing (`src-tauri/src/adb.rs` → `core/device-manager`)
+- **Current State:** High-level device discovery and auto-reconnection loop (`get_adb_devices_impl`) live in `src-tauri/src/adb.rs` while primitive ADB calls live in `core/device-manager`.
+- **Target Architecture:**
+  - Move stateful device tracking & background auto-reconnection into `core/device-manager::android`.
+  - Provide headless Rust/C-API/NAPI methods (`get_adb_devices`, `pair_adb_device`, `start_qr_pairing`) accessible to both Tauri app and `testspectra devices pair` CLI command.
+
+### B. Dependency Check & Installer (`src-tauri/src/dependencies.rs` → `core/test-runner`)
+- **Current State:** `src-tauri/src/dependencies.rs` wraps `testspectra_core_runner::dependency` with Tauri `AppHandle` events for emitting install logs.
+- **Target Architecture:**
+  - Decouple log emission using a generic callback/channel pattern (`fn(log: DependencyLog)`).
+  - Move full dependency resolution & auto-installer (`install_missing_dependencies`) into `core/test-runner::dependency`.
+  - Tauri UI subscribes via channel; CLI `testspectra doctor --fix` renders progress directly to terminal stdout/stderr via `ora` spinner / progress bar.
+
+---
+
+## 8. Multi-Platform Hierarchy & Ambient Type Resolution
+
+TestSpectra scripts are organized natively by **Entity Folders** supporting multi-platform hierarchy resolution (as defined in `docs/features/v1.3-MULTI_PLATFORM_AUTOMATION.md`):
+
+### A. Resolution Hierarchy (Highest to Lowest Priority)
+| Target Context / Spec | Hierarchy Chain |
+| :--- | :--- |
+| **Web Context (`web.test.ts`)** | `*.web.ts` &rarr; `*.common.ts` (or `*.ts` fallback) |
+| **iOS Context (`ios.test.ts`)** | `*.ios.ts` &rarr; `*.mobile.ts` &rarr; `*.common.ts` |
+| **Android Context (`android.test.ts`)** | `*.android.ts` &rarr; `*.mobile.ts` &rarr; `*.common.ts` |
+| **Mobile Context (`mobile.test.ts`)** | `*.mobile.ts` &rarr; `*.common.ts` |
+| **Common Context (`common.test.ts`)** | `*.common.ts` (Strict base only) |
+
+### B. Ambient Global Resolution in Specs (Zero Manual Imports)
+TestSpectra execution preparer (`core/test-runner`) and the CLI Type Generator (`cli::TypeGenerator`) synthesize global ambient declarations (`.testspectra/types/{web,android,ios,mobile,common}.d.ts`) so specs never need manual imports for Page Objects, Actions, Steps, or Fixtures:
+- **`LoginPage.open()`** &rarr; Ambiently declared via `declare const LoginPage: typeof import('../page-objects/LoginPage/web.js').default;`
+- **`Spectra.actionName()`** &rarr; Ambiently declared per platform from `actions/`.
+- **`Step.stepName()`** &rarr; Ambiently declared per platform from `steps/`.
+- **`Fixture.fixtureName`** &rarr; Ambiently declared from `fixtures/` assets.
+- **`browser.intercept()`** &rarr; Ambiently declared on `WebdriverIO.Browser`.
+
+No custom VS Code language server plugin or extension is required. Standard TypeScript compiler (`tsc`) and standard IDEs (VS Code, Cursor, WebStorm) handle everything natively via the platform tsconfigs.
+
+## 9. Standard TestSpectra Multi-Platform Project Structure & Platform-Isolated TSConfigs
+
+To ensure 100% accurate TypeScript type resolution without collisions across platform signatures (e.g. `login(u,p)` on Web vs `login(u,p,captcha)` on Mobile), TestSpectra uses **Platform-Isolated TSConfigs**:
+
+```text
+my-test-project/
+├── tsconfig.json                     # Solution root pointing to platform tsconfigs
+├── tsconfig.web.json                 # Web TS context (web specs + web.d.ts + common.d.ts)
+├── tsconfig.android.json             # Android TS context (android specs + android.d.ts + mobile.d.ts + common.d.ts)
+├── tsconfig.ios.json                 # iOS TS context (ios specs + ios.d.ts + mobile.d.ts + common.d.ts)
+├── spectra.config.ts                 # Matching backend ConfigData schema (typed with defineConfig)
+├── .testspectra/                     # Local TestSpectra runtime & types (ignored in git)
+│   ├── types/
+│   │   ├── web.d.ts                  # Generated ambient types for web
+│   │   ├── android.d.ts              # Generated ambient types for android
+│   │   ├── ios.d.ts                  # Generated ambient types for ios
+│   │   └── common.d.ts               # Generated ambient types for common
+│   └── driver_cache/                 # Managed Chromedriver / Appium cache
+│
+├── specs/                            # Entity folder per Test Case
+│   └── TC-LOGIN-01/
+│       ├── web.test.ts               # Web implementation (zero-import single it block)
+│       ├── android.test.ts           # Android implementation
+│       └── ios.test.ts               # iOS implementation
+│
+├── page-objects/                     # Entity folder per Page Object
+│   └── LoginPage/
+│       ├── web.ts                    # Web Page Object implementation
+│       └── mobile.ts                 # Shared mobile Page Object implementation
+│
+├── actions/                          # Entity folder per Action
+│   └── verifyOtp/
+│       ├── web.action.ts
+│       └── mobile.action.ts
+│
+├── steps/                            # Entity folder per Step
+│   └── loginUser/
+│       ├── web.step.ts
+│       └── mobile.step.ts
+│
+├── fixtures/                         # Test assets (JSON, PNG, CSV)
+│   └── userData.json
+│
+└── hooks/                            # Per-suite lifecycle hooks
+    └── default/
+        ├── before.web.hook.ts
+        ├── before.android.hook.ts
+        └── before.ios.hook.ts
+```
+
+### Complete Scaffolding on `spectra init`
+Running `spectra init` automatically scaffolds:
+1. `spectra.config.ts` using `defineConfig`.
+2. Root `tsconfig.json` & platform-isolated `tsconfig.web.json`, `tsconfig.android.json`, `tsconfig.ios.json`.
+3. Complete boilerplate templates for **Page Objects**, **Specs**, **Actions**, **Steps**, **Fixtures**, and **Suite Hooks**.
+4. `.gitignore` ensuring `.testspectra/`, `dist/`, and `node_modules/` are not committed.
+5. All scaffolded templates pass TypeScript checking with **0 errors**.
+
+  3. Updates TypeScript triple-slash references if necessary.
+
+### B. Dependencies Location & Isolation (`node_modules`)
+- CLI isolates WebdriverIO & Appium dependencies into `./.testspectra/node_modules` (or uses root `node_modules` if a `package.json` is present).
+- Ensures user test projects don't need a manually managed `package.json` unless desired.
+
+---
+
+## 11. Custom Browser Commands & Fixture-Integrated Interceptor (`browser.intercept`)
+
+TestSpectra extends WebdriverIO's `browser` object with runtime custom commands bundled directly in `core/test-runner` execution preparer (keeping user `wdio.conf.ts` completely clean).
+
+### A. Feature Capabilities
+- **`browser.intercept(path, method, fixture?, options?)`**: Strongly-typed API mock interceptor.
+- **Fixture Object Integration:** Accepts `Fixture.sampleJson` asset references directly, auto-loading and parsing files from `fixtures/`.
+- **Dynamic `mock.respondWith()`**: Allows updating mock responses on the fly within individual test steps.
+
+### B. Type Declarations (`cli/src/types/webdriverio.d.ts`)
+```typescript
+declare global {
+  namespace WebdriverIO {
+    export interface InterceptFixtureOptions {
+      statusCode?: number;
+      headers?: Record<string, string>;
+    }
+
+    export interface InterceptFixtureObject<TData = unknown> {
+      statusCode?: number;
+      body: TData;
+      headers?: Record<string, string>;
+    }
+
+    export type InterceptInput<TData = unknown> =
+      | InterceptFixtureObject<TData>
+      | TData
+      | string;
+
+    interface Mock {
+      /**
+       * Dynamically set or change the fixture response for this mock instance.
+       * Supports Fixture paths, `{ statusCode, body, headers }` objects, or raw payloads.
+       */
+      respondWith<TData = unknown>(
+        fixture: InterceptInput<TData>,
+        options?: InterceptFixtureOptions,
+      ): Promise<void>;
+    }
+
+    interface Browser {
+      /**
+       * Clean & strongly-typed API interceptor for WebdriverIO.
+       * Automatically resolves relative path against browser.options.baseUrl.
+       * Integrated directly with TestSpectra Fixtures.
+       */
+      intercept<TData = unknown>(
+        path: string,
+        method: 'GET' | 'POST' | 'PUT' | 'DELETE' | 'PATCH',
+        fixture?: InterceptInput<TData>,
+        options?: InterceptFixtureOptions,
+      ): Promise<Mock>;
+    }
+  }
+}
+```
+
+### C. Usage Example in Test Files
+```typescript
+test('intercept user API using TestSpectra Fixtures', async () => {
+  // Pass Fixture asset directly
+  await browser.intercept('/api/users', 'GET', Fixture.usersListJson);
+
+  // Pass Fixture object with custom status code
+  await browser.intercept('/api/login', 'POST', {
+    statusCode: 401,
+    body: { error: 'Invalid credentials' }
+  });
+
+  // Dynamic response update
+  const userMock = await browser.intercept('/api/profile', 'GET');
+  await userMock.respondWith(Fixture.adminProfileJson, { statusCode: 200 });
+});
+```
+
+---
+
+### C. Test Output & Reports (Real-Time Stdout + Local JSON Export)
+For local CLI runs, test execution provides real-time feedback and JSON persistence:
+- **Terminal Stdout:** Real-time colored stdout stream of step `TestLog` entries.
+- **Local JSON Output:** Saves complete `TestRunResult` payload (`status`, `duration`, `logs`, CDP `networkResources`) to `./.testspectra/reports/result.json` (or custom path via `--output <path>`).

package/README.md

@@ -0,0 +1,167 @@
+# @testspectra/cli — Architecture & Implementation
+
+The **TestSpectra CLI** (`spectra` / `testspectra`) is the command-line orchestrator and developer tooling layer for the TestSpectra testing framework. It enables unified multi-platform test authoring (Web, Android, iOS), zero-import ambient typing, dynamic configuration, and high-performance native test execution powered by the Rust core runner.
+
+---
+
+## 1. Core Architecture Overview
+
+```
+                          ┌──────────────────────────┐
+                          │    User Test Project     │
+                          │ (Zero-Import TypeScript) │
+                          └─────────────┬────────────┘
+                                        │
+                 ┌──────────────────────┴──────────────────────┐
+                 │                                             │
+                 ▼                                             ▼
+     ┌──────────────────────┐                     ┌────────────────────────┐
+     │  spectra watch / run │                     │ Solution TSConfigs     │
+     │  (CLI Orchestration) │                     │ (tsconfig.*.json)      │
+     └───────────┬──────────┘                     └────────────┬───────────┘
+                 │                                             │
+                 │ 1. Generates Ambient .d.ts                  │ 2. Isolated Platform
+                 │    in .testspectra/types/                   │    Type Checking
+                 ▼                                             ▼
+     ┌──────────────────────┐                     ┌────────────────────────┐
+     │  Core Test Runner    │                     │  Standard IDE & tsc    │
+     │  (Rust Native Bin)   │                     │  (VS Code, Cursor, CI) │
+     └──────────────────────┘                     └────────────────────────┘
+```
+
+---
+
+## 2. Key Architectural Pillars
+
+### A. Zero-Import Multi-Platform Authoring
+TestSpectra allows developers to write clean, boilerplate-free test specs, steps, actions, and page objects without manual `import` statements for globals or framework entities:
+- **Page Objects**: `LoginPage.login(...)` resolves automatically based on target platform.
+- **Actions**: `Spectra.verifyOtp(...)` provides typed action access.
+- **Steps**: `Step.loginUser(...)` exposes shared business step flows.
+- **Fixtures**: `Fixture.userData` provides typed, platform-agnostic test fixture access.
+- **WebdriverIO Globals**: `$`, `$$`, `browser`, `expect` are available globally across all platforms.
+
+### B. Platform Hierarchy & Resolution
+Entities are structured with hierarchical platform stems:
+```
+page-objects/
+  └── LoginPage/
+        ├── web.ts          # Used for Web
+        └── mobile.ts       # Fallback for Android and iOS
+
+specs/
+  └── TC-LOGIN-01/
+        ├── web.test.ts     # Web spec
+        ├── android.test.ts # Android spec
+        └── ios.test.ts     # iOS spec
+```
+
+Resolution order:
+- **`web`**: `web` → `common`
+- **`android`**: `android` → `mobile` → `common`
+- **`ios`**: `ios` → `mobile` → `common`
+- **`mobile`**: `mobile` → `common`
+- **`common`**: `common`
+
+### C. Solution-Style TypeScript Configuration (`tsconfig.json`)
+To avoid ambient type clashes between platforms (such as different method signatures across Web and Mobile Page Objects), TestSpectra uses standard TypeScript **Project References**:
+- **`tsconfig.json`**: Root project reference orchestrator pointing to platform configs.
+- **`tsconfig.web.json`**: Scoped exclusively to Web files and `.testspectra/types/web.d.ts`.
+- **`tsconfig.android.json`**: Scoped exclusively to Android files and `.testspectra/types/android.d.ts`.
+- **`tsconfig.ios.json`**: Scoped exclusively to iOS files and `.testspectra/types/ios.d.ts`.
+- **`fixtures.d.ts`**: Single platform-agnostic declaration file referenced by all platform declarations.
+
+Project verification is executed with standard `tsc`:
+```bash
+tsc -b
+```
+
+### D. Typed Configuration with `defineConfig`
+Configuration is strongly typed with full JSDoc documentation via `spectra.config.ts`:
+```typescript
+import { defineConfig } from "@testspectra/cli";
+
+export default defineConfig({
+  webConfig: {
+    baseUrl: "https://the-internet.herokuapp.com",
+    headlessMode: true,
+  },
+  browsers: [
+    { id: "chrome-desktop", type: "chrome" },
+  ],
+  androidConfig: {
+    platformName: "Android",
+    automationName: "UiAutomator2",
+  },
+});
+```
+
+---
+
+## 3. CLI Commands
+
+| Command | Description |
+| :--- | :--- |
+| `spectra init` | Scaffolds a complete multi-platform project from scratch with tsconfigs, specs, page objects, actions, steps, and fixtures. |
+| `spectra watch` | Starts a file-system watcher that regenerates `.testspectra/types/` ambient declarations on changes in debounced mode. |
+| `spectra run` | Generates declaration types and invokes the native Rust test runner to execute the test suite. |
+
+---
+
+## 4. Directory Structure of a TestSpectra Project
+
+```
+├── spectra.config.ts            # Central typed project configuration
+├── package.json                 # Scripts & dependencies
+├── tsconfig.json                # Root solution references
+├── tsconfig.web.json            # Web platform TypeScript scope
+├── tsconfig.android.json        # Android platform TypeScript scope
+├── tsconfig.ios.json            # iOS platform TypeScript scope
+├── page-objects/                # Page Object Model folders
+│   └── LoginPage/
+│         ├── web.ts
+│         └── mobile.ts
+├── actions/                     # Reusable atomic actions
+│   └── verifyOtp/
+│         ├── web.action.ts
+│         └── mobile.action.ts
+├── steps/                       # High-level business flows
+│   └── loginUser/
+│         ├── web.step.ts
+│         └── mobile.step.ts
+├── hooks/                       # Suite lifecycle hooks
+│   └── default/
+│         ├── before.web.hook.ts
+│         ├── before.android.hook.ts
+│         └── before.ios.hook.ts
+├── specs/                       # Standalone zero-import test cases
+│   └── TC-LOGIN-01/
+│         ├── web.test.ts
+│         ├── android.test.ts
+│         └── ios.test.ts
+├── fixtures/                    # Platform-agnostic test data
+│   └── userData.json
+└── .testspectra/                # Auto-generated ambient typings
+    └── types/
+          ├── fixtures.d.ts
+          ├── web.d.ts
+          ├── android.d.ts
+          ├── ios.d.ts
+          ├── mobile.d.ts
+          └── common.d.ts
+```
+
+---
+
+## 5. Development & Verification
+
+To verify the CLI and example app:
+```bash
+# Build CLI
+pnpm --filter @testspectra/cli build
+
+# Initialize and verify example app
+cd apps/example-app
+../../cli/bin/spectra.js init
+npx tsc -b tsconfig.json
+```

package/bin/spectra.js

@@ -0,0 +1,7 @@
+#!/usr/bin/env node
+import { runCli } from "../dist/index.js";
+
+runCli().catch((err) => {
+  console.error(err);
+  process.exit(1);
+});

package/dist/commands/devices.d.ts

@@ -0,0 +1,3 @@
+export declare function devicesCommand(options: {
+    target?: "android" | "ios" | "web" | "all";
+}): Promise<void>;

package/dist/commands/devices.js

@@ -0,0 +1,37 @@
+import { execSync } from "child_process";
+export async function devicesCommand(options) {
+    const target = options.target || "all";
+    console.log(`\x1b[36m[TestSpectra Devices]\x1b[0m Listing connected test targets (scope: ${target})...\n`);
+    if (target === "all" || target === "android") {
+        console.log("\x1b[1mAndroid Devices (ADB):\x1b[0m");
+        try {
+            const adbOutput = execSync("adb devices -l", { stdio: "pipe" }).toString();
+            const lines = adbOutput.split("\n").slice(1);
+            let found = false;
+            for (const line of lines) {
+                if (line.trim()) {
+                    found = true;
+                    console.log(`  \x1b[32m•\x1b[0m ${line.trim()}`);
+                }
+            }
+            if (!found) {
+                console.log("  \x1b[90mNo Android devices/emulators connected via ADB.\x1b[0m");
+            }
+        }
+        catch {
+            console.log("  \x1b[31mADB command failed or platform-tools not in PATH.\x1b[0m");
+        }
+    }
+    if (target === "all" || target === "web") {
+        console.log("\n\x1b[1mWeb Browsers:\x1b[0m");
+        try {
+            const chromeVer = execSync(process.platform === "darwin"
+                ? '"/Applications/Google Chrome.app/Contents/MacOS/Google Chrome" --version'
+                : "google-chrome --version", { stdio: "pipe" }).toString().trim();
+            console.log(`  \x1b[32m•\x1b[0m Chrome: ${chromeVer}`);
+        }
+        catch {
+            console.log("  \x1b[90m• Chrome: Not installed\x1b[0m");
+        }
+    }
+}

package/dist/commands/doctor.d.ts

@@ -0,0 +1,3 @@
+export declare function doctorCommand(options: {
+    fix?: boolean;
+}): Promise<void>;

package/dist/commands/doctor.js

@@ -0,0 +1,54 @@
+import { execSync } from "child_process";
+export async function doctorCommand(options) {
+    console.log("\x1b[36m[TestSpectra Doctor]\x1b[0m Checking development and runtime dependencies...\n");
+    const checks = [
+        {
+            name: "Node.js",
+            command: "node -v",
+            required: true,
+        },
+        {
+            name: "Bun",
+            command: "bun -v",
+            required: false,
+        },
+        {
+            name: "ADB (Android Debug Bridge)",
+            command: "adb version",
+            required: false,
+        },
+        {
+            name: "Java JDK",
+            command: "java -version",
+            required: false,
+        },
+        {
+            name: "Google Chrome",
+            command: process.platform === "darwin"
+                ? '"/Applications/Google Chrome.app/Contents/MacOS/Google Chrome" --version'
+                : "google-chrome --version",
+            required: false,
+        },
+    ];
+    let missingCount = 0;
+    for (const check of checks) {
+        try {
+            const out = execSync(check.command, { stdio: "pipe" }).toString().trim();
+            const firstLine = out.split("\n")[0];
+            console.log(` \x1b[32m✓\x1b[0m ${check.name.padEnd(30)} \x1b[90m(${firstLine})\x1b[0m`);
+        }
+        catch {
+            console.log(` \x1b[31m✗\x1b[0m ${check.name.padEnd(30)} \x1b[31m(Not found)\x1b[0m`);
+            if (check.required) {
+                missingCount++;
+            }
+        }
+    }
+    console.log("\n------------------------------------------------------------");
+    if (missingCount === 0) {
+        console.log("\x1b[32m[Doctor]\x1b[0m System ready for local test execution!");
+    }
+    else {
+        console.log(`\x1b[33m[Doctor]\x1b[0m Found ${missingCount} missing required dependencies.`);
+    }
+}

package/dist/commands/init.d.ts

@@ -0,0 +1,3 @@
+export declare function initCommand(options: {
+    force?: boolean;
+}): Promise<void>;