toolroll 0.9.89 → 0.9.91

package/dist/laptop-background.d.ts

@@ -0,0 +1,171 @@
+/**
+ * Keeping Toolroll running in the background on a laptop (easy-start plan D): `toolroll background on|off|show`,
+ * `toolroll stop`, and the `laptop` part of `toolroll status`.
+ *
+ * The login item itself is laptop-service.ts's definition (com.toolroll.up / toolroll-up.service). This module is
+ * the handoff around it:
+ *
+ * - **on** writes and validates the unit without loading it, stops the foreground `up` this invoker owns (if one runs
+ *   for this database) by SIGTERM to its controller and waits until that controller's whole process record is proved
+ *   gone by start identity and the port is free, then loads the unit and proves the console live within 30 s. Any
+ *   failure boots the unit out, removes it (or puts back the one that was there), starts the foreground `up` again if
+ *   it was stopped, and says what failed. An identical unit already loaded is left alone.
+ * - **off** stops and removes only our own label.
+ * - **stop**: with the service loaded, the supervisor stops it (it comes back at login); otherwise the controller of
+ *   the proven console, found through its signed process record, gets SIGTERM — never the console child, which the
+ *   controller would only start again.
+ *
+ * Every outside effect goes through LaptopSeams: tests give a temporary HOME, a scripted launchctl/systemctl, and their
+ * own child processes. Without a supervisor seam, a test run (VITEST) refuses to reach the real launchctl or systemctl.
+ * Other services (the desktop app's com.toolroll.browser, a watch on this database) are reported, never touched.
+ */
+import { type AttachProof } from "./console-instance.js";
+import { type SupervisorRunner } from "./daemon.js";
+import { type LaptopConflict } from "./laptop-service.js";
+import { type ProcessProbe } from "./runner-process.js";
+import type { Runner } from "./runner.js";
+import { type Store } from "./store.js";
+/** Everything outside this process that the background handoff touches. Tests replace all of it. */
+export type LaptopSeams = {
+    platform?: NodeJS.Platform;
+    home?: string;
+    /** launchctl, systemctl, plutil and systemd-analyze. */
+    supervisor?: SupervisorRunner;
+    /** The absolute Node binary and package `dist` folder the unit pins (default: this process's). */
+    node?: string;
+    dist?: string;
+    pathEnv?: string;
+    /** A person at a terminal (stdin and stdout a TTY, no --json, not under a coding agent): only they may confirm. */
+    terminal?: boolean;
+    /** Run by a coding agent (prompt.ts underAgent): a login item is a person's own choice, so `on` refuses. */
+    agent?: boolean;
+    confirm?: (question: string) => Promise<boolean>;
+    /** Prove this database's console live (default: proveLiveConsole at this package's version). */
+    proveConsole?: (databaseFile: string, store: Store) => Promise<AttachProof>;
+    probe?: ProcessProbe;
+    /** A process's parent, or null when it can't be read. */
+    parentOf?: (pid: number) => number | null;
+    signal?: (pid: number, signal: NodeJS.Signals) => void;
+    portFree?: (port: number) => Promise<boolean>;
+    sleep?: (ms: number) => Promise<void>;
+    host?: string;
+    healthTimeoutMs?: number;
+    exitTimeoutMs?: number;
+    /** The foreground `up` this invoker started (the terminal UI's child): its controller's pid, and how to start it again. */
+    foreground?: {
+        controllerPid: number;
+        restart: () => Promise<void>;
+    };
+};
+export type BackgroundState = "on" | "off" | "other-service";
+type Resolved = Required<Omit<LaptopSeams, "foreground" | "node" | "dist" | "pathEnv">> & Pick<LaptopSeams, "foreground" | "pathEnv"> & {
+    node: string;
+    dist: string;
+};
+export type ControllerProof = {
+    /** The `up` process that started the console: the one to stop. */
+    pid: number;
+    started: string;
+    consolePid: number;
+    port: number;
+    url: string;
+    runner: string;
+    /** The registration whose signed record names both, captured now: the exit proof uses exactly it. */
+    holder: {
+        runner: Runner;
+        credentialHash: string;
+    };
+};
+/**
+ * The controller of this database's live console, proved from the plane's own records: a live runner on this host
+ * whose signed process record names the proven console (pid and start time) and exactly one live `up` process, that
+ * `up` still the process the record names (same start time), and the console's parent that `up`. Anything else —
+ * no record, a reused pid, a console whose parent is someone else — proves nothing and is refused.
+ */
+export declare function findController(store: Store, databaseFile: string, console_: {
+    pid: number;
+    port: number;
+    url: string;
+}, s: Pick<Resolved, "probe" | "parentOf" | "host">): ControllerProof | {
+    why: string;
+};
+export type BackgroundShow = {
+    platform: NodeJS.Platform;
+    label: string | null;
+    unit: string | null;
+    installed: "same" | "different" | "absent";
+    loaded: boolean;
+    running: {
+        url: string;
+        pid: number;
+    } | null;
+    conflicts: LaptopConflict[];
+    port: number;
+};
+export declare function backgroundShow(store: Store, databaseFile: string, requestedPort: number | null, seams?: LaptopSeams): Promise<{
+    ok: true;
+    show: BackgroundShow;
+} | {
+    ok: false;
+    reason: string;
+    message: string;
+}>;
+export type BackgroundOn = {
+    ok: true;
+    action: "unchanged" | "installed" | "replaced";
+    label: string;
+    unit: string;
+    url: string;
+    pid: number;
+    stoppedForeground: boolean;
+} | {
+    ok: false;
+    reason: string;
+    message: string;
+    rolledBack?: string[];
+};
+/** `requestedPort`: --port, else the running console's, else the port this laptop install saved, else `up`'s default. */
+export declare function backgroundOn(store: Store, databaseFile: string, requestedPort: number | null, seams?: LaptopSeams): Promise<BackgroundOn>;
+export type BackgroundOff = {
+    ok: true;
+    action: "removed" | "already-off";
+    label: string;
+    unit: string;
+} | {
+    ok: false;
+    reason: string;
+    message: string;
+};
+export declare function backgroundOff(store: Store, databaseFile: string, seams?: LaptopSeams): Promise<BackgroundOff>;
+export type LaptopStop = {
+    ok: true;
+    action: "service-stopped" | "stopped" | "not-running";
+    pid: number | null;
+    startsAtLogin: boolean;
+} | {
+    ok: false;
+    reason: string;
+    message: string;
+};
+export declare function laptopStop(store: Store, databaseFile: string, seams?: LaptopSeams): Promise<LaptopStop>;
+export type LaptopStatus = {
+    running: boolean;
+    url: string | null;
+    pid: number | null;
+    background: BackgroundState;
+};
+/**
+ * The `laptop` key of `toolroll status`: whether this database's console is proven live (its address and the console
+ * process), and whether a background service runs it — ours ("on"), another service on this database or the desktop
+ * app's ("other-service"), or none ("off"). Reads files only; never asks the supervisor.
+ */
+export declare function laptopStatus(store: Store, databaseFile: string, seams?: LaptopSeams): Promise<LaptopStatus>;
+/** Whether Toolroll's own login item is installed here (its unit file exists). Reads one path; asks no supervisor. */
+export declare function backgroundInstalled(seams?: LaptopSeams): boolean;
+/**
+ * Bare `toolroll` and `toolroll open` with the background service installed but this database's console not running
+ * (stopped with `toolroll stop`, or not yet started at this login): start it through its supervisor — never a second
+ * `up` beside it — and prove the console it runs live. Our own label only.
+ */
+export declare function startInstalledService(store: Store, databaseFile: string, seams?: LaptopSeams): Promise<AttachProof>;
+export {};