@mesh-tech/mesh-cli 0.1.0 → 0.12.0

package/dist/build-info.json

@@ -0,0 +1,4 @@
+{
+  "commit": "eced59511",
+  "builtAt": "2026-08-16T04:05:41.376Z"
+}

package/dist/src/commands/agent-api-client.d.ts

@@ -0,0 +1,79 @@
+/**
+ * Shared agent-api client: resolves a `--target`/`--api-url`/`--context`
+ * triple (via the `@mesh-tech/agent-targets` registry) to a concrete
+ * `AgentApiTarget`, and fetches agent-api paths against it with auth.
+ *
+ * Consumed by `mesh artifacts get` today; later `mesh conversations`
+ * commands share the same resolution + fetch path.
+ */
+export interface AgentApiTarget {
+    apiBaseUrl: string;
+    loginContext?: string;
+    conversationPathPrefix?: string;
+    hubBaseUrl?: string;
+    token?: string;
+}
+export declare class TargetResolutionError extends Error {
+}
+/**
+ * Precedence:
+ *  1. --api-url (+ --context, default "mesh.dev") — highest.
+ *  2. --target explicitly given → registry: loaded+found wins, loaded+missing
+ *     throws (unknown target), invalid throws (with the registry's parse
+ *     error), absent throws ("no registry" guidance).
+ *  3. neither given → loaded registry's defaultTarget; otherwise (registry
+ *     absent/invalid) falls back to AGENT_API_URL/API_URL/localhost:8787 —
+ *     this path NEVER throws (backward compat with the old no-flag behavior).
+ */
+export declare function resolveTarget(opts: {
+    target?: string;
+    apiUrl?: string;
+    context?: string;
+}): AgentApiTarget;
+/**
+ * Fetch an agent-api path on the resolved target, with auth. Caller checks
+ * status.
+ *
+ * `redirect: "manual"` is deliberate: an unauthenticated `/v1` call against a
+ * deployed agent 302s to Zitadel. With the default `redirect: "follow"`,
+ * fetch follows it and returns a `200` HTML login page — `describeHttpError`'s
+ * auth branch never fires and the caller sees a raw JSON-parse error instead
+ * of auth guidance. With `"manual"`, the redirect surfaces as a Response with
+ * `type: "opaqueredirect"` (status 0), which `describeHttpError` already maps
+ * to the "auth did not reach the agent" message.
+ */
+export declare function agentApiFetch(target: AgentApiTarget, apiPath: string): Promise<Response>;
+/**
+ * Turn a thrown fetch error into local-vs-remote-aware guidance. A bare
+ * `ECONNREFUSED`/`fetch failed` (also `ENOTFOUND`/`EAI_AGAIN`) means
+ * something different depending on the target: against a LOCAL apiBaseUrl it
+ * almost always means the local `mesh dev` agent API isn't running; against
+ * a REMOTE one it means a down host, a DNS typo, a dropped VPN/tailscale
+ * connection, or (occasionally) an auth redirect that the fetch layer
+ * couldn't follow. Only actual network throws get this treatment — every
+ * other error (including ones `describeHttpError` already produced) passes
+ * through unchanged so callers can log it without double guidance.
+ */
+export declare function describeNetworkError(err: unknown, target: AgentApiTarget): string;
+/**
+ * Shared, target-aware renderer for a non-ok agent-api response. Used by
+ * both `mesh conversations` (list/show/artifacts) and `mesh artifacts get`
+ * so there is exactly one place that turns an HTTP failure into human
+ * guidance — no more dev-oriented "restart the API process" advice, no more
+ * a second parallel renderer for `show`'s 503 special-case.
+ *
+ * `ctx.id` (a conversation id, when the caller has one) enables the
+ * `mesh temporal recover-conversation <id>` hint on a `conversation_unavailable`
+ * 503 and is echoed in the 404 message for context.
+ *
+ * Response shapes are verified against
+ * `packages/agent-sdk/src/agent-api/server.ts` — do not re-infer:
+ *  - 404 → `{ error: "conversation not found", conversationId }`.
+ *  - 503 conversation_unavailable → `{ error: "conversation_unavailable",
+ *    conversationId, detail: "<text>" }` — human text is under `detail`,
+ *    NOT `message`.
+ */
+export declare function describeHttpError(res: Response, target: AgentApiTarget, ctx?: {
+    id?: string;
+}): Promise<string>;
+//# sourceMappingURL=agent-api-client.d.ts.map

package/dist/src/commands/agent-api-client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-api-client.d.ts","sourceRoot":"","sources":["../../../src/commands/agent-api-client.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAYH,MAAM,WAAW,cAAc;IAC7B,UAAU,EAAE,MAAM,CAAC;IACnB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,sBAAsB,CAAC,EAAE,MAAM,CAAC;IAChC,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,qBAAa,qBAAsB,SAAQ,KAAK;CAAG;AAKnD;;;;;;;;;GASG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE;IAAE,MAAM,CAAC,EAAE,MAAM,CAAC;IAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IAAC,OAAO,CAAC,EAAE,MAAM,CAAA;CAAE,GAAG,cAAc,CAuD1G;AAWD;;;;;;;;;;;GAWG;AACH,wBAAsB,aAAa,CAAC,MAAM,EAAE,cAAc,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,QAAQ,CAAC,CAG9F;AAID;;;;;;;;;;GAUG;AACH,wBAAgB,oBAAoB,CAAC,GAAG,EAAE,OAAO,EAAE,MAAM,EAAE,cAAc,GAAG,MAAM,CAajF;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAsB,iBAAiB,CACrC,GAAG,EAAE,QAAQ,EACb,MAAM,EAAE,cAAc,EACtB,GAAG,CAAC,EAAE;IAAE,EAAE,CAAC,EAAE,MAAM,CAAA;CAAE,GACpB,OAAO,CAAC,MAAM,CAAC,CA4BjB"}

package/dist/src/commands/agent-api-client.js

@@ -0,0 +1,170 @@
+/**
+ * Shared agent-api client: resolves a `--target`/`--api-url`/`--context`
+ * triple (via the `@mesh-tech/agent-targets` registry) to a concrete
+ * `AgentApiTarget`, and fetches agent-api paths against it with auth.
+ *
+ * Consumed by `mesh artifacts get` today; later `mesh conversations`
+ * commands share the same resolution + fetch path.
+ */
+import { loadTargetsFile, stripSlash } from "@mesh-tech/agent-targets";
+import { getValidToken } from "./login.js";
+import { logWarn } from "../utils/log.js";
+const DEFAULT_AUTH_CONTEXT = "mesh.dev";
+/** Matches a local (`mesh dev`-hosted) apiBaseUrl — shared by `authHeaders`'s
+ * dev-identity fallback and `describeNetworkError`'s local/remote gating. */
+const LOCAL_URL_RE = /^https?:\/\/(localhost|127\.0\.0\.1|\[::1\])(:|\/|$)/i;
+export class TargetResolutionError extends Error {
+}
+const NO_REGISTRY_GUIDANCE = "no registry — add `mesh agent-targets add <name>` or pass --api-url";
+/**
+ * Precedence:
+ *  1. --api-url (+ --context, default "mesh.dev") — highest.
+ *  2. --target explicitly given → registry: loaded+found wins, loaded+missing
+ *     throws (unknown target), invalid throws (with the registry's parse
+ *     error), absent throws ("no registry" guidance).
+ *  3. neither given → loaded registry's defaultTarget; otherwise (registry
+ *     absent/invalid) falls back to AGENT_API_URL/API_URL/localhost:8787 —
+ *     this path NEVER throws (backward compat with the old no-flag behavior).
+ */
+export function resolveTarget(opts) {
+    if (opts.apiUrl) {
+        return { apiBaseUrl: stripSlash(opts.apiUrl), loginContext: opts.context || DEFAULT_AUTH_CONTEXT };
+    }
+    const res = loadTargetsFile();
+    if (opts.target) {
+        if (res.status === "invalid") {
+            throw new TargetResolutionError(`Registry at ${res.path} is invalid: ${res.message}. Fix it, or pass --api-url <url>.`);
+        }
+        if (res.status === "absent") {
+            throw new TargetResolutionError(`No agent target given and ${NO_REGISTRY_GUIDANCE}.`);
+        }
+        const entry = res.targets[opts.target];
+        if (!entry) {
+            throw new TargetResolutionError(`Unknown target "${opts.target}". Available: ${Object.keys(res.targets).join(", ") || "(none)"}. ` +
+                `Add it with 'mesh agent-targets add ${opts.target}' or pass --api-url.`);
+        }
+        return {
+            apiBaseUrl: entry.apiBaseUrl,
+            loginContext: entry.loginContext,
+            conversationPathPrefix: entry.conversationPathPrefix,
+            hubBaseUrl: entry.hubBaseUrl,
+            token: entry.token,
+        };
+    }
+    if (res.status === "loaded") {
+        // RegistrySchema's refine() guarantees defaultTarget names an existing entry.
+        const entry = res.targets[res.defaultTarget];
+        return {
+            apiBaseUrl: entry.apiBaseUrl,
+            loginContext: entry.loginContext,
+            conversationPathPrefix: entry.conversationPathPrefix,
+            hubBaseUrl: entry.hubBaseUrl,
+            token: entry.token,
+        };
+    }
+    if (res.status === "invalid") {
+        // Neither --target nor --api-url given, so this is the implicit/no-flag
+        // path — warn (don't throw) so a broken registry file doesn't silently
+        // swallow itself while the CLI quietly falls back to env/localhost.
+        logWarn(`Agent-targets registry at ${res.path} is invalid: ${res.message}. Falling back to env/localhost.`);
+    }
+    // No target/api-url given and no usable registry: preserve the old
+    // `mesh artifacts get` no-flag behavior — never throw here.
+    const fallbackUrl = process.env.AGENT_API_URL || process.env.API_URL || "http://localhost:8787";
+    return { apiBaseUrl: stripSlash(fallbackUrl), loginContext: opts.context || DEFAULT_AUTH_CONTEXT };
+}
+async function authHeaders(target) {
+    if (target.token)
+        return { Authorization: `Bearer ${target.token}` };
+    const ctx = target.loginContext || DEFAULT_AUTH_CONTEXT;
+    const token = await getValidToken(ctx);
+    if (token)
+        return { Authorization: `Bearer ${token}` };
+    if (LOCAL_URL_RE.test(target.apiBaseUrl))
+        return { "X-Forwarded-User": "dev-user", "X-Forwarded-Email": "dev@localhost" };
+    throw new TargetResolutionError(`No valid credentials for context "${ctx}". Run: mesh login ${ctx}`);
+}
+/**
+ * Fetch an agent-api path on the resolved target, with auth. Caller checks
+ * status.
+ *
+ * `redirect: "manual"` is deliberate: an unauthenticated `/v1` call against a
+ * deployed agent 302s to Zitadel. With the default `redirect: "follow"`,
+ * fetch follows it and returns a `200` HTML login page — `describeHttpError`'s
+ * auth branch never fires and the caller sees a raw JSON-parse error instead
+ * of auth guidance. With `"manual"`, the redirect surfaces as a Response with
+ * `type: "opaqueredirect"` (status 0), which `describeHttpError` already maps
+ * to the "auth did not reach the agent" message.
+ */
+export async function agentApiFetch(target, apiPath) {
+    const headers = await authHeaders(target);
+    return fetch(`${target.apiBaseUrl}${apiPath}`, { headers, redirect: "manual" });
+}
+const NETWORK_ERROR_PATTERN = /ECONNREFUSED|fetch failed|ENOTFOUND|EAI_AGAIN/;
+/**
+ * Turn a thrown fetch error into local-vs-remote-aware guidance. A bare
+ * `ECONNREFUSED`/`fetch failed` (also `ENOTFOUND`/`EAI_AGAIN`) means
+ * something different depending on the target: against a LOCAL apiBaseUrl it
+ * almost always means the local `mesh dev` agent API isn't running; against
+ * a REMOTE one it means a down host, a DNS typo, a dropped VPN/tailscale
+ * connection, or (occasionally) an auth redirect that the fetch layer
+ * couldn't follow. Only actual network throws get this treatment — every
+ * other error (including ones `describeHttpError` already produced) passes
+ * through unchanged so callers can log it without double guidance.
+ */
+export function describeNetworkError(err, target) {
+    const message = err instanceof Error ? err.message : String(err);
+    if (!NETWORK_ERROR_PATTERN.test(message))
+        return message;
+    if (LOCAL_URL_RE.test(target.apiBaseUrl)) {
+        return "Is the agent API running? Start it with: mesh dev";
+    }
+    const loginContext = target.loginContext ?? DEFAULT_AUTH_CONTEXT;
+    return (`Couldn't reach ${target.apiBaseUrl} — check the URL/VPN/tailscale, ` +
+        `or \`mesh login ${loginContext}\` if it's an auth redirect.`);
+}
+/**
+ * Shared, target-aware renderer for a non-ok agent-api response. Used by
+ * both `mesh conversations` (list/show/artifacts) and `mesh artifacts get`
+ * so there is exactly one place that turns an HTTP failure into human
+ * guidance — no more dev-oriented "restart the API process" advice, no more
+ * a second parallel renderer for `show`'s 503 special-case.
+ *
+ * `ctx.id` (a conversation id, when the caller has one) enables the
+ * `mesh temporal recover-conversation <id>` hint on a `conversation_unavailable`
+ * 503 and is echoed in the 404 message for context.
+ *
+ * Response shapes are verified against
+ * `packages/agent-sdk/src/agent-api/server.ts` — do not re-infer:
+ *  - 404 → `{ error: "conversation not found", conversationId }`.
+ *  - 503 conversation_unavailable → `{ error: "conversation_unavailable",
+ *    conversationId, detail: "<text>" }` — human text is under `detail`,
+ *    NOT `message`.
+ */
+export async function describeHttpError(res, target, ctx) {
+    const isRedirect = res.redirected || res.type === "opaqueredirect" || res.status === 302;
+    if (res.status === 401 || res.status === 403 || isRedirect) {
+        const loginContext = target.loginContext ?? DEFAULT_AUTH_CONTEXT;
+        return `auth did not reach the agent — run \`mesh login ${loginContext}\``;
+    }
+    if (res.status === 404) {
+        const idPart = ctx?.id ? ` (${ctx.id})` : "";
+        return `conversation/artifact not found${idPart}, or not owned by this identity — run \`mesh conversations list\` to see valid ids.`;
+    }
+    const bodyText = await res.text();
+    if (res.status === 503) {
+        try {
+            const parsed = JSON.parse(bodyText);
+            if (parsed.error === "conversation_unavailable") {
+                const message = parsed.detail ?? bodyText;
+                const recoverHint = ctx?.id ? `\ntry: mesh temporal recover-conversation ${ctx.id}` : "";
+                return `${message}${recoverHint}`;
+            }
+        }
+        catch {
+            // Not JSON, or not the shape we expect — fall through to the generic message.
+        }
+    }
+    return `agent-api error ${res.status}: ${bodyText || res.statusText} (${target.apiBaseUrl})`;
+}
+//# sourceMappingURL=agent-api-client.js.map

package/dist/src/commands/agent-api-client.js.map

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

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

@@ -0,0 +1,13 @@
+/**
+ * mesh artifacts — manage workflow artifacts from AI agent conversations
+ *
+ * Commands:
+ *   mesh artifacts get <ref>  Download artifact files to local directory
+ *
+ * Ref format: <conversationId>:<artifactId>
+ *   - Full:    mesh artifacts get conv-abc123:workflow-artifact
+ *   - Short:   mesh artifacts get conv-abc123          (defaults to "workflow-artifact")
+ */
+import { Command } from "commander";
+export declare function registerArtifactsCommands(program: Command): void;
+//# sourceMappingURL=artifacts.d.ts.map

package/dist/src/commands/artifacts.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"artifacts.d.ts","sourceRoot":"","sources":["../../../src/commands/artifacts.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AA0HpC,wBAAgB,yBAAyB,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CAqDhE"}

package/dist/src/commands/artifacts.js

@@ -0,0 +1,140 @@
+/**
+ * mesh artifacts — manage workflow artifacts from AI agent conversations
+ *
+ * Commands:
+ *   mesh artifacts get <ref>  Download artifact files to local directory
+ *
+ * Ref format: <conversationId>:<artifactId>
+ *   - Full:    mesh artifacts get conv-abc123:workflow-artifact
+ *   - Short:   mesh artifacts get conv-abc123          (defaults to "workflow-artifact")
+ */
+import * as fs from "fs";
+import * as path from "path";
+import { logError, logInfo, logSuccess, logWarn } from "../utils/log.js";
+import { agentApiFetch, describeHttpError, describeNetworkError, resolveTarget } from "./agent-api-client.js";
+const DEFAULT_ARTIFACT_ID = "workflow-artifact";
+/**
+ * Parse an artifact ref: "conversationId:artifactId" or just "conversationId".
+ */
+function parseRef(ref) {
+    const colonIdx = ref.indexOf(":");
+    if (colonIdx === -1) {
+        return { conversationId: ref, artifactId: DEFAULT_ARTIFACT_ID };
+    }
+    return {
+        conversationId: ref.slice(0, colonIdx),
+        artifactId: ref.slice(colonIdx + 1),
+    };
+}
+const DEFAULT_AUTH_CONTEXT = "mesh.dev";
+async function fetchExportBundle(target, conversationId, artifactId) {
+    const apiPath = `/v1/conversations/${encodeURIComponent(conversationId)}/artifacts/${encodeURIComponent(artifactId)}/export`;
+    const response = await agentApiFetch(target, apiPath);
+    if (!response.ok) {
+        throw new Error(await describeHttpError(response, target, { id: conversationId }));
+    }
+    return (await response.json());
+}
+async function getArtifact(ref, options, target) {
+    const { conversationId, artifactId } = parseRef(ref);
+    logInfo(`Fetching ${conversationId}:${artifactId} from ${target.apiBaseUrl}…`);
+    const bundle = await fetchExportBundle(target, conversationId, artifactId);
+    // Determine output directory
+    const outputDir = options.output
+        ?? path.join("workflows", bundle.primaryWorkflow);
+    // Create directory
+    fs.mkdirSync(outputDir, { recursive: true });
+    let filesWritten = 0;
+    // Write workflow source files
+    for (const file of bundle.files) {
+        const filePath = path.join(outputDir, file.filename);
+        fs.writeFileSync(filePath, file.code, "utf-8");
+        logSuccess(`  ${file.filename}`);
+        filesWritten++;
+    }
+    // Write README.md from overview
+    if (bundle.overview) {
+        const readmePath = path.join(outputDir, "README.md");
+        fs.writeFileSync(readmePath, bundle.overview, "utf-8");
+        logSuccess(`  README.md`);
+        filesWritten++;
+    }
+    // Write IR as JSON — always present, essential for IR-only artifacts
+    // (from update_workflow) that have no source files.
+    if (bundle.ir) {
+        const irPath = path.join(outputDir, "workflow-ir.json");
+        fs.writeFileSync(irPath, JSON.stringify(bundle.ir, null, 2), "utf-8");
+        logSuccess(`  workflow-ir.json`);
+        filesWritten++;
+    }
+    // Write metadata file (conversation ref, IR for tooling)
+    const metaPath = path.join(outputDir, ".workflow-meta.json");
+    const meta = {
+        conversationId: bundle.conversationId,
+        artifactId,
+        primaryWorkflow: bundle.primaryWorkflow,
+        exportedAt: bundle.exportedAt,
+        files: bundle.files.map((f) => f.filename),
+    };
+    fs.writeFileSync(metaPath, JSON.stringify(meta, null, 2), "utf-8");
+    console.log();
+    logSuccess(`Exported ${filesWritten} files to ${outputDir}/`);
+    if (bundle.files.length > 1) {
+        const primary = bundle.files.find((f) => f.name === bundle.primaryWorkflow);
+        if (primary) {
+            logInfo(`Entry point: ${primary.filename}`);
+        }
+    }
+    logInfo(`Ref: ${conversationId}:${artifactId}`);
+}
+export function registerArtifactsCommands(program) {
+    const artifacts = program
+        .command("artifacts")
+        .description("Manage workflow artifacts from AI agent conversations");
+    artifacts
+        .command("get <ref>")
+        .description("Download artifact files from an agent conversation\n\n" +
+        "Ref format: <conversationId>:<artifactId>\n" +
+        `  Short form uses default artifactId "${DEFAULT_ARTIFACT_ID}"`)
+        .option("-o, --output <dir>", "Output directory (default: workflows/<workflowName>)")
+        .option("--target <name>", "Named agent target from the agent-targets registry")
+        .option("--api-url <url>", "Agent API URL (overrides --target; ad-hoc, no registry lookup)")
+        .option("--context <ctx>", `Zitadel auth context, used with --api-url (default: ${DEFAULT_AUTH_CONTEXT})`)
+        .action(async (ref, opts) => {
+        // Resolved outside the try so a network-error catch below can give
+        // local-vs-remote-aware guidance (`describeNetworkError` needs the
+        // target). If resolution itself throws (bad --target), there's no
+        // target to reason about — just report the resolution error.
+        let target;
+        try {
+            target = resolveTarget(opts);
+        }
+        catch (error) {
+            logError(error instanceof Error ? error.message : String(error));
+            process.exitCode = 1;
+            return;
+        }
+        try {
+            await getArtifact(ref, opts, target);
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            logError(message);
+            // `describeHttpError` covers every HTTP-level failure mode (auth,
+            // not-found, 503, generic) with target-aware messages already baked
+            // into the thrown message, so it round-trips through here as `hint
+            // === message` and is not re-logged. Only a genuine network throw
+            // (ECONNREFUSED/"fetch failed"/ENOTFOUND/EAI_AGAIN) — nothing
+            // listening at apiBaseUrl, a down host, a DNS typo, a dropped
+            // VPN/tailscale connection — gets guidance here, and it differs for
+            // a local vs. remote target (see `describeNetworkError`).
+            const hint = describeNetworkError(error, target);
+            if (hint !== message) {
+                logWarn(hint);
+                logWarn("Or specify the URL: mesh artifacts get <ref> --api-url https://your-agent-api.example.com");
+            }
+            process.exitCode = 1;
+        }
+    });
+}
+//# sourceMappingURL=artifacts.js.map

package/dist/src/commands/artifacts.js.map

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

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

@@ -0,0 +1,45 @@
+/**
+ * mesh cluster access — `mesh kubectl` / `mesh logs` / `mesh exec` against a
+ * deployed app's EKS cluster, authenticated as the app's Zitadel deployer role
+ * (MESH-2060).
+ *
+ * Reuses exactly what `mesh dev` already does internally: assume the app's
+ * deployer role, build a session kubeconfig from the platform `eks` SSM export
+ * (`aws eks get-token` — needs neither `eks:DescribeCluster` nor a readable
+ * `~/.kube/config`, which macOS TCC blocks for non-FDA shells), and shell out to
+ * kubectl with `KUBECONFIG` set.
+ *
+ * The deployer role's cluster RBAC is namespace-scoped to the tenant's
+ * namespaces (verified live: the `<tenant>-<env>-deployers` group grants
+ * pods/log/exec read in the app's namespace), so every command defaults to the
+ * app's own namespace and callers can still `-n <other>` within the tenant.
+ */
+import { Command } from "commander";
+import { type EnsureKubeconfigFailure } from "../utils/kubeconfig.js";
+/**
+ * Render the "couldn't resolve the EKS cluster" failure with the parameter
+ * tried and the real exception. The pre-MESH-2515 message guessed "you have
+ * SSM read access" at every failure — which sent three investigations after a
+ * permission that was never missing when the actual cause was the wrong
+ * platform name in the SSM path.
+ */
+export declare function clusterResolveErrorMessage(platformName: string, platformEnv: string, failure?: EnsureKubeconfigFailure): string;
+/**
+ * Whether the user already scoped the namespace. Deliberately only detects the
+ * split forms (`-n foo`, `--namespace foo`, `--namespace=foo`, `-A`), NOT the
+ * smashed short form `-nfoo`: our default `-n <ns>` is PREPENDED, and kubectl's
+ * pflag lets the later (user-supplied) `-nfoo` win, so a missed detection here is
+ * harmless. Do not "fix" this into an append — that would let our default win
+ * over the user's intent.
+ */
+export declare function hasNamespaceFlag(args: string[]): boolean;
+/**
+ * Translate an ergonomic log/exec target into kubectl selector args.
+ *  - `deployment/x` / `pod/x` (contains `/`) → passed through
+ *  - `k=v` (contains `=`)                    → label selector `-l k=v`
+ *  - bare `<service>`                        → `-l app=<service>` (the reliable
+ *    per-service label; deployment names == service names)
+ */
+export declare function targetToSelector(target: string): string[];
+export declare function registerClusterCommands(program: Command): void;
+//# sourceMappingURL=cluster.d.ts.map

package/dist/src/commands/cluster.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cluster.d.ts","sourceRoot":"","sources":["../../../src/commands/cluster.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAGH,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAUpC,OAAO,EAGL,KAAK,uBAAuB,EAC7B,MAAM,wBAAwB,CAAC;AAwGhC;;;;;;GAMG;AACH,wBAAgB,0BAA0B,CACxC,YAAY,EAAE,MAAM,EACpB,WAAW,EAAE,MAAM,EACnB,OAAO,CAAC,EAAE,uBAAuB,GAChC,MAAM,CAiBR;AASD;;;;;;;GAOG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CAExD;AA+BD;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,CAIzD;AAED,wBAAgB,uBAAuB,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CA2F9D"}