@harperfast/harper 5.2.0-beta.4 → 5.2.1

package/bin/help.ts

@@ -0,0 +1,216 @@
+/**
+ * The `harper help` / `harper -h` output, kept as structured data so {@link help} can render it to
+ * the current terminal width (capped at 120 columns) at call time. Content lives separately from
+ * layout: editing the text can't break the wrapping, command names stay column-aligned across
+ * sections, and the CI/CD sample stays a verbatim, copy-pasteable line at any width.
+ */
+
+const MAX_WIDTH = 120;
+const INDENT = 2; // leading spaces for command names and detail blocks
+const DASH = ' - '; // separator between a command name and its description
+// Minimum description width for the two-column command layout. On terminals too narrow for it
+// (width < descCol + this), command rows stack the name above an indented description instead of
+// overflowing. Set to the widest word in any command description so two-column never overflows.
+const MIN_DESC_WIDTH = 20;
+
+/** A paragraph of prose, reflowed to the target width at `indent` spaces. */
+interface TextBlock {
+	text: string;
+	indent?: number;
+}
+
+/** A verbatim line (a code sample); never joined or wrapped so it stays copy-pasteable. */
+interface PreBlock {
+	pre: string;
+	indent?: number;
+}
+
+/** A two-column list of `[name, description]` rows; descriptions wrap with a hanging indent. */
+interface CommandsBlock {
+	commands: [name: string, description: string][];
+}
+
+type Block = TextBlock | PreBlock | CommandsBlock;
+
+interface Section {
+	heading?: string;
+	blocks: Block[];
+}
+
+const SECTIONS: Section[] = [
+	{ blocks: [{ text: 'Usage: harperdb [command]' }] },
+	{ blocks: [{ text: 'With no command, harper will simply run Harper (in the foreground)' }] },
+	{ blocks: [{ text: 'Documentation: https://docs.harperdb.io/' }] },
+	{
+		blocks: [
+			{
+				text: [
+					'By default, the CLI also supports certain Operation APIs. Specify the operation name and any required',
+					"parameters, and omit the 'operation' command.",
+				].join(' '),
+			},
+		],
+	},
+	{ blocks: [{ text: 'Commands:' }] },
+	{
+		heading: 'Server',
+		blocks: [
+			{
+				commands: [
+					['start', 'Starts a separate background process for harperdb and CLI will exit'],
+					['stop', 'Stop the harperdb background process'],
+					['restart', 'Restart the harperdb background process'],
+					['status', 'Print the status of Harper'],
+				],
+			},
+		],
+	},
+	{
+		heading: 'Applications',
+		blocks: [
+			{
+				commands: [
+					['run <path>', 'Run the application in the specified path'],
+					['dev <path>', 'Run the application in dev mode with debugging, foreground logging, no auth'],
+					['deploy', 'Deploy the application locally or remotely with target=<remote url>'],
+				],
+			},
+		],
+	},
+	{
+		heading: 'Install & maintenance',
+		blocks: [
+			{
+				commands: [
+					['install', 'Install harperdb'],
+					['upgrade', 'Upgrade harperdb'],
+					['register', 'Register harperdb'],
+					['renew-certs', 'Generate a new set of self-signed certificates'],
+					['copy-db <source> <target>', 'Copies a database from source path to target path'],
+					['version', 'Print the version'],
+					['help', 'Display this output'],
+				],
+			},
+		],
+	},
+	{
+		heading: 'Accounts',
+		blocks: [
+			{ pre: 'login [target] [username]', indent: INDENT },
+			{
+				text: [
+					'Login to a remote or local Harper instance. --for-ci prints the CI/CD credentials (target +',
+					'long-lived refresh token) to stdout in dotenv format, and everything else to stderr, so it pipes',
+					'without the token hitting your screen:',
+				].join(' '),
+				indent: 4,
+			},
+			{ pre: 'harper login --for-ci | gh secret set --env-file -', indent: 6 },
+			{
+				text: [
+					'Log in as a user dedicated to that one CI consumer: Harper stores a single refresh token per user, so',
+					'this revokes any refresh token that user already holds — another runner, another machine, or an earlier',
+					"'harper login' will 401 on its next refresh. Two consumers cannot share a user.",
+				].join(' '),
+				indent: 4,
+			},
+			{ commands: [['logout [target]', 'Logout from Harper and clear saved JWT']] },
+		],
+	},
+	{
+		heading: 'Assistants',
+		blocks: [
+			{
+				commands: [
+					['agent [message]', 'Chat with the built-in agent (interactive, or one-shot with a message; alias: chat)'],
+					['mcp [subcommand]', "MCP stdio bridge / print-config / doctor (see 'harper mcp help')"],
+				],
+			},
+		],
+	},
+	{
+		heading: 'Operations API',
+		blocks: [
+			{ pre: '<api-operation> <param>=<value>', indent: INDENT },
+			{
+				text: [
+					'Run an API operation and return the result to the CLI (not all operations are supported). See the full',
+					'list of operations at: https://docs.harperdb.io/reference/v5/operations-api/operations',
+				].join(' '),
+				indent: 4,
+			},
+			{
+				text: [
+					'To authenticate as a different user than the one being operated on (e.g. add_user/alter_user), set',
+					"HARPER_CLI_USERNAME/HARPER_CLI_PASSWORD or run 'harper login'. The equivalent auth_username=<value>",
+					'auth_password=<value> args also work, but a password passed as an argument is exposed in shell',
+					'history, process listings and CI logs. A saved login token always outranks username=/password=, so a',
+					"stale token that fails to refresh will 401 rather than falling back to them — run 'harper logout' or",
+					'pass auth_username=/auth_password= to override it.',
+				].join(' '),
+				indent: 4,
+			},
+		],
+	},
+];
+
+const pad = (count: number): string => ' '.repeat(count);
+
+/** Greedy word wrap. Never splits a token, so URLs and flags survive intact (they overflow). */
+function wrap(text: string, width: number): string[] {
+	const words = text.split(/\s+/).filter(Boolean);
+	if (words.length === 0) return [];
+	const lines: string[] = [];
+	let line = words[0];
+	for (let i = 1; i < words.length; i++) {
+		if (line.length + 1 + words[i].length > width) {
+			lines.push(line);
+			line = words[i];
+		} else {
+			line += ' ' + words[i];
+		}
+	}
+	lines.push(line);
+	return lines;
+}
+
+function renderBlock(block: Block, width: number, nameWidth: number, descCol: number): string[] {
+	if ('commands' in block) {
+		// Two columns when the terminal leaves a readable description column; otherwise stack the name
+		// above an indented description so narrow terminals don't overflow the command rows.
+		const twoColumn = width - descCol >= MIN_DESC_WIDTH;
+		return block.commands.flatMap(([name, description]) => {
+			if (twoColumn) {
+				const wrapped = wrap(description, width - descCol);
+				const head = pad(INDENT) + name.padEnd(nameWidth) + DASH;
+				return [head + (wrapped[0] ?? ''), ...wrapped.slice(1).map((line) => pad(descCol) + line)];
+			}
+			const detail = INDENT * 2;
+			return [pad(INDENT) + name, ...wrap(description, Math.max(1, width - detail)).map((line) => pad(detail) + line)];
+		});
+	}
+	if ('pre' in block) return [pad(block.indent ?? 0) + block.pre];
+	const indent = block.indent ?? 0;
+	return wrap(block.text, Math.max(1, width - indent)).map((line) => pad(indent) + line);
+}
+
+/** Render the CLI help, wrapped to the terminal width (capped at 120, and 120 when not a TTY). */
+export function help(): string {
+	const width = Math.min(process.stdout.columns || MAX_WIDTH, MAX_WIDTH);
+
+	// One shared description column across every command list so names line up between sections,
+	// driven by the longest command name.
+	const names = SECTIONS.flatMap((section) =>
+		section.blocks.flatMap((block) => ('commands' in block ? block.commands.map(([name]) => name) : []))
+	);
+	const nameWidth = Math.max(...names.map((name) => name.length));
+	const descCol = INDENT + nameWidth + DASH.length;
+
+	const lines: string[] = [];
+	for (const section of SECTIONS) {
+		if (lines.length) lines.push(''); // blank line between sections
+		if (section.heading) lines.push(section.heading);
+		for (const block of section.blocks) lines.push(...renderBlock(block, width, nameWidth, descCol));
+	}
+	return '\n' + lines.join('\n') + '\n';
+}

package/components/Application.ts

@@ -483,10 +483,106 @@ const COMPONENT_PREPARATION_WAIT_MARGIN_MS = 30000;
 const MAX_GIT_EXTRACTION_COMMANDS = 4;
 const MAX_INSTALL_COMMANDS = 2;
 
+type ExtractionTransaction = {
+	commit(): Promise<void>;
+	rollback(): Promise<void>;
+};
+
 // The credential helper git executes for a private git-reference deploy. It ships alongside this
 // module (both in source and in dist), holds no secret, and is inert without a live session.
 export const GIT_CREDENTIAL_HELPER_PATH = join(__dirname, 'gitCredentialHelper.js');
 
+const PACKAGE_LOCK_FILES = [
+	'package-lock.json',
+	'npm-shrinkwrap.json',
+	'pnpm-lock.yaml',
+	'yarn.lock',
+	'bun.lock',
+	'bun.lockb',
+];
+
+type InstalledPackageMetadata = {
+	files: Map<string, Buffer>;
+	readable: boolean;
+	hasLockfile: boolean;
+	hasInstallableDependencies: boolean;
+};
+
+export async function readInstalledPackageMetadata(directory: string): Promise<InstalledPackageMetadata> {
+	const files = new Map<string, Buffer>();
+	let readable = true;
+	let packageJSON: any;
+	await Promise.all([
+		(async () => {
+			try {
+				const contents = await readFile(join(directory, 'package.json'));
+				try {
+					packageJSON = JSON.parse(contents.toString());
+					files.set('package.json', Buffer.from(JSON.stringify(canonicalizeJSON(packageJSON))));
+				} catch {
+					files.set('package.json', contents);
+				}
+			} catch (error) {
+				if ((error as NodeJS.ErrnoException).code !== 'ENOENT') readable = false;
+			}
+		})(),
+		...PACKAGE_LOCK_FILES.map(async (filename) => {
+			try {
+				files.set(filename, await readFile(join(directory, filename)));
+			} catch (error) {
+				if ((error as NodeJS.ErrnoException).code !== 'ENOENT') readable = false;
+			}
+		}),
+	]);
+	return {
+		files,
+		readable,
+		hasLockfile: PACKAGE_LOCK_FILES.some((filename) => files.has(filename)),
+		hasInstallableDependencies: ['dependencies', 'devDependencies', 'optionalDependencies', 'peerDependencies'].some(
+			(field) => {
+				const dependencies = packageJSON?.[field];
+				return (
+					typeof dependencies === 'object' &&
+					dependencies !== null &&
+					!Array.isArray(dependencies) &&
+					Object.keys(dependencies).length > 0
+				);
+			}
+		),
+	};
+}
+
+export function installedPackageMetadataEqual(
+	previous: InstalledPackageMetadata,
+	current: InstalledPackageMetadata
+): boolean {
+	if (!previous.readable || !current.readable || previous.files.size !== current.files.size) return false;
+	for (const [filename, contents] of previous.files) {
+		if (!current.files.get(filename)?.equals(contents)) return false;
+	}
+	return true;
+}
+
+export function installedRuntimeChanged(
+	previous: InstalledPackageMetadata,
+	current: InstalledPackageMetadata,
+	installationIsOpaque: boolean
+): boolean {
+	return (
+		installationIsOpaque ||
+		(current.hasInstallableDependencies && !current.hasLockfile) ||
+		!installedPackageMetadataEqual(previous, current)
+	);
+}
+
+function canonicalizeJSON(value: any): any {
+	if (Array.isArray(value)) return value.map(canonicalizeJSON);
+	if (!value || typeof value !== 'object') return value;
+	const canonical: Record<string, any> = Object.create(null);
+	for (const key of Object.keys(value).sort()) canonical[key] = canonicalizeJSON(value[key]);
+	return canonical;
+}
+
 /**
  * Extract an application given payload (content of the application) or package (npm-compatible identifier to the application).
  *
@@ -497,7 +593,10 @@ export const GIT_CREDENTIAL_HELPER_PATH = join(__dirname, 'gitCredentialHelper.j
  * This method may be called from any Harper thread. Same-component calls are serialized across
  * threads by the preparation lock below.
  */
-export async function extractApplication(application: Application) {
+export async function extractApplication(
+	application: Application,
+	deferCommit = false
+): Promise<ExtractionTransaction | undefined> {
 	// Can't specify neither
 	if (!application.payload && !application.packageIdentifier) {
 		throw new Error('Either payload or package must be provided');
@@ -507,7 +606,6 @@ export async function extractApplication(application: Application) {
 	if (application.payload && application.packageIdentifier) {
 		throw new Error('Both payload and package cannot be provided');
 	}
-
 	// Resolve the tarball from the input
 	let tarballPath: string;
 	let tarball: Readable;
@@ -576,6 +674,7 @@ export async function extractApplication(application: Application) {
 			// not have, so this gates the pack step regardless of whether a credential happens to be in
 			// play.
 			const allowScripts = !!application.install?.allowInstallScripts;
+			if (allowScripts) application.installationIsOpaque = true;
 			// `--ignore-scripts` alone isn't a reliable way to enforce that: pacote's DirFetcher runs a
 			// git source's `prepare` unconditionally on npm versions before 11.0.0 (see
 			// packGitReferenceWithoutScripts), which is exactly what Node 22's bundled npm ships. For a
@@ -630,12 +729,13 @@ export async function extractApplication(application: Application) {
 	// component, and the per-component path means a sibling component never collides
 	// with (or sweeps) another's aside.
 	const asideStagingDir = join(dirname(application.dirPath), ASIDE_STAGING_DIR, basename(application.dirPath));
-	let didRenameAside = false;
+	let asidePath: string | undefined;
 	try {
 		await access(application.dirPath, constants.F_OK);
 		await mkdir(asideStagingDir, { recursive: true });
-		await rename(application.dirPath, join(asideStagingDir, `${process.pid}-${Date.now()}-${randomUUID()}`));
-		didRenameAside = true;
+		const candidateAsidePath = join(asideStagingDir, `${process.pid}-${Date.now()}-${randomUUID()}`);
+		await rename(application.dirPath, candidateAsidePath);
+		asidePath = candidateAsidePath;
 	} catch (err) {
 		// Ignore does not exist error
 		if (err.code !== 'ENOENT') {
@@ -644,35 +744,37 @@ export async function extractApplication(application: Application) {
 	}
 	// A directory existed for this component name prior to this deploy, so this is a redeploy of
 	// an already-active component rather than a first-time deploy. See `isNewComponent` above.
-	if (didRenameAside) application.isNewComponent = false;
-	// Finally, create the application directory fresh
-	await mkdir(application.dirPath, { recursive: true });
-
-	// Now pipeline the tarball into maybe-gunzip then tar-fs to reliably decompress and extract the contents
-	await pipeline(tarball, gunzip(), extract(application.dirPath));
-
-	// If the extracted directory contains a single folder, move the contents up one level
-	// The `npm pack` command does this (the top-level folder is called "package")
-	// Other packing tools may have similar behavior, but the directory name is not guaranteed.
-	const extracted = await readdir(application.dirPath, { withFileTypes: true });
-	if (extracted.length === 1 && extracted[0].isDirectory()) {
-		const topLevelDirPath = join(application.dirPath, extracted[0].name);
-
-		const tempDirPath = await mkdtemp(application.dirPath);
-
-		// Copy contents of top-level directory to temp directory (in order to avoid collisions of top-level directory name and one of the contents)
-		await cp(topLevelDirPath, tempDirPath, { recursive: true });
-		// Remove top-level directory
-		await rm(topLevelDirPath, { recursive: true, force: true });
-		// Copy contents of temp directory to application directory
-		await cp(tempDirPath, application.dirPath, { recursive: true });
-		// Finally, remove the temp dir
-		await rm(tempDirPath, { recursive: true, force: true });
+	if (asidePath) application.isNewComponent = false;
+	try {
+		await mkdir(application.dirPath, { recursive: true });
+		await pipeline(tarball, gunzip(), extract(application.dirPath));
+
+		const extracted = await readdir(application.dirPath, { withFileTypes: true });
+		if (extracted.length === 1 && extracted[0].isDirectory()) {
+			const topLevelDirPath = join(application.dirPath, extracted[0].name);
+			await mkdir(asideStagingDir, { recursive: true });
+			const tempDirPath = await mkdtemp(join(asideStagingDir, '.normalize-'));
+			await cp(topLevelDirPath, tempDirPath, { recursive: true });
+			await rm(topLevelDirPath, { recursive: true, force: true });
+			await cp(tempDirPath, application.dirPath, { recursive: true });
+			await rm(tempDirPath, { recursive: true, force: true });
+		}
+	} catch (error) {
+		try {
+			await rollbackExtractedDirectory(application, asideStagingDir, asidePath);
+		} catch (rollbackError) {
+			throw new AggregateError(
+				[error, rollbackError],
+				`Failed to extract ${application.name} and restore its previous component directory`
+			);
+		}
+		throw error;
 	}
-
 	// Clean up the original tarball
 	if (shouldDeleteTarball && tarballPath) {
-		await rm(tarballPath, { force: true });
+		await rm(tarballPath, { force: true }).catch((error) =>
+			application.logger.warn(`Failed to remove temporary package ${tarballPath}:`, error)
+		);
 	}
 
 	// Remove this component's aside copies. The old worker may still hold files open
@@ -681,11 +783,76 @@ export async function extractApplication(application: Application) {
 	// earlier deploys whose workers have since exited, and a copy that survives because
 	// its worker is still live is swept by the next deploy. The failure is expected in
 	// the live-worker case, so it's logged at trace rather than as a warning.
-	if (didRenameAside) {
-		rm(asideStagingDir, { recursive: true, force: true, maxRetries: 3, retryDelay: 100 }).catch((err) =>
-			logger.trace?.(`Deferred cleanup of previous ${application.name} component directory: ${err.message}`)
-		);
+	let settled = false;
+	const transaction: ExtractionTransaction = {
+		async commit() {
+			if (settled) return;
+			settled = true;
+			await cleanupExtractionStaging(application, asideStagingDir);
+		},
+		async rollback() {
+			if (settled) return;
+			settled = true;
+			await rollbackExtractedDirectory(application, asideStagingDir, asidePath);
+		},
+	};
+	if (deferCommit) return transaction;
+	await transaction.commit();
+}
+
+async function cleanupExtractionStaging(application: Application, asideStagingDir: string): Promise<void> {
+	try {
+		await rm(asideStagingDir, { recursive: true, force: true, maxRetries: 3, retryDelay: 100 });
+	} catch (error) {
+		logger.trace?.(`Cleanup of previous ${application.name} component directory deferred: ${error.message}`);
+	}
+}
+
+async function rollbackExtractedDirectory(
+	application: Application,
+	asideStagingDir: string,
+	asidePath: string | undefined
+): Promise<void> {
+	await mkdir(asideStagingDir, { recursive: true });
+	const retryableRenameCodes = new Set(['EEXIST', 'ENOTEMPTY', 'EPERM', 'EACCES', 'EBUSY']);
+	const displaceCurrentDirectory = async () => {
+		const displacedPath = join(asideStagingDir, `.failed-${process.pid}-${Date.now()}-${randomUUID()}`);
+		let lastError: unknown;
+		for (let attempt = 0; attempt < 100; attempt++) {
+			try {
+				await rename(application.dirPath, displacedPath);
+				return;
+			} catch (error) {
+				const code = (error as NodeJS.ErrnoException).code;
+				if (code === 'ENOENT') return;
+				if (!retryableRenameCodes.has(code ?? '')) throw error;
+				lastError = error;
+				await delay(10);
+			}
+		}
+		throw lastError;
+	};
+
+	await displaceCurrentDirectory();
+	if (asidePath) {
+		let restored = false;
+		let restoreError: unknown;
+		for (let attempt = 0; attempt < 100; attempt++) {
+			try {
+				await rename(asidePath, application.dirPath);
+				restored = true;
+				break;
+			} catch (error) {
+				restoreError = error;
+				if (!retryableRenameCodes.has((error as NodeJS.ErrnoException).code ?? '')) break;
+				await displaceCurrentDirectory();
+				await delay(10);
+			}
+		}
+		if (!restored) throw restoreError;
 	}
+
+	await cleanupExtractionStaging(application, asideStagingDir);
 }
 
 /**
@@ -711,7 +878,10 @@ export async function installApplication(application: Application) {
 	try {
 		// Does node_modules exist?
 		await access(join(application.dirPath, 'node_modules'), constants.F_OK);
-		application.logger.info(`Application ${application.name} already has node_modules; skipping install`);
+		application.logger.info(
+			`Application ${application.name} already has node_modules; skipping install and treating the runtime as opaque for redeploy comparison`
+		);
+		application.installationIsOpaque = true;
 		return;
 	} catch (err) {
 		if (err.code !== 'ENOENT') throw err;
@@ -735,6 +905,7 @@ export async function installApplication(application: Application) {
 		);
 		// if it succeeds, return
 		if (code === 0) {
+			application.installationIsOpaque = true;
 			return;
 		}
 		if (stdout) {
@@ -797,6 +968,7 @@ export async function installApplication(application: Application) {
 
 		// if it succeeds, return
 		if (code === 0) {
+			if (application.install?.allowInstallScripts) application.installationIsOpaque = true;
 			return;
 		}
 
@@ -854,6 +1026,7 @@ export async function installApplication(application: Application) {
 
 	// if it succeeds, return
 	if (code === 0) {
+		if (application.install?.allowInstallScripts) application.installationIsOpaque = true;
 		return;
 	}
 
@@ -911,14 +1084,10 @@ export class Application {
 	npmUserconfigPath?: string;
 	#npmrcTempDir?: string;
 	#gitCredentialSession?: GitCredentialSession;
-	// Whether this component's directory did not already exist when extractApplication ran —
-	// i.e. this deploy is the component's first, as opposed to a redeploy of something already
-	// active. Defaults true and is flipped to false by extractApplication when it finds (and
-	// renames aside) a pre-existing directory for this component name. Used by deployComponent to
-	// scope its unconditional requestRestart() call to genuinely new components (harper#1806):
-	// an existing, already-loaded component already has a live file watcher (Scope/EntryHandler)
-	// that independently requests a restart if the redeploy actually needs one.
+	// Existing components rely on their runtime-equivalence checks; only a first deploy restarts unconditionally.
 	isNewComponent: boolean = true;
+	packageMetadataChanged: boolean = false;
+	installationIsOpaque: boolean = false;
 
 	constructor({ name, payload, packageIdentifier, install, onInstallLine, credentials }: ApplicationOptions) {
 		this.name = name;
@@ -1064,12 +1233,14 @@ export function derivePackageIdentifier(packageIdentifier: string) {
  * @returns A promise that resolves when all preparation steps complete.
  */
 export async function prepareApplication(application: Application) {
-	await broadcastDeployStart(application.name);
+	const deploymentId = await broadcastDeployStart(application.name);
 	try {
 		const commandTimeoutMs = application.install?.timeout ?? DEFAULT_COMMAND_TIMEOUT_MS;
 		await withComponentPreparationLock(
 			application.dirPath,
 			async () => {
+				const previousPackageMetadata = await readInstalledPackageMetadata(application.dirPath);
+				let extraction: ExtractionTransaction | undefined;
 				try {
 					// Materialize the per-deploy `.npmrc` before extraction so both `npm pack` (extract) and
 					// `npm install` authenticate against the private registry; always remove it afterward.
@@ -1080,11 +1251,30 @@ export async function prepareApplication(application: Application) {
 						// already gone by the time the component's dependency tree (and any install script it is
 						// allowed to run) executes.
 						await application.startGitCredentialSession();
-						await extractApplication(application);
+						extraction = await extractApplication(application, true);
 					} finally {
 						await application.cleanupGitCredentialSession();
 					}
 					await installApplication(application);
+					if (!application.isNewComponent) {
+						const currentPackageMetadata = await readInstalledPackageMetadata(application.dirPath);
+						application.packageMetadataChanged = installedRuntimeChanged(
+							previousPackageMetadata,
+							currentPackageMetadata,
+							application.installationIsOpaque
+						);
+					}
+					await extraction?.commit();
+				} catch (error) {
+					try {
+						await extraction?.rollback();
+					} catch (rollbackError) {
+						throw new AggregateError(
+							[error, rollbackError],
+							`Failed to prepare ${application.name} and restore its previous component directory`
+						);
+					}
+					throw error;
 				} finally {
 					await application.cleanupTransientNpmrc();
 				}
@@ -1111,7 +1301,7 @@ export async function prepareApplication(application: Application) {
 			}
 		);
 	} finally {
-		broadcastDeployEnd(application.name);
+		broadcastDeployEnd(application.name, deploymentId);
 	}
 }
 

package/components/ApplicationScope.ts

@@ -4,6 +4,8 @@ import { forComponent } from '../utility/logging/harper_logger.ts';
 import { scopedImport } from '../security/jsLoader.ts';
 import * as env from '../utility/environment/environmentManager.ts';
 import { CONFIG_PARAMS } from '../utility/hdbTerms.ts';
+import { RuntimeModuleTracker } from './RuntimeModuleTracker.ts';
+import { deployLifecycle } from './deployLifecycle.ts';
 
 export class MissingDefaultFilesOptionError extends Error {
 	constructor() {
@@ -24,14 +26,18 @@ export class ApplicationScope {
 	mode?: 'native' | 'vm' | 'vm-current-context' | 'compartment'; // option to set this from the scope
 	dependencyLoader?: 'native' | 'app' | 'auto'; // option to set this from the scope
 	allowedPath?: string;
+	runtimeRoot?: string;
 	config: any;
 	moduleCache: any; // used by the loader to retain a cache of modules, type is an internal detail of the loader
+	#runtimeModules: RuntimeModuleTracker;
 	constructor(name: string, resources: Resources, server: Server, isInternal = false) {
 		this.name = name;
 		this.logger = forComponent(name, !isInternal);
 
 		this.resources = resources;
 		this.server = server;
+		this.#runtimeModules = new RuntimeModuleTracker(() => this.runtimeRoot);
+		if (deployLifecycle.isDeployInFlight(name)) this.#runtimeModules.beginDeploy();
 
 		this.mode = env.get(CONFIG_PARAMS.APPLICATIONS_MODULELOADER) ?? 'vm-current-context';
 		this.dependencyLoader = env.get(CONFIG_PARAMS.APPLICATIONS_DEPENDENCYLOADER);
@@ -50,4 +56,24 @@ export class ApplicationScope {
 	async import(filePath: string): Promise<unknown> {
 		return scopedImport(filePath, this);
 	}
+
+	recordLoadedModule(moduleUrl: string, source: string | Buffer): void {
+		this.#runtimeModules.recordModule(moduleUrl, source);
+	}
+
+	recordModuleResolution(specifier: string, referrer: string, resolvedUrl: string): void {
+		this.#runtimeModules.recordResolution(specifier, referrer, resolvedUrl);
+	}
+
+	markNativeRuntime(): void {
+		this.#runtimeModules.markNativeRuntime();
+	}
+
+	beginDeploy(): void {
+		this.#runtimeModules.beginDeploy();
+	}
+
+	finishDeploy(): Promise<boolean> {
+		return this.#runtimeModules.finishDeploy();
+	}
 }