@intentius/chant-lexicon-fly 0.16.0

package/src/import/live-export.test.ts

@@ -0,0 +1,150 @@
+import { describe, test, expect, vi } from "vitest";
+import { stripMachineServerFields, stripAppServerFields, buildExportFromApp } from "./live-export";
+import { FlyGenerator } from "./generator";
+import { exportResources } from "../export-resources";
+import type { FlapsMachine, FlyHttp } from "../op/activities/fly-apply";
+
+const OWNED_META = { "managed-by": "chant" };
+
+/** A live flaps machine as list/get returns it, carrying server-written fields. */
+function liveMachine(name: string, image: string, owned = true): FlapsMachine {
+  return {
+    id: `m-${name}`,
+    name,
+    state: "started",
+    instance_id: "INST0",
+    private_ip: "fdaa::1",
+    config: { image, metadata: owned ? { ...OWNED_META } : { role: "db" } },
+  } as unknown as FlapsMachine;
+}
+
+/** A live app as GET /v1/apps/{app} returns it. */
+function liveApp() {
+  return {
+    id: "app-1",
+    name: "my-app",
+    status: "deployed",
+    machine_count: 1,
+    volume_count: 0,
+    internal_numeric_id: 42,
+    organization: { slug: "acme" },
+  };
+}
+
+describe("fly stripMachineServerFields", () => {
+  test("drops server-written read-only fields, keeps config", () => {
+    const cleaned = stripMachineServerFields(liveMachine("web", "nginx:1") as unknown as Record<string, unknown>);
+    expect(cleaned.id).toBeUndefined();
+    expect(cleaned.state).toBeUndefined();
+    expect(cleaned.instance_id).toBeUndefined();
+    expect(cleaned.private_ip).toBeUndefined();
+    expect(cleaned.name).toBe("web");
+    expect(cleaned.config).toEqual({ image: "nginx:1", metadata: { "managed-by": "chant" } });
+  });
+
+  test("does not mutate the input", () => {
+    const input = liveMachine("web", "nginx:1") as unknown as Record<string, unknown>;
+    stripMachineServerFields(input);
+    expect(input.id).toBe("m-web");
+  });
+});
+
+describe("fly stripAppServerFields", () => {
+  test("drops read-only app fields and carries organization.slug into org_slug", () => {
+    const cleaned = stripAppServerFields(liveApp() as unknown as Record<string, unknown>);
+    expect(cleaned.id).toBeUndefined();
+    expect(cleaned.status).toBeUndefined();
+    expect(cleaned.machine_count).toBeUndefined();
+    expect(cleaned.organization).toBeUndefined();
+    expect(cleaned.name).toBe("my-app");
+    expect(cleaned.org_slug).toBe("acme");
+  });
+});
+
+describe("fly buildExportFromApp", () => {
+  test("maps an app and its machines to export IR, stripped by default", () => {
+    const ir = buildExportFromApp(liveApp(), [liveMachine("web", "nginx:1")]);
+    expect(ir.resources.map((r) => r.type)).toEqual([
+      "Fly::Machines::App",
+      "Fly::Machines::Machine",
+    ]);
+    const machine = ir.resources.find((r) => r.type === "Fly::Machines::Machine")!;
+    expect((machine.properties as Record<string, unknown>).id).toBeUndefined();
+    expect(machine.properties.config).toEqual({ image: "nginx:1", metadata: { "managed-by": "chant" } });
+    const app = ir.resources.find((r) => r.type === "Fly::Machines::App")!;
+    expect(app.properties.org_slug).toBe("acme");
+  });
+
+  test("verbatim is inert: fly maps only the writable surface, so server fields never round-trip", () => {
+    const ir = buildExportFromApp(liveApp(), [liveMachine("web", "nginx:1")], { verbatim: true });
+    const machine = ir.resources.find((r) => r.type === "Fly::Machines::Machine")!;
+    expect((machine.properties as Record<string, unknown>).id).toBeUndefined();
+    expect((machine.properties as Record<string, unknown>).instance_id).toBeUndefined();
+  });
+
+  test("owned filter drops unmarked machines and keeps the app (it has a managed machine)", () => {
+    const ir = buildExportFromApp(liveApp(), [liveMachine("web", "nginx:1", true), liveMachine("legacy", "redis:7", false)], { owned: true });
+    const machines = ir.resources.filter((r) => r.type === "Fly::Machines::Machine");
+    expect(machines.map((m) => m.logicalId)).toEqual(["web"]);
+    expect(ir.resources.some((r) => r.type === "Fly::Machines::App")).toBe(true);
+  });
+
+  test("owned filter drops the app when no machine is chant-managed, and logs the boundary inference", () => {
+    const onBoundaryInference = vi.fn();
+    const ir = buildExportFromApp(liveApp(), [liveMachine("legacy", "redis:7", false)], { owned: true, onBoundaryInference });
+    expect(ir.resources.some((r) => r.type === "Fly::Machines::App")).toBe(false);
+    expect(ir.resources.some((r) => r.type === "Fly::Machines::Machine")).toBe(false);
+    expect(onBoundaryInference).toHaveBeenCalled();
+  });
+
+  test("selector by type narrows the export", () => {
+    const ir = buildExportFromApp(liveApp(), [liveMachine("web", "nginx:1")], {
+      selector: { type: "Fly::Machines::Machine" },
+    });
+    expect(ir.resources.map((r) => r.type)).toEqual(["Fly::Machines::Machine"]);
+  });
+
+  test("export IR feeds FlyGenerator (templateGenerator) unchanged", () => {
+    const ir = buildExportFromApp(liveApp(), [liveMachine("web", "nginx:1")]);
+    const files = new FlyGenerator().generate(ir);
+    expect(files[0].content).toContain("new Machine({");
+  });
+});
+
+describe("fly exportResources (live I/O over injected flaps)", () => {
+  const APP = "my-app";
+
+  /** A fake flaps serving the app listing, one app GET, and one machine list. */
+  function fakeHttp(machines: FlapsMachine[]): FlyHttp {
+    return async (method, url) => {
+      if (method === "GET" && url.includes("/v1/apps?org_slug=")) {
+        return { status: 200, text: JSON.stringify({ apps: [{ name: APP }] }) };
+      }
+      if (method === "GET" && new RegExp(`/v1/apps/${APP}$`).test(url)) {
+        return { status: 200, text: JSON.stringify(liveApp()) };
+      }
+      if (method === "GET" && url.endsWith("/machines")) {
+        return { status: 200, text: JSON.stringify(machines) };
+      }
+      return { status: 404, text: "" };
+    };
+  }
+
+  test("discovers the org's apps, lists machines, and returns the declared shape", async () => {
+    const http = fakeHttp([liveMachine("web", "nginx:1")]);
+    const ir = await exportResources({ environment: "prod" }, http);
+    expect(ir.resources.map((r) => r.type)).toEqual([
+      "Fly::Machines::App",
+      "Fly::Machines::Machine",
+    ]);
+    const machine = ir.resources.find((r) => r.type === "Fly::Machines::Machine")!;
+    expect((machine.properties as Record<string, unknown>).instance_id).toBeUndefined();
+  });
+
+  test("owned filter drops the foreign machine", async () => {
+    const http = fakeHttp([liveMachine("web", "nginx:1", true), liveMachine("legacy", "redis:7", false)]);
+    const ir = await exportResources({ environment: "prod", owned: true }, http);
+    const machines = ir.resources.filter((r) => r.type === "Fly::Machines::Machine");
+    expect(machines.map((m) => m.logicalId)).toEqual(["web"]);
+  });
+});

package/src/import/live-export.ts

@@ -0,0 +1,107 @@
+/**
+ * Pure export helpers for the fly lexicon — strip live flaps state to the
+ * authored shape and build import IR from it. All flaps I/O stays in the caller
+ * (`../export-resources`); this module is deterministic and unit-testable.
+ *
+ * The strip mirrors the read-only field lists the parser drops, so a live
+ * machine/app reaches the same declared shape a user would have written. Machine
+ * ownership is a per-resource marker (`managed-by: chant` in `config.metadata`,
+ * read via `isChantOwned`); the app carries no marker, so under the `owned`
+ * filter its ownership is inferred at the app boundary (an app is chant-managed
+ * when one of its machines is), and the limitation is logged rather than
+ * silently returning everything — the seam contract, matching gcp/aws.
+ *
+ * `verbatim` is inert for fly (the core contract permits this for targets whose
+ * importable surface is already the declared shape): the App/Machine
+ * constructors accept only the writable surface, so server-written fields are
+ * not constructor parameters and cannot round-trip into the generated code. The
+ * option is accepted for signature parity.
+ */
+
+import type { ExportedTemplate, ResourceSelector } from "@intentius/chant/lexicon";
+import { isChantOwned, type FlapsMachine } from "../op/activities/fly-apply";
+import {
+  FlyParser,
+  MACHINE_SERVER_FIELDS,
+  APP_SERVER_FIELDS,
+} from "./parser";
+
+function isRecord(v: unknown): v is Record<string, unknown> {
+  return typeof v === "object" && v !== null && !Array.isArray(v);
+}
+
+/** Drop server-written read-only machine fields to reach the authored shape. Returns a new object. */
+export function stripMachineServerFields(machine: Record<string, unknown>): Record<string, unknown> {
+  const clone = JSON.parse(JSON.stringify(machine)) as Record<string, unknown>;
+  for (const f of MACHINE_SERVER_FIELDS) delete clone[f];
+  return clone;
+}
+
+/** Drop server-written read-only app fields, keeping `name`/`org_slug`. Returns a new object. */
+export function stripAppServerFields(app: Record<string, unknown>): Record<string, unknown> {
+  const clone = JSON.parse(JSON.stringify(app)) as Record<string, unknown>;
+  // Carry the org slug down before dropping the organization object it rides on.
+  if (clone.org_slug === undefined && isRecord(clone.organization) && typeof clone.organization.slug === "string") {
+    clone.org_slug = clone.organization.slug;
+  }
+  for (const f of APP_SERVER_FIELDS) delete clone[f];
+  return clone;
+}
+
+/**
+ * Build export IR from one app's live flaps state. Reuses {@link FlyParser} as
+ * the single wire→authoring mapping authority by feeding it a cleaned
+ * app-with-machines bundle.
+ *
+ * `opts.owned` keeps only machines carrying the chant marker, and includes the
+ * app only when it is chant-managed (a machine is). `opts.verbatim` keeps server
+ * fields. Pure: logging is delegated to `opts.onBoundaryInference`, which the
+ * I/O caller wires to a single warn.
+ */
+export function buildExportFromApp(
+  app: Record<string, unknown> | undefined,
+  machines: FlapsMachine[],
+  opts: {
+    verbatim?: boolean;
+    selector?: ResourceSelector;
+    owned?: boolean;
+    onBoundaryInference?: () => void;
+  } = {},
+): ExportedTemplate {
+  const appManaged = machines.some((m) => isChantOwned(m.config?.metadata));
+
+  const keptMachines = opts.owned
+    ? machines.filter((m) => isChantOwned(m.config?.metadata))
+    : machines;
+
+  // The app has no per-resource marker; under `owned` it rides the app boundary.
+  let keptApp = app;
+  if (opts.owned && app) {
+    opts.onBoundaryInference?.();
+    if (!appManaged) keptApp = undefined;
+  }
+
+  // The parser maps to the writable surface regardless; the explicit strip here
+  // keeps the pure cleaning layer visible and testable. `verbatim` is inert (see
+  // module header) — server fields are not App/Machine constructor parameters.
+  const cleanMachines = keptMachines.map((m) =>
+    stripMachineServerFields(m as unknown as Record<string, unknown>),
+  );
+  const cleanApp = keptApp ? stripAppServerFields(keptApp) : keptApp;
+
+  const bundle: Record<string, unknown> = { ...(cleanApp ?? {}), machines: cleanMachines };
+  const ir = new FlyParser().parse(JSON.stringify(bundle));
+
+  const selector = opts.selector;
+  if (!selector || (selector.type === undefined && selector.name === undefined)) {
+    return ir;
+  }
+  return {
+    ...ir,
+    resources: ir.resources.filter(
+      (r) =>
+        (selector.type === undefined || r.type === selector.type) &&
+        (selector.name === undefined || r.logicalId === selector.name),
+    ),
+  };
+}

package/src/import/parser.test.ts

@@ -0,0 +1,132 @@
+import { describe, test, expect } from "vitest";
+import { FlyParser } from "./parser";
+
+const parser = new FlyParser();
+
+describe("FlyParser", () => {
+  test("empty input returns empty resources", () => {
+    const ir = parser.parse("");
+    expect(ir.resources).toEqual([]);
+    expect(ir.parameters).toEqual([]);
+  });
+
+  test("serializer plan: /v1/apps body → App, app_name mapped to name", () => {
+    const plan = JSON.stringify({
+      app: { endpoint: "/v1/apps", method: "POST", body: { app_name: "my-app", org_slug: "personal" } },
+    });
+    const ir = parser.parse(plan);
+    expect(ir.resources).toHaveLength(1);
+    const app = ir.resources[0];
+    expect(app.type).toBe("Fly::Machines::App");
+    expect(app.logicalId).toBe("my-app");
+    expect(app.properties.name).toBe("my-app");
+    expect(app.properties.org_slug).toBe("personal");
+    // The wire field name never leaks into the authoring surface.
+    expect((app.properties as Record<string, unknown>).app_name).toBeUndefined();
+  });
+
+  test("serializer plan: machines endpoint → Machine with name/region/config", () => {
+    const plan = JSON.stringify({
+      web: {
+        endpoint: "/v1/apps/my-app/machines",
+        method: "POST",
+        body: { name: "web", region: "iad", config: { image: "nginx:1" } },
+      },
+    });
+    const ir = parser.parse(plan);
+    expect(ir.resources).toHaveLength(1);
+    const m = ir.resources[0];
+    expect(m.type).toBe("Fly::Machines::Machine");
+    expect(m.logicalId).toBe("web");
+    expect(m.properties.name).toBe("web");
+    expect(m.properties.region).toBe("iad");
+    expect(m.properties.config).toEqual({ image: "nginx:1" });
+  });
+
+  test("serializer plan with an App and a Machine → both resources", () => {
+    const plan = JSON.stringify({
+      app: { endpoint: "/v1/apps", method: "POST", body: { app_name: "my-app" } },
+      web: {
+        endpoint: "/v1/apps/my-app/machines",
+        method: "POST",
+        body: { name: "web", region: "iad", config: { image: "nginx:1" } },
+      },
+    });
+    const ir = parser.parse(plan);
+    expect(ir.resources.map((r) => r.type)).toEqual([
+      "Fly::Machines::App",
+      "Fly::Machines::Machine",
+    ]);
+  });
+
+  test("machines listing (array) → one Machine each", () => {
+    const listing = JSON.stringify([
+      { id: "m1", name: "web", region: "iad", state: "started", config: { image: "nginx:1" } },
+      { id: "m2", name: "worker", region: "iad", state: "started", config: { image: "redis:7" } },
+    ]);
+    const ir = parser.parse(listing);
+    expect(ir.resources.map((r) => r.logicalId)).toEqual(["web", "worker"]);
+    expect(ir.resources.every((r) => r.type === "Fly::Machines::Machine")).toBe(true);
+  });
+
+  test("machine object strips server-written read-only fields", () => {
+    const machine = JSON.stringify({
+      id: "abc123",
+      name: "web",
+      region: "iad",
+      state: "started",
+      instance_id: "INST0",
+      private_ip: "fdaa::1",
+      created_at: "2026-01-01T00:00:00Z",
+      updated_at: "2026-01-02T00:00:00Z",
+      nonce: "n1",
+      events: [{ type: "start" }],
+      checks: [{ status: "passing" }],
+      host_status: "ok",
+      image_ref: { tag: "latest" },
+      incomplete_config: { image: "x" },
+      config: { image: "nginx:1", metadata: { "managed-by": "chant" } },
+    });
+    const ir = parser.parse(machine);
+    const props = ir.resources[0].properties;
+    expect(props).toEqual({
+      name: "web",
+      region: "iad",
+      config: { image: "nginx:1", metadata: { "managed-by": "chant" } },
+    });
+  });
+
+  test("app-with-machines bundle → App plus its Machines", () => {
+    const bundle = JSON.stringify({
+      name: "my-app",
+      org_slug: "personal",
+      machines: [{ name: "web", region: "iad", config: { image: "nginx:1" } }],
+    });
+    const ir = parser.parse(bundle);
+    expect(ir.resources.map((r) => r.type)).toEqual([
+      "Fly::Machines::App",
+      "Fly::Machines::Machine",
+    ]);
+    expect(ir.resources[0].properties.name).toBe("my-app");
+  });
+
+  test("app GET shape: name + organization.slug → App with org_slug", () => {
+    const appGet = JSON.stringify({
+      id: "app-1",
+      name: "my-app",
+      status: "deployed",
+      machine_count: 2,
+      organization: { slug: "acme" },
+    });
+    const ir = parser.parse(appGet);
+    expect(ir.resources).toHaveLength(1);
+    expect(ir.resources[0].type).toBe("Fly::Machines::App");
+    expect(ir.resources[0].properties.name).toBe("my-app");
+    expect(ir.resources[0].properties.org_slug).toBe("acme");
+  });
+
+  test("parameters are always empty (flaps has no template parameters)", () => {
+    const ir = parser.parse(JSON.stringify({ app_name: "x" }));
+    expect(ir.parameters).toEqual([]);
+  });
+});

package/src/import/parser.ts

@@ -0,0 +1,185 @@
+/**
+ * flaps JSON template parser.
+ *
+ * Turns Fly Machines API ("flaps") JSON into the import IR for conversion to
+ * chant TypeScript. Three input shapes are accepted, all mapped to the authoring
+ * surface (the writable fields a user would have declared):
+ *
+ *   1. The #738 serializer plan — `{ <entity>: { endpoint, method, body } }`.
+ *      `/v1/apps` bodies become `App`s; `.../machines` bodies become `Machine`s.
+ *   2. A machines listing (an array) or an app-with-machines bundle
+ *      (`{ ...appFields, machines: [...] }`) — an `App` plus its `Machine`s.
+ *   3. A single machine (`{ name, region, config }`) or a single app
+ *      (`{ app_name }` / the `GET /v1/apps/{app}` shape).
+ *
+ * flaps wire field names are mapped back to the authoring surface: an app's
+ * `app_name` becomes the `App`'s `name`, and server-written read-only machine
+ * fields (id, state, instance_id, ...) are dropped so the IR is the declared
+ * shape. `logicalId` is the app/machine name (the generator camelCases it into a
+ * variable).
+ */
+
+import type {
+  TemplateParser,
+  TemplateIR,
+  ResourceIR,
+} from "@intentius/chant/import/parser";
+import { BaseValueParser } from "@intentius/chant/import/base-parser";
+import { isSerializerPlan } from "../detect";
+
+export const APP_TYPE = "Fly::Machines::App";
+export const MACHINE_TYPE = "Fly::Machines::Machine";
+
+/** Server-written read-only machine fields — never part of the authored shape. */
+export const MACHINE_SERVER_FIELDS = [
+  "id",
+  "state",
+  "created_at",
+  "updated_at",
+  "private_ip",
+  "instance_id",
+  "nonce",
+  "checks",
+  "events",
+  "host_status",
+  "image_ref",
+  "incomplete_config",
+];
+
+/** Server-written read-only app fields — never part of the authored shape. */
+export const APP_SERVER_FIELDS = [
+  "id",
+  "status",
+  "machine_count",
+  "volume_count",
+  "internal_numeric_id",
+  "organization",
+];
+
+function isRecord(v: unknown): v is Record<string, unknown> {
+  return typeof v === "object" && v !== null && !Array.isArray(v);
+}
+
+export class FlyParser extends BaseValueParser implements TemplateParser {
+  protected dispatchIntrinsic(
+    _key: string,
+    _value: unknown,
+    _obj: Record<string, unknown>,
+  ): unknown | null {
+    // flaps JSON has no intrinsic functions.
+    return null;
+  }
+
+  parse(input: string): TemplateIR {
+    const trimmed = input.trim();
+    if (!trimmed) return { resources: [], parameters: [] };
+
+    const data = JSON.parse(trimmed) as unknown;
+    const resources: ResourceIR[] = [];
+
+    if (isSerializerPlan(data)) {
+      for (const [entityName, req] of Object.entries(data as Record<string, unknown>)) {
+        const r = this.resourceFromRequest(entityName, req as Record<string, unknown>);
+        if (r) resources.push(r);
+      }
+      return { resources, parameters: [] };
+    }
+
+    if (Array.isArray(data)) {
+      for (const m of data) {
+        if (isRecord(m)) resources.push(this.machineResource(m));
+      }
+      return { resources, parameters: [] };
+    }
+
+    if (isRecord(data)) {
+      // App-with-machines bundle: top-level app fields plus a `machines` array.
+      if (Array.isArray(data.machines)) {
+        const { machines, ...appFields } = data;
+        if (this.looksLikeApp(appFields)) resources.push(this.appResource(appFields));
+        for (const m of machines) {
+          if (isRecord(m)) resources.push(this.machineResource(m));
+        }
+        return { resources, parameters: [] };
+      }
+
+      // A single machine (has a config) wins over an app read, since a machine
+      // GET also carries a `name`.
+      if (isRecord(data.config)) {
+        resources.push(this.machineResource(data));
+        return { resources, parameters: [] };
+      }
+
+      if (this.looksLikeApp(data)) {
+        resources.push(this.appResource(data));
+        return { resources, parameters: [] };
+      }
+    }
+
+    return { resources, parameters: [] };
+  }
+
+  /** Map one serializer-plan request to a resource by its endpoint. */
+  private resourceFromRequest(
+    entityName: string,
+    req: Record<string, unknown>,
+  ): ResourceIR | null {
+    const endpoint = typeof req.endpoint === "string" ? req.endpoint : "";
+    const body = isRecord(req.body) ? req.body : {};
+
+    if (/^\/v1\/apps\/?$/.test(endpoint)) {
+      return this.appResource(body, entityName);
+    }
+    if (/^\/v1\/apps\/[^/]+\/machines\/?$/.test(endpoint)) {
+      return this.machineResource(body, entityName);
+    }
+    // Other endpoints (volumes, ip_assignments, certificates, secrets) are not
+    // part of the App/Machine import surface.
+    return null;
+  }
+
+  private looksLikeApp(obj: Record<string, unknown>): boolean {
+    return typeof obj.app_name === "string" || typeof obj.name === "string";
+  }
+
+  /** An `App` resource. flaps `app_name` (create body) or `name` (GET) → `name`. */
+  private appResource(obj: Record<string, unknown>, entityName?: string): ResourceIR {
+    const name =
+      (typeof obj.app_name === "string" && obj.app_name) ||
+      (typeof obj.name === "string" && obj.name) ||
+      entityName ||
+      "app";
+
+    const properties: Record<string, unknown> = { name };
+    // org_slug either sits on the create body directly, or is carried on the GET
+    // shape under `organization.slug`.
+    if (obj.org_slug !== undefined) {
+      properties.org_slug = this.parseValue(obj.org_slug);
+    } else if (isRecord(obj.organization) && typeof obj.organization.slug === "string") {
+      properties.org_slug = obj.organization.slug;
+    }
+    if (obj.network !== undefined) properties.network = this.parseValue(obj.network);
+    if (obj.enable_subdomains !== undefined) {
+      properties.enable_subdomains = this.parseValue(obj.enable_subdomains);
+    }
+
+    return { logicalId: name, type: APP_TYPE, properties };
+  }
+
+  /** A `Machine` resource, stripped of server-written read-only fields. */
+  private machineResource(obj: Record<string, unknown>, entityName?: string): ResourceIR {
+    const name =
+      (typeof obj.name === "string" && obj.name) || entityName || "machine";
+
+    const properties: Record<string, unknown> = {};
+    for (const [key, value] of Object.entries(obj)) {
+      if (MACHINE_SERVER_FIELDS.includes(key)) continue;
+      if (value === undefined) continue;
+      properties[key] = this.parseValue(value);
+    }
+    // Always carry a name so the round-trip keeps the machine's identity.
+    properties.name = name;
+
+    return { logicalId: name, type: MACHINE_TYPE, properties };
+  }
+}

package/src/import/roundtrip.test.ts

@@ -0,0 +1,77 @@
+import { describe, test, expect } from "vitest";
+import { writeFileSync, mkdtempSync } from "fs";
+import { join, dirname } from "path";
+import { tmpdir } from "os";
+import { fileURLToPath } from "url";
+import { FlyParser } from "./parser";
+import { FlyGenerator } from "./generator";
+import { flySerializer } from "../serializer";
+import { App, Machine, MachineConfig, MachineGuest } from "../generated/index";
+
+const here = dirname(fileURLToPath(import.meta.url));
+const generatedIndex = join(here, "..", "generated", "index");
+
+const parser = new FlyParser();
+const generator = new FlyGenerator();
+
+describe("roundtrip: flaps plan → parse → generate TypeScript", () => {
+  test("an App + Machine plan generates equivalent chant TS", () => {
+    const plan = JSON.stringify({
+      app: { endpoint: "/v1/apps", method: "POST", body: { app_name: "my-app", org_slug: "personal" } },
+      web: {
+        endpoint: "/v1/apps/my-app/machines",
+        method: "POST",
+        body: { name: "web", region: "iad", config: { image: "nginx:1", guest: { cpu_kind: "shared", cpus: 1 } } },
+      },
+    });
+    const ts = generator.generate(parser.parse(plan))[0].content;
+    expect(ts).toContain("new App({");
+    expect(ts).toContain("new Machine({");
+    expect(ts).toContain("new MachineConfig({");
+    expect(ts).toContain('image: "nginx:1"');
+    expect(ts).toContain('region: "iad"');
+  });
+});
+
+describe("roundtrip: declared entities → serialize → parse → generate → re-serialize", () => {
+  test("the generated code compiles, runs, and re-serializes to equivalent flaps bodies", async () => {
+    // 1. Declare an App + Machine and serialize with the #738 serializer.
+    const app = new App({ name: "my-app", org_slug: "personal" });
+    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 }),
+      }),
+    });
+    const entities = new Map<string, any>([
+      ["app", app],
+      ["web", web],
+    ]);
+    const planA = JSON.parse(flySerializer.serialize(entities));
+
+    // 2. Parse the plan and generate TypeScript.
+    const ir = parser.parse(JSON.stringify(planA));
+    const ts = generator.generate(ir)[0].content;
+
+    // 3. Execute the generated code: rewrite the package import to the local
+    //    generated module, then dynamic-import it.
+    const runnable = ts.replace(
+      '"@intentius/chant-lexicon-fly"',
+      JSON.stringify(generatedIndex),
+    );
+    const file = join(mkdtempSync(join(tmpdir(), "fly-roundtrip-")), "main.ts");
+    writeFileSync(file, runnable);
+    const mod = await import(file);
+
+    // 4. Re-serialize the regenerated entities.
+    const regenerated = new Map<string, any>(Object.entries(mod));
+    const planB = JSON.parse(flySerializer.serialize(regenerated));
+
+    // The bodies survive the round-trip. Entity keys differ (variable names are
+    // camelCased from the resource name), so compare the create bodies by kind.
+    const bodies = (plan: Record<string, any>) => Object.values(plan).map((r) => r.body).sort((a, b) => JSON.stringify(a).localeCompare(JSON.stringify(b)));
+    expect(bodies(planB)).toEqual(bodies(planA));
+  });
+});

package/src/index.ts

@@ -0,0 +1,23 @@
+// Plugin
+export { flyPlugin } from "./plugin";
+
+// Serializer
+export { flySerializer } from "./serializer";
+
+// Pseudo-parameters — environment-resolved values (`Fly.Region`, `Fly.OrgSlug`,
+// `Fly.AppName`) usable in place of hard-coded strings.
+export { Fly, Region, OrgSlug, AppName, PseudoParameter } from "./pseudo";
+
+// Ownership marker convention (machine config.metadata keys)
+export { FLY_METADATA_OWNERSHIP_KEYS } from "./ownership";
+
+// Deploy Op composite + typed step builders (#744). `flyDeploy` returns a
+// `boot → build → flyApply → wait → teardown` Op; the step builders wrap the
+// generic `activity()` so the fly activities resolve by name without a core change.
+export { flyDeploy, flapsUp, flapsDown, flyApplyStep, LOCAL_FLAPS_ENDPOINT } from "./composites/fly-deploy";
+export type { FlyDeployOpts, FlyApplyStepOpts, FlapsStepOpts } from "./composites/fly-deploy";
+
+// Generated resources — export everything from generated index.
+// Provides `App`, `Machine`, `Volume`, and the property types
+// (`MachineConfig`, `MachineGuest`, `MachineService`, ...) for authoring.
+export * from "./generated/index";