@intentius/chant-lexicon-fly 0.91.0 → 0.93.0

package/src/composites/fly-site.ts

@@ -0,0 +1,140 @@
+/**
+ * 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 type { Declarable } from "@intentius/chant/declarable";
+import { Fly } from "../pseudo";
+import {
+  App,
+  IPAddress,
+  Machine,
+  MachineConfig,
+  MachineGuest,
+  MachineMount,
+  MachinePort,
+  MachineService,
+  Secret,
+  Volume,
+} from "../generated/index";
+
+export interface FlySiteProps {
+  /** The App's name. Fly app names are global. */
+  app: string;
+  /** The owning org (default: `Fly.OrgSlug`, which the build resolves from `FLY_ORG`). */
+  org?: string | Declarable;
+  /** Region of the Machine and the Volume (default: `Fly.Region`, from `FLY_REGION`). */
+  region?: string | Declarable;
+  /** The Machine's name (default: "web"). */
+  machine?: string;
+  /** The image the Machine runs until a release replaces it. */
+  image: string;
+  /** The port the app listens on inside the Machine (default: 8080). Fly's proxy sends 443 (TLS) and 80 to it. */
+  port?: number;
+  /** The Machine's env. */
+  env?: Record<string, string>;
+  /** Guest CPU kind (default: "shared"). */
+  cpuKind?: string;
+  /** Guest CPUs (default: 1). */
+  cpus?: number;
+  /** Guest memory in MB (default: 256). */
+  memoryMb?: number;
+  /** A Volume for the app's data, mounted at `path`. It outlives releases. Omitted: no Volume. */
+  volume?: { name: string; sizeGb: number; path: string };
+  /** A public IP of this type (for example "shared_v4"). Omitted: none. */
+  ip?: "shared_v4" | "v4" | "v6";
+  /**
+   * The app's Secrets, by name. An undefined value declares the Secret
+   * without a value, so the release checks the app already has it.
+   */
+  secrets?: Record<string, string | undefined>;
+  /** Per-member defaults for fine-grained overrides. */
+  defaults?: {
+    app?: Partial<Record<string, unknown>>;
+    machine?: Partial<Record<string, unknown>>;
+    volume?: Partial<Record<string, unknown>>;
+  };
+}
+
+/** `APP_SECRET` -> `appSecret`: a Secret's member name, never one of the other members'. */
+function memberName(secret: string): string {
+  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: FlySiteProps) => {
+  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 } as Record<string, unknown>, defs?.app) as ConstructorParameters<typeof App>[0]);
+
+  const volume = props.volume
+    ? new Volume(mergeDefaults({ name: props.volume.name, region, size_gb: props.volume.sizeGb } as Record<string, unknown>, defs?.volume) as ConstructorParameters<typeof Volume>[0])
+    : 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 } as Record<string, unknown>, defs?.machine) as ConstructorParameters<typeof Machine>[0]);
+
+  const ip = props.ip ? new IPAddress({ type: props.ip }) : undefined;
+
+  const secrets: Record<string, Declarable> = {};
+  for (const [name, value] of Object.entries(props.secrets ?? {})) {
+    secrets[memberName(name)] = new Secret({ name, value } as ConstructorParameters<typeof Secret>[0]);
+  }
+
+  return {
+    app,
+    machine,
+    ...(volume ? { volume } : {}),
+    ...(ip ? { ip } : {}),
+    ...secrets,
+  };
+}, "FlySite");

package/src/index.ts

@@ -32,6 +32,10 @@ export type { FlyDeployOpts, FlyApplyStepOpts, FlapsStepOpts } from "./composite
 export { FlyOtelCollector } from "./composites/fly-otel-collector";
 export type { FlyOtelCollectorProps } from "./composites/fly-otel-collector";
 
+// A Fly app that serves one app's releases: App, Machine, and its Volume, IP and Secrets (#2809, ws-056).
+export { FlySite } from "./composites/fly-site";
+export type { FlySiteProps } from "./composites/fly-site";
+
 // Sprite Op step builders. chant #1288 Stage 2: these author
 // `activity("spriteCreate", ...)` steps with authoring-time types derived
 // from this lexicon's own `Sprite*Args` interfaces (`./op/builders.ts`),
@@ -64,6 +68,8 @@ export {
   spriteServiceStop,
   spriteServiceDelete,
   spriteServiceLogs,
+  spriteServicesObserve,
+  spriteServiceRestart,
   spriteTaskCreate,
   spriteTaskRefresh,
   spriteTaskRelease,
@@ -75,6 +81,8 @@ export {
   flyMachineStop,
   flyMachineVerify,
   flyMachineRestore,
+  flyRelease,
+  flyRollback,
 } from "./op/builders";
 
 // Generated resources — export everything from generated index.

package/src/op/activities/fly-release-step.ts

@@ -0,0 +1,32 @@
+/**
+ * `flyRelease`: the `fly-release` capability (../../components/fly-release.ts)
+ * as an Op activity (#2782), so an Op's ship phase runs the same site steps a
+ * component's deploy does: upload and start, each migration once per
+ * environment under a receipt in chant's lifecycle receipt store, verify, and
+ * restore on a failure after the Machine changed.
+ *
+ * An Op has no environment of its own, so the step names the one it ships to
+ * (`environment`); the receipts and the recorded Machine configs are that
+ * environment's, as they are for the component.
+ *
+ * Retrying a release that already serves changes nothing: the apply finds the
+ * Machine's config unchanged, and every migration's receipt matches.
+ */
+
+import type { FlyReleaseInput, FlyReleaseOutput } from "../../components/fly-release";
+
+export interface FlyReleaseArgs extends FlyReleaseInput {
+  /** The environment the release ships to: its receipts and recorded configs. (`env` is the Machine's env, as for the capability.) */
+  environment: string;
+  /** The component the release belongs to, for attribution. Default `app`. */
+  component?: string;
+}
+
+export type FlyReleaseResult = FlyReleaseOutput;
+
+export async function flyRelease(args: FlyReleaseArgs): Promise<FlyReleaseResult> {
+  const { environment, component, ...input } = args;
+  if (!environment) throw new Error("flyRelease: name the environment the release ships to (environment)");
+  const { flyReleaseCapability } = await import("../../components/fly-release");
+  return flyReleaseCapability.run({ env: environment, component: component ?? "app" }, input);
+}

package/src/op/activities/fly-rollback-step.ts

@@ -0,0 +1,33 @@
+/**
+ * `flyRollback`: the `fly-rollback` capability (../../components/fly-release.ts)
+ * as an Op activity (#2800), so a rollback Op puts an earlier release back on
+ * the Machine the way the release Op's `flyRelease` put it there.
+ *
+ * It restores the Machine config `fly-release` recorded for the release it
+ * goes back to (files included), in the environment `environment` names, and
+ * checks that the Machine is started with that release. Given `source`, the
+ * archive is read only once it hashes to its digest, before any flaps call,
+ * and the recorded config must carry exactly that tree, or nothing changes.
+ * A release with no recorded config is refused by name.
+ *
+ * Running it again once the Machine serves the release changes nothing.
+ * Migrations are not undone: the data stays where the later release left it.
+ */
+
+import type { FlyRollbackInput, FlyRollbackOutput } from "../../components/fly-release";
+
+export interface FlyRollbackArgs extends FlyRollbackInput {
+  /** The environment whose recorded Machine configs are read. */
+  environment: string;
+  /** The component the release belongs to, for attribution. Default `app`. */
+  component?: string;
+}
+
+export type FlyRollbackResult = FlyRollbackOutput;
+
+export async function flyRollback(args: FlyRollbackArgs): Promise<FlyRollbackResult> {
+  const { environment, component, ...input } = args;
+  if (!environment) throw new Error("flyRollback: name the environment whose release it restores (environment)");
+  const { flyRollbackCapability } = await import("../../components/fly-release");
+  return flyRollbackCapability.run({ env: environment, component: component ?? "app" }, input);
+}

package/src/op/activities/index.ts

@@ -47,10 +47,17 @@ export {
   flyMachineVerify,
   flyMachineRestore,
 } from "./machine-release";
+// The fly-release capability as an Op step (#2782): a release Op's ship phase.
+export { flyRelease } from "./fly-release-step";
+export type { FlyReleaseArgs, FlyReleaseResult } from "./fly-release-step";
+// The fly-rollback capability as an Op step (#2800): a rollback Op's restore.
+export { flyRollback } from "./fly-rollback-step";
+export type { FlyRollbackArgs, FlyRollbackResult } from "./fly-rollback-step";
 export type {
   MachineRelease,
   FlyMachineReleaseArgs,
   FlyMachineReleaseResult,
+  MachineFile,
   FlyMachineExecArgs,
   FlyMachineExecResult,
   FlyMachineStateArgs,
@@ -143,6 +150,24 @@ export type {
   SpriteServiceLogsResult,
 } from "./sprite-services";
 
+// A sprite's services as resources a ConvergeOp observes and converges (#2778):
+// the observer step and the restart a converge rule dispatches.
+export {
+  spriteServicesObserve,
+  spriteServiceRestart,
+  declaredServices,
+  findSpriteEnv,
+  parseServicesList,
+  probeHealth,
+} from "./sprite-service-converge";
+export type {
+  DeclaredSpriteService,
+  SpriteServicesObserveArgs,
+  SpriteServicesObserveResult,
+  SpriteServiceRestartArgs,
+  SpriteServiceRestartResult,
+} from "./sprite-service-converge";
+
 // Sprite filesystem activities (#848) — imperative file I/O over the fs API.
 // `loadActivities(["fly"])` binds these; the step builders live in core.
 export {

package/src/op/activities/machine-release.ts

@@ -139,9 +139,26 @@ export interface FlyMachineReleaseArgs extends FlapsTarget {
   image?: string;
   /** Env to add to the declared Machine's env. */
   env?: Record<string, string>;
+  /**
+   * Files the release puts on the Machine, added to the declared ones: a
+   * source release's tree (#2782). A declared file at the same path is
+   * replaced.
+   */
+  files?: MachineFile[];
+  /** The command the Machine starts, in place of the image's: an argv, or a string run with `sh -c`. */
+  cmd?: string[] | string;
   wait?: WaitOpts;
 }
 
+/** One file a Machine's config carries, as the Machines API takes it. */
+export interface MachineFile {
+  guest_path: string;
+  /** The file's bytes, base64. */
+  raw_value: string;
+  /** Unix mode, such as 0o755 for an executable. */
+  mode?: number;
+}
+
 export interface FlyMachineReleaseResult {
   app: string;
   machine: { id: string; name: string };
@@ -180,11 +197,16 @@ export async function flyMachineRelease(
   if (!previousDigest) delete release.previousDigest;
 
   const declared = (target.request.body.config ?? {}) as MachineConfig;
+  const declaredFiles = (declared.files as MachineFile[] | undefined) ?? [];
+  const releasePaths = new Set((args.files ?? []).map((f) => f.guest_path));
+  const cmd = typeof args.cmd === "string" ? ["sh", "-c", args.cmd] : args.cmd;
   const config = withReleaseMetadata(
     {
       ...declared,
       ...(args.image ? { image: args.image } : {}),
       ...(args.env ? { env: { ...(declared.env ?? {}), ...args.env } } : {}),
+      ...(args.files ? { files: [...declaredFiles.filter((f) => !releasePaths.has(f.guest_path)), ...args.files] } : {}),
+      ...(cmd ? { init: { ...((declared.init as Record<string, unknown> | undefined) ?? {}), cmd } } : {}),
     },
     release,
   );

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

@@ -6,6 +6,8 @@
  * 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.
+ * It runs nothing; ./machines-local.ts is the opt-in mode that runs each
+ * started Machine's files and command on this host (#2831).
  *
  * Not an activity: nothing in ./index.ts exports it, so `loadActivities`
  * never binds it.
@@ -42,8 +44,8 @@ export interface MachinesFake {
 }
 
 export interface MachinesFakeOptions {
-  /** Answer an exec. Default: exit 0 with no output. */
-  exec?: (app: string, machine: FakeMachine, command: string[]) => FakeExecResult;
+  /** Answer an exec. Default: exit 0 with no output. The running mode (./machines-local.ts) answers it by running the command. */
+  exec?: (app: string, machine: FakeMachine, command: string[]) => FakeExecResult | Promise<FakeExecResult>;
   /** The state a created or updated machine settles in. Default `started`. */
   settle?: (machine: FakeMachine) => string;
 }
@@ -144,7 +146,7 @@ export function createMachinesFake(options: MachinesFakeOptions = {}): MachinesF
       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(200, (await options.exec?.(app, m, command)) ?? { exit_code: 0, stdout: "", stderr: "" });
       }
       return json(404, { error: `no ${method} ${action}` });
     }

package/src/op/activities/machines-local-cli.ts

@@ -0,0 +1,73 @@
+/**
+ * A local Fly Machines API that runs its Machines (#2831), as a command:
+ *
+ *   tsx node_modules/@intentius/chant-lexicon-fly/src/op/activities/machines-local-cli.ts \
+ *     [--listen 4280] [--root <dir>] [--publish <port> | --publish <name>=<port> ...] [--log <file>]
+ *
+ * Point the release activities at it with `FLY_FLAPS_BASE_URL=http://127.0.0.1:4280`.
+ * `--publish 8080` publishes every Machine's service on 8080; `--publish web=8080`
+ * publishes the Machine named `web` there; with no `--publish` each Machine gets a free
+ * port, which the event lines say. SIGINT or SIGTERM stops every Machine's process
+ * and exits. See ./machines-local.ts.
+ */
+
+import { realpathSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { serveLocalMachines, type LocalPublish } from "./machines-local";
+
+export function parseArgs(argv: string[]): { port: number; root?: string; publish?: LocalPublish; log?: string } {
+  let port = 4280;
+  let root: string | undefined;
+  let log: string | undefined;
+  let all: number | undefined;
+  const byName: Record<string, number> = {};
+  for (let i = 0; i < argv.length; i++) {
+    const flag = argv[i];
+    const value = argv[i + 1];
+    if (value === undefined) throw new Error(`${flag} needs a value`);
+    if (flag === "--listen") port = Number(value);
+    else if (flag === "--root") root = value;
+    else if (flag === "--log") log = value;
+    else if (flag === "--publish") {
+      const eq = value.lastIndexOf("=");
+      if (eq === -1) all = Number(value);
+      else byName[value.slice(0, eq)] = Number(value.slice(eq + 1));
+    } else throw new Error(`unknown flag ${flag}`);
+    i++;
+  }
+  for (const n of [port, all, ...Object.values(byName)]) if (n !== undefined && !Number.isInteger(n)) throw new Error(`not a port: ${n}`);
+  const named = Object.keys(byName).length > 0;
+  const publish: LocalPublish | undefined =
+    named ? (app, m) => byName[`${app}/${m.name}`] ?? byName[m.name] ?? all : all;
+  return { port, root, publish, log };
+}
+
+async function main(): Promise<void> {
+  let args: ReturnType<typeof parseArgs>;
+  try {
+    args = parseArgs(process.argv.slice(2));
+  } catch (error) {
+    console.error(`machines-local: ${(error as Error).message}`);
+    console.error("usage: machines-local-cli.ts [--listen <port>] [--root <dir>] [--publish <port> | --publish <name>=<port>]... [--log <file>]");
+    process.exit(2);
+  }
+  const served = await serveLocalMachines({ ...args, handleSignals: false, onEvent: (line) => console.log(`machines-local: ${line}`) });
+  console.log(`machines-local: flaps on ${served.url}${args.root ? `, guest paths under ${args.root}` : ""}`);
+  let closing = false;
+  const shutdown = () => {
+    if (closing) return;
+    closing = true;
+    void served.close().then(() => process.exit(0));
+  };
+  process.on("SIGINT", shutdown);
+  process.on("SIGTERM", shutdown);
+}
+
+const invoked = (() => {
+  try {
+    return !!process.argv[1] && realpathSync(process.argv[1]) === realpathSync(fileURLToPath(import.meta.url));
+  } catch {
+    return false;
+  }
+})();
+if (invoked) void main();

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

@@ -0,0 +1,225 @@
+import { afterEach, describe, expect, test } from "vitest";
+import { spawn, spawnSync } from "node:child_process";
+import { existsSync, mkdtempSync, readFileSync, realpathSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { dirname, join } from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+import { createLocalMachines, serveLocalMachines } from "./machines-local";
+import { parseArgs } from "./machines-local-cli";
+import { flyMachineExec, flyMachineRelease, flyMachineRestore, flyMachineStop, type MachineFile } from "./machine-release";
+import type { FlyPlan } from "./fly-apply";
+
+const here = dirname(fileURLToPath(import.meta.url));
+const repoRoot = join(here, "../../../../..");
+const tsxLoader = pathToFileURL(join(repoRoot, "node_modules/tsx/dist/loader.mjs")).href;
+
+/** A tiny app: serves page.txt and, when a migration has written it, /data/state. */
+const SERVER = `
+import { createServer } from "node:http";
+import { readFileSync, existsSync } from "node:fs";
+const state = () => (existsSync(process.env.DATA + "/state") ? readFileSync(process.env.DATA + "/state", "utf8").trim() : "none");
+createServer((req, res) => res.end(readFileSync(new URL("./page.txt", import.meta.url), "utf8").trim() + " " + state())).listen(Number(process.env.PORT), "127.0.0.1");
+`;
+
+const b64 = (s: string) => Buffer.from(s).toString("base64");
+const files = (page: string): MachineFile[] => [
+  { guest_path: "/srv/app/server.mjs", raw_value: b64(SERVER) },
+  { guest_path: "/srv/app/page.txt", raw_value: b64(page) },
+];
+const config = (page: string) => ({
+  image: "node:22-slim",
+  env: { PORT: "8080", DATA: "/data" },
+  services: [{ protocol: "tcp", internal_port: 8080 }],
+  mounts: [{ volume: "data", path: "/data" }],
+  files: files(page),
+  init: { cmd: ["sh", "-c", "cd /srv/app && exec node server.mjs"] },
+});
+
+/** Is `pid` running, as `ps` sees it? */
+const alive = (pid: number) => spawnSync("ps", ["-p", String(pid)]).status === 0;
+const get = async (url: string) => (await fetch(url)).text();
+
+let dirs: string[] = [];
+let open: Array<{ close(): Promise<void> }> = [];
+const tmp = () => {
+  const d = realpathSync(mkdtempSync(join(tmpdir(), "chant-machines-local-")));
+  dirs.push(d);
+  return d;
+};
+afterEach(async () => {
+  for (const o of open) await o.close();
+  for (const d of dirs) rmSync(d, { recursive: true, force: true });
+  open = [];
+  dirs = [];
+});
+
+describe("the running mode of the local Machines API (#2831)", () => {
+  test("runs a Machine's files and command, serves it, restarts it on a new config, and stops it with no process left", { timeout: 60_000 }, async () => {
+    const root = tmp();
+    const served = await serveLocalMachines({ port: 0, root, log: join(root, "machines.log") });
+    open.push(served);
+    const machines = served.machines;
+    const call = async (method: string, path: string, body?: unknown) => {
+      const res = await fetch(`${served.url}${path}`, { method, body: body === undefined ? undefined : JSON.stringify(body), headers: { "content-type": "application/json" } });
+      const text = await res.text();
+      return { status: res.status, json: text ? JSON.parse(text) : undefined };
+    };
+
+    expect((await call("GET", "/_mudflaps/health")).status).toBe(200);
+    await call("POST", "/v1/apps", { app_name: "shop", org_slug: "personal" });
+    const created = await call("POST", "/v1/apps/shop/machines", { name: "web", config: config("A") });
+    expect(created.status).toBe(200);
+    const id = created.json.id as string;
+
+    const url = machines.endpoint("shop", "web");
+    expect(url).toMatch(/^http:\/\/127\.0\.0\.1:\d+$/);
+    expect(await get(url!)).toBe("A none");
+    // The files are under root, the guest paths the command named mapped there.
+    expect(readFileSync(join(root, "srv/app/page.txt"), "utf8")).toBe("A");
+    const [first] = machines.processes();
+    expect(first).toMatchObject({ app: "shop", name: "web", id });
+    expect(alive(first.pid!)).toBe(true);
+
+    // An exec runs in the Machine's env, against the Volume the app reads.
+    const exec = await call("POST", `/v1/apps/shop/machines/${id}/exec`, { command: ["sh", "-c", "echo migrated > $DATA/state && echo done"], timeout: 30 });
+    expect(exec.json).toMatchObject({ exit_code: 0, stdout: "done\n" });
+    expect(await get(url!)).toBe("A migrated");
+
+    // A new config is a new instance: the process starts again on the new files, on the same port, and the Volume is kept.
+    const updated = await call("POST", `/v1/apps/shop/machines/${id}`, { config: config("B") });
+    expect(updated.json.instance_id).not.toBe(created.json.instance_id);
+    const [second] = machines.processes();
+    expect(second.pid).not.toBe(first.pid);
+    expect(alive(first.pid!)).toBe(false);
+    expect(machines.endpoint("shop", "web")).toBe(url);
+    expect(await get(url!)).toBe("B migrated");
+
+    // A restart runs it again.
+    await call("POST", `/v1/apps/shop/machines/${id}/restart`);
+    const [third] = machines.processes();
+    expect(third.pid).not.toBe(second.pid);
+    expect(alive(second.pid!)).toBe(false);
+    expect(await get(url!)).toBe("B migrated");
+
+    // A stop leaves nothing running and removes the instance's files; the Volume stays.
+    await call("POST", `/v1/apps/shop/machines/${id}/stop`);
+    expect(machines.processes()).toEqual([]);
+    expect(alive(third.pid!)).toBe(false);
+    expect(machines.endpoint("shop", "web")).toBeUndefined();
+    expect(existsSync(join(root, "srv/app/page.txt"))).toBe(false);
+    expect(readFileSync(join(root, "data/state"), "utf8")).toBe("migrated\n");
+
+    // Start, then delete: running again, then gone.
+    await call("POST", `/v1/apps/shop/machines/${id}/start`);
+    const [fourth] = machines.processes();
+    expect(await get(url!)).toBe("B migrated");
+    await call("DELETE", `/v1/apps/shop/machines/${id}`);
+    expect(machines.processes()).toEqual([]);
+    expect(alive(fourth.pid!)).toBe(false);
+  });
+
+  test("the release activities: release A, a migration, release B, then A restored serves A again", { timeout: 60_000 }, async () => {
+    const root = tmp();
+    const machines = createLocalMachines({ root });
+    open.push(machines);
+    const endpoint = "http://flaps.local";
+    const wait = { intervalMs: 20, deadlineMs: 10_000 };
+    const plan: FlyPlan = {
+      shop: { endpoint: "/v1/apps", method: "POST", body: { app_name: "shop", org_slug: "personal" } },
+      web: {
+        endpoint: "/v1/apps/shop/machines",
+        method: "POST",
+        body: { name: "web", config: { image: "node:22-slim", env: { PORT: "8080", DATA: "/data" }, services: [{ internal_port: 8080 }], mounts: [{ volume: "data", path: "/data" }] } },
+      },
+    };
+    const release = (page: string, digest: string) =>
+      flyMachineRelease({ plan, endpoint, release: { digest }, files: files(page), cmd: "cd /srv/app && exec node server.mjs", wait }, undefined, machines.http);
+
+    const a = await release("A", "sha256:a");
+    const url = machines.endpoint("shop", "web")!;
+    expect(await get(url)).toBe("A none");
+    await flyMachineExec({ app: "shop", machine: "web", command: "echo v1 > /data/state", endpoint }, undefined, machines.http);
+    expect(await get(url)).toBe("A v1");
+
+    await release("B", "sha256:b");
+    expect(await get(url)).toBe("B v1");
+
+    await flyMachineRestore({ app: "shop", machine: "web", config: a.config, endpoint, wait }, undefined, machines.http);
+    expect(await get(url)).toBe("A v1");
+
+    const [p] = machines.processes();
+    await flyMachineStop({ app: "shop", machine: "web", endpoint, wait }, undefined, machines.http);
+    expect(machines.processes()).toEqual([]);
+    expect(alive(p.pid!)).toBe(false);
+  });
+
+  test("a process that exits on its own leaves its Machine stopped", { timeout: 30_000 }, async () => {
+    const machines = createLocalMachines({ root: tmp(), log: join(tmp(), "log") });
+    open.push(machines);
+    await machines.http("POST", "http://f/v1/apps", { app_name: "shop" });
+    const r = await machines.http("POST", "http://f/v1/apps/shop/machines", { name: "web", config: { init: { cmd: ["sh", "-c", "exit 3"] } } });
+    const id = JSON.parse(r.text).id as string;
+    for (let i = 0; i < 100 && machines.machine("shop", "web")!.state === "started"; i++) await new Promise((ok) => setTimeout(ok, 20));
+    expect(machines.machine("shop", "web")!.state).toBe("stopped");
+    expect(machines.processes()).toEqual([]);
+    expect(JSON.parse((await machines.http("GET", `http://f/v1/apps/shop/machines/${id}/wait?state=started`)).text)).toEqual({ ok: false });
+  });
+
+  test("with no root, guest paths are host paths", async () => {
+    const dir = tmp();
+    const machines = createLocalMachines({ log: join(dir, "log") });
+    open.push(machines);
+    await machines.http("POST", "http://f/v1/apps", { app_name: "shop" });
+    await machines.http("POST", "http://f/v1/apps/shop/machines", {
+      name: "web",
+      config: { files: [{ guest_path: join(dir, "a/b.txt"), raw_value: b64("hi") }] },
+    });
+    expect(readFileSync(join(dir, "a/b.txt"), "utf8")).toBe("hi");
+  });
+
+  for (const how of ["SIGTERM", "SIGINT", "exit"] as const) {
+    test(`a Machine's process does not outlive its host process (${how})`, { timeout: 60_000 }, async () => {
+      const root = tmp();
+      const script = join(root, "host.mts");
+      writeFileSync(
+        script,
+        `import { createLocalMachines } from ${JSON.stringify(join(here, "machines-local.ts"))};
+const m = createLocalMachines({ root: ${JSON.stringify(root)}, log: ${JSON.stringify(join(root, "log"))} });
+await m.http("POST", "http://f/v1/apps", { app_name: "shop" });
+await m.http("POST", "http://f/v1/apps/shop/machines", { name: "web", config: { init: { cmd: ["sh", "-c", "sleep 300 & exec sleep 301"] } } });
+console.log(JSON.stringify(m.processes()[0].pid));
+${how === "exit" ? "setTimeout(() => process.exit(0), 100);" : "setInterval(() => undefined, 1000);"}
+`,
+      );
+      const host = spawn(process.execPath, ["--import", tsxLoader, script], {
+        stdio: ["ignore", "pipe", "inherit"],
+        // tsx's on-disk cache can stall for seconds under load; this script is too small to need it.
+        env: { ...process.env, TSX_DISABLE_CACHE: "1" },
+      });
+      const pid = await new Promise<number>((ok) => host.stdout!.once("data", (d) => ok(Number(String(d).trim()))));
+      expect(alive(pid)).toBe(true);
+      const exited = new Promise((ok) => host.once("exit", ok));
+      if (how !== "exit") host.kill(how);
+      await exited;
+      for (let i = 0; i < 50 && alive(pid); i++) await new Promise((ok) => setTimeout(ok, 20));
+      expect(alive(pid)).toBe(false);
+      // Nor does anything the command started in its group.
+      const left = spawnSync("pgrep", ["-g", String(pid)], { encoding: "utf8" }).stdout.trim();
+      expect(left).toBe("");
+    });
+  }
+});
+
+describe("machines-local-cli args", () => {
+  test("--publish takes one port for every Machine, or name=port", () => {
+    expect(parseArgs([])).toMatchObject({ port: 4280, publish: undefined });
+    expect(parseArgs(["--listen", "4999", "--root", "/r", "--publish", "8080"])).toMatchObject({ port: 4999, root: "/r", publish: 8080 });
+    const { publish } = parseArgs(["--publish", "web=8080", "--publish", "shop/api=9090"]);
+    const fn = publish as (app: string, m: { name: string }) => number | undefined;
+    expect(fn("shop", { name: "web" })).toBe(8080);
+    expect(fn("shop", { name: "api" })).toBe(9090);
+    expect(fn("shop", { name: "other" })).toBeUndefined();
+    expect(() => parseArgs(["--publish"])).toThrow(/needs a value/);
+    expect(() => parseArgs(["--nope", "1"])).toThrow(/unknown flag/);
+  });
+});