@http-forge/core 0.1.0 → 0.2.1

package/dist/script/module-loader.d.ts

@@ -0,0 +1,115 @@
+/**
+ * Module Loader Implementation
+ *
+ * Single Responsibility: Load custom modules from workspace for script execution
+ *
+ * Provides consistent module loading behavior across all packages:
+ * - VS Code Extension
+ * - @http-forge/standalone
+ * - @http-forge/playwright
+ *
+ * All packages provide module paths, resulting in identical behavior.
+ *
+ * SECURITY NOTE: This loader is designed to work within Node.js vm sandbox.
+ * The returned require function should ONLY be exposed within the vm context.
+ */
+/**
+ * Module loader configuration options
+ */
+export interface ModuleLoaderOptions {
+    /** Whether to allow loading custom modules (default: true) */
+    allowCustomModules?: boolean;
+    /** Maximum module resolution depth (prevents circular dependencies) */
+    maxResolveDepth?: number;
+    /** Output channel for logging (VS Code environment) */
+    outputChannel?: {
+        appendLine: (message: string) => void;
+    };
+}
+/**
+ * Create a lightweight moment.js replacement (when not available)
+ */
+export declare function createMomentShim(): any;
+/**
+ * Create a lightweight lodash replacement (when not available)
+ */
+export declare function createLodashShim(): any;
+/**
+ * ModuleLoader handles loading custom modules from the workspace's modules/ folder.
+ *
+ * Directory structure:
+ * ```
+ * http-forge-assets/modules/            ← modulePath
+ * ├── package.json                      ← Declares dependencies
+ * ├── global-setup.js                   ← Global exports injected into sandbox
+ * └── auth-helpers.js                   ← User's custom code
+ * ```
+ *
+ * SECURITY IMPORTANT:
+ * 1. The require function returned by createRequireFunction() should ONLY be used inside vm sandbox
+ * 2. Built-in modules are carefully whitelisted - review before adding new ones
+ * 3. Relative paths are restricted to modules/ directory subtree
+ */
+export declare class ModuleLoader {
+    private availableModules;
+    private customModulesRequire?;
+    private globalSetupExports?;
+    private options;
+    private modulesPath;
+    private moduleCache;
+    private resolveStack;
+    /**
+     * Built-in modules with fallback loading support
+     */
+    private readonly builtinModules;
+    /**
+     * Create a new ModuleLoader
+     *
+     * @param modulePaths - Array of paths to modules directories. First valid path is used.
+     * @param options - Configuration options
+     */
+    constructor(modulePaths?: string[], options?: ModuleLoaderOptions);
+    /**
+     * Unified fallback module loader
+     */
+    private loadOptionalModule;
+    private logModuleWarning;
+    private getModuleInstallInstructions;
+    /**
+     * Initialize modules from the resolved path
+     * @returns true if successfully initialized
+     */
+    private initializeModules;
+    private loadAvailableModules;
+    private loadGlobalSetup;
+    /**
+     * Create require function for use in VM sandbox
+     *
+     * Resolution order:
+     * 1. Built-in modules (lodash, moment, crypto, etc.)
+     * 2. Relative paths (./helpers, ../utils) - restricted to modules/ directory
+     * 3. Workspace dependencies from modules/package.json
+     */
+    createRequireFunction(): (moduleName: string) => any;
+    private getModuleSuggestions;
+    private cacheModule;
+    /** Get global setup exports for sandbox injection */
+    getGlobalSetupExports(): Record<string, any> | undefined;
+    /** Check if custom modules are available */
+    hasCustomModules(): boolean;
+    /** Get list of available module names (built-ins + workspace) */
+    getAvailableModules(): string[];
+    /** Clear module cache */
+    clearCache(): void;
+    /** Get cache statistics */
+    getCacheStats(): {
+        size: number;
+        hits: number;
+    };
+    private logDebug;
+    private logError;
+}
+/**
+ * Factory function: create a pre-configured ModuleLoader instance
+ */
+export declare function createModuleLoader(modulePaths: string[], options?: ModuleLoaderOptions): ModuleLoader;

package/dist/script/request-script-session.d.ts

@@ -0,0 +1,73 @@
+/**
+ * Request Script Session
+ *
+ * Single Responsibility: Manage shared VM context between pre-request and post-response scripts
+ *
+ * This class creates a single VM sandbox that persists across both script phases,
+ * allowing JavaScript variables declared in pre-request to be accessible in post-response.
+ * This matches Postman's behavior for per-request script execution.
+ */
+import * as vm from 'vm';
+import { CommonScriptContext, IRequestScriptSession, PostResponseScriptResult, PreRequestScriptContext, PreRequestScriptResult, ResponseContext } from './interfaces';
+/**
+ * Dependencies injected from ScriptExecutor
+ * Interface Segregation: Only the methods needed by the session
+ */
+export interface SessionDependencies {
+    createVM: (ctx: any, scriptConsole: any) => vm.Context;
+    createCommonContext: (context: CommonScriptContext, eventName: 'prerequest' | 'test') => any;
+}
+/**
+ * Request Script Session Implementation
+ *
+ * Manages a shared VM context for executing pre-request and post-response scripts.
+ * Variables declared in pre-request are accessible in post-response.
+ */
+export declare class RequestScriptSession implements IRequestScriptSession {
+    private readonly deps;
+    private readonly initialContext;
+    private vmContext;
+    private ctx;
+    private modifiedRequest;
+    private assertions;
+    private consoleMessages;
+    private _variables;
+    private _collectionVariables;
+    private _globals;
+    private _sessionVariables;
+    private _environmentVariables;
+    private _nextRequest;
+    private _skipRequest;
+    private _visualizerData;
+    constructor(deps: SessionDependencies, initialContext: PreRequestScriptContext);
+    /**
+     * Initialize the shared VM context
+     */
+    private initializeSession;
+    /**
+     * Create shared context object that will be augmented with response data later
+     */
+    private createSharedContext;
+    /**
+     * Create request object with getters/setters for modification tracking
+     * Maps HTTP Forge body types to Postman modes for script API compatibility
+     */
+    private createRequestObject;
+    /**
+     * Execute pre-request scripts in the shared session
+     */
+    executePreRequest(script: string | string[]): Promise<PreRequestScriptResult>;
+    /**
+     * Execute post-response scripts in the shared session
+     * The response data is injected into the existing VM context
+     */
+    executePostResponse(script: string | string[], responseContext: ResponseContext): Promise<PostResponseScriptResult>;
+    /**
+     * Compare two RequestBody objects for equality
+     */
+    private bodiesEqual;
+    /**
+     * Clean up the session resources
+     */
+    dispose(): void;
+}

package/dist/script/script-executor.d.ts

@@ -0,0 +1,60 @@
+/**
+ * Script Executor
+ *
+ * Single Responsibility: Orchestrate script execution and VM configuration
+ * Open/Closed: Uses composition to delegate to specialized modules
+ * Dependency Inversion: Depends on abstractions (IRequestScriptSession, IScriptExecutor)
+ *
+ * This is the main entry point for script execution.
+ * It configures the VM sandbox and delegates session management to RequestScriptSession.
+ */
+import { IHttpRequestService } from '../http/interfaces';
+import { IRequestScriptSession, IScriptExecutor, PreRequestScriptContext } from './interfaces';
+/**
+ * Script Executor Implementation
+ *
+ * Orchestrates script execution by:
+ * - Configuring VM sandbox with built-in libraries
+ * - Creating common context for variable scopes
+ * - Delegating session management to RequestScriptSession
+ */
+export declare class ScriptExecutor implements IScriptExecutor {
+    private readonly httpService?;
+    private readonly moduleLoader;
+    constructor(httpService?: IHttpRequestService | undefined, modulePaths?: string[]);
+    /**
+     * Create a request execution session
+     * Factory method implementing IScriptExecutor
+     */
+    createRequestSession(context: PreRequestScriptContext): IRequestScriptSession;
+    /**
+     * Create VM context with sandbox configuration
+     * Returns a context object that can be used with vm.runInContext()
+     */
+    private createVM;
+    /**
+     * Create common context object for variable scopes
+     * Used by RequestScriptSession for pre-request and test scripts
+     */
+    private createCommonContext;
+    /**
+     * Create a basic variable scope with get/set/has/unset/clear/toObject
+     */
+    private createVariableScope;
+    /**
+     * Create merged variable scope (Postman-style cascading lookup)
+     */
+    private createMergedVariableScope;
+    /**
+     * Create environment variable scope with change callbacks
+     */
+    private createEnvironmentScope;
+    /**
+     * Create session variable scope with change callbacks
+     */
+    private createSessionScope;
+    /**
+     * Create sendRequest function using httpService
+     */
+    private createSendRequest;
+}

package/dist/script/script-factories.d.ts

@@ -0,0 +1,94 @@
+/**
+ * Script Factories
+ *
+ * Single Responsibility: Create objects used in script execution contexts
+ * Open/Closed: New factory methods can be added without modifying existing ones
+ */
+import { ResponseContext } from './interfaces';
+/**
+ * Response object interface for script context
+ */
+export interface ScriptResponse {
+    status: number;
+    code: number;
+    statusText: string;
+    headers: Record<string, string>;
+    body: any;
+    cookies: Record<string, string>;
+    responseTime?: number;
+    responseSize?: number;
+    getHeader(name: string): string | undefined;
+    getCookie(name: string): string | undefined;
+    reason(): string;
+    json(): any;
+    text(): string;
+    cookie(name: string): string | undefined;
+    hasCookie(name: string): boolean;
+    to: ResponseAssertions;
+}
+/**
+ * Response assertion helpers (Postman-style)
+ * Note: be.ok/error/etc. are getters that execute assertions on property access
+ */
+export interface ResponseAssertions {
+    have: {
+        status(expectedStatus: number): void;
+        header(headerName: string, expectedValue?: string): void;
+        body(expectedBody?: string): void;
+        jsonBody(expectedJson?: any): void;
+    };
+    be: {
+        readonly ok: any;
+        readonly success: any;
+        readonly error: any;
+        readonly clientError: any;
+        readonly serverError: any;
+    };
+}
+/**
+ * Create response object with helper methods for script context
+ * Provides Postman-compatible response API
+ */
+export declare function createResponseObject(response: ResponseContext): ScriptResponse;
+/**
+ * Expect chain interface for Chai-style assertions
+ */
+export interface ExpectChain {
+    _value: any;
+    _negated: boolean;
+    _deep: boolean;
+    not: ExpectChain;
+    to: ExpectChain;
+    be: ExpectChain;
+    have: ExpectChain;
+    deep: ExpectChain;
+    equal(expected: any): ExpectChain;
+    eql(expected: any): ExpectChain;
+    property(name: string, value?: any): ExpectChain;
+    ok: ExpectChain;
+    exist: ExpectChain;
+    include(value: any): ExpectChain;
+    oneOf(values: any[]): ExpectChain;
+    match(pattern: RegExp): ExpectChain;
+    above(num: number): ExpectChain;
+    below(num: number): ExpectChain;
+    greaterThan(num: number): ExpectChain;
+    lessThan(num: number): ExpectChain;
+    within(start: number, end: number): ExpectChain;
+    a(type: string): ExpectChain;
+    an(type: string): ExpectChain;
+    true: ExpectChain;
+    false: ExpectChain;
+    null: ExpectChain;
+    undefined: ExpectChain;
+    empty: ExpectChain;
+    length(len: number): ExpectChain;
+    lengthOf(len: number): ExpectChain;
+    members(arr: any[]): ExpectChain;
+    keys(...args: any[]): ExpectChain;
+    string(substr: string): ExpectChain;
+}
+/**
+ * Create Chai-style expect chain for assertions
+ */
+export declare function createExpectChain(value: any): ExpectChain;

package/dist/script/script-utils.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Script Utilities
+ *
+ * Single Responsibility: Pure utility functions for script execution
+ * These are stateless helper functions with no side effects
+ */
+import { TestAssertion } from '../types/types';
+/**
+ * Console message structure for script output
+ */
+export interface ConsoleMessage {
+    level: 'log' | 'info' | 'warn' | 'error';
+    args: any[];
+}
+/**
+ * Concatenate multiple scripts into one with clear separators
+ * Enables variables defined in earlier scripts to be accessible in later scripts
+ */
+export declare function concatenateScripts(scripts: string | string[]): string;
+/**
+ * Check if an object has changed from its original value
+ * Uses JSON serialization for deep comparison
+ */
+export declare function hasChanged(current: any, original: any): boolean;
+/**
+ * Format console messages into output strings
+ */
+export declare function formatConsoleOutput(messages: ConsoleMessage[]): string[];
+/**
+ * Create a script console that captures output
+ */
+export declare function createScriptConsole(messages: ConsoleMessage[]): Console;
+/**
+ * Create a test function that records assertions
+ * Supports both sync and async test functions (Postman-compatible)
+ */
+export declare function createTestFunction(assertions: TestAssertion[]): any;
+/**
+ * Normalize HTTP headers to Record<string, string>
+ * Converts multi-value headers (string[]) to comma-separated strings
+ */
+export declare function normalizeHeaders(headers: Record<string, string | string[]>): Record<string, string>;

package/dist/test-suite/index.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Test Suite Services
+ */
+export * from './interfaces';
+export * from './result-storage';
+export { ResultStorageService } from './result-storage-service';
+export { StatisticsService } from './statistics-service';
+export { TestSuiteService } from './test-suite-service';
+export { TestSuiteStore } from './test-suite-store';
+export type { ITestSuiteStore, SuiteRequestEntry } from './test-suite-store';

package/dist/test-suite/interfaces.d.ts

@@ -0,0 +1,164 @@
+/**
+ * Test Suite Interfaces
+ *
+ * Defines data structures for Test Suite functionality
+ */
+/**
+ * Request reference within a Test Suite
+ * References a request from a Collection (not a copy)
+ */
+export interface SuiteRequest {
+    /** Collection ID where the request lives */
+    collectionId: string;
+    /** Collection name for display purposes */
+    collectionName: string;
+    /** Request ID within the collection */
+    requestId: string;
+    /** Cached display info (avoid querying collection each time) */
+    name: string;
+    method: string;
+    folderPath: string;
+    /** Whether this request is enabled for execution */
+    enabled?: boolean;
+}
+/**
+ * Test Suite run configuration
+ */
+export interface SuiteConfig {
+    /** Number of iterations to run */
+    iterations: number;
+    /** Delay between requests in milliseconds */
+    delayBetweenRequests: number;
+    /** Stop execution on first error */
+    stopOnError: boolean;
+    /** Read variables from shared session */
+    readFromSharedSession: boolean;
+    /** Write variables to shared session */
+    writeToSharedSession: boolean;
+    /** Data file path for variable injection */
+    dataFilePath?: string;
+}
+/**
+ * Test Suite definition
+ */
+export interface TestSuite {
+    /** Unique identifier */
+    id: string;
+    /** Suite name */
+    name: string;
+    /** Optional description */
+    description?: string;
+    /** Ordered list of request references */
+    requests: SuiteRequest[];
+    /** Run configuration */
+    config: SuiteConfig;
+    /** Whether this is a temporary suite (not saved) */
+    isTemporary?: boolean;
+    /** Creation timestamp */
+    createdAt: number;
+    /** Last update timestamp */
+    updatedAt: number;
+}
+/**
+ * Per-request statistics
+ */
+export interface RequestStatistics {
+    /** Request name */
+    name: string;
+    /** Number of executions */
+    count: number;
+    /** Number of passed executions */
+    passed: number;
+    /** Number of failed executions */
+    failed: number;
+    /** Number of skipped executions */
+    skipped: number;
+    /** Minimum response time (ms) */
+    min: number;
+    /** Maximum response time (ms) */
+    max: number;
+    /** Average response time (ms) */
+    avg: number;
+    /** 50th percentile (median) */
+    p50: number;
+    /** 90th percentile */
+    p90: number;
+    /** 95th percentile */
+    p95: number;
+    /** 99th percentile */
+    p99: number;
+    /** Raw duration data for recalculation */
+    durations: number[];
+}
+/**
+ * Run statistics summary
+ */
+export interface RunSummary {
+    /** Total requests executed */
+    totalRequests: number;
+    /** Number of passed requests */
+    passed: number;
+    /** Number of failed requests */
+    failed: number;
+    /** Number of skipped requests */
+    skipped: number;
+    /** Pass rate percentage */
+    passRate: number;
+    /** Total duration in milliseconds */
+    duration: number;
+    /** Whether run is still in progress */
+    isRunning: boolean;
+}
+/**
+ * Error summary entry
+ */
+export interface ErrorSummary {
+    /** Error message or status */
+    message: string;
+    /** Number of occurrences */
+    count: number;
+}
+/**
+ * Complete run statistics
+ */
+export interface RunStatistics {
+    /** Summary statistics */
+    summary: RunSummary;
+    /** Statistics grouped by request name */
+    byRequest: Map<string, RequestStatistics>;
+    /** Overall statistics across all requests */
+    overall: RequestStatistics;
+    /** Error summary */
+    errors: ErrorSummary[];
+}
+/**
+ * Test Suite Service Interface
+ */
+export interface ITestSuiteService {
+    createSuite(name: string, requests?: SuiteRequest[]): Promise<TestSuite>;
+    getSuite(id: string): Promise<TestSuite | undefined>;
+    getAllSuites(): Promise<TestSuite[]>;
+    updateSuite(suite: TestSuite): Promise<void>;
+    deleteSuite(id: string): Promise<boolean>;
+    createTempSuiteFromCollection(collectionId: string): Promise<TestSuite | undefined>;
+    saveTempSuite(suite: TestSuite, name: string): Promise<TestSuite>;
+}
+/**
+ * Statistics Service Interface
+ */
+export interface IStatisticsService {
+    /** Add a result and update statistics */
+    addResult(requestName: string, duration: number, passed: boolean, skipped: boolean, error?: string): void;
+    /** Get current statistics */
+    getStatistics(): RunStatistics;
+    /** Reset statistics for a new run */
+    reset(): void;
+    /** Mark run as complete */
+    complete(): void;
+    /** Set start time for duration tracking */
+    start(): void;
+}
+/**
+ * Default suite configuration
+ */
+export declare const DEFAULT_SUITE_CONFIG: SuiteConfig;

package/dist/test-suite/result-storage-service.d.ts

@@ -0,0 +1,70 @@
+/**
+ * Result Storage Service for Test Suite
+ *
+ * Architecture (JMeter-inspired):
+ * - Append-only index pages for fast writes
+ * - Individual JSON files for full details
+ * - Aggregated stats in memory (constant size)
+ * - On-demand result loading
+ */
+import { IConfigService } from '../config';
+import { ExecutionResult } from '../types/types';
+import { FullResultDetails, IndexPage, IResultStorageService, RecentError, RequestStats, ResultSummary, RunConfig, RunManifest, RunStats } from './result-storage';
+/**
+ * File-based Result Storage Service for Test Suite
+ */
+export declare class ResultStorageService implements IResultStorageService {
+    private configService;
+    private basePath;
+    private currentRunPath;
+    private currentRunId;
+    private currentSuiteId;
+    private currentManifest;
+    private currentIndexPage;
+    private currentPageNumber;
+    private readonly indexPageSize;
+    private recentErrors;
+    private readonly recentErrorsLimit;
+    private resultIndex;
+    private requestDurations;
+    constructor(configService: IConfigService);
+    /**
+     * Get the base path for result storage
+     */
+    getBasePath(): string;
+    /**
+     * Initialize a new run
+     */
+    initializeRun(suiteId: string, suiteName: string, environment: string, config: RunConfig): Promise<string>;
+    /**
+     * Save a request result
+     * Returns lightweight summary for UI
+     */
+    saveResult(iteration: number, result: ExecutionResult): Promise<ResultSummary>;
+    /**
+     * Finalize run
+     */
+    finalizeRun(status?: 'completed' | 'aborted' | 'error'): Promise<void>;
+    getCurrentStats(): {
+        stats: RunStats;
+        requestStats: Record<string, RequestStats>;
+        recentErrors: RecentError[];
+    } | null;
+    getCurrentRunId(): string | null;
+    getCurrentSuiteId(): string | null;
+    getResultDetails(suiteId: string, runId: string, resultFile: string): Promise<FullResultDetails>;
+    getIndexPage(suiteId: string, runId: string, page: number): Promise<IndexPage>;
+    getManifest(suiteId: string, runId: string): Promise<RunManifest>;
+    listRuns(suiteId: string): Promise<RunManifest[]>;
+    listSuites(): Promise<string[]>;
+    deleteRun(suiteId: string, runId: string): Promise<void>;
+    cleanupOldRuns(): Promise<{
+        deleted: number;
+        freed: number;
+    }>;
+    private generateRunId;
+    private saveManifest;
+    private writeCurrentIndexPage;
+    private updateStats;
+    private getDirectorySize;
+}