@crewhaus/tool-desktop 0.7.0

package/dist/fixtures.d.ts

@@ -0,0 +1,84 @@
+/**
+ * Recorded output, and where each line came from.
+ *
+ * Nothing in this package's suite asks the machine it runs on. CI is a Linux
+ * container with no desktop at all, this was written on macOS, and a parser
+ * checked against whatever the test host happens to answer is a parser
+ * checked against nothing. So every classifier is fed from here.
+ *
+ * Each constant says whether it was RECORDED (somebody ran the command and
+ * pasted the bytes) or DOCUMENTED (written from the program's source or
+ * manual because nobody here has that platform). The distinction is kept
+ * deliberately: a documented fixture proves the parser handles the shape it
+ * was told about, and claims nothing more.
+ */
+/** No X server at all. Exit 1, empty stdout. */
+export declare const XCLIP_NO_DISPLAY_STDERR = "Error: Can't open display: (null)\n";
+/**
+ * A reachable display with nothing on the selection. Exit 1, empty stdout —
+ * the SAME exit code and the SAME empty stdout as the line above, and the
+ * opposite meaning. This pair is why `classifyClipboardRead` reads stderr.
+ */
+export declare const XCLIP_EMPTY_SELECTION_STDERR = "Error: target STRING not available\n";
+/** The happy path. */
+export declare const XCLIP_TEXT_STDOUT = "ssh-rsa AAAAB3NzaC1yc2EA... deploy@example\n";
+/** `clipboard info` against an EMPTY pasteboard: empty stdout, exit 0. */
+export declare const CLIPBOARD_INFO_EMPTY_STDOUT = "";
+/**
+ * `clipboard info` with a screenshot on the pasteboard: flavour names and
+ * byte counts, and no content. This is what tells "empty" from "there is
+ * something here pbpaste cannot give you".
+ */
+export declare const CLIPBOARD_INFO_IMAGE_STDOUT = "\u00ABclass PNGf\u00BB, 284913, \u00ABclass 8BPS\u00BB, 1049928, TIFF picture, 1063968";
+export declare const NOTIFY_SEND_NO_BUS_STDERR = "Cannot autolaunch D-Bus without X11 $DISPLAY\n";
+/**
+ * The argument-injection this package's `--` exists to prevent: with the
+ * summary passed as a bare positional, `-u` was consumed as the urgency flag
+ * and the body became its argument.
+ */
+export declare const NOTIFY_SEND_FLAG_INJECTION_STDERR = "Unknown urgency body specified\n";
+export declare const OSASCRIPT_NO_ACCESSIBILITY_STDERR = "44:87: execution error: System Events got an error: osascript is not allowed assistive access. (-25211)\n";
+/** The OTHER grant, in a different System Settings pane. */
+export declare const OSASCRIPT_NO_AUTOMATION_STDERR = "48:52: execution error: Not authorized to send Apple events to System Events. (-1743)\n";
+/**
+ * `wmctrl -l -G -p -x`. Nine fixed columns then a title with spaces in it;
+ * the second row's title repeats a column's text on purpose, because a parser
+ * that re-joins the split fields gets that one wrong.
+ */
+export declare const WMCTRL_STDOUT: string;
+/**
+ * `ioreg -r -c IOHIDSystem -d 1`. NANOSECONDS: 3_254_341_351_000 ns is 3254
+ * seconds. Reading it as milliseconds would report 3254 seconds of idleness
+ * as three, and make a locked machine look freshly used.
+ *
+ * The `-r` matters as much as the unit. `ioreg -c IOHIDSystem -d 1` — the
+ * form the survey sketch gave — prints this key NOWHERE on this OS version,
+ * because without `-r` the depth is measured from the root.
+ */
+export declare const IOREG_HIDIDLE_STDOUT: string;
+/** The same machine, `ioreg -n Root -d1`, with the screen locked. */
+export declare const IOREG_ROOT_LOCKED_STDOUT: string;
+/** An unlocked console, same keys. */
+export declare const IOREG_ROOT_UNLOCKED_STDOUT: string;
+/** A macOS version that reports lock state somewhere this parser cannot see. */
+export declare const IOREG_ROOT_NO_LOCK_KEY_STDOUT = "      \"IORegistryPlanes\" = {\"IOService\"=\"IOService\"}";
+/** DOCUMENTED: `loginctl show-session self -p LockedHint -p Type -p Active`. */
+export declare const LOGINCTL_STDOUT = "LockedHint=no\nType=x11\nActive=yes\n";
+/** DOCUMENTED: the Windows presence script's two lines. */
+export declare const WINDOWS_PRESENCE_STDOUT = "idleMs=42000\nlocked=no\n";
+/**
+ * `lpstat -p -d`, verbatim. Two printers in two DIFFERENT sentence shapes,
+ * an INDENTED continuation line that belongs to the row above it, and the
+ * default-destination line.
+ */
+export declare const LPSTAT_STDOUT: string;
+/**
+ * A host whose scheduler is down. It lists NOTHING, which reads exactly like
+ * a host with no printers — the rule-6 case this fixture exists for.
+ */
+export declare const LPSTAT_NO_SCHEDULER_STDERR = "lpstat: Scheduler is not running.\n";
+/** DOCUMENTED: `lp` answers with prose and the job id is inside it. */
+export declare const LP_REQUEST_ID_STDOUT = "request id is Canon_MX490_series-34 (1 file(s))\n";
+export declare const PS_CAFFEINATE_STDOUT = "caffeinate -i -m -t 1800\n";
+/** The same pid, now owned by something else entirely. */
+export declare const PS_REUSED_PID_STDOUT = "/usr/sbin/cupsd -l\n";

package/dist/fixtures.js

@@ -0,0 +1,130 @@
+/**
+ * Recorded output, and where each line came from.
+ *
+ * Nothing in this package's suite asks the machine it runs on. CI is a Linux
+ * container with no desktop at all, this was written on macOS, and a parser
+ * checked against whatever the test host happens to answer is a parser
+ * checked against nothing. So every classifier is fed from here.
+ *
+ * Each constant says whether it was RECORDED (somebody ran the command and
+ * pasted the bytes) or DOCUMENTED (written from the program's source or
+ * manual because nobody here has that platform). The distinction is kept
+ * deliberately: a documented fixture proves the parser handles the shape it
+ * was told about, and claims nothing more.
+ */
+// ---------------------------------------------------------------------------
+// clipboard — Linux, RECORDED on Debian 12 / xclip 0.13
+// ---------------------------------------------------------------------------
+/** No X server at all. Exit 1, empty stdout. */
+export const XCLIP_NO_DISPLAY_STDERR = "Error: Can't open display: (null)\n";
+/**
+ * A reachable display with nothing on the selection. Exit 1, empty stdout —
+ * the SAME exit code and the SAME empty stdout as the line above, and the
+ * opposite meaning. This pair is why `classifyClipboardRead` reads stderr.
+ */
+export const XCLIP_EMPTY_SELECTION_STDERR = "Error: target STRING not available\n";
+/** The happy path. */
+export const XCLIP_TEXT_STDOUT = "ssh-rsa AAAAB3NzaC1yc2EA... deploy@example\n";
+// ---------------------------------------------------------------------------
+// clipboard — macOS, RECORDED on macOS 26.6.2
+// ---------------------------------------------------------------------------
+/** `clipboard info` against an EMPTY pasteboard: empty stdout, exit 0. */
+export const CLIPBOARD_INFO_EMPTY_STDOUT = "";
+/**
+ * `clipboard info` with a screenshot on the pasteboard: flavour names and
+ * byte counts, and no content. This is what tells "empty" from "there is
+ * something here pbpaste cannot give you".
+ */
+export const CLIPBOARD_INFO_IMAGE_STDOUT = "«class PNGf», 284913, «class 8BPS», 1049928, TIFF picture, 1063968";
+// ---------------------------------------------------------------------------
+// notifications — Linux, RECORDED on Debian 12 / libnotify 0.8.1
+// ---------------------------------------------------------------------------
+export const NOTIFY_SEND_NO_BUS_STDERR = "Cannot autolaunch D-Bus without X11 $DISPLAY\n";
+/**
+ * The argument-injection this package's `--` exists to prevent: with the
+ * summary passed as a bare positional, `-u` was consumed as the urgency flag
+ * and the body became its argument.
+ */
+export const NOTIFY_SEND_FLAG_INJECTION_STDERR = "Unknown urgency body specified\n";
+// ---------------------------------------------------------------------------
+// AppleScript — RECORDED on macOS 26.6.2 with Accessibility NOT granted
+// ---------------------------------------------------------------------------
+export const OSASCRIPT_NO_ACCESSIBILITY_STDERR = "44:87: execution error: System Events got an error: osascript is not allowed assistive access. (-25211)\n";
+/** The OTHER grant, in a different System Settings pane. */
+export const OSASCRIPT_NO_AUTOMATION_STDERR = "48:52: execution error: Not authorized to send Apple events to System Events. (-1743)\n";
+// ---------------------------------------------------------------------------
+// windows — DOCUMENTED (wmctrl 1.07 output format)
+// ---------------------------------------------------------------------------
+/**
+ * `wmctrl -l -G -p -x`. Nine fixed columns then a title with spaces in it;
+ * the second row's title repeats a column's text on purpose, because a parser
+ * that re-joins the split fields gets that one wrong.
+ */
+export const WMCTRL_STDOUT = [
+    "0x03c00003  0 2841   64   27   1280 800  Navigator.firefox     buildbox  Mozilla Firefox",
+    "0x04200005  0 3120   0    0    2560 1440 gnome-terminal-server.Gnome-terminal  buildbox  0x04200005 build log",
+    "0x05000007 -1 4001   200  180  900  600  code.Code             buildbox  index.ts - factory",
+].join("\n");
+// ---------------------------------------------------------------------------
+// presence — RECORDED on macOS 26.6.2, screen locked, ~54 minutes idle
+// ---------------------------------------------------------------------------
+/**
+ * `ioreg -r -c IOHIDSystem -d 1`. NANOSECONDS: 3_254_341_351_000 ns is 3254
+ * seconds. Reading it as milliseconds would report 3254 seconds of idleness
+ * as three, and make a locked machine look freshly used.
+ *
+ * The `-r` matters as much as the unit. `ioreg -c IOHIDSystem -d 1` — the
+ * form the survey sketch gave — prints this key NOWHERE on this OS version,
+ * because without `-r` the depth is measured from the root.
+ */
+export const IOREG_HIDIDLE_STDOUT = [
+    "+-o IOHIDSystem  <class IOHIDSystem, id 0x1000005b6, registered, matched, active>",
+    "  | {",
+    '  |   "IOClass" = "IOHIDSystem"',
+    '  |   "HIDIdleTime" = 3254341351000',
+    '  |   "IOProviderClass" = "IOResources"',
+    "  | }",
+].join("\n");
+/** The same machine, `ioreg -n Root -d1`, with the screen locked. */
+export const IOREG_ROOT_LOCKED_STDOUT = [
+    '      "IOConsoleLocked" = Yes',
+    '      "IOConsoleUsers" = ({"kCGSSessionOnConsoleKey"=Yes,"kCGSSessionIDKey"=257,"CGSSessionScreenIsLocked"=Yes,"kCGSSessionUserIDKey"=506})',
+].join("\n");
+/** An unlocked console, same keys. */
+export const IOREG_ROOT_UNLOCKED_STDOUT = [
+    '      "IOConsoleLocked" = No',
+    '      "IOConsoleUsers" = ({"kCGSSessionOnConsoleKey"=Yes,"CGSSessionScreenIsLocked"=No})',
+].join("\n");
+/** A macOS version that reports lock state somewhere this parser cannot see. */
+export const IOREG_ROOT_NO_LOCK_KEY_STDOUT = '      "IORegistryPlanes" = {"IOService"="IOService"}';
+/** DOCUMENTED: `loginctl show-session self -p LockedHint -p Type -p Active`. */
+export const LOGINCTL_STDOUT = "LockedHint=no\nType=x11\nActive=yes\n";
+/** DOCUMENTED: the Windows presence script's two lines. */
+export const WINDOWS_PRESENCE_STDOUT = "idleMs=42000\nlocked=no\n";
+// ---------------------------------------------------------------------------
+// printing — RECORDED on macOS 26.6.2, CUPS 2.4
+// ---------------------------------------------------------------------------
+/**
+ * `lpstat -p -d`, verbatim. Two printers in two DIFFERENT sentence shapes,
+ * an INDENTED continuation line that belongs to the row above it, and the
+ * default-destination line.
+ */
+export const LPSTAT_STDOUT = [
+    "printer Canon_MX490_series is idle.  enabled since Sun Jul 26 10:59:45 2026",
+    "printer Canon_TS5300_series now printing Canon_TS5300_series-33.  enabled since Sat Sep 12 00:00:20 2026",
+    "\tLooking for printer.",
+    "system default destination: Canon_MX490_series",
+].join("\n");
+/**
+ * A host whose scheduler is down. It lists NOTHING, which reads exactly like
+ * a host with no printers — the rule-6 case this fixture exists for.
+ */
+export const LPSTAT_NO_SCHEDULER_STDERR = "lpstat: Scheduler is not running.\n";
+/** DOCUMENTED: `lp` answers with prose and the job id is inside it. */
+export const LP_REQUEST_ID_STDOUT = "request id is Canon_MX490_series-34 (1 file(s))\n";
+// ---------------------------------------------------------------------------
+// power — DOCUMENTED (`ps -o command= -p <pid>`)
+// ---------------------------------------------------------------------------
+export const PS_CAFFEINATE_STDOUT = "caffeinate -i -m -t 1800\n";
+/** The same pid, now owned by something else entirely. */
+export const PS_REUSED_PID_STDOUT = "/usr/sbin/cupsd -l\n";

package/dist/host.d.ts

@@ -0,0 +1,99 @@
+/**
+ * The platforms this package makes decisions about.
+ *
+ * `"unsupported"` is a real member, not a placeholder: it is what every tool
+ * here returns `unavailable` for, and it is what an un-injected seam answers
+ * under test. Keeping it in the union means the exhaustive switch in each
+ * backend selector has to handle it, so a new tool cannot forget.
+ */
+export type HostPlatform = "darwin" | "linux" | "win32" | "unsupported";
+/** What `process.platform` actually says. Only the smoke test asks. */
+export declare function realHostPlatform(): HostPlatform;
+export declare function hostPlatform(): HostPlatform;
+/** Test seam: pretend to be another OS. */
+export declare function _setPlatform(platform: HostPlatform | undefined): void;
+/**
+ * The parts of the environment that decide whether a desktop is reachable.
+ *
+ * These are not configuration, they are *facts about the session*, and every
+ * one of them changes a tool's answer from "here it is" to "there is nothing
+ * to ask". Reading `process.env` directly inside a tool would mean a test's
+ * answer depended on whether the developer happened to be in an SSH session.
+ */
+export type SessionEnv = {
+    /** X11 display. Absent ⇒ `xclip`/`wmctrl` cannot connect at all. */
+    readonly DISPLAY: string | undefined;
+    /** Wayland socket name. */
+    readonly WAYLAND_DISPLAY: string | undefined;
+    /** `wl-paste` refuses without it even when WAYLAND_DISPLAY is set. */
+    readonly XDG_RUNTIME_DIR: string | undefined;
+    /** "x11" | "wayland" | "tty" on a logind session. */
+    readonly XDG_SESSION_TYPE: string | undefined;
+    /**
+     * The session bus `notify-send` posts to.
+     *
+     * Not in the first draft of this file, and its absence was a real gap: a
+     * notification does not go to the display server, it goes to a D-Bus
+     * service. With `DISPLAY` forwarded and this one dropped, libnotify falls
+     * back to autolaunching a bus — which on a headless box prints "Cannot
+     * autolaunch D-Bus without X11 $DISPLAY" and on a desktop box can start a
+     * SECOND private bus that no notification daemon is listening on, so the
+     * call succeeds and nothing is ever shown.
+     */
+    readonly DBUS_SESSION_BUS_ADDRESS: string | undefined;
+    /** Set by sshd ⇒ this is a remote shell, not the console. */
+    readonly SSH_CONNECTION: string | undefined;
+    readonly SSH_TTY: string | undefined;
+};
+/** An environment with no desktop in it — the hostile default under test. */
+export declare const HEADLESS_ENV: SessionEnv;
+export declare function sessionEnv(): SessionEnv;
+export declare function _setSessionEnv(env: SessionEnv | undefined): void;
+/** True when this process is talking to a machine over ssh, not sitting at it. */
+export declare function isRemoteShell(env?: SessionEnv): boolean;
+/**
+ * Is there a graphical session a Linux backend could talk to, and which kind?
+ *
+ * Four answers, never two. "I could not tell" is not "there is no desktop":
+ * a Wayland session whose `XDG_RUNTIME_DIR` is unset really has no reachable
+ * compositor (recorded: `wl-paste` prints "XDG_RUNTIME_DIR is invalid or not
+ * set in the environment"), but a session with neither variable set may
+ * simply be a service manager that scrubbed the environment.
+ */
+export type LinuxSession = {
+    readonly kind: "x11";
+    readonly display: string;
+} | {
+    readonly kind: "wayland";
+    readonly display: string;
+    readonly runtimeDir: string;
+} | {
+    readonly kind: "wayland-unreachable";
+    readonly reason: string;
+} | {
+    readonly kind: "none";
+    readonly reason: string;
+};
+export declare function linuxSession(env?: SessionEnv): LinuxSession;
+/**
+ * The session variables a Linux desktop backend needs, forwarded explicitly.
+ *
+ * Explicitly, because `childEnv` copies nothing from `process.env` — and
+ * because an X11 client with no `DISPLAY` does not fail fast, it fails after
+ * a connection attempt or, on some builds, blocks until the deadline.
+ */
+export declare function linuxDisplayEnv(env: SessionEnv): Record<string, string>;
+export type Clock = () => number;
+/**
+ * Epoch milliseconds.
+ *
+ * `PowerAssertion` writes a deadline into a state file and reports when an
+ * assertion expires, so its whole contract is clock arithmetic. Reading
+ * `Date.now()` inside the tool would make every assertion about an expiry a
+ * race with the wall clock (house rule: never assert wall-clock timing —
+ * inject the clock instead).
+ */
+export declare function now(): number;
+export declare function _setClock(clock: Clock | undefined): void;
+/** Put every seam in this file back. Called from `afterEach`. */
+export declare function _resetHostSeams(): void;

package/dist/host.js

@@ -0,0 +1,174 @@
+/**
+ * The seams, and the hostile default behind them.
+ *
+ * Every tool in this package reaches the operator's real desktop. That makes
+ * the machine the code runs on part of the answer twice over: the platform
+ * decides which backend exists at all (`pbpaste` is macOS-only, `wmctrl` is
+ * X11-only, `Out-Printer` is Windows-only), and the *session* decides whether
+ * that backend can do anything (an X11 clipboard with no `$DISPLAY` is not a
+ * slow clipboard, it is no clipboard).
+ *
+ * So the platform, the session environment, the clock and the child processes
+ * are all injected, and the suite never learns anything about the box it runs
+ * on except through a fixture somebody captured and pasted into `./fixtures`.
+ *
+ * ── THE HOSTILE DEFAULT ────────────────────────────────────────────────────
+ *
+ * `hostPlatform()` does not fall back to `process.platform`. It answers
+ * `"unsupported"` — a platform no backend in this package serves, on every
+ * machine, identically — whenever EITHER of two things is true:
+ *
+ *   1. A RUNNER IS INSTALLED. This is `@crewhaus/tool-pkgmgr`'s rule, and the
+ *      primary guard. A test that has installed a recorded runner has already
+ *      declared "I am not talking to this host"; if it then forgets to
+ *      declare which host it is pretending to be, every backend refuses
+ *      identically rather than taking the author's branch on macOS and a
+ *      different one on a two-core Linux CI box.
+ *   2. THE REAL-HOST GATE IS SHUT (`run.ts`'s `_realHostAllowed`, false under
+ *      `bun test`). The belt under the braces, for a test that never
+ *      installed the seam at all. See `run.ts` for why this package is
+ *      stricter than tool-pkgmgr about that case.
+ *
+ * That bug is not hypothetical: it cost this project a CI round in
+ * `tool-hostfs`, where one test relied on the ambient `process.platform`,
+ * passed on macOS and took a different branch on Linux. The cure is to make
+ * the ambient answer useless rather than to remember not to use it.
+ *
+ * `integration.test.ts` — the single test allowed near the real host — says so
+ * out loud by calling `_allowRealHost(true)`, and puts it back. It also
+ * asserts that the un-injected path then DOES read the real platform, so the
+ * guard above is provably a test-only condition rather than a package that
+ * refuses everywhere.
+ */
+import { _realHostAllowed, _runnerInstalled } from "./run";
+let platformOverride;
+function classifyPlatform(raw) {
+    if (raw === "darwin" || raw === "linux" || raw === "win32")
+        return raw;
+    return "unsupported";
+}
+/** What `process.platform` actually says. Only the smoke test asks. */
+export function realHostPlatform() {
+    return classifyPlatform(process.platform);
+}
+export function hostPlatform() {
+    if (platformOverride !== undefined)
+        return platformOverride;
+    if (_runnerInstalled())
+        return "unsupported";
+    return _realHostAllowed() ? classifyPlatform(process.platform) : "unsupported";
+}
+/** Test seam: pretend to be another OS. */
+export function _setPlatform(platform) {
+    platformOverride = platform;
+}
+const SESSION_KEYS = [
+    "DISPLAY",
+    "WAYLAND_DISPLAY",
+    "XDG_RUNTIME_DIR",
+    "XDG_SESSION_TYPE",
+    "DBUS_SESSION_BUS_ADDRESS",
+    "SSH_CONNECTION",
+    "SSH_TTY",
+];
+/** An environment with no desktop in it — the hostile default under test. */
+export const HEADLESS_ENV = Object.freeze({
+    DISPLAY: undefined,
+    WAYLAND_DISPLAY: undefined,
+    XDG_RUNTIME_DIR: undefined,
+    XDG_SESSION_TYPE: undefined,
+    DBUS_SESSION_BUS_ADDRESS: undefined,
+    SSH_CONNECTION: undefined,
+    SSH_TTY: undefined,
+});
+let envOverride;
+export function sessionEnv() {
+    if (envOverride !== undefined)
+        return envOverride;
+    if (_runnerInstalled() || !_realHostAllowed())
+        return HEADLESS_ENV;
+    const read = (key) => {
+        const value = process.env[key];
+        // An EMPTY `DISPLAY` is not a display. Treating `""` as set is how a
+        // headless host gets classified as an X11 session and then blocks on a
+        // clipboard read until its deadline.
+        return value === undefined || value === "" ? undefined : value;
+    };
+    const out = {};
+    for (const key of SESSION_KEYS)
+        out[key] = read(key);
+    return out;
+}
+export function _setSessionEnv(env) {
+    envOverride = env;
+}
+/** True when this process is talking to a machine over ssh, not sitting at it. */
+export function isRemoteShell(env = sessionEnv()) {
+    return env.SSH_CONNECTION !== undefined || env.SSH_TTY !== undefined;
+}
+export function linuxSession(env = sessionEnv()) {
+    if (env.WAYLAND_DISPLAY !== undefined) {
+        if (env.XDG_RUNTIME_DIR === undefined) {
+            return {
+                kind: "wayland-unreachable",
+                reason: "WAYLAND_DISPLAY is set but XDG_RUNTIME_DIR is not, so the compositor socket cannot be located",
+            };
+        }
+        return {
+            kind: "wayland",
+            display: env.WAYLAND_DISPLAY,
+            runtimeDir: env.XDG_RUNTIME_DIR,
+        };
+    }
+    if (env.DISPLAY !== undefined)
+        return { kind: "x11", display: env.DISPLAY };
+    return {
+        kind: "none",
+        reason: "neither DISPLAY nor WAYLAND_DISPLAY is set in this process's environment, so there is no graphical session to reach",
+    };
+}
+/**
+ * The session variables a Linux desktop backend needs, forwarded explicitly.
+ *
+ * Explicitly, because `childEnv` copies nothing from `process.env` — and
+ * because an X11 client with no `DISPLAY` does not fail fast, it fails after
+ * a connection attempt or, on some builds, blocks until the deadline.
+ */
+export function linuxDisplayEnv(env) {
+    const out = {};
+    if (env.DISPLAY !== undefined)
+        out["DISPLAY"] = env.DISPLAY;
+    if (env.WAYLAND_DISPLAY !== undefined)
+        out["WAYLAND_DISPLAY"] = env.WAYLAND_DISPLAY;
+    if (env.XDG_RUNTIME_DIR !== undefined)
+        out["XDG_RUNTIME_DIR"] = env.XDG_RUNTIME_DIR;
+    if (env.DBUS_SESSION_BUS_ADDRESS !== undefined) {
+        out["DBUS_SESSION_BUS_ADDRESS"] = env.DBUS_SESSION_BUS_ADDRESS;
+    }
+    return out;
+}
+let clockOverride;
+/**
+ * Epoch milliseconds.
+ *
+ * `PowerAssertion` writes a deadline into a state file and reports when an
+ * assertion expires, so its whole contract is clock arithmetic. Reading
+ * `Date.now()` inside the tool would make every assertion about an expiry a
+ * race with the wall clock (house rule: never assert wall-clock timing —
+ * inject the clock instead).
+ */
+export function now() {
+    return clockOverride === undefined ? Date.now() : clockOverride();
+}
+export function _setClock(clock) {
+    clockOverride = clock;
+}
+// ---------------------------------------------------------------------------
+// reset
+// ---------------------------------------------------------------------------
+/** Put every seam in this file back. Called from `afterEach`. */
+export function _resetHostSeams() {
+    platformOverride = undefined;
+    envOverride = undefined;
+    clockOverride = undefined;
+}

package/dist/index.d.ts

@@ -0,0 +1,21 @@
+import type { RegisteredTool } from "@crewhaus/tool-catalog";
+import { type HostPlatform } from "./host";
+import { type UnknownFact } from "./lib/outcome";
+export { _setRunner, _setDetacher, _resetRunSeams, _allowRealHost } from "./run";
+export type { Runner, Detacher, RunRequest, RunResult, DetachResult } from "./run";
+export { _setPlatform, _setSessionEnv, _setClock, _resetHostSeams, realHostPlatform, HEADLESS_ENV, } from "./host";
+export type { HostPlatform, SessionEnv } from "./host";
+export { _setFs } from "./lib/fsseam";
+export type { HostFs, PathFacts } from "./lib/fsseam";
+export { ToolPermissionError } from "./paths";
+export declare const clipboardRead: RegisteredTool;
+export declare const clipboardWrite: RegisteredTool;
+export declare const desktopNotify: RegisteredTool;
+export declare const openExternal: RegisteredTool;
+export declare const printDocument: RegisteredTool;
+export declare const windowList: RegisteredTool;
+export declare const userPresence: RegisteredTool;
+export declare const powerAssertion: RegisteredTool;
+/** Everything this package registers, in one place for the catalog wiring. */
+export declare const DESKTOP_TOOLS: ReadonlyArray<RegisteredTool>;
+export type { UnknownFact, HostPlatform as DesktopPlatform };