@outfitter/daemon 0.2.1 → 0.2.2

package/dist/shared/@outfitter/daemon-8tpctdgw.d.ts

@@ -0,0 +1,127 @@
+import { TaggedErrorClass } from "@outfitter/contracts";
+declare const StaleSocketErrorBase: TaggedErrorClass<"StaleSocketError", {
+	message: string;
+	socketPath: string;
+	pid?: number;
+}>;
+declare const ConnectionRefusedErrorBase: TaggedErrorClass<"ConnectionRefusedError", {
+	message: string;
+	socketPath: string;
+}>;
+declare const ConnectionTimeoutErrorBase: TaggedErrorClass<"ConnectionTimeoutError", {
+	message: string;
+	socketPath: string;
+	timeoutMs: number;
+}>;
+declare const ProtocolErrorBase: TaggedErrorClass<"ProtocolError", {
+	message: string;
+	socketPath: string;
+	details?: string;
+}>;
+declare const LockErrorBase: TaggedErrorClass<"LockError", {
+	message: string;
+	lockPath: string;
+	pid?: number;
+}>;
+/**
+* Socket exists but daemon process is dead.
+*
+* Indicates a stale socket from a crashed daemon that needs cleanup
+* before a new daemon can start.
+*
+* @example
+* ```typescript
+* const error = new StaleSocketError({
+*   message: "Daemon socket is stale",
+*   socketPath: "/run/user/1000/waymark/daemon.sock",
+*   pid: 12345,
+* });
+* ```
+*/
+declare class StaleSocketError extends StaleSocketErrorBase {}
+/**
+* Daemon is not running (connection refused).
+*
+* Socket does not exist or connection was actively refused,
+* indicating no daemon is listening.
+*
+* @example
+* ```typescript
+* const error = new ConnectionRefusedError({
+*   message: "Connection refused",
+*   socketPath: "/run/user/1000/waymark/daemon.sock",
+* });
+* ```
+*/
+declare class ConnectionRefusedError extends ConnectionRefusedErrorBase {}
+/**
+* Daemon did not respond within timeout.
+*
+* Connection was established but daemon failed to respond
+* to ping or request within the configured timeout.
+*
+* @example
+* ```typescript
+* const error = new ConnectionTimeoutError({
+*   message: "Connection timed out after 5000ms",
+*   socketPath: "/run/user/1000/waymark/daemon.sock",
+*   timeoutMs: 5000,
+* });
+* ```
+*/
+declare class ConnectionTimeoutError extends ConnectionTimeoutErrorBase {}
+/**
+* Invalid response format from daemon.
+*
+* Daemon responded but the response could not be parsed
+* or did not match the expected protocol format.
+*
+* @example
+* ```typescript
+* const error = new ProtocolError({
+*   message: "Invalid JSON response",
+*   socketPath: "/run/user/1000/waymark/daemon.sock",
+*   details: "Unexpected token at position 42",
+* });
+* ```
+*/
+declare class ProtocolError extends ProtocolErrorBase {}
+/**
+* Failed to acquire or release daemon lock.
+*
+* Used when PID file operations fail due to permissions,
+* concurrent access, or file system errors.
+*
+* @example
+* ```typescript
+* const error = new LockError({
+*   message: "Daemon already running",
+*   lockPath: "/run/user/1000/waymark/daemon.lock",
+*   pid: 12345,
+* });
+* ```
+*/
+declare class LockError extends LockErrorBase {}
+/**
+* Union of all daemon connection error types.
+*
+* Use for exhaustive matching on connection failures:
+*
+* @example
+* ```typescript
+* function handleError(error: DaemonConnectionError): string {
+*   switch (error._tag) {
+*     case "StaleSocketError":
+*       return `Stale socket at ${error.socketPath}`;
+*     case "ConnectionRefusedError":
+*       return "Daemon not running";
+*     case "ConnectionTimeoutError":
+*       return `Timeout after ${error.timeoutMs}ms`;
+*     case "ProtocolError":
+*       return `Protocol error: ${error.details}`;
+*   }
+* }
+* ```
+*/
+type DaemonConnectionError = StaleSocketError | ConnectionRefusedError | ConnectionTimeoutError | ProtocolError;
+export { StaleSocketError, ConnectionRefusedError, ConnectionTimeoutError, ProtocolError, LockError, DaemonConnectionError };

package/dist/shared/@outfitter/daemon-906e24jc.js

@@ -0,0 +1,106 @@
+// @bun
+import {
+  LockError
+} from "./daemon-qqn2jpsg.js";
+
+// packages/daemon/src/locking.ts
+import { unlink } from "fs/promises";
+function isProcessAlive(pid) {
+  if (pid <= 0) {
+    return false;
+  }
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (error) {
+    if (error instanceof Error && "code" in error && error.code === "EPERM") {
+      return true;
+    }
+    return false;
+  }
+}
+async function isDaemonAlive(lockPath) {
+  const file = Bun.file(lockPath);
+  if (!await file.exists()) {
+    return false;
+  }
+  try {
+    const content = await file.text();
+    const pid = Number.parseInt(content.trim(), 10);
+    if (Number.isNaN(pid)) {
+      return false;
+    }
+    return isProcessAlive(pid);
+  } catch {
+    return false;
+  }
+}
+async function acquireDaemonLock(lockPath) {
+  const file = Bun.file(lockPath);
+  if (await file.exists()) {
+    try {
+      const content = await file.text();
+      const existingPid = Number.parseInt(content.trim(), 10);
+      if (!Number.isNaN(existingPid) && isProcessAlive(existingPid)) {
+        return {
+          isOk: () => false,
+          isErr: () => true,
+          error: new LockError({
+            message: `Daemon already running with PID ${existingPid}`,
+            lockPath,
+            pid: existingPid
+          })
+        };
+      }
+    } catch {}
+  }
+  const pid = process.pid;
+  try {
+    await Bun.write(lockPath, `${pid}
+`);
+    return {
+      isOk: () => true,
+      isErr: () => false,
+      value: { lockPath, pid }
+    };
+  } catch (error) {
+    return {
+      isOk: () => false,
+      isErr: () => true,
+      error: new LockError({
+        message: `Failed to write lock file: ${error instanceof Error ? error.message : String(error)}`,
+        lockPath,
+        pid
+      })
+    };
+  }
+}
+async function releaseDaemonLock(handle) {
+  const { lockPath, pid } = handle;
+  const file = Bun.file(lockPath);
+  if (!await file.exists()) {
+    return;
+  }
+  try {
+    const content = await file.text();
+    const filePid = Number.parseInt(content.trim(), 10);
+    if (filePid === pid) {
+      await unlink(lockPath);
+    }
+  } catch {}
+}
+async function readLockPid(lockPath) {
+  const file = Bun.file(lockPath);
+  if (!await file.exists()) {
+    return;
+  }
+  try {
+    const content = await file.text();
+    const pid = Number.parseInt(content.trim(), 10);
+    return Number.isNaN(pid) ? undefined : pid;
+  } catch {
+    return;
+  }
+}
+
+export { isProcessAlive, isDaemonAlive, acquireDaemonLock, releaseDaemonLock, readLockPid };

package/dist/shared/@outfitter/daemon-9w2ey87r.d.ts

@@ -0,0 +1,161 @@
+import { Result, TaggedErrorClass } from "@outfitter/contracts";
+import { LoggerInstance } from "@outfitter/logging";
+declare const DaemonErrorBase: TaggedErrorClass<"DaemonError", {
+	code: DaemonErrorCode;
+	message: string;
+}>;
+/**
+* Error codes for daemon operations.
+*
+* - `ALREADY_RUNNING`: Daemon start requested but already running
+* - `NOT_RUNNING`: Daemon stop requested but not running
+* - `SHUTDOWN_TIMEOUT`: Graceful shutdown exceeded timeout
+* - `PID_ERROR`: PID file operations failed
+* - `START_FAILED`: Daemon failed to start
+*/
+type DaemonErrorCode = "ALREADY_RUNNING" | "NOT_RUNNING" | "SHUTDOWN_TIMEOUT" | "PID_ERROR" | "START_FAILED";
+/**
+* Error type for daemon operations.
+*
+* Uses the TaggedError pattern for type-safe error handling with Result types.
+*
+* @example
+* ```typescript
+* const error = new DaemonError({
+*   code: "ALREADY_RUNNING",
+*   message: "Daemon is already running with PID 1234",
+* });
+*
+* if (error.code === "ALREADY_RUNNING") {
+*   console.log("Stop the existing daemon first");
+* }
+* ```
+*/
+declare class DaemonError extends DaemonErrorBase {}
+/**
+* Daemon lifecycle states.
+*
+* State machine transitions:
+* - `stopped` -> `starting` (via start())
+* - `starting` -> `running` (when initialization complete)
+* - `starting` -> `stopped` (if start fails)
+* - `running` -> `stopping` (via stop() or signal)
+* - `stopping` -> `stopped` (when shutdown complete)
+*/
+type DaemonState = "stopped" | "starting" | "running" | "stopping";
+/**
+* Configuration options for creating a daemon.
+*
+* @example
+* ```typescript
+* const options: DaemonOptions = {
+*   name: "my-daemon",
+*   pidFile: "/var/run/my-daemon.pid",
+*   logger: myLogger,
+*   shutdownTimeout: 10000, // 10 seconds
+* };
+*
+* const daemon = createDaemon(options);
+* ```
+*/
+interface DaemonOptions {
+	/**
+	* Unique name identifying this daemon.
+	* Used in log messages and error context.
+	*/
+	name: string;
+	/**
+	* Absolute path to the PID file.
+	* The daemon writes its process ID here on start and removes it on stop.
+	* Used to prevent multiple instances and for external process management.
+	*/
+	pidFile: string;
+	/**
+	* Optional logger instance for daemon messages.
+	* If not provided, logging is disabled.
+	*/
+	logger?: LoggerInstance;
+	/**
+	* Maximum time in milliseconds to wait for graceful shutdown.
+	* After this timeout, the daemon will force stop.
+	* @defaultValue 5000
+	*/
+	shutdownTimeout?: number;
+}
+/**
+* Shutdown handler function type.
+*
+* Called during graceful shutdown to allow cleanup of resources.
+* Must complete within the shutdown timeout.
+*/
+type ShutdownHandler = () => Promise<void>;
+/**
+* Daemon instance interface.
+*
+* Provides lifecycle management for a background process including
+* start/stop operations, signal handling, and shutdown hooks.
+*
+* @example
+* ```typescript
+* const daemon = createDaemon({
+*   name: "my-service",
+*   pidFile: "/var/run/my-service.pid",
+* });
+*
+* // Register cleanup handlers
+* daemon.onShutdown(async () => {
+*   await database.close();
+* });
+*
+* // Start the daemon
+* const result = await daemon.start();
+* if (result.isErr()) {
+*   console.error("Failed to start:", result.error.message);
+*   process.exit(1);
+* }
+*
+* // Daemon is now running...
+* // Stop gracefully when needed
+* await daemon.stop();
+* ```
+*/
+interface Daemon {
+	/**
+	* Current lifecycle state of the daemon.
+	*/
+	readonly state: DaemonState;
+	/**
+	* Start the daemon.
+	*
+	* Creates PID file and registers signal handlers.
+	* Transitions from `stopped` to `starting` then `running`.
+	*
+	* @returns Result with void on success, or DaemonError on failure
+	*/
+	start(): Promise<Result<void, DaemonError>>;
+	/**
+	* Stop the daemon gracefully.
+	*
+	* Runs shutdown handlers, removes PID file, and cleans up signal handlers.
+	* Transitions from `running` to `stopping` then `stopped`.
+	*
+	* @returns Result with void on success, or DaemonError on failure
+	*/
+	stop(): Promise<Result<void, DaemonError>>;
+	/**
+	* Check if the daemon is currently running.
+	*
+	* @returns true if state is "running", false otherwise
+	*/
+	isRunning(): boolean;
+	/**
+	* Register a shutdown handler to be called during graceful shutdown.
+	*
+	* Multiple handlers can be registered and will be called in registration order.
+	* Handlers must complete within the shutdown timeout.
+	*
+	* @param handler - Async function to execute during shutdown
+	*/
+	onShutdown(handler: ShutdownHandler): void;
+}
+export { DaemonErrorCode, DaemonError, DaemonState, DaemonOptions, ShutdownHandler, Daemon };

package/dist/shared/@outfitter/daemon-bd6kcdnj.d.ts

@@ -0,0 +1,32 @@
+import { Daemon, DaemonOptions } from "./daemon-9w2ey87r";
+/**
+* Create a new daemon instance.
+*
+* The daemon manages its own lifecycle including PID file creation/removal,
+* signal handling for graceful shutdown, and execution of registered
+* shutdown handlers.
+*
+* @param options - Daemon configuration options
+* @returns Daemon instance
+*
+* @example
+* ```typescript
+* const daemon = createDaemon({
+*   name: "my-service",
+*   pidFile: "/var/run/my-service.pid",
+*   shutdownTimeout: 10000,
+* });
+*
+* daemon.onShutdown(async () => {
+*   await database.close();
+* });
+*
+* const result = await daemon.start();
+* if (result.isErr()) {
+*   console.error("Failed to start:", result.error.message);
+*   process.exit(1);
+* }
+* ```
+*/
+declare function createDaemon(options: DaemonOptions): Daemon;
+export { createDaemon };

package/dist/shared/@outfitter/daemon-c1zbfqq5.js

@@ -0,0 +1,50 @@
+// @bun
+// packages/daemon/src/health.ts
+function createHealthChecker(checks) {
+  const registeredChecks = [...checks];
+  const startTime = Date.now();
+  async function runCheck(check) {
+    try {
+      const result = await check.check();
+      if (result.isOk()) {
+        return { healthy: true };
+      }
+      return {
+        healthy: false,
+        message: result.error.message
+      };
+    } catch (error) {
+      return {
+        healthy: false,
+        message: error instanceof Error ? error.message : "Unknown error"
+      };
+    }
+  }
+  return {
+    async check() {
+      const results = await Promise.all(registeredChecks.map(async (check) => ({
+        name: check.name,
+        result: await runCheck(check)
+      })));
+      const checksRecord = {};
+      let allHealthy = true;
+      for (const { name, result } of results) {
+        checksRecord[name] = result;
+        if (!result.healthy) {
+          allHealthy = false;
+        }
+      }
+      const uptime = Math.floor((Date.now() - startTime) / 1000);
+      return {
+        healthy: allHealthy,
+        checks: checksRecord,
+        uptime
+      };
+    },
+    register(check) {
+      registeredChecks.push(check);
+    }
+  };
+}
+
+export { createHealthChecker };

package/dist/shared/@outfitter/daemon-cy5wntm2.js

@@ -0,0 +1,207 @@
+// @bun
+// packages/daemon/src/ipc.ts
+import { unlink } from "fs/promises";
+function createIpcServer(socketPath) {
+  let messageHandler = null;
+  let server = null;
+  let isListening = false;
+  const socketBuffers = new WeakMap;
+  function processSocketBuffer(socket) {
+    const buffer = socketBuffers.get(socket) ?? "";
+    const lines = buffer.split(`
+`);
+    socketBuffers.set(socket, lines.pop() ?? "");
+    for (const line of lines) {
+      if (!line.trim())
+        continue;
+      try {
+        const message = JSON.parse(line);
+        if (message.type === "request" && messageHandler) {
+          (async () => {
+            try {
+              const result = await messageHandler(message.payload);
+              const response = {
+                id: message.id,
+                type: "response",
+                payload: result
+              };
+              socket.write(`${JSON.stringify(response)}
+`);
+            } catch (error) {
+              const errorResponse = {
+                id: message.id,
+                type: "error",
+                payload: {
+                  message: error instanceof Error ? error.message : "Unknown error"
+                }
+              };
+              socket.write(`${JSON.stringify(errorResponse)}
+`);
+            }
+          })();
+        }
+      } catch {}
+    }
+  }
+  return {
+    async listen() {
+      if (isListening)
+        return;
+      try {
+        await unlink(socketPath);
+      } catch {}
+      server = Bun.listen({
+        unix: socketPath,
+        socket: {
+          data(socket, data) {
+            const text = Buffer.isBuffer(data) ? data.toString("utf-8") : String(data);
+            const currentBuffer = socketBuffers.get(socket) ?? "";
+            socketBuffers.set(socket, currentBuffer + text);
+            processSocketBuffer(socket);
+          },
+          open(socket) {
+            socketBuffers.set(socket, "");
+          },
+          close(socket) {
+            socketBuffers.delete(socket);
+          },
+          error() {}
+        }
+      });
+      isListening = true;
+    },
+    async close() {
+      if (!isListening)
+        return;
+      server?.stop();
+      server = null;
+      isListening = false;
+      try {
+        await unlink(socketPath);
+      } catch {}
+    },
+    onMessage(handler) {
+      messageHandler = handler;
+    }
+  };
+}
+function createIpcClient(socketPath) {
+  let socket = null;
+  let isConnected = false;
+  const pendingRequests = new Map;
+  let messageBuffer = "";
+  function generateId() {
+    return `${Date.now()}-${Math.random().toString(36).slice(2, 10)}`;
+  }
+  function processBuffer() {
+    const lines = messageBuffer.split(`
+`);
+    messageBuffer = lines.pop() ?? "";
+    for (const line of lines) {
+      if (!line.trim())
+        continue;
+      try {
+        const message = JSON.parse(line);
+        const pending = pendingRequests.get(message.id);
+        if (pending) {
+          pendingRequests.delete(message.id);
+          if (message.type === "response") {
+            pending.resolve(message.payload);
+          } else if (message.type === "error") {
+            const errorPayload = message.payload;
+            pending.reject(new Error(errorPayload.message));
+          }
+        }
+      } catch {}
+    }
+  }
+  function rejectAllPending() {
+    for (const [id, pending] of pendingRequests) {
+      pending.reject(new Error("Connection closed"));
+      pendingRequests.delete(id);
+    }
+  }
+  return {
+    connect() {
+      if (isConnected && socket)
+        return Promise.resolve();
+      messageBuffer = "";
+      return new Promise((resolve, reject) => {
+        try {
+          Bun.connect({
+            unix: socketPath,
+            socket: {
+              data(_socket, data) {
+                const text = Buffer.isBuffer(data) ? data.toString("utf-8") : String(data);
+                messageBuffer += text;
+                processBuffer();
+              },
+              open(_socket) {
+                isConnected = true;
+                socket = _socket;
+                resolve();
+              },
+              close() {
+                isConnected = false;
+                socket = null;
+                rejectAllPending();
+              },
+              error(_socket, error) {
+                isConnected = false;
+                socket = null;
+                reject(error);
+              },
+              connectError(_socket, error) {
+                isConnected = false;
+                socket = null;
+                reject(error);
+              }
+            }
+          });
+        } catch (error) {
+          reject(error);
+        }
+      });
+    },
+    send(message) {
+      if (!(isConnected && socket)) {
+        return Promise.reject(new Error("Not connected to server"));
+      }
+      const id = generateId();
+      const request = {
+        id,
+        type: "request",
+        payload: message
+      };
+      return new Promise((resolve, reject) => {
+        pendingRequests.set(id, {
+          resolve,
+          reject
+        });
+        try {
+          const written = socket?.write(`${JSON.stringify(request)}
+`);
+          if (written === 0) {
+            pendingRequests.delete(id);
+            reject(new Error("Failed to write to socket"));
+          }
+        } catch (error) {
+          pendingRequests.delete(id);
+          reject(error);
+        }
+      });
+    },
+    close() {
+      if (!(isConnected && socket))
+        return;
+      try {
+        socket?.terminate();
+      } catch {}
+      socket = null;
+      isConnected = false;
+      rejectAllPending();
+    }
+  };
+}
+
+export { createIpcServer, createIpcClient };

package/dist/shared/@outfitter/daemon-dzt3fqvp.js

@@ -0,0 +1,9 @@
+// @bun
+// packages/daemon/src/types.ts
+import { TaggedError } from "@outfitter/contracts";
+var DaemonErrorBase = TaggedError("DaemonError")();
+
+class DaemonError extends DaemonErrorBase {
+}
+
+export { DaemonError };