@intentius/chant-lexicon-temporal 0.1.5 → 0.1.8

package/src/describe-resources.ts

@@ -0,0 +1,300 @@
+/**
+ * Live introspection of a Temporal cluster — implements the
+ * LexiconPlugin.describeResources() contract for the temporal lexicon.
+ *
+ * Connects to the cluster identified by the chant config profile that
+ * matches the current environment (falls back to defaultProfile), then lists:
+ *   - Namespaces        via workflowService.listNamespaces
+ *   - SearchAttributes  via operatorService.listSearchAttributes (per namespace)
+ *   - Schedules         via scheduleClient.list (per namespace)
+ *
+ * Results are keyed by server-side identifier (e.g. "namespace/prod",
+ * "searchAttribute/prod/Project", "schedule/prod/daily-report"). Mapping back
+ * to chant entity names is a separate concern (would need entity props passed
+ * through the plugin contract).
+ */
+
+import { loadChantConfig } from "@intentius/chant/config";
+import {
+  loadTemporalClient,
+  connectionOptions,
+  resolveProfile,
+  type WorkerProfile,
+} from "@intentius/chant/cli/handlers/run-client";
+import type { ResourceMetadata } from "@intentius/chant/lexicon";
+
+interface NamespaceListResponse {
+  namespaces?: Array<{
+    namespaceInfo?: {
+      name?: string;
+      state?: number | string;
+      description?: string;
+      ownerEmail?: string;
+    } | null;
+    config?: {
+      workflowExecutionRetentionTtl?: { seconds?: number | bigint | { toNumber(): number } } | null;
+    } | null;
+    isGlobalNamespace?: boolean;
+  }>;
+  nextPageToken?: Uint8Array | null;
+}
+
+interface SearchAttributesResponse {
+  customAttributes?: Record<string, number | string> | null;
+  systemAttributes?: Record<string, number | string> | null;
+}
+
+interface ScheduleSummary {
+  scheduleId?: string;
+  spec?: { cronExpressions?: string[] } | null;
+  action?: { type?: string; workflowType?: string } | null;
+  state?: { paused?: boolean; note?: string } | null;
+}
+
+interface RichConnection {
+  workflowService: {
+    listNamespaces(req: { pageSize?: number; nextPageToken?: Uint8Array }): Promise<NamespaceListResponse>;
+  };
+  operatorService: {
+    listSearchAttributes(req: { namespace: string }): Promise<SearchAttributesResponse>;
+  };
+  close?(): Promise<void>;
+}
+
+interface RichClient {
+  scheduleClient: {
+    list(opts: { namespace?: string }): AsyncIterable<ScheduleSummary>;
+  };
+}
+
+interface RichClientModule {
+  Connection: { connect(opts: Record<string, unknown>): Promise<RichConnection> };
+  Client: new (opts: { connection: RichConnection; namespace?: string }) => RichClient;
+}
+
+const NAMESPACE_STATE_NAMES: Record<number, string> = {
+  0: "UNSPECIFIED",
+  1: "REGISTERED",
+  2: "DEPRECATED",
+  3: "DELETED",
+};
+
+const VALUE_TYPE_NAMES: Record<number, string> = {
+  0: "Unspecified",
+  1: "Text",
+  2: "Keyword",
+  3: "Int",
+  4: "Double",
+  5: "Bool",
+  6: "Datetime",
+  7: "KeywordList",
+};
+
+function namespaceStateToString(state: number | string | undefined): string {
+  if (typeof state === "string") return state;
+  if (typeof state === "number") return NAMESPACE_STATE_NAMES[state] ?? `STATE_${state}`;
+  return "UNKNOWN";
+}
+
+function valueTypeToString(t: number | string | undefined): string {
+  if (typeof t === "string") return t;
+  if (typeof t === "number") return VALUE_TYPE_NAMES[t] ?? `TYPE_${t}`;
+  return "Unknown";
+}
+
+function retentionTtlToSeconds(
+  ttl: { seconds?: number | bigint | { toNumber(): number } } | null | undefined,
+): number | undefined {
+  if (!ttl?.seconds) return undefined;
+  const s = ttl.seconds;
+  if (typeof s === "number") return s;
+  if (typeof s === "bigint") return Number(s);
+  if (typeof s === "object" && "toNumber" in s) return s.toNumber();
+  return undefined;
+}
+
+function resolveProfileForEnv(
+  config: Record<string, unknown>,
+  environment: string,
+): WorkerProfile {
+  // Try env-named profile first, fall back to defaultProfile.
+  try {
+    return resolveProfile(config, environment);
+  } catch {
+    return resolveProfile(config);
+  }
+}
+
+async function paginateNamespaces(connection: RichConnection): Promise<NonNullable<NamespaceListResponse["namespaces"]>> {
+  const all: NonNullable<NamespaceListResponse["namespaces"]> = [];
+  let nextPageToken: Uint8Array | undefined;
+  do {
+    const res = await connection.workflowService.listNamespaces({
+      pageSize: 100,
+      ...(nextPageToken && { nextPageToken }),
+    });
+    if (res.namespaces) all.push(...res.namespaces);
+    nextPageToken = res.nextPageToken && res.nextPageToken.length > 0 ? res.nextPageToken : undefined;
+  } while (nextPageToken);
+  return all;
+}
+
+/**
+ * Build reverse-lookup maps from server-side identifiers back to chant
+ * entity names, using the `entities` map passed via the plugin contract.
+ *
+ * Mapping rules:
+ *   - Namespace:       props.name              -> entity name
+ *   - SearchAttribute: <ns>/<props.name>       -> entity name
+ *   - Schedule:        <ns>/<props.scheduleId> -> entity name
+ *
+ * For SearchAttribute, the namespace defaults to the *first declared
+ * Temporal::Namespace's name* if the entity itself doesn't pin one — this
+ * matches the serializer's behavior when emitting registration commands.
+ */
+function buildEntityIndex(
+  entities: Map<string, { entityType: string; props: Record<string, unknown> }>,
+): {
+  namespaceByName: Map<string, string>;
+  searchAttrByKey: Map<string, string>;
+  scheduleByKey: Map<string, string>;
+  defaultNamespace?: string;
+} {
+  const namespaceByName = new Map<string, string>();
+  const searchAttrByKey = new Map<string, string>();
+  const scheduleByKey = new Map<string, string>();
+  let defaultNamespace: string | undefined;
+
+  for (const [entityName, { entityType, props }] of entities) {
+    if (entityType === "Temporal::Namespace") {
+      const nsName = (props.name as string) || "";
+      if (nsName) {
+        namespaceByName.set(nsName, entityName);
+        if (!defaultNamespace) defaultNamespace = nsName;
+      }
+    }
+  }
+
+  for (const [entityName, { entityType, props }] of entities) {
+    if (entityType === "Temporal::SearchAttribute") {
+      const attrName = (props.name as string) || "";
+      const ns = (props.namespace as string) || defaultNamespace || "";
+      if (attrName && ns) searchAttrByKey.set(`${ns}/${attrName}`, entityName);
+    } else if (entityType === "Temporal::Schedule") {
+      const scheduleId = (props.scheduleId as string) || "";
+      const ns = (props.namespace as string) || defaultNamespace || "";
+      if (scheduleId && ns) scheduleByKey.set(`${ns}/${scheduleId}`, entityName);
+    }
+  }
+
+  return { namespaceByName, searchAttrByKey, scheduleByKey, defaultNamespace };
+}
+
+export async function describeResources(options: {
+  environment: string;
+  buildOutput: string;
+  entityNames: string[];
+  entities: Map<string, { entityType: string; props: Record<string, unknown> }>;
+}): Promise<Record<string, ResourceMetadata>> {
+  const { config } = await loadChantConfig(process.cwd());
+  const profile = resolveProfileForEnv(config as Record<string, unknown>, options.environment);
+
+  const mod = (await loadTemporalClient()) as unknown as RichClientModule;
+  const connection = await mod.Connection.connect(connectionOptions(profile));
+  const client = new mod.Client({ connection });
+
+  const idx = buildEntityIndex(options.entities);
+  const result: Record<string, ResourceMetadata> = {};
+
+  // Map a server-side identifier to a chant entity name when possible;
+  // otherwise fall back to the server-side prefixed key (orphan).
+  const keyForNamespace = (name: string): string =>
+    idx.namespaceByName.get(name) ?? `namespace/${name}`;
+  const keyForSearchAttr = (ns: string, attr: string): string =>
+    idx.searchAttrByKey.get(`${ns}/${attr}`) ?? `searchAttribute/${ns}/${attr}`;
+  const keyForSchedule = (ns: string, scheduleId: string): string =>
+    idx.scheduleByKey.get(`${ns}/${scheduleId}`) ?? `schedule/${ns}/${scheduleId}`;
+
+  try {
+    const namespaces = await paginateNamespaces(connection);
+
+    for (const ns of namespaces) {
+      const name = ns.namespaceInfo?.name;
+      if (!name) continue;
+
+      result[keyForNamespace(name)] = {
+        type: "Temporal::Namespace",
+        physicalId: name,
+        status: namespaceStateToString(ns.namespaceInfo?.state),
+        attributes: pruneUndefined({
+          description: ns.namespaceInfo?.description,
+          ownerEmail: ns.namespaceInfo?.ownerEmail,
+          isGlobalNamespace: ns.isGlobalNamespace,
+          retentionSeconds: retentionTtlToSeconds(ns.config?.workflowExecutionRetentionTtl ?? undefined),
+        }),
+      };
+
+      // SearchAttributes — failure on one namespace shouldn't abort others.
+      try {
+        const sa = await connection.operatorService.listSearchAttributes({ namespace: name });
+        for (const [attrName, valueType] of Object.entries(sa.customAttributes ?? {})) {
+          result[keyForSearchAttr(name, attrName)] = {
+            type: "Temporal::SearchAttribute",
+            physicalId: `${name}/${attrName}`,
+            status: "REGISTERED",
+            attributes: {
+              valueType: valueTypeToString(valueType),
+              namespace: name,
+            },
+          };
+        }
+      } catch (err) {
+        // eslint-disable-next-line no-console
+        console.warn(
+          `[temporal] failed to list search attributes for namespace "${name}": ${
+            err instanceof Error ? err.message : String(err)
+          }`,
+        );
+      }
+
+      // Schedules — same fail-soft policy.
+      try {
+        for await (const s of client.scheduleClient.list({ namespace: name })) {
+          if (!s.scheduleId) continue;
+          result[keyForSchedule(name, s.scheduleId)] = {
+            type: "Temporal::Schedule",
+            physicalId: `${name}/${s.scheduleId}`,
+            status: s.state?.paused ? "PAUSED" : "ACTIVE",
+            attributes: pruneUndefined({
+              namespace: name,
+              workflowType: s.action?.workflowType,
+              cronExpressions: s.spec?.cronExpressions,
+              note: s.state?.note,
+            }),
+          };
+        }
+      } catch (err) {
+        // eslint-disable-next-line no-console
+        console.warn(
+          `[temporal] failed to list schedules for namespace "${name}": ${
+            err instanceof Error ? err.message : String(err)
+          }`,
+        );
+      }
+    }
+  } finally {
+    if (typeof connection.close === "function") {
+      try { await connection.close(); } catch { /* best-effort */ }
+    }
+  }
+
+  return result;
+}
+
+function pruneUndefined<T extends Record<string, unknown>>(obj: T): Record<string, unknown> {
+  const out: Record<string, unknown> = {};
+  for (const [k, v] of Object.entries(obj)) {
+    if (v !== undefined) out[k] = v;
+  }
+  return out;
+}

package/src/index.ts

@@ -27,3 +27,22 @@ export { TemporalDevStack } from "./composites/dev-stack";
 export type { TemporalDevStackConfig, TemporalDevStackResources } from "./composites/dev-stack";
 export { TemporalCloudStack } from "./composites/cloud-stack";
 export type { TemporalCloudStackConfig, TemporalCloudStackResources } from "./composites/cloud-stack";
+export { WatchOp } from "./composites/watch-op";
+export type { WatchOpConfig, WatchOpResources } from "./composites/watch-op";
+
+// Op builders (re-exported from core for single-import convenience)
+export {
+  Op,
+  phase,
+  activity,
+  gate,
+  build,
+  kubectlApply,
+  helmInstall,
+  waitForStack,
+  gitlabPipeline,
+  stateSnapshot,
+  shell,
+  teardown,
+} from "@intentius/chant/op";
+export type { OpConfig, PhaseDefinition, StepDefinition, ActivityStep, GateStep } from "@intentius/chant/op";

package/src/op/activities/build.ts

@@ -0,0 +1,23 @@
+import { exec } from "node:child_process";
+import { promisify } from "node:util";
+
+const execAsync = promisify(exec);
+
+export interface ChantBuildArgs {
+  path: string;
+  /** Optional extra env vars to pass to the build command. */
+  env?: Record<string, string>;
+}
+
+/**
+ * Run `npm run build` in the given project directory.
+ * Uses fastIdempotent profile — 5m timeout, 3 retries.
+ */
+export async function chantBuild(args: ChantBuildArgs): Promise<void> {
+  const { stdout, stderr } = await execAsync("npm run build", {
+    cwd: args.path,
+    env: { ...process.env, ...args.env },
+  });
+  if (stdout) console.log(stdout);
+  if (stderr) console.error(stderr);
+}

package/src/op/activities/gitlab.ts

@@ -0,0 +1,56 @@
+import { exec } from "node:child_process";
+import { promisify } from "node:util";
+import { Context } from "@temporalio/activity";
+
+const execAsync = promisify(exec);
+
+export interface GitlabPipelineArgs {
+  /** GitLab project name or path (e.g. "group/project"). */
+  name: string;
+  /** Git ref to run the pipeline on. Default: current branch. */
+  ref?: string;
+  /** Poll interval in ms. Default: 30000. */
+  intervalMs?: number;
+}
+
+/**
+ * Trigger a GitLab CI pipeline and wait for it to complete successfully.
+ * Requires `glab` CLI authenticated in the environment.
+ * Uses longInfra profile — 20m timeout, heartbeat every 60s.
+ */
+export async function gitlabPipeline(args: GitlabPipelineArgs): Promise<void> {
+  const ref = args.ref ?? "HEAD";
+  const interval = args.intervalMs ?? 30_000;
+
+  // Trigger
+  const { stdout: triggerOut } = await execAsync(
+    `glab ci run --project ${args.name} --ref ${ref}`,
+  );
+  console.log(triggerOut);
+
+  // Poll status
+  let attempt = 0;
+  while (true) {
+    attempt++;
+    Context.current().heartbeat({ step: "gitlabPipeline", project: args.name, attempt });
+
+    const { stdout } = await execAsync(
+      `glab ci status --project ${args.name} --format json`,
+    );
+
+    let status: string | undefined;
+    try {
+      const parsed = JSON.parse(stdout) as { status?: string }[];
+      status = parsed[0]?.status;
+    } catch {
+      // Non-JSON output — keep polling
+    }
+
+    if (status === "success") return;
+    if (status === "failed" || status === "canceled") {
+      throw new Error(`GitLab pipeline for ${args.name} ended with status: ${status}`);
+    }
+
+    await new Promise((r) => setTimeout(r, interval));
+  }
+}

package/src/op/activities/helm.ts

@@ -0,0 +1,41 @@
+import { exec } from "node:child_process";
+import { promisify } from "node:util";
+import { Context } from "@temporalio/activity";
+
+const execAsync = promisify(exec);
+
+export interface HelmInstallArgs {
+  /** Helm release name. */
+  name: string;
+  /** Chart reference (local path or `repo/chart`). */
+  chart: string;
+  /** Path to a values file. */
+  values?: string;
+  /** Kubernetes namespace. */
+  namespace?: string;
+  /** Additional --set arguments. */
+  set?: Record<string, string>;
+}
+
+/**
+ * Run `helm upgrade --install <name> <chart>`.
+ * Uses longInfra profile — 20m timeout, heartbeat every 60s.
+ */
+export async function helmInstall(args: HelmInstallArgs): Promise<void> {
+  const parts = ["helm", "upgrade", "--install", "--wait", args.name, args.chart];
+  if (args.namespace) parts.push("--namespace", args.namespace, "--create-namespace");
+  if (args.values) parts.push("-f", args.values);
+  for (const [k, v] of Object.entries(args.set ?? {})) parts.push("--set", `${k}=${v}`);
+
+  const heartbeatInterval = setInterval(() => {
+    Context.current().heartbeat({ step: "helm install", release: args.name });
+  }, 15_000);
+
+  try {
+    const { stdout, stderr } = await execAsync(parts.join(" "));
+    if (stdout) console.log(stdout);
+    if (stderr) console.error(stderr);
+  } finally {
+    clearInterval(heartbeatInterval);
+  }
+}

package/src/op/activities/index.ts

@@ -0,0 +1,23 @@
+export { chantBuild } from "./build";
+export type { ChantBuildArgs } from "./build";
+
+export { kubectlApply } from "./kubectl";
+export type { KubectlApplyArgs } from "./kubectl";
+
+export { helmInstall } from "./helm";
+export type { HelmInstallArgs } from "./helm";
+
+export { waitForStack } from "./wait";
+export type { WaitForStackArgs } from "./wait";
+
+export { gitlabPipeline } from "./gitlab";
+export type { GitlabPipelineArgs } from "./gitlab";
+
+export { shellCmd } from "./shell";
+export type { ShellCmdArgs } from "./shell";
+
+export { stateSnapshot, stateDiff } from "./state";
+export type { StateSnapshotArgs, StateDiffArgs, StateDiffResult } from "./state";
+
+export { chantTeardown } from "./teardown";
+export type { ChantTeardownArgs } from "./teardown";

package/src/op/activities/kubectl.ts

@@ -0,0 +1,32 @@
+import { exec } from "node:child_process";
+import { promisify } from "node:util";
+import { Context } from "@temporalio/activity";
+
+const execAsync = promisify(exec);
+
+export interface KubectlApplyArgs {
+  manifest: string;
+  /** kubectl context name. Uses current context if omitted. */
+  context?: string;
+}
+
+/**
+ * Run `kubectl apply -f <manifest>`.
+ * Uses longInfra profile — 20m timeout, heartbeat every 60s.
+ */
+export async function kubectlApply(args: KubectlApplyArgs): Promise<void> {
+  const ctx = args.context ? `--context ${args.context}` : "";
+  const heartbeatInterval = setInterval(() => {
+    Context.current().heartbeat({ step: "kubectl apply", manifest: args.manifest });
+  }, 15_000);
+
+  try {
+    const { stdout, stderr } = await execAsync(
+      `kubectl apply -f ${args.manifest} ${ctx} --wait=true`,
+    );
+    if (stdout) console.log(stdout);
+    if (stderr) console.error(stderr);
+  } finally {
+    clearInterval(heartbeatInterval);
+  }
+}

package/src/op/activities/shell.ts

@@ -0,0 +1,25 @@
+import { exec } from "node:child_process";
+import { promisify } from "node:util";
+
+const execAsync = promisify(exec);
+
+export interface ShellCmdArgs {
+  cmd: string;
+  /** Additional environment variables. */
+  env?: Record<string, string>;
+  /** Working directory. Default: process.cwd(). */
+  cwd?: string;
+}
+
+/**
+ * Run an arbitrary shell command.
+ * Uses fastIdempotent profile — 5m timeout, 3 retries.
+ */
+export async function shellCmd(args: ShellCmdArgs): Promise<string> {
+  const { stdout, stderr } = await execAsync(args.cmd, {
+    cwd: args.cwd,
+    env: { ...process.env, ...args.env },
+  });
+  if (stderr) console.error(stderr);
+  return stdout.trim();
+}

package/src/op/activities/state.ts

@@ -0,0 +1,85 @@
+import { exec } from "node:child_process";
+import { promisify } from "node:util";
+
+const execAsync = promisify(exec);
+
+export interface StateSnapshotArgs {
+  /** Environment name (e.g. "dev", "staging", "prod"). */
+  env: string;
+}
+
+/**
+ * Take a chant state snapshot for the given environment.
+ * Uses fastIdempotent profile — 5m timeout, 3 retries.
+ */
+export async function stateSnapshot(args: StateSnapshotArgs): Promise<void> {
+  const { stdout, stderr } = await execAsync(`chant state snapshot ${args.env}`);
+  if (stdout) console.log(stdout);
+  if (stderr) console.error(stderr);
+}
+
+export interface StateDiffArgs {
+  /** Environment name (e.g. "dev", "staging", "prod"). */
+  env: string;
+  /**
+   * When true, run `chant state diff <env> --live` (queries cloud APIs).
+   * When false (default), run digest-only diff against the last snapshot.
+   */
+  live?: boolean;
+}
+
+export interface StateDiffResult {
+  /** Combined stdout + stderr from the chant command. */
+  output: string;
+  /** Process exit code (0 = success). */
+  exitCode: number;
+  /**
+   * True when the diff output contains any drift indicators
+   * (MISSING / ORPHAN / DRIFTED / DISAPPEARED section headers from
+   * `chant state diff --live`).
+   */
+  drifted: boolean;
+}
+
+/**
+ * Section headers emitted by `chant state diff --live` that indicate a
+ * non-empty drift category. See packages/core/src/cli/handlers/state.ts.
+ */
+const DRIFT_HEADERS = [
+  "MISSING",
+  "ORPHAN",
+  "DISAPPEARED",
+  "DRIFTED",
+  "ARTIFACTS ADDED",
+  "ARTIFACTS REMOVED",
+  "ARTIFACTS CHANGED",
+];
+
+function detectDrift(output: string): boolean {
+  return DRIFT_HEADERS.some((h) => output.includes(`${h} (`) || output.includes(`\n${h}`));
+}
+
+/**
+ * Run `chant state diff <env>` and return the output + structured drift
+ * flag. Read-only; intended for use inside watch/observation workflows.
+ * Uses fastIdempotent profile.
+ *
+ * The `drifted` field is computed by scanning the output for any of the
+ * MISSING / ORPHAN / DRIFTED / DISAPPEARED section headers documented in
+ * cli/state.mdx. Pair with `outcomeAttribute: { name: "Drift", from: "drifted" }`
+ * on a WatchOp activity step to surface drift as a workflow search attribute.
+ */
+export async function stateDiff(args: StateDiffArgs): Promise<StateDiffResult> {
+  const liveFlag = args.live ? " --live" : "";
+  try {
+    const { stdout, stderr } = await execAsync(`chant state diff ${args.env}${liveFlag}`);
+    const output = `${stdout}${stderr}`.trim();
+    if (output) console.log(output);
+    return { output, exitCode: 0, drifted: detectDrift(output) };
+  } catch (err) {
+    const e = err as { code?: number; stdout?: string; stderr?: string };
+    const output = `${e.stdout ?? ""}${e.stderr ?? ""}`.trim();
+    if (output) console.error(output);
+    return { output, exitCode: e.code ?? 1, drifted: detectDrift(output) };
+  }
+}

package/src/op/activities/teardown.ts

@@ -0,0 +1,21 @@
+import { exec } from "node:child_process";
+import { promisify } from "node:util";
+
+const execAsync = promisify(exec);
+
+export interface ChantTeardownArgs {
+  /** Path to the chant project to tear down. */
+  path: string;
+}
+
+/**
+ * Run `chant teardown` in the given project path.
+ * Uses longInfra profile — 20m timeout, heartbeat every 60s.
+ */
+export async function chantTeardown(args: ChantTeardownArgs): Promise<void> {
+  const { stdout, stderr } = await execAsync("npm run teardown", {
+    cwd: args.path,
+  });
+  if (stdout) console.log(stdout);
+  if (stderr) console.error(stderr);
+}

package/src/op/activities/wait.ts

@@ -0,0 +1,52 @@
+import { exec } from "node:child_process";
+import { promisify } from "node:util";
+import { Context } from "@temporalio/activity";
+
+const execAsync = promisify(exec);
+
+export interface WaitForStackArgs {
+  /** Stack name — used to locate the kubectl deployment/statefulset to poll. */
+  name: string;
+  /** Kubernetes namespace. */
+  namespace?: string;
+  /** kubectl context. */
+  context?: string;
+  /** Poll interval in ms. Default: 10000. */
+  intervalMs?: number;
+}
+
+/**
+ * Poll until a Kubernetes Deployment or StatefulSet named `name` is fully rolled out.
+ * Uses k8sWait profile — 15m timeout, heartbeat every 60s.
+ */
+export async function waitForStack(args: WaitForStackArgs): Promise<void> {
+  const ns = args.namespace ? `-n ${args.namespace}` : "";
+  const ctx = args.context ? `--context ${args.context}` : "";
+  const interval = args.intervalMs ?? 10_000;
+  let attempt = 0;
+
+  while (true) {
+    attempt++;
+    Context.current().heartbeat({ step: "waitForStack", stack: args.name, attempt });
+
+    try {
+      await execAsync(
+        `kubectl rollout status deployment/${args.name} ${ns} ${ctx} --timeout=30s`,
+      );
+      return;
+    } catch {
+      // Not ready yet — wait and retry
+    }
+
+    try {
+      await execAsync(
+        `kubectl rollout status statefulset/${args.name} ${ns} ${ctx} --timeout=30s`,
+      );
+      return;
+    } catch {
+      // Not ready yet
+    }
+
+    await new Promise((r) => setTimeout(r, interval));
+  }
+}