@intentius/chant-lexicon-fly 0.16.0

package/src/composites/fly-deploy.ts

@@ -0,0 +1,169 @@
+/**
+ * fly deploy Op (#744) — the integration proof: `boot → build → flyApply → wait
+ * → teardown` on the local executor. The peer of the aws/gcp deploy Ops in
+ * `examples/local-cloud-trio`, for a single cloud.
+ *
+ * The phases compose modeled activities, no raw shell:
+ *   Emulator  boot mudflaps (the Fly Machines API fake) via `flapsUp`
+ *   Build     run the project's `build:fly` npm script → the serialized plan
+ *   Apply     `flyApply` the plan straight to flaps (creates App + Machine and
+ *             waits each machine to `started` via `/wait`)
+ *   Verify    GET the app's machines and assert one reached `started`
+ *   Teardown  stop and remove the mudflaps container via `flapsDown`
+ *
+ * The activity steps are the generic `activity(fn, args)` builder tagged with
+ * the exported activity function names the fly lexicon contributes
+ * (`flapsUp`/`flapsDown`/`flyApply` from `src/op/activities`). The core activity
+ * registry resolves them by name when a project lists the `fly` lexicon, so
+ * these typed builders give `gcpApply()`-style DX without a core change.
+ *
+ * D3 (local vs real Fly): the Apply step's flaps endpoint defaults to local
+ * mudflaps (`http://localhost:4280`). Pass `endpoint: null` to drop the override
+ * and let `flyApply` fall through to `FLY_FLAPS_BASE_URL` / real Fly (with a
+ * `FLY_API_TOKEN`).
+ */
+
+import { Op, phase, build, activity, httpCheck } from "@intentius/chant/op";
+import type { OpResource } from "@intentius/chant/op";
+import type { ActivityStep } from "@intentius/chant/op";
+
+/** The local mudflaps endpoint the deploy Op targets by default. */
+export const LOCAL_FLAPS_ENDPOINT = "http://localhost:4280";
+
+/** Options accepted by the mudflaps lifecycle step builders. */
+export interface FlapsStepOpts {
+  /** Container name. Default: `chant-mudflaps`. */
+  name?: string;
+  /** Host port mapped to the emulator's `:4280`. Default: `4280`. */
+  port?: number;
+  /** Image. Default: `ghcr.io/intentius/mudflaps:0.3.0`. */
+  image?: string;
+  /** Readiness timeout in ms. */
+  timeoutMs?: number;
+  /** Health poll interval in ms. */
+  intervalMs?: number;
+  /** Activity profile override. */
+  profile?: ActivityStep["profile"];
+}
+
+/**
+ * Boot a local mudflaps (Fly Machines API emulator) in Docker and point the
+ * apply step at it — the typed twin of `flociGcpUp` for flaps. Resolves to the
+ * `flapsUp` activity (#740). Defaults to the `longInfra` profile (the image may
+ * pull); override via `opts.profile`.
+ */
+export const flapsUp = (opts?: FlapsStepOpts): ActivityStep => {
+  const { profile, ...args } = opts ?? {};
+  return activity("flapsUp", args as Record<string, unknown>, profile ?? "longInfra");
+};
+
+/** Stop and remove the local mudflaps container. Resolves to the `flapsDown` activity. Defaults to the `fastIdempotent` profile (override via `opts.profile`). */
+export const flapsDown = (opts?: FlapsStepOpts): ActivityStep => {
+  const { profile, ...args } = opts ?? {};
+  return activity("flapsDown", args as Record<string, unknown>, profile ?? "fastIdempotent");
+};
+
+/** Options for the flaps apply step (mirror `FlyApplyArgs`, minus `planPath`). */
+export interface FlyApplyStepOpts {
+  /** flaps endpoint override (D3). Default: `FLY_FLAPS_BASE_URL` env, else real Fly. */
+  endpoint?: string;
+  /** Bearer token for real Fly. Default: `FLY_API_TOKEN`. mudflaps ignores it. */
+  token?: string;
+  /** Prune declared-then-removed resources (D2). Destructive — off by default. */
+  prune?: boolean;
+  /** Wait-loop tuning (mainly for tests). */
+  wait?: Record<string, unknown>;
+  /** Activity profile override. */
+  profile?: ActivityStep["profile"];
+}
+
+/**
+ * Apply the serialized flaps plan straight to the Machines API — the typed twin
+ * of `gcpApply` for fly. Resolves to the `flyApply` activity (#739): create
+ * App + Machine, wait each machine to `started`, prune owned-only when asked.
+ * Defaults to the `longInfra` profile (override via `opts.profile`).
+ */
+export const flyApplyStep = (planPath: string, opts?: FlyApplyStepOpts): ActivityStep => {
+  const { profile, ...rest } = opts ?? {};
+  return activity("flyApply", { planPath, ...(rest as Record<string, unknown>) }, profile ?? "longInfra");
+};
+
+/** Options for {@link flyDeploy}. */
+export interface FlyDeployOpts {
+  /** Op name (the `chant run <name>` target). Default: `fly`. */
+  name?: string;
+  /** Op overview line. */
+  overview?: string;
+  /** Temporal task queue (unused by the local executor). Default: `local-fly`. */
+  taskQueue?: string;
+  /** Directory the `build:fly` script and plan path are relative to. Default: `.`. */
+  path?: string;
+  /** npm build script to run. Default: `build:fly`. */
+  buildScript?: string;
+  /** Path to the serialized flaps plan the build writes. Default: `dist/fly.json`. */
+  planPath?: string;
+  /**
+   * flaps endpoint the apply + verify steps target (D3). Defaults to local
+   * mudflaps ({@link LOCAL_FLAPS_ENDPOINT}). Pass `null` to drop the override so
+   * `flyApply` targets real Fly via `FLY_FLAPS_BASE_URL` / a `FLY_API_TOKEN`.
+   */
+  endpoint?: string | null;
+  /**
+   * App name for the Verify step. When set (with a local `endpoint`), the Op GETs
+   * the app's machines and asserts one reached `started`. Omitted → no Verify
+   * step (the Apply step still waits each machine to `started`).
+   */
+  app?: string;
+  /** Prune declared-then-removed resources on apply (D2). Off by default. */
+  prune?: boolean;
+  /** Wait-loop tuning passed through to `flyApply` (mainly for tests). */
+  wait?: Record<string, unknown>;
+}
+
+/**
+ * Build a fly deploy Op: boot mudflaps, build the plan, apply App + Machine,
+ * verify the machine reached `started`, tear the emulator down. See the module
+ * docstring for the phase layout and the D3 endpoint story.
+ */
+export function flyDeploy(opts: FlyDeployOpts = {}): InstanceType<typeof OpResource> {
+  const path = opts.path ?? ".";
+  const planPath = opts.planPath ?? "dist/fly.json";
+  const endpoint = opts.endpoint === undefined ? LOCAL_FLAPS_ENDPOINT : opts.endpoint;
+
+  const applyOpts: FlyApplyStepOpts = {
+    ...(endpoint ? { endpoint } : {}),
+    ...(opts.prune ? { prune: true } : {}),
+    ...(opts.wait ? { wait: opts.wait } : {}),
+  };
+
+  const phases = [
+    phase("Emulator", [flapsUp()]),
+    phase("Build", [build(path, { script: opts.buildScript ?? "build:fly" })]),
+    phase("Apply", [flyApplyStep(planPath, applyOpts)]),
+  ];
+
+  // Verify only makes sense against a reachable local endpoint: mudflaps needs
+  // no auth, so a plain GET of the app's machines can assert `started`. Against
+  // real Fly (no endpoint) the flaps API needs a bearer token httpCheck can't
+  // carry, so the Apply step's own `/wait` is the verification there.
+  if (endpoint && opts.app) {
+    phases.push(
+      phase("Verify", [
+        httpCheck(`${endpoint}/v1/apps/${opts.app}/machines`, {
+          contains: "started",
+          retries: 15,
+          intervalMs: 2000,
+        }),
+      ]),
+    );
+  }
+
+  phases.push(phase("Teardown", [flapsDown()]));
+
+  return Op({
+    name: opts.name ?? "fly",
+    overview: opts.overview ?? "Fly: App + Machine → mudflaps (direct flaps apply), local, no account",
+    taskQueue: opts.taskQueue ?? "local-fly",
+    phases,
+  });
+}

package/src/describe-resources.test.ts

@@ -0,0 +1,188 @@
+import { describe, test, expect } from "vitest";
+import { describeResources, flyPlan } from "./describe-resources";
+import type { FlyHttp } from "./op/activities/fly-apply";
+
+// Injected-HTTP unit tests, mirroring fly-apply.test.ts: a scripted flaps answers
+// list/get reads, and describeResources maps them to ResourceMetadata with the
+// right ownership verdict.
+
+const ENDPOINT = "http://localhost:4280";
+const APP = "demo";
+const OWNED_META = { "managed-by": "chant" };
+
+/** A scripted flaps machine as list/get would return it. */
+function liveMachine(
+  name: string,
+  image: string,
+  extra: Partial<{ id: string; state: string; instance_id: string; owned: boolean }> = {},
+): Record<string, unknown> {
+  const metadata = extra.owned === false ? { role: "db" } : { ...OWNED_META };
+  return {
+    id: extra.id ?? `m-${name}`,
+    name,
+    state: extra.state ?? "started",
+    instance_id: extra.instance_id ?? "INST0",
+    config: { image, metadata },
+  };
+}
+
+/** entities map keyed by declared entity name → its entityType (props unused here). */
+function entities(pairs: Array<[string, string]>): Map<string, { entityType: string; props: Record<string, unknown> }> {
+  return new Map(pairs.map(([name, entityType]) => [name, { entityType, props: {} }]));
+}
+
+/**
+ * A fake flaps that serves an app GET, a machine list, and empty breadth lists.
+ * `machines` is the live machine array returned for the app.
+ */
+function fakeHttp(machines: Array<Record<string, unknown>>): FlyHttp {
+  return async (method, url) => {
+    if (method === "GET" && /\/v1\/apps\/[^/]+$/.test(url)) return { status: 200, text: "{}" }; // app exists
+    if (method === "GET" && url.endsWith("/machines")) return { status: 200, text: JSON.stringify(machines) };
+    if (method === "GET" && url.endsWith("/volumes")) return { status: 200, text: "[]" };
+    if (method === "GET" && url.endsWith("/ip_assignments")) return { status: 200, text: JSON.stringify({ ips: [] }) };
+    if (method === "GET" && url.endsWith("/certificates")) return { status: 200, text: JSON.stringify({ certificates: [] }) };
+    return { status: 404, text: "" };
+  };
+}
+
+const PLAN = JSON.stringify({
+  app: { endpoint: "/v1/apps", method: "POST", body: { app_name: APP, org_slug: "personal" } },
+  web: {
+    endpoint: `/v1/apps/${APP}/machines`,
+    method: "POST",
+    body: { name: "web", config: { image: "nginx:1", metadata: { ...OWNED_META } } },
+  },
+});
+
+const ENTS = entities([
+  ["app", "Fly::Machines::App"],
+  ["web", "Fly::Machines::Machine"],
+]);
+
+describe("describeResources: live machines → ResourceMetadata verdicts", () => {
+  test("a managed-by:chant machine is owned; an unmarked one is foreign", async () => {
+    const http = fakeHttp([
+      liveMachine("web", "nginx:1", { id: "m-web" }), // declared + owned
+      liveMachine("legacy", "redis:1", { id: "m-legacy", owned: false }), // orphan + unmarked
+    ]);
+    const res = await describeResources(
+      { environment: "prod", buildOutput: PLAN, entityNames: ["app", "web"], entities: ENTS, endpoint: ENDPOINT },
+      http,
+    );
+
+    // Declared machine keyed by its entity name; orphan keyed by its live name.
+    expect(res.web.type).toBe("Fly::Machines::Machine");
+    expect(res.web.ownership).toBe("owned");
+    expect(res.web.physicalId).toBe("m-web");
+    expect(res.web.status).toBe("started");
+    expect((res.web.attributes as { config?: unknown }).config).toEqual({
+      image: "nginx:1",
+      metadata: { "managed-by": "chant" },
+    });
+
+    expect(res.legacy.ownership).toBe("foreign");
+    expect(res.legacy.type).toBe("Fly::Machines::Machine");
+
+    // App surfaced as owned (app-boundary: it carries an owned machine).
+    expect(res.app.type).toBe("Fly::Machines::App");
+    expect(res.app.ownership).toBe("owned");
+  });
+
+  test("the owned filter drops foreign entries", async () => {
+    const http = fakeHttp([
+      liveMachine("web", "nginx:1", { id: "m-web" }),
+      liveMachine("legacy", "redis:1", { id: "m-legacy", owned: false }),
+    ]);
+    const res = await describeResources(
+      { environment: "prod", buildOutput: PLAN, entityNames: ["app", "web"], entities: ENTS, owned: true, endpoint: ENDPOINT },
+      http,
+    );
+    expect(res.web?.ownership).toBe("owned");
+    expect(res.legacy).toBeUndefined(); // foreign machine filtered out
+  });
+
+  test("terminal machines (destroyed/destroying) are not reported live", async () => {
+    const http = fakeHttp([
+      liveMachine("web", "nginx:1"),
+      liveMachine("gone", "nginx:1", { state: "destroyed" }),
+    ]);
+    const res = await describeResources(
+      { environment: "prod", buildOutput: PLAN, entityNames: ["app", "web"], entities: ENTS, endpoint: ENDPOINT },
+      http,
+    );
+    expect(res.web).toBeDefined();
+    expect(res.gone).toBeUndefined();
+  });
+
+  test("empty build output returns nothing", async () => {
+    const res = await describeResources(
+      { environment: "prod", buildOutput: "", entityNames: [], entities: new Map(), endpoint: ENDPOINT },
+      fakeHttp([]),
+    );
+    expect(res).toEqual({});
+  });
+});
+
+describe("flyPlan: declared-vs-live change set (create/noop/delete/adopt)", () => {
+  test("classifies each action; an unmarked machine is never a delete", async () => {
+    // Declared: app, web (live+equal → noop), web2 (not live → create).
+    const plan = JSON.stringify({
+      app: { endpoint: "/v1/apps", method: "POST", body: { app_name: APP, org_slug: "personal" } },
+      web: {
+        endpoint: `/v1/apps/${APP}/machines`,
+        method: "POST",
+        body: { name: "web", config: { image: "nginx:1", metadata: { ...OWNED_META } } },
+      },
+      web2: {
+        endpoint: `/v1/apps/${APP}/machines`,
+        method: "POST",
+        body: { name: "web2", config: { image: "nginx:1", metadata: { ...OWNED_META } } },
+      },
+    });
+    const ents = entities([
+      ["app", "Fly::Machines::App"],
+      ["web", "Fly::Machines::Machine"],
+      ["web2", "Fly::Machines::Machine"],
+    ]);
+    const http = fakeHttp([
+      liveMachine("web", "nginx:1"), // declared + owned + config equal → noop
+      liveMachine("orphan", "nginx:1"), // owned + undeclared → delete
+      liveMachine("legacy", "redis:1", { owned: false }), // unmarked + undeclared → adopt
+    ]);
+
+    const { changeSet } = await flyPlan(
+      { environment: "prod", buildOutput: plan, entityNames: [...ents.keys()], entities: ents, endpoint: ENDPOINT },
+      http,
+    );
+    const action = (name: string) => changeSet.entries.find((e) => e.name === name)?.action;
+
+    expect(action("web")).toBe("noop");
+    expect(action("web2")).toBe("create");
+    expect(action("orphan")).toBe("delete");
+    expect(action("legacy")).toBe("adopt"); // unmarked → adopt, never delete
+    // No entry, anywhere, deletes an unmarked machine.
+    expect(changeSet.entries.filter((e) => e.action === "delete").map((e) => e.name)).toEqual(["orphan"]);
+  });
+
+  test("config drift on a declared machine → update (configEqual, matching apply)", async () => {
+    const plan = JSON.stringify({
+      app: { endpoint: "/v1/apps", method: "POST", body: { app_name: APP } },
+      web: {
+        endpoint: `/v1/apps/${APP}/machines`,
+        method: "POST",
+        body: { name: "web", config: { image: "nginx:2", metadata: { ...OWNED_META } } },
+      },
+    });
+    const ents = entities([
+      ["app", "Fly::Machines::App"],
+      ["web", "Fly::Machines::Machine"],
+    ]);
+    const http = fakeHttp([liveMachine("web", "nginx:1")]); // live image nginx:1 ≠ declared nginx:2
+    const { changeSet } = await flyPlan(
+      { environment: "prod", buildOutput: plan, entityNames: [...ents.keys()], entities: ents, endpoint: ENDPOINT },
+      http,
+    );
+    expect(changeSet.entries.find((e) => e.name === "web")?.action).toBe("update");
+  });
+});

package/src/detect.ts

@@ -0,0 +1,64 @@
+/**
+ * Template detection for the fly lexicon.
+ *
+ * `chant import` parses a template file as JSON and asks each installed lexicon
+ * whether it recognizes the shape. fly's importable source is flaps JSON — the
+ * Machines API surface the #738 serializer emits and the applier POSTs. Three
+ * shapes are recognized:
+ *
+ *   1. The serializer plan: an object keyed by entity name whose values are
+ *      `{ endpoint, method, body }` flaps requests (what #738 produces).
+ *   2. A machine, a machines listing, or an app-with-machines bundle: what
+ *      `GET /v1/apps/{app}/machines` returns, or a single machine create body.
+ *   3. An app: a create body (`{ app_name }`) or the `GET /v1/apps/{app}` shape.
+ */
+
+function isRecord(v: unknown): v is Record<string, unknown> {
+  return typeof v === "object" && v !== null && !Array.isArray(v);
+}
+
+/** A single flaps request as the serializer emits it. */
+function isFlapsRequest(v: unknown): boolean {
+  if (!isRecord(v)) return false;
+  return typeof v.endpoint === "string" && v.endpoint.startsWith("/v1/apps") && "body" in v;
+}
+
+/** The serializer's whole output: entity name → flaps request. */
+export function isSerializerPlan(v: unknown): boolean {
+  if (!isRecord(v)) return false;
+  const values = Object.values(v);
+  return values.length > 0 && values.every(isFlapsRequest);
+}
+
+/** A live or create-body machine: carries a `config` object, or the id+state+region GET shape. */
+export function isMachineObject(v: unknown): boolean {
+  if (!isRecord(v)) return false;
+  if (isRecord(v.config)) return true;
+  return typeof v.id === "string" && typeof v.state === "string" && "region" in v;
+}
+
+/** An app: a create body (`app_name`) or the `GET /v1/apps/{app}` shape (`name` + machine_count/organization/status). */
+export function isAppObject(v: unknown): boolean {
+  if (!isRecord(v)) return false;
+  if (typeof v.app_name === "string") return true;
+  return (
+    typeof v.name === "string" &&
+    ("machine_count" in v || "organization" in v || typeof v.status === "string")
+  );
+}
+
+export function detectTemplate(data: unknown): boolean {
+  if (isSerializerPlan(data)) return true;
+
+  if (Array.isArray(data)) {
+    return data.length > 0 && data.some(isMachineObject);
+  }
+
+  if (isRecord(data)) {
+    if (Array.isArray(data.machines)) return true;
+    if (isMachineObject(data)) return true;
+    if (isAppObject(data)) return true;
+  }
+
+  return false;
+}

package/src/export-resources.ts

@@ -0,0 +1,123 @@
+/**
+ * Live export for the fly lexicon — implements `LexiconPlugin.exportResources()`
+ * so `chant import --from <fly-env>` regenerates existing Fly apps and machines
+ * as chant TypeScript.
+ *
+ * Reads live flaps state and hands it to the pure `./import/live-export`
+ * helpers, which strip server-written fields to the authored shape and map it to
+ * import IR via `FlyParser`. Endpoint + auth reuse the applier verbatim
+ * (`resolveEndpoint` / `defaultFlyHttp` → FLY_FLAPS_BASE_URL / FLY_API_TOKEN),
+ * and the machine listing reuses the applier's `listMachines`, so export reads
+ * the same target `flyApply` writes and `describeResources` observes.
+ *
+ * Which apps are exported: an app named by the selector, else `FLY_APP_NAME`,
+ * else every app in the org (`GET /v1/apps?org_slug=<FLY_ORG>`). All flaps I/O
+ * lives here; cleaning and IR-building are pure in `./import/live-export`.
+ */
+
+import type { ExportedTemplate, ResourceSelector } from "@intentius/chant/lexicon";
+import {
+  resolveEndpoint,
+  defaultFlyHttp,
+  listMachines,
+  type FlyHttp,
+  type ApplyCtx,
+} from "./op/activities/fly-apply";
+import { buildExportFromApp } from "./import/live-export";
+
+const DEFAULT_ORG = "personal";
+
+function parseJson(text: string): unknown {
+  try {
+    return JSON.parse(text);
+  } catch {
+    return undefined;
+  }
+}
+
+function orgSlug(): string {
+  return process.env.FLY_ORG || process.env.FLY_ORG_SLUG || DEFAULT_ORG;
+}
+
+/** Resolve which apps to export: selector name → FLY_APP_NAME → org listing. */
+async function resolveApps(
+  ctx: ApplyCtx,
+  selector: ResourceSelector | undefined,
+  http: FlyHttp,
+  signal?: AbortSignal,
+): Promise<string[]> {
+  if (selector?.name) return [selector.name];
+  if (process.env.FLY_APP_NAME) return [process.env.FLY_APP_NAME];
+
+  const res = await http(
+    "GET",
+    `${ctx.base}/v1/apps?org_slug=${encodeURIComponent(orgSlug())}`,
+    undefined,
+    undefined,
+    signal,
+  );
+  if (res.status >= 300) return [];
+  const body = parseJson(res.text);
+  const apps = Array.isArray(body)
+    ? body
+    : body && typeof body === "object" && Array.isArray((body as { apps?: unknown[] }).apps)
+      ? (body as { apps: unknown[] }).apps
+      : [];
+  return apps
+    .map((a) => (a && typeof a === "object" ? (a as { name?: unknown }).name : undefined))
+    .filter((n): n is string => typeof n === "string");
+}
+
+export async function exportResources(
+  options: {
+    environment: string;
+    selector?: ResourceSelector;
+    owned?: boolean;
+    verbatim?: boolean;
+  },
+  http: FlyHttp = defaultFlyHttp(),
+  signal?: AbortSignal,
+): Promise<ExportedTemplate> {
+  const ctx: ApplyCtx = { base: resolveEndpoint({}) };
+  const apps = await resolveApps(ctx, options.selector, http, signal);
+  if (apps.length === 0) return { resources: [], parameters: [] };
+
+  // The app-boundary log fires at most once per call, only under `owned`, when
+  // the marker-less app type is reached (mirrors describe-resources).
+  let loggedBoundary = false;
+  const onBoundaryInference = (): void => {
+    if (loggedBoundary) return;
+    loggedBoundary = true;
+    console.warn(
+      "[fly] apps carry no per-resource ownership marker — ownership is inferred at the app boundary (#741/#743); only apps with a chant-managed machine are exported under --owned",
+    );
+  };
+
+  const resources: ExportedTemplate["resources"] = [];
+  for (const app of apps) {
+    const appRes = await http(
+      "GET",
+      `${ctx.base}/v1/apps/${encodeURIComponent(app)}`,
+      undefined,
+      undefined,
+      signal,
+    );
+    const appBody = appRes.status === 200 ? parseJson(appRes.text) : undefined;
+    const appObj =
+      appBody && typeof appBody === "object" && !Array.isArray(appBody)
+        ? (appBody as Record<string, unknown>)
+        : { name: app };
+
+    const machines = await listMachines(ctx, app, http, signal);
+
+    const ir = buildExportFromApp(appObj, machines, {
+      verbatim: options.verbatim,
+      selector: options.selector,
+      owned: options.owned,
+      onBoundaryInference,
+    });
+    resources.push(...ir.resources);
+  }
+
+  return { resources, parameters: [] };
+}