@testspectra/cli 1.1.8-rc.3 → 1.1.8-rc.30

package/README.md

@@ -37,6 +37,56 @@ pnpm --filter @testspectra/cli dev
 
 ---
 
+## 🌍 Native Binary Distribution (Multiplatform Releases)
+
+`spectra run` shells out to `testspectra-runner`, a native Rust binary (`core/`) — it isn't
+portable JS, so one npm package can't ship a single binary that works on every OS/arch. Instead,
+`@testspectra/cli` follows the same pattern as esbuild/swc/turbo:
+
+- `@testspectra/cli` itself ships **no native binary** — only the JS launcher (`bin/spectra.js`).
+- The binary is published as three separate, platform-locked packages under `cli/npm/`:
+  - `@testspectra/cli-darwin-arm64`
+  - `@testspectra/cli-win32-x64`
+  - `@testspectra/cli-linux-x64`
+
+  (Windows arm64 has no native build — `resolveBinaryPath()` throws a clear "not supported"
+  error there instead of pointing at a package that was never published.)
+
+  Each has `os`/`cpu` fields in its `package.json`, so npm/pnpm/yarn only ever download the one
+  matching the installing machine.
+
+- `@testspectra/cli` lists all three as `optionalDependencies`, pinned to an exact version (not
+  `^`) that always matches the `@testspectra/cli` release it ships with.
+- At runtime, `RustCoreBridge.resolveBinaryPath()` (`cli/src/runner/bridge.ts`) resolves the
+  binary from whichever platform package got installed (`require.resolve('@testspectra/cli-<platform>/package.json')`),
+  falling back to the monorepo's local build output (`core/target/release/...`) for local dev
+  where no optional package is installed.
+- If a user's platform/arch isn't one of the three above, install succeeds (optional deps just
+  get skipped) but `resolveBinaryPath()` throws a clear "not supported" error at run time.
+
+### Building & releasing all platforms
+
+`scripts/build-cross-platform-binaries.js` builds the binary for all three platforms from a
+single macOS machine and copies each into `cli/npm/<platform>/bin/`:
+
+- **macOS arm64** — native `cargo build` (this machine only builds arm64; there's no x64 macOS
+  package).
+- **Windows x64** — cross-compiled via [`cargo-xwin`](https://github.com/rust-cross/cargo-xwin)
+  (`cargo install cargo-xwin`), which downloads the MSVC CRT/Windows SDK bits needed for linking.
+  reqwest's default `native-tls` backend uses Schannel on Windows, so no OpenSSL cross-compile
+  headaches here.
+- **Linux x64 (glibc)** — cross-compiled via [`cross`](https://github.com/cross-rs/cross)
+  (`cargo install cross --git https://github.com/cross-rs/cross`), which builds inside a Docker
+  container that already has a matching glibc + OpenSSL for the target — required because
+  `native-tls` needs OpenSSL on Linux and cross-compiling OpenSSL from macOS directly is painful.
+  Docker must be running for this step.
+
+`scripts/release-cli-local.sh` runs this automatically, then stamps every `cli/npm/*/package.json`
+and `cli/package.json`'s `optionalDependencies` with the target version, packs all four tarballs,
+and (with `--publish`) publishes the three platform packages before `@testspectra/cli` itself.
+
+---
+
 ## 💻 CLI Commands Summary
 
 | Command           | Usage                                       | Description                                                             |

package/bin/.testspectra-runner.hash

@@ -1 +1 @@
-ee8892a6b2c4c19bf5da415da3d29172023c383de2d12c0080b5dc61dc339af3
+2db95c618fc201b3c5e4b2f56e93c5e5fca36ba0d31250c65c98aabed5385361

package/dist/commands/__tests__/doctor-filter.test.js

@@ -0,0 +1,37 @@
+import { describe, it, expect, vi } from 'vitest';
+const { execFileSyncMock } = vi.hoisted(() => ({ execFileSyncMock: vi.fn() }));
+vi.mock('child_process', () => ({
+    execFileSync: execFileSyncMock,
+    spawn: vi.fn(),
+}));
+vi.mock('../../runner/bridge.js', () => ({
+    RustCoreBridge: { resolveBinaryPath: () => '/fake/testspectra-runner' },
+}));
+import { runSystemChecks } from '../doctor.js';
+const EMPTY = JSON.stringify({ all_ready: true, missing_count: 0, dependencies: [] });
+describe('runSystemChecks filter forwarding', () => {
+    it('forwards a category scope to the runner', async () => {
+        execFileSyncMock.mockReturnValueOnce(EMPTY);
+        await runSystemChecks('/tmp/ws', { scope: 'web' });
+        const [, args] = execFileSyncMock.mock.calls.at(-1);
+        expect(args).toEqual(['doctor', '--json', '--scope', 'web']);
+    });
+    it('forwards a fine-grained --only filter (single dependency)', async () => {
+        execFileSyncMock.mockReturnValueOnce(EMPTY);
+        await runSystemChecks('/tmp/ws', { only: 'chrome' });
+        const [, args] = execFileSyncMock.mock.calls.at(-1);
+        expect(args).toEqual(['doctor', '--json', '--only', 'chrome']);
+    });
+    it('forwards both scope and only when provided', async () => {
+        execFileSyncMock.mockReturnValueOnce(EMPTY);
+        await runSystemChecks('/tmp/ws', { scope: 'web', only: 'chrome,adb' });
+        const [, args] = execFileSyncMock.mock.calls.at(-1);
+        expect(args).toEqual(['doctor', '--json', '--scope', 'web', '--only', 'chrome,adb']);
+    });
+    it('omits filters entirely when none are requested (full doctor)', async () => {
+        execFileSyncMock.mockReturnValueOnce(EMPTY);
+        await runSystemChecks('/tmp/ws');
+        const [, args] = execFileSyncMock.mock.calls.at(-1);
+        expect(args).toEqual(['doctor', '--json']);
+    });
+});

package/dist/commands/__tests__/doctor-scope.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/commands/__tests__/doctor-scope.test.js

@@ -0,0 +1,24 @@
+import { describe, it, expect, vi } from 'vitest';
+const { execFileSyncMock } = vi.hoisted(() => ({ execFileSyncMock: vi.fn() }));
+vi.mock('child_process', () => ({
+    execFileSync: execFileSyncMock,
+    spawn: vi.fn(),
+}));
+vi.mock('../../runner/bridge.js', () => ({
+    RustCoreBridge: { resolveBinaryPath: () => '/fake/testspectra-runner' },
+}));
+import { runSystemChecks } from '../doctor.js';
+describe('runSystemChecks scope forwarding', () => {
+    it('forwards a category scope to the runner (efficient partial doctor)', async () => {
+        execFileSyncMock.mockReturnValueOnce(JSON.stringify({ all_ready: true, missing_count: 0, dependencies: [] }));
+        await runSystemChecks('/tmp/ws', 'web');
+        const [, args] = execFileSyncMock.mock.calls.at(-1);
+        expect(args).toEqual(['doctor', '--json', '--scope', 'web']);
+    });
+    it('omits --scope entirely when no scope is requested (full doctor)', async () => {
+        execFileSyncMock.mockReturnValueOnce(JSON.stringify({ all_ready: true, missing_count: 0, dependencies: [] }));
+        await runSystemChecks('/tmp/ws');
+        const [, args] = execFileSyncMock.mock.calls.at(-1);
+        expect(args).toEqual(['doctor', '--json']);
+    });
+});

package/dist/commands/__tests__/run-e2e.test.js

@@ -146,10 +146,10 @@ describe('End-to-End (E2E) Test Plan: Native Orchestrator Execution (docs/v2/cor
         // Inject a failing step / invalid selector in a new test case
         const failingDir = path.join(tmpDir, 'specs', 'Playground', 'TC-0099-failing');
         fs.mkdirSync(failingDir, { recursive: true });
-        fs.writeFileSync(path.join(failingDir, 'web.test.ts'), `it("should fail when element does not exist", async () => {
-  await Step.verifyPlaygroundState();
-  await $("#non-existent-button-999").shouldBeVisible();
-});
+        fs.writeFileSync(path.join(failingDir, 'web.test.ts'), `it("should fail when element does not exist", async () => {
+  await Step.verifyPlaygroundState();
+  await $("#non-existent-button-999").shouldBeVisible();
+});
 `, 'utf-8');
         // Mock exit to prevent process termination during unit test assertion
         const exitSpy = vi.spyOn(process, 'exit').mockImplementation((() => { }));
@@ -166,13 +166,13 @@ describe('End-to-End (E2E) Test Plan: Native Orchestrator Execution (docs/v2/cor
         // 1. Test a valid spec using pure Spectra static commands
         const spectraStaticDir = path.join(tmpDir, 'specs', 'Playground', 'TC-0100-spectra-static');
         fs.mkdirSync(spectraStaticDir, { recursive: true });
-        fs.writeFileSync(path.join(spectraStaticDir, 'web.test.ts'), `it("should execute via unified Spectra static object", async () => {
-  await Spectra.navigate("/#playground");
-  await Spectra.type("#demo-email-input-pg", "automated@spectra.dev");
-  await Spectra.get("#demo-email-input-pg").shouldHaveValue("automated@spectra.dev");
-  await Spectra.wait(50);
-  await Spectra.getAll(".demo-product-item").shouldHaveLengthGreaterThan(0);
-});
+        fs.writeFileSync(path.join(spectraStaticDir, 'web.test.ts'), `it("should execute via unified Spectra static object", async () => {
+  await Spectra.navigate("/#playground");
+  await Spectra.type("#demo-email-input-pg", "automated@spectra.dev");
+  await Spectra.get("#demo-email-input-pg").shouldHaveValue("automated@spectra.dev");
+  await Spectra.wait(50);
+  await Spectra.getAll(".demo-product-item").shouldHaveLengthGreaterThan(0);
+});
 `, 'utf-8');
         await runCommand(['specs/Playground/TC-0100-spectra-static/web.test.ts'], { target: 'web', demo: true });
         const resultStatic = JSON.parse(fs.readFileSync(path.join(tmpDir, '.testspectra', 'reports', 'result.json'), 'utf-8'));
@@ -181,11 +181,11 @@ describe('End-to-End (E2E) Test Plan: Native Orchestrator Execution (docs/v2/cor
         // 2. Test that assertion mismatch on existing element strictly FAILS (no false positive)
         const mismatchDir = path.join(tmpDir, 'specs', 'Playground', 'TC-0101-mismatch');
         fs.mkdirSync(mismatchDir, { recursive: true });
-        fs.writeFileSync(path.join(mismatchDir, 'web.test.ts'), `it("should strictly fail when assertion text does not match", async () => {
-  await Spectra.navigate("/#playground");
-  // Element exists, but text is wrong -> MUST throw and fail
-  await Spectra.get("#demo-email-input-pg").shouldHaveValue("completely_wrong_value_xyz");
-});
+        fs.writeFileSync(path.join(mismatchDir, 'web.test.ts'), `it("should strictly fail when assertion text does not match", async () => {
+  await Spectra.navigate("/#playground");
+  // Element exists, but text is wrong -> MUST throw and fail
+  await Spectra.get("#demo-email-input-pg").shouldHaveValue("completely_wrong_value_xyz");
+});
 `, 'utf-8');
         const exitSpy = vi.spyOn(process, 'exit').mockImplementation((() => { }));
         await runCommand(['specs/Playground/TC-0101-mismatch/web.test.ts'], { target: 'web', demo: true });
@@ -375,39 +375,39 @@ describe('End-to-End (E2E) Test Plan: Native Orchestrator Execution (docs/v2/cor
     it('E2E-10: Spectra.intercept FIFO respondOnce sequential polling and abort simulation in real Chromium', async () => {
         const fifoAbortDir = path.join(tmpDir, 'specs', 'ApiInterception', 'TC-0010-fifo-abort');
         fs.mkdirSync(fifoAbortDir, { recursive: true });
-        fs.writeFileSync(path.join(fifoAbortDir, 'web.test.ts'), `it("should handle FIFO respondOnce queue and abort simulation", async () => {
-  await MatchersPage.open("api-fetch");
-
-  // Setup intercept with default fallback and FIFO queue
-  const mock = await Spectra.intercept("api/posts", "GET", [
-    { id: 999, title: "Default Fallback Post" }
-  ]);
-
-  await mock.respondOnce([
-    { id: 101, title: "FIFO Queued Post #1" }
-  ]);
-  await mock.respondOnce([
-    { id: 102, title: "FIFO Queued Post #2" }
-  ]);
-
-  // 1. First fetch triggers FIFO item #1
-  await MatchersPage.fetchApiButton.click();
-  await MatchersPage.fetchedItems.first().shouldContainText("FIFO Queued Post #1");
-
-  // 2. Second fetch triggers FIFO item #2
-  await MatchersPage.fetchApiButton.click();
-  await MatchersPage.fetchedItems.first().shouldContainText("FIFO Queued Post #2");
-
-  // 3. Third fetch falls back to default response
-  await MatchersPage.fetchApiButton.click();
-  await MatchersPage.fetchedItems.first().shouldContainText("Default Fallback Post");
-
-  // 4. Test abort simulation
-  await mock.abort("Failed");
-  await MatchersPage.fetchApiButton.click();
-  // On network failure, demo app shows fallback 200 OK from catch block
-  await MatchersPage.fetchStatusBadge.shouldHaveText("200 OK");
-});
+        fs.writeFileSync(path.join(fifoAbortDir, 'web.test.ts'), `it("should handle FIFO respondOnce queue and abort simulation", async () => {
+  await MatchersPage.open("api-fetch");
+
+  // Setup intercept with default fallback and FIFO queue
+  const mock = await Spectra.intercept("api/posts", "GET", [
+    { id: 999, title: "Default Fallback Post" }
+  ]);
+
+  await mock.respondOnce([
+    { id: 101, title: "FIFO Queued Post #1" }
+  ]);
+  await mock.respondOnce([
+    { id: 102, title: "FIFO Queued Post #2" }
+  ]);
+
+  // 1. First fetch triggers FIFO item #1
+  await MatchersPage.fetchApiButton.click();
+  await MatchersPage.fetchedItems.first().shouldContainText("FIFO Queued Post #1");
+
+  // 2. Second fetch triggers FIFO item #2
+  await MatchersPage.fetchApiButton.click();
+  await MatchersPage.fetchedItems.first().shouldContainText("FIFO Queued Post #2");
+
+  // 3. Third fetch falls back to default response
+  await MatchersPage.fetchApiButton.click();
+  await MatchersPage.fetchedItems.first().shouldContainText("Default Fallback Post");
+
+  // 4. Test abort simulation
+  await mock.abort("Failed");
+  await MatchersPage.fetchApiButton.click();
+  // On network failure, demo app shows fallback 200 OK from catch block
+  await MatchersPage.fetchStatusBadge.shouldHaveText("200 OK");
+});
 `, 'utf-8');
         await runCommand(['specs/ApiInterception/TC-0010-fifo-abort/web.test.ts'], { target: 'web' });
         const resultJsonPath = path.join(tmpDir, '.testspectra', 'reports', 'result.json');

package/dist/commands/__tests__/test-error-streaming.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/commands/__tests__/test-error-streaming.test.js

@@ -0,0 +1,85 @@
+import { describe, expect, it, vi } from 'vitest';
+import { isVitestNoise, sanitizeErrorMessage } from '@testspectra/react';
+import { Reporter } from '../../runner/reporter.js';
+describe('spectra test error streaming and formatting', () => {
+    it('sanitizes Vitest/Vite error messages without leaking behind-the-scenes tooling', () => {
+        const rawError = 'Failed to fetch dynamically imported module: http://localhost:63315/@fs/D:/wangs-ui-react/packages/testing-library/page-objects/AccordionComponent/web.ts?import';
+        const sanitized = sanitizeErrorMessage(rawError);
+        expect(sanitized).toBe('Failed to load module: D:/wangs-ui-react/packages/testing-library/page-objects/AccordionComponent/web.ts');
+        expect(sanitized).not.toContain('localhost');
+        expect(sanitized).not.toContain('@fs');
+        expect(sanitized).not.toContain('?import');
+    });
+    it('filters Vitest CLI runner noise while allowing actual errors through', () => {
+        expect(isVitestNoise('RUN  v2.1.8 /Volumes/Home/TestSpectra')).toBe(true);
+        expect(isVitestNoise('Test Files  1 failed (1)')).toBe(true);
+        expect(isVitestNoise('⎯⎯⎯⎯⎯⎯⎯ Failed Suites 1 ⎯⎯⎯⎯⎯⎯⎯')).toBe(true);
+        expect(isVitestNoise('Re-optimizing dependencies because vite config has changed')).toBe(true);
+        expect(isVitestNoise('Error: Cannot find module "./Button"')).toBe(false);
+        expect(isVitestNoise('SyntaxError: Unexpected token (10:15)')).toBe(false);
+    });
+    it('formats multi-line errors with clean indentation in Reporter', () => {
+        const reporter = new Reporter();
+        reporter.addLog({
+            timestamp: '12:00:00',
+            level: 'INFO',
+            message: '[TESTSPECTRA_TEST_START] {"title":"specs/Accordion/TC-0009/web.test.tsx"}',
+        });
+        reporter.addLog({
+            timestamp: '12:00:00',
+            level: 'INFO',
+            message: '[TESTSPECTRA_TEST_ERROR] Failed to load module: D:/wangs-ui-react/page-objects/Accordion/web.ts',
+        });
+        reporter.addLog({
+            timestamp: '12:00:00',
+            level: 'INFO',
+            message: '[TESTSPECTRA_TEST_FAIL] specs/Accordion/TC-0009/web.test.tsx (0ms)',
+        });
+        const result = reporter.generateResult('failed', '0.1s');
+        expect(result.failedCount).toBe(1);
+        expect(result.passedCount).toBe(0);
+        expect(result.status).toBe('failed');
+    });
+    it('prints error message below test title and steps on failure', () => {
+        const reporter = new Reporter();
+        const consoleLogs = [];
+        const spy = vi.spyOn(console, 'log').mockImplementation((msg) => {
+            if (typeof msg === 'string')
+                consoleLogs.push(msg);
+        });
+        reporter.addLog({
+            timestamp: '12:00:00',
+            level: 'INFO',
+            message: '[TESTSPECTRA_TEST_START] {"title":"ApiInterception / TC-0009-post-mocking"}',
+        });
+        reporter.addLog({
+            timestamp: '12:00:00',
+            level: 'INFO',
+            message: '[TESTSPECTRA_STEP_PASS] {"type":"action","key":"navigate","args":["/#api-post"],"test":"ApiInterception / TC-0009-post-mocking"} (8ms)',
+        });
+        reporter.addLog({
+            timestamp: '12:00:00',
+            level: 'INFO',
+            message: '[TESTSPECTRA_STEP_FAIL] {"type":"assertion","target":"#post-status-badge","args":["201 Created"],"test":"ApiInterception / TC-0009-post-mocking"} (2005ms)',
+        });
+        reporter.addLog({
+            timestamp: '12:00:00',
+            level: 'INFO',
+            message: '[TESTSPECTRA_TEST_ERROR] Expected element "#post-status-badge" to have text "201 Created", but got ""',
+        });
+        reporter.addLog({
+            timestamp: '12:00:00',
+            level: 'INFO',
+            message: '[TESTSPECTRA_TEST_FAIL] ApiInterception / TC-0009-post-mocking (2066ms)',
+        });
+        spy.mockRestore();
+        const titleIndex = consoleLogs.findIndex((log) => log.includes('ApiInterception / TC-0009-post-mocking'));
+        const stepPassIndex = consoleLogs.findIndex((log) => log.includes('Navigate to'));
+        const stepFailIndex = consoleLogs.findIndex((log) => log.includes('#post-status-badge'));
+        const errorIndex = consoleLogs.findIndex((log) => log.includes('↳ Error:'));
+        expect(titleIndex).toBeGreaterThanOrEqual(0);
+        expect(stepPassIndex).toBeGreaterThan(titleIndex);
+        expect(stepFailIndex).toBeGreaterThan(stepPassIndex);
+        expect(errorIndex).toBeGreaterThan(stepFailIndex);
+    });
+});

package/dist/commands/__tests__/test-scaffolding.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/commands/__tests__/test-scaffolding.test.js

@@ -0,0 +1,32 @@
+import fs from 'fs';
+import os from 'os';
+import path from 'path';
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import { ensureTestSpectraScaffolding } from '../test.js';
+describe('spectra test pre-flight scaffolding (docs/v2/features/component-testing/react/README.md)', () => {
+    let tmpDir;
+    beforeEach(() => {
+        tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'testspectra-test-scaffold-'));
+    });
+    afterEach(() => {
+        try {
+            fs.rmSync(tmpDir, { recursive: true, force: true });
+        }
+        catch { }
+    });
+    it('generates the .testspectra solution tsconfig when it is missing (clean clone / CI)', () => {
+        const masterConfig = path.join(tmpDir, '.testspectra', 'tsconfig.json');
+        expect(fs.existsSync(masterConfig)).toBe(false);
+        ensureTestSpectraScaffolding(tmpDir);
+        // The exact file `vite:esbuild` tries to read via the root tsconfig's `references` entry.
+        expect(fs.existsSync(masterConfig)).toBe(true);
+        expect(fs.existsSync(path.join(tmpDir, '.testspectra', 'tsconfig', 'web.json'))).toBe(true);
+    });
+    it('leaves an existing scaffolding untouched', () => {
+        const masterConfig = path.join(tmpDir, '.testspectra', 'tsconfig.json');
+        fs.mkdirSync(path.dirname(masterConfig), { recursive: true });
+        fs.writeFileSync(masterConfig, '{"custom":true}\n', 'utf-8');
+        ensureTestSpectraScaffolding(tmpDir);
+        expect(fs.readFileSync(masterConfig, 'utf-8')).toBe('{"custom":true}\n');
+    });
+});

package/dist/commands/__tests__/upgrade.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/commands/__tests__/upgrade.test.js

@@ -0,0 +1,95 @@
+import fs from 'fs';
+import os from 'os';
+import path from 'path';
+import { execFileSync, execSync } from 'child_process';
+import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest';
+import { upgradeCommand } from '../upgrade.js';
+const DOCTOR_JSON = JSON.stringify({
+    all_ready: true,
+    missing_count: 0,
+    dependencies: [
+        {
+            name: 'Google Chrome',
+            category: 'web',
+            installed: true,
+            version: 'Google Chrome 123.0.0.0 (Chrome for Testing)',
+            required: true,
+            required_version: 'Stable / CfT',
+            depends_on: [],
+        },
+        {
+            name: 'Bun',
+            category: 'core',
+            installed: true,
+            version: 'v1.0.0',
+            required: true,
+            required_version: '>=1.0.0',
+            depends_on: [],
+        },
+    ],
+});
+vi.mock('child_process', () => ({
+    execFileSync: vi.fn((_cmd, args) => Array.isArray(args) && args[0] === 'doctor' ? DOCTOR_JSON : '"9.9.9"'),
+    execSync: vi.fn(),
+}));
+describe('upgradeCommand self-upgrade mechanism (docs/v2/features/upgrade-mechanism-and-notifications.md)', () => {
+    let tmpDir;
+    const originalCwd = process.cwd();
+    beforeEach(() => {
+        tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'testspectra-upgrade-test-'));
+        process.chdir(tmpDir);
+        vi.clearAllMocks();
+        vi.stubGlobal('fetch', vi.fn(async (url) => {
+            const href = String(url);
+            if (href.includes('chrome-for-testing')) {
+                return { ok: true, json: async () => ({ channels: { Stable: { version: '999.0.0.0' } } }) };
+            }
+            if (href.includes('github')) {
+                return { ok: true, json: async () => ({ tag_name: 'bun-v2.0.0' }) };
+            }
+            return {
+                ok: true,
+                text: async () => '<remotePackage path="platform-tools"><revision><major>99</major><minor>0</minor><micro>0</micro></revision></remotePackage>',
+            };
+        }));
+    });
+    afterEach(() => {
+        vi.unstubAllGlobals();
+        process.chdir(originalCwd);
+        try {
+            fs.rmSync(tmpDir, { recursive: true, force: true });
+        }
+        catch { }
+    });
+    it('emits a pure JSON payload covering packages and drivers in --json mode', async () => {
+        const logSpy = vi.spyOn(console, 'log').mockImplementation(() => { });
+        await upgradeCommand([], { json: true });
+        expect(logSpy).toHaveBeenCalledTimes(1);
+        const payload = JSON.parse(logSpy.mock.calls[0][0]);
+        expect(payload.packages).toHaveLength(3);
+        expect(payload.packages.every((p) => p.latest === '9.9.9')).toBe(true);
+        expect(payload.drivers).toHaveLength(2);
+        expect(payload.drivers.find((d) => d.name === 'Google Chrome')?.latest).toBe('999.0.0.0');
+        expect(payload.updatesAvailable).toBeGreaterThan(0);
+        expect(execSync).not.toHaveBeenCalled();
+        logSpy.mockRestore();
+    });
+    it('restricts to a single package (no drivers) when package names are passed', async () => {
+        const logSpy = vi.spyOn(console, 'log').mockImplementation(() => { });
+        await upgradeCommand(['@testspectra/cli'], { json: true });
+        const payload = JSON.parse(logSpy.mock.calls[0][0]);
+        expect(payload.packages).toHaveLength(1);
+        expect(payload.packages[0].pkg).toBe('@testspectra/cli');
+        expect(payload.drivers).toHaveLength(0);
+        logSpy.mockRestore();
+    });
+    it('reports available updates in --check mode without running the package manager', async () => {
+        const logSpy = vi.spyOn(console, 'log').mockImplementation(() => { });
+        await upgradeCommand([], { check: true });
+        expect(execFileSync).toHaveBeenCalled();
+        expect(execSync).not.toHaveBeenCalled();
+        const output = logSpy.mock.calls.map((c) => String(c[0])).join('\n');
+        expect(output).toContain('package update(s) available');
+        logSpy.mockRestore();
+    });
+});

package/dist/commands/add.js

@@ -4,6 +4,7 @@ import { fileURLToPath } from 'url';
 import * as p from '@clack/prompts';
 import chalk from 'chalk';
 import { TypeGenerator } from '../types/generator.js';
+import { ConfigLoader } from '../config/loader.js';
 function parsePnpmWorkspaceGlobs(content) {
     const lines = content.split('\n');
     const globs = [];
@@ -107,9 +108,8 @@ export async function addCommand(moduleNameArg, options = {}) {
     let rootDir = cwd;
     let cur = cwd;
     while (cur !== path.dirname(cur)) {
-        if (fs.existsSync(path.join(cur, 'spectra.config.ts')) ||
-            fs.existsSync(path.join(cur, 'pnpm-workspace.yaml')) ||
-            fs.existsSync(path.join(cur, 'nx.json'))) {
+        const hasConfig = ConfigLoader.CONFIG_FILE_NAMES.some((name) => fs.existsSync(path.join(cur, name)));
+        if (hasConfig || fs.existsSync(path.join(cur, 'pnpm-workspace.yaml')) || fs.existsSync(path.join(cur, 'nx.json'))) {
             rootDir = cur;
             break;
         }
@@ -289,6 +289,7 @@ export async function addCommand(moduleNameArg, options = {}) {
         copyRecursive(sampleE2eSrc, targetE2eDir, {
             'playground-e2e': e2eProjectName,
             'packages/playground/e2e': path.relative(rootDir, targetE2eDir).replace(/\\/g, '/'),
+            'testspectra:scope:playground': `testspectra:scope:${featureName}`,
             'scope:playground': `scope:${featureName}`,
         });
         // Adjust project.json
@@ -300,7 +301,7 @@ export async function addCommand(moduleNameArg, options = {}) {
                 pObj.sourceRoot = path.relative(rootDir, targetE2eDir).replace(/\\/g, '/');
                 pObj.targets.e2e.options.cwd = path.relative(rootDir, 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/devices.js

@@ -32,6 +32,7 @@ export async function devicesCommand(options = {}) {
             cwd,
             env: getRunnerEnv(),
             stdio: 'inherit',
+            windowsHide: true,
         });
         child.on('close', (code) => {
             if (code === 0) {

package/dist/commands/docs.d.ts

@@ -0,0 +1,4 @@
+export interface DocsCommandOptions {
+    cwd?: string;
+}
+export declare function docsUpdateCommand(options?: DocsCommandOptions): void;

package/dist/commands/docs.js

@@ -0,0 +1,17 @@
+import path from 'path';
+import chalk from 'chalk';
+import * as p from '@clack/prompts';
+import { generateArchitectureDoc } from '../generator/architecture-doc-generator.js';
+function resolveBaseDir(options = {}) {
+    return options.cwd ? path.resolve(options.cwd) : process.cwd();
+}
+export function docsUpdateCommand(options = {}) {
+    const cwd = resolveBaseDir(options);
+    const result = generateArchitectureDoc(cwd);
+    if (result.mode === 'nx') {
+        p.log.success(chalk.green(`ARCHITECTURE.md regenerated (Nx/monorepo mode, ${result.featureCount ?? 0} feature module(s) detected).`));
+    }
+    else {
+        p.log.success(chalk.green('ARCHITECTURE.md regenerated (standalone mode).'));
+    }
+}

package/dist/commands/doctor.d.ts

@@ -13,9 +13,17 @@ export interface SystemCheckResult {
     missing_count: number;
     dependencies: DependencyStatus[];
 }
-export declare function runSystemChecks(cwd?: string): Promise<SystemCheckResult>;
+export interface SystemCheckOptions {
+    /** Category filter: `core`, `web`, or `mobile` (default: all). */
+    scope?: string;
+    /** Comma-separated specific dependency keys, e.g. `chrome` or `chrome,adb` (takes precedence over `scope`). */
+    only?: string;
+}
+export declare function runSystemChecks(cwd?: string, options?: SystemCheckOptions): Promise<SystemCheckResult>;
 export declare function doctorCommand(options?: {
     fix?: boolean;
     json?: boolean;
     verbose?: boolean;
+    scope?: string;
+    only?: string;
 }): Promise<void>;

package/dist/commands/doctor.js

@@ -9,9 +9,16 @@ function getRunnerEnv() {
         TEST_SPECTRA_DRIVER_CACHE: globalDriversDir,
     };
 }
-export async function runSystemChecks(cwd = process.cwd()) {
+export async function runSystemChecks(cwd = process.cwd(), options = {}) {
     const binPath = RustCoreBridge.resolveBinaryPath();
-    const stdout = execFileSync(binPath, ['doctor', '--json'], {
+    const args = ['doctor', '--json'];
+    if (options.scope) {
+        args.push('--scope', options.scope);
+    }
+    if (options.only) {
+        args.push('--only', options.only);
+    }
+    const stdout = execFileSync(binPath, args, {
         cwd,
         env: getRunnerEnv(),
         encoding: 'utf8',
@@ -29,11 +36,17 @@ export async function doctorCommand(options = {}) {
     if (options.verbose) {
         args.push('--verbose');
     }
+    if (options.scope) {
+        args.push('--scope', options.scope);
+    }
+    if (options.only) {
+        args.push('--only', options.only);
+    }
     if (options.fix) {
         args.push('--fix');
     }
     if (options.json) {
-        const result = await runSystemChecks(cwd);
+        const result = await runSystemChecks(cwd, { scope: options.scope, only: options.only });
         console.log(JSON.stringify(result, null, 2));
         return;
     }
@@ -42,6 +55,7 @@ export async function doctorCommand(options = {}) {
             cwd,
             env: getRunnerEnv(),
             stdio: 'inherit',
+            windowsHide: true,
         });
         child.on('close', (code) => {
             if (code === 0 || options.fix) {