cli/daemon.ts

Daemon lifecycle management.
Provides daemon info schema, PID file management, and process lifecycle
operations. Separates lifecycle from presentation — stop_daemon returns
a result object instead of logging directly.

Declarations
#

8 declarations

view source

check_daemon_health
#

cli/daemon.ts view source

(deps: FetchDeps, port: number, host?: string, timeout_ms?: number): Promise<boolean>

Check if a daemon is healthy by probing its /health endpoint.
Complements is_daemon_running (PID check) with an HTTP liveness probe.
Requires the daemon to register a /health route (e.g. via create_health_route_spec).

`deps`

runtime with fetch capability

type FetchDeps

`port`

port the daemon should be listening on

type number

`host`

hostname (default localhost)

type string

default 'localhost'

`timeout_ms`

request timeout in milliseconds (default 2000)

type number

default 2000

returns

Promise<boolean>

true if the health endpoint responds with 2xx

DaemonInfo
#

cli/daemon.ts view source

ZodObject<{ version: ZodNumber; pid: ZodNumber; port: ZodNumber; started: ZodString; app_version: ZodString; }, $strict>

Daemon info schema for ~/.{name}/run/daemon.json.

get_daemon_info_path
#

cli/daemon.ts view source

(runtime: Pick<EnvDeps, "env_get">, name: string): string | null

Get the daemon info file path (~/.{name}/run/daemon.json).

`runtime`

runtime with env_get capability

type Pick<EnvDeps, "env_get">

`name`

application name

type string

returns

string | null

path to daemon.json, or null if $HOME is not set

is_daemon_running
#

cli/daemon.ts view source

(runtime: CommandDeps, pid: number): Promise<boolean>

Check if a process is running by PID.

`runtime`

runtime with command execution capability

type CommandDeps

`pid`

process ID to check

type number

returns

Promise<boolean>

true if the process is running

read_daemon_info
#

cli/daemon.ts view source

(runtime: Pick<EnvDeps, "env_get"> & Pick<FsReadDeps, "stat" | "read_text_file"> & LogDeps, name: string): Promise<{ version: number; pid: number; port: number; started: string; app_version: string; } | null>

Read and validate daemon info from the PID file.

`runtime`

runtime with file read and env capabilities

type Pick<EnvDeps, "env_get"> & Pick<FsReadDeps, "stat" | "read_text_file"> & LogDeps

`name`

application name

type string

returns

Promise<{ version: number; pid: number; port: number; started: string; app_version: string; } | null>

parsed daemon info, or null if missing or invalid

stop_daemon
#

cli/daemon.ts view source

(runtime: Pick<EnvDeps, "env_get"> & Pick<FsReadDeps, "stat" | "read_text_file"> & FsRemoveDeps & CommandDeps & LogDeps, name: string): Promise<...>

Stop a running daemon by sending SIGTERM and cleaning up the PID file.
Returns a result object instead of logging directly, separating
lifecycle from presentation. Errors removing the PID file are swallowed
(the daemon's own shutdown handler may have removed it concurrently).

`runtime`

runtime with command, file, and env capabilities

type Pick<EnvDeps, "env_get"> & Pick<FsReadDeps, "stat" | "read_text_file"> & FsRemoveDeps & CommandDeps & LogDeps

`name`

application name

type string

returns

Promise<StopDaemonResult>

result describing the outcome

StopDaemonResult
#

cli/daemon.ts view source

StopDaemonResult

Result of a stop_daemon operation.

`stopped`

Whether a daemon was stopped.

type boolean

`pid`

PID of the stopped daemon, if any.

type number

`message`

Human-readable message describing the outcome.

type string

write_daemon_info
#

cli/daemon.ts view source

(runtime: Pick<EnvDeps, "env_get"> & Pick<FsWriteDeps, "mkdir" | "write_text_file" | "rename">, name: string, info: { version: number; pid: number; port: number; started: string; app_version: string; }): Promise<...>

Write daemon info to the PID file, creating directories as needed.

`runtime`

runtime with file write and env capabilities

type Pick<EnvDeps, "env_get"> & Pick<FsWriteDeps, "mkdir" | "write_text_file" | "rename">

`name`

application name

type string

`info`

daemon info to write

type { version: number; pid: number; port: number; started: string; app_version: string; }

returns

Promise<void>

throws

Error - if `$HOME` is not set