endia 0.0.0-stage → 0.0.2

package/dist/groups/execs.js

@@ -0,0 +1,119 @@
+import { ExecSession } from "../exec/exec-session.js";
+import { Routes } from "../routes.js";
+import { jsonBody } from "../transport/api-connection.js";
+import { QueryText } from "../transport/query-text.js";
+/**
+ * The exec routes, which run a program in a running machine as `docker exec` does: create the exec, then start it attached over a
+ * WebSocket or detached. `run`, `spawn` and `start` do both steps; `create`, `attach`, `startDetached`, `inspect` and `resize` are the
+ * single routes.
+ */
+export class ExecsClient {
+    connection;
+    /** @internal */
+    constructor(connection) {
+        this.connection = connection;
+    }
+    /**
+     * Runs a program to its end and collects its output: `endia exec`.
+     *
+     * @param machine - The machine name or a unique prefix of its ID.
+     * @param request - The program and its arguments in `cmd`, and how to run it.
+     * @param options - `input` is sent to the program's standard input.
+     * @returns The exit code in full and the output.
+     */
+    async run(machine, request, options = {}) {
+        const session = await this.spawn(machine, { ...request, attachStdin: options.input !== undefined }, options.signal);
+        session.stdin?.end(options.input);
+        const [stdout, stderr] = await Promise.all([collect(session.stdout), collect(session.stderr)]);
+        const exec = await session.wait(options.signal);
+        return { exitCode: exec.exitCode, startError: exec.startError, stdout, stderr, exec };
+    }
+    /**
+     * Starts a program with the caller attached to its streams: `endia exec` without collecting.
+     *
+     * @param machine - The machine name or a unique prefix of its ID.
+     * @param request - The program and its arguments in `cmd`, and how to run it. With `attachStdin`, the session's `stdin` is open.
+     * @param signal - Cancels the requests; the program keeps running once it has started.
+     * @returns The running program's streams; read both output streams.
+     */
+    async spawn(machine, request, signal) {
+        const created = await this.create(machine, request, signal);
+        return this.attach(created.id, { tty: request.tty ?? false, attachStdin: request.attachStdin ?? false }, signal);
+    }
+    /**
+     * Starts a program and returns at once: `endia exec -d`. The program's output is kept in the machine for
+     * `ProcessesClient.logs`.
+     *
+     * @param machine - The machine name or a unique prefix of its ID.
+     * @param request - The program and its arguments in `cmd`, and how to run it.
+     * @param signal - Cancels the requests.
+     * @returns The exec ID and the process the program runs in, which the process routes take.
+     */
+    async start(machine, request, signal) {
+        const created = await this.create(machine, request, signal);
+        return { id: created.id, ...await this.startDetached(created.id, signal) };
+    }
+    /**
+     * Creates an exec without starting it: `POST /v1/machines/{name}/exec`.
+     *
+     * @param machine - The machine name or a unique prefix of its ID.
+     * @param request - The program and its arguments in `cmd`, and how to run it.
+     * @param signal - Cancels the request.
+     * @returns The new exec's ID.
+     */
+    create(machine, request, signal) {
+        return this.connection.change({ method: "POST", path: Routes.machineExec(machine), body: jsonBody(request), signal });
+    }
+    /**
+     * Starts a created exec with the caller attached, over a WebSocket: `GET /v1/execs/{id}/start`.
+     *
+     * @param id - The exec ID.
+     * @param shape - Whether the exec was created with `tty` and with `attachStdin`, which decides how its messages are read and written.
+     * @param signal - Cancels the opening.
+     * @returns The running program's streams.
+     */
+    async attach(id, shape, signal) {
+        const socket = await this.connection.openWebSocket(Routes.execStart(id), signal);
+        return new ExecSession(id, socket, shape, this);
+    }
+    /**
+     * Starts a created exec without the caller attached: `POST /v1/execs/{id}/start` with `{ "detach": true }`.
+     *
+     * @param id - The exec ID.
+     * @param signal - Cancels the request.
+     * @returns The process the program runs in.
+     */
+    startDetached(id, signal) {
+        return this.connection.change({ method: "POST", path: Routes.execStart(id), body: jsonBody({ detach: true }), signal });
+    }
+    /**
+     * Reads an exec: what was asked for, its process, and its exit code once it has ended.
+     *
+     * @param id - The exec ID.
+     * @param signal - Cancels the request.
+     * @returns The exec.
+     */
+    inspect(id, signal) {
+        return this.connection.read(Routes.exec(id), signal);
+    }
+    /**
+     * Changes the size of an exec's console.
+     *
+     * @param id - The exec ID.
+     * @param rows - The number of rows.
+     * @param columns - The number of columns.
+     * @param signal - Cancels the request.
+     * @returns When the service has resized the console.
+     */
+    resize(id, rows, columns, signal) {
+        const query = new QueryText().add("h", rows).add("w", columns);
+        return this.connection.changeWithoutAnswer({ method: "POST", path: Routes.execResize(id) + query.toString(), signal });
+    }
+}
+async function collect(stream) {
+    const chunks = [];
+    for await (const chunk of stream) {
+        chunks.push(chunk);
+    }
+    return Buffer.concat(chunks).toString("utf8");
+}

package/dist/groups/fleets.d.ts

@@ -0,0 +1,206 @@
+import type { Readable } from "node:stream";
+import type { ComposeModel } from "../contract/compose.js";
+import type { FleetDetail, FleetDownResult, FleetDryRun, FleetMachinesResult, FleetSummary, FleetUpResult } from "../contract/fleets.js";
+import type { MachineLogLine, MachineSummary } from "../contract/machines.js";
+import type { FleetPurpose, FleetPurposeResult } from "../contract/purposes.js";
+import { type LogOptions } from "./machines.js";
+import type { OperationHandle } from "./operations.js";
+/** How `compose up` brings the fleet to the state its model describes, as the options of `endia compose up` choose it. */
+export interface FleetUpOptions {
+    /** The services to bring up, with the services they depend on; every service when undefined or empty. */
+    readonly services?: readonly string[];
+    /** The number of machines of some services, whatever the model says, each written `<service>=<n>`. */
+    readonly scale?: readonly string[];
+    /** When images are built: `always`, `never`, or `missing`, the default, which builds a service's image only when it does not exist. */
+    readonly build?: "always" | "never" | "missing";
+    /** When existing machines are recreated: `force`, `never`, or `changed`, the default, which recreates a machine whose service changed. */
+    readonly recreate?: "force" | "never" | "changed";
+    /** Whether machines of services no longer in the model are removed, rather than named in a warning. */
+    readonly removeOrphans?: boolean;
+    /** The time in seconds Windows has to shut down in machines being recreated or removed. */
+    readonly timeout?: number;
+    /** The Compose files the model came from, which the fleet's record keeps and `compose ls` shows. */
+    readonly configFiles?: readonly string[];
+    /** The folder against which the model's relative paths were resolved, which the fleet's record keeps. */
+    readonly projectDirectory?: string;
+    /** The fleet's purpose, what it is being used for, in one line of 1 to 200 characters: `--purpose`. The service stores it, replacing any purpose the fleet has, before any other work; undefined leaves the fleet's purpose as it is. It cannot be given with a `FleetArchive`, which carries its own `purpose.json` or none. */
+    readonly purpose?: string;
+    /** Markdown notes for that purpose, at most 65536 bytes in UTF-8: the text of the file `--purpose-file` names. It needs `purpose`. */
+    readonly purposeDetail?: string;
+    readonly signal?: AbortSignal;
+}
+/** The options of `wait`, as the options of `endia compose up --wait` choose them. */
+export interface FleetWaitOptions {
+    /** The services whose machines to wait for, with the services they depend on; every service when undefined or empty. */
+    readonly services?: readonly string[];
+    /** The longest wait in seconds, as `--wait-timeout`; no limit when undefined. */
+    readonly timeout?: number;
+    readonly signal?: AbortSignal;
+}
+/** The fleet's archive as the caller packed it, holding `compose.json` and every build context and bind mount source it needs. */
+export interface FleetArchive {
+    /** The fleet's name, which is the Compose project name. */
+    readonly name: string;
+    /** The archive: its bytes, or a function that opens it afresh, so that a retried request sends the same bytes. */
+    readonly archive: Uint8Array | (() => Readable);
+}
+/** The options of `compose stop` and `compose restart`. */
+export interface FleetServicesOptions {
+    /** The services whose machines to act on; every service when undefined or empty. */
+    readonly services?: readonly string[];
+    /** The time in seconds Windows has to shut down before the virtual machine is turned off. */
+    readonly timeout?: number;
+    readonly signal?: AbortSignal;
+}
+/**
+ * The fleet routes, which bring a Compose project up and down as `docker compose` does, and read, set and clear a fleet's purpose. The client does not read Compose files: `up`
+ * takes the resolved model, as `endia compose config --format json` prints it, and packs it with the build contexts and bind mount
+ * sources it names into the archive the service expects. The service changes a fleet in the background, so every method that changes
+ * one returns a handle that follows that work and gives its result.
+ */
+export declare class FleetsClient {
+    private readonly connection;
+    private readonly operations;
+    /**
+     * Brings a fleet to the state its resolved model describes: `endia compose up -d`. The fleet's name is the model's `name`.
+     *
+     * The operation succeeds once every machine it created, recreated or started is ready: its virtual machine runs and it was
+     * configured in this boot, and when its image signs a user in by itself, that user is signed in with the desktop helper ready.
+     * A machine whose user is not signed in within `desktopReadyTimeoutSeconds` fails the operation with `TIMEOUT`. A machine that
+     * was already running and is kept unchanged is not checked again. Health checks are not waited for; `wait` waits for them, and
+     * for kept machines, as `endia compose up --wait` does.
+     *
+     * @param model - The resolved model, as an object or as the JSON text `endia compose config --format json` prints; or an archive
+     * the caller packed.
+     * @param options - Which services, when to build and recreate, and the fleet's purpose.
+     * @returns The operation; its result says what was done to each machine, network and volume.
+     * @throws Error when `purposeDetail` is given without `purpose`, when `purpose` has a line break or `purposeDetail` is too long, or
+     * when a purpose is given with a `FleetArchive`. Nothing is sent then.
+     */
+    up(model: ComposeModel | string | FleetArchive, options?: FleetUpOptions): Promise<OperationHandle<FleetUpResult>>;
+    /**
+     * Works out what `up` would do and changes nothing: `endia compose up --dry-run`.
+     *
+     * @param model - As for `up`.
+     * @param options - As for `up`. A purpose is checked and sent as `up` sends it.
+     * @returns The planned actions in order, and whether the host has the memory they need.
+     */
+    dryRun(model: ComposeModel | string | FleetArchive, options?: FleetUpOptions): Promise<FleetDryRun>;
+    /**
+     * Removes a fleet's machines and networks: `endia compose down`.
+     *
+     * @param name - The fleet's name.
+     * @param options - `volumes` deletes the named volumes too; `removeOrphans` removes machines of services no longer in the model;
+     * `timeout` as for `stop`.
+     * @returns The operation; its result names what was removed.
+     */
+    down(name: string, options?: {
+        readonly volumes?: boolean;
+        readonly removeOrphans?: boolean;
+        readonly timeout?: number;
+        readonly signal?: AbortSignal;
+    }): Promise<OperationHandle<FleetDownResult>>;
+    /**
+     * Shuts a fleet's machines down: `endia compose stop`.
+     *
+     * @param name - The fleet's name.
+     * @param options - The services, and the shutdown time.
+     * @returns The operation; its result names the machines stopped.
+     */
+    stop(name: string, options?: FleetServicesOptions): Promise<OperationHandle<FleetMachinesResult>>;
+    /**
+     * Starts a fleet's stopped machines: `endia compose start`.
+     *
+     * @param name - The fleet's name.
+     * @param options - The services.
+     * @returns The operation; its result names the machines started.
+     */
+    start(name: string, options?: {
+        readonly services?: readonly string[];
+        readonly signal?: AbortSignal;
+    }): Promise<OperationHandle<FleetMachinesResult>>;
+    /**
+     * Restarts a fleet's machines: `endia compose restart`.
+     *
+     * @param name - The fleet's name.
+     * @param options - The services, and the shutdown time.
+     * @returns The operation; its result names the machines restarted.
+     */
+    restart(name: string, options?: FleetServicesOptions): Promise<OperationHandle<FleetMachinesResult>>;
+    /**
+     * Lists fleets: `endia compose ls`.
+     *
+     * @param options - `all` includes fleets with no running machine.
+     * @returns The fleets.
+     */
+    list(options?: {
+        readonly all?: boolean;
+        readonly signal?: AbortSignal;
+    }): Promise<FleetSummary[]>;
+    /**
+     * Reads one fleet with its machines: `endia compose ps`.
+     *
+     * @param name - The fleet's name.
+     * @param signal - Cancels the request.
+     * @returns The fleet.
+     */
+    inspect(name: string, signal?: AbortSignal): Promise<FleetDetail>;
+    /**
+     * Reads a fleet's purpose with every change to it while the fleet has existed: `endia purpose show`.
+     *
+     * @param name - The fleet's name.
+     * @param signal - Cancels the request.
+     * @returns The purpose, or null, and the history, oldest first.
+     */
+    purpose(name: string, signal?: AbortSignal): Promise<FleetPurpose>;
+    /**
+     * Replaces a fleet's whole purpose, which its machines without a purpose of their own have: `endia purpose set`.
+     *
+     * @param name - The fleet's name.
+     * @param title - What the fleet is being used for, in one line of 1 to 200 characters.
+     * @param options - `detail` is Markdown notes of at most 65536 bytes in UTF-8; without it the detail stored before is cleared.
+     * @returns The purpose now stored.
+     * @throws Error when the title has a line break or the detail is too long. Nothing is sent then.
+     */
+    setPurpose(name: string, title: string, options?: {
+        readonly detail?: string;
+        readonly signal?: AbortSignal;
+    }): Promise<FleetPurposeResult>;
+    /**
+     * Removes a fleet's purpose: `endia purpose clear`. Clearing a fleet without a purpose changes nothing.
+     *
+     * @param name - The fleet's name.
+     * @param signal - Cancels the request.
+     * @returns The purpose now stored, which is null.
+     */
+    clearPurpose(name: string, signal?: AbortSignal): Promise<FleetPurposeResult>;
+    /**
+     * Waits until a fleet's machines are running and ready, and healthy when they have a health check, as `endia compose up --wait`
+     * waits once its operation has succeeded. `up`'s result already comes only once every machine it created, recreated or started
+     * was made ready; this wait adds what `--wait` adds: it checks every selected machine, kept ones too, waits for health checks to
+     * pass, and fails when a machine exits or becomes unhealthy.
+     *
+     * @param name - The fleet's name.
+     * @param options - Which services, as `up` takes them, and the longest wait.
+     * @returns The machines waited for, as last read.
+     * @throws MachineFailedError when a machine exited or became unhealthy.
+     * @throws DOMException named `TimeoutError` when some machine was not yet running, ready and healthy when the time-out passed. The
+     * machines carry on.
+     * @throws Error when a named service is not in the fleet's model.
+     */
+    wait(name: string, options?: FleetWaitOptions): Promise<MachineSummary[]>;
+    /**
+     * Reads the main-process output of a fleet's machines, each line naming its machine: `endia compose logs`.
+     *
+     * @param name - The fleet's name.
+     * @param options - Which lines; `services` limits them to some services, and `index` to one machine of each.
+     * @returns The lines, as they arrive.
+     */
+    logs(name: string, options?: LogOptions & {
+        readonly services?: readonly string[];
+        readonly index?: number;
+    }): AsyncGenerator<MachineLogLine, void, undefined>;
+    private sendFleet;
+    private sendArchive;
+    private sendAction;
+}

package/dist/groups/fleets.js

@@ -0,0 +1,255 @@
+import { setTimeout as delay } from "node:timers/promises";
+import { packFleet, selectServices } from "../archives/fleet-archive.js";
+import { MachineFailedError } from "../errors.js";
+import { purposeBody } from "../purposes.js";
+import { Routes } from "../routes.js";
+import { jsonBody, tarBody } from "../transport/api-connection.js";
+import { QueryText } from "../transport/query-text.js";
+import { addLogOptions } from "./machines.js";
+/** How often `wait` reads the fleet, as `endia compose up --wait` does. */
+const WaitPollMilliseconds = 1000;
+/**
+ * The fleet routes, which bring a Compose project up and down as `docker compose` does, and read, set and clear a fleet's purpose. The client does not read Compose files: `up`
+ * takes the resolved model, as `endia compose config --format json` prints it, and packs it with the build contexts and bind mount
+ * sources it names into the archive the service expects. The service changes a fleet in the background, so every method that changes
+ * one returns a handle that follows that work and gives its result.
+ */
+export class FleetsClient {
+    connection;
+    operations;
+    /** @internal */
+    constructor(connection, operations) {
+        this.connection = connection;
+        this.operations = operations;
+    }
+    /**
+     * Brings a fleet to the state its resolved model describes: `endia compose up -d`. The fleet's name is the model's `name`.
+     *
+     * The operation succeeds once every machine it created, recreated or started is ready: its virtual machine runs and it was
+     * configured in this boot, and when its image signs a user in by itself, that user is signed in with the desktop helper ready.
+     * A machine whose user is not signed in within `desktopReadyTimeoutSeconds` fails the operation with `TIMEOUT`. A machine that
+     * was already running and is kept unchanged is not checked again. Health checks are not waited for; `wait` waits for them, and
+     * for kept machines, as `endia compose up --wait` does.
+     *
+     * @param model - The resolved model, as an object or as the JSON text `endia compose config --format json` prints; or an archive
+     * the caller packed.
+     * @param options - Which services, when to build and recreate, and the fleet's purpose.
+     * @returns The operation; its result says what was done to each machine, network and volume.
+     * @throws Error when `purposeDetail` is given without `purpose`, when `purpose` has a line break or `purposeDetail` is too long, or
+     * when a purpose is given with a `FleetArchive`. Nothing is sent then.
+     */
+    async up(model, options = {}) {
+        const accepted = await this.sendFleet(model, options, false);
+        return this.operations.handle(accepted);
+    }
+    /**
+     * Works out what `up` would do and changes nothing: `endia compose up --dry-run`.
+     *
+     * @param model - As for `up`.
+     * @param options - As for `up`. A purpose is checked and sent as `up` sends it.
+     * @returns The planned actions in order, and whether the host has the memory they need.
+     */
+    dryRun(model, options = {}) {
+        return this.sendFleet(model, options, true);
+    }
+    /**
+     * Removes a fleet's machines and networks: `endia compose down`.
+     *
+     * @param name - The fleet's name.
+     * @param options - `volumes` deletes the named volumes too; `removeOrphans` removes machines of services no longer in the model;
+     * `timeout` as for `stop`.
+     * @returns The operation; its result names what was removed.
+     */
+    async down(name, options = {}) {
+        const query = new QueryText().addFlag("volumes", options.volumes).addFlag("removeOrphans", options.removeOrphans).add("timeout", options.timeout);
+        const accepted = await this.connection.change({ method: "DELETE", path: Routes.fleet(name) + query.toString(), signal: options.signal });
+        return this.operations.handle(accepted);
+    }
+    /**
+     * Shuts a fleet's machines down: `endia compose stop`.
+     *
+     * @param name - The fleet's name.
+     * @param options - The services, and the shutdown time.
+     * @returns The operation; its result names the machines stopped.
+     */
+    stop(name, options = {}) {
+        return this.sendAction(Routes.fleetStop(name), options.services, options.timeout, options.signal);
+    }
+    /**
+     * Starts a fleet's stopped machines: `endia compose start`.
+     *
+     * @param name - The fleet's name.
+     * @param options - The services.
+     * @returns The operation; its result names the machines started.
+     */
+    start(name, options = {}) {
+        return this.sendAction(Routes.fleetStart(name), options.services, undefined, options.signal);
+    }
+    /**
+     * Restarts a fleet's machines: `endia compose restart`.
+     *
+     * @param name - The fleet's name.
+     * @param options - The services, and the shutdown time.
+     * @returns The operation; its result names the machines restarted.
+     */
+    restart(name, options = {}) {
+        return this.sendAction(Routes.fleetRestart(name), options.services, options.timeout, options.signal);
+    }
+    /**
+     * Lists fleets: `endia compose ls`.
+     *
+     * @param options - `all` includes fleets with no running machine.
+     * @returns The fleets.
+     */
+    list(options = {}) {
+        return this.connection.read(Routes.fleets + new QueryText().addFlag("all", options.all).toString(), options.signal);
+    }
+    /**
+     * Reads one fleet with its machines: `endia compose ps`.
+     *
+     * @param name - The fleet's name.
+     * @param signal - Cancels the request.
+     * @returns The fleet.
+     */
+    inspect(name, signal) {
+        return this.connection.read(Routes.fleet(name), signal);
+    }
+    /**
+     * Reads a fleet's purpose with every change to it while the fleet has existed: `endia purpose show`.
+     *
+     * @param name - The fleet's name.
+     * @param signal - Cancels the request.
+     * @returns The purpose, or null, and the history, oldest first.
+     */
+    purpose(name, signal) {
+        return this.connection.read(Routes.fleetPurpose(name), signal);
+    }
+    /**
+     * Replaces a fleet's whole purpose, which its machines without a purpose of their own have: `endia purpose set`.
+     *
+     * @param name - The fleet's name.
+     * @param title - What the fleet is being used for, in one line of 1 to 200 characters.
+     * @param options - `detail` is Markdown notes of at most 65536 bytes in UTF-8; without it the detail stored before is cleared.
+     * @returns The purpose now stored.
+     * @throws Error when the title has a line break or the detail is too long. Nothing is sent then.
+     */
+    async setPurpose(name, title, options = {}) {
+        const body = purposeBody(title, options.detail);
+        return await this.connection.change({ method: "PUT", path: Routes.fleetPurpose(name), body: jsonBody(body), signal: options.signal });
+    }
+    /**
+     * Removes a fleet's purpose: `endia purpose clear`. Clearing a fleet without a purpose changes nothing.
+     *
+     * @param name - The fleet's name.
+     * @param signal - Cancels the request.
+     * @returns The purpose now stored, which is null.
+     */
+    clearPurpose(name, signal) {
+        return this.connection.change({ method: "DELETE", path: Routes.fleetPurpose(name), signal });
+    }
+    /**
+     * Waits until a fleet's machines are running and ready, and healthy when they have a health check, as `endia compose up --wait`
+     * waits once its operation has succeeded. `up`'s result already comes only once every machine it created, recreated or started
+     * was made ready; this wait adds what `--wait` adds: it checks every selected machine, kept ones too, waits for health checks to
+     * pass, and fails when a machine exits or becomes unhealthy.
+     *
+     * @param name - The fleet's name.
+     * @param options - Which services, as `up` takes them, and the longest wait.
+     * @returns The machines waited for, as last read.
+     * @throws MachineFailedError when a machine exited or became unhealthy.
+     * @throws DOMException named `TimeoutError` when some machine was not yet running, ready and healthy when the time-out passed. The
+     * machines carry on.
+     * @throws Error when a named service is not in the fleet's model.
+     */
+    async wait(name, options = {}) {
+        const deadline = options.timeout === undefined ? undefined : Date.now() + options.timeout * 1000;
+        let selected;
+        for (;;) {
+            const fleet = await this.inspect(name, options.signal);
+            selected ??= selectServices(fleet.model, options.services ?? []);
+            const machines = fleet.machines.filter((machine) => selected?.has(machine.service) === true);
+            const failed = machines.find(hasFailed);
+            if (failed !== undefined) {
+                throw new MachineFailedError(failed);
+            }
+            if (machines.every(isUp)) {
+                return machines;
+            }
+            if (deadline !== undefined && Date.now() >= deadline) {
+                throw new DOMException(`timed out after ${String(options.timeout)} seconds waiting for the machines to be running and healthy`, "TimeoutError");
+            }
+            await delay(WaitPollMilliseconds, undefined, { signal: options.signal });
+        }
+    }
+    /**
+     * Reads the main-process output of a fleet's machines, each line naming its machine: `endia compose logs`.
+     *
+     * @param name - The fleet's name.
+     * @param options - Which lines; `services` limits them to some services, and `index` to one machine of each.
+     * @returns The lines, as they arrive.
+     */
+    logs(name, options = {}) {
+        const query = addLogOptions(new QueryText(), options).addEach("services", options.services).add("index", options.index);
+        return this.connection.readLines(Routes.fleetLogs(name) + query.toString(), options.signal);
+    }
+    // Sends the archive with PUT /v1/fleets/{name}. A model is packed into a temporary archive, which is deleted once the service
+    // has answered.
+    async sendFleet(model, options, dryRun) {
+        const purpose = purposeOf(options);
+        if (isFleetArchive(model)) {
+            if (purpose !== undefined) {
+                throw new Error("A purpose cannot be given with a packed archive; put purpose.json in the archive.");
+            }
+            const archive = model.archive;
+            const body = tarBody(archive);
+            return this.sendArchive(model.name, body, options, dryRun);
+        }
+        const resolved = typeof model === "string" ? JSON.parse(model) : model;
+        const packed = await packFleet(resolved, typeof model === "string" ? model : JSON.stringify(model), options.services ?? [], purpose);
+        try {
+            return await this.sendArchive(resolved.name, packed.body, options, dryRun);
+        }
+        finally {
+            await packed.delete();
+        }
+    }
+    sendArchive(name, body, options, dryRun) {
+        const query = new QueryText()
+            .addEach("services", options.services)
+            .addEach("scale", options.scale)
+            .add("build", options.build)
+            .add("recreate", options.recreate)
+            .addFlag("removeOrphans", options.removeOrphans)
+            .add("timeout", options.timeout)
+            .addFlag("dryRun", dryRun)
+            .addEach("configFiles", options.configFiles)
+            .add("projectDirectory", options.projectDirectory);
+        return this.connection.change({ method: "PUT", path: Routes.fleet(name) + query.toString(), body, signal: options.signal }, false);
+    }
+    async sendAction(path, services, timeout, signal) {
+        const query = new QueryText().addEach("services", services).add("timeout", timeout);
+        const accepted = await this.connection.change({ method: "POST", path: path + query.toString(), signal });
+        return this.operations.handle(accepted);
+    }
+}
+// Detail without a title is refused as the CLI refuses --purpose-file without --purpose.
+function purposeOf(options) {
+    if (options.purpose === undefined) {
+        if (options.purposeDetail !== undefined) {
+            throw new Error("purposeDetail needs purpose.");
+        }
+        return undefined;
+    }
+    return purposeBody(options.purpose, options.purposeDetail);
+}
+function isFleetArchive(model) {
+    return typeof model === "object" && "archive" in model && (model.archive instanceof Uint8Array || typeof model.archive === "function");
+}
+/** Whether a machine ends a wait in failure: it exited, or its health check made it unhealthy. */
+function hasFailed(machine) {
+    return machine.health === "unhealthy" || machine.state === "exited";
+}
+/** Whether a machine is what a wait waits for: running and ready, and healthy when it has a health check. */
+function isUp(machine) {
+    return machine.state === "running" && machine.ready && (machine.health === "none" || machine.health === "healthy");
+}