@testspectra/cli 1.1.7 → 1.1.8-rc.10

package/dist/generator/type-generator.d.ts

@@ -9,8 +9,11 @@ export interface EntityScope {
  * Discovers all feature directories and shared library directories.
  * Standard discovery hierarchy:
  * 1. Nx / Monorepo Project Descriptors (`project.json`):
- *    - projectType: "library" OR tags: ["type:shared", "type:library", "scope:shared"] => Shared Library Scope (isShared: true)
- *    - projectType: "application" OR tags: ["type:e2e", "type:app"] => Feature Scope (isShared: false)
+ *    - tags: ["testspectra:shared"] => Shared Library Scope (isShared: true)
+ *    - tags: ["testspectra:e2e"] or ["testspectra:scope:<name>"] => Feature Scope (isShared: false)
+ *    - Generic Nx libraries/apps without testspectra tags are not TestSpectra scopes and recursion
+ *      continues into their subdirectories so nested e2e projects (e.g. `packages/features/auth/e2e`)
+ *      are discovered.
  * 2. Explicit User Configuration (`tsconfig.spectra.shared.json`):
  *    - Custom include path for shared testing utilities
  * 3. Dynamic Workspace Filesystem Discovery (Fallback for non-Nx / custom layouts):
@@ -18,11 +21,23 @@ export interface EntityScope {
  *    - Directory with page-objects/support/fixtures and NO specs => Shared Scope
  */
 export declare function discoverEntityScopes(cwd: string): EntityScope[];
+/**
+ * Detects a component-testing project (`@testspectra/react`'s Vitest browser-mode runner), via
+ * the same signal `cli/src/commands/test.ts` uses to gate `spectra test` itself. Used to augment
+ * the generated `Spectra` ambient type with `.mount()`, which only exists in that runtime.
+ */
+export declare function isComponentTestingProject(cwd: string): boolean;
 export declare class TypeGenerator {
     /**
      * Main entry point to generate all ambient type declarations.
      */
     static generateAll(cwd: string): void;
+    /**
+     * Reloads `spectra.config.ts` and refreshes `.testspectra/types/env.d.ts` with the current
+     * `executionConfig.environmentVariables`. Separate from `writeDeclarationFiles`/`generateAll`
+     * (which must stay synchronous) because reading the config file is unavoidably async.
+     */
+    static syncEnvDeclaration(cwd: string): Promise<void>;
     /**
      * Discovers all feature directories and shared library directories.
      * Returns a map of scope -> base directory
@@ -30,7 +45,18 @@ export declare class TypeGenerator {
     static getEntityScopes(cwd: string): EntityScope[];
     static getPageObjectsDirsForScope(scopeDir: string, sharedDir?: string): string[];
     static getEntityDirsForScope(entityType: 'actions' | 'steps' | 'fixtures', scopeDir: string, sharedDir?: string): string[];
-    static generateDeclarationsForScope(cwd: string, outputTypesDir: string, scopeDir: string, sharedDir?: string): Record<PlatformTarget, string>;
+    static generateDeclarationsForScope(cwd: string, outputTypesDir: string, scopeDir: string, sharedDir?: string, rootTypesDir?: string): Record<PlatformTarget, string>;
     static generateFixturesDeclarationForScope(cwd: string, outputTypesDir: string, scopeDir: string, sharedDir?: string): string;
+    /**
+     * Generates the typed `Spectra.env` ambient declaration from `spectra.config.ts`'s
+     * `executionConfig.environmentVariables` — mirrors `generateFixturesDeclarationForScope`, but
+     * env vars come from a single project-level config rather than a scanned directory.
+     *
+     * Emits a bare global `interface SpectraEnv { readonly KEY: string; ... }`, which TypeScript
+     * interface-merges with the empty `SpectraEnv` shipped by `@testspectra/matchers` (the same
+     * mechanism `@types/node` uses for projects to augment `NodeJS.ProcessEnv`) — so `Spectra.env.KEY`
+     * resolves to `string`, never `string | undefined` like raw `process.env.KEY`.
+     */
+    static generateEnvDeclaration(environmentVariables: Record<string, string>): string;
     static writeDeclarationFiles(cwd: string): void;
 }

package/dist/generator/type-generator.js

@@ -1,5 +1,6 @@
 import fs from 'fs';
 import path from 'path';
+import { ConfigLoader } from '../config/loader.js';
 import { TsConfigGenerator } from './tsconfig-generator.js';
 export const PLATFORM_HIERARCHY = {
     web: ['web', 'common'],
@@ -12,8 +13,11 @@ export const PLATFORM_HIERARCHY = {
  * Discovers all feature directories and shared library directories.
  * Standard discovery hierarchy:
  * 1. Nx / Monorepo Project Descriptors (`project.json`):
- *    - projectType: "library" OR tags: ["type:shared", "type:library", "scope:shared"] => Shared Library Scope (isShared: true)
- *    - projectType: "application" OR tags: ["type:e2e", "type:app"] => Feature Scope (isShared: false)
+ *    - tags: ["testspectra:shared"] => Shared Library Scope (isShared: true)
+ *    - tags: ["testspectra:e2e"] or ["testspectra:scope:<name>"] => Feature Scope (isShared: false)
+ *    - Generic Nx libraries/apps without testspectra tags are not TestSpectra scopes and recursion
+ *      continues into their subdirectories so nested e2e projects (e.g. `packages/features/auth/e2e`)
+ *      are discovered.
  * 2. Explicit User Configuration (`tsconfig.spectra.shared.json`):
  *    - Custom include path for shared testing utilities
  * 3. Dynamic Workspace Filesystem Discovery (Fallback for non-Nx / custom layouts):
@@ -47,16 +51,9 @@ export function discoverEntityScopes(cwd) {
         if (fs.existsSync(projectJsonPath)) {
             try {
                 const pObj = JSON.parse(fs.readFileSync(projectJsonPath, 'utf-8'));
-                const projectType = pObj.projectType;
                 const tags = Array.isArray(pObj.tags) ? pObj.tags : [];
-                const isSharedLib = projectType === 'library' ||
-                    tags.includes('type:shared') ||
-                    tags.includes('type:library') ||
-                    tags.includes('scope:shared');
-                const isE2eApp = projectType === 'application' ||
-                    tags.includes('type:e2e') ||
-                    tags.includes('type:app') ||
-                    tags.some((t) => t.startsWith('scope:') && t !== 'scope:shared');
+                const isSharedLib = tags.includes('testspectra:shared');
+                const isE2eApp = tags.includes('testspectra:e2e') || tags.some((t) => t.startsWith('testspectra:scope:'));
                 if (isSharedLib) {
                     if (!scopes.some((s) => s.dir === dir)) {
                         scopes.push({ name: 'shared', dir, isShared: true });
@@ -64,9 +61,9 @@ export function discoverEntityScopes(cwd) {
                     return; // Do not recurse into subdirectories of an identified project
                 }
                 else if (isE2eApp) {
-                    // Extract scope name from tags (e.g. "scope:matchers" => "matchers") or project name
-                    const scopeTag = tags.find((t) => t.startsWith('scope:') && t !== 'scope:shared');
-                    let featureName = scopeTag ? scopeTag.replace('scope:', '') : '';
+                    // Extract scope name from tags (e.g. "testspectra:scope:matchers" => "matchers") or project name
+                    const scopeTag = tags.find((t) => t.startsWith('testspectra:scope:'));
+                    let featureName = scopeTag ? scopeTag.replace('testspectra:scope:', '') : '';
                     if (!featureName && pObj.name) {
                         featureName = pObj.name.replace(/-e2e$/, '').replace(/^e2e-/, '');
                     }
@@ -180,6 +177,23 @@ export function discoverEntityScopes(cwd) {
     fallbackScan(cwd, 5);
     return scopes;
 }
+/**
+ * Detects a component-testing project (`@testspectra/react`'s Vitest browser-mode runner), via
+ * the same signal `cli/src/commands/test.ts` uses to gate `spectra test` itself. Used to augment
+ * the generated `Spectra` ambient type with `.mount()`, which only exists in that runtime.
+ */
+export function isComponentTestingProject(cwd) {
+    try {
+        const pkgPath = path.join(cwd, 'package.json');
+        if (!fs.existsSync(pkgPath))
+            return false;
+        const pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf-8'));
+        return Boolean(pkg.dependencies?.['@testspectra/react'] || pkg.devDependencies?.['@testspectra/react']);
+    }
+    catch {
+        return false;
+    }
+}
 export class TypeGenerator {
     /**
      * Main entry point to generate all ambient type declarations.
@@ -188,6 +202,24 @@ export class TypeGenerator {
         this.writeDeclarationFiles(cwd);
         TsConfigGenerator.scaffoldConfigs(cwd);
     }
+    /**
+     * Reloads `spectra.config.ts` and refreshes `.testspectra/types/env.d.ts` with the current
+     * `executionConfig.environmentVariables`. Separate from `writeDeclarationFiles`/`generateAll`
+     * (which must stay synchronous) because reading the config file is unavoidably async.
+     */
+    static async syncEnvDeclaration(cwd) {
+        const rootTypesDir = path.join(cwd, '.testspectra', 'types');
+        if (!fs.existsSync(rootTypesDir)) {
+            fs.mkdirSync(rootTypesDir, { recursive: true });
+        }
+        let environmentVariables = {};
+        try {
+            const config = await ConfigLoader.loadConfig(cwd);
+            environmentVariables = config.executionConfig?.environmentVariables ?? {};
+        }
+        catch { }
+        fs.writeFileSync(path.join(rootTypesDir, 'env.d.ts'), this.generateEnvDeclaration(environmentVariables), 'utf-8');
+    }
     /**
      * Discovers all feature directories and shared library directories.
      * Returns a map of scope -> base directory
@@ -267,10 +299,11 @@ export class TypeGenerator {
         }
         return dirs;
     }
-    static generateDeclarationsForScope(cwd, outputTypesDir, scopeDir, sharedDir) {
+    static generateDeclarationsForScope(cwd, outputTypesDir, scopeDir, sharedDir, rootTypesDir) {
         const poDirs = this.getPageObjectsDirsForScope(scopeDir, sharedDir);
         const actionsDirs = this.getEntityDirsForScope('actions', scopeDir, sharedDir);
         const stepsDirs = this.getEntityDirsForScope('steps', scopeDir, sharedDir);
+        const isComponentTesting = isComponentTestingProject(cwd);
         const platforms = ['web', 'android', 'ios', 'mobile', 'common'];
         const results = {
             web: '',
@@ -279,14 +312,40 @@ export class TypeGenerator {
             mobile: '',
             common: '',
         };
+        // `env.d.ts` always lives at the workspace root types dir (env vars come from a single
+        // `spectra.config.ts`, unlike per-scope fixtures/page-objects), so a shared/feature scope's
+        // own declarations reference it via a relative path back up to the root.
+        let envRefPath = './env.d.ts';
+        if (rootTypesDir && rootTypesDir !== outputTypesDir) {
+            envRefPath = path.relative(outputTypesDir, path.join(rootTypesDir, 'env.d.ts')).replace(/\\/g, '/');
+            if (!envRefPath.startsWith('.'))
+                envRefPath = `./${envRefPath}`;
+        }
         for (const platform of platforms) {
             const hierarchy = PLATFORM_HIERARCHY[platform];
             let content = `// Auto-generated ambient declarations for TestSpectra [${platform.toUpperCase()}]\n`;
             content += `// Managed automatically by TestSpectra Language Service Plugin.\n\n`;
-            content += `/// <reference types="@wdio/globals/types" />\n`;
-            content += `/// <reference types="@wdio/mocha-framework" />\n`;
             content += `/// <reference types="@testspectra/matchers" />\n`;
-            content += `/// <reference path="./fixtures.d.ts" />\n\n`;
+            content += `/// <reference path="./fixtures.d.ts" />\n`;
+            content += `/// <reference path="${envRefPath}" />\n\n`;
+            // TestSpectra's Rust-native orchestrator worker (core/orchestrator/src/worker/bdd_runner.ts)
+            // registers its own `it`/`test`/lifecycle-hook globals directly — there is no WDIO or Mocha
+            // runtime involved at all (not just for component testing; this is true across every
+            // platform). `describe` is intentionally NOT declared here even though the runtime has a
+            // transparent no-op implementation of it — spec-schema-linter's no-describe-block rule
+            // forbids authoring it, so leaving it undeclared makes that a compile error too, not just a
+            // lint error.
+            content += `declare function it(title: string, fn: () => Promise<void> | void): void;\n`;
+            if (isComponentTesting) {
+                // Vitest's own `expect` global (test.globals: true in tools/react/vitest.config.ts) — the
+                // one thing component specs legitimately need beyond the Spectra.* DSL, for asserting
+                // plain closure/callback state (e.g. "was this onClick handler invoked") that has no DOM
+                // element to target. Reuses @testspectra/react's own re-exported `ExpectStatic` type
+                // rather than hand-duplicating Vitest's expect API surface. Not declared for E2E projects
+                // — the Rust orchestrator's BDD runtime has no `expect` global at all.
+                content += `declare const expect: import('@testspectra/react').ExpectStatic;\n`;
+            }
+            content += `\n`;
             // 1. Page Objects Global Declarations
             const declaredPOMs = new Set();
             for (const poDir of poDirs) {
@@ -423,7 +482,10 @@ export class TypeGenerator {
                 }
             }
             content += `}\n`;
-            content += `type TestSpectraActions = import('@testspectra/matchers').SpectraStatic & TestSpectraCustomActions;\n`;
+            // Reuses @testspectra/react's own exported `mount` type rather than hand-duplicating its
+            // signature here — stays in sync automatically if that signature ever changes.
+            const mountAugment = isComponentTesting ? ` & { mount: typeof import('@testspectra/react').mount }` : '';
+            content += `type TestSpectraActions = import('@testspectra/matchers').SpectraStatic & TestSpectraCustomActions${mountAugment};\n`;
             content += `declare const Spectra: TestSpectraActions;\n\n`;
             // 3. Built-in Steps Declaration
             content += `interface TestSpectraSteps {\n`;
@@ -543,11 +605,42 @@ export class TypeGenerator {
         content += `declare const Fixture: TestSpectraFixtures;\n`;
         return content;
     }
+    /**
+     * Generates the typed `Spectra.env` ambient declaration from `spectra.config.ts`'s
+     * `executionConfig.environmentVariables` — mirrors `generateFixturesDeclarationForScope`, but
+     * env vars come from a single project-level config rather than a scanned directory.
+     *
+     * Emits a bare global `interface SpectraEnv { readonly KEY: string; ... }`, which TypeScript
+     * interface-merges with the empty `SpectraEnv` shipped by `@testspectra/matchers` (the same
+     * mechanism `@types/node` uses for projects to augment `NodeJS.ProcessEnv`) — so `Spectra.env.KEY`
+     * resolves to `string`, never `string | undefined` like raw `process.env.KEY`.
+     */
+    static generateEnvDeclaration(environmentVariables) {
+        let content = `// Auto-generated ambient Spectra.env declarations for TestSpectra\n`;
+        content += `// Managed automatically by TestSpectra Language Service Plugin.\n\n`;
+        content += `interface SpectraEnv {\n`;
+        for (const key of Object.keys(environmentVariables)) {
+            content += `  readonly ${JSON.stringify(key)}: string;\n`;
+        }
+        content += `}\n`;
+        return content;
+    }
     static writeDeclarationFiles(cwd) {
         const rootTypesDir = path.join(cwd, '.testspectra', 'types');
         if (!fs.existsSync(rootTypesDir)) {
             fs.mkdirSync(rootTypesDir, { recursive: true });
         }
+        // env.d.ts always lives at the root, regardless of Nx scopes — a single spectra.config.ts's
+        // executionConfig.environmentVariables applies workspace-wide (see generateEnvDeclaration).
+        // Reading spectra.config.ts itself is unavoidably async (ESM dynamic import), which would ripple
+        // an async signature through every caller of this long-standing sync method — instead, this only
+        // guarantees env.d.ts *exists* (so the reference below never points at a missing file) and
+        // leaves it accurate as of the last real sync. `syncEnvDeclaration` (called at the actual
+        // execution entry points: run/watch/sync-types) is what keeps its content up to date.
+        const envDtsPath = path.join(rootTypesDir, 'env.d.ts');
+        if (!fs.existsSync(envDtsPath)) {
+            fs.writeFileSync(envDtsPath, this.generateEnvDeclaration({}), 'utf-8');
+        }
         const scopes = this.getEntityScopes(cwd);
         const sharedScope = scopes.find((s) => s.isShared);
         const featureScopes = scopes.filter((s) => !s.isShared);
@@ -561,7 +654,7 @@ export class TypeGenerator {
         if (!hasScopes || hasRootEntities) {
             const rootFixtures = this.generateFixturesDeclarationForScope(cwd, rootTypesDir, cwd);
             fs.writeFileSync(path.join(rootTypesDir, 'fixtures.d.ts'), rootFixtures, 'utf-8');
-            const rootDeclarations = this.generateDeclarationsForScope(cwd, rootTypesDir, cwd);
+            const rootDeclarations = this.generateDeclarationsForScope(cwd, rootTypesDir, cwd, undefined, rootTypesDir);
             for (const [platform, content] of Object.entries(rootDeclarations)) {
                 fs.writeFileSync(path.join(rootTypesDir, `${platform}.d.ts`), content, 'utf-8');
             }
@@ -587,7 +680,7 @@ export class TypeGenerator {
                 fs.mkdirSync(sharedTypesDir, { recursive: true });
             const sharedFixtures = this.generateFixturesDeclarationForScope(cwd, sharedTypesDir, sharedScope.dir);
             fs.writeFileSync(path.join(sharedTypesDir, 'fixtures.d.ts'), sharedFixtures, 'utf-8');
-            const sharedDeclarations = this.generateDeclarationsForScope(cwd, sharedTypesDir, sharedScope.dir);
+            const sharedDeclarations = this.generateDeclarationsForScope(cwd, sharedTypesDir, sharedScope.dir, undefined, rootTypesDir);
             for (const [platform, content] of Object.entries(sharedDeclarations)) {
                 fs.writeFileSync(path.join(sharedTypesDir, `${platform}.d.ts`), content, 'utf-8');
             }
@@ -609,7 +702,7 @@ export class TypeGenerator {
                 fs.mkdirSync(featureTypesDir, { recursive: true });
             const featureFixtures = this.generateFixturesDeclarationForScope(cwd, featureTypesDir, feature.dir, sharedScope?.dir);
             fs.writeFileSync(path.join(featureTypesDir, 'fixtures.d.ts'), featureFixtures, 'utf-8');
-            const featureDeclarations = this.generateDeclarationsForScope(cwd, featureTypesDir, feature.dir, sharedScope?.dir);
+            const featureDeclarations = this.generateDeclarationsForScope(cwd, featureTypesDir, feature.dir, sharedScope?.dir, rootTypesDir);
             for (const [platform, content] of Object.entries(featureDeclarations)) {
                 fs.writeFileSync(path.join(featureTypesDir, `${platform}.d.ts`), content, 'utf-8');
             }

package/dist/index.d.ts

@@ -2,9 +2,9 @@ import { Command } from 'commander';
 export * from './config/schema.js';
 export * from './config/loader.js';
 export * from './generator/index.js';
-export * from './lifecycle/index.js';
 export * from './refactor/index.js';
 export * from './mobile/index.js';
+export * from './linter/index.js';
 export * from './types/generator.js';
 export * from '@testspectra/matchers';
 export declare function createCliProgram(): Command;

package/dist/index.js

@@ -1,23 +1,25 @@
 import { Command } from 'commander';
 import { addCommand } from './commands/add.js';
-import { cloudRunCommand } from './commands/cloud-run.js';
 import { demoCommand } from './commands/demo.js';
 import { devicesCommand } from './commands/devices.js';
 import { doctorCommand } from './commands/doctor.js';
 import { initCommand } from './commands/init.js';
 import { installCommand } from './commands/install.js';
 import { runCommand } from './commands/run.js';
+import { testCommand } from './commands/test.js';
 import { updateCommand } from './commands/update.js';
 import { watchCommand } from './commands/watch.js';
 import { syncTypesCommand } from './commands/sync-types.js';
 import { refactorCommand } from './commands/refactor.js';
+import { lintCommand } from './commands/lint.js';
 import { licenseCommand } from './commands/license.js';
+import { skillsInitCommand, skillsListCommand, skillsAddCommand, skillsUpdateCommand, skillsRemoveCommand, } from './commands/skills.js';
 export * from './config/schema.js';
 export * from './config/loader.js';
 export * from './generator/index.js';
-export * from './lifecycle/index.js';
 export * from './refactor/index.js';
 export * from './mobile/index.js';
+export * from './linter/index.js';
 export * from './types/generator.js';
 export * from '@testspectra/matchers';
 export function createCliProgram() {
@@ -26,7 +28,7 @@ export function createCliProgram() {
     program
         .command('init')
         .description('Initialize testspectra.config.json and project directories')
-        .option('-t, --template <template>', 'Project template: default, nx')
+        .option('-t, --template <template>', 'Project template: default, nx, react-component')
         .option('-f, --force', 'Overwrite existing configuration if present')
         .action(initCommand);
     program
@@ -71,7 +73,16 @@ Examples:
         .option('--to <path>', 'Destination file or directory to refactor to')
         .option('--dry-run', 'Preview changes without modifying files')
         .option('--json', 'Output results as JSON')
-        .action(refactorCommand);
+        .action(async (...args) => {
+        await refactorCommand(...args);
+    });
+    program
+        .command('lint [path]')
+        .description('Validate spec and suite schemas, frontmatter, and step integrity')
+        .option('-w, --cwd <dir>', 'Custom workspace directory')
+        .option('--strict', 'Treat warnings as errors and exit with code 1')
+        .option('--json', 'Output diagnostic results as JSON')
+        .action(lintCommand);
     program
         .command('doctor')
         .description('Verify local environment prerequisites (ADB, Spectra Android Driver, Chrome, Bun)')
@@ -100,8 +111,44 @@ Examples:
   $ spectra license status           Display active license organization, plan, and expiration
   $ spectra license remove           Remove locally activated license credentials`)
         .action(licenseCommand);
+    const skills = program
+        .command('skills')
+        .description('Manage AI agent skills that standardize TestSpectra script authoring (@testspectra/skills)');
+    skills
+        .command('init')
+        .description('Prompt which AI agent(s) you use and save the choice for future add/update/remove/list')
+        .option('-w, --cwd <dir>', 'Custom workspace directory')
+        .action(skillsInitCommand);
+    skills
+        .command('list')
+        .alias('ls')
+        .description('List all available and installed TestSpectra AI agent skills')
+        .option('-w, --cwd <dir>', 'Custom workspace directory')
+        .option('-a, --agent <ids>', 'One-off override: comma-separated agent(s) to target, bypassing the saved "init" selection (claude, opencode, kilo, agents, gemini)')
+        .action(skillsListCommand);
+    skills
+        .command('add [skillIds...]')
+        .alias('install')
+        .description('Install specified skills into the detected AI agent directories (interactive if none provided)')
+        .option('-w, --cwd <dir>', 'Custom workspace directory')
+        .option('-a, --agent <ids>', 'One-off override: comma-separated agent(s) to target, bypassing the saved "init" selection (claude, opencode, kilo, agents, gemini)')
+        .action(skillsAddCommand);
+    skills
+        .command('update [skillIds...]')
+        .alias('up')
+        .description('Update installed skills to the current bundled version (defaults to all installed)')
+        .option('-w, --cwd <dir>', 'Custom workspace directory')
+        .option('-a, --agent <ids>', 'One-off override: comma-separated agent(s) to target, bypassing the saved "init" selection (claude, opencode, kilo, agents, gemini)')
+        .action(skillsUpdateCommand);
+    skills
+        .command('remove <skillIds...>')
+        .alias('rm')
+        .description('Remove specified skills from the detected AI agent directories')
+        .option('-w, --cwd <dir>', 'Custom workspace directory')
+        .option('-a, --agent <ids>', 'One-off override: comma-separated agent(s) to target, bypassing the saved "init" selection (claude, opencode, kilo, agents, gemini)')
+        .action(skillsRemoveCommand);
     program
-        .command('run [path]')
+        .command('run [paths...]')
         .description('Execute test suite or individual test case')
         .option('-s, --spec <path>', 'Spec file path to execute')
         .option('-t, --target <target>', 'Target platform: web, android, ios, common', 'web')
@@ -111,7 +158,6 @@ Examples:
         .option('--devices <list>', 'Comma-separated list of device UDIDs to run on')
         .option('--license-key <key>', 'Explicit commercial license key override')
         .option('--demo', 'Automatically launch built-in demo web app server during test execution')
-        .option('--base-url <url>', "Override spectra.config.ts's webConfig.baseUrl for this run (e.g. a dev server started by CI just for this job)")
         .option('--headless', 'Run in headless mode')
         .option('--no-headless', 'Run in headed mode')
         .option('--headed', 'Run browser in visible GUI mode (alias for --no-headless)')
@@ -122,29 +168,19 @@ Examples:
         .option('-w, --workdir <dir>', 'Custom app data / temp workdir')
         .option('-o, --output <path>', 'Custom test report JSON output path')
         .action(runCommand);
-    const cloud = program.command('cloud').description('TestSpectra Cloud commands');
-    cloud
-        .command('run')
-        .description('Trigger a TestSpectra Cloud run (spawns testspectra-runner on the cloud server) and optionally wait for the result')
-        .requiredOption('--project <id>', 'Project identifier as registered in TestSpectra')
-        .option('--project-name <name>', 'Human-readable project name (defaults to --project)')
-        .option('--branch <branch>', 'Branch to run against (defaults to the current git branch)')
-        .option('--commit <hash>', 'Commit hash (defaults to the current git HEAD)')
-        .option('--platform <platform>', 'Target platform: web | android', 'web')
-        .option('--wait', 'Block until the run finishes and exit 0/1 on pass/fail (default)')
-        .option('--no-wait', 'Return immediately after triggering, without waiting for the result')
-        .option('--timeout <duration>', 'Max time to wait for the run to finish (e.g. 30m, 10m)', '30m')
-        .option('--demo', "Start TestSpectra's own bundled demo web app on the cloud server before running (template/demo projects only — a real project should point spectra.config.ts's baseUrl at its deployed app instead)")
-        .option('--base-url <url>', 'Override spectra.config.ts\'s webConfig.baseUrl for this run — for a dev server the CI runner itself started in the background and exposed at a reachable URL, forwarded to the cloud server as `spectra run --base-url`')
-        .addHelpText('after', `
-Requires SPECTRA_URL and SPECTRA_TOKEN (a Gitea Personal Access Token) as
-environment variables — see docs/v2/cloud/git-spec-standards-and-workflow.md.
-
-Examples:
-  $ spectra cloud run --project org/repo --branch main --platform web --wait
-  $ spectra cloud run --project org/repo --no-wait
-  $ spectra cloud run --project org/repo --base-url http://192.168.1.50:5173 --wait`)
-        .action(cloudRunCommand);
+    program
+        .command('test')
+        .description('Run React component tests via @testspectra/react (bundled Vitest browser mode)')
+        .option('-w, --cwd <dir>', 'Custom workspace directory')
+        .option('-s, --spec <path>', 'Spec file path (or substring filter) to execute')
+        .option('--headless', 'Run in headless mode (default)')
+        .option('--no-headless', 'Run in headed mode')
+        .option('--headed', 'Run the browser in visible GUI mode (alias for --no-headless)')
+        .option('--step-delay <ms>', 'Delay after each action/assertion in milliseconds (slow motion, for observing DOM transitions in --headed mode)')
+        .option('--delay <ms>', 'Alias for --step-delay')
+        .option('-c, --concurrency <number>', 'Run spec files sequentially (1) or in parallel (>1, default). Browser mode has no numeric N-worker sizing like `spectra run`.')
+        .option('-o, --output <path>', 'Write a Vitest JSON test report to this path')
+        .action(testCommand);
     return program;
 }
 export async function runCli(args = process.argv) {

package/dist/linter/__tests__/anonymous-export.test.js

@@ -0,0 +1,184 @@
+import fs from 'fs';
+import path from 'path';
+import { fileURLToPath } from 'url';
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import { extractModuleExports } from '../extractor.js';
+import { SpecLinter } from '../spec-linter.js';
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+describe('Anonymous Default Export (testspectra/require-anonymous-default-export)', () => {
+    const tempDir = path.join(__dirname, '__temp_anonymous_export__');
+    beforeEach(() => {
+        fs.mkdirSync(tempDir, { recursive: true });
+    });
+    afterEach(() => {
+        if (fs.existsSync(tempDir)) {
+            fs.rmSync(tempDir, { recursive: true, force: true });
+        }
+    });
+    describe('extractModuleExports()', () => {
+        it('detects valid anonymous async default export in .step.ts', () => {
+            const code = `export default async function () {
+  await LoginPage.open();
+}`;
+            const result = extractModuleExports(code, 'web.step.ts');
+            expect(result.hasAnonymousAsyncDefaultExport).toBe(true);
+            expect(result.hasNamedExports).toBe(false);
+            expect(result.testBlocks).toHaveLength(0);
+        });
+        it('detects valid anonymous async arrow function default export in .step.ts', () => {
+            const code = `export default async () => {
+  await LoginPage.open();
+};`;
+            const result = extractModuleExports(code, 'web.step.ts');
+            expect(result.hasAnonymousAsyncDefaultExport).toBe(true);
+            expect(result.hasNamedExports).toBe(false);
+        });
+        it('detects named function with export default (forbidden)', () => {
+            const code = `export default async function login() {
+  await LoginPage.open();
+}`;
+            const result = extractModuleExports(code, 'web.step.ts');
+            expect(result.hasAnonymousAsyncDefaultExport).toBe(false);
+            expect(result.hasNamedExports).toBe(true);
+            expect(result.namedExportLines).toHaveLength(1);
+            expect(result.namedExportLines[0].name).toBe('login');
+            expect(result.namedExportLines[0].line).toBe(1);
+        });
+        it('detects named export function (forbidden)', () => {
+            const code = `export async function verifyUser() {
+  await UserPage.verify();
+}`;
+            const result = extractModuleExports(code, 'web.step.ts');
+            expect(result.hasAnonymousAsyncDefaultExport).toBe(false);
+            expect(result.hasNamedExports).toBe(true);
+            expect(result.namedExportLines[0].name).toBe('verifyUser');
+        });
+        it('detects named export class (forbidden)', () => {
+            const code = `export class Helper {}`;
+            const result = extractModuleExports(code, 'web.step.ts');
+            expect(result.hasAnonymousAsyncDefaultExport).toBe(false);
+            expect(result.hasNamedExports).toBe(true);
+            expect(result.namedExportLines[0].name).toBe('Helper');
+        });
+        it('detects export { ... } clauses (forbidden)', () => {
+            const code = `const a = 1; export { a };`;
+            const result = extractModuleExports(code, 'web.step.ts');
+            expect(result.hasAnonymousAsyncDefaultExport).toBe(false);
+            expect(result.hasNamedExports).toBe(true);
+            expect(result.namedExportLines[0].name).toBe('a');
+        });
+        it('detects named arrow function with export default (forbidden)', () => {
+            const code = `const fn = async () => {}; export default async function named() {}`;
+            const result = extractModuleExports(code, 'web.step.ts');
+            expect(result.hasAnonymousAsyncDefaultExport).toBe(false);
+            expect(result.hasNamedExports).toBe(true);
+        });
+        it('detects valid anonymous async default export in .action.ts', () => {
+            const code = `export default async function (email: string) {
+  await this.get("#email").type(email);
+}`;
+            const result = extractModuleExports(code, 'web.action.ts');
+            expect(result.hasAnonymousAsyncDefaultExport).toBe(true);
+            expect(result.hasNamedExports).toBe(false);
+        });
+        it('detects valid anonymous async default export in .hook.ts', () => {
+            const code = `export default async function () {}`;
+            const result = extractModuleExports(code, 'web.hook.ts');
+            expect(result.hasAnonymousAsyncDefaultExport).toBe(true);
+            expect(result.hasNamedExports).toBe(false);
+        });
+        it('detects missing default export', () => {
+            const code = `function verifyLogin() {
+  await LoginPage.open();
+}`;
+            const result = extractModuleExports(code, 'web.step.ts');
+            expect(result.hasAnonymousAsyncDefaultExport).toBe(false);
+        });
+        it('detects non-async default export as invalid', () => {
+            const code = `export default function verifyLogin() {
+  console.log("hello");
+}`;
+            const result = extractModuleExports(code, 'web.step.ts');
+            expect(result.hasAnonymousAsyncDefaultExport).toBe(false);
+        });
+        it('detects forbidden it() and describe() blocks in shared module', () => {
+            const code = `export default async function () {}
+it("test block", async () => {});
+describe("suite block", () => {});
+`;
+            const result = extractModuleExports(code, 'web.step.ts');
+            expect(result.testBlocks).toHaveLength(2);
+            expect(result.testBlocks[0].name).toBe('it');
+            expect(result.testBlocks[1].name).toBe('describe');
+        });
+    });
+    describe('testspectra/require-anonymous-default-export workspace validation', () => {
+        it('emits testspectra/require-anonymous-default-export when shared step lacks anonymous async default export', () => {
+            const stepsDir = path.join(tempDir, 'shared', 'testing', 'support', 'steps', 'login');
+            fs.mkdirSync(stepsDir, { recursive: true });
+            fs.writeFileSync(path.join(stepsDir, 'web.step.ts'), `function verifyLogin() {
+  console.log("no export");
+}
+`);
+            const result = SpecLinter.validateWorkspace(tempDir);
+            const errors = result.diagnostics.filter((d) => d.code === 'testspectra/require-anonymous-default-export');
+            expect(errors.length).toBeGreaterThanOrEqual(1);
+            expect(errors[0].message).toContain('anonymous async function as default export');
+        });
+        it('passes validation when shared step has valid anonymous async default export', () => {
+            const stepsDir = path.join(tempDir, 'shared', 'testing', 'support', 'steps', 'login');
+            fs.mkdirSync(stepsDir, { recursive: true });
+            fs.writeFileSync(path.join(stepsDir, 'web.step.ts'), `export default async function () {
+  await LoginPage.open();
+}
+`);
+            const result = SpecLinter.validateWorkspace(tempDir);
+            const errors = result.diagnostics.filter((d) => d.code === 'testspectra/require-anonymous-default-export');
+            expect(errors).toHaveLength(0);
+        });
+        it('emits testspectra/require-anonymous-default-export when shared action has named exports', () => {
+            const actionsDir = path.join(tempDir, 'shared', 'testing', 'support', 'actions', 'fillForm');
+            fs.mkdirSync(actionsDir, { recursive: true });
+            fs.writeFileSync(path.join(actionsDir, 'web.action.ts'), `export default async function () {}
+export function helper() {}
+`);
+            const result = SpecLinter.validateWorkspace(tempDir);
+            const errors = result.diagnostics.filter((d) => d.code === 'testspectra/require-anonymous-default-export');
+            expect(errors.length).toBeGreaterThanOrEqual(1);
+            expect(errors.some((d) => d.message.includes('Named export'))).toBe(true);
+        });
+        it('emits testspectra/require-anonymous-default-export when shared hook has test blocks', () => {
+            const hooksDir = path.join(tempDir, 'shared', 'testing', 'global-hooks', 'before');
+            fs.mkdirSync(hooksDir, { recursive: true });
+            fs.writeFileSync(path.join(hooksDir, 'web.hook.ts'), `export default async function () {}
+it("should run", async () => {});
+`);
+            const result = SpecLinter.validateWorkspace(tempDir);
+            const errors = result.diagnostics.filter((d) => d.code === 'testspectra/require-anonymous-default-export');
+            expect(errors.length).toBeGreaterThanOrEqual(1);
+            expect(errors.some((d) => d.message.includes('it() block is forbidden'))).toBe(true);
+        });
+        it('does NOT emit testspectra/require-anonymous-default-export for valid shared step files', () => {
+            const stepsDir = path.join(tempDir, 'shared', 'testing', 'support', 'steps', 'verify');
+            fs.mkdirSync(stepsDir, { recursive: true });
+            fs.writeFileSync(path.join(stepsDir, 'web.step.ts'), `export default async function () {
+  await Page.open();
+  await Page.element.should("be.visible");
+}
+`);
+            const result = SpecLinter.validateWorkspace(tempDir);
+            const errors = result.diagnostics.filter((d) => d.code === 'testspectra/require-anonymous-default-export');
+            expect(errors).toHaveLength(0);
+        });
+        it('does NOT emit testspectra/require-anonymous-default-export for files outside shared/ directory', () => {
+            const featureDir = path.join(tempDir, 'packages', 'playground', 'e2e');
+            fs.mkdirSync(featureDir, { recursive: true });
+            fs.writeFileSync(path.join(featureDir, 'helper.ts'), `export function helper() {}
+`);
+            const result = SpecLinter.validateWorkspace(tempDir);
+            const errors = result.diagnostics.filter((d) => d.code === 'testspectra/require-anonymous-default-export');
+            expect(errors).toHaveLength(0);
+        });
+    });
+});