@outfitter/daemon 0.2.0 → 0.2.2

package/dist/errors.d.ts

@@ -0,0 +1,2 @@
+import { ConnectionRefusedError, ConnectionTimeoutError, DaemonConnectionError, LockError, ProtocolError, StaleSocketError } from "./shared/@outfitter/daemon-8tpctdgw";
+export { StaleSocketError, ProtocolError, LockError, DaemonConnectionError, ConnectionTimeoutError, ConnectionRefusedError };

package/dist/errors.js

@@ -0,0 +1,15 @@
+// @bun
+import {
+  ConnectionRefusedError,
+  ConnectionTimeoutError,
+  LockError,
+  ProtocolError,
+  StaleSocketError
+} from "./shared/@outfitter/daemon-qqn2jpsg.js";
+export {
+  StaleSocketError,
+  ProtocolError,
+  LockError,
+  ConnectionTimeoutError,
+  ConnectionRefusedError
+};

package/dist/health.d.ts

@@ -0,0 +1,2 @@
+import { HealthCheck, HealthCheckResult, HealthChecker, HealthStatus, createHealthChecker } from "./shared/@outfitter/daemon-3qezw7hc";
+export { createHealthChecker, HealthStatus, HealthChecker, HealthCheckResult, HealthCheck };

package/dist/health.js

@@ -0,0 +1,7 @@
+// @bun
+import {
+  createHealthChecker
+} from "./shared/@outfitter/daemon-c1zbfqq5.js";
+export {
+  createHealthChecker
+};

package/dist/ipc.d.ts

@@ -0,0 +1,2 @@
+import { IpcClient, IpcMessageHandler, IpcServer, createIpcClient, createIpcServer } from "./shared/@outfitter/daemon-6efpehdg";
+export { createIpcServer, createIpcClient, IpcServer, IpcMessageHandler, IpcClient };

package/dist/ipc.js

@@ -0,0 +1,9 @@
+// @bun
+import {
+  createIpcClient,
+  createIpcServer
+} from "./shared/@outfitter/daemon-cy5wntm2.js";
+export {
+  createIpcServer,
+  createIpcClient
+};

package/dist/lifecycle.d.ts

@@ -0,0 +1,3 @@
+import { createDaemon } from "./shared/@outfitter/daemon-bd6kcdnj";
+import "./shared/@outfitter/daemon-9w2ey87r";
+export { createDaemon };

package/dist/lifecycle.js

@@ -0,0 +1,8 @@
+// @bun
+import {
+  createDaemon
+} from "./shared/@outfitter/daemon-3j14csts.js";
+import"./shared/@outfitter/daemon-dzt3fqvp.js";
+export {
+  createDaemon
+};

package/dist/locking.d.ts

@@ -0,0 +1,3 @@
+import { LockHandle, acquireDaemonLock, isDaemonAlive, isProcessAlive, readLockPid, releaseDaemonLock } from "./shared/@outfitter/daemon-h536nv4k";
+import "./shared/@outfitter/daemon-8tpctdgw";
+export { releaseDaemonLock, readLockPid, isProcessAlive, isDaemonAlive, acquireDaemonLock, LockHandle };

package/dist/locking.js

@@ -0,0 +1,16 @@
+// @bun
+import {
+  acquireDaemonLock,
+  isDaemonAlive,
+  isProcessAlive,
+  readLockPid,
+  releaseDaemonLock
+} from "./shared/@outfitter/daemon-906e24jc.js";
+import"./shared/@outfitter/daemon-qqn2jpsg.js";
+export {
+  releaseDaemonLock,
+  readLockPid,
+  isProcessAlive,
+  isDaemonAlive,
+  acquireDaemonLock
+};

package/dist/platform.d.ts

@@ -0,0 +1,2 @@
+import { getDaemonDir, getLockPath, getPidPath, getSocketPath, isUnixPlatform } from "./shared/@outfitter/daemon-5as2p88e";
+export { isUnixPlatform, getSocketPath, getPidPath, getLockPath, getDaemonDir };

package/dist/platform.js

@@ -0,0 +1,15 @@
+// @bun
+import {
+  getDaemonDir,
+  getLockPath,
+  getPidPath,
+  getSocketPath,
+  isUnixPlatform
+} from "./shared/@outfitter/daemon-wz4peqjh.js";
+export {
+  isUnixPlatform,
+  getSocketPath,
+  getPidPath,
+  getLockPath,
+  getDaemonDir
+};

package/dist/shared/@outfitter/daemon-3j14csts.js

@@ -0,0 +1,180 @@
+// @bun
+import {
+  DaemonError
+} from "./daemon-dzt3fqvp.js";
+
+// packages/daemon/src/lifecycle.ts
+import { mkdir, unlink, writeFile } from "fs/promises";
+import { dirname } from "path";
+import { Result } from "@outfitter/contracts";
+function pidFileExists(path) {
+  return Bun.file(path).exists();
+}
+async function writePidFile(path, pid) {
+  try {
+    const dir = dirname(path);
+    await mkdir(dir, { recursive: true });
+    await writeFile(path, String(pid), { flag: "wx" });
+    return Result.ok(undefined);
+  } catch (error) {
+    return Result.err(new DaemonError({
+      code: "PID_ERROR",
+      message: `Failed to write PID file: ${error instanceof Error ? error.message : "Unknown error"}`
+    }));
+  }
+}
+async function removePidFile(path) {
+  try {
+    await unlink(path);
+    return Result.ok(undefined);
+  } catch (error) {
+    if (error instanceof Error && "code" in error && error.code === "ENOENT") {
+      return Result.ok(undefined);
+    }
+    return Result.err(new DaemonError({
+      code: "PID_ERROR",
+      message: `Failed to remove PID file: ${error instanceof Error ? error.message : "Unknown error"}`
+    }));
+  }
+}
+async function runShutdownHandlers(handlers, timeout, logger) {
+  const errors = [];
+  const runHandlers = async () => {
+    for (const handler of handlers) {
+      try {
+        await handler();
+      } catch (error) {
+        const err = error instanceof Error ? error : new Error(String(error));
+        errors.push(err);
+        logger?.warn("Shutdown handler failed", { error: err.message });
+      }
+    }
+  };
+  const timeoutPromise = new Promise((resolve) => {
+    setTimeout(() => resolve("timeout"), timeout);
+  });
+  const result = await Promise.race([
+    runHandlers().then(() => "completed"),
+    timeoutPromise
+  ]);
+  return {
+    completed: result === "completed",
+    errors
+  };
+}
+function createDaemon(options) {
+  const internalState = {
+    state: "stopped",
+    options: {
+      name: options.name,
+      pidFile: options.pidFile,
+      logger: options.logger,
+      shutdownTimeout: options.shutdownTimeout ?? 5000
+    },
+    shutdownHandlers: [],
+    signalHandlers: {},
+    isShuttingDown: false
+  };
+  async function doStop() {
+    const { logger } = internalState.options;
+    if (internalState.isShuttingDown) {
+      return Result.ok(undefined);
+    }
+    if (internalState.state === "stopped") {
+      return Result.err(new DaemonError({
+        code: "NOT_RUNNING",
+        message: `Daemon "${internalState.options.name}" is not running`
+      }));
+    }
+    internalState.isShuttingDown = true;
+    internalState.state = "stopping";
+    logger?.info("Daemon stopping", { name: internalState.options.name });
+    const { completed } = await runShutdownHandlers(internalState.shutdownHandlers, internalState.options.shutdownTimeout, logger);
+    if (!completed) {
+      logger?.warn("Shutdown handlers timed out", {
+        name: internalState.options.name,
+        timeout: internalState.options.shutdownTimeout
+      });
+    }
+    if (internalState.signalHandlers.sigterm) {
+      process.off("SIGTERM", internalState.signalHandlers.sigterm);
+    }
+    if (internalState.signalHandlers.sigint) {
+      process.off("SIGINT", internalState.signalHandlers.sigint);
+    }
+    const removeResult = await removePidFile(internalState.options.pidFile);
+    if (removeResult.isErr()) {
+      logger?.error("Failed to remove PID file", {
+        error: removeResult.error.message
+      });
+    }
+    internalState.state = "stopped";
+    internalState.isShuttingDown = false;
+    logger?.info("Daemon stopped", { name: internalState.options.name });
+    if (!completed) {
+      return Result.err(new DaemonError({
+        code: "SHUTDOWN_TIMEOUT",
+        message: `Shutdown handlers exceeded timeout of ${internalState.options.shutdownTimeout}ms`
+      }));
+    }
+    return Result.ok(undefined);
+  }
+  const daemon = {
+    get state() {
+      return internalState.state;
+    },
+    async start() {
+      const { logger } = internalState.options;
+      if (internalState.state !== "stopped") {
+        return Result.err(new DaemonError({
+          code: "ALREADY_RUNNING",
+          message: `Daemon "${internalState.options.name}" is already running`
+        }));
+      }
+      internalState.state = "starting";
+      logger?.info("Daemon starting", { name: internalState.options.name });
+      if (await pidFileExists(internalState.options.pidFile)) {
+        internalState.state = "stopped";
+        return Result.err(new DaemonError({
+          code: "ALREADY_RUNNING",
+          message: `PID file already exists: ${internalState.options.pidFile}`
+        }));
+      }
+      const writeResult = await writePidFile(internalState.options.pidFile, process.pid);
+      if (writeResult.isErr()) {
+        internalState.state = "stopped";
+        return writeResult;
+      }
+      const sigTermHandler = () => {
+        logger?.info("Received SIGTERM signal");
+        doStop();
+      };
+      const sigIntHandler = () => {
+        logger?.info("Received SIGINT signal");
+        doStop();
+      };
+      internalState.signalHandlers.sigterm = sigTermHandler;
+      internalState.signalHandlers.sigint = sigIntHandler;
+      process.on("SIGTERM", sigTermHandler);
+      process.on("SIGINT", sigIntHandler);
+      internalState.state = "running";
+      logger?.info("Daemon started", {
+        name: internalState.options.name,
+        pid: process.pid
+      });
+      return Result.ok(undefined);
+    },
+    stop() {
+      return doStop();
+    },
+    isRunning() {
+      return internalState.state === "running";
+    },
+    onShutdown(handler) {
+      internalState.shutdownHandlers.push(handler);
+    }
+  };
+  return daemon;
+}
+
+export { createDaemon };

package/dist/shared/@outfitter/daemon-3qezw7hc.d.ts

@@ -0,0 +1,154 @@
+import { Result } from "@outfitter/contracts";
+/**
+* A single health check definition.
+*
+* Health checks are used to verify that a service or resource is functioning
+* correctly. Each check has a name for identification and a check function
+* that returns a Result indicating success or failure.
+*
+* @example
+* ```typescript
+* const databaseCheck: HealthCheck = {
+*   name: "database",
+*   check: async () => {
+*     try {
+*       await db.ping();
+*       return Result.ok(undefined);
+*     } catch (error) {
+*       return Result.err(error);
+*     }
+*   },
+* };
+* ```
+*/
+interface HealthCheck {
+	/**
+	* Unique name identifying this health check.
+	* Used as the key in the HealthStatus.checks record.
+	*/
+	name: string;
+	/**
+	* Function that performs the health check.
+	*
+	* Should return Result.ok(undefined) if healthy, or Result.err(error)
+	* with details about the failure.
+	*/
+	check(): Promise<Result<void, Error>>;
+}
+/**
+* Result of an individual health check.
+*
+* Contains the healthy/unhealthy status and an optional message
+* providing more details (typically the error message on failure).
+*/
+interface HealthCheckResult {
+	/** Whether this check passed (true) or failed (false) */
+	healthy: boolean;
+	/** Optional message, typically the error message on failure */
+	message?: string;
+}
+/**
+* Aggregated health status from all registered checks.
+*
+* The overall healthy status is true only if ALL individual checks pass.
+* Includes the uptime of the health checker in seconds.
+*
+* @example
+* ```typescript
+* const status: HealthStatus = {
+*   healthy: false,
+*   checks: {
+*     database: { healthy: true },
+*     cache: { healthy: false, message: "Connection refused" },
+*   },
+*   uptime: 3600,
+* };
+* ```
+*/
+interface HealthStatus {
+	/** Overall health status - true only if ALL checks pass */
+	healthy: boolean;
+	/** Individual check results keyed by check name */
+	checks: Record<string, HealthCheckResult>;
+	/** Uptime in seconds since the health checker was created */
+	uptime: number;
+}
+/**
+* Health checker interface for managing and running health checks.
+*
+* Provides methods to run all registered checks and get the aggregated
+* health status, as well as dynamically registering new checks at runtime.
+*
+* @example
+* ```typescript
+* const checker = createHealthChecker([
+*   { name: "db", check: checkDatabase },
+*   { name: "cache", check: checkCache },
+* ]);
+*
+* // Later, add more checks
+* checker.register({ name: "queue", check: checkQueue });
+*
+* // Get health status
+* const status = await checker.check();
+* console.log("Healthy:", status.healthy);
+* ```
+*/
+interface HealthChecker {
+	/**
+	* Run all registered health checks and return aggregated status.
+	*
+	* Checks are run in parallel for efficiency. The overall healthy
+	* status is true only if all individual checks pass.
+	*
+	* @returns Aggregated health status
+	*/
+	check(): Promise<HealthStatus>;
+	/**
+	* Register a new health check at runtime.
+	*
+	* The check will be included in all subsequent calls to check().
+	*
+	* @param check - Health check to register
+	*/
+	register(check: HealthCheck): void;
+}
+/**
+* Create a health checker with initial checks.
+*
+* The health checker runs all registered checks in parallel and aggregates
+* their results. Individual check failures are isolated and don't prevent
+* other checks from running.
+*
+* @param checks - Initial health checks to register
+* @returns HealthChecker instance
+*
+* @example
+* ```typescript
+* const checker = createHealthChecker([
+*   {
+*     name: "database",
+*     check: async () => {
+*       await db.ping();
+*       return Result.ok(undefined);
+*     },
+*   },
+*   {
+*     name: "cache",
+*     check: async () => {
+*       await redis.ping();
+*       return Result.ok(undefined);
+*     },
+*   },
+* ]);
+*
+* // Run health checks
+* const status = await checker.check();
+*
+* if (!status.healthy) {
+*   console.error("Service unhealthy:", status.checks);
+* }
+* ```
+*/
+declare function createHealthChecker(checks: HealthCheck[]): HealthChecker;
+export { HealthCheck, HealthCheckResult, HealthStatus, HealthChecker, createHealthChecker };

package/dist/shared/@outfitter/daemon-5as2p88e.d.ts

@@ -0,0 +1,69 @@
+/**
+* Check if running on a Unix-like platform (macOS or Linux).
+*
+* @returns true on macOS/Linux, false on Windows
+*
+* @example
+* ```typescript
+* if (isUnixPlatform()) {
+*   // Use Unix domain sockets
+* } else {
+*   // Use named pipes
+* }
+* ```
+*/
+declare function isUnixPlatform(): boolean;
+/**
+* Get the Unix domain socket path for a tool's daemon.
+*
+* @param toolName - Name of the tool (e.g., "waymark", "firewatch")
+* @returns Absolute path to the daemon socket
+*
+* @example
+* ```typescript
+* const socketPath = getSocketPath("waymark");
+* // "/run/user/1000/waymark/daemon.sock" on Linux
+* // "/var/folders/.../waymark/daemon.sock" on macOS
+* ```
+*/
+declare function getSocketPath(toolName: string): string;
+/**
+* Get the lock file path for a tool's daemon.
+*
+* @param toolName - Name of the tool (e.g., "waymark", "firewatch")
+* @returns Absolute path to the daemon lock file
+*
+* @example
+* ```typescript
+* const lockPath = getLockPath("waymark");
+* // "/run/user/1000/waymark/daemon.lock" on Linux
+* ```
+*/
+declare function getLockPath(toolName: string): string;
+/**
+* Get the PID file path for a tool's daemon.
+*
+* @param toolName - Name of the tool (e.g., "waymark", "firewatch")
+* @returns Absolute path to the daemon PID file
+*
+* @example
+* ```typescript
+* const pidPath = getPidPath("waymark");
+* // "/run/user/1000/waymark/daemon.pid" on Linux
+* ```
+*/
+declare function getPidPath(toolName: string): string;
+/**
+* Get the directory containing daemon files for a tool.
+*
+* @param toolName - Name of the tool (e.g., "waymark", "firewatch")
+* @returns Absolute path to the daemon directory
+*
+* @example
+* ```typescript
+* const daemonDir = getDaemonDir("waymark");
+* // "/run/user/1000/waymark" on Linux
+* ```
+*/
+declare function getDaemonDir(toolName: string): string;
+export { isUnixPlatform, getSocketPath, getLockPath, getPidPath, getDaemonDir };

package/dist/shared/@outfitter/daemon-6efpehdg.d.ts

@@ -0,0 +1,133 @@
+/**
+* Message handler type for processing incoming IPC messages.
+*
+* Receives a parsed message and returns a response to send back to the client.
+* Throwing an error will result in an error response to the client.
+*/
+type IpcMessageHandler = (message: unknown) => Promise<unknown>;
+/**
+* IPC server interface for receiving messages from clients.
+*
+* The server listens on a Unix socket and processes incoming messages
+* using the registered message handler.
+*
+* @example
+* ```typescript
+* const server = createIpcServer("/var/run/my-daemon.sock");
+*
+* server.onMessage(async (msg) => {
+*   if (msg.type === "status") {
+*     return { status: "ok", uptime: process.uptime() };
+*   }
+*   return { error: "Unknown command" };
+* });
+*
+* await server.listen();
+* ```
+*/
+interface IpcServer {
+	/**
+	* Start listening for connections on the Unix socket.
+	*
+	* Creates the socket file and begins accepting client connections.
+	* Messages are processed using the handler registered via onMessage.
+	*/
+	listen(): Promise<void>;
+	/**
+	* Stop listening and close all connections.
+	*
+	* Removes the socket file and cleans up resources.
+	*/
+	close(): Promise<void>;
+	/**
+	* Register a message handler for incoming messages.
+	*
+	* Only one handler can be registered. Calling this multiple times
+	* replaces the previous handler.
+	*
+	* @param handler - Function to process incoming messages
+	*/
+	onMessage(handler: IpcMessageHandler): void;
+}
+/**
+* IPC client interface for sending messages to a server.
+*
+* The client connects to a Unix socket and can send messages,
+* receiving responses asynchronously.
+*
+* @example
+* ```typescript
+* const client = createIpcClient("/var/run/my-daemon.sock");
+*
+* await client.connect();
+*
+* const response = await client.send<StatusResponse>({ type: "status" });
+* console.log("Daemon uptime:", response.uptime);
+*
+* client.close();
+* ```
+*/
+interface IpcClient {
+	/**
+	* Connect to the IPC server.
+	*
+	* Establishes a connection to the Unix socket. Throws if the
+	* server is not available.
+	*/
+	connect(): Promise<void>;
+	/**
+	* Send a message and wait for a response.
+	*
+	* Serializes the message to JSON, sends it to the server, and
+	* waits for a response.
+	*
+	* @typeParam T - Expected response type
+	* @param message - Message to send (must be JSON-serializable)
+	* @returns Promise resolving to the server's response
+	* @throws Error if not connected or communication fails
+	*/
+	send<T>(message: unknown): Promise<T>;
+	/**
+	* Close the connection to the server.
+	*
+	* Can be called multiple times safely.
+	*/
+	close(): void;
+}
+/**
+* Create an IPC server listening on a Unix socket.
+*
+* @param socketPath - Path to the Unix socket file
+* @returns IpcServer instance
+*
+* @example
+* ```typescript
+* const server = createIpcServer("/var/run/my-daemon.sock");
+*
+* server.onMessage(async (msg) => {
+*   return { echo: msg };
+* });
+*
+* await server.listen();
+* // Server is now accepting connections
+* ```
+*/
+declare function createIpcServer(socketPath: string): IpcServer;
+/**
+* Create an IPC client for connecting to a server.
+*
+* @param socketPath - Path to the Unix socket file
+* @returns IpcClient instance
+*
+* @example
+* ```typescript
+* const client = createIpcClient("/var/run/my-daemon.sock");
+*
+* await client.connect();
+* const response = await client.send({ command: "status" });
+* console.log(response);
+* client.close();
+* ```
+*/
+declare function createIpcClient(socketPath: string): IpcClient;
+export { IpcMessageHandler, IpcServer, IpcClient, createIpcServer, createIpcClient };