@harperfast/harper 5.0.0-alpha.10 → 5.0.0-beta.3

package/components/status/index.ts

@@ -0,0 +1,44 @@
+/**
+ * Component Status System
+ *
+ * A simple, clean API for tracking component health across Harper's distributed architecture.
+ *
+ * @example Basic usage:
+ * ```typescript
+ * import { statusForComponent, STATUS } from './components/status/index.ts';
+ *
+ * // Report component status
+ * statusForComponent('my-service').healthy('Service initialized');
+ * statusForComponent('database').error('Connection timeout', error);
+ * statusForComponent('cache').warning('High memory usage');
+ *
+ * // Get component status
+ * const status = statusForComponent('my-service').get();
+ * ```
+ *
+ * @example Lifecycle usage (for component loader):
+ * ```typescript
+ * import { lifecycle } from './components/status/index.ts';
+ *
+ * lifecycle.loading('my-component');
+ * // ... load component ...
+ * lifecycle.loaded('my-component', 'Successfully initialized');
+ * // or
+ * lifecycle.failed('my-component', error);
+ * ```
+ */
+
+// Public API - clean and simple
+export {
+	statusForComponent, // Main API for reporting status
+	lifecycle, // Component loader lifecycle hooks
+	reset, // Reset all statuses (testing)
+	STATUS, // Status level constants
+} from './api.ts';
+
+// Only export types that external code needs
+export type { ComponentStatusLevel, AggregatedComponentStatus, ComponentStatus } from './api.ts';
+
+// Internal exports for Harper core only
+// These should NOT be used by components
+export * as internal from './internal.ts';

package/components/status/internal.ts

@@ -0,0 +1,65 @@
+/**
+ * Internal Component Status Exports
+ *
+ * These exports are for Harper core internal use only.
+ * Components should use the public API from index.ts
+ */
+
+// Import what we need for the query object
+import type { ComponentStatusLevel } from './types.ts';
+import { componentStatusRegistry } from './registry.ts';
+import { ComponentStatusRegistry } from './ComponentStatusRegistry.ts';
+
+// Internal classes and types
+export { ComponentStatus } from './ComponentStatus.ts';
+export { ComponentStatusRegistry } from './ComponentStatusRegistry.ts';
+export { CrossThreadStatusCollector, StatusAggregator, crossThreadCollector } from './crossThread.ts';
+export type { ComponentStatusMap } from './ComponentStatusRegistry.ts';
+
+// Registry singleton for internal use
+export { componentStatusRegistry } from './registry.ts';
+
+// All error types for internal error handling
+export * from './errors.ts';
+
+// All type definitions
+export * from './types.ts';
+
+// Internal query functions for Harper core
+export const query = {
+	/**
+	 * Get a single component's status
+	 */
+	get(componentName: string) {
+		return componentStatusRegistry.getStatus(componentName);
+	},
+
+	/**
+	 * Get all component statuses in the current thread
+	 */
+	all() {
+		return componentStatusRegistry.getAllStatuses();
+	},
+
+	/**
+	 * Get components by status level
+	 */
+	byStatus(status: ComponentStatusLevel) {
+		return componentStatusRegistry.getComponentsByStatus(status);
+	},
+
+	/**
+	 * Get a summary of component statuses
+	 */
+	summary() {
+		return componentStatusRegistry.getStatusSummary();
+	},
+
+	/**
+	 * Get aggregated status from all threads
+	 * This is an async operation that collects status from all worker threads
+	 */
+	async allThreads() {
+		return ComponentStatusRegistry.getAggregatedFromAllThreads(componentStatusRegistry);
+	},
+};

package/components/status/registry.ts

@@ -0,0 +1,12 @@
+/**
+ * Component Status Registry Singleton
+ *
+ * This module provides the global component status registry instance.
+ */
+
+import { ComponentStatusRegistry } from './ComponentStatusRegistry.ts';
+
+/**
+ * Global component status registry instance
+ */
+export const componentStatusRegistry = new ComponentStatusRegistry();

package/components/status/types.ts

@@ -0,0 +1,96 @@
+/**
+ * Component Status Type Definitions
+ *
+ * This module defines the core types, constants, and interfaces for the
+ * component status tracking system.
+ */
+
+/**
+ * Status levels for components
+ */
+export const COMPONENT_STATUS_LEVELS = {
+	HEALTHY: 'healthy',
+	WARNING: 'warning',
+	ERROR: 'error',
+	UNKNOWN: 'unknown',
+	LOADING: 'loading',
+} as const;
+
+export type ComponentStatusLevel = (typeof COMPONENT_STATUS_LEVELS)[keyof typeof COMPONENT_STATUS_LEVELS];
+
+/**
+ * Component status information as a plain object
+ */
+export interface ComponentStatusSummary {
+	/** Last time this status was checked/updated */
+	lastChecked: Date;
+	/** Current status level */
+	status: ComponentStatusLevel;
+	/** Human-readable status message */
+	message?: string;
+	/** Error information if status is 'error' */
+	error?: Error | string;
+	/** Worker index for cross-thread tracking */
+	workerIndex?: number;
+}
+
+/**
+ * Abnormal component status information for a specific thread
+ */
+export interface ComponentStatusAbnormality {
+	/** Worker index for the thread with abnormal status */
+	workerIndex: number;
+	/** The abnormal status level */
+	status: ComponentStatusLevel;
+	/** Status message for this abnormal instance */
+	message?: string;
+	/** Error information if status is 'error' */
+	error?: Error | string;
+}
+
+/**
+ * Aggregated component status with thread information
+ */
+export interface AggregatedComponentStatus {
+	/** Component name (without thread suffix) */
+	componentName: string;
+	/** Overall status - error if any thread has error, warning if any has warning, etc */
+	status: ComponentStatusLevel;
+	/** Last checked times for each thread (ms since epoch) */
+	lastChecked: {
+		/** Main thread last checked time (if component runs on main) */
+		main?: number;
+		/** Worker thread last checked times indexed by worker number */
+		workers: Record<number, number>;
+	};
+	/** Map of thread-specific statuses if they differ (only populated when inconsistent) */
+	abnormalities?: Map<string, ComponentStatusAbnormality>;
+	/** Most recent message across all threads */
+	latestMessage?: string;
+	/** Any error from any thread */
+	error?: Error | string;
+}
+
+/**
+ * Component status information from a worker thread
+ */
+export interface WorkerComponentStatuses {
+	workerIndex: number | undefined;
+	isMainThread: boolean;
+	statuses: Array<[string, ComponentStatusSummary]>;
+}
+
+/**
+ * Aggregated application-level component status
+ * Used for components that may have multiple sub-components (e.g., application-template.rest, application-template.static)
+ */
+export interface ComponentApplicationStatus {
+	/** Overall aggregated status (error > loading > loaded > healthy) */
+	status: ComponentStatusLevel;
+	/** Descriptive message with details when not healthy */
+	message: string;
+	/** Detailed breakdown when issues exist */
+	details?: Record<string, { status: ComponentStatusLevel; message?: string }>;
+	/** Last checked time information */
+	lastChecked: { workers: Record<number, number> };
+}

package/config/RootConfigWatcher.ts

@@ -0,0 +1,59 @@
+import chokidar, { FSWatcher } from 'chokidar';
+import { readFile } from 'node:fs/promises';
+import { getConfigFilePath } from './configUtils.js';
+import { EventEmitter, once } from 'node:events';
+import { parse } from 'yaml';
+
+export class RootConfigWatcher extends EventEmitter {
+	#configFilePath: string;
+	#watcher: FSWatcher;
+	#config: any;
+	ready: Promise<any[]>;
+
+	constructor() {
+		super();
+		this.#configFilePath = getConfigFilePath();
+		this.ready = once(this, 'ready');
+		this.#watcher = chokidar
+			.watch(this.#configFilePath, { persistent: false })
+			.on('add', this.handleChange.bind(this))
+			.on('change', this.handleChange.bind(this))
+			.on('error', this.handleError.bind(this));
+	}
+
+	handleError(error: unknown) {
+		this.emit('error', error);
+	}
+
+	handleChange() {
+		readFile(this.#configFilePath, 'utf-8')
+			.then((data) => {
+				if (!data) return;
+
+				const config = parse(data);
+
+				if (!this.#config) {
+					this.#config = config;
+					this.emit('ready', this.#config);
+					return;
+				}
+
+				this.emit('change', (this.#config = config));
+			})
+			.catch((_error) => {
+				// if yaml parse error ignore?
+			});
+	}
+
+	close() {
+		this.#watcher.close();
+		this.#config = undefined;
+		this.emit('close');
+		this.removeAllListeners();
+		return this;
+	}
+
+	get config() {
+		return this.#config;
+	}
+}

package/config/configHelpers.ts

@@ -0,0 +1,11 @@
+import * as path from 'node:path';
+import * as hdbTerms from '../utility/hdbTerms.ts';
+
+/**
+ * Get the backup directory path for the given Harper root
+ * @param hdbRoot - Harper root path
+ * @returns Full path to backup directory
+ */
+export function getBackupDirPath(hdbRoot: string): string {
+	return path.join(hdbRoot, hdbTerms.BACKUP_DIR_NAME);
+}