@intentius/chant-lexicon-k8s 0.17.0 → 0.18.0

package/dist/integrity.json

@@ -1,7 +1,7 @@
 {
   "algorithm": "sha256",
   "artifacts": {
-    "manifest.json": "b73d03d86640f02553298a0c5ba1274bbff9dbbadc4ad47a660f1f37d4c28019",
+    "manifest.json": "e5e92d6151af7a608284b708614aa867dad5d1cc2ef7b53d02234188953fb55f",
     "meta.json": "560e496dee251a4fcc249373e50b7f16b5ee563ac8f9c832343a56f62bcfb656",
     "types/index.d.ts": "3cba22f6b907ebcbad3efded303cb21ba82fb5b8ac0ec41883fee6c84f0895ee",
     "rules/argo-appset-single-project.ts": "afa9f310753aa2d475f35012b13135b2dfaebed2a35d44edbe185ebc07673674",
@@ -50,5 +50,5 @@
     "skills/chant-k8s-aks.md": "e18f0e2b055f72cd7a37deaf258d7027c2d4d3e286e8fd4975b27a1f981a3ad9",
     "skills/chant-k8s-argo.md": "b1a0b826559d8c5033a479c5781efaf650320f0aee4419d8841170bd3393cea5"
   },
-  "composite": "c7f22fdb62408197b52e6c20d7ce299eef14971bdfd5b15191bddcd2af76a745"
+  "composite": "775b5fbf8890c053e071209666333a08ba40a5f613d11c35753914cf49d7e7d4"
 }

package/dist/manifest.json

@@ -1,6 +1,6 @@
 {
   "name": "k8s",
-  "version": "0.17.0",
+  "version": "0.18.0",
   "chantVersion": ">=0.1.0",
   "namespace": "K8s",
   "intrinsics": [],

package/dist/op/activities/argo.d.ts

@@ -0,0 +1,57 @@
+/**
+ * waitForArgoSync — block until an Argo CD Application reports
+ * `health=Healthy && sync=Synced`.
+ *
+ * This activity is intentionally **dependency-light**: though it now lives in the
+ * k8s lexicon (#809), it must not import the lexicon's generated Argo CRD types —
+ * its signature is primitives-only (app name / namespace / server), so a Temporal
+ * worker can load it without pulling in the declarable surface. It reads the
+ * Application's status either via `kubectl get application` (default) or the Argo
+ * CD REST API (when `server` is given), so an Op can gate procedural steps on a
+ * declarative apply that Argo owns.
+ */
+export interface WaitForArgoSyncArgs {
+    /** Argo Application name. */
+    appName: string;
+    /** Namespace the Application object lives in (default "argocd"). */
+    namespace?: string;
+    /**
+     * Argo CD API base URL (e.g. https://argocd.example.com). When set, status is
+     * read from the REST API instead of kubectl. Pass `authToken` with it.
+     */
+    server?: string;
+    /** Bearer token for the Argo CD REST API (used with `server`). */
+    authToken?: string;
+    /** Skip TLS verification for the REST API (default false). */
+    insecure?: boolean;
+    /** kubectl context (used when `server` is not set). */
+    context?: string;
+    /** Poll interval in ms (default 15000). Heartbeats every poll. */
+    intervalMs?: number;
+}
+/** The two status fields the activity gates on. */
+export interface ArgoAppStatus {
+    /** Application health: Healthy | Progressing | Degraded | Missing | Suspended | Unknown. */
+    health: string;
+    /** Sync status: Synced | OutOfSync | Unknown. */
+    sync: string;
+}
+/** Pluggable status reader — overridden in tests with a faked Argo API. */
+export type ArgoStatusFetcher = (args: WaitForArgoSyncArgs, signal?: AbortSignal) => Promise<ArgoAppStatus>;
+/** Error thrown when the Application reaches a terminal unhealthy state. */
+export declare class ArgoSyncFailedError extends Error {
+    constructor(message: string);
+}
+/** Default fetcher: REST API when `server` is set, else kubectl. */
+export declare const defaultArgoStatusFetcher: ArgoStatusFetcher;
+/**
+ * Poll until the Application is Healthy and Synced. Throws
+ * `ArgoSyncFailedError` if it reaches a terminal unhealthy state (Degraded /
+ * Missing). Heartbeats every poll so the `argoSync` profile's 60s heartbeat
+ * timeout never trips.
+ *
+ * @param fetcher injectable status reader (defaults to kubectl/REST). Tests pass
+ *   a fake to drive Healthy/Progressing/Degraded transitions.
+ */
+export declare function waitForArgoSync(args: WaitForArgoSyncArgs, signal?: AbortSignal, fetcher?: ArgoStatusFetcher): Promise<ArgoAppStatus>;
+//# sourceMappingURL=argo.d.ts.map

package/dist/op/activities/argo.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"argo.d.ts","sourceRoot":"","sources":["../../../src/op/activities/argo.ts"],"names":[],"mappings":"AAMA;;;;;;;;;;;GAWG;AAEH,MAAM,WAAW,mBAAmB;IAClC,6BAA6B;IAC7B,OAAO,EAAE,MAAM,CAAC;IAChB,oEAAoE;IACpE,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;;;OAGG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,kEAAkE;IAClE,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,8DAA8D;IAC9D,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,uDAAuD;IACvD,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,kEAAkE;IAClE,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,mDAAmD;AACnD,MAAM,WAAW,aAAa;IAC5B,4FAA4F;IAC5F,MAAM,EAAE,MAAM,CAAC;IACf,iDAAiD;IACjD,IAAI,EAAE,MAAM,CAAC;CACd;AAED,2EAA2E;AAC3E,MAAM,MAAM,iBAAiB,GAAG,CAC9B,IAAI,EAAE,mBAAmB,EACzB,MAAM,CAAC,EAAE,WAAW,KACjB,OAAO,CAAC,aAAa,CAAC,CAAC;AAK5B,4EAA4E;AAC5E,qBAAa,mBAAoB,SAAQ,KAAK;gBAChC,OAAO,EAAE,MAAM;CAI5B;AA4CD,oEAAoE;AACpE,eAAO,MAAM,wBAAwB,EAAE,iBACkC,CAAC;AAE1E;;;;;;;;GAQG;AACH,wBAAsB,eAAe,CACnC,IAAI,EAAE,mBAAmB,EACzB,MAAM,CAAC,EAAE,WAAW,EACpB,OAAO,GAAE,iBAA4C,GACpD,OAAO,CAAC,aAAa,CAAC,CAuBxB"}

package/dist/op/activities/index.d.ts

@@ -0,0 +1,20 @@
+/**
+ * k8s Op activities — resolved by the core activity registry when a project's
+ * `chant.config.ts` lists the `k8s` lexicon. Relocated from the temporal lexicon
+ * (#809) so Kubernetes-facing imperative activities live with their product:
+ *   - kubectlApply — `kubectl apply` a rendered manifest
+ *   - k3dUp / k3dDown — boot/tear down a local k3d cluster
+ *   - waitForArgoSync — block until an Argo CD Application is Healthy && Synced
+ *
+ * The step builders (kubectlApply, k3dUp, k3dDown) stay in core, re-exported from
+ * the temporal Op-authoring barrel like the other core builders. Each activity is
+ * dependency-light — it shells out to a CLI and does not import the k8s declarable
+ * surface — so a Temporal worker loads it cheaply.
+ */
+export { kubectlApply } from "./kubectl.js";
+export type { KubectlApplyArgs } from "./kubectl.js";
+export { k3dUp, k3dDown, k3dUpCommand, k3dDownCommand, k3dExistsCommand } from "./k3d.js";
+export type { K3dUpArgs, K3dDownArgs } from "./k3d.js";
+export { waitForArgoSync, defaultArgoStatusFetcher, ArgoSyncFailedError } from "./argo.js";
+export type { WaitForArgoSyncArgs, ArgoAppStatus, ArgoStatusFetcher } from "./argo.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/op/activities/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/op/activities/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AACH,OAAO,EAAE,YAAY,EAAE,MAAM,WAAW,CAAC;AACzC,YAAY,EAAE,gBAAgB,EAAE,MAAM,WAAW,CAAC;AAElD,OAAO,EAAE,KAAK,EAAE,OAAO,EAAE,YAAY,EAAE,cAAc,EAAE,gBAAgB,EAAE,MAAM,OAAO,CAAC;AACvF,YAAY,EAAE,SAAS,EAAE,WAAW,EAAE,MAAM,OAAO,CAAC;AAEpD,OAAO,EAAE,eAAe,EAAE,wBAAwB,EAAE,mBAAmB,EAAE,MAAM,QAAQ,CAAC;AACxF,YAAY,EAAE,mBAAmB,EAAE,aAAa,EAAE,iBAAiB,EAAE,MAAM,QAAQ,CAAC"}

package/dist/op/activities/k3d.d.ts

@@ -0,0 +1,44 @@
+export interface K3dUpArgs {
+    /** Cluster name (`k3d cluster create <name>`). */
+    name: string;
+    /** Number of server (control-plane) nodes. */
+    servers?: number;
+    /** Number of agent (worker) nodes. */
+    agents?: number;
+    /** k3s image, e.g. `rancher/k3s:v1.31.4-k3s1`. */
+    image?: string;
+    /** Port mappings, e.g. `["8080:80@loadbalancer"]`. */
+    ports?: string[];
+    /** Create a managed local registry with this name (`--registry-create`). */
+    registryCreate?: string;
+    /** Path to a k3d config file (`--config`). */
+    configFile?: string;
+    /** Readiness timeout for `--wait`. Default: `120s`. */
+    timeout?: string;
+}
+export interface K3dDownArgs {
+    /** Cluster name to delete. */
+    name: string;
+}
+/** `k3d cluster list <name> --no-headers` — non-empty stdout means the cluster exists. */
+export declare function k3dExistsCommand(name: string): string;
+/**
+ * Build the `k3d cluster create` command. k3d merges the new cluster into the
+ * default kubeconfig and switches context by default, so no extra flags are
+ * needed for the manifests to be `kubectl apply`-able afterward.
+ */
+export declare function k3dUpCommand(args: K3dUpArgs): string;
+/** Build the `k3d cluster delete` command. */
+export declare function k3dDownCommand(args: K3dDownArgs): string;
+/**
+ * Create a local k3d cluster (vanilla Kubernetes in Docker). Idempotent: if a
+ * cluster of the same name already exists it is left as-is. Uses longInfra
+ * profile — 20m timeout, heartbeat every 15s (creation may pull the k3s image).
+ */
+export declare function k3dUp(args: K3dUpArgs, signal?: AbortSignal): Promise<void>;
+/**
+ * Delete a local k3d cluster. Uses fastIdempotent profile — 5m timeout.
+ * `k3d cluster delete` is a no-op success when the cluster is already gone.
+ */
+export declare function k3dDown(args: K3dDownArgs, signal?: AbortSignal): Promise<void>;
+//# sourceMappingURL=k3d.d.ts.map

package/dist/op/activities/k3d.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"k3d.d.ts","sourceRoot":"","sources":["../../../src/op/activities/k3d.ts"],"names":[],"mappings":"AAMA,MAAM,WAAW,SAAS;IACxB,kDAAkD;IAClD,IAAI,EAAE,MAAM,CAAC;IACb,8CAA8C;IAC9C,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,sCAAsC;IACtC,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,kDAAkD;IAClD,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,sDAAsD;IACtD,KAAK,CAAC,EAAE,MAAM,EAAE,CAAC;IACjB,4EAA4E;IAC5E,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,8CAA8C;IAC9C,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,uDAAuD;IACvD,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,WAAW;IAC1B,8BAA8B;IAC9B,IAAI,EAAE,MAAM,CAAC;CACd;AAED,0FAA0F;AAC1F,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAErD;AAED;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,SAAS,GAAG,MAAM,CAWpD;AAED,8CAA8C;AAC9C,wBAAgB,cAAc,CAAC,IAAI,EAAE,WAAW,GAAG,MAAM,CAExD;AAED;;;;GAIG;AACH,wBAAsB,KAAK,CAAC,IAAI,EAAE,SAAS,EAAE,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC,CAsBhF;AAED;;;GAGG;AACH,wBAAsB,OAAO,CAAC,IAAI,EAAE,WAAW,EAAE,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC,CAIpF"}

package/dist/op/activities/kubectl.d.ts

@@ -0,0 +1,11 @@
+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 15s.
+ */
+export declare function kubectlApply(args: KubectlApplyArgs, signal?: AbortSignal): Promise<void>;
+//# sourceMappingURL=kubectl.d.ts.map

package/dist/op/activities/kubectl.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"kubectl.d.ts","sourceRoot":"","sources":["../../../src/op/activities/kubectl.ts"],"names":[],"mappings":"AAMA,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,EAAE,MAAM,CAAC;IACjB,6DAA6D;IAC7D,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED;;;GAGG;AACH,wBAAsB,YAAY,CAAC,IAAI,EAAE,gBAAgB,EAAE,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC,CAgB9F"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@intentius/chant-lexicon-k8s",
-  "version": "0.17.0",
+  "version": "0.18.0",
   "description": "Kubernetes lexicon for chant — declarative IaC in TypeScript",
   "license": "Apache-2.0",
   "homepage": "https://intentius.io/chant",
@@ -49,6 +49,11 @@
       "types": "./dist/lint/post-synth/index.d.ts",
       "default": "./src/lint/post-synth/index.ts"
     },
+    "./op/activities": {
+      "development": "./src/op/activities/index.ts",
+      "types": "./dist/op/activities/index.d.ts",
+      "default": "./src/op/activities/index.ts"
+    },
     "./manifest": "./dist/manifest.json",
     "./meta": "./dist/meta.json",
     "./types": "./dist/types/index.d.ts"
@@ -70,6 +75,6 @@
     "typescript": "^5.9.3"
   },
   "peerDependencies": {
-    "@intentius/chant": "^0.17.0"
+    "@intentius/chant": "^0.18.0"
   }
 }

package/src/op/activities/argo.test.ts

@@ -0,0 +1,80 @@
+import { describe, test, expect } from "vitest";
+import {
+  waitForArgoSync,
+  ArgoSyncFailedError,
+  type ArgoAppStatus,
+  type ArgoStatusFetcher,
+} from "./argo";
+// Activity profiles live centrally in the temporal lexicon (loadProfiles reads
+// them there); argoSync marks ArgoSyncFailedError non-retryable for this activity.
+import { TEMPORAL_ACTIVITY_PROFILES } from "@intentius/chant-lexicon-temporal/config";
+
+/** A fetcher that returns a scripted sequence of statuses, repeating the last. */
+function scriptedFetcher(sequence: ArgoAppStatus[]): ArgoStatusFetcher {
+  let i = 0;
+  return async () => {
+    const status = sequence[Math.min(i, sequence.length - 1)];
+    i++;
+    return status;
+  };
+}
+
+const fast = { appName: "guestbook", intervalMs: 0 };
+
+describe("waitForArgoSync", () => {
+  test("resolves once the Application is Healthy and Synced", async () => {
+    const fetcher = scriptedFetcher([
+      { health: "Progressing", sync: "OutOfSync" },
+      { health: "Progressing", sync: "Synced" },
+      { health: "Healthy", sync: "Synced" },
+    ]);
+    const result = await waitForArgoSync(fast, undefined, fetcher);
+    expect(result).toEqual({ health: "Healthy", sync: "Synced" });
+  });
+
+  test("does not resolve while Synced but still Progressing", async () => {
+    // First Healthy+Synced read is the third; ensure it polls past the
+    // Progressing reads rather than returning early.
+    let calls = 0;
+    const fetcher: ArgoStatusFetcher = async () => {
+      calls++;
+      if (calls < 3) return { health: "Progressing", sync: "Synced" };
+      return { health: "Healthy", sync: "Synced" };
+    };
+    await waitForArgoSync(fast, undefined, fetcher);
+    expect(calls).toBe(3);
+  });
+
+  test("throws ArgoSyncFailedError when the Application is Degraded", async () => {
+    const fetcher = scriptedFetcher([{ health: "Degraded", sync: "Synced" }]);
+    await expect(waitForArgoSync(fast, undefined, fetcher)).rejects.toBeInstanceOf(
+      ArgoSyncFailedError,
+    );
+  });
+
+  test("throws ArgoSyncFailedError when the Application is Missing", async () => {
+    const fetcher = scriptedFetcher([{ health: "Missing", sync: "OutOfSync" }]);
+    await expect(waitForArgoSync(fast, undefined, fetcher)).rejects.toThrow(/Missing/);
+  });
+
+  test("honors an aborted signal", async () => {
+    const controller = new AbortController();
+    controller.abort();
+    const fetcher = scriptedFetcher([{ health: "Progressing", sync: "OutOfSync" }]);
+    await expect(waitForArgoSync(fast, controller.signal, fetcher)).rejects.toThrow(/aborted/);
+  });
+});
+
+describe("argoSync profile", () => {
+  test("is exported with a long timeout and 60s heartbeat", () => {
+    const p = TEMPORAL_ACTIVITY_PROFILES.argoSync;
+    expect(p.startToCloseTimeout).toBe("30m");
+    expect(p.heartbeatTimeout).toBe("60s");
+  });
+
+  test("treats ArgoSyncFailedError as non-retryable", () => {
+    expect(TEMPORAL_ACTIVITY_PROFILES.argoSync.retry?.nonRetryableErrorTypes).toContain(
+      "ArgoSyncFailedError",
+    );
+  });
+});

package/src/op/activities/argo.ts

@@ -0,0 +1,147 @@
+import { exec } from "node:child_process";
+import { promisify } from "node:util";
+import { safeHeartbeat, sleep } from "@intentius/chant/op";
+
+const execAsync = promisify(exec);
+
+/**
+ * waitForArgoSync — block until an Argo CD Application reports
+ * `health=Healthy && sync=Synced`.
+ *
+ * This activity is intentionally **dependency-light**: though it now lives in the
+ * k8s lexicon (#809), it must not import the lexicon's generated Argo CRD types —
+ * its signature is primitives-only (app name / namespace / server), so a Temporal
+ * worker can load it without pulling in the declarable surface. It reads the
+ * Application's status either via `kubectl get application` (default) or the Argo
+ * CD REST API (when `server` is given), so an Op can gate procedural steps on a
+ * declarative apply that Argo owns.
+ */
+
+export interface WaitForArgoSyncArgs {
+  /** Argo Application name. */
+  appName: string;
+  /** Namespace the Application object lives in (default "argocd"). */
+  namespace?: string;
+  /**
+   * Argo CD API base URL (e.g. https://argocd.example.com). When set, status is
+   * read from the REST API instead of kubectl. Pass `authToken` with it.
+   */
+  server?: string;
+  /** Bearer token for the Argo CD REST API (used with `server`). */
+  authToken?: string;
+  /** Skip TLS verification for the REST API (default false). */
+  insecure?: boolean;
+  /** kubectl context (used when `server` is not set). */
+  context?: string;
+  /** Poll interval in ms (default 15000). Heartbeats every poll. */
+  intervalMs?: number;
+}
+
+/** The two status fields the activity gates on. */
+export interface ArgoAppStatus {
+  /** Application health: Healthy | Progressing | Degraded | Missing | Suspended | Unknown. */
+  health: string;
+  /** Sync status: Synced | OutOfSync | Unknown. */
+  sync: string;
+}
+
+/** Pluggable status reader — overridden in tests with a faked Argo API. */
+export type ArgoStatusFetcher = (
+  args: WaitForArgoSyncArgs,
+  signal?: AbortSignal,
+) => Promise<ArgoAppStatus>;
+
+/** Health states that will never become Healthy without intervention. */
+const TERMINAL_UNHEALTHY = new Set(["Degraded", "Missing"]);
+
+/** Error thrown when the Application reaches a terminal unhealthy state. */
+export class ArgoSyncFailedError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "ArgoSyncFailedError";
+  }
+}
+
+/** Read status via the Argo CD REST API. */
+async function fetchViaApi(args: WaitForArgoSyncArgs, signal?: AbortSignal): Promise<ArgoAppStatus> {
+  const base = args.server!.replace(/\/$/, "");
+  const ns = args.namespace ?? "argocd";
+  const url = `${base}/api/v1/applications/${encodeURIComponent(args.appName)}?appNamespace=${encodeURIComponent(ns)}`;
+  const headers: Record<string, string> = { Accept: "application/json" };
+  if (args.authToken) headers.Authorization = `Bearer ${args.authToken}`;
+
+  // Honor `insecure` without importing https Agent types — Node respects this
+  // env toggle for the duration of the call.
+  const prevTlsReject = process.env.NODE_TLS_REJECT_UNAUTHORIZED;
+  if (args.insecure) process.env.NODE_TLS_REJECT_UNAUTHORIZED = "0";
+  try {
+    const res = await fetch(url, { headers, signal });
+    if (!res.ok) {
+      throw new Error(`Argo CD API returned ${res.status} for application "${args.appName}"`);
+    }
+    const body = (await res.json()) as { status?: { health?: { status?: string }; sync?: { status?: string } } };
+    return {
+      health: body.status?.health?.status ?? "Unknown",
+      sync: body.status?.sync?.status ?? "Unknown",
+    };
+  } finally {
+    if (args.insecure) {
+      if (prevTlsReject === undefined) delete process.env.NODE_TLS_REJECT_UNAUTHORIZED;
+      else process.env.NODE_TLS_REJECT_UNAUTHORIZED = prevTlsReject;
+    }
+  }
+}
+
+/** Read status via `kubectl get application -o json`. */
+async function fetchViaKubectl(args: WaitForArgoSyncArgs, signal?: AbortSignal): Promise<ArgoAppStatus> {
+  const ns = args.namespace ?? "argocd";
+  const ctx = args.context ? `--context ${args.context}` : "";
+  const cmd =
+    `kubectl get application ${args.appName} -n ${ns} ${ctx} ` +
+    `-o jsonpath='{.status.health.status}|{.status.sync.status}'`;
+  const { stdout } = await execAsync(cmd, { signal });
+  const [health = "Unknown", sync = "Unknown"] = stdout.trim().replace(/^'|'$/g, "").split("|");
+  return { health: health || "Unknown", sync: sync || "Unknown" };
+}
+
+/** Default fetcher: REST API when `server` is set, else kubectl. */
+export const defaultArgoStatusFetcher: ArgoStatusFetcher = (args, signal) =>
+  args.server ? fetchViaApi(args, signal) : fetchViaKubectl(args, signal);
+
+/**
+ * Poll until the Application is Healthy and Synced. Throws
+ * `ArgoSyncFailedError` if it reaches a terminal unhealthy state (Degraded /
+ * Missing). Heartbeats every poll so the `argoSync` profile's 60s heartbeat
+ * timeout never trips.
+ *
+ * @param fetcher injectable status reader (defaults to kubectl/REST). Tests pass
+ *   a fake to drive Healthy/Progressing/Degraded transitions.
+ */
+export async function waitForArgoSync(
+  args: WaitForArgoSyncArgs,
+  signal?: AbortSignal,
+  fetcher: ArgoStatusFetcher = defaultArgoStatusFetcher,
+): Promise<ArgoAppStatus> {
+  const interval = args.intervalMs ?? 15_000;
+  let attempt = 0;
+
+  while (true) {
+    if (signal?.aborted) throw new Error("waitForArgoSync aborted");
+    attempt++;
+
+    const status = await fetcher(args, signal);
+    safeHeartbeat({ step: "waitForArgoSync", app: args.appName, attempt, ...status });
+
+    if (TERMINAL_UNHEALTHY.has(status.health)) {
+      throw new ArgoSyncFailedError(
+        `Argo Application "${args.appName}" is ${status.health} (sync=${status.sync}) — it will not become Healthy without intervention.`,
+      );
+    }
+
+    if (status.health === "Healthy" && status.sync === "Synced") {
+      return status;
+    }
+
+    await sleep(interval, signal);
+  }
+}

package/src/op/activities/index.ts

@@ -0,0 +1,21 @@
+/**
+ * k8s Op activities — resolved by the core activity registry when a project's
+ * `chant.config.ts` lists the `k8s` lexicon. Relocated from the temporal lexicon
+ * (#809) so Kubernetes-facing imperative activities live with their product:
+ *   - kubectlApply — `kubectl apply` a rendered manifest
+ *   - k3dUp / k3dDown — boot/tear down a local k3d cluster
+ *   - waitForArgoSync — block until an Argo CD Application is Healthy && Synced
+ *
+ * The step builders (kubectlApply, k3dUp, k3dDown) stay in core, re-exported from
+ * the temporal Op-authoring barrel like the other core builders. Each activity is
+ * dependency-light — it shells out to a CLI and does not import the k8s declarable
+ * surface — so a Temporal worker loads it cheaply.
+ */
+export { kubectlApply } from "./kubectl";
+export type { KubectlApplyArgs } from "./kubectl";
+
+export { k3dUp, k3dDown, k3dUpCommand, k3dDownCommand, k3dExistsCommand } from "./k3d";
+export type { K3dUpArgs, K3dDownArgs } from "./k3d";
+
+export { waitForArgoSync, defaultArgoStatusFetcher, ArgoSyncFailedError } from "./argo";
+export type { WaitForArgoSyncArgs, ArgoAppStatus, ArgoStatusFetcher } from "./argo";

package/src/op/activities/k3d.test.ts

@@ -0,0 +1,68 @@
+import { describe, test, expect } from "vitest";
+import { k3dUpCommand, k3dDownCommand, k3dExistsCommand } from "./k3d";
+
+describe("k3dUpCommand (#704)", () => {
+  test("minimal — name only, defaults to --wait with a 120s timeout", () => {
+    const cmd = k3dUpCommand({ name: "chant-local" });
+    expect(cmd).toBe("k3d cluster create chant-local --wait --timeout 120s");
+  });
+
+  test("servers/agents/image flags", () => {
+    const cmd = k3dUpCommand({
+      name: "dev",
+      servers: 1,
+      agents: 2,
+      image: "rancher/k3s:v1.31.4-k3s1",
+    });
+    expect(cmd).toContain("--servers 1");
+    expect(cmd).toContain("--agents 2");
+    expect(cmd).toContain("--image rancher/k3s:v1.31.4-k3s1");
+  });
+
+  test("each port becomes a quoted -p flag", () => {
+    const cmd = k3dUpCommand({
+      name: "dev",
+      ports: ["8080:80@loadbalancer", "8443:443@loadbalancer"],
+    });
+    expect(cmd).toContain('-p "8080:80@loadbalancer"');
+    expect(cmd).toContain('-p "8443:443@loadbalancer"');
+  });
+
+  test("registry and config file", () => {
+    const cmd = k3dUpCommand({
+      name: "dev",
+      registryCreate: "chant-registry",
+      configFile: "k3d.yaml",
+    });
+    expect(cmd).toContain("--registry-create chant-registry");
+    expect(cmd).toContain("--config k3d.yaml");
+  });
+
+  test("custom timeout overrides the default", () => {
+    const cmd = k3dUpCommand({ name: "dev", timeout: "300s" });
+    expect(cmd).toContain("--timeout 300s");
+    expect(cmd).not.toContain("120s");
+  });
+
+  test("zero servers is emitted (not dropped as falsy)", () => {
+    // servers: 0 is unusual but must round-trip — guarded by `!== undefined`.
+    const cmd = k3dUpCommand({ name: "dev", servers: 0 });
+    expect(cmd).toContain("--servers 0");
+  });
+});
+
+describe("k3dDownCommand (#704)", () => {
+  test("deletes the named cluster", () => {
+    expect(k3dDownCommand({ name: "chant-local" })).toBe(
+      "k3d cluster delete chant-local",
+    );
+  });
+});
+
+describe("k3dExistsCommand (#704)", () => {
+  test("lists a single cluster with no headers for an emptiness check", () => {
+    expect(k3dExistsCommand("chant-local")).toBe(
+      "k3d cluster list chant-local --no-headers",
+    );
+  });
+});

package/src/op/activities/k3d.ts

@@ -0,0 +1,96 @@
+import { exec } from "node:child_process";
+import { promisify } from "node:util";
+import { safeHeartbeat } from "@intentius/chant/op";
+
+const execAsync = promisify(exec);
+
+export interface K3dUpArgs {
+  /** Cluster name (`k3d cluster create <name>`). */
+  name: string;
+  /** Number of server (control-plane) nodes. */
+  servers?: number;
+  /** Number of agent (worker) nodes. */
+  agents?: number;
+  /** k3s image, e.g. `rancher/k3s:v1.31.4-k3s1`. */
+  image?: string;
+  /** Port mappings, e.g. `["8080:80@loadbalancer"]`. */
+  ports?: string[];
+  /** Create a managed local registry with this name (`--registry-create`). */
+  registryCreate?: string;
+  /** Path to a k3d config file (`--config`). */
+  configFile?: string;
+  /** Readiness timeout for `--wait`. Default: `120s`. */
+  timeout?: string;
+}
+
+export interface K3dDownArgs {
+  /** Cluster name to delete. */
+  name: string;
+}
+
+/** `k3d cluster list <name> --no-headers` — non-empty stdout means the cluster exists. */
+export function k3dExistsCommand(name: string): string {
+  return `k3d cluster list ${name} --no-headers`;
+}
+
+/**
+ * Build the `k3d cluster create` command. k3d merges the new cluster into the
+ * default kubeconfig and switches context by default, so no extra flags are
+ * needed for the manifests to be `kubectl apply`-able afterward.
+ */
+export function k3dUpCommand(args: K3dUpArgs): string {
+  const parts = ["k3d", "cluster", "create", args.name];
+  if (args.servers !== undefined) parts.push(`--servers ${args.servers}`);
+  if (args.agents !== undefined) parts.push(`--agents ${args.agents}`);
+  if (args.image) parts.push(`--image ${args.image}`);
+  for (const p of args.ports ?? []) parts.push(`-p "${p}"`);
+  if (args.registryCreate) parts.push(`--registry-create ${args.registryCreate}`);
+  if (args.configFile) parts.push(`--config ${args.configFile}`);
+  parts.push("--wait");
+  parts.push(`--timeout ${args.timeout ?? "120s"}`);
+  return parts.join(" ");
+}
+
+/** Build the `k3d cluster delete` command. */
+export function k3dDownCommand(args: K3dDownArgs): string {
+  return `k3d cluster delete ${args.name}`;
+}
+
+/**
+ * Create a local k3d cluster (vanilla Kubernetes in Docker). Idempotent: if a
+ * cluster of the same name already exists it is left as-is. Uses longInfra
+ * profile — 20m timeout, heartbeat every 15s (creation may pull the k3s image).
+ */
+export async function k3dUp(args: K3dUpArgs, signal?: AbortSignal): Promise<void> {
+  try {
+    const { stdout } = await execAsync(k3dExistsCommand(args.name), { signal });
+    if (stdout.trim()) {
+      console.log(`k3d cluster "${args.name}" already exists — skipping create`);
+      return;
+    }
+  } catch {
+    // `cluster list` errors when the cluster is absent — fall through to create.
+  }
+
+  const heartbeatInterval = setInterval(() => {
+    safeHeartbeat({ step: "k3d cluster create", cluster: args.name });
+  }, 15_000);
+
+  try {
+    const { stdout, stderr } = await execAsync(k3dUpCommand(args), { signal });
+    if (stdout) console.log(stdout);
+    if (stderr) console.error(stderr);
+  } finally {
+    clearInterval(heartbeatInterval);
+  }
+}
+
+/**
+ * Delete a local k3d cluster. Uses fastIdempotent profile — 5m timeout.
+ * `k3d cluster delete` is a no-op success when the cluster is already gone.
+ */
+export async function k3dDown(args: K3dDownArgs, signal?: AbortSignal): Promise<void> {
+  const { stdout, stderr } = await execAsync(k3dDownCommand(args), { signal });
+  if (stdout) console.log(stdout);
+  if (stderr) console.error(stderr);
+}

package/src/op/activities/kubectl.ts

@@ -0,0 +1,33 @@
+import { exec } from "node:child_process";
+import { promisify } from "node:util";
+import { safeHeartbeat } from "@intentius/chant/op";
+
+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 15s.
+ */
+export async function kubectlApply(args: KubectlApplyArgs, signal?: AbortSignal): Promise<void> {
+  const ctx = args.context ? `--context ${args.context}` : "";
+  const heartbeatInterval = setInterval(() => {
+    safeHeartbeat({ step: "kubectl apply", manifest: args.manifest });
+  }, 15_000);
+
+  try {
+    const { stdout, stderr } = await execAsync(
+      `kubectl apply -f ${args.manifest} ${ctx} --wait=true`,
+      { signal },
+    );
+    if (stdout) console.log(stdout);
+    if (stderr) console.error(stderr);
+  } finally {
+    clearInterval(heartbeatInterval);
+  }
+}