@twin.org/node-core 0.0.3-next.3 → 0.0.3-next.31

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/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)
 - [NodeExtensionShutdownMethod](type-aliases/NodeExtensionShutdownMethod.md)
-- [NodeFeatures](type-aliases/NodeFeatures.md)
 
 ## Variables
 
@@ -27,42 +31,40 @@
 - [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)
 - [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)
 - [buildEngineServerConfiguration](functions/buildEngineServerConfiguration.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)

package/docs/reference/interfaces/ICacheMetadata.md

@@ -4,7 +4,7 @@ Metadata for cached HTTPS extensions.
 
 ## Properties
 
-### downloadedAt
+### downloadedAt {#downloadedat}
 
 > **downloadedAt**: `number`
 
@@ -12,7 +12,7 @@ Timestamp when the file was downloaded.
 
 ***
 
-### url
+### url {#url}
 
 > **url**: `string`
 
@@ -20,7 +20,7 @@ Original URL of the cached file.
 
 ***
 
-### size
+### size {#size}
 
 > **size**: `number`
 

package/docs/reference/interfaces/ICliArgs.md

@@ -0,0 +1,35 @@
+# Interface: ICliArgs
+
+Command to execute in the CLI.
+
+## Properties
+
+### nodePath? {#nodepath}
+
+> `optional` **nodePath?**: `string`
+
+The path of the node executable.
+
+***
+
+### scriptPath? {#scriptpath}
+
+> `optional` **scriptPath?**: `string`
+
+The path of the script to execute.
+
+***
+
+### options? {#options}
+
+> `optional` **options?**: `object`[]
+
+The command line options.
+
+#### key
+
+> **key**: `string`
+
+#### value
+
+> **value**: `string`

package/docs/reference/interfaces/ICliCommand.md

@@ -0,0 +1,23 @@
+# Interface: ICliCommand
+
+Command to execute in the CLI.
+
+## Properties
+
+### definition {#definition}
+
+> **definition**: [`ICliCommandDefinition`](ICliCommandDefinition.md)
+
+The command to execute.
+
+***
+
+### params {#params}
+
+> **params**: `object`
+
+The params to execute the command with.
+
+#### Index Signature
+
+\[`id`: `string`\]: [`CliCommandParamType`](../type-aliases/CliCommandParamType.md)

package/docs/reference/interfaces/ICliCommandDefinition.md

@@ -0,0 +1,101 @@
+# Interface: ICliCommandDefinition
+
+Command to execute in the CLI.
+
+## Properties
+
+### command {#command}
+
+> **command**: `string`
+
+The command name.
+
+***
+
+### description {#description}
+
+> **description**: `string`
+
+The command description.
+
+***
+
+### example {#example}
+
+> **example**: `string`
+
+The example.
+
+***
+
+### params {#params}
+
+> **params**: [`ICliCommandDefinitionParam`](ICliCommandDefinitionParam.md)[]
+
+The params available for the command.
+
+***
+
+### action {#action}
+
+> **action**: (`engineCore`, `envVars`, `params`) => `Promise`\<`unknown`\>
+
+The method to execute for the command.
+
+#### Parameters
+
+##### engineCore
+
+`IEngineCore`
+
+##### envVars
+
+[`INodeEnvironmentVariables`](INodeEnvironmentVariables.md)
+
+##### params
+
+#### Returns
+
+`Promise`\<`unknown`\>
+
+***
+
+### requiresEngineStarted? {#requiresenginestarted}
+
+> `optional` **requiresEngineStarted?**: `boolean`
+
+Indicates whether the engine needs to be started before executing the command.
+
+#### Default
+
+```ts
+true
+```
+
+***
+
+### requiresNodeIdentity? {#requiresnodeidentity}
+
+> `optional` **requiresNodeIdentity?**: `boolean`
+
+Indicates whether the engine needs the node identity to be set if configured to use.
+
+#### Default
+
+```ts
+true
+```
+
+***
+
+### requiresTenantId? {#requirestenantid}
+
+> `optional` **requiresTenantId?**: `boolean`
+
+Indicates whether the engine needs the tenant id to be set if configured to use.
+
+#### Default
+
+```ts
+true
+```