@intentius/chant-lexicon-fly 0.16.0

package/src/skills/chant-fly.md

@@ -0,0 +1,123 @@
+---
+skill: chant-fly
+description: Author, lint, and deploy Fly apps and machines from a chant project, applied straight to the Machines API
+user-invocable: true
+---
+
+# Deploy to Fly Operational Playbook
+
+## How chant and Fly relate
+
+chant is a synthesis compiler: it compiles TypeScript in `src/` into a plan of Fly Machines API ("flaps") create requests, then reconciles that plan against a Fly org. Unlike the AWS or GCP lexicons, there is no external CLI to hand off to. `flyApply` speaks the Machines API directly, so the same code that builds the plan also applies it. There is no `flyctl` shell-out and no state file to store, lock, or keep in sync.
+
+The source of truth is the TypeScript in `src/`. The serialized plan (a JSON object keyed by entity name, each value a `{ endpoint, method, body }` flaps request) is an intermediate artifact.
+
+Your job as an agent:
+
+- Use `chant build` for synthesis and lint (region, guest sizing, mounts, secret literals).
+- Use `flyApply` (via the deploy Op, `chant run`) to reconcile the plan against the Machines API: create and update machines, wait each to `started`, and optionally prune what chant owns.
+
+## The endpoint switch
+
+One environment variable decides where the same code applies:
+
+- `FLY_FLAPS_BASE_URL` unset, no token: point it at a local [mudflaps](https://github.com/intentius/mudflaps) emulator (offline, no Fly account, no bill). This is the loop CI runs.
+- `FLY_FLAPS_BASE_URL` set to a real Fly org endpoint, plus `FLY_API_TOKEN`: the same plan deploys for real.
+
+Resolution order for the endpoint is: an explicit `endpoint` arg, then `FLY_FLAPS_BASE_URL`, then the real-Fly default (`https://api.machines.dev`). The bearer token defaults to `FLY_API_TOKEN`; mudflaps ignores it.
+
+Start from the runnable [`examples/local-fly`](../../examples/local-fly) loop:
+
+```bash
+cd examples/local-fly
+chant run fly        # boots mudflaps, applies an App + Machine, waits for started, tears down
+```
+
+That Op runs the phases boot, build, apply, verify, and teardown against a local mudflaps container (Docker required). To target a real org, drop the local endpoint override and set `FLY_API_TOKEN`.
+
+## Author an App and a Machine
+
+Import resource types from `@intentius/chant-lexicon-fly`. They are generated from Fly's Machines API OpenAPI spec, so `MachineConfig` is typed all the way down through guest, services, mounts, and checks.
+
+```ts
+import { App, Machine, MachineConfig, MachineGuest } from "@intentius/chant-lexicon-fly";
+
+export const app = new App({ name: "my-app" });
+
+export const web = new Machine({
+  name: "web",
+  region: "iad",
+  config: new MachineConfig({
+    image: "flyio/hellofly:latest",
+    guest: new MachineGuest({ cpu_kind: "shared", cpus: 1, memory_mb: 256 }),
+  }),
+});
+```
+
+A machine that names no app is bound to the stack's sole app at apply time. You do not stamp the ownership marker yourself: the serializer writes `managed-by: chant` into each machine's `config.metadata`, and the owned-only prune reads it back.
+
+The full resource set is `App`, `Machine`, `Volume`, `IPAddress`, `Certificate`, and `Secret`. Volumes, mounts, IPs, certificates, and apply-only secrets are covered in `chant-fly-patterns`.
+
+## Build and lint
+
+```bash
+chant build src/
+```
+
+Build synthesizes the flaps plan and runs the lint rules before anything reaches the API:
+
+| Rule | Catches |
+|------|---------|
+| FLY001 | `region` is not a real Fly region |
+| FLY002 | Guest sizing (`cpu_kind` / `cpus` / `memory_mb`) is not a valid combination |
+| FLY004 | A secret value written inline in machine config |
+| FLY010 | A machine config with no `image` |
+| FLY011 | A machine mount that references a `Volume` not declared in the stack (checked across files) |
+
+Fix every reported violation before applying. Secret values belong in a `Secret` or a reference, never inline (FLY004).
+
+## Apply with flyApply
+
+`flyApply` reads the serialized plan and applies it to flaps in dependency order: app, then volumes, then machines, then IPs, certificates, and secrets. Per machine it does a GET-then-create or update, then waits.
+
+- Create or update: POST the machine, then poll `GET .../wait` until it reaches `started` at its new `instance_id`. flaps caps its own long-poll at 60 seconds and answers 408 on expiry, so the client re-polls until its deadline (default 300 seconds).
+- No-op on no drift: a re-apply of an unchanged machine (config structurally equal to live) does nothing.
+- Leases: mutating an existing machine goes through the Machines API lease protocol. `flyApply` acquires a lease, echoes the nonce in the `fly-machine-lease-nonce` header on the mutation, and re-acquires and retries once if the lease was lost. Concurrent operators stay out of each other's way.
+
+### Owned-only prune
+
+Prune is off by default and destructive; turn it on to remove declared-then-removed resources.
+
+- Machines prune owned-only: a machine is destroyed only if it carries the `managed-by: chant` marker and the plan no longer declares it. An unmarked (foreign) machine in the same app is never modified or deleted, so the applier is safe to point at an app that also holds resources you manage elsewhere.
+- Volumes, IPs, certificates, and secrets have no metadata channel, so their ownership boundary is the app itself. See `chant-fly-patterns` for that app-boundary model before enabling prune on an app that mixes chant and non-chant resources.
+
+## The deploy Op
+
+The lexicon ships `flyDeploy`, a composite Op that wraps the boot, build, apply, verify, and teardown phases so `chant run` drives the whole loop as modeled activities with no raw shell.
+
+```ts
+// examples/local-fly/ops/fly.op.ts
+import { flyDeploy } from "@intentius/chant-lexicon-fly";
+
+export default flyDeploy({ app: "local-fly-demo" });
+```
+
+`chant run fly` boots mudflaps, builds the plan, applies the App and Machine, waits for the machine to reach `started`, and tears the emulator down. To deploy the same Op to a real org, drop the local endpoint override and set `FLY_API_TOKEN`.
+
+## Teardown
+
+`flyDelete` is the inverse of `flyApply`: it destroys the machines the plan declares (dependents first), then deletes the apps. It is idempotent, so an already-absent resource is a no-op.
+
+## Quick reference
+
+| Command | Description |
+|---------|-------------|
+| `chant build src/` | Synthesize the flaps plan and run lint (FLY001/FLY002/FLY004/FLY010/FLY011) |
+| `chant run fly` | Run the deploy Op (boot, build, apply, verify, teardown) |
+| `FLY_FLAPS_BASE_URL=...` | Point the same code at mudflaps or a real Fly org |
+| `FLY_API_TOKEN=...` | Bearer token for a real Fly org (mudflaps ignores it) |
+
+## Where to go next
+
+- `chant-fly-patterns` covers volumes and mounts, IP assignments, certificates, apply-only secrets, and the app-boundary ownership model.
+- `chant-fly-ops` covers operating a live app: waiting on stuck machines, lease conflicts, prune safety, and targeting a real org versus the emulator.

package/src/spec/fetch.ts

@@ -0,0 +1,34 @@
+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?: { force?: boolean }): Promise<Map<string, Buffer>> {
+  const raw = await fetchWithCache({ url: SCHEMA_URL, cacheFile: CACHE_FILE }, options?.force);
+  return new Map([["Fly::OpenAPI", raw]]);
+}

package/src/spec/parse.ts

@@ -0,0 +1,323 @@
+/**
+ * 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,
+  type JsonSchemaProperty,
+  type PropertyConstraints,
+} from "@intentius/chant/codegen/json-schema";
+
+// ── Types ──────────────────────────────────────────────────────────
+
+export type { PropertyConstraints };
+
+export interface ParsedProperty {
+  name: string;
+  tsType: string;
+  required: boolean;
+  description?: string;
+  constraints: PropertyConstraints;
+}
+
+export interface ParsedResource {
+  typeName: string;
+  description?: string;
+  properties: ParsedProperty[];
+  attributes: Array<{ name: string; tsType: string }>;
+}
+
+export interface FlyParseResult {
+  resource: ParsedResource;
+  /** Always empty — fly emits property types as standalone results. */
+  propertyTypes: Array<{ name: string; defType: string }>;
+  /** Always empty — enums are inlined as string-literal unions. */
+  enums: Array<{ name: string; values: string[] }>;
+  /** Whether this entity is a property type (nested config shape). */
+  isProperty?: boolean;
+}
+
+// ── OpenAPI types ──────────────────────────────────────────────────
+
+interface OpenAPISchema extends JsonSchemaProperty {
+  allOf?: OpenAPISchema[];
+  additionalProperties?: boolean | OpenAPISchema;
+  items?: OpenAPISchema;
+  properties?: Record<string, OpenAPISchema>;
+}
+
+interface OpenAPISpec {
+  components?: { schemas?: Record<string, OpenAPISchema> };
+}
+
+// ── Curated manifest ───────────────────────────────────────────────
+
+/** The single service segment for all fly type names. */
+const SERVICE = "Machines";
+
+interface ResourceSpec {
+  typeName: string;
+  request: string;
+  response: string;
+}
+
+const RESOURCES: ResourceSpec[] = [
+  { 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" },
+];
+
+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: string | Buffer): FlyParseResult[] {
+  const spec: OpenAPISpec = 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: string): string => schemaToClassName(schemaName);
+  const resolve = (prop: OpenAPISchema | undefined): string => resolveType(prop, schemas, emitted);
+
+  const results: FlyParseResult[] = [];
+
+  // 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: ParsedProperty[] = [];
+    for (const [name, prop] of Object.entries(reqProps)) {
+      properties.push({
+        name,
+        tsType: resolve(prop),
+        required: requiredSet.has(name),
+        description: prop.description,
+        constraints: coreExtractConstraints(prop as JsonSchemaProperty),
+      });
+    }
+
+    // Attributes = response props not present in the request schema.
+    const attributes: Array<{ name: string; tsType: string }> = [];
+    for (const [name, prop] of Object.entries(res?.properties ?? {})) {
+      if (name in reqProps) 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: ParsedProperty[] = [];
+    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 as JsonSchemaProperty),
+      });
+    }
+    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: Record<string, OpenAPISchema>): string[] {
+  const emitted = new Set<string>();
+  const queue: string[] = [];
+
+  const seedFrom = (node: unknown) => {
+    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: unknown, acc: Set<string> = new Set()): Set<string> {
+  if (!node || typeof node !== "object") return acc;
+  if (Array.isArray(node)) {
+    for (const item of node) collectRefs(item, acc);
+    return acc;
+  }
+  const obj = node as Record<string, unknown>;
+  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: OpenAPISchema): boolean {
+  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: OpenAPISchema | undefined,
+  schemas: Record<string, OpenAPISchema>,
+  emitted: string[],
+): string {
+  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: string, schemas: Record<string, OpenAPISchema>, emitted: string[]): string {
+  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: string): string {
+  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: string): string {
+  const parts = typeName.split("::");
+  return parts[parts.length - 1];
+}
+
+/** Extract service name: "Fly::Machines::Machine" → "Machines". */
+export function flyServiceName(typeName: string): string {
+  const parts = typeName.split("::");
+  return parts.length >= 2 ? parts[1] : SERVICE;
+}

package/src/validate-cli.ts

@@ -0,0 +1,5 @@
+#!/usr/bin/env tsx
+import { validate } from "./validate";
+import { printValidationResult } from "@intentius/chant/codegen/validate";
+
+printValidationResult(await validate());

package/src/validate.ts

@@ -0,0 +1,28 @@
+/**
+ * Validate generated lexicon-fly artifacts.
+ *
+ * Thin wrapper around the core validation framework
+ * with fly-specific configuration.
+ */
+
+import { dirname } from "path";
+import { fileURLToPath } from "url";
+import { validateLexiconArtifacts, type ValidateResult } from "@intentius/chant/codegen/validate";
+
+export type { ValidateCheck, ValidateResult } from "@intentius/chant/codegen/validate";
+
+// TODO: Add names of required entities for your lexicon
+const REQUIRED_NAMES: string[] = [];
+
+/**
+ * Validate the generated lexicon-fly artifacts.
+ */
+export async function validate(opts?: { basePath?: string }): Promise<ValidateResult> {
+  const basePath = opts?.basePath ?? dirname(dirname(fileURLToPath(import.meta.url)));
+
+  return validateLexiconArtifacts({
+    lexiconJsonFilename: "lexicon-fly.json",
+    requiredNames: REQUIRED_NAMES,
+    basePath,
+  });
+}