@intentius/chant-lexicon-cpln 0.53.0

package/src/serializer.ts

@@ -0,0 +1,253 @@
+/**
+ * cpln serializer — emits the multi-document YAML that `cpln apply --file`
+ * consumes.
+ *
+ * Each declared resource becomes one document:
+ *
+ *   kind: workload
+ *   name: my-app
+ *   gvc: my-gvc
+ *   tags:
+ *     chant.intentius.io/managed-by: chant
+ *   spec:
+ *     containers:
+ *       - name: main
+ *         image: nginx:1.27
+ *
+ * Three things this file is careful about.
+ *
+ * **Only authoring surface is emitted.** Control Plane's own guidance is to
+ * export with `-o yaml-slim` rather than `-o yaml` before re-applying, because
+ * the server-side fields (`status`, `id`, `created`, `lastModified`, `links`)
+ * break `cpln apply`. Those are attributes in this lexicon rather than
+ * properties, so they never reach a document in the first place — the shape a
+ * user can declare is already the slim shape.
+ *
+ * **References become links, not names.** Control Plane addresses resources by
+ * link (`//gvc/prod/identity/api`, `//secret/db-password`), and the GVC-scoped
+ * forms have to carry the GVC. Passing a declared resource where a link is
+ * expected resolves to the right link for its kind, which is the difference
+ * between a reference that survives a rename and a hand-spelled string that
+ * does not. The identity form matters especially: the bare `//identity/NAME`
+ * that reads perfectly plausibly is *silently ignored* by Control Plane's
+ * policy engine, and is documented as a common silent failure.
+ *
+ * **Document order is stable and dependency-first.** `cpln apply` resolves
+ * ordering itself for a multi-doc file, so this is not needed for correctness —
+ * it is so the emitted file diffs cleanly between builds and reads in the order
+ * a person would write it.
+ */
+
+import type { Declarable } from "@intentius/chant/declarable";
+import { isResourceDeclarable } from "@intentius/chant/declarable";
+import type { Serializer, SerializeContext } from "@intentius/chant/serializer";
+import type { LexiconOutput } from "@intentius/chant/lexicon-output";
+import { ownershipEntries } from "@intentius/chant/ownership";
+import { walkValue, type SerializerVisitor } from "@intentius/chant/serializer-walker";
+import { emitYAML } from "@intentius/chant/yaml";
+import { KINDS, kindByTypeName, type CplnKind } from "./kinds";
+import { CPLN_TAG_OWNERSHIP_KEYS } from "./ownership";
+
+/**
+ * Document order: a GVC before anything inside it, and the org-scoped assets a
+ * workload references before the workload. Matches the order the API would
+ * accept the documents in one at a time.
+ */
+const KIND_ORDER: string[] = ["gvc", "secret", "ipset", "policy", "identity", "volumeset", "workload", "domain"];
+
+/**
+ * Manifest key order. `kind` and `name` first because that is how every
+ * Control Plane example reads; `spec` last because it is the long one.
+ */
+const KEY_ORDER: string[] = ["kind", "name", "description", "gvc", "tags"];
+
+/** Properties consumed to build the envelope rather than copied into the body. */
+const ENVELOPE_KEYS = new Set(["name", "description", "gvc", "tags"]);
+
+/**
+ * `satisfies` rather than a type annotation: `Serializer.serialize` returns
+ * `string | SerializerResult`, and cpln always emits a single YAML string.
+ * Annotating widens the export to the union and every caller — the tests
+ * included — has to narrow it back with a cast that asserts something the
+ * implementation already guarantees. `satisfies` checks the shape against the
+ * interface and keeps the narrower return type.
+ */
+export const cplnSerializer = {
+  name: "cpln",
+  rulePrefix: "CPL",
+
+  serialize(entities: Map<string, Declarable>, _outputs?: LexiconOutput[], context?: SerializeContext): string {
+    // The walker wants Declarable → name; link resolution wants the inverse.
+    const entityNames = new Map<Declarable, string>();
+    for (const [name, entity] of entities) entityNames.set(entity, name);
+
+    const visitor = cplnVisitor(entities);
+
+    const documents: Array<{ order: number; name: string; text: string }> = [];
+
+    for (const [entityName, entity] of entities) {
+      const kind = kindByTypeName(entity.entityType);
+      // Not ours. A build can mix lexicons, and each serializer sees only the
+      // entities routed to it, but skipping defensively costs nothing.
+      if (!kind) continue;
+
+      const props = readProps(entity);
+      const manifest: Record<string, unknown> = { kind: kind.kind };
+
+      // `name` falls back to the entity's own name, so a resource declared
+      // without one still round-trips rather than emitting `name: undefined`.
+      manifest.name = props.name ?? entityName;
+
+      if (props.description !== undefined) manifest.description = walkValue(props.description, entityNames, visitor);
+      if (kind.gvcScoped) manifest.gvc = walkValue(props.gvc, entityNames, visitor);
+
+      const tags = buildTags(props.tags, entityNames, visitor, context);
+      if (tags) manifest.tags = tags;
+
+      for (const [key, value] of Object.entries(props)) {
+        if (ENVELOPE_KEYS.has(key) || value === undefined) continue;
+        manifest[key] = walkValue(value, entityNames, visitor);
+      }
+
+      documents.push({
+        order: KIND_ORDER.indexOf(kind.kind),
+        name: String(manifest.name),
+        text: emitManifest(manifest),
+      });
+    }
+
+    documents.sort((a, b) => a.order - b.order || a.name.localeCompare(b.name));
+
+    return documents.map((d) => d.text).join("\n---\n");
+  },
+} satisfies Serializer;
+
+// ── Tags and ownership ─────────────────────────────────────────────
+
+/**
+ * Merge the declared tags with chant's ownership marker.
+ *
+ * The marker is stamped even when the resource declares no tags of its own —
+ * that is the whole point of it, since an unmarked resource is invisible to
+ * the owned-resource prune that lets `chant delete` be precise without a state
+ * file.
+ */
+function buildTags(
+  declared: unknown,
+  entityNames: Map<Declarable, string>,
+  visitor: SerializerVisitor,
+  context?: SerializeContext,
+): Record<string, unknown> | undefined {
+  const walked = declared === undefined ? undefined : walkValue(declared, entityNames, visitor);
+  const tags: Record<string, unknown> =
+    walked && typeof walked === "object" && !Array.isArray(walked) ? { ...(walked as Record<string, unknown>) } : {};
+
+  if (context?.ownership) {
+    Object.assign(tags, ownershipEntries(CPLN_TAG_OWNERSHIP_KEYS, context.ownership));
+  }
+
+  return Object.keys(tags).length > 0 ? tags : undefined;
+}
+
+// ── References ─────────────────────────────────────────────────────
+
+/**
+ * Build the Control Plane link for a declared resource.
+ *
+ * GVC-scoped kinds nest under their GVC. For identities in particular the
+ * nested form is not cosmetic: a policy binding written against the bare
+ * `//identity/NAME` is accepted and then ignored.
+ */
+export function cplnLink(kind: CplnKind, name: string, gvc?: unknown): string {
+  if (kind.kind === "gvc") return `//gvc/${name}`;
+  if (kind.gvcScoped) {
+    if (typeof gvc !== "string" || gvc.length === 0) {
+      throw new Error(
+        `Cannot build a link to ${kind.kind} "${name}": its \`gvc\` is not a plain string at build time. ` +
+          `GVC-scoped links must be \`//gvc/<gvc>/${kind.kind}/<name>\`, and the bare \`//${kind.kind}/<name>\` ` +
+          `form is silently ignored by Control Plane.`,
+      );
+    }
+    return `//gvc/${gvc}/${kind.kind}/${name}`;
+  }
+  return `//${kind.kind}/${name}`;
+}
+
+/**
+ * Visitor for the generic serializer walker.
+ *
+ * Property declarables unwrap to plain objects; resource references resolve to
+ * Control Plane links; attribute references have nowhere to go.
+ */
+function cplnVisitor(entities: Map<string, Declarable>): SerializerVisitor {
+  const linkFor = (logicalName: string): string => {
+    const target = entities.get(logicalName);
+    const kind = target && kindByTypeName(target.entityType);
+    if (!target || !kind) {
+      // A reference to something this lexicon does not model. The logical name
+      // is the most useful thing left to emit, and a post-synth check reports
+      // links that do not resolve.
+      return logicalName;
+    }
+    const props = readProps(target);
+    const name = typeof props.name === "string" ? props.name : logicalName;
+    return cplnLink(kind, name, props.gvc);
+  };
+
+  return {
+    attrRef: (name, attribute) => {
+      throw new Error(
+        `Cannot serialize a reference to ${name}.${attribute}: Control Plane manifests have no ` +
+          `template-time reference language, so an attribute known only after apply cannot be embedded in one. ` +
+          `Reference the resource itself — it resolves to a link — or read the attribute after apply.`,
+      );
+    },
+    resourceRef: linkFor,
+    propertyDeclarable: (entity, walk) => {
+      const props = isResourceDeclarable(entity) ? entity.props : undefined;
+      if (!props || typeof props !== "object") return undefined;
+      const result: Record<string, unknown> = {};
+      for (const [key, value] of Object.entries(props)) {
+        if (value !== undefined) result[key] = walk(value);
+      }
+      return Object.keys(result).length > 0 ? result : undefined;
+    },
+  };
+}
+
+// ── Emission ───────────────────────────────────────────────────────
+
+function readProps(entity: Declarable): Record<string, unknown> {
+  const props = isResourceDeclarable(entity) ? entity.props : undefined;
+  return props && typeof props === "object" ? (props as Record<string, unknown>) : {};
+}
+
+/** Emit one manifest document, ordered keys first and the rest alphabetically. */
+function emitManifest(manifest: Record<string, unknown>): string {
+  const lines: string[] = [];
+
+  for (const key of KEY_ORDER) {
+    if (manifest[key] !== undefined) lines.push(emitKeyValue(key, manifest[key]));
+  }
+
+  const rest = Object.keys(manifest)
+    .filter((k) => !KEY_ORDER.includes(k))
+    .sort();
+  for (const key of rest) {
+    if (manifest[key] !== undefined) lines.push(emitKeyValue(key, manifest[key]));
+  }
+
+  return `${lines.join("\n")}\n`;
+}
+
+/** Scalars get `key: value`; blocks get the value indented beneath the key. */
+function emitKeyValue(key: string, value: unknown): string {
+  const yaml = emitYAML(value, 1);
+  return yaml.startsWith("\n") ? `${key}:${yaml}` : `${key}: ${yaml}`;
+}
+
+/** Kind order used for document sorting, exported for the serializer tests. */
+export const DOCUMENT_KIND_ORDER: readonly string[] = KIND_ORDER;
+
+/** Every modelled kind, re-exported so consumers need not reach into `kinds`. */
+export const SERIALIZED_KINDS = KINDS;

package/src/skills/chant-cpln-secrets.md

@@ -0,0 +1,110 @@
+---
+skill: chant-cpln-secrets
+description: Wire Control Plane secrets, identities and policies so a workload can actually read them — the three-step path and its silent failures
+user-invocable: true
+---
+
+# Control Plane Secrets, Identities and Policies
+
+Control Plane's own documentation calls a partial version of this its **number one support issue**. The reason is worth stating up front: every way of getting it wrong fails *silently at runtime*. The API accepts the broken form, the workload starts, and the failure surfaces later as an application error.
+
+## The three steps
+
+All three are required. Missing any one produces no apply-time error.
+
+**1. The workload has an identity.**
+
+```ts
+export const identity = new Identity({ name: "web-identity", gvc: "prod" });
+
+export const web = new Workload({
+  name: "web",
+  gvc: "prod",
+  spec: { identityLink: identity, /* ... */ },
+});
+```
+
+**2. A policy grants that identity `reveal` on the secret.**
+
+```ts
+export const policy = new Policy({
+  name: "web-secrets",
+  targetKind: "secret",
+  targetLinks: ["//secret/db-password"],
+  bindings: [{
+    permissions: ["reveal"],
+    principalLinks: ["//gvc/prod/identity/web-identity"],
+  }],
+});
+```
+
+**3. The reference is field-qualified.**
+
+```ts
+env: [{ name: "DATABASE_PASSWORD", value: "cpln://secret/db-password.payload" }]
+```
+
+`SecretAccess` does steps 1 and 2, and `secretRef()` does step 3:
+
+```ts
+import { SecretAccess, secretRef } from "@intentius/chant-lexicon-cpln";
+
+export const { identity, policy } = SecretAccess({
+  name: "web-identity",
+  gvc: "prod",
+  secrets: ["db-password"],
+});
+
+// → "cpln://secret/db-password.payload"
+secretRef("db-password", "payload");
+```
+
+## The two silent failures
+
+**The principal link must be GVC-qualified.** `//identity/NAME` is accepted and ignored. Only `//gvc/GVC/identity/NAME` grants anything. (CPL013)
+
+**The secret reference must name a field.** `cpln://secret/db` resolves to nothing:
+
+| Type | Field |
+|---|---|
+| `opaque` | `.payload` |
+| `dictionary` | `.KEY` — one env var per key, or volume-mount the whole thing as a directory |
+| `userpass` | `.username`, `.password` |
+| `tls` | `.cert`, `.key` |
+| `keypair` | `.publicKey`, `.privateKey` |
+| `aws` | `.accessKey`, `.secretKey`, `.roleArn` |
+| `gcp` | unqualified — conventionally a volume-mounted JSON file |
+
+(CPL014)
+
+## Identities
+
+- **GVC-scoped and not shareable.** An identity cannot be used from another GVC — declare one per GVC with the same spec (CPL029).
+- A workload has **at most one**.
+- One cloud account per provider: one AWS + one GCP + one Azure, not two AWS.
+- Provider sections have XOR rules: AWS `roleName` ⊻ `policyRefs`, GCP `serviceAccount` ⊻ `bindings`. Network resources `IPs` ⊻ `FQDN`.
+- **Do not assign one unless the workload needs it** — secret access, credential-free cloud access, or private network access. An empty identity assignment complicates audit traces for no benefit.
+
+## Policies
+
+- `targetKind` is singular and lowercase.
+- Pick exactly one scope: `target: "all"`, `targetLinks`, or `targetQuery`.
+- `ipset`, `mk8s` and `workloadreplica` are **not** valid targets — they are governed through their parent.
+- Max 50 bindings per policy, 200 principal links per binding. Permissions must be sorted alphabetically and unique.
+- Never set `origin` — the system sets it, and a declared value reads as drift on every plan. `builtin` policies cannot be modified at all.
+
+Principal forms: `//user/EMAIL`, `//group/NAME`, `//serviceaccount/NAME`, `//gvc/GVC/identity/NAME`.
+
+(CPL043)
+
+## Secret values in source
+
+There are 12 secret types. `cpln secret create` does not exist — the CLI has a `create-<type>` variant for each.
+
+Never put credential material in a chant declaration. CPL001 fires on recognisable credential shapes — private keys, cloud access keys, JWTs, database URLs with inline passwords — at author time, where the finding has a file and a line and the credential has not yet reached git history. CPL012 catches the rest from the model: a credential-named env var set to any literal.
+
+Read the value from the environment at build time, or set it out of band with `cpln secret edit` and leave chant managing only the secret's existence and its type.
+
+## Pull secrets are GVC-level
+
+`spec.pullSecretLinks` on the GVC, not on the workload. Only `docker`, `ecr` and `gcp` types are valid as pull secrets. Images from your own org's registry need none.

package/src/skills/chant-cpln-workloads.md

@@ -0,0 +1,78 @@
+---
+skill: chant-cpln-workloads
+description: Choose a Control Plane workload type and configure autoscaling, Capacity AI, resources and probes correctly
+user-invocable: true
+---
+
+# Control Plane Workloads
+
+## Pick the type first — it is immutable
+
+Changing `type` means delete and recreate. Almost every other constraint follows from it.
+
+| | Serverless | Standard | Stateful | Cron |
+|---|:---:|:---:|:---:|:---:|
+| Ports | **exactly 1 HTTP** | 0 or more | 0 or more | **none** |
+| Scale to zero | `rps` / `concurrency` | KEDA only | KEDA only | no |
+| Persistent volumes | no | no | **yes** | no |
+| Multi-metric autoscaling | no | yes | yes | n/a |
+| `spec.job` | forbidden | forbidden | forbidden | **required** |
+| `timeoutSeconds` max | 600 | 3600 | 3600 | n/a |
+
+- **Serverless** must expose exactly one HTTP port. Zero is the common mistake and the confusing one: it deploys, reports healthy, and serves nothing (CPL020).
+- **Cron** must not expose ports and must set `spec.job.schedule`. Probes, autoscaling, `timeoutSeconds` and `debug` are all accepted and ignored, so setting them is a silent no-op (CPL021).
+- **Stateful** is the only type that mounts `ext4`/`xfs` volume sets, and the only one that supports `replicaDirect` load balancing or `workloadLink` domain routing.
+
+Max 8 containers per workload. Workload names are ≤ 49 characters and cannot end in `-headless`. Container names cannot start with `cpln-` or `debugger-`.
+
+## Resources: the ratio is the surprise
+
+Defaults are `cpu: 50m`, `memory: 128Mi`.
+
+- CPU ≥ 25 millicores, memory ≥ 32 MiB.
+- **`memory(MiB) / cpu(millicores)` ≤ 8.** So `2Gi` needs at least 256m of CPU. A memory-heavy, CPU-light workload is rejected — which surprises people coming from Kubernetes, where the two are independent. The `cpln/relaxMemoryToCpuRatio` tag raises the ceiling to 32.
+
+CPL023 checks all three, using the defaults when a value is omitted, so an unset field is checked as what it will actually become.
+
+## Autoscaling
+
+`metric` and `multi` are alternatives, not layers. `target` belongs to the single-metric form and is capped at 100 for `cpu`/`memory` (it is a utilization percentage).
+
+Scale to zero is the one worth being careful with. `minScale: 0` is accepted on any type and only *takes effect* for serverless under `rps`/`concurrency`, or standard/stateful under KEDA. Everywhere else the workload holds at one replica and the cost saving never arrives, with nothing reported (CPL026).
+
+KEDA has to be enabled on the GVC before a workload in it can use it.
+
+## Capacity AI is on by default
+
+For serverless, standard and cron. It resizes CPU and memory from observed usage, and it is **mutually exclusive** with:
+
+- CPU-utilization autoscaling — dynamic CPU moves the baseline the metric scales against.
+- Multi-metric autoscaling — needs stable baselines.
+- GPUs — GPU allocation is fixed.
+
+These conflicts are usually reached by *adding* CPU scaling or a GPU to a workload that never opted into Capacity AI, so CPL027 says which of the two it is. Turn it off with `spec.defaultOptions.capacityAI: false`.
+
+## Probes
+
+Exactly one of `exec`, `grpc`, `tcpSocket`, `httpGet` per probe. A probe with only timing fields set looks configured and checks nothing (CPL024).
+
+Defaults differ by type: readiness is TCP-on-port for serverless and **disabled** for standard, stateful and cron. And `spec.containers[].port` must match the port the process actually binds, or health checks fail.
+
+## Firewalls start closed
+
+Both directions of the external firewall are disabled by default, and the internal one is `none`.
+
+- Inbound: add CIDRs (`0.0.0.0/0` for the internet).
+- Outbound: CIDRs, or hostnames with a wildcard prefix (`*.amazonaws.com`). Hostname rules allow ports 80/443/445 only unless `outboundAllowPort` says otherwise.
+- CIDR rules take precedence over hostname rules; blocked rules take precedence over allowed ones.
+
+CPL010 flags outbound `0.0.0.0/0` — it is rarely needed and is the egress path for anything that gets a foothold. CPL011 flags internal `same-org`, which crosses the boundary the GVC exists to draw.
+
+Internal traffic between workloads in a GVC is automatically mTLS-encrypted at `WORKLOAD.GVC.cpln.local:PORT`; there is nothing to configure.
+
+## Images
+
+- Never prefix a public image with `docker.io/` — `nginx:1.27`, not `docker.io/library/nginx:1.27` (CPL041).
+- Your own org's images are `//image/NAME:TAG` in a workload spec. `<org>.registry.cpln.io` is for `docker login`/`push` only.
+- Images must be `linux/amd64` — the wrong platform is an `exec format error` at runtime, not at apply.
+- Pin a tag or digest. A scale-from-zero cold start re-pulls, so `:latest` means two replicas of one deploy can be different builds (CPL040).

package/src/skills/chant-cpln.md

@@ -0,0 +1,103 @@
+---
+skill: chant-cpln
+description: Declare Control Plane (cpln) infrastructure from chant — the kinds, GVC scoping, links, and what the serializer emits
+user-invocable: true
+---
+
+# Control Plane with chant
+
+## The shape
+
+Control Plane's hierarchy is two levels, and it decides almost everything else:
+
+```
+Org                                          (immutable, cannot be deleted)
+├── org-scoped: Secret, Policy, Domain, IpSet
+└── GVC — the placement and networking boundary
+    ├── Workload
+    ├── Identity
+    └── VolumeSet
+```
+
+This lexicon models those eight kinds. `Gvc`, `Secret`, `Policy`, `Domain` and `IpSet` are org-scoped; `Workload`, `Identity` and `VolumeSet` take a required `gvc`.
+
+```ts
+import { Gvc, Workload } from "@intentius/chant-lexicon-cpln";
+
+export const gvc = new Gvc({
+  name: "prod",
+  spec: {
+    staticPlacement: {
+      locationLinks: ["/org/acme/location/aws-us-east-1"],
+    },
+  },
+});
+
+export const web = new Workload({
+  name: "web",
+  gvc: "prod",
+  spec: {
+    type: "serverless",
+    containers: [{ name: "main", image: "nginx:1.27", ports: [{ number: 8080, protocol: "http" }] }],
+    firewallConfig: { external: { inboundAllowCIDR: ["0.0.0.0/0"] } },
+  },
+});
+```
+
+`chant build` emits multi-document YAML for `cpln apply --file`. The `gvc` property becomes the manifest's own `gvc:` key, so the file is self-contained and does not depend on a `--gvc` flag.
+
+## Pass resources, not link strings
+
+Control Plane addresses resources by link. Pass the declared resource where a link is expected and the serializer emits the right one for its kind:
+
+```ts
+export const identity = new Identity({ name: "web-identity", gvc: "prod" });
+
+export const web = new Workload({
+  name: "web",
+  gvc: "prod",
+  spec: { identityLink: identity, /* → //gvc/prod/identity/web-identity */ ... },
+});
+```
+
+This matters most for identities. The bare `//identity/NAME` form reads perfectly naturally, is accepted by the API, and is **silently ignored** — the policy applies cleanly and grants nothing. Only `//gvc/GVC/identity/NAME` works. Passing the resource is how you stop having to remember that (CPL013 catches it if you write the string by hand).
+
+Link forms, when you do need to write one:
+
+| Kind | Link |
+|---|---|
+| GVC | `//gvc/NAME` |
+| Workload / Identity / VolumeSet | `//gvc/GVC/<kind>/NAME` |
+| Secret / Policy / Domain / IpSet | `//<kind>/NAME` |
+| Location | `/org/ORG/location/<provider>-<region>` |
+| Own org's image | `//image/NAME:TAG` |
+
+`cpln://secret/NAME.FIELD` and `cpln://volumeset/NAME` are different things — runtime resolution URIs the container reads, not links between resources.
+
+## Composites
+
+Five, each encoding rules that are easy to violate by omission:
+
+- `GvcEnvironment` — GVC with locations and pull secrets. Pull secrets are GVC-level, not per workload.
+- `ServerlessService` — one HTTP port, explicit firewall, autoscaling defaults.
+- `CronJob` — schedule, no ports, no knobs cron ignores.
+- `StatefulService` — workload + volume set, mounted, with the capacity floor checked.
+- `SecretAccess` — identity + policy, GVC-qualified.
+
+## Live state
+
+Every kind carries a free-form `tags` map, and chant stamps its ownership marker there — `chant.intentius.io/managed-by: chant` plus stack and env. That is what makes `chant plan` precise without a state file: a resource carrying the marker is this stack's, one without it is never auto-deleted.
+
+Reading live state needs `CPLN_ORG` and `CPLN_TOKEN` (a service account key, or a JWT). Use the env var, not `--token` — the flag leaks into process listings and logs.
+
+```bash
+CPLN_ORG=acme CPLN_TOKEN=$(cat key) chant plan
+```
+
+## Things that are immutable
+
+Worth settling before the first apply, because the fix afterwards is delete-and-recreate:
+
+- Workload `type` and `name`.
+- VolumeSet `fileSystemType` and `performanceClass` — recreating means data loss.
+- The org itself, which cannot be deleted at all without Control Plane support.