@intentius/chant-lexicon-render 0.124.31 → 0.124.33

package/dist/ownership.js

@@ -0,0 +1,38 @@
+/**
+ * The render lexicon's ownership convention, declared here so core carries no
+ * render-specific branch — the #686 seam: each lexicon owns its key names; core
+ * keeps only the generic stamp/detect logic (@intentius/chant/ownership).
+ *
+ * Render has no tags or labels on any resource. What it does have, on the two
+ * kinds chant creates most and prunes — services and env groups — is a
+ * key/value store the API writes and reads back verbatim: environment
+ * variables. chant stamps `CHANT_MANAGED_BY=chant` (+ `CHANT_STACK` /
+ * `CHANT_ENV`) into a service's or env group's env vars at serialize time and
+ * reads them back through `GET .../env-vars`; that is the primary marker and
+ * the basis for owned-only prune. A service without it is never modified or
+ * deleted by a prune. The keys are upper-snake because that is what an env var
+ * is; the values are exactly what every other lexicon stamps.
+ *
+ * Disks and custom domains carry no marker either, but they hang off a
+ * service, so they inherit the parent's verdict — the service boundary, one
+ * level down from fly's app boundary. An undeclared disk under a chant-owned
+ * service is chant's and is pruned; one under a foreign service is foreign.
+ *
+ * Datastores, projects, environments, registry credentials, and webhooks
+ * carry no channel and no boundary. Their verdict is `unknown` (never
+ * `foreign`, never `owned`): the change set never escalates `unknown` to a
+ * delete, so an undeclared Postgres is never pruned. Removing one is an
+ * explicit `renderDelete` of a plan that names it.
+ */
+/** Env-var keys for chant's ownership markers on services and env groups. */
+export const RENDER_ENV_OWNERSHIP_KEYS = {
+    managedBy: "CHANT_MANAGED_BY",
+    stack: "CHANT_STACK",
+    env: "CHANT_ENV",
+};
+/** True when a key is one of chant's marker env vars. */
+export function isOwnershipKey(key) {
+    return (key === RENDER_ENV_OWNERSHIP_KEYS.managedBy ||
+        key === RENDER_ENV_OWNERSHIP_KEYS.stack ||
+        key === RENDER_ENV_OWNERSHIP_KEYS.env);
+}

package/dist/package-cli.js

@@ -0,0 +1,17 @@
+#!/usr/bin/env tsx
+/**
+ * Thin entry point for `npm run bundle` in lexicon-render.
+ * Generates src/generated/ files and writes dist/ bundle.
+ */
+import { packageLexicon } from "./codegen/package.js";
+import { writeBundleSpec } from "@intentius/chant/codegen/package";
+import { dirname, join } from "path";
+import { fileURLToPath } from "url";
+const pkgDir = dirname(fileURLToPath(import.meta.url));
+const distDir = join(pkgDir, "..", "dist");
+const verbose = process.argv.includes("--verbose") || !process.argv.includes("--quiet");
+const force = process.argv.includes("--force");
+const { spec, stats } = await packageLexicon({ verbose, force });
+writeBundleSpec(spec, distDir);
+console.error(`Packaged ${stats.resources} resources, ${stats.ruleCount} rules, ${stats.skillCount} skills`);
+console.error(`dist/ written to ${distDir}`);

package/dist/plugin.js

@@ -0,0 +1,229 @@
+import { createSkillsLoader } from "@intentius/chant/lexicon-plugin-helpers";
+import { renderSerializer } from "./serializer.js";
+import { rules } from "./lint/rules/index.js";
+import { postSynthChecks } from "./lint/post-synth/index.js";
+import { renderAuditCatalog } from "./lint/audit-catalog.js";
+import { completions } from "./lsp/completions.js";
+import { hover } from "./lsp/hover.js";
+import { detectTemplate as detectRenderTemplate } from "./detect.js";
+import { RENDER_ENV_OWNERSHIP_KEYS } from "./ownership.js";
+/**
+ * render lexicon plugin.
+ *
+ * Implements all required LexiconPlugin lifecycle methods.
+ */
+export const renderPlugin = {
+    name: "render",
+    // Services and env groups carry the env-var marker; describeResources reads
+    // it back. See ./ownership.ts for the two-tier story.
+    ownershipChannel: { keys: RENDER_ENV_OWNERSHIP_KEYS, reads: ["describeResources"] },
+    auditCatalog: () => renderAuditCatalog,
+    serializer: renderSerializer,
+    // ── Required lifecycle methods ────────────────────────────────
+    async generate(options) {
+        const { generate } = await import("./codegen/generate.js");
+        await generate(options);
+    },
+    async validate(options) {
+        const { validate } = await import("./validate.js");
+        const { printValidationResult } = await import("@intentius/chant/codegen/validate");
+        const result = await validate();
+        printValidationResult(result);
+    },
+    async coverage(options) {
+        const { analyzeRenderCoverage } = await import("./coverage.js");
+        await analyzeRenderCoverage({ verbose: options?.verbose, minOverall: options?.minOverall });
+    },
+    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`);
+    },
+    // ── Optional extensions ────────────────────────────────────
+    lintRules() {
+        return rules;
+    },
+    postSynthChecks() {
+        return postSynthChecks;
+    },
+    skills: createSkillsLoader(import.meta.url, [
+        {
+            file: "chant-render.md",
+            name: "chant-render",
+            description: "Author, lint, and deploy Render services, datastores, and env groups from a chant project, applied straight to the Render Public API",
+            triggers: [
+                { type: "file-pattern", value: "*.render.ts" },
+                { type: "context", value: "render" },
+                { type: "context", value: "render.com" },
+            ],
+            parameters: [
+                {
+                    name: "resourceType",
+                    type: "string",
+                    description: "Render resource type to work with (WebService, StaticSite, PrivateService, BackgroundWorker, CronJob, Postgres, KeyValue, EnvGroup, Project, Environment, Disk, CustomDomain, RegistryCredential, Webhook)",
+                },
+            ],
+            examples: [
+                {
+                    title: "Author a web service and a database",
+                    output: 'new Postgres({ name: "app-db", plan: "free", version: "16" });\nnew WebService({ name: "app-web", repo: "https://github.com/…", serviceDetails: new WebServiceDetails({ runtime: "node", envSpecificDetails: new NativeEnvironmentDetails({ buildCommand: "npm ci", startCommand: "npm start" }) }), envVars: [new EnvVar({ key: "DATABASE_URL", value: db.internalConnectionString })] })',
+                },
+                {
+                    title: "Deploy to a workspace",
+                    input: "Apply the stack to Render",
+                    output: "export RENDER_API_KEY=… RENDER_OWNER_ID=… && chant run render",
+                },
+            ],
+        },
+        {
+            file: "chant-render-patterns.md",
+            name: "chant-render-patterns",
+            description: "Render patterns in chant — env groups, projects and environments, disks, custom domains, image-backed and cron services, and the ownership model",
+            triggers: [
+                { type: "context", value: "render env group" },
+                { type: "context", value: "render disk" },
+                { type: "context", value: "render custom domain" },
+                { type: "context", value: "render cron" },
+            ],
+            parameters: [],
+            examples: [
+                {
+                    title: "Env group shared by two services",
+                    input: "Share env vars between a web service and a worker",
+                    output: 'new EnvGroup({ name: "shared", envVars: [new EnvVar({ key: "LOG_LEVEL", value: "info" })], serviceIds: [web, worker] })',
+                },
+            ],
+        },
+    ]),
+    mcpTools() {
+        // No MCP tools yet: Render's read-only context is the chant-render skills.
+        return [];
+    },
+    mcpResources() {
+        return [];
+    },
+    detectTemplate(data) {
+        return detectRenderTemplate(data);
+    },
+    pseudoParameters() {
+        return ["Render::OwnerId", "Render::Region"];
+    },
+    initTemplates(template) {
+        if (template === "database") {
+            return {
+                src: {
+                    "infra.ts": `import {
+  WebService,
+  WebServiceDetails,
+  NativeEnvironmentDetails,
+  EnvVar,
+  GeneratedEnvVar,
+  Postgres,
+  Render,
+} from "@intentius/chant-lexicon-render";
+
+// A Postgres database and a web service wired to it. The connection string is
+// read from the live database at apply time, after it exists. The owner comes
+// from Render.OwnerId (RENDER_OWNER_ID); the region from Render.Region
+// (RENDER_REGION, default "oregon").
+const db = new Postgres({
+  name: "app-db",
+  plan: "free",
+  version: "16",
+  region: Render.Region,
+});
+
+const web = new WebService({
+  name: "app-web",
+  repo: "https://github.com/render-examples/express-hello-world",
+  branch: "main",
+  serviceDetails: new WebServiceDetails({
+    runtime: "node",
+    plan: "starter",
+    region: Render.Region,
+    envSpecificDetails: new NativeEnvironmentDetails({ buildCommand: "npm ci", startCommand: "npm start" }),
+  }),
+  envVars: [
+    new EnvVar({ key: "DATABASE_URL", value: db.internalConnectionString }),
+    new GeneratedEnvVar({ key: "SESSION_SECRET", generateValue: true }),
+  ],
+});
+
+export { db, web };
+`,
+                },
+            };
+        }
+        if (template === "static") {
+            return {
+                src: {
+                    "infra.ts": `import { StaticSite, StaticSiteDetails, Route } from "@intentius/chant-lexicon-render";
+
+// A static site built from a repo and served from its publish path, with an
+// SPA rewrite. The owner comes from Render.OwnerId (RENDER_OWNER_ID).
+const site = new StaticSite({
+  name: "my-site",
+  repo: "https://github.com/render-examples/vite-react-hello-world",
+  branch: "main",
+  serviceDetails: new StaticSiteDetails({
+    buildCommand: "npm ci && npm run build",
+    publishPath: "dist",
+    routes: [new Route({ type: "rewrite", source: "/*", destination: "/index.html" })],
+  }),
+});
+
+export { site };
+`,
+                },
+            };
+        }
+        // Default: one web service — the smallest complete deploy.
+        return {
+            src: {
+                "infra.ts": `import { WebService, WebServiceDetails, NativeEnvironmentDetails, Render } from "@intentius/chant-lexicon-render";
+
+// One Render web service — the smallest complete deploy. The serializer turns
+// this into the POST /services body renderApply issues. The owner comes from
+// Render.OwnerId (RENDER_OWNER_ID); the region from Render.Region
+// (RENDER_REGION, default "oregon").
+const web = new WebService({
+  name: "my-web",
+  repo: "https://github.com/render-examples/express-hello-world",
+  branch: "main",
+  serviceDetails: new WebServiceDetails({
+    runtime: "node",
+    plan: "starter",
+    region: Render.Region,
+    envSpecificDetails: new NativeEnvironmentDetails({ buildCommand: "npm ci", startCommand: "npm start" }),
+  }),
+});
+
+export { web };
+`,
+            },
+        };
+    },
+    completionProvider(ctx) {
+        return completions(ctx);
+    },
+    hoverProvider(ctx) {
+        return hover(ctx);
+    },
+    async docs(options) {
+        const { generateDocs } = await import("./codegen/docs.js");
+        return generateDocs(options);
+    },
+    // The read-back seam for plan + drift. Lists live Render resources over the
+    // Public API, keyed by chant entity name, with an ownership verdict core's
+    // change set reads. Endpoint + auth reuse the applier (RENDER_API_BASE_URL /
+    // RENDER_API_KEY / RENDER_OWNER_ID), so it reads the same target renderApply writes.
+    async describeResources(options) {
+        const { describeResources } = await import("./describe-resources.js");
+        return describeResources(options);
+    },
+};

package/dist/pseudo.js

@@ -0,0 +1,23 @@
+import { PseudoParameter, createPseudoParameters } from "@intentius/chant/pseudo-parameter";
+export { PseudoParameter };
+/**
+ * Render pseudo-parameters — environment-resolved values a project references
+ * without hard-coding. Each serializes to a `{ Ref: "Render::..." }` marker
+ * that the serializer resolves from an environment variable at build time (see
+ * PSEUDO_ENV_MAP in ./serializer.ts), mirroring fly's `Fly.OrgSlug`.
+ *
+ *   - OwnerId → the workspace (team or personal) id (RENDER_OWNER_ID), e.g. `tea-…`.
+ *     Every ownerId chant fills in defaults to this, so a stack rarely names it.
+ *   - Region  → the target region (RENDER_REGION), default `oregon`.
+ */
+export const { OwnerId, Region } = createPseudoParameters({
+    OwnerId: "Render::OwnerId",
+    Region: "Render::Region",
+});
+/**
+ * Render namespace containing all pseudo-parameters.
+ */
+export const Render = {
+    OwnerId,
+    Region,
+};

package/dist/serializer.js

@@ -0,0 +1,238 @@
+/**
+ * Render serializer.
+ *
+ * Turns declared `WebService`, `Postgres`, `EnvGroup`, `Project`, ... resources
+ * into the JSON create bodies the Render Public API accepts, so the applier can
+ * POST them straight through.
+ *
+ * Output shape — a JSON object keyed by entity name. Each value is a single
+ * Render request plus the identity the applier reconciles by:
+ *
+ *   {
+ *     "<entityName>": {
+ *       "kind": "WebService",                       // generated class name
+ *       "entityType": "Render::Services::WebService",
+ *       "endpoint": "/services",                    // create collection
+ *       "method": "POST",
+ *       "name": "my-web",                           // reconcile key (Render has no client-chosen ids)
+ *       "body": { ... },                            // the create body
+ *       "pathParams": { "serviceId": { "$ref": "web" } }   // for child collections
+ *     }
+ *   }
+ *
+ * Cross-resource references. Render identifies resources by server-assigned
+ * ids, so a Disk's `serviceId` or an Environment's `projectId` cannot be known
+ * at build time. A declared resource passed where an id is expected serializes
+ * to `{ "$ref": "<entityName>" }`; an attribute read (`db.internalConnectionString`)
+ * to `{ "$attr": { "entity": "<entityName>", "attribute": "..." } }`. The applier
+ * resolves both once the target exists.
+ *
+ * Ownership. Every serialized service and env group carries the
+ * `CHANT_MANAGED_BY=chant` marker (plus the stack/env identity from
+ * `context.ownership`) merged into `envVars`, even when the author supplied
+ * none. See ./ownership.ts for why env vars.
+ *
+ * `ownerId`. Every owner-scoped body gets `ownerId` filled from `Render.OwnerId`
+ * (`RENDER_OWNER_ID`) when the author omitted it. When that is unset too, an
+ * `{ "$owner": true }` marker is left for the applier, which resolves it from
+ * `GET /owners` when the token sees exactly one workspace.
+ */
+import { isPropertyDeclarable, isResourceDeclarable } from "@intentius/chant/declarable";
+import { ownershipEntries, OWNERSHIP_MANAGED_BY_VALUE } from "@intentius/chant/ownership";
+import { walkValue } from "@intentius/chant/serializer-walker";
+import { INTRINSIC_MARKER } from "@intentius/chant/intrinsic";
+import { RENDER_ENV_OWNERSHIP_KEYS } from "./ownership.js";
+import { CATALOG, SERVICE_TYPE_OF, catalogEntry, isServiceEntityType } from "./catalog.js";
+export function isRefMarker(v) {
+    return !!v && typeof v === "object" && typeof v.$ref === "string";
+}
+export function isAttrMarker(v) {
+    const a = v;
+    return !!a && typeof a === "object" && !!a.$attr && typeof a.$attr.entity === "string";
+}
+export function isOwnerMarker(v) {
+    return !!v && typeof v === "object" && v.$owner === true;
+}
+/**
+ * Visitor for the generic serializer walker. Property declarables
+ * (WebServiceDetails, Image, ServiceDisk, ...) are unwrapped to plain objects;
+ * resource references and attribute reads become the applier's markers.
+ */
+function renderVisitor() {
+    return {
+        attrRef: (entity, attribute) => ({ $attr: { entity, attribute } }),
+        resourceRef: (name) => ({ $ref: name }),
+        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 result;
+        },
+    };
+}
+function readProps(entity) {
+    const props = isResourceDeclarable(entity) ? entity.props : undefined;
+    return props && typeof props === "object" ? props : {};
+}
+/**
+ * Pseudo-parameter → environment variable mapping. Render bodies are plain
+ * JSON, so `Render.OwnerId` / `Render.Region` (which the walker lowers to a
+ * `{ Ref: "Render::..." }` marker) are resolved from the environment at build
+ * time. Region has a fallback (Render's own default); the owner does not — an
+ * unset owner becomes the `$owner` marker for the applier.
+ */
+const PSEUDO_ENV_MAP = {
+    "Render::OwnerId": { envVars: ["RENDER_OWNER_ID"], fallback: { $owner: true } },
+    "Render::Region": { envVars: ["RENDER_REGION"], fallback: "oregon" },
+};
+function resolvePseudoRef(ref) {
+    const mapping = PSEUDO_ENV_MAP[ref];
+    if (!mapping)
+        return undefined;
+    for (const envVar of mapping.envVars) {
+        const value = process.env[envVar];
+        if (value)
+            return value;
+    }
+    return mapping.fallback;
+}
+/**
+ * Recursively replace pseudo-parameters with their resolved environment value.
+ * Handles both a raw `PseudoParameter` instance and the already-walked
+ * `{ Ref: "Render::X" }` shape. Everything else passes through untouched.
+ */
+export function resolvePseudoParameters(value) {
+    if (Array.isArray(value)) {
+        return value.map(resolvePseudoParameters);
+    }
+    if (value && typeof value === "object") {
+        const record = value;
+        if (INTRINSIC_MARKER in record && typeof record.toJSON === "function") {
+            return resolvePseudoParameters(record.toJSON());
+        }
+        const keys = Object.keys(record);
+        if (keys.length === 1 && keys[0] === "Ref" && typeof record.Ref === "string") {
+            const resolved = resolvePseudoRef(record.Ref);
+            if (resolved !== undefined)
+                return resolved;
+        }
+        const result = {};
+        for (const [key, val] of Object.entries(record)) {
+            result[key] = resolvePseudoParameters(val);
+        }
+        return result;
+    }
+    return value;
+}
+/** The Render name a resource gets: an explicit `name` prop, else the entity name. */
+function resourceName(props, entityName) {
+    return typeof props.name === "string" && props.name ? props.name : entityName;
+}
+/**
+ * Merge chant's ownership marker into an `envVars` list. The marker wins over
+ * any colliding user key so ownership can never be silently unset; the user's
+ * ordering is otherwise preserved.
+ */
+export function stampOwnership(envVars, marker) {
+    const list = Array.isArray(envVars) ? [...envVars] : [];
+    const out = list.filter((e) => !(e && typeof e === "object" && e.key !== undefined && e.key in marker));
+    for (const [key, value] of Object.entries(marker))
+        out.push({ key, value });
+    return out;
+}
+/**
+ * Serialize a render partition into the plan document `renderApply` consumes.
+ *
+ * Split out of the `Serializer` object so callers that need the concrete
+ * document — the applier, its tests, the `describeResources` fixtures — get
+ * `string` rather than the interface's `string | SerializerResult` union.
+ */
+export function serializeRender(entities, _outputs, context) {
+    const entityNames = new Map();
+    for (const [name, entity] of entities)
+        entityNames.set(entity, name);
+    const visitor = renderVisitor();
+    // Ownership marker. `CHANT_MANAGED_BY=chant` is always stamped; stack/env
+    // are added when the build threads an ownership marker through the context.
+    const ownershipEnv = context?.ownership
+        ? ownershipEntries(RENDER_ENV_OWNERSHIP_KEYS, context.ownership)
+        : { [RENDER_ENV_OWNERSHIP_KEYS.managedBy]: OWNERSHIP_MANAGED_BY_VALUE };
+    const requests = {};
+    for (const [entityName, entity] of entities) {
+        if (isPropertyDeclarable(entity))
+            continue;
+        const entityType = entity.entityType;
+        if (!entityType || !(entityType in CATALOG))
+            continue;
+        const entry = catalogEntry(entityType);
+        const props = readProps(entity);
+        // Body: every prop except association hints, walked so nested property
+        // declarables flatten and references become markers.
+        const body = {};
+        const pathParams = {};
+        for (const [key, value] of Object.entries(props)) {
+            if (value === undefined)
+                continue;
+            const walked = walkValue(value, entityNames, visitor);
+            if (entry.nonBodyProps.includes(key)) {
+                pathParams[key] = walked;
+            }
+            else {
+                body[key] = walked;
+            }
+        }
+        // Services: re-inject the fixed `type` discriminator the authoring
+        // surface hides, and stamp the marker.
+        if (isServiceEntityType(entityType)) {
+            body.type = SERVICE_TYPE_OF[entityType];
+        }
+        if (entry.marked) {
+            body.envVars = stampOwnership(body.envVars, ownershipEnv);
+        }
+        // Owner: fill from the pseudo-parameter when omitted; the walked value
+        // of `Render.OwnerId` is a `{ Ref }` resolved below with the rest.
+        if (entry.ownerScoped && body.ownerId === undefined) {
+            body.ownerId = { Ref: "Render::OwnerId" };
+        }
+        // `image.ownerId` must match the service's; default it the same way.
+        if (isServiceEntityType(entityType) && body.image && typeof body.image === "object") {
+            const image = body.image;
+            if (image.ownerId === undefined)
+                image.ownerId = body.ownerId;
+        }
+        // Child collections: fill the endpoint placeholder from pathParams when
+        // the value is a literal id; a `{ $ref }` stays for the applier.
+        let endpoint = entry.collection;
+        for (const [key, value] of Object.entries(pathParams)) {
+            if (typeof value === "string")
+                endpoint = endpoint.replace(`{${key}}`, encodeURIComponent(value));
+        }
+        const request = {
+            kind: entry.kind,
+            entityType,
+            endpoint,
+            method: "POST",
+            name: resourceName(props, entityName),
+            body,
+        };
+        if (Object.keys(pathParams).length > 0)
+            request.pathParams = pathParams;
+        requests[entityName] = request;
+    }
+    // Resolve pseudo-parameter markers (Render.OwnerId, Render.Region) to their
+    // environment value so bodies carry plain strings, not `{ Ref }`.
+    return JSON.stringify(resolvePseudoParameters(requests), null, 2);
+}
+/**
+ * Render serializer.
+ */
+export const renderSerializer = {
+    name: "render",
+    rulePrefix: "REN",
+    serialize: serializeRender,
+};

package/dist/spec/fetch.js

@@ -0,0 +1,30 @@
+import { join } from "path";
+import { homedir } from "os";
+import { fetchWithCache } from "@intentius/chant/codegen/fetch";
+/**
+ * Render's published Public API OpenAPI 3.0 spec.
+ *
+ * Render serves the current spec at a fixed URL with no version or release tag
+ * to pin (the document's own `info.version` has sat at "1.0.0" across many
+ * additive changes), so — like fly — the plugin declares no `upstreamPin`.
+ * Re-running `generate` picks up whatever the URL currently serves.
+ */
+export const SCHEMA_URL = "https://api-docs.render.com/v1.0/openapi/render-public-api-1.json";
+/**
+ * Cache under `~/.chant` so CI's `~/.chant` schema cache covers it — an
+ * api-docs.render.com hiccup then falls back to the cache instead of failing
+ * the generate step.
+ */
+const CACHE_FILE = join(homedir(), ".chant", "render-public-api-openapi.json");
+/**
+ * Fetch the Render OpenAPI spec and return it as a Map<typeName, Buffer>
+ * compatible with the generatePipeline fetchSchemas callback.
+ *
+ * The spec is a single document, so we return a single entry keyed by
+ * "Render::OpenAPI" — the parse step splits it into the curated resources and
+ * their reachable property types.
+ */
+export async function fetchSchemas(options) {
+    const raw = await fetchWithCache({ url: SCHEMA_URL, cacheFile: CACHE_FILE }, options?.force);
+    return new Map([["Render::OpenAPI", raw]]);
+}