@fontoxml/fontoxml-development-tools 3.10.0 → 3.12.0-beta.1

package/src/modules/shared/src/addBackendDockerCommands.js

@@ -0,0 +1,334 @@
+import path from 'path';
+import { fileURLToPath, pathToFileURL } from 'url';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+
+/**
+ * @typedef AddBackendDockerCommandsOptions
+ *
+ * @property {string}   productLabel
+ * @property {string}   commandPrefix
+ * @property {string}   [commandAlias]
+ * @property {string}   licenseProductName
+ *
+ * @property {string}   [documentationConfigurationGuide]
+ * @property {string}   [documentationExecuteError]
+ * @property {string}   [documentationGettingStartedGuide]
+ *
+ * @property {string}   defaultHttpPort
+ * @property {string}   [defaultHttpsPort]
+ * @property {string}   defaultImageName
+ * @property {string}   defaultImageTag
+ *
+ * @property {string}   manifestFileName
+ * @property {string}   manifestVersionPropertyName
+ *
+ * @property {string}   instanceBuildDockerfilePath
+ * @property {string}   instanceDevBuildDirectoryPath
+ * @property {string}   instanceDevBuildDockerfilePath
+ * @property {string}   instanceTemplateDirectoryPath
+ *
+ * @property {string}   temporaryBuildDirectoryName
+ * @property {string}   temporaryDirectoryName
+ * @property {string[]} requiredConfiguration
+ * @property {string[]} whitelist
+ *
+ * @property {{[key: string]: string}} debugEnvEntries
+ */
+
+/**
+ * @param {ModuleRegistrationApi}       moduleRegistration
+ * @param {FdtCommand}                  command
+ * @param {AddBackendDockerCommandsOptions} options
+ */
+function addBackendDockerBuildCommand(moduleRegistration, command, options) {
+	const buildCommand = command.addCommand('build', async (...args) => {
+		const controllerFactory = (
+			await import(
+				pathToFileURL(
+					path.resolve(
+						__dirname,
+						'controller-templates',
+						'command.backend.build.controller.factory.js'
+					)
+				)
+			)
+		).default;
+		return controllerFactory(options)(...args);
+	});
+
+	buildCommand
+		.setDescription(
+			`Build a ${options.productLabel} Docker image for production use. Requires Docker to be installed.`
+		)
+		.addOption(
+			'image-name',
+			'n',
+			`The name of the Docker image which will be created. This defaults to ${options.defaultImageName}.`,
+			false
+		)
+		.addOption(
+			'image-tag',
+			't',
+			`The tag of the Docker image which will be created. This defaults to ${options.defaultImageTag}.`,
+			false
+		)
+		.addOption(
+			'location',
+			'l',
+			'The directory where the instance is located. Defaults to the current working directory.',
+			false
+		)
+		.addOption(
+			'verbose',
+			null,
+			'Output default stdout and stderr information.'
+		)
+		.addOption('debug', null, 'Output all debug information.')
+
+		.addExample(
+			`${moduleRegistration.getAppInfo().name} ${
+				options.commandPrefix
+			} build`,
+			`Build production image "${options.defaultImageName}:${options.defaultImageTag}" using the ${options.productLabel} instance located at the current working directory.`
+		)
+		.addExample(
+			`${moduleRegistration.getAppInfo().name} ${
+				options.commandPrefix
+			} build --image-name my-instance --image-tag 1.0.0 --location /opt/my-instance/`,
+			`Build production image "my-instance:1.0.0" using the ${options.productLabel} instance located at "/opt/my-instance/".`
+		);
+}
+
+/**
+ * @param {ModuleRegistrationApi}       moduleRegistration
+ * @param {FdtCommand}                  command
+ * @param {AddBackendDockerCommandsOptions} options
+ */
+function addBackendDockerInitCommand(moduleRegistration, command, options) {
+	const initCommand = command.addCommand('init', async (...args) => {
+		const controllerFactory = (
+			await import(
+				pathToFileURL(
+					path.resolve(
+						__dirname,
+						'controller-templates',
+						'command.backend.init.controller.factory.js'
+					)
+				)
+			)
+		).default;
+		return controllerFactory(options)(...args);
+	});
+
+	initCommand
+		.setDescription(
+			`Initialize a ${options.productLabel} instance in an empty or nonexistent directory.`
+		)
+
+		.addOption(
+			'location',
+			'l',
+			'The directory where to initialize the instance. If not set this defaults to the current working directory. Note that the directory has to empty or nonexistent.',
+			false
+		)
+		.addOption(
+			'version',
+			null,
+			'The version to initialize with. Can be either a specific version or "nightly". Be warned: nightly can be unstable or may not work at all.',
+			true
+		)
+
+		.addExample(
+			`${moduleRegistration.getAppInfo().name} ${
+				options.commandPrefix
+			} init --version x.x.x`,
+			`Initialize a new ${options.productLabel} instance located at the current working directory.`
+		)
+		.addExample(
+			`${moduleRegistration.getAppInfo().name} ${
+				options.commandPrefix
+			} init --location /opt/my-instance/ --version x.x.x`,
+			`Initialize a new ${options.productLabel} instance located at "/opt/my-instance/".`
+		);
+}
+
+/**
+ * @param {ModuleRegistrationApi}       moduleRegistration
+ * @param {FdtCommand}                  command
+ * @param {AddBackendDockerCommandsOptions} options
+ */
+function addBackendDockerRunCommand(moduleRegistration, command, options) {
+	const hasHttps = !!options.defaultHttpsPort;
+
+	const runCommand = command.addCommand('run', async (...args) => {
+		const controllerFactory = (
+			await import(
+				pathToFileURL(
+					path.resolve(
+						__dirname,
+						'controller-templates',
+						'command.backend.run.controller.factory.js'
+					)
+				)
+			)
+		).default;
+		return controllerFactory(options)(...args);
+	});
+
+	runCommand.setDescription(
+		`Run a ${options.productLabel} instance${
+			hasHttps ? 'with a self-signed certificate' : ''
+		} for development purposes. Requires Docker to be installed.`
+	);
+
+	if (hasHttps) {
+		runCommand
+			.addOption(
+				'http-port',
+				null,
+				`Listen on the specified http port instead of listening on the default port (default=${options.defaultHttpPort}).`
+			)
+			.addOption(
+				'https-port',
+				null,
+				`Listen on the specified https port instead of listening on the default port (default=${options.defaultHttpsPort}).`
+			);
+	} else {
+		runCommand.addOption(
+			'port',
+			'p',
+			`Listen on the specified http port instead of listening on the default port (default=${options.defaultHttpPort}).`
+		);
+	}
+
+	runCommand
+		.addOption(
+			'location',
+			'l',
+			'The directory where the instance is located. Defaults to the current working directory.',
+			false
+		)
+		.addOption(
+			'config-location',
+			'c',
+			`The path where the configuration file (.env) is located.${
+				options.documentationConfigurationGuide
+					? ` Information about the .env file can be found at ${options.documentationConfigurationGuide}.`
+					: ''
+			}`,
+			false
+		)
+
+		.addOption(
+			'verbose',
+			null,
+			'Output default stdout and stderr information.'
+		)
+		.addOption(
+			'debug',
+			null,
+			`Output all debug information. This also overrides the ${Object.keys(
+				options.debugEnvEntries
+			).join(', ')} environment options if set.`
+		)
+
+		.addExample(
+			`${moduleRegistration.getAppInfo().name} ${
+				options.commandPrefix
+			} run`,
+			`Build and run a development image using the ${options.productLabel} instance and configuration located at the current working directory.`
+		)
+		.addExample(
+			`${moduleRegistration.getAppInfo().name} ${
+				options.commandPrefix
+			} run --location /opt/my-instances/specific-instance/ --config-location /opt/my-instances/.env`,
+			`Build and run a development image using the ${options.productLabel} instance located at "/opt/my-instances/specific-instance/" using the configuration located at "/opt/my-instances/.env".`
+		);
+
+	if (hasHttps) {
+		runCommand.addExample(
+			`${moduleRegistration.getAppInfo().name} ${
+				options.commandPrefix
+			} run --http-port 8080 --https-port 8443`,
+			`Build and run a development image using the ${options.productLabel} instance and configuration located at the current working directory on the non-default ports 8080 and 8443.`
+		);
+	} else {
+		runCommand.addExample(
+			`${moduleRegistration.getAppInfo().name} ${
+				options.commandPrefix
+			} run --port 7455`,
+			`Build and run a development image using the ${options.productLabel} instance and configuration located at the current working directory on the non-default port 7455.`
+		);
+	}
+}
+
+/**
+ * @param {ModuleRegistrationApi}       moduleRegistration
+ * @param {FdtCommand}                  command
+ * @param {AddBackendDockerCommandsOptions} options
+ */
+function addBackendDockerUpgradeCommand(moduleRegistration, command, options) {
+	const upgradeCommand = command.addCommand('upgrade', async (...args) => {
+		const controllerFactory = (
+			await import(
+				pathToFileURL(
+					path.resolve(
+						__dirname,
+						'controller-templates',
+						'command.backend.upgrade.controller.factory.js'
+					)
+				)
+			)
+		).default;
+		return controllerFactory(options)(...args);
+	});
+
+	upgradeCommand
+		.setDescription(
+			`Upgrade an existing ${options.productLabel} instance to the specified version.`
+		)
+
+		.addOption(
+			'location',
+			'l',
+			'The directory of the instance to upgrade. If not set this defaults to the current working directory.',
+			false
+		)
+		.addOption(
+			'version',
+			null,
+			'The version to upgrade to. Can be either a specific version or "nightly". Be warned: nightly can be unstable or may not work at all.',
+			true
+		)
+
+		.addExample(
+			`${moduleRegistration.getAppInfo().name} ${
+				options.commandPrefix
+			} upgrade --version x.x.x`,
+			`Upgrade the ${options.productLabel} instance located at the current working directory to version x.x.x.`
+		)
+		.addExample(
+			`${moduleRegistration.getAppInfo().name} ${
+				options.commandPrefix
+			} upgrade --location /opt/my-instance/ --version x.x.x`,
+			`Upgrade the ${options.productLabel} instance located at "/opt/my-instance/" to version x.x.x.`
+		);
+}
+
+/**
+ * @param {ModuleRegistrationApi}       moduleRegistration
+ * @param {FdtCommand}                  command
+ * @param {AddBackendDockerCommandsOptions} options
+ */
+export default function addBackendDockerCommands(
+	moduleRegistration,
+	command,
+	options
+) {
+	addBackendDockerBuildCommand(moduleRegistration, command, options);
+	addBackendDockerInitCommand(moduleRegistration, command, options);
+	addBackendDockerRunCommand(moduleRegistration, command, options);
+	addBackendDockerUpgradeCommand(moduleRegistration, command, options);
+}

package/src/modules/shared/src/addBackendDownloadSelfContainedCommands.js

@@ -0,0 +1,78 @@
+import path from 'path';
+import { fileURLToPath, pathToFileURL } from 'url';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+
+/**
+ * @typedef AddBackendDownloadSelfContainedCommandsOptions
+ *
+ * @property {string} productLabel
+ * @property {string} commandPrefix
+ * @property {string} licenseProductName
+ */
+
+/**
+ * @param {ModuleRegistrationApi}                      moduleRegistration
+ * @param {FdtCommand}                                 command
+ * @param {AddBackendDownloadSelfContainedCommandsOptions} options
+ */
+export default function addBackendDownloadSelfContainedCommands(
+	moduleRegistration,
+	command,
+	options
+) {
+	const downloadSelfContainedCommand = command.addCommand(
+		'download-self-contained',
+		async (...args) => {
+			const controllerFactory = (
+				await import(
+					pathToFileURL(
+						path.resolve(
+							__dirname,
+							'controller-templates',
+							'command.backend.download-self-contained.controller.factory.js'
+						)
+					)
+				)
+			).default;
+			return controllerFactory(options)(...args);
+		}
+	);
+
+	downloadSelfContainedCommand
+		.addAlias('dsc')
+		.setDescription('Downloads a self-contained build.')
+
+		.addOption(
+			'location',
+			'l',
+			'The directory where to save the self-contained build. If not set this defaults to the current working directory.',
+			false
+		)
+		.addOption(
+			'runtime',
+			null,
+			'The runtime to download. Supported values: linux-x64, win-x64.',
+			true
+		)
+		.addOption(
+			'version',
+			null,
+			'The version to download. Can be either a specific version or "nightly". Be warned: nightly can be unstable or may not work at all.',
+			true
+		)
+
+		.addExample(
+			`${moduleRegistration.getAppInfo().name} ${
+				options.commandPrefix
+			} download-self-contained --runtime linux-x64 --version x.x.x`,
+			`Download the linux-x64 self-contained build for ${options.productLabel} into the current working directory.`
+		)
+		.addExample(
+			`${moduleRegistration.getAppInfo().name} ${
+				options.commandPrefix
+			} download-self-contained --runtime linux-x64 --version x.x.x --location /opt/my-instance/`,
+			`Download the linux-x64 self-contained build for ${options.productLabel} into "/opt/my-instance/".`
+		);
+}

package/src/modules/shared/src/addBackendVersionsCommands.js

@@ -0,0 +1,55 @@
+import path from 'path';
+import { fileURLToPath, pathToFileURL } from 'url';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+
+/**
+ * @typedef AddBackendVersionsCommandsOptions
+ *
+ * @property {string} productLabel
+ * @property {string} commandPrefix
+ * @property {string} licenseProductName
+ */
+
+/**
+ * @param {ModuleRegistrationApi}         moduleRegistration
+ * @param {FdtCommand}                    command
+ * @param {AddBackendVersionsCommandsOptions} options
+ */
+export default function addBackendVersionsCommands(
+	moduleRegistration,
+	command,
+	options
+) {
+	const versionsCommand = command.addCommand('versions', async (...args) => {
+		const controllerFactory = (
+			await import(
+				pathToFileURL(
+					path.resolve(
+						__dirname,
+						'controller-templates',
+						'command.backend.versions.controller.factory.js'
+					)
+				)
+			)
+		).default;
+		return controllerFactory(options)(...args);
+	});
+
+	versionsCommand
+		.setDescription(`List the available ${options.productLabel} versions.`)
+
+		.addHiddenOption(
+			'all',
+			undefined,
+			'Include nightly and prerelease versions.'
+		)
+
+		.addExample(
+			`${moduleRegistration.getAppInfo().name} ${
+				options.commandPrefix
+			} versions`,
+			`Request the available versions for ${options.productLabel}.`
+		);
+}