@testspectra/cli 1.0.17 → 1.0.19

package/README.md

@@ -161,14 +161,14 @@ export default defineConfig({
 
 | Command | Description |
 | :--- | :--- |
-| `spectra init` | Scaffolds a complete multi-platform project from scratch with tsconfigs, specs, page objects, actions, steps, and fixtures. |
-| `spectra run` | Generates declaration types and invokes the native Rust test runner to execute the test suite. |
+| `spectra init` / `npx @testspectra/cli init` | Interactive project setup. Auto-detects standalone or Nx Monorepos, discovers workspace packages from `pnpm-workspace.yaml`, and scaffolds centralized/distributed configurations. |
+| `spectra run [spec]` | Automatically updates ambient declarations and invokes the native Rust test runner to execute the test suite. |
 | `spectra doctor` | Verifies local environment prerequisites (ADB, Java, Chrome, Bun, Node). |
 | `spectra devices` | Lists connected Android/iOS devices and local browsers. |
 
 ---
 
-## 4. Directory Structure of a TestSpectra Project
+## 4. Standalone Project Directory Structure
 
 ```
 ├── spectra.config.ts            # Central typed project configuration
@@ -189,19 +189,17 @@ export default defineConfig({
 │   └── loginUser/
 │         ├── web.step.ts
 │         └── mobile.step.ts
-├── hooks/                       # Suite lifecycle hooks
-│   └── default/
-│         ├── before.web.hook.ts
-│         ├── before.android.hook.ts
-│         └── before.ios.hook.ts
-├── specs/                       # Standalone zero-import test cases
-│   └── TC-LOGIN-01/
-│         ├── web.test.ts
-│         ├── android.test.ts
-│         └── ios.test.ts
+├── global-hooks/                # Global lifecycle hooks
+│   └── before.web.hook.ts
+├── specs/                       # Layered zero-import test cases
+│   └── Auth/
+│         └── TC-AUTH-01/
+│               ├── web.test.ts
+│               ├── android.test.ts
+│               └── ios.test.ts
 ├── fixtures/                    # Platform-agnostic test data
 │   └── userData.json
-└── .testspectra/                # Auto-generated ambient typings
+└── .testspectra/                # Auto-generated ambient typings & cache
     └── types/
           ├── fixtures.d.ts
           ├── web.d.ts
@@ -213,15 +211,83 @@ export default defineConfig({
 
 ---
 
-## 5. Development & Verification
+## 5. Enterprise Monorepo Architecture (Nx & PNPM Workspace)
+
+TestSpectra features an enterprise-grade architecture for large monorepos: **"Centralized Configuration, Distributed Implementation"**.
+
+```
+                  ┌───────────────────────────────────────────────────────────┐
+                  │                 Root Monorepo Directory                   │
+                  │                                                           │
+                  │  ├── spectra.config.ts       (Central Execution Config)   │
+                  │  ├── .testspectra/           (Central Cache, AppData, Log)│
+                  │  ├── pnpm-workspace.yaml     (Workspace Definition)       │
+                  │  ├── nx.json                 (Nx Target & Caching Rules)  │
+                  │  └── tsconfig.json           (Solution References)        │
+                  └─────────────────────────────┬─────────────────────────────┘
+                                                │
+                 ┌──────────────────────────────┴──────────────────────────────┐
+                 ▼                                                             ▼
+  ┌───────────────────────────────┐                             ┌───────────────────────────────┐
+  │   shared/testing/ (Library)   │                             │  packages/features/auth/e2e/  │
+  ├───────────────────────────────┤                             ├───────────────────────────────┤
+  │ - Shared Page Objects         │ ◄─── Auto-Scanned Globals ──│ - Feature Specs (specs/)      │
+  │ - Shared Steps (loginAsAdmin) │     (100% Zero-Import!)     │ - Feature Page Objects (POMs) │
+  │ - Shared Actions (dismissBtn) │                             │ - project.json (Nx Target)    │
+  │ - Shared Fixtures (appConfig) │                             │ - tsconfig.web/android/ios    │
+  └───────────────────────────────┘                             └───────────────────────────────┘
+```
+
+### Key Pillars of Monorepo Integration:
+
+1. **Interactive Workspace Auto-Discovery (`spectra init`)**:
+   - Parses `pnpm-workspace.yaml` (e.g. `packages/features/*`, `modules/**`).
+   - Scans sub-directories for existing `project.json` or `package.json`.
+   - Prompts the user with an interactive multi-select checkbox to choose which features will receive E2E testing.
+   - Prompts for customizable E2E folder names (e.g. `e2e`, `test/e2e`) and the shared testing library path (`shared/testing`).
+
+2. **Centralized Configuration (`spectra.config.ts`) & App Data (`.testspectra/`)**:
+   - `spectra.config.ts` lives exclusively at the root of the monorepo.
+   - CLI test runs executed from sub-feature folders automatically traverse up to find the root configuration.
+   - Driver caches, binaries, and logs reside in `<root>/.testspectra/`, preventing repository clutter across individual feature folders.
+
+3. **Global Zero-Import Consumption of Shared Library**:
+   - Entities placed inside `shared/testing/page-objects/`, `shared/testing/steps/`, `shared/testing/actions/`, and `shared/testing/fixtures/` are automatically aggregated into ambient declarations.
+   - Feature test specs consume shared Page Objects (`NavigationBar.goToHome()`), steps (`Step.loginAsAdmin()`), actions (`Spectra.dismissBanner()`), and fixtures (`Fixture.appConfig`) **without a single line of `import` statement**.
+
+4. **Nx Target Execution & Affected Caching**:
+   - Each feature E2E folder includes an Nx `project.json`:
+     ```json
+     {
+       "name": "auth-e2e",
+       "targets": {
+         "e2e": {
+           "executor": "nx:run-commands",
+           "options": { "command": "spectra run", "cwd": "modules/auth/e2e" },
+           "configurations": {
+             "android": { "command": "spectra run --target android" },
+             "ios": { "command": "spectra run --target ios" },
+             "headless": { "command": "spectra run --headless" }
+           }
+         }
+       }
+     }
+     ```
+   - Running `nx run-many -t e2e` executes all feature test suites in parallel.
+5. **Automatic Architecture Documentation (`ARCHITECTURE.md`)**:
+   - Every `spectra init` run produces a comprehensive, project-tailored `ARCHITECTURE.md` file in the root workspace.
+   - It documents the generated file map, exact distributed feature paths, shared library resolution, and zero-import mechanics for onboarding engineers.
+
+---
+
+## 6. Development & Verification
 
 To verify the CLI and example app:
 ```bash
 # Build CLI
 pnpm --filter @testspectra/cli build
 
-# Initialize and verify example app
-cd apps/example-app
-../../cli/bin/spectra.js init
-npx tsc -b tsconfig.json
+# Test interactive scaffolding
+npx @testspectra/cli init
+pnpm type-check
 ```

package/dist/commands/init.js

@@ -4,41 +4,152 @@ import { fileURLToPath } from "url";
 import { ConfigLoader } from "../config/loader.js";
 import { TypeGenerator } from "../types/generator.js";
 import inquirer from "inquirer";
+function parsePnpmWorkspaceGlobs(content) {
+    const lines = content.split("\n");
+    const globs = [];
+    let inPackages = false;
+    for (const line of lines) {
+        const trimmed = line.trim();
+        if (trimmed.startsWith("packages:")) {
+            inPackages = true;
+            continue;
+        }
+        if (inPackages) {
+            if (trimmed.startsWith("-")) {
+                const item = trimmed.replace(/^-\s*['"]?/, "").replace(/['"]?\s*$/, "");
+                if (item)
+                    globs.push(item);
+            }
+            else if (trimmed && !trimmed.startsWith("#")) {
+                break;
+            }
+        }
+    }
+    return globs;
+}
+function scanDirectoriesForProjects(cwd, patterns) {
+    const foundProjects = [];
+    const visited = new Set();
+    function search(dir, currentDepth, maxDepth) {
+        if (currentDepth > maxDepth || !fs.existsSync(dir))
+            return;
+        const base = path.basename(dir);
+        if (base === "node_modules" || base === "dist" || base === ".testspectra" || base === ".git" || base === "shared") {
+            return;
+        }
+        const hasPkg = fs.existsSync(path.join(dir, "package.json"));
+        const hasNx = fs.existsSync(path.join(dir, "project.json"));
+        if ((hasPkg || hasNx) && dir !== cwd) {
+            const rel = path.relative(cwd, dir);
+            if (!visited.has(rel)) {
+                visited.add(rel);
+                let name = path.basename(dir);
+                if (hasPkg) {
+                    try {
+                        const pkg = JSON.parse(fs.readFileSync(path.join(dir, "package.json"), "utf-8"));
+                        if (pkg.name)
+                            name = pkg.name;
+                    }
+                    catch { }
+                }
+                else if (hasNx) {
+                    try {
+                        const nxJson = JSON.parse(fs.readFileSync(path.join(dir, "project.json"), "utf-8"));
+                        if (nxJson.name)
+                            name = nxJson.name;
+                    }
+                    catch { }
+                }
+                foundProjects.push({
+                    name,
+                    relPath: rel,
+                    absPath: dir,
+                    hasNxProject: hasNx,
+                });
+            }
+            return; // don't recurse into nested sub-packages unless needed
+        }
+        try {
+            const entries = fs.readdirSync(dir, { withFileTypes: true });
+            for (const entry of entries) {
+                if (entry.isDirectory()) {
+                    search(path.join(dir, entry.name), currentDepth + 1, maxDepth);
+                }
+            }
+        }
+        catch { }
+    }
+    // If patterns exist from pnpm-workspace.yaml, search those roots
+    if (patterns.length > 0) {
+        for (const pat of patterns) {
+            const cleanPat = pat.replace(/\/\*\*?$/, "").replace(/\/\*$/, "");
+            const searchRoot = path.join(cwd, cleanPat);
+            if (fs.existsSync(searchRoot)) {
+                const stat = fs.statSync(searchRoot);
+                if (stat.isDirectory()) {
+                    const entries = fs.readdirSync(searchRoot, { withFileTypes: true });
+                    for (const e of entries) {
+                        if (e.isDirectory()) {
+                            search(path.join(searchRoot, e.name), 1, 3);
+                        }
+                    }
+                }
+            }
+        }
+    }
+    // Fallback search in standard directories if nothing found
+    if (foundProjects.length === 0) {
+        for (const fallback of ["modules", "packages", "apps", "libs", "features"]) {
+            const fbPath = path.join(cwd, fallback);
+            if (fs.existsSync(fbPath)) {
+                search(fbPath, 1, 3);
+            }
+        }
+    }
+    return foundProjects;
+}
 export async function initCommand(options = {}) {
     const cwd = process.cwd();
     const existingConfig = ConfigLoader.findConfigFile(cwd);
-    if (existingConfig && !options.force) {
+    if (existingConfig && existingConfig === path.join(cwd, path.basename(existingConfig)) && !options.force) {
         console.log(`\x1b[33m[TestSpectra]\x1b[0m Config already exists at ${path.basename(existingConfig)}. Use --force to overwrite.`);
         return;
     }
-    // Interactive Prompt if template is not specified
-    let selectedTemplate = options.template;
-    if (!selectedTemplate) {
-        // Detect if we are inside an Nx workspace
-        let isNx = false;
-        let checkNx = cwd;
-        while (checkNx !== path.dirname(checkNx)) {
-            if (fs.existsSync(path.join(checkNx, "nx.json"))) {
-                isNx = true;
-                break;
-            }
-            checkNx = path.dirname(checkNx);
+    // Detect monorepo environment
+    let isMonorepo = false;
+    let pnpmPatterns = [];
+    const pnpmWorkspacePath = path.join(cwd, "pnpm-workspace.yaml");
+    const nxJsonPath = path.join(cwd, "nx.json");
+    if (fs.existsSync(pnpmWorkspacePath)) {
+        isMonorepo = true;
+        try {
+            const content = fs.readFileSync(pnpmWorkspacePath, "utf-8");
+            pnpmPatterns = parsePnpmWorkspaceGlobs(content);
         }
+        catch { }
+    }
+    else if (fs.existsSync(nxJsonPath)) {
+        isMonorepo = true;
+    }
+    const detectedProjects = isMonorepo ? scanDirectoriesForProjects(cwd, pnpmPatterns) : [];
+    let selectedTemplate = options.template;
+    if (!selectedTemplate && !options.force) {
+        const choices = [
+            { name: "Standard (Standalone or single project)", value: "default" },
+            { name: "Nx Monorepo (Interactive multi-module feature discovery & centralized config)", value: "nx" },
+        ];
         const answers = await inquirer.prompt([
             {
                 type: "list",
                 name: "template",
-                message: "Select TestSpectra project template:",
-                choices: [
-                    { name: "Standard (Standalone or standard monorepo)", value: "default" },
-                    { name: "Nx Monorepo (Includes project.json with Nx targets & affected support)", value: "nx" },
-                ],
-                default: isNx ? "nx" : "default",
+                message: "Select TestSpectra setup mode:",
+                choices,
+                default: isMonorepo ? "nx" : "default",
             },
         ]);
         selectedTemplate = answers.template;
     }
-    const templateName = selectedTemplate || "default";
+    const templateName = selectedTemplate || (isMonorepo ? "nx" : "default");
     // 1. Resolve template directory
     const __filename = fileURLToPath(import.meta.url);
     const __dirname = path.dirname(__filename);
@@ -52,8 +163,8 @@ export async function initCommand(options = {}) {
     if (!fs.existsSync(templateDir)) {
         throw new Error(`[TestSpectra] Scaffold template directory not found at: ${templateDir}`);
     }
-    // 2. Dynamically resolve CLI version
-    let cliVersion = "^1.0.6";
+    // 2. Resolve CLI dependency version
+    let cliVersion = "^1.0.17";
     try {
         const cliPackageJsonPath = path.resolve(__dirname, "../../package.json");
         if (fs.existsSync(cliPackageJsonPath)) {
@@ -64,7 +175,6 @@ export async function initCommand(options = {}) {
         }
     }
     catch { }
-    // Check if cwd is inside the testspectra monorepo with a pnpm-workspace.yaml
     let isInternalWorkspace = false;
     let cur = cwd;
     while (cur !== path.dirname(cur)) {
@@ -80,10 +190,10 @@ export async function initCommand(options = {}) {
         }
         cur = path.dirname(cur);
     }
-    const cliDepVersion = isInternalWorkspace ? "workspace:*" : cliVersion;
     const projectName = path.basename(cwd);
-    // 3. Recursive copy function with variable replacement
-    function copyRecursive(src, dest) {
+    const cliDepVersion = isInternalWorkspace ? "workspace:*" : cliVersion;
+    // Helper: Copy directory contents recursively
+    function copyRecursive(src, dest, replacements = {}) {
         const base = path.basename(src);
         if (base === "node_modules" || base === "dist" || base === ".testspectra" || base === ".git") {
             return;
@@ -95,41 +205,248 @@ export async function initCommand(options = {}) {
             }
             const entries = fs.readdirSync(src);
             for (const entry of entries) {
-                copyRecursive(path.join(src, entry), path.join(dest, entry));
+                copyRecursive(path.join(src, entry), path.join(dest, entry), replacements);
             }
         }
         else {
-            // If destination exists and force is not set, skip
             if (fs.existsSync(dest) && !options.force) {
                 return;
             }
             let content = fs.readFileSync(src, "utf-8");
-            if (src.endsWith("package.json")) {
+            for (const [k, v] of Object.entries(replacements)) {
+                content = content.replaceAll(k, v);
+            }
+            if (dest.endsWith("package.json")) {
                 try {
-                    const pkgObj = JSON.parse(content);
-                    if (src === path.join(templateDir, "package.json")) {
-                        pkgObj.name = projectName;
+                    const pkg = JSON.parse(content);
+                    if (pkg.devDependencies && pkg.devDependencies["@testspectra/cli"]) {
+                        pkg.devDependencies["@testspectra/cli"] = cliDepVersion;
                     }
-                    if (pkgObj.devDependencies && pkgObj.devDependencies["@testspectra/cli"]) {
-                        pkgObj.devDependencies["@testspectra/cli"] = cliDepVersion;
+                    if (pkg.dependencies && pkg.dependencies["@testspectra/cli"]) {
+                        pkg.dependencies["@testspectra/cli"] = cliDepVersion;
                     }
-                    if (pkgObj.dependencies && pkgObj.dependencies["@testspectra/cli"]) {
-                        pkgObj.dependencies["@testspectra/cli"] = cliDepVersion;
-                    }
-                    content = JSON.stringify(pkgObj, null, 2);
+                    content = JSON.stringify(pkg, null, 2);
                 }
                 catch { }
             }
-            else if (src.endsWith("project.json")) {
-                content = content
-                    .replace(/\{\{PROJECT_NAME\}\}/g, projectName)
-                    .replace(/\{\{PROJECT_DIR\}\}/g, path.relative(cur, cwd) || ".");
-            }
             fs.writeFileSync(dest, content, "utf-8");
         }
     }
+    // --- MONOREPO INTERACTIVE FLOW ---
+    if (templateName === "nx" && (detectedProjects.length > 0 || isMonorepo)) {
+        console.log(`\n\x1b[36m[TestSpectra Monorepo Discovery]\x1b[0m`);
+        console.log(`Found ${detectedProjects.length} workspace feature project(s).`);
+        let chosenProjects = [];
+        if (detectedProjects.length > 0) {
+            const projectAnswers = await inquirer.prompt([
+                {
+                    type: "checkbox",
+                    name: "selectedProjects",
+                    message: "Select workspace features where TestSpectra should be initialized:",
+                    choices: detectedProjects.map((p) => ({
+                        name: `${p.relPath} (${p.name})${p.hasNxProject ? " [Nx project.json]" : ""}`,
+                        value: p.relPath,
+                        checked: true,
+                    })),
+                },
+            ]);
+            chosenProjects = projectAnswers.selectedProjects;
+        }
+        const folderAnswers = await inquirer.prompt([
+            {
+                type: "input",
+                name: "e2eFolderName",
+                message: "Enter E2E test folder name for each selected feature:",
+                default: "e2e",
+            },
+            {
+                type: "input",
+                name: "sharedTestingPath",
+                message: "Enter path for Shared Testing library (POMs, Steps, Actions, Fixtures):",
+                default: "shared/testing",
+            },
+        ]);
+        const e2eFolderName = folderAnswers.e2eFolderName.trim() || "e2e";
+        const sharedTestingRelPath = folderAnswers.sharedTestingPath.trim() || "shared/testing";
+        const sharedTestingAbsPath = path.join(cwd, sharedTestingRelPath);
+        // 1. Centralized Root Config
+        const rootConfigSrc = path.join(templateDir, "spectra.config.ts");
+        const rootConfigDest = path.join(cwd, "spectra.config.ts");
+        if (fs.existsSync(rootConfigSrc) && (!fs.existsSync(rootConfigDest) || options.force)) {
+            fs.copyFileSync(rootConfigSrc, rootConfigDest);
+            console.log(`\x1b[32m[TestSpectra]\x1b[0m Created centralized configuration at ./spectra.config.ts`);
+        }
+        // 2. Centralized Root .testspectra folder for cache/logs
+        const rootTestDataDir = path.join(cwd, ".testspectra");
+        if (!fs.existsSync(rootTestDataDir)) {
+            fs.mkdirSync(rootTestDataDir, { recursive: true });
+        }
+        // 3. Centralized Shared Testing Library
+        const sharedTestingSrc = path.join(templateDir, "shared/testing");
+        if (fs.existsSync(sharedTestingSrc)) {
+            copyRecursive(sharedTestingSrc, sharedTestingAbsPath);
+            console.log(`\x1b[32m[TestSpectra]\x1b[0m Initialized shared testing library at ./${sharedTestingRelPath}`);
+        }
+        // 4. Distribute E2E Folders to Selected Feature Modules
+        const sampleE2eSrc = path.join(templateDir, "modules/auth/e2e");
+        const featureE2eDirs = [];
+        for (const projRel of chosenProjects) {
+            const targetE2eDir = path.join(cwd, projRel, e2eFolderName);
+            const featureName = path.basename(projRel);
+            const e2eProjectName = `${featureName}-${e2eFolderName}`;
+            copyRecursive(sampleE2eSrc, targetE2eDir, {
+                "auth-e2e": e2eProjectName,
+                "modules/auth/e2e": path.relative(cwd, targetE2eDir).replace(/\\/g, "/"),
+                "scope:auth": `scope:${featureName}`,
+            });
+            // Adjust project.json
+            const projJsonPath = path.join(targetE2eDir, "project.json");
+            if (fs.existsSync(projJsonPath)) {
+                try {
+                    const pObj = JSON.parse(fs.readFileSync(projJsonPath, "utf-8"));
+                    pObj.name = e2eProjectName;
+                    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 = path.relative(cwd, targetE2eDir).replace(/\\/g, "/");
+                    pObj.tags = [`scope:${featureName}`, "type:e2e"];
+                    fs.writeFileSync(projJsonPath, JSON.stringify(pObj, null, 2), "utf-8");
+                }
+                catch { }
+            }
+            // Ensure no local spectra.config.ts (centralized in root)
+            const localConfig = path.join(targetE2eDir, "spectra.config.ts");
+            if (fs.existsSync(localConfig))
+                fs.unlinkSync(localConfig);
+            featureE2eDirs.push(targetE2eDir);
+            console.log(`\x1b[32m[TestSpectra]\x1b[0m Initialized ${e2eProjectName} in ./${path.relative(cwd, targetE2eDir)}`);
+        }
+        // 5. Update Root Solution tsconfig.json references
+        const rootTsConfigPath = path.join(cwd, "tsconfig.json");
+        const references = [];
+        for (const e2eDir of featureE2eDirs) {
+            references.push({ path: `./${path.relative(cwd, e2eDir).replace(/\\/g, "/")}` });
+        }
+        references.push({ path: `./${sharedTestingRelPath.replace(/\\/g, "/")}` });
+        let rootTsConfig = { files: [], references: [] };
+        if (fs.existsSync(rootTsConfigPath)) {
+            try {
+                rootTsConfig = JSON.parse(fs.readFileSync(rootTsConfigPath, "utf-8"));
+                if (!rootTsConfig.references)
+                    rootTsConfig.references = [];
+                for (const ref of references) {
+                    if (!rootTsConfig.references.some((r) => r.path === ref.path)) {
+                        rootTsConfig.references.push(ref);
+                    }
+                }
+            }
+            catch { }
+        }
+        else {
+            rootTsConfig = { files: [], references };
+        }
+        // 6. Generate Ambient Types for Shared + All E2E Feature Directories
+        TypeGenerator.writeDeclarationFiles(cwd);
+        for (const e2eDir of featureE2eDirs) {
+            TypeGenerator.writeDeclarationFiles(e2eDir);
+        }
+        // 7. Generate ARCHITECTURE.md in root documenting the exact generated layout
+        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/\`: Centralized app data folder containing driver caches (ChromeDriver, GeckoDriver, Appium), execution logs, and universal ambient types (\`.testspectra/types/\`).
+- \`./nx.json\`: Nx target defaults with execution caching and inputs.
+- \`./pnpm-workspace.yaml\`: Monorepo package glob definitions.
+- \`./tsconfig.json\`: Solution-style TypeScript orchestrator linking all distributed E2E projects and shared libraries.
+
+### Centralized Shared 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));
+            return `- \`./${rel}\` (**${name}**):
+  - \`specs/\`: Feature test cases (\`specs/<SuiteName>/<CaseId>/\` for web, android, ios).
+  - \`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\`).
+  - \`tsconfig.json\`: Solution TypeScript config reference.`;
+        }).join("\n")}
+
+---
+
+## 2. Zero-Import Consumption Flow
+
+\`\`\`
+  ┌──────────────────────────────┐          ┌──────────────────────────────┐
+  │ shared/testing/page-objects  │          │   modules/*/e2e/specs/       │
+  │ shared/testing/steps         │ ───────► │   (Zero-Import Test Cases)   │
+  │ shared/testing/actions       │          │   - NavigationBar.goToHome() │
+  │ shared/testing/fixtures      │          │   - Step.loginAsAdmin()      │
+  └──────────────────────────────┘          │   - Spectra.dismissBanner()  │
+                                            └──────────────────────────────┘
+\`\`\`
+
+---
+
+## 3. Running Tests via Nx
+
+\`\`\`bash
+# Run all feature E2E suites in parallel
+pnpm nx run-many -t e2e
+
+# Run only E2E tests for features changed in PR
+pnpm nx affected -t e2e
+
+# Run E2E for a specific feature on Android
+pnpm nx run auth-${e2eFolderName}:e2e --configuration=android
+
+# Run type check across all E2E projects
+pnpm nx run-many -t type-check
+# Or standard TypeScript compilation
+pnpm type-check
+\`\`\`
+`;
+        fs.writeFileSync(path.join(cwd, "ARCHITECTURE.md"), archDocContent, "utf-8");
+        // 8. Update root README.md
+        const rootReadmePath = path.join(cwd, "README.md");
+        const readmeContent = `# ${projectName} (TestSpectra Monorepo)
+
+Automated cross-platform E2E testing powered by [TestSpectra](https://github.com/testspectra).
+
+## Architecture & Layout
+
+This project follows TestSpectra's **Centralized Configuration, Distributed Implementation** architecture.
+Detailed architecture, file locations, and zero-import mechanics are documented in:
+👉 **[ARCHITECTURE.md](./ARCHITECTURE.md)**
+
+## Commands
+
+- **Run all E2E tests**: \`pnpm nx run-many -t e2e\`
+- **Run affected E2E tests**: \`pnpm nx affected -t e2e\`
+- **Type-check all suites**: \`pnpm type-check\`
+`;
+        fs.writeFileSync(rootReadmePath, readmeContent, "utf-8");
+        console.log(`\n\x1b[32m[TestSpectra]\x1b[0m Enterprise Nx Monorepo initialized successfully!`);
+        console.log(`\x1b[36m- Centralized Configuration:\x1b[0m ./spectra.config.ts`);
+        console.log(`\x1b[36m- Centralized App Data/Cache:\x1b[0m ./.testspectra/`);
+        console.log(`\x1b[36m- Shared Testing Library:\x1b[0m ./${sharedTestingRelPath}`);
+        console.log(`\x1b[36m- Architecture Documentation:\x1b[0m ./ARCHITECTURE.md`);
+        console.log(`\x1b[36m- Initialized Features (${featureE2eDirs.length}):\x1b[0m\n  ${featureE2eDirs.map((d) => path.relative(cwd, d)).join("\n  ")}`);
+        return;
+    }
+    // --- STANDALONE / DEFAULT PROJECT FLOW ---
     copyRecursive(templateDir, cwd);
-    // 4. Pre-configure pnpm allowBuilds for standalone projects
     if (!isInternalWorkspace) {
         const pnpmWorkspacePath = path.join(cwd, "pnpm-workspace.yaml");
         if (!fs.existsSync(pnpmWorkspacePath) || options.force) {
@@ -137,21 +454,50 @@ export async function initCommand(options = {}) {
             fs.writeFileSync(pnpmWorkspacePath, pnpmWsContent, "utf-8");
         }
     }
-    // 5. Generate ambient declaration files
     TypeGenerator.writeDeclarationFiles(cwd);
-    // If subprojects exist (e.g. in Nx monorepo template), generate types for them as well
-    const modulesDir = path.join(cwd, "modules");
-    if (fs.existsSync(modulesDir)) {
-        const mods = fs.readdirSync(modulesDir, { withFileTypes: true });
-        for (const m of mods) {
-            if (m.isDirectory()) {
-                const e2eDir = path.join(modulesDir, m.name, "e2e");
-                if (fs.existsSync(e2eDir)) {
-                    TypeGenerator.writeDeclarationFiles(e2eDir);
-                }
-            }
-        }
-    }
+    // 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");
+    const standaloneReadme = `# ${projectName}
+
+TestSpectra automated testing project.
+
+## Architecture & Layout
+Detailed architecture and folder structure are documented in:
+👉 **[ARCHITECTURE.md](./ARCHITECTURE.md)**
+
+## Commands
+- **Run tests**: \`pnpm test\`
+- **Type-check**: \`pnpm type-check\`
+`;
+    fs.writeFileSync(path.join(cwd, "README.md"), standaloneReadme, "utf-8");
     console.log(`\x1b[32m[TestSpectra]\x1b[0m Initialized project from template successfully!`);
+    console.log(`\x1b[32m[TestSpectra]\x1b[0m Generated documentation at ./ARCHITECTURE.md`);
     console.log(`\x1b[32m[TestSpectra]\x1b[0m Generated ambient multi-platform types in .testspectra/types/`);
 }

package/dist/commands/run.js

@@ -13,7 +13,17 @@ export async function runCommand(specPath, options = {}) {
         config.webConfig.headlessMode = options.headless;
     }
     const platform = options.target || "web";
-    const appDataPath = options.workdir ? path.resolve(options.workdir) : path.join(cwd, ".testspectra");
+    // Find workspace root for centralized .testspectra
+    let workspaceRoot = cwd;
+    let cur = cwd;
+    while (cur !== path.dirname(cur)) {
+        if (fs.existsSync(path.join(cur, "pnpm-workspace.yaml")) || fs.existsSync(path.join(cur, "nx.json")) || fs.existsSync(path.join(cur, "spectra.config.ts")) || fs.existsSync(path.join(cur, "testspectra.config.ts"))) {
+            workspaceRoot = cur;
+            break;
+        }
+        cur = path.dirname(cur);
+    }
+    const appDataPath = options.workdir ? path.resolve(options.workdir) : path.join(workspaceRoot, ".testspectra");
     if (!fs.existsSync(appDataPath)) {
         fs.mkdirSync(appDataPath, { recursive: true });
     }

package/dist/config/loader.js

@@ -11,11 +11,18 @@ export class ConfigLoader {
         ".testspectrarc.json",
     ];
     static findConfigFile(cwd = process.cwd()) {
-        for (const filename of this.CONFIG_FILE_NAMES) {
-            const fullPath = path.join(cwd, filename);
-            if (fs.existsSync(fullPath)) {
-                return fullPath;
+        let cur = path.resolve(cwd);
+        while (true) {
+            for (const filename of this.CONFIG_FILE_NAMES) {
+                const fullPath = path.join(cur, filename);
+                if (fs.existsSync(fullPath)) {
+                    return fullPath;
+                }
             }
+            const parent = path.dirname(cur);
+            if (parent === cur)
+                break;
+            cur = parent;
         }
         return null;
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@testspectra/cli",
-  "version": "1.0.17",
+  "version": "1.0.19",
   "description": "TestSpectra Zero-Config Cross-Platform Test Runner CLI",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",

package/templates/nx/modules/catalog/e2e/spectra.config.ts

@@ -1,61 +0,0 @@
-import { defineConfig } from "@testspectra/cli";
-
-export default defineConfig({
-  webConfig: {
-    baseUrl: "https://the-internet.herokuapp.com",
-    maxConcurrentSessions: "1",
-    headlessMode: true,
-    implicitWait: "5000",
-    pageLoadTimeout: "30000",
-    scriptTimeout: "30000",
-    parallelizationMode: "testcase",
-  },
-  browsers: [
-    {
-      id: "chrome-desktop",
-      type: "chrome",
-      mobileEmulation: false,
-    },
-  ],
-  androidConfig: {
-    appiumServer: "http://127.0.0.1:4723",
-    platformName: "Android",
-    platformVersion: "13",
-    deviceName: "emulator-5554",
-    automationName: "UiAutomator2",
-    appPackage: "",
-    appActivity: "",
-    autoGrantPermissions: true,
-    noReset: false,
-    implicitWait: "10000",
-    parallelizationMode: "suite",
-  },
-  iosConfig: {
-    appiumServer: "http://127.0.0.1:4723",
-    platformName: "iOS",
-    platformVersion: "16.0",
-    deviceName: "iPhone 14",
-    automationName: "XCUITest",
-    bundleId: "",
-    udid: "auto",
-    xcodeOrgId: "",
-    xcodeSigningId: "iPhone Developer",
-    autoAcceptAlerts: true,
-    noReset: false,
-    implicitWait: "10000",
-    parallelizationMode: "suite",
-  },
-  loadConfig: {
-    virtualUsers: "10",
-    duration: "1m",
-  },
-  loadStages: [],
-  thresholds: [],
-  executionConfig: {
-    networkMonitoringEnabled: true,
-    fastResponseTime: "200",
-    normalResponseTime: "1000",
-    monitoredDomains: [],
-    environmentVariables: [],
-  },
-});