@harperfast/harper-pro 5.0.25 → 5.1.0-beta.1

package/core/benchmarks/ycsb/workload.test.mts

@@ -0,0 +1,174 @@
+/**
+ * Unit tests for the YCSB workload generator (distributions, op-mix selection,
+ * key model, latency stats). Run standalone with: node --test benchmarks/ycsb/
+ */
+import { test } from 'node:test';
+import { strictEqual, ok } from 'node:assert/strict';
+import {
+	WORKLOADS,
+	makeKeyChooser,
+	formatKey,
+	buildRecord,
+	KeyState,
+	LatencyRecorder,
+	ZipfianGenerator,
+	runOperations,
+	type OpExecutor,
+	type OperationType,
+} from './workload.mts';
+
+function countingExecutor(counts: Record<string, number>): OpExecutor {
+	const bump = (k: string) => {
+		counts[k] = (counts[k] ?? 0) + 1;
+	};
+	return {
+		async read() {
+			bump('read');
+		},
+		async insert() {
+			bump('insert');
+		},
+		async update() {
+			bump('update');
+		},
+		async readModifyWrite() {
+			bump('rmw');
+		},
+		async scan() {
+			bump('scan');
+		},
+	};
+}
+
+test('formatKey zero-pads to a fixed width', () => {
+	strictEqual(formatKey(42, 8), 'user00000042');
+	strictEqual(formatKey(0, 4), 'user0000');
+});
+
+test('buildRecord produces the requested field count and length', () => {
+	const record = buildRecord({ fieldCount: 5, fieldLength: 20 });
+	strictEqual(Object.keys(record).length, 5);
+	ok('field0' in record && 'field4' in record);
+	strictEqual(record.field0.length, 20);
+});
+
+test('uniform chooser stays within the keyspace', () => {
+	const chooser = makeKeyChooser('uniform');
+	for (let i = 0; i < 10000; i++) {
+		const v = chooser.next(1000);
+		ok(v >= 0 && v < 1000, `out of range: ${v}`);
+	}
+});
+
+test('raw ZipfianGenerator concentrates mass on low indices', () => {
+	// Validates the zeta math directly (no FNV scramble): under Zipf(0.99) the
+	// lowest 10% of the value range should absorb a clear majority of draws.
+	const n = 1000;
+	const gen = new ZipfianGenerator(0, n - 1);
+	const samples = 50000;
+	let inLowDecile = 0;
+	for (let i = 0; i < samples; i++) {
+		const v = gen.nextLong(n);
+		ok(v >= 0 && v < n, `out of range: ${v}`);
+		if (v < n * 0.1) inLowDecile++;
+	}
+	ok(inLowDecile / samples > 0.55, `expected skew, low decile got ${(inLowDecile / samples).toFixed(2)}`);
+});
+
+test('scrambled zipfian chooser is skewed across a realistic keyspace', () => {
+	// The scrambled generator draws from a 10^10 universe and hashes into the
+	// keyspace, so its skew is only pronounced at realistic sizes (here 100k).
+	const chooser = makeKeyChooser('zipfian');
+	const keyCount = 100_000;
+	const hits = new Map<number, number>();
+	const samples = 300_000;
+	for (let i = 0; i < samples; i++) {
+		const v = chooser.next(keyCount);
+		ok(v >= 0 && v < keyCount, `out of range: ${v}`);
+		hits.set(v, (hits.get(v) ?? 0) + 1);
+	}
+	const sorted = [...hits.values()].sort((a, b) => b - a);
+	const top10pct = sorted.slice(0, keyCount * 0.1).reduce((a, b) => a + b, 0);
+	ok(top10pct / samples > 0.35, `expected skew, top 10% got ${(top10pct / samples).toFixed(2)}`);
+});
+
+test('latest chooser is biased toward the newest keys', () => {
+	const chooser = makeKeyChooser('latest');
+	const keyCount = 100_000;
+	let inTopDecile = 0;
+	const samples = 300_000;
+	for (let i = 0; i < samples; i++) {
+		const v = chooser.next(keyCount);
+		ok(v >= 0 && v < keyCount, `out of range: ${v}`);
+		if (v >= keyCount * 0.9) inTopDecile++;
+	}
+	ok(inTopDecile / samples > 0.3, `expected recency bias, got ${(inTopDecile / samples).toFixed(2)}`);
+});
+
+test('KeyState allocates inserts sequentially and gates reads on acknowledgement', () => {
+	const keys = new KeyState({
+		distribution: 'uniform',
+		initialKeyCount: 100,
+		keyWidth: 8,
+		shape: { fieldCount: 1, fieldLength: 4 },
+		maxScanLength: 10,
+	});
+	const a = keys.nextInsert();
+	const b = keys.nextInsert();
+	strictEqual(a.key, formatKey(100, 8));
+	strictEqual(b.key, formatKey(101, 8));
+	// Out-of-order ack: 101 done first must NOT make index 101 readable past the gap at 100.
+	keys.acknowledgeInsert(b.index);
+	for (let i = 0; i < 1000; i++) ok(keys.existingKey() < formatKey(101, 8), 'must not expose unacked key');
+	keys.acknowledgeInsert(a.index);
+	// Now both 100 and 101 are contiguously acknowledged and readable.
+	let sawNew = false;
+	for (let i = 0; i < 5000; i++) if (keys.existingKey() === formatKey(101, 8)) sawNew = true;
+	ok(sawNew, 'acknowledged key should become readable');
+});
+
+test('LatencyRecorder computes ordered percentiles', () => {
+	const recorder = new LatencyRecorder();
+	for (let i = 1; i <= 1000; i++) recorder.record('read', i);
+	const stats = recorder.statsByType().read!;
+	strictEqual(stats.count, 1000);
+	strictEqual(stats.min, 1);
+	strictEqual(stats.max, 1000);
+	ok(Math.abs(stats.p50 - 500) <= 1, `p50 ~500, got ${stats.p50}`);
+	ok(stats.p99 >= 990, `p99 >=990, got ${stats.p99}`);
+});
+
+test('runOperations honors the workload mix within tolerance', async () => {
+	const counts: Record<string, number> = {};
+	const keys = new KeyState({
+		distribution: 'uniform',
+		initialKeyCount: 1000,
+		keyWidth: 8,
+		shape: { fieldCount: 2, fieldLength: 8 },
+		maxScanLength: 10,
+	});
+	const opCount = 20000;
+	const result = await runOperations({
+		opCount,
+		concurrency: 16,
+		mix: WORKLOADS.A.mix,
+		executor: countingExecutor(counts),
+		keys,
+	});
+	strictEqual(result.ops, opCount);
+	strictEqual(result.errors, 0);
+	const readFrac = (counts.read ?? 0) / opCount;
+	const updateFrac = (counts.update ?? 0) / opCount;
+	ok(Math.abs(readFrac - 0.5) < 0.05, `read frac ${readFrac}`);
+	ok(Math.abs(updateFrac - 0.5) < 0.05, `update frac ${updateFrac}`);
+});
+
+test('every declared workload has a normalized op mix', () => {
+	for (const spec of Object.values(WORKLOADS)) {
+		const total = Object.values(spec.mix).reduce((a, b) => a + (b ?? 0), 0);
+		ok(Math.abs(total - 1) < 1e-9, `${spec.name} mix sums to ${total}`);
+		for (const type of Object.keys(spec.mix) as OperationType[]) {
+			ok(['read', 'update', 'insert', 'scan', 'rmw'].includes(type), `bad op ${type}`);
+		}
+	}
+});

package/core/bin/{BinObjects.js → BinObjects.ts}

@@ -4,14 +4,13 @@
  * This is meant as a central place to defined POJOs used by functions in the /bin/ directory.
  */
 
-class HdbInfoInsertObject {
+export class HdbInfoInsertObject {
+	info_id: any;
+	data_version_num: any;
+	hdb_version_num: any;
 	constructor(id, dataVersionNum, hdbVersionNum) {
 		this.info_id = id;
 		this.data_version_num = dataVersionNum;
 		this.hdb_version_num = hdbVersionNum;
 	}
 }
-
-module.exports = {
-	HdbInfoInsertObject,
-};

package/core/bin/cliCredentials.ts

@@ -0,0 +1,133 @@
+import { getHomeDir } from '../utility/common_utils.ts';
+import fs from 'node:fs';
+import path from 'node:path';
+
+const ownerRWDenyAllOthers = 0o600;
+
+interface TargetedCredentials {
+	last_target: string | null;
+	targets: {
+		[target: string]: Tokens;
+	};
+}
+
+interface Tokens {
+	operation_token: string;
+	refresh_token: string;
+}
+
+/**
+ * Normalizes a target operations API URL to a canonical form (with trailing slash).
+ */
+export function normalizeTarget(target: string): string {
+	if (!target) return target;
+	let normalized = target;
+	if (!normalized.startsWith('http://') && !normalized.startsWith('https://')) {
+		normalized = 'https://' + normalized;
+	}
+	try {
+		const url = new URL(normalized);
+		if (!url.port && !normalized.includes(':', normalized.indexOf('://') + 3)) {
+			url.port = '9925';
+		}
+		normalized = url.toString();
+	} catch {
+		// If it's not a valid URL yet, we'll let it be handled later or it will fail
+	}
+	if (!normalized.endsWith('/')) {
+		normalized += '/';
+	}
+	return normalized;
+}
+
+/**
+ * Loads the JWT credentials from the ~/.harperdb/credentials.json file.
+ */
+export function loadCredentials(): TargetedCredentials {
+	const credentialsFile = getCredentialsFile();
+	try {
+		return JSON.parse(fs.readFileSync(credentialsFile, 'utf8'));
+	} catch (err) {
+		if (err.code !== 'ENOENT') {
+			throw new Error(`Error reading credentials file: ${err.message}`);
+		}
+	}
+	return {
+		last_target: null,
+		targets: {},
+	};
+}
+
+/**
+ * Saves the JWT credentials to the ~/.harperdb/credentials.json file.
+ */
+export function saveCredentials(target: string, tokens: Tokens): void {
+	if (!target) {
+		throw new Error('Target is required to save credentials.');
+	}
+
+	target = normalizeTarget(target);
+	const allCredentials = loadCredentials();
+
+	allCredentials.targets ||= {};
+	allCredentials.targets[target] = tokens;
+	allCredentials.last_target = target;
+
+	try {
+		fs.mkdirSync(getCredentialsDir(), { recursive: true });
+		fs.writeFileSync(getCredentialsFile(), JSON.stringify(allCredentials, null, 2), { mode: ownerRWDenyAllOthers });
+	} catch (err) {
+		throw new Error(`Error saving credentials file: ${err.message}`);
+	}
+}
+
+/**
+ * Deletes the credentials for a specific target or all if no target provided.
+ */
+export function clearCredentials(target: string): void {
+	const credentialsFile = getCredentialsFile();
+	if (target) {
+		target = normalizeTarget(target);
+		const allCredentials = loadCredentials();
+		if (allCredentials && allCredentials.targets) {
+			if (allCredentials.targets[target]) {
+				delete allCredentials.targets[target];
+			} else {
+				console.error(`No credentials found for ${target}`);
+				process.exit(1);
+			}
+
+			if (allCredentials.last_target === target) {
+				allCredentials.last_target = null;
+			}
+			try {
+				fs.writeFileSync(credentialsFile, JSON.stringify(allCredentials, null, 2), {
+					mode: ownerRWDenyAllOthers,
+				});
+				console.log(`Logged out from ${target}`);
+			} catch (err) {
+				throw new Error(`Error clearing credentials file: ${err.message}`);
+			}
+		} else {
+			console.error(`No credentials found for ${target}`);
+			process.exit(1);
+		}
+	} else if (fs.existsSync(credentialsFile)) {
+		try {
+			fs.unlinkSync(credentialsFile);
+			console.log('Logged out from all targets');
+		} catch (err) {
+			throw new Error(`Error clearing credentials file: ${err.message}`);
+		}
+	} else {
+		console.log('No credentials found to clear.');
+	}
+}
+
+function getCredentialsFile(): string {
+	return path.join(getHomeDir(), '.harperdb', 'credentials.json');
+}
+
+function getCredentialsDir(): string {
+	return path.join(getHomeDir(), '.harperdb');
+}

package/core/bin/cliOperations.ts

@@ -0,0 +1,339 @@
+'use strict';
+
+import { loadCredentials, saveCredentials, normalizeTarget } from './cliCredentials.ts';
+import { isJWTExpired } from '../security/tokenAuthentication.ts';
+import * as envMgr from '../utility/environment/environmentManager.ts';
+envMgr.initSync();
+import * as terms from '../utility/hdbTerms.ts';
+import { httpRequest } from '../utility/common_utils.ts';
+import * as path from 'path';
+import * as fs from 'fs-extra';
+import * as YAML from 'yaml';
+import { streamPackagedDirectory, getPackagedDirectorySize } from '../components/packageComponent.ts';
+import { buildMultipartBody } from './multipartBuilder.ts';
+import { parseSSE } from './sseConsumer.ts';
+import { DeployRenderer } from './deployRenderer.ts';
+import { getHdbPid } from '../utility/processManagement/processManagement.js';
+import { initConfig, getConfigPath } from '../config/configUtils.js';
+
+const OP_ALIASES = { deploy: 'deploy_component', package: 'package_component' };
+
+// Operations whose responses should be consumed as text/event-stream so live phase events
+// (prepare, load, replicate, restart) render as they happen instead of after the whole
+// deploy completes. Add an operation here only after wiring its server-side
+// SSE_PROGRESS_OPERATIONS entry — otherwise the server returns the buffered JSON path and
+// the SSE parser sees no events.
+const SSE_OPERATIONS = new Set(['deploy_component']);
+
+// Properties on `req` that the CLI itself uses for transport/UX, not the operations API.
+// They never get serialized into the request body.
+const TRANSPORT_ONLY_FIELDS = new Set([
+	'target',
+	'username',
+	'password',
+	'rejectUnauthorized',
+	'json',
+	'skip_node_modules',
+	'skip_symlinks',
+]);
+
+export { cliOperations, buildRequest };
+const PREPARE_OPERATION: any = {
+	deploy_component: async (req) => {
+		if (req.package) {
+			return;
+		}
+
+		const projectPath = process.cwd();
+		if (!req.project) req.project = path.basename(projectPath);
+		const packageOptions = {
+			skip_node_modules: req.skip_node_modules !== false,
+			skip_symlinks: req.skip_symlinks === true,
+		};
+		// Store path + options for deferred stream creation after the renderer is set up,
+		// so the pre-gzip onBytes callback can be wired directly to renderer.countUploadBytes.
+		req._projectPath = projectPath;
+		req._packageOptions = packageOptions;
+		// Pre-walk the directory for an uncompressed-size estimate. Both the progress counter
+		// and this total are in uncompressed units so the bar tracks to 100% naturally.
+		req._uploadSizeEstimate = await getPackagedDirectorySize(projectPath, packageOptions);
+		req._multipart = true;
+	},
+};
+
+/**
+ * Builds an Op-API request object from CLI args
+ */
+function buildRequest(): any {
+	const req: any = {};
+	for (const arg of process.argv.slice(2)) {
+		if (OP_ALIASES.hasOwnProperty(arg)) {
+			req.operation = OP_ALIASES[arg];
+		} else if (arg.includes('=')) {
+			let [first, ...rest] = arg.split('=');
+			let restStr: any = rest.join('=');
+
+			try {
+				restStr = JSON.parse(restStr);
+			} catch {
+				/* noop */
+			}
+
+			req[first] = restStr;
+		} else {
+			// operation should only be in the first arg
+			req.operation ??= arg;
+		}
+	}
+
+	return req;
+}
+
+/**
+ * Resolves the target URL from various sources.
+ * @param {Object} req The request object.
+ * @param {Object} allCredentials Stored credentials.
+ * @returns {string|null} The resolved target URL.
+ */
+function resolveTarget(req, allCredentials) {
+	return (
+		req.target ||
+		process.env.HARPER_CLI_TARGET ||
+		process.env.CLI_TARGET ||
+		(allCredentials && allCredentials.last_target)
+	);
+}
+
+/**
+ * Using a unix domain socket will send a request to hdb operations API server
+ * @param req
+ * @param skipResponseLog By default, the response is logged to the console. Set this to true to skip logging it, which can be useful for sensitive responses like login calls!
+ * @returns {Promise<void>}
+ */
+async function cliOperations(req: any, skipResponseLog = false) {
+	require('dotenv').config();
+
+	const allCredentials = loadCredentials();
+	req.target = normalizeTarget(resolveTarget(req, allCredentials));
+	let target;
+	if (req.target) {
+		try {
+			target = new URL(req.target);
+		} catch (error) {
+			try {
+				target = new URL(`https://${req.target}:9925`);
+			} catch {
+				throw error;
+			}
+		}
+		const resolvedTarget = req.target;
+		target = {
+			protocol: target.protocol,
+			hostname: target.hostname,
+			port: target.port,
+			username: req.username || target.username || process.env.HARPER_CLI_USERNAME || process.env.CLI_TARGET_USERNAME,
+			password: req.password || target.password || process.env.HARPER_CLI_PASSWORD || process.env.CLI_TARGET_PASSWORD,
+			rejectUnauthorized: req.rejectUnauthorized,
+			resolvedTarget,
+		};
+		console.error(`Connecting to ${resolvedTarget}`);
+	} else {
+		// if we aren't doing a targeted operation (like deploy), we initialize the config and verify that local harper
+		// is running and that we can communicate with it.
+		console.error('Connecting to local Harper instance');
+		initConfig();
+		if (!getHdbPid()) {
+			console.error('Harper must be running to perform this operation');
+			process.exit(1);
+		}
+
+		if (!fs.existsSync(getConfigPath(terms.CONFIG_PARAMS.OPERATIONSAPI_NETWORK_DOMAINSOCKET))) {
+			console.error('No domain socket found, unable to perform this operation');
+			process.exit(1);
+		}
+	}
+	await PREPARE_OPERATION[req.operation]?.(req);
+	try {
+		let options = target ?? {
+			protocol: 'http:',
+			socketPath: getConfigPath(terms.CONFIG_PARAMS.OPERATIONSAPI_NETWORK_DOMAINSOCKET),
+		};
+		options.method = 'POST';
+		options.headers = { 'Content-Type': 'application/json' };
+		if (target?.username) {
+			options.headers.Authorization = `Basic ${Buffer.from(`${target.username}:${target.password}`).toString('base64')}`;
+		} else if (allCredentials) {
+			let tokens = null;
+			let lookupKey = null;
+			if (target && allCredentials.targets) {
+				lookupKey = target.resolvedTarget;
+				tokens = allCredentials.targets[lookupKey] ?? null;
+			}
+
+			if (tokens?.operation_token) {
+				if (tokens.refresh_token && isJWTExpired(tokens.operation_token)) {
+					console.error('Operation token expired, attempting to refresh...');
+					try {
+						const refreshOptions = { ...options };
+						refreshOptions.headers = { ...options.headers, Authorization: `Bearer ${tokens.refresh_token}` };
+						const refreshResponse = await httpRequest(refreshOptions, {
+							operation: 'refresh_operation_token',
+						});
+						if (refreshResponse.statusCode === 200) {
+							const refreshData = JSON.parse(refreshResponse.body);
+							if (refreshData.operation_token) {
+								tokens.operation_token = refreshData.operation_token;
+								saveCredentials(lookupKey || target?.resolvedTarget, {
+									operation_token: tokens.operation_token,
+									refresh_token: tokens.refresh_token,
+								});
+								console.error('Operation token refreshed successfully.');
+								// Update the original request's authorization header with the new token
+								options.headers.Authorization = `Bearer ${tokens.operation_token}`;
+							}
+						} else if (refreshResponse.statusCode === 401) {
+							console.error('Refresh token expired or invalid. Please run harper login again.');
+							process.exit(1);
+						} else {
+							console.error(`Failed to refresh operation token: ${refreshResponse.statusCode}`);
+						}
+					} catch (refreshErr) {
+						console.error(`Error refreshing operation token: ${refreshErr.message}`);
+					}
+				}
+				options.headers.Authorization = `Bearer ${tokens.operation_token}`;
+			}
+		}
+		const useSse = SSE_OPERATIONS.has(req.operation);
+		if (useSse) {
+			options.headers.Accept = 'text/event-stream';
+			options.streamResponse = true;
+		}
+		// One renderer owns the (future) upload bar and the SSE event rendering for a
+		// multipart deploy. Created here so the upload-stream tap and the SSE consumer
+		// below share the same instance.
+		const renderer = req._multipart ? new DeployRenderer({ uploadTotal: req._uploadSizeEstimate ?? 0 }) : null;
+		let body;
+		if (req._multipart) {
+			// Create the package stream here — after the renderer exists — so we can pass
+			// renderer.countUploadBytes as the onBytes callback. Both progress and total are
+			// uncompressed bytes, so the bar tracks accurately to 100% without premature snapping.
+			const packageStream = streamPackagedDirectory(
+				req._projectPath,
+				req._packageOptions,
+				renderer ? (n) => renderer.countUploadBytes(n) : undefined
+			);
+			const fields = {};
+			for (const [key, value] of Object.entries(req)) {
+				if (key.startsWith('_') || TRANSPORT_ONLY_FIELDS.has(key)) continue;
+				fields[key] = value;
+			}
+			const multipart = buildMultipartBody(fields, {
+				name: 'payload',
+				filename: 'package.tar.gz',
+				contentType: 'application/gzip',
+				stream: packageStream,
+			});
+			options.headers['Content-Type'] = multipart.contentType;
+			// Use chunked transfer-encoding: we don't know the total size up front because the
+			// payload is streamed from `tar.pack` and never fully buffered.
+			options.headers['Transfer-Encoding'] = 'chunked';
+			// Tap the body so bytes flowing into the HTTP request advance the upload bar.
+			// The renderer's Transform is identity — chunks pass through unmodified.
+			body = renderer ? renderer.tapUploadStream(multipart.stream) : multipart.stream;
+		} else {
+			body = req;
+		}
+		let response: any = await httpRequest(options, body);
+
+		// endUpload() is called from the counter Transform's flush callback in tapUploadStream
+		// once all multipart bytes have flowed through. For SSE deploys, httpRequest resolves
+		// when response headers arrive (streamResponse: true), which happens before the full
+		// upload completes — calling endUpload() here would snap the bar prematurely.
+
+		let responseData;
+		if (useSse && response.headers['content-type']?.startsWith('text/event-stream')) {
+			// Consume SSE: render phase events live, capture the final result from the `done`
+			// event (or the error message from the `error` event). The HTTP status stays 200
+			// until end-of-stream; failures are signaled in-band.
+			let finalResult;
+			let sseError;
+			for await (const message of parseSSE(response)) {
+				renderer?.renderEvent(message);
+				if (message.event === 'done') {
+					try {
+						finalResult = JSON.parse(message.data)?.result;
+					} catch {
+						finalResult = message.data;
+					}
+				} else if (message.event === 'error') {
+					try {
+						sseError = JSON.parse(message.data);
+					} catch {
+						sseError = { message: message.data };
+					}
+				}
+			}
+			if (sseError) {
+				const errMsg = sseError.message ?? (typeof sseError === 'object' ? JSON.stringify(sseError) : sseError);
+				console.error(`error: ${errMsg}`);
+				process.exit(1);
+			}
+			responseData = finalResult ?? { message: 'Deploy completed (no result payload).' };
+		} else {
+			// When useSse is true, httpRequest returns a raw IncomingMessage (streamResponse mode),
+			// so .body is undefined. Drain the stream to get the text (e.g. a 401 error body).
+			let bodyText: string;
+			if (useSse) {
+				const chunks: Buffer[] = [];
+				for await (const chunk of response as AsyncIterable<Buffer>) chunks.push(Buffer.from(chunk));
+				bodyText = Buffer.concat(chunks).toString('utf8');
+			} else {
+				bodyText = response.body;
+			}
+			try {
+				responseData = JSON.parse(bodyText);
+			} catch {
+				responseData = {
+					status: response.statusCode + ' ' + (response.statusMessage || 'Unknown'),
+					body: bodyText,
+				};
+			}
+		}
+
+		let responseLog;
+		if (req.json) {
+			responseLog = JSON.stringify(responseData, null, 2);
+		} else {
+			responseLog = YAML.stringify(responseData).trim();
+		}
+
+		const { statusCode } = response;
+		if (statusCode < 200 || (statusCode >= 300 && statusCode !== 304)) {
+			const errorPrefix = responseLog.startsWith('error:') ? '' : 'error: ';
+			console.error(`${errorPrefix}${responseLog}`);
+			process.exit(1);
+		}
+
+		if (!skipResponseLog) {
+			console.log(responseLog);
+		}
+
+		if (target) {
+			responseData.resolvedTarget = target.resolvedTarget;
+		}
+
+		return responseData;
+	} catch (err) {
+		if (err.code === 'ENOENT' || err.code === 'ECONNREFUSED') {
+			console.error(`error: Failed to connect to Harper (${err.code}): ${err.message}`);
+		} else if (err.code === 'EACCES') {
+			console.error(`error: Permission denied accessing the domain socket: ${err.message}`);
+		} else if (err.code === 'ENOTFOUND') {
+			console.error(`error: Host not found: "${err.hostname}" ${err.message}`);
+		} else {
+			console.error(`error: ${err.message ?? err}`);
+		}
+		process.exit(1);
+	}
+}