@intentius/chant-lexicon-k8s 0.1.13 → 0.1.15

package/dist/rules/argo002.ts

@@ -0,0 +1,47 @@
+/**
+ * ARGO002: Application.spec.project must reference a declared AppProject
+ *
+ * An Argo `Application` names an `AppProject` in `spec.project`; the project is
+ * the RBAC and source/destination guardrail. If the named project isn't
+ * declared in the build, Argo will reject the Application at sync time. The
+ * built-in `default` project always exists on an Argo install, so a reference
+ * to `default` is never flagged.
+ */
+import type { PostSynthCheck, PostSynthContext, PostSynthDiagnostic } from "@intentius/chant/lint/post-synth";
+import { allManifests, manifestsOfKind } from "./argo-helpers";
+
+export const argo002: PostSynthCheck = {
+  id: "ARGO002",
+  description: "Application.spec.project must reference a declared AppProject (or the built-in default)",
+
+  check(ctx: PostSynthContext): PostSynthDiagnostic[] {
+    const diagnostics: PostSynthDiagnostic[] = [];
+    const manifests = allManifests(ctx);
+
+    const declaredProjects = new Set(
+      manifestsOfKind(manifests, "AppProject")
+        .map((p) => p.metadata?.name)
+        .filter((n): n is string => typeof n === "string"),
+    );
+    // Argo ships a built-in default project.
+    declaredProjects.add("default");
+
+    for (const app of manifestsOfKind(manifests, "Application")) {
+      const project = app.spec?.project;
+      const name = app.metadata?.name ?? "Application";
+      // No project set → defaults to `default` at sync time; not this check's job.
+      if (typeof project !== "string" || project === "") continue;
+      if (declaredProjects.has(project)) continue;
+
+      diagnostics.push({
+        checkId: "ARGO002",
+        severity: "error",
+        message: `Application "${name}" references AppProject "${project}", which is not declared. Add an AppProject named "${project}" or reference an existing project.`,
+        entity: name,
+        lexicon: "k8s",
+      });
+    }
+
+    return diagnostics;
+  },
+};

package/dist/rules/argo003.ts

@@ -0,0 +1,80 @@
+/**
+ * ARGO003: Application.spec.destination must reference a registered cluster
+ *
+ * An Argo `Application` targets a cluster via `spec.destination.server` (an API
+ * server URL) or `spec.destination.name` (a registered cluster name). External
+ * clusters are registered with a Secret labelled
+ * `argocd.argoproj.io/secret-type: cluster`. The in-cluster target
+ * (`https://kubernetes.default.svc` / name `in-cluster`) is always available.
+ * A destination that names neither a registered cluster nor the in-cluster
+ * target won't resolve at sync time.
+ */
+import type { PostSynthCheck, PostSynthContext, PostSynthDiagnostic } from "@intentius/chant/lint/post-synth";
+import {
+  allManifests,
+  manifestsOfKind,
+  isClusterSecret,
+  secretField,
+  IN_CLUSTER_SERVER,
+  IN_CLUSTER_NAME,
+} from "./argo-helpers";
+
+export const argo003: PostSynthCheck = {
+  id: "ARGO003",
+  description: "Application.spec.destination must reference a registered cluster or the in-cluster target",
+
+  check(ctx: PostSynthContext): PostSynthDiagnostic[] {
+    const diagnostics: PostSynthDiagnostic[] = [];
+    const manifests = allManifests(ctx);
+
+    const registeredServers = new Set<string>([IN_CLUSTER_SERVER]);
+    const registeredNames = new Set<string>([IN_CLUSTER_NAME]);
+    for (const secret of manifests.filter(isClusterSecret)) {
+      const server = secretField(secret, "server");
+      if (server) registeredServers.add(server);
+      const name = secretField(secret, "name") ?? secret.metadata?.name;
+      if (typeof name === "string") registeredNames.add(name);
+    }
+
+    for (const app of manifestsOfKind(manifests, "Application")) {
+      const name = app.metadata?.name ?? "Application";
+      const destination = app.spec?.destination as
+        | { server?: unknown; name?: unknown }
+        | undefined;
+
+      if (!destination || (destination.server === undefined && destination.name === undefined)) {
+        diagnostics.push({
+          checkId: "ARGO003",
+          severity: "error",
+          message: `Application "${name}" has no spec.destination.server or spec.destination.name — Argo cannot resolve a target cluster.`,
+          entity: name,
+          lexicon: "k8s",
+        });
+        continue;
+      }
+
+      if (typeof destination.server === "string" && !registeredServers.has(destination.server)) {
+        diagnostics.push({
+          checkId: "ARGO003",
+          severity: "error",
+          message: `Application "${name}" targets cluster server "${destination.server}", which is not registered. Register it with a cluster Secret (label argocd.argoproj.io/secret-type=cluster) or use the in-cluster target.`,
+          entity: name,
+          lexicon: "k8s",
+        });
+        continue;
+      }
+
+      if (typeof destination.name === "string" && !registeredNames.has(destination.name)) {
+        diagnostics.push({
+          checkId: "ARGO003",
+          severity: "error",
+          message: `Application "${name}" targets cluster name "${destination.name}", which is not registered. Register it with a cluster Secret or use the in-cluster target.`,
+          entity: name,
+          lexicon: "k8s",
+        });
+      }
+    }
+
+    return diagnostics;
+  },
+};

package/dist/rules/argo005.ts

@@ -0,0 +1,59 @@
+/**
+ * ARGO005: Application source.path should point at an existing directory (warn)
+ *
+ * When an Argo `Application` syncs from a git source it names a `source.path`
+ * inside the repo. In the common monorepo layout — Argo watches the same repo
+ * Chant builds — that path is relative to the build root, so a typo'd or moved
+ * path surfaces as a sync error only after deploy. This check warns when the
+ * path doesn't resolve to a directory under the build root.
+ *
+ * It is a warning, not an error: Applications that sync from a *different*
+ * remote repo legitimately reference paths that don't exist locally. Helm chart
+ * sources (`source.chart`) and pathless sources are skipped.
+ */
+import { existsSync, statSync } from "fs";
+import { isAbsolute, resolve } from "path";
+import type { PostSynthCheck, PostSynthContext, PostSynthDiagnostic } from "@intentius/chant/lint/post-synth";
+import { allManifests, manifestsOfKind } from "./argo-helpers";
+
+function dirExists(path: string): boolean {
+  try {
+    const full = isAbsolute(path) ? path : resolve(process.cwd(), path);
+    return existsSync(full) && statSync(full).isDirectory();
+  } catch {
+    return false;
+  }
+}
+
+export const argo005: PostSynthCheck = {
+  id: "ARGO005",
+  description: "Application source.path should resolve to an existing directory under the build root",
+
+  check(ctx: PostSynthContext): PostSynthDiagnostic[] {
+    const diagnostics: PostSynthDiagnostic[] = [];
+
+    for (const app of manifestsOfKind(allManifests(ctx), "Application")) {
+      const name = app.metadata?.name ?? "Application";
+      const source = app.spec?.source as
+        | { path?: unknown; chart?: unknown }
+        | undefined;
+      if (!source) continue;
+      // Helm chart sources have no filesystem path.
+      if (typeof source.chart === "string" && source.chart !== "") continue;
+
+      const path = source.path;
+      if (typeof path !== "string" || path === "") continue;
+      if (dirExists(path)) continue;
+
+      diagnostics.push({
+        checkId: "ARGO005",
+        severity: "warning",
+        message: `Application "${name}" source.path "${path}" does not resolve to a directory under the build root. Confirm the path (or ignore if it lives in a different repo).`,
+        entity: name,
+        lexicon: "k8s",
+      });
+    }
+
+    return diagnostics;
+  },
+};

package/dist/skills/chant-k8s-argo.md

@@ -0,0 +1,176 @@
+---
+skill: chant-k8s-argo
+description: Argo CD composites for GitOps reconciliation — ArgoAppFor, ArgoAppSetForRegions, AppProject scoping, cluster registration, and the Argo-vs-Temporal split
+user-invocable: true
+---
+
+# Argo CD Composites
+
+Chant authors typed infrastructure into manifests. Argo CD continuously reconciles those manifests into a cluster. These composites are the opt-in bridge — the k8s lexicon itself stays runtime-agnostic and only emits YAML; nothing here is implied unless you reach for it.
+
+## The three-layer model
+
+| Layer | Owns | In Chant |
+|---|---|---|
+| **Chant** | Authoring typed infra → manifests | the lexicons |
+| **Argo CD** | Continuously reconciling declarative manifests (the apply layer) | `ArgoAppFor` / `ArgoAppSetForRegions` |
+| **Temporal** | Procedural steps Argo can't express — ordering, signals, human gates, one-shot RPCs | the temporal lexicon + `waitForArgoSync` |
+
+Rule of thumb: **if it's declarative and converges, let Argo reconcile it. If it's a procedure with ordering, gates, or out-of-band steps, orchestrate it in Temporal.** Prefer Argo CD over Argo Workflows — the procedural layer stays Temporal.
+
+## Prerequisites
+
+Argo CD must be installed in the target cluster before applying any Argo CRs:
+
+```bash
+kubectl create namespace argocd
+kubectl apply -n argocd -f https://raw.githubusercontent.com/argoproj/argo-cd/v2.13.3/manifests/install.yaml
+kubectl -n argocd wait deploy/argocd-server --for=condition=Available --timeout=180s
+```
+
+## When to use which composite
+
+| Composite | Use case |
+|---|---|
+| `ArgoAppFor` | A single Chant build target reconciled by Argo |
+| `ArgoAppSetForRegions` | The same app fanned out across regions/clusters from one declaration |
+| `registerArgoCluster` | Teaching Argo about an external (non in-cluster) target |
+
+---
+
+## ArgoAppFor — one Application from a build target
+
+```typescript
+import { ArgoAppFor } from "@intentius/chant-lexicon-k8s";
+
+export const api = ArgoAppFor("api", {
+  repo: "https://github.com/acme/infra",
+  path: "dist/api",
+  destination: { server: "https://kubernetes.default.svc", namespace: "api" },
+});
+```
+
+One call replaces ~30 lines of hand-written `Application` YAML. Defaults are production-friendly:
+
+- **destination** — defaults to the in-cluster target (`https://kubernetes.default.svc`, namespace = target name) when omitted.
+- **project** — defaults to `default`. Pass `project` to scope it to a declared `AppProject`.
+- **syncPolicy** — defaults to **automated, non-pruning, self-healing** with `CreateNamespace=true`. Pass `syncPolicy: {}` for manual sync, or override fields explicitly.
+
+```typescript
+export const api = ArgoAppFor("api", {
+  repo: "https://github.com/acme/infra",
+  path: "dist/api",
+  project: "payments",
+  syncPolicy: { automated: { prune: false, selfHeal: true }, syncOptions: ["ServerSideApply=true"] },
+});
+```
+
+> **ARGO001** — on a *production* Application (name / namespace / destination namespace contains `prod`), automated `prune` must be `false` unless you opt in with the `argocd.chant.dev/allow-prune` annotation. Pruning deletes live resources that vanish from git; on prod that's a foot-gun.
+
+---
+
+## ArgoAppSetForRegions — fan out across clusters
+
+```typescript
+import { ArgoAppSetForRegions } from "@intentius/chant-lexicon-k8s";
+
+const clusterServers: Record<string, string> = {
+  east: "https://east.example.com",
+  central: "https://central.example.com",
+  west: "https://west.example.com",
+};
+
+export const crdb = ArgoAppSetForRegions(
+  ["east", "central", "west"],
+  (region) => ({
+    server: clusterServers[region],
+    namespace: `crdb-${region}`,
+    path: `dist/${region}`,
+  }),
+  { name: "crdb", repo: "https://github.com/acme/infra", project: "crdb" },
+);
+```
+
+Emits **one `ApplicationSet`** with a list generator — Argo expands it into one synced `Application` per region (`east-crdb`, `central-crdb`, `west-crdb`). The mapper resolves per-region values (`server`, `namespace`, `path`, `targetRevision`); the template interpolates them (`{{server}}`, `{{namespace}}`, `{{path}}`).
+
+> **ARGO004** — the template scopes to a **single static** `AppProject`. `ArgoAppSetForRegions` always sets a static `project`; never template it (`project: "{{...}}"`) or the set sprays Applications across projects and defeats the RBAC boundary.
+
+---
+
+## AppProject scoping
+
+An `AppProject` is the RBAC and source/destination guardrail for a group of Applications. Declare one and reference it by name:
+
+```typescript
+import { AppProject } from "@intentius/chant-lexicon-k8s";
+
+export const payments = new AppProject({
+  metadata: { name: "payments", namespace: "argocd" },
+  spec: {
+    description: "Payments team applications",
+    sourceRepos: ["https://github.com/acme/infra"],
+    destinations: [{ server: "https://kubernetes.default.svc", namespace: "payments-*" }],
+  },
+});
+```
+
+> **ARGO002** — every `Application.spec.project` must reference a declared `AppProject` (the built-in `default` is exempt). Declaring the project in the same build keeps the reference honest.
+
+---
+
+## registerArgoCluster — external clusters
+
+The in-cluster target needs no registration. For any other cluster, emit the registration Secret:
+
+```typescript
+import { registerArgoCluster } from "@intentius/chant-lexicon-k8s";
+
+export const east = registerArgoCluster({
+  name: "east",
+  server: "https://east.example.com",
+  config: { tlsClientConfig: { insecure: false }, bearerToken: process.env.EAST_TOKEN },
+});
+```
+
+Produces a `Secret` labelled `argocd.argoproj.io/secret-type: cluster`. After this, Applications can target the cluster by `destination.server: "https://east.example.com"` or `destination.name: "east"`.
+
+> **ARGO003** — every `Application.spec.destination` must reference a registered cluster (a cluster Secret) or the in-cluster target. Register external clusters before pointing Applications at them.
+
+---
+
+## The Argo-vs-Temporal split
+
+When a deploy has both declarative and procedural parts, let each layer own what it's good at. Example — the multi-region CockroachDB deploy:
+
+| Step | Owner | Why |
+|---|---|---|
+| Apply shared + regional infra | **Argo** | Declarative, converges — Argo reconciles it |
+| Install ESO / operators (Helm) | **Argo** | Declarative Helm source |
+| Apply per-cluster K8s manifests | **Argo** (`ApplicationSet`) | One App per workload cluster |
+| Wait for workloads Healthy | **Argo** (`Health=Healthy`) | Subsumed by Application health |
+| Wait for DNS delegation | **Temporal** | Signal/update/auto-poll race — out of band |
+| Generate + push TLS certs | **Temporal** | One-shot procedure, secrets not in git |
+| `cockroach init`, configure regions | **Temporal** | Ordered one-shot RPCs |
+
+From a Temporal workflow, gate procedural steps on Argo finishing a declarative apply with the `waitForArgoSync` activity (temporal lexicon, `argoSync` profile):
+
+```typescript
+// In a Temporal Op workflow:
+await waitForArgoSync({ appName: "east-crdb", namespace: "argocd" });
+// ...now run the procedural steps that depend on the workloads being Healthy.
+```
+
+`waitForArgoSync` is dependency-free — it polls the Application's status (`health=Healthy && sync=Synced`) and never imports the Argo CRD types.
+
+---
+
+## Troubleshooting
+
+| Symptom | Likely cause | Fix |
+|---|---|---|
+| Application stuck `OutOfSync` | Manual sync policy, no auto-sync | Set `syncPolicy.automated`, or sync via `argocd app sync <name>` |
+| Application `Healthy` but resources missing | Wrong `destination.namespace` or `source.path` | Check ARGO005 (path) / ARGO003 (destination) |
+| `ComparisonError: project not found` | `spec.project` references an undeclared `AppProject` | Declare the project (ARGO002) |
+| `cluster ... not found` at sync | Destination cluster not registered | `registerArgoCluster` before targeting it (ARGO003) |
+| Prod resources unexpectedly deleted | Automated `prune: true` on prod | Set `prune: false` (ARGO001) |
+| `ApplicationSet` generates apps in wrong projects | Templated `spec.project` | Pin to a single static project (ARGO004) |

package/dist/types/index.d.ts

@@ -76,6 +76,40 @@ export declare class APIVersions {
   readonly uid: string;
 }
 
+export declare class Application {
+  constructor(props: {
+    metadata: Record<string, unknown>;
+    /** ApplicationSpec represents desired application state. Contains link to repository with application definition and additional parameters link definition revision. */
+    spec: Record<string, unknown>;
+    /** Operation contains information about a requested or running operation */
+    operation?: Record<string, unknown>;
+  });
+  readonly name: string;
+  readonly namespace: string;
+  readonly uid: string;
+}
+
+export declare class ApplicationSet {
+  constructor(props: {
+    metadata: Record<string, unknown>;
+    spec: Record<string, unknown>;
+  });
+  readonly name: string;
+  readonly namespace: string;
+  readonly uid: string;
+}
+
+export declare class AppProject {
+  constructor(props: {
+    metadata: Record<string, unknown>;
+    /** AppProjectSpec is the specification of an AppProject */
+    spec: Record<string, unknown>;
+  });
+  readonly name: string;
+  readonly namespace: string;
+  readonly uid: string;
+}
+
 export declare class BatchJob {
   constructor(props: {
     /** Standard object's metadata. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#metadata */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@intentius/chant-lexicon-k8s",
-  "version": "0.1.13",
+  "version": "0.1.15",
   "description": "Kubernetes lexicon for chant — declarative IaC in TypeScript",
   "license": "Apache-2.0",
   "homepage": "https://intentius.io/chant",

package/src/codegen/docs.ts

@@ -397,6 +397,18 @@ Post-synth checks run against the serialized YAML after build.
 | WK8302 | Single replica Deployment |
 | WK8303 | HA Deployment without PodDisruptionBudget |
 
+### Argo CD
+
+Quality checks for the [Argo CD composites](/chant/lexicons/k8s/argo-composites/). ARGO001/ARGO004 are declarative (source AST); ARGO002/003/005 are post-synth (cross-resource / filesystem).
+
+| Rule | Description |
+|------|-------------|
+| ARGO001 | Production \`Application\` enables automated \`prune\` without the \`argocd.chant.dev/allow-prune\` override |
+| ARGO002 | \`Application.spec.project\` references an undeclared \`AppProject\` |
+| ARGO003 | \`Application.spec.destination\` references an unregistered cluster |
+| ARGO004 | \`ApplicationSet\` template doesn't scope to a single static \`AppProject\` |
+| ARGO005 | \`Application\` \`source.path\` doesn't resolve to a directory (warn) |
+
 ## Running lint
 
 \`\`\`bash
@@ -1139,6 +1151,7 @@ The lexicon also provides MCP (Model Context Protocol) tools and resources:
     ],
     basePath: "/chant/lexicons/k8s/",
     sidebarExtra: [
+      { label: "Argo CD Composites", slug: "argo-composites" },
       {
         label: "Vendor Composites",
         items: [

package/src/codegen/versions.ts

@@ -5,6 +5,8 @@
  * a helper to check for newer Kubernetes releases.
  */
 
+import { fetchWithRetry } from "@intentius/chant/codegen/fetch";
+
 /** Pinned versions of external dependencies. */
 export const PINNED_VERSIONS = {
   k8sOpenAPI: "v1.32.0",
@@ -24,13 +26,12 @@ export function k8sSwaggerUrl(version?: string): string {
  */
 export async function checkForUpdates(): Promise<string | null> {
   try {
-    const res = await fetch(
+    const res = await fetchWithRetry(
       "https://api.github.com/repos/kubernetes/kubernetes/releases/latest",
-      {
-        headers: { Accept: "application/vnd.github+json" },
-      },
+      undefined,
+      undefined,
+      { headers: { Accept: "application/vnd.github+json" } },
     );
-    if (!res.ok) return null;
 
     const data = (await res.json()) as { tag_name?: string };
     const latest = data.tag_name;
@@ -38,6 +39,8 @@ export async function checkForUpdates(): Promise<string | null> {
 
     return latest !== PINNED_VERSIONS.k8sOpenAPI ? latest : null;
   } catch {
+    // Transient failures are retried inside fetchWithRetry; permanent
+    // failures (or exhausted retries) land here — treat as up-to-date.
     return null;
   }
 }