@crewhaus/tool-desktop 0.7.0

package/dist/lib/clipboard.d.ts

@@ -0,0 +1,122 @@
+/**
+ * Clipboard backends, and the one distinction the rest of the package is
+ * shaped around: an EMPTY clipboard is not an UNREADABLE one.
+ *
+ * Recorded on Debian 12 / xclip 0.13, in a container with no X server and
+ * then under Xvfb:
+ *
+ *   no display        `xclip -selection clipboard -o` -> exit 1,
+ *                     "Error: Can't open display: (null)"
+ *   display, nothing  `xclip -selection primary -o`   -> exit 1,
+ *   on the selection                                    "Error: target STRING
+ *                                                        not available"
+ *   display, text     `xclip -selection clipboard -o` -> exit 0, the text
+ *
+ * The first two are the same exit code and the same empty stdout. A backend
+ * that reports "the clipboard is empty" for both tells a workflow that the
+ * operator has copied nothing when the truth is that nothing was asked.
+ *
+ * macOS is the mirror image: `pbpaste` exits 0 with empty stdout whether the
+ * clipboard is empty or holds an image with no text flavour. So the macOS
+ * reader disambiguates with a SECOND probe, `clipboard info`, and only when
+ * the first one came back empty - never on the happy path.
+ */
+import type { SessionEnv } from "../host";
+import { type HostPlatform } from "../host";
+import type { RunRequest } from "../run";
+import { type Unavailable } from "./outcome";
+export type ClipboardFormat = "text" | "html";
+/**
+ * `clipboard info` names the FLAVOURS on the pasteboard and their byte
+ * counts. It never returns content, which is why it is safe to run as a
+ * disambiguating probe: the tool learns "there is something there" without
+ * putting whatever it is into a context window.
+ *
+ * Recorded on macOS 26.6.2 against an EMPTY clipboard: empty stdout, exit 0.
+ */
+export declare const CLIPBOARD_INFO_SCRIPT: import("./escape").AppleScript;
+/** Windows readers. Two registered scripts, chosen from a closed enum - the
+ *  format is never interpolated into one script. */
+export declare const WINDOWS_CLIPBOARD_READ_TEXT: import("./escape").PowerShellScript;
+export declare const WINDOWS_CLIPBOARD_READ_HTML: import("./escape").PowerShellScript;
+/**
+ * The Windows disambiguating probe, and the reason it exists.
+ *
+ * `Get-Clipboard -Raw` returns `$null` for an image or a file-drop exactly as
+ * it does for an empty clipboard, so Windows has the SAME ambiguity macOS has
+ * and an earlier draft of this file only handled the macOS half. This names
+ * the non-text flavours without returning their content, mirroring
+ * `clipboard info`.
+ *
+ * DOCUMENTED, NOT RECORDED: `-Format Image|FileDropList|Audio` is a
+ * PowerShell 5.1 parameter set, but nobody here has a Windows box to capture
+ * it on. It is written to fail safe — any error or unexpected output leaves
+ * `classifyClipboardInfo` reading empty stdout, which is the answer the
+ * primary read already gave.
+ */
+export declare const WINDOWS_CLIPBOARD_FORMATS: import("./escape").PowerShellScript;
+/**
+ * The Windows writer takes the payload on STDIN, not as a parameter.
+ *
+ * Argv is world-readable through a process listing on every platform this
+ * package supports, and a clipboard payload is exactly the sort of thing an
+ * operator would not want there. It is also, on Windows specifically, the
+ * channel that would put the value back into PowerShell source.
+ */
+export declare const WINDOWS_CLIPBOARD_WRITE: import("./escape").PowerShellScript;
+export type ClipboardPlan = {
+    readonly ok: true;
+    /** Which backend program was chosen, for the result and for `dryRun`. */
+    readonly backend: string;
+    readonly request: Omit<RunRequest, "timeoutMs">;
+    /**
+     * Run only when the primary read came back empty, to tell an empty
+     * clipboard from one holding a flavour the reader cannot return.
+     * macOS and Windows both need it; the Linux backends report the
+     * difference in their own stderr, so neither carries one.
+     */
+    readonly disambiguate?: Omit<RunRequest, "timeoutMs">;
+} | {
+    readonly ok: false;
+    readonly unavailable: Unavailable;
+};
+export declare function planClipboardRead(platform: HostPlatform, env: SessionEnv, format: ClipboardFormat): ClipboardPlan;
+export declare function planClipboardWrite(platform: HostPlatform, env: SessionEnv, payload: string): ClipboardPlan;
+/**
+ * What a clipboard READ actually found.
+ *
+ * Four outcomes, not two. `noTextFlavour` is the one people forget: a
+ * screenshot on the clipboard makes `pbpaste` print nothing at all, and
+ * reporting that as "empty" sends a workflow off to ask the operator to copy
+ * something they have already copied.
+ */
+export type ClipboardReadOutcome = {
+    readonly outcome: "read";
+    readonly text: string;
+} | {
+    readonly outcome: "empty";
+    readonly reason: string;
+} | {
+    readonly outcome: "noTextFlavour";
+    readonly reason: string;
+} | Unavailable | {
+    readonly outcome: "failed";
+    readonly reason: string;
+};
+export declare function classifyClipboardRead(result: {
+    readonly code: number;
+    readonly stdout: string;
+    readonly stderr: string;
+    readonly timedOut: boolean;
+    readonly missing: boolean;
+    readonly refused?: boolean;
+    readonly stdoutTruncated?: boolean;
+}): ClipboardReadOutcome;
+/**
+ * Read the macOS disambiguating probe.
+ *
+ * Empty output means the pasteboard genuinely holds nothing (recorded).
+ * Non-empty means it holds SOMETHING that `pbpaste` would not give us, which
+ * is a different answer and a different instruction to the caller.
+ */
+export declare function classifyClipboardInfo(stdout: string): "empty" | "noTextFlavour";

package/dist/lib/clipboard.js

@@ -0,0 +1,230 @@
+import { linuxDisplayEnv, linuxSession } from "../host";
+import { osascriptArgv, powershellArgv, registerAppleScript, registerPowerShellScript, } from "./escape";
+import { unavailable, unsupportedPlatform } from "./outcome";
+/**
+ * `clipboard info` names the FLAVOURS on the pasteboard and their byte
+ * counts. It never returns content, which is why it is safe to run as a
+ * disambiguating probe: the tool learns "there is something there" without
+ * putting whatever it is into a context window.
+ *
+ * Recorded on macOS 26.6.2 against an EMPTY clipboard: empty stdout, exit 0.
+ */
+export const CLIPBOARD_INFO_SCRIPT = registerAppleScript({
+    name: "clipboard-info",
+    lines: ["return (clipboard info) as string"],
+    arity: 0,
+});
+/** Windows readers. Two registered scripts, chosen from a closed enum - the
+ *  format is never interpolated into one script. */
+export const WINDOWS_CLIPBOARD_READ_TEXT = registerPowerShellScript({
+    name: "clipboard-read-text",
+    script: "$t = Get-Clipboard -Raw; if ($null -ne $t) { [Console]::Out.Write($t) }",
+    reads: [],
+});
+export const WINDOWS_CLIPBOARD_READ_HTML = registerPowerShellScript({
+    name: "clipboard-read-html",
+    script: "$t = Get-Clipboard -TextFormatType Html -Raw; if ($null -ne $t) { [Console]::Out.Write($t) }",
+    reads: [],
+});
+/**
+ * The Windows disambiguating probe, and the reason it exists.
+ *
+ * `Get-Clipboard -Raw` returns `$null` for an image or a file-drop exactly as
+ * it does for an empty clipboard, so Windows has the SAME ambiguity macOS has
+ * and an earlier draft of this file only handled the macOS half. This names
+ * the non-text flavours without returning their content, mirroring
+ * `clipboard info`.
+ *
+ * DOCUMENTED, NOT RECORDED: `-Format Image|FileDropList|Audio` is a
+ * PowerShell 5.1 parameter set, but nobody here has a Windows box to capture
+ * it on. It is written to fail safe — any error or unexpected output leaves
+ * `classifyClipboardInfo` reading empty stdout, which is the answer the
+ * primary read already gave.
+ */
+export const WINDOWS_CLIPBOARD_FORMATS = registerPowerShellScript({
+    name: "clipboard-formats",
+    script: "$f = @(); foreach ($k in 'Image','FileDropList','Audio') { try { if (Get-Clipboard -Format $k) { $f += $k } } catch {} }; [Console]::Out.Write($f -join ',')",
+    reads: [],
+});
+/**
+ * The Windows writer takes the payload on STDIN, not as a parameter.
+ *
+ * Argv is world-readable through a process listing on every platform this
+ * package supports, and a clipboard payload is exactly the sort of thing an
+ * operator would not want there. It is also, on Windows specifically, the
+ * channel that would put the value back into PowerShell source.
+ */
+export const WINDOWS_CLIPBOARD_WRITE = registerPowerShellScript({
+    name: "clipboard-write",
+    script: "Set-Clipboard -Value ([Console]::In.ReadToEnd())",
+    reads: [],
+});
+export function planClipboardRead(platform, env, format) {
+    switch (platform) {
+        case "darwin": {
+            if (format === "html") {
+                return {
+                    ok: false,
+                    unavailable: unavailable("program", 'pbpaste exposes only the plain-text flavour; the HTML flavour needs an osascript «class HTML» round-trip that returns hex, which this package does not decode - ask for format "text"', "pbpaste"),
+                };
+            }
+            return {
+                ok: true,
+                backend: "pbpaste",
+                request: { argv: ["pbpaste"] },
+                disambiguate: { argv: osascriptArgv(CLIPBOARD_INFO_SCRIPT) },
+            };
+        }
+        case "linux": {
+            const session = linuxSession(env);
+            if (session.kind === "none" || session.kind === "wayland-unreachable") {
+                return { ok: false, unavailable: unavailable("session", session.reason) };
+            }
+            const displayEnv = linuxDisplayEnv(env);
+            if (session.kind === "wayland") {
+                return {
+                    ok: true,
+                    backend: "wl-paste",
+                    request: {
+                        argv: format === "html"
+                            ? ["wl-paste", "--no-newline", "--type", "text/html"]
+                            : ["wl-paste", "--no-newline"],
+                        env: displayEnv,
+                    },
+                };
+            }
+            return {
+                ok: true,
+                backend: "xclip",
+                request: {
+                    argv: format === "html"
+                        ? ["xclip", "-selection", "clipboard", "-o", "-t", "text/html"]
+                        : ["xclip", "-selection", "clipboard", "-o"],
+                    env: displayEnv,
+                },
+            };
+        }
+        case "win32": {
+            const script = format === "html" ? WINDOWS_CLIPBOARD_READ_HTML : WINDOWS_CLIPBOARD_READ_TEXT;
+            const built = powershellArgv(script, {});
+            return {
+                ok: true,
+                backend: "powershell Get-Clipboard",
+                request: { argv: built.argv },
+                disambiguate: { argv: powershellArgv(WINDOWS_CLIPBOARD_FORMATS, {}).argv },
+            };
+        }
+        default:
+            return { ok: false, unavailable: unsupportedPlatform(platform, "clipboard") };
+    }
+}
+export function planClipboardWrite(platform, env, payload) {
+    switch (platform) {
+        case "darwin":
+            return { ok: true, backend: "pbcopy", request: { argv: ["pbcopy"], stdin: payload } };
+        case "linux": {
+            const session = linuxSession(env);
+            if (session.kind === "none" || session.kind === "wayland-unreachable") {
+                return { ok: false, unavailable: unavailable("session", session.reason) };
+            }
+            const displayEnv = linuxDisplayEnv(env);
+            if (session.kind === "wayland") {
+                return {
+                    ok: true,
+                    backend: "wl-copy",
+                    request: { argv: ["wl-copy"], stdin: payload, env: displayEnv },
+                };
+            }
+            // Under X11 there is no server-side clipboard store: the writing
+            // process OWNS the selection and must outlive this call or the content
+            // vanishes the moment the child exits. `xclip -i` forks a resident
+            // holder by itself, which is the behaviour that makes this work - and
+            // the reason the runner's stream drain is BOUNDED, because that holder
+            // inherits the stdout pipe and never closes it.
+            return {
+                ok: true,
+                backend: "xclip",
+                request: {
+                    argv: ["xclip", "-selection", "clipboard", "-i"],
+                    stdin: payload,
+                    env: displayEnv,
+                },
+            };
+        }
+        case "win32": {
+            const built = powershellArgv(WINDOWS_CLIPBOARD_WRITE, {});
+            return {
+                ok: true,
+                backend: "powershell Set-Clipboard",
+                request: { argv: built.argv, stdin: payload },
+            };
+        }
+        default:
+            return { ok: false, unavailable: unsupportedPlatform(platform, "clipboard") };
+    }
+}
+/** Stderr patterns that mean "there is no display to talk to", per backend. */
+const NO_SESSION = [
+    /Can't open display/i,
+    /Failed to connect to a Wayland server/i,
+    /XDG_RUNTIME_DIR is invalid or not set/i,
+    /Unable to init server/i,
+];
+/** Stderr patterns that mean "the display is fine, the selection is empty". */
+const EMPTY_SELECTION = [
+    // xclip 0.13, recorded under Xvfb with nothing on the PRIMARY selection.
+    /target \S+ not available/i,
+    // wl-clipboard's wording. DOCUMENTED, NOT RECORDED: the capture container
+    // had no compositor, so this branch is written from wl-clipboard's source
+    // and is the one string in this file nobody here has seen a program print.
+    /Nothing is copied/i,
+];
+export function classifyClipboardRead(result) {
+    if (result.refused === true) {
+        return { outcome: "failed", reason: result.stderr };
+    }
+    if (result.missing) {
+        return unavailable("program", "the clipboard program for this platform is not installed on this host");
+    }
+    if (result.timedOut) {
+        // An X11 clipboard read against a wedged server BLOCKS rather than
+        // exiting, which is why every read here has a deadline. What it would
+        // have said is unknown, and unknown is not empty.
+        return unavailable("unknown", "the clipboard program did not finish within its timeout and was killed - the clipboard could not be read, which is not the same as it being empty");
+    }
+    if (result.code === 0) {
+        if (result.stdout.length > 0)
+            return { outcome: "read", text: result.stdout };
+        // Exit 0 and nothing on stdout: on macOS this is ambiguous and the caller
+        // runs the disambiguating probe; on Linux and Windows an empty successful
+        // read means an empty clipboard.
+        return { outcome: "empty", reason: "the clipboard program returned no bytes" };
+    }
+    for (const pattern of NO_SESSION) {
+        if (pattern.test(result.stderr)) {
+            return unavailable("session", `the clipboard backend could not reach a display: ${result.stderr.trim()}`);
+        }
+    }
+    for (const pattern of EMPTY_SELECTION) {
+        if (pattern.test(result.stderr)) {
+            return {
+                outcome: "empty",
+                reason: `the display was reachable and the selection holds nothing: ${result.stderr.trim()}`,
+            };
+        }
+    }
+    return {
+        outcome: "failed",
+        reason: `the clipboard program exited ${result.code}: ${result.stderr.trim()}`,
+    };
+}
+/**
+ * Read the macOS disambiguating probe.
+ *
+ * Empty output means the pasteboard genuinely holds nothing (recorded).
+ * Non-empty means it holds SOMETHING that `pbpaste` would not give us, which
+ * is a different answer and a different instruction to the caller.
+ */
+export function classifyClipboardInfo(stdout) {
+    return stdout.trim() === "" ? "empty" : "noTextFlavour";
+}

package/dist/lib/escape.d.ts

@@ -0,0 +1,220 @@
+/**
+ * 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.
+ */
+/**
+ * One AppleScript, as a fixed list of statements.
+ *
+ * `lines` become one `-e` argument each. They are written by hand in this
+ * package and contain no caller value; `item N of argv` is how they reach
+ * what the caller sent.
+ */
+export type AppleScript = {
+    readonly name: string;
+    readonly lines: readonly string[];
+    /** How many `argv` items the statements read. Checked when argv is built. */
+    readonly arity: number;
+};
+/** One PowerShell script, as a single statement string plus its env contract. */
+export type PowerShellScript = {
+    readonly name: string;
+    readonly script: string;
+    /** Environment variable names the script reads. Nothing else is set. */
+    readonly reads: readonly string[];
+};
+/**
+ * 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 declare function registerAppleScript(script: AppleScript): AppleScript;
+export declare function registerPowerShellScript(script: PowerShellScript): PowerShellScript;
+/**
+ * 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 declare function registeredPowerShellSources(): ReadonlySet<string>;
+/** Raised when something tries to run source this file did not register. */
+export declare class UnregisteredScriptError extends Error {
+    constructor(kind: string, name: string);
+}
+/**
+ * `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 declare function osascriptArgv(script: AppleScript, values?: readonly string[]): readonly string[];
+/**
+ * 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 declare function osascriptProgramText(argv: readonly string[]): string;
+/**
+ * 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 declare function parseOsascriptError(stderr: string): {
+    code: number | null;
+    message: string;
+};
+/**
+ * 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 declare const APPLESCRIPT_PERMISSION_CODES: ReadonlyMap<number, string>;
+/**
+ * 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 declare function osascriptPermissionReason(stderr: string): string | undefined;
+/** The fixed prefix for every PowerShell invocation this package makes. */
+export declare const POWERSHELL_FLAGS: readonly string[];
+/**
+ * `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 declare function powershellArgv(script: PowerShellScript, env: Readonly<Record<string, string>>): {
+    readonly argv: readonly string[];
+    readonly env: Readonly<Record<string, string>>;
+};
+/**
+ * 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 declare function escapeXmlText(value: string): string;
+/**
+ * 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 declare function stripXmlIllegalChars(value: string): {
+    text: string;
+    removed: number;
+};
+/**
+ * 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 declare function looksLikeFlag(value: string): boolean;
+/**
+ * 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 declare const SAFE_DESTINATION: RegExp;
+/** A CUPS `page-ranges` value: `1`, `1-4`, `1,3,5-9`. Nothing else. */
+export declare const SAFE_PAGE_RANGES: RegExp;