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

package/dist/commands/upgrade.js

@@ -0,0 +1,197 @@
+import { execSync, execFileSync } from 'child_process';
+import fs from 'fs';
+import path from 'path';
+import { fileURLToPath } from 'url';
+import { RustCoreBridge } from '../runner/bridge.js';
+import { checkDriverUpdates } from '../utils/dependency-updates.js';
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+const PACKAGES = ['@testspectra/cli', '@testspectra/matchers', '@testspectra/react'];
+/** Filters requested package names against the known catalog; empty means "all". */
+function selectPackages(requested) {
+    if (requested.length === 0)
+        return [...PACKAGES];
+    const known = new Set(PACKAGES);
+    const unknown = requested.filter((p) => !known.has(p));
+    if (unknown.length > 0) {
+        console.warn(`\x1b[33mIgnoring unknown TestSpectra package(s): ${unknown.join(', ')}\x1b[0m`);
+    }
+    return requested.filter((p) => known.has(p));
+}
+function getLatestVersion(pkg) {
+    try {
+        const out = execFileSync('npm', ['view', pkg, 'version', '--json'], {
+            stdio: ['ignore', 'pipe', 'ignore'],
+            timeout: 10000,
+        })
+            .toString()
+            .trim()
+            .replace(/"/g, '');
+        return out || null;
+    }
+    catch {
+        return null;
+    }
+}
+function getCurrentVersion(pkg, cwd) {
+    let cur = path.resolve(cwd);
+    while (cur && cur !== path.dirname(cur)) {
+        const pkgJson = path.join(cur, 'node_modules', pkg, 'package.json');
+        if (fs.existsSync(pkgJson)) {
+            try {
+                const p = JSON.parse(fs.readFileSync(pkgJson, 'utf-8'));
+                return p.version ?? null;
+            }
+            catch { }
+        }
+        cur = path.dirname(cur);
+    }
+    return null;
+}
+function detectPackageManager(cwd) {
+    if (fs.existsSync(path.join(cwd, 'pnpm-lock.yaml')))
+        return 'pnpm';
+    if (fs.existsSync(path.join(cwd, 'bun.lockb')) || fs.existsSync(path.join(cwd, 'bun.lock')))
+        return 'bun';
+    return 'npm';
+}
+function collectPackageUpdates(cwd, packages) {
+    return packages.map((pkg) => {
+        const current = getCurrentVersion(pkg, cwd);
+        const latest = getLatestVersion(pkg);
+        return { pkg, current, latest, needsUpdate: !!latest && latest !== current };
+    });
+}
+function printUpdateRow(label, current, latest, needsUpdate) {
+    const currentStr = current ? `\x1b[33mv${current}\x1b[0m` : '\x1b[90m(not installed)\x1b[0m';
+    const latestStr = latest ? `\x1b[32mv${latest}\x1b[0m` : '\x1b[90m(unknown)\x1b[0m';
+    const arrow = needsUpdate ? ` → ${latestStr}` : '';
+    const status = needsUpdate ? '\x1b[33m↑\x1b[0m' : '\x1b[32m✓\x1b[0m';
+    console.log(`\x1b[36m│\x1b[0m   ${status} ${label.padEnd(28)} ${currentStr}${arrow}`);
+}
+function buildInstallCmd(pm, pkgSpecs, cwd) {
+    const list = pkgSpecs.join(' ');
+    switch (pm) {
+        case 'pnpm': {
+            const isWorkspaceRoot = fs.existsSync(path.join(cwd, 'pnpm-workspace.yaml'));
+            return isWorkspaceRoot ? `pnpm add -D -w ${list}` : `pnpm add -D ${list}`;
+        }
+        case 'bun':
+            return `bun add -d ${list}`;
+        case 'npm':
+        default:
+            return `npm install -D ${list}`;
+    }
+}
+export async function upgradeCommand(requestedPackages = [], options = {}) {
+    const cwd = process.cwd();
+    const pm = detectPackageManager(cwd);
+    const selected = selectPackages(requestedPackages);
+    const targeted = requestedPackages.length > 0;
+    if (targeted && selected.length === 0) {
+        console.error(`\x1b[31mNo known TestSpectra package matched: ${requestedPackages.join(', ')}. Known packages: ${PACKAGES.join(', ')}\x1b[0m`);
+        process.exitCode = 1;
+        return;
+    }
+    // Machine-readable mode for the VS Code Preflight panel: implies `--check`, never mutates.
+    if (options.json) {
+        const packages = collectPackageUpdates(cwd, selected);
+        const drivers = targeted ? [] : await checkDriverUpdates();
+        const updatesAvailable = [...packages, ...drivers].filter((u) => u.needsUpdate).length;
+        console.log(JSON.stringify({ packages, drivers, updatesAvailable }, null, 2));
+        return;
+    }
+    console.log('\x1b[36m┌  🚀 TestSpectra Self-Upgrade Mechanism\x1b[0m');
+    console.log('\x1b[36m│\x1b[0m');
+    const updates = [];
+    let packagesUpdated = false;
+    // Phase 1: NPM Packages
+    if (!options.driversOnly) {
+        console.log(`\x1b[36m│\x1b[0m  \x1b[1mPhase 1: Workspace Packages\x1b[0m (Manager: \x1b[33m${pm}\x1b[0m)`);
+        console.log('\x1b[36m│\x1b[0m  Fetching latest versions from npm registry...');
+        updates.push(...collectPackageUpdates(cwd, selected));
+        for (const { pkg, current, latest, needsUpdate } of updates) {
+            const currentStr = current ? `\x1b[33mv${current}\x1b[0m` : '\x1b[90m(not installed)\x1b[0m';
+            const latestStr = latest ? `\x1b[32mv${latest}\x1b[0m` : '\x1b[31m(unavailable)\x1b[0m';
+            const arrow = needsUpdate ? ` → ${latestStr}` : '';
+            const status = !latest ? '\x1b[31m✗\x1b[0m' : needsUpdate ? '\x1b[33m↑\x1b[0m' : '\x1b[32m✓\x1b[0m';
+            console.log(`\x1b[36m│\x1b[0m   ${status} ${pkg.padEnd(28)} ${currentStr}${arrow}`);
+        }
+        const toUpdate = updates.filter((u) => u.needsUpdate && u.latest);
+        console.log('\x1b[36m│\x1b[0m');
+        if (options.check) {
+            console.log(`\x1b[36m│\x1b[0m  \x1b[33m${toUpdate.length} package update(s) available. Run \x1b[36mspectra upgrade\x1b[33m to install.\x1b[0m`);
+        }
+        else if (toUpdate.length > 0) {
+            const pkgSpecs = toUpdate.map((u) => `${u.pkg}@${u.latest}`);
+            const installCmd = buildInstallCmd(pm, pkgSpecs, cwd);
+            console.log(`\x1b[36m│\x1b[0m  Running: \x1b[90m${installCmd}\x1b[0m`);
+            try {
+                execSync(installCmd, { cwd, stdio: 'inherit' });
+                packagesUpdated = true;
+            }
+            catch (err) {
+                console.error(`\x1b[31m│  ✗ Package upgrade failed: ${err.message}\x1b[0m`);
+                process.exit(1);
+            }
+        }
+        else {
+            console.log('\x1b[36m│\x1b[0m  \x1b[32m✓ All TestSpectra packages are already up-to-date!\x1b[0m');
+        }
+        console.log('\x1b[36m│\x1b[0m');
+    }
+    if (options.check) {
+        if (!targeted) {
+            const drivers = await checkDriverUpdates();
+            if (drivers.length > 0) {
+                console.log('\x1b[36m│\x1b[0m  \x1b[1mDriver & Agent Status\x1b[0m');
+                for (const dep of drivers) {
+                    printUpdateRow(dep.name, dep.current, dep.latest, dep.needsUpdate);
+                }
+                console.log('\x1b[36m│\x1b[0m');
+            }
+        }
+        console.log('\x1b[36m└──────────────────────────────────────────────────────────\x1b[0m\n');
+        return;
+    }
+    // Phase 2: Drivers and Binaries
+    if (!options.packagesOnly && !targeted) {
+        console.log(`\x1b[36m│\x1b[0m  \x1b[1mPhase 2: System Binaries & Drivers\x1b[0m`);
+        try {
+            const binPath = RustCoreBridge.resolveBinaryPath();
+            // Using doctor --fix as the underlying mechanism for pulling drivers
+            // In the future, this could be passed a specific --force-latest flag
+            console.log(`\x1b[36m│\x1b[0m  Forcing update for ADB and Spectra Android Agent...`);
+            const home = process.env.HOME || process.env.USERPROFILE || '';
+            const globalDriversDir = path.join(home, '.testspectra', 'drivers');
+            execSync(`"${binPath}" doctor --fix`, {
+                cwd,
+                stdio: 'inherit',
+                env: {
+                    ...process.env,
+                    TEST_SPECTRA_DRIVER_CACHE: globalDriversDir,
+                    TEST_SPECTRA_FORCE_LATEST: '1',
+                },
+            });
+            console.log('\x1b[36m│\x1b[0m  \x1b[32m✓ Drivers updated successfully.\x1b[0m');
+        }
+        catch (err) {
+            console.error(`\x1b[31m│  ✗ Driver upgrade failed: ${err.message}\x1b[0m`);
+            // We don't exit 1 here so we can still print the post-upgrade report
+        }
+        console.log('\x1b[36m│\x1b[0m');
+    }
+    // Phase 3: Post-Upgrade Report
+    console.log('\x1b[36m└──────────────────────────────────────────────────────────\x1b[0m');
+    console.log('\x1b[32m🎉 TestSpectra upgrade complete!\x1b[0m');
+    if (!options.driversOnly && packagesUpdated) {
+        const toUpdate = updates.filter((u) => u.needsUpdate && u.latest);
+        for (const u of toUpdate) {
+            console.log(`   \x1b[32m✓\x1b[0m ${u.pkg}: v${u.current ?? '?'} → v${u.latest}`);
+        }
+    }
+    if (!options.packagesOnly) {
+        console.log(`   \x1b[32m✓\x1b[0m System drivers and agents synchronized to latest versions`);
+    }
+    console.log('');
+}

package/dist/config/schema.d.ts

@@ -1,3 +1,42 @@
+/**
+ * Configuration for an individual local development server lifecycle.
+ */
+export interface DevServerConfig {
+    /**
+     * Unique name or alias identifying this server (e.g. "sso", "adminConsole", "globalSettings").
+     */
+    name?: string;
+    /**
+     * Shell command to launch the development server (e.g. "pnpm --filter sso dev" or "nx serve sso").
+     */
+    command: string;
+    /**
+     * Target URL or healthcheck endpoint (e.g. "https://sso.tagsamurai.local:5174").
+     */
+    url: string;
+    /**
+     * Optional port number (inferred from `url` if omitted).
+     */
+    port?: number;
+    /**
+     * Maximum wait timeout in milliseconds for the server to become interactive and accept HTTP connections.
+     * @default 60000
+     */
+    timeout?: number;
+    /**
+     * Whether to reuse an already running development server if its port/URL is actively responding.
+     * @default true
+     */
+    reuseExistingServer?: boolean;
+    /**
+     * Working directory from which to launch `command`. Defaults to workspace root.
+     */
+    cwd?: string;
+    /**
+     * Custom environment variables passed to the spawned development server process.
+     */
+    env?: Record<string, string>;
+}
 /**
  * Configuration for web automation and browser test runners.
  */
@@ -7,6 +46,20 @@ export interface WebConfig {
      * @default "http://localhost:3000"
      */
     baseUrl: string;
+    /**
+     * Multi-host / multi-app mapping dictionary for micro-frontends and multi-entrypoint monorepos.
+     * Maps named aliases to full base URLs (e.g. `{ sso: "https://sso.tagsamurai.local:5174", fam: "https://fam.tagsamurai.local:5175" }`).
+     * Allows tests to navigate using `Spectra.navigate('sso:/login')` or CLI `--host sso`.
+     */
+    hosts?: Record<string, string>;
+    /**
+     * Array of development servers to auto-start and healthcheck before running tests.
+     */
+    devServers?: DevServerConfig[];
+    /**
+     * Convenience single development server configuration.
+     */
+    devServer?: DevServerConfig;
     /**
      * Maximum number of parallel browser sessions/workers spawned during test execution.
      * Can be an explicit number, numeric string, or `"auto"`.

package/dist/config/schema.js

@@ -22,6 +22,8 @@ export function defineConfig(config) {
 export const DEFAULT_CONFIG_DATA = {
     webConfig: {
         baseUrl: 'http://localhost:3000',
+        hosts: {},
+        devServers: [],
         maxConcurrentSessions: '1',
         headless: true,
         implicitWait: '5000',

package/dist/generator/__tests__/tsconfig-isolation.test.js

@@ -41,7 +41,8 @@ describe('Platform TSConfigs & Type Isolation (docs/v2/cli/tsconfig-platform-iso
         expect(rootConfig.references).toEqual([{ path: './.testspectra/tsconfig.json' }]);
         // Verify dynamic master solution references all 5 platform solution tsconfigs in .testspectra/tsconfig/
         const solutionConfig = JSON.parse(fs.readFileSync(path.join(tmpDir, '.testspectra', 'tsconfig.json'), 'utf-8'));
-        expect(solutionConfig.compilerOptions.noEmit).toBe(true);
+        expect(solutionConfig.compilerOptions.composite).toBe(true);
+        expect(solutionConfig.compilerOptions.noEmit).toBeUndefined();
         expect(solutionConfig.references).toEqual([
             { path: './tsconfig/web.json' },
             { path: './tsconfig/mobile.json' },

package/dist/generator/__tests__/type-generator.test.js

@@ -383,4 +383,42 @@ async function verifyZeroImport() {
         expect(fs.existsSync(path.join(tmpDir, '.testspectra', 'types', 'web.d.ts'))).toBe(false);
         expect(fs.existsSync(path.join(tmpDir, '.testspectra', 'types', 'common.d.ts'))).toBe(false);
     });
+    it('nx monorepo: does NOT treat feature library as shared library and discovers nested e2e subproject', () => {
+        // 1. Shared library with testspectra:shared
+        const sharedDir = path.join(tmpDir, 'shared', 'testing');
+        fs.mkdirSync(path.join(sharedDir, 'page-objects', 'SharedNav'), { recursive: true });
+        fs.writeFileSync(path.join(sharedDir, 'project.json'), JSON.stringify({ name: 'shared-testing', projectType: 'library', tags: ['testspectra:shared'] }));
+        fs.writeFileSync(path.join(sharedDir, 'page-objects', 'SharedNav', 'common.ts'), 'export default class SharedNav {}');
+        // 2. Nx Feature library (projectType: "library", standard Nx tags, NO testspectra tags)
+        const featureLibDir = path.join(tmpDir, 'packages', 'features', 'auth');
+        fs.mkdirSync(featureLibDir, { recursive: true });
+        fs.writeFileSync(path.join(featureLibDir, 'project.json'), JSON.stringify({
+            name: '@tagsamurai/feature-auth',
+            projectType: 'library',
+            sourceRoot: 'packages/features/auth',
+            targets: {},
+            tags: ['type:feature', 'scope:feature-auth'],
+        }));
+        // 3. Nested E2E subproject inside feature library
+        const featureE2eDir = path.join(featureLibDir, 'e2e');
+        fs.mkdirSync(path.join(featureE2eDir, 'specs', 'AuthSuite', 'TC-001'), { recursive: true });
+        fs.writeFileSync(path.join(featureE2eDir, 'project.json'), JSON.stringify({
+            name: 'feature-auth-e2e',
+            projectType: 'application',
+            tags: ['testspectra:e2e', 'testspectra:scope:feature-auth'],
+        }));
+        fs.writeFileSync(path.join(featureE2eDir, 'specs', 'AuthSuite', 'TC-001', 'web.test.ts'), 'it("auth test", async () => {});');
+        const scopes = TypeGenerator.getEntityScopes(tmpDir);
+        expect(scopes).toHaveLength(2);
+        const sharedScope = scopes.find((s) => s.isShared);
+        expect(sharedScope).toBeDefined();
+        expect(sharedScope?.name).toBe('shared');
+        expect(sharedScope?.dir).toBe(path.resolve(sharedDir));
+        const featureScope = scopes.find((s) => !s.isShared);
+        expect(featureScope).toBeDefined();
+        expect(featureScope?.name).toBe('feature-auth');
+        expect(featureScope?.dir).toBe(path.resolve(featureE2eDir));
+        // Verify packages/features/auth is NOT in scopes
+        expect(scopes.some((s) => s.dir === path.resolve(featureLibDir))).toBe(false);
+    });
 });

package/dist/generator/architecture-doc-generator.d.ts

@@ -0,0 +1,14 @@
+export interface ArchitectureDocResult {
+    mode: 'nx' | 'default';
+    path: string;
+    sharedTestingRelPath?: string;
+    featureCount?: number;
+}
+export declare function buildFeatureModulesSection(cwd: string, featureE2eDirs: string[]): string;
+/**
+ * (Re)generates `ARCHITECTURE.md` from the current on-disk workspace state — no prompts, no other
+ * scaffolding side effects. Nx/monorepo mode is auto-detected via `TsConfigGenerator.getEntityScopes`
+ * (the same shared/feature discovery `sync-types` already relies on), so this stays accurate after
+ * features are added/removed/renamed without needing to re-run `spectra init`.
+ */
+export declare function generateArchitectureDoc(cwd: string): ArchitectureDocResult;

package/dist/generator/architecture-doc-generator.js

@@ -0,0 +1,80 @@
+import fs from 'fs';
+import path from 'path';
+import { fileURLToPath } from 'url';
+import { TsConfigGenerator } from './tsconfig-generator.js';
+function resolveDocsTemplateDir() {
+    const __filename = fileURLToPath(import.meta.url);
+    const __dirname = path.dirname(__filename);
+    const candidates = [
+        path.resolve(__dirname, '../templates/docs'),
+        path.resolve(__dirname, '../../templates/docs'),
+        path.resolve(__dirname, '../../../templates/docs'),
+    ];
+    return candidates.find((d) => fs.existsSync(d)) ?? candidates[candidates.length - 1];
+}
+function renderArchitectureDoc(templatePath, replacements) {
+    let content = fs.readFileSync(templatePath, 'utf-8');
+    for (const [token, value] of Object.entries(replacements)) {
+        content = content.replaceAll(token, value);
+    }
+    return content;
+}
+/** Reads a feature e2e dir's project.json for its Nx project name, falling back to `<parentDirName>-<e2eDirName>`. */
+function resolveNxProjectName(featureDir) {
+    const parentName = path.basename(path.dirname(featureDir));
+    const fallback = `${parentName}-${path.basename(featureDir)}`;
+    const projJsonPath = path.join(featureDir, 'project.json');
+    if (!fs.existsSync(projJsonPath))
+        return fallback;
+    try {
+        const pObj = JSON.parse(fs.readFileSync(projJsonPath, 'utf-8'));
+        return typeof pObj.name === 'string' && pObj.name ? pObj.name : fallback;
+    }
+    catch {
+        return fallback;
+    }
+}
+export function buildFeatureModulesSection(cwd, featureE2eDirs) {
+    return featureE2eDirs
+        .map((d) => {
+        const rel = path.relative(cwd, d).replace(/\\/g, '/');
+        const featureName = path.basename(path.dirname(d));
+        const e2eName = resolveNxProjectName(d);
+        return `- \`./${rel}\` (**${featureName}**, 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');
+}
+/**
+ * (Re)generates `ARCHITECTURE.md` from the current on-disk workspace state — no prompts, no other
+ * scaffolding side effects. Nx/monorepo mode is auto-detected via `TsConfigGenerator.getEntityScopes`
+ * (the same shared/feature discovery `sync-types` already relies on), so this stays accurate after
+ * features are added/removed/renamed without needing to re-run `spectra init`.
+ */
+export function generateArchitectureDoc(cwd) {
+    const docsTemplateDir = resolveDocsTemplateDir();
+    const destPath = path.join(cwd, 'ARCHITECTURE.md');
+    const scopes = TsConfigGenerator.getEntityScopes(cwd);
+    const isNxMode = scopes.length > 0 || fs.existsSync(path.join(cwd, 'nx.json'));
+    if (!isNxMode) {
+        fs.copyFileSync(path.join(docsTemplateDir, 'ARCHITECTURE.default.md'), destPath);
+        return { mode: 'default', path: destPath };
+    }
+    const sharedScope = scopes.find((s) => s.isShared);
+    const featureE2eDirs = scopes.filter((s) => !s.isShared).map((s) => s.dir);
+    const sharedTestingRelPath = sharedScope ? path.relative(cwd, sharedScope.dir).replace(/\\/g, '/') : 'shared/testing';
+    const e2eFolderName = featureE2eDirs.length > 0 ? path.basename(featureE2eDirs[0]) : 'e2e';
+    const content = renderArchitectureDoc(path.join(docsTemplateDir, 'ARCHITECTURE.nx.md'), {
+        __SHARED_TESTING_REL_PATH__: sharedTestingRelPath,
+        __FEATURE_COUNT__: String(featureE2eDirs.length),
+        __FEATURE_MODULES_SECTION__: buildFeatureModulesSection(cwd, featureE2eDirs),
+        __E2E_FOLDER_NAME__: e2eFolderName,
+        __SAMPLE_FEATURE_E2E_PATH__: featureE2eDirs.length > 0
+            ? path.relative(cwd, featureE2eDirs[0]).replace(/\\/g, '/')
+            : `modules/auth/${e2eFolderName}`,
+    });
+    fs.writeFileSync(destPath, content, 'utf-8');
+    return { mode: 'nx', path: destPath, sharedTestingRelPath, featureCount: featureE2eDirs.length };
+}

package/dist/generator/index.d.ts

@@ -1,2 +1,3 @@
 export * from './type-generator.js';
 export * from './tsconfig-generator.js';
+export * from './architecture-doc-generator.js';

package/dist/generator/index.js

@@ -1,2 +1,3 @@
 export * from './type-generator.js';
 export * from './tsconfig-generator.js';
+export * from './architecture-doc-generator.js';

package/dist/generator/tsconfig-generator.js

@@ -16,7 +16,7 @@ export class TsConfigGenerator {
                 moduleResolution: 'NodeNext',
                 skipLibCheck: true,
                 strict: true,
-                noEmit: true,
+                composite: true,
             },
             files: [],
             references: references || [

package/dist/generator/type-generator.d.ts

@@ -9,8 +9,11 @@ export interface EntityScope {
  * Discovers all feature directories and shared library directories.
  * Standard discovery hierarchy:
  * 1. Nx / Monorepo Project Descriptors (`project.json`):
- *    - projectType: "library" OR tags: ["type:shared", "type:library", "scope:shared"] => Shared Library Scope (isShared: true)
- *    - projectType: "application" OR tags: ["type:e2e", "type:app"] => Feature Scope (isShared: false)
+ *    - tags: ["testspectra:shared"] => Shared Library Scope (isShared: true)
+ *    - tags: ["testspectra:e2e"] or ["testspectra:scope:<name>"] => Feature Scope (isShared: false)
+ *    - Generic Nx libraries/apps without testspectra tags are not TestSpectra scopes and recursion
+ *      continues into their subdirectories so nested e2e projects (e.g. `packages/features/auth/e2e`)
+ *      are discovered.
  * 2. Explicit User Configuration (`tsconfig.spectra.shared.json`):
  *    - Custom include path for shared testing utilities
  * 3. Dynamic Workspace Filesystem Discovery (Fallback for non-Nx / custom layouts):

package/dist/generator/type-generator.js

@@ -13,8 +13,11 @@ export const PLATFORM_HIERARCHY = {
  * Discovers all feature directories and shared library directories.
  * Standard discovery hierarchy:
  * 1. Nx / Monorepo Project Descriptors (`project.json`):
- *    - projectType: "library" OR tags: ["type:shared", "type:library", "scope:shared"] => Shared Library Scope (isShared: true)
- *    - projectType: "application" OR tags: ["type:e2e", "type:app"] => Feature Scope (isShared: false)
+ *    - tags: ["testspectra:shared"] => Shared Library Scope (isShared: true)
+ *    - tags: ["testspectra:e2e"] or ["testspectra:scope:<name>"] => Feature Scope (isShared: false)
+ *    - Generic Nx libraries/apps without testspectra tags are not TestSpectra scopes and recursion
+ *      continues into their subdirectories so nested e2e projects (e.g. `packages/features/auth/e2e`)
+ *      are discovered.
  * 2. Explicit User Configuration (`tsconfig.spectra.shared.json`):
  *    - Custom include path for shared testing utilities
  * 3. Dynamic Workspace Filesystem Discovery (Fallback for non-Nx / custom layouts):
@@ -48,16 +51,9 @@ export function discoverEntityScopes(cwd) {
         if (fs.existsSync(projectJsonPath)) {
             try {
                 const pObj = JSON.parse(fs.readFileSync(projectJsonPath, 'utf-8'));
-                const projectType = pObj.projectType;
                 const tags = Array.isArray(pObj.tags) ? pObj.tags : [];
-                const isSharedLib = projectType === 'library' ||
-                    tags.includes('type:shared') ||
-                    tags.includes('type:library') ||
-                    tags.includes('scope:shared');
-                const isE2eApp = projectType === 'application' ||
-                    tags.includes('type:e2e') ||
-                    tags.includes('type:app') ||
-                    tags.some((t) => t.startsWith('scope:') && t !== 'scope:shared');
+                const isSharedLib = tags.includes('testspectra:shared');
+                const isE2eApp = tags.includes('testspectra:e2e') || tags.some((t) => t.startsWith('testspectra:scope:'));
                 if (isSharedLib) {
                     if (!scopes.some((s) => s.dir === dir)) {
                         scopes.push({ name: 'shared', dir, isShared: true });
@@ -65,9 +61,9 @@ export function discoverEntityScopes(cwd) {
                     return; // Do not recurse into subdirectories of an identified project
                 }
                 else if (isE2eApp) {
-                    // Extract scope name from tags (e.g. "scope:matchers" => "matchers") or project name
-                    const scopeTag = tags.find((t) => t.startsWith('scope:') && t !== 'scope:shared');
-                    let featureName = scopeTag ? scopeTag.replace('scope:', '') : '';
+                    // Extract scope name from tags (e.g. "testspectra:scope:matchers" => "matchers") or project name
+                    const scopeTag = tags.find((t) => t.startsWith('testspectra:scope:'));
+                    let featureName = scopeTag ? scopeTag.replace('testspectra:scope:', '') : '';
                     if (!featureName && pObj.name) {
                         featureName = pObj.name.replace(/-e2e$/, '').replace(/^e2e-/, '');
                     }
@@ -329,6 +325,9 @@ export class TypeGenerator {
             const hierarchy = PLATFORM_HIERARCHY[platform];
             let content = `// Auto-generated ambient declarations for TestSpectra [${platform.toUpperCase()}]\n`;
             content += `// Managed automatically by TestSpectra Language Service Plugin.\n\n`;
+            content += `/// <reference types="@testspectra/matchers" />\n`;
+            content += `/// <reference path="./fixtures.d.ts" />\n`;
+            content += `/// <reference path="${envRefPath}" />\n\n`;
             // TestSpectra's Rust-native orchestrator worker (core/orchestrator/src/worker/bdd_runner.ts)
             // registers its own `it`/`test`/lifecycle-hook globals directly — there is no WDIO or Mocha
             // runtime involved at all (not just for component testing; this is true across every
@@ -346,9 +345,7 @@ export class TypeGenerator {
                 // — the Rust orchestrator's BDD runtime has no `expect` global at all.
                 content += `declare const expect: import('@testspectra/react').ExpectStatic;\n`;
             }
-            content += `/// <reference types="@testspectra/matchers" />\n`;
-            content += `/// <reference path="./fixtures.d.ts" />\n`;
-            content += `/// <reference path="${envRefPath}" />\n\n`;
+            content += `\n`;
             // 1. Page Objects Global Declarations
             const declaredPOMs = new Set();
             for (const poDir of poDirs) {