commandmate 0.27.1 → 0.29.0

package/dist/lib/remote/tailscale.js

@@ -0,0 +1,546 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.tailscaleProvider = exports.defaultTailscaleDeps = exports.BACKEND_STATE_RUNNING = exports.SERVE_TIMEOUT_MS = exports.DETECT_TIMEOUT_MS = exports.SERVE_PATH = exports.SERVE_HTTPS_PORT = exports.LOOPBACK_HOST = exports.TAILSCALE_VERSION_ARG = exports.TAILSCALE_BIN = void 0;
+exports.normalizeDnsName = normalizeDnsName;
+exports.serveHandlerKey = serveHandlerKey;
+exports.parseServeHandlerKey = parseServeHandlerKey;
+exports.parseServeConfig = parseServeConfig;
+exports.serveHandlerKeys = serveHandlerKeys;
+exports.snapshotServeConfig = snapshotServeConfig;
+exports.buildServeArgs = buildServeArgs;
+exports.buildServeOffArgs = buildServeOffArgs;
+exports.buildServeUrl = buildServeUrl;
+exports.readServeReadiness = readServeReadiness;
+exports.createTailscaleProvider = createTailscaleProvider;
+/**
+ * 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: {}`).
+ */
+const child_process_1 = require("child_process");
+const types_1 = require("./types");
+/** The executable. Looked up on PATH by `spawnSync`, never through a shell. */
+exports.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.
+ */
+exports.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.
+ */
+exports.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).
+ */
+exports.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 `/`.
+ */
+exports.SERVE_PATH = '/';
+/** Same 5s budget `PreflightChecker` gives every other dependency probe. */
+exports.DETECT_TIMEOUT_MS = 5_000;
+/**
+ * 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.
+ */
+exports.SERVE_TIMEOUT_MS = 30_000;
+/** `BackendState` from `tailscale status --json` when the node is usable. */
+exports.BACKEND_STATE_RUNNING = 'Running';
+exports.defaultTailscaleDeps = {
+    spawnSync: child_process_1.spawnSync,
+    servePort: exports.SERVE_HTTPS_PORT,
+    servePath: exports.SERVE_PATH,
+    detectTimeoutMs: exports.DETECT_TIMEOUT_MS,
+    serveTimeoutMs: exports.SERVE_TIMEOUT_MS,
+};
+/**
+ * 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.
+ */
+function normalizeDnsName(name) {
+    return name.trim().replace(/\.+$/, '');
+}
+/**
+ * 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.
+ */
+function serveHandlerKey(host, port, path) {
+    return `${normalizeDnsName(host)}:${String(port)}${path}`;
+}
+/**
+ * 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.
+ */
+function parseServeHandlerKey(key) {
+    const slash = key.indexOf('/');
+    if (slash <= 0)
+        return null;
+    const hostPort = key.slice(0, slash);
+    const path = key.slice(slash);
+    const colon = hostPort.lastIndexOf(':');
+    if (colon <= 0 || colon === hostPort.length - 1)
+        return null;
+    const host = hostPort.slice(0, colon);
+    const port = Number(hostPort.slice(colon + 1));
+    if (!Number.isInteger(port) || port < 1 || port > 65535)
+        return null;
+    if (host.length === 0)
+        return null;
+    return { host, port, path };
+}
+/**
+ * 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.
+ */
+function parseServeConfig(text) {
+    const trimmed = text.trim();
+    if (trimmed.length === 0)
+        return {};
+    let parsed;
+    try {
+        parsed = JSON.parse(trimmed);
+    }
+    catch {
+        return null;
+    }
+    if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed))
+        return null;
+    return parsed;
+}
+/**
+ * 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()`.
+ */
+function serveHandlerKeys(config) {
+    const keys = [];
+    for (const [hostPort, entry] of Object.entries(config.Web ?? {})) {
+        const handlers = entry?.Handlers;
+        if (typeof handlers !== 'object' || handlers === null)
+            continue;
+        for (const path of Object.keys(handlers)) {
+            keys.push(`${hostPort}${path}`);
+        }
+    }
+    return keys.sort();
+}
+/** Wraps a parsed config as the snapshot shape the shared skip rule reads. */
+function snapshotServeConfig(config) {
+    return { keys: serveHandlerKeys(config), raw: config };
+}
+/**
+ * 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.
+ */
+function buildServeArgs(opts) {
+    return [
+        'serve',
+        '--bg',
+        '--yes',
+        `--https=${String(opts.servePort)}`,
+        '--set-path',
+        opts.servePath,
+        `http://${exports.LOOPBACK_HOST}:${String(opts.upstreamPort)}`,
+    ];
+}
+/**
+ * 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.
+ */
+function buildServeOffArgs(parsed) {
+    return [
+        'serve',
+        `--https=${String(parsed.port)}`,
+        '--set-path',
+        parsed.path,
+        '--yes',
+        'off',
+    ];
+}
+/** The public URL a handler on `<host>:<port><path>` answers on. */
+function buildServeUrl(host, port) {
+    const authority = port === 443 ? normalizeDnsName(host) : `${normalizeDnsName(host)}:${String(port)}`;
+    return `https://${authority}`;
+}
+/** Rejects anything that could not be a TCP port before it reaches argv. */
+function assertUpstreamPort(port) {
+    if (!Number.isInteger(port) || port < 1 || port > 65535) {
+        throw new Error(`tailscale-serve: upstream port must be 1-65535, got ${String(port)}`);
+    }
+}
+function messageOf(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+/** Trims a command's output to something safe to put in a user-facing reason. */
+function outputTail(result) {
+    const text = `${result.stderr ?? ''}\n${result.stdout ?? ''}`;
+    const lines = text
+        .split('\n')
+        .map((line) => line.trim())
+        .filter((line) => line.length > 0)
+        .slice(-3);
+    if (lines.length === 0)
+        return '';
+    return `: ${lines.join(' | ').slice(0, 300)}`;
+}
+function runTailscale(deps, args, timeoutMs) {
+    let result;
+    try {
+        // Array args, no `shell`. MF-SEC-1, and the same call shape as
+        // `PreflightChecker.checkDependency()`.
+        result = deps.spawnSync(exports.TAILSCALE_BIN, args, { encoding: 'utf-8', timeout: timeoutMs });
+    }
+    catch (error) {
+        return { ok: false, stdout: '', reason: `tailscale ${args[0]} failed: ${messageOf(error)}` };
+    }
+    if (result.error) {
+        const code = result.error.code;
+        const reason = code === 'ENOENT'
+            ? 'tailscale is not installed'
+            : `tailscale ${args[0]} failed: ${messageOf(result.error)}`;
+        return { ok: false, stdout: result.stdout ?? '', reason };
+    }
+    if (result.status !== 0) {
+        return {
+            ok: false,
+            stdout: result.stdout ?? '',
+            reason: `tailscale ${args[0]} exited with ${String(result.status)}${outputTail(result)}`,
+        };
+    }
+    return { ok: true, stdout: result.stdout ?? '', reason: '' };
+}
+/**
+ * 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.
+ */
+function readServeReadiness(text) {
+    let status;
+    try {
+        const parsed = JSON.parse(text);
+        if (typeof parsed !== 'object' || parsed === null) {
+            return { ready: false, dnsName: null, reason: 'tailscale status --json was not an object' };
+        }
+        status = parsed;
+    }
+    catch (error) {
+        return {
+            ready: false,
+            dnsName: null,
+            reason: `could not parse tailscale status --json: ${messageOf(error)}`,
+        };
+    }
+    const backendState = typeof status.BackendState === 'string' ? status.BackendState : 'unknown';
+    if (backendState !== exports.BACKEND_STATE_RUNNING) {
+        return {
+            ready: false,
+            dnsName: null,
+            reason: `tailscale is not connected (BackendState=${backendState}); log in with the Tailscale app or CLI first`,
+        };
+    }
+    const rawName = typeof status.Self?.DNSName === 'string' ? status.Self.DNSName : '';
+    const dnsName = normalizeDnsName(rawName);
+    if (dnsName.length === 0) {
+        const suffix = typeof status.MagicDNSSuffix === 'string' && status.MagicDNSSuffix.length > 0
+            ? ` (MagicDNS suffix: ${status.MagicDNSSuffix})`
+            : '';
+        return {
+            ready: false,
+            dnsName: null,
+            reason: `this node has no MagicDNS name, so Serve has no hostname to publish on${suffix}`,
+        };
+    }
+    return { ready: true, dnsName };
+}
+/**
+ * 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.
+ */
+function createTailscaleProvider(overrides = {}) {
+    const deps = { ...exports.defaultTailscaleDeps, ...overrides };
+    /** Reads the current Serve configuration. Side-effect free. */
+    function readServeConfig() {
+        const run = runTailscale(deps, ['serve', 'status', '--json'], deps.detectTimeoutMs);
+        if (!run.ok)
+            return { config: null, reason: run.reason };
+        const config = parseServeConfig(run.stdout);
+        if (config === null) {
+            return { config: null, reason: 'could not parse tailscale serve status --json' };
+        }
+        return { config, reason: '' };
+    }
+    return {
+        id: 'tailscale-serve',
+        async detect() {
+            const version = runTailscale(deps, [exports.TAILSCALE_VERSION_ARG], deps.detectTimeoutMs);
+            if (!version.ok) {
+                return { available: false, ready: false, reason: version.reason };
+            }
+            // `available` is settled here: the executable exists and answered. Every
+            // failure past this point leaves `available: true` and only moves
+            // `ready`, which is the split §6.1 asks for and the split the
+            // orchestrator's selection rule is written against.
+            const parsedVersion = /(\d+\.\d+\.\d+)/.exec(version.stdout.trim())?.[1];
+            const base = parsedVersion === undefined ? {} : { version: parsedVersion };
+            const status = runTailscale(deps, ['status', '--json'], deps.detectTimeoutMs);
+            if (!status.ok) {
+                return { available: true, ...base, ready: false, reason: status.reason };
+            }
+            const readiness = readServeReadiness(status.stdout);
+            if (!readiness.ready) {
+                return { available: true, ...base, ready: false, reason: readiness.reason };
+            }
+            return { available: true, ...base, ready: true };
+        },
+        async start({ port, signal }) {
+            assertUpstreamPort(port);
+            if (signal.aborted) {
+                throw new Error('tailscale-serve: aborted before anything was served');
+            }
+            const status = runTailscale(deps, ['status', '--json'], deps.detectTimeoutMs);
+            if (!status.ok)
+                throw new Error(`tailscale-serve: ${status.reason}`);
+            const readiness = readServeReadiness(status.stdout);
+            if (!readiness.ready || readiness.dnsName === null) {
+                throw new Error(`tailscale-serve: ${readiness.reason ?? 'not ready'}`);
+            }
+            const host = readiness.dnsName;
+            // §6.3-2: the snapshot is taken before anything is created, and `start()`
+            // may not return without it. Failing to read it is fatal rather than
+            // degraded — a handle with an empty `preexisting` would tell `stop()`
+            // that the user has no configuration to protect.
+            const snapshot = readServeConfig();
+            if (snapshot.config === null) {
+                throw new Error(`tailscale-serve: refusing to serve without a pre-existing-config snapshot (${snapshot.reason})`);
+            }
+            const preexisting = snapshotServeConfig(snapshot.config);
+            const key = serveHandlerKey(host, deps.servePort, deps.servePath);
+            if (preexisting.keys.includes(key)) {
+                // Measured: running `serve` over an occupied path overwrites it, prints
+                // the new mapping and exits 0. The old upstream is then unrecoverable,
+                // and §6.3-2 cannot help — it governs `stop()`, not `start()`. So the
+                // only safe answer is to not start.
+                throw new Error(`tailscale-serve: ${key} is already served (by ${describeExistingProxy(snapshot.config, key)}). ` +
+                    'CommandMate will not overwrite a handler it did not create; remove it yourself, or free the path first.');
+            }
+            const tcpConflict = findTcpConflict(snapshot.config, deps.servePort);
+            if (tcpConflict !== null) {
+                throw new Error(`tailscale-serve: port ${String(deps.servePort)} is already used as ${tcpConflict}, not for HTTPS. ` +
+                    'CommandMate will not repurpose it.');
+            }
+            if (signal.aborted) {
+                throw new Error('tailscale-serve: aborted before anything was served');
+            }
+            const args = buildServeArgs({
+                servePort: deps.servePort,
+                servePath: deps.servePath,
+                upstreamPort: port,
+            });
+            const served = runTailscale(deps, args, deps.serveTimeoutMs);
+            if (!served.ok)
+                throw new Error(`tailscale-serve: ${served.reason}`);
+            const upstream = `http://${exports.LOOPBACK_HOST}:${String(port)}`;
+            // Verify against tailscaled rather than trusting exit 0. If the handler
+            // is not there, nothing was created, so there is nothing to undo and the
+            // failure can be reported without touching any configuration.
+            const after = readServeConfig();
+            if (after.config === null || !serveHandlerKeys(after.config).includes(key)) {
+                throw new Error(`tailscale-serve: ${key} was not created (checked with serve status --json${after.config === null ? `; ${after.reason}` : ''})`);
+            }
+            return {
+                provider: 'tailscale-serve',
+                url: buildServeUrl(host, deps.servePort),
+                // `pid: null` because Serve is configuration held by tailscaled, not a
+                // child process: `--bg` returns immediately and leaves nothing of ours
+                // running. The revert entry is the upstream we installed, kept so a
+                // human reading the state file can see what the key meant.
+                owned: { pid: null, revert: { [key]: upstream } },
+                preexisting,
+            };
+        },
+        async stop(handle) {
+            // The shared §6.3-2 rule, used by both Providers so they cannot drift.
+            const plan = (0, types_1.planStop)(handle);
+            const warnings = [];
+            for (const key of Object.keys(plan.revert)) {
+                const parsed = parseServeHandlerKey(key);
+                if (parsed === null) {
+                    // Refusing to act beats acting imprecisely: the less specific undo
+                    // command is exactly the one that wipes the whole port.
+                    warnings.push(`tailscale-serve: cannot parse owned key "${key}"; left in place rather than guessing a removal command`);
+                    continue;
+                }
+                const off = runTailscale(deps, buildServeOffArgs(parsed), deps.serveTimeoutMs);
+                if (!off.ok) {
+                    warnings.push(`tailscale-serve: could not remove ${key}: ${off.reason}`);
+                }
+            }
+            if (handle.owned.pid !== null) {
+                // This Provider never records a pid, so a handle that has one was not
+                // produced here. Signalling an unknown process is not a teardown step
+                // this Provider is entitled to take.
+                warnings.push(`tailscale-serve: handle claims pid ${String(handle.owned.pid)}, which this provider never creates; left alone`);
+            }
+            return { reverted: warnings.length === 0, skipped: plan.skipped, warnings };
+        },
+    };
+}
+/** Names the upstream currently behind a key, for a refusal message. */
+function describeExistingProxy(config, key) {
+    for (const [hostPort, entry] of Object.entries(config.Web ?? {})) {
+        const handlers = entry?.Handlers;
+        if (typeof handlers !== 'object' || handlers === null)
+            continue;
+        for (const [path, handler] of Object.entries(handlers)) {
+            if (`${hostPort}${path}` !== key)
+                continue;
+            const proxy = handler?.Proxy;
+            return typeof proxy === 'string' && proxy.length > 0 ? proxy : 'an existing handler';
+        }
+    }
+    return 'an existing handler';
+}
+/**
+ * Reports a non-HTTPS use of the port CommandMate wants.
+ *
+ * A raw TCP forwarder or a TLS-terminated forwarder occupies the whole port;
+ * adding an HTTPS handler there would take it over. Measured: an HTTPS handler
+ * records `{"HTTPS": true}` under `TCP.<port>`, which is the compatible case
+ * and is what lets a second path be added alongside an existing one.
+ */
+function findTcpConflict(config, port) {
+    const entry = config.TCP?.[String(port)];
+    if (entry === null || entry === undefined)
+        return null;
+    if (entry.HTTPS === true)
+        return null;
+    if (typeof entry.TCPForward === 'string' && entry.TCPForward.length > 0) {
+        return `a TCP forwarder to ${entry.TCPForward}`;
+    }
+    if (typeof entry.TerminateTLS === 'string' && entry.TerminateTLS.length > 0) {
+        return `a TLS-terminated forwarder for ${entry.TerminateTLS}`;
+    }
+    if (entry.HTTP === true)
+        return 'a plain-HTTP listener';
+    return 'a non-HTTPS listener';
+}
+/** The shipped Provider, wired to the real `tailscale`. */
+exports.tailscaleProvider = createTailscaleProvider();

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

@@ -0,0 +1,127 @@
+/**
+ * Provider abstraction for `commandmate remote` (Issue #1937, R1).
+ *
+ * The shapes here are §6.1 of `docs/design/remote-qr-pairing-1937.md` verbatim.
+ * Two of them carry a structural guarantee rather than a convention, and both
+ * exist because a Provider can destroy configuration the user created and that
+ * CommandMate has no way to restore (§6.3):
+ *
+ * 1. `RemoteProvider` has no `reset()` / `cleanupAll()`. `stop()` takes a
+ *    `RemoteHandle` and nothing else, so "read the Provider's whole config and
+ *    tear it down" is not expressible in this type. A pinning test asserts the
+ *    member list stays exactly `id` / `detect` / `start` / `stop`.
+ * 2. `start()` must return `preexisting`. `stop()` reverts only what is in
+ *    `owned` and NOT in `preexisting`; anything in both is skipped and reported
+ *    in `StopOutcome.skipped` so a human can see what was left alone.
+ *
+ * Choosing between Providers is deliberately NOT here. "Tailscale first, and do
+ * not silently fall back to a public tunnel" is a rule about selection, not a
+ * property of either Provider, so it lives in the orchestrator that will own
+ * `src/cli/commands/remote.ts` (R9). See `provider-registry.ts`.
+ */
+/** Every Provider CommandMate knows how to drive. */
+export type RemoteProviderId = 'tailscale-serve' | 'cloudflare-quick';
+/**
+ * Result of a side-effect-free probe.
+ *
+ * `available` and `ready` are separate on purpose: Tailscale can be installed
+ * and still be unable to serve because the machine is not logged in. Keeping
+ * the two apart is what lets the orchestrator write the selection rule
+ * (Tailscale -> cloudflared -> explain) as a plain `ready` check.
+ */
+export interface ProviderDetection {
+    /** The executable exists and could be run. */
+    available: boolean;
+    /** Version string as reported by the executable, when it could be read. */
+    version?: string;
+    /** The Provider is in a state where `start()` could succeed right now. */
+    ready: boolean;
+    /** Why `available` or `ready` is false. Shown to the user; never a secret. */
+    reason?: string;
+}
+/**
+ * A snapshot of the Provider's own configuration taken immediately before
+ * `start()` ran.
+ *
+ * `RemoteHandle.preexisting` is typed `unknown` because the raw shape differs
+ * per Provider (§6.2: "how to take the snapshot is Provider-specific"). This
+ * interface is the one part the shared skip rule needs to read, so a Provider
+ * that has revertible state MUST snapshot into this shape. A Provider with no
+ * persistent state (Cloudflare Quick Tunnel) leaves `preexisting` as `null`.
+ */
+export interface PreexistingSnapshot {
+    /**
+     * Keys, in the same keyspace as `RemoteHandle.owned.revert`, that already
+     * existed before `start()`. `stop()` must not touch these.
+     */
+    keys: readonly string[];
+    /** The verbatim Provider-specific snapshot, kept for diagnostics. */
+    raw: unknown;
+}
+/** What CommandMate made the Provider create during one remote session. */
+export interface RemoteHandle {
+    provider: RemoteProviderId;
+    /** The public https:// URL the Provider is now serving. */
+    url: string;
+    /** Identifies only what CommandMate created. `stop()` touches nothing else. */
+    owned: {
+        /** Child process CommandMate spawned, or null when the Provider is a daemon. */
+        pid: number | null;
+        /** Provider-specific "how to undo this", keyed like `PreexistingSnapshot.keys`. */
+        revert: Record<string, string> | null;
+    };
+    /**
+     * Provider state as it was just before `start()`. Anything in here is
+     * off-limits to `stop()`. Use `PreexistingSnapshot` when there is state to
+     * protect; `null` when the Provider persists nothing.
+     */
+    preexisting: unknown;
+}
+/** What `stop()` actually did, including what it deliberately did not do. */
+export interface StopOutcome {
+    /** True only if every owned entry that needed reverting was reverted. */
+    reverted: boolean;
+    /**
+     * Owned keys left alone because they were also in `preexisting`. Surfacing
+     * them is the point: a silent skip is indistinguishable from a silent delete.
+     */
+    skipped: string[];
+    /** Non-fatal problems worth showing the user. */
+    warnings: string[];
+}
+/**
+ * One way of exposing `http://127.0.0.1:<port>` to a phone.
+ *
+ * Deliberately absent: any method that operates on "the Provider's current
+ * configuration" instead of on a handle. See the file header.
+ */
+export interface RemoteProvider {
+    readonly id: RemoteProviderId;
+    /** Probe availability and readiness. Must have no side effects. */
+    detect(): Promise<ProviderDetection>;
+    /** Expose 127.0.0.1:port. Must fill in `preexisting` before returning. */
+    start(opts: {
+        port: number;
+        signal: AbortSignal;
+    }): Promise<RemoteHandle>;
+    /** Undo only `handle.owned`. Never touches anything in `handle.preexisting`. */
+    stop(handle: RemoteHandle): Promise<StopOutcome>;
+}
+/** Narrows `RemoteHandle.preexisting` to the shape the shared skip rule reads. */
+export declare function isPreexistingSnapshot(value: unknown): value is PreexistingSnapshot;
+/** The revert entries `stop()` may act on, and the ones it must leave alone. */
+export interface StopPlan {
+    /** Owned and not preexisting: safe to undo. */
+    revert: Record<string, string>;
+    /** Owned and also preexisting: must be left in place, and reported. */
+    skipped: string[];
+}
+/**
+ * Splits a handle's owned revert entries into "safe to undo" and "leave alone".
+ *
+ * This is the single implementation of §6.3-2. Every Provider's `stop()` routes
+ * through it so the rule cannot drift between Providers, and so the rule can be
+ * tested once instead of once per Provider.
+ */
+export declare function planStop(handle: RemoteHandle): StopPlan;
+//# sourceMappingURL=types.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/lib/remote/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,qDAAqD;AACrD,MAAM,MAAM,gBAAgB,GAAG,iBAAiB,GAAG,kBAAkB,CAAC;AAEtE;;;;;;;GAOG;AACH,MAAM,WAAW,iBAAiB;IAChC,8CAA8C;IAC9C,SAAS,EAAE,OAAO,CAAC;IACnB,2EAA2E;IAC3E,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,0EAA0E;IAC1E,KAAK,EAAE,OAAO,CAAC;IACf,8EAA8E;IAC9E,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED;;;;;;;;;GASG;AACH,MAAM,WAAW,mBAAmB;IAClC;;;OAGG;IACH,IAAI,EAAE,SAAS,MAAM,EAAE,CAAC;IACxB,qEAAqE;IACrE,GAAG,EAAE,OAAO,CAAC;CACd;AAED,2EAA2E;AAC3E,MAAM,WAAW,YAAY;IAC3B,QAAQ,EAAE,gBAAgB,CAAC;IAC3B,2DAA2D;IAC3D,GAAG,EAAE,MAAM,CAAC;IACZ,+EAA+E;IAC/E,KAAK,EAAE;QACL,gFAAgF;QAChF,GAAG,EAAE,MAAM,GAAG,IAAI,CAAC;QACnB,mFAAmF;QACnF,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,IAAI,CAAC;KACvC,CAAC;IACF;;;;OAIG;IACH,WAAW,EAAE,OAAO,CAAC;CACtB;AAED,6EAA6E;AAC7E,MAAM,WAAW,WAAW;IAC1B,yEAAyE;IACzE,QAAQ,EAAE,OAAO,CAAC;IAClB;;;OAGG;IACH,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,iDAAiD;IACjD,QAAQ,EAAE,MAAM,EAAE,CAAC;CACpB;AAED;;;;;GAKG;AACH,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,EAAE,EAAE,gBAAgB,CAAC;IAC9B,mEAAmE;IACnE,MAAM,IAAI,OAAO,CAAC,iBAAiB,CAAC,CAAC;IACrC,0EAA0E;IAC1E,KAAK,CAAC,IAAI,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,WAAW,CAAA;KAAE,GAAG,OAAO,CAAC,YAAY,CAAC,CAAC;IAC1E,gFAAgF;IAChF,IAAI,CAAC,MAAM,EAAE,YAAY,GAAG,OAAO,CAAC,WAAW,CAAC,CAAC;CAClD;AAED,kFAAkF;AAClF,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,mBAAmB,CAIlF;AAED,gFAAgF;AAChF,MAAM,WAAW,QAAQ;IACvB,+CAA+C;IAC/C,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC/B,uEAAuE;IACvE,OAAO,EAAE,MAAM,EAAE,CAAC;CACnB;AAED;;;;;;GAMG;AACH,wBAAgB,QAAQ,CAAC,MAAM,EAAE,YAAY,GAAG,QAAQ,CAgBvD"}