@testspectra/cli 1.1.7 → 1.1.8-rc.2

package/dist/commands/demo.js

@@ -1,24 +1,34 @@
 import chalk from 'chalk';
 import * as p from '@clack/prompts';
 import { DemoServer } from '../utils/demo-server.js';
+import { DemoApiServer } from '../utils/api-server.js';
 export async function demoCommand(options) {
     const port = options.port ? parseInt(options.port, 10) : 5173;
     p.intro(chalk.bold.cyan('🌐 TestSpectra Demo Web App'));
     const server = new DemoServer(port);
+    const apiServer = new DemoApiServer();
     try {
         const { url } = await server.start();
         p.log.success(chalk.green(`Demo web app is live at: ${chalk.bold.underline(url)}`));
+        // The web app fetches its API sections from the separate self-hosted API server, so start it
+        // too — otherwise the API demo sections show only their offline fallback data.
+        try {
+            const { url: apiUrl } = await apiServer.start();
+            p.log.success(chalk.green(`Demo API server is live at: ${chalk.bold.underline(apiUrl)}`));
+        }
+        catch (err) {
+            p.log.warn(chalk.yellow(`Could not start demo API server: ${err.message}`));
+        }
         p.log.info(chalk.dim("You can now run tests against this server in another terminal (e.g. 'spectra run -t web')."));
-        p.log.info(chalk.dim('Press Ctrl+C to stop the server.'));
+        p.log.info(chalk.dim('Press Ctrl+C to stop the servers.'));
         // Handle termination gracefully
-        process.on('SIGINT', async () => {
+        const shutdown = async () => {
             await server.stop();
+            await apiServer.stop();
             process.exit(0);
-        });
-        process.on('SIGTERM', async () => {
-            await server.stop();
-            process.exit(0);
-        });
+        };
+        process.on('SIGINT', shutdown);
+        process.on('SIGTERM', shutdown);
         await new Promise(() => { });
     }
     catch (err) {

package/dist/commands/init.d.ts

@@ -1,5 +1,5 @@
 export interface InitCommandOptions {
     force?: boolean;
-    template?: 'default' | 'nx';
+    template?: 'default' | 'nx' | 'react-component';
 }
 export declare function initCommand(options?: InitCommandOptions): Promise<void>;

package/dist/commands/init.js

@@ -215,10 +215,15 @@ export async function initCommand(options = {}) {
                     hint: 'Interactive workspace feature discovery & centralized config',
                 },
                 {
-                    label: 'Standard Project',
+                    label: 'Standard E2E Project',
                     value: 'default',
                     hint: 'Standalone single-suite E2E testing project',
                 },
+                {
+                    label: 'React Component Testing',
+                    value: 'react-component',
+                    hint: 'Real-browser React component testing with Vite & Testing Library',
+                },
             ],
         });
         if (p.isCancel(templateChoice)) {
@@ -552,135 +557,135 @@ 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)
+        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\`).
+            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
-\`\`\`
+            .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');
         // 8. Ensure root .gitignore ignores .testspectra/ and *.tsbuildinfo
@@ -736,32 +741,32 @@ 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
-\`\`\`
+    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');
     // Safely update root README.md (do not overwrite existing content)

package/dist/commands/lint.d.ts

@@ -0,0 +1,5 @@
+import type { LintOptions } from '../linter/types.js';
+export interface LintCommandOptions extends LintOptions {
+    path?: string;
+}
+export declare function lintCommand(targetPath?: string, options?: LintCommandOptions): Promise<void>;

package/dist/commands/lint.js

@@ -0,0 +1,55 @@
+import path from 'path';
+import chalk from 'chalk';
+import { SpecLinter } from '../linter/spec-linter.js';
+export async function lintCommand(targetPath, options = {}) {
+    const cwd = options.cwd ? path.resolve(options.cwd) : process.cwd();
+    try {
+        const result = SpecLinter.validateWorkspace(cwd, targetPath);
+        if (options.json) {
+            console.log(JSON.stringify(result, null, 2));
+            if (!result.valid || (options.strict && result.stats.warningCount > 0)) {
+                process.exit(1);
+            }
+            return;
+        }
+        console.log(chalk.bold('\n🔍 TestSpectra Spec & Code Linter\n'));
+        // Group diagnostics by file
+        const diagnosticsByFile = new Map();
+        for (const diag of result.diagnostics) {
+            const relPath = path.relative(cwd, diag.filePath);
+            const list = diagnosticsByFile.get(relPath) || [];
+            list.push(diag);
+            diagnosticsByFile.set(relPath, list);
+        }
+        if (diagnosticsByFile.size === 0) {
+            console.log(chalk.green(`  ✓ ${result.stats.totalSpecs} specs and ${result.stats.totalSuites} suites verified.`));
+            console.log(chalk.green.bold('\n✓ All spec schemas are valid. 0 lint errors found.\n'));
+            return;
+        }
+        for (const [file, diags] of diagnosticsByFile.entries()) {
+            console.log(chalk.bold(`  ${file}`));
+            for (const diag of diags) {
+                const icon = diag.severity === 'error' ? chalk.red('✗') : chalk.yellow('⚠');
+                const codeTag = chalk.gray(`[${diag.code}]`);
+                const loc = chalk.dim(`:${diag.line}`);
+                console.log(`    ${icon} ${codeTag} ${diag.message} ${loc}`);
+            }
+            console.log();
+        }
+        const { errorCount, warningCount } = result.stats;
+        if (errorCount > 0) {
+            console.log(chalk.red.bold(`✖ ${errorCount} lint error${errorCount > 1 ? 's' : ''}${warningCount > 0 ? ` and ${warningCount} warning${warningCount > 1 ? 's' : ''}` : ''} found.\n`));
+            process.exit(1);
+        }
+        else if (warningCount > 0) {
+            console.log(chalk.yellow.bold(`⚠ ${warningCount} lint warning${warningCount > 1 ? 's' : ''} found.\n`));
+            if (options.strict) {
+                process.exit(1);
+            }
+        }
+    }
+    catch (err) {
+        console.error(chalk.red(`\n✖ Fatal error during linting: ${err?.message || err}\n`));
+        process.exit(2);
+    }
+}

package/dist/commands/refactor.d.ts

@@ -1,3 +1,4 @@
+import { RefactorResult } from '../refactor/refactor-engine.js';
 export interface RefactorCommandOptions {
     cwd?: string;
     dryRun?: boolean;
@@ -5,4 +6,4 @@ export interface RefactorCommandOptions {
     from?: string;
     to?: string;
 }
-export declare function refactorCommand(entityType?: string, oldName?: string, newName?: string, options?: RefactorCommandOptions): Promise<void>;
+export declare function refactorCommand(entityType?: string, oldName?: string, newName?: string, options?: RefactorCommandOptions): Promise<RefactorResult>;

package/dist/commands/refactor.js

@@ -5,52 +5,142 @@ export async function refactorCommand(entityType, oldName, newName, options = {}
     let targetType = 'page-object';
     let fromSymbol = oldName || '';
     let toSymbol = newName || '';
-    if (options.from && options.to) {
-        // Path-based refactoring
-        if (options.from.includes('page-objects')) {
-            targetType = 'page-object';
-            fromSymbol = path.basename(options.from);
-            toSymbol = path.basename(options.to);
+    // 1. Path-based refactoring via --from and --to flags
+    if (options.from || options.to) {
+        if (!options.from || !options.to) {
+            const errorMsg = 'Both --from and --to must be specified for path-based refactoring.';
+            const result = {
+                status: 'failed',
+                entityType: 'page-object',
+                oldSymbol: options.from || '',
+                newSymbol: options.to || '',
+                modifiedFiles: [],
+                occurrencesReplaced: 0,
+                error: errorMsg,
+            };
+            if (options.json) {
+                console.log(JSON.stringify(result, null, 2));
+            }
+            else {
+                console.error(`\x1b[31m✗ ${errorMsg}\x1b[0m`);
+            }
+            process.exitCode = 1;
+            return result;
         }
-        else if (options.from.includes('steps')) {
-            targetType = 'step';
-            fromSymbol = path.basename(options.from);
-            toSymbol = path.basename(options.to);
+        const pathResult = await RefactorEngine.renameFromPaths({
+            workspaceRoot,
+            fromPath: options.from,
+            toPath: options.to,
+            dryRun: options.dryRun,
+        });
+        if (options.json) {
+            console.log(JSON.stringify(pathResult, null, 2));
+            if (pathResult.status === 'failed') {
+                process.exitCode = 1;
+            }
+            return pathResult;
         }
-        else if (options.from.includes('actions')) {
-            targetType = 'action';
-            fromSymbol = path.basename(options.from);
-            toSymbol = path.basename(options.to);
+        if (pathResult.status === 'success') {
+            const modeStr = options.dryRun ? '[Dry-Run] ' : '';
+            console.log(`\x1b[32m✓ ${modeStr}Refactored ${pathResult.entityType} "${pathResult.oldSymbol}" → "${pathResult.newSymbol}"\x1b[0m`);
+            console.log(`  Modified files: ${pathResult.modifiedFiles.length}`);
+            console.log(`  Occurrences replaced: ${pathResult.occurrencesReplaced}`);
+            for (const f of pathResult.modifiedFiles) {
+                console.log(`    ↳ ${f}`);
+            }
         }
-        else if (options.from.includes('fixtures')) {
-            targetType = 'fixture';
-            fromSymbol = path.parse(options.from).name;
-            toSymbol = path.parse(options.to).name;
+        else {
+            console.error(`\x1b[31m✗ Refactoring failed: ${pathResult.error}\x1b[0m`);
+            process.exitCode = 1;
         }
+        return pathResult;
     }
-    else {
-        if (!entityType || !oldName || !newName) {
-            console.error('Usage: spectra refactor <page-object|step|action|fixture> <oldName> <newName>');
-            process.exit(1);
+    // 2. Also support positional path syntax: spectra refactor <fromPath> <toPath>
+    if (entityType && oldName && !newName && RefactorEngine.parseEntityFromPath(entityType)) {
+        const pathResult = await RefactorEngine.renameFromPaths({
+            workspaceRoot,
+            fromPath: entityType,
+            toPath: oldName,
+            dryRun: options.dryRun,
+        });
+        if (options.json) {
+            console.log(JSON.stringify(pathResult, null, 2));
+            if (pathResult.status === 'failed') {
+                process.exitCode = 1;
+            }
+            return pathResult;
         }
-        const normalized = entityType.toLowerCase().replace(/_/g, '-');
-        if (['page-object', 'po', 'page'].includes(normalized)) {
-            targetType = 'page-object';
+        if (pathResult.status === 'success') {
+            const modeStr = options.dryRun ? '[Dry-Run] ' : '';
+            console.log(`\x1b[32m✓ ${modeStr}Refactored ${pathResult.entityType} "${pathResult.oldSymbol}" → "${pathResult.newSymbol}"\x1b[0m`);
+            console.log(`  Modified files: ${pathResult.modifiedFiles.length}`);
+            console.log(`  Occurrences replaced: ${pathResult.occurrencesReplaced}`);
+            for (const f of pathResult.modifiedFiles) {
+                console.log(`    ↳ ${f}`);
+            }
         }
-        else if (['step', 'steps'].includes(normalized)) {
-            targetType = 'step';
+        else {
+            console.error(`\x1b[31m✗ Refactoring failed: ${pathResult.error}\x1b[0m`);
+            process.exitCode = 1;
         }
-        else if (['action', 'actions'].includes(normalized)) {
-            targetType = 'action';
+        return pathResult;
+    }
+    // 3. Positional syntax: spectra refactor <entityType> <oldName> <newName>
+    if (!entityType || !oldName || !newName) {
+        const errorMsg = 'Usage: spectra refactor <page-object|step|action|fixture> <oldName> <newName> or spectra refactor --from <path> --to <path>';
+        const result = {
+            status: 'failed',
+            entityType: 'page-object',
+            oldSymbol: oldName || '',
+            newSymbol: newName || '',
+            modifiedFiles: [],
+            occurrencesReplaced: 0,
+            error: errorMsg,
+        };
+        if (options.json) {
+            console.log(JSON.stringify(result, null, 2));
         }
-        else if (['fixture', 'fixtures'].includes(normalized)) {
-            targetType = 'fixture';
+        else {
+            console.error(errorMsg);
+        }
+        process.exitCode = 1;
+        return result;
+    }
+    const normalized = entityType.toLowerCase().replace(/_/g, '-');
+    if (['page-object', 'po', 'page', 'pageobject'].includes(normalized)) {
+        targetType = 'page-object';
+    }
+    else if (['step', 'steps'].includes(normalized)) {
+        targetType = 'step';
+    }
+    else if (['action', 'actions'].includes(normalized)) {
+        targetType = 'action';
+    }
+    else if (['fixture', 'fixtures'].includes(normalized)) {
+        targetType = 'fixture';
+    }
+    else {
+        const errorMsg = `Unknown refactor entity type: "${entityType}". Valid types: page-object, step, action, fixture.`;
+        const result = {
+            status: 'failed',
+            entityType: 'page-object',
+            oldSymbol: oldName,
+            newSymbol: newName,
+            modifiedFiles: [],
+            occurrencesReplaced: 0,
+            error: errorMsg,
+        };
+        if (options.json) {
+            console.log(JSON.stringify(result, null, 2));
         }
         else {
-            console.error(`Unknown refactor entity type: "${entityType}". Valid types: page-object, step, action, fixture.`);
-            process.exit(1);
+            console.error(`\x1b[31m✗ ${errorMsg}\x1b[0m`);
         }
+        process.exitCode = 1;
+        return result;
     }
+    fromSymbol = oldName;
+    toSymbol = newName;
     const result = await RefactorEngine.renameSymbol({
         workspaceRoot,
         type: targetType,
@@ -60,7 +150,10 @@ export async function refactorCommand(entityType, oldName, newName, options = {}
     });
     if (options.json) {
         console.log(JSON.stringify(result, null, 2));
-        return;
+        if (result.status === 'failed') {
+            process.exitCode = 1;
+        }
+        return result;
     }
     if (result.status === 'success') {
         const modeStr = options.dryRun ? '[Dry-Run] ' : '';
@@ -73,6 +166,7 @@ export async function refactorCommand(entityType, oldName, newName, options = {}
     }
     else {
         console.error(`\x1b[31m✗ Refactoring failed: ${result.error}\x1b[0m`);
-        process.exit(1);
+        process.exitCode = 1;
     }
+    return result;
 }