@ocel/transforms 0.0.0

package/README.md

@@ -0,0 +1,47 @@
+# @ocel/transforms
+
+Patch the underlying cloud resources ocel provisions, from a module ocel runs
+before it provisions anything.
+
+## Install
+
+```bash
+pnpm add -D @ocel/transforms
+```
+
+## Use
+
+Write a module, and list it in `ocel.json`:
+
+```json
+{
+  "transforms": ["./transforms/network.transform.ts"]
+}
+```
+
+```ts
+import { defineTransform } from "@ocel/transforms";
+
+export default defineTransform(({ bindings, envClass }) => ({
+  aws: {
+    function: {
+      lambda: {
+        memorySize: envClass === "production" ? 2048 : 512,
+        vpcConfig: { subnetIds: bindings.custom.network.subnetIds },
+      },
+    },
+  },
+}));
+```
+
+The keys under `aws` are the ocel resources; the keys under those are the
+Pulumi resources the provider constructs for them, typed from `@pulumi/aws`.
+
+`bindings.<type>.<name>.<property>` reads a record your own infrastructure
+published — `<type>.<name>` is the key your `ocel.json` binds under, and
+`custom.<name>` reads a record nothing declared. Run `ocel bindings generate`
+to write those names and their types down.
+
+## License
+
+MIT

package/dist/aws/index.d.ts

@@ -0,0 +1,83 @@
+import type { cloudwatch, ec2, iam, lambda, rds, s3 } from "@pulumi/aws";
+import type { Unwrap } from "@pulumi/pulumi";
+import type { Patch } from "../patch";
+/**
+ * One key per Pulumi resource the AWS provider constructs for an ocel resource,
+ * named after the pulumi-aws module it comes from.
+ */
+export interface AwsResourceArgs {
+    function: {
+        lambda: lambda.FunctionArgs;
+        url: lambda.FunctionUrlArgs;
+        urlPermission: lambda.PermissionArgs;
+        logGroup: cloudwatch.LogGroupArgs;
+        role: iam.RoleArgs;
+    };
+    bucket: {
+        bucket: s3.BucketV2Args;
+        publicAccessBlock: s3.BucketPublicAccessBlockArgs;
+        cors: s3.BucketCorsConfigurationV2Args;
+        uploadCompleterRole: iam.RoleArgs;
+        uploadCompleterS3Policy: iam.RolePolicyArgs;
+        uploadCompleterSessionsPolicy: iam.RolePolicyArgs;
+        uploadCompleterLogsPolicy: iam.RolePolicyAttachmentArgs;
+        uploadCompleterLogGroup: cloudwatch.LogGroupArgs;
+        uploadCompleter: lambda.FunctionArgs;
+        uploadCompleterPermission: lambda.PermissionArgs;
+        notification: s3.BucketNotificationArgs;
+    };
+    postgres: {
+        securityGroup: ec2.SecurityGroupArgs;
+        subnetGroup: rds.SubnetGroupArgs;
+        cluster: rds.ClusterArgs;
+        instance: rds.ClusterInstanceArgs;
+    };
+}
+/** The ocel resource types the AWS provider renders patchable resources for. */
+export type AwsResourceType = keyof AwsResourceArgs;
+/**
+ * The fields ocel fills from its own state — the names it minted, the ARNs it
+ * created, the code it uploaded and the runtime that code was built for, the
+ * environment it sealed, the tags it sweeps by. A patch naming one is refused
+ * where it is written, and the deploy refuses it again by name.
+ */
+export declare const awsOwnedFields: {
+    readonly function: {
+        readonly lambda: readonly ["architectures", "code", "environment", "handler", "imageUri", "layers", "loggingConfig", "name", "packageType", "role", "runtime", "s3Bucket", "s3Key", "s3ObjectVersion", "sourceCodeHash", "tags"];
+        readonly url: readonly ["authorizationType", "functionName", "qualifier"];
+        readonly urlPermission: readonly ["action", "function", "functionUrlAuthType", "principal", "qualifier"];
+        readonly logGroup: readonly ["name", "namePrefix", "tags"];
+        readonly role: readonly ["assumeRolePolicy", "inlinePolicies", "managedPolicyArns", "name", "namePrefix", "permissionsBoundary", "tags"];
+    };
+    readonly bucket: {
+        readonly bucket: readonly ["bucket", "bucketPrefix", "tags"];
+        readonly publicAccessBlock: readonly ["bucket"];
+        readonly cors: readonly ["bucket"];
+        readonly uploadCompleterRole: readonly ["assumeRolePolicy", "inlinePolicies", "managedPolicyArns", "name", "namePrefix", "permissionsBoundary", "tags"];
+        readonly uploadCompleterS3Policy: readonly ["name", "namePrefix", "policy", "role"];
+        readonly uploadCompleterSessionsPolicy: readonly ["name", "namePrefix", "policy", "role"];
+        readonly uploadCompleterLogsPolicy: readonly ["policyArn", "role"];
+        readonly uploadCompleterLogGroup: readonly ["name", "namePrefix", "tags"];
+        readonly uploadCompleter: readonly ["architectures", "code", "environment", "handler", "imageUri", "loggingConfig", "name", "packageType", "role", "runtime", "s3Bucket", "s3Key", "s3ObjectVersion", "sourceCodeHash", "tags"];
+        readonly uploadCompleterPermission: readonly ["action", "function", "principal", "qualifier", "sourceArn"];
+        readonly notification: readonly ["bucket", "lambdaFunctions"];
+    };
+    readonly postgres: {
+        readonly securityGroup: readonly ["name", "namePrefix", "tags", "vpcId"];
+        readonly subnetGroup: readonly ["name", "namePrefix", "subnetIds", "tags"];
+        readonly cluster: readonly ["clusterIdentifier", "clusterIdentifierPrefix", "databaseName", "dbSubnetGroupName", "engine", "manageMasterUserPassword", "masterPassword", "masterUsername", "tags", "vpcSecurityGroupIds"];
+        readonly instance: readonly ["clusterIdentifier", "engine", "engineVersion", "identifier", "identifierPrefix", "tags"];
+    };
+};
+type AwsOwned = typeof awsOwnedFields;
+type OwnedNames<L> = L extends readonly (infer F)[] ? Extract<F, string> : never;
+/**
+ * What a rule may patch under `aws`, typed from the args pulumi-aws takes with
+ * the fields ocel owns removed. A binding output stands in for any leaf.
+ */
+export type AwsSurfaces = {
+    [T in AwsResourceType]: {
+        [K in keyof AwsResourceArgs[T]]: Patch<Omit<Unwrap<AwsResourceArgs[T][K]>, OwnedNames<AwsOwned[T][K & keyof AwsOwned[T]]>>>;
+    };
+};
+export {};

package/dist/aws/index.js

@@ -0,0 +1,101 @@
+/**
+ * The fields ocel fills from its own state — the names it minted, the ARNs it
+ * created, the code it uploaded and the runtime that code was built for, the
+ * environment it sealed, the tags it sweeps by. A patch naming one is refused
+ * where it is written, and the deploy refuses it again by name.
+ */
+export const awsOwnedFields = {
+    function: {
+        lambda: [
+            "architectures",
+            "code",
+            "environment",
+            "handler",
+            "imageUri",
+            "layers",
+            "loggingConfig",
+            "name",
+            "packageType",
+            "role",
+            "runtime",
+            "s3Bucket",
+            "s3Key",
+            "s3ObjectVersion",
+            "sourceCodeHash",
+            "tags",
+        ],
+        url: ["authorizationType", "functionName", "qualifier"],
+        urlPermission: ["action", "function", "functionUrlAuthType", "principal", "qualifier"],
+        logGroup: ["name", "namePrefix", "tags"],
+        role: [
+            "assumeRolePolicy",
+            "inlinePolicies",
+            "managedPolicyArns",
+            "name",
+            "namePrefix",
+            "permissionsBoundary",
+            "tags",
+        ],
+    },
+    bucket: {
+        bucket: ["bucket", "bucketPrefix", "tags"],
+        publicAccessBlock: ["bucket"],
+        cors: ["bucket"],
+        uploadCompleterRole: [
+            "assumeRolePolicy",
+            "inlinePolicies",
+            "managedPolicyArns",
+            "name",
+            "namePrefix",
+            "permissionsBoundary",
+            "tags",
+        ],
+        uploadCompleterS3Policy: ["name", "namePrefix", "policy", "role"],
+        uploadCompleterSessionsPolicy: ["name", "namePrefix", "policy", "role"],
+        uploadCompleterLogsPolicy: ["policyArn", "role"],
+        uploadCompleterLogGroup: ["name", "namePrefix", "tags"],
+        uploadCompleter: [
+            "architectures",
+            "code",
+            "environment",
+            "handler",
+            "imageUri",
+            "loggingConfig",
+            "name",
+            "packageType",
+            "role",
+            "runtime",
+            "s3Bucket",
+            "s3Key",
+            "s3ObjectVersion",
+            "sourceCodeHash",
+            "tags",
+        ],
+        uploadCompleterPermission: ["action", "function", "principal", "qualifier", "sourceArn"],
+        notification: ["bucket", "lambdaFunctions"],
+    },
+    postgres: {
+        securityGroup: ["name", "namePrefix", "tags", "vpcId"],
+        subnetGroup: ["name", "namePrefix", "subnetIds", "tags"],
+        cluster: [
+            "clusterIdentifier",
+            "clusterIdentifierPrefix",
+            "databaseName",
+            "dbSubnetGroupName",
+            "engine",
+            "manageMasterUserPassword",
+            "masterPassword",
+            "masterUsername",
+            "tags",
+            "vpcSecurityGroupIds",
+        ],
+        instance: [
+            "clusterIdentifier",
+            "engine",
+            "engineVersion",
+            "identifier",
+            "identifierPrefix",
+            "tags",
+        ],
+    },
+};

package/dist/define.d.ts

@@ -0,0 +1,71 @@
+import type { AwsSurfaces } from "./aws";
+import type { TransformBindings } from "./index";
+import type { VpsSurfaces } from "./vps";
+/** The environment classes a deploy can target. */
+export type EnvClass = "development" | "preview" | "production";
+/**
+ * What a rule's `if` gate is allowed to decide on: the environment being
+ * deployed and the app a candidate resource belongs to. Resources shared
+ * across apps carry no `app`, so `ctx.app === "api"` is false for them.
+ */
+export interface GateContext {
+    readonly envClass: EnvClass;
+    readonly env: string;
+    readonly app: string | undefined;
+}
+/** Decides whether a rule applies, from ambient context alone. */
+export type Gate = (ctx: GateContext) => boolean;
+/**
+ * Tags a rule unions into every taggable resource it reaches. Keys under the
+ * `ocel:` prefix are ocel's own and are rejected at deploy.
+ */
+export type TagMap = Record<string, string>;
+/** The prefix ocel reserves for the tags it writes itself. */
+export declare const reservedTagPrefix = "ocel:";
+/** What a provider renders that a transform may patch, keyed by provider name. */
+export interface ProviderSurfaces {
+    aws: AwsSurfaces;
+    vps: VpsSurfaces;
+}
+/** The providers that render patchable resources. */
+export type ProviderName = keyof ProviderSurfaces;
+/**
+ * One rule: an optional gate, tags to union into every resource it reaches,
+ * and a patch per underlying resource, under the provider that renders it.
+ */
+export type TransformRule = {
+    readonly if?: Gate;
+    readonly tags?: TagMap;
+} & {
+    readonly [P in ProviderName]?: {
+        readonly [T in keyof ProviderSurfaces[P]]?: {
+            readonly [K in keyof ProviderSurfaces[P][T]]?: ProviderSurfaces[P][T][K];
+        };
+    };
+};
+/** Keys a rule may carry besides the providers it targets. */
+export declare const ruleKeywords: readonly ["if", "tags"];
+/** What a callback form of `defineTransform` is handed, and nothing besides. */
+export interface TransformInputs {
+    readonly bindings: TransformBindings;
+    readonly envClass: EnvClass;
+    readonly env: string;
+}
+/** The rules a module contributes, written down or returned from the callback. */
+export type TransformRules = TransformRule | readonly TransformRule[];
+/** A module's default export: the rules it contributes, once the deploy asks. */
+export interface TransformDefinition {
+    readonly rules: (inputs: TransformInputs) => readonly TransformRule[];
+}
+/**
+ * Declares the rules a transform module contributes. Rules apply in the order
+ * written, and modules in the order `transforms` lists them, later winning.
+ *
+ * The callback form is handed the environment being deployed and `bindings`,
+ * the placeholders for the records bound to this project:
+ * `bindings.custom.network.subnetIds` is filled by the deploy, so the rules
+ * stay data a reviewer can read.
+ */
+export declare function defineTransform(rules: TransformRules | ((inputs: TransformInputs) => TransformRules)): TransformDefinition;
+/** Whether a module's default export came from `defineTransform`. */
+export declare function isTransformDefinition(value: unknown): value is TransformDefinition;

package/dist/define.js

@@ -0,0 +1,29 @@
+/** The prefix ocel reserves for the tags it writes itself. */
+export const reservedTagPrefix = "ocel:";
+/** Keys a rule may carry besides the providers it targets. */
+export const ruleKeywords = ["if", "tags"];
+/**
+ * Declares the rules a transform module contributes. Rules apply in the order
+ * written, and modules in the order `transforms` lists them, later winning.
+ *
+ * The callback form is handed the environment being deployed and `bindings`,
+ * the placeholders for the records bound to this project:
+ * `bindings.custom.network.subnetIds` is filled by the deploy, so the rules
+ * stay data a reviewer can read.
+ */
+export function defineTransform(rules) {
+    return {
+        rules: (inputs) => {
+            const authored = typeof rules === "function" ? rules(inputs) : rules;
+            return Array.isArray(authored)
+                ? authored
+                : [authored];
+        },
+    };
+}
+/** Whether a module's default export came from `defineTransform`. */
+export function isTransformDefinition(value) {
+    return (typeof value === "object" &&
+        value !== null &&
+        typeof value.rules === "function");
+}

package/dist/evaluate.d.ts

@@ -0,0 +1,42 @@
+import { type EnvClass, type TagMap, type TransformDefinition } from "./define";
+/**
+ * What one ocel resource's rules came to: a patch per underlying resource the
+ * provider constructs for it, keyed by the same key the rules were written
+ * under and carrying the provider SDK's own property names.
+ */
+export type Patches = Record<string, Record<string, unknown>>;
+/** One resource the deploy offers the modules, as the deploy addresses it. */
+export interface RequestResource {
+    readonly type: string;
+    readonly name: string;
+    readonly app?: string;
+}
+/** What a deploy asks the modules about: the environment, and every candidate in it. */
+export interface EvaluateRequest {
+    readonly provider: string;
+    readonly envClass: EnvClass;
+    readonly env: string;
+    readonly resources: readonly RequestResource[];
+}
+/** What the modules came to for one candidate, in the order the request listed it. */
+export interface EvaluatedResource {
+    readonly name: string;
+    readonly patches: Patches;
+    readonly tags: TagMap;
+}
+/** The answer to one request, one entry per candidate the request carried. */
+export interface EvaluateResponse {
+    readonly resources: readonly EvaluatedResource[];
+}
+/** A loaded module, paired with the specifier a refusal names it by. */
+export interface TransformModule {
+    readonly specifier: string;
+    readonly definition: TransformDefinition;
+}
+/**
+ * Applies the modules in order to every candidate the deploy offers, later
+ * modules winning. A rule that names a field ocel owns, a resource this
+ * provider does not construct, or a provider this project does not deploy to
+ * throws where it was written, and the deploy stops.
+ */
+export declare function evaluate(request: EvaluateRequest, modules: readonly TransformModule[]): EvaluateResponse;

package/dist/evaluate.js

@@ -0,0 +1,135 @@
+import { awsOwnedFields } from "./aws";
+import { reservedTagPrefix, ruleKeywords, } from "./define";
+import { bindings, isBindingOutput } from "./output";
+import { vpsOwnedFields } from "./vps";
+const ownedFields = {
+    aws: awsOwnedFields,
+    vps: vpsOwnedFields,
+};
+/**
+ * Applies the modules in order to every candidate the deploy offers, later
+ * modules winning. A rule that names a field ocel owns, a resource this
+ * provider does not construct, or a provider this project does not deploy to
+ * throws where it was written, and the deploy stops.
+ */
+export function evaluate(request, modules) {
+    const loaded = modules.map((module) => load(request, module));
+    return {
+        resources: request.resources.map((resource) => evaluateResource(request, resource, loaded)),
+    };
+}
+function load(request, module) {
+    const rules = module.definition.rules({
+        bindings: bindings,
+        envClass: request.envClass,
+        env: request.env,
+    });
+    const branches = new Set();
+    for (const rule of rules) {
+        for (const key of Object.keys(rule)) {
+            if (ruleKeywords.includes(key))
+                continue;
+            branches.add(key);
+        }
+    }
+    if (!branches.has(request.provider)) {
+        throw new Error(`${module.specifier} patches ${listed(branches)} and this project deploys to ${request.provider}; give the module an ${request.provider} branch, or drop it from "transforms"`);
+    }
+    return { specifier: module.specifier, rules };
+}
+function listed(branches) {
+    const names = [...branches].sort();
+    if (names.length === 0)
+        return "no provider";
+    return names.join(", ");
+}
+function evaluateResource(request, resource, modules) {
+    const patches = {};
+    const tags = {};
+    const ctx = Object.freeze({
+        envClass: request.envClass,
+        env: request.env,
+        app: resource.app,
+    });
+    for (const module of modules) {
+        for (const rule of module.rules) {
+            checkRuleKeys(module.specifier, rule, request.provider);
+            if (rule.if !== undefined && !rule.if(ctx))
+                continue;
+            collectTags(module.specifier, rule.tags, tags);
+            const branch = rule[request.provider];
+            if (branch === undefined)
+                continue;
+            const group = readGroup(module.specifier, request.provider, branch, resource.type);
+            if (group === undefined)
+                continue;
+            for (const [key, patch] of Object.entries(group)) {
+                if (patch === undefined)
+                    continue;
+                applyPatch(module.specifier, request.provider, resource.type, key, patch, patches);
+            }
+        }
+    }
+    return { name: resource.name, patches, tags };
+}
+function checkRuleKeys(specifier, rule, provider) {
+    for (const key of Object.keys(rule)) {
+        if (ruleKeywords.includes(key))
+            continue;
+        if (key === provider)
+            continue;
+        if (Object.hasOwn(ownedFields, key))
+            continue;
+        throw new Error(`${specifier}: a rule targets ${key}, which is neither a provider nor ${ruleKeywords.join(", ")}`);
+    }
+}
+function collectTags(specifier, authored, tags) {
+    if (authored === undefined)
+        return;
+    for (const [key, value] of Object.entries(authored)) {
+        if (key.startsWith(reservedTagPrefix)) {
+            throw new Error(`${specifier}: tag ${key} is ocel's own — the ${reservedTagPrefix} prefix is reserved`);
+        }
+        tags[key] = value;
+    }
+}
+function readGroup(specifier, provider, branch, type) {
+    const known = ownedFields[provider];
+    if (known === undefined) {
+        throw new Error(`${specifier}: this build renders nothing for ${provider}`);
+    }
+    const rendered = branch;
+    for (const key of Object.keys(rendered)) {
+        if (!Object.hasOwn(known, key)) {
+            throw new Error(`${specifier}: a rule patches ${provider}.${key}, which is not a resource this provider renders (it renders ${Object.keys(known).join(", ")})`);
+        }
+    }
+    const group = rendered[type];
+    return group === undefined ? undefined : group;
+}
+function applyPatch(specifier, provider, type, key, patch, into) {
+    const owned = ownedFields[provider]?.[type]?.[key];
+    if (owned === undefined) {
+        const rendered = Object.keys(ownedFields[provider]?.[type] ?? {}).join(", ");
+        throw new Error(`${specifier}: a rule patches ${provider}.${type}.${key}, which this provider does not construct (it constructs ${rendered})`);
+    }
+    const fields = patch;
+    for (const field of Object.keys(fields)) {
+        if (owned.includes(field)) {
+            throw new Error(`${specifier}: a rule sets ${provider}.${type}.${key}.${field}, which ocel fills from what this deploy built; drop it and let ocel own it`);
+        }
+    }
+    into[key] = mergePatch(into[key] ?? {}, fields);
+}
+function mergePatch(base, over) {
+    if (!plainObject(base) || !plainObject(over))
+        return over;
+    const merged = { ...base };
+    for (const [key, value] of Object.entries(over)) {
+        merged[key] = mergePatch(merged[key], value);
+    }
+    return merged;
+}
+function plainObject(value) {
+    return (typeof value === "object" && value !== null && !Array.isArray(value) && !isBindingOutput(value));
+}

package/dist/index.d.ts

@@ -0,0 +1,31 @@
+export type { EnvClass, Gate, GateContext, ProviderName, ProviderSurfaces, TagMap, TransformDefinition, TransformInputs, TransformRule, TransformRules, } from "./define";
+export { defineTransform } from "./define";
+export type { Patch } from "./patch";
+import { type BindingPlaceholdersOf } from "./output";
+/**
+ * The records this project's config binds, keyed by resource type and then by
+ * the name the config keys them under, with `custom` holding the records
+ * nothing declared. `ocel bindings generate` writes an augmentation of this
+ * interface from the records themselves; until something does, every name is
+ * open and the deploy is what checks it.
+ */
+export interface Bindings {
+}
+/**
+ * Whether `ocel bindings generate` has written the records down. It augments this
+ * separately from `Bindings`, so a coordinate that published nothing still closes
+ * `Bindings` to the empty set instead of reading as never generated.
+ */
+export interface BindingsGenerated {
+}
+/** The placeholders a transform module reads, narrowed by whatever was generated. */
+export type TransformBindings = BindingPlaceholdersOf<Bindings, BindingsGenerated>;
+/**
+ * The records a transform module reads, one placeholder per property named.
+ * Nothing is resolved here: `bindings.custom.network.subnetIds` is the
+ * instruction the deploy carries out against the records published to the
+ * environment it targets.
+ */
+export declare const bindings: TransformBindings;
+export type { BindingNames, BindingOutput, BindingOutputRef, BindingPlaceholders, BindingPlaceholdersOf, BindingProperties, Linked, } from "./output";
+export { isBindingOutput } from "./output";

package/dist/index.js

@@ -0,0 +1,10 @@
+export { defineTransform } from "./define";
+import { bindings as openBindings } from "./output";
+/**
+ * The records a transform module reads, one placeholder per property named.
+ * Nothing is resolved here: `bindings.custom.network.subnetIds` is the
+ * instruction the deploy carries out against the records published to the
+ * environment it targets.
+ */
+export const bindings = openBindings;
+export { isBindingOutput } from "./output";

package/dist/output.d.ts

@@ -0,0 +1,57 @@
+/** The key a binding output rides under from a transform module to the deploy. */
+export declare const outputPlaceholderKey = "$ocelOutput";
+/** What the deploy resolves an output from: one property of one bound record. */
+export interface BindingOutputRef {
+    readonly type: string;
+    readonly name: string;
+    readonly property: string;
+}
+declare const resolvedValue: unique symbol;
+/**
+ * A value the deploy reads from a record your own infrastructure published, in
+ * place of one a transform module could write down. It is resolved provider-side
+ * against the records published to the environment being deployed, so a module
+ * never holds the value itself.
+ */
+export interface BindingOutput<T = unknown> {
+    readonly [outputPlaceholderKey]: BindingOutputRef;
+    readonly [resolvedValue]?: T;
+}
+/** A leaf a transform may fill with either an authored value or a binding output. */
+export type Linked<T> = T | BindingOutput<T>;
+/** The properties one record carries, each read as a binding output. */
+export type BindingProperties = {
+    readonly [property: string]: BindingOutput<any>;
+};
+/** The records of one resource type, addressed by the name the config keys them under. */
+export type BindingNames = {
+    readonly [name: string]: BindingProperties;
+};
+/** Every readable record, addressed by resource type and then by name. */
+export type BindingPlaceholders = {
+    readonly [type: string]: BindingNames;
+};
+/**
+ * The placeholders `B` describes: one property of one record per leaf, each
+ * carrying the type that record publishes it as. `G` is what marks `B` as
+ * written down; while nothing has augmented it — nothing has run
+ * `ocel bindings generate` — every name stays open and the deploy is the check.
+ */
+export type BindingPlaceholdersOf<B, G> = keyof G extends never ? BindingPlaceholders : {
+    readonly [T in keyof B]: {
+        readonly [N in keyof B[T]]: {
+            readonly [P in keyof B[T][N]]: BindingOutput<B[T][N][P]>;
+        };
+    };
+};
+/** Whether a value names a property of a bound record. */
+export declare function isBindingOutput(value: unknown): value is BindingOutput;
+/**
+ * The records a transform module reads, one placeholder per property named.
+ * Nothing is resolved here: `bindings.postgres.orders.host` is the instruction
+ * the deploy carries out against the records published to the environment it
+ * targets, and `bindings.custom.network.subnetIds` reads a record nothing
+ * declared.
+ */
+export declare const bindings: BindingPlaceholders;
+export {};

package/dist/output.js

@@ -0,0 +1,49 @@
+/** The key a binding output rides under from a transform module to the deploy. */
+export const outputPlaceholderKey = "$ocelOutput";
+/** Whether a value names a property of a bound record. */
+export function isBindingOutput(value) {
+    return typeof value === "object" && value !== null && Object.hasOwn(value, outputPlaceholderKey);
+}
+/**
+ * The records a transform module reads, one placeholder per property named.
+ * Nothing is resolved here: `bindings.postgres.orders.host` is the instruction
+ * the deploy carries out against the records published to the environment it
+ * targets, and `bindings.custom.network.subnetIds` reads a record nothing
+ * declared.
+ */
+export const bindings = new Proxy({}, {
+    get(_target, type) {
+        return unnameable(type) ? undefined : namesOf(type);
+    },
+});
+function namesOf(type) {
+    return new Proxy({}, {
+        get(_target, name) {
+            return unnameable(name) ? undefined : propertiesOf(type, name);
+        },
+    });
+}
+function propertiesOf(type, name) {
+    return new Proxy({}, {
+        get(_target, property) {
+            return unnameable(property) ? undefined : placeholder(type, name, property);
+        },
+    });
+}
+function unnameable(key) {
+    return typeof key === "symbol" || key === "then";
+}
+function placeholder(type, name, property) {
+    if (type === "") {
+        throw new Error("a binding output names no resource type — read it as `bindings.<type>.<name>.<property>`");
+    }
+    if (name === "") {
+        throw new Error(`a binding output of ${type} names no binding — name the resource your config binds, or the record your own infrastructure published under \`custom\``);
+    }
+    if (property === "") {
+        throw new Error(`a binding output of ${type}.${name} names no property — name the property that record carries`);
+    }
+    return Object.freeze({
+        [outputPlaceholderKey]: Object.freeze({ type, name, property }),
+    });
+}

package/dist/patch.d.ts

@@ -0,0 +1,8 @@
+import type { Linked } from "./output";
+/**
+ * A deep-partial of one underlying resource's args, with every leaf open to a
+ * binding output as well as a written-down value.
+ */
+export type Patch<T> = T extends undefined | null ? never : T extends readonly (infer E)[] ? Linked<Patch<E>[]> : T extends object ? {
+    readonly [K in keyof T]?: Patch<T[K]>;
+} : Linked<T>;

package/dist/patch.js

@@ -0,0 +1 @@
+export {};

package/dist/run.d.ts

@@ -0,0 +1,16 @@
+import { type TransformModule } from "./evaluate";
+/**
+ * Pairs a module's authored specifier with its default export, so a deploy
+ * that rejects a rule can name the file the author wrote it in.
+ */
+export declare function loadModule(specifier: string, exported: unknown): TransformModule;
+/** The descriptor the deploy opens for the answer, leaving stdout to the modules. */
+export declare const resultDescriptor = 3;
+/**
+ * Runs the deploy-time pass: reads the candidate resources ocel offers on
+ * stdin, applies the modules in order, and writes the answer down the
+ * descriptor the deploy opened for it. A rejected rule rides down the same
+ * descriptor as a refusal, so a module that crashes or fails to import is not
+ * read as one, and anything a module prints stays on stdout where it belongs.
+ */
+export declare function runEvaluate(modules: readonly TransformModule[]): Promise<void>;

package/dist/run.js

@@ -0,0 +1,40 @@
+import { writeSync } from "node:fs";
+import { isTransformDefinition } from "./define";
+import { evaluate } from "./evaluate";
+/**
+ * Pairs a module's authored specifier with its default export, so a deploy
+ * that rejects a rule can name the file the author wrote it in.
+ */
+export function loadModule(specifier, exported) {
+    if (!isTransformDefinition(exported)) {
+        throw new Error(`${specifier}: a transform module must export a default \`defineTransform(...)\` result`);
+    }
+    return { specifier, definition: exported };
+}
+async function readRequest() {
+    const chunks = [];
+    for await (const chunk of process.stdin) {
+        chunks.push(chunk);
+    }
+    return JSON.parse(Buffer.concat(chunks).toString("utf8"));
+}
+/** The descriptor the deploy opens for the answer, leaving stdout to the modules. */
+export const resultDescriptor = 3;
+/**
+ * Runs the deploy-time pass: reads the candidate resources ocel offers on
+ * stdin, applies the modules in order, and writes the answer down the
+ * descriptor the deploy opened for it. A rejected rule rides down the same
+ * descriptor as a refusal, so a module that crashes or fails to import is not
+ * read as one, and anything a module prints stays on stdout where it belongs.
+ */
+export async function runEvaluate(modules) {
+    try {
+        const result = evaluate(await readRequest(), modules);
+        writeSync(resultDescriptor, JSON.stringify({ result }));
+    }
+    catch (error) {
+        const refusal = error instanceof Error ? error.message : String(error);
+        writeSync(resultDescriptor, JSON.stringify({ refusal }));
+        process.exitCode = 1;
+    }
+}

package/dist/vps/index.d.ts

@@ -0,0 +1,87 @@
+/**
+ * The container a box runs for an ocel resource, as `docker run` takes it.
+ */
+export interface VpsContainerArgs {
+    /** The name the container runs under, which is also the host an app dials. */
+    name: string;
+    /** The project network the container joins, and the only thing that reaches it. */
+    network: string;
+    /** The labels a teardown and a class destroy find the container by. */
+    labels: Record<string, string>;
+    /** Ports published on the box. A resource publishes none. */
+    publish: string[];
+    /** What is mounted into the container: its own volume, and nothing else. */
+    mounts: string[];
+    /**
+     * The image to run, pinned by digest (`…@sha256:…`). Swap it for a build of
+     * the same engine that carries what you need, such as pgvector.
+     */
+    image: string;
+    /** Arguments handed to the image's entrypoint, such as `["-c", "max_connections=200"]`. */
+    args: string[];
+    /** Environment for the container. The names the engine's credentials ride under stay ocel's. */
+    env: Record<string, string>;
+    /** A memory ceiling, as `docker run --memory` takes it: `"2g"`. */
+    memory: string;
+    /** A CPU ceiling, as `docker run --cpus` takes it: `"1.5"`. */
+    cpus: string;
+    /** The size of `/dev/shm`, as `docker run --shm-size` takes it: `"256m"`. */
+    shmSize: string;
+}
+/**
+ * The volume a box keeps an ocel resource's data on, as `docker volume create` takes it.
+ */
+export interface VpsVolumeArgs {
+    /** The volume's name, which a teardown removes it by. */
+    name: string;
+    /** The labels a class destroy finds the volume by. */
+    labels: Record<string, string>;
+    /** The volume driver. Defaults to the engine's own `local`. */
+    driver: string;
+    /** Options for the driver, such as a bind onto a disk mounted at `/mnt/pg`. */
+    driverOpts: Record<string, string>;
+}
+/**
+ * One key per thing the vps provider stands up on the box for an ocel resource.
+ */
+export interface VpsResourceArgs {
+    postgres: {
+        container: VpsContainerArgs;
+        volume: VpsVolumeArgs;
+    };
+    bucket: {
+        container: VpsContainerArgs;
+        volume: VpsVolumeArgs;
+    };
+}
+/** The ocel resource types the vps provider renders patchable resources for. */
+export type VpsResourceType = keyof VpsResourceArgs;
+/**
+ * The fields ocel fills itself — the name an app dials, the network that is
+ * the resource's whole boundary, the labels it is found and removed by, and
+ * what is published and mounted. A patch naming one is refused where it is
+ * written, and the deploy refuses it again by name.
+ */
+export declare const vpsOwnedFields: {
+    readonly postgres: {
+        readonly container: readonly ["name", "network", "labels", "publish", "mounts"];
+        readonly volume: readonly ["name", "labels"];
+    };
+    readonly bucket: {
+        readonly container: readonly ["name", "network", "labels", "publish", "mounts"];
+        readonly volume: readonly ["name", "labels"];
+    };
+};
+type VpsOwned = typeof vpsOwnedFields;
+type OwnedNames<L> = L extends readonly (infer F)[] ? Extract<F, string> : never;
+/**
+ * What a rule may patch under `vps`: the box's own args with the fields ocel
+ * owns removed. Every leaf is a written-down value; a binding output has
+ * nothing on a box to resolve against.
+ */
+export type VpsSurfaces = {
+    [T in VpsResourceType]: {
+        [K in keyof VpsResourceArgs[T]]: Partial<Omit<VpsResourceArgs[T][K], OwnedNames<VpsOwned[T][K & keyof VpsOwned[T]]>>>;
+    };
+};
+export {};

package/dist/vps/index.js

@@ -0,0 +1,16 @@
+/**
+ * The fields ocel fills itself — the name an app dials, the network that is
+ * the resource's whole boundary, the labels it is found and removed by, and
+ * what is published and mounted. A patch naming one is refused where it is
+ * written, and the deploy refuses it again by name.
+ */
+export const vpsOwnedFields = {
+    postgres: {
+        container: ["name", "network", "labels", "publish", "mounts"],
+        volume: ["name", "labels"],
+    },
+    bucket: {
+        container: ["name", "network", "labels", "publish", "mounts"],
+        volume: ["name", "labels"],
+    },
+};

package/package.json

@@ -0,0 +1,55 @@
+{
+  "name": "@ocel/transforms",
+  "version": "0.0.0",
+  "private": false,
+  "type": "module",
+  "description": "Patches the underlying cloud resources ocel provisions, typed from the provider's own SDK",
+  "files": [
+    "dist/",
+    "README.md"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./aws": {
+      "types": "./dist/aws/index.d.ts",
+      "import": "./dist/aws/index.js"
+    },
+    "./vps": {
+      "types": "./dist/vps/index.d.ts",
+      "import": "./dist/vps/index.js"
+    },
+    "./run": {
+      "types": "./dist/run.d.ts",
+      "import": "./dist/run.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "dependencies": {
+    "@pulumi/aws": "7.36.0",
+    "@pulumi/pulumi": "^3.259.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20",
+    "typescript": "^5.9.3",
+    "vite": "^8.1.3",
+    "vitest": "^4.1.9"
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ocelhq/ocel.git",
+    "directory": "packages/ocel-transforms"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "scripts": {
+    "build": "tsc",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit -p tsconfig.typecheck.json && tsc --noEmit -p tsconfig.typetests.json && tsc --noEmit -p tsconfig.typetests-empty.json && tsc --noEmit -p tsconfig.typetests-open.json"
+  }
+}