@testspectra/cli 1.0.70 → 1.1.0-rc.1

package/dist/commands/run.js

@@ -1,134 +1,342 @@
-import fs from "fs";
-import path from "path";
-import { ConfigLoader } from "../config/loader.js";
-import { RustCoreBridge } from "../runner/bridge.js";
-import { Reporter } from "../runner/reporter.js";
-import { TypeGenerator } from "../types/generator.js";
-import { DemoServer } from "../utils/demo-server.js";
-export async function runCommand(specPath, options = {}) {
+import fs from 'fs';
+import path from 'path';
+import { ConfigLoader } from '../config/loader.js';
+import { RustCoreBridge } from '../runner/bridge.js';
+import { Reporter } from '../runner/reporter.js';
+import { TypeGenerator } from '../types/generator.js';
+import { DemoServer } from '../utils/demo-server.js';
+import { DemoApiServer } from '../utils/api-server.js';
+function renderSummaryCard(options) {
+    const width = 64;
+    const borderColor = options.isPassed ? '\x1b[38;2;52;211;153m' : '\x1b[38;2;248;113;113m';
+    const reset = '\x1b[0m';
+    const boldWhite = '\x1b[1;37m';
+    const dim = '\x1b[90m';
+    const cyan = '\x1b[38;2;45;212;191m';
+    const yellow = '\x1b[38;2;251;191;36m';
+    const green = '\x1b[38;2;52;211;153m';
+    const red = '\x1b[38;2;248;113;113m';
+    const strip = (s) => s.replace(/\x1B(?:[@-Z\\-_]|\[[0-?]*[ -/]*[@-~])/g, '');
+    const visualWidth = (s) => {
+        const plain = strip(s);
+        let w = 0;
+        for (const ch of plain) {
+            const code = ch.codePointAt(0) || 0;
+            if (code >= 0x1f300 || (code >= 0x2600 && code <= 0x27bf)) {
+                w += 2;
+            }
+            else {
+                w += 1;
+            }
+        }
+        return w;
+    };
+    const row = (label, value) => {
+        const rawLen = visualWidth(label) + visualWidth(value);
+        const padding = Math.max(1, width - rawLen);
+        return `  ${borderColor}│${reset}  ${label}${' '.repeat(padding)}${value}  ${borderColor}│${reset}`;
+    };
+    const headerRow = (title) => {
+        const rawLen = visualWidth(title);
+        const padding = Math.max(1, width - rawLen);
+        return `  ${borderColor}│${reset}  ${title}${' '.repeat(padding)}  ${borderColor}│${reset}`;
+    };
+    const top = `  ${borderColor}╭${'─'.repeat(width + 4)}╮${reset}`;
+    const mid = `  ${borderColor}├${'─'.repeat(width + 4)}┤${reset}`;
+    const bot = `  ${borderColor}╰${'─'.repeat(width + 4)}╯${reset}`;
+    const statusBadge = options.isPassed ? `${green}✓ PASSED${reset}` : `${red}✗ FAILED${reset}`;
+    const passedSuites = options.passedSuites ?? (options.isPassed ? options.suiteCount : 0);
+    const failedSuites = options.failedSuites ?? (options.isPassed ? 0 : options.suiteCount);
+    const testsPassedText = options.carriedPassed
+        ? `${options.passedCount > 0 ? `${green}${options.passedCount} passed${reset}` : `${options.passedCount} passed`} ${dim}(${options.carriedPassed} carried over)${reset}`
+        : options.passedCount > 0
+            ? `${green}${options.passedCount} passed${reset}`
+            : `${options.passedCount} passed`;
+    console.log(`\n${top}`);
+    console.log(headerRow(`${boldWhite}✨  TESTSPECTRA EXECUTION SUMMARY${reset}`));
+    console.log(mid);
+    console.log(row(`${dim}Status${reset}`, statusBadge));
+    console.log(row(`${dim}Suites${reset}`, `${passedSuites > 0 ? `${green}${passedSuites} passed${reset}` : `${passedSuites} passed`}, ` +
+        `${failedSuites > 0 ? `${red}${failedSuites} failed${reset}` : `${failedSuites} failed`} ` +
+        `${dim}(${options.suiteCount} total)${reset}`));
+    console.log(row(`${dim}Tests${reset}`, `${testsPassedText}, ` +
+        `${options.failedCount > 0 ? `${red}${options.failedCount} failed${reset}` : `${options.failedCount} failed`} ` +
+        `${dim}(${options.testCount} total)${reset}`));
+    console.log(row(`${dim}Platform${reset}`, `${cyan}${options.platform}${reset}`));
+    console.log(row(`${dim}Duration${reset}`, `${yellow}${options.duration}${reset}`));
+    console.log(row(`${dim}Report${reset}`, `${dim}${options.reportPath}${reset}`));
+    if (options.networkReportPath) {
+        console.log(row(`${dim}Network${reset}`, `${dim}${options.networkReportPath}${reset}`));
+    }
+    console.log(`${bot}\n`);
+}
+const TIMING_PHASE_LABELS = {
+    web: { boot: '1. Master Chromium Process Boot', handshake: '3. Incognito Context & CDP Handshake' },
+    android: { boot: '1. Android Driver Bootstrap (ADB + Agent)', handshake: '3. Device Session Handshake' },
+    ios: { boot: '1. iOS Driver Bootstrap (Appium)', handshake: '3. WDA Session Handshake' },
+};
+export function renderTimingBreakdown(performance, platform = 'web') {
+    const phaseLabels = TIMING_PHASE_LABELS[platform] ?? TIMING_PHASE_LABELS.web;
+    const yellowBold = '\x1b[1;38;2;251;191;36m';
+    const reset = '\x1b[0m';
+    const borderColor = '\x1b[38;2;75;85;99m';
+    const pad = (str, width) => {
+        const s = String(str);
+        return ' '.repeat(Math.max(0, width - s.length)) + s;
+    };
+    const padRight = (str, width) => {
+        const s = String(str);
+        return s + ' '.repeat(Math.max(0, width - s.length));
+    };
+    const wallClock = performance.duration
+        ? performance.duration
+        : `${((performance.wallClockDurationMs ?? 0) / 1000).toFixed(2)}s`;
+    const totalTests = performance.totalTests ?? 1;
+    const totalTestExecMs = performance.totalTestExecutionMs ?? (performance.avgTestExecutionMs ?? 0) * totalTests;
+    const avgTestExecMs = performance.avgTestExecutionMs ?? (totalTests > 0 ? Math.round(totalTestExecMs / totalTests) : 0);
+    const contextHandshakeMs = (performance.avgContextCreationMs ?? 0) + (performance.avgCdpHandshakeMs ?? 0);
+    const testLabel = totalTests === 1 ? '4. Total Test Execution (1 test)' : `4. Total Test Execution (${totalTests} tests)`;
+    const testDetail = totalTests <= 1 ? `${pad(totalTestExecMs, 13)} ms` : `${pad(totalTestExecMs, 5)} ms (${pad(avgTestExecMs, 3)}ms/t)`;
+    console.log(`⏱️  ${yellowBold}EXECUTION TIMING BREAKDOWN (PHASE-BY-PHASE)${reset}`);
+    console.log(`${borderColor}┌──────────────────────────────────────────┬───────────────────┐${reset}`);
+    console.log(`${borderColor}│${reset} Execution Phase                          ${borderColor}│${reset} Duration / Detail ${borderColor}│${reset}`);
+    console.log(`${borderColor}├──────────────────────────────────────────┼───────────────────┤${reset}`);
+    console.log(`${borderColor}│${reset} ${padRight(phaseLabels.boot, 40)} ${borderColor}│${reset} ${pad(performance.masterBootLatencyMs ?? 0, 13)} ms ${borderColor}│${reset}`);
+    console.log(`${borderColor}│${reset} ${padRight('2. Worker Spawning & Runtime Overhead', 40)} ${borderColor}│${reset} ${pad(performance.runnerOverheadMs ?? 0, 13)} ms ${borderColor}│${reset}`);
+    console.log(`${borderColor}│${reset} ${padRight(phaseLabels.handshake, 40)} ${borderColor}│${reset} ${pad(contextHandshakeMs, 10)} ms (avg)${borderColor}│${reset}`);
+    console.log(`${borderColor}│${reset} ${padRight(testLabel, 40)} ${borderColor}│${reset} ${pad(testDetail, 17)} ${borderColor}│${reset}`);
+    console.log(`${borderColor}│${reset} ${padRight('5. Context Teardown / Cleanup', 40)} ${borderColor}│${reset} ${pad(performance.avgTeardownMs ?? 0, 10)} ms (avg)${borderColor}│${reset}`);
+    console.log(`${borderColor}├──────────────────────────────────────────┼───────────────────┤${reset}`);
+    console.log(`${borderColor}│${reset} Total Wall-Clock Execution Time          ${borderColor}│${reset} ${pad(wallClock, 15)} ${borderColor}│${reset}`);
+    console.log(`${borderColor}└──────────────────────────────────────────┴───────────────────┘${reset}\n`);
+}
+export async function runCommand(specPaths, options = {}) {
     const cwd = process.cwd();
-    const effectiveSpecPath = specPath || options.spec;
+    // Opt-in duration logging (TESTSPECTRA_DURATION_LOG): resolve to one absolute JSONL path that
+    // both this host process (Rust orchestrator) and every spawned Bun worker append to, and stamp a
+    // run id so repeated runs can be told apart. Off by default; toggled purely via the env var.
+    if (process.env.TESTSPECTRA_DURATION_LOG) {
+        const v = process.env.TESTSPECTRA_DURATION_LOG;
+        const abs = v === '1' || v === 'true' ? path.join(cwd, '.testspectra', 'logs', 'duration.jsonl') : path.resolve(cwd, v);
+        process.env.TESTSPECTRA_DURATION_LOG = abs;
+        if (!process.env.TESTSPECTRA_RUN_ID)
+            process.env.TESTSPECTRA_RUN_ID = String(Date.now());
+    }
+    const effectiveSpecPaths = specPaths && specPaths.length > 0 ? specPaths : options.spec ? [options.spec] : undefined;
     // Ensure latest ambient types are up-to-date
     TypeGenerator.writeDeclarationFiles(cwd);
-    const config = await ConfigLoader.loadConfig(cwd);
-    let demoServer = null;
-    if (options.demo) {
-        demoServer = new DemoServer(5173);
-        try {
-            const { url } = await demoServer.start();
-            config.webConfig.baseUrl = url;
-            console.log(`\x1b[36m[TestSpectra]\x1b[0m 🌐 Demo Web App automatically started at: \x1b[33m${url}\x1b[0m`);
-        }
-        catch (err) {
-            console.warn(`\x1b[33m[TestSpectra] Warning: Could not start built-in demo server: ${err.message}\x1b[0m`);
-        }
+    await TypeGenerator.syncEnvDeclaration(cwd);
+    const home = process.env.HOME || process.env.USERPROFILE || '';
+    const globalAppDataPath = path.join(home, '.testspectra');
+    const appDataPath = options.workdir ? path.resolve(options.workdir) : globalAppDataPath;
+    if (!fs.existsSync(appDataPath)) {
+        fs.mkdirSync(appDataPath, { recursive: true });
     }
-    if (options.headless !== undefined) {
-        config.webConfig.headlessMode = options.headless;
+    const projectAppData = path.join(cwd, '.testspectra');
+    const outputJsonPath = options.output
+        ? path.resolve(options.output)
+        : path.join(projectAppData, 'reports', 'result.json');
+    const isFailedMode = options.failed !== undefined;
+    let failedTarget;
+    if (typeof options.failed === 'string' && options.failed !== 'true') {
+        failedTarget = options.failed;
     }
-    const platform = options.target || "web";
-    // Find workspace root for centralized .testspectra (monorepo root or current test project)
-    let workspaceRoot = cwd;
-    let cur = cwd;
-    while (cur !== path.dirname(cur)) {
-        if (fs.existsSync(path.join(cur, "pnpm-workspace.yaml")) || fs.existsSync(path.join(cur, "nx.json"))) {
-            workspaceRoot = cur;
-            break;
+    if (isFailedMode) {
+        if (fs.existsSync(outputJsonPath)) {
+            try {
+                const prev = JSON.parse(fs.readFileSync(outputJsonPath, 'utf8'));
+                const failedItems = (prev.suites || []).flatMap((s) => (s.tests || []).filter((t) => t.passed === false || t.status === 'failed'));
+                if (failedItems.length === 0) {
+                    console.log(`\x1b[32m✨ [TestSpectra] No failed tests found in previous test session! Everything is already passing.\x1b[0m\n`);
+                    return;
+                }
+                const targetDesc = failedTarget ? `target '${failedTarget}' in` : '';
+                console.log(`\x1b[36m[TestSpectra]\x1b[0m 🔄 Re-running ${targetDesc} ${failedItems.length} failed test(s) with session state carry-over...`);
+            }
+            catch { }
         }
-        cur = path.dirname(cur);
-    }
-    const appDataPath = options.workdir ? path.resolve(options.workdir) : path.join(workspaceRoot, ".testspectra");
-    if (!fs.existsSync(appDataPath)) {
-        fs.mkdirSync(appDataPath, { recursive: true });
     }
-    // Determine suite/test case name
-    let suiteName = "default";
-    let testCases = [];
-    if (effectiveSpecPath) {
-        const relSpec = path.isAbsolute(effectiveSpecPath) ? path.relative(cwd, effectiveSpecPath) : effectiveSpecPath;
-        const normalized = relSpec.replace(/\\/g, "/");
-        const parts = normalized.split("/");
-        if (parts.length >= 2 && (parts[0] === "specs" || parts[0] === "suites")) {
-            suiteName = parts[1];
+    const config = await ConfigLoader.loadConfig(cwd);
+    let demoServer = null;
+    let apiServer = null;
+    try {
+        if (options.demo) {
+            demoServer = new DemoServer(5173);
+            try {
+                const { url } = await demoServer.start();
+                config.webConfig.baseUrl = url;
+                console.log(`\x1b[36m[TestSpectra]\x1b[0m 🌐 Demo Web App automatically started at: \x1b[33m${url}\x1b[0m`);
+            }
+            catch (err) {
+                console.warn(`\x1b[33m[TestSpectra] Warning: Could not start built-in demo server: ${err.message}\x1b[0m`);
+            }
+            apiServer = new DemoApiServer();
+            try {
+                const { url, port } = await apiServer.start();
+                console.log(`\x1b[36m[TestSpectra]\x1b[0m 🌐 Demo API server automatically started at: \x1b[33m${url}\x1b[0m (port ${port}, self-hosted /api/*)`);
+            }
+            catch (err) {
+                console.warn(`\x1b[33m[TestSpectra] Warning: Could not start built-in demo API server: ${err.message}\x1b[0m`);
+            }
         }
-        else {
-            const parsed = path.parse(normalized);
-            suiteName = parsed.name.replace(/\.(web|android|ios|common|test|spec)/g, "") || "default";
+        if (options.headed) {
+            config.webConfig.headless = false;
         }
-        testCases.push({
-            id: normalized,
-            title: normalized,
-            executionOrder: 1,
-        });
-    }
-    else {
-        // 1. Scan specs/ directory (specs/<Suite>/<CaseId>/web.test.ts)
-        const specsDir = path.join(cwd, "specs");
-        if (fs.existsSync(specsDir)) {
-            const suiteEntries = fs.readdirSync(specsDir, { withFileTypes: true });
-            for (const sEntry of suiteEntries) {
-                if (sEntry.name.startsWith(".") || !sEntry.isDirectory())
-                    continue;
-                const currentSuite = sEntry.name;
-                const suitePath = path.join(specsDir, currentSuite);
-                const caseEntries = fs.readdirSync(suitePath, { withFileTypes: true });
-                for (const cEntry of caseEntries) {
-                    if (cEntry.name.startsWith(".") || cEntry.name === "hooks")
-                        continue;
-                    if (cEntry.isDirectory()) {
-                        testCases.push({ id: path.join("specs", currentSuite, cEntry.name).replace(/\\/g, "/"), title: `${currentSuite} / ${cEntry.name}` });
-                    }
-                    else if (cEntry.isFile() && (cEntry.name.endsWith(".test.ts") || cEntry.name.endsWith(".spec.ts"))) {
-                        const id = path.join("specs", currentSuite, cEntry.name).replace(/\\/g, "/");
-                        testCases.push({ id, title: `${currentSuite} / ${cEntry.name}` });
-                    }
-                }
+        else if (options.headless !== undefined) {
+            config.webConfig.headless = options.headless;
+        }
+        const rawDelay = options.stepDelay ?? options.delay;
+        if (rawDelay !== undefined) {
+            const delayNum = parseInt(String(rawDelay), 10);
+            if (!isNaN(delayNum) && delayNum >= 0) {
+                config.webConfig.stepDelay = delayNum;
+                config.androidConfig.stepDelay = delayNum;
+                config.iosConfig.stepDelay = delayNum;
             }
         }
-        // 2. Fallback: Scan suites/ directory
-        const suitesDir = path.join(cwd, "suites");
-        if (fs.existsSync(suitesDir)) {
-            const suiteEntries = fs.readdirSync(suitesDir, { withFileTypes: true });
-            for (const sEntry of suiteEntries) {
-                if (sEntry.name.startsWith(".") || !sEntry.isDirectory())
-                    continue;
-                const currentSuite = sEntry.name;
-                const suitePath = path.join(suitesDir, currentSuite);
-                const caseEntries = fs.readdirSync(suitePath, { withFileTypes: true });
-                for (const cEntry of caseEntries) {
-                    if (cEntry.name.startsWith(".") || cEntry.name === "hooks" || !cEntry.isDirectory())
-                        continue;
-                    testCases.push({ id: path.join("suites", currentSuite, cEntry.name).replace(/\\/g, "/"), title: `${currentSuite} / ${cEntry.name}` });
-                }
+        const platform = options.target || 'web';
+        const userConcurrency = options.concurrency ? parseInt(String(options.concurrency), 10) : undefined;
+        console.log(`\x1b[36m[TestSpectra]\x1b[0m Starting execution on target \x1b[1m${platform}\x1b[0m...`);
+        if (options.devices || options.device) {
+            const rawDevices = (options.devices || options.device);
+            const devIds = rawDevices.includes(',')
+                ? rawDevices
+                    .split(',')
+                    .map((s) => s.trim())
+                    .filter(Boolean)
+                : [rawDevices.trim()].filter(Boolean);
+            const mappedDevices = devIds.map((id) => ({ id }));
+            if (platform === 'ios') {
+                config.iosConfig.devices = mappedDevices;
             }
+            else {
+                config.androidConfig.devices = mappedDevices;
+            }
+            const count = devIds.length;
+            const desc = devIds.join(', ');
+            console.log(`\x1b[36m[TestSpectra Grid]\x1b[0m Mobile device target configured (${count} device(s)): ${desc}`);
         }
-    }
-    if (testCases.length === 0) {
-        testCases.push({
-            id: suiteName,
-            title: suiteName,
-            executionOrder: 1,
-        });
-    }
-    const outputJsonPath = options.output
-        ? path.resolve(options.output)
-        : path.join(appDataPath, "reports/result.json");
-    console.log(`\x1b[36m[TestSpectra]\x1b[0m Starting execution on target \x1b[1m${platform}\x1b[0m...`);
-    console.log(`\x1b[36m[TestSpectra]\x1b[0m Base URL: \x1b[33m${config.webConfig.baseUrl}\x1b[0m`);
-    console.log(`\x1b[36m[TestSpectra]\x1b[0m Suite: ${suiteName} (${testCases.length} case(s))\n`);
-    const reporter = new Reporter();
-    try {
+        else if (options.allDevices || options.multiDevice) {
+            if (platform === 'ios') {
+                config.iosConfig.devices = 'auto';
+            }
+            else {
+                config.androidConfig.devices = 'auto';
+            }
+            console.log('\x1b[36m[TestSpectra Grid]\x1b[0m Multi-device grid enabled (auto-detecting connected devices)');
+        }
+        console.log(`\x1b[36m[TestSpectra]\x1b[0m Base URL: \x1b[33m${config.webConfig.baseUrl}\x1b[0m\n`);
+        const reporter = new Reporter();
+        const targetDevice = options.devices || options.device || (options.allDevices || options.multiDevice ? 'auto' : undefined);
         const result = await RustCoreBridge.run({
             baseDir: cwd,
             appDataPath,
             platform,
-            suite: suiteName,
-            testCases,
             config,
-            targetDevice: options.device,
+            targetDevice,
+            licenseKey: options.licenseKey,
             outputJsonPath,
+            specs: effectiveSpecPaths,
+            concurrency: userConcurrency,
+            failedOnly: isFailedMode,
+            failedTarget,
         }, reporter);
-        console.log(`\n\x1b[36m[TestSpectra]\x1b[0m Run finished: \x1b[1m${result.status.toUpperCase()}\x1b[0m in ${result.duration}`);
+        const isPassed = result.status.toLowerCase() === 'passed';
+        const relReport = path.relative(cwd, outputJsonPath);
+        const networkReportFile = path.join(path.dirname(outputJsonPath), 'network-resources.json');
+        const relNetworkReport = fs.existsSync(networkReportFile) ? path.relative(cwd, networkReportFile) : undefined;
+        let carriedOver;
+        if (process.env.TESTSPECTRA_CARRIED_OVER) {
+            try {
+                carriedOver = JSON.parse(process.env.TESTSPECTRA_CARRIED_OVER);
+            }
+            catch { }
+        }
+        const carriedPassed = carriedOver?.passed || 0;
+        const carriedDurationMs = carriedOver?.durationMs || 0;
+        let suiteCount = 1;
+        let passedSuites = isPassed ? 1 : 0;
+        let failedSuites = isPassed ? 0 : 1;
+        let basePassed = result.passedCount ?? (isPassed ? 1 : 0);
+        let baseFailed = result.failedCount ?? (isPassed ? 0 : 1);
+        const totalPassed = basePassed + carriedPassed;
+        const totalFailed = baseFailed;
+        const totalTests = basePassed + baseFailed + carriedPassed;
+        let finalDuration = result.duration;
+        if (carriedDurationMs > 0) {
+            const match = result.duration.match(/([\d.]+)\s*(ms|s|m)/);
+            let runMs = 0;
+            if (match) {
+                const val = parseFloat(match[1]);
+                const unit = match[2];
+                runMs = unit === 's' ? val * 1000 : unit === 'm' ? val * 60000 : val;
+            }
+            const totalMs = runMs + carriedDurationMs;
+            finalDuration = totalMs < 1000 ? `${Math.round(totalMs)}ms` : `${(totalMs / 1000).toFixed(1)}s`;
+        }
+        const overallPassed = isPassed && totalFailed === 0;
+        if (fs.existsSync(outputJsonPath)) {
+            try {
+                const fullReport = JSON.parse(fs.readFileSync(outputJsonPath, 'utf8'));
+                if (fullReport.summary) {
+                    suiteCount = fullReport.summary.totalSuites ?? 1;
+                }
+                if (fullReport.suites && Array.isArray(fullReport.suites)) {
+                    failedSuites = fullReport.suites.filter((s) => (typeof s.failed === 'number' && s.failed > 0) ||
+                        s.status === 'failed' ||
+                        s.tests?.some((t) => t.passed === false || t.status === 'failed')).length;
+                    passedSuites = fullReport.suites.length - failedSuites;
+                }
+                if (fullReport.performance) {
+                    renderSummaryCard({
+                        isPassed: overallPassed,
+                        statusText: overallPassed ? 'PASSED' : 'FAILED',
+                        duration: finalDuration,
+                        platform,
+                        suiteCount,
+                        passedSuites,
+                        failedSuites,
+                        testCount: totalTests,
+                        passedCount: totalPassed,
+                        failedCount: totalFailed,
+                        carriedPassed,
+                        reportPath: relReport,
+                        networkReportPath: relNetworkReport,
+                    });
+                    renderTimingBreakdown({
+                        ...fullReport.performance,
+                        wallClockDurationMs: fullReport.wallClockDurationMs,
+                        duration: fullReport.duration,
+                        totalTests: fullReport.summary?.totalTests ?? totalTests,
+                    }, platform);
+                    if (!overallPassed || totalFailed > 0) {
+                        process.exitCode = 1;
+                    }
+                    return;
+                }
+            }
+            catch {
+                // ignore
+            }
+        }
+        renderSummaryCard({
+            isPassed: overallPassed,
+            statusText: overallPassed ? 'PASSED' : 'FAILED',
+            duration: finalDuration,
+            platform,
+            suiteCount,
+            passedSuites,
+            failedSuites,
+            testCount: totalTests,
+            passedCount: totalPassed,
+            failedCount: totalFailed,
+            carriedPassed,
+            reportPath: relReport,
+            networkReportPath: relNetworkReport,
+        });
+        if (!overallPassed || totalFailed > 0) {
+            process.exitCode = 1;
+        }
     }
     catch (e) {
         console.error(`\x1b[31m[TestSpectra] Execution error:\x1b[0m`, e);
@@ -138,5 +346,8 @@ export async function runCommand(specPath, options = {}) {
         if (demoServer) {
             await demoServer.stop();
         }
+        if (apiServer) {
+            await apiServer.stop();
+        }
     }
 }

package/dist/commands/skills.d.ts

@@ -0,0 +1,9 @@
+export interface SkillsCommandOptions {
+    cwd?: string;
+    agent?: string;
+}
+export declare function skillsInitCommand(options?: SkillsCommandOptions): Promise<void>;
+export declare function skillsListCommand(options?: SkillsCommandOptions): void;
+export declare function skillsAddCommand(ids?: string[], options?: SkillsCommandOptions): Promise<void>;
+export declare function skillsUpdateCommand(ids?: string[], options?: SkillsCommandOptions): void;
+export declare function skillsRemoveCommand(ids?: string[], options?: SkillsCommandOptions): void;

package/dist/commands/skills.js

@@ -0,0 +1,28 @@
+import path from 'path';
+import chalk from 'chalk';
+import { initSkills, listSkills, addSkills, updateSkills, removeSkills, getKnownAgentIds, resolveAgentSelection, } from '@testspectra/skills';
+function resolveBaseDir(options = {}) {
+    return options.cwd ? path.resolve(options.cwd) : process.cwd();
+}
+function resolveAgentIds(options = {}) {
+    const { ids, unknown } = resolveAgentSelection(options.agent);
+    if (unknown.length > 0) {
+        console.log(chalk.yellow(`⚠️  Unknown --agent value(s): ${unknown.join(', ')}. Known ids: ${getKnownAgentIds().join(', ')}`));
+    }
+    return ids.length > 0 ? ids : undefined;
+}
+export async function skillsInitCommand(options = {}) {
+    await initSkills(resolveBaseDir(options));
+}
+export function skillsListCommand(options = {}) {
+    listSkills(resolveBaseDir(options), resolveAgentIds(options));
+}
+export async function skillsAddCommand(ids = [], options = {}) {
+    await addSkills(ids, resolveBaseDir(options), resolveAgentIds(options));
+}
+export function skillsUpdateCommand(ids = [], options = {}) {
+    updateSkills(ids, resolveBaseDir(options), resolveAgentIds(options));
+}
+export function skillsRemoveCommand(ids = [], options = {}) {
+    removeSkills(ids, resolveBaseDir(options), resolveAgentIds(options));
+}

package/dist/commands/sync-types.d.ts

@@ -0,0 +1,4 @@
+export interface SyncTypesCommandOptions {
+    cwd?: string;
+}
+export declare function syncTypesCommand(options?: SyncTypesCommandOptions): Promise<void>;

package/dist/commands/sync-types.js

@@ -0,0 +1,15 @@
+import path from 'path';
+import chalk from 'chalk';
+import { TypeGenerator } from '../types/generator.js';
+export async function syncTypesCommand(options = {}) {
+    const cwd = options.cwd ? path.resolve(options.cwd) : process.cwd();
+    try {
+        TypeGenerator.generateAll(cwd);
+        await TypeGenerator.syncEnvDeclaration(cwd);
+        console.log(chalk.green('✔ Successfully synchronized TestSpectra ambient type declarations in .testspectra/types/'));
+    }
+    catch (err) {
+        console.error(chalk.red(`✖ Failed to synchronize ambient declarations: ${err?.message}`));
+        process.exit(1);
+    }
+}

package/dist/commands/test.d.ts

@@ -0,0 +1,17 @@
+export interface TestCommandOptions {
+    cwd?: string;
+    headed?: boolean;
+    headless?: boolean;
+    stepDelay?: string | number;
+    delay?: string | number;
+    spec?: string;
+    output?: string;
+    concurrency?: string | number;
+}
+/**
+ * `spectra test` — delegates to `@testspectra/react`'s bundled Vitest browser-mode runner for
+ * component testing. Deliberately separate from `spectra run` (E2E via core/orchestrator): see
+ * docs/v2/features/component-testing/react/README.md §2 for why these are two independent
+ * runners rather than one extended pipeline.
+ */
+export declare function testCommand(options?: TestCommandOptions): Promise<void>;

package/dist/commands/test.js

@@ -0,0 +1,76 @@
+import path from 'node:path';
+import chalk from 'chalk';
+import * as p from '@clack/prompts';
+import { runSystemChecks } from './doctor.js';
+/**
+ * Finds the Chrome-for-Testing binary that `spectra doctor` already installs/manages for the
+ * E2E CDP driver (`core/driver-cdp`) — same install, same binary. `@testspectra/react` must not
+ * contain any browser-discovery logic of its own (see the package-level comment in
+ * tools/react/vitest.config.ts): this is the one place that resolves the path, passed down to
+ * the bundled Vitest/Playwright runner as a plain argument (env var), so component testing never
+ * requires a separate `playwright install` download alongside TestSpectra's own browser.
+ */
+async function resolveBrowserExecutable(cwd) {
+    try {
+        const { dependencies } = await runSystemChecks(cwd);
+        const chrome = dependencies.find((d) => d.category === 'web' && (d.name.includes('Chrome') || d.name.includes('Chromium')));
+        return chrome?.installed && chrome.location ? chrome.location : null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * `spectra test` — delegates to `@testspectra/react`'s bundled Vitest browser-mode runner for
+ * component testing. Deliberately separate from `spectra run` (E2E via core/orchestrator): see
+ * docs/v2/features/component-testing/react/README.md §2 for why these are two independent
+ * runners rather than one extended pipeline.
+ */
+export async function testCommand(options = {}) {
+    const cwd = options.cwd ?? process.cwd();
+    let reactPkg;
+    try {
+        reactPkg = await import('@testspectra/react');
+    }
+    catch {
+        p.log.error(chalk.red('✖ @testspectra/react is not installed in this workspace.'));
+        p.log.info(chalk.dim('Component testing requires the @testspectra/react package.'));
+        p.log.info(chalk.dim('  👉 Install it:  pnpm add -D @testspectra/react'));
+        process.exit(1);
+        return;
+    }
+    const browserExecutablePath = await resolveBrowserExecutable(cwd);
+    if (!browserExecutablePath) {
+        p.log.error(chalk.red('✖ TestSpectra-managed Chrome for Testing was not found.'));
+        p.log.info(chalk.dim('Component testing reuses the same browser install as `spectra run` (web).'));
+        p.log.info(chalk.dim('  👉 Install it:  spectra doctor --fix'));
+        process.exit(1);
+        return;
+    }
+    let stepDelayMs;
+    const rawDelay = options.stepDelay ?? options.delay;
+    if (rawDelay !== undefined) {
+        const delayNum = parseInt(String(rawDelay), 10);
+        if (!isNaN(delayNum) && delayNum >= 0) {
+            stepDelayMs = delayNum;
+        }
+    }
+    let headless = true;
+    if (options.headed) {
+        headless = false;
+    }
+    else if (options.headless !== undefined) {
+        headless = options.headless;
+    }
+    const concurrency = options.concurrency !== undefined ? parseInt(String(options.concurrency), 10) : undefined;
+    const ok = await reactPkg.runComponentTests({
+        cwd,
+        headless,
+        stepDelayMs,
+        spec: options.spec,
+        outputFile: options.output ? path.resolve(cwd, options.output) : undefined,
+        concurrency: concurrency !== undefined && !isNaN(concurrency) ? concurrency : undefined,
+        browserExecutablePath,
+    });
+    process.exit(ok ? 0 : 1);
+}