@intentius/chant-lexicon-cpln 0.124.31 → 0.124.32

package/dist/api.js

@@ -0,0 +1,88 @@
+/**
+ * Minimal Control Plane REST client.
+ *
+ * Deliberately small: observation needs list-and-index, nothing more. The API
+ * is uniform enough that one `get` covers every kind — `/org/{org}/{kind}` for
+ * org-scoped, `/org/{org}/{kind}` again for the GVC-scoped rollup, which is why
+ * `collectionPath` in `kinds.ts` returns the org-wide form when no GVC is given.
+ * That rollup is what makes observation one request per kind instead of one per
+ * GVC.
+ *
+ * Credentials follow the CLI's own conventions so `chant plan` reads the org a
+ * `cpln` command in the same shell would write to. Nothing here reads a secret
+ * value: `-reveal` is never called.
+ */
+import { collectionPath } from "./kinds.js";
+/** Default API root. `CPLN_ENDPOINT` overrides it for a private deployment. */
+export const DEFAULT_ENDPOINT = "https://api.cpln.io";
+/** Thrown when there is no org or no token to read with. */
+export class CplnCredentialsError extends Error {
+}
+/**
+ * Resolve endpoint, org and token from the environment.
+ *
+ * `CPLN_TOKEN` is the documented CI variable and the one Control Plane's own
+ * guidance prefers over `--token`, which leaks into process listings and logs.
+ * A service account key works in the same header.
+ */
+export function resolveConfig(overrides = {}) {
+    const endpoint = overrides.endpoint ?? process.env.CPLN_ENDPOINT ?? DEFAULT_ENDPOINT;
+    const org = overrides.org ?? process.env.CPLN_ORG ?? "";
+    const token = overrides.token ?? process.env.CPLN_TOKEN ?? "";
+    if (!org) {
+        throw new CplnCredentialsError("No Control Plane org. Set CPLN_ORG (or pass `org`) — it is the top-level isolation boundary and " +
+            "every read path is scoped to it.");
+    }
+    if (!token) {
+        throw new CplnCredentialsError("No Control Plane token. Set CPLN_TOKEN to a service account key or a JWT. Prefer the env var over " +
+            "`--token`, which leaks into logs.");
+    }
+    return { endpoint: endpoint.replace(/\/+$/, ""), org, token };
+}
+/**
+ * Build the `Authorization` header value.
+ *
+ * The spec declares two schemes on the same header: `serviceAccountKey` is an
+ * apiKey sent bare, `jwt` is an HTTP bearer token. They are distinguishable by
+ * shape — a JWT is three base64url segments and always starts `eyJ` — so a
+ * caller does not have to say which kind of credential they have. An
+ * already-prefixed value is passed through so an explicit `Bearer …` works too.
+ */
+export function authorization(token) {
+    if (token.startsWith("Bearer "))
+        return token;
+    return /^eyJ[A-Za-z0-9_-]+\./.test(token) ? `Bearer ${token}` : token;
+}
+/** The default transport — `fetch` with the documented auth header. */
+export function defaultCplnHttp(config) {
+    return {
+        async get(path) {
+            const response = await fetch(`${config.endpoint}${path}`, {
+                headers: { Authorization: authorization(config.token), Accept: "application/json" },
+            });
+            if (response.status === 404)
+                return undefined;
+            if (!response.ok) {
+                throw new Error(`GET ${path} → ${response.status} ${response.statusText}`);
+            }
+            return response.json();
+        },
+    };
+}
+/**
+ * List every resource of one kind in the org, keyed by name.
+ *
+ * Returns an empty map for a 404, which the API uses for a kind the org has
+ * none of as well as for one the token cannot see — the distinction is not
+ * available here, and the observer treats an absent resource as absent either
+ * way.
+ */
+export async function listKind(http, config, kind) {
+    const body = (await http.get(collectionPath(kind, config.org)));
+    const index = new Map();
+    for (const item of body?.items ?? []) {
+        if (typeof item.name === "string")
+            index.set(item.name, item);
+    }
+    return index;
+}

package/dist/codegen/docs-cli.js

@@ -0,0 +1,6 @@
+#!/usr/bin/env tsx
+import { generateDocs } from "./docs.js";
+generateDocs({ verbose: true }).catch((err) => {
+    console.error(err);
+    process.exit(1);
+});

package/dist/codegen/docs.js

@@ -0,0 +1,85 @@
+/**
+ * cpln documentation generator.
+ *
+ * Calls the core `docsPipeline` with cpln-specific config. The prose pages live
+ * as authored `.mdx` under `docs/pages/`, each naming its Diátaxis quadrant in
+ * frontmatter (chant #1731 / #1733); the pipeline reads them, expands markers
+ * and builds the sidebar from the quadrant. Only the overview and the output
+ * format description stay here, because they are interpolated into generated
+ * pages rather than being pages of their own.
+ */
+import { dirname, join } from "path";
+import { fileURLToPath } from "url";
+import { docsPipeline, writeDocsSite } from "@intentius/chant/codegen/docs";
+const pkgDir = dirname(dirname(dirname(fileURLToPath(import.meta.url))));
+const overview = `The **cpln** lexicon declares [Control Plane](https://controlplane.com) infrastructure as typed chant resources. Control Plane is a hybrid multi-cloud platform: workloads deploy into Global Virtual Clouds that span AWS, GCP, Azure and private clouds, with geo-routing, TLS termination and identity-based cloud access handled by the platform.
+
+Types are generated from Control Plane's served OpenAPI document (\`https://api.cpln.io/openapi.json\`), so they track the real API.
+
+Install it with:
+
+\`\`\`bash
+npm install --save-dev @intentius/chant-lexicon-cpln
+\`\`\`
+
+## Quick Start
+
+\`\`\`typescript
+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"],   // placement is GVC-level
+    },
+  },
+});
+
+export const web = new Workload({
+  name: "web",
+  gvc: "prod",
+  spec: {
+    type: "serverless",                                       // exactly one HTTP port
+    containers: [{
+      name: "main",
+      image: "nginx:1.27",
+      ports: [{ number: 8080, protocol: "http" }],
+    }],
+    firewallConfig: {
+      external: { inboundAllowCIDR: ["0.0.0.0/0"] },          // closed by default
+    },
+  },
+});
+\`\`\`
+
+## The loop
+
+1. \`chant build\` — synthesize and lint. The CPL rules catch the silent failures Control Plane does not report: an unqualified identity link, a scale-to-zero that never happens, a secret reference with no field.
+2. \`cpln apply --file dist/cpln.yaml --ready\` — reconcile. Ordering across documents is resolved by \`cpln apply\` itself.
+3. \`chant plan\` — read the live org back and diff. Ownership comes from the \`tags\` marker chant stamps at synthesis.
+`;
+const outputFormat = "multi-document Control Plane YAML for `cpln apply --file`";
+/**
+ * Generate the documentation site for the cpln lexicon.
+ */
+export async function generateDocs(options) {
+    const config = {
+        name: "cpln",
+        displayName: "Control Plane",
+        description: "Control Plane (cpln) GVCs, workloads, identities and secrets as typed estate.",
+        distDir: join(pkgDir, "dist"),
+        outDir: join(pkgDir, "docs"),
+        srcDir: join(pkgDir, "src"),
+        basePath: process.env.DOCS_BASE_PATH ?? "/chant/lexicons/cpln/",
+        overview,
+        outputFormat,
+        serviceFromType: (type) => type.split("::")[1] ?? type,
+    };
+    const result = docsPipeline(config);
+    writeDocsSite(config, result);
+    if (options?.verbose) {
+        console.error(`Generated docs: ${result.stats.resources} resources, ${result.stats.properties} properties, ` +
+            `${result.stats.services} services, ${result.stats.rules} rules`);
+    }
+}

package/dist/codegen/generate-cli.js

@@ -0,0 +1,25 @@
+#!/usr/bin/env tsx
+/**
+ * CLI entry point for cpln lexicon generation.
+ */
+import { dirname } from "path";
+import { fileURLToPath } from "url";
+import { generate, writeGeneratedFiles } from "./generate.js";
+const pkgDir = dirname(dirname(dirname(fileURLToPath(import.meta.url))));
+async function main() {
+    const verbose = process.argv.includes("--verbose") || process.argv.includes("-v");
+    const force = process.argv.includes("--force") || process.argv.includes("-f");
+    console.error("Generating cpln lexicon...");
+    const result = await generate({ verbose, force });
+    writeGeneratedFiles(result, pkgDir);
+    console.error(`Generated ${result.resources} resources, ${result.properties} property types, ${result.enums} enums`);
+    if (result.warnings.length > 0) {
+        console.error(`${result.warnings.length} warnings:`);
+        for (const w of result.warnings)
+            console.error(`  ${w.file}: ${w.error}`);
+    }
+}
+main().catch((err) => {
+    console.error("Generation failed:", err);
+    process.exit(1);
+});

package/dist/codegen/generate-lexicon.js

@@ -0,0 +1,50 @@
+/**
+ * Lexicon registry generator — produces `lexicon-cpln.json`, the metadata the
+ * evaluator and lint engine read for each cpln resource and property type.
+ */
+import { buildRegistry, serializeRegistry, } from "@intentius/chant/codegen/generate-registry";
+import { cplnShortName, kindByTypeName } from "../kinds.js";
+/**
+ * Generate the `lexicon-cpln.json` content.
+ */
+export function generateLexiconJSON(results, naming) {
+    const registryResources = results.map((r) => ({
+        typeName: r.resource.typeName,
+        attributes: r.resource.attributes,
+        properties: r.resource.properties,
+        propertyTypes: [],
+    }));
+    // Every writable property, with its constraints — see `propertyConstraints`.
+    const byTypeName = new Map(results.map((r) => [r.resource.typeName, r]));
+    const entries = buildRegistry(registryResources, naming, {
+        shortName: cplnShortName,
+        buildEntry: (resource) => {
+            const kind = kindByTypeName(resource.typeName);
+            const entry = {
+                resourceType: resource.typeName,
+                kind: kind ? "resource" : "property",
+                lexicon: "cpln",
+            };
+            if (kind) {
+                // Carried on the entry so the serializer and observation can route a
+                // resource without re-deriving the mapping from its class name.
+                entry.cplnKind = kind.kind;
+                entry.gvcScoped = kind.gvcScoped;
+            }
+            const parsed = byTypeName.get(resource.typeName);
+            const constraints = {};
+            for (const property of parsed?.resource.properties ?? []) {
+                constraints[property.name] = property.constraints ?? {};
+            }
+            if (Object.keys(constraints).length > 0)
+                entry.propertyConstraints = constraints;
+            return entry;
+        },
+        buildPropertyEntry: (resourceType, propertyType) => ({
+            resourceType: `${resourceType}.${propertyType}`,
+            kind: "property",
+            lexicon: "cpln",
+        }),
+    });
+    return serializeRegistry(entries);
+}

package/dist/codegen/generate-typescript.js

@@ -0,0 +1,48 @@
+/**
+ * TypeScript declaration generator — produces `index.d.ts` with the eight cpln
+ * resource classes and the property-type classes their specs reach.
+ */
+import { writeResourceClass, writePropertyClass, } from "@intentius/chant/codegen/generate-typescript";
+/**
+ * Generate the complete `.d.ts` content.
+ */
+export function generateTypeScriptDeclarations(results, naming) {
+    const lines = [];
+    lines.push("// Code generated by chant cpln generate. DO NOT EDIT.");
+    const entries = [];
+    for (const r of results) {
+        const tsName = naming.resolve(r.resource.typeName);
+        if (!tsName)
+            continue;
+        entries.push({
+            tsName,
+            isProperty: !!r.isProperty,
+            properties: r.resource.properties.map((p) => ({
+                name: p.name,
+                type: p.tsType,
+                required: p.required,
+                description: p.description,
+            })),
+            attributes: r.resource.attributes.map((a) => ({ name: a.name, type: a.tsType })),
+        });
+    }
+    entries.sort((a, b) => a.tsName.localeCompare(b.tsName));
+    const resources = entries.filter((e) => !e.isProperty);
+    const propertyTypes = entries.filter((e) => e.isProperty);
+    if (resources.length > 0) {
+        lines.push("");
+        lines.push("// --- Control Plane resource classes ---");
+        for (const re of resources) {
+            writeResourceClass(lines, re.tsName, re.properties, re.attributes);
+        }
+    }
+    if (propertyTypes.length > 0) {
+        lines.push("");
+        lines.push("// --- Property type classes ---");
+        for (const pe of propertyTypes) {
+            writePropertyClass(lines, pe.tsName, pe.properties);
+        }
+    }
+    lines.push("");
+    return lines.join("\n");
+}

package/dist/codegen/generate.js

@@ -0,0 +1,86 @@
+/**
+ * cpln generation pipeline — core `generatePipeline` with cpln's fetch, parse,
+ * naming and emit callbacks.
+ */
+import { existsSync, readFileSync } from "fs";
+import { dirname, join } from "path";
+import { fileURLToPath } from "url";
+import { generatePipeline, writeGeneratedArtifacts, } from "@intentius/chant/codegen/generate";
+import { generateRuntimeIndex as coreGenerateRuntimeIndex, } from "@intentius/chant/codegen/generate-runtime-index";
+import { fetchSchemas } from "../spec/fetch.js";
+import { parseCplnOpenAPI } from "../spec/parse.js";
+import { NamingStrategy } from "./naming.js";
+import { generateLexiconJSON } from "./generate-lexicon.js";
+import { generateTypeScriptDeclarations } from "./generate-typescript.js";
+const PKG_DIR = dirname(dirname(dirname(fileURLToPath(import.meta.url))));
+const SURFACE_SNAPSHOT = join(PKG_DIR, "surface.snapshot.json");
+/**
+ * Read the committed surface snapshot, when there is one.
+ *
+ * Absent before the first publish, which is the honest state for a lexicon
+ * with no published names to protect — the naming strategy simply has nothing
+ * to reserve.
+ */
+function readSurfaceSnapshot() {
+    if (!existsSync(SURFACE_SNAPSHOT))
+        return undefined;
+    try {
+        return JSON.parse(readFileSync(SURFACE_SNAPSHOT, "utf-8"));
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Run the full cpln generation pipeline.
+ */
+export async function generate(opts = {}) {
+    const config = {
+        fetchSchemas: (fetchOpts) => fetchSchemas({ force: fetchOpts.force }),
+        // The spec is one document and `parseSchema` is called once with it; the
+        // pipeline accepts an array back, so there is no need for fly's
+        // parse-once-stash-the-rest dance.
+        parseSchema: (_typeName, data) => parseCplnOpenAPI(data),
+        createNaming: (results) => new NamingStrategy(results, { snapshot: readSurfaceSnapshot() }),
+        generateRegistry: (results, naming) => generateLexiconJSON(results, naming),
+        generateTypes: (results, naming) => generateTypeScriptDeclarations(results, naming),
+        generateRuntimeIndex: (results, naming) => buildRuntimeIndex(results, naming),
+    };
+    return generatePipeline(config, opts);
+}
+/**
+ * Write generated artifacts under `src/generated/`.
+ */
+export function writeGeneratedFiles(result, baseDir) {
+    writeGeneratedArtifacts({
+        baseDir,
+        files: {
+            "lexicon-cpln.json": result.lexiconJSON,
+            "index.d.ts": result.typesDTS,
+            "index.ts": result.indexTS,
+            "runtime.ts": `/**\n * Runtime factory constructors — re-exported from core.\n */\nexport { createResource, createProperty } from "@intentius/chant/runtime";\n`,
+        },
+    });
+}
+/**
+ * Build the runtime index with the factory constructor exports.
+ */
+function buildRuntimeIndex(results, naming) {
+    const resourceEntries = [];
+    const propertyEntries = [];
+    for (const r of results) {
+        const typeName = r.resource.typeName;
+        const tsName = naming.resolve(typeName);
+        if (!tsName)
+            continue;
+        if (r.isProperty) {
+            propertyEntries.push({ tsName, resourceType: typeName });
+            continue;
+        }
+        const attrs = {};
+        for (const attr of r.resource.attributes)
+            attrs[attr.name] = attr.name;
+        resourceEntries.push({ tsName, resourceType: typeName, attrs });
+    }
+    return coreGenerateRuntimeIndex(resourceEntries, propertyEntries, { lexiconName: "cpln" });
+}

package/dist/codegen/naming.js

@@ -0,0 +1,43 @@
+/**
+ * cpln naming strategy.
+ *
+ * Every generated type is `Cpln::Core::{Name}` with a `{Name}` the parser has
+ * already made unique — `$ref`'d schemas take their upstream name and inline
+ * shapes take their path — so the core strategy's collision phases never fire
+ * and `resolve` returns the last segment unchanged. The value of going through
+ * the core strategy anyway is phase 1a: once this lexicon publishes a surface
+ * snapshot, a name that has shipped stays attached to the type that shipped it
+ * even if an upstream reshuffle would otherwise hand it to a newcomer.
+ */
+import { NamingStrategy as CoreNamingStrategy, reservedNamesFromSnapshot, } from "@intentius/chant/codegen/naming";
+import { cplnShortName, cplnServiceName, KINDS, SERVICE } from "../kinds.js";
+export { propertyTypeName, extractDefName } from "@intentius/chant/codegen/naming";
+/**
+ * The eight kinds are pinned by hand. They are the names users type, and they
+ * should not move because a property type elsewhere in the spec started or
+ * stopped existing.
+ */
+const priorityNames = Object.fromEntries(KINDS.map((k) => [k.typeName, k.className]));
+const cplnNamingConfig = {
+    priorityNames,
+    priorityAliases: {},
+    priorityPropertyAliases: {},
+    serviceAbbreviations: { [SERVICE]: SERVICE },
+    shortName: cplnShortName,
+    serviceName: cplnServiceName,
+};
+/**
+ * cpln-specific naming strategy.
+ */
+export class NamingStrategy extends CoreNamingStrategy {
+    constructor(results, options = {}) {
+        const inputs = results.map((r) => ({
+            typeName: r.resource.typeName,
+            propertyTypes: r.propertyTypes,
+        }));
+        super(inputs, {
+            ...cplnNamingConfig,
+            reservedNames: reservedNamesFromSnapshot(options.snapshot),
+        });
+    }
+}

package/dist/codegen/package.js

@@ -0,0 +1,31 @@
+/**
+ * Package the cpln lexicon into the distributable bundle under `dist/`.
+ */
+import { readFileSync } from "fs";
+import { dirname, join } from "path";
+import { moduleSourceDir } from "@intentius/chant/module-source";
+import { packagePipeline, collectSkills } from "@intentius/chant/codegen/package";
+import { generate } from "./generate.js";
+import { cplnPlugin } from "../plugin.js";
+export async function packageLexicon(options) {
+    // This file is `src/codegen/package.ts`; rules and skills are collected
+    // relative to `src/`, so srcDir is the parent of this directory. Pointing it
+    // at `src/codegen` globs a directory that does not exist and silently ships
+    // a bundle with zero rules and zero skills.
+    const srcDir = dirname(moduleSourceDir(import.meta.url));
+    const pkgJson = JSON.parse(readFileSync(join(srcDir, "..", "package.json"), "utf-8"));
+    const { spec, stats } = await packagePipeline({
+        generate: (opts) => generate({ verbose: opts?.verbose, force: opts?.force }),
+        buildManifest: () => ({
+            name: "cpln",
+            version: pkgJson.version ?? "0.0.0",
+            chantVersion: ">=0.1.0",
+            namespace: "Cpln",
+        }),
+        srcDir,
+        collectSkills: () => collectSkills(cplnPlugin.skills?.() ?? []),
+    });
+    // Both callers (the plugin's `package()` and `package-cli`) print their own
+    // summary — don't double-report here.
+    return { spec, stats };
+}