@fontoxml/fontoxml-development-tools 3.11.0 → 3.12.0

package/src/modules/shared/src/controller-templates/docker/dockerCleanup.js

@@ -0,0 +1,146 @@
+import fs from 'fs-extra';
+import path from 'path';
+
+import executeAndLog, { VERBOSITY_LEVEL } from '../../executeAndLog.js';
+
+/**
+ * @param {string}      temporaryDirectoryPath
+ * @param {string}      projectName
+ * @param {FdtResponse} res
+ * @param {number}      verbosityLevel
+ *
+ * @return {Promise<void>}
+ */
+async function actualCleanup(
+	temporaryDirectoryPath,
+	projectName,
+	res,
+	verbosityLevel
+) {
+	const temporaryDirectoryExists = await fs.exists(temporaryDirectoryPath);
+	if (!temporaryDirectoryExists) {
+		return;
+	}
+
+	const destroySpinner = res.spinner('Removing temporary resources...');
+
+	try {
+		const dockerComposeFileExists = await fs.exists(
+			path.join(temporaryDirectoryPath, 'docker-compose.yml')
+		);
+
+		const errors = [];
+		const tasks = [
+			async () => {
+				if (dockerComposeFileExists && projectName) {
+					await executeAndLog(
+						res,
+						'docker',
+						verbosityLevel === VERBOSITY_LEVEL.DEBUG
+							? [
+									'compose',
+									'-p',
+									projectName,
+									'--verbose',
+									'down',
+									'--rmi',
+									'local',
+							  ]
+							: [
+									'compose',
+									'-p',
+									projectName,
+									'down',
+									'--rmi',
+									'local',
+							  ],
+						temporaryDirectoryPath,
+						verbosityLevel
+					);
+				}
+			},
+			async () => {
+				await fs.remove(temporaryDirectoryPath);
+			},
+		];
+
+		// Run all cleanup tasks in order. Continue on errors. But collect the errors.
+		for (let i = 0; i < tasks.length; i++) {
+			try {
+				await tasks[i]();
+			} catch (error) {
+				errors.push(error);
+			}
+		}
+
+		// Only throw if a task have failed.
+		if (errors.length > 0) {
+			throw errors[0];
+		}
+		// eslint-disable-next-line no-useless-catch
+	} catch (error) {
+		throw error;
+	} finally {
+		destroySpinner();
+	}
+}
+
+const cleanupQueuePromises = new Set();
+
+/**
+ * @param {string}      temporaryDirectoryPath
+ * @param {string}      projectName
+ * @param {FdtResponse} res
+ * @param {number}      verbosityLevel
+ *
+ * @return {Promise<void>}
+ */
+export default async function dockerCleanup(
+	temporaryDirectoryPath,
+	projectName,
+	res,
+	verbosityLevel
+) {
+	// Get the existing queue promises.
+	const existingCleanupQueuePromises = [...cleanupQueuePromises];
+
+	// Create a queue entry.
+	let cleanupQueuePromiseResolve = null;
+	let cleanupQueuePromiseReject = null;
+	const cleanupQueuePromise = new Promise((resolve, reject) => {
+		cleanupQueuePromiseResolve = resolve;
+		cleanupQueuePromiseReject = reject;
+	});
+	cleanupQueuePromises.add(cleanupQueuePromise);
+
+	// Wait for existing cleanup queue promises.
+	await Promise.all(
+		existingCleanupQueuePromises.map(
+			async (existingCleanupQueuePromise) => {
+				try {
+					await existingCleanupQueuePromise;
+				} catch (_error) {
+					// Ignore other cleanup errors.
+				}
+			}
+		)
+	);
+
+	// Call actual cleanup, resolving/rejecting the queue promise when done.
+	await actualCleanup(
+		temporaryDirectoryPath,
+		projectName,
+		res,
+		verbosityLevel
+	)
+		.then((...args) => {
+			cleanupQueuePromises.delete(cleanupQueuePromise);
+			cleanupQueuePromiseResolve(...args);
+		})
+		.catch((error) => {
+			cleanupQueuePromises.delete(cleanupQueuePromise);
+			cleanupQueuePromiseReject(error);
+		});
+
+	return cleanupQueuePromise;
+}

package/src/modules/shared/src/controller-templates/docker/tryDockerLogout.js

@@ -0,0 +1,31 @@
+import executeAndLog, { VERBOSITY_LEVEL } from '../../executeAndLog.js';
+
+/** @typedef {import('../../executeAndLog').ProcessCreatedCallback} ProcessCreatedCallback */
+
+/**
+ * @param {string}                 registry
+ * @param {FdtResponse}            res
+ * @param {ProcessCreatedCallback} setPidToKillOnForceExit
+ *
+ * @returns {Promise<void>}
+ */
+export default async function tryDockerLogout(
+	registry,
+	res,
+	setPidToKillOnForceExit
+) {
+	try {
+		// Clear the time limited login credentials.
+		await executeAndLog(
+			res,
+			'docker',
+			['logout', registry],
+			null,
+			VERBOSITY_LEVEL.NORMAL,
+			false,
+			setPidToKillOnForceExit
+		);
+	} catch (_error) {
+		// Ignore error.
+	}
+}

package/src/modules/shared/src/controller-templates/docker/validateBackendInstance.js

@@ -0,0 +1,48 @@
+import fs from 'fs-extra';
+import path from 'path';
+
+import BackendManifest from './BackendManifest.js';
+
+/** @typedef {import('../../addBackendDockerCommands').AddBackendDockerCommandsOptions} AddBackendDockerCommandsOptions */
+
+/**
+ * @param {string}                          directoryPath
+ * @param {AddBackendDockerCommandsOptions} options
+ *
+ * @return {Promise<void>}
+ */
+export default async function validateBackendInstance(directoryPath, options) {
+	const manifestFilePath = path.join(directoryPath, options.manifestFileName);
+
+	// Verify that the instance directory exists.
+	const directoryExists = await fs.exists(directoryPath);
+	if (!directoryExists) {
+		throw new Error(`Directory "${directoryPath}" does not exist.`);
+	}
+
+	// Verify that the BackendManifest file exists
+	const manifestExists = await fs.exists(manifestFilePath);
+	if (!manifestExists) {
+		throw new Error(
+			`The ${options.manifestFileName} manifest file does not exist.`
+		);
+	}
+
+	// Verify that the BackendManifest file is valid.
+	await BackendManifest.fromJsonFile(
+		manifestFilePath,
+		options.manifestVersionPropertyName
+	);
+
+	// Verify that all required configuration files exist.
+	await Promise.all(
+		options.requiredConfiguration.map(async (entryName) => {
+			const exists = await fs.exists(path.join(directoryPath, entryName));
+			if (!exists) {
+				throw new Error(
+					`Directory "${directoryPath}" does not contain a valid ${options.productLabel} instance. Missing "${entryName}".`
+				);
+			}
+		})
+	);
+}

package/src/modules/shared/src/ensureDockerCommands.js

@@ -0,0 +1,61 @@
+import executeAndLog, { VERBOSITY_LEVEL } from './executeAndLog.js';
+
+/**
+ * @typedef EnsureDockerCommandsOptions
+ *
+ * @property {boolean} [checkDocker=true]
+ * @property {boolean} [checkDockerCompose=false]
+ */
+
+/**
+ * Ensures that the Docker, and optionally also Docker compose, commands are available.
+ *
+ * NOTE: This does not check if Docker is running.
+ *
+ * @param {string}                      workingDirectory
+ * @param {FdtResponse}                 res
+ * @param {EnsureDockerCommandsOptions} [options={}]
+ *
+ * @returns {Promise<void>}
+ */
+export default async function ensureDockerCommands(
+	workingDirectory,
+	res,
+	options = { checkDocker: true, checkDockerCompose: false }
+) {
+	if (options.checkDocker) {
+		try {
+			await executeAndLog(
+				res,
+				'docker',
+				['-v'],
+				workingDirectory,
+				VERBOSITY_LEVEL.SILENT,
+				false
+			);
+		} catch (_error) {
+			throw new res.ErrorWithSolution(
+				'Cannot run Docker commands.',
+				'Please make sure Docker is installed. See: https://docs.docker.com/install/.'
+			);
+		}
+	}
+
+	if (options.checkDockerCompose) {
+		try {
+			await executeAndLog(
+				res,
+				'docker',
+				['compose', 'version'],
+				workingDirectory,
+				VERBOSITY_LEVEL.SILENT,
+				false
+			);
+		} catch (_error) {
+			throw new res.ErrorWithSolution(
+				'Cannot run Docker Compose commands.',
+				'Please make sure the Docker Compose plugin is installed, which differs from the docker-compose standalone tool. See: https://docs.docker.com/compose/install/.'
+			);
+		}
+	}
+}

package/src/modules/shared/src/executeAndLog.js

@@ -0,0 +1,113 @@
+import cp from 'child_process';
+
+/** @typedef {import('child_process').ChildProcess} ChildProcess */
+
+/**
+ * @callback ProcessCreatedCallback
+ *
+ * @param {ChildProcess} process
+ *
+ * @return {void}
+ */
+
+export const VERBOSITY_LEVEL = {
+	SILENT: -1,
+	NORMAL: 0,
+	VERBOSE: 1,
+	DEBUG: 2,
+};
+
+/**
+ * @param {boolean} verbose
+ * @param {boolean} debug
+ *
+ * @returns {number}
+ */
+export function getVerbosityLevel(verbose, debug) {
+	if (debug) {
+		return VERBOSITY_LEVEL.DEBUG;
+	}
+	if (verbose) {
+		return VERBOSITY_LEVEL.VERBOSE;
+	}
+	return VERBOSITY_LEVEL.NORMAL;
+}
+
+/**
+ * @param {FdtResponse}            res
+ * @param {string}                 command
+ * @param {string[]}               args
+ * @param {string}                 currentWorkingDirectoryPath
+ * @param {number}                 verbosityLevel
+ * @param {boolean}                showStdout
+ * @param {ProcessCreatedCallback} processCreatedCallback
+ * @param {number[]}               [additionalSuccessExitCodes=[]]
+ *
+ * @returns {Promise<void>}
+ */
+function executeAndLog(
+	res,
+	command,
+	args,
+	currentWorkingDirectoryPath,
+	verbosityLevel,
+	showStdout,
+	processCreatedCallback,
+	additionalSuccessExitCodes = []
+) {
+	return new Promise((resolve, reject) => {
+		const errors = [];
+		const childProcess = cp.spawn(command, args, {
+			cwd: currentWorkingDirectoryPath,
+		});
+		const silent = verbosityLevel === VERBOSITY_LEVEL.SILENT;
+		const verbose =
+			verbosityLevel === VERBOSITY_LEVEL.VERBOSE ||
+			verbosityLevel === verbosityLevel.DEBUG;
+		const debug = verbosityLevel === VERBOSITY_LEVEL.DEBUG;
+
+		if (processCreatedCallback) {
+			processCreatedCallback(process);
+		}
+
+		childProcess.stdout.on('data', (data) => {
+			if (verbose || showStdout) {
+				res.raw(data);
+			}
+		});
+
+		childProcess.stderr.on('data', (data) => {
+			if (debug) {
+				res.raw(data);
+			} else {
+				errors.push(data.toString());
+			}
+		});
+
+		childProcess.on('error', (error) => {
+			res.error(error);
+		});
+
+		childProcess.on('close', (code) => {
+			if (code === 0 || additionalSuccessExitCodes.includes(code)) {
+				if (verbose) {
+					res.debug(
+						`${command} ${args.join(' ')} exited with code ${code}`
+					);
+				}
+				resolve();
+			} else {
+				if (!debug && !silent) {
+					errors.forEach((error) => res.log(error));
+				}
+				reject(
+					new Error(
+						`${command} ${args.join(' ')} exited with code ${code}`
+					)
+				);
+			}
+		});
+	});
+}
+
+export default executeAndLog;

package/src/modules/{review/src/utilities/setEntryVisibility.js → shared/src/setFileVisibility.js}

@@ -1,10 +1,16 @@
 import fswin from 'fswin';
 
-export default function setEntryVisibility(entryPath, isVisible) {
+/**
+ * @param {string}  filePath
+ * @param {boolean} isVisible
+ *
+ * @return {Promise<void>}
+ */
+export default function setFileVisibility(filePath, isVisible) {
 	return new Promise((resolve, reject) => {
 		if (fswin) {
 			fswin.setAttributes(
-				entryPath,
+				filePath,
 				{ IS_HIDDEN: !isVisible },
 				(success) => {
 					if (!success) {

package/src/modules/spell-checker/index.js

@@ -1,22 +1,105 @@
-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';
-
-export default (moduleRegistration) => {
-	const spellCheckerCommand = moduleRegistration
-		.registerCommand('spell-checker')
-		.setDescription('Provides tools for working with Fonto Spell Checker.')
-		.addRequiredProductLicenses(['editor'])
+import path from 'path';
+import { fileURLToPath, pathToFileURL } from 'url';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+
+export default async (moduleRegistration) => {
+	const options = {
+		licenseProductName: 'spell-checker',
+		licensesRequired: ['editor'],
+		productLabel: 'Fonto Spell Checker',
+		commandPrefix: 'spell-checker',
+
+		documentationConfigurationGuide:
+			'https://documentation.fontoxml.com/latest/fontoxml-spell-checker-4428b1080ce1',
+		documentationExecuteError:
+			'https://documentation.fontoxml.com/latest/fontoxml-spell-checker-4428b1080ce1',
+		documentationGettingStartedGuide:
+			'https://documentation.fontoxml.com/latest/fontoxml-spell-checker-4428b1080ce1',
+
+		defaultHttpPort: 6050,
+		defaultImageName: 'fonto-spell-checker',
+		defaultImageTag: 'latest',
+
+		manifestFileName: '.fontoxmlSpellCheckerManifest',
+		manifestVersionPropertyName: 'spellCheckerVersion',
+
+		instanceBuildDockerfilePath: path.join(
+			__dirname,
+			'instanceBuild',
+			'Dockerfile'
+		),
+		instanceDevBuildDirectoryPath: path.join(__dirname, 'instanceDevBuild'),
+		instanceDevBuildDockerfilePath: path.join(
+			__dirname,
+			'instanceBuild',
+			'Dockerfile'
+		),
+		instanceTemplateDirectoryPath: path.join(__dirname, 'instanceTemplate'),
+
+		requiredConfiguration: [],
+		temporaryDirectoryName: '.spellCheckerTmp',
+		temporaryBuildDirectoryName: '.spellCheckerBuildTmp',
+		whitelist: [
+			// Optional.
+			'nlog.config',
+		],
+
+		debugEnvEntries: {
+			Logging__LogLevel__Default: 'Trace',
+		},
+	};
+
+	const command = moduleRegistration
+		.registerCommand(options.commandPrefix)
+		.setDescription(
+			`Provides tools for working with ${options.productLabel}.`
+		)
+
+		.addRequiredProductLicenses(options.licensesRequired)
 		.setHideIfMissingRequiredProductLicenses()
 		.setAsHelpCommand();
 
-	commandBuild(moduleRegistration, spellCheckerCommand);
-	commandDownloadSelfContained(moduleRegistration, spellCheckerCommand);
-	commandInit(moduleRegistration, spellCheckerCommand);
-	commandRun(moduleRegistration, spellCheckerCommand);
-	commandUpgrade(moduleRegistration, spellCheckerCommand);
-	commandVersions(moduleRegistration, spellCheckerCommand);
+	if (options.commandAlias) {
+		command.addAlias(options.commandAlias);
+	}
+
+	const sharedModulePath = moduleRegistration.getPathToModule(
+		'@fontoxml/fontoxml-development-tools-module-shared'
+	);
+
+	// Add the docker based commands.
+	const addBackendDockerCommandsPath = pathToFileURL(
+		path.resolve(sharedModulePath, 'src/addBackendDockerCommands.js')
+	);
+	const addBackendDockerCommands = (
+		await import(addBackendDockerCommandsPath)
+	).default;
+	addBackendDockerCommands(moduleRegistration, command, options);
+
+	// Add the version commands.
+	const addBackendVersionsCommandsPath = pathToFileURL(
+		path.resolve(sharedModulePath, 'src/addBackendVersionsCommands.js')
+	);
+	const addBackendVersionsCommands = (
+		await import(addBackendVersionsCommandsPath)
+	).default;
+	addBackendVersionsCommands(moduleRegistration, command, options);
+
+	// Add the download-self-contained command.
+	const addBackendDownloadSelfContainedCommandsPath = pathToFileURL(
+		path.resolve(
+			sharedModulePath,
+			'src/addBackendDownloadSelfContainedCommands.js'
+		)
+	);
+	const addBackendDownloadSelfContainedCommands = (
+		await import(addBackendDownloadSelfContainedCommandsPath)
+	).default;
+	addBackendDownloadSelfContainedCommands(
+		moduleRegistration,
+		command,
+		options
+	);
 };

package/src/modules/spell-checker/instanceBuild/Dockerfile

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

package/src/modules/spell-checker/instanceDevBuild/docker-compose.yml

@@ -6,4 +6,4 @@ services:
         env_file:
             - .env
         ports:
-            - '${spellCheckerPort}:80'
+            - '${httpPort}:80'

package/test/module.shared.test.js

@@ -0,0 +1,81 @@
+import AskNicely from 'ask-nicely';
+import assert from 'assert';
+import fs from 'fs-extra';
+import path from 'path';
+import { fileURLToPath } from 'url';
+
+import { App } from '../index.js';
+
+const defaultStdoutColumns = process.stdout.columns;
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+
+async function cleanupAppDir() {
+	await new Promise((response, reject) =>
+		fs.remove(path.join(process.cwd(), '.fdttestrc'), (err) =>
+			err ? reject(err) : response()
+		)
+	);
+
+	await new Promise((response, reject) =>
+		fs.remove(path.join(__dirname, '..', '.fdttestrc'), (err) =>
+			err ? reject(err) : response()
+		)
+	);
+}
+
+let app;
+let oldCwd;
+let sharedModulePath;
+let sharedModule;
+
+before(cleanupAppDir);
+after(cleanupAppDir);
+
+describe('module: shared', () => {
+	beforeEach(async () => {
+		process.stdout.columns = 150;
+
+		oldCwd = process.cwd();
+		process.chdir(path.join(__dirname, 'app'));
+
+		app = new App();
+
+		await app.init({
+			appName: 'fontoxml-development-tools-test',
+			skipWarnIfNotInsideEditorRepository: true,
+			testMode: true,
+		});
+
+		sharedModulePath = path.join(
+			__dirname,
+			'..',
+			'src',
+			'modules',
+			'shared'
+		);
+		sharedModule = app.modules.find(
+			(c) =>
+				c.getInfo().name ===
+				'@fontoxml/fontoxml-development-tools-module-shared'
+		);
+	});
+
+	afterEach(() => {
+		process.chdir(oldCwd);
+
+		process.stdout.columns = defaultStdoutColumns;
+	});
+
+	it('has enabled this shared module', () => {
+		assert.ok(
+			app.modules.some(
+				(c) =>
+					c.getInfo().name ===
+					'@fontoxml/fontoxml-development-tools-module-shared'
+			)
+		);
+		assert.ok(app.modules.some((c) => c === sharedModule));
+	});
+});