toolroll 0.5.0

package/dist/daemon.d.ts

@@ -0,0 +1,209 @@
+/**
+ * The daemon manager: the loop as a service, with no crontab in sight.
+ *
+ * `toolroll daemon install` writes the platform's own supervision unit —
+ * a launchd LaunchAgent on macOS, a systemd user unit on Linux, a Task
+ * Scheduler task on Windows, chosen by process.platform — pointed at
+ * `toolroll watch`, and loads it. The OS keeps it alive across crashes
+ * and reboots; watch's incarnation recovery is what makes those restarts
+ * safe, so the two halves were built for each other.
+ *
+ * The runner token never enters the unit file. It is written 0600 to a
+ * credential file beside the database (the same discipline as the Telegram
+ * bot token), and the unit runs `watch --token-file <path>`. A unit file is
+ * the kind of thing that ends up in a dotfiles repo; a credential file
+ * beside the database is the kind of thing backup tooling already treats
+ * as sensitive.
+ *
+ * The lifecycle (OS containment and login recovery plan) is ONE contract
+ * for the CLI daemon and the desktop service, which share the launchd road
+ * below:
+ *   - an installed always-on controller restarts after an unexpected
+ *     clean exit as well as a crash (launchd KeepAlive=true, systemd
+ *     Restart=always, a cmd restart loop under Task Scheduler);
+ *   - start is idempotent — a healthy running service is never killed
+ *     because the installer or the app window ran again;
+ *   - a CHANGED definition (runtime, entry, flags) really reloads: the old
+ *     job is booted out, its disappearance is awaited (the pending-bootout
+ *     race), and the new unit is bootstrapped;
+ *   - explicit stop unloads AND disables, so nothing relaunches it until a
+ *     person installs again — which re-enables;
+ *   - status tells a loaded definition from a fresh working controller,
+ *     and names a missing runtime, a missing entry, or a disabled service.
+ *
+ * Everything here is generation plus one supervisor invocation, both
+ * injectable — the tests read the generated unit and script `launchctl`,
+ * and never touch the machine's real supervision.
+ */
+import type { ExecResult, RunOptions } from "./exec.js";
+import type { Store } from "./store.js";
+export type SupervisorRunner = (file: string, args: readonly string[], options?: RunOptions) => Promise<ExecResult>;
+/** What every installed service — CLI watch or desktop controller — is made of. */
+export type ServiceDefinition = {
+    platform: "darwin" | "linux" | "win32";
+    label: string;
+    unitPath: string;
+    unitContent: string;
+    logPath: string;
+    /** The executable the unit runs (the pinned Node binary, or an explicit wrapper). */
+    bin: string;
+    /** The JavaScript entry the runtime is given, when there is one. */
+    entry: string | null;
+};
+export type DaemonPlan = ServiceDefinition & {
+    tokenFile: string;
+};
+/** A stable fingerprint of a unit's text: the changed-definition test. */
+export declare function definitionDigest(unitContent: string): string;
+/**
+ * Pin a service to the Node runtime that is executing Toolroll.
+ *
+ * launchd does not inherit an interactive shell's PATH, so invoking a JS
+ * package bin through `#!/usr/bin/env node` can install successfully and then
+ * fail before the CLI starts. The service instead runs the absolute Node
+ * binary with the package entry as its first argument. An explicitly supplied
+ * non-JavaScript executable remains an escape hatch for wrappers and packaged
+ * binaries.
+ */
+export declare function daemonLaunchCommand(args: {
+    execPath: string;
+    entry?: string;
+    explicitBin?: string;
+}): {
+    bin: string;
+    binArgs: string[];
+} | null;
+/** One service per repo, named so two repos' watches never collide. */
+export declare function labelFor(repo: string): string;
+/** The label a watch installed before the rename to Toolroll runs under: still found, stopped and uninstalled. */
+export declare function legacyLabelFor(repo: string): string;
+/**
+ * The launchd unit shared by the CLI daemon and the desktop service.
+ * KeepAlive requests relaunch after either clean exit or crash. macOS may
+ * defer nondemand launches; the desktop's live controller supervisor covers
+ * controller exits independently. Login/OS-service recovery requires the
+ * physical certification, not just a valid plist.
+ */
+export declare function launchdPlist(args: {
+    label: string;
+    command: readonly string[];
+    workingDirectory: string;
+    pathEnv: string;
+    logPath: string;
+    environment?: Record<string, string>;
+    associatedBundleId?: string;
+    keepAlive?: boolean;
+    startInterval?: number;
+}): string;
+/**
+ * Everything `install` would do, computed without doing it — the unit text,
+ * where it goes, where logs land. `--dry-run` prints exactly this.
+ */
+export declare function planDaemon(args: {
+    platform: NodeJS.Platform;
+    bin: string;
+    binArgs: readonly string[];
+    runner: string;
+    repo: string;
+    configDir: string;
+    watchFlags: readonly string[];
+    home?: string;
+    /** The interactive installer's executable search path, pinned into the
+     * service so logged-in provider CLIs remain discoverable after reboot. */
+    pathEnv?: string;
+    /** Defaults to labelFor(repo). */
+    label?: string;
+}): DaemonPlan | {
+    error: string;
+};
+/** The desktop shell's always-on controller: the same launchd contract, pointed at the desktop host. */
+export declare function planDesktopService(args: {
+    node: string;
+    helper: string;
+    stateDir: string;
+    label: string;
+    home?: string;
+    pathEnv?: string;
+    environment?: Record<string, string>;
+    associatedBundleId?: string;
+}): ServiceDefinition;
+export type ServiceStart = {
+    ok: true;
+    changed: boolean;
+    action: "bootstrapped" | "reloaded" | "started" | "running";
+} | {
+    ok: false;
+    message: string;
+};
+/**
+ * The shared launchd road. Idempotent start: a loaded job whose definition
+ * is unchanged is kickstarted WITHOUT -k (a running one is left alone; a
+ * stopped one starts); a loaded job whose definition changed is booted out,
+ * awaited, and bootstrapped afresh; an unloaded label is enabled (an
+ * explicit stop had disabled it) and bootstrapped. Nothing here kills a
+ * healthy service to prove it can.
+ */
+export declare function installLaunchdService(definition: ServiceDefinition, run: SupervisorRunner): Promise<ServiceStart>;
+/** Explicit stop: unload AND disable, so nothing relaunches it until a person installs again. */
+export declare function stopLaunchdService(definition: ServiceDefinition, run: SupervisorRunner): Promise<{
+    ok: true;
+    wasLoaded: boolean;
+} | {
+    ok: false;
+    message: string;
+}>;
+/**
+ * The same repo's watch as installed under the label it had before the
+ * rename to Toolroll, when its unit is still on disk; null otherwise.
+ * Installing the new one stops and removes it, so two watches never run.
+ */
+export declare function installedLegacyDaemon(args: Parameters<typeof planDaemon>[0]): DaemonPlan | null;
+/** Write the token 0600 and the unit, then hand the unit to the supervisor. */
+export declare function installDaemon(plan: DaemonPlan, token: string, run: SupervisorRunner): Promise<ServiceStart>;
+export declare function uninstallDaemon(plan: DaemonPlan, run: SupervisorRunner): Promise<{
+    ok: true;
+    existed: boolean;
+}>;
+/**
+ * The definition a label is INSTALLED under, read back from the unit file
+ * (the certificate's view: whatever is on disk is the baseline, so `stale`
+ * is false by construction and the runtime/entry are the installed ones).
+ * Null when no unit file exists for the label.
+ */
+export declare function installedServiceDefinition(args: {
+    label: string;
+    platform?: NodeJS.Platform;
+    home?: string;
+    configDir?: string;
+    logPath?: string;
+}): ServiceDefinition | null;
+export type ServiceStatus = {
+    /** `loaded` = the supervisor knows the definition but no process runs;
+     * `disabled` = an explicit stop turned it off. Neither is "working". */
+    state: "running" | "loaded" | "disabled" | "not-installed";
+    pid: number | null;
+    detail: string;
+    /** Diagnostics a person can act on: a missing runtime, a missing entry. */
+    problems: string[];
+    /** The installed unit's fingerprint, or null when no unit file exists. */
+    installedDigest: string | null;
+    /** Whether the installed unit still matches what this build would write. */
+    stale: boolean;
+};
+/** Runtime facts that make a loaded definition unable to become a working controller. */
+export declare function runtimeProblems(definition: ServiceDefinition): string[];
+export declare function daemonStatus(plan: ServiceDefinition, run: SupervisorRunner): Promise<ServiceStatus>;
+/**
+ * A supervisor PID is necessary but not sufficient: macOS can leave a
+ * process stuck behind a protected-folder access check before it ever
+ * opens the queue. The credentialed runner heartbeat is the end-to-end
+ * readiness receipt that proves a service reached the work loop — and a
+ * FRESH one, newer than what stood before the start, so a stale row from
+ * the previous incarnation cannot pass for the new controller.
+ */
+export declare function awaitFreshHeartbeat(store: Store, runnerName: string, heartbeatBefore: string | null, deadlineMs?: number, sleep?: (ms: number) => Promise<void>): Promise<{
+    ok: true;
+    heartbeatAt: string;
+} | {
+    ok: false;
+}>;