@intentius/chant-lexicon-fly 0.16.0 → 0.18.0

package/src/op/activities/machines-contract.docker.integration.test.ts

@@ -0,0 +1,72 @@
+import { describe, test, expect, beforeAll, afterAll } from "vitest";
+import { flapsUp, flapsDown } from "./flaps";
+import { MACHINES_CONTRACT, normalizeEndpoint, contractKeys } from "./machines-contract";
+
+// Fidelity check: every flaps endpoint the flyApply applier depends on
+// (MACHINES_CONTRACT) must be served by the pinned mudflaps image — the twin of
+// the Sprites contract ⊆ spritzer check (#808 T3). mudflaps enumerates its
+// implemented paths at `/_mudflaps/health` and answers roadmap endpoints
+// (machines/{id}/signal, /exec, /ps) with 501; flyApply must never depend on one.
+// Docker required; skipped in CI unless FLY_DOCKER=1 (GitHub runners have Docker,
+// so relying on absence would pull the image on every run).
+
+const CONTAINER = "chant-mudflaps-contract-it";
+const PORT = 4283;
+
+let available = false;
+let endpoint = "";
+
+/** Parse a mudflaps health `implemented` entry ("METHOD path (note)") to a normalized key. */
+function normalizeImplemented(entry: string): string {
+  const stripped = entry.replace(/\s*\(.*\)\s*$/, "").trim();
+  const sp = stripped.indexOf(" ");
+  return normalizeEndpoint(stripped.slice(0, sp), stripped.slice(sp + 1));
+}
+
+beforeAll(async () => {
+  if (process.env.CI && !process.env.FLY_DOCKER) {
+    available = false;
+    return;
+  }
+  try {
+    const up = await flapsUp({ name: CONTAINER, port: PORT, timeoutMs: 30_000 });
+    endpoint = up.endpoint;
+    available = true;
+  } catch {
+    available = false;
+  }
+}, 60_000);
+
+afterAll(async () => {
+  if (available) await flapsDown({ name: CONTAINER });
+});
+
+describe("Machines contract ⊆ mudflaps implemented paths", () => {
+  test("the pinned mudflaps serves every endpoint flyApply depends on", async (ctx) => {
+    if (!available) ctx.skip();
+
+    const res = await fetch(`${endpoint}/_mudflaps/health`);
+    expect(res.ok).toBe(true);
+    const health = (await res.json()) as { implemented?: string[] };
+    expect(Array.isArray(health.implemented)).toBe(true);
+
+    const served = new Set((health.implemented ?? []).map(normalizeImplemented));
+
+    const missing = [...contractKeys()].filter((k) => !served.has(k));
+    // A non-empty list means flyApply calls something mudflaps can't serve — a
+    // real fidelity gap between the applier and the pinned emulator.
+    expect(missing, `mudflaps is missing contract endpoints: ${missing.join(", ")}`).toEqual([]);
+  });
+
+  test("flyApply never depends on a mudflaps roadmap (501) endpoint", async (ctx) => {
+    if (!available) ctx.skip();
+    const res = await fetch(`${endpoint}/_mudflaps/health`);
+    const health = (await res.json()) as { unimplemented?: string[] };
+    const roadmap = new Set((health.unimplemented ?? []).map(normalizeImplemented));
+
+    for (const e of MACHINES_CONTRACT) {
+      const key = normalizeEndpoint(e.method, e.path);
+      expect(roadmap.has(key), `${e.op} → ${e.method} ${e.path} is a mudflaps roadmap endpoint`).toBe(false);
+    }
+  });
+});

package/src/op/activities/machines-contract.test.ts

@@ -0,0 +1,49 @@
+import { describe, test, expect } from "vitest";
+import { readFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { dirname, join } from "node:path";
+import { MACHINES_CONTRACT, normalizeEndpoint, contractKeys } from "./machines-contract";
+
+describe("MACHINES_CONTRACT", () => {
+  test("covers the flyApply resource operations (apps, machines, leases, volumes, ips, certs, secrets)", () => {
+    for (const area of ["/machines", "/lease", "/volumes", "/ip_assignments", "/certificates", "/secrets"]) {
+      expect(MACHINES_CONTRACT.some((e) => e.path.includes(area)), area).toBe(true);
+    }
+    expect(MACHINES_CONTRACT.some((e) => e.path === "/v1/apps"), "apps").toBe(true);
+  });
+
+  test("every entry has a v1/apps path and a known method", () => {
+    for (const e of MACHINES_CONTRACT) {
+      expect(e.path.startsWith("/v1/apps")).toBe(true);
+      expect(["GET", "POST", "PUT", "DELETE"]).toContain(e.method);
+    }
+  });
+
+  test("normalizeEndpoint collapses param names ({id} ≡ {vol} ≡ {hostname})", () => {
+    expect(normalizeEndpoint("DELETE", "/v1/apps/{app}/volumes/{id}")).toBe(
+      normalizeEndpoint("DELETE", "/v1/apps/{app}/volumes/{vol}"),
+    );
+    expect(normalizeEndpoint("GET", "/v1/apps/{app}")).toBe("GET /v1/apps/{}");
+  });
+
+  test("contractKeys is the deduped normalized set", () => {
+    const keys = contractKeys();
+    expect(keys.has("POST /v1/apps")).toBe(true);
+    expect(keys.has("DELETE /v1/apps/{}/machines/{}")).toBe(true);
+    // lease acquire (POST) and release (DELETE) are distinct keys
+    expect(keys.has("POST /v1/apps/{}/machines/{}/lease")).toBe(true);
+    expect(keys.has("DELETE /v1/apps/{}/machines/{}/lease")).toBe(true);
+  });
+
+  test("every contract path segment appears in the fly-apply.ts source (drift anchor)", () => {
+    const src = readFileSync(join(dirname(fileURLToPath(import.meta.url)), "fly-apply.ts"), "utf-8");
+    const segments = new Set(
+      MACHINES_CONTRACT.flatMap((e) =>
+        e.path.split("/").filter((s) => s.length > 0 && !s.startsWith("{")),
+      ),
+    );
+    for (const seg of segments) {
+      expect(src, `path segment "${seg}" from the contract is absent from fly-apply.ts`).toContain(seg);
+    }
+  });
+});

package/src/op/activities/machines-contract.ts

@@ -0,0 +1,73 @@
+/**
+ * Fly Machines (flaps) API contract — the endpoint set the `flyApply` applier
+ * (./fly-apply.ts) depends on, and the mudflaps counterpart of the hand-authored
+ * Sprites contract (./sprites-contract.ts, #808 T3).
+ *
+ * Unlike Sprites, Machines *does* ship a machine-readable OpenAPI that the fly
+ * resource surface drift-checks against (docs.machines.dev, the rolling-upgrade
+ * path #813). This contract serves a different fidelity axis: it pins the exact
+ * endpoints flyApply calls so the docker-gated coverage test can prove the pinned
+ * mudflaps emulator serves them all. mudflaps carries roadmap endpoints that
+ * answer 501 (currently machines/{id}/signal, /exec, /ps) — flyApply must never
+ * depend on one; if it ever does, the coverage test fails instead of the applier
+ * silently passing against a fake that can't model the call.
+ *
+ * Param names match ./fly-apply.ts's URL builders (`{app}`, `{id}`); the coverage
+ * check normalizes param names before comparing, since mudflaps spells volume
+ * ids `{vol}` and cert hostnames `{hostname}`.
+ */
+
+/** One flaps endpoint the flyApply applier calls. */
+export interface MachinesEndpoint {
+  method: "GET" | "POST" | "PUT" | "DELETE";
+  /** Path template under the flaps base, e.g. `/v1/apps/{app}/machines/{id}`. */
+  path: string;
+  /** The applier operation that calls it. */
+  op: string;
+}
+
+/**
+ * The flaps endpoints ./fly-apply.ts depends on. Keep in sync with the applier —
+ * the unit test asserts every path segment appears in fly-apply.ts.
+ */
+export const MACHINES_CONTRACT: readonly MachinesEndpoint[] = [
+  // Apps
+  { method: "POST", path: "/v1/apps", op: "createApp" },
+  { method: "GET", path: "/v1/apps/{app}", op: "getApp" },
+  { method: "DELETE", path: "/v1/apps/{app}", op: "deleteApp" },
+  // Machines
+  { method: "GET", path: "/v1/apps/{app}/machines", op: "listMachines" },
+  { method: "POST", path: "/v1/apps/{app}/machines", op: "createMachine" },
+  { method: "POST", path: "/v1/apps/{app}/machines/{id}", op: "updateMachine" },
+  { method: "DELETE", path: "/v1/apps/{app}/machines/{id}", op: "destroyMachine" },
+  { method: "GET", path: "/v1/apps/{app}/machines/{id}/wait", op: "waitForMachine" },
+  // Leases
+  { method: "POST", path: "/v1/apps/{app}/machines/{id}/lease", op: "acquireLease" },
+  { method: "DELETE", path: "/v1/apps/{app}/machines/{id}/lease", op: "releaseLease" },
+  // Volumes
+  { method: "GET", path: "/v1/apps/{app}/volumes", op: "listVolumes" },
+  { method: "POST", path: "/v1/apps/{app}/volumes", op: "createVolume" },
+  { method: "DELETE", path: "/v1/apps/{app}/volumes/{id}", op: "deleteVolume" },
+  // IP assignments
+  { method: "GET", path: "/v1/apps/{app}/ip_assignments", op: "listIps" },
+  { method: "POST", path: "/v1/apps/{app}/ip_assignments", op: "allocateIp" },
+  { method: "DELETE", path: "/v1/apps/{app}/ip_assignments/{ip}", op: "releaseIp" },
+  // Certificates
+  { method: "GET", path: "/v1/apps/{app}/certificates", op: "listCerts" },
+  { method: "POST", path: "/v1/apps/{app}/certificates", op: "addCert" },
+  { method: "DELETE", path: "/v1/apps/{app}/certificates/{hostname}", op: "deleteCert" },
+  // Secrets
+  { method: "GET", path: "/v1/apps/{app}/secrets", op: "listSecrets" },
+  { method: "POST", path: "/v1/apps/{app}/secrets/{name}", op: "setSecret" },
+  { method: "DELETE", path: "/v1/apps/{app}/secrets/{name}", op: "deleteSecret" },
+] as const;
+
+/** Normalize a `METHOD path` key: collapse every `{param}` to `{}` so param names match. */
+export function normalizeEndpoint(method: string, path: string): string {
+  return `${method.toUpperCase()} ${path.replace(/\{[^}]+\}/g, "{}")}`;
+}
+
+/** The contract as a set of normalized `METHOD path` keys. */
+export function contractKeys(): Set<string> {
+  return new Set(MACHINES_CONTRACT.map((e) => normalizeEndpoint(e.method, e.path)));
+}

package/src/op/activities/sprites-contract.docker.integration.test.ts

@@ -0,0 +1,74 @@
+import { describe, test, expect, beforeAll, afterAll } from "vitest";
+import { spritesUp, spritesDown } from "./sprites-emulator";
+import { SPRITES_CONTRACT, normalizeEndpoint, contractKeys } from "./sprites-contract";
+
+// Fidelity check (#808 T3): every endpoint the fly sprite activities depend on
+// (SPRITES_CONTRACT) must be served by the pinned spritzer image. Sprites has no
+// OpenAPI to diff, so spritzer's `/_spritzer/health` implemented-paths list is
+// the machine-readable oracle. If an activity ever calls something the emulator
+// doesn't model, this fails instead of the tests silently passing against a
+// partial fake. Docker required; skipped in CI unless SPRITES_DOCKER=1 (GitHub
+// runners have Docker, so relying on absence would pull the image every run).
+
+const CONTAINER = "chant-spritzer-contract-it";
+const PORT = 4293;
+
+let available = false;
+let endpoint = "";
+
+/** Parse a spritzer health `implemented` entry ("METHOD path (note)") to a normalized key. */
+function normalizeImplemented(entry: string): string {
+  const stripped = entry.replace(/\s*\(.*\)\s*$/, "").trim();
+  const sp = stripped.indexOf(" ");
+  const method = stripped.slice(0, sp);
+  const path = stripped.slice(sp + 1);
+  return normalizeEndpoint(method, path);
+}
+
+beforeAll(async () => {
+  if (process.env.CI && !process.env.SPRITES_DOCKER) {
+    available = false;
+    return;
+  }
+  try {
+    const up = await spritesUp({ name: CONTAINER, port: PORT, timeoutMs: 30_000 });
+    endpoint = up.endpoint;
+    available = true;
+  } catch {
+    available = false;
+  }
+}, 60_000);
+
+afterAll(async () => {
+  if (available) await spritesDown({ name: CONTAINER });
+});
+
+describe("Sprites contract ⊆ spritzer implemented paths (#808 T3)", () => {
+  test("the pinned spritzer serves every endpoint the fly activities depend on", async (ctx) => {
+    if (!available) ctx.skip();
+
+    const res = await fetch(`${endpoint}/_spritzer/health`);
+    expect(res.ok).toBe(true);
+    const health = (await res.json()) as { implemented?: string[] };
+    expect(Array.isArray(health.implemented)).toBe(true);
+
+    const served = new Set((health.implemented ?? []).map(normalizeImplemented));
+
+    const missing = [...contractKeys()].filter((k) => !served.has(k));
+    // A non-empty list means an activity calls something spritzer can't serve —
+    // a real fidelity gap between the contract and the pinned emulator.
+    expect(missing, `spritzer is missing contract endpoints: ${missing.join(", ")}`).toEqual([]);
+  });
+
+  test("each contract endpoint maps to a served path (per-activity report)", async (ctx) => {
+    if (!available) ctx.skip();
+    const res = await fetch(`${endpoint}/_spritzer/health`);
+    const health = (await res.json()) as { implemented?: string[] };
+    const served = new Set((health.implemented ?? []).map(normalizeImplemented));
+
+    for (const e of SPRITES_CONTRACT) {
+      const key = normalizeEndpoint(e.method, e.path);
+      expect(served.has(key), `${e.activity} → ${e.method} ${e.path} not served by spritzer`).toBe(true);
+    }
+  });
+});

package/src/op/activities/sprites-contract.test.ts

@@ -0,0 +1,60 @@
+import { describe, test, expect } from "vitest";
+import { readFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { dirname, join } from "node:path";
+import { SPRITES_CONTRACT, normalizeEndpoint, contractKeys } from "./sprites-contract";
+
+describe("SPRITES_CONTRACT", () => {
+  test("covers every sprite activity that calls the Sprites API", () => {
+    const activities = new Set(SPRITES_CONTRACT.map((e) => e.activity));
+    // The six ./sprites.ts activities that make an HTTP/WS call.
+    expect(activities).toEqual(
+      new Set([
+        "spriteCreate",
+        "spriteExec",
+        "spriteCheckpoint",
+        "listCheckpoints",
+        "spriteRestore",
+        "spriteDestroy",
+      ]),
+    );
+  });
+
+  test("every entry has a v1 path and a known method", () => {
+    for (const e of SPRITES_CONTRACT) {
+      expect(e.path.startsWith("/v1/sprites")).toBe(true);
+      expect(["GET", "POST", "DELETE", "WS"]).toContain(e.method);
+    }
+  });
+
+  test("normalizeEndpoint collapses param names and maps WS→GET", () => {
+    // {cp} and {cid} must compare equal (spritzer spells it {cid}).
+    expect(normalizeEndpoint("POST", "/v1/sprites/{id}/checkpoints/{cp}/restore")).toBe(
+      normalizeEndpoint("POST", "/v1/sprites/{id}/checkpoints/{cid}/restore"),
+    );
+    // The exec WebSocket is registered as a GET on the emulator.
+    expect(normalizeEndpoint("WS", "/v1/sprites/{id}/exec")).toBe("GET /v1/sprites/{}/exec");
+  });
+
+  test("contractKeys is the deduped normalized set", () => {
+    const keys = contractKeys();
+    expect(keys.has("POST /v1/sprites")).toBe(true);
+    expect(keys.has("DELETE /v1/sprites/{}")).toBe(true);
+    expect(keys.size).toBe(SPRITES_CONTRACT.length);
+  });
+
+  test("every contract path segment appears in the sprites.ts source (drift anchor)", () => {
+    // Anchors the hand-authored contract to the activity implementations: if an
+    // activity's endpoint path changes, a segment goes missing here and the
+    // contract must be updated in the same change.
+    const src = readFileSync(join(dirname(fileURLToPath(import.meta.url)), "sprites.ts"), "utf-8");
+    const segments = new Set(
+      SPRITES_CONTRACT.flatMap((e) =>
+        e.path.split("/").filter((s) => s.length > 0 && !s.startsWith("{")),
+      ),
+    );
+    for (const seg of segments) {
+      expect(src, `path segment "${seg}" from the contract is absent from sprites.ts`).toContain(seg);
+    }
+  });
+});

package/src/op/activities/sprites-contract.ts

@@ -0,0 +1,61 @@
+/**
+ * Hand-authored Fly Sprites API contract (#808 T3).
+ *
+ * The Fly Machines API ships a machine-readable OpenAPI (docs.machines.dev) that
+ * the fly resource surface generates + drift-checks against. The Sprites API
+ * (api.sprites.dev) ships no such spec at any conventional path, so there is
+ * nothing to diff automatically. This module is the manual stand-in: the exact
+ * endpoint set the fly sprite activities (./sprites.ts) depend on, maintained by
+ * hand from https://docs.sprites.dev.
+ *
+ * It anchors two fidelity checks:
+ *   1. Coverage — every endpoint here must be served by the pinned spritzer
+ *      emulator (its `/_spritzer/health` enumerates implemented paths). If an
+ *      activity ever calls something spritzer doesn't model, the docker-gated
+ *      contract test fails instead of silently passing against a partial fake.
+ *   2. Drift anchor — when the Sprites API changes, a human updates this file;
+ *      reviewers see exactly which activity/endpoint moved.
+ *
+ * Path params are written with names matching ./sprites.ts (`{id}`, `{cp}`);
+ * the coverage check normalizes param names before comparing, since spritzer
+ * spells the checkpoint id `{cid}`.
+ */
+
+/** One endpoint the fly sprite activities call. */
+export interface SpritesEndpoint {
+  /** HTTP method, or "WS" for the control-WebSocket exec channel. */
+  method: "GET" | "POST" | "DELETE" | "WS";
+  /** Path template under the Sprites base, e.g. `/v1/sprites/{id}/checkpoint`. */
+  path: string;
+  /** The fly activity that calls it (./sprites.ts export). */
+  activity: string;
+}
+
+/**
+ * The Sprites endpoints ./sprites.ts depends on. Keep in sync with the activity
+ * implementations — the unit test asserts every sprite activity is represented.
+ */
+export const SPRITES_CONTRACT: readonly SpritesEndpoint[] = [
+  { method: "POST", path: "/v1/sprites", activity: "spriteCreate" },
+  { method: "WS", path: "/v1/sprites/{id}/exec", activity: "spriteExec" },
+  { method: "POST", path: "/v1/sprites/{id}/checkpoint", activity: "spriteCheckpoint" },
+  { method: "GET", path: "/v1/sprites/{id}/checkpoints", activity: "listCheckpoints" },
+  { method: "POST", path: "/v1/sprites/{id}/checkpoints/{cp}/restore", activity: "spriteRestore" },
+  { method: "DELETE", path: "/v1/sprites/{id}", activity: "spriteDestroy" },
+] as const;
+
+/**
+ * Normalize a `METHOD path` key for comparison across sources: collapse every
+ * `{param}` to `{}` (so `{cp}` and `{cid}` match) and treat the WebSocket exec
+ * channel as a `GET` (spritzer registers it as `GET .../exec`).
+ */
+export function normalizeEndpoint(method: string, path: string): string {
+  const m = method === "WS" ? "GET" : method.toUpperCase();
+  const p = path.replace(/\{[^}]+\}/g, "{}");
+  return `${m} ${p}`;
+}
+
+/** The contract as a set of normalized `METHOD path` keys. */
+export function contractKeys(): Set<string> {
+  return new Set(SPRITES_CONTRACT.map((e) => normalizeEndpoint(e.method, e.path)));
+}

package/src/op/activities/sprites-emulator.ts

@@ -0,0 +1,46 @@
+import { emulatorLifecycle } from "@intentius/chant/op";
+import { SPRITZER_IMAGE } from "./emulator-images";
+
+export interface SpritesUpArgs {
+  /** Container name. Default: `chant-spritzer`. */
+  name?: string;
+  /** Host port mapped to the emulator's `:4290`. Default: `4290`. */
+  port?: number;
+  /** Image. Default: the pinned spritzer image ({@link SPRITZER_IMAGE}). */
+  image?: string;
+  /** Readiness timeout in ms. Default: `60000`. */
+  timeoutMs?: number;
+  /** Health poll interval in ms. Default: `2000`. */
+  intervalMs?: number;
+}
+
+export interface SpritesDownArgs {
+  /** Container name to remove. Default: `chant-spritzer`. */
+  name?: string;
+}
+
+// spritzer is a stateful fake of the Fly Sprites API — a plain 200 on its health
+// endpoint means ready. The local target for the sprite activities; point them
+// there with SPRITES_BASE_URL. Shared lifecycle: emulatorLifecycle (the same
+// helper that boots mudflaps for fly).
+const spritzer = emulatorLifecycle({
+  name: "chant-spritzer",
+  image: SPRITZER_IMAGE,
+  containerPort: 4290,
+  healthPath: "/_spritzer/health",
+});
+
+export const spritesExistsCommand = spritzer.existsCommand;
+export const spritesRmCommand = spritzer.rmCommand;
+export const spritesHealthUrl = spritzer.healthUrl;
+/** The Sprites endpoint URL (what the sprite activities' `SPRITES_BASE_URL`/`endpoint` points at). */
+export const spritesEndpoint = spritzer.endpoint;
+export const spritesRunCommand = (args: SpritesUpArgs = {}): string => spritzer.runCommand(args);
+
+/** Boot a local spritzer (Fly Sprites API emulator) in Docker and return its endpoint. */
+export const spritesUp = (args: SpritesUpArgs = {}, signal?: AbortSignal): Promise<{ endpoint: string }> =>
+  spritzer.up(args, signal);
+
+/** Stop and remove the local spritzer container (no-op if already gone). */
+export const spritesDown = (args: SpritesDownArgs = {}, signal?: AbortSignal): Promise<void> =>
+  spritzer.down(args, signal);