@zintrust/core 0.1.19 → 0.1.21

package/src/runtime/PluginManager.js

@@ -1,14 +1,13 @@
 /* eslint-disable @typescript-eslint/require-await */
-/* eslint-disable no-await-in-loop */
 /**
  * Plugin Manager
  * Handles installation and removal of framework plugins.
  */
+import { execSync } from '../node-singletons/child-process.js';
 import { SpawnUtil } from '../cli/utils/spawn.js';
 import { esmDirname, resolvePackageManager } from '../common/index.js';
 import { Logger } from '../config/logger.js';
 import { ErrorFactory } from '../exceptions/ZintrustError.js';
-import { execSync } from '../node-singletons/child-process.js';
 import { existsSync, fsPromises as fs } from '../node-singletons/fs.js';
 import * as path from '../node-singletons/path.js';
 import { PluginRegistry } from './PluginRegistry.js';
@@ -88,6 +87,21 @@ async function npmInstall(packages, options) {
     Logger.info(`Installing ${options.label}: ${packages.join(', ')}...`);
     const projectRoot = options.projectRoot ?? resolveProjectRoot();
     const pm = options.packageManager ?? resolvePackageManager();
+    // Legacy behavior: npm uses execSync in this framework.
+    // This keeps behavior predictable for CI/test environments and matches existing unit tests.
+    if (pm === 'npm') {
+        const cmd = options.dev
+            ? `npm install -D ${packages.join(' ')}`
+            : `npm install ${packages.join(' ')}`;
+        try {
+            execSync(cmd, { cwd: projectRoot, stdio: 'inherit' });
+            return;
+        }
+        catch (error) {
+            ErrorFactory.createCliError(`Failed to install ${options.label}`, { error });
+            throw error;
+        }
+    }
     let cmd;
     let args = [];
     switch (pm) {
@@ -106,20 +120,12 @@ async function npmInstall(packages, options) {
             break;
     }
     try {
-        if (pm === 'npm') {
-            // Preserve legacy execSync behavior for npm so integration tests and simple CLI usage behave identically
-            const cmdStr = options.dev
-                ? `npm install -D ${packages.join(' ')}`
-                : `npm install ${packages.join(' ')}`; // NOSONAR
-            execSync(cmdStr, { stdio: 'inherit', cwd: projectRoot });
-        }
-        else {
-            const exit = await SpawnUtil.spawnAndWait({ command: cmd, args, cwd: projectRoot });
-            if (exit !== 0) {
-                throw ErrorFactory.createCliError(`Package manager ${pm} failed to install ${options.label}`, {
-                    exit,
-                });
-            }
+        // Use async spawn for all package managers to avoid blocking event loop
+        const exit = await SpawnUtil.spawnAndWait({ command: cmd, args, cwd: projectRoot });
+        if (exit !== 0) {
+            throw ErrorFactory.createCliError(`Package manager ${pm} failed to install ${options.label}`, {
+                exit,
+            });
         }
     }
     catch (error) {
@@ -130,7 +136,8 @@ async function npmInstall(packages, options) {
 async function copyPluginTemplates(plugin) {
     const templateRoot = resolveTemplateRootOrThrow();
     const projectRoot = resolveProjectRoot();
-    for (const template of plugin.templates) {
+    // Parallelize file operations using Promise.all
+    await Promise.all(plugin.templates.map(async (template) => {
         const sourcePath = path.join(templateRoot, template.source);
         const destPath = path.join(projectRoot, template.destination);
         // Prevent path traversal: resolved destination must be within project root
@@ -154,7 +161,7 @@ async function copyPluginTemplates(plugin) {
             ErrorFactory.createCliError(`Failed to copy template ${template.source}`, { error });
             throw error;
         }
-    }
+    }));
 }
 async function ensurePluginAutoImports(plugin) {
     const rawImports = plugin.autoImports;

package/src/runtime/RuntimeDetector.d.ts

@@ -1,4 +1,4 @@
-import { AdapterConfig, RuntimeAdapter, ZintrustHandler } from './RuntimeAdapter';
+import type { AdapterConfig, RuntimeAdapter, ZintrustHandler } from './RuntimeAdapter';
 export declare const RuntimeDetector: Readonly<{
     RUNTIME_VAR: "RUNTIME";
     AUTO: "auto";

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

@@ -1 +1 @@
-{"version":3,"file":"RuntimeDetector.d.ts","sourceRoot":"","sources":["../../../src/runtime/RuntimeDetector.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,aAAa,EAAE,cAAc,EAAE,eAAe,EAAE,MAAM,yBAAyB,CAAC;AAkKzF,eAAO,MAAM,eAAe;;;yBA9GF,MAAM;4BAyBD,aAAa,KAAG,cAAc;uCAQnB,MAAM,UAAU,aAAa,KAAG,cAAc;0BAuD7D,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;EA6BhD,CAAC;AA8IH,eAAO,MAAM,oBAAoB;0BAtGE,eAAe,KAAG,OAAO,CAAC,IAAI,CAAC;wBA0DlC,MAAM,KAAe,OAAO,CAAC,IAAI,CAAC;iCAmChC,IAAI;EAapC,CAAC"}
+{"version":3,"file":"RuntimeDetector.d.ts","sourceRoot":"","sources":["../../../src/runtime/RuntimeDetector.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,aAAa,EAAE,cAAc,EAAE,eAAe,EAAE,MAAM,yBAAyB,CAAC;AAkK9F,eAAO,MAAM,eAAe;;;yBA9GF,MAAM;4BAyBD,aAAa,KAAG,cAAc;uCAQnB,MAAM,UAAU,aAAa,KAAG,cAAc;0BAuD7D,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;EA6BhD,CAAC;AA8IH,eAAO,MAAM,oBAAoB;0BAtGE,eAAe,KAAG,OAAO,CAAC,IAAI,CAAC;wBA0DlC,MAAM,KAAe,OAAO,CAAC,IAAI,CAAC;iCAmChC,IAAI;EAapC,CAAC"}

package/src/runtime/StartupConfigFileRegistry.d.ts

@@ -0,0 +1,20 @@
+export declare enum StartupConfigFile {
+    Broadcast = "config/broadcast.ts",
+    Cache = "config/cache.ts",
+    Database = "config/database.ts",
+    Mail = "config/mail.ts",
+    Middleware = "config/middleware.ts",
+    Notification = "config/notification.ts",
+    Queue = "config/queue.ts",
+    Storage = "config/storage.ts"
+}
+export declare const StartupConfigFileRegistry: Readonly<{
+    preload(files: readonly StartupConfigFile[]): Promise<void>;
+    isPreloaded(): boolean;
+    get<T>(file: StartupConfigFile): T | undefined;
+    has(file: StartupConfigFile): boolean;
+    /** Intended for tests only. */
+    clear(): void;
+}>;
+export default StartupConfigFileRegistry;
+//# sourceMappingURL=StartupConfigFileRegistry.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"StartupConfigFileRegistry.d.ts","sourceRoot":"","sources":["../../../src/runtime/StartupConfigFileRegistry.ts"],"names":[],"mappings":"AAEA,oBAAY,iBAAiB;IAC3B,SAAS,wBAAwB;IACjC,KAAK,oBAAoB;IACzB,QAAQ,uBAAuB;IAC/B,IAAI,mBAAmB;IACvB,UAAU,yBAAyB;IACnC,YAAY,2BAA2B;IACvC,KAAK,oBAAoB;IACzB,OAAO,sBAAsB;CAC9B;AAKD,eAAO,MAAM,yBAAyB;mBACf,SAAS,iBAAiB,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC;mBAelD,OAAO;QAIlB,CAAC,QAAQ,iBAAiB,GAAG,CAAC,GAAG,SAAS;cAIpC,iBAAiB,GAAG,OAAO;IAIrC,+BAA+B;aACtB,IAAI;EAIb,CAAC;AAEH,eAAe,yBAAyB,CAAC"}

package/src/runtime/StartupConfigFileRegistry.js

@@ -0,0 +1,44 @@
+import useFileLoader from '../runtime/useFileLoader.js';
+export var StartupConfigFile;
+(function (StartupConfigFile) {
+    StartupConfigFile["Broadcast"] = "config/broadcast.ts";
+    StartupConfigFile["Cache"] = "config/cache.ts";
+    StartupConfigFile["Database"] = "config/database.ts";
+    StartupConfigFile["Mail"] = "config/mail.ts";
+    StartupConfigFile["Middleware"] = "config/middleware.ts";
+    StartupConfigFile["Notification"] = "config/notification.ts";
+    StartupConfigFile["Queue"] = "config/queue.ts";
+    StartupConfigFile["Storage"] = "config/storage.ts";
+})(StartupConfigFile || (StartupConfigFile = {}));
+const cache = new Map();
+let preloaded = false;
+export const StartupConfigFileRegistry = Object.freeze({
+    async preload(files) {
+        const tasks = files.map(async (file) => {
+            const loader = useFileLoader(file);
+            if (!loader.exists()) {
+                cache.delete(file);
+                return;
+            }
+            const value = await loader.get();
+            cache.set(file, value);
+        });
+        await Promise.all(tasks);
+        preloaded = true;
+    },
+    isPreloaded() {
+        return preloaded;
+    },
+    get(file) {
+        return cache.get(file);
+    },
+    has(file) {
+        return cache.has(file);
+    },
+    /** Intended for tests only. */
+    clear() {
+        cache.clear();
+        preloaded = false;
+    },
+});
+export default StartupConfigFileRegistry;

package/src/runtime/adapters/CloudflareAdapter.d.ts

@@ -1,4 +1,4 @@
-import { AdapterConfig, RuntimeAdapter } from '../RuntimeAdapter';
+import type { AdapterConfig, RuntimeAdapter } from '../RuntimeAdapter';
 /**
  * Cloudflare Workers adapter for Cloudflare's edge compute platform
  * Uses fetch API and handles D1 database, KV storage bindings

package/src/runtime/adapters/CloudflareAdapter.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"CloudflareAdapter.d.ts","sourceRoot":"","sources":["../../../../src/runtime/adapters/CloudflareAdapter.ts"],"names":[],"mappings":"AAMA,OAAO,EACL,aAAa,EAMb,cAAc,EACf,MAAM,yBAAyB,CAAC;AAEjC;;;;GAIG;AACH,eAAO,MAAM,iBAAiB;IAC5B;;OAEG;mBACY,aAAa,GAAG,cAAc;IAoD7C;;;OAGG;qBACc,OAAO;IAKxB;;;OAGG;qBACc,MAAM,GAAG,OAAO;EAIjC,CAAC;AA4IH;;;;GAIG;AACH,MAAM,WAAW,iBAAkB,SAAQ,OAAO;IAChD,GAAG,EAAE,MAAM,CAAC;IACZ,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,OAAO,CAAC;IACjB,IAAI,EAAE,cAAc,CAAC,UAAU,CAAC,CAAC;IACjC,EAAE,CAAC,EAAE;QACH,IAAI,CAAC,EAAE,MAAM,CAAC;QACd,OAAO,CAAC,EAAE,MAAM,CAAC;QACjB,YAAY,CAAC,EAAE,MAAM,CAAC;QACtB,QAAQ,CAAC,EAAE,MAAM,CAAC;QAClB,SAAS,CAAC,EAAE,MAAM,CAAC;QACnB,UAAU,CAAC,EAAE,MAAM,CAAC;QACpB,eAAe,CAAC,EAAE,MAAM,CAAC;KAC1B,CAAC;CACH"}
+{"version":3,"file":"CloudflareAdapter.d.ts","sourceRoot":"","sources":["../../../../src/runtime/adapters/CloudflareAdapter.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EACV,aAAa,EAGb,cAAc,EAAC,MAAM,yBAAyB,CAAC;AAOjD;;;;GAIG;AACH,eAAO,MAAM,iBAAiB;IAC5B;;OAEG;mBACY,aAAa,GAAG,cAAc;IAoD7C;;;OAGG;qBACc,OAAO;IAKxB;;;OAGG;qBACc,MAAM,GAAG,OAAO;EAIjC,CAAC;AA4IH;;;;GAIG;AACH,MAAM,WAAW,iBAAkB,SAAQ,OAAO;IAChD,GAAG,EAAE,MAAM,CAAC;IACZ,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,OAAO,CAAC;IACjB,IAAI,EAAE,cAAc,CAAC,UAAU,CAAC,CAAC;IACjC,EAAE,CAAC,EAAE;QACH,IAAI,CAAC,EAAE,MAAM,CAAC;QACd,OAAO,CAAC,EAAE,MAAM,CAAC;QACjB,YAAY,CAAC,EAAE,MAAM,CAAC;QACtB,QAAQ,CAAC,EAAE,MAAM,CAAC;QAClB,SAAS,CAAC,EAAE,MAAM,CAAC;QACnB,UAAU,CAAC,EAAE,MAAM,CAAC;QACpB,eAAe,CAAC,EAAE,MAAM,CAAC;KAC1B,CAAC;CACH"}

package/src/runtime/adapters/CloudflareAdapter.js

@@ -3,7 +3,7 @@
  */
 import { appConfig } from '../../config/index.js';
 import { Logger } from '../../config/logger.js';
-import { createMockHttpObjects, ErrorResponse, HttpResponse, } from '../RuntimeAdapter.js';
+import { createMockHttpObjects, ErrorResponse, HttpResponse } from '../RuntimeAdapter.js';
 /**
  * Cloudflare Workers adapter for Cloudflare's edge compute platform
  * Uses fetch API and handles D1 database, KV storage bindings

package/src/runtime/adapters/DenoAdapter.d.ts

@@ -1,4 +1,4 @@
-import { AdapterConfig, RuntimeAdapter } from '../RuntimeAdapter';
+import type { AdapterConfig, RuntimeAdapter } from '../RuntimeAdapter';
 /**
  * Deno runtime adapter for Deno Deploy and edge compute environments
  * Sealed namespace for immutability

package/src/runtime/adapters/DenoAdapter.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"DenoAdapter.d.ts","sourceRoot":"","sources":["../../../../src/runtime/adapters/DenoAdapter.ts"],"names":[],"mappings":"AAKA,OAAO,EACL,aAAa,EAKb,cAAc,EACf,MAAM,yBAAyB,CAAC;AAEjC;;;GAGG;AACH,eAAO,MAAM,WAAW;IACtB;;OAEG;mBACY,aAAa,GAAG,cAAc,GAAG;QAC9C,WAAW,CAAC,IAAI,CAAC,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;KAC1D;IAwDD;;OAEG;yBAEQ,cAAc,SACjB,MAAM,SACN,MAAM,GACX,OAAO,CAAC,IAAI,CAAC;IAQhB;;OAEG;aACY,OAAO,CAAC,OAAO,CAAC;IAK/B;;OAEG;mBACY,MAAM,iBAAiB,MAAM,GAAG,MAAM;IAKrD;;OAEG;2BACoB,OAAO;EAI9B,CAAC"}
+{"version":3,"file":"DenoAdapter.d.ts","sourceRoot":"","sources":["../../../../src/runtime/adapters/DenoAdapter.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EACV,aAAa,EAGb,cAAc,EAAC,MAAM,yBAAyB,CAAC;AAMjD;;;GAGG;AACH,eAAO,MAAM,WAAW;IACtB;;OAEG;mBACY,aAAa,GAAG,cAAc,GAAG;QAC9C,WAAW,CAAC,IAAI,CAAC,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;KAC1D;IAwDD;;OAEG;yBAEQ,cAAc,SACjB,MAAM,SACN,MAAM,GACX,OAAO,CAAC,IAAI,CAAC;IAQhB;;OAEG;aACY,OAAO,CAAC,OAAO,CAAC;IAK/B;;OAEG;mBACY,MAAM,iBAAiB,MAAM,GAAG,MAAM;IAKrD;;OAEG;2BACoB,OAAO;EAI9B,CAAC"}

package/src/runtime/adapters/DenoAdapter.js

@@ -2,7 +2,7 @@
  * Runtime adapter for Deno
  */
 import Logger from '../../config/logger.js';
-import { createMockHttpObjects, ErrorResponse, } from '../RuntimeAdapter.js';
+import { createMockHttpObjects, ErrorResponse } from '../RuntimeAdapter.js';
 /**
  * Deno runtime adapter for Deno Deploy and edge compute environments
  * Sealed namespace for immutability

package/src/runtime/adapters/LambdaAdapter.d.ts

@@ -1,4 +1,4 @@
-import { AdapterConfig, RuntimeAdapter } from '../RuntimeAdapter';
+import type { AdapterConfig, RuntimeAdapter } from '../RuntimeAdapter';
 /**
  * AWS Lambda adapter for API Gateway and ALB events
  * Converts Lambda events to standard HTTP format for Zintrust framework

package/src/runtime/adapters/LambdaAdapter.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"LambdaAdapter.d.ts","sourceRoot":"","sources":["../../../../src/runtime/adapters/LambdaAdapter.ts"],"names":[],"mappings":"AAYA,OAAO,EACL,aAAa,EAKb,cAAc,EACf,MAAM,yBAAyB,CAAC;AAEjC;;;;GAIG;AACH,eAAO,MAAM,aAAa;IACxB;;OAEG;mBACY,aAAa,GAAG,cAAc;EA8D7C,CAAC"}
+{"version":3,"file":"LambdaAdapter.d.ts","sourceRoot":"","sources":["../../../../src/runtime/adapters/LambdaAdapter.ts"],"names":[],"mappings":"AAYA,OAAO,KAAK,EACV,aAAa,EAGb,cAAc,EAAC,MAAM,yBAAyB,CAAC;AAMjD;;;;GAIG;AACH,eAAO,MAAM,aAAa;IACxB;;OAEG;mBACY,aAAa,GAAG,cAAc;EA8D7C,CAAC"}

package/src/runtime/adapters/LambdaAdapter.js

@@ -4,7 +4,7 @@
 import { Env } from '../../config/env.js';
 import { Logger } from '../../config/logger.js';
 import { IncomingMessage, ServerResponse, } from '../../node-singletons/http.js';
-import { ErrorResponse, HttpResponse, } from '../RuntimeAdapter.js';
+import { ErrorResponse, HttpResponse } from '../RuntimeAdapter.js';
 /**
  * AWS Lambda adapter for API Gateway and ALB events
  * Converts Lambda events to standard HTTP format for Zintrust framework

package/src/runtime/adapters/NodeServerAdapter.d.ts

@@ -1,4 +1,4 @@
-import { AdapterConfig, RuntimeAdapter } from '../RuntimeAdapter';
+import type { AdapterConfig, RuntimeAdapter } from '../RuntimeAdapter';
 /**
  * Node.js HTTP Server adapter for standard containers and traditional servers
  * Uses Node.js built-in HTTP server for maximum compatibility

package/src/runtime/adapters/NodeServerAdapter.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"NodeServerAdapter.d.ts","sourceRoot":"","sources":["../../../../src/runtime/adapters/NodeServerAdapter.ts"],"names":[],"mappings":"AAIA,OAAO,EACL,aAAa,EAGb,cAAc,EACf,MAAM,yBAAyB,CAAC;AAEjC;;;;GAIG;AACH,eAAO,MAAM,iBAAiB;IAC5B;;OAEG;mBACY,aAAa,GAAG,cAAc,GAAG;QAC9C,WAAW,CAAC,IAAI,CAAC,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;QACzD,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;KACvB;EAoED,CAAC"}
+{"version":3,"file":"NodeServerAdapter.d.ts","sourceRoot":"","sources":["../../../../src/runtime/adapters/NodeServerAdapter.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EACV,aAAa,EAGb,cAAc,EACf,MAAM,yBAAyB,CAAC;AAEjC;;;;GAIG;AACH,eAAO,MAAM,iBAAiB;IAC5B;;OAEG;mBACY,aAAa,GAAG,cAAc,GAAG;QAC9C,WAAW,CAAC,IAAI,CAAC,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;QACzD,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;KACvB;EAoED,CAAC"}

package/src/runtime/getKernel.d.ts

@@ -0,0 +1,9 @@
+import type { IKernel } from '../http/Kernel';
+export declare function getKernel(): Promise<IKernel>;
+/**
+ * Test-only helper.
+ *
+ * Allows unit tests to reset the singleton between cases without leaking state.
+ */
+export declare function __resetKernelForTests(): void;
+//# sourceMappingURL=getKernel.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"getKernel.d.ts","sourceRoot":"","sources":["../../../src/runtime/getKernel.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AAK5C,wBAAsB,SAAS,IAAI,OAAO,CAAC,OAAO,CAAC,CAkBlD;AAED;;;;GAIG;AACH,wBAAgB,qBAAqB,IAAI,IAAI,CAE5C"}

package/src/runtime/getKernel.js

@@ -0,0 +1,27 @@
+import { Application } from '../boot/Application.js';
+import { Kernel } from '../http/Kernel.js';
+let kernelPromise = null;
+export async function getKernel() {
+    if (kernelPromise !== null) {
+        return kernelPromise;
+    }
+    const initialize = async () => {
+        const app = Application.create();
+        await app.boot();
+        return Kernel.create(app.getRouter(), app.getContainer());
+    };
+    kernelPromise = initialize().catch((error) => {
+        // Allow retry on subsequent calls if initialization fails.
+        kernelPromise = null;
+        throw error;
+    });
+    return kernelPromise;
+}
+/**
+ * Test-only helper.
+ *
+ * Allows unit tests to reset the singleton between cases without leaking state.
+ */
+export function __resetKernelForTests() {
+    kernelPromise = null;
+}

package/src/runtime/useFileLoader.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Project file loader
+ *
+ * Loads project-owned files (typically config modules) from the project root.
+ *
+ * Usage:
+ *  - useFileLoader('config/mail.ts').get<TypeMail>()
+ *  - useFileLoader('config', 'mail.ts').get<TypeMail>()
+ */
+export type FileLoader = Readonly<{
+    /** Absolute filesystem candidates (in resolution order). */
+    candidates: () => readonly string[];
+    /** Returns the first existing candidate path (or the first candidate if none exist). */
+    path: () => string;
+    /** Whether any candidate exists on disk. */
+    exists: () => boolean;
+    /**
+     * Loads the file via ESM dynamic import and returns:
+     * - `default` export when present
+     * - otherwise the full module namespace object
+     */
+    get: <T = unknown>() => Promise<T>;
+}>;
+export declare const useFileLoader: (...args: [string] | [string, ...string[]]) => FileLoader;
+export default useFileLoader;
+//# sourceMappingURL=useFileLoader.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"useFileLoader.d.ts","sourceRoot":"","sources":["../../../src/runtime/useFileLoader.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAUH,MAAM,MAAM,UAAU,GAAG,QAAQ,CAAC;IAChC,4DAA4D;IAC5D,UAAU,EAAE,MAAM,SAAS,MAAM,EAAE,CAAC;IACpC,wFAAwF;IACxF,IAAI,EAAE,MAAM,MAAM,CAAC;IACnB,4CAA4C;IAC5C,MAAM,EAAE,MAAM,OAAO,CAAC;IACtB;;;;OAIG;IACH,GAAG,EAAE,CAAC,CAAC,GAAG,OAAO,OAAO,OAAO,CAAC,CAAC,CAAC,CAAC;CACpC,CAAC,CAAC;AAyIH,eAAO,MAAM,aAAa,GAAI,GAAG,MAAM,CAAC,MAAM,CAAC,GAAG,CAAC,MAAM,EAAE,GAAG,MAAM,EAAE,CAAC,KAAG,UA+DzE,CAAC;AAEF,eAAe,aAAa,CAAC"}

package/src/runtime/useFileLoader.js

@@ -0,0 +1,188 @@
+/**
+ * Project file loader
+ *
+ * Loads project-owned files (typically config modules) from the project root.
+ *
+ * Usage:
+ *  - useFileLoader('config/mail.ts').get<TypeMail>()
+ *  - useFileLoader('config', 'mail.ts').get<TypeMail>()
+ */
+import { ErrorFactory } from '../exceptions/ZintrustError.js';
+import { existsSync } from '../node-singletons/fs.js';
+import pathModule, { extname, join, resolve, sep } from '../node-singletons/path.js';
+import processModule from '../node-singletons/process.js';
+import { pathToFileURL } from '../node-singletons/url.js';
+const resolveProjectRoot = () => {
+    const isTestRuntime = () => {
+        const nodeEnv = processModule.env?.['NODE_ENV'];
+        const isVitest = processModule.env?.['VITEST'] !== undefined ||
+            processModule.env?.['VITEST_WORKER_ID'] !== undefined ||
+            processModule.env?.['VITEST_POOL_ID'] !== undefined;
+        return nodeEnv === 'testing' || isVitest;
+    };
+    const isCoreRepo = (cwdPath) => {
+        const fromNpm = processModule.env?.['npm_package_name'];
+        if (fromNpm === '@zintrust/core')
+            return true;
+        // Vitest suites (notably CoverageBoost) may mock `@node-singletons/fs` to return
+        // `existsSync() === true` for everything and `readFileSync() === '{}'`, which makes
+        // any package.json-based detection unreliable. Instead, detect a core repo checkout
+        // by checking whether this module is being executed from within the current cwd.
+        // - core repo tests: import.meta.url points into `<cwd>/src/...`
+        // - consumer apps: import.meta.url points into `node_modules/@zintrust/core/...`
+        try {
+            const cwdAbs = resolve(cwdPath);
+            const selfUrl = new URL(import.meta.url);
+            const selfPath = decodeURIComponent(selfUrl.pathname);
+            const selfAbs = resolve(selfPath);
+            return selfAbs === cwdAbs || selfAbs.startsWith(cwdAbs + sep);
+        }
+        catch {
+            return false;
+        }
+    };
+    const fromEnv = processModule.env?.['ZINTRUST_PROJECT_ROOT'];
+    if (typeof fromEnv === 'string' && fromEnv.trim().length > 0)
+        return fromEnv.trim();
+    const cwd = processModule.cwd();
+    // In the ZinTrust core repo, `config/*.ts` are templates (not consumer app config).
+    // During core test runs, we avoid auto-loading them to prevent unexpected overrides.
+    // In normal runs, keep the historical behavior (projectRoot = cwd).
+    if (isCoreRepo(cwd) && isTestRuntime()) {
+        return resolve(cwd, '.zintrust-internal-project-root');
+    }
+    return cwd;
+};
+const isInternalProjectRoot = (projectRoot) => pathModule.basename(projectRoot) === '.zintrust-internal-project-root';
+const normalizeProjectRelativePath = (raw) => {
+    const value = String(raw ?? '').trim();
+    if (value.length === 0) {
+        throw ErrorFactory.createConfigError('useFileLoader() requires a non-empty path');
+    }
+    if (value.includes('\u0000')) {
+        throw ErrorFactory.createSecurityError('Invalid file path (null byte)');
+    }
+    const normalized = value.replaceAll('\\', '/').replace(/^\.\/+/, '');
+    if (pathModule.isAbsolute(normalized)) {
+        throw ErrorFactory.createSecurityError('Absolute paths are not allowed', { requested: value });
+    }
+    return normalized;
+};
+const resolveWithinProjectRoot = (projectRoot, relativePath) => {
+    const rootAbs = resolve(projectRoot);
+    const candidateAbs = resolve(projectRoot, relativePath);
+    if (candidateAbs === rootAbs)
+        return candidateAbs;
+    if (!candidateAbs.startsWith(rootAbs + sep)) {
+        throw ErrorFactory.createSecurityError('Invalid file path (path traversal detected)', {
+            projectRoot: rootAbs,
+            requested: relativePath,
+            resolved: candidateAbs,
+        });
+    }
+    return candidateAbs;
+};
+const replaceExtension = (filePath, nextExt) => {
+    const current = extname(filePath);
+    if (current.length === 0)
+        return `${filePath}${nextExt}`;
+    return filePath.slice(0, -current.length) + nextExt;
+};
+const unique = (items) => {
+    const seen = new Set();
+    const out = [];
+    for (const item of items) {
+        if (seen.has(item))
+            continue;
+        seen.add(item);
+        out.push(item);
+    }
+    return out;
+};
+const buildCandidateAbsolutePaths = (projectRoot, relativePath) => {
+    const ext = extname(relativePath);
+    const baseRelCandidates = unique([
+        relativePath,
+        ...(ext.length === 0
+            ? [`${relativePath}.ts`, `${relativePath}.js`, `${relativePath}.mjs`]
+            : []),
+        ...(ext === '.ts'
+            ? [replaceExtension(relativePath, '.js'), replaceExtension(relativePath, '.mjs')]
+            : []),
+        ...(ext === '.js'
+            ? [replaceExtension(relativePath, '.mjs'), replaceExtension(relativePath, '.ts')]
+            : []),
+        ...(ext === '.mjs'
+            ? [replaceExtension(relativePath, '.js'), replaceExtension(relativePath, '.ts')]
+            : []),
+    ]);
+    const absCandidates = baseRelCandidates.flatMap((rel) => [
+        resolveWithinProjectRoot(projectRoot, rel),
+        resolveWithinProjectRoot(projectRoot, join('dist', rel)),
+    ]);
+    return unique(absCandidates);
+};
+const importModule = async (filePath) => {
+    const url = pathToFileURL(filePath).href;
+    return (await import(url));
+};
+export const useFileLoader = (...args) => {
+    const relativePath = args.length === 1
+        ? normalizeProjectRelativePath(args[0])
+        : normalizeProjectRelativePath(args.join('/'));
+    const projectRoot = resolveProjectRoot();
+    const isInternalRoot = isInternalProjectRoot(projectRoot);
+    const candidates = buildCandidateAbsolutePaths(projectRoot, relativePath);
+    // The core repo uses `.zintrust-internal-project-root` as a sentinel during core test runs.
+    // In this mode, we must *never* import project config templates.
+    // This also avoids test suites that mock `existsSync()` globally (e.g. CoverageBoost).
+    const exists = () => (isInternalRoot ? false : candidates.some((c) => existsSync(c)));
+    const resolveFirstExistingPath = () => {
+        if (isInternalRoot)
+            return candidates[0] ?? resolveWithinProjectRoot(projectRoot, relativePath);
+        for (const candidate of candidates) {
+            if (existsSync(candidate))
+                return candidate;
+        }
+        return candidates[0] ?? resolveWithinProjectRoot(projectRoot, relativePath);
+    };
+    const get = async () => {
+        if (isInternalRoot) {
+            throw ErrorFactory.createNotFoundError('Project file not found', {
+                projectRoot,
+                relativePath,
+                candidates,
+            });
+        }
+        const candidate = candidates.find((c) => existsSync(c));
+        if (candidate === undefined) {
+            throw ErrorFactory.createNotFoundError('Project file not found', {
+                projectRoot,
+                relativePath,
+                candidates,
+            });
+        }
+        try {
+            const mod = await importModule(candidate);
+            if (Object.hasOwn(mod, 'default') && mod.default !== undefined) {
+                return mod.default;
+            }
+            return mod;
+        }
+        catch (error) {
+            throw ErrorFactory.createTryCatchError('Failed to import project file', {
+                candidate,
+                projectRoot,
+                relativePath,
+                error,
+            });
+        }
+    };
+    return Object.freeze({
+        candidates: () => candidates,
+        path: resolveFirstExistingPath,
+        exists,
+        get,
+    });
+};
+export default useFileLoader;

package/src/scripts/TemplateImportsCheck.js

@@ -1,5 +1,6 @@
 import * as fs from 'node:fs';
 import * as path from 'node:path';
+import ts from 'typescript';
 const TEMPLATES_ROOT = path.resolve(process.cwd(), 'src/templates');
 const bannedPrefixes = [
     '@exceptions/',
@@ -79,6 +80,29 @@ function checkFile(filePath) {
     }
     return offenses;
 }
+function looksLikeTypeScriptTemplate(text) {
+    // Only attempt TS parsing when the template appears to contain TS module syntax.
+    // Many templates are not TS (markdown/env/etc.) and should not be validated this way.
+    return /\b(import|export)\b/.test(text);
+}
+function getTypeScriptSyntaxErrors(filePath) {
+    const text = fs.readFileSync(filePath, 'utf8');
+    if (!looksLikeTypeScriptTemplate(text))
+        return [];
+    const sourceFile = ts.createSourceFile(filePath, text, ts.ScriptTarget.ESNext, true, ts.ScriptKind.TS);
+    const diagnostics = sourceFile
+        .parseDiagnostics;
+    if (!diagnostics || diagnostics.length === 0)
+        return [];
+    const out = [];
+    for (const d of diagnostics) {
+        const message = ts.flattenDiagnosticMessageText(d.messageText, '\n');
+        const pos = typeof d.start === 'number' ? d.start : 0;
+        const { line } = sourceFile.getLineAndCharacterOfPosition(pos);
+        out.push({ line: line + 1, message });
+    }
+    return out;
+}
 function main() {
     if (!fs.existsSync(TEMPLATES_ROOT)) {
         process.stderr.write(`Templates root not found: ${TEMPLATES_ROOT}\n`);
@@ -86,6 +110,7 @@ function main() {
     }
     const files = listFilesRecursive(TEMPLATES_ROOT).filter(isTemplateFile);
     const allOffenses = [];
+    const allSyntaxErrors = [];
     for (const file of files) {
         const offenses = checkFile(file);
         for (const o of offenses) {
@@ -96,6 +121,21 @@ function main() {
                 text: o.text,
             });
         }
+        const syntaxErrors = getTypeScriptSyntaxErrors(file);
+        for (const e of syntaxErrors) {
+            allSyntaxErrors.push({
+                file: path.relative(process.cwd(), file),
+                line: e.line,
+                message: e.message,
+            });
+        }
+    }
+    if (allSyntaxErrors.length > 0) {
+        process.stderr.write('Template syntax check failed. TypeScript parse errors found:\n');
+        for (const e of allSyntaxErrors) {
+            process.stderr.write(`- ${e.file}:${e.line} -> ${e.message}\n`);
+        }
+        process.exit(1);
     }
     if (allOffenses.length > 0) {
         process.stderr.write('Template import check failed. Disallowed import specifiers found:\n');