@mesh-tech/mesh-cli 0.20.1 → 0.20.3

package/dist/src/utils/stack-flag.d.ts

@@ -1,23 +1,10 @@
 export interface StackSelector {
-    /** Canonical Pulumi stack name. */
     stack?: string;
-    /** @deprecated SST-era alias for {@link StackSelector.stack}; still accepted. */
     stage?: string;
 }
-/**
- * Resolve the stack selector, preferring the canonical `--stack` over the
- * deprecated `--stage` alias. Pure: reports whether the deprecated alias supplied
- * the value so the caller can warn. `--stack` wins when both are present.
- */
 export declare function resolveStackSelector(opts: StackSelector): {
     stack: string | undefined;
     usedDeprecatedStage: boolean;
 };
-/** Test-only: reset the once-per-process deprecation-warning latch. */
 export declare function resetStackFlagWarning(): void;
-/**
- * Resolve `--stack`/`--stage` to the effective stack for use at a consumption
- * site, warning ONCE per process when the deprecated `--stage` alias supplied it.
- */
 export declare function resolveStackOption(opts: StackSelector): string | undefined;
-//# sourceMappingURL=stack-flag.d.ts.map

package/dist/src/utils/stack-flag.js

@@ -1,19 +1,4 @@
-/**
- * Stack-selection flag resolution (MESH-2154).
- *
- * `mesh` subcommands historically disagreed on the stack-selection flag:
- * `deploy`/`cluster` use `--stack` (Pulumi-native), while `dev`/`secrets` used
- * `--stage` (the SST-era term the platform has moved off). So `mesh kubectl
- * --stage dev` and `mesh dev --stack …` each errored on muscle memory. We
- * consolidate on `--stack` everywhere and keep `--stage` as a HIDDEN, deprecated
- * alias that still works but warns — removable after a transition window.
- */
 import { logWarn } from './log.js';
-/**
- * Resolve the stack selector, preferring the canonical `--stack` over the
- * deprecated `--stage` alias. Pure: reports whether the deprecated alias supplied
- * the value so the caller can warn. `--stack` wins when both are present.
- */
 export function resolveStackSelector(opts) {
     if (opts.stack != null)
         return { stack: opts.stack, usedDeprecatedStage: false };
@@ -22,14 +7,9 @@ export function resolveStackSelector(opts) {
     return { stack: undefined, usedDeprecatedStage: false };
 }
 let warnedOnce = false;
-/** Test-only: reset the once-per-process deprecation-warning latch. */
 export function resetStackFlagWarning() {
     warnedOnce = false;
 }
-/**
- * Resolve `--stack`/`--stage` to the effective stack for use at a consumption
- * site, warning ONCE per process when the deprecated `--stage` alias supplied it.
- */
 export function resolveStackOption(opts) {
     const { stack, usedDeprecatedStage } = resolveStackSelector(opts);
     if (usedDeprecatedStage && !warnedOnce) {
@@ -38,4 +18,3 @@ export function resolveStackOption(opts) {
     }
     return stack;
 }
-//# sourceMappingURL=stack-flag.js.map

package/dist/src/utils/tailscale-targets.d.ts

@@ -1,52 +1,15 @@
-/**
- * Resolve a tenant's VPC tunnel targets from the platform bastion's service
- * map — the same source `startSsmTunnels` reads — mapping bastion service keys
- * to the app's tunnel names, resolving each ELB/RDS hostname to its private IP,
- * and assigning collision-free localhost ports via the SSM port convention.
- * (MESH-2040 / Slice 1 of MESH-2014.)
- */
-/** Local-port block width per tenant — wider than the canonical port span so
- * two tenants' port blocks never overlap. */
 export declare const PORT_BLOCK = 3000;
-/**
- * Deterministic per-tenant index for local-port offsetting. Reads a machine-global
- * registry (`~/.config/mesh/tailscale/port-registry.json`), seeded `{ mesh: 0 }` so
- * the hub's canonical ports are grandfathered regardless of registration order.
- * Assigns the next index to an unseen tenant and persists it. `registryPath` is
- * injectable for tests.
- */
 export declare function tenantPortIndex(tenant: string, registryPath?: string): number;
 export interface TunnelTarget {
-    /** App-facing tunnel name (e.g. "temporal"). */
     name: string;
-    /** Local port the forwarder listens on (SSM convention: base + remotePort). */
     localPort: number;
-    /** VPC hostname (internal ELB / RDS endpoint). */
     targetHost: string;
-    /** Resolved private IP of `targetHost`. */
     targetIp: string;
-    /** Port on the VPC service. */
     remotePort: number;
 }
-/**
- * Bastion service key → app tunnel name. Mirrors `tunnelToBastionKey` in dev.ts
- * (inverted): the bastion exposes `temporal-frontend`; the app calls it `temporal`.
- */
 export declare const TUNNEL_NAME_BY_BASTION_KEY: Record<string, string>;
-/**
- * Build the tunnel target set. `resolveIp` is injected for testability (the
- * command passes `resolveElbIp`). Services not in the name map are skipped;
- * services whose host can't be resolved are skipped (the forwarder needs an IP).
- */
 export declare function resolveTunnelTargets(services: Record<string, {
     host: string;
     port: number;
 }>, resolveIp: (host: string) => string | null, portOffset?: number): TunnelTarget[];
-/**
- * Resolve an AWS-internal ELB/RDS hostname to its private IP via a public
- * resolver — these names publish their private (10.x) address to public DNS
- * but the host's default resolver may not answer for them. Returns null on
- * failure (caller skips that tunnel).
- */
 export declare function resolveElbIp(host: string): string | null;
-//# sourceMappingURL=tailscale-targets.d.ts.map

package/dist/src/utils/tailscale-targets.js

@@ -1,25 +1,9 @@
-/**
- * Resolve a tenant's VPC tunnel targets from the platform bastion's service
- * map — the same source `startSsmTunnels` reads — mapping bastion service keys
- * to the app's tunnel names, resolving each ELB/RDS hostname to its private IP,
- * and assigning collision-free localhost ports via the SSM port convention.
- * (MESH-2040 / Slice 1 of MESH-2014.)
- */
 import { execFileSync } from "node:child_process";
 import * as fs from "node:fs";
 import * as path from "node:path";
 import { reserveSsmLocalPortCandidate, preferredSsmLocalPort } from "../commands/dev.js";
 import { CONFIG_DIR, atomicWriteFileSync } from "../commands/login.js";
-/** Local-port block width per tenant — wider than the canonical port span so
- * two tenants' port blocks never overlap. */
 export const PORT_BLOCK = 3000;
-/**
- * Deterministic per-tenant index for local-port offsetting. Reads a machine-global
- * registry (`~/.config/mesh/tailscale/port-registry.json`), seeded `{ mesh: 0 }` so
- * the hub's canonical ports are grandfathered regardless of registration order.
- * Assigns the next index to an unseen tenant and persists it. `registryPath` is
- * injectable for tests.
- */
 export function tenantPortIndex(tenant, registryPath) {
     const p = registryPath ?? path.join(CONFIG_DIR, "tailscale", "port-registry.json");
     let reg;
@@ -37,20 +21,11 @@ export function tenantPortIndex(tenant, registryPath) {
     atomicWriteFileSync(p, JSON.stringify(reg, null, 2), 0o600);
     return idx;
 }
-/**
- * Bastion service key → app tunnel name. Mirrors `tunnelToBastionKey` in dev.ts
- * (inverted): the bastion exposes `temporal-frontend`; the app calls it `temporal`.
- */
 export const TUNNEL_NAME_BY_BASTION_KEY = {
     "temporal-frontend": "temporal",
     "temporal-ui": "temporal-ui",
     rds: "rds",
 };
-/**
- * Build the tunnel target set. `resolveIp` is injected for testability (the
- * command passes `resolveElbIp`). Services not in the name map are skipped;
- * services whose host can't be resolved are skipped (the forwarder needs an IP).
- */
 export function resolveTunnelTargets(services, resolveIp, portOffset = 0) {
     const reserved = new Set();
     const targets = [];
@@ -61,18 +36,11 @@ export function resolveTunnelTargets(services, resolveIp, portOffset = 0) {
         const targetIp = resolveIp(svc.host);
         if (!targetIp)
             continue;
-        // Per-tenant offset keeps concurrent platform tenants off each other's ports.
         const localPort = reserveSsmLocalPortCandidate(svc.port, reserved, preferredSsmLocalPort(svc.port) + portOffset);
         targets.push({ name, localPort, targetHost: svc.host, targetIp, remotePort: svc.port });
     }
     return targets;
 }
-/**
- * Resolve an AWS-internal ELB/RDS hostname to its private IP via a public
- * resolver — these names publish their private (10.x) address to public DNS
- * but the host's default resolver may not answer for them. Returns null on
- * failure (caller skips that tunnel).
- */
 export function resolveElbIp(host) {
     try {
         const out = execFileSync("dig", ["+short", host, "@1.1.1.1"], {
@@ -90,4 +58,3 @@ export function resolveElbIp(host) {
         return null;
     }
 }
-//# sourceMappingURL=tailscale-targets.js.map

package/dist/src/utils/tailscale.d.ts

@@ -1,12 +1,3 @@
-/**
- * Userspace-Tailscale daemon management + tunnel-session state for
- * `mesh vpn tunnel` (MESH-2040 / Slice 1 of MESH-2014).
- *
- * A per-tenant `tailscaled` runs in userspace-networking mode (brew formula,
- * NOT the GUI app) exposing a SOCKS5 proxy; forwarders bridge `localhost:PORT`
- * to VPC services through it. State lives under `~/.config/mesh/tailscale/<tenant>/`
- * (r+w-granted under safehouse — see the MESH-2036 spike).
- */
 import type { PidSource } from "./pid.js";
 import type { OwnershipCheck } from "./tunnel-ownership.js";
 import type { TunnelTarget } from "./tailscale-targets.js";
@@ -15,29 +6,14 @@ export declare function tenantStateDir(tenant: string): string;
 export declare function socketPath(tenant: string): string;
 export declare function logPath(tenant: string): string;
 export declare function statePath(tenant: string): string;
-/**
- * Daemon-scoped metadata, written by `ensureDaemon` when it actually spawns the
- * daemon. Unlike `tunnel-state.json` (which `down` clears), this survives `down`
- * so a later `up` reuses the RUNNING daemon's SOCKS port instead of minting a
- * fresh one the daemon isn't listening on (which would leave every forwarder
- * dialing a dead port). Also records the daemon pid so `stopDaemon` can kill it.
- */
 export declare function daemonMetaPath(tenant: string): string;
-/**
- * Ownership manifest written by the RUNNER (the process that binds the
- * forwarder ports) — pid, process-group id, per-run token, control port. The
- * ownership handshake (MESH-2407) verifies against it; teardown signals the
- * recorded process group.
- */
 export declare function runnerManifestPath(tenant: string): string;
 export interface TunnelState {
     tenant: string;
     env: string;
     socksPort: number;
     loginServer: string;
-    /** PID of the detached forwarder supervisor (null until spawned). */
     supervisorPid: number | null;
-    /** How the runner is supervised. Defaults to "detached" when absent. */
     managed?: "launchd" | "detached";
     startedAt: string;
     tunnels: TunnelTarget[];
@@ -46,191 +22,60 @@ export declare function readTunnelState(tenant: string): TunnelState | null;
 export declare function writeTunnelState(tenant: string, state: TunnelState): void;
 export declare function clearTunnelState(tenant: string): void;
 export interface DaemonMeta {
-    /** The `--socks5-server` port the running daemon actually listens on. */
     socksPort: number;
-    /** PID of the detached `tailscaled` process (for `stopDaemon`). */
     pid: number;
 }
 export declare function readDaemonMeta(tenant: string): DaemonMeta | null;
 export declare function writeDaemonMeta(tenant: string, meta: DaemonMeta): void;
 export declare function clearDaemonMeta(tenant: string): void;
-/** Parse `tailscale status --json` → the fields we care about. */
 export declare function parseDaemonState(statusJson: string): {
     backendState: string;
     selfName?: string;
 };
-/** The brew `tailscaled` (NOT the GUI app, which ships no standalone daemon). */
 export declare function tailscaledBinPath(): string;
-/** The brew `tailscale` CLI (prefer it over the GUI shim, which aborts under sandbox). */
 export declare function tailscaleBinPath(): string;
-/** Backend state via the tenant's control socket; "Down" when no daemon answers. */
 export declare function daemonState(tenant: string): {
     backendState: string;
     selfName?: string;
 };
-/**
- * Extract the `--socks5-server` port from a `tailscaled` command line. Pure so
- * it's unit-testable. Accepts both `--socks5-server=127.0.0.1:PORT` and the
- * space-separated form, and a `localhost` host literal. Returns null if absent
- * or malformed.
- */
 export declare function parseSocksPortFromArgv(argv: string): number | null;
-/**
- * Find the running userspace `tailscaled` for a tenant by its unique
- * `--socket=<path>` argument, returning its pid and the SOCKS port it ACTUALLY
- * bound (parsed from argv). Authoritative when `daemon.json` is missing or stale
- * (e.g. a daemon left by an older build that predates the meta file). Returns
- * null when no matching process is found or `ps` is unavailable.
- */
 export declare function findRunningDaemon(tenant: string): {
     pid: number;
     socksPort: number | null;
 } | null;
-/** True if something accepts TCP on 127.0.0.1:port within `timeoutMs`. */
 export declare function portAccepts(port: number, timeoutMs?: number): Promise<boolean>;
-/**
- * Ensure a userspace `tailscaled` is running for the tenant and return the SOCKS
- * port the forwarders should dial. Idempotent — reuses a live daemon, but
- * RECONCILES the port: a daemon that's up on a different port than requested
- * (older build with no `daemon.json`, or stale meta) would otherwise leave every
- * forwarder dialing a dead port (MESH-2169). Trust `opts.socksPort` only if it
- * truly accepts; else adopt the running daemon's real port; else restart fresh.
- */
 export declare function ensureDaemon(tenant: string, opts: {
     region: string;
     socksPort: number;
 }): Promise<number>;
-/**
- * Stop the detached `tailscaled` for a tenant (SIGTERM its pid) and remove the
- * socket + daemon metadata. Leaves the Headscale node identity in `tailscaled.state`
- * so a later `up` re-spawns and rejoins without an interactive re-login — unless
- * the caller logged out first.
- *
- * Best-effort, and that includes a corrupt `daemon.json`: an unsignalable
- * recorded pid is REFUSED (never handed to `kill`) but only warns — the socket
- * and meta are still cleared. `ensureDaemon` calls this on the UP path to
- * recycle a daemon it can't verify, so throwing here would dead-end
- * `mesh vpn tunnel up` / `mesh dev` on the very file this function deletes.
- * Safe to call when nothing is running.
- */
 export declare function stopDaemon(tenant: string): void;
-/**
- * Build the `tailscale up` argument vector. Pure so it can be unit-tested and so
- * the interactive (browser-register) and zero-touch (pre-auth key) forms differ
- * only by the trailing `--authkey`.
- */
 export declare function buildTailscaleUpArgs(opts: {
     socket: string;
     loginServer: string;
     hostname: string;
     preAuthKey?: string;
 }): string[];
-/**
- * Join the tenant's Headscale tailnet via Zitadel OIDC if not already Running.
- * Prints the device-flow registration URL and polls until registered. When a
- * pre-auth key is supplied the join is non-interactive: no `/register/` URL is
- * emitted, so the scrape/relay is skipped and we just wait for Running.
- */
 export declare function joinHeadscale(tenant: string, loginServer: string, opts?: {
     preAuthKey?: string;
 }): Promise<void>;
-/** Log the tenant daemon out of Headscale (disconnect). Daemon process persists. */
 export declare function logout(tenant: string): void;
-/**
- * True iff two target sets are identical down to targetIp + remotePort. A live
- * runner pins each forwarder's target at startup, so if the ELB IP rotated (or a
- * port changed) the running forwarders point at a dead address and must be
- * respawned, not reused. Pid-agnostic (a launchd runner records no supervisor pid).
- */
 export declare function tunnelTargetsEqual(a: TunnelTarget[], b: TunnelTarget[]): boolean;
-/** True iff `state` has a supervisor pid and its target set equals `targets`. */
 export declare function supervisorTargetsMatch(state: TunnelState | null, targets: TunnelTarget[]): boolean;
-/**
- * SIGTERM the supervisor's whole process GROUP, not the bare pid.
- *
- * `state.supervisorPid` is the pid of the detached spawn — which, under the
- * canonical source launcher, is `bin/mesh.mjs`. That launcher blocks in
- * `execFileSync` around the *real* runner (a `node --import tsx … mesh.ts`
- * grandchild that actually binds the forwarder ports), and `execFileSync` does
- * not forward signals. So signalling the bare pid kills only the launcher and
- * ORPHANS the runner, which keeps its ports bound — the orphan then answers
- * `allForwardersListening`'s ownership-less liveness dial and silently pins
- * every tunnel to a stale target (the MESH-2169 / MESH-2014 failure class).
- *
- * The launcher is spawned `detached: true`, so it is a process-group leader
- * (`pgid === pid`); `process.kill(-pid, …)` reaps the launcher and the runner
- * together. Falls back to the bare pid for a legacy state file whose pid was
- * not a group leader, and tolerates ESRCH (already gone).
- *
- * `pid` is always recovered — from `tunnel-state.json`, `runner.json`, or a
- * `ps` scan — never constructed here, so it is guarded first. The guard rejects
- * anything below 2, which is what makes the NEGATED form safe: `pid >= 2` ⇒
- * `-pid <= -2`, a real process group, never `kill(0)` (this shell's own group)
- * or `kill(-1)` (broadcast to everything the user can signal). See utils/pid.ts.
- *
- * @throws {MeshCliError} when `pid` is unsignalable. Callers reaping SEVERAL
- * independently-recovered pids must catch per-pid (see `stopTunnelRunners`) —
- * letting one refusal propagate would skip the other pids and leave a live
- * runner holding ports.
- */
 export declare function killSupervisor(pid: number, source?: PidSource): void;
-/**
- * The ownership handshake for a tenant's tunnel runner (MESH-2407): manifest →
- * live pid → control endpoint → token + SOCKS port + port coverage. This is
- * the ONLY readiness/reuse signal — a bare TCP dial proves a listener exists,
- * not that it is ours, and adopting a foreign listener is exactly the
- * silent-dead-tunnel class (MESH-2169 / MESH-2014 / #2991). As a bonus the
- * handshake reads listening state from the runner's in-process servers, so it
- * opens no SOCKS→VPC data connection the way port dials do.
- */
 export declare function verifyTunnelOwnership(tenant: string, expected: {
     socksPort: number;
     ports: number[];
 }): Promise<OwnershipCheck>;
-/**
- * Tear down EVERY runner we can attribute to the tenant: the recorded
- * supervisor pid (as a process group — see `killSupervisor`), the launchd
- * agent, the manifest's process group, and any `__run`/`__supervise` process
- * discovered from argv (a runner from an older build, or one whose state file
- * was lost). This is the single teardown path — the #2991 lesson generalized:
- * no kill path may leave a grandchild with ports still bound.
- */
 export declare function stopTunnelRunners(tenant: string, prior: TunnelState | null): void;
-/**
- * Ensure the per-tenant forwarder supervisor is running for `state.tunnels`.
- * Idempotent: reuses a live runner ONLY when it passes the ownership handshake
- * (our manifest token, our SOCKS port, every target port listening in-process);
- * otherwise tears down every attributable runner, verifies the ports actually
- * freed (a still-held port is a foreign squatter → loud failure, never spawn
- * over it), and (re)spawns a fresh runner — whose readiness is again the
- * handshake, not a bare port dial. Persists the state and returns the pid.
- */
 export declare function ensureForwarders(state: TunnelState): Promise<number>;
-/**
- * Rewrite `devOutput.tunnels` so each resolved target points at its local
- * forwarder (`localhost:localPort`) — the same shape `startSsmTunnels`
- * produces. Unmatched tunnels are left untouched. Pure (no mutation of input).
- */
 export declare function rewriteTunnelsForTargets(devOutput: DevOutput, targets: TunnelTarget[]): DevOutput;
-/** True when the brew `tailscaled` binary is resolvable (Tailscale transport is usable). */
 export declare function tailscaleAvailable(): boolean;
-/**
- * Ensure the tenant's Tailscale tunnels are fully up: the shared per-tenant
- * daemon (started + OIDC-joined if needed), the resolved VPC targets, and the
- * forwarder supervisor. Idempotent (shared across worktrees/invocations of the
- * same tenant). Returns the resolved targets. Used by both `mesh vpn tunnel up`
- * and `mesh dev --transport=tailscale`.
- */
 export declare function ensureTailscaleTunnels(tenant: string, env: string, opts: {
     region: string;
     loginServer: string;
     socksPort: number;
     preAuthKey?: string;
 }): Promise<TunnelTarget[]>;
-/**
- * `startSsmTunnels` drop-in for `mesh dev`: ensure the tenant's Tailscale
- * tunnels, then rewrite `devOutput.tunnels` to the local forwarder ports.
- */
 export declare function startTailscaleTunnels(devOutput: DevOutput, ctx: {
     tenant: string;
     env: string;
@@ -240,38 +85,16 @@ export declare function startTailscaleTunnels(devOutput: DevOutput, ctx: {
     preAuthKey?: string;
 }): Promise<DevOutput>;
 export declare function launchAgentLabel(tenant: string): string;
-/** Render the per-tenant LaunchAgent plist (pure). */
 export declare function renderLaunchAgentPlist(args: {
     tenant: string;
     meshBin: string;
     nodeBin: string;
     logPath: string;
-    /** PATH for the agent — must include the dir of `tailscaled` so daemon reheal
-     * works under launchd's minimal PATH (esp. Intel `/usr/local/bin`). */
     pathEnv?: string;
 }): string;
-/** Targets whose local forwarder port isn't currently accepting connections. */
 export declare function forwardersNeedingRebind(targets: TunnelTarget[], listening: Set<number>): TunnelTarget[];
 export declare function launchAgentPath(tenant: string): string;
-/** True when launchctl works for this user (blocked under the seatbelt sandbox → false). */
 export declare function launchdAvailable(): boolean;
-/**
- * Write + (re)load the per-tenant LaunchAgent. Returns true iff it fully
- * succeeded — any failure (plist write blocked by the sandbox, `launchctl`
- * bootstrap denied, …) returns false so the caller falls back to a detached
- * runner. Never throws.
- */
 export declare function installLaunchAgent(tenant: string, meshBin: string): boolean;
-/** Unload + remove the per-tenant LaunchAgent (best-effort). */
 export declare function uninstallLaunchAgent(tenant: string): void;
-/**
- * Long-lived runner for a tenant's tunnels — used both under launchd and as the
- * detached fallback. Runs a forwarder per target and, every ~5s, self-heals:
- * respawns the daemon if its process died, and rebinds any forwarder whose port
- * stopped listening. As the process that actually binds the ports, it is the
- * sole author of the ownership manifest + control endpoint (MESH-2407) that
- * callers verify against. Needs no AWS (targets come from tunnel-state). Never
- * returns.
- */
 export declare function runTunnels(tenant: string): Promise<never>;
-//# sourceMappingURL=tailscale.d.ts.map