@mesh-tech/mesh-cli 0.20.2 → 0.20.3

package/dist/src/commands/dev.d.ts

@@ -1,24 +1,8 @@
-/**
- * mesh dev — Pulumi-output-driven local development orchestrator
- *
- * Reads `pulumi stack output dev --json` to discover services and VPC endpoints,
- * then launches each service's dev command in a tmux window.
- * Requires VPN connection for direct access to VPC resources.
- *
- * Usage:
- *   mesh dev                  Start all services, attach tmux
- *   mesh dev --headless       Start without attaching
- *   mesh dev --kill           Stop everything
- *   mesh dev --status         Show service health (--json for structured)
- *   mesh dev logs <service>   Tail a service's output
- *   mesh dev restart <svc>    Restart a single service
- */
 import { Command } from 'commander';
 import { type ResolvedAwsCreds } from '../utils/aws-auth.js';
 import { type ComposeExternalRef } from './local/mocks.js';
 interface DevEnvVar {
     value: string;
-    /** If set, env var value uses the named tunnel's host:port */
     tunnel?: string;
 }
 interface DevService {
@@ -26,266 +10,66 @@ interface DevService {
     port: number;
     command: string[];
     env?: Record<string, DevEnvVar>;
-    /**
-     * Service kind discriminator. `"dagster"` marks the `dg dev` webserver the
-     * local session synthesizes for a Dagster workspace, so the local
-     * registration path writes a Dagster discovery record the Hub's Data
-     * section reads, instead of only a plain service entry.
-     */
     kind?: 'dagster';
 }
-/** VPC-accessible endpoint for VPN direct access */
 interface DevTunnel {
-    /** VPC hostname (RDS endpoint, NLB hostname, etc.) */
     host: string;
-    /** Port number */
     port: number;
 }
 interface DevSecret {
-    /** Secrets Manager secret name */
     secretName: string;
-    /** Maps secret JSON keys → env var names to inject into services */
     envMapping: Record<string, string>;
 }
 export interface DevOutput {
-    /**
-     * Platform context. `tenant` is the APP tenant (Temporal namespace auth +
-     * encoding key). `name` is the HUB platform name (bastion + headscale DNS,
-     * which live in the hub for shared tenants); falls back to "mesh".
-     */
     platform?: {
         tenant: string;
         name?: string;
         env: string;
     };
-    /** App name (e.g., "hub") */
     app?: string;
-    /** Pulumi stack name (e.g., "dev", "feature-xyz") */
     stack?: string;
     services: Record<string, DevService>;
     tunnels: Record<string, DevTunnel>;
-    /** Secrets to resolve from Secrets Manager at dev startup */
     secrets?: Record<string, DevSecret>;
 }
-/**
- * The app's own services, as blackbox probe targets, so local uptime is real.
- *
- * Mock stand-ins are excluded: `--externals` already registers each of those
- * under its own external-service labels, and probing them twice would show one
- * dependency as two rows — one of which disappears when the mock does.
- *
- * Best-effort. A probe file is monitoring, not the app: failing to write one
- * must never take down a dev session that is otherwise working.
- */
 export declare function registerServiceProbes(devOutput: DevOutput, tenant: string, probeFiles: string[]): void;
 export interface SessionState {
     appRoot: string;
     stack: string;
     devOutput: DevOutput;
     startedAt: string;
-    /** 'tmux' (default) or 'docker' (mesh dev --runner docker, local mode) */
     runner?: 'tmux' | 'docker';
-    /** Compose-mode external services (mesh dev --externals) this session brought
-     * up — torn down (volumes kept) on `mesh dev --kill`. */
     composeExternals?: ComposeExternalRef[];
-    /** Prometheus file_sd probe targets this session's externals registered —
-     * removed on `mesh dev --kill` so the Hub stops showing uptime for a
-     * session that isn't running. Recorded as paths so `--kill --session`
-     * works without resolving an app root. */
     externalProbeFiles?: string[];
-    /**
-     * Content fingerprint of the workflow source (agent-sdk / interpreter /
-     * agent-contracts) at launch. Compared on relaunch/restart to warn before the
-     * worker replays in-flight conversations against changed workflow code
-     * (MESH-2017). Absent for sessions launched before this field existed.
-     */
     workflowFingerprint?: string;
 }
-/**
- * Relaunch safety (MESH-2017): if the workflow source changed since this session
- * launched, restarting the worker replays any in-flight conversations against the
- * NEW code — a replay-incompatible change strands them. Warn and require `--force`.
- *
- * Silent no-op when there's no prior session, no stored fingerprint (pre-feature
- * session), or nothing changed — so a restart of unchanged code never nags.
- * Returns `true` if the caller should ABORT (changed && !force).
- */
-/** Pure: did the workflow source change since launch (→ risk of stranding)? */
 export declare function workflowChanged(prior: string | undefined, current: string): boolean;
-/**
- * Check whether a TCP port is available — probing the way services actually bind.
- *
- * This used to bind `127.0.0.1` only, and that made it blind to exactly the
- * processes it exists to find. Node's `listen(port)` (and `@hono/node-server`,
- * which every agent-api uses) binds the WILDCARD address `::` in dual-stack mode,
- * holding the port on every interface — yet a probe bound to `127.0.0.1` still
- * succeeds against such a holder. So the check returned `true` for a port already
- * held by a prior `mesh dev` service, `allocatePorts` kept the preferred port, and
- * the service then died on `EADDRINUSE` at its real bind.
- *
- * Observed 2026-07-31: the `studio-api` pane died on `EADDRINUSE :::40161` while a
- * stale agent-api from an earlier boot kept serving on the same port, so the Studio
- * UI drove a process from a previous session's configuration and the conversation
- * list came back empty. Reproduced in isolation — holder on `::`, loopback probe
- * reports free, real bind fails (MESH-2590).
- *
- * Both addresses are probed: the wildcard catches all-interface holders, and the
- * loopback probe still catches a loopback-only squatter. A false "busy" is cheap —
- * `allocatePorts` simply picks another port — while a false "free" crashes the
- * service, so this deliberately errs toward busy.
- */
 export declare function isPortFree(port: number): Promise<boolean>;
-/**
- * Rewrite a service's OWN listen-port env var(s) from `oldPort` to `newPort`
- * when `allocatePorts` reassigns its port (e.g. a worktree block). Matches any
- * port-ish var (`PORT` or `*_PORT`, e.g. `VCS_PORT`/`AGENT_API_PORT`) whose value
- * is exactly the old port — so a service that reads its own env var still binds
- * the reassigned port instead of its deploy-time default (which would collide
- * with another worktree/session on that default). The name + exact-value match
- * keeps this from touching cross-service references or unrelated vars.
- * Mutates `service.env`. Pure otherwise — exported for unit testing. (MESH-2088)
- */
 export declare function rewriteOwnServicePort(service: DevService, oldPort: number, newPort: number): void;
-/**
- * Merge a session's PINNED ports/tunnels into a freshly-read DevOutput.
- *
- * `mesh dev restart <svc> --refresh-env` re-reads `pulumi stack output` to pick
- * up config/deploy changes, but the running session already allocated local
- * ports (`allocatePorts`) and opened SSM tunnels. Re-reading the raw stack
- * output would carry the DEPLOYED (pre-allocation) ports, so writing those into
- * the env file would point the service — and its peers — at the wrong ports and
- * break the live tunnels.
- *
- * This returns `fresh` (so new/changed non-port env values win) but overrides:
- *   - EVERY service present in both `fresh` and `pinned` keeps its pinned/
- *     allocated PORT (both `service.port` and `service.env.PORT.value`) — not
- *     just the refreshed one, so a regenerated service's peer references land on
- *     the session-allocated ports, and
- *   - every tunnel present in `pinned` with the pinned host:port (the live SSM
- *     endpoints); tunnels that exist only in `fresh` survive untouched.
- *
- * It then re-applies BOTH of the peer-addressing rewrites `allocatePorts` does —
- * there are two now, and naming only one here is how they drift apart:
- *   - PORT: for each service whose port differs between `fresh` (preferred) and
- *     `pinned` (allocated), `localhost:${freshPort}` → `localhost:${pinnedPort}`
- *     across EVERY service's env (e.g. a `ui`'s `API_URL` pointing at `api`).
- *   - HOST: an in-cluster address for a service running LOCALLY becomes its local
- *     one. `pulumi stack output` carries cluster hosts verbatim, so a refresh
- *     without this restores exactly the value MESH-2597 exists to remove.
- *
- * Pure: deep-clones and never mutates its arguments.
- */
 export declare function mergePinnedPorts(fresh: DevOutput, pinned: DevOutput): DevOutput;
-/**
- * Build the AWS env vars to hand to long-lived child services (ui, api,
- * ai-assistant) and SSM tunnels.
- *
- * For the AWS SSO credential path, returns AWS_PROFILE + AWS_REGION only so
- * the AWS SDK's default provider chain can auto-refresh credentials from the
- * SSO cache (~8h session) as short-lived STS tokens expire. Without this,
- * child processes inherit a frozen STS triple and start throwing
- * ExpiredTokenException ~1h into a dev session.
- *
- * For the Zitadel web-identity path, when `opts` is supplied we write an AWS
- * config file whose `credential_process` re-invokes `mesh login … --credential-process`,
- * so the AWS SDK's default provider chain auto-refreshes the underlying STS
- * triple (the `mesh login` process re-issues the Zitadel token as needed).
- * This removes the ~1h forced `mesh dev` restart. When `opts` is absent we
- * fall back to the frozen STS triple (used by CI/`environment` and any caller
- * that doesn't thread the context/role through).
- *
- * For the remaining non-SSO paths (CI/CD env keys, or no deployer role),
- * returns the explicit STS triple — there is no profile to refresh from. The
- * user must restart `mesh dev` when those tokens expire.
- */
 export declare function buildChildAwsEnv(awsEnv: Record<string, string>, method: ResolvedAwsCreds['method'] | 'ambient', profile: string | undefined, opts?: {
     context: string;
     roleArn: string;
     sessionScratchDir: string;
     meshBin: string;
 }): Record<string, string>;
-/**
- * Is `serviceDir` a package this app DEV-LINKED, rather than a stale sibling
- * worktree?
- *
- * Both look identical to the wrong-worktree guard — a source directory outside
- * the app's worktree — but only one is a mistake. A module that contributes a
- * dev service (`InfraContribution.devServices`) reports `resolvePackageRoot()`,
- * which is the package's REAL path; when that package is dev-linked from another
- * repo it legitimately lives there. Refusing it means a devService can run only
- * while its package is published — i.e. never while you are developing it, which
- * is the only time you need it.
- *
- * The test is proof, not a heuristic: read the directory's own package name and
- * ask whether THIS app resolves that name to THIS directory. A stale sibling
- * worktree cannot satisfy that — nothing in the app's `node_modules` points at
- * it — so the wrong-worktree guard keeps its teeth.
- *
- * @example
- * isLinkedDependencyDir("/repo/libs/infra-components/src/components/ai/redis", "/repo/apps/demo");
- * // → true when the app resolves @mesh-tech/infra-components to that directory
- */
 export declare function isLinkedDependencyDir(serviceDir: string, appRoot: string): boolean;
-/**
- * Reduce a service `src` to its monorepo-relative form (pure; no filesystem).
- *   - relative (`./packages/x` or `packages/x`) → normalized `packages/x`
- *   - legacy absolute (`/…/mesh-platform[/.worktrees/<name>]/packages/x`) →
- *     `packages/x` (drops the repo root AND any deploying-worktree segment)
- * Returns null when an absolute path has no recognizable monorepo marker.
- */
 export declare function monorepoRelativeSrc(src: string): string | null;
-/**
- * Build the client-facing `host:port` for an SSM tunnel.
- *
- * The `aws ssm start-session` port-forwarder binds IPv4 `127.0.0.1` only.
- * Advertising `localhost` lets Node/grpc-js resolve to IPv6 `::1` first, which
- * the tunnel isn't listening on — so e.g. the Temporal gRPC client fails with
- * `ECONNREFUSED ::1:<port>` and the Hub's Automations/workflow lists never load.
- * Maps the literal `localhost` (how tunnels are advertised today) to `127.0.0.1`
- * so clients hit the bound listener. Any other host — VPN-direct VPC endpoints,
- * or a different loopback literal like `::1`/`127.0.0.1` — passes through unchanged.
- */
 export declare function tunnelClientAddress(tunnel: {
     host: string;
     port: number;
 }): string;
-/** One tunnel's live health, resolved by a TCP dial of its client address. */
 export interface TunnelHealth {
     name: string;
-    /** Client-facing `host:port` (see {@link tunnelClientAddress}). */
     address: string;
     reachable: boolean;
 }
-/**
- * Render the Connections section (live tunnel health) as status-window lines.
- *
- * The status window refreshes every ~2s, so this is where a mid-session tunnel
- * death surfaces (MESH-2016): a dead tunnel shows `⚠ … DOWN` and a SINGLE
- * remediation line explains the `ECONNREFUSED` retry spam the dependent service
- * windows emit — instead of leaving the operator to decode that spam themselves.
- * Returns `[]` when there are no tunnels (nothing to show).
- */
 export declare function formatTunnelHealth(health: TunnelHealth[]): string[];
-/**
- * Probe the routing-critical tunnel of a (Tailscale-rewritten) devOutput and
- * return its name if the forwarder binds but does not ROUTE, else null.
- *
- * Only `temporal` is gated — it's the load-bearing VPC dependency (services die
- * on a gRPC deadline when it's dead), and keying on it mirrors the vpn-direct
- * reachability gate ({@link gateVpnDirectReachability}). A Tailscale forwarder
- * accepts its local port even when its SOCKS upstream is dead or the joined
- * tailnet doesn't route the VPC; such a forwarder tears the connection down
- * within the grace window, so it fails the connection-HOLDS probe that a bare
- * accept (the readiness gate's `waitForPort`) would pass (MESH-2169/MESH-2268).
- */
 export declare function firstUnroutableTunnel(tunnels: Record<string, {
     host: string;
     port: number;
 }>): Promise<string | null>;
-/** Compute the preferred local port for an SSM tunnel. */
-/** Tunnel backing for a dev session. */
 export type Transport = "ssm" | "tailscale" | "vpn-direct";
-/** What `startServices` should do for VPC tunnels. */
 export interface TunnelPlan {
     transport: Transport;
     tailscale?: {
@@ -296,49 +80,19 @@ export interface TunnelPlan {
         socksPort: number;
         preAuthKey?: string;
     };
-    /** True when the user EXPLICITLY asked for this transport (`--transport <x>`),
-     *  vs an auto-resolved default. An explicit tailscale choice must NOT silently
-     *  fall back to SSM — surface the failure so the user can act (MESH-2098). */
     explicit?: boolean;
 }
-/**
- * Resolve which tunnel backing `mesh dev` should use.
- *
- * An explicit `--transport` flag wins. Both `auto` and the default (unset)
- * prefer Tailscale when it's available (brew `tailscaled` present), else fall
- * back to the VPN-direct/SSM choice: VPN-direct when the VPN is connected, else
- * SSM when the session-manager plugin is present. Where Tailscale isn't
- * available the behavior is unchanged from before this feature.
- */
 export declare function resolveTransport(flag: string | undefined, ctx: {
     vpnConnected: boolean;
     hasSsmPlugin: boolean;
     tailscaleAvailable: boolean;
 }): Transport;
-/** Outcome of the reachability gate — `transport` is what to use, `reason` drives the log. */
 export type ReachabilityDecision = {
     transport: Transport;
     reason: "not-vpn-direct" | "reachable" | "fallback-ssm" | "unreachable-no-plugin";
 };
-/**
- * Correct an auto-selected `vpn-direct` transport against ACTUAL reachability of
- * the Temporal VPC endpoint (MESH-2016). `resolveTransport` uses a presence check
- * (any Tailscale/VPN up) that's tailnet-blind — Tailscale-for-SSH looks connected
- * but doesn't route the mesh VPC. Only `vpn-direct` is reachability-gated (it's
- * never an explicit choice); every other transport passes through unchanged.
- *
- * Pure so the fallback logic is testable independently of the TCP probe.
- */
 export declare function reachabilityFallbackTransport(transport: Transport, temporalReachable: boolean, hasSsmPlugin: boolean): ReachabilityDecision;
 export declare function preferredSsmLocalPort(remotePort: number): number;
-/**
- * Reserve a deterministic local-port candidate for an SSM tunnel.
- *
- * This prevents two tunnels with the same remote port (common for HTTPS
- * endpoints) from being assigned the same localhost port before the AWS CLI
- * has a chance to bind it.
- */
 export declare function reserveSsmLocalPortCandidate(remotePort: number, reservedPorts: Set<number>, startAt?: number): number;
 export declare function registerDevCommand(program: Command): void;
 export {};
-//# sourceMappingURL=dev.d.ts.map