commandmate 0.28.0 → 0.29.0

package/dist/cli/utils/remote-state.js

@@ -0,0 +1,193 @@
+"use strict";
+/**
+ * Persisted state of one `commandmate remote` session (Issue #1937, R9).
+ *
+ * Design: `docs/design/remote-qr-pairing-1937.md` §6.3.
+ *
+ * ## Why this file exists at all
+ *
+ * `remote stop` must undo exactly what `remote up` created and nothing else.
+ * The Provider interface enforces that structurally — `stop()` takes a
+ * `RemoteHandle` and there is no `reset()` / `cleanupAll()` to reach for — but
+ * the two commands are separate processes, so the handle has to survive on
+ * disk between them. This module is that hop, and nothing more: it stores, it
+ * does not interpret.
+ *
+ * ## Why "unreadable" is not "guess"
+ *
+ * `readRemoteState()` answers `null` for absent, unparseable and structurally
+ * wrong alike, and `remote stop` turns all three into "I do not know what to
+ * clean up" and exits SUCCESS (§6.3-4). That is deliberate and is the whole
+ * reason the reader validates rather than casts: a half-read state file must
+ * never become a Provider teardown aimed at configuration the user created.
+ * `stop.ts` treats a stale PID file the same way.
+ *
+ * ## Format
+ *
+ * Plain JSON with a `schemaVersion`, not `PidManager`'s hybrid
+ * "bare PID line + JSON line" shape. That format exists so a CLI predating
+ * #1354 can still `parseInt()` the first line; nothing has ever read this file,
+ * so there is no such reader to stay compatible with, and a PID is not what
+ * this record is about.
+ *
+ * The file is written 0600 like the pairing handoff. It holds no secret — the
+ * pairing code and the session token are never in it — but it names a public
+ * URL that reaches this machine, and that is not something to leave
+ * world-readable.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.REMOTE_STATE_SCHEMA_VERSION = exports.REMOTE_STATE_FILE_MODE = exports.REMOTE_STATE_FILE_NAME = void 0;
+exports.getRemoteStatePath = getRemoteStatePath;
+exports.writeRemoteState = writeRemoteState;
+exports.readRemoteState = readRemoteState;
+exports.removeRemoteState = removeRemoteState;
+exports.isRemoteState = isRemoteState;
+const fs_1 = require("fs");
+const path_1 = require("path");
+const install_context_1 = require("./install-context");
+/** File name inside the config directory (`~/.commandmate` for global installs). */
+exports.REMOTE_STATE_FILE_NAME = 'remote.json';
+/** Owner read/write only. Asserted by tests, not merely intended. */
+exports.REMOTE_STATE_FILE_MODE = 0o600;
+/**
+ * Bumped when a field changes meaning. A reader that does not recognise the
+ * version returns null, which routes to "nothing to clean up" rather than to a
+ * teardown driven by a record it does not understand.
+ */
+exports.REMOTE_STATE_SCHEMA_VERSION = 1;
+/**
+ * Absolute path of the state file.
+ *
+ * @returns `<configDir>/remote.json`
+ */
+function getRemoteStatePath() {
+    return (0, path_1.join)((0, install_context_1.getConfigDir)(), exports.REMOTE_STATE_FILE_NAME);
+}
+/**
+ * Write the state file with mode 0600.
+ *
+ * An existing file is unlinked first: `writeFileSync`'s `mode` is only honoured
+ * on creation, so writing over a file left world-readable by something else
+ * would silently keep those permissions. Mirrors `writePairingHandoff()`.
+ *
+ * @param state - The session record to persist
+ * @param filePath - Override for the destination, for tests
+ */
+function writeRemoteState(state, filePath) {
+    const target = filePath ?? (0, path_1.join)((0, install_context_1.ensureConfigDir)(), exports.REMOTE_STATE_FILE_NAME);
+    (0, fs_1.mkdirSync)((0, path_1.dirname)(target), { recursive: true, mode: 0o700 });
+    try {
+        (0, fs_1.unlinkSync)(target);
+    }
+    catch {
+        // Not there yet - the normal case.
+    }
+    (0, fs_1.writeFileSync)(target, JSON.stringify(state, null, 2), {
+        encoding: 'utf8',
+        mode: exports.REMOTE_STATE_FILE_MODE,
+    });
+    (0, fs_1.chmodSync)(target, exports.REMOTE_STATE_FILE_MODE);
+}
+/**
+ * Read and validate the state file.
+ *
+ * @param filePath - Override for the source, for tests
+ * @returns The state, or null when it is absent, unreadable or not this schema
+ */
+function readRemoteState(filePath) {
+    const target = filePath ?? getRemoteStatePath();
+    let raw;
+    try {
+        raw = (0, fs_1.readFileSync)(target, 'utf8');
+    }
+    catch {
+        return null;
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        return null;
+    }
+    return isRemoteState(parsed) ? parsed : null;
+}
+/**
+ * Delete the state file. Idempotent — a missing file is success.
+ *
+ * @param filePath - Override for the target, for tests
+ */
+function removeRemoteState(filePath) {
+    try {
+        (0, fs_1.unlinkSync)(filePath ?? getRemoteStatePath());
+    }
+    catch {
+        // Already gone: the state we wanted.
+    }
+}
+/**
+ * Structural check for a parsed state file.
+ *
+ * Every field `remote stop` and `remote status` read is checked, because the
+ * cost of being wrong is asymmetric: a rejected record costs the user one
+ * "nothing to clean up" message, an accepted-but-wrong one aims a Provider
+ * teardown at a handle nobody wrote.
+ *
+ * @param value - Parsed JSON
+ * @returns true when the value is a state record of the current schema
+ */
+function isRemoteState(value) {
+    if (typeof value !== 'object' || value === null)
+        return false;
+    const record = value;
+    if (record.schemaVersion !== exports.REMOTE_STATE_SCHEMA_VERSION)
+        return false;
+    if (record.provider !== 'tailscale-serve' && record.provider !== 'cloudflare-quick')
+        return false;
+    if (typeof record.url !== 'string' || record.url.length === 0)
+        return false;
+    if (typeof record.startedAt !== 'string')
+        return false;
+    if (typeof record.expiresAt !== 'number' || !Number.isFinite(record.expiresAt))
+        return false;
+    const pairing = record.pairing;
+    if (typeof pairing !== 'object' || pairing === null)
+        return false;
+    if (typeof pairing.filePath !== 'string' || pairing.filePath.length === 0)
+        return false;
+    if (typeof pairing.expiresAt !== 'number' || !Number.isFinite(pairing.expiresAt))
+        return false;
+    const server = record.server;
+    if (typeof server !== 'object' || server === null)
+        return false;
+    if (server.pid !== null && typeof server.pid !== 'number')
+        return false;
+    if (typeof server.port !== 'number')
+        return false;
+    return isRemoteHandle(record.handle);
+}
+/**
+ * @param value - Candidate handle from a parsed state file
+ * @returns true when the value carries everything `stop()` needs
+ */
+function isRemoteHandle(value) {
+    if (typeof value !== 'object' || value === null)
+        return false;
+    const handle = value;
+    if (handle.provider !== 'tailscale-serve' && handle.provider !== 'cloudflare-quick')
+        return false;
+    if (typeof handle.url !== 'string')
+        return false;
+    const owned = handle.owned;
+    if (typeof owned !== 'object' || owned === null)
+        return false;
+    if (owned.pid !== null && typeof owned.pid !== 'number')
+        return false;
+    if (owned.revert !== null && (typeof owned.revert !== 'object' || owned.revert === undefined)) {
+        return false;
+    }
+    // `preexisting` is deliberately `unknown` in the interface: its shape is the
+    // Provider's business, and `planStop()` narrows it itself. Requiring the key
+    // to be present is as far as this reader can honestly go.
+    return 'preexisting' in handle;
+}

package/dist/config/auth-config.d.ts

@@ -20,7 +20,7 @@ export declare function isValidTokenHash(hash: string | undefined): hash is stri
  * Paths excluded from authentication check.
  * S002: Must use === for matching (no startsWith - bypass attack prevention)
  */
-export declare const AUTH_EXCLUDED_PATHS: readonly ["/login", "/api/auth/login", "/api/auth/logout", "/api/auth/status", "/manifest.webmanifest", "/sw.js", "/offline"];
+export declare const AUTH_EXCLUDED_PATHS: readonly ["/login", "/api/auth/login", "/api/auth/logout", "/api/auth/status", "/api/remote/pair", "/manifest.webmanifest", "/sw.js", "/offline"];
 /** Default token expiration duration (24 hours) */
 export declare const DEFAULT_EXPIRE_DURATION_MS: number;
 /**

package/dist/config/auth-config.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"auth-config.d.ts","sourceRoot":"","sources":["../../src/config/auth-config.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,2CAA2C;AAC3C,eAAO,MAAM,gBAAgB,EAAG,eAAwB,CAAC;AAKzD;;;;;;;GAOG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,SAAS,GAAG,IAAI,IAAI,MAAM,CAEzE;AAED;;;GAGG;AACH,eAAO,MAAM,mBAAmB,+HAWtB,CAAC;AAeX,mDAAmD;AACnD,eAAO,MAAM,0BAA0B,QAAmB,CAAC;AAQ3D;;;;;;;;GAQG;AACH,wBAAgB,aAAa,CAAC,CAAC,EAAE,MAAM,GAAG,MAAM,CAgC/C;AAED;;;;;GAKG;AACH,wBAAgB,eAAe,IAAI,MAAM,GAAG,IAAI,CAgB/C"}
+{"version":3,"file":"auth-config.d.ts","sourceRoot":"","sources":["../../src/config/auth-config.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,2CAA2C;AAC3C,eAAO,MAAM,gBAAgB,EAAG,eAAwB,CAAC;AAKzD;;;;;;;GAOG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,SAAS,GAAG,IAAI,IAAI,MAAM,CAEzE;AAED;;;GAGG;AACH,eAAO,MAAM,mBAAmB,mJAgBtB,CAAC;AAeX,mDAAmD;AACnD,eAAO,MAAM,0BAA0B,QAAmB,CAAC;AAQ3D;;;;;;;;GAQG;AACH,wBAAgB,aAAa,CAAC,CAAC,EAAE,MAAM,GAAG,MAAM,CAgC/C;AAED;;;;;GAKG;AACH,wBAAgB,eAAe,IAAI,MAAM,GAAG,IAAI,CAgB/C"}

package/dist/config/auth-config.js

@@ -35,6 +35,11 @@ exports.AUTH_EXCLUDED_PATHS = [
     '/api/auth/login',
     '/api/auth/logout',
     '/api/auth/status',
+    // Issue #1937 (R5): one-shot pairing-code exchange for `commandmate remote`.
+    // The pairing SCREEN is '/login' above, driven by a '#code=' fragment, so
+    // this is the only entry the remote feature adds. Handler:
+    // src/app/api/remote/pair/route.ts (it authenticates the code itself).
+    '/api/remote/pair',
     // Issue #1124 (PWA): non-sensitive resources that must stay reachable before
     // auth so the app is installable and the offline fallback can be precached.
     // All carry no user data (app metadata / public SW code / static fallback).

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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"}