@mesh-tech/mesh-cli 0.1.0 → 0.12.0

package/dist/src/utils/errors.js

@@ -0,0 +1,106 @@
+/**
+ * Shared CLI error type with structured remediation.
+ *
+ * Every failure along the golden path should tell the user the exact `mesh`
+ * command (or doc) that fixes it. Remediation strings must be commands or
+ * docs — never "ask <person>".
+ */
+import chalk from "chalk";
+export class MeshCliError extends Error {
+    remediation;
+    exitCode;
+    constructor(message, options = {}) {
+        super(message, options.cause !== undefined ? { cause: options.cause } : undefined);
+        this.name = "MeshCliError";
+        this.remediation = options.remediation;
+        this.exitCode = options.exitCode ?? 1;
+    }
+}
+/**
+ * Render an error's BODY — the message plus its "→ run: <command>" /
+ * "→ see: <docs>" remediation lines, with no leading severity glyph.
+ *
+ * Use this when the caller supplies its own glyph: a recovery path that logs a
+ * refusal through `logWarn` (which prefixes ⚠) and carries on would otherwise
+ * print "⚠ ✗ …". The remediation lines are the part that must survive — they
+ * name the corrupt file to delete.
+ */
+export function renderErrorBody(err) {
+    const message = err instanceof Error ? err.message : String(err);
+    if (!(err instanceof MeshCliError))
+        return message;
+    const lines = [message];
+    if (err.remediation?.command) {
+        lines.push(chalk.cyan("  → run: ") + err.remediation.command);
+    }
+    if (err.remediation?.docs) {
+        lines.push(chalk.cyan("  → see: ") + err.remediation.docs);
+    }
+    return lines.join("\n");
+}
+/**
+ * Render an error for humans. MeshCliError gets its remediation appended as
+ * "→ run: <command>" / "→ see: <docs>" lines; anything else renders its message.
+ */
+export function renderError(err) {
+    return chalk.red("✗") + " " + renderErrorBody(err);
+}
+/**
+ * Render an error as JSON for agents. Same structure as the human output:
+ * { error, remediation?: { command?, docs?, autoFixable? } }.
+ */
+export function renderErrorJson(err) {
+    if (err instanceof MeshCliError) {
+        return JSON.stringify({
+            error: err.message,
+            ...(err.remediation ? { remediation: err.remediation } : {}),
+        });
+    }
+    return JSON.stringify({ error: err instanceof Error ? err.message : String(err) });
+}
+let jsonPayloadEmitted = false;
+/**
+ * Print a command's `--json` payload — the single machine-readable document on
+ * stdout — and record that it happened.
+ *
+ * A command that emits a payload and *then* throws (the `mesh init` doctor
+ * throws by design whenever a check fails) used to produce TWO concatenated
+ * JSON documents on stdout, because `handleCliError` appended `{"error":…}`.
+ * Two documents is not JSON: `mesh init app-tenant --json | jq` failed to parse
+ * on exactly the failure path a script cares about. Routing every payload
+ * through here lets the handler know stdout is already spoken for.
+ */
+export function emitJsonPayload(payload) {
+    console.log(JSON.stringify(payload, null, 2));
+    jsonPayloadEmitted = true;
+}
+/** True once a command has written its `--json` payload to stdout. */
+export function hasEmittedJsonPayload() {
+    return jsonPayloadEmitted;
+}
+/** Test seam — the flag is module state, so specs have to be able to clear it. */
+export function resetJsonPayloadEmitted() {
+    jsonPayloadEmitted = false;
+}
+/**
+ * Top-level handler for bin/mesh.ts. Prints the error (JSON when the
+ * invocation asked for --json anywhere, since per-command flags aren't
+ * parsed once dispatch has failed) and exits with the error's code.
+ *
+ * When the command already emitted a `--json` payload, that payload IS the
+ * machine surface — and it says strictly more than this error would (the
+ * doctor's payload carries `ok:false` plus a per-check `fix` command). So the
+ * error goes to stderr as human diagnostics and stdout keeps exactly one
+ * parseable document.
+ */
+export function handleCliError(err) {
+    const wantsJson = process.argv.includes("--json");
+    if (wantsJson && !hasEmittedJsonPayload()) {
+        console.log(renderErrorJson(err));
+    }
+    else {
+        console.error(renderError(err));
+    }
+    process.exit(err instanceof MeshCliError ? err.exitCode : 1);
+}
+//# sourceMappingURL=errors.js.map

package/dist/src/utils/errors.js.map

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

package/dist/src/utils/first-party-contexts.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Pinned short-name → FQDN map for FIRST-PARTY Mesh platforms.
+ *
+ * ## Why this file exists
+ *
+ * `mesh login mesh.dev` on a clean laptop used to be unresolvable. Discovery
+ * has two paths: SSM (needs AWS credentials — the thing we are removing) and
+ * the anonymous `https://cli.<domain>/.well-known/mesh.json` endpoint. The
+ * HTTPS path is deliberately gated to contexts with ≥2 dots, because hitting
+ * `https://cli.<short-name>/…` for an arbitrary short context would let whoever
+ * registers that domain seed our cached issuer/clientId — login phishing.
+ *
+ * So the short context every internal doc tells a new developer to use was
+ * exactly the one that could not resolve without AWS.
+ *
+ * ## Why a compiled-in map is the safe fix
+ *
+ * The alias is resolved from THIS table, which ships inside the CLI and is
+ * changed only by a reviewed commit. It is not read from the network, from
+ * `~/.config/mesh`, or from an environment variable, so it cannot be seeded by
+ * an attacker — which is the property the ≥2-dot guard protects and the reason
+ * that guard must NOT be loosened instead.
+ *
+ * ## Adding an entry
+ *
+ * Only add a domain Trabian controls and has verified serves
+ * `/.well-known/mesh.json`. The map is the trust anchor; a typo here is a
+ * phishing vector, so treat additions as a security review, not a config edit.
+ */
+export declare const FIRST_PARTY_CONTEXTS: Readonly<Record<string, string>>;
+/**
+ * The FQDN to run anonymous HTTPS discovery against for a short first-party
+ * context, or null when the context is not a pinned alias.
+ *
+ * `Object.hasOwn` rather than a bare lookup: a plain-object index answers
+ * `constructor` / `toString` from the prototype chain, and this function's
+ * answer decides which host we trust with our issuer + client id.
+ */
+export declare function firstPartyDomainFor(context: string): string | null;
+//# sourceMappingURL=first-party-contexts.d.ts.map

package/dist/src/utils/first-party-contexts.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"first-party-contexts.d.ts","sourceRoot":"","sources":["../../../src/utils/first-party-contexts.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,eAAO,MAAM,oBAAoB,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAQhE,CAAC;AAEH;;;;;;;GAOG;AACH,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAIlE"}

package/dist/src/utils/first-party-contexts.js

@@ -0,0 +1,53 @@
+/**
+ * Pinned short-name → FQDN map for FIRST-PARTY Mesh platforms.
+ *
+ * ## Why this file exists
+ *
+ * `mesh login mesh.dev` on a clean laptop used to be unresolvable. Discovery
+ * has two paths: SSM (needs AWS credentials — the thing we are removing) and
+ * the anonymous `https://cli.<domain>/.well-known/mesh.json` endpoint. The
+ * HTTPS path is deliberately gated to contexts with ≥2 dots, because hitting
+ * `https://cli.<short-name>/…` for an arbitrary short context would let whoever
+ * registers that domain seed our cached issuer/clientId — login phishing.
+ *
+ * So the short context every internal doc tells a new developer to use was
+ * exactly the one that could not resolve without AWS.
+ *
+ * ## Why a compiled-in map is the safe fix
+ *
+ * The alias is resolved from THIS table, which ships inside the CLI and is
+ * changed only by a reviewed commit. It is not read from the network, from
+ * `~/.config/mesh`, or from an environment variable, so it cannot be seeded by
+ * an attacker — which is the property the ≥2-dot guard protects and the reason
+ * that guard must NOT be loosened instead.
+ *
+ * ## Adding an entry
+ *
+ * Only add a domain Trabian controls and has verified serves
+ * `/.well-known/mesh.json`. The map is the trust anchor; a typo here is a
+ * phishing vector, so treat additions as a security review, not a config edit.
+ */
+export const FIRST_PARTY_CONTEXTS = Object.freeze({
+    // Verified 2026-08-14: https://cli.dev.platform.meshtech.io/.well-known/mesh.json
+    // answers with the platform's issuer + CLI client id + registryBroker,
+    // anonymously. (Repointed from dev.trabian.meshtech.io — the trabian tenant
+    // platform lives in a different AWS account with no registry; the
+    // platform-dev stack in the registry-owning account is the developer front
+    // door. mesh-sandbox#32 / #3587.)
+    "mesh.dev": "dev.platform.meshtech.io",
+});
+/**
+ * The FQDN to run anonymous HTTPS discovery against for a short first-party
+ * context, or null when the context is not a pinned alias.
+ *
+ * `Object.hasOwn` rather than a bare lookup: a plain-object index answers
+ * `constructor` / `toString` from the prototype chain, and this function's
+ * answer decides which host we trust with our issuer + client id.
+ */
+export function firstPartyDomainFor(context) {
+    if (!Object.hasOwn(FIRST_PARTY_CONTEXTS, context))
+        return null;
+    const domain = FIRST_PARTY_CONTEXTS[context];
+    return typeof domain === "string" && domain ? domain : null;
+}
+//# sourceMappingURL=first-party-contexts.js.map

package/dist/src/utils/first-party-contexts.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"first-party-contexts.js","sourceRoot":"","sources":["../../../src/utils/first-party-contexts.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,MAAM,CAAC,MAAM,oBAAoB,GAAqC,MAAM,CAAC,MAAM,CAAC;IAClF,kFAAkF;IAClF,uEAAuE;IACvE,4EAA4E;IAC5E,kEAAkE;IAClE,2EAA2E;IAC3E,kCAAkC;IAClC,UAAU,EAAE,0BAA0B;CACvC,CAAC,CAAC;AAEH;;;;;;;GAOG;AACH,MAAM,UAAU,mBAAmB,CAAC,OAAe;IACjD,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,oBAAoB,EAAE,OAAO,CAAC;QAAE,OAAO,IAAI,CAAC;IAC/D,MAAM,MAAM,GAAG,oBAAoB,CAAC,OAAO,CAAC,CAAC;IAC7C,OAAO,OAAO,MAAM,KAAK,QAAQ,IAAI,MAAM,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,IAAI,CAAC;AAC9D,CAAC"}

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

@@ -1,9 +1,11 @@
 /**
  * Utility exports
  */
+export * from "./errors.js";
 export * from "./log.js";
 export * from "./context.js";
 export * from "./bastion.js";
 export * from "./credentials.js";
 export * from "./pulumi.js";
+export * from "./vpn.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/src/utils/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/utils/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,cAAc,UAAU,CAAC;AACzB,cAAc,cAAc,CAAC;AAC7B,cAAc,cAAc,CAAC;AAC7B,cAAc,kBAAkB,CAAC;AACjC,cAAc,aAAa,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/utils/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,cAAc,aAAa,CAAC;AAC5B,cAAc,UAAU,CAAC;AACzB,cAAc,cAAc,CAAC;AAC7B,cAAc,cAAc,CAAC;AAC7B,cAAc,kBAAkB,CAAC;AACjC,cAAc,aAAa,CAAC;AAC5B,cAAc,UAAU,CAAC"}

package/dist/src/utils/index.js

@@ -1,9 +1,11 @@
 /**
  * Utility exports
  */
+export * from "./errors.js";
 export * from "./log.js";
 export * from "./context.js";
 export * from "./bastion.js";
 export * from "./credentials.js";
 export * from "./pulumi.js";
+export * from "./vpn.js";
 //# sourceMappingURL=index.js.map

package/dist/src/utils/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/utils/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,cAAc,UAAU,CAAC;AACzB,cAAc,cAAc,CAAC;AAC7B,cAAc,cAAc,CAAC;AAC7B,cAAc,kBAAkB,CAAC;AACjC,cAAc,aAAa,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/utils/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,cAAc,aAAa,CAAC;AAC5B,cAAc,UAAU,CAAC;AACzB,cAAc,cAAc,CAAC;AAC7B,cAAc,cAAc,CAAC;AAC7B,cAAc,kBAAkB,CAAC;AACjC,cAAc,aAAa,CAAC;AAC5B,cAAc,UAAU,CAAC"}

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

@@ -0,0 +1,62 @@
+interface EksClusterData {
+    clusterEndpoint: string;
+    clusterCaData: string;
+    clusterName: string;
+}
+/**
+ * Build a kubeconfig YAML that authenticates to `cluster` via `aws eks get-token`.
+ * Pure — no I/O. The `region` is for the get-token exec args (the active AWS
+ * identity is whatever the process runs as: deployer / SSO / CI).
+ */
+export declare function buildKubeconfig(cluster: EksClusterData, region: string): string;
+/**
+ * Deterministic path of the session-scoped kubeconfig written by
+ * {@link ensureKubeconfig}. Exposed so callers can point `KUBECONFIG` at the
+ * last-good file when a fresh SSM re-resolve isn't available (e.g. on
+ * `mesh dev restart --refresh-env`), rather than letting kubectl fall back to
+ * `~/.kube/config`.
+ */
+export declare function sessionKubeconfigPath(sessionName: string): string;
+/** Why {@link ensureKubeconfig} couldn't resolve the cluster. */
+export interface EnsureKubeconfigFailure {
+    /** The SSM parameter name that was read (or attempted). */
+    parameter: string;
+    /** The exception thrown, or a synthetic Error for empty/malformed data. */
+    error: unknown;
+}
+export interface EnsureKubeconfigDeps {
+    /** SSM GetParameter (decrypted value or undefined) — injectable for tests. */
+    getParameter?: (name: string) => Promise<string | undefined>;
+    /**
+     * Invoked when cluster resolution fails, with the parameter tried and the
+     * underlying error — so callers can say WHAT failed instead of guessing
+     * "check your SSM read access" at the user (MESH-2515).
+     */
+    onError?: (failure: EnsureKubeconfigFailure) => void;
+}
+/**
+ * The HUB platform name for platform-level resource lookups (EKS export,
+ * bastion). `platform.name` in the dev output is the hub (e.g. "trabian");
+ * when absent — outputs predating the field — fall back to the default hub
+ * "mesh", NEVER to the app tenant. This one definition pins the axis that
+ * regressed in the original MESH-2515 bug.
+ */
+export declare function resolveHubPlatformName(platform: {
+    name?: string;
+    tenant?: string;
+    env?: string;
+} | undefined): string;
+/**
+ * Resolve the hub EKS cluster from SSM and write a session-scoped kubeconfig.
+ *
+ * Reads `/mesh-platform/{platformName}/{env}/core/eks` — platform-level cluster
+ * data lives under the app's HUB platform (`platform.name` in the dev output,
+ * e.g. "trabian"; "mesh" is only the default hub, MESH-2515). Writes to
+ * `${tmpdir}/mesh-dev-sessions/{sessionName}.kubeconfig` (never touches
+ * ~/.kube/config). Returns the path, or `null` if the cluster data can't be
+ * resolved (best-effort — the caller continues without it; the failure detail
+ * goes to `deps.onError`).
+ */
+export declare function ensureKubeconfig(platformName: string, env: string, sessionName: string, deps?: EnsureKubeconfigDeps): Promise<string | null>;
+export {};
+//# sourceMappingURL=kubeconfig.d.ts.map

package/dist/src/utils/kubeconfig.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"kubeconfig.d.ts","sourceRoot":"","sources":["../../../src/utils/kubeconfig.ts"],"names":[],"mappings":"AAiBA,UAAU,cAAc;IACtB,eAAe,EAAE,MAAM,CAAC;IACxB,aAAa,EAAE,MAAM,CAAC;IACtB,WAAW,EAAE,MAAM,CAAC;CACrB;AAED;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,OAAO,EAAE,cAAc,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,CA4B/E;AAED;;;;;;GAMG;AACH,wBAAgB,qBAAqB,CAAC,WAAW,EAAE,MAAM,GAAG,MAAM,CAEjE;AAED,iEAAiE;AACjE,MAAM,WAAW,uBAAuB;IACtC,2DAA2D;IAC3D,SAAS,EAAE,MAAM,CAAC;IAClB,2EAA2E;IAC3E,KAAK,EAAE,OAAO,CAAC;CAChB;AAED,MAAM,WAAW,oBAAoB;IACnC,8EAA8E;IAC9E,YAAY,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAAC;IAC7D;;;;OAIG;IACH,OAAO,CAAC,EAAE,CAAC,OAAO,EAAE,uBAAuB,KAAK,IAAI,CAAC;CACtD;AAED;;;;;;GAMG;AACH,wBAAgB,sBAAsB,CACpC,QAAQ,EAAE;IAAE,IAAI,CAAC,EAAE,MAAM,CAAC;IAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IAAC,GAAG,CAAC,EAAE,MAAM,CAAA;CAAE,GAAG,SAAS,GACrE,MAAM,CAER;AASD;;;;;;;;;;GAUG;AACH,wBAAsB,gBAAgB,CACpC,YAAY,EAAE,MAAM,EACpB,GAAG,EAAE,MAAM,EACX,WAAW,EAAE,MAAM,EACnB,IAAI,GAAE,oBAAyB,GAC9B,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CA6BxB"}

package/dist/src/utils/kubeconfig.js

@@ -0,0 +1,118 @@
+/**
+ * Turnkey kubeconfig for `mesh dev`.
+ *
+ * `mesh dev` shells out to `kubectl` (Temporal encoding-key read, temporal-pod
+ * env fallback). Rather than depend on the operator's ambient ~/.kube/config
+ * (which may be unset/stale, and which the apps-deployer role can't populate via
+ * `aws eks update-kubeconfig` — it lacks `eks:DescribeCluster`), we build a
+ * kubeconfig from the platform EKS cluster data in SSM and authenticate via
+ * `aws eks get-token` (STS-only — needs just the cluster name).
+ *
+ * Mirrors the kubeconfig the Pulumi k8s provider builds in
+ * `@mesh-tech/infra-components` AppEnvironment.buildExecKubeconfig.
+ */
+import * as fs from 'fs';
+import * as os from 'os';
+import * as path from 'path';
+/**
+ * Build a kubeconfig YAML that authenticates to `cluster` via `aws eks get-token`.
+ * Pure — no I/O. The `region` is for the get-token exec args (the active AWS
+ * identity is whatever the process runs as: deployer / SSO / CI).
+ */
+export function buildKubeconfig(cluster, region) {
+    return `apiVersion: v1
+kind: Config
+clusters:
+- cluster:
+    server: ${cluster.clusterEndpoint}
+    certificate-authority-data: ${cluster.clusterCaData}
+  name: eks-cluster
+contexts:
+- context:
+    cluster: eks-cluster
+    user: eks-user
+  name: eks-context
+current-context: eks-context
+users:
+- name: eks-user
+  user:
+    exec:
+      apiVersion: client.authentication.k8s.io/v1beta1
+      command: aws
+      args:
+        - eks
+        - get-token
+        - --cluster-name
+        - ${cluster.clusterName}
+        - --region
+        - ${region}
+`;
+}
+/**
+ * Deterministic path of the session-scoped kubeconfig written by
+ * {@link ensureKubeconfig}. Exposed so callers can point `KUBECONFIG` at the
+ * last-good file when a fresh SSM re-resolve isn't available (e.g. on
+ * `mesh dev restart --refresh-env`), rather than letting kubectl fall back to
+ * `~/.kube/config`.
+ */
+export function sessionKubeconfigPath(sessionName) {
+    return path.join(os.tmpdir(), 'mesh-dev-sessions', `${sessionName}.kubeconfig`);
+}
+/**
+ * The HUB platform name for platform-level resource lookups (EKS export,
+ * bastion). `platform.name` in the dev output is the hub (e.g. "trabian");
+ * when absent — outputs predating the field — fall back to the default hub
+ * "mesh", NEVER to the app tenant. This one definition pins the axis that
+ * regressed in the original MESH-2515 bug.
+ */
+export function resolveHubPlatformName(platform) {
+    return platform?.name ?? 'mesh';
+}
+async function ssmGetParameter(name) {
+    const { SSMClient, GetParameterCommand } = await import('@aws-sdk/client-ssm');
+    const ssm = new SSMClient({ region: process.env.AWS_REGION || 'us-east-2' });
+    const resp = await ssm.send(new GetParameterCommand({ Name: name, WithDecryption: true }));
+    return resp.Parameter?.Value;
+}
+/**
+ * Resolve the hub EKS cluster from SSM and write a session-scoped kubeconfig.
+ *
+ * Reads `/mesh-platform/{platformName}/{env}/core/eks` — platform-level cluster
+ * data lives under the app's HUB platform (`platform.name` in the dev output,
+ * e.g. "trabian"; "mesh" is only the default hub, MESH-2515). Writes to
+ * `${tmpdir}/mesh-dev-sessions/{sessionName}.kubeconfig` (never touches
+ * ~/.kube/config). Returns the path, or `null` if the cluster data can't be
+ * resolved (best-effort — the caller continues without it; the failure detail
+ * goes to `deps.onError`).
+ */
+export async function ensureKubeconfig(platformName, env, sessionName, deps = {}) {
+    const parameter = `/mesh-platform/${platformName}/${env}/core/eks`;
+    const getParameter = deps.getParameter ?? ssmGetParameter;
+    let cluster;
+    try {
+        const value = await getParameter(parameter);
+        if (!value)
+            throw new Error('parameter is empty or missing');
+        const parsed = JSON.parse(value);
+        if (!parsed.clusterEndpoint || !parsed.clusterCaData || !parsed.clusterName) {
+            throw new Error('cluster data is missing clusterEndpoint/clusterCaData/clusterName');
+        }
+        cluster = {
+            clusterEndpoint: parsed.clusterEndpoint,
+            clusterCaData: parsed.clusterCaData,
+            clusterName: parsed.clusterName,
+        };
+    }
+    catch (error) {
+        deps.onError?.({ parameter, error });
+        return null;
+    }
+    const region = process.env.AWS_REGION || 'us-east-2';
+    const kubeconfigPath = sessionKubeconfigPath(sessionName);
+    if (!fs.existsSync(path.dirname(kubeconfigPath))) {
+        fs.mkdirSync(path.dirname(kubeconfigPath), { recursive: true });
+    }
+    fs.writeFileSync(kubeconfigPath, buildKubeconfig(cluster, region), { mode: 0o600 });
+    return kubeconfigPath;
+}
+//# sourceMappingURL=kubeconfig.js.map

package/dist/src/utils/kubeconfig.js.map

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

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

@@ -1,8 +1,34 @@
 /**
- * Logging utilities with colored output
+ * Logging utilities with colored output.
+ *
+ * Non-TTY streams (CI, agent runs, piped output) get an [HH:MM:SS] prefix on
+ * every line so long quiet stretches are attributable after the fact
+ * (MESH-2479); interactive terminals stay clean. Override with
+ * MESH_LOG_TIMESTAMPS=1 (force on) / =0 (force off).
  */
+/**
+ * Pure prefix decision, exported for tests: timestamps when the env flag says
+ * so, else whenever stderr is not a TTY.
+ */
+export declare function logPrefix(opts: {
+    isTTY: boolean;
+    envFlag: string | undefined;
+    now: Date;
+}): string;
 export declare function logInfo(message: string): void;
 export declare function logSuccess(message: string): void;
 export declare function logWarn(message: string): void;
 export declare function logError(message: string): void;
+/** Render elapsed milliseconds compactly: "45s", "2m 30s", "1h 5m". */
+export declare function formatElapsed(ms: number): string;
+/**
+ * Periodic "still working" line during a long silent operation (registry
+ * fetches, image builds) so a non-TTY first run never sits at 0 bytes of
+ * output for minutes (MESH-2479). `touch()` marks recent real output, which
+ * suppresses the next beat — the heartbeat only fills silence.
+ */
+export declare function startHeartbeat(label: string, intervalMs?: number): {
+    stop: () => void;
+    touch: () => void;
+};
 //# sourceMappingURL=log.d.ts.map

package/dist/src/utils/log.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"log.d.ts","sourceRoot":"","sources":["../../../src/utils/log.ts"],"names":[],"mappings":"AAAA;;GAEG;AAIH,wBAAgB,OAAO,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAE7C;AAED,wBAAgB,UAAU,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAEhD;AAED,wBAAgB,OAAO,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAE7C;AAED,wBAAgB,QAAQ,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAE9C"}
+{"version":3,"file":"log.d.ts","sourceRoot":"","sources":["../../../src/utils/log.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAIH;;;GAGG;AACH,wBAAgB,SAAS,CAAC,IAAI,EAAE;IAC9B,KAAK,EAAE,OAAO,CAAC;IACf,OAAO,EAAE,MAAM,GAAG,SAAS,CAAC;IAC5B,GAAG,EAAE,IAAI,CAAC;CACX,GAAG,MAAM,CAGT;AAYD,wBAAgB,OAAO,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAE7C;AAED,wBAAgB,UAAU,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAEhD;AAED,wBAAgB,OAAO,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAE7C;AAED,wBAAgB,QAAQ,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAE9C;AAED,uEAAuE;AACvE,wBAAgB,aAAa,CAAC,EAAE,EAAE,MAAM,GAAG,MAAM,CAQhD;AAED;;;;;GAKG;AACH,wBAAgB,cAAc,CAC5B,KAAK,EAAE,MAAM,EACb,UAAU,SAAS,GAClB;IAAE,IAAI,EAAE,MAAM,IAAI,CAAC;IAAC,KAAK,EAAE,MAAM,IAAI,CAAA;CAAE,CAczC"}

package/dist/src/utils/log.js

@@ -1,17 +1,71 @@
 /**
- * Logging utilities with colored output
+ * Logging utilities with colored output.
+ *
+ * Non-TTY streams (CI, agent runs, piped output) get an [HH:MM:SS] prefix on
+ * every line so long quiet stretches are attributable after the fact
+ * (MESH-2479); interactive terminals stay clean. Override with
+ * MESH_LOG_TIMESTAMPS=1 (force on) / =0 (force off).
  */
 import chalk from "chalk";
+/**
+ * Pure prefix decision, exported for tests: timestamps when the env flag says
+ * so, else whenever stderr is not a TTY.
+ */
+export function logPrefix(opts) {
+    const enabled = opts.envFlag === "1" || (opts.envFlag !== "0" && !opts.isTTY);
+    return enabled ? `[${opts.now.toISOString().slice(11, 19)}] ` : "";
+}
+function prefix() {
+    return chalk.dim(logPrefix({
+        isTTY: !!process.stderr.isTTY,
+        envFlag: process.env.MESH_LOG_TIMESTAMPS,
+        now: new Date(),
+    }));
+}
 export function logInfo(message) {
-    console.error(chalk.blue("ℹ"), message);
+    console.error(prefix() + chalk.blue("ℹ"), message);
 }
 export function logSuccess(message) {
-    console.error(chalk.green("✓"), message);
+    console.error(prefix() + chalk.green("✓"), message);
 }
 export function logWarn(message) {
-    console.error(chalk.yellow("⚠"), message);
+    console.error(prefix() + chalk.yellow("⚠"), message);
 }
 export function logError(message) {
-    console.error(chalk.red("✗"), message);
+    console.error(prefix() + chalk.red("✗"), message);
+}
+/** Render elapsed milliseconds compactly: "45s", "2m 30s", "1h 5m". */
+export function formatElapsed(ms) {
+    const totalSec = Math.max(0, Math.round(ms / 1000));
+    const h = Math.floor(totalSec / 3600);
+    const m = Math.floor((totalSec % 3600) / 60);
+    const s = totalSec % 60;
+    if (h > 0)
+        return `${h}h ${m}m`;
+    if (m > 0)
+        return `${m}m ${s}s`;
+    return `${s}s`;
+}
+/**
+ * Periodic "still working" line during a long silent operation (registry
+ * fetches, image builds) so a non-TTY first run never sits at 0 bytes of
+ * output for minutes (MESH-2479). `touch()` marks recent real output, which
+ * suppresses the next beat — the heartbeat only fills silence.
+ */
+export function startHeartbeat(label, intervalMs = 15_000) {
+    const startedAt = Date.now();
+    let lastOutputAt = startedAt;
+    const timer = setInterval(() => {
+        if (Date.now() - lastOutputAt < intervalMs)
+            return;
+        logInfo(`… still working: ${label} (${formatElapsed(Date.now() - startedAt)} elapsed)`);
+    }, intervalMs);
+    timer.unref?.();
+    return {
+        stop: () => clearInterval(timer),
+        touch: () => {
+            lastOutputAt = Date.now();
+        },
+    };
 }
 //# sourceMappingURL=log.js.map

package/dist/src/utils/log.js.map

@@ -1 +1 @@
-{"version":3,"file":"log.js","sourceRoot":"","sources":["../../../src/utils/log.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,KAAK,MAAM,OAAO,CAAC;AAE1B,MAAM,UAAU,OAAO,CAAC,OAAe;IACrC,OAAO,CAAC,KAAK,CAAC,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,OAAO,CAAC,CAAC;AAC1C,CAAC;AAED,MAAM,UAAU,UAAU,CAAC,OAAe;IACxC,OAAO,CAAC,KAAK,CAAC,KAAK,CAAC,KAAK,CAAC,GAAG,CAAC,EAAE,OAAO,CAAC,CAAC;AAC3C,CAAC;AAED,MAAM,UAAU,OAAO,CAAC,OAAe;IACrC,OAAO,CAAC,KAAK,CAAC,KAAK,CAAC,MAAM,CAAC,GAAG,CAAC,EAAE,OAAO,CAAC,CAAC;AAC5C,CAAC;AAED,MAAM,UAAU,QAAQ,CAAC,OAAe;IACtC,OAAO,CAAC,KAAK,CAAC,KAAK,CAAC,GAAG,CAAC,GAAG,CAAC,EAAE,OAAO,CAAC,CAAC;AACzC,CAAC"}
+{"version":3,"file":"log.js","sourceRoot":"","sources":["../../../src/utils/log.ts"],"names":[],"mappings":"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"}

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

@@ -0,0 +1,47 @@
+/**
+ * Guard for pids the CLI reads back rather than constructs.
+ *
+ * Every teardown path in the CLI signals a pid it recovered from somewhere:
+ * `tunnel-state.json`, `runner.json`, `daemon.json`, or a `ps` argv scan. None
+ * of those are trustworthy — a truncated write, a stale file from an older
+ * build, or a hand-edited state dir can put any integer there. POSIX `kill(2)`
+ * overloads the pid argument, so the wrong integer is not a no-op:
+ *
+ *  - `kill(0, sig)`  → every process in the CALLER'S OWN process group.
+ *  - `kill(-1, sig)` → every process the caller is permitted to signal.
+ *  - `kill(1, sig)`  → init. And teardown negates before signalling, so a `1`
+ *    on disk becomes `kill(-1)` — the broadcast.
+ *
+ * That is not hypothetical: a `pid: -1` written by a unit test SIGTERM'd the
+ * author's entire login session (tmux server, every pane, an in-flight
+ * `mesh login`) on 2026-08-01. Refuse the input instead of signalling it.
+ *
+ * The guard is intentionally strict about the LOW end (`pid >= 2`) so the
+ * NEGATED form used for process-group teardown is safe by construction: if
+ * `pid >= 2` then `-pid <= -2`, which is always a real process group and never
+ * `0` (own group) or `-1` (broadcast). Callers signalling `-pid` need no
+ * second check — see `killSupervisor`.
+ */
+/** Where a recovered pid came from, for the refusal message + remediation. */
+export interface PidSource {
+    /** What the pid claims to be, e.g. "tunnel supervisor pid". */
+    what: string;
+    /**
+     * Absolute path of the state file it was read from, when there is one.
+     * Present ⇒ the refusal tells the user the exact file to delete, so a corrupt
+     * state dir does not brick `mesh tunnel down` (which is the command that
+     * would otherwise clear it).
+     */
+    file?: string;
+}
+/**
+ * Throw unless `pid` is safe to pass to `process.kill` (directly or negated).
+ *
+ * Call this at the top of any function that signals a pid it did not construct
+ * itself. Existence checks (`process.kill(pid, 0)`) do not need it — signal 0
+ * delivers nothing — but they gain nothing from skipping it either.
+ *
+ * @throws {MeshCliError} with `rm <file>` remediation when `source.file` is set.
+ */
+export declare function assertSignalablePid(pid: unknown, source: PidSource): void;
+//# sourceMappingURL=pid.d.ts.map

package/dist/src/utils/pid.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pid.d.ts","sourceRoot":"","sources":["../../../src/utils/pid.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAIH,8EAA8E;AAC9E,MAAM,WAAW,SAAS;IACxB,+DAA+D;IAC/D,IAAI,EAAE,MAAM,CAAC;IACb;;;;;OAKG;IACH,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAuCD;;;;;;;;GAQG;AACH,wBAAgB,mBAAmB,CAAC,GAAG,EAAE,OAAO,EAAE,MAAM,EAAE,SAAS,GAAG,IAAI,CAczE"}