@testspectra/cli 1.1.7 → 1.1.8-rc.10

package/dist/commands/init.js

@@ -215,10 +215,15 @@ export async function initCommand(options = {}) {
                     hint: 'Interactive workspace feature discovery & centralized config',
                 },
                 {
-                    label: 'Standard Project',
+                    label: 'Standard E2E Project',
                     value: 'default',
                     hint: 'Standalone single-suite E2E testing project',
                 },
+                {
+                    label: 'React Component Testing',
+                    value: 'react-component',
+                    hint: 'Real-browser React component testing with Vite & Testing Library',
+                },
             ],
         });
         if (p.isCancel(templateChoice)) {
@@ -503,6 +508,7 @@ export async function initCommand(options = {}) {
             copyRecursive(sampleE2eSrc, targetE2eDir, {
                 'playground-e2e': e2eProjectName,
                 'packages/playground/e2e': path.relative(cwd, targetE2eDir).replace(/\\/g, '/'),
+                'testspectra:scope:playground': `testspectra:scope:${featureName}`,
                 'scope:playground': `scope:${featureName}`,
             });
             // Adjust project.json
@@ -514,7 +520,7 @@ export async function initCommand(options = {}) {
                     pObj.sourceRoot = path.relative(cwd, targetE2eDir).replace(/\\/g, '/');
                     pObj.targets.e2e.options.cwd = path.relative(cwd, targetE2eDir).replace(/\\/g, '/');
                     pObj.targets['type-check'].options.cwd = '.';
-                    pObj.tags = [`scope:${featureName}`, 'type:e2e'];
+                    pObj.tags = ['testspectra:e2e', `testspectra:scope:${featureName}`];
                     fs.writeFileSync(projJsonPath, JSON.stringify(pObj, null, 2), 'utf-8');
                 }
                 catch { }

package/dist/commands/lint.d.ts

@@ -0,0 +1,5 @@
+import type { LintOptions } from '../linter/types.js';
+export interface LintCommandOptions extends LintOptions {
+    path?: string;
+}
+export declare function lintCommand(targetPath?: string, options?: LintCommandOptions): Promise<void>;

package/dist/commands/lint.js

@@ -0,0 +1,55 @@
+import path from 'path';
+import chalk from 'chalk';
+import { SpecLinter } from '../linter/spec-linter.js';
+export async function lintCommand(targetPath, options = {}) {
+    const cwd = options.cwd ? path.resolve(options.cwd) : process.cwd();
+    try {
+        const result = SpecLinter.validateWorkspace(cwd, targetPath);
+        if (options.json) {
+            console.log(JSON.stringify(result, null, 2));
+            if (!result.valid || (options.strict && result.stats.warningCount > 0)) {
+                process.exit(1);
+            }
+            return;
+        }
+        console.log(chalk.bold('\n🔍 TestSpectra Spec & Code Linter\n'));
+        // Group diagnostics by file
+        const diagnosticsByFile = new Map();
+        for (const diag of result.diagnostics) {
+            const relPath = path.relative(cwd, diag.filePath);
+            const list = diagnosticsByFile.get(relPath) || [];
+            list.push(diag);
+            diagnosticsByFile.set(relPath, list);
+        }
+        if (diagnosticsByFile.size === 0) {
+            console.log(chalk.green(`  ✓ ${result.stats.totalSpecs} specs and ${result.stats.totalSuites} suites verified.`));
+            console.log(chalk.green.bold('\n✓ All spec schemas are valid. 0 lint errors found.\n'));
+            return;
+        }
+        for (const [file, diags] of diagnosticsByFile.entries()) {
+            console.log(chalk.bold(`  ${file}`));
+            for (const diag of diags) {
+                const icon = diag.severity === 'error' ? chalk.red('✗') : chalk.yellow('⚠');
+                const codeTag = chalk.gray(`[${diag.code}]`);
+                const loc = chalk.dim(`:${diag.line}`);
+                console.log(`    ${icon} ${codeTag} ${diag.message} ${loc}`);
+            }
+            console.log();
+        }
+        const { errorCount, warningCount } = result.stats;
+        if (errorCount > 0) {
+            console.log(chalk.red.bold(`✖ ${errorCount} lint error${errorCount > 1 ? 's' : ''}${warningCount > 0 ? ` and ${warningCount} warning${warningCount > 1 ? 's' : ''}` : ''} found.\n`));
+            process.exit(1);
+        }
+        else if (warningCount > 0) {
+            console.log(chalk.yellow.bold(`⚠ ${warningCount} lint warning${warningCount > 1 ? 's' : ''} found.\n`));
+            if (options.strict) {
+                process.exit(1);
+            }
+        }
+    }
+    catch (err) {
+        console.error(chalk.red(`\n✖ Fatal error during linting: ${err?.message || err}\n`));
+        process.exit(2);
+    }
+}

package/dist/commands/refactor.d.ts

@@ -1,3 +1,4 @@
+import { RefactorResult } from '../refactor/refactor-engine.js';
 export interface RefactorCommandOptions {
     cwd?: string;
     dryRun?: boolean;
@@ -5,4 +6,4 @@ export interface RefactorCommandOptions {
     from?: string;
     to?: string;
 }
-export declare function refactorCommand(entityType?: string, oldName?: string, newName?: string, options?: RefactorCommandOptions): Promise<void>;
+export declare function refactorCommand(entityType?: string, oldName?: string, newName?: string, options?: RefactorCommandOptions): Promise<RefactorResult>;

package/dist/commands/refactor.js

@@ -5,52 +5,142 @@ export async function refactorCommand(entityType, oldName, newName, options = {}
     let targetType = 'page-object';
     let fromSymbol = oldName || '';
     let toSymbol = newName || '';
-    if (options.from && options.to) {
-        // Path-based refactoring
-        if (options.from.includes('page-objects')) {
-            targetType = 'page-object';
-            fromSymbol = path.basename(options.from);
-            toSymbol = path.basename(options.to);
+    // 1. Path-based refactoring via --from and --to flags
+    if (options.from || options.to) {
+        if (!options.from || !options.to) {
+            const errorMsg = 'Both --from and --to must be specified for path-based refactoring.';
+            const result = {
+                status: 'failed',
+                entityType: 'page-object',
+                oldSymbol: options.from || '',
+                newSymbol: options.to || '',
+                modifiedFiles: [],
+                occurrencesReplaced: 0,
+                error: errorMsg,
+            };
+            if (options.json) {
+                console.log(JSON.stringify(result, null, 2));
+            }
+            else {
+                console.error(`\x1b[31m✗ ${errorMsg}\x1b[0m`);
+            }
+            process.exitCode = 1;
+            return result;
         }
-        else if (options.from.includes('steps')) {
-            targetType = 'step';
-            fromSymbol = path.basename(options.from);
-            toSymbol = path.basename(options.to);
+        const pathResult = await RefactorEngine.renameFromPaths({
+            workspaceRoot,
+            fromPath: options.from,
+            toPath: options.to,
+            dryRun: options.dryRun,
+        });
+        if (options.json) {
+            console.log(JSON.stringify(pathResult, null, 2));
+            if (pathResult.status === 'failed') {
+                process.exitCode = 1;
+            }
+            return pathResult;
         }
-        else if (options.from.includes('actions')) {
-            targetType = 'action';
-            fromSymbol = path.basename(options.from);
-            toSymbol = path.basename(options.to);
+        if (pathResult.status === 'success') {
+            const modeStr = options.dryRun ? '[Dry-Run] ' : '';
+            console.log(`\x1b[32m✓ ${modeStr}Refactored ${pathResult.entityType} "${pathResult.oldSymbol}" → "${pathResult.newSymbol}"\x1b[0m`);
+            console.log(`  Modified files: ${pathResult.modifiedFiles.length}`);
+            console.log(`  Occurrences replaced: ${pathResult.occurrencesReplaced}`);
+            for (const f of pathResult.modifiedFiles) {
+                console.log(`    ↳ ${f}`);
+            }
         }
-        else if (options.from.includes('fixtures')) {
-            targetType = 'fixture';
-            fromSymbol = path.parse(options.from).name;
-            toSymbol = path.parse(options.to).name;
+        else {
+            console.error(`\x1b[31m✗ Refactoring failed: ${pathResult.error}\x1b[0m`);
+            process.exitCode = 1;
         }
+        return pathResult;
     }
-    else {
-        if (!entityType || !oldName || !newName) {
-            console.error('Usage: spectra refactor <page-object|step|action|fixture> <oldName> <newName>');
-            process.exit(1);
+    // 2. Also support positional path syntax: spectra refactor <fromPath> <toPath>
+    if (entityType && oldName && !newName && RefactorEngine.parseEntityFromPath(entityType)) {
+        const pathResult = await RefactorEngine.renameFromPaths({
+            workspaceRoot,
+            fromPath: entityType,
+            toPath: oldName,
+            dryRun: options.dryRun,
+        });
+        if (options.json) {
+            console.log(JSON.stringify(pathResult, null, 2));
+            if (pathResult.status === 'failed') {
+                process.exitCode = 1;
+            }
+            return pathResult;
         }
-        const normalized = entityType.toLowerCase().replace(/_/g, '-');
-        if (['page-object', 'po', 'page'].includes(normalized)) {
-            targetType = 'page-object';
+        if (pathResult.status === 'success') {
+            const modeStr = options.dryRun ? '[Dry-Run] ' : '';
+            console.log(`\x1b[32m✓ ${modeStr}Refactored ${pathResult.entityType} "${pathResult.oldSymbol}" → "${pathResult.newSymbol}"\x1b[0m`);
+            console.log(`  Modified files: ${pathResult.modifiedFiles.length}`);
+            console.log(`  Occurrences replaced: ${pathResult.occurrencesReplaced}`);
+            for (const f of pathResult.modifiedFiles) {
+                console.log(`    ↳ ${f}`);
+            }
         }
-        else if (['step', 'steps'].includes(normalized)) {
-            targetType = 'step';
+        else {
+            console.error(`\x1b[31m✗ Refactoring failed: ${pathResult.error}\x1b[0m`);
+            process.exitCode = 1;
         }
-        else if (['action', 'actions'].includes(normalized)) {
-            targetType = 'action';
+        return pathResult;
+    }
+    // 3. Positional syntax: spectra refactor <entityType> <oldName> <newName>
+    if (!entityType || !oldName || !newName) {
+        const errorMsg = 'Usage: spectra refactor <page-object|step|action|fixture> <oldName> <newName> or spectra refactor --from <path> --to <path>';
+        const result = {
+            status: 'failed',
+            entityType: 'page-object',
+            oldSymbol: oldName || '',
+            newSymbol: newName || '',
+            modifiedFiles: [],
+            occurrencesReplaced: 0,
+            error: errorMsg,
+        };
+        if (options.json) {
+            console.log(JSON.stringify(result, null, 2));
         }
-        else if (['fixture', 'fixtures'].includes(normalized)) {
-            targetType = 'fixture';
+        else {
+            console.error(errorMsg);
+        }
+        process.exitCode = 1;
+        return result;
+    }
+    const normalized = entityType.toLowerCase().replace(/_/g, '-');
+    if (['page-object', 'po', 'page', 'pageobject'].includes(normalized)) {
+        targetType = 'page-object';
+    }
+    else if (['step', 'steps'].includes(normalized)) {
+        targetType = 'step';
+    }
+    else if (['action', 'actions'].includes(normalized)) {
+        targetType = 'action';
+    }
+    else if (['fixture', 'fixtures'].includes(normalized)) {
+        targetType = 'fixture';
+    }
+    else {
+        const errorMsg = `Unknown refactor entity type: "${entityType}". Valid types: page-object, step, action, fixture.`;
+        const result = {
+            status: 'failed',
+            entityType: 'page-object',
+            oldSymbol: oldName,
+            newSymbol: newName,
+            modifiedFiles: [],
+            occurrencesReplaced: 0,
+            error: errorMsg,
+        };
+        if (options.json) {
+            console.log(JSON.stringify(result, null, 2));
         }
         else {
-            console.error(`Unknown refactor entity type: "${entityType}". Valid types: page-object, step, action, fixture.`);
-            process.exit(1);
+            console.error(`\x1b[31m✗ ${errorMsg}\x1b[0m`);
         }
+        process.exitCode = 1;
+        return result;
     }
+    fromSymbol = oldName;
+    toSymbol = newName;
     const result = await RefactorEngine.renameSymbol({
         workspaceRoot,
         type: targetType,
@@ -60,7 +150,10 @@ export async function refactorCommand(entityType, oldName, newName, options = {}
     });
     if (options.json) {
         console.log(JSON.stringify(result, null, 2));
-        return;
+        if (result.status === 'failed') {
+            process.exitCode = 1;
+        }
+        return result;
     }
     if (result.status === 'success') {
         const modeStr = options.dryRun ? '[Dry-Run] ' : '';
@@ -73,6 +166,7 @@ export async function refactorCommand(entityType, oldName, newName, options = {}
     }
     else {
         console.error(`\x1b[31m✗ Refactoring failed: ${result.error}\x1b[0m`);
-        process.exit(1);
+        process.exitCode = 1;
     }
+    return result;
 }

package/dist/commands/run.d.ts

@@ -12,7 +12,6 @@ export interface RunCommandOptions {
     workdir?: string;
     output?: string;
     demo?: boolean;
-    baseUrl?: string;
     failed?: boolean | string;
     concurrency?: string | number;
     licenseKey?: string;
@@ -28,5 +27,5 @@ export declare function renderTimingBreakdown(performance: {
     wallClockDurationMs?: number;
     totalTests?: number;
     duration?: string;
-}): void;
-export declare function runCommand(specPath?: string, options?: RunCommandOptions): Promise<void>;
+}, platform?: string): void;
+export declare function runCommand(specPaths?: string[], options?: RunCommandOptions): Promise<void>;

package/dist/commands/run.js

@@ -5,6 +5,7 @@ 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';
@@ -46,6 +47,11 @@ function renderSummaryCard(options) {
     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);
@@ -53,7 +59,7 @@ function renderSummaryCard(options) {
     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}`, `${options.passedCount > 0 ? `${green}${options.passedCount} passed${reset}` : `${options.passedCount} passed`}, ` +
+    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}`));
@@ -64,7 +70,13 @@ function renderSummaryCard(options) {
     }
     console.log(`${bot}\n`);
 }
-export function renderTimingBreakdown(performance) {
+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';
@@ -89,20 +101,31 @@ export function renderTimingBreakdown(performance) {
     console.log(`${borderColor}┌──────────────────────────────────────────┬───────────────────┐${reset}`);
     console.log(`${borderColor}│${reset} Execution Phase                          ${borderColor}│${reset} Duration / Detail ${borderColor}│${reset}`);
     console.log(`${borderColor}├──────────────────────────────────────────┼───────────────────┤${reset}`);
-    console.log(`${borderColor}│${reset} 1. Master Chromium Process Boot          ${borderColor}│${reset} ${pad(performance.masterBootLatencyMs ?? 0, 13)} ms ${borderColor}│${reset}`);
-    console.log(`${borderColor}│${reset} 2. Worker Spawning & Runtime Overhead    ${borderColor}│${reset} ${pad(performance.runnerOverheadMs ?? 0, 13)} ms ${borderColor}│${reset}`);
-    console.log(`${borderColor}│${reset} 3. Incognito Context & CDP Handshake     ${borderColor}│${reset} ${pad(contextHandshakeMs, 10)} ms (avg)${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} 5. Context Teardown / Cleanup            ${borderColor}│${reset} ${pad(performance.avgTeardownMs ?? 0, 10)} ms (avg)${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(specPath, options = {}) {
+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);
+    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;
@@ -135,6 +158,7 @@ export async function runCommand(specPath, options = {}) {
     }
     const config = await ConfigLoader.loadConfig(cwd);
     let demoServer = null;
+    let apiServer = null;
     try {
         if (options.demo) {
             demoServer = new DemoServer(5173);
@@ -146,9 +170,14 @@ export async function runCommand(specPath, options = {}) {
             catch (err) {
                 console.warn(`\x1b[33m[TestSpectra] Warning: Could not start built-in demo server: ${err.message}\x1b[0m`);
             }
-        }
-        if (options.baseUrl) {
-            config.webConfig.baseUrl = options.baseUrl;
+            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`);
+            }
         }
         if (options.headed) {
             config.webConfig.headless = false;
@@ -207,7 +236,7 @@ export async function runCommand(specPath, options = {}) {
             targetDevice,
             licenseKey: options.licenseKey,
             outputJsonPath,
-            spec: effectiveSpecPath,
+            specs: effectiveSpecPaths,
             concurrency: userConcurrency,
             failedOnly: isFailedMode,
             failedTarget,
@@ -216,16 +245,41 @@ export async function runCommand(specPath, options = {}) {
         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 testCount = (result.passedCount ?? 0) + (result.failedCount ?? 0);
+        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;
-                    testCount = fullReport.summary.totalTests ?? testCount;
                 }
                 if (fullReport.suites && Array.isArray(fullReport.suites)) {
                     failedSuites = fullReport.suites.filter((s) => (typeof s.failed === 'number' && s.failed > 0) ||
@@ -235,16 +289,17 @@ export async function runCommand(specPath, options = {}) {
                 }
                 if (fullReport.performance) {
                     renderSummaryCard({
-                        isPassed,
-                        statusText: isPassed ? 'PASSED' : 'FAILED',
-                        duration: result.duration,
+                        isPassed: overallPassed,
+                        statusText: overallPassed ? 'PASSED' : 'FAILED',
+                        duration: finalDuration,
                         platform,
                         suiteCount,
                         passedSuites,
                         failedSuites,
-                        testCount,
-                        passedCount: result.passedCount ?? (isPassed ? testCount : 0),
-                        failedCount: result.failedCount ?? (isPassed ? 0 : testCount),
+                        testCount: totalTests,
+                        passedCount: totalPassed,
+                        failedCount: totalFailed,
+                        carriedPassed,
                         reportPath: relReport,
                         networkReportPath: relNetworkReport,
                     });
@@ -252,8 +307,11 @@ export async function runCommand(specPath, options = {}) {
                         ...fullReport.performance,
                         wallClockDurationMs: fullReport.wallClockDurationMs,
                         duration: fullReport.duration,
-                        totalTests: fullReport.summary?.totalTests ?? testCount,
-                    });
+                        totalTests: fullReport.summary?.totalTests ?? totalTests,
+                    }, platform);
+                    if (!overallPassed || totalFailed > 0) {
+                        process.exitCode = 1;
+                    }
                     return;
                 }
             }
@@ -262,19 +320,23 @@ export async function runCommand(specPath, options = {}) {
             }
         }
         renderSummaryCard({
-            isPassed,
-            statusText: isPassed ? 'PASSED' : 'FAILED',
-            duration: result.duration,
+            isPassed: overallPassed,
+            statusText: overallPassed ? 'PASSED' : 'FAILED',
+            duration: finalDuration,
             platform,
             suiteCount,
             passedSuites,
             failedSuites,
-            testCount,
-            passedCount: result.passedCount ?? (isPassed ? testCount : 0),
-            failedCount: result.failedCount ?? (isPassed ? 0 : testCount),
+            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);
@@ -284,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.js

@@ -5,6 +5,7 @@ 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) {

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>;