@crewhaus/tool-desktop 0.7.0

package/dist/lib/escape.js

@@ -0,0 +1,338 @@
+/**
+ * THE SECURITY BOUNDARY OF THIS PACKAGE.
+ *
+ * Every tool here carries a caller-supplied string to a platform API, and on
+ * two of the three platforms that API takes SOURCE CODE rather than data.
+ *
+ *   macOS   `osascript -e '<statement>'` compiles AppleScript. A title
+ *           interpolated into `display notification "<title>"` is not text in
+ *           a dialog — it is program text. A single double quote ends the
+ *           string literal and everything after it RUNS, with the operator's
+ *           automation permissions.
+ *   Windows `powershell.exe -Command <script>` compiles PowerShell, and the
+ *           toast payload inside it is an XML document. A body containing
+ *           `</toast>` closes the document early; a body containing `&`
+ *           makes it malformed. Same shape, one layer over.
+ *   Linux   `notify-send` takes argv, which is the easy case — except that a
+ *           summary beginning with `-` is still read as a FLAG. Recorded on
+ *           Debian 12 / libnotify 0.8.1: `notify-send "-u" "body"` prints
+ *           "Unknown urgency body specified", because `-u` was consumed as
+ *           the urgency flag and the body became its argument.
+ *
+ * THE THREE RULES THIS FILE ENFORCES.
+ *
+ * 1. NO SCRIPT SOURCE IS EVER BUILT AT CALL TIME. Every AppleScript and every
+ *    PowerShell script in this package is a frozen module constant registered
+ *    here at load. `osascriptArgv` and `powershellArgv` REFUSE a script object
+ *    that is not in that registry, so "just interpolate it this once" cannot
+ *    compile. This is stronger than escaping and needs no escaper to be
+ *    correct: there is nothing to escape into.
+ * 2. CALLER VALUES TRAVEL BESIDE THE PROGRAM, NEVER INSIDE IT.
+ *      - macOS: as ARGV, after `--`, read back with `item N of argv`. Verified
+ *        on macOS 26.6.2 (Darwin 25.6.0) while writing this:
+ *
+ *          $ osascript -e 'on run argv' \
+ *              -e 'return (item 1 of argv) & "|" & (item 2 of argv)' \
+ *              -e 'end run' -- '-e' 'say "hi"; display dialog "x"'
+ *          -e|say "hi"; display dialog "x"
+ *
+ *        Both hostile values came back as DATA. Nothing was spoken and no
+ *        dialog appeared. Without the `--`, the same run answers
+ *        "osascript: option requires an argument -- e", which is why the `--`
+ *        is mandatory rather than decorative.
+ *      - Windows: through the child's ENVIRONMENT. Argv is not a safe channel
+ *        for PowerShell — `powershell -Command <script> a b c` CONCATENATES
+ *        the trailing arguments onto the command string, so a value passed
+ *        "as an argument" is still source.
+ *      - Linux: as argv after `--`.
+ * 3. WHAT CANNOT TRAVEL BESIDE THE PROGRAM IS VALIDATED, NOT ESCAPED. The
+ *    Windows toast body has to end up inside an XML document, so it is
+ *    escaped here (`escapeXmlText`) and the FINISHED DOCUMENT is what crosses
+ *    the environment channel — one testable escaper, applied once, whose
+ *    output never becomes PowerShell source. Everything else that would have
+ *    to be interpolated (a printer name, a page range) is matched against a
+ *    closed pattern and refused if it does not fit.
+ */
+const APPLE_SCRIPTS = new Set();
+const POWERSHELL_SCRIPTS = new Set();
+/**
+ * Declare an AppleScript. Only a registered script may be run, and the only
+ * place `registerAppleScript` is called is at module scope in this package —
+ * so a script cannot be assembled from a caller's value and then run.
+ */
+export function registerAppleScript(script) {
+    const frozen = Object.freeze({
+        name: script.name,
+        lines: Object.freeze([...script.lines]),
+        arity: script.arity,
+    });
+    APPLE_SCRIPTS.add(frozen);
+    return frozen;
+}
+export function registerPowerShellScript(script) {
+    const frozen = Object.freeze({
+        name: script.name,
+        script: script.script,
+        reads: Object.freeze([...script.reads]),
+    });
+    POWERSHELL_SCRIPTS.add(frozen);
+    return frozen;
+}
+/**
+ * Every registered PowerShell script's SOURCE.
+ *
+ * Exported for one assertion: `every powershell argv is a registered script
+ * with nothing appended` in index.test.ts checks that the last element of
+ * every recorded `powershell.exe` argv is one of these, and that there is
+ * nothing after it. That narrow, checkable guarantee is what lets `run.ts`
+ * carve PowerShell out of its blanket shell refusal.
+ */
+export function registeredPowerShellSources() {
+    return new Set([...POWERSHELL_SCRIPTS].map((s) => s.script));
+}
+/** Raised when something tries to run source this file did not register. */
+export class UnregisteredScriptError extends Error {
+    constructor(kind, name) {
+        super(`refusing to run an unregistered ${kind} script "${name}": script source in this package is a frozen module constant, never built at call time`);
+        this.name = "UnregisteredScriptError";
+    }
+}
+// ---------------------------------------------------------------------------
+// macOS — osascript
+// ---------------------------------------------------------------------------
+/**
+ * `osascript` with the caller's values as `argv`.
+ *
+ * The shape is `osascript -e 'on run argv' -e '<statement>' ... -e 'end run'
+ * -- <value> ...`, which is the whole point: the statements are compiled, the
+ * values are not. `--` is mandatory and is not decoration — see the header.
+ */
+export function osascriptArgv(script, values = []) {
+    if (!APPLE_SCRIPTS.has(script))
+        throw new UnregisteredScriptError("AppleScript", script.name);
+    if (values.length !== script.arity) {
+        throw new Error(`AppleScript "${script.name}" reads ${script.arity} argv item(s) but ${values.length} were supplied`);
+    }
+    const argv = ["osascript", "-e", "on run argv"];
+    for (const line of script.lines) {
+        argv.push("-e", line);
+    }
+    argv.push("-e", "end run", "--", ...values);
+    return Object.freeze(argv);
+}
+/**
+ * The statements of an osascript argv — everything the compiler sees.
+ *
+ * Used by the tests that assert a hostile value never reaches program text,
+ * and by `dryRun` so a caller can read the source that would run.
+ */
+export function osascriptProgramText(argv) {
+    const text = [];
+    for (let i = 0; i < argv.length; i += 1) {
+        if (argv[i] === "--")
+            break;
+        if (argv[i] === "-e") {
+            const line = argv[i + 1];
+            if (line !== undefined)
+                text.push(line);
+            i += 1;
+        }
+    }
+    return text.join("\n");
+}
+/**
+ * An AppleScript error line, split into its code and message.
+ *
+ * Recorded on macOS 26.6.2 with Accessibility NOT granted:
+ *   `44:87: execution error: System Events got an error: osascript is not
+ *    allowed assistive access. (-25211)`
+ * The code is what distinguishes "you have not granted this" from "the script
+ * was wrong", and the two must not become the same result.
+ */
+export function parseOsascriptError(stderr) {
+    const trimmed = stderr.trim();
+    const codeMatch = /\((-?\d+)\)\s*$/.exec(trimmed);
+    const code = codeMatch?.[1] === undefined ? null : Number(codeMatch[1]);
+    const afterPrefix = /execution error:\s*(.*)$/s.exec(trimmed);
+    const message = (afterPrefix?.[1] ?? trimmed).trim();
+    return { code, message };
+}
+/**
+ * macOS error codes that mean "the operator has not granted this", as
+ * distinct from "the script failed".
+ *
+ * -25211 and -1728 are both reported by System Events for an un-granted
+ * Accessibility request, which is why this is a set and not an equality
+ * check. -1743 is the Automation (Apple-events) denial, a DIFFERENT grant in
+ * a DIFFERENT pane of System Settings, so its message names the right one.
+ */
+export const APPLESCRIPT_PERMISSION_CODES = new Map([
+    [
+        -25211,
+        "macOS Accessibility is not granted — System Settings > Privacy & Security > Accessibility, and add the program running this harness",
+    ],
+    [
+        -1728,
+        "macOS Accessibility is not granted — System Settings > Privacy & Security > Accessibility, and add the program running this harness",
+    ],
+    [
+        -1743,
+        "macOS Automation is not granted — System Settings > Privacy & Security > Automation, and allow this program to control System Events",
+    ],
+]);
+/**
+ * True when a failed osascript run failed for want of a PERMISSION.
+ *
+ * The message test is a fallback for a future OS that changes the code but
+ * keeps the sentence; a code match is preferred because a message is
+ * localised and this package pins `LC_ALL=C` for the commands it parses but
+ * cannot pin the language of a macOS framework string.
+ */
+export function osascriptPermissionReason(stderr) {
+    const { code, message } = parseOsascriptError(stderr);
+    if (code !== null) {
+        const known = APPLESCRIPT_PERMISSION_CODES.get(code);
+        if (known !== undefined)
+            return known;
+    }
+    if (/not allowed assistive access/i.test(message)) {
+        return APPLESCRIPT_PERMISSION_CODES.get(-25211);
+    }
+    if (/not authori[sz]ed to send apple events/i.test(message)) {
+        return APPLESCRIPT_PERMISSION_CODES.get(-1743);
+    }
+    return undefined;
+}
+// ---------------------------------------------------------------------------
+// Windows — PowerShell and XML
+// ---------------------------------------------------------------------------
+/** The fixed prefix for every PowerShell invocation this package makes. */
+export const POWERSHELL_FLAGS = Object.freeze([
+    "-NoProfile",
+    "-NonInteractive",
+    "-ExecutionPolicy",
+    "Bypass",
+    "-Command",
+]);
+/**
+ * `powershell.exe` running a registered script, with caller values in the
+ * ENVIRONMENT.
+ *
+ * Nothing is appended after the script: `powershell -Command <script> a b`
+ * concatenates `a b` onto the command string, which would put a caller's
+ * value back into source. The refusal below makes that impossible to write
+ * by accident — the env keys supplied must match the script's declared
+ * `reads` EXACTLY, so neither an unread extra nor a missing one gets through.
+ */
+export function powershellArgv(script, env) {
+    if (!POWERSHELL_SCRIPTS.has(script)) {
+        throw new UnregisteredScriptError("PowerShell", script.name);
+    }
+    const supplied = Object.keys(env).sort();
+    const expected = [...script.reads].sort();
+    if (supplied.join(",") !== expected.join(",")) {
+        throw new Error(`PowerShell script "${script.name}" reads [${expected.join(", ")}] but was given [${supplied.join(", ")}]`);
+    }
+    return {
+        argv: Object.freeze(["powershell.exe", ...POWERSHELL_FLAGS, script.script]),
+        env: Object.freeze({ ...env }),
+    };
+}
+/**
+ * XML text escaping for the Windows toast payload.
+ *
+ * This is the one place in the package where a caller's value is put INSIDE
+ * something it could otherwise restructure, and it is done here — in
+ * TypeScript, where it can be tested against `</toast>`, `&`, `<`, `"`, a
+ * backslash and a newline — rather than in PowerShell, where the same
+ * escaping would be invisible to this suite.
+ *
+ * The finished document then crosses to PowerShell through the environment,
+ * so even the ESCAPED value is never part of the program text. Escaping is
+ * the second line of defence here, not the first.
+ *
+ * `'` and `"` are escaped although an XML text node does not require it: the
+ * value also has to survive an attribute position in a future template, and
+ * an escaper whose correctness depends on where its output is pasted is the
+ * kind that eventually is not.
+ */
+export function escapeXmlText(value) {
+    return value
+        .replace(/&/g, "&amp;")
+        .replace(/</g, "&lt;")
+        .replace(/>/g, "&gt;")
+        .replace(/"/g, "&quot;")
+        .replace(/'/g, "&apos;");
+}
+/*
+ * The three classes of character an XML 1.0 document cannot carry.
+ *
+ * WRITTEN AS `\u` ESCAPES, NEVER `\x` AND NEVER THE RAW BYTE. House rule 13,
+ * and the earlier draft of this file broke it: it contained the literal bytes
+ * 0x00, 0x08, 0x0B, 0x0C, 0x0E, 0x1F and 0x7F inside the character class, so
+ * `file(1)` reported this source as "data" and `grep` refused to search it.
+ * biome folds `\x` escapes into raw bytes on format, and bun 1.3.11 (the CI
+ * runtime) then rejects the class as "range out of order" while the 1.3.14
+ * here accepts it — a package that compiles on the author's machine and not
+ * on the box that ships it.
+ *
+ * Kept as three separate one-line constants so the `biome-ignore` can sit
+ * DIRECTLY above the only line that needs it. A suppression with anything in
+ * between is reported as unused AND leaves the rule firing.
+ */
+// biome-ignore lint/suspicious/noControlCharactersInRegex: finding control characters is the entire job here.
+const XML_ILLEGAL_C0 = /[\u0000-\u0008\u000B\u000C\u000E-\u001F\u007F]/g;
+/** An unpaired surrogate is not a character; `LoadXml` throws on one. */
+const XML_LONE_SURROGATE = /[\uD800-\uDBFF](?![\uDC00-\uDFFF])|(?<![\uD800-\uDBFF])[\uDC00-\uDFFF]/g;
+/** The two permanent non-characters at the end of the BMP. */
+const XML_NONCHARACTER = /[￾￿]/g;
+/**
+ * Strip what an XML 1.0 document cannot represent.
+ *
+ * A C0 control such as U+0001 has no escape in XML 1.0 — the numeric
+ * reference for it is itself illegal — so `LoadXml` throws on the document
+ * rather than showing a broken toast. Dropping it is the only option that
+ * still delivers the message, and the tool SAYS it did (`sanitized`) rather
+ * than silently changing what the operator asked to show. TAB, LF and CR are
+ * legal and are kept.
+ *
+ * U+007F (DEL) is in fact LEGAL in XML 1.0 — it is above U+0020 — and is
+ * dropped here anyway, because it is a discouraged character that no
+ * notification is improved by and its removal is reported like any other.
+ * Saying so is the point: an escaper whose comment overstates what it is
+ * doing is one somebody later "simplifies" on the strength of the comment.
+ */
+export function stripXmlIllegalChars(value) {
+    const cleaned = value
+        .replace(XML_ILLEGAL_C0, "")
+        .replace(XML_LONE_SURROGATE, "")
+        .replace(XML_NONCHARACTER, "");
+    return { text: cleaned, removed: value.length - cleaned.length };
+}
+// ---------------------------------------------------------------------------
+// argv hygiene for programs with no `--`
+// ---------------------------------------------------------------------------
+/**
+ * Would this value be read as an OPTION rather than as a value?
+ *
+ * `--` solves this wherever the program supports it. Verified on macOS
+ * 26.6.2: `open -- -a` answers "The file /private/tmp/-a does not exist",
+ * while `open -a` answers "open: option requires an argument -- a". Where a
+ * program documents no `--` — CUPS `lp` and `lpstat` do not — the answer is
+ * not to escape but to REFUSE, and to say so. This repo has already shipped
+ * one argument injection of exactly this shape (`gitBranchCreate({name:"-D"})`
+ * ran `git branch -D victim`).
+ */
+export function looksLikeFlag(value) {
+    return value.startsWith("-");
+}
+/**
+ * A printer/queue name that can safely be an argv element.
+ *
+ * CUPS destination names are documented as printable ASCII without space,
+ * `/`, `#` or `@`; this is stricter still, and deliberately excludes a
+ * leading `-`.
+ */
+export const SAFE_DESTINATION = /^[A-Za-z0-9][A-Za-z0-9_.-]{0,126}$/;
+/** A CUPS `page-ranges` value: `1`, `1-4`, `1,3,5-9`. Nothing else. */
+export const SAFE_PAGE_RANGES = /^\d{1,6}(-\d{1,6})?(,\d{1,6}(-\d{1,6})?)*$/;

package/dist/lib/fsseam.d.ts

@@ -0,0 +1,23 @@
+/** What this package needs to know about a path, and nothing else. */
+export type PathFacts = {
+    readonly exists: boolean;
+    readonly isDirectory: boolean;
+    readonly isFile: boolean;
+    /** POSIX mode bits. 0 on a platform that has none worth reading. */
+    readonly mode: number;
+    readonly sizeBytes: number;
+};
+export type HostFs = {
+    stat(absolutePath: string): PathFacts | undefined;
+    readText(absolutePath: string): string | undefined;
+    /** Write via a temporary file and a rename, so a crash cannot leave half a
+     *  state file behind for the next call to parse. */
+    writeTextAtomic(absolutePath: string, text: string): void;
+    remove(absolutePath: string): void;
+};
+export declare function fs(): HostFs;
+export declare function _setFs(replacement: HostFs | undefined): void;
+/** The owner/group/other execute bits. */
+export declare const EXEC_BITS = 73;
+/** True when the OS would treat this file as something to RUN. */
+export declare function isExecutable(facts: PathFacts): boolean;

package/dist/lib/fsseam.js

@@ -0,0 +1,73 @@
+/**
+ * The filesystem seam.
+ *
+ * Two tools need one. `OpenExternal` has to know whether the thing it is
+ * about to hand to the operating system is a directory and whether it is
+ * EXECUTABLE, because "open this" and "run this" are the same gesture to a
+ * desktop and only one of them is what a caller meant. `PowerAssertion` has
+ * to remember a held inhibitor across tool calls, which means a file.
+ *
+ * Both go through here for the same reason the commands go through `./run`:
+ * a test that made a real file with a real mode bit would be asserting the
+ * umask of whoever ran it, and a test that wrote a real state file would be
+ * racing every other test in the same process.
+ */
+import { mkdirSync, readFileSync, renameSync, rmSync, statSync, writeFileSync, } from "node:fs";
+import { dirname } from "node:path";
+const nodeFs = {
+    stat(absolutePath) {
+        let stats;
+        try {
+            // `statSync`, not `lstatSync`: the question is what the OS would OPEN,
+            // and a symlink to a shell script is as executable as the script. The
+            // containment check in ./paths.ts has already resolved the link and
+            // proved the destination is inside the workspace.
+            stats = statSync(absolutePath, { throwIfNoEntry: false });
+        }
+        catch {
+            // A path whose parent is unreadable throws EACCES rather than returning
+            // undefined. An unprobeable path is treated as absent, which every
+            // caller here turns into a refusal rather than a guess.
+            return undefined;
+        }
+        if (stats === undefined)
+            return undefined;
+        return {
+            exists: true,
+            isDirectory: stats.isDirectory(),
+            isFile: stats.isFile(),
+            mode: stats.mode,
+            sizeBytes: stats.size,
+        };
+    },
+    readText(absolutePath) {
+        try {
+            return readFileSync(absolutePath, "utf-8");
+        }
+        catch {
+            return undefined;
+        }
+    },
+    writeTextAtomic(absolutePath, text) {
+        mkdirSync(dirname(absolutePath), { recursive: true });
+        const temp = `${absolutePath}.${process.pid}.tmp`;
+        writeFileSync(temp, text, { mode: 0o600 });
+        renameSync(temp, absolutePath);
+    },
+    remove(absolutePath) {
+        rmSync(absolutePath, { force: true });
+    },
+};
+let fsOverride;
+export function fs() {
+    return fsOverride ?? nodeFs;
+}
+export function _setFs(replacement) {
+    fsOverride = replacement;
+}
+/** The owner/group/other execute bits. */
+export const EXEC_BITS = 0o111;
+/** True when the OS would treat this file as something to RUN. */
+export function isExecutable(facts) {
+    return (facts.mode & EXEC_BITS) !== 0;
+}

package/dist/lib/notify.d.ts

@@ -0,0 +1,110 @@
+/**
+ * DesktopNotify's backends.
+ *
+ * This is the tool the escaping rule was written for. On macOS the notifier
+ * is a COMPILER: `osascript -e 'display notification "<body>"'` puts the
+ * caller's body inside a string literal in a program, and one double quote in
+ * it ends the literal and turns the rest into statements. On Windows the
+ * payload is an XML DOCUMENT inside a PowerShell script, so `</toast>` and
+ * `&` do the same job one layer over. Only Linux takes plain argv - and there
+ * a summary beginning with `-` is still read as a flag.
+ *
+ * So: the AppleScript is four frozen constants that read `item N of argv`,
+ * the toast XML is built and escaped in TypeScript and crosses to PowerShell
+ * through the ENVIRONMENT, and every notify-send positional goes after `--`.
+ * See ./escape.ts for why each of those is the shape it is.
+ */
+import type { SessionEnv } from "../host";
+import { type HostPlatform } from "../host";
+import type { RunRequest } from "../run";
+import { type Unavailable } from "./outcome";
+export type NotifyUrgency = "low" | "normal" | "critical";
+/**
+ * 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 declare const NOTIFY_PLAIN: import("./escape").AppleScript;
+export declare const NOTIFY_SUBTITLE: import("./escape").AppleScript;
+export declare const NOTIFY_PLAIN_SOUND: import("./escape").AppleScript;
+export declare const NOTIFY_SUBTITLE_SOUND: import("./escape").AppleScript;
+/**
+ * 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 declare const WINDOWS_TOAST_APPID = "{1AC14E77-02E7-4E5D-B744-2EB1AE5198B7}\\WindowsPowerShell\\v1.0\\powershell.exe";
+export declare const WINDOWS_TOAST_SCRIPT: import("./escape").PowerShellScript;
+export type ToastDocument = {
+    readonly xml: string;
+    /**
+     * True when characters XML 1.0 cannot carry at all were dropped. Reported
+     * rather than silent: the operator asked for a particular message and got a
+     * slightly different one.
+     */
+    readonly sanitized: boolean;
+    readonly removedChars: number;
+};
+/**
+ * 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 declare function buildToastXml(input: {
+    readonly title: string;
+    readonly body: string;
+    readonly subtitle?: string;
+    readonly sound: boolean;
+}): ToastDocument;
+export type NotifyPlan = {
+    readonly ok: true;
+    readonly backend: string;
+    readonly request: Omit<RunRequest, "timeoutMs">;
+    readonly sanitized?: boolean;
+} | {
+    readonly ok: false;
+    readonly unavailable: Unavailable;
+};
+export declare function planNotify(platform: HostPlatform, env: SessionEnv, input: {
+    readonly title: string;
+    readonly body: string;
+    readonly subtitle?: string;
+    readonly urgency: NotifyUrgency;
+    readonly sound: boolean;
+    readonly expireMs?: number;
+}): NotifyPlan;
+/**
+ * What came back from a notifier.
+ *
+ * `dispatched` is deliberately not called `shown`. Every one of these APIs
+ * accepts a notification and returns; whether the operator SAW it depends on
+ * Do Not Disturb, a Focus mode, a notification daemon's own filtering and
+ * whether the screen is on. None of that is observable from here, so the tool
+ * claims only what it did.
+ */
+export type NotifyOutcome = {
+    readonly outcome: "dispatched";
+} | Unavailable | {
+    readonly outcome: "failed";
+    readonly reason: string;
+};
+export declare function classifyNotify(result: {
+    readonly code: number;
+    readonly stderr: string;
+    readonly timedOut: boolean;
+    readonly missing: boolean;
+    readonly refused?: boolean;
+}): NotifyOutcome;