@testspectra/cli 1.0.3 → 1.0.5

package/README.md

@@ -16,7 +16,7 @@ The **TestSpectra CLI** (`spectra` / `testspectra`) is the command-line orchestr
                  │                                             │
                  ▼                                             ▼
      ┌──────────────────────┐                     ┌────────────────────────┐
-     │  spectra watch / run │                     │ Solution TSConfigs     │
+     │  spectra run / CLI   │                     │ Solution TSConfigs     │
      │  (CLI Orchestration) │                     │ (tsconfig.*.json)      │
      └───────────┬──────────┘                     └────────────┬───────────┘
                  │                                             │
@@ -63,14 +63,19 @@ Resolution order:
 - **`mobile`**: `mobile` → `common`
 - **`common`**: `common`
 
-### C. Solution-Style TypeScript Configuration (`tsconfig.json`)
+### C. 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 pointing to platform configs.
+- **`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.
 
+#### 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
@@ -103,8 +108,9 @@ export default defineConfig({
 | 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. |
+| `spectra doctor` | Verifies local environment prerequisites (ADB, Java, Chrome, Bun, Node). |
+| `spectra devices` | Lists connected Android/iOS devices and local browsers. |
 
 ---
 

package/dist/commands/init.js

@@ -98,7 +98,6 @@ export default defineConfig({
         private: true,
         type: "module",
         scripts: {
-            dev: "spectra watch",
             test: "spectra run",
             "type-check": "tsc -b",
         },
@@ -118,7 +117,6 @@ export default defineConfig({
                 ...existing,
                 scripts: {
                     ...(existing.scripts || {}),
-                    dev: existing.scripts?.dev || "spectra watch",
                     test: existing.scripts?.test || "spectra run",
                     "type-check": existing.scripts?.["type-check"] || "tsc -b",
                 },
@@ -144,13 +142,16 @@ export default defineConfig({
         fs.writeFileSync(gitignorePath, gitignoreContent, "utf-8");
         console.log(`\x1b[32m[TestSpectra]\x1b[0m Created .gitignore`);
     }
-    // 4. Create platform tsconfigs with Solution-Style Project References
+    // 4. Create platform tsconfigs with Solution-Style Project References & TS Plugin
     const tsconfigRoot = {
         compilerOptions: {
             target: "ES2022",
             module: "NodeNext",
             moduleResolution: "NodeNext",
             types: ["node", "@wdio/globals/types", "@wdio/mocha-framework"],
+            plugins: [
+                { name: "@testspectra/cli" }
+            ],
             skipLibCheck: true,
             strict: true,
             noEmit: true,

package/dist/index.d.ts

@@ -2,5 +2,6 @@ import { Command } from "commander";
 export * from "./config/schema.js";
 export * from "./config/loader.js";
 export * from "./types/generator.js";
+export { init as initTsPlugin, default as tsPlugin } from "./plugin.js";
 export declare function createCliProgram(): Command;
 export declare function runCli(args?: string[]): Promise<void>;

package/dist/index.js

@@ -3,16 +3,16 @@ import { devicesCommand } from "./commands/devices.js";
 import { doctorCommand } from "./commands/doctor.js";
 import { initCommand } from "./commands/init.js";
 import { runCommand } from "./commands/run.js";
-import { watchCommand } from "./commands/watch.js";
 export * from "./config/schema.js";
 export * from "./config/loader.js";
 export * from "./types/generator.js";
+export { init as initTsPlugin, default as tsPlugin } from "./plugin.js";
 export function createCliProgram() {
     const program = new Command();
     program
         .name("spectra")
         .description("TestSpectra Zero-Config Cross-Platform Test Runner CLI")
-        .version("2.0.0");
+        .version("1.0.0");
     program
         .command("init")
         .description("Initialize testspectra.config.json and project directories")
@@ -38,11 +38,6 @@ export function createCliProgram() {
         .option("-w, --workdir <dir>", "Custom app data / temp workdir")
         .option("-o, --output <path>", "Custom test report JSON output path")
         .action(runCommand);
-    program
-        .command("watch")
-        .description("Watch page-objects, actions, steps, fixtures and auto-regenerate ambient types")
-        .option("--once", "Generate ambient types once and exit")
-        .action(watchCommand);
     return program;
 }
 export async function runCli(args = process.argv) {

package/dist/plugin.d.ts

@@ -0,0 +1,15 @@
+import type ts from "typescript";
+/**
+ * TypeScript Language Service Plugin Factory for TestSpectra.
+ * Runs silently inside TSServer (VS Code, Cursor, WebStorm, Neovim, etc.).
+ *
+ * It generates and refreshes `.testspectra/types/` ambient declarations
+ * automatically in the background whenever the project is opened or files change.
+ */
+declare function init(modules: {
+    typescript: typeof ts;
+}): {
+    create: (info: ts.server.PluginCreateInfo) => ts.LanguageService;
+};
+export default init;
+export { init };

package/dist/plugin.js

@@ -0,0 +1,65 @@
+import { TypeGenerator } from "./types/generator.js";
+/**
+ * TypeScript Language Service Plugin Factory for TestSpectra.
+ * Runs silently inside TSServer (VS Code, Cursor, WebStorm, Neovim, etc.).
+ *
+ * It generates and refreshes `.testspectra/types/` ambient declarations
+ * automatically in the background whenever the project is opened or files change.
+ */
+function init(modules) {
+    const tsModule = modules.typescript;
+    function create(info) {
+        const project = info.project;
+        const projectDir = project.getCurrentDirectory();
+        // 1. Initial Generation on project load
+        try {
+            TypeGenerator.writeDeclarationFiles(projectDir);
+            info.project.projectService.logger.info(`[TestSpectra TS Plugin] Initialized ambient declarations in ${projectDir}`);
+        }
+        catch (err) {
+            info.project.projectService.logger.info(`[TestSpectra TS Plugin] Failed initial type generation: ${err?.message}`);
+        }
+        // 2. Watch for entity file changes inside TSServer
+        const watchedFolders = ["page-objects", "pageobjects", "actions", "steps", "fixtures", "hooks"];
+        // Debounce type regeneration
+        let debounceTimer = null;
+        const triggerRegeneration = (pathChanged) => {
+            if (debounceTimer)
+                clearTimeout(debounceTimer);
+            debounceTimer = setTimeout(() => {
+                try {
+                    TypeGenerator.writeDeclarationFiles(projectDir);
+                    info.project.projectService.logger.info(`[TestSpectra TS Plugin] Regenerated ambient declarations after change in ${pathChanged}`);
+                }
+                catch (err) {
+                    info.project.projectService.logger.info(`[TestSpectra TS Plugin] Error during regeneration: ${err?.message}`);
+                }
+            }, 200);
+        };
+        // 3. Proxy language service methods to detect file modifications / completions
+        const proxy = Object.create(null);
+        for (const k of Object.keys(info.languageService)) {
+            const x = info.languageService[k];
+            // @ts-ignore
+            proxy[k] = (...args) => x.apply(info.languageService, args);
+        }
+        // Intercept getCompletionsAtPosition to ensure fresh types
+        const originalGetCompletions = info.languageService.getCompletionsAtPosition;
+        proxy.getCompletionsAtPosition = (fileName, position, options, formattingSettings) => {
+            const isEntity = watchedFolders.some((f) => fileName.includes(f));
+            if (isEntity) {
+                triggerRegeneration(fileName);
+            }
+            return originalGetCompletions.apply(info.languageService, [
+                fileName,
+                position,
+                options,
+                formattingSettings,
+            ]);
+        };
+        return proxy;
+    }
+    return { create };
+}
+export default init;
+export { init };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@testspectra/cli",
-  "version": "1.0.3",
+  "version": "1.0.5",
   "description": "TestSpectra Zero-Config Cross-Platform Test Runner CLI",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",

package/src/commands/init.ts

@@ -103,7 +103,6 @@ export default defineConfig({
     private: true,
     type: "module",
     scripts: {
-      dev: "spectra watch",
       test: "spectra run",
       "type-check": "tsc -b",
     },
@@ -123,7 +122,6 @@ export default defineConfig({
         ...existing,
         scripts: {
           ...(existing.scripts || {}),
-          dev: existing.scripts?.dev || "spectra watch",
           test: existing.scripts?.test || "spectra run",
           "type-check": existing.scripts?.["type-check"] || "tsc -b",
         },
@@ -150,13 +148,16 @@ export default defineConfig({
     console.log(`\x1b[32m[TestSpectra]\x1b[0m Created .gitignore`);
   }
 
-  // 4. Create platform tsconfigs with Solution-Style Project References
+  // 4. Create platform tsconfigs with Solution-Style Project References & TS Plugin
   const tsconfigRoot = {
     compilerOptions: {
       target: "ES2022",
       module: "NodeNext",
       moduleResolution: "NodeNext",
       types: ["node", "@wdio/globals/types", "@wdio/mocha-framework"],
+      plugins: [
+        { name: "@testspectra/cli" }
+      ],
       skipLibCheck: true,
       strict: true,
       noEmit: true,

package/src/index.ts

@@ -3,11 +3,11 @@ import { devicesCommand } from "./commands/devices.js";
 import { doctorCommand } from "./commands/doctor.js";
 import { initCommand } from "./commands/init.js";
 import { runCommand } from "./commands/run.js";
-import { watchCommand } from "./commands/watch.js";
 
 export * from "./config/schema.js";
 export * from "./config/loader.js";
 export * from "./types/generator.js";
+export { init as initTsPlugin, default as tsPlugin } from "./plugin.js";
 
 export function createCliProgram() {
   const program = new Command();
@@ -15,7 +15,7 @@ export function createCliProgram() {
   program
     .name("spectra")
     .description("TestSpectra Zero-Config Cross-Platform Test Runner CLI")
-    .version("2.0.0");
+    .version("1.0.0");
 
   program
     .command("init")
@@ -46,12 +46,6 @@ export function createCliProgram() {
     .option("-o, --output <path>", "Custom test report JSON output path")
     .action(runCommand);
 
-  program
-    .command("watch")
-    .description("Watch page-objects, actions, steps, fixtures and auto-regenerate ambient types")
-    .option("--once", "Generate ambient types once and exit")
-    .action(watchCommand);
-
   return program;
 }
 

package/src/plugin.ts

@@ -0,0 +1,81 @@
+import type ts from "typescript";
+import { TypeGenerator } from "./types/generator.js";
+
+/**
+ * TypeScript Language Service Plugin Factory for TestSpectra.
+ * Runs silently inside TSServer (VS Code, Cursor, WebStorm, Neovim, etc.).
+ *
+ * It generates and refreshes `.testspectra/types/` ambient declarations
+ * automatically in the background whenever the project is opened or files change.
+ */
+function init(modules: { typescript: typeof ts }) {
+  const tsModule = modules.typescript;
+
+  function create(info: ts.server.PluginCreateInfo) {
+    const project = info.project;
+    const projectDir = project.getCurrentDirectory();
+
+    // 1. Initial Generation on project load
+    try {
+      TypeGenerator.writeDeclarationFiles(projectDir);
+      info.project.projectService.logger.info(
+        `[TestSpectra TS Plugin] Initialized ambient declarations in ${projectDir}`
+      );
+    } catch (err: any) {
+      info.project.projectService.logger.info(
+        `[TestSpectra TS Plugin] Failed initial type generation: ${err?.message}`
+      );
+    }
+
+    // 2. Watch for entity file changes inside TSServer
+    const watchedFolders = ["page-objects", "pageobjects", "actions", "steps", "fixtures", "hooks"];
+    
+    // Debounce type regeneration
+    let debounceTimer: NodeJS.Timeout | null = null;
+    const triggerRegeneration = (pathChanged: string) => {
+      if (debounceTimer) clearTimeout(debounceTimer);
+      debounceTimer = setTimeout(() => {
+        try {
+          TypeGenerator.writeDeclarationFiles(projectDir);
+          info.project.projectService.logger.info(
+            `[TestSpectra TS Plugin] Regenerated ambient declarations after change in ${pathChanged}`
+          );
+        } catch (err: any) {
+          info.project.projectService.logger.info(
+            `[TestSpectra TS Plugin] Error during regeneration: ${err?.message}`
+          );
+        }
+      }, 200);
+    };
+
+    // 3. Proxy language service methods to detect file modifications / completions
+    const proxy: ts.LanguageService = Object.create(null);
+    for (const k of Object.keys(info.languageService) as Array<keyof ts.LanguageService>) {
+      const x = info.languageService[k]!;
+      // @ts-ignore
+      proxy[k] = (...args: Array<{}>) => x.apply(info.languageService, args);
+    }
+
+    // Intercept getCompletionsAtPosition to ensure fresh types
+    const originalGetCompletions = info.languageService.getCompletionsAtPosition;
+    proxy.getCompletionsAtPosition = (fileName, position, options, formattingSettings) => {
+      const isEntity = watchedFolders.some((f) => fileName.includes(f));
+      if (isEntity) {
+        triggerRegeneration(fileName);
+      }
+      return originalGetCompletions.apply(info.languageService, [
+        fileName,
+        position,
+        options,
+        formattingSettings,
+      ]);
+    };
+
+    return proxy;
+  }
+
+  return { create };
+}
+
+export default init;
+export { init };

package/src/commands/watch.ts

@@ -1,34 +0,0 @@
-import fs from "fs";
-import path from "path";
-import { TypeGenerator } from "../types/generator.js";
-
-export function watchCommand(options: { once?: boolean } = {}) {
-  const cwd = process.cwd();
-
-  // Run initial generation
-  TypeGenerator.writeDeclarationFiles(cwd);
-  console.log(`\x1b[32m[TestSpectra]\x1b[0m Generated ambient types in .testspectra/types/`);
-
-  if (options.once) {
-    return;
-  }
-
-  console.log(`\x1b[34m[TestSpectra]\x1b[0m Watching for changes in page-objects/, actions/, steps/, fixtures/...`);
-
-  const watchDirs = ["page-objects", "pageobjects", "actions", "steps", "fixtures"];
-  let debounceTimeout: NodeJS.Timeout | null = null;
-
-  for (const dir of watchDirs) {
-    const fullPath = path.join(cwd, dir);
-    if (fs.existsSync(fullPath)) {
-      fs.watch(fullPath, { recursive: true }, (_eventType, filename) => {
-        if (!filename || filename.startsWith(".")) return;
-        if (debounceTimeout) clearTimeout(debounceTimeout);
-        debounceTimeout = setTimeout(() => {
-          TypeGenerator.writeDeclarationFiles(cwd);
-          console.log(`\x1b[32m[TestSpectra]\x1b[0m Updated ambient declarations (.testspectra/types/) due to ${filename}`);
-        }, 150);
-      });
-    }
-  }
-}