@zintrust/core 2.4.1 → 2.4.3

package/src/cli/services/WorkerStartupDiagnostics.js

@@ -0,0 +1,350 @@
+import { Env } from '../../config/env.js';
+import { Logger } from '../../config/logger.js';
+import { queueConfig } from '../../config/queue.js';
+import { ErrorFactory } from '../../exceptions/ZintrustError.js';
+import { isNonEmptyString, isObject } from '../../helper/index.js';
+const SECRET_KEY_PATTERN = /(SECRET|PASSWORD|TOKEN|KEY)$/i;
+const uniqueStrings = (values) => {
+    const seen = new Set();
+    const out = [];
+    for (const value of values) {
+        const normalized = value.trim();
+        if (!isNonEmptyString(normalized))
+            continue;
+        if (seen.has(normalized))
+            continue;
+        seen.add(normalized);
+        out.push(normalized);
+    }
+    return out;
+};
+const getSnapshotValue = (snapshot, key) => {
+    const value = snapshot[key];
+    return typeof value === 'string' ? value.trim() : '';
+};
+const getExplicitEnv = (snapshot, key) => getSnapshotValue(snapshot, key);
+const getResolvedEnv = (key) => Env.get(key, '').trim();
+const resolveRedisProxyKeyId = (snapshot) => {
+    const explicit = getExplicitEnv(snapshot, 'REDIS_PROXY_KEY_ID');
+    if (isNonEmptyString(explicit))
+        return explicit;
+    const appName = getExplicitEnv(snapshot, 'APP_NAME') || Env.get('APP_NAME', 'zintrust').trim();
+    return (appName || 'zintrust').trim().toLowerCase().replaceAll(/\s+/g, '_');
+};
+const resolveRedisProxySecret = (snapshot) => {
+    const explicit = getExplicitEnv(snapshot, 'REDIS_PROXY_SECRET');
+    if (isNonEmptyString(explicit))
+        return explicit;
+    return getExplicitEnv(snapshot, 'APP_KEY') || Env.get('APP_KEY', '').trim();
+};
+const resolveRedisProxyUrl = (snapshot) => {
+    const explicit = getExplicitEnv(snapshot, 'REDIS_PROXY_URL');
+    if (isNonEmptyString(explicit))
+        return explicit;
+    if (!Env.getBool('USE_REDIS_PROXY', false))
+        return '';
+    const host = getExplicitEnv(snapshot, 'REDIS_PROXY_HOST') || Env.get('REDIS_PROXY_HOST', '127.0.0.1').trim();
+    const port = getExplicitEnv(snapshot, 'REDIS_PROXY_PORT') || Env.get('REDIS_PROXY_PORT', '8791').trim();
+    return host === '' || port === '' ? '' : `http://${host}:${port}`;
+};
+const DIAGNOSTIC_VALUE_RESOLVERS = Object.freeze({
+    RUNTIME_MODE: (_snapshot, flags) => flags.runtimeMode,
+    WORKER_ENABLED: (_snapshot, flags) => String(flags.workerEnabled),
+    WORKER_AUTO_START: (_snapshot, flags) => String(flags.workerAutoStart),
+    DOCKER_WORKER: (_snapshot, flags) => String(flags.dockerWorker),
+    QUEUE_ENABLED: (_snapshot, flags) => String(flags.queueEnabled),
+    QUEUE_DRIVER: (_snapshot, flags) => flags.queueDriver,
+    WORKER_PERSISTENCE_DRIVER: (_snapshot, flags) => flags.persistenceDriver,
+    REDIS_PROXY_URL: (snapshot) => resolveRedisProxyUrl(snapshot),
+    REDIS_PROXY_HOST: (snapshot) => getExplicitEnv(snapshot, 'REDIS_PROXY_HOST') ||
+        Env.get('REDIS_PROXY_HOST', '127.0.0.1').trim(),
+    REDIS_PROXY_SECRET: (snapshot) => resolveRedisProxySecret(snapshot),
+    REDIS_PROXY_KEY_ID: (snapshot) => resolveRedisProxyKeyId(snapshot),
+    REDIS_QUEUE_DB: (snapshot) => getExplicitEnv(snapshot, 'REDIS_QUEUE_DB') || Env.get('REDIS_QUEUE_DB', '1').trim(),
+    WORKER_PERSISTENCE_DB_CONNECTION: (snapshot) => getExplicitEnv(snapshot, 'WORKER_PERSISTENCE_DB_CONNECTION') ||
+        Env.get('WORKER_PERSISTENCE_DB_CONNECTION', 'default').trim(),
+    WORKER_PERSISTENCE_TABLE: (snapshot) => getExplicitEnv(snapshot, 'WORKER_PERSISTENCE_TABLE') ||
+        Env.get('WORKER_PERSISTENCE_TABLE', 'zintrust_workers').trim(),
+    DB_CONNECTION: (snapshot) => getExplicitEnv(snapshot, 'DB_CONNECTION') || Env.get('DB_CONNECTION', '').trim(),
+});
+const getDiagnosticResolvedValue = (snapshot, key, flags) => DIAGNOSTIC_VALUE_RESOLVERS[key]?.(snapshot, flags) ?? getResolvedEnv(key);
+const maskResolvedValue = (key, value) => {
+    if (!isNonEmptyString(value))
+        return '[missing]';
+    if (SECRET_KEY_PATTERN.test(key))
+        return '[set]';
+    return value;
+};
+const getQueueDriver = () => {
+    try {
+        return { value: queueConfig.default };
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        return {
+            value: Env.get('QUEUE_DRIVER', 'sync').trim() || 'sync',
+            issue: {
+                severity: 'error',
+                message: `Queue config failed to resolve: ${message}`,
+                envKeys: extractEnvKeysFromMessage(message),
+            },
+        };
+    }
+};
+const getPersistenceDriver = () => {
+    const raw = Env.get('WORKER_PERSISTENCE_DRIVER', '').trim().toLowerCase();
+    return raw === '' ? 'memory (implicit)' : raw;
+};
+const extractEnvKeysFromMessage = (message) => {
+    const matches = message.match(/\b[A-Z][A-Z0-9_]{2,}\b/g) ?? [];
+    return uniqueStrings(matches);
+};
+const inferEnvKeysFromContext = (message, flags) => {
+    const lower = message.toLowerCase();
+    const inferred = [];
+    if (lower.includes('redis') && lower.includes('host is required')) {
+        inferred.push('REDIS_HOST');
+    }
+    if (lower.includes('worker persistence') && lower.includes('database client')) {
+        inferred.push('WORKER_PERSISTENCE_DB_CONNECTION', 'DB_CONNECTION');
+    }
+    if (lower.includes('worker persistence') && lower.includes('redis config')) {
+        inferred.push('REDIS_HOST', 'REDIS_PORT');
+    }
+    if (flags.queueDriver === 'sqs') {
+        inferred.push('AWS_ACCESS_KEY_ID', 'AWS_SECRET_ACCESS_KEY', 'AWS_REGION', 'AWS_SQS_QUEUE_URL');
+    }
+    return uniqueStrings(inferred);
+};
+const getFirstFault = (error, flags) => {
+    if (!(error instanceof Error))
+        return null;
+    const errorCode = isObject(error) && typeof error['code'] === 'string' ? error['code'] : undefined;
+    const envKeys = uniqueStrings([
+        ...extractEnvKeysFromMessage(error.message),
+        ...inferEnvKeysFromContext(error.message, flags),
+    ]);
+    return {
+        message: envKeys.length > 0
+            ? `${error.message} | likely env keys: ${envKeys.join(', ')}`
+            : error.message,
+        code: errorCode,
+    };
+};
+const getQueueDriverEnvKeys = (snapshot, queueDriver) => {
+    if (queueDriver === 'sqs') {
+        return ['AWS_ACCESS_KEY_ID', 'AWS_SECRET_ACCESS_KEY', 'AWS_REGION', 'AWS_SQS_QUEUE_URL'];
+    }
+    if (queueDriver === 'database') {
+        return ['QUEUE_DB_CONNECTION', 'DB_CONNECTION'];
+    }
+    if (queueDriver === 'rabbitmq') {
+        return ['RABBITMQ_HOST', 'RABBITMQ_PORT', 'RABBITMQ_USER', 'RABBITMQ_PASSWORD'];
+    }
+    const usesRedisProxy = Env.getBool('USE_REDIS_PROXY', false) &&
+        (isNonEmptyString(getExplicitEnv(snapshot, 'REDIS_RPC_URL')) ||
+            isNonEmptyString(getExplicitEnv(snapshot, 'REDIS_PROXY_URL')));
+    if (queueDriver === 'redis' && usesRedisProxy) {
+        return [
+            'REDIS_RPC_URL',
+            'REDIS_PROXY_URL',
+            'REDIS_PROXY_HOST',
+            'REDIS_PROXY_SECRET',
+            'REDIS_PROXY_KEY_ID',
+            'APP_KEY',
+            'REDIS_QUEUE_DB',
+        ];
+    }
+    if (queueDriver === 'redis') {
+        return ['REDIS_HOST', 'REDIS_PORT', 'REDIS_PASSWORD', 'REDIS_QUEUE_DB'];
+    }
+    return [];
+};
+const getPersistenceEnvKeys = (persistenceDriver) => {
+    if (persistenceDriver === 'database' || persistenceDriver === 'db') {
+        return ['WORKER_PERSISTENCE_DB_CONNECTION', 'WORKER_PERSISTENCE_TABLE', 'DB_CONNECTION'];
+    }
+    if (persistenceDriver === 'redis') {
+        return ['WORKER_PERSISTENCE_REDIS_DB', 'REDIS_HOST', 'REDIS_PORT', 'REDIS_PASSWORD'];
+    }
+    return [];
+};
+const buildFlags = () => {
+    const queueDriver = getQueueDriver();
+    return {
+        runtimeMode: Env.get('RUNTIME_MODE', 'node-server').trim() || 'node-server',
+        workerEnabled: Env.getBool('WORKER_ENABLED', false),
+        workerAutoStart: Env.getBool('WORKER_AUTO_START', false),
+        dockerWorker: Env.getBool('DOCKER_WORKER', false),
+        queueEnabled: Env.getBool('QUEUE_ENABLED', false),
+        queueDriver: queueDriver.value,
+        persistenceDriver: getPersistenceDriver(),
+    };
+};
+const buildEnvStatus = (snapshot, flags, firstFault) => {
+    const relevantKeys = uniqueStrings([
+        'RUNTIME_MODE',
+        'WORKER_ENABLED',
+        'WORKER_AUTO_START',
+        'DOCKER_WORKER',
+        'QUEUE_ENABLED',
+        'QUEUE_DRIVER',
+        'WORKER_PERSISTENCE_DRIVER',
+        ...getQueueDriverEnvKeys(snapshot, flags.queueDriver),
+        ...getPersistenceEnvKeys(flags.persistenceDriver),
+        ...(firstFault ? extractEnvKeysFromMessage(firstFault.message) : []),
+    ]);
+    return relevantKeys.map((key) => {
+        const explicitValue = getExplicitEnv(snapshot, key);
+        const effectiveValue = getDiagnosticResolvedValue(snapshot, key, flags);
+        return {
+            key,
+            present: isNonEmptyString(explicitValue) || isNonEmptyString(effectiveValue),
+            explicitValue,
+            resolvedValue: maskResolvedValue(key, effectiveValue),
+        };
+    });
+};
+const buildIssues = (envStatus, flags, firstFault, queueIssue) => {
+    const issues = [];
+    if (queueIssue !== undefined) {
+        issues.push(queueIssue);
+    }
+    if (!flags.workerEnabled) {
+        issues.push({
+            severity: flags.dockerWorker ? 'error' : 'warn',
+            message: 'WORKER_ENABLED is false, so the worker runtime will not process jobs.',
+            envKeys: ['WORKER_ENABLED'],
+        });
+    }
+    if (!flags.queueEnabled) {
+        issues.push({
+            severity: 'warn',
+            message: 'QUEUE_ENABLED is false, so queue-backed workers cannot process jobs.',
+            envKeys: ['QUEUE_ENABLED'],
+        });
+    }
+    if (flags.workerEnabled && !flags.workerAutoStart) {
+        issues.push({
+            severity: 'warn',
+            message: 'WORKER_AUTO_START is false, so worker:start-all will skip auto-start.',
+            envKeys: ['WORKER_AUTO_START'],
+        });
+    }
+    const missingEnvKeys = envStatus.filter((entry) => !entry.present).map((entry) => entry.key);
+    if (flags.queueDriver === 'sqs') {
+        const sqsMissing = missingEnvKeys.filter((key) => ['AWS_ACCESS_KEY_ID', 'AWS_SECRET_ACCESS_KEY', 'AWS_REGION', 'AWS_SQS_QUEUE_URL'].includes(key));
+        if (sqsMissing.length > 0) {
+            issues.push({
+                severity: 'error',
+                message: 'SQS queue driver is selected but required AWS queue env keys are missing.',
+                envKeys: sqsMissing,
+            });
+        }
+    }
+    if (firstFault !== null) {
+        const firstFaultKeys = uniqueStrings([
+            ...extractEnvKeysFromMessage(firstFault.message),
+            ...inferEnvKeysFromContext(firstFault.message, flags),
+        ]);
+        if (firstFaultKeys.length > 0) {
+            issues.push({
+                severity: 'error',
+                message: 'The first failure points to missing or invalid runtime env configuration.',
+                envKeys: firstFaultKeys,
+            });
+        }
+    }
+    return issues;
+};
+const buildLogPointers = (flags) => flags.runtimeMode === 'containers'
+    ? [
+        'worker:start-all stderr/stdout',
+        'zin docker --wrangler-config wrangler.containers-proxy.jsonc --env <env> output',
+        'worker container logs for the node dist/bin/zin.js worker:start-all process',
+    ]
+    : ['worker:start-all stderr/stdout'];
+const buildNextSteps = (flags) => flags.runtimeMode === 'containers'
+    ? [
+        'zin worker:doctor --json',
+        'node dist/bin/zin.js worker:start-all',
+        'node scripts/docker-image-smoke.mjs worker --skip-build --image <image>',
+    ]
+    : ['zin worker:doctor --json'];
+const collect = (error) => {
+    const snapshot = Env.snapshot();
+    const queueDriver = getQueueDriver();
+    const flags = buildFlags();
+    const firstFault = getFirstFault(error, flags);
+    const envStatus = buildEnvStatus(snapshot, flags, firstFault);
+    const issues = buildIssues(envStatus, flags, firstFault, queueDriver.issue);
+    const missingFromIssues = issues.flatMap((issue) => issue.envKeys);
+    const missingEnvKeys = uniqueStrings(missingFromIssues);
+    return {
+        flags,
+        issues,
+        missingEnvKeys,
+        envStatus,
+        firstFault,
+        logPointers: buildLogPointers(flags),
+        nextSteps: buildNextSteps(flags),
+    };
+};
+const appendSection = (lines, title, items) => {
+    if (items.length === 0)
+        return;
+    lines.push('', title, ...items);
+};
+const renderIssues = (report) => report.issues.map((issue) => {
+    const envSuffix = issue.envKeys.length > 0 ? ` [${issue.envKeys.join(', ')}]` : '';
+    return `- ${issue.severity.toUpperCase()}: ${issue.message}${envSuffix}`;
+});
+const renderEnvStatus = (report) => report.envStatus.map((entry) => {
+    const state = entry.present ? entry.resolvedValue : '[missing]';
+    return `- ${entry.key}: ${state}`;
+});
+const renderBullets = (items) => items.map((item) => `- ${item}`);
+const renderLines = (report) => {
+    const lines = [
+        '=== Worker Startup Diagnostics ===',
+        '',
+        `Runtime Mode: ${report.flags.runtimeMode}`,
+        `Worker Enabled: ${report.flags.workerEnabled}`,
+        `Worker Auto Start: ${report.flags.workerAutoStart}`,
+        `Docker Worker: ${report.flags.dockerWorker}`,
+        `Queue Enabled: ${report.flags.queueEnabled}`,
+        `Queue Driver: ${report.flags.queueDriver}`,
+        `Persistence Driver: ${report.flags.persistenceDriver}`,
+    ];
+    appendSection(lines, 'First Fault:', report.firstFault === null ? [] : [`- ${report.firstFault.message}`]);
+    appendSection(lines, 'Issues:', renderIssues(report));
+    appendSection(lines, 'Relevant Env:', renderEnvStatus(report));
+    appendSection(lines, 'Log Pointers:', renderBullets(report.logPointers));
+    appendSection(lines, 'Next Steps:', renderBullets(report.nextSteps));
+    return lines;
+};
+const log = (error, context = 'worker startup') => {
+    const report = collect(error);
+    Logger.error(`${context} first-fault summary`, {
+        flags: report.flags,
+        missingEnvKeys: report.missingEnvKeys,
+        firstFault: report.firstFault,
+        issues: report.issues,
+        logPointers: report.logPointers,
+        nextSteps: report.nextSteps,
+    });
+    if (report.missingEnvKeys.length > 0) {
+        Logger.error('Likely missing env keys for worker startup', report.missingEnvKeys);
+    }
+    return report;
+};
+const hasBlockingIssues = (report) => report.issues.some((issue) => issue.severity === 'error');
+export const WorkerStartupDiagnostics = Object.freeze({
+    collect,
+    renderLines,
+    log,
+    hasBlockingIssues,
+    createCliError(message) {
+        return ErrorFactory.createCliError(message);
+    },
+});

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;AAIrE,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,iBAwCjE,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,59 @@
+import { PromptHelper } from '../PromptHelper.js';
+import { Env } from '../../config/env.js';
+import { ErrorFactory } from '../../exceptions/ZintrustError.js';
+export const mapConnectionToOrmConfig = (conn) => {
+    switch (conn.driver) {
+        case 'd1':
+            return { driver: 'd1' };
+        case 'd1-remote':
+            return { driver: 'd1-remote' };
+        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:
+            throw ErrorFactory.createCliError(`Unsupported database driver for ORM migrations: ${String(conn.driver)}`);
+    }
+};
+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`
+     * without clobbering the publishable package manifest.
+     */
+    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":"AAgKA,eAAO,MAAM,YAAY;IACvB;;;OAGG;sBACe,MAAM,aAAY,MAAM,GAAmB,IAAI;EAgBjE,CAAC"}

package/src/cli/utils/DistPackager.js

@@ -0,0 +1,137 @@
+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,
+        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',
+            },
+            './cli': {
+                types: './src/cli.d.ts',
+                default: './src/cli.js',
+            },
+            './proxy': {
+                types: './src/proxy.d.ts',
+                default: './src/proxy.js',
+            },
+            './proxy/*': {
+                types: './src/proxy/*.d.ts',
+                default: './src/proxy/*.js',
+            },
+            './collections': {
+                types: './src/collections/index.d.ts',
+                default: './src/collections/index.js',
+            },
+            './helper': {
+                types: './src/helper/index.d.ts',
+                default: './src/helper/index.js',
+            },
+            './node': {
+                types: './src/node.d.ts',
+                default: './src/node.js',
+            },
+            './routes/*': {
+                types: './routes/*.d.ts',
+                default: './routes/*.js',
+            },
+            './package.json': './package.json',
+        },
+        dependencies: coerceDependencies(rootPkg.dependencies),
+        publishConfig: {
+            access: 'public',
+        },
+    };
+};
+const writeDistEntrypoints = (distPath) => {
+    const entrypoints = [
+        ['index.js', "export * from './src/index.js';\n"],
+        ['index.d.ts', "export * from './src/index';\n"],
+        ['start.js', "export * from './src/start.js'; export { default } from './src/start.js';\n"],
+        ['start.d.ts', "export * from './src/start'; export { default } from './src/start';\n"],
+    ];
+    for (const [relativePath, content] of entrypoints) {
+        fs.writeFileSync(path.join(distPath, relativePath), content);
+    }
+};
+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 = [
+        ['src/index.js', 'Dist artifact missing (did you run build?)'],
+        ['bin/zintrust.js', 'Dist artifact missing (did you run build?)'],
+        ['bin/zin.js', 'Dist artifact missing (did you run build?)'],
+        ['public', 'Docs public root missing'],
+    ];
+    for (const [relativePath, message] of expected) {
+        const candidate = path.join(distPath, ...relativePath.split('/'));
+        if (fs.existsSync(candidate)) {
+            continue;
+        }
+        if (relativePath === 'public') {
+            Logger.warn(`${message} at ${candidate} (expected dist/public)`);
+            continue;
+        }
+        Logger.warn(`${message}: ${candidate}`);
+    }
+};
+export const DistPackager = Object.freeze({
+    /**
+     * Creates minimal metadata so `dist/` can be installed via `file:/.../dist`
+     * without clobbering the publishable package manifest.
+     */
+    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,28 @@
+type node_env = 'development' | 'production' | 'testing';
+type LoadOptions = {
+    cwd?: string;
+    includeCwd?: boolean;
+    extraCwds?: string[];
+    envPaths?: string[];
+    envPathsOverrideExisting?: boolean;
+    overrideExisting?: boolean;
+};
+type LoadState = {
+    loadedFiles: string[];
+    mode?: string;
+};
+type CliOverrides = {
+    nodeEnv?: node_env;
+    port?: number;
+    runtime?: string;
+    cacheEnabled?: boolean;
+};
+export declare const EnvFileLoader: Readonly<{
+    load: (options?: LoadOptions) => LoadState;
+    ensureLoaded: (options?: Omit<LoadOptions, "overrideExisting">) => LoadState;
+    applyCliOverrides: (overrides: CliOverrides) => void;
+    getState: () => LoadState;
+    resetCache: () => void;
+}>;
+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":"AASA,KAAK,QAAQ,GAAG,aAAa,GAAG,YAAY,GAAG,SAAS,CAAC;AA8IzD,KAAK,WAAW,GAAG;IACjB,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,SAAS,CAAC,EAAE,MAAM,EAAE,CAAC;IACrB,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAC;IACpB,wBAAwB,CAAC,EAAE,OAAO,CAAC;IACnC,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;AAaF,KAAK,YAAY,GAAG;IAClB,OAAO,CAAC,EAAE,QAAQ,CAAC;IACnB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,YAAY,CAAC,EAAE,OAAO,CAAC;CACxB,CAAC;AA6MF,eAAO,MAAM,aAAa;qBArDH,WAAW,KAAQ,SAAS;6BAiBpB,IAAI,CAAC,WAAW,EAAE,kBAAkB,CAAC,KAAQ,SAAS;mCAG/C,YAAY,KAAG,IAAI;oBA+BpC,SAAS;sBAtCP,IAAI;EA8CzB,CAAC"}