@twin.org/node-core 0.0.2-next.17 → 0.0.2-next.18

package/dist/cjs/index.cjs

@@ -11,6 +11,7 @@ var vaultModels = require('@twin.org/vault-models');
 var walletModels = require('@twin.org/wallet-models');
 var promises = require('node:fs/promises');
 var path = require('node:path');
+var cliCore = require('@twin.org/cli-core');
 var rightsManagementRestClient = require('@twin.org/rights-management-rest-client');
 var engineServer = require('@twin.org/engine-server');
 var modules = require('@twin.org/modules');
@@ -70,20 +71,19 @@ const NodeFeatures = {
 
 // Copyright 2024 IOTA Stiftung.
 // SPDX-License-Identifier: Apache-2.0.
-/* eslint-disable no-console */
 /**
  * Initialise the locales for the application.
  * @param localesDirectory The directory containing the locales.
  */
 async function initialiseLocales(localesDirectory) {
     const localesFile = path.resolve(path.join(localesDirectory, "en.json"));
-    console.info("Locales File:", localesFile);
+    cliCore.CLIDisplay.value("Locales File", localesFile);
     if (await fileExists(localesFile)) {
         const enLangContent = await promises.readFile(localesFile, "utf8");
         core.I18n.addDictionary("en", JSON.parse(enLangContent));
     }
     else {
-        console.warn(`Locales file not found: ${localesFile}`);
+        cliCore.CLIDisplay.error(`Locales file not found: ${localesFile}`);
     }
 }
 /**
@@ -1815,7 +1815,6 @@ async function buildEngineServerConfiguration(envVars, coreEngineConfig, serverI
 
 // Copyright 2024 IOTA Stiftung.
 // SPDX-License-Identifier: Apache-2.0.
-/* eslint-disable no-console */
 /**
  * Handles the configuration of the extensions.
  * @param envVars The environment variables for the node.
@@ -1828,11 +1827,11 @@ async function extensionsConfiguration(envVars, nodeEngineConfig) {
         for (const extension of extensions) {
             let initialiseConfigMethod;
             try {
-                console.info(`Loading extension "${extension}"`);
+                cliCore.CLIDisplay.value(core.I18n.formatMessage("node.extensionLoading"), extension);
                 initialiseConfigMethod = await modules.ModuleHelper.getModuleMethod(extension, "extensionInitialise");
             }
             catch (err) {
-                console.error(`Failed to load extension "${extension}":`, err);
+                throw new core.GeneralError("node", "extensionLoadingError", { extension }, err);
             }
             if (core.Is.function(initialiseConfigMethod)) {
                 await initialiseConfigMethod(envVars, nodeEngineConfig);
@@ -1853,6 +1852,7 @@ async function extensionsInitialiseEngine(envVars, engineCore) {
         for (const extension of extensions) {
             let initialiseEngineMethod;
             try {
+                engineCore.logInfo(core.I18n.formatMessage("node.extensionInitialisingEngine", { extension }));
                 initialiseEngineMethod =
                     await modules.ModuleHelper.getModuleMethod(extension, "extensionInitialiseEngine");
             }
@@ -1876,6 +1876,7 @@ async function extensionsInitialiseEngineServer(envVars, engineCore, engineServe
         for (const extension of extensions) {
             let initialiseEngineServerMethod;
             try {
+                engineCore.logInfo(core.I18n.formatMessage("node.extensionInitialisingEngineServer", { extension }));
                 initialiseEngineServerMethod =
                     await modules.ModuleHelper.getModuleMethod(extension, "extensionInitialiseEngineServer");
             }
@@ -1889,14 +1890,16 @@ async function extensionsInitialiseEngineServer(envVars, engineCore, engineServe
 /**
  * Handles the shutdown of the extensions.
  * @param envVars The environment variables for the node.
+ * @param engineCore The engine core instance.
  * @returns Nothing.
  */
-async function shutdownExtensions(envVars) {
+async function shutdownExtensions(envVars, engineCore) {
     if (core.Is.stringValue(envVars.extensions)) {
         const extensions = envVars.extensions.split(",");
         for (const extension of extensions) {
             let shutdownMethod;
             try {
+                engineCore.logInfo(core.I18n.formatMessage("node.extensionShutdown", { extension }));
                 shutdownMethod = await modules.ModuleHelper.getModuleMethod(extension, "extensionShutdown");
             }
             catch { }
@@ -1909,7 +1912,6 @@ async function shutdownExtensions(envVars) {
 
 // Copyright 2024 IOTA Stiftung.
 // SPDX-License-Identifier: Apache-2.0.
-/* eslint-disable no-console */
 /**
  * Start the engine server.
  * @param nodeOptions Optional run options for the engine server.
@@ -1940,13 +1942,13 @@ async function start(nodeOptions, nodeEngineConfig, envVars) {
     const server = new engineServer.EngineServer({ engineCore: engine$1 });
     // Extend the engine.
     if (core.Is.function(nodeOptions?.extendEngine)) {
-        console.info("Extending Engine");
+        engine$1.logInfo(core.I18n.formatMessage("node.extendingEngine"));
         await nodeOptions.extendEngine(engine$1);
     }
     await extensionsInitialiseEngine(envVars, engine$1);
     // Extend the engine server.
     if (core.Is.function(nodeOptions?.extendEngineServer)) {
-        console.info("Extending Engine Server");
+        engine$1.logInfo(core.I18n.formatMessage("node.extendingEngineServer"));
         await nodeOptions?.extendEngineServer(server);
     }
     await extensionsInitialiseEngineServer(envVars, engine$1, server);
@@ -1961,7 +1963,7 @@ async function start(nodeOptions, nodeEngineConfig, envVars) {
             server,
             shutdown: async () => {
                 await server.stop();
-                await shutdownExtensions(envVars);
+                await shutdownExtensions(envVars, engine$1);
             }
         };
     }
@@ -1969,7 +1971,6 @@ async function start(nodeOptions, nodeEngineConfig, envVars) {
 
 // Copyright 2024 IOTA Stiftung.
 // SPDX-License-Identifier: Apache-2.0.
-/* eslint-disable no-console */
 /**
  * Run the TWIN Node server.
  * @param nodeOptions Optional configuration options for running the server.
@@ -1980,42 +1981,48 @@ async function run(nodeOptions) {
         nodeOptions ??= {};
         const serverInfo = {
             name: nodeOptions?.serverName ?? "TWIN Node Server",
-            version: nodeOptions?.serverVersion ?? "0.0.2-next.17" // x-release-please-version
+            version: nodeOptions?.serverVersion ?? "0.0.2-next.18" // x-release-please-version
         };
-        console.log(`\u001B[4m🌩️  ${serverInfo.name} v${serverInfo.version}\u001B[24m\n`);
+        cliCore.CLIDisplay.header(serverInfo.name, serverInfo.version, "🌩️ ");
         if (!core.Is.stringValue(nodeOptions?.executionDirectory)) {
             nodeOptions.executionDirectory = getExecutionDirectory();
         }
-        console.info("Execution Directory:", nodeOptions.executionDirectory);
+        cliCore.CLIDisplay.value("Execution Directory", nodeOptions.executionDirectory);
         nodeOptions.localesDirectory =
             nodeOptions?.localesDirectory ??
                 path.resolve(path.join(nodeOptions.executionDirectory, "dist", "locales"));
-        console.info("Locales Directory:", nodeOptions.localesDirectory);
+        cliCore.CLIDisplay.value("Locales Directory", nodeOptions.localesDirectory);
         await initialiseLocales(nodeOptions.localesDirectory);
         if (core.Is.empty(nodeOptions?.openApiSpecFile)) {
             const specFile = path.resolve(path.join(nodeOptions.executionDirectory ?? "", "docs", "open-api", "spec.json"));
-            console.info("Default OpenAPI Spec File:", specFile);
+            cliCore.CLIDisplay.value("Default OpenAPI Spec File", specFile);
             if (await fileExists(specFile)) {
                 nodeOptions ??= {};
                 nodeOptions.openApiSpecFile = specFile;
             }
         }
+        else {
+            cliCore.CLIDisplay.value("OpenAPI Spec File", nodeOptions.openApiSpecFile);
+        }
         if (core.Is.empty(nodeOptions?.favIconFile)) {
             const favIconFile = path.resolve(path.join(nodeOptions.executionDirectory ?? "", "static", "favicon.png"));
-            console.info("Default Favicon File:", favIconFile);
+            cliCore.CLIDisplay.value("Default Favicon File", favIconFile);
             if (await fileExists(favIconFile)) {
                 nodeOptions ??= {};
                 nodeOptions.favIconFile = favIconFile;
             }
         }
+        else {
+            cliCore.CLIDisplay.value("Favicon File", nodeOptions.favIconFile);
+        }
         nodeOptions.envPrefix ??= "TWIN_NODE_";
-        console.info("Environment Prefix:", nodeOptions.envPrefix);
+        cliCore.CLIDisplay.value("Environment Variable Prefix", nodeOptions.envPrefix);
         overrideModuleImport(nodeOptions.executionDirectory ?? "");
         const { nodeEngineConfig, nodeEnvVars: envVars } = await buildConfiguration(
         // This is the only location in the code base that should access process.env directly
         // eslint-disable-next-line no-restricted-syntax
         process.env, nodeOptions, serverInfo);
-        console.info();
+        cliCore.CLIDisplay.break();
         const startResult = await start(nodeOptions, nodeEngineConfig, envVars);
         if (!core.Is.empty(startResult)) {
             for (const signal of ["SIGHUP", "SIGINT", "SIGTERM"]) {
@@ -2026,7 +2033,7 @@ async function run(nodeOptions) {
         }
     }
     catch (err) {
-        console.error(core.ErrorHelper.formatErrors(err).join("\n"));
+        cliCore.CLIDisplay.error(err);
         // eslint-disable-next-line unicorn/no-process-exit
         process.exit(1);
     }
@@ -2043,7 +2050,7 @@ async function buildConfiguration(processEnv, options, serverInfo) {
     let defaultEnvOnly = false;
     if (core.Is.empty(options?.envFilenames)) {
         const envFile = path.resolve(path.join(options.executionDirectory ?? "", ".env"));
-        console.info("Default Environment File:", envFile);
+        cliCore.CLIDisplay.value("Default Environment File", envFile);
         options ??= {};
         options.envFilenames = [envFile];
         defaultEnvOnly = true;
@@ -2071,18 +2078,18 @@ async function buildConfiguration(processEnv, options, serverInfo) {
             const filePath = envVars[key].slice(6).trim();
             const embeddedFile = path.resolve(path.join(options.executionDirectory ?? "", filePath));
             if (envVars[key].startsWith("@text:")) {
-                console.info(`Expanding Environment Variable: ${key} from text file: ${embeddedFile}`);
+                cliCore.CLIDisplay.value(`Expanding Environment Variable: ${key} from text file`, embeddedFile);
                 envVars[key] = await loadTextFile(embeddedFile);
             }
             else if (envVars[key].startsWith("@json:")) {
-                console.info(`Expanding Environment Variable: ${key} from JSON file: ${embeddedFile}`);
+                cliCore.CLIDisplay.value(`Expanding Environment Variable: ${key} from JSON file`, embeddedFile);
                 envVars[key] = await loadJsonFile(embeddedFile);
             }
         }
     }
     // Extend the environment variables with any additional custom configuration.
     if (core.Is.function(options?.extendEnvVars)) {
-        console.info("Extending Environment Variables");
+        cliCore.CLIDisplay.task("Extending Environment Variables");
         await options.extendEnvVars(envVars);
     }
     // Build the engine configuration from the environment variables.
@@ -2091,19 +2098,19 @@ async function buildConfiguration(processEnv, options, serverInfo) {
     // Merge any custom configuration provided in the options.
     if (core.Is.arrayValue(options?.configFilenames)) {
         for (const configFile of options.configFilenames) {
-            console.info("Loading Configuration File:", configFile);
+            cliCore.CLIDisplay.value("Loading Configuration File", configFile);
             const configFilePath = path.resolve(path.join(options.executionDirectory ?? "", configFile));
             const config = await loadJsonFile(configFilePath);
             Object.assign(engineServerConfig, config);
         }
     }
     if (core.Is.objectValue(options?.config)) {
-        console.info("Merging Custom Configuration");
+        cliCore.CLIDisplay.task("Merging Custom Configuration");
         Object.assign(engineServerConfig, options.config);
     }
     // Merge any custom configuration provided in the options.
     if (core.Is.function(options?.extendConfig)) {
-        console.info("Extending Configuration");
+        cliCore.CLIDisplay.task("Extending Configuration");
         await options.extendConfig(envVars, engineServerConfig);
     }
     const nodeEngineConfig = await extensionsConfiguration(envVars, engineServerConfig);

package/dist/esm/index.mjs

@@ -1,5 +1,5 @@
 import { PasswordHelper } from '@twin.org/api-auth-entity-storage-service';
-import { I18n, Is, Coerce, Converter, RandomHelper, Urn, GeneralError, ErrorHelper, EnvHelper } from '@twin.org/core';
+import { I18n, Is, Coerce, Converter, RandomHelper, Urn, GeneralError, EnvHelper } from '@twin.org/core';
 import { PasswordGenerator, Bip39 } from '@twin.org/crypto';
 import { AuthenticationComponentType, InformationComponentType, RestRouteProcessorType, SocketRouteProcessorType, AuthenticationAdminComponentType } from '@twin.org/engine-server-types';
 import { WalletConnectorType, IdentityConnectorType, EntityStorageConnectorType, BlobStorageConnectorType, BlobStorageComponentType, VaultConnectorType, DltConfigType, LoggingConnectorType, LoggingComponentType, BackgroundTaskConnectorType, TaskSchedulerComponentType, EventBusConnectorType, EventBusComponentType, TelemetryConnectorType, TelemetryComponentType, MessagingEmailConnectorType, MessagingSmsConnectorType, MessagingPushNotificationConnectorType, MessagingAdminComponentType, MessagingComponentType, FaucetConnectorType, EngineTypeHelper, NftConnectorType, NftComponentType, VerifiableStorageConnectorType, VerifiableStorageComponentType, ImmutableProofComponentType, IdentityComponentType, IdentityResolverConnectorType, IdentityResolverComponentType, IdentityProfileConnectorType, IdentityProfileComponentType, AttestationConnectorType, AttestationComponentType, DataProcessingComponentType, DataConverterConnectorType, DataExtractorConnectorType, AuditableItemGraphComponentType, AuditableItemStreamComponentType, DocumentManagementComponentType, AuthenticationGeneratorComponentType, RightsManagementPapComponentType, RightsManagementPmpComponentType, RightsManagementPipComponentType, RightsManagementPxpComponentType, RightsManagementPdpComponentType, RightsManagementPepComponentType, RightsManagementPnpComponentType, RightsManagementPnapComponentType, RightsManagementDapComponentType, RightsManagementDarpComponentType, SynchronisedStorageComponentType, FederatedCatalogueComponentType, DataSpaceConnectorComponentType } from '@twin.org/engine-types';
@@ -9,6 +9,7 @@ import { VaultConnectorFactory, VaultKeyType } from '@twin.org/vault-models';
 import { WalletConnectorFactory } from '@twin.org/wallet-models';
 import { readFile, stat, readdir } from 'node:fs/promises';
 import path from 'node:path';
+import { CLIDisplay } from '@twin.org/cli-core';
 import { PolicyNegotiationPointClient, DataAccessPointClient } from '@twin.org/rights-management-rest-client';
 import { addDefaultRestPaths, addDefaultSocketPaths, EngineServer } from '@twin.org/engine-server';
 import { ModuleHelper } from '@twin.org/modules';
@@ -49,20 +50,19 @@ const NodeFeatures = {
 
 // Copyright 2024 IOTA Stiftung.
 // SPDX-License-Identifier: Apache-2.0.
-/* eslint-disable no-console */
 /**
  * Initialise the locales for the application.
  * @param localesDirectory The directory containing the locales.
  */
 async function initialiseLocales(localesDirectory) {
     const localesFile = path.resolve(path.join(localesDirectory, "en.json"));
-    console.info("Locales File:", localesFile);
+    CLIDisplay.value("Locales File", localesFile);
     if (await fileExists(localesFile)) {
         const enLangContent = await readFile(localesFile, "utf8");
         I18n.addDictionary("en", JSON.parse(enLangContent));
     }
     else {
-        console.warn(`Locales file not found: ${localesFile}`);
+        CLIDisplay.error(`Locales file not found: ${localesFile}`);
     }
 }
 /**
@@ -1794,7 +1794,6 @@ async function buildEngineServerConfiguration(envVars, coreEngineConfig, serverI
 
 // Copyright 2024 IOTA Stiftung.
 // SPDX-License-Identifier: Apache-2.0.
-/* eslint-disable no-console */
 /**
  * Handles the configuration of the extensions.
  * @param envVars The environment variables for the node.
@@ -1807,11 +1806,11 @@ async function extensionsConfiguration(envVars, nodeEngineConfig) {
         for (const extension of extensions) {
             let initialiseConfigMethod;
             try {
-                console.info(`Loading extension "${extension}"`);
+                CLIDisplay.value(I18n.formatMessage("node.extensionLoading"), extension);
                 initialiseConfigMethod = await ModuleHelper.getModuleMethod(extension, "extensionInitialise");
             }
             catch (err) {
-                console.error(`Failed to load extension "${extension}":`, err);
+                throw new GeneralError("node", "extensionLoadingError", { extension }, err);
             }
             if (Is.function(initialiseConfigMethod)) {
                 await initialiseConfigMethod(envVars, nodeEngineConfig);
@@ -1832,6 +1831,7 @@ async function extensionsInitialiseEngine(envVars, engineCore) {
         for (const extension of extensions) {
             let initialiseEngineMethod;
             try {
+                engineCore.logInfo(I18n.formatMessage("node.extensionInitialisingEngine", { extension }));
                 initialiseEngineMethod =
                     await ModuleHelper.getModuleMethod(extension, "extensionInitialiseEngine");
             }
@@ -1855,6 +1855,7 @@ async function extensionsInitialiseEngineServer(envVars, engineCore, engineServe
         for (const extension of extensions) {
             let initialiseEngineServerMethod;
             try {
+                engineCore.logInfo(I18n.formatMessage("node.extensionInitialisingEngineServer", { extension }));
                 initialiseEngineServerMethod =
                     await ModuleHelper.getModuleMethod(extension, "extensionInitialiseEngineServer");
             }
@@ -1868,14 +1869,16 @@ async function extensionsInitialiseEngineServer(envVars, engineCore, engineServe
 /**
  * Handles the shutdown of the extensions.
  * @param envVars The environment variables for the node.
+ * @param engineCore The engine core instance.
  * @returns Nothing.
  */
-async function shutdownExtensions(envVars) {
+async function shutdownExtensions(envVars, engineCore) {
     if (Is.stringValue(envVars.extensions)) {
         const extensions = envVars.extensions.split(",");
         for (const extension of extensions) {
             let shutdownMethod;
             try {
+                engineCore.logInfo(I18n.formatMessage("node.extensionShutdown", { extension }));
                 shutdownMethod = await ModuleHelper.getModuleMethod(extension, "extensionShutdown");
             }
             catch { }
@@ -1888,7 +1891,6 @@ async function shutdownExtensions(envVars) {
 
 // Copyright 2024 IOTA Stiftung.
 // SPDX-License-Identifier: Apache-2.0.
-/* eslint-disable no-console */
 /**
  * Start the engine server.
  * @param nodeOptions Optional run options for the engine server.
@@ -1919,13 +1921,13 @@ async function start(nodeOptions, nodeEngineConfig, envVars) {
     const server = new EngineServer({ engineCore: engine });
     // Extend the engine.
     if (Is.function(nodeOptions?.extendEngine)) {
-        console.info("Extending Engine");
+        engine.logInfo(I18n.formatMessage("node.extendingEngine"));
         await nodeOptions.extendEngine(engine);
     }
     await extensionsInitialiseEngine(envVars, engine);
     // Extend the engine server.
     if (Is.function(nodeOptions?.extendEngineServer)) {
-        console.info("Extending Engine Server");
+        engine.logInfo(I18n.formatMessage("node.extendingEngineServer"));
         await nodeOptions?.extendEngineServer(server);
     }
     await extensionsInitialiseEngineServer(envVars, engine, server);
@@ -1940,7 +1942,7 @@ async function start(nodeOptions, nodeEngineConfig, envVars) {
             server,
             shutdown: async () => {
                 await server.stop();
-                await shutdownExtensions(envVars);
+                await shutdownExtensions(envVars, engine);
             }
         };
     }
@@ -1948,7 +1950,6 @@ async function start(nodeOptions, nodeEngineConfig, envVars) {
 
 // Copyright 2024 IOTA Stiftung.
 // SPDX-License-Identifier: Apache-2.0.
-/* eslint-disable no-console */
 /**
  * Run the TWIN Node server.
  * @param nodeOptions Optional configuration options for running the server.
@@ -1959,42 +1960,48 @@ async function run(nodeOptions) {
         nodeOptions ??= {};
         const serverInfo = {
             name: nodeOptions?.serverName ?? "TWIN Node Server",
-            version: nodeOptions?.serverVersion ?? "0.0.2-next.17" // x-release-please-version
+            version: nodeOptions?.serverVersion ?? "0.0.2-next.18" // x-release-please-version
         };
-        console.log(`\u001B[4m🌩️  ${serverInfo.name} v${serverInfo.version}\u001B[24m\n`);
+        CLIDisplay.header(serverInfo.name, serverInfo.version, "🌩️ ");
         if (!Is.stringValue(nodeOptions?.executionDirectory)) {
             nodeOptions.executionDirectory = getExecutionDirectory();
         }
-        console.info("Execution Directory:", nodeOptions.executionDirectory);
+        CLIDisplay.value("Execution Directory", nodeOptions.executionDirectory);
         nodeOptions.localesDirectory =
             nodeOptions?.localesDirectory ??
                 path.resolve(path.join(nodeOptions.executionDirectory, "dist", "locales"));
-        console.info("Locales Directory:", nodeOptions.localesDirectory);
+        CLIDisplay.value("Locales Directory", nodeOptions.localesDirectory);
         await initialiseLocales(nodeOptions.localesDirectory);
         if (Is.empty(nodeOptions?.openApiSpecFile)) {
             const specFile = path.resolve(path.join(nodeOptions.executionDirectory ?? "", "docs", "open-api", "spec.json"));
-            console.info("Default OpenAPI Spec File:", specFile);
+            CLIDisplay.value("Default OpenAPI Spec File", specFile);
             if (await fileExists(specFile)) {
                 nodeOptions ??= {};
                 nodeOptions.openApiSpecFile = specFile;
             }
         }
+        else {
+            CLIDisplay.value("OpenAPI Spec File", nodeOptions.openApiSpecFile);
+        }
         if (Is.empty(nodeOptions?.favIconFile)) {
             const favIconFile = path.resolve(path.join(nodeOptions.executionDirectory ?? "", "static", "favicon.png"));
-            console.info("Default Favicon File:", favIconFile);
+            CLIDisplay.value("Default Favicon File", favIconFile);
             if (await fileExists(favIconFile)) {
                 nodeOptions ??= {};
                 nodeOptions.favIconFile = favIconFile;
             }
         }
+        else {
+            CLIDisplay.value("Favicon File", nodeOptions.favIconFile);
+        }
         nodeOptions.envPrefix ??= "TWIN_NODE_";
-        console.info("Environment Prefix:", nodeOptions.envPrefix);
+        CLIDisplay.value("Environment Variable Prefix", nodeOptions.envPrefix);
         overrideModuleImport(nodeOptions.executionDirectory ?? "");
         const { nodeEngineConfig, nodeEnvVars: envVars } = await buildConfiguration(
         // This is the only location in the code base that should access process.env directly
         // eslint-disable-next-line no-restricted-syntax
         process.env, nodeOptions, serverInfo);
-        console.info();
+        CLIDisplay.break();
         const startResult = await start(nodeOptions, nodeEngineConfig, envVars);
         if (!Is.empty(startResult)) {
             for (const signal of ["SIGHUP", "SIGINT", "SIGTERM"]) {
@@ -2005,7 +2012,7 @@ async function run(nodeOptions) {
         }
     }
     catch (err) {
-        console.error(ErrorHelper.formatErrors(err).join("\n"));
+        CLIDisplay.error(err);
         // eslint-disable-next-line unicorn/no-process-exit
         process.exit(1);
     }
@@ -2022,7 +2029,7 @@ async function buildConfiguration(processEnv, options, serverInfo) {
     let defaultEnvOnly = false;
     if (Is.empty(options?.envFilenames)) {
         const envFile = path.resolve(path.join(options.executionDirectory ?? "", ".env"));
-        console.info("Default Environment File:", envFile);
+        CLIDisplay.value("Default Environment File", envFile);
         options ??= {};
         options.envFilenames = [envFile];
         defaultEnvOnly = true;
@@ -2050,18 +2057,18 @@ async function buildConfiguration(processEnv, options, serverInfo) {
             const filePath = envVars[key].slice(6).trim();
             const embeddedFile = path.resolve(path.join(options.executionDirectory ?? "", filePath));
             if (envVars[key].startsWith("@text:")) {
-                console.info(`Expanding Environment Variable: ${key} from text file: ${embeddedFile}`);
+                CLIDisplay.value(`Expanding Environment Variable: ${key} from text file`, embeddedFile);
                 envVars[key] = await loadTextFile(embeddedFile);
             }
             else if (envVars[key].startsWith("@json:")) {
-                console.info(`Expanding Environment Variable: ${key} from JSON file: ${embeddedFile}`);
+                CLIDisplay.value(`Expanding Environment Variable: ${key} from JSON file`, embeddedFile);
                 envVars[key] = await loadJsonFile(embeddedFile);
             }
         }
     }
     // Extend the environment variables with any additional custom configuration.
     if (Is.function(options?.extendEnvVars)) {
-        console.info("Extending Environment Variables");
+        CLIDisplay.task("Extending Environment Variables");
         await options.extendEnvVars(envVars);
     }
     // Build the engine configuration from the environment variables.
@@ -2070,19 +2077,19 @@ async function buildConfiguration(processEnv, options, serverInfo) {
     // Merge any custom configuration provided in the options.
     if (Is.arrayValue(options?.configFilenames)) {
         for (const configFile of options.configFilenames) {
-            console.info("Loading Configuration File:", configFile);
+            CLIDisplay.value("Loading Configuration File", configFile);
             const configFilePath = path.resolve(path.join(options.executionDirectory ?? "", configFile));
             const config = await loadJsonFile(configFilePath);
             Object.assign(engineServerConfig, config);
         }
     }
     if (Is.objectValue(options?.config)) {
-        console.info("Merging Custom Configuration");
+        CLIDisplay.task("Merging Custom Configuration");
         Object.assign(engineServerConfig, options.config);
     }
     // Merge any custom configuration provided in the options.
     if (Is.function(options?.extendConfig)) {
-        console.info("Extending Configuration");
+        CLIDisplay.task("Extending Configuration");
         await options.extendConfig(envVars, engineServerConfig);
     }
     const nodeEngineConfig = await extensionsConfiguration(envVars, engineServerConfig);

package/dist/types/builders/extensionsBuilder.d.ts

@@ -26,6 +26,7 @@ export declare function extensionsInitialiseEngineServer(envVars: INodeEnvironme
 /**
  * Handles the shutdown of the extensions.
  * @param envVars The environment variables for the node.
+ * @param engineCore The engine core instance.
  * @returns Nothing.
  */
-export declare function shutdownExtensions(envVars: INodeEnvironmentVariables): Promise<void>;
+export declare function shutdownExtensions(envVars: INodeEnvironmentVariables, engineCore: IEngineCore): Promise<void>;

package/dist/types/models/nodeExtensionMethods.d.ts

@@ -20,3 +20,8 @@ export type NodeExtensionInitialiseEngineMethod = (engineCore: IEngineCore) => P
  * @param engineServer The engine server instance.
  */
 export type NodeExtensionInitialiseEngineServerMethod = (engineCore: IEngineCore, engineServer: IEngineServer) => Promise<void>;
+/**
+ * The type for the shutdown method of an extension module.
+ * This is called when the engine is shutting down.
+ */
+export type NodeExtensionShutdownMethod = () => Promise<void>;

package/docs/changelog.md

@@ -1,5 +1,12 @@
 # @twin.org/node-core - Changelog
 
+## [0.0.2-next.18](https://github.com/twinfoundation/node/compare/node-core-v0.0.2-next.17...node-core-v0.0.2-next.18) (2025-10-03)
+
+
+### Features
+
+* improve error handling for extensions and logging ([bd84fde](https://github.com/twinfoundation/node/commit/bd84fde67e5a9db6ac66730397992401ca52e88c))
+
 ## [0.0.2-next.17](https://github.com/twinfoundation/node/compare/node-core-v0.0.2-next.16...node-core-v0.0.2-next.17) (2025-10-02)
 
 

package/docs/reference/functions/shutdownExtensions.md

@@ -1,6 +1,6 @@
 # Function: shutdownExtensions()
 
-> **shutdownExtensions**(`envVars`): `Promise`\<`void`\>
+> **shutdownExtensions**(`envVars`, `engineCore`): `Promise`\<`void`\>
 
 Handles the shutdown of the extensions.
 
@@ -12,6 +12,12 @@ Handles the shutdown of the extensions.
 
 The environment variables for the node.
 
+### engineCore
+
+`IEngineCore`
+
+The engine core instance.
+
 ## Returns
 
 `Promise`\<`void`\>

package/docs/reference/index.md

@@ -13,6 +13,7 @@
 - [NodeExtensionInitialiseMethod](type-aliases/NodeExtensionInitialiseMethod.md)
 - [NodeExtensionInitialiseEngineMethod](type-aliases/NodeExtensionInitialiseEngineMethod.md)
 - [NodeExtensionInitialiseEngineServerMethod](type-aliases/NodeExtensionInitialiseEngineServerMethod.md)
+- [NodeExtensionShutdownMethod](type-aliases/NodeExtensionShutdownMethod.md)
 - [NodeFeatures](type-aliases/NodeFeatures.md)
 
 ## Variables

package/docs/reference/type-aliases/NodeExtensionShutdownMethod.md

@@ -0,0 +1,10 @@
+# Type Alias: NodeExtensionShutdownMethod()
+
+> **NodeExtensionShutdownMethod** = () => `Promise`\<`void`\>
+
+The type for the shutdown method of an extension module.
+This is called when the engine is shutting down.
+
+## Returns
+
+`Promise`\<`void`\>

package/locales/en.json

@@ -1,7 +1,8 @@
 {
 	"error": {
 		"node": {
-			"storageFileRootNotSet": "{storageFileRoot} is not set, the server will not start without it, please set it in the shell or create a .env file"
+			"storageFileRootNotSet": "{storageFileRoot} is not set, the server will not start without it, please set it in the shell or create a .env file",
+			"extensionLoadingError": "Failed to load extension \"{extension}\""
 		}
 	},
 	"node": {
@@ -31,6 +32,12 @@
 		"existingUserProfile": "User profile already exists \"{identity}\"",
 		"nodeIdentity": "Node identity \"{identity}\"",
 		"nodeAdminUserEmail": "Node Admin User Email \"{email}\"",
-		"nodeAdminUserPassword": "Node Admin User Password \"{password}\""
+		"nodeAdminUserPassword": "Node Admin User Password \"{password}\"",
+		"extensionLoading": "Loading Extension",
+		"extensionInitialisingEngine": "Initialising engine for extension \"{extension}\"",
+		"extensionInitialisingEngineServer": "Initialising engine server for extension \"{extension}\"",
+		"extensionShutdown": "Shutdown extension \"{extension}\"",
+		"extendingEngine": "Extending Engine",
+		"extendingEngineServer": "Extending Engine Server"
 	}
 }

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@twin.org/node-core",
-	"version": "0.0.2-next.17",
+	"version": "0.0.2-next.18",
 	"description": "TWIN Node Core for serving APIs using the specified configuration",
 	"repository": {
 		"type": "git",
@@ -15,6 +15,7 @@
 	},
 	"dependencies": {
 		"@twin.org/api-auth-entity-storage-service": "next",
+		"@twin.org/cli-core": "next",
 		"@twin.org/core": "next",
 		"@twin.org/crypto": "next",
 		"@twin.org/data-space-connector-models": "next",