howtofixcli 0.7.7 → 0.7.9

package/dist/cli-auth.js

@@ -1,142 +0,0 @@
-/**
- * Proof of identity for the requests this CLI makes to start a sign-in.
- *
- * The panel used to take the fingerprint prefix (`howtofix-cli-…`) as proof that
- * a request came from this CLI. It is not proof: the prefix is a public string,
- * so any script could send it. Two things go wrong when it is trusted —
- *
- *   1. the panel records a login that did not come from a CLI, and
- *   2. worse, the forger can start a login and hand the approval link to someone
- *      else, so a stranger's browser approves a sign-in that mints a key for the
- *      forger's pending flow.
- *
- * A signature fixes both. The CLI signs the request with a key only the published
- * bundle carries, so the panel can tell a real CLI from anything that merely says
- * it is one.
- *
- * The honest limit, stated where it belongs: the private key ships inside the
- * published bundle, so anyone willing to unpack a minified file can recover it.
- * This is a bar, not a wall. It defeats the drive-by forger — the curl, the
- * script, the "just send the header" trick — and it makes an abuse of the login
- * endpoint traceable to something that had to be extracted, not guessed. A real
- * wall needs a per-install credential the panel issued, and that only exists
- * after a first sign-in; the bootstrap is what has to be open.
- */
-import { createPrivateKey, createPublicKey, createHash, randomBytes, sign } from "node:crypto";
-import { arch, cpus, hostname, platform } from "node:os";
-import { APP_VERSION } from "./brand.js";
-/** The key this build signs with. Rotating it means publishing a new CLI. */
-export const CLI_SIGNING_KEY_ID = "hf-cli-1";
-/**
- * The private half of the CLI's signing keypair, as a PKCS#8 DER blob.
- *
- * A private key cannot live anywhere else in this project: the CLI ships as a
- * single minified file with no asset loading, so the key is either in the bundle
- * or the CLI cannot prove anything. That is the tradeoff described above, made
- * explicit here so nobody mistakes it for an oversight.
- */
-const CLI_SIGNING_PRIVATE_KEY_DER_B64 = "MC4CAQAwBQYDK2VwBCIEIDmKoNgInS7oDpncee1d1+Mnci1R/q4aE5xxHeCKq4Dc";
-/**
- * Domain separation: the same key must never be usable for a second purpose, so
- * every signature is over a string that names what it is for.
- */
-const SIGNATURE_DOMAIN = "howtofix-cli-auth-v1";
-let cachedKey;
-/** The signing key, built once from the embedded DER. */
-function signingKey() {
-    if (!cachedKey) {
-        cachedKey = createPrivateKey({
-            key: Buffer.from(CLI_SIGNING_PRIVATE_KEY_DER_B64, "base64"),
-            format: "der",
-            type: "pkcs8",
-        });
-    }
-    return cachedKey;
-}
-/** The matching public key — used by the self-check below, and nothing else. */
-export function cliSigningPublicKey() {
-    return createPublicKey(signingKey());
-}
-/**
- * The exact byte string that gets signed. The panel builds the same string, so
- * the two must agree field for field; each field is on its own line and the
- * separator cannot occur inside any of them.
- */
-export function cliSignaturePayload(keyId, fingerprintId, clientInfo, nonce) {
-    return Buffer.from([SIGNATURE_DOMAIN, keyId, fingerprintId, clientInfo, nonce].join("\n"), "utf8");
-}
-/** A fresh, single-use value for each request, so a captured one cannot be reused. */
-export function createNonce() {
-    return randomBytes(16).toString("hex");
-}
-/**
- * The public half this build's key must match, as the panel has it configured.
- *
- * A wrong half of the pair is silent otherwise: every sign-in fails with a 401
- * that reads like a server problem, and nothing points at the key. `--version`
- * checks this so a mismatch is visible at once, and the bundle self-check fails
- * on it.
- */
-const EXPECTED_PUBLIC_KEY_B64 = "tQ91uspGl0sw5Y8x+soLYnFNX6a9vEzSzCuuvalzdKk=";
-/** Report whether the embedded key is the one the panel verifies against. */
-export function cliSigningKeyMatchesPanel() {
-    const spki = cliSigningPublicKey().export({ format: "der", type: "spki" });
-    // The SPKI wrapper is a fixed 12-byte prefix, so the raw key is the tail.
-    const raw = spki.subarray(spki.length - 32);
-    return raw.toString("base64") === EXPECTED_PUBLIC_KEY_B64;
-}
-/** A short fingerprint of the signing key, for logs and bug reports. */
-export function cliSigningKeyFingerprint() {
-    const spki = cliSigningPublicKey().export({ format: "der", type: "spki" });
-    return createHash("sha256").update(spki).digest("hex").slice(0, 16);
-}
-/**
- * A short, human-readable description of this machine, shown on the approval page
- * so the person can see what they are approving. It is display only — the panel
- * sanitises it and never authorises on it — so a best-effort value is correct.
- *
- * The version leads, because the panel turns this string into the name its usage
- * log records for the device ("CLI (0.4.90)"): that is what tells one terminal's
- * runs apart from an API key in the log. The machine detail follows it so the
- * person approving still sees which computer is asking.
- */
-export function describeClient() {
-    const model = cpus()[0]?.model ?? "";
-    const shortModel = model.replace(/\s+/g, " ").trim();
-    const name = hostname();
-    const machine = shortModel ? `${name} (${platform()}/${arch()}, ${shortModel})` : `${name} (${platform()}/${arch()})`;
-    return `CLI (${APP_VERSION}, ${machine})`;
-}
-/**
- * The header that names this CLI on every call it makes to the gateway.
- *
- * It is the counterpart of {@link describeClient} for requests that are not the
- * login: the gateway labels the usage log of a model call with whatever this
- * says, so a run from a terminal is told apart from an API key without opening
- * the request. It is a label, never a credential, and never a permission.
- */
-export const CLI_CLIENT_HEADER = "X-HowToFix-Client";
-/**
- * What the CLI calls itself in that header: the version, and nothing else.
- *
- * The machine detail stays on the approval page rather than riding every model
- * request, and the version alone is what the panel turns into the log label
- * ("CLI (0.4.92)"). The panel parses this exactly as it parses the login
- * description, so both spellings produce the same label.
- */
-export function cliClientHeader() {
-    return `CLI (${APP_VERSION})`;
-}
-/**
- * Sign one login request.
- *
- * `fingerprintId` and `clientInfo` are signed too, not just carried: otherwise a
- * captured signature could be replayed against a different fingerprint or with a
- * different description of the machine, and the panel's record of who asked
- * would be worthless.
- */
-export function signLoginRequest(fingerprintId, clientInfo) {
-    const nonce = createNonce();
-    const signature = sign(null, cliSignaturePayload(CLI_SIGNING_KEY_ID, fingerprintId, clientInfo, nonce), signingKey());
-    return { keyId: CLI_SIGNING_KEY_ID, nonce, signature: signature.toString("base64") };
-}

package/dist/cli-checkin.js

@@ -1,116 +0,0 @@
-/**
- * The daily check-in, claimed from the CLI.
- *
- * The server endpoint (`/v1/cli/checkin` on the gateway) exists because a
- * terminal holds no dashboard session — the web claim needs a cookie the CLI
- * can never send — but the rules are the server's own: one claim per account
- * per day, the date from the server clock, the amount from the admin's
- * setting. Nothing in this module can grant more than once or choose a
- * number; it asks, and the server answers.
- *
- * Every failure is a sentence and none is fatal: an auto check-in that could
- * not reach the gateway costs the user nothing they had before, and a CLI
- * that refused to start over it would be far worse than one line missing.
- */
-import { CLI_CLIENT_HEADER, cliClientHeader } from "./cli-auth.js";
-import { deviceId } from "./device-id.js";
-/** Base URL for the check-in endpoints: the API host, `/v1` included. */
-const CHECKIN_PATH = "/cli/checkin";
-/**
-The auth scheme name, assembled rather than written out: the tooling that
-writes these files rewrites a literal header prefix and breaks the build.
- */
-const AUTH_SCHEME = ["Bearer", ""].join(" ").trim();
-/** Quota units per dollar, as the gateway bills them ($1 = 500,000). */
-export const QUOTA_PER_USD = 500_000;
-/** Quota formatted the way a person reads it: dollars, two decimals. */
-export function formatQuotaUsd(quota) {
-    return `$${(quota / QUOTA_PER_USD).toFixed(2)}`;
-}
-async function callCheckin(token, method, baseUrl, fetchImpl, timeoutMs) {
-    const controller = new AbortController();
-    const timer = setTimeout(() => controller.abort(), timeoutMs);
-    try {
-        const response = await fetchImpl(`${baseUrl}${CHECKIN_PATH}`, {
-            method,
-            headers: {
-                [CLI_CLIENT_HEADER]: cliClientHeader(),
-                "X-HowToFix-Device": deviceId().id,
-                Authorization: `${AUTH_SCHEME} ${token}`,
-            },
-            signal: controller.signal,
-        });
-        let parsed = {};
-        try {
-            parsed = (await response.json());
-        }
-        catch {
-            // A non-JSON body leaves the status as the story.
-        }
-        return { status: response.status, body: parsed };
-    }
-    finally {
-        clearTimeout(timer);
-    }
-}
-/** Ask the gateway whether today's claim is already taken. Never throws. */
-export async function checkCliCheckin(token, options) {
-    const baseUrl = (options?.baseUrl ?? "https://api.howtofix.id/v1").replace(/\/+$/, "");
-    const fetchImpl = options?.fetchImpl ?? fetch;
-    const timeoutMs = options?.timeoutMs ?? 10_000;
-    const trimmed = token.trim();
-    if (!trimmed)
-        return { ok: false, enabled: false, checkedInToday: false, quotaToday: 0, message: "no token given" };
-    try {
-        const { status, body } = await callCheckin(trimmed, "GET", baseUrl, fetchImpl, timeoutMs);
-        if (status === 401 || status === 403) {
-            return { ok: false, enabled: false, checkedInToday: false, quotaToday: 0, message: "the gateway rejected that token for the check-in status" };
-        }
-        if (status >= 400 || body.success !== true) {
-            return { ok: false, enabled: false, checkedInToday: false, quotaToday: 0, message: typeof body.message === "string" ? body.message : `the gateway answered ${status}` };
-        }
-        const data = (body.data ?? {});
-        return {
-            ok: true,
-            enabled: data.enabled === true,
-            checkedInToday: data.checked_in_today === true,
-            quotaToday: Number(data.quota_today ?? 0) || 0,
-            message: "",
-        };
-    }
-    catch (cause) {
-        const aborted = cause instanceof Error && cause.name === "AbortError";
-        return { ok: false, enabled: false, checkedInToday: false, quotaToday: 0, message: aborted ? "the gateway did not answer the check-in in time" : "could not reach the gateway" };
-    }
-}
-/**
- * Claim today's check-in.
- *
- * A refusal that says today is already taken is `alreadyClaimed`, not a
- * failure: that is the normal state of a second start in one day and the
- * caller shows nothing for it.
- */
-export async function claimCliCheckin(token, options) {
-    const baseUrl = (options?.baseUrl ?? "https://api.howtofix.id/v1").replace(/\/+$/, "");
-    const fetchImpl = options?.fetchImpl ?? fetch;
-    const timeoutMs = options?.timeoutMs ?? 15_000;
-    const trimmed = token.trim();
-    if (!trimmed)
-        return { ok: false, alreadyClaimed: false, quotaAwarded: 0, message: "no token given" };
-    try {
-        const { status, body } = await callCheckin(trimmed, "POST", baseUrl, fetchImpl, timeoutMs);
-        if (body.success === true) {
-            const data = (body.data ?? {});
-            return { ok: true, alreadyClaimed: false, quotaAwarded: Number(data.quota_awarded ?? 0) || 0, message: "" };
-        }
-        const message = typeof body.message === "string" ? body.message : `the gateway answered ${status}`;
-        // The server's own sentence for "today is spent" — recognised so a normal
-        // second start never reads as an error.
-        const alreadyClaimed = /签到|check-?in|already|今日/.test(message) && !/not enabled/i.test(message);
-        return { ok: false, alreadyClaimed, quotaAwarded: 0, message };
-    }
-    catch (cause) {
-        const aborted = cause instanceof Error && cause.name === "AbortError";
-        return { ok: false, alreadyClaimed: false, quotaAwarded: 0, message: aborted ? "the gateway did not answer the check-in in time" : "could not reach the gateway" };
-    }
-}

package/dist/cli-credentials.js

@@ -1,254 +0,0 @@
-/**
- * The CLI's own credential file: a short-lived access token plus the refresh
- * token that renews it.
- *
- * This file exists because the SDK cannot hold this shape. A stored credential
- * is a single string — an `api_key` is one secret with no expiry — and the SDK
- * only ever refreshes a credential it understands as OAuth. Measured against the
- * SDK: `resolveRefreshCredential` returns early unless the stored credential's
- * type is `oauth`, so an `api_key` is handed to the relay until the relay
- * refuses it, and then the user is stuck.
- *
- * So the CLI owns the pair. It writes the file, renews it before the access
- * token dies, and feeds the fresh access token to the SDK as a runtime key. That
- * is the same split Claude Code and Codex use: their own credentials file next to
- * the client, and the client does the refreshing.
- *
- * What the pair buys, stated plainly: a leaked access token is worth hours, not
- * forever. Revoking the device from the panel disables the relay token, so the
- * old way — a permanent `sk-` key that works until someone remembers to delete
- * it — is gone.
- *
- * The refresh token is stored as the server issued it (an opaque secret). It is
- * never sent anywhere but `/api/auth/cli/refresh` on the panel, and never
- * printed: `maskToken` is what reaches the feed.
- */
-import { existsSync, readFileSync } from "node:fs";
-import { join } from "node:path";
-import { writeFileAtomicSync } from "./fs-atomic.js";
-import { createFingerprintId, PANEL_URL } from "./oauth-login.js";
-/** Where the pair lives, next to the rest of the agent state. */
-export function cliCredentialsPath(agentDir) {
-    return join(agentDir, "cli-credentials.json");
-}
-/**
- * How long before expiry the CLI renews.
- *
- * A renewal that only fires once the key is dead leaves a window where the very
- * next prompt fails, and the user has to retry to make the refresh happen. Five
- * minutes is comfortably longer than a request and short enough that a stale
- * file is refreshed on any normal start.
- */
-export const CLI_REFRESH_SKEW_MS = 5 * 60 * 1000;
-/**
- * Whether the stored access token is usable right now.
- *
- * A credential with no readable expiry is treated as usable: the file is ours,
- * and refusing to start because a field is missing would strand a user whose
- * only problem is a truncated write. The relay is the real authority on whether
- * the key works, and a 401 is handled at the call site.
- */
-export function accessTokenIsFresh(credential, now = Date.now()) {
-    if (!credential.accessToken)
-        return false;
-    if (!Number.isFinite(credential.accessExpiresAt) || credential.accessExpiresAt <= 0)
-        return true;
-    return credential.accessExpiresAt * 1000 - CLI_REFRESH_SKEW_MS > now;
-}
-/** Whether the refresh token can still renew anything. */
-export function refreshTokenIsUsable(credential, now = Date.now()) {
-    if (!credential.refreshToken || !credential.deviceId)
-        return false;
-    if (!Number.isFinite(credential.refreshExpiresAt) || credential.refreshExpiresAt <= 0)
-        return true;
-    return credential.refreshExpiresAt * 1000 > now;
-}
-/**
- * Read the pair, or undefined.
- *
- * Never throws. A corrupt or half-written file is a file with no usable
- * credential in it, which is a state the caller already handles — the user signs
- * in again — and turning it into an exception would make the CLI fail to start
- * over a file it can simply ignore.
- */
-export function readCliCredential(agentDir) {
-    const path = cliCredentialsPath(agentDir);
-    if (!existsSync(path))
-        return undefined;
-    let parsed;
-    try {
-        parsed = JSON.parse(readFileSync(path, "utf8"));
-    }
-    catch {
-        return undefined;
-    }
-    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed))
-        return undefined;
-    const record = parsed;
-    const accessToken = typeof record.accessToken === "string" ? record.accessToken.trim() : "";
-    const refreshToken = typeof record.refreshToken === "string" ? record.refreshToken.trim() : "";
-    const deviceId = typeof record.deviceId === "string" ? record.deviceId.trim() : "";
-    if (!accessToken || !refreshToken || !deviceId)
-        return undefined;
-    return {
-        accessToken,
-        accessExpiresAt: numberOrZero(record.accessExpiresAt),
-        refreshToken,
-        deviceId,
-        refreshExpiresAt: numberOrZero(record.refreshExpiresAt),
-    };
-}
-/** Write the pair. Returns false when the file could not be written. */
-export function writeCliCredential(agentDir, credential) {
-    try {
-        // 0600: this file carries the device access token and its refresh pair —
-        // readable by anyone on a shared host is a live session stolen.
-        writeFileAtomicSync(cliCredentialsPath(agentDir), `${JSON.stringify(credential, null, 2)}\n`, { mode: 0o600 });
-        return true;
-    }
-    catch {
-        return false;
-    }
-}
-/** Forget the pair. Used when the panel says the sign-in is gone for good. */
-export function clearCliCredential(agentDir) {
-    try {
-        const path = cliCredentialsPath(agentDir);
-        if (existsSync(path))
-            writeFileAtomicSync(path, "", { mode: 0o600 });
-    }
-    catch {
-        // Nothing to do: the caller is already on the "sign in again" path.
-    }
-}
-function numberOrZero(value) {
-    return typeof value === "number" && Number.isFinite(value) ? value : 0;
-}
-/**
- * Renew the pair against the panel.
- *
- * The response carries a new access token *and* a new refresh token: the server
- * rotates the refresh secret on every use, so the value in hand is spent the
- * moment this succeeds. That is why the new pair is written before the caller
- * sees it — losing the rotated refresh token would force the user to sign in
- * again for no reason.
- */
-export async function refreshCliCredential(credential, options) {
-    const panel = (options?.panelUrl ?? PANEL_URL).replace(/\/+$/, "");
-    const doFetch = options?.fetchImpl ?? fetch;
-    const timeoutMs = options?.timeoutMs ?? 15_000;
-    const controller = new AbortController();
-    const timer = setTimeout(() => controller.abort(), timeoutMs);
-    try {
-        const response = await doFetch(`${panel}/api/auth/cli/refresh`, {
-            method: "POST",
-            headers: { "Content-Type": "application/json", Accept: "application/json" },
-            body: JSON.stringify({
-                device_id: credential.deviceId,
-                refresh_token: credential.refreshToken,
-                // The machine this renewal comes from. The server pins a device to the
-                // machine that first renewed it and refuses a renewal from any other, so
-                // a refresh token copied off the disk is not portable. The value is the
-                // same fingerprint the sign-in sent, so the panel shows one identity for
-                // one machine instead of two. A machine that cannot read an OS id still
-                // sends one (a hostname-derived value), which is weaker but consistent —
-                // the server compares what it is given and does not care how strong the
-                // source was.
-                fingerprint_id: createFingerprintId(),
-            }),
-            signal: controller.signal,
-        });
-        const body = (await response.json().catch(() => ({})));
-        if (response.status === 401 || response.status === 403) {
-            return {
-                ok: false,
-                terminal: true,
-                message: "this sign-in is no longer valid — run /connect to sign in again",
-            };
-        }
-        if (!response.ok) {
-            return { ok: false, terminal: false, message: `the panel refused the renewal (${response.status})` };
-        }
-        const data = (body.data ?? {});
-        const accessToken = pickString(body.token, data.token);
-        const refreshToken = pickString(body.refresh_token, data.refresh_token);
-        const deviceId = pickString(body.device_id, data.device_id) ?? credential.deviceId;
-        if (!accessToken || !refreshToken) {
-            return { ok: false, terminal: false, message: "the panel did not return a renewed credential" };
-        }
-        return {
-            ok: true,
-            terminal: false,
-            credential: {
-                accessToken,
-                accessExpiresAt: pickNumber(body.access_expires_at, data.access_expires_at),
-                refreshToken,
-                deviceId,
-                refreshExpiresAt: pickNumber(body.refresh_expires_at, data.refresh_expires_at),
-            },
-        };
-    }
-    catch (cause) {
-        const aborted = cause instanceof Error && cause.name === "AbortError";
-        return {
-            ok: false,
-            terminal: false,
-            message: aborted ? `the panel did not answer within ${Math.round(timeoutMs / 1000)}s` : "could not reach the panel",
-        };
-    }
-    finally {
-        clearTimeout(timer);
-    }
-}
-function pickString(...values) {
-    for (const value of values) {
-        if (typeof value === "string" && value.trim())
-            return value.trim();
-    }
-    return undefined;
-}
-function pickNumber(...values) {
-    for (const value of values) {
-        if (typeof value === "number" && Number.isFinite(value))
-            return value;
-    }
-    return 0;
-}
-/**
- * Renew the pair and persist the result, if the access token is close to
- * expiring.
- *
- * One function rather than two call sites each doing it, because the order is
- * load-bearing: the rotated refresh token must reach the disk *before* anything
- * else happens, since the value in hand is spent the moment the server answers.
- * A caller that renewed and then forgot to write would lock the user out at the
- * next start with a refresh token that no longer works.
- *
- * Returns the credential in hand when nothing needed doing, so callers can treat
- * "no renewal required" and "renewed" the same way.
- */
-export async function renewCliCredentialIfNeeded(agentDir, credential, options) {
-    const now = options?.now ?? Date.now();
-    if (accessTokenIsFresh(credential, now) || !refreshTokenIsUsable(credential, now)) {
-        return { credential, renewed: false, terminal: false };
-    }
-    const outcome = await refreshCliCredential(credential, options);
-    if (!outcome.ok || !outcome.credential) {
-        // A terminal refusal means the panel has already ended this device session —
-        // the refresh token is gone and, because revoking a device disables the relay
-        // token behind it, the access token in hand is dead too. Keeping the pair
-        // would make every prompt retry against a credential that can never work and
-        // repeat the same message; clearing it means one clear answer and a clean
-        // `/connect` afterwards.
-        if (outcome.terminal)
-            clearCliCredential(agentDir);
-        return { credential, renewed: false, terminal: outcome.terminal, message: outcome.message };
-    }
-    const persisted = writeCliCredential(agentDir, outcome.credential);
-    return {
-        credential: outcome.credential,
-        renewed: true,
-        terminal: false,
-        message: persisted ? undefined : `the renewed sign-in could not be saved to ${cliCredentialsPath(agentDir)}`,
-    };
-}

package/dist/clipboard.js

@@ -1,149 +0,0 @@
-/**
- * Reading the system clipboard on every desktop we can actually reach.
- *
- * The SDK's `getNativeClipboard()` is a native module, and on Linux it returns
- * nothing unless `DISPLAY` is set: a Wayland-only session (no XWayland) has no
- * path at all, and a machine without the prebuilt binary has none either. On
- * every platform but Windows mouse tracking has also stopped the terminal from
- * pasting on its own, so a right click reaches the app and does nothing unless
- * this module is behind it. (On Windows the terminal does the pasting, which is
- * why `rightClickPastesHere` in `settings.ts` says so — see its comment.)
- *
- * This module fills that in with the command-line clipboard tools that are
- * actually installed, and it keeps three rules a sibling harness learned the
- * hard way (see the pitfalls file):
- *
- * - **Never block the event loop.** A clipboard daemon that is slow or hung used
- *   to freeze the whole TUI, because reading it ran a synchronous subprocess
- *   with a two-second timeout. Every read here is `spawn` + `await`.
- * - **Ask Wayland for the right type.** `wl-paste --type text/plain` returns
- *   ISO Latin-1 when the clipboard is owned by an X11 client through XWayland
- *   (`STRING`), which turns CJK text into `?`. Ask for
- *   `text/plain;charset=utf-8` first — that maps to `UTF8_STRING` — and fall
- *   back only if the owner does not offer it.
- * - **Read back before you claim a write.** On X11 an empty `xclip` write can
- *   return success while the clipboard stays empty, so `copyText` verifies.
- */
-import { spawn } from "node:child_process";
-/**
- * Run a command, return its stdout, and never throw.
- *
- * The timeout is a guard against a hung daemon, not a normal path: a clipboard
- * read on a healthy machine is a few milliseconds.
- */
-export function runClipboardCommand(command, args, timeoutMs = 2000) {
-    return new Promise((resolve) => {
-        let settled = false;
-        // Declared before `finish`, not after `spawn`: a spawn that throws
-        // synchronously calls `finish` from the catch below, and `clearTimeout` on a
-        // `const` timer that has not been reached yet is a temporal-dead-zone
-        // ReferenceError. The executor then throws, the promise rejects, and the
-        // caller gets an exception from the one helper documented to never throw —
-        // the failure path was the thing that crashed.
-        let timer;
-        const finish = (value) => {
-            if (settled)
-                return;
-            settled = true;
-            if (timer !== undefined)
-                clearTimeout(timer);
-            resolve(value);
-        };
-        let child;
-        try {
-            child = spawn(command, [...args], { stdio: ["ignore", "pipe", "ignore"] });
-        }
-        catch {
-            finish({ ok: false, stdout: "" });
-            return;
-        }
-        timer = setTimeout(() => {
-            child.kill("SIGKILL");
-            finish({ ok: false, stdout: "" });
-        }, timeoutMs);
-        const chunks = [];
-        child.stdout?.on("data", (chunk) => chunks.push(chunk));
-        child.on("error", () => finish({ ok: false, stdout: "" }));
-        child.on("close", (code) => {
-            finish({ ok: code === 0, stdout: Buffer.concat(chunks).toString("utf8") });
-        });
-    });
-}
-/** True when the process is running under Wayland, with or without XWayland. */
-function onWayland() {
-    return process.env.XDG_SESSION_TYPE === "wayland" || (process.env.WAYLAND_DISPLAY?.length ?? 0) > 0;
-}
-/**
- * Read the clipboard with the platform's own tools.
- *
- * Each entry is tried in order and the first one that yields text wins. The
- * order matters: the Wayland read asks for UTF-8 before the plain type, and the
- * X11 read comes after Wayland so a Wayland session never picks up a stale X11
- * selection through XWayland.
- */
-async function readWithTools() {
-    const candidates = [];
-    if (process.platform === "darwin") {
-        candidates.push({ command: "pbpaste", args: [] });
-    }
-    else if (process.platform === "win32") {
-        candidates.push({ command: "powershell.exe", args: ["-NoProfile", "-Command", "Get-Clipboard -Raw"] });
-    }
-    else {
-        if (onWayland()) {
-            candidates.push({ command: "wl-paste", args: ["--no-newline", "--type", "text/plain;charset=utf-8"] });
-            candidates.push({ command: "wl-paste", args: ["--no-newline", "--type", "text/plain"] });
-            candidates.push({ command: "wl-paste", args: ["--no-newline"] });
-        }
-        if ((process.env.DISPLAY?.length ?? 0) > 0 || !onWayland()) {
-            candidates.push({ command: "xclip", args: ["-selection", "clipboard", "-o"] });
-            candidates.push({ command: "xsel", args: ["--clipboard", "--output"] });
-        }
-        candidates.push({ command: "termux-clipboard-get", args: [] });
-    }
-    for (const candidate of candidates) {
-        const result = await runClipboardCommand(candidate.command, candidate.args);
-        if (result.ok && result.stdout.length > 0)
-            return result.stdout;
-    }
-    return undefined;
-}
-/**
- * Read the clipboard, preferring the SDK's native helper and falling back to the
- * command-line tools.
- *
- * The native helper is tried first because it is faster and already handles the
- * desktop's own conventions; the tools are what makes Linux without `DISPLAY`,
- * or without the prebuilt binary, work at all.
- */
-export async function readClipboardText() {
-    let native;
-    try {
-        const { getNativeClipboard } = await import("@netrodev/hxf-tui");
-        native = getNativeClipboard();
-    }
-    catch {
-        native = undefined;
-    }
-    if (native) {
-        try {
-            const text = await native.getText();
-            if (typeof text === "string" && text.length > 0)
-                return { ok: true, text };
-        }
-        catch {
-            // Fall through: a native failure must not be the end of the story.
-        }
-    }
-    const text = await readWithTools();
-    if (text !== undefined)
-        return { ok: true, text };
-    const hint = onWayland()
-        ? "install wl-clipboard (wl-paste)"
-        : process.platform === "darwin"
-            ? "pbpaste should be present on macOS"
-            : process.platform === "win32"
-                ? "Get-Clipboard should be present on Windows"
-                : "install xclip or xsel, or run under a display";
-    return { ok: false, reason: `no clipboard tool could read it — ${hint}` };
-}