@intentius/chant-lexicon-fly 0.16.0 → 0.18.0

package/dist/reference-catalog.d.ts

@@ -0,0 +1,21 @@
+import type { ReferenceCatalog } from "@intentius/chant/lexicon";
+/**
+ * Fly reference catalog (#804) — how observed Fly resources reference each other,
+ * so `chant graph --live` reconstructs the topology and draws the App as a
+ * boundary box (the reference resolver, chant#778; containment, chant#779).
+ *
+ * Fly's relationships are app-centric and simple. `describeResources`
+ * (./describe-resources.ts) already returns the rich per-resource shape — each
+ * app-scoped resource carries its owning `app`, and a machine carries its full
+ * `config` (with `mounts`) — so, unlike AWS (chant#784), Fly needs **no**
+ * `enrichLiveAttrs`: the references are already in the observed attributes.
+ *
+ * Keyed to the `describeResources` attribute shape:
+ *   - App        → `{ app }`           (physicalId = app name)
+ *   - Machine    → `{ app, config }`   (config.mounts[].volume references a Volume)
+ *   - Volume     → `{ app, volumeName }`
+ *   - IPAddress  → `{ app, ... }`
+ *   - Certificate→ `{ app, ... }`
+ */
+export declare const flyReferenceCatalog: ReferenceCatalog;
+//# sourceMappingURL=reference-catalog.d.ts.map

package/dist/reference-catalog.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"reference-catalog.d.ts","sourceRoot":"","sources":["../src/reference-catalog.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,0BAA0B,CAAC;AAEjE;;;;;;;;;;;;;;;;;GAiBG;AACH,eAAO,MAAM,mBAAmB,EAAE,gBAkBjC,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@intentius/chant-lexicon-fly",
-  "version": "0.16.0",
+  "version": "0.18.0",
   "type": "module",
   "files": [
     "src/",
@@ -47,13 +47,17 @@
     "prepack": "npm run generate && npm run bundle && npm run validate && npm run build",
     "build": "tsc -p tsconfig.build.json && tsc-alias -p tsconfig.build.json && find dist -type f \\( -name \"*.js\" -o -name \"*.js.map\" \\) -delete"
   },
+  "dependencies": {
+    "ws": "^8.18.0"
+  },
   "devDependencies": {
     "@intentius/chant": "*",
+    "@types/ws": "^8.5.12",
     "tsc-alias": "^1.8.17",
     "typescript": "^5.9.3"
   },
   "peerDependencies": {
-    "@intentius/chant": "^0.16.0"
+    "@intentius/chant": "^0.18.0"
   },
   "description": "Google Cloud lexicon for chant — declarative IaC in TypeScript",
   "license": "Apache-2.0",

package/src/composites/fly-deploy.ts

@@ -36,7 +36,7 @@ export interface FlapsStepOpts {
   name?: string;
   /** Host port mapped to the emulator's `:4280`. Default: `4280`. */
   port?: number;
-  /** Image. Default: `ghcr.io/intentius/mudflaps:0.3.0`. */
+  /** Image. Default: the pinned mudflaps image (`MUDFLAPS_IMAGE`, from the flapsUp activity). */
   image?: string;
   /** Readiness timeout in ms. */
   timeoutMs?: number;

package/src/coverage.ts

@@ -0,0 +1,49 @@
+/**
+ * Coverage analysis for the fly lexicon (#804) — how much of the generated
+ * Machines API surface the lexicon's typed resources cover. Thin wrapper over
+ * the shared `computeCoverage`, mirroring the docker/gcp/github peers.
+ */
+
+import { existsSync, readFileSync } from "fs";
+import { join, dirname } from "path";
+import { fileURLToPath } from "url";
+import {
+  computeCoverage,
+  overallPct,
+  formatSummary,
+  formatVerbose,
+  checkThresholds,
+  type CoverageReport,
+  type CoverageThresholds,
+} from "@intentius/chant/codegen/coverage";
+
+export type { CoverageReport, CoverageThresholds };
+export { computeCoverage, overallPct, formatSummary, formatVerbose, checkThresholds };
+
+/** Run coverage analysis for the fly lexicon. */
+export async function analyzeFlyCoverage(opts?: {
+  basePath?: string;
+  verbose?: boolean;
+  minOverall?: number;
+}): Promise<CoverageReport> {
+  const basePath = opts?.basePath ?? dirname(dirname(fileURLToPath(import.meta.url)));
+  const lexiconPath = join(basePath, "src", "generated", "lexicon-fly.json");
+
+  if (!existsSync(lexiconPath)) {
+    throw new Error(`Generated lexicon not found at ${lexiconPath}. Run "chant dev generate" first.`);
+  }
+
+  const report = computeCoverage(readFileSync(lexiconPath, "utf-8"));
+
+  console.error(opts?.verbose ? formatVerbose(report) : formatSummary(report));
+
+  if (typeof opts?.minOverall === "number") {
+    const result = checkThresholds(report, { minOverallPct: opts.minOverall });
+    if (!result.ok) {
+      for (const v of result.violations) console.error(`  FAIL: ${v}`);
+      throw new Error("Coverage below threshold");
+    }
+  }
+
+  return report;
+}

package/src/emulator-freshness-cli.ts

@@ -0,0 +1,49 @@
+/**
+ * CLI for the emulator-freshness check (#808 T2). Fetches the latest mudflaps /
+ * spritzer releases, compares to the pinned tags, prints a report, and — when
+ * run in CI — writes `behind` + a Markdown `body` to `$GITHUB_OUTPUT` so the
+ * weekly workflow can open/refresh a single "N releases behind" notice issue.
+ *
+ * Advisory only: exits 0 whether or not a pin is behind (the bump is a human
+ * decision per the #808 policy). A hard failure (network/API) exits 1.
+ */
+
+import { appendFileSync } from "node:fs";
+import { checkFreshness, formatResult, type FreshnessResult } from "./emulator-freshness";
+
+function issueBody(behind: FreshnessResult[]): string {
+  const rows = behind.map((r) => `- **${r.name}** — pinned \`${r.pinned}\`, latest \`${r.latest}\``).join("\n");
+  return [
+    "The pinned Fly emulator image(s) are behind their latest upstream release:",
+    "",
+    rows,
+    "",
+    "The tag lives in `lexicons/fly/src/op/activities/emulator-images.ts` (single source).",
+    "",
+    "Per the #808 bump policy this is **advisory** — move the pin only when a consuming",
+    "test needs the newer emulator (a fidelity fix the fly activities exercise), not on",
+    "every release. Close this issue once reviewed or bumped.",
+  ].join("\n");
+}
+
+async function main(): Promise<void> {
+  const results = await checkFreshness();
+  for (const r of results) console.error(formatResult(r));
+
+  const behind = results.filter((r) => r.behind);
+  console.log(JSON.stringify({ behind: behind.length > 0, results }, null, 2));
+
+  const out = process.env.GITHUB_OUTPUT;
+  if (out) {
+    appendFileSync(out, `behind=${behind.length > 0}\n`);
+    if (behind.length > 0) {
+      // Multiline output via the GITHUB_OUTPUT heredoc form.
+      appendFileSync(out, `body<<FRESHNESS_EOF\n${issueBody(behind)}\nFRESHNESS_EOF\n`);
+    }
+  }
+}
+
+main().catch((err: unknown) => {
+  console.error(err instanceof Error ? err.message : String(err));
+  process.exit(1);
+});

package/src/emulator-freshness.test.ts

@@ -0,0 +1,86 @@
+import { describe, test, expect } from "vitest";
+import {
+  parseVersion,
+  compare,
+  latestRelease,
+  checkFreshness,
+  formatResult,
+  EMULATOR_PINS,
+} from "./emulator-freshness";
+
+describe("parseVersion", () => {
+  test("extracts the version from a ghcr image ref, stripping a leading v", () => {
+    expect(parseVersion("ghcr.io/intentius/mudflaps:0.3.1")).toBe("0.3.1");
+    expect(parseVersion("ghcr.io/intentius/spritzer:v1.2.0")).toBe("1.2.0");
+  });
+});
+
+describe("compare", () => {
+  test("not behind when pinned equals latest", () => {
+    expect(compare("mudflaps", "0.3.1", "v0.3.1").behind).toBe(false);
+  });
+  test("behind when latest is a newer patch/minor/major", () => {
+    expect(compare("m", "0.3.1", "v0.3.2").behind).toBe(true);
+    expect(compare("m", "0.3.1", "v0.4.0").behind).toBe(true);
+    expect(compare("m", "0.3.1", "v1.0.0").behind).toBe(true);
+  });
+  test("not behind when pinned is ahead of latest", () => {
+    expect(compare("m", "0.4.0", "v0.3.9").behind).toBe(false);
+  });
+  test("normalizes the leading v out of the reported versions", () => {
+    const r = compare("m", "0.3.1", "v0.3.2");
+    expect(r.pinned).toBe("0.3.1");
+    expect(r.latest).toBe("0.3.2");
+  });
+});
+
+describe("EMULATOR_PINS", () => {
+  test("tracks mudflaps and spritzer from the single-source image constants", () => {
+    expect(EMULATOR_PINS.map((p) => p.name).sort()).toEqual(["mudflaps", "spritzer"]);
+    for (const p of EMULATOR_PINS) {
+      expect(p.repo).toMatch(/^intentius\//);
+      expect(p.pinned).toMatch(/^\d+\.\d+\.\d+$/);
+    }
+  });
+});
+
+describe("latestRelease + checkFreshness (mocked fetch)", () => {
+  const mkFetch = (tags: Record<string, string>): typeof fetch =>
+    (async (url: string | URL | Request) => {
+      const u = String(url);
+      const repo = u.match(/repos\/([^/]+\/[^/]+)\/releases/)?.[1] ?? "";
+      return { ok: true, status: 200, json: async () => ({ tag_name: tags[repo] }) } as Response;
+    }) as unknown as typeof fetch;
+
+  test("latestRelease returns the tag_name", async () => {
+    const f = mkFetch({ "intentius/mudflaps": "v0.9.0" });
+    expect(await latestRelease("intentius/mudflaps", f)).toBe("v0.9.0");
+  });
+
+  test("checkFreshness flags a pin behind its latest release", async () => {
+    // Force both upstreams to a high version so the check reports behind
+    // regardless of the currently-pinned tag.
+    const f = mkFetch({ "intentius/mudflaps": "v99.0.0", "intentius/spritzer": "v99.0.0" });
+    const results = await checkFreshness(f);
+    expect(results).toHaveLength(2);
+    expect(results.every((r) => r.behind)).toBe(true);
+  });
+
+  test("checkFreshness reports current when latest matches the pin", async () => {
+    const pins = Object.fromEntries(EMULATOR_PINS.map((p) => [p.repo, `v${p.pinned}`]));
+    const results = await checkFreshness(mkFetch(pins));
+    expect(results.every((r) => !r.behind)).toBe(true);
+  });
+
+  test("latestRelease throws on a non-ok response", async () => {
+    const f = (async () => ({ ok: false, status: 404 }) as Response) as unknown as typeof fetch;
+    await expect(latestRelease("intentius/nope", f)).rejects.toThrow(/HTTP 404/);
+  });
+});
+
+describe("formatResult", () => {
+  test("marks behind vs current distinctly", () => {
+    expect(formatResult({ name: "m", pinned: "0.3.1", latest: "0.4.0", behind: true })).toMatch(/behind/);
+    expect(formatResult({ name: "m", pinned: "0.3.1", latest: "0.3.1", behind: false })).toMatch(/current/);
+  });
+});

package/src/emulator-freshness.ts

@@ -0,0 +1,87 @@
+/**
+ * Emulator-freshness check (#808 T2, second half).
+ *
+ * mudflaps (Machines) and spritzer (Sprites) are pinned to a single source
+ * (./op/activities/emulator-images.ts). Their upstream repos cut GitHub releases,
+ * so this compares each pinned tag against the latest release and reports how far
+ * behind it is. A weekly workflow surfaces a "N releases behind" notice — never
+ * an auto-bump. Per the bump policy (#808), the tag moves only when a consuming
+ * test needs the newer emulator, so this is advisory, not gating on the pin.
+ */
+
+import { MUDFLAPS_IMAGE, SPRITZER_IMAGE } from "./op/activities/emulator-images";
+
+export interface EmulatorPin {
+  /** Short name, e.g. "mudflaps". */
+  name: string;
+  /** GitHub repo "owner/name" whose releases publish the emulator. */
+  repo: string;
+  /** Pinned version, no leading "v" (e.g. "0.3.1"). */
+  pinned: string;
+}
+
+export interface FreshnessResult {
+  name: string;
+  pinned: string;
+  latest: string;
+  /** True when the latest release is newer than the pinned version. */
+  behind: boolean;
+}
+
+/** Parse the version tag from a ghcr image ref (".../mudflaps:0.3.1" → "0.3.1"). */
+export function parseVersion(image: string): string {
+  const tag = image.slice(image.lastIndexOf(":") + 1);
+  return tag.replace(/^v/, "");
+}
+
+function toParts(v: string): number[] {
+  return v.replace(/^v/, "").split(".").map((n) => parseInt(n, 10) || 0);
+}
+
+/** Compare pinned vs latest as dotted numeric versions; `behind` when latest > pinned. */
+export function compare(name: string, pinned: string, latest: string): FreshnessResult {
+  const p = toParts(pinned);
+  const l = toParts(latest);
+  let behind = false;
+  for (let i = 0; i < Math.max(p.length, l.length); i++) {
+    const a = p[i] ?? 0;
+    const b = l[i] ?? 0;
+    if (b > a) {
+      behind = true;
+      break;
+    }
+    if (b < a) break;
+  }
+  return { name, pinned: pinned.replace(/^v/, ""), latest: latest.replace(/^v/, ""), behind };
+}
+
+/** The emulator pins to check, read from the single-source image constants. */
+export const EMULATOR_PINS: readonly EmulatorPin[] = [
+  { name: "mudflaps", repo: "intentius/mudflaps", pinned: parseVersion(MUDFLAPS_IMAGE) },
+  { name: "spritzer", repo: "intentius/spritzer", pinned: parseVersion(SPRITZER_IMAGE) },
+] as const;
+
+/** Fetch the latest release tag for a repo via the GitHub REST API. */
+export async function latestRelease(repo: string, fetchImpl: typeof fetch = fetch): Promise<string> {
+  const headers: Record<string, string> = { Accept: "application/vnd.github+json" };
+  if (process.env.GITHUB_TOKEN) headers.Authorization = `Bearer ${process.env.GITHUB_TOKEN}`;
+  const res = await fetchImpl(`https://api.github.com/repos/${repo}/releases/latest`, { headers });
+  if (!res.ok) throw new Error(`releases/latest ${repo}: HTTP ${res.status}`);
+  const body = (await res.json()) as { tag_name?: string };
+  if (!body.tag_name) throw new Error(`releases/latest ${repo}: no tag_name`);
+  return body.tag_name;
+}
+
+/** Check every emulator pin against its latest release. */
+export async function checkFreshness(fetchImpl: typeof fetch = fetch): Promise<FreshnessResult[]> {
+  return Promise.all(
+    EMULATOR_PINS.map(async (p) => compare(p.name, p.pinned, await latestRelease(p.repo, fetchImpl))),
+  );
+}
+
+/** One-line human summary of a result. */
+export function formatResult(r: FreshnessResult): string {
+  return r.behind
+    ? `⚠ ${r.name}: pinned ${r.pinned}, latest ${r.latest} — behind`
+    : `✓ ${r.name}: pinned ${r.pinned} is current (latest ${r.latest})`;
+}

package/src/index.ts

@@ -17,6 +17,21 @@ export { FLY_METADATA_OWNERSHIP_KEYS } from "./ownership";
 export { flyDeploy, flapsUp, flapsDown, flyApplyStep, LOCAL_FLAPS_ENDPOINT } from "./composites/fly-deploy";
 export type { FlyDeployOpts, FlyApplyStepOpts, FlapsStepOpts } from "./composites/fly-deploy";
 
+// Sprite Op step builders (re-exported from core for single-import convenience).
+// These author `activity("spriteCreate", ...)` steps; `loadActivities(["fly"])`
+// binds them to the implementations in ./op/activities/sprites.ts. The `spritesUp`
+// /`spritesDown` builders boot/tear down the spritzer emulator as modeled steps.
+export {
+  spriteCreate,
+  spriteExec,
+  spriteCheckpoint,
+  spriteRestore,
+  listCheckpoints,
+  spriteDestroy,
+  spritesUp,
+  spritesDown,
+} from "@intentius/chant/op";
+
 // Generated resources — export everything from generated index.
 // Provides `App`, `Machine`, `Volume`, and the property types
 // (`MachineConfig`, `MachineGuest`, `MachineService`, ...) for authoring.

package/src/mcp/context-tools.test.ts

@@ -0,0 +1,27 @@
+import { describe, it, expect } from "vitest";
+import { flyContextTools, imagePinned } from "./context-tools";
+
+describe("flyContextTools", () => {
+  const tools = flyContextTools();
+
+  it("exposes the read-only fly:* context tools", () => {
+    expect(tools.map((t) => t.name).sort()).toEqual(["fly:app", "fly:checks", "fly:plan", "fly:references"]);
+  });
+
+  it("every tool has a description, a path input, and a handler", () => {
+    for (const t of tools) {
+      expect(t.description.length).toBeGreaterThan(10);
+      expect(t.inputSchema.type).toBe("object");
+      expect(t.inputSchema.properties).toHaveProperty("path");
+      expect(typeof t.handler).toBe("function");
+    }
+  });
+});
+
+describe("imagePinned", () => {
+  it("is pinned only when the image names a digest", () => {
+    expect(imagePinned("flyio/hellofly@sha256:abc123")).toBe(true);
+    expect(imagePinned("flyio/hellofly:latest")).toBe(false);
+    expect(imagePinned("flyio/hellofly")).toBe(false);
+  });
+});

package/src/mcp/context-tools.ts

@@ -0,0 +1,120 @@
+/**
+ * Read-only MCP tools that expose what `chant build` already computes about a
+ * Fly deploy — its apps and machines, the flaps create bodies, image pinning,
+ * and the lexicon's findings — so an agent can ask about a change *before it
+ * runs* (#804).
+ *
+ * Every tool builds from source and returns data. None touch a live Fly org,
+ * read run history, or write anything — the same context-producer boundary the
+ * AWS/GitLab context tools hold.
+ */
+
+import { build, type BuildResult } from "@intentius/chant/build";
+import type { SerializerResult } from "@intentius/chant/serializer";
+import { runPostSynthChecks, getPrimaryOutput } from "@intentius/chant/lint/post-synth";
+import { postSynthChecks } from "../lint/post-synth";
+import type { McpToolContribution } from "@intentius/chant/mcp/types";
+import { flySerializer } from "../serializer";
+import { parsePlan, isAppRequest, isMachineRequest, type FlyPlan, type FlapsRequest } from "../op/activities/fly-apply";
+
+const PATH_INPUT = {
+  type: "object" as const,
+  properties: {
+    path: { type: "string", description: "Path to the chant project directory (default: current directory)" },
+  },
+};
+
+/** Build the project and parse the flaps plan the serializer emits. */
+async function buildFly(path: string): Promise<{ plan: FlyPlan; result: BuildResult; output?: string | SerializerResult }> {
+  const result = await build(path || ".", [flySerializer]);
+  const output = result.outputs.get("fly");
+  let plan: FlyPlan = {};
+  if (output) {
+    try {
+      plan = parsePlan(getPrimaryOutput(output));
+    } catch {
+      // not a parseable fly plan — leave empty
+    }
+  }
+  return { plan, result, output };
+}
+
+const machineImage = (req: FlapsRequest): string | undefined => {
+  const config = req.body.config as { image?: unknown } | undefined;
+  return typeof config?.image === "string" ? config.image : undefined;
+};
+
+/** A container image reference is pinned when it names a digest, not a tag. */
+export function imagePinned(image: string): boolean {
+  return image.includes("@sha256:");
+}
+
+export function flyContextTools(): McpToolContribution[] {
+  return [
+    {
+      name: "fly:app",
+      description:
+        "Build the project and summarize the declared Fly apps and machines — regions, images, guest sizing — from source. Read-only; never touches a live Fly org.",
+      inputSchema: PATH_INPUT,
+      async handler(params: Record<string, unknown>): Promise<unknown> {
+        const { plan } = await buildFly(String(params.path ?? "."));
+        const apps: Array<{ name: string; org_slug: unknown }> = [];
+        const machines: Array<{ name: string; region: unknown; image: string | null; guest: unknown }> = [];
+        for (const [name, req] of Object.entries(plan)) {
+          if (isAppRequest(req)) {
+            apps.push({ name: String(req.body.app_name ?? name), org_slug: req.body.org_slug ?? null });
+          } else if (isMachineRequest(req)) {
+            machines.push({
+              name: String(req.body.name ?? name),
+              region: req.body.region ?? null,
+              image: machineImage(req) ?? null,
+              guest: (req.body.config as { guest?: unknown } | undefined)?.guest ?? null,
+            });
+          }
+        }
+        return { apps, machines };
+      },
+    },
+    {
+      name: "fly:checks",
+      description:
+        "Build the project and return the fly lexicon's post-synth findings (machine requires an image, a mount references a declared Volume) as JSON. Read-only.",
+      inputSchema: PATH_INPUT,
+      async handler(params: Record<string, unknown>): Promise<unknown> {
+        const { output, result } = await buildFly(String(params.path ?? "."));
+        if (!output) return { findings: [], note: "no Fly plan produced from this project" };
+        const scoped: BuildResult = { ...result, outputs: new Map([["fly", output]]) };
+        const diags = runPostSynthChecks(postSynthChecks, scoped);
+        return {
+          findings: diags.map((d) => ({ id: d.checkId, severity: d.severity, entity: d.entity ?? null, message: d.message })),
+        };
+      },
+    },
+    {
+      name: "fly:references",
+      description:
+        "Build the project and list each machine's container image and whether it is pinned to a digest (vs a floating tag). Read-only.",
+      inputSchema: PATH_INPUT,
+      async handler(params: Record<string, unknown>): Promise<unknown> {
+        const { plan } = await buildFly(String(params.path ?? "."));
+        const images: Array<{ machine: string; image: string; pinned: boolean }> = [];
+        for (const [name, req] of Object.entries(plan)) {
+          if (!isMachineRequest(req)) continue;
+          const image = machineImage(req);
+          if (image) images.push({ machine: String(req.body.name ?? name), image, pinned: imagePinned(image) });
+        }
+        return images;
+      },
+    },
+    {
+      name: "fly:plan",
+      description:
+        "Build the project and return the flaps create bodies the serializer emits — exactly what flyApply would POST to the Machines API. Read-only.",
+      inputSchema: PATH_INPUT,
+      async handler(params: Record<string, unknown>): Promise<unknown> {
+        const { plan } = await buildFly(String(params.path ?? "."));
+        return plan;
+      },
+    },
+  ];
+}

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

@@ -0,0 +1,21 @@
+/**
+ * Single source of truth for the Fly emulator image pins (#808 T2).
+ *
+ * mudflaps (Machines API) and spritzer (Sprites API) are the local fakes fly's
+ * activities are exercised against. These tags were previously duplicated across
+ * flaps.ts, sprites-emulator.ts, the fly-deploy composite, and tests — and had
+ * already drifted (the composite's docstring said mudflaps 0.3.0 while the
+ * activity pinned 0.3.1). Pin each here so a bump touches one line and the
+ * emulator-freshness check (#808 T2) has a single target to compare against the
+ * latest GHCR release.
+ *
+ * Bump policy (#808): move these only when a consuming test needs a newer
+ * emulator (a fidelity fix the activities exercise), not on every emulator
+ * release. For new upstream API surface the emulator leads, then fly bumps here.
+ */
+
+/** Pinned mudflaps (Fly Machines / flaps emulator) image. */
+export const MUDFLAPS_IMAGE = "ghcr.io/intentius/mudflaps:0.4.0";
+
+/** Pinned spritzer (Fly Sprites emulator) image. */
+export const SPRITZER_IMAGE = "ghcr.io/intentius/spritzer:0.3.1";

package/src/op/activities/flaps.test.ts

@@ -6,11 +6,12 @@ import {
   flapsHealthUrl,
   flapsEndpoint,
 } from "./flaps";
+import { MUDFLAPS_IMAGE } from "./emulator-images";
 
 describe("flaps (mudflaps) lifecycle commands", () => {
   test("run command uses defaults and maps the port", () => {
     expect(flapsRunCommand({})).toBe(
-      "docker run -d --rm --name chant-mudflaps -p 4280:4280 ghcr.io/intentius/mudflaps:0.3.0",
+      `docker run -d --rm --name chant-mudflaps -p 4280:4280 ${MUDFLAPS_IMAGE}`,
     );
   });
 

package/src/op/activities/flaps.ts

@@ -1,11 +1,12 @@
 import { emulatorLifecycle } from "@intentius/chant/op";
+import { MUDFLAPS_IMAGE } from "./emulator-images";
 
 export interface FlapsUpArgs {
   /** 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. Default: the pinned mudflaps image ({@link MUDFLAPS_IMAGE}). */
   image?: string;
   /** Readiness timeout in ms. Default: `60000`. */
   timeoutMs?: number;
@@ -23,7 +24,7 @@ export interface FlapsDownArgs {
 // with FLY_FLAPS_BASE_URL. Shared lifecycle: emulatorLifecycle (#746).
 const flaps = emulatorLifecycle({
   name: "chant-mudflaps",
-  image: "ghcr.io/intentius/mudflaps:0.3.0",
+  image: MUDFLAPS_IMAGE,
   containerPort: 4280,
   healthPath: "/_mudflaps/health",
 });

package/src/op/activities/index.ts

@@ -46,3 +46,56 @@ export {
   flapsEndpoint,
 } from "./flaps";
 export type { FlapsUpArgs, FlapsDownArgs } from "./flaps";
+
+// Sprites (sprites.dev) — the other Fly product: imperative, checkpointable
+// sandbox activities. `loadActivities(["fly"])` provides these; the fake lives
+// in `sprites-fake.ts` and is imported only by tests (not an activity). Unlike
+// Machines, Sprites have no desired state to reconcile — they are runtime
+// primitives driven inside an Op, with checkpoint-as-compensation as the
+// headline capability.
+export {
+  spriteCreate,
+  spriteExec,
+  spriteCheckpoint,
+  spriteRestore,
+  listCheckpoints,
+  spriteDestroy,
+  resolveSpritesEndpoint,
+  defaultSpritesHttp,
+  spriteCreateBody,
+  parseCreateResponse,
+  accumulateExecFrames,
+  parseCheckpointNdjson,
+  pickCheckpointByComment,
+  splitCommand,
+  spriteExecWsUrl,
+  DEFAULT_SPRITES_BASE_URL,
+} from "./sprites";
+export type {
+  SpritesHttp,
+  SpriteCreateArgs,
+  SpriteCreateResult,
+  SpriteExecArgs,
+  SpriteExecResult,
+  SpriteCheckpointArgs,
+  SpriteCheckpointResult,
+  SpriteRestoreArgs,
+  ListCheckpointsArgs,
+  Checkpoint,
+  SpriteDestroyArgs,
+} from "./sprites";
+
+// spritzer (the Sprites API emulator) Docker lifecycle — the twin of mudflaps
+// above. `spritesUp`/`spritesDown` resolve by name so an Op can boot/tear down
+// the emulator as a modeled step; the sprite activities target it via
+// SPRITES_BASE_URL.
+export {
+  spritesUp,
+  spritesDown,
+  spritesRunCommand,
+  spritesRmCommand,
+  spritesExistsCommand,
+  spritesHealthUrl,
+  spritesEndpoint,
+} from "./sprites-emulator";
+export type { SpritesUpArgs, SpritesDownArgs } from "./sprites-emulator";