@testspectra/cli 1.1.8-rc.9 → 1.1.11-rc.3

package/README.md

@@ -44,31 +44,34 @@ portable JS, so one npm package can't ship a single binary that works on every O
 `@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 four separate, platform-locked packages under `cli/npm/`:
+- The binary is published as three separate, platform-locked packages under `cli/npm/`:
   - `@testspectra/cli-darwin-arm64`
   - `@testspectra/cli-win32-x64`
-  - `@testspectra/cli-win32-arm64`
   - `@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 four as `optionalDependencies`, pinned to an exact version (not
+
+- `@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 four above, install succeeds (optional deps just
+- 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 four platforms from a
+`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 / arm64** — cross-compiled via [`cargo-xwin`](https://github.com/rust-cross/cargo-xwin)
+- **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.
@@ -79,8 +82,8 @@ single macOS machine and copies each into `cli/npm/<platform>/bin/`:
   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 five tarballs,
-and (with `--publish`) publishes the four platform packages before `@testspectra/cli` itself.
+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.
 
 ---
 

package/bin/.testspectra-runner.hash

@@ -0,0 +1 @@
+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__/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;
         }

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) {

package/dist/commands/init.js

@@ -6,6 +6,7 @@ import chalk from 'chalk';
 import { ConfigLoader } from '../config/loader.js';
 import { TypeGenerator } from '../types/generator.js';
 import { TsConfigGenerator } from '../generator/tsconfig-generator.js';
+import { generateArchitectureDoc } from '../generator/architecture-doc-generator.js';
 function parsePnpmWorkspaceGlobs(content) {
     const lines = content.split('\n');
     const globs = [];
@@ -460,6 +461,8 @@ export async function initCommand(options = {}) {
                     (typeof rootPkg.devDependencies['@testspectra/matchers'] === 'string' &&
                         rootPkg.devDependencies['@testspectra/matchers'].startsWith('link:')))
                     rootPkg.devDependencies['@testspectra/matchers'] = cliDepVersion;
+                if (!rootPkg.devDependencies['nx'])
+                    rootPkg.devDependencies['nx'] = '^20.8.4';
                 if (!rootPkg.devDependencies['typescript'])
                     rootPkg.devDependencies['typescript'] = '^5.4.5';
                 if (!rootPkg.devDependencies['@wdio/cli'])
@@ -558,137 +561,7 @@ export async function initCommand(options = {}) {
         // 7. Generate Ambient Types in ROOT only
         TypeGenerator.writeDeclarationFiles(cwd);
         ensureVsCodeExtensions(cwd);
-        const archDocContent = `# TestSpectra Enterprise Monorepo Architecture
-
-This workspace uses TestSpectra's **"Centralized Configuration, Distributed Implementation"** model for automated cross-platform testing.
-
----
-
-## 1. Directory & File Overview
-
-### Centralized Root Elements
-- \`./spectra.config.ts\`: Single source of truth for runtime configurations (Base URL, Appium devices, browser targets, timeouts).
-- \`./.testspectra/\`: Local test project cache, runtime metadata, auto-generated master TSConfig (\`.testspectra/tsconfig.json\`), platform sub-configs (\`.testspectra/tsconfig/\`), and universal ambient types (\`.testspectra/types/\`). Global binaries and drivers are managed at \`~/.testspectra/drivers/\`.
-- \`./nx.json\`: Nx target defaults with execution caching and inputs.
-- \`./pnpm-workspace.yaml\`: Monorepo package glob definitions.
-- \`./tsconfig.json\`: Solution-style TypeScript orchestrator referencing \`./.testspectra/tsconfig.json\`.
-
-### Centralized Shared Testing Library (\`./${sharedTestingRelPath}\`)
-Provides cross-feature reusable test entities with **100% zero-import global resolution**:
-- \`page-objects/\`: Shared Page Object models (e.g. NavigationBar, AppHeader).
-- \`steps/\`: Cross-feature business step flows (e.g. \`Step.loginAsAdmin()\`).
-- \`actions/\`: Custom atomic actions (e.g. \`Spectra.dismissBanner()\`).
-- \`fixtures/\`: Common test data and environment configurations (e.g. \`Fixture.appConfig\`).
-
-### Distributed Feature E2E Modules (${featureE2eDirs.length} Features)
-${featureE2eDirs
-            .map((d) => {
-            const rel = path.relative(cwd, d);
-            const name = path.basename(path.dirname(d));
-            const e2eName = `${name}-${e2eFolderName}`;
-            return `- \`./${rel}\` (**${name}**, Nx Project: \`${e2eName}\`):
-  - \`specs/\`: Feature test cases (\`specs/<SuiteName>/<CaseId>/\` with \`web.test.ts\`, \`android.test.ts\`, \`ios.test.ts\`).
-  - \`page-objects/\`: Feature-specific Page Objects (e.g. \`LoginPage\`, \`ProductPage\`).
-  - \`project.json\`: Nx targets (\`e2e\`, \`type-check\`) supporting configurations (\`--configuration=android\`, \`--configuration=ios\`, \`--configuration=headless\`).`;
-        })
-            .join('\n')}
-
----
-
-## 2. Zero-Import Consumption Flow & Mechanics
-
-TestSpectra completely eliminates boilerplate \`import\` statements across all test specs, steps, and page objects.
-
-### How It Works:
-1. **Centralized Ambient Aggregation**:  
-   TestSpectra Language Service Plugin & CLI automatically scan:
-   - **Local Feature Entities**: \`<feature>/${e2eFolderName}/page-objects/\`, \`<feature>/${e2eFolderName}/steps/\`, \`<feature>/${e2eFolderName}/actions/\`
-   - **Shared Library Entities**: \`./${sharedTestingRelPath}/page-objects/\`, \`./${sharedTestingRelPath}/steps/\`, \`./${sharedTestingRelPath}/actions/\`, \`./${sharedTestingRelPath}/fixtures/\`
-2. **Ambient Typing Generation**:  
-   These are compiled into \`.testspectra/types/web.d.ts\`, \`android.d.ts\`, \`ios.d.ts\`, \`fixtures.d.ts\`.
-3. **Instant IDE Autocomplete & Zero Clutter**:  
-   Specs consume both local feature objects and shared library utilities globally.
-
-### Code Example:
-\`\`\`typescript
-// packages/features/auth/e2e/specs/Auth/TC-AUTH-01/web.test.ts
-// 🌟 NOTICE: 100% Zero-Import & Flat Execution! (No import statement, no describe wrapper)
-
-it("should navigate via shared header and login with local POM", async () => {
-  // 1. Consumed from Shared Testing Library (${sharedTestingRelPath}/page-objects/NavigationBar)
-  await NavigationBar.goToLogin();
-
-  // 2. Consumed from Shared Testing Library (${sharedTestingRelPath}/steps/loginAsAdmin)
-  await Step.loginAsAdmin();
-
-  // 3. Consumed from Local Feature POM (page-objects/LoginPage)
-  await LoginPage.flashAlert.shouldBeVisible();
-  await LoginPage.flashAlert.shouldContainText("Welcome");
-
-  // 4. Consumed from Shared Testing Library Custom Action (${sharedTestingRelPath}/actions/dismissBanner)
-  await Spectra.dismissBanner();
-});
-\`\`\`
-
----
-
-## 3. How to Run Tests
-
-You can execute tests either from the **Monorepo Root via Nx** or directly inside each **Feature Directory via CLI**:
-
-### Option A: From Root Monorepo via Nx (Recommended for CI & Team Workflows)
-
-\`\`\`bash
-# 1. Run E2E for a SPECIFIC feature module (e.g. auth)
-pnpm nx run auth-${e2eFolderName}:e2e
-
-# 2. Run E2E for a specific feature on ANDROID or IOS
-pnpm nx run auth-${e2eFolderName}:e2e --configuration=android
-pnpm nx run auth-${e2eFolderName}:e2e --configuration=ios
-
-# 3. Run E2E for a specific feature in HEADLESS browser mode
-pnpm nx run auth-${e2eFolderName}:e2e --configuration=headless
-
-# 4. Run ALL feature E2E suites across the entire monorepo in parallel
-pnpm nx run-many -t e2e
-
-# 5. Run only E2E tests for features modified in current Git branch / PR
-pnpm nx affected -t e2e
-\`\`\`
-
-### Option B: From Inside the Feature Directory (Direct CLI)
-
-\`\`\`bash
-# Navigate to the feature e2e folder
-cd ${featureE2eDirs.length > 0 ? path.relative(cwd, featureE2eDirs[0]).replace(/\\/g, '/') : `modules/auth/${e2eFolderName}`}
-
-# Run all specs in this feature
-pnpm spectra run
-
-# Run a specific test case file
-pnpm spectra run specs/Auth/TC-AUTH-01/web.test.ts
-
-# Target Android device or emulator
-pnpm spectra run --target android
-
-# Run in headed / interactive browser mode
-pnpm spectra run --no-headless
-\`\`\`
-
----
-
-## 4. Type Checking & Validation
-
-\`\`\`bash
-# Type check all E2E projects via Nx
-pnpm nx run-many -t type-check
-
-# Or standard TypeScript project references build from root
-pnpm type-check
-# or: npx tsc -b
-\`\`\`
-`;
-        fs.writeFileSync(path.join(cwd, 'ARCHITECTURE.md'), archDocContent, 'utf-8');
+        generateArchitectureDoc(cwd);
         // 8. Ensure root .gitignore ignores .testspectra/ and *.tsbuildinfo
         const rootGitignorePath = path.join(cwd, '.gitignore');
         const ignoreEntries = ['.testspectra/', '*.tsbuildinfo', '.nx/cache'];
@@ -742,34 +615,7 @@ pnpm type-check
     TypeGenerator.writeDeclarationFiles(cwd);
     ensureVsCodeExtensions(cwd);
     // Standalone Architecture Documentation
-    const standaloneArchDoc = `# TestSpectra Project Architecture
-
-This project is built with the TestSpectra testing framework.
-
-## Structure & File Map
-- \`./spectra.config.ts\`: Typed runner configuration.
-- \`./specs/\`: Layered test cases (\`specs/<Suite>/<CaseId>/\` with \`web.test.ts\`, \`android.test.ts\`, \`ios.test.ts\`).
-- \`./page-objects/\`: Page Object models per platform.
-- \`./steps/\`: Business flows accessible globally via \`Step.*\`.
-- \`./actions/\`: Atomic actions accessible globally via \`Spectra.*\`.
-- \`./fixtures/\`: JSON fixtures accessible globally via \`Fixture.*\`.
-- \`./global-hooks/\`: Global suite lifecycle hooks.
-- \`./.testspectra/\`: Auto-generated ambient typings and local runtime cache.
-
-## Execution
-\`\`\`bash
-# Run web test suite
-pnpm test
-
-# Run Android / iOS
-pnpm spectra run --target android
-pnpm spectra run --target ios
-
-# Type check
-pnpm type-check
-\`\`\`
-`;
-    fs.writeFileSync(path.join(cwd, 'ARCHITECTURE.md'), standaloneArchDoc, 'utf-8');
+    generateArchitectureDoc(cwd);
     // Safely update root README.md (do not overwrite existing content)
     const standaloneReadmePath = path.join(cwd, 'README.md');
     const standaloneArchSection = `\n## E2E Testing Architecture (TestSpectra)\n\nDetailed test architecture and folder map are documented in:  \n👉 **[ARCHITECTURE.md](./ARCHITECTURE.md)**\n\n- **Run tests**: \`pnpm test\`\n- **Type-check**: \`pnpm type-check\`\n`;