@intentius/chant-lexicon-fly 0.90.0 → 0.91.0

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

@@ -2,7 +2,7 @@ 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";
+import { MACHINES_CONTRACT, MACHINE_RELEASE_CONTRACT, normalizeEndpoint, contractKeys } from "./machines-contract";
 
 describe("MACHINES_CONTRACT", () => {
   test("covers the flyApply resource operations (apps, machines, leases, volumes, ips, certs, secrets)", () => {
@@ -46,4 +46,14 @@ describe("MACHINES_CONTRACT", () => {
       expect(src, `path segment "${seg}" from the contract is absent from fly-apply.ts`).toContain(seg);
     }
   });
+
+  test("every release-contract verb appears in the machine-release.ts source (drift anchor, #2736)", () => {
+    const src = readFileSync(join(dirname(fileURLToPath(import.meta.url)), "machine-release.ts"), "utf-8");
+    for (const e of MACHINE_RELEASE_CONTRACT) {
+      expect(src, `${e.op} is absent from machine-release.ts`).toContain(e.op);
+    }
+    // exec is a literal path segment; restart and stop go through one `/${verb}` template.
+    expect(src).toContain("/exec");
+    for (const verb of ['"restart"', '"stop"']) expect(src).toContain(verb);
+  });
 });

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

@@ -71,3 +71,20 @@ export function normalizeEndpoint(method: string, path: string): string {
 export function contractKeys(): Set<string> {
   return new Set(MACHINES_CONTRACT.map((e) => normalizeEndpoint(e.method, e.path)));
 }
+
+/**
+ * The flaps endpoints the release activities (./machine-release.ts, #2736)
+ * add beyond the applier's: getting one Machine back, exec (a migration),
+ * restart and stop. The applier's own contract above stays exec-free; these
+ * are the site steps', and the docker-gated coverage test holds the pinned
+ * mudflaps to them the same way.
+ */
+export const MACHINE_RELEASE_CONTRACT: readonly MachinesEndpoint[] = [
+  { method: "GET", path: "/v1/apps/{app}/machines", op: "findMachine" },
+  { method: "POST", path: "/v1/apps/{app}/machines/{id}", op: "flyMachineRestore" },
+  { method: "POST", path: "/v1/apps/{app}/machines/{id}/exec", op: "flyMachineExec" },
+  { method: "POST", path: "/v1/apps/{app}/machines/{id}/restart", op: "flyMachineRestart" },
+  { method: "POST", path: "/v1/apps/{app}/machines/{id}/stop", op: "flyMachineStop" },
+  { method: "POST", path: "/v1/apps/{app}/machines/{id}/lease", op: "withLease" },
+  { method: "GET", path: "/v1/apps/{app}/machines/{id}/wait", op: "waitForMachine" },
+] as const;

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

@@ -0,0 +1,165 @@
+/**
+ * An in-memory Fly Machines (flaps) API, as a {@link FlyHttp} (#2736).
+ *
+ * The twin of ./sprites-fake.ts for the Machines side: the endpoints the
+ * applier (./fly-apply.ts) and the release activities (./machine-release.ts)
+ * call, answered from memory with the response shapes flaps and mudflaps use.
+ * Unit tests inject it where the default client would reach the network; the
+ * docker-gated tests run the same activities against the pinned mudflaps.
+ *
+ * Not an activity: nothing in ./index.ts exports it, so `loadActivities`
+ * never binds it.
+ */
+
+import type { FlyHttp } from "./fly-apply";
+
+/** One Machine the fake holds. */
+export interface FakeMachine {
+  id: string;
+  name: string;
+  state: string;
+  instance_id: string;
+  config: Record<string, unknown> & { metadata?: Record<string, string> };
+}
+
+/** What an `exec` answers: the Machines API's exec envelope. */
+export interface FakeExecResult {
+  exit_code: number;
+  stdout?: string;
+  stderr?: string;
+}
+
+export interface MachinesFake {
+  http: FlyHttp;
+  apps: Set<string>;
+  machines: Map<string, FakeMachine[]>;
+  /** Every exec, in order: the app, the machine id and the command. */
+  execs: Array<{ app: string; id: string; command: string[] }>;
+  /** Every call, as `METHOD path` (no base, no query). */
+  calls: string[];
+  /** The live machine named `name` in `app`, if any. */
+  machine(app: string, name: string): FakeMachine | undefined;
+}
+
+export interface MachinesFakeOptions {
+  /** Answer an exec. Default: exit 0 with no output. */
+  exec?: (app: string, machine: FakeMachine, command: string[]) => FakeExecResult;
+  /** The state a created or updated machine settles in. Default `started`. */
+  settle?: (machine: FakeMachine) => string;
+}
+
+const json = (status: number, body: unknown) => ({ status, text: body === undefined ? "" : JSON.stringify(body) });
+
+let seq = 0;
+const nextId = (prefix: string) => `${prefix}${(++seq).toString(16).padStart(10, "0")}`;
+
+/** A fresh in-memory flaps. */
+export function createMachinesFake(options: MachinesFakeOptions = {}): MachinesFake {
+  const apps = new Set<string>();
+  const machines = new Map<string, FakeMachine[]>();
+  const execs: MachinesFake["execs"] = [];
+  const calls: string[] = [];
+  const settle = options.settle ?? (() => "started");
+  const list = (app: string) => machines.get(app) ?? [];
+  const find = (app: string, id: string) => list(app).find((m) => m.id === id);
+
+  const http: FlyHttp = async (method, url, body) => {
+    const { pathname, searchParams } = new URL(url);
+    calls.push(`${method} ${pathname}`);
+    const seg = pathname.split("/").filter(Boolean).map(decodeURIComponent);
+    // seg: ["v1", "apps", app?, kind?, id?, action?]
+    if (seg[0] !== "v1" || seg[1] !== "apps") return json(404, { error: "not found" });
+    const app = seg[2];
+    const b = (body ?? {}) as Record<string, unknown>;
+
+    if (!app) {
+      if (method === "POST") {
+        const name = String(b.app_name);
+        if (apps.has(name)) return json(409, { error: "app exists" });
+        apps.add(name);
+        return json(201, { name, status: "deployed" });
+      }
+      return json(200, [...apps].map((name) => ({ name })));
+    }
+    if (seg.length === 3) {
+      if (method === "GET") return apps.has(app) ? json(200, { name: app, status: "deployed" }) : json(404, { error: "app not found" });
+      if (method === "DELETE") {
+        apps.delete(app);
+        machines.delete(app);
+        return json(202, undefined);
+      }
+    }
+    if (!apps.has(app)) return json(404, { error: "app not found" });
+    const kind = seg[3];
+
+    if (kind === "machines") {
+      const id = seg[4];
+      const action = seg[5];
+      if (!id) {
+        if (method === "GET") return json(200, list(app));
+        if (method === "POST") {
+          const m: FakeMachine = {
+            id: nextId("m"),
+            name: String(b.name ?? ""),
+            state: "created",
+            instance_id: nextId("I"),
+            config: structuredClone((b.config ?? {}) as FakeMachine["config"]),
+          };
+          m.state = settle(m);
+          machines.set(app, [...list(app), m]);
+          return json(200, m);
+        }
+      }
+      const m = id ? find(app, id) : undefined;
+      if (!m) return action === "wait" ? json(200, { ok: true }) : json(404, { error: "machine not found" });
+      if (!action) {
+        if (method === "GET") return json(200, m);
+        if (method === "POST") {
+          m.config = structuredClone((b.config ?? {}) as FakeMachine["config"]);
+          m.instance_id = nextId("I");
+          m.state = settle(m);
+          return json(200, m);
+        }
+        if (method === "DELETE") {
+          machines.set(app, list(app).filter((x) => x !== m));
+          return json(200, { ok: true });
+        }
+      }
+      if (action === "lease") {
+        if (method === "POST") return json(200, { data: { nonce: nextId("n") } });
+        return json(200, { ok: true });
+      }
+      if (action === "wait") {
+        const want = searchParams.get("state") ?? "started";
+        return json(200, { ok: m.state === want });
+      }
+      if (action === "restart" || action === "start") {
+        m.state = "started";
+        return json(200, { ok: true });
+      }
+      if (action === "stop") {
+        m.state = "stopped";
+        return json(200, { ok: true });
+      }
+      if (action === "exec" && method === "POST") {
+        const command = (b.command as string[] | undefined) ?? String(b.cmd ?? "").split(" ");
+        execs.push({ app, id: m.id, command });
+        return json(200, options.exec?.(app, m, command) ?? { exit_code: 0, stdout: "", stderr: "" });
+      }
+      return json(404, { error: `no ${method} ${action}` });
+    }
+    if (kind === "ip_assignments") return method === "GET" ? json(200, { ips: [] }) : json(200, {});
+    if (kind === "certificates") return method === "GET" ? json(200, { certificates: [] }) : json(200, {});
+    if (kind === "volumes" || kind === "secrets") return method === "GET" ? json(200, []) : json(200, {});
+    return json(404, { error: "not found" });
+  };
+
+  return {
+    http,
+    apps,
+    machines,
+    execs,
+    calls,
+    machine: (app, name) => list(app).find((m) => m.name === name && !["destroyed", "destroying"].includes(m.state)),
+  };
+}

package/src/op/builders.ts

@@ -42,6 +42,13 @@ import type {
 } from "./activities/sprite-services";
 import type { SpriteTaskCreateArgs, SpriteTaskRefreshArgs, SpriteTaskReleaseArgs } from "./activities/sprite-tasks";
 import type { SpritesUpArgs, SpritesDownArgs } from "./activities/sprites-emulator";
+import type {
+  FlyMachineReleaseArgs,
+  FlyMachineExecArgs,
+  FlyMachineStateArgs,
+  FlyMachineVerifyArgs,
+  FlyMachineRestoreArgs,
+} from "./activities/machine-release";
 
 type StepOpts = { profile?: ActivityStep["profile"] };
 
@@ -127,3 +134,21 @@ export const spritesUp = (args: WithStepRefs<SpritesUpArgs> & StepOpts = {}): Na
 /** Stop and remove the local spritzer container — the fully typed twin of core's `spritesDown`. Defaults to the `fastIdempotent` profile. */
 export const spritesDown = (args: WithStepRefs<SpritesDownArgs> & StepOpts = {}): NamedActivityStep =>
   spriteStep<SpritesDownArgs>("spritesDown", "fastIdempotent")(args);
+
+// ── Machines release activities (#2736, ws-056) ──────────────────────────────
+// The site steps as Op steps: upload and start, a migration inside the
+// Machine, restart, stop, verify and restore. Wrap a migration's
+// `flyMachineExec` in `effect()` so it fires once per environment.
+
+/** Apply the plan with the Machine serving a release (its digest in the Machine's metadata). Defaults to the `longInfra` profile. */
+export const flyMachineRelease = spriteStep<FlyMachineReleaseArgs>("flyMachineRelease", "longInfra");
+/** Run a command inside a Machine (a migration). Defaults to the `atMostOnce` profile: chant cannot know the command is safe to repeat. */
+export const flyMachineExec = spriteStep<FlyMachineExecArgs>("flyMachineExec", "atMostOnce");
+/** Restart a Machine under a lease and wait for it to be started. Defaults to the `longInfra` profile. */
+export const flyMachineRestart = spriteStep<FlyMachineStateArgs>("flyMachineRestart", "longInfra");
+/** Stop a Machine under a lease. Defaults to the `longInfra` profile. */
+export const flyMachineStop = spriteStep<FlyMachineStateArgs>("flyMachineStop", "longInfra");
+/** Check a Machine is started with a release, and its health endpoint answers. Defaults to the `longInfra` profile. */
+export const flyMachineVerify = spriteStep<FlyMachineVerifyArgs>("flyMachineVerify", "longInfra");
+/** Put a recorded Machine config back (restore, rollback). Defaults to the `longInfra` profile. */
+export const flyMachineRestore = spriteStep<FlyMachineRestoreArgs>("flyMachineRestore", "longInfra");

package/src/release-metadata.ts

@@ -0,0 +1,72 @@
+/**
+ * The release a Fly Machine serves, as its metadata records it (#2736, ws-056).
+ *
+ * Pure: the keys, a reader, and a writer over a Machine config. The Machines
+ * activities (./op/activities/machine-release.ts) stamp these on a release,
+ * `describeResources` (./describe-resources.ts) reads them back, and
+ * `chant components status --live` compares the digest with the release
+ * ledger.
+ */
+
+/**
+ * The Machine metadata keys that say which release it serves. Fly metadata is
+ * a string map, so each field is its own key.
+ *
+ * - `digest`: the release's digest, the release ledger's join key.
+ * - `gitSha`: the commit the release was built from.
+ * - `release`: an optional human label (a tag, a release id).
+ * - `previousDigest`: the release this one replaced when it first shipped, so
+ *   a rollback knows where to go back to with no history of its own.
+ */
+export const RELEASE_METADATA_KEYS = {
+  digest: "chant-release-digest",
+  gitSha: "chant-release-git-sha",
+  release: "chant-release",
+  previousDigest: "chant-release-previous-digest",
+} as const;
+
+/** A release, as a Machine's metadata records it. */
+export interface MachineRelease {
+  /** The release's digest (`sha256:...`): what the release ledger records. */
+  digest: string;
+  /** The commit it was built from. */
+  gitSha?: string;
+  /** A human label for it. */
+  release?: string;
+  /** The digest of the release it replaced, when there was one. */
+  previousDigest?: string;
+}
+
+export type MachineConfig = Record<string, unknown> & { metadata?: Record<string, string>; env?: Record<string, string> };
+
+/** The release a Machine's metadata names, or undefined when it names none. Pure. */
+export function readMachineRelease(metadata: Record<string, string> | null | undefined): MachineRelease | undefined {
+  const digest = metadata?.[RELEASE_METADATA_KEYS.digest];
+  if (!digest) return undefined;
+  const gitSha = metadata?.[RELEASE_METADATA_KEYS.gitSha];
+  const release = metadata?.[RELEASE_METADATA_KEYS.release];
+  const previousDigest = metadata?.[RELEASE_METADATA_KEYS.previousDigest];
+  return {
+    digest,
+    ...(gitSha ? { gitSha } : {}),
+    ...(release ? { release } : {}),
+    ...(previousDigest ? { previousDigest } : {}),
+  };
+}
+
+/**
+ * A Machine config serving `release`: a copy of `config` with the release's
+ * metadata keys set (and any it does not carry removed). Pure.
+ */
+export function withReleaseMetadata(config: MachineConfig | undefined, release: MachineRelease): MachineConfig {
+  const out = structuredClone(config ?? {}) as MachineConfig;
+  const metadata = { ...(out.metadata ?? {}) };
+  for (const key of Object.values(RELEASE_METADATA_KEYS)) delete metadata[key];
+  metadata[RELEASE_METADATA_KEYS.digest] = release.digest;
+  if (release.gitSha) metadata[RELEASE_METADATA_KEYS.gitSha] = release.gitSha;
+  if (release.release) metadata[RELEASE_METADATA_KEYS.release] = release.release;
+  if (release.previousDigest) metadata[RELEASE_METADATA_KEYS.previousDigest] = release.previousDigest;
+  out.metadata = metadata;
+  return out;
+}
+

package/src/release-store.ts

@@ -0,0 +1,70 @@
+/**
+ * Where a Fly release's Machine config is kept, so a rollback can put it back
+ * (#2736, ws-056).
+ *
+ * The Machine's metadata says which release it serves and which one it
+ * replaced; the config that earlier release applied is kept on the
+ * `chant/lifecycle` branch beside the release ledger, one file per release at
+ * `<env>/fly/<app>/<machine>/<digest>.json`. It is written through core's
+ * ledger plumbing, so a workspace member's copy lands under its own prefix,
+ * and every checkout that fetches the branch can roll back.
+ *
+ * Not exported from the package entry point: it spawns git, which stays off
+ * the build path. The `fly-release` and `fly-rollback` capabilities import it.
+ */
+
+import { readBlobFromPath, writeBlobToPath } from "@intentius/chant/lifecycle/git";
+
+/** Which Machine and release a config belongs to. */
+export interface MachineConfigRef {
+  app: string;
+  machine: string;
+  digest: string;
+}
+
+/** A store of the Machine config each release applied. */
+export interface MachineConfigStore {
+  read(ref: MachineConfigRef): Promise<Record<string, unknown> | undefined>;
+  write(ref: MachineConfigRef, config: Record<string, unknown>): Promise<void>;
+}
+
+const safe = (s: string) => s.replace(/[^a-zA-Z0-9_.-]/g, "_");
+
+/** The file a release's Machine config is kept in, under the environment's ledger directory. */
+export function machineConfigFile(ref: MachineConfigRef): string {
+  return `fly/${safe(ref.app)}/${safe(ref.machine)}/${safe(ref.digest.replace(/^sha256:/, ""))}.json`;
+}
+
+/** The lifecycle-branch store for `environment`. */
+export function lifecycleMachineConfigStore(environment: string, opts?: { cwd?: string }): MachineConfigStore {
+  return {
+    async read(ref) {
+      const content = await readBlobFromPath(environment, machineConfigFile(ref), opts);
+      return content === null ? undefined : (JSON.parse(content) as Record<string, unknown>);
+    },
+    async write(ref, config) {
+      await writeBlobToPath(
+        environment,
+        machineConfigFile(ref),
+        `${JSON.stringify(config, null, 2)}\n`,
+        `Fly release config ${ref.app}/${ref.machine} ${ref.digest}`,
+        opts,
+      );
+    },
+  };
+}
+
+/** An in-memory store, for tests and for a caller with nowhere to keep configs. */
+export function memoryMachineConfigStore(): MachineConfigStore & { entries: Map<string, Record<string, unknown>> } {
+  const entries = new Map<string, Record<string, unknown>>();
+  return {
+    entries,
+    async read(ref) {
+      const found = entries.get(machineConfigFile(ref));
+      return found ? structuredClone(found) : undefined;
+    },
+    async write(ref, config) {
+      entries.set(machineConfigFile(ref), structuredClone(config));
+    },
+  };
+}

package/src/skills/chant-fly-ops.md

@@ -53,3 +53,36 @@ Each prune logs the resource and endpoint it removed, so a prune run is auditabl
 ## Re-applying is safe
 
 A re-apply of an unchanged stack is a no-op per resource: machines whose config is structurally equal to live are skipped, volumes and certificates that already exist are skipped, and an IP of an already-present family is skipped. Only apply-only secrets are always re-set, because flaps exposes no value to diff against.
+
+## Releases on a Machine
+
+A component can deploy to Fly with this lexicon alone. It declares an `App` and the `Machine` that serves, builds them with `chant build --lexicon fly -o dist/fly.json`, and deploys with the `fly-release` step. Here a `Publish` phase (`publish-image`, elided) pushes the image, and the release serves it by digest:
+
+```ts
+import { phase, type Component } from "@intentius/chant/components";
+
+export const web: Component = {
+  name: "web",
+  deploy: [
+    phase("Publish", [/* publish-image */]),
+    phase("Release", [
+      {
+        kind: "fly-release",
+        plan: "dist/fly.json",
+        digest: "@Publish.digest",
+        image: "@Publish.uri",
+        migrations: [{ name: "001_init.sql", command: "node migrate.js 001_init.sql" }],
+        verify: { url: "https://web.example.com", healthPath: "/health" },
+      },
+    ]),
+  ],
+};
+```
+
+The step updates the Machine in place with the release in its `config.metadata`: `chant-release-digest`, `chant-release-git-sha` (the commit, `git rev-parse HEAD` unless given), and `chant-release-previous-digest` (the release it replaced). Each migration then runs inside the Machine through the Machines API's exec, once per environment: its receipt is kept on `chant/lifecycle` at `<env>/receipts/`, and a migration fires again only when its `sha` (or command) changes. After a migration fires, the Machine restarts, and the step checks that it is started with this release and, given a `url`, that its health endpoint answers with this commit or digest. If anything fails after the Machine changed, the step puts back the config the Machine served before (on a first release, it stops the Machine) and fails.
+
+The step's output carries `uri` and `digest`, so `chant run --components web --env prod` records the release in the ledger. `chant components status prod --live` reads the Machine's metadata back and compares its digest with the ledger's: the row is `reconciled` when they agree and `drifted` when the Machine serves something the ledger does not name. The component joins the Machine by name: name the component after the Machine entity, or list it in `liveNames`.
+
+Each release's Machine config is kept on `chant/lifecycle` at `<env>/fly/<app>/<machine>/<digest>.json`. `fly-rollback` puts back the config of the release the serving one replaced (or the digest given as `to`), checks it, and outputs that digest so the ledger records it again. `fly-release`'s own saga compensation does the same.
+
+The steps are also Op activities, for an Op that composes them itself: `flyMachineRelease`, `flyMachineExec`, `flyMachineRestart`, `flyMachineStop`, `flyMachineVerify` and `flyMachineRestore`. Wrap a migration's `flyMachineExec` in `effect()` so it fires once.