@intentius/chant-lexicon-cpln 0.124.31 → 0.124.32

package/dist/plugin.js

@@ -0,0 +1,141 @@
+import { compositeCatalog } from "./composites/catalog.js";
+import { createSkillsLoader, createDiffTool, createCatalogResource } from "@intentius/chant/lexicon-plugin-helpers";
+import { cplnSerializer } from "./serializer.js";
+import { rules } from "./lint/rules/index.js";
+import { postSynthChecks } from "./lint/post-synth/index.js";
+import { cplnAuditCatalog } from "./lint/audit-catalog.js";
+import { cplnReferenceCatalog } from "./reference-catalog.js";
+import { CPLN_TAG_OWNERSHIP_KEYS } from "./ownership.js";
+import { detectCplnTemplate } from "./detect.js";
+import { cplnInitTemplates } from "./init-templates.js";
+import { completions } from "./lsp/completions.js";
+import { hover } from "./lsp/hover.js";
+/**
+ * The cpln lexicon plugin.
+ *
+ * Control Plane's `tags` map is the ownership channel, and unusually it works
+ * on the thin read: every kind carries `tags` and every read path returns
+ * them, so `describeResources` resolves a real verdict rather than `unknown`.
+ * That is why `describeResources` is declared among the channel's read paths
+ * where aws — whose `describe-stack-resources` returns no tags at all — cannot
+ * declare it.
+ *
+ * `observeResourcesDeep` and `exportResources` are not implemented yet, so
+ * they are absent from `reads` rather than listed optimistically: the contract
+ * is that a declared path resolves a verdict, and claiming one this plugin has
+ * no implementation for would be a lie the checker cannot catch.
+ */
+const ownershipChannel = {
+    keys: CPLN_TAG_OWNERSHIP_KEYS,
+    reads: ["describeResources"],
+};
+export const cplnPlugin = {
+    name: "cpln",
+    serializer: cplnSerializer,
+    // ── Required lifecycle methods ────────────────────────────────
+    async generate(options) {
+        const { generate, writeGeneratedFiles } = await import("./codegen/generate.js");
+        const { dirname } = await import("path");
+        const { fileURLToPath } = await import("url");
+        const result = await generate(options);
+        writeGeneratedFiles(result, dirname(dirname(fileURLToPath(import.meta.url))));
+    },
+    async validate() {
+        const { validate } = await import("./validate.js");
+        const { printValidationResult } = await import("@intentius/chant/codegen/validate");
+        printValidationResult(await validate());
+    },
+    async coverage(options) {
+        const { analyzeCplnCoverage } = await import("./coverage.js");
+        await analyzeCplnCoverage(options);
+    },
+    async package(options) {
+        const { packageLexicon } = await import("./codegen/package.js");
+        const { writeBundleSpec } = await import("@intentius/chant/codegen/package");
+        const { join, dirname } = await import("path");
+        const { fileURLToPath } = await import("url");
+        const { spec, stats } = await packageLexicon(options);
+        const pkgDir = dirname(dirname(fileURLToPath(import.meta.url)));
+        writeBundleSpec(spec, join(pkgDir, "dist"));
+        console.error(`Packaged ${stats.resources} resources, ${stats.ruleCount} rules, ${stats.skillCount} skills`);
+    },
+    // ── Lint and audit ────────────────────────────────────────────
+    lintRules() {
+        return rules;
+    },
+    postSynthChecks() {
+        return postSynthChecks;
+    },
+    auditCatalog: () => cplnAuditCatalog,
+    // ── Observation ───────────────────────────────────────────────
+    ownershipChannel,
+    referenceCatalog: cplnReferenceCatalog,
+    async describeResources(options) {
+        const { describeResources } = await import("./describe-resources.js");
+        return describeResources({
+            environment: options.environment,
+            buildOutput: options.buildOutput,
+            entityNames: options.entityNames,
+            entities: options.entities,
+            owned: options.owned,
+        });
+    },
+    // ── Language surface ──────────────────────────────────────────
+    completionProvider(ctx) {
+        return completions(ctx);
+    },
+    hoverProvider(ctx) {
+        return hover(ctx);
+    },
+    // ── Import and project surface ────────────────────────────────
+    detectTemplate(data) {
+        return detectCplnTemplate(data);
+    },
+    /**
+     * The three `chant init` scaffolds, named at the plugin surface so the
+     * available set is visible where a reader looks for it rather than only
+     * inside the switch that resolves them. An unrecognised name falls through
+     * to the default — `chant init` treats it as a hint, not a key.
+     */
+    initTemplates(template) {
+        if (template === "secrets")
+            return cplnInitTemplates("secrets");
+        if (template === "stateful")
+            return cplnInitTemplates("stateful");
+        return cplnInitTemplates();
+    },
+    skills: createSkillsLoader(import.meta.url, [
+        {
+            file: "chant-cpln.md",
+            name: "chant-cpln",
+            description: "Declare Control Plane (cpln) infrastructure from chant — the kinds, GVC scoping, links, and what the serializer emits",
+        },
+        {
+            file: "chant-cpln-workloads.md",
+            name: "chant-cpln-workloads",
+            description: "Choose a Control Plane workload type and configure autoscaling, Capacity AI, resources and probes correctly",
+        },
+        {
+            file: "chant-cpln-secrets.md",
+            name: "chant-cpln-secrets",
+            description: "Wire Control Plane secrets, identities and policies so a workload can actually read them",
+        },
+    ]),
+    composites() {
+        return compositeCatalog;
+    },
+    mcpTools() {
+        return [
+            createDiffTool(cplnSerializer, "Diff the current cpln manifests against the previous build output", "cpln"),
+        ];
+    },
+    mcpResources() {
+        return [
+            createCatalogResource(import.meta.url, "Control Plane Resource Catalog", "Every cpln resource and property type, with its Control Plane type name", "lexicon-cpln.json", "cpln"),
+        ];
+    },
+    async docs(options) {
+        const { generateDocs } = await import("./codegen/docs.js");
+        return generateDocs(options);
+    },
+};

package/dist/reference-catalog.js

@@ -0,0 +1,99 @@
+/**
+ * How observed cpln resources reference each other, so `chant graph --live` can
+ * rebuild the topology from a bag of nodes.
+ *
+ * Control Plane addresses resources by **link string**
+ * (`//gvc/prod/identity/api`), and edge reconstruction matches identifiers
+ * exactly, so a raw link never equals the `name` it points at. Rather than add
+ * an enrichment pass, `describeResources` resolves each link down to the bare
+ * name it ends in and files it under a stable attribute — `refs.identity`,
+ * `refs.gvc`, `refs.pullSecrets` — and the rules below read those. See
+ * {@link referenceAttributes} in `describe-resources.ts`.
+ *
+ * Names are unique per kind within an org (per GVC for the GVC-scoped kinds),
+ * so `name` is the identity for every kind and `targetKind` disambiguates the
+ * cases where two kinds could hold the same name.
+ *
+ * Containment vs reference matters for the picture: "this workload is in this
+ * GVC" is a boundary the renderer draws as a box, not a line from every
+ * resource to its GVC. It still declares `viaAttr` so a traversal can walk it —
+ * "which GVCs have no workloads" is a containment question.
+ */
+import { KINDS, kindByName } from "./kinds.js";
+const typeOf = (kind) => kindByName(kind).typeName;
+export const cplnReferenceCatalog = {
+    identities: KINDS.map((kind) => ({ kind: kind.typeName, ids: ["name"] })),
+    refs: [
+        // Every GVC-scoped resource lives inside its GVC — a boundary, not a line.
+        ...KINDS.filter((kind) => kind.gvcScoped).map((kind) => ({
+            from: kind.typeName,
+            path: "refs.gvc",
+            targetKind: typeOf("gvc"),
+            relation: "containment",
+            label: "in GVC",
+            viaAttr: "gvc",
+        })),
+        // A workload runs as one identity.
+        {
+            from: typeOf("workload"),
+            path: "refs.identity",
+            targetKind: typeOf("identity"),
+            relation: "reference",
+            label: "identity",
+            viaAttr: "identityLink",
+        },
+        // A GVC pulls private images with org-scoped secrets.
+        {
+            from: typeOf("gvc"),
+            path: "refs.pullSecrets[]",
+            targetKind: typeOf("secret"),
+            relation: "reference",
+            label: "pull secret",
+            viaAttr: "pullSecretLinks",
+        },
+        // A domain routes into a GVC, or straight at a stateful workload.
+        {
+            from: typeOf("domain"),
+            path: "refs.gvc",
+            targetKind: typeOf("gvc"),
+            relation: "reference",
+            label: "routes to",
+            viaAttr: "gvcLink",
+        },
+        {
+            from: typeOf("domain"),
+            path: "refs.workloads[]",
+            targetKind: typeOf("workload"),
+            relation: "reference",
+            label: "routes to",
+            viaAttr: "workloadLink",
+        },
+        // A policy's explicit target links.
+        {
+            from: typeOf("policy"),
+            path: "refs.targets[]",
+            targetKind: typeOf("secret"),
+            relation: "reference",
+            label: "grants on",
+            viaAttr: "targetLinks",
+        },
+        // An IP set fronts the workload it is bound to.
+        {
+            from: typeOf("ipset"),
+            path: "refs.workloads[]",
+            targetKind: typeOf("workload"),
+            relation: "reference",
+            label: "fronts",
+            viaAttr: "link",
+        },
+        // A workload mounts volume sets.
+        {
+            from: typeOf("workload"),
+            path: "refs.volumeSets[]",
+            targetKind: typeOf("volumeset"),
+            relation: "reference",
+            label: "mounts",
+            viaAttr: "volumes",
+        },
+    ],
+};

package/dist/serializer.js

@@ -0,0 +1,217 @@
+/**
+ * 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 { isResourceDeclarable } from "@intentius/chant/declarable";
+import { ownershipEntries } from "@intentius/chant/ownership";
+import { walkValue } from "@intentius/chant/serializer-walker";
+import { emitYAML } from "@intentius/chant/yaml";
+import { KINDS, kindByTypeName } from "./kinds.js";
+import { CPLN_TAG_OWNERSHIP_KEYS } from "./ownership.js";
+/**
+ * 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 = ["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 = ["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, _outputs, context) {
+        // The walker wants Declarable → name; link resolution wants the inverse.
+        const entityNames = new Map();
+        for (const [name, entity] of entities)
+            entityNames.set(entity, name);
+        const visitor = cplnVisitor(entities);
+        const documents = [];
+        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 = { 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");
+    },
+};
+// ── 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, entityNames, visitor, context) {
+    const walked = declared === undefined ? undefined : walkValue(declared, entityNames, visitor);
+    const tags = walked && typeof walked === "object" && !Array.isArray(walked) ? { ...walked } : {};
+    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, name, gvc) {
+    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) {
+    const linkFor = (logicalName) => {
+        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 = {};
+            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) {
+    const props = isResourceDeclarable(entity) ? entity.props : undefined;
+    return props && typeof props === "object" ? props : {};
+}
+/** Emit one manifest document, ordered keys first and the rest alphabetically. */
+function emitManifest(manifest) {
+    const lines = [];
+    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, value) {
+    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 = KIND_ORDER;
+/** Every modelled kind, re-exported so consumers need not reach into `kinds`. */
+export const SERIALIZED_KINDS = KINDS;

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

@@ -1 +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"}
+{"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,QAAuE,CAAC;AAElG,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/fetch.js

@@ -0,0 +1,70 @@
+/**
+ * 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`).
+ */
+import { join } from "path";
+import { homedir } from "os";
+import { readFileSync } from "fs";
+import { moduleSourceDir } from "@intentius/chant/module-source";
+import { fetchWithCache } from "@intentius/chant/codegen/fetch";
+export const SCHEMA_URL = "https://api.cpln.io/openapi.json";
+/**
+ * Cache under `~/.chant` (like fly and k8s) so CI's `~/.chant` schema cache
+ * covers it — an api.cpln.io hiccup then falls back to the cache before it
+ * falls back to the committed snapshot.
+ */
+const CACHE_FILE = join(homedir(), ".chant", "cpln-openapi.json");
+export const SNAPSHOT_FILE = join(moduleSourceDir(import.meta.url), "cpln-openapi.snapshot.json");
+/** The single map key the parser is handed. The spec is one document. */
+export 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 async function fetchSchemas(options) {
+    let raw;
+    try {
+        raw = await fetchWithCache({ url: SCHEMA_URL, cacheFile: CACHE_FILE }, options?.force);
+        // A 404 body is still a body. Parsing proves we got a spec and not an error
+        // page that would otherwise be cached and then generated from.
+        const parsed = JSON.parse(raw.toString("utf-8"));
+        if (!parsed.components?.schemas) {
+            throw new Error("response carried no components.schemas");
+        }
+        console.error(`[cpln] spec: live ${SCHEMA_URL}`);
+    }
+    catch (err) {
+        console.error(`[cpln] spec: committed snapshot — could not fetch ${SCHEMA_URL} ` +
+            `(${err instanceof Error ? err.message.split("\n")[0] : String(err)}). ` +
+            `Refresh it with \`just snapshot\` on a networked machine.`);
+        raw = readFileSync(SNAPSHOT_FILE);
+    }
+    return new Map([[SPEC_KEY, raw]]);
+}