@testspectra/cli 1.0.70 → 1.1.0-rc.0

package/LICENSE.md

@@ -0,0 +1,48 @@
+# TestSpectra Commercial Software License Agreement
+
+Copyright (c) 2026 TestSpectra. All rights reserved.
+
+IMPORTANT NOTICE: This software is NOT open-source. Although distribution archives,
+npm packages, and editor extensions are publicly downloadable, installation,
+execution, and use of the Software are strictly conditioned upon obtaining a valid
+Commercial License or an authorized Evaluation/Trial License from TestSpectra.
+
+1. GRANT OF LICENSE
+   Subject to payment of applicable license fees or an active authorized evaluation
+   period, TestSpectra grants you a non-exclusive, non-transferable, revocable license
+   to install and execute the Software solely for authoring, debugging, and executing
+   automated software tests.
+
+2. LICENSE ACTIVATION & ENFORCEMENT
+   - Use of the Software requires activation via a valid License Key, authorized CI token,
+     or active TestSpectra Cloud account.
+   - Any attempt to circumvent, disable, modify, reverse engineer, or tamper with the
+     license verification mechanisms, cryptographic signatures, or binary checks is
+     a material breach of this Agreement and automatically terminates your license.
+
+3. RESTRICTIONS
+   You shall not, and shall not permit any third party to:
+   - Decompile, disassemble, reverse engineer, or derive source code from the binaries,
+     compiled scripts, or libraries of the Software.
+   - Sublicense, sell, rent, lease, distribute, or host the Software as a service for third parties.
+   - Re-brand, white-label, or package the Software or any of its components as part of a
+     competing commercial QA, testing, or developer tooling product.
+   - Modify, alter, or remove any proprietary notices, copyright labels, or license headers.
+
+4. INTELLECTUAL PROPERTY
+   The Software, including its source code, architecture, Rust core engine, algorithms,
+   matchers, extensions, interfaces, and documentation, represents valuable intellectual
+   property and trade secrets of TestSpectra.
+
+5. TERMINATION
+   This license is effective until terminated. Your rights under this license will terminate
+   automatically without notice if you fail to comply with any of its terms, or upon expiration
+   of your active subscription or trial term. Upon termination, you must cease all use of
+   the Software and delete all copies in your possession.
+
+6. DISCLAIMER OF WARRANTY & LIMITATION OF LIABILITY
+   THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED,
+   INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR
+   PURPOSE, AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE
+   FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
+   ARISING FROM THE USE OF OR INABILITY TO USE THE SOFTWARE.

package/README.md

@@ -1,295 +1,61 @@
-# @testspectra/cli — Architecture & Implementation
+# @testspectra/cli
 
-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.
+Command-line interface and development tooling layer for the TestSpectra testing framework.
 
 ---
 
-## 1. Core Architecture Overview
+## 🛠️ Development Guide
 
-```
-                          ┌──────────────────────────┐
-                          │    User Test Project     │
-                          │ (Zero-Import TypeScript) │
-                          └─────────────┬────────────┘
-                                        │
-                 ┌──────────────────────┴──────────────────────┐
-                 │                                             │
-                 ▼                                             ▼
-     ┌──────────────────────┐                     ┌────────────────────────┐
-     │  spectra run / CLI   │                     │ 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(...)` and getters `LoginPage.flashAlert` resolve automatically based on target platform.
-- **Actions (`Spectra.*`)**: Built-in 16 atomic actions (`Spectra.navigate`, `Spectra.click`, `Spectra.type`, `Spectra.select`, `Spectra.scroll`, `Spectra.swipe`, `Spectra.wait`, etc.) matching TestSpectra database schema, merged seamlessly with user-defined custom actions (`Spectra.verifyOtp`).
-- **Direct Callable Assertions**: Instant, auto-completed assertion methods available directly on `WebdriverIO.Element`, `ChainablePromiseElement`, and `browser` (`shouldBeVisible()`, `shouldContainText()`, `shouldHaveValue()`, `shouldHaveUrl()`, etc.).
-- **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. Built-in Regular Actions & Direct Callable Assertions
-
-TestSpectra provides a bundled, 100% database-schema-compatible library of built-in atomic actions and direct element assertions:
-
-#### 1. Direct Callable Element Assertions (`should*`)
-All Page Object elements and locators support direct callable assertions without extra nesting:
-```typescript
-it("should authenticate user using Page Objects and assertions", async () => {
-  // Navigation & high-level business flows
-  await LoginPage.open();
-  await Step.loginUser("tomsmith", "SuperSecretPassword!");
-
-  // Direct assertions on Page Object elements
-  await LoginPage.flashAlert.shouldBeVisible();
-  await LoginPage.flashAlert.shouldContainText("You logged into a secure area!");
-  await LoginPage.usernameInput.shouldHaveValue("tomsmith");
-});
-```
+### Prerequisites
 
-#### Available Assertion Methods:
-| Kategori | Method Callable |
-| :--- | :--- |
-| **Visibility** | `await el.shouldBeVisible()` / `await el.shouldNotBeVisible()` |
-| **DOM Existence** | `await el.shouldExist()` / `await el.shouldNotExist()` |
-| **Element State** | `await el.shouldBeEnabled()` / `await el.shouldBeDisabled()` / `await el.shouldBeSelected()` / `await el.shouldBeChecked()` |
-| **Text Matching** | `await el.shouldHaveText(expected)` / `await el.shouldContainText(expected)` |
-| **Input Value** | `await el.shouldHaveValue(expected)` / `await el.shouldContainValue(expected)` |
-| **CSS Class** | `await el.shouldHaveClass(className)` |
-| **Attribute** | `await el.shouldHaveAttribute(name, val?)` |
-| **Browser URL / Title**| `await browser.shouldHaveUrl(url)` / `await browser.shouldHaveTitle(title)` |
+- [Node.js](https://nodejs.org/) (>= 18.0.0)
+- [pnpm](https://pnpm.io/) (>= 8.0.0)
+- [Bun](https://bun.sh/) (>= 1.0.0)
 
-#### 2. Built-in Atomic Actions (`Spectra.*`)
-Available inside Page Objects, Actions, and Steps for raw element manipulation:
-```typescript
-// Navigation
-await Spectra.navigate("https://example.com/login");
-await Spectra.back();
-await Spectra.refresh();
+### Getting Started
 
-// Interactions with Page Object getters or locators
-await Spectra.type(this.usernameInput, "tomsmith");
-await Spectra.click(this.submitButton);
-await Spectra.select(this.countryDropdown, "ID");
-await Spectra.clear(this.searchField);
-await Spectra.pressKey("Enter");
+```bash
+# Install workspace dependencies
+pnpm install
 
-// Gestures & Timing
-await Spectra.scroll({ direction: "down", pixels: 300 });
-await Spectra.swipe({ direction: "up", distance: 500 });
-await Spectra.wait(1000);
-await Spectra.waitForElement(this.flashAlert, 5000);
-```
+# Build @testspectra/cli
+pnpm --filter @testspectra/cli build
 
-### C. 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
+# Run type check
+pnpm --filter @testspectra/cli type-check
 
-specs/
-  └── TC-LOGIN-01/
-        ├── web.test.ts     # Web spec
-        ├── android.test.ts # Android spec
-        └── ios.test.ts     # iOS spec
+# Run unit tests
+pnpm --filter @testspectra/cli test
 ```
 
-Resolution order:
-- **`web`**: `web` → `common`
-- **`android`**: `android` → `mobile` → `common`
-- **`ios`**: `ios` → `mobile` → `common`
-- **`mobile`**: `mobile` → `common`
-- **`common`**: `common`
-
-### D. Solution-Style TypeScript Configuration & Language Service Plugin
-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 with `@testspectra/cli` plugin registered.
-- **`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.
+### Development Watch Mode
 
-#### Zero-Terminal Background Type Generation (TS Plugin)
-With the built-in TypeScript Server plugin (`@testspectra/cli`), background type generation is completely automatic:
-- When you open the project in **VS Code**, **Cursor**, or **WebStorm**, the IDE's TypeScript Server automatically boots the `@testspectra/cli` Language Service plugin.
-- The plugin generates and updates `.testspectra/types/` ambient declarations in the background in real-time as you author Page Objects, Actions, Steps, and Fixtures.
-
-Project verification is executed with standard `tsc`:
 ```bash
-tsc -b
-```
-
-### E. 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",
-  },
-});
+# Watch and rebuild on file changes
+pnpm --filter @testspectra/cli dev
 ```
 
 ---
 
-## 3. CLI Commands
+## 💻 CLI Commands Summary
 
-| Command | Description |
-| :--- | :--- |
-| `spectra init` / `npx @testspectra/cli init` | Interactive project setup. Auto-detects standalone or Nx Monorepos, discovers workspace packages from `pnpm-workspace.yaml`, and scaffolds centralized/distributed configurations. |
-| `spectra add [module]` | Adds a new TestSpectra E2E testing module to an existing workspace project or creates a new feature testing suite. |
-| `spectra run [spec]` | Automatically updates ambient declarations and invokes the native Rust test runner to execute the test suite. |
-| `spectra doctor` | Verifies local environment prerequisites (ADB, Java, Chrome, Bun, Node). |
-| `spectra devices` | Lists connected Android/iOS devices and local browsers. |
+| Command           | Usage                                       | Description                                                             |
+| :---------------- | :------------------------------------------ | :---------------------------------------------------------------------- |
+| `spectra init`    | `spectra init [-t default\|nx]`             | Scaffold a new TestSpectra project or monorepo workspace                |
+| `spectra run`     | `spectra run [path] [-t web\|android\|ios]` | Execute test specs or suites                                            |
+| `spectra watch`   | `spectra watch [-w <dir>]`                  | Watch workspace and generate `.testspectra/types/` declarations         |
+| `spectra doctor`  | `spectra doctor [--fix] [--json]`           | Diagnose local environment prerequisites (ADB, Java, Chrome, Bun, Node) |
+| `spectra demo`    | `spectra demo [-p <port>]`                  | Launch built-in demo web application                                    |
+| `spectra devices` | `spectra devices [-t <target>]`             | List connected Android/iOS devices and browsers                         |
+| `spectra add`     | `spectra add [module]`                      | Add a new testing module to an existing workspace                       |
+| `spectra update`  | `spectra update [--check]`                  | Check and update TestSpectra packages                                   |
 
 ---
 
-## 4. Standalone Project Directory Structure
+## 📚 Documentation & Specifications
 
-```
-├── 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
-│   └── PlaygroundPage/
-│         ├── web.ts
-│         └── mobile.ts
-├── support/
-│   ├── actions/                 # Reusable atomic actions
-│   │   └── fillCredentials/
-│   │         ├── web.action.ts
-│   │         └── mobile.action.ts
-│   └── steps/                   # High-level business flows
-│       └── verifyPlaygroundState/
-│             ├── web.step.ts
-│             └── mobile.step.ts
-├── global-hooks/                # Global lifecycle hooks
-│   └── before/
-│         └── web.hook.ts
-├── specs/                       # Layered zero-import test cases
-│   └── Playground/
-│         └── TC-0001-form-controls/
-│               ├── web.test.ts
-│               └── mobile.test.ts
-├── fixtures/                    # Platform-agnostic test data
-│   └── playgroundData.json
-├── .testspectra/                # Auto-generated ambient typings & cache
-│     └── types/
-│           ├── fixtures.d.ts
-│           ├── web.d.ts
-│           ├── android.d.ts
-│           ├── ios.d.ts
-│           ├── mobile.d.ts
-│           └── common.d.ts
-```
-
----
-
-## 5. Enterprise Monorepo Architecture (Nx & PNPM Workspace)
-
-TestSpectra features an enterprise-grade architecture for large monorepos: **"Centralized Configuration, Distributed Implementation"**.
-
-```
-                  ┌───────────────────────────────────────────────────────────┐
-                  │                 Root Monorepo Directory                   │
-                  │                                                           │
-                  │  ├── spectra.config.ts       (Central Execution Config)   │
-                  │  ├── .testspectra/           (Central Cache, AppData, Log)│
-                  │  ├── pnpm-workspace.yaml     (Workspace Definition)       │
-                  │  ├── nx.json                 (Nx Target & Caching Rules)  │
-                  │  └── tsconfig.json           (Solution References)        │
-                  └─────────────────────────────┬─────────────────────────────┘
-                                                │
-                 ┌──────────────────────────────┴──────────────────────────────┐
-                 ▼                                                             ▼
-  ┌───────────────────────────────┐                             ┌───────────────────────────────┐
-  │   shared/testing/ (Library)   │                             │    packages/playground/e2e/   │
-  ├───────────────────────────────┤                             ├───────────────────────────────┤
-  │ - Shared Page Objects         │ ◄─── Auto-Scanned Globals ──│ - Feature Specs (specs/)      │
-  │ - Shared Steps (verifyState)  │     (100% Zero-Import!)     │ - Feature Page Objects (POMs) │
-  │ - Shared Actions (fillCreds)  │                             │ - project.json (Nx Target)    │
-  │ - Shared Fixtures (playData)  │                             │ - tsconfig.web/android/ios    │
-  └───────────────────────────────┘                             └───────────────────────────────┘
-```
-
-### Key Pillars of Monorepo Integration:
-
-1. **Interactive Workspace Auto-Discovery (`spectra init`)**:
-   - Parses `pnpm-workspace.yaml` (e.g. `packages/*`, `modules/**`).
-   - Scans sub-directories for existing `project.json` or `package.json`.
-   - Prompts the user with an interactive multi-select checkbox to choose which features will receive E2E testing.
-   - Prompts for customizable E2E folder names (e.g. `e2e`, `test/e2e`) and the shared testing library path (`shared/testing`).
+For comprehensive feature guides and technical specifications, refer to:
 
-2. **Centralized Configuration (`spectra.config.ts`) & App Data (`.testspectra/`)**:
-   - `spectra.config.ts` lives exclusively at the root of the monorepo.
-   - CLI test runs executed from sub-feature folders automatically traverse up to find the root configuration.
-   - Driver caches, binaries, and logs reside in `<root>/.testspectra/`, preventing repository clutter across individual feature folders.
-
-3. **Global Zero-Import Consumption of Shared Library**:
-   - Entities placed inside `shared/testing/page-objects/`, `shared/testing/support/steps/`, `shared/testing/support/actions/`, and `shared/testing/fixtures/` are automatically aggregated into ambient declarations.
-   - Feature test specs consume shared Page Objects (`PlaygroundPage.open()`), steps (`Step.verifyPlaygroundState()`), actions (`Spectra.fillCredentials()`), and fixtures (`Fixture.playgroundData`) **without a single line of `import` statement**.
-
-4. **Nx Target Execution & Affected Caching**:
-   - Each feature E2E folder includes an Nx `project.json`:
-     ```json
-     {
-       "name": "playground-e2e",
-       "targets": {
-         "e2e": {
-           "executor": "nx:run-commands",
-           "options": { "command": "spectra run", "cwd": "packages/playground/e2e" },
-           "configurations": {
-             "android": { "command": "spectra run --target android" },
-             "ios": { "command": "spectra run --target ios" },
-             "headless": { "command": "spectra run --headless" }
-           }
-         }
-       }
-     }
-     ```
-   - Running `nx run-many -t e2e` executes all feature test suites in parallel.
-5. **Automatic Architecture Documentation (`ARCHITECTURE.md`)**:
-   - Every `spectra init` run produces a comprehensive, project-tailored `ARCHITECTURE.md` file in the root workspace.
-   - It documents the generated file map, exact distributed feature paths, shared library resolution, and zero-import mechanics for onboarding engineers.
-
----
-
-## 6. Development & Verification
-
-To verify the CLI and example app:
-```bash
-# Build CLI
-pnpm --filter @testspectra/cli build
-
-# Test interactive scaffolding
-npx @testspectra/cli init
-pnpm type-check
-```
+- **Feature Guides**: [`docs/v2/features/`](../docs/v2/features/)
+- **CLI Technical Specifications**: [`docs/v2/cli/`](../docs/v2/cli/)
+- **Master v2 Architecture**: [`docs/v2/README.md`](../docs/v2/README.md)

package/bin/spectra.js

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