@gobing-ai/ts-infra 0.3.4 → 0.3.6

package/src/application/plugins/host.ts

@@ -0,0 +1,143 @@
+/**
+ * Bare `PluginHost` — owns an insertion-ordered set of plugins and drives
+ * lifecycle fan-out (load → start → stop → unload) with fail-soft semantics
+ * for start/stop/unload and fail-fast for load.
+ *
+ * This is a runtime concern: it needs a logger and event bus, both provided
+ * by the application bootstrap. No capabilities, no trust ladder.
+ *
+ * @module application/plugins
+ */
+
+import type { EventBus } from '../../event-bus/event-bus';
+import type { EventMap } from '../../event-bus/types';
+import { getLogger, type Logger } from '../../logger';
+import type { Plugin, PluginSummary } from './types';
+
+// ── PluginHost ─────────────────────────────────────────────────────────────
+
+/**
+ * Plugin host: registers plugins in insertion order and drives their lifecycle
+ * fan-out (load → start → stop → unload).
+ *
+ * The host stores `EventBus<EventMap>` (the base event contract) rather than
+ * a narrower `TEvents` subtype, because `EventBus` is invariant in its type
+ * parameter and plugins only need the base contract.
+ */
+export class PluginHost {
+    readonly logger: Logger;
+    readonly events: EventBus<EventMap>;
+
+    private readonly _plugins = new Map<string, Plugin>();
+
+    constructor(events: EventBus<EventMap>, opts?: { logger?: Logger }) {
+        this.events = events;
+        this.logger = opts?.logger ?? getLogger('plugin-host');
+    }
+
+    // ── Registration ────────────────────────────────────────────────────
+
+    /** Register a plugin. Throws on duplicate name. */
+    register(plugin: Plugin): void {
+        if (this._plugins.has(plugin.name)) {
+            throw new Error(`Plugin already registered: ${plugin.name}`);
+        }
+        this._plugins.set(plugin.name, plugin);
+    }
+
+    /** Remove a plugin by name. No-op if absent. */
+    unregister(name: string): void {
+        this._plugins.delete(name);
+    }
+
+    /** Check whether a plugin is registered. */
+    has(name: string): boolean {
+        return this._plugins.has(name);
+    }
+
+    /** List registered plugins in registration order. */
+    list(): readonly PluginSummary[] {
+        const result: PluginSummary[] = [];
+        for (const p of this._plugins.values()) {
+            result.push({ name: p.name, version: p.version });
+        }
+        return result;
+    }
+
+    // ── Lifecycle fan-out ───────────────────────────────────────────────
+
+    /**
+     * Fail-fast: calls `onLoad` on every plugin in registration order.
+     * A throwing hook aborts the bootstrap.
+     */
+    async loadAll(): Promise<void> {
+        for (const plugin of this._plugins.values()) {
+            this.logger.debug(`Loading plugin: ${plugin.name}`, { name: plugin.name });
+            await plugin.onLoad(this);
+        }
+    }
+
+    /**
+     * Calls `onStart` on every plugin in registration order.
+     * Plugins with `failFast: true` rethrow (aborting boot); others log + skip.
+     */
+    async startAll(): Promise<void> {
+        for (const plugin of this._plugins.values()) {
+            if (!plugin.onStart) continue;
+            try {
+                this.logger.debug(`Starting plugin: ${plugin.name}`, { name: plugin.name });
+                await plugin.onStart(this);
+            } catch (err) {
+                if (plugin.failFast) {
+                    throw err;
+                }
+                this.logger.error(`Plugin start hook failed: ${plugin.name}`, {
+                    name: plugin.name,
+                    error: (err as Error).message,
+                });
+            }
+        }
+    }
+
+    /**
+     * Fail-soft: calls `onStop` on every plugin in **reverse** registration order.
+     * A throwing hook is logged + skipped.
+     * `reason` is forwarded to each plugin's `onStop(host, reason?)`.
+     */
+    async stopAll(reason?: string): Promise<void> {
+        const reversed = [...this._plugins.values()].reverse();
+        for (const plugin of reversed) {
+            if (!plugin.onStop) continue;
+            try {
+                this.logger.debug(`Stopping plugin: ${plugin.name}`, { name: plugin.name, reason });
+                await plugin.onStop(this, reason);
+            } catch (err) {
+                this.logger.error(`Plugin stop hook failed: ${plugin.name}`, {
+                    name: plugin.name,
+                    error: (err as Error).message,
+                });
+            }
+        }
+    }
+
+    /**
+     * Fail-soft: calls `onUnload` on every plugin in **reverse** registration order.
+     * A throwing hook is logged + skipped.
+     * `reason` is forwarded to each plugin's `onUnload(host, reason?)`.
+     */
+    async unloadAll(reason?: string): Promise<void> {
+        const reversed = [...this._plugins.values()].reverse();
+        for (const plugin of reversed) {
+            if (!plugin.onUnload) continue;
+            try {
+                this.logger.debug(`Unloading plugin: ${plugin.name}`, { name: plugin.name, reason });
+                await plugin.onUnload(this, reason);
+            } catch (err) {
+                this.logger.error(`Plugin unload hook failed: ${plugin.name}`, {
+                    name: plugin.name,
+                    error: (err as Error).message,
+                });
+            }
+        }
+    }
+}

package/src/application/plugins/index.ts

@@ -0,0 +1,3 @@
+// PluginHost class doubles as the type (same contract)
+export { PluginHost } from './host';
+export type { Plugin, PluginSummary } from './types';

package/src/application/plugins/types.ts

@@ -0,0 +1,86 @@
+/**
+ * Portable plugin lifecycle contract.
+ *
+ * The `Plugin` interface is a minimal runtime-neutral lifecycle contract:
+ * no capabilities, no trust ladder, no manifest schema — just `onLoad` / `onUnload`
+ * and `onStart` / `onStop` hooks. Names are deliberately runtime-neutral so
+ * CLI and long-lived server apps share the same semantics.
+ *
+ * @module application/plugins
+ */
+
+import type { EventBus } from '../../event-bus/event-bus';
+import type { EventMap } from '../../event-bus/types';
+import type { Logger } from '../../logger';
+
+// ── Plugin contract ────────────────────────────────────────────────────────
+
+/**
+ * Minimal plugin lifecycle contract.
+ *
+ * All hooks receive the host reference so a plugin can access the runtime
+ * logger, event bus, and other plugins.
+ */
+export interface Plugin {
+    /** Unique name. Used for dedup and lookup in the host. */
+    readonly name: string;
+
+    /** Semver-compatible version string. Informational only in this cut. */
+    readonly version: string;
+
+    /**
+     * When `true`, a throwing `onStart` aborts the bootstrap (fail-fast).
+     * When absent/false, a throwing `onStart` is logged and skipped (fail-soft).
+     * Has no effect on `loadAll` (always fail-fast) or `stopAll`/`unloadAll`
+     * (always fail-soft — teardown is best-effort).
+     */
+    readonly failFast?: boolean;
+
+    /**
+     * Called during `PluginHost.loadAll()` — fail-fast.
+     * A throwing `onLoad` aborts the bootstrap.
+     */
+    onLoad(host: PluginHost): void | Promise<void>;
+
+    /** Called during `PluginHost.unloadAll()` — fail-soft. */
+    onUnload?(host: PluginHost, reason?: string): void | Promise<void>;
+
+    /** Called during `PluginHost.startAll()` — fail-soft. */
+    onStart?(host: PluginHost): void | Promise<void>;
+
+    /** Called during `PluginHost.stopAll()` — fail-soft. */
+    onStop?(host: PluginHost, reason?: string): void | Promise<void>;
+}
+
+// ── Plugin host public shape ───────────────────────────────────────────────
+
+/**
+ * Summary view of a registered plugin (no references, just metadata).
+ */
+export interface PluginSummary {
+    readonly name: string;
+    readonly version: string;
+}
+
+// ── PluginHost structural interface ────────────────────────────────────────
+
+/**
+ * Structural contract for the plugin host.
+ *
+ * This is the shape exposed on `ApplicationRuntime.pluginHost`. Consumers
+ * that need to register/unregister plugins at runtime use this interface.
+ */
+export interface PluginHost {
+    readonly logger: Logger;
+    readonly events: EventBus<EventMap>;
+
+    register(plugin: Plugin): void;
+    unregister(name: string): void;
+    has(name: string): boolean;
+    list(): readonly PluginSummary[];
+
+    loadAll(): Promise<void>;
+    startAll(): Promise<void>;
+    stopAll(reason?: string): Promise<void>;
+    unloadAll(reason?: string): Promise<void>;
+}

package/src/application/types.ts

@@ -0,0 +1,210 @@
+/**
+ * Portable application bootstrap types.
+ *
+ * These types define the DI contract for `runApplication` — a thin orchestration
+ * layer over existing ts-infra primitives. The portable subpath does not import
+ * any runtime-specific adapters; everything injectable comes through the options.
+ *
+ * @module application/types
+ */
+
+import type { EventBus } from '../event-bus/event-bus';
+import type { BusLifecycleEvents, EventMap } from '../event-bus/types';
+import type { InfraEvents } from '../events';
+import type { Logger, LogLevel } from '../logger';
+import type { SchedulerAdapter } from '../scheduler/types';
+import type { PluginHost } from './plugins/host';
+import type { Plugin } from './plugins/types';
+
+// ── Feature flag option groups ────────────────────────────────────────────
+
+/** Logging feature flags. */
+export interface LoggingOptions {
+    /** Enable logging. Default `true`. */
+    enabled?: boolean;
+    /** Minimum log level. Default `'info'`. */
+    level?: LogLevel;
+    /** Enable console output. Default `true`. */
+    console?: boolean;
+    /**
+     * File sink writer. The portable bootstrap never opens files — the caller
+     * (or Node convenience subpath) provides a writer.
+     */
+    fileSink?: (line: string) => void;
+    /** JSON Lines format. Default `true`. */
+    json?: boolean;
+}
+
+/** Event bus feature flags. */
+export interface EventsOptions<TEvents extends EventMap = InfraEvents> {
+    /** Enable event bus. Default `true`. */
+    enabled?: boolean;
+    /** Create and attach a lifecycle bus. Default `true`. */
+    lifecycle?: boolean;
+    /** Attach default observers (log + telemetry). Default `true`. */
+    defaultObservers?: boolean;
+    /** Pre-built event bus (skips creation when provided). */
+    bus?: EventBus<TEvents>;
+}
+
+/** Telemetry feature flags. */
+export interface TelemetryOptions {
+    /** Enable telemetry instrumentation. Default `true`. */
+    enabled?: boolean;
+    /** Service name for spans. Default `'ts-libs'`. */
+    serviceName?: string;
+    /** Deployment environment. Default `'development'`. */
+    environment?: string;
+    /** Capture sanitized SQL in DB spans. Default `false`. */
+    dbStatementDebug?: boolean;
+}
+
+/** Scheduler feature flags. */
+export interface SchedulerOptions {
+    /** Enable scheduler. Default `false`. */
+    enabled?: boolean;
+    /** Injected adapter (skips noop default when provided). */
+    adapter?: SchedulerAdapter;
+    /** Cron entries to register: `[cron, action][]`. */
+    entries?: Array<[string, () => Promise<void>]>;
+    /** Start scheduler immediately after registration. Default `true` when enabled. */
+    autoStart?: boolean;
+}
+
+// ── Resolved bootstrap config ─────────────────────────────────────────────
+
+/**
+ * Fully-resolved bootstrap config (all optionals filled with defaults).
+ * Constructed internally by `resolveBootstrapConfig`.
+ */
+export interface ApplicationBootstrapConfig {
+    readonly logging: Readonly<
+        Required<Pick<LoggingOptions, 'enabled' | 'level' | 'console' | 'json'>> & { fileSink?: (line: string) => void }
+    >;
+    readonly events: { enabled: boolean; lifecycle: boolean; defaultObservers: boolean };
+    readonly telemetry: { enabled: boolean; serviceName: string; environment: string; dbStatementDebug: boolean };
+    readonly scheduler: { enabled: boolean; autoStart: boolean };
+}
+
+// ── Injected services ─────────────────────────────────────────────────────
+
+/** Services that may be pre-injected instead of created by the bootstrap. */
+export interface ApplicationServices<TEvents extends EventMap = InfraEvents> {
+    logger?: Logger;
+    events?: EventBus<TEvents>;
+    lifecycleBus?: EventBus<BusLifecycleEvents>;
+    db?: DbAdapterLike;
+    scheduler?: SchedulerAdapter;
+    /** Pre-built plugin host (when injecting instead of constructing). */
+    pluginHost?: PluginHost;
+}
+
+/**
+ * Minimal DB adapter shape the bootstrap cares about: `close()` for lifecycle.
+ * This avoids importing `ts-db` (an optional peer) from the portable subpath.
+ */
+export interface DbAdapterLike {
+    close(): void;
+}
+
+// ── Stop reason ───────────────────────────────────────────────────────────
+
+/** Why the application is stopping. */
+export type ApplicationStopReason = 'manual' | 'signal' | 'error' | 'shutdown';
+
+// ── Runtime handle ────────────────────────────────────────────────────────
+
+/**
+ * Runtime handle returned by `runApplication`.
+ *
+ * Exposes all resolved services and a `stop()` method for graceful shutdown.
+ */
+export interface ApplicationRuntime<TAppConfig = unknown, TEvents extends EventMap = InfraEvents> {
+    /** Fully-resolved bootstrap config (feature flags + defaults). */
+    readonly config: ApplicationBootstrapConfig;
+    /** Caller-provided application config, or `undefined`. */
+    readonly appConfig: TAppConfig;
+    /** Structured logger. */
+    readonly logger: Logger;
+    /** Application event bus. */
+    readonly events: EventBus<TEvents>;
+    /** Lifecycle bus (when enabled). */
+    readonly lifecycleBus?: EventBus<BusLifecycleEvents>;
+    /** DB adapter (when enabled and injected). */
+    readonly db?: DbAdapterLike;
+    /** Scheduler adapter (when enabled). */
+    readonly scheduler?: SchedulerAdapter;
+    readonly pluginHost: PluginHost;
+    /** Graceful shutdown. Idempotent — safe to call multiple times. */
+    stop(reason?: ApplicationStopReason): Promise<void>;
+}
+
+// ── Options ───────────────────────────────────────────────────────────────
+
+/**
+ * Options for the portable `runApplication`.
+ */
+export interface ApplicationBootstrapOptions<TAppConfig = unknown, TEvents extends EventMap = InfraEvents> {
+    /** Bootstrap feature flags (partial — defaults applied internally). */
+    readonly config?: {
+        logging?: LoggingOptions;
+        events?: EventsOptions<TEvents>;
+        telemetry?: TelemetryOptions;
+        scheduler?: SchedulerOptions;
+    };
+    /** Already-resolved application config. Portable — no file reads. */
+    readonly appConfig?: TAppConfig;
+    /** Pre-built services to inject instead of creating defaults. */
+    readonly services?: Partial<ApplicationServices<TEvents>>;
+    /** Plugins to register and lifecycle-manage via PluginHost. */
+    readonly plugins?: Plugin[];
+    /** User callback: application logic. Called after all services are ready. */
+    readonly start: (app: ApplicationRuntime<TAppConfig, TEvents>) => Promise<void> | void;
+    /** User callback: cleanup before services shut down. */
+    readonly stop?: (
+        app: ApplicationRuntime<TAppConfig, TEvents>,
+        reason: ApplicationStopReason,
+    ) => Promise<void> | void;
+}
+
+// ── Config validation (Node/Bun convenience subpath) ──────────────────────
+
+/**
+ * Validation result matching the structural `safeParse` pattern.
+ * Avoids hard-coupling to a specific validation library.
+ */
+export interface ConfigValidationResult<T> {
+    readonly success: boolean;
+    readonly data?: T;
+    readonly errors?: ReadonlyArray<{ path: string; message: string }>;
+}
+
+/**
+ * Config validator: structural `safeParse`-compatible adapter.
+ * Accepts any validation library that produces `{ success, data?, errors? }`.
+ */
+export type ApplicationConfigValidator<TAppConfig> =
+    | { safeParse(raw: unknown): ConfigValidationResult<TAppConfig> }
+    | ((raw: unknown) => TAppConfig)
+    | { validate(raw: unknown): TAppConfig }
+    | { parse(raw: unknown): TAppConfig };
+
+/**
+ * Config loader options for the Node/Bun convenience subpath.
+ */
+export interface ApplicationConfigLoader<TAppConfig = unknown> {
+    /** Path to the YAML config file. */
+    readonly configFile?: string;
+    /** YAML section name for bootstrap config. Default `'bootstrap'`. */
+    readonly bootstrapSection?: string;
+    /** YAML section name for app-specific config. Default: remaining object. */
+    readonly appSection?: string;
+    /** Caller-provided validator for the app config section. */
+    readonly appConfig?: ApplicationConfigValidator<TAppConfig>;
+    /** Override values merged after loading. */
+    readonly overrides?: Record<string, unknown>;
+}
+
+// Re-export event types needed by consumers
+export type { BusLifecycleEvents, EventMap } from '../event-bus/types';
+export type { InfraEvents } from '../events';