@fontoxml/fontoxml-development-tools 3.7.0 → 3.8.1

package/src/modules/core/src/precontroller.debug.js

@@ -1,6 +1,6 @@
-'use strict';
+import inspector from 'inspector';
 
-module.exports = (moduleRegistration, app) => {
+export default (moduleRegistration, app) => {
 	function debugController(req, res) {
 		const inspect = !!req.options['fdt-inspect'] || process.env.FDT_INSPECT;
 		const inspectAndBreak =
@@ -15,7 +15,6 @@ module.exports = (moduleRegistration, app) => {
 		app.hideStacktraceOnErrors = false;
 
 		try {
-			const inspector = require('inspector');
 			inspector.open(undefined, undefined, inspectAndBreak);
 
 			if (inspectAndBreak) {

package/src/modules/core/src/precontroller.help.js

@@ -1,15 +1,17 @@
-'use strict';
+import path from 'path';
+import { fileURLToPath } from 'url';
 
-const path = require('path');
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
 
-const packageJson = require(path.join(
+const packageJson = path.resolve(
 	__dirname,
 	'..',
 	'..',
 	'..',
 	'..',
 	'package.json'
-));
+);
 
 const NO_DESCRIPTION = '<no description>';
 
@@ -33,7 +35,7 @@ function toOptionRow(option) {
 	];
 }
 
-module.exports = (moduleRegistration, app) => {
+export default (moduleRegistration, app) => {
 	function helpController(req, res) {
 		const command = req.command;
 		const isRoot = !command.parent;

package/src/modules/document-history/index.js

@@ -1,18 +1,27 @@
-'use strict';
+import commandBuild from './src/command.build.js';
+import commandDownloadSelfContained from './src/command.download-self-contained.js';
+import commandInit from './src/command.init.js';
+import commandRun from './src/command.run.js';
+import commandUpgrade from './src/command.upgrade.js';
+import commandVersions from './src/command.versions.js';
+import constants from './src/utilities/constants.js';
 
-module.exports = (moduleRegistration) => {
+export default (moduleRegistration) => {
 	const fdhCommand = moduleRegistration
-		.registerCommand('document-history')
+		.registerCommand(constants.COMMAND_PREFIX)
 		.setDescription(
 			'Provides tools for working with Fonto Document History.'
 		)
-		.addAlias('fdh')
+		.addAlias(constants.COMMAND_PREFIX_ALIAS)
+
 		.addRequiredProductLicenses(['document-history'])
 		.setHideIfMissingRequiredProductLicenses()
 		.setAsHelpCommand();
 
-	[
-		require('./src/command.download-self-contained.js'),
-		require('./src/command.versions.js'),
-	].forEach((mod) => mod(moduleRegistration, fdhCommand));
+	commandBuild(moduleRegistration, fdhCommand);
+	commandDownloadSelfContained(moduleRegistration, fdhCommand);
+	commandInit(moduleRegistration, fdhCommand);
+	commandRun(moduleRegistration, fdhCommand);
+	commandUpgrade(moduleRegistration, fdhCommand);
+	commandVersions(moduleRegistration, fdhCommand);
 };

package/src/modules/document-history/instanceBuild/Dockerfile

@@ -0,0 +1,4 @@
+FROM ${fdhImage}
+
+# copy files
+COPY ./instance .

package/src/modules/document-history/instanceDevBuild/.env

@@ -0,0 +1,2 @@
+# An empty .env is required since all files specified in the docker-compose must exist.
+# https://github.com/docker/compose/issues/3560

package/src/modules/document-history/instanceDevBuild/docker-compose.yml

@@ -0,0 +1,9 @@
+version: '3'
+services:
+    instance:
+        container_name: '${containerName}'
+        build: .
+        env_file:
+            - .env
+        ports:
+            - '${fdhPort}:80'

package/src/modules/document-history/instanceTemplate/.env

@@ -0,0 +1,7 @@
+# WARNING: We recommend not storing this file in version control since it can contain secrets.
+
+# Required configuration:
+#Cms__ApiBaseUrl=http://host.docker.internal:8080/connectors/cms/standard/
+
+# Optional configuration:
+#Logging__LogLevel__Default=Warning

package/src/modules/document-history/instanceTemplate/Configuration/sx.xml

@@ -0,0 +1,4 @@
+<?xml version="1.0" encoding="utf-8"?>
+<sx:schemaExperience xmlns:sx="http://schemas.fontoxml.com/document-history/2.0/schema-experience.xsd">
+	<!-- This is where your schema experience configuration needs to be filled in. See https://documentation.fontoxml.com/latest/configuration-for-document-history-c2092b6378a3 for more information. -->
+</sx:schemaExperience>

package/src/modules/document-history/package.json

@@ -9,5 +9,6 @@
 		"fonto",
 		"fontoxml"
 	],
-	"main": "index.js"
+	"main": "index.js",
+	"type": "module"
 }

package/src/modules/document-history/src/command.build.controller.js

@@ -0,0 +1,260 @@
+import fs from 'fs-extra';
+import path from 'path';
+
+import cleanup from './utilities/cleanup.js';
+import constants from './utilities/constants.js';
+import copyWhitelistedFiles from './utilities/copyWhitelistedFiles.js';
+import executeAndLog from './utilities/executeAndLog.js';
+import FontoxmlFdhManifest from './utilities/FontoxmlFdhManifest.js';
+import getVerbosityLevel from './utilities/getVerbosityLevel.js';
+import getWhitelist from './utilities/getWhitelist.js';
+import setEntryVisibility from './utilities/setEntryVisibility.js';
+import validateInstance from './utilities/validateInstance.js';
+
+export default function buildCommand(req, res) {
+	res.caption(req.command.getLongName());
+
+	const directoryPath = path.resolve(
+		req.options.location ? req.options.location : process.cwd()
+	);
+	const temporaryDirectoryPath = path.join(
+		directoryPath,
+		constants.TEMPORARY_BUILD_DIRECTORY_NAME
+	);
+	const imageName = req.options['image-name']
+		? req.options['image-name']
+		: constants.DEFAULT_IMAGE_NAME;
+	const imageTag = req.options['image-tag']
+		? req.options['image-tag']
+		: constants.DEFAULT_IMAGE_TAG;
+	const manifestFilePath = path.join(
+		directoryPath,
+		constants.MANIFEST_FILENAME
+	);
+	const verbosityLevel = getVerbosityLevel(
+		req.options.verbose,
+		req.options.debug
+	);
+
+	let pidToKillOnForceExit = null;
+	const setPidToKillOnForceExit = (process) => {
+		pidToKillOnForceExit = process && process.pid;
+	};
+
+	// Ensure we cleanup before exiting.
+	let stopping = false;
+	process.on('SIGINT', (_code) => {
+		if (stopping) {
+			if (pidToKillOnForceExit) {
+				process.kill(pidToKillOnForceExit);
+			}
+			process.exit();
+			return;
+		}
+
+		stopping = true;
+		res.log('Gracefully stopping... (press Ctrl+C again to force)');
+		return cleanup(
+			temporaryDirectoryPath,
+			undefined,
+			res,
+			verbosityLevel
+		).then(process.exit);
+	});
+
+	return (
+		validateInstance(directoryPath)
+			// Cleanup possible remaining resources from a previous build or run.
+			.then(() =>
+				cleanup(temporaryDirectoryPath, undefined, res, verbosityLevel)
+			)
+			.then(() => {
+				const destroySpinner = res.spinner(
+					`Building the production image "${imageName}:${imageTag}" at "${directoryPath}"...`
+				);
+
+				// Retrieve data for the docker image
+				return FontoxmlFdhManifest.fromJsonFile(manifestFilePath).then(
+					(manifestObj) => {
+						const requestObj = {
+							'document-history': {
+								docker: {
+									version: manifestObj.fdhVersion,
+								},
+							},
+						};
+
+						return req.fdt.license
+							.getDataForProducts(requestObj)
+							.catch((error) => {
+								if (error.statusCode === 404) {
+									error.solution =
+										'This error might be caused by requesting a nonexistent Fonto Document History version, please check your version.';
+								}
+								throw error;
+							})
+							.then((productData) => {
+								const dockerData =
+									productData.products['document-history']
+										.docker;
+
+								// Create a hidden temporary directory.
+								return (
+									fs
+										.mkdir(temporaryDirectoryPath)
+										.then(() =>
+											setEntryVisibility(
+												temporaryDirectoryPath,
+												false
+											)
+										)
+										// Copy the instance files into the temporary directory.
+										.then(() => {
+											// Rewrite the version in the Dockerfile.
+											return fs
+												.readFile(
+													path.join(
+														constants.INSTANCE_BUILD_DIRECTORY_PATH,
+														'Dockerfile'
+													),
+													'utf8'
+												)
+												.then((dockerContent) =>
+													dockerContent.replace(
+														'${fdhImage}',
+														dockerData.image
+													)
+												)
+												.then((fixedDockerContent) =>
+													fs.writeFile(
+														path.join(
+															temporaryDirectoryPath,
+															'Dockerfile'
+														),
+														fixedDockerContent
+													)
+												);
+										})
+										.then(() => getWhitelist())
+										.then((whitelist) =>
+											copyWhitelistedFiles(
+												whitelist,
+												directoryPath,
+												path.join(
+													temporaryDirectoryPath,
+													'instance'
+												)
+											)
+										)
+
+										// Pull the docker image
+										.then(() => {
+											return executeAndLog(
+												res,
+												'docker',
+												[
+													'login',
+													dockerData.registry,
+													'-u',
+													dockerData.login,
+													'-p',
+													dockerData.password,
+												],
+												null,
+												constants.VERBOSITY_LEVEL_NORMAL,
+												false,
+												setPidToKillOnForceExit
+											)
+												.then(() =>
+													executeAndLog(
+														res,
+														'docker',
+														[
+															'pull',
+															dockerData.image,
+														],
+														null,
+														verbosityLevel,
+														false,
+														setPidToKillOnForceExit
+													)
+												)
+												.then(() =>
+													executeAndLog(
+														res,
+														'docker',
+														[
+															'logout',
+															dockerData.registry,
+														],
+														null,
+														constants.VERBOSITY_LEVEL_NORMAL,
+														false,
+														setPidToKillOnForceExit
+													)
+												)
+												.catch(() => {
+													throw new Error(
+														'Failed to retrieve the image file.'
+													);
+												});
+										})
+
+										// Build the docker image.
+										.then(() =>
+											executeAndLog(
+												res,
+												'docker',
+												[
+													'build',
+													'-t',
+													`${imageName}:${imageTag}`,
+													'.',
+												],
+												temporaryDirectoryPath,
+												verbosityLevel,
+												false,
+												setPidToKillOnForceExit
+											)
+										)
+										.then(() =>
+											req.fdt.license.sendTelemetry({
+												product:
+													req.command.parent.name,
+												type: 'docker',
+												version: manifestObj.fdhVersion,
+												action: req.command.name,
+											})
+										)
+										.then(() => destroySpinner())
+								);
+							});
+					}
+				);
+			})
+			// Cleanup temporary directory.
+			.then(() =>
+				cleanup(temporaryDirectoryPath, undefined, res, verbosityLevel)
+			)
+			.catch((error) => {
+				if (!stopping) {
+					res.notice(
+						`See our documentation at ${constants.DOCUMENTATION_EXECUTE_ERROR} for help.`
+					);
+				}
+
+				return cleanup(
+					temporaryDirectoryPath,
+					undefined,
+					res,
+					verbosityLevel
+				)
+					.then(() => {
+						throw error;
+					})
+					.catch(() => {
+						throw error;
+					});
+			})
+	);
+}

package/src/modules/document-history/src/command.build.js

@@ -0,0 +1,56 @@
+import path from 'path';
+import { fileURLToPath } from 'url';
+
+import constants from './utilities/constants.js';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+
+export default (moduleRegistration, fdhCommand) => {
+	fdhCommand
+		.addCommand(
+			'build',
+			path.resolve(__dirname, 'command.build.controller.js')
+		)
+		.setDescription(
+			'Build a Fonto Document History 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 ${constants.DEFAULT_IMAGE_NAME}.`,
+			false
+		)
+		.addOption(
+			'image-tag',
+			't',
+			`The tag of the Docker image which will be created. This defaults to ${constants.DEFAULT_IMAGE_TAG}.`,
+			false
+		)
+		.addOption(
+			'location',
+			'l',
+			'The directory where the Fonto Document History 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} ${
+				constants.COMMAND_PREFIX
+			} build`,
+			`Build production image "${constants.DEFAULT_IMAGE_NAME}:${constants.DEFAULT_IMAGE_NAME}" using the Fonto Document History instance located at the current working directory.`
+		)
+		.addExample(
+			`${moduleRegistration.getAppInfo().name} ${
+				constants.COMMAND_PREFIX
+			} build --image-name my-fdh-instance --image-tag 1.0.0 --location /opt/my-instance/`,
+			'Build production image "my-fdh-instance:1.0.0" using the Fonto Document History instance located at "/opt/my-instance/".'
+		);
+};

package/src/modules/document-history/src/command.download-self-contained.controller.js

@@ -1,11 +1,9 @@
-'use strict';
+import fs from 'fs-extra';
+import path from 'path';
+import requestPromise from 'request-promise-native';
+import url from 'url';
 
-const fs = require('fs-extra');
-const path = require('path');
-const requestPromise = require('request-promise-native');
-const url = require('url');
-
-module.exports = function buildCommand(req, res) {
+export default function buildCommand(req, res) {
 	res.caption(req.command.getLongName());
 
 	const directoryPath = path.resolve(
@@ -109,4 +107,4 @@ module.exports = function buildCommand(req, res) {
 					);
 				});
 		});
-};
+}

package/src/modules/document-history/src/command.download-self-contained.js

@@ -1,10 +1,17 @@
-'use strict';
+import path from 'path';
+import { fileURLToPath } from 'url';
 
-module.exports = (moduleRegistration, connectorsCommand) => {
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+
+export default (moduleRegistration, connectorsCommand) => {
 	connectorsCommand
 		.addCommand(
 			'download-self-contained',
-			'./command.download-self-contained.controller'
+			path.resolve(
+				__dirname,
+				'command.download-self-contained.controller.js'
+			)
 		)
 		.addAlias('dsc')
 		.setDescription('Downloads a self-contained build.')

package/src/modules/document-history/src/command.init.controller.js

@@ -0,0 +1,91 @@
+import fs from 'fs-extra';
+import path from 'path';
+
+import constants from './utilities/constants.js';
+import FontoxmlFdhManifest from './utilities/FontoxmlFdhManifest.js';
+import setEntryVisibility from './utilities/setEntryVisibility.js';
+
+export default async function initCommand(req, res) {
+	res.caption(req.command.getLongName());
+
+	// Check if the version exists.
+	const sdkVersions = await req.fdt.license.getVersionsForProduct(
+		'document-history'
+	);
+	const version = req.options.version;
+	if (!sdkVersions.includes(version)) {
+		throw new Error(
+			`Could not initialize for version (${version}), please check if it is a valid version. The latest version is ${sdkVersions.getLatestStable()}, run \`fdt document-history versions\` to get a list of all available versions.`
+		);
+	}
+
+	const directoryPath = path.resolve(
+		req.options.location ? req.options.location : process.cwd()
+	);
+	return fs
+		.exists(directoryPath)
+		.then((exists) => {
+			if (!exists) {
+				// Create the directory if it does not exist.
+				return fs.ensureDir(directoryPath);
+			}
+			// Ensure the directory is empty if it does exist.
+			return fs.readdir(directoryPath).then((files) => {
+				if (files.length) {
+					throw new Error(
+						`The directory "${directoryPath}" is not empty.`
+					);
+				}
+			});
+		})
+		.then(() => {
+			const destroySpinner = res.spinner(
+				`Initializing a Fonto Document History instance at "${directoryPath}"...`
+			);
+			return fs
+				.copy(
+					constants.INSTANCE_TEMPLATE_DIRECTORY_PATH,
+					directoryPath,
+					{
+						filter: (src, _dest) => {
+							const filename = path.basename(src);
+							return filename !== '.gitkeep';
+						},
+					}
+				)
+				.then(() => {
+					const data = new FontoxmlFdhManifest(version);
+					const manifest = path.join(
+						directoryPath,
+						constants.MANIFEST_FILENAME
+					);
+
+					return fs
+						.writeJson(manifest, data)
+						.then(() => setEntryVisibility(manifest, false));
+				})
+				.catch((error) => {
+					return fs.emptyDir(directoryPath).then(() => {
+						destroySpinner();
+						throw error;
+					});
+				})
+				.then(() =>
+					req.fdt.license.sendTelemetry({
+						product: req.command.parent.name,
+						type: 'docker',
+						version,
+						action: req.command.name,
+					})
+				)
+				.then(() => destroySpinner());
+		})
+		.then(() => {
+			res.log(
+				'Complete the configuration before building or running the instance.'
+			);
+			res.log(
+				`See ${constants.DOCUMENTATION_GETTING_STARTED_GUIDE} for more information.`
+			);
+		});
+}

package/src/modules/document-history/src/command.init.js

@@ -0,0 +1,44 @@
+import path from 'path';
+import { fileURLToPath } from 'url';
+
+import constants from './utilities/constants.js';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+
+export default (moduleRegistration, fdhCommand) => {
+	fdhCommand
+		.addCommand(
+			'init',
+			path.resolve(__dirname, 'command.init.controller.js')
+		)
+		.setDescription(
+			'Initialize a Fonto Document History 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 be 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} ${
+				constants.COMMAND_PREFIX
+			} init --version x.x.x`,
+			'Initialize a new Fonto Document History instance located at the current working directory.'
+		)
+		.addExample(
+			`${moduleRegistration.getAppInfo().name} ${
+				constants.COMMAND_PREFIX
+			} init --location /opt/my-instance/ --version x.x.x`,
+			'Initialize a new Fonto Document History instance located at "/opt/my-instance/".'
+		);
+};