@zintrust/core 0.1.0

package/src/cli/utils/DistPackager.js

@@ -0,0 +1,94 @@
+import { Logger } from '../../config/logger';
+import { ErrorFactory } from '../../exceptions/ZintrustError';
+import fs from '../../node-singletons/fs';
+import * as path from '../../node-singletons/path';
+const readRootPackageJson = (rootPath) => {
+    const rootPackageJsonPath = path.join(rootPath, 'package.json');
+    if (!fs.existsSync(rootPackageJsonPath)) {
+        throw ErrorFactory.createConfigError(`Missing package.json at: ${rootPackageJsonPath}`);
+    }
+    try {
+        const raw = fs.readFileSync(rootPackageJsonPath, 'utf8');
+        return JSON.parse(raw);
+    }
+    catch (error) {
+        throw ErrorFactory.createTryCatchError('Failed to read root package.json', error);
+    }
+};
+const coerceDependencies = (value) => {
+    if (typeof value !== 'object' || value === null)
+        return {};
+    return value;
+};
+const buildDistPackageJson = (rootPkg) => {
+    const name = typeof rootPkg.name === 'string' && rootPkg.name.trim() !== ''
+        ? rootPkg.name
+        : '@zintrust/core';
+    const version = typeof rootPkg.version === 'string' && rootPkg.version.trim() !== ''
+        ? rootPkg.version
+        : '0.0.0';
+    return {
+        name,
+        version,
+        private: true,
+        type: 'module',
+        main: './index.js',
+        types: './index.d.ts',
+        bin: {
+            zintrust: './bin/zintrust.js',
+            zin: './bin/zin.js',
+            z: './bin/z.js',
+            zt: './bin/zt.js',
+        },
+        exports: {
+            '.': {
+                types: './index.d.ts',
+                default: './index.js',
+            },
+        },
+        dependencies: coerceDependencies(rootPkg.dependencies),
+    };
+};
+const writeDistEntrypoints = (distPath) => {
+    const distIndexJsPath = path.join(distPath, 'index.js');
+    const distIndexDtsPath = path.join(distPath, 'index.d.ts');
+    fs.writeFileSync(distIndexJsPath, "export * from './src/index.js';\n");
+    fs.writeFileSync(distIndexDtsPath, "export * from './src/index';\n");
+};
+const writeDistPackageJson = (distPath, pkg) => {
+    const distPackageJsonPath = path.join(distPath, 'package.json');
+    fs.writeFileSync(distPackageJsonPath, JSON.stringify(pkg, null, 2) + '\n');
+};
+const warnIfMissingDistArtifacts = (distPath) => {
+    const expected = [
+        path.join(distPath, 'src', 'index.js'),
+        path.join(distPath, 'bin', 'zintrust.js'),
+        path.join(distPath, 'bin', 'zin.js'),
+    ];
+    for (const candidate of expected) {
+        if (!fs.existsSync(candidate)) {
+            Logger.warn(`Dist artifact missing (did you run build?): ${candidate}`);
+        }
+    }
+    const docsRoot = path.join(distPath, 'public');
+    if (!fs.existsSync(docsRoot)) {
+        Logger.warn(`Docs public root missing at ${docsRoot} (expected dist/public)`);
+    }
+};
+export const DistPackager = Object.freeze({
+    /**
+     * Creates minimal metadata so `dist/` can be installed via `file:/.../dist`.
+     * This is intended for local dev/simulate apps, not publishing.
+     */
+    prepare(distPath, rootPath = process.cwd()) {
+        if (!fs.existsSync(distPath)) {
+            throw ErrorFactory.createConfigError(`Missing dist output at: ${distPath}. Run 'npm run build' first.`);
+        }
+        const rootPkg = readRootPackageJson(rootPath);
+        const distPkg = buildDistPackageJson(rootPkg);
+        writeDistPackageJson(distPath, distPkg);
+        writeDistEntrypoints(distPath);
+        warnIfMissingDistArtifacts(distPath);
+        Logger.info(`✅ Prepared dist package metadata at: ${path.join(distPath, 'package.json')}`);
+    },
+});

package/src/cli/utils/EnvFileLoader.d.ts

@@ -0,0 +1,21 @@
+type LoadOptions = {
+    cwd?: string;
+    overrideExisting?: boolean;
+};
+type LoadState = {
+    loadedFiles: string[];
+    mode?: string;
+};
+type CliOverrides = {
+    nodeEnv?: 'development' | 'production' | 'testing';
+    port?: number;
+    runtime?: string;
+};
+export declare const EnvFileLoader: Readonly<{
+    load: (options?: LoadOptions) => LoadState;
+    ensureLoaded: () => LoadState;
+    applyCliOverrides: (overrides: CliOverrides) => void;
+    getState: () => LoadState;
+}>;
+export {};
+//# sourceMappingURL=EnvFileLoader.d.ts.map

package/src/cli/utils/EnvFileLoader.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"EnvFileLoader.d.ts","sourceRoot":"","sources":["../../../../src/cli/utils/EnvFileLoader.ts"],"names":[],"mappings":"AA2GA,KAAK,WAAW,GAAG;IACjB,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,gBAAgB,CAAC,EAAE,OAAO,CAAC;CAC5B,CAAC;AAEF,KAAK,SAAS,GAAG;IACf,WAAW,EAAE,MAAM,EAAE,CAAC;IACtB,IAAI,CAAC,EAAE,MAAM,CAAC;CACf,CAAC;AAEF,KAAK,YAAY,GAAG;IAClB,OAAO,CAAC,EAAE,aAAa,GAAG,YAAY,GAAG,SAAS,CAAC;IACnD,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB,CAAC;AAsFF,eAAO,MAAM,aAAa;qBA7DH,WAAW,KAAQ,SAAS;wBA8B1B,SAAS;mCAEI,YAAY,KAAG,IAAI;oBA2BpC,SAAS;EAO5B,CAAC"}

package/src/cli/utils/EnvFileLoader.js

@@ -0,0 +1,166 @@
+import { existsSync, readFileSync } from '../../node-singletons/fs';
+import { join } from '../../node-singletons/path';
+const normalizeAppMode = (value) => {
+    const normalized = value.trim().toLowerCase();
+    if (normalized === 'production' || normalized === 'pro' || normalized === 'prod')
+        return 'production';
+    if (normalized === 'dev' || normalized === 'development')
+        return 'dev';
+    // Per spec: any other value is treated as development.
+    return 'dev';
+};
+const stripInlineComment = (value) => {
+    let inSingle = false;
+    let inDouble = false;
+    for (let i = 0; i < value.length; i += 1) {
+        const ch = value[i];
+        if (ch === "'" && !inDouble)
+            inSingle = !inSingle;
+        if (ch === '"' && !inSingle)
+            inDouble = !inDouble;
+        if (!inSingle && !inDouble && ch === '#') {
+            const prev = value[i - 1];
+            if (prev === undefined || prev === ' ' || prev === '\t') {
+                return value.slice(0, i).trimEnd();
+            }
+        }
+    }
+    return value;
+};
+const unquote = (value) => {
+    const trimmed = value.trim();
+    if (trimmed.length >= 2) {
+        const first = trimmed[0];
+        const last = trimmed.at(-1);
+        if ((first === '"' && last === '"') || (first === "'" && last === "'")) {
+            return trimmed.slice(1, -1);
+        }
+    }
+    return trimmed;
+};
+const parseEnvFile = (raw) => {
+    const result = {};
+    const lines = raw.split(/\r?\n/);
+    for (const line of lines) {
+        const trimmed = line.trim();
+        if (trimmed === '' || trimmed.startsWith('#'))
+            continue;
+        const withoutExport = trimmed.startsWith('export ') ? trimmed.slice('export '.length) : trimmed;
+        const eq = withoutExport.indexOf('=');
+        if (eq <= 0)
+            continue;
+        const key = withoutExport.slice(0, eq).trim();
+        if (key === '')
+            continue;
+        const rhs = withoutExport.slice(eq + 1);
+        const withoutComment = stripInlineComment(rhs);
+        const value = unquote(withoutComment);
+        result[key] = value;
+    }
+    return result;
+};
+const applyToProcessEnv = (values, overrideExisting) => {
+    for (const [key, value] of Object.entries(values)) {
+        if (!overrideExisting && typeof process.env[key] === 'string')
+            continue;
+        process.env[key] = value;
+    }
+    // Compatibility helpers
+    if (typeof process.env['PORT'] !== 'string' && typeof process.env['APP_PORT'] === 'string') {
+        process.env['PORT'] = process.env['APP_PORT'];
+    }
+    if (typeof process.env['NODE_ENV'] !== 'string' && typeof process.env['APP_MODE'] === 'string') {
+        const mode = normalizeAppMode(process.env['APP_MODE']);
+        process.env['NODE_ENV'] = mode === 'production' ? 'production' : 'development';
+    }
+};
+const readEnvFileIfExists = (cwd, filename) => {
+    const fullPath = join(cwd, filename);
+    if (!existsSync(fullPath))
+        return undefined;
+    const raw = readFileSync(fullPath, 'utf-8');
+    return parseEnvFile(raw);
+};
+const resolveAppMode = (cwd) => {
+    const existing = process.env['APP_MODE'];
+    if (typeof existing === 'string' && existing.trim() !== '')
+        return normalizeAppMode(existing);
+    const fromDotEnv = readEnvFileIfExists(cwd, '.env');
+    const value = fromDotEnv?.['APP_MODE'];
+    if (typeof value === 'string' && value.trim() !== '')
+        return normalizeAppMode(value);
+    return undefined;
+};
+const filesLoader = (cwd, mode) => {
+    const files = [];
+    if (existsSync(join(cwd, '.env')))
+        files.push('.env');
+    // Per your rule: production uses .env; dev uses .env.dev
+    if (mode !== undefined && mode !== '' && mode !== 'production') {
+        const modeFile = `.env.${mode}`;
+        if (existsSync(join(cwd, modeFile)))
+            files.push(modeFile);
+    }
+    const local = '.env.local';
+    if (existsSync(join(cwd, local)))
+        files.push(local);
+    if (mode !== undefined && mode !== '') {
+        const modeLocal = `.env.${mode}.local`;
+        if (existsSync(join(cwd, modeLocal)))
+            files.push(modeLocal);
+    }
+    return files;
+};
+let cached;
+const load = (options = {}) => {
+    if (cached !== undefined)
+        return cached;
+    const cwd = typeof options.cwd === 'string' && options.cwd !== '' ? options.cwd : process.cwd();
+    const overrideExisting = options.overrideExisting ?? true;
+    const mode = resolveAppMode(cwd);
+    const files = filesLoader(cwd, mode);
+    let baseApplied = false;
+    for (const file of files) {
+        const parsed = readEnvFileIfExists(cwd, file);
+        if (!parsed)
+            continue;
+        if (file === '.env') {
+            applyToProcessEnv(parsed, overrideExisting);
+            baseApplied = true;
+            continue;
+        }
+        // .env is primary: overlays only fill missing values and never override base.
+        applyToProcessEnv(parsed, baseApplied ? false : overrideExisting);
+    }
+    cached = { loadedFiles: files, mode };
+    return cached;
+};
+const ensureLoaded = () => load({ overrideExisting: true });
+const applyCliOverrides = (overrides) => {
+    // Ensure base env is loaded first.
+    ensureLoaded();
+    if (typeof overrides.runtime === 'string' && overrides.runtime.trim() !== '') {
+        process.env['RUNTIME'] = overrides.runtime.trim();
+    }
+    if (typeof overrides.nodeEnv === 'string') {
+        process.env['NODE_ENV'] = overrides.nodeEnv;
+    }
+    if (typeof overrides.port === 'number') {
+        process.env['PORT'] = String(overrides.port);
+        process.env['APP_PORT'] = String(overrides.port);
+    }
+    // Keep PORT/APP_PORT in sync if only one exists.
+    if (typeof process.env['PORT'] !== 'string' && typeof process.env['APP_PORT'] === 'string') {
+        process.env['PORT'] = process.env['APP_PORT'];
+    }
+    if (typeof process.env['APP_PORT'] !== 'string' && typeof process.env['PORT'] === 'string') {
+        process.env['APP_PORT'] = process.env['PORT'];
+    }
+};
+const getState = () => ensureLoaded();
+export const EnvFileLoader = Object.freeze({
+    load,
+    ensureLoaded,
+    applyCliOverrides,
+    getState,
+});

package/src/cli/utils/spawn.d.ts

@@ -0,0 +1,11 @@
+export interface SpawnAndWaitInput {
+    command: string;
+    args: string[];
+    cwd?: string;
+    env?: NodeJS.ProcessEnv;
+    forwardSignals?: boolean;
+}
+export declare const SpawnUtil: Readonly<{
+    spawnAndWait(input: SpawnAndWaitInput): Promise<number>;
+}>;
+//# sourceMappingURL=spawn.d.ts.map

package/src/cli/utils/spawn.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"spawn.d.ts","sourceRoot":"","sources":["../../../../src/cli/utils/spawn.ts"],"names":[],"mappings":"AAMA,MAAM,WAAW,iBAAiB;IAChC,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,MAAM,EAAE,CAAC;IACf,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,GAAG,CAAC,EAAE,MAAM,CAAC,UAAU,CAAC;IACxB,cAAc,CAAC,EAAE,OAAO,CAAC;CAC1B;AA8BD,eAAO,MAAM,SAAS;wBACM,iBAAiB,GAAG,OAAO,CAAC,MAAM,CAAC;EAwD7D,CAAC"}

package/src/cli/utils/spawn.js

@@ -0,0 +1,81 @@
+import { appConfig } from '../../config/app';
+import { ErrorFactory } from '../../exceptions/ZintrustError';
+import { spawn } from '../../node-singletons/child-process';
+import { existsSync } from '../../node-singletons/fs';
+import * as path from 'node:path';
+const getExitCode = (exitCode, signal) => {
+    if (typeof exitCode === 'number')
+        return exitCode;
+    if (signal === 'SIGINT' || signal === 'SIGTERM')
+        return 0;
+    return 1;
+};
+const resolveLocalBin = (command, cwd) => {
+    // If command is already a path, leave it alone.
+    if (command.includes('/') || command.includes('\\'))
+        return command;
+    const binDir = path.join(cwd, 'node_modules', '.bin');
+    const candidates = process.platform === 'win32'
+        ? [
+            path.join(binDir, `${command}.cmd`),
+            path.join(binDir, `${command}.exe`),
+            path.join(binDir, `${command}.bat`),
+            path.join(binDir, command),
+        ]
+        : [path.join(binDir, command)];
+    for (const candidate of candidates) {
+        if (existsSync(candidate))
+            return candidate;
+    }
+    return command;
+};
+export const SpawnUtil = Object.freeze({
+    async spawnAndWait(input) {
+        const cwd = input.cwd ?? process.cwd();
+        const resolvedCommand = resolveLocalBin(input.command, cwd);
+        const child = spawn(resolvedCommand, input.args, {
+            cwd,
+            env: input.env ?? appConfig.getSafeEnv(),
+            stdio: 'inherit',
+        });
+        const forwardSignals = input.forwardSignals !== false;
+        const forwardSignal = (signal) => {
+            try {
+                child.kill(signal);
+            }
+            catch (error) {
+                throw ErrorFactory.createTryCatchError('Failed to forward signal to child process', error);
+            }
+        };
+        const onSigint = () => forwardSignal('SIGINT');
+        const onSigterm = () => forwardSignal('SIGTERM');
+        if (forwardSignals) {
+            process.on('SIGINT', onSigint);
+            process.on('SIGTERM', onSigterm);
+        }
+        try {
+            const result = await new Promise((resolve, reject) => {
+                child.once('error', (error) => {
+                    reject(error);
+                });
+                child.once('close', (code, signal) => {
+                    resolve({ exitCode: code, signal });
+                });
+            });
+            return getExitCode(result.exitCode, result.signal);
+        }
+        catch (error) {
+            const code = error?.code;
+            if (code === 'ENOENT') {
+                throw ErrorFactory.createCliError(`Error: '${input.command}' not found on PATH.`);
+            }
+            throw ErrorFactory.createTryCatchError('Failed to spawn child process', error);
+        }
+        finally {
+            if (forwardSignals) {
+                process.off('SIGINT', onSigint);
+                process.off('SIGTERM', onSigterm);
+            }
+        }
+    },
+});

package/src/common/index.d.ts

@@ -0,0 +1,87 @@
+/**
+ * Common utilities - Sealed namespace for immutability
+ */
+export declare const CommonUtils: Readonly<{
+    /**
+     * Resolve npm executable path from Node.js installation
+     */
+    resolveNpmPath(): string;
+    /**
+     * STRING UTILITIES
+     */
+    /**
+     * Convert string to camelCase
+     */
+    camelCase(str: string): string;
+    /**
+     * Convert string to snake_case
+     */
+    toSnakeCase(str: string): string;
+    /**
+     * Convert string to PascalCase
+     */
+    toPascalCase(str: string): string;
+    /**
+     * FILE SYSTEM UTILITIES
+     */
+    /**
+     * Check if file exists
+     */
+    fileExists(filePath: string): boolean;
+    /**
+     * Ensure directory exists, create if missing
+     */
+    ensureDir(dirPath: string): void;
+    /**
+     * Read file contents as string
+     */
+    readFile(filePath: string): string;
+    /**
+     * Write file with optional directory creation
+     */
+    writeFile(filePath: string, content: string, createDir?: boolean): void;
+    /**
+     * Delete file if it exists
+     */
+    deleteFile(filePath: string): void;
+    /**
+     * TIMESTAMP UTILITIES
+     */
+    /**
+     * Get current timestamp in ISO format
+     */
+    getCurrentTimestamp(): string;
+    /**
+     * Format timestamp for filenames (YYYY-MM-DDTHH-MM-SS-SSSZ)
+     */
+    formatTimestamp(date?: Date): string;
+    /**
+     * Parse ISO timestamp string to Date
+     */
+    parseTimestamp(timestamp: string): Date;
+    /**
+     * VALIDATION UTILITIES
+     */
+    /**
+     * Extract error message from unknown error type
+     */
+    extractErrorMessage(error: unknown): string;
+    /**
+     * Validate options object and throw if invalid
+     */
+    validateOptions(options: Record<string, unknown>, requiredFields: string[], context: string): void;
+    /**
+     * Check if value is valid (not null, undefined, or empty string)
+     */
+    isValid(value: unknown): boolean;
+    /**
+     * Ensure value is string, throw otherwise
+     */
+    ensureString(value: unknown, fieldName: string): string;
+    /**
+     * Ensure value is object, throw otherwise
+     */
+    ensureObject(value: unknown, fieldName: string): Record<string, unknown>;
+}>;
+export declare const resolveNpmPath: () => string;
+//# sourceMappingURL=index.d.ts.map

package/src/common/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/common/index.ts"],"names":[],"mappings":"AAIA;;GAEG;AACH,eAAO,MAAM,WAAW;IACtB;;OAEG;sBACe,MAAM;IAgBxB;;OAEG;IAEH;;OAEG;mBACY,MAAM,GAAG,MAAM;IAgB9B;;OAEG;qBACc,MAAM,GAAG,MAAM;IAUhC;;OAEG;sBACe,MAAM,GAAG,MAAM;IAQjC;;OAEG;IAEH;;OAEG;yBACkB,MAAM,GAAG,OAAO;IAQrC;;OAEG;uBACgB,MAAM,GAAG,IAAI;IAMhC;;OAEG;uBACgB,MAAM,GAAG,MAAM;IAUlC;;OAEG;wBACiB,MAAM,WAAW,MAAM,wBAAqB,IAAI;IAcpE;;OAEG;yBACkB,MAAM,GAAG,IAAI;IAYlC;;OAEG;IAEH;;OAEG;2BACoB,MAAM;IAI7B;;OAEG;2BACmB,IAAI,GAAgB,MAAM;IAIhD;;OAEG;8BACuB,MAAM,GAAG,IAAI;IAYvC;;OAEG;IAEH;;OAEG;+BACwB,OAAO,GAAG,MAAM;IAa3C;;OAEG;6BAEQ,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,kBAChB,MAAM,EAAE,WACf,MAAM,GACd,IAAI;IAWP;;OAEG;mBACY,OAAO,GAAG,OAAO;IAIhC;;OAEG;wBACiB,OAAO,aAAa,MAAM,GAAG,MAAM;IAOvD;;OAEG;wBACiB,OAAO,aAAa,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;EAMxE,CAAC;AAGH,eAAO,MAAM,cAAc,QAAO,MAAsC,CAAC"}

package/src/common/index.js

@@ -0,0 +1,207 @@
+import { ErrorFactory } from '../exceptions/ZintrustError';
+import fs from '../node-singletons/fs';
+import * as path from 'node:path';
+/**
+ * Common utilities - Sealed namespace for immutability
+ */
+export const CommonUtils = Object.freeze({
+    /**
+     * Resolve npm executable path from Node.js installation
+     */
+    resolveNpmPath() {
+        const nodeBinDir = path.dirname(process.execPath);
+        const candidates = process.platform === 'win32'
+            ? [path.join(nodeBinDir, 'npm.cmd'), path.join(nodeBinDir, 'npm.exe')]
+            : [path.join(nodeBinDir, 'npm')];
+        for (const candidate of candidates) {
+            if (fs.existsSync(candidate))
+                return candidate;
+        }
+        throw ErrorFactory.createGeneralError('Unable to locate npm executable. Ensure Node.js (with npm) is installed in the standard location.');
+    },
+    /**
+     * STRING UTILITIES
+     */
+    /**
+     * Convert string to camelCase
+     */
+    camelCase(str) {
+        return (str
+            // First convert PascalCase/camelCase to snake_case format for splitting
+            .replaceAll(/([a-z])([A-Z])/g, '$1_$2')
+            .split(/[\s_-]+/)
+            .map((word, index) => {
+            if (index === 0) {
+                return word.charAt(0).toLowerCase() + word.slice(1).toLowerCase();
+            }
+            return word.charAt(0).toUpperCase() + word.slice(1).toLowerCase();
+        })
+            .join(''));
+    },
+    /**
+     * Convert string to snake_case
+     */
+    toSnakeCase(str) {
+        return str
+            .replaceAll(/([a-z])([A-Z])/g, '$1_$2')
+            .replaceAll(/([A-Z])/g, '_$1')
+            .replaceAll(/(\d)([A-Z])/g, '$1_$2')
+            .toLowerCase()
+            .replace(/^_/, '')
+            .replaceAll(/__+/g, '_');
+    },
+    /**
+     * Convert string to PascalCase
+     */
+    toPascalCase(str) {
+        return str
+            .replaceAll(/([a-z])([A-Z])/g, '$1_$2') // Add underscore before capital letters in camelCase
+            .split(/[\s_-]+/)
+            .map((word) => word.charAt(0).toUpperCase() + word.slice(1).toLowerCase())
+            .join('');
+    },
+    /**
+     * FILE SYSTEM UTILITIES
+     */
+    /**
+     * Check if file exists
+     */
+    fileExists(filePath) {
+        try {
+            return fs.existsSync(filePath);
+        }
+        catch {
+            return false;
+        }
+    },
+    /**
+     * Ensure directory exists, create if missing
+     */
+    ensureDir(dirPath) {
+        if (!fs.existsSync(dirPath)) {
+            fs.mkdirSync(dirPath, { recursive: true });
+        }
+    },
+    /**
+     * Read file contents as string
+     */
+    readFile(filePath) {
+        try {
+            return fs.readFileSync(filePath, 'utf-8');
+        }
+        catch (error) {
+            throw ErrorFactory.createGeneralError(`Failed to read file: ${filePath}. ${error instanceof Error ? error.message : 'Unknown error'}`);
+        }
+    },
+    /**
+     * Write file with optional directory creation
+     */
+    writeFile(filePath, content, createDir = true) {
+        try {
+            if (createDir) {
+                const dir = path.dirname(filePath);
+                this.ensureDir(dir);
+            }
+            fs.writeFileSync(filePath, content, 'utf-8');
+        }
+        catch (error) {
+            throw ErrorFactory.createGeneralError(`Failed to write file: ${filePath}. ${error instanceof Error ? error.message : 'Unknown error'}`);
+        }
+    },
+    /**
+     * Delete file if it exists
+     */
+    deleteFile(filePath) {
+        try {
+            if (fs.existsSync(filePath)) {
+                fs.unlinkSync(filePath);
+            }
+        }
+        catch (error) {
+            throw ErrorFactory.createGeneralError(`Failed to delete file: ${filePath}. ${error instanceof Error ? error.message : 'Unknown error'}`);
+        }
+    },
+    /**
+     * TIMESTAMP UTILITIES
+     */
+    /**
+     * Get current timestamp in ISO format
+     */
+    getCurrentTimestamp() {
+        return new Date().toISOString();
+    },
+    /**
+     * Format timestamp for filenames (YYYY-MM-DDTHH-MM-SS-SSSZ)
+     */
+    formatTimestamp(date = new Date()) {
+        return date.toISOString().replaceAll(/[:.]/g, '-');
+    },
+    /**
+     * Parse ISO timestamp string to Date
+     */
+    parseTimestamp(timestamp) {
+        try {
+            const date = new Date(timestamp);
+            if (date.toString() === 'Invalid Date') {
+                throw ErrorFactory.createGeneralError('Invalid date');
+            }
+            return date;
+        }
+        catch (error) {
+            throw ErrorFactory.createGeneralError(`Failed to parse timestamp: ${timestamp}`, error);
+        }
+    },
+    /**
+     * VALIDATION UTILITIES
+     */
+    /**
+     * Extract error message from unknown error type
+     */
+    extractErrorMessage(error) {
+        if (error instanceof Error) {
+            return error.message;
+        }
+        if (typeof error === 'string') {
+            return error;
+        }
+        if (error !== undefined && error !== null && typeof error === 'object' && 'message' in error) {
+            return String(error.message);
+        }
+        return 'Unknown error occurred';
+    },
+    /**
+     * Validate options object and throw if invalid
+     */
+    validateOptions(options, requiredFields, context) {
+        const missingFields = requiredFields.filter((field) => options[field] === undefined || options[field] === null);
+        if (missingFields.length > 0) {
+            throw ErrorFactory.createGeneralError(`${context}: Missing required options: ${missingFields.join(', ')}`);
+        }
+    },
+    /**
+     * Check if value is valid (not null, undefined, or empty string)
+     */
+    isValid(value) {
+        return value !== null && value !== undefined && value !== '';
+    },
+    /**
+     * Ensure value is string, throw otherwise
+     */
+    ensureString(value, fieldName) {
+        if (typeof value !== 'string') {
+            throw ErrorFactory.createGeneralError(`${fieldName} must be a string, got ${typeof value}`);
+        }
+        return value;
+    },
+    /**
+     * Ensure value is object, throw otherwise
+     */
+    ensureObject(value, fieldName) {
+        if (typeof value !== 'object' || value === null) {
+            throw ErrorFactory.createGeneralError(`${fieldName} must be an object, got ${typeof value}`);
+        }
+        return value;
+    },
+});
+// Re-export for backward compatibility
+export const resolveNpmPath = () => CommonUtils.resolveNpmPath();