@fulmenhq/tsfulmen 0.1.13 → 0.2.0

package/dist/signals/index.d.ts

@@ -0,0 +1,675 @@
+import { a as BehaviorInfo, m as SignalInfo, k as SignalCatalog, S as SignalManager, l as SignalHandler, H as HandlerOptions, F as FallbackLogger, T as TelemetryEmitter } from '../manager-CH3fX7zO.js';
+export { B as Behavior, b as BehaviorPhase, E as ExitCodes, L as LogLevel, O as OsMappings, P as PlatformOverrides, e as PlatformSupport, f as PlatformSupportLevel, i as Signal, j as SignalBehavior, n as SignalManagerOptions, o as TimeoutBehavior, W as WindowsFallback, p as WindowsFallbackBehavior, q as WindowsFallbackOptions, s as WindowsFallbackResult, c as createSignalManager, g as getFallbackMetadata, d as getHttpFallbackGuidance, h as handleWindowsFallback, r as requiresFallback } from '../manager-CH3fX7zO.js';
+
+/**
+ * Signal Capability Detection
+ *
+ * Platform-aware signal support detection driven by catalog metadata.
+ * Ensures cross-language parity by querying windows_event/fallback fields
+ * rather than hardcoding signal names.
+ */
+/**
+ * Platform types
+ */
+type Platform = "linux" | "darwin" | "win32" | "freebsd" | "unknown";
+/**
+ * Platform capabilities summary
+ */
+interface PlatformCapabilities {
+    platform: Platform;
+    isPOSIX: boolean;
+    isWindows: boolean;
+    supportsNativeSignals: boolean;
+    supportsSignalExitCodes: boolean;
+    supportedSignals: string[];
+    unsupportedSignals: string[];
+    mappedSignals: string[];
+}
+/**
+ * Detect current platform
+ */
+declare function getPlatform(): Platform;
+/**
+ * Check if current platform is POSIX-compliant
+ */
+declare function isPOSIX(): boolean;
+/**
+ * Check if current platform is Windows
+ */
+declare function isWindows(): boolean;
+/**
+ * Check if a signal is supported on the current platform
+ *
+ * Uses catalog metadata (windows_event field) to determine support.
+ * Returns true if:
+ * - Platform is POSIX (all signals natively supported)
+ * - Platform is Windows AND signal has non-null windows_event
+ *
+ * @param signalName - Signal name (e.g., "SIGTERM") or id (e.g., "term")
+ */
+declare function supportsSignal(signalName: string): Promise<boolean>;
+/**
+ * Check if platform supports signal-based exit codes (128+N pattern)
+ *
+ * Windows doesn't propagate signal numbers via exit codes in the same way
+ * as POSIX systems. This function helps applications decide whether to
+ * rely on signal exit codes for process monitoring.
+ */
+declare function supportsSignalExitCodes(): boolean;
+/**
+ * Get comprehensive platform capabilities
+ *
+ * Queries catalog to build a complete picture of signal support.
+ * Useful for capability reporting, documentation generation, and testing.
+ */
+declare function getPlatformCapabilities(): Promise<PlatformCapabilities>;
+/**
+ * Get the signal number for the current platform
+ *
+ * Handles platform-specific overrides (e.g., SIGUSR1/SIGUSR2 on macOS/FreeBSD).
+ * Returns the appropriate signal number based on platform_overrides.
+ *
+ * @param signalName - Signal name (e.g., "SIGTERM") or id (e.g., "term")
+ * @returns Signal number for current platform, or null if signal not found
+ */
+declare function getSignalNumber(signalName: string): Promise<number | null>;
+/**
+ * Get the Windows console event name for a signal
+ *
+ * Returns the Windows console event that corresponds to a Unix signal,
+ * or null if the signal is not supported on Windows.
+ *
+ * @param signalName - Signal name (e.g., "SIGTERM") or id (e.g., "term")
+ */
+declare function getWindowsEvent(signalName: string): Promise<string | null>;
+
+/**
+ * Signal Catalog Loader
+ *
+ * Loads and validates the signal handling catalog from Crucible SSOT assets
+ * following the same pattern as other Foundry catalogs.
+ */
+
+/**
+ * Get the signals catalog version
+ */
+declare function getSignalsVersion(): Promise<string>;
+/**
+ * Get all signals
+ */
+declare function listSignals(): Promise<SignalInfo[]>;
+/**
+ * Get a specific signal by ID or name
+ */
+declare function getSignal(identifier: string): Promise<SignalInfo | null>;
+/**
+ * Get all behaviors
+ */
+declare function listBehaviors(): Promise<BehaviorInfo[]>;
+/**
+ * Get a specific behavior by ID
+ */
+declare function getBehavior(id: string): Promise<BehaviorInfo | null>;
+/**
+ * Get the complete catalog (for advanced use cases)
+ */
+declare function getSignalCatalog(): Promise<SignalCatalog>;
+
+/**
+ * Signal Handler Convenience Wrappers
+ *
+ * Common signal handling patterns for shutdown, reload, and custom behaviors.
+ */
+
+/**
+ * Register a graceful shutdown handler
+ *
+ * Convenience wrapper for SIGTERM and SIGINT handlers.
+ * Automatically registers both signals to the same handler.
+ *
+ * @param manager - Signal manager instance
+ * @param handler - Shutdown handler function
+ * @param options - Handler options
+ *
+ * @example
+ * ```typescript
+ * await onShutdown(manager, async () => {
+ *   await closeDatabase();
+ *   await flushLogs();
+ * });
+ * ```
+ */
+declare function onShutdown(manager: SignalManager, handler: SignalHandler, options?: HandlerOptions): Promise<void>;
+/**
+ * Register a config reload handler
+ *
+ * Convenience wrapper for SIGHUP handler.
+ * Only registers on POSIX platforms (SIGHUP not supported on Windows).
+ *
+ * @param manager - Signal manager instance
+ * @param handler - Reload handler function
+ * @param options - Handler options
+ *
+ * @example
+ * ```typescript
+ * await onReload(manager, async () => {
+ *   const newConfig = await loadConfig();
+ *   await validateConfig(newConfig);
+ *   process.exit(129); // Exit for restart
+ * });
+ * ```
+ */
+declare function onReload(manager: SignalManager, handler: SignalHandler, options?: HandlerOptions): Promise<void>;
+/**
+ * Register a custom handler for SIGUSR1
+ *
+ * Common use cases: toggle debug logging, reopen log files, dump statistics.
+ *
+ * @param manager - Signal manager instance
+ * @param handler - Custom handler function
+ * @param options - Handler options
+ *
+ * @example
+ * ```typescript
+ * await onUSR1(manager, async () => {
+ *   logger.info('SIGUSR1 received - reopening log files');
+ *   await reopenLogFiles();
+ * });
+ * ```
+ */
+declare function onUSR1(manager: SignalManager, handler: SignalHandler, options?: HandlerOptions): Promise<void>;
+/**
+ * Register a custom handler for SIGUSR2
+ *
+ * Common use cases: trigger profiling, rotate credentials, toggle verbose mode.
+ *
+ * @param manager - Signal manager instance
+ * @param handler - Custom handler function
+ * @param options - Handler options
+ *
+ * @example
+ * ```typescript
+ * await onUSR2(manager, async () => {
+ *   logger.info('SIGUSR2 received - toggling debug mode');
+ *   toggleDebugMode();
+ * });
+ * ```
+ */
+declare function onUSR2(manager: SignalManager, handler: SignalHandler, options?: HandlerOptions): Promise<void>;
+/**
+ * Register an emergency quit handler
+ *
+ * Convenience wrapper for SIGQUIT (immediate exit, no cleanup).
+ *
+ * @param manager - Signal manager instance
+ * @param handler - Emergency quit handler
+ * @param options - Handler options
+ *
+ * @example
+ * ```typescript
+ * await onEmergencyQuit(manager, async () => {
+ *   logger.error('SIGQUIT received - emergency exit');
+ *   process.exit(131);
+ * });
+ * ```
+ */
+declare function onEmergencyQuit(manager: SignalManager, handler: SignalHandler, options?: HandlerOptions): Promise<void>;
+/**
+ * Register handlers for all common shutdown signals
+ *
+ * Registers the same handler for SIGTERM, SIGINT, and SIGQUIT.
+ * Useful for applications that want consistent shutdown behavior.
+ *
+ * @param manager - Signal manager instance
+ * @param handler - Shutdown handler function
+ * @param options - Handler options
+ */
+declare function onAnyShutdown(manager: SignalManager, handler: SignalHandler, options?: HandlerOptions): Promise<void>;
+
+/**
+ * Double-Tap Signal Handling
+ *
+ * Implements Ctrl+C double-tap pattern for graceful shutdown with force-quit option.
+ * Per Crucible standard: 2-second window, immediate exit on second signal.
+ */
+
+/**
+ * Double-tap configuration
+ */
+interface DoubleTapConfig {
+    /**
+     * Debounce window in milliseconds (default: 2000ms per Crucible standard)
+     */
+    windowMs?: number;
+    /**
+     * Exit code for forced double-tap exit (default: 130 for SIGINT)
+     */
+    exitCode?: number;
+    /**
+     * Message to display on first signal (default: from catalog)
+     */
+    hintMessage?: string;
+    /**
+     * Logger for double-tap events
+     */
+    logger?: FallbackLogger;
+    /**
+     * Enable test mode (prevents process.exit calls)
+     */
+    testMode?: boolean;
+}
+/**
+ * Double-tap state tracker
+ */
+interface DoubleTapState {
+    firstTapTime: number | null;
+    windowMs: number;
+    exitCode: number;
+    hintMessage: string;
+    logger?: FallbackLogger;
+    testMode: boolean;
+}
+/**
+ * Create double-tap state tracker for a signal
+ *
+ * @param signalName - Signal name (typically "SIGINT")
+ * @param config - Double-tap configuration
+ */
+declare function createDoubleTapTracker(signalName: string, config?: DoubleTapConfig): Promise<DoubleTapState>;
+/**
+ * Handle double-tap signal logic
+ *
+ * Returns true if this is the second tap (force-quit), false if first tap.
+ * Updates state to track timing between taps.
+ *
+ * @param state - Double-tap state tracker
+ * @returns true if force-quit should proceed, false if graceful shutdown
+ */
+declare function handleDoubleTap(state: DoubleTapState): boolean;
+/**
+ * Reset double-tap state
+ *
+ * Called when graceful shutdown completes before second tap.
+ */
+declare function resetDoubleTap(state: DoubleTapState): void;
+/**
+ * Check if currently within double-tap window
+ *
+ * Useful for testing and debugging.
+ */
+declare function isWithinWindow(state: DoubleTapState): boolean;
+/**
+ * Get time remaining in double-tap window (milliseconds)
+ *
+ * Returns null if not in a window, otherwise milliseconds remaining.
+ */
+declare function getWindowTimeRemaining(state: DoubleTapState): number | null;
+
+/**
+ * Signal Support Guards
+ *
+ * Validation functions that throw actionable errors when signals are unsupported.
+ * Used to fail-fast with clear operational guidance.
+ */
+/**
+ * Guard options
+ */
+interface GuardOptions {
+    /**
+     * Include platform-specific operational guidance in error message
+     */
+    includeGuidance?: boolean;
+}
+/**
+ * Ensure a signal is supported on the current platform
+ *
+ * Throws an error with actionable guidance if the signal is not supported.
+ * Use this as a guard at the start of signal registration functions.
+ *
+ * @param signalName - Signal name (e.g., "SIGTERM") or id (e.g., "term")
+ * @param options - Guard configuration
+ * @throws {FoundryCatalogError} If signal is not found or not supported
+ *
+ * @example
+ * ```typescript
+ * await ensureSupported("SIGHUP");
+ * // On Windows: throws with HTTP fallback guidance
+ * // On POSIX: passes through
+ * ```
+ */
+declare function ensureSupported(signalName: string, options?: GuardOptions): Promise<void>;
+/**
+ * Ensure platform supports signal-based exit codes
+ *
+ * Throws an error if the platform doesn't support the POSIX 128+N exit code pattern.
+ * Use this when exit code semantics are critical to application logic.
+ *
+ * @throws {FoundryCatalogError} If platform doesn't support signal exit codes
+ *
+ * @example
+ * ```typescript
+ * ensureSignalExitCodesSupported();
+ * // On Windows: throws with guidance
+ * // On POSIX: passes through
+ * ```
+ */
+declare function ensureSignalExitCodesSupported(): void;
+/**
+ * Ensure platform is POSIX
+ *
+ * Throws an error if the platform is not POSIX-compliant.
+ * Use this for functionality that strictly requires POSIX signal semantics.
+ *
+ * @throws {FoundryCatalogError} If platform is not POSIX
+ */
+declare function ensurePOSIX(): void;
+/**
+ * Ensure platform is Windows
+ *
+ * Throws an error if the platform is not Windows.
+ * Use this for Windows-specific fallback testing or functionality.
+ *
+ * @throws {FoundryCatalogError} If platform is not Windows
+ */
+declare function ensureWindows(): void;
+
+/**
+ * HTTP Signal Endpoint Helper
+ *
+ * Framework-agnostic scaffold for POST /admin/signal endpoint.
+ * Applications provide auth/rate-limiting; helper handles validation and execution.
+ */
+
+/**
+ * Signal request payload
+ */
+interface SignalRequest {
+    signal: string;
+    reason?: string;
+    correlation_id?: string;
+}
+/**
+ * Signal response (success)
+ */
+interface SignalResponse {
+    status: "accepted";
+    signal: string;
+    correlation_id: string;
+    message: string;
+}
+/**
+ * Signal error response
+ */
+interface SignalErrorResponse {
+    status: "error";
+    error: string;
+    message: string;
+    valid_signals?: string[];
+}
+/**
+ * Authentication result
+ */
+interface AuthResult {
+    authenticated: boolean;
+    identity?: string;
+    reason?: string;
+}
+/**
+ * Rate limit result
+ */
+interface RateLimitResult {
+    allowed: boolean;
+    remaining?: number;
+    reset_at?: number;
+}
+/**
+ * Authentication hook function
+ *
+ * Applications must provide this to validate requests.
+ * Returns authentication result with optional identity.
+ */
+type AuthHook = (req: unknown) => Promise<AuthResult> | AuthResult;
+/**
+ * Rate limiting hook function
+ *
+ * Applications may provide this to enforce rate limits.
+ * Returns whether request is allowed and quota info.
+ */
+type RateLimitHook = (identity: string, signal: string) => Promise<RateLimitResult> | RateLimitResult;
+/**
+ * Signal endpoint options
+ */
+interface SignalEndpointOptions {
+    /**
+     * Signal manager instance
+     */
+    manager: SignalManager;
+    /**
+     * Authentication hook (required)
+     */
+    auth: AuthHook;
+    /**
+     * Rate limiting hook (optional)
+     */
+    rateLimit?: RateLimitHook;
+    /**
+     * Logger for endpoint events
+     */
+    logger?: FallbackLogger;
+    /**
+     * Telemetry emitter
+     */
+    telemetry?: TelemetryEmitter;
+    /**
+     * Allowed signals (default: all catalog signals)
+     */
+    allowedSignals?: string[];
+}
+/**
+ * Create a framework-agnostic signal endpoint handler
+ *
+ * Returns an async function that processes signal requests.
+ * Applications wire this to their HTTP framework (Express, Fastify, etc.)
+ *
+ * @param options - Endpoint configuration
+ *
+ * @example Express
+ * ```typescript
+ * const handler = createSignalEndpoint({
+ *   manager,
+ *   auth: async (req) => {
+ *     const token = req.headers.authorization?.split(' ')[1];
+ *     return { authenticated: token === process.env.ADMIN_TOKEN };
+ *   },
+ * });
+ *
+ * app.post('/admin/signal', async (req, res) => {
+ *   const result = await handler(req.body, req);
+ *   res.status(result.status === 'accepted' ? 202 : result.statusCode || 400)
+ *      .json(result);
+ * });
+ * ```
+ *
+ * @example Fastify
+ * ```typescript
+ * const handler = createSignalEndpoint({ manager, auth });
+ *
+ * fastify.post('/admin/signal', async (request, reply) => {
+ *   const result = await handler(request.body, request);
+ *   reply.status(result.status === 'accepted' ? 202 : 400).send(result);
+ * });
+ * ```
+ */
+declare function createSignalEndpoint(options: SignalEndpointOptions): (payload: SignalRequest, req: unknown) => Promise<(SignalResponse | SignalErrorResponse) & {
+    statusCode?: number;
+}>;
+/**
+ * Create a simple bearer token auth hook
+ *
+ * Validates requests against a static token.
+ * For production, use mTLS or more robust auth.
+ *
+ * @param expectedToken - Expected bearer token
+ *
+ * @example
+ * ```typescript
+ * const auth = createBearerTokenAuth(process.env.ADMIN_TOKEN);
+ * const handler = createSignalEndpoint({ manager, auth });
+ * ```
+ */
+declare function createBearerTokenAuth(expectedToken: string): AuthHook;
+/**
+ * Create a simple in-memory rate limiter
+ *
+ * Tracks requests per identity with sliding window.
+ * For production, use Redis or distributed rate limiting.
+ *
+ * @param requestsPerMinute - Max requests per minute per identity
+ *
+ * @example
+ * ```typescript
+ * const rateLimit = createSimpleRateLimiter(10); // 10 req/min
+ * const handler = createSignalEndpoint({ manager, auth, rateLimit });
+ * ```
+ */
+declare function createSimpleRateLimiter(requestsPerMinute: number): RateLimitHook;
+
+/**
+ * Configuration Reload Helpers
+ *
+ * Implements restart-based config reload pattern with mandatory schema validation.
+ * Per Crucible standard: validate before restart, reject invalid configs without disruption.
+ */
+
+/**
+ * Configuration validator function type
+ *
+ * Applications provide this function to validate new config against schema.
+ * Should return validation result with errors if invalid.
+ */
+type ConfigValidator<T = unknown> = (config: T) => Promise<ConfigValidationResult> | ConfigValidationResult;
+/**
+ * Configuration validation result
+ */
+interface ConfigValidationResult {
+    valid: boolean;
+    errors?: Array<{
+        path: string;
+        message: string;
+    }>;
+}
+/**
+ * Configuration loader function type
+ *
+ * Applications provide this function to load new config from disk/environment.
+ */
+type ConfigLoader<T = unknown> = () => Promise<T> | T;
+/**
+ * Config reload options
+ */
+interface ConfigReloadOptions<T = unknown> {
+    /**
+     * Config loader function
+     */
+    loader: ConfigLoader<T>;
+    /**
+     * Schema validator function
+     */
+    validator: ConfigValidator<T>;
+    /**
+     * Callback invoked after successful validation, before exit
+     * Use for cleanup, logging, etc.
+     */
+    onValidated?: (config: T) => void | Promise<void>;
+    /**
+     * Exit code for successful reload (default: 129 for SIGHUP)
+     */
+    exitCode?: number;
+    /**
+     * Logger for reload events
+     */
+    logger?: FallbackLogger;
+    /**
+     * Telemetry emitter
+     */
+    telemetry?: TelemetryEmitter;
+    /**
+     * Test mode (prevents process.exit)
+     */
+    testMode?: boolean;
+}
+/**
+ * Config reload result (for testing)
+ */
+interface ConfigReloadResult {
+    reloaded: boolean;
+    validationErrors?: Array<{
+        path: string;
+        message: string;
+    }>;
+    error?: Error;
+}
+/**
+ * Create a config reload handler with schema validation
+ *
+ * Returns a signal handler function that implements restart-based reload:
+ * 1. Load new config
+ * 2. Validate against schema (mandatory)
+ * 3. If invalid: log errors, continue with current config
+ * 4. If valid: invoke callback, exit for restart
+ *
+ * @param options - Reload configuration
+ *
+ * @example
+ * ```typescript
+ * const reloadHandler = createConfigReloadHandler({
+ *   loader: () => loadConfig('./config.yaml'),
+ *   validator: (config) => validateConfigSchema(config),
+ *   onValidated: async (config) => {
+ *     logger.info('Config validated, restarting...');
+ *   },
+ *   logger: myLogger,
+ * });
+ *
+ * await manager.register('SIGHUP', reloadHandler);
+ * ```
+ */
+declare function createConfigReloadHandler<T = unknown>(options: ConfigReloadOptions<T>): () => Promise<void>;
+/**
+ * Three-strikes failure tracker
+ *
+ * Tracks consecutive config reload failures and triggers alerts.
+ * Useful for detecting persistent config source issues.
+ */
+declare class ConfigReloadTracker {
+    private failures;
+    private lastFailureTime;
+    private readonly maxFailures;
+    private readonly logger?;
+    private readonly telemetry?;
+    constructor(options: {
+        maxFailures?: number;
+        logger?: FallbackLogger;
+        telemetry?: TelemetryEmitter;
+    });
+    /**
+     * Record a reload failure
+     *
+     * @returns true if threshold exceeded, false otherwise
+     */
+    recordFailure(): boolean;
+    /**
+     * Record a successful reload (resets counter)
+     */
+    recordSuccess(): void;
+    /**
+     * Get current failure count
+     */
+    getFailureCount(): number;
+    /**
+     * Get last failure timestamp
+     */
+    getLastFailureTime(): number | null;
+}
+
+export { type AuthHook, type AuthResult, BehaviorInfo, type ConfigLoader, type ConfigReloadOptions, type ConfigReloadResult, ConfigReloadTracker, type ConfigValidationResult, type ConfigValidator, type DoubleTapConfig, type DoubleTapState, FallbackLogger, type GuardOptions, HandlerOptions, type Platform, type PlatformCapabilities, type RateLimitHook, type RateLimitResult, SignalCatalog, type SignalEndpointOptions, type SignalErrorResponse, SignalHandler, SignalInfo, SignalManager, type SignalRequest, type SignalResponse, TelemetryEmitter, createBearerTokenAuth, createConfigReloadHandler, createDoubleTapTracker, createSignalEndpoint, createSimpleRateLimiter, ensurePOSIX, ensureSignalExitCodesSupported, ensureSupported, ensureWindows, getBehavior, getPlatform, getPlatformCapabilities, getSignal, getSignalCatalog, getSignalNumber, getSignalsVersion, getWindowTimeRemaining, getWindowsEvent, handleDoubleTap, isPOSIX, isWindows, isWithinWindow, listBehaviors, listSignals, onAnyShutdown, onEmergencyQuit, onReload, onShutdown, onUSR1, onUSR2, resetDoubleTap, supportsSignal, supportsSignalExitCodes };