@intentius/chant-lexicon-k8s 0.1.14 → 0.1.16

package/src/plugin.ts

@@ -15,6 +15,8 @@ import { k8sSerializer } from "./serializer";
 import { hardcodedNamespaceRule } from "./lint/rules/hardcoded-namespace";
 import { latestImageTagRule } from "./lint/rules/latest-image-tag";
 import { missingResourceLimitsRule } from "./lint/rules/missing-resource-limits";
+import { argoAutomatedPruneRule } from "./lint/rules/argo-automated-prune";
+import { argoAppSetSingleProjectRule } from "./lint/rules/argo-appset-single-project";
 import { k8sCompletions } from "./lsp/completions";
 import { k8sHover } from "./lsp/hover";
 import { K8sParser } from "./import/parser";
@@ -25,7 +27,13 @@ export const k8sPlugin: LexiconPlugin = {
   serializer: k8sSerializer,
 
   lintRules(): LintRule[] {
-    return [hardcodedNamespaceRule, latestImageTagRule, missingResourceLimitsRule];
+    return [
+      hardcodedNamespaceRule,
+      latestImageTagRule,
+      missingResourceLimitsRule,
+      argoAutomatedPruneRule,
+      argoAppSetSingleProjectRule,
+    ];
   },
 
   postSynthChecks() {
@@ -566,10 +574,45 @@ const { deployment, service, serviceMonitor, prometheusRule } = MonitoredService
           },
         ],
       },
+      {
+        file: "chant-k8s-argo.md",
+        name: "chant-k8s-argo",
+        description: "Argo CD composites — ArgoAppFor, ArgoAppSetForRegions, AppProject scoping, cluster registration, and the Argo-vs-Temporal split",
+        triggers: [
+          { type: "context", value: "argo" },
+          { type: "context", value: "argo cd" },
+          { type: "context", value: "argocd" },
+          { type: "context", value: "gitops" },
+          { type: "context", value: "application" },
+          { type: "context", value: "applicationset" },
+          { type: "context", value: "appproject" },
+          { type: "context", value: "reconcile" },
+        ],
+        parameters: [],
+        examples: [
+          {
+            title: "Application from a build target",
+            description: "Reconcile a Chant build target with Argo CD",
+            input: "Deploy my api target through Argo CD",
+            output: "import { ArgoAppFor } from \"@intentius/chant-lexicon-k8s\";\n\nexport const api = ArgoAppFor(\"api\", {\n  repo: \"https://github.com/acme/infra\",\n  path: \"dist/api\",\n  destination: { server: \"https://kubernetes.default.svc\", namespace: \"api\" },\n});",
+          },
+          {
+            title: "Per-region ApplicationSet",
+            description: "Fan one app out across regional clusters",
+            input: "Deploy crdb to east, central, and west clusters via Argo",
+            output: "import { ArgoAppSetForRegions } from \"@intentius/chant-lexicon-k8s\";\n\nexport const crdb = ArgoAppSetForRegions(\n  [\"east\", \"central\", \"west\"],\n  (region) => ({ server: servers[region], namespace: `crdb-${region}`, path: `dist/${region}` }),\n  { name: \"crdb\", repo: \"https://github.com/acme/infra\", project: \"crdb\" },\n);",
+          },
+        ],
+      },
     ]),
 
   async describeResources(options) {
     const { describeResources } = await import("./describe-resources");
     return describeResources(options);
   },
+
+  async exportResources(options) {
+    const { exportResources } = await import("./export-resources");
+    return exportResources(options);
+  },
 };

package/src/serializer-ownership.test.ts

@@ -0,0 +1,44 @@
+import { describe, test, expect } from "vitest";
+import { k8sSerializer } from "./serializer";
+import { DECLARABLE_MARKER } from "@intentius/chant/declarable";
+
+function mockResource(entityType: string, props: Record<string, unknown>): any {
+  return { [DECLARABLE_MARKER]: true, lexicon: "k8s", entityType, kind: "resource", props };
+}
+
+describe("k8sSerializer ownership stamping (#119)", () => {
+  test("stamps the ownership marker as labels when context.ownership is set", () => {
+    const entities = new Map<string, any>([
+      ["web", mockResource("K8s::Apps::Deployment", { metadata: { name: "web" }, spec: { replicas: 1 } })],
+    ]);
+    const yaml = k8sSerializer.serialize(entities, [], { ownership: { stack: "billing", env: "prod" } });
+    expect(yaml).toContain("app.kubernetes.io/managed-by: chant");
+    expect(yaml).toContain("chant.intentius.io/stack: billing");
+    expect(yaml).toContain("chant.intentius.io/env: prod");
+  });
+
+  test("explicit resource labels still win over the stamped marker", () => {
+    const entities = new Map<string, any>([
+      [
+        "web",
+        mockResource("K8s::Apps::Deployment", {
+          metadata: { name: "web", labels: { "app.kubernetes.io/managed-by": "argocd" } },
+          spec: { replicas: 1 },
+        }),
+      ],
+    ]);
+    const yaml = k8sSerializer.serialize(entities, [], { ownership: { stack: "billing" } });
+    expect(yaml).toContain("app.kubernetes.io/managed-by: argocd");
+    // stack identity still stamped (no explicit override)
+    expect(yaml).toContain("chant.intentius.io/stack: billing");
+  });
+
+  test("no ownership context → no chant labels", () => {
+    const entities = new Map<string, any>([
+      ["web", mockResource("K8s::Apps::Deployment", { metadata: { name: "web" }, spec: { replicas: 1 } })],
+    ]);
+    const yaml = k8sSerializer.serialize(entities, []);
+    expect(yaml).not.toContain("app.kubernetes.io/managed-by: chant");
+    expect(yaml).not.toContain("chant.intentius.io/stack");
+  });
+});

package/src/serializer.test.ts

@@ -128,6 +128,31 @@ describe("k8sSerializer", () => {
     expect(result).not.toContain("spec:");
   });
 
+  test("Argo Application serializes with argoproj.io/v1alpha1 GVK", () => {
+    const entities = new Map<string, any>();
+    entities.set(
+      "guestbook",
+      mockResource("K8s::Argo::Application", {
+        metadata: { name: "guestbook", namespace: "argocd" },
+        spec: {
+          project: "default",
+          source: {
+            repoURL: "https://github.com/argoproj/argocd-example-apps",
+            path: "guestbook",
+            targetRevision: "HEAD",
+          },
+          destination: { server: "https://kubernetes.default.svc", namespace: "guestbook" },
+        },
+      }),
+    );
+
+    const result = k8sSerializer.serialize(entities);
+    expect(result).toContain("apiVersion: argoproj.io/v1alpha1");
+    expect(result).toContain("kind: Application");
+    expect(result).toContain("name: guestbook");
+    expect(result).toContain("project: default");
+  });
+
   test("Namespace is specless type", () => {
     const entities = new Map<string, any>();
     entities.set(

package/src/serializer.ts

@@ -8,7 +8,8 @@
 import { createRequire } from "module";
 import type { Declarable } from "@intentius/chant/declarable";
 import { isPropertyDeclarable } from "@intentius/chant/declarable";
-import type { Serializer, SerializerResult } from "@intentius/chant/serializer";
+import type { Serializer, SerializerResult, SerializeContext } from "@intentius/chant/serializer";
+import { ownershipEntries } from "@intentius/chant/ownership";
 import type { LexiconOutput } from "@intentius/chant/lexicon-output";
 import { walkValue, type SerializerVisitor } from "@intentius/chant/serializer-walker";
 import { emitYAML } from "@intentius/chant/yaml";
@@ -153,15 +154,19 @@ export const k8sSerializer: Serializer = {
   name: "k8s",
   rulePrefix: "WK8",
 
-  serialize(entities: Map<string, Declarable>, _outputs?: LexiconOutput[]): string {
+  serialize(entities: Map<string, Declarable>, _outputs?: LexiconOutput[], context?: SerializeContext): string {
     // Build reverse map: entity → name
     const entityNames = new Map<Declarable, string>();
     for (const [name, entity] of entities) {
       entityNames.set(entity, name);
     }
 
-    // Collect default labels and annotations
-    let defaultLabelEntries: Record<string, unknown> = {};
+    // Collect default labels and annotations. Ownership markers are stamped as
+    // labels, so they seed defaultLabelEntries and flow through the same merge
+    // (explicit resource labels still win).
+    let defaultLabelEntries: Record<string, unknown> = context?.ownership
+      ? { ...ownershipEntries("label", context.ownership) }
+      : {};
     let defaultAnnotationEntries: Record<string, unknown> = {};
 
     for (const [, entity] of entities) {

package/src/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) |