@iskra-bun/core 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,7 @@
+# @iskra-bun/core
+
+## 0.1.0
+
+### Minor Changes
+
+- Initial public release.

package/README.md

@@ -0,0 +1,31 @@
+# @iskra-bun/core
+
+Nucleo del framework Iskra: clase `App`, inyeccion de dependencias, bus de eventos, logger y manejo de errores. Todos los kits se registran sobre el Core como Drivers o Plugins.
+
+## Instalacion
+
+```bash
+bun add @iskra-bun/core
+```
+
+## Uso rapido
+
+```typescript
+import { App } from '@iskra-bun/core'
+
+const app = new App({ name: 'mi-app' })
+
+app.on('app:started', () => app.logger.info('Listo'))
+
+await app.start()
+```
+
+Registra capacidades adicionales con `app.register(driver)` (Drivers) o `app.use(plugin)` (Plugins).
+
+## Documentacion
+
+Guia completa: [docs/core.md](../../docs/core.md) · Arquitectura: [docs/arquitectura.md](../../docs/arquitectura.md)
+
+## Licencia
+
+AGPL-3.0-or-later

package/dist/index.d.ts

@@ -0,0 +1,323 @@
+import { Emitter } from 'mitt';
+import pino, { Logger as Logger$1 } from 'pino';
+import { z } from 'zod';
+
+declare const createLogger: (name: string, level?: string) => pino.Logger<never, boolean>;
+type Logger = pino.Logger;
+
+interface Driver {
+    name: string;
+    init(app: App): Promise<void> | void;
+    start?(): Promise<void> | void;
+    stop?(): Promise<void> | void;
+}
+interface Plugin {
+    name: string;
+    install(app: App): Promise<void> | void;
+}
+interface Context<T = any> {
+    app: App;
+    logger: Logger$1;
+    payload: T;
+    reply(data: any): void;
+}
+interface OtelConfig {
+    /** Defaults to true when otel config is present */
+    enabled?: boolean;
+    /** OTLP endpoint URL. Defaults to http://localhost:4318 */
+    endpoint?: string;
+    /** Overrides app name for the service.name resource attribute */
+    serviceName?: string;
+    /** Service version resource attribute */
+    serviceVersion?: string;
+    /** Deployment environment resource attribute. Defaults to NODE_ENV */
+    environment?: string;
+    /** Metric export interval in ms. Defaults to 60000 */
+    metricIntervalMs?: number;
+    /** Additional resource attributes */
+    resourceAttributes?: Record<string, string>;
+    /** Auto-instrumentation overrides (passed to getNodeAutoInstrumentations) */
+    instrumentations?: Record<string, {
+        enabled?: boolean;
+    }>;
+}
+interface AppConfig {
+    name: string;
+    debug?: boolean;
+    logger?: {
+        level?: string;
+    };
+    otel?: OtelConfig;
+    processes?: Record<string, ProcessConfig>;
+    socket?: {
+        enabled: boolean;
+        port?: number;
+        adapter?: 'bun' | 'socket.io';
+    };
+    kv?: {
+        driver: 'memory' | 'redis' | 'libsql';
+        connection?: any;
+    };
+    db?: {
+        driver: 'postgres' | 'mysql' | 'sqlite' | 'libsql';
+        url: string;
+        authToken?: string;
+    };
+    [key: string]: any;
+}
+interface ProcessConfig {
+    command: string;
+    args?: string[];
+    mode?: 'daemon' | 'oneshot' | 'stdio';
+    restartOnCrash?: boolean;
+    maxRestarts?: number;
+    restartCooldown?: number;
+    env?: Record<string, string>;
+}
+
+declare class App {
+    config: AppConfig;
+    logger: Logger;
+    events: Emitter<any>;
+    private drivers;
+    context: Map<string, any>;
+    constructor(config?: AppConfig);
+    init(): Promise<void>;
+    register(driver: Driver): this;
+    use(plugin: Plugin): this;
+    on(event: string, handler: (ctx: Context) => Promise<void> | void): this;
+    emit(event: string, payload: any): void;
+    start(): Promise<void>;
+    stop(): Promise<void>;
+}
+
+declare const ErrorCodes: {
+    readonly INTERNAL_ERROR: "INTERNAL_ERROR";
+    readonly NOT_INITIALIZED: "NOT_INITIALIZED";
+    readonly ADAPTER_ERROR: "ADAPTER_ERROR";
+    readonly CONFIG_INVALID: "CONFIG_INVALID";
+    readonly CONFIG_MISSING: "CONFIG_MISSING";
+    readonly DRIVER_INIT_FAILED: "DRIVER_INIT_FAILED";
+    readonly DRIVER_START_FAILED: "DRIVER_START_FAILED";
+    readonly DRIVER_STOP_FAILED: "DRIVER_STOP_FAILED";
+    readonly DRIVER_NOT_FOUND: "DRIVER_NOT_FOUND";
+    readonly PLUGIN_INSTALL_FAILED: "PLUGIN_INSTALL_FAILED";
+    readonly LIFECYCLE_START_FAILED: "LIFECYCLE_START_FAILED";
+    readonly LIFECYCLE_STOP_FAILED: "LIFECYCLE_STOP_FAILED";
+    readonly BAD_REQUEST: "BAD_REQUEST";
+    readonly UNAUTHORIZED: "UNAUTHORIZED";
+    readonly FORBIDDEN: "FORBIDDEN";
+    readonly NOT_FOUND: "NOT_FOUND";
+    readonly CONFLICT: "CONFLICT";
+    readonly VALIDATION_ERROR: "VALIDATION_ERROR";
+    readonly DATABASE_ERROR: "DATABASE_ERROR";
+    readonly CONNECTION_ERROR: "CONNECTION_ERROR";
+    readonly QUERY_ERROR: "QUERY_ERROR";
+    readonly MIGRATION_ERROR: "MIGRATION_ERROR";
+    readonly CACHE_ERROR: "CACHE_ERROR";
+    readonly STORAGE_ERROR: "STORAGE_ERROR";
+    readonly FILE_UPLOAD_ERROR: "FILE_UPLOAD_ERROR";
+    readonly FILE_NOT_FOUND: "FILE_NOT_FOUND";
+    readonly QUEUE_ERROR: "QUEUE_ERROR";
+    readonly JOB_ERROR: "JOB_ERROR";
+    readonly SOCKET_CONNECTION_ERROR: "SOCKET_CONNECTION_ERROR";
+    readonly SOCKET_MESSAGE_ERROR: "SOCKET_MESSAGE_ERROR";
+};
+type ErrorCode = (typeof ErrorCodes)[keyof typeof ErrorCodes];
+interface IskraErrorOptions {
+    code: ErrorCode;
+    cause?: Error;
+    context?: Record<string, unknown>;
+}
+/**
+ * Clase base para todos los errores del framework Iskra.
+ * Soporta encadenamiento de errores vía `cause` y metadata arbitraria en `context`.
+ */
+declare class IskraError extends Error {
+    readonly code: ErrorCode;
+    readonly context: Record<string, unknown>;
+    constructor(message: string, options: IskraErrorOptions);
+    toJSON(): {
+        cause?: string | undefined;
+        name: string;
+        message: string;
+        code: ErrorCode;
+        context: Record<string, unknown>;
+    };
+}
+declare class ConfigError extends IskraError {
+    constructor(message: string, options?: {
+        cause?: Error;
+        context?: Record<string, unknown>;
+    });
+}
+declare class DriverError extends IskraError {
+    constructor(message: string, options?: {
+        code?: ErrorCode;
+        cause?: Error;
+        context?: Record<string, unknown>;
+    });
+}
+declare class PluginError extends IskraError {
+    constructor(message: string, options?: {
+        cause?: Error;
+        context?: Record<string, unknown>;
+    });
+}
+declare class LifecycleError extends IskraError {
+    readonly failures: PromiseRejectedResult[];
+    constructor(message: string, options: {
+        failures?: PromiseRejectedResult[];
+        cause?: Error;
+        context?: Record<string, unknown>;
+    });
+}
+
+/**
+ * OpenTelemetry SDK initialization for Iskra apps.
+ *
+ * All OTel packages are dynamic-imported so they remain optional peer deps.
+ * Apps that don't set `config.otel` never load this code.
+ *
+ * The module specifiers are held in variables rather than passed as string
+ * literals to `import()`. This stops `tsc` from statically resolving the
+ * optional `@opentelemetry/*` packages at compile time, so the module
+ * typechecks cleanly even when those peer deps are absent. At runtime the
+ * imports still resolve normally, and a missing package degrades to a clear,
+ * actionable error instead of an unhandled module-resolution failure.
+ */
+
+/**
+ * Initialize the OpenTelemetry NodeSDK with OTLP exporters.
+ * Must be called before any drivers start so auto-instrumentation can patch libraries.
+ */
+declare function initOtel(config: OtelConfig, appName: string): Promise<void>;
+/**
+ * Gracefully shut down the OTel SDK, flushing any pending spans/metrics.
+ */
+declare function shutdownOtel(): Promise<void>;
+
+declare function loadAppConfig(cwd?: string): Promise<AppConfig>;
+
+declare const AppConfigSchema: z.ZodObject<{
+    name: z.ZodDefault<z.ZodString>;
+    debug: z.ZodDefault<z.ZodBoolean>;
+    logger: z.ZodDefault<z.ZodObject<{
+        level: z.ZodDefault<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        level: string;
+    }, {
+        level?: string | undefined;
+    }>>;
+    otel: z.ZodOptional<z.ZodObject<{
+        enabled: z.ZodDefault<z.ZodBoolean>;
+        endpoint: z.ZodDefault<z.ZodString>;
+        serviceName: z.ZodOptional<z.ZodString>;
+        serviceVersion: z.ZodDefault<z.ZodString>;
+        environment: z.ZodOptional<z.ZodString>;
+        metricIntervalMs: z.ZodDefault<z.ZodNumber>;
+        resourceAttributes: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+        instrumentations: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodObject<{
+            enabled: z.ZodOptional<z.ZodBoolean>;
+        }, "strip", z.ZodTypeAny, {
+            enabled?: boolean | undefined;
+        }, {
+            enabled?: boolean | undefined;
+        }>>>;
+    }, "strip", z.ZodTypeAny, {
+        enabled: boolean;
+        endpoint: string;
+        serviceVersion: string;
+        metricIntervalMs: number;
+        serviceName?: string | undefined;
+        environment?: string | undefined;
+        resourceAttributes?: Record<string, string> | undefined;
+        instrumentations?: Record<string, {
+            enabled?: boolean | undefined;
+        }> | undefined;
+    }, {
+        enabled?: boolean | undefined;
+        endpoint?: string | undefined;
+        serviceName?: string | undefined;
+        serviceVersion?: string | undefined;
+        environment?: string | undefined;
+        metricIntervalMs?: number | undefined;
+        resourceAttributes?: Record<string, string> | undefined;
+        instrumentations?: Record<string, {
+            enabled?: boolean | undefined;
+        }> | undefined;
+    }>>;
+    processes: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodObject<{
+        command: z.ZodString;
+        args: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+        mode: z.ZodDefault<z.ZodEnum<["daemon", "oneshot", "stdio"]>>;
+        restartOnCrash: z.ZodDefault<z.ZodBoolean>;
+        env: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+    }, "strip", z.ZodTypeAny, {
+        command: string;
+        mode: "daemon" | "oneshot" | "stdio";
+        restartOnCrash: boolean;
+        args?: string[] | undefined;
+        env?: Record<string, string> | undefined;
+    }, {
+        command: string;
+        args?: string[] | undefined;
+        mode?: "daemon" | "oneshot" | "stdio" | undefined;
+        restartOnCrash?: boolean | undefined;
+        env?: Record<string, string> | undefined;
+    }>>>;
+}, "strip", z.ZodTypeAny, {
+    debug: boolean;
+    name: string;
+    logger: {
+        level: string;
+    };
+    otel?: {
+        enabled: boolean;
+        endpoint: string;
+        serviceVersion: string;
+        metricIntervalMs: number;
+        serviceName?: string | undefined;
+        environment?: string | undefined;
+        resourceAttributes?: Record<string, string> | undefined;
+        instrumentations?: Record<string, {
+            enabled?: boolean | undefined;
+        }> | undefined;
+    } | undefined;
+    processes?: Record<string, {
+        command: string;
+        mode: "daemon" | "oneshot" | "stdio";
+        restartOnCrash: boolean;
+        args?: string[] | undefined;
+        env?: Record<string, string> | undefined;
+    }> | undefined;
+}, {
+    debug?: boolean | undefined;
+    name?: string | undefined;
+    logger?: {
+        level?: string | undefined;
+    } | undefined;
+    otel?: {
+        enabled?: boolean | undefined;
+        endpoint?: string | undefined;
+        serviceName?: string | undefined;
+        serviceVersion?: string | undefined;
+        environment?: string | undefined;
+        metricIntervalMs?: number | undefined;
+        resourceAttributes?: Record<string, string> | undefined;
+        instrumentations?: Record<string, {
+            enabled?: boolean | undefined;
+        }> | undefined;
+    } | undefined;
+    processes?: Record<string, {
+        command: string;
+        args?: string[] | undefined;
+        mode?: "daemon" | "oneshot" | "stdio" | undefined;
+        restartOnCrash?: boolean | undefined;
+        env?: Record<string, string> | undefined;
+    }> | undefined;
+}>;
+type AppConfigInput = z.input<typeof AppConfigSchema>;
+type AppConfigOutput = z.output<typeof AppConfigSchema>;
+
+export { App, type AppConfig, type AppConfigInput, type AppConfigOutput, AppConfigSchema, ConfigError, type Context, type Driver, DriverError, type ErrorCode, ErrorCodes, IskraError, type IskraErrorOptions, LifecycleError, type Logger, type OtelConfig, type Plugin, PluginError, type ProcessConfig, createLogger, initOtel, loadAppConfig, shutdownOtel };

package/dist/index.js

@@ -0,0 +1,314 @@
+// src/app.ts
+import mitt from "mitt";
+
+// src/logger/index.ts
+import pino from "pino";
+var createLogger = (name, level = "info") => {
+  return pino({
+    name,
+    level,
+    transport: {
+      target: "pino-pretty",
+      options: {
+        colorize: true
+      }
+    }
+  });
+};
+
+// src/config/loader.ts
+import { loadConfig } from "c12";
+
+// src/config/schema.ts
+import { z } from "zod";
+var AppConfigSchema = z.object({
+  name: z.string().default("IskraApp"),
+  debug: z.boolean().default(false),
+  logger: z.object({
+    level: z.string().default("info")
+  }).default({}),
+  otel: z.object({
+    enabled: z.boolean().default(true),
+    endpoint: z.string().default("http://localhost:4318"),
+    serviceName: z.string().optional(),
+    serviceVersion: z.string().default("0.1.0"),
+    environment: z.string().optional(),
+    metricIntervalMs: z.number().default(6e4),
+    resourceAttributes: z.record(z.string()).optional(),
+    instrumentations: z.record(z.object({ enabled: z.boolean().optional() })).optional()
+  }).optional(),
+  processes: z.record(z.object({
+    command: z.string(),
+    args: z.array(z.string()).optional(),
+    mode: z.enum(["daemon", "oneshot", "stdio"]).default("daemon"),
+    restartOnCrash: z.boolean().default(false),
+    env: z.record(z.string()).optional()
+  })).optional()
+});
+
+// src/config/loader.ts
+async function loadAppConfig(cwd = process.cwd()) {
+  const { config } = await loadConfig({
+    name: "app",
+    configFile: "app.config",
+    cwd,
+    dotenv: true
+  });
+  const validConfig = AppConfigSchema.parse(config || {});
+  return validConfig;
+}
+
+// src/errors.ts
+var ErrorCodes = {
+  // General
+  INTERNAL_ERROR: "INTERNAL_ERROR",
+  NOT_INITIALIZED: "NOT_INITIALIZED",
+  ADAPTER_ERROR: "ADAPTER_ERROR",
+  // Config
+  CONFIG_INVALID: "CONFIG_INVALID",
+  CONFIG_MISSING: "CONFIG_MISSING",
+  // Driver
+  DRIVER_INIT_FAILED: "DRIVER_INIT_FAILED",
+  DRIVER_START_FAILED: "DRIVER_START_FAILED",
+  DRIVER_STOP_FAILED: "DRIVER_STOP_FAILED",
+  DRIVER_NOT_FOUND: "DRIVER_NOT_FOUND",
+  // Plugin
+  PLUGIN_INSTALL_FAILED: "PLUGIN_INSTALL_FAILED",
+  // Lifecycle
+  LIFECYCLE_START_FAILED: "LIFECYCLE_START_FAILED",
+  LIFECYCLE_STOP_FAILED: "LIFECYCLE_STOP_FAILED",
+  // HTTP
+  BAD_REQUEST: "BAD_REQUEST",
+  UNAUTHORIZED: "UNAUTHORIZED",
+  FORBIDDEN: "FORBIDDEN",
+  NOT_FOUND: "NOT_FOUND",
+  CONFLICT: "CONFLICT",
+  VALIDATION_ERROR: "VALIDATION_ERROR",
+  // Data
+  DATABASE_ERROR: "DATABASE_ERROR",
+  CONNECTION_ERROR: "CONNECTION_ERROR",
+  QUERY_ERROR: "QUERY_ERROR",
+  MIGRATION_ERROR: "MIGRATION_ERROR",
+  CACHE_ERROR: "CACHE_ERROR",
+  // Storage / Upload
+  STORAGE_ERROR: "STORAGE_ERROR",
+  FILE_UPLOAD_ERROR: "FILE_UPLOAD_ERROR",
+  FILE_NOT_FOUND: "FILE_NOT_FOUND",
+  // Worker
+  QUEUE_ERROR: "QUEUE_ERROR",
+  JOB_ERROR: "JOB_ERROR",
+  // Socket
+  SOCKET_CONNECTION_ERROR: "SOCKET_CONNECTION_ERROR",
+  SOCKET_MESSAGE_ERROR: "SOCKET_MESSAGE_ERROR"
+};
+var IskraError = class extends Error {
+  code;
+  context;
+  constructor(message, options) {
+    super(message, { cause: options.cause });
+    this.name = "IskraError";
+    this.code = options.code;
+    this.context = options.context ?? {};
+  }
+  toJSON() {
+    return {
+      name: this.name,
+      message: this.message,
+      code: this.code,
+      context: this.context,
+      ...this.cause instanceof Error ? { cause: this.cause.message } : {}
+    };
+  }
+};
+var ConfigError = class extends IskraError {
+  constructor(message, options) {
+    super(message, { code: ErrorCodes.CONFIG_INVALID, ...options });
+    this.name = "ConfigError";
+  }
+};
+var DriverError = class extends IskraError {
+  constructor(message, options) {
+    super(message, { code: options?.code ?? ErrorCodes.DRIVER_INIT_FAILED, cause: options?.cause, context: options?.context });
+    this.name = "DriverError";
+  }
+};
+var PluginError = class extends IskraError {
+  constructor(message, options) {
+    super(message, { code: ErrorCodes.PLUGIN_INSTALL_FAILED, ...options });
+    this.name = "PluginError";
+  }
+};
+var LifecycleError = class extends IskraError {
+  failures;
+  constructor(message, options) {
+    super(message, { code: ErrorCodes.LIFECYCLE_STOP_FAILED, cause: options.cause, context: options.context });
+    this.name = "LifecycleError";
+    this.failures = options.failures ?? [];
+  }
+};
+
+// src/otel.ts
+var sdkInstance = null;
+var OTEL_MODULES = {
+  sdkNode: "@opentelemetry/sdk-node",
+  autoInstrumentations: "@opentelemetry/auto-instrumentations-node",
+  traceExporter: "@opentelemetry/exporter-trace-otlp-http",
+  metricExporter: "@opentelemetry/exporter-metrics-otlp-http",
+  sdkMetrics: "@opentelemetry/sdk-metrics",
+  resources: "@opentelemetry/resources",
+  semconv: "@opentelemetry/semantic-conventions"
+};
+function importOptional(specifier) {
+  return import(specifier);
+}
+async function initOtel(config, appName) {
+  if (sdkInstance) return;
+  try {
+    const [
+      { NodeSDK },
+      { getNodeAutoInstrumentations },
+      { OTLPTraceExporter },
+      { OTLPMetricExporter },
+      { PeriodicExportingMetricReader },
+      { Resource },
+      semconv
+    ] = await Promise.all([
+      importOptional(OTEL_MODULES.sdkNode),
+      importOptional(OTEL_MODULES.autoInstrumentations),
+      importOptional(OTEL_MODULES.traceExporter),
+      importOptional(OTEL_MODULES.metricExporter),
+      importOptional(OTEL_MODULES.sdkMetrics),
+      importOptional(OTEL_MODULES.resources),
+      importOptional(OTEL_MODULES.semconv)
+    ]);
+    const serviceName = config.serviceName || appName;
+    const endpoint = config.endpoint || "http://localhost:4318";
+    const resource = new Resource({
+      [semconv.ATTR_SERVICE_NAME]: serviceName,
+      [semconv.ATTR_SERVICE_VERSION]: config.serviceVersion || "0.1.0",
+      "deployment.environment": config.environment || process.env.NODE_ENV || "development",
+      ...config.resourceAttributes
+    });
+    const instrumentationOverrides = {
+      "@opentelemetry/instrumentation-fs": { enabled: false },
+      ...config.instrumentations
+    };
+    const sdk = new NodeSDK({
+      resource,
+      traceExporter: new OTLPTraceExporter({ url: `${endpoint}/v1/traces` }),
+      metricReader: new PeriodicExportingMetricReader({
+        exporter: new OTLPMetricExporter({ url: `${endpoint}/v1/metrics` }),
+        exportIntervalMillis: config.metricIntervalMs ?? 6e4
+      }),
+      instrumentations: [getNodeAutoInstrumentations(instrumentationOverrides)]
+    });
+    sdk.start();
+    sdkInstance = sdk;
+  } catch (err) {
+    if (err?.code === "ERR_MODULE_NOT_FOUND" || err?.code === "MODULE_NOT_FOUND" || err?.message?.includes("Cannot find")) {
+      throw new Error(
+        `[iskra/otel] OpenTelemetry packages are not installed. Install them with: bun add @opentelemetry/sdk-node @opentelemetry/auto-instrumentations-node @opentelemetry/exporter-trace-otlp-http @opentelemetry/exporter-metrics-otlp-http @opentelemetry/sdk-metrics @opentelemetry/resources @opentelemetry/semantic-conventions`
+      );
+    }
+    throw err;
+  }
+}
+async function shutdownOtel() {
+  if (sdkInstance) {
+    await sdkInstance.shutdown();
+    sdkInstance = null;
+  }
+}
+
+// src/app.ts
+var App = class {
+  config;
+  logger;
+  events;
+  drivers = [];
+  context = /* @__PURE__ */ new Map();
+  constructor(config) {
+    this.events = mitt();
+    this.config = config || { name: "Bootstrapping", logger: { level: "info" } };
+    this.logger = createLogger(this.config.name, this.config.logger?.level);
+  }
+  async init() {
+    if (this.config.name === "Bootstrapping") {
+      this.config = await loadAppConfig();
+      this.logger = createLogger(this.config.name, this.config.logger?.level);
+    }
+    if (this.config.otel && this.config.otel.enabled !== false) {
+      await initOtel(this.config.otel, this.config.name);
+      this.logger.info({ endpoint: this.config.otel.endpoint }, "OpenTelemetry initialized");
+    }
+    this.logger.info("Initializing App...");
+    for (const driver of this.drivers) {
+      if (driver.init) {
+        this.logger.debug(`Initializing driver: ${driver.name}`);
+        await driver.init(this);
+      }
+    }
+  }
+  register(driver) {
+    this.drivers.push(driver);
+    return this;
+  }
+  use(plugin) {
+    plugin.install(this);
+    return this;
+  }
+  on(event, handler) {
+    this.events.on(event, async (payload) => {
+      const ctx = {
+        app: this,
+        logger: this.logger.child({ event }),
+        payload,
+        reply: (data) => this.events.emit(`${event}:reply`, data)
+      };
+      try {
+        await handler(ctx);
+      } catch (err) {
+        this.logger.error({ err, event }, "Error handling event");
+      }
+    });
+    return this;
+  }
+  emit(event, payload) {
+    this.events.emit(event, payload);
+  }
+  async start() {
+    await this.init();
+    this.logger.info("Starting drivers...");
+    await Promise.all(this.drivers.map((d) => d.start ? d.start() : Promise.resolve()));
+    this.logger.info("App started successfully \u{1F680}");
+  }
+  async stop() {
+    this.logger.info("Stopping app...");
+    const results = await Promise.allSettled(this.drivers.map((d) => d.stop ? d.stop() : Promise.resolve()));
+    const failures = results.filter((r) => r.status === "rejected");
+    if (failures.length > 0) {
+      this.logger.error({ failures }, "Some drivers failed to stop");
+      throw new LifecycleError("Some drivers failed to stop", {
+        failures,
+        context: { driverCount: this.drivers.length, failedCount: failures.length }
+      });
+    }
+    await shutdownOtel();
+    this.logger.info("App stopped.");
+  }
+};
+export {
+  App,
+  AppConfigSchema,
+  ConfigError,
+  DriverError,
+  ErrorCodes,
+  IskraError,
+  LifecycleError,
+  PluginError,
+  createLogger,
+  initOtel,
+  loadAppConfig,
+  shutdownOtel
+};
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/app.ts","../src/logger/index.ts","../src/config/loader.ts","../src/config/schema.ts","../src/errors.ts","../src/otel.ts"],"sourcesContent":["import mitt, { type Emitter } from 'mitt';\nimport { createLogger, type Logger } from './logger';\nimport { loadAppConfig } from './config/loader';\nimport type { AppConfig, Driver, Plugin, Context } from './types';\nimport { LifecycleError } from './errors';\nimport { initOtel, shutdownOtel } from './otel';\n\nexport class App {\n    public config: AppConfig;\n    public logger: Logger;\n    public events: Emitter<any>;\n    private drivers: Driver[] = [];\n    public context: Map<string, any> = new Map();\n\n    constructor(config?: AppConfig) {\n        this.events = mitt();\n        // Temporary config until init() is called (or passed in constructor)\n        this.config = config || { name: 'Bootstrapping', logger: { level: 'info' } } as AppConfig;\n        this.logger = createLogger(this.config.name, this.config.logger?.level);\n    }\n\n    async init() {\n        // If config was not passed, load it\n        if (this.config.name === 'Bootstrapping') {\n            this.config = await loadAppConfig();\n            this.logger = createLogger(this.config.name, this.config.logger?.level);\n        }\n\n        // Initialize OpenTelemetry SDK before drivers (so auto-instrumentation patches libraries)\n        if (this.config.otel && this.config.otel.enabled !== false) {\n            await initOtel(this.config.otel, this.config.name);\n            this.logger.info({ endpoint: this.config.otel.endpoint }, 'OpenTelemetry initialized');\n        }\n\n        this.logger.info('Initializing App...');\n\n        for (const driver of this.drivers) {\n            if (driver.init) {\n                this.logger.debug(`Initializing driver: ${driver.name}`);\n                await driver.init(this);\n            }\n        }\n    }\n\n    register(driver: Driver) {\n        this.drivers.push(driver);\n        return this;\n    }\n\n    use(plugin: Plugin) {\n        plugin.install(this);\n        return this;\n    }\n\n    on(event: string, handler: (ctx: Context) => Promise<void> | void) {\n        this.events.on(event, async (payload) => {\n            const ctx: Context = {\n                app: this,\n                logger: this.logger.child({ event }),\n                payload,\n                reply: (data) => this.events.emit(`${event}:reply`, data)\n            };\n\n            try {\n                await handler(ctx);\n            } catch (err) {\n                this.logger.error({ err, event }, 'Error handling event');\n            }\n        });\n        return this;\n    }\n\n    emit(event: string, payload: any) {\n        this.events.emit(event, payload);\n    }\n\n    async start() {\n        await this.init();\n        this.logger.info('Starting drivers...');\n        await Promise.all(this.drivers.map(d => d.start ? d.start() : Promise.resolve()));\n        this.logger.info('App started successfully 🚀');\n    }\n\n    async stop() {\n        this.logger.info('Stopping app...');\n        const results = await Promise.allSettled(this.drivers.map(d => d.stop ? d.stop() : Promise.resolve()));\n\n        const failures = results.filter((r): r is PromiseRejectedResult => r.status === 'rejected');\n        if (failures.length > 0) {\n            this.logger.error({ failures }, 'Some drivers failed to stop');\n            throw new LifecycleError('Some drivers failed to stop', {\n                failures,\n                context: { driverCount: this.drivers.length, failedCount: failures.length },\n            });\n        }\n\n        // Shutdown OTel SDK after drivers (flush pending spans/metrics)\n        await shutdownOtel();\n\n        this.logger.info('App stopped.');\n    }\n}\n","import pino from 'pino';\n\nexport const createLogger = (name: string, level: string = 'info') => {\n    return pino({\n        name,\n        level,\n        transport: {\n            target: 'pino-pretty',\n            options: {\n                colorize: true\n            }\n        }\n    });\n};\n\nexport type Logger = pino.Logger;\n","import { loadConfig } from 'c12';\nimport { AppConfigSchema, type AppConfigOutput } from './schema';\nimport type { AppConfig } from '../types';\n\nexport async function loadAppConfig(cwd: string = process.cwd()): Promise<AppConfig> {\n    const { config } = await loadConfig<AppConfig>({\n        name: 'app',\n        configFile: 'app.config',\n        cwd,\n        dotenv: true\n    });\n\n    const validConfig = AppConfigSchema.parse(config || {});\n    return validConfig as AppConfig;\n}\n","import { z } from 'zod';\n\nexport const AppConfigSchema = z.object({\n    name: z.string().default('IskraApp'),\n    debug: z.boolean().default(false),\n    logger: z.object({\n        level: z.string().default('info')\n    }).default({}),\n    otel: z.object({\n        enabled: z.boolean().default(true),\n        endpoint: z.string().default('http://localhost:4318'),\n        serviceName: z.string().optional(),\n        serviceVersion: z.string().default('0.1.0'),\n        environment: z.string().optional(),\n        metricIntervalMs: z.number().default(60_000),\n        resourceAttributes: z.record(z.string()).optional(),\n        instrumentations: z.record(z.object({ enabled: z.boolean().optional() })).optional(),\n    }).optional(),\n    processes: z.record(z.object({\n        command: z.string(),\n        args: z.array(z.string()).optional(),\n        mode: z.enum(['daemon', 'oneshot', 'stdio']).default('daemon'),\n        restartOnCrash: z.boolean().default(false),\n        env: z.record(z.string()).optional()\n    })).optional()\n});\n\nexport type AppConfigInput = z.input<typeof AppConfigSchema>;\nexport type AppConfigOutput = z.output<typeof AppConfigSchema>;\n","export const ErrorCodes = {\n    // General\n    INTERNAL_ERROR: 'INTERNAL_ERROR',\n    NOT_INITIALIZED: 'NOT_INITIALIZED',\n    ADAPTER_ERROR: 'ADAPTER_ERROR',\n\n    // Config\n    CONFIG_INVALID: 'CONFIG_INVALID',\n    CONFIG_MISSING: 'CONFIG_MISSING',\n\n    // Driver\n    DRIVER_INIT_FAILED: 'DRIVER_INIT_FAILED',\n    DRIVER_START_FAILED: 'DRIVER_START_FAILED',\n    DRIVER_STOP_FAILED: 'DRIVER_STOP_FAILED',\n    DRIVER_NOT_FOUND: 'DRIVER_NOT_FOUND',\n\n    // Plugin\n    PLUGIN_INSTALL_FAILED: 'PLUGIN_INSTALL_FAILED',\n\n    // Lifecycle\n    LIFECYCLE_START_FAILED: 'LIFECYCLE_START_FAILED',\n    LIFECYCLE_STOP_FAILED: 'LIFECYCLE_STOP_FAILED',\n\n    // HTTP\n    BAD_REQUEST: 'BAD_REQUEST',\n    UNAUTHORIZED: 'UNAUTHORIZED',\n    FORBIDDEN: 'FORBIDDEN',\n    NOT_FOUND: 'NOT_FOUND',\n    CONFLICT: 'CONFLICT',\n    VALIDATION_ERROR: 'VALIDATION_ERROR',\n\n    // Data\n    DATABASE_ERROR: 'DATABASE_ERROR',\n    CONNECTION_ERROR: 'CONNECTION_ERROR',\n    QUERY_ERROR: 'QUERY_ERROR',\n    MIGRATION_ERROR: 'MIGRATION_ERROR',\n    CACHE_ERROR: 'CACHE_ERROR',\n\n    // Storage / Upload\n    STORAGE_ERROR: 'STORAGE_ERROR',\n    FILE_UPLOAD_ERROR: 'FILE_UPLOAD_ERROR',\n    FILE_NOT_FOUND: 'FILE_NOT_FOUND',\n\n    // Worker\n    QUEUE_ERROR: 'QUEUE_ERROR',\n    JOB_ERROR: 'JOB_ERROR',\n\n    // Socket\n    SOCKET_CONNECTION_ERROR: 'SOCKET_CONNECTION_ERROR',\n    SOCKET_MESSAGE_ERROR: 'SOCKET_MESSAGE_ERROR',\n} as const;\n\nexport type ErrorCode = (typeof ErrorCodes)[keyof typeof ErrorCodes];\n\nexport interface IskraErrorOptions {\n    code: ErrorCode;\n    cause?: Error;\n    context?: Record<string, unknown>;\n}\n\n/**\n * Clase base para todos los errores del framework Iskra.\n * Soporta encadenamiento de errores vía `cause` y metadata arbitraria en `context`.\n */\nexport class IskraError extends Error {\n    public readonly code: ErrorCode;\n    public readonly context: Record<string, unknown>;\n\n    constructor(message: string, options: IskraErrorOptions) {\n        super(message, { cause: options.cause });\n        this.name = 'IskraError';\n        this.code = options.code;\n        this.context = options.context ?? {};\n    }\n\n    toJSON() {\n        return {\n            name: this.name,\n            message: this.message,\n            code: this.code,\n            context: this.context,\n            ...(this.cause instanceof Error ? { cause: this.cause.message } : {}),\n        };\n    }\n}\n\n// ─── Config Errors ───────────────────────────────────────────────────────────\n\nexport class ConfigError extends IskraError {\n    constructor(message: string, options?: { cause?: Error; context?: Record<string, unknown> }) {\n        super(message, { code: ErrorCodes.CONFIG_INVALID, ...options });\n        this.name = 'ConfigError';\n    }\n}\n\n// ─── Driver Errors ───────────────────────────────────────────────────────────\n\nexport class DriverError extends IskraError {\n    constructor(message: string, options?: { code?: ErrorCode; cause?: Error; context?: Record<string, unknown> }) {\n        super(message, { code: options?.code ?? ErrorCodes.DRIVER_INIT_FAILED, cause: options?.cause, context: options?.context });\n        this.name = 'DriverError';\n    }\n}\n\n// ─── Plugin Errors ───────────────────────────────────────────────────────────\n\nexport class PluginError extends IskraError {\n    constructor(message: string, options?: { cause?: Error; context?: Record<string, unknown> }) {\n        super(message, { code: ErrorCodes.PLUGIN_INSTALL_FAILED, ...options });\n        this.name = 'PluginError';\n    }\n}\n\n// ─── Lifecycle Errors ────────────────────────────────────────────────────────\n\nexport class LifecycleError extends IskraError {\n    public readonly failures: PromiseRejectedResult[];\n\n    constructor(message: string, options: { failures?: PromiseRejectedResult[]; cause?: Error; context?: Record<string, unknown> }) {\n        super(message, { code: ErrorCodes.LIFECYCLE_STOP_FAILED, cause: options.cause, context: options.context });\n        this.name = 'LifecycleError';\n        this.failures = options.failures ?? [];\n    }\n}\n","/**\n * OpenTelemetry SDK initialization for Iskra apps.\n *\n * All OTel packages are dynamic-imported so they remain optional peer deps.\n * Apps that don't set `config.otel` never load this code.\n *\n * The module specifiers are held in variables rather than passed as string\n * literals to `import()`. This stops `tsc` from statically resolving the\n * optional `@opentelemetry/*` packages at compile time, so the module\n * typechecks cleanly even when those peer deps are absent. At runtime the\n * imports still resolve normally, and a missing package degrades to a clear,\n * actionable error instead of an unhandled module-resolution failure.\n */\nimport type { OtelConfig } from './types';\n\nlet sdkInstance: any = null;\n\n/** Optional OTel package specifiers, indirected so tsc does not resolve them statically. */\nconst OTEL_MODULES = {\n    sdkNode: '@opentelemetry/sdk-node',\n    autoInstrumentations: '@opentelemetry/auto-instrumentations-node',\n    traceExporter: '@opentelemetry/exporter-trace-otlp-http',\n    metricExporter: '@opentelemetry/exporter-metrics-otlp-http',\n    sdkMetrics: '@opentelemetry/sdk-metrics',\n    resources: '@opentelemetry/resources',\n    semconv: '@opentelemetry/semantic-conventions',\n} as const;\n\n/** Import an optional module by specifier; the indirection keeps tsc from resolving it. */\nfunction importOptional(specifier: string): Promise<any> {\n    return import(specifier);\n}\n\n/**\n * Initialize the OpenTelemetry NodeSDK with OTLP exporters.\n * Must be called before any drivers start so auto-instrumentation can patch libraries.\n */\nexport async function initOtel(config: OtelConfig, appName: string): Promise<void> {\n    if (sdkInstance) return; // Already initialized\n\n    try {\n        const [\n            { NodeSDK },\n            { getNodeAutoInstrumentations },\n            { OTLPTraceExporter },\n            { OTLPMetricExporter },\n            { PeriodicExportingMetricReader },\n            { Resource },\n            semconv,\n        ] = await Promise.all([\n            importOptional(OTEL_MODULES.sdkNode),\n            importOptional(OTEL_MODULES.autoInstrumentations),\n            importOptional(OTEL_MODULES.traceExporter),\n            importOptional(OTEL_MODULES.metricExporter),\n            importOptional(OTEL_MODULES.sdkMetrics),\n            importOptional(OTEL_MODULES.resources),\n            importOptional(OTEL_MODULES.semconv),\n        ]);\n\n        const serviceName = config.serviceName || appName;\n        const endpoint = config.endpoint || 'http://localhost:4318';\n\n        const resource = new Resource({\n            [semconv.ATTR_SERVICE_NAME]: serviceName,\n            [semconv.ATTR_SERVICE_VERSION]: config.serviceVersion || '0.1.0',\n            'deployment.environment': config.environment || process.env.NODE_ENV || 'development',\n            ...config.resourceAttributes,\n        });\n\n        const instrumentationOverrides: Record<string, any> = {\n            '@opentelemetry/instrumentation-fs': { enabled: false },\n            ...config.instrumentations,\n        };\n\n        const sdk = new NodeSDK({\n            resource,\n            traceExporter: new OTLPTraceExporter({ url: `${endpoint}/v1/traces` }),\n            metricReader: new PeriodicExportingMetricReader({\n                exporter: new OTLPMetricExporter({ url: `${endpoint}/v1/metrics` }),\n                exportIntervalMillis: config.metricIntervalMs ?? 60_000,\n            }),\n            instrumentations: [getNodeAutoInstrumentations(instrumentationOverrides)],\n        });\n\n        sdk.start();\n        sdkInstance = sdk;\n    } catch (err: any) {\n        // Provide a clear error when OTel packages are not installed\n        if (err?.code === 'ERR_MODULE_NOT_FOUND' || err?.code === 'MODULE_NOT_FOUND' || err?.message?.includes('Cannot find')) {\n            throw new Error(\n                `[iskra/otel] OpenTelemetry packages are not installed. ` +\n                `Install them with: bun add @opentelemetry/sdk-node @opentelemetry/auto-instrumentations-node ` +\n                `@opentelemetry/exporter-trace-otlp-http @opentelemetry/exporter-metrics-otlp-http ` +\n                `@opentelemetry/sdk-metrics @opentelemetry/resources @opentelemetry/semantic-conventions`,\n            );\n        }\n        throw err;\n    }\n}\n\n/**\n * Gracefully shut down the OTel SDK, flushing any pending spans/metrics.\n */\nexport async function shutdownOtel(): Promise<void> {\n    if (sdkInstance) {\n        await sdkInstance.shutdown();\n        sdkInstance = null;\n    }\n}\n"],"mappings":";AAAA,OAAO,UAA4B;;;ACAnC,OAAO,UAAU;AAEV,IAAM,eAAe,CAAC,MAAc,QAAgB,WAAW;AAClE,SAAO,KAAK;AAAA,IACR;AAAA,IACA;AAAA,IACA,WAAW;AAAA,MACP,QAAQ;AAAA,MACR,SAAS;AAAA,QACL,UAAU;AAAA,MACd;AAAA,IACJ;AAAA,EACJ,CAAC;AACL;;;ACbA,SAAS,kBAAkB;;;ACA3B,SAAS,SAAS;AAEX,IAAM,kBAAkB,EAAE,OAAO;AAAA,EACpC,MAAM,EAAE,OAAO,EAAE,QAAQ,UAAU;AAAA,EACnC,OAAO,EAAE,QAAQ,EAAE,QAAQ,KAAK;AAAA,EAChC,QAAQ,EAAE,OAAO;AAAA,IACb,OAAO,EAAE,OAAO,EAAE,QAAQ,MAAM;AAAA,EACpC,CAAC,EAAE,QAAQ,CAAC,CAAC;AAAA,EACb,MAAM,EAAE,OAAO;AAAA,IACX,SAAS,EAAE,QAAQ,EAAE,QAAQ,IAAI;AAAA,IACjC,UAAU,EAAE,OAAO,EAAE,QAAQ,uBAAuB;AAAA,IACpD,aAAa,EAAE,OAAO,EAAE,SAAS;AAAA,IACjC,gBAAgB,EAAE,OAAO,EAAE,QAAQ,OAAO;AAAA,IAC1C,aAAa,EAAE,OAAO,EAAE,SAAS;AAAA,IACjC,kBAAkB,EAAE,OAAO,EAAE,QAAQ,GAAM;AAAA,IAC3C,oBAAoB,EAAE,OAAO,EAAE,OAAO,CAAC,EAAE,SAAS;AAAA,IAClD,kBAAkB,EAAE,OAAO,EAAE,OAAO,EAAE,SAAS,EAAE,QAAQ,EAAE,SAAS,EAAE,CAAC,CAAC,EAAE,SAAS;AAAA,EACvF,CAAC,EAAE,SAAS;AAAA,EACZ,WAAW,EAAE,OAAO,EAAE,OAAO;AAAA,IACzB,SAAS,EAAE,OAAO;AAAA,IAClB,MAAM,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,SAAS;AAAA,IACnC,MAAM,EAAE,KAAK,CAAC,UAAU,WAAW,OAAO,CAAC,EAAE,QAAQ,QAAQ;AAAA,IAC7D,gBAAgB,EAAE,QAAQ,EAAE,QAAQ,KAAK;AAAA,IACzC,KAAK,EAAE,OAAO,EAAE,OAAO,CAAC,EAAE,SAAS;AAAA,EACvC,CAAC,CAAC,EAAE,SAAS;AACjB,CAAC;;;ADrBD,eAAsB,cAAc,MAAc,QAAQ,IAAI,GAAuB;AACjF,QAAM,EAAE,OAAO,IAAI,MAAM,WAAsB;AAAA,IAC3C,MAAM;AAAA,IACN,YAAY;AAAA,IACZ;AAAA,IACA,QAAQ;AAAA,EACZ,CAAC;AAED,QAAM,cAAc,gBAAgB,MAAM,UAAU,CAAC,CAAC;AACtD,SAAO;AACX;;;AEdO,IAAM,aAAa;AAAA;AAAA,EAEtB,gBAAgB;AAAA,EAChB,iBAAiB;AAAA,EACjB,eAAe;AAAA;AAAA,EAGf,gBAAgB;AAAA,EAChB,gBAAgB;AAAA;AAAA,EAGhB,oBAAoB;AAAA,EACpB,qBAAqB;AAAA,EACrB,oBAAoB;AAAA,EACpB,kBAAkB;AAAA;AAAA,EAGlB,uBAAuB;AAAA;AAAA,EAGvB,wBAAwB;AAAA,EACxB,uBAAuB;AAAA;AAAA,EAGvB,aAAa;AAAA,EACb,cAAc;AAAA,EACd,WAAW;AAAA,EACX,WAAW;AAAA,EACX,UAAU;AAAA,EACV,kBAAkB;AAAA;AAAA,EAGlB,gBAAgB;AAAA,EAChB,kBAAkB;AAAA,EAClB,aAAa;AAAA,EACb,iBAAiB;AAAA,EACjB,aAAa;AAAA;AAAA,EAGb,eAAe;AAAA,EACf,mBAAmB;AAAA,EACnB,gBAAgB;AAAA;AAAA,EAGhB,aAAa;AAAA,EACb,WAAW;AAAA;AAAA,EAGX,yBAAyB;AAAA,EACzB,sBAAsB;AAC1B;AAcO,IAAM,aAAN,cAAyB,MAAM;AAAA,EAClB;AAAA,EACA;AAAA,EAEhB,YAAY,SAAiB,SAA4B;AACrD,UAAM,SAAS,EAAE,OAAO,QAAQ,MAAM,CAAC;AACvC,SAAK,OAAO;AACZ,SAAK,OAAO,QAAQ;AACpB,SAAK,UAAU,QAAQ,WAAW,CAAC;AAAA,EACvC;AAAA,EAEA,SAAS;AACL,WAAO;AAAA,MACH,MAAM,KAAK;AAAA,MACX,SAAS,KAAK;AAAA,MACd,MAAM,KAAK;AAAA,MACX,SAAS,KAAK;AAAA,MACd,GAAI,KAAK,iBAAiB,QAAQ,EAAE,OAAO,KAAK,MAAM,QAAQ,IAAI,CAAC;AAAA,IACvE;AAAA,EACJ;AACJ;AAIO,IAAM,cAAN,cAA0B,WAAW;AAAA,EACxC,YAAY,SAAiB,SAAgE;AACzF,UAAM,SAAS,EAAE,MAAM,WAAW,gBAAgB,GAAG,QAAQ,CAAC;AAC9D,SAAK,OAAO;AAAA,EAChB;AACJ;AAIO,IAAM,cAAN,cAA0B,WAAW;AAAA,EACxC,YAAY,SAAiB,SAAkF;AAC3G,UAAM,SAAS,EAAE,MAAM,SAAS,QAAQ,WAAW,oBAAoB,OAAO,SAAS,OAAO,SAAS,SAAS,QAAQ,CAAC;AACzH,SAAK,OAAO;AAAA,EAChB;AACJ;AAIO,IAAM,cAAN,cAA0B,WAAW;AAAA,EACxC,YAAY,SAAiB,SAAgE;AACzF,UAAM,SAAS,EAAE,MAAM,WAAW,uBAAuB,GAAG,QAAQ,CAAC;AACrE,SAAK,OAAO;AAAA,EAChB;AACJ;AAIO,IAAM,iBAAN,cAA6B,WAAW;AAAA,EAC3B;AAAA,EAEhB,YAAY,SAAiB,SAAmG;AAC5H,UAAM,SAAS,EAAE,MAAM,WAAW,uBAAuB,OAAO,QAAQ,OAAO,SAAS,QAAQ,QAAQ,CAAC;AACzG,SAAK,OAAO;AACZ,SAAK,WAAW,QAAQ,YAAY,CAAC;AAAA,EACzC;AACJ;;;AC5GA,IAAI,cAAmB;AAGvB,IAAM,eAAe;AAAA,EACjB,SAAS;AAAA,EACT,sBAAsB;AAAA,EACtB,eAAe;AAAA,EACf,gBAAgB;AAAA,EAChB,YAAY;AAAA,EACZ,WAAW;AAAA,EACX,SAAS;AACb;AAGA,SAAS,eAAe,WAAiC;AACrD,SAAO,OAAO;AAClB;AAMA,eAAsB,SAAS,QAAoB,SAAgC;AAC/E,MAAI,YAAa;AAEjB,MAAI;AACA,UAAM;AAAA,MACF,EAAE,QAAQ;AAAA,MACV,EAAE,4BAA4B;AAAA,MAC9B,EAAE,kBAAkB;AAAA,MACpB,EAAE,mBAAmB;AAAA,MACrB,EAAE,8BAA8B;AAAA,MAChC,EAAE,SAAS;AAAA,MACX;AAAA,IACJ,IAAI,MAAM,QAAQ,IAAI;AAAA,MAClB,eAAe,aAAa,OAAO;AAAA,MACnC,eAAe,aAAa,oBAAoB;AAAA,MAChD,eAAe,aAAa,aAAa;AAAA,MACzC,eAAe,aAAa,cAAc;AAAA,MAC1C,eAAe,aAAa,UAAU;AAAA,MACtC,eAAe,aAAa,SAAS;AAAA,MACrC,eAAe,aAAa,OAAO;AAAA,IACvC,CAAC;AAED,UAAM,cAAc,OAAO,eAAe;AAC1C,UAAM,WAAW,OAAO,YAAY;AAEpC,UAAM,WAAW,IAAI,SAAS;AAAA,MAC1B,CAAC,QAAQ,iBAAiB,GAAG;AAAA,MAC7B,CAAC,QAAQ,oBAAoB,GAAG,OAAO,kBAAkB;AAAA,MACzD,0BAA0B,OAAO,eAAe,QAAQ,IAAI,YAAY;AAAA,MACxE,GAAG,OAAO;AAAA,IACd,CAAC;AAED,UAAM,2BAAgD;AAAA,MAClD,qCAAqC,EAAE,SAAS,MAAM;AAAA,MACtD,GAAG,OAAO;AAAA,IACd;AAEA,UAAM,MAAM,IAAI,QAAQ;AAAA,MACpB;AAAA,MACA,eAAe,IAAI,kBAAkB,EAAE,KAAK,GAAG,QAAQ,aAAa,CAAC;AAAA,MACrE,cAAc,IAAI,8BAA8B;AAAA,QAC5C,UAAU,IAAI,mBAAmB,EAAE,KAAK,GAAG,QAAQ,cAAc,CAAC;AAAA,QAClE,sBAAsB,OAAO,oBAAoB;AAAA,MACrD,CAAC;AAAA,MACD,kBAAkB,CAAC,4BAA4B,wBAAwB,CAAC;AAAA,IAC5E,CAAC;AAED,QAAI,MAAM;AACV,kBAAc;AAAA,EAClB,SAAS,KAAU;AAEf,QAAI,KAAK,SAAS,0BAA0B,KAAK,SAAS,sBAAsB,KAAK,SAAS,SAAS,aAAa,GAAG;AACnH,YAAM,IAAI;AAAA,QACN;AAAA,MAIJ;AAAA,IACJ;AACA,UAAM;AAAA,EACV;AACJ;AAKA,eAAsB,eAA8B;AAChD,MAAI,aAAa;AACb,UAAM,YAAY,SAAS;AAC3B,kBAAc;AAAA,EAClB;AACJ;;;ALrGO,IAAM,MAAN,MAAU;AAAA,EACN;AAAA,EACA;AAAA,EACA;AAAA,EACC,UAAoB,CAAC;AAAA,EACtB,UAA4B,oBAAI,IAAI;AAAA,EAE3C,YAAY,QAAoB;AAC5B,SAAK,SAAS,KAAK;AAEnB,SAAK,SAAS,UAAU,EAAE,MAAM,iBAAiB,QAAQ,EAAE,OAAO,OAAO,EAAE;AAC3E,SAAK,SAAS,aAAa,KAAK,OAAO,MAAM,KAAK,OAAO,QAAQ,KAAK;AAAA,EAC1E;AAAA,EAEA,MAAM,OAAO;AAET,QAAI,KAAK,OAAO,SAAS,iBAAiB;AACtC,WAAK,SAAS,MAAM,cAAc;AAClC,WAAK,SAAS,aAAa,KAAK,OAAO,MAAM,KAAK,OAAO,QAAQ,KAAK;AAAA,IAC1E;AAGA,QAAI,KAAK,OAAO,QAAQ,KAAK,OAAO,KAAK,YAAY,OAAO;AACxD,YAAM,SAAS,KAAK,OAAO,MAAM,KAAK,OAAO,IAAI;AACjD,WAAK,OAAO,KAAK,EAAE,UAAU,KAAK,OAAO,KAAK,SAAS,GAAG,2BAA2B;AAAA,IACzF;AAEA,SAAK,OAAO,KAAK,qBAAqB;AAEtC,eAAW,UAAU,KAAK,SAAS;AAC/B,UAAI,OAAO,MAAM;AACb,aAAK,OAAO,MAAM,wBAAwB,OAAO,IAAI,EAAE;AACvD,cAAM,OAAO,KAAK,IAAI;AAAA,MAC1B;AAAA,IACJ;AAAA,EACJ;AAAA,EAEA,SAAS,QAAgB;AACrB,SAAK,QAAQ,KAAK,MAAM;AACxB,WAAO;AAAA,EACX;AAAA,EAEA,IAAI,QAAgB;AAChB,WAAO,QAAQ,IAAI;AACnB,WAAO;AAAA,EACX;AAAA,EAEA,GAAG,OAAe,SAAiD;AAC/D,SAAK,OAAO,GAAG,OAAO,OAAO,YAAY;AACrC,YAAM,MAAe;AAAA,QACjB,KAAK;AAAA,QACL,QAAQ,KAAK,OAAO,MAAM,EAAE,MAAM,CAAC;AAAA,QACnC;AAAA,QACA,OAAO,CAAC,SAAS,KAAK,OAAO,KAAK,GAAG,KAAK,UAAU,IAAI;AAAA,MAC5D;AAEA,UAAI;AACA,cAAM,QAAQ,GAAG;AAAA,MACrB,SAAS,KAAK;AACV,aAAK,OAAO,MAAM,EAAE,KAAK,MAAM,GAAG,sBAAsB;AAAA,MAC5D;AAAA,IACJ,CAAC;AACD,WAAO;AAAA,EACX;AAAA,EAEA,KAAK,OAAe,SAAc;AAC9B,SAAK,OAAO,KAAK,OAAO,OAAO;AAAA,EACnC;AAAA,EAEA,MAAM,QAAQ;AACV,UAAM,KAAK,KAAK;AAChB,SAAK,OAAO,KAAK,qBAAqB;AACtC,UAAM,QAAQ,IAAI,KAAK,QAAQ,IAAI,OAAK,EAAE,QAAQ,EAAE,MAAM,IAAI,QAAQ,QAAQ,CAAC,CAAC;AAChF,SAAK,OAAO,KAAK,oCAA6B;AAAA,EAClD;AAAA,EAEA,MAAM,OAAO;AACT,SAAK,OAAO,KAAK,iBAAiB;AAClC,UAAM,UAAU,MAAM,QAAQ,WAAW,KAAK,QAAQ,IAAI,OAAK,EAAE,OAAO,EAAE,KAAK,IAAI,QAAQ,QAAQ,CAAC,CAAC;AAErG,UAAM,WAAW,QAAQ,OAAO,CAAC,MAAkC,EAAE,WAAW,UAAU;AAC1F,QAAI,SAAS,SAAS,GAAG;AACrB,WAAK,OAAO,MAAM,EAAE,SAAS,GAAG,6BAA6B;AAC7D,YAAM,IAAI,eAAe,+BAA+B;AAAA,QACpD;AAAA,QACA,SAAS,EAAE,aAAa,KAAK,QAAQ,QAAQ,aAAa,SAAS,OAAO;AAAA,MAC9E,CAAC;AAAA,IACL;AAGA,UAAM,aAAa;AAEnB,SAAK,OAAO,KAAK,cAAc;AAAA,EACnC;AACJ;","names":[]}

package/package.json

@@ -0,0 +1,90 @@
+{
+    "name": "@iskra-bun/core",
+    "version": "0.1.0",
+    "description": "Nucleo del framework Iskra: App, DI, eventos, logger, errores.",
+    "keywords": [
+        "iskra",
+        "bun",
+        "typescript",
+        "framework",
+        "dependency-injection",
+        "hexagonal"
+    ],
+    "author": "Joan Lascano",
+    "license": "AGPL-3.0-or-later",
+    "repository": {
+        "type": "git",
+        "url": "git+https://github.com/fearful/iskra.git",
+        "directory": "packages/core"
+    },
+    "homepage": "https://github.com/fearful/iskra/tree/main/packages/core#readme",
+    "bugs": "https://github.com/fearful/iskra/issues",
+    "type": "module",
+    "main": "./dist/index.js",
+    "module": "./dist/index.js",
+    "types": "./dist/index.d.ts",
+    "exports": {
+        ".": {
+            "source": "./src/index.ts",
+            "bun": "./src/index.ts",
+            "types": "./dist/index.d.ts",
+            "import": "./dist/index.js",
+            "default": "./dist/index.js"
+        }
+    },
+    "files": [
+        "dist",
+        "src",
+        "README.md",
+        "CHANGELOG.md"
+    ],
+    "publishConfig": {
+        "access": "public"
+    },
+    "scripts": {
+        "test": "bun test",
+        "build": "tsup --config ../../tsup.config.ts"
+    },
+    "dependencies": {
+        "c12": "^2.0.1",
+        "mitt": "^3.0.1",
+        "pino": "^9.6.0",
+        "pino-pretty": "^13.0.0",
+        "zod": "^3.24.1"
+    },
+    "peerDependencies": {
+        "@opentelemetry/sdk-node": ">=0.50.0",
+        "@opentelemetry/auto-instrumentations-node": ">=0.40.0",
+        "@opentelemetry/exporter-trace-otlp-http": ">=0.50.0",
+        "@opentelemetry/exporter-metrics-otlp-http": ">=0.50.0",
+        "@opentelemetry/sdk-metrics": ">=1.20.0",
+        "@opentelemetry/resources": ">=1.20.0",
+        "@opentelemetry/semantic-conventions": ">=1.20.0"
+    },
+    "peerDependenciesMeta": {
+        "@opentelemetry/sdk-node": {
+            "optional": true
+        },
+        "@opentelemetry/auto-instrumentations-node": {
+            "optional": true
+        },
+        "@opentelemetry/exporter-trace-otlp-http": {
+            "optional": true
+        },
+        "@opentelemetry/exporter-metrics-otlp-http": {
+            "optional": true
+        },
+        "@opentelemetry/sdk-metrics": {
+            "optional": true
+        },
+        "@opentelemetry/resources": {
+            "optional": true
+        },
+        "@opentelemetry/semantic-conventions": {
+            "optional": true
+        }
+    },
+    "devDependencies": {
+        "@types/node": "^22.10.2"
+    }
+}

package/src/app.ts

@@ -0,0 +1,102 @@
+import mitt, { type Emitter } from 'mitt';
+import { createLogger, type Logger } from './logger';
+import { loadAppConfig } from './config/loader';
+import type { AppConfig, Driver, Plugin, Context } from './types';
+import { LifecycleError } from './errors';
+import { initOtel, shutdownOtel } from './otel';
+
+export class App {
+    public config: AppConfig;
+    public logger: Logger;
+    public events: Emitter<any>;
+    private drivers: Driver[] = [];
+    public context: Map<string, any> = new Map();
+
+    constructor(config?: AppConfig) {
+        this.events = mitt();
+        // Temporary config until init() is called (or passed in constructor)
+        this.config = config || { name: 'Bootstrapping', logger: { level: 'info' } } as AppConfig;
+        this.logger = createLogger(this.config.name, this.config.logger?.level);
+    }
+
+    async init() {
+        // If config was not passed, load it
+        if (this.config.name === 'Bootstrapping') {
+            this.config = await loadAppConfig();
+            this.logger = createLogger(this.config.name, this.config.logger?.level);
+        }
+
+        // Initialize OpenTelemetry SDK before drivers (so auto-instrumentation patches libraries)
+        if (this.config.otel && this.config.otel.enabled !== false) {
+            await initOtel(this.config.otel, this.config.name);
+            this.logger.info({ endpoint: this.config.otel.endpoint }, 'OpenTelemetry initialized');
+        }
+
+        this.logger.info('Initializing App...');
+
+        for (const driver of this.drivers) {
+            if (driver.init) {
+                this.logger.debug(`Initializing driver: ${driver.name}`);
+                await driver.init(this);
+            }
+        }
+    }
+
+    register(driver: Driver) {
+        this.drivers.push(driver);
+        return this;
+    }
+
+    use(plugin: Plugin) {
+        plugin.install(this);
+        return this;
+    }
+
+    on(event: string, handler: (ctx: Context) => Promise<void> | void) {
+        this.events.on(event, async (payload) => {
+            const ctx: Context = {
+                app: this,
+                logger: this.logger.child({ event }),
+                payload,
+                reply: (data) => this.events.emit(`${event}:reply`, data)
+            };
+
+            try {
+                await handler(ctx);
+            } catch (err) {
+                this.logger.error({ err, event }, 'Error handling event');
+            }
+        });
+        return this;
+    }
+
+    emit(event: string, payload: any) {
+        this.events.emit(event, payload);
+    }
+
+    async start() {
+        await this.init();
+        this.logger.info('Starting drivers...');
+        await Promise.all(this.drivers.map(d => d.start ? d.start() : Promise.resolve()));
+        this.logger.info('App started successfully 🚀');
+    }
+
+    async stop() {
+        this.logger.info('Stopping app...');
+        const results = await Promise.allSettled(this.drivers.map(d => d.stop ? d.stop() : Promise.resolve()));
+
+        const failures = results.filter((r): r is PromiseRejectedResult => r.status === 'rejected');
+        if (failures.length > 0) {
+            this.logger.error({ failures }, 'Some drivers failed to stop');
+            throw new LifecycleError('Some drivers failed to stop', {
+                failures,
+                context: { driverCount: this.drivers.length, failedCount: failures.length },
+            });
+        }
+
+        // Shutdown OTel SDK after drivers (flush pending spans/metrics)
+        await shutdownOtel();
+
+        this.logger.info('App stopped.');
+    }
+}

package/src/config/loader.ts

@@ -0,0 +1,15 @@
+import { loadConfig } from 'c12';
+import { AppConfigSchema, type AppConfigOutput } from './schema';
+import type { AppConfig } from '../types';
+
+export async function loadAppConfig(cwd: string = process.cwd()): Promise<AppConfig> {
+    const { config } = await loadConfig<AppConfig>({
+        name: 'app',
+        configFile: 'app.config',
+        cwd,
+        dotenv: true
+    });
+
+    const validConfig = AppConfigSchema.parse(config || {});
+    return validConfig as AppConfig;
+}

package/src/config/schema.ts

@@ -0,0 +1,29 @@
+import { z } from 'zod';
+
+export const AppConfigSchema = z.object({
+    name: z.string().default('IskraApp'),
+    debug: z.boolean().default(false),
+    logger: z.object({
+        level: z.string().default('info')
+    }).default({}),
+    otel: z.object({
+        enabled: z.boolean().default(true),
+        endpoint: z.string().default('http://localhost:4318'),
+        serviceName: z.string().optional(),
+        serviceVersion: z.string().default('0.1.0'),
+        environment: z.string().optional(),
+        metricIntervalMs: z.number().default(60_000),
+        resourceAttributes: z.record(z.string()).optional(),
+        instrumentations: z.record(z.object({ enabled: z.boolean().optional() })).optional(),
+    }).optional(),
+    processes: z.record(z.object({
+        command: z.string(),
+        args: z.array(z.string()).optional(),
+        mode: z.enum(['daemon', 'oneshot', 'stdio']).default('daemon'),
+        restartOnCrash: z.boolean().default(false),
+        env: z.record(z.string()).optional()
+    })).optional()
+});
+
+export type AppConfigInput = z.input<typeof AppConfigSchema>;
+export type AppConfigOutput = z.output<typeof AppConfigSchema>;

package/src/errors.ts

@@ -0,0 +1,124 @@
+export const ErrorCodes = {
+    // General
+    INTERNAL_ERROR: 'INTERNAL_ERROR',
+    NOT_INITIALIZED: 'NOT_INITIALIZED',
+    ADAPTER_ERROR: 'ADAPTER_ERROR',
+
+    // Config
+    CONFIG_INVALID: 'CONFIG_INVALID',
+    CONFIG_MISSING: 'CONFIG_MISSING',
+
+    // Driver
+    DRIVER_INIT_FAILED: 'DRIVER_INIT_FAILED',
+    DRIVER_START_FAILED: 'DRIVER_START_FAILED',
+    DRIVER_STOP_FAILED: 'DRIVER_STOP_FAILED',
+    DRIVER_NOT_FOUND: 'DRIVER_NOT_FOUND',
+
+    // Plugin
+    PLUGIN_INSTALL_FAILED: 'PLUGIN_INSTALL_FAILED',
+
+    // Lifecycle
+    LIFECYCLE_START_FAILED: 'LIFECYCLE_START_FAILED',
+    LIFECYCLE_STOP_FAILED: 'LIFECYCLE_STOP_FAILED',
+
+    // HTTP
+    BAD_REQUEST: 'BAD_REQUEST',
+    UNAUTHORIZED: 'UNAUTHORIZED',
+    FORBIDDEN: 'FORBIDDEN',
+    NOT_FOUND: 'NOT_FOUND',
+    CONFLICT: 'CONFLICT',
+    VALIDATION_ERROR: 'VALIDATION_ERROR',
+
+    // Data
+    DATABASE_ERROR: 'DATABASE_ERROR',
+    CONNECTION_ERROR: 'CONNECTION_ERROR',
+    QUERY_ERROR: 'QUERY_ERROR',
+    MIGRATION_ERROR: 'MIGRATION_ERROR',
+    CACHE_ERROR: 'CACHE_ERROR',
+
+    // Storage / Upload
+    STORAGE_ERROR: 'STORAGE_ERROR',
+    FILE_UPLOAD_ERROR: 'FILE_UPLOAD_ERROR',
+    FILE_NOT_FOUND: 'FILE_NOT_FOUND',
+
+    // Worker
+    QUEUE_ERROR: 'QUEUE_ERROR',
+    JOB_ERROR: 'JOB_ERROR',
+
+    // Socket
+    SOCKET_CONNECTION_ERROR: 'SOCKET_CONNECTION_ERROR',
+    SOCKET_MESSAGE_ERROR: 'SOCKET_MESSAGE_ERROR',
+} as const;
+
+export type ErrorCode = (typeof ErrorCodes)[keyof typeof ErrorCodes];
+
+export interface IskraErrorOptions {
+    code: ErrorCode;
+    cause?: Error;
+    context?: Record<string, unknown>;
+}
+
+/**
+ * Clase base para todos los errores del framework Iskra.
+ * Soporta encadenamiento de errores vía `cause` y metadata arbitraria en `context`.
+ */
+export class IskraError extends Error {
+    public readonly code: ErrorCode;
+    public readonly context: Record<string, unknown>;
+
+    constructor(message: string, options: IskraErrorOptions) {
+        super(message, { cause: options.cause });
+        this.name = 'IskraError';
+        this.code = options.code;
+        this.context = options.context ?? {};
+    }
+
+    toJSON() {
+        return {
+            name: this.name,
+            message: this.message,
+            code: this.code,
+            context: this.context,
+            ...(this.cause instanceof Error ? { cause: this.cause.message } : {}),
+        };
+    }
+}
+
+// ─── Config Errors ───────────────────────────────────────────────────────────
+
+export class ConfigError extends IskraError {
+    constructor(message: string, options?: { cause?: Error; context?: Record<string, unknown> }) {
+        super(message, { code: ErrorCodes.CONFIG_INVALID, ...options });
+        this.name = 'ConfigError';
+    }
+}
+
+// ─── Driver Errors ───────────────────────────────────────────────────────────
+
+export class DriverError extends IskraError {
+    constructor(message: string, options?: { code?: ErrorCode; cause?: Error; context?: Record<string, unknown> }) {
+        super(message, { code: options?.code ?? ErrorCodes.DRIVER_INIT_FAILED, cause: options?.cause, context: options?.context });
+        this.name = 'DriverError';
+    }
+}
+
+// ─── Plugin Errors ───────────────────────────────────────────────────────────
+
+export class PluginError extends IskraError {
+    constructor(message: string, options?: { cause?: Error; context?: Record<string, unknown> }) {
+        super(message, { code: ErrorCodes.PLUGIN_INSTALL_FAILED, ...options });
+        this.name = 'PluginError';
+    }
+}
+
+// ─── Lifecycle Errors ────────────────────────────────────────────────────────
+
+export class LifecycleError extends IskraError {
+    public readonly failures: PromiseRejectedResult[];
+
+    constructor(message: string, options: { failures?: PromiseRejectedResult[]; cause?: Error; context?: Record<string, unknown> }) {
+        super(message, { code: ErrorCodes.LIFECYCLE_STOP_FAILED, cause: options.cause, context: options.context });
+        this.name = 'LifecycleError';
+        this.failures = options.failures ?? [];
+    }
+}

package/src/index.ts

@@ -0,0 +1,7 @@
+export * from './app';
+export * from './types';
+export * from './logger';
+export * from './errors';
+export * from './otel';
+export * from './config/loader';
+export * from './config/schema';

package/src/logger/index.ts

@@ -0,0 +1,16 @@
+import pino from 'pino';
+
+export const createLogger = (name: string, level: string = 'info') => {
+    return pino({
+        name,
+        level,
+        transport: {
+            target: 'pino-pretty',
+            options: {
+                colorize: true
+            }
+        }
+    });
+};
+
+export type Logger = pino.Logger;

package/src/otel.ts

@@ -0,0 +1,109 @@
+/**
+ * OpenTelemetry SDK initialization for Iskra apps.
+ *
+ * All OTel packages are dynamic-imported so they remain optional peer deps.
+ * Apps that don't set `config.otel` never load this code.
+ *
+ * The module specifiers are held in variables rather than passed as string
+ * literals to `import()`. This stops `tsc` from statically resolving the
+ * optional `@opentelemetry/*` packages at compile time, so the module
+ * typechecks cleanly even when those peer deps are absent. At runtime the
+ * imports still resolve normally, and a missing package degrades to a clear,
+ * actionable error instead of an unhandled module-resolution failure.
+ */
+import type { OtelConfig } from './types';
+
+let sdkInstance: any = null;
+
+/** Optional OTel package specifiers, indirected so tsc does not resolve them statically. */
+const OTEL_MODULES = {
+    sdkNode: '@opentelemetry/sdk-node',
+    autoInstrumentations: '@opentelemetry/auto-instrumentations-node',
+    traceExporter: '@opentelemetry/exporter-trace-otlp-http',
+    metricExporter: '@opentelemetry/exporter-metrics-otlp-http',
+    sdkMetrics: '@opentelemetry/sdk-metrics',
+    resources: '@opentelemetry/resources',
+    semconv: '@opentelemetry/semantic-conventions',
+} as const;
+
+/** Import an optional module by specifier; the indirection keeps tsc from resolving it. */
+function importOptional(specifier: string): Promise<any> {
+    return import(specifier);
+}
+
+/**
+ * Initialize the OpenTelemetry NodeSDK with OTLP exporters.
+ * Must be called before any drivers start so auto-instrumentation can patch libraries.
+ */
+export async function initOtel(config: OtelConfig, appName: string): Promise<void> {
+    if (sdkInstance) return; // Already initialized
+
+    try {
+        const [
+            { NodeSDK },
+            { getNodeAutoInstrumentations },
+            { OTLPTraceExporter },
+            { OTLPMetricExporter },
+            { PeriodicExportingMetricReader },
+            { Resource },
+            semconv,
+        ] = await Promise.all([
+            importOptional(OTEL_MODULES.sdkNode),
+            importOptional(OTEL_MODULES.autoInstrumentations),
+            importOptional(OTEL_MODULES.traceExporter),
+            importOptional(OTEL_MODULES.metricExporter),
+            importOptional(OTEL_MODULES.sdkMetrics),
+            importOptional(OTEL_MODULES.resources),
+            importOptional(OTEL_MODULES.semconv),
+        ]);
+
+        const serviceName = config.serviceName || appName;
+        const endpoint = config.endpoint || 'http://localhost:4318';
+
+        const resource = new Resource({
+            [semconv.ATTR_SERVICE_NAME]: serviceName,
+            [semconv.ATTR_SERVICE_VERSION]: config.serviceVersion || '0.1.0',
+            'deployment.environment': config.environment || process.env.NODE_ENV || 'development',
+            ...config.resourceAttributes,
+        });
+
+        const instrumentationOverrides: Record<string, any> = {
+            '@opentelemetry/instrumentation-fs': { enabled: false },
+            ...config.instrumentations,
+        };
+
+        const sdk = new NodeSDK({
+            resource,
+            traceExporter: new OTLPTraceExporter({ url: `${endpoint}/v1/traces` }),
+            metricReader: new PeriodicExportingMetricReader({
+                exporter: new OTLPMetricExporter({ url: `${endpoint}/v1/metrics` }),
+                exportIntervalMillis: config.metricIntervalMs ?? 60_000,
+            }),
+            instrumentations: [getNodeAutoInstrumentations(instrumentationOverrides)],
+        });
+
+        sdk.start();
+        sdkInstance = sdk;
+    } catch (err: any) {
+        // Provide a clear error when OTel packages are not installed
+        if (err?.code === 'ERR_MODULE_NOT_FOUND' || err?.code === 'MODULE_NOT_FOUND' || err?.message?.includes('Cannot find')) {
+            throw new Error(
+                `[iskra/otel] OpenTelemetry packages are not installed. ` +
+                `Install them with: bun add @opentelemetry/sdk-node @opentelemetry/auto-instrumentations-node ` +
+                `@opentelemetry/exporter-trace-otlp-http @opentelemetry/exporter-metrics-otlp-http ` +
+                `@opentelemetry/sdk-metrics @opentelemetry/resources @opentelemetry/semantic-conventions`,
+            );
+        }
+        throw err;
+    }
+}
+
+/**
+ * Gracefully shut down the OTel SDK, flushing any pending spans/metrics.
+ */
+export async function shutdownOtel(): Promise<void> {
+    if (sdkInstance) {
+        await sdkInstance.shutdown();
+        sdkInstance = null;
+    }
+}

package/src/types.ts

@@ -0,0 +1,75 @@
+import type { App } from './app';
+import type { Logger } from 'pino';
+
+export interface Driver {
+    name: string;
+    init(app: App): Promise<void> | void;
+    start?(): Promise<void> | void;
+    stop?(): Promise<void> | void;
+}
+
+export interface Plugin {
+    name: string;
+    install(app: App): Promise<void> | void;
+}
+
+export interface Context<T = any> {
+    app: App;
+    logger: Logger;
+    payload: T;
+    reply(data: any): void;
+}
+
+export interface OtelConfig {
+    /** Defaults to true when otel config is present */
+    enabled?: boolean;
+    /** OTLP endpoint URL. Defaults to http://localhost:4318 */
+    endpoint?: string;
+    /** Overrides app name for the service.name resource attribute */
+    serviceName?: string;
+    /** Service version resource attribute */
+    serviceVersion?: string;
+    /** Deployment environment resource attribute. Defaults to NODE_ENV */
+    environment?: string;
+    /** Metric export interval in ms. Defaults to 60000 */
+    metricIntervalMs?: number;
+    /** Additional resource attributes */
+    resourceAttributes?: Record<string, string>;
+    /** Auto-instrumentation overrides (passed to getNodeAutoInstrumentations) */
+    instrumentations?: Record<string, { enabled?: boolean }>;
+}
+
+export interface AppConfig {
+    name: string;
+    debug?: boolean;
+    logger?: {
+        level?: string;
+    };
+    otel?: OtelConfig;
+    processes?: Record<string, ProcessConfig>;
+    socket?: {
+        enabled: boolean;
+        port?: number; // If different from web
+        adapter?: 'bun' | 'socket.io';
+    };
+    kv?: {
+        driver: 'memory' | 'redis' | 'libsql';
+        connection?: any;
+    };
+    db?: {
+        driver: 'postgres' | 'mysql' | 'sqlite' | 'libsql';
+        url: string;
+        authToken?: string;
+    };
+    [key: string]: any;
+}
+
+export interface ProcessConfig {
+    command: string;
+    args?: string[];
+    mode?: 'daemon' | 'oneshot' | 'stdio';
+    restartOnCrash?: boolean;
+    maxRestarts?: number;
+    restartCooldown?: number;
+    env?: Record<string, string>;
+}