@testspectra/cli 1.1.8-rc.2 → 1.1.8-rc.21

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

@@ -0,0 +1,93 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import { cloudRunCommand, parseTimeoutMs } from '../cloud-run.js';
+const ORIGINAL_ENV = { ...process.env };
+function mockFetchSequence(responses) {
+    let call = 0;
+    return vi.fn(async (_url, _init) => {
+        const res = responses[Math.min(call, responses.length - 1)];
+        call += 1;
+        return {
+            ok: res.ok,
+            status: res.status ?? (res.ok ? 200 : 500),
+            statusText: 'error',
+            json: async () => res.json,
+        };
+    });
+}
+describe('cloudRunCommand (docs/v2/cloud/git-spec-standards-and-workflow.md)', () => {
+    beforeEach(() => {
+        process.env = { ...ORIGINAL_ENV, SPECTRA_URL: 'https://cloud.test', SPECTRA_TOKEN: 'gitea-pat-123' };
+        process.exitCode = undefined;
+        vi.useFakeTimers();
+    });
+    afterEach(() => {
+        process.env = { ...ORIGINAL_ENV };
+        vi.restoreAllMocks();
+        vi.useRealTimers();
+    });
+    it('fails fast without SPECTRA_URL/SPECTRA_TOKEN', async () => {
+        delete process.env.SPECTRA_URL;
+        delete process.env.SPECTRA_TOKEN;
+        const fetchSpy = vi.fn();
+        vi.stubGlobal('fetch', fetchSpy);
+        await cloudRunCommand({ project: 'org/repo', branch: 'main' });
+        expect(process.exitCode).toBe(1);
+        expect(fetchSpy).not.toHaveBeenCalled();
+    });
+    it('triggers and returns immediately with --no-wait', async () => {
+        const fetchSpy = mockFetchSequence([{ ok: true, json: { job_id: 'job-1', status: 'queued' } }]);
+        vi.stubGlobal('fetch', fetchSpy);
+        await cloudRunCommand({ project: 'org/repo', branch: 'main', wait: false });
+        expect(fetchSpy).toHaveBeenCalledTimes(1);
+        const [url, init] = fetchSpy.mock.calls[0];
+        expect(url).toBe('https://cloud.test/api/v1/runs/trigger');
+        const headers = init.headers;
+        expect(headers.Authorization).toBe('Bearer gitea-pat-123');
+        expect(JSON.parse(init.body)).toMatchObject({ project_id: 'org/repo', branch: 'main', platform: 'web' });
+        expect(process.exitCode).toBeUndefined();
+    });
+    it('exits 0 when the job reaches done', async () => {
+        const fetchSpy = mockFetchSequence([
+            { ok: true, json: { job_id: 'job-2', status: 'queued' } },
+            { ok: true, json: { status: 'done', run_id: 'run-2', started_at: null, completed_at: null, error_log: null } },
+        ]);
+        vi.stubGlobal('fetch', fetchSpy);
+        const promise = cloudRunCommand({ project: 'org/repo', branch: 'main' });
+        await vi.advanceTimersByTimeAsync(5000);
+        await promise;
+        expect(process.exitCode).toBe(0);
+    });
+    it('exits 1 when the job reaches failed', async () => {
+        const fetchSpy = mockFetchSequence([
+            { ok: true, json: { job_id: 'job-3', status: 'queued' } },
+            {
+                ok: true,
+                json: { status: 'failed', run_id: 'run-3', started_at: null, completed_at: null, error_log: 'boom' },
+            },
+        ]);
+        vi.stubGlobal('fetch', fetchSpy);
+        const promise = cloudRunCommand({ project: 'org/repo', branch: 'main' });
+        await vi.advanceTimersByTimeAsync(5000);
+        await promise;
+        expect(process.exitCode).toBe(1);
+    });
+    it('exits 1 when the trigger request itself fails', async () => {
+        const fetchSpy = mockFetchSequence([{ ok: false, status: 401, json: { error: 'Invalid PAT' } }]);
+        vi.stubGlobal('fetch', fetchSpy);
+        await cloudRunCommand({ project: 'org/repo', branch: 'main' });
+        expect(process.exitCode).toBe(1);
+    });
+});
+describe('parseTimeoutMs', () => {
+    it('parses seconds, minutes, and hours', () => {
+        expect(parseTimeoutMs('30s')).toBe(30_000);
+        expect(parseTimeoutMs('30m')).toBe(30 * 60_000);
+        expect(parseTimeoutMs('2h')).toBe(2 * 3_600_000);
+    });
+    it('defaults to minutes when no unit is given', () => {
+        expect(parseTimeoutMs('10')).toBe(10 * 60_000);
+    });
+    it('falls back to 30m for unparseable input', () => {
+        expect(parseTimeoutMs('nonsense')).toBe(30 * 60_000);
+    });
+});

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/add.js

@@ -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/cloud-run.d.ts

@@ -0,0 +1,13 @@
+export interface CloudRunOptions {
+    project: string;
+    projectName?: string;
+    branch?: string;
+    commit?: string;
+    platform?: string;
+    wait?: boolean;
+    timeout?: string;
+    demo?: boolean;
+    baseUrl?: string;
+}
+export declare function parseTimeoutMs(timeout: string): number;
+export declare function cloudRunCommand(options: CloudRunOptions): Promise<void>;

package/dist/commands/cloud-run.js

@@ -0,0 +1,120 @@
+import { execFileSync } from 'child_process';
+import chalk from 'chalk';
+import ora from 'ora';
+const POLL_INTERVAL_MS = 5000;
+const DEFAULT_TIMEOUT = '30m';
+function detectGitRef(...args) {
+    try {
+        return execFileSync('git', args, { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] }).trim() || undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+export function parseTimeoutMs(timeout) {
+    const match = /^(\d+)(s|m|h)?$/.exec(timeout.trim());
+    if (!match)
+        return 30 * 60 * 1000;
+    const value = Number(match[1]);
+    const unit = match[2] ?? 'm';
+    const multiplier = unit === 's' ? 1000 : unit === 'h' ? 3_600_000 : 60_000;
+    return value * multiplier;
+}
+// Same credential path as the trigger endpoint expects: a Gitea PAT, not the
+// dashboard's OAuth2 session — a CI runner can't complete a browser redirect.
+// See docs/v2/cloud/git-spec-standards-and-workflow.md.
+function requireEnv(name) {
+    const value = process.env[name];
+    if (!value) {
+        console.error(chalk.red(`Missing required environment variable: ${name}`));
+        console.error(chalk.gray('Set it as a CI secret — see docs/v2/cloud/git-spec-standards-and-workflow.md'));
+    }
+    return value;
+}
+export async function cloudRunCommand(options) {
+    const spectraUrl = requireEnv('SPECTRA_URL')?.replace(/\/$/, '');
+    const spectraToken = requireEnv('SPECTRA_TOKEN');
+    if (!spectraUrl || !spectraToken) {
+        process.exitCode = 1;
+        return;
+    }
+    const branch = options.branch ?? detectGitRef('rev-parse', '--abbrev-ref', 'HEAD');
+    if (!branch) {
+        console.error(chalk.red('Could not determine branch: pass --branch or run inside a git repository.'));
+        process.exitCode = 1;
+        return;
+    }
+    const commit = options.commit ?? detectGitRef('rev-parse', 'HEAD');
+    const platform = options.platform ?? 'web';
+    const wait = options.wait !== false;
+    const timeout = options.timeout ?? DEFAULT_TIMEOUT;
+    const spinner = ora(`Triggering cloud run for ${chalk.bold(options.project)}@${branch}...`).start();
+    let trigger;
+    try {
+        const res = await fetch(`${spectraUrl}/api/v1/runs/trigger`, {
+            method: 'POST',
+            headers: {
+                'Content-Type': 'application/json',
+                Authorization: `Bearer ${spectraToken}`,
+            },
+            body: JSON.stringify({
+                project_id: options.project,
+                project_name: options.projectName ?? options.project,
+                branch,
+                commit_hash: commit,
+                platform,
+                demo: options.demo ?? false,
+                base_url: options.baseUrl,
+            }),
+        });
+        if (!res.ok) {
+            const body = await res.json().catch(() => ({ error: res.statusText }));
+            throw new Error(body.error ?? `HTTP ${res.status}`);
+        }
+        trigger = (await res.json());
+    }
+    catch (err) {
+        spinner.fail(chalk.red(`Failed to trigger cloud run: ${err.message}`));
+        process.exitCode = 1;
+        return;
+    }
+    spinner.succeed(`Cloud run queued: ${chalk.cyan(trigger.job_id)}`);
+    if (!wait) {
+        console.log(chalk.gray(`Not waiting for result. Poll ${spectraUrl}/api/v1/jobs/${trigger.job_id}/status yourself.`));
+        return;
+    }
+    await waitForJob(spectraUrl, spectraToken, trigger.job_id, timeout);
+}
+async function waitForJob(spectraUrl, spectraToken, jobId, timeout) {
+    const spinner = ora('Waiting for run to finish...').start();
+    const deadline = Date.now() + parseTimeoutMs(timeout);
+    while (Date.now() < deadline) {
+        await new Promise((resolve) => setTimeout(resolve, POLL_INTERVAL_MS));
+        let job;
+        try {
+            const res = await fetch(`${spectraUrl}/api/v1/jobs/${jobId}/status`, {
+                headers: { Authorization: `Bearer ${spectraToken}` },
+            });
+            if (!res.ok)
+                throw new Error(`HTTP ${res.status}`);
+            job = (await res.json());
+        }
+        catch (err) {
+            spinner.text = chalk.yellow(`Poll failed, retrying: ${err.message}`);
+            continue;
+        }
+        if (job.status === 'done') {
+            spinner.succeed(chalk.green(`Run passed (run_id: ${job.run_id})`));
+            process.exitCode = 0;
+            return;
+        }
+        if (job.status === 'failed') {
+            spinner.fail(chalk.red(`Run failed (run_id: ${job.run_id})${job.error_log ? `: ${job.error_log}` : ''}`));
+            process.exitCode = 1;
+            return;
+        }
+        spinner.text = `Run status: ${job.status}`;
+    }
+    spinner.fail(chalk.red(`Timed out after ${timeout} waiting for the run to finish.`));
+    process.exitCode = 1;
+}

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.js

@@ -42,6 +42,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'])
@@ -508,6 +511,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
@@ -519,7 +523,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 { }
@@ -557,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'];
@@ -741,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`;

package/dist/commands/install.js

@@ -34,6 +34,7 @@ export async function installCommand(item, options = {}) {
                 cwd: workspaceRoot,
                 env: runnerEnv,
                 stdio: 'inherit',
+                windowsHide: true,
             });
         }
         else {
@@ -41,6 +42,7 @@ export async function installCommand(item, options = {}) {
                 cwd,
                 env: runnerEnv,
                 stdio: 'inherit',
+                windowsHide: true,
             });
         }
         child.on('close', (code) => {

package/dist/commands/license.js

@@ -14,6 +14,7 @@ export async function licenseCommand(action = 'status', key, options = {}) {
         const child = spawn(binPath, args, {
             stdio: 'inherit',
             env: process.env,
+            windowsHide: true,
         });
         child.on('close', (code) => {
             if (code === 0) {