@chidchanun/bcp 0.2.19 → 0.3.0

package/packages/client/src/application.mjs

@@ -0,0 +1,1873 @@
+// packages/server/src/deployment.ts
+import {
+  randomUUID
+} from "node:crypto";
+
+// packages/server/src/production-hardening.ts
+var nextShutdownHookId = 1;
+var shutdownHooks = /* @__PURE__ */ new Map();
+function registerShutdownHook(hook, options = {}) {
+  if (typeof hook !== "function") {
+    throw new TypeError(
+      "BCP Framework: shutdown hook must be a function."
+    );
+  }
+  const id = nextShutdownHookId++;
+  const name = normalizeHookName(
+    options.name,
+    id
+  );
+  shutdownHooks.set(
+    id,
+    {
+      id,
+      name,
+      hook
+    }
+  );
+  return () => {
+    shutdownHooks.delete(
+      id
+    );
+  };
+}
+function normalizeHookName(value, id) {
+  const normalized = value?.trim();
+  if (!normalized) {
+    return `hook-${id}`;
+  }
+  if (normalized.length > 128 || /[\r\n]/.test(
+    normalized
+  )) {
+    throw new TypeError(
+      "BCP Framework: shutdown hook name must be at most 128 characters without line breaks."
+    );
+  }
+  return normalized;
+}
+
+// packages/server/src/deployment.ts
+var DEFAULT_SHUTDOWN_TIMEOUT_MS = 1e4;
+var DEFAULT_READINESS_TIMEOUT_MS = 5e3;
+var DEFAULT_SIGNALS = [
+  "SIGTERM",
+  "SIGINT"
+];
+function createDeploymentRuntime(options) {
+  const environment = options.environment ?? process.env;
+  const now = options.now ?? Date.now;
+  const idFactory = options.idFactory ?? randomUUID;
+  const shutdownTimeoutMs = positiveInteger(
+    options.shutdownTimeoutMs ?? parseOptionalPositiveInteger(
+      environment.BCP_SHUTDOWN_TIMEOUT_MS
+    ) ?? DEFAULT_SHUTDOWN_TIMEOUT_MS,
+    "shutdownTimeoutMs"
+  );
+  const readinessTimeoutMs = positiveInteger(
+    options.readinessTimeoutMs ?? DEFAULT_READINESS_TIMEOUT_MS,
+    "readinessTimeoutMs"
+  );
+  const startedAtMs = now();
+  assertTimestamp(
+    startedAtMs,
+    "runtime start timestamp"
+  );
+  const metadata = {
+    serviceName: normalizeName(
+      options.serviceName,
+      "serviceName"
+    ),
+    ...normalizeOptionalText(
+      options.version
+    ) ? {
+      version: normalizeOptionalText(
+        options.version
+      )
+    } : {},
+    deploymentId: normalizeName(
+      options.deploymentId ?? environment.BCP_DEPLOYMENT_ID ?? idFactory(),
+      "deploymentId"
+    ),
+    ...normalizeOptionalText(
+      options.instanceId ?? environment.BCP_INSTANCE_ID
+    ) ? {
+      instanceId: normalizeOptionalText(
+        options.instanceId ?? environment.BCP_INSTANCE_ID
+      )
+    } : {},
+    ...normalizeOptionalText(
+      options.release ?? environment.BCP_RELEASE
+    ) ? {
+      release: normalizeOptionalText(
+        options.release ?? environment.BCP_RELEASE
+      )
+    } : {},
+    ...normalizeOptionalText(
+      options.environmentName ?? environment.NODE_ENV
+    ) ? {
+      environment: normalizeOptionalText(
+        options.environmentName ?? environment.NODE_ENV
+      )
+    } : {},
+    startedAt: new Date(startedAtMs).toISOString(),
+    pid: process.pid,
+    nodeVersion: process.version,
+    platform: process.platform,
+    arch: process.arch
+  };
+  const abortController = new AbortController();
+  const resourceEntries = [];
+  const names = /* @__PURE__ */ new Set();
+  let state = "idle";
+  let startPromise;
+  let shutdownPromise;
+  const runtime = {
+    metadata,
+    get state() {
+      return state;
+    },
+    addResource(resource) {
+      if (state !== "idle") {
+        throw new Error(
+          "BCP Deployment: resources can only be registered before runtime start."
+        );
+      }
+      const name = normalizeName(
+        resource.name,
+        "resource name"
+      );
+      if (names.has(name)) {
+        throw new Error(
+          `BCP Deployment: resource "${name}" is already registered.`
+        );
+      }
+      const normalized = {
+        ...resource,
+        name
+      };
+      const entry = {
+        resource: normalized,
+        status: {
+          name,
+          state: "registered"
+        }
+      };
+      names.add(name);
+      resourceEntries.push(entry);
+      return () => {
+        if (state !== "idle") {
+          return;
+        }
+        const index = resourceEntries.indexOf(
+          entry
+        );
+        if (index >= 0) {
+          resourceEntries.splice(
+            index,
+            1
+          );
+          names.delete(name);
+        }
+      };
+    },
+    resources() {
+      return resourceEntries.map(
+        (entry) => ({
+          ...entry.status
+        })
+      );
+    },
+    async start() {
+      if (state === "ready") {
+        return;
+      }
+      if (startPromise) {
+        return startPromise;
+      }
+      if (state === "draining" || state === "stopped") {
+        throw new Error(
+          "BCP Deployment: stopped runtime cannot be started again."
+        );
+      }
+      if (state === "failed") {
+        throw new Error(
+          "BCP Deployment: failed runtime cannot be started again."
+        );
+      }
+      startPromise = startResources();
+      return startPromise;
+    },
+    async readiness() {
+      const checkedAtMs = now();
+      assertTimestamp(
+        checkedAtMs,
+        "readiness timestamp"
+      );
+      const results = [];
+      for (const entry of resourceEntries) {
+        if (entry.status.state !== "started") {
+          results.push({
+            name: entry.resource.name,
+            ok: false,
+            durationMs: 0,
+            detail: `Resource state is ${entry.status.state}.`
+          });
+          continue;
+        }
+        if (!entry.resource.ready) {
+          results.push({
+            name: entry.resource.name,
+            ok: true,
+            durationMs: 0
+          });
+          continue;
+        }
+        const checkStarted = performance.now();
+        try {
+          const value = await withTimeout(
+            Promise.resolve(
+              entry.resource.ready(
+                createContext()
+              )
+            ),
+            readinessTimeoutMs,
+            `readiness check for ${entry.resource.name}`
+          );
+          const normalized = typeof value === "boolean" ? {
+            ok: value
+          } : value;
+          results.push({
+            name: entry.resource.name,
+            ok: normalized.ok === true,
+            durationMs: elapsedMilliseconds(
+              checkStarted
+            ),
+            ...normalized.detail ? {
+              detail: normalized.detail
+            } : {}
+          });
+        } catch (error) {
+          results.push({
+            name: entry.resource.name,
+            ok: false,
+            durationMs: elapsedMilliseconds(
+              checkStarted
+            ),
+            detail: errorMessage(error)
+          });
+        }
+      }
+      return {
+        ok: state === "ready" && results.every(
+          (item) => item.ok
+        ),
+        state,
+        checkedAt: new Date(
+          checkedAtMs
+        ).toISOString(),
+        resources: results
+      };
+    },
+    async diagnostics() {
+      const resources = [];
+      for (const entry of resourceEntries) {
+        let details;
+        let error;
+        if (entry.resource.diagnostics) {
+          try {
+            details = await entry.resource.diagnostics(
+              createContext()
+            );
+          } catch (diagnosticError) {
+            error = errorMessage(
+              diagnosticError
+            );
+          }
+        }
+        resources.push({
+          name: entry.resource.name,
+          lifecycle: {
+            ...entry.status
+          },
+          ...details ? {
+            details
+          } : {},
+          ...error ? {
+            error
+          } : {}
+        });
+      }
+      return {
+        metadata: {
+          ...metadata
+        },
+        state,
+        uptimeSeconds: Math.max(
+          0,
+          (now() - startedAtMs) / 1e3
+        ),
+        resources
+      };
+    },
+    async shutdown(_options = {}) {
+      if (shutdownPromise) {
+        return shutdownPromise;
+      }
+      if (state === "stopped") {
+        return;
+      }
+      shutdownPromise = stopResources();
+      return shutdownPromise;
+    },
+    installSignalHandlers(signalOptions = {}) {
+      const signals = normalizeSignals(
+        signalOptions.signals ?? DEFAULT_SIGNALS
+      );
+      const handlers = /* @__PURE__ */ new Map();
+      for (const signal of signals) {
+        const handler = () => {
+          void runtime.shutdown({
+            reason: signal
+          }).then(
+            () => {
+              if (signalOptions.setExitCode !== false) {
+                process.exitCode = 0;
+              }
+            },
+            () => {
+              process.exitCode = 1;
+            }
+          );
+        };
+        handlers.set(
+          signal,
+          handler
+        );
+        process.on(
+          signal,
+          handler
+        );
+      }
+      return () => {
+        for (const [
+          signal,
+          handler
+        ] of handlers) {
+          process.off(
+            signal,
+            handler
+          );
+        }
+        handlers.clear();
+      };
+    },
+    registerShutdownHook(name = `deployment:${metadata.serviceName}`) {
+      return registerShutdownHook(
+        () => runtime.shutdown({
+          reason: "framework-shutdown"
+        }),
+        {
+          name
+        }
+      );
+    }
+  };
+  for (const resource of options.resources ?? []) {
+    runtime.addResource(resource);
+  }
+  return runtime;
+  async function startResources() {
+    state = "starting";
+    try {
+      for (const entry of resourceEntries) {
+        entry.status = {
+          name: entry.resource.name,
+          state: "starting"
+        };
+        try {
+          await entry.resource.start?.(
+            createContext()
+          );
+          entry.status = {
+            name: entry.resource.name,
+            state: "started",
+            startedAt: new Date(
+              now()
+            ).toISOString()
+          };
+        } catch (error) {
+          entry.status = {
+            name: entry.resource.name,
+            state: "failed",
+            error: errorMessage(error)
+          };
+          throw new Error(
+            `BCP Deployment: resource "${entry.resource.name}" failed to start. ${errorMessage(error)}`
+          );
+        }
+      }
+      state = "ready";
+    } catch (error) {
+      state = "failed";
+      abortController.abort(error);
+      await stopStartedResources(
+        shutdownTimeoutMs
+      );
+      throw error;
+    }
+  }
+  async function stopResources() {
+    state = "draining";
+    if (!abortController.signal.aborted) {
+      abortController.abort(
+        new Error(
+          "BCP Deployment: runtime is shutting down."
+        )
+      );
+    }
+    const failures = await stopStartedResources(
+      shutdownTimeoutMs
+    );
+    state = failures.length > 0 ? "failed" : "stopped";
+    if (failures.length > 0) {
+      throw new AggregateError(
+        failures,
+        "BCP Deployment: one or more resources failed to stop."
+      );
+    }
+  }
+  async function stopStartedResources(timeoutMs) {
+    const failures = [];
+    const deadline = Date.now() + timeoutMs;
+    for (const entry of [...resourceEntries].reverse()) {
+      if (entry.status.state !== "started") {
+        continue;
+      }
+      entry.status = {
+        ...entry.status,
+        state: "stopping"
+      };
+      try {
+        const remaining = Math.max(
+          1,
+          deadline - Date.now()
+        );
+        await withTimeout(
+          Promise.resolve(
+            entry.resource.stop?.(
+              createContext()
+            )
+          ),
+          remaining,
+          `shutdown of ${entry.resource.name}`
+        );
+        entry.status = {
+          ...entry.status,
+          state: "stopped",
+          stoppedAt: new Date(
+            now()
+          ).toISOString()
+        };
+      } catch (error) {
+        const message = errorMessage(error);
+        entry.status = {
+          ...entry.status,
+          state: "failed",
+          error: message
+        };
+        failures.push(
+          new Error(
+            `BCP Deployment: resource "${entry.resource.name}" failed to stop. ${message}`
+          )
+        );
+      }
+    }
+    return failures;
+  }
+  function createContext() {
+    return {
+      metadata,
+      signal: abortController.signal
+    };
+  }
+}
+function normalizeSignals(signals) {
+  return Array.from(
+    new Set(signals)
+  );
+}
+function normalizeName(value, field) {
+  const normalized = String(value ?? "").trim();
+  if (!normalized) {
+    throw new TypeError(
+      `BCP Deployment: ${field} must be a non-empty string.`
+    );
+  }
+  if (normalized.length > 256 || /[\r\n]/.test(normalized)) {
+    throw new TypeError(
+      `BCP Deployment: ${field} must be at most 256 characters without line breaks.`
+    );
+  }
+  return normalized;
+}
+function normalizeOptionalText(value) {
+  if (value === void 0) {
+    return void 0;
+  }
+  const normalized = value.trim();
+  return normalized || void 0;
+}
+function positiveInteger(value, field) {
+  if (!Number.isSafeInteger(value) || value <= 0) {
+    throw new TypeError(
+      `BCP Deployment: ${field} must be a positive safe integer.`
+    );
+  }
+  return value;
+}
+function parseOptionalPositiveInteger(value) {
+  if (value === void 0) {
+    return void 0;
+  }
+  const parsed = Number(value.trim());
+  if (!Number.isSafeInteger(parsed) || parsed <= 0) {
+    throw new TypeError(
+      "BCP Deployment: BCP_SHUTDOWN_TIMEOUT_MS must be a positive safe integer."
+    );
+  }
+  return parsed;
+}
+function assertTimestamp(value, field) {
+  if (!Number.isFinite(value)) {
+    throw new TypeError(
+      `BCP Deployment: ${field} must be a finite number.`
+    );
+  }
+}
+function errorMessage(error) {
+  return error instanceof Error ? error.message : String(error);
+}
+function elapsedMilliseconds(startedAt) {
+  return Math.max(
+    0,
+    performance.now() - startedAt
+  );
+}
+function withTimeout(promise, timeoutMs, label) {
+  return new Promise(
+    (resolve, reject) => {
+      const timer = setTimeout(
+        () => reject(
+          new Error(
+            `BCP Deployment: ${label} timed out after ${timeoutMs}ms.`
+          )
+        ),
+        timeoutMs
+      );
+      timer.unref?.();
+      promise.then(
+        (value) => {
+          clearTimeout(timer);
+          resolve(value);
+        },
+        (error) => {
+          clearTimeout(timer);
+          reject(error);
+        }
+      );
+    }
+  );
+}
+
+// packages/server/src/plugins.ts
+var PluginDependencyError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "PluginDependencyError";
+  }
+};
+var PluginLifecycleError = class extends Error {
+  plugin;
+  phase;
+  cause;
+  constructor(plugin, phase, cause) {
+    super(
+      `BCP Plugins: ${phase} failed for plugin "${plugin}": ${formatError(cause)}`
+    );
+    this.name = "PluginLifecycleError";
+    this.plugin = plugin;
+    this.phase = phase;
+    this.cause = cause;
+  }
+};
+function defineModule(module) {
+  if (!module || typeof module !== "object") {
+    throw new TypeError(
+      "BCP Plugins: module must be an object."
+    );
+  }
+  normalizeName2(
+    module.name,
+    "module name"
+  );
+  if (!Array.isArray(module.plugins)) {
+    throw new TypeError(
+      "BCP Plugins: module plugins must be an array."
+    );
+  }
+  for (const plugin of module.plugins) {
+    validatePluginDefinition(plugin);
+  }
+  return module;
+}
+function createPluginServiceRegistry(initial) {
+  const values = /* @__PURE__ */ new Map();
+  if (initial) {
+    for (const [key, value] of initial) {
+      assertServiceKey(key);
+      if (values.has(key)) {
+        throw new Error(
+          `BCP Plugins: duplicate initial service ${formatServiceKey(key)}.`
+        );
+      }
+      values.set(key, value);
+    }
+  }
+  const registry = {
+    provide(key, value, options = {}) {
+      assertServiceKey(key);
+      if (values.has(key) && !options.replace) {
+        throw new Error(
+          `BCP Plugins: service ${formatServiceKey(key)} is already registered.`
+        );
+      }
+      values.set(key, value);
+    },
+    get(key) {
+      assertServiceKey(key);
+      if (!values.has(key)) {
+        throw new Error(
+          `BCP Plugins: service ${formatServiceKey(key)} is not registered.`
+        );
+      }
+      return values.get(key);
+    },
+    optional(key) {
+      assertServiceKey(key);
+      return values.get(key);
+    },
+    has(key) {
+      assertServiceKey(key);
+      return values.has(key);
+    },
+    delete(key) {
+      assertServiceKey(key);
+      return values.delete(key);
+    },
+    keys() {
+      return [
+        ...values.keys()
+      ];
+    }
+  };
+  return registry;
+}
+function createPluginHookBus() {
+  const hooks = /* @__PURE__ */ new Map();
+  const bus = {
+    on(name, handler) {
+      const normalized = normalizeName2(
+        name,
+        "hook name"
+      );
+      if (typeof handler !== "function") {
+        throw new TypeError(
+          "BCP Plugins: hook handler must be a function."
+        );
+      }
+      let group = hooks.get(normalized);
+      if (!group) {
+        group = /* @__PURE__ */ new Set();
+        hooks.set(
+          normalized,
+          group
+        );
+      }
+      group.add(
+        handler
+      );
+      return () => {
+        group?.delete(
+          handler
+        );
+        if (group?.size === 0) {
+          hooks.delete(normalized);
+        }
+      };
+    },
+    async emit(name, payload) {
+      const normalized = normalizeName2(
+        name,
+        "hook name"
+      );
+      const group = hooks.get(normalized);
+      if (!group) {
+        return;
+      }
+      for (const handler of [
+        ...group
+      ]) {
+        await handler(payload);
+      }
+    },
+    listenerCount(name) {
+      return hooks.get(
+        normalizeName2(
+          name,
+          "hook name"
+        )
+      )?.size ?? 0;
+    },
+    clear(name) {
+      if (name === void 0) {
+        hooks.clear();
+        return;
+      }
+      hooks.delete(
+        normalizeName2(
+          name,
+          "hook name"
+        )
+      );
+    }
+  };
+  return bus;
+}
+function createPluginHost(options = {}) {
+  const now = options.now ?? Date.now;
+  const services = createPluginServiceRegistry(
+    options.services
+  );
+  const hooks = createPluginHookBus();
+  const entries = /* @__PURE__ */ new Map();
+  const configs = {
+    ...options.configs ?? {}
+  };
+  let setupCompleted = false;
+  let started = false;
+  let closed = false;
+  let lifecycleActive = false;
+  let fatalError = null;
+  const host = {
+    services,
+    hooks,
+    get started() {
+      return started;
+    },
+    use(extension) {
+      assertMutable();
+      if (isPluginModule(extension)) {
+        defineModule(extension);
+        for (const plugin of extension.plugins) {
+          register(plugin);
+        }
+        return host;
+      }
+      register(extension);
+      return host;
+    },
+    resolveOrder() {
+      return resolvePluginOrder(
+        entries
+      );
+    },
+    async setup() {
+      assertOpen();
+      assertHealthy();
+      if (setupCompleted) {
+        return;
+      }
+      assertNotActive();
+      lifecycleActive = true;
+      try {
+        const order = resolvePluginOrder(
+          entries
+        );
+        for (const name of order) {
+          const entry = requireInternal(name);
+          if (entry.record.state !== "registered") {
+            continue;
+          }
+          entry.record.state = "setting-up";
+          try {
+            const context = createContext(entry);
+            entry.context = context;
+            await entry.definition.setup?.(
+              context
+            );
+            entry.record.state = "ready";
+            entry.record.setupAt = timestamp();
+          } catch (error) {
+            markFailed(
+              entry,
+              error
+            );
+            const lifecycleError = error instanceof PluginLifecycleError ? error : new PluginLifecycleError(
+              name,
+              "setup",
+              error
+            );
+            fatalError = lifecycleError;
+            await disposePrepared(
+              order,
+              name
+            );
+            throw lifecycleError;
+          }
+        }
+        setupCompleted = true;
+      } finally {
+        lifecycleActive = false;
+      }
+    },
+    async start() {
+      assertOpen();
+      assertHealthy();
+      if (started) {
+        return;
+      }
+      if (!setupCompleted) {
+        await host.setup();
+      }
+      assertHealthy();
+      assertNotActive();
+      lifecycleActive = true;
+      const order = resolvePluginOrder(
+        entries
+      );
+      const startedNames = [];
+      try {
+        for (const name of order) {
+          const entry = requireInternal(name);
+          if (entry.record.state !== "ready" && entry.record.state !== "stopped") {
+            continue;
+          }
+          entry.record.state = "starting";
+          try {
+            await entry.definition.start?.(
+              requireContext(entry)
+            );
+            entry.record.state = "started";
+            entry.record.startedAt = timestamp();
+            entry.record.error = void 0;
+            startedNames.push(name);
+          } catch (error) {
+            markFailed(
+              entry,
+              error
+            );
+            const lifecycleError = new PluginLifecycleError(
+              name,
+              "start",
+              error
+            );
+            fatalError = lifecycleError;
+            await stopNames(
+              [
+                ...startedNames
+              ].reverse()
+            );
+            throw lifecycleError;
+          }
+        }
+        started = true;
+      } finally {
+        lifecycleActive = false;
+      }
+    },
+    async stop() {
+      if (closed || !started) {
+        return;
+      }
+      assertNotActive();
+      lifecycleActive = true;
+      try {
+        const errors = await stopNames(
+          resolvePluginOrder(
+            entries
+          ).reverse()
+        );
+        started = false;
+        if (errors.length > 0) {
+          throw new AggregateError(
+            errors,
+            "BCP Plugins: one or more plugin stop hooks failed."
+          );
+        }
+      } finally {
+        lifecycleActive = false;
+      }
+    },
+    async close() {
+      if (closed) {
+        return;
+      }
+      const errors = [];
+      if (started) {
+        try {
+          await host.stop();
+        } catch (error) {
+          if (error instanceof AggregateError) {
+            errors.push(
+              ...error.errors
+            );
+          } else {
+            errors.push(error);
+          }
+        }
+      }
+      assertNotActive();
+      lifecycleActive = true;
+      try {
+        const order = resolvePluginOrder(
+          entries
+        ).reverse();
+        for (const name of order) {
+          const entry = requireInternal(name);
+          if (entry.disposed || !entry.context) {
+            continue;
+          }
+          try {
+            await entry.definition.dispose?.(
+              entry.context
+            );
+          } catch (error) {
+            errors.push(
+              new PluginLifecycleError(
+                name,
+                "dispose",
+                error
+              )
+            );
+          } finally {
+            entry.disposed = true;
+          }
+        }
+        hooks.clear();
+        closed = true;
+      } finally {
+        lifecycleActive = false;
+      }
+      if (errors.length > 0) {
+        throw new AggregateError(
+          errors,
+          "BCP Plugins: one or more plugin shutdown hooks failed."
+        );
+      }
+    },
+    plugin(name) {
+      const entry = entries.get(
+        normalizeName2(
+          name,
+          "plugin name"
+        )
+      );
+      return entry ? cloneRecord(
+        entry.record
+      ) : null;
+    },
+    plugins() {
+      return [
+        ...entries.values()
+      ].map(
+        (entry) => cloneRecord(
+          entry.record
+        )
+      ).sort(
+        (left, right) => left.registeredAt - right.registeredAt || left.name.localeCompare(
+          right.name
+        )
+      );
+    }
+  };
+  for (const module of options.modules ?? []) {
+    host.use(module);
+  }
+  for (const plugin of options.plugins ?? []) {
+    host.use(plugin);
+  }
+  return host;
+  function register(definition) {
+    validatePluginDefinition(
+      definition
+    );
+    const name = normalizeName2(
+      definition.name,
+      "plugin name"
+    );
+    if (entries.has(name)) {
+      throw new Error(
+        `BCP Plugins: plugin "${name}" is already registered.`
+      );
+    }
+    const requires = normalizeDependencyList(
+      definition.requires,
+      name,
+      "requires"
+    );
+    const optional = normalizeDependencyList(
+      definition.optional,
+      name,
+      "optional"
+    );
+    entries.set(
+      name,
+      {
+        definition: {
+          ...definition,
+          name,
+          requires,
+          optional
+        },
+        record: {
+          name,
+          version: normalizeOptionalVersion(
+            definition.version
+          ),
+          state: "registered",
+          requires,
+          optional,
+          registeredAt: timestamp()
+        },
+        disposed: false
+      }
+    );
+  }
+  function createContext(entry) {
+    const rawConfig = Object.prototype.hasOwnProperty.call(
+      configs,
+      entry.record.name
+    ) ? configs[entry.record.name] : entry.definition.config;
+    const config = parseConfig(
+      entry.definition.schema,
+      rawConfig,
+      entry.record.name
+    );
+    return {
+      name: entry.record.name,
+      config,
+      services,
+      hooks,
+      host
+    };
+  }
+  async function stopNames(names) {
+    const errors = [];
+    for (const name of names) {
+      const entry = requireInternal(name);
+      if (entry.record.state !== "started") {
+        continue;
+      }
+      entry.record.state = "stopping";
+      try {
+        await entry.definition.stop?.(
+          requireContext(entry)
+        );
+        entry.record.state = "stopped";
+        entry.record.stoppedAt = timestamp();
+      } catch (error) {
+        markFailed(
+          entry,
+          error
+        );
+        errors.push(
+          new PluginLifecycleError(
+            name,
+            "stop",
+            error
+          )
+        );
+      }
+    }
+    return errors;
+  }
+  async function disposePrepared(order, failedName) {
+    const index = order.indexOf(failedName);
+    const names = order.slice(
+      0,
+      Math.max(0, index) + 1
+    ).reverse();
+    for (const name of names) {
+      const entry = requireInternal(name);
+      if (entry.disposed || !entry.context) {
+        continue;
+      }
+      try {
+        await entry.definition.dispose?.(
+          entry.context
+        );
+      } catch {
+      } finally {
+        entry.disposed = true;
+      }
+    }
+  }
+  function requireInternal(name) {
+    const entry = entries.get(name);
+    if (!entry) {
+      throw new Error(
+        `BCP Plugins: plugin "${name}" is not registered.`
+      );
+    }
+    return entry;
+  }
+  function timestamp() {
+    const value = now();
+    if (!Number.isFinite(value)) {
+      throw new TypeError(
+        "BCP Plugins: now() must return a finite number."
+      );
+    }
+    return value;
+  }
+  function assertOpen() {
+    if (closed) {
+      throw new Error(
+        "BCP Plugins: plugin host is closed."
+      );
+    }
+  }
+  function assertHealthy() {
+    if (fatalError) {
+      throw fatalError;
+    }
+  }
+  function assertMutable() {
+    assertOpen();
+    if (setupCompleted || lifecycleActive || fatalError) {
+      throw new Error(
+        "BCP Plugins: plugins cannot be registered after setup begins or after a lifecycle failure."
+      );
+    }
+  }
+  function assertNotActive() {
+    if (lifecycleActive) {
+      throw new Error(
+        "BCP Plugins: another lifecycle transition is already running."
+      );
+    }
+  }
+}
+function resolvePluginOrder(entries) {
+  for (const entry of entries.values()) {
+    for (const dependency of entry.record.requires) {
+      if (!entries.has(dependency)) {
+        throw new PluginDependencyError(
+          `BCP Plugins: plugin "${entry.record.name}" requires missing plugin "${dependency}".`
+        );
+      }
+    }
+  }
+  const visiting = /* @__PURE__ */ new Set();
+  const visited = /* @__PURE__ */ new Set();
+  const order = [];
+  const stack = [];
+  const visit = (name) => {
+    if (visited.has(name)) {
+      return;
+    }
+    if (visiting.has(name)) {
+      const start = stack.indexOf(name);
+      const cycle = [
+        ...stack.slice(
+          Math.max(0, start)
+        ),
+        name
+      ];
+      throw new PluginDependencyError(
+        `BCP Plugins: dependency cycle detected: ${cycle.join(" -> ")}.`
+      );
+    }
+    const entry = entries.get(name);
+    if (!entry) {
+      return;
+    }
+    visiting.add(name);
+    stack.push(name);
+    for (const dependency of [
+      ...entry.record.requires,
+      ...entry.record.optional.filter(
+        (candidate) => entries.has(candidate)
+      )
+    ]) {
+      visit(dependency);
+    }
+    stack.pop();
+    visiting.delete(name);
+    visited.add(name);
+    order.push(name);
+  };
+  for (const name of entries.keys()) {
+    visit(name);
+  }
+  return order;
+}
+function validatePluginDefinition(definition) {
+  if (!definition || typeof definition !== "object") {
+    throw new TypeError(
+      "BCP Plugins: plugin definition must be an object."
+    );
+  }
+  const name = normalizeName2(
+    definition.name,
+    "plugin name"
+  );
+  normalizeDependencyList(
+    definition.requires,
+    name,
+    "requires"
+  );
+  normalizeDependencyList(
+    definition.optional,
+    name,
+    "optional"
+  );
+  for (const hook of [
+    "setup",
+    "start",
+    "stop",
+    "dispose"
+  ]) {
+    const value = definition[hook];
+    if (value !== void 0 && typeof value !== "function") {
+      throw new TypeError(
+        `BCP Plugins: plugin "${name}" ${hook} must be a function.`
+      );
+    }
+  }
+  if (definition.schema !== void 0 && typeof definition.schema !== "function" && (!definition.schema || typeof definition.schema.parse !== "function")) {
+    throw new TypeError(
+      `BCP Plugins: plugin "${name}" schema must be a parser function or object with parse().`
+    );
+  }
+}
+function normalizeDependencyList(value, plugin, field) {
+  if (value === void 0) {
+    return [];
+  }
+  if (!Array.isArray(value)) {
+    throw new TypeError(
+      `BCP Plugins: plugin "${plugin}" ${field} must be an array.`
+    );
+  }
+  const normalized = value.map(
+    (item) => normalizeName2(
+      item,
+      `${field} dependency`
+    )
+  );
+  if (new Set(normalized).size !== normalized.length) {
+    throw new Error(
+      `BCP Plugins: plugin "${plugin}" ${field} contains duplicate dependencies.`
+    );
+  }
+  if (normalized.includes(plugin)) {
+    throw new PluginDependencyError(
+      `BCP Plugins: plugin "${plugin}" cannot depend on itself.`
+    );
+  }
+  return normalized;
+}
+function parseConfig(parser, raw, plugin) {
+  if (!parser) {
+    return raw;
+  }
+  try {
+    return typeof parser === "function" ? parser(raw) : parser.parse(raw);
+  } catch (error) {
+    throw new PluginLifecycleError(
+      plugin,
+      "config",
+      error
+    );
+  }
+}
+function requireContext(entry) {
+  if (!entry.context) {
+    throw new Error(
+      `BCP Plugins: plugin "${entry.record.name}" has not been set up.`
+    );
+  }
+  return entry.context;
+}
+function markFailed(entry, error) {
+  entry.record.state = "failed";
+  entry.record.error = formatError(error);
+}
+function cloneRecord(record) {
+  return {
+    ...record,
+    requires: [
+      ...record.requires
+    ],
+    optional: [
+      ...record.optional
+    ]
+  };
+}
+function isPluginModule(value) {
+  return Boolean(
+    value && typeof value === "object" && Array.isArray(
+      value.plugins
+    )
+  );
+}
+function normalizeName2(value, field) {
+  const text = String(value ?? "").trim();
+  if (!text) {
+    throw new TypeError(
+      `BCP Plugins: ${field} must be a non-empty string.`
+    );
+  }
+  if (text.length > 200) {
+    throw new TypeError(
+      `BCP Plugins: ${field} must not exceed 200 characters.`
+    );
+  }
+  return text;
+}
+function normalizeOptionalVersion(value) {
+  if (value === void 0) {
+    return void 0;
+  }
+  return normalizeName2(
+    value,
+    "plugin version"
+  );
+}
+function assertServiceKey(key) {
+  if (typeof key === "string") {
+    normalizeName2(
+      key,
+      "service key"
+    );
+    return;
+  }
+  if (typeof key !== "symbol") {
+    throw new TypeError(
+      "BCP Plugins: service key must be a string or symbol."
+    );
+  }
+}
+function formatServiceKey(key) {
+  return typeof key === "symbol" ? String(key) : `"${key}"`;
+}
+function formatError(error) {
+  if (error instanceof Error) {
+    return error.message || error.name;
+  }
+  if (typeof error === "string") {
+    return error;
+  }
+  try {
+    return JSON.stringify(error) ?? String(error);
+  } catch {
+    return String(error);
+  }
+}
+
+// packages/server/src/application.ts
+var DEFAULT_APPLICATION_SIGNALS = [
+  "SIGTERM",
+  "SIGINT"
+];
+var ApplicationLifecycleError = class extends Error {
+  phase;
+  cause;
+  constructor(phase, cause) {
+    super(
+      `BCP Application: ${phase} failed: ${formatError2(cause)}`
+    );
+    this.name = "ApplicationLifecycleError";
+    this.phase = phase;
+    this.cause = cause;
+  }
+};
+function defineApp(definition) {
+  validateDefinition(definition);
+  return definition;
+}
+function createApp(definition) {
+  defineApp(definition);
+  const name = normalizeName3(
+    definition.name,
+    "application name"
+  );
+  const version = normalizeOptionalText2(
+    definition.version
+  );
+  const config = parseConfig2(
+    definition.schema,
+    definition.config
+  );
+  const plugins = createPluginHost({
+    plugins: definition.plugins,
+    modules: definition.modules,
+    configs: definition.pluginConfigs,
+    services: definition.services
+  });
+  const deployment = createDeploymentRuntime({
+    ...definition.deployment ?? {},
+    serviceName: name,
+    ...version ? {
+      version
+    } : {}
+  });
+  let state = "created";
+  let startPromise = null;
+  let stopPromise = null;
+  let setupCompleted = false;
+  let applicationResourceRegistered = false;
+  let disposed = false;
+  let failure = null;
+  const context = {
+    name,
+    ...version ? {
+      version
+    } : {},
+    config,
+    services: plugins.services,
+    hooks: plugins.hooks,
+    plugins,
+    deployment,
+    get metadata() {
+      return deployment.metadata;
+    },
+    get state() {
+      return state;
+    }
+  };
+  deployment.addResource({
+    name: "bcp:plugins",
+    async start() {
+      await plugins.start();
+    },
+    ready() {
+      return {
+        ok: plugins.started,
+        detail: plugins.started ? "Plugin host started." : "Plugin host is not started."
+      };
+    },
+    async stop() {
+      await plugins.close();
+    },
+    diagnostics() {
+      return {
+        started: plugins.started,
+        plugins: plugins.plugins()
+      };
+    }
+  });
+  for (const resource of definition.resources ?? []) {
+    deployment.addResource(resource);
+  }
+  const app = {
+    name,
+    ...version ? {
+      version
+    } : {},
+    config,
+    context,
+    services: plugins.services,
+    hooks: plugins.hooks,
+    plugins,
+    deployment,
+    get state() {
+      return state;
+    },
+    use(extension) {
+      assertMutable();
+      plugins.use(extension);
+      return app;
+    },
+    provide(key, value, options = {}) {
+      assertMutable();
+      plugins.services.provide(
+        key,
+        value,
+        options
+      );
+      return app;
+    },
+    addResource(resource) {
+      assertMutable();
+      deployment.addResource(
+        resource
+      );
+      return app;
+    },
+    async start() {
+      if (state === "ready") {
+        return;
+      }
+      if (state === "starting") {
+        if (!startPromise) {
+          throw new Error(
+            "BCP Application: startup promise is unavailable while starting."
+          );
+        }
+        return startPromise;
+      }
+      if (state === "stopping") {
+        throw new Error(
+          "BCP Application: application cannot start while stopping."
+        );
+      }
+      if (state === "stopped") {
+        throw new Error(
+          "BCP Application: a stopped application cannot be started again."
+        );
+      }
+      if (state === "failed") {
+        throw failure ?? new Error(
+          "BCP Application: failed application cannot be started again."
+        );
+      }
+      state = "starting";
+      startPromise = startApplication();
+      return startPromise;
+    },
+    stop(options = {}) {
+      return shutdownApplication(
+        options
+      );
+    },
+    shutdown(options = {}) {
+      return shutdownApplication(
+        options
+      );
+    },
+    close(options = {}) {
+      return shutdownApplication(
+        options
+      );
+    },
+    readiness() {
+      return deployment.readiness();
+    },
+    diagnostics() {
+      return deployment.diagnostics();
+    },
+    installSignalHandlers(signalOptions = {}) {
+      const signals = Array.from(
+        new Set(
+          signalOptions.signals ?? DEFAULT_APPLICATION_SIGNALS
+        )
+      );
+      const handlers = /* @__PURE__ */ new Map();
+      for (const signal of signals) {
+        const handler = () => {
+          void app.shutdown({
+            reason: signal
+          }).then(
+            () => {
+              if (signalOptions.setExitCode !== false) {
+                process.exitCode = 0;
+              }
+            },
+            () => {
+              process.exitCode = 1;
+            }
+          );
+        };
+        handlers.set(
+          signal,
+          handler
+        );
+        process.on(
+          signal,
+          handler
+        );
+      }
+      return () => {
+        for (const [
+          signal,
+          handler
+        ] of handlers) {
+          process.off(
+            signal,
+            handler
+          );
+        }
+        handlers.clear();
+      };
+    },
+    registerShutdownHook(hookName) {
+      return registerShutdownHook(
+        () => app.shutdown({
+          reason: "framework-shutdown"
+        }),
+        {
+          name: hookName ?? `application:${name}`
+        }
+      );
+    }
+  };
+  return app;
+  async function startApplication() {
+    try {
+      if (!setupCompleted) {
+        await runHook(
+          "setup",
+          definition.setup
+        );
+        setupCompleted = true;
+      }
+      registerApplicationResource();
+      await deployment.start();
+      state = "ready";
+      failure = null;
+    } catch (error) {
+      const lifecycleError = error instanceof ApplicationLifecycleError ? error : new ApplicationLifecycleError(
+        "start",
+        error
+      );
+      failure = lifecycleError;
+      state = "failed";
+      await cleanupAfterFailure();
+      throw lifecycleError;
+    } finally {
+      startPromise = null;
+    }
+  }
+  async function shutdownApplication(options) {
+    if (state === "stopped") {
+      return;
+    }
+    if (state === "stopping") {
+      return stopPromise ?? Promise.resolve();
+    }
+    if (state === "starting") {
+      try {
+        await startPromise;
+      } catch {
+      }
+    }
+    state = "stopping";
+    stopPromise = stopApplication(options);
+    return stopPromise;
+  }
+  async function stopApplication(options) {
+    const errors = [];
+    try {
+      if (deployment.state !== "idle" && deployment.state !== "stopped") {
+        try {
+          await deployment.shutdown(
+            options
+          );
+        } catch (error) {
+          errors.push(error);
+        }
+      } else {
+        try {
+          await plugins.close();
+        } catch (error) {
+          errors.push(error);
+        }
+      }
+      try {
+        await disposeApplication();
+      } catch (error) {
+        errors.push(error);
+      }
+      state = "stopped";
+    } finally {
+      stopPromise = null;
+    }
+    if (errors.length > 0) {
+      throw new AggregateError(
+        errors,
+        "BCP Application: one or more shutdown operations failed."
+      );
+    }
+  }
+  function registerApplicationResource() {
+    if (applicationResourceRegistered) {
+      return;
+    }
+    deployment.addResource({
+      name: "bcp:application",
+      async start() {
+        await runHook(
+          "start",
+          definition.start
+        );
+      },
+      ready() {
+        return true;
+      },
+      async stop() {
+        await runHook(
+          "stop",
+          definition.stop
+        );
+      },
+      diagnostics() {
+        return {
+          name,
+          ...version ? {
+            version
+          } : {},
+          state,
+          services: plugins.services.keys().map(
+            formatServiceKey2
+          ),
+          pluginCount: plugins.plugins().length
+        };
+      }
+    });
+    applicationResourceRegistered = true;
+  }
+  async function cleanupAfterFailure() {
+    if (deployment.state !== "idle" && deployment.state !== "stopped") {
+      try {
+        await deployment.shutdown({
+          reason: "application-start-failed"
+        });
+      } catch {
+      }
+    }
+    try {
+      await plugins.close();
+    } catch {
+    }
+    try {
+      await disposeApplication();
+    } catch {
+    }
+  }
+  async function disposeApplication() {
+    if (disposed) {
+      return;
+    }
+    disposed = true;
+    await runHook(
+      "dispose",
+      definition.dispose
+    );
+  }
+  async function runHook(phase, hook) {
+    if (!hook) {
+      return;
+    }
+    try {
+      await hook(context);
+    } catch (error) {
+      throw new ApplicationLifecycleError(
+        phase,
+        error
+      );
+    }
+  }
+  function assertMutable() {
+    if (state !== "created") {
+      throw new Error(
+        "BCP Application: plugins, services and resources must be registered before start()."
+      );
+    }
+  }
+}
+function parseConfig2(parser, value) {
+  if (!parser) {
+    return value;
+  }
+  if (typeof parser === "function") {
+    return parser(value);
+  }
+  if (parser && typeof parser === "object" && typeof parser.parse === "function") {
+    return parser.parse(value);
+  }
+  throw new TypeError(
+    "BCP Application: config schema must be a function or an object with parse()."
+  );
+}
+function validateDefinition(definition) {
+  if (!definition || typeof definition !== "object") {
+    throw new TypeError(
+      "BCP Application: definition must be an object."
+    );
+  }
+  normalizeName3(
+    definition.name,
+    "application name"
+  );
+  normalizeOptionalText2(
+    definition.version
+  );
+  if (definition.plugins !== void 0 && !Array.isArray(definition.plugins)) {
+    throw new TypeError(
+      "BCP Application: plugins must be an array."
+    );
+  }
+  if (definition.modules !== void 0 && !Array.isArray(definition.modules)) {
+    throw new TypeError(
+      "BCP Application: modules must be an array."
+    );
+  }
+  if (definition.resources !== void 0 && !Array.isArray(definition.resources)) {
+    throw new TypeError(
+      "BCP Application: resources must be an array."
+    );
+  }
+  for (const [phase, hook] of [
+    ["setup", definition.setup],
+    ["start", definition.start],
+    ["stop", definition.stop],
+    ["dispose", definition.dispose]
+  ]) {
+    if (hook !== void 0 && typeof hook !== "function") {
+      throw new TypeError(
+        `BCP Application: ${phase} must be a function.`
+      );
+    }
+  }
+}
+function normalizeName3(value, label) {
+  if (typeof value !== "string") {
+    throw new TypeError(
+      `BCP Application: ${label} must be a string.`
+    );
+  }
+  const normalized = value.trim();
+  if (!normalized) {
+    throw new TypeError(
+      `BCP Application: ${label} cannot be empty.`
+    );
+  }
+  return normalized;
+}
+function normalizeOptionalText2(value) {
+  if (value === void 0) {
+    return void 0;
+  }
+  if (typeof value !== "string") {
+    throw new TypeError(
+      "BCP Application: optional text values must be strings."
+    );
+  }
+  return value.trim() || void 0;
+}
+function formatServiceKey2(key) {
+  return typeof key === "symbol" ? key.description ? `Symbol(${key.description})` : key.toString() : key;
+}
+function formatError2(value) {
+  if (value instanceof Error) {
+    return value.message;
+  }
+  return String(value);
+}
+export {
+  ApplicationLifecycleError,
+  createApp,
+  defineApp
+};