commandmate 0.28.0 → 0.29.0

package/dist/lib/remote/index.js

@@ -0,0 +1,64 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.tailscaleProvider = exports.TAILSCALE_VERSION_ARG = exports.TAILSCALE_BIN = exports.snapshotServeConfig = exports.serveHandlerKeys = exports.serveHandlerKey = exports.SERVE_TIMEOUT_MS = exports.SERVE_PATH = exports.SERVE_HTTPS_PORT = exports.readServeReadiness = exports.parseServeHandlerKey = exports.parseServeConfig = exports.normalizeDnsName = exports.TAILSCALE_LOOPBACK_HOST = exports.TAILSCALE_DETECT_TIMEOUT_MS = exports.createTailscaleProvider = exports.buildServeUrl = exports.buildServeOffArgs = exports.buildServeArgs = exports.BACKEND_STATE_RUNNING = exports.STDERR_CAPTURE_LIMIT = exports.resolveCloudflareStateDir = exports.QUICK_TUNNEL_SUFFIX = exports.parseQuickTunnelHostname = exports.parseBannerUrl = exports.openStderrLog = exports.LOOPBACK_HOST = exports.isQuickTunnelHostname = exports.findFreeLoopbackPort = exports.fetchQuickTunnelHostname = exports.DETECT_TIMEOUT_MS = exports.DEFAULT_QUICK_TUNNEL_TIMING = exports.createCloudflareProvider = exports.cloudflareProvider = exports.CLOUDFLARED_VERSION_ARG = exports.CLOUDFLARED_PIDFILE_NAME = exports.CLOUDFLARED_LOG_NAME = exports.CLOUDFLARED_BIN = exports.buildQuickTunnelSpawnOptions = exports.buildQuickTunnelArgs = exports.REMOTE_PROVIDER_ORDER = exports.detectRemoteProviders = exports.createRemoteProviders = exports.planStop = exports.isPreexistingSnapshot = void 0;
+/**
+ * Public surface of the remote Provider layer (Issue #1937, R1/R2/R3).
+ *
+ * Note what is not re-exported: there is no selection helper. The orchestrator
+ * that owns `src/cli/commands/remote.ts` (R9) applies the selection rule
+ * itself — see the header of `./provider-registry`.
+ *
+ * Both `CLOUDFLARE_NOT_IMPLEMENTED_REASON` (removed in R2) and
+ * `TAILSCALE_NOT_IMPLEMENTED_REASON` (removed here in R3) are gone for the same
+ * reason: both Providers are implemented, so a constant saying otherwise would
+ * be a lie a caller could still read and act on.
+ */
+var types_1 = require("./types");
+Object.defineProperty(exports, "isPreexistingSnapshot", { enumerable: true, get: function () { return types_1.isPreexistingSnapshot; } });
+Object.defineProperty(exports, "planStop", { enumerable: true, get: function () { return types_1.planStop; } });
+var provider_registry_1 = require("./provider-registry");
+Object.defineProperty(exports, "createRemoteProviders", { enumerable: true, get: function () { return provider_registry_1.createRemoteProviders; } });
+Object.defineProperty(exports, "detectRemoteProviders", { enumerable: true, get: function () { return provider_registry_1.detectRemoteProviders; } });
+Object.defineProperty(exports, "REMOTE_PROVIDER_ORDER", { enumerable: true, get: function () { return provider_registry_1.REMOTE_PROVIDER_ORDER; } });
+var cloudflare_1 = require("./cloudflare");
+Object.defineProperty(exports, "buildQuickTunnelArgs", { enumerable: true, get: function () { return cloudflare_1.buildQuickTunnelArgs; } });
+Object.defineProperty(exports, "buildQuickTunnelSpawnOptions", { enumerable: true, get: function () { return cloudflare_1.buildQuickTunnelSpawnOptions; } });
+Object.defineProperty(exports, "CLOUDFLARED_BIN", { enumerable: true, get: function () { return cloudflare_1.CLOUDFLARED_BIN; } });
+Object.defineProperty(exports, "CLOUDFLARED_LOG_NAME", { enumerable: true, get: function () { return cloudflare_1.CLOUDFLARED_LOG_NAME; } });
+Object.defineProperty(exports, "CLOUDFLARED_PIDFILE_NAME", { enumerable: true, get: function () { return cloudflare_1.CLOUDFLARED_PIDFILE_NAME; } });
+Object.defineProperty(exports, "CLOUDFLARED_VERSION_ARG", { enumerable: true, get: function () { return cloudflare_1.CLOUDFLARED_VERSION_ARG; } });
+Object.defineProperty(exports, "cloudflareProvider", { enumerable: true, get: function () { return cloudflare_1.cloudflareProvider; } });
+Object.defineProperty(exports, "createCloudflareProvider", { enumerable: true, get: function () { return cloudflare_1.createCloudflareProvider; } });
+Object.defineProperty(exports, "DEFAULT_QUICK_TUNNEL_TIMING", { enumerable: true, get: function () { return cloudflare_1.DEFAULT_QUICK_TUNNEL_TIMING; } });
+Object.defineProperty(exports, "DETECT_TIMEOUT_MS", { enumerable: true, get: function () { return cloudflare_1.DETECT_TIMEOUT_MS; } });
+Object.defineProperty(exports, "fetchQuickTunnelHostname", { enumerable: true, get: function () { return cloudflare_1.fetchQuickTunnelHostname; } });
+Object.defineProperty(exports, "findFreeLoopbackPort", { enumerable: true, get: function () { return cloudflare_1.findFreeLoopbackPort; } });
+Object.defineProperty(exports, "isQuickTunnelHostname", { enumerable: true, get: function () { return cloudflare_1.isQuickTunnelHostname; } });
+Object.defineProperty(exports, "LOOPBACK_HOST", { enumerable: true, get: function () { return cloudflare_1.LOOPBACK_HOST; } });
+Object.defineProperty(exports, "openStderrLog", { enumerable: true, get: function () { return cloudflare_1.openStderrLog; } });
+Object.defineProperty(exports, "parseBannerUrl", { enumerable: true, get: function () { return cloudflare_1.parseBannerUrl; } });
+Object.defineProperty(exports, "parseQuickTunnelHostname", { enumerable: true, get: function () { return cloudflare_1.parseQuickTunnelHostname; } });
+Object.defineProperty(exports, "QUICK_TUNNEL_SUFFIX", { enumerable: true, get: function () { return cloudflare_1.QUICK_TUNNEL_SUFFIX; } });
+Object.defineProperty(exports, "resolveCloudflareStateDir", { enumerable: true, get: function () { return cloudflare_1.resolveCloudflareStateDir; } });
+Object.defineProperty(exports, "STDERR_CAPTURE_LIMIT", { enumerable: true, get: function () { return cloudflare_1.STDERR_CAPTURE_LIMIT; } });
+var tailscale_1 = require("./tailscale");
+Object.defineProperty(exports, "BACKEND_STATE_RUNNING", { enumerable: true, get: function () { return tailscale_1.BACKEND_STATE_RUNNING; } });
+Object.defineProperty(exports, "buildServeArgs", { enumerable: true, get: function () { return tailscale_1.buildServeArgs; } });
+Object.defineProperty(exports, "buildServeOffArgs", { enumerable: true, get: function () { return tailscale_1.buildServeOffArgs; } });
+Object.defineProperty(exports, "buildServeUrl", { enumerable: true, get: function () { return tailscale_1.buildServeUrl; } });
+Object.defineProperty(exports, "createTailscaleProvider", { enumerable: true, get: function () { return tailscale_1.createTailscaleProvider; } });
+Object.defineProperty(exports, "TAILSCALE_DETECT_TIMEOUT_MS", { enumerable: true, get: function () { return tailscale_1.DETECT_TIMEOUT_MS; } });
+Object.defineProperty(exports, "TAILSCALE_LOOPBACK_HOST", { enumerable: true, get: function () { return tailscale_1.LOOPBACK_HOST; } });
+Object.defineProperty(exports, "normalizeDnsName", { enumerable: true, get: function () { return tailscale_1.normalizeDnsName; } });
+Object.defineProperty(exports, "parseServeConfig", { enumerable: true, get: function () { return tailscale_1.parseServeConfig; } });
+Object.defineProperty(exports, "parseServeHandlerKey", { enumerable: true, get: function () { return tailscale_1.parseServeHandlerKey; } });
+Object.defineProperty(exports, "readServeReadiness", { enumerable: true, get: function () { return tailscale_1.readServeReadiness; } });
+Object.defineProperty(exports, "SERVE_HTTPS_PORT", { enumerable: true, get: function () { return tailscale_1.SERVE_HTTPS_PORT; } });
+Object.defineProperty(exports, "SERVE_PATH", { enumerable: true, get: function () { return tailscale_1.SERVE_PATH; } });
+Object.defineProperty(exports, "SERVE_TIMEOUT_MS", { enumerable: true, get: function () { return tailscale_1.SERVE_TIMEOUT_MS; } });
+Object.defineProperty(exports, "serveHandlerKey", { enumerable: true, get: function () { return tailscale_1.serveHandlerKey; } });
+Object.defineProperty(exports, "serveHandlerKeys", { enumerable: true, get: function () { return tailscale_1.serveHandlerKeys; } });
+Object.defineProperty(exports, "snapshotServeConfig", { enumerable: true, get: function () { return tailscale_1.snapshotServeConfig; } });
+Object.defineProperty(exports, "TAILSCALE_BIN", { enumerable: true, get: function () { return tailscale_1.TAILSCALE_BIN; } });
+Object.defineProperty(exports, "TAILSCALE_VERSION_ARG", { enumerable: true, get: function () { return tailscale_1.TAILSCALE_VERSION_ARG; } });
+Object.defineProperty(exports, "tailscaleProvider", { enumerable: true, get: function () { return tailscale_1.tailscaleProvider; } });

package/dist/lib/remote/provider-registry.d.ts

@@ -0,0 +1,29 @@
+import type { ProviderDetection, RemoteProvider, RemoteProviderId } from './types';
+/**
+ * Preference order, most preferred first.
+ *
+ * Tailscale is first because it exposes the server only to the user's own
+ * tailnet; the Cloudflare Quick Tunnel puts it on the public internet. The
+ * order is data, not control flow — being second here never causes a fallback.
+ */
+export declare const REMOTE_PROVIDER_ORDER: readonly RemoteProviderId[];
+/** The shipped Providers, in `REMOTE_PROVIDER_ORDER`. */
+export declare function createRemoteProviders(): RemoteProvider[];
+/** One Provider and what probing it just said. */
+export interface ProviderCandidate {
+    provider: RemoteProvider;
+    detection: ProviderDetection;
+}
+/**
+ * Probes every Provider and returns all of them in preference order.
+ *
+ * Every candidate comes back, including the unusable ones: the caller needs the
+ * `reason` of the preferred Provider to explain why it is falling through to a
+ * question rather than to a tunnel.
+ *
+ * A Provider whose `detect()` throws is reported as unavailable rather than
+ * taking down the probe — a broken `tailscale` binary must not stop the user
+ * from seeing that `cloudflared` exists.
+ */
+export declare function detectRemoteProviders(providers?: readonly RemoteProvider[]): Promise<ProviderCandidate[]>;
+//# sourceMappingURL=provider-registry.d.ts.map

package/dist/lib/remote/provider-registry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"provider-registry.d.ts","sourceRoot":"","sources":["../../../src/lib/remote/provider-registry.ts"],"names":[],"mappings":"AA0BA,OAAO,KAAK,EAAE,iBAAiB,EAAE,cAAc,EAAE,gBAAgB,EAAE,MAAM,SAAS,CAAC;AAEnF;;;;;;GAMG;AACH,eAAO,MAAM,qBAAqB,EAAE,SAAS,gBAAgB,EAG5D,CAAC;AAEF,yDAAyD;AACzD,wBAAgB,qBAAqB,IAAI,cAAc,EAAE,CAExD;AAED,kDAAkD;AAClD,MAAM,WAAW,iBAAiB;IAChC,QAAQ,EAAE,cAAc,CAAC;IACzB,SAAS,EAAE,iBAAiB,CAAC;CAC9B;AAED;;;;;;;;;;GAUG;AACH,wBAAsB,qBAAqB,CACzC,SAAS,GAAE,SAAS,cAAc,EAA4B,GAC7D,OAAO,CAAC,iBAAiB,EAAE,CAAC,CAW9B"}

package/dist/lib/remote/provider-registry.js

@@ -0,0 +1,73 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.REMOTE_PROVIDER_ORDER = void 0;
+exports.createRemoteProviders = createRemoteProviders;
+exports.detectRemoteProviders = detectRemoteProviders;
+/**
+ * Provider registry for `commandmate remote` (Issue #1937, R1).
+ *
+ * What this module does: run every Provider's `detect()` and hand back the
+ * results **in preference order**.
+ *
+ * What this module deliberately does NOT do, and why (§6.2):
+ *
+ * - It does not pick a Provider. "Tailscale first, and never fall back to a
+ *   public tunnel on its own" is a rule about selection, not a property of
+ *   either Provider. Putting it here would bury an irreversible decision —
+ *   exposing the machine through a third party — inside a probe helper. The
+ *   orchestrator (`src/cli/commands/remote.ts`, R9) reads this ordered list,
+ *   applies the rule, and asks the user before anything public is created.
+ * - It does not prompt. A prompt in here would have to re-derive
+ *   interactive-vs-not per Provider, and the answer would be invisible to the
+ *   caller that has to honour `--yes`.
+ * - It does not know about `~/.commandmate/remote.json`. Persistence is the
+ *   orchestrator's; a Provider that can read the state file is one refactor
+ *   away from "clean up whatever the state file forgot".
+ *
+ * A test pins the export list of this module so that a future `selectProvider()`
+ * cannot be added here without someone having to delete that assertion.
+ */
+const cloudflare_1 = require("./cloudflare");
+const tailscale_1 = require("./tailscale");
+/**
+ * Preference order, most preferred first.
+ *
+ * Tailscale is first because it exposes the server only to the user's own
+ * tailnet; the Cloudflare Quick Tunnel puts it on the public internet. The
+ * order is data, not control flow — being second here never causes a fallback.
+ */
+exports.REMOTE_PROVIDER_ORDER = [
+    'tailscale-serve',
+    'cloudflare-quick',
+];
+/** The shipped Providers, in `REMOTE_PROVIDER_ORDER`. */
+function createRemoteProviders() {
+    return [tailscale_1.tailscaleProvider, cloudflare_1.cloudflareProvider];
+}
+/**
+ * Probes every Provider and returns all of them in preference order.
+ *
+ * Every candidate comes back, including the unusable ones: the caller needs the
+ * `reason` of the preferred Provider to explain why it is falling through to a
+ * question rather than to a tunnel.
+ *
+ * A Provider whose `detect()` throws is reported as unavailable rather than
+ * taking down the probe — a broken `tailscale` binary must not stop the user
+ * from seeing that `cloudflared` exists.
+ */
+async function detectRemoteProviders(providers = createRemoteProviders()) {
+    const ordered = [...providers].sort((a, b) => exports.REMOTE_PROVIDER_ORDER.indexOf(a.id) - exports.REMOTE_PROVIDER_ORDER.indexOf(b.id));
+    return Promise.all(ordered.map(async (provider) => ({
+        provider,
+        detection: await probe(provider),
+    })));
+}
+async function probe(provider) {
+    try {
+        return await provider.detect();
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        return { available: false, ready: false, reason: `detect() failed: ${message}` };
+    }
+}

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

@@ -0,0 +1,268 @@
+/**
+ * Tailscale Serve Provider (Issue #1937, R3).
+ *
+ * Implements §6.1–§6.3 of `docs/design/remote-qr-pairing-1937.md`. §6.4's
+ * Tailscale table was written as a guess on a machine that had no `tailscale`
+ * at all (U-2). Everything below marked "measured" was measured on 2026-08-29
+ * against Tailscale 1.102.3 (standalone/macsys, `/usr/local/bin/tailscale`) on
+ * macOS; the raw session is in `dev-reports/issue/1937/u2-tailscale-serve.md`.
+ * Where the two disagree, the measurement wins.
+ *
+ * ## The one thing this file exists to get right
+ *
+ * Serve configuration is persistent state owned by tailscaled. The user may
+ * already be publishing their own services through it, and **there is no undo
+ * and no backup**. So the whole design here is about the blast radius of
+ * teardown, and the measurement below is the reason it is not obvious:
+ *
+ * | invocation | measured effect on a node serving `/` and `/u2-existing-user` |
+ * |---|---|
+ * | `serve --https=<port> --set-path <path> off` | removes exactly that one handler |
+ * | the same command with the path passed positionally instead | **wiped both handlers; config back to `{}`** |
+ * | the same command with no path at all | **wiped both handlers; config back to `{}`** |
+ *
+ * The middle row matters most, because the untargeted form is *what Tailscale
+ * itself prints* after a successful `serve`: its success banner recommends
+ * re-running `serve` with only `--https=<port>` and the word "off", no path.
+ * Following that hint would delete the user's configuration along with ours,
+ * silently, with exit status 0. (The banner's exact wording is quoted in the
+ * dev report; it is paraphrased here so this file does not trip the guard that
+ * forbids the shape — which is itself a small positive control.)
+ *
+ * Hence {@link buildServeOffArgs} is the only place an `off` argv is built, it
+ * always carries `--set-path`, and it derives that path from the handler key it
+ * is undoing rather than from anything ambient.
+ *
+ * ## Why `off` at all, when `serve --help` never mentions it
+ *
+ * 1.102.3's help lists `status` / `reset` / `drain` / `clear` / `advertise` /
+ * `get-config` / `set-config` and no `off`. Two alternatives were measured and
+ * rejected before settling on the undocumented-but-live `off`:
+ *
+ * - `get-config` + `set-config` looked like a "snapshot and restore" route, but
+ *   measuring their help shows both are **service**-scoped (`--service`, or
+ *   `--all` meaning "all services"). They do not address node-level Serve
+ *   handlers at all, so they cannot express "remove this one handler".
+ * - `drain` / `clear` are likewise service-scoped, and both are *destructive*
+ *   at service granularity. They are now forbidden outright by
+ *   `tests/unit/config/remote-destructive-command-guard.test.ts`.
+ *
+ * That leaves `off`, which is undocumented in `--help` yet is the exact string
+ * the CLI recommends in its own success output, and which measured clean:
+ * exit 0, only the named handler removed, and the `TCP` entry for the port
+ * cleaned up automatically once the last handler on it is gone.
+ *
+ * ## What `start()` refuses to do
+ *
+ * Measured: running `serve` for a path that already has a handler **overwrites
+ * it, prints the new mapping, and exits 0**. Nothing warns, and the previous
+ * upstream is unrecoverable. `preexisting` cannot help after the fact — §6.3-2
+ * protects the user's entries from `stop()`, not from `start()`. So `start()`
+ * reads the snapshot first and refuses when its target key is already taken.
+ *
+ * Deliberately absent: `reset()` / `cleanupAll()` (§6.3-1), and any command
+ * that operates on "the current configuration" rather than on a handle.
+ *
+ * This module imports Node builtins and `./types` only. No `@/` alias, so it
+ * resolves under `tsconfig.cli.json` (which sets `paths: {}`).
+ */
+import { type SpawnSyncOptionsWithStringEncoding, type SpawnSyncReturns } from 'child_process';
+import { type PreexistingSnapshot, type RemoteProvider } from './types';
+/** The executable. Looked up on PATH by `spawnSync`, never through a shell. */
+export declare const TAILSCALE_BIN = "tailscale";
+/**
+ * Mirrors `PreflightChecker.checkDependency()`: one argument, passed in an
+ * array. Measured: `tailscale version` prints `1.102.3` as its first line,
+ * while `tailscale --version` prints the same number followed by four lines of
+ * commit hashes. Both work; the subcommand is the tidier one to parse.
+ */
+export declare const TAILSCALE_VERSION_ARG = "version";
+/**
+ * The only host this Provider ever names.
+ *
+ * A constant rather than a parameter, so "the upstream is always loopback" is a
+ * property of the code and not of every call site. §9.2 pins it from outside as
+ * well, by asserting the argv `start()` builds.
+ *
+ * Measured: passing a bare port (`tailscale serve --bg 19001`) also resolves to
+ * `http://127.0.0.1:19001`. The full URL is passed anyway, so the guarantee is
+ * visible in argv instead of relying on a Tailscale-side default.
+ */
+export declare const LOOPBACK_HOST = "127.0.0.1";
+/**
+ * The HTTPS port Serve publishes on.
+ *
+ * 443 is the port `tailscale serve <target>` uses by default and the one the
+ * tailnet's HTTPS certificate covers (measured: `status --json` reports
+ * `CertDomains: ["<node>.<tailnet>.ts.net"]`, so no extra enablement step is
+ * needed on this machine).
+ */
+export declare const SERVE_HTTPS_PORT = 443;
+/**
+ * The path CommandMate publishes on.
+ *
+ * Root, not a prefix: the Next.js app is served without a `basePath`, so a
+ * handler mounted at `/commandmate` would return an app whose own asset and API
+ * URLs all point back at `/`.
+ */
+export declare const SERVE_PATH = "/";
+/** Same 5s budget `PreflightChecker` gives every other dependency probe. */
+export declare const DETECT_TIMEOUT_MS = 5000;
+/**
+ * Budget for the Serve mutations.
+ *
+ * Longer than the probe: `serve --bg` talks to tailscaled and, the first time a
+ * tailnet uses HTTPS, can provision a certificate. Measured latency on an
+ * already-provisioned node was well under a second.
+ */
+export declare const SERVE_TIMEOUT_MS = 30000;
+/** `BackendState` from `tailscale status --json` when the node is usable. */
+export declare const BACKEND_STATE_RUNNING = "Running";
+/** The subset of `tailscale serve status --json` this module reads. */
+export interface ServeTcpEntry {
+    HTTPS?: boolean;
+    HTTP?: boolean;
+    TCPForward?: string;
+    TerminateTLS?: string;
+}
+/** One `host:port` block of the `Web` map. */
+export interface ServeWebEntry {
+    Handlers?: Record<string, {
+        Proxy?: string;
+    } | null>;
+}
+/**
+ * `tailscale serve status --json`, as measured.
+ *
+ * With nothing configured the command prints `{}` and exits 0 (the human form
+ * says `No serve config`). With two handlers on 443 it prints
+ * `{"TCP":{"443":{"HTTPS":true}},"Web":{"<node>.<tailnet>.ts.net:443":
+ * {"Handlers":{"/":{"Proxy":"http://127.0.0.1:19002"}, ...}}}}`.
+ */
+export interface ServeConfig {
+    TCP?: Record<string, ServeTcpEntry | null>;
+    Web?: Record<string, ServeWebEntry | null>;
+}
+/** The fields of `tailscale status --json` readiness is decided from. */
+export interface TailscaleStatus {
+    BackendState?: string;
+    MagicDNSSuffix?: string;
+    Self?: {
+        DNSName?: string;
+    } | null;
+    Version?: string;
+}
+/** The seam that lets this Provider be tested without a tailnet. */
+export interface TailscaleProviderDeps {
+    spawnSync: (command: string, args: readonly string[], options: SpawnSyncOptionsWithStringEncoding) => SpawnSyncReturns<string>;
+    /** HTTPS port to publish on. Overridable so tests can prove it reaches argv. */
+    servePort: number;
+    /** Path to publish on. Same reason. */
+    servePath: string;
+    detectTimeoutMs: number;
+    serveTimeoutMs: number;
+}
+export declare const defaultTailscaleDeps: TailscaleProviderDeps;
+/**
+ * Drops the trailing dot from a MagicDNS name.
+ *
+ * Measured: `Self.DNSName` is `maenomac-studio.taile4f402.ts.net.` — fully
+ * qualified, with the root dot — while the key Serve uses in its own `Web` map
+ * is `maenomac-studio.taile4f402.ts.net:443`, without it. The two must agree
+ * or every snapshot key would miss.
+ */
+export declare function normalizeDnsName(name: string): string;
+/**
+ * The key one Serve handler is known by, in the keyspace `PreexistingSnapshot`
+ * and `RemoteHandle.owned.revert` share (§6.3-2).
+ *
+ * `<host>:<port><path>` — byte-for-byte the `Web` map key with the handler path
+ * appended, so a snapshot key and an owned key are comparable by construction
+ * rather than by convention.
+ */
+export declare function serveHandlerKey(host: string, port: number, path: string): string;
+/** The parts of a handler key an undo command needs. */
+export interface ParsedServeHandlerKey {
+    host: string;
+    port: number;
+    path: string;
+}
+/**
+ * Inverse of {@link serveHandlerKey}.
+ *
+ * Returns null rather than guessing. A key that cannot be parsed is a key whose
+ * undo command cannot be built safely, and the caller reports that instead of
+ * running a less specific command — which, per the measurement in the file
+ * header, is how a whole-port wipe happens.
+ */
+export declare function parseServeHandlerKey(key: string): ParsedServeHandlerKey | null;
+/**
+ * Parses `tailscale serve status --json`.
+ *
+ * Empty output is an empty configuration, not a failure: measured, the command
+ * prints `{}` when nothing is served, and a Provider that treated "no config"
+ * as "could not read config" would refuse to start on a clean machine.
+ */
+export declare function parseServeConfig(text: string): ServeConfig | null;
+/**
+ * Every handler currently configured, as keys, sorted.
+ *
+ * This is the list §6.3-2 protects. Anything in here existed before CommandMate
+ * ran and must survive `stop()`.
+ */
+export declare function serveHandlerKeys(config: ServeConfig): string[];
+/** Wraps a parsed config as the snapshot shape the shared skip rule reads. */
+export declare function snapshotServeConfig(config: ServeConfig): PreexistingSnapshot;
+/**
+ * The argv that publishes `http://127.0.0.1:<upstreamPort>`.
+ *
+ * `LOOPBACK_HOST` is a constant here and `upstreamPort` is validated before it
+ * arrives, so the only caller-supplied value that reaches the command line is a
+ * port number. `--yes` keeps tailscaled from ever asking a question on a
+ * non-interactive run.
+ */
+export declare function buildServeArgs(opts: {
+    servePort: number;
+    servePath: string;
+    upstreamPort: number;
+}): string[];
+/**
+ * The argv that removes exactly one handler.
+ *
+ * **The `--set-path` is load-bearing.** Measured on 1.102.3, dropping it — or
+ * passing the path positionally, the way older Tailscale documentation shows —
+ * removes every handler on the port and exits 0. See the table in the file
+ * header. This is the only function in the codebase that builds an `off` argv,
+ * and it cannot build one without a path.
+ */
+export declare function buildServeOffArgs(parsed: ParsedServeHandlerKey): string[];
+/** The public URL a handler on `<host>:<port><path>` answers on. */
+export declare function buildServeUrl(host: string, port: number): string;
+/** What `tailscale status --json` says about this node being able to serve. */
+export interface ServeReadiness {
+    ready: boolean;
+    /** The MagicDNS name, without its trailing dot, when there is one. */
+    dnsName: string | null;
+    reason?: string;
+}
+/**
+ * Decides `ready` from `tailscale status --json`.
+ *
+ * Two signals, both measured present on a working node: `BackendState` is
+ * `Running`, and `Self.DNSName` carries the MagicDNS name Serve publishes on.
+ * They are checked separately because they fail separately — a logged-out node
+ * reports a non-`Running` state, while a tailnet with MagicDNS disabled is
+ * `Running` with no name to serve under.
+ */
+export declare function readServeReadiness(text: string): ServeReadiness;
+/**
+ * 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 createTailscaleProvider(overrides?: Partial<TailscaleProviderDeps>): RemoteProvider;
+/** The shipped Provider, wired to the real `tailscale`. */
+export declare const tailscaleProvider: RemoteProvider;
+//# sourceMappingURL=tailscale.d.ts.map

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

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