@twin.org/node-core 0.0.3-next.6 → 0.0.3-next.60

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/buildEngineConfiguration.md

@@ -1,6 +1,6 @@
 # Function: buildEngineConfiguration()
 
-> **buildEngineConfiguration**(`envVars`, `contextIdKeys`): `Promise`\<`IEngineConfig`\>
+> **buildEngineConfiguration**(`envVars`): `Promise`\<`IEngineConfig`\>
 
 Build the engine core configuration from environment variables.
 
@@ -12,12 +12,6 @@ Build the engine core configuration from environment variables.
 
 The environment variables.
 
-### contextIdKeys
-
-`object`[]
-
-The context ID keys.
-
 ## Returns
 
 `Promise`\<`IEngineConfig`\>

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/extensionsInitialiseEngine.md

@@ -22,4 +22,4 @@ The engine core instance.
 
 `Promise`\<`void`\>
 
-Nothing.
+A promise that resolves when all extension engine initialisation methods have completed.

package/docs/reference/functions/extensionsInitialiseEngineServer.md

@@ -28,4 +28,4 @@ The engine server instance.
 
 `Promise`\<`void`\>
 
-Nothing.
+A promise that resolves when all extension engine-server initialisation methods have completed.

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 directory containing the entry-point script, or the current working directory if not determinable.

package/docs/reference/functions/initialiseLocales.md

@@ -15,3 +15,5 @@ The directory containing the locales.
 ## Returns
 
 `Promise`\<`void`\>
+
+A promise that resolves when the locale dictionary has been loaded.

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 federated catalogue subsystem is required.
+Returns true when the catalogue is explicitly enabled, a remote endpoint is configured, filters are set, or dataspace is enabled.
+
+## Parameters
+
+### envVars
+
+[`IEngineEnvironmentVariables`](../interfaces/IEngineEnvironmentVariables.md)
+
+The environment variables.
+
+## Returns
+
+`boolean`
+
+True if the federated catalogue is required.

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,23 @@
+# 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.
+Note: rights management has no standalone enable flag - it is gated entirely on
+`dataspaceEnabled`. Setting `TWIN_RIGHTS_MANAGEMENT_*` env var in isolation does not
+enable the subsystem; `TWIN_DATASPACE_ENABLED` must also be true.
+
+## 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, or dataspace is enabled.

package/docs/reference/functions/loadJsonFile.md

@@ -22,4 +22,4 @@ The filename of the JSON file to load.
 
 `Promise`\<`T`\>
 
-The contents of the JSON file or null if it could not be loaded.
+The parsed JSON content of the file.

package/docs/reference/functions/loadTextFile.md

@@ -16,4 +16,4 @@ The filename of the text file to load.
 
 `Promise`\<`string`\>
 
-The contents of the text file if it could not be loaded.
+The contents of the text file as a UTF-8 string.

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 substituted options, mutated in place with env variable values resolved.
+
+## Throws
+
+GeneralError if an env file has errors.

package/docs/reference/functions/registerCommands.md

@@ -0,0 +1,9 @@
+# Function: registerCommands()
+
+> **registerCommands**(): `void`
+
+Register all built-in CLI command definitions into the shared command map.
+
+## 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/shutdownExtensions.md

@@ -22,4 +22,4 @@ The engine core instance.
 
 `Promise`\<`void`\>
 
-Nothing.
+A promise that resolves when all extension shutdown methods have completed.

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.