@zintrust/core 2.4.1 → 2.4.2

package/src/routes/openapi.js

@@ -0,0 +1,76 @@
+/**
+ * OpenAPI Routes
+ *
+ * Serves a generated OpenAPI spec from the in-memory RouteRegistry.
+ */
+import { OpenApiGenerator } from '../openapi/OpenApiGenerator.js';
+import { Env } from '../config/env.js';
+import { Router } from './Router.js';
+import { RouteRegistry } from './RouteRegistry.js';
+const getServerUrl = () => {
+    const explicit = Env.BASE_URL;
+    if (explicit.trim() !== '')
+        return explicit;
+    const host = Env.HOST;
+    const port = Env.PORT;
+    if (host.trim() === '' || Number.isNaN(port) || port <= 0)
+        return undefined;
+    return `http://${host}:${port}`;
+};
+const getDocsHtml = (specUrl) => `<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <title>${Env.APP_NAME} API Docs</title>
+    <link rel="stylesheet" href="https://unpkg.com/swagger-ui-dist@5/swagger-ui.css" />
+    <style>
+      html, body { margin: 0; padding: 0; }
+      #swagger-ui { box-sizing: border-box; }
+    </style>
+  </head>
+  <body>
+    <div id="swagger-ui"></div>
+    <script src="https://unpkg.com/swagger-ui-dist@5/swagger-ui-bundle.js"></script>
+    <script src="https://unpkg.com/swagger-ui-dist@5/swagger-ui-standalone-preset.js"></script>
+    <script>
+      window.onload = function () {
+        window.ui = SwaggerUIBundle({
+          url: ${JSON.stringify(specUrl)},
+          dom_id: '#swagger-ui',
+          presets: [SwaggerUIBundle.presets.apis, SwaggerUIStandalonePreset],
+          layout: 'BaseLayout'
+        });
+      };
+    </script>
+  </body>
+</html>`;
+export function registerOpenApiRoutes(router) {
+    Router.get(router, '/openapi.json', (_req, res) => {
+        // Convert readonly to mutable array for OpenApiGenerator
+        const routes = Array.from(RouteRegistry.list());
+        const doc = OpenApiGenerator.generate(routes, {
+            title: Env.APP_NAME,
+            version: Env.get('APP_VERSION', '0.0.0'),
+            serverUrl: getServerUrl(),
+            excludePaths: ['/openapi.json', '/docs'],
+        });
+        res.json(doc);
+    }, {
+        meta: {
+            summary: 'OpenAPI spec',
+            tags: ['Docs'],
+            responseStatus: 200,
+        },
+    });
+    Router.get(router, '/docs', (_req, res) => {
+        res.html(getDocsHtml('/openapi.json'));
+    }, {
+        meta: {
+            summary: 'Swagger UI',
+            tags: ['Docs'],
+            responseStatus: 200,
+        },
+    });
+}
+export default registerOpenApiRoutes;

package/src/routes/publicRoot.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Public Root Resolution
+ * Determines where framework/app static assets live (public/ or dist/public).
+ */
+/**
+ * Find the package root directory.
+ */
+export declare const findPackageRoot: (startDir: string) => string;
+/**
+ * Find the package root directory (async).
+ */
+export declare const findPackageRootAsync: (startDir: string) => Promise<string>;
+/**
+ * Framework public roots (dist/public preferred).
+ */
+export declare const getFrameworkPublicRoots: () => string[];
+export declare const getFrameworkPublicRootsAsync: () => Promise<string[]>;
+/**
+ * Resolve the effective public root.
+ * Prefers app-local `public/` when present; otherwise falls back to framework public roots.
+ */
+export declare const getPublicRoot: () => string;
+/**
+ * Resolve the effective public root (async).
+ */
+export declare const getPublicRootAsync: () => Promise<string>;
+//# sourceMappingURL=publicRoot.d.ts.map

package/src/routes/publicRoot.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"publicRoot.d.ts","sourceRoot":"","sources":["../../../src/routes/publicRoot.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAMH;;GAEG;AACH,eAAO,MAAM,eAAe,GAAI,UAAU,MAAM,KAAG,MAalD,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,oBAAoB,GAAU,UAAU,MAAM,KAAG,OAAO,CAAC,MAAM,CAkB3E,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,uBAAuB,QAAO,MAAM,EAIhD,CAAC;AAEF,eAAO,MAAM,4BAA4B,QAAa,OAAO,CAAC,MAAM,EAAE,CAIrE,CAAC;AAKF;;;GAGG;AACH,eAAO,MAAM,aAAa,QAAO,MAgBhC,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,kBAAkB,QAAa,OAAO,CAAC,MAAM,CA+BzD,CAAC"}

package/src/routes/publicRoot.js

@@ -0,0 +1,112 @@
+/**
+ * Public Root Resolution
+ * Determines where framework/app static assets live (public/ or dist/public).
+ */
+import { esmDirname } from '../common/index.js';
+import * as fs from '../node-singletons/fs.js';
+import * as path from '../node-singletons/path.js';
+/**
+ * Find the package root directory.
+ */
+export const findPackageRoot = (startDir) => {
+    let current = startDir;
+    for (let i = 0; i < 10; i++) {
+        try {
+            if (fs.existsSync(path.join(current, 'package.json')))
+                return current;
+        }
+        catch {
+            // ignore access errors
+        }
+        const parent = path.dirname(current);
+        if (parent === current)
+            break;
+        current = parent;
+    }
+    return startDir;
+};
+/**
+ * Find the package root directory (async).
+ */
+export const findPackageRootAsync = async (startDir) => {
+    const findUp = async (current, depth) => {
+        if (depth >= 10)
+            return startDir;
+        try {
+            await fs.fsPromises.access(path.join(current, 'package.json'));
+            return current;
+        }
+        catch {
+            // ignore
+        }
+        const parent = path.dirname(current);
+        if (parent === current)
+            return startDir;
+        return findUp(parent, depth + 1);
+    };
+    return findUp(startDir, 0);
+};
+/**
+ * Framework public roots (dist/public preferred).
+ */
+export const getFrameworkPublicRoots = () => {
+    const thisDir = esmDirname(import.meta.url);
+    const packageRoot = findPackageRoot(thisDir);
+    return [path.join(packageRoot, 'dist/public'), path.join(packageRoot, 'public')];
+};
+export const getFrameworkPublicRootsAsync = async () => {
+    const thisDir = esmDirname(import.meta.url);
+    const packageRoot = await findPackageRootAsync(thisDir);
+    return [path.join(packageRoot, 'dist/public'), path.join(packageRoot, 'public')];
+};
+// Cache process.cwd() at module load time
+const projectCwd = process.cwd();
+/**
+ * Resolve the effective public root.
+ * Prefers app-local `public/` when present; otherwise falls back to framework public roots.
+ */
+export const getPublicRoot = () => {
+    const appRoots = [path.join(projectCwd, 'public')];
+    const candidates = [...appRoots, ...getFrameworkPublicRoots()];
+    // Prefer a root that contains an index.html (common for docs + dev portal).
+    const hasIndex = (root) => fs.existsSync(path.join(root, 'index.html'));
+    for (const candidate of candidates) {
+        if (fs.existsSync(candidate) && hasIndex(candidate))
+            return candidate;
+    }
+    for (const candidate of candidates) {
+        if (fs.existsSync(candidate))
+            return candidate;
+    }
+    return candidates[0];
+};
+/**
+ * Resolve the effective public root (async).
+ */
+export const getPublicRootAsync = async () => {
+    const appRoots = [path.join(projectCwd, 'public')];
+    const fwRoots = await getFrameworkPublicRootsAsync();
+    const candidates = [...appRoots, ...fwRoots];
+    const exists = async (p) => {
+        try {
+            await fs.fsPromises.access(p);
+            return true;
+        }
+        catch {
+            return false;
+        }
+    };
+    const hasIndex = async (root) => exists(path.join(root, 'index.html'));
+    const checks = await Promise.all(candidates.map(async (candidate) => {
+        const rootExists = await exists(candidate);
+        const indexExists = rootExists ? await hasIndex(candidate) : false;
+        return { candidate, rootExists, indexExists };
+    }));
+    const withIndex = checks.find((c) => c.indexExists);
+    if (withIndex)
+        return withIndex.candidate;
+    const firstExisting = checks.find((c) => c.rootExists);
+    if (firstExisting)
+        return firstExisting.candidate;
+    return candidates[0];
+};

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/OfficialPlugins.d.ts

@@ -0,0 +1,10 @@
+export type OfficialPluginImageMode = 'base' | 'worker';
+export declare const OfficialPlugins: Readonly<{
+    basePackages: readonly string[];
+    workerPackages: readonly string[];
+    baseAutoImports: readonly string[];
+    workerAutoImports: readonly string[];
+    getPackages(mode?: OfficialPluginImageMode): ReadonlyArray<string>;
+    getAutoImports(mode?: OfficialPluginImageMode): ReadonlyArray<string>;
+}>;
+//# sourceMappingURL=OfficialPlugins.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"OfficialPlugins.d.ts","sourceRoot":"","sources":["../../../src/runtime/OfficialPlugins.ts"],"names":[],"mappings":"AAEA,MAAM,MAAM,uBAAuB,GAAG,MAAM,GAAG,QAAQ,CAAC;AAwJxD,eAAO,MAAM,eAAe;;;;;uBAKR,uBAAuB,GAAY,aAAa,CAAC,MAAM,CAAC;0BAGrD,uBAAuB,GAAY,aAAa,CAAC,MAAM,CAAC;EAG7E,CAAC"}

package/src/runtime/OfficialPlugins.js

@@ -0,0 +1,144 @@
+import { Env } from '../config/env.js';
+const readEnvString = (...keys) => {
+    for (const key of keys) {
+        const value = Env.get(key, '').trim().toLowerCase();
+        if (value !== '')
+            return value;
+    }
+    return '';
+};
+const readEnvBool = (key) => Env.getBool(key, false);
+const isSelected = (keys, expected) => {
+    const value = readEnvString(...keys);
+    return value !== '' && expected.includes(value);
+};
+const looksLikeSqlitePath = () => {
+    const raw = readEnvString('DB_PATH', 'DB_DATABASE');
+    if (raw === '')
+        return false;
+    if (raw === ':memory:')
+        return true;
+    return (raw.includes('/') ||
+        raw.includes('\\') ||
+        raw.endsWith('.sqlite') ||
+        raw.endsWith('.db') ||
+        raw.startsWith('.') ||
+        raw.startsWith('~'));
+};
+const baseRegistrations = Object.freeze([
+    {
+        packageName: '@zintrust/db-postgres',
+        specifier: '@zintrust/db-postgres/register',
+        isEnabled: () => isSelected(['DB_CONNECTION'], ['postgresql', 'postgres', 'pg']),
+    },
+    {
+        packageName: '@zintrust/db-mysql',
+        specifier: '@zintrust/db-mysql/register',
+        isEnabled: () => isSelected(['DB_CONNECTION'], ['mysql']),
+    },
+    {
+        packageName: '@zintrust/db-sqlserver',
+        specifier: '@zintrust/db-sqlserver/register',
+        isEnabled: () => isSelected(['DB_CONNECTION'], ['sqlserver', 'sql-server', 'mssql']),
+    },
+    {
+        packageName: '@zintrust/db-sqlite',
+        specifier: '@zintrust/db-sqlite/register',
+        isEnabled: () => isSelected(['DB_CONNECTION'], ['sqlite']) || looksLikeSqlitePath(),
+    },
+    {
+        packageName: '@zintrust/queue-redis',
+        specifier: '@zintrust/queue-redis/register',
+        isEnabled: () => isSelected(['QUEUE_DRIVER'], ['redis']) ||
+            isSelected(['BROADCAST_CONNECTION', 'BROADCAST_DRIVER'], ['redis', 'redishttps']),
+    },
+    {
+        packageName: '@zintrust/queue-rabbitmq',
+        specifier: '@zintrust/queue-rabbitmq/register',
+        isEnabled: () => isSelected(['QUEUE_DRIVER'], ['rabbitmq']),
+    },
+    {
+        packageName: '@zintrust/queue-sqs',
+        specifier: '@zintrust/queue-sqs/register',
+        isEnabled: () => isSelected(['QUEUE_DRIVER'], ['sqs']),
+    },
+    {
+        packageName: '@zintrust/cache-redis',
+        specifier: '@zintrust/cache-redis/register',
+        isEnabled: () => isSelected(['CACHE_CONNECTION', 'CACHE_DRIVER'], ['redis']),
+    },
+    {
+        packageName: '@zintrust/cache-mongodb',
+        specifier: '@zintrust/cache-mongodb/register',
+        isEnabled: () => isSelected(['CACHE_CONNECTION', 'CACHE_DRIVER'], ['mongodb']),
+    },
+    {
+        packageName: '@zintrust/mail-nodemailer',
+        specifier: '@zintrust/mail-nodemailer/register',
+        isEnabled: () => isSelected(['MAIL_CONNECTION', 'MAIL_DRIVER'], ['nodemailer']),
+    },
+    {
+        packageName: '@zintrust/mail-smtp',
+        specifier: '@zintrust/mail-smtp/register',
+        isEnabled: () => isSelected(['MAIL_CONNECTION', 'MAIL_DRIVER'], ['smtp']),
+    },
+    {
+        packageName: '@zintrust/mail-sendgrid',
+        specifier: '@zintrust/mail-sendgrid/register',
+        isEnabled: () => isSelected(['MAIL_CONNECTION', 'MAIL_DRIVER'], ['sendgrid']),
+    },
+    {
+        packageName: '@zintrust/mail-mailgun',
+        specifier: '@zintrust/mail-mailgun/register',
+        isEnabled: () => isSelected(['MAIL_CONNECTION', 'MAIL_DRIVER'], ['mailgun']),
+    },
+    {
+        packageName: '@zintrust/storage-s3',
+        specifier: '@zintrust/storage-s3/register',
+        isEnabled: () => isSelected(['STORAGE_CONNECTION', 'STORAGE_DRIVER', 'BACKUP_DRIVER'], ['s3']),
+    },
+    {
+        packageName: '@zintrust/storage-r2',
+        specifier: '@zintrust/storage-r2/register',
+        isEnabled: () => isSelected(['STORAGE_CONNECTION', 'STORAGE_DRIVER', 'BACKUP_DRIVER'], ['r2']),
+    },
+    {
+        packageName: '@zintrust/storage-gcs',
+        specifier: '@zintrust/storage-gcs/register',
+        isEnabled: () => isSelected(['STORAGE_CONNECTION', 'STORAGE_DRIVER', 'BACKUP_DRIVER'], ['gcs']),
+    },
+    {
+        packageName: '@zintrust/socket',
+        specifier: '@zintrust/socket/register',
+        isEnabled: () => readEnvBool('SOCKET_ENABLED'),
+    },
+]);
+const workerRegistrations = Object.freeze([
+    {
+        packageName: '@zintrust/workers',
+        specifier: '@zintrust/workers/register',
+        isEnabled: () => readEnvBool('WORKER_ENABLED'),
+    },
+]);
+const basePackages = Object.freeze(baseRegistrations.map(({ packageName }) => packageName));
+const workerPackages = Object.freeze(workerRegistrations.map(({ packageName }) => packageName));
+const baseAutoImports = Object.freeze(baseRegistrations.map(({ specifier }) => specifier));
+const workerAutoImports = Object.freeze(workerRegistrations.map(({ specifier }) => specifier));
+const unique = (values) => Object.freeze([...new Set(values)]);
+const getRelevantRegistrations = (mode = 'base') => {
+    return mode === 'worker'
+        ? unique([...baseRegistrations, ...workerRegistrations]).filter((entry) => entry.isEnabled())
+        : baseRegistrations.filter((entry) => entry.isEnabled());
+};
+export const OfficialPlugins = Object.freeze({
+    basePackages,
+    workerPackages,
+    baseAutoImports,
+    workerAutoImports,
+    getPackages(mode = 'base') {
+        return getRelevantRegistrations(mode).map(({ packageName }) => packageName);
+    },
+    getAutoImports(mode = 'base') {
+        return getRelevantRegistrations(mode).map(({ specifier }) => specifier);
+    },
+});

package/src/runtime/OverrideValueMerge.d.ts

@@ -0,0 +1,3 @@
+export declare const mergeOverrideValues: (base: unknown, override: unknown) => unknown;
+export default mergeOverrideValues;
+//# sourceMappingURL=OverrideValueMerge.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"OverrideValueMerge.d.ts","sourceRoot":"","sources":["../../../src/runtime/OverrideValueMerge.ts"],"names":[],"mappings":"AAEA,eAAO,MAAM,mBAAmB,GAAI,MAAM,OAAO,EAAE,UAAU,OAAO,KAAG,OAatE,CAAC;AAEF,eAAe,mBAAmB,CAAC"}

package/src/runtime/OverrideValueMerge.js

@@ -0,0 +1,14 @@
+import { isObject } from '../helper/index.js';
+export const mergeOverrideValues = (base, override) => {
+    if (!isObject(base) || !isObject(override)) {
+        return override;
+    }
+    const merged = { ...base };
+    for (const [key, value] of Object.entries(override)) {
+        const current = merged[key];
+        merged[key] =
+            isObject(current) && isObject(value) ? mergeOverrideValues(current, value) : value;
+    }
+    return merged;
+};
+export default mergeOverrideValues;

package/src/runtime/PluginAutoImports.d.ts

@@ -0,0 +1,24 @@
+import { type OfficialPluginImageMode } from './OfficialPlugins';
+type ImportResult = {
+    ok: true;
+    loadedPath: string;
+} | {
+    ok: false;
+    loadedPath?: string;
+    reason: 'not-found' | 'import-failed';
+    errorMessage?: string;
+};
+export declare const PluginAutoImports: Readonly<{
+    tryImportRuntimeAutoImports(mode?: OfficialPluginImageMode): Promise<ImportResult>;
+    /**
+     * Best-effort import of a project's `src/zintrust.plugins.ts` file.
+     *
+     * This file is generated/maintained by `zin plugin install` and contains
+     * side-effect imports (e.g. `@zintrust/db-mysql/register`) which register
+     * adapters/drivers into core registries.
+     */
+    tryImportProjectAutoImports(): Promise<ImportResult>;
+    tryImportFromFileContents(files: string[]): Promise<ImportResult>;
+}>;
+export {};
+//# sourceMappingURL=PluginAutoImports.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"PluginAutoImports.d.ts","sourceRoot":"","sources":["../../../src/runtime/PluginAutoImports.ts"],"names":[],"mappings":"AAKA,OAAO,EAAmB,KAAK,uBAAuB,EAAE,MAAM,0BAA0B,CAAC;AAEzF,KAAK,YAAY,GACb;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,UAAU,EAAE,MAAM,CAAA;CAAE,GAChC;IACE,EAAE,EAAE,KAAK,CAAC;IACV,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,MAAM,EAAE,WAAW,GAAG,eAAe,CAAC;IACtC,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB,CAAC;AA2RN,eAAO,MAAM,iBAAiB;uCACY,uBAAuB,GAAY,OAAO,CAAC,YAAY,CAAC;IAkBhG;;;;;;OAMG;mCACkC,OAAO,CAAC,YAAY,CAAC;qCAgFnB,MAAM,EAAE,GAAG,OAAO,CAAC,YAAY,CAAC;EAavE,CAAC"}