commandmate 0.28.0 → 0.29.0

package/dist/cli/commands/remote.d.ts

@@ -0,0 +1,248 @@
+/**
+ * remote Command - expose this server to a phone and pair it with a QR code
+ * Issue #1937 (R9). Design: `docs/design/remote-qr-pairing-1937.md` §5, §6.2.
+ *
+ *   commandmate remote            # up (default): start, publish, show the QR
+ *   commandmate remote status     # Provider / URL / expiry / pairing state
+ *   commandmate remote stop       # close the door, keeping the server running
+ *
+ * ## What lives here rather than in a Provider (§6.2)
+ *
+ * Two things, and both for the same reason — they are decisions about an
+ * IRREVERSIBLE act (putting this machine on a network it was not on), and a
+ * decision buried in a probe helper is a decision nobody reviews:
+ *
+ *  1. **Which Provider runs.** `detectRemoteProviders()` returns every Provider
+ *     in preference order and picks none. "Tailscale first, and never fall
+ *     through to a public tunnel on its own" is a rule about selection, so it
+ *     is written here, once, as {@link selectProvider}.
+ *  2. **Whether a public tunnel may be created at all.** A prompt inside a
+ *     Provider would have to re-derive interactive-vs-not per Provider, and its
+ *     answer would be invisible to the caller that has to honour `--yes`.
+ *
+ * ## What this command deliberately does not have
+ *
+ *  - **`--token`.** `remote` is the side that MINTS a token; one supplied from
+ *    outside has no hash on the server to match (§5.1).
+ *  - **`--auto-yes` in any form.** Auto-Yes state is an in-memory map that is
+ *    empty at server start, so a freshly started server has it off for every
+ *    worktree. Not offering a flag is what keeps it that way (§5.5); a test
+ *    pins that the launch env carries no Auto-Yes key either.
+ *  - **Anything that stops the server on expiry.** `--expires` closes the
+ *    outside door only. A `commandmate stop` on a timer would take the user's
+ *    local session down along with the remote one (§5.3).
+ */
+import { Command } from 'commander';
+import { ExitCode } from '../types';
+import type { RemoteOptions } from '../types';
+import { type ProviderCandidate, type RemoteProviderId } from '../../lib/remote';
+/** Default remote-session TTL. Follows `parseDuration`'s 1h-30d range (§5.1). */
+export declare const DEFAULT_REMOTE_EXPIRES = "8h";
+/** Default pairing-code TTL (§5.1). See {@link parsePairingDuration}. */
+export declare const DEFAULT_PAIRING_EXPIRES = "10m";
+/** Shortest pairing window: below a minute the QR cannot be scanned in time. */
+export declare const MIN_PAIRING_TTL_MS: number;
+/**
+ * Longest pairing window.
+ *
+ * The handoff file holds the plaintext session token until the code is used
+ * (§7.2), so this bound is the maximum time that plaintext sits on disk. It is
+ * deliberately far below `--expires`' 30-day ceiling.
+ */
+export declare const MAX_PAIRING_TTL_MS: number;
+/** What the user may type after `--provider`, and what it resolves to. */
+export declare const REMOTE_PROVIDER_ALIASES: Readonly<Record<string, RemoteProviderId>>;
+/**
+ * Providers that publish to the open internet rather than to a private network.
+ *
+ * Membership here is what triggers the explicit approval below, so this list —
+ * not a Provider's own opinion of itself — is the thing to check when a
+ * Provider is added.
+ */
+export declare const PUBLIC_TUNNEL_PROVIDERS: readonly RemoteProviderId[];
+/**
+ * Every environment variable `remote` adds to the server it starts, and no
+ * other (§9.1).
+ *
+ * All three are already-existing keys or a path:
+ *
+ *  - `CM_AUTH_TOKEN_HASH` / `CM_AUTH_EXPIRE` — what `start --auth` sets.
+ *  - `CM_REMOTE_PAIRING_FILE` — a PATH, not a secret. The plaintext token and
+ *    the pairing hash live in the 0600 file it names, because a pane spawned by
+ *    `src/lib/tmux/**` inherits the server's environment wholesale, so anything
+ *    put here would be readable by the very agents CommandMate is driving
+ *    (§7.2).
+ *
+ * `tests/unit/cli/commands/remote-launch-env-1937.test.ts` holds the measured
+ * set to this declaration in BOTH directions, the way
+ * `agent-launch-plan-secrets-1933.test.ts` does for `prepareLaunch`. Adding a
+ * key without adding it here goes red; so does removing one.
+ */
+export declare const REMOTE_LAUNCH_ENV_KEYS: readonly ["CM_AUTH_TOKEN_HASH", "CM_AUTH_EXPIRE", "CM_REMOTE_PAIRING_FILE"];
+/** Inputs of {@link buildRemoteLaunchEnv}. */
+export interface RemoteLaunchEnvInput {
+    /** SHA-256 of the session token. The token itself never reaches the env. */
+    authTokenHash: string;
+    /** The `--expires` duration string, verbatim, for `computeExpireAt()`. */
+    authExpire: string;
+    /** Absolute path of the 0600 pairing handoff file. */
+    pairingFilePath: string;
+}
+/** Pairing state as reported by `remote status` (§5.4). */
+export type PairingState = 'unused' | 'consumed' | 'expired';
+/**
+ * Build the exact environment `remote` contributes to the server it starts.
+ *
+ * Returned as a plain map rather than written straight into `process.env` so
+ * the contribution is a value a test can compare against
+ * {@link REMOTE_LAUNCH_ENV_KEYS} — "what did remote add" is otherwise only
+ * observable by diffing a global.
+ *
+ * @param input - Hash, expiry and handoff path
+ * @returns The three variables, and nothing else
+ */
+export declare function buildRemoteLaunchEnv(input: RemoteLaunchEnvInput): Record<string, string>;
+/**
+ * Copy the launch env into `process.env`, where `daemon.ts` reads it.
+ *
+ * `runStart` -> `DaemonManager.start()` builds the child environment from
+ * `process.env` plus `.env`, exactly as `start --auth` does, so this is the
+ * hand-off point. Note what is NOT here: `CM_BIND` is neither read nor written
+ * by `remote`, so a user already running `CM_BIND=0.0.0.0` keeps that setting
+ * and a user on the 127.0.0.1 default keeps that one (§9.1).
+ *
+ * @param env - Output of {@link buildRemoteLaunchEnv}
+ * @returns A function restoring the previous values, used on the rollback paths
+ */
+export declare function applyRemoteLaunchEnv(env: Record<string, string>): () => void;
+/**
+ * Parse a `--pairing-expires` duration.
+ *
+ * `parseDuration()` from `auth-config` is NOT reused here even though `remote`
+ * uses it for `--expires`: its floor is 1 hour, and the pairing default is ten
+ * minutes. Raising that floor would loosen `CM_AUTH_EXPIRE` for every caller of
+ * a shared function, so the short-lived case gets its own bounds instead.
+ *
+ * @param value - Duration string (`Nm` or `Nh`)
+ * @returns Duration in milliseconds
+ * @throws Error when the format is wrong or the value is out of range
+ */
+export declare function parsePairingDuration(value: string): number;
+/** Outcome of applying the selection rule to a probe result. */
+export interface ProviderSelection {
+    /** The Provider to use, when there is one. */
+    candidate?: ProviderCandidate;
+    /** Why there is none. Mutually exclusive with `candidate`. */
+    error?: {
+        exitCode: ExitCode;
+        message: string;
+        /** One line per Provider, so the user sees what was tried and why it failed. */
+        details: string[];
+    };
+}
+/**
+ * Apply the Provider selection rule (§6.2).
+ *
+ * The rule, in full:
+ *
+ *  - `--provider` names exactly one Provider. An unusable one is an error, not
+ *    a reason to try another: the user asked for that one.
+ *  - Without `--provider`, the first READY Provider in preference order wins.
+ *    Preference order puts Tailscale (private tailnet) ahead of the Cloudflare
+ *    Quick Tunnel (public internet).
+ *  - Being chosen is never enough to be started. A Provider in
+ *    {@link PUBLIC_TUNNEL_PROVIDERS} still has to clear the explicit approval
+ *    in {@link approvePublicTunnel}, which is what makes "Tailscale failed, so
+ *    it silently published me to the internet" impossible rather than merely
+ *    unlikely.
+ *  - No Provider ready is `DEPENDENCY_ERROR`, never a fallback.
+ *
+ * Pure: it neither probes nor prompts, so the rule can be tested without a
+ * Provider being installed.
+ *
+ * @param candidates - `detectRemoteProviders()` output, in preference order
+ * @param requested - The raw `--provider` value, if any
+ * @returns The chosen candidate, or the error to exit with
+ */
+export declare function selectProvider(candidates: readonly ProviderCandidate[], requested?: string): ProviderSelection;
+/**
+ * Run the `up` flow: start, publish, pair (§5.3, steps 1-9).
+ *
+ * @param options - Parsed command options
+ * @returns The exit code the caller should terminate with
+ */
+export declare function runRemoteUp(options: RemoteOptions): Promise<ExitCode>;
+/**
+ * @param url - Public URL the Provider published
+ * @param code - Plaintext pairing code
+ * @returns The `/login#code=` URL the QR encodes
+ */
+export declare function buildPairingUrl(url: string, code: string): string;
+/**
+ * Decide what to report on the `Pairing:` line (§5.4).
+ *
+ * The absence of the handoff file IS the consumed flag (§7.2) - the route
+ * unlinks it between verifying the code and setting the cookie - so absence is
+ * reported as `consumed` rather than being guessed at from the clock.
+ *
+ * @param handoffPresent - Whether the handoff file still exists
+ * @param pairingExpiresAt - Epoch ms the code dies at
+ * @param now - Epoch ms, injectable for tests
+ * @returns The state to display
+ */
+export declare function derivePairingState(handoffPresent: boolean, pairingExpiresAt: number, now?: number): PairingState;
+/**
+ * Format a millisecond delta the way `remote status` shows expiry.
+ *
+ * @param ms - Milliseconds remaining; zero or less reads as expired
+ * @returns e.g. `in 6h 12m`, or `expired`
+ */
+export declare function formatRemaining(ms: number): string;
+/**
+ * Run the `status` flow (§5.4).
+ *
+ * This is also where `--expires` is enforced in Phase 1: `up` starts the server
+ * as a daemon and returns, so no `remote` process survives to hold a timer.
+ * §5.3 allows either, and "the expiry is judged when `remote status` runs" is
+ * the half that works without a resident process. It closes the Provider only -
+ * the server keeps running, because the local user is still using it.
+ *
+ * @param options - Parsed command options
+ * @returns The exit code the caller should terminate with
+ */
+export declare function runRemoteStatus(options: RemoteOptions): Promise<ExitCode>;
+/**
+ * Run the `stop` flow (§6.3-4).
+ *
+ * With no readable state file this exits SUCCESS having done nothing. That is
+ * the point, not a shortcut: the alternative is inferring a Provider and tearing
+ * down whatever configuration it currently holds, and for Tailscale Serve that
+ * configuration can be the user's own, with no way to restore it. `stop.ts`
+ * treats a stale PID file with the same restraint.
+ *
+ * @param options - Parsed command options
+ * @returns The exit code the caller should terminate with
+ */
+export declare function runRemoteStop(options: RemoteOptions): Promise<ExitCode>;
+/**
+ * Dispatch one `remote` invocation and terminate.
+ *
+ * The exit-free `run*` functions above are what the tests drive and what a
+ * future caller (a `quickstart --remote`, say) would compose, exactly as
+ * `runStart` / `startCommand` are split (#1195).
+ *
+ * @param action - `up` (default), `status` or `stop`
+ * @param options - Parsed command options
+ */
+export declare function remoteCommand(action: string | undefined, options: RemoteOptions): Promise<void>;
+/**
+ * Create the remote command.
+ * [DR1-08] Factory pattern for addCommand() registration, as `createSyncCommand()`
+ * and `createInstancesCommand()` do. `instances`' shape is followed too - a
+ * default action with the verb as an optional positional - the only difference
+ * being that the default here is `up` rather than a listing.
+ *
+ * @returns The configured commander command
+ */
+export declare function createRemoteCommand(): Command;
+//# sourceMappingURL=remote.d.ts.map

package/dist/cli/commands/remote.d.ts.map

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