@intentius/chant-lexicon-fly 0.124.31 → 0.124.33

package/dist/composites/fly-deploy.js

@@ -0,0 +1,91 @@
+/**
+ * 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";
+/** The local mudflaps endpoint the deploy Op targets by default. */
+export const LOCAL_FLAPS_ENDPOINT = "http://localhost:4280";
+/**
+ * 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) => {
+    const { profile, ...args } = opts ?? {};
+    return activity("flapsUp", args, 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) => {
+    const { profile, ...args } = opts ?? {};
+    return activity("flapsDown", args, profile ?? "fastIdempotent");
+};
+/**
+ * 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, opts) => {
+    const { profile, ...rest } = opts ?? {};
+    return activity("flyApply", { planPath, ...rest }, profile ?? "longInfra");
+};
+/**
+ * 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 = {}) {
+    const path = opts.path ?? ".";
+    const planPath = opts.planPath ?? "dist/fly.json";
+    const endpoint = opts.endpoint === undefined ? LOCAL_FLAPS_ENDPOINT : opts.endpoint;
+    const applyOpts = {
+        ...(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",
+        phases,
+    });
+}

package/dist/composites/fly-otel-collector.js

@@ -0,0 +1,66 @@
+/**
+ * FlyOtelCollector composite: an OpenTelemetry Collector on a Fly Machine.
+ *
+ * The collector config is declared with the otel lexicon
+ * (`@intentius/chant-lexicon-otel`), rendered with `collectorYaml`, and
+ * written into the machine as a file (`files[].raw_value`, base64). Other
+ * machines in the organization reach it over the private network at
+ * `<app>.internal` on the receiver ports. When the config serves a
+ * `health_check` endpoint, the machine gets an HTTP check on it.
+ */
+import { Composite, mergeDefaults } from "@intentius/chant";
+import { buildCollectorConfig, collectorEndpoints, collectorYaml, otlpCollector, COLLECTOR_CONFIG_PATH, COLLECTOR_IMAGE, } from "@intentius/chant-lexicon-otel";
+import { Fly } from "../pseudo.js";
+import { Machine, MachineConfig, MachineGuest, MachineInit, MachineCheck, MachineRestart, File } from "../generated/index.js";
+/** Base64 of a UTF-8 string, the encoding flaps expects in `raw_value`. */
+function base64(text) {
+    return Buffer.from(text, "utf8").toString("base64");
+}
+/**
+ * Create a FlyOtelCollector composite. Returns one Machine.
+ *
+ * @example
+ * ```ts
+ * import { App } from "@intentius/chant-lexicon-fly";
+ * import { FlyOtelCollector } from "@intentius/chant-lexicon-fly";
+ * import { OtlpHttpExporter } from "@intentius/chant-lexicon-otel";
+ *
+ * export const app = new App({ name: "otel" });
+ * export const collector = FlyOtelCollector({
+ *   exporters: [new OtlpHttpExporter({ endpoint: "https://otlp.example.com" })],
+ * });
+ * ```
+ */
+export const FlyOtelCollector = Composite((props) => {
+    const { name = "otel-collector", image = COLLECTOR_IMAGE, cpuKind = "shared", cpus = 1, memoryMb = 512, defaults: defs, } = props;
+    const entities = props.config ? [...props.config] : otlpCollector({ exporters: props.exporters, signals: props.signals });
+    const { healthCheck } = collectorEndpoints(buildCollectorConfig(entities).config);
+    const config = new MachineConfig({
+        image,
+        init: new MachineInit({ cmd: [`--config=${COLLECTOR_CONFIG_PATH}`] }),
+        files: [new File({ guest_path: COLLECTOR_CONFIG_PATH, raw_value: base64(collectorYaml(entities)) })],
+        guest: new MachineGuest({ cpu_kind: cpuKind, cpus, memory_mb: memoryMb }),
+        restart: new MachineRestart({ policy: "always" }),
+        ...(healthCheck
+            ? {
+                checks: {
+                    health: new MachineCheck({
+                        type: "http",
+                        port: healthCheck.port,
+                        path: healthCheck.path,
+                        interval: "15s",
+                        timeout: "5s",
+                        grace_period: "10s",
+                    }),
+                },
+            }
+            : {}),
+    });
+    const machine = new Machine(mergeDefaults({
+        name,
+        region: props.region ?? Fly.Region,
+        ...(props.app !== undefined ? { app: props.app } : {}),
+        config,
+    }, defs?.machine));
+    return { machine };
+}, "FlyOtelCollector");

package/dist/composites/fly-site.js

@@ -0,0 +1,80 @@
+/**
+ * FlySite composite: a Fly app that serves one app's releases.
+ *
+ * It declares the App, the Machine that serves (behind Fly's proxy on 443 and
+ * 80), and, when asked for, a Volume the app's data lives on, mounted into the
+ * Machine, a public IP, and the app's Secrets. It is the fly lexicon's home
+ * for chud's `FlySite` and `ChudLocalSite` sites (ws-056, #2809): a repo that
+ * `chant workspace upgrade` takes off the chud lexicon declares its Fly site
+ * with it, so `chant workspace graph --composites` lists the site as a
+ * composite instance, and a component that names `FlySite` in its
+ * `composites` deploys it.
+ *
+ * The Machine is the one a release ships to: `chant build --lexicon fly`
+ * serializes the site into a plan with exactly one Machine, so the
+ * `fly-release` steps (a component's deploy, or an Op's `flyRelease`) find it
+ * without being told its name. `image` is what the Machine runs until a
+ * release puts its own image, or its files and start command, on it.
+ */
+import { Composite, mergeDefaults } from "@intentius/chant";
+import { Fly } from "../pseudo.js";
+import { App, IPAddress, Machine, MachineConfig, MachineGuest, MachineMount, MachinePort, MachineService, Secret, Volume, } from "../generated/index.js";
+/** `APP_SECRET` -> `appSecret`: a Secret's member name, never one of the other members'. */
+function memberName(secret) {
+    const words = secret.toLowerCase().split(/[^a-z0-9]+/).filter(Boolean);
+    const name = words.map((w, i) => (i === 0 ? w : w[0].toUpperCase() + w.slice(1))).join("") || "secret";
+    return ["app", "machine", "volume", "ip"].includes(name) ? `${name}Secret` : name;
+}
+/**
+ * Create a FlySite composite. Returns the App and the Machine, and the
+ * Volume, IP and Secrets it was asked for.
+ *
+ * @example
+ * ```ts
+ * import { FlySite } from "@intentius/chant-lexicon-fly";
+ *
+ * export const flySite = FlySite({
+ *   app: "notes",
+ *   region: "iad",
+ *   image: "node:22-slim",
+ *   env: { PORT: "8080", APP_DATA: "/data" },
+ *   volume: { name: "data", sizeGb: 1, path: "/data" },
+ *   ip: "shared_v4",
+ *   secrets: { APP_SECRET: process.env.APP_SECRET || undefined },
+ * });
+ * ```
+ */
+export const FlySite = Composite((props) => {
+    const { port = 8080, cpuKind = "shared", cpus = 1, memoryMb = 256, defaults: defs } = props;
+    const region = props.region ?? Fly.Region;
+    const app = new App(mergeDefaults({ name: props.app, org_slug: props.org ?? Fly.OrgSlug }, defs?.app));
+    const volume = props.volume
+        ? new Volume(mergeDefaults({ name: props.volume.name, region, size_gb: props.volume.sizeGb }, defs?.volume))
+        : undefined;
+    const config = new MachineConfig({
+        image: props.image,
+        guest: new MachineGuest({ cpu_kind: cpuKind, cpus, memory_mb: memoryMb }),
+        ...(props.volume ? { mounts: [new MachineMount({ volume: props.volume.name, path: props.volume.path })] } : {}),
+        services: [
+            new MachineService({
+                protocol: "tcp",
+                internal_port: port,
+                ports: [new MachinePort({ port: 443, handlers: ["tls", "http"] }), new MachinePort({ port: 80, handlers: ["http"] })],
+            }),
+        ],
+        ...(props.env ? { env: props.env } : {}),
+    });
+    const machine = new Machine(mergeDefaults({ name: props.machine ?? "web", region, config }, defs?.machine));
+    const ip = props.ip ? new IPAddress({ type: props.ip }) : undefined;
+    const secrets = {};
+    for (const [name, value] of Object.entries(props.secrets ?? {})) {
+        secrets[memberName(name)] = new Secret({ name, value });
+    }
+    return {
+        app,
+        machine,
+        ...(volume ? { volume } : {}),
+        ...(ip ? { ip } : {}),
+        ...secrets,
+    };
+}, "FlySite");

package/dist/coverage.js

@@ -0,0 +1,29 @@
+/**
+ * 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, } from "@intentius/chant/codegen/coverage";
+export { computeCoverage, overallPct, formatSummary, formatVerbose, checkThresholds };
+/** Run coverage analysis for the fly lexicon. */
+export async function analyzeFlyCoverage(opts) {
+    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;
+}