@zintrust/core 0.4.54 → 0.4.55

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zintrust/core",
-  "version": "0.4.54",
+  "version": "0.4.55",
   "description": "Production-grade TypeScript backend framework for JavaScript",
   "homepage": "https://zintrust.com",
   "repository": {

package/src/boot.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"boot.d.ts","sourceRoot":"","sources":["../../src/boot.ts"],"names":[],"mappings":"AAoCA,OAAO,EAAE,CAAC"}
+{"version":3,"file":"boot.d.ts","sourceRoot":"","sources":["../../src/boot.ts"],"names":[],"mappings":"AAQA,OAAO,EAAE,CAAC"}

package/src/boot.js

@@ -1,30 +1,6 @@
-import { isNodeRuntime } from './runtime/detectRuntime.js';
-import { resolveNodeProjectRoot } from './runtime/resolveNodeProjectRoot.js';
-const ensureNodeBootstrapEnv = async () => {
-    if (!isNodeRuntime())
-        return;
-    const projectRoot = await resolveNodeProjectRoot();
-    if ((process.env?.['ZINTRUST_PROJECT_ROOT'] ?? '').trim() === '') {
-        process.env['ZINTRUST_PROJECT_ROOT'] = projectRoot;
-    }
-    const [{ EnvFileLoader }, { Logger }, { existsSync }, path] = await Promise.all([
-        import('./cli/utils/EnvFileLoader.js'),
-        import('./config/logger.js'),
-        import('./node-singletons/fs.js'),
-        import('./node-singletons/path.js'),
-    ]);
-    const state = EnvFileLoader.ensureLoaded({
-        cwd: projectRoot,
-        includeCwd: true,
-    });
-    if (state.loadedFiles.length > 0)
-        return;
-    const resolvedDotEnv = path.join(projectRoot, '.env');
-    Logger.warn('Node bootstrap started without loaded env files.', {
-        projectRoot,
-        resolvedDotEnv: existsSync(resolvedDotEnv) ? resolvedDotEnv : 'missing',
-        entry: '@zintrust/core/boot',
-    });
-};
-await ensureNodeBootstrapEnv();
+import { ensureNodeStartupEnvLoaded } from './runtime/NodeStartup.js';
+await ensureNodeStartupEnvLoaded({
+    entry: '@zintrust/core/boot',
+    warnOnMissingEnv: true,
+});
 await import('./boot/bootstrap.js');

package/src/cli/commands/StartCommand.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"StartCommand.d.ts","sourceRoot":"","sources":["../../../../src/cli/commands/StartCommand.ts"],"names":[],"mappings":"AAAA,OAAO,EAAoC,KAAK,YAAY,EAAE,MAAM,kBAAkB,CAAC;AA2+BvF,eAAO,MAAM,YAAY;cACb,YAAY;;mCAn7BU,MAAM,KAAG,OAAO;4CAaP,MAAM,KAAG,MAAM;4CA4Bf,MAAM,KAAG,OAAO;sCAetB,MAAM,WAAW,MAAM,KAAG,OAAO;oCAmBnC,MAAM,KAAG,OAAO;;EAm5BjD,CAAC"}
+{"version":3,"file":"StartCommand.d.ts","sourceRoot":"","sources":["../../../../src/cli/commands/StartCommand.ts"],"names":[],"mappings":"AAAA,OAAO,EAAoC,KAAK,YAAY,EAAE,MAAM,kBAAkB,CAAC;AAggCvF,eAAO,MAAM,YAAY;cACb,YAAY;;mCAp8BU,MAAM,KAAG,OAAO;4CAaP,MAAM,KAAG,MAAM;4CA4Bf,MAAM,KAAG,OAAO;sCAetB,MAAM,WAAW,MAAM,KAAG,OAAO;oCAmBnC,MAAM,KAAG,OAAO;;EAo6BjD,CAAC"}

package/src/cli/commands/StartCommand.js

@@ -1,6 +1,6 @@
 import { BaseCommand } from '../BaseCommand.js';
 import { withWranglerDevVarsSnapshot } from '../cloudflare/CloudflareWranglerDevEnv.js';
-import { createDenoRunnerSource, createLambdaRunnerSource } from '../commands/runner/index.js';
+import { createDenoRunnerSource, createLambdaRunnerSource, createNodeRunnerSource, } from '../commands/runner/index.js';
 import { EnvFileLoader } from '../utils/EnvFileLoader.js';
 import { SpawnUtil } from '../utils/spawn.js';
 import { readEnvString } from '../../common/ExternalServiceUtils.js';
@@ -415,17 +415,25 @@ const resolveRuntimeStartModuleSpecifier = (cwd) => {
     }
     return '@zintrust/core/start';
 };
-const resolveNodeDevCommand = (cwd, packageJson) => {
-    if (isFrameworkRepo(packageJson)) {
-        const bootstrap = resolveBootstrapEntryTs(cwd);
-        return { command: 'tsx', args: ['watch', bootstrap ?? 'src/index.ts'] };
-    }
-    const bootstrap = resolveBootstrapEntryTs(cwd);
-    if (bootstrap !== undefined) {
-        return { command: 'tsx', args: ['watch', bootstrap] };
+const resolveRuntimeCompiledStartModuleSpecifier = (cwd) => {
+    const localCompiledStart = path.join(cwd, 'dist', 'src', 'start.js');
+    if (existsSync(localCompiledStart)) {
+        return '../dist/src/start.js';
     }
-    if (existsSync(path.join(cwd, 'src/index.ts'))) {
-        return { command: 'tsx', args: ['watch', 'src/index.ts'] };
+    return '@zintrust/core/start';
+};
+const hasNodeSourceEntrypoint = (cwd) => {
+    return resolveBootstrapEntryTs(cwd) !== undefined || existsSync(path.join(cwd, 'src/index.ts'));
+};
+const ensureNodeSourceRunner = (cwd) => {
+    return ensureTmpRunnerFile(cwd, 'zin-start-node.ts', createNodeRunnerSource(resolveRuntimeStartModuleSpecifier(cwd)));
+};
+const ensureNodeCompiledRunner = (cwd) => {
+    return ensureTmpRunnerFile(cwd, 'zin-start-node.mjs', createNodeRunnerSource(resolveRuntimeCompiledStartModuleSpecifier(cwd)));
+};
+const resolveNodeDevCommand = (cwd, packageJson) => {
+    if (isFrameworkRepo(packageJson) || hasNodeSourceEntrypoint(cwd)) {
+        return { command: 'tsx', args: ['watch', ensureNodeSourceRunner(cwd)] };
     }
     // Fallback: if the app provides a dev script, run it.
     // IMPORTANT: avoid calling `npm run dev` when the dev script itself invokes `zin`/`zintrust`
@@ -440,24 +448,16 @@ const resolveNodeDevCommand = (cwd, packageJson) => {
 };
 const resolveNodeProdCommand = (cwd) => {
     const compiledBoot = path.join(cwd, 'dist/src/boot/bootstrap.js');
-    let compiled;
     if (existsSync(compiledBoot) && !runFromSource()) {
-        compiled = 'dist/src/boot/bootstrap.js';
+        return { command: 'node', args: [ensureNodeCompiledRunner(cwd)] };
     }
     // If compiled app isn't available (or the env forces running from source),
     // fall back to running the source entry with `tsx` so developers can test
     // core files with production semantics without building.
-    if (compiled === undefined) {
-        const bootstrap = resolveBootstrapEntryTs(cwd);
-        if (bootstrap !== undefined) {
-            return { command: 'tsx', args: [bootstrap] };
-        }
-        if (existsSync(path.join(cwd, 'src/index.ts'))) {
-            return { command: 'tsx', args: ['src/index.ts'] };
-        }
-        throw ErrorFactory.createCliError("Error: Compiled app not found at dist/src/boot/bootstrap.js. Run 'npm run build' first or set ZINTRUST_RUN_FROM_SOURCE=1 to run source in production.");
+    if (hasNodeSourceEntrypoint(cwd)) {
+        return { command: 'tsx', args: [ensureNodeSourceRunner(cwd)] };
     }
-    return { command: 'node', args: [compiled] };
+    throw ErrorFactory.createCliError("Error: Compiled app not found at dist/src/boot/bootstrap.js. Run 'npm run build' first or set ZINTRUST_RUN_FROM_SOURCE=1 to run source in production.");
 };
 const resolveWranglerDevConfig = (context, wranglerConfig) => {
     const normalizedConfig = typeof wranglerConfig === 'string' ? wranglerConfig.trim() : '';
@@ -612,13 +612,15 @@ const executeNodeStart = async (cmd, context, mode, watchEnabled, _port) => {
     if (mode === 'development') {
         if (!watchEnabled) {
             cmd.warn('Watch mode disabled; starting once.');
-            const bootstrap = resolveBootstrapEntryTs(context.cwd);
-            const args = bootstrap === undefined ? ['src/index.ts'] : [bootstrap];
+            const args = [ensureNodeSourceRunner(context.cwd)];
             const exitCode = await SpawnUtil.spawnAndWait({
                 command: 'tsx',
                 args,
                 forwardSignals: false,
-                env: buildStartEnv(context.projectRoot),
+                env: {
+                    ...buildStartEnv(context.projectRoot),
+                    ZINTRUST_BOOTSTRAP_PREFERENCE: 'source',
+                },
             });
             process.exit(exitCode);
         }
@@ -628,7 +630,10 @@ const executeNodeStart = async (cmd, context, mode, watchEnabled, _port) => {
             command: dev.command,
             args: dev.args,
             forwardSignals: false,
-            env: buildStartEnv(context.projectRoot),
+            env: {
+                ...buildStartEnv(context.projectRoot),
+                ZINTRUST_BOOTSTRAP_PREFERENCE: 'source',
+            },
         });
         process.exit(exitCode);
     }
@@ -638,7 +643,10 @@ const executeNodeStart = async (cmd, context, mode, watchEnabled, _port) => {
         command: prod.command,
         args: prod.args,
         forwardSignals: false,
-        env: buildStartEnv(context.projectRoot),
+        env: {
+            ...buildStartEnv(context.projectRoot),
+            ZINTRUST_BOOTSTRAP_PREFERENCE: runFromSource() ? 'source' : 'compiled',
+        },
     });
     process.exit(exitCode);
 };

package/src/cli/commands/runner/index.d.ts

@@ -1,3 +1,4 @@
 export declare const createDenoRunnerSource: (startModuleSpecifier: string) => string;
 export declare const createLambdaRunnerSource: (startModuleSpecifier: string) => string;
+export declare const createNodeRunnerSource: (startModuleSpecifier: string) => string;
 //# sourceMappingURL=index.d.ts.map

package/src/cli/commands/runner/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../../src/cli/commands/runner/index.ts"],"names":[],"mappings":"AAoJA,eAAO,MAAM,sBAAsB,GAAI,sBAAsB,MAAM,KAAG,MAErE,CAAC;AAEF,eAAO,MAAM,wBAAwB,GAAI,sBAAsB,MAAM,KAAG,MAEvE,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../../src/cli/commands/runner/index.ts"],"names":[],"mappings":"AA2JA,eAAO,MAAM,sBAAsB,GAAI,sBAAsB,MAAM,KAAG,MAErE,CAAC;AAEF,eAAO,MAAM,wBAAwB,GAAI,sBAAsB,MAAM,KAAG,MAEvE,CAAC;AAEF,eAAO,MAAM,sBAAsB,GAAI,sBAAsB,MAAM,KAAG,MAErE,CAAC"}

package/src/cli/commands/runner/index.js

@@ -142,9 +142,18 @@ const lambdaRunnerTemplate = [
     '});',
     '',
 ].join('\n');
+const nodeRunnerTemplate = [
+    `import { start } from ${START_MODULE_PLACEHOLDER};`,
+    '',
+    'await start();',
+    '',
+].join('\n');
 export const createDenoRunnerSource = (startModuleSpecifier) => {
     return injectStartModuleSpecifier(denoRunnerTemplate, startModuleSpecifier);
 };
 export const createLambdaRunnerSource = (startModuleSpecifier) => {
     return injectStartModuleSpecifier(lambdaRunnerTemplate, startModuleSpecifier);
 };
+export const createNodeRunnerSource = (startModuleSpecifier) => {
+    return injectStartModuleSpecifier(nodeRunnerTemplate, startModuleSpecifier);
+};

package/src/index.js

@@ -1,11 +1,11 @@
 /**
- * @zintrust/core v0.4.54
+ * @zintrust/core v0.4.55
  *
  * ZinTrust Framework - Production-Grade TypeScript Backend
  * Built for performance, type safety, and exceptional developer experience
  *
  * Build Information:
- *   Built: 2026-04-04T15:24:52.580Z
+ *   Built: 2026-04-04T15:47:44.856Z
  *   Node: >=20.0.0
  *   License: MIT
  *
@@ -21,7 +21,7 @@
  * Available at runtime for debugging and health checks
  */
 export const ZINTRUST_VERSION = '0.1.41';
-export const ZINTRUST_BUILD_DATE = '2026-04-04T15:24:52.546Z'; // Replaced during build
+export const ZINTRUST_BUILD_DATE = '2026-04-04T15:47:44.824Z'; // Replaced during build
 export { Application } from './boot/Application.js';
 export { AwsSigV4 } from './common/index.js';
 export { SignedRequest } from './security/SignedRequest.js';

package/src/runtime/NodeStartup.d.ts

@@ -0,0 +1,14 @@
+type NodeStartupLoadState = {
+    loadedFiles: string[];
+    mode?: string;
+};
+type EnsureNodeStartupEnvOptions = {
+    entry: string;
+    warnOnMissingEnv?: boolean;
+};
+export declare const ensureNodeStartupEnvLoaded: (options: EnsureNodeStartupEnvOptions) => Promise<NodeStartupLoadState | undefined>;
+declare const _default: Readonly<{
+    ensureNodeStartupEnvLoaded: (options: EnsureNodeStartupEnvOptions) => Promise<NodeStartupLoadState | undefined>;
+}>;
+export default _default;
+//# sourceMappingURL=NodeStartup.d.ts.map

package/src/runtime/NodeStartup.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"NodeStartup.d.ts","sourceRoot":"","sources":["../../../src/runtime/NodeStartup.ts"],"names":[],"mappings":"AAGA,KAAK,oBAAoB,GAAG;IAC1B,WAAW,EAAE,MAAM,EAAE,CAAC;IACtB,IAAI,CAAC,EAAE,MAAM,CAAC;CACf,CAAC;AAEF,KAAK,2BAA2B,GAAG;IACjC,KAAK,EAAE,MAAM,CAAC;IACd,gBAAgB,CAAC,EAAE,OAAO,CAAC;CAC5B,CAAC;AAmBF,eAAO,MAAM,0BAA0B,GACrC,SAAS,2BAA2B,KACnC,OAAO,CAAC,oBAAoB,GAAG,SAAS,CAuB1C,CAAC;;0CAxBS,2BAA2B,KACnC,OAAO,CAAC,oBAAoB,GAAG,SAAS,CAAC;;AAyB5C,wBAEG"}

package/src/runtime/NodeStartup.js

@@ -0,0 +1,39 @@
+import { isNodeRuntime } from './detectRuntime.js';
+import { resolveNodeProjectRoot } from './resolveNodeProjectRoot.js';
+let pendingNodeStartupEnv;
+const warnOnMissingEnvFiles = async (projectRoot, entry) => {
+    const [{ Logger }, { existsSync }, path] = await Promise.all([
+        import('../config/logger.js'),
+        import('../node-singletons/fs.js'),
+        import('../node-singletons/path.js'),
+    ]);
+    const resolvedDotEnv = path.join(projectRoot, '.env');
+    Logger.warn('Node bootstrap started without loaded env files.', {
+        projectRoot,
+        resolvedDotEnv: existsSync(resolvedDotEnv) ? resolvedDotEnv : 'missing',
+        entry,
+    });
+};
+export const ensureNodeStartupEnvLoaded = async (options) => {
+    if (!isNodeRuntime())
+        return undefined;
+    pendingNodeStartupEnv ??= (async () => {
+        const projectRoot = await resolveNodeProjectRoot();
+        if ((process.env?.['ZINTRUST_PROJECT_ROOT'] ?? '').trim() === '') {
+            process.env['ZINTRUST_PROJECT_ROOT'] = projectRoot;
+        }
+        const { EnvFileLoader } = await import('../cli/utils/EnvFileLoader.js');
+        const state = EnvFileLoader.ensureLoaded({
+            cwd: projectRoot,
+            includeCwd: true,
+        });
+        if (options.warnOnMissingEnv === true && state.loadedFiles.length === 0) {
+            await warnOnMissingEnvFiles(projectRoot, options.entry);
+        }
+        return state;
+    })();
+    return pendingNodeStartupEnv;
+};
+export default Object.freeze({
+    ensureNodeStartupEnvLoaded,
+});

package/src/runtime/ProjectBootstrap.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ProjectBootstrap.d.ts","sourceRoot":"","sources":["../../../src/runtime/ProjectBootstrap.ts"],"names":[],"mappings":"AAgCA,wBAAsB,oBAAoB,IAAI,OAAO,CAAC,IAAI,CAAC,CAU1D;;;;AAED,wBAEG"}
+{"version":3,"file":"ProjectBootstrap.d.ts","sourceRoot":"","sources":["../../../src/runtime/ProjectBootstrap.ts"],"names":[],"mappings":"AA2CA,wBAAsB,oBAAoB,IAAI,OAAO,CAAC,IAAI,CAAC,CAU1D;;;;AAED,wBAEG"}

package/src/runtime/ProjectBootstrap.js

@@ -8,11 +8,20 @@ const getProjectRoot = () => {
         return fromEnv.trim();
     return process.cwd();
 };
-const getBootstrapCandidates = (projectRoot) => [
-    path.join(projectRoot, 'src', 'boot', 'bootstrap.ts'),
-    path.join(projectRoot, 'dist', 'src', 'boot', 'bootstrap.js'),
-    path.join(projectRoot, 'src', 'boot', 'bootstrap.js'),
-];
+const getBootstrapPreference = () => {
+    const raw = process.env?.['ZINTRUST_BOOTSTRAP_PREFERENCE'] ?? '';
+    return raw.trim().toLowerCase() === 'compiled' ? 'compiled' : 'source';
+};
+const getBootstrapCandidates = (projectRoot) => {
+    const sourceCandidates = [
+        path.join(projectRoot, 'src', 'boot', 'bootstrap.ts'),
+        path.join(projectRoot, 'src', 'boot', 'bootstrap.js'),
+    ];
+    const compiledCandidate = path.join(projectRoot, 'dist', 'src', 'boot', 'bootstrap.js');
+    return getBootstrapPreference() === 'compiled'
+        ? [compiledCandidate, ...sourceCandidates]
+        : [sourceCandidates[0], compiledCandidate, sourceCandidates[1]];
+};
 const tryImportBootstrapCandidate = async (candidate) => {
     if (!existsSync(candidate))
         return false;

package/src/start.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"start.d.ts","sourceRoot":"","sources":["../../src/start.ts"],"names":[],"mappings":"AAGA,OAAO,EAEL,KAAK,oBAAoB,EAC1B,MAAM,gCAAgC,CAAC;AAwBxC,eAAO,MAAM,UAAU,GAAI,eAAe,MAAM,KAAG,OAYlD,CAAC;AAEF,eAAO,MAAM,0BAA0B,GAAI,eAAe,OAAO,KAAG,oBASnE,CAAC;AAoEF,eAAO,MAAM,qBAAqB,GAChC,eAAe,MAAM,EACrB,eAAe,OAAO,KACrB,OAAO,CAAC,oBAAoB,CAS9B,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,KAAK,QAAa,OAAO,CAAC,IAAI,CAO1C,CAAC;AAEF;;GAEG;AACH,OAAO,EAAE,OAAO,EAAE,MAAM,uBAAuB,CAAC;AAEhD,OAAO,EAAE,OAAO,IAAI,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AAEpE;;GAEG;AACH,OAAO,EAAE,OAAO,IAAI,IAAI,EAAE,MAAM,iBAAiB,CAAC;AAElD;;GAEG;AACH,OAAO,EAAE,OAAO,EAAE,MAAM,mBAAmB,CAAC"}
+{"version":3,"file":"start.d.ts","sourceRoot":"","sources":["../../src/start.ts"],"names":[],"mappings":"AAGA,OAAO,EAEL,KAAK,oBAAoB,EAC1B,MAAM,gCAAgC,CAAC;AAyBxC,eAAO,MAAM,UAAU,GAAI,eAAe,MAAM,KAAG,OAYlD,CAAC;AAEF,eAAO,MAAM,0BAA0B,GAAI,eAAe,OAAO,KAAG,oBASnE,CAAC;AAoEF,eAAO,MAAM,qBAAqB,GAChC,eAAe,MAAM,EACrB,eAAe,OAAO,KACrB,OAAO,CAAC,oBAAoB,CAS9B,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,KAAK,QAAa,OAAO,CAAC,IAAI,CAW1C,CAAC;AAEF;;GAEG;AACH,OAAO,EAAE,OAAO,EAAE,MAAM,uBAAuB,CAAC;AAEhD,OAAO,EAAE,OAAO,IAAI,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AAEpE;;GAEG;AACH,OAAO,EAAE,OAAO,IAAI,IAAI,EAAE,MAAM,iBAAiB,CAAC;AAElD;;GAEG;AACH,OAAO,EAAE,OAAO,EAAE,MAAM,mBAAmB,CAAC"}

package/src/start.js

@@ -2,6 +2,7 @@ import { ErrorFactory } from './exceptions/ZintrustError.js';
 import { isArray, isNonEmptyString, isObject } from './helper/index.js';
 import { ZintrustLang } from './lang/lang.js';
 import { normalizeActiveServiceRuntime, } from './microservices/ServiceManifest.js';
+import { ensureNodeStartupEnvLoaded } from './runtime/NodeStartup.js';
 import { ProjectRuntime } from './runtime/ProjectRuntime.js';
 import { resolveNodeProjectRoot } from './runtime/resolveNodeProjectRoot.js';
 import { isNodeRuntime } from './runtime/detectRuntime.js';
@@ -97,6 +98,9 @@ export const bootStandaloneService = async (importMetaUrl, activeService) => {
 export const start = async () => {
     if (!isNodeRuntime())
         return;
+    await ensureNodeStartupEnvLoaded({
+        entry: '@zintrust/core/start',
+    });
     const projectBootstrapModule = (await import('./runtime/ProjectBootstrap.js'));
     await projectBootstrapModule.loadProjectBootstrap();
 };