commandmate 0.27.1 → 0.29.0

package/dist/lib/push/vapid.js

@@ -0,0 +1,293 @@
+"use strict";
+/**
+ * VAPID configuration for Web Push, and the one startup check that reports on it
+ * (Issue #1125; the check and the subject rules are Issues #2123 / #2124).
+ *
+ * Keys are supplied via environment variables and read lazily so tests can vary
+ * them and so an unconfigured deployment simply disables push (never crashes).
+ * The private key and subject are secrets — never log the returned config.
+ *
+ * ## Why the default subject is an https: URL (Issue #2124)
+ *
+ * The VAPID `sub` claim is the sender's contact, and **Apple validates it**. The
+ * original default, `mailto:commandmate@localhost`, names a domain that cannot
+ * exist, so APNs answered 403 and iOS/iPadOS received nothing while Android kept
+ * working — FCM is permissive about `sub`, so testing on Android alone cannot
+ * see it. Measured by the orchestrator during the Epic #2002 device UAT
+ * (2026-08-27, develop e8d09989), fanning ONE waiting notification to two
+ * devices:
+ *
+ *   Android 10 / Chrome 151 -> FCM   default subject: delivered
+ *   iPad / iPadOS 18.7      -> APNs  default subject: 403, push-send-failed
+ *                                    https://github.com/Kewton/CommandMate: delivered
+ *
+ * This file's author did NOT reproduce that on hardware; the APNs/FCM behaviour
+ * above is quoted from that UAT and is not re-measured here. What IS pinned by
+ * the unit suite is the pure part: which subjects this module accepts and which
+ * it flags, and that the default is one of the accepted ones.
+ *
+ * RFC 8292 §2.1 allows both `mailto:` and `https:` for `sub`, so a project URL
+ * is a conforming default that needs no per-install mailbox.
+ *
+ * ## Why an invalid subject is reported and NOT replaced
+ *
+ * {@link inspectVapidConfig} flags a bad `CM_VAPID_SUBJECT`; {@link getVapidConfig}
+ * still returns it verbatim. Silently substituting the default would make the
+ * warning describe a value the server does not actually send, and would make
+ * `commandmate status` disagree with the wire. The operator set it; they are told
+ * it will be rejected, and startup is never blocked (fail-open, exactly as
+ * `lib/server/localhost-self-check` is).
+ *
+ * ## No `@/` imports here, ever
+ *
+ * `src/cli/commands/status.ts` imports this module so the CLI and the server run
+ * the SAME check, and `tsconfig.cli.json` resets `paths` to `{}` — an alias
+ * import here would break `npm run build:cli`. Same constraint as
+ * `lib/server/localhost-self-check.ts` and `lib/detection/version-probes.ts`.
+ * This module must also stay dependency-free for that reason.
+ *
+ * @module lib/push/vapid
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.VAPID_ENV_KEYS = exports.VAPID_DEFAULT_SUBJECT = void 0;
+exports.extractVapidSubjectHost = extractVapidSubjectHost;
+exports.classifyVapidSubject = classifyVapidSubject;
+exports.inspectVapidConfig = inspectVapidConfig;
+exports.formatVapidReportLines = formatVapidReportLines;
+exports.runVapidSelfCheck = runVapidSelfCheck;
+exports.getVapidConfig = getVapidConfig;
+exports.isPushConfigured = isPushConfigured;
+exports.getVapidPublicKey = getVapidPublicKey;
+/**
+ * Default `sub` claim when `CM_VAPID_SUBJECT` is unset.
+ *
+ * A real, resolvable https: URL — see the module header for the APNs measurement
+ * that made `mailto:commandmate@localhost` the wrong answer (Issue #2124).
+ */
+exports.VAPID_DEFAULT_SUBJECT = 'https://github.com/Kewton/CommandMate';
+/** The three environment variables that configure Web Push. */
+exports.VAPID_ENV_KEYS = {
+    publicKey: 'CM_VAPID_PUBLIC_KEY',
+    privateKey: 'CM_VAPID_PRIVATE_KEY',
+    subject: 'CM_VAPID_SUBJECT',
+};
+/**
+ * Host suffixes that never resolve on the public internet, so a push service can
+ * never verify a `sub` that names one.
+ *
+ * `.example` is here as a *TLD*; `example.com` is an ordinary resolvable domain
+ * and is deliberately NOT rejected (it is the conventional placeholder in every
+ * VAPID tutorial and in this repository's own tests).
+ */
+const NON_ROUTABLE_TLDS = [
+    'local',
+    'localhost',
+    'localdomain',
+    'internal',
+    'intranet',
+    'home',
+    'lan',
+    'test',
+    'invalid',
+    'example',
+];
+/** Loopback / unspecified literals, which are never a contact anyone can reach. */
+function isLoopbackLiteral(host) {
+    if (host === '::1' || host === '0.0.0.0' || host === '::')
+        return true;
+    return /^127\.\d{1,3}\.\d{1,3}\.\d{1,3}$/.test(host);
+}
+/**
+ * The host a subject names, lowercased, or `null` when it names none.
+ *
+ * `mailto:` takes everything after the LAST `@` (a local part may legally contain
+ * one when quoted) up to the first `?` (RFC 6068 header separator). `https:` is
+ * parsed by `URL`, whose `hostname` already strips the brackets off an IPv6
+ * literal.
+ */
+function extractVapidSubjectHost(subject) {
+    const trimmed = subject.trim();
+    if (/^mailto:/i.test(trimmed)) {
+        const address = trimmed.slice('mailto:'.length).split('?')[0];
+        const at = address.lastIndexOf('@');
+        if (at < 0)
+            return null;
+        const host = address.slice(at + 1).trim().toLowerCase();
+        return host.length > 0 ? host : null;
+    }
+    try {
+        const url = new URL(trimmed);
+        return url.hostname.length > 0 ? url.hostname.toLowerCase() : null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Decide whether a `sub` claim is one a push service can be expected to accept.
+ *
+ * Deliberately conservative: it rejects only hosts that provably cannot resolve.
+ * A reachable-but-wrong contact (`mailto:nobody@example.com`) is the operator's
+ * business, and a check that guessed at it would warn on healthy installs.
+ *
+ * @param subject - Raw `CM_VAPID_SUBJECT`, or the default.
+ * @returns The problem, or `null` when the subject is usable.
+ */
+function classifyVapidSubject(subject) {
+    const trimmed = subject.trim();
+    if (!/^(mailto:|https:\/\/)/i.test(trimmed))
+        return 'unsupported-scheme';
+    const host = extractVapidSubjectHost(trimmed);
+    if (host === null)
+        return 'missing-host';
+    if (isLoopbackLiteral(host))
+        return 'non-routable-host';
+    // A bare name (`localhost`, `mac-mini`) has no public resolution path.
+    if (!host.includes('.'))
+        return 'non-routable-host';
+    const tld = host.slice(host.lastIndexOf('.') + 1);
+    if (NON_ROUTABLE_TLDS.includes(tld))
+        return 'non-routable-host';
+    return null;
+}
+/**
+ * Read the three variables and say, in one verdict, everything both Issues need
+ * reported: whether push is on at all (#2123) and whether the subject will be
+ * accepted (#2124).
+ *
+ * ONE check, two facts — deliberately not two checks. The startup log, the
+ * `commandmate status` output and the unit suite all consume this one function,
+ * so the two surfaces cannot drift apart.
+ *
+ * Pure: no I/O, no logging, never throws.
+ *
+ * @param env - Environment to read (default: `process.env`). `commandmate status`
+ *   passes the env the *daemon* runs with, which is not this process's own.
+ */
+function inspectVapidConfig(env = process.env) {
+    const publicKey = env[exports.VAPID_ENV_KEYS.publicKey]?.trim() ?? '';
+    const privateKey = env[exports.VAPID_ENV_KEYS.privateKey]?.trim() ?? '';
+    const rawSubject = env[exports.VAPID_ENV_KEYS.subject]?.trim() ?? '';
+    const presentKeys = [];
+    const missingKeys = [];
+    (publicKey ? presentKeys : missingKeys).push(exports.VAPID_ENV_KEYS.publicKey);
+    (privateKey ? presentKeys : missingKeys).push(exports.VAPID_ENV_KEYS.privateKey);
+    const subject = rawSubject || exports.VAPID_DEFAULT_SUBJECT;
+    const subjectSource = rawSubject ? 'env' : 'default';
+    const subjectIssue = classifyVapidSubject(subject);
+    if (rawSubject)
+        presentKeys.push(exports.VAPID_ENV_KEYS.subject);
+    const configured = publicKey !== '' && privateKey !== '';
+    const status = configured
+        ? subjectIssue === null
+            ? 'ok'
+            : 'invalid-subject'
+        : publicKey || privateKey
+            ? 'partial'
+            : 'unconfigured';
+    return {
+        status,
+        configured,
+        subject,
+        subjectSource,
+        subjectIssue,
+        presentKeys,
+        missingKeys,
+    };
+}
+/** Human-readable reason for a {@link VapidSubjectIssue}. */
+function describeSubjectIssue(issue) {
+    switch (issue) {
+        case 'unsupported-scheme':
+            return 'it is neither a "mailto:" address nor an "https://" URL (RFC 8292 allows only those two)';
+        case 'missing-host':
+            return 'it names no host at all';
+        case 'non-routable-host':
+            return 'its host cannot be resolved from the public internet (localhost, a bare name, or a reserved TLD)';
+    }
+}
+/**
+ * The startup / `status` report, as lines — shared by both surfaces so they can
+ * never drift apart, exactly as `formatLocalhostConflictWarning` is (#2113).
+ *
+ * **Returns an empty array when the configuration is healthy.** That silence is
+ * the negative control both Issues ask for: a correctly configured server prints
+ * nothing about push, so the presence of a line is itself the signal.
+ *
+ * Never includes a key or a private value. `subject` is printed because it is the
+ * value the operator has to fix, and it is a contact address rather than a
+ * credential — the module header's "never log the config" rule is about the keys.
+ */
+function formatVapidReportLines(inspection) {
+    switch (inspection.status) {
+        case 'ok':
+            return [];
+        case 'unconfigured':
+            return [
+                'Push notifications are disabled: no VAPID keys are configured.',
+                `  Set ${exports.VAPID_ENV_KEYS.publicKey} and ${exports.VAPID_ENV_KEYS.privateKey} to enable them.`,
+                '  "commandmate init" generates a key pair for you.',
+                '  Setup: docs/user-guide/webapp-guide.md ("Phone notifications")',
+            ];
+        case 'partial':
+            return [
+                `Push notifications are disabled: ${inspection.missingKeys.join(' and ')} ${inspection.missingKeys.length > 1 ? 'are' : 'is'} not set.`,
+                `  Both ${exports.VAPID_ENV_KEYS.publicKey} and ${exports.VAPID_ENV_KEYS.privateKey} are required;` +
+                    ' a key pair only works as a pair.',
+                '  "commandmate init" generates a key pair for you.',
+                '  Setup: docs/user-guide/webapp-guide.md ("Phone notifications")',
+            ];
+        case 'invalid-subject':
+            return [
+                `${exports.VAPID_ENV_KEYS.subject}="${inspection.subject}" will be rejected by Apple (APNs):` +
+                    ` ${describeSubjectIssue(inspection.subjectIssue)}.`,
+                '  iPhone/iPad receive nothing while Android keeps working, because FCM does not check it.',
+                `  Use a reachable contact, e.g. ${exports.VAPID_DEFAULT_SUBJECT} or mailto:you@your-domain.example.org.`,
+                `  Unset ${exports.VAPID_ENV_KEYS.subject} to fall back to ${exports.VAPID_DEFAULT_SUBJECT}.`,
+            ];
+    }
+}
+/**
+ * Run the startup self-check and print its verdict, or nothing when healthy.
+ *
+ * Fail-open by construction, the same contract `runLocalhostSelfCheck` carries:
+ * it never throws, it never blocks `listen`, and a healthy install is silent.
+ *
+ * @returns The inspection, or `null` when the check itself could not be carried
+ *   out (which is reported as nothing at all).
+ */
+function runVapidSelfCheck(options = {}) {
+    const { env = process.env, warn = (message) => console.warn(message) } = options;
+    try {
+        const inspection = inspectVapidConfig(env);
+        for (const line of formatVapidReportLines(inspection)) {
+            warn(line);
+        }
+        return inspection;
+    }
+    catch {
+        // A diagnostic must never be the reason a server fails to start.
+        return null;
+    }
+}
+/**
+ * Returns the VAPID config, or null when push is not configured (both public
+ * and private keys must be present). Read from env on every call.
+ */
+function getVapidConfig() {
+    const publicKey = process.env[exports.VAPID_ENV_KEYS.publicKey]?.trim();
+    const privateKey = process.env[exports.VAPID_ENV_KEYS.privateKey]?.trim();
+    if (!publicKey || !privateKey) {
+        return null;
+    }
+    const subject = process.env[exports.VAPID_ENV_KEYS.subject]?.trim() || exports.VAPID_DEFAULT_SUBJECT;
+    return { publicKey, privateKey, subject };
+}
+/** True when both VAPID keys are configured. */
+function isPushConfigured() {
+    return getVapidConfig() !== null;
+}
+/** The public (application server) key clients need to subscribe, or null. */
+function getVapidPublicKey() {
+    return getVapidConfig()?.publicKey ?? null;
+}

package/dist/lib/remote/cloudflare.d.ts

@@ -0,0 +1,285 @@
+/**
+ * Cloudflare Quick Tunnel Provider (Issue #1937, R2).
+ *
+ * Implements §6.4 of `docs/design/remote-qr-pairing-1937.md`. Everything below
+ * that says "measured" was measured on 2026-08-29 against cloudflared 2025.4.0;
+ * the raw capture is in `dev-reports/issue/1937/u3-quicktunnel-url.md`.
+ *
+ * ## Three properties this file is responsible for
+ *
+ * 1. **Nothing but loopback is ever exposed.** `LOOPBACK_HOST` is a constant and
+ *    is never derived from an argument, so neither the upstream nor the metrics
+ *    listener can be pointed anywhere else. That matters twice over for
+ *    `--metrics`: `cloudflared tunnel --help` says its default address "binds to
+ *    all interfaces" under a virtual environment. CommandMate defaults `CM_BIND`
+ *    to 127.0.0.1, and opening a hole in the Provider's own diagnostics port
+ *    would give that back.
+ *
+ * 2. **`stop()` only signals the process this module started.** A Quick Tunnel
+ *    writes no persistent Provider configuration, so `preexisting` is `null` and
+ *    `owned.revert` is `null`; the whole teardown is one SIGTERM to `owned.pid`.
+ *    Measured: the process is gone in about a second and the public URL then
+ *    answers HTTP 530. There is no reason to reach for any command that acts on
+ *    "every tunnel this machine knows about", and
+ *    `tests/unit/config/remote-destructive-command-guard.test.ts` forbids it.
+ *    This is not hypothetical — the machine this was measured on had a named
+ *    tunnel of the user's own running for nine days at the time.
+ *
+ * 3. **The URL comes from the metrics API first.** Measured order: the stderr
+ *    banner appears at t+3s, the metrics server only at t+4s. So a loop that
+ *    tried both every round would find the banner first every single time and
+ *    `/quicktunnel` would be dead code. `METRICS_PREFERENCE_WINDOW_MS` is what
+ *    keeps the first candidate actually first: for that long, only the metrics
+ *    route is consulted.
+ *
+ * 4. **The tunnel outlives the CLI that started it.** `commandmate remote up`
+ *    exits as soon as it has a URL — measured at about 6.5 seconds, taken from
+ *    the metrics API. cloudflared has to still be there afterwards, because the
+ *    whole point is a QR code someone reads with a phone a minute later. Two
+ *    things make that true, and Issue #2146 is what happens without them:
+ *    cloudflared's stderr goes to a **file descriptor, never a pipe**, and the
+ *    child is spawned `detached` and `unref`ed.
+ *
+ *    Measured (Issue #2146, `docs/qa/1937-remote-uat-record.md` D-1): with
+ *    `stdio: ['ignore', 'ignore', 'pipe']` the child was dead within two
+ *    seconds of the parent exiting, and the public URL answered HTTP 530 before
+ *    the QR code could be read. The parent's exit closes the read end of that
+ *    pipe; cloudflared is Go, does not ignore SIGPIPE, and dies on its next
+ *    write to fd 2 — which, at t+6.5s, is still mid log-burst. The same argv
+ *    with a parent kept alive for 70 seconds gave a child that lived 70
+ *    seconds, so this is the plumbing and not cloudflared giving up.
+ *
+ *    `'ignore'` would also have fixed it and is the wrong fix: it takes fd 2
+ *    away entirely, and fd 2 is where both the **second URL candidate**
+ *    (`parseBannerUrl`) and every failure diagnostic (`stderrTail`) come from.
+ *    A file keeps both — nothing closes when the CLI exits, and the parser and
+ *    the diagnostic read it back by path. `--logfile` was the other candidate:
+ *    it covers cloudflared's own log lines but not anything the Go runtime or
+ *    the loader writes straight to fd 2, so fd 2 would still have been a pipe.
+ *    `'ignore'` for fd 2 is what this falls back to only when the log file
+ *    cannot be opened at all: a diagnostic is worth less than a working tunnel.
+ *
+ * Deliberately absent: the approval prompt. Creating a public URL is an
+ * irreversible, user-facing decision, and §6.2 puts it in the orchestrator that
+ * owns `src/cli/commands/remote.ts` — the same code that knows whether the
+ * session is interactive and whether `--yes` was passed.
+ *
+ * This module imports Node builtins and `./types` only. No `@/` alias, so the
+ * orchestrator can pull it into the `tsconfig.cli.json` build (which sets
+ * `paths: {}`) without the import failing to resolve.
+ */
+import { type SpawnOptions, type SpawnSyncOptionsWithStringEncoding, type SpawnSyncReturns } from 'child_process';
+import { type RemoteProvider } from './types';
+/** The executable. Looked up on PATH by `spawn`, never through a shell. */
+export declare const CLOUDFLARED_BIN = "cloudflared";
+/** Mirrors `PreflightChecker.checkDependency()`: one flag, passed as an array. */
+export declare const CLOUDFLARED_VERSION_ARG = "--version";
+/**
+ * The only host this Provider ever names.
+ *
+ * A constant rather than a parameter on purpose: "the upstream is always
+ * loopback" is then a property of the code, not of every call site. §9.2 pins it
+ * from the outside as well, by asserting the argv `start()` builds.
+ */
+export declare const LOOPBACK_HOST = "127.0.0.1";
+/** Quick Tunnel hostnames live under this suffix, and nothing else does. */
+export declare const QUICK_TUNNEL_SUFFIX = "trycloudflare.com";
+/** Written next to the rest of CommandMate's state, for humans and for `ps`. */
+export declare const CLOUDFLARED_PIDFILE_NAME = "cloudflared.pid";
+/**
+ * Where cloudflared's stderr goes. Beside the pidfile, and for the same reason:
+ * a human who wants to know what the tunnel is doing should be able to find it.
+ *
+ * A fixed name, like the pidfile, so one `remote` session at a time is the
+ * assumption in both places rather than in one of them.
+ */
+export declare const CLOUDFLARED_LOG_NAME = "cloudflared.log";
+/** Same 5s budget `PreflightChecker` gives every other dependency probe. */
+export declare const DETECT_TIMEOUT_MS = 5000;
+/** How the wait for a public URL is paced. See `QuickTunnelTiming`. */
+export interface QuickTunnelTiming {
+    /** Total budget for the URL to appear before `start()` gives up. */
+    urlWaitMs: number;
+    /**
+     * How long only `/quicktunnel` is consulted.
+     *
+     * Measured: the banner lands ~1s *before* the metrics server is listening. A
+     * window shorter than that gap turns the documented first candidate into
+     * something that never runs.
+     */
+    metricsPreferenceMs: number;
+    /** Gap between polls. */
+    pollIntervalMs: number;
+}
+export declare const DEFAULT_QUICK_TUNNEL_TIMING: QuickTunnelTiming;
+/** Per-request budget for the loopback metrics call. */
+export declare const METRICS_REQUEST_TIMEOUT_MS = 1000;
+/**
+ * How much of the stderr log is read back, so a chatty reconnect loop cannot
+ * make either consumer grow unbounded.
+ *
+ * The **tail**, not the head: `parseBannerUrl` takes the last match on purpose
+ * (a reconnect banner should win), and `stderrTail` wants the last few lines.
+ */
+export declare const STDERR_CAPTURE_LIMIT: number;
+/**
+ * The part of a spawned cloudflared this module uses, and nothing more.
+ *
+ * No `stderr`: as of Issue #2146 fd 2 is a file, so there is no stream to read
+ * and nothing here that could be tempted to hold one open. `unref` is required
+ * rather than optional because forgetting it is exactly the class of mistake
+ * this interface exists to make impossible.
+ */
+export interface QuickTunnelProcess {
+    readonly pid?: number | undefined;
+    once(event: 'exit', listener: (code: number | null, signal: NodeJS.Signals | null) => void): unknown;
+    kill(signal?: NodeJS.Signals): boolean;
+    /** Releases the parent's event-loop reference to this child. */
+    unref(): unknown;
+}
+export type SpawnQuickTunnel = (command: string, args: readonly string[], options: SpawnOptions) => QuickTunnelProcess;
+export type SpawnSyncProbe = (command: string, args: readonly string[], options: SpawnSyncOptionsWithStringEncoding) => SpawnSyncReturns<string>;
+/**
+ * The seams that let this Provider be tested without a public tunnel.
+ *
+ * They are constructor arguments rather than members of the Provider because
+ * `RemoteProvider` is pinned to exactly `id` / `detect` / `start` / `stop`
+ * (§6.3-1): the returned object must not grow a fifth key.
+ */
+export interface CloudflareProviderDeps {
+    spawn: SpawnQuickTunnel;
+    spawnSync: SpawnSyncProbe;
+    /** Signals a process. Defaults to `process.kill`. */
+    kill: (pid: number, signal: NodeJS.Signals) => void;
+    /** Picks the `--metrics` port. Bound on loopback, then released. */
+    findFreePort: () => Promise<number>;
+    /** The first URL candidate: `GET /quicktunnel` on the metrics listener. */
+    fetchHostname: (metricsPort: number) => Promise<string | null>;
+    /** Directory the pidfile goes in. */
+    resolveStateDir: () => string;
+    timing: QuickTunnelTiming;
+}
+/**
+ * The argv for one Quick Tunnel.
+ *
+ * `LOOPBACK_HOST` appears twice and is a constant both times. `port` is the only
+ * caller-supplied value that reaches the command line, and it is validated as a
+ * port number before it gets here.
+ */
+export declare function buildQuickTunnelArgs(opts: {
+    port: number;
+    metricsPort: number;
+    pidfile: string;
+}): string[];
+/**
+ * The spawn options for one Quick Tunnel. Issue #2146 is entirely about these.
+ *
+ * `stderr` is a **file descriptor**, or `'ignore'` when the log file could not
+ * be opened. It is never `'pipe'`: a pipe's read end belongs to `commandmate
+ * remote`, which exits as soon as it has the URL, and cloudflared then dies of
+ * SIGPIPE on its next write to fd 2. See the file header for the measurement.
+ *
+ * `detached: true` puts the child in its own session. Without it, a Ctrl-C in
+ * the terminal that launched the CLI reaches cloudflared too — the tunnel is
+ * supposed to outlive the command, so it must not share its process group.
+ * `stop()` is unaffected: it signals a **positive** pid, which is one process,
+ * not a group, so detaching changes nothing about teardown.
+ */
+export declare function buildQuickTunnelSpawnOptions(stderr: number | 'ignore'): SpawnOptions;
+/**
+ * cloudflared's stderr, as this module hands it out and reads it back.
+ *
+ * Two consumers depend on it and both survive the change from a pipe to a file,
+ * because a file can be re-read by path at any time: `parseBannerUrl()` (the
+ * second URL candidate) and `stderrTail()` (the failure diagnostic).
+ */
+export interface StderrLog {
+    /** Goes in slot 2 of `stdio`. A descriptor, or `'ignore'`. Never `'pipe'`. */
+    readonly stdio: number | 'ignore';
+    /** The file being written to, or `null` when there is none. */
+    readonly path: string | null;
+    /** The tail of what cloudflared has written so far. Never throws. */
+    read(): string;
+    /** Closes this process's copy of the descriptor. The child keeps its own. */
+    close(): void;
+}
+/**
+ * Opens the file cloudflared's stderr is redirected into.
+ *
+ * Truncating (`'w'`) rather than appending, because `parseBannerUrl()` takes the
+ * last URL in the buffer and a previous session's banner names a tunnel that no
+ * longer exists. Starting from empty means the only banner that can be read is
+ * this session's.
+ *
+ * Returns `SILENT_STDERR_LOG` rather than throwing when the file cannot be
+ * opened: `start()` still has `/quicktunnel` — the *first* URL candidate — and
+ * a tunnel with no diagnostics beats no tunnel.
+ */
+export declare function openStderrLog(logPath: string): StderrLog;
+/** True for a hostname cloudflared could actually have handed out. */
+export declare function isQuickTunnelHostname(value: string): boolean;
+/**
+ * Reads the hostname out of a `/quicktunnel` response body.
+ *
+ * Measured body: `{"hostname":"villas-activists-hey-barbie.trycloudflare.com"}`
+ * — served as `text/plain`, and **without a scheme**, so the `https://` is ours
+ * to add. The shape is checked before it is used because this string becomes the
+ * QR code a phone is asked to open; a value that is not a Quick Tunnel hostname
+ * is treated as no answer rather than as a destination.
+ */
+export declare function parseQuickTunnelHostname(body: string): string | null;
+/**
+ * Second candidate: the URL cloudflared prints on stderr.
+ *
+ * Anchored on the **shape of the URL**, not on the surrounding words. Two
+ * measured facts drive that. The banner text and the URL are on *different*
+ * lines — the URL sits alone inside a box-drawn frame — so "read what follows
+ * `Visit it at`" does not work against the real output. And the wording is
+ * exactly the part Cloudflare is free to reword, while the hostname suffix is
+ * the service's identity.
+ *
+ * The same stderr also carries `https://www.cloudflare.com/website-terms/` and
+ * `https://developers.cloudflare.com/...`; neither ends in the Quick Tunnel
+ * suffix, and the `Requesting new quick Tunnel on trycloudflare.com...` line has
+ * no scheme. All three are negative controls in the unit test.
+ *
+ * The last match wins, so a reconnect that prints a fresher banner is preferred.
+ */
+export declare function parseBannerUrl(stderr: string): string | null;
+/**
+ * Asks the OS for a free port on loopback and hands it back unheld.
+ *
+ * Binding the probe to `LOOPBACK_HOST` rather than to every interface is part of
+ * the same guarantee as the `--metrics` argument: the port this returns is one
+ * that is free *on loopback*, which is the only place it will be used.
+ */
+export declare function findFreeLoopbackPort(): Promise<number>;
+/**
+ * `GET http://127.0.0.1:<metricsPort>/quicktunnel`.
+ *
+ * Never rejects: "no answer yet" and "no such route" are both normal during the
+ * poll, and neither should look different from a slow start.
+ */
+export declare function fetchQuickTunnelHostname(metricsPort: number, timeoutMs?: number): Promise<string | null>;
+/**
+ * Where the pidfile goes: the same `~/.commandmate` the rest of CommandMate
+ * uses.
+ *
+ * Not read from the environment. §6.2 keeps state-file locations out of
+ * Providers, and an env-supplied directory would also have to defend against the
+ * `/proc` recursive-mkdir hang that `resolveSafeDirectory()` exists for. Tests
+ * override it through `CloudflareProviderDeps` instead.
+ */
+export declare function resolveCloudflareStateDir(): string;
+export declare const defaultCloudflareDeps: CloudflareProviderDeps;
+/**
+ * Builds the Provider.
+ *
+ * The returned object has exactly the four members `RemoteProvider` declares —
+ * the seams stay closed over in here rather than becoming a fifth key, because
+ * the contract test pins that list and §6.3-1 is the reason it does.
+ */
+export declare function createCloudflareProvider(overrides?: Partial<CloudflareProviderDeps>): RemoteProvider;
+/** The shipped Provider, wired to the real `cloudflared`. */
+export declare const cloudflareProvider: RemoteProvider;
+//# sourceMappingURL=cloudflare.d.ts.map

package/dist/lib/remote/cloudflare.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cloudflare.d.ts","sourceRoot":"","sources":["../../../src/lib/remote/cloudflare.ts"],"names":[],"mappings":"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"}