@testspectra/cli 1.0.70 → 1.1.1

package/dist/index.js

@@ -1,72 +1,145 @@
-import { Command } from "commander";
-import { addCommand } from "./commands/add.js";
-import { demoCommand } from "./commands/demo.js";
-import { devicesCommand } from "./commands/devices.js";
-import { doctorCommand } from "./commands/doctor.js";
-import { initCommand } from "./commands/init.js";
-import { runCommand } from "./commands/run.js";
-import { updateCommand } from "./commands/update.js";
-import { watchCommand } from "./commands/watch.js";
-export * from "./config/schema.js";
-export * from "./config/loader.js";
-export * from "./types/generator.js";
-export * from "@testspectra/matchers";
+import { Command } from 'commander';
+import { addCommand } from './commands/add.js';
+import { cloudRunCommand } from './commands/cloud-run.js';
+import { demoCommand } from './commands/demo.js';
+import { devicesCommand } from './commands/devices.js';
+import { doctorCommand } from './commands/doctor.js';
+import { initCommand } from './commands/init.js';
+import { installCommand } from './commands/install.js';
+import { runCommand } from './commands/run.js';
+import { updateCommand } from './commands/update.js';
+import { watchCommand } from './commands/watch.js';
+import { syncTypesCommand } from './commands/sync-types.js';
+import { refactorCommand } from './commands/refactor.js';
+import { licenseCommand } from './commands/license.js';
+export * from './config/schema.js';
+export * from './config/loader.js';
+export * from './generator/index.js';
+export * from './lifecycle/index.js';
+export * from './refactor/index.js';
+export * from './mobile/index.js';
+export * from './types/generator.js';
+export * from '@testspectra/matchers';
 export function createCliProgram() {
     const program = new Command();
+    program.name('spectra').description('TestSpectra Zero-Config Cross-Platform Test Runner CLI').version('1.0.0');
     program
-        .name("spectra")
-        .description("TestSpectra Zero-Config Cross-Platform Test Runner CLI")
-        .version("1.0.0");
-    program
-        .command("init")
-        .description("Initialize testspectra.config.json and project directories")
-        .option("-t, --template <template>", "Project template: default, nx")
-        .option("-f, --force", "Overwrite existing configuration if present")
+        .command('init')
+        .description('Initialize testspectra.config.json and project directories')
+        .option('-t, --template <template>', 'Project template: default, nx')
+        .option('-f, --force', 'Overwrite existing configuration if present')
         .action(initCommand);
     program
-        .command("add [module]")
-        .description("Add a new TestSpectra E2E testing module to workspace or standalone project")
-        .option("-e, --e2e-folder <name>", "Name of E2E sub-folder (default: e2e)")
-        .option("-f, --force", "Overwrite existing module files if present")
+        .command('add [module]')
+        .description('Add a new TestSpectra E2E testing module to workspace or standalone project')
+        .option('-e, --e2e-folder <name>', 'Name of E2E sub-folder (default: e2e)')
+        .option('-f, --force', 'Overwrite existing module files if present')
         .action(addCommand);
     program
-        .command("demo")
-        .description("Launch the built-in TestSpectra Demo Web App server on localhost:5173")
-        .option("-p, --port <port>", "Port to bind server (default: 5173)")
+        .command('install [dependency]')
+        .description('Install missing testing dependencies, browser drivers, and workspace packages')
+        .option('-f, --force', 'Force re-installation of dependencies')
+        .addHelpText('after', `
+Examples:
+  $ spectra install                 Install all missing required dependencies automatically
+  $ spectra install chrome          Install Google Chrome for Testing & matching Chromedriver
+  $ spectra install adb             Install Google Android SDK Platform Tools (ADB)
+  $ spectra install bun             Install Bun runtime
+  $ spectra install android-driver  Install Spectra Android Native Driver & WDIO Service
+  $ spectra install wdio            Install WebDriverIO core packages and matchers`)
+        .action(installCommand);
+    program
+        .command('demo')
+        .description('Launch the built-in TestSpectra Demo Web App server on localhost:5173')
+        .option('-p, --port <port>', 'Port to bind server (default: 5173)')
         .action(demoCommand);
     program
-        .command("watch")
-        .description("Watch workspace and continuously auto-generate TestSpectra ambient declarations")
-        .option("-w, --cwd <dir>", "Custom workspace directory")
+        .command('watch')
+        .description('Watch workspace and continuously auto-generate TestSpectra ambient declarations')
+        .option('-w, --cwd <dir>', 'Custom workspace directory')
         .action(watchCommand);
     program
-        .command("doctor")
-        .description("Verify local environment prerequisites (ADB, Java, Chrome, Bun, Node)")
-        .option("--fix", "Attempt automatic fix / download of missing tools")
-        .option("--json", "Output diagnostic results as JSON")
+        .command('sync-types')
+        .description('Scan workspace and regenerate .testspectra/types/*.d.ts ambient declarations')
+        .option('-w, --cwd <dir>', 'Custom workspace directory')
+        .action(syncTypesCommand);
+    program
+        .command('refactor [entityType] [oldName] [newName]')
+        .description('Atomically rename and propagate symbols (page-object, step, action, fixture)')
+        .option('-w, --cwd <dir>', 'Custom workspace directory')
+        .option('--from <path>', 'Source file or directory to refactor from')
+        .option('--to <path>', 'Destination file or directory to refactor to')
+        .option('--dry-run', 'Preview changes without modifying files')
+        .option('--json', 'Output results as JSON')
+        .action(refactorCommand);
+    program
+        .command('doctor')
+        .description('Verify local environment prerequisites (ADB, Spectra Android Driver, Chrome, Bun)')
+        .option('-v, --verbose', 'Show full installation paths for all detected runtimes and packages')
+        .option('--fix', 'Attempt automatic fix / download of missing tools')
+        .option('--json', 'Output diagnostic results as JSON')
         .action(doctorCommand);
     program
-        .command("update")
-        .description("Update @testspectra/cli and @testspectra/matchers to the latest version from npm")
-        .option("--check", "Only check for available updates without installing")
+        .command('update')
+        .description('Update @testspectra/cli and @testspectra/matchers to the latest version from npm')
+        .option('--check', 'Only check for available updates without installing')
         .action(updateCommand);
     program
-        .command("devices")
-        .description("List connected Android/iOS devices and local browsers")
-        .option("-t, --target <target>", "Filter scope: android, ios, web, all", "all")
+        .command('devices')
+        .description('List connected Android/iOS devices and local browsers')
+        .option('-t, --target <target>', 'Filter scope: android, ios, web, all', 'all')
+        .option('--json', 'Output results as JSON')
         .action(devicesCommand);
     program
-        .command("run [path]")
-        .description("Execute test suite or individual test case")
-        .option("-s, --spec <path>", "Spec file path to execute")
-        .option("-t, --target <target>", "Target platform: web, android, ios, common", "web")
-        .option("-d, --device <device>", "Target device name or UDID")
-        .option("--demo", "Automatically launch built-in demo web app server during test execution")
-        .option("--headless", "Run in headless mode")
-        .option("--no-headless", "Run in headed mode")
-        .option("-w, --workdir <dir>", "Custom app data / temp workdir")
-        .option("-o, --output <path>", "Custom test report JSON output path")
+        .command('license [action] [key]')
+        .description('Manage TestSpectra commercial license (activate, status, remove)')
+        .option('--json', 'Output license details as JSON')
+        .addHelpText('after', `
+Examples:
+  $ spectra license activate <KEY>   Activate license key and auto-configure private driver registry
+  $ spectra license status           Display active license organization, plan, and expiration
+  $ spectra license remove           Remove locally activated license credentials`)
+        .action(licenseCommand);
+    program
+        .command('run [path]')
+        .description('Execute test suite or individual test case')
+        .option('-s, --spec <path>', 'Spec file path to execute')
+        .option('-t, --target <target>', 'Target platform: web, android, ios, common', 'web')
+        .option('-d, --device <device>', 'Target device name or UDID')
+        .option('--all-devices', 'Distribute test execution across all connected devices')
+        .option('--multi-device', 'Distribute test execution across all connected devices (alias for --all-devices)')
+        .option('--devices <list>', 'Comma-separated list of device UDIDs to run on')
+        .option('--license-key <key>', 'Explicit commercial license key override')
+        .option('--demo', 'Automatically launch built-in demo web app server during test execution')
+        .option('--headless', 'Run in headless mode')
+        .option('--no-headless', 'Run in headed mode')
+        .option('--headed', 'Run browser in visible GUI mode (alias for --no-headless)')
+        .option('--step-delay <ms>', 'Delay between consecutive actions and commands in milliseconds (slow motion)')
+        .option('--delay <ms>', 'Alias for --step-delay')
+        .option('--failed [targets]', 'Re-run failed tests from previous run (accepts comma-separated test IDs or spec paths)')
+        .option('-c, --concurrency <number>', 'Maximum parallel worker concurrency (auto-detected if omitted)')
+        .option('-w, --workdir <dir>', 'Custom app data / temp workdir')
+        .option('-o, --output <path>', 'Custom test report JSON output path')
         .action(runCommand);
+    const cloud = program.command('cloud').description('TestSpectra Cloud commands');
+    cloud
+        .command('run')
+        .description('Trigger a TestSpectra Cloud run (spawns testspectra-runner on the cloud server) and optionally wait for the result')
+        .requiredOption('--project <id>', 'Project identifier as registered in TestSpectra')
+        .option('--project-name <name>', 'Human-readable project name (defaults to --project)')
+        .option('--branch <branch>', 'Branch to run against (defaults to the current git branch)')
+        .option('--commit <hash>', 'Commit hash (defaults to the current git HEAD)')
+        .option('--platform <platform>', 'Target platform: web | android', 'web')
+        .option('--no-wait', 'Return immediately after triggering, without waiting for the result')
+        .option('--timeout <duration>', 'Max time to wait for the run to finish (e.g. 30m, 10m)', '30m')
+        .addHelpText('after', `
+Requires SPECTRA_URL and SPECTRA_TOKEN (a Gitea Personal Access Token) as
+environment variables — see docs/v2/cloud/git-spec-standards-and-workflow.md.
+
+Examples:
+  $ spectra cloud run --project org/repo --branch main --platform web --wait
+  $ spectra cloud run --project org/repo --no-wait`)
+        .action(cloudRunCommand);
     return program;
 }
 export async function runCli(args = process.argv) {

package/dist/lifecycle/__tests__/lifecycle-engine.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/lifecycle/__tests__/lifecycle-engine.test.js

@@ -0,0 +1,290 @@
+import fs from 'fs';
+import path from 'path';
+import os from 'os';
+import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest';
+import { discoverGlobalHooks, discoverSuiteHooks } from '../hook-discovery.js';
+import { LifecycleDispatcher, HookExecutionError } from '../hook-dispatcher.js';
+import { calculateWorkerCount, groupSpecs } from '../parallel-grouping.js';
+describe('Core Lifecycle Execution Engine (docs/v2/cli/lifecycle-execution-engine.md)', () => {
+    let tmpDir;
+    beforeEach(() => {
+        tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'testspectra-lifecycle-test-'));
+    });
+    afterEach(() => {
+        try {
+            fs.rmSync(tmpDir, { recursive: true, force: true });
+        }
+        catch { }
+    });
+    describe('Hook Discovery', () => {
+        it('discovers global-hooks and filters by platform hierarchy', () => {
+            const gBefore = path.join(tmpDir, 'global-hooks', 'before');
+            const gAfter = path.join(tmpDir, 'global-hooks', 'after');
+            fs.mkdirSync(gBefore, { recursive: true });
+            fs.mkdirSync(gAfter, { recursive: true });
+            fs.writeFileSync(path.join(gBefore, 'web.hook.ts'), 'export default async () => {}');
+            fs.writeFileSync(path.join(gBefore, 'mobile.hook.ts'), 'export default async () => {}');
+            fs.writeFileSync(path.join(gBefore, 'common.hook.ts'), 'export default async () => {}');
+            fs.writeFileSync(path.join(gAfter, 'web.hook.ts'), 'export default async () => {}');
+            const webGlobal = discoverGlobalHooks(tmpDir, 'web');
+            expect(webGlobal.before.some((h) => h.endsWith('web.hook.ts'))).toBe(true);
+            expect(webGlobal.before.some((h) => h.endsWith('common.hook.ts'))).toBe(true);
+            expect(webGlobal.before.some((h) => h.endsWith('mobile.hook.ts'))).toBe(false);
+            const mobileGlobal = discoverGlobalHooks(tmpDir, 'mobile');
+            expect(mobileGlobal.before.some((h) => h.endsWith('mobile.hook.ts'))).toBe(true);
+            expect(mobileGlobal.before.some((h) => h.endsWith('common.hook.ts'))).toBe(true);
+            expect(mobileGlobal.before.some((h) => h.endsWith('web.hook.ts'))).toBe(false);
+        });
+        it('discovers suite hooks (before, beforeEach, afterEach, after)', () => {
+            const suiteDir = path.join(tmpDir, 'specs', 'Auth');
+            for (const hookType of ['before', 'beforeEach', 'afterEach', 'after']) {
+                const hDir = path.join(suiteDir, 'hooks', hookType);
+                fs.mkdirSync(hDir, { recursive: true });
+                fs.writeFileSync(path.join(hDir, 'web.hook.ts'), 'export default async () => {}');
+            }
+            const suiteHooks = discoverSuiteHooks(suiteDir, 'web');
+            expect(suiteHooks.before.length).toBe(1);
+            expect(suiteHooks.beforeEach.length).toBe(1);
+            expect(suiteHooks.afterEach.length).toBe(1);
+            expect(suiteHooks.after.length).toBe(1);
+        });
+    });
+    describe('Lifecycle Dispatcher & Execution Flow', () => {
+        it('single run executes suite hooks without triggering global hooks', async () => {
+            const executionOrder = [];
+            const globalBeforeFn = vi.fn(async () => {
+                executionOrder.push('globalBefore');
+            });
+            const globalAfterFn = vi.fn(async () => {
+                executionOrder.push('globalAfter');
+            });
+            const suiteHooks = {
+                before: [
+                    async () => {
+                        executionOrder.push('suiteBefore');
+                    },
+                ],
+                beforeEach: [
+                    async () => {
+                        executionOrder.push('beforeEach');
+                    },
+                ],
+                afterEach: [
+                    async () => {
+                        executionOrder.push('afterEach');
+                    },
+                ],
+                after: [
+                    async () => {
+                        executionOrder.push('suiteAfter');
+                    },
+                ],
+            };
+            const dispatcher = new LifecycleDispatcher('single', {
+                before: [globalBeforeFn],
+                after: [globalAfterFn],
+            });
+            // Single run bypasses global before & global after
+            await dispatcher.runGlobalBefore();
+            expect(globalBeforeFn).not.toHaveBeenCalled();
+            const result = await dispatcher.executeSuite('AuthSuite', suiteHooks, [
+                {
+                    id: 'TC-01',
+                    title: 'Valid Login',
+                    fn: async () => {
+                        executionOrder.push('testBody');
+                    },
+                },
+            ]);
+            await dispatcher.runGlobalAfter();
+            expect(globalAfterFn).not.toHaveBeenCalled();
+            expect(result.status).toBe('PASSED');
+            expect(executionOrder).toEqual(['suiteBefore', 'beforeEach', 'testBody', 'afterEach', 'suiteAfter']);
+        });
+        it('global batch run executes global-hooks/before once at start and global-hooks/after once at finish', async () => {
+            const executionOrder = [];
+            const globalBeforeFn = vi.fn(async () => {
+                executionOrder.push('globalBefore');
+            });
+            const globalAfterFn = vi.fn(async () => {
+                executionOrder.push('globalAfter');
+            });
+            const dispatcher = new LifecycleDispatcher('global', {
+                before: [globalBeforeFn],
+                after: [globalAfterFn],
+            });
+            await dispatcher.runGlobalBefore();
+            expect(globalBeforeFn).toHaveBeenCalledTimes(1);
+            const suiteHooks = {
+                before: [
+                    async () => {
+                        executionOrder.push('suiteBefore');
+                    },
+                ],
+                beforeEach: [
+                    async () => {
+                        executionOrder.push('beforeEach');
+                    },
+                ],
+                afterEach: [
+                    async () => {
+                        executionOrder.push('afterEach');
+                    },
+                ],
+                after: [
+                    async () => {
+                        executionOrder.push('suiteAfter');
+                    },
+                ],
+            };
+            const result = await dispatcher.executeSuite('AuthSuite', suiteHooks, [
+                {
+                    id: 'TC-01',
+                    title: 'Test 1',
+                    fn: async () => {
+                        executionOrder.push('tc1');
+                    },
+                },
+                {
+                    id: 'TC-02',
+                    title: 'Test 2',
+                    fn: async () => {
+                        executionOrder.push('tc2');
+                    },
+                },
+            ]);
+            await dispatcher.runGlobalAfter();
+            expect(globalAfterFn).toHaveBeenCalledTimes(1);
+            expect(result.status).toBe('PASSED');
+            expect(executionOrder).toEqual([
+                'globalBefore',
+                'suiteBefore',
+                'beforeEach',
+                'tc1',
+                'afterEach',
+                'beforeEach',
+                'tc2',
+                'afterEach',
+                'suiteAfter',
+                'globalAfter',
+            ]);
+        });
+        it('when beforeEach fails, test body is skipped, afterEach is guaranteed to execute, and test is marked as ERROR', async () => {
+            const testBodyFn = vi.fn();
+            let afterEachRan = false;
+            const suiteHooks = {
+                before: [],
+                beforeEach: [
+                    async () => {
+                        throw new Error('Database connection failed in beforeEach');
+                    },
+                ],
+                afterEach: [
+                    async () => {
+                        afterEachRan = true;
+                    },
+                ],
+                after: [],
+            };
+            const dispatcher = new LifecycleDispatcher('single');
+            const result = await dispatcher.executeSuite('FailingBeforeEachSuite', suiteHooks, [
+                {
+                    id: 'TC-FAIL-01',
+                    title: 'Should be skipped',
+                    fn: testBodyFn,
+                },
+            ]);
+            expect(testBodyFn).not.toHaveBeenCalled();
+            expect(afterEachRan).toBe(true);
+            expect(result.results[0].status).toBe('ERROR');
+            expect(result.results[0].error?.message).toContain('Database connection failed in beforeEach');
+            expect(result.status).toBe('ERROR');
+        });
+        it('when afterEach fails, test transitions to ERROR status', async () => {
+            const suiteHooks = {
+                before: [],
+                beforeEach: [],
+                afterEach: [
+                    async () => {
+                        throw new Error('Teardown resource leak in afterEach');
+                    },
+                ],
+                after: [],
+            };
+            const dispatcher = new LifecycleDispatcher('single');
+            const result = await dispatcher.executeSuite('TeardownFailSuite', suiteHooks, [
+                {
+                    id: 'TC-01',
+                    title: 'Passing Body but failing afterEach',
+                    fn: async () => {
+                        // Passing body
+                    },
+                },
+            ]);
+            expect(result.results[0].status).toBe('ERROR');
+            expect(result.results[0].error?.message).toContain('Teardown resource leak in afterEach');
+            expect(result.status).toBe('ERROR');
+        });
+        it('when global-hooks/before fails, throws HookExecutionError immediately', async () => {
+            const dispatcher = new LifecycleDispatcher('global', {
+                before: [
+                    async () => {
+                        throw new Error('Global health check failed');
+                    },
+                ],
+                after: [],
+            });
+            await expect(dispatcher.runGlobalBefore()).rejects.toThrow(HookExecutionError);
+            await expect(dispatcher.runGlobalBefore()).rejects.toThrow('Global health check failed');
+        });
+    });
+    describe('Parallel Spec Grouping & Dynamic Worker Sizing', () => {
+        it('prioritizes explicit user concurrency flag over auto-calculation', () => {
+            const targets = Array.from({ length: 10 }, () => 'spec.ts');
+            expect(calculateWorkerCount(targets, { userConcurrency: 4 })).toBe(4);
+            // Clamps to item count if items < userConcurrency
+            expect(calculateWorkerCount(['only-one.ts'], { userConcurrency: 4 })).toBe(1);
+        });
+        it('enforces low-CPU safety ratio based on container/host CPU quota', () => {
+            const targets = Array.from({ length: 10 }, () => 'spec.ts');
+            const highRam = 16 * 1024 * 1024 * 1024; // 16 GB
+            // CPU <= 2 (e.g. 2-vCPU standard CI runner): clamped to 1 worker
+            expect(calculateWorkerCount(targets, { cpuQuotaOverride: 1, memoryBytesOverride: highRam })).toBe(1);
+            expect(calculateWorkerCount(targets, { cpuQuotaOverride: 2, memoryBytesOverride: highRam })).toBe(1);
+            // CPU 3 - 4: allocates 2 workers
+            expect(calculateWorkerCount(targets, { cpuQuotaOverride: 3, memoryBytesOverride: highRam })).toBe(2);
+            expect(calculateWorkerCount(targets, { cpuQuotaOverride: 4, memoryBytesOverride: highRam })).toBe(2);
+            // CPU > 4: allocates (cpu - 2) capped at maxWorkersCap (default 6)
+            expect(calculateWorkerCount(targets, { cpuQuotaOverride: 6, memoryBytesOverride: highRam })).toBe(4);
+            expect(calculateWorkerCount(targets, { cpuQuotaOverride: 8, memoryBytesOverride: highRam })).toBe(6);
+            expect(calculateWorkerCount(targets, { cpuQuotaOverride: 64, memoryBytesOverride: highRam })).toBe(6);
+        });
+        it('enforces memory-aware guard to prevent OOM kills during browser automation', () => {
+            const targets = Array.from({ length: 10 }, () => 'spec.ts');
+            const highCpu = 16;
+            // 500 MB RAM budget -> allows at most 1 worker (~600MB budget per browser)
+            expect(calculateWorkerCount(targets, { cpuQuotaOverride: highCpu, memoryBytesOverride: 500 * 1024 * 1024 })).toBe(1);
+            // 1.5 GB RAM budget -> allows 2 workers
+            expect(calculateWorkerCount(targets, { cpuQuotaOverride: highCpu, memoryBytesOverride: 1500 * 1024 * 1024 })).toBe(2);
+            // 2.5 GB RAM budget -> allows 4 workers
+            expect(calculateWorkerCount(targets, { cpuQuotaOverride: highCpu, memoryBytesOverride: 2500 * 1024 * 1024 })).toBe(4);
+        });
+        it('groups specs by suite directory in nested array format when mode is "suite"', () => {
+            const specs = [
+                'specs/Auth/TC-001/web.test.ts',
+                'specs/Auth/TC-002/web.test.ts',
+                'specs/Cart/TC-010/web.test.ts',
+                'specs/Cart/TC-011/web.test.ts',
+            ];
+            const grouped = groupSpecs(specs, 'suite');
+            expect(grouped.length).toBe(2);
+            expect(grouped[0]).toEqual(['specs/Auth/TC-001/web.test.ts', 'specs/Auth/TC-002/web.test.ts']);
+            expect(grouped[1]).toEqual(['specs/Cart/TC-010/web.test.ts', 'specs/Cart/TC-011/web.test.ts']);
+        });
+        it('flattens specs when mode is "testcase"', () => {
+            const specs = ['specs/Auth/TC-001/web.test.ts', 'specs/Auth/TC-002/web.test.ts', 'specs/Cart/TC-010/web.test.ts'];
+            const flat = groupSpecs(specs, 'testcase');
+            expect(flat).toEqual(specs);
+        });
+    });
+});

package/dist/lifecycle/hook-discovery.d.ts

@@ -0,0 +1,24 @@
+import { PlatformTarget } from '../generator/type-generator.js';
+export type HookEntry = string | (() => Promise<void> | void);
+export interface DiscoveredSuiteHooks {
+    before: string[];
+    beforeEach: string[];
+    afterEach: string[];
+    after: string[];
+}
+export interface DiscoveredGlobalHooks {
+    before: string[];
+    after: string[];
+}
+export interface SuiteHooks {
+    before: HookEntry[];
+    beforeEach: HookEntry[];
+    afterEach: HookEntry[];
+    after: HookEntry[];
+}
+export interface GlobalHooks {
+    before: HookEntry[];
+    after: HookEntry[];
+}
+export declare function discoverGlobalHooks(cwd: string, platform?: PlatformTarget): DiscoveredGlobalHooks;
+export declare function discoverSuiteHooks(suiteDir: string, platform?: PlatformTarget): DiscoveredSuiteHooks;

package/dist/lifecycle/hook-discovery.js

@@ -0,0 +1,60 @@
+import fs from 'fs';
+import path from 'path';
+import { PLATFORM_HIERARCHY } from '../generator/type-generator.js';
+function resolveHookFilesForType(dir, platform = 'web') {
+    if (!fs.existsSync(dir))
+        return [];
+    const entries = fs.readdirSync(dir, { withFileTypes: true });
+    const hierarchy = PLATFORM_HIERARCHY[platform] || ['common'];
+    const matched = [];
+    // Group files by base name if applicable or collect directly
+    for (const entry of entries) {
+        if (!entry.isFile() || !entry.name.endsWith('.hook.ts'))
+            continue;
+        const parts = entry.name.split('.');
+        // Formats:
+        // 1. web.hook.ts -> parts = ['web', 'hook', 'ts']
+        // 2. auth.web.hook.ts -> parts = ['auth', 'web', 'hook', 'ts']
+        // 3. auth.hook.ts -> parts = ['auth', 'hook', 'ts']
+        let filePlatform = 'common';
+        if (parts.length === 3) {
+            filePlatform = parts[0];
+        }
+        else if (parts.length >= 4) {
+            filePlatform = parts[parts.length - 3];
+        }
+        if (hierarchy.includes(filePlatform) || filePlatform === 'common') {
+            matched.push(path.join(dir, entry.name));
+        }
+    }
+    // Sort by hierarchy priority
+    matched.sort((a, b) => {
+        const getPriority = (filePath) => {
+            const base = path.basename(filePath);
+            for (let i = 0; i < hierarchy.length; i++) {
+                if (base.includes(`.${hierarchy[i]}.`) || base.startsWith(`${hierarchy[i]}.`)) {
+                    return i;
+                }
+            }
+            return hierarchy.length;
+        };
+        return getPriority(a) - getPriority(b);
+    });
+    return matched;
+}
+export function discoverGlobalHooks(cwd, platform = 'web') {
+    const globalHooksDir = path.join(cwd, 'global-hooks');
+    return {
+        before: resolveHookFilesForType(path.join(globalHooksDir, 'before'), platform),
+        after: resolveHookFilesForType(path.join(globalHooksDir, 'after'), platform),
+    };
+}
+export function discoverSuiteHooks(suiteDir, platform = 'web') {
+    const hooksDir = path.join(suiteDir, 'hooks');
+    return {
+        before: resolveHookFilesForType(path.join(hooksDir, 'before'), platform),
+        beforeEach: resolveHookFilesForType(path.join(hooksDir, 'beforeEach'), platform),
+        afterEach: resolveHookFilesForType(path.join(hooksDir, 'afterEach'), platform),
+        after: resolveHookFilesForType(path.join(hooksDir, 'after'), platform),
+    };
+}

package/dist/lifecycle/hook-dispatcher.d.ts

@@ -0,0 +1,34 @@
+import { SuiteHooks, GlobalHooks } from './hook-discovery.js';
+export type TestCaseStatus = 'PASSED' | 'FAILED' | 'SKIPPED' | 'ERROR';
+export interface TestCaseResult {
+    id: string;
+    title: string;
+    status: TestCaseStatus;
+    error?: Error;
+    durationMs: number;
+}
+export interface SuiteExecutionResult {
+    suiteName: string;
+    results: TestCaseResult[];
+    status: 'PASSED' | 'FAILED' | 'ERROR';
+    error?: Error;
+}
+export type HookFn = () => Promise<void> | void;
+export declare class HookExecutionError extends Error {
+    phase: 'before' | 'beforeEach' | 'afterEach' | 'after' | 'globalBefore' | 'globalAfter';
+    originalError: any;
+    constructor(phase: 'before' | 'beforeEach' | 'afterEach' | 'after' | 'globalBefore' | 'globalAfter', originalError: any);
+}
+export declare function runHook(hookPathOrFn: string | HookFn, timeoutMs?: number): Promise<void>;
+export declare class LifecycleDispatcher {
+    mode: 'single' | 'global';
+    globalHooks: GlobalHooks;
+    constructor(mode?: 'single' | 'global', globalHooks?: GlobalHooks);
+    runGlobalBefore(): Promise<void>;
+    runGlobalAfter(): Promise<void>;
+    executeSuite(suiteName: string, suiteHooks: SuiteHooks, testCases: Array<{
+        id: string;
+        title: string;
+        fn: () => Promise<void>;
+    }>): Promise<SuiteExecutionResult>;
+}