@kb-labs/shared-daemon 2.96.0

package/README.md

@@ -0,0 +1,48 @@
+# @kb-labs/shared-daemon
+
+Universal process-lifecycle bootstrapper for KB Labs daemon services.
+
+`runDaemon()` owns the boilerplate every daemon repeats — repo-root
+resolution, `.env` loading, platform bootstrap, port/host resolution from
+env, and graceful `SIGTERM`/`SIGINT` shutdown — so each service only writes
+its own `setup()`.
+
+## Usage
+
+```ts
+import { runDaemon } from '@kb-labs/shared-daemon';
+import { createServiceBootstrap } from '@kb-labs/core-runtime';
+import { makeAssemblyHook } from '@kb-labs/plugin-runtime';
+import { getListenOptions } from '@kb-labs/shared-http';
+
+await runDaemon(
+  {
+    appId: 'my-service',
+    defaultPort: 5070,
+    portEnvVar: 'MY_SERVICE_PORT',
+    hostEnvVar: 'MY_SERVICE_HOST',
+    async setup({ platform, port, host, repoRoot }) {
+      const server = await createServer({ platform, repoRoot });
+      await server.listen(getListenOptions(port, host));
+      return () => server.close(); // teardown — runs before platform.shutdown()
+    },
+  },
+  // DI: keeps makeAssemblyHook (Layer 1) out of this package
+  (appId, repoRoot) =>
+    createServiceBootstrap({ appId, repoRoot, assemblyHook: makeAssemblyHook() }),
+);
+```
+
+## What it handles
+
+- **Env + platform** — resolves `repoRoot` via `findRepoRoot`, loads `.env`,
+  bootstraps the platform through the injected factory.
+- **Socket isolation** — seeds `KB_SOCKET_HASH` (from `KB_PROJECT_ROOT ?? repoRoot`)
+  before config interpolation so `${KB_SOCKET_HASH}` socket paths resolve, matching
+  kb-dev's per-project hash.
+- **Port/host** — read from the configured env vars with defaults.
+- **Shutdown** — a single re-entrant handler runs `setup()`'s teardown, then
+  `platform.shutdown()`, then exits; a second signal is ignored.
+
+Pairs with `createDaemonServer()` from `@kb-labs/shared-http`, which owns the
+HTTP-layer boilerplate (Fastify, request correlation, observability routes).

package/dist/index.d.ts

@@ -0,0 +1,47 @@
+import { PlatformContainer } from '@kb-labs/core-runtime';
+import { ILogger } from '@kb-labs/core-platform';
+
+interface DaemonContext {
+    platform: PlatformContainer;
+    logger: ILogger;
+    port: number;
+    host: string;
+    /**
+     * Repository root resolved via findRepoRoot(process.cwd()). Services should
+     * use this (not process.cwd()) for plugin/workflow discovery so they behave
+     * correctly when launched from a subdirectory.
+     */
+    repoRoot: string;
+}
+interface DaemonConfig {
+    appId: string;
+    /**
+     * serviceId in the transport map (declarative network). Defaults to appId.
+     * Set explicitly when they differ. The daemon binds the port the transport
+     * publishes for this serviceId — keeping bind and route consistent (incl.
+     * any KB_NET_OFFSET shift).
+     */
+    serviceId?: string;
+    defaultPort: number;
+    portEnvVar: string;
+    defaultHost?: string;
+    hostEnvVar?: string;
+    /**
+     * Called after platform is ready. Returns a teardown callback.
+     * The callback is invoked before platform.shutdown() on SIGTERM/SIGINT.
+     */
+    setup(ctx: DaemonContext): Promise<() => Promise<void>>;
+}
+/**
+ * Universal process-lifecycle runner for KB Labs daemon services.
+ *
+ * Handles: env loading, platform init, port/host resolution,
+ * setup invocation, and graceful SIGTERM/SIGINT shutdown.
+ *
+ * @param config - Service-specific configuration
+ * @param platformBootstrap - DI factory for platform (keeps makeAssemblyHook out of this package)
+ *   Example: (appId, repoRoot) => createServiceBootstrap({ appId, repoRoot, assemblyHook: makeAssemblyHook() })
+ */
+declare function runDaemon(config: DaemonConfig, platformBootstrap: (appId: string, repoRoot: string) => Promise<PlatformContainer>): Promise<void>;
+
+export { type DaemonConfig, type DaemonContext, runDaemon };

package/dist/index.js

@@ -0,0 +1,49 @@
+import { createHash } from 'crypto';
+import { findRepoRoot } from '@kb-labs/core-sys';
+import { loadEnvFromRoot } from '@kb-labs/core-runtime';
+
+// src/daemon.ts
+async function runDaemon(config, platformBootstrap) {
+  const repoRoot = await findRepoRoot(process.cwd());
+  loadEnvFromRoot(repoRoot);
+  if (!process.env.KB_SOCKET_HASH) {
+    const hashRoot = process.env.KB_PROJECT_ROOT ?? repoRoot;
+    process.env.KB_SOCKET_HASH = createHash("md5").update(hashRoot).digest("hex").slice(0, 8);
+  }
+  const platform = await platformBootstrap(config.appId, repoRoot);
+  const logger = platform.logger.child({
+    serviceId: config.appId,
+    service: "bootstrap"
+  });
+  const serviceId = config.serviceId ?? config.appId;
+  const transport = platform.getAdapter("serviceTransport");
+  const addr = transport?.listenAddress?.(serviceId);
+  const netOffset = Number(process.env.KB_NET_OFFSET) || 0;
+  const port = addr && "port" in addr ? addr.port : (process.env[config.portEnvVar] ? parseInt(process.env[config.portEnvVar], 10) : config.defaultPort) + netOffset;
+  const addrHost = addr && "host" in addr ? addr.host : void 0;
+  const host = config.hostEnvVar && process.env[config.hostEnvVar] ? process.env[config.hostEnvVar] : addrHost ?? config.defaultHost ?? "0.0.0.0";
+  logger.info(`${config.appId}: starting`, { port, host });
+  const teardown = await config.setup({ platform, logger, port, host, repoRoot });
+  let shuttingDown = false;
+  const shutdown = async (signal) => {
+    if (shuttingDown) {
+      return;
+    }
+    shuttingDown = true;
+    logger.warn(`${config.appId}: received ${signal}`);
+    await teardown();
+    await platform.shutdown();
+    logger.info(`${config.appId}: stopped`);
+    process.exit(0);
+  };
+  process.on("SIGTERM", async () => {
+    await shutdown("SIGTERM");
+  });
+  process.on("SIGINT", async () => {
+    await shutdown("SIGINT");
+  });
+}
+
+export { runDaemon };
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/daemon.ts"],"names":[],"mappings":"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","file":"index.js","sourcesContent":["import { createHash } from 'node:crypto';\nimport { findRepoRoot } from '@kb-labs/core-sys';\nimport { loadEnvFromRoot } from '@kb-labs/core-runtime';\nimport type { PlatformContainer } from '@kb-labs/core-runtime';\nimport type { ILogger, IServiceTransport } from '@kb-labs/core-platform';\n\nexport interface DaemonContext {\n  platform: PlatformContainer;\n  logger: ILogger;\n  port: number;\n  host: string;\n  /**\n   * Repository root resolved via findRepoRoot(process.cwd()). Services should\n   * use this (not process.cwd()) for plugin/workflow discovery so they behave\n   * correctly when launched from a subdirectory.\n   */\n  repoRoot: string;\n}\n\nexport interface DaemonConfig {\n  appId: string;\n  /**\n   * serviceId in the transport map (declarative network). Defaults to appId.\n   * Set explicitly when they differ. The daemon binds the port the transport\n   * publishes for this serviceId — keeping bind and route consistent (incl.\n   * any KB_NET_OFFSET shift).\n   */\n  serviceId?: string;\n  defaultPort: number;\n  portEnvVar: string;\n  defaultHost?: string;\n  hostEnvVar?: string;\n  /**\n   * Called after platform is ready. Returns a teardown callback.\n   * The callback is invoked before platform.shutdown() on SIGTERM/SIGINT.\n   */\n  setup(ctx: DaemonContext): Promise<() => Promise<void>>;\n}\n\n/**\n * Universal process-lifecycle runner for KB Labs daemon services.\n *\n * Handles: env loading, platform init, port/host resolution,\n * setup invocation, and graceful SIGTERM/SIGINT shutdown.\n *\n * @param config - Service-specific configuration\n * @param platformBootstrap - DI factory for platform (keeps makeAssemblyHook out of this package)\n *   Example: (appId, repoRoot) => createServiceBootstrap({ appId, repoRoot, assemblyHook: makeAssemblyHook() })\n */\nexport async function runDaemon(\n  config: DaemonConfig,\n  platformBootstrap: (appId: string, repoRoot: string) => Promise<PlatformContainer>,\n): Promise<void> {\n  const repoRoot = await findRepoRoot(process.cwd());\n  loadEnvFromRoot(repoRoot);\n\n  // Ensure KB_SOCKET_HASH is set before interpolateConfig() runs inside platformBootstrap.\n  // kb-dev sets it via spawnEnv() for all managed services (including gateway, rest-api).\n  // For manual starts (dev scripts, local testing), derive it the same way kb-dev does —\n  // from the project dir (KB_PROJECT_ROOT), falling back to repoRoot — so a manually\n  // started service lands in the same /tmp/kb-<hash>/ dir as kb-dev-managed peers.\n  if (!process.env.KB_SOCKET_HASH) {\n    const hashRoot = process.env.KB_PROJECT_ROOT ?? repoRoot;\n    process.env.KB_SOCKET_HASH = createHash('md5').update(hashRoot).digest('hex').slice(0, 8);\n  }\n\n  const platform = await platformBootstrap(config.appId, repoRoot);\n  const logger = platform.logger.child({\n    serviceId: config.appId,\n    service: 'bootstrap',\n  });\n\n  // Bind port from the transport (the single declarative network source): the\n  // daemon listens on exactly the port the transport publishes for its\n  // serviceId, so bind and route stay consistent — including any KB_NET_OFFSET\n  // shift. Socket services resolve their bind via KB_SOCKET_PATH (setup →\n  // getListenOptions), so listenAddress returns socketPath and we keep the\n  // fallback port. Services NOT in the transport map (e.g. state-daemon — not\n  // gateway-routed) are treated as edges: the fallback applies KB_NET_OFFSET\n  // directly, so the one offset knob still shifts their bind. Host stays the\n  // daemon's own concern (offset never affects host).\n  const serviceId = config.serviceId ?? config.appId;\n  const transport = platform.getAdapter<IServiceTransport>('serviceTransport');\n  const addr = transport?.listenAddress?.(serviceId);\n  const netOffset = Number(process.env.KB_NET_OFFSET) || 0;\n  const port = addr && 'port' in addr\n    ? addr.port\n    : (process.env[config.portEnvVar]\n        ? parseInt(process.env[config.portEnvVar]!, 10)\n        : config.defaultPort) + netOffset;\n\n  // Host precedence: explicit env override > transport's advisory host (set only\n  // by adapters that own the bind host, e.g. k8s) > daemon default.\n  const addrHost = addr && 'host' in addr ? addr.host : undefined;\n  const host = (config.hostEnvVar && process.env[config.hostEnvVar])\n    ? process.env[config.hostEnvVar]!\n    : (addrHost ?? config.defaultHost ?? '0.0.0.0');\n\n  logger.info(`${config.appId}: starting`, { port, host } as Record<string, unknown>);\n\n  const teardown = await config.setup({ platform, logger, port, host, repoRoot });\n\n  // Guard against a second signal (e.g. SIGTERM then Ctrl-C) re-running teardown\n  // against already-closed resources.\n  let shuttingDown = false;\n  const shutdown = async (signal: string) => {\n    if (shuttingDown) {\n      return;\n    }\n    shuttingDown = true;\n    logger.warn(`${config.appId}: received ${signal}`);\n    await teardown();\n    await platform.shutdown();\n    logger.info(`${config.appId}: stopped`);\n    process.exit(0);\n  };\n\n  process.on('SIGTERM', async () => { await shutdown('SIGTERM'); });\n  process.on('SIGINT', async () => { await shutdown('SIGINT'); });\n}\n"]}

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "@kb-labs/shared-daemon",
+  "description": "Universal process-lifecycle bootstrapper for KB Labs daemon services",
+  "version": "2.96.0",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "dependencies": {
+    "@kb-labs/core-platform": "2.96.0",
+    "@kb-labs/core-runtime": "2.96.0",
+    "@kb-labs/core-sys": "2.96.0"
+  },
+  "devDependencies": {
+    "@types/node": "^24.3.3",
+    "rimraf": "^6.0.1",
+    "tsup": "^8.5.0",
+    "typescript": "^5.6.3",
+    "vitest": "^3.2.6",
+    "@kb-labs/devkit": "2.96.0"
+  },
+  "engines": {
+    "node": ">=20.0.0",
+    "pnpm": ">=9.0.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "sideEffects": false,
+  "scripts": {
+    "build": "tsup --config tsup.config.ts",
+    "clean": "rimraf dist",
+    "dev": "tsup --config tsup.config.ts --watch",
+    "lint": "eslint src",
+    "lint:fix": "eslint src --fix",
+    "test": "vitest run --passWithNoTests",
+    "test:watch": "vitest",
+    "type-check": "tsc --noEmit"
+  }
+}