@intentius/chant-lexicon-k8s 0.124.31 → 0.124.32

package/dist/op/activities/argo.js

@@ -0,0 +1,98 @@
+import { exec } from "node:child_process";
+import { promisify } from "node:util";
+import { readinessFor, waitForReady, ReadinessFailedError } from "./wait-for-ready.js";
+const execAsync = promisify(exec);
+/** Error thrown when the Application reaches a terminal unhealthy state. */
+export class ArgoSyncFailedError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "ArgoSyncFailedError";
+    }
+}
+/** Read status via the Argo CD REST API. */
+async function fetchViaApi(args, signal) {
+    const base = args.server.replace(/\/$/, "");
+    const ns = args.namespace ?? "argocd";
+    const url = `${base}/api/v1/applications/${encodeURIComponent(args.appName)}?appNamespace=${encodeURIComponent(ns)}`;
+    const headers = { 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());
+        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, signal) {
+    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 = (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).
+ *
+ * Delegates the poll loop and the ready/terminal evaluation to the
+ * generic `waitForReady` using the shared `argoproj.io/Application` readiness
+ * spec. The Argo `ArgoStatusFetcher` is adapted into a `ResourceFetcher` that
+ * shapes `{health, sync}` into the `status.health.status` / `status.sync.status`
+ * paths the spec reads — so the REST-API path is preserved.
+ *
+ * @param fetcher injectable status reader (defaults to kubectl/REST). Tests pass
+ *   a fake to drive Healthy/Progressing/Degraded transitions.
+ */
+export async function waitForArgoSync(args, signal, fetcher = defaultArgoStatusFetcher) {
+    const spec = readinessFor("argoproj.io", "Application");
+    // Adapt the Argo status fetcher into the object shape the spec's paths read.
+    const resourceFetcher = async (_a, s) => {
+        const status = await fetcher(args, s);
+        return { status: { health: { status: status.health }, sync: { status: status.sync } } };
+    };
+    try {
+        const obj = await waitForReady({
+            kind: "application",
+            name: args.appName,
+            namespace: args.namespace ?? "argocd",
+            group: "argoproj.io",
+            spec,
+            intervalMs: args.intervalMs ?? 15000,
+        }, signal, resourceFetcher);
+        const status = obj.status;
+        return { health: status.health.status, sync: status.sync.status };
+    }
+    catch (err) {
+        // Preserve the Argo-specific error type (the argoSync profile marks it
+        // non-retryable) while reusing the generic terminal detection.
+        if (err instanceof ReadinessFailedError) {
+            throw new ArgoSyncFailedError(`Argo Application "${args.appName}" reached a terminal unhealthy state (Degraded / Missing) — it will not become Healthy without intervention.`);
+        }
+        throw err;
+    }
+}

package/dist/op/activities/ensure-secret.js

@@ -0,0 +1,38 @@
+/**
+ * `ensureSecret` — the activity behind core's `ensureSecret(...)` op step
+ * builder (#1829), provided by the store's lexicon as that builder promises
+ * (#1830). Registered by name through the activity registry when a project's
+ * `chant.config.ts` lists the `k8s` lexicon, exactly like `kubectlApply`.
+ *
+ * All it does is connect (the same environment→cluster binding every k8s
+ * path uses), build the namespace-scoped store adapter, and run core's one
+ * materialization engine over it. The contract — present means done, never
+ * mint over an existing value, mismatches fail naming key names only, no
+ * output carries material — lives in core (`secret-materialization.ts`) and
+ * in the adapter (../../secret-store.ts), not here.
+ */
+import { ensureSecretMaterialization, } from "@intentius/chant/secret-materialization";
+import { defaultK8sConnector } from "../../api/connect.js";
+import { k8sSecretStore } from "../../secret-store.js";
+/**
+ * Ensure a `generated-once` Secret exists in the target cluster. Returns
+ * names only — see core's `EnsureSecretOutcome`.
+ */
+export async function ensureSecret(args, _signal, connect = defaultK8sConnector) {
+    const { client } = await connect({
+        ...(args.environment !== undefined ? { environment: args.environment } : {}),
+        ...(args.context !== undefined ? { context: args.context } : {}),
+        ...(args.cwd !== undefined ? { cwd: args.cwd } : {}),
+    });
+    const marker = args.stack
+        ? { stack: args.stack, ...(args.env ? { env: args.env } : {}) }
+        : undefined;
+    const store = k8sSecretStore(args.namespace ?? client.defaultNamespace, client, {
+        ...(marker ? { marker } : {}),
+    });
+    return ensureSecretMaterialization(store, {
+        name: args.name,
+        keys: args.keys,
+        ...(args.metadata ? { metadata: args.metadata } : {}),
+    });
+}

package/dist/op/activities/index.js

@@ -0,0 +1,51 @@
+/**
+ * k8s Op activities — resolved by the core activity registry when a project's
+ * `chant.config.ts` lists the `k8s` lexicon. Relocated from the hosting lexicon
+ * (#809) so Kubernetes-facing imperative activities live with their product:
+ *   - kubectlApply — server-side apply a rendered manifest (and, since chant
+ *     #1075, prune chant-owned objects it no longer declares; `applyManifest`
+ *     is the same work with a report of what it did, which is what core's
+ *     `nativeApply` dispatcher calls for a kubectl target)
+ *   - waitForArgoSync — block until an Argo CD Application is Healthy && Synced
+ *
+ * k3dUp / k3dDown moved again, to the k3d lexicon (chant #1410) — a lexicon
+ * owns its own product's activities, and k3d is its own product now. Projects
+ * using them list `k3d` in `lexicons`; loadActivities(["k3d"]) provides them.
+ *
+ * The step builders (kubectlApply, k3dUp, k3dDown) stay in core and reach
+ * authors through `@intentius/chant/op` 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 `loadActivities`
+ * (`packages/core/src/op/activity-registry.ts`), which imports this module at
+ * run time, pulls in nothing expensive.
+ */
+export { kubectlApply, applyManifest, readManifestDocuments } from "./kubectl.js";
+// Generated-once secret materialization (#1830) — the activity behind core's
+// `ensureSecret(...)` step builder (#1829). Read-then-write over the
+// namespace-scoped store adapter in ../../secret-store.ts; no output carries
+// secret material.
+export { ensureSecret } from "./ensure-secret.js";
+export { waitForArgoSync, defaultArgoStatusFetcher, ArgoSyncFailedError } from "./argo.js";
+export { waitForReady, defaultResourceFetcher, apiResourceFetcher, ReadinessFailedError, readinessFor, isReady, firstTerminal, DEFAULT_READINESS, READINESS_OVERRIDES, } from "./wait-for-ready.js";
+// Environment→cluster binding (chant #1100) — the same resolver
+// `describeResources` (the read path) uses. `kubectlApply` and `waitForReady`
+// above already accept an optional `context`; a workflow author who wants the
+// write path to target the environment's bound cluster (rather than an
+// ambient one, closing the read/write split) resolves it here and passes the
+// result through, e.g. `kubectlApply({ manifest, context: (await
+// resolveClusterTarget(config, environment, "k8s")).context })`. Re-exported
+// from core rather than duplicated so both paths agree on one source of
+// truth — see `lexicons/k8s/src/config.ts` for the config shape.
+export { resolveClusterTarget, ClusterBindingMismatchError } from "@intentius/chant/kubectl-context";
+// Effect-receipt activities (#2074): core's receipt seam (#1834) bound to
+// this lexicon's ConfigMap-backed store (../../receipt-store.ts), the same
+// way the aws lexicon binds its SSM store (#1835). Re-exported individually:
+// `receiptRead`/`receiptWrite` serve the `effect()` step's
+// read-compare-run-write, `receiptStaleness` serves WatchOp's read-only
+// staleness reporting.
+import { receiptActivities } from "@intentius/chant/op/receipt-store";
+import { k8sReceiptStore } from "../../receipt-store.js";
+const boundReceiptActivities = receiptActivities(k8sReceiptStore());
+export const receiptRead = boundReceiptActivities.receiptRead;
+export const receiptWrite = boundReceiptActivities.receiptWrite;
+export const receiptStaleness = boundReceiptActivities.receiptStaleness;

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

@@ -32,6 +32,7 @@
  */
 import type { K8sObject } from "@intentius/chant-k8s-client";
 import { type K8sConnector } from "../../api/connect.js";
+import { type FieldChange } from "./apply-diff.js";
 /**
  * How the apply treats chant-owned objects that are no longer declared. The
  * same three values `nativeApply` has always taken; `gated` differs from
@@ -149,6 +150,69 @@ export declare function resolveFieldManager(args: KubectlApplyArgs): Promise<str
  * reports the shell command it ran.
  */
 export declare function applyManifest(args: KubectlApplyArgs, signal?: AbortSignal, connect?: K8sConnector): Promise<ApplyManifestResult>;
+/** What a dry-run apply would do to one declared object (#3998). */
+export interface PlannedObject {
+    ref: AppliedRef;
+    /** `create` when no live object exists, `no-op` when the dry run equals it, `update` otherwise. */
+    action: "create" | "update" | "no-op";
+    /**
+     * For a create, the document as the apply sends it (ownership stamped).
+     * Not the dry-run result: the server can fill in values a dry run picks
+     * afresh each time (a Service's cluster IP), which would make the plan
+     * differ from itself.
+     */
+    object?: Record<string, unknown>;
+    /** The fields an update changes, live against the dry-run result, both normalized. */
+    changes: FieldChange[];
+    /**
+     * The API server rejected the dry run of a change to a live object because
+     * it changes an immutable field. The apply does not delete and recreate,
+     * so it would fail the same way. The server's message.
+     */
+    refused?: string;
+}
+/** What {@link planManifest} found. */
+export interface ManifestPlanResult {
+    fieldManager: string;
+    stack?: string;
+    objects: PlannedObject[];
+    /** What the apply's prune would delete: empty unless `deleteMode` deletes. */
+    deletes: AppliedRef[];
+    /** Owned, undeclared objects the prune keeps (#1830, #2074). */
+    retained: AppliedRef[];
+}
+/**
+ * Say what {@link applyManifest} would do, without changing anything (#3998).
+ *
+ * Every document is stamped and dry-run applied exactly as the apply sends
+ * it: the same field manager, `force: false`, and the same retake of a
+ * conflict chant has only with itself. The live object is read first and
+ * compared with the dry-run result through `./apply-diff.ts`, so a field the
+ * server defaults counts as unchanged when the live object already has it.
+ *
+ * An object in a namespace an earlier document of the same plan creates
+ * cannot be dry-run (the server answers 404, as the namespace was never
+ * persisted), so it plans as a create of the document as sent.
+ *
+ * Deletes come from the apply's own prune scope (`findOrphans`): marker
+ * scoped, in the namespaces the apply set touches, generated-once Secrets
+ * and effect receipts kept. They are found only when `deleteMode` is not
+ * `never`, as the apply prunes only then.
+ */
+export declare function planManifest(args: KubectlApplyArgs, signal?: AbortSignal, connect?: K8sConnector): Promise<ManifestPlanResult>;
+/** Where {@link readLiveObjects} reads, and which objects. */
+export interface ReadLiveObjectsArgs {
+    refs: AppliedRef[];
+    environment?: string;
+    context?: string;
+    cwd?: string;
+}
+/**
+ * Read each of `refs` as the cluster holds it now, `undefined` for one that
+ * does not exist (#3999). `kubectl-apply` reads the fields its step names as
+ * outputs from these.
+ */
+export declare function readLiveObjects(args: ReadLiveObjectsArgs, signal?: AbortSignal, connect?: K8sConnector): Promise<Array<Record<string, unknown> | undefined>>;
 /**
  * Apply every document in `args.manifest`.
  * Uses the longInfra profile: 20m timeout, three attempts backing off from 30s.

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

@@ -1 +1 @@
-{"version":3,"file":"kubectl.d.ts","sourceRoot":"","sources":["../../../src/op/activities/kubectl.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AAWH,OAAO,KAAK,EAAa,SAAS,EAAE,MAAM,6BAA6B,CAAC;AACxE,OAAO,EAAuB,KAAK,YAAY,EAAE,MAAM,mBAAmB,CAAC;AAM3E;;;;;GAKG;AACH,MAAM,MAAM,eAAe,GAAG,OAAO,GAAG,YAAY,GAAG,OAAO,CAAC;AAE/D,MAAM,WAAW,gBAAgB;IAC/B;;;;OAIG;IACH,QAAQ,EAAE,MAAM,CAAC;IACjB;;;;;;;OAOG;IACH,SAAS,CAAC,EAAE,SAAS,EAAE,CAAC;IACxB;;;;;OAKG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB;;;;OAIG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB;;;;OAIG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB;;;OAGG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;IACf;;;OAGG;IACH,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB;;;;OAIG;IACH,UAAU,CAAC,EAAE,eAAe,CAAC;IAC7B;;;;;;;OAOG;IACH,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,sFAAsF;IACtF,GAAG,CAAC,EAAE,MAAM,CAAC;CACd;AAED,oCAAoC;AACpC,MAAM,WAAW,UAAU;IACzB,UAAU,EAAE,MAAM,CAAC;IACnB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,sCAAsC;AACtC,MAAM,WAAW,mBAAmB;IAClC,qDAAqD;IACrD,YAAY,EAAE,MAAM,CAAC;IACrB,OAAO,EAAE,UAAU,EAAE,CAAC;IACtB,sFAAsF;IACtF,MAAM,EAAE,UAAU,EAAE,CAAC;IACrB;;;;;;;OAOG;IACH,QAAQ,CAAC,EAAE,UAAU,EAAE,CAAC;CACzB;AAED,+EAA+E;AAC/E,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,CAiB7E;AAED;;;;;;;;;;GAUG;AACH,wBAAsB,mBAAmB,CAAC,IAAI,EAAE,gBAAgB,GAAG,OAAO,CAAC,MAAM,CAAC,CAEjF;AAqHD;;;;;;;GAOG;AACH,wBAAsB,aAAa,CACjC,IAAI,EAAE,gBAAgB,EACtB,MAAM,CAAC,EAAE,WAAW,EACpB,OAAO,GAAE,YAAkC,GAC1C,OAAO,CAAC,mBAAmB,CAAC,CAqD9B;AAED;;;GAGG;AACH,wBAAsB,YAAY,CAChC,IAAI,EAAE,gBAAgB,EACtB,MAAM,CAAC,EAAE,WAAW,EACpB,OAAO,GAAE,YAAkC,GAC1C,OAAO,CAAC,IAAI,CAAC,CAEf"}
+{"version":3,"file":"kubectl.d.ts","sourceRoot":"","sources":["../../../src/op/activities/kubectl.ts"],"names":[],"mappings":"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"}