@tahminator/pipeline 1.0.90 → 1.0.91-beta.gabf5f4ea

package/README.md

@@ -172,6 +172,7 @@ See the [action documentation](./actions/commands/README.md) for GitHub App perm
 ```ts
 import {
   DockerClient,
+  FluxClient,
   EnvClient,
   GitHubClient,
   NPMClient,
@@ -194,6 +195,7 @@ Jump to client documentation
 
 - [`GitHubClient`](#githubclient)
 - [`DockerClient`](#dockerclient)
+- [`FluxClient`](#fluxclient)
 - [`ProtobufCompilerClient`](#protobufcompilerclient)
   - [Setup action versions](#setup-action-versions)
 - [`NPMClient`](#npmclient)
@@ -257,6 +259,14 @@ await client.sendPrMessage({
   message: "Deployed and healthy.",
 });
 
+// uploads files as an artifact of the current workflow run; returns { id, url }
+// requires the Actions runtime token, which the setup action exposes
+await client.uploadArtifact({
+  name: "report",
+  files: ["/tmp/report/report.md"],
+  rootDirectory: "/tmp/report",
+});
+
 // use VersioningClient to compute your next semver tag.
 // look for `VersioningClient` section for how to configure / use
 const versioning = new VersioningClient(client, VersionUpdatingStrategy.JSTS);
@@ -286,6 +296,39 @@ await client.outputToGithubOutput({
 });
 ```
 
+### `FluxClient`
+
+Work with a repository of [Flux](https://fluxcd.io) manifests. Currently renders every Flux `Kustomization` the way kustomize-controller does and diffs the output between two commits, so a PR shows what would actually change in the cluster.
+
+Requires `git`, `diff` and `kustomize` on `PATH` (`INSTALL_KUSTOMIZE: true` in the setup action).
+
+```ts
+const gh = await GitHubClient.createWithGithubAppToken({ ... });
+
+const flux = new FluxClient(gh, {
+  // optional; globs scanned for Flux Kustomizations. by default, it will check all yaml files
+  include: ["clusters/**/*.yaml"],
+  // optional; which sourceRefs are this repository. default: every GitRepository
+  isLocalSource: (ref) => ref.kind === "GitRepository" && ref.name === "flux-system",
+});
+
+// renders every Flux Kustomization at baseRef and in the working tree, then posts the
+// changed ones as a new PR comment. If comment would exceed GitHub's comment size limit, the full
+// comment is uploaded as a workflow run artifact and the PR comment links to it instead.
+await flux.diff({
+  baseRef: process.env.BASE_SHA!,
+  owner: "tahminator",
+  repository: "infra",
+  prId: 123,
+  title: "Rendered manifest diff", // optional
+  description: "Secrets are shown SOPS-encrypted.", // optional
+});
+```
+
+Each Kustomization is rendered as `kustomize build` of `spec.path` with `targetNamespace`, `namePrefix`, `nameSuffix`, `components`, `images`, `patches` and `commonMetadata` applied on top, followed by `postBuild.substitute`. Paths without a `kustomization.yaml` get one generated, as Flux does. Values from `postBuild.substituteFrom` live in the cluster, so those variables are left as-is and listed in the diff's notes. A build failure is shown in the comment instead of being skipped. `HelmRelease` objects are diffed as manifests; charts are not templated.
+
+The diff is split per Kubernetes object (matched by API group, kind, namespace and name), and each object is labelled with the file that defines it, taken from kustomize's `originAnnotations`. Generated ConfigMaps and Secrets point at the `kustomization.yaml` whose generator creates them, and are matched without their content-hash suffix, so editing a generator's data shows as a line diff of the same object rather than a removal and an addition. Files that only patch an object are not recorded, so a change made by a patch is attributed to the object's original file. Any other renamed object shows as one removal and one addition.
+
 ### `DockerClient`
 
 Interface with Docker to build & deploy images

package/dist/flux/client.d.ts

@@ -0,0 +1,33 @@
+import type { GitHubClient } from "../gh";
+import { type FormatFluxDiffOpts } from "./format";
+import { type FluxClientOpts, type FluxKustomization } from "./types";
+/**
+ * Works with a repository of Flux manifests: finds its Flux `Kustomization`s, renders them the
+ * way kustomize-controller would, and reports how a change affects the rendered output.
+ *
+ * Requires `git`, `diff` and `kustomize` on `PATH`.
+ */
+export declare class FluxClient {
+    private readonly ghClient;
+    private readonly include;
+    private readonly isLocalSource;
+    constructor(ghClient: GitHubClient, opts?: FluxClientOpts);
+    /** Returns every Flux `Kustomization` declared under `root`. */
+    findKustomizations(root?: string): Promise<FluxKustomization[]>;
+    /**
+     * Renders every Flux `Kustomization` at `baseRef` and in the working tree at `root`,
+     * and posts the ones whose output differs as a new PR comment.
+     *
+     * `baseRef` is fetched from `origin` if it is not available locally (e.g. shallow CI clones).
+     * If the comment would exceed GitHub's size limit, the full comment is uploaded as an
+     * artifact of the current workflow run and the PR comment links to it instead.
+     */
+    diff({ baseRef, root, owner, repository, prId, ...formatOpts }: {
+        baseRef: string;
+        root?: string;
+        owner: string;
+        repository: string;
+        prId: number;
+    } & Omit<FormatFluxDiffOpts, "artifactUrl">): Promise<void>;
+    private collectDiff;
+}

package/dist/flux/client.js

@@ -0,0 +1,215 @@
+import { $ } from "bun";
+import { mkdir, mkdtemp, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import path from "node:path";
+import { findFluxKustomizations } from "./discover";
+import { formatFluxDiff, label } from "./format";
+import { objectKey, renderKustomization } from "./render";
+import {} from "./types";
+/** GitHub rejects comment bodies above 65536 characters. */
+const MAX_COMMENT_LENGTH = 65_536;
+const DEFAULT_INCLUDE = ["**/*.yaml", "**/*.yml"];
+/**
+ * Works with a repository of Flux manifests: finds its Flux `Kustomization`s, renders them the
+ * way kustomize-controller would, and reports how a change affects the rendered output.
+ *
+ * Requires `git`, `diff` and `kustomize` on `PATH`.
+ */
+export class FluxClient {
+    ghClient;
+    include;
+    isLocalSource;
+    constructor(ghClient, opts = {}) {
+        this.ghClient = ghClient;
+        this.include = opts.include ?? DEFAULT_INCLUDE;
+        this.isLocalSource =
+            opts.isLocalSource ?? ((sourceRef) => sourceRef.kind === "GitRepository");
+    }
+    /** Returns every Flux `Kustomization` declared under `root`. */
+    findKustomizations(root = ".") {
+        return findFluxKustomizations(root, this.include);
+    }
+    /**
+     * Renders every Flux `Kustomization` at `baseRef` and in the working tree at `root`,
+     * and posts the ones whose output differs as a new PR comment.
+     *
+     * `baseRef` is fetched from `origin` if it is not available locally (e.g. shallow CI clones).
+     * If the comment would exceed GitHub's size limit, the full comment is uploaded as an
+     * artifact of the current workflow run and the PR comment links to it instead.
+     */
+    async diff({ baseRef, root = ".", owner, repository, prId, ...formatOpts }) {
+        const result = await this.collectDiff(baseRef, root);
+        const full = formatFluxDiff(result, formatOpts);
+        if (full.length <= MAX_COMMENT_LENGTH) {
+            await this.ghClient.sendPrMessage({
+                owner,
+                repository,
+                prId,
+                message: full,
+            });
+            return;
+        }
+        const dir = await mkdtemp(path.join(tmpdir(), "flux-diff-artifact-"));
+        try {
+            const file = path.join(dir, "flux-diff.md");
+            await Bun.write(file, full);
+            const attempt = process.env.GITHUB_RUN_ATTEMPT ?? "1";
+            const { url } = await this.ghClient.uploadArtifact({
+                name: `flux-diff-pr-${prId}-attempt-${attempt}`,
+                files: [file],
+                rootDirectory: dir,
+            });
+            const message = formatFluxDiff(result, {
+                ...formatOpts,
+                artifactUrl: url,
+            });
+            await this.ghClient.sendPrMessage({ owner, repository, prId, message });
+        }
+        finally {
+            await rm(dir, { recursive: true, force: true });
+        }
+    }
+    async collectDiff(baseRef, root) {
+        const workdir = await mkdtemp(path.join(tmpdir(), "flux-diff-"));
+        const baseRoot = path.join(workdir, "base");
+        await $ `git -C ${root} fetch --depth=1 origin ${baseRef}`.quiet().nothrow();
+        await $ `git -C ${root} worktree add --detach ${baseRoot} ${baseRef}`.quiet();
+        try {
+            const [baseKustomizations, headKustomizations] = await Promise.all([
+                this.findKustomizations(baseRoot),
+                this.findKustomizations(root),
+            ]);
+            const pairs = new Map();
+            for (const kustomization of baseKustomizations) {
+                pairs.set(label(kustomization), { base: kustomization });
+            }
+            for (const kustomization of headKustomizations) {
+                const key = label(kustomization);
+                pairs.set(key, { ...pairs.get(key), head: kustomization });
+            }
+            const changed = [];
+            const skipped = [];
+            let nextDiffId = 0;
+            const nextDiffDir = () => path.join(workdir, "diffs", String(nextDiffId++));
+            await Promise.all([...pairs.values()].map(async ({ base, head }) => {
+                const current = (head ?? base);
+                const { name, namespace } = current;
+                const unrenderable = [base, head].find((kustomization) => kustomization &&
+                    !this.isLocalSource(kustomization.spec.sourceRef));
+                if (unrenderable) {
+                    const { kind, name: sourceName } = unrenderable.spec.sourceRef;
+                    skipped.push({
+                        name,
+                        namespace,
+                        reason: `source \`${kind}/${sourceName}\` is not this repository`,
+                    });
+                    return;
+                }
+                const [baseRender, headRender] = await Promise.all([
+                    base ? renderKustomization(baseRoot, base) : undefined,
+                    head ? renderKustomization(root, head) : undefined,
+                ]);
+                const buildError = headRender?.error;
+                const objects = buildError ?
+                    []
+                    : await diffObjects(baseRender?.objects ?? [], headRender?.objects ?? [], nextDiffDir);
+                const unchanged = buildError ?
+                    buildError === baseRender?.error
+                    : objects.length === 0;
+                if (unchanged) {
+                    return;
+                }
+                const notes = new Set([
+                    ...(baseRender?.notes ?? []),
+                    ...(headRender?.notes ?? []),
+                ]);
+                if (baseRender?.error && !buildError) {
+                    notes.add("`kustomize build` fails at the base commit, so every object is shown as added.");
+                }
+                changed.push({
+                    name,
+                    namespace,
+                    path: current.path,
+                    status: !base ? "added"
+                        : !head ? "removed"
+                            : "changed",
+                    objects,
+                    ...(buildError ? { buildError } : {}),
+                    additions: objects.reduce((sum, o) => sum + o.additions, 0),
+                    deletions: objects.reduce((sum, o) => sum + o.deletions, 0),
+                    notes: [...notes],
+                });
+            }));
+            const byLabel = (a, b) => label(a).localeCompare(label(b));
+            return {
+                baseRef,
+                changed: changed.sort(byLabel),
+                skipped: skipped.sort(byLabel),
+            };
+        }
+        finally {
+            await $ `git -C ${root} worktree remove --force ${baseRoot}`
+                .quiet()
+                .nothrow();
+            await rm(workdir, { recursive: true, force: true });
+        }
+    }
+}
+/** Pairs base and head objects by {@link objectKey} and diffs the ones whose rendered YAML differs. */
+async function diffObjects(baseObjects, headObjects, nextDir) {
+    const pairs = new Map();
+    for (const object of baseObjects) {
+        pairs.set(objectKey(object), { base: object });
+    }
+    for (const object of headObjects) {
+        const k = objectKey(object);
+        pairs.set(k, { ...pairs.get(k), head: object });
+    }
+    const diffs = await Promise.all([...pairs.values()].map(async ({ base, head }) => {
+        if (base?.yaml === head?.yaml) {
+            return null;
+        }
+        const current = (head ?? base);
+        const { kind, namespace, name, file } = current;
+        const diff = await unifiedDiff(nextDir(), [kind, namespace, name].filter(Boolean).join("/"), base?.yaml ?? "", head?.yaml ?? "");
+        const lines = diff.split("\n");
+        const objectDiff = {
+            kind,
+            namespace,
+            name,
+            ...(file ? { file } : {}),
+            status: !base ? "added"
+                : !head ? "removed"
+                    : "changed",
+            diff,
+            additions: lines.filter((line) => line.startsWith("+") && !line.startsWith("+++")).length,
+            deletions: lines.filter((line) => line.startsWith("-") && !line.startsWith("---")).length,
+        };
+        return objectDiff;
+    }));
+    return diffs
+        .filter((diff) => diff !== null)
+        .sort((a, b) => 
+    // objects without a recorded file sort last
+    (a.file ?? "\uffff").localeCompare(b.file ?? "\uffff") ||
+        a.kind.localeCompare(b.kind) ||
+        a.namespace.localeCompare(b.namespace) ||
+        a.name.localeCompare(b.name));
+}
+async function unifiedDiff(dir, targetPath, baseOutput, headOutput) {
+    await mkdir(dir, { recursive: true });
+    const baseFile = path.join(dir, "base.yaml");
+    const headFile = path.join(dir, "head.yaml");
+    await Promise.all([
+        Bun.write(baseFile, baseOutput),
+        Bun.write(headFile, headOutput),
+    ]);
+    const result = await $ `diff -u --label ${`a/${targetPath}`} --label ${`b/${targetPath}`} ${baseFile} ${headFile}`
+        .quiet()
+        .nothrow();
+    // diff exits 1 when the files differ and 2 on error
+    if (result.exitCode > 1) {
+        throw new Error(`diff failed for ${targetPath}: ${result.stderr}`);
+    }
+    return result.stdout.toString();
+}

package/dist/flux/discover.d.ts

@@ -0,0 +1,6 @@
+import { type FluxKustomization } from "./types";
+/**
+ * Returns every Flux `Kustomization` declared in files under `root` matching `include`,
+ * sorted by namespace then name. Hidden directories and `node_modules` are never scanned.
+ */
+export declare function findFluxKustomizations(root: string, include: string[]): Promise<FluxKustomization[]>;

package/dist/flux/discover.js

@@ -0,0 +1,51 @@
+import { Glob } from "bun";
+import path from "node:path";
+import { parseAllDocuments } from "yaml";
+import { fluxKustomizationSchema } from "./types";
+const FLUX_API_GROUP = "kustomize.toolkit.fluxcd.io/";
+/**
+ * Returns every Flux `Kustomization` declared in files under `root` matching `include`,
+ * sorted by namespace then name. Hidden directories and `node_modules` are never scanned.
+ */
+export async function findFluxKustomizations(root, include) {
+    const files = new Set();
+    for (const pattern of include) {
+        for await (const file of new Glob(pattern).scan({ cwd: root })) {
+            if (!file.split(path.sep).includes("node_modules")) {
+                files.add(file);
+            }
+        }
+    }
+    const found = await Promise.all([...files].map(async (file) => {
+        const content = await Bun.file(path.join(root, file)).text();
+        // cheap pre-filter; most YAML in a manifest repo is not a Flux Kustomization
+        if (!content.includes(FLUX_API_GROUP)) {
+            return [];
+        }
+        return parseFile(file, content);
+    }));
+    return found
+        .flat()
+        .sort((a, b) => a.namespace.localeCompare(b.namespace) || a.name.localeCompare(b.name));
+}
+function parseFile(file, content) {
+    const kustomizations = [];
+    for (const doc of parseAllDocuments(content)) {
+        if (doc.errors.length > 0) {
+            continue;
+        }
+        const parsed = fluxKustomizationSchema.safeParse(doc.toJS());
+        if (!parsed.success) {
+            continue;
+        }
+        const { metadata, spec } = parsed.data;
+        kustomizations.push({
+            file,
+            name: metadata.name,
+            namespace: metadata.namespace ?? "",
+            path: path.normalize(spec.path ?? "."),
+            spec,
+        });
+    }
+    return kustomizations;
+}

package/dist/flux/format.d.ts

@@ -0,0 +1,18 @@
+import type { FluxDiffResult } from "./types";
+export type FormatFluxDiffOpts = {
+    /** @default "Flux diff" */
+    title?: string;
+    /** extra markdown shown under the title, e.g. how secrets are displayed */
+    description?: string;
+    /**
+     * when set, diffs are replaced by a summary and a link here
+     * (used when the full comment would exceed GitHub's size limit)
+     */
+    artifactUrl?: string;
+};
+/** Formats a {@link FluxDiffResult} as a markdown PR comment. */
+export declare function formatFluxDiff(result: FluxDiffResult, { title, description, artifactUrl }?: FormatFluxDiffOpts): string;
+export declare function label({ name, namespace, }: {
+    name: string;
+    namespace: string;
+}): string;

package/dist/flux/format.js

@@ -0,0 +1,50 @@
+/** Formats a {@link FluxDiffResult} as a markdown PR comment. */
+export function formatFluxDiff(result, { title = "Flux diff", description, artifactUrl } = {}) {
+    const base = `\`${result.baseRef.slice(0, 7)}\``;
+    const lines = [`### ${title}`, ""];
+    if (description) {
+        lines.push(description, "");
+    }
+    lines.push(result.changed.length === 0 ?
+        `No Flux Kustomization renders differently against ${base}.`
+        : `${result.changed.length} Flux Kustomization(s) render differently against ${base}.`, "");
+    if (artifactUrl) {
+        lines.push(`> [!WARNING]`, `> The rendered diff is too long for a GitHub comment. [Download the full diff from the workflow run](${artifactUrl}).`, "");
+        for (const change of result.changed) {
+            lines.push(`- ${summary(change)}`);
+            if (change.buildError) {
+                lines.push("  - `kustomize build` failed");
+            }
+            lines.push(...change.objects.map((object) => `  - ${objectSummary(object)}`));
+        }
+        lines.push("");
+    }
+    else {
+        for (const change of result.changed) {
+            lines.push(`<details><summary>${summary(change)}</summary>`, "", ...change.notes.map((note) => `> ${note}\n`));
+            if (change.buildError) {
+                lines.push("`kustomize build` failed:", "", "````text", change.buildError, "````", "");
+            }
+            for (const object of change.objects) {
+                lines.push(objectSummary(object), "", "````diff", object.diff.trimEnd(), "````", "");
+            }
+            lines.push("</details>", "");
+        }
+    }
+    if (result.skipped.length > 0) {
+        lines.push(`<details><summary>${result.skipped.length} Flux Kustomization(s) not rendered</summary>`, "", ...result.skipped.map((skipped) => `- <code>${label(skipped)}</code>: ${skipped.reason}`), "", "</details>", "");
+    }
+    return lines.join("\n");
+}
+export function label({ name, namespace, }) {
+    return namespace ? `${namespace}/${name}` : name;
+}
+function summary(change) {
+    const counts = change.buildError ? "build failed" : (`${change.objects.length} object(s), +${change.additions} −${change.deletions}`);
+    return `<code>${label(change)}</code> — <code>${change.path}</code> (${change.status}, ${counts})`;
+}
+function objectSummary(object) {
+    const name = [object.namespace, object.name].filter(Boolean).join("/");
+    const file = object.file ? ` — \`${object.file}\`` : "";
+    return `**\`${object.kind}\` \`${name}\`**${file} (${object.status}, +${object.additions} −${object.deletions})`;
+}

package/dist/flux/index.d.ts

@@ -0,0 +1,2 @@
+export * from "./client";
+export type { FluxClientOpts, FluxKustomization, FluxSourceRef } from "./types";

package/dist/flux/index.js

@@ -0,0 +1 @@
+export * from "./client";

package/dist/flux/render.d.ts

@@ -0,0 +1,52 @@
+import type { FluxKustomization } from "./types";
+export type RenderedObject = {
+    apiVersion: string;
+    kind: string;
+    namespace: string;
+    name: string;
+    /**
+     * repository-relative file that defines the object (for generated objects, the
+     * kustomization.yaml whose generator creates it); `undefined` if kustomize did not record one
+     */
+    file?: string;
+    /** created by a ConfigMap/Secret generator, so `name` may end in a content hash */
+    generated: boolean;
+    /** the object's rendered YAML, without the origin annotation */
+    yaml: string;
+};
+/**
+ * Identifies the same object across two renders: API group, kind, namespace and name.
+ * An apiVersion bump within a group keeps the key; generated objects drop the content hash
+ * from their name so an edited ConfigMap/Secret pairs with its previous version.
+ */
+export declare function objectKey(object: RenderedObject): string;
+type RenderedKustomization = {
+    /** rendered objects, in kustomize's output order; empty when `error` is set */
+    objects: RenderedObject[];
+    /** `kustomize build` error output, when the build failed */
+    error?: string;
+    notes: string[];
+};
+/**
+ * Renders a Flux `Kustomization` the way kustomize-controller does: `kustomize build` of
+ * `spec.path` with the overlay fields from the spec (`targetNamespace`, `namePrefix`,
+ * `nameSuffix`, `components`, `images`, `patches`, `commonMetadata`) applied on top,
+ * followed by `postBuild` variable substitution.
+ *
+ * Each rendered object records the file that defines it.
+ */
+export declare function renderKustomization(root: string, kustomization: FluxKustomization): Promise<RenderedKustomization>;
+/**
+ * Applies Flux `postBuild` substitution to rendered multi-document YAML. Documents annotated
+ * with `kustomize.toolkit.fluxcd.io/substitute: disabled` are left untouched.
+ *
+ * Variables without a value and without a default become empty strings, as in Flux, unless
+ * `keepUnresolved` is set (used when some values come from `substituteFrom` and are unknown).
+ */
+export declare function substituteVariables(input: string, vars: Record<string, string>, { keepUnresolved }: {
+    keepUnresolved: boolean;
+}): {
+    output: string;
+    unresolved: string[];
+};
+export {};

package/dist/flux/render.js

@@ -0,0 +1,203 @@
+import { $ } from "bun";
+import { mkdtemp, readdir, rm } from "node:fs/promises";
+import path from "node:path";
+import yaml from "yaml";
+const KUSTOMIZATION_FILES = [
+    "kustomization.yaml",
+    "kustomization.yml",
+    "Kustomization",
+];
+const SUBSTITUTE_DISABLED = /kustomize\.toolkit\.fluxcd\.io\/substitute:\s*["']?disabled["']?/;
+/** `${VAR}`, `${VAR:-default}`, `${VAR-default}`, `${VAR:=default}`, `${VAR=default}`; `$${VAR}` escapes. */
+const VARIABLE = /\$(\$)?\{([A-Za-z_][A-Za-z0-9_]*)(?:(:?[-=])([^}]*))?\}/g;
+/** kustomize's `originAnnotations` build metadata; records the file that defines each object. */
+const ORIGIN_ANNOTATION = "config.kubernetes.io/origin";
+const GENERATORS = ["ConfigMapGenerator", "SecretGenerator"];
+/** kustomize's name hash: 10 characters from its vowel-free alphabet, appended last. */
+const NAME_HASH = /-[2456789bcdfghkmt]{10}$/;
+/**
+ * Identifies the same object across two renders: API group, kind, namespace and name.
+ * An apiVersion bump within a group keeps the key; generated objects drop the content hash
+ * from their name so an edited ConfigMap/Secret pairs with its previous version.
+ */
+export function objectKey(object) {
+    const group = object.apiVersion.includes("/") ? object.apiVersion.split("/")[0] : "";
+    const name = object.generated ? object.name.replace(NAME_HASH, "") : object.name;
+    return [group, object.kind, object.namespace, name].join("\0");
+}
+/**
+ * Renders a Flux `Kustomization` the way kustomize-controller does: `kustomize build` of
+ * `spec.path` with the overlay fields from the spec (`targetNamespace`, `namePrefix`,
+ * `nameSuffix`, `components`, `images`, `patches`, `commonMetadata`) applied on top,
+ * followed by `postBuild` variable substitution.
+ *
+ * Each rendered object records the file that defines it.
+ */
+export async function renderKustomization(root, kustomization) {
+    const notes = [];
+    const { spec } = kustomization;
+    const targetDir = path.join(root, kustomization.path);
+    // kustomize rejects absolute resource paths, so the wrapper must live inside `root`
+    const wrapper = await mkdtemp(path.join(root, ".flux-render-"));
+    try {
+        const relative = (to) => path.relative(wrapper, to);
+        let resources = [relative(targetDir)];
+        if (!(await hasKustomizationFile(targetDir))) {
+            resources = (await generateResources(targetDir)).map(relative);
+            notes.push(`\`${kustomization.path}\` has no kustomization.yaml; resources were generated the way Flux does.`);
+        }
+        const wrapperKustomization = {
+            apiVersion: "kustomize.config.k8s.io/v1beta1",
+            kind: "Kustomization",
+            namespace: spec.targetNamespace,
+            namePrefix: spec.namePrefix,
+            nameSuffix: spec.nameSuffix,
+            resources,
+            components: spec.components?.map((component) => relative(path.join(targetDir, component))),
+            images: spec.images,
+            patches: spec.patches,
+            labels: spec.commonMetadata?.labels ?
+                [{ pairs: spec.commonMetadata.labels, includeSelectors: false }]
+                : undefined,
+            commonAnnotations: spec.commonMetadata?.annotations,
+            buildMetadata: ["originAnnotations"],
+        };
+        await Bun.write(path.join(wrapper, "kustomization.yaml"), yaml.stringify(wrapperKustomization));
+        const result = await $ `kustomize build --load-restrictor LoadRestrictionsNone ${wrapper}`
+            .quiet()
+            .nothrow();
+        if (result.exitCode !== 0) {
+            return { objects: [], error: result.stderr.toString().trim(), notes };
+        }
+        let output = result.stdout.toString();
+        if (spec.postBuild) {
+            const hasExternalValues = (spec.postBuild.substituteFrom ?? []).length > 0;
+            const substituted = substituteVariables(output, spec.postBuild.substitute ?? {}, { keepUnresolved: hasExternalValues });
+            output = substituted.output;
+            if (substituted.unresolved.length > 0) {
+                notes.push(`\`postBuild.substituteFrom\` values live in the cluster and were left unresolved: ${substituted.unresolved
+                    .map((name) => `\`\${${name}}\``)
+                    .join(", ")}.`);
+            }
+        }
+        const docs = yaml.parseAllDocuments(output);
+        const invalid = docs.find((doc) => doc.errors.length > 0);
+        if (invalid) {
+            return {
+                objects: [],
+                error: `rendered output is not valid YAML: ${invalid.errors[0]?.message}`,
+                notes,
+            };
+        }
+        const objects = docs
+            .filter((doc) => doc.contents !== null)
+            .map((doc) => toRenderedObject(doc, root, wrapper));
+        return { objects, notes };
+    }
+    finally {
+        await rm(wrapper, { recursive: true, force: true });
+    }
+}
+function toRenderedObject(doc, root, wrapper) {
+    const raw = doc.getIn(["metadata", "annotations", ORIGIN_ANNOTATION]);
+    doc.deleteIn(["metadata", "annotations", ORIGIN_ANNOTATION]);
+    const annotations = doc.getIn(["metadata", "annotations"]);
+    if (yaml.isMap(annotations) && annotations.items.length === 0) {
+        doc.deleteIn(["metadata", "annotations"]);
+    }
+    const origin = typeof raw === "string" ? yaml.parse(raw) : null;
+    const value = (doc.toJS() ?? {});
+    return {
+        apiVersion: String(value.apiVersion ?? ""),
+        kind: String(value.kind ?? ""),
+        namespace: String(value.metadata?.namespace ?? ""),
+        name: String(value.metadata?.name ?? ""),
+        file: origin ? originFile(origin, root, wrapper) : undefined,
+        generated: GENERATORS.includes(origin?.configuredBy?.kind ?? ""),
+        yaml: doc.toString({ lineWidth: 0 }).replace(/^---\n/, ""),
+    };
+}
+/**
+ * Converts an origin annotation (`path`, or `configuredIn` for generated objects, relative to
+ * the wrapper kustomization) to a repository-relative path. Remote origins are returned as
+ * `<repo>//<path>?ref=<ref>`.
+ */
+function originFile(origin, root, wrapper) {
+    const file = origin.path ?? origin.configuredIn;
+    if (origin.repo) {
+        return `${origin.repo}//${file ?? ""}${origin.ref ? `?ref=${origin.ref}` : ""}`;
+    }
+    return file ? path.relative(root, path.resolve(wrapper, file)) : undefined;
+}
+/**
+ * Applies Flux `postBuild` substitution to rendered multi-document YAML. Documents annotated
+ * with `kustomize.toolkit.fluxcd.io/substitute: disabled` are left untouched.
+ *
+ * Variables without a value and without a default become empty strings, as in Flux, unless
+ * `keepUnresolved` is set (used when some values come from `substituteFrom` and are unknown).
+ */
+export function substituteVariables(input, vars, { keepUnresolved }) {
+    const unresolved = new Set();
+    const output = input
+        .split(/^(?=---$)/m)
+        .map((doc) => {
+        if (SUBSTITUTE_DISABLED.test(doc)) {
+            return doc;
+        }
+        return doc.replace(VARIABLE, (match, escape, name, operator, fallback) => {
+            if (escape) {
+                return match.slice(1);
+            }
+            const value = vars[name];
+            if (operator !== undefined) {
+                const useValue = value !== undefined &&
+                    (!operator.startsWith(":") || value !== "");
+                return useValue ? value : (fallback ?? "");
+            }
+            if (value !== undefined) {
+                return value;
+            }
+            if (keepUnresolved) {
+                unresolved.add(name);
+                return match;
+            }
+            return "";
+        });
+    })
+        .join("");
+    return { output, unresolved: [...unresolved].sort() };
+}
+async function hasKustomizationFile(dir) {
+    const entries = await readdir(dir).catch(() => []);
+    return entries.some((entry) => KUSTOMIZATION_FILES.includes(entry));
+}
+/**
+ * Mirrors Flux's generated kustomization for a path without one: every Kubernetes manifest
+ * under `dir`, with subdirectories that have their own kustomization included as a whole.
+ */
+async function generateResources(dir) {
+    const entries = await readdir(dir, { withFileTypes: true }).catch(() => []);
+    const resources = [];
+    for (const entry of entries.sort((a, b) => a.name.localeCompare(b.name))) {
+        const full = path.join(dir, entry.name);
+        if (entry.isDirectory()) {
+            if (await hasKustomizationFile(full)) {
+                resources.push(full);
+            }
+            else {
+                resources.push(...(await generateResources(full)));
+            }
+        }
+        else if (/\.ya?ml$/.test(entry.name) && (await isManifest(full))) {
+            resources.push(full);
+        }
+    }
+    return resources;
+}
+async function isManifest(file) {
+    const docs = yaml.parseAllDocuments(await Bun.file(file).text());
+    return docs.some((doc) => {
+        const value = doc.errors.length === 0 ? doc.toJS() : undefined;
+        return (typeof value?.apiVersion === "string" && typeof value?.kind === "string");
+    });
+}

package/dist/flux/types.d.ts

@@ -0,0 +1,117 @@
+import z from "zod";
+/**
+ * The subset of a Flux `Kustomization` (`kustomize.toolkit.fluxcd.io`) that affects rendered output.
+ */
+export declare const fluxKustomizationSchema: z.ZodObject<{
+    apiVersion: z.ZodString;
+    kind: z.ZodLiteral<"Kustomization">;
+    metadata: z.ZodObject<{
+        name: z.ZodString;
+        namespace: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>;
+    spec: z.ZodObject<{
+        path: z.ZodOptional<z.ZodString>;
+        sourceRef: z.ZodObject<{
+            kind: z.ZodString;
+            name: z.ZodString;
+            namespace: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>;
+        targetNamespace: z.ZodOptional<z.ZodString>;
+        namePrefix: z.ZodOptional<z.ZodString>;
+        nameSuffix: z.ZodOptional<z.ZodString>;
+        components: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        images: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            name: z.ZodString;
+            newName: z.ZodOptional<z.ZodString>;
+            newTag: z.ZodOptional<z.ZodString>;
+            digest: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>>>;
+        patches: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            patch: z.ZodString;
+            target: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+        }, z.core.$strip>>>;
+        commonMetadata: z.ZodOptional<z.ZodObject<{
+            labels: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+            annotations: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+        }, z.core.$strip>>;
+        postBuild: z.ZodOptional<z.ZodObject<{
+            substitute: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+            substituteFrom: z.ZodOptional<z.ZodArray<z.ZodUnknown>>;
+        }, z.core.$strip>>;
+    }, z.core.$strip>;
+}, z.core.$strip>;
+type FluxKustomizationSpec = z.infer<typeof fluxKustomizationSchema>["spec"];
+/** A Flux `Kustomization` found in the repository. */
+export type FluxKustomization = {
+    /** repository-relative file the Kustomization is declared in */
+    file: string;
+    name: string;
+    /** `metadata.namespace`, or `""` when the manifest leaves it to an enclosing kustomization */
+    namespace: string;
+    /** normalized, repository-relative `spec.path` */
+    path: string;
+    spec: FluxKustomizationSpec;
+};
+export type FluxSourceRef = FluxKustomizationSpec["sourceRef"];
+type FluxDiffStatus = "added" | "changed" | "removed";
+/** A rendered Kubernetes object whose output differs between base and head. */
+export type FluxObjectDiff = {
+    kind: string;
+    /** `""` for cluster-scoped objects */
+    namespace: string;
+    name: string;
+    /**
+     * repository-relative file that defines the object, from kustomize's origin annotations.
+     * Generated objects (ConfigMap/Secret generators) point at the kustomization.yaml that
+     * generates them. Files that only patch the object are not recorded.
+     */
+    file?: string;
+    status: FluxDiffStatus;
+    /** unified diff of the object's rendered YAML */
+    diff: string;
+    additions: number;
+    deletions: number;
+};
+export type FluxKustomizationDiff = {
+    name: string;
+    namespace: string;
+    path: string;
+    status: FluxDiffStatus;
+    /** changed objects, sorted by file then kind, namespace and name */
+    objects: FluxObjectDiff[];
+    /** `kustomize build` error at head; `objects` is empty when set */
+    buildError?: string;
+    /** totals across `objects` */
+    additions: number;
+    deletions: number;
+    /** caveats about how faithful the render is, e.g. unresolvable `substituteFrom` variables */
+    notes: string[];
+};
+export type FluxSkippedKustomization = {
+    name: string;
+    namespace: string;
+    reason: string;
+};
+export type FluxDiffResult = {
+    baseRef: string;
+    /** Kustomizations whose rendered output differs, sorted by name */
+    changed: FluxKustomizationDiff[];
+    /** Kustomizations that could not be rendered locally */
+    skipped: FluxSkippedKustomization[];
+};
+export type FluxClientOpts = {
+    /**
+     * Globs (relative to the repository root) scanned for Flux Kustomizations.
+     *
+     * @default ["**\/*.yaml", "**\/*.yml"]
+     */
+    include?: string[];
+    /**
+     * Decides whether a Kustomization's `sourceRef` points at the repository being diffed.
+     * Kustomizations with any other source are reported as skipped.
+     *
+     * @default every `GitRepository` source
+     */
+    isLocalSource?: (sourceRef: FluxSourceRef) => boolean;
+};
+export {};

package/dist/flux/types.js

@@ -0,0 +1,50 @@
+import z from "zod";
+/**
+ * The subset of a Flux `Kustomization` (`kustomize.toolkit.fluxcd.io`) that affects rendered output.
+ */
+export const fluxKustomizationSchema = z.object({
+    apiVersion: z.string().startsWith("kustomize.toolkit.fluxcd.io/"),
+    kind: z.literal("Kustomization"),
+    metadata: z.object({
+        name: z.string(),
+        namespace: z.string().optional(),
+    }),
+    spec: z.object({
+        path: z.string().optional(),
+        sourceRef: z.object({
+            kind: z.string(),
+            name: z.string(),
+            namespace: z.string().optional(),
+        }),
+        targetNamespace: z.string().optional(),
+        namePrefix: z.string().optional(),
+        nameSuffix: z.string().optional(),
+        components: z.array(z.string()).optional(),
+        images: z
+            .array(z.object({
+            name: z.string(),
+            newName: z.string().optional(),
+            newTag: z.string().optional(),
+            digest: z.string().optional(),
+        }))
+            .optional(),
+        patches: z
+            .array(z.object({
+            patch: z.string(),
+            target: z.record(z.string(), z.unknown()).optional(),
+        }))
+            .optional(),
+        commonMetadata: z
+            .object({
+            labels: z.record(z.string(), z.string()).optional(),
+            annotations: z.record(z.string(), z.string()).optional(),
+        })
+            .optional(),
+        postBuild: z
+            .object({
+            substitute: z.record(z.string(), z.string()).optional(),
+            substituteFrom: z.array(z.unknown()).optional(),
+        })
+            .optional(),
+    }),
+});

package/dist/gh/artifact/index.d.ts

@@ -0,0 +1,28 @@
+export declare class GitHubArtifactManager {
+    private readonly client;
+    constructor();
+    /**
+     * Uploads `files` as an artifact of the current workflow run and returns a link to it.
+     *
+     * @note must run inside a GitHub Actions job with the runtime token exposed
+     * (the `setup` action automatically exposes it).
+     */
+    uploadArtifact({ name, files, rootDirectory, retentionDays, }: {
+        /**
+         * must be unique within the workflow run
+         */
+        name: string;
+        /**
+         * absolute paths of the files to upload
+         */
+        files: string[];
+        /**
+         * paths inside the artifact are relative to this directory
+         */
+        rootDirectory: string;
+        retentionDays?: number;
+    }): Promise<{
+        id: number;
+        url: string;
+    }>;
+}

package/dist/gh/artifact/index.js

@@ -0,0 +1,29 @@
+import { DefaultArtifactClient } from "@actions/artifact";
+export class GitHubArtifactManager {
+    client;
+    constructor() {
+        this.client = new DefaultArtifactClient();
+    }
+    /**
+     * Uploads `files` as an artifact of the current workflow run and returns a link to it.
+     *
+     * @note must run inside a GitHub Actions job with the runtime token exposed
+     * (the `setup` action automatically exposes it).
+     */
+    async uploadArtifact({ name, files, rootDirectory, retentionDays, }) {
+        const serverUrl = process.env.GITHUB_SERVER_URL;
+        const repository = process.env.GITHUB_REPOSITORY;
+        const runId = process.env.GITHUB_RUN_ID;
+        if (!serverUrl || !repository || !runId) {
+            throw new Error("uploadArtifact must run inside a GitHub Actions job (missing GITHUB_SERVER_URL, GITHUB_REPOSITORY or GITHUB_RUN_ID)");
+        }
+        const { id } = await this.client.uploadArtifact(name, files, rootDirectory, { retentionDays });
+        if (id === undefined) {
+            throw new Error(`Artifact ${name} was uploaded but GitHub returned no id`);
+        }
+        return {
+            id,
+            url: `${serverUrl}/${repository}/actions/runs/${runId}/artifacts/${id}`,
+        };
+    }
+}

package/dist/gh/client.d.ts

@@ -1,3 +1,4 @@
+import { GitHubArtifactManager } from "./artifact";
 import { GitHubOutputManager } from "./output";
 import { GitHubPRManager } from "./pr";
 import { GitHubTagManager } from "./tag";
@@ -6,6 +7,7 @@ export declare class GitHubClient {
     private readonly client;
     private readonly isExplicitToken;
     private readonly tagManager;
+    private readonly artifactManager;
     private readonly outputManager;
     private readonly prManager;
     private readonly teamManager;
@@ -82,6 +84,15 @@ export declare class GitHubClient {
      */
     updateK8sTagWithPR(...args: Parameters<GitHubPRManager["updateK8sTagWithPR"]>): Promise<void>;
     sendPrMessage(...args: Parameters<GitHubPRManager["sendPrMessage"]>): Promise<void>;
+    /**
+     * Uploads files as an artifact of the current workflow run and returns its download URL.
+     *
+     * @note requires the Actions runtime token, which the `setup` action exposes.
+     */
+    uploadArtifact(...args: Parameters<GitHubArtifactManager["uploadArtifact"]>): Promise<{
+        id: number;
+        url: string;
+    }>;
     /**
      * @note if the PR doesn't exist yet, just use `updateK8sTagWithPR` instead, since it
      * creates the PR with the necessary changes and merges it for you in one call.

package/dist/gh/client.js

@@ -1,5 +1,6 @@
 import { createAppAuth } from "@octokit/auth-app";
 import { Octokit } from "@octokit/rest";
+import { GitHubArtifactManager } from "./artifact";
 import { GitHubOutputManager } from "./output";
 import { GitHubPRManager } from "./pr";
 import { GitHubTagManager } from "./tag";
@@ -8,6 +9,7 @@ export class GitHubClient {
     client;
     isExplicitToken;
     tagManager;
+    artifactManager;
     outputManager;
     prManager;
     teamManager;
@@ -15,6 +17,7 @@ export class GitHubClient {
         this.client = client;
         this.isExplicitToken = isExplicitToken;
         this.tagManager = new GitHubTagManager(this.client, this.isExplicitToken);
+        this.artifactManager = new GitHubArtifactManager();
         this.outputManager = new GitHubOutputManager();
         this.prManager = new GitHubPRManager(this.client);
         this.teamManager = new GitHubTeamManager(this.client);
@@ -112,6 +115,14 @@ export class GitHubClient {
     sendPrMessage(...args) {
         return this.prManager.sendPrMessage(...args);
     }
+    /**
+     * Uploads files as an artifact of the current workflow run and returns its download URL.
+     *
+     * @note requires the Actions runtime token, which the `setup` action exposes.
+     */
+    uploadArtifact(...args) {
+        return this.artifactManager.uploadArtifact(...args);
+    }
     /**
      * @note if the PR doesn't exist yet, just use `updateK8sTagWithPR` instead, since it
      * creates the PR with the necessary changes and merges it for you in one call.

package/dist/index.d.ts

@@ -1,4 +1,5 @@
 export * from "./gh";
+export * from "./flux";
 export * from "./docker";
 export * from "./npm";
 export * from "./sonar";

package/dist/index.js

@@ -1,4 +1,5 @@
 export * from "./gh";
+export * from "./flux";
 export * from "./docker";
 export * from "./npm";
 export * from "./sonar";

package/package.json

@@ -3,7 +3,7 @@
   "type": "module",
   "author": "Tahmid Ahmed",
   "description": "A collection of Bun shell scripts that can be re-used in various CICD pipelines.",
-  "version": "1.0.90",
+  "version": "1.0.91-beta.gabf5f4ea",
   "repository": {
     "url": "git+https://github.com/tahminator/pipeline.git"
   },
@@ -47,6 +47,7 @@
     "typescript": "^5"
   },
   "dependencies": {
+    "@actions/artifact": "^6.2.1",
     "@octokit/auth-app": "^8.2.0",
     "@octokit/rest": "^22.0.1",
     "@pulumi/pulumi": "^3.258.0",