add harper application lock file and some unit tests (#11)

Author: Ethan-Arrowood

components/Application.ts

@@ -3,7 +3,19 @@ import { CONFIG_PARAMS } from '../utility/hdbTerms.js';
 import logger from '../utility/logging/harper_logger.js';
 
 import { dirname, extname, join } from 'node:path';
-import { access, constants, cp, mkdir, mkdtemp, readdir, readFile, rm, stat, symlink } from 'node:fs/promises';
+import {
+	access,
+	constants,
+	cp,
+	mkdir,
+	mkdtemp,
+	readdir,
+	readFile,
+	rm,
+	stat,
+	symlink,
+	writeFile,
+} from 'node:fs/promises';
 import { spawn } from 'node:child_process';
 import { createReadStream, existsSync, readdirSync } from 'node:fs';
 import { Readable } from 'node:stream';
@@ -13,43 +25,74 @@ import { extract } from 'tar-fs';
 import gunzip from 'gunzip-maybe';
 
 interface ApplicationConfig {
+	// define known config properties
 	package: string;
 	install?: {
 		command?: string;
 		timeout?: number;
 	};
+	// an application config can have other arbitrary properties
+	[key: string]: unknown;
+}
+
+export class InvalidPackageIdentifierError extends TypeError {
+	constructor(applicationName: string, packageIdentifier: unknown) {
+		super(
+			`Invalid 'package' property for application ${applicationName}: expected string, got ${typeof packageIdentifier}`
+		);
+	}
+}
+
+export class InvalidInstallPropertyError extends TypeError {
+	constructor(applicationName: string, installProperty: unknown) {
+		super(
+			`Invalid 'install' property for application ${applicationName}: expected object, got ${typeof installProperty}`
+		);
+	}
+}
+
+export class InvalidInstallCommandError extends TypeError {
+	constructor(applicationName: string, command: unknown) {
+		super(
+			`Invalid 'install.command' property for application ${applicationName}: expected string, got ${typeof command}`
+		);
+	}
+}
+
+export class InvalidInstallTimeoutError extends TypeError {
+	constructor(applicationName: string, timeout: unknown) {
+		super(
+			`Invalid 'install.timeout' property for application ${applicationName}: expected non-negative number, got ${typeof timeout}`
+		);
+	}
 }
 
 export function assertApplicationConfig(
 	applicationName: string,
-	applicationConfig: object & Record<'package', unknown>
+	applicationConfig: Record<'package', unknown> & Record<string, unknown>
 ): asserts applicationConfig is ApplicationConfig {
 	if (typeof applicationConfig.package !== 'string') {
-		throw new TypeError(
-			`Invalid 'package' property for application ${applicationName}: expected string, got ${typeof applicationConfig.package}`
-		);
+		throw new InvalidPackageIdentifierError(applicationName, applicationConfig.package);
 	}
 
 	if ('install' in applicationConfig) {
-		if (typeof applicationConfig.install !== 'object' || applicationConfig.install === null) {
-			throw new TypeError(
-				`Invalid 'install' property for application ${applicationName}: expected object, got ${typeof applicationConfig.install}`
-			);
+		if (
+			typeof applicationConfig.install !== 'object' ||
+			applicationConfig.install === null ||
+			Array.isArray(applicationConfig.install)
+		) {
+			throw new InvalidInstallPropertyError(applicationName, applicationConfig.install);
 		}
 
 		if ('command' in applicationConfig.install && typeof applicationConfig.install.command !== 'string') {
-			throw new TypeError(
-				`Invalid 'install.command' property for application ${applicationName}: expected string, got ${typeof applicationConfig.install.command}`
-			);
+			throw new InvalidInstallCommandError(applicationName, applicationConfig.install.command);
 		}
 
 		if (
 			'timeout' in applicationConfig.install &&
 			(typeof applicationConfig.install.timeout !== 'number' || applicationConfig.install.timeout < 0)
 		) {
-			throw new TypeError(
-				`Invalid 'install.timeout' property for application ${applicationName}: expected non-negativenumber, got ${typeof applicationConfig.install.timeout}`
-			);
+			throw new InvalidInstallTimeoutError(applicationName, applicationConfig.install.timeout);
 		}
 	}
 }
@@ -184,8 +227,9 @@ export async function extractApplication(application: Application) {
  * This method should only be called from the main thread
  */
 export async function installApplication(application: Application) {
+	let packageJSON: any;
 	try {
-		await access(join(application.dirPath, 'package.json'), constants.F_OK);
+		packageJSON = JSON.parse(await readFile(join(application.dirPath, 'package.json'), 'utf8'));
 	} catch (err) {
 		if (err.code !== 'ENOENT') throw err;
 		// If no package.json, nothing to install
@@ -225,8 +269,6 @@ export async function installApplication(application: Application) {
 	}
 
 	// Next, try package.json devEngines field
-	const packageJSON = JSON.parse(await readFile(join(application.dirPath, 'package.json'), 'utf8'));
-
 	const { packageManager } = packageJSON.devEngines || {};
 
 	// Custom package manager specified
@@ -344,7 +386,7 @@ export class Application {
  * during the installation process in order to actually resolve what the user specifies for a
  * component matching some of npm's package resolution rules.
  */
-function derivePackageIdentifier(packageIdentifier: string) {
+export function derivePackageIdentifier(packageIdentifier: string) {
 	if (packageIdentifier.includes(':')) {
 		return packageIdentifier;
 	}
@@ -384,6 +426,18 @@ export async function installApplications() {
 	// Ensure component directory exists
 	await mkdir(componentsRootDirPath, { recursive: true });
 
+	const harperApplicationLockPath = join(getConfigValue(CONFIG_PARAMS.ROOTPATH), 'harper-application-lock.json');
+
+	let harperApplicationLock: any = { application: {} };
+	try {
+		harperApplicationLock = JSON.parse(await readFile(harperApplicationLockPath, 'utf8'));
+	} catch (error) {
+		// Ignore file not found error; will create new lock file after installations
+		if (error.code !== 'ENOENT') {
+			throw error;
+		}
+	}
+
 	const applicationInstallationPromises: Promise<void>[] = [];
 
 	for (const [name, applicationConfig] of Object.entries(config)) {
@@ -403,12 +457,27 @@ export async function installApplications() {
 			install: applicationConfig.install,
 		});
 
+		// Lock check: only install if not already installed with matching configuration
+		if (
+			existsSync(application.dirPath) &&
+			harperApplicationLock.applications[name] &&
+			JSON.stringify(harperApplicationLock.applications[name]) === JSON.stringify(applicationConfig)
+		) {
+			logger.info(`Application ${name} is already installed with matching configuration; skipping installation`);
+			continue;
+		}
+
 		applicationInstallationPromises.push(prepareApplication(application));
+
+		harperApplicationLock.applications[name] = applicationConfig;
 	}
 
 	const applicationInstallationStatuses = await Promise.allSettled(applicationInstallationPromises);
 	logger.debug(applicationInstallationStatuses);
 	logger.info('All root applications loaded');
+
+	// Finally, write the lock file
+	await writeFile(harperApplicationLockPath, JSON.stringify(harperApplicationLock, null, 2), 'utf8');
 }
 
 function getGitSSHCommand() {
@@ -455,7 +524,6 @@ export function nonInteractiveSpawn(
 			env.GIT_SSH_COMMAND = gitSSHCommand;
 		}
 
-		// eslint-disable-next-line sonarjs/os-command
 		const childProcess = spawn(command, args, {
 			shell: true,
 			cwd,