@crewhaus/tool-desktop 0.7.0

package/dist/lib/notify.js

@@ -0,0 +1,198 @@
+import { linuxDisplayEnv, linuxSession } from "../host";
+import { escapeXmlText, osascriptArgv, powershellArgv, registerAppleScript, registerPowerShellScript, stripXmlIllegalChars, } from "./escape";
+import { unavailable, unsupportedPlatform } from "./outcome";
+// ---------------------------------------------------------------------------
+// macOS
+// ---------------------------------------------------------------------------
+/**
+ * Four scripts rather than one built from flags.
+ *
+ * `display notification` has no runtime way to say "no subtitle" or "no
+ * sound" - the clause is present in the source or it is not. Choosing between
+ * four FROZEN constants keeps that decision out of string concatenation: a
+ * boolean picks a script, it never edits one.
+ *
+ * The sound name is a fixed literal for the same reason. A caller-chosen
+ * sound would have to be either an argv item (AppleScript cannot use a
+ * variable in the `sound name` clause) or interpolated source, and the second
+ * of those is the thing this package exists not to do.
+ */
+export const NOTIFY_PLAIN = registerAppleScript({
+    name: "notify-plain",
+    lines: ["display notification (item 2 of argv) with title (item 1 of argv)"],
+    arity: 2,
+});
+export const NOTIFY_SUBTITLE = registerAppleScript({
+    name: "notify-subtitle",
+    lines: [
+        "display notification (item 2 of argv) with title (item 1 of argv) subtitle (item 3 of argv)",
+    ],
+    arity: 3,
+});
+export const NOTIFY_PLAIN_SOUND = registerAppleScript({
+    name: "notify-plain-sound",
+    lines: [
+        'display notification (item 2 of argv) with title (item 1 of argv) sound name "Submarine"',
+    ],
+    arity: 2,
+});
+export const NOTIFY_SUBTITLE_SOUND = registerAppleScript({
+    name: "notify-subtitle-sound",
+    lines: [
+        'display notification (item 2 of argv) with title (item 1 of argv) subtitle (item 3 of argv) sound name "Submarine"',
+    ],
+    arity: 3,
+});
+// ---------------------------------------------------------------------------
+// Windows
+// ---------------------------------------------------------------------------
+/**
+ * The AppUserModelID a toast is shown under.
+ *
+ * Windows refuses to display a toast from an unregistered AUMID, so this is
+ * the shell's own PowerShell identity - the documented way to raise a toast
+ * without installing a Start-menu shortcut first. It is a fixed literal and
+ * never comes from a caller.
+ */
+export const WINDOWS_TOAST_APPID = "{1AC14E77-02E7-4E5D-B744-2EB1AE5198B7}\\WindowsPowerShell\\v1.0\\powershell.exe";
+export const WINDOWS_TOAST_SCRIPT = registerPowerShellScript({
+    name: "toast",
+    script: [
+        "[void][Windows.UI.Notifications.ToastNotificationManager, Windows.UI.Notifications, ContentType=WindowsRuntime]",
+        "$doc = New-Object Windows.Data.Xml.Dom.XmlDocument",
+        "$doc.LoadXml($env:CREWHAUS_TOAST_XML)",
+        "$toast = New-Object Windows.UI.Notifications.ToastNotification $doc",
+        "[Windows.UI.Notifications.ToastNotificationManager]::CreateToastNotifier($env:CREWHAUS_TOAST_APPID).Show($toast)",
+    ].join("; "),
+    reads: ["CREWHAUS_TOAST_XML", "CREWHAUS_TOAST_APPID"],
+});
+/**
+ * Build the toast document, with every caller value escaped.
+ *
+ * The result crosses to PowerShell through the environment, so this escaping
+ * is defence in depth rather than the only defence - but it is the part this
+ * suite can prove, which is why it lives here and not in the script.
+ */
+export function buildToastXml(input) {
+    let removed = 0;
+    const clean = (value) => {
+        const stripped = stripXmlIllegalChars(value);
+        removed += stripped.removed;
+        return escapeXmlText(stripped.text);
+    };
+    const lines = [clean(input.title), clean(input.body)];
+    if (input.subtitle !== undefined)
+        lines.push(clean(input.subtitle));
+    const texts = lines.map((line) => `<text>${line}</text>`).join("");
+    const audio = input.sound
+        ? '<audio src="ms-winsoundevent:Notification.Default"/>'
+        : '<audio silent="true"/>';
+    return {
+        xml: `<toast><visual><binding template="ToastGeneric">${texts}</binding></visual>${audio}</toast>`,
+        sanitized: removed > 0,
+        removedChars: removed,
+    };
+}
+export function planNotify(platform, env, input) {
+    switch (platform) {
+        case "darwin": {
+            const hasSubtitle = input.subtitle !== undefined;
+            const script = hasSubtitle
+                ? input.sound
+                    ? NOTIFY_SUBTITLE_SOUND
+                    : NOTIFY_SUBTITLE
+                : input.sound
+                    ? NOTIFY_PLAIN_SOUND
+                    : NOTIFY_PLAIN;
+            const values = hasSubtitle
+                ? [input.title, input.body, input.subtitle]
+                : [input.title, input.body];
+            return {
+                ok: true,
+                backend: "osascript display notification",
+                request: { argv: osascriptArgv(script, values) },
+            };
+        }
+        case "linux": {
+            const session = linuxSession(env);
+            if (session.kind === "none" || session.kind === "wayland-unreachable") {
+                return { ok: false, unavailable: unavailable("session", session.reason) };
+            }
+            // `linuxDisplayEnv` forwards DBUS_SESSION_BUS_ADDRESS as well as the
+            // display. That matters more here than anywhere else in the package: a
+            // notification does not go to the display server, it goes to a D-Bus
+            // service, and libnotify with no bus address either autolaunches a
+            // private bus nobody is listening on (exit 0, nothing shown) or prints
+            // "Cannot autolaunch D-Bus without X11 $DISPLAY".
+            const displayEnv = linuxDisplayEnv(env);
+            // Every option uses the `--option=value` form, so an option's value can
+            // never be mistaken for the next option; every POSITIONAL goes after
+            // `--`, so a summary of "-u" is a summary. Recorded on libnotify 0.8.1:
+            // without `--`, `notify-send "-u" "body"` answers "Unknown urgency body
+            // specified" - the summary became a flag and the body became its value.
+            const argv = [
+                "notify-send",
+                "--app-name=crewhaus",
+                `--urgency=${input.urgency}`,
+                // Sent ONLY when the caller asked for one. libnotify's default is
+                // NOTIFY_EXPIRES_DEFAULT (-1, "the daemon decides") while 0 is
+                // NOTIFY_EXPIRES_NEVER — so passing 0 as a stand-in for "no
+                // preference" pins the notification on screen until it is dismissed,
+                // which is the opposite of what it reads like.
+                ...(input.expireMs === undefined ? [] : [`--expire-time=${Math.trunc(input.expireMs)}`]),
+                "--",
+                input.title,
+                // A subtitle has no place in the FreeDesktop notification spec, so it
+                // is folded into the body rather than dropped silently.
+                input.subtitle === undefined ? input.body : `${input.subtitle}\n${input.body}`,
+            ];
+            return { ok: true, backend: "notify-send", request: { argv, env: displayEnv } };
+        }
+        case "win32": {
+            const doc = buildToastXml(input);
+            const built = powershellArgv(WINDOWS_TOAST_SCRIPT, {
+                CREWHAUS_TOAST_XML: doc.xml,
+                CREWHAUS_TOAST_APPID: WINDOWS_TOAST_APPID,
+            });
+            return {
+                ok: true,
+                backend: "powershell ToastNotification",
+                request: { argv: built.argv, env: built.env },
+                ...(doc.sanitized ? { sanitized: true } : {}),
+            };
+        }
+        default:
+            return { ok: false, unavailable: unsupportedPlatform(platform, "notification") };
+    }
+}
+/** Stderr that means there is no notification daemon to hand it to. */
+const NO_DAEMON = [
+    // Recorded, Debian 12 / libnotify 0.8.1, no DISPLAY.
+    /Cannot autolaunch D-Bus without X11/i,
+    /Failed to connect to (the )?(session )?bus/i,
+    /Failed to connect to a Wayland server/i,
+];
+export function classifyNotify(result) {
+    if (result.refused === true)
+        return { outcome: "failed", reason: result.stderr };
+    if (result.missing) {
+        return unavailable("program", "the notifier for this platform is not installed on this host (on Linux that is notify-send, from libnotify-bin)");
+    }
+    if (result.timedOut) {
+        return {
+            outcome: "failed",
+            reason: "the notifier did not finish within its timeout and was killed - whether the notification was posted is unknown",
+        };
+    }
+    if (result.code === 0)
+        return { outcome: "dispatched" };
+    for (const pattern of NO_DAEMON) {
+        if (pattern.test(result.stderr)) {
+            return unavailable("session", `there is no notification daemon to post to: ${result.stderr.trim()}`);
+        }
+    }
+    return {
+        outcome: "failed",
+        reason: `the notifier exited ${result.code}: ${result.stderr.trim()}`,
+    };
+}

package/dist/lib/open.d.ts

@@ -0,0 +1,149 @@
+/**
+ * `OpenExternal` — handing something to whatever the operating system has
+ * registered for it, which is the widest-reaching thing in this package.
+ *
+ * "Open this" and "run this" are the SAME GESTURE to a desktop. `open` on a
+ * `.command` file runs it in Terminal; `xdg-open` on a file whose type is
+ * associated with an interpreter runs it; `Start-Process` on a `.ps1` or a
+ * `.bat` runs it. And the URL side is worse than the file side, because the
+ * scheme table on a real machine is enormous and mostly undocumented:
+ * `file://` reaches the filesystem with no containment, `smb://` mounts a
+ * remote share (and leaks an authentication handshake to whoever owns the
+ * host in the URL), and Windows `ms-*` handlers reach settings pages, the
+ * Store, and on unpatched builds have been argument-injection vectors in
+ * their own right.
+ *
+ * SO THE GATE IS AN ALLOW-LIST, AND IT IS SHORT.
+ *
+ *   - Anything with a URI scheme must have one of `https`, `http`, `mailto`.
+ *     Every other scheme is refused by name. There is no input that widens
+ *     this set — `allowSchemes` can only NARROW it, because a knob that
+ *     re-enables `smb:` is the hole with extra steps.
+ *   - THE STRING THAT IS CHECKED IS THE STRING THAT IS OPENED. An http(s) URL
+ *     is handed to the desktop in the WHATWG parser's NORMALISED form, not as
+ *     the caller typed it, because a gate that validates one spelling and
+ *     passes on another is not a gate. A backslash — where WHATWG and CFURL
+ *     disagree outright — is refused rather than folded, and credentials
+ *     before the `@` are refused too: they end up in a process listing and in
+ *     the transcript, and `https://google.com@evil.example/` reads as the
+ *     host it is not.
+ *   - A `mailto:` may carry only the headers RFC 6068 calls safe. `attach=`
+ *     is the reason: a client that honours it reads a local file into a
+ *     message, which is `file:`'s hole with a mail client in the middle.
+ *   - Anything without a scheme is a PATH, and goes through `../paths.ts`'s
+ *     containment (the workspace root, resolved, symlinks followed) before it
+ *     is allowed to exist. A local file is opened by naming its path, never
+ *     by building a `file://` URL — that way there is exactly one code path
+ *     that decides whether a path is reachable.
+ *   - An EXECUTABLE file is refused even inside the workspace. It is the one
+ *     case where the caller may have meant "open" and the OS will hear "run".
+ *
+ * The three openers also disagree about `--`, so this file does not assume:
+ *   macOS     `open` honours it. Verified on 26.6.2: `open -- -a` answers
+ *             "The file /private/tmp/-a does not exist", while `open -a`
+ *             answers "open: option requires an argument -- a".
+ *   Linux     `xdg-open` does NOT. It rejects any argument beginning with `-`
+ *             as an unknown option, `--` included, so passing one would break
+ *             every call. Flag-shaped targets are REFUSED instead.
+ *   Windows   argv is not the channel at all — the target crosses in the
+ *             environment and `Start-Process -FilePath $env:…` reads it. Not
+ *             the `start` shell builtin, which treats a first quoted argument
+ *             as a window title and splits an unquoted one on `&`, so a URL
+ *             with a query string opens something other than what was asked.
+ */
+import { type HostPlatform, type SessionEnv } from "../host";
+import type { RunRequest } from "../run";
+import { type PathFacts } from "./fsseam";
+import { type Unavailable } from "./outcome";
+/**
+ * The schemes this package will hand to the OS, and the complete list.
+ *
+ * Deliberately three. `mailto` is here because composing a message is the one
+ * non-web thing a harness plausibly wants, and it reaches a compose window
+ * rather than a filesystem or a network share.
+ */
+export declare const OPENABLE_SCHEMES: readonly ["https", "http", "mailto"];
+export type OpenableScheme = (typeof OPENABLE_SCHEMES)[number];
+export declare const WINDOWS_OPEN_SCRIPT: import("./escape").PowerShellScript;
+/** What the caller's string turned out to be. */
+export type OpenTarget = {
+    readonly kind: "url";
+    readonly scheme: OpenableScheme;
+    /**
+     * THE STRING THAT IS HANDED TO THE OPERATING SYSTEM, and the string this
+     * function validated — they are the same object on purpose. See
+     * `classifyTarget`.
+     */
+    readonly value: string;
+    /** The caller's own text, when normalising changed it. For the result. */
+    readonly given?: string;
+} | {
+    readonly kind: "path";
+    readonly value: string;
+};
+export type TargetDecision = {
+    readonly ok: true;
+    readonly target: OpenTarget;
+} | {
+    readonly ok: false;
+    readonly reason: string;
+    readonly scheme?: string;
+};
+/**
+ * Does this string carry a URI scheme?
+ *
+ * RFC 3986: `ALPHA *( ALPHA / DIGIT / "+" / "-" / "." ) ":"`. The
+ * single-letter carve-out is for Windows: `C:\Users\…` matches the scheme
+ * production exactly, and classifying a drive path as a `c:` URL would refuse
+ * every absolute Windows path with a baffling message.
+ */
+export declare function uriScheme(value: string): string | undefined;
+/**
+ * Decide what a caller's target is, or refuse it.
+ *
+ * Returns the URL case resolved; a path is handed back for the caller to
+ * contain, because containment needs the filesystem and this function is
+ * pure.
+ */
+export declare function classifyTarget(target: string, allowed: readonly OpenableScheme[]): TargetDecision;
+/** The lowercase extension, or `""`. */
+export declare function extensionOf(path: string): string;
+/**
+ * Why a contained path is still not openable.
+ *
+ * `undefined` means it is. The two executable refusals are the substantive
+ * ones — see the header and `DANGEROUS_EXTENSIONS`.
+ */
+export declare function refusePath(absolutePath: string, facts: PathFacts | undefined): string | undefined;
+export type OpenPlan = {
+    readonly ok: true;
+    readonly backend: string;
+    readonly request: Omit<RunRequest, "timeoutMs">;
+} | {
+    readonly ok: false;
+    readonly unavailable: Unavailable;
+};
+/** Build the argv (or the env channel) that would open an accepted target. */
+export declare function planOpen(platform: HostPlatform, env: SessionEnv, value: string): OpenPlan;
+/**
+ * What an opener reported.
+ *
+ * `handedOff` rather than `opened`: `open` and `xdg-open` both return as soon
+ * as the handler has been asked, long before anything is on screen, and
+ * neither reports what the handler then did. Claiming more than that is the
+ * "silent success" rule 5 names.
+ */
+export type OpenOutcome = {
+    readonly outcome: "handedOff";
+} | Unavailable | {
+    readonly outcome: "failed";
+    readonly reason: string;
+};
+export declare function classifyOpen(backend: string, result: {
+    readonly code: number;
+    readonly stdout: string;
+    readonly stderr: string;
+    readonly timedOut: boolean;
+    readonly missing: boolean;
+    readonly refused?: boolean;
+}): OpenOutcome;