@zintrust/core 0.1.1 → 0.1.3

package/src/cli/scaffolding/TemplateGenerator.js

@@ -0,0 +1,172 @@
+/**
+ * Template Generator
+ * Scaffolds mail and notification markdown templates into the application source.
+ *
+ * Notes:
+ * - Generates into application folders (default: src/mail/markdown and src/notification/markdown)
+ * - Uses FileGenerator for consistent file I/O + logging
+ */
+import { FileGenerator } from '../scaffolding/FileGenerator';
+import { Logger } from '../../config/logger';
+import { ErrorFactory } from '../../exceptions/ZintrustError';
+import * as path from '../../node-singletons/path';
+const normalizeList = (items) => {
+    const out = [];
+    for (const raw of items) {
+        const v = raw.trim();
+        if (v === '')
+            continue;
+        if (!out.includes(v))
+            out.push(v);
+    }
+    return out;
+};
+export const TemplateGenerator = Object.freeze({
+    validateTemplateName(name) {
+        const trimmed = name.trim();
+        if (trimmed === '') {
+            throw ErrorFactory.createValidationError('Template name cannot be empty');
+        }
+        // Alphanumeric + hyphens only (case-insensitive)
+        const re = /^[a-z0-9-]+$/i;
+        if (re.exec(trimmed) === null) {
+            throw ErrorFactory.createValidationError('Template name must be alphanumeric and may include hyphens only');
+        }
+    },
+    parseVariablesCsv(csv) {
+        if (csv === undefined || csv.trim() === '')
+            return [];
+        return normalizeList(csv.split(','));
+    },
+    scaffoldMailMarkdownTemplate(options) {
+        this.validateTemplateName(options.name);
+        const variables = normalizeList(options.variables);
+        const relPath = path.join('src', 'mail', 'markdown', options.category, `${options.name}.md`);
+        const filePath = path.join(options.projectRoot, relPath);
+        const content = buildMailTemplateContent({
+            name: options.name,
+            category: options.category,
+            variables,
+            copyright: options.copyright,
+        });
+        const wrote = FileGenerator.writeFile(filePath, content, {
+            overwrite: options.overwrite === true,
+            createDirs: true,
+        });
+        if (!wrote) {
+            return {
+                success: false,
+                filePath,
+                message: `Template already exists (skipped): ${relPath}`,
+            };
+        }
+        return {
+            success: true,
+            filePath,
+            message: `Mail template created: ${relPath}`,
+        };
+    },
+    scaffoldNotificationMarkdownTemplate(options) {
+        this.validateTemplateName(options.name);
+        const variables = normalizeList(options.variables);
+        const channels = normalizeList(options.channels);
+        const relPath = path.join('src', 'notification', 'markdown', `${options.name}.md`);
+        const filePath = path.join(options.projectRoot, relPath);
+        const content = buildNotificationTemplateContent({
+            name: options.name,
+            channels,
+            variables,
+            smsVariant: options.smsVariant ?? 'none',
+            copyright: options.copyright,
+        });
+        const wrote = FileGenerator.writeFile(filePath, content, {
+            overwrite: options.overwrite === true,
+            createDirs: true,
+        });
+        if (!wrote) {
+            return {
+                success: false,
+                filePath,
+                message: `Template already exists (skipped): ${relPath}`,
+            };
+        }
+        return {
+            success: true,
+            filePath,
+            message: `Notification template created: ${relPath}`,
+        };
+    },
+    ensureDirectories(projectRoot) {
+        try {
+            // These are app-side directories, created on-demand.
+            FileGenerator.createDirectories(['src/mail/markdown', 'src/notification/markdown'], projectRoot);
+        }
+        catch (error) {
+            Logger.error('Failed to ensure template directories', error);
+            throw ErrorFactory.createTryCatchError('Failed to ensure template directories', error);
+        }
+    },
+});
+const buildMailTemplateContent = (input) => {
+    const variablesLine = input.variables.length > 0 ? input.variables.join(', ') : '';
+    const varHint = input.variables.length > 0 ? `<!-- Variables: ${variablesLine} -->\n` : '<!-- Variables: -->\n';
+    const normalizedVars = normalizeList(input.variables);
+    const hasName = normalizedVars.includes('name');
+    const nonNameVars = normalizedVars.filter((v) => v !== 'name');
+    const dataRows = normalizedVars.map((v) => `- **${v}:** {{${v}}}`).join('\n');
+    const dataSection = normalizedVars.length > 0 ? `## Template Data\n\n${dataRows}\n\n` : '';
+    const introLine = hasName ? 'Welcome, {{name}}!' : 'Welcome!';
+    const exampleLinkVar = nonNameVars.find((v) => v.toLowerCase().includes('link'));
+    const exampleExpiryVar = nonNameVars.find((v) => v.toLowerCase().includes('expiry'));
+    const actionLine = exampleLinkVar === undefined
+        ? 'Action link: (add your link here)'
+        : `Action link: {{${exampleLinkVar}}}`;
+    const expiryLine = exampleExpiryVar === undefined ? '' : `_This link expires in {{${exampleExpiryVar}}}._\n\n`;
+    // Keep content intentionally minimal and copy-paste ready.
+    // Developers can adjust links/layout and remove sections as needed.
+    return `<!-- Mail Template: ${input.name} -->
+<!-- Category: ${input.category} -->
+<!-- Copyright: ${input.copyright} -->
+${varHint}
+# ${introLine}
+
+Thanks for reaching out. This is a scaffolded markdown template.
+
+${dataSection}## Next Steps
+
+- ${actionLine}
+- Customize the sections for your product
+
+${expiryLine}---
+
+Questions? Contact support.
+`;
+};
+const buildNotificationTemplateContent = (input) => {
+    const channelsLine = input.channels.length > 0 ? input.channels.join(', ') : '';
+    const variablesLine = input.variables.length > 0 ? input.variables.join(', ') : '';
+    const smsLine = input.smsVariant === 'short' ? '<!-- SMS Variant: short -->\n' : '';
+    const normalizedVars = normalizeList(input.variables);
+    const dataRows = normalizedVars.map((v) => `- **${v}:** {{${v}}}`).join('\n');
+    const dataSection = normalizedVars.length > 0 ? `## Template Data\n\n${dataRows}\n\n` : '';
+    const smsPreviewVars = normalizedVars.slice(0, 2);
+    const smsPreview = smsPreviewVars.length > 0
+        ? smsPreviewVars.map((v) => `${v}: {{${v}}}`).join(', ')
+        : 'add variables as needed';
+    const smsVariantBlock = input.smsVariant === 'short'
+        ? `\n<!-- SMS Variant Start -->\n\n${input.name}: ${smsPreview}\n\n<!-- SMS Variant End -->\n`
+        : '';
+    return `<!-- Notification Template: ${input.name} -->
+<!-- Copyright: ${input.copyright} -->
+<!-- Channels: ${channelsLine} -->
+<!-- Variables: ${variablesLine} -->
+${smsLine}
+# Notification: ${input.name}
+
+This is a scaffolded notification template.
+
+${dataSection}---
+
+Add your message content here.
+${smsVariantBlock}`;
+};

package/src/cli/scaffolding/index.d.ts

@@ -31,4 +31,5 @@ export { ServiceScaffolder } from '../scaffolding/ServiceScaffolder';
 export type { ServiceOptions, ServiceScaffoldResult } from '../scaffolding/ServiceScaffolder';
 export { BUILT_IN_TEMPLATES, TemplateEngine } from '../scaffolding/TemplateEngine';
 export type { Template, TemplateFile, TemplateVariables } from '../scaffolding/TemplateEngine';
+export { TemplateGenerator } from '../scaffolding/TemplateGenerator';
 //# sourceMappingURL=index.d.ts.map

package/src/cli/scaffolding/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/cli/scaffolding/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAE,mBAAmB,EAAE,MAAM,sCAAsC,CAAC;AAC3E,YAAY,EACV,yBAAyB,EACzB,iBAAiB,EACjB,cAAc,GACf,MAAM,sCAAsC,CAAC;AAC9C,OAAO,EAAE,gBAAgB,EAAE,MAAM,mCAAmC,CAAC;AACrE,YAAY,EACV,YAAY,EACZ,sBAAsB,EACtB,cAAc,GACf,MAAM,mCAAmC,CAAC;AAC3C,OAAO,EAAE,iBAAiB,EAAE,MAAM,oCAAoC,CAAC;AACvE,YAAY,EACV,cAAc,EACd,qBAAqB,EACrB,WAAW,GACZ,MAAM,oCAAoC,CAAC;AAC5C,OAAO,EAAE,aAAa,EAAE,MAAM,gCAAgC,CAAC;AAC/D,YAAY,EAAE,mBAAmB,EAAE,MAAM,gCAAgC,CAAC;AAC1E,OAAO,EAAE,kBAAkB,EAAE,MAAM,qCAAqC,CAAC;AACzE,YAAY,EACV,gBAAgB,EAChB,uBAAuB,GACxB,MAAM,qCAAqC,CAAC;AAC7C,OAAO,EAAE,cAAc,EAAE,MAAM,iCAAiC,CAAC;AACjE,YAAY,EACV,SAAS,EACT,UAAU,EACV,oBAAoB,EACpB,YAAY,EACZ,iBAAiB,GAClB,MAAM,iCAAiC,CAAC;AACzC,OAAO,EAAE,iBAAiB,EAAE,MAAM,oCAAoC,CAAC;AACvE,YAAY,EACV,sBAAsB,EACtB,qBAAqB,GACtB,MAAM,oCAAoC,CAAC;AAC5C,OAAO,EAAE,uBAAuB,EAAE,MAAM,0CAA0C,CAAC;AACnF,YAAY,EACV,6BAA6B,EAC7B,qBAAqB,EACrB,YAAY,GACb,MAAM,0CAA0C,CAAC;AAClD,OAAO,EAAE,wBAAwB,EAAE,MAAM,2CAA2C,CAAC;AACrF,YAAY,EACV,8BAA8B,EAC9B,sBAAsB,EACtB,aAAa,GACd,MAAM,2CAA2C,CAAC;AACnD,OAAO,EAAE,cAAc,EAAE,MAAM,iCAAiC,CAAC;AACjE,YAAY,EACV,eAAe,EACf,oBAAoB,EACpB,WAAW,EACX,YAAY,GACb,MAAM,iCAAiC,CAAC;AACzC,OAAO,EAAE,eAAe,EAAE,MAAM,kCAAkC,CAAC;AACnE,YAAY,EACV,WAAW,EACX,qBAAqB,EACrB,aAAa,GACd,MAAM,kCAAkC,CAAC;AAC1C,OAAO,EAAE,+BAA+B,EAAE,MAAM,kDAAkD,CAAC;AACnG,YAAY,EACV,eAAe,EACf,6BAA6B,EAC7B,4BAA4B,GAC7B,MAAM,kDAAkD,CAAC;AAC1D,OAAO,EAAE,8BAA8B,EAAE,MAAM,iDAAiD,CAAC;AACjG,YAAY,EACV,2BAA2B,EAC3B,mBAAmB,EACnB,qBAAqB,GACtB,MAAM,iDAAiD,CAAC;AACzD,OAAO,EAAE,iBAAiB,EAAE,MAAM,oCAAoC,CAAC;AACvE,YAAY,EAAE,cAAc,EAAE,qBAAqB,EAAE,MAAM,oCAAoC,CAAC;AAChG,OAAO,EAAE,kBAAkB,EAAE,cAAc,EAAE,MAAM,iCAAiC,CAAC;AACrF,YAAY,EAAE,QAAQ,EAAE,YAAY,EAAE,iBAAiB,EAAE,MAAM,iCAAiC,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/cli/scaffolding/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAE,mBAAmB,EAAE,MAAM,sCAAsC,CAAC;AAC3E,YAAY,EACV,yBAAyB,EACzB,iBAAiB,EACjB,cAAc,GACf,MAAM,sCAAsC,CAAC;AAC9C,OAAO,EAAE,gBAAgB,EAAE,MAAM,mCAAmC,CAAC;AACrE,YAAY,EACV,YAAY,EACZ,sBAAsB,EACtB,cAAc,GACf,MAAM,mCAAmC,CAAC;AAC3C,OAAO,EAAE,iBAAiB,EAAE,MAAM,oCAAoC,CAAC;AACvE,YAAY,EACV,cAAc,EACd,qBAAqB,EACrB,WAAW,GACZ,MAAM,oCAAoC,CAAC;AAC5C,OAAO,EAAE,aAAa,EAAE,MAAM,gCAAgC,CAAC;AAC/D,YAAY,EAAE,mBAAmB,EAAE,MAAM,gCAAgC,CAAC;AAC1E,OAAO,EAAE,kBAAkB,EAAE,MAAM,qCAAqC,CAAC;AACzE,YAAY,EACV,gBAAgB,EAChB,uBAAuB,GACxB,MAAM,qCAAqC,CAAC;AAC7C,OAAO,EAAE,cAAc,EAAE,MAAM,iCAAiC,CAAC;AACjE,YAAY,EACV,SAAS,EACT,UAAU,EACV,oBAAoB,EACpB,YAAY,EACZ,iBAAiB,GAClB,MAAM,iCAAiC,CAAC;AACzC,OAAO,EAAE,iBAAiB,EAAE,MAAM,oCAAoC,CAAC;AACvE,YAAY,EACV,sBAAsB,EACtB,qBAAqB,GACtB,MAAM,oCAAoC,CAAC;AAC5C,OAAO,EAAE,uBAAuB,EAAE,MAAM,0CAA0C,CAAC;AACnF,YAAY,EACV,6BAA6B,EAC7B,qBAAqB,EACrB,YAAY,GACb,MAAM,0CAA0C,CAAC;AAClD,OAAO,EAAE,wBAAwB,EAAE,MAAM,2CAA2C,CAAC;AACrF,YAAY,EACV,8BAA8B,EAC9B,sBAAsB,EACtB,aAAa,GACd,MAAM,2CAA2C,CAAC;AACnD,OAAO,EAAE,cAAc,EAAE,MAAM,iCAAiC,CAAC;AACjE,YAAY,EACV,eAAe,EACf,oBAAoB,EACpB,WAAW,EACX,YAAY,GACb,MAAM,iCAAiC,CAAC;AACzC,OAAO,EAAE,eAAe,EAAE,MAAM,kCAAkC,CAAC;AACnE,YAAY,EACV,WAAW,EACX,qBAAqB,EACrB,aAAa,GACd,MAAM,kCAAkC,CAAC;AAC1C,OAAO,EAAE,+BAA+B,EAAE,MAAM,kDAAkD,CAAC;AACnG,YAAY,EACV,eAAe,EACf,6BAA6B,EAC7B,4BAA4B,GAC7B,MAAM,kDAAkD,CAAC;AAC1D,OAAO,EAAE,8BAA8B,EAAE,MAAM,iDAAiD,CAAC;AACjG,YAAY,EACV,2BAA2B,EAC3B,mBAAmB,EACnB,qBAAqB,GACtB,MAAM,iDAAiD,CAAC;AACzD,OAAO,EAAE,iBAAiB,EAAE,MAAM,oCAAoC,CAAC;AACvE,YAAY,EAAE,cAAc,EAAE,qBAAqB,EAAE,MAAM,oCAAoC,CAAC;AAChG,OAAO,EAAE,kBAAkB,EAAE,cAAc,EAAE,MAAM,iCAAiC,CAAC;AACrF,YAAY,EAAE,QAAQ,EAAE,YAAY,EAAE,iBAAiB,EAAE,MAAM,iCAAiC,CAAC;AACjG,OAAO,EAAE,iBAAiB,EAAE,MAAM,oCAAoC,CAAC"}

package/src/cli/scaffolding/index.js

@@ -16,3 +16,4 @@ export { ServiceIntegrationTestGenerator } from '../scaffolding/ServiceIntegrati
 export { ServiceRequestFactoryGenerator } from '../scaffolding/ServiceRequestFactoryGenerator';
 export { ServiceScaffolder } from '../scaffolding/ServiceScaffolder';
 export { BUILT_IN_TEMPLATES, TemplateEngine } from '../scaffolding/TemplateEngine';
+export { TemplateGenerator } from '../scaffolding/TemplateGenerator';

package/src/cli/utils/spawn.js

@@ -2,7 +2,7 @@ import { appConfig } from '../../config/app';
 import { ErrorFactory } from '../../exceptions/ZintrustError';
 import { spawn } from '../../node-singletons/child-process';
 import { existsSync } from '../../node-singletons/fs';
-import * as path from 'node:path';
+import * as path from '../../node-singletons/path';
 const getExitCode = (exitCode, signal) => {
     if (typeof exitCode === 'number')
         return exitCode;

package/src/common/AwsSigV4.d.ts

@@ -0,0 +1,41 @@
+export type AwsSigV4Credentials = {
+    accessKeyId: string;
+    secretAccessKey: string;
+    sessionToken?: string;
+};
+type CanonicalizedHeaders = {
+    canonicalHeaders: string;
+    signedHeaders: string;
+};
+export declare const AwsSigV4: Readonly<{
+    sha256Hex(data: string | Uint8Array): string;
+    hmacSha256(key: Uint8Array | string, data: string): Uint8Array;
+    toAmzDate(date: Date): {
+        amzDate: string;
+        dateStamp: string;
+    };
+    deriveSigningKey(params: {
+        secretAccessKey: string;
+        dateStamp: string;
+        region: string;
+        service: string;
+    }): Uint8Array;
+    canonicalizeHeaders(headers: Record<string, string>): CanonicalizedHeaders;
+    buildAuthorization(params: {
+        method: string;
+        canonicalUri: string;
+        canonicalQueryString: string;
+        headers: Record<string, string>;
+        payloadHash: string;
+        region: string;
+        service: string;
+        amzDate: string;
+        dateStamp: string;
+        credentials: AwsSigV4Credentials;
+    }): {
+        authorization: string;
+        signedHeaders: string;
+    };
+}>;
+export {};
+//# sourceMappingURL=AwsSigV4.d.ts.map

package/src/common/AwsSigV4.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"AwsSigV4.d.ts","sourceRoot":"","sources":["../../../src/common/AwsSigV4.ts"],"names":[],"mappings":"AAEA,MAAM,MAAM,mBAAmB,GAAG;IAChC,WAAW,EAAE,MAAM,CAAC;IACpB,eAAe,EAAE,MAAM,CAAC;IACxB,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB,CAAC;AAEF,KAAK,oBAAoB,GAAG;IAC1B,gBAAgB,EAAE,MAAM,CAAC;IACzB,aAAa,EAAE,MAAM,CAAC;CACvB,CAAC;AAEF,eAAO,MAAM,QAAQ;oBACH,MAAM,GAAG,UAAU,GAAG,MAAM;oBAI5B,UAAU,GAAG,MAAM,QAAQ,MAAM,GAAG,UAAU;oBAI9C,IAAI,GAAG;QAAE,OAAO,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,MAAM,CAAA;KAAE;6BAapC;QACvB,eAAe,EAAE,MAAM,CAAC;QACxB,SAAS,EAAE,MAAM,CAAC;QAClB,MAAM,EAAE,MAAM,CAAC;QACf,OAAO,EAAE,MAAM,CAAC;KACjB,GAAG,UAAU;iCAOe,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,oBAAoB;+BAY/C;QACzB,MAAM,EAAE,MAAM,CAAC;QACf,YAAY,EAAE,MAAM,CAAC;QACrB,oBAAoB,EAAE,MAAM,CAAC;QAC7B,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;QAChC,WAAW,EAAE,MAAM,CAAC;QACpB,MAAM,EAAE,MAAM,CAAC;QACf,OAAO,EAAE,MAAM,CAAC;QAChB,OAAO,EAAE,MAAM,CAAC;QAChB,SAAS,EAAE,MAAM,CAAC;QAClB,WAAW,EAAE,mBAAmB,CAAC;KAClC,GAAG;QAAE,aAAa,EAAE,MAAM,CAAC;QAAC,aAAa,EAAE,MAAM,CAAA;KAAE;EA6CpD,CAAC"}

package/src/common/AwsSigV4.js

@@ -0,0 +1,69 @@
+import { createHash, createHmac } from '../node-singletons/crypto';
+export const AwsSigV4 = Object.freeze({
+    sha256Hex(data) {
+        return createHash('sha256').update(data).digest('hex');
+    },
+    hmacSha256(key, data) {
+        return createHmac('sha256', key).update(data).digest();
+    },
+    toAmzDate(date) {
+        const yyyy = String(date.getUTCFullYear());
+        const mm = String(date.getUTCMonth() + 1).padStart(2, '0');
+        const dd = String(date.getUTCDate()).padStart(2, '0');
+        const hh = String(date.getUTCHours()).padStart(2, '0');
+        const mi = String(date.getUTCMinutes()).padStart(2, '0');
+        const ss = String(date.getUTCSeconds()).padStart(2, '0');
+        const dateStamp = `${yyyy}${mm}${dd}`;
+        const amzDate = `${dateStamp}T${hh}${mi}${ss}Z`;
+        return { amzDate, dateStamp };
+    },
+    deriveSigningKey(params) {
+        const kDate = this.hmacSha256(`AWS4${params.secretAccessKey}`, params.dateStamp);
+        const kRegion = this.hmacSha256(kDate, params.region);
+        const kService = this.hmacSha256(kRegion, params.service);
+        return this.hmacSha256(kService, 'aws4_request');
+    },
+    canonicalizeHeaders(headers) {
+        const sortedHeaderKeys = Object.keys(headers).sort((a, b) => a.localeCompare(b));
+        const canonicalHeaders = sortedHeaderKeys
+            .map((k) => `${k}:${String(headers[k]).trim().replaceAll(/\s+/g, ' ')}`)
+            .join('\n');
+        const signedHeaders = sortedHeaderKeys.join(';');
+        return { canonicalHeaders, signedHeaders };
+    },
+    buildAuthorization(params) {
+        const sessionToken = params.credentials.sessionToken;
+        if (typeof sessionToken === 'string' &&
+            sessionToken.trim() !== '' &&
+            params.headers['x-amz-security-token'] === undefined) {
+            params.headers['x-amz-security-token'] = sessionToken;
+        }
+        const { canonicalHeaders, signedHeaders } = this.canonicalizeHeaders(params.headers);
+        const canonicalRequest = [
+            params.method,
+            params.canonicalUri,
+            params.canonicalQueryString,
+            `${canonicalHeaders}\n`,
+            signedHeaders,
+            params.payloadHash,
+        ].join('\n');
+        const algorithm = 'AWS4-HMAC-SHA256';
+        const credentialScope = `${params.dateStamp}/${params.region}/${params.service}/aws4_request`;
+        const stringToSign = [
+            algorithm,
+            params.amzDate,
+            credentialScope,
+            this.sha256Hex(canonicalRequest),
+        ].join('\n');
+        const signingKey = this.deriveSigningKey({
+            secretAccessKey: params.credentials.secretAccessKey,
+            dateStamp: params.dateStamp,
+            region: params.region,
+            service: params.service,
+        });
+        const signature = createHmac('sha256', signingKey).update(stringToSign).digest('hex');
+        const authorization = `${algorithm} Credential=${params.credentials.accessKeyId}/${credentialScope}, ` +
+            `SignedHeaders=${signedHeaders}, Signature=${signature}`;
+        return { authorization, signedHeaders };
+    },
+});

package/src/common/index.d.ts

@@ -1,3 +1,7 @@
+export { AwsSigV4 } from './AwsSigV4';
+export declare const FileChecker: {
+    exists(filePath: string): boolean;
+};
 /**
  * Common utilities - Sealed namespace for immutability
  */
@@ -6,6 +10,21 @@ export declare const CommonUtils: Readonly<{
      * Resolve npm executable path from Node.js installation
      */
     resolveNpmPath(): string;
+    /**
+     * RUNTIME UTILITIES
+     */
+    /**
+     * Async delay helper. No-ops when timers are unavailable.
+     */
+    delay(ms: number): Promise<void>;
+    /**
+     * Resolve an ESM `import.meta.url` to a filesystem path.
+     */
+    esmFilePath(metaUrl: string | URL): string;
+    /**
+     * Resolve an ESM `import.meta.url` to a filesystem directory.
+     */
+    esmDirname(metaUrl: string | URL): string;
     /**
      * STRING UTILITIES
      */
@@ -32,6 +51,10 @@ export declare const CommonUtils: Readonly<{
      * Ensure directory exists, create if missing
      */
     ensureDir(dirPath: string): void;
+    /**
+     * Best-effort variant of ensureDir() that never throws.
+     */
+    ensureDirSafe(dirPath: string): void;
     /**
      * Read file contents as string
      */
@@ -82,6 +105,22 @@ export declare const CommonUtils: Readonly<{
      * Ensure value is object, throw otherwise
      */
     ensureObject(value: unknown, fieldName: string): Record<string, unknown>;
+    /**
+     * Resolve preferred package manager.
+     * If `preferred` is provided, the first value is returned. Otherwise we detect by lock files.
+     */
+    resolvePackageManager(preferred?: string[]): string;
 }>;
 export declare const resolveNpmPath: () => string;
+export declare const delay: (ms: number) => Promise<void>;
+export declare const esmFilePath: (metaUrl: string | URL) => string;
+export declare const esmDirname: (metaUrl: string | URL) => string;
+export declare const resolvePackageManager: (preferred?: string[]) => string;
+export declare const extractErrorMessage: (error: unknown) => string;
+export declare const extractErrorMessageStrict: (error: unknown) => string;
+export declare const fileExists: (filePath: string) => boolean;
+export declare const ensureDir: (dirPath: string) => void;
+export declare const ensureDirSafe: (dirPath: string) => void;
+export declare const readFile: (filePath: string) => string;
+export declare const writeFile: (filePath: string, content: string, createDir?: boolean) => void;
 //# sourceMappingURL=index.d.ts.map

package/src/common/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/common/index.ts"],"names":[],"mappings":"AAIA;;GAEG;AACH,eAAO,MAAM,WAAW;IACtB;;OAEG;sBACe,MAAM;IAgBxB;;OAEG;IAEH;;OAEG;mBACY,MAAM,GAAG,MAAM;IAgB9B;;OAEG;qBACc,MAAM,GAAG,MAAM;IAUhC;;OAEG;sBACe,MAAM,GAAG,MAAM;IAQjC;;OAEG;IAEH;;OAEG;yBACkB,MAAM,GAAG,OAAO;IAQrC;;OAEG;uBACgB,MAAM,GAAG,IAAI;IAMhC;;OAEG;uBACgB,MAAM,GAAG,MAAM;IAUlC;;OAEG;wBACiB,MAAM,WAAW,MAAM,wBAAqB,IAAI;IAcpE;;OAEG;yBACkB,MAAM,GAAG,IAAI;IAYlC;;OAEG;IAEH;;OAEG;2BACoB,MAAM;IAI7B;;OAEG;2BACmB,IAAI,GAAgB,MAAM;IAIhD;;OAEG;8BACuB,MAAM,GAAG,IAAI;IAYvC;;OAEG;IAEH;;OAEG;+BACwB,OAAO,GAAG,MAAM;IAa3C;;OAEG;6BAEQ,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,kBAChB,MAAM,EAAE,WACf,MAAM,GACd,IAAI;IAWP;;OAEG;mBACY,OAAO,GAAG,OAAO;IAIhC;;OAEG;wBACiB,OAAO,aAAa,MAAM,GAAG,MAAM;IAOvD;;OAEG;wBACiB,OAAO,aAAa,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;EAMxE,CAAC;AAGH,eAAO,MAAM,cAAc,QAAO,MAAsC,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/common/index.ts"],"names":[],"mappings":"AAKA,OAAO,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAC;AAG5C,eAAO,MAAM,WAAW;qBACL,MAAM,GAAG,OAAO;CAOlC,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,WAAW;IACtB;;OAEG;sBACe,MAAM;IAgBxB;;OAEG;IAEH;;OAEG;cACa,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAWtC;;OAEG;yBACkB,MAAM,GAAG,GAAG,GAAG,MAAM;IAI1C;;OAEG;wBACiB,MAAM,GAAG,GAAG,GAAG,MAAM;IAIzC;;OAEG;IAEH;;OAEG;mBACY,MAAM,GAAG,MAAM;IAgB9B;;OAEG;qBACc,MAAM,GAAG,MAAM;IAUhC;;OAEG;sBACe,MAAM,GAAG,MAAM;IAQjC;;OAEG;IAEH;;OAEG;yBACkB,MAAM,GAAG,OAAO;IAIrC;;OAEG;uBACgB,MAAM,GAAG,IAAI;IAMhC;;OAEG;2BACoB,MAAM,GAAG,IAAI;IAQpC;;OAEG;uBACgB,MAAM,GAAG,MAAM;IAUlC;;OAEG;wBACiB,MAAM,WAAW,MAAM,wBAAqB,IAAI;IAcpE;;OAEG;yBACkB,MAAM,GAAG,IAAI;IAYlC;;OAEG;IAEH;;OAEG;2BACoB,MAAM;IAI7B;;OAEG;2BACmB,IAAI,GAAgB,MAAM;IAIhD;;OAEG;8BACuB,MAAM,GAAG,IAAI;IAYvC;;OAEG;IAEH;;OAEG;+BACwB,OAAO,GAAG,MAAM;IAa3C;;OAEG;6BAEQ,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,kBAChB,MAAM,EAAE,WACf,MAAM,GACd,IAAI;IAWP;;OAEG;mBACY,OAAO,GAAG,OAAO;IAIhC;;OAEG;wBACiB,OAAO,aAAa,MAAM,GAAG,MAAM;IAOvD;;OAEG;wBACiB,OAAO,aAAa,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;IAOxE;;;OAGG;sCAC+B,MAAM,EAAE,GAAG,MAAM;EAgBnD,CAAC;AAGH,eAAO,MAAM,cAAc,QAAO,MAAsC,CAAC;AAEzE,eAAO,MAAM,KAAK,GAAU,IAAI,MAAM,KAAG,OAAO,CAAC,IAAI,CAA0B,CAAC;AAEhF,eAAO,MAAM,WAAW,GAAI,SAAS,MAAM,GAAG,GAAG,KAAG,MAA0C,CAAC;AAC/F,eAAO,MAAM,UAAU,GAAI,SAAS,MAAM,GAAG,GAAG,KAAG,MAAyC,CAAC;AAE7F,eAAO,MAAM,qBAAqB,GAAI,YAAY,MAAM,EAAE,KAAG,MAE5D,CAAC;AAEF,eAAO,MAAM,mBAAmB,GAAI,OAAO,OAAO,KAAG,MACb,CAAC;AAIzC,eAAO,MAAM,yBAAyB,GAAI,OAAO,OAAO,KAAG,MAM1D,CAAC;AAGF,eAAO,MAAM,UAAU,GAAI,UAAU,MAAM,KAAG,OAA2C,CAAC;AAC1F,eAAO,MAAM,SAAS,GAAI,SAAS,MAAM,KAAG,IAAsC,CAAC;AACnF,eAAO,MAAM,aAAa,GAAI,SAAS,MAAM,KAAG,IAA0C,CAAC;AAC3F,eAAO,MAAM,QAAQ,GAAI,UAAU,MAAM,KAAG,MAAwC,CAAC;AACrF,eAAO,MAAM,SAAS,GAAI,UAAU,MAAM,EAAE,SAAS,MAAM,EAAE,mBAAgB,KAAG,IAC3B,CAAC"}

package/src/common/index.js

@@ -1,6 +1,19 @@
 import { ErrorFactory } from '../exceptions/ZintrustError';
-import fs from '../node-singletons/fs';
-import * as path from 'node:path';
+import * as fs from '../node-singletons/fs';
+import * as path from '../node-singletons/path';
+import { fileURLToPath } from '../node-singletons/url';
+export { AwsSigV4 } from './AwsSigV4';
+// Mutable FileChecker used to abstract FS checks for easier testing/mocking
+export const FileChecker = {
+    exists(filePath) {
+        try {
+            return fs.existsSync(filePath);
+        }
+        catch {
+            return false;
+        }
+    },
+};
 /**
  * Common utilities - Sealed namespace for immutability
  */
@@ -19,6 +32,35 @@ export const CommonUtils = Object.freeze({
         }
         throw ErrorFactory.createGeneralError('Unable to locate npm executable. Ensure Node.js (with npm) is installed in the standard location.');
     },
+    /**
+     * RUNTIME UTILITIES
+     */
+    /**
+     * Async delay helper. No-ops when timers are unavailable.
+     */
+    async delay(ms) {
+        if (ms <= 0)
+            return;
+        await new Promise((resolve) => {
+            if (typeof globalThis.setTimeout !== 'function') {
+                resolve();
+                return;
+            }
+            globalThis.setTimeout(() => resolve(), ms);
+        });
+    },
+    /**
+     * Resolve an ESM `import.meta.url` to a filesystem path.
+     */
+    esmFilePath(metaUrl) {
+        return fileURLToPath(metaUrl);
+    },
+    /**
+     * Resolve an ESM `import.meta.url` to a filesystem directory.
+     */
+    esmDirname(metaUrl) {
+        return path.dirname(this.esmFilePath(metaUrl));
+    },
     /**
      * STRING UTILITIES
      */
@@ -67,12 +109,7 @@ export const CommonUtils = Object.freeze({
      * Check if file exists
      */
     fileExists(filePath) {
-        try {
-            return fs.existsSync(filePath);
-        }
-        catch {
-            return false;
-        }
+        return FileChecker.exists(filePath);
     },
     /**
      * Ensure directory exists, create if missing
@@ -82,6 +119,17 @@ export const CommonUtils = Object.freeze({
             fs.mkdirSync(dirPath, { recursive: true });
         }
     },
+    /**
+     * Best-effort variant of ensureDir() that never throws.
+     */
+    ensureDirSafe(dirPath) {
+        try {
+            this.ensureDir(dirPath);
+        }
+        catch {
+            // best-effort
+        }
+    },
     /**
      * Read file contents as string
      */
@@ -202,6 +250,51 @@ export const CommonUtils = Object.freeze({
         }
         return value;
     },
+    /**
+     * Resolve preferred package manager.
+     * If `preferred` is provided, the first value is returned. Otherwise we detect by lock files.
+     */
+    resolvePackageManager(preferred) {
+        if (Array.isArray(preferred) && preferred.length > 0) {
+            return preferred[0];
+        }
+        try {
+            if (this.fileExists('pnpm-lock.yaml'))
+                return 'pnpm';
+            if (this.fileExists('yarn.lock'))
+                return 'yarn';
+            if (this.fileExists('package-lock.json'))
+                return 'npm';
+        }
+        catch {
+            // ignore FS errors and fall through to default
+        }
+        // Default to npm
+        return 'npm';
+    },
 });
 // Re-export for backward compatibility
 export const resolveNpmPath = () => CommonUtils.resolveNpmPath();
+export const delay = async (ms) => CommonUtils.delay(ms);
+export const esmFilePath = (metaUrl) => CommonUtils.esmFilePath(metaUrl);
+export const esmDirname = (metaUrl) => CommonUtils.esmDirname(metaUrl);
+export const resolvePackageManager = (preferred) => {
+    return CommonUtils.resolvePackageManager(preferred);
+};
+export const extractErrorMessage = (error) => CommonUtils.extractErrorMessage(error);
+// Some call sites historically treated non-Error throws (e.g. string) as unknown.
+// Keep that behavior available as a shared helper.
+export const extractErrorMessageStrict = (error) => {
+    if (error instanceof Error)
+        return error.message;
+    if (error !== undefined && error !== null && typeof error === 'object' && 'message' in error) {
+        return String(error.message);
+    }
+    return 'Unknown error';
+};
+// Convenience named exports to make specific helpers testable and import-friendly
+export const fileExists = (filePath) => CommonUtils.fileExists(filePath);
+export const ensureDir = (dirPath) => CommonUtils.ensureDir(dirPath);
+export const ensureDirSafe = (dirPath) => CommonUtils.ensureDirSafe(dirPath);
+export const readFile = (filePath) => CommonUtils.readFile(filePath);
+export const writeFile = (filePath, content, createDir = true) => CommonUtils.writeFile(filePath, content, createDir);

package/src/common/uuid.d.ts

@@ -0,0 +1,3 @@
+export declare const generateUuid: () => string;
+export declare function generateSecureJobId(errMsg?: string): Promise<string>;
+//# sourceMappingURL=uuid.d.ts.map

package/src/common/uuid.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"uuid.d.ts","sourceRoot":"","sources":["../../../src/common/uuid.ts"],"names":[],"mappings":"AAEA,eAAO,MAAM,YAAY,QAAO,MAG/B,CAAC;AAEF,wBAAsB,mBAAmB,CACvC,MAAM,GAAE,MAAgE,GACvE,OAAO,CAAC,MAAM,CAAC,CAqBjB"}

package/src/common/uuid.js

@@ -0,0 +1,30 @@
+import { ErrorFactory } from '../exceptions/ZintrustError';
+export const generateUuid = () => {
+    if (typeof globalThis?.crypto?.randomUUID === 'function')
+        return globalThis.crypto.randomUUID();
+    return `${Date.now()}-${Math.random().toString(36).slice(2, 9)}`; // NOSONAR
+};
+export async function generateSecureJobId(errMsg = 'Secure crypto API not available to generate a job id.') {
+    if (typeof globalThis.crypto?.randomUUID === 'function') {
+        return globalThis.crypto.randomUUID();
+    }
+    if (typeof globalThis.crypto?.getRandomValues === 'function') {
+        const bytes = new Uint8Array(16);
+        globalThis.crypto.getRandomValues(bytes);
+        return bytesToHex(bytes);
+    }
+    // Node fallback for environments without Web Crypto
+    try {
+        const nodeCrypto = await import('../node-singletons/crypto');
+        return nodeCrypto.randomBytes(16).toString('hex');
+    }
+    catch (error) {
+        throw ErrorFactory.createTryCatchError(errMsg || 'Secure crypto API not available to generate a job id.', error);
+    }
+}
+function bytesToHex(bytes) {
+    let out = '';
+    for (const b of bytes)
+        out += b.toString(16).padStart(2, '0');
+    return out;
+}

package/src/config/FileLogWriter.d.ts

@@ -0,0 +1,22 @@
+/**
+ * FileLogWriter (Node.js only)
+ *
+ * Provides best-effort file logging with daily + size-based rotation.
+ * This module imports Node built-ins and should be loaded only in Node environments.
+ */
+type CleanOnceOptions = {
+    logsDir?: string;
+    keepDays?: number;
+    maxTotalSize?: number;
+    keepFiles?: number;
+};
+/**
+ * Clean log files with additional retention policies.
+ * Returns an array of deleted file paths for auditing/tests.
+ */
+export declare const cleanOnce: (options?: CleanOnceOptions) => string[];
+export declare const FileLogWriter: Readonly<{
+    write(line: string): void;
+}>;
+export default FileLogWriter;
+//# sourceMappingURL=FileLogWriter.d.ts.map

package/src/config/FileLogWriter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"FileLogWriter.d.ts","sourceRoot":"","sources":["../../../src/config/FileLogWriter.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AA8EH,KAAK,gBAAgB,GAAG;IACtB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB,CAAC;AAiFF;;;GAGG;AACH,eAAO,MAAM,SAAS,GAAI,UAAU,gBAAgB,KAAG,MAAM,EAsB5D,CAAC;AAoBF,eAAO,MAAM,aAAa;gBACZ,MAAM,GAAG,IAAI;EAqBzB,CAAC;AAEH,eAAe,aAAa,CAAC"}