@intentius/chant-lexicon-cpln 0.53.0

package/dist/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/dist/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/dist/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.

package/dist/spec/fetch.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Control Plane Core API OpenAPI 3.0.3 spec.
+ *
+ * `https://api.cpln.io/openapi.json` is an unversioned live endpoint: it always
+ * serves the current spec, and there is no tag, release asset, or `info.version`
+ * bump to pin against — `info.version` has read `1.0.0` for as long as the
+ * endpoint has existed. There is consequently nothing for the self-upgrade
+ * tooling to bump, so this plugin declares no `upstreamPin`, the same call fly
+ * makes for `docs.machines.dev/openapi.json`. Re-running `generate` picks up
+ * whatever the endpoint currently serves.
+ *
+ * Unlike fly, this lexicon keeps a committed offline fallback. Two reasons the
+ * live-only route was not good enough here:
+ *
+ * - The endpoint is the production API's own doc route, not a docs CDN. It is
+ *   subject to the same maintenance windows as the API, and a generate step
+ *   that fails when Control Plane is briefly unreachable makes CI a function of
+ *   someone else's uptime.
+ * - The full document is 2.8 MB, almost all of which is the `patch_*` mirror
+ *   schemas and kinds this lexicon does not model. The snapshot is pruned to
+ *   the schemas actually reachable from the modelled kinds — 23 of 106 — which
+ *   is small enough to commit, and to re-indent for a readable diff, without
+ *   turning every regeneration into a megabyte-scale change.
+ *
+ * The fallback is never silent. Both routes log which one was taken, because a
+ * fallback nobody can see is how you end up debugging types that came from
+ * somewhere you did not expect.
+ *
+ * Refresh the snapshot with `just snapshot` (see `snapshot-cli.ts`).
+ */
+export declare const SCHEMA_URL = "https://api.cpln.io/openapi.json";
+export declare const SNAPSHOT_FILE: string;
+/** The single map key the parser is handed. The spec is one document. */
+export declare const SPEC_KEY = "Cpln::OpenAPI";
+/**
+ * Fetch the Control Plane OpenAPI spec, falling back to the committed pruned
+ * snapshot when the endpoint is unreachable. Returns a single-entry map — the
+ * whole spec is one document; the parser fans it out into per-kind results.
+ */
+export declare function fetchSchemas(options?: {
+    force?: boolean;
+}): Promise<Map<string, Buffer>>;
+//# sourceMappingURL=fetch.d.ts.map

package/dist/spec/fetch.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fetch.d.ts","sourceRoot":"","sources":["../../src/spec/fetch.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AAQH,eAAO,MAAM,UAAU,qCAAqC,CAAC;AAS7D,eAAO,MAAM,aAAa,QAA8E,CAAC;AAEzG,yEAAyE;AACzE,eAAO,MAAM,QAAQ,kBAAkB,CAAC;AAExC;;;;GAIG;AACH,wBAAsB,YAAY,CAAC,OAAO,CAAC,EAAE;IAAE,KAAK,CAAC,EAAE,OAAO,CAAA;CAAE,GAAG,OAAO,CAAC,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAoB9F"}

package/dist/spec/parse.d.ts

@@ -0,0 +1,79 @@
+/**
+ * Control Plane Core API OpenAPI 3.0.3 parser.
+ *
+ * The cpln spec is one document with a schema per kind. Unlike the k8s swagger
+ * or ARM, it is mostly *inline*: `workload.spec.containers[].readinessProbe`
+ * is nested object literals all the way down, with only a handful of named
+ * `$ref` schemas (`query`, `policy_binding`, `secret_opaque`, …). So there is
+ * no upstream definition table to lift property types out of — this parser
+ * synthesizes them from the tree, which raises two questions the naming rules
+ * below answer: what to call them, and where to stop.
+ *
+ * ## Naming
+ *
+ * A `$ref`'d schema keeps its upstream name (`query` → `Query`), so a shape
+ * shared by two kinds is emitted once and both reference it. An inline object
+ * is named by its path under the nearest named ancestor
+ * (`workload.spec.containers[].readinessProbe` → `WorkloadSpecContainersReadinessProbe`).
+ * Names are long, but they are derived rather than chosen, so two runs of the
+ * generator over the same spec agree, and a property that moves in the spec
+ * produces a visible rename rather than a silent re-binding.
+ *
+ * Arrays do not contribute a segment: an array of objects and a single object
+ * yield the same class, because `containers[]` and `containers` describe the
+ * same shape.
+ *
+ * ## Where it stops
+ *
+ * One subtree is deliberately untyped: `spec.sidecar.envoy` on both `gvc` and
+ * `workload`. It is a raw Envoy bootstrap fragment that Control Plane passes
+ * through verbatim — `typed_config`, `google_grpc` channel credentials, the
+ * lot — and expanding it costs 81 property-type classes on `gvc` alone, more
+ * than four times every other shape in this lexicon combined, to type a field
+ * whose contents are Envoy's contract and not Control Plane's. It resolves to
+ * `Record<string, unknown>`; see {@link LOOSENED_PATHS}.
+ *
+ * Everything else is typed in full. That comes to 137 property types across
+ * the eight kinds, with a natural maximum depth of 6.
+ */
+import { type PropertyConstraints } from "@intentius/chant/codegen/json-schema";
+export type { PropertyConstraints };
+export interface ParsedProperty {
+    name: string;
+    tsType: string;
+    required: boolean;
+    description?: string;
+    constraints: PropertyConstraints;
+}
+export interface ParsedResource {
+    typeName: string;
+    description?: string;
+    properties: ParsedProperty[];
+    attributes: Array<{
+        name: string;
+        tsType: string;
+    }>;
+}
+export interface CplnParseResult {
+    resource: ParsedResource;
+    /** Always empty — cpln emits property types as standalone results, like fly. */
+    propertyTypes: Array<{
+        name: string;
+        defType: string;
+    }>;
+    /** Always empty — enums are inlined as string-literal unions. */
+    enums: Array<{
+        name: string;
+        values: string[];
+    }>;
+    /** Whether this entity is a property type rather than a resource. */
+    isProperty?: boolean;
+}
+/**
+ * Parse the cpln OpenAPI spec into the modelled kinds and every property type
+ * reachable from them.
+ */
+export declare function parseCplnOpenAPI(data: string | Buffer): CplnParseResult[];
+/** `volumeset_spec` → `VolumeSetSpec`, `policy_binding` → `PolicyBinding`. */
+export declare function schemaClassName(schemaName: string): string;
+//# sourceMappingURL=parse.d.ts.map

package/dist/spec/parse.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"parse.d.ts","sourceRoot":"","sources":["../../src/spec/parse.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AAEH,OAAO,EAIL,KAAK,mBAAmB,EACzB,MAAM,sCAAsC,CAAC;AAK9C,YAAY,EAAE,mBAAmB,EAAE,CAAC;AAEpC,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,OAAO,CAAC;IAClB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,WAAW,EAAE,mBAAmB,CAAC;CAClC;AAED,MAAM,WAAW,cAAc;IAC7B,QAAQ,EAAE,MAAM,CAAC;IACjB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,UAAU,EAAE,cAAc,EAAE,CAAC;IAC7B,UAAU,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;CACrD;AAED,MAAM,WAAW,eAAe;IAC9B,QAAQ,EAAE,cAAc,CAAC;IACzB,gFAAgF;IAChF,aAAa,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IACxD,iEAAiE;IACjE,KAAK,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,EAAE,CAAA;KAAE,CAAC,CAAC;IACjD,qEAAqE;IACrE,UAAU,CAAC,EAAE,OAAO,CAAC;CACtB;AA+GD;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,eAAe,EAAE,CAsEzE;AAgKD,8EAA8E;AAC9E,wBAAgB,eAAe,CAAC,UAAU,EAAE,MAAM,GAAG,MAAM,CAK1D"}

package/dist/spec/snapshot-cli.d.ts

@@ -0,0 +1,18 @@
+#!/usr/bin/env tsx
+/**
+ * Refresh the committed offline spec snapshot (`just snapshot`).
+ *
+ * Fetches the live Control Plane OpenAPI document and writes back the subset
+ * reachable from the modelled kinds. Pruning is what makes committing it
+ * reasonable: the full document is 2.8 MB of which this lexicon reads 23
+ * schemas, and the remainder is `patch_*` mirrors and kinds not modelled here
+ * — churn in a file whose whole purpose is to be a stable fallback. It is
+ * written re-indented rather than compact so upstream changes show up as a
+ * readable diff.
+ *
+ * Run this on a networked machine whenever the generated surface is meant to
+ * move, and commit the result in the same change as the regenerated types, so
+ * the snapshot and the types in the tree always describe the same API.
+ */
+export {};
+//# sourceMappingURL=snapshot-cli.d.ts.map

package/dist/spec/snapshot-cli.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"snapshot-cli.d.ts","sourceRoot":"","sources":["../../src/spec/snapshot-cli.ts"],"names":[],"mappings":";AACA;;;;;;;;;;;;;;GAcG"}