@zintrust/core 0.1.28 → 0.1.30

package/src/cli/services/VersionChecker.js

@@ -0,0 +1,258 @@
+/**
+ * VersionChecker - CLI Version Update Notification Service
+ *
+ * Checks if the current CLI version is outdated and warns users
+ * when a newer version is available from npm registry.
+ */
+import { HttpClient } from '../../tools/http/Http.js';
+import { existsSync, readFileSync } from '../../node-singletons/fs.js';
+import { dirname, join } from '../../node-singletons/path.js';
+import { fileURLToPath } from '../../node-singletons/url.js';
+export const VersionChecker = Object.freeze({
+    /**
+     * Resolve the nearest package.json from a starting directory.
+     */
+    findNearestPackageJson(startDir) {
+        let current = startDir;
+        for (let i = 0; i < 8; i++) {
+            const candidate = join(current, 'package.json');
+            if (existsSync(candidate))
+                return candidate;
+            const parent = dirname(current);
+            if (parent === current)
+                break;
+            current = parent;
+        }
+        return null;
+    },
+    /**
+     * Get current version from package.json
+     */
+    getCurrentVersion() {
+        try {
+            const moduleDir = dirname(fileURLToPath(import.meta.url));
+            const modulePackagePath = this.findNearestPackageJson(moduleDir);
+            const cwdPackagePath = this.findNearestPackageJson(process.cwd());
+            const packagePath = modulePackagePath ?? cwdPackagePath;
+            if (packagePath === null)
+                return '0.0.0';
+            const packageJson = JSON.parse(readFileSync(packagePath, 'utf-8'));
+            return typeof packageJson.version === 'string' ? packageJson.version : '0.0.0';
+        }
+        catch {
+            return '0.0.0';
+        }
+    },
+    /**
+     * Get version check configuration
+     */
+    getConfig() {
+        return {
+            enabled: process.env['ZINTRUST_VERSION_CHECK'] !== 'false',
+            checkInterval: Number.parseInt(process.env['ZINTRUST_VERSION_CHECK_INTERVAL'] ?? '24', 10),
+            skipVersionCheck: process.env['ZINTRUST_SKIP_VERSION_CHECK'] === 'true',
+        };
+    },
+    /**
+     * Check if version check should be performed
+     */
+    shouldCheckVersion() {
+        const config = this.getConfig();
+        // Skip if disabled
+        if (!config.enabled || config.skipVersionCheck) {
+            return false;
+        }
+        // Skip for version commands
+        const args = new Set(process.argv.slice(2));
+        if (args.has('-v') || args.has('--version') || args.has('help') || args.has('new')) {
+            return false;
+        }
+        // Check last check time
+        const lastCheckKey = 'zintrust_last_version_check';
+        const lastCheck = globalThis.localStorage?.getItem?.(lastCheckKey);
+        if (lastCheck !== null && lastCheck !== undefined) {
+            const lastCheckTime = Number.parseInt(lastCheck, 10);
+            const now = Date.now();
+            const hoursSinceLastCheck = (now - lastCheckTime) / (1000 * 60 * 60);
+            if (hoursSinceLastCheck < config.checkInterval) {
+                return false;
+            }
+        }
+        return true;
+    },
+    /**
+     * Fetch latest version from npm registry
+     */
+    async fetchLatestVersion() {
+        try {
+            const response = await this.fetchFromNpmRegistry();
+            if (!response.ok) {
+                return this.handleHttpError();
+            }
+            const data = await response.json();
+            return this.extractVersionFromResponse(data);
+        }
+        catch {
+            // For network errors or other issues, don't block CLI usage
+            return this.getCurrentVersion();
+        }
+    },
+    /**
+     * Make request to npm registry
+     */
+    async fetchFromNpmRegistry() {
+        return HttpClient.get('https://registry.npmjs.org/@zintrust/core/latest')
+            .withHeader('Accept', 'application/json')
+            .withHeader('User-Agent', 'ZinTrust-CLI-Version-Check')
+            .withTimeout(5000) // 5 second timeout
+            .send();
+    },
+    /**
+     * Handle HTTP errors from npm registry
+     */
+    handleHttpError() {
+        return this.getCurrentVersion();
+    },
+    /**
+     * Extract version from npm registry response
+     */
+    extractVersionFromResponse(data) {
+        if (!this.isValidResponseData(data)) {
+            return this.getCurrentVersion();
+        }
+        const dataRecord = data;
+        // Try to get version from dist-tags.latest (standard npm response)
+        const latestVersion = this.getVersionFromDistTags(dataRecord);
+        if (latestVersion !== null && latestVersion !== undefined && latestVersion !== '') {
+            return latestVersion;
+        }
+        // Fallback to version field
+        const fallbackVersion = this.getVersionFromField(dataRecord);
+        if (fallbackVersion !== null && fallbackVersion !== undefined && fallbackVersion !== '') {
+            return fallbackVersion;
+        }
+        // Final fallback
+        return this.getCurrentVersion();
+    },
+    /**
+     * Check if response data is valid object
+     */
+    isValidResponseData(data) {
+        return data !== null && data !== undefined && typeof data === 'object';
+    },
+    /**
+     * Extract version from dist-tags
+     */
+    getVersionFromDistTags(dataRecord) {
+        const distTags = dataRecord['dist-tags'];
+        if (distTags !== null && distTags !== undefined) {
+            const distTagsRecord = distTags;
+            const latest = distTagsRecord['latest'];
+            if (typeof latest === 'string' && latest !== '') {
+                return latest;
+            }
+        }
+        return null;
+    },
+    /**
+     * Extract version from version field
+     */
+    getVersionFromField(dataRecord) {
+        const version = dataRecord['version'];
+        if (typeof version === 'string' && version !== '') {
+            return version;
+        }
+        return null;
+    },
+    /**
+     * Compare versions using semver-like comparison
+     */
+    compareVersions(current, latest) {
+        const cleanVersion = (version) => {
+            // Remove leading 'v' and trailing pre-release identifiers safely
+            // Using specific patterns instead of greedy quantifiers to prevent ReDoS
+            return version.replace(/^v/, '').replace(/-[^-]*$/, '');
+        };
+        const currentParts = cleanVersion(current).split('.').map(Number);
+        const latestParts = cleanVersion(latest).split('.').map(Number);
+        const maxLength = Math.max(currentParts.length, latestParts.length);
+        for (let i = 0; i < maxLength; i++) {
+            const currentPart = currentParts[i] || 0;
+            const latestPart = latestParts[i] || 0;
+            if (currentPart < latestPart)
+                return -1;
+            if (currentPart > latestPart)
+                return 1;
+        }
+        return 0;
+    },
+    /**
+     * Perform version check and return result
+     */
+    async checkVersion() {
+        if (!this.shouldCheckVersion()) {
+            return null;
+        }
+        try {
+            const currentVersion = this.getCurrentVersion();
+            const latestVersion = await this.fetchLatestVersion();
+            const comparison = this.compareVersions(currentVersion, latestVersion);
+            const isOutdated = comparison < 0;
+            const updateAvailable = isOutdated;
+            // Update last check time
+            const lastCheckKey = 'zintrust_last_version_check';
+            globalThis.localStorage?.setItem?.(lastCheckKey, Date.now().toString());
+            return {
+                currentVersion,
+                latestVersion,
+                isOutdated,
+                updateAvailable,
+            };
+        }
+        catch {
+            // Silently fail - version check should never block CLI usage
+            return null;
+        }
+    },
+    /**
+     * Display update notification to user
+     */
+    displayUpdateNotification(result) {
+        if (!result.updateAvailable) {
+            return;
+        }
+        const { currentVersion, latestVersion } = result;
+        // Use process.stdout.write for better control and to avoid eslint console errors
+        const output = [
+            '',
+            '⚠️  Update Available',
+            '┌' + '─'.repeat(50) + '┐',
+            `│ Current:  ${currentVersion.padEnd(40)}│`,
+            `│ Latest:   ${latestVersion.padEnd(40)}│`,
+            '└' + '─'.repeat(50) + '┘',
+            '',
+            '💡 Update to get the latest features and bug fixes:',
+            `   npm install -g @zintrust/core@${latestVersion}`,
+            '   or: npx @zintrust/core@latest [command]',
+            '',
+            '🔧 To disable version checks:',
+            '   export ZINTRUST_VERSION_CHECK=false',
+            '',
+        ].join('\n');
+        process.stdout.write(output);
+    },
+    /**
+     * Run version check and display notification if needed
+     */
+    async runVersionCheck() {
+        try {
+            const result = await this.checkVersion();
+            if (result) {
+                this.displayUpdateNotification(result);
+            }
+        }
+        catch {
+            // Version check should never crash the CLI
+        }
+    },
+});

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

@@ -0,0 +1,20 @@
+import type { CommandOptions, IBaseCommand } from '../BaseCommand';
+import type { DatabaseConfig as OrmDatabaseConfig } from '../../orm/DatabaseAdapter';
+export type ConnectionConfig = {
+    driver: string;
+    host?: string;
+    port?: number;
+    database?: string;
+    username?: string;
+    password?: string;
+};
+export declare const mapConnectionToOrmConfig: (conn: ConnectionConfig) => OrmDatabaseConfig;
+export declare const parseRollbackSteps: (options: CommandOptions) => number;
+export declare const confirmProductionRun: (params: {
+    cmd: IBaseCommand;
+    interactive: boolean;
+    message: string;
+    destructive?: boolean;
+    force?: boolean;
+}) => Promise<boolean>;
+//# sourceMappingURL=DatabaseCliUtils.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"DatabaseCliUtils.d.ts","sourceRoot":"","sources":["../../../../src/cli/utils/DatabaseCliUtils.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAC;AAGrE,OAAO,KAAK,EAAE,cAAc,IAAI,iBAAiB,EAAE,MAAM,sBAAsB,CAAC;AAEhF,MAAM,MAAM,gBAAgB,GAAG;IAC7B,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB,CAAC;AAEF,eAAO,MAAM,wBAAwB,GAAI,MAAM,gBAAgB,KAAG,iBAkCjE,CAAC;AAEF,eAAO,MAAM,kBAAkB,GAAI,SAAS,cAAc,KAAG,MAG5D,CAAC;AAEF,eAAO,MAAM,oBAAoB,GAAU,QAAQ;IACjD,GAAG,EAAE,YAAY,CAAC;IAClB,WAAW,EAAE,OAAO,CAAC;IACrB,OAAO,EAAE,MAAM,CAAC;IAChB,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB,KAAG,OAAO,CAAC,OAAO,CAalB,CAAC"}

package/src/cli/utils/DatabaseCliUtils.js

@@ -0,0 +1,54 @@
+import { PromptHelper } from '../PromptHelper.js';
+import { Env } from '../../config/env.js';
+export const mapConnectionToOrmConfig = (conn) => {
+    switch (conn.driver) {
+        case 'sqlite':
+            return { driver: 'sqlite', database: conn.database ?? ':memory:' };
+        case 'postgresql':
+            return {
+                driver: 'postgresql',
+                host: conn.host,
+                port: conn.port,
+                database: conn.database,
+                username: conn.username,
+                password: conn.password,
+            };
+        case 'mysql':
+            return {
+                driver: 'mysql',
+                host: conn.host,
+                port: conn.port,
+                database: conn.database,
+                username: conn.username,
+                password: conn.password,
+            };
+        case 'sqlserver':
+            return {
+                driver: 'sqlserver',
+                host: conn.host,
+                port: conn.port,
+                database: conn.database,
+                username: conn.username,
+                password: conn.password,
+            };
+        default:
+            return { driver: 'sqlite', database: ':memory:' };
+    }
+};
+export const parseRollbackSteps = (options) => {
+    const stepRaw = typeof options['step'] === 'string' ? options['step'] : '1';
+    return Math.max(1, Number.parseInt(stepRaw, 10) || 1);
+};
+export const confirmProductionRun = async (params) => {
+    if (Env.NODE_ENV !== 'production')
+        return true;
+    if (params.force === true)
+        return true;
+    const prompt = params.destructive === true ? `${params.message} (destructive)` : params.message;
+    const confirmed = await PromptHelper.confirm(prompt, false, params.interactive);
+    if (!confirmed) {
+        params.cmd.warn('Cancelled.');
+        return false;
+    }
+    return true;
+};

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

@@ -0,0 +1,8 @@
+export declare const DistPackager: Readonly<{
+    /**
+     * Creates minimal metadata so `dist/` can be installed via `file:/.../dist`.
+     * This is intended for local dev/simulate apps, not publishing.
+     */
+    prepare(distPath: string, rootPath?: string): void;
+}>;
+//# sourceMappingURL=DistPackager.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"DistPackager.d.ts","sourceRoot":"","sources":["../../../../src/cli/utils/DistPackager.ts"],"names":[],"mappings":"AAoIA,eAAO,MAAM,YAAY;IACvB;;;OAGG;sBACe,MAAM,aAAY,MAAM,GAAmB,IAAI;EAgBjE,CAAC"}

package/src/cli/utils/DistPackager.js

@@ -0,0 +1,102 @@
+import { Logger } from '../../config/logger.js';
+import { ErrorFactory } from '../../exceptions/ZintrustError.js';
+import fs from '../../node-singletons/fs.js';
+import * as path from '../../node-singletons/path.js';
+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',
+            },
+            './start': {
+                types: './start.d.ts',
+                default: './start.js',
+            },
+        },
+        dependencies: coerceDependencies(rootPkg.dependencies),
+    };
+};
+const writeDistEntrypoints = (distPath) => {
+    const distIndexJsPath = path.join(distPath, 'index.js');
+    const distIndexDtsPath = path.join(distPath, 'index.d.ts');
+    const distStartJsPath = path.join(distPath, 'start.js');
+    const distStartDtsPath = path.join(distPath, 'start.d.ts');
+    fs.writeFileSync(distIndexJsPath, "export * from './src/index.js';\n");
+    fs.writeFileSync(distIndexDtsPath, "export * from './src/index';\n");
+    fs.writeFileSync(distStartJsPath, "export * from './src/start.js'; export { default } from './src/start.js';\n");
+    fs.writeFileSync(distStartDtsPath, "export * from './src/start'; export { default } from './src/start';\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":"AAgHA,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.js';
+import { join } from '../../node-singletons/path.js';
+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;EAwE7D,CAAC"}