@twin.org/node-core 0.0.3-next.4 → 0.0.3-next.40

package/docs/examples.md

@@ -1 +1,99 @@
-# @twin.org/node-core - Examples
+# Node Core Examples
+
+These snippets show practical runtime setup patterns, state inspection, and controlled shutdown so you can move from local development to automation with predictable behaviour.
+
+## Engine
+
+```typescript
+import { run } from '@twin.org/node-core';
+
+const runtime = await run(
+  {
+    disableProcessExitOnFailure: true,
+    envVars: {
+      TWIN_HOST: '127.0.0.1',
+      TWIN_PORT: '8080',
+      TWIN_STORAGE_FILE_ROOT: './storage',
+      TWIN_STATE_FILENAME: 'engine-state.json'
+    }
+  },
+  ['node', 'index.js']
+);
+
+if (runtime) {
+  const state = runtime.engine.getState();
+  console.log(typeof state); // object
+  console.log(state.nodeId ?? 'not-configured'); // not-configured
+  await runtime.shutdown();
+}
+```
+
+```typescript
+import { run } from '@twin.org/node-core';
+
+const runtime = await run(
+  {
+    disableProcessExitOnFailure: true,
+    envVars: {
+      TWIN_HOST: '127.0.0.1',
+      TWIN_PORT: '8081',
+      TWIN_STORAGE_FILE_ROOT: './storage',
+      TWIN_STATE_FILENAME: 'engine-state.json'
+    }
+  },
+  ['node', 'index.js']
+);
+
+if (runtime) {
+  await runtime.engine.logInfo('Startup validation completed');
+  const state = runtime.engine.getState();
+  console.log(Object.keys(state).length >= 0); // true
+  await runtime.shutdown();
+}
+```
+
+## EngineServer
+
+```typescript
+import type { IServerInfo } from '@twin.org/api-models';
+import type { INodeOptions } from '@twin.org/node-core';
+import { buildConfiguration, start } from '@twin.org/node-core';
+
+const processEnv: Record<string, string> = {
+  TWIN_HOST: '127.0.0.1',
+  TWIN_PORT: '8082',
+  TWIN_STORAGE_FILE_ROOT: './storage',
+  TWIN_STATE_FILENAME: 'engine-state.json'
+};
+
+const options: INodeOptions = {
+  disableProcessExitOnFailure: true,
+  envPrefix: 'TWIN_',
+  executionDirectory: process.cwd(),
+  scriptDirectory: process.cwd()
+};
+
+const serverInfo: IServerInfo = {
+  name: 'Local Runtime',
+  version: '0.0.0-dev'
+};
+
+const { nodeEngineConfig, nodeEnvVars, availableContextIdKeys } = await buildConfiguration(
+  processEnv,
+  options,
+  serverInfo
+);
+
+const runtime = await start(
+  options,
+  nodeEngineConfig,
+  nodeEnvVars,
+  undefined,
+  availableContextIdKeys
+);
+
+if (runtime) {
+  console.log(typeof runtime.server.stop); // function
+  await runtime.server.stop();
+}
+```

package/docs/reference/functions/buildConfiguration.md

@@ -2,7 +2,7 @@
 
 > **buildConfiguration**(`processEnv`, `options`, `serverInfo`): `Promise`\<\{ `nodeEnvVars`: [`INodeEnvironmentVariables`](../interfaces/INodeEnvironmentVariables.md) & `object`; `nodeEngineConfig`: [`INodeEngineConfig`](../interfaces/INodeEngineConfig.md); `availableContextIdKeys`: `object`[]; \}\>
 
-Build the configuration for the TWIN Node server.
+Build the configuration for the TWIN Node.
 
 ## Parameters
 

package/docs/reference/functions/buildEngineServerConfiguration.md

@@ -8,7 +8,7 @@ Handles the configuration of the server.
 
 ### envVars
 
-[`IEngineServerEnvironmentVariables`](../interfaces/IEngineServerEnvironmentVariables.md)
+[`IEngineServerEnvironmentVariables`](../interfaces/IEngineServerEnvironmentVariables.md) & `object`
 
 The environment variables for the engine server.
 

package/docs/reference/functions/constructCliCommand.md

@@ -0,0 +1,27 @@
+# Function: constructCliCommand()
+
+> **constructCliCommand**(`processEnv`, `cliArgs`): [`ICliCommand`](../interfaces/ICliCommand.md) \| `undefined`
+
+Construct the CLI command from the parsed arguments.
+
+## Parameters
+
+### processEnv
+
+The environment variables from the process.
+
+### cliArgs
+
+[`ICliArgs`](../interfaces/ICliArgs.md)
+
+The parsed CLI arguments.
+
+## Returns
+
+[`ICliCommand`](../interfaces/ICliCommand.md) \| `undefined`
+
+The constructed CLI command.
+
+## Throws
+
+GeneralError if the command is missing.

package/docs/reference/functions/executeCommand.md

@@ -0,0 +1,29 @@
+# Function: executeCommand()
+
+> **executeCommand**(`engineCore`, `envVars`, `cliCommand`): `Promise`\<`void`\>
+
+Execute the CLI command.
+
+## Parameters
+
+### engineCore
+
+`IEngineCore`
+
+The engine core.
+
+### envVars
+
+[`INodeEnvironmentVariables`](../interfaces/INodeEnvironmentVariables.md)
+
+The environment variables for the node.
+
+### cliCommand
+
+[`ICliCommand`](../interfaces/ICliCommand.md)
+
+The CLI command to execute.
+
+## Returns
+
+`Promise`\<`void`\>

package/docs/reference/functions/getEnvDefaults.md

@@ -0,0 +1,19 @@
+# Function: getEnvDefaults()
+
+> **getEnvDefaults**(`envPrefix`): `object`
+
+Get the default environment variables for the node.
+
+## Parameters
+
+### envPrefix
+
+`string`
+
+The environment variable prefix.
+
+## Returns
+
+`object`
+
+The default environment variables.

package/docs/reference/functions/getScriptDirectory.md

@@ -0,0 +1,19 @@
+# Function: getScriptDirectory()
+
+> **getScriptDirectory**(`args?`): `string`
+
+Get the directory where the script is located.
+
+## Parameters
+
+### args?
+
+`string`[]
+
+The command line arguments.
+
+## Returns
+
+`string`
+
+The execution directory.

package/docs/reference/functions/isAuthEntityStorageRequired.md

@@ -0,0 +1,20 @@
+# Function: isAuthEntityStorageRequired()
+
+> **isAuthEntityStorageRequired**(`envVars`): `boolean`
+
+Checks if the authentication entity storage subsystem is required.
+Returns true when any component that depends on the authentication entity storage subsystem is enabled.
+
+## Parameters
+
+### envVars
+
+[`IEngineServerEnvironmentVariables`](../interfaces/IEngineServerEnvironmentVariables.md)
+
+The environment variables.
+
+## Returns
+
+`boolean`
+
+True if authentication entity storage is enabled.

package/docs/reference/functions/isAutomationRequired.md

@@ -0,0 +1,20 @@
+# Function: isAutomationRequired()
+
+> **isAutomationRequired**(`envVars`): `boolean`
+
+Checks if the automation subsystem is required.
+Returns true when any component that depends on the automation subsystem is enabled.
+
+## Parameters
+
+### envVars
+
+[`IEngineEnvironmentVariables`](../interfaces/IEngineEnvironmentVariables.md)
+
+The environment variables.
+
+## Returns
+
+`boolean`
+
+True if automation is enabled.

package/docs/reference/functions/isBackgroundTasksRequired.md

@@ -0,0 +1,20 @@
+# Function: isBackgroundTasksRequired()
+
+> **isBackgroundTasksRequired**(`envVars`): `boolean`
+
+Checks if the background tasks subsystem is required.
+Returns true when any component that depends on the background tasks subsystem is enabled.
+
+## Parameters
+
+### envVars
+
+[`IEngineEnvironmentVariables`](../interfaces/IEngineEnvironmentVariables.md)
+
+The environment variables.
+
+## Returns
+
+`boolean`
+
+True if dataspace or verifiable storage is enabled.

package/docs/reference/functions/isFederatedCatalogueRequired.md

@@ -0,0 +1,20 @@
+# Function: isFederatedCatalogueRequired()
+
+> **isFederatedCatalogueRequired**(`envVars`): `boolean`
+
+Checks if the immutable proof subsystem is required.
+Returns true when any component that depends on the immutable proof subsystem is enabled.
+
+## Parameters
+
+### envVars
+
+[`IEngineEnvironmentVariables`](../interfaces/IEngineEnvironmentVariables.md)
+
+The environment variables.
+
+## Returns
+
+`boolean`
+
+True if verifiable storage is enabled.

package/docs/reference/functions/isImmutableProofRequired.md

@@ -0,0 +1,20 @@
+# Function: isImmutableProofRequired()
+
+> **isImmutableProofRequired**(`envVars`): `boolean`
+
+Checks if the immutable proof subsystem is required.
+Returns true when any component that depends on the immutable proof subsystem is enabled.
+
+## Parameters
+
+### envVars
+
+[`IEngineEnvironmentVariables`](../interfaces/IEngineEnvironmentVariables.md)
+
+The environment variables.
+
+## Returns
+
+`boolean`
+
+True if verifiable storage is enabled.

package/docs/reference/functions/isRightsManagementRequired.md

@@ -0,0 +1,20 @@
+# Function: isRightsManagementRequired()
+
+> **isRightsManagementRequired**(`envVars`): `boolean`
+
+Checks if the rights management subsystem is required.
+Returns true when any component that depends on the rights management subsystem is enabled.
+
+## Parameters
+
+### envVars
+
+[`IEngineEnvironmentVariables`](../interfaces/IEngineEnvironmentVariables.md)
+
+The environment variables.
+
+## Returns
+
+`boolean`
+
+True if rights management is enabled.

package/docs/reference/functions/isTaskSchedulerRequired.md

@@ -0,0 +1,20 @@
+# Function: isTaskSchedulerRequired()
+
+> **isTaskSchedulerRequired**(`envVars`): `boolean`
+
+Checks if the task scheduler subsystem is required.
+Returns true when any component that depends on the task scheduler subsystem is enabled.
+
+## Parameters
+
+### envVars
+
+[`IEngineEnvironmentVariables`](../interfaces/IEngineEnvironmentVariables.md)
+
+The environment variables.
+
+## Returns
+
+`boolean`
+
+True if task scheduler is enabled.

package/docs/reference/functions/isTelemetryRequired.md

@@ -0,0 +1,20 @@
+# Function: isTelemetryRequired()
+
+> **isTelemetryRequired**(`envVars`): `boolean`
+
+Checks if the telemetry subsystem is required.
+Returns true when any component that depends on the telemetry subsystem is enabled.
+
+## Parameters
+
+### envVars
+
+[`IEngineEnvironmentVariables`](../interfaces/IEngineEnvironmentVariables.md)
+
+The environment variables.
+
+## Returns
+
+`boolean`
+
+True if telemetry is enabled.

package/docs/reference/functions/isTrustRequired.md

@@ -0,0 +1,20 @@
+# Function: isTrustRequired()
+
+> **isTrustRequired**(`envVars`): `boolean`
+
+Checks if the trust subsystem is required.
+Returns true when any component that depends on the trust subsystem is enabled.
+
+## Parameters
+
+### envVars
+
+[`IEngineEnvironmentVariables`](../interfaces/IEngineEnvironmentVariables.md)
+
+The environment variables.
+
+## Returns
+
+`boolean`
+
+True if rights-management, synchronised-storage, or dataspace is enabled.

package/docs/reference/functions/isUrlTransformerRequired.md

@@ -0,0 +1,20 @@
+# Function: isUrlTransformerRequired()
+
+> **isUrlTransformerRequired**(`envVars`): `boolean`
+
+Checks if the URL transformer subsystem is required.
+Returns true when any component that depends on the URL transformer subsystem is enabled.
+
+## Parameters
+
+### envVars
+
+[`IEngineEnvironmentVariables`](../interfaces/IEngineEnvironmentVariables.md)
+
+The environment variables.
+
+## Returns
+
+`boolean`
+
+True if rights-management, dataspace, federated-catalogue, or tenant is enabled.

package/docs/reference/functions/parseCommandLineArgs.md

@@ -0,0 +1,19 @@
+# Function: parseCommandLineArgs()
+
+> **parseCommandLineArgs**(`args?`): [`ICliArgs`](../interfaces/ICliArgs.md)
+
+Parse command line arguments.
+
+## Parameters
+
+### args?
+
+`string`[]
+
+The command line arguments.
+
+## Returns
+
+[`ICliArgs`](../interfaces/ICliArgs.md)
+
+The parsed command line arguments.

package/docs/reference/functions/processEnvOptions.md

@@ -0,0 +1,27 @@
+# Function: processEnvOptions()
+
+> **processEnvOptions**(`processEnv`, `options`): `void`
+
+Load the env files and process the options.
+
+## Parameters
+
+### processEnv
+
+The environment variables from the process.
+
+### options
+
+`object`[]
+
+The options.
+
+## Returns
+
+`void`
+
+The processed parameters.
+
+## Throws
+
+GeneralError if an env file has errors.

package/docs/reference/functions/registerCommands.md

@@ -0,0 +1,9 @@
+# Function: registerCommands()
+
+> **registerCommands**(): `void`
+
+Register available CLI commands.
+
+## Returns
+
+`void`

package/docs/reference/functions/resolvePackageEntryPoint.md

@@ -1,6 +1,6 @@
 # Function: resolvePackageEntryPoint()
 
-> **resolvePackageEntryPoint**(`packagePath`, `packageName`, `fallback`): `Promise`\<`string`\>
+> **resolvePackageEntryPoint**(`packagePath`, `packageName`, `fallback?`): `Promise`\<`string`\>
 
 Resolve the main entry point from a package directory using Node.js resolution with fallback.
 Uses require.resolve() when possible for standard Node.js behavior, with manual fallback.
@@ -19,7 +19,7 @@ The absolute path to the package directory.
 
 The package name for require.resolve().
 
-### fallback
+### fallback?
 
 `string` = `"index.js"`
 

package/docs/reference/functions/run.md

@@ -1,8 +1,8 @@
 # Function: run()
 
-> **run**(`nodeOptions?`): `Promise`\<\{ `engine`: `Engine`\<`IEngineServerConfig`, [`INodeEngineState`](../interfaces/INodeEngineState.md)\>; `server`: `EngineServer`; `shutdown`: () => `Promise`\<`void`\>; \} \| `undefined`\>
+> **run**(`nodeOptions?`, `args?`): `Promise`\<\{ `engine`: `Engine`\<`IEngineServerConfig`, [`INodeEngineState`](../interfaces/INodeEngineState.md)\>; `server`: `EngineServer`; `shutdown`: () => `Promise`\<`void`\>; \} \| `undefined`\>
 
-Run the TWIN Node server.
+Run the TWIN Node.
 
 ## Parameters
 
@@ -12,6 +12,12 @@ Run the TWIN Node server.
 
 Optional configuration options for running the server.
 
+### args?
+
+`string`[]
+
+Optional command line arguments.
+
 ## Returns
 
 `Promise`\<\{ `engine`: `Engine`\<`IEngineServerConfig`, [`INodeEngineState`](../interfaces/INodeEngineState.md)\>; `server`: `EngineServer`; `shutdown`: () => `Promise`\<`void`\>; \} \| `undefined`\>

package/docs/reference/functions/start.md

@@ -1,6 +1,6 @@
 # Function: start()
 
-> **start**(`nodeOptions`, `nodeEngineConfig`, `envVars`, `availableContextIdKeys?`): `Promise`\<\{ `engine`: `Engine`\<`IEngineServerConfig`, [`INodeEngineState`](../interfaces/INodeEngineState.md)\>; `server`: `EngineServer`; `shutdown`: () => `Promise`\<`void`\>; \} \| `undefined`\>
+> **start**(`nodeOptions`, `nodeEngineConfig`, `envVars`, `cliCommand?`, `availableContextIdKeys?`): `Promise`\<\{ `engine`: `Engine`\<`IEngineServerConfig`, [`INodeEngineState`](../interfaces/INodeEngineState.md)\>; `server`: `EngineServer`; `shutdown`: () => `Promise`\<`void`\>; \} \| `undefined`\>
 
 Start the engine server.
 
@@ -8,9 +8,9 @@ Start the engine server.
 
 ### nodeOptions
 
-Optional run options for the engine server.
+[`INodeOptions`](../interfaces/INodeOptions.md) \| `undefined`
 
-[`INodeOptions`](../interfaces/INodeOptions.md) | `undefined`
+Optional run options for the engine server.
 
 ### nodeEngineConfig
 
@@ -24,6 +24,12 @@ The configuration for the engine server.
 
 The environment variables.
 
+### cliCommand?
+
+[`ICliCommand`](../interfaces/ICliCommand.md)
+
+The constructed CLI command (optional).
+
 ### availableContextIdKeys?
 
 `object`[]

package/docs/reference/functions/substituteEnvOptions.md

@@ -0,0 +1,25 @@
+# Function: substituteEnvOptions()
+
+> **substituteEnvOptions**(`processEnv`, `options`): `void`
+
+Process options and replace any env variables with their values.
+
+## Parameters
+
+### processEnv
+
+The environment variables from the process.
+
+### options
+
+`object`[]
+
+The options.
+
+## Returns
+
+`void`
+
+## Throws
+
+GeneralError if an env variable is missing.

package/docs/reference/index.md

@@ -3,6 +3,10 @@
 ## Interfaces
 
 - [ICacheMetadata](interfaces/ICacheMetadata.md)
+- [ICliArgs](interfaces/ICliArgs.md)
+- [ICliCommand](interfaces/ICliCommand.md)
+- [ICliCommandDefinition](interfaces/ICliCommandDefinition.md)
+- [ICliCommandDefinitionParam](interfaces/ICliCommandDefinitionParam.md)
 - [IEngineEnvironmentVariables](interfaces/IEngineEnvironmentVariables.md)
 - [IEngineServerEnvironmentVariables](interfaces/IEngineServerEnvironmentVariables.md)
 - [IModuleProtocol](interfaces/IModuleProtocol.md)
@@ -14,12 +18,12 @@
 
 ## Type Aliases
 
+- [CliCommandParamType](type-aliases/CliCommandParamType.md)
 - [ModuleProtocol](type-aliases/ModuleProtocol.md)
-- [NodeExtensionInitialiseMethod](type-aliases/NodeExtensionInitialiseMethod.md)
 - [NodeExtensionInitialiseEngineMethod](type-aliases/NodeExtensionInitialiseEngineMethod.md)
 - [NodeExtensionInitialiseEngineServerMethod](type-aliases/NodeExtensionInitialiseEngineServerMethod.md)
+- [NodeExtensionInitialiseMethod](type-aliases/NodeExtensionInitialiseMethod.md)
 - [NodeExtensionShutdownMethod](type-aliases/NodeExtensionShutdownMethod.md)
-- [NodeFeatures](type-aliases/NodeFeatures.md)
 
 ## Variables
 
@@ -27,42 +31,51 @@
 - [IMMUTABLE\_PROOF\_VERIFICATION\_METHOD\_ID](variables/IMMUTABLE_PROOF_VERIFICATION_METHOD_ID.md)
 - [BLOB\_STORAGE\_ENCRYPTION\_KEY\_ID](variables/BLOB_STORAGE_ENCRYPTION_KEY_ID.md)
 - [SYNCHRONISED\_STORAGE\_BLOB\_STORAGE\_ENCRYPTION\_KEY\_ID](variables/SYNCHRONISED_STORAGE_BLOB_STORAGE_ENCRYPTION_KEY_ID.md)
-- [VC\_AUTHENTICATION\_VERIFICATION\_METHOD\_ID](variables/VC_AUTHENTICATION_VERIFICATION_METHOD_ID.md)
+- [TRUST\_VERIFICATION\_METHOD\_ID](variables/TRUST_VERIFICATION_METHOD_ID.md)
 - [AUTH\_SIGNING\_KEY\_ID](variables/AUTH_SIGNING_KEY_ID.md)
+- [URL\_TRANSFORMER\_ENCRYPTION\_KEY\_ID](variables/URL_TRANSFORMER_ENCRYPTION_KEY_ID.md)
 - [CONTEXT\_ID\_HANDLER\_FEATURE\_DID](variables/CONTEXT_ID_HANDLER_FEATURE_DID.md)
 - [CONTEXT\_ID\_HANDLER\_FEATURE\_TENANT](variables/CONTEXT_ID_HANDLER_FEATURE_TENANT.md)
 - [ModuleProtocol](variables/ModuleProtocol.md)
-- [NodeFeatures](variables/NodeFeatures.md)
 
 ## Functions
 
-- [bootstrap](functions/bootstrap.md)
-- [bootstrapNodeId](functions/bootstrapNodeId.md)
-- [bootstrapTenantId](functions/bootstrapTenantId.md)
-- [bootstrapNodeAdminUser](functions/bootstrapNodeAdminUser.md)
-- [bootstrapImmutableProofMethod](functions/bootstrapImmutableProofMethod.md)
-- [bootstrapBlobEncryption](functions/bootstrapBlobEncryption.md)
-- [bootstrapAuth](functions/bootstrapAuth.md)
-- [bootstrapSynchronisedStorage](functions/bootstrapSynchronisedStorage.md)
 - [buildEngineConfiguration](functions/buildEngineConfiguration.md)
+- [isTrustRequired](functions/isTrustRequired.md)
+- [isUrlTransformerRequired](functions/isUrlTransformerRequired.md)
+- [isBackgroundTasksRequired](functions/isBackgroundTasksRequired.md)
+- [isImmutableProofRequired](functions/isImmutableProofRequired.md)
+- [isFederatedCatalogueRequired](functions/isFederatedCatalogueRequired.md)
+- [isRightsManagementRequired](functions/isRightsManagementRequired.md)
+- [isTaskSchedulerRequired](functions/isTaskSchedulerRequired.md)
+- [isAutomationRequired](functions/isAutomationRequired.md)
+- [isTelemetryRequired](functions/isTelemetryRequired.md)
 - [buildEngineServerConfiguration](functions/buildEngineServerConfiguration.md)
+- [isAuthEntityStorageRequired](functions/isAuthEntityStorageRequired.md)
 - [extensionsConfiguration](functions/extensionsConfiguration.md)
 - [extensionsInitialiseEngine](functions/extensionsInitialiseEngine.md)
 - [extensionsInitialiseEngineServer](functions/extensionsInitialiseEngineServer.md)
 - [shutdownExtensions](functions/shutdownExtensions.md)
+- [parseCommandLineArgs](functions/parseCommandLineArgs.md)
+- [constructCliCommand](functions/constructCliCommand.md)
+- [executeCommand](functions/executeCommand.md)
+- [processEnvOptions](functions/processEnvOptions.md)
+- [substituteEnvOptions](functions/substituteEnvOptions.md)
+- [registerCommands](functions/registerCommands.md)
+- [getEnvDefaults](functions/getEnvDefaults.md)
 - [run](functions/run.md)
 - [buildConfiguration](functions/buildConfiguration.md)
 - [overrideModuleImport](functions/overrideModuleImport.md)
 - [start](functions/start.md)
 - [initialiseLocales](functions/initialiseLocales.md)
 - [getExecutionDirectory](functions/getExecutionDirectory.md)
+- [getScriptDirectory](functions/getScriptDirectory.md)
 - [fileExists](functions/fileExists.md)
 - [directoryExists](functions/directoryExists.md)
 - [getSubFolders](functions/getSubFolders.md)
 - [getFiles](functions/getFiles.md)
 - [loadTextFile](functions/loadTextFile.md)
 - [loadJsonFile](functions/loadJsonFile.md)
-- [getFeatures](functions/getFeatures.md)
 - [parseModuleProtocol](functions/parseModuleProtocol.md)
 - [hashUrl](functions/hashUrl.md)
 - [getExtensionsCacheDir](functions/getExtensionsCacheDir.md)