@twin.org/node-core 0.0.2-next.9 → 0.0.3-next.10

package/dist/es/utils.js

@@ -0,0 +1,397 @@
+// Copyright 2024 IOTA Stiftung.
+// SPDX-License-Identifier: Apache-2.0.
+import { execSync } from "node:child_process";
+import { mkdir, readdir, readFile, rename, stat, writeFile } from "node:fs/promises";
+import { get as httpsGet } from "node:https";
+import path from "node:path";
+import { CLIDisplay } from "@twin.org/cli-core";
+import { BaseError, Converter, GeneralError, I18n } from "@twin.org/core";
+import { Sha256 } from "@twin.org/crypto";
+import { ModuleHelper } from "@twin.org/modules";
+import { ModuleProtocol } from "./models/moduleProtocol.js";
+/**
+ * Initialise the locales for the application.
+ * @param localesDirectory The directory containing the locales.
+ */
+export async function initialiseLocales(localesDirectory) {
+    const localesFile = path.resolve(path.join(localesDirectory, "en.json"));
+    CLIDisplay.value("Locales File", localesFile);
+    if (await fileExists(localesFile)) {
+        const enLangContent = await readFile(localesFile, "utf8");
+        I18n.addDictionary("en", JSON.parse(enLangContent));
+    }
+    else {
+        CLIDisplay.error(`Locales file not found: ${localesFile}`);
+    }
+}
+/**
+ * Get the directory where the application is being executed.
+ * @returns The execution directory.
+ */
+export function getExecutionDirectory() {
+    return process.cwd();
+}
+/**
+ * Does the specified file exist.
+ * @param filename The filename to check for existence.
+ * @returns True if the file exists.
+ */
+export async function fileExists(filename) {
+    try {
+        const stats = await stat(filename);
+        return stats.isFile();
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Does the specified directory exist.
+ * @param directory The directory to check for existence.
+ * @returns True if the directory exists.
+ */
+export async function directoryExists(directory) {
+    try {
+        const stats = await stat(directory);
+        return stats.isDirectory();
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Get the sub folders for the folder.
+ * @param directory The directory to get the sub folders.
+ * @returns The list of sub folders.
+ */
+export async function getSubFolders(directory) {
+    try {
+        const dir = await readdir(directory);
+        const folders = [];
+        for (const dirEntry of dir) {
+            const fullPath = path.join(directory, dirEntry);
+            const stats = await stat(fullPath);
+            if (stats.isDirectory()) {
+                folders.push(fullPath);
+            }
+        }
+        return folders;
+    }
+    catch {
+        return [];
+    }
+}
+/**
+ * Get the files in the directory.
+ * @param directory The directory to get the files from.
+ * @returns The list of files in the directory.
+ */
+export async function getFiles(directory) {
+    try {
+        const dir = await readdir(directory);
+        const files = [];
+        for (const dirEntry of dir) {
+            const fullPath = path.join(directory, dirEntry);
+            const stats = await stat(fullPath);
+            if (stats.isFile()) {
+                files.push(fullPath);
+            }
+        }
+        return files;
+    }
+    catch {
+        return [];
+    }
+}
+/**
+ * Load the text file.
+ * @param filename The filename of the text file to load.
+ * @returns The contents of the text file if it could not be loaded.
+ */
+export async function loadTextFile(filename) {
+    return readFile(filename, "utf8");
+}
+/**
+ * Load the JSON file.
+ * @param filename The filename of the JSON file to load.
+ * @returns The contents of the JSON file or null if it could not be loaded.
+ */
+export async function loadJsonFile(filename) {
+    const content = await loadTextFile(filename);
+    return JSON.parse(content);
+}
+/**
+ * Parse the protocol from a module name.
+ * @param moduleName The module name to parse.
+ * @returns The parsed protocol information.
+ */
+export function parseModuleProtocol(moduleName) {
+    const trimmed = moduleName.trim();
+    if (trimmed.startsWith("npm:")) {
+        return {
+            protocol: ModuleProtocol.Npm,
+            identifier: trimmed.slice(4),
+            original: trimmed
+        };
+    }
+    if (trimmed.startsWith("https://")) {
+        return {
+            protocol: ModuleProtocol.Https,
+            identifier: trimmed,
+            original: trimmed
+        };
+    }
+    if (trimmed.startsWith("http://")) {
+        return {
+            protocol: ModuleProtocol.Http,
+            identifier: trimmed,
+            original: trimmed
+        };
+    }
+    if (trimmed.startsWith("file://")) {
+        return {
+            protocol: ModuleProtocol.Local,
+            identifier: trimmed,
+            original: trimmed
+        };
+    }
+    if (ModuleHelper.isLocalModule(trimmed)) {
+        return {
+            protocol: ModuleProtocol.Local,
+            identifier: trimmed,
+            original: trimmed
+        };
+    }
+    return {
+        protocol: ModuleProtocol.Default,
+        identifier: trimmed,
+        original: trimmed
+    };
+}
+/**
+ * Hash a URL to create a safe filename.
+ * @param url The URL to hash.
+ * @returns A hashed filename safe for the filesystem.
+ */
+export function hashUrl(url) {
+    const urlBytes = Converter.utf8ToBytes(url);
+    const hashBytes = Sha256.sum256(urlBytes);
+    const hash = Converter.bytesToHex(hashBytes);
+    const ext = path.extname(new URL(url).pathname);
+    return `${hash}${ext}`;
+}
+/**
+ * Get the extensions cache directory.
+ * @param executionDirectory The execution directory.
+ * @param protocol The protocol type for subdirectory organization.
+ * @param cacheDirectory The cache directory base path.
+ * @returns The cache directory path.
+ */
+export function getExtensionsCacheDir(executionDirectory, protocol, cacheDirectory) {
+    // Resolve to absolute path to ensure consistent behavior
+    const absoluteDir = path.resolve(executionDirectory);
+    const baseDir = cacheDirectory ?? ".tmp";
+    return path.join(absoluteDir, baseDir, "extensions", protocol);
+}
+/**
+ * Handle the npm: protocol by installing the package if needed.
+ * @param packageName The npm package name (without npm: prefix).
+ * @param executionDirectory The execution directory.
+ * @param cacheDirectory The cache directory base path.
+ * @returns The resolved path to the installed module.
+ */
+export async function handleNpmProtocol(packageName, executionDirectory, cacheDirectory) {
+    const cacheDir = getExtensionsCacheDir(executionDirectory, ModuleProtocol.Npm, cacheDirectory);
+    // Extract just the package name (without version) for the directory
+    // e.g. "picocolors@1.0.0" becomes "picocolors"
+    // e.g. "@scope/package@1.0.0" becomes "@scope/package"
+    const lastAtIndex = packageName.lastIndexOf("@");
+    const packageNameOnly = lastAtIndex > 0 ? packageName.slice(0, lastAtIndex) : packageName;
+    const packageDir = path.join(cacheDir, "node_modules", packageNameOnly);
+    const packageJsonPath = path.join(packageDir, "package.json");
+    const exists = await fileExists(packageJsonPath);
+    if (exists) {
+        const mainFile = await resolvePackageEntryPoint(packageDir, packageNameOnly);
+        const modulePath = path.join(packageDir, mainFile);
+        return {
+            resolvedPath: modulePath,
+            cached: true
+        };
+    }
+    await mkdir(cacheDir, { recursive: true });
+    CLIDisplay.task(I18n.formatMessage("node.extensionNpmInstalling"), packageName);
+    try {
+        // Always pipe stdio to comply with env access restrictions in tests/lint
+        const stdio = "pipe";
+        execSync(`npm install ${packageName} --prefix "${cacheDir}" --no-save --no-package-lock`, {
+            cwd: cacheDir,
+            stdio
+        });
+    }
+    catch (err) {
+        throw new GeneralError("node", "extensionNpmInstallFailed", {
+            package: packageName
+        }, BaseError.fromError(err));
+    }
+    const mainFile = await resolvePackageEntryPoint(packageDir, packageNameOnly);
+    const modulePath = path.join(packageDir, mainFile);
+    return {
+        resolvedPath: modulePath,
+        cached: false
+    };
+}
+/**
+ * Check if a cached file has expired based on TTL and force refresh settings.
+ * @param metadataPath Path to the cache metadata file.
+ * @param ttlHours Time to live in hours.
+ * @param forceRefresh Whether to force refresh regardless of TTL.
+ * @returns True if the cache is expired or should be refreshed.
+ */
+export async function isCacheExpired(metadataPath, ttlHours, forceRefresh) {
+    if (forceRefresh) {
+        return true;
+    }
+    try {
+        const metadata = await loadJsonFile(metadataPath);
+        const ttlMillis = ttlHours * 60 * 60 * 1000;
+        const expireTime = metadata.downloadedAt + ttlMillis;
+        return Date.now() > expireTime;
+    }
+    catch {
+        // If metadata doesn't exist or is corrupted, consider expired
+        return true;
+    }
+}
+/**
+ * Handle the https: protocol by downloading the module if needed.
+ * @param url The HTTPS URL to download from.
+ * @param executionDirectory The execution directory.
+ * @param maxSizeMb The maximum size in MB for the download.
+ * @param cacheDirectory The cache directory base path.
+ * @param ttlHours TTL in hours for cache expiration.
+ * @param forceRefresh Whether to force refresh the cache.
+ * @returns The resolved path to the downloaded module.
+ */
+export async function handleHttpsProtocol(url, executionDirectory, maxSizeMb, cacheDirectory, ttlHours, forceRefresh) {
+    const effectiveTtlHours = ttlHours ?? 24;
+    const effectiveForceRefresh = forceRefresh ?? false;
+    const cacheDir = getExtensionsCacheDir(executionDirectory, ModuleProtocol.Https, cacheDirectory);
+    const filename = hashUrl(url);
+    const cachedPath = path.join(cacheDir, filename);
+    const metadataPath = `${cachedPath}.meta`;
+    const exists = await fileExists(cachedPath);
+    if (exists) {
+        const expired = await isCacheExpired(metadataPath, effectiveTtlHours, effectiveForceRefresh);
+        if (!expired) {
+            return {
+                resolvedPath: cachedPath,
+                cached: true
+            };
+        }
+        if (effectiveForceRefresh) {
+            CLIDisplay.warning(I18n.formatMessage("node.extensionForceRefresh", { url }));
+        }
+        else {
+            CLIDisplay.task(I18n.formatMessage("node.extensionCacheExpired", { url }));
+        }
+    }
+    CLIDisplay.warning(I18n.formatMessage("node.extensionSecurityWarning", { url }));
+    CLIDisplay.task(I18n.formatMessage("node.extensionHttpsDownloading"), url);
+    await mkdir(cacheDir, { recursive: true });
+    const maxSizeBytes = maxSizeMb * 1024 * 1024;
+    let downloadedSize = 0;
+    const chunks = [];
+    try {
+        await new Promise((resolve, reject) => {
+            httpsGet(url, response => {
+                if (response.statusCode !== 200) {
+                    reject(new GeneralError("node", "extensionDownloadFailed", {
+                        url,
+                        status: response.statusCode ?? 0
+                    }));
+                    return;
+                }
+                response.on("data", (chunk) => {
+                    downloadedSize += chunk.length;
+                    if (downloadedSize > maxSizeBytes) {
+                        response.destroy();
+                        reject(new GeneralError("node", "extensionSizeLimitExceeded", {
+                            size: downloadedSize,
+                            limit: maxSizeBytes
+                        }));
+                        return;
+                    }
+                    chunks.push(chunk);
+                });
+                response.on("end", () => {
+                    resolve();
+                });
+                response.on("error", err => {
+                    reject(BaseError.fromError(err));
+                });
+            }).on("error", err => {
+                reject(BaseError.fromError(err));
+            });
+        });
+    }
+    catch (err) {
+        throw new GeneralError("node", "extensionDownloadFailed", {
+            url
+        }, BaseError.fromError(err));
+    }
+    const tempPath = `${cachedPath}.tmp`;
+    await writeFile(tempPath, Buffer.concat(chunks));
+    // Atomic move from temp to final location
+    await rename(tempPath, cachedPath);
+    // Save metadata for TTL tracking
+    const metadata = {
+        downloadedAt: Date.now(),
+        url,
+        size: Buffer.concat(chunks).length
+    };
+    await writeFile(metadataPath, JSON.stringify(metadata, null, 2));
+    return {
+        resolvedPath: cachedPath,
+        cached: false
+    };
+}
+/**
+ * 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.
+ * @param packagePath The absolute path to the package directory.
+ * @param packageName The package name for require.resolve().
+ * @param fallback The fallback file name if no entry point is found.
+ * @returns The resolved entry point file name (relative to package directory).
+ */
+export async function resolvePackageEntryPoint(packagePath, packageName, fallback = "index.js") {
+    try {
+        // Try require.resolve() first - handles exports, main, module automatically
+        const resolvedPath = require.resolve(packageName, { paths: [path.dirname(packagePath)] });
+        // Convert absolute path back to relative filename within package
+        const relativePath = path.relative(packagePath, resolvedPath);
+        return relativePath ?? fallback;
+    }
+    catch {
+        // Fallback to manual package.json parsing if require.resolve fails
+        try {
+            const packageJsonPath = path.join(packagePath, "package.json");
+            const packageJsonContent = await loadJsonFile(packageJsonPath);
+            // Future: Could expand exports field support here
+            return packageJsonContent.module ?? packageJsonContent.main ?? fallback;
+        }
+        catch {
+            return fallback;
+        }
+    }
+}
+/**
+ * Convert a file path to an import-compatible URL for cross-platform module loading.
+ * On Windows, adds the 'file://' protocol prefix required for dynamic imports.
+ * On other platforms, returns the path unchanged.
+ * @param filePath The absolute file path to convert.
+ * @returns A URL string compatible with dynamic import().
+ */
+export function createModuleImportUrl(filePath) {
+    return process.platform === "win32" ? `file://${filePath}` : filePath;
+}
+//# sourceMappingURL=utils.js.map

package/dist/es/utils.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"utils.js","sourceRoot":"","sources":["../../src/utils.ts"],"names":[],"mappings":"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","sourcesContent":["// Copyright 2024 IOTA Stiftung.\n// SPDX-License-Identifier: Apache-2.0.\nimport { execSync } from \"node:child_process\";\nimport { mkdir, readdir, readFile, rename, stat, writeFile } from \"node:fs/promises\";\nimport { get as httpsGet } from \"node:https\";\nimport path from \"node:path\";\nimport { CLIDisplay } from \"@twin.org/cli-core\";\nimport { BaseError, Converter, GeneralError, I18n, type ILocaleDictionary } from \"@twin.org/core\";\nimport { Sha256 } from \"@twin.org/crypto\";\nimport { ModuleHelper } from \"@twin.org/modules\";\nimport type { ICacheMetadata } from \"./models/ICacheMetadata.js\";\nimport type { IModuleProtocol } from \"./models/IModuleProtocol.js\";\nimport type { IProtocolHandlerResult } from \"./models/IProtocolHandlerResult.js\";\nimport { ModuleProtocol } from \"./models/moduleProtocol.js\";\n\n/**\n * Initialise the locales for the application.\n * @param localesDirectory The directory containing the locales.\n */\nexport async function initialiseLocales(localesDirectory: string): Promise<void> {\n\tconst localesFile = path.resolve(path.join(localesDirectory, \"en.json\"));\n\tCLIDisplay.value(\"Locales File\", localesFile);\n\tif (await fileExists(localesFile)) {\n\t\tconst enLangContent = await readFile(localesFile, \"utf8\");\n\t\tI18n.addDictionary(\"en\", JSON.parse(enLangContent) as ILocaleDictionary);\n\t} else {\n\t\tCLIDisplay.error(`Locales file not found: ${localesFile}`);\n\t}\n}\n\n/**\n * Get the directory where the application is being executed.\n * @returns The execution directory.\n */\nexport function getExecutionDirectory(): string {\n\treturn process.cwd();\n}\n\n/**\n * Does the specified file exist.\n * @param filename The filename to check for existence.\n * @returns True if the file exists.\n */\nexport async function fileExists(filename: string): Promise<boolean> {\n\ttry {\n\t\tconst stats = await stat(filename);\n\t\treturn stats.isFile();\n\t} catch {\n\t\treturn false;\n\t}\n}\n\n/**\n * Does the specified directory exist.\n * @param directory The directory to check for existence.\n * @returns True if the directory exists.\n */\nexport async function directoryExists(directory: string): Promise<boolean> {\n\ttry {\n\t\tconst stats = await stat(directory);\n\t\treturn stats.isDirectory();\n\t} catch {\n\t\treturn false;\n\t}\n}\n\n/**\n * Get the sub folders for the folder.\n * @param directory The directory to get the sub folders.\n * @returns The list of sub folders.\n */\nexport async function getSubFolders(directory: string): Promise<string[]> {\n\ttry {\n\t\tconst dir = await readdir(directory);\n\t\tconst folders: string[] = [];\n\t\tfor (const dirEntry of dir) {\n\t\t\tconst fullPath = path.join(directory, dirEntry);\n\t\t\tconst stats = await stat(fullPath);\n\t\t\tif (stats.isDirectory()) {\n\t\t\t\tfolders.push(fullPath);\n\t\t\t}\n\t\t}\n\t\treturn folders;\n\t} catch {\n\t\treturn [];\n\t}\n}\n\n/**\n * Get the files in the directory.\n * @param directory The directory to get the files from.\n * @returns The list of files in the directory.\n */\nexport async function getFiles(directory: string): Promise<string[]> {\n\ttry {\n\t\tconst dir = await readdir(directory);\n\t\tconst files: string[] = [];\n\t\tfor (const dirEntry of dir) {\n\t\t\tconst fullPath = path.join(directory, dirEntry);\n\t\t\tconst stats = await stat(fullPath);\n\t\t\tif (stats.isFile()) {\n\t\t\t\tfiles.push(fullPath);\n\t\t\t}\n\t\t}\n\t\treturn files;\n\t} catch {\n\t\treturn [];\n\t}\n}\n\n/**\n * Load the text file.\n * @param filename The filename of the text file to load.\n * @returns The contents of the text file if it could not be loaded.\n */\nexport async function loadTextFile(filename: string): Promise<string> {\n\treturn readFile(filename, \"utf8\");\n}\n\n/**\n * Load the JSON file.\n * @param filename The filename of the JSON file to load.\n * @returns The contents of the JSON file or null if it could not be loaded.\n */\nexport async function loadJsonFile<T>(filename: string): Promise<T> {\n\tconst content = await loadTextFile(filename);\n\treturn JSON.parse(content) as T;\n}\n\n/**\n * Parse the protocol from a module name.\n * @param moduleName The module name to parse.\n * @returns The parsed protocol information.\n */\nexport function parseModuleProtocol(moduleName: string): IModuleProtocol {\n\tconst trimmed = moduleName.trim();\n\n\tif (trimmed.startsWith(\"npm:\")) {\n\t\treturn {\n\t\t\tprotocol: ModuleProtocol.Npm,\n\t\t\tidentifier: trimmed.slice(4),\n\t\t\toriginal: trimmed\n\t\t};\n\t}\n\n\tif (trimmed.startsWith(\"https://\")) {\n\t\treturn {\n\t\t\tprotocol: ModuleProtocol.Https,\n\t\t\tidentifier: trimmed,\n\t\t\toriginal: trimmed\n\t\t};\n\t}\n\n\tif (trimmed.startsWith(\"http://\")) {\n\t\treturn {\n\t\t\tprotocol: ModuleProtocol.Http,\n\t\t\tidentifier: trimmed,\n\t\t\toriginal: trimmed\n\t\t};\n\t}\n\n\tif (trimmed.startsWith(\"file://\")) {\n\t\treturn {\n\t\t\tprotocol: ModuleProtocol.Local,\n\t\t\tidentifier: trimmed,\n\t\t\toriginal: trimmed\n\t\t};\n\t}\n\n\tif (ModuleHelper.isLocalModule(trimmed)) {\n\t\treturn {\n\t\t\tprotocol: ModuleProtocol.Local,\n\t\t\tidentifier: trimmed,\n\t\t\toriginal: trimmed\n\t\t};\n\t}\n\n\treturn {\n\t\tprotocol: ModuleProtocol.Default,\n\t\tidentifier: trimmed,\n\t\toriginal: trimmed\n\t};\n}\n\n/**\n * Hash a URL to create a safe filename.\n * @param url The URL to hash.\n * @returns A hashed filename safe for the filesystem.\n */\nexport function hashUrl(url: string): string {\n\tconst urlBytes = Converter.utf8ToBytes(url);\n\tconst hashBytes = Sha256.sum256(urlBytes);\n\tconst hash = Converter.bytesToHex(hashBytes);\n\tconst ext = path.extname(new URL(url).pathname);\n\treturn `${hash}${ext}`;\n}\n\n/**\n * Get the extensions cache directory.\n * @param executionDirectory The execution directory.\n * @param protocol The protocol type for subdirectory organization.\n * @param cacheDirectory The cache directory base path.\n * @returns The cache directory path.\n */\nexport function getExtensionsCacheDir(\n\texecutionDirectory: string,\n\tprotocol: ModuleProtocol,\n\tcacheDirectory?: string\n): string {\n\t// Resolve to absolute path to ensure consistent behavior\n\tconst absoluteDir = path.resolve(executionDirectory);\n\tconst baseDir = cacheDirectory ?? \".tmp\";\n\treturn path.join(absoluteDir, baseDir, \"extensions\", protocol);\n}\n\n/**\n * Handle the npm: protocol by installing the package if needed.\n * @param packageName The npm package name (without npm: prefix).\n * @param executionDirectory The execution directory.\n * @param cacheDirectory The cache directory base path.\n * @returns The resolved path to the installed module.\n */\nexport async function handleNpmProtocol(\n\tpackageName: string,\n\texecutionDirectory: string,\n\tcacheDirectory?: string\n): Promise<IProtocolHandlerResult> {\n\tconst cacheDir = getExtensionsCacheDir(executionDirectory, ModuleProtocol.Npm, cacheDirectory);\n\t// Extract just the package name (without version) for the directory\n\t// e.g. \"picocolors@1.0.0\" becomes \"picocolors\"\n\t// e.g. \"@scope/package@1.0.0\" becomes \"@scope/package\"\n\tconst lastAtIndex = packageName.lastIndexOf(\"@\");\n\tconst packageNameOnly = lastAtIndex > 0 ? packageName.slice(0, lastAtIndex) : packageName;\n\tconst packageDir = path.join(cacheDir, \"node_modules\", packageNameOnly);\n\tconst packageJsonPath = path.join(packageDir, \"package.json\");\n\n\tconst exists = await fileExists(packageJsonPath);\n\tif (exists) {\n\t\tconst mainFile = await resolvePackageEntryPoint(packageDir, packageNameOnly);\n\t\tconst modulePath = path.join(packageDir, mainFile);\n\n\t\treturn {\n\t\t\tresolvedPath: modulePath,\n\t\t\tcached: true\n\t\t};\n\t}\n\n\tawait mkdir(cacheDir, { recursive: true });\n\n\tCLIDisplay.task(I18n.formatMessage(\"node.extensionNpmInstalling\"), packageName);\n\n\ttry {\n\t\t// Always pipe stdio to comply with env access restrictions in tests/lint\n\t\tconst stdio: \"pipe\" | \"inherit\" | \"ignore\" = \"pipe\";\n\t\texecSync(`npm install ${packageName} --prefix \"${cacheDir}\" --no-save --no-package-lock`, {\n\t\t\tcwd: cacheDir,\n\t\t\tstdio\n\t\t});\n\t} catch (err) {\n\t\tthrow new GeneralError(\n\t\t\t\"node\",\n\t\t\t\"extensionNpmInstallFailed\",\n\t\t\t{\n\t\t\t\tpackage: packageName\n\t\t\t},\n\t\t\tBaseError.fromError(err)\n\t\t);\n\t}\n\n\tconst mainFile = await resolvePackageEntryPoint(packageDir, packageNameOnly);\n\tconst modulePath = path.join(packageDir, mainFile);\n\n\treturn {\n\t\tresolvedPath: modulePath,\n\t\tcached: false\n\t};\n}\n\n/**\n * Check if a cached file has expired based on TTL and force refresh settings.\n * @param metadataPath Path to the cache metadata file.\n * @param ttlHours Time to live in hours.\n * @param forceRefresh Whether to force refresh regardless of TTL.\n * @returns True if the cache is expired or should be refreshed.\n */\nexport async function isCacheExpired(\n\tmetadataPath: string,\n\tttlHours: number,\n\tforceRefresh: boolean\n): Promise<boolean> {\n\tif (forceRefresh) {\n\t\treturn true;\n\t}\n\n\ttry {\n\t\tconst metadata = await loadJsonFile<ICacheMetadata>(metadataPath);\n\t\tconst ttlMillis = ttlHours * 60 * 60 * 1000;\n\t\tconst expireTime = metadata.downloadedAt + ttlMillis;\n\t\treturn Date.now() > expireTime;\n\t} catch {\n\t\t// If metadata doesn't exist or is corrupted, consider expired\n\t\treturn true;\n\t}\n}\n\n/**\n * Handle the https: protocol by downloading the module if needed.\n * @param url The HTTPS URL to download from.\n * @param executionDirectory The execution directory.\n * @param maxSizeMb The maximum size in MB for the download.\n * @param cacheDirectory The cache directory base path.\n * @param ttlHours TTL in hours for cache expiration.\n * @param forceRefresh Whether to force refresh the cache.\n * @returns The resolved path to the downloaded module.\n */\nexport async function handleHttpsProtocol(\n\turl: string,\n\texecutionDirectory: string,\n\tmaxSizeMb: number,\n\tcacheDirectory?: string,\n\tttlHours?: number,\n\tforceRefresh?: boolean\n): Promise<IProtocolHandlerResult> {\n\tconst effectiveTtlHours = ttlHours ?? 24;\n\tconst effectiveForceRefresh = forceRefresh ?? false;\n\tconst cacheDir = getExtensionsCacheDir(executionDirectory, ModuleProtocol.Https, cacheDirectory);\n\tconst filename = hashUrl(url);\n\tconst cachedPath = path.join(cacheDir, filename);\n\tconst metadataPath = `${cachedPath}.meta`;\n\n\tconst exists = await fileExists(cachedPath);\n\tif (exists) {\n\t\tconst expired = await isCacheExpired(metadataPath, effectiveTtlHours, effectiveForceRefresh);\n\t\tif (!expired) {\n\t\t\treturn {\n\t\t\t\tresolvedPath: cachedPath,\n\t\t\t\tcached: true\n\t\t\t};\n\t\t}\n\n\t\tif (effectiveForceRefresh) {\n\t\t\tCLIDisplay.warning(I18n.formatMessage(\"node.extensionForceRefresh\", { url }));\n\t\t} else {\n\t\t\tCLIDisplay.task(I18n.formatMessage(\"node.extensionCacheExpired\", { url }));\n\t\t}\n\t}\n\n\tCLIDisplay.warning(I18n.formatMessage(\"node.extensionSecurityWarning\", { url }));\n\tCLIDisplay.task(I18n.formatMessage(\"node.extensionHttpsDownloading\"), url);\n\n\tawait mkdir(cacheDir, { recursive: true });\n\n\tconst maxSizeBytes = maxSizeMb * 1024 * 1024;\n\tlet downloadedSize = 0;\n\tconst chunks: Buffer[] = [];\n\n\ttry {\n\t\tawait new Promise<void>((resolve, reject) => {\n\t\t\thttpsGet(url, response => {\n\t\t\t\tif (response.statusCode !== 200) {\n\t\t\t\t\treject(\n\t\t\t\t\t\tnew GeneralError(\"node\", \"extensionDownloadFailed\", {\n\t\t\t\t\t\t\turl,\n\t\t\t\t\t\t\tstatus: response.statusCode ?? 0\n\t\t\t\t\t\t})\n\t\t\t\t\t);\n\t\t\t\t\treturn;\n\t\t\t\t}\n\n\t\t\t\tresponse.on(\"data\", (chunk: Buffer) => {\n\t\t\t\t\tdownloadedSize += chunk.length;\n\n\t\t\t\t\tif (downloadedSize > maxSizeBytes) {\n\t\t\t\t\t\tresponse.destroy();\n\t\t\t\t\t\treject(\n\t\t\t\t\t\t\tnew GeneralError(\"node\", \"extensionSizeLimitExceeded\", {\n\t\t\t\t\t\t\t\tsize: downloadedSize,\n\t\t\t\t\t\t\t\tlimit: maxSizeBytes\n\t\t\t\t\t\t\t})\n\t\t\t\t\t\t);\n\t\t\t\t\t\treturn;\n\t\t\t\t\t}\n\n\t\t\t\t\tchunks.push(chunk);\n\t\t\t\t});\n\n\t\t\t\tresponse.on(\"end\", () => {\n\t\t\t\t\tresolve();\n\t\t\t\t});\n\n\t\t\t\tresponse.on(\"error\", err => {\n\t\t\t\t\treject(BaseError.fromError(err));\n\t\t\t\t});\n\t\t\t}).on(\"error\", err => {\n\t\t\t\treject(BaseError.fromError(err));\n\t\t\t});\n\t\t});\n\t} catch (err) {\n\t\tthrow new GeneralError(\n\t\t\t\"node\",\n\t\t\t\"extensionDownloadFailed\",\n\t\t\t{\n\t\t\t\turl\n\t\t\t},\n\t\t\tBaseError.fromError(err)\n\t\t);\n\t}\n\n\tconst tempPath = `${cachedPath}.tmp`;\n\tawait writeFile(tempPath, Buffer.concat(chunks));\n\n\t// Atomic move from temp to final location\n\tawait rename(tempPath, cachedPath);\n\n\t// Save metadata for TTL tracking\n\tconst metadata: ICacheMetadata = {\n\t\tdownloadedAt: Date.now(),\n\t\turl,\n\t\tsize: Buffer.concat(chunks).length\n\t};\n\tawait writeFile(metadataPath, JSON.stringify(metadata, null, 2));\n\n\treturn {\n\t\tresolvedPath: cachedPath,\n\t\tcached: false\n\t};\n}\n\n/**\n * Resolve the main entry point from a package directory using Node.js resolution with fallback.\n * Uses require.resolve() when possible for standard Node.js behavior, with manual fallback.\n * @param packagePath The absolute path to the package directory.\n * @param packageName The package name for require.resolve().\n * @param fallback The fallback file name if no entry point is found.\n * @returns The resolved entry point file name (relative to package directory).\n */\nexport async function resolvePackageEntryPoint(\n\tpackagePath: string,\n\tpackageName: string,\n\tfallback = \"index.js\"\n): Promise<string> {\n\ttry {\n\t\t// Try require.resolve() first - handles exports, main, module automatically\n\t\tconst resolvedPath = require.resolve(packageName, { paths: [path.dirname(packagePath)] });\n\t\t// Convert absolute path back to relative filename within package\n\t\tconst relativePath = path.relative(packagePath, resolvedPath);\n\t\treturn relativePath ?? fallback;\n\t} catch {\n\t\t// Fallback to manual package.json parsing if require.resolve fails\n\t\ttry {\n\t\t\tconst packageJsonPath = path.join(packagePath, \"package.json\");\n\t\t\tconst packageJsonContent = await loadJsonFile<{\n\t\t\t\tmodule?: string;\n\t\t\t\tmain?: string;\n\t\t\t\t// eslint-disable-next-line @typescript-eslint/no-explicit-any\n\t\t\t\texports?: any;\n\t\t\t}>(packageJsonPath);\n\n\t\t\t// Future: Could expand exports field support here\n\t\t\treturn packageJsonContent.module ?? packageJsonContent.main ?? fallback;\n\t\t} catch {\n\t\t\treturn fallback;\n\t\t}\n\t}\n}\n\n/**\n * Convert a file path to an import-compatible URL for cross-platform module loading.\n * On Windows, adds the 'file://' protocol prefix required for dynamic imports.\n * On other platforms, returns the path unchanged.\n * @param filePath The absolute file path to convert.\n * @returns A URL string compatible with dynamic import().\n */\nexport function createModuleImportUrl(filePath: string): string {\n\treturn process.platform === \"win32\" ? `file://${filePath}` : filePath;\n}\n"]}

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

@@ -1,8 +1,12 @@
 import { type IEngineConfig } from "@twin.org/engine-types";
-import type { IEngineEnvironmentVariables } from "../models/IEngineEnvironmentVariables";
+import type { IEngineEnvironmentVariables } from "../models/IEngineEnvironmentVariables.js";
 /**
  * Build the engine core configuration from environment variables.
  * @param envVars The environment variables.
+ * @param contextIdKeys The context ID keys.
  * @returns The config for the core.
  */
-export declare function buildEngineConfiguration(envVars: IEngineEnvironmentVariables): IEngineConfig;
+export declare function buildEngineConfiguration(envVars: IEngineEnvironmentVariables, contextIdKeys: {
+    key: string;
+    requiredHandlerFeatures: string[];
+}[]): Promise<IEngineConfig>;

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

@@ -1,14 +1,18 @@
 import type { IServerInfo } from "@twin.org/api-models";
 import type { IEngineCoreConfig } from "@twin.org/engine-models";
 import { type IEngineServerConfig } from "@twin.org/engine-server-types";
-import type { IEngineServerEnvironmentVariables } from "../models/IEngineServerEnvironmentVariables";
+import type { IEngineServerEnvironmentVariables } from "../models/IEngineServerEnvironmentVariables.js";
 /**
  * Handles the configuration of the server.
  * @param envVars The environment variables for the engine server.
+ * @param availableContextIdKeys The context ID keys.
  * @param coreEngineConfig The core engine config.
  * @param serverInfo The server information.
  * @param openApiSpecPath The path to the open api spec.
  * @param favIconPath The path to the favicon.
- * @returns The the config for the core and the server.
+ * @returns The config for the core and the server.
  */
-export declare function buildEngineServerConfiguration(envVars: IEngineServerEnvironmentVariables, coreEngineConfig: IEngineCoreConfig, serverInfo: IServerInfo, openApiSpecPath?: string, favIconPath?: string): IEngineServerConfig;
+export declare function buildEngineServerConfiguration(envVars: IEngineServerEnvironmentVariables, availableContextIdKeys: {
+    key: string;
+    requiredHandlerFeatures: string[];
+}[], coreEngineConfig: IEngineCoreConfig, serverInfo: IServerInfo, openApiSpecPath?: string, favIconPath?: string): Promise<IEngineServerConfig>;

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

@@ -0,0 +1,32 @@
+import type { IEngineCore, IEngineServer } from "@twin.org/engine-models";
+import type { INodeEngineConfig } from "../models/INodeEngineConfig.js";
+import type { INodeEnvironmentVariables } from "../models/INodeEnvironmentVariables.js";
+/**
+ * Handles the configuration of the extensions.
+ * @param envVars The environment variables for the node.
+ * @param nodeEngineConfig The node engine config.
+ * @returns The config for the core and the server.
+ */
+export declare function extensionsConfiguration(envVars: INodeEnvironmentVariables, nodeEngineConfig: INodeEngineConfig): Promise<INodeEngineConfig>;
+/**
+ * Handles the initialisation of the extensions when the engine has been constructed.
+ * @param envVars The environment variables for the node.
+ * @param engineCore The engine core instance.
+ * @returns Nothing.
+ */
+export declare function extensionsInitialiseEngine(envVars: INodeEnvironmentVariables, engineCore: IEngineCore): Promise<void>;
+/**
+ * Handles the initialisation of the extensions when the engine server has been constructed.
+ * @param envVars The environment variables for the node.
+ * @param engineCore The engine core instance.
+ * @param engineServer The engine server instance.
+ * @returns Nothing.
+ */
+export declare function extensionsInitialiseEngineServer(envVars: INodeEnvironmentVariables, engineCore: IEngineCore, engineServer: IEngineServer): Promise<void>;
+/**
+ * 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, engineCore: IEngineCore): Promise<void>;

package/dist/types/cli.d.ts

@@ -0,0 +1,66 @@
+import type { IEngineCore } from "@twin.org/engine-models";
+import type { ICliArgs } from "./models/ICliArgs.js";
+import type { ICliCommand } from "./models/ICliCommand.js";
+import type { INodeEnvironmentVariables } from "./models/INodeEnvironmentVariables.js";
+/**
+ * Initialise the CLI.
+ * @param processEnv The environment variables from the process.
+ * @param args The command line arguments.
+ * @returns The constructed CLI command if there is one.
+ * @throws GeneralError if the command is missing or invalid.
+ */
+export declare function initCli(processEnv: {
+    [id: string]: string;
+}, args?: string[]): ICliCommand | undefined;
+/**
+ * Parse command line arguments.
+ * @param args The command line arguments.
+ * @returns The parsed command line arguments.
+ */
+export declare function parseCommandLineArgs(args?: string[]): ICliArgs;
+/**
+ * Construct the CLI command from the parsed arguments.
+ * @param processEnv The environment variables from the process.
+ * @param cliArgs The parsed CLI arguments.
+ * @returns The constructed CLI command.
+ * @throws GeneralError if the command is missing.
+ */
+export declare function constructCliCommand(processEnv: {
+    [id: string]: string;
+}, cliArgs: ICliArgs): ICliCommand | undefined;
+/**
+ * Execute the CLI command.
+ * @param engineCore The engine core.
+ * @param envVars The environment variables for the node.
+ * @param cliCommand The CLI command to execute.
+ */
+export declare function executeCommand(engineCore: IEngineCore, envVars: INodeEnvironmentVariables, cliCommand: ICliCommand): Promise<void>;
+/**
+ * Load the env files and process the options.
+ * @param processEnv The environment variables from the process.
+ * @param options The options.
+ * @returns The processed parameters.
+ * @throws GeneralError if an env file has errors.
+ */
+export declare function processEnvOptions(processEnv: {
+    [id: string]: string;
+}, options: {
+    key: string;
+    value: string;
+}[]): void;
+/**
+ * Process options and replace any env variables with their values.
+ * @param processEnv The environment variables from the process.
+ * @param options The options.
+ * @throws GeneralError if an env variable is missing.
+ */
+export declare function substituteEnvOptions(processEnv: {
+    [id: string]: string;
+}, options: {
+    key: string;
+    value: string;
+}[]): void;
+/**
+ * Register available CLI commands.
+ */
+export declare function registerCommands(): void;

package/dist/types/commands/bootstrapLegacy.d.ts

@@ -0,0 +1,66 @@
+import type { IEngineCore } from "@twin.org/engine-models";
+import type { ICliCommandDefinition } from "../models/ICliCommandDefinition.js";
+import type { INodeEngineConfig } from "../models/INodeEngineConfig.js";
+import type { INodeEngineState } from "../models/INodeEngineState.js";
+import type { INodeEnvironmentVariables } from "../models/INodeEnvironmentVariables.js";
+/**
+ * Get the command definition parameters.
+ * @param commandDefinitions The registered command definitions.
+ */
+export declare function getCommandDefinitionBootstrapLegacy(commandDefinitions: {
+    [id: string]: ICliCommandDefinition;
+}): void;
+/**
+ * Command for legacy bootstrap.
+ * @param engineCore The engine core.
+ * @param envVars The environment variables for the node.
+ * @param params The parameters for the command.
+ */
+export declare function bootstrapLegacy(engineCore: IEngineCore<INodeEngineConfig, INodeEngineState>, envVars: INodeEnvironmentVariables & {
+    /**
+     * The features that are enabled on the node.
+     * @default []
+     */
+    features?: string;
+    /**
+     * The identity of the node which, if empty and node-identity feature is enabled it will be generated.
+     */
+    nodeIdentity?: string;
+    /**
+     * The mnemonic for the identity, if empty and node-identity feature is enabled it will be randomly generated.
+     */
+    nodeMnemonic?: string;
+    /**
+     * A tenant id to use as a default for the node.
+     */
+    tenantId?: string;
+    /**
+     * A tenant api key to use as a default for the node.
+     */
+    tenantApiKey?: string;
+    /**
+     * If the node-admin-user feature is enabled, this will be the organization of the user, if one is not provided it will be generated
+     */
+    organizationIdentity?: string;
+    /**
+     * The mnemonic for the organization, if empty and node-admin-user feature is enabled it will be randomly generated.
+     */
+    organizationMnemonic?: string;
+    /**
+     * If the node-admin-user feature is enabled, this will be the identity of the user, if one is not provided it will be generated
+     */
+    adminUserIdentity?: string;
+    /**
+     * The mnemonic for the admin user, if empty and node-admin-user feature is enabled it will be randomly generated.
+     */
+    adminUserMnemonic?: string;
+    /**
+     * If the node-admin-user feature is enabled, this will be the name of the user.
+     * @default admin@node
+     */
+    adminUserName?: string;
+    /**
+     * If the node-admin-user feature is enabled, this will be the password of the user, if empty it will be randomly generated.
+     */
+    adminUserPassword?: string;
+}, params: {}): Promise<void>;