@intentius/chant-lexicon-fly 0.124.31 → 0.124.32

package/dist/release-store.js

@@ -0,0 +1,46 @@
+/**
+ * Where a Fly release's Machine config is kept, so a rollback can put it back
+ * (#2736, ws-056).
+ *
+ * The Machine's metadata says which release it serves and which one it
+ * replaced; the config that earlier release applied is kept on the
+ * `chant/lifecycle` branch beside the release ledger, one file per release at
+ * `<env>/fly/<app>/<machine>/<digest>.json`. It is written through core's
+ * ledger plumbing, so a workspace member's copy lands under its own prefix,
+ * and every checkout that fetches the branch can roll back.
+ *
+ * Not exported from the package entry point: it spawns git, which stays off
+ * the build path. The `fly-release` and `fly-rollback` capabilities import it.
+ */
+import { readBlobFromPath, writeBlobToPath } from "@intentius/chant/lifecycle/git";
+const safe = (s) => s.replace(/[^a-zA-Z0-9_.-]/g, "_");
+/** The file a release's Machine config is kept in, under the environment's ledger directory. */
+export function machineConfigFile(ref) {
+    return `fly/${safe(ref.app)}/${safe(ref.machine)}/${safe(ref.digest.replace(/^sha256:/, ""))}.json`;
+}
+/** The lifecycle-branch store for `environment`. */
+export function lifecycleMachineConfigStore(environment, opts) {
+    return {
+        async read(ref) {
+            const content = await readBlobFromPath(environment, machineConfigFile(ref), opts);
+            return content === null ? undefined : JSON.parse(content);
+        },
+        async write(ref, config) {
+            await writeBlobToPath(environment, machineConfigFile(ref), `${JSON.stringify(config, null, 2)}\n`, `Fly release config ${ref.app}/${ref.machine} ${ref.digest}`, opts);
+        },
+    };
+}
+/** An in-memory store, for tests and for a caller with nowhere to keep configs. */
+export function memoryMachineConfigStore() {
+    const entries = new Map();
+    return {
+        entries,
+        async read(ref) {
+            const found = entries.get(machineConfigFile(ref));
+            return found ? structuredClone(found) : undefined;
+        },
+        async write(ref, config) {
+            entries.set(machineConfigFile(ref), structuredClone(config));
+        },
+    };
+}

package/dist/serializer.js

@@ -0,0 +1,299 @@
+/**
+ * fly (Machines API / "flaps") serializer.
+ *
+ * Turns declared `App`, `Machine`, `Volume`, `IPAddress`, `Certificate`, and
+ * `Secret` resources into the JSON create bodies the flaps REST API accepts, so
+ * #739's applier can POST them straight through and mudflaps (#740) can
+ * round-trip them.
+ *
+ * Output shape — a JSON object keyed by entity name. Each value is a single
+ * flaps request:
+ *
+ *   {
+ *     "<entityName>": {
+ *       "endpoint": "/v1/apps",                       // or /v1/apps/{app}/machines
+ *       "method": "POST",
+ *       "body": { ... }                               // the create body
+ *     }
+ *   }
+ *
+ * Field names are taken from mudflaps' Go structs (the wire oracle), which win
+ * over the OpenAPI-generated TypeScript names:
+ *   - App    → CreateAppRequest    `{ app_name, org_slug? }` (NOT `name`).
+ *   - Machine→ CreateMachineRequest `{ name?, region?, config?, skip_launch? }`;
+ *     `config` is the full MachineConfig. The owning app is a URL path segment,
+ *     not a body field, so it lands in `endpoint`.
+ *
+ * D2: every serialized Machine carries the `managed-by: chant` ownership marker
+ * (plus the stack/env identity from `context.ownership`) merged into
+ * `config.metadata`, even when the user supplied no metadata.
+ */
+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 { mergeResourceAttributes, telemetryEnvironment } from "@intentius/chant/telemetry-attribution";
+import { FLY_METADATA_OWNERSHIP_KEYS } from "./ownership.js";
+const APP_ENTITY_TYPE = "Fly::Machines::App";
+const MACHINE_ENTITY_TYPE = "Fly::Machines::Machine";
+const VOLUME_ENTITY_TYPE = "Fly::Machines::Volume";
+const IP_ENTITY_TYPE = "Fly::Machines::IPAddress";
+const CERTIFICATE_ENTITY_TYPE = "Fly::Machines::Certificate";
+const SECRET_ENTITY_TYPE = "Fly::Machines::Secret";
+/**
+ * Visitor for the generic serializer walker. Property declarables (MachineConfig,
+ * MachineGuest, MachineService, ...) are unwrapped to plain objects; resource
+ * references resolve to their logical name.
+ */
+function flyVisitor() {
+    return {
+        attrRef: (name) => name,
+        resourceRef: (name) => 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 Object.keys(result).length > 0 ? result : undefined;
+        },
+    };
+}
+function readProps(entity) {
+    const props = isResourceDeclarable(entity) ? entity.props : undefined;
+    return props && typeof props === "object" ? props : {};
+}
+/**
+ * Pseudo-parameter → environment variable mapping. flaps create bodies are
+ * plain JSON, so `Fly.Region` / `Fly.OrgSlug` / `Fly.AppName` (which the walker
+ * lowers to a `{ Ref: "Fly::..." }` marker) are resolved from the environment
+ * at build time, mirroring gcp's PSEUDO_ENV_MAP. The first set env var wins;
+ * absent all of them, the fallback keeps output valid offline (mudflaps).
+ */
+const PSEUDO_ENV_MAP = {
+    "Fly::Region": { envVars: ["FLY_REGION"], fallback: "iad" },
+    "Fly::OrgSlug": { envVars: ["FLY_ORG", "FLY_ORG_SLUG"], fallback: "personal" },
+    "Fly::AppName": { envVars: ["FLY_APP_NAME"], fallback: "app" },
+};
+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 (any intrinsic carrying the
+ * marker, unwrapped via `toJSON()`) and the already-walked `{ Ref: "Fly::X" }`
+ * shape. Non-Fly `{ Ref }` shapes and every other value pass through untouched.
+ */
+function resolvePseudoParameters(value) {
+    if (Array.isArray(value)) {
+        return value.map(resolvePseudoParameters);
+    }
+    if (value && typeof value === "object") {
+        const record = value;
+        // Unwrap an intrinsic (e.g. a PseudoParameter assigned without walking) to
+        // the { Ref } envelope it serializes to, then resolve that.
+        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 app_name flaps expects: an explicit `name` prop, else the entity name. */
+function appName(entity, entityName) {
+    const name = readProps(entity).name;
+    return typeof name === "string" ? name : entityName;
+}
+// ── Telemetry attribution (#3060, D22) ────────────────────────────
+/** The digest of an image reference pinned with `@sha256:...`, or undefined. */
+function imageDigest(image) {
+    if (typeof image !== "string")
+        return undefined;
+    const at = image.lastIndexOf("@");
+    return at === -1 ? undefined : image.slice(at + 1);
+}
+/**
+ * Stamp one Machine's attributes as `OTEL_SERVICE_NAME` and
+ * `OTEL_RESOURCE_ATTRIBUTES` in its `config.env`, the env the Machine's
+ * process gets. `service` is the owning app's name on Fly, `decl` the
+ * Machine's declaration id. A value the Machine already sets is kept: its own
+ * `OTEL_SERVICE_NAME` wins, and its own resource attributes keep their keys
+ * while the missing ones are appended.
+ *
+ * Machine env values are literal strings, so there is no reference to the
+ * release attributes here: `fly-release` writes them into the value it
+ * deploys (#3061, ws-081).
+ */
+function stampTelemetry(config, service, decl, telemetry) {
+    const version = imageDigest(config.image);
+    const vars = telemetryEnvironment(telemetry, { service, decl, ...(version ? { version } : {}) });
+    const env = config.env && typeof config.env === "object" && !Array.isArray(config.env) ? { ...config.env } : {};
+    if (!("OTEL_SERVICE_NAME" in env))
+        env.OTEL_SERVICE_NAME = vars.OTEL_SERVICE_NAME;
+    const own = env.OTEL_RESOURCE_ATTRIBUTES;
+    if (own === undefined)
+        env.OTEL_RESOURCE_ATTRIBUTES = vars.OTEL_RESOURCE_ATTRIBUTES;
+    else if (typeof own === "string")
+        env.OTEL_RESOURCE_ATTRIBUTES = mergeResourceAttributes(own, vars.OTEL_RESOURCE_ATTRIBUTES);
+    config.env = env;
+}
+/**
+ * fly flaps serializer.
+ */
+export const flySerializer = {
+    name: "fly",
+    rulePrefix: "FLY",
+    serialize(entities, _outputs, context) {
+        const entityNames = new Map();
+        for (const [name, entity] of entities)
+            entityNames.set(entity, name);
+        const visitor = flyVisitor();
+        // D2 ownership marker. `managed-by: chant` is always stamped; stack/env are
+        // added when the build threads an ownership marker through the context.
+        const ownershipMeta = context?.ownership
+            ? ownershipEntries(FLY_METADATA_OWNERSHIP_KEYS, context.ownership)
+            : { [FLY_METADATA_OWNERSHIP_KEYS.managedBy]: OWNERSHIP_MANAGED_BY_VALUE };
+        // Resolve which app a machine belongs to (a URL path segment, not a body
+        // field). A machine may name its app explicitly via an `app` prop (a string
+        // or an `App` reference); otherwise, when the stack declares exactly one
+        // app, machines default to it. Failing both, a `{app}` placeholder is left
+        // for the applier to fill.
+        const apps = [];
+        for (const [name, entity] of entities) {
+            if (entity.entityType === APP_ENTITY_TYPE) {
+                apps.push([name, entity]);
+            }
+        }
+        const soleApp = apps.length === 1 ? appName(apps[0][1], apps[0][0]) : undefined;
+        // The owning app of any app-scoped resource (machine, volume, ip, cert,
+        // secret): an explicit `app` prop (string or `App` reference), else the
+        // stack's sole app, else a `{app}` placeholder for the applier to fill.
+        const resolveOwningApp = (entity) => {
+            const app = readProps(entity).app;
+            if (typeof app === "string")
+                return app;
+            if (app && typeof app === "object" && "entityType" in app) {
+                const decl = app;
+                return appName(decl, entityNames.get(decl) ?? "{app}");
+            }
+            return soleApp ?? "{app}";
+        };
+        const requests = {};
+        for (const [name, entity] of entities) {
+            if (isPropertyDeclarable(entity))
+                continue;
+            const entityType = entity.entityType;
+            const props = readProps(entity);
+            if (entityType === APP_ENTITY_TYPE) {
+                const body = { app_name: appName(entity, name) };
+                if (props.org_slug !== undefined)
+                    body.org_slug = props.org_slug;
+                if (props.network !== undefined)
+                    body.network = props.network;
+                if (props.enable_subdomains !== undefined)
+                    body.enable_subdomains = props.enable_subdomains;
+                requests[name] = { endpoint: "/v1/apps", method: "POST", body };
+                continue;
+            }
+            if (entityType === MACHINE_ENTITY_TYPE) {
+                const walkedConfig = props.config
+                    ? walkValue(props.config, entityNames, visitor)
+                    : undefined;
+                const config = walkedConfig && typeof walkedConfig === "object"
+                    ? { ...walkedConfig }
+                    : {};
+                // Merge the ownership marker into config.metadata. The marker wins over
+                // any colliding user key so ownership can never be silently unset.
+                const userMeta = config.metadata && typeof config.metadata === "object"
+                    ? config.metadata
+                    : {};
+                config.metadata = { ...userMeta, ...ownershipMeta };
+                // Spread the create-body fields (name, region, skip_launch, ...) and
+                // override with the walked config. `app` is our association hint, not a
+                // flaps field, so it is dropped.
+                const body = {};
+                for (const [key, value] of Object.entries(props)) {
+                    if (key === "config" || key === "app" || value === undefined)
+                        continue;
+                    body[key] = walkValue(value, entityNames, visitor);
+                }
+                body.config = config;
+                // Telemetry attribution (#3060): service.name is the app's name on
+                // Fly, or the Machine's export name when no app is resolved.
+                const owningApp = resolveOwningApp(entity);
+                if (context?.telemetry) {
+                    stampTelemetry(config, owningApp === "{app}" ? name : owningApp, name, context.telemetry);
+                }
+                requests[name] = {
+                    endpoint: `/v1/apps/${owningApp}/machines`,
+                    method: "POST",
+                    body,
+                };
+                continue;
+            }
+            // ── App-scoped, metadata-less resources (#741, D2). ──────────────────
+            // Each spreads its scalar create-body props straight through; the `app`
+            // association hint is a URL segment, not a body field, so it is dropped.
+            // Ownership is at the app boundary, so none carry a metadata marker.
+            if (entityType === VOLUME_ENTITY_TYPE ||
+                entityType === IP_ENTITY_TYPE ||
+                entityType === CERTIFICATE_ENTITY_TYPE ||
+                entityType === SECRET_ENTITY_TYPE) {
+                const app = resolveOwningApp(entity);
+                if (entityType === SECRET_ENTITY_TYPE) {
+                    // Apply-only (D7): name is the URL segment; `value` is the only body
+                    // field. mudflaps returns just a digest, so this never enters a diff.
+                    // A Secret with no value is set out of band. It is marked
+                    // `mustExist`, and the applier checks for it instead of posting.
+                    const secretName = typeof props.name === "string" ? props.name : name;
+                    const endpoint = `/v1/apps/${app}/secrets/${encodeURIComponent(secretName)}`;
+                    requests[name] =
+                        props.value !== undefined
+                            ? { endpoint, method: "POST", body: { value: props.value }, applyOnly: true }
+                            : { endpoint, method: "POST", body: {}, applyOnly: true, mustExist: true };
+                    continue;
+                }
+                // A Certificate is an ACME certificate. flaps creates those at
+                // `.../certificates/acme` and answers a bare POST to `.../certificates`
+                // with 404 (#3114).
+                const segment = entityType === VOLUME_ENTITY_TYPE
+                    ? "volumes"
+                    : entityType === IP_ENTITY_TYPE
+                        ? "ip_assignments"
+                        : "certificates/acme";
+                const body = {};
+                for (const [key, value] of Object.entries(props)) {
+                    if (key === "app" || value === undefined)
+                        continue;
+                    body[key] = walkValue(value, entityNames, visitor);
+                }
+                requests[name] = { endpoint: `/v1/apps/${app}/${segment}`, method: "POST", body };
+                continue;
+            }
+        }
+        // Resolve pseudo-parameter markers (Fly.Region, Fly.OrgSlug, ...) to their
+        // environment value so create bodies carry plain strings, not `{ Ref }`.
+        return JSON.stringify(resolvePseudoParameters(requests), null, 2);
+    },
+};

package/dist/spec/fetch.js

@@ -0,0 +1,32 @@
+import { join } from "path";
+import { homedir } from "os";
+import { fetchWithCache } from "@intentius/chant/codegen/fetch";
+/**
+ * Fly's published Machines API (flaps) OpenAPI 3.0.1 spec.
+ *
+ * This is an unversioned live endpoint: it always serves the current spec with
+ * no version or release tag to pin. There is nothing for the self-upgrade
+ * tooling (#685) to bump, so the plugin declares no `upstreamPin` — unlike gcp
+ * (`KCC_VERSION`) or k8s (`K8S_SCHEMA_VERSION`), which pin a released schema
+ * version. Re-running `generate` simply picks up whatever this URL currently
+ * serves.
+ */
+const SCHEMA_URL = "https://docs.machines.dev/openapi.json";
+/**
+ * Cache under `~/.chant` (like the k8s lexicon) so CI's `~/.chant` schema
+ * cache covers it — a `docs.machines.dev` hiccup then falls back to the cache
+ * instead of failing the generate step.
+ */
+const CACHE_FILE = join(homedir(), ".chant", "fly-machines-openapi.json");
+/**
+ * Fetch the flaps OpenAPI spec and return it as a Map<typeName, Buffer>
+ * compatible with the generatePipeline fetchSchemas callback.
+ *
+ * The flaps spec is a single document, so we return a single entry keyed by
+ * "Fly::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([["Fly::OpenAPI", raw]]);
+}

package/dist/spec/parse.js

@@ -0,0 +1,260 @@
+/**
+ * Fly Machines API OpenAPI 3.0.1 parser.
+ *
+ * The flaps spec has no resource marker and is mostly request/response DTOs,
+ * so we generate a curated set of resources rather than every schema. Each
+ * curated resource pairs a request schema (writable authoring surface) with a
+ * response schema (read-only attributes). The property types reachable from the
+ * request schemas — notably the fly.MachineConfig graph — are emitted as
+ * standalone property-type classes so `config` is fully typed.
+ */
+import { extractConstraints as coreExtractConstraints, primaryType, isEnumDefinition, } from "@intentius/chant/codegen/json-schema";
+// ── Curated manifest ───────────────────────────────────────────────
+/** The single service segment for all fly type names. */
+const SERVICE = "Machines";
+const RESOURCES = [
+    { typeName: `Fly::${SERVICE}::App`, request: "CreateAppRequest", response: "App" },
+    { typeName: `Fly::${SERVICE}::Machine`, request: "CreateMachineRequest", response: "Machine" },
+    { typeName: `Fly::${SERVICE}::Volume`, request: "CreateVolumeRequest", response: "Volume" },
+    { typeName: `Fly::${SERVICE}::IPAddress`, request: "assignIPRequest", response: "IPAssignment" },
+    { typeName: `Fly::${SERVICE}::Certificate`, request: "createAcmeCertificateRequest", response: "CertificateDetail" },
+    {
+        typeName: `Fly::${SERVICE}::Secret`,
+        request: "SetAppSecretRequest",
+        response: "AppSecret",
+        pathProps: [
+            {
+                name: "name",
+                tsType: "string",
+                required: false,
+                description: "The secret's name on the app. Defaults to the declaration's export name. " +
+                    "A Secret with no value is never sent: apply checks that the app already has it.",
+                constraints: {},
+            },
+        ],
+    },
+];
+const REF_PREFIX = "#/components/schemas/";
+// ── Parser ─────────────────────────────────────────────────────────
+/**
+ * Parse the flaps OpenAPI spec into the curated resources and the property
+ * types reachable from their request schemas.
+ */
+export function parseFlyOpenAPI(data) {
+    const spec = JSON.parse(typeof data === "string" ? data : data.toString("utf-8"));
+    const schemas = spec.components?.schemas ?? {};
+    // Phase 1: discover the emitted property-type set — object schemas reachable
+    // (transitively) from the request schemas' properties. Enums are inlined, so
+    // they are never emitted as classes.
+    const emitted = collectPropertyTypes(schemas);
+    const className = (schemaName) => schemaToClassName(schemaName);
+    const resolve = (prop) => resolveType(prop, schemas, emitted);
+    const results = [];
+    // Phase 2: resources.
+    for (const rspec of RESOURCES) {
+        const req = schemas[rspec.request];
+        const res = schemas[rspec.response];
+        const reqProps = req?.properties ?? {};
+        const requiredSet = new Set(req?.required ?? []);
+        const properties = [];
+        for (const [name, prop] of Object.entries(reqProps)) {
+            properties.push({
+                name,
+                tsType: resolve(prop),
+                required: requiredSet.has(name),
+                description: prop.description,
+                constraints: coreExtractConstraints(prop),
+            });
+        }
+        for (const extra of rspec.pathProps ?? []) {
+            if (!(extra.name in reqProps))
+                properties.push(extra);
+        }
+        // Attributes = response props not present in the request schema.
+        const attributes = [];
+        for (const [name, prop] of Object.entries(res?.properties ?? {})) {
+            if (properties.some((p) => p.name === name))
+                continue;
+            attributes.push({ name, tsType: resolve(prop) });
+        }
+        results.push({
+            resource: { typeName: rspec.typeName, description: req?.description, properties, attributes },
+            propertyTypes: [],
+            enums: [],
+        });
+    }
+    // Phase 3: property-type classes.
+    for (const schemaName of emitted) {
+        const def = schemas[schemaName];
+        const requiredSet = new Set(def.required ?? []);
+        const properties = [];
+        for (const [name, prop] of Object.entries(def.properties ?? {})) {
+            properties.push({
+                name,
+                tsType: resolve(prop),
+                required: requiredSet.has(name),
+                description: prop.description,
+                constraints: coreExtractConstraints(prop),
+            });
+        }
+        results.push({
+            resource: {
+                typeName: `Fly::${SERVICE}::${className(schemaName)}`,
+                description: def.description,
+                properties,
+                attributes: [],
+            },
+            propertyTypes: [],
+            enums: [],
+            isProperty: true,
+        });
+    }
+    return results;
+}
+/**
+ * Walk the request schemas and collect the set of object schemas reachable
+ * through their properties (following $ref, allOf, arrays, and maps). Returns
+ * the schema names in insertion order, deduplicated across resources.
+ */
+function collectPropertyTypes(schemas) {
+    const emitted = new Set();
+    const queue = [];
+    const seedFrom = (node) => {
+        for (const ref of collectRefs(node)) {
+            const target = schemas[ref];
+            if (!target)
+                continue;
+            if (isObjectSchema(target) && !emitted.has(ref)) {
+                emitted.add(ref);
+                queue.push(ref);
+            }
+        }
+    };
+    for (const spec of RESOURCES) {
+        seedFrom(schemas[spec.request]?.properties);
+    }
+    while (queue.length > 0) {
+        const name = queue.shift();
+        seedFrom(schemas[name]?.properties);
+    }
+    return [...emitted];
+}
+/** Collect every `#/components/schemas/X` ref name nested anywhere in a node. */
+function collectRefs(node, acc = new Set()) {
+    if (!node || typeof node !== "object")
+        return acc;
+    if (Array.isArray(node)) {
+        for (const item of node)
+            collectRefs(item, acc);
+        return acc;
+    }
+    const obj = node;
+    const ref = obj.$ref;
+    if (typeof ref === "string" && ref.startsWith(REF_PREFIX))
+        acc.add(ref.slice(REF_PREFIX.length));
+    for (const [key, value] of Object.entries(obj)) {
+        if (key === "$ref")
+            continue;
+        collectRefs(value, acc);
+    }
+    return acc;
+}
+/** An object schema with properties (not a pure enum). */
+function isObjectSchema(def) {
+    return !!def.properties && Object.keys(def.properties).length > 0 && !isEnumDefinition(def);
+}
+// ── Type resolution ────────────────────────────────────────────────
+/**
+ * Resolve an OpenAPI schema node to its TypeScript type string. Emitted object
+ * schemas resolve to their class name; enums inline as string-literal unions;
+ * everything else falls back to primitives or `Record<string, any>`.
+ */
+function resolveType(prop, schemas, emitted) {
+    if (!prop)
+        return "any";
+    if (prop.$ref)
+        return resolveRefType(prop.$ref, schemas, emitted);
+    // allOf: [{ $ref }] — the OpenAPI idiom for "typed as this schema".
+    if (prop.allOf && prop.allOf.length > 0) {
+        const withRef = prop.allOf.find((s) => s.$ref);
+        if (withRef?.$ref)
+            return resolveRefType(withRef.$ref, schemas, emitted);
+    }
+    if (prop.enum && prop.enum.length > 0) {
+        return [...prop.enum].sort().map((v) => JSON.stringify(v)).join(" | ");
+    }
+    const pt = primaryType(prop.type);
+    switch (pt) {
+        case "string":
+            return "string";
+        case "integer":
+        case "number":
+            return "number";
+        case "boolean":
+            return "boolean";
+        case "array": {
+            if (prop.items) {
+                const itemType = resolveType(prop.items, schemas, emitted);
+                return itemType.includes(" | ") ? `(${itemType})[]` : `${itemType}[]`;
+            }
+            return "any[]";
+        }
+        case "object":
+            if (prop.additionalProperties && typeof prop.additionalProperties === "object") {
+                return `Record<string, ${resolveType(prop.additionalProperties, schemas, emitted)}>`;
+            }
+            return "Record<string, any>";
+        default:
+            return "any";
+    }
+}
+/** Resolve a `#/components/schemas/X` ref to a TypeScript type. */
+function resolveRefType(ref, schemas, emitted) {
+    if (!ref.startsWith(REF_PREFIX))
+        return "any";
+    const name = ref.slice(REF_PREFIX.length);
+    const def = schemas[name];
+    if (!def)
+        return "any";
+    // Emitted object schemas reference their class by name.
+    if (emitted.includes(name))
+        return schemaToClassName(name);
+    // Enums inline as string-literal unions.
+    if (isEnumDefinition(def)) {
+        return [...(def.enum ?? [])].sort().map((v) => JSON.stringify(v)).join(" | ");
+    }
+    // Object schemas we did not emit (response-only shapes) loosen to a map.
+    if (def.properties)
+        return "Record<string, any>";
+    const pt = primaryType(def.type);
+    switch (pt) {
+        case "string":
+            return "string";
+        case "integer":
+        case "number":
+            return "number";
+        case "boolean":
+            return "boolean";
+        default:
+            return "any";
+    }
+}
+// ── Naming helpers ─────────────────────────────────────────────────
+/**
+ * Convert a schema name into a PascalCase class-name segment.
+ * "fly.MachineConfig" → "MachineConfig", "fly.dnsOption" → "DnsOption".
+ */
+export function schemaToClassName(schemaName) {
+    const base = schemaName.slice(schemaName.lastIndexOf(".") + 1);
+    return base.charAt(0).toUpperCase() + base.slice(1);
+}
+/** Extract short name: "Fly::Machines::Machine" → "Machine". */
+export function flyShortName(typeName) {
+    const parts = typeName.split("::");
+    return parts[parts.length - 1];
+}
+/** Extract service name: "Fly::Machines::Machine" → "Machines". */
+export function flyServiceName(typeName) {
+    const parts = typeName.split("::");
+    return parts.length >= 2 ? parts[1] : SERVICE;
+}